@agent-native/core 0.88.0 → 0.90.2

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

@@ -1,79 +1,103 @@
 ---
-title: "Boîte à outils Agent-Native"
-description: "Kits réutilisables pour collaboration, réglages, partage, navigation, présence, historique, configuration et UX agent."
+title: "Toolkit"
+description: "Reusable app-building primitives that sit between @agent-native/core and template apps."
 ---
 
-# 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.
+# Toolkit
+
+`@agent-native/core` owns the foundational runtime: actions, app state, auth,
+SQL, server plugins, agent chat, sharing access checks, and collaboration
+transport. `@agent-native/toolkit` owns reusable app-building pieces that sit on
+top of that runtime: UI primitives, app-local adapters, shell helpers, sharing
+badges, and collaboration UI.
+
+Apps should compose those pieces through local adapters. That keeps app UI easy
+to customize without copying Toolkit implementation code.
+
+<WireframeBlock id="doc-block-toolkit-layering">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:520px;box-sizing:border-box;padding:48px 36px;display:flex;align-items:center;justify-content:center'><div style='width:min(900px,100%);display:grid;grid-template-columns:1fr;gap:18px'><div class='wf-card' style='padding:22px 24px'><div style='display:flex;align-items:center;justify-content:space-between;gap:16px'><div><strong>App</strong><p class='wf-muted' style='margin:6px 0 0'>Domain routes, actions, local UI adapters, product-specific views</p></div><span class='wf-pill'>@/components/ui/button</span></div></div><div class='wf-card' style='padding:22px 24px;border-color:hsl(var(--primary))'><div style='display:flex;align-items:center;justify-content:space-between;gap:16px'><div><strong>Toolkit</strong><p class='wf-muted' style='margin:6px 0 0'>Reusable primitives, collab UI, sharing UI, app shell hooks</p></div><span class='wf-pill'>ToolkitProvider</span></div><div style='display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:10px;margin-top:16px'><span class='wf-pill'>UI</span><span class='wf-pill'>Collab UI</span><span class='wf-pill'>Sharing UI</span><span class='wf-pill'>Shell</span></div></div><div class='wf-card' style='padding:22px 24px'><div style='display:flex;align-items:center;justify-content:space-between;gap:16px'><div><strong>Core</strong><p class='wf-muted' style='margin:6px 0 0'>Actions, SQL, auth, sharing runtime, Yjs transport, app state</p></div><span class='wf-pill'>@agent-native/core</span></div></div></div></div>"
+    }
+  />
+</WireframeBlock>
+
+## What Ships Today {#what-ships-today}
+
+- **UI primitives**: shadcn-style components under
+  `@agent-native/toolkit/ui/*`.
+- **App adapters**: template-local wrappers such as
+  `@/components/ui/button` that re-export Toolkit primitives until an app wants
+  to customize them.
+- **ToolkitProvider**: an override layer that lets reusable Toolkit UI use an
+  app's local primitives, starting with `Button`.
+- **Collaboration UI**: presence avatars, live cursors, remote selection rings,
+  recent edit highlights, and agent presence chips under
+  `@agent-native/toolkit/collab-ui`.
+- **Sharing UI**: the reusable `VisibilityBadge` under
+  `@agent-native/toolkit/sharing`.
+- **Shell and hooks**: app-shell header actions plus shared hooks such as
+  `useIsMobile` and `useToast`.
+
+## Compatibility {#compatibility}
+
+Existing imports from `@agent-native/core/client` keep working. Core now exposes
+thin re-export shims for Toolkit-owned visual pieces while keeping runtime
+behavior in core.
+
+Those core shims are temporary migration support, not the long-term dependency
+direction. The next major can remove them; after that, reusable app-building
+packages should import Toolkit directly, and behaviorful Toolkit kits may compose
+core runtime APIs as peer/runtime dependencies instead of pushing more UI back
+into core.
+
+Extract future behaviorful kits one at a time before broadening the split.
+Sharing is the first candidate to validate that model because it exercises
+access checks, action-backed data, and share-link UI together.
+
+That means this keeps working:
+
+```tsx
+import { PresenceBar, VisibilityBadge } from "@agent-native/core/client";
+```
+
+New reusable app code should prefer Toolkit or app-local adapters:
+
+```tsx
+import { PresenceBar } from "@agent-native/toolkit/collab-ui";
+import { Button } from "@/components/ui/button";
+```
+
+## Boundary {#boundary}
+
+Move code into Toolkit when it is reusable app-building UI or a pure UI contract.
+Keep code in core when it owns access control, SQL, actions, request context,
+Yjs transport, auth, or other runtime guarantees.
+
+Good Toolkit candidates:
+
+- Components that render the same interaction across apps.
+- Display-only helpers and structural prop types.
+- Base components that receive data and callbacks from an app or core wrapper.
+- App-shell hooks and adapters that do not own domain data.
+
+Keep app-local:
+
+- Domain-specific workflows.
+- Resource-specific mutations and routes.
+- Custom visual systems an app intentionally owns.
+
+Keep core-owned:
+
+- Sharing actions and access checks.
+- Collaboration storage, awareness transport, and Yjs document sync.
+- Auth, sessions, app state, SQL, and server plugins.
+
+## Pages {#pages}
+
+- [UI Primitives](/docs/toolkit-ui)
+- [App Adapters](/docs/toolkit-app-adapters)
+- [Collaboration UI](/docs/toolkit-collaboration-ui)
+- [Sharing UI](/docs/toolkit-sharing-ui)
+- [Shell & Hooks](/docs/toolkit-shell-hooks)

