@agent-native/core 0.63.0 → 0.63.2

package/docs/content/embedding-sdk.md

@@ -5,137 +5,31 @@ description: "Embed an Agent-Native sidecar into an existing SaaS app with page
 
 # Embedding SDK
 
-## Installation {#installation}
-
-```bash
-pnpm add @agent-native/embedding
-```
-
-Subpath exports from `@agent-native/embedding`:
-
-| Import path                        | What it provides                                                                        |
-| ---------------------------------- | --------------------------------------------------------------------------------------- |
-| `@agent-native/embedding`          | `EmbeddedApp` picker component, `getA2AUrl`, `getMcpUrl`, `sendMessage` (streaming A2A) |
-| `@agent-native/embedding/react`    | React-specific hooks and components                                                     |
-| `@agent-native/embedding/bridge`   | `announceEmbeddedAppReady`, `sendEmbeddedAppMessage` — used inside the embedded app     |
-| `@agent-native/embedding/agent`    | Agent endpoint helpers                                                                  |
-| `@agent-native/embedding/protocol` | Protocol types                                                                          |
-
-For the **batteries-included embedded mode** (full sidecar with actions, database, and agent chat), install `@agent-native/core` on the server and use `createAgentNativeEmbeddedPlugin`:
+Embed Agent-Native into an existing product: keep your SaaS app, add a durable
+agent sidecar, and let that agent see and operate on the page the user is
+already using. If you are still deciding between headless agents, rich chat, an
+embedded sidecar, or a full app, start with
+[Agent Surfaces](/docs/agent-surfaces).
+
+## Start here: the batteries-included plugin {#batteries-included}
+
+For most SaaS hosts, **use the full embedded runtime** — the server plugin
+`createAgentNativeEmbeddedPlugin` plus the `<AgentNativeEmbedded>` client
+component. This is the recommended default: it reuses the entire framework
+(actions, SQL-backed app state, extensions, browser-session tools) and gives the
+agent the ability to see and operate on the page the user is already using.
+
+The host mounts Agent-Native server routes into its existing app, passes its
+logged-in user to Agent-Native, and renders the React sidebar in the product UI.
+Agent-Native uses the host deployment, host session, and the configured
+`DATABASE_URL` to manage its own framework tables: chat threads, settings,
+application state, extensions, extension data, secrets, browser sessions, and
+action routes.
 
 ```bash
 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`                                |
