@agent-native/core 0.63.0 → 0.63.1

package/docs/content/actions.md

@@ -19,6 +19,10 @@ One definition, seven consumers. This is rung 3 of the [ladder](/docs/what-is-ag
 If you are deciding whether to expose an operation headlessly, in chat, in an
 embedded sidecar, or as a full app screen, see [Agent Surfaces](/docs/agent-surfaces).
 
+If the UI and agent both need to do something, reach for an action — not a custom
+route. For when a route-shaped protocol _is_ the right call, see [Prefer Actions
+For App Operations](/docs/server#actions-first).
+
 ## Start with one action {#hello-action}
 
 The primitive-first on-ramp is one action, not a template. In a headless
@@ -154,9 +158,22 @@ Every action the agent can see is a tool in the model's context window, and a lo
 
 A repo-level advisory helper, `node scripts/audit-template-actions.mjs [template ...]` (alias `pnpm actions:audit`), statically scans a template's `actions/` and flags likely UI-dead actions and redundant per-field clusters. It is advisory only (always exits 0, never fails CI) and uses conservative heuristics, so review its suggestions rather than treating them as errors.
 
-### Agent tool exposure {#agent-tool}
+### Exposure flags {#exposure-flags}
+
+Four flags control _who_ can invoke an action. All default to the permissive value, so you only set one to tighten a specific surface. This table is the glanceable summary; the subsections add the one detail each needs.
+
+| Flag            | Default       | Restrictive value → who can still call                                      | Typical use                                                     |
+| --------------- | ------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `agentTool`     | `true`        | `false` → UI, HTTP, CLI only — **hidden from the model**, MCP, and A2A      | UI-only / programmatic actions that shouldn't spend a tool slot |
+| `toolCallable`  | `true`        | `false` → everything **except** the sandboxed extension iframe bridge (403) | Auth-adjacent ops (delete account, change org membership/roles) |
+| `publicAgent`   | off (private) | `{ expose: true }` → adds the action to **public** MCP/A2A/OpenAPI surfaces | Safe read/ingest tools reachable without authentication         |
+| `needsApproval` | `false`       | `true` → the agent **pauses**; a human must approve the specific call       | Consequential side effects (send email, charge a card, delete)  |
 
-By default every action is exposed to the agent — the in-app assistant plus the app's MCP / A2A tool surfaces — as a callable tool. For an action that only the frontend (or an HTTP / cron caller) needs, set `agentTool: false` to keep it behind the framework's auth + action surface while removing it from every agent tool list:
+These are independent: `agentTool` controls the model's view, `toolCallable` controls only the extension iframe, `publicAgent` adds an opt-in public surface (public web routes never imply public tool exposure), and `needsApproval` gates execution after the call is made — see [Human-in-the-loop approval](#needs-approval) below.
+
+#### `agentTool` — hide from the model {#agent-tool}
+
+By default every action is a callable agent tool. Set `agentTool: false` to keep it behind the framework's auth + action surface while removing it from every agent tool list — it stays callable from the UI (`useActionMutation` / `callAction`), CLI, and `/_agent-native/actions/<name>`:
 
 ```ts
 export default defineAction({
@@ -170,24 +187,11 @@ export default defineAction({
 });
 ```
 
-| Value       | Behavior                                                                                                                                                                                   |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `true`      | Allow (same as undefined). Useful for documenting intent.                                                                                                                                  |
-| `false`     | **Hidden from the model entirely** — not in the agent's tool list, MCP, or A2A. Still callable from the UI (`useActionMutation` / `callAction`), CLI, and `/_agent-native/actions/<name>`. |
-| `undefined` | **Default-allow.** The action is a normal agent tool.                                                                                                                                      |
-
-`agentTool: false` is **not** the same as [`toolCallable: false`](#tool-callable):
+Reach for it when you add a UI-only or purely programmatic action, or when the UI stops using an action you'd otherwise leave exposed to the model.
 
-- **`agentTool: false`** removes the action from the **model's** view. The model can no longer see or call it; the UI and HTTP can.
-- **`toolCallable: false`** only blocks the sandboxed **extension iframe bridge** (`appAction(...)`). The action stays fully visible to the model, UI, CLI, MCP, and A2A. It exists for high-blast-radius operations (account/org/auth changes), not for trimming the tool list.
+#### `toolCallable` — block the extension iframe {#tool-callable}
 
-Reach for `agentTool: false` when you find yourself adding a UI-only or purely programmatic action, or when the UI stops using an action you'd otherwise leave exposed to the model.
-
-### Extension callability {#tool-callable}
-
-Extensions (Alpine.js mini-apps that run inside sandboxed iframes — see [Extensions](/docs/extensions)) call actions via `appAction(name, params)`. Because a shared extension's HTML/JS executes inside the _viewer's_ session, an action invoked from an extension runs with the viewer's permissions, secrets, and SQL scope. For high-blast-radius operations, that is too much trust to grant by default.
-
-Use the `toolCallable` flag to control this (the flag name is kept for backward compatibility — it gates extension iframe callability):
+Extensions ([Alpine.js mini-apps in sandboxed iframes](/docs/extensions)) call actions via `appAction(name, params)`, running with the _viewer's_ permissions, secrets, and SQL scope. For high-blast-radius operations that is too much trust by default. Set `toolCallable: false` to make the extension bridge return 403 while keeping the action callable from the UI, agent, CLI, MCP, and A2A:
 
 ```ts
 export default defineAction({
@@ -200,20 +204,7 @@ export default defineAction({
 });
 ```
 
-| Value       | Behavior                                                                                                                                                                                                                                          |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `true`      | Allow (same as undefined). Useful for documentation of intent.                                                                                                                                                                                    |
-| `false`     | Explicit deny. The extension bridge returns 403; the action is still callable normally from the UI, agent, CLI, MCP, and A2A.                                                                                                                     |
-| `undefined` | **Default-allow.** Extensions are intra-org and typically authored by trusted teammates, so the default trusts the org-level access controls. Set `false` only for genuinely auth-adjacent operations (account deletion, org membership changes). |
-
-Enforcement: the parent host tags every outbound action call from an extension iframe with the header `X-Agent-Native-Tool-Bridge: 1`. The action route layer reads this header and applies the rule above. Regular UI/agent/CLI/A2A calls do not carry the header and are unaffected. The header is set by the React host; the iframe's user-authored content cannot spoof it because the bridge sanitizes iframe-supplied headers.
-
-Set `toolCallable: false` for actions that:
-
-- delete or transfer ownership of any account/org,
-- change auth state (sign-out-all sessions, rotate tokens),
-- modify org membership (invite/remove members, change roles),
-- change resource visibility or grant share access (the framework's built-in `share-resource`, `unshare-resource`, and `set-resource-visibility` are already opted out).
+Use it for actions that delete or transfer accounts/orgs, change auth state, modify org membership, or grant share access. The framework's built-in `share-resource`, `unshare-resource`, and `set-resource-visibility` are already opted out. Enforcement is by an unspoofable host-set header on iframe calls; regular UI/agent/CLI/MCP/A2A calls are unaffected — see [Security](/docs/security) for details.
 
 ### Run context (second argument) {#run-context}
 
@@ -307,10 +298,10 @@ export default defineAction({
 });
 ```
 
-`needsApproval` accepts a boolean or a predicate `(args, ctx) => boolean | Promise<boolean>` to gate conditionally (e.g. only external recipients, only above a threshold). The predicate **fails closed**: a throw is treated as "approval required". When the gate is truthy and the call isn't yet approved, the loop emits an `approval_required` event and stops the turn — the side effect never happens — and the action runs only once a human approves via the chat UI's Approve affordance.
+`needsApproval` also accepts a predicate `(args, ctx) => boolean | Promise<boolean>` to gate conditionally (e.g. only external recipients, only above a threshold); it **fails closed**, so a throw counts as "approval required". When the gate is truthy and unapproved, the loop stops the turn and the side effect never fires until a human approves in the chat UI.
 
 > [!WARNING]
-> Keep approvals rare. Each gated action is a hard stop in the agent loop. The default is **off**, and almost every action should leave it off. See [Human-in-the-Loop Approvals](/docs/human-approval) for the full flow.
+> Keep approvals rare. Each gated action is a hard stop in the agent loop. The default is **off**, and almost every action should leave it off. See [Human-in-the-Loop Approvals](/docs/human-approval) for the predicate API, the `approval_required` event, and the full flow.
 
 ## Calling it from the UI {#ui}
 
@@ -394,12 +385,11 @@ export default defineAction({
 ```
 
 The built-in discriminants are `"data-table"`, `"data-chart"`, and
-`"data-insights"`. Their server-safe builders and schemas are exported from
-`@agent-native/core/data-widgets`, and native renderer ids are exported from
-`@agent-native/core`. See [Native Chat UI](/docs/native-chat-ui) for the full
-result contract and BYO runtime guidance, or [Agent Surfaces](/docs/agent-surfaces)
-for how this same action can stay headless, render in chat, or grow into a full
-screen.
+`"data-insights"`, with server-safe builders and schemas in
+`@agent-native/core/data-widgets`. See [Native Chat UI](/docs/native-chat-ui)
+for the full result contract and BYO runtime guidance, or
+[Agent Surfaces](/docs/agent-surfaces) for how the same action can stay
+headless, render in chat, or grow into a full screen.
 
 ## Calling it from the CLI {#cli}
 
@@ -417,9 +407,9 @@ If your app is an [A2A](/docs/a2a-protocol) peer, other agent-native apps discov
 
 ## Exposing it over MCP {#mcp}
 
-With MCP enabled, your actions show up in the framework's MCP server at `/_agent-native/mcp`. Every caller gets a compact catalog by default — code/stdio developer clients, the local CLI proxy, and chat-style app hosts (OAuth MCP Apps callers and generic authenticated remote HTTP/static-token callers) alike — containing app-facing builtins (`open_app`, `list_apps`, `ask_app`, and app-only embed helpers) plus the template-declared app actions; action-specific MCP App resources stay out of that catalog unless an action explicitly sets `mcpApp.compactCatalog: true`. `tool-search` is always present (call it with no query for the full tool menu, or with a query for ranked matches), so any tool stays reachable on demand. The full action surface is served only on explicit opt-in (`--full-catalog` token or `AGENT_NATIVE_MCP_FULL_CATALOG=1`). `publicAgent.expose` is still the opt-in for safe read/ingest tools outside that compact app catalog. See [MCP Protocol](/docs/mcp-protocol).
+With MCP enabled, your actions show up in the framework's MCP server at `/_agent-native/mcp`. Every caller gets a compact catalog by default — app-facing builtins plus the template-declared app actions — and `tool-search` is always present so any other tool stays reachable on demand. The full action surface is served only on explicit opt-in (`--full-catalog` token or `AGENT_NATIVE_MCP_FULL_CATALOG=1`), and `publicAgent.expose` opts a safe read/ingest tool onto the public surface. See [MCP Protocol](/docs/mcp-protocol) for catalog tiers, auth, and the `mcpApp` resource details.
 
-For UI-capable MCP hosts, an action can also declare an optional MCP Apps resource via the `mcpApp` field (and a matching `link`) so capable hosts render the result inline. The pattern mirrors the focused link we already return for external agents: the action exposes the operation, `link` points at the route with the right URL or deep-link params, and the embed helper uses that same target as the inline app. When an action's `link` and `mcpApp` should point at the same route, use `embedRoute()` to build both from one pure path builder.
+For UI-capable MCP hosts, an action can declare an optional MCP Apps resource via the `mcpApp` field (plus a matching `link`) so capable hosts render the result inline. When `link` and `mcpApp` should point at the same route, `embedRoute()` builds both from one pure path builder:
 
 ```ts
 import { embedRoute } from "@agent-native/core";

package/docs/content/agent-surfaces.md

@@ -15,23 +15,60 @@ you want, then use the matching primitive.
 
 | Surface                       | Use it when                                                                                                 | Start with                                                                                  |
 | ----------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| **Headless agent/actions**    | Code, jobs, scripts, another app, or another agent should call the work directly.                           | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A |
+| **Headless agent**            | Code, jobs, scripts, another app, or another agent should call the work directly.                           | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A |
 | **Rich chat on Agent-Native** | You want a standalone or embedded chat backed by the built-in agent loop.                                   | [Chat template](/docs/template-chat), `<AgentChatSurface>`, `<AssistantChat>`               |
 | **Rich chat on your agent**   | You built the agent elsewhere and want Agent-Native's composer, transcript, tool cards, and native widgets. | `AgentChatRuntime`, `<AssistantChat runtime={runtime}>`                                     |
 | **Embedded sidecar**          | You already have a SaaS app and want an agent beside it with page context and host commands.                | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded`                                  |
 | **Full application**          | Humans and agents should share durable screens, data, navigation, and collaboration.                        | Templates, actions, SQL state, context awareness                                            |
 
 Those are stages, not separate products. A workflow can start as a headless
-action, appear in chat as a table or chart, and later become a full screen in an
-app without changing the operation the agent calls.
+agent with one action, appear in chat as a table or chart, and later become a
+full screen in an app without changing the operation the agent calls.
 
-## Headless agent/actions {#headless}
+## Headless agent {#headless}
 
 Use the headless path when no one needs to stare at a custom app screen while
 the work runs: scheduled jobs, integrations, backend workflows, CLI loops,
 another agent, or an existing product calling into Agent-Native.
 
-The smallest local path is a headless scaffold plus one action:
+This is also the shape to reach for when **the agent _is_ the product** — the
+app-agent loop is the front door, not a dashboard. You send a request from the
+terminal, Slack, email, a scheduled job, another agent, or Chat — "summarize my
+unread emails," "post the daily metrics to Slack," "find the candidates who
+replied last week" — and the agent acts and returns the result wherever it
+belongs. It is still a real app, not a stateless prompt: actions, auth sessions,
+app state, thread/run history, settings, credentials, and share records all live
+in SQL.
+
+Pick this pattern when:
+
+- **The work happens in the background.** Most of the value is created while the user isn't looking — triage agents, daily-report agents, on-call responders.
+- **The output leaves the app.** The agent posts to Slack, sends email, or updates a third-party system; there's nothing to browse in-app.
+- **The domain is one-shot.** Research bot, summary generator, report writer — no persistent object that needs a list view.
+- **You're prototyping.** Ship the agent now; add richer UI later if users want one.
+
+If your product is built around persistent objects users browse, pivot, and
+share — emails, events, documents, charts — pick a [full application](#full-application)
+or a [template](/docs/cloneable-saas) instead; those add a full UI _plus_ the agent.
+
+### What ships in the box {#in-the-box}
+
+A headless app skips weeks of dashboard work, and it's channel-agnostic from day
+one — the same agent runs from the web, Slack, Telegram, email, and other agents
+because everything goes through the agent, not the UI. The trade-off is there's
+no "browse-everything-at-a-glance" view; if users need that, mix patterns and
+add a small status page or list view.
+
+When you add the built-in Chat shell, the framework provides five management
+surfaces you don't have to build: **Chat** (the main input), **Workspace**
+(skills, memory, instructions, sub-agents, connected MCP servers, scheduled
+jobs), **Job history**, **Thread history**, and **Settings**. Those are usually
+enough — talk to it, see what it's done, configure how it behaves. Reach for
+[Chat](/docs/template-chat) when you're ready to add that browser UI, or the
+[Dispatch template](/docs/template-dispatch) for a workspace-style starting
+point with Slack/Telegram, scheduled jobs, and shared secrets out of the box.
+
+The smallest local path is a headless agent scaffold plus one action:
 
 ```bash
 npx @agent-native/core@latest create my-agent --headless
@@ -81,45 +118,20 @@ If another app or script needs to call the whole agent, use
 `agentNative.invoke("analytics", "...")` or the `agent-native invoke` CLI. That
 keeps cross-app work on the A2A path while local work stays on actions.
 
-Workers, jobs, integration webhooks, and custom hosts can use the server API
-directly. This is lower-level than actions: you provide the engine, model,
-messages, actions, and event sink yourself.
+Workers, jobs, integration webhooks, and custom hosts can drive the agent loop
+directly through the server API. This is lower-level than actions — you provide
+the engine, model, messages, actions, and event sink yourself:
 
 ```ts
-import {
-  actionsToEngineTools,
-  resolveEngine,
-  runAgentLoop,
-} from "@agent-native/core/server";
-
-const engine = await resolveEngine({ engineOption: undefined });
-const model = engine.defaultModel;
-const controller = new AbortController();
-
-await runAgentLoop({
-  engine,
-  model,
-  systemPrompt: "You are the reporting agent for this workspace.",
-  actions,
-  tools: actionsToEngineTools(actions),
-  messages: [
-    {
-      role: "user",
-      content: [{ type: "text", text: "Summarize this week's forms." }],
-    },
-  ],
-  send: (event) => {
-    // Persist, log, stream, or translate AgentChatEvent objects.
-  },
-  signal: controller.signal,
-  ownerEmail: user.email,
-  orgId: user.orgId,
-});
+import { runAgentLoop } from "@agent-native/core/server";
+
+await runAgentLoop({ engine, model, systemPrompt, actions, messages, send });
 ```
 
 For most apps, scheduled prompts and integration webhooks already call this loop
-for you. Reach for direct `runAgentLoop()` when you are building a custom
-headless host, eval runner, or server-side orchestration surface.
+for you. Reach for it directly only when building a custom headless host, eval
+runner, or server-side orchestration surface — see [Server — Production agent
+handler](/docs/server#agent-handler) for the full signature.
 
 ### Running against a folder {#folder-loop}
 
@@ -178,6 +190,48 @@ export default function ChatRoute() {
 }
 ```
 
+When an app has both a full-page chat tab and an `AgentSidebar`, use the same
+`storageKey` on both surfaces, enable `chatViewTransition`, and install the
+chat-home handoff helpers in the layout. Ordinary in-app links out of the chat
+page can then morph the full chat into the sidebar while keeping the active
+thread:
+
+```tsx
+import {
+  AgentChatSurface,
+  AgentSidebar,
+  useAgentChatHomeHandoff,
+  useAgentChatHomeHandoffLinks,
+} from "@agent-native/core/client/chat";
+import { useLocation } from "react-router";
+
+function ChatRoute() {
+  return (
+    <AgentChatSurface mode="page" storageKey="my-app" chatViewTransition />
+  );
+}
+
+function AppLayout({ children }: { children: React.ReactNode }) {
+  const location = useLocation();
+  const handoffActive = useAgentChatHomeHandoff({
+    storageKey: "my-app",
+    activePath: location.pathname,
+    enabled: location.pathname !== "/chat",
+  });
+  useAgentChatHomeHandoffLinks({ storageKey: "my-app", chatPath: "/chat" });
+
+  return (
+    <AgentSidebar
+      storageKey="my-app"
+      chatViewTransition
+      openOnChatRunning={handoffActive}
+    >
+      {children}
+    </AgentSidebar>
+  );
+}
+```
+
 The simplest embedded chat with your own chrome:
 
 ```tsx
@@ -195,14 +249,9 @@ components in the chat, without iframes. See [Native Chat UI](/docs/native-chat-
 ## Rich chat on your agent {#byo-agent}
 
 Use this path when your agent is already built with another framework or
-runtime and you want Agent-Native's chat UI around it.
-
-The [Chat template](/docs/template-chat) is still useful here: keep its app
-shell and thread UI, then swap the runtime behind the chat plugin or route.
-
-`AgentChatRuntime` is the boundary. Your runtime streams normalized events;
-Agent-Native renders the composer, transcript, tool calls, approvals, native
-widgets, and app layout.
+runtime and you want Agent-Native's chat UI around it. `AgentChatRuntime` is the
+boundary: your runtime streams normalized events, and Agent-Native renders the
+composer, transcript, tool calls, approvals, native widgets, and app layout.
 
 ```tsx
 import {
@@ -211,10 +260,7 @@ import {
 } from "@agent-native/core/client/chat";
 
 const runtime = createHttpAgentChatRuntime({
-  id: "external:support-agent",
-  label: "Support agent",
   endpoint: "/api/support-agent/chat",
-  headers: async () => ({ Authorization: `Bearer ${await getToken()}` }),
 });
 
 export function SupportAgentChat() {
@@ -222,40 +268,15 @@ export function SupportAgentChat() {
 }
 ```
 
-Use `createOpenAIAgentsChatRuntime()`,
-`createOpenAIResponsesChatRuntime()`, `createClaudeAgentChatRuntime()`,
-`createVercelAiChatRuntime()`, or `createAgUiChatRuntime()` when your endpoint
-already streams one of those event shapes. Use `createHttpAgentChatRuntime()`
-when your agent streams Agent-Native's normalized event shape directly:
-
-```ts
-import { createOpenAIAgentsChatRuntime } from "@agent-native/core/client/chat";
-
-const runtime = createOpenAIAgentsChatRuntime({
-  endpoint: "/api/openai-agent/chat",
-});
-```
-
-The endpoint can stream SSE or NDJSON events:
-
-```txt
-data: {"type":"message-delta","messageId":"m1","delta":{"type":"text","text":"I found 34 submissions."}}
-data: {"type":"tool-start","toolCall":{"id":"t1","name":"query","input":{"formId":"form_123"}}}
-data: {"type":"tool-done","toolCallId":"t1","toolName":"query","status":"completed","resultText":"34 rows"}
-data: {"type":"done","reason":"complete"}
-```
-
-For a trivial integration, returning `{ "text": "..." }` also works. For richer
-integrations, stream `message-*`, `tool-*`, `approval-request`, `status`,
-`artifact`, `file`, `usage`, `error`, and `done` events. Tool results can carry
-`chatUI` metadata so the same native table/chart/card renderers work with your
-agent too.
+Ready-made runtime helpers exist for OpenAI Agents, OpenAI Responses, the Claude
+Agent SDK, the Vercel AI SDK, and AG-UI, plus the normalized HTTP runtime above
+for any other agent (Mastra, Flue, Eve, LangGraph, or a custom service). ACP is
+not the default end-user app chat protocol, and Agent-Native does not currently
+claim A2UI support.
 
-This is the right place to adapt the OpenAI Agents SDK, Claude Agent SDK, Vercel
-AI SDK, Mastra, Flue, Eve, LangGraph, a custom service, or an AG-UI-compatible
-event stream. Do not use ACP as the default end-user app chat protocol; ACP is
-better framed as coding-agent/editor interoperability. Agent-Native does not
-currently claim A2UI support.
+[Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes)
+is the canonical home for the event shapes, the runtime helpers, and `chatUI`
+tool-result metadata. Start there when wiring an external agent into the chat.
 
 ## Embedded sidecar {#embedded-sidecar}
 
@@ -322,7 +343,7 @@ want a complete product shape.
 
 | If you are thinking...                                          | Choose                    |
 | --------------------------------------------------------------- | ------------------------- |
-| "I just need a callable tool or workflow."                      | Headless action           |
+| "I just need a callable tool or workflow."                      | Headless agent            |
 | "I want the framework's agent, but chat should be the main UI." | Rich chat on Agent-Native |
 | "I already have an agent; I need a polished chat UI for it."    | Rich chat on your agent   |
 | "I already have a SaaS app; add an agent beside it."            | Embedded sidecar          |

package/docs/content/agent-teams.md

@@ -127,19 +127,7 @@ interface AgentTask {
 
 ## Custom agent profiles {#profiles}
 
-A custom agent is a Markdown file in the workspace. Minimal example:
-
-```markdown
----
-name: Code Review
-description: Reviews TypeScript PRs for correctness and type safety.
-model: inherit
----
-
-You are a meticulous code reviewer. Be terse and concrete — cite file:line wherever you can.
-```
-
-Store at `agents/code-review.md` in the workspace. It appears in the `@mention` dropdown and is available to the main agent as a delegation target. See [Workspace — Custom Agents](/docs/workspace#custom-agents) for the full format including `tools`, `delegate-default`, and model overrides.
+Sub-agents map to custom agent profiles — Markdown files at `agents/<slug>.md` in the workspace that appear in the `@mention` dropdown and serve as delegation targets. [Workspace — Custom Agents](/docs/workspace#custom-agents) owns the full format (frontmatter, `tools`, `delegate-default`, model overrides).
 
 ## Delegation depth guard {#depth-guard}
 
@@ -147,7 +135,7 @@ Sub-agents can spawn sub-agents, which is a runaway/cost risk: an unbounded chai
 
 The top-level chat is depth `0`. A sub-agent it spawns is depth `1`; that sub-agent may spawn once more (depth `2`); a spawn that would create a depth-`3` sub-agent is **refused**. The default cap is **2**.
 
-```txt
+```text
 depth 0  top-level chat        (may spawn)
 depth 1  sub-agent             (may spawn)
 depth 2  sub-agent's sub-agent (at the cap — may NOT spawn)

package/docs/content/agent-web-surfaces.md

@@ -1,11 +1,11 @@
 ---
-title: "Agent Web Surfaces"
-description: "Make public routes crawlable, readable, citable, and optionally callable by agents."
+title: "Public Agent Web"
+description: "Make public routes crawlable, readable, citable, and optionally callable by agents — robots.txt, llms.txt, markdown mirrors, JSON-LD, and a public MCP surface."
 ---
 
-# Agent Web Surfaces
+# Public Agent Web
 
-Agent Web surfaces make public Agent-Native routes easy for agents to crawl, read, cite, and call. The goal is not to make every app endpoint public. The goal is to publish a clean public surface for pages that are already public, while keeping private data and tool access behind explicit controls.
+The public agent web makes public Agent-Native routes easy for agents to crawl, read, cite, and call. The goal is not to make every app endpoint public. The goal is to publish a clean public surface for pages that are already public, while keeping private data and tool access behind explicit controls.
 
 The docs site is the reference implementation. Today it ships:
 

package/docs/content/authentication.md

@@ -9,13 +9,25 @@ Agent-native apps use [Better Auth](https://better-auth.com) for authentication
 
 ## Overview {#overview}
 
-Auth is configured automatically via `autoMountAuth(app)` in the auth server plugin. The behavior depends on your environment:
+Auth is configured automatically via `autoMountAuth(app)` in the auth server plugin. There are three modes:
 
 - **Default:** Better Auth with email/password + social providers. Onboarding page shown on first visit.
 - **Remote MCP OAuth:** Standard OAuth 2.1 for MCP hosts such as Claude Code and ChatGPT connectors.
 - **Custom:** Bring your own auth via `getSession` callback.
 
-Local development uses the same Better Auth flow as production — there is no dev auth bypass, and `getSession()` never falls back to a `local@localhost` sentinel. The first time you load a template the framework auto-creates a throwaway dev account and signs you in, so you are not stuck at a login wall (disable with `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1` to use the normal signup page). Set `AUTH_DISABLED=true` (or `AUTH_DISABLED=1`) to skip login/signup entirely and run every request as a shared user — for local dev, cloud previews, and internal demos only, not production with real users. `AUTH_MODE=local` only affects CLI/agent identity resolution (which signed-in dev user `pnpm action` runs as) — it is not a browser login bypass. Email verification is skipped by default in development (and when no email provider is configured), so signup is just an email + password.
+The browser flow is the same Better Auth flow everywhere — there is **no dev auth bypass**, and `getSession()` never falls back to a `local@localhost` sentinel. What changes between environments is signup friction, not the login wall:
+
+| Environment      | First-load behavior                                                           | Email verification                              |
+| ---------------- | ----------------------------------------------------------------------------- | ----------------------------------------------- |
+| **Local dev**    | Auto-creates a throwaway dev account and signs you in (no login wall)         | Skipped by default (and when no email provider) |
+| **QA / preview** | Normal signup, but verification can be skipped so testers don't wait on email | Skip with `AUTH_SKIP_EMAIL_VERIFICATION=1`      |
+| **Production**   | Normal Better Auth signup/login                                               | Required (when an email provider is configured) |
+
+A few flags tune this; full details are in the [Environment Variables](#environment-variables) table:
+
+- `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1` — use the normal signup page in local dev instead of the auto dev account.
+- `AUTH_DISABLED=true` — skip login/signup entirely and run every request as one shared user (local dev / previews / demos only, never production with real users).
+- `AUTH_MODE=local` — affects only CLI/agent identity (which dev user `pnpm action` runs as); it is **not** a browser login bypass.
 
 ## Better Auth (Default) {#better-auth}
 
@@ -36,24 +48,23 @@ Better Auth routes are mounted at `/_agent-native/auth/ba/*`. The framework also
 
 ## Cookie Realms {#cookie-realms}
 
-Standalone apps keep their framework session cookie isolated by app when an
-app slug is available (`APP_NAME`, or the package name in local dev). Better
-Auth keeps its production standalone cookie prefix stable as `an` so existing
-sessions are not renamed casually.
-
-Workspace mode (`AGENT_NATIVE_WORKSPACE=1`) uses one shared session realm
-because workspace apps share an origin and database. Custom same-database
-subdomain deployments can opt into shared cookies with `COOKIE_DOMAIN`.
-
-First-party hosted apps at `*.agent-native.com` are different: each app has its
-own auth database, so `COOKIE_DOMAIN=.agent-native.com` is ignored by default
-and the app uses an isolated cookie namespace instead. Cross-app sign-in for
-those apps should go through [Cross-App SSO](/docs/cross-app-sso). First-party
-deploys must provide `APP_NAME` or a derivable app URL (`APP_URL`, `URL`,
-`DEPLOY_PRIME_URL`, or `DEPLOY_URL`); otherwise startup fails instead of
-falling back to the shared `an_session` name. If a first-party deployment
-intentionally shares one auth database across subdomains, set
-`AGENT_NATIVE_SHARE_COOKIE_DOMAIN=1` alongside `COOKIE_DOMAIN`.
+The session cookie's realm follows the deployment shape, so apps that share a
+database/origin share sign-in and apps that don't stay isolated:
+
+| Deployment shape                            | Cookie realm                                                                                                         |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| Standalone app                              | Isolated per app by slug (`APP_NAME`, or package name in local dev); stable `an` prefix in production                |
+| Workspace mode (`AGENT_NATIVE_WORKSPACE=1`) | One shared realm — workspace apps share an origin and database                                                       |
+| Custom same-database subdomains             | Opt into shared cookies with `COOKIE_DOMAIN`                                                                         |
+| First-party hosted (`*.agent-native.com`)   | Isolated namespace per app (each has its own auth database); `COOKIE_DOMAIN=.agent-native.com` is ignored by default |
+
+First-party hosted apps each have their own auth database, so cross-app sign-in
+goes through [Cross-App SSO](/docs/cross-app-sso) rather than a shared cookie.
+These deploys must provide `APP_NAME` or a derivable app URL (`APP_URL`, `URL`,
+`DEPLOY_PRIME_URL`, or `DEPLOY_URL`); otherwise startup fails instead of falling
+back to the shared `an_session` name. To intentionally share one auth database
+across subdomains, set `AGENT_NATIVE_SHARE_COOKIE_DOMAIN=1` alongside
+`COOKIE_DOMAIN`.
 
 ## QA Accounts {#qa-accounts}
 
@@ -136,7 +147,7 @@ Access tokens are signed with `A2A_SECRET` when set, otherwise `BETTER_AUTH_SECR
 
 Pass a custom `getSession` callback to use any auth provider (Clerk, Auth0, Firebase, etc.):
 
-```typescript
+```ts
 // server/plugins/auth.ts
 import { createAuthPlugin } from "@agent-native/core/server";
 
@@ -191,7 +202,7 @@ unless the app explicitly adds those prefixes to
 
 The session object returned by `getSession(event)` has this shape:
 
-```typescript
+```ts
 interface AuthSession {
   email: string; // User's email (primary identifier)
   userId?: string; // Better Auth user ID
@@ -205,7 +216,7 @@ interface AuthSession {
 
 On the client, use the `useSession()` hook:
 
-```typescript
+```ts
 import { useSession } from "@agent-native/core/client";
 
 function MyComponent() {
@@ -253,7 +264,7 @@ Both flows (the explicit `/_agent-native/sign-in` entrypoint and the bookmarked-
 
 If your template wraps `/_agent-native/google/auth-url` directly (e.g. mail and calendar templates do, to widen scopes), accept a `?return=<path>` query and forward it via the options-object form of `encodeOAuthState`:
 
-```typescript
+```ts
 const returnUrl = getQuery(event).return;
 const state = encodeOAuthState({
   redirectUri,
@@ -272,6 +283,11 @@ The default `/_agent-native/google/auth-url` route does this automatically — o
 | `AUTH_SKIP_EMAIL_VERIFICATION`          | Set to `1` in QA/preview environments to let email/password signups proceed without verification; local dev/test skips by default            |
 | `AUTH_DISABLED`                         | Set to `true` or `1` to skip login/signup; all requests run as one shared user (local dev/preview only — not for production with real users) |
 | `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT` | Set to `1` to disable localhost auto-sign-in on a fresh dev database                                                                         |
+| `AUTH_MODE`                             | `local` resolves CLI/agent identity only (which dev user `pnpm action` runs as); never a browser login bypass                                |
+| `COOKIE_DOMAIN`                         | Opt into shared session cookies across same-database subdomains (see [Cookie Realms](#cookie-realms))                                        |
+| `AGENT_NATIVE_WORKSPACE`                | `1` runs in workspace mode — one shared session realm across workspace apps                                                                  |
+| `AGENT_NATIVE_SHARE_COOKIE_DOMAIN`      | Set with `COOKIE_DOMAIN` to share one auth database across first-party subdomains                                                            |
+| `OAUTH_STATE_SECRET`                    | Dedicated HMAC key for OAuth state envelopes (see [Security — OAuth State Signing](/docs/security#oauth-state))                              |
 | `GOOGLE_CLIENT_ID`                      | Enable Google OAuth                                                                                                                          |
 | `GOOGLE_CLIENT_SECRET`                  | Google OAuth secret                                                                                                                          |
 | `GITHUB_CLIENT_ID`                      | Enable GitHub OAuth                                                                                                                          |