@agent-native/core 0.93.0 → 0.94.0

package/docs/content/locales/zh-TW/template-dispatch.mdx

@@ -5,7 +5,11 @@ description: "Dispatch 是工作區控制平面 - 中央收件箱、跨應用編
 
 # 調度
 
-> **另請參閱：** 有關 Dispatch 功能以及何時需要它的概念概述，請參閱 [Dispatch](/docs/dispatch)。此頁面是特定於範本的參考。
+<Callout tone="info">
+
+**另請參閱：** 有關 Dispatch 功能以及何時需要它的概念概述，請參閱 [Dispatch](/docs/dispatch)。此頁面是特定於範本的參考。
+
+</Callout>
 
 Dispatch 是**工作區控制平面**。其他範本是域應用程式（郵件、行事曆、分析、大腦），而 Dispatch 是您與它們一起執行以協調一切的應用程式：中央收件箱、機密庫、計畫作業、Slack/Telegram 整合以及透過 [A2A](/docs/a2a-protocol) 將域工作委托給正確的專業應用程式的協調器代理。
 

package/docs/content/locales/zh-TW/template-mail.mdx

@@ -362,3 +362,11 @@ UI 中的路由：
 **更改鍵盤快速鍵。** `templates/mail/app/components/email/` 中存在按鍵綁定處理常式 - 搜尋 `useHotkeys` 或 `addEventListener("keydown"` 以尋找每個按鍵的接線位置。
 
 要求代理為您進行任何這些更改。代理可以編輯自己的來源程式碼 - 請參閱 [Self-Modifying Code](/docs/key-concepts#agent-modifies-code)。
+
+## 接下來
+
+- [**範本**](/docs/cloneable-saas) — 複製並擁有的模式，以及可作為起點的所有其他領域範本
+- [**開始使用**](/docs/getting-started) — 框架基礎：actions、application state 和即時同步
+- [**行事曆**](/docs/template-calendar) — 涵蓋排程和預約的相關領域範本
+- [**自動化**](/docs/automations) — Mail 自動分類規則所依據的事件觸發引擎
+- [**Actions**](/docs/actions) — 聊天、快速鍵和自動化共同呼叫的 action 系統

package/docs/content/locales/zh-TW/tracking.mdx

@@ -127,6 +127,8 @@ import { defineAction } from "@agent-native/core/action";
 import { track } from "@agent-native/core/tracking";
 import { z } from "zod";
 
+import { getDb, schema } from "../server/db/index.js";
+
 export default defineAction({
   description: "Create a new project.",
   schema: z.object({
@@ -134,14 +136,15 @@ export default defineAction({
     template: z.string().optional(),
   }),
   run: async ({ name, template }, ctx) => {
-    const project = await db
-      .insert(projects)
+    const db = getDb();
+    const [project] = await db
+      .insert(schema.projects)
       .values({ name, template })
       .returning();
 
-    track("project.created", { name, template }, { userId: ctx.userEmail });
+    track("project.created", { name, template }, { userId: ctx?.userEmail });
 
-    return { ok: true, projectId: project[0].id };
+    return { ok: true, projectId: project.id };
   },
 });
 ```
@@ -349,5 +352,5 @@ interface TrackingEvent {
 ## 下一步是什麼
 
 - [**Actions**](/docs/actions) — 大多數跟蹤呼叫的發起位置
-- [**Server Plugins**](/docs/server) - `registerBuiltinProviders()` 在啟動時在 core-routes 外掛中執行
-- [**Secrets**](/docs/security) — 管理用於跟蹤提供者的 API 金鑰
+- [**Server Plugins**](/docs/server#server-plugins) - `registerBuiltinProviders()` 在啟動時在 core-routes 外掛中執行
+- [**安全性 — 秘密管理**](/docs/security#secrets) — 管理用於跟蹤提供者的 API 金鑰

package/docs/content/locales/zh-TW/using-your-agent.mdx

@@ -92,21 +92,14 @@ agent-native 背後的定義思想是，agent 和 UI 是**平等的伙伴** -
 
 代理不是您透過 Tab 鍵切換到的單獨應用程式。它以幾個 React 元件的形式提供——一個側邊欄、一個原始面板和一個 `sendToAgentChat()` 呼叫——您可以將它們放入任何應用程式中。渲染 `<AgentSidebar>` 為每個螢幕提供一個可切換代理，或連線一個按鈕將特定工作交給聊天，而不是執行一次性 LLM 呼叫。
 
-→ [**Drop-in Agent**](/docs/drop-in-agent) — 將 `<AgentPanel>`、`<AgentSidebar>` 和 `sendToAgentChat()` 安裝到任何 React 應用程式中。
-→ [**Agent Surfaces**](/docs/agent-surfaces) — 選取工作流程是否應為無頭、聊天優先、嵌入式或完整應用程式。
-
 ## 你可以去輕 UI {#ui-light}
 
 並非每個應用程式都需要完整的儀表板。當代理*是*產品時，您可以跳過大部分自訂 UI：開啟應用程式，詢問您想要的內容，然後讓代理完成其餘的工作。代理仍然有其管理介面——歷史紀錄、工作區、設定——但主要互動是對話而不是點選。
 
-→ [**Automation-First Apps**](/docs/pure-agent-apps) — 用於 jobs、queues、scripts 和外部 agents 的無瀏覽器應用。
-
 ## 您與它共同編輯 {#you-co-edit}
 
 當您和代理處理同一份檔案時，你們不會輪流處理。透過即時協作，代理的編輯可以與您的編輯一起傳輸 - 即時游標，不會覆蓋 - 與隊友的編輯方式相同。您可以在它工作時繼續輸入，並且它會在發生更改時看到您的更改。
 
-→ [**Real-Time Collaboration**](/docs/real-time-collaboration) — 在同一檔案中使用即時游標和代理編輯進行多使用者協作編輯。
-
 ## 下一步是什麼 {#whats-next}
 
 - [**Context Awareness**](/docs/context-awareness) — 代理知道您在看什麼

package/docs/content/locales/zh-TW/voice-input.mdx

@@ -9,6 +9,12 @@ description: "代理聊天編輯器中的語音聽寫 - Builder Gemini、BYOK
 
 框架會自動處理所有這些。 Builder 連線的使用者預設獲得 Builder 託管的 Gemini Flash-Lite；否則，使用者可以攜帶自己的提供者金鑰或退回到瀏覽器語音識別。
 
+## 即時語音模式 {#realtime-speech-mode}
+
+開啟麥克風後，彈出式選單會讓您在**即時語音對話**和**可編輯聽寫**之間選擇。即時模式需要使用者範圍的 `OPENAI_API_KEY`，並透過 WebRTC 將瀏覽器連線到 `gpt-realtime-2.1`。聊天會收合為右下角的語音球；點選語音球即可顯示或隱藏聊天，而不會結束對話。
+
+語音模型使用與聊天相同且經過驗證的 Agent Native 工具，因此可以一邊說話，一邊在應用程式中導覽和呼叫動作。需要核准的動作會維持暫停，直到您核准為止。音訊絕不會儲存到 SQL 中；Agent Native 只保留精簡的工作階段和轉錄狀態。即時工作階段最長可持續 60 分鐘。
+
 ## 它是如何工作的 {#how-it-works}
 
 撰寫器的語音按鈕在瀏覽器中錄製音訊，然後選取提供者：

package/docs/content/locales/zh-TW/workspace-connections.mdx

@@ -423,10 +423,9 @@ Brain's Sources 頁面是參考實現。它在 Brain 來源紀錄旁邊顯示可
 
 ### 調度控制平面設定
 
-Dispatch 公開了控制平面 actions，該控制平面編寫應用程式可以直接呼叫的相同共用儲存函式：
+Dispatch 提供控制平面 actions，它們使用應用程式可直接呼叫的相同共用儲存函式 — 其中 `upsert-workspace-connection` action 會根據提供者目錄驗證輸入，然後委派給本頁所示的同一個 `upsertWorkspaceConnection()`：
 
 ```ts
-// templates/dispatch/actions/upsert-workspace-connection.ts delegates to this.
 await upsertWorkspaceConnection({
   id: "team-slack",
   provider: "slack",
@@ -491,3 +490,11 @@ await upsertWorkspaceConnectionGrant({
 保持嚴格的邊界：提供者中繼資料可以安全地顯示；憑證值保留在保管庫中。
 
 </details>
+
+## 接下來 {#whats-next}
+
+- [**Dispatch**](/docs/dispatch) — 通常負責工作區連線設定和保管庫的應用程式
+- [**安全性**](/docs/security) — 連線所指向的憑證保管庫、機密範圍和存取模型
+- [**入門設定**](/docs/onboarding#checking-workspace-connections-in-onboarding) — 從範本設定清單檢查連線就緒狀態
+- [**MCP 用戶端**](/docs/mcp-clients) — 在工作區中共用 MCP 伺服器憑證的相關可重用設定模式
+- [**Brain**](/docs/template-brain) — 基於此模型建構提供者 Sources 頁面的參考實作

package/docs/content/locales/zh-TW/workspace.mdx

@@ -5,7 +5,11 @@ description: "Claude - 每個使用者的程式碼級自訂 - skills、記憶、
 
 # 工作區
 
-> **哪個工作區檔案？** 此頁面涵蓋 **自訂層** — 工作區*是什麼*。對於部署形狀（一個單一儲存庫，許多應用程式），請參閱 [Multi-App Workspaces](/docs/multi-app-workspace)；有關治理（誰審查、核准和擁有什麼），請參閱 [Workspace Governance](/docs/workspace-management)。
+<Callout tone="info">
+
+**哪個工作區檔案？** 此頁面涵蓋 **自訂層** — 工作區*是什麼*。對於部署形狀（一個單一儲存庫，許多應用程式），請參閱 [Multi-App Workspaces](/docs/multi-app-workspace)；有關治理（誰審查、核准和擁有什麼），請參閱 [Workspace Governance](/docs/workspace-management)。
+
+</Callout>
 
 每個 Agent-Native 應用程式都附帶一個**工作區**：使代理成為您的自訂層。它包含團隊指令 (`AGENTS.md`)、共用學習內容 (`LEARNINGS.md`)、個人結構化記憶 (`memory/MEMORY.md`)、代理按需拉入的 skills、自訂子代理、計畫作業和連線的 MCP 伺服器 — 您期望從 Claude 程式碼 / Codex 設定獲得的一切。
 
@@ -82,7 +86,7 @@ description: "Claude - 每個使用者的程式碼級自訂 - skills、記憶、
 | 每個專案 `CLAUDE.md` / skills | 每個應用 `AGENTS.md` + 工作區記憶資源   |
 | JSON 檔案中的 MCP 設定        | JSON 中的 MCP 設定*或*設定 UI，每個範圍 |
 
-相同的功能。不同的經濟。請參閱 [Templates](/docs/cloneable-saas) 了解為什麼這對 SaaS 很重要。
+相同的功能。不同的經濟。請參閱 [應用程式](/docs/cloneable-saas) 了解為什麼這對 SaaS 很重要。
 
 ## 概述 {#overview}
 
@@ -219,11 +223,9 @@ workspace context/brand.md
 -> personal context/brand.md
 ```
 
-保持 `context/` 檔案簡短且真實——代理可以瀏覽的一些要點：
-
-```text
-<!-- context/brand.md -->
+例如：
 
+```text filename="context/brand.md"
 # 品牌
 
 - Voice: direct, warm, concrete
@@ -388,15 +390,9 @@ Skills 是 `skills/` 路徑（最好是 `skills/<name>/SKILL.md`）下的 Markdo
 
 在一個應用程式內使用自訂代理進行委派。當您需要透過 A2A 呼叫另一個應用程式時，請使用連線的代理。
 
-## @標記 {#at-tagging}
-
-在聊天輸入中鍵入 `@` 以引用工作區專案。游標處會出現一個下拉清單，顯示匹配的代理和檔案。使用箭頭鍵進行導覽並使用 Enter 進行選取。所選專案在輸入中顯示為行內標籤。
-
-當您傳送訊息時，**檔案/資源**作為代理可以讀取的引用進行傳遞，**自訂代理**使用其設定檔案指令在本機執行，並且**連線的代理**透過 A2A 進行呼叫。
+## @ 標記與 / 斜線指令 {#at-tagging}
 
-## / 斜線指令 {#slash-commands}
-
-在行首鍵入 `/` 以呼叫技能。下拉清單顯示可用的 skills 及其名稱和描述；選取一個會新增一個行內標籤，並在傳送訊息時將其內容作為脈絡包含在內。如果未設定 skills，則下拉清單連結到這些檔案。
+在聊天輸入框中輸入 `@` 可參照代理、檔案或資源，輸入 `/` 可呼叫 skill——兩者都會在游標處開啟下拉選單，並在選擇項目後加入行內標籤。完整機制（路由、`MentionProvider`、子代理選擇）請參閱[代理提及](/docs/agent-mentions)；skills 的編寫與探索方式請參閱 [Skills 指南](/docs/skills-guide)。
 
 ## 程式碼與應用程式模式 {#dev-vs-prod}
 
@@ -416,10 +412,6 @@ Skills 是 `skills/` 路徑（最好是 `skills/<name>/SKILL.md`）下的 Markdo
 
 請參閱 [Workspace Connections](/docs/workspace-connections) 了解快速入門、connection/grant/credentialRef API 以及具體的 Slack、HubSpot 和 GitHub 範例。
 
----
-
-# 參考
-
 ## 資源 API {#resource-api}
 
 可以透過伺服器程式碼、actions 或 REST API 管理資源。
@@ -463,3 +455,12 @@ pnpm action resource-write --path "notes/meeting.md" --content "# 會議紀錄..
 # 刪除資源
 pnpm action resource-delete --path "notes/old.md"
 ```
+
+## 接下來 {#whats-next}
+
+- [**Skills 指南**](/docs/skills-guide) — 編寫 `skills/` 中參照的 skill 檔案並設定其範圍
+- [**代理提及**](/docs/agent-mentions) — `@` 提及與 `/` 指令的完整機制
+- [**定期工作**](/docs/recurring-jobs) — 排程由 Scheduled Tasks 建立的提示詞
+- [**Workspace 治理**](/docs/workspace-management) — 誰負責審查、核准和擁有 workspace 變更
+- [**多應用程式 Workspace**](/docs/multi-app-workspace) — 一個 workspace 所涵蓋的部署形態
+- [**Workspace 連線**](/docs/workspace-connections) — 在應用程式之間共用供應商憑證

package/docs/content/mcp-apps.mdx

@@ -5,7 +5,7 @@ description: "Author and embed interactive MCP App UIs inside Claude, ChatGPT, a
 
 # MCP Apps
 
-**This page: inline UIs in Claude/ChatGPT.** Authoring MCP App resources and the embed bridge that renders a real app route inside a compatible host's chat. This page is also the single home for the **client support matrix** ([below](#client-support)).
+**This page: inline UIs in Claude/ChatGPT.** Authoring MCP App resources and the embed bridge that renders a real app route inside a compatible host's chat. This page is also the single home for the **host support matrix** ([below](#client-support)).
 
 | If you want to…                                              | Read                                     |
 | ------------------------------------------------------------ | ---------------------------------------- |
@@ -13,7 +13,7 @@ description: "Author and embed interactive MCP App UIs inside Claude, ChatGPT, a
 | Give your agent more tools (consume other MCP servers)       | [MCP Clients](/docs/mcp-clients)         |
 | Build inline UIs that render in Claude/ChatGPT               | **This page** — MCP Apps                 |
 | Build generated inline UI inside Agent-Native chat           | [Generative UI](/docs/generative-ui)     |
-| Lower-level MCP server reference (auth, tools, custom mount) | [MCP Protocol](/docs/mcp-protocol)       |
+| Lower-level MCP server reference (auth, tools, custom mount) | [MCP Server](/docs/mcp-protocol)         |
 
 MCP Apps are the official `io.modelcontextprotocol/ui` extension that lets compatible hosts — Claude, Claude Desktop, ChatGPT, VS Code GitHub Copilot, Goose, Postman, MCPJam, and Cursor — render interactive UIs inline in chat. In agent-native apps, every MCP App is a **real React route**, not a separate plain-HTML widget.
 
@@ -95,22 +95,6 @@ Do not hand-write one-off plain HTML MCP Apps for product UI; if the action need
 
 </Diagram>
 
-```ts
-import { embedApp } from "@agent-native/core";
-
-export default defineAction({
-  // ...description, schema, run, link...
-  mcpApp: {
-    resource: embedApp({
-      title: "Review draft",
-      description: "Open the generated draft in the real Mail compose UI.",
-      iframeTitle: "Agent-Native Mail",
-      openLabel: "Open in Mail",
-    }),
-  },
-});
-```
-
 <AnnotatedCode
   id="doc-block-exq36i"
   title="The mcpApp resource config"
@@ -159,7 +143,7 @@ MCP App embeds are route embeds, not separate mini-products. `embedApp()` starts
       <strong>Claude web</strong
       ><span class="diagram-pill accent">single-frame transplant</span
       ><small class="diagram-muted"
-        >hydrates signed app HTML in Claude's iframe, then direct`ui/_` host
+        >hydrates signed app HTML in Claude's iframe, then direct `ui/*` host
         bridge</small
       >
     </div>
@@ -167,7 +151,7 @@ MCP App embeds are route embeds, not separate mini-products. `embedApp()` starts
       <strong>ChatGPT web</strong
       ><span class="diagram-pill accent">controlled route iframe</span
       ><small class="diagram-muted"
-        >`window.openai`host APIs ·`agentNative.mcpHost.*` postMessage
+        >`window.openai` host APIs · `agentNative.mcpHost.*` postMessage
         relay</small
       >
     </div>
@@ -214,19 +198,17 @@ MCP App embeds are route embeds, not separate mini-products. `embedApp()` starts
 
 Claude web uses a single-frame transplant path: the resource document fetches the signed app HTML and hydrates it inside Claude's MCP App iframe because Claude does not reliably allow app-owned child iframes or external frame navigation. ChatGPT web gets a controlled route iframe because its Apps bridge gives us stable `window.openai` host APIs and bounded height control. All paths point at the same signed app route and render the normal route and React components. Design embedded routes so a reload with the same signed URL reconstructs the same view.
 
-For same-app `open_app({ embed: true })`, the framework mints the embed-start ticket during the original tool call and stores the signed start URL in hidden tool metadata. Custom actions can return `embedStartUrl` for the same fast path; the MCP layer strips that ticket-bearing URL from model-visible `structuredContent` and normal open-link metadata. When no embed start URL is present, the resource falls back to the app-only `create_embed_session` helper. This keeps production hosts that restrict iframe-initiated tool calls on the direct route without leaking one-time app session URLs into the transcript. If a user reopens an old chat after a one-time start ticket has expired, the start route returns a small refresh page and posts `agentNative.embedSessionExpired` to the wrapper; `embedApp()` clears the stale start URL and mints a fresh ticket through `create_embed_session` when it still has the original app route.
-
-ChatGPT gets a dedicated compatibility path through `window.openai`: the launch document reads `toolInput`, `toolOutput`, and `toolResponseMetadata` directly, then calls `create_embed_session` via `window.openai.callTool(...)`. Standard MCP Apps hosts use the `ui/*` JSON-RPC bridge. Directly hydrated routes can call `ui/update-model-context`, `ui/message`, `ui/open-link`, and `ui/request-display-mode` through the host bridge helpers. Claude's transplanted route uses the same direct `ui/*` host bridge after hydration. When the ChatGPT or explicit diagnostic iframe path is used, the wrapper relays the same host actions over `agentNative.mcpHost.*` postMessage requests. Keep the result shape identical for both paths: return a focused `link` and concise structured content.
-
-Do not set standard `_meta.ui.domain` to an app URL. MCP Apps treats that field as host-specific: Claude validates `{hash}.claudemcpcontent.com`-style sandbox domains, while ChatGPT uses its own `openai/widgetDomain` metadata. Omit `ui.domain` unless you are deliberately emitting a host-specific value; the host will choose a default sandbox origin.
-
-Extension pages keep their sandbox in MCP chat embeds without navigating a second route iframe. Normal app usage renders `/_agent-native/extensions/:id/render` as a sandboxed child iframe. In MCP chat bridge mode the framework renders the same extension document as sandboxed `srcDoc` inside the route iframe, avoiding host `frame-ancestors` / `X-Frame-Options` failures while preserving `sandbox="allow-scripts allow-forms"`.
+A few bridge mechanics worth knowing:
 
-The resource shell owns the outer host size. `embedApp({ height })` defaults to `560px`, clamps the shell to `320-900px`, and reserves `44px` for the small toolbar, so the route viewport is `height - 44px`. Keep embedded app routes internally scrollable and let the launcher report that bounded intrinsic height rather than the full document height; otherwise host auto-resize can turn a normal app page into a very tall chat artifact. A changed shell only affects new MCP App resources and new tool calls. Old ChatGPT/Claude conversation frames can keep the previous resource behavior, so verify sizing with a fresh inline render before judging a fix.
+- **Embed-start tickets are reused, not re-minted, when possible.** For same-app `open_app({ embed: true })`, the framework mints the embed-start ticket during the original tool call and stores the signed start URL in hidden tool metadata. Custom actions can return `embedStartUrl` for the same fast path; the MCP layer strips that ticket-bearing URL from model-visible `structuredContent` and normal open-link metadata. When no embed start URL is present, the resource falls back to the app-only `create_embed_session` helper — this keeps production hosts that restrict iframe-initiated tool calls on the direct route without leaking one-time app session URLs into the transcript. If a user reopens an old chat after a one-time start ticket has expired, the start route returns a small refresh page and posts `agentNative.embedSessionExpired` to the wrapper; `embedApp()` clears the stale start URL and mints a fresh ticket through `create_embed_session` when it still has the original app route.
+- **ChatGPT's compatibility path** reads `toolInput`, `toolOutput`, and `toolResponseMetadata` directly through `window.openai`, then calls `create_embed_session` via `window.openai.callTool(...)`. Standard MCP Apps hosts use the `ui/*` JSON-RPC bridge instead — directly hydrated routes call `ui/update-model-context`, `ui/message`, `ui/open-link`, and `ui/request-display-mode` through the host bridge helpers, and Claude's transplanted route uses that same direct `ui/*` bridge after hydration. When the ChatGPT or explicit diagnostic iframe path is used, the wrapper relays the same host actions over `agentNative.mcpHost.*` postMessage requests instead. Keep the result shape identical for both paths: return a focused `link` and concise structured content.
+- **Don't set standard `_meta.ui.domain` to an app URL.** MCP Apps treats that field as host-specific: Claude validates `{hash}.claudemcpcontent.com`-style sandbox domains, while ChatGPT uses its own `openai/widgetDomain` metadata. Omit `ui.domain` unless you are deliberately emitting a host-specific value; the host will choose a default sandbox origin.
+- **Extension pages keep their sandbox** in MCP chat embeds without navigating a second route iframe. Normal app usage renders `/_agent-native/extensions/:id/render` as a sandboxed child iframe; in MCP chat bridge mode the framework renders the same extension document as sandboxed `srcDoc` inside the route iframe, avoiding host `frame-ancestors` / `X-Frame-Options` failures while preserving `sandbox="allow-scripts allow-forms"`.
+- **The resource shell owns the outer host size.** `embedApp({ height })` defaults to `560px`, clamps the shell to `320-900px`, and reserves `44px` for the small toolbar, so the route viewport is `height - 44px`. Keep embedded app routes internally scrollable and let the launcher report that bounded intrinsic height rather than the full document height — otherwise host auto-resize can turn a normal app page into a very tall chat artifact. A changed shell only affects new MCP App resources and new tool calls; old ChatGPT/Claude conversation frames can keep the previous resource behavior, so verify sizing with a fresh inline render before judging a fix.
 
 ### Embed modes {#embed-modes}
 
-Claude uses the single-frame transplant path by default. You can also force it in other hosts with `embedMode: "transplant"` or `frame: "transplant"` when debugging host module-loading behavior. You can force the nested diagnostic iframe with `embedMode: "iframe"`, `renderMode: "iframe"`, `nested: true`, or `frame: "iframe"`. If the iframe is blocked, `embedApp()` replaces it with an open-app fallback: the user can retry inline, open a freshly minted embed session through the host, or use the visible route URL. Keep the action's `link` target useful on its own because it is still the universal escape hatch.
+Claude uses the single-frame transplant path by default. You can also force it in other hosts with `embedMode: "transplant"` when debugging host module-loading behavior, or force the nested diagnostic iframe with `embedMode: "iframe"`. `embedMode` is the canonical option name; `renderMode`, `frame`, and `nested: true` (for the iframe case) are recognized aliases kept for compatibility — prefer `embedMode` in new code. If the iframe is blocked, `embedApp()` replaces it with an open-app fallback: the user can retry inline, open a freshly minted embed session through the host, or use the visible route URL. Keep the action's `link` target useful on its own because it is still the universal escape hatch.
 
 When testing Claude through ngrok, use a production build (`npx @agent-native/core@latest build` then `npx @agent-native/core@latest start`) or a deployed preview/production URL. Claude's single-frame transplant path works with production asset chunks; raw Vite dev modules such as `/app/root.tsx` can be protected by app auth and fail dynamic imports from the Claude resource origin.
 
@@ -249,7 +231,7 @@ Embedded routes can use `updateMcpAppModelContext()`, `openMcpAppHostLink()`, `r
 
 Display mode is best-effort. The in-app `McpAppRenderer` currently reports an inline web host context and an inline-only display mode; external hosts may honor larger display requests, ignore them, or reply with an unsupported-mode error. Always keep the inline route usable.
 
-## Client support and caching {#client-support}
+## Host support and caching {#client-support}
 
 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.
 
@@ -261,9 +243,9 @@ Claude and ChatGPT can cache tool and resource metadata for an existing custom c
 
 Test MCP Apps with the lightweight fixtures around `embedApp()` and `McpAppRenderer`; they cover CSP, host context, app launch, and bridge message behavior without needing a real external host. When validating ChatGPT or Claude web, trigger a fresh tool call after shell changes and measure the visible iframe. Previously rendered frames in the same conversation may still show cached height or launch behavior.
 
-## Related {#related}
+## What's next {#whats-next}
 
 - [External Agents](/docs/external-agents) — connecting Claude, ChatGPT, Codex, and Cursor to hosted apps; MCP Apps compatibility matrix; catalog tiers; deep links.
-- [MCP Protocol](/docs/mcp-protocol) — the auto-mounted MCP server, auth, tools, and `ask-agent`.
+- [MCP Server](/docs/mcp-protocol) — the auto-mounted MCP server, auth, tools, and `ask-agent`.
 - [Actions](/docs/actions) — `defineAction`, the `link` builder, `publicAgent`.
 - [Generative UI](/docs/generative-ui) — generated inline UI inside the app's own chat.

package/docs/content/mcp-clients.mdx

@@ -5,14 +5,15 @@ description: "Connect your agent-native app to local MCP servers (claude-in-chro
 
 # MCP Clients
 
-**This page: give your agent more tools.** Point an agent-native app at MCP servers — local or remote — so their tools show up in the agent chat. This is the _client_ direction, the mirror image of [MCP Protocol](/docs/mcp-protocol) (which makes your app an MCP _server_).
+**This page: give your agent more tools.** Point an agent-native app at MCP servers — local or remote — so their tools show up in the agent chat. This is the _client_ direction, the mirror image of [MCP Server](/docs/mcp-protocol) (which makes your app an MCP _server_). Note the dual use of "client" here: this page is about your app acting as an MCP client of _other_ servers — a different sense from an "MCP host" like Claude or Cursor connecting to your app (see [MCP Server](/docs/mcp-protocol) for that direction).
 
 | 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)       | **This page** — MCP Clients              |
 | Build inline UIs that render in Claude/ChatGPT               | [MCP Apps](/docs/mcp-apps)               |
-| Lower-level MCP server reference (auth, tools, custom mount) | [MCP Protocol](/docs/mcp-protocol)       |
+| Build generated inline UI inside Agent-Native chat           | [Generative UI](/docs/generative-ui)     |
+| Lower-level MCP server reference (auth, tools, custom mount) | [MCP Server](/docs/mcp-protocol)         |
 
 With one config file, every agent-native app in your workspace gains access to tools provided by MCP servers on your machine: `claude-in-chrome` for browser automation, `@modelcontextprotocol/server-filesystem` for reading files, `@playwright/mcp` for browser testing, and anything else that speaks MCP.
 
@@ -96,7 +97,7 @@ Every source resolves into one runtime **MCP manager**, and every tool it learns
 
 </Diagram>
 
-> The opposite direction — making _your_ app an MCP server that other hosts consume — lives in [MCP Protocol](/docs/mcp-protocol) and [External Agents](/docs/external-agents).
+> The opposite direction — making _your_ app an MCP server that other hosts consume — lives in [MCP Server](/docs/mcp-protocol) and [External Agents](/docs/external-agents).
 
 ## Built-in browser and computer-use capabilities {#built-in-capabilities}
 
@@ -309,9 +310,43 @@ Stdio servers are still a no-op outside Node runtimes, but remote HTTP MCP serve
 
 ## Shared MCP servers via a hub {#hub}
 
-If your workspace runs multiple agent-native apps (e.g. dispatch + mail + clips), you can configure **one** app as the hub and have the others pull its org-scope MCP servers automatically. No per-app copy-paste of URLs and bearer tokens. See [Multi-App Workspace](/docs/multi-app-workspace) for the canonical approach using Dispatch workspace MCP resources.
+If your workspace runs multiple agent-native apps (e.g. dispatch + mail + clips), share MCP servers across all of them without per-app copy-pasting of URLs and bearer tokens. See [Multi-App Workspace](/docs/multi-app-workspace) for the full deployment picture.
 
-Dispatch is the conventional hub — it already coordinates across apps.
+### Recommended: Dispatch workspace MCP resources {#hub-recommended}
+
+For new workspace setups, prefer **Dispatch workspace MCP resources** — the
+same All-app vs selected-app grant model used by workspace skills,
+instructions, and reference resources. Add a workspace resource with:
+
+```json
+{
+  "type": "http",
+  "url": "https://example.com/mcp",
+  "headers": {
+    "Authorization": "Bearer ${keys.MCP_SERVER_TOKEN}"
+  },
+  "description": "Shared MCP tools for workspace apps"
+}
+```
+
+Save it under `mcp-servers/<name>.json` with kind `mcp-server`. All-app
+resources are loaded by every workspace app; selected resources load only in
+apps with an active Dispatch grant. Secret placeholders resolve from the app
+secret store, so put raw bearer tokens in Dispatch Vault and reference them
+with `${keys.NAME}` instead of storing them in the resource body.
+
+Apps refresh their merged MCP config about once a minute, so central resource
+edits, grant changes, and removals take effect without a deploy. Set
+`AGENT_NATIVE_MCP_CONFIG_REFRESH_MS=0` to disable that background refresh, or
+set it to a value of at least `5000` milliseconds to tune the interval.
+
+### Legacy: self-hosted hub mode {#hub-legacy}
+
+The mode below remains useful for coarse "share every org-scope MCP server
+from Dispatch" setups and for deployments that already use the MCP settings UI
+as the source of truth. You configure **one** app as the hub and the others
+pull its org-scope MCP servers automatically. Dispatch is the conventional hub
+— it already coordinates across apps.
 
 <Diagram id="doc-block-1dnioze" title="Hub model: one app serves org-scope MCP servers" summary={"Dispatch holds the org-scope MCP servers; consumer apps pull and merge them as mcp__hub_<orgId>_<name>__*. Only org-scope rows are shared — personal credentials stay put."}>
 
@@ -376,36 +411,6 @@ Dispatch is the conventional hub — it already coordinates across apps.
 
 </Diagram>
 
-For new workspace setups, prefer **Dispatch workspace MCP resources** when you
-want the same All-app vs selected-app grant model used by workspace skills,
-instructions, and reference resources. Add a workspace resource with:
-
-```json
-{
-  "type": "http",
-  "url": "https://example.com/mcp",
-  "headers": {
-    "Authorization": "Bearer ${keys.MCP_SERVER_TOKEN}"
-  },
-  "description": "Shared MCP tools for workspace apps"
-}
-```
-
-Save it under `mcp-servers/<name>.json` with kind `mcp-server`. All-app
-resources are loaded by every workspace app; selected resources load only in
-apps with an active Dispatch grant. Secret placeholders resolve from the app
-secret store, so put raw bearer tokens in Dispatch Vault and reference them
-with `${keys.NAME}` instead of storing them in the resource body.
-
-Apps refresh their merged MCP config about once a minute, so central resource
-edits, grant changes, and removals take effect without a deploy. Set
-`AGENT_NATIVE_MCP_CONFIG_REFRESH_MS=0` to disable that background refresh, or
-set it to a value of at least `5000` milliseconds to tune the interval.
-
-The older hub mode below remains useful for coarse “share every org-scope MCP
-server from Dispatch” setups and for deployments that already use the MCP
-settings UI as the source of truth.
-
 ### 1. Enable hub-serve on the hub app (dispatch)
 
 Set an env var in dispatch's deployment:
@@ -456,28 +461,10 @@ Every app exposes `GET /_agent-native/mcp/status` for tooling and onboarding:
   }
 ]}>
 
-Reports which configured servers connected, the total live tool count, the merged prefixed tool list, and any per-server connection errors. Use it to build "detected — your agent can now drive X" hints or to debug connection problems.
+Reports which configured servers connected, the total live tool count, the merged prefixed tool list, and any per-server connection errors. Use it to build "detected — your agent can now drive X" hints (e.g. "claude-in-chrome detected — your agent can now drive Chrome") or to debug connection problems.
 
 </Endpoint>
 
-```json
-{
-  "configuredServers": ["claude-in-chrome", "playwright"],
-  "connectedServers": ["claude-in-chrome", "playwright"],
-  "totalTools": 21,
-  "tools": [
-    {
-      "source": "claude-in-chrome",
-      "name": "mcp__claude-in-chrome__navigate",
-      "description": "Navigate the browser to a URL"
-    }
-  ],
-  "errors": {}
-}
-```
-
-Use this to build "claude-in-chrome detected — your agent can now drive Chrome" onboarding hints, or debug MCP connection problems.
-
 ## Failure modes {#failures}
 
 Individual MCP server failures never take down the agent:
@@ -491,3 +478,10 @@ Agent-native will always boot; broken MCP configuration just means fewer tools.
 ## Security {#security}
 
 MCP tools run on your machine with whatever permissions the spawned process has. Treat `mcp.config.json` like any other list of executables you're willing to let the agent drive. Tools from MCP servers appear in the agent's tool-use loop just like your template's own actions, so make sure you trust every server you configure.
+
+## What's next {#whats-next}
+
+- [**MCP Server**](/docs/mcp-protocol) — the opposite direction: making your app an MCP server other hosts consume
+- [**External Agents**](/docs/external-agents) — connecting Claude, Cursor, and other hosts to your app
+- [**Multi-App Workspace**](/docs/multi-app-workspace) — the shared-resource model behind Dispatch workspace MCP resources
+- [**Actions**](/docs/actions) — how your own actions show up alongside MCP tools in the agent's registry

package/docs/content/mcp-protocol.mdx

@@ -1,9 +1,9 @@
 ---
-title: "MCP Protocol"
+title: "MCP Server"
 description: "Expose your agent-native app as a remote MCP server so Claude, ChatGPT, Claude Code, Cursor, and other AI tools can call your app's actions directly."
 ---
 
-# MCP Protocol
+# MCP Server
 
 **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).
 
@@ -12,13 +12,14 @@ description: "Expose your agent-native app as a remote MCP server so Claude, Cha
 | 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             |
+| Build generated inline UI inside Agent-Native chat           | [Generative UI](/docs/generative-ui)     |
+| Lower-level MCP server reference (auth, tools, custom mount) | **This page** — MCP Server               |
 
 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}
 
-MCP is the standard protocol for connecting AI tools to external capabilities. When you deploy an agent-native app, it auto-mounts an MCP endpoint alongside the existing A2A endpoint. Any MCP-compatible client can connect and use your app's tools.
+MCP is the standard protocol for connecting AI tools to external capabilities. When you deploy an agent-native app, it auto-mounts an MCP endpoint alongside the existing A2A endpoint. Any MCP-compatible host can connect and use your app's tools.
 
 Key concepts:
 
@@ -100,9 +101,9 @@ Both protocols are auto-mounted. Use whichever fits your use case:
 
 You can also use the `ask-agent` MCP tool to get the best of both worlds — call it from Claude Code and let your app's agent reason through complex tasks.
 
-## Manual MCP client config {#manual-config}
+## Manual MCP host config {#manual-config}
 
-For the recommended one-command setup, use [External Agents](/docs/external-agents). If you are hand-writing MCP config for an OAuth-capable client, add your app as a remote MCP server with no static headers:
+For the recommended one-command setup, use [External Agents](/docs/external-agents). If you are hand-writing MCP config for an OAuth-capable host, add your app as a remote MCP server with no static headers:
 
 ```bash
 claude mcp add --transport http mail https://mail.example.com/_agent-native/mcp
@@ -130,9 +131,9 @@ Then run `/mcp` in Claude Code and choose **Authenticate**. For clients that can
 Claude Code calls: draft-email(to: "john@example.com", subject: "Q3 Report", body: "...")
 ```
 
-## Connecting from other MCP clients {#other-clients}
+## Connecting from other MCP hosts {#other-clients}
 
-Any MCP client that supports Streamable HTTP transport can connect. The endpoint is:
+Any MCP host that supports Streamable HTTP transport can connect. The endpoint is:
 
 ```
 POST https://your-app.example.com/_agent-native/mcp
@@ -140,7 +141,7 @@ POST https://your-app.example.com/_agent-native/mcp
 
 The server supports the standard MCP handshake: `initialize` → `initialized` → `tools/list` → `tools/call`.
 
-<Endpoint id="doc-block-86ic5g" title="MCP endpoint" summary="The auto-mounted Streamable HTTP endpoint every agent-native app exposes." method="POST" path="/_agent-native/mcp" summary="MCP Streamable HTTP endpoint" auth="Standard remote MCP OAuth (Bearer access token), connect-minted JWT, or static ACCESS_TOKEN/ACCESS_TOKENS" params={[
+<Endpoint id="doc-block-86ic5g" title="MCP endpoint" summary="The auto-mounted Streamable HTTP endpoint every agent-native app exposes." method="POST" path="/_agent-native/mcp" auth="Standard remote MCP OAuth (Bearer access token), connect-minted JWT, or static ACCESS_TOKEN/ACCESS_TOKENS" params={[
   {
     "name": "Authorization",
     "in": "header",
@@ -173,7 +174,13 @@ Auto-mounted on every app. Speaks the standard MCP handshake (`initialize` → `
 
 </Endpoint>
 
-If an action declares `mcpApp`, the server also advertises the official MCP Apps extension (`io.modelcontextprotocol/ui`) and supports `resources/list`, `resources/templates/list`, and `resources/read` for the app resource. Hosts that render MCP Apps can show the UI inline; hosts that do not can still call the tool and use the deep-link fallback. Product UIs should use `embedApp()` so the inline surface is the real React app route, or a focused route that renders a shared React component such as an Analytics chart, not a separate plain HTML implementation. The server emits both standard MCP Apps metadata and ChatGPT Apps SDK compatibility metadata so app-capable hosts can find the same `ui://` resource. The current official extension matrix includes Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT, and Cursor; host support varies by version and plan, so use the [External Agents MCP Apps notes](/docs/external-agents#mcp-apps-compatibility) for the user-facing guidance.
+If an action declares `mcpApp`, the server advertises the official MCP Apps extension and supports the resource routes needed to render it inline:
+
+- Advertises `io.modelcontextprotocol/ui` and supports `resources/list`, `resources/templates/list`, and `resources/read` for the app resource.
+- Hosts that render MCP Apps show the UI inline; hosts that don't can still call the tool and use the deep-link fallback.
+- Product UIs should use `embedApp()` so the inline surface is the real React app route, or a focused route that renders a shared React component such as an Analytics chart — never a separate plain-HTML implementation.
+- The server emits both standard MCP Apps metadata and ChatGPT Apps SDK compatibility metadata so app-capable hosts find the same `ui://` resource.
+- The current official extension matrix includes Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT, and Cursor. Host support varies by version and plan — see the [External Agents MCP Apps notes](/docs/external-agents#mcp-apps-compatibility) for the user-facing guidance.
 
 ### MCP App embed bridge {#mcp-app-embed-bridge}
 
@@ -385,3 +392,11 @@ For more complex analysis:
 Claude Code calls: ask-agent(message: "Prepare a full breakdown of Q3 signups by source, with trends")
 → The analytics agent runs multiple queries, reasons about the data, and returns a formatted report
 ```
+
+## What's next {#whats-next}
+
+- [**External Agents**](/docs/external-agents) — the recommended connect flow, catalog tiers, and per-host setup
+- [**MCP Apps**](/docs/mcp-apps) — inline UI resources for hosts that render them
+- [**MCP Clients**](/docs/mcp-clients) — the other direction: your app consuming external MCP servers
+- [**A2A Protocol**](/docs/a2a-protocol) — the sibling protocol for agent-to-agent calls
+- [**Actions**](/docs/actions) — how an action becomes an MCP tool