-| **Batteries-included server plugin** | Adding a durable agent sidecar with its own database and actions to your existing SaaS app.         | `@agent-native/core` + `createAgentNativeEmbeddedPlugin` |
-| **`<AgentNative>` host component**   | Client-side: rendering the agent sidecar panel in your React app shell with live page context.      | `@agent-native/core/client`                              |
-| **Extension slot**                   | Embedding a sandboxed mini-app (extension) inside an existing agent-native template.                | `@agent-native/core` extensions system                   |
-
-The CLAW-style host bridge described below uses the batteries-included plugin (server) + the `<AgentNativeEmbedded>` component (client). It is the recommended default when you want the agent to see and operate on the page the user is already using.
-
----
-
-The embedding SDK is for the CLAW-style shape: keep your existing SaaS app, add a durable agent sidecar, and let that agent see and operate on the page the user is already using.
-
-Use it when you want an assistant that can:
-
-- Read current page context: route, selected resource, highlighted text, active filters, user/org, and app-specific state.
-- Call durable backend actions, MCP tools, or integration-backed tools from the sidecar app.
-- Ask the host app to navigate, refresh data, remount a view, or open a resource after durable work completes.
-- Run as an iframe/sidebar now, while leaving room for a no-iframe package or hosted template later.
-
-## Embedded App And Picker Mode
-
-Use `@agent-native/embedding` when the host product wants to launch a complete
-Agent-Native app as a focused iframe surface: an asset picker, asset generator,
-form builder, calendar slot picker, approval panel, or any other task-specific
-workflow. This is intentionally smaller than the sidecar host bridge below: the
-iframe announces readiness, the host can send named messages, and the embedded
-app can emit domain events such as `chooseAsset` or `close`.
-
-```tsx
-import { EmbeddedApp } from "@agent-native/embedding";
-
-export function AssetPickerDialog({ close }) {
-  return (
-    <EmbeddedApp
-      url="https://assets.agent-native.com/picker"
-      className="h-full w-full"
-      onLoad={(ref) => {
-        ref.postMessage("configure", {
-          prompt: "Editorial blog hero",
-          aspectRatio: "16:9",
-        });
-      }}
-      onMessage={(name, payload) => {
-        if (name === "chooseAsset") {
-          const asset = payload as { url: string; altText?: string };
-          insertAsset(asset.url, asset.altText);
-          close();
-        }
-        if (name === "close") close();
-      }}
-    />
-  );
-}
-```
-
-Inside the embedded app, use the browser bridge to announce readiness and send
-events back to the host:
-
-```ts
-import {
-  announceEmbeddedAppReady,
-  sendEmbeddedAppMessage,
-} from "@agent-native/embedding/bridge";
-
-announceEmbeddedAppReady({ app: "assets", mode: "picker" });
-sendEmbeddedAppMessage("chooseAsset", {
-  url: asset.previewUrl,
-  assetId: asset.id,
-  altText: asset.altText,
-});
-```
-
-Assets also emits `chooseImage` as a compatibility alias for older image-picker
-hosts; new integrations should listen for `chooseAsset`.
-
-For hosted first-party apps, enable Cross-App SSO with Dispatch as the identity
-hub so `content.agent-native.com` and `assets.agent-native.com` link users by
-verified email. Iframe launches should still use short-lived, route-scoped
-embed sessions when they need third-party-cookie resilience; normal app cookies
-are not a complete embed auth story on their own.
-
-The same package includes agent endpoint helpers for protocol discovery and
-streaming text over A2A:
-
-```ts
-import { getA2AUrl, getMcpUrl, sendMessage } from "@agent-native/embedding";
-
-getMcpUrl("https://assets.agent-native.com");
-getA2AUrl("https://assets.agent-native.com");
-
-for await (const chunk of sendMessage(
-  "https://assets.agent-native.com",
-  "Generate a blog hero",
-)) {
-  append(chunk);
-}
-```
-
-## Batteries-Included Embedded Mode
-
-For most SaaS hosts, use the full embedded runtime. The host mounts Agent-Native server routes into its existing app, passes its logged-in user to Agent-Native, and then renders the React sidebar/surface in the product UI. Agent-Native uses the host deployment, host session, and the configured `DATABASE_URL` to manage its own framework tables: chat threads, settings, application state, extensions, extension data, secrets, browser sessions, and action routes.
-
 On the server:
 
 ```ts
@@ -238,7 +132,115 @@ export default createAgentNativeEmbeddedPlugin({
 
 Using the host product's main `DATABASE_URL` is supported, but make that an explicit choice. Agent-Native creates framework tables such as `settings`, `application_state`, `tools`, `tool_data`, browser-session tables, secrets, chat threads, and related indexes. A dedicated DB/schema avoids table-name collisions, keeps ownership of managed tables clear, and makes backup/retention policy easier to reason about. If you intentionally share the host DB, review existing table names first and treat Agent-Native tables as framework-owned.
 
-## Host App
+## Other modes {#other-modes}
+
+The batteries-included plugin above is the happy path. Reach for one of these
+only when it fits your situation better:
+
+| 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`                  |
+| **`<AgentNative>` host bridge** | Standalone sidecar apps or cross-origin iframes that wire page context and client actions manually. | `@agent-native/core/client`                |
+| **Portable extensions**         | Letting host users build sandboxed mini-apps when the SaaS already owns extension storage/approval. | `@agent-native/core/client` extension slot |
+
+The lower-level `@agent-native/embedding` package exposes:
+
+| Import path                        | What it provides                                                                        |
+| ---------------------------------- | --------------------------------------------------------------------------------------- |
+| `@agent-native/embedding`          | `EmbeddedApp` picker component, `getA2AUrl`, `getMcpUrl`, `sendMessage` (streaming A2A) |
+| `@agent-native/embedding/react`    | React-specific hooks and components                                                     |
+| `@agent-native/embedding/bridge`   | `announceEmbeddedAppReady`, `sendEmbeddedAppMessage` — used inside the embedded app     |
+| `@agent-native/embedding/agent`    | Agent endpoint helpers                                                                  |
+| `@agent-native/embedding/protocol` | Protocol types                                                                          |
+
+```bash
+pnpm add @agent-native/embedding
+```
+
+### Embedded App And Picker Mode
+
+Use `@agent-native/embedding` when the host product wants to launch a complete
+Agent-Native app as a focused iframe surface: an asset picker, asset generator,
+form builder, calendar slot picker, approval panel, or any other task-specific
+workflow. This is intentionally smaller than the sidecar host bridge below: the
+iframe announces readiness, the host can send named messages, and the embedded
+app can emit domain events such as `chooseAsset` or `close`.
+
+```tsx
+import { EmbeddedApp } from "@agent-native/embedding";
+
+export function AssetPickerDialog({ close }) {
+  return (
+    <EmbeddedApp
+      url="https://assets.agent-native.com/picker"
+      className="h-full w-full"
+      onLoad={(ref) => {
+        ref.postMessage("configure", {
+          prompt: "Editorial blog hero",
+          aspectRatio: "16:9",
+        });
+      }}
+      onMessage={(name, payload) => {
+        if (name === "chooseAsset") {
+          const asset = payload as { url: string; altText?: string };
+          insertAsset(asset.url, asset.altText);
+          close();
+        }
+        if (name === "close") close();
+      }}
+    />
+  );
+}
+```
+
+Inside the embedded app, use the browser bridge to announce readiness and send
+events back to the host:
+
+```ts
+import {
+  announceEmbeddedAppReady,
+  sendEmbeddedAppMessage,
+} from "@agent-native/embedding/bridge";
+
+announceEmbeddedAppReady({ app: "assets", mode: "picker" });
+sendEmbeddedAppMessage("chooseAsset", {
+  url: asset.previewUrl,
+  assetId: asset.id,
+  altText: asset.altText,
+});
+```
+
+Assets also emits `chooseImage` as a compatibility alias for older image-picker
+hosts; new integrations should listen for `chooseAsset`.
+
+For hosted first-party apps, enable Cross-App SSO with Dispatch as the identity
+hub so `content.agent-native.com` and `assets.agent-native.com` link users by
+verified email. Iframe launches should still use short-lived, route-scoped
+embed sessions when they need third-party-cookie resilience; normal app cookies
+are not a complete embed auth story on their own.
+
+The same package includes agent endpoint helpers for protocol discovery and
+streaming text over A2A:
+
+```ts
+import { getA2AUrl, getMcpUrl, sendMessage } from "@agent-native/embedding";
+
+getMcpUrl("https://assets.agent-native.com");
+getA2AUrl("https://assets.agent-native.com");
+
+for await (const chunk of sendMessage(
+  "https://assets.agent-native.com",
+  "Generate a blog hero",
+)) {
+  append(chunk);
+}
+```
+
+### Host App (`<AgentNative>` host bridge)
+
+> The batteries-included plugin above is preferred. Use this lower-level bridge
+> only for standalone sidecar apps or cross-origin iframes where you wire page
+> context and client actions yourself.
 
 For standalone sidecar apps or cross-origin iframes, use the lower-level `<AgentNative />`. It renders the iframe sidecar and wires page context, live client actions, and host refresh/navigation commands in one place:
 
