@agent-native/core 0.157.3 → 0.157.5

package/docs/content/actions-overview.mdx

@@ -0,0 +1,214 @@
+---
+title: "Overview"
+description: "Actions are the single source of truth for anything your app does. Define one with defineAction() and it fans out to an agent tool, UI hooks, HTTP, an MCP tool, an A2A tool, and a CLI command."
+---
+
+# Overview
+
+Actions are the single source of truth for anything your app does. Define one with `defineAction()` and drop it in `actions/`. Every surface below picks it up automatically. You write the logic once. No surface gets its own copy, and none can drift out of sync with the others.
+
+<Cards columns={2}>
+
+### :robot: [Agent Tool](/docs/agent-surfaces)
+
+The agent reads the description and schema as a callable tool. Ask for it in chat, like "reply to this ticket" or "summarize this thread."
+
+### :components: [UI Hooks](/docs/client-data)
+
+`useActionQuery()`, `useActionMutation()`, and `callAction()` call the same action from React. A click and a chat message run the exact same operation.
+
+### :server: [Framework Transport](/docs/http-api)
+
+Auto-mounted at `/_agent-native/actions/<name>` on startup. The UI hooks call this route under the hood, and an external HTTP client can call it directly too.
+
+### :plug: [MCP Tool](/docs/actions-other-surfaces#mcp)
+
+Shows up as a tool to any MCP host: Claude, Claude Desktop, Cursor, Codex. Use it when a different AI client should drive your app.
+
+### :network: [A2A Tool](/docs/actions-other-surfaces#a2a)
+
+Other agent-native apps discover and call it over A2A. Use it when a second app in your workspace needs this one to act on its behalf.
+
+### :terminal: [CLI Command](/docs/actions-other-surfaces#cli)
+
+`pnpm action <name>` runs it from a terminal. Use it for scripts, cron jobs, and quick manual tests.
+
+</Cards>
+
+Most apps build a separate API layer between the frontend and the database, one that only the browser can call. An agent that wants the same capability needs its own, separate integration, written and maintained again. Agent-native apps skip that split. The UI and the agent call the exact same action, so there is only one implementation to write, and only one place for a bug to hide.
+
+<Diagram id="doc-block-actions-overview-2" title="Traditional frontend vs. Agent Native" summary="A traditional frontend calls its own API layer, which only it can reach. In Agent Native, app/ and the agent both call the same actions, so every capability built here is agent-callable for free.">
+
+```html
+<div class="diagram-cocmp">
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Traditional</div>
+    <div class="diagram-node">app/ (React frontend)</div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>API layer</strong>
+      <small class="diagram-muted">only the frontend calls it</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Database</div>
+  </div>
+  <div class="cocmp-vs diagram-muted">vs</div>
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Agent Native</div>
+    <div class="cocmp-callers">
+      <div class="diagram-node">app/ (React frontend)</div>
+      <div class="diagram-node">Agent</div>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">Actions</span
+      ><small class="diagram-muted">equal partners, same operations</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL database</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-cocmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.cocmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 180px;
+}
+.cocmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.cocmp-callers {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+.cocmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-cocmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-self: stretch;
+  align-items: center;
+}
+.cocmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+If the UI and the agent both need to do something, reach for an action instead of a custom route. For the rare case where a route-shaped protocol is the right call, visit [Prefer Actions For App Operations](/docs/server-overview#actions-first).
+
+## Where Actions Fit {#role}
+
+`app/` (visit [Client Overview](/docs/client-overview#role)) and the agent both resolve to the same actions and the same SQL database. There is no separate "app backend" this layer talks to that the agent can't also reach. Building a feature means defining an operation here and getting a UI, an agent tool, and every other surface for it at the same time.
+
+`actions/` itself is a flat folder. Each file is one action: a `defineAction()` call exported as the file's default export. The framework scans this folder on startup and mounts every file it finds. There is no registration step and no index file to keep up to date.
+
+An action's `run()` body is regular server code, so it commonly reaches into a few other directories:
+
+<FileTree
+  id="doc-block-actions-overview-filetree"
+  entries={[
+    {
+      path: "actions/reply-to-email.ts",
+      note: "One action per file. Exports a defineAction() call, and the framework mounts it automatically.",
+    },
+    {
+      path: "server/db/schema.ts",
+      note: "Drizzle table definitions most actions read and write through.",
+    },
+    {
+      path: "server/lib/access.ts",
+      note: "Shared access guards (accessFilter, assertAccess, authorize) reused across actions.",
+    },
+    {
+      path: "shared/feature-flags.ts",
+      note: "Flag definitions an action and a server plugin both check.",
+    },
+    {
+      path: "app/components/ReplyButton.tsx",
+      note: "Calls the action from the UI with useActionMutation.",
+    },
+  ]}
+/>
+
+Nothing outside `actions/` should import an action's `run` function directly. Call it through one of the surfaces above instead: the agent tool, a UI hook, HTTP, MCP, A2A, or the CLI. Every one of those paths runs the same schema validation, access checks, and audit trail.
+
+## Start with one action {#hello-action}
+
+The first operation in a chat-first app can be tiny. In the Chat template,
+replace `actions/hello.ts` or add a new file beside it:
+
+```ts
+// actions/hello.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Say hello from the local agent.",
+  schema: z.object({
+    name: z.string().default("world"),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async ({ name }) => {
+    return { message: `Hello, ${name}!` };
+  },
+});
+```
+
+Run it from the same folder:
+
+```bash
+pnpm action hello '{"name":"Steve"}'
+```
+
+The CLI accepts a JSON object as the action input, which matches the structured
+tool calls agents already make. Simple flags still work for quick manual runs:
+
+```bash
+pnpm action hello --name Steve
+```
+
+Then run the app-agent loop against the folder:
+
+```bash
+npx agent-native agent "Call hello for Steve and explain the result"
+```
+
+That is the same app-agent loop your scheduled jobs, chat UI, external MCP
+tools, and future screens will use. Chat and domain templates are for adding UI
+around actions, not a required prerequisite for the action itself.
+
+## What's next
+
+- [**Defining Actions**](/docs/actions-defining) — `defineAction()` anatomy, schema, and HTTP config
+- [**Access & Authorization**](/docs/actions-access-control) — exposure flags, `ctx` scoping, and `authorize`
+- [**Run Context**](/docs/actions-run-context) — the full `ctx` field table
+- [**Other Surfaces**](/docs/actions-other-surfaces) — native chat UI, CLI, A2A, MCP, and standard actions
+- [**Advanced & Legacy**](/docs/actions-advanced) — feature-flag gating and legacy CLI-style actions
+- [**Overview**](/docs/client-overview) — the `app/` side of this same contract
+- [**Data & Sync**](/docs/client-data) — `useActionQuery`, `useActionMutation`, and `callAction` in the UI
+- [**Agent Surfaces**](/docs/agent-surfaces) — how one action grows from chat tool to full screen

package/docs/content/actions-run-context.mdx

@@ -0,0 +1,180 @@
+---
+title: "Run Context"
+description: "The ctx second argument passed to run(): the full ActionRunContext signature and the caller union, for tracking, automation attribution, and cross-cutting concerns."
+---
+
+# Run Context
+
+`run` receives an optional second argument, `ctx`, carrying the resolved request identity and the surface that invoked the action. Read it instead of calling `getRequestUserEmail()` / `getRequestOrgId()` by hand, and pass the whole `ctx` to tracking:
+
+```ts
+export default defineAction({
+  description: "Log an audit entry for the current request.",
+  schema: z.object({ event: z.string() }),
+  run: async (args, ctx) => {
+    // ctx is undefined-safe: a 1-arg `run(args)` is still valid.
+    const actor = ctx?.userEmail ?? "system";
+    if (ctx?.caller === "frontend") {
+      // tighter rules for browser-initiated calls, looser for "tool"/"cli"
+    }
+    await db.insert(audit).values({
+      actor,
+      orgId: ctx?.orgId ?? null,
+      source: ctx?.caller ?? "unknown",
+      event: args.event,
+    });
+    return { ok: true };
+  },
+});
+```
+
+Most actions only ever read `ctx?.userEmail` and `ctx?.orgId`, the [access-control scoping](/docs/actions-access-control#access-control) used in nearly every real action. The rest of this page covers cross-cutting concerns like tracking and automation attribution, which fewer actions need.
+
+## The `ctx` argument {#ctx}
+
+`ctx` carries two kinds of information: the resolved request identity (`userEmail`, `orgId`) that's present on nearly every call, and metadata about the surface that invoked the action (`caller`, plus surface-specific fields like `threadId` or `automation` that are only populated for certain callers). The full shape, as the second argument to `run()`:
+
+<Signature
+  id="doc-block-actions-run-context-1"
+  name="run"
+  params={[
+    {
+      name: "args",
+      type: "TInput",
+      description: "The validated input, parsed from `schema`.",
+    },
+    {
+      name: "ctx",
+      type: "ActionRunContext",
+      optional: true,
+      description:
+        "The resolved request identity and the surface that invoked the action. Undefined-safe: a 1-argument `run(args)` handler is still valid.",
+      fields: [
+        {
+          name: "userEmail",
+          type: "string",
+          optional: true,
+          description:
+            "Resolved request user. **Never defaulted to a dev identity**: `undefined` when the request has no authenticated user. Apply your own fallback if you need one.",
+        },
+        {
+          name: "orgId",
+          type: "string | null",
+          description:
+            "Resolved org id, or `null` when the request has no org.",
+        },
+        {
+          name: "caller",
+          type: "ActionCaller",
+          description:
+            "How the action was invoked. See [the caller union](#caller) below.",
+        },
+        {
+          name: "send",
+          type: "(event) => void",
+          optional: true,
+          description:
+            'Emits an SSE event to the client. Only present inside the agent tool loop (`caller: "tool"`). `undefined` elsewhere.',
+        },
+        {
+          name: "attachments",
+          type: "AgentChatAttachment[]",
+          optional: true,
+          description:
+            'Files, images, and pasted text blocks submitted with the current agent turn. Populated only when `caller: "tool"`. `undefined` on all other surfaces.',
+        },
+        {
+          name: "signal",
+          type: "AbortSignal",
+          optional: true,
+          description:
+            'Aborts when the run is soft-timed-out, cancelled, or the server shuts down. Populated only when `caller: "tool"`. Long-running actions can observe it to cancel early instead of waiting for the per-tool 60s hard timeout.',
+        },
+        {
+          name: "actionName",
+          type: "string",
+          optional: true,
+          description:
+            "The registry key of the action being called (e.g. `delete-recording`), set at each dispatch site so cross-cutting concerns like the audit log can attribute the call. `undefined` for direct programmatic `run()` calls that bypass the dispatcher.",
+        },
+        {
+          name: "threadId",
+          type: "string",
+          optional: true,
+          description:
+            'The agent conversation thread that triggered this call. Populated only when `caller: "tool"`, so the audit log can link a mutation back to the exact agent run.',
+        },
+        {
+          name: "runId",
+          type: "string",
+          optional: true,
+          description:
+            'The agent run attempt that triggered this call. Populated only when `caller: "tool"`.',
+        },
+        {
+          name: "turnId",
+          type: "string",
+          optional: true,
+          description:
+            'The specific turn within that run that triggered this call. Populated only when `caller: "tool"`.',
+        },
+        {
+          name: "automation",
+          type: "ActionAutomationContext",
+          optional: true,
+          description:
+            'Present only when `caller: "automation"`. Carries `triggerId`, `triggerName`, and an optional `policyId` for the event-triggered automation that dispatched this call.',
+        },
+        {
+          name: "networkProtocol",
+          type: '"a2a" | "mcp" | "provider-api"',
+          optional: true,
+          description:
+            "Which delegated-call protocol this request arrived over. Set only for those direct-dispatch paths.",
+        },
+        {
+          name: "networkId",
+          type: "string",
+          optional: true,
+          description:
+            "A correlation id for that delegated call, e.g. the A2A delegation JWT id.",
+        },
+        {
+          name: "networkPeer",
+          type: "string",
+          optional: true,
+          description: "The calling peer's identity for that delegated call.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<TReturn> | TReturn",
+    description:
+      "The action's result, validated against `outputSchema` if one is set.",
+  }}
+/>
+
+`run()` stays backward compatible: existing 1-argument handlers and handlers that only destructure `{ send }` continue to work unchanged.
+
+### The `caller` union {#caller}
+
+`caller` is the union `"tool" | "http" | "frontend" | "cli" | "mcp" | "a2a" | "automation"`:
+
+| `caller`       | Set when…                                                                                                                                                                                                |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"tool"`       | The in-app agent loop, a sub-agent or agent team, or natural-language cross-app A2A delegation, which drives the same agent loop, so its tool calls are `"tool"`.                                        |
+| `"frontend"`   | A browser call via `useActionMutation()`, `useActionQuery()`, or `callAction()` (tagged with the `X-Agent-Native-Frontend: 1` header).                                                                   |
+| `"http"`       | A bare programmatic `POST` or `GET` to `/_agent-native/actions/<name>` without the frontend marker.                                                                                                      |
+| `"cli"`        | `pnpm action <name>` (the CLI runner).                                                                                                                                                                   |
+| `"mcp"`        | An external agent over the MCP `tools/call` endpoint.                                                                                                                                                    |
+| `"a2a"`        | A direct HTTP call to `/_agent-native/actions/<name>` carrying a signed A2A delegation token. This is an explicitly exposed, cross-app dispatch, distinct from the natural-language `"tool"` path above. |
+| `"automation"` | An event-triggered automation dispatched from a stored workspace trigger. `ctx.automation` carries the trigger lineage. See [Automations](/docs/automations).                                            |
+
+## What's next
+
+- [**Access & Authorization**](/docs/actions-access-control) — the `ctx.userEmail`/`ctx.orgId` scoping pattern this context enables
+- [**Defining Actions**](/docs/actions-defining) — `defineAction()` anatomy and HTTP config
+- [**Other Surfaces**](/docs/actions-other-surfaces) — how CLI, A2A, MCP, and automation callers set `caller`
+- [**Audit Log**](/docs/audit-log) — how `threadId`/`runId`/`turnId` link a mutation back to its agent run
+- [**Automations**](/docs/automations) — the `ctx.automation` trigger lineage

