@agent-native/core 0.63.0 → 0.63.2

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                                                                                                                          |

package/docs/content/automations.md

@@ -7,7 +7,7 @@ description: "Event-triggered and scheduled automations with natural-language co
 
 An **automation** is a rule: _when X happens, do Y_ — described in natural language. The agent executes the instructions, so automations have access to every action, tool, and MCP server the agent can use in an interactive chat.
 
-Automations extend [recurring jobs](/docs/recurring-jobs) with **event triggers**, **natural-language conditions**, and **outbound HTTP** via the `web-request` tool. They live as markdown resources under `jobs/` — the same storage and format as recurring jobs, with extra frontmatter fields.
+Automations extend [recurring jobs](/docs/recurring-jobs) with **event triggers**, **natural-language conditions**, and **outbound HTTP** via the `web-request` tool. They use the same `jobs/<name>.md` file format, storage, and "create three ways" workflow as recurring jobs — see [Recurring Jobs](/docs/recurring-jobs#job-file) for the shared format. This page covers only what's new for event-driven automations.
 
 ## Two trigger types {#trigger-types}
 
@@ -30,17 +30,10 @@ The agent discovers available events, confirms the plan, and writes the automati
 
 Automations appear in the settings panel. Users can view, enable/disable, and delete them there.
 
-### Via the API
+The third path — writing the `jobs/<name>.md` file by hand via `resourcePut` — works exactly as it does for [recurring jobs](/docs/recurring-jobs#creating). For an event-driven automation you add the event-trigger frontmatter below to that same file. An event-triggered job sets `schedule: ""` and supplies `triggerType: event`, an `event` name, and an optional `condition`:
 
-Write a `jobs/<name>.md` resource directly:
-
-```ts
-import { resourcePut } from "@agent-native/core/resources";
-
-await resourcePut(
-  ownerEmail,
-  "jobs/slack-on-builder-booking.md",
-  `---
+```yaml
+---
 schedule: ""
 enabled: true
 triggerType: event
@@ -48,36 +41,25 @@ event: calendar.booking.created
 condition: "attendee email ends with @builder.io"
 mode: agentic
 domain: calendar
-createdBy: steve@builder.io
 runAs: creator
 ---
-
 Send a Slack message to #sales with the booking details.
-Use the web-request tool to POST to \${keys.SLACK_WEBHOOK}.`,
-);
+Use the web-request tool to POST to ${keys.SLACK_WEBHOOK}.
 ```
 
-## The markdown format {#format}
-
-Each automation is a markdown file with YAML frontmatter and a body containing natural-language instructions.
-
-### Frontmatter fields {#frontmatter}
-
-| Field         | Type                                                   | Default      | Description                                                                                                                                                  |
-| ------------- | ------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `schedule`    | cron expression                                        | `""`         | Cron expression (required for schedule triggers)                                                                                                             |
-| `enabled`     | boolean                                                | `true`       | Whether the automation is active                                                                                                                             |
-| `triggerType` | `"schedule"` \| `"event"`                              | `"schedule"` | How the automation fires                                                                                                                                     |
-| `event`       | string                                                 | _(optional)_ | Event name to subscribe to (event triggers only)                                                                                                             |
-| `condition`   | string                                                 | _(optional)_ | Natural-language condition evaluated before dispatch                                                                                                         |
-| `mode`        | `"agentic"` \| `"deterministic"`                       | `"agentic"`  | Full agent loop. (`"deterministic"` is reserved but not yet implemented — automations that set it are skipped. Use `"agentic"` for all current automations.) |
-| `domain`      | string                                                 | _(optional)_ | Grouping tag (mail, calendar, clips, etc.)                                                                                                                   |
-| `createdBy`   | email                                                  | _(auto)_     | Owner email                                                                                                                                                  |
-| `orgId`       | string                                                 | _(auto)_     | Org scope; inherited from the creator's active org                                                                                                           |
-| `runAs`       | `"creator"` \| `"shared"`                              | `"creator"`  | Whose API key and permissions to use                                                                                                                         |
-| `lastRun`     | ISO timestamp                                          | _(managed)_  | Written by the dispatcher after each run                                                                                                                     |
-| `lastStatus`  | `"success"` \| `"error"` \| `"running"` \| `"skipped"` | _(managed)_  | Latest outcome                                                                                                                                               |
-| `lastError`   | string                                                 | _(managed)_  | Error message if the last run failed                                                                                                                         |
+## Automation frontmatter {#frontmatter}
+
+Automations share every field in the [recurring-jobs frontmatter table](/docs/recurring-jobs#frontmatter). These additional fields control event triggers, conditions, and the execution mode:
+
+| Field         | Type                             | Default      | Description                                                                                                                                                  |
+| ------------- | -------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `triggerType` | `"schedule"` \| `"event"`        | `"schedule"` | How the automation fires                                                                                                                                     |
+| `event`       | string                           | _(optional)_ | Event name to subscribe to (event triggers only)                                                                                                             |
+| `condition`   | string                           | _(optional)_ | Natural-language condition evaluated before dispatch                                                                                                         |
+| `mode`        | `"agentic"` \| `"deterministic"` | `"agentic"`  | Full agent loop. (`"deterministic"` is reserved but not yet implemented — automations that set it are skipped. Use `"agentic"` for all current automations.) |
+| `domain`      | string                           | _(optional)_ | Grouping tag (mail, calendar, clips, etc.)                                                                                                                   |
+
+For an event trigger, `schedule` is `""` (empty); for a schedule trigger it carries the cron expression. The dispatcher also writes the same managed `lastRun` / `lastStatus` / `lastError` fields the scheduler does, plus a `"skipped"` status when a condition evaluates to false.
 
 ## The event bus {#event-bus}
 

package/docs/content/blueprint-installer.md

@@ -5,6 +5,9 @@ description: "agent-native add prints a curated Markdown integration recipe to s
 
 # Blueprint Installer
 
+> **Who is this for:** host authors and integrators adding a provider, channel,
+> sandbox backend, or action to a repo by piping a recipe into their coding agent.
+
 `agent-native add` is **not** a dumb scaffolder that writes files for you. It emits a curated Markdown _integration blueprint_ to stdout. You pipe that blueprint into your own coding agent (Claude Code, Codex, …), which applies the changes against the live repo with full context.
 
 This fits the agent-applies-changes, filesystem-first house style: the framework supplies the recipe (the canonical files to touch, the rules to honor, the verification step), and the coding agent does the editing.

package/docs/content/cli-adapters.md

@@ -1,21 +1,16 @@
 ---
 title: "CLI Adapters"
-description: "Connect any CLI tool to your agent-native app with a standard adapter interface for discovery and execution."
+description: "Give the agent structured access to any CLI tool (gh, ffmpeg, stripe) through a standard adapter interface — one of the two adapter seams covered in the Adapters guide."
 ---
 
 # CLI Adapters
 
-Give your agent structured access to any CLI tool — with discovery, execution, and consistent output handling.
+> **Where this fits:** CLI adapters are one of two adapter seams in the
+> framework. The canonical guide is [Adapters](/docs/sandbox-adapters), which
+> covers both this seam and the `run-code` sandbox seam — including the shared
+> edge/serverless constraint. This page is the quick reference for the CLI side.
 
-## Overview {#overview}
-
-Agents are great at running CLI commands. But without structure, every script reinvents how to invoke a CLI, check if it's installed, and parse its output.
-
-CLI adapters solve this with a small interface — similar to file sync adapters but for command-line tools. Each adapter wraps a single CLI (`gh`, `ffmpeg`, `stripe`, `aws`) and provides:
-
-- **Discovery** — the agent can list what CLIs are available and what they do
-- **Availability checks** — is the CLI installed?
-- **Consistent execution** — stdout, stderr, and exit code in a standard format
+A CLI adapter 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. Without this seam, every script reinvents how to invoke a CLI and parse its output.
 
 ## The interface {#the-interface}
 
@@ -40,7 +35,7 @@ interface CliResult {
 
 ## ShellCliAdapter {#shell-adapter}
 
-For most CLIs, you don't need a custom class. `ShellCliAdapter` wraps any CLI binary with sensible defaults:
+For most CLIs you don't need a custom class — `ShellCliAdapter` wraps any binary with sensible defaults:
 
 ```ts
 import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
@@ -54,177 +49,37 @@ const ffmpeg = new ShellCliAdapter({
   command: "ffmpeg",
   description: "Audio/video processing and transcoding",
   timeoutMs: 120_000, // 2 min for long encodes
-});
-
-const stripe = new ShellCliAdapter({
-  command: "stripe",
-  description: "Stripe CLI — manage payments, webhooks, and customers",
   env: { STRIPE_API_KEY: process.env.STRIPE_SECRET_KEY! },
 });
 ```
 
-### Options {#shell-adapter-options}
+Options: `command` (required), `description` (required), `name` (defaults to `command`), `env` (merged with `process.env`), `cwd` (defaults to `process.cwd()`), and `timeoutMs` (default `30000`).
 
-| Option        | Type   | Description                                         |
-| ------------- | ------ | --------------------------------------------------- |
-| `command`     | string | Binary name or path (required)                      |
-| `description` | string | What the CLI does — shown to the agent (required)   |
-| `name`        | string | Display name (defaults to `command`)                |
-| `env`         | Record | Extra environment variables merged with process.env |
-| `cwd`         | string | Working directory (defaults to process.cwd())       |
-| `timeoutMs`   | number | Execution timeout (default: 30000)                  |
+For custom auth, output parsing, or pre/post processing, implement `CliAdapter` directly instead of using `ShellCliAdapter`.
 
 ## Registry {#registry}
 
-The `CliRegistry` collects adapters so the agent can discover what's available at runtime:
+`CliRegistry` collects adapters so the agent can discover what's available at runtime:
 
 ```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",
-  }),
+  new ShellCliAdapter({ command: "gh", description: "GitHub CLI" }),
 );
 
