@agent-native/core 0.62.1 → 0.63.1

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

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

@@ -5,6 +5,18 @@ description: "Build and customize Agent-Native Code surfaces with the shared UI
 
 # Agent-Native Code UI
 
+> **Who is this for:** host authors building or customizing a coding-workspace
+> surface (CLI, Desktop, or a browser template) on the shared Code UI package.
+
+## Which coding doc do I want? {#which-doc}
+
+| You want to…                                                               | Use                                    |
+| -------------------------------------------------------------------------- | -------------------------------------- |
+| Render a Claude-Code/Codex-style **coding workspace UI**                   | **Agent-Native Code UI** (this page)   |
+| Run Claude Code / Codex / Pi **as the agent**, with their own loop + tools | [Harness Agents](/docs/harness-agents) |
+| Swap the backend that runs the agent's **`run-code` tool**                 | [Adapters](/docs/sandbox-adapters)     |
+| Wrap a CLI tool (`gh`, `ffmpeg`) for the agent to call                     | [Adapters](/docs/sandbox-adapters)     |
+
 Agent-Native Code is the Agent-Native coding surface: a local Claude Code/Codex-style workspace for coding sessions, slash commands, migrations, audits, transcripts, run controls, and follow-ups. A bare `npx @agent-native/core@latest` command opens this workspace; `npx @agent-native/core@latest code` is the explicit subcommand for the same experience.
 
 There are three layers:
@@ -62,6 +74,24 @@ Desktop uses the shared UI but keeps privileged capabilities in Electron:
 
 That separation matters. The UI can be reused by templates, but native process control should stay in Desktop or CLI.
 
+## Codex CLI Auth {#codex-cli-auth}
+
+Agent-Native Code can use a local Codex CLI login instead of an OpenAI API key.
+Install the Codex CLI on your `PATH`, sign in once, then restart Desktop or the
+Code UI if it was already open:
+
+```bash
+npm install -g @openai/codex@latest
+codex login
+codex login status
+```
+
+Desktop and the CLI read `codex login status` and run `codex exec`, so they
+reuse whatever ChatGPT subscription or API-key auth your installed Codex CLI
+reports. This is separate from the `@ai-sdk/harness-codex` package used by
+[Harness Agents](/docs/harness-agents); the harness adapter does not add a
+separate Agent-Native OAuth flow.
+
 ## Browser Host
 
 The old hidden `code` template has been removed. To build a browser-hosted Code surface, create a normal app and mount the shared UI package with a host implementation:
@@ -252,6 +282,19 @@ available when needed.
 
 Agent-Native Code treats migration as a capability, not a separate app category. `/migrate` can be a built-in goal, a project command, or a custom instruction pack on top of the same host contract.
 
+### Migrating to Agent-Native with `/migrate` {#migrate}
+
+`/migrate` is the built-in goal for moving an existing app, URL, or described product into Agent-Native. It is a slash goal in the Code workspace — not a separate template to scaffold and not a one-off product — so it shares the same session store, transcript, run controls, and Desktop hub as every other Code session, and you can resume, attach to, inspect, and stop it the same way.
+
+```bash
+npx @agent-native/core@latest code /migrate ./my-next-app --out ../migrated-app
+npx @agent-native/core@latest code /migrate https://example.com --describe "marketing site plus dashboard"
+npx @agent-native/core@latest code /migrate --describe "A Rails admin app with reports and CSV imports" --emit
+npx @agent-native/core@latest migrate ./my-next-app --out ../migrated-app   # shortcut into the same goal
+```
+
+Local source paths are read-only; generated output must live outside the source tree. Use `--emit <dir>` to write a portable migration dossier (`AGENTS.md`, `MIGRATION_PLAYBOOK.md`, assessment, and an `ir.json` inventory when available) and hand it to another coding agent instead of opening the internal run surface. `/migrate` reuses the framework's normal credentials system — there is no migration-specific key store. The `@agent-native/migrate` package exposes a reusable engine (`createMigrationRun`, `discoverMigration`, `planMigration`, source/target adapters) for custom workflows.
+
 Project-specific commands live in:
 
 ```text

package/docs/content/components.md

@@ -49,9 +49,11 @@ so bundlers choose the browser-safe entry.
 `AgentChatRuntime` is the BYO-agent contract for the standard chat shell. Pass
 `runtime` to `<AssistantChat>` when an external agent should power the
 conversation while Agent-Native keeps the composer, transcript, tool cards, and
-native widget rendering. If you are choosing between headless actions, rich
-chat, embedded sidecar, and full app shapes, see
-[Agent Surfaces](/docs/agent-surfaces).
+native widget rendering. The connectors above are the API surface; the runtime
+contract and event shapes are taught in
+[Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes).
+If you are choosing between headless agents, rich chat, embedded sidecar, and
+full app shapes, see [Agent Surfaces](/docs/agent-surfaces).
 
 The shortest custom route is still a pre-wired surface:
 
@@ -85,26 +87,11 @@ function CustomChat({ projectSlug }: { projectSlug: string }) {
 }
 ```
 
-For a bring-your-own agent endpoint:
-
-```tsx
-import {
-  AssistantChat,
-  createOpenAIAgentsChatRuntime,
-} from "@agent-native/core/client/chat";
-
-const runtime = createOpenAIAgentsChatRuntime({
-  endpoint: "/api/my-agent/chat",
-  label: "My agent",
-});
-
-export function MyAgentChat() {
-  return <AssistantChat runtime={runtime} />;
-}
-```
-
-Use `createHttpAgentChatRuntime()` instead when your endpoint already emits
-Agent-Native normalized events.
+For a bring-your-own agent endpoint, build an `AgentChatRuntime` with one of the
+connectors above and pass it to `<AssistantChat runtime={...} />`. See
+[Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes)
+for the connector usage, the normalized event stream, and when to reach for
+`createHttpAgentChatRuntime()` versus a protocol-specific connector.
 
 ## Chat Field And Composer {#composer}
 

package/docs/content/context-awareness.md

@@ -13,7 +13,7 @@ How the agent knows what the user is looking at -- and how the agent can control
 
 Without context awareness, the agent is blind. It asks "which email?" when the user is staring at one. It cannot act on the current selection, cannot provide relevant suggestions, and cannot modify what the user sees. With context awareness, the user can click a row, highlight a paragraph, select a slide element, or press Cmd+I, then say "summarize this" and the agent already knows what "this" means.
 
-Six patterns solve this. To understand what to put in which surface (AGENTS.md vs. skills vs. application_state), see [Writing Agent Instructions — The four surfaces the agent sees](/docs/writing-agent-instructions#four-surfaces).
+To understand what to put in which surface (AGENTS.md vs. skills vs. application_state), see [Writing Agent Instructions — The four surfaces the agent sees](/docs/writing-agent-instructions#four-surfaces).
 
 Six patterns solve this:
 
@@ -76,7 +76,7 @@ const navigation = await readAppState("navigation");
 
 `AgentPanel` automatically syncs the current React Router URL into the `__url__` application-state key. The built-in agent includes it in every turn as a `<current-url>` block:
 
-```txt
+```text
 <current-url>
 pathname: /adhoc/revenue
 search: ?f_region=west&q=renewal
@@ -88,7 +88,7 @@ searchParams:
 
 This is the canonical layer for shareable filter state. If the user can copy a URL and come back to the same filtered list, the filter belongs in the query string. The agent can change those filters with the built-in `set-search-params` tool:
 
-```txt
+```text
 set-search-params({ "params": { "f_region": "east", "q": null } })
 ```