package/docs/content/agent-surfaces.mdx

@@ -591,7 +591,7 @@ tool-result metadata. Start there when wiring an external agent into the chat.
 
 <Cards>
 
-### [Actions](/docs/actions)
+### [Actions](/docs/actions-overview)
 
 Define the operation once. Every surface above calls the same one.
 

package/docs/content/agent-teams.mdx

@@ -328,4 +328,4 @@ When a sub-agent is at or below the cap, the framework injects a line into its r
 
 - [**Agent Resources — Custom Agents**](/docs/agent-resources#custom-agents) — the profile format
 - [**A2A Protocol**](/docs/a2a-protocol) — when the "sub-agent" lives in a different app entirely
-- [**Actions**](/docs/actions) — the tools a sub-agent calls
+- [**Actions**](/docs/actions-overview) — the tools a sub-agent calls

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

@@ -212,6 +212,6 @@ The audit exits non-zero if a required public surface is missing.
 
 ## What's next
 
-- [**Actions**](/docs/actions) — how to opt actions into the public agent protocol
+- [**Actions**](/docs/actions-overview) — how to opt actions into the public agent protocol
 - [**MCP Protocol**](/docs/mcp-protocol) — the MCP surface that `publicMcp: true` enables
 - [**Deployment**](/docs/deployment) — where these static files are written during builds

package/docs/content/audit-log.mdx

@@ -182,7 +182,7 @@ Configure via environment:
 
 ## What's next
 
-- [**Actions**](/docs/actions) — the `defineAction` seam where capture happens
+- [**Actions**](/docs/actions-overview) — the `defineAction` seam where capture happens
 - [**Human-in-the-Loop Approvals**](/docs/human-approval) — gated actions, recorded as `denied`
 - [**Security & Data Scoping**](/docs/security) — the ownership model audit reads reuse
 - [**Observability**](/docs/observability) — agent-run telemetry (the other "what happened")

package/docs/content/automation-connectors.mdx

@@ -119,5 +119,5 @@ See [Zapier REST Hook triggers](https://docs.zapier.com/integrations/build/hook-
 
 - [**Automations**](/docs/automations#web-request) — the ad-hoc `web-request` tool for one-off outbound HTTP, the lighter-weight sibling to a configured connector
 - [**Messaging**](/docs/messaging) — reaching the agent from Slack, email, Telegram, and WhatsApp, the queue-and-processor pattern this page's callbacks reuse
-- [**Actions**](/docs/actions) — `defineAction`, `needsApproval`, and the action surface `createInvokeAutomationWorkflowAction` builds on
+- [**Actions**](/docs/actions-overview) — `defineAction`, `needsApproval`, and the action surface `createInvokeAutomationWorkflowAction` builds on
 - [**Security**](/docs/security) — `${keys.NAME}` secret substitution and the credential-scoping model this runtime relies on

package/docs/content/automations.mdx

@@ -450,7 +450,7 @@ for the full `plan.commented` payload reference and all four plan events.
 ## What's next
 
 - [**Recurring Jobs**](/docs/recurring-jobs) — legacy compatibility and advanced scheduled-job fields
-- [**Actions**](/docs/actions) — automations can call any registered action via the agent loop
+- [**Actions**](/docs/actions-overview) — automations can call any registered action via the agent loop
 - [**Workflow Connectors**](/docs/automation-connectors) — pre-configured n8n/Zapier-style workflow invocation, for when ad-hoc `web-request` isn't a strict enough contract
 - [**Security**](/docs/security) — input validation and secret handling
 - [**Events and Automations**](/docs/template-plan-automations) — the Plan event reference and automation recipes

package/docs/content/blueprint-installer.mdx

@@ -124,5 +124,5 @@ A new curated blueprint under an existing kind needs no code — but if you crea
 ## What's next
 
 - [**Sandbox Adapters**](/docs/sandbox-adapters) — the seam the `add sandbox docker` blueprint targets
-- [**Actions**](/docs/actions) — the single source of truth every blueprint builds on
+- [**Actions**](/docs/actions-overview) — the single source of truth every blueprint builds on
 - [**External Agents**](/docs/external-agents) — connecting the coding agent you pipe blueprints into

package/docs/content/cli-adapters.mdx

@@ -169,4 +169,4 @@ CLI adapters use `node:child_process`, which does not exist on edge/worker runti
 ## What's next
 
 - [**Adapters**](/docs/sandbox-adapters) — the canonical guide to both adapter seams.
-- [**Actions**](/docs/actions) — the action surface CLI adapters are usually wrapped in.
+- [**Actions**](/docs/actions-overview) — the action surface CLI adapters are usually wrapped in.

package/docs/content/client-agent-chat.mdx

@@ -37,7 +37,7 @@ The user experience is as follows:
 
 1. The user picks **Offer a refund**, which causes `sendDraftRequest()` to send the prompt and ticket context to the agent.
 
-1. The agent calls the `draft-ticket-reply` [action](/docs/actions), and the drafted reply appears in the reply composer.
+1. The agent calls the `draft-ticket-reply` [action](/docs/actions-overview), and the drafted reply appears in the reply composer.
 
 ## askUserQuestion(opts) {#ask-user-question}
 

package/docs/content/client-data.mdx

@@ -5,7 +5,7 @@ description: "The action hooks app/ uses to read, write, and stay live-synced wi
 
 # Data & Sync
 
-The primary way to read and write app data from client application is through [action](/docs/actions) hooks. By embedding requests into actions, both your client and agent can interact with your application in the same way.
+The primary way to read and write app data from client application is through [action](/docs/actions-overview) hooks. By embedding requests into actions, both your client and agent can interact with your application in the same way.
 
 In the example below, a ticket is assigned to the current user manually through a dropdown, and then through the chat agent. Both the UI and agent access the same action.
 
@@ -426,7 +426,7 @@ For normal CRUD, prefer `useActionQuery()` and `useActionMutation()`. Mutating a
 
 - [**Overview**](/docs/client-overview) — the `app/` and `public/` directory layout this page's hooks live in
 - [**Agent Chat**](/docs/client-agent-chat) — sending prompts and staging context for the agent
-- [**Actions**](/docs/actions) — the `defineAction` surface behind every hook on this page
+- [**Actions**](/docs/actions-overview) — the `defineAction` surface behind every hook on this page
 - [**Advanced**](/docs/client-advanced) — direct `application_state` access
 - [**Sync Internals**](/docs/client-sync-internals) — syncing a raw `useQuery` with `useChangeVersion`
 - [**Real-Time Sync**](/docs/key-concepts#polling-sync) — how `useDbSync` keeps the UI current

package/docs/content/client-overview.mdx

@@ -92,7 +92,7 @@ The one architectural difference from a typical frontend: this layer has no back
 
 ## Where the Client Fits {#role}
 
-Browser requests, the agent loop, and external API clients all resolve to the same actions and the same SQL database — there is no separate "app backend" this layer talks to that the agent can't also reach. Building a feature here means building a UI on top of an operation the agent already has, or defining a new action and getting a UI for it at the same time. See [Actions](/docs/actions) for the operation side of that contract.
+Browser requests, the agent loop, and external API clients all resolve to the same actions and the same SQL database — there is no separate "app backend" this layer talks to that the agent can't also reach. Building a feature here means building a UI on top of an operation the agent already has, or defining a new action and getting a UI for it at the same time. See [Actions](/docs/actions-overview) for the operation side of that contract.
 
 This page covers the directories you build in and the pieces of the browser runtime nothing else documents (`root.tsx`, `public/`). The React hooks that connect your components to actions and to the agent live on their own focused pages:
 
@@ -201,6 +201,6 @@ import { cn } from "@agent-native/toolkit/utils";
 - [**Sync Internals**](/docs/client-sync-internals) — `useChangeVersion` for syncing a raw `useQuery`
 - [**Entry Points**](/docs/client-entry-points) — SSR bootstrap customization
 - [**Routing**](/docs/client-routing) — file-based pages, dynamic params, and navigation
-- [**Actions**](/docs/actions) — the `defineAction` surface behind every data hook
+- [**Actions**](/docs/actions-overview) — the `defineAction` surface behind every data hook
 - [**Custom Design Systems**](/docs/custom-design-system) — swapping in your own component library via `app/design-system.ts`
 - [**Authentication**](/docs/authentication) — the session checks `AppProviders` runs on private paths

package/docs/content/components.mdx

@@ -526,7 +526,7 @@ reasoning.
 
 - [**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
+- [**Actions**](/docs/actions-overview) — `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
 - [**Toolkit piece: Toolkit UI Primitives**](/docs/toolkit-ui) — the shared shadcn-style building blocks and app-adapter pattern behind these exports

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

@@ -1,6 +1,6 @@
 ---
 title: "Cross-App SSO"
-description: "Sign in once across every hosted agent-native app via identity federation with Dispatch as the identity authority — opt-in per app, reversible with a single env var."
+description: "Sign in once across every hosted agent-native app via identity federation with Dispatch as the identity authority. Canonical hosted clients are enabled by exact origin; self-hosted apps opt in with one env var."
 ---
 
 # Cross-App SSO
@@ -233,16 +233,20 @@ trust boundary.
 
 5. **App mints a normal local session.** From here on the user has an ordinary local session in that app's own store — every existing access check, org scoping, and action guard works exactly as before. The federation only happened at the front door.
 
-### Opting in {#opt-in}
+### Hosted and self-hosted behavior {#opt-in}
 
-An app's ordinary web sign-in participates **only** when this environment variable is set on its deployment:
+Canonical hosted client apps use Dispatch automatically when their deployment has
+one of the exact registered `*.agent-native.com` origins. Dispatch is the
+identity authority, not a client, so it never federates to itself. Self-hosted
+apps remain opt-in and must set this environment variable on their deployment:
 
 ```bash
 AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
 ```
 
-- **Set** → the app shows a **"Sign in with Agent-Native"** option that runs the flow above. Direct local login (email/password, Google) still works alongside it.
-- **Unset (default)** → **zero behavior change.** The app authenticates exactly as it did before; the federation code path is dormant. There is no schema change and nothing to migrate, so flipping the variable on or off is fully reversible at any time.
+- **Canonical hosted client** → the app shows a **"Sign in with Agent-Native"** option that runs the flow above. Direct local login (email/password, Google) still works alongside it.
+- **Self-hosted with the variable set** → the app shows the same option, using the configured Dispatch instance.
+- **Self-hosted with the variable unset** → **zero behavior change.** The app authenticates exactly as it did before; the federation code path is dormant. There is no schema change and nothing to migrate.
 
 ## Security {#security}
 
@@ -262,7 +266,7 @@ The whole model rests on a few deliberately small guarantees:
   accept a user id, role, org membership, or any privileged state from the
   wire — it derives everything locally from the matched account.
 - **Additive-only identity writes.** Linking either reuses an existing same-email account untouched or inserts a new one. No update, rename, repoint, or delete of identity rows ever happens on this path.
-- **Off by default.** With `AGENT_NATIVE_IDENTITY_HUB_URL` unset, ordinary browser federation is inert. The separately gated packaged Desktop path is described below.
+- **Exact-origin trust.** Only the registered canonical hosted client origins get the implicit hosted default. Self-hosted and custom origins remain opt-in through `AGENT_NATIVE_IDENTITY_HUB_URL`; the separately gated packaged Desktop path is described below.
 
 <Callout id="doc-block-18qhl3m" tone="success">
 
@@ -345,8 +349,8 @@ flag controls whether Desktop may begin the ceremony; it does not authorize a
 user or weaken nonce, signature, origin, callback, app-binding, cookie,
 revocation, or credential-custody checks. With the flag Off or unavailable,
 Desktop leaves ordinary per-app sign-in, sign-out, and Settings unchanged.
-Canonical hosted apps recognize the packaged Desktop request without requiring
-`AGENT_NATIVE_IDENTITY_HUB_URL` on every deployment; ordinary web browsers and
+Canonical hosted apps recognize the packaged Desktop request and ordinary web
+browsers without requiring `AGENT_NATIVE_IDENTITY_HUB_URL` on every deployment;
 self-hosted apps still require that explicit configuration.
 Stable Desktop builds do not initialize the broker until a later release is
 separately approved.
@@ -379,19 +383,22 @@ Without an exact custom registry entry, a self-hosted Dispatch can only issue co
 
 ## Canary rollout runbook {#canary-rollout}
 
-Cutover and rollback are **a single environment variable per app deployment**. Roll out one app at a time, verify, then expand. Do not set the variable on every app at once.
+Canonical hosted clients take the default after the release ships. Self-hosted
+and custom deployments still use **a single environment variable per app**.
+Roll out one deployment at a time, verify, then expand.
 
-**1. Deploy the code — no behavior change.**
-Ship the release to every app with `AGENT_NATIVE_IDENTITY_HUB_URL` **unset everywhere**. Confirm normal logins still work on a couple of apps.
+**1. Deploy the code and verify a canonical hosted client.**
+Ship the release to the canonical apps. Confirm normal logins still work on a
+couple of apps and that the new sign-in option appears on a client app.
 
-**2. Enable the canary on ONE app at a time.**
+**2. Enable self-hosted/custom apps one at a time.**
 Set, on one deployment only:
 
 ```bash
 AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
 ```
 
-Leave every other app's environment unset. Redeploy/restart so it picks up the variable.
+Leave every other self-hosted app's environment unset. Redeploy/restart so it picks up the variable.
 
 **3. Verify the canary (checklist).**
 
@@ -402,13 +409,13 @@ Leave every other app's environment unset. Redeploy/restart so it picks up the v
 - **App data is intact** — your existing records, settings, and org scoping are exactly as they were.
 - **Existing direct logins still work** — email/password and Google sign-in continue to function alongside SSO.
 
-If any check fails, go straight to step 4 (rollback) — it is instant and data-safe.
+If any check fails, go straight to step 5 (rollback) — it is instant and data-safe.
 
 **4. Expand app-by-app.**
-Once one app is verified, repeat steps 2–3 for the next app — setting `AGENT_NATIVE_IDENTITY_HUB_URL` on one deployment at a time. Never batch-enable.
+Once one deployment is verified, repeat steps 2–3 for the next one. Never batch-enable custom origins.
 
-**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.
+**5. Rollback.**
+For a self-hosted app, **remove `AGENT_NATIVE_IDENTITY_HUB_URL` from its environment and redeploy/restart it.** A canonical hosted client can be rolled back by reverting the release or disabling the hosted client path. There is **no data change to undo** — identity rows were only ever added. Each deployment's cutover and rollback are independent and reversible.
 
 <Callout tone="info">
 

package/docs/content/data-programs.mdx

@@ -14,7 +14,7 @@ search: "data program emit rows schema providerFetch dashboard panel program sou
 
 A **data program** is a named, stored, agent-authored JS script that fetches, joins, filters, or aggregates data — provider APIs via `providerFetch` / `providerFetchAll` / `providerSearchAll`, app data via `appAction`, or Resources-backed workspace files — and calls `emit(rows, schema)` exactly once with the result. The result is cached in SQL and any chart/table component can render it, refreshed on a policy you choose instead of on every page view.
 
-It ships automatically wherever [`run-code`](/docs/actions) is available — there is nothing to mount or configure per app. If your app already has run-code enabled, `save-data-program`, `preview-data-program`, `run-data-program`, `list-data-programs`, `get-data-program`, and `delete-data-program` are already registered actions.
+It ships automatically wherever [`run-code`](/docs/actions-overview) is available — there is nothing to mount or configure per app. If your app already has run-code enabled, `save-data-program`, `preview-data-program`, `run-data-program`, `list-data-programs`, `get-data-program`, and `delete-data-program` are already registered actions.
 
 <Diagram id="doc-block-dp-overview" title="From ad-hoc query to live panel" summary="A run-code script becomes a stored program once it calls emit(); any dashboard panel can bind to it and the cache/refresh policy takes over from there.">
 
@@ -330,6 +330,6 @@ Any app can implement the same adoption for its own dashboards/tables: call `run
 ## 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.
+- [Actions](/docs/actions-overview) — the `run-code` conventions and sandbox globals (`providerFetch`, `appAction`, etc.) data programs are built on.
 - [Sharing & Privacy](/docs/sharing) — the org-internal, never-public sharing model data programs use.
 - [Security](/docs/security) — the framework's credential-handling and access-scoping invariants.