@agent-native/core 0.47.1 → 0.48.2

package/docs/content/key-concepts.md

@@ -28,9 +28,9 @@ Every agent-native app is three things working together:
 >
 > **Application** — Full React UI with dashboards, flows, and visualizations. Guided experiences your team can use.
 >
-> **Computer** — Database, browser, code execution. Agents work directly with SQL and tools — no MCPs needed.
+> **Computer** — Database, browser, code execution. Agents work directly with SQL and built-in tools; MCP servers are optional add-ons, not the foundation.
 
-Every app includes an embedded agent panel with chat and optional CLI terminal. Locally, you run `pnpm dev` and the agent is right there. In the cloud, Builder.io provides a managed frame with collaboration, visual editing, and managed infrastructure for teams.
+Every app includes an embedded agent panel with chat and optional CLI terminal. Locally, you run `pnpm dev` and the agent is right there. In the cloud, Builder.io provides a managed frame — the environment that hosts the agent next to your app — with collaboration, visual editing, and managed infrastructure for teams.
 
 Six rules govern the architecture:
 
@@ -41,23 +41,6 @@ Six rules govern the architecture:
 5. **The agent can modify code** — the app evolves as you use it
 6. **Application state in SQL** — ephemeral UI state lives in the database, readable by both agent and UI
 
