@agent-native/core 0.7.13 → 0.7.15

package/docs/content/getting-started.md

@@ -5,37 +5,51 @@ description: "Pick a template, create your app, and start customizing it with AI
 
 # Getting Started
 
-The fastest way to get started is to pick a template and make it yours. Agent-native templates are **[cloneable SaaS](/docs/cloneable-saas)** — complete, production-grade apps, not starter kits. You get a working product in under a minute and start customizing it with the agent.
+By the end of this page, you'll have a working app — Mail, Calendar, Forms, or any other template — running with an AI agent built into the sidebar that can drive every part of it.
 
-## Create Your Workspace {#create-your-app}
+## Who is this for? {#who-is-this-for}
 
-```bash
-npx @agent-native/core create my-platform
-```
+There are two ways to use agent-native, depending on how hands-on you want to be:
+
+- **You want to use a hosted version.** Try a template right now at [agent-native.com/templates](/templates). Each template is a live, hosted app — you sign in, start using it, and the agent is already there. No install, no setup. You can stop reading this page and head straight to the [template gallery](/templates).
+- **You want to run locally or customize it.** You'll clone a template, run it on your machine, and shape it however you want — branding, features, integrations. The rest of this page is for you. You'll need [Node.js](https://nodejs.org) and [pnpm](https://pnpm.io) installed.
 
-The CLI shows a multi-select picker — pick as many templates as you want (Mail + Calendar + Forms, for example) and they all get scaffolded into the same workspace sharing auth, brand, and agent config. Then boot them all:
+Not sure which path? If you've never written code, the hosted version is for you. If you have a developer or AI coding tool ready, the local path gives you total control.
+
+## First run {#create-your-app}
+
+Three commands and you're up:
 
 ```bash
+npx @agent-native/core create my-platform
 cd my-platform
-pnpm install
-pnpm dev
+pnpm install && pnpm dev
 ```
 
-That's it — you have every app running locally with an AI agent built in. Open the agent panel, ask it to do something, and watch it work.
+The `create` command shows a multi-select picker — pick one template or several (Mail + Calendar + Forms, for example) and they all scaffold into one workspace sharing auth, brand, and agent config.
 
-Want a single app with no monorepo? Pass `--standalone`:
+Open the URL the dev server prints (usually `http://localhost:3000`).
 
-```bash
-npx @agent-native/core create my-app --standalone --template mail
-```
+## What just happened? {#what-just-happened}
 
-Need to add more apps later? From inside the workspace:
+You now have a real, full-featured app running on your machine. Open it in the browser and try it:
 
-```bash
-agent-native add-app
-```
+- Click around the UI like you would any SaaS product.
+- Open the agent panel on the right side. Type something like "show me my settings" or "create a new entry called Welcome." Watch the agent click through the app on your behalf.
+- Anything you do by clicking, the agent can do by reading and writing the same database. Anything the agent does shows up in the UI immediately.
+
+That parity between agent and UI is the whole point — see [What Is Agent-Native?](/docs/what-is-agent-native) for the bigger picture.
+
+## What's next {#whats-next}
+
+From here, use any AI coding tool (Claude Code, Cursor, Windsurf, Builder.io) to customize the app. The agent instructions in `AGENTS.md` are already set up so any tool understands the codebase.
 
-From here, use your AI coding tool (Claude Code, Cursor, Windsurf, etc.) to customize it. The agent instructions in `AGENTS.md` are already set up so any tool understands the codebase. See [Multi-App Workspace](/docs/multi-app-workspace) for the full story on sharing auth, skills, components, and credentials across apps.
+Common next steps:
+
+- **Add another app to the same workspace** — run `agent-native add-app` from inside the workspace folder. See [Multi-App Workspace](/docs/multi-app-workspace) for sharing auth, components, and credentials across apps.
+- **Single app instead of a monorepo?** Pass `--standalone` when creating: `npx @agent-native/core create my-app --standalone --template mail`.
+- **Build a brand-new template from scratch** — see [Creating Templates](/docs/creating-templates) for the full Vite, Tailwind, and TypeScript setup.
+- **Understand the architecture** — see [Key Concepts](/docs/key-concepts) for how SQL, actions, polling sync, and context awareness fit together.
 
 ## Templates {#templates}
 
@@ -55,7 +69,7 @@ Each template is a complete app with UI, agent actions, database schema, and AI
 
 Browse the [template gallery](/templates) for live demos, or see [Cloneable SaaS](/docs/cloneable-saas) for the full list and the clone → customize → deploy flow.
 
-## Project Structure {#project-structure}
+## Project structure {#project-structure}
 
 Every agent-native app — whether from a template or from scratch — follows the same structure:
 
@@ -67,53 +81,15 @@ my-app/
   .agents/         # Agent instructions and skills
 ```
 
-Templates add domain-specific code on top of this: database schemas in `server/db/`, API routes in `server/routes/api/`, and actions in `actions/`.
-
-## Configuration {#configuration}
-
-Templates come pre-configured. If you're starting from scratch, here are the config files:
-
-```ts
-// vite.config.ts
-import { defineConfig } from "@agent-native/core/vite";
-export default defineConfig();
-```
-
-```json
-// tsconfig.json
-{ "extends": "@agent-native/core/tsconfig.base.json" }
-```
-
-```css
-/* app/global.css — Tailwind v4 (CSS-first, no tailwind.config.ts needed) */
-@import "tailwindcss";
-@import "@agent-native/core/styles/agent-native.css";
-
-@source "./**/*.{ts,tsx}";
-
-:root {
-  --background: 0 0% 100%;
-  --foreground: 220 10% 10%;
-  /* ...rest of your shadcn-style tokens */
-}
-
-.dark {
-  --background: 220 6% 6%;
-  --foreground: 0 0% 90%;
-  /* ... */
-}
-```
-
-The framework auto-injects `@tailwindcss/vite` from `defineConfig()`.
-No `tailwind.config.ts`, `postcss.config.js`, or vite changes needed.
+Templates add domain-specific code on top: database schemas in `server/db/`, API routes in `server/routes/api/`, and actions in `actions/`. Building from scratch? See [Creating Templates](/docs/creating-templates) for `vite.config.ts`, `tsconfig.json`, and Tailwind setup.
 
-## Architecture Principles {#architecture-principles}
+## Architecture principles {#architecture-principles}
 
-These principles apply to all agent-native apps. Understanding them helps you customize templates or build from scratch:
+These principles apply to all agent-native apps. Skim them now, revisit them when you're customizing.
 
 1. **Agent + UI are equal partners** — Everything the UI can do, the agent can do, and vice versa. They share the same database and always stay in sync. You don't think about "the agent" and "the app" separately — you think about them together.
 2. **Context-aware** — The agent always knows what you're looking at. If an email is open, it knows which one. If you select text and hit Cmd+I, it can act on just that selection.
-3. **Skills-driven** — Core functionalities have instructions so the agent doesn't explore from scratch every time. When you add a feature, you update all four areas: UI, actions, skills/instructions, and application state.
+3. **Skills-driven** — Core functionality has written instructions so the agent doesn't explore from scratch every time. New features update all four areas: UI, actions, skills/instructions, and application state.
 4. **Inter-agent communication** — Agents can discover and call each other via the A2A protocol. Tag your analytics agent from the mail app to pull data into a draft.
 5. **Fully portable** — Any SQL database Drizzle supports, any hosting backend Nitro supports, any AI coding tool. These are non-negotiable.
 6. **Fork and customize** — Apps you clone and evolve. The agent can modify the app's own code — components, routes, styles, actions — so it gets better over time.

package/docs/content/mcp-clients.md

@@ -77,7 +77,20 @@ This means users who've installed the claude-in-chrome extension get browser con
 
 ## Remote MCP servers via the settings UI {#remote-via-ui}
 
-Users don't have to edit `mcp.config.json` to add a remote, HTTP-based MCP server (Zapier, Cloudflare, Composio, an internal tool, etc). Open the settings panel → **MCP Servers** and paste the server's URL. Two scopes are supported:
+MCP (Model Context Protocol) servers give your agent new abilities — like connecting to Zapier, Cloudflare, Composio, or your company's internal tools. Once connected, the agent can use those tools just like its built-in ones.
+
+### How to connect a remote MCP server
+
+1. **Server name** — a short label for your own reference (e.g. "zapier", "slack-tools").
+2. **URL** — the HTTPS endpoint the MCP server provider gave you (e.g. `https://mcp.zapier.com/s/abc123/mcp`). This is usually found in the provider's dashboard or integration docs.
+3. **Description** (optional) — a note about what this server does.
+4. **Headers** — authentication credentials the server requires, one per line. Most servers need an `Authorization` header. Example: `Authorization: Bearer sk-your-key-here`. The provider's docs will tell you what to put here.
+
+Click **Test** to verify the connection before saving. If it succeeds, you'll see the number of tools available. Click **Connect** to add it.
+
+### Personal vs Organization scope
+
+Two scopes are supported:
 
 - **Personal** — only the signed-in user gets the tools. Stored as a user-scope setting.
 - **Team** — everyone in the active organization gets the tools. Owners and admins can add; members see the list read-only. Stored as an org-scope setting.

package/docs/content/messaging.md

@@ -0,0 +1,324 @@
+---
+title: "Messaging"
+description: "Talk to your agent from Slack, email, Telegram, or WhatsApp — same agent, same memory, same tools."
+---
+
+# 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.
+
+> **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).
+
+## 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 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.
+
+## Set up Slack {#slack}
+
+### What you'll need
+
+- A Slack workspace where you can install apps (admin access)
+- About 5 minutes
+
+### Steps
+
+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:
+
+   ```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.
+
+7. Send your bot a DM in Slack. It should reply.
+
+### 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.
+
+## Set up Telegram {#telegram}
+
+### What you'll need
+
+- The Telegram app on your phone
+- About 3 minutes
+
+### Steps
+
+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:
+
+   ```text
+   POST https://your-app.example.com/_agent-native/integrations/telegram/setup
+   ```
+
+   This tells Telegram to send messages to your app's webhook. You only need to do this once per deployment.
+
+5. Find your bot in Telegram (search for the username BotFather gave you) and send it a message.
+
+## 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.
+
+### What you'll need
+
+- 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
+
+### Steps (with Resend — easiest)
+
+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:
+
+   ```text
+   https://your-app.example.com/_agent-native/integrations/email/webhook
+   ```
+
+   Subscribe to the **`email.received`** event. Resend will give you a signing secret — copy it.
+
+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)
+
+5. Send an email to the agent's address. It'll reply in the same thread.
+
+### Steps (with SendGrid)
+
+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:
+
+   ```text
+   https://your-app.example.com/_agent-native/integrations/email/webhook
+   ```
+
+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
+
+5. Send an email to the agent's address.
+
+### Tips
+
+- **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.
+
+## Set up WhatsApp {#whatsapp}
+
+### What you'll need
+
+- A Meta (Facebook) developer account
+- A phone number you can dedicate to the bot
+- About 15 minutes (Meta's setup has the most steps)
+
+### Steps
+
+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:
+
+   ```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
+   ```
+
+   Subscribe to the `messages` field.
+
+7. Send a WhatsApp message to the bot's phone number.
+
+## 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 the **[Dispatch template](/docs/template-dispatch)** and let it route work to your domain apps over [A2A](/docs/a2a-protocol).
+
+Why this is nice:
+
+- **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.
+
+If you don't need an orchestrator, any single template can wire up messaging directly using the env vars on this page.
+
+---
+
+## For developers {#for-developers}
+
+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.
+
+### How it works {#how-it-works}
+
+Each platform talks to your app via a standard HTTP webhook:
+
+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.
+
+```text
+User → Platform webhook → Verify → Parse → Agent runs → Response posted back
+```
+
+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.
+
+### The integrations plugin {#plugin}
+
+The plugin auto-mounts when no custom version exists. To customize, create:
+
+```ts
+// server/plugins/integrations.ts
+import { createIntegrationsPlugin } from "@agent-native/core/server";
+import { scriptRegistry } from "../../agent.config";
+
+export default createIntegrationsPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+});
+```
+
+Which platforms are active depends on which env vars are set. The plugin registers webhook routes for each one under `/_agent-native/integrations/`.
+
+### Webhook URLs {#webhook-urls}
+
+```text
+/_agent-native/integrations/slack/webhook
+/_agent-native/integrations/telegram/webhook
+/_agent-native/integrations/whatsapp/webhook
+/_agent-native/integrations/email/webhook
+```
+
+Telegram also exposes a one-time setup endpoint:
+
+```text
+POST /_agent-native/integrations/telegram/setup
+```
+
+### Environment variables {#env-vars}
+
+| 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` | —                              |
+
+All credentials live in env vars — never the database, never source code. Use the sidebar settings UI or your hosting provider's env panel.
+
+### Threading and identity {#threading-and-identity}
+
+Each external conversation maps to a persistent thread in the agent-native database:
+
+- **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.
+
+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.
+
+### Security {#security}
+
+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.
+- **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.
+
+The email adapter also enforces:
+
+- **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.
+
+### 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 template at `actions/send-platform-message.ts` and you can copy/adapt it for any template.
+
+### Custom adapters {#custom-adapters}
+
+To add a new messaging platform, implement the `PlatformAdapter` interface:
+
+```ts
+import type { PlatformAdapter } from "@agent-native/core/server";
+
+const myAdapter: PlatformAdapter = {
+  platform: "discord",
+
+  // Verify the incoming webhook is authentic
+  verifyRequest(request: Request): Promise<boolean> {
+    // Validate signature headers
+  },
+
+  // Extract the message text and thread context
+  parseMessage(body: unknown): Promise<{
+    text: string;
+    threadId: string;
+    senderId: string;
+    metadata?: Record<string, unknown>;
+  }> {
+    // Parse platform-specific payload
+  },
+
+  // Post the agent's response back
+  sendResponse(threadId: string, text: string): Promise<void> {
+    // Call the platform's API
+  },
+};
+```
+
+Register it in your integrations plugin:
+
+```ts
+export default createIntegrationsPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+  adapters: [myAdapter],
+});
+```
+
+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.
+
+### See also {#see-also}
+
+- [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

package/docs/content/onboarding.md

@@ -1,16 +1,80 @@
 # Onboarding
 
-The framework-level onboarding system gives every template a shared setup
-experience in the agent chat sidebar. Users see a checklist of setup steps,
-each with one or more ways to complete it — paste an API key, connect
-Builder, or ask the agent to do it for them.
+When you first open an app built on the agent-native framework, you'll see a
+**Setup** checklist in the agent sidebar. Each item is something the app needs
+from you — connect an AI engine, paste an API key, configure email delivery —
+before the agent can do its full job.
+
+## For end users
+
+### What you'll see
+
+- A **Setup** panel above the agent chat with a checklist like "Connect an AI
+  engine", "Email delivery", etc.
+- A counter at the top (e.g. "1 of 4") shows how many steps are done.
+- The current step is expanded; finished steps collapse with a green check;
+  remaining steps sit dimmed below.
+- Required steps show a small red **required** pill. The panel stays visible
+  until every required step is complete.
+- Once everything required is done, the panel hides itself automatically.
+- The whole panel can be collapsed with the chevron in the top-right, or
+  hidden entirely with **Hide setup** at the bottom.
+
+### How to complete each step
+
+Steps offer one or more **methods** — different ways to satisfy the same
+requirement. The recommended option is highlighted in blue; alternatives sit
+below it.
+
+- **Connect a service (one click)** — e.g. _Connect Builder_ for the managed
+  AI gateway. Click the button, a window opens, you sign in, the window closes,
+  and the step is marked complete. No keys to copy.
+- **Paste an API key or fill a form** — e.g. _Use your Anthropic API key_,
+  _Use Resend_ for email. Click the method, paste the value(s), click **Save**.
+  Secret fields use a password input so the value isn't shown on screen. Saved
+  values go into your local `.env` (or workspace settings) — see
+  [Secrets](/docs/secrets) for where they live.
+- **Open a link** — some steps point to a sign-in page or docs. Click
+  **Continue** and finish the flow in the new tab.
+- **Ask the agent** — a few steps offer a "Let the agent set it up" option.
+  Click it and the agent picks up in the chat, walking you through any
+  external setup (creating OAuth credentials, etc.).
+
+### The built-in steps you'll usually see
+
+- **Connect an AI engine** (required) — the only mandatory step. Either
+  connect Builder for a one-click managed gateway, or paste a key for
+  Anthropic, OpenAI, Google Gemini, or OpenRouter.
+- **Email delivery** (optional) — needed for password resets and team
+  invitations. Resend or SendGrid; without it, reset emails just log to the
+  server console.
+- **Database** and **Authentication** — only shown in local dev mode.
+  Production deployments configure these via environment variables.
+
+Templates can add their own steps on top of these — e.g. a CRM template might
+add "Connect Gmail", a docs template might add "Pick a default workspace". See
+[Authentication](/docs/authentication) for sign-in setup details.
+
+### Coming back to the checklist
+
+If you hit **Hide setup**, the panel disappears for that browser session.
+Required steps that aren't yet complete will surface again on next load. Once
+everything required is done, the panel auto-hides for good — there's nothing
+left to do.
+
+## For developers
+
+If you're building a template, you register onboarding steps so they appear in
+the user's sidebar checklist. The framework handles rendering, completion
+tracking, and dismissal — you just declare what the step is and how it's
+satisfied.
 
 The system is **auto-mounted**. Templates don't need to wire anything to get
-the three built-in steps (LLM, database, auth). To add app-specific steps
-(Gmail, Slack, Notion, etc.), call `registerOnboardingStep()` from a server
-plugin.
+the four built-in steps (LLM, database, auth, email). To add app-specific
+steps (Gmail, Slack, Notion, etc.), call `registerOnboardingStep()` from a
+server plugin.
 
-## Auto-mounted routes
+### Auto-mounted routes
 
 All routes live under `/_agent-native/onboarding/`:
 
@@ -22,7 +86,7 @@ All routes live under `/_agent-native/onboarding/`:
 | `POST /_agent-native/onboarding/reopen`             | Clear dismissal (re-show panel)   |
 | `GET /_agent-native/onboarding/dismissed`           | Read dismissal + allComplete flag |
 
-## Adding a step from a template
+### Adding a step from a template
 
 ```ts
 // server/plugins/my-onboarding.ts
@@ -61,7 +125,7 @@ export default defineNitroPlugin(() => {
 });
 ```
 
-## Method kinds
+### Method kinds
 
 | Kind               | Payload                   | Use for                                   |
 | ------------------ | ------------------------- | ----------------------------------------- |
@@ -72,18 +136,19 @@ export default defineNitroPlugin(() => {
 
 The `primary: true` flag marks a method as the big CTA for its step.
 
-## Built-in steps
+### Built-in steps
 
 | ID         | Required | Description                                   |
 | ---------- | -------- | --------------------------------------------- |
 | `llm`      | yes      | ANTHROPIC_API_KEY or Builder connection       |
 | `database` | no       | SQLite default or a DATABASE_URL for Postgres |
 | `auth`     | no       | Local dev mode, Google OAuth, or access token |
+| `email`    | no       | Resend or SendGrid for transactional email    |
 
 Any of these can be overridden by re-registering with the same `id` after the
 defaults load.
 
-## Client usage
+### Client usage
 
 The panel is already inside `<AgentPanel>`. To build a custom layout:
 
@@ -105,3 +170,8 @@ function MySidebar() {
   );
 }
 ```
+
+For background on where step values are stored and how secrets are handled,
+see [Secrets](/docs/secrets). For end-user messaging touchpoints (invitations,
+password resets) that depend on the **Email delivery** step, see
+[Messaging](/docs/messaging).