@agent-native/core 0.86.1 → 0.88.0

package/corpus/README.md

@@ -27,5 +27,5 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 2046
-- template files: 4839
+- core files: 2062
+- template files: 4304

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @agent-native/core
 
+## 0.88.0
+
+### Minor Changes
+
+- 945c525: Add shared scoped agent-access helpers, agent-readable resource discovery helpers, and a `create-agent-resource-link` action for bot-visible resource links and JSON API URLs.
+
+## 0.87.0
+
+### Minor Changes
+
+- b24446e: Add shared scoped agent-access helpers for bot-visible resource links and JSON API URLs, and keep commonly imported server utilities browser-safe when template route modules are bundled.
+
+### Patch Changes
+
+- b24446e: Add `@agent-native/toolkit` for reusable app-building UI, move shared template primitives into it, and keep core UI shim imports working through compatibility re-exports.
+- Updated dependencies [b24446e]
+  - @agent-native/toolkit@0.2.0
+
 ## 0.86.1
 
 ### Patch Changes

package/corpus/core/docs/content/agent-native-toolkit.mdx

@@ -0,0 +1,162 @@
+---
+title: "Agent-Native Toolkit"
+description: "Reusable app-building kits for collaboration, settings, sharing, navigation, presence, history, setup, and agent UX."
+---
+
+# Agent-Native Toolkit
+
+Agent-Native apps should not rebuild workspace plumbing. Apps own their domain
+models, domain actions, and product-specific views. The framework and
+`@agent-native/toolkit` own the reusable product surface that every app should
+inherit: collaboration, sharing, settings, navigation, setup, resource
+organization, agent UX, history, and operational visibility.
+
+The point is not only faster app development. The point is that users learn one
+way to share, one way to connect API keys, one way to see the agent editing
+beside them, one way to find settings, and one way to understand what changed.
+
+## Toolkit Contract {#toolkit-contract}
+
+Move behavior into the toolkit when it is:
+
+- **Workspace-wide** - users expect it to work the same across apps.
+- **Agent-visible** - the agent needs the same capability through actions,
+  instructions, or application state.
+- **Governed** - permissions, audit history, secrets, org policy, billing, or
+  sharing rules apply.
+- **Repeated** - two apps have already built similar UI or logic.
+- **Non-domain-specific** - the app supplies resource names and actions, but the
+  interaction pattern is generic.
+
+Keep behavior app-local when it is tied to a domain model, a custom workflow, or
+an app-specific mental model that would become awkward as a generic abstraction.
+
+## Reusable Kits {#reusable-kits}
+
+### Settings Kit {#settings-kit}
+
+Every app should get standard settings tabs for account, workspace, AI models,
+LLM keys, connections, secrets, usage, notifications, changelog, and app-specific
+preferences. Persistent configuration should live under the Settings app or a
+registered settings route. The agent sidebar should keep contextual quick
+controls and deep links into the right settings tab, not a second large settings
+surface.
+
+Apps register their own settings panels instead of inventing separate settings
+navigation. Standard links should be stable, for example `/settings/ai`,
+`/settings/connections`, `/settings/secrets`, and `/settings/apps/:appId`.
+
+### Collaboration Kit {#collaboration-kit}
+
+Use the framework collaboration layer for real-time editing, Yjs documents,
+presence, agent presence, live cursors, remote selections, recent edit
+highlights, and shared undo grouping. See
+[Real-Time Collaboration](/docs/real-time-collaboration).
+
+Apps should provide adapters for their document shape. The toolkit should
+provide the shared editing chrome: who is here, where the agent is editing,
+whether edits are synced, and how undo/redo behaves when humans and agents edit
+together.
+
+### Sharing Kit {#sharing-kit}
+
+Resources should share through one privacy and permission model: private,
+workspace, org, public link, invite, role, expiration, and agent-readable access.
+Apps should register resource types and access rules instead of creating one-off
+share dialogs. See [Sharing & Privacy](/docs/sharing).
+
+### Navigation And Command Kit {#navigation-and-command-kit}
+
+Apps should reuse one shell model for primary nav, breadcrumbs, app switcher,
+command palette entries, recent resources, pinned resources, and global search.
+The app supplies resource routes and commands; the toolkit supplies the chrome,
+keyboard patterns, and indexing conventions.
+
+### Organization Kit {#organization-kit}
+
+Common organization primitives belong in the toolkit: folders, tags, favorites,
+archive, trash, recents, ownership, workspace membership, and resource metadata.
+This keeps dashboards, documents, decks, forms, recordings, and designs from
+each inventing a different organization system.
+
+### Setup And Connections Kit {#setup-and-connections-kit}
+
+API keys, OAuth grants, provider connections, model readiness, missing-secret
+states, and onboarding checks should be declarative. Apps register what they
+need; the shared setup surface explains what is missing and links to the
+standard settings tab. See [Workspace Connections](/docs/workspace-connections)
+and [Onboarding](/docs/onboarding).
+
+### Agent UX Kit {#agent-ux-kit}
+
+The sidebar, composer, staged context, mentions, voice input, run progress,
+human approval, generative UI, and agent-visible screen state should feel like
+one system across apps. Apps should expose context and actions; the toolkit
+should render the agent interaction surface. See
+[Component API](/docs/components) and
+[Context Awareness](/docs/context-awareness).
+
+### History And Recovery Kit {#history-and-recovery-kit}
+
+Users need one way to answer "what changed?", "who did it?", "can I undo it?",
+and "can I restore an older version?" Audit log, activity feed, version history,
+undo/redo, checkpoints, and restore flows should share a toolkit contract even
+when each app has different resource content. See [Audit Log](/docs/audit-log).
+
+### Comments And Review Kit {#comments-and-review-kit}
+
+Anchored comments, pins, review requests, resolved threads, mentions, and agent
+follow-up tasks are reusable. Apps provide anchor adapters for text ranges,
+slides, canvas nodes, rows, clips, or dashboard widgets; the toolkit owns the
+thread UX and notification model.
+
+### Notifications And Workflow Kit {#notifications-and-workflow-kit}
+
+Notifications, approvals, scheduled work, background runs, recurring jobs, and
+automation status should not be app-specific chrome. Apps emit domain events and
+actions; the toolkit handles subscriptions, inboxes, approval prompts, and
+status surfaces. See [Notifications](/docs/notifications),
+[Human Approval](/docs/human-approval), and [Automations](/docs/automations).
+
+### Observability Kit {#observability-kit}
+
+Agentic apps need first-class traces, feedback, evals, run timelines, tool-call
+inspection, and proof-of-done views. The toolkit should make these available to
+builders and, where appropriate, to end users. See
+[Observability](/docs/observability) and [Progress](/docs/progress).
+
+## What Every App Should Inherit {#what-every-app-should-inherit}
+
+New apps should start with these defaults:
+
+- Standard Settings tabs and stable settings deep links.
+- Shared agent sidebar, composer, command palette, and app shell primitives.
+- Shared setup checks for model keys, OAuth connections, and secrets.
+- Shared sharing dialog and resource permission model.
+- Shared organization primitives for recents, favorites, folders, tags, archive,
+  and trash.
+- Shared real-time presence, agent presence, undo/redo, and edit sync indicators
+  when the app has collaborative resources.
+- Shared comments, review threads, notifications, and activity history when the
+  app has reviewable resources.
+- Shared audit log, version history, restore, and proof-of-done patterns.
+- App-specific actions, resource adapters, and context providers that plug into
+  the shared surfaces.
+
+## Implementation Order {#implementation-order}
+
+1. **Settings** - consolidate durable configuration into standard Settings tabs,
+   then replace sidebar settings sprawl with deep links and quick controls.
+2. **Collaboration** - normalize real-time editing, undo/redo, presence, agent
+   presence, and recent edit highlights behind shared adapters.
+3. **Navigation and organization** - move sidebars, command palette entries,
+   recents, favorites, folders, tags, archive, and trash into shared primitives.
+4. **Resource sharing** - make every shareable app resource register with the
+   same sharing, privacy, role, and agent-readable access model.
+5. **History, comments, and review** - give every collaborative resource a
+   consistent activity, comment, review, restore, and audit story.
+6. **Workflow and observability** - unify notifications, approvals, background
+   run status, traces, evals, and user feedback.
+
+This keeps the toolkit opinionated without making every app identical: apps
+bring the domain; the toolkit brings the reusable operating system around it.

