@agent-native/core 0.93.0 → 0.94.1

package/corpus/core/docs/content/deployment.mdx

@@ -233,7 +233,7 @@ receives upstream security updates.
 
 ### Docker {#docker}
 
-```dockerfile
+```dockerfile filename="Dockerfile"
 FROM node:24-slim AS build
 WORKDIR /app
 COPY package.json pnpm-lock.yaml ./
@@ -273,7 +273,7 @@ node .output/server/index.mjs
 A reusable workspace Dockerfile can take the app name and path prefix as build
 arguments:
 
-```dockerfile maxLines=12
+```dockerfile filename="Dockerfile.workspace-app" maxLines=12
 FROM node:24-slim AS build
 WORKDIR /workspace
 RUN corepack enable
@@ -303,7 +303,7 @@ Then compose Postgres, the app containers, and your proxy. This example uses
 Caddy because it can terminate HTTP locally or sit behind Cloudflare's SSL
 proxy, but the important part is the path-prefix routing:
 
-```yaml maxLines=30
+```yaml filename="docker-compose.yml" maxLines=30
 services:
   postgres:
     image: postgres:17
@@ -365,7 +365,7 @@ volumes:
   postgres-data:
 ```
 
-```caddyfile
+```caddyfile filename="Caddyfile"
 agents.example.com {
   reverse_proxy /mail* mail:3000
   reverse_proxy /calendar* calendar:3000
@@ -387,8 +387,7 @@ Notes for this shape:
 
 ## Vercel {#vercel}
 
-```ts
-// vite.config.ts
+```ts filename="vite.config.ts"
 export default defineConfig({
   plugins: [agentNative({ nitro: { preset: "vercel" } })],
 });
@@ -418,8 +417,7 @@ The workspace build copies each app's Nitro `vercel` output into the root `.verc
 
 The Nitro `netlify` preset works well and, in practice, has given us much faster cold starts than Cloudflare Pages (~200ms TTFB vs ~9s) for templates that talk to external Postgres (Neon). Either set the preset in `vite.config.ts`:
 
-```ts
-// vite.config.ts
+```ts filename="vite.config.ts"
 export default defineConfig({
   plugins: [agentNative({ nitro: { preset: "netlify" } })],
 });
@@ -437,8 +435,7 @@ The workspace build writes static assets under `dist/_workspace_static/` and rou
 
 ## Cloudflare Pages {#cloudflare-pages}
 
-```ts
-// vite.config.ts
+```ts filename="vite.config.ts"
 export default defineConfig({
   plugins: [agentNative({ nitro: { preset: "cloudflare_pages" } })],
 });
