@agent-native/core 0.32.2 → 0.32.18

package/docs/content/context-awareness.md

@@ -1,25 +1,42 @@
 ---
 title: "Context Awareness"
-description: "How the agent knows what the user is looking at: navigation state, view-screen, navigate commands, and jitter prevention."
+description: "How the agent knows what the user is looking at: navigation state, selection context, view-screen, sendToAgentChat handoffs, navigate commands, and jitter prevention."
 ---
 
 # Context Awareness
 
-How the agent knows what the user is looking at — and how the agent can control what the user sees.
+How the agent knows what the user is looking at -- and how the agent can control what the user sees.
 
 ## Overview {#overview}
 
-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.
+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.
 
-Three patterns solve this:
+Five patterns solve this:
 
-1. **Navigation state** — the UI writes a `navigation` key to application-state on every route change
-2. **`view-screen`** — an action that reads navigation state, fetches contextual data, and returns a snapshot of what the user sees
-3. **`navigate`** — a one-shot command from the agent that tells the UI where to go
+1. **Navigation state** -- the UI writes a `navigation` key to application-state on every route change
+2. **Selection state** -- the UI writes a `selection` key when the user focuses, selects, or multi-selects something meaningful
+3. **`view-screen`** -- an action that reads application state, fetches contextual data, and returns a snapshot of what the user sees
+4. **Prompt handoff** -- UI controls call `sendToAgentChat()` when a click should become an agent turn
+5. **`navigate`** -- a one-shot command from the agent that tells the UI where to go
+
+## Context layers {#context-layers}
+
+Use different context channels for different jobs:
+
+| Layer                                     | Owner             | Use it for                                                                 |
+| ----------------------------------------- | ----------------- | -------------------------------------------------------------------------- |
+| `navigation` app-state key                | UI                | Current route, view, open record, filters, active tab                      |
+| `selection` app-state key                 | UI                | Durable semantic selection: rows, blocks, shapes, assets, messages         |
+| `pending-selection-context` app-state key | UI / `AgentPanel` | One-shot selected text attached to the next chat turn, usually from Cmd+I  |
+| `view-screen` action                      | Agent             | Hydrating the app-state keys into real records and screen summaries        |
+| `sendToAgentChat()`                       | UI                | Turning a click, command, comment pin, or selected item into a chat prompt |
+| `navigate` app-state key                  | Agent             | Asking the UI to move to another route or focus another object             |
+
+The short version: app state tells the agent what the user is looking at, `view-screen` turns that state into useful data, and `sendToAgentChat()` turns UI intent into a chat message when the user clicks a command.
 
 ## Navigation state {#navigation-state}
 
-The UI writes a `navigation` key to application-state on every route change. This tells the agent what view the user is on and what item is selected.
+The UI writes a `navigation` key to application-state on every route change. This tells the agent what view the user is on, what item is open, and which filters shape the visible list.
 
 ```json
 {
@@ -33,10 +50,12 @@ The UI writes a `navigation` key to application-state on every route change. Thi
 
 What to include in navigation state:
 
-- `view` — the current page/section (e.g., "inbox", "form-builder", "dashboard")
-- Item IDs — the selected/open item (e.g., `threadId`, `formId`)
-- Filter state — active search, label, or category filters
-- Any selection — focused item, selected text range, active tab
+- `view` -- the current page/section, such as "inbox", "form-builder", or "dashboard"
+- Item IDs -- the selected/open item, such as `threadId` or `formId`
+- Filter state -- active search, label, or category filters
+- Light focus state -- focused row, active tab, current panel
+
+Keep `navigation` small and URL-like. It should identify the current screen, not duplicate whole records. Fetch records in `view-screen` so the agent always gets fresh data.
 
 The agent reads this before acting:
 
@@ -47,27 +66,113 @@ const navigation = await readAppState("navigation");
 // { view: "inbox", threadId: "thread-123", label: "important" }
 ```
 