package/corpus/core/docs/content/components.mdx

@@ -25,6 +25,19 @@ Avoid importing UI components from the bare `@agent-native/core` package. Use
 `@agent-native/core/client` or a focused `@agent-native/core/client/*` subpath
 so bundlers choose the browser-safe entry.
 
+Use `@agent-native/toolkit` for reusable app-building pieces that are not part
+of the foundational runtime contract: shadcn-style UI primitives, shared hooks,
+simple app shell helpers, and other template composition modules. Core keeps
+compatibility re-exports for migrated internals during the transition, but new
+template and app code should import toolkit modules directly:
+
+```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-u3yfqy" title="Drop down a layer, not out of the framework" summary={"Each layer keeps the same runtime — actions, thread state, and SQL-backed sync — while giving you more control over the chrome."}>
 
 ```html

package/corpus/core/docs/content/creating-templates.mdx

@@ -7,6 +7,13 @@ description: "How to create and publish your own agent-native app templates."
 
 Templates are complete, forkable agent-native apps that solve a real workflow. The first-party templates are built with the same framework surface you use: React routes for the UI, Drizzle SQL for data, actions for operations, workspace resources for agent behavior, and polling sync so the agent and UI stay aligned.
 
+Use `@agent-native/core` for the runtime contract: actions, server plugins,
+database helpers, app state, routing helpers, and agent chat. Use
+`@agent-native/toolkit` for reusable app-building UI and helpers such as shared
+shadcn-style primitives, toast/mobile hooks, date pickers, and simple app shell
+slots. Keep template-specific variants local when they encode product behavior
+or visual identity.
+
 A good template:
 
 - Solves one workflow end-to-end, with useful seed data or an empty-state flow.

