@agent-native/core 0.86.1 → 0.88.0

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

@@ -0,0 +1,61 @@
+---
+title: "Agent-Native 工具包"
+description: "用于协作、设置、共享、导航、在线状态、历史、配置和 Agent UX 的可复用套件。"
+---
+
+# Agent-Native 工具包
+
+Agent-Native 应用不应该重复搭建 workspace 的通用能力。应用负责自己的领域模型、领域
+actions 和产品视图。Framework 和 `@agent-native/toolkit` 负责每个应用都应该继承的可复用
+产品表面：协作、共享、设置、导航、组织、配置、Agent UX、历史和运营可见性。
+
+用户应该只学习一种共享方式、一种连接密钥的方式、一种看到 Agent 一起编辑的方式、一处设置入口，
+以及一种理解变更的方式。
+
+## 工具包契约 {#toolkit-contract}
+
+当行为符合以下条件时，应移动到 toolkit：
+
+- **Workspace 级别** - 用户期望所有应用都一样。
+- **Agent 可见** - Agent 需要通过 actions、instructions 或 application state 使用同一能力。
+- **受治理** - 权限、audit、secrets、组织策略、billing 或共享规则会参与。
+- **重复出现** - 两个应用已经构建了类似 UI 或逻辑。
+- **非领域专属** - 应用提供资源名称和 actions，但交互模式是通用的。
+
+如果行为绑定领域模型、专属 workflow 或应用自己的心智模型，就保持 app-local。
+
+## 可复用套件 {#reusable-kits}
+
+- **Settings kit** - account、workspace、AI models、LLM keys、connections、secrets、
+  usage、notifications、changelog 和 app preferences 的标准 tabs。持久配置放在 Settings；
+  Agent sidebar 只保留上下文 quick controls 和 deep links。
+- **Collaboration kit** - real-time editing、Yjs docs、presence、agent presence、live
+  cursors、remote selections、recent edit highlights 和 shared undo/redo。参见
+  [Real-Time Collaboration](/docs/real-time-collaboration)。
+- **Sharing kit** - 用一个隐私和权限模型处理 private、workspace、org、public link、invites、
+  roles、expirations 和 agent-readable access。参见 [Sharing & Privacy](/docs/sharing)。
+- **Navigation and command kit** - app shell、nav、breadcrumbs、app switcher、command
+  palette、recents、pinned resources 和 search。
+- **Organization kit** - folders、tags、favorites、archive、trash、ownership、membership
+  和 common metadata。
+- **Setup and connections kit** - API keys、OAuth、connections、model readiness、
+  missing secrets 和 declarative onboarding。参见
+  [Workspace Connections](/docs/workspace-connections)。
+- **Agent UX kit** - sidebar、composer、staged context、mentions、voice、human approval、
+  generative UI、progress 和 Agent-visible state。
+- **History and recovery kit** - audit log、activity feed、version history、checkpoints、
+  undo、redo、restore 和 proof-of-done。参见 [Audit Log](/docs/audit-log)。
+- **Comments and review kit** - anchored comments、pins、mentions、review requests、
+  resolved threads 和 Agent follow-up tasks。
+- **Workflow and observability kit** - notifications、approvals、background runs、
+  recurring jobs、traces、evals、feedback 和 run timelines。参见
+  [Observability](/docs/observability)。
+
+## 实施顺序 {#implementation-order}
+
+1. 将持久配置合并到标准 Settings tabs。
+2. 用共享 adapters 统一 collaboration、presence、agent presence、undo/redo 和 real-time editing。
+3. 将 navigation、commands、recents、favorites、folders、tags、archive 和 trash 移入共享 primitives。
+4. 让所有可共享 resource 注册到同一 permissions 和 agent-readable access 模型。
+5. 为每个 collaborative resource 提供一致的 activity、comments、review、restore 和 audit 体验。
+6. 统一 notifications、approvals、run status、traces、evals 和 feedback。

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

@@ -25,6 +25,15 @@ import { ResourcesPanel } from "@agent-native/core/client/resources";
 `@agent-native/core/client` 或聚焦的 `@agent-native/core/client/*` 子路径
 因此捆绑商选择浏览器安全的条目。
 
