@agent-native/core 0.164.1 → 0.164.4

package/dist/server/agent-chat-plugin.js

@@ -199,17 +199,19 @@ export function createSerializedA2ATaskStatusWriter(taskId, writeStatus = update
 const A2A_ACTIVITY_CHECKPOINT_MIN_INTERVAL_MS = 2_000;
 export async function resolveA2ARecoverableArtifactSecret(orgId = getRequestOrgId()) {
     const globalSecret = process.env.A2A_SECRET?.trim();
-    if (globalSecret)
-        return globalSecret;
-    if (!orgId)
-        return undefined;
-    try {
-        const { getOrgA2ASecret } = await import("../org/context.js");
-        return (await getOrgA2ASecret(orgId))?.trim() || undefined;
-    }
-    catch {
-        return undefined;
+    if (orgId) {
+        try {
+            const { getOrgA2ASecret } = await import("../org/context.js");
+            const orgSecret = (await getOrgA2ASecret(orgId))?.trim();
+            if (orgSecret)
+                return orgSecret;
+            // coercion-ok: undefined is the fail-closed result when organization secret lookup throws
+        }
+        catch {
+            return undefined;
+        }
     }
+    return globalSecret || undefined;
 }
 export function buildLeanRunPolicyPrompt(codeEditingSurfaceRestriction, prodCodeExecPromptNote) {
     return codeEditingSurfaceRestriction + prodCodeExecPromptNote;
@@ -1619,6 +1621,7 @@ export function createAgentChatPlugin(options) {
                                         baseUrl: artifactBaseUrl,
                                         includePersistedArtifactMarker: true,
                                         persistedArtifactSecret: recoverableArtifactSecret,
+                                        delegatedTaskId: context.taskId,
                                     })
                                     : null;
                                 if (recoverableArtifactText &&
@@ -1723,7 +1726,12 @@ export function createAgentChatPlugin(options) {
                         };
                         return;
                     }
-                    const { responseText, finalText } = assembleA2AFinalResponse(a2aEvents, a2aToolResults, { event: context.event, outcome: a2aOutcome });
+                    const { responseText, finalText, mutationReceipts } = assembleA2AFinalResponse(a2aEvents, a2aToolResults, {
+                        event: context.event,
+                        outcome: a2aOutcome,
+                        persistedArtifactSecret: recoverableArtifactSecret,
+                        delegatedTaskId: context.taskId,
+                    });
                     console.log(`[A2A] Loop complete. Text: ${responseText.slice(0, 100)}...`);
                     // Yield the final accumulated text
                     yield {
@@ -1734,6 +1742,18 @@ export function createAgentChatPlugin(options) {
                                 type: "text",
                                 text: finalText,
                             },
+                            ...(mutationReceipts.length > 0
+                                ? [
+                                    {
+                                        type: "data",
+                                        data: {
+                                            kind: "agent-native/mutation-receipts",
+                                            version: 1,
+                                            receipts: mutationReceipts,
+                                        },
+                                    },
+                                ]
+                                : []),
                         ],
                     };
                 },
@@ -2000,8 +2020,10 @@ export function createAgentChatPlugin(options) {
                                 delegation: { protocol: "mcp" },
                             },
                         });
+                        const persistedArtifactSecret = await resolveA2ARecoverableArtifactSecret();
                         return assembleA2AFinalResponse(mcpEvents, mcpToolResults, {
                             outcome: mcpOutcome,
+                            persistedArtifactSecret,
                         }).finalText;
                     },
                 });

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
-    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
+    error?: undefined;
 }>>;

package/dist/server/ssr-handler.js

@@ -18,7 +18,7 @@ import { defineEventHandler } from "h3";
  */
 import { createRequestHandler } from "react-router";
 import { isMcpPublicPath } from "../mcp/route-paths.js";
-import { DEFAULT_SPECULATION_RULES_PATH, resolveSsrCacheHeaders, resolveSsrCacheKeyHeaders, } from "../shared/cache-control.js";
+import { DEFAULT_SPECULATION_RULES_PATH, resolveSsrCacheHeaders, resolveSsrCacheKeyHeaders, SSR_QUERY_CACHE_KEY_HEADER, } from "../shared/cache-control.js";
 import { AGENT_NATIVE_SOCIAL_IMAGE_ALT, AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT, AGENT_NATIVE_SOCIAL_IMAGE_PATH, AGENT_NATIVE_SOCIAL_IMAGE_TYPE, AGENT_NATIVE_SOCIAL_IMAGE_WIDTH, withAgentNativeSocialImageCacheBuster, } from "../shared/social-meta.js";
 import { getAppBasePathFromViteEnv, stripAppBasePath as canonicalStripAppBasePath, } from "./app-base-path.js";
 import { getAppOriginClientConfigScript } from "./app-origin-config.js";
