@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/fr-FR/creating-templates.md

@@ -0,0 +1,411 @@
+---
+title: "Création de modèles"
+description: "Comment créer et publier vos propres modèles d'applications natives pour agents."
+---
+
+# Création de modèles
+
+Les modèles sont des applications natives d'agent complètes et exploitables qui résolvent un véritable flux de travail. Les modèles propriétaires sont créés avec la même surface de structure que vous utilisez : routes React pour le UI, Drizzle SQL pour les données, actions pour les opérations, ressources d'espace de travail pour le comportement de l'agent et synchronisation des interrogations afin que l'agent et le UI restent alignés.
+
+Un bon modèle :
+
+- Résout un flux de travail de bout en bout, avec des données de départ utiles ou un flux à état vide.
+- Stocke l'état durable dans les fichiers SQL, pas dans les fichiers JSON.
+- Définit les opérations de l'application comme `defineAction()` actions.
+- Expose la navigation et la sélection via l'état de l'application.
+- Expédie un `AGENTS.md` clair et un skills ciblé pour les flux de travail non évidents.
+- Enregistre les étapes d'intégration pour les fournisseurs et les secrets requis.
+- Fonctionne comme une application autonome et dans le cadre d'un espace de travail multi-applications.
+
+## Commencer à partir du chat {#start-from-chat}
+
+Utilisez le modèle Chat lorsque vous souhaitez une application minimale avec le câblage du framework déjà en place :
+
+```bash
+npx @agent-native/core@latest create my-template --template chat --standalone
+```
+
+Pour un espace de travail avec plusieurs applications, exécutez le sélecteur et incluez Chat avec les modèles de domaine de votre choix :
+
+```bash
+npx @agent-native/core@latest create my-platform
+```
+
+Chat vous offre une authentification, des fils de discussion durables, des ressources soutenues par SQL, des outils, l'état de l'application, actions et la synchronisation des sondages. Vous ajoutez le modèle de domaine et le produit UI.
+
+Si vous ne créez pas encore de modèle UI réutilisable, utilisez la rampe d'accès sans tête dans [Getting Started](/docs/getting-started#1-create-your-app) : définissez une action, exécutez-la avec `pnpm agent` et ajoutez UI plus tard lorsque le flux de travail a besoin d'une surface durable.
+
+## Structure du projet {#project-structure}
+
+Chaque modèle suit la même présentation générale :
+
+```an-file-tree title="Template project layout"
+{
+  "title": "my-template/",
+  "entries": [
+    { "path": "app/", "note": "React frontend" },
+    { "path": "app/root.tsx", "note": "HTML shell and providers" },
+    { "path": "app/routes/", "note": "React Router file routes" },
+    { "path": "app/components/", "note": "Template UI" },
+    { "path": "app/hooks/", "note": "UI state and data hooks" },
+    { "path": "actions/", "note": "defineAction operations — the single source of truth" },
+    { "path": "server/db/schema.ts", "note": "Drizzle schema" },
+    { "path": "server/plugins/db.ts", "note": "additive migrations" },
+    { "path": "server/plugins/", "note": "startup integrations" },
+    { "path": "server/routes/api/", "note": "custom routes only when actions are not enough" },
+    { "path": "shared/types.ts", "note": "shared client/server types" },
+    { "path": ".agents/skills/", "note": "<skill>/SKILL.md — agent guidance for complex workflows" },
+    { "path": "AGENTS.md", "note": "template-specific agent instructions" },
+    { "path": "package.json" },
+    { "path": "react-router.config.ts" },
+    { "path": "vite.config.ts" }
+  ]
+}
+```
+
+N'ajoutez pas de répertoire `data/` pour l'état de l'application. Les données d'application durables appartiennent à SQL, et le UI les lit via actions ou des gestionnaires de serveur typés.
+
+Les quatre zones de chaque modèle s'articulent via une surface d'action partagée et une base de données SQL : l'agent et le UI sont des partenaires égaux pour les mêmes opérations :
+
+```an-diagram title="How a template's four areas connect" summary="The UI and the agent both reach SQL through the same actions; application state and polling sync keep them aligned."
+{
+  "html": "<div class=\"diagram-tmpl\"><div class=\"diagram-col\"><div class=\"diagram-node\">React UI<br><small class=\"diagram-muted\">app/routes · components</small></div><div class=\"diagram-node\">Agent<br><small class=\"diagram-muted\">AGENTS.md · skills</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">defineAction()</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>SQL via Drizzle<br><small class=\"diagram-muted\">additive schema</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">Polling sync</div></div>",
+  "css": ".diagram-tmpl{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-tmpl .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-tmpl .diagram-arrow{font-size:22px;line-height:1}.diagram-tmpl .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Données du modèle dans SQL {#data-models}
+
+Définissez des tables de domaines avec les assistants du framework Drizzle afin que les schémas restent portables sur SQLite, Postgres, D1, Turso, Supabase, Neon et d'autres backends pris en charge :
+
+```ts
+// server/db/schema.ts
+import {
+  table,
+  text,
+  integer,
+  now,
+  ownableColumns,
+  createSharesTable,
+} from "@agent-native/core/db/schema";
+
+export const projects = table("projects", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  status: text("status", {
+    enum: ["draft", "active", "archived"],
+  })
+    .notNull()
+    .default("draft"),
+  sortOrder: integer("sort_order").notNull().default(0),
+  ...ownableColumns(),
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+});
+
+export const projectShares = createSharesTable("project_shares");
+```
+
+Les modifications du schéma doivent être additives. Ajoutez des tables et des colonnes via `runMigrations()` dans `server/plugins/db.ts` ; n'utilisez jamais de SQL, `drizzle-kit push` destructeurs, des renommages de tables ou des suppressions de colonnes.
+
+Pour les lectures et écritures d'applications, utilisez le générateur de requêtes de Drizzle et les opérateurs portables de `drizzle-orm`. N'écrivez pas de code produit avec SQL brut lorsque Drizzle peut exprimer la requête, et n'importez pas depuis `drizzle-orm/sqlite-core` ou `drizzle-orm/pg-core` dans des modèles.
+
+```ts
+// server/plugins/db.ts
+import { runMigrations } from "@agent-native/core/db";
+
+export default runMigrations(
+  [
+    {
+      version: 1,
+      sql: `CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'draft',
+      sort_order INTEGER NOT NULL DEFAULT 0,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      visibility TEXT NOT NULL DEFAULT 'private',
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    )`,
+    },
+  ],
+  { table: "my_app_migrations" },
+);
+```
+
+Utilisez les documents [Database](/docs/database) et [Security](/docs/security) avant d'ajouter des schémas contenant des données utilisateur ou organisationnelles.
+
+## Définir les opérations comme Actions {#actions}
+
+Actions est la source unique de vérité sur le comportement des applications. L'agent les appelle en tant qu'outils, le frontend les appelle via des hooks et d'autres applications peuvent les atteindre via MCP/A2A.
+
+```an-annotated-code title="actions/create-project.ts"
+{
+  "filename": "actions/create-project.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { getDb } from \"../server/db/index.js\";\nimport { nanoid } from \"nanoid\";\nimport { z } from \"zod\";\nimport * as schema from \"../server/db/schema\";\n\nexport default defineAction({\n  description: \"Create a project.\",\n  schema: z.object({\n    title: z.string().min(1).describe(\"Project title\"),\n  }),\n  run: async ({ title }, ctx) => {\n    const db = getDb();\n    const id = nanoid();\n    await db.insert(schema.projects).values({\n      id,\n      title,\n      ownerEmail: ctx.userEmail,\n      orgId: ctx.orgId,\n    });\n    return { id, title };\n  },\n});",
+  "annotations": [
+    { "lines": "2", "note": "`getDb` is created per app via `createGetDb(schema)` in `server/db/index.ts`." },
+    { "lines": "8", "label": "Tool surface", "note": "The `description` is what the agent reads to decide when to call this action as a tool." },
+    { "lines": "9-11", "label": "Contrat typé", "note": "One zod `schema` validates input from the agent, the UI, HTTP, MCP, and A2A." },
+    { "lines": "18-19", "label": "Scoped write", "note": "Stamp `ownerEmail` / `orgId` from `ctx` so the row is correctly scoped for sharing and access checks." }
+  ]
+}
+```
+
+Utilisez `http: { method: "GET" }` ou `readOnly: true` pour actions en lecture seule. Utilisez `parallelSafe: true` uniquement pour la mutation de actions qui peut être exécutée en toute sécurité simultanément avec des appels d'outils au même tour. Utilisez `toolCallable: false` pour le actions à rayon de souffle élevé qui ne doit pas être exécuté à partir d'outils en bac à sable.
+
+## Construisez le UI {#ui}
+
+Les itinéraires résident dans `app/routes/` et utilisent le routage de fichiers React Router v7. Interrogez les données via les gestionnaires actions ou API et rendez les mutations optimistes par défaut.
+
+```tsx
+import { useActionMutation, useActionQuery } from "@agent-native/core/client";
+
+export default function ProjectsPage() {
+  const { data: projects = [] } = useActionQuery("list-projects", {});
+  const create = useActionMutation("create-project");
+
+  return (
+    <button onClick={() => create.mutate({ title: "Launch plan" })}>
+      New project ({projects.length})
+    </button>
+  );
+}
+```
+
+Câblez la synchronisation en direct une fois à proximité du shell de l'application afin que les caches de requête React s'actualisent lorsque l'agent, un autre onglet ou une action modifie les données :
+
+```tsx
+import { useDbSync } from "@agent-native/core/client";
+import { useQueryClient } from "@tanstack/react-query";
+
+export function AppSync() {
+  const queryClient = useQueryClient();
+  useDbSync({ queryClient });
+  return null;
+}
+```
+
+**La promesse native de l'agent : les écritures de l'agent s'affichent dans le UI sans actualisation manuelle.** `useActionQuery` est la voie la plus simple : chaque hook est récupéré lorsqu'une action de mutation émet `source: "action"`. Si vous accédez au `useQuery` brut avec une clé personnalisée (par exemple, un assistant client de bas niveau qui lit l'état d'intégration), insérez le compteur par source dans la clé de requête pour des actualisations ciblées :
+
+```tsx
+import { useChangeVersions } from "@agent-native/core/client";
+
+const v = useChangeVersions(["dashboards", "action"]);
+useQuery({
+  queryKey: ["dashboard", id, v],
+  queryFn: () => fetchDashboard(id),
+  placeholderData: (prev) => prev, // no flicker on refetch
+});
+```
+
+Sources courantes : `"action"` (chaque action d'agent réussie – la solution de secours fiable), `"app-state"`, `"settings"`, ainsi que toute source de ressources personnalisée émise par votre boutique via `recordChange`. Voir la compétence `real-time-sync` pour le modèle complet.
+
+## Ajouter un état d'application {#application-state}
+
+L'état de l'application indique comment l'agent sait ce que l'utilisateur voit. Au minimum, ajoutez :
+
+- Un hook UI qui écrit l'état sémantique `navigation` lorsque les itinéraires, les enregistrements sélectionnés, les onglets actifs ou les sélections de l'éditeur changent.
+- Une action `view-screen` qui lit cet état et renvoie la capture d'écran actuelle.
+- Une action `navigate` qui écrit une commande `navigate` unique à consommer par le UI.
+
+Utilisez `useAgentRouteState` pour le hook UI afin que les écritures dans l'état de l'application, les lectures de commandes par tabulation, la suppression après lecture et la protection contre les commandes en double restent cohérentes :
+
+```tsx
+import { useAgentRouteState } from "@agent-native/core/client";
+import { TAB_ID } from "@/lib/tab-id";
+
+export function useNavigationState() {
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view: pathname === "/" ? "home" : pathname.slice(1),
+      selectedId: searchParams.get("id"),
+    }),
+    getCommandPath: (command: any) => command.path ?? "/",
+    navigateOptions: { replace: true, flushSync: true },
+  });
+}
+```
+
+Conserver les filtres partageables dans les paramètres de requête URL. Le framework les expose à l'agent sous le nom `<current-url>` et l'agent intégré peut les modifier avec `set-search-params` ; `navigation` doit contenir les ID sémantiques et les alias, et non une deuxième copie de la chaîne de requête complète.
+
+Pour la navigation dans les applications, préférez une commande `navigate` incluant une commande de même origine
+`path` lorsque le URL est connu. N'écrivez pas également `__set_url__` pour le même coup ;
+cette clé est réservée aux outils du framework URL et aux modifications de filtre URL uniquement.
+
+```ts
+// actions/navigate.ts
+import { defineAction } from "@agent-native/core/action";
+import { writeAppState } from "@agent-native/core/application-state";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Navigate the UI.",
+  schema: z.object({
+    view: z.enum(["home", "project"]),
+    projectId: z.string().optional(),
+    path: z.string().optional(),
+  }),
+  run: async (args) => {
+    await writeAppState("navigate", args);
+    return { ok: true };
+  },
+});
+```
+
+Voir [Context Awareness](/docs/context-awareness) pour le modèle complet.
+
+## Utilisez les itinéraires API avec parcimonie {#api-routes}
+
+Préférez actions pour les opérations de l'application. Créez des itinéraires Nitro personnalisés uniquement pour les surfaces qui ne peuvent pas être proprement actions :
+
+- Téléchargement de fichiers ou streaming binaire.
+- Pages publiques anonymes et webhooks.
+- Rappels OAuth et gestionnaires de protocole spécifiques au fournisseur.
+- Contenu public rendu par le serveur.
+
+Les itinéraires personnalisés qui touchent des données propriétaires doivent appeler `getSession(event)` et envelopper le travail de la base de données dans `runWithRequestContext({ userEmail, orgId }, fn)` avant d'utiliser les assistants d'accès.
+
+## Écrire les instructions de l'agent {#write-agents-md}
+
+`AGENTS.md` est la carte de l'agent de votre application : un petit fichier écrémé avec un
+ligne d'objectif, règles de base, clés d'état d'application, table d'action et skills
+index :
+
+```markdown
+# My Template
+
+One workspace for projects, tasks, and notes.
+
+## Core Rules
+
+- Data lives in SQL via Drizzle. Use actions for all writes; schema is additive.
+- Use `view-screen` before acting on "this project" if the screen is unclear.
+
+## Application State
+
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
+
+## Actions
+
+| Action           | Purpose                  |
+| ---------------- | ------------------------ |
+| `list-projects`  | List accessible projects |
+| `create-project` | Create a project         |
+```
+
+Mettez à jour `AGENTS.md` chaque fois que vous ajoutez une nouvelle action, un nouvel itinéraire, une clé d'état ou une action récurrente
+flux de travail. [Writing Agent Instructions](/docs/writing-agent-instructions) est le
+guide complet – comment garder `AGENTS.md` écrémé, ce qui appartient à chacun des quatre
+Surfaces de guidage et comment formuler les descriptions de compétences et d'outils pour que l'agent
+les déclenche de manière fiable.
+
+## Ajouter Skills {#skills}
+
+Utilisez skills pour les modèles détaillés qui gonfleraient `AGENTS.md` : API spécifiques au fournisseur, formats d'importation/exportation, flux d'édition complexes ou terminologie du domaine.
+
+```markdown
+---
+name: project-imports
+description: How to import projects from the legacy CSV export.
+---
+
+# Project Imports
+
+Use this skill when the user uploads a legacy project CSV.
+
+## Rules
+
+- Validate required columns before creating rows.
+- Use `create-project` for each project so ownership and sync are correct.
+- Save rejected rows as a note attached to the import summary.
+```
+
+Stocker le modèle skills dans `.agents/skills/<name>/SKILL.md`. Si les utilisateurs doivent pouvoir modifier les instructions au moment de l'exécution, faites-les également apparaître via les ressources de l'espace de travail.
+
+## Étapes de configuration de l'enregistrement {#onboarding}
+
+Si un modèle nécessite une clé API, une connexion OAuth ou un compte fournisseur, enregistrez une étape d'intégration au lieu d'enfouir l'exigence dans un README.
+
+```ts
+// server/plugins/onboarding.ts
+import { defineNitroPlugin } from "@agent-native/core/server";
+import { registerOnboardingStep } from "@agent-native/core/onboarding";
+
+export default defineNitroPlugin(() => {
+  registerOnboardingStep({
+    id: "github",
+    title: "Connect GitHub",
+    description: "Needed to import repositories and pull requests.",
+    order: 100,
+    methods: [
+      {
+        id: "token",
+        kind: "form",
+        primary: true,
+        label: "Save token",
+        payload: {
+          fields: [
+            { key: "GITHUB_TOKEN", label: "GitHub token", secret: true },
+          ],
+        },
+      },
+    ],
+    isComplete: () => !!process.env.GITHUB_TOKEN,
+  });
+});
+```
+
+Voir [Onboarding & API Keys](/docs/onboarding).
+
+## Prêt pour l'espace de travail {#workspace-ready}
+
+Les modèles doivent s'intégrer naturellement dans [Multi-App Workspaces](/docs/multi-app-workspace), généralement coordonnés par [Dispatch](/docs/dispatch).
+
+Liste de contrôle :
+
+- Montez A2A via le plug-in de discussion de l'agent framework ou `mountA2A()` afin que les applications sœurs puissent appeler votre agent.
+- Conservez les descriptions des cartes d'agent suffisamment précises pour que Dispatch puisse acheminer le travail avec précision.
+- Enregistrez les secrets/intégrations requis pour que la configuration apparaisse dans la barre latérale et que Dispatch puisse gérer les informations d'identification partagées.
+- Conservez les instructions transversales dans l'espace de travail `AGENTS.md` ou dans les ressources de l'espace de travail, et non copiées dans chaque application.
+- Utilisez des assistants de partage/d'accès pour toutes les ressources propriétaires afin que les espaces de travail à l'échelle de l'organisation restent isolés.
+
+## Publier un modèle {#publishing}
+
+Avant de partager :
+
+1. Exécutez `pnpm install`, `pnpm typecheck` et les tests du modèle.
+2. Vérifiez qu'il fonctionne sans aucune clé de fournisseur facultative configurée.
+3. Vérifiez l'authentification, le partage et l'isolation des données pour deux utilisateurs.
+4. Documenter les variables d'environnement requises et les étapes d'intégration.
+5. Inclure des exemples ou des lignes de départ via des migrations additives, et non des fichiers de données d'exécution suivis.
+
+Les modèles de communauté peuvent être créés à partir d'un dépôt GitHub :
+
+```bash
+npx @agent-native/core@latest create my-app --template github:user/repo
+```
+
+## Contribuer au framework monorepo {#contributing}
+
+### Tester les modifications non publiées du framework {#test-unpublished-framework-changes}
+
+Lorsque vous travaillez dans le framework monorepo et que vous avez besoin d'un fichier généré
+espace de travail pour utiliser des modifications de package ou de modèle non publiées, exécutez create avec le
+indicateur de package local :
+
+```bash
+AGENT_NATIVE_CREATE_USE_LOCAL_CORE=1 pnpm --filter @agent-native/core create my-platform
+```
+
+L'espace de travail généré relie le `@agent-native/core` local et
+Packages `@agent-native/dispatch`, donc modifications apportées aux Core API, espace de travail Dispatch
+le comportement ou les modèles propriétaires peuvent être testés avant la publication. Le colis
+Les scripts `prepack` créent `dist` avant la liaison, ce qui conserve le généré
+espace de travail pointé vers la sortie de build actuelle.

package/docs/content/locales/fr-FR/cross-app-sso.md

@@ -0,0 +1,185 @@
+---
+title: "Inter-application SSO"
+description: "Connectez-vous une fois sur chaque application native d'agent hébergée via la fédération d'identité avec Dispatch comme autorité d'identité – opt-in par application, réversible avec une seule variable d'environnement."
+---
+
+# Inter-application SSO
+
+Chaque application hébergée sur `*.agent-native.com` exécute son propre déploiement avec son **propre magasin d'utilisateurs distinct**. `mail.agent-native.com` et `calendar.agent-native.com` ne partagent pas de base de données, de table de session ou de domaine de cookie. Ainsi, « Connectez-vous une fois, utilisez chaque application » ne peut pas être un cookie partagé : il doit s'agir d'une **fédération d'identité**, avec [Dispatch](/docs/dispatch) agissant en tant qu'autorité d'identité pour l'espace de travail.
+
+Il s'agit de la même primitive de confiance que [A2A](/docs/a2a-protocol) et [External Agents](/docs/external-agents) utilisent déjà (un JWT signé `A2A_SECRET` et vérifié à la limite de la demande) appliquée au chemin de connexion humaine au lieu des appels d'agent à agent.
+
+> **Déploiement unifié ou déploiement par domaine.** Si vous hébergez toutes les applications sur une seule origine (`your-agents.com/mail`, `your-agents.com/calendar`), vous bénéficiez déjà d'une connexion partagée via un seul domaine de cookie — aucune fédération n'est nécessaire. Cross-App SSO n’est nécessaire que lorsque les applications s’exécutent sur des domaines distincts. Voir [Multi-App Workspaces — Unified deploy](/docs/multi-app-workspace#deployment).
+
+## Quoi et pourquoi {#what-why}
+
+Les magasins d'utilisateurs par application signifient qu'il n'existe pas d'endroit unique où un cookie de navigateur puisse résider et auquel chaque application fasse confiance. Le modèle de fédération nomme plutôt une application, **Dispatch**, comme autorité d'identité. Toute autre application peut déléguer « qui est cette personne ? » à Dispatch, récupérez une assertion signée de courte durée de l'adresse e-mail vérifiée de l'utilisateur, puis **associez-la à son propre compte local par e-mail**.
+
+La règle de liaison est délibérément étroite et additive :
+
+- **Utilisateur existant avec la même adresse e-mail → lié.** Le compte local est mis en correspondance avec une adresse e-mail vérifiée et réutilisé tel quel. Il n'est **jamais modifié, renommé ou supprimé** — la couche de fédération ne fait que le lire et créer une session pour celui-ci.
+- **Nouvel e-mail → créé.** Un nouveau compte local est créé pour cet e-mail vérifié, puis une session locale normale est créée.
+
+Cela sécurise le déploiement même si les utilisateurs se déconnectent. **La déconnexion est attendue.** Lorsqu'une application active cette fonctionnalité, les sessions existantes se terminent et les utilisateurs se réauthentifient via Dispatch. Mais ils se reconnectent toujours au **même compte correspondant à leur adresse e-mail, avec toutes leurs données intactes**, car les lignes d'identité ne sont que _ajoutées à_ — jamais détruites, renommées ou redirigées.
+
+## Comment ça marche {#how-it-works}
+
+Le flux est une redirection standard d'autorisation → jeton signé → rappel, avec le courrier électronique comme seule chose qui traverse la limite de confiance.
+
+```an-diagram title="Identity federation flow" summary="Dispatch authenticates the human and returns a short-lived signed assertion of one thing — the verified email. The app links by email and mints its own local session."
+{
+  "html": "<div class=\"diagram-sso\"><div class=\"diagram-card\" data-rough><strong>Client app</strong><small class=\"diagram-muted\">own user store</small></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill\">authorize</span></div><div class=\"diagram-card\" data-rough><strong>Dispatch</strong><small class=\"diagram-muted\">identity authority</small><span class=\"diagram-pill accent\">authenticates human</span></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill accent\">302 + signed JWT</span></div><div class=\"diagram-card\" data-rough><strong>App callback</strong><small class=\"diagram-muted\">verify signature · scope:identity · exp &le; 2 min</small><span class=\"diagram-pill ok\">JIT-link by email</span><span class=\"diagram-pill ok\">mint local session</span></div></div>",
+  "css": ".diagram-sso{display:flex;align-items:stretch;gap:12px;flex-wrap:wrap}.diagram-sso .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:150px}.diagram-sso .diagram-step{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:6px}.diagram-sso .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+1. **Application → Répartir (autoriser).** L'application envoie l'utilisateur à l'autorité d'identité :
+
+   ```
+   GET https://dispatch.agent-native.com/_agent-native/identity/authorize
+       ?app=<requesting-app>
+       &redirect_uri=<app-callback-url>
+       &state=<csrf-state>
+   ```
+
+   ```an-api title="Point de terminaison d'autorisation d'identité"
+   {
+     "méthode": "GET",
+     "path": "/_agent-native/identity/authorize",
+     "summary": "Dispatch (autorité d'identité) authentifie l'humain et le redirige avec un jeton d'identité signé",
+     "auth": "Session de répartition (connexion interactive si aucune)",
+     "params": [
+       { "name": "app", "in": "query", "type": "string", "required": true, "description": "L'identifiant de l'application demandeuse." },
+       { "name": "redirect_uri", "in": "query", "type": "string", "required": true, "description": "App callback URL. Validé par rapport à une liste blanche stricte (`*.agent-native.com` ou localhost par défaut)." },
+       { "name": "state", "in": "query", "type": "string", "required": true, "description": "L'état CSRF a été renvoyé lors de la redirection."
+     ],
+     "réponses" : [
+       { "status": "302", "description": "Redirection vers `redirect_uri` portant une identité signée `A2A_SECRET` de courte durée JWT (`scope: \"identity\"`, `exp` ≤ 2 minutes) plus l'original `state`." },
+       { "status": "400", "description": "Échec de la validation de la liste d'autorisation `redirect_uri` (origine croisée, `//host` relative au schéma ou suffixe non répertorié)."
+     ]
+   }
+   ```
+
+2. **Dispatch authentifie l'humain.** Si l'utilisateur dispose déjà d'une session Dispatch, cela est transparent. Sinon, Dispatch affiche son propre identifiant normal (e-mail/mot de passe, Google, etc. — voir [Authentication](/docs/authentication)). Dispatch n'est ici qu'une application native d'agent classique ; il n'exécute pas de mode d'authentification spécial.
+
+3. **Dispatch → Application (jeton d'identité signé).** Dispatch valide `redirect_uri` par rapport à une liste autorisée stricte et redirige vers le `redirect_uri` de l'application portant une **identité signée `A2A_SECRET` de courte durée JWT**. Les revendications du jeton sont intentionnellement minimes :
+
+   | Réclamation  | Signification                                                              |
+   | ------------ | -------------------------------------------------------------------------- |
+   | `sub`        | ID utilisateur stable auprès de l'autorité d'identité                      |
+   | `email`      | L'adresse e-mail **vérifiée** de l'utilisateur : la seule clé de connexion |
+   | `name`       | Nom d'affichage (ne faisant pas autorité, pour UI uniquement)              |
+   | `org_domain` | Domaine de l'espace de travail/de l'organisation, le cas échéant           |
+   | `scope`      | Toujours `"identity"` : ce jeton autorise uniquement la connexion          |
+   | `exp`        | **≤ 2 minutes** à partir du problème                                       |
+
+4. **L'application vérifie et les liens JIT par e-mail.** L'application vérifie la signature du jeton avec son propre `A2A_SECRET`, vérifie `scope: "identity"` et `exp`, puis effectue **une liaison juste à temps strictement par e-mail vérifié** :
+   - S'il existe un utilisateur local avec cette adresse e-mail → réutilisez-le tel quel.
+   - Sinon → créez un utilisateur local pour cet e-mail.
+
+5. **L'application crée une session locale normale.** À partir de là, l'utilisateur dispose d'une session locale ordinaire dans le propre magasin de cette application : chaque vérification d'accès, portée d'organisation et protection d'action existante fonctionne exactement comme avant. La fédération ne s'est produite qu'à la porte d'entrée.
+
+### S'inscrire {#opt-in}
+
+Une application participe **uniquement** lorsque cette variable d'environnement est définie lors de son déploiement :
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+- **Set** → l'application affiche une option **"Connectez-vous avec Agent-Native"** qui exécute le flux ci-dessus. La connexion locale directe (e-mail/mot de passe, Google) fonctionne toujours en parallèle.
+- **Désactivé (par défaut)** → **zéro changement de comportement.** L'application s'authentifie exactement comme avant ; le chemin du code de la fédération est inactif. Il n'y a aucun changement de schéma et rien à migrer, donc l'activation ou la désactivation de la variable est entièrement réversible à tout moment.
+
+## Sécurité {#security}
+
+L'ensemble du modèle repose sur quelques garanties volontairement petites :
+
+- **Jeton signé de courte durée.** L'assertion d'identité est un JWT signé `A2A_SECRET` avec une expiration **≤ 2 minutes** et `scope: "identity"`. Il autorise une connexion unique et ne peut pas être rejoué longtemps ni réutilisé pour l'accès aux API/A2A.
+- **Liste verte stricte de `redirect_uri`.** La répartition redirige uniquement vers `*.agent-native.com` ou localhost par défaut. Les cibles de redirection arbitraires, relatives au schéma (`//host`) et d'origine croisée sont rejetées, de sorte que l'autorité ne peut pas être transformée en un oracle de redirection ouverte ou d'exfiltration de jetons.
+- **Jointure par e-mail uniquement à partir d'un jeton vérifié.** La seule chose qui traverse la limite de confiance est l'e-mail vérifié dans un jeton signé. L'application n'accepte pas d'identifiant d'utilisateur, de rôle, d'appartenance à une organisation ou tout autre état privilégié du fil : elle dérive tout localement du compte correspondant.
+- **Écrites d'identité additives uniquement.** La liaison réutilise un compte de même adresse existant sans modification ou en insère un nouveau. Aucune mise à jour, renommage, redirection ou suppression des lignes d'identité ne se produit sur ce chemin.
+- **Désactivé par défaut.** Avec `AGENT_NATIVE_IDENTITY_HUB_URL` désactivé, toute la fonctionnalité est inerte.
+
+```an-callout
+{
+  "tone": "success",
+  "body": "**Safe to enable, safe to revert.** Identity writes are **additive only** — an existing same-email account is reused untouched, and a new email just inserts a fresh row. There is no schema change and nothing to migrate, so flipping `AGENT_NATIVE_IDENTITY_HUB_URL` on or off is fully reversible at any time, per app."
+}
+```
+
+Le lien juste à temps est une décision unique entièrement saisie sur l’e-mail vérifié :
+
+```an-diagram title="JIT-link decision" summary="Linking is keyed on the verified email and is additive only — existing accounts are reused unchanged, new emails create a fresh local user."
+{
+  "html": "<div class=\"diagram-jit\"><div class=\"diagram-node\" data-rough>Verified email<br><small class=\"diagram-muted\">from signed identity JWT</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-branch\"><div class=\"diagram-box\" data-rough>Local user exists?<span class=\"diagram-pill ok\">yes &rarr; reuse unchanged</span><span class=\"diagram-pill accent\">no &rarr; create local user</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Mint normal local session</div></div></div>",
+  "css": ".diagram-jit{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-node{display:flex;flex-direction:column;gap:4px;padding:12px 14px}.diagram-jit .diagram-branch{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-box{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-jit .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Auto-hébergement {#self-hosting}
+
+Tout déploiement Dispatch peut servir de centre d'identité ; vous n'êtes pas limité à `dispatch.agent-native.com`. Définissez `AGENT_NATIVE_IDENTITY_HUB_URL` sur chaque application client pour pointer vers votre instance Dispatch :
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.yourcompany.com
+```
+
+**Liste autorisée de redirection.** Le hub (Dispatch) valide `redirect_uri` sur le point de terminaison d'autorisation avant d'émettre un jeton. La liste blanche est configurée dans `templates/dispatch/server/lib/identity-sso.ts` :
+
+- **Par défaut :** `*.agent-native.com` et localhost uniquement (la constante `DEFAULT_ALLOWED_HOST_SUFFIXES`).
+- **Extension :** définissez la variable d'environnement `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` sur le déploiement Dispatch avec une liste de suffixes d'hôte supplémentaires séparés par des virgules :
+
+  ```bash
+  # Autoriser les sous-domaines yourcompany.com en plus des valeurs par défaut
+  IDENTITY_SSO_ALLOWED_HOST_SUFFIXES=".votreentreprise.com,.staging.votreentreprise.com"
+  ```
+
+  Chaque entrée est normalisée par un suffixe préfixé par un point (`.yourcompany.com`), donc une vérification du suffixe est à la fois suffisante et la moins sujette aux coups de pied - pas de liste par application à synchroniser. Les entrées qui correspondent à tout (vides ou simplement `.`) sont filtrées.
+
+- **Localhost** est toujours autorisé pour le développement local d'applications côté client, quel que soit `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`.
+
+Sans `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`, un Dispatch auto-hébergé ne peut émettre des jetons qu'aux applications sur `*.agent-native.com`. Définissez la variable d'environnement sur votre déploiement Dispatch pour déverrouiller d'autres domaines.
+
+## Runbook de déploiement Canary {#canary-rollout}
+
+Le basculement et la restauration sont **une seule variable d'environnement par déploiement d'application**. Déployez une application à la fois, vérifiez, puis développez. Ne définissez pas la variable sur chaque application à la fois.
+
+**1. Déployez le code — aucun changement de comportement.**
+Expédiez la version à chaque application avec `AGENT_NATIVE_IDENTITY_HUB_URL` **non défini partout**. Confirmez que les connexions normales fonctionnent toujours sur quelques applications.
+
+**2. Activez le Canari sur l'application ONE à la fois.**
+Défini, sur un seul déploiement :
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+Laissez l'environnement de toutes les autres applications non défini. Redéployez/redémarrez pour qu'il récupère la variable.
+
+**3. Vérifiez le canari (liste de contrôle).**
+
+- Déconnectez-vous\*\* de l'application.
+- L'écran de connexion affiche désormais **"Connectez-vous avec Agent-Native"**. Cliquez dessus.
+- Vous êtes redirigé vers **Dispatch** et complétez sa connexion (ou passez directement si vous y êtes déjà connecté).
+- Vous êtes redirigé **vers l'application, connecté** — et il s'agit du **même compte préexistant** (même e-mail) que vous aviez auparavant, pas un nouveau.
+- **Les données de l'application sont intactes** : vos enregistrements, paramètres et portée de l'organisation existants sont exactement tels qu'ils étaient.
+- **Les connexions directes existantes fonctionnent toujours** : l'adresse e-mail/mot de passe et la connexion Google continuent de fonctionner aux côtés de SSO.
+
+Si une vérification échoue, passez directement à l'étape 4 (restauration) : c'est instantané et sécurisé pour les données.
+
+**4. Développez application par application.**
+Une fois qu'une application est vérifiée, répétez les étapes 2 à 3 pour l'application suivante : en définissant `AGENT_NATIVE_IDENTITY_HUB_URL` sur un déploiement à la fois. Ne jamais activer par lots.
+
+**5. Rollback = désactivez la variable d'environnement lors du déploiement de cette application.**
+Pour restaurer une application, **supprimez `AGENT_NATIVE_IDENTITY_HUB_URL` de l'environnement de cette application et redéployez-la/redémarrez-la.** L'application revient immédiatement à son comportement d'authentification antérieur. Il n'y a **aucune modification de données à annuler** : les lignes d'identité n'ont été ajoutées que, et la suppression de la variable rend simplement le chemin de fédération à nouveau inactif. Le basculement et la restauration de chaque application sont indépendants et réversibles.
+
+> Le déploiement déconnecte les utilisateurs lorsque chaque application est activée (ils se ré-authentifient via Dispatch), mais ils se reconnectent toujours au **même compte correspondant à l'adresse e-mail avec les données intactes**, car les lignes d'identité ne sont jamais détruites ou renommées : elles sont seulement ajoutées.
+
+## Connexe {#related}
+
+- [Authentication](/docs/authentication) – modes d'authentification locaux, sessions, organisations, variable d'environnement `A2A_SECRET`.
+- [A2A Protocol](/docs/a2a-protocol) — le modèle de confiance signé JWT, à vérification à la limite, réutilisé.
+- [External Agents](/docs/external-agents) : le même modèle d'identité signé `A2A_SECRET` appliqué aux connexions d'agent et aux liens profonds.
+- [Dispatch](/docs/dispatch) : l'autorité d'identité de l'espace de travail et le hub de routage.
+- [Security & Data Scoping](/docs/security) : écritures de données additives uniquement et portée par compte.
+- [Multi-App Workspaces](/docs/multi-app-workspace) : le déploiement unifié à origine unique qui évite entièrement SSO inter-domaines.