@agent-native/core 0.62.1 → 0.63.1

package/docs/content/mcp-protocol.md

@@ -5,19 +5,16 @@ description: "Expose your agent-native app as a remote MCP server so Claude, Cha
 
 # MCP Protocol
 
-Every agent-native app automatically exposes a remote MCP (Model Context Protocol) server. This lets external AI tools like Claude, ChatGPT custom MCP apps, Claude Code, Cursor, Codex, VS Code GitHub Copilot, and Windsurf discover and call your app's actions directly — no extra code needed.
+**This page: the lower-level MCP server reference.** How every agent-native app exposes its actions over MCP — the auto-mounted endpoint, auth modes, the `tools/call` / `ask-agent` surface, and custom mounting. Reach for it when you need server internals; for connecting a host, start with [External Agents](/docs/external-agents).
 
-**Which page do I need?**
+| If you want to…                                              | Read                                     |
+| ------------------------------------------------------------ | ---------------------------------------- |
+| Connect an external agent/host to your app                   | [External Agents](/docs/external-agents) |
+| Give your agent more tools (consume other MCP servers)       | [MCP Clients](/docs/mcp-clients)         |
+| Build inline UIs that render in Claude/ChatGPT               | [MCP Apps](/docs/mcp-apps)               |
+| Lower-level MCP server reference (auth, tools, custom mount) | **This page** — MCP Protocol             |
 
-| Goal                                                        | Page                                     |
-| ----------------------------------------------------------- | ---------------------------------------- |
-| Connect Claude / ChatGPT / Codex / Cursor to a hosted app   | [External Agents](/docs/external-agents) |
-| Make your app callable over MCP (server setup, auth, tools) | This page                                |
-| Give your app's agent more tools from external MCP servers  | [MCP Clients](/docs/mcp-clients)         |
-| App-to-app delegation via JSON-RPC                          | [A2A Protocol](/docs/a2a-protocol)       |
-| Build or embed interactive MCP App resources                | [MCP Apps](/docs/mcp-apps)               |
-
-If your goal is to connect Claude, ChatGPT, Claude Code, Codex, Cursor, or Claude Cowork to hosted agent-native apps, start with [External Agents](/docs/external-agents). It documents the recommended single Dispatch connector at `https://dispatch.agent-native.com/_agent-native/mcp`, direct per-app URLs for isolated app access, standard remote MCP OAuth, fallback config for older clients, MCP Apps inline UIs, and deep links back into the UI. This page is the lower-level MCP server reference.
+Every agent-native app automatically exposes a remote MCP (Model Context Protocol) server, so external AI tools like Claude, ChatGPT custom MCP apps, Claude Code, Cursor, Codex, and VS Code GitHub Copilot can discover and call your app's actions directly — no extra code needed. If your goal is to _connect_ one of those hosts to a hosted app, [External Agents](/docs/external-agents) covers the recommended single Dispatch connector, per-app URLs, OAuth, MCP Apps inline UIs, and deep links. This page documents what sits underneath that.
 
 ## Overview {#overview}
 