+## Selection state {#selection-state}
+
+Selection is semantic UI state. It is how "the chart I clicked", "these three rows", "this slide title", or "the current email draft range" becomes model-visible context.
+
+Use the `selection` app-state key for durable selection that should survive a moment of navigation, empty-chat suggestions, or a later `view-screen` call:
+
+```json
+{
+  "kind": "slide.elements",
+  "deckId": "deck-123",
+  "slideId": "slide-4",
+  "items": [
+    {
+      "id": "hero-title",
+      "selector": "[data-block-id='hero-title']",
+      "label": "Hero title",
+      "text": "Q3 launch plan"
+    }
+  ],
+  "capturedAt": 1780332977027
+}
+```
+
+Write it from the UI when the user selects, focuses, or multi-selects meaningful objects:
+
+```tsx
+import { agentNativePath } from "@agent-native/core/client";
+
+async function syncSelection(selection: unknown | null) {
+  const url = agentNativePath("/_agent-native/application-state/selection");
+
+  if (!selection) {
+    await fetch(url, { method: "DELETE", keepalive: true });
+    return;
+  }
+
+  await fetch(url, {
+    method: "PUT",
+    keepalive: true,
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(selection),
+  });
+}
+```
+
+Good selection state includes:
+
+- Stable IDs the agent can use in actions, such as `threadId`, `slideId`, or `assetId`
+- A short human label so prompts and suggestions are readable
+- Enough text or metadata to disambiguate the object
+- Optional UI locators such as selectors or coordinates when the agent needs to refer back to a visual element
+- `capturedAt` when stale selection would be harmful
+
+Avoid storing secrets, full documents, large binary payloads, or whole API responses in `selection`. Store IDs plus short excerpts, then let `view-screen` fetch the current source of truth.
+
+### One-shot selected text {#pending-selection-context}
+
+`AgentPanel` already handles the common text-selection flow. When the user presses Cmd+I (or Ctrl+I) with text selected on the page, it:
+
+1. Reads `window.getSelection()`
+2. Writes `{ text, capturedAt }` to `pending-selection-context`
+3. Focuses the agent chat
+
+The production agent injects that key into the next turn as immediate selection context and ignores it once it is stale. This is the path that makes "select text, press Cmd+I, ask 'make this punchier'" work without the user copying the selection into the prompt.
+
+Custom editors can write the same key when their selection is not represented by native browser selection:
+
+```tsx
+await fetch(
+  agentNativePath("/_agent-native/application-state/pending-selection-context"),
+  {
+    method: "PUT",
+    keepalive: true,
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      text: selectedMarkdown,
+      capturedAt: Date.now(),
+    }),
+  },
+);
+```
+
+Use `pending-selection-context` for one-shot "act on this exact highlighted text" flows. Use `selection` for durable object selection that `view-screen` and dynamic suggestions should keep seeing.
+
 ## The view-screen action {#view-screen-action}
 
-Every template should have a `view-screen` action. It reads navigation state, fetches the relevant data, and returns a snapshot of what the user sees. This is the agent's eyes.
+Every template should have a `view-screen` action. It reads navigation and selection state, fetches the relevant data, and returns a snapshot of what the user sees. This is the agent's eyes.
 
 ```ts
 // actions/view-screen.ts
 import { defineAction } from "@agent-native/core";
 import { readAppState } from "@agent-native/core/application-state";
-import { eq } from "drizzle-orm";
+import { eq, inArray } from "drizzle-orm";
 import { z } from "zod";
 import { getDb, schema } from "../server/db/index.js";
 
 export default defineAction({
   description:
-    "See what the user is currently looking at on screen. Reads navigation state and fetches matching data.",
+    "See what the user is currently looking at on screen. Reads navigation and selection state and fetches matching data.",
   schema: z.object({}),
   http: false,
   run: async () => {
     const navigation = (await readAppState("navigation")) as any;
+    const selection = (await readAppState("selection")) as any;
     const screen: Record<string, unknown> = {};
     if (navigation) screen.navigation = navigation;
+    if (selection) screen.selection = selection;
 
     const db = getDb();
 
@@ -84,6 +189,12 @@ export default defineAction({
         .from(schema.threads)
         .where(eq(schema.threads.id, navigation.threadId));
     }
+    if (selection?.kind === "email.messages") {
+      screen.selectedMessages = await db
+        .select()
+        .from(schema.emails)
+        .where(inArray(schema.emails.id, selection.messageIds));
+    }
 
     if (Object.keys(screen).length === 0) {
       return "No application state found. Is the app running?";
@@ -93,14 +204,68 @@ export default defineAction({
 });
 ```
 
