@agent-native/core 0.93.0 → 0.94.1

package/corpus/core/docs/content/mcp-clients.mdx

@@ -5,14 +5,15 @@ description: "Connect your agent-native app to local MCP servers (claude-in-chro
 
 # MCP Clients
 
-**This page: give your agent more tools.** Point an agent-native app at MCP servers — local or remote — so their tools show up in the agent chat. This is the _client_ direction, the mirror image of [MCP Protocol](/docs/mcp-protocol) (which makes your app an MCP _server_).
+**This page: give your agent more tools.** Point an agent-native app at MCP servers — local or remote — so their tools show up in the agent chat. This is the _client_ direction, the mirror image of [MCP Server](/docs/mcp-protocol) (which makes your app an MCP _server_). Note the dual use of "client" here: this page is about your app acting as an MCP client of _other_ servers — a different sense from an "MCP host" like Claude or Cursor connecting to your app (see [MCP Server](/docs/mcp-protocol) for that direction).
 
 | If you want to…                                              | Read                                     |
 | ------------------------------------------------------------ | ---------------------------------------- |
 | Connect an external agent/host to your app                   | [External Agents](/docs/external-agents) |
 | Give your agent more tools (consume other MCP servers)       | **This page** — MCP Clients              |
 | Build inline UIs that render in Claude/ChatGPT               | [MCP Apps](/docs/mcp-apps)               |
-| Lower-level MCP server reference (auth, tools, custom mount) | [MCP Protocol](/docs/mcp-protocol)       |
+| Build generated inline UI inside Agent-Native chat           | [Generative UI](/docs/generative-ui)     |
+| Lower-level MCP server reference (auth, tools, custom mount) | [MCP Server](/docs/mcp-protocol)         |
 
 With one config file, every agent-native app in your workspace gains access to tools provided by MCP servers on your machine: `claude-in-chrome` for browser automation, `@modelcontextprotocol/server-filesystem` for reading files, `@playwright/mcp` for browser testing, and anything else that speaks MCP.
 
@@ -96,7 +97,7 @@ Every source resolves into one runtime **MCP manager**, and every tool it learns
 
 </Diagram>
 
-> The opposite direction — making _your_ app an MCP server that other hosts consume — lives in [MCP Protocol](/docs/mcp-protocol) and [External Agents](/docs/external-agents).
+> The opposite direction — making _your_ app an MCP server that other hosts consume — lives in [MCP Server](/docs/mcp-protocol) and [External Agents](/docs/external-agents).
 
 ## Built-in browser and computer-use capabilities {#built-in-capabilities}
 
@@ -309,9 +310,43 @@ Stdio servers are still a no-op outside Node runtimes, but remote HTTP MCP serve
 
 ## Shared MCP servers via a hub {#hub}
 
-If your workspace runs multiple agent-native apps (e.g. dispatch + mail + clips), you can configure **one** app as the hub and have the others pull its org-scope MCP servers automatically. No per-app copy-paste of URLs and bearer tokens. See [Multi-App Workspace](/docs/multi-app-workspace) for the canonical approach using Dispatch workspace MCP resources.
+If your workspace runs multiple agent-native apps (e.g. dispatch + mail + clips), share MCP servers across all of them without per-app copy-pasting of URLs and bearer tokens. See [Multi-App Workspace](/docs/multi-app-workspace) for the full deployment picture.
 
