@agent-native/core 0.87.0 → 0.88.0

package/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/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/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/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/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/docs/content/locales/es-ES/agent-native-toolkit.mdx

@@ -0,0 +1,77 @@
+---
+title: "Toolkit de Agent-Native"
+description: "Kits reutilizables para colaboración, ajustes, compartir, navegación, presencia, historial, configuración y UX del agente."
+---
+
+# Toolkit de Agent-Native
+
+Las apps de Agent-Native no deberían reconstruir la fontanería del workspace.
+Las apps son dueñas de sus modelos, acciones y vistas de producto. El framework
+y `@agent-native/toolkit` son dueños de las piezas reutilizables que todas las
+apps deberían heredar: colaboración, compartir, ajustes, navegación,
+organización, configuración, UX del agente, historial y visibilidad operativa.
+
+El objetivo es que los usuarios aprendan una sola forma de compartir, conectar
+claves, ver al agente editar junto a ellos, encontrar ajustes y entender qué
+cambió.
+
+## Contrato del toolkit {#toolkit-contract}
+
+Mueve comportamiento al toolkit cuando sea:
+
+- **De workspace** - los usuarios esperan que funcione igual en todas las apps.
+- **Visible para el agente** - el agente necesita la misma capacidad mediante
+  acciones, instrucciones o estado de aplicación.
+- **Gobernado** - aplican permisos, auditoría, secretos, política de org,
+  facturación o reglas de compartir.
+- **Repetido** - dos apps ya construyeron UI o lógica parecida.
+- **No específico del dominio** - la app aporta nombres y acciones de recursos,
+  pero el patrón de interacción es genérico.
+
+Mantén lo local cuando dependa de un modelo de dominio o de un flujo propio de
+la app.
+
+## Kits reutilizables {#reusable-kits}
+
+- **Settings kit** - pestañas estándar para cuenta, workspace, modelos de AI,
+  claves LLM, conexiones, secretos, uso, notificaciones, changelog y preferencias
+  de app. La configuración durable vive en Settings; la barra lateral del agente
+  conserva controles contextuales y enlaces profundos.
+- **Collaboration kit** - edición en tiempo real, documentos Yjs, presencia,
+  presencia del agente, cursores, selecciones remotas, resaltado de ediciones y
+  undo/redo compartido. Ver
+  [Real-Time Collaboration](/docs/real-time-collaboration).
+- **Sharing kit** - un solo modelo de privacidad y permisos para privado,
+  workspace, org, enlace público, invitaciones, roles, expiraciones y acceso
+  legible por agentes. Ver [Sharing & Privacy](/docs/sharing).
+- **Navigation and command kit** - app shell, navegación, breadcrumbs, app
+  switcher, command palette, recursos recientes, recursos fijados y búsqueda.
+- **Organization kit** - carpetas, tags, favoritos, archivo, papelera,
+  propietarios, membresía y metadata común.
+- **Setup and connections kit** - claves API, OAuth, conexiones, estado de
+  modelos, secretos faltantes y onboarding declarativo. Ver
+  [Workspace Connections](/docs/workspace-connections).
+- **Agent UX kit** - sidebar, composer, contexto preparado, menciones, voz,
+  aprobación humana, UI generativa, progreso y estado visible para el agente.
+- **History and recovery kit** - audit log, activity feed, version history,
+  checkpoints, undo, redo, restore y proof-of-done. Ver
+  [Audit Log](/docs/audit-log).
+- **Comments and review kit** - comentarios anclados, pines, menciones,
+  solicitudes de revisión, threads resueltos y tareas de seguimiento del agente.
+- **Workflow and observability kit** - notificaciones, aprobaciones, runs en
+  background, jobs recurrentes, traces, evals, feedback y líneas de tiempo. Ver
+  [Observability](/docs/observability).
+
+## Orden de implementación {#implementation-order}
+
+1. Consolidar la configuración durable en pestañas estándar de Settings.
+2. Normalizar colaboración, presence, agent presence, undo/redo y edición en
+   tiempo real detrás de adapters compartidos.
+3. Mover navegación, comandos, recientes, favoritos, carpetas, tags, archivo y
+   papelera a primitivas compartidas.
+4. Registrar todos los recursos compartibles en el mismo modelo de permisos y
+   acceso legible por agentes.
+5. Dar a cada recurso colaborativo una historia consistente de actividad,
+   comentarios, revisión, restore y auditoría.
+6. Unificar notificaciones, aprobaciones, estado de runs, traces, evals y
+   feedback.

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