package/corpus/core/docs/content/locales/ar-SA/agent-native-toolkit.mdx

@@ -0,0 +1,73 @@
+---
+title: "مجموعة أدوات Agent-Native"
+description: "مجموعات قابلة لإعادة الاستخدام للتعاون والإعدادات والمشاركة والتنقل والحضور والسجل والإعداد وتجربة الوكيل."
+---
+
+# مجموعة أدوات Agent-Native
+
+لا ينبغي لتطبيقات Agent-Native إعادة بناء بنية الـ workspace المشتركة في كل
+مرة. تمتلك التطبيقات نماذج المجال و actions الخاصة بالمجال وواجهات المنتج. أما
+الإطار و `@agent-native/toolkit` فيمتلكان السطوح القابلة لإعادة الاستخدام التي
+ينبغي أن يرثها كل تطبيق: التعاون، المشاركة، الإعدادات، التنقل، التنظيم،
+الإعداد، تجربة Agent، السجل، والرؤية التشغيلية.
+
+يجب أن يتعلم المستخدمون طريقة واحدة للمشاركة، وطريقة واحدة لربط المفاتيح،
+ومكانا واحدا للإعدادات، وطريقة واحدة لرؤية Agent وهو يحرر معهم وفهم ما تغير.
+
+## عقد مجموعة الأدوات {#toolkit-contract}
+
+انقل السلوك إلى toolkit عندما يكون:
+
+- **على مستوى workspace** - يتوقع المستخدمون السلوك نفسه في كل التطبيقات.
+- **مرئيا للـ Agent** - يحتاج Agent إلى القدرة نفسها عبر actions أو instructions
+  أو application state.
+- **محكوما** - تنطبق عليه الصلاحيات أو audit أو secrets أو سياسة المؤسسة أو
+  billing أو قواعد المشاركة.
+- **متكررا** - بنى تطبيقان بالفعل UI أو logic متشابهين.
+- **غير خاص بالمجال** - يقدم التطبيق أسماء الموارد و actions، لكن نمط التفاعل
+  عام.
+
+أبق السلوك محليا عندما يكون مرتبطا بنموذج مجال أو workflow خاص بالتطبيق.
+
+## مجموعات قابلة لإعادة الاستخدام {#reusable-kits}
+
+- **Settings kit** - تبويبات قياسية للحساب، workspace، نماذج AI، مفاتيح LLM،
+  الاتصالات، secrets، الاستخدام، notifications، changelog وتفضيلات التطبيق.
+  تبقى الإعدادات الدائمة في Settings؛ وتبقى sidebar الخاصة بالـ Agent للروابط
+  العميقة والتحكم السياقي فقط.
+- **Collaboration kit** - تحرير فوري، مستندات Yjs، 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 والدعوات والأدوار والانتهاء و 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 القياسية.
+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 تجربة متسقة للنشاط والتعليقات والمراجعة
+   والاستعادة و audit.
+6. وحّد notifications و approvals و run status و traces و evals و feedback.

