@agent-native/core 0.109.3 → 0.110.0

package/docs/content/locales/zh-TW/agent-native-toolkit.mdx

@@ -1,23 +1,15 @@
 ---
-title: "Toolkits"
-description: "Battle-tested reusable building blocks for high-quality agentic applications: collaboration, sharing, settings, teams, setup, navigation, resources, agent UX, history, comments, and observability."
+title: "Toolkit"
+description: "一個均衡的目錄，涵蓋可重用基礎、編輯器與畫布、智慧代理脈絡、治理、工作區框架、營運以及 Toolkit 能力模組。"
 ---
 
 <!-- i18n-docs-ignore -->
 
-# Toolkits
+# Toolkit
 
-Toolkits are reusable, battle-tested building blocks for high-quality agentic
-applications. They turn the hard product work that repeats across apps into
-standard surfaces: realtime collaboration between humans and agents, sharing
-with humans and agents, settings, teams, setup, resources, history, review, and
-observability.
+Toolkit 是面向高品質智慧代理應用程式、可重複使用且經過實戰驗證的建構元件。它將跨應用程式反覆出現的困難產品工作轉化為標準介面：人類與智慧代理之間的即時協作、面向人類和智慧代理的分享、設定、團隊、設定流程、資源、歷程、審閱和可觀測性。
 
-Each kit packages the UI patterns, action contracts, app-state expectations,
-access boundaries, and agent-visible behavior that users expect to work
-consistently. Apps still own their domain model and visual identity; toolkits
-make the common product systems feel complete from the first version instead of
-being rebuilt in slightly different ways every time.
+每個套件都封裝了使用者期待能持續一致運作的 UI 模式、動作契約、應用程式狀態預期、存取邊界和智慧代理可見行為。應用程式仍擁有自己的領域模型和視覺識別；Toolkit 讓通用產品系統從第一個版本起就完整可用，而不是每次以稍有不同的方式重新建立。
 
 <WireframeBlock id="doc-block-toolkits-index">
   <Screen
@@ -28,23 +20,23 @@ being rebuilt in slightly different ways every time.
   />
 </WireframeBlock>
 
-<Diagram id="doc-block-toolkits-boundary" title="How kits fit" summary={"The framework runtime supplies durable guarantees. Toolkits turn those guarantees into reusable product systems. Apps add domain-specific data, routes, and visual identity."}>
+<Diagram id="doc-block-toolkits-boundary" title="套件如何融入" summary={"框架執行階段提供持久保證。Toolkit 將這些保證轉化為可重複使用的產品系統。應用程式再加入領域特定的資料、路由和視覺識別。"}>
 
 ```html
 <div class="diagram-row">
   <div class="diagram-card">
-    <span class="diagram-pill accent">Runtime</span><br />
-    actions, SQL, auth, app state, access checks, realtime transport
+    <span class="diagram-pill accent">執行階段</span><br />
+    動作、SQL、驗證、應用程式狀態、存取檢查、即時傳輸
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
   <div class="diagram-card">
-    <span class="diagram-pill accent">Toolkits</span><br />
-    collaboration, sharing, setup, review, history, observability
+    <span class="diagram-pill accent">Toolkit</span><br />
+    協作、分享、設定流程、審閱、歷程、可觀測性
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
   <div class="diagram-card">
-    <span class="diagram-pill accent">Apps</span><br />
-    domain schema, routes, actions, branding, specialized workflows
+    <span class="diagram-pill accent">應用程式</span><br />
+    領域結構描述、路由、動作、品牌、專門工作流程
   </div>
 </div>
 ```
@@ -68,45 +60,60 @@ being rebuilt in slightly different ways every time.
 
 </Diagram>
 
