@agent-native/core 0.62.1 → 0.63.1

package/docs/content/getting-started.md

@@ -1,42 +1,53 @@
 ---
 title: "Getting Started"
-description: "Start with one headless action, or start with Chat when the conversation UI is the product."
+description: "Create an agent app — with a chat UI or headless — add an action, and watch the agent call it."
 ---
 
 # Getting Started
 
-Agent-Native is for apps where an AI agent and any UI around it share the same
-actions, data, and state. The smallest useful app can be just one action. The
-first useful UI can be Chat. Both paths use the same runtime, so you can move
-between them without rewriting the operation the agent calls.
+Agent-Native apps give an AI agent and your UI the same actions, data, and
+state. The smallest useful app is a single action.
 
-Choose the first path that matches what you want to prove:
+**Want a complete app to start from?** Clone one of our rich templates —
+[Chat](/docs/template-chat), [Mail](/docs/template-mail),
+[Calendar](/docs/template-calendar), [Content](/docs/template-content),
+[Analytics](/docs/template-analytics), and [many more](/docs/cloneable-saas) —
+each a full-featured app you customize.
 
-| Path                | Pick it when                                                                                                    | Creates                                                             |
-| ------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| **Headless action** | You want the primitive first: one local action, the app-agent loop, CLI/HTTP/MCP/A2A, and no custom screen yet. | `actions/`, `.agents/`, runtime config, local SQLite state          |
-| **Chat app**        | You want a browser app users can talk to immediately, with durable threads and tool-call UI.                    | Everything above, plus the Chat route, sidebar, auth, and live sync |
+Building from scratch? The only choice up front is whether you want a UI —
+everything after (defining actions, running the agent) is the same either way.
 
-If you already know you want a finished domain app, go to
-[Templates](/docs/cloneable-saas). If you are choosing between headless, chat,
-embedded, or full app surfaces, go to [Agent Surfaces](/docs/agent-surfaces).
+## 1. Create your app
 
-## Path 1: One headless action {#headless-action}
+You'll need [Node.js 22+](https://nodejs.org) and [pnpm](https://pnpm.io).
 
