@agent-native/core 0.149.6 → 0.151.1

package/docs/content/extensions.mdx

@@ -268,27 +268,27 @@ Everything from here through [Local File Extensions](#local-file-extensions) is
 
 Inside the iframe sandbox, every extension has these helpers on `window`:
 
-| Helper                                           | Purpose                                                   | Example                                                   |
-| ------------------------------------------------ | --------------------------------------------------------- | --------------------------------------------------------- |
-| `appAction(name, params)`                        | Call any of the host template's actions, including writes | `appAction('list-emails', { view: 'inbox' })`             |
-| `appFetch(path, options)`                        | Call allowed framework endpoints under `/_agent-native/*` | `appFetch('/_agent-native/application-state/navigation')` |
-| `dbQuery(sql, args)`                             | Read from SQL (auto-scoped to the user; never for writes) | `dbQuery('SELECT id, name FROM tools')`                   |
-| `dbExec(sql, args)`                              | Legacy trusted SQL writes for editor/admin extensions     | Prefer `appAction` for app data writes                    |
-| `extensionFetch(url, options)`                   | Hit external APIs through a secure proxy with secrets     | `extensionFetch('https://api.github.com/user')`           |
-| `extensionData.set(collection, id, data, opts?)` | Persist data per-extension (user / org scoping)           | `extensionData.set('notes', id, { text: '...' })`         |
-| `extensionData.list(collection, opts?)`          | List persisted items                                      | `extensionData.list('notes', { scope: 'all' })`           |
-| `extensionData.get(collection, id, opts?)`       | Get a single item                                         | `extensionData.get('notes', 'note-1')`                    |
-| `extensionData.remove(collection, id, opts?)`    | Delete a persisted item                                   | `extensionData.remove('notes', 'note-1')`                 |
-| `window.slotContext`                             | Read the page/chat context passed into this slot          | `window.slotContext?.contactEmail`                        |
-| `agentNative.ui.output(value, opts?)`            | Record passive inline UI output in application state      | `agentNative.ui.output({ threshold })`                    |
-| `agentNative.chat.send(message, opts?)`          | Send a prompt or selected value back to the agent chat    | `agentNative.chat.send('Use Q2', { context: { q: 2 } })`  |
+| Helper                                           | Purpose                                                   | Example                                                                |
+| ------------------------------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `appAction(name, params)`                        | Call any of the host template's actions, including writes | `appAction('list-emails', { view: 'inbox' })`                          |
+| `appFetch(path, options)`                        | Call allowed framework endpoints under `/_agent-native/*` | `appFetch('/_agent-native/application-state/navigation')`              |
+| `dbQuery(sql, args)`                             | Read from SQL (auto-scoped to the user; never for writes) | `dbQuery('SELECT id, name FROM tools')`                                |
+| `dbExec(sql, args)`                              | Legacy trusted SQL writes for editor/admin extensions     | Prefer `appAction` for app data writes                                 |
+| `extensionFetch(url, options)`                   | Hit external APIs through a secure proxy with secrets     | `extensionFetch('https://api.github.com/user')`                        |
+| `extensionData.set(collection, id, data, opts?)` | Persist data per-extension (user / org scoping)           | `extensionData.set('notes', id, { text: '...' })`                      |
+| `extensionData.list(collection, opts?)`          | List persisted items                                      | `extensionData.list('notes', { scope: 'all' })`                        |
+| `extensionData.get(collection, id, opts?)`       | Get a single item                                         | `extensionData.get('notes', 'note-1')`                                 |
+| `extensionData.remove(collection, id, opts?)`    | Delete a persisted item                                   | `extensionData.remove('notes', 'note-1')`                              |
+| `window.slotContext`                             | Read the page/chat context passed into this slot          | `window.slotContext?.contactEmail`                                     |
+| `agentNative.ui.output(value, opts?)`            | Record passive inline UI output in application state      | `agentNative.ui.output({ threshold })`                                 |
+| `agentNative.chat.send(message, opts?)`          | Send a prompt or selected value back to the agent chat    | `agentNative.chat.send('Use Q2', { submit: true, context: { q: 2 } })` |
 
 Three rules of thumb:
 
 - **Prefer `appAction` over raw SQL.** Actions are the template's official surface — they handle access control, scoping, and validation for you. `dbQuery` is read-only; `dbExec` remains for legacy trusted editor/admin extensions, but new app data writes should go through actions.
 - **Use `appAction` for template data.** Extension `appFetch` is limited to framework `/_agent-native/*` endpoints; template `/api/*` routes are blocked by the iframe bridge.
 - **Prefer `extensionData` over making new tables.** Each extension gets its own isolated key-value store. No schema, no migration. Set `{ scope: 'org' }` to share with the user's org, `'user'` (default) for private.
-- **Use `agentNative.ui.output` for inline control values the agent should read later.** It writes `inline-ui:<extensionId>:output` to application state; `agentNative.chat.send` is for visible submit/apply messages.
+- **Use `agentNative.ui.output` for inline control values the agent should read later.** It writes `inline-ui:<extensionId>:output` to application state; `agentNative.chat.send` is draft-only unless `{ submit: true }` is passed for a user-triggered submit/apply message. Never call it from polling, refresh, or error handlers.
 
 ```html
 <script>

package/docs/content/file-uploads.mdx

@@ -1,6 +1,6 @@
 ---
 title: "File Uploads"
-description: "Configure file upload storage — SQL fallback for dev, Builder.io or custom providers for production."
+description: "Configure durable file upload storage — Builder.io or custom object storage for production."
 ---
 
 # File Uploads
@@ -15,9 +15,9 @@ The provider resolution order is:
 
 1. **User-registered providers** — custom providers registered via `registerFileUploadProvider()`
 2. **Builder.io provider** — built-in, activates automatically when Builder.io is connected
-3. **SQL fallback** — stores files as base64 in the database (fine for dev, not for production)
+3. **No provider** — the upload is rejected and the chat renders a storage setup CTA; binary data is never persisted in SQL
 
-<Diagram id="doc-block-hq5uvx" title="Provider resolution order" summary="uploadFile() picks the first configured provider in order. The SQL fallback always exists so uploads work with zero setup.">
+<Diagram id="doc-block-hq5uvx" title="Provider resolution order" summary="uploadFile() picks the first configured provider in order. Without one, the upload fails closed so binary data is never persisted in SQL.">
 
 ```html
 <div class="diagram-upload">
@@ -47,8 +47,8 @@ The provider resolution order is:
     <div class="diagram-step">
       <span class="diagram-pill warn">3</span>
       <div class="diagram-node">
-        SQL fallback<br /><small class="diagram-muted"
-          >base64 in DB — dev only</small
+        No provider<br /><small class="diagram-muted"
+          >setup CTA — no binary persistence</small
         >
       </div>
     </div>
@@ -94,15 +94,13 @@ Dispatches to the first configured provider in resolution order. Check the activ
 
 </Endpoint>
 
-## Default: SQL Fallback {#sql-fallback}
+## Storage required for durable uploads {#storage-required}
 
-When no provider is configured, files are stored as base64 data in the SQL database via the resources system. This works out of the box for local development but is not recommended for production — large files bloat the database and there's no CDN.
-
-A one-time warning is logged when the fallback is used.
+When no provider is configured, `uploadFile()` returns `null` and the multipart route returns `503`. Chat attachments remain available only for the current request, the agent receives a storage setup hint, and the transcript stores a setup marker instead of the binary payload. This fail-closed behavior keeps SQL small and makes the missing configuration visible.
 
 ## Builder.io Hosting {#builder-hosting}
 
-When your app is connected to Builder.io, file uploads are automatically routed to Builder's asset hosting. Builder.io's free tier includes this managed storage. Files are served from a CDN with no configuration needed. This is the recommended production setup.
+When your app is connected to Builder.io, file uploads are automatically routed to Builder's asset hosting. Builder.io's free tier includes this managed storage. Files are served from a CDN with no configuration needed, and the durable URL is stored in the chat thread so later turns can reuse it. This is the recommended production setup.
 
 ## Custom Providers {#custom-providers}
 
@@ -159,7 +157,7 @@ interface FileUploadInput {
   data: Uint8Array | Buffer; // File contents
   filename?: string; // Original filename
   mimeType?: string; // MIME type, e.g. "image/png"
-  ownerEmail?: string; // For per-user scoping in fallback
+  ownerEmail?: string; // For request-scoped provider credentials
 }
 
 interface FileUploadResult {
@@ -183,7 +181,7 @@ const result = await uploadFile({
 if (result) {
   // Provider handled it — result.url is the public URL
 } else {
-  // No provider configured — handle SQL fallback yourself, or skip
+  // No provider configured — show the storage setup CTA, or skip
 }
 ```
 

package/docs/content/generative-ui.mdx

@@ -222,12 +222,17 @@ Generated UI can send a visible prompt or result back into the current app chat:
 `agentNative.chat.send(message, options)` is also available as
 `sendToAgentChat(message, options)`.
 
+For generated extensions, chat messages are draft-only unless `submit: true` is
+passed explicitly. Use that opt-in only from a user-triggered Apply or Submit
+action. Do not call either helper from polling, refresh, or error handlers; use
+`agentNative.ui.output` or application state for passive results.
+
 Options:
 
 | Option        | Default | Effect                                           |
 | ------------- | ------- | ------------------------------------------------ |
 | `context`     | none    | hidden context appended to the submitted message |
-| `submit`      | `true`  | `false` pre-fills/reviews instead of auto-submit |
+| `submit`      | `false` | `true` auto-submits; `false` pre-fills/reviews   |
 | `openSidebar` | `true`  | opens the agent sidebar when the message is sent |
 
 This is the same app chat bridge used by normal UI components, so generated

package/docs/content/key-concepts.mdx

@@ -1,21 +1,21 @@
 ---
 title: "Key Concepts"
-description: "How agent-native apps work across three layers: the Core framework, optional Toolkit building blocks, and optional Templates, plus the shared actions, SQL database, app-agent loop, and portability contract."
+description: "How agent-native apps work across three layers: the Core framework, optional Toolkit building blocks, and optional Templates, plus the shared actions, SQL database, app-agent loop, and portability rules."
 ---
 
 # Key Concepts
 
-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).
+How agent-native apps work under the hood: the principles and the architecture. This page is the contract: the fixed rules an app has to follow to count as agent-native. For the vision and the case for building this way, see [What Is Agent-Native?](/docs/what-is-agent-native).
 
 ## The three layers {#three-layers}
 
-Agent Native is a framework, not a single template. It has three layers:
+Agent Native is a framework with three layers:
 
-| Layer                                                    | What it is                                                                                                                                                                                            |
-| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Core - the framework**                                 | The foundational runtime contract: actions, SQL and Drizzle helpers, auth, application state, agent execution, access checks, routing, and live sync. Every app can use Core directly.                |
-| **Toolkit - optional reusable pieces for the framework** | Shared app-building UI and product systems such as primitives, editors, sharing, collaboration, settings, and agent UX. Apps can use, compose, or fork the pieces they need.                          |
-| **Templates - optional apps built on Core**              | Complete, domain-specific apps with routes, schema, actions, instructions, and visual identity. First-party and custom templates commonly use Toolkit, and can be forked and used as starting points. |
+| Layer                                      | What it is                                                                                                                                                                                            |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Core: the framework**                    | The foundational runtime contract: actions, SQL and Drizzle helpers, auth, application state, agent execution, access checks, routing, and live sync. Every app can use Core directly.                |
+| **Toolkit: optional reusable pieces**      | Shared app-building UI and product systems such as primitives, editors, sharing, collaboration, settings, and agent UX. Apps can use, compose, or fork the pieces they need.                          |
+| **Templates: optional apps built on Core** | Complete, domain-specific apps with routes, schema, actions, instructions, and visual identity. First-party and custom templates commonly use Toolkit, and can be forked and used as starting points. |
 
 Core is the foundation. Toolkit and Templates are optional: a template can use Toolkit, but Toolkit is not required to build an app on Core.
 
@@ -23,9 +23,11 @@ Core is the foundation. Toolkit and Templates are optional: a template can use T
 
 At runtime, every agent-native app is three things working together:
 
-- **Agent** — Autonomous AI that reads data, writes data, runs actions, and uses configured tools. It can also modify source when its frame is intentionally granted workspace and write tooling. Customizable with skills and instructions.
-- **Application** — The product surface around the agent. This may start as chat, add native inline results, grow into a small control plane, or become a full React UI with dashboards, flows, and visualizations.
-- **Computer** — Database, browser, and configured tool runtimes. Agents work through the app's action and data surface; an app may expose that same action surface over MCP, while external MCP servers remain optional add-ons rather than the foundation.
+- **Agent:** The autonomous AI. It reads data, writes data, runs actions, and uses whatever tools are configured. When its frame is intentionally granted workspace access and write tooling, it can also modify the app's own source. Customizable with skills and instructions.
+- **Application:** The product surface around the agent. It may start as chat, add native inline results, grow into a small control plane, or become a full React UI with dashboards, flows, and visualizations.
+- **Computer:** The database, browser, and configured tool runtimes the agent acts through. Agents work through the app's own action and data surface; that same surface can optionally be exposed over MCP, but external MCP servers stay an add-on, not the foundation.
+
+The diagram below shows the agent and the application side by side, both with two-way arrows into one shared computer layer underneath. Neither one owns the data. Instead, they read and write the same SQL store, so a change either side makes is visible to the other immediately, with no sync layer to build in between.
 
 <Diagram id="doc-block-t1f7pj" title="Agent, application, and computer" summary="Three layers working together over one shared SQL store. The agent and the application both read and write the same data.">
 
@@ -88,12 +90,13 @@ At runtime, every agent-native app is three things working together:
 
 </Diagram>
 
-Automation-first apps can run the same production app-agent loop from the folder with `pnpm agent`, while UI apps mount the embedded agent panel and run locally with `pnpm dev`. In the cloud, Builder.io provides a managed frame — the environment that hosts the agent next to your app — with collaboration, visual editing, and managed infrastructure for teams.
+That same agent-application-computer loop is what runs locally and in production. Automation-first apps run it straight from the folder with `pnpm agent`; UI apps mount the embedded agent panel and add `pnpm dev`. In the cloud, Builder.io hosts the identical loop as a managed frame: the environment that runs the agent next to your app. It handles collaboration, visual editing, and infrastructure for you.
 
 ## Agent building blocks {#agent-building-blocks}
 
 Every agent-native app has the same agent building blocks, regardless of whether
-the product surface is chat-first, automation-first, or a full UI:
+the product surface is chat-first, automation-first, or a full UI. Each one lives
+in its own file:
 
 <FileTree
   id="doc-block-1ae57y4"
@@ -114,11 +117,13 @@ the product surface is chat-first, automation-first, or a full UI:
   ]}
 />
 
-| Building block   | Use it for                                                                                          | Loaded when                                           |
-| ---------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| **Instructions** | Stable guidance the agent should carry into every task: what the app is, invariants, tone, indexes  | Every turn                                            |
-| **Skills**       | Reusable behavior: how to follow a workflow, apply a policy, inspect evidence, or verify an output  | On demand when the skill description matches the task |
-| **Actions**      | Real operations: read or write data, call APIs, send messages, run approvals, produce typed results | Listed as tools every turn; executed only when called |
+A turn is one exchange with the agent: it reads its context, decides what to do, and responds. Loaded every turn means the file re-enters that context each time, not just once at session start.
+
+| Building block   | File                             | Use it for                                                                                          | Loaded when                                           |
+| ---------------- | -------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| **Instructions** | `AGENTS.md`                      | Stable guidance the agent should carry into every task: what the app is, invariants, tone, indexes  | Every turn                                            |
+| **Skills**       | `.agents/skills/<name>/SKILL.md` | Reusable behavior: how to follow a workflow, apply a policy, inspect evidence, or verify an output  | On demand when the skill description matches the task |
+| **Actions**      | `actions/<name>.ts`              | Real operations: read or write data, call APIs, send messages, run approvals, produce typed results | Listed as tools every turn; executed only when called |
 
 Skills and actions work together. A skill teaches the agent how to do a class of
 work; an action is the code path it can call while doing that work. For example,
@@ -128,41 +133,59 @@ and write the actual data.
 
 Five rules govern the architecture:
 
-1. **Data lives in SQL** — all app state lives in the database via Drizzle ORM
-2. **All AI goes through the agent** — no inline LLM calls
-3. **Actions for agent operations** — complex work runs as actions
-4. **Live sync keeps the UI in sync** — database changes stream over SSE with polling as the universal fallback
-5. **Application state in SQL** — ephemeral UI state lives in the database, readable by both agent and UI
+1. **Data lives in SQL:** all app state lives in the database via Drizzle ORM.
+2. **All AI goes through the agent:** no inline LLM calls; every AI interaction flows through the agent chat bridge.
+3. **Actions for agent operations:** complex work runs as a typed action, not inline code.
+4. **Live sync keeps the UI in sync:** database changes stream over SSE, with polling as the universal fallback.
+5. **Application state in SQL:** ephemeral UI state lives in the database, readable by both agent and UI.
 
 ## The four-area checklist {#four-area-checklist}
 
 Every user-facing feature should update all applicable areas. Skipping an applicable area breaks the agent-native contract; forcing a screen onto an automation that no human needs to browse is also a smell.
 
-| Area             | Description                                                    |
-| ---------------- | -------------------------------------------------------------- |
-| **1. UI**        | Page, component, or dialog the user interacts with             |
-| **2. Action**    | Agent-callable action in actions/ for the same operation       |
-| **3. Skills**    | Update AGENTS.md and/or create a skill documenting the pattern |
-| **4. App-State** | Navigation state, view-screen data, and navigate commands      |
+- **1. UI:** Page, component, or dialog the user interacts with.
+- **2. Action:** Agent-callable action in `actions/` for the same operation.
+- **3. Skills:** Update `AGENTS.md` and/or create a skill documenting the pattern.
+- **4. App-State:** Navigation state, view-screen data, and navigate commands.
 
 A feature with only UI is invisible to the agent. A full UI feature with only actions is invisible to the user. A feature without app-state means the agent is blind to what the user is doing. An automation-first operation can legitimately start with action + instructions and add chat, UI, or app-state later when humans need to browse, approve, configure, or share it.
 
+## What Agent Native includes {#what-you-get-for-free}
+
+Adopting the framework is valuable mostly because of what you stop having to build. The moment your app follows the five rules above, you inherit:
+
+| Feature                              | What it gives you                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| One action = every surface           | Every action defined with `defineAction()` is simultaneously an agent tool, a typesafe frontend hook (`useActionQuery` / `useActionMutation`), a framework-owned HTTP transport, a CLI command, an MCP tool for external clients, and an A2A tool for other agent-native apps. Optional `link` and `mcpApp` metadata add deep links and MCP Apps UI without a second implementation. |
+| Full agent resources per user        | Skills, shared `LEARNINGS.md`, personal `memory/MEMORY.md`, `AGENTS.md`, custom sub-agents, scheduled jobs, and connected MCP servers. All SQL-backed, no dev-box required. See [Agent Resources](/docs/agent-resources).                                                                                                                                                            |
+| Drop-in React components             | `<AgentPanel />` and `<AgentSidebar />` render chat + resources anywhere in your app. See [Drop-in Agent](/docs/drop-in-agent).                                                                                                                                                                                                                                                      |
+| BYO agent chat runtimes              | The same chat UI can sit on top of OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI, or your own normalized HTTP stream. See [Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes).                                                                                                                                                                       |
+| Live sync between agent and UI       | Same-process writes stream immediately over `/_agent-native/events`; a lightweight poll keeps serverless, cron, and cross-process writes convergent. Mutating actions invalidate action-backed queries automatically, so agent-created records appear without a manual refresh. See [Live Sync](#polling-sync) below.                                                                |
+| Auth, orgs, RBAC                     | Better Auth with orgs/members/roles is wired in for every template. See [Authentication](/docs/authentication). For more than one user, start with [Organizations, Teams & Permissions](/docs/organizations-teams-permissions).                                                                                                                                                      |
+| Context awareness                    | The agent always knows what the user is looking at through the `navigation` app-state key. See [Context Awareness](/docs/context-awareness).                                                                                                                                                                                                                                         |
+| MCP client + server, both directions | The app ingests MCP servers (local, remote, hub-shared) _and_ exposes its own actions as an MCP server. See [MCP Clients](/docs/mcp-clients) and [MCP Protocol](/docs/mcp-protocol).                                                                                                                                                                                                 |
+| Inter-app delegation                 | Agents in different apps talk over [A2A](/docs/a2a-protocol). Same-origin deploys skip JWT; cross-origin uses a shared `A2A_SECRET`.                                                                                                                                                                                                                                                 |
+| Sub-agent teams                      | Spawn a sub-agent with its own thread and tools, surfaced as a chip inline in chat. See [Agent Teams](/docs/agent-teams).                                                                                                                                                                                                                                                            |
+| Portability                          | Any Drizzle-supported SQL database, any Nitro-compatible host (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun).                                                                                                                                                                                                                                                                   |
+
 ## Data in SQL {#data-in-sql}
 
 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:
 
-- `application_state` — ephemeral UI state (navigation, drafts, selections)
-- `settings` — persistent key-value config
-- `oauth_tokens` — OAuth credentials
-- `sessions` — auth sessions
+- `application_state`: ephemeral UI state (navigation, drafts, selections)
+- `settings`: persistent key-value config
+- `oauth_tokens`: OAuth credentials
+- `sessions`: auth sessions
+
+Each row below expands to show its fields:
 
 <DataModel
   id="doc-block-4w0fu8"
   title="Core SQL stores"
   summary={
-    "Auto-created in every template — the agent and UI both read and write these."
+    "Auto-created in every template. The agent and UI both read and write these."
   }
   entities={[
     {
@@ -234,6 +257,8 @@ Core SQL stores are auto-created and available in every template:
   ]}
 />
 
+To add your own domain data, define a table with the same schema helpers used by the core stores above:
+
 ```ts
 // Drizzle schema for domain data
 import { table, text, integer } from "@agent-native/core/db/schema";
@@ -247,12 +272,18 @@ export const forms = table("forms", {
 });
 ```
 
+Both you and the agent can inspect that data from the terminal, without a separate SQL client:
+
 ```bash
 # Core actions for quick database inspection
 pnpm action db-schema                                       # show all tables
 pnpm action db-query --sql "SELECT * FROM forms"
 ```
 
+`db-schema` prints every table's columns and types. `db-query` runs read-only SQL directly, which is useful for checking an action's writes without opening a database client.
+
+<Callout tone="decision">
+
 The production agent chat plugin defaults raw SQL tools to read-only
 (`frameworkTools: { database: "read" }`), so agents inspect app-owned data with
 `db-schema` / `db-query` and perform writes through typed app actions. Set
@@ -268,12 +299,14 @@ chat, and email. See
 list, the `"minimal"` preset, and why disabling a group leaves its HTTP routes
 mounted.
 
+</Callout>
+
 ## Agent chat bridge {#agent-chat-bridge}
 
-The UI never calls an LLM directly. When a user clicks "Generate chart" or "Write summary", the UI sends a message to the agent via `postMessage`. The agent does the work — with full conversation history, skills, instructions, and the ability to iterate.
+The UI never calls an LLM directly. When a user clicks "Generate chart" or "Write summary", the UI sends a message to the agent via `postMessage`. The agent does the work. It has full conversation history, skills, instructions, and the ability to iterate.
 
 ```ts
-// In a React component — delegate AI work to the agent
+// Delegate AI work to the agent from a React component
 import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
 sendToAgentChat({
   message: "Generate a chart showing signups by source",
@@ -282,16 +315,19 @@ sendToAgentChat({
 });
 ```
 
-Why not call an LLM inline?
+In short:
+
+- **AI is non-deterministic**: You need conversation flow to give feedback and iterate, not one-shot buttons.
+- **Context matters**: The agent has the app's instructions, skills, and history. An inline call has none of that.
+- **The agent can do more**: It can run actions, browse the web, and chain multiple steps together.
 
-- **AI is non-deterministic.** You need conversation flow to give feedback and iterate — not one-shot buttons.
-- **Context matters.** The agent has the app's instructions, skills, and history. An inline call has none of that.
-- **The agent can do more.** It can run actions, browse the web, and chain multiple steps together.
-- **External execution.** Because everything goes through the agent and actions, any app can be driven from Slack, Telegram, scheduled jobs, scripts, or another agent via [A2A](/docs/a2a-protocol).
+**[External execution](/docs/a2a-protocol)**
+
+Because everything goes through the agent and actions, any app can be driven from Slack, Telegram, scheduled jobs, scripts, or another agent via A2A.
 
 ## Actions system {#actions-system}
 
-When the agent needs to do something complex — call an API, process data, query the database — it runs an **action**. Actions are TypeScript files in `actions/` that export a default `defineAction()`:
+When the agent needs to do something complex, like calling an API, processing data, or querying the database, it runs an **action**. Actions are TypeScript files in `actions/` that export a default `defineAction()`:
 
 ```ts filename="actions/fetch-data.ts"
 import { defineAction } from "@agent-native/core/action";
@@ -309,19 +345,30 @@ export default defineAction({
 });
 ```
 
-One `defineAction()` call gives you:
+This action fetches JSON from a source API and returns it. `defineAction()` wraps the function with a zod schema for its input (`source`), so the framework can validate that input, generate a JSON Schema the agent can call, and infer types for the frontend hook, all from this one definition.
+
+One `defineAction()` call reaches five different consumers automatically. The diagram shows the fan-out from a single action; the list below explains what each consumer gets:
+
+```mermaid
+graph LR
+  A[defineAction] --> B[Agent tool]
+  A --> C[Frontend hook]
+  A --> D[Framework transport]
+  A --> E[CLI command]
+  A --> F[MCP or A2A tool]
+```
 
-- **Agent tool** — the agent sees it with the zod-derived JSON Schema and can call it.
-- **Frontend hook** — `useActionMutation("fetch-data")` with full TypeScript inference.
-- **Framework transport** — auto-mounted behind the client hooks.
-- **CLI** — `pnpm action fetch-data --source=signups` for scripting and agent dev loops.
-- **MCP tool / A2A tool** — when MCP server or A2A is enabled, the same action shows up there too.
+- **Agent tool:** the agent sees it with the zod-derived JSON Schema and can call it.
+- **Frontend hook:** `useActionMutation("fetch-data")` with full TypeScript inference.
+- **Framework transport:** auto-mounted behind the client hooks.
+- **CLI:** `pnpm action fetch-data --source=signups` for scripting and agent dev loops.
+- **MCP tool / A2A tool:** when MCP server or A2A is enabled, the same action shows up there too.
 
-Same logic, one definition, wired to every consumer automatically. See [Actions](/docs/actions) for the full reference.
+Every consumer calls the same underlying function, so there is only one implementation to write and maintain. See [Actions](/docs/actions) for the full reference.
 
 ## Live sync {#polling-sync}
 
-Database changes are synced to the UI through `useDbSync()`. Same-process writes stream over `/_agent-native/events`; `/_agent-native/poll` remains the cross-process and serverless fallback. When the agent writes to the database (application state, settings, or domain data), a version counter increments and the client invalidates the relevant React Query caches.
+When the agent changes data, the UI needs to reflect that without a manual refresh. `useDbSync()` is what makes that automatic. Same-process writes stream over `/_agent-native/events`; `/_agent-native/poll` remains the cross-process and serverless fallback. When the agent writes to the database (application state, settings, or domain data), a version counter increments and the client invalidates the relevant React Query caches.
 
 ```ts
 // Client: subscribe to agent/UI data changes once near the app shell
@@ -329,6 +376,8 @@ import { useDbSync } from "@agent-native/core/client/hooks";
 useDbSync({ queryClient });
 ```
 
+Call this once, near the root of the app. It subscribes the whole app to change events, so any component using `useActionQuery` or a source-versioned `useQuery` refetches automatically when the data it reads changes.
+
 The flow is:
 
 1. Agent runs an action that writes to the database
@@ -337,7 +386,9 @@ The flow is:
 4. `useActionQuery` hooks and source-versioned `useQuery` hooks refetch
 5. Components render the new data without a page reload
 
-<Diagram id="doc-block-87e1c3" title="Live sync flow" summary={"An agent write becomes a UI render with no manual refresh — SSE first, polling as the universal fallback."}>
+The diagram traces that same sequence end to end:
+
+<Diagram id="doc-block-87e1c3" title="Live sync flow" summary={"An agent write becomes a UI render with no manual refresh. SSE first, polling as the universal fallback."}>
 
 ```html
 <div class="diagram-sync">
@@ -384,16 +435,16 @@ The flow is:
 
 </Diagram>
 
-This works in all deployment environments — including serverless and edge — because it uses the database, not in-memory state or file system watchers.
+This works in all deployment environments, including serverless and edge, because it uses the database instead of in-memory state or file system watchers.
 
 ## Frames {#frames}
 
-A _frame_ is the environment that hosts the agent next to your app — locally that's the embedded panel; in the cloud it's Builder.io's managed surface. See [Frames](/docs/frames).
+A _frame_ is the environment that hosts the agent next to your app. Locally that's the embedded panel; in the cloud it's Builder.io's managed surface. See [Frames](/docs/frames).
 
 Agent-native apps include an embedded agent panel that provides the AI agent alongside the app UI. This is what makes the architecture work: the agent needs a computer (database, browser, code execution), and the app needs the agent for AI work.
 
-- **Embedded Agent Panel** — Chat and optional CLI terminal built into every app. Supports Claude Code, Codex, Gemini, OpenCode, and Builder.io. Runs locally. Free and open source.
-- **Cloud** — Deploy to any cloud with real-time collaboration, visual editing, roles and permissions. Best for teams.
+- **Embedded Agent Panel:** Chat and optional CLI terminal built into every app. Supports Claude Code, Codex, Gemini, OpenCode, and Builder.io. Runs locally, free and open source.
+- **Cloud:** Deploy to any cloud with real-time collaboration, visual editing, roles, and permissions. Best for teams.
 
 ## Context awareness {#context-awareness}
 
@@ -405,7 +456,11 @@ For example, when you open an email thread the UI upserts a row like:
 { "key": "navigation", "value": { "view": "thread", "threadId": "th_abc123" } }
 ```
 
-The UI writes this on route change; the agent reads it (via `view-screen`) before taking any action, so it always knows which thread — or chart, or slide — you're focused on.
+<Callout tone="info">
+
+The UI writes this on route change; the agent reads it (via `view-screen`) before taking any action, so it always knows which thread, chart, or slide you're focused on.
+
+</Callout>
 
 See [Context Awareness](/docs/context-awareness) for the full pattern: navigation state, view-screen, navigate commands, and jitter prevention.
 
@@ -413,7 +468,7 @@ See [Context Awareness](/docs/context-awareness) for the full pattern: navigatio
 
 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`, native-widget metadata, or Generative UI wrappers added only when a surface needs richer interaction. Skills and instructions cover behavior.
 
-For the full protocol/surface matrix (MCP server and OAuth, MCP Apps, A2A, deep links, native chat widgets, Generative UI, AgentChatRuntime connectors, Agent Web, and the adapter horizon for ACP and A2UI), and for choosing a product shape — chat, inline UI, full app pages, embedded sidecar, automation, or external-agent access — see [Agent Surfaces](/docs/agent-surfaces).
+For the full protocol/surface matrix (MCP server and OAuth, MCP Apps, A2A, deep links, native chat widgets, Generative UI, AgentChatRuntime connectors, Agent Web, and the adapter horizon for ACP and A2UI), and for choosing a product shape (chat, inline UI, full app pages, embedded sidecar, automation, or external-agent access), see [Agent Surfaces](/docs/agent-surfaces).
 
 ## App code and customization {#agent-modifies-code}
 
@@ -430,43 +485,46 @@ without source changes, use [Extensions](/docs/extensions).
 Two architectural rules keep apps portable across databases and hosts:
 
 - **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).
+- **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).
 
 ## Agent Resources {#workspace}
 
-Every user gets a personal set of **agent resources** — 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 [Agent Resources](/docs/agent-resources).
+Every user gets a personal set of **agent resources**: 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 [Agent Resources](/docs/agent-resources).
 
 ## Related building blocks {#building-blocks}
 
 These sit on top of the same contract and have their own deep dives:
 
-- **[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.
+- **[Dispatch](/docs/dispatch):** the workspace control plane, with a 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, with 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}
+## What's next {#deep-dives}
 
-Adopting the framework is valuable mostly because of what you stop having to build. The moment your app follows the five rules, you inherit:
+<Cards>
 
-- **One action = every surface.** Every action defined with `defineAction()` is simultaneously an agent tool, a typesafe frontend hook (`useActionQuery` / `useActionMutation`), a framework-owned HTTP transport, a CLI command, an MCP tool for external clients, and an A2A tool for other agent-native apps. Optional `link` and `mcpApp` metadata add deep links and MCP Apps UI without a second implementation.
-- **A full set of agent resources per user.** Skills, shared `LEARNINGS.md`, personal `memory/MEMORY.md`, `AGENTS.md`, custom sub-agents, scheduled jobs, connected MCP servers — all SQL-backed, no dev-box required. See [Agent Resources](/docs/agent-resources).
-- **Drop-in React components.** `<AgentPanel />` and `<AgentSidebar />` render chat + resources anywhere in your app. See [Drop-in Agent](/docs/drop-in-agent).
-- **BYO agent chat runtimes.** The same chat UI can sit on top of OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI, or your own normalized HTTP stream. See [Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes).
-- **Live sync between agent and UI.** Same-process writes stream immediately over `/_agent-native/events`; a lightweight poll keeps serverless, cron, and cross-process writes convergent. Mutating actions invalidate action-backed queries automatically, so agent-created records appear without a manual refresh. See [Live Sync](#polling-sync) below.
-- **Auth, orgs, RBAC.** Better Auth with orgs/members/roles is wired in for every template. See [Authentication](/docs/authentication). Building for more than one user? Start with [Organizations, Teams & Permissions](/docs/organizations-teams-permissions).
-- **Context awareness.** The agent always knows what the user is looking at through the `navigation` app-state key. See [Context Awareness](/docs/context-awareness).
-- **MCP client + server, both directions.** The app ingests MCP servers (local, remote, hub-shared) _and_ exposes its own actions as an MCP server. See [MCP Clients](/docs/mcp-clients) and [MCP Protocol](/docs/mcp-protocol).
-- **Inter-app delegation.** Agents in different apps talk over [A2A](/docs/a2a-protocol). Same-origin deploys skip JWT; cross-origin uses a shared `A2A_SECRET`.
-- **Sub-agent teams.** Spawn a sub-agent with its own thread and tools, surfaced as a chip inline in chat. See [Agent Teams](/docs/agent-teams).
-- **Portability.** Any Drizzle-supported SQL database, any Nitro-compatible host (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun).
+### [What Is Agent-Native?](/docs/what-is-agent-native)
 
-That's the "and everything else" you'd otherwise be gluing together yourself.
+The vision and philosophy behind these rules.
 
-## What's next {#deep-dives}
+### [Context Awareness](/docs/context-awareness)
+
+Navigation state, view-screen, and navigate commands in depth.
+
+### [Skills Guide](/docs/skills-guide)
+
+Framework skills, domain skills, and creating custom skills.
+
+### [Native Chat UI](/docs/native-chat-ui)
+
+Action-declared tables, charts, and BYO runtime posture.
+
+### [Agent Surfaces](/docs/agent-surfaces)
+
+Chat, native inline UI, full app pages, embedded sidecar, automation, and external-agent paths.
+
+### [A2A Protocol](/docs/a2a-protocol)
+
+Agent-to-agent communication.
 
-- [**What Is Agent-Native?**](/docs/what-is-agent-native) — the vision and philosophy behind these rules
-- [**Context Awareness**](/docs/context-awareness) — navigation state, view-screen, and navigate commands in depth
-- [**Skills Guide**](/docs/skills-guide) — framework skills, domain skills, and creating custom skills
-- [**Native Chat UI**](/docs/native-chat-ui) — action-declared tables, charts, and BYO runtime posture
-- [**Agent Surfaces**](/docs/agent-surfaces) — chat, native inline UI, full app pages, embedded sidecar, automation, and external-agent paths
-- [**A2A Protocol**](/docs/a2a-protocol) — agent-to-agent communication
+</Cards>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.149.6",
+  "version": "0.151.1",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -414,7 +414,7 @@
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
     "@agent-native/recap-cli": "0.5.4",
-    "@agent-native/toolkit": "^0.13.9"
+    "@agent-native/toolkit": "^0.13.10"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/templates/chat/.agents/skills/delegate-to-agent/SKILL.md

@@ -49,6 +49,34 @@ sendToAgentChat({
 });
 ```
 
+### Keep user text separate from injected context
+
+Treat the visible `message` as the user's request or the shortest clear
+description of an app-initiated operation. Put context the user did not type —
+IDs, URLs, filenames, current selection or screen state, serialized records,
+upload instructions, and bounded source excerpts — in the `context` field.
+`context` is model input carried through the agent turn; it is stripped from
+the rendered user message, so do not concatenate it into `message` with labels,
+blank-line sections, or `<context>` tags yourself.
+
+Use the related surface for each kind of supporting input:
+
+| Surface | Use for |
+| --- | --- |
+| `message` | User-authored intent or a concise app action description |
+| `context` | Derived metadata and bounded text needed to carry out that intent |
+| `setAgentChatContextItem` | Context staged for a later user-submitted prompt; keep it keyed so updates replace stale context |
+| `images`, `referenceImagePaths`, attachments | Binary or visual inputs; describe only the handling instructions in `context` |
+
+If an app builds a prompt from a form, selection, upload, or editor state, keep
+the visible message short and pass the assembled details as `context`. Preserve
+the user's actual freeform text in `message` when it is the request; do not
+restate it as metadata in `context` unless the agent needs a structured copy.
+
+This boundary applies to auto-submitted turns and prefills. A hidden context
+field is not a license to send unbounded records or secrets: cap excerpts,
+prefer stable IDs and URLs, and use an action or resource lookup for full data.
+
 **From the UI, in the background:**
 
 ```ts