-Dispatch is the conventional hub — it already coordinates across apps.
+### Recommended: Dispatch workspace MCP resources {#hub-recommended}
+
+For new workspace setups, prefer **Dispatch workspace MCP resources** — the
+same All-app vs selected-app grant model used by workspace skills,
+instructions, and reference resources. Add a workspace resource with:
+
+```json
+{
+  "type": "http",
+  "url": "https://example.com/mcp",
+  "headers": {
+    "Authorization": "Bearer ${keys.MCP_SERVER_TOKEN}"
+  },
+  "description": "Shared MCP tools for workspace apps"
+}
+```
+
+Save it under `mcp-servers/<name>.json` with kind `mcp-server`. All-app
+resources are loaded by every workspace app; selected resources load only in
+apps with an active Dispatch grant. Secret placeholders resolve from the app
+secret store, so put raw bearer tokens in Dispatch Vault and reference them
+with `${keys.NAME}` instead of storing them in the resource body.
+
+Apps refresh their merged MCP config about once a minute, so central resource
+edits, grant changes, and removals take effect without a deploy. Set
+`AGENT_NATIVE_MCP_CONFIG_REFRESH_MS=0` to disable that background refresh, or
+set it to a value of at least `5000` milliseconds to tune the interval.
+
+### Legacy: self-hosted hub mode {#hub-legacy}
+
+The mode below remains useful for coarse "share every org-scope MCP server
+from Dispatch" setups and for deployments that already use the MCP settings UI
+as the source of truth. You configure **one** app as the hub and the others
+pull its org-scope MCP servers automatically. Dispatch is the conventional hub
+— it already coordinates across apps.
 
 <Diagram id="doc-block-1dnioze" title="Hub model: one app serves org-scope MCP servers" summary={"Dispatch holds the org-scope MCP servers; consumer apps pull and merge them as mcp__hub_<orgId>_<name>__*. Only org-scope rows are shared — personal credentials stay put."}>
 
@@ -376,36 +411,6 @@ Dispatch is the conventional hub — it already coordinates across apps.
 
 </Diagram>
 
-For new workspace setups, prefer **Dispatch workspace MCP resources** when you
-want the same All-app vs selected-app grant model used by workspace skills,
-instructions, and reference resources. Add a workspace resource with:
-
-```json
-{
-  "type": "http",
-  "url": "https://example.com/mcp",
-  "headers": {
-    "Authorization": "Bearer ${keys.MCP_SERVER_TOKEN}"
-  },
-  "description": "Shared MCP tools for workspace apps"
-}
-```
-
-Save it under `mcp-servers/<name>.json` with kind `mcp-server`. All-app
-resources are loaded by every workspace app; selected resources load only in
-apps with an active Dispatch grant. Secret placeholders resolve from the app
-secret store, so put raw bearer tokens in Dispatch Vault and reference them
-with `${keys.NAME}` instead of storing them in the resource body.
-
-Apps refresh their merged MCP config about once a minute, so central resource
-edits, grant changes, and removals take effect without a deploy. Set
-`AGENT_NATIVE_MCP_CONFIG_REFRESH_MS=0` to disable that background refresh, or
-set it to a value of at least `5000` milliseconds to tune the interval.
-
-The older hub mode below remains useful for coarse “share every org-scope MCP
-server from Dispatch” setups and for deployments that already use the MCP
-settings UI as the source of truth.
-
 ### 1. Enable hub-serve on the hub app (dispatch)
 
 Set an env var in dispatch's deployment:
@@ -456,28 +461,10 @@ Every app exposes `GET /_agent-native/mcp/status` for tooling and onboarding:
   }
 ]}>
 
-Reports which configured servers connected, the total live tool count, the merged prefixed tool list, and any per-server connection errors. Use it to build "detected — your agent can now drive X" hints or to debug connection problems.
+Reports which configured servers connected, the total live tool count, the merged prefixed tool list, and any per-server connection errors. Use it to build "detected — your agent can now drive X" hints (e.g. "claude-in-chrome detected — your agent can now drive Chrome") or to debug connection problems.
 
 </Endpoint>
 
-```json
-{
-  "configuredServers": ["claude-in-chrome", "playwright"],
-  "connectedServers": ["claude-in-chrome", "playwright"],
-  "totalTools": 21,
-  "tools": [
-    {
-      "source": "claude-in-chrome",
-      "name": "mcp__claude-in-chrome__navigate",
-      "description": "Navigate the browser to a URL"
-    }
-  ],
-  "errors": {}
-}
-```
-
-Use this to build "claude-in-chrome detected — your agent can now drive Chrome" onboarding hints, or debug MCP connection problems.
-
 ## Failure modes {#failures}
 
 Individual MCP server failures never take down the agent:
@@ -491,3 +478,10 @@ Agent-native will always boot; broken MCP configuration just means fewer tools.
 ## Security {#security}
 
 MCP tools run on your machine with whatever permissions the spawned process has. Treat `mcp.config.json` like any other list of executables you're willing to let the agent drive. Tools from MCP servers appear in the agent's tool-use loop just like your template's own actions, so make sure you trust every server you configure.