-You'll need [Node.js 22 or newer](https://nodejs.org) and
-[pnpm](https://pnpm.io) installed. Then run:
+**Want a UI?** Start from the Chat template. You get a working agent plus a
+customizable chat UI, and every action you add shows up in it automatically:
+
+```bash
+npx @agent-native/core@latest create my-app --template chat
+```
+
+**Just the headless primitive?** Start headless — the same actions and agent
+loop, no UI shell:
 
 ```bash
 npx @agent-native/core@latest create my-agent --headless
-cd my-agent
+```
+
+Then install:
+
+```bash
+cd my-app
 pnpm install
-pnpm action hello --name Steve
-pnpm agent "Call the hello action for Steve and explain what happened."
 ```
 
-That is the primitive-first on-ramp: one action, no app screen, and the same
-production app-agent loop used by chat, jobs, webhooks, and hosted runtimes.
-The scaffold includes one example action:
+From here on, the two are identical.
+
+## 2. Add an action
+
+An action is one operation your agent — and your UI — can call. Both scaffolds
+ship with this example:
 
 ```ts
 // actions/hello.ts
@@ -56,163 +67,106 @@ export default defineAction({
 });
 ```
 
-Replace `hello` with the smallest real operation in your domain. That one
-operation is then callable through the CLI, HTTP, MCP, A2A, scheduled jobs,
-integration webhooks, and any future UI.
-
-Headless does not mean stateless. Actions, auth/session data, application
-state, threads, run history, credentials, and share records use SQL. Locally
-that defaults to SQLite at `data/app.db`; in production you will usually set
-`DATABASE_URL`. See [Deployment](/docs/deployment).
+Replace `hello` with the smallest real operation in your domain. You define it
+once; every surface picks it up.
 
-## Path 2: Chat app {#chat-app}
+## 3. Run it
 
-Use Chat when the first thing users need is a conversation UI with durable
-threads and visible tool calls:
+Call the action directly:
 
 ```bash
-npx @agent-native/core@latest create my-chat-app --template chat
-cd my-chat-app
-pnpm install
-pnpm dev
+pnpm action hello --name Steve
 ```
 
-Open the local URL, then ask the chat what actions are available. The Chat
-template includes the same `actions/hello.ts` shape as the headless scaffold,
-plus a full-page chat route, the standard left sidebar, auth, live sync, and a
-SQLite database at `data/app.db` unless you set `DATABASE_URL`.
-
-Run the example action directly:
+Or ask the agent to call it for you:
 
 ```bash
-pnpm action hello --name Steve
+pnpm agent "Call the hello action for Steve and explain what happened."
 ```
 
-Then run the same app-agent loop from the terminal:
+If you started from the Chat template, run the app and use the same agent in the
+browser — it can already call every action you define:
 
 ```bash
-pnpm agent "Call the hello action for Steve and explain what happened."
+pnpm dev
 ```
 
-The chat UI, CLI, HTTP, MCP, A2A, jobs, and future screens all call the same
-action surface.
-
-## Move between paths {#move-between-paths}
+That one action is now reachable from the chat UI, the CLI, HTTP, MCP, A2A,
+scheduled jobs, and webhooks. Define once, call from anywhere.
 
-Headless and Chat are not separate products. Start headless when you want the
-operation first. Add Chat when a durable conversation UI helps users inspect,
-approve, or continue the work. Start with Chat when the conversation itself is
-the main workflow, then add screens only where structured UI clarifies the job.
+## State is built in
 
-For a deeper comparison, see [Agent Surfaces](/docs/agent-surfaces). For the
-Chat template reference, see [Chat template](/docs/template-chat).
+Headless doesn't mean stateless. Actions, sessions, application state, threads,
+run history, and credentials all live in SQL. Locally that's SQLite at
+`data/app.db`; in production you set `DATABASE_URL`. See
+[Deployment](/docs/deployment).
 
-## Run against a connected repo {#connected-repo}
+## Customize the UI
 
-For a cloud headless app that works on repository files, connect GitHub through
-the connector/token model rather than cloning a long-lived sandbox checkout.
-The agent can list, search, read, create, update, and delete repository files
-through provider-scoped credentials.
+If you started from the Chat template, the UI is yours to edit. The chat itself
+is one small route built on the `<AgentChatSurface>` component:
 
-In local development, use the same shape with explicit environment variables:
+```tsx
+// app/routes/_index.tsx
+import { AgentChatSurface } from "@agent-native/core/client";
 
-```bash
-GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action."
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-full" />;
+}
 ```
 
-The repo becomes context for the app-agent loop and `agent-native invoke`
-calls. This path is for repository CRUD over the GitHub API. Use a sandbox or
-Fusion-style code runtime only when you need true isolated code execution.
+- **`app/routes/_index.tsx`** — the chat page. Change the suggestions, empty
+  state, and layout.
+- **`app/root.tsx`** — the app shell. Add your own routes and screens around the
+  agent.
+- Drop the agent into any screen with `<AgentSidebar>`, hand work to it from a
+  button with `sendToAgentChat()`, or run an action directly with
+  `useActionMutation()`.
+
+See [Drop-in Agent](/docs/drop-in-agent) for the full component set, and
+[Native Chat UI](/docs/native-chat-ui) to render action results as tables,
+charts, and typed cards instead of plain text.
 
-## Compose mini-apps {#compose-mini-apps}
+**Started headless and want a UI later?** The Chat template _is_ the UI on-ramp —
+its `app/` layer (React Router + Vite) is exactly what the headless scaffold
+leaves out. The cleanest move is to start (or re-scaffold) from the Chat
+template; your `actions/`, agent, and SQL state carry over unchanged. See
+[Agent Surfaces](/docs/agent-surfaces) for every surface in between.
 
-Workspaces often become easier to reason about as several focused apps instead
-of one giant app. A `hubspot-pipeline` app can own CRM access, a
-`gong-evidence` app can own transcripts, and a `deal-brief` app can call both
-through A2A.
+## Compose mini-apps
 
-From the CLI:
+A big workspace is usually easier to reason about as a few focused apps than one
+giant one. A `hubspot-pipeline` app can own CRM access, a `gong-evidence` app can
+own transcripts, and a `deal-brief` app can call both over A2A:
 
 ```bash
 pnpm agent-native agents list
 pnpm agent-native invoke gong-evidence "Find transcript evidence for deal_123."
 ```
 
-From TypeScript:
-
-```ts
-import { agentNative } from "@agent-native/core/agent-native";
-
-const agents = await agentNative.listAgents();
-const result = await agentNative.invoke(
-  "gong-evidence",
-  "Find transcript evidence for deal_123.",
-  { userEmail: "steve@example.com" },
-);
-```
-
-For production agent-native apps, set `A2A_SECRET` in each app environment and
-pass the caller identity (`userEmail`) so outbound calls are signed. Use
-`apiKeyEnv` only for legacy external peers that expect a static bearer token.
-
-See [A2A Protocol](/docs/a2a-protocol) and
-[Pure Agent Apps](/docs/pure-agent-apps) for the full pattern.
-
-## What just happened? {#what-just-happened}
-
-You now have a real app-agent loop:
-
-- `hello` is one action definition, available to the agent, CLI, HTTP, MCP,
-  A2A, and any future UI.
-- `pnpm agent` calls the production app-agent loop, not an external coding
-  harness.
-- Changes and history stay in sync because the runtime uses SQL-backed state,
-  even when you have no custom UI yet.
-
-That parity between agent and UI is the whole point. See
-[What Is Agent-Native?](/docs/what-is-agent-native) for the bigger picture.
-
-## Project structure {#project-structure}
+Each app keeps its own actions, agent, and state, and can discover its siblings.
+See [Multi-App Workspaces](/docs/multi-app-workspace) and
+[A2A Protocol](/docs/a2a-protocol).
 
-Every agent-native app follows the same structure:
+## Project structure
 
 ```text
 my-app/
   actions/         # Agent-callable actions
-  app/             # React frontend in UI templates; omitted in headless apps
+  app/             # React frontend (UI templates only; omitted when headless)
   server/          # Nitro API server (routes, plugins)
   .agents/         # Agent instructions and skills
-  data/app.db      # Local SQLite runtime state when DATABASE_URL is unset
+  data/app.db      # Local SQLite state when DATABASE_URL is unset
 ```
 
-Templates add domain-specific code on top: database schemas in `server/db/`,
-API routes in `server/routes/api/`, and actions in `actions/`. See
-[Creating Templates](/docs/creating-templates) when you are ready to build or
-publish a reusable template.
-
-## Common next moves {#next-docs}
-
-Once your agent is running, the usual next step is small and concrete:
-
-- **Add one real action** - replace `hello` with the smallest useful operation
-  in your domain.
-- **Open Chat when conversation helps** - ask "what actions do you have, and
-  what can you do here?"
-- **Connect a repo** - give the app-agent loop explicit GitHub repository
-  context when file CRUD is the job.
-- **Compose siblings** - split provider-heavy workflows into focused mini-apps
-  and invoke them over A2A.
-- **Deploy it** - see [Deployment](/docs/deployment) when you're ready to put
-  the app on your own domain.
-
-Useful follow-up docs:
-
-- [Key Concepts](/docs/key-concepts) for the architecture: SQL, actions,
-  polling sync, and context awareness
-- [Agent Surfaces](/docs/agent-surfaces) for choosing headless, rich chat,
-  embedded, and full-app surfaces
-- [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
+## Where to go next
+
+- **[Key Concepts](/docs/key-concepts)** — the core architecture: SQL, actions,
+  sync, and context awareness.
+- **[Actions](/docs/actions)** — the full action API: schemas, HTTP, auth, and
+  approval.
+- **[Agent Surfaces](/docs/agent-surfaces)** — headless, chat, embedded sidecar,
+  and full app.
+- **[Drop-in Agent](/docs/drop-in-agent)** — add the agent chat to any React app.
+- **[Deployment](/docs/deployment)** — put your app on your own domain.
+- **[FAQ](/docs/faq)** — setup and product questions.

package/docs/content/harness-agents.md

@@ -6,6 +6,10 @@ search: "harness agents AgentHarness ai-sdk HarnessAgent Claude Code Codex Pi Cu
 
 # Harness Agents
 
+> **Who is this for:** host authors wiring a full coding runtime (Claude Code,
+> Codex, Pi) into Agent-Native as the agent. Building an app? Start with
+> [Creating Templates](/docs/creating-templates).
+
 A harness agent is a full agent runtime — Claude Code, Codex, Pi, and similar —
 that owns its own loop, workspace, native file tools, session state, compaction,
 approval model, and sandbox behavior. Agent-Native runs these through the
@@ -19,13 +23,19 @@ beneath `runAgentLoop`. A harness is not an `AgentEngine` provider — it runs i
 own loop end to end, so Agent-Native drives it as a session, not as a single
 model call.
 
-| You want to…                                                               | Use                                                           |
-| -------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| Run Claude Code / Codex / Pi **as the agent**, with their own loop + tools | **Harness agents** (this page)                                |
-| Put an agent you built elsewhere behind Agent-Native's **chat UI**         | [`AgentChatRuntime`](/docs/native-chat-ui#byo-agent-runtimes) |
-| Let an external MCP host (Claude Code, Cursor, …) **call into your app**   | [External Agents](/docs/external-agents)                      |
-| Render a Claude-Code/Codex-style **coding workspace UI**                   | [Agent-Native Code UI](/docs/code-agents-ui)                  |
-| Spawn background / sub-agent runs and teams                                | [Custom Agents & Teams](/docs/agent-teams)                    |
+## Which coding doc do I want? {#which-doc}
+
+| You want to…                                                               | Use                                          |
+| -------------------------------------------------------------------------- | -------------------------------------------- |
+| Run Claude Code / Codex / Pi **as the agent**, with their own loop + tools | **Harness agents** (this page)               |
+| Render a Claude-Code/Codex-style **coding workspace UI**                   | [Agent-Native Code UI](/docs/code-agents-ui) |
+| Swap the backend that runs the agent's **`run-code` tool**                 | [Adapters](/docs/sandbox-adapters)           |
+| Wrap a CLI tool (`gh`, `ffmpeg`) for the agent to call                     | [Adapters](/docs/sandbox-adapters)           |
+
+Adjacent surfaces: put an agent you built elsewhere behind Agent-Native's chat
+UI with [`AgentChatRuntime`](/docs/native-chat-ui#byo-agent-runtimes); let an
+external MCP host call into your app via [External Agents](/docs/external-agents);
+spawn background / sub-agent runs with [Custom Agents & Teams](/docs/agent-teams).
 
 ## Built-in harnesses {#built-in}
 
@@ -45,6 +55,13 @@ app that never uses a harness does not pay for it. Each adapter carries an
 error if the packages are missing, and `isAgentHarnessPackageInstalled(entry)`
 lets you check first.
 
+Codex auth has two paths. The `ai-sdk-harness:codex` adapter loads the AI SDK
+Codex harness package and does not implement a separate Agent-Native OAuth flow.
+For Agent-Native Code or Desktop coding sessions, Agent-Native can use the
+local Codex CLI after the user runs `codex login`; that reuses whatever
+ChatGPT subscription or API-key auth the installed Codex CLI reports through
+`codex login status`.
+
 ## Register and resolve {#register-resolve}
 
 ```ts

