@agent-native/core 0.86.0 → 0.87.0

package/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/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/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/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/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/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/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/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/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/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/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}

package/docs/content/locales/es-ES/components.mdx

@@ -25,6 +25,15 @@ Evite importar componentes UI desde el paquete básico `@agent-native/core`. Usa
 `@agent-native/core/client` o una subruta `@agent-native/core/client/*` enfocada
 para que los paquetes elijan la entrada segura para el navegador.
 
+Use `@agent-native/toolkit` para piezas reutilizables de construcción de aplicaciones que no forman parte del contrato fundacional del runtime: primitivas UI estilo shadcn, hooks compartidos, ayudantes simples de shell de aplicación y otros módulos para componer plantillas. Core conserva reexports de compatibilidad durante la transición, pero el código nuevo de plantillas y aplicaciones debe importar módulos de toolkit directamente:
+
+```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-1v79shu" title="Bajar una capa, no fuera del marco." summary={"Cada capa mantiene el mismo tiempo de ejecución (acciones, estado del subproceso y sincronización SQL-backed) al tiempo que le brinda más control sobre Chrome."}>
 
 ```html

package/docs/content/locales/es-ES/creating-templates.mdx

@@ -7,6 +7,8 @@ description: "Cómo crear y publicar sus propias plantillas de aplicaciones nati
 
 Las plantillas son aplicaciones nativas del agente completas y bifurcables que resuelven un flujo de trabajo real. Las plantillas propias se crean con la misma superficie de marco que usted utiliza: rutas React para UI, Drizzle SQL para datos, actions para operaciones, recursos del espacio de trabajo para el comportamiento del agente y sincronización de sondeos para que el agente y UI permanezcan alineados.
 
+Use `@agent-native/core` para el contrato de runtime: actions, plugins de servidor, helpers de base de datos, estado de aplicación, helpers de rutas y chat del agente. Use `@agent-native/toolkit` para UI reutilizable y helpers de construcción de apps, como primitivas compartidas, hooks de toast/móvil, selectores de fecha y slots simples de shell de aplicación. Mantenga locales las variantes específicas de una plantilla cuando codifiquen comportamiento de producto o identidad visual.
+
 Una buena plantilla:
 
 - Resuelve un flujo de trabajo de principio a fin, con datos iniciales útiles o un flujo de estado vacío.

package/docs/content/locales/es-ES/template-analytics.mdx

@@ -149,6 +149,12 @@ El CLI imprime el desarrollador local URL. Inicia sesión con Google y luego abr
 
 **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.
+
 ### Trabajar con el agente
 
 El agente siempre sabe lo que estás mirando. El estado actual de la pantalla se inyecta en cada mensaje como un bloque `<current-screen>`: contiene la vista activa, el panel o análisis abierto y los filtros seleccionados.

package/docs/content/locales/es-ES/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.
+
 Los puntos finales siguen las mismas reglas de público/contraseña/caducidad que la página para compartir.
 Los clips protegidos con contraseña requieren la contraseña una vez; regresan respuestas exitosas
 Enlaces tokenizados de corta duración para que los agentes posteriores no necesiten el texto sin formato

package/docs/content/locales/es-ES/tracking.mdx