@@ -446,8 +443,7 @@ export default defineConfig({
 
 ## AWS Lambda {#aws-lambda}
 
-```ts
-// vite.config.ts
+```ts filename="vite.config.ts"
 export default defineConfig({
   plugins: [agentNative({ nitro: { preset: "aws_lambda" } })],
 });
@@ -455,8 +451,7 @@ export default defineConfig({
 
 ## Deno Deploy {#deno-deploy}
 
-```ts
-// vite.config.ts
+```ts filename="vite.config.ts"
 export default defineConfig({
   plugins: [agentNative({ nitro: { preset: "deno_deploy" } })],
 });
@@ -521,8 +516,7 @@ the agent chat plugin. SQL inspection is enabled by default, while database
 writes go through typed app actions unless the app explicitly opts into raw
 write tools:
 
-```ts
-// server/plugins/agent-chat.ts
+```ts filename="server/plugins/agent-chat.ts"
 export default createAgentChatPlugin({
   // Default: "read"
   databaseTools: "read", // "write" | "read" | "off"
@@ -547,8 +541,7 @@ By default, production agents run without code-execution tools. They can call ap
 
 Node-compatible deployments can opt into production code execution through the agent chat plugin or an environment override:
 
-```ts
-// server/plugins/agent-chat.ts
+```ts filename="server/plugins/agent-chat.ts"
 export default createAgentChatPlugin({
   codeExecution: { production: "sandboxed" },
 });
@@ -586,3 +579,11 @@ See [Frames](/docs/frames) for more on the embedded agent panel vs. cloud frame
 ## Multi-instance deploys {#multi-instance}
 
 Agent-native apps store all state in SQL via Drizzle and sync the UI via [polling](/docs/key-concepts#polling-sync) against the database — no file-system state, no sticky sessions, no in-memory caches. That means multi-instance and serverless deployments work out of the box: point every instance at the same `DATABASE_URL` and they converge automatically. See [Key Concepts — Data in SQL](/docs/key-concepts#data-in-sql) and [Portability](/docs/key-concepts#hosting-agnostic).
+
+## What's next
+
+- [**Database**](/docs/database#production) — pick a persistent SQL backend before your first production deploy
+- [**Security**](/docs/security) — the production checklist and opt-in flags referenced throughout this page
+- [**Authentication**](/docs/authentication) — OAuth credentials and env vars for the auth mode you choose
+- [**Multi-App Workspace**](/docs/multi-app-workspace) — the workspace model behind `deploy`'s one-origin build
+- [**Frames**](/docs/frames) — the embedded agent panel vs. Builder.io's cloud frame for production UI edits

package/corpus/core/docs/content/dispatch.mdx

@@ -7,7 +7,11 @@ description: "The workspace control plane: secrets vault, integration hub, cross
 
 Dispatch is the central app that sits in front of every other app in your workspace and handles secrets, integrations, messaging, and cross-app delegation. It is the **workspace control plane** — the single agent your team talks to, the single place credentials live, and the single router that decides which specialist app should handle a given request.
 
-> **Dispatch the template vs. `@agent-native/dispatch` the package.** This page covers the Dispatch app/template concept — what it does and why you'd want it. The `@agent-native/dispatch` npm package is the separately published runtime that bundles the Dispatch template's server logic (vault, integrations, destinations, scheduled jobs, and cross-app delegation) as a drop-in package for workspaces that extend it. For the scaffolded app itself (routes, screens, agent guide), see the [Dispatch template](/docs/template-dispatch).
+<Callout tone="info">
+
+**Dispatch the template vs. `@agent-native/dispatch` the package.** This page covers the Dispatch app/template concept — what it does and why you'd want it. The `@agent-native/dispatch` npm package is the separately published runtime that bundles the Dispatch template's server logic (vault, integrations, destinations, scheduled jobs, and cross-app delegation) as a drop-in package for workspaces that extend it. For the scaffolded app itself (routes, screens, agent guide), see the [Dispatch template](/docs/template-dispatch).
+
+</Callout>
 
 Without Dispatch, every app in a multi-app workspace ends up re-implementing the same plumbing: its own Slack bot, its own secret store, its own scheduled jobs, its own copy of the workspace's instructions. Rotating one API key turns into ten redeployments. Adding a new policy turns into ten copy-pastes. Dispatch centralizes all of that in one app so the others stay focused on their domain.
 
@@ -261,7 +265,7 @@ Three short steps:
 
 Then add credentials to the vault and (optionally) author global workspace resources under **Resources**. Vault keys can still be synced or granted depending on access mode; All-app workspace resources are inherited automatically. If you need per-app secret isolation, switch the vault access setting to manual before granting individual apps.
 
-## See also {#see-also}
+## What's next {#whats-next}
 
 - [Dispatch template](/docs/template-dispatch) — the actual scaffolded app, with its full action catalog and agent guide
 - [Messaging](/docs/messaging) — connecting Slack, email, Telegram, WhatsApp

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

@@ -5,13 +5,19 @@ description: "Mount the agent chat + workspace into any React app with <AgentPan
 
 # Drop-in Agent
 
-> **Developer page.** This page is for developers embedding the agent into a React app. For the end-user experience of working with the agent, see [Using Your Agent](/docs/using-your-agent).
+<Callout tone="info">
+
+**Developer page.** This page is for developers embedding the agent into a React app. For the end-user experience of working with the agent, see [Using Your Agent](/docs/using-your-agent).
+
+</Callout>
 
 You don't need to build agent-native from scratch. The agent chat, workspace tab, CLI terminal, voice input, and all the related infrastructure ship as a handful of React components you drop into any app.
 
-> **Prerequisite:** the server has to be running the `agent-chat-plugin` (it auto-mounts in every template). If you're starting from scratch, see [Server](/docs/server).
->
-> Need the public API map instead of a tutorial? See [Component API](/docs/components).
+<Callout tone="info">
+
+**Prerequisite:** the server has to be running the `agent-chat-plugin` (it auto-mounts in every template). If you're starting from scratch, see [Server](/docs/server). Need the public API map instead of a tutorial? See [Component API](/docs/components).
+
+</Callout>
 
 ## The components at a glance {#components}
 

package/corpus/core/docs/content/durable-background-runs.mdx

@@ -5,10 +5,14 @@ description: "Long agent-chat turns can run on a separate 15-minute Netlify back
 
 # Durable Background Runs
 
-> **Who is this for:** anyone deploying an agent-native app who wants long,
-> multi-step agent turns to complete server-side, and anyone wondering what the
-> `AGENT_CHAT_DURABLE_BACKGROUND` flag and the second Netlify function do. This
-> is opt-in and entirely inside the framework — there is no app code to write.
+<Callout id="doc-block-dbgr1who" tone="info">
+
+**Who is this for:** anyone deploying an agent-native app who wants long,
+multi-step agent turns to complete server-side, and anyone wondering what the
+`AGENT_CHAT_DURABLE_BACKGROUND` flag and the second Netlify function do. This
+is opt-in and entirely inside the framework — there is no app code to write.
+
+</Callout>
 
 A normal hosted agent turn runs inside the synchronous request function, which
 is capped by the platform's request timeout (~10s on Netlify's free tier, and
@@ -190,7 +194,7 @@ Durable runs are opt-in per app and default OFF. Enable with AGENT_CHAT_DURABLE_
 
 </Callout>
 
-## Related
+## What's next
 
 - [**Durable Resume**](/docs/durable-resume) — how an interrupted run resumes
   without repeating completed side effects (a separate, always-on protection).

package/corpus/core/docs/content/durable-resume.mdx

@@ -5,9 +5,13 @@ description: "When a hosted agent run is interrupted and resumes, completed side
 
 # Durable Resume
 
-> **Who is this for:** anyone who wants to understand how the framework's run
-> recovery avoids duplicate side effects. This is built-in behavior — there is
-> nothing to wire up.
+<Callout id="doc-block-dres1who" tone="info">
+
+**Who is this for:** anyone who wants to understand how the framework's run
+recovery avoids duplicate side effects. This is built-in behavior — there is
+nothing to wire up.
+
+</Callout>
 
 Hosted agent runs get interrupted: a serverless function hits its hard timeout mid-stream, a gateway drops the connection at 45s, a socket hangs up, the platform cold-starts. The framework already recovers from these by saving the conversation prefix and re-running the LLM call ("continue from where you left off"). But recovery alone has a sharp edge: if the interrupted attempt **already sent an email or created a ticket**, a naive resume could do it again.
 
@@ -100,8 +104,9 @@ Together the two layers mean an interrupted run that already had a real side eff
 
 </Callout>
 
-## Related
+## What's next
 
 - [**Real-Time Sync**](/docs/real-time-collaboration) — how the durable run ledger streams to the client and replays on reconnect.
 - [**Actions**](/docs/actions) — `readOnly` marks reads as safe to re-run; everything else is treated as side-effecting.
 - [**In-Loop Processors**](/docs/processors) — another loop-internal hardening seam.
+- [**Durable Background Runs**](/docs/durable-background-runs) — moving a long turn onto a separate background function.

package/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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