@agent-native/core 0.63.0 → 0.63.2

package/dist/tailwind.preset.js.map

@@ -1 +1 @@
-{"version":3,"file":"tailwind.preset.js","sourceRoot":"","sources":["../src/tailwind.preset.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Config } from \"tailwindcss\";\n\n/**\n * @deprecated Legacy Tailwind v3 preset.\n *\n * The framework has moved to Tailwind v4. Templates should now use the shared\n * stylesheet from CSS instead of a `tailwind.config.ts`:\n *\n *   // app/global.css\n *   @import \"tailwindcss\";\n *   @import \"@agent-native/core/styles/agent-native.css\";\n *\n * No `tailwind.config.ts` or `postcss.config.js` is needed. The\n * `@tailwindcss/vite` plugin is auto-injected by `defineConfig()`.\n *\n * This export is kept only for third-party templates still on the v3 PostCSS pipeline.\n */\nimport { join, dirname } from \"path\";\nimport { fileURLToPath } from \"url\";\n\n// Scan @agent-native/core's dist/client for Tailwind classes used in\n// core components (AgentPanel, AssistantChat, etc.)\nconst thisDir =\n  typeof __dirname !== \"undefined\"\n    ? __dirname\n    : dirname(fileURLToPath(import.meta.url));\n\n/**\n * Glob pattern that matches all core client component files.\n * Templates MUST include this in their `content` array — Tailwind v3\n * does NOT merge `content` from presets, so the preset alone isn't enough.\n *\n * Usage:\n *   import preset, { coreContentGlob } from \"@agent-native/core/tailwind\";\n *   export default { presets: [preset], content: [\"./app/**\\/*.{ts,tsx}\", coreContentGlob] };\n */\nexport const coreContentGlob = join(thisDir, \"client\", \"**/*.{js,mjs}\");\n\n// Cast to `any` for the inner config — Tailwind v4 ships stricter Config types\n// than v3 (e.g. `darkMode: [\"class\"]` is v3-only). This file exists only to\n// keep third-party v3 setups working until they migrate.\nconst preset = {\n  darkMode: [\"class\"],\n  content: [coreContentGlob],\n  prefix: \"\",\n  theme: {\n    container: {\n      center: true,\n      padding: \"2rem\",\n      screens: {\n        \"2xl\": \"1400px\",\n      },\n    },\n    extend: {\n      colors: {\n        border: \"hsl(var(--border))\",\n        input: \"hsl(var(--input))\",\n        ring: \"hsl(var(--ring))\",\n        background: \"hsl(var(--background))\",\n        foreground: \"hsl(var(--foreground))\",\n        primary: {\n          DEFAULT: \"hsl(var(--primary))\",\n          foreground: \"hsl(var(--primary-foreground))\",\n        },\n        secondary: {\n          DEFAULT: \"hsl(var(--secondary))\",\n          foreground: \"hsl(var(--secondary-foreground))\",\n        },\n        destructive: {\n          DEFAULT: \"hsl(var(--destructive))\",\n          foreground: \"hsl(var(--destructive-foreground))\",\n        },\n        muted: {\n          DEFAULT: \"hsl(var(--muted))\",\n          foreground: \"hsl(var(--muted-foreground))\",\n        },\n        accent: {\n          DEFAULT: \"hsl(var(--accent))\",\n          foreground: \"hsl(var(--accent-foreground))\",\n        },\n        popover: {\n          DEFAULT: \"hsl(var(--popover))\",\n          foreground: \"hsl(var(--popover-foreground))\",\n        },\n        card: {\n          DEFAULT: \"hsl(var(--card))\",\n          foreground: \"hsl(var(--card-foreground))\",\n        },\n        sidebar: {\n          DEFAULT: \"hsl(var(--sidebar-background))\",\n          foreground: \"hsl(var(--sidebar-foreground))\",\n          primary: \"hsl(var(--sidebar-primary))\",\n          \"primary-foreground\": \"hsl(var(--sidebar-primary-foreground))\",\n          accent: \"hsl(var(--sidebar-accent))\",\n          \"accent-foreground\": \"hsl(var(--sidebar-accent-foreground))\",\n          border: \"hsl(var(--sidebar-border))\",\n          ring: \"hsl(var(--sidebar-ring))\",\n        },\n      },\n      borderRadius: {\n        lg: \"var(--radius)\",\n        md: \"calc(var(--radius) - 2px)\",\n        sm: \"calc(var(--radius) - 4px)\",\n      },\n      keyframes: {\n        \"accordion-down\": {\n          from: { height: \"0\" },\n          to: { height: \"var(--radix-accordion-content-height)\" },\n        },\n        \"accordion-up\": {\n          from: { height: \"var(--radix-accordion-content-height)\" },\n          to: { height: \"0\" },\n        },\n      },\n      animation: {\n        \"accordion-down\": \"accordion-down 0.2s ease-out\",\n        \"accordion-up\": \"accordion-up 0.2s ease-out\",\n      },\n    },\n  },\n  plugins: [\n    // tailwindcss-animate is v3-only and is no longer a peer dep — guard the require.\n    (() => {\n      try {\n        return require(\"tailwindcss-animate\");\n      } catch {\n        return null;\n      }\n    })(),\n    require(\"@tailwindcss/typography\"),\n  ].filter(Boolean),\n};\n\nexport default preset as unknown as Config;\n"]}
+{"version":3,"file":"tailwind.preset.js","sourceRoot":"","sources":["../src/tailwind.preset.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Config } from \"tailwindcss\";\n\n/**\n * @deprecated Legacy Tailwind v3 preset.\n *\n * The framework has moved to Tailwind v4. Templates should now use the shared\n * stylesheet from CSS instead of a `tailwind.config.ts`:\n *\n *   // app/global.css\n *   @import \"tailwindcss\";\n *   @import \"@agent-native/core/styles/agent-native.css\";\n *\n * No `tailwind.config.ts` or `postcss.config.js` is needed. The\n * `@tailwindcss/vite` plugin is auto-injected by `defineConfig()`.\n *\n * This export is kept only for third-party templates still on the v3 PostCSS pipeline.\n */\nimport { join, dirname } from \"path\";\nimport { fileURLToPath } from \"url\";\n\n// Scan @agent-native/core's dist/client for Tailwind classes used in\n// core components (AgentPanel, AssistantChat, etc.)\nconst thisDir =\n  typeof __dirname !== \"undefined\"\n    ? __dirname\n    : dirname(fileURLToPath(import.meta.url));\n\n/**\n * Glob pattern that matches all core client component files.\n * Templates MUST include this in their `content` array — Tailwind v3\n * does NOT merge `content` from presets, so the preset alone isn't enough.\n *\n * Usage:\n *   import preset, { coreContentGlob } from \"@agent-native/core/tailwind\";\n *   export default { presets: [preset], content: [\"./app/**\\/*.{ts,tsx}\", coreContentGlob] };\n */\nexport const coreContentGlob = join(thisDir, \"client\", \"**/*.{js,mjs}\");\n\n// Cast to `any` for the inner config — Tailwind v4 ships stricter Config types\n// than v3 (e.g. `darkMode: [\"class\"]` is v3-only). This file exists only to\n// keep third-party v3 setups working until they migrate.\nconst preset = {\n  darkMode: [\"class\"],\n  content: [coreContentGlob],\n  prefix: \"\",\n  theme: {\n    container: {\n      center: true,\n      padding: \"2rem\",\n      screens: {\n        \"2xl\": \"1400px\",\n      },\n    },\n    extend: {\n      colors: {\n        border: \"hsl(var(--border))\",\n        input: \"hsl(var(--input))\",\n        ring: \"hsl(var(--ring))\",\n        background: \"hsl(var(--background))\",\n        foreground: \"hsl(var(--foreground))\",\n        primary: {\n          DEFAULT: \"hsl(var(--primary))\",\n          foreground: \"hsl(var(--primary-foreground))\",\n        },\n        secondary: {\n          DEFAULT: \"hsl(var(--secondary))\",\n          foreground: \"hsl(var(--secondary-foreground))\",\n        },\n        destructive: {\n          DEFAULT: \"hsl(var(--destructive))\",\n          foreground: \"hsl(var(--destructive-foreground))\",\n        },\n        muted: {\n          DEFAULT: \"hsl(var(--muted))\",\n          foreground: \"hsl(var(--muted-foreground))\",\n        },\n        accent: {\n          DEFAULT: \"hsl(var(--accent))\",\n          foreground: \"hsl(var(--accent-foreground))\",\n        },\n        popover: {\n          DEFAULT: \"hsl(var(--popover))\",\n          foreground: \"hsl(var(--popover-foreground))\",\n        },\n        card: {\n          DEFAULT: \"hsl(var(--card))\",\n          foreground: \"hsl(var(--card-foreground))\",\n        },\n        sidebar: {\n          DEFAULT: \"hsl(var(--sidebar-background))\",\n          foreground: \"hsl(var(--sidebar-foreground))\",\n          primary: \"hsl(var(--sidebar-primary))\",\n          \"primary-foreground\": \"hsl(var(--sidebar-primary-foreground))\",\n          accent: \"hsl(var(--sidebar-accent))\",\n          \"accent-foreground\": \"hsl(var(--sidebar-accent-foreground))\",\n          border: \"hsl(var(--sidebar-border))\",\n          ring: \"hsl(var(--sidebar-ring))\",\n        },\n      },\n      borderRadius: {\n        lg: \"var(--radius)\",\n        md: \"calc(var(--radius) - 2px)\",\n        sm: \"calc(var(--radius) - 4px)\",\n      },\n      keyframes: {\n        \"accordion-down\": {\n          from: { height: \"0\" },\n          to: { height: \"var(--radix-accordion-content-height)\" },\n        },\n        \"accordion-up\": {\n          from: { height: \"var(--radix-accordion-content-height)\" },\n          to: { height: \"0\" },\n        },\n      },\n      animation: {\n        \"accordion-down\": \"accordion-down 0.2s ease-out\",\n        \"accordion-up\": \"accordion-up 0.2s ease-out\",\n      },\n    },\n  },\n  plugins: [\n    // tailwindcss-animate is v3-only and is no longer a peer dep — guard the require.\n    (() => {\n      try {\n        return require(\"tailwindcss-animate\");\n      } catch {\n        return null;\n      }\n    })(),\n    (() => {\n      try {\n        return require(\"@tailwindcss/typography\");\n      } catch {\n        return null;\n      }\n    })(),\n  ].filter(Boolean),\n};\n\nexport default preset as unknown as Config;\n"]}

