@agent-native/core 0.55.0 → 0.56.0

package/docs/content/actions.md

@@ -305,6 +305,58 @@ const { data, isLoading } = useActionQuery("get-lead", { leadId });
 
 The query is cached under `["action", "get-lead", { leadId }]` and auto-invalidated on any mutating action that completes.
 
+## Rendering native chat UI {#native-chat-ui}
+
+Actions can return structured widget data that the in-app chat renders
+natively. This is the first-party chat path for reusable tables, charts, setup
+summaries, and insight cards; use [MCP Apps](/docs/mcp-apps) for inline UI in
+external MCP hosts.
+
+```ts
+import {
+  ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER,
+  dataInsightsWidgetResultSchema,
+  defineAction,
+} from "@agent-native/core";
+import { createDataInsightsWidgetResult } from "@agent-native/core/data-widgets";
+
+export default defineAction({
+  description: "Summarize response trends.",
+  readOnly: true,
+  outputSchema: dataInsightsWidgetResultSchema,
+  chatUI: { renderer: ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER },
+  run: async () =>
+    createDataInsightsWidgetResult({
+      title: "Response trends",
+      chartSeries: {
+        type: "line",
+        xKey: "day",
+        series: [{ key: "responses", label: "Responses" }],
+        data: [
+          { day: "Mon", responses: 12 },
+          { day: "Tue", responses: 18 },
+        ],
+      },
+      table: {
+        columns: [
+          { key: "day", label: "Day" },
+          { key: "responses", label: "Responses", align: "right" },
+        ],
+        rows: [
+          { day: "Mon", responses: 12 },
+          { day: "Tue", responses: 18 },
+        ],
+      },
+    }),
+});
+```
+
+The built-in discriminants are `"data-table"`, `"data-chart"`, and
+`"data-insights"`. Their server-safe builders and schemas are exported from
+`@agent-native/core/data-widgets`, and native renderer ids are exported from
+`@agent-native/core`. See [Native Chat UI](/docs/native-chat-ui) for the full
+result contract and BYO runtime guidance.
+
 ## Calling it from the CLI {#cli}
 
 Every action is runnable via `pnpm action`:

package/docs/content/components.md