package/corpus/core/docs/content/locales/ar-SA/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` للقطع القابلة لإعادة الاستخدام في بناء التطبيقات التي ليست جزءا من عقد وقت التشغيل الأساسي: عناصر UI بأسلوب shadcn، hooks المشتركة، مساعدات هيكل التطبيق البسيطة، ووحدات تركيب القوالب. يحتفظ Core بإعادة تصدير توافقية أثناء الانتقال، لكن يجب أن تستورد القوالب والتطبيقات الجديدة وحدات 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-1vw6fvr" title={"المنسدلة طبقة، وليس خارج الإطار"} summary={"تحتفظ كل طبقة بنفس وقت التشغيل — الإجراءات، وحالة مؤشر الترابط، ومزامنة SQL-backed — بينما تمنحك مزيدًا من التحكم في Chrome."}>
 
 ```html

package/corpus/core/docs/content/locales/ar-SA/creating-templates.mdx

@@ -7,6 +7,8 @@ description: "كيفية إنشاء ونشر قوالب تطبيقات الوك
 
 النماذج عبارة عن تطبيقات متكاملة ومتشعبة للوكلاء الأصليين تعمل على حل سير العمل الحقيقي. تم إنشاء قوالب الطرف الأول بنفس سطح إطار العمل الذي تستخدمه: مسارات React لـ UI، وDrizzle SQL للبيانات، وactions للعمليات، وموارد مساحة العمل لسلوك الوكيل، ومزامنة الاستقصاء بحيث يظل الوكيل وUI متوازيين.
 
+استخدم `@agent-native/core` لعقد وقت التشغيل: actions، مكونات server الإضافية، مساعدات قاعدة البيانات، حالة التطبيق، مساعدات التوجيه، ودردشة الوكيل. استخدم `@agent-native/toolkit` لعناصر UI ومساعدات بناء التطبيقات القابلة لإعادة الاستخدام مثل primitives المشتركة، hooks للتنبيه والجوال، منتقيات التاريخ، وفتحات هيكل التطبيق البسيطة. أبق المتغيرات الخاصة بالقالب محلية عندما تعبّر عن سلوك المنتج أو هويته البصرية.
+
 نموذج جيد:
 
 - يعمل على حل سير عمل واحد من البداية إلى النهاية، باستخدام بيانات أولية مفيدة أو تدفق في حالة فارغة.

package/corpus/core/docs/content/locales/ar-SA/sharing.mdx