@@ -103,24 +100,9 @@ See [MCP Apps](/docs/mcp-apps#mcp-app-bridge) for the full embed bridge details
 
 ## Tools {#tools}
 
-Every caller gets a compact app-host catalog by default — chat-style app hosts
-(OAuth callers that request `mcp:apps` and generic authenticated remote
-HTTP/static-token callers), code/stdio developer clients, and the local CLI
-proxy alike: app-facing builtins (`list_apps`, `open_app`, `ask_app`, and
-app-only `create_embed_session`), the template-declared app actions, and rare
-actions marked `mcpApp.compactCatalog: true`. Their `resources/list` is compact
-too, normally advertising only the generic `open_app` embed resource. The
-catalog is never inferred from the client name or user-agent. The full action
-surface is served only on explicit opt-in — a token minted with `--full-catalog`
-(`catalog_scope: "full"`) or the deployment-wide `AGENT_NATIVE_MCP_FULL_CATALOG=1`
-override. `tool-search` is always available, including in the compact catalog:
-call it with no query for the full menu of tool names and one-line descriptions,
-or with a query for ranked matches with parameter summaries, to reach any tool
-on demand. `publicAgent.expose` remains the opt-in for safe read/ingest tools
-outside that compact app catalog. This keeps ChatGPT/Claude app-host discovery
-small while keeping every tool reachable.
-
-The mapping is direct:
+Every caller gets a **compact catalog by default** (template-declared app actions plus the cross-app builtins), with the full action surface served only on explicit opt-in and `tool-search` always available to reach the rest. See [External Agents → Catalog tiers](/docs/external-agents#catalog-tiers) for the full explanation.
+
+Each action maps directly to one MCP tool:
 
 | Action property    | MCP tool property |
 | ------------------ | ----------------- |

package/docs/content/messaging.md

@@ -291,7 +291,7 @@ Every incoming webhook is signature-verified before processing:
 The email adapter also enforces:
 
 - **Allowed domains** — optional `allowedDomains` array in the integration's `integration_configs` row; senders outside the list are dropped.
-- **Rate limit** — in-memory limiter at 20 inbound messages per sender per hour.
+- **Rate limit** — SQL-queue-backed rate limit of 20 inbound messages per sender per hour.
 
 ### Proactive sends {#proactive-sends}
 

package/docs/content/migration-workbench.md

@@ -1,187 +1,26 @@
 ---
 title: "Migrating to Agent-Native (/migrate)"
-description: "Use the open-source Agent-Native Code workspace for coding sessions, including the built-in /migrate capability."
+description: "Migration is a built-in /migrate goal in the Agent-Native Code workspace — not a separate app. See Agent-Native Code UI for the full guide."
 ---
 
 # Migrating to Agent-Native (/migrate)
 
-Start from **Agent-Native Code**:
+Migration is **not a separate product or template** — it is the built-in
+`/migrate` goal inside the [Agent-Native Code](/docs/code-agents-ui) workspace.
+It runs as a normal Code session you can resume, attach to, inspect, and stop.
 
 ```bash
-npx @agent-native/core@latest
-npx @agent-native/core@latest "fix the failing auth tests"
-npx @agent-native/core@latest code
-npx @agent-native/core@latest code "fix the failing auth tests"
-npx @agent-native/core@latest code attach --last
 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 migrate ./my-next-app --out ../migrated-app   # shortcut into the same goal
 ```
 
-**Agent-Native Code** is the open-source Claude Code/Codex-like workspace for coding work in Agent-Native. `npx @agent-native/core@latest` or `npx @agent-native/core@latest code` launches it with no prompt required, and a bare prompt starts a generic coding task directly. `/migrate` is one built-in capability for moving an existing app, URL, or described product into agent-native. It uses the same session store, transcript, and desktop hub as the CLI `code` command, so migration behaves like a goal you can resume, attach to, inspect, and stop rather than a separate one-off product.
+The full guide — input shapes (path / URL / description), `--emit` dossiers,
+Plan vs Auto mode, run controls, credentials, Desktop deep links, and the
+`@agent-native/migrate` package exports — lives in
+[Agent-Native Code UI → Migrating to Agent-Native](/docs/code-agents-ui#migrate).
 
-See [Agent-Native Code UI](/docs/code-agents-ui) for the shared CLI run controls (`list`/`attach`/`logs`/`resume`/`status`/`stop`/`ui`) and the file-backed, long-running background-run model that `/migrate` sessions use.
-
-By default `/migrate` creates a generic Agent-Native Code session plus a portable migration dossier. Migration is a slash command in the Code workspace, not a normal template to scaffold. The legacy hidden `migration` detail app has been removed; use the Code workspace, Desktop Code tab, or emitted dossier as the supported surfaces.
-
-The direct `migrate` command remains a shortcut into the same goal:
-
-```bash
-npx @agent-native/core@latest migrate ./my-next-app --out ../migrated-app
-```
-
-Both forms print the same handoff: run id, source, output, dossier directory,
-important artifact files, and the exact Agent-Native Code commands to inspect or
-resume the session (see [Agent-Native Code UI](/docs/code-agents-ui) for the
-full run-control command set).
-
-## Code Workspace
-
-`npx @agent-native/core@latest code` opens the interactive Agent-Native Code shell. Inside the shell, `/migrate` is a slash goal alongside `/audit` and other built-in commands. Projects can also define custom migration variants in `.agents/commands/*.md`. The CLI and Desktop hub share the same run store — start in one and continue in the other using the standard `list`/`attach`/`logs`/`resume`/`approve`/`stop` controls.
-
-See [Agent-Native Code UI](/docs/code-agents-ui) for the full shell, run controls, Plan/Auto modes, slash-goal discovery, and Desktop hub integration.
-
-## Input Shapes
-
-Use a local source path when you have code:
-
-```bash
-npx @agent-native/core@latest code /migrate ./my-next-app --out ../migrated-app
-```
-
-Use a URL when the first artifact is a live site or product surface:
-
-```bash
-npx @agent-native/core@latest code /migrate https://example.com --describe "marketing site plus logged-in dashboard"
-```
-
-Use a description when the migration starts from requirements, screenshots, or a handoff brief:
-
-```bash
-npx @agent-native/core@latest code /migrate --describe "A Rails admin app with reports, approvals, and CSV imports" --emit
-```
-
-For local paths, the source is read-only. Generated output must live outside the source tree.
-
-## Internal Run Flow
-
-The normal command creates a generic Agent-Native Code session and writes artifacts under the Agent-Native Code run store. It does **not** scaffold an app/template. The flow is:
-
-1. **Discover** reads the source and creates `01-assessment.md`.
-2. **Plan** creates recipe tasks and writes `02-plan.md` plus `03-tasks.md`.
-3. **Approve** unlocks generated output writes.
-4. **Sweep** runs migration tasks against the generated output project.
-5. **Verify** runs deterministic checks and writes `04-report.md`.
-
-Drive the session with the standard run controls (`status`/`list`/`attach`/`logs`/`approve`/`resume`/`ui`/`stop`, plus `--continue "prompt"` to record and run a follow-up). See [Agent-Native Code UI](/docs/code-agents-ui) for what each control does and how stop/approve behave.
-
-## Long-Running Goals
-
-The `/migrate` goal advances a run in bounded iterations:
-
-- before approval, it can assess and plan but cannot write generated output
-- after approval, it scaffolds once, advances pending tasks, verifies, and records verifier results
-- if verification fails, the critic policy returns `retry-with-more-context`, `tune-recipe`, `manual-decision-needed`, `rollback-generated-output`, or `accept`
-
-That gives the flow Claude Code `/goal`-style semantics without making migration a one-shot rewrite. The app state and disk artifacts let you resume after restarts, long pauses, or manual decisions.
-
-## Credentials
-
-The `/migrate` goal reuses the same credentials system as agent-native. There is no migration-specific key store and no `MIGRATION_*` secret namespace.
-
-In Agent-Native Code, Desktop, or the internal run surface, connect providers through the normal settings and onboarding surfaces. For headless CLI use, existing provider environment variables are detected, including `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, and other provider env vars supported by the framework. Secret values are never copied into migration artifacts.
-
-## Desktop Deep Links
-
-`/migrate` runs appear in the Desktop Agent-Native Code hub alongside any other Code session and use the same hub run controls and approval gate ([Agent-Native Code UI](/docs/code-agents-ui) covers the Desktop host and run controls). Browser/Desktop approval remains the trust gate for generated output writes.
-
-The hub handles a `/migrate` goal deep link:
-
-```text
-agentnative://open?goal=migrate&run=<runId>
-```
-
-The legacy app-style deep link still works and opens the internal run detail surface:
-
-```text
-agentnative://open?app=migration&run=<runId>
-```
-
-## Emit Mode
-
-Use `--emit` when you want Codex, Claude Code, another code agent, or Agent-Native Desktop to do the next phase without opening the internal run surface:
-
-```bash
-npx @agent-native/core@latest code /migrate ./my-next-app --emit ../migration-dossier
-```
-
-The dossier is always written outside `sourceRoot`. It includes:
-
-- `AGENTS.md` with migration-specific instructions
-- `.agents/skills/migration*/SKILL.md` when migration skills are available from the template
-- `MIGRATION_PLAYBOOK.md`
-- `01-assessment.md`
-- `ir.json` when file-level inventory is available
-
-Hand the dossier to your preferred coding agent with a prompt like:
-
-```text
-Use this migration dossier. Follow AGENTS.md and MIGRATION_PLAYBOOK.md, keep the source read-only, write the agent-native output outside the source tree, and record verification evidence before calling the migration complete.
-```
-
-When `@agent-native/migrate` helpers are installed, `--emit` uses them for Next.js assessment and IR. If they are not available, the CLI falls back to a safe local inventory pass. URL-only and description-only dossiers still include the playbook and assessment, but they do not claim file-level IR until an agent inspects source.
-
-## Instruction Packs
-
-The `/migrate` goal is driven by instruction packs instead of one source-specific path.
-
-| Pack             | What it tells the agent to do                                       |
-| ---------------- | ------------------------------------------------------------------- |
-| Source intake    | Normalize path, URL, or prose input into an assessment              |
-| Agent-native map | Convert operations to actions, SQL, app state, sharing, and SSR     |
-| Output safety    | Keep generated code outside sourceRoot and require approval gates   |
-| Verification     | Use deterministic checks and record manual gaps                     |
-| Platform exits   | Add source-specific guidance for systems such as AEM or CMS exports |
-
-Builder.io, AEM, crawls, package exports, and CMS APIs are optional instruction-pack concerns, not top-level assumptions. Builder Publish can be a target for marketing, docs, landing, and content surfaces. Transactional SaaS state, dashboards, app-owned data, and workflows stay in agent-native SQL/actions.
-
-## Agent-Native Mapping
-
-The recipes are named after the framework contracts they enforce:
-
-| Source pattern              | Agent-native target                                               |
-| --------------------------- | ----------------------------------------------------------------- |
-| API routes / server actions | `actions/`, except uploads, webhooks, OAuth, and streaming routes |
-| app-owned data              | Drizzle SQL tables plus actions                                   |
-| direct LLM calls            | agent chat delegation                                             |
-| important client state      | `application_state` navigation and selection                      |
-| UI mutations                | optimistic action mutations                                       |
-| shared resources            | ownership, sharing, and access helpers                            |
-| public pages                | server rendering                                                  |
-| logged-in workflows         | persistent client app shell                                       |
-
-This is the difference between porting React code and actually migrating to agent-native.
-
-## Package Exports
-
-`@agent-native/migrate` exposes a reusable engine for adapters and custom workflows:
-
-```ts
-import {
-  createMigrationRun,
-  discoverMigration,
-  planMigration,
-  selectSourceAdapter,
-  createSkeletonProjectIR,
-  createBrowserVerifier,
-  nextjsSourceAdapter,
-  agentNativeTargetAdapter,
-} from "@agent-native/migrate";
-```
-
-Subpath exports are available for first-party V1 adapters:
-
-```ts
-import { nextjsSourceAdapter } from "@agent-native/migrate/source-nextjs";
-import { agentNativeTargetAdapter } from "@agent-native/migrate/target-agent-native";
-```
-
-The intermediate representation is split into four graphs: site, components, content, and behavior. Verification starts with deterministic checks and can grow to Playwright, visual, accessibility, Lighthouse, SEO, and redirect checks.
+> [!NOTE]
+> The legacy hidden `migration` detail app has been removed. Use the Code
+> workspace, the Desktop Code tab, or an emitted dossier as the supported
+> surfaces.

package/docs/content/multi-app-workspace.md

@@ -5,7 +5,7 @@ description: "Host many agent-native apps in one monorepo with shared auth, RBAC
 
 # Multi-App Workspaces
 
-> For what a workspace _is_ — the customization layer, `AGENTS.md`, `LEARNINGS.md`, personal memory, skills, and custom agents — see [Workspace](/docs/workspace). This page is about the **deployment shape**: hosting many agent-native apps in one monorepo with shared auth, components, and a unified deploy.
+> **Which workspace doc?** This page covers the **deployment shape** — one monorepo, many apps, shared auth and a unified deploy. For what a workspace _is_ (the customization layer: `AGENTS.md`, `LEARNINGS.md`, personal memory, skills, custom agents) see [Workspace](/docs/workspace); for governance (who reviews, approves, and owns what) see [Workspace Governance](/docs/workspace-management).
 
 When vibe-coding an internal tool takes an afternoon, you don't stop at one. A team ends up with a CRM, a support inbox, a dashboard, an ops console — ten small apps, each scaffolded independently. That's great until you need to change something in all of them.
 

package/docs/content/multi-tenancy.md

@@ -1,67 +1,38 @@
 ---
 title: "Multi-Tenancy"
-description: "Every agent-native app is multi-tenant out of the box — organizations, team members, roles, and per-org data isolation with zero configuration."
+description: "Every agent-native app is multi-tenant out of the box — organizations, team members, roles, and per-org data isolation, with zero configuration."
 ---
 
 # Multi-Tenancy
 
-Every agent-native app is multi-tenant by default. Organizations, team members, role-based access, and per-org data isolation are built into the framework — there is nothing to configure or opt into.
+Every agent-native app is multi-tenant out of the box. Organizations, team members, role-based access, and per-org data isolation are built into the framework with zero configuration.
 
-## How it works {#how-it-works}
+## What you get for free {#free}
 
-The framework provides full multi-tenancy through its own built-in organization system — the core `org/` module backed by the `organizations` and `org_members` tables. (This is the framework's own system, not [Better Auth](https://better-auth.com)'s organization plugin, which is intentionally not registered.)
+A fresh `npx @agent-native/core@latest create` scaffold already ships with:
 
-- **Organizations** — users create organizations and invite team members. Each org is a fully isolated tenant.
-- **Roles** — every member has a role: `owner`, `admin`, or `member`. Actions can check roles for authorization.
-- **Active organization** — the session tracks which org the user is currently working in (`session.orgId`). Switching orgs changes the data they see.
-- **Data isolation** — SQL queries are automatically scoped to the active org via `org_id` columns. Data tagged with one org is invisible to users in another org, including the agent.
+- **User registration and login** — see [Authentication](/docs/authentication).
+- **Organizations** — users create orgs and invite members by email. Each org is a fully isolated tenant.
+- **Roles** — every member is an `owner`, `admin`, or `member`; actions can check the role for authorization.
+- **Org switching** — the session tracks the active org (`session.orgId`), and switching it changes the data the user and agent see.
+- **Per-org data isolation** — every query is automatically scoped to the active org.
 
-All first-party templates are multi-tenant out of the box. See [Cloneable SaaS templates](/docs/cloneable-saas) for the full list.
+If you're evaluating agent-native for a CRM, project tracker, support inbox, or any team tool, the multi-tenant foundation is already there. All first-party templates are multi-tenant — see [Cloneable SaaS templates](/docs/cloneable-saas) for the list.
 
-## Organizations and members {#organizations-and-members}
+## The org switcher UI {#org-switcher}
 
-Users can create organizations, invite members by email, and assign roles. The org-switcher and members UI drive this through the core org REST routes (no template code required):
+The org-switcher and members UI render in every template with no extra code. They drive the core org REST routes under `/_agent-native/org/*` (create org, switch org, list/invite/remove members, change roles, set allowed email domain). Users pick the active org from the switcher; the members panel handles invitations and role changes.
 
-```text
-POST /_agent-native/org              # create an organization
-POST /_agent-native/org/invitations  # invite a member by email
-```
+This is the framework's own `org/` module, not Better Auth's organization plugin (which is intentionally not registered). The full org-management surface — `createOrganization`, the REST routes, and template-authored `defineAction` wrappers like `invite-member` — is documented in [Authentication → Organizations](/docs/authentication#organizations).
 
-Server code can call the same surface directly through the `org/` module. `createOrganization(name, email, role?)` creates an org and adds the caller as a member; membership and roles live in the `org_members` table:
+## How isolation works {#isolation}
 
-```typescript
-import { createOrganization } from "@agent-native/core/org";
+Tenant data is isolated by an `org_id` column (added by `ownableColumns()`), and the framework scopes every query to the active org automatically: `session.orgId → AGENT_ORG_ID → SQL`. When a user switches organizations, the UI, actions, and agent all see only that org's data — the agent cannot reach data for an org the user isn't a member of.
 
-// Creating an org adds the caller (email) as a member with the given role
-const org = await createOrganization(
-  "Acme Inc",
-  "alice@acme.com",
-  "owner", // "owner" | "admin" | "member", defaults to "owner"
-);
-```
-
-Org management is a **framework built-in**: the core org plugin auto-mounts REST routes under `/_agent-native/org/*` (create org, switch org, list/invite/remove members, change roles, set allowed email domain), and these back the org-switcher and members UI in every template with no extra code. Agent-callable actions with names like `create-organization` or `invite-member` are **template-authored** on top of this surface, not built-in tools — a template wires its own `defineAction` wrappers when it wants the agent to manage its specific membership model.
-
-## Data scoping {#data-scoping}
-
-Tenant data is isolated by an `org_id` column (added by `ownableColumns()`), and the framework scopes every query to the active org automatically — `session.orgId → AGENT_ORG_ID → SQL`. When a user switches organizations, the UI, actions, and agent all see only that org's data; the agent cannot reach data for an org the user isn't a member of.
-
-This is the same pipeline used for per-user scoping. For the SQL-level mechanics, the `ownableColumns()` contract, and the `accessFilter` / `resolveAccess` / `assertAccess` guards, see [Security & Data Scoping](/docs/security#data-scoping).
-
-## No configuration needed {#zero-config}
-
-Multi-tenancy is not a feature you enable — it's the default architecture. A fresh `npx @agent-native/core@latest create` scaffold already has:
-
-- User registration and login
-- Organization creation and management
-- Member invitations with role assignment
-- Per-org data isolation
-- Org switching in the UI
-
-If you're evaluating agent-native for a product like a CRM, project tracker, support inbox, or any team tool — the multi-tenant foundation is already there.
+This is the same pipeline used for per-user scoping. For the SQL-level mechanics, the `ownableColumns()` contract, and the `accessFilter` / `resolveAccess` / `assertAccess` guards, see [Security → Data Scoping](/docs/security#data-scoping) — the single source of truth for the scoping pipeline.
 
 ## Related docs {#related}
 
-- [Authentication](/docs/authentication) — auth modes, social providers, session API
-- [Security & Data Scoping](/docs/security) — SQL-level isolation, input validation, access guards
+- [Authentication](/docs/authentication#organizations) — sessions, social providers, and the org-management surface
+- [Security → Data Scoping](/docs/security#data-scoping) — SQL-level isolation, the `ownableColumns()` contract, and access guards
 - [Multi-App Workspace](/docs/multi-app-workspace) — hosting multiple agent-native apps in one monorepo with shared auth and RBAC

package/docs/content/native-chat-ui.md

@@ -190,15 +190,18 @@ arbitrary query execution behind typed read actions rather than raw SQL in chat.
 
 ## BYO agent runtimes {#byo-agent-runtimes}
 
-`AgentChatRuntime` is the bring-your-own-agent contract for the chat shell. It
-lets an agent you built elsewhere stream normalized events into Agent-Native's
-conversation UI while keeping the shared composer, transcript rendering, tool
-cards, approvals, native widgets, and surrounding app layout. For how this fits
-with headless actions, embedded sidecars, and full applications, see
-[Agent Surfaces](/docs/agent-surfaces).
-
-Use the generic HTTP runtime when your agent can expose a POST endpoint that
-returns SSE or NDJSON runtime events:
+`AgentChatRuntime` is the bring-your-own-agent contract for the chat shell, and
+this section is its canonical reference. It lets an agent you built elsewhere
+stream normalized events into Agent-Native's conversation UI while keeping the
+shared composer, transcript rendering, tool cards, approvals, native widgets,
+and surrounding app layout. The [Drop-in Agent](/docs/drop-in-agent#custom-chat-ui)
+tutorial points here for the runtime story, and [Component API](/docs/components#agent-chat-ui)
+lists each connector and adapter with its import path; the contract itself is
+described below.
+
+All connectors are exported from `@agent-native/core/client/chat` (and the root
+`@agent-native/core/client` entry). Use the generic HTTP runtime when your agent
+can expose a POST endpoint that returns SSE or NDJSON runtime events:
 
 ```tsx
 import {
@@ -255,7 +258,7 @@ const agUiRuntime = createAgUiChatRuntime({
 
 The endpoint may stream the normalized event shape directly:
 
-```txt
+```text
 data: {"type":"message-start","message":{"id":"m1","role":"assistant","content":[]}}
 data: {"type":"message-delta","messageId":"m1","delta":{"type":"text","text":"Hello"}}
 data: {"type":"tool-start","toolCall":{"id":"t1","name":"query","input":{"q":"forms"}}}
@@ -295,7 +298,7 @@ if it matures, it should adapt into this same explicit runtime/widget contract.
 
 - [Actions](/docs/actions) — define the operations that return native widget data.
 - [Agent Surfaces](/docs/agent-surfaces) — decide whether you need headless, chat, sidecar, or full app.
-- [Drop-in Agent](/docs/drop-in-agent) — mount the standard chat runtime.
-- [Component API](/docs/components) — custom chat layers and tool renderers.
+- [Drop-in Agent](/docs/drop-in-agent) — the tutorial for mounting the standard chat runtime.
+- [Component API](/docs/components) — the per-export API map for chat layers, runtimes, and tool renderers.
 - [MCP Apps](/docs/mcp-apps) — inline UI for external MCP hosts.
 - [Key Concepts](/docs/key-concepts#protocols) — protocol status and positioning.

package/docs/content/observability.md

@@ -9,6 +9,18 @@ Every agent-native app gets observability out of the box. Traces, automated eval
 
 This page covers _agent quality_ metrics: traces, cost, evals, and feedback stored in your database. For _product_ analytics (your app's events flowing to PostHog/Mixpanel/Amplitude), see [Tracking](/docs/tracking).
 
+## Three things called "evals"/"observability" — which do I want? {#which}
+
+These three pages are easy to confuse. Pick by the question you're asking:
+
+| Page                                                   | The question it answers                                    | When it runs                                 | Concern        |
+| ------------------------------------------------------ | ---------------------------------------------------------- | -------------------------------------------- | -------------- |
+| **Observability evals** (this page, the _Evals_ tab)   | "How did my real production runs do?"                      | Passive, after every run (LLM-judge sampled) | Quality        |
+| **[CI Eval Gate](/docs/evals)** (`*.eval.ts`)          | "Does the agent do the right thing on this fixed input?"   | Active, deterministic, a CI/deploy gate      | Quality        |
+| **[Observational Memory](/docs/observational-memory)** | "Is this long thread staying cheap and inside the window?" | Background compaction on long threads        | Cost / context |
+
+Observability and the CI Eval Gate both score _quality_ but from opposite ends — passive post-hoc scoring of real traffic vs. active pass/fail checks on fixed inputs. Observational Memory is unrelated to quality; it's about token cost and context-window pressure.
+
 ## What's captured automatically {#captured}
 
 When a user sends a message, the framework automatically records:
@@ -113,10 +125,10 @@ Test different models, temperatures, or agent configurations:
 // Create via API
 POST /_agent-native/observability/experiments
 {
-  "name": "sonnet-vs-haiku",
+  "name": "model-a-vs-b",
   "variants": [
-    { "id": "control", "weight": 50, "config": { "model": "claude-sonnet-4-6" } },
-    { "id": "treatment", "weight": 50, "config": { "model": "claude-haiku-4-5-20251001" } }
+    { "id": "control", "weight": 50, "config": { "model": "<your-model-id>" } },
+    { "id": "treatment", "weight": 50, "config": { "model": "<other-model-id>" } }
   ],
   "metrics": ["cost", "latency", "satisfaction"]
 }
@@ -126,7 +138,7 @@ PUT /_agent-native/observability/experiments/:id
 { "status": "running" }
 ```
 
-The agent loop automatically resolves the user's variant and applies the config override. Assignment uses consistent hashing — same user always gets the same variant.
+Use the real model identifiers your engine accepts in place of `<your-model-id>` / `<other-model-id>` (model names change often — check your provider/engine for the current ids). The agent loop automatically resolves the user's variant and applies the config override. Assignment uses consistent hashing — same user always gets the same variant.
 
 ## Configuration {#config}
 

package/docs/content/observational-memory.md

@@ -58,6 +58,6 @@ The injection is best-effort and boundary-safe — if a safe trim point can't be
 
 ## Related
 
-- [**Context X-Ray**](/docs/using-your-agent) — inspect what's actually in the live context window.
+- [**Using Your Agent**](/docs/using-your-agent) — the day-to-day loop of working with the agent docked next to your app.
 - [**Observability**](/docs/observability) — token and cost metrics per run, where OM's savings show up.
 - [**Custom Agents & Teams**](/docs/agent-teams) — long sub-agent runs benefit from the same compaction.