-cliRegistry.register(
-  new ShellCliAdapter({
-    command: "ffmpeg",
-    description: "Audio/video processing and transcoding",
-  }),
-);
-
-// List all registered CLIs
-cliRegistry.list();
-// → [{ name: "gh", ... }, { name: "ffmpeg", ... }]
-
-// List only installed CLIs
-await cliRegistry.listAvailable();
-// → [{ name: "gh", ... }]  (if ffmpeg isn't installed)
+cliRegistry.list(); // all registered
+await cliRegistry.listAvailable(); // only installed
+await cliRegistry.describe(); // [{ name, description, available }] for discovery
 
-// Get a full summary for agent discovery
-await cliRegistry.describe();
-// → [{ name: "gh", description: "...", available: true },
-//    { name: "ffmpeg", description: "...", available: false }]
-
-// Execute a command
 const gh = cliRegistry.get("gh");
 const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
-console.log(result?.stdout);
-```
-
-## Custom adapters {#custom-adapter}
-
-When you need more than `ShellCliAdapter` provides — custom auth, output parsing, or pre/post processing — implement `CliAdapter` directly:
-
-```ts
-import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
-import { execFile } from "node:child_process";
-
-export class DockerAdapter implements CliAdapter {
-  name = "docker";
-  description =
-    "Docker container management — build, run, and manage containers";
-
-  async isAvailable(): Promise<boolean> {
-    try {
-      const result = await this.execute([
-        "info",
-        "--format",
-        "{{.ServerVersion}}",
-      ]);
-      return result.exitCode === 0;
-    } catch {
-      return false;
-    }
-  }
-
-  async execute(args: string[]): Promise<CliResult> {
-    return new Promise((resolve) => {
-      execFile(
-        "docker",
-        args,
-        {
-          timeout: 60_000,
-          maxBuffer: 10 * 1024 * 1024,
-          encoding: "utf-8",
-        },
-        (error, stdout, stderr) => {
-          resolve({
-            stdout: stdout ?? "",
-            stderr: stderr ?? "",
-            exitCode: (error as any)?.code ?? 0,
-          });
-        },
-      );
-    });
-  }
-}
-```
-
-> [!WARNING]
-> **Edge and Serverless Compatibility:**
-> CLI adapters (both `ShellCliAdapter` and custom adapters using `node:child_process`) rely on Node.js-specific system bindings (`child_process.execFile` or `child_process.spawn`).
-> These APIs **do not exist** on edge/worker runtimes (e.g., Cloudflare Workers, Netlify Edge Functions). If you deploy your server routes to these edge presets, executing CLI adapters will throw runtime exceptions. Always ensure CLI adapter endpoints and tasks run in standard Node.js environments (like traditional server containers or serverless Node functions).
-
-## Server route {#server-route}
-
-Expose the registry to the UI via an API route so actions and components can discover and invoke CLIs:
-
-`createServer()` returns an H3 `{ app, router }`. Mount routes on `router` with H3 handlers (`defineEventHandler`, `readBody`, `getRouterParam`):
-
-```ts
-// server/index.ts
-import { createServer } from "@agent-native/core";
-import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
-import {
-  defineEventHandler,
-  readBody,
-  getRouterParam,
-  setResponseStatus,
-} from "h3";
-
-const { router } = createServer();
-const cliRegistry = new CliRegistry();
-
-cliRegistry.register(
-  new ShellCliAdapter({
-    command: "gh",
-    description: "GitHub CLI",
-  }),
-);
-
-// Discovery endpoint — agent can query this
-router.get(
-  "/api/cli",
-  defineEventHandler(async () => {
-    return await cliRegistry.describe();
-  }),
-);
-
-// Execution endpoint
-router.post(
-  "/api/cli/:name",
-  defineEventHandler(async (event) => {
-    const name = getRouterParam(event, "name");
-    const adapter = name ? cliRegistry.get(name) : undefined;
-    if (!adapter) {
-      setResponseStatus(event, 404);
-      return { error: "CLI not found" };
-    }
-
-    const { args } = await readBody(event);
-    return await adapter.execute(args ?? []);
-  }),
-);
 ```
 
 ## Using from actions {#from-actions}
 
-Actions can use CLI adapters directly for structured access:
+Wrap a CLI call in `defineAction` to expose it on the action surface — `defineAction` is required when the code runs inside the server action surface; use an adapter directly in a `scripts/` file otherwise. Never call `process.exit` in an action; throw an error instead.
 
 ```ts
 // actions/list-prs.ts