+
+## What's next {#whats-next}
+
+- [**MCP Server**](/docs/mcp-protocol) — the opposite direction: making your app an MCP server other hosts consume
+- [**External Agents**](/docs/external-agents) — connecting Claude, Cursor, and other hosts to your app
+- [**Multi-App Workspace**](/docs/multi-app-workspace) — the shared-resource model behind Dispatch workspace MCP resources
+- [**Actions**](/docs/actions) — how your own actions show up alongside MCP tools in the agent's registry

package/corpus/core/docs/content/mcp-protocol.mdx

@@ -1,9 +1,9 @@
 ---
-title: "MCP Protocol"
+title: "MCP Server"
 description: "Expose your agent-native app as a remote MCP server so Claude, ChatGPT, Claude Code, Cursor, and other AI tools can call your app's actions directly."
 ---
 
-# MCP Protocol
+# MCP Server
 
 **This page: the lower-level MCP server reference.** How every agent-native app exposes its actions over MCP — the auto-mounted endpoint, auth modes, the `tools/call` / `ask-agent` surface, and custom mounting. Reach for it when you need server internals; for connecting a host, start with [External Agents](/docs/external-agents).
 
@@ -12,13 +12,14 @@ description: "Expose your agent-native app as a remote MCP server so Claude, Cha
 | Connect an external agent/host to your app                   | [External Agents](/docs/external-agents) |
 | Give your agent more tools (consume other MCP servers)       | [MCP Clients](/docs/mcp-clients)         |
 | Build inline UIs that render in Claude/ChatGPT               | [MCP Apps](/docs/mcp-apps)               |
-| Lower-level MCP server reference (auth, tools, custom mount) | **This page** — MCP Protocol             |
+| Build generated inline UI inside Agent-Native chat           | [Generative UI](/docs/generative-ui)     |
+| Lower-level MCP server reference (auth, tools, custom mount) | **This page** — MCP Server               |
 
 Every agent-native app automatically exposes a remote MCP (Model Context Protocol) server, so external AI tools like Claude, ChatGPT custom MCP apps, Claude Code, Cursor, Codex, and VS Code GitHub Copilot can discover and call your app's actions directly — no extra code needed. If your goal is to _connect_ one of those hosts to a hosted app, [External Agents](/docs/external-agents) covers the recommended single Dispatch connector, per-app URLs, OAuth, MCP Apps inline UIs, and deep links. This page documents what sits underneath that.
 
 ## Overview {#overview}
 
-MCP is the standard protocol for connecting AI tools to external capabilities. When you deploy an agent-native app, it auto-mounts an MCP endpoint alongside the existing A2A endpoint. Any MCP-compatible client can connect and use your app's tools.
+MCP is the standard protocol for connecting AI tools to external capabilities. When you deploy an agent-native app, it auto-mounts an MCP endpoint alongside the existing A2A endpoint. Any MCP-compatible host can connect and use your app's tools.
 
 Key concepts:
 
@@ -100,9 +101,9 @@ Both protocols are auto-mounted. Use whichever fits your use case:
 
 You can also use the `ask-agent` MCP tool to get the best of both worlds — call it from Claude Code and let your app's agent reason through complex tasks.
 
-## Manual MCP client config {#manual-config}
+## Manual MCP host config {#manual-config}
 
-For the recommended one-command setup, use [External Agents](/docs/external-agents). If you are hand-writing MCP config for an OAuth-capable client, add your app as a remote MCP server with no static headers:
+For the recommended one-command setup, use [External Agents](/docs/external-agents). If you are hand-writing MCP config for an OAuth-capable host, add your app as a remote MCP server with no static headers:
 
 ```bash
 claude mcp add --transport http mail https://mail.example.com/_agent-native/mcp
@@ -130,9 +131,9 @@ Then run `/mcp` in Claude Code and choose **Authenticate**. For clients that can
 Claude Code calls: draft-email(to: "john@example.com", subject: "Q3 Report", body: "...")
 ```
 
-## Connecting from other MCP clients {#other-clients}
+## Connecting from other MCP hosts {#other-clients}
 
