@agent-native/core 0.54.1 → 0.56.0

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/external-agents.md

@@ -10,6 +10,13 @@ An agent-native app is reachable by any MCP-compatible host — Claude, Claude D
 
 The external-agent bridge closes the loop. First you connect your own agent to a **hosted** app — either by pasting the app's remote MCP URL into a chat host like Claude or ChatGPT, or by running the developer CLI flow for local coding agents. Then the agent does the work over MCP and hands the user either an inline **MCP App** UI in compatible hosts or a single **"Open in <app> →"** link that opens the real app focused on exactly what was produced. It reuses the existing `navigate` / `application_state` contract the UI already drains every 2s (see [Context Awareness](/docs/context-awareness)) — there is no second navigation mechanism.
 
+## 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 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.
+
 ## Easy setup {#easy-setup}
 
 Add one remote MCP connector to the host where you want to use Agent-Native.
@@ -83,7 +90,7 @@ In hosts that support MCP Apps, Analytics can render real dashboard and analysis
 
 ## Advanced setup: local agents {#connect}
 
-Use this flow for local agent clients on your machine — Claude Code, Claude Code CLI, Codex, and Claude Cowork. (Cursor uses the paste-URL flow above; it does not need this CLI path.)
+Use this flow for local agent clients on your machine — Claude Code, Claude Code CLI, Codex, Claude Cowork, Cursor, OpenCode, and GitHub Copilot / VS Code. Cursor and other OAuth-native clients can also use the paste-URL flow above when their UI supports remote MCP OAuth.
 
 Run the connect command through npm:
 
@@ -93,7 +100,7 @@ npx @agent-native/core@latest connect https://dispatch.agent-native.com
 
 The command asks which local agent clients should receive MCP config. All clients are preselected the first time; after you choose, the selection is saved to `~/.agent-native/connect.json` so the next run can reuse it with Enter, or you can edit the checked items.
 
-For Claude Code and Claude Code CLI, `connect` writes a standard remote HTTP MCP entry with no static headers. Restart Claude Code, run `/mcp`, and choose **Authenticate**; Claude completes the OAuth flow and stores its own tokens. For Codex and Claude Cowork, `connect` uses the compatibility device-code flow: it opens your browser at the app, you click **Authorize** once, and the command writes a scoped bearer-token entry. If you choose a mix of clients, it does both.
+For Claude Code, Claude Code CLI, Cursor, OpenCode, and GitHub Copilot / VS Code, `connect` writes a standard remote HTTP MCP entry with no static headers. Restart the client and authenticate from its MCP UI when prompted. For Codex and Claude Cowork, `connect` uses the compatibility device-code flow: it opens your browser at the app, you click **Authorize** once, and the command writes a scoped bearer-token entry. If you choose a mix of clients, it does both.
 
 Keep the `connect` command running until the browser approval completes. If the
 waiting process is stopped early, the approval can succeed in the browser but
@@ -104,7 +111,10 @@ If you previously connected Claude Code through the old bearer-token flow, just
 | Local client                  | Config written by `connect`                             | Auth flow                                       |
 | ----------------------------- | ------------------------------------------------------- | ----------------------------------------------- |
 | Claude Code / Claude Code CLI | `.mcp.json` or `~/.claude.json`, depending on `--scope` | Standard remote MCP OAuth in Claude's `/mcp` UI |
-| Codex                         | `~/.codex/config.toml` under `[mcp_servers.<app>]`      | Browser-authorized bearer fallback              |
+| Cursor                        | `.cursor/mcp.json` or `~/.cursor/mcp.json`              | Standard remote MCP OAuth in Cursor's MCP UI    |
+| OpenCode                      | `opencode.json` or `~/.config/opencode/opencode.json`   | Standard remote MCP OAuth in OpenCode's MCP UI  |
+| GitHub Copilot / VS Code      | `.vscode/mcp.json` or VS Code user MCP config           | Standard remote MCP OAuth in VS Code's MCP UI   |
+| Codex                         | `$CODEX_HOME/config.toml` or `~/.codex/config.toml`     | Browser-authorized bearer fallback              |
 | Claude Cowork                 | `~/.cowork/mcp.json` using the Claude Code MCP shape    | Browser-authorized bearer fallback              |
 
 Restart the agent client after connecting so it picks up the new MCP server; OAuth-native clients may then prompt you to authenticate from their MCP UI.
