@agent-native/core 0.56.0 → 0.57.0

package/docs/content/agent-surfaces.md

@@ -0,0 +1,258 @@
+---
+title: "Agent Surfaces"
+description: "Use Agent-Native headlessly, as rich chat, inside an existing app, or as a full agent-native application."
+search: "headless agent rich chat full app BYO agent runtime AgentChatRuntime embed actions MCP A2A HTTP CLI"
+---
+
+# Agent Surfaces
+
+Agent-Native is deliberately composable. You can use the agent without much UI,
+use the UI without the built-in agent runtime, or use both together as a full
+application.
+
+The useful way to choose is not by protocol first. Choose the product surface
+you want, then use the matching primitive.
+
+| Surface                       | Use it when                                                                                                 | Start with                                                         |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| **Headless agent/actions**    | Code, jobs, scripts, another app, or another agent should call the work directly.                           | `defineAction`, HTTP, CLI, MCP, A2A                                |
+| **Rich chat on Agent-Native** | You want a standalone or embedded chat backed by the built-in agent loop.                                   | `<AgentChatSurface>`, `<AssistantChat>`, `createAgentChatPlugin()` |
+| **Rich chat on your agent**   | You built the agent elsewhere and want Agent-Native's composer, transcript, tool cards, and native widgets. | `AgentChatRuntime`, `<AssistantChat runtime={runtime}>`            |
+| **Embedded sidecar**          | You already have a SaaS app and want an agent beside it with page context and host commands.                | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded`         |
+| **Full application**          | Humans and agents should share durable screens, data, navigation, and collaboration.                        | Templates, actions, SQL state, context awareness                   |
+
+Those are stages, not separate products. A workflow can start as a headless
+action, appear in chat as a table or chart, and later become a full screen in an
+app without changing the operation the agent calls.
+
+## Headless agent/actions {#headless}
+
+Use the headless path when no one needs to stare at a custom app screen while
+the work runs: scheduled jobs, integrations, backend workflows, CLI loops,
+another agent, or an existing product calling into Agent-Native.
+
+Most headless integrations should start with actions:
+
+```ts
+// actions/summarize-week.ts
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Summarize this week's submissions.",
+  readOnly: true,
+  schema: z.object({ formId: z.string() }),
+  run: async ({ formId }) => {
+    return { formId, summary: "34 submissions, up 18% from last week." };
+  },
+});
+```
+
+One action is then callable as:
+
+- **HTTP** — `POST /_agent-native/actions/summarize-week`
+- **CLI** — `pnpm action summarize-week --formId form_123`
+- **MCP** — from Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot, and other MCP hosts
+- **A2A** — from another agent-native app or agent peer
+- **UI** — through `useActionQuery`, `useActionMutation`, or `callAction`
+- **Agent tool** — from the built-in chat loop
+
+If you need the whole agent loop headlessly, use the server API from a worker,
+job, integration webhook, or custom host. This is lower-level than actions: you
+provide the engine, model, messages, actions, and event sink yourself.
+
+```ts
+import {
+  actionsToEngineTools,
+  resolveEngine,
+  runAgentLoop,
+} from "@agent-native/core/server";
+
+const engine = await resolveEngine({ engineOption: undefined });
+const model = engine.defaultModel;
+const controller = new AbortController();
+
+await runAgentLoop({
+  engine,
+  model,
+  systemPrompt: "You are the reporting agent for this workspace.",
+  actions,
+  tools: actionsToEngineTools(actions),
+  messages: [
+    {
+      role: "user",
+      content: [{ type: "text", text: "Summarize this week's forms." }],
+    },
+  ],
+  send: (event) => {
+    // Persist, log, stream, or translate AgentChatEvent objects.
+  },
+  signal: controller.signal,
+  ownerEmail: user.email,
+  orgId: user.orgId,
+});
+```
+
+For most apps, scheduled prompts and integration webhooks already call this loop
+for you. Reach for direct `runAgentLoop()` when you are building a custom
+headless host, eval runner, or server-side orchestration surface.
+
+## Rich chat on Agent-Native {#rich-chat}
+
+Use the built-in chat when the user should talk to the agent, see tool calls,
+approve work, inspect native results, and keep a durable thread history.
+
+The simplest full-page chat:
+
+```tsx
+import { AgentChatSurface } from "@agent-native/core/client/chat";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-screen" />;
+}
+```
+
+The simplest embedded chat with your own chrome:
+
+```tsx
+import { AssistantChat } from "@agent-native/core/client/chat";
+
+export function ProjectChat({ threadId }: { threadId: string }) {
+  return <AssistantChat threadId={threadId} />;
+}
+```
+
+Actions can return explicit native widget results so chat output is not just
+text. Tables, charts, and typed product cards render as first-party React
+components in the chat, without iframes. See [Native Chat UI](/docs/native-chat-ui).
+
+## Rich chat on your agent {#byo-agent}
+
+Use this path when your agent is already built with another framework or
+runtime and you want Agent-Native's chat UI around it.
+
+`AgentChatRuntime` is the boundary. Your runtime streams normalized events;
+Agent-Native renders the composer, transcript, tool calls, approvals, native
+widgets, and app layout.
+
+```tsx
+import {
+  AssistantChat,
+  createHttpAgentChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const runtime = createHttpAgentChatRuntime({
+  id: "external:support-agent",
+  label: "Support agent",
+  endpoint: "/api/support-agent/chat",
+  headers: async () => ({ Authorization: `Bearer ${await getToken()}` }),
+});
+
+export function SupportAgentChat() {
+  return <AssistantChat runtime={runtime} threadId="support" />;
+}
+```
+
+The endpoint can stream SSE or NDJSON events:
+
+```txt
+data: {"type":"message-delta","messageId":"m1","delta":{"type":"text","text":"I found 34 submissions."}}
+data: {"type":"tool-start","toolCall":{"id":"t1","name":"query","input":{"formId":"form_123"}}}
+data: {"type":"tool-done","toolCallId":"t1","toolName":"query","status":"completed","resultText":"34 rows"}
+data: {"type":"done","reason":"complete"}
+```
+
+For a trivial integration, returning `{ "text": "..." }` also works. For richer
+integrations, stream `message-*`, `tool-*`, `approval-request`, `status`,
+`artifact`, `file`, `usage`, `error`, and `done` events. Tool results can carry
+`chatUI` metadata so the same native table/chart/card renderers work with your
+agent too.
+
+This is the right place to adapt Mastra, Flue, Eve, LangGraph, a custom service,
+or an AG-UI-compatible event stream. Do not use ACP as the default end-user app
+chat protocol; ACP is better framed as coding-agent/editor interoperability.
+Agent-Native does not currently claim A2UI support.
+
+## Embedded sidecar {#embedded-sidecar}
+
+Use the embedded sidecar when the main product already exists and you want an
+agent beside it.
+
+The server plugin mounts Agent-Native routes into your host app and resolves
+host identity server-side:
+
+```ts
+import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server";
+
+export default createAgentNativeEmbeddedPlugin({
+  databaseUrl: process.env.AGENT_NATIVE_DATABASE_URL,
+  auth: getHostSession,
+  actions: hostActions,
+});
+```
+
+The React sidecar passes page context and host commands:
+
+```tsx
+import { AgentNativeEmbedded } from "@agent-native/core/client";
+
+export function AppShell({ children }) {
+  return (
+    <AgentNativeEmbedded
+      getContext={() => ({
+        route: { pathname: window.location.pathname },
+        selection: { text: window.getSelection()?.toString() || undefined },
+      })}
+      onNavigate={(payload) =>
+        router.navigate((payload as { path: string }).path)
+      }
+      onRefresh={() => queryClient.invalidateQueries()}
+    >
+      {children}
+    </AgentNativeEmbedded>
+  );
+}
+```
+
+See [Embedding SDK](/docs/embedding-sdk) for host auth, database isolation,
+iframe/picker mode, and lower-level bridge APIs.
+
+## Full application {#full-application}
+
+Use the full app path when users need durable objects and workflows: forms,
+dashboards, calendars, inboxes, editors, documents, assets, or reports.
+
+Full apps add product UI around the same action and agent contract:
+
+- **SQL state** — app data, navigation, settings, and chat history are durable.
+- **Context awareness** — the agent knows the current route, selection, and focused object.
+- **Live sync** — agent changes update the UI, and UI changes update the agent's context.
+- **Deep links** — action results can open the right app view.
+- **Native chat widgets** — tables, charts, cards, approvals, and typed results appear inline.
+
+Start from a [template](/docs/cloneable-saas) when you want a complete app, or
+from [Starter](/docs/template-starter) when you want only the framework wiring.
+
+## How to choose {#how-to-choose}
+
+| If you are thinking...                                          | Choose                    |
+| --------------------------------------------------------------- | ------------------------- |
+| "I just need a callable tool or workflow."                      | Headless action           |
+| "I want the framework's agent, but chat should be the main UI." | Rich chat on Agent-Native |
+| "I already have an agent; I need a polished chat UI for it."    | Rich chat on your agent   |
+| "I already have a SaaS app; add an agent beside it."            | Embedded sidecar          |
+| "The agent and UI should evolve together as the product."       | Full application          |
+
+Keep the contract small: define durable operations as actions, return explicit
+widget results when chat needs rich UI, and add full screens only when users
+need to browse, compare, configure, or collaborate over persistent objects.
+
+## Related docs {#related-docs}
+
+- [Actions](/docs/actions) — define the headless operation once.
+- [Native Chat UI](/docs/native-chat-ui) — render typed action results in chat.
+- [Drop-in Agent](/docs/drop-in-agent) — mount chat, sidebar, or panel surfaces.
+- [Component API](/docs/components) — lower-level React chat/composer pieces.
+- [Embedding SDK](/docs/embedding-sdk) — add Agent-Native to an existing app.
+- [External Agents](/docs/external-agents) — connect MCP-compatible hosts to an app.
+- [A2A Protocol](/docs/a2a-protocol) — call agents from other agents.

package/docs/content/components.md

@@ -27,23 +27,26 @@ so bundlers choose the browser-safe entry.
 
 ## Agent And Chat UI {#agent-chat-ui}
 
-| API                        | Import path                                   | Use when                                                                                         |
-| -------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `<AgentSidebar>`           | `@agent-native/core/client` or `/client/chat` | You want the complete sidebar around your app.                                                   |
-| `<AgentToggleButton>`      | `@agent-native/core/client` or `/client/chat` | You render your own header button for the sidebar.                                               |
-| `<AgentPanel>`             | `@agent-native/core/client` or `/client/chat` | You want the full panel in your own layout, route, dialog, or side column.                       |
-| `<AgentChatSurface>`       | `@agent-native/core/client` or `/client/chat` | You want chat in panel or page mode without the sidebar wrapper.                                 |
-| `<AssistantChat>`          | `@agent-native/core/client` or `/client/chat` | You want to own surrounding chrome while keeping the standard conversation and composer runtime. |
-| `<MultiTabAssistantChat>`  | `@agent-native/core/client` or `/client/chat` | You want the framework's thread tabs without `AgentPanel` chrome.                                |
-| `createAgentChatAdapter()` | `@agent-native/core/client` or `/client/chat` | You are adapting a BYO assistant-ui transport into the Agent-Native chat runtime.                |
-| `useChatThreads()`         | `@agent-native/core/client` or `/client/chat` | You need a custom thread list, history picker, or scoped chat UI.                                |
-| `sendToAgentChat()`        | `@agent-native/core/client` or `/client/chat` | A product action should hand work to the agent chat.                                             |
-
-In docs, `AgentChatRuntime` means this standard runtime posture: assistant-ui
-thread state, Agent-Native streaming, run recovery, attachments, model
-selection, approvals, native tool widgets, and SQL-backed sync. It is not a
-separate protocol replacement. BYO agents should adapt into this runtime with
-`createAgentChatAdapter()` when they want the normal app chat experience.
+| API                               | Import path                                   | Use when                                                                                         |
+| --------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `<AgentSidebar>`                  | `@agent-native/core/client` or `/client/chat` | You want the complete sidebar around your app.                                                   |
+| `<AgentToggleButton>`             | `@agent-native/core/client` or `/client/chat` | You render your own header button for the sidebar.                                               |
+| `<AgentPanel>`                    | `@agent-native/core/client` or `/client/chat` | You want the full panel in your own layout, route, dialog, or side column.                       |
+| `<AgentChatSurface>`              | `@agent-native/core/client` or `/client/chat` | You want chat in panel or page mode without the sidebar wrapper.                                 |
+| `<AssistantChat>`                 | `@agent-native/core/client` or `/client/chat` | You want to own surrounding chrome while keeping the standard conversation and composer runtime. |
+| `<MultiTabAssistantChat>`         | `@agent-native/core/client` or `/client/chat` | You want the framework's thread tabs without `AgentPanel` chrome.                                |
+| `createHttpAgentChatRuntime()`    | `@agent-native/core/client` or `/client/chat` | You have a BYO agent endpoint that streams normalized chat events.                               |
+| `createAgentChatRuntimeAdapter()` | `@agent-native/core/client` or `/client/chat` | You need to adapt an `AgentChatRuntime` into assistant-ui yourself.                              |
+| `createAgentChatAdapter()`        | `@agent-native/core/client` or `/client/chat` | You need the built-in Agent-Native SSE transport as a low-level assistant-ui adapter.            |
+| `useChatThreads()`                | `@agent-native/core/client` or `/client/chat` | You need a custom thread list, history picker, or scoped chat UI.                                |
+| `sendToAgentChat()`               | `@agent-native/core/client` or `/client/chat` | A product action should hand work to the agent chat.                                             |
+
+`AgentChatRuntime` is the BYO-agent contract for the standard chat shell. Pass
+`runtime` to `<AssistantChat>` when an external agent should power the
+conversation while Agent-Native keeps the composer, transcript, tool cards, and
+native widget rendering. If you are choosing between headless actions, rich
+chat, embedded sidecar, and full app shapes, see
+[Agent Surfaces](/docs/agent-surfaces).
 
 The shortest custom route is still a pre-wired surface:
 
@@ -77,6 +80,24 @@ function CustomChat({ projectSlug }: { projectSlug: string }) {
 }
 ```
 
+For a bring-your-own agent endpoint:
+
+```tsx
+import {
+  AssistantChat,
+  createHttpAgentChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const runtime = createHttpAgentChatRuntime({
+  endpoint: "/api/my-agent/chat",
+  label: "My agent",
+});
+
+export function MyAgentChat() {
+  return <AssistantChat runtime={runtime} />;
+}
+```
+
 ## Chat Field And Composer {#composer}
 
 Use `@agent-native/core/client/composer` when you need to place the same chat

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

@@ -184,20 +184,25 @@ framework own the agent runtime:
 - **`@agent-native/core/client/conversation`** — use this for transcript
   rendering without the full chat runtime.
 - **`createAgentChatAdapter()`** — use this only when building a custom
-  assistant-ui transport for the standard Agent-Native chat runtime. It
+  assistant-ui transport for the built-in Agent-Native chat endpoint. It
   connects to the same `/_agent-native/agent-chat` stream and preserves
   run-manager recovery, attachments, model selection, native widgets, and
   thread metadata.
+- **`createHttpAgentChatRuntime()`** — use this when a BYO agent exposes a
+  POST endpoint that streams `AgentChatRuntime` events. Pass the runtime to
+  `<AssistantChat runtime={runtime} />`.
 
 Avoid posting directly to `/_agent-native/agent-chat` from product UI. If a
 lower-level helper is missing for a real custom surface, add that named helper
 first so client code does not learn a second, ad hoc transport.
 
 For BYO agent runtimes, keep actions and SQL-backed app state as the contract.
-Adapt the runtime into `<AssistantChat createAdapter={...} />` when you want
-Agent-Native chat behavior, or use `PromptComposer` by itself only when the
-external runtime owns the transcript and loop. See
-[Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes).
+Adapt the runtime into `<AssistantChat runtime={...} />` when you want
+Agent-Native chat behavior. Use `<AssistantChat createAdapter={...} />` only
+for lower-level assistant-ui transports, or `PromptComposer` by itself only
+when the external runtime owns the transcript and loop. See
+[Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes) and
+[Agent Surfaces](/docs/agent-surfaces#byo-agent).
 
 ### Build your own sidebar from pieces {#build-your-own-sidebar}
 

package/docs/content/embedding-sdk.md

@@ -29,6 +29,10 @@ pnpm add @agent-native/core
 
 ## Choosing a mode {#choosing-a-mode}
 
+This page is for embedding Agent-Native into an existing product. If you are
+still deciding between headless actions, rich chat, an embedded sidecar, or a
+full app, start with [Agent Surfaces](/docs/agent-surfaces).
+
 | Mode                                 | Use it when                                                                                         | Package                                                  |
 | ------------------------------------ | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
 | **EmbeddedApp picker**               | Launching a full Agent-Native app as a focused iframe (asset picker, form builder, approval panel). | `@agent-native/embedding`                                |

package/docs/content/external-agents.md

@@ -13,6 +13,7 @@ The external-agent bridge closes the loop. First you connect your own agent to a
 ## Which agent path do you need? {#which-agent-path}
 
 - **External MCP host:** use this page when Claude, ChatGPT, Codex, Cursor, OpenCode, GitHub Copilot / VS Code, or another MCP-compatible host should call your hosted agent-native app.
+- **Your own runtime behind Agent-Native chat:** see [Agent Surfaces](/docs/agent-surfaces#byo-agent) and [Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes) when an agent built with another framework should power `<AssistantChat runtime={...}>`.
 - **Your app consuming MCP tools:** see [MCP Clients](/docs/mcp-clients) when an agent-native app needs to call tools exposed by another MCP server.
 - **Another app or agent via A2A:** use [Agent Mentions](/docs/agent-mentions) and [A2A](/docs/a2a-protocol) when agent-native apps should discover and delegate to each other.
 - **Local custom sub-agents:** use [Workspace](/docs/workspace) when you want custom agent profiles inside the agent-native workspace itself.

package/docs/content/getting-started.md

@@ -13,6 +13,7 @@ Start with the path that matches what you want to do next:
 
 - **Use a starter app.** Browse the [template gallery](/templates). Hosted apps already include sign-in, data, and the agent sidebar. No install required.
 - **Build or customize your own app.** Continue with [Create a local app](#create-your-app). You'll scaffold a template, run it locally, then change the code, brand, data model, and integrations.
+- **Choose headless, chat, embedded, or full app.** Use [Agent Surfaces](/docs/agent-surfaces) when you know the workflow but not how much UI belongs around it.
 - **Add agent-native skills to a code tool.** Jump to [Try it with a skill](#try-with-a-skill) to add Plans or PR Recaps to Claude Code, Codex, or Cursor without scaffolding an app.
 - **Connect an external agent to an app.** Use [External Agents](/docs/external-agents) to connect Claude, ChatGPT, Codex, Cursor, OpenCode, GitHub Copilot / VS Code, or another MCP host to an existing app.
 
@@ -122,6 +123,7 @@ Once your app is running, the usual next step is small and concrete:
 Useful follow-up docs:
 
 - [Key Concepts](/docs/key-concepts) for the architecture: SQL, actions, polling sync, and context awareness
+- [Agent Surfaces](/docs/agent-surfaces) for choosing headless, rich chat, embedded sidecar, or full app
 - [Workspace](/docs/workspace) for instructions, skills, memory, and per-user MCP connections
 - [Messaging](/docs/messaging) for Slack, email, Telegram, and other ways to reach the agent
 - [FAQ](/docs/faq) for setup and product questions

package/docs/content/key-concepts.md

@@ -194,7 +194,7 @@ Agent-native supports a lot of agent-facing protocols because different hosts st
 | ----------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
 | Agent tool calling      | Shipping            | The in-app agent sees actions as function tools with zod-derived JSON Schema.                                                   | `defineAction()`                        |
 | UI actions              | Shipping            | React calls the same action through `useActionMutation()` / `useActionQuery()`.                                                 | The same action                         |
-| Native chat widgets     | Shipping            | Tool results with explicit widget discriminants can render native tables, charts, approvals, and setup cards in chat.           | Structured action results               |
+| Native chat widgets     | Shipping            | Tool results with explicit widget discriminants can render native tables, charts, and typed app results in chat.                | Structured action results               |
 | HTTP and CLI            | Shipping            | Actions auto-mount at `/_agent-native/actions/:name` and run via `pnpm action <name>`.                                          | The same action                         |
 | MCP server              | Shipping            | External MCP hosts get Streamable HTTP tools, the `ask-agent` meta-tool, and optional MCP Apps resources.                       | The same action, plus optional `mcpApp` |
 | MCP OAuth               | Shipping            | Standard remote MCP OAuth, PKCE, dynamic client registration, refresh tokens, and `mcp:read` / `mcp:write` / `mcp:apps` scopes. | Nothing per action                      |
@@ -222,7 +222,7 @@ Those protocol adapters let the same app grow across three product shapes:
 | **Rich chat agent**   | A standalone or embedded chat can guide setup, call tools, request approvals, and render native tables/charts/results. | Agent-first workflows that still need inspectable output       |
 | **Whole application** | Chat starts central when helpful, then becomes a sidebar next to forms, dashboards, editors, calendars, or documents.  | Durable products where humans and agents share state over time |
 
-You should be able to start with the headless contract, add rich chat, and then grow a full app around the same actions and SQL state instead of rebuilding.
+You should be able to start with the headless contract, add rich chat, and then grow a full app around the same actions and SQL state instead of rebuilding. See [Agent Surfaces](/docs/agent-surfaces) for the concrete choice guide and APIs.
 
 ## Agent modifies code {#agent-modifies-code}
 
@@ -320,5 +320,6 @@ For detailed guidance on specific patterns:
 - [Context Awareness](/docs/context-awareness) — navigation state, view-screen, navigate commands
 - [Skills Guide](/docs/skills-guide) — framework skills, domain skills, creating custom skills
 - [Native Chat UI](/docs/native-chat-ui) — action-declared tables, charts, and BYO runtime posture
+- [Agent Surfaces](/docs/agent-surfaces) — headless, rich chat, embedded sidecar, and full-app paths
 - [A2A Protocol](/docs/a2a-protocol) — agent-to-agent communication
 - [Multi-App Workspace](/docs/multi-app-workspace) — host many apps in one monorepo with shared auth, skills, components, and credentials

package/docs/content/mcp-apps.md

@@ -9,7 +9,7 @@ MCP Apps are the official `io.modelcontextprotocol/ui` extension that lets compa
 
 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.
 
-Inside an Agent-Native app's own chat, prefer [native chat renderers](/docs/native-chat-ui) for first-party widgets such as tables, charts, setup cards, and approvals. Use MCP Apps for external/cross-host inline UI in Claude, ChatGPT, Copilot, Cursor, and other compatible hosts, with the action `link` as the universal deep-link fallback.
+Inside an Agent-Native app's own chat, prefer [native chat renderers](/docs/native-chat-ui) for first-party widgets such as tables, charts, typed results, and approval affordances. Use MCP Apps for external/cross-host inline UI in Claude, ChatGPT, Copilot, Cursor, and other compatible hosts, with the action `link` as the universal deep-link fallback.
 
 ## Authoring: optional MCP Apps UI {#mcp-apps}
 

package/docs/content/native-chat-ui.md

@@ -178,32 +178,79 @@ arbitrary query execution behind typed read actions rather than raw SQL in chat.
 
 ## BYO agent runtimes {#byo-agent-runtimes}
 
-Agent-Native ships the chat/runtime stack: thread persistence, streaming,
-attachments, tool calls, run recovery, approvals, suggestions, native widgets,
-and SQL-backed app state. In docs, `AgentChatRuntime` refers to that standard
-runtime posture, not a separate package you need to replace.
-
-For bring-your-own agent work, keep the action surface and app state as the
-contract:
-
-- Use `createAgentChatAdapter()` or the `<AssistantChat createAdapter={...} />`
-  prop when you need a custom assistant-ui transport while keeping the standard
-  chat runtime.
-- Use `PromptComposer` only when your product owns the full external runtime
-  and wants the Agent-Native composer field without the standard transcript.
-- Treat AG-UI as the likely adapter shape for external event-stream runtimes.
-  It should adapt into Agent-Native actions, context, and native renderers
-  rather than creating a second app API.
-- Treat ACP as coding-agent/editor interoperability. It is useful for IDE
-  agents, but it is not the general BYO chat runtime contract for app users.
-
-The goal is one operation model: actions, SQL state, context awareness, native
-widgets, MCP Apps, A2A, and MCP all wrap the same app capabilities instead of
-forking behavior per agent surface.
+`AgentChatRuntime` is the bring-your-own-agent contract for the chat shell. It
+lets an agent you built elsewhere stream normalized events into Agent-Native's
+conversation UI while keeping the shared composer, transcript rendering, tool
+cards, approvals, native widgets, and surrounding app layout. For how this fits
+with headless actions, embedded sidecars, and full applications, see
+[Agent Surfaces](/docs/agent-surfaces).
+
+Use the generic HTTP runtime when your agent can expose a POST endpoint that
+returns SSE or NDJSON runtime events:
+
+```tsx
+import {
+  AssistantChat,
+  createHttpAgentChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const runtime = createHttpAgentChatRuntime({
+  id: "external:mastra",
+  label: "Mastra",
+  endpoint: "/api/mastra/chat",
+  headers: async () => ({
+    Authorization: `Bearer ${await getAgentToken()}`,
+  }),
+});
+
+export function SupportChat() {
+  return <AssistantChat runtime={runtime} threadId="support" />;
+}
+```
+
+The endpoint may stream the normalized event shape directly:
+
+```txt
+data: {"type":"message-start","message":{"id":"m1","role":"assistant","content":[]}}
+data: {"type":"message-delta","messageId":"m1","delta":{"type":"text","text":"Hello"}}
+data: {"type":"tool-start","toolCall":{"id":"t1","name":"query","input":{"q":"forms"}}}
+data: {"type":"tool-done","toolCallId":"t1","toolName":"query","status":"completed","resultText":"34 rows"}
+data: {"type":"done","reason":"complete"}
+```
+
+For very simple agents, a JSON response `{ "text": "..." }` is accepted and
+converted into a single assistant message. For richer agents, stream
+`message-*`, `tool-*`, `approval-request`, `status`, `artifact`, `file`,
+`usage`, `error`, and `done` events. Tool results can carry `mcpApp` or
+`chatUI` metadata, so action-declared native widgets still render without
+iframes.
+
+When you want the built-in Agent-Native transport as a runtime object, use:
+
+```ts
+import { createAgentNativeChatRuntime } from "@agent-native/core/client/chat";
+
+const runtime = createAgentNativeChatRuntime({
+  threadId: "forms-chat",
+  mode: "act",
+});
+```
+
+Use `<AssistantChat createAdapter={...} />` only when you need full
+assistant-ui adapter control. Use `PromptComposer` by itself when your product
+owns the entire external transcript and only wants Agent-Native's composer
+field.
+
+AG-UI is still an adapter target: it can be mapped into `AgentChatRuntime`
+events, actions, context, and native renderers over time. 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}
 
 - [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.
 - [Drop-in Agent](/docs/drop-in-agent) — mount the standard chat runtime.
 - [Component API](/docs/components) — custom chat layers and tool renderers.
 - [MCP Apps](/docs/mcp-apps) — inline UI for external MCP hosts.

package/docs/content/plan-plugin.md

@@ -37,9 +37,35 @@ the Plan MCP connector. They write `plans/<slug>/plan.mdx` plus optional
 `canvas.mdx`, `prototype.mdx`, and `.plan-state.json`, then preview locally with:
 
 ```bash
-npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind plan --open
+npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan --open
 ```
 
+This starts a tiny localhost bridge and opens the Plan UI against the local
+folder. (`plan local preview` runs a local Plan dev-server route instead, and
+`plan local preview --out preview.html` is a legacy escape hatch that writes a
+standalone static HTML file. `plan serve` is accepted as a short alias for
+`plan local serve`.)
+
+A few local-files-mode gotchas worth knowing:
+
+- **Use a Chromium browser.** Safari blocks the hosted HTTPS Plan page from
+  reading the `http://127.0.0.1` localhost bridge (mixed-content / private
+  network), so the page hangs on "Loading plan." On macOS `--open` already
+  prefers Chrome/Chromium/Edge/Brave; if Safari opens anyway, reopen the printed
+  URL in a Chromium browser.
+- **The served URL is written to `plans/<slug>/.plan-url`** (override with
+  `--url-file`). A backgrounded or headless agent can read that file instead of
+  scraping the long-running `serve` stdout. Treat it as a local token file and
+  do not commit it.
+- **Verify headlessly** when no browser is available:
+  `npx @agent-native/core@latest plan local verify --dir plans/<slug>` starts the
+  bridge, checks the private-network preflight and JSON payload, prints
+  diagnostics, and exits non-zero on failure — no human eyes required.
+- **Run `plan local check` first.** It validates the MDX against the Plan
+  renderer's block schema (including required fields like `checklist` item
+  `id`/`label` and `question-form` question `id`/`title`/`mode`), so authoring
+  mistakes surface before the browser handoff instead of as a stuck loader.
+
 For folders in the current repo, the direct local route includes `?path=...` so
 the local Plan app can keep browser edits saving to the repo folder. The Plan
 app uses `apps.plan.roots[0].path` in `agent-native.json` as the default place

package/docs/content/pure-agent-apps.md

@@ -5,7 +5,7 @@ description: "Apps where the agent is the whole product — open it, ask for wha
 
 # Pure-Agent Apps
 
-This is the minimal end of agent-native — for the full-UI end, start from a [template](/docs/cloneable-saas).
+This is the minimal end of agent-native — for the full-UI end, start from a [template](/docs/cloneable-saas). If you are choosing between headless, chat-first, embedded, and full-app shapes, start with [Agent Surfaces](/docs/agent-surfaces).
 
 Imagine opening an app and seeing… just a chat. No dashboard. No sidebar full of menus. No forms. You ask for what you want — "summarize my unread emails," "post the daily metrics to Slack," "find the candidates who replied last week" — and the agent goes off and does it. The output shows up in chat, in Slack, in your inbox, wherever it belongs.
 
@@ -90,6 +90,7 @@ Most pure-agent apps eventually want a little custom UI — not a dashboard, but
 ## What's next
 
 - [**Getting Started**](/docs/getting-started) — clone the Starter template
+- [**Agent Surfaces**](/docs/agent-surfaces) — choose headless, rich chat, embedded sidecar, or full app
 - [**Messaging the agent**](/docs/messaging) — how users talk to the agent across web, Slack, Telegram, email
 - [**Recurring Jobs**](/docs/recurring-jobs) — scheduled prompts the agent runs on its own
 - [**Dispatch**](/docs/template-dispatch) — the workspace template that's a great starting point for pure-agent apps

package/docs/content/using-your-agent.md

@@ -39,6 +39,7 @@ _For developers building the app._
 The agent isn't a separate app you tab over to. It ships as a handful of React components — a sidebar, a raw panel, and a `sendToAgentChat()` call — that you drop into any app. Render `<AgentSidebar>` to give every screen a toggleable agent, or wire a button to hand a specific task off to the chat instead of running a one-shot LLM call.
 
 → [**Drop-in Agent**](/docs/drop-in-agent) — mount `<AgentPanel>`, `<AgentSidebar>`, and `sendToAgentChat()` into any React app. _(For developers building the app.)_
+→ [**Agent Surfaces**](/docs/agent-surfaces) — choose whether the workflow should be headless, chat-first, embedded, or a full app. _(For developers designing the product shape.)_
 
 ## You can go UI-light {#ui-light}
 

package/docs/content/what-is-agent-native.md

@@ -66,10 +66,10 @@ At minimum, "a UI for the agent" is an observability and management dashboard. A
 There are three useful shapes:
 
 - **Headless** — call the agent and actions from code, HTTP, CLI, MCP, or A2A.
-- **Rich chat** — give the agent a first-class chat UI with native tool widgets such as tables, charts, approvals, setup cards, and links into app views. See [Native Chat UI](/docs/native-chat-ui).
+- **Rich chat** — give the agent a first-class chat UI with native tool widgets such as tables, charts, typed results, approvals, and links into app views. See [Native Chat UI](/docs/native-chat-ui).
 - **Whole app** — put a full application around the agent, with SQL state, context awareness, deep links, and live sync so humans and agents stay in the same workspace.
 
-Agent-native is designed so those are stages, not rewrites. You can start headless, add rich chat, and grow into a full app around the same action surface.
+Agent-native is designed so those are stages, not rewrites. You can start headless, add rich chat, and grow into a full app around the same action surface. See [Agent Surfaces](/docs/agent-surfaces) for the concrete APIs behind each shape.
 
 ## Why every app benefits from an agent {#why-every-app-benefits-from-an-agent}
 
@@ -186,6 +186,7 @@ One action, many surfaces: the agent calls it as a tool, the UI calls it as a ty
 ## What's next {#whats-next}
 
 - [**Getting Started**](/docs) — pick a template and run it
+- [**Agent Surfaces**](/docs/agent-surfaces) — choose headless, rich chat, embedded sidecar, or full app
 - [**Key Concepts**](/docs/key-concepts) — the architecture: SQL, actions, polling sync, context awareness, portability
 - [**Templates**](/docs/cloneable-saas) — templates as complete products you own
 - [**Workspace**](/docs/workspace) — the per-user customization layer (skills, memory, instructions, MCP) backed by SQL, not files