@@ -319,7 +321,7 @@ Use `screen={false}` if you only want explicit semantic context. Use `screen={{
 
 For non-React hosts, call `createAgentNativeHostBridge()` directly and pass the same `getContext`, `actions`, and `commands` options.
 
-## Iframe Side
+### Iframe Side
 
 Inside the Agent-Native sidecar, use the frame helpers to request host context, discover live browser-session actions, run them, or ask the host to do UI work. Always pass the expected `hostOrigin` in production:
 
@@ -360,7 +362,7 @@ const hostTools = createAgentNativeHostTools({
 });
 ```
 
-## Server-Mediated Tool Bridge
+### Server-Mediated Tool Bridge
 
 For a CLAW-style coworker, the iframe can also register its live browser tab with the sidecar backend. The agent then gets normal backend tools that enqueue a request, the iframe claims it, the host page executes it, and the backend returns the result to the agent.
 
@@ -395,7 +397,7 @@ The framework mounts `/_agent-native/browser-sessions` automatically. Once the b
 
 This is the bridge to use when the agent is running on the backend, in Slack/Telegram/email, or as an A2A callee but still needs to touch the user's current browser tab when it is open. If the browser is closed, backend actions should still handle durable work and the browser-session tools will report that no active tab is connected.
 
-## Actions
+### Actions
 
 There are two action classes:
 
@@ -408,7 +410,11 @@ Backend actions should be the default for anything that must survive refreshes,
 
 Client actions are a live bridge to one browser tab. The host advertises them with `source: "client"` and `availability: "browser-session"`, and the sidecar should treat that manifest as temporary. Re-list actions when route or selection changes, and fall back to backend actions when the tab disappears.
 