-The agent should always call `pnpm action view-screen` before acting. This is a hard convention across all templates. When adding new features, update `view-screen` to return data for the new view.
+The agent should call `pnpm action view-screen` before acting on the current UI. This is a hard convention across all templates. When adding new features, update `view-screen` to return data for the new view and any new selection shape.
+
+## Prompt handoff with `sendToAgentChat()` {#send-to-agent-chat}
+
+Sometimes context should not just sit in app state. A user clicks a button, drops a comment pin, selects an item and chooses "Ask agent", or presses an AI command in a toolbar. That click is an instruction. In browser UI, hand it to the agent with `sendToAgentChat()`.
+
+```tsx
+import { sendToAgentChat } from "@agent-native/core/client";
+
+function askAgentAboutSelection(selection: {
+  documentId: string;
+  blockId: string;
+  label: string;
+  text: string;
+}) {
+  sendToAgentChat({
+    message: `Improve the selected block: ${selection.label}`,
+    context: [
+      `Document id: ${selection.documentId}`,
+      `Block id: ${selection.blockId}`,
+      "Current selected text:",
+      selection.text,
+    ].join("\n"),
+    submit: false,
+    openSidebar: true,
+  });
+}
+```
+
+Use the fields deliberately:
+
+| Field               | Meaning                                                                          |
+| ------------------- | -------------------------------------------------------------------------------- |
+| `message`           | Visible prompt text shown in chat                                                |
+| `context`           | Hidden model-visible context, not shown as user-facing chat text                 |
+| `submit: true`      | Send immediately; good for explicit command buttons such as "Fix layout"         |
+| `submit: false`     | Prefill for user review; good for "Ask agent about this" or ambiguous selections |
+| `openSidebar: true` | Make the agent response visible even if the panel was collapsed                  |
+| `newTab: true`      | Start a separate chat thread for a larger creation task                          |
+| `type: "code"`      | Route to the code-editing frame when the request is about changing app source    |
+
+`sendToAgentChat()` is the supported browser wrapper for the submitted-chat path sometimes seen internally as `agentNative.submitChat`. App UI should call the wrapper instead of posting `agentNative.submitChat` directly because the wrapper handles local sidebars, Builder/Frame routing, MCP App host routing, tab IDs, and code-request routing.
+
+Use `agentChat.submit()` or `agentChat.prefill()` for Node/script contexts where there is no browser sidebar. Server actions generally should not call browser-only `sendToAgentChat()`; if an action needs the open UI to ask the agent something, write a small request into `application_state` and let a UI bridge send it from the browser.
+
+### Clicked items in the prompt {#clicked-items-in-prompt}
+
+For the "click items in the UI and they become part of the prompt" experience, combine selection state with prompt handoff:
+
+1. On click or multi-select, write semantic `selection` state so `view-screen`, dynamic suggestions, and future turns can see it.
+2. If the click is also a command, call `sendToAgentChat()` with a concise visible `message` and richer hidden `context`.
+3. In `view-screen`, hydrate the selected IDs into current records so the agent can verify the object before mutating it.
+4. Clear `selection` when the object is no longer selected, deleted, or no longer relevant.
+
+That gives the user the magic "this is what I meant" behavior without stuffing every prompt with bulky visible context.
 
 ## The navigate action {#navigate-action}
 
 The agent writes a one-shot `navigate` command to application-state. The UI reads it, performs the navigation, and deletes the entry.
 
 ```ts
-// Agent side — write a navigate command
+// Agent side -- write a navigate command
 import { writeAppState } from "@agent-native/core/application-state";
 
 await writeAppState("navigate", { view: "inbox", threadId: "thread-123" });
@@ -109,7 +274,7 @@ await writeAppState("navigate", { view: "inbox", threadId: "thread-123" });
 The UI polls for this command and navigates when it appears:
 
 ```ts
