@agent-native/core 0.93.0 → 0.94.1

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

@@ -197,7 +197,7 @@ When building templates that interact with external services (like Slack, Google
 
 You can check connection readiness in your `isComplete` callback using the connection catalog APIs:
 
-```ts
+```ts filename="server/plugins/my-onboarding.ts"
 import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core/workspace-connections";
 
 // Inside registerOnboardingStep:
@@ -253,7 +253,7 @@ defaults load.
 
 The panel is already inside `<AgentPanel>`. To build a custom layout:
 
-```tsx
+```tsx filename="app/components/MySidebar.tsx"
 import {
   OnboardingPanel,
   OnboardingBanner,
@@ -276,3 +276,10 @@ For background on where step values are stored and how secrets are handled,
 see [Security](/docs/security). For end-user messaging touchpoints (invitations,
 password resets) that depend on the **Email delivery** step, see
 [Messaging](/docs/messaging).
+
+## What's next {#whats-next}
+
+- [**Security**](/docs/security) — where onboarding secrets and step values are stored
+- [**Authentication**](/docs/authentication) — sign-in setup for the Authentication step
+- [**Workspace Connections**](/docs/workspace-connections) — the connection catalog APIs used by `isComplete` checks
+- [**Messaging**](/docs/messaging) — email delivery setup that the Email delivery step unlocks

package/corpus/core/docs/content/plan-plugin.mdx

@@ -253,7 +253,11 @@ codex mcp login plan   # OAuth in the browser
 
 After install, **start a new Codex thread** so the skills and MCP tools load into the session. The plugin ships a URL-only connector (`[mcp_servers.plan]` → `https://plan.agent-native.com/_agent-native/mcp`); `codex mcp login plan` runs the OAuth flow. The universal CLI route above also works for Codex (`npx @agent-native/core@latest skills add visual-plan --client codex`) if you prefer one command that installs and authenticates together, or when you want local-files or self-hosted mode.
 
-> **Older installs:** if your config still has an `agent-native-plans` entry pointing at the same URL, running `npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex` for Codex, or the same command with your target `--client`, consolidates it to the canonical `plan` name.
+<Callout tone="info">
+
+**Older installs:** if your config still has an `agent-native-plans` entry pointing at the same URL, running `npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex` for Codex, or the same command with your target `--client`, consolidates it to the canonical `plan` name.
+
+</Callout>
 
 ## Updates {#updates}
 
@@ -265,7 +269,11 @@ The plugin routes auto-update — you do not re-pack or re-add the marketplace f
 
 The connector points at a **hosted** app, so the Plan app's actions and live tool surface always reflect the deployed version regardless of when you installed; only the bundled skill instructions follow the update mechanisms above.
 
-> **Maintainers:** the marketplace bundle (`.claude-plugin/`, `.agents/plugins/`) is generated from the canonical plan skills by `pnpm sync:plan-marketplace` and verified in CI by `pnpm guard:plan-marketplace`, so the published marketplace always matches the canonical skills. Edit the skill, run `pnpm sync:plan-marketplace`, and commit.
+<Callout tone="info">
+
+**Maintainers:** the marketplace bundle (`.claude-plugin/`, `.agents/plugins/`) is generated from the canonical plan skills by `pnpm sync:plan-marketplace` and verified in CI by `pnpm guard:plan-marketplace`, so the published marketplace always matches the canonical skills. Edit the skill, run `pnpm sync:plan-marketplace`, and commit.
+
+</Callout>
 
 ## Do you need to submit anything? {#submission}
 

package/corpus/core/docs/content/pr-visual-recap.mdx

@@ -495,7 +495,7 @@ The `cli-version` input controls which `@agent-native/core` CLI version runs ins
 
 Do not trigger the caller on `workflow_dispatch` or `push` — those events do not carry a `pull_request` payload, and the gate will skip the recap with "no pull_request payload".
 
-## Related
+## What's next
 
 - [Visual Plans](/docs/template-plan) — the `/visual-plan` and `/visual-recap` skills, the hosted Plans connector, and the interactive review surface this action publishes to.
 - [Skills](/docs/skills-guide) — installing agent-native skills into your coding agent.

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

@@ -51,8 +51,11 @@ A `Processor` is a loop-internal **observer/guardrail** for the agent run. It wa
 
 </Diagram>
 
-> [!WARNING]
-> A processor is **configuration**, not a tool, not an action, and not an authoring DSL. Processors only observe, mutate their own stream-scoped state, and `abort()`. They never define app behavior, replace actions, or appear to the model. App operations belong in [actions](/docs/actions).
+<Callout id="doc-block-proc1cfg" tone="warning">
+
+A processor is **configuration**, not a tool, not an action, and not an authoring DSL. Processors only observe, mutate their own stream-scoped state, and `abort()`. They never define app behavior, replace actions, or appear to the model. App operations belong in [actions](/docs/actions).
+
+</Callout>
 
 ## The hooks {#hooks}
 
@@ -133,10 +136,13 @@ await runAgentLoop({
 
 **Zero-overhead when unused.** The loop builds the processor chain only when at least one processor is supplied; when `processors` is omitted or empty, none of the seam code runs and the loop is byte-for-byte unchanged. Hooks run in registration order and may be sync or async.
 
-> [!NOTE]
-> The loop-level seam is the deliverable today and is callable directly by sub-agents, A2A, MCP, and tests. Threading `processors` through the HTTP chat handler (so a per-request resolver can configure them without calling `runAgentLoop` directly) is convenience plumbing that is not yet wired — configure processors at the `runAgentLoop` call site for now.
+<Callout id="doc-block-proc1note" tone="info">
+
+The loop-level seam is the deliverable today and is callable directly by sub-agents, A2A, MCP, and tests. Threading `processors` through the HTTP chat handler (so a per-request resolver can configure them without calling `runAgentLoop` directly) is convenience plumbing that is not yet wired — configure processors at the `runAgentLoop` call site for now.
+
+</Callout>
 
-## Related
+## What's next
 
 - [**Durable Resume**](/docs/durable-resume) — how the loop survives interruptions without re-running completed side effects.
 - [**Custom Agents & Teams**](/docs/agent-teams) — sub-agents run the same loop and can carry their own processors.

package/corpus/core/docs/content/pure-agent-apps.mdx

@@ -10,6 +10,10 @@ and durable app pages. Use this pattern when the primary surface is not a
 browser UI yet: scheduled reports, queues, integration workers, CLI loops, or
 another app or agent calling this app over MCP/A2A.
 
+Building something people browse, compare, edit, or share in a full app? See
+[Templates](/docs/cloneable-saas) instead — this page covers the complementary
+archetype, where the work runs without a persistent screen.
+
 Automation-first does **not** mean stateless. The app-agent loop still uses the
 same Agent-Native contract: actions, sessions, app state, history, settings,
 credentials, and share records live in SQL.
@@ -113,7 +117,7 @@ Choose chat when people need conversational steering, approvals, or durable
 thread history; add app pages when they need to browse, compare, edit, or share
 persistent objects.
 
-## What to add next {#whats-next}
+## What's next {#whats-next}
 
 - [**Getting Started**](/docs/getting-started) — the chat-first tutorial from action to inline result to durable page
 - [**Agent Surfaces — Automation-first app**](/docs/agent-surfaces#headless) — the full decision guide and APIs

package/corpus/core/docs/content/real-time-collaboration.mdx

@@ -15,11 +15,10 @@ agent-native collaboration model.
 ## Vision {#vision}
 
 Editing alongside the agent feels like working in a collaborative editor with
-a coworker who is both instant and tireless:
-
-If you just need the UI to refresh when the agent or another user writes to SQL, you don't need any of this — use [`useDbSync`](/docs/client). This page is for character-level co-editing of a single rich-text document (shared cursors, conflict-free merging). Both ride the same `/_agent-native/poll` channel.
-
-This is built on three battle-tested technologies: **Yjs** (CRDT for conflict-free merging), **TipTap** (rich text editor), and **polling-based sync** (works in all deployment environments including serverless and edge).
+a coworker who is both instant and tireless. This is built on three
+battle-tested technologies: **Yjs** (CRDT for conflict-free merging),
+**TipTap** (rich text editor), and **polling-based sync** (works in all
+deployment environments including serverless and edge).
 
 - **CRDT merging** — Concurrent edits from humans and agents merge without
   conflicts. You type in one paragraph; the agent rewrites another; both
@@ -32,6 +31,12 @@ This is built on three battle-tested technologies: **Yjs** (CRDT for conflict-fr
 - **Works everywhere** — Any SQL database Drizzle supports (SQLite, Postgres).
   Any hosting target Nitro supports, including serverless and edge.
 
+<Callout tone="info">
+
+**Just need the UI to refresh, not character-level co-editing?** Use [`useDbSync`](/docs/client#usedbsync) instead — it's for reacting to SQL writes from the agent or other users. This page covers real-time character-level co-editing of a single rich-text document (shared cursors, conflict-free merging). Both ride the same `/_agent-native/poll` channel.
+
+</Callout>
+
 ## Architecture {#architecture}
 
 The collaboration system has five interlocking layers.
@@ -126,21 +131,18 @@ Collab update events travel via two paths:
 
 - **SSE fast-path** — The client subscribes to `/_agent-native/poll-events`
   (the same `EventSource` used by `useDbSync`). Collab update events arrive
-  push-style, typically in tens of milliseconds. While SSE is healthy the
-  poll loop relaxes to a slow cadence (~12 s by default).
-- **Polling fallback** — `/_agent-native/poll?since=N` is polled every 2 s
-  when SSE is unavailable. This makes collaboration work on any deployment
-  target — including serverless functions where persistent connections are
-  impossible and different invocations can handle different requests.
-
-Local Yjs updates are debounced and coalesced with `Y.mergeUpdates` (~80 ms)
-before being sent to the server, reducing keystroke-level network traffic.
-The batch is flushed immediately on `visibilitychange` or `pagehide`. A
-state-vector diff (`GET /:docId/state?stateVector=…`) is fetched only on
-reconnect, ring-buffer overflow, or every 15th poll cycle — not on every
-cycle.
-
-Network errors use exponential backoff with jitter, capped at ~15 s.
+  push-style, and the poll loop relaxes to a slow cadence while SSE is healthy.
+- **Polling fallback** — `/_agent-native/poll?since=N` is polled on a fixed
+  interval when SSE is unavailable. This makes collaboration work on any
+  deployment target — including serverless functions where persistent
+  connections are impossible and different invocations can handle different
+  requests.
+
+Local Yjs updates are debounced and coalesced with `Y.mergeUpdates` before
+being sent to the server, reducing keystroke-level network traffic, and the
+batch is flushed immediately on `visibilitychange` or `pagehide`. See
+[Transport and performance](#transport) for the exact intervals, state-vector
+refetch cadence, and backoff values.
 
 <Diagram id="doc-block-1h873p8" title="Two edit paths, one merge" summary={"Human keystrokes flow Y.Doc → server → SSE. Agent edits go through SQL: the action bumps updatedAt, the lead client reconciles, then the change re-enters Yjs."}>
 
@@ -258,7 +260,7 @@ export default createCollabPlugin({
 ### 4. Use the client hook
 
 ```ts
-import { useCollaborativeDoc } from "@agent-native/core/client";
+import { generateTabId, useCollaborativeDoc } from "@agent-native/core/client";
 import { emailToColor, emailToName } from "@agent-native/toolkit/collab-ui";
 
 const TAB_ID = generateTabId(); // or Math.random().toString(36)
@@ -316,25 +318,14 @@ User identity is derived from the session email. The framework provides `emailTo
 Templates can add a comments system with threaded discussions on documents. The content template's comments system includes a full implementation with:
 
 - `document_comments` SQL table (threads, replies, resolved status)
-- The content template's REST routes for update/delete at `/api/comments/:id`; create and list run through the `add-comment` / `list-comments` actions. Custom templates implement their own equivalent endpoints against the core `POST /_agent-native/collab/:docId/search-replace` route.
+- Comment create and list run through the `add-comment` / `list-comments` actions; the content template also exposes REST routes for update/delete at `/api/comments/:id`. Custom templates can implement their own equivalent endpoints, and comment anchors resolve against the document body through the core `POST /_agent-native/collab/:docId/search-replace` route.
 - Comments sidebar with threaded view and reply UI
 - Resolve/unresolve threads
 - **Send to AI** button — sends the comment thread context to the agent chat via `sendToAgentChat()`
 - Agent actions: `list-comments`, `add-comment`
 - Notion comment sync: `sync-notion-comments` action for bidirectional pull/push
 
-## Collab routes {#collab-routes}
-
-All collab routes are auto-mounted under `/_agent-native/collab/` by the collab plugin:
-
-| Route                         | Purpose                                  |
-| ----------------------------- | ---------------------------------------- |
-| `GET /:docId/state`           | Fetch full Y.Doc state (base64)          |
-| `POST /:docId/update`         | Apply client Yjs update                  |
-| `POST /:docId/text`           | Apply full text replacement (diff-based) |
-| `POST /:docId/search-replace` | Surgical find/replace in Y.XmlFragment   |
-| `POST /:docId/awareness`      | Sync cursor/presence state               |
-| `GET /:docId/users`           | List active users on a document          |
+All collab routes are auto-mounted under `/_agent-native/collab/` — see the [route table](#routes) for the full list.
 
 ## Agent edit action {#edit-document}
 
@@ -351,11 +342,9 @@ pnpm action edit-document --id doc123 --edits '[{"find":"old","replace":"new"}]'
 pnpm action edit-document --id doc123 --find "delete me" --replace ""
 ```
 
----
-
 ## Presence Kit {#presence-kit}
 
-The presence kit provides Liveblocks/collaboration-grade live-cursor and selection primitives on top of the existing awareness layer.
+The presence kit provides Liveblocks/collaboration-grade live-cursor and selection primitives on top of the existing awareness layer. Finer-grained presence — such as which users are viewing a given slide in a deck — layers on top of the same awareness state using the same hooks below.
 
 Import client-side presence and editor UI from the focused browser subpath:
 
@@ -421,7 +410,7 @@ import {
 
 ### Fast awareness {#fast-awareness}
 
-Awareness state changes now propagate at ~150ms instead of the 2s poll cycle:
+Awareness state changes propagate at ~150ms instead of waiting for the full poll cycle:
 
 - **Client → server**: any call to `setPresence()` or `awareness.setLocalStateField()` triggers a throttled POST to `/_agent-native/collab/:docId/awareness` within 150ms, coalescing rapid changes into one request.
 - **Server → clients**: the `postAwareness` handler emits an `AWARENESS_CHANGE_EVENT` after storing. The `/_agent-native/poll-events` SSE stream forwards these events push-style to connected peers. Polling-only deployments continue to work — cursors degrade to poll cadence without errors.
@@ -467,7 +456,7 @@ import { LiveCursorOverlay } from "@agent-native/toolkit/collab-ui";
 </div>;
 ```
 
-The agent's cursor renders distinctly with a sparkle icon. Cursors fade out after 10s of inactivity with smooth CSS transitions at 120ms.
+The agent's cursor renders with a distinct style so it's clear at a glance which cursor is the agent's. Cursors fade out after 10s of inactivity with smooth CSS transitions at 120ms.
 
 ### `RemoteSelectionRings` {#remote-selection-rings}
 
@@ -511,7 +500,7 @@ Participants publish their viewport with `setPresence({ viewport: { fileId, zoom
 
 ### `PresenceBar` follow-mode props {#presence-bar-follow}
 
-The `PresenceBar` component now accepts optional follow-mode props:
+The `PresenceBar` component accepts optional follow-mode props:
 
 ```tsx
 <PresenceBar
@@ -568,8 +557,6 @@ try {
 
 The selection metadata flows through `usePresence` on connected clients as `other.presence.selection`.
 
----
-
 ## Route table {#routes}
 
 All routes are auto-mounted under `/_agent-native/collab/` by the collab
@@ -723,11 +710,6 @@ Key properties:
 
 </Callout>
 
-- **Same-region simultaneous rewrite is LWW** — If the agent rewrites a
-  passage and a human has unsaved edits in the exact same region, the
-  lead-client snapshot can overwrite the human's in-flight changes. Edits in
-  different regions merge correctly via the CRDT. Granular server-side merge
-  (see above) avoids this for structured documents.
 - **In-process write locks on serverless** — The `_writeLocks` map is
   process-local. Concurrent requests landing on different serverless
   invocations serialize at the SQL CAS layer (optimistic concurrency) rather
@@ -738,26 +720,7 @@ Key properties:
   state per invocation. Clients still receive full awareness snapshots on each
   poll cycle, so presence indicators update within one poll interval.
 
-## Presence {#presence}
-
-The `useCollaborativeDoc` hook returns:
-
-- `activeUsers` — array of `CollabUser` (name, email, color) for all peers
-  currently in the document (sourced from awareness).
-- `agentActive` — `true` briefly after the agent makes an edit (use for a
-  transient visual indicator).
-- `agentPresent` — `true` while the agent has an active awareness entry
-  (durable presence heartbeat).
-
-Use `emailToColor(email)` and `emailToName(email)` from
-`@agent-native/toolkit/collab-ui` to generate consistent cursor colors and display
-names from email addresses.
-
-A `PresenceBar` rendered with `activeUsers` shows live human and agent
-collaborators. Per-slide presence (which users are viewing a given slide)
-layers on top of the same awareness state.
-
-## Related docs {#related}
+## What's next {#whats-next}
 
 - [Real-Time Sync](/docs/client#usedbsync) — the `useDbSync` + `useChangeVersion`
   system that delivers the `updatedAt` bump driving editor reconciliation.

package/corpus/core/docs/content/recurring-jobs.mdx

@@ -191,12 +191,14 @@ The scheduler is a framework plugin (the internal `processRecurringJobs()` routi
 
 A single `manage-jobs` tool is registered in every template. The `action` parameter selects the operation:
 
-| Action   | Parameters                                                        | Purpose                                                      |
-| -------- | ----------------------------------------------------------------- | ------------------------------------------------------------ |
-| `create` | `name`, `schedule`, `instructions` (required); `scope`, `runAs`   | Create a new recurring job                                   |
-| `list`   | `scope` (`personal`, `shared`, or all)                            | List all jobs with status (schedule, enabled, last/next run) |
-| `update` | `name` (required); `schedule`, `instructions`, `enabled`, `runAs` | Edit an existing job                                         |
-| `delete` | `name` (required)                                                 | Delete a job — always confirm with the user first            |
+| Action   | Parameters                                                                 | Purpose                                                      |
+| -------- | -------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `create` | `name`, `schedule`, `instructions` (required); `scope`, `runAs`, `model`   | Create a new recurring job                                   |
+| `list`   | `scope` (`personal`, `shared`, or all)                                     | List all jobs with status (schedule, enabled, last/next run) |
+| `update` | `name` (required); `schedule`, `instructions`, `enabled`, `runAs`, `model` | Edit an existing job                                         |
+| `delete` | `name` (required)                                                          | Delete a job — always confirm with the user first            |
+
+`model` is optional on both `create` and `update` — pass a model id to override the channel/app/engine default for that one routine.
 
 **Personal vs shared scope.** Each job lives in either personal scope (runs as and is visible only to the creator) or shared/org scope (runs on behalf of the creator but is visible to org members). The `scope` and `runAs` parameters control this at create time. Org admins can update or delete any shared job; non-admin members can only manage their own.
 

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

@@ -72,8 +72,7 @@ Prefix a segment with `$` for a dynamic param. Prefix with `_` to make it a path
 
 Create the file and export a default component:
 
-```tsx
-// app/routes/settings.tsx
+```tsx filename="app/routes/settings.tsx"
 export function meta() {
   return [{ title: "Settings" }];
 }
@@ -87,8 +86,7 @@ That's it — React Router picks it up automatically, no registration needed.
 
 ## Dynamic params {#dynamic-params}
 
-```tsx
-// app/routes/inbox/$threadId.tsx
+```tsx filename="app/routes/inbox.$threadId.tsx"
 import { useParams } from "react-router";
 
 export default function ThreadPage() {
@@ -116,3 +114,4 @@ navigate(`/inbox/${threadId}`);
 
 - [**Client**](/docs/client) — the agent-native browser hooks and utilities
 - [**Server**](/docs/server) — file-based server routes and the `/_agent-native/` namespace
+- [**Context Awareness**](/docs/context-awareness) — how the agent learns the current route and selection

package/corpus/core/docs/content/sandbox-adapters.mdx

@@ -6,8 +6,12 @@ search: "adapters sandbox adapter cli adapter run-code SandboxAdapter CliAdapter
 
 # Adapters
 
-> **Who is this for:** host authors extending the runtime. App developers rarely
-> need this — the defaults work out of the box.
+<Callout id="doc-block-adap1who" tone="info">
+
+**Who is this for:** host authors extending the runtime. App developers rarely
+need this — the defaults work out of the box.
+
+</Callout>
 
 Agent-Native has two adapter seams that factor a concern out behind a narrow,
 swappable interface:
@@ -26,15 +30,15 @@ not run on edge/worker runtimes — see [Edge and serverless](#edge-serverless).
 | You want to…                                                               | Use                                          |
 | -------------------------------------------------------------------------- | -------------------------------------------- |
 | Swap the backend that runs the agent's **`run-code` tool**                 | **Sandbox adapters** (this page)             |
-| Wrap a CLI tool (`gh`, `ffmpeg`) for the agent to call                     | **CLI adapters** (this page)                 |
+| Wrap a CLI tool (`gh`, `ffmpeg`) for the agent to call                     | [CLI Adapters](/docs/cli-adapters)           |
 | Render a Claude-Code/Codex-style **coding workspace UI**                   | [Agent-Native Code UI](/docs/code-agents-ui) |
 | Run Claude Code / Codex / Pi **as the agent**, with their own loop + tools | [Harness Agents](/docs/harness-agents)       |
 
-# Sandbox Adapters
+## Sandbox Adapters {#sandbox-adapters}
 
 The `run-code` tool runs agent-supplied JavaScript in an isolated environment. **Sandbox adapters** factor the _execution_ concern out of that tool so the backend can be swapped — a local child process by default, or a Docker / remote / durable runner — without touching the agent loop, `run-code.ts`, the localhost bridge, the env scrub, or the output formatting.
 
-## Why a seam {#why}
+### Why a seam {#why}
 
 The default backend spawns a locked-down local Node child process. That's bounded by the hosting process: on the hosted platform it shares the agent loop's soft execution ceiling (~40s before timeout/continuation thrash). A remote or durable adapter is the lever to exceed that ceiling — it runs large data jobs to completion independently of the request lifecycle.
 
@@ -86,14 +90,13 @@ Keeping the contract narrow means a remote adapter inherits the same security po
 
 </Diagram>
 
-## The interface {#interface}
+### The interface {#interface}
 
 The seam lives in core at `packages/core/src/coding-tools/sandbox/` — `adapter.ts` (the contract), `index.ts` (selection: `getSandboxAdapter()` / `registerSandboxAdapter()`), and `local-child-process-adapter.ts` (the default). It is wired in-package by `run-code.ts`; a host plugs in a different backend through the `index.ts` registration helper (or, for a Docker backend, via the [blueprint](/docs/blueprint-installer) that edits these files directly).
 
 <FileTree
   id="doc-block-b1k8n3"
   title="The sandbox seam in core"
-  title="packages/core/src/coding-tools/sandbox/"
   entries={[
     {
       path: "adapter.ts",
@@ -160,7 +163,7 @@ interface SandboxRunResult {
 }
 ```
 
-## The default: `LocalChildProcessAdapter` {#default}
+### The default: `LocalChildProcessAdapter` {#default}
 
 Out of the box, `getSandboxAdapter()` returns `LocalChildProcessAdapter` (`id: "local-child-process"`). It preserves the historical `run-code` behavior byte-for-byte:
 
@@ -170,10 +173,13 @@ Out of the box, `getSandboxAdapter()` returns `LocalChildProcessAdapter` (`id: "
 - A timeout sends `SIGTERM`, then `SIGKILL` after a 2s grace period.
 - Temp files are cleaned up best-effort after the run.
 
-> [!WARNING]
-> The default adapter uses `node:child_process`, which does not exist on edge/worker runtimes. Run `run-code` in a standard Node.js environment, or register a remote adapter — see [Edge and serverless](#edge-serverless).
+<Callout id="doc-block-adap1def" tone="warning">
+
+The default adapter uses `node:child_process`, which does not exist on edge/worker runtimes. Run `run-code` in a standard Node.js environment, or register a remote adapter — see [Edge and serverless](#edge-serverless).
+
+</Callout>
 
-## Selecting an adapter {#selection}
+### Selecting an adapter {#selection}
 
 Resolution order — an explicitly registered adapter wins; otherwise the env var selects a built-in; otherwise the local default is used:
 
@@ -181,7 +187,7 @@ Resolution order — an explicitly registered adapter wins; otherwise the env va
 registerSandboxAdapter(adapter)  →  AGENT_NATIVE_SANDBOX  →  local default
 ```
 
-### `AGENT_NATIVE_SANDBOX` env var {#env}
+#### `AGENT_NATIVE_SANDBOX` env var {#env}
 
 Selects a built-in adapter by id. Currently only `local` (the default) is wired; unknown values fall back to local rather than failing the run.
 
@@ -189,7 +195,7 @@ Selects a built-in adapter by id. Currently only `local` (the default) is wired;
 AGENT_NATIVE_SANDBOX=local   # the default — explicit
 ```
 
-### `registerSandboxAdapter()` {#register}
+#### `registerSandboxAdapter()` {#register}
 
 A host process overrides the backend for all subsequent `run-code` invocations through the seam's `index.ts` — for example, to run every call in a remote container:
 
@@ -211,7 +217,7 @@ registerSandboxAdapter(new RemoteSandboxAdapter());
 // Pass `null` to clear the override and fall back to env-var / default resolution.
 ```
 
-## The seam for a durable runner {#durable}
+### The seam for a durable runner {#durable}
 
 This interface is deliberately the seam for a future remote/durable sandbox. A remote or durable adapter (Docker, a Vercel-Sandbox-style runner, or a queued background worker) would:
 
@@ -221,54 +227,25 @@ This interface is deliberately the seam for a future remote/durable sandbox. A r
 
 Register it under a new `AGENT_NATIVE_SANDBOX` value (e.g. `remote`) and/or via `registerSandboxAdapter()`. The agent loop and `run-code.ts` never change.
 
-> [!TIP]
-> The `agent-native add sandbox docker` blueprint emits a full, self-contained recipe for implementing a Docker adapter against this seam. See [Blueprint Installer](/docs/blueprint-installer).
+<Callout id="doc-block-adap1tip" tone="info">
 
-# CLI Adapters
+The `agent-native add sandbox docker` blueprint emits a full, self-contained recipe for implementing a Docker adapter against this seam. See [Blueprint Installer](/docs/blueprint-installer).
 
-The other adapter seam wraps a single command-line tool (`gh`, `ffmpeg`, `stripe`, `aws`) so the agent can discover it, check whether it's installed, and run it with a consistent stdout/stderr/exit-code result. Every CLI adapter implements `CliAdapter`:
+</Callout>
 
-```ts
-import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+## CLI Adapters {#cli-adapters}
 
-interface CliAdapter {
-  name: string; // "gh", "stripe", "ffmpeg"
-  description: string; // What the agent sees during discovery
-  isAvailable(): Promise<boolean>;
-  execute(args: string[]): Promise<CliResult>;
-}
+The other adapter seam wraps a single command-line tool (`gh`, `ffmpeg`, `stripe`, `aws`) behind a `CliAdapter` contract, so the agent can discover it, check whether it's installed, and run it with a consistent stdout/stderr/exit-code result.
 
-interface CliResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-}
-```
+See [CLI Adapters](/docs/cli-adapters) for the `CliAdapter` contract, `ShellCliAdapter`, `CliRegistry`, and the action-wrapping pattern — this page only covers the seam it shares with sandbox adapters.
 
-For most CLIs, `ShellCliAdapter` wraps any binary with sensible defaults, and `CliRegistry` collects adapters for runtime discovery:
-
-```ts
-import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
-
-const cliRegistry = new CliRegistry();
-cliRegistry.register(
-  new ShellCliAdapter({
-    command: "gh",
-    description: "GitHub CLI — manage repos, PRs, issues, and releases",
-  }),
-);
-
-await cliRegistry.describe(); // [{ name, description, available }] for discovery
-const gh = cliRegistry.get("gh");
-const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
-```
+## Edge and serverless {#edge-serverless}
 
-Wrap a CLI call in `defineAction` to expose it on the action surface. See the [CLI Adapters](/docs/cli-adapters) quick reference for `ShellCliAdapter` options, custom adapters, and the action-wrapping pattern.
+<Callout id="doc-block-adap1edge" tone="warning">
 
-## Edge and serverless {#edge-serverless}
+Both adapter seams rely on Node.js system bindings. The sandbox `LocalChildProcessAdapter` and CLI adapters (`ShellCliAdapter` and custom adapters) use `node:child_process` (`execFile` / `spawn`), which **does not exist** on edge/worker runtimes such as Cloudflare Workers or Netlify Edge Functions. If you deploy server routes to these edge presets, executing these adapters throws a runtime exception. Run adapter endpoints and tasks in a standard Node.js environment (traditional server containers or serverless Node functions) — or, for the sandbox seam, register a remote adapter that ships work out of process.
 
-> [!WARNING]
-> Both adapter seams rely on Node.js system bindings. The sandbox `LocalChildProcessAdapter` and CLI adapters (`ShellCliAdapter` and custom adapters) use `node:child_process` (`execFile` / `spawn`), which **does not exist** on edge/worker runtimes such as Cloudflare Workers or Netlify Edge Functions. If you deploy server routes to these edge presets, executing these adapters throws a runtime exception. Run adapter endpoints and tasks in a standard Node.js environment (traditional server containers or serverless Node functions) — or, for the sandbox seam, register a remote adapter that ships work out of process.
+</Callout>
 
 ## What's next
 

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

@@ -415,3 +415,11 @@ AGENT_NATIVE_KEYS_WORKSPACE_FALLBACK=1
 ```
 
 Workspace-scope secret writes still require org owner/admin role regardless of this flag.
+
+## What's next
+
+- [**Authentication**](/docs/authentication) — auth modes, cookie realms, and session details this page builds on
+- [**Multi-Tenancy**](/docs/multi-tenancy) — the org-membership model behind `org_id` scoping
+- [**Sharing**](/docs/sharing) — the `ownableColumns()` and access-guard pattern applied to shareable resources
+- [**Messaging**](/docs/messaging#env-vars) — per-integration webhook signing secrets referenced in the checklist above
+- [**Deployment**](/docs/deployment) — the production environment variables this checklist assumes are set

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

@@ -96,8 +96,7 @@ server/routes/
 
 Each route exports a `defineEventHandler`:
 
-```ts
-// server/routes/api/health.get.ts
+```ts filename="server/routes/api/health.get.ts"
 import { defineEventHandler } from "h3";
 
 export default defineEventHandler(() => ({
@@ -137,8 +136,7 @@ Use the action `http` option to shape direct HTTP access: actions are `POST` by
 
 For a read-only status endpoint, keep it as an action:
 
-```ts
-// actions/get-status.ts
+```ts filename="actions/get-status.ts"
 import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 
@@ -171,8 +169,7 @@ what happened. For narrow server-side transforms that intentionally do not need
 tools, chat history, or run state, use `completeText()` as an explicit escape
 hatch.
 
-```ts
-// actions/classify-message.ts
+```ts filename="actions/classify-message.ts"
 import { defineAction } from "@agent-native/core/action";
 import { completeText } from "@agent-native/core/server";
 import { z } from "zod";
@@ -237,8 +234,7 @@ Actions mounted by the framework automatically run with request context. Custom
 
 Plugins live in `server/plugins/` and run at startup. Use them for migrations, provider setup, recurring jobs, integration adapters, and framework plugin configuration.
 
-```ts
-// server/plugins/db.ts
+```ts filename="server/plugins/db.ts"
 import { runMigrations } from "@agent-native/core/db";
 
 export default runMigrations(
@@ -416,8 +412,11 @@ Inbound webhooks should verify, persist, and return quickly. Long-running agent
 
 </Diagram>
 
-> [!WARNING]
-> Do not rely on unawaited promises after returning a response — serverless hosts freeze the execution. See [Messaging](/docs/messaging) for the canonical integration queue.
+<Callout tone="warning">
+  Do not rely on unawaited promises after returning a response — serverless
+  hosts freeze the execution. See [Messaging](/docs/messaging) for the canonical
+  integration queue.
+</Callout>
 
 ## Advanced: Escape Hatches {#advanced-escape-hatches}
 
@@ -459,3 +458,11 @@ const handler = createProductionAgentHandler({
   systemPrompt: "You are the app agent...",
 });
 ```
+
+## What's next
+
+- [**Actions**](/docs/actions) — the default operation surface; reach for a custom route only when it doesn't fit
+- [**Database**](/docs/database) — the `getDb()`/`schema` pattern custom routes and actions both import
+- [**Security**](/docs/security#access-guards) — `accessFilter`/`assertAccess` and the full data-scoping model
+- [**Messaging**](/docs/messaging) — the canonical inbound-webhook integration queue pattern
+- [**MCP Protocol**](/docs/mcp-protocol) — the `/_agent-native/mcp` endpoint this server mounts automatically