@@ -93,9 +93,10 @@ description: "المشاركة بأسلوب Google-Docs، المضمنة في إ
 - **الشرائح** — التشكيلات
 - **التصميم** — التصاميم والأصول
 - **المقاطع** — تسجيلات الشاشة (نمط المنوال)
+- **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.            |
 
 أخبر الوكيل "بمشاركة هذا التصميم مع فريق التسويق كمحررين" وسيقوم باستدعاء `share-resource` مقابل نفس نقطة النهاية التي يستخدمها UI. تظهر النتيجة في مربع حوار المشاركة في العرض التالي.
 
+## 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/corpus/core/docs/content/locales/ar-SA/template-analytics.mdx

@@ -149,6 +149,12 @@ pnpm dev
 
 **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/corpus/core/docs/content/locales/ar-SA/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/corpus/core/docs/content/locales/ar-SA/tracking.mdx

@@ -241,6 +241,12 @@ VITE_AGENT_NATIVE_SESSION_REPLAY_SAMPLE_RATE=0.1
 
 عندما تحتاج إلى تسليم تسجيل خاص إلى وكيل خارجي، استخدم عنصر التحكم **نسخ للوكيل** في صفحة تفاصيل الجلسة. فهو يُنشئ رابط `agent_access` محدد النطاق بالتسجيل ومدته ساعتان، ويقوم بعرض SSR لحمولة اكتشاف صغيرة على `/sessions/:recordingId`، ولا يكشف إلا عن واجهات برمجة تطبيقات JSON الخاصة بسياق/أحداث الوكيل. لا تتغير رؤية التسجيل.
 
+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 الرجوع إلى أجزاء SQL مضمّنة محدودة السعة عندما يكون تخزين blob الخاص غير متاح. يجب أن تُهيّئ عمليات النشر في الإنتاج تخزين blob خاصًا أو مشفّرًا بدلاً من الاعتماد على Postgres لحمولات إعادة التشغيل.
 
 ## متقدم: الموفرون المخصصون والداخليون {#advanced}

package/corpus/core/docs/content/locales/de-DE/agent-native-toolkit.mdx

