@agent-native/core 0.164.3 → 0.164.11

package/docs/content/faq.mdx

@@ -1,34 +1,34 @@
 ---
 title: "FAQ"
-description: "Common questions about agent-native — what it is, who it's for, what you can build, and how it works."
+description: "Common questions about Agent-Native — what it is, who it's for, what you can build, and how it works."
 ---
 
 # FAQ
 
-Common questions about agent-native, organized from "I'm just looking" to "I'm wiring up auth right now."
+Common questions about Agent-Native, organized from "I'm just looking" to "I'm wiring up auth right now."
 
 ## The basics {#general}
 
-### What is agent-native? {#what-is-agent-native}
+### What is Agent-Native? {#what-is-agent-native}
 
-Agent-native is a framework for building apps where the AI agent and the product surface around it are equal partners. The usual path starts with chat, adds typed actions, renders structured results inline, and grows into durable pages around the same SQL state. The invariant is that agents and humans share the same actions, database, and state. See [What Is Agent-Native?](/docs/what-is-agent-native) for the full explanation.
+Agent-Native is a framework for building apps where the AI agent and the product surface around it are equal partners. The usual path starts with chat, adds typed actions, renders structured results inline, and grows into durable pages around the same SQL state. The invariant is that agents and humans share the same actions, database, and state. See [What is Agent-Native?](/docs/what-is-agent-native) for the full explanation.
 
 ### Who is this for? {#who-is-this-for}
 
-Agent-native is for people who want a real app and an AI agent to work from the same data and actions. The common paths are:
+Agent-Native is for people who want a real app and an AI agent to work from the same data and actions. The common paths are:
 
 - **Use a hosted app** if you want Mail, Calendar, Forms, Plan, or another finished template with no setup — start at the [template gallery](/templates).
 - **Start with Chat** if you want the default from-scratch path: users can talk to the agent immediately, then you extend with actions, native results, and screens — start with [Getting Started](/docs/getting-started) or [Chat](/docs/template-chat).
 - **Start automation-first** if you are building scheduled jobs, queues, scripts, integration workers, or external-agent workflows with no browser UI yet — start with [Automation-First Apps](/docs/pure-agent-apps).
 - **Start from a template and customize it** if you want your own SaaS product with auth, database, UI, and agent actions already wired — see [Templates](/docs/cloneable-saas).
 - **Build from scratch** if you want the framework primitives for a new agent-driven product — start with [Getting Started](/docs/getting-started).
-- **Connect another agent or code tool** if you want Claude, ChatGPT, Codex, Cursor, or GitHub Copilot / VS Code to use an agent-native app — see [External Agents](/docs/external-agents) and [Skills Guide](/docs/skills-guide).
+- **Connect another agent or code tool** if you want Claude, ChatGPT, Codex, Cursor, or GitHub Copilot / VS Code to use an Agent-Native app — see [External Agents](/docs/external-agents) and [Skills Guide](/docs/skills-guide).
 
 ### How is this different from adding AI to an existing app? {#how-is-this-different}
 
-Most apps bolt AI on as an afterthought that can't actually _do_ things in the app. In an agent-native app the agent is a first-class citizen that shares the same actions, database, and state as the UI, so it can do anything the buttons can. See [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder).
+Most apps bolt AI on as an afterthought that can't actually _do_ things in the app. In an Agent-Native app the agent is a first-class citizen that shares the same actions, database, and state as the UI, so it can do anything the buttons can. See [Why build apps this way](/docs/what-is-agent-native#why-build-apps-this-way).
 
-<Diagram id="doc-block-1s6b04" title="Bolted-on AI vs. agent-native" summary="A bolted-on chat sidebar lives in its own world. An agent-native agent shares the same actions, database, and state as the UI.">
+<Diagram id="doc-block-1s6b04" title="Bolted-on AI vs. Agent-Native" summary="A bolted-on chat sidebar lives in its own world. An Agent-Native agent shares the same actions, database, and state as the UI.">
 
 ```html
 <div class="diagram-vs">
@@ -45,7 +45,7 @@ Most apps bolt AI on as an afterthought that can't actually _do_ things in the a
   </div>
   <div class="diagram-divider" aria-hidden="true"></div>
   <div class="diagram-col">
-    <span class="diagram-pill ok">Agent-native</span>
+    <span class="diagram-pill ok">Agent-Native</span>
     <div class="diagram-row2">
       <div class="diagram-node">UI</div>
       <div class="diagram-node">Agent</div>
@@ -114,9 +114,9 @@ Anthropic Claude, OpenAI (GPT-5 family), Google Gemini, and any provider that sp
 
 No. You don't train models, fine-tune, or deal with embeddings. You build a regular web app — and on the hosted version, you barely build anything at all. The framework handles the agent integration: routing messages, running actions, syncing state.
 
-### Can I migrate an existing app to agent-native? {#can-i-use-existing-code}
+### Can I migrate an existing app to Agent-Native? {#can-i-use-existing-code}
 
-You can, but agent-native works best when built from the ground up. The architecture — shared database, polling sync, actions, application state — needs to be integrated throughout. Starting from an app and customizing it is the recommended path. Think of it like the shift from desktop-first to mobile-first: you _can_ retrofit, but building native is better.
+You can, but Agent-Native works best when built from the ground up. The architecture — shared database, polling sync, actions, application state — needs to be integrated throughout. Starting from an app and customizing it is the recommended path. Think of it like the shift from desktop-first to mobile-first: you _can_ retrofit, but building native is better.
 
 ## Templates and what you can build {#templates}
 
@@ -148,7 +148,7 @@ Yes. The same agent runs in your web UI, in Slack, in Telegram, over email, and
 
 ### Can agents talk to each other? {#can-agents-talk-to-each-other}
 
-Yes, via the [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol). Every agent-native app automatically gets an A2A endpoint. From the mail app, you can tag the analytics agent to query data. An agent discovers what other agents are available, calls them over the protocol, and shows results in the UI. No configuration needed — the agent card is auto-generated from your template's actions.
+Yes, via the [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol). Every Agent-Native app automatically gets an A2A endpoint. From the mail app, you can tag the analytics agent to query data. An agent discovers what other agents are available, calls them over the protocol, and shows results in the UI. No configuration needed — the agent card is auto-generated from your template's actions.
 
 ### What can the agent see in the app? {#what-can-the-agent-see}
 
@@ -156,7 +156,7 @@ The agent always knows what the user is currently viewing. The UI writes navigat
 
 ## Development questions {#development}
 
-### Which AI coding tools work with agent-native? {#which-ai-tools-work}
+### Which AI coding tools work with Agent-Native? {#which-ai-tools-work}
 
 Any AI coding tool that reads project instructions. The framework uses AGENTS.md as the universal standard:
 
@@ -227,7 +227,7 @@ SSE gives same-process writes an immediate path to the browser, and a lightweigh
 
 AI is non-deterministic, so you need conversation flow to give feedback and iterate — not one-shot buttons — and the agent already has your codebase, instructions, skills, and history that an inline call lacks. Routing everything through the agent is also what lets the app be driven from Slack, Telegram, or another agent. See [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge).
 
-### How do I upgrade an older Agent Native app? {#upgrade-older-app}
+### How do I upgrade an older Agent-Native app? {#upgrade-older-app}
 
 Run the supported upgrade path from the app or workspace root:
 
@@ -251,7 +251,7 @@ The shared database, live sync, actions system, and application state only work
 ## What's next
 
 - [**Getting Started**](/docs/getting-started) — build your first action and render it inline in chat
-- [**What Is Agent-Native?**](/docs/what-is-agent-native) — the full explanation behind the answers above
+- [**What is Agent-Native?**](/docs/what-is-agent-native) — the full explanation behind the answers above
 - [**Templates**](/docs/cloneable-saas) — start from a complete SaaS product instead of starting from scratch
 - [**Key Concepts**](/docs/key-concepts) — the architecture: SQL, actions, polling sync, and portability
 - [**Deployment**](/docs/deployment) — host on your own domain or any Nitro-compatible provider

package/docs/content/getting-started.mdx

@@ -1,69 +1,201 @@
 ---
 title: "Getting Started"
-description: "Create a Chat app and configure an agent, then extend it with an action and a page."
+description: "Create an Agent-Native app and call the same action from the agent and the UI."
 ---
 
 # Getting Started
 
-Agent-Native apps give the agent and the UI the same [actions](/docs/actions-overview),
-SQL data, and application state. This path starts with Chat, which already
-creates the framework tables it needs and stores chat history in local SQLite by
-default. Add your own tables only when your app needs to persist domain data.
+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.
 
-<Steps>
+In this guide, you'll create a Chat app and call its included `hello` action
+from the agent and the UI.
 
-### Create a chat app and configure an agent
+## Prerequisites
 
-Scaffold the Chat template, install dependencies, start the dev server, and
-configure an agent. You'll have a working chat app to extend.
-**You are here.**
+- [Node.js](https://nodejs.org) 22 or later
+- [pnpm](https://pnpm.io)
+- An LLM connection for the agent: Builder.io, an Anthropic or OpenAI API key,
+  or a local Ollama model
 
-### Add an action
+## Create an app
 
-Define a typed text analyzer and render its result as a chart in the chat.
+In a new directory, create a Chat app:
 
-### Add a page
-
-Build a React route that calls the same action outside the transcript.
-
-</Steps>
+```bash
+npx @agent-native/core@latest create my-app --standalone --template chat
+cd my-app
+pnpm install
+```
 
-## 1. Create a chat app {#create-your-app}
+The template includes a browser app, authentication, durable conversations,
+live sync, application context, and an `actions/` directory. It also includes a
+small `hello` action that you'll use throughout this guide.
 
-You'll need [Node.js 22+](https://nodejs.org) and [pnpm](https://pnpm.io).
+## Start the development server
 
-Open a terminal, go to the directory where you want your Agent Native app, and run:
+Start the app:
 
 ```bash