package/docs/content/human-approval.md

@@ -77,7 +77,7 @@ On `approval_required`, the chat UI renders an **Approve / Deny** affordance on
 
 ## End-to-end {#flow}
 
-```txt
+```text
 agent calls send-email
    │
    ▼

package/docs/content/key-concepts.md

@@ -5,20 +5,7 @@ description: "How agent-native apps work: actions first, SQL database, app-agent
 
 # Key Concepts
 
-How agent-native apps work under the hood — the principles, the architecture, and why they're built this way.
-
-## Why agent-native {#why-agent-native}
-
-Teams today have four options for AI-powered work, and none of them are ideal:
-
-1. **Chat apps** (Claude Projects, ChatGPT) — accessible but not built for structured workflows. No persistent UI, no dashboards, no team collaboration.
-2. **Raw agent interfaces** (Claude Code, Cursor) — powerful but inaccessible to non-devs. No guardrails, no onboarding, no structured UI.
-3. **Custom AI apps** — limited. The AI can't see what you see, can't react to what you click, and can't update the app itself. No conversation history, no rollback, no skills.
-4. **Existing SaaS** (Amplitude, HubSpot, Google Slides) — bolting AI onto architectures that weren't designed for it. You can feel the seams.
-
-Agent-native apps solve this by making the agent and any UI equal citizens of the same system. Think of it as Claude Code, but with durable actions, SQL state, and visual interfaces when the workflow needs them. A workflow can start as one callable action, then grow into chat, screens, schedules, or a full app without rewriting the operation.
-
-See [What Is Agent-Native?](/docs/what-is-agent-native) for the full vision and philosophy.
+How agent-native apps work under the hood — the principles and the architecture. This page is the contract; for the vision and the case for building this way, see [What Is Agent-Native?](/docs/what-is-agent-native).
 
 ## The architecture {#the-architecture}
 