@@ -0,0 +1,77 @@
+---
+title: "Agent-Native-Toolkit"
+description: "Wiederverwendbare Kits für Zusammenarbeit, Einstellungen, Teilen, Navigation, Präsenz, Verlauf, Einrichtung und Agent-UX."
+---
+
+# Agent-Native-Toolkit
+
+Agent-Native-Apps sollten Workspace-Infrastruktur nicht neu bauen. Apps besitzen
+ihre Domänenmodelle, Domänenaktionen und produktspezifischen Ansichten. Das
+Framework und `@agent-native/toolkit` besitzen die wiederverwendbare
+Produktoberfläche, die jede App erben sollte: Zusammenarbeit, Teilen,
+Einstellungen, Navigation, Organisation, Einrichtung, Agent-UX, Verlauf und
+operative Sichtbarkeit.
+
+Nutzer sollen eine einzige Art lernen, Ressourcen zu teilen, Schlüssel zu
+verbinden, den Agenten beim Bearbeiten zu sehen, Einstellungen zu finden und
+Änderungen zu verstehen.
+
+## Toolkit-Vertrag {#toolkit-contract}
+
+Verschiebe Verhalten in das Toolkit, wenn es:
+
+- **Workspace-weit** ist - Nutzer erwarten dasselbe Verhalten in allen Apps.
+- **Für den Agenten sichtbar** ist - der Agent braucht dieselbe Fähigkeit über
+  Aktionen, Anweisungen oder Application State.
+- **Governed** ist - Berechtigungen, Audit, Secrets, Org-Policy, Billing oder
+  Sharing-Regeln gelten.
+- **Wiederholt** ist - zwei Apps haben bereits ähnliche UI oder Logik gebaut.
+- **Nicht domänenspezifisch** ist - die App liefert Ressourcennamen und
+  Aktionen, aber das Interaktionsmuster ist generisch.
+
+Behalte Verhalten lokal, wenn es an ein Domänenmodell oder einen
+app-spezifischen Workflow gebunden ist.
+
+## Wiederverwendbare Kits {#reusable-kits}
+
+- **Settings kit** - Standard-Tabs für Account, Workspace, AI-Modelle,
+  LLM-Schlüssel, Connections, Secrets, Usage, Notifications, Changelog und
+  App-Präferenzen. Dauerhafte Konfiguration gehört in Settings; die
+  Agent-Sidebar behält Kontextkontrollen und Deep Links.
+- **Collaboration kit** - Echtzeitbearbeitung, Yjs-Dokumente, Presence,
+  Agent-Presence, Cursor, Remote-Auswahlen, Edit-Highlights und gemeinsames
+  Undo/Redo. Siehe [Real-Time Collaboration](/docs/real-time-collaboration).
+- **Sharing kit** - ein Modell für Datenschutz und Berechtigungen: private,
+  workspace, org, public link, Einladungen, Rollen, Ablaufzeiten und
+  agent-readable access. Siehe [Sharing & Privacy](/docs/sharing).
+- **Navigation and command kit** - App-Shell, Navigation, Breadcrumbs, App
+  Switcher, Command Palette, aktuelle Ressourcen, angeheftete Ressourcen und
+  Suche.
+- **Organization kit** - Ordner, Tags, Favoriten, Archiv, Papierkorb,
+  Eigentümer, Mitgliedschaft und gemeinsame Metadaten.
+- **Setup and connections kit** - API-Schlüssel, OAuth, Connections,
+  Modellbereitschaft, fehlende Secrets und deklaratives Onboarding. Siehe
+  [Workspace Connections](/docs/workspace-connections).
+- **Agent UX kit** - Sidebar, Composer, staged context, Mentions, Voice, Human
+  Approval, generative UI, Fortschritt und für den Agenten sichtbarer Zustand.
+- **History and recovery kit** - Audit Log, Activity Feed, Version History,
+  Checkpoints, Undo, Redo, Restore und Proof-of-Done. Siehe
+  [Audit Log](/docs/audit-log).
+- **Comments and review kit** - verankerte Kommentare, Pins, Mentions,
+  Review-Anfragen, gelöste Threads und Agent-Follow-ups.
+- **Workflow and observability kit** - Notifications, Approvals,
+  Background-Runs, recurring jobs, traces, evals, feedback und Run-Timelines.
+  Siehe [Observability](/docs/observability).
+
+## Implementierungsreihenfolge {#implementation-order}
+
+1. Dauerhafte Konfiguration in Standard-Settings-Tabs konsolidieren.
+2. Collaboration, Presence, Agent-Presence, Undo/Redo und Echtzeitbearbeitung
+   hinter gemeinsamen Adaptern normalisieren.
+3. Navigation, Commands, Recents, Favoriten, Ordner, Tags, Archiv und Papierkorb
+   in gemeinsame Primitive verschieben.
+4. Jede teilbare Ressource im selben Berechtigungs- und agent-readable
+   Access-Modell registrieren.
+5. Kollaborativen Ressourcen eine konsistente Story für Aktivität, Kommentare,
+   Review, Restore und Audit geben.
+6. Notifications, Approvals, Run-Status, Traces, Evals und Feedback vereinheitlichen.

package/corpus/core/docs/content/locales/de-DE/components.mdx

@@ -25,6 +25,15 @@ Vermeiden Sie den Import von UI-Komponenten aus dem bloßen `@agent-native/core`
 `@agent-native/core/client` oder ein fokussierter `@agent-native/core/client/*`-Unterpfad
 daher wählen Bundler den browsersicheren Eintrag.
 