package/corpus/core/docs/content/locales/fr-FR/cloneable-saas.mdx

@@ -1,19 +1,19 @@
 ---
-title: "Modèles"
+title: "Apps"
 description: "Créez un produit SaaS fonctionnel et personnalisez-le – agent inclus."
 ---
 
-# Modèles
+# Apps
 
-Vous souhaitez proposer votre propre outil d'analyse basé sur l'IA ? Client de messagerie ? Générateur de formulaires ? Choisissez un modèle et vous obtenez un SaaS fonctionnel en quelques minutes : agent, base de données, authentification et pipeline de déploiement déjà connectés.
+Vous souhaitez proposer votre propre outil d'analyse basé sur l'IA ? Client de messagerie ? Générateur de formulaires ? Choisissez une app d'exemple et vous obtenez un SaaS fonctionnel en quelques minutes : agent, base de données, authentification et pipeline de déploiement déjà connectés.
 
-La plupart des « modèles » vous donnent un échafaudage vierge et une longue liste TODO. L'agent natif inverse cela. Chacun est un **produit complet de qualité SaaS** — déjà exécutable dès le premier jour, déjà livrable et entièrement à vous pour personnaliser, personnaliser et déployer. Considérez-les comme des SaaS clonables, et non comme des kits de démarrage : vous créez un produit fini, et non un passe-partout.
+La plupart des modèles de démarrage vous donnent un échafaudage vierge et une longue liste TODO. L'agent natif inverse cela. Chaque app d'exemple est un **produit complet de qualité SaaS** — déjà exécutable dès le premier jour, déjà livrable et entièrement à vous pour personnaliser, marquer et déployer. Considérez-les comme des SaaS clonables, et non comme des kits de démarrage : vous créez un produit fini, et non un passe-partout.
 
-## Modèles disponibles {#catalog}
+## Apps d'exemple {#catalog}
 
 Chacune est une véritable application que vous pouvez utiliser aujourd'hui, et une rampe de lancement pour votre propre version.
 
-| Modèle                                    | Qu'est-ce que c'est                                                                                                                                            |
+| App                                       | Qu'est-ce que c'est                                                                                                                                            |
 | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [**Chat**](/docs/template-chat)           | Application minimale axée sur le chat avec des threads durables, actions, l'authentification et un chemin propre vers UI personnalisé ou votre propre backend. |
 | [**Mail**](/docs/template-mail)           | Un surhumain natif d'agent. Boîte de réception, étiquettes, tri IA, clavier d'abord, brouillons et envois via l'agent.                                         |
@@ -35,16 +35,16 @@ Consultez le catalogue complet sous [Apps](/apps) ou passez directement à l'un
 
 ## Ce que vous obtenez hors de la boîte {#what-you-get}
 
-Chaque modèle est livré avec les éléments dont la création prend normalement des mois :
+Chaque app d'exemple est livrée avec les éléments dont la création prend normalement des mois :
 
 - **Un agent fonctionnel** — déjà connecté à l'application, déjà capable d'utiliser actions sur vos données, déjà conscient du contexte de ce que vous regardez. Voir [Messaging the agent](/docs/messaging) pour savoir comment cela fonctionne.
 - **Auth** : connexion, sessions, organisations, isolation multi-locataires. Déjà fait.