-## The Kits {#the-kits}
-
-| Kit                                                      | Use it for                                                                                                  |
-| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| [Sharing](/docs/toolkit-sharing)                         | Ownable resources, share dialogs, visibility badges, share actions, public/private/org access.              |
-| [Collaboration](/docs/toolkit-collaboration)             | Realtime editing, presence, live cursors, recent-edit highlights, collaborative undo.                       |
-| [Settings](/docs/toolkit-settings)                       | Standard settings pages and tabs so app settings and agent/provider settings live in one predictable place. |
-| [Org & Team](/docs/toolkit-org-team)                     | Team pages, org switching, invites, org domains, roles, and app switching.                                  |
-| [Setup & Connections](/docs/toolkit-setup-connections)   | Onboarding, secrets, workspace connections, OAuth/provider readiness, and Builder connect.                  |
-| [Command & Navigation](/docs/toolkit-command-navigation) | Command menu, deep links, standard app routes, sidebar and shell patterns.                                  |
-| [Resources](/docs/toolkit-resources)                     | Resource trees, editors, file picker/search, attachments, and local file mode.                              |
-| [Agent UX](/docs/toolkit-agent-ux)                       | Composer, model picker, context chips, approvals, run recovery, and the runs tray.                          |
-| [History](/docs/toolkit-history)                         | Version history, audit logs, undo/redo, restore, and "what changed" surfaces.                               |
-| [Comments & Review](/docs/toolkit-comments-review)       | Inline comments, annotations, mentions, resolved threads, review status.                                    |
-| [Observability](/docs/toolkit-observability)             | Usage, spend, feedback, replay, errors, and run diagnostics.                                                |
-
-## Implementation Boundary {#implementation-boundary}
-
-Kits are product surfaces first. Some pieces are runtime-backed
-(`@agent-native/core`), some are presentation primitives
-(`@agent-native/toolkit`), and apps usually wrap both through local adapters.
-Use the package path that owns the needed behavior, but design the user-facing
-settings, collaboration, sharing, team, review, and setup experiences as one
-coherent kit instead of exposing package boundaries in the app.
-
-## Foundation Pieces {#foundation-pieces}
-
-- [UI Primitives](/docs/toolkit-ui) cover shared shadcn-style primitives under
-  `@agent-native/toolkit/ui/*`.
-- [App Adapters](/docs/toolkit-ui#app-adapters) show how apps wrap Toolkit pieces
-  through local `@/components/*` adapters.
-- [Shell & Hooks](/docs/toolkit-ui#shell-hooks) cover header actions, mobile hooks,
-  toasts, and small app-shell helpers.
-- [Component API](/docs/components) remains the lower-level reference for the
-  public React exports.
-
-## Design Rule {#design-rule}
-
-Use a toolkit when the behavior repeats across apps and users expect it to feel
-standard: sharing, settings, teams, comments, history, and agent progress should
-not be slightly different in every template. Keep domain-specific data,
-workflows, labels, and visual styling in the app.
+## 目錄 {#catalog}
+
+| 領域               | 從這裡開始                                     | 涵蓋內容                                                     |
+| ------------------ | ---------------------------------------------- | ------------------------------------------------------------ |
+| 基礎               | [UI 原語](/docs/toolkit-ui)                    | 共用控制項、Hook、應用程式配接器和 Shell 接點。              |
+| 編輯器與畫布       | [編輯器與畫布](/docs/toolkit-editors-canvases) | 豐富編輯、結構化區塊、可重用畫布控制項和 Design 模式。       |
+| 智慧代理體驗與脈絡 | [脈絡與知識](/docs/toolkit-context-knowledge)  | Context X-Ray、資源、知識、Composer 脈絡和智慧代理可見狀態。 |
+| 協作與治理         | [協作](/docs/toolkit-collaboration)            | 分享、在線狀態、審閱、歷程、稽核和組織邊界。                 |
+| 工作區框架         | [應用程式框架](/docs/toolkit-settings)         | 設定、團隊、設定流程、導覽、資源和智慧代理 UX。              |
+| 營運               | [可觀測性](/docs/toolkit-observability)        | 使用情況、意見回饋、重播、診斷和營運可見性。                 |
+| Toolkit 能力模組   | [能力套件](/docs/toolkit-capability-packages)  | 依需要安裝的領域套件及其生命週期資訊清單。                   |
+
+## 產品套件 {#product-kits}
+
+| 套件                                              | 用途                                                                           |
+| ------------------------------------------------- | ------------------------------------------------------------------------------ |
+| [分享](/docs/toolkit-sharing)                     | 可擁有資源、分享對話方塊、可見性徽章、分享動作、公開／私人／組織存取。         |
+| [協作](/docs/toolkit-collaboration)               | 即時編輯、在線狀態、即時游標、最近編輯醒目提示、協作復原。                     |
+| [設定](/docs/toolkit-settings)                    | 標準設定頁面和分頁，讓應用程式設定與智慧代理／提供者設定位於一個可預期的位置。 |
+| [組織與團隊](/docs/toolkit-org-team)              | 團隊頁面、組織切換、邀請、組織網域、角色和應用程式切換。                       |
+| [設定流程與連線](/docs/toolkit-setup-connections) | 上手引導、密鑰、工作區連線、OAuth／提供者就緒狀態和 Builder 連線。             |
+| [命令與導覽](/docs/toolkit-command-navigation)    | 命令選單、深層連結、標準應用程式路由、側欄和 Shell 模式。                      |
+| [資源](/docs/toolkit-resources)                   | 資源樹、編輯器、檔案選擇／搜尋、附件和本機檔案模式。                           |
+| [智慧代理 UX](/docs/toolkit-agent-ux)             | Composer、模型選擇器、脈絡籤、核准、執行復原和執行托盤。                       |
+| [歷程](/docs/toolkit-history)                     | 版本歷程、稽核日誌、復原／重做、還原和「有何變更」介面。                       |
+| [評論與審閱](/docs/toolkit-comments-review)       | 內嵌評論、註解、提及、已解決討論串和審閱狀態。                                 |
+| [可觀測性](/docs/toolkit-observability)           | 使用量、支出、意見回饋、重播、錯誤和執行診斷。                                 |
+
+## 套件成熟度與所有權 {#package-maturity-and-ownership}
+
+- 豐富編輯器由 **Toolkit** 擁有；移轉期間，現有 Core import 持續作為精簡的相容性 re-export。
+- Design 是使用可重用 `design-tweaks` 的**範本模式**，不是完整的即插即用編輯器或畫布。
+- 此階段 Blocks 和 Context X-Ray 引擎仍由 **Core** 擁有；可重用的 Context X-Ray 呈現由 Toolkit 擁有。
+- Creative Context、Scheduling 和 Pinpoint 是依需要安裝的 **Toolkit 能力模組**；它們保留獨立 npm 套件和生命週期資訊清單。Dispatch 仍是獨立產品。
+
+## 實作邊界 {#implementation-boundary}
+
+套件首先是產品介面。有些部分由執行階段支援（`@agent-native/core`），有些是呈現原語（`@agent-native/toolkit`），應用程式通常會透過本機配接器封裝兩者。請使用擁有所需行為的套件路徑，但將面向使用者的設定、協作、分享、團隊、審閱和設定流程體驗設計為一個連貫的套件，而不要在應用程式中暴露套件邊界。
+
+## 基礎元件 {#foundation-pieces}
+
+- [UI 原語](/docs/toolkit-ui) 涵蓋 `@agent-native/toolkit/ui/*` 下共用的 shadcn 風格原語。
+- [應用程式配接器](/docs/toolkit-ui#app-adapters) 說明應用程式如何透過本機 `@/components/*` 配接器封裝 Toolkit 元件。
+- [Shell 與 Hook](/docs/toolkit-ui#shell-hooks) 涵蓋頁首動作、行動裝置 Hook、Toast 和小型應用程式 Shell 輔助工具。
+- [元件 API](/docs/components) 仍是公開 React 匯出的低階參考。
+
+## 設計規則 {#design-rule}
+
+當行為在各應用程式間重複出現，且使用者期待標準體驗時，請使用 Toolkit：分享、設定、團隊、評論、歷程和智慧代理進度不應在每個範本中略有不同。請將領域特定的資料、工作流程、標籤和視覺樣式保留在應用程式中。
+
+## 下一步
+
+- [**Toolkit UI 原語**](/docs/toolkit-ui) — 共用原語、應用程式配接器和 Shell Hook。
+- [**分享套件**](/docs/toolkit-sharing) — 資源、分享對話框和可見性的良好起點。
+- [**建立範本**](/docs/creating-templates) — 端到端建立範本，並了解套件如何融入其中。
+- [**元件 API**](/docs/components) — 所有公開 React 匯出的參考。
+- [**套件生命週期**](/docs/package-lifecycle) — 安全地檢查、新增和彈出由資訊清單驅動的 Toolkit 能力模組。

package/docs/content/locales/zh-TW/agent-surfaces.mdx

@@ -14,8 +14,7 @@ search: "無頭代理豐富聊天完整應用程式 BYO 代理執行時 AgentCha
 而不必重複這些流程。
 
 ```tsx filename="app/routes/agent.tsx"
-import { AgentTabsPage } from "@agent-native/core/client";
-
+import { AgentTabsPage } from "@agent-native/core/client/agent-chat";
 export default function AgentRoute() {
   return <AgentTabsPage />;
 }
@@ -406,8 +405,7 @@ export default createAgentNativeEmbeddedPlugin({
 React sidecar 傳遞頁面脈絡和主機指令：
 
 ```tsx
-import { AgentNativeEmbedded } from "@agent-native/core/client";
-
+import { AgentNativeEmbedded } from "@agent-native/core/client/host";
 export function AppShell({ children }) {
   return (
     <AgentNativeEmbedded

package/docs/content/locales/zh-TW/audit-log.mdx

@@ -82,8 +82,7 @@ export default defineAction({
 透過使用 `useActionQuery` 從 UI 呼叫 `list-audit-events` 來建置活動來源或“誰更改了此”行 - 切勿手寫對審核表的擷取：
 
 ```tsx
-import { useActionQuery } from "@agent-native/core/client";
-
+import { useActionQuery } from "@agent-native/core/client/hooks";
 const { data } = useActionQuery("list-audit-events", {
   targetType: "recording",
   targetId: recordingId,

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

@@ -363,8 +363,9 @@ interface AuthSession {
 在用戶端上，使用 `useSession()` 掛鉤：
 
 ```ts
-import { useSession } from "@agent-native/core/client";
-
+import {
+  useSession,
+} from "@agent-native/core/client/hooks"
 function MyComponent() {
   const { session, isLoading } = useSession();
   if (isLoading) return <p>Loading...</p>;

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

@@ -65,8 +65,7 @@ import {
   useActionQuery,
   useActionMutation,
   callAction,
-} from "@agent-native/core/client";
-
+} from "@agent-native/core/client/hooks";
 // Read: auto-cached, auto-invalidated on mutations
 const { data, isLoading } = useActionQuery("get-lead", { leadId });
 
@@ -83,8 +82,7 @@ await callAction("archive-lead", { leadId });
 透過 postMessage 向代理聊天傳送訊息——這是從 UI 互動中委派 AI 工作的常用方法。傳遞 `context` 來隱藏模型脈絡，傳遞 `submit: true` 來立即傳送，或者傳遞 `submit: false` 來預先填寫使用者首先審閱的草稿。
 
 ```ts
-import { sendToAgentChat } from "@agent-native/core/client";
-
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
 // Auto-submit a prompt with hidden context
 sendToAgentChat({
   message: "Generate alt text for this image",
@@ -174,8 +172,7 @@ overwrite the user's active conversation. Use the returned `tabId` if the UI
 `"automations"`、`"voice"` 或 `"limits"` 開啟特定部分。
 
 ```ts
-import { openAgentSettings } from "@agent-native/core/client";
-
+import { openAgentSettings } from "@agent-native/core/client/navigation";
 openAgentSettings();
 openAgentSettings("secrets");
 ```
@@ -183,8 +180,7 @@ openAgentSettings("secrets");
 更喜歡這個助手而不是直接調度 `agent-panel:open-settings`。
 
 ```tsx
-import { useAgentChatContext } from "@agent-native/core/client";
-
+import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
 function SelectionContextButton({ record }: { record: { id: string } }) {
   const chatContext = useAgentChatContext();
   const contextKey = `selected-record:${record.id}`;
@@ -242,8 +238,10 @@ function SelectionContextButton({ record }: { record: { id: string } }) {
 用於自由形式細節的組合器，以及用於多欄位輸入的表單/快顯框。
 
 ```tsx
-import { askUserQuestion, sendToAgentChat } from "@agent-native/core/client";
-
+import {
+  askUserQuestion,
+  sendToAgentChat,
+} from "@agent-native/core/client/agent-chat";
 const length = await askUserQuestion({
   question: "How long should this deck be?",
   header: "Deck length", // optional short chip/heading (≈12 chars)
@@ -286,7 +284,7 @@ import {
   requestMcpAppDisplayMode,
   updateMcpAppModelContext,
   useMcpAppHostContext,
-} from "@agent-native/core/client";
+} from "@agent-native/core/client/agent-chat";
 ```
 
 `getMcpAppHostContext()`讀取最新推送的主機脈絡快照；
@@ -321,8 +319,9 @@ import {
 React 鉤子，透過載入狀態跟蹤包裝 sendToAgentChat：
 
 ```ts
-import { useAgentChatGenerating } from "@agent-native/core/client";
-
+import {
+  useAgentChatGenerating,
+} from "@agent-native/core/client/agent-chat"
 function GenerateButton() {
   const [isGenerating, send] = useAgentChatGenerating();
 
@@ -348,7 +347,9 @@ function GenerateButton() {
 React 掛鉤（以前稱為 `useFileWatcher`），用於偵聽 SSE 上的資料庫更改，回退到輪詢，並使保持 UI 與代理寫入保持一致的框架查詢快取無效：
 
 ```ts
-import { useDbSync } from "@agent-native/core/client";
+import {
+  useDbSync,
+} from "@agent-native/core/client/hooks"
 import { useQueryClient } from "@tanstack/react-query";
 
 function App() {
@@ -393,8 +394,7 @@ function App() {
 
 ```tsx
 import { useQuery } from "@tanstack/react-query";
-import { useChangeVersion } from "@agent-native/core/client";
-
+import { useChangeVersion } from "@agent-native/core/client/hooks";
 function DashboardView({ id }) {
   // Get version for dashboards domain source
   const v = useChangeVersion("dashboards");
@@ -459,8 +459,9 @@ function DashboardView({ id }) {
 合併類名的實用程式（clsx + tailwind-merge）：
 
 ```ts
-import { cn } from "@agent-native/core/client";
-
+import {
+  cn,
+} from "@agent-native/toolkit/utils"
 <div className={cn(
   "px-4 py-2 rounded",
   isActive && "bg-primary text-primary-foreground",

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

@@ -13,7 +13,7 @@ Agent-Native 附帶了完整的側邊欄，但側邊欄不是合同。
 從聚焦的用戶端子路徑匯入瀏覽器 UI：
 
 ```tsx
-import { AgentSidebar } from "@agent-native/core/client";
+import { AgentSidebar } from "@agent-native/core/client/agent-chat";
 import { PromptComposer } from "@agent-native/core/client/composer";
 import { AgentConversation } from "@agent-native/core/client/conversation";
 import { usePresence } from "@agent-native/core/client/collab";

package/docs/content/locales/zh-TW/context-awareness.mdx

@@ -196,8 +196,7 @@ if (url?.searchParams) {
 當使用者選取、聚焦或多選有意義的物件時，從 UI 寫入：
 
 ```tsx
-import { setClientAppState } from "@agent-native/core/client";
-
+import { setClientAppState } from "@agent-native/core/client/hooks";
 async function syncSelection(selection: unknown | null) {
   await setClientAppState("selection", selection, { keepalive: true });
 }
@@ -226,8 +225,7 @@ async function syncSelection(selection: unknown | null) {
 當自訂編輯器的選取不由本機瀏覽器選取表示時，可以編寫相同的鍵：
 
 ```tsx
-import { setClientAppState } from "@agent-native/core/client";
-
+import { setClientAppState } from "@agent-native/core/client/hooks";
 await setClientAppState(
   "pending-selection-context",
   {
@@ -289,8 +287,7 @@ await setClientAppState(
 有時脈絡不應該僅僅處於應用程式狀態。使用者點選按鈕、放下評論圖釘、選取專案並選取“詢問代理”，或者按下工具列中的 AI 指令。那次點選是一個指令。在瀏覽器 UI 中，將其交給帶有`sendToAgentChat()`的代理。
 
 ```tsx
-import { sendToAgentChat } from "@agent-native/core/client";
-
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
 function askAgentAboutSelection(selection: {
   documentId: string;
   blockId: string;
@@ -373,7 +370,7 @@ await writeAppState("navigate", { view: "inbox", threadId: "thread-123" });
 
 ```tsx
 // app/hooks/use-navigation-state.ts -- this file lives in YOUR app
-import { useAgentRouteState } from "@agent-native/core/client";
+import { useAgentRouteState } from "@agent-native/core/client/navigation";
 import { TAB_ID } from "@/lib/tab-id";
 
 interface NavigationState {

package/docs/content/locales/zh-TW/creating-templates.mdx

@@ -270,8 +270,10 @@ export default runMigrations(
 路由位於 `app/routes/` 中並使用 React Router v8 檔案路由。透過actions或 API 處理常式查詢資料，並預設使突變樂觀。
 
 ```tsx
-import { useActionMutation, useActionQuery } from "@agent-native/core/client";
-
+import {
+  useActionMutation,
+  useActionQuery,
+} from "@agent-native/core/client/hooks";
 export default function ProjectsPage() {
   const { data: projects = [] } = useActionQuery("list-projects", {});
   const create = useActionMutation("create-project");
@@ -287,7 +289,7 @@ export default function ProjectsPage() {
 在應用程式 shell 附近連線一次即時同步，以便在代理、另一個分頁或操作更改資料時重新整理 React 查詢快取：
 
 ```tsx
-import { useDbSync } from "@agent-native/core/client";
+import { useDbSync } from "@agent-native/core/client/hooks";
 import { useQueryClient } from "@tanstack/react-query";
 
 export function AppSync() {
@@ -300,7 +302,7 @@ export function AppSync() {
 **Agent-Native 承諾：代理寫入顯示在 UI 中，無需手動重新整理。** `useActionQuery` 是簡單路徑 - 當變異操作發出 `source: "action"` 時，每個鉤子都會重新取得。如果您使用自訂金鑰（例如，讀取整合狀態的低階用戶端幫助程式）取得原始 `useQuery`，請將每個來源計數器折疊到 queryKey 中以進行有針對性的重新整理：
 
 ```tsx
-import { useChangeVersions } from "@agent-native/core/client";
+import { useChangeVersions } from "@agent-native/core/client/hooks";
 
 const v = useChangeVersions(["dashboards", "action"]);
 useQuery({
@@ -323,7 +325,7 @@ useQuery({
 使用 `useAgentRouteState` 作為 UI 掛鉤，以便應用程式狀態寫入、分頁範圍指令讀取、讀取後刪除和重複指令保護保持一致：
 
 ```tsx
-import { useAgentRouteState } from "@agent-native/core/client";
+import { useAgentRouteState } from "@agent-native/core/client/navigation";
 import { TAB_ID } from "@/lib/tab-id";
 
 export function useNavigationState() {

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

@@ -0,0 +1,10 @@
+---
+title: Doctor
+description: 安全與遷移檢查。
+---
+
+# Doctor
+
+`agent-native doctor` 會執行 8 個 guard：7 個安全 guard 與 `migration-manifest`。後者會找出已安裝 `migration-manifest.json` 的 import，且沒有 opt-out。執行 `agent-native doctor --only migration-manifest`，以 `npx @agent-native/core@latest upgrade --codemods` 預覽，再用 `--yes` 套用。JSON 的 `guardsRun` 會列出全部 8 項。
+
+標記為 `planned` 的項目只會顯示為警告，不會被重寫。active 項目會列為問題；codemod 只有在目標 export 已安裝時才會重寫。

package/docs/content/locales/zh-TW/drop-in-agent.mdx

@@ -105,7 +105,7 @@ description: "使用 <AgentPanel>、<AgentSidebar> 和 sendToAgentChat() 將代
   filename="app/root.tsx"
   language="tsx"
   code={
-    'import { Outlet } from "react-router";\nimport { AgentSidebar, AgentToggleButton } from "@agent-native/core/client";\n\nexport default function Root() {\n  return (\n    <AgentSidebar\n      emptyStateText="我能幫什麼？"\n      suggestions={[\n        "Summarize my inbox",\n        "Draft a reply to the latest email",\n        "Show me yesterday\'s signup numbers",\n      ]}\n      dynamicSuggestions\n      defaultSidebarWidth={420}\n      position="right"\n    >\n      <header>\n        <AgentToggleButton />\n      </header>\n\n      <main>\n        <Outlet />\n      </main>\n    </AgentSidebar>\n  );\n}'
+    'import { Outlet } from "react-router";\nimport { AgentSidebar, AgentToggleButton } from "@agent-native/core/client/agent-chat";\n\nexport default function Root() {\n  return (\n    <AgentSidebar\n      emptyStateText="我能幫什麼？"\n      suggestions={[\n        "Summarize my inbox",\n        "Draft a reply to the latest email",\n        "Show me yesterday\'s signup numbers",\n      ]}\n      dynamicSuggestions\n      defaultSidebarWidth={420}\n      position="right"\n    >\n      <header>\n        <AgentToggleButton />\n      </header>\n\n      <main>\n        <Outlet />\n      </main>\n    </AgentSidebar>\n  );\n}'
   }
   annotations={[
     {
@@ -154,8 +154,7 @@ description: "使用 <AgentPanel>、<AgentSidebar> 和 sendToAgentChat() 將代
 
 ```tsx
 // app/routes/agent.tsx
-import { AgentPanel } from "@agent-native/core/client";
-
+import { AgentPanel } from "@agent-native/core/client/agent-chat";
 export default function AgentRoute() {
   return (
     <div className="h-screen">
@@ -182,8 +181,7 @@ export default function AgentRoute() {
 將工作交給代理的按鈕（而不是執行行內 `llm()` 呼叫 - [ladder](/docs/what-is-agent-native#the-ladder) 的反模式）：
 
 ```tsx
-import { sendToAgentChat } from "@agent-native/core/client";
-
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
 <Button
   onClick={() =>
     sendToAgentChat({
@@ -232,8 +230,7 @@ sendToAgentChat({
 如果您想要載入狀態，請使用 `useSendToAgentChat()` 鉤子 - 它返回 `send` 和 `isGenerating`：
 
 ```ts
-import { useSendToAgentChat } from "@agent-native/core/client";
-
+import { useSendToAgentChat } from "@agent-native/core/client/agent-chat";
 const { send, isGenerating } = useSendToAgentChat();
 ```
 
@@ -267,8 +264,7 @@ const { send, isGenerating } = useSendToAgentChat();
 當 UI 需要執行代理工具將執行的相同操作（[ladder](/docs/what-is-agent-native#rung-three) 的梯級 3）時，請使用 `useActionMutation`：
 
 ```tsx
-import { useActionMutation } from "@agent-native/core/client";
-
+import { useActionMutation } from "@agent-native/core/client/hooks";
 const { mutate, isPending } = useActionMutation("reply-to-email");
 
 <Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
@@ -298,8 +294,7 @@ import {
   AgentSidebar,
   AgentToggleButton,
   sendToAgentChat,
-} from "@agent-native/core/client";
-
+} from "@agent-native/core/client/agent-chat";
 export default function Root() {
   return (
     <AgentSidebar suggestions={["Draft a reply", "Summarize selection"]}>

package/docs/content/locales/zh-TW/embedding-sdk.mdx

@@ -116,8 +116,7 @@ export default createAgentNativeEmbeddedPlugin({
 import {
   AgentNativeEmbedded,
   defineClientAction,
-} from "@agent-native/core/client";
-
+} from "@agent-native/core/client/host";
 export function BuilderAppShell({ children, content, editor }) {
   return (
     <AgentNativeEmbedded
@@ -295,8 +294,10 @@ for await (const chunk of sendMessage(
 對於獨立的 sidecar 應用程式或跨來源 iframe，請使用較低階別的 `<AgentNative />`。它將 iframe sidecar 和連線頁面脈絡、即時用戶端 actions 以及主機重新整理/導覽指令呈現在一個位置：
 
 ```tsx
-import { AgentNative, defineClientAction } from "@agent-native/core/client";
-
+import {
+  AgentNative,
+  defineClientAction,
+} from "@agent-native/core/client/host";
 export function AssistantDock({ customer, sessionToken }) {
   return (
     <AgentNative
@@ -383,8 +384,7 @@ import {
   requestAgentNativeHostContext,
   runAgentNativeHostAction,
   sendAgentNativeHostCommand,
-} from "@agent-native/core/client";
-
+} from "@agent-native/core/client/host";
 announceAgentNativeFrameReady({ hostOrigin: "https://app.example.com" });
 
 const context = await requestAgentNativeHostContext({
@@ -459,8 +459,7 @@ const hostTools = createAgentNativeHostTools({
 
 ```tsx
 import { useEffect } from "react";
-import { startAgentNativeBrowserSessionBridge } from "@agent-native/core/client";
-
+import { startAgentNativeBrowserSessionBridge } from "@agent-native/core/client/host";
 export function SidecarRuntime() {
   useEffect(() => {
     const bridge = startAgentNativeBrowserSessionBridge({
@@ -512,8 +511,7 @@ import {
   AgentNativeExtensionSlot,
   createHttpAgentNativeExtensionStorage,
   defineClientAction,
-} from "@agent-native/core/client";
-
+} from "@agent-native/core/client/host";
 const storage = createHttpAgentNativeExtensionStorage({
   endpoint: "/api/agent-native/extensions/storage",
   headers: () => ({ Authorization: `Bearer ${sessionToken()}` }),

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

@@ -15,7 +15,11 @@ SQL 設定中的語言選取，將其公開為 actions，並回退到
 透過`AppProviders`使用提供者：
 
 ```tsx
-import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
+import {
+  AppProviders,
+} from "@agent-native/core/client/hooks"import {
+  getLocaleInitScript,
+} from "@agent-native/core/client/i18n"
 import { i18nCatalog } from "./i18n";
 
 const LOCALE_INIT_SCRIPT = getLocaleInitScript();
@@ -42,8 +46,7 @@ const LOCALE_INIT_SCRIPT = getLocaleInitScript();
 ```ts
 // app/i18n/index.ts
 import enUS from "./en-US";
-import type { AgentNativeI18nCatalog } from "@agent-native/core/client";
-
+import type { AgentNativeI18nCatalog } from "@agent-native/core/client/i18n";
 export const i18nCatalog = {
   sourceLocale: "en-US",
   messages: enUS,
@@ -71,10 +74,10 @@ export const i18nCatalog = {
 ```tsx
 import {
   LanguagePicker,
-  openAgentSettings,
   useT,
-} from "@agent-native/core/client";
-
+} from "@agent-native/core/client/i18n"import {
+  openAgentSettings,
+} from "@agent-native/core/client/navigation"
 function SettingsPage() {
   const t = useT();
   return (

package/docs/content/locales/zh-TW/key-concepts.mdx

@@ -252,8 +252,7 @@ UI 從不直接呼叫 LLM。當使用者點選“產生圖表”或“寫入摘
 
 ```ts
 // In a React component — delegate AI work to the agent
-import { sendToAgentChat } from "@agent-native/core/client";
-
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
 sendToAgentChat({
   message: "Generate a chart showing signups by source",
   context: "Dashboard ID: main, date range: last 30 days",
@@ -304,8 +303,7 @@ export default defineAction({
 
 ```ts
 // Client: subscribe to agent/UI data changes once near the app shell
-import { useDbSync } from "@agent-native/core/client";
-
+import { useDbSync } from "@agent-native/core/client/hooks";
 useDbSync({ queryClient });
 ```
 

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

@@ -94,8 +94,7 @@ description: "代理跟蹤、評估、意見回饋、A/B 實驗和內建儀表
 
 ```tsx
 // app/routes/observability.tsx
-import { ObservabilityDashboard } from "@agent-native/core/client";
-
+import { ObservabilityDashboard } from "@agent-native/core/client/observability";
 export default function ObservabilityPage() {
   return (
     <div className="min-h-screen bg-background p-6">

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

@@ -17,3 +17,9 @@ agent-native package eject @agent-native/scheduling --apply
 新增與退出預設只會預覽。只有指定 `--apply` 才會寫入檔案並執行偵測到的套件
 管理器。CLI 會拒絕衝突與未知配置；安裝失敗時會還原檔案與鎖定檔。試辦期間
 只有 Scheduling 可退出，Pinpoint 暫不納入。
+
+## 遷移
+
+已發佈套件包含記錄移動路徑與符號的 `migration-manifest.json`。`npx @agent-native/core@latest upgrade --codemods` 會預覽差異，檢閱後用 `--yes` 套用。CI 請執行 `agent-native doctor --only migration-manifest`；此檢查沒有 opt-out。
+
+`planned` 項目可在目標之前發佈；它們只會顯示為非阻塞警告，codemod 不會重寫。active 移動只有在目標 export 已安裝時才會重寫。