+Verwenden Sie `@agent-native/toolkit` für wiederverwendbare App-Bausteine, die nicht Teil des grundlegenden Laufzeitvertrags sind: shadcn-artige UI-Primitives, gemeinsame Hooks, einfache App-Shell-Helfer und weitere Template-Kompositionsmodule. Core behält während der Umstellung Kompatibilitäts-Reexports, aber neuer Template- und App-Code sollte Toolkit-Module direkt importieren:
+
+```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-6bst90" title="Lassen Sie eine Ebene nach unten fallen, nicht aus dem Framework heraus" summary={"Jede Ebene behält die gleiche Laufzeit bei – Aktionen, Thread-Status und SQL-backed-Synchronisierung – und gibt Ihnen gleichzeitig mehr Kontrolle über Chrome."}>
 
 ```html

package/corpus/core/docs/content/locales/de-DE/creating-templates.mdx

@@ -7,6 +7,8 @@ description: "So erstellen und veröffentlichen Sie Ihre eigenen agentennativen
 
 Vorlagen sind vollständige, forkbare agentennative Apps, die einen echten Arbeitsablauf lösen. Die Erstanbieter-Vorlagen werden mit derselben Framework-Oberfläche erstellt, die Sie verwenden: React-Routen für UI, Drizzle SQL für Daten, actions für Vorgänge, Arbeitsbereichsressourcen für Agentenverhalten und Abfragesynchronisierung, damit der Agent und UI aufeinander abgestimmt bleiben.
 
+Verwenden Sie `@agent-native/core` für den Laufzeitvertrag: Actions, Server-Plugins, Datenbank-Helfer, App-State, Routing-Helfer und Agent-Chat. Verwenden Sie `@agent-native/toolkit` für wiederverwendbare App-Building-UI und Helfer wie gemeinsame Primitives, Toast- und Mobile-Hooks, Date-Picker und einfache App-Shell-Slots. Halten Sie template-spezifische Varianten lokal, wenn sie Produktverhalten oder visuelle Identität kodieren.
+
 Eine gute Vorlage:
 
 - Löst einen Workflow durchgängig, mit nützlichen Seed-Daten oder einem Leerzustandsfluss.

package/corpus/core/docs/content/locales/de-DE/sharing.mdx

@@ -93,9 +93,10 @@ Jede Vorlage, die vom Benutzer erstellte Arbeiten speichert, verwendet dieses Mo
 - **Folien** – Decks
 - **Design** – Designs und Assets
 - **Clips** – Bildschirmaufnahmen (Loom-Stil)
+- **Plan** — visual plans and PR recaps
 - **Formulare** – Formulardefinitionen
 - **Kalender** – Veranstaltungen und Buchungslinks