@@ -35,10 +35,16 @@ so bundlers choose the browser-safe entry.
 | `<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 building a custom assistant-ui runtime and need the Agent-Native chat transport.         |
+| `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.
+
 The shortest custom route is still a pre-wired surface:
 
 ```tsx
@@ -116,6 +122,23 @@ This layer is intentionally data-first: you own where messages come from, and
 the renderer owns consistent markdown, attachments, notices, artifacts, and
 tool-call display.
 
+## Native Tool Widgets {#native-tool-widgets}
+
+Use native tool widgets when an action result should render as app-quality UI
+inside chat instead of plain JSON. Built-in reusable outputs include
+`DataTableWidget`, `DataChartWidget`, and `DataWidgetResult`; they are exported
+from `@agent-native/core/client/chat` and the root client entry. See
+[Native Chat UI](/docs/native-chat-ui) for the action result contract.
+
+| API                              | Use when                                                                                |
+| -------------------------------- | --------------------------------------------------------------------------------------- |
+| `DataTableWidget`                | You want an action result to render rows and columns in native chat.                    |
+| `DataChartWidget`                | You want compact bar, line, or area chart output in native chat.                        |
+| `DataWidgetResult`               | You want a typed result shape for `"data-table"`, `"data-chart"`, or `"data-insights"`. |
+| `registerActionChatRenderer()`   | You need an action-declared renderer selected by exact `chatUI.renderer`.               |
+| `registerToolRenderer()`         | You need a product-specific native renderer for a non-core tool result.                 |
+| `registerReservedToolRenderer()` | Framework code needs a reserved renderer that wins before template renderers.           |
+
 ## Realtime Collab And Presence {#collab-presence}
 
 Use `@agent-native/core/client/collab` for Liveblocks-style presence and

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

@@ -184,14 +184,21 @@ 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 runtime. It connects to the same `/_agent-native/agent-chat`
-  stream and preserves run-manager recovery, attachments, model selection, and
+  assistant-ui transport for the standard Agent-Native chat runtime. It
+  connects to the same `/_agent-native/agent-chat` stream and preserves
+  run-manager recovery, attachments, model selection, native widgets, and
   thread metadata.
 
 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).
+
 ### Build your own sidebar from pieces {#build-your-own-sidebar}
 
 The stock sidebar is optional. This example builds the agent-side UI itself.

package/docs/content/faq.md

@@ -15,11 +15,12 @@ Agent-native is a framework for building apps where the AI agent and the UI are
 
 ### Who is this for? {#who-is-this-for}
 
-Anyone who wants to ship an AI-powered product without spending a year building the boring parts. That includes:
+Agent-native is for people who want a real app and an AI agent to work from the same data and actions. The common paths are:
 
-- **Founders and PMs** who want to fork a working SaaS and make it their own — see [Templates](/docs/cloneable-saas).
-- **Operators** who want a [pure-agent app](/docs/pure-agent-apps) — an agent that does work in the background with a minimal management UI.
-- **Developers** building agent-driven products from scratch and want auth, multi-tenancy, real-time sync, and an architecture that won't break when AI is the primary user.
+- **Use a hosted app** if you want Mail, Calendar, Forms, Plan, or another finished template with no setup — start at the [template gallery](/templates).
+- **Fork and customize a template** if you want your own SaaS product with auth, database, UI, and agent actions already wired — see [Templates](/docs/cloneable-saas).
+- **Build from scratch** if you want the framework primitives for a new agent-driven product — start with [Getting Started](/docs/getting-started).
+- **Connect another agent or code tool** if you want Claude, ChatGPT, Codex, Cursor, or GitHub Copilot / VS Code to use an agent-native app — see [External Agents](/docs/external-agents) and [Skills Guide](/docs/skills-guide).
 
 ### How is this different from adding AI to an existing app? {#how-is-this-different}
 

package/docs/content/getting-started.md

@@ -1,26 +1,26 @@
 ---
 title: "Getting Started"
-description: "Pick a template, create your app, and start customizing it with AI."
+description: "Choose the right path: hosted apps, local setup, agent-native skills, or external-agent connections."
 ---
 
 # Getting Started
 
-By the end of this page, you'll have a working app — Mail, Calendar, Forms, or any other template — running with an AI agent built into the sidebar that can drive every part of it.
+Agent-Native is for apps where a real UI and an AI agent share the same actions, data, and state. This page helps you choose the right starting point, then walks through the local setup path.
 
-## Who is this for? {#who-is-this-for}
+## Pick your path {#who-is-this-for}
 
-There are two ways to use agent-native, depending on how hands-on you want to be:
+Start with the path that matches what you want to do next:
 
-- **You want to use a hosted version.** Try a template right now at [agent-native.com/templates](/templates). Each template is a live, hosted app — you sign in, start using it, and the agent is already there. No install, no setup. You can stop reading this page and head straight to the [template gallery](/templates).
-- **You want to run locally or customize it.** You'll clone a template, run it on your machine, and shape it however you want — branding, features, integrations. The rest of this page is for you. You'll need [Node.js 22 or newer (LTS recommended)](https://nodejs.org) and [pnpm](https://pnpm.io) installed.
-- **You just want to add agent-native to your existing coding agent.** Skip the scaffold entirely — install a skill into Claude Code, Codex, or Cursor with one command. Jump to [Try it with a skill](#try-with-a-skill).
-- **You want your existing agent to call an agent-native app.** Connect Claude, ChatGPT, Codex, Cursor, OpenCode, GitHub Copilot / VS Code, or another MCP host through [External Agents](/docs/external-agents).
+- **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.
+- **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.
 
-Not sure which path? If you've never written code, the hosted version is for you. If you have a developer or AI coding tool ready, the local path gives you total control.
+If you're not sure, use the hosted app when you want to use software now. Use the local path when you want to own and change the software.
 
-## First run {#create-your-app}
+## Create a local app {#create-your-app}
 
-Three commands and you're up:
+You'll need [Node.js 22 or newer](https://nodejs.org) and [pnpm](https://pnpm.io) installed. Then run:
 
 ```bash
 npx @agent-native/core@latest create my-platform
@@ -28,7 +28,7 @@ cd my-platform
 pnpm install && pnpm dev
 ```
 
-The `create` command defaults to a workspace monorepo. It shows a multi-select picker — pick one template or several (Mail + Calendar + Forms, for example) and they all scaffold into one workspace sharing auth, brand, and agent config. If you want one app directory instead, pass `--standalone`.
+The `create` command opens a template picker. Pick one template for a single app, or pick several templates to create a workspace where the apps share auth, brand, and agent configuration. If you want one app directory instead of a workspace, pass `--standalone`.
 
 Open the URL the dev server prints. The workspace gateway always starts on port 8080 and serves every app through it; individual apps run on their own ports that are printed at startup. Standalone apps default to `http://localhost:3000`.
 
@@ -38,46 +38,27 @@ In local development the embedded agent panel picks up your existing Claude Code
 
 ## What just happened? {#what-just-happened}
 
-You now have a real, full-featured app running on your machine. Open it in the browser and try it:
+You now have a real app running on your machine with an agent built into it:
 
-- Click around the UI like you would any SaaS product.
-- Open the agent panel on the right side. Type something like "show me my settings" or "create a new entry called Welcome." Watch the agent click through the app on your behalf.
-- Anything you do by clicking, the agent can do by reading and writing the same database. Anything the agent does shows up in the UI immediately.
+- The UI works like a normal SaaS product: routes, forms, tables, settings, and keyboard flows.
+- The agent panel can read the current screen and run the same actions the UI runs.
+- Changes stay in sync because the UI and agent share the same database and application state.
 
 That parity between agent and UI is the whole point — see [What Is Agent-Native?](/docs/what-is-agent-native) for the bigger picture.
 
-## Templates {#templates}
+## Pick a template {#templates}
 
-Each template is a complete app with UI, agent actions, database schema, and AI instructions ready to go:
+Templates are complete apps, not blank starters. Choose one when you want a familiar product to customize:
 
-| Template                              | What it is                                                            |
-| ------------------------------------- | --------------------------------------------------------------------- |
-| [Calendar](/docs/template-calendar)   | Agent-native Google Calendar + Calendly-style booking                 |
-| [Content](/docs/template-content)     | Open-source Obsidian for MDX                                          |
-| [Brain](/docs/template-brain)         | Company chat with cited institutional memory                          |
-| [Assets](/docs/template-assets)       | Brand asset libraries and generated media                             |
-| [Slides](/docs/template-slides)       | Agent-native Google Slides / Pitch                                    |
-| [Video](/docs/template-videos)        | Programmatic motion graphics and product-demo videos on Remotion      |
-| [Analytics](/docs/template-analytics) | Agent-native Amplitude / Mixpanel                                     |
-| [Mail](/docs/template-mail)           | Agent-native Superhuman / Gmail                                       |
-| [Clips](/docs/template-clips)         | Async screen + camera recording with transcription and AI summaries   |
-| [Design](/docs/template-design)       | Agent-native HTML prototyping studio                                  |
-| [Forms](/docs/template-forms)         | Agent-native Typeform                                                 |
-| [Plan](/docs/template-plan)           | Visual plans and PR recaps with diagrams, wireframes, and annotations |
-| [Dispatch](/docs/template-dispatch)   | Workspace control plane — shared secrets, integrations, routing       |
+- **Productivity apps** — [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Content](/docs/template-content), [Slides](/docs/template-slides), [Design](/docs/template-design), [Clips](/docs/template-clips), and [Video](/docs/template-videos)
+- **Team and data apps** — [Analytics](/docs/template-analytics), [Brain](/docs/template-brain), [Dispatch](/docs/template-dispatch), [Assets](/docs/template-assets), and [Plan](/docs/template-plan)
+- **Bare starting point** — [Starter](/docs/template-starter), a minimal app with the framework wiring and no domain model
 
-Browse the [template gallery](/templates) for live demos, or see [Templates](/docs/cloneable-saas) for the full catalog and the clone → customize → deploy flow.
+Browse the [template gallery](/templates) for live hosted apps. See [Templates](/docs/cloneable-saas) for the full catalog and the clone → customize → deploy flow.
 
-## Creating vs adding apps {#creating-vs-adding-apps}
+## Add more apps to a workspace {#creating-vs-adding-apps}
 