@@ -56,7 +43,7 @@ A feature with only UI is invisible to the agent. A full UI feature with only ac
 
 ## Data in SQL {#data-in-sql}
 
-All application state lives in a SQL database via Drizzle ORM. The framework supports multiple databases — SQLite, Postgres (Neon, Supabase), Turso, Cloudflare D1. Users configure `DATABASE_URL` to choose their database.
+All application state lives in a SQL database via Drizzle ORM. Schemas are provider-agnostic; the supported databases, `DATABASE_URL` config, and portability rules live in [Database](/docs/database).
 
 Core SQL stores are auto-created and available in every template:
 
@@ -186,43 +173,11 @@ The UI writes this on route change; the agent reads it (via `view-screen`) befor
 
 See [Context Awareness](/docs/context-awareness) for the full pattern: navigation state, view-screen, navigate commands, and jitter prevention.
 
-## One action, many protocols {#protocols}
-
-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.
+## One action, many surfaces {#protocols}
 
-| 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, and typed app results in chat.                                        | Structured action results                         |
-| AgentChatRuntime connectors | Shipping            | The chat shell can sit on top of OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI, or normalized HTTP streams.                   | Pick a runtime helper or stream normalized events |
-| HTTP and CLI                | Shipping            | Actions auto-mount at `/_agent-native/actions/:name`, run via `pnpm action <name>`, and can be driven by the headless app-agent loop with `pnpm agent`. | 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()`                |
-| ACP                         | Coding-agent/editor | Useful for coding agents inside editors/IDEs; not the general BYO app-chat runtime contract.                                                            | Editor/agent adapter work                         |
+Implement a domain operation once as an action; the framework exposes it to every consumer. The same `defineAction()` becomes an agent tool, a typesafe UI hook, an HTTP endpoint, a CLI command, an MCP tool, and an A2A tool, with optional `link`, `mcpApp`, or explicit native-widget metadata added only when a surface needs it. Skills and instructions cover behavior.
 
-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, AgentChatRuntime connectors, CLI commands, and deep-link handoffs are adapters around that same core.
-
-Adapter horizon: [A2UI](https://a2ui.org/) is worth watching for portable generated UI across trust boundaries, but first-party Agent-Native widgets should stay explicit native renderers. [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. See [Agent Surfaces](/docs/agent-surfaces) for the concrete choice guide and APIs.
+For the full protocol/surface matrix (MCP server and OAuth, MCP Apps, A2A, deep links, native chat widgets, AgentChatRuntime connectors, Agent Web, and the adapter horizon for ACP and A2UI), and for choosing a product shape — headless, rich chat, embedded sidecar, or full app — see [Agent Surfaces](/docs/agent-surfaces).
 
 ## Agent modifies code {#agent-modifies-code}
 
@@ -236,64 +191,24 @@ There's no shared codebase to break. You own the app, and the agent evolves it f
 4. "Connect to our Stripe account" — the agent writes the integration
 5. Your app keeps improving without manual development
 
-## Database agnostic {#database-agnostic}
-
-The framework supports portable Drizzle-backed SQL databases. Write app schemas with `@agent-native/core/db/schema` and app reads/writes with Drizzle's query builder so code can run across providers.
+## Portable by default {#hosting-agnostic}
 
-- **SQLite** — local dev fallback when `DATABASE_URL` is unset
-- **Neon Postgres** — common in both dev and production
-- **Turso** (libSQL) — edge-friendly SQLite-compatible
-- **Supabase Postgres**
-- **Cloudflare D1**
-- **Plain Postgres**
+Two architectural rules keep apps portable across databases and hosts:
 
-Use Drizzle's portable query DSL for normal app code:
-
-```ts
-import { and, desc, eq } from "drizzle-orm";
-
-const forms = await db
-  .select()
-  .from(schema.forms)
-  .where(
-    and(eq(schema.forms.ownerEmail, email), eq(schema.forms.status, "open")),
-  )
-  .orderBy(desc(schema.forms.createdAt));
-```
-
-Use raw SQL only for additive migrations, health checks, or one-off maintenance, and keep it parameterized and dialect-agnostic.
-
-## Hosting agnostic {#hosting-agnostic}
-
-The server runs on Nitro, which compiles to any deployment target:
-
-- Node.js — local dev, traditional servers
-- Cloudflare Workers/Pages
-- Netlify Functions/Edge
-- Vercel Serverless/Edge
-- Deno Deploy
-- AWS Lambda
-- Bun
-
-Never use Node-specific APIs (`fs`, `child_process`, `path`) in server routes or plugins. These don't exist in Workers/edge environments. Actions in `actions/` run in Node.js and can use Node APIs freely.
-
-Never assume a persistent server process. Serverless and edge environments are stateless — no in-memory caches, no long-lived connections. Use the SQL database for all state.
+- **Database-agnostic.** Write schemas with `@agent-native/core/db/schema` and reads/writes with Drizzle's portable query DSL so the same code runs on any supported provider. Use raw SQL only for additive migrations or one-off maintenance, kept parameterized and dialect-agnostic. See [Database](/docs/database).
+- **Hosting-agnostic.** The server runs on Nitro and compiles to any deployment target. Never use Node-specific APIs (`fs`, `child_process`, `path`) in server routes or plugins, and never assume a persistent server process — serverless and edge are stateless, so keep all state in SQL. See [Deployment](/docs/deployment).
 
 ## Workspace {#workspace}
 
 Every user gets a personal **workspace** — instructions, skills, memory, custom sub-agents, scheduled jobs, and connected MCP servers — all stored in SQL rather than files. That makes Claude-Code-level customization viable inside multi-tenant SaaS without spinning up a container per user. See [Workspace](/docs/workspace).
 
-## Dispatch {#dispatch}
-
-**Dispatch** is the workspace control plane: a central inbox for Slack/email/Telegram, a shared secrets vault, scheduled jobs, and an orchestrator agent that delegates domain work to specialist apps over A2A. Run it alongside your domain apps when you have more than one. See [Dispatch](/docs/dispatch).
-
-## Extensions {#extensions}
-
-**Extensions** are sandboxed mini-apps the agent can create at runtime — Alpine.js HTML rendered inside an iframe, with built-in helpers for persistent storage (`extensionData`), calling app actions (`appAction`), and proxied external APIs (`extensionFetch`). No source-code changes, no schema migrations. (Distinct from LLM "tools" — the function-call surface area the agent uses, e.g. `defineAction` entries and MCP tools. See [Extensions](/docs/extensions).)
+## Related building blocks {#building-blocks}
 
-## A2A {#a2a}
+These sit on top of the same contract and have their own deep dives:
 
-Agent-to-agent (**A2A**) is how apps in the same workspace discover and call each other. Each app publishes an agent card with skill metadata; other agents can invoke its actions over JSON-RPC. Same-origin deploys skip JWT; cross-origin uses a shared secret. See [A2A Protocol](/docs/a2a-protocol).
+- **[Dispatch](/docs/dispatch)** — the workspace control plane: shared inbox, secrets vault, scheduled jobs, and an orchestrator that delegates to specialist apps over A2A.
+- **[Extensions](/docs/extensions)** — sandboxed Alpine.js mini-apps the agent creates at runtime, no source changes or migrations.
+- **[A2A Protocol](/docs/a2a-protocol)** — how apps in the same workspace discover and call each other over JSON-RPC.
 
 ## What you get for free {#what-you-get-for-free}
 

package/docs/content/local-file-mode.md

@@ -50,7 +50,7 @@ to SQL rows or local files.
 
 A Content workspace can be as small as this:
 
-```txt
+```text
 my-content-repo/
   agent-native.json
   docs/
@@ -285,7 +285,7 @@ Local File Mode can also load repo-backed extensions from the configured
 `extensions` folder. Each extension is one directory with an `extension.json`
 manifest and an HTML entry file:
 
-```txt
+```text
 extensions/
   doc-status/
     extension.json

package/docs/content/mcp-apps.md

@@ -5,9 +5,16 @@ description: "Author and embed interactive MCP App UIs inside Claude, ChatGPT, a
 
 # MCP Apps
 
-MCP Apps are the official `io.modelcontextprotocol/ui` extension that lets compatible hosts — Claude, Claude Desktop, ChatGPT, VS Code GitHub Copilot, Goose, Postman, MCPJam, and Cursor — render interactive UIs inline in chat. In agent-native apps, every MCP App is a **real React route**, not a separate plain-HTML widget.
+**This page: inline UIs in Claude/ChatGPT.** Authoring MCP App resources and the embed bridge that renders a real app route inside a compatible host's chat. This page is also the single home for the **client support matrix** ([below](#client-support)).
+
+| If you want to…                                              | Read                                     |
+| ------------------------------------------------------------ | ---------------------------------------- |
+| Connect an external agent/host to your app                   | [External Agents](/docs/external-agents) |
+| Give your agent more tools (consume other MCP servers)       | [MCP Clients](/docs/mcp-clients)         |
+| Build inline UIs that render in Claude/ChatGPT               | **This page** — MCP Apps                 |
+| Lower-level MCP server reference (auth, tools, custom mount) | [MCP Protocol](/docs/mcp-protocol)       |
 
-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.
+MCP Apps are the official `io.modelcontextprotocol/ui` extension that lets compatible hosts — Claude, Claude Desktop, ChatGPT, VS Code GitHub Copilot, Goose, Postman, MCPJam, and Cursor — render interactive UIs inline in chat. In agent-native apps, every MCP App is a **real React route**, not a separate plain-HTML widget.
 
 Inside an Agent-Native app's own chat, prefer [native chat renderers](/docs/native-chat-ui) for first-party widgets such as tables, charts, typed results, and approval affordances. Use MCP Apps for external/cross-host inline UI in Claude, ChatGPT, Copilot, Cursor, and other compatible hosts, with the action `link` as the universal deep-link fallback.
 

package/docs/content/mcp-clients.md

@@ -5,9 +5,14 @@ description: "Connect your agent-native app to local MCP servers (claude-in-chro
 
 # MCP Clients
 
-Agent-native apps can also act as MCP **clients** — connecting to locally installed MCP servers and exposing their tools to the agent chat. This is the symmetric counterpart to the [MCP Protocol](/docs/mcp-protocol) (which makes your app an MCP server).
-
-Looking for the other direction — connecting Claude, ChatGPT, Claude Code, Codex, Cursor, or Claude Cowork to an agent-native app? Use [External Agents](/docs/external-agents).
+**This page: give your agent more tools.** Point an agent-native app at MCP servers — local or remote — so their tools show up in the agent chat. This is the _client_ direction, the mirror image of [MCP Protocol](/docs/mcp-protocol) (which makes your app an MCP _server_).
+
+| If you want to…                                              | Read                                     |
+| ------------------------------------------------------------ | ---------------------------------------- |
+| Connect an external agent/host to your app                   | [External Agents](/docs/external-agents) |
+| Give your agent more tools (consume other MCP servers)       | **This page** — 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)       |
 
 With one config file, every agent-native app in your workspace gains access to tools provided by MCP servers on your machine: `claude-in-chrome` for browser automation, `@modelcontextprotocol/server-filesystem` for reading files, `@playwright/mcp` for browser testing, and anything else that speaks MCP.