@agent-native/core 0.93.0 → 0.94.1

package/docs/content/code-agents-ui.mdx

@@ -354,6 +354,54 @@ Agent-Native Code treats migration as a capability, not a separate app category.
 
 `/migrate` is the built-in goal for moving an existing app, URL, or described product into Agent-Native. It is a slash goal in the Code workspace — not a separate template to scaffold and not a one-off product — so it shares the same session store, transcript, run controls, and Desktop hub as every other Code session, and you can resume, attach to, inspect, and stop it the same way.
 
+<Diagram id="doc-block-1lox5dw" title="/migrate is a Code session, not a separate app" summary={"A path, URL, or description goes in; the run shares the same store, transcript, and controls as every other Code session, and can emit a portable dossier."}>
+
+```html
+<div class="diagram-migrate">
+  <div class="diagram-col">
+    <div class="diagram-pill">./local-app</div>
+    <div class="diagram-pill">https://example.com</div>
+    <div class="diagram-pill">--describe \"...\"</div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center" data-rough>
+    <span class="diagram-pill accent">/migrate goal</span
+    ><small class="diagram-muted">same store · transcript · run controls</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-col">
+    <div class="diagram-box" data-rough>Migrated app</div>
+    <div class="diagram-pill ok">--emit dossier</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-migrate {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-migrate .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.diagram-migrate .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+.diagram-migrate .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+```
+
+</Diagram>
+
 ```bash
 npx @agent-native/core@latest code /migrate ./my-next-app --out ../migrated-app
 npx @agent-native/core@latest code /migrate https://example.com --describe "marketing site plus dashboard"
@@ -363,6 +411,12 @@ npx @agent-native/core@latest migrate ./my-next-app --out ../migrated-app   # sh
 
 Local source paths are read-only; generated output must live outside the source tree. Use `--emit <dir>` to write a portable migration dossier (`AGENTS.md`, `MIGRATION_PLAYBOOK.md`, assessment, and an `ir.json` inventory when available) and hand it to another coding agent instead of opening the internal run surface. `/migrate` reuses the framework's normal credentials system — there is no migration-specific key store. The `@agent-native/migrate` package exposes a reusable engine (`createMigrationRun`, `discoverMigration`, `planMigration`, source/target adapters) for custom workflows.
 
+<Callout id="doc-block-mig8ban" tone="info">
+  The legacy hidden `migration` detail app has been removed. Use the Code
+  workspace, the Desktop Code tab, or an emitted dossier as the supported
+  surfaces.
+</Callout>
+
 Project-specific commands live in:
 
 ```text
@@ -522,3 +576,14 @@ The stylesheet uses the same shadcn-style HSL custom properties as the templates
 ## Limits
 
 The browser template is local-first. It can start and resume runs while its local Node server is alive. For native process lifecycle, terminal launch, and app webviews, use Desktop.
+
+## What's next
+
+- [**Harness Agents**](/docs/harness-agents) — run Claude Code, Codex, or Pi
+  as the agent instead of the built-in Code loop.
+- [**Adapters**](/docs/sandbox-adapters) — swap the sandbox or CLI backend
+  behind the agent's `run-code` tool.
+- [**Agent Teams**](/docs/agent-teams) — the same run-manager foundation for
+  delegating work to background sub-agents.
+- [**Durable Background Runs**](/docs/durable-background-runs) — the hosted
+  execution model behind long-running work.

package/docs/content/components.mdx

@@ -229,19 +229,25 @@ tool-call display.
 ## Native Tool Widgets {#native-tool-widgets}
 
 Use native tool widgets when an action result should render as app-quality UI
-inside chat instead of plain JSON. Built-in reusable outputs include
-`DataTableWidget`, `DataChartWidget`, and `DataWidgetResult`; they are exported
-from `@agent-native/core/client/chat` and the root client entry. See
-[Native Chat UI](/docs/native-chat-ui) for the action result contract.
-
-| API                              | Use when                                                                                |
-| -------------------------------- | --------------------------------------------------------------------------------------- |
-| `DataTableWidget`                | You want an action result to render rows and columns in native chat.                    |
-| `DataChartWidget`                | You want compact bar, line, or area chart output in native chat.                        |
-| `DataWidgetResult`               | You want a typed result shape for `"data-table"`, `"data-chart"`, or `"data-insights"`. |
-| `registerActionChatRenderer()`   | You need an action-declared renderer selected by exact `chatUI.renderer`.               |
-| `registerToolRenderer()`         | You need a product-specific native renderer for a non-core tool result.                 |
-| `registerReservedToolRenderer()` | Framework code needs a reserved renderer that wins before template renderers.           |
+inside chat instead of plain JSON. You don't import or mount a widget
+component yourself — an action builds its result with a server-safe helper
+(`createDataTableWidgetResult()`, `createDataChartWidgetResult()`) from
+`@agent-native/core/data-widgets`, and the runtime picks the matching built-in
+React renderer automatically. `DataTableWidget`, `DataChartWidget`, and
+`DataWidgetResult` are the **result-shape types** — exported from
+`@agent-native/core/client/chat` and the root client entry for typing action
+results, not renderable components. See
+[Native Chat UI](/docs/native-chat-ui#action-declared-widgets) for the full action result
+contract and a worked example.
+
+| API                              | Use when                                                                                 |
+| -------------------------------- | ---------------------------------------------------------------------------------------- |
+| `createDataTableWidgetResult()`  | Your action returns rows and columns that should render as a native table in chat.       |
+| `createDataChartWidgetResult()`  | Your action returns series data that should render as a native bar, line, or area chart. |
+| `DataWidgetResult`               | You need the typed union shape for `"data-table"`, `"data-chart"`, or `"data-insights"`. |
+| `registerActionChatRenderer()`   | You need an action-declared renderer selected by exact `chatUI.renderer`.                |
+| `registerToolRenderer()`         | You need a product-specific native renderer for a non-core tool result.                  |
+| `registerReservedToolRenderer()` | Framework code needs a reserved renderer that wins before template renderers.            |
 
 ## Realtime Collab And Presence {#collab-presence}
 
@@ -482,10 +488,12 @@ action so the UI and agent share the same capability.
 ```ts
 import { defineAction } from "@agent-native/core/action";
 import { completeText } from "@agent-native/core/server";
+import { z } from "zod";
 
 export default defineAction({
   description: "Classify a short message",
-  run: async ({ body }: { body: string }) => {
+  schema: z.object({ body: z.string() }),
+  run: async ({ body }) => {
     const result = await completeText({
       systemPrompt: "Return exactly one label.",
       input: body,
@@ -500,3 +508,11 @@ export default defineAction({
 Use `sendToAgentChat({ background: true, openSidebar: false })` instead when
 the work needs tools, state, auditability, user steering, or multi-step
 reasoning.
+
+## What's next {#whats-next}
+
+- [**Drop-in Agent**](/docs/drop-in-agent) — mount `<AgentSidebar>` and `<AgentPanel>` with a tutorial-first walkthrough
+- [**Native Chat UI**](/docs/native-chat-ui) — the action result contract behind data widgets and custom renderers
+- [**Actions**](/docs/actions) — `defineAction()`, schemas, and the action surface these components call
+- [**Real-Time Collaboration**](/docs/real-time-collaboration) — the collab hooks and presence components in depth
+- [**Sharing**](/docs/sharing) — `<ShareButton>` and `<ShareDialog>` wiring for ownable resources

package/docs/content/context-awareness.mdx

@@ -5,9 +5,13 @@ description: "How the agent knows what the user is looking at: navigation state,
 
 # Context Awareness
 
-> **Developer page.** This page is for developers wiring the app's context layer. For the end-user experience — how the agent uses that context in conversation — see [Using Your Agent](/docs/using-your-agent).
+<Callout tone="info">
 
-How the agent knows what the user is looking at -- and how the agent can control what the user sees.
+**Developer page.** This page is for developers wiring the app's context layer. For the end-user experience — how the agent uses that context in conversation — see [Using Your Agent](/docs/using-your-agent).
+
+</Callout>
+
+How the agent knows what the user is looking at — and how the agent can control what the user sees.
 
 ## Overview {#overview}
 
@@ -17,12 +21,12 @@ To understand what to put in which surface (AGENTS.md vs. skills vs. application
 
 Six patterns solve this:
 
-1. **Navigation state** -- the UI writes a `navigation` key to application-state on every route change
-2. **Current URL** -- the framework writes `__url__` so query params are visible and editable by the agent
-3. **Selection state** -- the UI writes a `selection` key when the user focuses, selects, or multi-selects something meaningful
-4. **`view-screen`** -- an action that reads application state, fetches contextual data, and returns a snapshot of what the user sees
-5. **Prompt handoff** -- UI controls call `sendToAgentChat()` when a click should become an agent turn
-6. **`navigate`** -- a one-shot command from the agent that tells the UI where to go
+1. **Navigation state** — the UI writes a `navigation` key to application-state on every route change
+2. **Current URL** — the framework writes `__url__` so query params are visible and editable by the agent
+3. **Selection state** — the UI writes a `selection` key when the user focuses, selects, or multi-selects something meaningful
+4. **`view-screen`** — an action that reads application state, fetches contextual data, and returns a snapshot of what the user sees
+5. **Prompt handoff** — UI controls call `sendToAgentChat()` when a click should become an agent turn
+6. **`navigate`** — a one-shot command from the agent that tells the UI where to go
 
 <Diagram id="doc-block-1jsrbbk" title="How the agent sees what you see" summary={"The UI writes lightweight state keys; view-screen hydrates them into real records; the agent can write navigate back to move the UI."}>
 
@@ -116,10 +120,10 @@ The UI writes a `navigation` key to application-state on every route change. Thi
 
 What to include in navigation state:
 
-- `view` -- the current page/section, such as "inbox", "form-builder", or "dashboard"
-- Item IDs -- the selected/open item, such as `threadId` or `formId`
-- Semantic aliases -- active tab, label name, or other stable app concepts that help the agent reason
-- Light focus state -- focused row, active tab, current panel
+- `view` — the current page/section, such as "inbox", "form-builder", or "dashboard"
+- Item IDs — the selected/open item, such as `threadId` or `formId`
+- Semantic aliases — active tab, label name, or other stable app concepts that help the agent reason
+- Light focus state — focused row, active tab, current panel
 
 Keep `navigation` small and semantic. It should identify the current screen, not duplicate whole records or mirror every query param. Fetch records in `view-screen` so the agent always gets fresh data.
 
@@ -349,7 +353,7 @@ import { writeAppState } from "@agent-native/core/application-state";
 await writeAppState("navigate", { view: "inbox", threadId: "thread-123" });
 ```
 
-On the UI side you never poll or delete this key by hand. Both directions -- writing `navigation` on every route change and consuming the agent's `navigate` command -- are handled by a single hook, [`useNavigationState`](#use-navigation-state), covered in the next section.
+On the UI side you never poll or delete this key by hand. Both directions — writing `navigation` on every route change and consuming the agent's `navigate` command — are handled by a single hook, [`useNavigationState`](#use-navigation-state), covered in the next section.
 
 The `navigation` key belongs to the UI; the agent must never write to it directly. The agent writes `navigate`, the UI performs the move, and that move is what updates `navigation`.
 
@@ -409,7 +413,7 @@ export function useNavigationState() {
 | `getNavigationState` — map the URL to semantic state   | `navigation` writes, tab-scoped plus a global fallback key                               |
 | `getCommandPath` — map a `navigate` command to a route | command polling, delete-after-read, duplicate-command protection, request-source tagging |
 
-`useAgentRouteState` assumes React Router. When navigation does not live in the URL -- a wizard step, a canvas selection, a non-router shell -- drop down to the lower-level `useSemanticNavigationState` instead: you hand it a ready-made `state` value plus `navigationKeys`/`commandKeys` and an `onCommand` callback, and it stays completely agnostic about React Router.
+`useAgentRouteState` assumes React Router. When navigation does not live in the URL — a wizard step, a canvas selection, a non-router shell — drop down to the lower-level `useSemanticNavigationState` instead: you hand it a ready-made `state` value plus `navigationKeys`/`commandKeys` and an `onCommand` callback, and it stays completely agnostic about React Router.
 
 ## Jitter prevention {#jitter-prevention}
 
@@ -432,7 +436,7 @@ How it works:
 - Agent writes are tagged with `requestSource: "agent"` (the action helpers do this automatically)
 - UI writes include the tab's unique ID via `X-Request-Source` header
 - The server stores the source on each event
-- When processing sync events, the UI filters out events matching its own `ignoreSource` value -- so it doesn't refetch data it just wrote
+- When processing sync events, the UI filters out events matching its own `ignoreSource` value — so it doesn't refetch data it just wrote
 - Events from agents, other tabs, and actions still come through normally
 
 <Diagram id="doc-block-t8sq6j" title="Source tagging stops self-refetch jitter" summary="A tab ignores sync events stamped with its own TAB_ID, but still reacts to agent and other-tab writes.">
@@ -478,3 +482,11 @@ How it works:
 ```
 
 </Diagram>
+
+## What's next {#whats-next}
+
+- [**Using Your Agent**](/docs/using-your-agent) — how end users experience the context the agent sees
+- [**Agent Mentions**](/docs/agent-mentions) — `@`-mention files and agents into a turn instead of relying on ambient context
+- [**Drop-in Agent**](/docs/drop-in-agent) — mount the panel that reads and writes this state
+- [**Real-Time Collaboration**](/docs/real-time-collaboration) — keep app state in sync when the agent and users edit together
+- [**Client Methods**](/docs/client) — the full `application-state` and client helper reference

package/docs/content/creating-templates.mdx

@@ -49,7 +49,6 @@ Every template follows the same broad layout:
 <FileTree
   id="doc-block-1pqnp29"
   title="Template project layout"
-  title="my-template/"
   entries={[
     {
       path: "app/",
@@ -175,8 +174,7 @@ The four areas of every template wire together through one shared action surface
 
 Define domain tables with the framework Drizzle helpers so schemas stay portable across SQLite, Postgres, D1, Turso, Supabase, Neon, and other supported backends:
 
-```ts
-// server/db/schema.ts
+```ts filename="server/db/schema.ts"
 import {
   table,
   text,
@@ -207,8 +205,7 @@ Schema changes must be additive. Add tables and columns through `runMigrations()
 
 For app reads and writes, use Drizzle's query builder and portable operators from `drizzle-orm`. Do not write product code with raw SQL when Drizzle can express the query, and do not import from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in templates.
 
-```ts
-// server/plugins/db.ts
+```ts filename="server/plugins/db.ts"
 import { runMigrations } from "@agent-native/core/db";
 
 export default runMigrations(
@@ -352,8 +349,7 @@ For app navigation, prefer one `navigate` command that includes a same-origin
 `path` when the URL is known. Do not also write `__set_url__` for the same move;
 that key is reserved for the framework URL tools and URL-only filter changes.
 
-```ts
-// actions/navigate.ts
+```ts filename="actions/navigate.ts"
 import { defineAction } from "@agent-native/core/action";
 import { writeAppState } from "@agent-native/core/application-state";
 import { z } from "zod";
@@ -447,8 +443,7 @@ Store template skills in `.agents/skills/<name>/SKILL.md`. If users should be ab
 
 If a template needs an API key, OAuth connection, or provider account, register an onboarding step instead of burying the requirement in a README.
 
-```ts
-// server/plugins/onboarding.ts
+```ts filename="server/plugins/onboarding.ts"
 import { defineNitroPlugin } from "@agent-native/core/server";
 import { registerOnboardingStep } from "@agent-native/core/onboarding";
 
@@ -523,3 +518,14 @@ The generated workspace links the local `@agent-native/core` and
 behavior, or first-party templates can be tested before publishing. The package
 `prepack` scripts build `dist` before linking, which keeps the generated
 workspace pointed at current build output.
+
+## What's next
+
+- [**Writing Agent Instructions**](/docs/writing-agent-instructions) — how to
+  keep `AGENTS.md` and skills skimmable as the template grows.
+- [**Agent-Native Toolkit**](/docs/agent-native-toolkit) — reusable sharing,
+  settings, history, and review surfaces instead of rebuilding them per app.
+- [**Multi-App Workspace**](/docs/multi-app-workspace) — make the template fit
+  naturally alongside sibling apps and Dispatch.
+- [**Cloneable SaaS**](/docs/cloneable-saas) — turn a template into a
+  publishable, monetizable product.

package/docs/content/cross-app-sso.mdx

@@ -9,7 +9,11 @@ Each hosted app at `*.agent-native.com` runs its own deployment with its **own s
 
 This is the same trust primitive [A2A](/docs/a2a-protocol) and [External Agents](/docs/external-agents) already use — an `A2A_SECRET`-signed JWT verified at the request boundary — applied to the human sign-in path instead of agent-to-agent calls.
 
-> **Unified deploy vs. per-domain deploy.** If you host all apps at one origin (`your-agents.com/mail`, `your-agents.com/calendar`), you already get shared login via a single cookie domain — no federation needed. Cross-App SSO is only necessary when apps run on separate domains. See [Multi-App Workspaces — Unified deploy](/docs/multi-app-workspace#deployment).
+<Callout tone="info">
+
+**Unified deploy vs. per-domain deploy.** If you host all apps at one origin (`your-agents.com/mail`, `your-agents.com/calendar`), you already get shared login via a single cookie domain — no federation needed. Cross-App SSO is only necessary when apps run on separate domains. See [Multi-App Workspaces — Unified deploy](/docs/multi-app-workspace#deployment).
+
+</Callout>
 
 ## What & why {#what-why}
 
@@ -86,15 +90,17 @@ The flow is a standard authorize → signed-token → callback redirect, with em
 
 </Diagram>
 
-1. **App → Dispatch (authorize).** The app sends the user to the identity authority:
+1. **App → Dispatch (authorize).** The app-side `GET /_agent-native/identity/login` route (what the "Sign in with Agent-Native" button links to) builds the redirect and sends the user to the identity authority:
 
-   ```
+   ```http
    GET https://dispatch.agent-native.com/_agent-native/identity/authorize
        ?app=<requesting-app>
        &redirect_uri=<app-callback-url>
        &state=<csrf-state>
    ```
 
+   `redirect_uri` is this app's own `GET /_agent-native/identity/callback` route — the route that receives the signed token in step 3.
+
 <Endpoint id="doc-block-1wojo41" title="Identity authorize endpoint" method="GET" path="/_agent-native/identity/authorize" summary="Dispatch (identity authority) authenticates the human and redirects back with a signed identity token" auth="Dispatch session (interactive login if none)" params={[
   {
     "name": "app",
@@ -143,7 +149,7 @@ The flow is a standard authorize → signed-token → callback redirect, with em
    | `scope`      | Always `"identity"` — this token authorizes sign-in only |
    | `exp`        | **≤ 2 minutes** from issue                               |
 
-4. **App verifies and JIT-links by email.** The app verifies the token signature with its own `A2A_SECRET`, checks `scope: "identity"` and `exp`, then performs **just-in-time linking strictly by verified email**:
+4. **App verifies and JIT-links by email.** The app's `GET /_agent-native/identity/callback` route verifies the token signature with its own `A2A_SECRET`, checks `scope: "identity"` and `exp`, then performs **just-in-time linking strictly by verified email**:
    - If a local user with that email exists → reuse it unchanged.
    - If not → create a local user for that email.
 
@@ -290,9 +296,13 @@ Once one app is verified, repeat steps 2–3 for the next app — setting `AGENT
 **5. Rollback = unset the env var on that app's deploy.**
 To revert any app, **remove `AGENT_NATIVE_IDENTITY_HUB_URL` from that app's environment and redeploy/restart it.** The app immediately returns to its prior auth behavior. There is **no data change to undo** — identity rows were only ever added, and unsetting the variable simply makes the federation path dormant again. Each app's cutover and rollback are independent and reversible.
 
-> Rollout logs users out as each app is enabled (they re-auth via Dispatch), but they always log back into the **same email-matched account with data intact**, because identity rows are never destroyed or renamed — only added.
+<Callout tone="info">
+
+Rollout logs users out as each app is enabled (they re-auth via Dispatch), but they always log back into the **same email-matched account with data intact**, because identity rows are never destroyed or renamed — only added.
+
+</Callout>
 
-## Related {#related}
+## What's next {#whats-next}
 
 - [Authentication](/docs/authentication) — local auth modes, sessions, orgs, the `A2A_SECRET` env var.
 - [A2A Protocol](/docs/a2a-protocol) — the signed-JWT, verify-at-the-boundary trust model this reuses.

package/docs/content/data-programs.mdx

@@ -321,7 +321,7 @@ The `"program"` dashboard panel source is one adoption of the primitive, impleme
 
 Any app can implement the same adoption for its own dashboards/tables: call `run-data-program` (or `runDataProgram` directly if you're inside the same server process) from your own read path, and hand the returned `rows`/`schema` to your own rendering components.
 
-## Related docs {#related}
+## What's next {#whats-next}
 
 - [Extensions](/docs/extensions) — the sandboxed mini-app primitive data programs share a security posture and sharing model with, but with a UI of its own.
 - [Actions](/docs/actions) — the `run-code` conventions and sandbox globals (`providerFetch`, `appAction`, etc.) data programs are built on.

package/docs/content/database.mdx

@@ -116,8 +116,7 @@ _Planned (not yet available):_ when connected to Builder.io, your app will be ab
 
 Each template creates a lazy, singleton Drizzle client by calling `createGetDb(schema)` from `@agent-native/core/db`. The canonical location is `server/db/index.ts`:
 
-```ts
-// server/db/index.ts
+```ts filename="server/db/index.ts"
 import { createGetDb } from "@agent-native/core/db";
 import * as schema from "./schema.js";
 
@@ -257,9 +256,14 @@ All database schema updates must be **strictly additive**.
 - **Do not rename tables or columns.** Renaming a column or table looks like a drop + create sequence to Drizzle, which will permanently delete your existing production data.
 - If a column needs to be renamed or replaced, add the new column alongside the old one, update your application code to read from/write to both, migrate the data, and only retire the old column in a later release once no active deployments are referencing it.
 
-> [!WARNING]
-> **Never run `drizzle-kit push` against a production database.**
-> Template database schemas only define app-specific domain tables; they do not define central framework tables (`user`, `session`, `application_state`, etc.). If you run `drizzle-kit push` against production, Drizzle will detect these framework tables as "not in schema" and attempt to drop them, causing immediate system-wide failure and data loss.
+<Callout tone="risk">
+  **Never run `drizzle-kit push` against a production database.** Template
+  database schemas only define app-specific domain tables; they do not define
+  central framework tables (`user`, `session`, `application_state`, etc.). If
+  you run `drizzle-kit push` against production, Drizzle will detect these
+  framework tables as "not in schema" and attempt to drop them, causing
+  immediate system-wide failure and data loss.
+</Callout>
 
 ### Safe Migration Path
 
@@ -298,3 +302,11 @@ Instead of pushing directly, schema changes should be applied via SQL migrations
 | --------------------- | ------------------------------------------------------------------------------------------------------- |
 | `DATABASE_URL`        | Persistent SQL connection string (unset = local SQLite; `pglite:./data/pglite` = local Postgres opt-in) |
 | `DATABASE_AUTH_TOKEN` | Auth token for providers that require a separate token, such as Turso/libSQL                            |
+
+## What's next
+
+- [**Security — Data Scoping**](/docs/security#data-scoping) — how `owner_email` and access helpers scope reads and writes
+- [**Sharing**](/docs/sharing#building) — `ownableColumns()` and the visibility model for shared resources
+- [**Server**](/docs/server#request-context) — how actions and custom routes each import `getDb`
+- [**Deployment**](/docs/deployment#persistent-database) — connecting a persistent database per deploy target
+- [**Actions**](/docs/actions#access-control) — a complete, paste-ready action that reads and writes through `getDb`/`schema`

package/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/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/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/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/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.