-Run `create` from the folder where you want a brand-new workspace:
-
-```bash
-cd ~/projects
-npx @agent-native/core@latest create my-platform
-```
-
-After a workspace exists, run app commands from the workspace root:
+`create` (above) makes a brand-new workspace. Once you have one, add more apps to it with `add-app`, run from the workspace root:
 
 ```bash
 cd my-platform
@@ -86,9 +67,9 @@ pnpm install
 pnpm dev
 ```
 
-If your terminal is inside `apps/content` or another app folder, the CLI still detects the workspace and adds the new app as a sibling under `apps/`. Afterward, go back to the workspace root before running `pnpm install` or `pnpm dev`.
+If your terminal is inside `apps/content` or another app folder, the CLI still detects the workspace and adds the new app as a sibling under `apps/`. Go back to the workspace root before running `pnpm install` or `pnpm dev`.
 
-To make a second app from the same template, give it a new app name:
+To add another app from a specific template, pass a name and `--template`:
 
 ```bash
 npx @agent-native/core@latest add-app design-lab --template design
@@ -96,7 +77,7 @@ npx @agent-native/core@latest add-app design-lab --template design
 
 ## Try it with a skill {#try-with-a-skill}
 
-Don't want to scaffold a whole app yet? Add agent-native superpowers to a coding agent you already use — Claude Code, Codex, or Cursor — with a single command. Installing the **Plans** skill turns the plans your agent writes into structured, reviewable docs with diagrams, wireframes, and inline comments:
+Don't want to scaffold an app? Add agent-native capabilities to a coding agent you already use. Installing the **Plans** skill turns the plans your agent writes into structured, reviewable docs with diagrams, wireframes, and inline comments:
 
 ```bash
 npx @agent-native/core@latest skills add visual-plan