-- **Une base de données** : chaque modèle a son schéma, ses requêtes et ses migrations prêts à l'emploi. Apportez votre propre base de données SQL (Postgres, SQLite, Turso, D1) — le framework s'adapte.
+- **Une base de données** : chaque app d'exemple a son schéma, ses requêtes et ses migrations prêts à l'emploi. Apportez votre propre base de données SQL (Postgres, SQLite, Turso, D1) — le framework s'adapte.
 - **Un UI** en temps réel : l'écran reste synchronisé avec ce que fait l'agent. Cliquez sur « rédiger un e-mail » dans le chat et regardez le brouillon apparaître immédiatement dans votre boîte de réception.
 - **Prêt pour le déploiement** : envoyez-le vers Netlify, Vercel, Cloudflare, AWS ou n'importe quel autre endroit exécutant Node. Pas de dépendance envers un fournisseur.
 - **Crochets de branding** : le nom, les couleurs, le logo et la copie sont tous faciles à modifier.
 
-Ce n'est pas une affirmation théorique. L'auteur du framework exécute sa boîte de réception réelle sur le modèle Mail, son calendrier réel sur le modèle Calendrier et ses analyses réelles sur le modèle Analytics. Les modèles sont des logiciels pilotes quotidiens.
+Ce n'est pas une affirmation théorique. L'auteur du framework exécute sa boîte de réception réelle dans l'app Mail, son calendrier réel dans l'app Calendar et ses analyses réelles dans l'app Analytics. Ces apps sont des logiciels du quotidien.
 
 ## Ce que vous faites {#what-you-do}
 
@@ -56,7 +56,7 @@ Le chemin de « Je veux mon propre SaaS » à « J'ai mon propre SaaS » est cou
 <div class="diagram-fork">
   <div class="diagram-card">
     <span class="diagram-pill">1</span><strong>Pick</strong
-    ><small class="diagram-muted">a complete template</small>
+    ><small class="diagram-muted">une app complète</small>
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
   <div class="diagram-card">
@@ -98,8 +98,8 @@ Le chemin de « Je veux mon propre SaaS » à « J'ai mon propre SaaS » est cou
 
 </Diagram>
 
-1. **Choisissez un modèle.** Utilisez le sélecteur CLI ou parcourez la documentation et choisissez-en un pour commencer.
-2. **Marquez-le.** Modifiez le nom, les couleurs, le logo et la copie. La plupart des modèles exposent cela dans un seul fichier de configuration.
+1. **Choisissez une app d'exemple.** Utilisez le sélecteur CLI ou parcourez la documentation et choisissez-en une pour commencer.
+2. **Marquez-la.** Modifiez le nom, les couleurs, le logo et la copie. La plupart des apps d'exemple exposent cela dans un seul fichier de configuration.
 3. **Personnalisez-le.** Demandez à l'agent d'ajouter la colonne dont vous avez besoin, modifiez la façon dont les groupes de boîtes de réception, connectez-vous à votre API interne, ajoutez une nouvelle vue. L'agent édite le code ; vous examinez la différence.
 4. **Expédiez-le.** Exécutez la commande de déploiement. Vous disposez désormais de votre propre SaaS de production sur votre propre domaine.
 
@@ -159,7 +159,7 @@ Le résultat : une flexibilité au niveau du code Claude pour chaque utilisateu
 
 ## Vous ne voulez pas bifurquer ? {#hosted}
 
-Vous n'êtes pas obligé. Chaque modèle est également disponible sous forme d'application hébergée sur `agent-native.com` — `mail.agent-native.com`, `calendar.agent-native.com`, etc. Utilisez la version hébergée gratuitement ou payante ; fork uniquement lorsque vous souhaitez modifier quelque chose que la version hébergée n'expose pas.
+Vous n'êtes pas obligé. Chaque app d'exemple est également disponible sous forme d'application hébergée sur `agent-native.com` — `mail.agent-native.com`, `calendar.agent-native.com`, etc. Utilisez la version hébergée gratuitement ou payante ; fork uniquement lorsque vous souhaitez modifier quelque chose que la version hébergée n'expose pas.
 
 ## Essayez-le avec une compétence {#try-with-a-skill}
 
@@ -168,10 +168,10 @@ Pas prêt à monter un échafaudage ? Vous pouvez ajouter des super pouvoirs na
 ## Construire sur cette base
 
 - [**Getting Started**](/docs/getting-started) : créez une application de chat minimale ou un agent sans tête