@@ -93,9 +93,10 @@ Cada plantilla que almacena trabajos escritos por usuarios utiliza este modelo.
 - **Diapositivas**: presentaciones
 - **Diseño**: diseños y recursos
 - **Clips**: grabaciones de pantalla (estilo Loom)
+- **Plan** — visual plans and PR recaps
 - **Formularios**: definiciones de formulario
 - **Calendario**: enlaces a eventos y reservas
-- **Analytics**: paneles (en implementación; consulte el `AGENTS.md` de la plantilla de análisis)
+- **Analytics**: dashboards, saved analyses, and tokenized session replays
 - **Extensiones**: miniaplicaciones en espacio aislado (consulte [Extensions](/docs/extensions#sharing))
 
 Cada uno de estos utiliza el mismo asistente de esquema `ownableColumns()`, la misma acción `share-resource` y el mismo `<ShareButton>` UI. Pase de una plantilla a otra y el cuadro de diálogo para compartir se verá idéntico.
@@ -136,15 +137,22 @@ Para las listas, coloque un `<VisibilityBadge visibility={row.visibility} />` al
 
 El marco monta automáticamente estos actions en cada plantilla: el agente los llama como herramientas y el UI los llama a través de `useActionQuery`/`useActionMutation`:
 
-| Acción                    | Qué hace                                                                                                                                       |
-| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `share-resource`          | Otorgar acceso a un usuario u organización en una función específica. El `notify` opcional controla las notificaciones por correo electrónico. |
-| `unshare-resource`        | Revocar el acceso a un usuario u organización.                                                                                                 |
-| `list-resource-shares`    | Mostrar visibilidad actual más todas las subvenciones explícitas.                                                                              |
-| `set-resource-visibility` | Cambiar a `private`, `org` o `public`.                                                                                                         |
+| Acción                       | Qué hace                                                                                                                                       |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `share-resource`             | Otorgar acceso a un usuario u organización en una función específica. El `notify` opcional controla las notificaciones por correo electrónico. |
+| `unshare-resource`           | Revocar el acceso a un usuario u organización.                                                                                                 |
+| `list-resource-shares`       | Mostrar visibilidad actual más todas las subvenciones explícitas.                                                                              |
+| `set-resource-visibility`    | Cambiar a `private`, `org` o `public`.                                                                                                         |
+| `create-agent-resource-link` | Mint a temporary read-only `agent_access` URL for a registered agent-readable resource.                                                        |
 
 Dígale al agente "comparta este diseño con el equipo de marketing como editores" y llamará a `share-resource` contra el mismo punto final que utiliza UI. El resultado aparece en el cuadro de diálogo para compartir en el siguiente renderizado.
 
+## 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`.
+
 ## Construyéndolo en una nueva plantilla {#building}
 
 Si está creando una plantilla (consulte [Creating Templates](/docs/creating-templates)), el cableado compartido es corto. Dos adiciones a su esquema:

package/docs/content/locales/fr-FR/agent-native-toolkit.mdx

@@ -0,0 +1,79 @@
+---
+title: "Boîte à outils Agent-Native"
+description: "Kits réutilisables pour collaboration, réglages, partage, navigation, présence, historique, configuration et UX agent."
+---
+
+# Boîte à outils Agent-Native
+
+Les apps Agent-Native ne devraient pas reconstruire toute la plomberie du
+workspace. Les apps possèdent leurs modèles métier, leurs actions métier et
+leurs vues produit. Le framework et `@agent-native/toolkit` possèdent les
+surfaces réutilisables que chaque app devrait hériter : collaboration, partage,
+réglages, navigation, organisation, configuration, UX agent, historique et
+visibilité opérationnelle.
+
+L'objectif est que les utilisateurs apprennent une seule manière de partager,
+connecter des clés, voir l'agent modifier avec eux, trouver les réglages et
+comprendre ce qui a changé.
+
+## Contrat du toolkit {#toolkit-contract}
+
+Déplacez un comportement dans le toolkit quand il est :
+
+- **À l'échelle du workspace** - les utilisateurs s'attendent au même
+  fonctionnement dans toutes les apps.
+- **Visible par l'agent** - l'agent a besoin de la même capacité via actions,
+  instructions ou état applicatif.
+- **Gouverné** - permissions, audit, secrets, politique d'organisation,
+  facturation ou règles de partage s'appliquent.
+- **Répété** - deux apps ont déjà construit une UI ou une logique similaire.
+- **Non spécifique au domaine** - l'app fournit les noms et actions de
+  ressources, mais le modèle d'interaction est générique.
+
+Gardez le comportement local quand il dépend vraiment du domaine ou d'un flux
+spécifique à l'app.
+
+## Kits réutilisables {#reusable-kits}
+
+- **Settings kit** - onglets standard pour compte, workspace, modèles AI, clés
+  LLM, connexions, secrets, usage, notifications, changelog et préférences
+  d'app. La configuration durable vit dans Settings ; la sidebar agent garde des
+  contrôles contextuels et des liens profonds.
+- **Collaboration kit** - édition temps réel, documents Yjs, présence, présence
+  de l'agent, curseurs, sélections distantes, surlignage des éditions et
+  undo/redo partagé. Voir
+  [Real-Time Collaboration](/docs/real-time-collaboration).
+- **Sharing kit** - un seul modèle de confidentialité et permissions pour privé,
+  workspace, org, lien public, invitations, rôles, expirations et accès lisible
+  par l'agent. Voir [Sharing & Privacy](/docs/sharing).
+- **Navigation and command kit** - app shell, navigation, breadcrumbs, app
+  switcher, command palette, ressources récentes, ressources épinglées et
+  recherche.
+- **Organization kit** - dossiers, tags, favoris, archive, corbeille,
+  propriétaires, membres et metadata commune.
+- **Setup and connections kit** - clés API, OAuth, connexions, disponibilité des
+  modèles, secrets manquants et onboarding déclaratif. Voir
+  [Workspace Connections](/docs/workspace-connections).
+- **Agent UX kit** - sidebar, composer, contexte préparé, mentions, voix,
+  validation humaine, UI générative, progression et état visible par l'agent.
+- **History and recovery kit** - audit log, activity feed, version history,
+  checkpoints, undo, redo, restore et proof-of-done. Voir
+  [Audit Log](/docs/audit-log).
+- **Comments and review kit** - commentaires ancrés, pins, mentions, demandes de
+  review, threads résolus et tâches de suivi agent.
+- **Workflow and observability kit** - notifications, validations, runs en
+  arrière-plan, jobs récurrents, traces, evals, feedback et timelines. Voir
+  [Observability](/docs/observability).
+
+## Ordre d'implémentation {#implementation-order}
+
+1. Consolider la configuration durable dans des onglets Settings standard.
+2. Normaliser collaboration, presence, agent presence, undo/redo et édition
+   temps réel derrière des adapters partagés.
+3. Déplacer navigation, commandes, récents, favoris, dossiers, tags, archive et
+   corbeille vers des primitives partagées.
+4. Enregistrer chaque ressource partageable dans le même modèle de permissions
+   et d'accès lisible par l'agent.
+5. Donner à chaque ressource collaborative une histoire cohérente d'activité,
+   commentaires, review, restore et audit.
+6. Unifier notifications, validations, état des runs, traces, evals et feedback.