-// UI side — poll for navigate commands
+// UI side -- poll for navigate commands
 const { data: navCommand } = useQuery({
   queryKey: ["navigate-command"],
   queryFn: async () => {
@@ -133,7 +298,7 @@ useEffect(() => {
 }, [navCommand]);
 ```
 
-The `navigation` key belongs to the UI — the agent should never write to it directly. Instead, the agent writes to `navigate`, and the UI performs the actual navigation (which then updates `navigation`).
+The `navigation` key belongs to the UI -- the agent should never write to it directly. Instead, the agent writes to `navigate`, and the UI performs the actual navigation, which then updates `navigation`.
 
 ## useNavigationState hook {#use-navigation-state}
 
@@ -158,7 +323,7 @@ export function useNavigationState() {
 }
 ```
 
-The `deriveNavigationState()` function is template-specific — it parses the URL path and extracts the view, item IDs, and filters relevant to your app.
+The `deriveNavigationState()` function is template-specific -- it parses the URL path and extracts the view, item IDs, and filters relevant to your app.
 
 ## Jitter prevention {#jitter-prevention}
 
@@ -179,5 +344,5 @@ How it works:
 - Agent writes are tagged with `requestSource: "agent"` (the action helpers do this automatically)
 - UI writes include the tab's unique ID via `X-Request-Source` header
 - The server stores the source on each event
-- When processing sync events, the UI filters out events matching its own `ignoreSource` value — so it doesn't refetch data it just wrote
+- When processing sync events, the UI filters out events matching its own `ignoreSource` value -- so it doesn't refetch data it just wrote
 - Events from agents, other tabs, and actions still come through normally

package/docs/content/deployment.md

@@ -252,9 +252,6 @@ Inbound webhook handlers refuse forged requests when their signing secret is mis
 | `WHATSAPP_APP_SECRET`           | WhatsApp Business integration is enabled.                                                                      |
 | `WHATSAPP_VERIFY_TOKEN`         | WhatsApp webhook verification handshake (set in your Meta app dashboard too).                                  |
 | `SLACK_SIGNING_SECRET`          | Slack integration is enabled. Verifies Slack request signatures.                                               |
-| `RECALL_WEBHOOK_SECRET`         | Calls / Recall.ai integration is enabled.                                                                      |
-| `DEEPGRAM_WEBHOOK_SECRET`       | Calls / Deepgram transcription webhook is enabled.                                                             |
-| `ZOOM_WEBHOOK_SECRET`           | Calls / Zoom integration is enabled.                                                                           |
 | `GOOGLE_DOCS_PUSH_AUDIENCE`     | Google Docs Pub/Sub push integration is enabled. Set to the public URL of your push endpoint.                  |
 | `GOOGLE_DOCS_PUSH_SIGNER_EMAIL` | Google Docs Pub/Sub push integration is enabled. Set to the Pub/Sub service account email.                     |
 | `GMAIL_WATCH_TOPIC`             | Gmail Pub/Sub push (mail template). Optional — disables push if unset and falls back to history-delta polling. |
@@ -267,14 +264,14 @@ For local development of any of these integrations, set `AGENT_NATIVE_ALLOW_UNVE
 
 Defaults are strict; these flags relax behavior. Don't set them unless you specifically want the relaxed path.
 
-| Variable                                 | Effect                                                                                                                                                                                                                                                                                                           |
-| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AGENT_NATIVE_DEBUG_ERRORS`              | `=1` to include stack traces in 500 JSON responses. Useful on previews; do **not** set in real prod (was previously gated by `NODE_ENV !== "production"`, which leaked stacks on misconfigured deploys).                                                                                                         |
-| `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS` | `=1` to accept webhooks without their signing secret (local dev only). Defaults to fail-closed in production.                                                                                                                                                                                                    |
-| `AGENT_NATIVE_KEYS_WORKSPACE_FALLBACK`   | `=1` to let `${keys.NAME}` resolution in tools/automations fall through user-scope → workspace-scope. Default off (user-scope only) — a malicious org member could otherwise plant a workspace `OPENAI_API_KEY` and harvest other members' calls. Turn on only if your org genuinely shares workspace-wide keys. |
-| `AGENT_NATIVE_MCP_HUB_MULTI_ORG`         | `=1` to allow `AGENT_NATIVE_MCP_HUB_TOKEN` to serve multiple orgs from a single hub deployment. Default refuses to serve when more than one org exists in a hub deploy. Only relevant if you operate the workspace MCP hub.                                                                                      |
-| `AGENT_NATIVE_ALLOW_ENV_VAR_WRITES`      | `=1` to let runtime code mutate `process.env` from the env-var write API. Off by default — required to be explicitly enabled outside dev SQLite.                                                                                                                                                                 |
-| `AUTH_SKIP_EMAIL_VERIFICATION`           | `=1` to skip email verification for password signups. Local dev/test skips by default; hosted deploys should use this only for QA — see Auth section above.                                                                                                                                                      |
+| Variable                                 | Effect                                                                                                                                                                                                                                                                                                              |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AGENT_NATIVE_DEBUG_ERRORS`              | `=1` to include stack traces in 500 JSON responses. Useful on previews; do **not** set in real prod (was previously gated by `NODE_ENV !== "production"`, which leaked stacks on misconfigured deploys).                                                                                                            |
+| `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS` | `=1` to accept webhooks without their signing secret (local dev only). Defaults to fail-closed in production.                                                                                                                                                                                                       |
+| `AGENT_NATIVE_KEYS_WORKSPACE_FALLBACK`   | `=1` to let `${keys.NAME}` resolution in tools/automations fall through user-scope → workspace-scope. Default off (user-scope only) — a malicious org member could otherwise plant a workspace `OPENAI_API_KEY` and harvest other members' requests. Turn on only if your org genuinely shares workspace-wide keys. |
+| `AGENT_NATIVE_MCP_HUB_MULTI_ORG`         | `=1` to allow `AGENT_NATIVE_MCP_HUB_TOKEN` to serve multiple orgs from a single hub deployment. Default refuses to serve when more than one org exists in a hub deploy. Only relevant if you operate the workspace MCP hub.                                                                                         |
+| `AGENT_NATIVE_ALLOW_ENV_VAR_WRITES`      | `=1` to let runtime code mutate `process.env` from the env-var write API. Off by default — required to be explicitly enabled outside dev SQLite.                                                                                                                                                                    |
+| `AUTH_SKIP_EMAIL_VERIFICATION`           | `=1` to skip email verification for password signups. Local dev/test skips by default; hosted deploys should use this only for QA — see Auth section above.                                                                                                                                                         |
 
 ### Workspace .env Inheritance {#env-inheritance}
 

package/docs/content/dispatch.md

@@ -15,7 +15,7 @@ Without Dispatch, every app in a multi-app workspace ends up re-implementing the
 
 Reach for Dispatch when any of these are true:
 
-- You're running a [multi-app workspace](/docs/multi-app-workspace) — mail, calendar, analytics, content, recruiting — and you don't want one Slack bot per app.
+- You're running a [multi-app workspace](/docs/multi-app-workspace) — mail, calendar, analytics, content — and you don't want one Slack bot per app.
 - You want **one inbox for "the agent"** so users DM a single bot and the right specialist app picks up the work behind the scenes.
 - You have **workspace-wide secrets** (Stripe key, OpenAI key, third-party API tokens) that several apps need and you want one vault instead of copying values into every `.env`.
 - You want a **runtime approval flow** in front of sensitive changes (saved destinations, policy edits) so non-admins can request and admins can sign off without a code deploy.

package/docs/content/external-agents.md

@@ -101,6 +101,10 @@ The command asks which local agent clients should receive MCP config. All client
 
 For Claude Code and Claude Code CLI, `connect` writes a standard remote HTTP MCP entry with no static headers. Restart Claude Code, run `/mcp`, and choose **Authenticate**; Claude completes the OAuth flow and stores its own tokens. For Codex and Claude Cowork, `connect` uses the compatibility device-code flow: it opens your browser at the app, you click **Authorize** once, and the command writes a scoped bearer-token entry. If you choose a mix of clients, it does both.
 
+Keep the `connect` command running until the browser approval completes. If the
+waiting process is stopped early, the approval can succeed in the browser but
+the local client config will not receive the token.
+
 If you previously connected Claude Code through the old bearer-token flow, just run the same `agent-native connect ... --client claude-code` command again. The CLI replaces the legacy `Authorization` headers with the URL-only OAuth entry and tells you to re-authenticate from `/mcp`.
 
 | Local client                  | Config written by `connect`                             | Auth flow                                       |
@@ -111,15 +115,32 @@ If you previously connected Claude Code through the old bearer-token flow, just
 
 Restart the agent client after connecting so it picks up the new MCP server; OAuth-native clients may then prompt you to authenticate from their MCP UI.
 
+When troubleshooting local MCP config, redact `Authorization`, `http_headers`,
+and token values before sharing logs. Do not use raw curl as a substitute for a
+host MCP session; after connecting, use the host-exposed tools or restart the
+client if the new server is not visible yet.
+
 Use `--client codex` (or `--client claude-code`, `--client claude-code-cli`, `--client cowork`, `--client all`) to skip the picker for scripts or one-off installs.
 
-First-party app skills install the instructions and the hosted MCP connector together with `skills add <name>`. Each has a short alias for demos and tutorials:
+First-party app skills install the instructions and the hosted MCP connector together with the Agent Native CLI:
 
 ```bash
 npx @agent-native/core@latest skills add assets              # aliases: images, image-generation
 npx @agent-native/core@latest skills add design-exploration  # aliases: design, ux-exploration
 ```
 
+The Vercel/open Skills CLI path is also available when you only want portable
+instructions:
+
+```bash
+npx skills add BuilderIO/agent-native --skill assets
+npx skills add BuilderIO/agent-native --skill design-exploration
+```
+
+The raw `skills` CLI installs `SKILL.md` files only; local MCP clients still
+need a connector such as `npx @agent-native/core@latest connect
+https://assets.agent-native.com`.
+
 | Skill                | Alias    | For                    |
 | -------------------- | -------- | ---------------------- |
 | `assets`             | `images` | image/video generation |
@@ -228,7 +249,16 @@ only when it truly needs to stay visible in chat-host discovery.
 
 That makes the same app surface available to every compatible host rather than building per-client shims. The current official MCP Apps client list includes Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT, and Cursor; host support still varies by plan, release channel, and client version, so check the [MCP extension support matrix](https://modelcontextprotocol.io/extensions/client-matrix). ChatGPT custom MCP apps are available through developer mode for Business and Enterprise/Edu workspaces on ChatGPT web; see OpenAI's [developer mode and MCP apps](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-apps-in-chatgpt-beta) notes.
 
-Claude Code and other CLI-first clients still receive the same resources and metadata when they support MCP Apps, but the deep link remains the reliable fallback when a host chooses not to render an iframe. In practice, every agent-native app should be authored with both: MCP Apps for inline review/edit in capable hosts, and `link` for universal round-tripping back to the full app. Human-selection tools can add a paste-back step to that fallback: for example, the Assets picker opens from the fallback link, lets the user choose media in the browser, then copies a handoff summary that the user pastes back into the chat.
+Claude Code, Codex, and other CLI/code-editor clients still receive the same
+resources and metadata when they support MCP Apps, but treat them as link-out
+hosts unless you have verified inline iframe rendering in that exact surface.
+The deep link remains the reliable fallback when a host chooses not to render an
+iframe. In practice, every agent-native app should be authored with both: MCP
+Apps for inline review/edit in capable hosts, and `link` for universal
+round-tripping back to the full app. Human-selection tools can add a paste-back
+step to that fallback: for example, the Assets picker opens from the fallback
+link, lets the user choose media in the browser, then copies a handoff summary
+that the user pastes back into the chat.
 
 Claude and ChatGPT can cache tool and resource metadata for an existing custom
 connector. After changing MCP App metadata, verify with a fresh tool call; if

package/docs/content/migration-workbench.md

@@ -20,7 +20,7 @@ npx @agent-native/core@latest code /migrate ./my-next-app --out ../migrated-app
 
 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 hidden `migration` app is now a legacy/internal detail surface, available with `--app-surface` when a run needs a richer assessment/approval/task/verifier dashboard.
+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:
 
@@ -104,26 +104,9 @@ npx @agent-native/core@latest code /migrate --describe "A Rails admin app with r
 
 For local paths, the source is read-only. Generated output must live outside the source tree.
 
-## Internal Run Surface
+## 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.
-
-Open the legacy hidden `migration` detail surface only when you explicitly want that richer dashboard:
-
-```bash
-npx @agent-native/core@latest code /migrate ./my-next-app --app-surface
-cd migration
-pnpm install
-pnpm dev
-```
-
-The local dev URL is printed by Vite. In first-party dev setups it is usually:
-
-```text
-http://localhost:8101/
-```
-
-Inside that optional internal surface, the flow is:
+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`.
@@ -131,7 +114,7 @@ Inside that optional internal surface, the flow is:
 4. **Sweep** runs migration tasks against the generated output project.
 5. **Verify** runs deterministic checks and writes `04-report.md`.
 
-Drive this surface 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.
+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
 

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

@@ -7,7 +7,7 @@ description: "Host many agent-native apps in one monorepo with shared auth, RBAC
 
 > 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.
 
-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, a recruiting tracker, an ops console — ten small apps, each scaffolded independently. That's great until you need to change something in all of them.
+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.
 
 At that point every app has its own `AGENTS.md`, its own auth plugin, its own copy-pasted layout component, its own hard-coded Slack token, its own idea of what an "organization" is. A compliance rule change means ten PRs. Rotating an API key means ten redeployments. A brand refresh means ten different headers drifting out of sync. The thing that made it easy to build them is now making it hard to manage them.
 

package/docs/content/recurring-jobs.md

@@ -112,7 +112,7 @@ If the runtime is serverless/edge, trigger the tick from an external cron (Cloud
 Don't confuse recurring jobs with `@agent-native/scheduling`:
 
 - **Recurring jobs (this page)** — cron-scheduled _prompts_ the agent runs in the background. Framework-level. Lives in the workspace. Runs on any agent-native app.
-- **`@agent-native/scheduling`** — a reusable domain package for building calendar/booking features (event types, availability windows, bookings). Powers the `calendar` and `scheduling` templates. See the scheduling template for usage.
+- **`@agent-native/scheduling`** — a reusable domain package for building calendar/booking features (event types, availability windows, bookings). Powers the `calendar` template and custom scheduling surfaces.
 
 Recurring jobs are "how do I make the agent act on its own?" The scheduling package is "how do I build a calendar app?" Different concerns.
 

package/docs/content/security.md

@@ -239,7 +239,6 @@ Workspace-scope secret writes still require org owner/admin role regardless of t
 - [ ] `EMAIL_INBOUND_WEBHOOK_SECRET` if Resend / SendGrid inbound is enabled
 - [ ] `SLACK_SIGNING_SECRET` if Slack is enabled
 - [ ] `TELEGRAM_WEBHOOK_SECRET` / `WHATSAPP_APP_SECRET` for those integrations
-- [ ] `RECALL_WEBHOOK_SECRET`, `DEEPGRAM_WEBHOOK_SECRET`, `ZOOM_WEBHOOK_SECRET` for calls
 - [ ] `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS` is **not** set in prod
 
 ### Schema

package/docs/content/sharing.md

@@ -46,8 +46,6 @@ Every template that stores user-authored work uses this model. Concretely:
 - **Design** — designs and assets
 - **Video** — compositions
 - **Clips** — screen recordings (Loom-style)
-- **Calls** — meeting recordings and transcripts (Granola-style)
-- **Meeting Notes** — transcripts and summaries
 - **Forms** — form definitions
 - **Calendar** — events and booking links
 - **Analytics** — dashboards (rolling out — see the analytics template's `AGENTS.md`)
@@ -60,7 +58,7 @@ Every one of these uses the same `ownableColumns()` schema helper, the same `sha
 A few areas are intentionally outside the sharing system:
 
 - **Personal-data apps** (Mail, Macros) — user-scoped by design. There's no "share my inbox" concept.
-- **External source-of-truth apps** (Issues → Jira, Recruiting → Greenhouse) — access control lives in the upstream system, not the agent-native app.
+- **External source-of-truth apps** — access control lives in the upstream system, not the agent-native app.
 - **Anonymous public URLs** — form publish slugs and booking-link slugs that expose a URL to logged-out users are a separate axis. They live alongside the sharing system, not on top of it.
 
 ## The share UI {#share-ui}

package/docs/content/skills-guide.md

@@ -81,15 +81,15 @@ Hosted is the default install path. Local launch is explicit for customization,
 offline work, or privacy-sensitive use.
 
 ```bash
-# One-command hosted install for the exported Assets skill plus MCP connector.
+# Happy path: exported instructions plus hosted MCP connector.
 npx @agent-native/core@latest skills add assets
-
-# Same install, using the image-generation alias for demos and tutorials.
 npx @agent-native/core@latest skills add images
-
-# One-command hosted install for Design exploration plus MCP connector.
 npx @agent-native/core@latest skills add design-exploration
 
+# Vercel/open Skills CLI: exported instructions only, no MCP config.
+npx skills add BuilderIO/agent-native --skill assets
+npx skills add BuilderIO/agent-native --skill design-exploration
+
 # Register a hosted MCP connector for local agent clients.
 agent-native app-skill ensure --manifest templates/assets/agent-native.app-skill.json
 
@@ -100,7 +100,7 @@ agent-native app-skill launch --manifest templates/assets/agent-native.app-skill
 # plain/Claude skills, and MCP configs.
 agent-native app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill
 
-# Install the exported skill with the open skills CLI.
+# Install a local exported bundle with the Vercel/open Skills CLI.
 npx skills add ./dist/assets-skill --skill assets -a codex -y
 
 # Add the generated Claude Code marketplace, then install its Assets plugin.
@@ -113,10 +113,12 @@ metadata; OAuth/device setup happens in the MCP host or through the app's normal
 settings flow.
 
 The Vercel Labs `skills` adapter is a portable `skills/<name>/SKILL.md` bundle
-for `npx skills add ...`. For first-party hosted apps, prefer
-`agent-native skills add images`, `agent-native skills add assets`, or
-`agent-native skills add design-exploration`; each installs the exported
-instructions and runs the MCP registration step together.
+for `npx skills add ...`, but the raw `skills` CLI installs instructions only.
+It does not run repo-defined postinstall scripts or register MCP connectors.
+Keep the Agent Native CLI as the default docs path for local agents because it
+also registers the MCP connector. `BuilderIO/agent-native` is a real GitHub
+repository source for the Vercel/open Skills CLI; `skills.sh` is a discovery and
+leaderboard directory, not an npm-style package namespace.
 
 The Claude Code marketplace adapter writes
 `adapters/claude-marketplace/.claude-plugin/marketplace.json` plus a nested

package/docs/content/template-assets.md

@@ -54,6 +54,16 @@ Generate and pick brand media without leaving Codex, Claude Code, Claude, or Cha
    ```
 
    Default client is `codex`; add `--client claude-code` or `--client all` for others.
+   If you only want the portable skill instructions through the Vercel/open
+   Skills CLI, use:
+
+   ```bash
+   npx skills add BuilderIO/agent-native --skill assets
+   ```
+
+   The Vercel/open Skills CLI installs the instruction file only; it does not
+   run MCP connector setup. Use the Agent Native CLI path above when you want
+   the one-command setup.
 
 2. **Ask for images.** In your agent's chat: "Generate three blog hero options from the Acme product shots." The agent opens the picker with candidate images you can regenerate, retune (prompt, aspect, count), and choose from.
 3. **Pick.** In inline hosts (ChatGPT, Claude.ai, Claude Desktop main chat) the picker renders right in the chat — click a candidate and the choice flows back automatically. On CLI/link-only hosts (Codex, Claude Code, Claude Desktop "Code" tab) you get an **"Open in Assets →"** link; open it, pick in the browser, then paste the copied handoff summary back into your chat — or just say "use image A".
@@ -128,6 +138,13 @@ copies a handoff summary and shows a copyable context block; paste that summary
 back into the chat so the external agent can use the selected media URL and
 asset metadata.
 
+Codex, Claude Code, and Claude Desktop Code should be treated as link-out hosts
+for this flow. They may not render MCP Apps inline, and remote CDN markdown
+images may not display reliably in the chat transcript. Agents should keep the
+asset link as the source of truth; when a visible inline preview is needed in a
+code-editor chat, download the selected `previewUrl`/`downloadUrl` to a local
+image file and embed that absolute local path.
+
 For generate-and-choose flows, call `open-asset-picker` with `prompt`,
 `autoGenerate: true`, and `count: 3` (customizable from 1-6). The picker opens
 with candidate images and lets the user adjust count, aspect ratio, or a
@@ -148,6 +165,9 @@ npx @agent-native/core@latest skills add assets
 # Image-generation alias for demos and tutorials.
 npx @agent-native/core@latest skills add images
 
+# Vercel/open Skills CLI install: exported instructions only, no MCP config.
+npx skills add BuilderIO/agent-native --skill assets
+
 # Hosted install: URL-only MCP connector, no shared secrets in skill files.
 agent-native app-skill ensure --manifest templates/assets/agent-native.app-skill.json
 
@@ -157,7 +177,7 @@ agent-native app-skill launch --manifest templates/assets/agent-native.app-skill
 # Marketplace package, including Claude Code marketplace and Vercel Labs skills adapters.
 agent-native app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill
 
-# Install the exported Assets skill with the open skills CLI.
+# Install a local exported Assets bundle with the open skills CLI.
 npx skills add ./dist/assets-skill --skill assets -a codex -y
 
 # Install from the generated Claude Code marketplace adapter.