-npx @agent-native/core@latest create my-app --template chat
-cd my-app
-pnpm install
 pnpm dev
 ```
 
-The app opens at `http://localhost:8080`. If you see the login screen, sign up
-with a made-up login. Local development does not require email verification.
+The app opens at `http://localhost:8080`. If it doesn't open automatically,
+visit that URL in your browser.
+
+<Callout tone="info">
+
+On the Welcome screen, select **Continue as local dev**. You don't need to
+enter an email or password for local development.
+
+</Callout>
+
+Next, connect an LLM. Select **Connect Builder.io** to use free credits, or
+select **Custom keys**, choose a provider, and enter the requested connection
+details.
+
+## Run the action from the agent
+
+An action is a typed function that your React UI can call from code and agents
+can use as a tool. The Chat template includes a simple `hello` action so you
+can try the pattern before writing one yourself.
+
+In the app, ask:
+
+> Call the hello action for Alex.
+
+The agent finds `hello` from its description and input schema, passes `Alex` as
+the `name` input, and responds:
+
+```text
+Hello, Alex!
+```
+
+## Inspect the action
+
+Open `actions/hello.ts`:
+
+```ts filename="actions/hello.ts"
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Return a friendly greeting.",
+  schema: z.object({
+    name: z.string().default("world").describe("Name to greet"),
+  }),
+  http: { method: "GET" },
+  run: async ({ name }) => {
+    return { message: `Hello, ${name}!` };
+  },
+});
+```
+
+For now, focus on four parts:
+
+- `description` tells the agent when to use the action.
+- `schema` validates the input and gives the agent a typed tool definition.
+- `http` exposes this read-only action through `GET`, which lets
+  `useActionQuery` call it from React.
+- `run` contains the application logic shared by the agent and the UI.
+
+Read [Defining Actions](/docs/actions-defining) for the complete API.
+
+## Call the action from React
+
+Add a route at `app/routes/hello.tsx`:
+
+```tsx filename="app/routes/hello.tsx"
+import { useActionQuery } from "@agent-native/core/client/hooks";
+import { useState } from "react";
+
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+
+export default function HelloRoute() {
+  const [name, setName] = useState("Alex");
+  const { data } = useActionQuery("hello", { name });
+
+  return (
+    <main className="mx-auto grid w-full max-w-xl gap-6 p-6">
+      <h1 className="text-2xl font-semibold">Hello action</h1>
+      <div className="grid gap-2">
+        <Label htmlFor="name">Name</Label>
+        <Input
+          id="name"
+          value={name}
+          onChange={(event) => setName(event.target.value)}
+        />
+      </div>
+      <p className="text-xl font-medium">{data?.message}</p>
+    </main>
+  );
+}
+```
+
+<Callout tone="warning">
+
+Restart the development server so it discovers the new route, then open
+`http://localhost:8080/hello`.
+
+</Callout>
+
+As you type a name, `useActionQuery` calls `hello` and renders the result. It
+infers the action's input and result types, so the page doesn't need a custom
+API route or a second implementation of the greeting.
+
+## Change the action
+
+In `actions/hello.ts`, change the return value:
+
+```ts
+return { message: `Welcome, ${name}.` };
+```
+
+Refresh `/hello`, then ask the agent to call `hello` again. Both return the
+updated greeting because they call the same action.
+
+## Call actions in other ways
+
+You called the same action from the agent and UI. The same action can also be
+called from:
+
+| Call from                               | Use it to                                                     |
+| --------------------------------------- | ------------------------------------------------------------- |
+| [HTTP API](/docs/http-api)              | Call an action from a script, backend, or integration.        |
+| [CLI](/docs/actions-other-surfaces#cli) | Run or test an action from a terminal.                        |
+| [MCP](/docs/actions-other-surfaces#mcp) | Let an external AI client discover and call actions as tools. |
+| [A2A](/docs/actions-other-surfaces#a2a) | Let another Agent-Native app ask this app to do work.         |
+
+Every caller uses the same action definition. You do not need a separate
+implementation for each one. This shared action model is central to
+Agent-Native: behavior, validation, and permissions stay aligned across the
+UI, agents, and integrations as the app changes.
+
+## What you built
+
+You created an Agent-Native app, called its `hello` action from the agent and a
+React UI, then changed the greeting once and watched both update. Every action
+you write from here follows that same pattern.
+
+## Next steps
 
-The Chat template includes durable chat threads, auth, live sync, an
-`actions/` directory, and the standard `view-screen` and `navigate` actions.
+<Cards>
 
-### Choose a different starting point
+### [What is Agent-Native?](/docs/what-is-agent-native)
 
-If Chat is not the right starting point, run `create` without `--template` and
-choose another option in the CLI. See [Creating Templates](/docs/creating-templates)
-for the other paths.
+Understand why the UI and agent share actions, data, and context.
 
-## 2. Configure an agent {#connect-ai}
+### [Key Concepts](/docs/key-concepts)
 
-The Chat template opens directly to the chat surface. If the agent is not ready
-to respond, open **Settings > Manage agent** or use **Cmd/Ctrl+K > Manage agent**
-to configure a model and provider.
+Learn how actions, SQL data, application context, access, and live sync fit
+together.
 
-Once the agent responds, continue with [Add an Action](/docs/getting-started-actions).
+### [Actions](/docs/actions-overview)
 
-## Related docs
+Define actions for reads, writes, and approvals, then call them from the UI,
+agents, and external clients.
 
-- [What Is Agent-Native?](/docs/what-is-agent-native): the architecture behind this path.
-- [Chat Template](/docs/template-chat): what the starter app includes.
-- [Database](/docs/database): add app-owned tables when your app needs domain data.
-- [FAQ](/docs/faq): answers about models, hosting, and templates.
+</Cards>

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}