@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/fr-FR/workspace-connections.md

@@ -0,0 +1,321 @@
+---
+title: "Connexions à l'espace de travail"
+description: "Métadonnées, subventions et références d'informations d'identification partagées du fournisseur pour les intégrations à connexion unique, à utiliser partout."
+---
+
+# Connexions à l'espace de travail
+
+Les connexions à l'espace de travail constituent la primitive de structure pour les métadonnées d'intégration réutilisables. Ils permettent de « se connecter une fois, d'accorder des applications, de réutiliser les informations d'identification » sans prétendre que chaque fournisseur est entièrement générique.
+
+## Démarrage rapide {#quickstart}
+
+### Les quatre concepts
+
+- **Connexion** : un compte de fournisseur nommé (`team-slack`, `acme-hubspot`). Enregistre l’identifiant du fournisseur, l’étiquette du compte, le statut, les étendues et la configuration sécurisée. Ne stocke jamais les valeurs secrètes.
+- **Accorder** — autorisation permettant à une application spécifique d'utiliser une connexion. Une application sans autorisation ne peut pas voir les informations d'identification de la connexion.
+- **credentialRef** — un pointeur vers un secret de coffre-fort (`{ key: "SLACK_BOT_TOKEN", scope: "org" }`). La connexion indique où se trouve le jeton ; le coffre-fort contient la valeur.
+- **Préparation** : état combiné affiché par une application : `connected` (accordé + informations d'identification présentes), `needs_grant`, `needs_credentials`, `needs_attention` ou `not_configured`.
+
+```an-diagram title="Connect once, grant apps, reuse credentials" summary="A Connection holds provider metadata (never secrets) and credentialRefs that point at the vault. Per-app Grants unlock it. Apps read a single Readiness status."
+{
+  "html": "<div class=\"diagram-conn\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">Connection</span><div class=\"diagram-box\" data-rough>named provider account<br><small class=\"diagram-muted\">provider, label, status, scopes, config &middot; never stores secret values</small></div><div class=\"diagram-muted\">credentialRef &rarr; pointer to a vault secret</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill\">Grant</span><div class=\"diagram-box\" data-rough>per-app permission<br><small class=\"diagram-muted\">no grant = no credential access</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill ok\">Readiness</span><small class=\"diagram-muted\">what the app sees</small><div class=\"sev-row\"><span class=\"diagram-pill ok\">connected</span><span class=\"diagram-pill warn\">needs_grant</span></div><div class=\"sev-row\"><span class=\"diagram-pill warn\">needs_credentials</span><span class=\"diagram-pill warn\">needs_attention</span></div><div class=\"sev-row\"><span class=\"diagram-pill\">not_configured</span></div></div></div>",
+  "css": ".diagram-conn{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-conn .col{display:flex;flex-direction:column;gap:8px;padding:14px;min-width:220px}.diagram-conn .diagram-arrow{font-size:22px;line-height:1}.diagram-conn .sev-row{display:flex;gap:8px;flex-wrap:wrap}"
+}
+```
+
+### Exemple concret : Slack
+
+Connectez Slack une fois et accordez-le à Brain and Analytics :
+
+```ts
+import {
+  upsertWorkspaceConnection,
+  upsertWorkspaceConnectionGrant,
+} from "@agent-native/core/workspace-connections";
+
+await upsertWorkspaceConnection({
+  id: "acme-slack",
+  provider: "slack",
+  label: "Acme Slack",
+  accountId: "T012345",
+  accountLabel: "Acme",
+  status: "connected",
+  scopes: ["channels:history", "groups:history", "chat:write"],
+  config: {
+    teamDomain: "acme",
+    channelHints: ["product", "dev-fusion", "customer-success"],
+  },
+  credentialRefs: [{ key: "SLACK_BOT_TOKEN", scope: "org" }],
+});
+
+await upsertWorkspaceConnectionGrant({
+  connectionId: "acme-slack",
+  appId: "brain",
+});
+await upsertWorkspaceConnectionGrant({
+  connectionId: "acme-slack",
+  appId: "analytics",
+});
+```
+
+```an-schema title="The connection model" summary="A connection records safe provider metadata and credentialRefs (pointers, not secrets). Each grant unlocks one app — one connection, many grants."
+{
+  "entities": [
+    {
+      "id": "conn",
+      "name": "workspace_connections",
+      "note": "Named provider account. Never stores secret values.",
+      "fields": [
+        { "name": "id", "type": "string", "pk": true, "note": "e.g. acme-slack" },
+        { "name": "provider", "type": "string", "note": "stable provider id, e.g. slack" },
+        { "name": "label", "type": "string" },
+        { "name": "accountId", "type": "string", "nullable": true },
+        { "name": "accountLabel", "type": "string", "nullable": true },
+        { "name": "status", "type": "string", "note": "e.g. connected" },
+        { "name": "scopes", "type": "string[]", "nullable": true },
+        { "name": "config", "type": "json", "nullable": true, "note": "safe, non-secret config" },
+        { "name": "credentialRefs", "type": "json", "nullable": true, "note": "pointers to vault keys, e.g. { key, scope }" }
+      ]
+    },
+    {
+      "id": "grant",
+      "name": "workspace_connection_grants",
+      "note": "Per-app permission to use a connection.",
+      "fields": [
+        { "name": "connectionId", "type": "string", "fk": "conn.id" },
+        { "name": "appId", "type": "string", "note": "e.g. brain, analytics" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "conn", "to": "grant", "kind": "1-n", "label": "grants apps" }
+  ]
+}
+```
+
+### Quels appels les applications
+
+Avant de demander à un utilisateur de coller une nouvelle clé, vérifiez d'abord qu'il est prêt :
+
+```ts
+import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core/workspace-connections";
+
+const catalog = await listWorkspaceConnectionProviderCatalogForApp({
+  appId: "brain",
+  templateUse: "brain",
+  provider: "slack",
+  includeConnections: "all",
+});
+
+const slack = catalog.providers[0];
+if (slack.workspaceConnection.grantState === "needs_grant") {
+  // Show "Grant Brain access" instead of asking for a second Slack token.
+}
+if (slack.readiness.status === "needs_credentials") {
+  // Show the missing credential ref names, never a secret value.
+}
+```
+
+## Référence {#reference}
+
+### Catalogue des fournisseurs
+
+Importer le catalogue depuis `@agent-native/core/connections` :
+
+```ts
+import {
+  getWorkspaceConnectionProvider,
+  listWorkspaceConnectionProvidersForTemplate,
+  workspaceConnectionProviderSupports,
+} from "@agent-native/core/connections";
+
+const brainProviders = listWorkspaceConnectionProvidersForTemplate("brain");
+const slack = getWorkspaceConnectionProvider("slack");
+
+if (workspaceConnectionProviderSupports("slack", "messages")) {
+  // Offer a Slack source, sync check, or onboarding step.
+}
+```
+
+Les identifiants de fournisseur initiaux sont :
+
+| Fournisseur    | Capacités                                   | Utilisations courantes                           |
+| -------------- | ------------------------------------------- | ------------------------------------------------ |
+| `slack`        | recherche, importation, messages            | cerveau, répartition, analyses                   |
+| `github`       | recherche, importation, code, documents     | cerveau, analyses, répartition                   |
+| `notion`       | recherche, importation, documents           | cerveau, contenu, répartition                    |
+| `gmail`        | recherche, importation, messages            | courrier, cerveau, expédition                    |
+| `google_drive` | recherche, importation, documents           | cerveau, contenu, diapositives                   |
+| `hubspot`      | recherche, importation, CRM                 | analyse, cerveau, courrier                       |
+| `granola`      | recherche, importation, réunions, documents | cerveau, calendrier, répartition                 |
+| `clips`        | recherche, importation, réunions            | cerveau, clips, vidéos                           |
+| `generic`      | recherche, importation, documents           | webhooks personnalisé et suppression de fichiers |
+
+Les clés d'identification sont uniquement des noms, tels que `SLACK_BOT_TOKEN` ou `GITHUB_TOKEN`. Les métadonnées du fournisseur ne doivent jamais inclure les valeurs réelles des informations d'identification.
+
+### Magasin de connexion API
+
+```ts
+import {
+  listWorkspaceConnectionProviderCatalogForApp,
+  listWorkspaceConnectionGrants,
+  listWorkspaceConnections,
+  summarizeWorkspaceConnectionProviderForApp,
+  summarizeWorkspaceConnectionProviderReadiness,
+  upsertWorkspaceConnection,
+  upsertWorkspaceConnectionGrant,
+  revokeWorkspaceConnectionGrant,
+} from "@agent-native/core/workspace-connections";
+
+const connections = await listWorkspaceConnections({ includeDisabled: true });
+const grants = await listWorkspaceConnectionGrants({ appId: "brain" });
+
+const appGrant = summarizeWorkspaceConnectionProviderForApp({
+  providerId: "slack",
+  appId: "brain",
+  connections,
+  grants,
+});
+
+const readiness = summarizeWorkspaceConnectionProviderReadiness({
+  provider: slack!,
+  appId: "brain",
+  connections,
+  grants,
+});
+
+const brainCatalog = await listWorkspaceConnectionProviderCatalogForApp({
+  appId: "brain",
+  templateUse: "brain",
+});
+```
+
+Le tableau `credentialRefs` pointe vers les clés du coffre-fort ; il ne s'agit pas de stockage d'informations d'identification. Par exemple, `{ key: "SLACK_BOT_TOKEN", scope: "org" }` demande à une application accordée de rechercher le secret du coffre-fort à l'échelle de l'organisation nommé `SLACK_BOT_TOKEN` lorsqu'elle doit appeler Slack. Les références au niveau de la connexion décrivent le compte du fournisseur ; les références au niveau des subventions peuvent restreindre ou remplacer ce qu'une application spécifique doit utiliser.
+
+Les lignes de connexion sont limitées à l'organisation active lorsqu'elle est présente. Sans organisation, ils sont limités à l’utilisateur authentifié. Les lignes d'octroi utilisent la même portée.
+
+**Champ `allowedApps` hérité :** `allowedApps: []` signifie que chaque application de la même portée peut utiliser la connexion ; `allowedApps: ["dispatch"]` accorde l'accès via le champ hérité. Utilisez des lignes `workspace_connection_grants` explicites pour la nouvelle configuration : elles facilitent la révocation, l'audit et la préparation par application. `revokeWorkspaceConnectionGrant(connectionId, appId)` supprime une autorisation explicite mais ne modifie pas l'ancien `allowedApps`.
+
+Utilisez `summarizeWorkspaceConnectionProviderForApp()` et `summarizeWorkspaceConnectionProviderReadiness()` pour le statut de l'application au lieu de procéder à des contrôles d'octroi manuels. Les résumés partagés renvoient `grantState`, `grantAvailability`, les noms de référence d'informations d'identification sécurisées, les lignes de connexion par application et les champs de préparation tels que `readyConnectionCount` et `missingRequiredCredentialKeys`.
+
+Pour les nouveaux écrans de configuration d'application, préférez `listWorkspaceConnectionProviderCatalogForApp()` comme limite de niveau supérieur : il combine le catalogue des fournisseurs, les connexions étendues, les autorisations explicites, les résumés d'accès par application et la préparation du fournisseur dans une forme sécurisée.
+
+### Comment cela complète le coffre-fort
+
+Le coffre-fort des informations d'identification répond : « Où le secret est-il stocké, qui peut y accéder et quelles applications y ont accès ? »
+
+Réponses des métadonnées du fournisseur de connexion Workspace : "De quel fournisseur s'agit-il, que peut-il faire, de quelles clés d'identification pourrait-il avoir besoin et quels modèles devraient le proposer ?"
+
+```an-diagram title="Connection store vs. vault" summary="The vault owns the secret value. The connection owns provider metadata plus credentialRefs (pointers). At execution time the app resolves the ref through a granted connection and reads the value from the vault."
+{
+  "html": "<div class=\"diagram-vault\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">Connection store</span><div class=\"diagram-box\" data-rough>provider account + metadata<br><small class=\"diagram-muted\">status, scopes, config</small></div><div class=\"diagram-box\" data-rough>credentialRef<br><small class=\"diagram-muted\">{ key: SLACK_BOT_TOKEN, scope: org }</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">App action</span><small class=\"diagram-muted\">resolves at execution time through a granted ref</small><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill ok\">Vault</span><div class=\"diagram-box\" data-rough>secret value<br><small class=\"diagram-muted\">never returned to the agent or UI</small></div></div></div>",
+  "css": ".diagram-vault{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-vault .col{display:flex;flex-direction:column;gap:8px;padding:14px;min-width:220px}.diagram-vault .diagram-card{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-vault .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+Utilisez les deux ensemble :
+
+1. Dispatch (ou un autre flux de configuration de l'espace de travail) crée le secret du coffre-fort sous-jacent ou la référence d'identifiant OAuth.
+2. Le magasin de connexions de l'espace de travail enregistre le compte du fournisseur, les métadonnées sécurisées, les références d'informations d'identification et les autorisations d'application.
+3. Chaque application lit les métadonnées du fournisseur à partir du catalogue et les résumés de connexion/octroi à partir du magasin partagé.
+4. L'application UI indique qu'elle est prête : connectée, accordée mais non opérationnelle, nécessite une autorisation, des informations d'identification manquantes ou des métadonnées uniquement.
+5. SQL spécifique à l'application stocke uniquement les identifiants sources, les curseurs, les filtres, les fenêtres de synchronisation, les définitions de métriques, les règles de révision et les choix des utilisateurs spécifiques à l'application.
+6. L'application actions résout les informations d'identification au moment de l'exécution via les références de connexion accordées et le coffre-fort, et ne renvoie jamais de valeurs secrètes.
+
+### Exécution du lecteur du fournisseur
+
+La couche fournisseur-lecteur est avant tout un contrat, et non une promesse selon laquelle chaque fournisseur dispose d'un lecteur en direct partagé. Les définitions de lecteur décrivent les opérations prises en charge, les exigences d'identification et l'état de mise en œuvre : `metadata-only`, `template-owned` ou `shared`. Le moteur d'exécution résout la connexion à l'espace de travail accordée et les références d'informations d'identification pour une application, appelle un gestionnaire enregistré et renvoie les éléments normalisés sans exposer les valeurs secrètes.
+
+La plupart des gestionnaires en direct restent aujourd'hui la propriété de modèles, ce qui signifie que Brain est toujours propriétaire du comportement d'ingestion Slack/GitHub et qu'Analytics possède toujours l'interprétation analytique. Promouvez un lecteur vers `shared` uniquement lorsque les appels, la pagination, les autorisations et la sémantique des résultats spécifiques au fournisseur sont véritablement réutilisables dans les modèles.
+
+### Modèle de préparation de l'application
+
+Les applications qui utilisent les informations d'identification du fournisseur partagé doivent exposer une action de préparation en lecture seule et une petite surface de configuration couvrant :
+
+- **Catalogue de fournisseurs :** identifiant du fournisseur, étiquette, fonctionnalités, utilisations de modèles recommandées et noms de clés d'identification requis de `@agent-native/core/connections`.
+- **Résumé de l'espace de travail :** nombre de connexions, nombres d'actifs/accordés, état d'attribution, noms de référence d'informations d'identification et étiquettes de compte non secrets de `@agent-native/core/workspace-connections`.
+- **Préparation du fournisseur :** `ready`, `needs_credentials`, `needs_attention`, `checking`, `disabled` ou `not_configured` via `summarizeWorkspaceConnectionProviderReadiness()`.
+- **État de la source :** sources configurées au niveau de l'application locale, curseurs, état de synchronisation et action suivante.
+
+La page Sources de Brain est l'implémentation de référence. Il affiche les fournisseurs de connexion d'espace de travail réutilisables à côté des enregistrements source Brain, étiquette les états d'octroi comme `connected`, `granted`, `needs_grant` ou `not_connected`, et affiche l'état du fournisseur comme étant prêt, clés manquantes, octroi nécessaire, besoin de réparation ou métadonnées uniquement.
+
+### Créer un connecteur réutilisable
+
+Quand un nouveau fournisseur doit fonctionner sur plusieurs modèles :
+
+1. **Métadonnées du fournisseur :** ajoutez ou réutilisez un fournisseur dans `@agent-native/core/connections`. Il s'agit de l'identifiant stable, de l'étiquette d'affichage, de la liste des fonctionnalités, des utilisations de modèles recommandées et des noms de clés d'identification.
+2. **Connexion à l'espace de travail :** Dispatch ou une autre surface de configuration de l'espace de travail stocke les métadonnées sécurisées, l'état, les étendues, `credentialRefs` et les subventions d'application du compte connecté via `@agent-native/core/workspace-connections`.
+3. **Source locale de l'application :** Brain, Analytics, Mail ou une autre application stocke uniquement les choix spécifiques à l'application qu'elle possède, tels que les canaux Slack, les référentiels GitHub, les filtres d'objets HubSpot, les curseurs de synchronisation ou la cadence d'interrogation.
+
+Ne dupliquez pas le stockage OAuth/jeton dans chaque application. L'enregistrement de connexion indique « ici Acme Slack et son jeton réside à `SLACK_BOT_TOKEN` » ; la source locale de l'application indique "Brain peut ingérer `#product` et `#dev-fusion` à partir de cette connexion Slack."
+
+### Configuration du plan de contrôle de répartition
+
+Dispatch expose le plan de contrôle actions qui écrit les mêmes fonctions de magasin partagé qu'une application pourrait appeler directement :
+
+```ts
+// templates/dispatch/actions/upsert-workspace-connection.ts delegates to this.
+await upsertWorkspaceConnection({
+  id: "team-slack",
+  provider: "slack",
+  label: "Acme Slack",
+  accountId: "T012345",
+  accountLabel: "acme",
+  status: "connected",
+  scopes: ["channels:history", "groups:history"],
+  config: { teamDomain: "acme", preferredChannels: ["product", "dev-fusion"] },
+  credentialRefs: [
+    {
+      key: "SLACK_BOT_TOKEN",
+      scope: "org",
+      provider: "slack",
+      label: "Slack bot token",
+    },
+  ],
+});
+
+// Then grant the apps that should reuse the provider.
+await upsertWorkspaceConnectionGrant({
+  connectionId: "team-slack",
+  appId: "brain",
+});
+await upsertWorkspaceConnectionGrant({
+  connectionId: "team-slack",
+  appId: "analytics",
+});
+```
+
+Utilisez `allowedApps: []` uniquement lorsqu'une connexion doit être disponible pour chaque application dans la même étendue. Préférez les lignes d'attribution explicites pour la configuration de la production.
+
+### Résolution des identifiants
+
+Le code d'exécution de l'application résout les valeurs d'informations d'identification du `credentialRefs` accordé via le coffre-fort dans la portée de la demande active. Le `source-credentials.ts` de Brain est l'implémentation de référence actuelle : il répertorie les connexions à l'espace de travail pour le fournisseur, vérifie `getWorkspaceConnectionAppAccess` pour `appId: "brain"`, fusionne les références d'informations d'identification au niveau de la connexion et de l'octroi, et lit le premier secret de coffre-fort correspondant. D'autres applications devraient suivre cette forme au lieu d'atteindre `process.env`.
+
+## Notes de conception {#design-notes}
+
+<details>
+<summary>Politique de promotion des lecteurs et chemin vers "Connectez-vous une fois, utilisez partout" </summary>
+
+### Limite locale de l'application
+
+La frontière entre les connexions partagées et les sources locales des applications est intentionnelle. Ce qui est réutilisable aujourd'hui, c'est l'identité du fournisseur, la résolution des références d'informations d'identification, les subventions par application, la préparation du fournisseur, les métadonnées de compte sécurisées et le contrat normalisé fournisseur-lecteur. Ce qui n'est pas encore générique, c'est la plupart des lectures API du fournisseur en direct, la propriété du flux OAuth, les curseurs d'ingestion, les filtres sources, la cadence de synchronisation et l'interprétation du domaine. Ceux-ci restent dans l'application propriétaire du flux de travail, à moins qu'une implémentation de lecteur ne soit explicitement promue au statut partagé.
+
+Les connecteurs source d’application ne doivent pas lire les variables d’environnement au niveau du déploiement comme solution de secours pour les informations d’identification source de l’utilisateur/de l’organisation. Les variables d'environnement sont globales pour le déploiement et n'expriment pas les autorisations d'espace de travail.
+
+Les agents doivent suivre une règle simple : si un utilisateur demande à se connecter à Slack, GitHub, HubSpot, Gmail, Google Drive, Granola ou un autre fournisseur partagé, inspectez d'abord le catalogue de connexions à l'espace de travail. Si le fournisseur est `connected`, utilisez-le. S'il s'agit de `needs_grant`, demandez ou effectuez l'octroi d'application. S'il s'agit de `needs_credentials`, demandez la clé du coffre-fort manquant. Ne demandez une nouvelle clé brute que lorsqu'aucune connexion réutilisable n'existe.
+
+### Chemin vers "Connectez-vous une fois, utilisez partout"
+
+Le catalogue des fournisseurs et le magasin de subventions constituent la base d'une couche d'espace de travail plus large :
+
+- Les identifiants de fournisseur partagés et les noms de fonctionnalités maintiennent les modèles alignés.
+- L'inventaire au niveau de l'espace de travail peut montrer quels fournisseurs sont configurés dans les applications Brain, Mail, Analytics, Dispatch et futures.
+- Les lignes de connexion enregistrent les étiquettes de compte, l'état, les applications autorisées, les références d'informations d'identification et les vérifications d'état sans modifier les identifiants de fournisseur associés au modèle.
+- Les lignes d'autorisation permettent au propriétaire d'un espace de travail de se connecter une seule fois, puis d'activer des applications individuelles au fur et à mesure que l'espace de travail les adopte.
+- Les agents peuvent acheminer le travail entre les applications en sachant quels fournisseurs sont déjà connectés et quelles applications bénéficient de subventions.
+- La recherche fédérée peut demander des fournisseurs dotés des fonctionnalités `search`, `docs`, `messages`, `meetings`, `crm` ou `code` au lieu de coder en dur la liste des connecteurs de chaque application.
+- Les lecteurs spécifiques au fournisseur, les flux d'actualisation OAuth, les points de contrôle d'ingestion et les modèles de données appartenant à l'application peuvent être partagés ultérieurement, mais ils ne sont pas impliqués par une connexion à un espace de travail aujourd'hui.
+
+Gardez les limites strictes : les métadonnées du fournisseur peuvent être affichées en toute sécurité ; les valeurs des informations d'identification restent dans le coffre-fort.
+
+</details>

package/docs/content/locales/fr-FR/workspace-management.md

@@ -0,0 +1,175 @@
+---
+title: "Gouvernance de l'espace de travail"
+description: "Branching, CODEOWNERS, examen des relations publiques et comment Dispatch gère la gouvernance d'exécution parallèlement à la gouvernance au niveau Git."
+---
+
+# Gouvernance de l'espace de travail
+
+> **Quel document d'espace de travail ?** Cette page couvre la **gouvernance** : qui révise, approuve et possède quoi dans de nombreuses applications dans un seul dépôt. Pour savoir ce qu'est un espace de travail (la couche de personnalisation), voir [Workspace](/docs/workspace) ; pour la forme de déploiement (un monorepo, plusieurs applications), voir [Multi-App Workspaces](/docs/multi-app-workspace).
+
+Ce guide couvre l'aspect opérationnel de l'exécution d'un espace de travail natif d'agent : comment créer des branches, qui examine quoi, comment configurer la propriété du code et comment le plan de contrôle Dispatch s'intègre dans votre modèle de gouvernance.
+
+```an-diagram title="Two governance planes" summary="Git governs code; Dispatch governs runtime. They are complementary — don't replicate one inside the other."
+{
+  "html": "<div class=\"gov\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Git / GitHub</span><strong>Code governance</strong><div class=\"gov-list\"><span class=\"diagram-pill\">CODEOWNERS</span><span class=\"diagram-pill\">branch protection</span><span class=\"diagram-pill\">PR review</span><span class=\"diagram-pill\">git log / blame</span></div></div><div class=\"diagram-pill diagram-muted\">+</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Dispatch</span><strong>Runtime governance</strong><div class=\"gov-list\"><span class=\"diagram-pill\">vault secrets &amp; grants</span><span class=\"diagram-pill\">workspace resources</span><span class=\"diagram-pill\">agent profiles</span><span class=\"diagram-pill\">approvals &amp; audit</span></div></div></div>",
+  "css": ".gov{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.gov .diagram-card{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:240px}.gov .gov-list{display:flex;flex-wrap:wrap;gap:6px;margin-top:4px}"
+}
+```
+
+## Branchement
+
+### Branches de fonctionnalités
+
+Utilisez des branches de fonctionnalités éphémères pour tous les travaux :
+
+```
+main                         ← production
+├── feat/mail-filters        ← single-app change
+├── feat/core-oauth-refresh  ← framework change
+├── fix/analytics-chart      ← targeted bug fix
+└── feat/vault-encryption    ← dispatch/infra change
+```
+
+**Conventions de dénomination :**
+
+- **Modifications pour une seule application :** `feat/<app>-<description>` ou `fix/<app>-<description>` — par ex. `feat/mail-thread-search`, `fix/calendar-recurrence-parse`
+- **Modifications du framework :** `feat/core-<description>` ou `fix/core-<description>` — par ex. `feat/core-polling-v2`
+- **Modifications de répartition :** `feat/dispatch-<description>` — par ex. `feat/dispatch-vault-policies`
+- **Modifications inter-applications :** si une modification du framework nécessite des mises à jour de modèles, effectuez les deux dans une seule branche afin qu'elles soient expédiées de manière atomique
+
+Gardez les branches de courte durée. Les branches de longue durée divergent des branches principales et créent des fusions douloureuses, en particulier dans un monorepo où plusieurs équipes poussent quotidiennement.
+
+### Branchement non-développeur
+
+Tous ceux qui ont besoin d'apporter des modifications ne sont pas à l'aise avec git. [Builder.io](https://www.builder.io) prend en charge un modèle de branchement visuel qui correspond aux branches Git sous le capot – utile pour les modifications de contenu et de copie, les ajustements de mise en page, les itérations de conception et les tests A/B sans environnement de développement.
+
+## Propriété du code
+
+La gouvernance du code est configurée par une poignée de fichiers à la racine du dépôt :
+
+```an-file-tree title="Governance config in the repo"
+{
+  "entries": [
+    { "path": ".github/CODEOWNERS", "note": "Auto-assigns reviewers per changed path" },
+    { "path": ".github/labeler.yml", "note": "Auto-labels PRs by app" },
+    { "path": "pnpm-workspace.yaml", "note": "Workspace-level — broad review" },
+    { "path": "package.json", "note": "Workspace-level — platform team owns" }
+  ]
+}
+```
+
+Le fichier CODEOWNERS de GitHub attribue automatiquement les réviseurs aux PR en fonction des fichiers modifiés. Créez `.github/CODEOWNERS` à la racine du dépôt :
+
+```
+# Framework core — affects every app; platform team reviews all changes
+packages/core/                     @your-org/platform-team
+
+# Dispatch control plane — secrets, integrations, workspace resources
+templates/dispatch/                @your-org/platform-team
+
+# Per-app ownership — each team reviews their own app
+templates/mail/                    @your-org/mail-team
+templates/analytics/               @your-org/analytics-team
+templates/calendar/                @your-org/calendar-team
+# ... add an entry per app
+
+# Workspace-level config — broad review since it affects everyone
+.github/                           @your-org/platform-team
+package.json                       @your-org/platform-team
+pnpm-workspace.yaml                @your-org/platform-team
+```
+
+Conseils clés : utilisez les équipes GitHub (`@org/team`), et non les individus. Les modifications du framework et de la répartition devraient toujours nécessiter un examen de la plate-forme. Voir [GitHub CODEOWNERS docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) pour la syntaxe globale et les modèles à propriétaires multiples.
+
+Pour activer les révisions requises : Paramètres → Branches → Protection des branches pour `main` → **Exiger une demande d'extraction avant la fusion** → **Exiger une révision des propriétaires de code**.
+
+## Étiquetage des relations publiques
+
+Étiqueter automatiquement les PR par application avec `.github/labeler.yml` (extrait) :
+
+```yaml
+app:mail:
+  - changed-files:
+      - any-glob-to-any-file: templates/mail/**
+app:analytics:
+  - changed-files:
+      - any-glob-to-any-file: templates/analytics/**
+core:
+  - changed-files:
+      - any-glob-to-any-file: packages/core/**
+```
+
+Ajoutez ensuite l'action [actions/labeler](https://github.com/actions/labeler) — consultez le README de ce dépôt pour le flux de travail complet YAML. Les étiquettes s'appliquent automatiquement lorsque les PR sont ouvertes ou mises à jour.
+
+## Consignes relatives à l'examen des relations publiques
+
+| Modifier le type                                | Qui évalue                                                 | À surveiller                                                                                               |
+| ----------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| **Application uniquement** (`templates/<app>/`) | Propriétaire de l'équipe de l'application                  | Excellence du domaine, schémas d'action                                                                    |
+| **Cadre** (`packages/core/`)                    | Équipe de plate-forme + une équipe d'application concernée | Modifications révolutionnaires, performances, compatibilité ascendante                                     |
+| **Migrations de schéma**                        | Équipe plateforme + ingénieur senior                       | Sécurité des données, agnosticisme dialectal (SQLite + Postgres)                                           |
+| **Actions**                                     | Équipe propriétaire                                        | Actions sont tous deux des points de terminaison des outils d'agent AND HTTP – examen sous les deux angles |
+| **Inter-application A2A**                       | Les deux équipes d'application                             | Si vous modifiez une interface A2A, les appelants doivent le savoir                                        |
+| **Répartir le coffre-fort/les ressources**      | Équipe Plateforme                                          | Accès secret, portée d'octroi, qui obtient quoi                                                            |
+
+### Travail d'agent simultané
+
+Les espaces de travail natifs pour agents comportent souvent plusieurs agents IA travaillant simultanément sur la même branche. C'est inhérent à la conception : les agents partagent une branche et effectuent des opérations indépendantes.
+
+```an-callout
+{ "tone": "warning", "body": "**The later commit wins.** Two agents touching the same file won't conflict at commit time — the conflict surfaces at review. Run `pnpm run prep` (typecheck + test + format) before pushing, and don't revert changes you didn't make unless they're clearly broken." }
+```
+
+Lors de l'examen des PR dans cet environnement :
+
+- **N'annulez pas les modifications que vous n'avez pas apportées** à moins qu'elles ne soient clairement rompues
+- **Les fichiers peuvent être modifiés par plusieurs agents** dans le même PR — c'est normal
+- **Exécutez `pnpm run prep`** (vérification de type + test + format) avant de pousser pour détecter les problèmes d'intégration entre les modifications des agents
+- **Si deux agents touchent le même fichier**, la validation la plus récente l'emporte. Les conflits font surface au moment de l'examen, pas au moment de la validation
+- **Corrigez les bugs dans n'importe quel code du PR,** quel que soit l'agent qui l'a écrit. Le PR est examiné dans son ensemble.
+
+## Répartition en tant que gouvernance
+
+L'application [Dispatch](/docs/dispatch) est le plan de contrôle d'exécution de l'espace de travail. Il complète la gouvernance au niveau Git avec la gouvernance d'exécution :
+
+| Inquiétudes                               | Git / GitHub                        | Expédition                                                                 |
+| ----------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------- |
+| Qui peut modifier le code                 | CODEOWNERS, protection des branches | —                                                                          |
+| Qui peut accéder aux secrets              | —                                   | Règle de Vault, subventions, workflow de demande                           |
+| Quelles instructions suivent les agents   | —                                   | Ressources de l'espace de travail global (AGENTS.md, instructions, skills) |
+| Quels agents sont partagés                | —                                   | Profils d'agent Workspace                                                  |
+| Inventaire d'intégration                  | —                                   | Catalogue de connexions et d'intégrations Workspace                        |
+| Approbation des modifications d'exécution | —                                   | Flux d'approbation d'envoi                                                 |
+| Piste d'audit                             | `git log` / `git blame`             | Audit du coffre-fort + journaux d'audit de répartition                     |
+| Messagerie et routage                     | —                                   | Slack / Intégration Telegram                                               |
+
+**Git gère la gouvernance du code. Dispatch gère la gouvernance d'exécution.** N'essayez pas de répliquer les workflows git dans Dispatch ou vice versa.
+
+Dispatch gère : les secrets du coffre-fort, les connexions à l'espace de travail réutilisables, les ressources de l'espace de travail (skills, instructions, profils d'agent, serveurs MCP), les approbations et les journaux d'audit. Pour la configuration de l'itinéraire de l'application publique (`workspaceApp.audience` / `publicPaths` / `protectedPaths`), voir [Multi-App Workspaces — Public app routes](/docs/multi-app-workspace#deployment).
+
+Pour le modèle de ressource et les chemins canoniques, voir [Workspace — Global resources](/docs/workspace#global-resources).
+
+## Liste de contrôle de configuration
+
+Pour un nouvel espace de travail, après avoir exécuté `npx @agent-native/core@latest create` :
+
+**Git & GitHub :**
+
+- [ ] Créez `.github/CODEOWNERS` avec propriété d'équipe par application
+- [ ] Activer la protection des branches sur `main` avec les révisions requises du propriétaire du code
+- [ ] Ajoutez `.github/labeler.yml` pour l'étiquetage automatique des PR par application
+- [ ] Créer des équipes GitHub pour chaque application et l'équipe de plateforme
+
+**Expédition :**
+
+- [ ] Ajouter des secrets partagés au coffre-fort (clés API, informations d'identification OAuth, etc.)
+- [ ] Conservez la stratégie de coffre-fort par défaut pour toutes les applications ou passez aux subventions manuelles par application
+- [ ] Synchronisez les secrets du coffre-fort pour les transmettre aux applications
+- [ ] Enregistrez les connexions d'espace de travail réutilisables pour les comptes de fournisseur partagés, puis
+      accorder des applications telles que Brain, Analytics, Mail ou Dispatch uniquement lorsqu'elles en ont besoin
+      ce compte
+- [ ] Ajoutez skills à l'échelle de l'espace de travail, des instructions de garde-corps et des ressources de référence de marque/entreprise via la page Ressources. Voir [Workspace](/docs/workspace#global-resources) pour le tableau complet du modèle de ressource et le pack de démarrage recommandé.
+- [ ] Configurer la politique d'approbation et les e-mails des approbateurs
+- [ ] Configurer SendGrid (`SENDGRID_API_KEY`, `SENDGRID_FROM_EMAIL`) pour les notifications d'administrateur
+- [ ] Connectez Slack ou Telegram pour la messagerie de l'espace de travail
+- [ ] Configurez les serveurs MCP partagés : ajoutez des ressources d'espace de travail `mcp-servers/<name>.json` dans Dispatch pour les subventions pour toutes les applications ou les applications sélectionnées ; utilisez `mcp.config.json` ou [MCP hub mode](/docs/mcp-clients#hub) pour les déploiements de niveau inférieur