package/dist/templates/default/package.json

@@ -24,6 +24,7 @@
   "devDependencies": {
     "@react-router/dev": "^7.16.0",
     "@react-router/fs-routes": "^7.16.0",
+    "@tailwindcss/typography": "^0.5.20",
     "@tailwindcss/vite": "^4.1.18",
     "@tanstack/react-query": "^5.99.2",
     "@types/node": "^24.2.1",

package/dist/templates/headless/AGENTS.md

@@ -9,6 +9,9 @@ This app is not stateless. The Agent Native runtime uses SQL-backed stores for a
 - Prefer actions in `actions/` for every app operation. Do not create REST wrappers around actions.
 - Keep action inputs validated with Zod and return structured data, not JSON strings.
 - Do not hardcode API keys, tokens, webhook URLs, private data, or credential-looking literals.
+- `actions/run.ts` is the CLI dispatcher for `pnpm action ...`, not an app
+  action. Leave it in place and add callable primitives as separate
+  `actions/<name>.ts` files.
 - There is intentionally no `app/` UI shell in this scaffold. When you need a browser UI, use the Chat template as the UI on-ramp and keep `agent-native add` for integration blueprints.
 
 ## Framework Docs Lookup

package/dist/templates/headless/DEVELOPING.md

@@ -7,6 +7,10 @@ pnpm install
 pnpm action hello --name Builder
 ```
 
+`actions/run.ts` is only the shared CLI dispatcher that powers
+`pnpm action <name>`. Add real agent-callable actions as separate files such as
+`actions/hello.ts`.
+
 Then run the production app-agent loop against this folder:
 
 ```bash

package/dist/templates/headless/actions/run.ts

@@ -1,3 +1,9 @@
+/**
+ * CLI dispatcher for `pnpm action ...`.
+ *
+ * This file lives in actions/ so the Agent Native CLI can find it. It is skipped
+ * by action discovery and is not exposed as an agent tool.
+ */
 import { runScript } from "@agent-native/core/scripts";
 
 runScript();

package/dist/templates/workspace-root/README.md

@@ -103,15 +103,15 @@ authenticated org routes whenever possible.
 pnpm exec agent-native create crm --template=chat
 ```
 
-The CLI detects the workspace root and scaffolds a minimal chat app that already
+The CLI detects the workspace root and scaffolds a minimal starter app that already
 depends on `@{{APP_NAME}}/shared`. Edit only the routes you care about;
 auth, org switching, skills, and instructions come from the shared package.
-Chat is only the source scaffold: the finished app should use its own name,
+The source template is only a scaffold: the finished app should use its own name,
 home screen, navigation, package metadata, and manifest rather than leaving
-chat or new-app UI in place.
+starter or new-app UI in place.
 If the request starts from Dispatch in production, Dispatch sends it to Builder
 branch creation; that branch should still add a new `apps/<app-id>` workspace
-app rather than adding files to `apps/chat`.
+app rather than editing an existing app directory.
 Dispatch discovers ready apps from `apps/<app-id>/package.json`; there is no
 separate workspace app registry to edit. React Router apps must preserve
 `APP_BASE_PATH` / `VITE_APP_BASE_PATH` in `app/entry.client.tsx` via

package/docs/content/actions.md

@@ -19,6 +19,10 @@ One definition, seven consumers. This is rung 3 of the [ladder](/docs/what-is-ag
 If you are deciding whether to expose an operation headlessly, in chat, in an
 embedded sidecar, or as a full app screen, see [Agent Surfaces](/docs/agent-surfaces).
 
+If the UI and agent both need to do something, reach for an action — not a custom
+route. For when a route-shaped protocol _is_ the right call, see [Prefer Actions
+For App Operations](/docs/server#actions-first).
+
 ## Start with one action {#hello-action}
 
 The primitive-first on-ramp is one action, not a template. In a headless
@@ -154,9 +158,22 @@ Every action the agent can see is a tool in the model's context window, and a lo
 
 A repo-level advisory helper, `node scripts/audit-template-actions.mjs [template ...]` (alias `pnpm actions:audit`), statically scans a template's `actions/` and flags likely UI-dead actions and redundant per-field clusters. It is advisory only (always exits 0, never fails CI) and uses conservative heuristics, so review its suggestions rather than treating them as errors.
 
-### Agent tool exposure {#agent-tool}
+### Exposure flags {#exposure-flags}
+
+Four flags control _who_ can invoke an action. All default to the permissive value, so you only set one to tighten a specific surface. This table is the glanceable summary; the subsections add the one detail each needs.
+
+| Flag            | Default       | Restrictive value → who can still call                                      | Typical use                                                     |
+| --------------- | ------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `agentTool`     | `true`        | `false` → UI, HTTP, CLI only — **hidden from the model**, MCP, and A2A      | UI-only / programmatic actions that shouldn't spend a tool slot |
+| `toolCallable`  | `true`        | `false` → everything **except** the sandboxed extension iframe bridge (403) | Auth-adjacent ops (delete account, change org membership/roles) |
+| `publicAgent`   | off (private) | `{ expose: true }` → adds the action to **public** MCP/A2A/OpenAPI surfaces | Safe read/ingest tools reachable without authentication         |
+| `needsApproval` | `false`       | `true` → the agent **pauses**; a human must approve the specific call       | Consequential side effects (send email, charge a card, delete)  |
 
-By default every action is exposed to the agent — the in-app assistant plus the app's MCP / A2A tool surfaces — as a callable tool. For an action that only the frontend (or an HTTP / cron caller) needs, set `agentTool: false` to keep it behind the framework's auth + action surface while removing it from every agent tool list:
+These are independent: `agentTool` controls the model's view, `toolCallable` controls only the extension iframe, `publicAgent` adds an opt-in public surface (public web routes never imply public tool exposure), and `needsApproval` gates execution after the call is made — see [Human-in-the-loop approval](#needs-approval) below.
+
+#### `agentTool` — hide from the model {#agent-tool}
+
+By default every action is a callable agent tool. Set `agentTool: false` to keep it behind the framework's auth + action surface while removing it from every agent tool list — it stays callable from the UI (`useActionMutation` / `callAction`), CLI, and `/_agent-native/actions/<name>`:
 
 ```ts
 export default defineAction({
@@ -170,24 +187,11 @@ export default defineAction({
 });
 ```
 
-| Value       | Behavior                                                                                                                                                                                   |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `true`      | Allow (same as undefined). Useful for documenting intent.                                                                                                                                  |
-| `false`     | **Hidden from the model entirely** — not in the agent's tool list, MCP, or A2A. Still callable from the UI (`useActionMutation` / `callAction`), CLI, and `/_agent-native/actions/<name>`. |
-| `undefined` | **Default-allow.** The action is a normal agent tool.                                                                                                                                      |
-
-`agentTool: false` is **not** the same as [`toolCallable: false`](#tool-callable):
+Reach for it when you add a UI-only or purely programmatic action, or when the UI stops using an action you'd otherwise leave exposed to the model.
 
-- **`agentTool: false`** removes the action from the **model's** view. The model can no longer see or call it; the UI and HTTP can.
-- **`toolCallable: false`** only blocks the sandboxed **extension iframe bridge** (`appAction(...)`). The action stays fully visible to the model, UI, CLI, MCP, and A2A. It exists for high-blast-radius operations (account/org/auth changes), not for trimming the tool list.
+#### `toolCallable` — block the extension iframe {#tool-callable}
 
-Reach for `agentTool: false` when you find yourself adding a UI-only or purely programmatic action, or when the UI stops using an action you'd otherwise leave exposed to the model.
-
-### Extension callability {#tool-callable}
-
-Extensions (Alpine.js mini-apps that run inside sandboxed iframes — see [Extensions](/docs/extensions)) call actions via `appAction(name, params)`. Because a shared extension's HTML/JS executes inside the _viewer's_ session, an action invoked from an extension runs with the viewer's permissions, secrets, and SQL scope. For high-blast-radius operations, that is too much trust to grant by default.
-
-Use the `toolCallable` flag to control this (the flag name is kept for backward compatibility — it gates extension iframe callability):
+Extensions ([Alpine.js mini-apps in sandboxed iframes](/docs/extensions)) call actions via `appAction(name, params)`, running with the _viewer's_ permissions, secrets, and SQL scope. For high-blast-radius operations that is too much trust by default. Set `toolCallable: false` to make the extension bridge return 403 while keeping the action callable from the UI, agent, CLI, MCP, and A2A:
 
 ```ts
 export default defineAction({
@@ -200,20 +204,7 @@ export default defineAction({
 });
 ```
 
-| Value       | Behavior                                                                                                                                                                                                                                          |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `true`      | Allow (same as undefined). Useful for documentation of intent.                                                                                                                                                                                    |
-| `false`     | Explicit deny. The extension bridge returns 403; the action is still callable normally from the UI, agent, CLI, MCP, and A2A.                                                                                                                     |
-| `undefined` | **Default-allow.** Extensions are intra-org and typically authored by trusted teammates, so the default trusts the org-level access controls. Set `false` only for genuinely auth-adjacent operations (account deletion, org membership changes). |
-
-Enforcement: the parent host tags every outbound action call from an extension iframe with the header `X-Agent-Native-Tool-Bridge: 1`. The action route layer reads this header and applies the rule above. Regular UI/agent/CLI/A2A calls do not carry the header and are unaffected. The header is set by the React host; the iframe's user-authored content cannot spoof it because the bridge sanitizes iframe-supplied headers.
-
-Set `toolCallable: false` for actions that:
-
-- delete or transfer ownership of any account/org,
-- change auth state (sign-out-all sessions, rotate tokens),
-- modify org membership (invite/remove members, change roles),
-- change resource visibility or grant share access (the framework's built-in `share-resource`, `unshare-resource`, and `set-resource-visibility` are already opted out).
+Use it for actions that delete or transfer accounts/orgs, change auth state, modify org membership, or grant share access. The framework's built-in `share-resource`, `unshare-resource`, and `set-resource-visibility` are already opted out. Enforcement is by an unspoofable host-set header on iframe calls; regular UI/agent/CLI/MCP/A2A calls are unaffected — see [Security](/docs/security) for details.
 
 ### Run context (second argument) {#run-context}
 
@@ -307,10 +298,10 @@ export default defineAction({
 });
 ```
 
-`needsApproval` accepts a boolean or a predicate `(args, ctx) => boolean | Promise<boolean>` to gate conditionally (e.g. only external recipients, only above a threshold). The predicate **fails closed**: a throw is treated as "approval required". When the gate is truthy and the call isn't yet approved, the loop emits an `approval_required` event and stops the turn — the side effect never happens — and the action runs only once a human approves via the chat UI's Approve affordance.
+`needsApproval` also accepts a predicate `(args, ctx) => boolean | Promise<boolean>` to gate conditionally (e.g. only external recipients, only above a threshold); it **fails closed**, so a throw counts as "approval required". When the gate is truthy and unapproved, the loop stops the turn and the side effect never fires until a human approves in the chat UI.
 
 > [!WARNING]
-> Keep approvals rare. Each gated action is a hard stop in the agent loop. The default is **off**, and almost every action should leave it off. See [Human-in-the-Loop Approvals](/docs/human-approval) for the full flow.
+> Keep approvals rare. Each gated action is a hard stop in the agent loop. The default is **off**, and almost every action should leave it off. See [Human-in-the-Loop Approvals](/docs/human-approval) for the predicate API, the `approval_required` event, and the full flow.
 
 ## Calling it from the UI {#ui}
 
@@ -394,12 +385,11 @@ export default defineAction({
 ```
 
 The built-in discriminants are `"data-table"`, `"data-chart"`, and
-`"data-insights"`. Their server-safe builders and schemas are exported from
-`@agent-native/core/data-widgets`, and native renderer ids are exported from
-`@agent-native/core`. See [Native Chat UI](/docs/native-chat-ui) for the full
-result contract and BYO runtime guidance, or [Agent Surfaces](/docs/agent-surfaces)
-for how this same action can stay headless, render in chat, or grow into a full
-screen.
+`"data-insights"`, with server-safe builders and schemas in
+`@agent-native/core/data-widgets`. See [Native Chat UI](/docs/native-chat-ui)
+for the full result contract and BYO runtime guidance, or
+[Agent Surfaces](/docs/agent-surfaces) for how the same action can stay
+headless, render in chat, or grow into a full screen.
 
 ## Calling it from the CLI {#cli}
 
@@ -417,9 +407,9 @@ If your app is an [A2A](/docs/a2a-protocol) peer, other agent-native apps discov
 
 ## Exposing it over MCP {#mcp}
 
-With MCP enabled, your actions show up in the framework's MCP server at `/_agent-native/mcp`. Every caller gets a compact catalog by default — code/stdio developer clients, the local CLI proxy, and chat-style app hosts (OAuth MCP Apps callers and generic authenticated remote HTTP/static-token callers) alike — containing app-facing builtins (`open_app`, `list_apps`, `ask_app`, and app-only embed helpers) plus the template-declared app actions; action-specific MCP App resources stay out of that catalog unless an action explicitly sets `mcpApp.compactCatalog: true`. `tool-search` is always present (call it with no query for the full tool menu, or with a query for ranked matches), so any tool stays reachable on demand. The full action surface is served only on explicit opt-in (`--full-catalog` token or `AGENT_NATIVE_MCP_FULL_CATALOG=1`). `publicAgent.expose` is still the opt-in for safe read/ingest tools outside that compact app catalog. See [MCP Protocol](/docs/mcp-protocol).
+With MCP enabled, your actions show up in the framework's MCP server at `/_agent-native/mcp`. Every caller gets a compact catalog by default — app-facing builtins plus the template-declared app actions — and `tool-search` is always present so any other tool stays reachable on demand. The full action surface is served only on explicit opt-in (`--full-catalog` token or `AGENT_NATIVE_MCP_FULL_CATALOG=1`), and `publicAgent.expose` opts a safe read/ingest tool onto the public surface. See [MCP Protocol](/docs/mcp-protocol) for catalog tiers, auth, and the `mcpApp` resource details.
 
-For UI-capable MCP hosts, an action can also declare an optional MCP Apps resource via the `mcpApp` field (and a matching `link`) so capable hosts render the result inline. The pattern mirrors the focused link we already return for external agents: the action exposes the operation, `link` points at the route with the right URL or deep-link params, and the embed helper uses that same target as the inline app. When an action's `link` and `mcpApp` should point at the same route, use `embedRoute()` to build both from one pure path builder.
+For UI-capable MCP hosts, an action can declare an optional MCP Apps resource via the `mcpApp` field (plus a matching `link`) so capable hosts render the result inline. When `link` and `mcpApp` should point at the same route, `embedRoute()` builds both from one pure path builder:
 
 ```ts
 import { embedRoute } from "@agent-native/core";

package/docs/content/agent-surfaces.md

@@ -15,23 +15,60 @@ you want, then use the matching primitive.
 
 | Surface                       | Use it when                                                                                                 | Start with                                                                                  |
 | ----------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| **Headless agent/actions**    | Code, jobs, scripts, another app, or another agent should call the work directly.                           | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A |
+| **Headless agent**            | Code, jobs, scripts, another app, or another agent should call the work directly.                           | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A |
 | **Rich chat on Agent-Native** | You want a standalone or embedded chat backed by the built-in agent loop.                                   | [Chat template](/docs/template-chat), `<AgentChatSurface>`, `<AssistantChat>`               |
 | **Rich chat on your agent**   | You built the agent elsewhere and want Agent-Native's composer, transcript, tool cards, and native widgets. | `AgentChatRuntime`, `<AssistantChat runtime={runtime}>`                                     |
 | **Embedded sidecar**          | You already have a SaaS app and want an agent beside it with page context and host commands.                | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded`                                  |
 | **Full application**          | Humans and agents should share durable screens, data, navigation, and collaboration.                        | Templates, actions, SQL state, context awareness                                            |
 
 Those are stages, not separate products. A workflow can start as a headless
-action, appear in chat as a table or chart, and later become a full screen in an
-app without changing the operation the agent calls.
+agent with one action, appear in chat as a table or chart, and later become a
+full screen in an app without changing the operation the agent calls.
 
-## Headless agent/actions {#headless}
+## Headless agent {#headless}
 
 Use the headless path when no one needs to stare at a custom app screen while
 the work runs: scheduled jobs, integrations, backend workflows, CLI loops,
 another agent, or an existing product calling into Agent-Native.
 
-The smallest local path is a headless scaffold plus one action:
+This is also the shape to reach for when **the agent _is_ the product** — the
+app-agent loop is the front door, not a dashboard. You send a request from the
+terminal, Slack, email, a scheduled job, another agent, or Chat — "summarize my
+unread emails," "post the daily metrics to Slack," "find the candidates who
+replied last week" — and the agent acts and returns the result wherever it
+belongs. It is still a real app, not a stateless prompt: actions, auth sessions,
+app state, thread/run history, settings, credentials, and share records all live
+in SQL.
+
+Pick this pattern when:
+
+- **The work happens in the background.** Most of the value is created while the user isn't looking — triage agents, daily-report agents, on-call responders.
+- **The output leaves the app.** The agent posts to Slack, sends email, or updates a third-party system; there's nothing to browse in-app.
+- **The domain is one-shot.** Research bot, summary generator, report writer — no persistent object that needs a list view.
+- **You're prototyping.** Ship the agent now; add richer UI later if users want one.
+
+If your product is built around persistent objects users browse, pivot, and
+share — emails, events, documents, charts — pick a [full application](#full-application)
+or a [template](/docs/cloneable-saas) instead; those add a full UI _plus_ the agent.
+
+### What ships in the box {#in-the-box}
+
+A headless app skips weeks of dashboard work, and it's channel-agnostic from day
+one — the same agent runs from the web, Slack, Telegram, email, and other agents
+because everything goes through the agent, not the UI. The trade-off is there's
+no "browse-everything-at-a-glance" view; if users need that, mix patterns and
+add a small status page or list view.
+
+When you add the built-in Chat shell, the framework provides five management
+surfaces you don't have to build: **Chat** (the main input), **Workspace**
+(skills, memory, instructions, sub-agents, connected MCP servers, scheduled
+jobs), **Job history**, **Thread history**, and **Settings**. Those are usually
+enough — talk to it, see what it's done, configure how it behaves. Reach for
+[Chat](/docs/template-chat) when you're ready to add that browser UI, or the
+[Dispatch template](/docs/template-dispatch) for a workspace-style starting
+point with Slack/Telegram, scheduled jobs, and shared secrets out of the box.
+
+The smallest local path is a headless agent scaffold plus one action:
 
 ```bash
 npx @agent-native/core@latest create my-agent --headless
@@ -81,45 +118,20 @@ If another app or script needs to call the whole agent, use
 `agentNative.invoke("analytics", "...")` or the `agent-native invoke` CLI. That
 keeps cross-app work on the A2A path while local work stays on actions.
 
-Workers, jobs, integration webhooks, and custom hosts can use the server API
-directly. This is lower-level than actions: you provide the engine, model,
-messages, actions, and event sink yourself.
+Workers, jobs, integration webhooks, and custom hosts can drive the agent loop
+directly through the server API. This is lower-level than actions — you provide
+the engine, model, messages, actions, and event sink yourself:
 
 ```ts
-import {
-  actionsToEngineTools,
-  resolveEngine,
-  runAgentLoop,
-} from "@agent-native/core/server";
-
-const engine = await resolveEngine({ engineOption: undefined });
-const model = engine.defaultModel;
-const controller = new AbortController();
-
-await runAgentLoop({
-  engine,
-  model,
-  systemPrompt: "You are the reporting agent for this workspace.",
-  actions,
-  tools: actionsToEngineTools(actions),
-  messages: [
-    {
-      role: "user",
-      content: [{ type: "text", text: "Summarize this week's forms." }],
-    },
-  ],
-  send: (event) => {
-    // Persist, log, stream, or translate AgentChatEvent objects.
-  },
-  signal: controller.signal,
-  ownerEmail: user.email,
-  orgId: user.orgId,
-});
+import { runAgentLoop } from "@agent-native/core/server";
+
+await runAgentLoop({ engine, model, systemPrompt, actions, messages, send });
 ```
 
 For most apps, scheduled prompts and integration webhooks already call this loop
-for you. Reach for direct `runAgentLoop()` when you are building a custom
-headless host, eval runner, or server-side orchestration surface.
+for you. Reach for it directly only when building a custom headless host, eval
+runner, or server-side orchestration surface — see [Server — Production agent
+handler](/docs/server#agent-handler) for the full signature.
 
 ### Running against a folder {#folder-loop}
 
@@ -178,6 +190,48 @@ export default function ChatRoute() {
 }
 ```
 
+When an app has both a full-page chat tab and an `AgentSidebar`, use the same
+`storageKey` on both surfaces, enable `chatViewTransition`, and install the
+chat-home handoff helpers in the layout. Ordinary in-app links out of the chat
+page can then morph the full chat into the sidebar while keeping the active
+thread:
+
+```tsx
+import {
+  AgentChatSurface,
+  AgentSidebar,
+  useAgentChatHomeHandoff,
+  useAgentChatHomeHandoffLinks,
+} from "@agent-native/core/client/chat";
+import { useLocation } from "react-router";
+
+function ChatRoute() {
+  return (
+    <AgentChatSurface mode="page" storageKey="my-app" chatViewTransition />
+  );
+}
+
+function AppLayout({ children }: { children: React.ReactNode }) {
+  const location = useLocation();
+  const handoffActive = useAgentChatHomeHandoff({
+    storageKey: "my-app",
+    activePath: location.pathname,
+    enabled: location.pathname !== "/chat",
+  });
+  useAgentChatHomeHandoffLinks({ storageKey: "my-app", chatPath: "/chat" });
+
+  return (
+    <AgentSidebar
+      storageKey="my-app"
+      chatViewTransition
+      openOnChatRunning={handoffActive}
+    >
+      {children}
+    </AgentSidebar>
+  );
+}
+```
+
 The simplest embedded chat with your own chrome:
 
 ```tsx
@@ -195,14 +249,9 @@ components in the chat, without iframes. See [Native Chat UI](/docs/native-chat-
 ## Rich chat on your agent {#byo-agent}
 
 Use this path when your agent is already built with another framework or
-runtime and you want Agent-Native's chat UI around it.
-
-The [Chat template](/docs/template-chat) is still useful here: keep its app
-shell and thread UI, then swap the runtime behind the chat plugin or route.
-
-`AgentChatRuntime` is the boundary. Your runtime streams normalized events;
-Agent-Native renders the composer, transcript, tool calls, approvals, native
-widgets, and app layout.
+runtime and you want Agent-Native's chat UI around it. `AgentChatRuntime` is the
+boundary: your runtime streams normalized events, and Agent-Native renders the
+composer, transcript, tool calls, approvals, native widgets, and app layout.
 
 ```tsx
 import {
@@ -211,10 +260,7 @@ import {
 } from "@agent-native/core/client/chat";
 
 const runtime = createHttpAgentChatRuntime({
-  id: "external:support-agent",
-  label: "Support agent",
   endpoint: "/api/support-agent/chat",
-  headers: async () => ({ Authorization: `Bearer ${await getToken()}` }),
 });
 
 export function SupportAgentChat() {
@@ -222,40 +268,15 @@ export function SupportAgentChat() {
 }
 ```
 
-Use `createOpenAIAgentsChatRuntime()`,
-`createOpenAIResponsesChatRuntime()`, `createClaudeAgentChatRuntime()`,
-`createVercelAiChatRuntime()`, or `createAgUiChatRuntime()` when your endpoint
-already streams one of those event shapes. Use `createHttpAgentChatRuntime()`
-when your agent streams Agent-Native's normalized event shape directly:
-
-```ts
-import { createOpenAIAgentsChatRuntime } from "@agent-native/core/client/chat";
-
-const runtime = createOpenAIAgentsChatRuntime({
-  endpoint: "/api/openai-agent/chat",
-});
-```
-
-The endpoint can stream SSE or NDJSON events:
-
-```txt
-data: {"type":"message-delta","messageId":"m1","delta":{"type":"text","text":"I found 34 submissions."}}
-data: {"type":"tool-start","toolCall":{"id":"t1","name":"query","input":{"formId":"form_123"}}}
-data: {"type":"tool-done","toolCallId":"t1","toolName":"query","status":"completed","resultText":"34 rows"}
-data: {"type":"done","reason":"complete"}
-```
-
-For a trivial integration, returning `{ "text": "..." }` also works. For richer
-integrations, stream `message-*`, `tool-*`, `approval-request`, `status`,
-`artifact`, `file`, `usage`, `error`, and `done` events. Tool results can carry
-`chatUI` metadata so the same native table/chart/card renderers work with your
-agent too.
+Ready-made runtime helpers exist for OpenAI Agents, OpenAI Responses, the Claude
+Agent SDK, the Vercel AI SDK, and AG-UI, plus the normalized HTTP runtime above
+for any other agent (Mastra, Flue, Eve, LangGraph, or a custom service). ACP is
+not the default end-user app chat protocol, and Agent-Native does not currently
+claim A2UI support.
 
-This is the right place to adapt the OpenAI Agents SDK, Claude Agent SDK, Vercel
-AI SDK, Mastra, Flue, Eve, LangGraph, a custom service, or an AG-UI-compatible
-event stream. Do not use ACP as the default end-user app chat protocol; ACP is
-better framed as coding-agent/editor interoperability. Agent-Native does not
-currently claim A2UI support.
+[Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes)
+is the canonical home for the event shapes, the runtime helpers, and `chatUI`
+tool-result metadata. Start there when wiring an external agent into the chat.
 
 ## Embedded sidecar {#embedded-sidecar}
 
@@ -322,7 +343,7 @@ want a complete product shape.
 
 | If you are thinking...                                          | Choose                    |
 | --------------------------------------------------------------- | ------------------------- |
-| "I just need a callable tool or workflow."                      | Headless action           |
+| "I just need a callable tool or workflow."                      | Headless agent            |
 | "I want the framework's agent, but chat should be the main UI." | Rich chat on Agent-Native |
 | "I already have an agent; I need a polished chat UI for it."    | Rich chat on your agent   |
 | "I already have a SaaS app; add an agent beside it."            | Embedded sidecar          |

package/docs/content/agent-teams.md

@@ -127,19 +127,7 @@ interface AgentTask {
 
 ## Custom agent profiles {#profiles}
 
-A custom agent is a Markdown file in the workspace. Minimal example:
-
-```markdown
----
-name: Code Review
-description: Reviews TypeScript PRs for correctness and type safety.
-model: inherit
----
-
-You are a meticulous code reviewer. Be terse and concrete — cite file:line wherever you can.
-```
-
-Store at `agents/code-review.md` in the workspace. It appears in the `@mention` dropdown and is available to the main agent as a delegation target. See [Workspace — Custom Agents](/docs/workspace#custom-agents) for the full format including `tools`, `delegate-default`, and model overrides.
+Sub-agents map to custom agent profiles — Markdown files at `agents/<slug>.md` in the workspace that appear in the `@mention` dropdown and serve as delegation targets. [Workspace — Custom Agents](/docs/workspace#custom-agents) owns the full format (frontmatter, `tools`, `delegate-default`, model overrides).
 
 ## Delegation depth guard {#depth-guard}
 
@@ -147,7 +135,7 @@ Sub-agents can spawn sub-agents, which is a runaway/cost risk: an unbounded chai
 
 The top-level chat is depth `0`. A sub-agent it spawns is depth `1`; that sub-agent may spawn once more (depth `2`); a spawn that would create a depth-`3` sub-agent is **refused**. The default cap is **2**.
 
-```txt
+```text
 depth 0  top-level chat        (may spawn)
 depth 1  sub-agent             (may spawn)
 depth 2  sub-agent's sub-agent (at the cap — may NOT spawn)

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

@@ -1,11 +1,11 @@
 ---
-title: "Agent Web Surfaces"
-description: "Make public routes crawlable, readable, citable, and optionally callable by agents."
+title: "Public Agent Web"
+description: "Make public routes crawlable, readable, citable, and optionally callable by agents — robots.txt, llms.txt, markdown mirrors, JSON-LD, and a public MCP surface."
 ---
 
-# Agent Web Surfaces
+# Public Agent Web
 
-Agent Web surfaces make public Agent-Native routes easy for agents to crawl, read, cite, and call. The goal is not to make every app endpoint public. The goal is to publish a clean public surface for pages that are already public, while keeping private data and tool access behind explicit controls.
+The public agent web makes public Agent-Native routes easy for agents to crawl, read, cite, and call. The goal is not to make every app endpoint public. The goal is to publish a clean public surface for pages that are already public, while keeping private data and tool access behind explicit controls.
 
 The docs site is the reference implementation. Today it ships: