@agent-native/core 0.86.1 → 0.88.0

package/docs/content/locales/ja-JP/agent-native-toolkit.mdx

@@ -0,0 +1,67 @@
+---
+title: "Agent-Native ツールキット"
+description: "コラボレーション、設定、共有、ナビゲーション、プレゼンス、履歴、セットアップ、Agent UX の再利用可能なキット。"
+---
+
+# Agent-Native ツールキット
+
+Agent-Native のアプリは、workspace の共通機能を毎回作り直すべきではありません。
+アプリはドメインモデル、ドメイン action、固有のビューを持ちます。Framework と
+`@agent-native/toolkit` は、すべてのアプリが継承すべき再利用可能な面を持ちます:
+コラボレーション、共有、設定、ナビゲーション、整理、セットアップ、Agent UX、履歴、
+運用の可視性です。
+
+ユーザーが覚える共有方法、キー接続、Agent の共同編集表示、設定の場所、変更履歴の見方は
+ひとつであるべきです。
+
+## ツールキットの契約 {#toolkit-contract}
+
+次の条件に当てはまる動作は toolkit に移します。
+
+- **Workspace 全体** - すべてのアプリで同じ挙動が期待される。
+- **Agent から見える** - action、instructions、application state を通じて Agent も使う。
+- **Governed** - 権限、audit、secrets、org policy、billing、sharing rules が関係する。
+- **繰り返される** - 2 つ以上のアプリが似た UI やロジックを持つ。
+- **ドメイン固有ではない** - アプリはリソース名と action を渡し、操作パターンは汎用。
+
+ドメインモデルやアプリ固有の 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** - リアルタイム編集、Yjs docs、presence、agent presence、live
+  cursors、remote selections、recent edit highlights、共有 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、共通 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. collaboration、presence、agent presence、undo/redo、real-time editing を共有
+   adapters の後ろに揃えます。
+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/ja-JP/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 プリミティブ、共有 hooks、シンプルなアプリ shell ヘルパー、その他のテンプレート合成モジュールです。移行中、Core は互換性 re-export を保持しますが、新しいテンプレートとアプリのコードは toolkit モジュールを直接 import してください:
+
+```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-9epcij" title={"フレームワークの外ではなく、レイヤーをドロップダウンします"} summary={"各レイヤーは同じランタイム (アクション、スレッド状態、SQL-backed 同期) を維持しながら、クロムをより詳細に制御できます。"}>
 
 ```html

package/docs/content/locales/ja-JP/creating-templates.mdx

@@ -7,6 +7,8 @@ description: "独自のエージェント ネイティブ アプリ テンプレ
 
 テンプレートは、実際のワークフローを解決する完全なフォーク可能なエージェント ネイティブ アプリです。ファーストパーティ テンプレートは、使用するのと同じフレームワーク サーフェスを使用して構築されます。UI の React ルート、データの Drizzle SQL、操作の actions、エージェントの動作のワークスペース リソース、およびエージェントと UI の連携を維持するためのポーリング同期です。
 
+`@agent-native/core` は runtime contract に使用します: actions、server plugins、database helpers、app state、routing helpers、agent chat です。`@agent-native/toolkit` は shared primitives、toast/mobile hooks、date pickers、simple app shell slots などの再利用可能な app-building UI と helpers に使用します。製品動作や visual identity を表す template-specific variants はローカルに保持してください。
+
 良いテンプレート:
 
 - 有用なシード データまたは空の状態のフローを使用して、1 つのワークフローをエンドツーエンドで解決します。

package/docs/content/locales/ja-JP/sharing.mdx

@@ -93,9 +93,10 @@ description: "フレームワークに組み込まれた Google ドキュメン
 - **スライド** — デッキ
 - **デザイン** — デザインとアセット
 - **クリップ** — 画面録画 (Loom スタイル)
+- **Plan** — visual plans and PR recaps
 - **フォーム** — フォーム定義
 - **カレンダー** — イベントと予約リンク
-- **Analytics** — ダッシュボード (展開中 — 分析テンプレートの `AGENTS.md` を参照)
+- **Analytics** — 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) を参照)、配線の共有は短くなります。スキーマへの 2 つの追加:

package/docs/content/locales/ja-JP/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/ja-JP/template-clips.mdx

@@ -133,6 +133,13 @@ API なので、テキストまたは静止画像のみを受け入れるモデ
 
 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.
+
 エンドポイントは、共有ページと同じパブリック/パスワード/有効期限ルールに従います。
 パスワードで保護されたクリップでは、パスワードが 1 回必要になります。成功した応答が返されます
 トークン化されたリンクは有効期間が短いため、ダウンストリーム エージェントはプレーンテキストを必要としません

package/docs/content/locales/ja-JP/tracking.mdx

@@ -241,6 +241,12 @@ Analytics テンプレートは、リプレイ メタデータを SQL (`session_
 
 プライベートな記録を外部エージェントに渡す必要がある場合は、セッション詳細ページの **Copy for agent** コントロールを使用します。これにより、2 時間有効で記録にスコープされた `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 インライン チャンクにフォールバックできます。本番デプロイでは、リプレイ ペイロードを Postgres に依存するのではなく、プライベートまたは暗号化された blob ストレージを設定する必要があります。
 
 ## 上級: カスタムプロバイダーと内部 {#advanced}

package/docs/content/locales/ko-KR/agent-native-toolkit.mdx

@@ -0,0 +1,63 @@
+---
+title: "Agent-Native 툴킷"
+description: "협업, 설정, 공유, 탐색, presence, 기록, 설정 준비, Agent UX를 위한 재사용 가능한 키트."
+---
+
+# Agent-Native 툴킷
+
+Agent-Native 앱은 workspace 공통 기능을 매번 다시 만들면 안 됩니다. 앱은 도메인 모델,
+도메인 action, 제품별 화면을 소유합니다. Framework와 `@agent-native/toolkit`은 모든 앱이
+상속해야 하는 재사용 가능한 표면을 소유합니다: 협업, 공유, 설정, 탐색, 정리, 설정 준비,
+Agent UX, 기록, 운영 가시성입니다.
+
+사용자는 공유, 키 연결, Agent의 공동 편집, 설정 위치, 변경 내역을 앱마다 새로 배우지 않아야 합니다.
+
+## 툴킷 계약 {#toolkit-contract}
+
+다음에 해당하면 동작을 toolkit으로 옮깁니다.
+
+- **Workspace 전체** - 모든 앱에서 같은 방식으로 동작해야 합니다.
+- **Agent-visible** - Agent가 actions, instructions, application state를 통해 같은 기능을 써야 합니다.
+- **Governed** - 권한, audit, secrets, org policy, billing, sharing rules가 적용됩니다.
+- **Repeated** - 두 앱 이상이 비슷한 UI나 로직을 이미 만들었습니다.
+- **Not domain-specific** - 앱은 resource 이름과 action을 제공하지만 interaction pattern은 일반적입니다.
+
+도메인 모델이나 앱 고유 workflow에 깊게 묶인 동작은 app-local로 둡니다.
+
+## 재사용 가능한 키트 {#reusable-kits}
+
+- **Settings kit** - account, workspace, AI models, LLM keys, connections,
+  secrets, usage, notifications, changelog, app preferences의 표준 tabs입니다. 지속 설정은
+  Settings에 두고 Agent sidebar는 contextual 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. collaboration, presence, agent presence, undo/redo, real-time editing을 공유 adapters 뒤로 정규화합니다.
+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/ko-KR/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, 단순 app shell helpers, 기타 template composition modules입니다. 전환 기간 동안 Core는 호환성 re-export를 유지하지만, 새 템플릿과 앱 코드는 toolkit modules를 직접 가져와야 합니다:
+
+```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-wyryue" title={"프레임워크 외부가 아닌 레이어를 드롭다운하세요."} summary={"각 레이어는 동일한 런타임(작업, 스레드 상태, SQL-backed 동기화)을 유지하면서 크롬에 대한 더 많은 제어권을 제공합니다."}>
 
 ```html

package/docs/content/locales/ko-KR/creating-templates.mdx

@@ -7,6 +7,8 @@ description: "자신만의 에이전트 기반 앱 템플릿을 만들고 게시
 
 템플릿은 실제 워크플로를 해결하는 완전하고 포크 가능한 에이전트 기반 앱입니다. 자사 템플릿은 귀하가 사용하는 것과 동일한 프레임워크 표면으로 구축됩니다. UI용 React 경로, 데이터용 Drizzle SQL, 작업용 actions, 에이전트 동작용 작업 공간 리소스, 에이전트와 UI가 정렬 상태를 유지하도록 폴링 동기화합니다.
 
+`@agent-native/core`는 runtime contract에 사용하세요: actions, server plugins, database helpers, app state, routing helpers, agent chat입니다. `@agent-native/toolkit`은 shared primitives, toast/mobile hooks, date pickers, simple app shell slots 같은 reusable app-building UI와 helpers에 사용하세요. 제품 동작이나 visual identity를 담는 template-specific variants는 로컬에 유지하세요.
+
 좋은 템플릿:
 
 - 유용한 시드 데이터 또는 빈 상태 흐름을 사용하여 하나의 워크플로를 엔드 투 엔드로 해결합니다.

package/docs/content/locales/ko-KR/sharing.mdx

@@ -93,9 +93,10 @@ Google 문서도구처럼 보이고 작동합니다. 동일한 공유 버튼,
 - **슬라이드** — 자료
 - **디자인** — 디자인 및 자산
 - **클립** — 화면 녹화(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/ko-KR/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/ko-KR/template-clips.mdx

@@ -133,6 +133,13 @@ API, 텍스트나 정지 이미지만 허용하는 모델도 여전히 무엇을
 
 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/ko-KR/tracking.mdx

@@ -241,6 +241,12 @@ Analytics 템플릿은 리플레이 메타데이터를 SQL(`session_recordings`)
 
 프라이빗 녹화를 외부 에이전트에게 전달해야 할 때는 세션 상세 페이지의 **Copy for agent** 컨트롤을 사용하세요. 이는 두 시간 동안 유효한 녹화 범위의 `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 인라인 청크로 대체할 수 있습니다. 프로덕션 배포에서는 리플레이 페이로드를 Postgres에 의존하기보다 프라이빗 또는 암호화된 blob 스토리지를 구성해야 합니다.
 
 ## 고급: 맞춤형 공급자 및 내부 {#advanced}

package/docs/content/locales/pt-BR/agent-native-toolkit.mdx

@@ -0,0 +1,77 @@
+---
+title: "Toolkit do Agent-Native"
+description: "Kits reutilizáveis para colaboração, configurações, compartilhamento, navegação, presença, histórico, setup e UX do agente."
+---
+
+# Toolkit do Agent-Native
+
+Apps Agent-Native não devem reconstruir a infraestrutura comum do workspace.
+Apps são donas dos modelos de domínio, ações de domínio e telas específicas do
+produto. O framework e `@agent-native/toolkit` são donos das superfícies
+reutilizáveis que toda app deve herdar: colaboração, compartilhamento,
+configurações, navegação, organização, setup, UX do agente, histórico e
+visibilidade operacional.
+
+O objetivo é que usuários aprendam uma única forma de compartilhar, conectar
+chaves, ver o agente editando junto, encontrar configurações e entender o que
+mudou.
+
+## Contrato do toolkit {#toolkit-contract}
+
+Mova comportamento para o toolkit quando ele for:
+
+- **Do workspace** - usuários esperam o mesmo comportamento em todas as apps.
+- **Visível ao agente** - o agente precisa da mesma capacidade por ações,
+  instruções ou estado da aplicação.
+- **Governado** - permissões, auditoria, secrets, política da org, cobrança ou
+  regras de compartilhamento se aplicam.
+- **Repetido** - duas apps já criaram UI ou lógica parecida.
+- **Não específico de domínio** - a app fornece nomes e ações de recursos, mas o
+  padrão de interação é genérico.
+
+Mantenha local quando o comportamento depender do modelo de domínio ou de um
+fluxo específico da app.
+
+## Kits reutilizáveis {#reusable-kits}
+
+- **Settings kit** - abas padrão para conta, workspace, modelos de AI, chaves
+  LLM, conexões, secrets, uso, notificações, changelog e preferências da app.
+  Configuração durável fica em Settings; a sidebar do agente mantém controles
+  contextuais e deep links.
+- **Collaboration kit** - edição em tempo real, documentos Yjs, presença,
+  presença do agente, cursores, seleções remotas, destaques de edição e
+  undo/redo compartilhado. Veja
+  [Real-Time Collaboration](/docs/real-time-collaboration).
+- **Sharing kit** - um modelo de privacidade e permissões para privado,
+  workspace, org, link público, convites, roles, expiração e acesso legível pelo
+  agente. Veja [Sharing & Privacy](/docs/sharing).
+- **Navigation and command kit** - app shell, navegação, breadcrumbs, app
+  switcher, command palette, recursos recentes, fixados e busca.
+- **Organization kit** - pastas, tags, favoritos, arquivo, lixeira, ownership,
+  membros e metadados comuns.
+- **Setup and connections kit** - chaves API, OAuth, conexões, prontidão de
+  modelos, secrets ausentes e onboarding declarativo. Veja
+  [Workspace Connections](/docs/workspace-connections).
+- **Agent UX kit** - sidebar, composer, contexto preparado, menções, voz,
+  aprovação humana, UI generativa, progresso e estado visível ao agente.
+- **History and recovery kit** - audit log, activity feed, version history,
+  checkpoints, undo, redo, restore e proof-of-done. Veja
+  [Audit Log](/docs/audit-log).
+- **Comments and review kit** - comentários ancorados, pins, menções, pedidos de
+  review, threads resolvidas e follow-ups do agente.
+- **Workflow and observability kit** - notificações, aprovações, background
+  runs, jobs recorrentes, traces, evals, feedback e timelines. Veja
+  [Observability](/docs/observability).
+
+## Ordem de implementação {#implementation-order}
+
+1. Consolidar configuração durável em abas padrão de Settings.
+2. Normalizar colaboração, presença, presença do agente, undo/redo e edição em
+   tempo real por adapters compartilhados.
+3. Mover navegação, comandos, recentes, favoritos, pastas, tags, arquivo e
+   lixeira para primitivas compartilhadas.
+4. Registrar todo recurso compartilhável no mesmo modelo de permissões e acesso
+   legível pelo agente.
+5. Dar a cada recurso colaborativo uma história consistente de atividade,
+   comentários, review, restore e auditoria.
+6. Unificar notificações, aprovações, status de runs, traces, evals e feedback.

package/docs/content/locales/pt-BR/components.mdx

@@ -25,6 +25,15 @@ Evite importar componentes UI do pacote `@agent-native/core` simples. Usar
 `@agent-native/core/client` ou um subcaminho `@agent-native/core/client/*` em foco
 para que os empacotadores escolham a entrada segura para o navegador.
 
+Use `@agent-native/toolkit` para peças reutilizáveis de construção de aplicativos que não fazem parte do contrato fundamental do runtime: primitivas UI no estilo shadcn, hooks compartilhados, helpers simples de shell do app e outros módulos de composição de templates. Core mantém reexports de compatibilidade durante a transição, mas novo código de templates e apps deve importar módulos do toolkit diretamente:
+
+```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-smqhxh" title={"Desça uma camada, não fora da estrutura"} summary={"Cada camada mantém o mesmo tempo de execução – ações, estado do thread e sincronização SQL-backed – enquanto oferece mais controle sobre o cromo."}>
 
 ```html

package/docs/content/locales/pt-BR/creating-templates.mdx

@@ -7,6 +7,8 @@ description: "Como criar e publicar seus próprios modelos de aplicativos nativo
 
 Os modelos são aplicativos nativos do agente completos e bifurcáveis que resolvem um fluxo de trabalho real. Os modelos primários são criados com a mesma superfície de estrutura que você usa: rotas React para UI, Drizzle SQL para dados, actions para operações, recursos de espaço de trabalho para comportamento do agente e sincronização de sondagem para que o agente e UI permaneçam alinhados.
 
+Use `@agent-native/core` para o contrato de runtime: actions, plugins de servidor, helpers de banco de dados, estado do app, helpers de rotas e chat do agente. Use `@agent-native/toolkit` para UI reutilizável e helpers de construção de apps, como primitivas compartilhadas, hooks de toast/mobile, seletores de data e slots simples de shell do app. Mantenha variantes específicas do template locais quando elas codificarem comportamento de produto ou identidade visual.
+
 Um bom modelo:
 
 - Resolve um fluxo de trabalho de ponta a ponta, com dados iniciais úteis ou um fluxo de estado vazio.

package/docs/content/locales/pt-BR/sharing.mdx

@@ -93,9 +93,10 @@ Todo modelo que armazena trabalhos de autoria do usuário usa esse modelo. Concr
 - **Apresentações** — apresentações
 - **Design** — designs e recursos
 - **Clipes** — gravações de tela (estilo Loom)
+- **Plan** — visual plans and PR recaps
 - **Formulários** — definições de formulário
 - **Calendário** — links para eventos e reservas
-- **Analytics** — painéis (lançamento — veja o modelo de análise `AGENTS.md`)
+- **Analytics** — dashboards, saved analyses, and tokenized session replays
 - **Extensões** — miniaplicativos em sandbox (consulte [Extensions](/docs/extensions#sharing))
 
 Cada um deles usa o mesmo auxiliar de esquema `ownableColumns()`, a mesma ação `share-resource` e o mesmo `<ShareButton>` UI. Mude de um modelo para outro e a caixa de diálogo de compartilhamento parecerá idêntica.
@@ -136,15 +137,22 @@ Para listas, coloque um `<VisibilityBadge visibility={row.visibility} />` ao lad
 
 A estrutura monta automaticamente esses actions em cada modelo — o agente os chama como ferramentas e o UI os chama por meio de `useActionQuery` / `useActionMutation`:
 
-| Ação                      | O que faz                                                                                                                |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `share-resource`          | Conceda acesso a um usuário ou organização em uma função específica. `notify` opcional controla notificações por e-mail. |
-| `unshare-resource`        | Revogar o acesso de um usuário ou organização.                                                                           |
-| `list-resource-shares`    | Mostrar a visibilidade atual e todas as concessões explícitas.                                                           |
-| `set-resource-visibility` | Mude para `private`, `org` ou `public`.                                                                                  |
+| Ação                         | O que faz                                                                                                                |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `share-resource`             | Conceda acesso a um usuário ou organização em uma função específica. `notify` opcional controla notificações por e-mail. |
+| `unshare-resource`           | Revogar o acesso de um usuário ou organização.                                                                           |
+| `list-resource-shares`       | Mostrar a visibilidade atual e todas as concessões explícitas.                                                           |
+| `set-resource-visibility`    | Mude para `private`, `org` ou `public`.                                                                                  |
+| `create-agent-resource-link` | Mint a temporary read-only `agent_access` URL for a registered agent-readable resource.                                  |
 
 Diga ao agente "compartilhe este design com a equipe de marketing como editores" e ele chamará `share-resource` no mesmo endpoint que UI usa. O resultado aparece na caixa de diálogo de compartilhamento na próxima renderização.
 
+## 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`.
+
 ## Construindo-o em um novo modelo {#building}
 
 Se você estiver criando um modelo (consulte [Creating Templates](/docs/creating-templates)), o compartilhamento de conexão será curto. Duas adições ao seu esquema:

package/docs/content/locales/pt-BR/template-analytics.mdx

@@ -149,6 +149,12 @@ O CLI imprime o dev local URL. Faça login com o Google e abra a página **Fonte
 
 **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.
+
 ### Trabalhando com o agente
 
 O agente sempre sabe o que você está vendo. O estado atual da tela é injetado em cada mensagem como um bloco `<current-screen>` — ele contém a visualização ativa, o painel ou análise aberta e quaisquer filtros selecionados.

package/docs/content/locales/pt-BR/template-clips.mdx

@@ -133,6 +133,13 @@ agente.
 
 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.
+
 Os endpoints seguem as mesmas regras de público/senha/expiração da página de compartilhamento.
 Clipes protegidos por senha exigem a senha uma vez; retorno de respostas bem-sucedidas
 links tokenizados de curta duração para que os agentes downstream não precisem do texto simples

package/docs/content/locales/pt-BR/tracking.mdx

@@ -241,6 +241,12 @@ O modelo Analytics armazena os metadados de replay em SQL (`session_recordings`)
 
 Quando você precisar entregar uma gravação privada a um agente externo, use o controle **Copy for agent** da página de detalhes da sessão. Ele emite um link `agent_access` com escopo de gravação e validade de duas horas, renderiza via SSR um pequeno payload de descoberta em `/sessions/:recordingId`, e expõe apenas as APIs JSON de contexto/eventos do agente. A visibilidade da gravação não muda.
 
+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.
+
 Apenas para desenvolvimento local, o Analytics pode recorrer a blocos embutidos em SQL com limite de tamanho quando o armazenamento privado de blob não estiver disponível. As implantações de produção devem configurar armazenamento de blob privado ou criptografado, em vez de depender do Postgres para os payloads de replay.
 
 ## Avançado: provedores personalizados e internos {#advanced}