@@ -204,6 +204,8 @@ function isSsrHtmlOrDataResponse(headers, status, pathname) {
  * that contradicts that.
  */
 function applyDefaultSsrCacheHeader(headers, status, pathname) {
+    const varyByQuery = headers.get(SSR_QUERY_CACHE_KEY_HEADER)?.trim().toLowerCase() === "query";
+    headers.delete(SSR_QUERY_CACHE_KEY_HEADER);
     if (!isSsrHtmlOrDataResponse(headers, status, pathname))
         return;
     // A public shell must never set a viewer cookie or vary by credentials.
@@ -234,9 +236,16 @@ function applyDefaultSsrCacheHeader(headers, status, pathname) {
     for (const [name, value] of Object.entries(resolveSsrCacheHeaders())) {
         headers.set(name, value);
     }
-    for (const [name, value] of Object.entries(resolveSsrCacheKeyHeaders())) {
-        headers.set(name, value);
-    }
+    const cacheKeyHeaders = resolveSsrCacheKeyHeaders();
+    const netlifyVary = varyByQuery
+        ? cacheKeyHeaders["netlify-vary"]
+            ? "query"
+            : undefined
+        : cacheKeyHeaders["netlify-vary"];
+    if (netlifyVary)
+        headers.set("netlify-vary", netlifyVary);
+    else
+        headers.delete("netlify-vary");
 }
 function applyDefaultSpeculationRulesHeader(headers, status, basePath) {
     if (status < 200 || status >= 400)

package/dist/shared/cache-control.d.ts

@@ -7,6 +7,28 @@ export declare const DEFAULT_SSR_CACHE_HEADERS: {
     readonly "cdn-cache-control": "public, max-age=600, stale-while-revalidate=604800, stale-if-error=3600";
     readonly "netlify-cdn-cache-control": "public, durable, s-maxage=31536000, stale-while-revalidate=604800, stale-if-error=3600";
 };
+/**
+ * Content type used by impersonal HTML redirects that should enter the
+ * deployment adapter's shared SSR cache path.
+ */
+export declare const SSR_HTML_CONTENT_TYPE = "text/html; charset=utf-8";
+/**
+ * Internal response marker for public HTML whose redirect target preserves
+ * request query parameters. The SSR adapters consume this marker and emit a
+ * provider-specific full-query cache key only where the provider supports it.
+ */
+export declare const SSR_QUERY_CACHE_KEY_HEADER = "x-agent-native-ssr-key";
+export type SsrHtmlContentTypeOptions = {
+    varyByQuery?: boolean;
+};
+/**
+ * Mark an already-built HTML response as HTML without changing its redirect
+ * status, location, or other headers. Only use this for redirects whose
+ * target is independent of the viewer and request credentials. Set
+ * `varyByQuery` when the target preserves request query parameters so the SSR
+ * adapter can request a full-query cache key on providers that support it.
+ */
+export declare function withSsrHtmlContentType<T extends Response>(response: T, options?: SsrHtmlContentTypeOptions): T;
 /**
  * Deployment-wide override for the SSR shell cache policy.
  *

package/dist/shared/cache-control.js

@@ -7,6 +7,31 @@ export const DEFAULT_SSR_CACHE_HEADERS = {
     "cdn-cache-control": DEFAULT_SSR_CDN_CACHE_CONTROL,
     "netlify-cdn-cache-control": DEFAULT_SSR_NETLIFY_CDN_CACHE_CONTROL,
 };
+/**
+ * Content type used by impersonal HTML redirects that should enter the
+ * deployment adapter's shared SSR cache path.
+ */
+export const SSR_HTML_CONTENT_TYPE = "text/html; charset=utf-8";
+/**
+ * Internal response marker for public HTML whose redirect target preserves
+ * request query parameters. The SSR adapters consume this marker and emit a
+ * provider-specific full-query cache key only where the provider supports it.
+ */
+export const SSR_QUERY_CACHE_KEY_HEADER = "x-agent-native-ssr-key";
+/**
+ * Mark an already-built HTML response as HTML without changing its redirect
+ * status, location, or other headers. Only use this for redirects whose
+ * target is independent of the viewer and request credentials. Set
+ * `varyByQuery` when the target preserves request query parameters so the SSR
+ * adapter can request a full-query cache key on providers that support it.
+ */
+export function withSsrHtmlContentType(response, options = {}) {
+    response.headers.set("content-type", SSR_HTML_CONTENT_TYPE);
+    if (options.varyByQuery) {
+        response.headers.set(SSR_QUERY_CACHE_KEY_HEADER, "query");
+    }
+    return response;
+}
 /**
  * Deployment-wide override for the SSR shell cache policy.
  *

package/dist/shared/index.d.ts

@@ -6,6 +6,7 @@ export { truncate } from "./truncate.js";
 export { isHumanReadableDocumentTitle, normalizeDocumentTitle, } from "./document-title.js";
 export { injectDocumentMarkup } from "./html-document.js";
 export { withBuilderUtmTrackingParams } from "./builder-link-tracking.js";
+export { SSR_HTML_CONTENT_TYPE, SSR_QUERY_CACHE_KEY_HEADER, type SsrHtmlContentTypeOptions, withSsrHtmlContentType, } from "./cache-control.js";
 export { AGENT_NATIVE_DOCS_ORIGIN, docsUrl, type DocsUrlOptions, } from "./docs-url.js";
 export { buildRuntimeConfigPrompt, formatRuntimeConfigReport, getRuntimeConfigReport, parseRuntimeConfigReport, runtimeConfigRequirementsFromSearchParams, type RuntimeConfigEnvironment, type RuntimeConfigIssue, type RuntimeConfigIssueCode, type RuntimeConfigIssueSeverity, type RuntimeConfigPhase, type RuntimeConfigReport, type RuntimeConfigRequirements, } from "./runtime-config.js";
 export { llmConnectionTrackingProperties, normalizeLlmConnection, type LlmConnectionStatus, } from "./llm-connection.js";

package/dist/shared/index.js

@@ -6,6 +6,7 @@ export { truncate } from "./truncate.js";
 export { isHumanReadableDocumentTitle, normalizeDocumentTitle, } from "./document-title.js";
 export { injectDocumentMarkup } from "./html-document.js";
 export { withBuilderUtmTrackingParams } from "./builder-link-tracking.js";
+export { SSR_HTML_CONTENT_TYPE, SSR_QUERY_CACHE_KEY_HEADER, withSsrHtmlContentType, } from "./cache-control.js";
 export { AGENT_NATIVE_DOCS_ORIGIN, docsUrl, } from "./docs-url.js";
 export { buildRuntimeConfigPrompt, formatRuntimeConfigReport, getRuntimeConfigReport, parseRuntimeConfigReport, runtimeConfigRequirementsFromSearchParams, } from "./runtime-config.js";
 export { llmConnectionTrackingProperties, normalizeLlmConnection, } from "./llm-connection.js";

package/docs/content/drop-in-agent.mdx

@@ -11,7 +11,7 @@ description: "Mount the agent chat + resources into any React app with <AgentPan
 
 </Callout>
 
-You don't need to build agent-native from scratch. The agent chat, resources tab, CLI terminal, voice input, and all the related infrastructure ship as a handful of React components you drop into any app.
+You don't need to build Agent-Native from scratch. The agent chat, resources tab, CLI terminal, voice input, and all the related infrastructure ship as a handful of React components you drop into any app.
 
 <Callout tone="info">
 
@@ -184,7 +184,7 @@ Full props: `AgentPanelProps` in `@agent-native/core/client`.
 
 ## Programmatic messages: `sendToAgentChat()` {#send}
 
-A button that hands work off to the agent (instead of running an inline `llm()` call — the anti-pattern from the [ladder](/docs/what-is-agent-native#the-ladder)). For visible, user-initiated AI work, open the sidebar explicitly so the user can see, steer, and continue the same thread:
+A button that hands work off to the agent instead of creating a separate AI path with an inline `llm()` call. See [Why build apps this way](/docs/what-is-agent-native#why-build-apps-this-way) for why that distinction matters. For visible, user-initiated AI work, open the sidebar explicitly so the user can see, steer, and continue the same thread:
 
 ```tsx
 import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
@@ -283,7 +283,7 @@ AI-shaped workflow inside one opaque action.
 
 ## Typesafe actions from the UI: `useActionMutation()` {#use-action-mutation}
 
-When the UI needs to run the same operation an agent tool would run — rung 3 of the [ladder](/docs/what-is-agent-native#rung-three) — use `useActionMutation`:
+When the UI needs to run the same operation an agent tool would run, use [`useActionMutation`](/docs/client-data#use-action-mutation):
 
 ```tsx
 import { useActionMutation } from "@agent-native/core/client/hooks";
@@ -298,7 +298,7 @@ Type-safe arguments come from the zod schema in your `defineAction()`. See [Acti
 
 <Callout id="doc-block-1757zi5" tone="decision">
 
-**`useActionMutation` vs `sendToAgentChat`.** Run the operation directly with `useActionMutation` when the user clicked a deterministic button ("Send reply"). Hand it to `sendToAgentChat` when the work needs the agent's reasoning, tools, or multi-step planning. Never call an inline `llm()` from UI — that is rung 1 of the [ladder](/docs/what-is-agent-native#the-ladder).
+**`useActionMutation` vs `sendToAgentChat`.** Run the operation directly with `useActionMutation` when the user clicked a deterministic button ("Send reply"). Hand it to `sendToAgentChat` when the work needs the agent's reasoning, tools, or multi-step planning. Never call an inline `llm()` from UI; that creates a separate AI path instead of using the shared agent loop.
 
 </Callout>
 

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>