+将 `@agent-native/toolkit` 用于不属于基础运行时契约的可复用应用构建部件：shadcn 风格 UI primitives、共享 hooks、简单应用 shell helpers，以及其他模板组合模块。迁移期间 Core 会保留兼容 re-export，但新的模板和应用代码应直接导入 toolkit 模块：
+
+```tsx
+import { Button } from "@agent-native/toolkit/ui/button";
+import { Toaster } from "@agent-native/toolkit/ui/sonner";
+import { useToast } from "@agent-native/toolkit/hooks/use-toast";
+import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
+```
+
 <Diagram id="doc-block-1tquzyh" title={"下拉一层，不脱离框架"} summary={"每个层都保持相同的运行时 - 操作、线程状态和 SQL-backed 同步 - 同时让您更好地控制镶边。"}>
 
 ```html

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

@@ -7,6 +7,8 @@ description: "如何创建和发布您自己的代理本机应用模板。"
 
 模板是完整的、可分叉的代理本机应用程序，可解决实际工作流程。第一方模板使用您使用的相同框架表面构建：用于 UI 的 React 路由、用于数据的 Drizzle SQL、用于操作的 actions、用于代理行为的工作区资源以及轮询同步，以便代理和 UI 保持一致。
 
+将 `@agent-native/core` 用于运行时契约：actions、server plugins、database helpers、app state、routing helpers 和 agent chat。将 `@agent-native/toolkit` 用于可复用的应用构建 UI 和 helpers，例如共享 primitives、toast/mobile hooks、date pickers 和简单 app shell slots。当变体承载产品行为或视觉身份时，请保留在模板本地。
+
 一个好的模板：
 
 - 使用有用的种子数据或空状态流端到端地解决一个工作流。

package/docs/content/locales/zh-CN/sharing.mdx

@@ -93,9 +93,10 @@ description: "Google Docs 风格的共享，内置于框架中。每个用户创
 - **幻灯片** — 幻灯片
 - **设计** — 设计和资产
 - **剪辑** — 屏幕录制（Loom 风格）
+- **Plan** — visual plans and PR recaps
 - **表单** — 表单定义
 - **日历** — 活动和预订链接
-- **分析** - 仪表板（推出 - 请参阅分析模板的 `AGENTS.md`）
+- **分析** - dashboards, saved analyses, and tokenized session replays
 - **扩展** - 沙盒迷你应用程序（参见 [Extensions](/docs/extensions#sharing)）
 
 其中每一个都使用相同的 `ownableColumns()` 模式助手、相同的 `share-resource` 操作和相同的 `<ShareButton>` UI。从一个模板移动到另一个模板，共享对话框看起来相同。
@@ -136,15 +137,22 @@ import { ShareButton } from "@agent-native/core/client";
 
 框架在每个模板中自动安装这些 actions - 代理将它们称为工具，UI 通过 `useActionQuery` / `useActionMutation` 调用它们：
 
-| 行动                      | 它的作用                                                             |
-| ------------------------- | -------------------------------------------------------------------- |
-| `share-resource`          | 授予用户或组织特定角色的访问权限。可选的 `notify` 控制电子邮件通知。 |
-| `unshare-resource`        | 撤销用户或组织的访问权限。                                           |
-| `list-resource-shares`    | 显示当前可见性以及所有显式授权。                                     |
-| `set-resource-visibility` | 更改为 `private`、`org` 或 `public`。                                |
+| 行动                         | 它的作用                                                                                |
+| ---------------------------- | --------------------------------------------------------------------------------------- |
+| `share-resource`             | 授予用户或组织特定角色的访问权限。可选的 `notify` 控制电子邮件通知。                    |
+| `unshare-resource`           | 撤销用户或组织的访问权限。                                                              |
+| `list-resource-shares`       | 显示当前可见性以及所有显式授权。                                                        |
+| `set-resource-visibility`    | 更改为 `private`、`org` 或 `public`。                                                   |
+| `create-agent-resource-link` | Mint a temporary read-only `agent_access` URL for a registered agent-readable resource. |
 
 告诉代理“与作为编辑的营销团队共享此设计”，它会针对 UI 使用的同一端点调用 `share-resource`。结果将显示在下一次渲染的共享对话框中。
 
+## Agent-readable share links {#agent-readable-links}
+
+Human share links should also work for agents when the resource is a document-like artifact: plans, documents, decks, designs, analytics dashboards, saved analyses, clips, and similar "things you would send to a person." Public links expose a small SSR discovery script that points at structured JSON. Private resources use a short-lived `agent_access` token scoped to exactly one resource.
+
+Register the resource with `agentReadable`, add a read-only JSON context endpoint, inject the SSR discovery script with `renderAgentReadableResourceDiscoveryScript()`, and let agents call `create-agent-resource-link` when they need a temporary private URL. The endpoint must return data only when the row is `public` or `verifyScopedAgentAccessToken()` accepts the token for that exact `resourceKind` and `resourceId`.
+
 ## 将其构建到新模板中 {#building}
 
 如果您正在创建模板（请参阅 [Creating Templates](/docs/creating-templates)），则共享接线会很短。您的架构中添加了两项内容：

package/docs/content/locales/zh-CN/template-analytics.mdx

@@ -149,6 +149,12 @@ CLI 打印本地开发 URL。使用 Google 登录，然后打开 **数据源**
 
 **Session replay agent handoff.** Session recordings stay private, but the session detail page can mint a temporary **Copy for agent** link. The two-hour `agent_access` URL lets an external agent read replay summaries, timelines, and bounded event details without exposing blob/provider URLs or making the recording public.
 
+Implementation note: use the shared core agent-access helpers
+(`createScopedAgentAccessGrant`, `verifyScopedAgentAccessToken`,
+`buildAgentAccessUrl`, and `buildAgentAccessApiUrl`) for the SSR/bot-visible
+URL contract. Keep replay chunk authorization, diagnostics payloads, and the
+session detail UI local to Analytics.
+
 ### 与代理合作
 
 代理始终知道您在看什么。当前屏幕状态作为 `<current-screen>` 块注入到每条消息中 - 它包含活动视图、打开的仪表板或分析以及任何选定的过滤器。

package/docs/content/locales/zh-CN/template-clips.mdx

@@ -133,6 +133,13 @@ APIs，因此仅接受文本或静态图像的模型仍然可以理解内容
 
 Temporary private agent links are also supported: the Share dialog can mint a two-hour `agent_access` URL for any recording the viewer can access. Agents use that token with the share page and JSON APIs, and the clip does not become public.
 
+Implementation note: use the shared core agent-access helpers
+(`createScopedAgentAccessGrant`, `verifyScopedAgentAccessToken`,
+`buildAgentAccessUrl`, and `buildAgentAccessApiUrl`) for the SSR/bot-visible
+URL contract. Keep Clips-specific visibility checks, transcript/frame payloads,
+and player UI local. New links use `agent_access`; routes should continue
+accepting the legacy `t` query where existing agent API URLs may already use it.
+
 端点遵循与共享页面相同的公共/密码/过期规则。
 受密码保护的剪辑需要密码一次；成功响应返回
 短暂的标记化链接，因此下游代理不需要明文

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

@@ -241,6 +241,12 @@ Analytics 模板将重放元数据存储在 SQL（`session_recordings`）中，
 
 当需要将私有录制内容提供给外部代理时，可使用会话详情页面的**复制给代理**控件。它会生成一个两小时有效期、仅限该录制的 `agent_access` 链接，在 `/sessions/:recordingId` 上以服务器端渲染方式生成一个小型发现载荷，并只暴露代理上下文/事件的 JSON API。该录制本身的可见性不会改变。
 
+Implementation note: the reusable layer is the core agent-access URL contract,
+not a replay-specific UI abstraction. Use `createScopedAgentAccessGrant`,
+`verifyScopedAgentAccessToken`, `buildAgentAccessUrl`, and
+`buildAgentAccessApiUrl` for scoped SSR and JSON API links; keep replay storage,
+diagnostics shaping, and access policy inside the Analytics template.
+
 仅在本地开发环境下，当私有 blob 存储不可用时，Analytics 可以回退为使用有上限的 SQL 内联数据块。生产部署应配置私有或加密的 blob 存储，而不是依赖 Postgres 来存放重放数据。
 
 ## 高级：自定义提供程序和内部结构 {#advanced}

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

@@ -0,0 +1,61 @@
+---
+title: "Agent-Native 工具包"
+description: "用於協作、設定、分享、導覽、線上狀態、歷史、配置和 Agent UX 的可重用套件。"
+---
+
+# Agent-Native 工具包
+
+Agent-Native 應用程式不應重複建置 workspace 的通用能力。應用程式負責自己的領域模型、
+領域 actions 和產品視圖。Framework 與 `@agent-native/toolkit` 負責每個應用程式都應繼承的
+可重用產品表面：協作、分享、設定、導覽、組織、配置、Agent UX、歷史和營運可見性。
+
+使用者應該只學會一種分享方式、一種連接金鑰的方式、一種看到 Agent 一起編輯的方式、一個設定入口，
+以及一種理解變更的方式。
+
+## 工具包契約 {#toolkit-contract}
+
+當行為符合以下條件時，應移到 toolkit：
+
+- **Workspace 層級** - 使用者期待所有應用程式都一致。
+- **Agent 可見** - Agent 需要透過 actions、instructions 或 application state 使用同一能力。
+- **受治理** - 權限、audit、secrets、組織政策、billing 或分享規則會參與。
+- **重複出現** - 兩個應用程式已經建了相似 UI 或邏輯。
+- **非領域專屬** - 應用程式提供 resource 名稱與 actions，但互動模式是通用的。
+
+如果行為綁定領域模型、專屬 workflow 或應用程式自己的心智模型，就保持 app-local。
+
+## 可重用套件 {#reusable-kits}
+
+- **Settings kit** - account、workspace、AI models、LLM keys、connections、secrets、
+  usage、notifications、changelog 和 app preferences 的標準 tabs。持久設定放在 Settings；
+  Agent sidebar 只保留情境 quick controls 與 deep links。
+- **Collaboration kit** - real-time editing、Yjs docs、presence、agent presence、live
+  cursors、remote selections、recent edit highlights 和 shared undo/redo。請參閱
+  [Real-Time Collaboration](/docs/real-time-collaboration)。
+- **Sharing kit** - 用一個隱私與權限模型處理 private、workspace、org、public link、invites、
+  roles、expirations 和 agent-readable access。請參閱 [Sharing & Privacy](/docs/sharing)。
+- **Navigation and command kit** - app shell、nav、breadcrumbs、app switcher、command
+  palette、recents、pinned resources 和 search。
+- **Organization kit** - folders、tags、favorites、archive、trash、ownership、membership
+  和 common metadata。
+- **Setup and connections kit** - API keys、OAuth、connections、model readiness、
+  missing secrets 和 declarative onboarding。請參閱
+  [Workspace Connections](/docs/workspace-connections)。
+- **Agent UX kit** - sidebar、composer、staged context、mentions、voice、human approval、
+  generative UI、progress 和 Agent-visible state。
+- **History and recovery kit** - audit log、activity feed、version history、checkpoints、
+  undo、redo、restore 和 proof-of-done。請參閱 [Audit Log](/docs/audit-log)。
+- **Comments and review kit** - anchored comments、pins、mentions、review requests、
+  resolved threads 和 Agent follow-up tasks。
+- **Workflow and observability kit** - notifications、approvals、background runs、
+  recurring jobs、traces、evals、feedback 和 run timelines。請參閱
+  [Observability](/docs/observability)。
+
+## 實作順序 {#implementation-order}
+
+1. 將持久設定合併到標準 Settings tabs。
+2. 用共享 adapters 統一 collaboration、presence、agent presence、undo/redo 和 real-time editing。
+3. 將 navigation、commands、recents、favorites、folders、tags、archive 和 trash 移入共享 primitives。
+4. 讓所有可分享 resource 註冊到同一 permissions 和 agent-readable access 模型。
+5. 為每個 collaborative resource 提供一致的 activity、comments、review、restore 和 audit 體驗。
+6. 統一 notifications、approvals、run status、traces、evals 和 feedback。

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

@@ -25,6 +25,15 @@ import { ResourcesPanel } from "@agent-native/core/client/resources";
 `@agent-native/core/client` 或聚焦的 `@agent-native/core/client/*` 子路徑
 因此捆綁商選取瀏覽器安全的條目。
 
+將 `@agent-native/toolkit` 用於不屬於基礎執行階段合約的可重用應用程式建構部件：shadcn 風格 UI primitives、共享 hooks、簡單應用程式 shell helpers，以及其他範本組合模組。遷移期間 Core 會保留相容 re-export，但新的範本和應用程式程式碼應直接匯入 toolkit 模組：
+
+```tsx
+import { Button } from "@agent-native/toolkit/ui/button";
+import { Toaster } from "@agent-native/toolkit/ui/sonner";
+import { useToast } from "@agent-native/toolkit/hooks/use-toast";
+import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
+```
+
 <Diagram id="doc-block-174p2n3" title={"下拉一層，不脫離框架"} summary={"每個層都保持相同的執行時 - 操作、對話串狀態和 SQL-backed 同步 - 同時讓您更好地控制鑲邊。"}>
 
 ```html

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

@@ -7,6 +7,8 @@ description: "如何建立和發布您自己的 Agent-Native 應用範本。"
 
 範本是完整的、可分叉的 Agent-Native 應用程式，可解決實際工作流程。第一方範本使用您使用的相同框架表面建置：用於 UI 的 React 路由、用於資料的 Drizzle SQL、用於操作的 actions、用於代理行為的工作區資源以及輪詢同步，以便代理和 UI 保持一致。
 
+將 `@agent-native/core` 用於執行階段合約：actions、server plugins、database helpers、app state、routing helpers 和 agent chat。將 `@agent-native/toolkit` 用於可重用的應用程式建構 UI 和 helpers，例如共享 primitives、toast/mobile hooks、date pickers 和簡單 app shell slots。當變體承載產品行為或視覺識別時，請保留在範本本地。
+
 一個好的範本：
 
 - 使用有用的種子資料或空狀態流端對端地解決一個工作流。

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

@@ -93,9 +93,10 @@ description: "Google Docs 風格的共用，內建於框架中。每個使用者
 - **幻燈片** — 幻燈片
 - **設計** — 設計和資產
 - **剪輯** — 螢幕錄製（Loom 風格）
+- **Plan** — visual plans and PR recaps
 - **表單** — 表單定義
 - **行事曆** — 活動和預訂連結
-- **分析** - 儀表板（推出 - 請參閱分析範本的 `AGENTS.md`）
+- **分析** - dashboards, saved analyses, and tokenized session replays
 - **擴充功能** - 沙盒迷你應用程式（參見 [Extensions](/docs/extensions#sharing)）
 
 其中每一個都使用相同的 `ownableColumns()` 模式助手、相同的 `share-resource` 操作和相同的 `<ShareButton>` UI。從一個範本行動到另一個範本，共用對話框看起來相同。
@@ -136,15 +137,22 @@ import { ShareButton } from "@agent-native/core/client";
 
 框架在每個範本中自動安裝這些 actions - 代理將它們稱為工具，UI 透過 `useActionQuery` / `useActionMutation` 呼叫它們：
 
-| 行動                      | 它的作用                                                               |
-| ------------------------- | ---------------------------------------------------------------------- |
-| `share-resource`          | 授予使用者或組織特定角色的存取權限。可選的 `notify` 控制電子郵件通知。 |
-| `unshare-resource`        | 撤銷使用者或組織的存取權限。                                           |
-| `list-resource-shares`    | 顯示目前可見性以及所有顯式授權。                                       |
-| `set-resource-visibility` | 更改為 `private`、`org` 或 `public`。                                  |
+| 行動                         | 它的作用                                                                                |
+| ---------------------------- | --------------------------------------------------------------------------------------- |
+| `share-resource`             | 授予使用者或組織特定角色的存取權限。可選的 `notify` 控制電子郵件通知。                  |
+| `unshare-resource`           | 撤銷使用者或組織的存取權限。                                                            |
+| `list-resource-shares`       | 顯示目前可見性以及所有顯式授權。                                                        |
+| `set-resource-visibility`    | 更改為 `private`、`org` 或 `public`。                                                   |
+| `create-agent-resource-link` | Mint a temporary read-only `agent_access` URL for a registered agent-readable resource. |
 
 告訴代理“與作為編輯的行銷團隊共用此設計”，它會針對 UI 使用的同一端點呼叫 `share-resource`。結果將顯示在下一次渲染的共用對話框中。
 
+## Agent-readable share links {#agent-readable-links}
+
+Human share links should also work for agents when the resource is a document-like artifact: plans, documents, decks, designs, analytics dashboards, saved analyses, clips, and similar "things you would send to a person." Public links expose a small SSR discovery script that points at structured JSON. Private resources use a short-lived `agent_access` token scoped to exactly one resource.
+
+Register the resource with `agentReadable`, add a read-only JSON context endpoint, inject the SSR discovery script with `renderAgentReadableResourceDiscoveryScript()`, and let agents call `create-agent-resource-link` when they need a temporary private URL. The endpoint must return data only when the row is `public` or `verifyScopedAgentAccessToken()` accepts the token for that exact `resourceKind` and `resourceId`.
+
 ## 將其建置到新範本中 {#building}
 
 如果您正在建立範本（請參閱 [Creating Templates](/docs/creating-templates)），則共用接線會很短。您的架構中新增了兩項內容：

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

@@ -149,6 +149,12 @@ CLI 列印本機開發 URL。使用 Google 登入，然後開啟 **資料來源*
 
 **Session replay agent handoff.** Session recordings stay private, but the session detail page can mint a temporary **Copy for agent** link. The two-hour `agent_access` URL lets an external agent read replay summaries, timelines, and bounded event details without exposing blob/provider URLs or making the recording public.
 
+Implementation note: use the shared core agent-access helpers
+(`createScopedAgentAccessGrant`, `verifyScopedAgentAccessToken`,
+`buildAgentAccessUrl`, and `buildAgentAccessApiUrl`) for the SSR/bot-visible
+URL contract. Keep replay chunk authorization, diagnostics payloads, and the
+session detail UI local to Analytics.
+
 ### 與代理合作
 
 代理始終知道您在看什麼。目前螢幕狀態作為 `<current-screen>` 塊注入到每條訊息中 - 它包含活動檢視、開啟的儀表板或分析以及任何選定的過濾器。

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

@@ -133,6 +133,13 @@ APIs，因此僅接受文字或靜態圖片的模型仍然可以理解內容
 
 Temporary private agent links are also supported: the Share dialog can mint a two-hour `agent_access` URL for any recording the viewer can access. Agents use that token with the share page and JSON APIs, and the clip does not become public.
 
+Implementation note: use the shared core agent-access helpers
+(`createScopedAgentAccessGrant`, `verifyScopedAgentAccessToken`,
+`buildAgentAccessUrl`, and `buildAgentAccessApiUrl`) for the SSR/bot-visible
+URL contract. Keep Clips-specific visibility checks, transcript/frame payloads,
+and player UI local. New links use `agent_access`; routes should continue
+accepting the legacy `t` query where existing agent API URLs may already use it.
+
 端點遵循與共用頁面相同的公開/密碼/過期規則。
 受密碼保護的剪輯需要密碼一次；成功回應返回
 短暫的標記化連結，因此下游代理不需要明文

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

@@ -241,6 +241,12 @@ Analytics 範本將重播中繼資料儲存在 SQL（`session_recordings`）中
 
 當您需要將私人錄製內容交給外部代理時，請使用工作階段詳細資料頁面的**複製給代理**控制項。它會產生一個兩小時、僅限該筆錄製的 `agent_access` 連結，在 `/sessions/:recordingId` 上以伺服器端轉譯（SSR）一個小型探索酬載，並僅公開代理內容/事件 JSON API。該筆錄製的可見性不會改變。
 
+Implementation note: the reusable layer is the core agent-access URL contract,
+not a replay-specific UI abstraction. Use `createScopedAgentAccessGrant`,
+`verifyScopedAgentAccessToken`, `buildAgentAccessUrl`, and
+`buildAgentAccessApiUrl` for scoped SSR and JSON API links; keep replay storage,
+diagnostics shaping, and access policy inside the Analytics template.
+
 僅在本機開發時，Analytics 可以在私有 blob 儲存體無法使用時，回退到有上限的 SQL 內嵌區塊。正式環境部署應設定私有或加密的 blob 儲存體，而不是依賴 Postgres 來儲存重播酬載。
 
 ## 進階：自訂提供者和內部結構 {#advanced}

package/docs/content/sharing.mdx

@@ -93,9 +93,10 @@ Every template that stores user-authored work uses this model. Concretely:
 - **Slides** — decks
 - **Design** — designs and assets
 - **Clips** — screen recordings (Loom-style)
+- **Plan** — visual plans and PR recaps
 - **Forms** — form definitions
 - **Calendar** — events and booking links
-- **Analytics** — dashboards (rolling out — see the analytics template's `AGENTS.md`)
+- **Analytics** — dashboards, saved analyses, and tokenized session replays
 - **Extensions** — sandboxed mini-apps (see [Extensions](/docs/extensions#sharing))
 
 Every one of these uses the same `ownableColumns()` schema helper, the same `share-resource` action, and the same `<ShareButton>` UI. Move from one template to another and the share dialog looks identical.
@@ -136,15 +137,46 @@ For lists, drop a `<VisibilityBadge visibility={row.visibility} />` next to each
 
 The framework auto-mounts these actions in every template — the agent calls them as tools, and the UI calls them through `useActionQuery` / `useActionMutation`:
 
-| Action                    | What it does                                                                                   |
-| ------------------------- | ---------------------------------------------------------------------------------------------- |
-| `share-resource`          | Grant a user or org access at a specific role. Optional `notify` controls email notifications. |
-| `unshare-resource`        | Revoke access for a user or org.                                                               |
-| `list-resource-shares`    | Show current visibility plus all explicit grants.                                              |
-| `set-resource-visibility` | Change to `private`, `org`, or `public`.                                                       |
+| Action                       | What it does                                                                                   |
+| ---------------------------- | ---------------------------------------------------------------------------------------------- |
+| `share-resource`             | Grant a user or org access at a specific role. Optional `notify` controls email notifications. |
+| `unshare-resource`           | Revoke access for a user or org.                                                               |
+| `list-resource-shares`       | Show current visibility plus all explicit grants.                                              |
+| `set-resource-visibility`    | Change to `private`, `org`, or `public`.                                                       |
+| `create-agent-resource-link` | Mint a temporary read-only `agent_access` URL for a registered agent-readable resource.        |
 
 Tell the agent "share this design with the marketing team as editors" and it calls `share-resource` against the same endpoint the UI uses. The result shows up in the share dialog the next render.
 
+## Agent-readable share links {#agent-readable-links}
+
+Human share links should also work for agents when the resource is a document-like artifact: plans, documents, decks, designs, analytics dashboards, saved analyses, clips, and similar "things you would send to a person." Public links expose a small SSR discovery script that points at structured JSON. Private resources use a short-lived `agent_access` token scoped to exactly one resource.
+
+The default flow is:
+
+1. Register the resource with `agentReadable`.
+2. Add a read-only JSON endpoint that returns the same content a viewer can see.
+3. Add an SSR discovery script on the human page with `renderAgentReadableResourceDiscoveryScript()`.
+4. Let agents call `create-agent-resource-link` when they need a temporary private URL.
+
+```ts
+registerShareableResource({
+  type: "deck",
+  resourceTable: schema.decks,
+  sharesTable: schema.deckShares,
+  displayName: "Deck",
+  titleColumn: "title",
+  getResourcePath: (deck) => `/p/${deck.id}`,
+  agentReadable: {
+    resourceKind: "slides:deck",
+    getContextPath: () => "/api/deck-agent-context.json",
+    getPagePath: (deck) => `/p/${deck.id}`,
+  },
+  getDb,
+});
+```
+
+The context endpoint must be read-only. It should return data only when the row is `public` or `verifyScopedAgentAccessToken()` accepts the token for that exact `resourceKind` and `resourceId`. Set `Cache-Control: no-store`, `Referrer-Policy: no-referrer`, and avoid including write credentials, provider blob URLs, or secrets. Token links should not change the resource visibility.
+
 ## Building it into a new template {#building}
 
 If you're creating a template (see [Creating Templates](/docs/creating-templates)), wiring sharing in is short. Two additions to your schema:

package/docs/content/template-analytics.mdx

@@ -154,6 +154,12 @@ The CLI prints the local dev URL. Sign in with Google, then open the **Data Sour
 
 **Session replay agent handoff.** Session recordings stay private, but the session detail page can mint a temporary **Copy for agent** link. The two-hour `agent_access` URL lets an external agent read replay summaries, timelines, and bounded event details without exposing blob/provider URLs or making the recording public.
 
+Implementation note: use the shared core agent-access helpers
+(`createScopedAgentAccessGrant`, `verifyScopedAgentAccessToken`,
+`buildAgentAccessUrl`, and `buildAgentAccessApiUrl`) for the SSR/bot-visible
+URL contract. Keep replay chunk authorization, diagnostics payloads, and the
+session detail UI local to Analytics.
+
 ### Working with the agent
 
 The agent always knows what you're looking at. The current screen state is injected into every message as a `<current-screen>` block — it contains the active view, the open dashboard or analysis, and any selected filters.

package/docs/content/template-clips.mdx

@@ -185,6 +185,13 @@ Password-protected clips require the password once; successful responses return
 short-lived tokenized links so downstream agents do not need the plaintext
 password.
 
+Implementation note: use the shared core agent-access helpers
+(`createScopedAgentAccessGrant`, `verifyScopedAgentAccessToken`,
+`buildAgentAccessUrl`, and `buildAgentAccessApiUrl`) for the SSR/bot-visible
+URL contract. Keep Clips-specific visibility checks, transcript/frame payloads,
+and player UI local. New links use `agent_access`; routes should continue
+accepting the legacy `t` query where existing agent API URLs may already use it.
+
 When `transcript.status` is `pending`, agents should wait 15-30 seconds and
 retry the context or transcript URL a few times before falling back to frames or
 reporting that no transcript is available. Long recordings can take several

package/docs/content/tracking.mdx

@@ -241,6 +241,12 @@ The Analytics template stores replay metadata in SQL (`session_recordings`) and
 
 When you need to hand a private recording to an external agent, use the session detail page's **Copy for agent** control. It mints a two-hour, recording-scoped `agent_access` link, SSRs a small discovery payload on `/sessions/:recordingId`, and exposes only the agent context/events JSON APIs. The recording's visibility does not change.
 
+Implementation note: the reusable layer is the core agent-access URL contract,
+not a replay-specific UI abstraction. Use `createScopedAgentAccessGrant`,
+`verifyScopedAgentAccessToken`, `buildAgentAccessUrl`, and
+`buildAgentAccessApiUrl` for scoped SSR and JSON API links; keep replay storage,
+diagnostics shaping, and access policy inside the Analytics template.
+
 For local development only, Analytics can fall back to capped SQL inline chunks when private blob storage is unavailable. Production deployments should configure private or encrypted blob storage rather than relying on Postgres for replay payloads.
 
 ## Advanced: custom providers & internals {#advanced}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.86.1",
+  "version": "0.88.0",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -73,6 +73,12 @@
     "./client/conversation": "./dist/client/conversation/index.js",
     "./client/editor": "./dist/client/editor/index.js",
     "./client/resources": "./dist/client/resources/index.js",
+    "./client/components/ui/dialog": "./dist/client/components/ui/dialog.js",
+    "./client/components/ui/dropdown-menu": "./dist/client/components/ui/dropdown-menu.js",
+    "./client/components/ui/hover-card": "./dist/client/components/ui/hover-card.js",
+    "./client/components/ui/popover": "./dist/client/components/ui/popover.js",
+    "./client/components/ui/sheet": "./dist/client/components/ui/sheet.js",
+    "./client/components/ui/tooltip": "./dist/client/components/ui/tooltip.js",
     "./blocks": "./dist/client/blocks/index.js",
     "./blocks/server": "./dist/client/blocks/server.js",
     "./client/AgentPanel": "./dist/client/AgentPanel.js",
@@ -126,6 +132,7 @@
     "./sharing/actions/unshare-resource": "./dist/sharing/actions/unshare-resource.js",
     "./sharing/actions/list-resource-shares": "./dist/sharing/actions/list-resource-shares.js",
     "./sharing/actions/set-resource-visibility": "./dist/sharing/actions/set-resource-visibility.js",
+    "./sharing/actions/create-agent-resource-link": "./dist/sharing/actions/create-agent-resource-link.js",
     "./client/sharing": "./dist/client/sharing/index.js",
     "./client/extensions": "./dist/client/extensions/index.js",
     "./client/tools": "./dist/client/extensions/index.js",
@@ -268,7 +275,8 @@
     "tw-animate-css": "1.4.0",
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "@agent-native/toolkit": "0.2.0"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/templates/workspace-core/.agents/skills/agent-native-toolkit/SKILL.md

@@ -0,0 +1,92 @@
+# Agent-Native Toolkit
+
+Use this skill when deciding whether app chrome, settings, collaboration,
+sharing, navigation, organization, setup, history, comments, or agent UX should
+be built app-locally or moved into reusable framework/toolkit pieces.
+
+## Core Rule
+
+Apps own domain models, domain actions, and product-specific workflows. The
+framework and `@agent-native/toolkit` own repeated workspace behavior users
+expect to work the same everywhere.
+
+Move behavior into shared toolkit primitives when it is:
+
+- workspace-wide, such as settings, nav, search, org membership, or setup
+- agent-visible, such as context, actions, run progress, or proof-of-done
+- governed, such as secrets, permissions, sharing, audit, or billing
+- repeated by two or more apps
+- not tied to one domain model
+
+Keep behavior app-local when the abstraction would hide important domain
+language or make a simple app-specific workflow harder to understand.
+
+## Settings Direction
+
+Durable settings belong in the Settings app or a registered settings route. The
+agent sidebar should not become a second settings app. It can show contextual
+quick controls and deep links such as:
+
+- `/settings/ai`
+- `/settings/connections`
+- `/settings/secrets`
+- `/settings/usage`
+- `/settings/apps/:appId`
+
+When adding a new API key, OAuth grant, provider connection, model selector, app
+preference, notification preference, or usage/billing surface, register it as a
+settings tab or app settings panel first. Only add sidebar UI when it is needed
+in the moment of agent use.
+
+## Reusable Kits
+
+- **Settings kit**: account, workspace, AI models, LLM keys, connections,
+  secrets, usage, notifications, changelog, and app-specific panels.
+- **Collaboration kit**: Yjs docs, presence, agent presence, live cursors,
+  remote selections, recent edit highlights, real-time sync indicators, and
+  undo/redo grouping.
+- **Sharing kit**: private/workspace/org/public-link access, invites, roles,
+  expirations, agent-readable links, and resource registration.
+- **Navigation and command kit**: app shell, side nav, breadcrumbs, app switcher,
+  command palette entries, recent resources, pinned resources, and global search.
+- **Organization kit**: folders, tags, favorites, archive, trash, ownership,
+  membership, and common resource metadata.
+- **Setup and connections kit**: declarative setup requirements, model readiness,
+  missing-secret states, OAuth grants, and provider connection health.
+- **Agent UX kit**: sidebar, composer, staged context, mentions, voice, human
+  approval, generative UI, progress, and screen-state exposure.
+- **History and recovery kit**: audit log, activity feed, version history,
+  checkpoints, undo, redo, restore, and proof-of-done.
+- **Comments and review kit**: anchored comments, pins, mentions, review
+  requests, resolved threads, agent follow-up tasks, and notifications.
+- **Workflow and observability kit**: notifications, approvals, scheduled work,
+  background runs, recurring jobs, traces, evals, feedback, and run timelines.
+
+## Implementation Checklist
+
+When adding or refactoring one of these areas:
+
+1. Search existing framework and template code for duplicated UI or actions.
+2. Decide the shared contract: data shape, action API, React component/hook, and
+   app adapter points.
+3. Keep shared data provider-agnostic and scoped by auth/sharing rules.
+4. Expose the same capability to the UI and agent through actions or documented
+   client helpers.
+5. Register app-specific labels, routes, resource adapters, and settings panels
+   instead of hardcoding app names in core UI.
+6. Update docs and relevant skills so future apps discover the shared path.
+
+## Related Skills
+
+Read these alongside this skill when the work touches the specific area:
+
+- `sharing`
+- `real-time-collab`
+- `real-time-sync`
+- `client-side-routing`
+- `context-awareness`
+- `onboarding`
+- `secrets`
+- `audit-log`
+- `observability`
+- `frontend-design`