@agent-native/core 0.164.1 → 0.164.4

package/docs/content/key-concepts.mdx

@@ -1,15 +1,15 @@
 ---
 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 rules."
+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: 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).
+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 with three layers:
+Agent-Native is a framework with three layers:
 
 | Layer                                      | What it is                                                                                                                                                                                            |
 | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -21,7 +21,7 @@ Core is the foundation. Toolkit and Templates are optional: a template can use T
 
 ## The architecture {#the-architecture}
 
-At runtime, every agent-native app is three things working together:
+At runtime, every Agent-Native app is three things working together:
 
 - **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.
@@ -94,7 +94,7 @@ That same agent-application-computer loop is what runs locally and in production
 
 ## Agent building blocks {#agent-building-blocks}
 
-Every agent-native app has the same agent building blocks, regardless of whether
+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. Each one lives
 in its own file:
 
@@ -141,7 +141,7 @@ Five rules govern the architecture:
 
 ## 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.
+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.
 
 - **1. UI:** Page, component, or dialog the user interacts with.
 - **2. Action:** Agent-callable action in `actions/` for the same operation.
@@ -150,13 +150,13 @@ Every user-facing feature should update all applicable areas. Skipping an applic
 
 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}
+## 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. |
+| 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).                                                                                                                                                                       |
@@ -441,7 +441,7 @@ This works in all deployment environments, including serverless and edge, becaus
 
 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.
+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.
@@ -503,7 +503,7 @@ These sit on top of the same contract and have their own deep dives:
 
 <Cards>
 
-### [What Is Agent-Native?](/docs/what-is-agent-native)
+### [What is Agent-Native?](/docs/what-is-agent-native)
 
 The vision and philosophy behind these rules.
 

package/docs/content/using-your-agent.mdx

@@ -5,7 +5,7 @@ description: "The day-to-day loop of working with the agent: it sees what you're
 
 # Using Your Agent
 
-The defining idea behind agent-native is that the agent and the UI are **equal partners** — see [What Is Agent-Native?](/docs/what-is-agent-native) for the why. This section is about the other half of that promise: what it feels like to actually work with the agent once it's docked next to your app.
+The defining idea behind Agent-Native is that the agent and the UI are **equal partners** — see [What is Agent-Native?](/docs/what-is-agent-native) for the reasoning. This section is about the other half of that promise: what it feels like to actually work with the agent once it's docked next to your app.
 
 There's a simple through-line. The agent **sees** what you're looking at, you **direct** it toward what you want, you can **embed** it anywhere, you can go fully **UI-light** when that's the better fit, and you can **co-edit** the same documents at the same time. Each of those is a page in this section.
 
@@ -105,7 +105,7 @@ A few examples of what that looks like in practice:
 
 ## You embed it {#you-embed-it}
 
-The agent isn't a separate app you tab over to. Wherever you see a chat panel in an agent-native app, it can be docked next to any screen — toggle it open, and it's right there next to whatever you're working on. App builders can also wire a button to hand a specific task straight to the agent instead of building a one-off "AI" feature for it. If you're building the app rather than using it, see [Drop-in Agent](/docs/drop-in-agent) for the components that make this work.
+The agent isn't a separate app you tab over to. Wherever you see a chat panel in an Agent-Native app, it can be docked next to any screen — toggle it open, and it's right there next to whatever you're working on. App builders can also wire a button to hand a specific task straight to the agent instead of building a one-off "AI" feature for it. If you're building the app rather than using it, see [Drop-in Agent](/docs/drop-in-agent) for the components that make this work.
 
 ## You can go UI-light {#ui-light}
 

package/docs/content/what-is-agent-native.mdx

@@ -1,260 +1,111 @@
 ---
-title: "What Is Agent-Native?"
-description: "Why most AI apps feel half-built, what makes an app truly agent-native, and what your day-to-day experience looks like as a result."
+title: "What is Agent-Native?"
+description: "What Agent-Native is, how its shared action architecture works, and when to build an app this way."
 ---
 
-# What Is Agent-Native?
-
-Most "AI features" today are a chat box bolted onto an existing product. You can ask questions and get summaries, but you can't ask the AI to actually _do_ anything in the app — and even when you can, the UI has no idea what the agent just did.
-
-Agent-native is the fix. It's a way of building software where **the AI agent and the UI are equal partners** — they share the same actions, the same database, and the same state. Everything the agent can do is also a button. Everything the user clicks is also something the agent can do. One system, two ways in.
-
-<Callout tone="decision">
-
-If you only remember one thing from this page: most AI apps stop one step short of being useful — and that gap is the biggest mistake in the space right now.
-
-</Callout>
-
-## What it looks like as a user {#what-it-looks-like}
-
-Picture a mail client, analytics dashboard, or project tracker. Chat might be the first screen — or docked on the side of a full app. Either way:
-
-<Cards>
-
-### Just ask
-
-Type "reply to the email from Sara saying I'll be there by 3." The agent opens the thread, drafts the reply, and shows it to you for approval.
-
-### Or click
-
-Every button, list, form, and keyboard shortcut still works — and calls the same operation the agent uses.
-
-### See what it sees
-
-Open an email and the agent knows which one. Highlight a paragraph and press `Cmd+I` — the agent acts on exactly that.
-
-### Watch it work
-
-The UI updates in real time as the agent opens views, edits drafts, and runs reports. Interrupt, redirect, or take over with the mouse at any moment.
-
-### Steer it like a teammate
-
-Give feedback, queue tasks, audit what it did, and edit its instructions.
-
-</Cards>
-
-Here's why most products don't get there.
-
-## Why most "AI apps" fall short {#the-ladder}
-
-There's a progression most teams climb, and most stop one rung too early.
-
-```mermaid
-graph LR
-  R1["Rung 1: Single LLM call"]
-  R2["Rung 2: Chat with tools"]
-  R3["Rung 3: Agent + UI parity"]
-  R1 --> R2 --> R3
-```
-
-**Rung 1** — A text box sends a prompt, the AI returns a string. No way to course-correct, no persistence, no audit trail. This is what most "AI features" actually are: a Summarize button bolted onto a SaaS product. Impressive in demos, breaks in production.
-
-**Rung 2** — The AI has tools and a chat interface. Claude, ChatGPT, and Cursor all look like this under the hood. Real step up — but it's still a chat window. No dashboards, no forms, no collaboration. Non-developers struggle to get real work done here.
-
-**Rung 3** — Every agent action is also a button; every button runs the same logic the agent uses. The agent has real context (it sees what you're looking at and writes to the same database), and external agents can call it too over A2A and MCP.
-
-<Callout tone="success">
-
-**Rung 3 is agent-native.** You stopped adding buttons to a chatbot. You added an agent to an app. That's a much higher-quality product on both sides.
+# What is Agent-Native?
+
+Agent-Native is an open-source TypeScript framework for building apps that
+serve both people and AI agents. You define your app's functionality once as
+[actions](/docs/actions-overview)—typed functions that your React UI calls
+from code and agents use as tools.
+
+## Why build apps this way
+
+Most applications are designed around a person working through the UI. Adding
+an agent introduces another way to use the product. For both to work as one
+product, three things need to be true:
+
+- **The agent needs access to the product.** If it receives a smaller, separate
+  set of tools, it remains constrained. You also end up maintaining two
+  implementations that drift as the application changes.
+- **People still need an application UI.** Chat works well for delegating work,
+  but not always for browsing information, comparing options, reviewing
+  changes, or sharing results with a team.
+- **Work needs to move between them.** A person should be able to inspect or
+  change the agent's work, and the agent should be able to continue from there
+  without starting over.
+
+Agent-Native architecture is built around these requirements. People can work
+directly through the UI or delegate an outcome to the agent, then move between
+the two without losing progress.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2Fc5b47d20f6a943e485717e5895739988%2Fc88d506c160142ae9b8618616ceedcea%2Fcompressed?apiKey=c5b47d20f6a943e485717e5895739988&token=c88d506c160142ae9b8618616ceedcea&alt=media&optimized=true"
+  alt="A comparison of a person using an application directly and working through an AI agent in the same application."
+  align="full"
+  caption="Watch a four-minute introduction to Agent-Native architecture."
+/>
 
-</Callout>
+## How Agent-Native works
 
-See [Key Concepts — Protocols](/docs/key-concepts#protocols) for how all of this hangs off the same action definition.
+An Agent-Native application gives people and agents two ways to work with the
+same product:
 
-## How agent and UI share the same actions {#agent-ui-parity}
+- **The UI** gives people a familiar way to browse, edit, review, and share
+  work.
+- **The agent** handles work people delegate to it.
 
-In a normal app, the UI and any "AI features" live in separate worlds — the buttons call one set of code, the AI calls another. Agent-native collapses that into one.
+Three shared foundations make this possible:
 
-Every operation is defined as a typed **action**: a name, a schema, and a `run` function. The agent calls those actions as tools. The UI calls the same actions when a button is clicked. There's no translation layer, no duplication, and no drift.
+- **Shared operations.** People trigger them through the UI, while agents call
+  them directly. Agent-Native defines each operation once as an
+  [action](/docs/actions-overview).
+- **[Shared data](/docs/database)** holds the work and information the
+  application needs to preserve. Depending on the application, that might be
+  customer records, project plans, conversations, or reports. The UI and agent
+  both read and update this shared data.
+- **[Shared application state](/docs/context-awareness)** describes what is
+  happening right now, such as the current page, selected record, or active
+  view. The framework gives relevant state to the agent as context, so it knows
+  what the person is working with.
 
 ```mermaid
 graph TD
-  UI_IN["Click a button"]
-  AG_IN["Type a message to the agent"]
-  ACTION["Same typed action"]
-  DB["Shared database"]
-  UI_OUT["UI updates instantly"]
-  AG_OUT["Agent sees the change"]
-
-  UI_IN --> ACTION
-  AG_IN --> ACTION
-  ACTION --> DB
-  DB --> UI_OUT
-  DB --> AG_OUT
-```
-
-The diagram above shows what this looks like at runtime: both the user and the agent submit actions to the same layer, which writes to the same database and sends updates back to both surfaces. When the agent creates a draft email, it appears in your inbox immediately. When you click Send, the agent knows it was sent. See [Key Concepts](/docs/key-concepts) for the full architecture.
-
-## Why agents need a UI — and apps need an agent {#why-both}
-
-These two questions answer each other.
-
-<Comparison>
-
-### Agents need a UI
-
-Even when the agent does all the heavy lifting, humans still need to see what it's doing, steer it, inspect its work, and share its output. At minimum that's an observability dashboard. At maximum it's a full app with the agent as a co-pilot. The surface can grow from one to the other without a rewrite.
-
-### Apps need an agent
-
-Even in a full app with every button working, natural language makes a huge difference. Because every action is defined once and exposed as both a button and a tool, the agent can do everything the buttons can — and more. Natural language becomes a first-class input alongside clicks, with no separate "AI world" to maintain.
-
-</Comparison>
-
-The argument isn't "agents replace UI." It's **agents belong inside applications, as equal partners**. See [Agent Surfaces](/docs/agent-surfaces) for the concrete shapes and APIs.
-
-## Per-user customization — without the complexity {#workspace-customization}
-
-What makes tools like Claude Code feel powerful isn't the model — it's the customization layer: per-project instructions, skills, memory, sub-agents, connected services.
-
-Agent-native gives every user that same layer, inside your app, stored in the database rather than on the filesystem. No dev environment per user, no container per user — just rows in a table.
-
-<Cards>
-
-### Team-wide rules
-
-Instructions every agent on the team reads — house style, escalation policy, whatever your team needs the agent to always know.
-
-### Personal memory
-
-The agent builds this automatically as you correct it. Over time it learns your preferences without you having to write anything down.
-
-### `/slash` commands
-
-Reusable how-to guides for common workflows. Type `/weekly-report` and the agent knows exactly what to do.
-
-### `@sub-agents`
-
-Specialized agents for specific tasks, scoped to a user or team. Delegate the routine stuff without writing a new integration.
-
-### Scheduled jobs
-
-Set it and forget it. "Every Monday, summarize last week and draft the team update."
-
-### External services
-
-Per-user MCP server connections. Each person can plug in their own tools without affecting anyone else's setup.
-
-</Cards>
-
-That's Claude Code-level flexibility in a multi-tenant SaaS product. See [Agent Resources](/docs/agent-resources) for the full concept.
-
-## What does it look like in code? {#what-does-it-look-like-in-code}
-
-Every operation in an agent-native app is an **action** — defined once, available to both the agent and the UI.
-
-<AnnotatedCode
-  id="doc-block-n4jy5o"
-  title="One action, defined once"
-  filename="actions/reply-to-email.ts"
-  language="ts"
-  code={
-    'import { defineAction } from "@agent-native/core/action";\nimport { z } from "zod";\n\nimport { getDb, schema } from "../server/db/index.js";\n\nexport default defineAction({\n  description: "Reply to an email thread",\n  schema: z.object({ emailId: z.string(), body: z.string() }),\n  run: async ({ emailId, body }) => {\n    const db = getDb();\n    await db.insert(schema.replies).values({ emailId, body });\n  },\n});'
-  }
-  annotations={[
-    {
-      lines: "7",
-      label: "Tool surface",
-      note: "The `description` is what the agent reads to decide when to call this as a tool.",
-    },
-    {
-      lines: "8",
-      label: "Typed contract",
-      note: "One zod `schema` validates input from **every** surface — agent, UI, HTTP, MCP, and A2A.",
-    },
-    {
-      lines: "9-12",
-      label: "One implementation",
-      note: "The `run` body is the single source of truth. The UI button and the agent tool both execute exactly this. `getDb()` and `schema` come from your app's `server/db/index.ts` — see [Database](/docs/database).",
-    },
-  ]}
-/>
-
-The same action is then callable from a React component, from the agent in chat, and from any external agent or MCP host:
-
-```tsx
-// In any React component — same action, called from a button
-const { mutate } = useActionMutation("reply-to-email");
-
-<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
-  Send Reply
-</Button>;
-```
-
-```tsx
-// And the agent panel mounted anywhere in your app
-import { AgentSidebar } from "@agent-native/core/client/agent-chat";
-<AgentSidebar />;
+  UI[UI] --> App[One application]
+  Agent[Agent] --> App
+  App --- Operations[Shared operations]
+  App --- Data[Shared data]
+  App --- State[Shared application state]
 ```
 
-One action definition powers the UI button, the agent tool, an HTTP endpoint, an MCP surface, an A2A integration, and a CLI command. See [Actions](/docs/actions-overview) for the full reference.
-
-## How to get started {#how-to-get-started}
-
-Agent-native apps follow a start-from-a-working-app model. Pick a template — Calendar, Mail, Analytics, Forms, and more — and make it yours.
-
-<Steps>
-
-### Pick a template
-
-Browse [agent-native.com/templates](/templates) and pick the one closest to what you want to build.
+The agent does not click through the UI. It calls the same actions as the UI,
+with the same validation, permissions, and implementation.
 
-### Use it immediately
+For example, a person can assign a support ticket through the UI or ask the
+agent to do it. Both paths run the same action and update the same ticket. The
+person can inspect or change the result in the UI, then let the agent continue
+from there.
 
-Many first-party templates are available as hosted apps (e.g. `mail.agent-native.com`). Try one before you touch any code.
+## When should you use Agent-Native?
 
-### Clone and customize
+Agent-Native is a good fit when:
 
-When you're ready to change something — "connect our Stripe account," "add a cohort chart" — create your own app from the template and customize the source in your own repository.
+- The agent should do real work in the app, not only answer questions.
+- People need a UI to inspect, edit, approve, or share the work.
+- Work should move between the UI and agent without losing progress or context.
 
-### Deploy to your domain
+If you only need one generated response, call a model directly. If the workflow
+follows a fixed, predictable sequence, ordinary application logic or automation
+is simpler. Use Agent-Native when the UI and agent both need an ongoing role in
+the same work.
 
-Ship your app to your own domain, or stay on agent-native.com. Because it's _your_ app, you own the source and can evolve it independently.
-
-</Steps>
-
-Not ready for a whole template? Add a **skill** to a coding agent you already use: `npx @agent-native/core@latest skills add visual-plan`. See the [Skills Guide](/docs/skills-guide#app-backed-skills).
-
-## Composable agents {#composable-agents}
-
-Agent-native apps can talk to each other. From inside the mail app, you can tag the analytics agent to query data and include the result in a draft. The agents discover what other agents are available, hand off work, and surface results in the UI you're already in — powered by [A2A](/docs/a2a-protocol) and [MCP](/docs/mcp-protocol) under the hood.
-
-## What's next {#whats-next}
+## Next steps
 
 <Cards>
 
 ### [Getting Started](/docs/getting-started)
 
-Build a working chat app in under five minutes, then add an action and a page. Add your own database tables when you need to persist domain data.
+Create an app and call the same action from the agent and UI.
 
 ### [Key Concepts](/docs/key-concepts)
 
-The architecture underneath everything on this page: SQL, actions, polling sync, and context awareness.
+Learn how actions, SQL data, application context, access, and live sync fit
+together.
 
 ### [Agent Surfaces](/docs/agent-surfaces)
 
-All the shapes an agent-native app can take: chat, inline UI, full app pages, sidecars, automation, and external agents.
-
-### [Templates](/docs/cloneable-saas)
-
-Complete, working products you own and customize — not blank scaffolds.
-
-### [Agent Resources](/docs/agent-resources)
-
-The per-user customization layer: skills, memory, instructions, and MCP connections — backed by SQL, not files.
-
-### [FAQ](/docs/faq)
-
-Quick answers on cost, hosting, models, and templates.
+See how the same model supports apps led by a UI, chat, automation, or another
+agent.
 
 </Cards>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.164.1",
+  "version": "0.164.4",
   "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": {