@@ -241,6 +241,12 @@ La plantilla de Analytics almacena los metadatos de repetición en SQL (`session
 
 Cuando necesite entregar una grabación privada a un agente externo, use el control **Copiar para el agente** de la página de detalle de la sesión. Este genera un enlace `agent_access` de dos horas con alcance limitado a la grabación, renderiza en el servidor (SSR) una pequeña carga útil de descubrimiento en `/sessions/:recordingId`, y expone únicamente las API JSON de contexto/eventos del agente. La visibilidad de la grabación no cambia.
 
+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.
+
 Solo para desarrollo local, Analytics puede recurrir a fragmentos en línea de SQL limitados cuando el almacenamiento de blob privado no está disponible. Las implementaciones de producción deberían configurar almacenamiento de blob privado o cifrado en lugar de depender de Postgres para las cargas útiles de repetición.
 
 ## Avanzado: proveedores personalizados e internos {#advanced}

package/docs/content/locales/fr-FR/components.mdx

@@ -25,6 +25,15 @@ import { ResourcesPanel } from "@agent-native/core/client/resources";
 `@agent-native/core/client` ou un sous-chemin `@agent-native/core/client/*` ciblé
 les bundlers choisissent donc l'entrée sécurisée pour le navigateur.
 
+Utilisez `@agent-native/toolkit` pour les éléments réutilisables de construction d'applications qui ne font pas partie du contrat fondamental du runtime : primitives UI de style shadcn, hooks partagés, aides simples de shell d'application et autres modules de composition de modèles. Core conserve des réexportations de compatibilité pendant la transition, mais le nouveau code de modèle et d'application doit importer directement les modules 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-n2zqzy" title={"Déposez un calque, pas hors du cadre"} summary={"Chaque couche conserve le même temps d'exécution (actions, état du thread et synchronisation SQL-backed) tout en vous donnant plus de contrôle sur le chrome."}>
 
 ```html

package/docs/content/locales/fr-FR/creating-templates.mdx

@@ -7,6 +7,8 @@ description: "Comment créer et publier vos propres modèles d'applications nati
 
 Les modèles sont des applications natives d'agent complètes et exploitables qui résolvent un véritable flux de travail. Les modèles propriétaires sont créés avec la même surface de structure que vous utilisez : routes React pour le UI, Drizzle SQL pour les données, actions pour les opérations, ressources d'espace de travail pour le comportement de l'agent et synchronisation des interrogations afin que l'agent et le UI restent alignés.
 
+Utilisez `@agent-native/core` pour le contrat de runtime : actions, plugins serveur, aides de base de données, état de l'application, aides de routage et chat de l'agent. Utilisez `@agent-native/toolkit` pour l'UI réutilisable de construction d'applications et les aides comme les primitives partagées, les hooks toast/mobile, les sélecteurs de date et les slots simples de shell d'application. Gardez les variantes propres au modèle locales lorsqu'elles encodent un comportement produit ou une identité visuelle.
+
 Un bon modèle :
 
 - Résout un flux de travail de bout en bout, avec des données de départ utiles ou un flux à état vide.

package/docs/content/locales/fr-FR/template-analytics.mdx

@@ -149,6 +149,12 @@ Le CLI imprime le développement local URL. Connectez-vous avec Google, puis ouv
 
 **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.
+
 ### Travailler avec l'agent
 
 L'agent sait toujours ce que vous regardez. L'état actuel de l'écran est injecté dans chaque message sous forme de bloc `<current-screen>` : il contient la vue active, le tableau de bord ou l'analyse ouvert et tous les filtres sélectionnés.

package/docs/content/locales/fr-FR/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.
+
 Les points de terminaison suivent les mêmes règles de public/mot de passe/expiration que la page de partage.
 Les clips protégés par mot de passe nécessitent le mot de passe une seule fois ; les réponses positives reviennent
 Liens tokenisés de courte durée afin que les agents en aval n'aient pas besoin du texte brut

package/docs/content/locales/fr-FR/tracking.mdx

@@ -241,6 +241,12 @@ Le modèle Analytics stocke les métadonnées de relecture en SQL (`session_reco
 
 Lorsque vous devez transmettre un enregistrement privé à un agent externe, utilisez le contrôle **Copy for agent** de la page de détail de session. Il génère un lien `agent_access` limité à l'enregistrement, valide deux heures, effectue le rendu SSR d'une petite charge utile de découverte sur `/sessions/:recordingId`, et n'expose que les API JSON de contexte/événements de l'agent. La visibilité de l'enregistrement ne change pas.
 
+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.
+
 Pour le développement local uniquement, Analytics peut se replier sur des blocs SQL en ligne plafonnés lorsque le stockage blob privé n'est pas disponible. Les déploiements en production doivent configurer un stockage blob privé ou chiffré plutôt que de s'appuyer sur Postgres pour les charges utiles de relecture.
 
 ## Avancé : fournisseurs personnalisés et éléments internes {#advanced}

package/docs/content/locales/hi-IN/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, और अन्य template composition modules. संक्रमण के दौरान Core compatibility re-exports रखता है, लेकिन नए template और app code को toolkit modules सीधे 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-109zkj3" title={"एक परत नीचे गिराएं, ढांचे से बाहर नहीं"} summary={"प्रत्येक परत आपको क्रोम पर अधिक नियंत्रण प्रदान करते हुए समान रनटाइम - क्रियाएं, थ्रेड स्थिति और SQL-backed सिंक रखती है।"}>
 
 ```html

package/docs/content/locales/hi-IN/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` का उपयोग reusable app-building UI और helpers के लिए करें, जैसे shared primitives, toast/mobile hooks, date pickers, और simple app shell slots. जब variants product behavior या visual identity encode करते हैं, तो उन्हें template-local रखें.
+
 एक अच्छा टेम्पलेट:
 
 - उपयोगी बीज डेटा या खाली-अवस्था प्रवाह के साथ एक वर्कफ़्लो को शुरू से अंत तक हल करता है।

package/docs/content/locales/hi-IN/template-analytics.mdx

@@ -149,6 +149,12 @@ CLI स्थानीय डेव URL प्रिंट करता है
 
 **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/hi-IN/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/hi-IN/tracking.mdx

@@ -241,6 +241,12 @@ Analytics टेम्पलेट replay मेटाडेटा को SQL (`
 
 जब आपको किसी बाहरी एजेंट को एक प्राइवेट रिकॉर्डिंग सौंपने की आवश्यकता हो, तो session डिटेल पेज के **Copy for agent** नियंत्रण का उपयोग करें। यह एक दो-घंटे का, रिकॉर्डिंग-स्कोप्ड `agent_access` लिंक बनाता है, `/sessions/:recordingId` पर एक छोटा डिस्कवरी पेलोड SSR करता है, और केवल एजेंट context/events JSON APIs को एक्सपोज़ करता है। रिकॉर्डिंग की visibility नहीं बदलती।
 
+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 storage उपलब्ध न होने पर capped SQL inline chunks पर फ़ॉलबैक कर सकता है। प्रोडक्शन डिप्लॉयमेंट्स को replay payloads के लिए Postgres पर निर्भर रहने के बजाय प्राइवेट या एन्क्रिप्टेड blob storage कॉन्फ़िगर करना चाहिए।
 
 ## उन्नत: कस्टम प्रदाता और आंतरिक {#advanced}

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/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/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/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/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/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