@@ -104,6 +85,8 @@ npx @agent-native/core@latest skills add visual-plan
 
 That one command installs the skill instructions, registers the hosted MCP connector, and signs you in — no marketplace browsing, no manual OAuth. Then run `/visual-plan` in your agent. See the [Skills Guide](/docs/skills-guide#app-backed-skills) for more skills, local/offline installs, and how app-backed skills work.
 
+Need the opposite direction, where Claude, ChatGPT, Codex, Cursor, OpenCode, GitHub Copilot / VS Code, or another MCP host calls an agent-native app? Use [External Agents](/docs/external-agents).
+
 ## Project structure {#project-structure}
 
 Every agent-native app — whether from a template or from scratch — follows the same structure:
@@ -118,30 +101,6 @@ my-app/
 
 Templates add domain-specific code on top: database schemas in `server/db/`, API routes in `server/routes/api/`, and actions in `actions/`. Building from scratch? See [Creating Templates](/docs/creating-templates) for `vite.config.ts`, `tsconfig.json`, and Tailwind setup.
 
-## Next docs to read {#next-docs}
-
-Once your app is running, the most useful follow-ups are:
-
-- **Connect Slack or email** so you can message your agent from anywhere — see [Messaging](/docs/messaging).
-- **Set up Dispatch as your central inbox** to triage messages and orchestrate across multiple apps — see [Dispatch](/docs/dispatch).
-- **Customize via Workspace** — edit instructions, skills, memory, and connect MCP servers per user — see [Workspace](/docs/workspace).
-- **Troubleshoot common setup questions** — see the [FAQ](/docs/faq).
-- **Understand the architecture** — see [Key Concepts](/docs/key-concepts) for how SQL, actions, polling sync, and context awareness fit together.
-
-## Try one concrete next step {#first-next-step}
-
-From here, use any AI coding tool (Agent-Native Code, Claude Code, Cursor, Windsurf, Builder.io) to customize the app. The agent instructions in `AGENTS.md` are already set up so any tool understands the codebase.
-
-Good first moves:
-
-- **Open Agent-Native Code** — run `npx @agent-native/core@latest` or `npx @agent-native/core@latest code` from the project. A bare command opens the local Claude Code/Codex-like workspace; a bare prompt such as `npx @agent-native/core@latest "rename the app"` starts a Code task directly.
-- **Ask the built-in agent what it sees** — open the agent panel and type "what app am I looking at, and what can you do here?" This verifies the app, UI state, and agent loop are all talking to each other.
-- **Make a tiny customization** — ask your coding tool to rename the app, change the first screen copy, or add one field to a form. It will read `AGENTS.md` for the framework conventions.
-- **Add another app to the same workspace** — use `npx @agent-native/core@latest add-app` from inside the workspace folder. The command starts at `npx`.
-- **Single app instead of a monorepo?** Pass `--standalone` when creating: `npx @agent-native/core@latest create my-app --standalone --template mail`.
-
-Agent-Native Code understands built-in slash goals such as `/migrate` and `/audit`, plus project commands in `.agents/commands/*.md`. Use `npx @agent-native/core@latest code list`, `status`, `resume`, `stop`, or `ui` to inspect and control the same run from the CLI, the local UI, or the Desktop Code tab.
-
 ## Architecture principles {#architecture-principles}
 
 The three principles that apply to every agent-native app:
@@ -152,25 +111,17 @@ The three principles that apply to every agent-native app:
 
 The definitive six rules are in [Key Concepts](/docs/key-concepts).
 
-## Testing local framework changes {#testing-local-framework-changes}
+## Common next moves {#next-docs}
 
-Framework contributors can scaffold against the current checkout instead of the
-published packages:
+Once your app is running, the usual next step is small and concrete:
 
-```bash
-AGENT_NATIVE_CREATE_USE_LOCAL_CORE=1 pnpm --filter @agent-native/core create my-platform
-```
-
-With that flag, generated workspaces link both the local `@agent-native/core`
-and local `@agent-native/dispatch` packages. Use it when you need to verify
-unpublished template or package changes end-to-end in a freshly generated
-workspace. The packages run their `prepack` build first, so the linked packages
-serve fresh `dist` output instead of stale build artifacts.
+- **Ask the built-in agent what it sees** — open the agent panel and type "what app am I looking at, and what can you do here?" This verifies that the app, UI state, and agent loop are connected.
+- **Make one customization** — rename the app, change the first screen copy, or add a field to a form. The project `AGENTS.md` already tells coding agents how this repo is organized.
+- **Deploy it** — see [Deployment](/docs/deployment) when you're ready to put the app on your own domain.
 
-To exercise the repo-local CLI itself without building first, run it through
-the root script:
+Useful follow-up docs:
 
-```bash
-pnpm dev:cli --help
-pnpm dev:cli code goals
-```
+- [Key Concepts](/docs/key-concepts) for the architecture: SQL, actions, polling sync, and context awareness
+- [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

@@ -190,28 +190,27 @@ See [Context Awareness](/docs/context-awareness) for the full pattern: navigatio
 
 Agent-native supports a lot of agent-facing protocols because different hosts standardize different pieces of the same workflow. App authors should not have to choose among them or rebuild the same operation for each client. The center of gravity stays the action system.
 
-| Surface                 | Status           | What agent-native provides                                                                                             | What you write                          |
-| ----------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
-| 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               |
-| 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 Auth                | Shipping         | Remote MCP OAuth, PKCE, dynamic client registration, refresh tokens, and `mcp:read` / `mcp:write` / `mcp:apps` scopes. | Nothing per action                      |
-| MCP Apps                | Shipping         | External hosts that support app resources can render iframe/native-host widgets, with deep-link fallback elsewhere.    | Optional `mcpApp` metadata              |
-| A2A                     | Shipping         | Other agents discover the agent card and call the app over JSON-RPC tasks.                                             | The same actions and agent config       |
-| Deep links              | Shipping         | Action results can round-trip users into the running UI through `/_agent-native/open` and `agentnative://open`.        | Optional `link` metadata                |
-| MCP clients             | Shipping         | The app can also consume local, remote, or hub-shared MCP servers as `mcp__...` tools.                                 | `mcp.config.json` or settings           |
-| Instructions and skills | Shipping         | `AGENTS.md`, skills, memory, slash commands, sub-agents, jobs, and automations live in the SQL-backed workspace.       | Workspace resources, not protocol glue  |
-| Agent Web               | Shipping         | Public pages can publish `robots.txt`, `sitemap.xml`, `llms.txt`, markdown mirrors, and structured metadata.           | Route access plus `agentWeb` config     |
-| Extensions              | Shipping         | Sandboxed mini-apps call app actions, persist extension data, and use proxied fetch helpers.                           | Extension HTML using `appAction()`      |
-| AG-UI                   | Adapter target   | A good fit for connecting an external agent runtime to an agent-native chat/UI shell through event streams.            | An adapter, not duplicate actions       |
-| A2UI                    | Watch / future   | A promising declarative UI wire format for agent-generated cross-platform widgets.                                     | A renderer/adapter when it matures      |
-| ACP                     | Coding-agent IDE | Useful for coding agents inside editors/IDEs; not the general app-agent UI contract.                                   | Editor/agent adapter work               |
-
-The practical rule is simple: implement domain operations as actions, add `readOnly`, `publicAgent`, `link`, `mcpApp`, or an explicit native widget result only when a surface needs it, and use skills/instructions for behavior. MCP, A2A, MCP Apps, MCP Auth, UI mutations, native chat widgets, CLI commands, and deep-link handoffs are adapters around that same core.
-
-Adapter horizon: [AG-UI](https://docs.ag-ui.com/introduction) is a strong fit for connecting external agent runtimes to Agent-Native chat and app shells through events. [A2UI](https://developers.googleblog.com/introducing-a2ui-an-open-project-for-agent-driven-interfaces/) is a promising declarative UI format for generated widgets. [ACP](https://zed.dev/acp) is important for coding-agent/editor interoperability, but it is not the general BYO app-agent UI contract.
+| Surface                 | Status              | What agent-native provides                                                                                                      | What you write                          |
+| ----------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| 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               |
+| 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                      |
+| MCP Apps                | Shipping            | External hosts that support app resources can render iframe/native-host widgets, with deep-link fallback elsewhere.             | Optional `mcpApp` metadata              |
+| A2A                     | Shipping            | Other agents discover the agent card and call the app over JSON-RPC tasks.                                                      | The same actions and agent config       |
+| Deep links              | Shipping            | Action results can round-trip users into the running UI through `/_agent-native/open` and `agentnative://open`.                 | Optional `link` metadata                |
+| MCP clients             | Shipping            | The app can also consume local, remote, or hub-shared MCP servers as `mcp__...` tools.                                          | `mcp.config.json` or settings           |
+| Instructions and skills | Shipping            | `AGENTS.md`, skills, memory, slash commands, sub-agents, jobs, and automations live in the SQL-backed workspace.                | Workspace resources, not protocol glue  |
+| Agent Web               | Shipping            | Public pages can publish `robots.txt`, `sitemap.xml`, `llms.txt`, markdown mirrors, and structured metadata.                    | Route access plus `agentWeb` config     |
+| Extensions              | Shipping            | Sandboxed mini-apps call app actions, persist extension data, and use proxied fetch helpers.                                    | Extension HTML using `appAction()`      |
+| AG-UI                   | Adapter target      | A good fit for connecting an external agent runtime to an agent-native chat/UI shell through event streams.                     | An adapter, not duplicate actions       |
+| ACP                     | Coding-agent/editor | Useful for coding agents inside editors/IDEs; not the general BYO app-chat runtime contract.                                    | Editor/agent adapter work               |
+
+The practical rule is simple: implement domain operations as actions, add `readOnly`, `publicAgent`, `link`, `mcpApp`, or an explicit native widget result only when a surface needs it, and use skills/instructions for behavior. MCP, A2A, MCP Apps, MCP OAuth, UI mutations, native chat widgets, CLI commands, and deep-link handoffs are adapters around that same core.
+
+Adapter horizon: [AG-UI](https://docs.ag-ui.com/introduction) is a strong fit for connecting external agent runtimes to Agent-Native chat and app shells through events. [ACP](https://zed.dev/acp) is important for coding-agent/editor interoperability, but it is not the general BYO app-agent UI contract.
 
 ## Three product shapes {#three-product-shapes}
 
@@ -320,5 +319,6 @@ For detailed guidance on specific patterns:
 - [What Is Agent-Native?](/docs/what-is-agent-native) — the vision and philosophy
 - [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
 - [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 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, 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.
 
 ## Authoring: optional MCP Apps UI {#mcp-apps}