-- **Analytics** – Dashboards (Einführung – siehe `AGENTS.md` der Analytics-Vorlage)
+- **Analytics** – dashboards, saved analyses, and tokenized session replays
 - **Erweiterungen** – Sandbox-Mini-Apps (siehe [Extensions](/docs/extensions#sharing))
 
 Alle davon verwenden denselben `ownableColumns()`-Schema-Helfer, dieselbe `share-resource`-Aktion und denselben `<ShareButton>` UI. Wenn Sie von einer Vorlage zu einer anderen wechseln, sieht der Freigabedialog identisch aus.
@@ -136,15 +137,22 @@ Fügen Sie bei Listen neben jeder Zeile ein `<VisibilityBadge visibility={row.vi
 
 Das Framework mountet diese actions automatisch in jeder Vorlage – der Agent nennt sie als Tools und der UI ruft sie über `useActionQuery` / `useActionMutation` auf:
 
-| Aktion                    | Was es tut                                                                                                                                   |
-| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `share-resource`          | Gewähren Sie einem Benutzer oder einer Organisation Zugriff für eine bestimmte Rolle. Optionales `notify` steuert E-Mail-Benachrichtigungen. |
-| `unshare-resource`        | Zugriff für einen Benutzer oder eine Organisation widerrufen.                                                                                |
-| `list-resource-shares`    | Aktuelle Sichtbarkeit sowie alle expliziten Gewährungen anzeigen.                                                                            |
-| `set-resource-visibility` | Wechseln Sie zu `private`, `org` oder `public`.                                                                                              |
+| Aktion                       | Was es tut                                                                                                                                   |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `share-resource`             | Gewähren Sie einem Benutzer oder einer Organisation Zugriff für eine bestimmte Rolle. Optionales `notify` steuert E-Mail-Benachrichtigungen. |
+| `unshare-resource`           | Zugriff für einen Benutzer oder eine Organisation widerrufen.                                                                                |
+| `list-resource-shares`       | Aktuelle Sichtbarkeit sowie alle expliziten Gewährungen anzeigen.                                                                            |
+| `set-resource-visibility`    | Wechseln Sie zu `private`, `org` oder `public`.                                                                                              |
+| `create-agent-resource-link` | Mint a temporary read-only `agent_access` URL for a registered agent-readable resource.                                                      |
 
 Sagen Sie dem Agenten: „Teilen Sie dieses Design mit dem Marketingteam als Redakteuren“, und er ruft `share-resource` für denselben Endpunkt auf, den UI verwendet. Das Ergebnis wird beim nächsten Rendern im Freigabedialog angezeigt.
 
+## 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`.
+
 ## In eine neue Vorlage einbauen {#building}
 
 Wenn Sie eine Vorlage erstellen (siehe [Creating Templates](/docs/creating-templates)), ist die gemeinsame Nutzung der Verkabelung kurz. Zwei Ergänzungen zu Ihrem Schema:

package/corpus/core/docs/content/locales/de-DE/template-analytics.mdx

@@ -149,6 +149,12 @@ CLI gibt den lokalen Entwickler URL aus. Melden Sie sich bei Google an und öffn
 
 **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.
+
 ### Zusammenarbeit mit dem Agenten
 
 Der Agent weiß immer, was Sie sehen. Der aktuelle Bildschirmstatus wird als `<current-screen>`-Block in jede Nachricht eingefügt – er enthält die aktive Ansicht, das geöffnete Dashboard oder die geöffnete Analyse und alle ausgewählten Filter.

package/corpus/core/docs/content/locales/de-DE/template-clips.mdx

@@ -133,6 +133,13 @@ Agent.
 
 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.
+
 Die Endpunkte folgen denselben öffentlichen/Passwort-/Ablaufregeln wie die Freigabeseite.
 Passwortgeschützte Clips erfordern das einmalige Passwort; Erfolgreiche Antworten werden zurückgegeben
 kurzlebige tokenisierte Links, sodass nachgeschaltete Agenten den Klartext nicht benötigen

package/corpus/core/docs/content/locales/de-DE/tracking.mdx

@@ -241,6 +241,12 @@ Das Analytics-Template speichert Replay-Metadaten in SQL (`session_recordings`)
 
 Wenn Sie eine private Aufzeichnung an einen externen Agenten übergeben müssen, verwenden Sie auf der Sitzungsdetailseite die Funktion **Copy for agent**. Sie erzeugt einen zwei Stunden gültigen, aufzeichnungsgebundenen `agent_access`-Link, rendert eine kleine Discovery-Payload per SSR unter `/sessions/:recordingId` und stellt ausschließlich die JSON-APIs für Agent-Kontext/-Ereignisse bereit. Die Sichtbarkeit der Aufzeichnung ändert sich dadurch nicht.
 
+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.
+
 Nur für die lokale Entwicklung kann Analytics auf begrenzte SQL-Inline-Chunks zurückgreifen, wenn kein privater Blob-Speicher verfügbar ist. Produktions-Deployments sollten privaten oder verschlüsselten Blob-Speicher konfigurieren, anstatt sich für Replay-Payloads auf Postgres zu verlassen.
 
 ## Erweitert: benutzerdefinierte Anbieter und Interna {#advanced}