-## Portable Extensions
+### Portable Extensions
+
+> Prefer the batteries-included plugin when you want Agent-Native to manage
+> extension definitions, approval, storage, and agent-created extensions. Use
+> the portable slot below only when the SaaS already owns those concerns.
 
 The SDK also supports user-defined extensions: sandboxed Alpine.js mini-apps that a host SaaS can render in named slots. Use this when the customer wants to build their own small panels, calculators, dashboards, or workflow helpers against the same action/context surface that the agent uses.
 
@@ -526,13 +532,13 @@ Security model:
 - Risky actions should set `destructive` or `requiresApproval` so the host can show an approval flow.
 - Treat user-authored extension HTML as untrusted. Review marketplace installs, log action usage, and scope backend storage by user/org.
 
-## Sessions And Tabs
+### Sessions And Tabs
 
 The host bridge is scoped to one iframe/host-window pair. If the same user opens multiple tabs, each tab has its own `session`, context, selection, client actions, and pending command responses. Do not assume a client action discovered in one tab can run in another tab, or that it will still exist after navigation.
 
 For multi-tab products, keep durable state in SQL/backend actions and use client actions only for the tab-local parts: focusing a row, copying visible editor state, selecting a canvas element, or refreshing the current React Query cache. Include enough `route`, `resource`, and `selection` context for the sidecar to decide whether the current tab is the right place to run a browser-session action.
 
-## Command Model
+### Command Model
 
 Built-in command names are deliberately app-shaped, not database-shaped:
 
@@ -547,7 +553,7 @@ Built-in command names are deliberately app-shaped, not database-shaped:
 
 If no handler is provided, safe defaults dispatch browser events like `agentNative:refresh-data` and `agentNative:remount-view`. `requestApproval` has no default handler; register one before relying on it.
 
-## Approval Guidance
+### Approval Guidance
 
 Mark risky client actions with `destructive: true` in their manifest and require host approval before running operations that delete, publish, send, charge, invite, share, or otherwise affect users outside the current view. Backend actions should enforce their own authorization and approval checks too; host approval is useful UX, not the security boundary.
 
@@ -557,7 +563,7 @@ Prefer this shape:
 - Host command opens an approval UI or focuses the affected resource.
 - Client action handles only the live UI step that cannot happen on the backend.
 
-## Runtime Integration
+### Runtime Integration
 
 Use `createAgentNativeHostTools()` inside the sidecar iframe when your agent runtime accepts plain tool descriptors. It returns four framework-agnostic tools:
 

package/docs/content/evals.md

@@ -1,9 +1,9 @@
 ---
-title: "Evals (CI Gate)"
+title: "CI Eval Gate"
 description: "Write *.eval.ts test cases that run the real agent against fixed inputs, score the output with composable scorers, and gate CI/deploys on a threshold."
 ---
 
-# Evals (CI Gate)
+# CI Eval Gate
 
 Evals are a first-class testing primitive: you declare a prompt plus the behavior you expect, the runner **actually runs the agent loop** against that input, scores the output with composable scorers, and exits non-zero if any case scores below its threshold. That non-zero exit makes `agent-native eval` a drop-in CI deploy gate.
 
@@ -73,7 +73,7 @@ Imported from `@agent-native/core/eval`:
 
 `createScorer` builds a scorer from a Mastra-style 4-step pipeline. Only `generateScore` is required:
 
-```txt
+```text
 preprocess(run)     → x          transform the run/output (optional)
 analyze(x, ctx)     → analysis   plain JS OR an LLM judge (optional)
 generateScore(a)    → 0..1       REQUIRED, normalized

package/docs/content/extensions.md

@@ -228,7 +228,7 @@ For deeper detail on slots — how to declare them in your template, how the con
 
 Local File Mode lets a workspace keep extensions in the repo:
 
-```txt
+```text
 extensions/
   doc-status/
     extension.json

package/docs/content/external-agents.md

@@ -6,6 +6,15 @@ search: "Claude ChatGPT Claude Code Codex Cursor Claude Cowork MCP Apps agent-na
 
 # External Agents
 
+**This page: connect an external agent or MCP host to your app.** Use it when Claude, ChatGPT, Codex, Cursor, Claude Cowork, or another MCP-compatible host should drive a hosted agent-native app and round-trip the result back into the running UI.
+
+| If you want to…                                              | Read                               |
+| ------------------------------------------------------------ | ---------------------------------- |
+| Connect an external agent/host to your app                   | **This page** — External Agents    |
+| Give your agent more tools (consume other MCP servers)       | [MCP Clients](/docs/mcp-clients)   |
+| Build inline UIs that render in Claude/ChatGPT               | [MCP Apps](/docs/mcp-apps)         |
+| Lower-level MCP server reference (auth, tools, custom mount) | [MCP Protocol](/docs/mcp-protocol) |
+
 An agent-native app is reachable by any MCP-compatible host — Claude, Claude Desktop, Claude Code, ChatGPT custom MCP apps, Codex, Cursor, Claude Cowork, VS Code GitHub Copilot, Goose, Postman, MCPJam, and future clients that implement the standard. External agents are great at producing artifacts (a draft, an event, a dashboard) but they often live in a terminal or another app. Without a bridge, the user gets a wall of JSON and has to go find the thing.
 
 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.