@@ -232,10 +87,7 @@ import { defineAction } from "@agent-native/core/action";
 import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
 import { z } from "zod";
 
-const gh = new ShellCliAdapter({
-  command: "gh",
-  description: "GitHub CLI",
-});
+const gh = new ShellCliAdapter({ command: "gh", description: "GitHub CLI" });
 
 export default defineAction({
   description: "List open pull requests via the GitHub CLI.",
@@ -244,7 +96,6 @@ export default defineAction({
     if (!(await gh.isAvailable())) {
       throw new Error("GitHub CLI not installed. Run: brew install gh");
     }
-
     const result = await gh.execute([
       "pr",
       "list",
@@ -253,14 +104,19 @@ export default defineAction({
       "--limit",
       "10",
     ]);
-
     if (result.exitCode !== 0) {
       throw new Error(result.stderr || "gh pr list failed");
     }
-
     return JSON.parse(result.stdout);
   },
 });
 ```
 
-Or use CLI adapters directly in a script under `scripts/` — adapters are useful when you want discovery, availability checks, and consistent error handling, but `defineAction` is required when the code runs inside the server action surface. Never call `process.exit` in an action; throw an error instead.
+## Edge and serverless {#edge-serverless}
+
+CLI adapters use `node:child_process`, which does not exist on edge/worker runtimes (Cloudflare Workers, Netlify Edge Functions). Run CLI adapter endpoints and tasks in a standard Node.js environment. This constraint is shared with the sandbox seam — see the full discussion in [Adapters](/docs/sandbox-adapters#edge-serverless).
+
+## 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.

package/docs/content/client.md

@@ -9,21 +9,7 @@ description: "React hooks and utilities for agent-native apps: sendToAgentChat,
 
 These client/React APIs are exported from both `@agent-native/core` and `@agent-native/core/client`. Import them from `@agent-native/core/client` (the browser entry) for clarity and correct bundling, since the bare `@agent-native/core` root resolves to the Node build by default.
 
-## File-Based Routing {#file-based-routing}
-
-Agent-native apps use **React Router v7** with file-based routing via `flatRoutes()` from `@react-router/fs-routes`. Every file in `app/routes/` becomes a URL. Templates use the dot-notation convention — dots separate URL segments inside a single filename.
-
-### File → URL mapping
-
-| File                  | URL                | Notes                                  |
-| --------------------- | ------------------ | -------------------------------------- |
-| `_index.tsx`          | `/`                | Index route                            |
-| `settings.tsx`        | `/settings`        | Simple page                            |
-| `inbox.$threadId.tsx` | `/inbox/:threadId` | Dot = `/`, `$` = dynamic param         |
-| `_app.tsx`            | (no URL segment)   | Pathless layout — prefix with `_`      |
-| `inbox/route.tsx`     | `/inbox`           | Folder form — `route.tsx` is the index |
-
-Prefix a segment with `$` for a dynamic param. Prefix with `_` to make it a pathless layout route (no URL segment). Templates use `flatRoutes()` — the dot-notation file above is primary; the nested-folder form `inbox/route.tsx` also works.
+For file-based routing — adding pages, dynamic params, and navigation — see [Routing](/docs/routing).
 
 ## Fetching and Mutating Data {#fetching-mutating}
 
@@ -47,70 +33,9 @@ mutate({ name: "Alice", company: "Acme" });
 await callAction("archive-lead", { leadId });
 ```
 
----
-
-### Adding a new page
-
-Create the file and export a default component:
-
-```tsx
-// app/routes/settings.tsx
-export function meta() {
-  return [{ title: "Settings" }];
-}
-
-export default function SettingsPage() {
-  return <div>Settings</div>;
-}
-```
-
-That's it — React Router picks it up automatically, no registration needed.
-
-### Dynamic params
-
-```tsx
-// app/routes/inbox/$threadId.tsx
-import { useParams } from "react-router";
-
-export default function ThreadPage() {
-  const { threadId } = useParams();
-  return <div>Thread: {threadId}</div>;
-}
-```
-
-### Navigation
-
-Use `<Link>` for client-side navigation and `useNavigate()` for programmatic navigation:
-
-```tsx
-import { Link, useNavigate } from "react-router";
-
-// In JSX
-<Link to="/settings">Settings</Link>;
-
-// Programmatic
-const navigate = useNavigate();
-navigate(`/inbox/${threadId}`);
-```
-
----
-
 ## sendToAgentChat(opts) {#sendtoagentchat}
 
-Send a message to the agent chat via postMessage. Used to delegate AI tasks from UI interactions.
-
-When the app route is running inside an MCP App embed created with `embedApp()`,
-auto-submitted messages (`submit` omitted or `true`) are forwarded to the MCP
-App host bridge, which asks the containing host to add hidden context and send
-the visible user turn. `context` is sent as model context before the visible
-message, so it stays model-visible without being posted as user-facing chat or
-concatenated into the host's visible prompt.
-`submit: false` keeps the local prefill/review behavior because MCP Apps do not
-define a standard draft-prefill API.
-
-Internally this is the submitted-chat path sometimes surfaced as
-`agentNative.submitChat`; app code should call `sendToAgentChat()` rather than
-posting that event directly.
+Send a message to the agent chat via postMessage — the common way to delegate an AI task from a UI interaction. Pass `context` for hidden model context and `submit: true` to send immediately, or `submit: false` to prefill a draft the user reviews first.
 
 ```ts
 import { sendToAgentChat } from "@agent-native/core/client";
@@ -130,6 +55,15 @@ sendToAgentChat({
 });
 ```
 
+Inside an MCP App embed created with `embedApp()`, auto-submitted messages
+(`submit` omitted or `true`) are forwarded to the MCP App host bridge, which
+asks the containing host to add hidden context and send the visible user turn.
+`context` stays model-visible without being posted as user-facing chat.
+`submit: false` keeps the local prefill/review behavior because MCP Apps do not
+define a standard draft-prefill API. Internally this is the submitted-chat path
+sometimes surfaced as `agentNative.submitChat`; app code should call
+`sendToAgentChat()` rather than posting that event directly.
+
 ### Silent background sends {#background-send}
 
 Use `background: true` when a UI action should kick off real agent work without

package/docs/content/cloneable-saas.md

@@ -77,7 +77,7 @@ Not ready to scaffold? You can add agent-native superpowers to a coding agent yo
 
 ## Building on this
 
-- [**Getting Started**](/docs/getting-started) — create a minimal chat app or headless action
+- [**Getting Started**](/docs/getting-started) — create a minimal chat app or headless agent
 - [**Messaging the agent**](/docs/messaging) — how users (and you) talk to the agent that ships with each template
 - [**Multi-App Workspace**](/docs/multi-app-workspace) — bundle several templates into one workspace that shares auth, brand, and agent
 - [**Dispatch**](/docs/template-dispatch) — the workspace control plane template