@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/fr-FR/template-analytics.md

@@ -0,0 +1,259 @@
+---
+title: "Analyses"
+description: "Posez des questions d'analyse dans un anglais simple, récupérez des graphiques et des tableaux de bord. Un remplacement open source pour Amplitude, Mixpanel et Looker."
+---
+
+# Analyses
+
+Posez des questions d'analyse dans un anglais simple, récupérez des graphiques et des tableaux de bord. L'agent se connecte à BigQuery, GA4, Amplitude, le collecteur d'événements propriétaire intégré, HubSpot, Jira et une douzaine d'autres sources, écrit la requête pour vous, la valide et affiche la réponse sous forme de graphique, de tableau ou de panneau de tableau de bord enregistré.
+
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='display:flex;flex-direction:column;gap:14px;padding:18px;min-height:500px;box-sizing:border-box'><h1 style='margin:0'>Agent-Native Templates</h1><p class='wf-muted' style='margin:0'>Adoption and engagement across the last 12 weeks.</p><div style='display:grid;grid-template-columns:repeat(3,1fr);gap:12px'><div class='wf-card'><small class='wf-muted'>Weekly active users</small><br/><strong>24,318</strong><br/><span class='wf-pill accent'>+12.4%</span></div><div class='wf-card'><small class='wf-muted'>New signups</small><br/><strong>1,842</strong><br/><span class='wf-pill accent'>+8.7%</span></div><div class='wf-card'><small class='wf-muted'>Revenue MRR</small><br/><strong>$48,210</strong><br/><span class='wf-pill accent'>+21.3%</span></div></div><div style='display:grid;grid-template-columns:1fr 1fr;gap:12px;flex:1'><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Weekly active users</strong><div style='flex:1;display:flex;align-items:end;gap:8px'><div style='height:38%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:44%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:58%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:74%;flex:1;background:var(--wf-accent-soft)'></div></div></div><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Revenue over time</strong><div style='flex:1;display:flex;align-items:end;gap:8px'><div style='height:32%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:48%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:63%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:80%;flex:1;background:var(--wf-accent-soft)'></div></div></div></div><div class='wf-card'><strong>Signups by source</strong><br/><small class='wf-muted'>Lower chart begins below the main charts.</small></div></div>"
+}
+```
+
+Il s'agit d'un remplacement open source d'Amplitude, Mixpanel et Looker, destiné aux équipes qui souhaitent posséder le code, les requêtes et les données.
+
+```an-diagram title="Question to chart" summary="The agent consults the data dictionary, writes SQL, validates it against the warehouse, then renders a chart or saves a panel."
+{
+  "html": "<div class=\"diagram-flow\"><div class=\"diagram-node\">Plain-English<br>question</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Agent</span><small class=\"diagram-muted\">reads data dictionary</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Writes SQL</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill ok\">Dry-run validate</div><small class=\"diagram-muted\">BigQuery / source</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Chart, table, or<br>saved panel</div></div>",
+  "css": ".diagram-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-flow .diagram-col{display:flex;flex-direction:column;gap:6px;align-items:center}.diagram-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-flow .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Ce que vous pouvez en faire
+
+- **Posez des questions sur les données dans un anglais simple.** "Quel pourcentage d'inscriptions le mois dernier ont été converties en inscriptions payantes ?" ou "Montrez-moi les utilisateurs actifs hebdomadaires au cours des 6 derniers mois." L'agent sélectionne la bonne source, écrit le SQL et restitue le graphique.
+- **Créez des tableaux de bord SQL réutilisables** avec des filtres, des vues enregistrées et des requêtes paramétriques.
+- **Exécutez des analyses ad hoc** qui croisent plusieurs sources de données, enregistrées sous forme d'enquêtes réexécutables avec la question, les instructions et les résultats d'origine.
+- **Maintenez un dictionnaire de données évolutif** de métriques, de tables et de recettes SQL afin que l'agent utilise les bons noms de colonnes à chaque fois (plus besoin de deviner `is_closed` alors qu'il s'agit en réalité de `hs_is_closed`).
+- **Partagez des tableaux de bord** avec votre équipe : privés par défaut, partageables par utilisateur ou par organisation avec des rôles de lecteur/éditeur/administrateur.
+- **Connectez-vous à de nombreuses sources** prêtes à l'emploi : BigQuery, GA4, Mixpanel, Amplitude, PostHog, HubSpot, Jira, Apollo, Pylon, Gong, Common Room, Twitter, ainsi que des sources SEO spécifiques aux applications.
+- **Réutiliser les intégrations d'espace de travail** lorsqu'un espace de travail est déjà connecté et
+  a attribué un fournisseur à Analytics. Le fournisseur de magasins d'intégration partagés
+  références d'identité et d'informations d'identification ; Analytics conserve la sélection de sources spécifiques à l'application,
+  Entrées du dictionnaire de données, tableau de bord SQL et historique d'analyse.
+
+## Démarrer
+
+Démo en direct : [analytics.agent-native.com](https://analytics.agent-native.com).
+
+Lorsque vous ouvrez l'application pour la première fois :
+
+1. Connectez-vous avec Google.
+2. Ouvrez la page **Sources de données** à partir de la barre latérale.
+3. Chaque source est accompagnée d'une procédure pas à pas : connectez celles dont vous avez besoin (commencez par une seule, comme BigQuery, GA4, Amplitude ou un suivi propriétaire).
+4. Ouvrez une nouvelle discussion avec l'agent et posez une question : "Combien d'inscriptions avons-nous reçu la semaine dernière ?"
+
+La première question suffit à confirmer que la connexion fonctionne. À partir de là, demandez à l'agent de « enregistrer ceci en tant que tableau de bord » ou de « créer un tableau de bord de présentation à 4 panneaux pour nos indicateurs clés ».
+
+### Invites utiles
+
+- "Créez un tableau de bord montrant les utilisateurs actifs hebdomadaires au cours des 6 derniers mois."
+- "Quel pourcentage d'inscriptions le mois dernier ont été converties en inscriptions payantes ?"
+- "Ajoutez un graphique comparant les revenus par plan à ce tableau de bord."
+- "Réorganisez les panneaux de ce tableau de bord pour que la métrique MRR vienne en premier."
+- "Analysez nos transactions conclues-perdues du premier trimestre et enregistrez l'analyse."
+- "Réexécutez l'analyse du taux de désabonnement avec les données de ce mois-ci."
+- "Documenter cette métrique dans le dictionnaire de données."
+
+L'agent sait toujours ce que vous regardez : tableau de bord actuel, filtres, vue – vous pouvez donc dire « ce tableau de bord » ou « ce panneau » sans être explicite.
+
+## Trois choses à savoir
+
+L'application comporte trois surfaces principales sur lesquelles vous passerez du temps :
+
+- **Tableaux de bord SQL** : panneaux réutilisables avec filtres et vues enregistrées. Idéal pour les statistiques que vous vérifiez régulièrement.
+- **Analyses ad hoc** : enquêtes longues provenant de plusieurs sources, avec des instructions de réexécution enregistrées à côté. Idéal pour les questions ponctuelles que vous souhaiterez peut-être revoir.
+- **Data Dictionary** — le catalogue canonique de métriques, de tables, de colonnes et de recettes SQL. L'agent le consulte avant d'écrire un SQL. Il utilise donc de vrais noms de colonnes d'entrepôt et connaît les mises en garde telles que « exclut les e-mails internes ».
+
+Le dictionnaire est généré en demandant à l'agent : "importer nos définitions dbt" ou "extraire les métriques de notre manuel Notion" et il fait le travail.
+
+## Pour les développeurs
+
+Le reste de ce document s'adresse à toute personne qui crée ou étend le modèle Analytics.
+
+### Démarrage rapide
+
+Créez une nouvelle application Analytics à partir du CLI :
+
+```bash
+npx @agent-native/core@latest create my-analytics --standalone --template analytics
+```
+
+Développeur local :
+
+```bash
+cd my-analytics
+pnpm install
+pnpm dev
+```
+
+Le CLI imprime le développement local URL. Connectez-vous avec Google, puis ouvrez la page **Sources de données** pour connecter BigQuery, GA4, le suivi propriétaire, HubSpot, Jira et les autres.
+
+### Fonctionnalités clés
+
+**Posez des questions, obtenez des graphiques.** L'agent sélectionne une source de données, écrit et valide SQL, puis affiche un graphique, un tableau, une métrique ou un panneau enregistré.
+
+**Tableaux de bord et enquêtes.** Les tableaux de bord réutilisables conservent les panneaux SQL, les filtres, les vues enregistrées et le partage ; les analyses ad hoc enregistrent des résultats plus longs avec des instructions de réexécution.
+
+**Dictionnaire de données évolutif.** Les définitions de métriques, les propriétaires, les tables sources et les mises en garde connues donnent à l'agent le véritable vocabulaire de l'entrepôt avant d'écrire des requêtes.
+
+**Large surface de connecteur.** Les événements BigQuery, GA4, analyses de produits, CRM, support, communauté, GitHub/Jira, SEO et `/track` propriétaires passent tous par actions que l'agent peut appeler.
+
+### Travailler avec l'agent
+
+L'agent sait toujours ce que vous regardez. L'état actuel de l'écran est injecté dans chaque message sous forme de bloc `<current-screen>` : il contient la vue active, le tableau de bord ou l'analyse ouvert et tous les filtres sélectionnés.
+
+L'invite système de l'agent reçoit un bloc `<data-dictionary>` injecté avec les entrées de métriques approuvées pour l'organisation active. Lorsque vous demandez un tableau de bord, l'agent consulte d'abord le dictionnaire et utilise textuellement les documents `table` / `columns` / `queryTemplate` documentés — il ne devine pas les noms de colonnes.
+
+**Contexte qu'il a automatiquement :**
+
+- **Vue actuelle** : `overview`, `adhoc` (avec `dashboardId`), `analyses` (avec `analysisId`), `data-dictionary`, `data-sources` ou `settings`.
+- **Organisation active** : s'étend à toutes les requêtes et écritures.
+- **Entrées de dictionnaire approuvées** — pour l'espace de travail actif.
+
+**Modifications du tableau de bord.** L'agent utilise l'action `update-dashboard` pour modifier les tableaux de bord. Il prend en charge deux modes :
+
+- `ops` — Patchs JSON-Pointer pour les modifications chirurgicales (déplacer un panneau, remplacer une chaîne SQL, supprimer un filtre).
+- `config` — remplacement complet de la configuration du tableau de bord.
+
+Le SQL de chaque panneau BigQuery est testé à sec sur l'entrepôt avant l'enregistrement du tableau de bord. Si une colonne est erronée, l'enregistrement est rejeté avec l'erreur BigQuery : l'agent corrige le SQL et réessaye au lieu de conserver les panneaux cassés.
+
+### Connexion des sources de données
+
+Ouvrez la page **Sources de données** (`/data-sources`) pour connecter les fournisseurs. Chacun
+la source expose une liste de clés d'environnement, une procédure pas à pas et un bouton **Test de connexion**.
+Lorsque Analytics est exécuté dans un espace de travail, `data-source-status` génère également des rapports
+accorde des connexions d'espace de travail réutilisables pour `appId=analytics` afin que l'agent puisse
+demandez une autorisation d'application au lieu d'une autre copie de la même clé de fournisseur.
+Pour les fournisseurs réutilisables tels que Slack, HubSpot, Notion et GitHub, les données
+Les sources UI montrent directement l'état d'intégration partagé : prêt via l'espace de travail,
+nécessite une autorisation, nécessite des informations d'identification ou des informations d'identification locales.
+
+Les intégrations d'espaces de travail réutilisables constituent la direction d'exécution pour les fournisseurs partagés :
+le framework stocke l'identité du fournisseur, les métadonnées du compte, les références d'informations d'identification et
+octroie une fois par application ; Analytics stocke l'interprétation de la source de données, la source de
+choix de vérité, définitions de métriques, tableaux de bord et analyses.
+
+Les informations d'identification sont stockées via la couche paramètres/env du framework — aucun secret dans git. La production nécessite :
+
+| Variable                                 | Objectif                                                               |
+| ---------------------------------------- | ---------------------------------------------------------------------- |
+| `DATABASE_URL`                           | Connexion persistante SQL URL                                          |
+| `BETTER_AUTH_SECRET` / `BETTER_AUTH_URL` | Authentification                                                       |
+| `GOOGLE_SIGN_IN_CLIENT_ID` / `_SECRET`   | Client de connexion Google préféré (OAuth 2.0)                         |
+| `GOOGLE_CLIENT_ID` / `_SECRET`           | Ancien système de secours de connexion/client d'intégration Google API |
+| `BIGQUERY_PROJECT_ID`                    | Projet BigQuery                                                        |
+| `GOOGLE_APPLICATION_CREDENTIALS_JSON`    | Compte de service BigQuery JSON                                        |
+| `ANTHROPIC_API_KEY`                      | Discussion avec les agents                                             |
+
+Les clés spécifiques au fournisseur (HubSpot, Jira, Gong, Pylon, etc.) sont documentées dans la procédure pas à pas de chaque source sur la page Sources de données. Si vous ajoutez une nouvelle action nécessitant une clé API, elle apparaît comme une nouvelle source sur cette page via l'enregistrement d'intégration du modèle.
+
+Remarque : l'identifiant BigQuery OAuth pour la connexion à Google est un **séparé**
+identifiant du compte de service BigQuery JSON. Créez le client de connexion sur
+Console GCP → API et services → Identifiants → ID client OAuth, et préférez le
+Noms d'environnement `GOOGLE_SIGN_IN_CLIENT_ID` / `GOOGLE_SIGN_IN_CLIENT_SECRET` donc ceci
+Le client de connexion à faible portée reste distinct des clients d'intégration Google API.
+
+### Modèle de données
+
+Tableaux de base (voir `templates/analytics/server/db/schema.ts`) :
+
+```an-schema title="Analytics data model" summary="Dashboards and analyses are the resources; views, shares, and a query cache hang off them. Org tables come from @agent-native/core/org."
+{
+  "entities": [
+    {
+      "id": "dashboards",
+      "name": "dashboards",
+      "note": "Explorer and SQL dashboards",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "kind", "type": "text", "note": "\"explorer\" or \"sql\"" },
+        { "name": "config", "type": "text", "note": "JSON matching SqlDashboardConfig" }
+      ]
+    },
+    {
+      "id": "dashboard_views",
+      "name": "dashboard_views",
+      "note": "Saved filter presets per dashboard",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "dashboard_id", "type": "text", "fk": "dashboards.id" }
+      ]
+    },
+    {
+      "id": "analyses",
+      "name": "analyses",
+      "note": "Re-runnable ad-hoc investigations",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "question", "type": "text" },
+        { "name": "instructions", "type": "text", "note": "Re-run steps" },
+        { "name": "dataSources", "type": "text", "note": "Sources touched" },
+        { "name": "resultMarkdown", "type": "text" },
+        { "name": "resultData", "type": "text", "nullable": true }
+      ]
+    },
+    {
+      "id": "bigquery_cache",
+      "name": "bigquery_cache",
+      "note": "Result cache keyed by SQL hash",
+      "fields": [
+        { "name": "sql_hash", "type": "text", "pk": true },
+        { "name": "bytes_processed", "type": "integer" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "dashboards", "to": "dashboard_views", "kind": "1-n", "label": "saved views" }
+  ]
+}
+```
+
+Plus les tables de partage par ressource (`dashboard_shares`, `analysis_shares`) et les tables d'organisation (`organizations`, `org_members`, `org_invitations`) fournies par `@agent-native/core/org`. Le dictionnaire de données se trouve dans la table `settings` du framework sous les clés de portée.
+
+- **`dashboards`** : tableaux de bord Explorer et SQL. `kind` est `"explorer"` ou `"sql"` ; `config` est un blob JSON correspondant à `SqlDashboardConfig`.
+- **`dashboard_shares`** – attributions de partages par ressource (principal, rôle).
+- **`dashboard_views`** – préréglages de filtres enregistrés par tableau de bord.
+- **`analyses`** – enquêtes ad hoc avec `question`, `instructions`, `dataSources`, `resultMarkdown` et `resultData` en option.
+- **`analysis_shares`** – attributions de partage par ressource pour les analyses.
+- **`bigquery_cache`** — cache des résultats de la requête saisi par le hachage SQL avec comptabilité traitée en octets.
+
+Plus les tables organisationnelles (`organizations`, `org_members`, `org_invitations`) fournies par `@agent-native/core/org`.
+
+Le dictionnaire de données se trouve dans la table `settings` du framework sous les clés de portée ; voir les modèles `list-data-dictionary` et `save-data-dictionary-entry` actions pour la forme complète.
+
+### Le personnaliser
+
+Le modèle Analytics est destiné à être dérivé et étendu. Tout vit dans `templates/analytics/` :
+
+- **`AGENTS.md`** : guide de niveau supérieur de l'agent. Vues de documents, actions et flux de travail.
+- **`actions/`** — chaque opération appelable par un agent. Ajouter un nouveau fichier pour ajouter une nouvelle action. Les plus notables :
+  - `update-dashboard.ts` – modifications du tableau de bord (opérations + remplacement complet)
+  - `save-analysis.ts` / `list-analyses.ts` — analyses ad hoc
+  - `save-data-dictionary-entry.ts` / `list-data-dictionary.ts` — dictionnaire
+  - `bigquery.ts` – exécution brute de BigQuery
+  - `view-screen.ts` / `navigate.ts` – conscience du contexte
+- **`app/routes/`** — itinéraires basés sur des fichiers. Chaque itinéraire est une fine enveloppe autour d'une page dans `app/pages/`.
+- **`app/pages/adhoc/sql-dashboard/`** : rendu du tableau de bord SQL, éditeur de panneaux, barre de filtre, vues enregistrées.
+- **`app/pages/analyses/`** — analyse la liste et la vue détaillée.
+- **`app/pages/DataSources.tsx`** – l'intégration de la source de données UI.
+- **`app/pages/DataDictionary.tsx`** — le navigateur et éditeur de dictionnaire.
+- **`.agents/skills/`** — les modèles de guides que l'agent lit à la demande :
+  - `dashboard-management` – stockage, résolution de la portée, forme de configuration du tableau de bord
+  - `data-querying` — quel script rechercher, modèles de filtrage
+  - `adhoc-analysis` – workflow pour les enquêtes multi-sources
+  - `data-querying`, `real-time-sync`, `frontend-design`, `storing-data`, `self-modifying-code`
+- **`.builder/skills/<provider>/SKILL.md`** : pièges spécifiques au fournisseur (BigQuery, HubSpot, Jira, GA4, etc.). Lire avant d'interroger ; mettre à jour lorsque vous apprenez quelque chose de nouveau.
+- **`server/db/schema.ts`** : schéma Drizzle pour les tableaux de bord, les partages, les vues, les analyses et le cache BigQuery.
+- **`server/lib/dashboards-store.ts`** — lecture/écriture du tableau de bord avec résolution de portée et migration KV héritée.
+- **`server/lib/bigquery.ts`** – Client BigQuery, validateur à sec, logique de cache.
+
+Pour ajouter une nouvelle source de données, déposez un script dans `actions/` qui appelle le fournisseur et renvoie les résultats via l'assistant `output()`. Il devient immédiatement disponible pour l'agent et peut être utilisé dans les panneaux du tableau de bord (si vous exposez le résultat via un gestionnaire de serveur).
+
+Pour ajouter un nouveau type de graphique, étendez l'union `ChartType` dans `app/pages/adhoc/sql-dashboard/types.ts`, gérez-la dans `SqlChartCard.tsx` et l'agent peut l'utiliser dans n'importe quel panneau.
+
+Pour un modèle plus large sur l'extension des modèles, voir [Skills guide](/docs/skills-guide) et [Actions](/docs/actions).

package/corpus/core/docs/content/locales/fr-FR/template-assets.md

@@ -0,0 +1,303 @@
+---
+title: "Actifs"
+description: "Un gestionnaire d'actifs numériques natif et un service de génération multi-agents pour des médias cohérents avec la marque."
+---
+
+# Actifs
+
+Assets est un espace de travail natif pour les agents permettant de créer et de gérer des médias cohérents avec la marque. Il organise les téléchargements et les résultats générés dans des bibliothèques et des dossiers, permet aux équipes de collecter des exemples de héros de blog, de diagrammes, de pages de destination, de photos de produits, de vidéos et de logos, puis achemine la génération via le chat de l'agent afin que chaque élément puisse être examiné et affiné.
+
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='display:flex;flex-direction:column;gap:14px;padding:18px;min-height:520px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>Launch brand</h1><span class='wf-pill accent'>Blog heroes</span><span class='wf-pill'>Product shots</span><span class='wf-pill'>Logos</span><div style='flex:1'></div><button>Upload</button><button class='primary'>Generate</button></div><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Create brand media</strong><div class='wf-box'>Three homepage hero options using the approved logo and product references.</div><div style='display:flex;gap:8px;flex-wrap:wrap'><span class='wf-pill accent'>4 references</span><span class='wf-pill'>16:9</span><span class='wf-pill'>Web export</span></div></div><div style='display:grid;grid-template-columns:repeat(3,1fr);gap:12px;flex:1'><div class='wf-card' style='display:flex;align-items:end;min-height:130px'><span class='wf-pill accent'>Hero A</span></div><div class='wf-card' style='display:flex;align-items:end;min-height:130px'><span class='wf-pill'>Reference set</span></div><div class='wf-card' style='display:flex;align-items:end;min-height:130px'><span class='wf-pill'>Logo safe</span></div></div><div class='wf-card' style='display:grid;grid-template-columns:repeat(4,1fr);gap:8px'><div class='wf-box'>Use</div><div class='wf-box'>Refine</div><div class='wf-box'>Compare</div><div class='wf-box'>Export</div></div></div>"
+}
+```
+
+Lorsque vous ouvrez l'application, la bibliothèque sélectionnée, l'invite, les références et les candidats générés restent dans un seul espace de travail. L'agent peut parcourir, rechercher, générer, affiner et exporter chaque actif via le même actions que le UI.
+
+```an-diagram title="Generate, review, reuse" summary="References and prompts feed a generate-and-choose session; chosen assets land in a library and flow out to other apps via the picker or A2A."
+{
+  "html": "<div class=\"diagram-assets\"><div class=\"diagram-col\"><div class=\"diagram-node\">References<br><small class=\"diagram-muted\">logos, product shots, style</small></div><div class=\"diagram-node\">Prompt<br><small class=\"diagram-muted\">chat or Generate controls</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><span class=\"diagram-pill accent\">Generation session</span><small class=\"diagram-muted\">image &amp; video candidates · audit log</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><span class=\"diagram-pill ok\">Library</span><small class=\"diagram-muted\">chosen, brand-consistent assets</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-node\">Picker<br><small class=\"diagram-muted\">iframe / MCP App</small></div><div class=\"diagram-node\">A2A<br><small class=\"diagram-muted\">Slides · Design · Content</small></div></div></div>",
+  "css": ".diagram-assets{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-assets .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-assets .diagram-box{display:flex;flex-direction:column;gap:4px}.diagram-assets .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+## Quand le choisir
+
+- **Votre équipe a besoin d'une direction visuelle réutilisable**, et non d'invites multimédias génériques uniques : collectez des logos approuvés, des photos de produits et des exemples de style afin que les générations restent fidèles à la marque.
+- **Vous souhaitez que les médias générés soient examinés et affinés**, avec un journal d'audit complet des invites, des modèles, des références et du lignage pour chaque exécution.
+- **D'autres applications nécessitent un sélecteur ou un générateur d'éléments** : Slides, Design, Content, un éditeur de blog ou un créateur de site peuvent intégrer le sélecteur ou appeler des éléments via A2A.
+- **Vous souhaitez que les médias de marque soient disponibles auprès de votre agent de codage** : Codex, Claude Code, Claude ou ChatGPT peuvent générer et sélectionner des éléments sans quitter le chat.
+
+## Démarrer
+
+Démo en direct : [assets.agent-native.com](https://assets.agent-native.com).
+
+1. **Créez une bibliothèque.** Ajoutez la marque, la campagne, le produit ou le flux de contenu que vous souhaitez
+   veulent gérer.
+2. **Téléchargez des références.** Ajoutez des logos approuvés, des photos de produits, des exemples de style ou
+   des vidéos existantes afin que l'agent dispose de matériel concret sur lequel travailler.
+3. **Générez à partir d'un chat ou d'une bibliothèque.** Demandez une image de héros, un diagramme, un produit
+   prise de vue ou variante vidéo. Les ressources stockent l'invite, les références, le modèle, le statut,
+   et lignée pour examen.
+4. **Utilisez l'élément ailleurs.** Copiez l'exportation, intégrez le sélecteur dans un autre
+   application, ou laissez un autre agent appeler Assets via A2A.
+
+## Invites utiles
+
+- "Générez trois options de héros de blog à l'aide des références de produits Acme."
+- "Créez une image sociale carrée dans le style d'une campagne de lancement."
+- "Rechercher tous les éléments approuvés pour la refonte de l'intégration."
+- "Transformez ce diagramme téléchargé en une image explicative du produit plus claire."
+- "Créez un storyboard vidéo et enregistrez le meilleur ensemble d'images dans cette bibliothèque."
+
+## Ce que vous pouvez en faire
+
+- **Créez des bibliothèques d'éléments.** Regroupez les images de référence, les vidéos, les logos canoniques, les notes de style, les palettes, les dossiers et les résultats générés par marque, campagne, produit ou catégorie.
+- **Générer via le chat.** Les contrôles de génération du composeur d'accueil et de la bibliothèque envoient l'invite à l'agent avec `sendToAgentChat()`, afin que les utilisateurs puissent inspecter les variantes, donner leur avis et itérer.
+- **Générer des images et des vidéos.** La génération d'images gérée par Builder est disponible lorsqu'elle est activée, et Gemini alimente la génération vidéo ainsi que le repli manuel des images.
+- **Téléchargez et décrivez les références.** Ajoutez des images ou des vidéos de la bibliothèque UI ou du bouton de pièce jointe du compositeur d'invite, puis recherchez par titre, description, texte alternatif, invite, modèle, type de média, statut, rôle, dossier ou collection.
+- **Conservez un journal d'audit de génération.** Chaque exécution enregistre les invites, le modèle, les proportions, les références, l'actif source, le lignage, les actifs générés, l'état, les erreurs et les horodatages pour une révision ultérieure de la conception.
+- **Préserver la précision du logo.** L'agent peut générer une zone d'espace réservé et le serveur compose le logo canonique téléchargé sur l'image finale au lieu de s'appuyer sur le modèle d'image pour le redessiner.
+- **Intégrer en tant que sélecteur.** D'autres applications peuvent iframer `/picker` et écouter l'événement `chooseAsset` de `@agent-native/embedding`, transformant ainsi les ressources en un sélecteur/générateur d'actifs pour les éditeurs de blogs, les créateurs de sites, les présentations de diapositives et les applications personnalisées. Le sélecteur émet également l'ancien alias `chooseImage` pour les hôtes d'images uniquement existants.
+- **Installer en tant que compétence basée sur une application.** Le manifeste `agent-native.app-skill.json` exporte une compétence Actifs ainsi que les métadonnées du connecteur MCP afin que les places de marché puissent installer ensemble l'application, ses instructions et son sélecteur.
+- **Servir d'autres agents.** Slides, Design, Content, Mail et Dispatch peuvent appeler des ressources via A2A pour répertorier les bibliothèques, générer des lots, créer des vidéos, affiner une ressource, récupérer des exportations et afficher des aperçus en ligne là où l'intégration est autorisée.
+
+## L'utiliser depuis votre agent de codage
+
+Générez et sélectionnez des médias de marque sans quitter le code Codex, Claude, Claude ou ChatGPT.
+
+1. **Installer une fois.** Cela ajoute les instructions de compétence et enregistre le connecteur MCP hébergé ensemble :
+
+   ```bash
+   npx @agent-native/core@latest skills ajouter des actifs # alias : génération d'images
+   ```
+
+   Le client par défaut est `codex` ; ajoutez `--client claude-code` ou `--client all` pour les autres.
+   Si vous souhaitez uniquement les instructions de compétences portables via Vercel/open
+   Skills CLI, utilisez :
+
+   ```bash
+   npx skills@dernier ajout d'actifs BuilderIO/agent-native --skill
+   ```
+
+   Le Vercel/open Skills CLI installe uniquement le fichier d'instructions ; ce n'est pas le cas
+   exécutez la configuration du connecteur MCP. Utilisez le chemin Agent Native CLI ci-dessus quand vous le souhaitez
+   la configuration en une seule commande.
+
+2. **Demandez des images.** Dans le chat de votre agent : "Générez trois options de héros de blog à partir des photos du produit Acme." L'agent ouvre le sélecteur avec des images candidates que vous pouvez régénérer, réajuster (invite, aspect, nombre) et parmi lesquelles choisir.
+3. **Pick.** Dans les hôtes en ligne (ChatGPT, Claude.ai, discussion principale du bureau Claude), le sélecteur s'affiche directement dans le chat : cliquez sur un candidat et le choix revient automatiquement. Sur les hôtes CLI/lien uniquement (Codex, Code Claude, onglet "Code" du bureau Claude), vous obtenez un lien **"Ouvrir dans les actifs →"** ; ouvrez-le, sélectionnez-le dans le navigateur, puis collez le résumé du transfert copié dans votre chat — ou dites simplement « utiliser l'image A ».
+
+   ```texte
+   Recollez cette sélection dans votre chat afin que l'agent puisse l'utiliser.
+
+   Image des éléments sélectionnés pour l'étape suivante : <label>
+   Médias URL : <url>
+   Utiliser cet élément sélectionné dans l'artefact ou la conception actuelle.
+
+   Contexte de l'élément sélectionné :
+   { "selectedAsset": { "assetId": "...", "url": "...", "mediaType": "image", ... } }
+   ```
+
+4. **Appliquer au code.** Les Media URL et `assetId` choisis reviennent à l'agent, qui utilise le URL directement dans le code qu'il écrit (un src `<img>`, un téléchargement) ou appelle `export-asset`.
+
+## Pour les développeurs
+
+Le reste de ce document s'adresse à toute personne qui crée ou étend le modèle Assets.
+
+### Échafaudage
+
+```bash
+npx @agent-native/core@latest create my-assets --standalone --template assets
+```
+
+### Modèle de données
+
+Toutes les données se trouvent dans SQL via Drizzle ORM (les supports binaires se trouvent dans le stockage d'objets ou dans la solution de secours de téléchargement de fichiers local pendant le développement). Schéma : `templates/assets/server/db/schema.ts`. Les bibliothèques proposent le standard `ownableColumns` et une table de partages de framework correspondante, elles s'intègrent donc dans le modèle de partage par utilisateur/par organisation.
+
+Remarque : les noms de table SQL conservent l'ancien préfixe `image_*` datant de l'époque où l'application s'appelait Images. Ils couvrent également les vidéos et d'autres médias.
+
+| Tableau                          | Ce qu'il contient                                                                                                                                                                                                                                 |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `image_libraries`                | Une bibliothèque : le conteneur de niveau supérieur regroupé par marque, campagne, produit ou catégorie. Contient `custom_instructions`, `style_brief`, le logo canonique et les références d'actifs de couverture, ainsi que l'état de l'archive |
+| `image_library_shares`           | Framework partage les principaux de mappage de table (utilisateurs ou organisations) avec les rôles (spectateur, éditeur, administrateur) par bibliothèque                                                                                        |
+| `image_collections`              | Regroupements de styles/catégories dans une bibliothèque – `style_brief`, `prompt_template`, rapport hauteur/largeur par défaut et taille de l'image                                                                                              |
+| `asset_folders`                  | Dossiers emboîtables dans une bibliothèque (`parent_id` pour la hiérarchie)                                                                                                                                                                       |
+| `image_generation_presets`       | Recettes de génération enregistrées : type de média, modèle d'invite, format d'image, modèle et stratégie de texte/référence                                                                                                                      |
+| `image_generation_sessions`      | Une session itérative de génération et de sélection avec un résumé, un statut, un actif actif et un résumé des commentaires                                                                                                                       |
+| `image_generation_session_items` | Actifs du candidat au sein d'une session, chacun avec un rôle et une note                                                                                                                                                                         |
+| `image_assets`                   | L'enregistrement de l'élément : type de média, rôle, statut, titre/description/texte alternatif, invite, modèle, dimensions, type MIME, clés d'objet/vignette et lignée                                                                           |
+| `image_generation_runs`          | Le journal d'audit de génération : invite, invite compilée, modèle, références, statut, erreurs et `source` (`chat` / `ui` / `a2a`) qui l'a déclenché                                                                                             |
+
+```an-schema title="Assets data model" summary="Libraries are the ownable container; collections, folders, and presets organize them. Sessions drive generate-and-choose; assets and runs hold output and the audit log. Table names keep the legacy image_* prefix but cover all media."
+{
+  "entities": [
+    { "id": "library", "name": "image_libraries", "note": "Top-level ownable container", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "custom_instructions", "type": "text", "nullable": true },
+      { "name": "style_brief", "type": "text", "nullable": true },
+      { "name": "logo_asset_id", "type": "id", "fk": "image_assets.id", "nullable": true },
+      { "name": "archived", "type": "boolean" }
+    ] },
+    { "id": "library_shares", "name": "image_library_shares", "note": "Framework shares table", "fields": [
+      { "name": "library_id", "type": "id", "fk": "image_libraries.id" },
+      { "name": "role", "type": "text", "note": "viewer / editor / admin" }
+    ] },
+    { "id": "collections", "name": "image_collections", "note": "Style/category groupings", "fields": [
+      { "name": "library_id", "type": "id", "fk": "image_libraries.id" },
+      { "name": "style_brief", "type": "text", "nullable": true },
+      { "name": "prompt_template", "type": "text", "nullable": true }
+    ] },
+    { "id": "folders", "name": "asset_folders", "note": "Nestable folders", "fields": [
+      { "name": "library_id", "type": "id", "fk": "image_libraries.id" },
+      { "name": "parent_id", "type": "id", "fk": "asset_folders.id", "nullable": true }
+    ] },
+    { "id": "presets", "name": "image_generation_presets", "note": "Saved generation recipes", "fields": [
+      { "name": "media_type", "type": "text" },
+      { "name": "prompt_template", "type": "text" },
+      { "name": "model", "type": "text" }
+    ] },
+    { "id": "sessions", "name": "image_generation_sessions", "note": "Iterative generate-and-choose", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "status", "type": "text" },
+      { "name": "active_asset_id", "type": "id", "fk": "image_assets.id", "nullable": true }
+    ] },
+    { "id": "session_items", "name": "image_generation_session_items", "note": "Candidate assets in a session", "fields": [
+      { "name": "session_id", "type": "id", "fk": "image_generation_sessions.id" },
+      { "name": "asset_id", "type": "id", "fk": "image_assets.id" },
+      { "name": "role", "type": "text" }
+    ] },
+    { "id": "assets", "name": "image_assets", "note": "The asset record", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "media_type", "type": "text", "note": "image / video" },
+      { "name": "status", "type": "text" },
+      { "name": "prompt", "type": "text", "nullable": true },
+      { "name": "object_key", "type": "text", "nullable": true }
+    ] },
+    { "id": "runs", "name": "image_generation_runs", "note": "Generation audit log", "fields": [
+      { "name": "model", "type": "text" },
+      { "name": "status", "type": "text" },
+      { "name": "source", "type": "text", "note": "chat / ui / a2a" }
+    ] }
+  ],
+  "relations": [
+    { "from": "library", "to": "collections", "kind": "1-n" },
+    { "from": "library", "to": "folders", "kind": "1-n" },
+    { "from": "library", "to": "assets", "kind": "1-n" },
+    { "from": "sessions", "to": "session_items", "kind": "1-n" },
+    { "from": "library", "to": "library_shares", "kind": "1-n" }
+  ]
+}
+```
+
+### Le personnaliser
+
+Assets est un modèle complet et clonable. Quelques idées d'extension pratiques :
+
+- "Ajoutez un connecteur de catalogue de produits afin que les plans de référence du produit puissent être sélectionnés par SKU."
+- "Ajoutez une file d'attente d'approbation stricte avant que les éléments générés ne soient marqués comme utilisables à des fins marketing."
+- "Ajoutez un tableau de bord d'évaluation de la marque qui filtre les générations ayant échoué ou mal notées par modèle."
+- "Créez une bibliothèque de ressources par défaut à l'échelle de l'espace de travail et acheminez la génération d'images Slides via celle-ci."
+- "Ajoutez un nouveau fournisseur derrière l'interface de génération d'images après avoir vérifié la dernière documentation du fournisseur."
+
+L'agent modifie les itinéraires, les composants, les modèles basés sur actions, skills et SQL selon les besoins. Voir [Templates](/docs/cloneable-saas) pour le clonage complet, la personnalisation, le flux de déploiement et [A2A Protocol](/docs/a2a-protocol) pour la génération inter-applications.
+
+### Intégrer le sélecteur
+
+Utilisez l'itinéraire du sélecteur lorsqu'un humain choisit ou génère un actif à l'intérieur
+un autre produit. Image est le type de média par défaut ; passer `mediaType=video` quand
+vous souhaitez parcourir/sélectionner des vidéos :
+
+```tsx
+import { EmbeddedApp } from "@agent-native/embedding";
+
+<EmbeddedApp
+  url="https://assets.agent-native.com/picker?mediaType=image"
+  onMessage={(name, payload) => {
+    if (name === "chooseAsset") {
+      insertAsset((payload as { url: string }).url);
+    }
+  }}
+/>;
+```
+
+Les hôtes MCP externes devraient appeler `open-asset-picker` au lieu de le construire
+iframe à la main. L'action renvoie un lien de secours du navigateur et les métadonnées de l'application MCP
+pour les hôtes en ligne. Lorsqu'un utilisateur sélectionne un actif, le sélecteur émet `chooseAsset`,
+l'ancien alias `chooseImage` pour les éléments d'image et met à jour le modèle d'application MCP
+contexte dans lequel l'hôte le prend en charge. Lorsqu'un hôte ouvre le lien de secours dans un
+Onglet normal du navigateur au lieu de rendre l'application MCP en ligne, en sélectionnant un élément
+copie un résumé de transfert et affiche un bloc de contexte copiable ; collez ce résumé
+revenir dans le chat pour que l'agent externe puisse utiliser le média sélectionné URL et
+métadonnées des éléments.
+
+Codex, Claude Code et Claude Desktop Code doivent être traités comme des hôtes de liaison
+pour ce flux. Ils ne peuvent pas rendre les applications MCP en ligne et la démarque CDN à distance
+les images peuvent ne pas s'afficher de manière fiable dans la transcription du chat. Les agents doivent conserver le
+le lien d'actif comme source de vérité ; lorsqu'un aperçu en ligne visible est nécessaire dans un
+chat avec l'éditeur de code, téléchargez le `previewUrl`/`downloadUrl` sélectionné sur un site local
+fichier image et intégrez ce chemin local absolu.
+
+Pour générer et choisir des flux, appelez `open-asset-picker` avec `prompt`,
+`autoGenerate: true` et `count: 3` (personnalisable de 1 à 6). Le sélecteur s'ouvre
+avec des images candidates et permet à l'utilisateur d'ajuster le nombre, le rapport hauteur/largeur ou un
+préréglage de génération avant de choisir l'actif final URL.
+
+Utilisez A2A lorsqu'un autre agent doit créer, rechercher ou exporter des ressources sans
+sélecteur humain UI.
+
+### Développeur : distribuer la compétence d'application
+
+La compétence d'application Actifs porte l'ID d'application `assets` et héberge MCP URL
+`https://assets.agent-native.com/_agent-native/mcp`.
+
+```bash
+# Easiest hosted install: exported skill instructions plus MCP connector.
+npx @agent-native/core@latest skills add assets
+
+# Vercel/open Skills CLI install: exported instructions only, no MCP config.
+npx skills@latest add BuilderIO/agent-native --skill assets
+
+# Hosted install: URL-only MCP connector, no shared secrets in skill files.
+npx @agent-native/core@latest app-skill ensure --manifest templates/assets/agent-native.app-skill.json
+
+# Local editable launch.
+npx @agent-native/core@latest app-skill launch --manifest templates/assets/agent-native.app-skill.json --local --into ./assets-local
+
+# Marketplace package, including Claude Code marketplace and Vercel Labs skills adapters.
+npx @agent-native/core@latest app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill
+
+# Install a local exported Assets bundle with the open skills CLI.
+npx skills@latest add ./dist/assets-skill --skill assets -a codex -y
+
+# Install from the generated Claude Code marketplace adapter.
+claude plugin marketplace add ./dist/assets-skill/adapters/claude-marketplace
+claude plugin install agent-native-assets@agent-native-apps
+```
+
+La compétence exportée apprend aux agents à utiliser le sélecteur pour le contact humain
+sélection, actions direct pour la génération d'images/vidéos sans surveillance et navigateur
+liens lorsque les applications MCP en ligne ne sont pas disponibles.
+
+L'adaptateur Marketplace Claude contient un `.claude-plugin/marketplace.json`
+catalogue et plugin `agent-native-assets` avec `skills/assets/SKILL.md` plus
+le `.mcp.json` hébergé. Dans le code Claude interactif, le même flux est disponible
+comme `/plugin marketplace add ./dist/assets-skill/adapters/claude-marketplace`,
+`/plugin install agent-native-assets@agent-native-apps`, `/reload-plugins` et
+`/mcp` pour l'authentification MCP.
+
+Si vous installez à partir d'un bundle Raw Marketplace avec `npx skills@latest`, enregistrez le
+connecteur MCP hébergé afin que ces instructions puissent appeler l'application Assets en direct :
+
+```bash
+npx @agent-native/core@latest app-skill ensure --manifest ./dist/assets-skill/agent-native.app-skill.json --yes
+```
+
+## Quelle est la prochaine étape
+
+- [**Templates**](/docs/cloneable-saas) — le modèle cloner et posséder
+- [**Embedding SDK**](/docs/embedding-sdk) – Modèles de sélecteur d'iframe et de side-car
+- [**A2A Protocol**](/docs/a2a-protocol) : comment les autres applications appellent les éléments
+- [**File Uploads**](/docs/file-uploads) – stockage et diffusion d'actifs authentifiés
+- [**Sharing & Privacy**](/docs/sharing) — contrôle d'accès au niveau de la bibliothèque