-## What you get for free {#what-you-get-for-free}
-
-Adopting the framework is valuable mostly because of what you stop having to build. The moment your app follows the six rules, you inherit:
-
-- **One action = every surface.** Every action defined with `defineAction()` is simultaneously an agent tool, a typesafe frontend hook (`useActionQuery` / `useActionMutation`), a framework-owned HTTP transport, a CLI command, an MCP tool for external clients, and an A2A tool for other agent-native apps. Optional `link` and `mcpApp` metadata add deep links and MCP Apps UI without a second implementation.
-- **A full workspace per user.** Skills, shared `LEARNINGS.md`, personal `memory/MEMORY.md`, `AGENTS.md`, custom sub-agents, scheduled jobs, connected MCP servers — all SQL-backed, no dev-box required. See [Workspace](/docs/workspace).
-- **Drop-in React components.** `<AgentPanel />` and `<AgentSidebar />` render chat + workspace anywhere in your app. See [Drop-in Agent](/docs/drop-in-agent).
-- **Live sync between agent and UI.** Same-process writes stream immediately over `/_agent-native/events`; a lightweight poll keeps serverless, cron, and cross-process writes convergent. Mutating actions invalidate action-backed queries automatically, so agent-created records appear without a manual refresh. See [Live Sync](#polling-sync) below.
-- **Auth, orgs, RBAC.** Better Auth with orgs/members/roles is wired in for every template. See [Authentication](/docs/authentication).
-- **Context awareness.** The agent always knows what the user is looking at through the `navigation` app-state key. See [Context Awareness](/docs/context-awareness).
-- **MCP client + server, both directions.** The app ingests MCP servers (local, remote, hub-shared) _and_ exposes its own actions as an MCP server. See [MCP Clients](/docs/mcp-clients) and [MCP Protocol](/docs/mcp-protocol).
-- **Inter-app delegation.** Agents in different apps talk over [A2A](/docs/a2a-protocol). Same-origin deploys skip JWT; cross-origin uses a shared `A2A_SECRET`.
-- **Sub-agent teams.** Spawn a sub-agent with its own thread and tools, surfaced as a chip inline in chat. See [Agent Teams](/docs/agent-teams).
-- **Portability.** Any Drizzle-supported SQL database, any Nitro-compatible host (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun).
-
-That's the "and everything else" you'd otherwise be gluing together yourself.
-
 ## The four-area checklist {#four-area-checklist}
 
 Every new feature must update all four areas. Skipping any one breaks the agent-native contract.
@@ -181,6 +164,8 @@ This works in all deployment environments — including serverless and edge —
 
 ## Frames {#frames}
 
+A _frame_ is the environment that hosts the agent next to your app — locally that's the embedded panel; in the cloud it's Builder.io's managed surface. See [Frames](/docs/frames).
+
 Agent-native apps include an embedded agent panel that provides the AI agent alongside the app UI. This is what makes the architecture work: the agent needs a computer (database, browser, code execution), and the app needs the agent for AI work.
 
 > **Embedded Agent Panel** — Chat and optional CLI terminal built into every app. Supports Claude Code, Codex, Gemini, OpenCode, and Builder.io. Runs locally. Free and open source.
@@ -191,6 +176,14 @@ Agent-native apps include an embedded agent panel that provides the AI agent alo
 
 The agent always knows what the user is looking at. The UI writes a `navigation` key to application-state on every route change. The agent reads it via the `view-screen` action before acting.
 
+For example, when you open an email thread the UI upserts a row like:
+
+```json
+{ "key": "navigation", "value": { "view": "thread", "threadId": "th_abc123" } }
+```
+
+The UI writes this on route change; the agent reads it (via `view-screen`) before taking any action, so it always knows which thread — or chart, or slide — you're focused on.
+
 See [Context Awareness](/docs/context-awareness) for the full pattern: navigation state, view-screen, navigate commands, and jitter prevention.
 
 ## One action, many protocols {#protocols}
@@ -284,6 +277,23 @@ Every user gets a personal **workspace** — instructions, skills, memory, custo
 
 Agent-to-agent (**A2A**) is how apps in the same workspace discover and call each other. Each app publishes an agent card with skill metadata; other agents can invoke its actions over JSON-RPC. Same-origin deploys skip JWT; cross-origin uses a shared secret. See [A2A Protocol](/docs/a2a-protocol).
 
+## What you get for free {#what-you-get-for-free}
+
+Adopting the framework is valuable mostly because of what you stop having to build. The moment your app follows the six rules, you inherit:
+
+- **One action = every surface.** Every action defined with `defineAction()` is simultaneously an agent tool, a typesafe frontend hook (`useActionQuery` / `useActionMutation`), a framework-owned HTTP transport, a CLI command, an MCP tool for external clients, and an A2A tool for other agent-native apps. Optional `link` and `mcpApp` metadata add deep links and MCP Apps UI without a second implementation.
+- **A full workspace per user.** Skills, shared `LEARNINGS.md`, personal `memory/MEMORY.md`, `AGENTS.md`, custom sub-agents, scheduled jobs, connected MCP servers — all SQL-backed, no dev-box required. See [Workspace](/docs/workspace).
+- **Drop-in React components.** `<AgentPanel />` and `<AgentSidebar />` render chat + workspace anywhere in your app. See [Drop-in Agent](/docs/drop-in-agent).
+- **Live sync between agent and UI.** Same-process writes stream immediately over `/_agent-native/events`; a lightweight poll keeps serverless, cron, and cross-process writes convergent. Mutating actions invalidate action-backed queries automatically, so agent-created records appear without a manual refresh. See [Live Sync](#polling-sync) below.
+- **Auth, orgs, RBAC.** Better Auth with orgs/members/roles is wired in for every template. See [Authentication](/docs/authentication).
+- **Context awareness.** The agent always knows what the user is looking at through the `navigation` app-state key. See [Context Awareness](/docs/context-awareness).
+- **MCP client + server, both directions.** The app ingests MCP servers (local, remote, hub-shared) _and_ exposes its own actions as an MCP server. See [MCP Clients](/docs/mcp-clients) and [MCP Protocol](/docs/mcp-protocol).
+- **Inter-app delegation.** Agents in different apps talk over [A2A](/docs/a2a-protocol). Same-origin deploys skip JWT; cross-origin uses a shared `A2A_SECRET`.
+- **Sub-agent teams.** Spawn a sub-agent with its own thread and tools, surfaced as a chip inline in chat. See [Agent Teams](/docs/agent-teams).
+- **Portability.** Any Drizzle-supported SQL database, any Nitro-compatible host (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun).
+
+That's the "and everything else" you'd otherwise be gluing together yourself.
+
 ## Deep dives {#deep-dives}
 
 For detailed guidance on specific patterns:

package/docs/content/mcp-apps.md

@@ -0,0 +1,103 @@
+---
+title: "MCP Apps"
+description: "Author and embed interactive MCP App UIs inside Claude, ChatGPT, and other compatible hosts — using real app routes, the embed bridge, and the host bridge API."
+---
+
+# MCP Apps
+
+MCP Apps are the official `io.modelcontextprotocol/ui` extension that lets compatible hosts — Claude, Claude Desktop, ChatGPT, VS Code GitHub Copilot, Goose, Postman, MCPJam, and Cursor — render interactive UIs inline in chat. In agent-native apps, every MCP App is a **real React route**, not a separate plain-HTML widget.
+
+For connecting external agents and the broader MCP server setup, see [External Agents](/docs/external-agents) and [MCP Protocol](/docs/mcp-protocol). This page covers authoring MCP App resources and the embed bridge that powers them.
+
+## Authoring: optional MCP Apps UI {#mcp-apps}
+
+For hosts that support the MCP Apps extension, an action can also advertise an inline UI resource with `mcpApp`. This is a progressive enhancement for flows where the external agent should hand the user an interactive surface instead of only text — for example reviewing an email draft, editing a calendar invite, or choosing between generated dashboard variants.
+
+Use the real React app with `embedRoute()` or `embedApp()` whenever the user needs UI. The mental model is simple: the action's `link` target is also the MCP App embed target. Expose the operation as a normal action/tool, return a focused deep link with `link`, and add `mcpApp.resource = embedApp(...)` so capable hosts load that same route inline instead of opening a new tab. When both should be built from the same route, prefer `embedRoute({ title, openLabel, path })`: it is the convenience wrapper that returns matching `link` and `mcpApp` fields from one call, while `embedApp(...)` is the lower-level resource you assign to `mcpApp.resource` directly.
+
+That means full-app embeds can do anything the route can do once opened: review or edit an email draft, show a filtered inbox/search, open a calendar event or event draft, load an extension page, inspect a full analytics dashboard or saved analysis, continue a deck in the Slides editor, or open a Design project/editor. Prefer URL/deep-link params and the existing `/_agent-native/open` navigation/app-state bridge over inventing a second state protocol for MCP Apps.
+
+On rare occasions the right target is a focused app route that renders one shared React component instead of the whole app shell. Analytics' `/chart` route is the model: it takes a compact `SqlPanel` payload in the URL and renders the same chart component the dashboard uses. This is still an app embed, not a plain HTML MCP App. Expose or call it through a normal action / `open_app({ path, embed: true })`, keep the URL deterministic, and let `embedApp()` render that route inline.
+
+Do not hand-write one-off plain HTML MCP Apps for product UI; if the action needs a custom surface, add or reuse a real app route/component first and embed that route.
+
+```ts
+import { embedApp } from "@agent-native/core";
+
+export default defineAction({
+  // ...description, schema, run, link...
+  mcpApp: {
+    resource: embedApp({
+      title: "Review draft",
+      description: "Open the generated draft in the real Mail compose UI.",
+      iframeTitle: "Agent-Native Mail",
+      openLabel: "Open in Mail",
+    }),
+  },
+});
+```
+
+The MCP server advertises extension `io.modelcontextprotocol/ui`, adds `_meta.ui.resourceUri` plus `_meta["ui/resourceUri"]` to `tools/list`, and also emits ChatGPT Apps SDK compatibility metadata (`openai/outputTemplate`, widget CSP/description/accessibility). It exposes the HTML through `resources/list`, `resources/templates/list`, and `resources/read` using MIME `text/html;profile=mcp-app`. The stdio proxy forwards those resource handlers from the live app, so desktop and CLI clients see the same resources as HTTP clients.
+
+Keep the existing `link` builder even when adding `mcpApp`. CLI-only clients, older hosts, and any host that does not render MCP Apps will ignore the UI metadata and still need the `"Open in … →"` link. `embedApp()` uses that link as its launch target, calls the app-only `create_embed_session` helper, exchanges a one-time SQL ticket at `/_agent-native/embed/start`, and navigates the MCP App frame to the target route with a short-lived browser session plus a bearer fallback for same-origin fetches. `open_app({ app, path, embed: true })` is the generic escape hatch for routes such as full dashboards, filtered inboxes, calendar draft views, analyses, and extension pages, and should be used liberally when the full app is the clearest review/edit surface.
+
+`embedApp()` includes the MCP request origin in the resource CSP so the launcher can fetch and, when explicitly requested, frame the signed first-party app route. Dispatch adds the exact origins for the granted apps to its `open_app` resource so a single Dispatch connector can inline Mail, Calendar, Slides, and the rest without allowing every HTTPS origin. Only pass additional frame or resource domains for a custom MCP App that truly embeds a third-party player or loads third-party assets.
+
+Inside those `embedApp()` routes, `sendToAgentChat()` is embed-aware. Auto-submitted prompts relay to the MCP host as `ui/update-model-context` plus `ui/message`, so a button in the embedded app can intentionally continue the Claude/ChatGPT conversation from the selected app state. Hidden context is sent as model context; the visible user turn stays just the app's prompt, which avoids scary host consent around internal app-state file paths. `submit: false` remains local prefill/review behavior.
+
+## First-class MCP App bridge {#mcp-app-bridge}
+
+MCP App embeds are route embeds, not separate mini-products. `embedApp()` starts from the action's `link` target, creates a short-lived embed session, and launches that signed app route. Standard MCP Apps hosts can navigate the MCP App frame itself when the host can hydrate the route directly. Claude web uses a single-frame transplant path: the resource document fetches the signed app HTML and hydrates it inside Claude's MCP App iframe because Claude does not reliably allow app-owned child iframes or external frame navigation. ChatGPT web gets a controlled route iframe because its Apps bridge gives us stable `window.openai` host APIs and bounded height control. All paths point at the same signed app route and render the normal route and React components. Design embedded routes so a reload with the same signed URL reconstructs the same view.
+
+For same-app `open_app({ embed: true })`, the framework mints the embed-start ticket during the original tool call and stores the signed start URL in hidden tool metadata. Custom actions can return `embedStartUrl` for the same fast path; the MCP layer strips that ticket-bearing URL from model-visible `structuredContent` and normal open-link metadata. When no embed start URL is present, the resource falls back to the app-only `create_embed_session` helper. This keeps production hosts that restrict iframe-initiated tool calls on the direct route without leaking one-time app session URLs into the transcript. If a user reopens an old chat after a one-time start ticket has expired, the start route returns a small refresh page and posts `agentNative.embedSessionExpired` to the wrapper; `embedApp()` clears the stale start URL and mints a fresh ticket through `create_embed_session` when it still has the original app route.
+
+ChatGPT gets a dedicated compatibility path through `window.openai`: the launch document reads `toolInput`, `toolOutput`, and `toolResponseMetadata` directly, then calls `create_embed_session` via `window.openai.callTool(...)`. Standard MCP Apps hosts use the `ui/*` JSON-RPC bridge. Directly hydrated routes can call `ui/update-model-context`, `ui/message`, `ui/open-link`, and `ui/request-display-mode` through the host bridge helpers. Claude's transplanted route uses the same direct `ui/*` host bridge after hydration. When the ChatGPT or explicit diagnostic iframe path is used, the wrapper relays the same host actions over `agentNative.mcpHost.*` postMessage requests. Keep the result shape identical for both paths: return a focused `link` and concise structured content.
+
+Do not set standard `_meta.ui.domain` to an app URL. MCP Apps treats that field as host-specific: Claude validates `{hash}.claudemcpcontent.com`-style sandbox domains, while ChatGPT uses its own `openai/widgetDomain` metadata. Omit `ui.domain` unless you are deliberately emitting a host-specific value; the host will choose a default sandbox origin.
+
+Extension pages keep their sandbox in MCP chat embeds without navigating a second route iframe. Normal app usage renders `/_agent-native/extensions/:id/render` as a sandboxed child iframe. In MCP chat bridge mode the framework renders the same extension document as sandboxed `srcDoc` inside the route iframe, avoiding host `frame-ancestors` / `X-Frame-Options` failures while preserving `sandbox="allow-scripts allow-forms"`.
+
+The resource shell owns the outer host size. `embedApp({ height })` defaults to `560px`, clamps the shell to `320-900px`, and reserves `44px` for the small toolbar, so the route viewport is `height - 44px`. Keep embedded app routes internally scrollable and let the launcher report that bounded intrinsic height rather than the full document height; otherwise host auto-resize can turn a normal app page into a very tall chat artifact. A changed shell only affects new MCP App resources and new tool calls. Old ChatGPT/Claude conversation frames can keep the previous resource behavior, so verify sizing with a fresh inline render before judging a fix.
+
+### Embed modes {#embed-modes}
+
+Claude uses the single-frame transplant path by default. You can also force it in other hosts with `embedMode: "transplant"` or `frame: "transplant"` when debugging host module-loading behavior. You can force the nested diagnostic iframe with `embedMode: "iframe"`, `renderMode: "iframe"`, `nested: true`, or `frame: "iframe"`. If the iframe is blocked, `embedApp()` replaces it with an open-app fallback: the user can retry inline, open a freshly minted embed session through the host, or use the visible route URL. Keep the action's `link` target useful on its own because it is still the universal escape hatch.
+
+When testing Claude through ngrok, use a production build (`agent-native build` then `agent-native start`) or a deployed preview/production URL. Claude's single-frame transplant path works with production asset chunks; raw Vite dev modules such as `/app/root.tsx` can be protected by app auth and fail dynamic imports from the Claude resource origin.
+
+## Host bridge API {#host-bridge}
+
+The host bridge is deliberately small:
+
+| Mode                   | Message type                          | Use it for                               |
+| ---------------------- | ------------------------------------- | ---------------------------------------- |
+| direct host route      | `ui/update-model-context`             | Hidden context for the host model        |
+| direct host route      | `ui/message`                          | Post a visible user turn into the host   |
+| direct host route      | `ui/open-link`                        | Open an external or app URL via the host |
+| direct host route      | `ui/request-display-mode`             | Request `inline`, `fullscreen`, or `pip` |
+| Claude transplant      | `ui/*`                                | Same direct host bridge after hydration  |
+| ChatGPT / iframe route | `agentNative.mcpHostContext`          | Theme, locale, host platform, dimensions |
+| ChatGPT / iframe route | `agentNative.embeddedAppReady`        | Confirm the route iframe loaded          |
+| ChatGPT / iframe route | `agentNative.mcpHost.*` / `.response` | Wrapper relay for host requests          |
+
+Embedded routes can use `updateMcpAppModelContext()`, `openMcpAppHostLink()`, `requestMcpAppDisplayMode()`, `getMcpAppHostContext()`, and `useMcpAppHostContext()` from `@agent-native/core/client`. `sendToAgentChat()` uses the same path from full-app embeds for auto-submitted prompts.
+
+Display mode is best-effort. The in-app `McpAppRenderer` currently reports an inline web host context and an inline-only display mode; external hosts may honor larger display requests, ignore them, or reply with an unsupported-mode error. Always keep the inline route usable.
+
+## Client support and caching {#client-support}
+
+The current official MCP Apps client list includes Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT, and Cursor; host support still varies by plan, release channel, and client version, so check the [MCP extension support matrix](https://modelcontextprotocol.io/extensions/client-matrix). ChatGPT custom MCP apps are available through developer mode for Business and Enterprise/Edu workspaces on ChatGPT web; see OpenAI's [developer mode and MCP apps](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-apps-in-chatgpt-beta) notes.
+
+Claude Code, Codex, and other CLI/code-editor clients still receive the same resources and metadata when they support MCP Apps, but treat them as link-out hosts unless you have verified inline iframe rendering in that exact surface. The deep link remains the reliable fallback when a host chooses not to render an iframe. In practice, every agent-native app should be authored with both: MCP Apps for inline review/edit in capable hosts, and `link` for universal round-tripping back to the full app.
+
+Claude and ChatGPT can cache tool and resource metadata for an existing custom connector. After changing MCP App metadata, verify with a fresh tool call; if the host still uses the old descriptor, reconnect the Claude connector or rescan/review the ChatGPT connector so it refreshes the catalog. If Claude logs a warning about `_meta.ui.csp` or `_meta.ui.permissions` living on the tool descriptor after a deploy, that connector is using stale metadata: delete/reconnect the Claude connector and start a fresh chat.
+
+## Testing {#testing}
+
+Test MCP Apps with the lightweight fixtures around `embedApp()` and `McpAppRenderer`; they cover CSP, host context, app launch, and bridge message behavior without needing a real external host. When validating ChatGPT or Claude web, trigger a fresh tool call after shell changes and measure the visible iframe. Previously rendered frames in the same conversation may still show cached height or launch behavior.
+
+## Related {#related}
+
+- [External Agents](/docs/external-agents) — connecting Claude, ChatGPT, Codex, and Cursor to hosted apps; MCP Apps compatibility matrix; catalog tiers; deep links.
+- [MCP Protocol](/docs/mcp-protocol) — the auto-mounted MCP server, auth, tools, and `ask-agent`.
+- [Actions](/docs/actions) — `defineAction`, the `link` builder, `publicAgent`.

package/docs/content/mcp-clients.md

@@ -167,7 +167,7 @@ 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.
+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.
 
 Dispatch is the conventional hub — it already coordinates across apps.
 
@@ -230,7 +230,7 @@ Hub responses include the full auth headers (Bearer tokens etc). The transport i
 
 ### 4. Hot reload vs restart
 
-Local UI adds in each app hot-reload via `McpClientManager.reconfigure()` — no restart. Hub-sourced servers currently re-fetch only when a local mutation triggers a reconfigure (or when the app restarts), so if you add a new server in dispatch, other apps pick it up on their next restart or next local change. Periodic background refresh is on the roadmap.
+Local UI adds in each app hot-reload via `McpClientManager.reconfigure()` — no restart. Hub-sourced servers are picked up by the same periodic background refresh (approximately 60 s, tunable or disableable via `AGENT_NATIVE_MCP_CONFIG_REFRESH_MS`) that the workspace resource path uses, so changes made in Dispatch propagate to all consumer apps within about a minute without a restart. Additionally, any local mutation in a consumer app immediately triggers a reconfigure for that app.
 
 ### Endpoints summary
 

package/docs/content/mcp-protocol.md

@@ -7,6 +7,16 @@ description: "Expose your agent-native app as a remote MCP server so Claude, Cha
 
 Every agent-native app automatically exposes a remote MCP (Model Context Protocol) server. This lets external AI tools like Claude, ChatGPT custom MCP apps, Claude Code, Cursor, Codex, VS Code GitHub Copilot, and Windsurf discover and call your app's actions directly — no extra code needed.
 
+**Which page do I need?**
+
+| Goal                                                        | Page                                     |
+| ----------------------------------------------------------- | ---------------------------------------- |
+| Connect Claude / ChatGPT / Codex / Cursor to a hosted app   | [External Agents](/docs/external-agents) |
+| Make your app callable over MCP (server setup, auth, tools) | This page                                |
+| Give your app's agent more tools from external MCP servers  | [MCP Clients](/docs/mcp-clients)         |
+| App-to-app delegation via JSON-RPC                          | [A2A Protocol](/docs/a2a-protocol)       |
+| Build or embed interactive MCP App UIs                      | [MCP Apps](/docs/mcp-apps)               |
+
 If your goal is to connect Claude, ChatGPT, Claude Code, Codex, Cursor, or Claude Cowork to hosted agent-native apps, start with [External Agents](/docs/external-agents). It documents the recommended single Dispatch connector at `https://dispatch.agent-native.com/_agent-native/mcp`, direct per-app URLs for isolated app access, standard remote MCP OAuth, fallback config for older clients, MCP Apps inline UIs, and deep links back into the UI. This page is the lower-level MCP server reference.
 
 ## Overview {#overview}
@@ -38,23 +48,29 @@ 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 {#claude-code}
+## Manual MCP client 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:
 
+```bash
+claude mcp add --transport http mail https://mail.example.com/_agent-native/mcp
+```
+
+Or write the entry by hand in `.mcp.json` (project scope) or `~/.claude.json` (user scope):
+
 ```jsonc
-// ~/.claude/mcp_servers.json
+// .mcp.json
 {
-  "mail": {
-    "type": "http",
-    "url": "https://mail.example.com/_agent-native/mcp",
+  "mcpServers": {
+    "mail": {
+      "type": "http",
+      "url": "https://mail.example.com/_agent-native/mcp",
+    },
   },
 }
 ```
 
-Then run `/mcp` in Claude Code and choose **Authenticate**. For clients that cannot perform remote MCP OAuth, use the Connect page or a static bearer-token entry with `headers.Authorization`.
-
-Then in Claude Code, you can use your app's tools naturally:
+Then run `/mcp` in Claude Code and choose **Authenticate**. For clients that cannot perform remote MCP OAuth, use the Connect page or a static bearer-token entry with `headers.Authorization`. Once authenticated, you can use your app's tools naturally:
 
 ```
 > draft an email to John about the Q3 report
@@ -83,10 +99,7 @@ navigation, mediates host actions over the `ui/*` JSON-RPC bridge (and the
 clamps the resource shell height so a full-app route does not render as an
 oversized chat artifact.
 
-See [External Agents](/docs/external-agents#mcp-app-bridge) for the full MCP App
-embed bridge and host-bridge details — transplant vs controlled-frame, the
-`ui/*` and postMessage tables, `create_embed_session` / `embedStartUrl`, CSP and
-domain rules, extension `srcDoc` embedding, and height clamping.
+See [MCP Apps](/docs/mcp-apps#mcp-app-bridge) for the full embed bridge details — transplant vs controlled-frame, the `ui/*` and postMessage tables, `create_embed_session` / `embedStartUrl`, CSP and domain rules, extension `srcDoc` embedding, height clamping, and the host bridge client API.
 
 ## Tools {#tools}
 
@@ -187,7 +200,7 @@ import { autoDiscoverActions } from "@agent-native/core/server";
 export default defineNitroPlugin(async (nitro) => {
   const actions = await autoDiscoverActions(import.meta.url);
 
-  mountMCP(nitro.h3App, {
+  mountMCP(nitro, {
     name: "My App",
     description: "Custom MCP server",
     actions,
@@ -196,6 +209,8 @@ export default defineNitroPlugin(async (nitro) => {
       // Your custom agent logic
       return "Response";
     },
+    // Optional: override the route prefix (default "/_agent-native")
+    // routePrefix: "/_agent-native",
   });
 });
 ```
@@ -204,12 +219,20 @@ export default defineNitroPlugin(async (nitro) => {
 
 You have a deployed analytics app at `analytics.example.com`. From Claude Code:
 
+```bash
+claude mcp add --transport http analytics https://analytics.example.com/_agent-native/mcp
+```
+
+Or add it by hand in `.mcp.json`:
+
 ```jsonc
-// ~/.claude/mcp_servers.json
+// .mcp.json
 {
-  "analytics": {
-    "type": "http",
-    "url": "https://analytics.example.com/_agent-native/mcp",
+  "mcpServers": {
+    "analytics": {
+      "type": "http",
+      "url": "https://analytics.example.com/_agent-native/mcp",
+    },
   },
 }
 ```

package/docs/content/messaging.md

@@ -16,6 +16,7 @@ Connect your agent to Slack, email, Telegram, or WhatsApp so you can chat with i
 - **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.
+- For one-way in-app alerts (bell icon, webhooks) see [Notifications](/docs/notifications).
 
 ## Set up Slack {#slack}
 
@@ -345,8 +346,13 @@ const myAdapter: PlatformAdapter = {
     };
   },
 
-  // Format plain agent text into a platform-appropriate OutgoingMessage
-  formatAgentResponse(text: string): OutgoingMessage {
+  // Format plain agent text into a platform-appropriate OutgoingMessage.
+  // opts.threadDeepLinkUrl, when provided, is a URL back to the originating
+  // thread in the dispatch UI — render it as a button (Slack) or inline link.
+  formatAgentResponse(
+    text: string,
+    opts?: { threadDeepLinkUrl?: string },
+  ): OutgoingMessage {
     return { text, platformContext: {} };
   },
 
@@ -358,8 +364,9 @@ const myAdapter: PlatformAdapter = {
     // Call the platform's API, using context.platformContext for routing
   },
 
-  // Return current connection/configuration status for the settings UI
-  async getStatus() {
+  // Return current connection/configuration status for the settings UI.
+  // baseUrl is the app's public URL, used for status checks that need it.
+  async getStatus(baseUrl?: string) {
     return {
       platform: "discord",
       label: "Discord",

package/docs/content/migration-workbench.md

@@ -1,9 +1,9 @@
 ---
-title: "Migration Workbench"
+title: "Migrating to Agent-Native (/migrate)"
 description: "Use the open-source Agent-Native Code workspace for coding sessions, including the built-in /migrate capability."
 ---
 
-# Agent-Native Code Workspace and /migrate
+# Migrating to Agent-Native (/migrate)
 
 Start from **Agent-Native Code**:
 
@@ -35,52 +35,9 @@ full run-control command set).
 
 ## Code Workspace
 
-`agent-native code` opens the interactive Agent-Native Code shell for coding-agent work. You do not need to pass an initial prompt:
+`agent-native code` opens the interactive Agent-Native Code shell. Inside the shell, `/migrate` is a slash goal alongside `/audit` and other built-in commands. Projects can also define custom migration variants in `.agents/commands/*.md`. The CLI and Desktop hub share the same run store — start in one and continue in the other using the standard `list`/`attach`/`logs`/`resume`/`approve`/`stop` controls.
 
-```bash
-npx @agent-native/core@latest code
-```
-
-Inside the shell, type a task or use slash goals as commands:
-
-```text
-code> fix the failing auth tests
-code> /migrate ./my-next-app --out ../migrated-app
-code> /audit --url https://example.com
-```
-
-Agent-Native Code uses the same minimal coding-tool profile (`bash`, `read`, `edit`, `write`) and shared composer as the rest of the framework; see [Agent-Native Code UI](/docs/code-agents-ui) for details.
-
-The same goals can run directly from the command line:
-
-```bash
-npx @agent-native/core@latest "fix the failing auth tests"
-npx @agent-native/core@latest code "fix the failing auth tests"
-npx @agent-native/core@latest code exec "fix the failing auth tests"
-npx @agent-native/core@latest code -p "fix the failing auth tests"
-npx @agent-native/core@latest code --plan "explain the failing auth tests"
-npx @agent-native/core@latest code --auto "fix the failing auth tests"
-npx @agent-native/core@latest code /migrate ./my-next-app --out ../migrated-app
-npx @agent-native/core@latest code /audit --url https://example.com
-```
-
-Run `agent-native code goals` to see the goals registered in your checkout. A bare prompt starts a local coding-agent session for open-ended code work, streams the run, records transcript/status/tool events, and accepts follow-up prompts through the same run record.
-
-Installed `agent-native` with no arguments launches the Agent-Native Code workspace, and `agent-native "prompt"` starts a generic Agent-Native Code task directly. Use `agent-native create` when you want to scaffold apps or workspaces.
-
-## Sessions and Modes
-
-Agent-Native Code makes migration feel like a local Codex/Claude Code session instead of a one-shot command. The CLI and Desktop hub share the same run store, so you can start a `/migrate` run in one place and continue it in the other with the standard `list`/`attach`/`logs`/`resume`/`approve`/`stop` controls. See [Agent-Native Code UI](/docs/code-agents-ui) for those run controls, the mixed background-run source model, two-way follow-up semantics, and the Plan/Auto run modes that also govern `/migrate` sessions. Auto mode is the default; use Plan mode for migration assessment, architecture, or review where you want a proposal before edits.
-
-## Project Slash Commands
-
-Built-in slash goals such as `/migrate` and `/audit` are framework commands. Projects can also define migration variants as custom commands in `.agents/commands/*.md` (see [Agent-Native Code UI](/docs/code-agents-ui) for how project commands and skills are discovered and inserted):
-
-```bash
-npx @agent-native/core@latest code /migrate-storefront ./legacy-shop --out ../agent-shop
-```
-
-Versioning migration variants this way keeps source-specific handoffs close to the repository. Source-specific systems such as AEM or Builder.io should stay as optional instruction-pack examples inside those commands, not top-level migration assumptions.
+See [Agent-Native Code UI](/docs/code-agents-ui) for the full shell, run controls, Plan/Auto modes, slash-goal discovery, and Desktop hub integration.
 
 ## Input Shapes
 

package/docs/content/multi-app-workspace.md

@@ -31,7 +31,7 @@ Anything every app in your org should agree on can live in `packages/shared`:
 
 Each individual app becomes _just a set of screens_ — routes, dashboards, views, domain-specific actions. Framework defaults cover the rest until you add a real workspace customization.
 
-That same boundary applies when your app wants to use another first-party app. A new workspace dashboard that needs email, calendar, analytics, and company-memory context should use the existing Mail, Calendar, Analytics, and Brain apps as connected neighbors over links or A2A. It should not clone those templates, create a wrapper app that nests them, or scaffold child apps inside itself just to get access to their data or agents. For example, the hosted first-party apps already live at [mail.agent-native.com](https://mail.agent-native.com), [calendar.agent-native.com](https://calendar.agent-native.com), [analytics.agent-native.com](https://analytics.agent-native.com), and [brain.agent-native.com](https://brain.agent-native.com). Fork or scaffold a copy only when you explicitly want to customize that app; otherwise, using the hosted/shared app keeps base template improvements flowing automatically.
+That same boundary applies when your app wants to use another first-party app. A new workspace dashboard that needs email, calendar, analytics, and company-memory context should use the existing Mail, Calendar, Analytics, and Brain apps as connected neighbors over links or A2A. It should not clone those templates, create a wrapper app that nests them, or scaffold child apps inside itself just to get access to their data or agents. Fork or scaffold a copy only when you explicitly want to customize that app.
 
 ## Getting started {#getting-started}
 
@@ -138,24 +138,33 @@ Because the shared package is a `workspace:*` dependency, pnpm symlinks it into
 
 Use `packages/shared` for code-level defaults that should ship with the repo: plugins, shared actions, shared React code, filesystem `AGENTS.md`, and filesystem skills. Use Dispatch workspace resources for runtime-editable global context that admins want to manage without a code change.
 
-Dispatch resources are scoped **All apps** (every app inherits them at runtime, no copy or sync step) or **Selected apps** (granted per app for app-specific context). The path — `AGENTS.md`/`instructions/<slug>.md`, `skills/<slug>/SKILL.md`, `context/<slug>.md`, `agents/<slug>.md`, `mcp-servers/<slug>.json` — determines how the agent uses each resource. See [Workspace](/docs/workspace#global-resources) for the full resource-model table and the recommended starter pack (`context/company.md`, `context/brand.md`, `context/messaging.md`, `instructions/guardrails.md`, `skills/company-voice/SKILL.md`).
+Dispatch resources are scoped **All apps** (every app inherits them at runtime, no copy or sync step) or **Selected apps** (granted per app for app-specific context). See [Workspace](/docs/workspace#global-resources) for the full resource-model table, path conventions, and the recommended starter pack.
 
 ## Authentication and RBAC {#auth-and-rbac}
 
-Every agent-native app already ships with [Better Auth](/docs/authentication) plus the framework's built-in organization system — users, organizations, members, and the `owner` / `admin` / `member` roles are all first-class, shared across every template. (Organizations are framework-managed via the `organizations` / `org_members` tables, not Better Auth's organization plugin, which is intentionally not registered.) In a workspace, you get that for free in every app, backed by the same database.
+Every agent-native app already ships with [Better Auth](/docs/authentication) plus the framework's built-in organization system. In a workspace, you get that for free in every app, backed by the same database. For the full multi-tenancy model — organizations, roles, data isolation — see [Multi-Tenancy](/docs/multi-tenancy).
 
 For enterprise-specific rules (allow-list domains, SSO enforcement, extra role checks), export an `authPlugin` from `packages/shared/src/server/index.ts`. Every app in the workspace now enforces those rules.
 
 Active organization flows automatically: `session.orgId` → `AGENT_ORG_ID` → SQL row scoping, so data tagged with `org_id` is invisible to other orgs even to the agent. See [Security & Data Scoping](/docs/security) for the full model.
 
+## Shared MCP servers {#shared-mcp}
+
+The recommended options for sharing MCP servers across workspace apps, in order of preference:
+
+1. **Dispatch workspace MCP resources** — add `mcp-servers/<name>.json` resources in Dispatch at **All apps** scope. Every app in the workspace inherits the MCP server at runtime with no file edits or redeploy. Grant to selected apps only when the server is app-specific. Tokens live in the Dispatch vault; reference them from the resource JSON with `${keys.NAME}`.
+
+2. **Root `mcp.config.json`** — drop a file at the workspace root and every app in the workspace connects to the same MCP servers. Individual apps can override with their own `mcp.config.json` (app-root wins). Use this for local/filesystem MCP servers (`@modelcontextprotocol/server-filesystem`, `claude-in-chrome`, Playwright) that don't need per-user vault credentials.
+
+3. **Settings UI (personal/org scope)** — for remote HTTP MCP servers, users can add them from the settings UI at Personal or Team (org) scope — no file edits, hot-reloaded into the running agent.
+
+See [MCP Clients](/docs/mcp-clients) for the config schema, precedence rules, and hub setup.
+
 ## Shared environment variables {#shared-env}
 
 The workspace root `.env` is loaded into every app automatically. Put shared keys once at the root — `ANTHROPIC_API_KEY`, `A2A_SECRET`, `BETTER_AUTH_SECRET`, `DATABASE_URL`, `BUILDER_PRIVATE_KEY`, etc. — and every app picks them up. Per-app overrides go in `apps/<name>/.env` and win on conflict.
 
-For runtime app credentials, prefer the Dispatch vault over hand-editing `.env`
-files. The vault defaults to all-apps access, so every saved vault key is
-available to every workspace app and can be pushed with `sync-vault-to-app`.
-Switch the vault to manual mode only when apps need explicit per-key grants.
+For runtime app credentials, prefer the Dispatch vault over hand-editing `.env` files. The vault defaults to all-apps access, so every saved vault key is available to every workspace app and can be pushed with `sync-vault-to-app`. Switch the vault to manual mode only when apps need explicit per-key grants.
 
 ```text
 my-company-platform/
@@ -170,14 +179,6 @@ 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 the **workspace root** `.env`, so every app gains browser access at once.
 - **Env-vars settings route** (`POST /_agent-native/env-vars`): when inside a workspace, defaults to writing the workspace root `.env`. Pass `scope: "app"` in the body to override one app.
 
-## Shared MCP servers {#shared-mcp}
-
-Drop an `mcp.config.json` at the workspace root and every app in the workspace connects to the same MCP servers — one place to configure `claude-in-chrome`, `@modelcontextprotocol/server-filesystem`, Playwright, or any internal MCP server. Individual apps can override with their own `mcp.config.json` (app-root wins over the workspace root for that one app).
-
-For remote HTTP MCP servers (Zapier, Composio, internal tools), users can add them from the settings UI at **Personal** or **Team (org)** scope — no file edits, hot-reloaded into the running agent. And if you run the dispatch template, it can act as an **MCP hub** that every other app in the workspace pulls org-scope servers from, so you configure each URL + bearer token exactly once.
-
-See [MCP Clients](/docs/mcp-clients) for the config schema, precedence rules, remote-UI scopes, and hub setup.
-
 ## 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.
@@ -242,9 +243,38 @@ For Vercel Git deployments, set the build command to:
 pnpm exec agent-native deploy --preset vercel --build-only
 ```
 
+### Public app routes
+
+Workspace apps are internal by default. For a public site with login-only admin pages, set a public audience and protect the admin prefix in that app's `package.json`:
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "audience": "public",
+      "protectedPaths": ["/admin"]
+    }
+  }
+}
+```
+
+For mostly internal apps with a few public pages, leave the audience internal and list page prefixes:
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "publicPaths": ["/", "/share"]
+    }
+  }
+}
+```
+
+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 && agent-native build` behaves exactly like a standalone scaffold. Cross-app A2A then goes through the standard JWT-signed path with a shared `A2A_SECRET`.
+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 && agent-native 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.
 
 ### Shared database, shared credentials
 
@@ -256,7 +286,6 @@ The shared package itself is never deployed standalone. It's a `workspace:*` dep
 
 The workspace pattern is intentionally narrow. A few things it deliberately doesn't handle yet:
 
-- **Cross-domain SSO.** The unified `agent-native deploy` flow solves the common case (one origin, many apps at `/mail`, `/calendar`, …). If you need `mail.company.com` and `calendar.company.com` on _different_ domains to share a session, that requires a shared cookie domain or a central auth app with OAuth redirects — both supported by the underlying stack but neither scaffolded out of the box.
 - **Encrypted credential vault.** Prefer the Dispatch vault for runtime app credentials (see [Shared environment variables](#shared-env)). The non-vault fallback path — shared credentials written directly to the framework `settings` table — stores them as plain text today, so rotate responsibly when you rely on it.
 - **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.
@@ -265,4 +294,6 @@ The workspace pattern is intentionally narrow. A few things it deliberately does
 
 - [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.
+- [Multi-Tenancy](/docs/multi-tenancy) — organizations, roles, and per-org data isolation.
+- [Cross-App SSO](/docs/cross-app-sso) — identity federation for separate-domain deploys.
 - [Dispatch](/docs/dispatch) — the runtime control plane that typically lives inside a multi-app workspace as the secrets vault, integration catalog, and approvals hub.

package/docs/content/multi-tenancy.md

@@ -16,7 +16,7 @@ The framework provides full multi-tenancy through its own built-in organization
 - **Active organization** — the session tracks which org the user is currently working in (`session.orgId`). Switching orgs changes the data they see.
 - **Data isolation** — SQL queries are automatically scoped to the active org via `org_id` columns. Data tagged with one org is invisible to users in another org, including the agent.
 
-All first-party templates (Mail, Calendar, Content, Brain, Assets, Slides, Video, Analytics, Clips, Design, Forms, and Dispatch) are multi-tenant out of the box. If you're building on any of these, your app already supports teams with no extra work.
+All first-party templates are multi-tenant out of the box. See [Cloneable SaaS templates](/docs/cloneable-saas) for the full list.
 
 ## Organizations and members {#organizations-and-members}
 

package/docs/content/notifications.md

@@ -7,6 +7,8 @@ description: "In-app notifications with pluggable channels — inbox, webhook, o
 
 One function, many destinations. Call `notify()` from any server-side code — an action, an automation, a plugin — and the event lands in the user's in-app inbox and fans out to every registered channel. Ships with a bell-and-dropdown UI component that the host template drops into its header.
 
+Notifications are one-way alerts into the app's bell inbox (plus webhook fan-out). To _converse_ with your agent from Slack/email/Telegram/WhatsApp, see [Messaging](/docs/messaging).
+
 ```ts
 import { notify } from "@agent-native/core/notifications";
 
@@ -160,14 +162,14 @@ Pass `browserNotifications` to also fire system `new Notification(...)` popups f
 
 ## Agent tools {#agent-tools}
 
-Two native tools are registered in every template:
+A single `manage-notifications` tool is registered in every template. The `action` parameter selects the operation:
 
-| Tool                 | Purpose                                              |
-| -------------------- | ---------------------------------------------------- |
-| `notify`             | Send a notification from an agent turn or automation |
-| `list-notifications` | Show recent notifications to the agent for context   |
+| Action | Parameters                                                                    | Purpose                                                         |
+| ------ | ----------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `send` | `severity` (required), `title` (required), `body`, `metadataJson`, `channels` | Send a notification to the user's inbox and registered channels |
+| `list` | `unreadOnly`, `limit` (max 200, default 20)                                   | List recent notifications for context                           |
 
-Automations (see [Automations](/docs/automations)) can call `notify` in their body — this is the canonical pattern for turning an external event into a user-visible alert.
+Automations (see [Automations](/docs/automations)) can call `manage-notifications` with `action=send` in their body — this is the canonical pattern for turning an external event into a user-visible alert.
 
 ## Event bus {#event-bus}