@agent-native/core 0.87.0 → 0.90.1

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

@@ -0,0 +1,103 @@
+---
+title: "Toolkit"
+description: "Reusable app-building primitives that sit between @agent-native/core and template apps."
+---
+
+# 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/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/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`    |

package/docs/content/locales/fr-FR/data-programs.mdx

@@ -0,0 +1,329 @@
+---
+title: "Programmes de données"
+description: "Scripts JS stockés et rédigés par l'agent qui récupèrent, joignent et agrègent des données côté serveur, mis en cache dans SQL et rendus par des panneaux de dashboard — le juste milieu entre une requête run-code ponctuelle et une action de fournisseur codée en dur."
+search: "data program emit rows schema providerFetch dashboard panel program source refresh TTL viewer-scoped cache save-data-program run-data-program"
+---
+
+# Programmes de données
+
+Un **programme de données** est un script JS nommé, stocké et rédigé par l'agent qui récupère, joint, filtre ou agrège des données — des API de fournisseurs via `providerFetch` / `providerFetchAll` / `providerSearchAll`, des données d'app via `appAction`, ou des fichiers de workspace adossés à Resources — et appelle `emit(rows, schema)` exactement une fois avec le résultat. Le résultat est mis en cache dans SQL et n'importe quel composant graphique/tableau peut le rendre, actualisé selon une politique que vous choisissez au lieu de chaque vue de page.
+
+Il est disponible automatiquement partout où [`run-code`](/docs/actions) est disponible — il n'y a rien à monter ni à configurer par app. Si votre app a déjà run-code activé, `save-data-program`, `preview-data-program`, `run-data-program`, `list-data-programs`, `get-data-program` et `delete-data-program` sont déjà des actions enregistrées.
+
+<Diagram id="doc-block-dp-overview" title={"D'une requête ponctuelle à un panneau en direct"} summary={"Un script run-code devient un programme stocké dès qu'il appelle emit(); n'importe quel panneau de dashboard peut s'y lier et la politique de cache/actualisation prend le relais à partir de là."}>
+
+```html
+<div class="dp-flow">
+  <div class="diagram-card" data-rough>
+    <span class="diagram-pill">run-code script</span
+    ><small class="diagram-muted">providerFetch, joins, aggregation</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel">
+    <span class="diagram-pill accent">emit(rows, schema)</span
+    ><small class="diagram-muted"
+      >save-data-program dry-runs, then persists</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    data_program_runs<br /><small class="diagram-muted"
+      >cached per (program, params, viewer)</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill">Panneau de dashboard</span
+    ><small class="diagram-muted"><code>source: "program"</code></small>
+  </div>
+</div>
+```
+
+```css
+.dp-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.dp-flow .diagram-card,
+.dp-flow .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 14px 16px;
+  min-width: 180px;
+}
+.dp-flow .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Pourquoi cela existe {#why}
+
+Sans programme de données stocké, « construire une vue en direct de X » finit souvent dans l'un de ces deux mauvais scénarios :
+
+- **Une action codée en dur par fournisseur/forme de requête.** Fragile, et elle ne peut pas anticiper les propriétés personnalisées de chaque client, une jointure entre fournisseurs, ou un filtre arbitraire auquel vous n'avez pas pensé.
+- **Relancer la même logique de récupération/jointure à zéro à chaque vue de page.** Lent, et cela redépense le même quota d'API du fournisseur à chaque fois que quelqu'un regarde un graphique.
+
+Un programme de données est le juste milieu : écrivez la logique de récupération/jointure/agrégation une fois comme du `run-code` ordinaire, enregistrez-la, et laissez le cache et la politique d'actualisation décider de la fréquence réelle de réexécution.
+
+## Quand en utiliser un {#when-to-use-one}
+
+| Situation                                                                                                                                                                                                           | Utilisez                                                                                |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Un rollup standard a déjà une action de premier ordre (un filtre `hubspot-deals` prédéfini, une métrique intégrée)                                                                                                  | L'action existante — ne l'enveloppez pas dans un programme                              |
+| Une question de chat ponctuelle que vous ne regarderez plus jamais                                                                                                                                                  | `run-code` simple ou `provider-api-request` — répondez-y directement, ne persistez rien |
+| Une extension a besoin d'un petit widget interactif par utilisateur avec sa propre UI                                                                                                                               | [Extensions](/docs/extensions) — un programme de données n'a pas d'UI propre            |
+| Une cohorte a besoin d'un filtre de propriété arbitraire, d'une recherche IN sur des valeurs personnalisées, ou d'une jointure entre deux fournisseurs, **et** quelqu'un voudra la revoir avec des données fraîches | Un programme de données                                                                 |
+| Un panneau de dashboard doit afficher ce résultat joint/agrégé et s'actualiser selon la politique de cache                                                                                                          | Un programme de données lié à un panneau `"program"`                                    |
+
+Une comparaison avec les autres options de forme run-code :
+
+|                                            | `run-code` ponctuel           | Action de fournisseur codée en dur                            | Programme de données                                           |
+| ------------------------------------------ | ----------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------- |
+| **Persiste entre les appels**              | Non                           | N/A (c'est du code source)                                    | Oui — ligne stockée + cache de résultat                        |
+| **Le résultat est mis en cache/actualisé** | Non, se relance à chaque fois | Pas de mise en cache intégrée                                 | Oui — `refreshMode`/`refreshTtlMs`                             |
+| **Gère les filtres/jointures arbitraires** | Oui, mais jeté après          | Non — limité à ce que le schéma de l'action expose            | Oui — c'est toujours du code ordinaire                         |
+| **Liable à un panneau de dashboard**       | Non                           | Seulement si une source de panneau a été construite pour cela | Oui — la source générique `"program"`                          |
+| **Nécessite un déploiement**               | Non                           | Oui (nouvelle action = changement de code)                    | Non — créé par l'agent à l'exécution                           |
+| **Identifiants utilisés à la lecture**     | Ceux de l'appelant            | Ceux de l'appelant                                            | **Ceux du visualiseur**, résolus par lecture (voir ci-dessous) |
+
+## Flux de travail de rédaction {#authoring-workflow}
+
+1. **Prototypez d'abord dans le chat.** Écrivez la logique de récupération/jointure/agrégation comme un script `run-code` normal et confirmez qu'il renvoie les lignes attendues.
+2. **Modifiez-le pour qu'il appelle `emit(rows, schema?)` exactement une fois** à la fin, au lieu de renvoyer ou d'imprimer le résultat.
+3. **Enregistrez-le** avec `save-data-program`. Cela **exécute un dry-run du code avec `defaultParams` avant de le persister** et rejette l'enregistrement avec une erreur structurée en cas d'échec, afin qu'un programme cassé ne soit jamais stocké. En cas de succès, il renvoie `{ programId, rowCount, columns, sampleRows }` — considérez cela comme une preuve que le programme produit les lignes attendues avant de dire à l'utilisateur que c'est prêt.
+4. **Liez un panneau de dashboard à celui-ci**, ou appelez `run-data-program` directement depuis votre propre chemin de lecture. Il n'y a pas de câblage spécifique au dashboard intégré dans la primitive elle-même — la source de panneau `"program"` du template analytics (ci-dessous) est une adoption, pas un modèle obligatoire.
+5. **Itérez sans persister** via `preview-data-program({ code, params? })` — le même chemin de dry-run, sans ligne stockée.
+
+### Un exemple réaliste
+
+Supposons qu'une app veuille un tableau en direct des « tickets de support récents à forte valeur » provenant d'un fournisseur de support, filtré selon un seuil qu'aucune action intégrée n'expose :
+
+```ts
+// The program's stored `code` — ordinary run-code, with one emit() call.
+const minValue = Number(params.minValue || 5000);
+
+const tickets = await providerFetchAll("acme-support", "/v1/tickets", {
+  query: { status: "open" },
+  itemsPath: "data",
+  pagination: {
+    cursorParam: "cursor",
+    nextCursorPath: "next_cursor",
+    maxPages: 10,
+  },
+});
+
+const rows = (tickets.items || [])
+  .filter((t) => Number(t.contract_value || 0) >= minValue)
+  .map((t) => ({
+    ticket_id: t.id,
+    subject: t.subject,
+    account: t.account_name,
+    contract_value: Number(t.contract_value || 0),
+    opened_at: t.created_at,
+  }));
+
+emit(rows, [
+  { name: "ticket_id", type: "string" },
+  { name: "subject", type: "string" },
+  { name: "account", type: "string" },
+  { name: "contract_value", type: "number" },
+  { name: "opened_at", type: "string" },
+]);
+```
+
+En l'enregistrant :
+
+```ts
+await appAction("save-data-program", {
+  name: "high-value-open-tickets",
+  title: "High-Value Open Tickets",
+  description:
+    "Open support tickets above a configurable contract-value threshold.",
+  code: "/* the script above */",
+  defaultParams: { minValue: 5000 },
+  refreshMode: "ttl",
+  refreshTtlMs: 300_000,
+});
+```
+
+La réponse contient `{ programId, rowCount, columns, sampleRows }` — la preuve d'achèvement du dry-run. À partir de là, `run-data-program({ programId, params: { minValue: 10000 } })` le relance (ou sert le cache) pour un seuil différent, et un panneau de dashboard peut se lier à `programId` de la même manière.
+
+## La surface du bac à sable {#sandbox-surface}
+
+Un programme de données s'exécute exactement dans le même bac à sable `executeSandboxCode` que `run-code` — aucun nouveau code de bac à sable, d'identifiants, de SSRF ou de quota n'existe pour cette primitive. Il obtient les mêmes globals (`providerFetch`, `providerFetchAll`, `providerSearchAll`, `appAction`, `webFetch`, helpers Resources `workspace*`) plus deux ajouts issus d'un petit préambule injecté par le framework :
+
+- **`params`** — un objet global **gelé** contenant les params de cette exécution (`defaultParams` fusionné avec ce qui a été passé à `run-data-program` ou au descripteur du panneau). Le lire est acceptable ; le muter lève une erreur.
+- **`emit(rows, schema?)`** — appelez ceci **exactement une fois**, à la fin. Un deuxième appel lève une erreur. `rows` doit être un tableau d'objets simples. `schema`, s'il est fourni, est `{ name: string, type: string }[]` ; s'il est omis, il est déduit des 50 premières lignes (une colonne est `"json"` si les lignes de l'échantillon ne s'accordent pas sur un type primitif, sinon `"number"` / `"string"` / `"boolean"`). `console.log` reste totalement libre pour le débogage — le runner capture stdout/stderr combinés et ne retire que la ligne sentinelle que `emit()` écrit lors de l'analyse du résultat.
+
+Plafonds appliqués à chaque exécution (non configurables par programme) :
+
+| Limite                                                             | Valeur                                                                                                                                                                      |
+| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Max de lignes émises                                               | 10 000 — les lignes au-delà sont supprimées, `truncated: true`                                                                                                              |
+| Taille max du résultat émis                                        | 4 Mio — les lignes sont supprimées depuis la fin pour tenir ; une seule ligne dépassant le plafond est un échec dur `result_too_large`, car il n'y a rien de sûr à tronquer |
+| Max de programmes actifs (non archivés) par app                    | 200 — archivez les inutilisés pour libérer de la place                                                                                                                      |
+| TTL d'actualisation minimum                                        | 60 000 ms                                                                                                                                                                   |
+| Lignes d'exécution conservées par (programme, params, visualiseur) | 5 plus récentes — les plus anciennes sont automatiquement purgées à chaque écriture                                                                                         |
+
+La troncature est toujours explicite (`truncated: true` dans le résultat) — jamais une perte silencieuse.
+
+## Params et liaison de panneau de dashboard {#params-and-panel-binding}
+
+Les programmes déclarent un `paramsSchema` optionnel (JSON Schema décrivant les params acceptés) et des `defaultParams`. Un dashboard adopte la source de panneau `"program"` en plaçant un petit descripteur JSON dans le champ de requête du panneau au lieu d'une chaîne de requête :
+
+```json
+{ "programId": "dp_a1b2c3d4e5f6", "params": { "minValue": 10000 } }
+```
+
+Le panneau se rend exactement à travers les mêmes composants graphique/tableau que n'importe quelle autre source de panneau — il ne reçoit jamais que `{ rows, schema }` en retour. Lier un panneau à un programme, c'est simplement « quel programme stocké, avec quelles surcharges de params » ; il n'existe aucun chemin d'exécution spécifique au dashboard dupliqué ailleurs.
+
+## Sémantique d'actualisation, de TTL et de mise en cache {#refresh-and-caching}
+
+Chaque paire `(programId, paramsHash)` a son propre historique d'exécution dans `data_program_runs`, et `paramsHash` intègre **le visualiseur**, pas seulement les params (voir la section sécurité pour comprendre pourquoi). Ce qui se passe à chaque lecture :
+
+| Situation                                                                                         | Comportement                                                                                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Cache frais (plus récent que `refreshTtlMs`, ou `refreshMode: "manual"` avec un succès préalable) | Renvoie instantanément les lignes en cache, `cacheHit: true`                                                                                                                                                                    |
+| Le cache est plus ancien que le TTL                                                               | Se réexécute de manière synchrone — un budget de 25s pour les lectures déclenchées par vue de panneau, 120s pour les appels agent/manuels — et remplace le cache en cas de succès                                               |
+| `refreshMode: "manual"`                                                                           | Ne s'actualise jamais automatiquement ; seul un `forceRefresh: true` explicite (ou une action d'actualisation manuelle de l'UI) le relance                                                                                      |
+| Pas encore de cache                                                                               | S'exécute de manière synchrone comme une première récupération normale                                                                                                                                                          |
+| Programme `background: true`, pas de cache frais                                                  | Sert immédiatement la dernière bonne exécution avec `stale: true` et met en file d'attente une exécution en arrière-plan durable (budget de 10 minutes) ; un appel ultérieur finalise le résultat une fois l'exécution terminée |
+| Programme en arrière-plan encore en cours, pas de succès préalable                                | Échec `background_pending` — affichez un état explicite « encore en calcul », jamais un résultat vide                                                                                                                           |
+| L'exécution échoue (timeout, erreur de bac à sable, forme de `emit()` incorrecte)                 | Un échec structuré `{ code, message }` ; si un succès précédent existe, il est attaché comme `lastGoodRun` afin qu'un panneau puisse servir des données obsolètes plutôt que de rester vide                                     |
+| Le programme a été archivé (suppression douce via `delete-data-program`)                          | Échec explicite `archived` — jamais un panneau vide silencieux                                                                                                                                                                  |
+
+Ne recourez à `background: true` que pour les programmes qui dépassent régulièrement le timeout de premier plan — grandes jointures multi-fournisseurs, pagination profonde. Tout le reste devrait rester en premier plan : c'est plus simple à raisonner et cela sert des données fraîches plus rapidement.
+
+### Pourquoi le cache est délimité par visualiseur {#per-viewer-cache}
+
+`providerFetch` à l'intérieur d'un programme résout l'authentification en utilisant **le propre contexte de requête du visualiseur appelant** — jamais celui de l'auteur du programme. C'est vrai que l'appel provienne de l'agent, d'un appel `run-data-program`, ou d'un panneau de dashboard consulté par un coéquipier. Deux visualiseurs différents exécutant le même programme avec les mêmes params peuvent légitimement obtenir deux résultats différents : l'un a une clé HubSpot configurée et l'autre non, ou les permissions du fournisseur au niveau des lignes diffèrent selon la personne.
+
+Pour cette raison, `hashDataProgramParams` intègre l'identité de l'appelant dans la clé de cache en plus des params canonicalisés. Cela compte le plus pour les **dashboards partagés** : si le cache était indexé uniquement par params, la première personne à consulter un panneau déterminerait silencieusement ce que voit chaque autre visualiseur, y compris un visualiseur sans les identifiants ayant produit ce résultat mis en cache. La délimitation par visualiseur signifie qu'un coéquipier sans identifiant voit sa propre erreur d'authentification sur ce panneau, pas les données de quelqu'un d'autre.
+
+## Modèle de sécurité {#security}
+
+<Callout id="doc-block-dp-security" tone="success">
+
+**Les jetons de fournisseur bruts n'atteignent jamais le modèle ni le navigateur.** La seule chose qui quitte jamais le bac à sable est le `{ rows, schema }` qu'un appel `emit()` produit — la même frontière de confiance que toute autre exécution run-code et toute autre source de panneau de dashboard.
+
+</Callout>
+
+- **Uniquement côté serveur.** Le code d'un programme de données s'exécute exclusivement à l'intérieur de `executeSandboxCode` sur le serveur. Ni le code source stocké ni aucun identifiant qu'il touche n'est envoyé au navigateur ou au modèle — seuls les lignes/schéma émis et les métadonnées d'exécution compactes (nombre de lignes, colonnes, lignes d'exemple) le sont.
+- **Les identifiants sont toujours ceux du visualiseur appelant, jamais ceux de l'auteur original du programme.** Voir [Sémantique d'actualisation, de TTL et de mise en cache](#per-viewer-cache) ci-dessus pour comprendre pourquoi cela détermine aussi la clé de cache.
+- **`allowPublic: false` est un invariant strict, pas une valeur par défaut.** Les programmes de données s'enregistrent auprès du registre de sharing de la même manière que les [Extensions](/docs/extensions#security), avec le sharing public désactivé. Un programme public permettrait à tout utilisateur authentifié d'exécuter du code arbitraire stocké sous son propre jeton — partager un programme est limité à votre organisation, et ne signifie jamais que « les coéquipiers peuvent voir son résultat mis en cache et déclencher de nouvelles exécutions », jamais que « l'internet général peut exécuter ceci ».
+- **Les actions mutantes et exécutantes ne sont pas invocables comme outil depuis le pont extension/iframe en bac à sable.** `save-data-program`, `preview-data-program`, `run-data-program` et `delete-data-program` sont `toolCallable: false` — seul l'agent ou un chemin de lecture côté serveur peut les invoquer, jamais un iframe d'extension sous la session de l'ouvreur. `list-data-programs` et `get-data-program` sont en lecture seule et délimités par accès via les mêmes helpers de sharing que toute autre ressource ownable.
+- **Les programmes sont limités à l'app qui les a créés.** Passer `appId` à une recherche signifie qu'un programme créé dans une app n'est pas exécutable depuis le chat agent d'une autre app dans un déploiement à base de données partagée, même pour un appelant qui aurait par ailleurs un accès au niveau des lignes (owner/org/share) à celui-ci.
+- **Ne vous liez qu'à un programme, ou ne le consultez que si vous lui faites confiance.** Puisque l'exécution utilise toujours les propres identifiants du visualiseur, consulter le résultat d'un programme partagé est exactement comme ouvrir l'extension de quelqu'un d'autre — faites confiance au code, pas seulement à l'autorisation d'accès.
+
+## L'exemple travaillé de Risk Meeting {#risk-meeting-example}
+
+Le template analytics fournit une étude de cas concrète et exécutable : l'action `ensure-risk-meeting-dashboard` installe de manière idempotente deux programmes de données plus un dashboard « Risk Meeting » à deux panneaux, démontrant trois choses qu'une action codée en dur ne peut pas anticiper pour chaque client.
+
+<FileTree
+  id="doc-block-dp-risk-meeting-files"
+  title={"Installateur Risk Meeting"}
+  entries={[
+    {
+      path: "templates/analytics/actions/ensure-risk-meeting-dashboard.ts",
+      note: "action idempotente : met à jour les deux programmes par nom stable, puis le dashboard par id",
+    },
+    {
+      path: "templates/analytics/seeds/data-programs/risk-meeting-cohort.js",
+      note: "charge utile de programme stocké — texte JS brut, pas un fichier source de build",
+    },
+    {
+      path: "templates/analytics/seeds/data-programs/risk-meeting-pylon-early-warning.js",
+      note: "le programme d'alerte précoce complémentaire",
+    },
+  ]}
+/>
+
+**`risk-meeting-cohort.js`** — recherche une cohorte configurable de deals CRM par une propriété `risk_status` arbitraire (une recherche IN sur des valeurs personnalisées qu'une action prédéfinie ne peut pas anticiper), résout l'entreprise de chaque deal via une recherche d'association par lots, résout le domaine de chaque entreprise, récupère le sentiment de compte d'un second fournisseur non lié, et joint les deux par domaine :
+
+```js
+// params: { riskStatuses?: string[], enterpriseOnly?: boolean }
+const riskStatuses = params.riskStatuses?.length
+  ? params.riskStatuses
+  : ["On the Radar", "Churn Risk", "Confirmed Churn", "No Save Attempted"];
+
+// 1. Arbitrary property IN-search — not expressible through a canned filter.
+const dealSearch = await providerFetchAll("crm-provider", "/deals/search", {
+  method: "POST",
+  body: {
+    filterGroups: [
+      {
+        filters: [
+          { propertyName: "risk_status", operator: "IN", values: riskStatuses },
+        ],
+      },
+    ],
+  },
+  itemsPath: "results",
+  pagination: {
+    cursorBodyPath: "after",
+    nextCursorPath: "paging.next.after",
+    maxPages: 20,
+  },
+});
+
+// 2-3. Batched deal -> company -> domain resolution (elided here; see the
+// real seed file for the full batching helper).
+
+// 4. A second, unrelated provider — zero bespoke glue action required.
+const accounts = await providerFetchAll("support-provider", "/accounts", {
+  itemsPath: "data",
+  pagination: {
+    cursorParam: "cursor",
+    nextCursorPath: "pagination.cursor",
+    maxPages: 20,
+  },
+});
+
+// 5. Join + emit.
+const rows = dealSearch.items.map((deal) => ({
+  deal_id: deal.id,
+  risk_status: deal.properties.risk_status,
+  arr: Number(deal.properties.total_contract_value || 0),
+  // ...domain lookup + sentiment join...
+}));
+
+emit(rows, [
+  { name: "deal_id", type: "string" },
+  { name: "risk_status", type: "string" },
+  { name: "arr", type: "number" },
+]);
+```
+
+**`risk-meeting-pylon-early-warning.js`** — la vue complémentaire : des comptes déjà signalés à risque par le sentiment de support qui **n'ont pas encore** apparu dans la cohorte CRM ci-dessus. Cet écart — un signal de support en avance sur le signal CRM — nécessite d'exclure la cohorte d'un fournisseur de celle d'un autre, exactement le type de logique d'ensemble entre fournisseurs qu'aucune action mono-fournisseur ne peut exprimer.
+
+Les deux programmes sont installés et maintenus à jour par `ensure-risk-meeting-dashboard`, qui :
+
+- Met à jour chaque programme par son `name` stable, de sorte que relancer l'installateur met à jour les mêmes lignes au lieu de les dupliquer.
+- Ne nécessite aucun identifiant CRM/support au moment de l'installation — l'authentification du fournisseur se résout par visualiseur uniquement lorsqu'un panneau est réellement rendu ou que `run-data-program` est appelé, cohérent avec la délimitation de cache par visualiseur ci-dessus.
+- Construit un dashboard à deux panneaux dont les panneaux utilisent `source: "program"`, liés à l'id de chaque programme.
+
+Voir la skill `data-programs` pour la source entièrement annotée.
+
+## Comment d'autres apps adoptent la source de panneau {#adopting-the-panel-source}
+
+La source de panneau de dashboard `"program"` est une adoption de la primitive, entièrement implémentée dans la propre couche de requête de panneau de l'app hôte — rien de spécifique au dashboard n'est intégré dans `@agent-native/core/data-programs` lui-même. L'implémentation du template analytics est une référence utile pour câbler la vôtre :
+
+- La colonne `sql` du panneau porte un petit descripteur JSON — `{ programId, params? }` — au lieu d'une chaîne de requête.
+- Rendre un panneau appelle `runDataProgram` avec `triggeredBy: "panel_view"` et l'identité du visualiseur actuel, de sorte que le cache par visualiseur et la résolution des identifiants s'appliquent automatiquement.
+- En cas de succès, le panneau obtient `{ rows, schema }` — la même forme que renvoie toute autre source de panneau, de sorte qu'elle circule sans modification à travers les composants graphique/tableau existants.
+- En cas d'échec, un `lastGoodRun` est préféré à un panneau cassé chaque fois qu'il en existe un ; ce n'est que lorsqu'il n'y a pas de succès préalable que le panneau affiche une erreur structurée (avec un texte plus convivial pour les codes courants comme `access_denied`, `archived` et `background_pending`).
+
+Toute app peut implémenter la même adoption pour ses propres dashboards/tableaux : appelez `run-data-program` (ou `runDataProgram` directement si vous êtes dans le même processus serveur) depuis votre propre chemin de lecture, et transmettez les `rows`/`schema` renvoyées à vos propres composants de rendu.
+
+## Docs associées {#related}
+
+- [Extensions](/docs/extensions) — la primitive de mini-app en bac à sable avec laquelle les programmes de données partagent une posture de sécurité et un modèle de sharing, mais avec une UI propre.
+- [Actions](/docs/actions) — les conventions `run-code` et les globals du bac à sable (`providerFetch`, `appAction`, etc.) sur lesquels les programmes de données sont construits.
+- [Sharing & confidentialité](/docs/sharing) — le modèle de sharing interne à l'organisation, jamais public, qu'utilisent les programmes de données.
+- [Sécurité](/docs/security) — les invariants de gestion des identifiants et de délimitation d'accès du framework.

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

@@ -384,24 +384,23 @@ Faites-les pivoter en remplaçant la variable d'environnement sur chaque instanc
 ## Outils d'agent de production {#production-agent-tools}
 
 Les agents de production obtiennent les outils actions enregistrés ainsi que les outils-cadres de l'application
-le plugin de chat d'agent. Les écritures de base de données sont activées par défaut car la base de données brute
-les outils sont limités à l'utilisateur/à l'organisation authentifié, mais les propriétaires d'applications peuvent restreindre l'accès
-faire surface lorsqu'un déploiement devrait être plus opiniâtre :
+le plugin de chat d'agent. L’inspection SQL est activée par défaut; les écritures
+passent par des actions d’application typées, sauf si l’application active explicitement les outils d’écriture SQL bruts :
 
 ```ts
 // server/plugins/agent-chat.ts
 export default createAgentChatPlugin({
-  // Default: "write" (also true)
+  // Default: "read"
   databaseTools: "read", // "write" | "read" | "off"
   extensionTools: false,
 });
 ```
 
-- `databaseTools: "write"` — par défaut. Registres `db-schema`, `db-query`,
-  `db-exec` et `db-patch`. Les écritures sont limitées à l'utilisateur/à l'organisation actuelle et
-  les modifications de schéma sont bloquées.
-- `databaseTools: "read"` — enregistre uniquement `db-schema` et `db-query` ; agents
-  inspectez les données avec SQL mais devez utiliser l'application typée actions pour les écritures.
+- `databaseTools: "read"` — par défaut. Enregistre uniquement `db-schema` et `db-query`;
+  les agents inspectent les données avec SQL, mais doivent utiliser les actions typées de l’application pour écrire.
+- `databaseTools: "write"` ou `true` — enregistre aussi `db-exec` et `db-patch`
+  pour une maintenance SQL brute délibérée. Les écritures sont limitées à
+  l’utilisateur/l’organisation actuel(le) et les modifications de schéma sont bloquées.
 - `databaseTools: "off"` ou `false` : supprime les outils de base de données brutes du
   surface de l'agent afin que les actions de l'application soient le seul chemin d'accès aux données.
 - `extensionTools: false` — supprime la gestion des extensions de framework actions et