-- [**Messaging the agent**](/docs/messaging) : comment les utilisateurs (et vous) parlent à l'agent fourni avec chaque modèle
-- [**Multi-App Workspace**](/docs/multi-app-workspace) : regroupez plusieurs modèles dans un seul espace de travail qui partage l'authentification, la marque et l'agent
-- [**Dispatch**](/docs/template-dispatch) — le modèle de plan de contrôle de l'espace de travail
-- [**Creating Templates**](/docs/creating-templates) – créez et publiez votre propre modèle
+- [**Messaging the agent**](/docs/messaging) : comment les utilisateurs (et vous) parlent à l'agent fourni avec chaque app
+- [**Multi-App Workspace**](/docs/multi-app-workspace) : regroupez plusieurs apps dans un seul espace de travail qui partage l'authentification, la marque et l'agent
+- [**Dispatch**](/docs/template-dispatch) — l'app de plan de contrôle de l'espace de travail
+- [**Creating Templates**](/docs/creating-templates) – créez et publiez votre propre modèle d'app
 
 ### Pour les développeurs {#dev-details}
 
@@ -181,10 +181,10 @@ Si vous créez un échafaudage maintenant, la commande CLI est :
 npx @agent-native/core@latest create my-platform
 ```
 
-Vous obtiendrez un sélecteur à sélection multiple. Choisissez une application (autonome) ou plusieurs (espace de travail : les applications partagent l'authentification, la marque, la configuration de l'agent et la base de données). Chaque modèle sélectionné est intégré dans `apps/<name>/` avec chaque fichier dont vous avez besoin. Pour une automation sans UI navigateur au lieu d'un modèle UI, utilisez `npx @agent-native/core@latest create my-agent --headless`.
+Vous obtiendrez un sélecteur à sélection multiple. Choisissez une application (autonome) ou plusieurs (espace de travail : les applications partagent l'authentification, la marque, la configuration de l'agent et la base de données). Chaque app sélectionnée est intégrée dans `apps/<name>/` avec chaque fichier dont vous avez besoin. Pour une automation sans UI navigateur au lieu d'une UI d'app, utilisez `npx @agent-native/core@latest create my-agent --headless`.
 
 Remplissez `.env` (principalement `ANTHROPIC_API_KEY` et `DATABASE_URL`), `pnpm install`, `pnpm dev`, et cela fonctionne. Pas de "TODO : implémenter la connexion", pas de routes d'espace réservé.
 
 Cibles de déploiement : tout hôte compatible Nitro (Node, Cloudflare, Netlify, Vercel, Deno, Lambda, Bun) et toute base de données SQL compatible Drizzle (SQLite, Postgres, Turso, D1, Supabase, Neon). Pour les espaces de travail, `npx @agent-native/core@latest deploy` crée chaque application en même temps et les livre derrière une seule origine. Voir [Deployment](/docs/deployment).
 
-Pour créer et publier votre propre modèle, consultez [Creating Templates](/docs/creating-templates).
+Pour créer et publier votre propre modèle d'app, consultez [Creating Templates](/docs/creating-templates).

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

@@ -25,7 +25,9 @@ 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 :
+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.
+
+Les packages réutilisables peuvent importer directement les modules Toolkit :
 
 ```tsx
 import { Button } from "@agent-native/toolkit/ui/button";
@@ -34,6 +36,13 @@ import { useToast } from "@agent-native/toolkit/hooks/use-toast";
 import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
 ```
 
+Dans les apps de template, privilégiez des adaptateurs locaux à l'app afin que les équipes puissent remplacer les primitives une seule fois et que chaque surface Toolkit réutilisée adopte l'implémentation locale :
+
+```tsx
+import { Button } from "@/components/ui/button";
+import { useToast } from "@/hooks/use-toast";
+```
+
 <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
@@ -443,7 +452,8 @@ function WorkspaceResources() {
 
 | Zone          | APIs                                                            | Chemin d'importation                      |
 | ------------- | --------------------------------------------------------------- | ----------------------------------------- |
-| Partage       | `<ShareButton>`, `<ShareDialog>`, `<VisibilityBadge>`           | `@agent-native/core/client/sharing`       |
+| Partage       | `<ShareButton>`, `<ShareDialog>`                                | `@agent-native/core/client/sharing`       |
+| Sharing UI    | `<VisibilityBadge>`                                             | `@agent-native/toolkit/sharing`           |
 | Notifications | `<NotificationsBell>`                                           | `@agent-native/core/client/notifications` |
 | Progrès       | `<RunsTray>`, crochets de progression et types                  | `@agent-native/core/client/progress`      |
 | Intégration   | `useOnboarding()`, crochets de panneau d'intégration            | `@agent-native/core/client/onboarding`    |