@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/fr-FR/faq.md

@@ -0,0 +1,142 @@
+---
+title: "FAQ"
+description: "Questions courantes sur l'agent natif : de quoi s'agit-il, à qui s'adresse-t-il, ce que vous pouvez créer et comment cela fonctionne."
+---
+
+# FAQ
+
+Questions courantes sur les agents natifs, organisées de "Je cherche juste" à "Je suis en train de configurer l'authentification en ce moment."
+
+## Les bases {#general}
+
+### Qu'est-ce que l'agent natif ? {#what-is-agent-native}
+
+Agent-native est un cadre permettant de créer des applications dans lesquelles l'agent IA et le produit qui l'entoure sont des partenaires égaux. Cette surface peut commencer comme un agent sans tête avec une action personnalisée, se transformer en un chat riche ou devenir un UI complet. L'invariant est que les agents et les humains partagent le même actions, la même base de données et le même état. Voir [What Is Agent-Native?](/docs/what-is-agent-native) pour l'explication complète.
+
+### À qui est-ce destiné ? {#who-is-this-for}
+
+Agent-native est destiné aux personnes qui souhaitent qu'une véritable application et un agent IA fonctionnent à partir des mêmes données et actions. Les chemins courants sont :
+
+- **Utilisez une application hébergée** si vous souhaitez recevoir un courrier, un calendrier, des formulaires, un plan ou un autre modèle fini sans configuration – commencez par le [template gallery](/templates).
+- **Commencez avec Chat** si vous souhaitez une application de base avec laquelle les utilisateurs peuvent parler immédiatement, puis étendez-la avec actions et les écrans – commencez par [Getting Started](/docs/getting-started) ou [Chat](/docs/template-chat).
+- **Démarrez d'abord les primitives** si vous souhaitez une action et une boucle d'agent d'application sans tête avant de vous engager dans UI — commencez par [Getting Started](/docs/getting-started).
+- ** Créez et personnalisez un modèle ** si vous souhaitez créer votre propre produit SaaS avec authentification, base de données, UI et agent actions déjà câblés – voir [Templates](/docs/cloneable-saas).
+- **Construisez à partir de zéro** si vous souhaitez les primitives de structure pour un nouveau produit piloté par agent : commencez par [Getting Started](/docs/getting-started).
+- **Connectez un autre agent ou un autre outil de code** si vous souhaitez que Claude, ChatGPT, Codex, Cursor ou GitHub Copilot / VS Code utilisent une application native d'agent – voir [External Agents](/docs/external-agents) et [Skills Guide](/docs/skills-guide).
+
+### En quoi est-ce différent de l'ajout de l'IA à une application existante ? {#how-is-this-different}
+
+La plupart des applications intègrent l'IA après coup, ce qui ne permet pas réellement de _faire_ des choses dans l'application. Dans une application native d'agent, l'agent est un citoyen de première classe qui partage le même actions, la même base de données et le même état que le UI, il peut donc faire tout ce que les boutons peuvent faire - et modifier le propre code de l'application. Voir [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder).
+
+```an-diagram title="Bolted-on AI vs. agent-native" summary="A bolted-on chat sidebar lives in its own world. An agent-native agent shares the same actions, database, and state as the UI."
+{
+  "html": "<div class=\"diagram-vs\"><div class=\"diagram-col\"><span class=\"diagram-pill warn\">Bolted-on AI</span><div class=\"diagram-node\">Chat sidebar</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>separate AI world<br><small class=\"diagram-muted\">can't touch the app</small></div><div class=\"diagram-box diagram-muted\">App UI &amp; data</div></div><div class=\"diagram-divider\" aria-hidden=\"true\"></div><div class=\"diagram-col\"><span class=\"diagram-pill ok\">Agent-native</span><div class=\"diagram-row2\"><div class=\"diagram-node\">UI</div><div class=\"diagram-node\">Agent</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>shared actions, DB &amp; state</div></div></div>",
+  "css": ".diagram-vs{display:flex;align-items:stretch;gap:18px;flex-wrap:wrap}.diagram-vs .diagram-col{display:flex;flex-direction:column;gap:8px;align-items:center;flex:1;min-width:200px}.diagram-vs .diagram-row2{display:flex;gap:8px}.diagram-vs .diagram-arrow{font-size:20px;line-height:1}.diagram-vs .diagram-divider{width:1px;align-self:stretch;background:currentColor;opacity:.15}"
+}
+```
+
+### Est-ce open source ? {#is-this-open-source}
+
+Oui. Le framework et tous les modèles sont open source. Vous pouvez tout exécuter localement, vous auto-héberger ou utiliser le cloud de Builder.io pour l'hébergement géré, la collaboration et les fonctionnalités d'équipe.
+
+### Combien ça coûte ? {#how-much}
+
+Le framework lui-même est gratuit. Les deux coûts que vous verrez en pratique :
+
+- **Utilisation de l'IA.** Vous apportez votre propre clé API (Anthropic, OpenAI, etc.) et payez directement le fournisseur de modèles. Il n'y a aucun balisage de notre part.
+- **Hébergement.** Quels que soient les frais facturés par votre hôte. La plupart des modèles fonctionnent correctement sur les niveaux gratuits (Netlify, Vercel, Cloudflare) pour les petites charges de travail.
+
+Si vous préférez ne rien gérer de tout cela, la version hébergée sur `agent-native.com` (exploitée par Builder.io) regroupe l'inférence et l'hébergement dans un forfait par siège.
+
+### Puis-je héberger cela moi-même ? {#can-i-self-host}
+
+Oui. Choisissez n'importe quel hôte qui exécute Node — Netlify, Vercel, Cloudflare, AWS, Deno Deploy, votre propre serveur — et n'importe quelle base de données SQL (Postgres, SQLite, Turso, D1). Le framework est conçu pour être portable. Voir [Deployment](/docs/deployment).
+
+### Quels modèles d'IA est-il pris en charge ? {#what-models}
+
+Anthropic Claude, OpenAI (famille GPT-5), Google Gemini et tout fournisseur parlant la forme OpenAI API (y compris les modèles locaux via Ollama). Vous configurez le modèle dans les paramètres ; la commutation est un changement de configuration, pas une réécriture de code. Le chemin le plus testé du framework est Claude, c'est donc la recommandation par défaut.
+
+### Dois-je connaître l'IA/ML ? {#do-i-need-to-know-ai}
+
+Non. Vous ne formez pas de modèles, n'ajustez pas et ne gérez pas les intégrations. Vous créez une application Web standard – et sur la version hébergée, vous ne créez pratiquement rien. Le framework gère l'intégration de l'agent : routage des messages, exécution de actions, état de synchronisation.
+
+### Puis-je migrer une application existante vers une application native pour agent ? {#can-i-use-existing-code}
+
+C'est possible, mais l'agent natif fonctionne mieux lorsqu'il est construit à partir de zéro. L'architecture (base de données partagée, synchronisation des interrogations, actions, état de l'application) doit être intégrée partout. Partir d’un modèle et le personnaliser est le chemin recommandé. Pensez-y comme au passage d'un ordinateur de bureau d'abord à un mobile d'abord : vous _pouvez_ effectuer une mise à niveau, mais construire en natif, c'est mieux.
+
+## Modèles et ce que vous pouvez créer {#templates}
+
+### Quels modèles sont disponibles ? {#what-templates-are-available}
+
+Le framework est livré avec des modèles prêts pour la production, notamment [Chat](/docs/template-chat), [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Plan](/docs/template-plan) (plans visuels et récapitulatifs des relations publiques), [Analytics](/docs/template-analytics), [Dispatch](/docs/template-dispatch), et bien plus encore. Chacune est une application complète avec UI, l'agent actions, un schéma de base de données et des instructions IA prêtes à l'emploi. Voir [Templates](/docs/cloneable-saas) pour le catalogue complet.
+
+### Puis-je personnaliser les modèles ? {#can-i-customize-templates}
+
+C'est là tout l'intérêt. Créez un modèle et personnalisez-le en le demandant à l'agent. "Ajouter un champ prioritaire aux formulaires." "Connectez-vous à notre instance Salesforce." "Changez la palette de couleurs pour qu'elle corresponde à notre marque." L'agent modifie le code et votre application évolue au fil du temps.
+
+### Puis-je créer quelque chose que les modèles ne couvrent pas ? {#build-from-scratch}
+
+Oui. Si vous souhaitez une application de chat de base, exécutez `npx @agent-native/core@latest create my-chat-app --template chat` ; vous bénéficiez de fils de discussion durables, de actions, d'une authentification, d'un état d'exécution soutenu par SQL et d'un espace pour ajouter vos propres écrans. Si vous souhaitez la plus petite application axée sur l'action sans UI, exécutez `npx @agent-native/core@latest create my-agent --headless`. Voir [Getting Started](/docs/getting-started), [Pure-Agent Apps](/docs/pure-agent-apps) et [Chat](/docs/template-chat).
+
+### Puis-je l'essayer sans créer de modèle ? {#try-with-a-skill}
+
+Oui : installez une compétence dans un agent de codage que vous utilisez déjà avec une seule commande et aucun échafaudage requis. Consultez le [Skills Guide](/docs/skills-guide#app-backed-skills) pour la procédure pas à pas.
+
+## Capacités de l'agent {#agent-capabilities}
+
+### L'agent peut-il réellement modifier le code de l'application ? {#can-the-agent-modify-code}
+
+Oui, et c'est une fonctionnalité. L'agent peut modifier en toute sécurité les composants, les itinéraires, les styles et actions. Vous demandez "ajouter un graphique d'analyse de cohorte" et l'agent le construit. Vous demandez "Connectez-vous à notre compte Stripe" et l'agent rédige l'intégration. Tout est du code normal suivi par Git, donc les mauvaises modifications sont faciles à annuler.
+
+### Les utilisateurs peuvent-ils parler à l'agent depuis l'extérieur de l'application ? {#external-channels}
+
+Oui. Le même agent s'exécute sur votre site Web UI, dans Slack, dans Telegram, par courrier électronique et à partir d'autres agents (via [A2A](/docs/a2a-protocol)). C'est le même agent avec la même mémoire et le même actions, accessible via différents canaux. Voir [Messaging the agent](/docs/messaging).
+
+### Les agents peuvent-ils communiquer entre eux ? {#can-agents-talk-to-each-other}
+
+Oui, via le [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol). Chaque application native d'agent obtient automatiquement un point de terminaison A2A. Depuis l'application de messagerie, vous pouvez marquer l'agent d'analyse pour interroger les données. Un agent découvre quels autres agents sont disponibles, les appelle via le protocole et affiche les résultats dans le UI. Aucune configuration nécessaire : la carte d'agent est générée automatiquement à partir du actions de votre modèle.
+
+### Que peut voir l'agent dans l'application ? {#what-can-the-agent-see}
+
+L'agent sait toujours ce que l'utilisateur consulte actuellement. Le UI écrit l'état de navigation dans la base de données à chaque changement d'itinéraire — quelle vue est ouverte, quel élément est sélectionné. L'agent lit ceci avant d'agir. Si un email est ouvert, l'agent sait quel email. Si une diapositive est sélectionnée, l'agent sait quelle diapositive. Voir [Context Awareness](/docs/context-awareness).
+
+## Questions de développement {#development}
+
+### Quels outils de codage d'IA fonctionnent avec les agents natifs ? {#which-ai-tools-work}
+
+Tout outil de codage d'IA qui lit les instructions du projet. Le framework utilise AGENTS.md comme standard universel et crée automatiquement des liens symboliques pour des outils spécifiques :
+
+- **Code Claude** — lit CLAUDE.md (lié symboliquement à partir de AGENTS.md par la configuration CLI)
+- **Curseur** — lit directement AGENTS.md, ou `.cursorrules` (emplacement hérité du curseur) s'il est présent dans votre projet
+- **Windsurf** — lit .windsurfrules (lié symboliquement depuis AGENTS.md par la configuration CLI)
+- **Codex, Gemini et autres** — travaillez via le panneau d'agent intégré
+- **Builder.io** – agent hébergé dans le cloud avec édition visuelle et collaboration
+
+### Puis-je utiliser ma propre base de données ? {#can-i-use-my-own-database}
+
+Oui. Définissez `DATABASE_URL` et le framework le détecte automatiquement. Les bases de données prises en charge incluent SQLite, Postgres (Neon, Supabase, plain), Turso (libSQL) et Cloudflare D1. Tous les SQL sont indépendants du dialecte via Drizzle ORM — le même code fonctionne partout.
+
+### Où puis-je déployer ? {#where-can-i-deploy}
+
+N'importe où. Le serveur fonctionne sur Nitro, qui se compile sur n'importe quelle cible de déploiement : Node.js, Cloudflare Workers/Pages, Netlify, Vercel, Deno Deploy, AWS Lambda et Bun. Vous pouvez également utiliser l'hébergement de Builder.io pour les déploiements gérés. Voir le [Deployment guide](/docs/deployment).
+
+## Architecture {#architecture}
+
+### Pourquoi SSE plus sondage au lieu de WebSocket ? {#why-polling-not-websockets}
+
+SSE donne aux écritures du même processus un chemin immédiat vers le navigateur, et un sondage léger du compteur de versions reste la solution de secours car il fonctionne dans tous les environnements de déploiement, y compris sans serveur et en périphérie, où les sockets persistants peuvent ne pas être disponibles. Voir [Key Concepts — Live sync](/docs/key-concepts#polling-sync).
+
+```an-diagram title="SSE first, polling fallback" summary="Same-process writes stream instantly; a version-counter poll keeps serverless, edge, and cross-process writes convergent."
+{
+  "html": "<div class=\"diagram-transport\"><div class=\"diagram-box\" data-rough>DB write</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-node\">SSE<br><small class=\"diagram-muted\">/_agent-native/events &middot; instant</small></div><div class=\"diagram-node\">Poll<br><small class=\"diagram-muted\">/_agent-native/poll &middot; universal fallback</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Browser refetch</div></div>",
+  "css": ".diagram-transport{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-transport .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-transport .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+### Pourquoi le UI ne peut-il pas appeler directement un LLM ? {#why-no-inline-llm-calls}
+
+L'IA n'est pas déterministe, vous avez donc besoin d'un flux de conversation pour donner des commentaires et itérer (et non de boutons ponctuels) et l'agent dispose déjà de votre base de code, de vos instructions, de skills et de l'historique qui manque à un appel en ligne. Tout acheminer via l'agent permet également à l'application d'être pilotée depuis Slack, Telegram ou un autre agent. Voir [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge).
+
+### Pourquoi s'agit-il d'un framework et non d'une bibliothèque ? {#why-framework-not-library}
+
+La base de données partagée, la synchronisation en direct, le système actions et l'état de l'application ne fonctionnent que parce qu'ils sont connectés ensemble depuis le début : le UI réagit instantanément aux changements d'agent, les agents communiquent et l'agent comprend ce que l'utilisateur regarde. Une bibliothèque vous donne des pièces ; c'est une architecture. Voir [Key Concepts](/docs/key-concepts).

package/docs/content/locales/fr-FR/file-uploads.md

@@ -0,0 +1,122 @@
+---
+title: "Téléchargements de fichiers"
+description: "Configurer le stockage de téléchargement de fichiers : solution de secours SQL pour le développement, Builder.io ou fournisseurs personnalisés pour la production."
+---
+
+# Téléchargements de fichiers
+
+Le framework fournit une abstraction de téléchargement de fichiers qui achemine les téléchargements via un fournisseur configurable. Les modèles appellent `uploadFile()` et récupèrent un URL : le backend de stockage est échangeable sans modifier le code de l'application.
+
+## Comment ça marche {#how-it-works}
+
+Les requêtes de téléchargement sont envoyées à `POST /_agent-native/file-upload`, qui les envoie au fournisseur actif. Vous pouvez vérifier quel fournisseur est configuré sur `GET /_agent-native/file-upload/status`.
+
+L'ordre de résolution du fournisseur est :
+
+1. **Fournisseurs enregistrés par l'utilisateur** : fournisseurs personnalisés enregistrés via `registerFileUploadProvider()`
+2. **Fournisseur Builder.io** — intégré, s'active automatiquement lorsque Builder.io est connecté
+3. **SQL fallback** — stocke les fichiers en base64 dans la base de données (bien pour le développement, pas pour la production)
+
+```an-diagram title="Provider resolution order" summary="uploadFile() picks the first configured provider in order. The SQL fallback always exists so uploads work with zero setup."
+{
+  "html": "<div class=\"diagram-upload\"><div class=\"diagram-box\" data-rough>uploadFile()<br><small class=\"diagram-muted\">POST /_agent-native/file-upload</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-step\"><span class=\"diagram-pill accent\">1</span><div class=\"diagram-node\">User-registered<br><small class=\"diagram-muted\">registerFileUploadProvider() — S3, R2, GCS…</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill\">2</span><div class=\"diagram-node\">Builder.io<br><small class=\"diagram-muted\">auto when connected — CDN-served</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill warn\">3</span><div class=\"diagram-node\">SQL fallback<br><small class=\"diagram-muted\">base64 in DB — dev only</small></div></div></div></div>",
+  "css": ".diagram-upload{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-upload .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-upload .diagram-step{display:flex;align-items:center;gap:8px}.diagram-upload .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```an-api title="The upload endpoint" method="POST" path="/_agent-native/file-upload"
+{
+  "method": "POST",
+  "path": "/_agent-native/file-upload",
+  "summary": "Upload a file through the active provider and get back a public URL.",
+  "description": "Dispatches to the first configured provider in resolution order. Check the active provider at `GET /_agent-native/file-upload/status`.",
+  "request": { "contentType": "multipart/form-data" },
+  "responses": [
+    { "status": "200", "description": "{ url, id?, provider } — the public URL and which provider handled it." }
+  ]
+}
+```
+
+## Par défaut : Retour SQL {#sql-fallback}
+
+Lorsqu'aucun fournisseur n'est configuré, les fichiers sont stockés sous forme de données base64 dans la base de données SQL via le système de ressources. Cela fonctionne immédiatement pour le développement local, mais n'est pas recommandé pour la production : les fichiers volumineux gonflent la base de données et il n'y a pas de CDN.
+
+Un avertissement unique est enregistré lorsque la solution de secours est utilisée.
+
+## Hébergement Builder.io {#builder-hosting}
+
+Lorsque votre application est connectée à Builder.io, les téléchargements de fichiers sont automatiquement acheminés vers l'hébergement d'actifs de Builder. Les fichiers sont servis à partir d'un CDN sans aucune configuration nécessaire. Il s'agit de la configuration de production recommandée.
+
+## Fournisseurs personnalisés {#custom-providers}
+
+Enregistrez un fournisseur personnalisé dans un plugin de serveur pour utiliser n'importe quel backend de stockage (S3, Cloudflare R2, GCS, etc.) :
+
+```ts
+// server/plugins/file-upload.ts
+import { registerFileUploadProvider } from "@agent-native/core/file-upload";
+
+export default defineNitroPlugin(() => {
+  registerFileUploadProvider({
+    id: "s3",
+    name: "Amazon S3",
+    isConfigured: () => !!process.env.S3_BUCKET,
+    upload: async ({ data, filename, mimeType }) => {
+      const key = `uploads/${Date.now()}-${filename}`;
+      await s3Client.putObject({
+        Bucket: process.env.S3_BUCKET!,
+        Key: key,
+        Body: data,
+        ContentType: mimeType,
+      });
+      return {
+        url: `https://${process.env.S3_BUCKET}.s3.amazonaws.com/${key}`,
+        provider: "s3",
+      };
+    },
+  });
+});
+```
+
+## Télécharger API {#upload-api}
+
+L'interface `FileUploadProvider` :
+
+```ts
+interface FileUploadProvider {
+  id: string; // Unique id, e.g. "s3"
+  name: string; // Human-readable name
+  isConfigured: () => boolean; // True when ready (env vars set, etc.)
+  upload: (input: FileUploadInput) => Promise<FileUploadResult>;
+}
+
+interface FileUploadInput {
+  data: Uint8Array | Buffer; // File contents
+  filename?: string; // Original filename
+  mimeType?: string; // MIME type, e.g. "image/png"
+  ownerEmail?: string; // For per-user scoping in fallback
+}
+
+interface FileUploadResult {
+  url: string; // Public URL for the uploaded file
+  id?: string; // Provider-specific id
+  provider: string; // Which provider handled it
+}
+```
+
+Utilisez `uploadFile()` à partir de `@agent-native/core/file-upload` dans actions ou le code serveur :
+
+```ts
+import { uploadFile } from "@agent-native/core/file-upload";
+
+const result = await uploadFile({
+  data: fileBuffer,
+  filename: "photo.jpg",
+  mimeType: "image/jpeg",
+});
+
+if (result) {
+  // Provider handled it — result.url is the public URL
+} else {
+  // No provider configured — handle SQL fallback yourself, or skip
+}
+```

package/docs/content/locales/fr-FR/frames.md

@@ -0,0 +1,153 @@
+---
+title: "Cadres"
+description: "Le cadre de développement local, le panneau d'agent intégré et le cadre cloud : la manière dont un agent IA s'exécute aux côtés de votre application."
+---
+
+# Cadres
+
+Chaque application native d'agent s'exécute avec un agent IA à côté de l'application UI. Un **cadre** est
+le wrapper qui héberge les deux : il affiche votre application et donne à l'agent un emplacement pour
+discutez, exécutez et (en développement) modifiez le code. Il existe trois frames partageant un même environnement d'exécution :
+
+- **Panneau d'agent intégré** : livré dans chaque application de `@agent-native/core`.
+  Il s'agit de la barre latérale que votre application affiche elle-même, en développement et en production.
+- **Cadre de développement local** : un wrapper léger qui charge votre application en cours d'exécution dans une iframe
+  et ajoute le même panneau d'agent plus un terminal CLI intégré à côté. Utilisé
+  pour le développement local de modèles dans ce dépôt.
+- **Cadre cloud Builder.io** : un cadre géré et hébergé avec collaboration,
+  édition visuelle et exécutions d'agents parallèles.
+
+Le code de votre application est identique quel que soit le cadre qui l'héberge. L'agent parle
+à votre application via le même actions et le même état d'application dans tous les cas.
+
+```an-diagram title="Three frames, one runtime" summary="Your app and the agent panel are the same in every frame; only the wrapper around them changes."
+{
+  "html": "<div class=\"diagram-frames\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">Embedded panel</span><small class=\"diagram-muted\">ships in every app · dev + prod</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Local dev frame</span><small class=\"diagram-muted\">app in an iframe + panel + CLI terminal</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Builder.io cloud frame</span><small class=\"diagram-muted\">hosted: collaboration · visual edit · parallel runs</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>Same runtime<br><small class=\"diagram-muted\">your app · actions · application state</small></div></div>",
+  "css": ".diagram-frames{display:flex;flex-direction:column;gap:10px;align-items:stretch}.diagram-frames .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.diagram-frames .diagram-arrow{font-size:22px;line-height:1;align-self:center}"
+}
+```
+
+## Panneau d'agent intégré {#embedded-agent}
+
+Le panneau intégré est la barre latérale de l'agent affichée par votre application. Il est livré avec
+`@agent-native/core` — il n'y a pas de package distinct à installer — et c'est le même
+composant en développement et en production.
+
+- Exporté en tant que `AgentPanel` depuis `@agent-native/core/client`, avec un
+  variante de production uniquement `ProductionAgentPanel`.
+- Fournit la surface Chat / CLI / Workspace complète, de sorte que l'entrée de l'agent reste activée
+  la pile de composition partagée utilisée partout ailleurs dans le framework.
+- Lit `application_state.navigation` à chaque tour, donc il sait déjà lequel
+  vue dans laquelle vous vous trouvez et ce qui est sélectionné – vous n'avez pas besoin de réexpliquer "ceci".
+
+### Modes des outils Application et Code {#tool-modes}
+
+Le panneau s'exécute dans l'un des deux modes d'outil :
+
+- **Mode application** — l'agent ne dispose que des outils propres à votre application : le actions vous
+  défini avec `defineAction`, plus navigation et contexte. Pas de système de fichiers ou
+  accès au shell. C'est ce qu'obtiennent les utilisateurs finaux.
+- **Mode Code** : ajoute les outils de codage partagés (`bash`, `read`, `edit`, `write`)
+  et accès à la base de données en plus des outils de l'application, afin que l'agent puisse modifier l'application
+  propre source. Les demandes de code sont fermées : lorsqu'un message nécessite du code
+  (`type: "code"`) et aucun cadre compatible avec le code n'est connecté, le panneau affiche un
+  boîte de dialogue expliquant que les modifications de code nécessitent Agent Native Desktop ou Builder ;
+  Lorsqu'une trame est connectée, la requête est acheminée vers elle et un agent de code
+  l'indicateur s'affiche pendant qu'il fonctionne (`useSendToAgentChat`). Pour le canonique
+  liste des outils de codage et contrats UI partagés, voir
+  [Agent-Native Code UI](/docs/code-agents-ui).
+
+```an-diagram title="Code-request gating" summary="A code-typed message needs a code-capable frame. With one connected, the request routes there; without one, the panel explains code changes need Desktop or Builder."
+{
+  "html": "<div class=\"diagram-gate\"><div class=\"diagram-node\" data-rough>message<br><small class=\"diagram-muted\">type: \\\"code\\\"</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>code-capable frame connected?</div><div class=\"diagram-col\"><div class=\"diagram-pill ok\">yes &rarr; route to frame, show code-agent indicator</div><div class=\"diagram-pill warn\">no &rarr; dialog: needs Desktop or Builder</div></div></div>",
+  "css": ".diagram-gate{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-gate .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-gate .diagram-arrow{font-size:22px;line-height:1}.diagram-gate .center{text-align:center}"
+}
+```
+
+Le « mode Code » est la bascule de capacité de l'agent, distincte du mode développement de l'environnement
+(`NODE_ENV` / Vite). Le hook client est `useCodeMode()`. (Voir
+[Compatibility notes](#compatibility) pour les alias de rétrocompatibilité.)
+
+Dans le cadre de développement local, le rouage des paramètres bascule entre ces modes. Commutation
+Le mode Code désactivé masque la propre barre latérale du cadre et affiche l'agent intégré à l'application
+barre latérale à l'intérieur de l'iframe, afin que vous puissiez prévisualiser exactement ce que voient les utilisateurs finaux.
+
+## Terminal intégré et commutation CLI {#cli-terminal}
+
+En développement, le panneau comprend un terminal intégré (`AgentTerminal`, également
+de `@agent-native/core/client`) soutenu par un serveur PTY. Vous pouvez exécuter un vrai
+codage CLI juste à côté de l'application et basculez entre eux ; le terminal redémarre
+avec le CLI sélectionné.
+
+Les CLI pris en charge proviennent du registre principal CLI
+(`packages/core/src/terminal/cli-registry.ts`). Seules ces commandes sont autorisées
+pour apparaître — le serveur PTY valide la commande demandée par rapport au registre
+liste blanche pour empêcher l'injection :
+
+| CLI         | Commande   | Installer le package        |
+| ----------- | ---------- | --------------------------- |
+| Code Claude | `claude`   | `@anthropic-ai/claude-code` |
+| Builder.io  | `builder`  | (intégré)                   |
+| Codex       | `codex`    | `@openai/codex`             |
+| Gémeaux CLI | `gemini`   | `@google/gemini-cli`        |
+| OpenCode    | `opencode` | `opencode-ai`               |
+
+Si le CLI sélectionné n'est pas trouvé sur `PATH`, le terminal recommence à l'exécuter
+via `npx --yes <install-package>@latest` (là où un package d’installation existe). Le
+la commande par défaut est `claude`. Basculez les CLI à partir des paramètres du panneau d'agent à tout moment
+heure.
+
+## Cadre nuage Builder.io {#cloud-frame}
+
+[Builder.io](https://www.builder.io) fournit un cadre géré qui héberge le
+même application et même panneau d'agent, dans le cloud :
+
+- Collaboration en temps réel : plusieurs utilisateurs peuvent regarder et interagir en même temps.
+- Édition visuelle, rôles et autorisations.
+- Exécution d'agent en parallèle pour une itération plus rapide.
+- Idéal pour une utilisation en équipe, où tout le monde partage un environnement hébergé.
+
+Demandes de code depuis l'itinéraire du panneau intégré vers le cadre Builder de la même manière
+ils sont acheminés vers le cadre de développement local, donc le comportement dev-vs-prod ci-dessus est
+cohérent dans les deux cas.
+
+## Exécution API {#runtime-apis}
+
+Ceux-ci sont livrés avec `@agent-native/core` et sont ce que votre application utilise pour communiquer avec le
+agent, quel que soit le frame qui l'héberge :
+
+1. **Envoyer un message** : `sendToAgentChat()` envoie un message à l'agent. Le
+   Le crochet `useSendToAgentChat()` l'enveloppe avec le déclenchement de demande de code décrit
+   ci-dessus et renvoie un élément `codeRequiredDialog` à restituer. Voir
+   [Drop-in Agent](/docs/drop-in-agent) pour une utilisation complète et des options.
+2. **État de génération** — `useAgentChatGenerating()` suit le moment où l'agent est
+   en cours d'exécution, afin que le UI puisse afficher la progression sans interroger directement l'agent.
+3. **Synchronisation d'interrogation** : la synchronisation basée sur la base de données maintient les caches UI à jour lorsque l'agent
+   modifie les données ou l'état de l'application.
+4. **Système d'action** – `pnpm action <name>` est envoyé au même appelable
+   actions que l'agent appelle comme outils, donc tout ce que l'agent peut faire, vous pouvez le faire
+   script.
+
+## L'exécuter {#running}
+
+Le panneau d'agent intégré fait partie de chaque application : créez un modèle et c'est
+déjà là :
+
+```bash
+npx @agent-native/core@latest create my-app --template mail --standalone
+cd my-app
+pnpm dev
+```
+
+Le cadre de développement local (le package privé `@agent-native/frame` dans le dépôt du framework) est un package d'outils internes qui n'est pas publié sur npm. Il charge le serveur de développement de l'application active dans une iframe et monte le panneau intégré à côté, en sélectionnant l'application via le paramètre de requête `app`. Le terminal CLI intégré nécessite Agent Native Desktop, qui fournit le code local et l'accès PTY aux besoins du terminal ; sans cela, le panneau affiche la surface de discussion et vous invite à ouvrir le bureau pour utiliser le CLI.
+
+## Remarques de compatibilité {#compatibility}
+
+Le concept de "mode Code" était auparavant nommé "mode dev", donc quelques rétro-compatibilités
+les noms persistent. Vous pouvez les ignorer, sauf si vous conservez une intégration plus ancienne
+code :
+
+- La variable d'environnement `AGENT_MODE` sous-jacente, la `/_agent-native/agent-chat/mode`
+  point de terminaison (dont la clé de charge utile est toujours `devMode`) et `agent-chat.mode`
+  la clé des paramètres est inchangée.
+- `useDevMode()` reste un alias obsolète pour `useCodeMode()`.

package/docs/content/locales/fr-FR/getting-started.md

@@ -0,0 +1,199 @@
+---
+title: "Démarrage"
+description: "Créez une application d'agent, comprenez les instructions, skills et actions, puis regardez l'agent appeler sa première action."
+---
+
+# Démarrage
+
+Les applications Agent-Native donnent à un agent IA et à votre UI les mêmes actions, données et
+état. Un agent de base est constitué d'instructions qui le guident, de skills qui lui enseignent
+comportement reproductible et actions qui lui permettent de faire un vrai travail.
+
+**Vous voulez commencer par une application complète ?** Clonez l'un de nos modèles riches –
+[Chat](/docs/template-chat), [Mail](/docs/template-mail),
+[Calendar](/docs/template-calendar), [Content](/docs/template-content),
+[Analytics](/docs/template-analytics) et [many more](/docs/cloneable-saas) —
+chacune une application complète que vous personnalisez.
+
+Construire à partir de zéro ? Le seul choix dès le départ est de savoir si vous voulez un UI —
+tout après (écrire les instructions, ajouter skills, définir actions, exécuter
+l'agent) est le même dans les deux cas.
+
+```an-file-tree title="A basic Agent-Native agent"
+{
+  "entries": [
+    { "path": "AGENTS.md", "note": "always-on instructions: purpose, rules, tone, and the map of what the agent can do" },
+    { "path": ".agents/skills/customer-research/SKILL.md", "note": "a reusable playbook the agent loads when the task matches" },
+    { "path": "actions/summarize-week.ts", "note": "typed code the agent, UI, CLI, HTTP, MCP, A2A, jobs, and webhooks can run" }
+  ]
+}
+```
+
+Cela est vrai que vous commenciez avec un chat UI, un agent sans tête ou une application complète.
+Le UI change la surface ; instructions, skills et actions donnent à l'agent son
+conseils et comportement.
+
+## 1. Créez votre application
+
+Vous aurez besoin de [Node.js 22+](https://nodejs.org) et [pnpm](https://pnpm.io).
+
+Exécutez `create` sans indicateur et il vous demande comment vous souhaitez démarrer (un modèle complet,
+Chat ou Headless) avant toute chose :
+
+```bash
+npx @agent-native/core@latest create my-app
+```
+
+Ou transmettez un indicateur pour ignorer l'invite :
+
+**Vous voulez un UI ?** Commencez à partir du modèle de chat. Vous obtenez un agent actif plus un
+chat personnalisable UI, et chaque action que vous ajoutez y apparaît automatiquement :
+
+```bash
+npx @agent-native/core@latest create my-app --template chat
+```
+
+**Juste la primitive sans tête ?** Démarrer sans tête – les mêmes actions et le même agent
+boucle, pas de shell UI :
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+```
+
+Installez ensuite à partir du dossier que vous avez créé :
+
+```bash
+cd my-agent # or my-app if you chose the Chat template
+pnpm install
+```
+
+À partir de maintenant, les deux sont identiques.
+
+## 2. Ajouter une action
+
+Une action est une opération que votre agent (et votre UI) peut appeler. Les deux échafaudages
+livré avec cet exemple :
+
+```an-annotated-code title="Votre première action"
+{
+  "filename": "actions/hello.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { z } from \"zod\";\n\nexport default defineAction({\n  description: \"Dites bonjour depuis l’agent local.\",\n  schema: z.object({\n    name: z.string().default(\"world\"),\n  }),\n  http: { method: \"GET\" },\n  readOnly: true,\n  run: async ({ name }) => {\n    return { message: `Hello, ${name}!` };\n  },\n});",
+  "annotations": [
+    { "lines": "5", "label": "Description de l’outil", "note": "L’agent lit `description` pour décider quand appeler ceci comme outil." },
+    { "lines": "6-8", "label": "Contrat typé", "note": "Un `schema` zod valide les entrées depuis chaque surface: agent, UI, HTTP, MCP et A2A." },
+    { "lines": "9", "label": "HTTP verb", "note": "Opt this action into an auto-mounted HTTP endpoint." },
+    { "lines": "10", "label": "Read-only", "note": "`readOnly` marks the action as safe to call without approval and cacheable for queries." },
+    { "lines": "11-13", "label": "One implementation", "note": "The `run` body is the single source of truth that every surface executes." }
+  ]
+}
+```
+
+Remplacez `hello` par la première opération réelle dans votre domaine. Vous le définissez une fois ;
+chaque surface le capte.
+
+Utilisez `AGENTS.md` pour obtenir des conseils qui doivent s'appliquer à chaque virage. Utilisez une compétence lorsque le
+l'agent a besoin d'un workflow ou d'une procédure de domaine réutilisable. Utilisez une action lorsque
+l'agent a besoin d'un moyen typé et testable pour lire des données, écrire des données, appeler un API ou
+effectuer une approbation.
+
+## 3. Exécutez-le
+
+Appelez l'action directement :
+
+```bash
+pnpm action hello --name Steve
+```
+
+Ou demandez à l'agent de l'appeler pour vous :
+
+```bash
+pnpm agent "Call the hello action for Steve and explain what happened."
+```
+
+Si vous avez démarré à partir du modèle Chat, exécutez l'application et utilisez le même agent dans le
+navigateur : il peut déjà appeler toutes les actions que vous définissez :
+
+```bash
+pnpm dev
+```
+
+Cette action est désormais accessible depuis le chat UI, les CLI, HTTP, MCP, A2A,
+tâches planifiées et webhooks. Définissez une fois, appelez de n'importe où.
+
+```an-diagram title="One action, every surface" summary="A single defineAction file fans out to every consumer with no extra wiring."
+{
+  "html": "<div class=\"diagram-fan\"><div class=\"diagram-box\" data-rough>defineAction</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-surfaces\"><span class=\"diagram-pill\">Chat UI</span><span class=\"diagram-pill\">CLI</span><span class=\"diagram-pill\">HTTP</span><span class=\"diagram-pill\">MCP</span><span class=\"diagram-pill\">A2A</span><span class=\"diagram-pill\">Scheduled jobs</span><span class=\"diagram-pill\">Webhooks</span></div></div>",
+  "css": ".diagram-fan{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-fan .diagram-surfaces{display:flex;flex-wrap:wrap;gap:8px;max-width:420px}.diagram-fan .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## L'État est intégré
+
+Sans tête ne signifie pas apatride. Actions, sessions, état de l'application, threads,
+l'historique d'exécution et les informations d'identification se trouvent tous dans SQL. Localement, c'est SQLite à
+`data/app.db` ; en production, vous définissez `DATABASE_URL`. Voir
+[Deployment](/docs/deployment).
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Headless is still a real app.** The app-agent loop persists sessions, threads, runs, settings, and credentials in SQL — it is not a stateless prompt. You can add a UI later without touching your actions or state."
+}
+```
+
+## Personnalisez le UI
+
+Si vous avez démarré à partir du modèle Chat, vous pouvez modifier le UI. Le chat lui-même
+est un petit itinéraire construit sur le composant `<AgentChatSurface>` :
+
+```tsx
+// app/routes/_index.tsx
+import { AgentChatSurface } from "@agent-native/core/client";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-full" />;
+}
+```
+
+- **`app/routes/_index.tsx`** — la page de discussion. Modifier les suggestions, vide
+  état et disposition.
+- **`app/root.tsx`** — le shell de l'application. Ajoutez vos propres itinéraires et écrans autour du
+  agent.
+- Déposez l'agent sur n'importe quel écran avec `<AgentSidebar>`, travaillez-y manuellement à partir d'un
+  bouton avec `sendToAgentChat()`, ou exécuter une action directement avec
+  `useActionMutation()`.
+
+Voir [Drop-in Agent](/docs/drop-in-agent) pour l'ensemble complet des composants, et
+[Native Chat UI](/docs/native-chat-ui) pour afficher les résultats des actions sous forme de tableaux,
+des graphiques et des cartes dactylographiées au lieu de texte brut.
+
+**Vous avez commencé sans tête et vous voulez un UI plus tard ?** Le modèle Chat _est_ la rampe d'accès au UI —
+sa couche `app/` (routeur React + Vite) correspond exactement à l'échafaudage sans tête
+laisse de côté. Le geste le plus simple consiste à démarrer (ou à ré-échafauder) à partir du chat
+modèle ; vos états `actions/`, agent et SQL restent inchangés. Voir
+[Agent Surfaces](/docs/agent-surfaces) pour chaque surface intermédiaire.
+
+## Structure du projet
+
+```text
+my-app/
+  actions/         # Agent-callable actions
+  app/             # React frontend (UI templates only; omitted when headless)
+  server/          # Nitro API server (routes, plugins)
+  AGENTS.md        # Always-on agent instructions
+  .agents/         # Skills the agent can pull in when relevant
+  data/app.db      # Local SQLite state when DATABASE_URL is unset
+```
+
+## Où aller ensuite
+
+- **[Key Concepts](/docs/key-concepts)** — l'architecture de base : SQL, actions,
+  synchronisation et prise en compte du contexte.
+- **[Actions](/docs/actions)** — l'action complète API : schémas, HTTP, authentification et
+  approbation.
+- **[Agent Surfaces](/docs/agent-surfaces)** – sans tête, chat, side-car intégré,
+  et application complète.
+- **[Drop-in Agent](/docs/drop-in-agent)** — ajoutez le chat d'agent à n'importe quelle application React.
+- **[Deployment](/docs/deployment)** : placez votre application sur votre propre domaine.
+- **[FAQ](/docs/faq)** — questions sur la configuration et le produit.