@agent-native/core 0.93.0 → 0.94.0

package/docs/content/embedding-sdk.mdx

@@ -82,8 +82,7 @@ pnpm add @agent-native/core
 
 On the server:
 
-```ts
-// server/plugins/agent-native.ts
+```ts filename="server/plugins/agent-native.ts"
 import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server";
 import { builderActions } from "../agent-native/actions";
 import { getBuilderSession } from "../auth";
@@ -288,9 +287,13 @@ for await (const chunk of sendMessage(
 
 ### Host App (`<AgentNative>` host bridge)
 
-> The batteries-included plugin above is preferred. Use this lower-level bridge
-> only for standalone sidecar apps or cross-origin iframes where you wire page
-> context and client actions yourself.
+<Callout id="doc-block-emb1host" tone="info">
+
+The batteries-included plugin above is preferred. Use this lower-level bridge
+only for standalone sidecar apps or cross-origin iframes where you wire page
+context and client actions yourself.
+
+</Callout>
 
 For standalone sidecar apps or cross-origin iframes, use the lower-level `<AgentNative />`. It renders the iframe sidecar and wires page context, live client actions, and host refresh/navigation commands in one place:
 
@@ -501,9 +504,13 @@ Client actions are a live bridge to one browser tab. The host advertises them wi
 
 ### Portable Extensions
 
-> Prefer the batteries-included plugin when you want Agent-Native to manage
-> extension definitions, approval, storage, and agent-created extensions. Use
-> the portable slot below only when the SaaS already owns those concerns.
+<Callout id="doc-block-emb1ext" tone="info">
+
+Prefer the batteries-included plugin when you want Agent-Native to manage
+extension definitions, approval, storage, and agent-created extensions. Use
+the portable slot below only when the SaaS already owns those concerns.
+
+</Callout>
 
 The SDK also supports user-defined extensions: sandboxed Alpine.js mini-apps that a host SaaS can render in named slots. Use this when the customer wants to build their own small panels, calculators, dashboards, or workflow helpers against the same action/context surface that the agent uses.
 
@@ -670,3 +677,14 @@ The helper intentionally returns plain `{ name, description, parameters, execute
 Start iframe-first. It works for Builder.io, customer SaaS apps, and internal admin tools without coupling release cycles or CSS/runtime assumptions.
 
 The sidecar itself should still be an Agent-Native app/template: actions are the backend API surface, SQL-backed app state is the agent's memory, and integrations such as Slack or Telegram can route into the same durable chat. The embedding SDK supplies the live membrane between that sidecar and the current host page.
+
+## What's next
+
+- [**Agent Surfaces**](/docs/agent-surfaces) — decide between headless, chat,
+  sidecar, and full-app before you start embedding.
+- [**Native Chat UI**](/docs/native-chat-ui) — the chat runtime and widget
+  contract the sidecar renders.
+- [**Extensions**](/docs/extensions) — the SQL-backed extension system this
+  SDK's portable slot is a lighter-weight alternative to.
+- [**Drop-in Agent**](/docs/drop-in-agent) — mount the same agent inside an
+  Agent-Native app instead of an external host.

package/docs/content/evals.mdx

@@ -73,8 +73,7 @@ The runner resolves a provider-agnostic engine/model from the existing registry
 
 Drop a `*.eval.ts` file anywhere in the app (or an `evals/*.ts` file). Each file `export default defineEval(...)` (or exports an array of them):
 
-```ts
-// evals/greeting.eval.ts
+```ts filename="evals/greeting.eval.ts"
 import { defineEval, contains, llmJudge } from "@agent-native/core/eval";
 
 export default defineEval({
@@ -255,10 +254,9 @@ coverage in normal PR CI.
 
 ### As a CI deploy gate {#ci}
 
-Add it to the pipeline that runs before a deploy:
+Add it to the pipeline that runs before a deploy (excerpt):
 
-```yaml
-# .github/workflows/deploy.yml (excerpt)
+```yaml filename=".github/workflows/deploy.yml"
 - run: npx agent-native eval --json
 ```
 

package/docs/content/extensions.mdx

@@ -17,13 +17,19 @@ If you've used QuickBooks Online, you've seen the model: QBO ships a core accoun
 
 The framing matters: an extension isn't a generic "do whatever you want" sandbox. It's a **mini-app that extends a specific template** — Mail, Analytics, Calendar, Clips, Design — and uses that template's actions and data. A Mail extension reads emails. An Analytics extension reads a dashboard's metrics. A Calendar extension acts on the open event. They feel like part of the host product because they _are_ part of the host product.
 
-> **Extensions add UI; they do not rewrite the host UI.** An extension renders on
-> its own page or inside a named [slot](#slots) exposed by the template. It
-> cannot inject elements into arbitrary native components — for example, beside
-> every attendee in Calendar — unless the template exposes a slot there. For
-> deeper customization, ask the agent to edit the template's source code. Full
-> code customization is a core Agent Native capability; extensions are the
-> fast, no-deploy layer.
+<Callout tone="info">
+
+**Extensions add UI; they do not rewrite the host UI.** An extension renders on
+its own page or inside a named [slot](#slots) exposed by the template. It
+cannot inject elements into arbitrary native components — for example, beside
+every attendee in Calendar — unless the template exposes a slot there. For
+deeper customization, ask the agent to edit the template's source code. Full
+code customization is a core Agent Native capability; extensions are the
+fast, no-deploy layer.
+
+</Callout>
+
+The gallery, building flow, and capabilities table below apply whether you're an end user asking the agent for a widget or a template developer wiring up slots. The bridge/data API reference (`#capabilities` onward through `#local-file-extensions`) is written for template developers who need the exact helper contract or the authenticated data-API shape.
 
 Three things make extensions work:
 
@@ -536,7 +542,11 @@ The next time you open an email thread, your sticky-note pad is right under the
 
 In practice you don't run those three commands by hand. Just say "pin this widget to my contact sidebar" and the agent handles target + install for you.
 
-> **Slots are an _added_ capability, not a prerequisite.** Plenty of useful extensions never get installed into a slot — they live happily on their own page. Reach for slots when the widget needs to be _next to_ what the user is looking at in the host template.
+<Callout tone="info">
+
+**Slots are an _added_ capability, not a prerequisite.** Plenty of useful extensions never get installed into a slot — they live happily on their own page. Reach for slots when the widget needs to be _next to_ what the user is looking at in the host template.
+
+</Callout>
 
 For deeper detail on slots — how to declare them in your template, how the context contract works, how installs are scoped — see the `extension-points` skill. Skills ship inside every scaffolded template under `.agents/skills/`; see [Skills Guide](/docs/skills-guide) for how they work.
 
@@ -622,6 +632,8 @@ The framework lets the agent edit the app's source code directly — components,
 
 Rule of thumb: **if it's for one user or one team, it's an extension.** If every user of the template should get it, ship it as a real feature.
 
+If what you actually need is a cached, refreshable data source for an existing chart or table — not a new interactive widget — see [Data Programs](/docs/data-programs) instead; it shares this page's sandbox and security posture but has no UI of its own.
+
 ## Security {#security}
 
 <Callout id="doc-block-frp4nq" tone="success">
@@ -652,8 +664,9 @@ You also won't see this in normal use, but the agent has a third related concept
 
 ## What's next
 
-- [**Templates**](/docs/cloneable-saas) — the host apps extensions extend
+- [**Apps**](/docs/cloneable-saas) — the host apps extensions extend
 - [**Actions**](/docs/actions) — the operations an extension calls via `appAction`
+- [**Data Programs**](/docs/data-programs) — the no-UI sibling primitive for cached, refreshable data sources
 - [**Sharing & Privacy**](/docs/sharing) — how extension visibility, org sharing, and per-user grants work
 - [**Onboarding & API Keys**](/docs/onboarding) — how secrets surface in the settings UI
 - [**Security**](/docs/security) — the framework's data scoping and access model

package/docs/content/external-agents.mdx

@@ -8,12 +8,13 @@ search: "Claude ChatGPT Claude Code Codex Cursor Claude Cowork MCP Apps agent-na
 
 **This page: connect an external agent or MCP host to your app.** Use it when Claude, ChatGPT, Codex, Cursor, Claude Cowork, or another MCP-compatible host should drive a hosted agent-native app and round-trip the result back into the running UI.
 
-| If you want to…                                              | Read                               |
-| ------------------------------------------------------------ | ---------------------------------- |
-| Connect an external agent/host to your app                   | **This page** — External Agents    |
-| Give your agent more tools (consume other MCP servers)       | [MCP Clients](/docs/mcp-clients)   |
-| Build inline UIs that render in Claude/ChatGPT               | [MCP Apps](/docs/mcp-apps)         |
-| Lower-level MCP server reference (auth, tools, custom mount) | [MCP Protocol](/docs/mcp-protocol) |
+| If you want to…                                              | Read                                 |
+| ------------------------------------------------------------ | ------------------------------------ |
+| Connect an external agent/host to your app                   | **This page** — External Agents      |
+| Give your agent more tools (consume other MCP servers)       | [MCP Clients](/docs/mcp-clients)     |
+| Build inline UIs that render in Claude/ChatGPT               | [MCP Apps](/docs/mcp-apps)           |
+| Build generated inline UI inside Agent-Native chat           | [Generative UI](/docs/generative-ui) |
+| Lower-level MCP server reference (auth, tools, custom mount) | [MCP Server](/docs/mcp-protocol)     |
 
 An agent-native app is reachable by any MCP-compatible host — Claude, Claude Desktop, Claude Code, ChatGPT custom MCP apps, Codex, Cursor, Claude Cowork, VS Code GitHub Copilot, Goose, Postman, MCPJam, and future clients that implement the standard. External agents are great at producing artifacts (a draft, an event, a dashboard) but they often live in a terminal or another app. Without a bridge, the user gets a wall of JSON and has to go find the thing.
 
@@ -136,13 +137,8 @@ snapshot until you refresh/review it again, so rescan the connector after MCP
 tool or MCP App metadata changes. If you still have old per-app connectors
 enabled alongside Dispatch, refresh or reconnect each stale connector; updating
 Dispatch does not rewrite ChatGPT or Claude's cached Calendar/Mail/etc.
-snapshots. The scopes are:
-
-| Scope       | What it enables                                      |
-| ----------- | ---------------------------------------------------- |
-| `mcp:read`  | Read-only tools and tool/resource discovery          |
-| `mcp:write` | Drafting, updating, and other mutating actions       |
-| `mcp:apps`  | Inline MCP Apps, charts, dashboards, drafts, and UIs |
+snapshots. The `mcp:read` / `mcp:write` / `mcp:apps` scopes are the same ones
+covered in [Standard remote MCP OAuth](#standard-oauth) below.
 
 Cursor, Goose, Postman, MCPJam, and VS Code GitHub Copilot use the same remote
 MCP URL through their own MCP-server UIs when their build supports remote OAuth
@@ -213,7 +209,7 @@ instructions:
 npx skills@latest add BuilderIO/agent-native --skill assets
 ```
 
-The raw `skills` CLI installs `SKILL.md` files only; local MCP clients still
+The raw `skills` CLI installs `SKILL.md` files only; local MCP hosts still
 need a connector such as `npx @agent-native/core@latest connect https://assets.agent-native.com`.
 
 | Skill    | Alias              | For                    |
@@ -239,7 +235,7 @@ The connection is **per-user, scoped, and revocable**. In the OAuth path, the ho
 Once connected, auth should persist long-term — access tokens last 30 days by default (override with `MCP_OAUTH_ACCESS_TOKEN_TTL` on the server, e.g. `7d` or `12h`) with a sliding 365-day refresh window, so random 401s should be rare. When one does happen, use the lightweight reconnect command rather than reinstalling:
 
 ```bash
-npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex
+npx @agent-native/core@latest reconnect https://plan.agent-native.com --client codex
 ```
 
 `reconnect` finds any MCP config entry whose URL ends in `/_agent-native/mcp` for the given host and selected client (matching by URL regardless of connector name), then refreshes or replaces the auth material without touching your installed skills or re-running the full install flow. Pass the base app URL (e.g. `https://plan.agent-native.com`) — the `/_agent-native/mcp` suffix is inferred. Auth and tool loading are per client, so restart/reload that client afterward; Codex needs a new session before newly loaded tools appear.
@@ -250,7 +246,7 @@ Never reinstall the skill from scratch just to fix a 401 — `reconnect` is the
 
 ### Connect page fallback {#connect-page-fallback}
 
-For MCP clients that cannot add a remote OAuth URL directly, open the app in your browser and use its **Connect** affordance (served at `https://<app>/_agent-native/mcp/connect`). While logged in, click **Connect / Authorize**. The page hands you either a one-click deep link that configures a detected agent, or a ready-to-paste `.mcp.json` block:
+For MCP hosts that cannot add a remote OAuth URL directly, open the app in your browser and use its **Connect** affordance (served at `https://<app>/_agent-native/mcp/connect`). While logged in, click **Connect / Authorize**. The page hands you either a one-click deep link that configures a detected agent, or a ready-to-paste `.mcp.json` block:
 
 ```jsonc
 // .mcp.json
@@ -267,7 +263,7 @@ For MCP clients that cannot add a remote OAuth URL directly, open the app in you
 
 Restart the agent client after connecting so it picks up the new MCP server.
 
-Use this manual bearer block for MCP clients that cannot complete the standard remote MCP OAuth flow, or for one-off debugging when you explicitly want to paste a token.
+Use this manual bearer block for MCP hosts that cannot complete the standard remote MCP OAuth flow, or for one-off debugging when you explicitly want to paste a token.
 
 ### Standard remote MCP OAuth {#standard-oauth}
 
@@ -420,17 +416,12 @@ included regardless of the declared list.
 
 ## What you can do once connected {#what-you-can-do}
 
-Once your agent is connected, every caller gets the compact catalog by default
-(see [Catalog tiers](#catalog-tiers)) — code/stdio developer clients, the local
-CLI proxy, and chat hosts like Claude and ChatGPT alike. That surface is the
-template-declared app actions plus the builtin cross-app verbs (`list_apps`,
-`open_app`, `ask_app`, and the app-only embed helper). Use `ask_app` to route a
-natural-language task through an app agent (the same cross-app entry point
-[A2A](/docs/a2a-protocol) uses). `tool-search` is always present, so any tool
-outside the compact list stays reachable on demand. To get the full ~105-tool
-surface up front, opt in explicitly with `--full-catalog` or
-`AGENT_NATIVE_MCP_FULL_CATALOG=1`. In all cases, ask the agent to do real work
-and it hands back a link straight into the running app:
+Once your agent is connected, it sees the [compact catalog](#catalog-tiers) by
+default: template-declared app actions plus the builtin cross-app verbs
+(`list_apps`, `open_app`, `ask_app`, and the app-only embed helper). Use
+`ask_app` to route a natural-language task through an app agent (the same
+cross-app entry point [A2A](/docs/a2a-protocol) uses). Ask the agent to do real
+work and it hands back a link straight into the running app:
 
 ```
 > draft an email to John about the Q3 report
@@ -453,7 +444,7 @@ entries and `resources/read` content, not on the tool descriptor.
 
 For ChatGPT/Claude-style OAuth app hosts, the discovery surface is compact by default: `tools/list` and `resources/list` advertise the generic `open_app` embed path instead of every action-specific MCP App resource (see [Catalog tiers](#catalog-tiers)). Mark an individual action with `mcpApp.compactCatalog: true` only when it truly needs to stay visible in chat-host discovery.
 
-That makes the same app surface available to every compatible host rather than building per-client shims. Which hosts render MCP Apps inline (and the connector-cache gotcha after metadata changes) lives in [MCP Apps → Client support and caching](/docs/mcp-apps#client-support) — that page is the single home for the client matrix.
+That makes the same app surface available to every compatible host rather than building per-client shims. Which hosts render MCP Apps inline (and the connector-cache gotcha after metadata changes) lives in [MCP Apps → Host support and caching](/docs/mcp-apps#client-support) — that page is the single home for the host matrix.
 
 In practice, every agent-native app should be authored with both: MCP Apps for inline review/edit in capable hosts, and `link` for universal round-tripping back to the full app. CLI/code-editor clients that do not render an iframe fall back to the deep link. Human-selection tools can add a paste-back step to that fallback: for example, the Assets picker opens from the fallback link, lets the user choose media in the browser, then copies a handoff summary that the user pastes back into the chat.
 
@@ -660,7 +651,7 @@ Restart the client after `install` so it picks up the new MCP server.
 
 ### Manual `.mcp.json` HTTP entry {#manual-entry}
 
-You can also write the MCP client config by hand against any deployed endpoint with a token you supply yourself (an `ACCESS_TOKEN`, or an `A2A_SECRET`-signed JWT carrying the caller's `sub` + `org_domain` so tool runs stay tenant-scoped):
+You can also write the host's MCP config by hand against any deployed endpoint with a token you supply yourself (an `ACCESS_TOKEN`, or an `A2A_SECRET`-signed JWT carrying the caller's `sub` + `org_domain` so tool runs stay tenant-scoped):
 
 ```jsonc
 // .mcp.json
@@ -675,7 +666,7 @@ You can also write the MCP client config by hand against any deployed endpoint w
 }
 ```
 
-This is the unmanaged equivalent of what `connect` writes for you. See [MCP Protocol](/docs/mcp-protocol) for the full auth env-var matrix.
+This is the unmanaged equivalent of what `connect` writes for you. See [MCP Server](/docs/mcp-protocol) for the full auth env-var matrix.
 
 ### Dev vs production tool surface {#dev-vs-prod}
 
@@ -710,7 +701,7 @@ Full-app embeds also avoid handing the MCP bearer token to the browser. The MCP
 The fallback hosted `connect` flow never copies the deployment's shared secret. Instead:
 
 - A logged-in browser session mints a **per-user, scoped, revocable** token — an `A2A_SECRET`-signed JWT carrying the caller's `sub` + `org_domain` and a unique `jti`, so every tool run stays tenant-scoped via `runWithRequestContext`.
-- The existing `/_agent-native/mcp` endpoint accepts that token like any other bearer (see [MCP Protocol](/docs/mcp-protocol)) — no new endpoint, no new transport.
+- The existing `/_agent-native/mcp` endpoint accepts that token like any other bearer (see [MCP Server](/docs/mcp-protocol)) — no new endpoint, no new transport.
 - The same Connect page lists every token you've minted and lets you **revoke** any of them by `jti`. Treat them like personal access tokens: one per agent client, revoke when a machine is decommissioned.
 - The deep link the agent hands back carries no privileged state. The record-focusing `navigate` write is always scoped to the **browser** session, never the agent's token — so a link is safe to paste into a terminal or chat transcript.
 
@@ -745,10 +736,10 @@ The fallback hosted `connect` flow never copies the deployment's shared secret.
 - Invent a new navigation mechanism; bridge to the existing `navigate` / `application_state` contract.
 - Widen the public template allow-list when scaffolding an app from an external agent — the allow-list is authoritative and guarded.
 
-## Related {#related}
+## What's next {#whats-next}
 
 - [MCP Apps](/docs/mcp-apps) — authoring MCP App UIs, the embed bridge, and host bridge API.
-- [MCP Protocol](/docs/mcp-protocol) — the auto-mounted MCP server and `ask-agent` meta-tool.
+- [MCP Server](/docs/mcp-protocol) — the auto-mounted MCP server and `ask-agent` meta-tool.
 - [MCP Clients](/docs/mcp-clients) — the symmetric direction: your app consuming local/remote MCP servers.
 - [A2A Protocol](/docs/a2a-protocol) — the `ask-agent` meta-tool and JSON-RPC peer calls.
 - [Actions](/docs/actions) — defining actions, `publicAgent`, GET / `readOnly`.

package/docs/content/faq.mdx

@@ -247,3 +247,11 @@ upgrade or typecheck fails, fix app-level code or ask — then re-run upgrade.
 ### Why is this a framework and not a library? {#why-framework-not-library}
 
 The shared database, live sync, actions system, and application state only work because they're wired together from the ground up — the UI reacts to agent changes instantly, agents communicate, and the agent understands what the user is looking at. A library gives you pieces; this is an architecture. See [Key Concepts](/docs/key-concepts).
+
+## 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
+- [**Templates**](/docs/cloneable-saas) — fork 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/file-uploads.mdx

@@ -108,10 +108,12 @@ When your app is connected to Builder.io, file uploads are automatically routed
 
 Register a custom provider in a server plugin to use any storage backend (S3, Cloudflare R2, GCS, etc.):
 
-```ts
-// server/plugins/file-upload.ts
+```ts filename="server/plugins/file-upload.ts"
+import { S3 } from "@aws-sdk/client-s3";
 import { registerFileUploadProvider } from "@agent-native/core/file-upload";
-import { resolveSecret } from "@agent-native/core/server";
+import { defineNitroPlugin, resolveSecret } from "@agent-native/core/server";
+
+const s3Client = new S3({ region: process.env.AWS_REGION });
 
 export default defineNitroPlugin(() => {
   const readBucket = () => resolveSecret("S3_BUCKET");
@@ -184,3 +186,10 @@ if (result) {
   // No provider configured — handle SQL fallback yourself, or skip
 }
 ```
+
+## What's next
+
+- [**Database**](/docs/database) — why binary blobs stay out of SQL and go through this provider abstraction instead
+- [**Security — Secrets Management**](/docs/security#secrets) — how `resolveSecret()` and the credential vault encrypt provider keys at rest
+- [**Onboarding**](/docs/onboarding) — registering a custom provider's setup step in the sidebar checklist
+- [**Deployment**](/docs/deployment) — connecting Builder.io or a custom provider in production

package/docs/content/frames.mdx

@@ -156,6 +156,11 @@ sidebar inside the iframe instead, so you can preview exactly what end users see
 
 ## Integrated terminal and CLI switching {#cli-terminal}
 
+This needs a code-capable frame connected — Agent Native Desktop, the local dev
+frame, or the Builder.io cloud frame. A plain scaffolded app running `pnpm dev`
+on its own shows the code-required dialog instead of a terminal; see
+[Running it](#running) below.
+
 In development the panel includes an embedded terminal (`AgentTerminal`, also
 from `@agent-native/core/client`) backed by a PTY server. You can run a real
 coding CLI right beside the app and switch between them; the terminal restarts
@@ -233,3 +238,14 @@ code:
   endpoint (whose payload key is still `devMode`), and the `agent-chat.mode`
   settings key are unchanged.
 - `useDevMode()` remains as a deprecated alias for `useCodeMode()`.
+
+## What's next
+
+- [**Drop-in Agent**](/docs/drop-in-agent) — mount `<AgentPanel>` /
+  `<AgentSidebar>` and send messages from your own UI.
+- [**Agent-Native Code UI**](/docs/code-agents-ui) — the coding-tool list and
+  workspace UI code mode adds.
+- [**Harness Agents**](/docs/harness-agents) — run Claude Code, Codex, or Pi as
+  the agent instead of the built-in chat loop.
+- [**Getting Started**](/docs/getting-started) — scaffold your first app and
+  see the embedded panel running.

package/docs/content/generative-ui.mdx

@@ -256,7 +256,7 @@ Do not put provider tokens, private data, or internal secrets directly in the
 generated HTML. Use `extensionFetch()` with `${keys.NAME}` placeholders or
 template actions that resolve credentials server-side.
 
-## Related docs {#related}
+## What's next {#whats-next}
 
 - [Extensions](/docs/extensions) — saved sandboxed mini-apps and the bridge API.
 - [Native Chat UI](/docs/native-chat-ui) — typed first-party React widgets for

package/docs/content/getting-started.mdx

@@ -59,9 +59,7 @@ An action is one typed operation your agent and UI can both call. Replace the
 starter `hello` action with the first real operation in your domain. This example
 analyzes form responses and returns a validated shape for a custom chat chart:
 
-<!-- prettier-ignore -->
-```ts
-// actions/analyze-responses.ts
+```ts filename="actions/analyze-responses.ts"
 import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 
@@ -72,18 +70,23 @@ const responseChartResultSchema = z.object({
 
 export default defineAction({
   description: "Analyze recent form responses and render a custom chart.",
-  schema: z.object({ 
-    formId: z.string().default("demo") 
+  schema: z.object({
+    formId: z.string().default("demo"),
   }),
   outputSchema: responseChartResultSchema,
-  chatUI: { 
-    renderer: "responses.response-chart", 
-    title: "Response chart" 
+  chatUI: {
+    renderer: "responses.response-chart",
+    title: "Response chart",
   },
   readOnly: true,
   run: async ({ formId }) => ({
     title: `Responses for ${formId}`,
-    points: [{ day: "Mon", responses: 12 }, { day: "Tue", responses: 18 }, { day: "Wed", responses: 24 }, { day: "Thu", responses: 21 }],
+    points: [
+      { day: "Mon", responses: 12 },
+      { day: "Tue", responses: 18 },
+      { day: "Wed", responses: 24 },
+      { day: "Thu", responses: 21 },
+    ],
   }),
 });
 ```
@@ -108,9 +111,11 @@ The action above declares `outputSchema` and a product-specific
 into prose. Register a React component for that exact renderer id, for example
 by importing `app/chat-renderers.tsx` once from `app/root.tsx`:
 
-<!-- prettier-ignore -->
 ```tsx
-import { registerActionChatRenderer, type ToolRendererProps,} from "@agent-native/core/client/chat";
+import {
+  registerActionChatRenderer,
+  type ToolRendererProps,
+} from "@agent-native/core/client/chat";
 
 type ResponseChartResult = {
   title: string;
@@ -125,8 +130,14 @@ function ResponseChart({ context }: ToolRendererProps) {
       <h3 className="text-sm font-medium">{result.title}</h3>
       <div className="mt-4 flex h-32 items-end gap-2">
         {result.points.map((point) => (
-          <div key={point.day} className="flex flex-1 flex-col items-center gap-2">
-            <div className="w-full rounded-t bg-primary" style={{ height: `${(point.responses / max) * 100}%` }} />
+          <div
+            key={point.day}
+            className="flex flex-1 flex-col items-center gap-2"
+          >
+            <div
+              className="w-full rounded-t bg-primary"
+              style={{ height: `${(point.responses / max) * 100}%` }}
+            />
             <span className="text-xs text-muted-foreground">{point.day}</span>
           </div>
         ))}
@@ -174,8 +185,7 @@ Inline chat is great for the first result. A real app needs durable data the
 agent can add, update, and revisit. Add a response-insights table in your schema
 and keep reads/writes behind actions:
 
-```ts
-// server/db/schema.ts
+```ts filename="server/db/schema.ts"
 import { integer, now, table, text } from "@agent-native/core/db/schema";
 
 export const responseInsights = table("response_insights", {
@@ -209,9 +219,7 @@ separate REST route just for the browser if an action is the operation.
 
 Now add a durable page for the data behind the chat result:
 
-<!-- prettier-ignore -->
-```tsx
-// app/routes/response-insights.tsx
+```tsx filename="app/routes/response-insights.tsx"
 import { useActionMutation, useActionQuery } from "@agent-native/core/client";
 
 export default function ResponseInsightsRoute() {
@@ -224,10 +232,15 @@ export default function ResponseInsightsRoute() {
         <h1>Response insights</h1>
         <p>Insights the agent created from form responses.</p>
       </header>
-      <button onClick={() => createInsight.mutate({ formId: "demo" })}>Analyze demo form</button>
+      <button onClick={() => createInsight.mutate({ formId: "demo" })}>
+        Analyze demo form
+      </button>
       <section>
         {insights.data?.map((insight) => (
-          <article key={insight.id}><h2>{insight.title}</h2><p>{insight.summary}</p></article>
+          <article key={insight.id}>
+            <h2>{insight.title}</h2>
+            <p>{insight.summary}</p>
+          </article>
         ))}
       </section>
     </main>
@@ -286,7 +299,7 @@ framework pieces. If you are building a real analytics product, start from
 connect your providers, use the existing dashboards and agent actions, then
 customize the app from there.
 
-## Where to go next {#next}
+## What's next {#next}
 
 - **[Actions](/docs/actions)** — schemas, auth, approvals, hooks, and transport.
 - **[Native Chat UI](/docs/native-chat-ui)** — render action results as tables,

package/docs/content/harness-agents.mdx

@@ -6,9 +6,13 @@ search: "harness agents AgentHarness ai-sdk HarnessAgent Claude Code Codex Pi Cu
 
 # Harness Agents
 
-> **Who is this for:** host authors wiring a full coding runtime (Claude Code,
-> Codex, Pi) into Agent-Native as the agent. Building an app? Start with
-> [Creating Templates](/docs/creating-templates).
+<Callout id="doc-block-harn1who" tone="info">
+
+**Who is this for:** host authors wiring a full coding runtime (Claude Code,
+Codex, Pi) into Agent-Native as the agent. Building an app? Start with
+[Creating Templates](/docs/creating-templates).
+
+</Callout>
 
 A harness agent is a full agent runtime — Claude Code, Codex, Pi, and similar —
 that owns its own loop, workspace, native file tools, session state, compaction,
@@ -408,7 +412,7 @@ one implementation of this contract, not the public abstraction.
 - Don't expose every app action to every harness session by default. Hand it a
   small, intentional tool set.
 
-## Related docs {#related-docs}
+## What's next
 
 - [Native Chat UI](/docs/native-chat-ui) — put your own agent behind the chat UI with `AgentChatRuntime`.
 - [Agent Surfaces](/docs/agent-surfaces) — choose headless, chat, sidecar, or full-app.

package/docs/content/human-approval.mdx

@@ -7,8 +7,13 @@ description: "Pause the agent before a high-consequence action runs — defineAc
 
 Most actions should just run. A few — sending an email, charging a card, deleting an account — are outward-facing and hard to undo, and you don't want the agent to do them autonomously. For those, `defineAction` has an opt-in **approval gate**: when the agent tries to call the action, the loop pauses, surfaces an Approve/Deny affordance to the human, and runs the action _only_ after the human approves that specific call.
 
-> [!WARNING]
-> Keep approvals rare. Every gated action is a hard stop in the agent loop — it interrupts the run and demands a human round-trip. Use `needsApproval` only for genuinely high-consequence, hard-to-undo, outward-facing operations. If you find yourself gating reads or routine writes, you're holding it wrong. The default is **off**, and almost every action should leave it off.
+<Callout tone="warning">
+  Keep approvals rare. Every gated action is a hard stop in the agent loop — it
+  interrupts the run and demands a human round-trip. Use `needsApproval` only
+  for genuinely high-consequence, hard-to-undo, outward-facing operations. If
+  you find yourself gating reads or routine writes, you're holding it wrong. The
+  default is **off**, and almost every action should leave it off.
+</Callout>
 
 ## The `needsApproval` gate {#needs-approval}
 
@@ -135,7 +140,7 @@ On `approval_required`, the chat UI renders an **Approve / Deny** affordance on
 
 The canonical (and intentionally rare) use of this gate in the framework is the Mail template's `send-email` action, which sets `needsApproval: true` so the agent can draft and queue freely but can never actually send a message without a human approving the specific send.
 
-## Related
+## What's next
 
 - [**Actions**](/docs/actions#needs-approval) — the full `defineAction` surface, including `outputSchema` for validating return values.
 - [**Security**](/docs/security) — when to reach for an approval gate vs. hiding an action from the model.

package/docs/content/internationalization.mdx

@@ -39,8 +39,7 @@ resolved locale/catalog into that script to avoid hydration mismatches.
 
 Each localized template keeps catalogs under `app/i18n/`:
 
-```ts
-// app/i18n/index.ts
+```ts filename="app/i18n/index.ts"
 import enUS from "./en-US";
 import type { AgentNativeI18nCatalog } from "@agent-native/core/client";
 
@@ -106,8 +105,8 @@ locale-sensitive date/number formatting inside translation strings.
 Public docs pages use the same core provider, but with
 `persistPreference={false}` so anonymous docs traffic uses localStorage and the
 browser language instead of SQL settings actions. The English source remains in
-`packages/core/docs/content/*.md`. Localized page overrides live next to it under
-`packages/core/docs/content/locales/<locale>/<slug>.md`.
+`packages/core/docs/content/*.mdx`. Localized page overrides live next to it under
+`packages/core/docs/content/locales/<locale>/<slug>.mdx`.
 
 Use the same BCP-47 locale codes as app catalogs. Keep the same slug as the
 English source, preserve stable anchors with `{#anchor}` on translated headings,
@@ -149,3 +148,9 @@ review.
 Do not translate stable identifiers such as action names, routes, enum values,
 app-state keys, database values, protocol fields, env var names, or provider
 names.
+
+## What's next
+
+- [**Client**](/docs/client) — the `AppProviders` wrapper and other browser hooks i18n builds on
+- [**Toolkit: Settings**](/docs/toolkit-settings) — put `<LanguagePicker>` on the standard settings page
+- [**Getting Started**](/docs/getting-started) — build your first app on a template that already ships localized catalogs