@@ -114,7 +124,7 @@ and token values before sharing logs. Do not use raw curl as a substitute for a
 host MCP session; after connecting, use the host-exposed tools or restart the
 client if the new server is not visible yet.
 
-Use `--client codex` (or `--client claude-code`, `--client claude-code-cli`, `--client cowork`, `--client all`) to skip the picker for scripts or one-off installs.
+Use `--client codex` (or `--client claude-code`, `--client claude-code-cli`, `--client cursor`, `--client opencode`, `--client github-copilot`, `--client cowork`, `--client all`) to skip the picker for scripts or one-off installs.
 
 First-party app skills install the instructions and the hosted MCP connector together with the Agent Native CLI:
 

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,25 +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).
+- **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
@@ -27,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`.
 
@@ -37,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
@@ -85,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
@@ -95,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
@@ -103,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:
@@ -117,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:
@@ -151,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,21 +190,39 @@ 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                 | What agent-native provides                                                                                             | What you write                          |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
-| Agent tool calling      | The in-app agent sees actions as function tools with zod-derived JSON Schema.                                          | `defineAction()`                        |
-| UI actions              | React calls the same action through `useActionMutation()` / `useActionQuery()`.                                        | The same action                         |
-| HTTP and CLI            | Actions auto-mount at `/_agent-native/actions/:name` and run via `pnpm action <name>`.                                 | The same action                         |
-| MCP server              | 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                | Remote MCP OAuth, PKCE, dynamic client registration, refresh tokens, and `mcp:read` / `mcp:write` / `mcp:apps` scopes. | Nothing per action                      |
-| A2A                     | Other agents discover the agent card and call the app over JSON-RPC tasks.                                             | The same actions and agent config       |
-| Deep links              | Action results can round-trip users into the running UI through `/_agent-native/open` and `agentnative://open`.        | Optional `link` metadata                |
-| MCP clients             | The app can also consume local, remote, or hub-shared MCP servers as `mcp__...` tools.                                 | `mcp.config.json` or settings           |
-| Instructions and skills | `AGENTS.md`, skills, memory, slash commands, sub-agents, jobs, and automations live in the SQL-backed workspace.       | Workspace resources, not protocol glue  |
-| Agent Web               | Public pages can publish `robots.txt`, `sitemap.xml`, `llms.txt`, markdown mirrors, and structured metadata.           | Route access plus `agentWeb` config     |
-| Extensions              | Sandboxed mini-apps call app actions, persist extension data, and use proxied fetch helpers.                           | Extension HTML using `appAction()`      |
-
-The practical rule is simple: implement domain operations as actions, add `readOnly`, `publicAgent`, `link`, or `mcpApp` metadata only when the surface needs it, and use skills/instructions for behavior. MCP, A2A, MCP Apps, MCP Auth, UI mutations, CLI commands, and deep-link handoffs are adapters around that same core.
+| 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}
+
+Those protocol adapters let the same app grow across three product shapes:
+
+| Shape                 | User experience                                                                                                        | Best for                                                       |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| **Headless agent**    | Call actions and the agent from your code, another app, MCP, A2A, HTTP, or CLI.                                        | Automation, integrations, background jobs, developer workflows |
+| **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.
 
 ## Agent modifies code {#agent-modifies-code}
 
@@ -301,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,6 +9,8 @@ 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.
+
 ## 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.

package/docs/content/mcp-protocol.md

@@ -15,7 +15,7 @@ Every agent-native app automatically exposes a remote MCP (Model Context Protoco
 | 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)               |
+| Build or embed interactive MCP App resources                | [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.
 
@@ -29,7 +29,7 @@ Key concepts:
 - **Streamable HTTP** — uses the modern MCP transport over standard HTTP (POST + SSE)
 - **Same actions** — the exact same action registry that powers agent chat and A2A
 - **`ask-agent` tool** — a meta-tool that delegates to the full agent loop for complex tasks
-- **MCP Apps** — actions can advertise inline HTML UIs through the official `io.modelcontextprotocol/ui` extension
+- **MCP Apps** — actions can advertise interactive UI resources through the official `io.modelcontextprotocol/ui` extension
 - **Standard remote MCP OAuth** — OAuth 2.1 discovery, dynamic client registration, authorization-code + PKCE, refresh-token rotation
 - **Bearer auth fallback** — uses `ACCESS_TOKEN`, `ACCESS_TOKENS`, or connect-minted JWTs for clients that cannot run OAuth