@@ -225,55 +234,33 @@ When the client requests no explicit scope, the app grants all three so the conn
 
 ## Catalog tiers {#catalog-tiers}
 
-The MCP server serves a **compact catalog by default to every caller** —
-hosted connectors (ChatGPT, Claude), code clients (Claude Code, Cursor,
-Codex), and the local CLI/stdio proxy alike. The full action surface is served
-only on an explicit opt-in. The catalog is never inferred from the client name
-or user-agent.
+This is the canonical explanation of MCP catalog tiers — other pages link here.
+
+The MCP server serves a **compact catalog by default to every caller** — hosted connectors (ChatGPT, Claude), code clients (Claude Code, Cursor, Codex), and the local CLI/stdio proxy alike. The full action surface is served only on explicit opt-in. The catalog is never inferred from the client name or user-agent.
 
 ### Compact / connector tier (default) {#connector-tier}
 
-By default every connected agent sees a small, curated catalog: the
-template-declared allow-list of app-level actions (create/get/update plan,
-sharing, upload, navigate, automations, `tool-search`) plus the builtin
-cross-app tools (`list_apps`, `open_app`, `ask_app`, `create_embed_session`).
-Tools outside the list — `db-exec`, `db-patch`, `seed-*`, the extension suite,
-browser-session tools, agent-engine management, and context-xray tools — are
-not advertised, and calls to them are rejected with "Unknown tool" unless the
-caller has opted into the full catalog.
-
-This keeps the context window of every connected external agent small (~20–30
-tools vs. ~105) and removes footguns that are only safe for single-tenant local
-development. The connector tier is active **whenever a template declares a
-`connectorCatalog`** — it is no longer gated behind an environment variable.
-
-`tool-search` is always available (including in the compact catalog), so a
-compacted client can still reach any tool on demand. Call it with **no query**
-to get the full menu of tool names plus one-line descriptions (cheap — no
-schemas), or with a query to get ranked matches with parameter summaries. This
-is how a compacted client discovers and loads any full-surface tool when it
-needs one.
+By default every connected agent sees a small, curated catalog (~20–30 tools vs. ~105 in the full surface):
+
+- **Template-declared app actions** — the safe app-level allow-list. For Plan that is `create-visual-plan`, `get-visual-plan`, `share-resource`, `navigate`, `tool-search`, and similar.
+- **Builtin cross-app tools** — `list_apps`, `open_app`, `ask_app`, `create_embed_session`.
+- **`tool-search`** is always present, so anything outside the list stays reachable on demand (see below).
+
+Tools outside the list — for example `db-exec`, `seed-*`, the extension suite, browser-session tools, and context-xray tools — are not advertised, and calls to them are rejected with "Unknown tool" unless the caller has opted into the full catalog. This keeps each connected agent's context window small and removes footguns that are only safe for single-tenant local development. The connector tier is active **whenever a template declares a `connectorCatalog`** — it is not gated behind an environment variable.
+
+`tool-search` works two ways: call it with **no query** for the full menu of tool names plus one-line descriptions (cheap, no schemas), or with a query for ranked matches with parameter summaries. That is how a compacted client discovers and loads any full-surface tool when it needs one.
 
 ### Full tier (explicit opt-in only) {#full-tier}
 
-The complete ~105-tool action surface is served only when a caller explicitly
-opts in. There are two ways to opt in:
+The complete ~105-tool action surface is served only on explicit opt-in, two ways:
 
-- Mint a token with `--full-catalog`, which embeds a `catalog_scope: "full"`
-  claim in the JWT:
+- **Per token** — mint with `--full-catalog`, which embeds a `catalog_scope: "full"` claim in the JWT. Subsequent requests bypass the compact filter for that token:
 
   ```bash
   npx @agent-native/core@latest connect https://plan.agent-native.com --client codex --full-catalog
   ```
 