-Any MCP client that supports Streamable HTTP transport can connect. The endpoint is:
+Any MCP host that supports Streamable HTTP transport can connect. The endpoint is:
 
 ```
 POST https://your-app.example.com/_agent-native/mcp
@@ -140,7 +141,7 @@ POST https://your-app.example.com/_agent-native/mcp
 
 The server supports the standard MCP handshake: `initialize` → `initialized` → `tools/list` → `tools/call`.
 
-<Endpoint id="doc-block-86ic5g" title="MCP endpoint" summary="The auto-mounted Streamable HTTP endpoint every agent-native app exposes." method="POST" path="/_agent-native/mcp" summary="MCP Streamable HTTP endpoint" auth="Standard remote MCP OAuth (Bearer access token), connect-minted JWT, or static ACCESS_TOKEN/ACCESS_TOKENS" params={[
+<Endpoint id="doc-block-86ic5g" title="MCP endpoint" summary="The auto-mounted Streamable HTTP endpoint every agent-native app exposes." method="POST" path="/_agent-native/mcp" auth="Standard remote MCP OAuth (Bearer access token), connect-minted JWT, or static ACCESS_TOKEN/ACCESS_TOKENS" params={[
   {
     "name": "Authorization",
     "in": "header",
@@ -173,7 +174,13 @@ Auto-mounted on every app. Speaks the standard MCP handshake (`initialize` → `
 
 </Endpoint>
 
