@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,183 @@
+---
+title: "Base de données"
+description: "Connectez une base de données SQL portable à votre application native d'agent et écrivez du code Drizzle indépendant du fournisseur."
+---
+
+# Base de données
+
+Les applications natives d'agent utilisent [Drizzle ORM](https://orm.drizzle.team) et prennent en charge les backends SQL portables. Pour tout ce qui va au-delà du développement local, connectez une base de données SQL persistante — Postgres, libSQL/Turso ou un autre backend compatible Drizzle — en définissant `DATABASE_URL`. Lorsque cette variable n'est pas définie, l'application revient à un fichier SQLite local sans configuration afin que vous puissiez commencer à développer immédiatement.
+
+```an-diagram title="One schema, many backends" summary="App code uses the framework's dialect-agnostic helpers. The dialect is auto-detected from DATABASE_URL at runtime; unset means a local SQLite file."
+{
+  "html": "<div class=\"diagram-db\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">@agent-native/core/db/schema</span><small class=\"diagram-muted\">table · text · integer · real · now</small><small class=\"diagram-muted\">+ Drizzle query DSL</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>DATABASE_URL<br><small class=\"diagram-muted\">dialect auto-detected</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">Postgres<br><small class=\"diagram-muted\">Neon · Supabase</small></span><span class=\"diagram-pill\">libSQL / Turso</span><span class=\"diagram-pill\">Cloudflare D1</span><span class=\"diagram-pill warn\">SQLite file<br><small class=\"diagram-muted\">unset = local dev only</small></span></div></div>",
+  "css": ".diagram-db{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-db .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-db .diagram-arrow{font-size:22px;line-height:1}.diagram-db .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}"
+}
+```
+
+## Local par défaut : fichier SQLite {#default-sqlite}
+
+Lorsque `DATABASE_URL` n'est pas défini, l'application crée une base de données SQLite sur `data/app.db`. Il s'agit de la configuration par défaut sans configuration pour le développement local : aucune configuration n'est requise. Il est destiné uniquement au développement ; pour la production, définissez `DATABASE_URL` sur une base de données SQL persistante.
+
+Ne comptez pas sur ce fichier local pour les applications déployées. Les conteneurs, les fonctions sans serveur et les environnements de prévisualisation peuvent réinitialiser leur système de fichiers, ce qui signifie qu'un fichier SQLite local peut disparaître entre les redémarrages. Définissez `DATABASE_URL` sur une base de données hébergée persistante avant utilisation en production.
+
+## Connexion d'une base de données de production {#production}
+
+Définissez `DATABASE_URL` dans votre fichier `.env` ou dans votre environnement de fournisseur de déploiement pour connecter une base de données hébergée. Turso n'est pas obligatoire ; utilisez le backend SQL compatible Drizzle qui correspond à votre déploiement :
+
+```bash
+# Neon Postgres
+DATABASE_URL=postgres://user:pass@ep-cool-name-123456.us-east-2.aws.neon.tech/mydb?sslmode=require
+
+# Supabase Postgres
+DATABASE_URL=postgres://postgres.xxxx:pass@aws-0-us-east-1.pooler.supabase.com:6543/postgres
+
+# Plain Postgres
+DATABASE_URL=postgres://user:pass@localhost:5432/mydb
+
+# Turso (libSQL)
+DATABASE_URL=libsql://my-db-org.turso.io
+DATABASE_AUTH_TOKEN=your-token
+```
+
+Le framework détecte automatiquement le dialecte du URL et configure le Drizzle en conséquence. Les adaptateurs intégrés couvrent les Postgres URL, les libSQL/Turso URL, les fichiers SQLite URL et les liaisons Cloudflare D1. Les choix de production courants incluent Neon, Supabase, Turso/libSQL, Postgres simple, SQLite durable et les environnements gérés par Builder.io lorsqu'ils sont disponibles.
+
+## Base de données gérée Builder.io {#builder-managed}
+
+_Planifié (pas encore disponible) :_ une fois connectée à Builder.io, votre application pourra utiliser une base de données gérée provisionnée automatiquement, sans aucune chaîne de connexion requise.
+
+## Où réside le client de base de données {#db-client}
+
+Chaque modèle crée un client Drizzle paresseux et singleton en appelant `createGetDb(schema)` à partir de `@agent-native/core/db`. L'emplacement canonique est `server/db/index.ts` :
+
+```ts
+// server/db/index.ts
+import { createGetDb } from "@agent-native/core/db";
+import * as schema from "./schema.js";
+
+export const getDb = createGetDb(schema);
+```
+
+Importez `getDb` à partir de ce chemin local de modèle – `../../server/db/index.js` dans les itinéraires, `../server/db/index.js` dans actions – plutôt que directement à partir de `@agent-native/core`. L'exportation principale renvoie une instance générique non typée ; le `getDb()` du modèle contient vos types de schéma. Voir [Server](/docs/server#request-context) pour savoir comment actions et les itinéraires personnalisés l'importent chacun.
+
+## Schéma et requêtes indépendants des dialectes {#schema}
+
+Le code de la base de données de l'application doit utiliser le schéma de Drizzle et interroger DSL afin de pouvoir s'exécuter sur tous les fournisseurs. N'écrivez jamais la syntaxe SQLite uniquement (`INSERT OR REPLACE`, `AUTOINCREMENT`, `datetime('now')`) ou la syntaxe Postgres uniquement dans le code produit.
+
+Utilisez les assistants de schéma du framework de `@agent-native/core/db/schema` :
+
+```ts
+import { table, text, integer, real, now } from "@agent-native/core/db/schema";
+
+export const tasks = table("tasks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  priority: integer("priority").notNull().default(0),
+  weight: real("weight"),
+  done: integer("done", { mode: "boolean" }).notNull().default(false),
+  ownerEmail: text("owner_email").notNull(),
+  createdAt: text("created_at").notNull().default(now()),
+});
+```
+
+| Aide      | Objectif                                                               |
+| --------- | ---------------------------------------------------------------------- |
+| `table`   | Définir une table — délégués à `pgTable` ou `sqliteTable`              |
+| `text`    | Colonne de texte, prend en charge `{ enum: [...] }`                    |
+| `integer` | Colonne entière, `{ mode: "boolean" }` correspond au booléen Postgres  |
+| `real`    | Colonne flottante – `real` sur SQLite, `double precision` sur Postgres |
+| `now`     | Horodatage actuel indépendant du dialecte pour `.default(now())`       |
+
+Le tableau `tasks` ci-dessus définit les mêmes colonnes sur chaque backend :
+
+```an-schema title="The tasks table" summary="Defined once with the framework helpers; the dialect is chosen at runtime from DATABASE_URL."
+{
+  "entities": [
+    {
+      "id": "tasks",
+      "name": "tasks",
+      "note": "Domain table. Add owner_email (or ...ownableColumns()) so SQL-level scoping can filter rows to the authenticated user.",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true, "nullable": false },
+        { "name": "title", "type": "text", "nullable": false },
+        { "name": "priority", "type": "integer", "nullable": false, "note": "default 0" },
+        { "name": "weight", "type": "real", "nullable": true },
+        { "name": "done", "type": "integer (boolean mode)", "nullable": false, "note": "default false; maps to a Postgres boolean" },
+        { "name": "owner_email", "type": "text", "nullable": false, "note": "enables data scoping" },
+        { "name": "created_at", "type": "text", "nullable": false, "note": "default now()" }
+      ]
+    }
+  ]
+}
+```
+
+N'importez jamais directement depuis `drizzle-orm/sqlite-core` ou `drizzle-orm/pg-core`. Utilisez toujours `@agent-native/core/db/schema`.
+
+Les tables qui stockent les données destinées aux utilisateurs doivent inclure une colonne `owner_email` afin que la portée au niveau SQL du framework puisse filtrer les lignes vers l'utilisateur authentifié – voir [Security](/docs/security#data-scoping). Les tables qui prennent également en charge le partage avec d'autres utilisateurs ou organisations doivent plutôt diffuser `...ownableColumns()`, ce qui ajoute `owner_email`, `org_id` et `visibility` en un seul appel – voir [Sharing](/docs/sharing#building).
+
+Pour les lectures et les écritures, utilisez le générateur de requêtes de Drizzle et les opérateurs portables de `drizzle-orm` :
+
+```ts
+import { and, desc, eq } from "drizzle-orm";
+import { getDb } from "../server/db/index.js";
+import { tasks } from "../server/db/schema.js";
+
+const db = getDb();
+
+const openTasks = await db
+  .select()
+  .from(tasks)
+  .where(and(eq(tasks.ownerEmail, userEmail), eq(tasks.done, false)))
+  .orderBy(desc(tasks.createdAt));
+
+await db.update(tasks).set({ done: true }).where(eq(tasks.id, taskId));
+```
+
+## Trappes d'évacuation SQL brutes {#raw-sql}
+
+Raw SQL n'est pas le code d'application par défaut API. Utilisez-le uniquement pour les migrations additives, les contrôles de santé, les requêtes avancées soigneusement examinées que Drizzle ne peut pas exprimer ou la maintenance ponctuelle. Gardez-le paramétré et indépendant du dialecte. Pour les horodatages dans les schémas Drizzle, préférez `.default(now())` ; pour la migration SQL, utilisez `runMigrations()` afin que les réécritures de compatibilité prises en charge par le framework et les instructions contrôlées par dialecte restent centralisées.
+
+Pour les cas où vous avez vraiment besoin de SQL brut en dehors des requêtes Drizzle :
+
+- `getDbExec()` – convertit automatiquement les paramètres `?` en `$1` pour Postgres
+- `isPostgres()` — vérification du dialecte d'exécution
+- `intType()` — renvoie le type entier correct pour le dialecte actuel
+
+## Migrations et mises à jour de schéma {#migrations}
+
+Dans les environnements hébergés, plusieurs aperçus de déploiement, branches et serveur de production partagent la même base de données sous-jacente. Par conséquent, les mises à jour des schémas de base de données doivent respecter des contraintes strictes pour éviter la perte de données et l'interruption du service.
+
+### La règle du « zéro changement destructif »
+
+Toutes les mises à jour du schéma de base de données doivent être **strictement additives**.
+
+- **Ne supprimez pas de tableaux ou de colonnes.**
+- **Ne renommez pas les tables ou les colonnes.** Renommer une colonne ou une table ressemble à une séquence déposer + créer en Drizzle, qui supprimera définitivement vos données de production existantes.
+- Si une colonne doit être renommée ou remplacée, ajoutez la nouvelle colonne à côté de l'ancienne, mettez à jour le code de votre application pour lire/écrire dans les deux, migrez les données et ne retirez l'ancienne colonne dans une version ultérieure que lorsqu'aucun déploiement actif ne la référence.
+
+> [!WARNING]
+> **N'exécutez jamais `drizzle-kit push` sur une base de données de production.**
+> Les schémas de base de données modèles définissent uniquement les tables de domaine spécifiques à l'application ; ils ne définissent pas de tables-cadres centrales (`user`, `session`, `application_state`, etc.). Si vous exécutez `drizzle-kit push` en production, Drizzle détectera ces tables-cadres comme « pas dans le schéma » et tentera de les supprimer, provoquant une panne immédiate à l'échelle du système et une perte de données.
+
+### Chemin de migration sécurisé
+
+Au lieu de pousser directement, les modifications de schéma doivent être appliquées via les migrations SQL exécutées au démarrage de l'application. Implémentez des migrations additives au sein d'un plugin de serveur (par exemple, `server/plugins/db.ts`) en appelant l'assistant `runMigrations()` du framework :
+
+```an-annotated-code title="An additive migration plugin"
+{
+  "filename": "server/plugins/db.ts",
+  "language": "ts",
+  "code": "import { runMigrations } from \"@agent-native/core/db\";\n\nexport default runMigrations(\n  [\n    {\n      version: 1,\n      sql: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS sort_order INTEGER NOT NULL DEFAULT 0`,\n    },\n    {\n      // Dialect-gated: runs only on the matching backend. Omit the other key\n      // to make it a no-op on that dialect.\n      version: 2,\n      sql: {\n        postgres: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS tsv tsvector`,\n        sqlite: `SELECT 1`, // no-op; tsvector is Postgres-only\n      },\n    },\n  ],\n  { table: \"my_app_migrations\" },\n);",
+  "annotations": [
+    { "lines": "6-7", "label": "Additive only", "note": "`ADD COLUMN IF NOT EXISTS` is safe to re-run and never drops data. Renames look like drop+create to Drizzle, so add-then-migrate instead." },
+    { "lines": "13-16", "label": "Dialect gating", "note": "Pass an object keyed by dialect to run different SQL per backend. Make the other key a no-op (`SELECT 1`) for Postgres-only or SQLite-only features." },
+    { "lines": "19", "label": "Per-app version table", "note": "Each app tracks its own applied versions so migrations are idempotent across restarts and instances." }
+  ]
+}
+```
+
+## Variables d'environnement {#environment-variables}
+
+| Variable              | Objectif                                                                                                            |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `DATABASE_URL`        | Chaîne de connexion SQL persistante (non définie = SQLite local, qui n'est durable que pour le développement local) |
+| `DATABASE_AUTH_TOKEN` | Jeton d'authentification pour les fournisseurs qui nécessitent un jeton distinct, tel que Turso/libSQL              |

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

@@ -0,0 +1,349 @@
+---
+title: "Déploiement"
+description: "Déployez des applications natives d'agent sur n'importe quelle plate-forme avec les préréglages Nitro : Node.js, Vercel, Netlify, Cloudflare, AWS, et plus encore."
+---
+
+# Déploiement
+
+Les applications natives d'agent utilisent [Nitro](https://nitro.build) sous le capot, ce qui signifie que vous pouvez les déployer sur n'importe quelle plate-forme sans aucune modification de configuration : il vous suffit de définir un préréglage.
+
+## Avant de déployer : choisissez une base de données persistante {#persistent-database}
+
+Chaque application déployée nécessite une base de données SQL persistante. Dans le développement local, l'agent natif s'appuie sur un fichier SQLite dans `data/app.db` ; c'est pratique sur votre machine, mais ce n'est pas durable dans les conteneurs, les aperçus ou les environnements sans serveur où le système de fichiers peut être réinitialisé.
+
+Définissez `DATABASE_URL` dans votre fournisseur de déploiement avant de promouvoir une application en production. Agent-native utilise Drizzle pour le schéma et les requêtes, de sorte que la couche de données est portable sur les backends SQL compatibles Drizzle et que le framework détecte automatiquement le dialecte du URL. Voir [Database](/docs/database#production) pour la liste des adaptateurs et les détails du dialecte.
+
+Utilisez `DATABASE_AUTH_TOKEN` uniquement lorsque votre fournisseur de base de données nécessite un jeton distinct, tel que Turso/libSQL. Pour les espaces de travail, toutes les applications héritent par défaut de la racine `DATABASE_URL` ; définissez `<APP_NAME>_DATABASE_URL` lorsqu'une application doit utiliser une base de données différente.
+
+## Déploiement de Workspace : une origine, de nombreuses applications {#workspace-deploy}
+
+Si votre projet est un [workspace](/docs/multi-app-workspace), vous pouvez envoyer chaque application qu'il contient à une seule origine avec une seule commande :
+
+```bash
+npx @agent-native/core@latest deploy
+# https://your-agents.com/mail/*       → apps/mail
+# https://your-agents.com/calendar/*   → apps/calendar
+# https://your-agents.com/forms/*      → apps/forms
+```
+
+Chaque application est construite avec `APP_BASE_PATH=/<name>` et `VITE_APP_BASE_PATH=/<name>`, puis packagée pour le préréglage cible Nitro. Cloudflare Pages est le préréglage par défaut et utilise un répartiteur généré sur `dist/_worker.js` ; Netlify utilise une fonction par application dans `.netlify/functions-internal/<app>-server` ainsi que les redirections générées ; Vercel écrit un `.vercel/output` au niveau de l'espace de travail à l'aide de la sortie de construction API.
+
+```an-diagram title="One origin, many apps" summary="Each workspace app is built with its own base path and mounted under a path prefix on a single origin — so login and cross-app A2A are same-origin and free."
+{
+  "html": "<div class=\"diagram-ws\"><div class=\"diagram-panel\" data-rough><strong>https://your-agents.com</strong><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/mail/*</span><small class=\"diagram-muted\">apps/mail</small></div><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/calendar/*</span><small class=\"diagram-muted\">apps/calendar</small></div><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/forms/*</span><small class=\"diagram-muted\">apps/forms</small></div></div><div class=\"diagram-col wins\"><span class=\"diagram-pill ok\">shared login session</span><span class=\"diagram-pill ok\">zero-config cross-app A2A</span></div></div>",
+  "css": ".diagram-ws{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.diagram-ws .diagram-panel{display:flex;flex-direction:column;gap:6px;padding:14px 16px}.diagram-ws .diagram-row{display:flex;align-items:center;gap:8px}.diagram-ws .wins{display:flex;flex-direction:column;gap:8px;align-items:flex-start}"
+}
+```
+
+Le déploiement de même origine vous offre deux gros gains gratuits :
+
+- **Session de connexion partagée** : connectez-vous à n'importe quelle application, chaque application est connectée.
+- **A2A inter-applications sans configuration** — le marquage de `@calendar` à partir du courrier est une récupération de même origine ; pas de signature CORS, pas de JWT entre frères et sœurs.
+
+Publiez le résultat avec :
+
+```bash
+wrangler pages deploy dist
+```
+
+Pour les déploiements unifiés Netlify, utilisez le préréglage Netlify :
+
+```bash
+npx @agent-native/core@latest deploy --preset netlify
+```
+
+Pour les déploiements unifiés Vercel, utilisez le préréglage Vercel :
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel
+```
+
+Lors de la configuration d'une commande de build de fournisseur, utilisez la même commande avec `--build-only`. Vercel devrait exécuter `npx @agent-native/core@latest deploy --preset vercel --build-only` ; la commande écrit directement `.vercel/output`, donc aucun `vercel.json` n'est requis pour le routage de l'espace de travail.
+
+Les builds d'espace de travail hébergé nécessitent `A2A_SECRET` dans l'environnement du fournisseur de déploiement.
+Cela permet aux Slack, aux webhooks entrants et aux A2A inter-applications de reprendre leur travail via une signature
+processeurs d'arrière-plan. Les vérifications locales des artefacts `--build-only` s'exécutent toujours sans celui-ci.
+
+Le déploiement indépendant par application est toujours pris en charge – juste `cd apps/<name> && npx @agent-native/core@latest build` comme un échafaudage autonome.
+
+## Comment ça marche {#how-it-works}
+
+Lorsque vous exécutez `npx @agent-native/core@latest build`, Nitro crée à la fois le client SPA et le serveur API dans `.output/` :
+
+```an-file-tree title="Build output"
+{
+  "entries": [
+    { "path": ".output/", "note": "self-contained — copy to any environment and run" },
+    { "path": ".output/public/", "note": "built SPA (static assets)" },
+    { "path": ".output/server/index.mjs", "note": "server entry point" },
+    { "path": ".output/server/chunks/", "note": "server code chunks" }
+  ]
+}
+```
+
+La sortie est autonome : copiez `.output/` dans n'importe quel environnement et exécutez-le.
+
+```an-diagram title="Build to deploy" summary="One source tree builds to a Nitro preset; the same self-contained output runs on Node, Vercel, Netlify, Cloudflare, AWS, or Deno. Every instance points at the same persistent DATABASE_URL."
+{
+  "html": "<div class=\"diagram-deploy\"><div class=\"diagram-box\" data-rough>App source</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">build</span><small class=\"diagram-muted\">Nitro preset</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">Node.js</span><span class=\"diagram-pill\">Vercel</span><span class=\"diagram-pill\">Netlify</span><span class=\"diagram-pill\">Cloudflare</span><span class=\"diagram-pill\">AWS Lambda</span><span class=\"diagram-pill\">Deno</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Persistent DATABASE_URL<br><small class=\"diagram-muted\">shared by every instance</small></div></div>",
+  "css": ".diagram-deploy{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-deploy .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-deploy .diagram-arrow{font-size:22px;line-height:1}.diagram-deploy .diagram-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:8px}"
+}
+```
+
+## Définition du préréglage {#setting-the-preset}
+
+Par défaut, Nitro est construit pour Node.js. Pour cibler une autre plate-forme, définissez le préréglage dans votre `vite.config.ts` :
+
+```ts
+import { defineConfig } from "@agent-native/core/vite";
+
+export default defineConfig({
+  nitro: {
+    preset: "vercel",
+  },
+});
+```
+
+Ou utilisez la variable d'environnement `NITRO_PRESET` au moment de la construction :
+
+```bash
+NITRO_PRESET=netlify npx @agent-native/core@latest build
+```
+
+## Node.js (par défaut) {#nodejs}
+
+Le préréglage par défaut. Créer et exécuter :
+
+```bash
+npx @agent-native/core@latest build
+node .output/server/index.mjs
+```
+
+Définissez `PORT` pour configurer le port d'écoute (par défaut : `3000`).
+
+Utilisez la gamme Node.js LTS actuelle pour les déploiements en production. Depuis mai 2026,
+est Node.js 24 ; Le Node.js 20 est arrivé en fin de vie le 30 avril 2026 et non plus
+reçoit des mises à jour de sécurité en amont.
+
+### Docker {#docker}
+
+```dockerfile
+FROM node:24-slim AS build
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm build
+
+FROM node:24-slim
+WORKDIR /app
+COPY --from=build /app/.output .output
+# data/ is a runtime-created SQLite directory — do not copy a dev DB into prod.
+# For production, set DATABASE_URL to a hosted Postgres or Turso instance.
+RUN mkdir -p /app/data
+ENV PORT=3000
+EXPOSE 3000
+CMD ["node", ".output/server/index.mjs"]
+```
+
+## Vercel {#vercel}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "vercel" },
+});
+```
+
+Déployez via Vercel CLI ou git push :
+
+```bash
+vercel deploy
+```
+
+Pour un espace de travail, créez chaque application dans un seul bundle Vercel Build Output API :
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel
+```
+
+Pour les déploiements Vercel Git, définissez la commande build sur :
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel --build-only
+```
+
+La version de l'espace de travail copie la sortie Nitro `vercel` de chaque application dans la racine `.vercel/output`, attribue à chaque fonction son propre environnement de chemin de montage et écrit la configuration de route qui dessert les applications sur `/<app-id>`.
+
+## Netlify {#netlify}
+
+Le préréglage Nitro `netlify` fonctionne bien et, en pratique, nous a permis des démarrages à froid beaucoup plus rapides que les pages Cloudflare (~ 200 ms TTFB contre ~ 9 s) pour les modèles qui communiquent avec un Postgres externe (Neon). Soit définir le préréglage dans `vite.config.ts` :
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "netlify" },
+});
+```
+
+…ou définissez `NITRO_PRESET=netlify` au moment de la construction.
+
+Pour un espace de travail, déployez chaque application à partir d'un site Netlify en exécutant :
+
+```bash
+npx @agent-native/core@latest deploy --preset netlify
+```
+
+La version de l'espace de travail écrit les ressources statiques sous `dist/_workspace_static/` et achemine chaque application vers sa propre fonction Netlify sans redirection forcée des ressources, de sorte que les fichiers comme `/mail/assets/...` sont servis de manière statique avant que la fonction serveur ne gère les routes des applications.
+
+## Pages Cloudflare {#cloudflare-pages}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "cloudflare_pages" },
+});
+```
+
+## AWS Lambda {#aws-lambda}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "aws_lambda" },
+});
+```
+
+## Déploiement Deno {#deno-deploy}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "deno_deploy" },
+});
+```
+
+## Variables d'environnement {#environment-variables}
+
+### Construction/Exécution {#env-runtime}
+
+| Variable                    | Description                                                                                                                                                             |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PORT`                      | Port du serveur (Node.js uniquement)                                                                                                                                    |
+| `NITRO_PRESET`              | Remplacer le préréglage de build au moment de la build                                                                                                                  |
+| `APP_BASE_PATH`             | Montez l'application sous un préfixe (par exemple `/mail`). Réglé automatiquement par `npx @agent-native/core@latest deploy` ; laissez-le désactivé pour être autonome. |
+| `AGENT_PROD_CODE_EXECUTION` | Mode d'exécution du code de production facultatif : `off` (par défaut), `sandboxed` ou `trusted`. Voir [Production Code Execution](#production-code-execution).         |
+
+Les variables de connexion à la base de données (`DATABASE_URL`, `DATABASE_AUTH_TOKEN`, `<APP_NAME>_DATABASE_URL` par application) résident dans [Database](/docs/database#production).
+
+### Obligatoire en production {#env-required-prod}
+
+Ceux-ci doivent être définis avant de promouvoir une application vers un véritable déploiement de production. Les valeurs manquantes sont soit fermées par échec (le framework refuse de démarrer/refuse de traiter les requêtes), soit reviennent à un comportement plus faible avec un avertissement fort.
+
+| Variable                 | Description                                                                                                                                                                                                                                                                                                          |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET`     | Chaîne aléatoire de plus de 32 caractères. Cookies de session de signalisation AND est la solution de secours HMAC pour `OAUTH_STATE_SECRET` et `SECRETS_ENCRYPTION_KEY`. Obligatoire : le framework se lance au démarrage s'il est manquant en production.                                                          |
+| `BETTER_AUTH_URL`        | Origine publique de cette application (par exemple `https://mail.example.com`). Utilisé pour le domaine de cookie et la construction de redirection OAuth.                                                                                                                                                           |
+| `ANTHROPIC_API_KEY`      | Clé API pour l'agent de production intégré. **Dans les déploiements multi-locataires**, le framework refuse de revenir à cela lorsque l'utilisateur ne dispose pas de clé par utilisateur : apporter votre propre clé est requis. Les installations auto-hébergées à locataire unique l'utilisent comme clé globale. |
+| `OAUTH_STATE_SECRET`     | Clé HMAC dédiée aux enveloppes d'état OAuth (Google, Atlassian, Zoom). Revient à `BETTER_AUTH_SECRET` lorsqu'il n'est pas défini, mais une valeur dédiée est recommandée afin que la rotation de l'une n'invalide pas l'autre. Générer via `openssl rand -hex 32`.                                                   |
+| `A2A_SECRET`             | HMAC partagé pour A2A JSON-RPC inter-applications. Sans cela, chaque point de terminaison A2A et le point de terminaison à déclenchement automatique `/_agent-native/integrations/process-task` renvoient 503 en production.                                                                                         |
+| `SECRETS_ENCRYPTION_KEY` | Clé AES-256-GCM pour le coffre-fort de secrets chiffrés au repos. Revient à `BETTER_AUTH_SECRET`. Échec brutal en production lorsque les deux ne sont pas définis.                                                                                                                                                   |
+
+### Authentification et identité {#env-auth}
+
+Les informations d'identification du fournisseur OAuth (Google, GitHub), les solutions de secours du support MCP statiques (`ACCESS_TOKEN` / `ACCESS_TOKENS`) et les bascules de vérification des e-mails sont documentées dans [Authentication](/docs/authentication). Définissez-les ici selon le mode d'authentification que vous choisissez.
+
+### Entrant Webhooks {#env-webhooks}
+
+Chaque intégration de messagerie nécessite son propre secret de signature en production (les gestionnaires échouent en cas de requêtes falsifiées lorsque le secret est manquant). Les variables par intégration sont répertoriées dans [Messaging](/docs/messaging) et [Security](/docs/security). Pour le développement local uniquement, `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS=1` revient sur « avertir et accepter » – ne le définissez jamais en production.
+
+### Configuration de la sécurité (adhésion) {#security-config}
+
+Les valeurs par défaut sont strictes. Une poignée d'indicateurs d'adhésion assouplissent le comportement (traces de pile de débogage, webhooks non vérifié, secours de clé à l'échelle de l'espace de travail, commutateur multi-organisation du hub MCP, écritures de la variable d'environnement d'exécution). Ils sont documentés avec leurs compromis en matière de sécurité dans [Security](/docs/security). Ne les définissez pas à moins que vous souhaitiez spécifiquement le chemin détendu.
+
+### Héritage .env de l'espace de travail {#env-inheritance}
+
+Dans un espace de travail, la racine `.env` est chargée automatiquement dans chaque application, de sorte que les clés partagées telles que `ANTHROPIC_API_KEY`, `A2A_SECRET`, `BETTER_AUTH_SECRET` et `OAUTH_STATE_SECRET` ne doivent être définies qu'une seule fois. `apps/<name>/.env` par application gagne en cas de conflit.
+
+### Générer des secrets puissants {#env-generate-secrets}
+
+Pour tout secret marqué « 32+ caractères aléatoires » (`BETTER_AUTH_SECRET`, `OAUTH_STATE_SECRET`, `A2A_SECRET`, `SECRETS_ENCRYPTION_KEY`), générez de nouvelles valeurs avec :
+
+```bash
+openssl rand -hex 32
+```
+
+Faites-les pivoter en remplaçant la variable d'environnement sur chaque instance et en redéployant : les enveloppes d'état des sessions/OAuth signées sous l'ancienne clé deviennent invalides, les utilisateurs devront donc peut-être se reconnecter.
+
+## 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 :
+
+```ts
+// server/plugins/agent-chat.ts
+export default createAgentChatPlugin({
+  // Default: "write" (also true)
+  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: "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
+  guides rapides (`create-extension`, `update-extension`, etc.) pour les applications qui
+  ne souhaitez pas que l'agent crée des mini-applications en bac à sable.
+
+## Exécution du code de production {#production-code-execution}
+
+Par défaut, les agents de production s'exécutent sans outils d'exécution de code. Ils peuvent appeler l'application actions, les outils de base de données, les outils MCP, les outils de navigateur/session et d'autres outils de framework enregistrés, mais ils n'ont pas accès au shell ou au système de fichiers.
+
+Les déploiements compatibles avec les nœuds peuvent opter pour l'exécution du code de production via le plug-in de chat d'agent ou un remplacement d'environnement :
+
+```ts
+// server/plugins/agent-chat.ts
+export default createAgentChatPlugin({
+  codeExecution: { production: "sandboxed" },
+});
+```
+
+Les modes disponibles sont :
+
+- `off` — valeur par défaut. Aucun outil d'exécution de code n'est enregistré en production.
+- `sandboxed` : enregistre `run-code`, un exécuteur Node.js JavaScript isolé avec un environnement épuré, un nouveau répertoire temporaire, des limites de sortie/durée et un pont d'hôte local pour les outils enregistrés sur liste autorisée tels que `provider-api-request`, `provider-api-docs`, `provider-api-catalog`, `web-request` et le pont de fichiers d'espace de travail basé sur les ressources utilisé par `workspaceRead` / `workspaceWrite`.
+- `trusted` : enregistre `run-code` ainsi que le registre complet de l'outil de codage (`bash`, `read`, `edit`, `write`). Utilisez-le uniquement pour les déploiements à locataire unique ou contrôlés par un opérateur où l'accès complet du shell à l'hôte est intentionnel.
+
+Définissez `AGENT_PROD_CODE_EXECUTION=sandboxed` ou `AGENT_PROD_CODE_EXECUTION=trusted` pour remplacer l'option du plug-in pour un déploiement spécifique sans modification du code. `AGENT_PROD_CODE_EXECUTION=off` force l'exécution du code même lorsque l'option du plugin l'active.
+
+Le bac à sable `run-code` est une isolation au niveau du processus, pas un conteneur de système d'exploitation. Il supprime les secrets d'application de l'environnement de processus enfant et utilise le modèle d'autorisation Node lorsqu'il est disponible, mais le réseau sortant n'est pas bloqué par Node lui-même ; les appels authentifiés doivent passer par les assistants de pont exposés par l'outil.
+
+## Mise à jour de UI en production {#updating-ui-in-production}
+
+L'une des fonctionnalités principales de l'agent natif est que l'agent peut modifier le code source de votre application : composants, itinéraires, styles, actions. Pendant le développement local, cela fonctionne de manière transparente car l'agent dispose d'un accès complet au système de fichiers.
+
+Dans un déploiement de production standard sans [production code execution](#production-code-execution), l'agent a accès aux outils de l'application (actions, base de données, MCP) mais pas au système de fichiers. Cela signifie que l'agent peut lire et écrire des données, exécuter actions et interagir avec des services externes, mais il ne peut pas modifier vos composants React ni ajouter de nouvelles routes sur une instance déployée.
+
+### Builder.io : Édition visuelle en production {#builderio}
+
+[Builder.io](https://www.builder.io) résout ce problème en fournissant un environnement cloud géré dans lequel l'agent conserve la possibilité de modifier le UI de votre application en production. Connectez votre dépôt à Builder.io et demandez directement les modifications de UI – aucun redéploiement n'est nécessaire.
+
+**Comment ça marche :**
+
+1. Connectez votre dépôt natif d'agent à Builder.io
+2. Builder.io fournit un cadre cloud avec l'agent, l'édition visuelle et la collaboration en temps réel
+3. Inviter l'agent à apporter des modifications à UI : il modifie vos composants, itinéraires et styles en direct
+4. Les modifications sont validées dans votre dépôt
+
+Voir [Frames](/docs/frames) pour en savoir plus sur le panneau d'agent intégré et les options de cadre cloud.
+
+## Déploiements multi-instances {#multi-instance}
+
+Les applications natives d'agent stockent tous les états dans SQL via Drizzle et synchronisent le UI via [polling](/docs/key-concepts#polling-sync) avec la base de données : pas d'état du système de fichiers, pas de sessions persistantes, pas de caches en mémoire. Cela signifie que les déploiements multi-instances et sans serveur fonctionnent immédiatement : pointez chaque instance vers le même `DATABASE_URL` et elles convergent automatiquement. Voir [Key Concepts — Data in SQL](/docs/key-concepts#data-in-sql) et [Portability](/docs/key-concepts#hosting-agnostic).