-  Swap `--client codex` for another target client when needed. On subsequent
-  requests the MCP server bypasses the compact-catalog filter for that token
-  and serves the complete action surface.
-
-- Set `AGENT_NATIVE_MCP_FULL_CATALOG=1` (process env on the server) as a
-  deployment-wide override that serves the full surface to all callers. Use it
-  for single-tenant hosted instances that want the full surface without
-  per-token opt-up.
+- **Per deployment** — set `AGENT_NATIVE_MCP_FULL_CATALOG=1` (server process env) to serve the full surface to all callers. Use it for single-tenant hosted instances that want the full surface without per-token opt-up.
 
 ### Template declaration {#catalog-declaration}
 
@@ -339,26 +326,9 @@ entries and `resources/read` content, not on the tool descriptor.
 
 For ChatGPT/Claude-style OAuth app hosts, the discovery surface is compact by default: `tools/list` and `resources/list` advertise the generic `open_app` embed path instead of every action-specific MCP App resource (see [Catalog tiers](#catalog-tiers)). Mark an individual action with `mcpApp.compactCatalog: true` only when it truly needs to stay visible in chat-host discovery.
 
-That makes the same app surface available to every compatible host rather than building per-client shims. The current official MCP Apps client list includes Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT, and Cursor; host support still varies by plan, release channel, and client version, so check the [MCP extension support matrix](https://modelcontextprotocol.io/extensions/client-matrix). ChatGPT custom MCP apps are available through developer mode for Business and Enterprise/Edu workspaces on ChatGPT web; see OpenAI's [developer mode and MCP apps](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-apps-in-chatgpt-beta) notes.
-
-Claude Code, Codex, and other CLI/code-editor clients still receive the same
-resources and metadata when they support MCP Apps, but treat them as link-out
-hosts unless you have verified inline iframe rendering in that exact surface.
-The deep link remains the reliable fallback when a host chooses not to render an
-iframe. In practice, every agent-native app should be authored with both: MCP
-Apps for inline review/edit in capable hosts, and `link` for universal
-round-tripping back to the full app. Human-selection tools can add a paste-back
-step to that fallback: for example, the Assets picker opens from the fallback
-link, lets the user choose media in the browser, then copies a handoff summary
-that the user pastes back into the chat.
-
-Claude and ChatGPT can cache tool and resource metadata for an existing custom
-connector. After changing MCP App metadata, verify with a fresh tool call; if
-the host still uses the old descriptor, reconnect the Claude connector or
-rescan/review the ChatGPT connector so it refreshes the catalog.
-If Claude logs a warning about `_meta.ui.csp` or `_meta.ui.permissions` living
-on the tool descriptor after a deploy, that connector is using stale metadata:
-delete/reconnect the Claude connector and start a fresh chat.
+That makes the same app surface available to every compatible host rather than building per-client shims. Which hosts render MCP Apps inline (and the connector-cache gotcha after metadata changes) lives in [MCP Apps → Client support and caching](/docs/mcp-apps#client-support) — that page is the single home for the client matrix.
+
+In practice, every agent-native app should be authored with both: MCP Apps for inline review/edit in capable hosts, and `link` for universal round-tripping back to the full app. CLI/code-editor clients that do not render an iframe fall back to the deep link. Human-selection tools can add a paste-back step to that fallback: for example, the Assets picker opens from the fallback link, lets the user choose media in the browser, then copies a handoff summary that the user pastes back into the chat.
 
 ### First-class MCP App bridge {#mcp-app-bridge}
 
@@ -395,9 +365,13 @@ Every allow-listed template that produces or lists a navigable resource ships a
 - **Content** — `pull-document` is the GET + `publicAgent` ingest action: it flushes any open live collaborative session to SQL first so the external agent ingests exactly what the user sees, then surfaces a deep link to the document.
 - **Brain** — `ask-brain` / `search-everything` return a cited answer plus a deep link to the underlying knowledge/capture, so a terminal agent's lookup links straight back into the source in the running app.
 
-## Authoring: the `link` builder {#link-builder}
+## Authoring (for template authors) {#authoring}
+
+Everything above is for **end users** connecting and using an app. The rest of this page is for **template authors** wiring an app up to be a good external-agent citizen: the `link` builder, the optional MCP Apps UI, the `/_agent-native/open` route internals, and ingest actions.
+
+### The `link` builder {#link-builder}
 
-This section is for template authors. `defineAction` accepts an optional `link` builder. When set, every MCP/A2A result for that tool auto-appends a markdown `[label →](absoluteUrl)` block and a structured `_meta["agent-native/openLink"] = { label, view, webUrl, desktopUrl, vscodeUrl }`. `tools/list` adds `annotations["agent-native/producesOpenLink"]` and a description suffix so the external agent knows the tool yields an openable link and should surface it.
+`defineAction` accepts an optional `link` builder. When set, every MCP/A2A result for that tool auto-appends a markdown `[label →](absoluteUrl)` block and a structured `_meta["agent-native/openLink"] = { label, view, webUrl, desktopUrl, vscodeUrl }`. `tools/list` adds `annotations["agent-native/producesOpenLink"]` and a description suffix so the external agent knows the tool yields an openable link and should surface it.
 
 Build the URL with `buildDeepLink(...)` — it is the single source of truth for the open-route format. Never hand-format the `/_agent-native/open` URL.
 
@@ -432,7 +406,7 @@ export default defineAction({
 
 List/search actions point at a record-focused view the same way — e.g. calendar's `create-event` returns `buildDeepLink({ app: "calendar", view: "calendar", params: { eventId, date } })` with label `"Open event in Calendar"`. Calendar draft actions use the same pattern: `manage-event-draft` returns `buildDeepLink({ app: "calendar", view: "calendar", to: "/", params: { eventDraftId, calendarDraft, date } })` with label `"Review invite in Calendar"`, so external agents can hand back a direct draft-review link without creating the event first.
 
-## Authoring: optional MCP Apps UI {#mcp-apps}
+### Optional MCP Apps UI {#mcp-apps}
 
 Actions can advertise an inline UI resource with `mcpApp` for hosts that support the MCP Apps extension. Use `embedRoute({ title, openLabel, path })` as the convenience wrapper, or assign `embedApp(...)` to `mcpApp.resource` directly. Every MCP App is a real React route, not a separate plain-HTML widget. Always keep the `link` builder — CLI-only hosts, older clients, and non-MCP-Apps hosts use it as the fallback.
 
@@ -442,7 +416,7 @@ See [MCP Apps](/docs/mcp-apps) for the full authoring guide — `embedRoute` vs
 
 The `link` builder is **pure and synchronous — no I/O, no awaits**. It runs best-effort: a throw, `null`, or `undefined` is swallowed and **never** fails the tool call. It only reads the call's `args` and `result`; it must not query the DB, read app-state, or call other actions. Return `null` when there's nothing to open.
 
-`buildDeepLink({ app, view, params?, to?, compose? })` returns the app-relative path `/_agent-native/open?app=…&view=…&<recordId>=…`. The MCP layer turns that into an absolute web URL (`toAbsoluteOpenUrl`, using the request origin), a desktop `agentnative://open?…` URL (`toDesktopOpenUrl`), and a VS Code extension URL (`toVsCodeOpenUrl`) for `vscode://builderio.agent-native/open?url=…`; the markdown link uses the desktop URL when the client signals `target: "desktop"`.
+`buildDeepLink({ app, view, params?, to?, compose? })` returns the app-relative path `/_agent-native/open?app=…&view=…&<recordId>=…`. The MCP layer turns that into an absolute web URL (`toAbsoluteOpenUrl`, using the request origin), a desktop `agentnative://open?…` URL (`toDesktopOpenUrl`), and a VS Code extension URL (`toVsCodeOpenUrl`) for `vscode://builder.agent-native/open?url=…`; the markdown link uses the desktop URL when the client signals `target: "desktop"`.
 
 ### The `/_agent-native/open` route {#open-route}
 

package/docs/content/faq.md

@@ -11,7 +11,7 @@ Common questions about agent-native, organized from "I'm just looking" to "I'm w
 
 ### What is agent-native? {#what-is-agent-native}
 
-Agent-native is a framework for building apps where the AI agent and the product surface around it are equal partners. That surface can start as one headless action, grow into rich chat, or become a full UI. The invariant is that agents and humans share the same actions, database, and state. See [What Is Agent-Native?](/docs/what-is-agent-native) for the full explanation.
+Agent-native is a framework for building apps where the AI agent and the product surface around it are equal partners. That surface can start as a headless agent with one custom action, grow into rich chat, or become a full UI. The invariant is that agents and humans share the same actions, database, and state. See [What Is Agent-Native?](/docs/what-is-agent-native) for the full explanation.
 
 ### Who is this for? {#who-is-this-for}
 
@@ -26,7 +26,7 @@ Agent-native is for people who want a real app and an AI agent to work from the
 
 ### How is this different from adding AI to an existing app? {#how-is-this-different}
 
-Most apps bolt AI on as an afterthought — an autocomplete here, a chat sidebar there. The AI can't actually _do_ things in the app. In an agent-native app, the agent is a first-class citizen. It can create emails, schedule events, build forms, generate slides, and modify the app's own code. The architecture is designed for this from the ground up.
+Most apps bolt AI on as an afterthought that can't actually _do_ things in the app. In an agent-native app the agent is a first-class citizen that shares the same actions, database, and state as the UI, so it can do anything the buttons can — and modify the app's own code. See [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder).
 
 ### Is it open source? {#is-this-open-source}
 
@@ -117,12 +117,12 @@ Anywhere. The server runs on Nitro, which compiles to any deployment target: Nod
 
 ### Why SSE plus polling instead of WebSockets? {#why-polling-not-websockets}
 
-SSE gives same-process writes an immediate path to the browser without requiring a bidirectional socket server. Polling remains the fallback because it works in every deployment environment — including serverless, edge, and container platforms where persistent connections may not be available. The fallback uses a lightweight version counter; when changes are detected, React Query caches are invalidated and components re-render.
+SSE gives same-process writes an immediate path to the browser, and a lightweight version-counter poll remains the fallback because it works in every deployment environment — including serverless and edge, where persistent sockets may not be available. See [Key Concepts — Live sync](/docs/key-concepts#polling-sync).
 
 ### Why can't the UI call an LLM directly? {#why-no-inline-llm-calls}
 
-AI is non-deterministic — you need conversation flow to give feedback and iterate, not one-shot buttons. The agent has your full codebase, instructions, skills, and conversation history. An inline LLM call has none of that. Plus, routing everything through the agent means the app can be driven from Slack, Telegram, or another agent via [A2A](/docs/a2a-protocol) — not just the UI.
+AI is non-deterministic, so you need conversation flow to give feedback and iterate — not one-shot buttons — and the agent already has your codebase, instructions, skills, and history that an inline call lacks. Routing everything through the agent is also what lets the app be driven from Slack, Telegram, or another agent. See [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge).
 
 ### Why is this a framework and not a library? {#why-framework-not-library}
 
-The shared database, polling sync, actions system, and application state all need to work together as a cohesive architecture. A library could give you pieces, but agent-native requires that the agent and UI are wired together from the ground up. Multiple agents need to be able to communicate, the UI needs to react to agent changes instantly, and the agent needs to understand what the user is looking at. That's an architecture, not a utility.
+The shared database, live sync, actions system, and application state only work because they're wired together from the ground up — the UI reacts to agent changes instantly, agents communicate, and the agent understands what the user is looking at. A library gives you pieces; this is an architecture. See [Key Concepts](/docs/key-concepts).

package/docs/content/frames.md

@@ -51,10 +51,8 @@ The panel runs in one of two tool modes:
   [Agent-Native Code UI](/docs/code-agents-ui).
 
 "Code mode" is the agent-capability toggle — distinct from environment dev mode
-(`NODE_ENV` / Vite). For back-compat the underlying `AGENT_MODE` env var, the
-`/_agent-native/agent-chat/mode` endpoint (whose payload still uses `devMode`),
-and the `agent-chat.mode` settings key are unchanged. The client hook is
-`useCodeMode()` (the older `useDevMode()` remains as a deprecated alias).
+(`NODE_ENV` / Vite). The client hook is `useCodeMode()`. (See
+[Compatibility notes](#compatibility) for the back-compat aliases.)
 
 In the local dev frame, the settings cog toggles between these modes. Switching
 off Code mode hides the frame's own sidebar and shows the app's in-app agent
@@ -128,3 +126,14 @@ pnpm dev
 ```
 
 The local dev frame (the private `@agent-native/frame` package in the framework repo) is an internal tooling package that is not published to npm. It loads the active app's dev server in an iframe and mounts the embedded panel beside it, selecting the app via the `app` query param. The integrated CLI terminal requires Agent Native Desktop, which provides the local code and PTY access the terminal needs; without it, the panel shows the chat surface and prompts you to open Desktop to use the CLI.
+
+## Compatibility notes {#compatibility}
+
+The "Code mode" concept was previously named "dev mode," so a few back-compat
+names persist. You can ignore these unless you are maintaining older integration
+code:
+
+- The underlying `AGENT_MODE` env var, the `/_agent-native/agent-chat/mode`
+  endpoint (whose payload key is still `devMode`), and the `agent-chat.mode`
+  settings key are unchanged.
+- `useDevMode()` remains as a deprecated alias for `useCodeMode()`.