-If an action declares `mcpApp`, the server also advertises the official MCP Apps extension (`io.modelcontextprotocol/ui`) and supports `resources/list`, `resources/templates/list`, and `resources/read` for the app resource. Hosts that render MCP Apps can show the UI inline; hosts that do not can still call the tool and use the deep-link fallback. Product UIs should use `embedApp()` so the inline surface is the real React app route, or a focused route that renders a shared React component such as an Analytics chart, not a separate plain HTML implementation. The server emits both standard MCP Apps metadata and ChatGPT Apps SDK compatibility metadata so app-capable hosts can find the same `ui://` resource. The current official extension matrix includes Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT, and Cursor; host support varies by version and plan, so use the [External Agents MCP Apps notes](/docs/external-agents#mcp-apps-compatibility) for the user-facing guidance.
+If an action declares `mcpApp`, the server advertises the official MCP Apps extension and supports the resource routes needed to render it inline:
+
+- Advertises `io.modelcontextprotocol/ui` and supports `resources/list`, `resources/templates/list`, and `resources/read` for the app resource.
+- Hosts that render MCP Apps show the UI inline; hosts that don't can still call the tool and use the deep-link fallback.
+- Product UIs should use `embedApp()` so the inline surface is the real React app route, or a focused route that renders a shared React component such as an Analytics chart — never a separate plain-HTML implementation.
+- The server emits both standard MCP Apps metadata and ChatGPT Apps SDK compatibility metadata so app-capable hosts find the same `ui://` resource.
+- The current official extension matrix includes Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT, and Cursor. Host support varies by version and plan — see the [External Agents MCP Apps notes](/docs/external-agents#mcp-apps-compatibility) for the user-facing guidance.
 
 ### MCP App embed bridge {#mcp-app-embed-bridge}
 
@@ -385,3 +392,11 @@ For more complex analysis:
 Claude Code calls: ask-agent(message: "Prepare a full breakdown of Q3 signups by source, with trends")
 → The analytics agent runs multiple queries, reasons about the data, and returns a formatted report
 ```
+
+## What's next {#whats-next}
+
+- [**External Agents**](/docs/external-agents) — the recommended connect flow, catalog tiers, and per-host setup
+- [**MCP Apps**](/docs/mcp-apps) — inline UI resources for hosts that render them
+- [**MCP Clients**](/docs/mcp-clients) — the other direction: your app consuming external MCP servers
+- [**A2A Protocol**](/docs/a2a-protocol) — the sibling protocol for agent-to-agent calls
+- [**Actions**](/docs/actions) — how an action becomes an MCP tool

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

@@ -7,7 +7,11 @@ description: "Talk to your agent from Slack, Microsoft Teams, Discord interactio
 
 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}
 
@@ -200,7 +204,7 @@ take precedence.
 ### 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:
 
@@ -586,14 +590,16 @@ 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` |
-| 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` | —                                                     |
+| 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`                                                                         | —                                                     |
+
+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.
 
@@ -754,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

package/corpus/core/docs/content/native-chat-ui.mdx

@@ -98,7 +98,7 @@ Server actions should import the server-safe helpers and schemas from
 `@agent-native/core/data-widgets`; client code can import the same types from
 `@agent-native/core/client/chat` or `@agent-native/core/client`.
 
-```ts
+```ts filename="actions/chart-form-responses.ts"
 import { defineAction } from "@agent-native/core/action";
 import { ACTION_CHAT_UI_DATA_CHART_RENDERER } from "@agent-native/core/action-ui";
 import {
@@ -216,7 +216,7 @@ deep link fallback.
 Register product-specific components by exact renderer id, then declare that id
 on the action:
 
-```tsx
+```tsx filename="app/chat-renderers.tsx"
 import { registerActionChatRenderer } from "@agent-native/core/client/chat";
 
 registerActionChatRenderer({
@@ -226,7 +226,7 @@ registerActionChatRenderer({
 });
 ```
 
-```ts
+```ts filename="actions/show-deal-card.ts"
 export default defineAction({
   description: "Show a deal card.",
   outputSchema: dealCardSchema,
@@ -397,7 +397,7 @@ connector helpers. ACP remains coding-agent/editor interoperability, not the
 general app-chat runtime for end users. A2UI is not claimed as supported here;
 if it matures, it should adapt into this same explicit runtime/widget contract.
 
-## Related docs {#related-docs}
+## What's next {#whats-next}
 
 - [Actions](/docs/actions) — define the operations that return native widget data.
 - [Agent Surfaces](/docs/agent-surfaces) — decide whether you need headless, chat, sidecar, or full app.

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

@@ -115,8 +115,8 @@ Severity drives the badge styling in the dropdown and is passed through to chann
 | `slack`   | POST Slack Block Kit JSON to an incoming webhook          | Per-notification `metadata.slackWebhookUrl` and/or `NOTIFICATIONS_SLACK_WEBHOOK_URL`. |
 | `webhook` | POST JSON to a configured URL                             | Per-notification `metadata.webhookUrl` and/or `NOTIFICATIONS_WEBHOOK_URL`.            |
 
-Slack and webhook are always registered. Delivery prefers the per-notification
-metadata URL, then falls back to the matching env var. If neither is set, that
+Email, Slack, and webhook are all always registered alongside the inbox. Delivery prefers the per-notification
+metadata URL/recipients, then falls back to the matching env var. If neither is set, that
 channel no-ops for the emission.
 
 The webhook and Slack channels resolve `${keys.NAME}` references in both the URL and `NOTIFICATIONS_*_AUTH` against the owner's ad-hoc [secrets](/docs/security), so the raw value never enters the agent's context. Per-key URL allowlists are enforced — same rule the automations `web-request` tool uses.
@@ -209,7 +209,7 @@ await notify(
 
 Register a custom channel from any server plugin.
 
-```ts
+```ts filename="server/plugins/notifications-slack-ops.ts"
 import { registerNotificationChannel } from "@agent-native/core/notifications";
 
 registerNotificationChannel({
@@ -280,15 +280,15 @@ interface NotificationMeta {
 
 Mounted at `/_agent-native/notifications/*` by the core-routes plugin. All routes are scoped to the authenticated session's email.
 
-| Method   | Path                                                |
-| -------- | --------------------------------------------------- |
-| `GET`    | `/_agent-native/notifications?unread=true&limit=50` |
-| `GET`    | `/_agent-native/notifications/count`                |
-| `POST`   | `/_agent-native/notifications/:id/read`             |
-| `POST`   | `/_agent-native/notifications/read-all`             |
-| `DELETE` | `/_agent-native/notifications/:id`                  |
+| Method   | Path                                                           |
+| -------- | -------------------------------------------------------------- |
+| `GET`    | `/_agent-native/notifications?unread=true&limit=50&before=ISO` |
+| `GET`    | `/_agent-native/notifications/count`                           |
+| `POST`   | `/_agent-native/notifications/:id/read`                        |
+| `POST`   | `/_agent-native/notifications/read-all`                        |
+| `DELETE` | `/_agent-native/notifications/:id`                             |
 
-<Endpoint id="doc-block-12hm3kj" title="List notifications" summary={"The route behind listNotifications() — scoped to the authenticated session's email."} method="GET" path={"/_agent-native/notifications?unread=true&limit=50"} summary="List recent notifications for the current user" auth={"Authenticated session; results are scoped to the session's email."} params={[
+<Endpoint id="doc-block-12hm3kj" title="List notifications" summary={"The route behind listNotifications() — scoped to the authenticated session's email."} method="GET" path={"/_agent-native/notifications?unread=true&limit=50&before=ISO"} auth={"Authenticated session; results are scoped to the session's email."} params={[
   {
     "name": "unread",
     "in": "query",
@@ -302,6 +302,13 @@ Mounted at `/_agent-native/notifications/*` by the core-routes plugin. All route
     "type": "number",
     "required": false,
     "description": "Max rows to return."
+  },
+  {
+    "name": "before",
+    "in": "query",
+    "type": "string",
+    "required": false,
+    "description": "ISO timestamp cursor — returns notifications created before this time, for pagination."
   }
 ]} responses={[
   {
@@ -314,7 +321,7 @@ Mounted at `/_agent-native/notifications/*` by the core-routes plugin. All route
 
 ## UI component {#ui}
 
-```tsx
+```tsx filename="app/components/HeaderBar.tsx"
 import { NotificationsBell } from "@agent-native/core/client/notifications";
 
 export function HeaderBar() {

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

@@ -92,8 +92,7 @@ No code changes needed. The instrumentation hooks into `production-agent.ts` tra
 
 Add the dashboard to any template with a single route:
 
-```tsx
-// app/routes/observability.tsx
+```tsx filename="app/routes/observability.tsx"
 import { ObservabilityDashboard } from "@agent-native/core/client";
 
 export default function ObservabilityPage() {
@@ -360,8 +359,7 @@ Optional knobs:
 
 Every template inherits this automatically — there's nothing to import. For SSR apps, the server injects a tiny browser config script when `SENTRY_CLIENT_DSN`, `VITE_SENTRY_CLIENT_DSN`, or shared `SENTRY_DSN` is available at runtime, so browser capture is not limited to Vite build-time env. Templates that want custom behavior (extra tags, different DSN per template, hard-disable Sentry) can override by exporting their own plugin from `server/plugins/sentry.ts`:
 
-```ts
-// server/plugins/sentry.ts
+```ts filename="server/plugins/sentry.ts"
 import { createSentryPlugin } from "@agent-native/core/server";
 export default createSentryPlugin();
 ```

package/corpus/core/docs/content/observational-memory.mdx

@@ -139,8 +139,12 @@ Defaults are conservative. An operator can dial compaction at deploy time with `
 
 The Observer and Reflector output caps (4000 / 2000 tokens) keep a single compaction pass from itself blowing the budget; they are tunable in code via `resolveObservationalMemoryConfig({ ... })` but not env-exposed.
 
-> [!TIP]
-> Lower the thresholds to compact sooner (cheaper long threads, slightly more summarization); raise them to keep more raw history in context before compacting. Set `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT` higher if your workflows need a longer verbatim tail.
+<Callout tone="info">
+  Lower the thresholds to compact sooner (cheaper long threads, slightly more
+  summarization); raise them to keep more raw history in context before
+  compacting. Set `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT` higher if your
+  workflows need a longer verbatim tail.
+</Callout>
 
 ## When it kicks in {#when}
 
@@ -151,7 +155,7 @@ OM only changes behavior for threads long enough to have produced at least one o
 
 The injection is best-effort and boundary-safe — if a safe trim point can't be found (e.g. a pending tool-use/result pair sits at the window edge), OM injects the memory block _additively_ without trimming rather than risk dropping a pending tool result.
 
-## Related
+## What's next
 
 - [**Using Your Agent**](/docs/using-your-agent) — the day-to-day loop of working with the agent docked next to your app.
 - [**Observability**](/docs/observability) — token and cost metrics per run, where OM's savings show up.