@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/fr-FR/plan-plugin.md

@@ -0,0 +1,200 @@
+---
+title: "Plugin de planification et place de marché"
+description: "Installez le Plan Agent-Native skills (/visual-plan, /visual-recap) ainsi que le connecteur Plan MCP hébergé en tant que code Claude ou plugin Codex, ou avec le CLI universel. Comment fonctionnent les mises à jour et si vous devez soumettre quelque chose."
+---
+
+# Plugin et place de marché du plan
+
+L'application Agent-Native **Plan** est livrée sous la forme d'un ensemble installable. Une seule installation ajoute à la fois la commande slash Plan skills **et** connecte le connecteur Plan MCP hébergé, afin que l'agent puisse générer des plans et que le skills puisse les publier directement dans l'application Plan.
+
+## Ce que vous obtenez {#what-you-get}
+
+Une installation vous offre :
+
+- **Deux skills** — `/visual-plan` (le point d'entrée canonique) et `/visual-recap`.
+- **Le connecteur Plan MCP** — enregistré auprès de l'application hébergée sur `https://plan.agent-native.com` (point de terminaison MCP `https://plan.agent-native.com/_agent-native/mcp`, nom de serveur `plan`).
+
+```an-diagram title="Three routes, one bundle" summary="The universal CLI, Claude Code plugin, and Codex plugin all install the same two skills plus the hosted Plan connector."
+{
+  "html": "<div class=\"diagram-routes\"><div class=\"diagram-col\"><div class=\"diagram-node\">Universal CLI<br><small class=\"diagram-muted\">skills add visual-plan</small></div><div class=\"diagram-node\">Claude Code plugin<br><small class=\"diagram-muted\">/plugin install</small></div><div class=\"diagram-node\">Codex plugin<br><small class=\"diagram-muted\">codex plugin add</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">/visual-plan</span><span class=\"diagram-pill accent\">/visual-recap</span><small class=\"diagram-muted\">two skills</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Plan MCP connector<br><small class=\"diagram-muted\">plan.agent-native.com/_agent-native/mcp</small></div></div>",
+  "css": ".diagram-routes{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-routes .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-routes .diagram-arrow{font-size:22px;line-height:1}.diagram-routes .center{display:flex;flex-direction:column;align-items:center;gap:4px;text-align:center}.diagram-routes .center .diagram-pill{margin:2px}"
+}
+```
+
+Par défaut, les deux skills publient sur l'application Plan hébergée : ils créent un plan via
+le connecteur MCP et vous remettra un lien ou un plan en ligne à examiner. Ils ne jettent jamais
+un plan Markdown/ASCII en ligne dans le chat comme livrable. Si un outil Planifier
+renvoie `needs auth`, `Unauthorized` ou `Session terminated`, ré-authentifier
+le connecteur au lieu de revenir à la sortie en ligne. Les jetons d'accès sont
+longue durée de vie (30 jours par défaut, actualisation glissante sur 365 jours), cela devrait donc être rare ;
+Quand cela se produit, la solution légère est la suivante :
+
+```bash
+npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex
+```
+
+`reconnect` recherche et actualise le connecteur par URL pour le local sélectionné
+client : aucune réinstallation n'est nécessaire. Démarrez un nouveau thread Codex après vous être reconnecté afin que
+rechargement du registre des outils. Dans le code Claude, l'équivalent est `/mcp` →
+**Authentifier / Reconnecter**, ou la même commande avec `--client claude-code`.
+
+L'exception est le **mode de confidentialité des fichiers locaux** explicite. Quand vous ne demandez pas de DB
+écrit ou définit `AGENT_NATIVE_PLANS_MODE=local-files`, le skills ne doit pas appeler
+le connecteur Plan MCP. Ils écrivent `plans/<slug>/plan.mdx` plus facultatif
+`canvas.mdx`, `prototype.mdx` et `.plan-state.json`, puis prévisualisez localement avec :
+
+```bash
+npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan --open
+```
+
+Cela démarre un petit pont localhost et ouvre le plan UI par rapport au local
+dossier. (`plan local preview` exécute à la place une route de serveur de développement Plan local, et
+`plan local preview --out preview.html` est une trappe de secours héritée qui écrit un
+fichier HTML statique autonome. `plan serve` est accepté comme alias court pour
+`plan local serve`.)
+
+Quelques pièges du mode fichiers locaux à connaître :
+
+- **Utilisez un navigateur Chromium.** Safari bloque la page du plan HTTPS hébergée
+  lecture du pont localhost `http://127.0.0.1` (contenu mixte / privé
+  réseau), la page se bloque donc sur "Plan de chargement". Déjà sur macOS `--open`
+  préfère Chrome/Chromium/Edge/Brave ; si Safari s'ouvre quand même, rouvrez le fichier imprimé
+  URL dans un navigateur Chromium.
+- **Le URL servi est écrit dans `plans/<slug>/.plan-url`** (remplacer par
+  `--url-file`). Un agent en arrière-plan ou sans tête peut lire ce fichier au lieu de
+  grattage de la sortie standard `serve` de longue durée. Traitez-le comme un fichier de jeton local et
+  ne le commettez pas.
+- **Vérifiez sans interface graphique** lorsqu'aucun navigateur n'est disponible :
+  `npx @agent-native/core@latest plan local verify --dir plans/<slug>` démarre le
+  pont, vérifie le contrôle en amont du réseau privé et la charge utile JSON, imprime
+  diagnostics et sorties non nulles en cas d'échec – aucun œil humain requis.
+- **Exécutez d'abord `plan local check`.** Il valide le MDX par rapport au plan
+  Schéma de bloc du moteur de rendu (y compris les champs obligatoires comme l'élément `checklist`
+  `id`/`label` et `question-form` question `id`/`title`/`mode`), donc création
+  des erreurs font surface avant le transfert du navigateur au lieu d'un chargeur bloqué.
+
+Pour les dossiers du dépôt actuel, la route locale directe inclut `?path=...` donc
+l'application Plan locale peut conserver les modifications du navigateur enregistrées dans le dossier du dépôt. Le plan
+l'application utilise `apps.plan.roots[0].path` dans `agent-native.json` comme emplacement par défaut
+pour enregistrer les plans locaux promus, en revenant à `plans/`.
+
+Cela maintient le contenu du plan hors de la base de données du plan Agent-Native. Partage hébergé,
+les commentaires, les captures d'écran et l'historique du plan ne sont pas disponibles jusqu'à ce que vous l'ayez explicitement
+publier plus tard.
+
+```an-diagram title="Hosted vs. local-files mode" summary="By default skills publish through the connector; local-files mode writes MDX to disk and previews via a localhost bridge instead."
+{
+  "html": "<div class=\"diagram-modes\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Default · hosted</span><strong>Publish to the Plan app</strong><small class=\"diagram-muted\">MCP connector &rarr; hosted DB &rarr; share links, comments, history, screenshots</small></div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">Local-files privacy</span><strong>Write MDX to disk</strong><small class=\"diagram-muted\">plan.mdx + canvas.mdx + prototype.mdx &rarr; localhost bridge &rarr; hosted Plan UI reads local source. No DB writes until <code>publish-visual-plan</code>.</small></div></div>",
+  "css": ".diagram-modes{display:flex;gap:14px;flex-wrap:wrap}.diagram-modes .diagram-card{flex:1 1 260px;display:flex;flex-direction:column;gap:6px;padding:16px 18px}"
+}
+```
+
+Agent Native Desktop dispose d'un chemin de synchronisation de fichiers locaux distinct pour les forfaits hébergés : le
+L'application de bureau peut refléter un plan hébergé dans des fichiers MDX locaux et réimporter les modifications
+sans cloner l'application Plan ni exécuter un CLI. Ce workflow conserve l'hébergement
+Planifier la base de données comme source de vérité ; utiliser le mode de confidentialité des fichiers locaux lorsque l'objectif
+il n'y a pas d'écriture dans la base de données Plan.
+
+> Le plugin (`agent-native-visual-plans`) porte l'identifiant d'application `visual-plans`, c'est pourquoi le nom du plugin Claude Code et le nom du plugin Codex sont tous deux `agent-native-visual-plans`. Le nom d'affichage de l'application Plan est "Agent-Native Plan".
+
+## Installer des itinéraires {#install}
+
+Il existe trois façons d'y accéder. La **route universelle CLI** est celle que nous recommandons par défaut, car elle installe le skills **et** vous permet de choisir le mode hébergé, fichiers locaux ou auto-hébergé en un seul flux. Les routes de plugins sont destinées aux hôtes dotés d'un système de plugins/place de marché de première classe et utilisent des plans hébergés par défaut.
+
+### Itinéraire de compétences universel (n'importe quel hôte MCP) {#universal}
+
+Fonctionne pour n'importe quel hôte : code Claude, Codex, Cursor, Cline, Goose, applications ChatGPT personnalisées MCP, Claude Cowork et tout ce qui est compatible avec MCP. Le Agent-Native CLI installe les deux skills, enregistre le connecteur Plan MCP hébergé et **et exécute l'authentification pour le(s) client(s) local(s) sélectionné(s) au cours de la même étape**, afin que votre premier appel d'outil ne heurte pas un mur OAuth :
+
+```bash
+npx @agent-native/core@latest skills add visual-plan
+```
+
+Cela installe `visual-plan` ainsi que la compétence associée `visual-recap`, puis enregistre le connecteur `plan`, puis exécute l'authentification (invite OAuth pour le partage hébergé/soutenu par un compte). Indicateurs utiles :
+
+- `--client codex|claude-code|claude-code-cli|cowork|all` — pour quels agents locaux écrire la configuration MCP (`all` par défaut).
+- `--no-connect` : enregistre le connecteur sans authentification ; exécutez `npx @agent-native/core@latest connect https://plan.agent-native.com --client all` plus tard ou choisissez un `--client` plus étroit.
+- `--mode hosted|local-files|self-hosted` : choisissez le partage hébergé, les fichiers MDX entièrement locaux ou votre propre application Plan.
+- `--mcp-url <url>` : pointez le connecteur vers une origine personnalisée (un tunnel ngrok, un serveur de développement local ou un déploiement auto-hébergé) au lieu de l'origine hébergée par défaut.
+- `--with-github-action` — rédigez également l'action PR Visual Recap GitHub (voir [PR Visual Recap](/docs/pr-visual-recap)).
+
+Les installations interactives proposent également l'action PR Visual Recap lorsqu'aucun flux de travail n'est disponible
+présent. Dites oui pour l'ajouter lors de la configuration des compétences, ou exécutez la commande ci-dessus plus tard
+avec `--with-github-action`. Une fois le workflow écrit, exécutez :
+
+```bash
+npx @agent-native/core@latest recap setup
+npx @agent-native/core@latest recap doctor
+```
+
+`recap setup` configure les secrets et les variables de l'action GitHub lorsque cela est possible,
+et `recap doctor` vérifie le workflow, le jeton de publication local, le dépôt GitHub
+accès et configuration Actions requise. Une fois l'installation terminée, redémarrez ou
+rechargez le client de l'agent pour que le nouveau skills et les nouveaux outils se chargent, puis exécutez
+`/visual-plan`.
+
+> Remarque : le `npx skills@latest add BuilderIO/agent-native --skill visual-plan` nu (Vercel/open Skills CLI) installe **instructions uniquement** — il n'enregistre pas le connecteur MCP. Utilisez le Agent-Native CLI ci-dessus lorsque vous souhaitez également câbler le connecteur.
+
+### Code Claude (plugin) {#claude-code}
+
+Le référentiel public `BuilderIO/agent-native` est lui-même un marché de plugins Claude Code, vous l'ajoutez donc directement – sans étape de construction. À l'intérieur du code Claude :
+
+```text
+/plugin marketplace add BuilderIO/agent-native
+/plugin install agent-native-visual-plans@agent-native-apps
+/reload-plugins
+/mcp        # authenticate the Plan connector (one OAuth approval)
+```
+
+`/plugin install` ajoute à la fois le plan skills et une configuration MCP **URL uniquement** (aucun secret dans le package) ; `/mcp` → **Authentifier** termine la négociation OAuth. Utilisez plutôt la route universelle CLI lorsque vous souhaitez des fichiers locaux ou un mode auto-hébergé.
+
+> Le catalogue Marketplace s'appelle `agent-native-apps` et le plug-in Plan est `agent-native-visual-plans`, la cible d'installation est donc toujours `agent-native-visual-plans@agent-native-apps`.
+
+### Codex (plug-in) {#codex}
+
+Le même référentiel est un marché de plugins Codex. Ajoutez-le, installez le plugin, puis authentifiez le connecteur :
+
+```bash
+codex plugin marketplace add BuilderIO/agent-native
+codex plugin add agent-native-visual-plans@agent-native-apps
+codex mcp login plan   # OAuth in the browser
+```
+
+Après l'installation, **démarrez un nouveau thread Codex** pour que les outils skills et MCP se chargent dans la session. Le plugin est livré avec un connecteur uniquement URL (`[mcp_servers.plan]` → `https://plan.agent-native.com/_agent-native/mcp`) ; `codex mcp login plan` exécute le flux OAuth. La route universelle CLI ci-dessus fonctionne également pour Codex (`npx @agent-native/core@latest skills add visual-plan --client codex`) si vous préférez une commande qui s'installe et s'authentifie ensemble, ou lorsque vous souhaitez des fichiers locaux ou un mode auto-hébergé.
+
+> **Installations plus anciennes :** si votre configuration a toujours une entrée `agent-native-plans` pointant vers le même URL, exécutant `npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex` pour Codex, ou la même commande avec votre `--client` cible, la consolide avec le nom canonique `plan`.
+
+## Mises à jour {#updates}
+
+Le plugin achemine la mise à jour automatique : vous ne reconditionnez ni n'ajoutez de nouveau le marché pour les changements de compétences de routine :
+
+- **Code Claude** — l'entrée du marché définit `autoUpdate: true` et le plugin utilise la gestion des versions commit-SHA, donc le code Claude extrait les nouvelles versions du référentiel au démarrage ; exécutez `/reload-plugins` pour l'activer. Chaque poussée vers la branche par défaut du dépôt atteint automatiquement les utilisateurs installés.
+- **Codex** — le plugin `version` intègre un hachage de contenu du point de terminaison skills et MCP groupé (par exemple `1.0.0+codex.<hash>`), de sorte que toute modification de compétence ou de point de terminaison génère une nouvelle version. La mise à niveau automatique de démarrage de Codex réinstalle seule les places de marché Git configurées ; il suffit de **démarrer un nouveau fil** pour prendre en compte le changement. Aucun `codex plugin marketplace upgrade` manuel n'est nécessaire pour les mises à jour de routine.
+- **Route universelle CLI** — exécutez `npx @agent-native/core@latest skills status visual-plan` pour vérifier les dossiers de compétences copiés, ou `npx @agent-native/core@latest skills update visual-plan` pour les actualiser. La réexécution de `skills add visual-plan` fonctionne toujours lorsque vous souhaitez également réenregistrer/authentifier le connecteur. `@latest` extrait toujours le skills actuel du package `@agent-native/core` publié.
+
+Le connecteur pointe vers une application **hébergée**, de sorte que le actions et la surface de l'outil en direct de l'application Plan reflètent toujours la version déployée, quel que soit le moment où vous l'avez installé ; seules les instructions de compétences groupées suivent les mécanismes de mise à jour ci-dessus.
+
+> **Mainteneurs :** le bundle de marché (`.claude-plugin/`, `.agents/plugins/`) est généré à partir du plan canonique skills par `pnpm sync:plan-marketplace` et vérifié dans CI par `pnpm guard:plan-marketplace`, de sorte que le marché publié correspond toujours au plan canonique skills. Modifiez la compétence, exécutez `pnpm sync:plan-marketplace` et validez.
+
+## Avez-vous besoin de soumettre quelque chose ? {#submission}
+
+**Aucune soumission ou révision n'est requise pour distribuer ou installer ceci.** `BuilderIO/agent-native` est un marché git public et auto-hébergé, les utilisateurs l'ajoutent donc directement avec les commandes ci-dessus sur **à la fois le code Claude et le Codex** — aucune demande ni approbation. L'itinéraire universel CLI ne nécessite aucun marché.
+
+Découverte facultative, si vous souhaitez une liste publique :
+
+- **Claude Code** dispose d'un marché communautaire auquel vous pouvez _éventuellement_ soumettre votre annonce (soumission plus un examen automatisé). Le marché officiel organisé par Anthropic est répertorié à la discrétion d'Anthropic — il n'y a pas d'application libre-service ouverte. Ni l'un ni l'autre n'est requis pour utiliser les commandes d'installation ci-dessus.
+- **Codex** dispose d'un catalogue de plugins organisé par OpenAI (une liste verte fermée, provenant d'un partenariat plutôt que d'une soumission en libre-service). Les marchés Git auto-hébergés et la route CLI ne nécessitent aucune soumission pour fonctionner.
+
+En bref : expédiez-le en tant que marché git auto-hébergé/public et les utilisateurs l'installent directement ; soumettez-le à un catalogue organisé uniquement si vous souhaitez qu'il soit répertorié pour la découverte.
+
+## Plugin vs compétence {#plugin-vs-skill}
+
+Une **compétence** est un fichier d'instructions `SKILL.md` unique que l'agent lit lorsqu'une tâche correspond. Un **plugin** (plugin Claude Code Marketplace ou plugin Codex) est un package qui regroupe un ou plusieurs skills **plus** un connecteur MCP et des métadonnées, afin qu'un hôte puisse tout installer en une seule étape.
+
+Sous le capot, les trois routes sont produites à partir de la même source par le `npx @agent-native/core@latest app-skill` CLI : `app-skill pack` construit les adaptateurs de marché/plug-in, et `skills add` est le programme d'installation convivial en une étape qui enregistre et authentifie également le connecteur MCP. Voir [Skills Guide](/docs/skills-guide) pour le format du manifeste de compétence d'application et [External Agents](/docs/external-agents) pour connecter n'importe quel hôte MCP et le flux `npx @agent-native/core@latest connect`.
+
+## Quelle est la prochaine étape {#whats-next}
+
+- [**Visual Plans**](/docs/template-plan) — que font les skills et comment les utiliser
+- [**PR Visual Recap**](/docs/pr-visual-recap) – exécutez `/visual-recap` automatiquement à chaque demande d'extraction
+- [**Skills Guide**](/docs/skills-guide) — skills basé sur l'application et format manifeste
+- [**External Agents**](/docs/external-agents) : connectez n'importe quel hôte MCP et artefacts aller-retour

package/corpus/core/docs/content/locales/fr-FR/pr-visual-recap.md

@@ -0,0 +1,384 @@
+---
+title: "Récapitulatif visuel des relations publiques"
+description: "Une action GitHub qui exécute la compétence de récapitulation visuelle de votre dépôt à chaque PR. Un agent de codage LLM lit la différence, publie un plan récapitulatif interactif, affiche une vérification informative et publie un commentaire PR collant avec une capture d'écran en ligne. Informatif et non bloquant."
+---
+
+# Récapitulatif visuel des relations publiques
+
+PR Visual Recap est une action GitHub qui transforme chaque demande d'extraction en une **révision visuelle du code**. À chaque poussée, un agent de codage LLM exécute la dernière compétence [`visual-recap`](/docs/template-plan) groupée (ou la copie validée de votre dépôt lorsque `VISUAL_RECAP_SKILL_SOURCE=repo`) par rapport au différentiel PR, publie un plan récapitulatif structuré sur l'application Plans hébergée, affiche une vérification informative `Visual Recap` pendant son exécution et insère **un commentaire PR collant** qui renvoie au plan interactif avec une **capture d'écran en ligne** intégrée directement dans le commentaire.
+
+Ceci n'est pas un moteur de rendu différentiel déterministe. L'action appelle un véritable agent de codage (Claude Code CLI par défaut, ou OpenAI Codex CLI) qui lit le changement, décide de ce qui compte et rédige le récapitulatif en appelant l'outil Plans MCP `create-visual-recap` - le même outil que la commande slash `/visual-recap` utilise. Vous obtenez une vue à haute altitude, schéma/API/avant-après du changement au lieu d'un mur de différences brutes.
+
+Le récapitulatif est **informatif et non bloquant**. Il crée une ligne de vérification afin que les réviseurs puissent voir que la génération est en cours, mais ce n'est pas une vérification obligatoire, elle ne bloque jamais le PR et ne remplace jamais la lecture de la différence réelle. Le commentaire collant est une aide à la révision, pas une approbation.
+
+## Ce qu'il fait
+
+À chaque push PR, le workflow :
+
+1. Collecte une différence limitée entre la base PR et la tête.
+2. Crée une vérification informative `Visual Recap` GitHub avec `Visual recap in progress`.
+3. Exécute l'agent de codage configuré sur cette différence. L'agent lit le guide de compétences `visual-recap` fourni (ou votre copie épinglée dans le dépôt) et rédige un récapitulatif, qu'il publie avec `create-visual-recap`.
+4. Lit le plan publié URL que l'agent a écrit à `recap-url.txt`.
+5. Ouvre ce URL dans Chrome sans tête et capture le plan rendu en modes clair et sombre.
+6. Télécharge les PNG sur un itinéraire d'image publique signé sur l'application Plans.
+7. Insère un seul commentaire PR collant qui intègre les captures d'écran **en ligne** avec un élément `<picture>` (servi via le proxy d'image camouflage de GitHub) à côté du lien vers le récapitulatif interactif.
+8. Termine la vérification `Visual Recap` comme étant réussie, ignorée ou neutre.
+
+```an-diagram title="What happens on each PR push" summary="A bounded diff feeds a real coding agent, which authors a recap; the workflow screenshots it and upserts one sticky comment."
+{
+  "html": "<div class=\"diagram-recap\"><div class=\"diagram-node\">PR push<br><small class=\"diagram-muted\">bounded base&hellip;head diff</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Coding agent<br><small class=\"diagram-muted\">Claude Code / Codex reads diff</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">create-visual-recap</span><small class=\"diagram-muted\">publishes recap plan</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Headless Chrome<br><small class=\"diagram-muted\">light + dark screenshots</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">One sticky PR comment<br><small class=\"diagram-muted\">inline screenshot + plan link</small></div></div><div class=\"diagram-foot diagram-muted\">Plus an informational <span class=\"diagram-pill\">Visual Recap</span> check &mdash; non-blocking, never required.</div>",
+  "css": ".diagram-recap{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.diagram-recap .diagram-arrow{font-size:20px;line-height:1}.diagram-recap .center{display:flex;flex-direction:column;align-items:center;gap:4px;text-align:center}.diagram-recap .diagram-foot{flex-basis:100%;margin-top:10px;font-size:13px}"
+}
+```
+
+Une nouvelle diffusion met à jour le même plan et le même commentaire persistant : pas de plans orphelins, pas de spam de commentaires.
+
+## L'installer
+
+Lorsque vous installez des plans de manière interactive, le Agent-Native CLI vous demande s'il faut ajouter
+Récapitulatifs visuels automatiques des relations publiques. Dites oui pour écrire l'action GitHub, ou ajoutez-la
+explicitement à tout moment :
+
+```bash
+npx @agent-native/core@latest skills add visual-plan --with-github-action
+```
+
+Cela installe la compétence `visual-plan` (qui inclut la compétence `visual-recap` exécutée par l'action) et écrit `.github/workflows/pr-visual-recap.yml` dans votre dépôt. Le flux de travail appelle **les sous-commandes CLI publiées** via `npx @agent-native/core@latest recap <subcommand>` — notamment `gate`, `collect-diff`, `block-reference`, `scan`, `build-prompt`, `publish`, `shot`, `comment`, `check` et `usage` — afin que rien ne soit copié dans votre dépôt en tant que scripts d'assistance. `setup` et `doctor` sont les assistants interactifs que vous exécutez localement ; `gate` est l'étape de sécurité que le flux de travail exécute avant chaque récapitulatif.
+
+Ensuite, exécutez l'assistant de configuration guidée :
+
+```bash
+npx @agent-native/core@latest recap setup
+npx @agent-native/core@latest recap doctor
+```
+
+`recap setup` actualise le flux de travail et utilise `gh` pour définir GitHub Actions
+secrets/variables lorsque les valeurs sont disponibles depuis l'environnement ou les plans locaux
+stocke les jetons de publication et imprime les commandes manquantes exactes pour tout ce qu'il ne peut pas
+défini. Les valeurs secrètes sont envoyées à `gh` via stdin, et non via les arguments de commande. Valider
+le fichier de workflow généré et ouvrez un PR pour le voir s'exécuter.
+
+Par défaut, le workflow crée son invite d'agent à partir de la dernière version groupée
+Conseils `visual-recap` dans `@agent-native/core@latest`, y compris les frères et sœurs
+fichiers de référence avec lesquels la compétence est livrée. Si votre dépôt personnalise intentionnellement et
+épingle son dossier `visual-recap` validé, définit la variable du référentiel
+`VISUAL_RECAP_SKILL_SOURCE=repo`.
+
+## Sélection du back-end
+
+Choisissez quel agent de codage exécute la compétence avec la variable du référentiel `VISUAL_RECAP_AGENT` :
+
+| `VISUAL_RECAP_AGENT`    | Agent de codage  | Clé API requise     |
+| ----------------------- | ---------------- | ------------------- |
+| `claude` _(par défaut)_ | Code Claude CLI  | `ANTHROPIC_API_KEY` |
+| `codex`                 | OpenAI Codex CLI | `OPENAI_API_KEY`    |
+
+Si la variable n'est pas définie, l'action utilise `claude`.
+
+## Modèle et raisonnement
+
+Au-delà du backend, deux variables du référentiel ajustent _comment_ l'agent s'exécute :
+
+- **`VISUAL_RECAP_MODEL`** épingle le modèle transmis au CLI (`--model`) — par exemple `gpt-5.5` pour Codex, ou un identifiant de modèle Claude. Laissez-le non défini pour utiliser le modèle par défaut du CLI.
+- **`VISUAL_RECAP_REASONING`** définit la profondeur du raisonnement : `none`, `minimal`, `low`, `medium`, `high` ou `xhigh`. Cela s'applique au backend Codex ; Le raisonnement de Claude est basé sur un modèle, cette variable y est donc ignorée.
+- **`VISUAL_RECAP_SKILL_SOURCE`** contrôle la fraîcheur des invites : `auto`/unset utilise les dernières instructions de compétences groupées, tandis que `repo` s'épingle dans le dossier de compétences `visual-recap` local du dépôt validé.
+
+Par exemple, pour exécuter le récapitulatif sur Codex avec GPT-5.5 avec un raisonnement élevé, définissez les variables du référentiel `VISUAL_RECAP_AGENT=codex`, `VISUAL_RECAP_MODEL=gpt-5.5` et `VISUAL_RECAP_REASONING=high`.
+
+## Secrets et variables
+
+Définissez-les dans **Paramètres → Secrets et variables → Actions** de votre référentiel.
+
+### Secrets (seulement deux requis)
+
+| Secret              | Objectif                                                                                                                                                    |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PLAN_RECAP_TOKEN`  | Jeton révocable émis par `npx @agent-native/core@latest connect`. Autorise la publication du plan récapitulatif et le téléchargement de la capture d'écran. |
+| `ANTHROPIC_API_KEY` | La clé LLM pour le backend du code Claude par défaut.                                                                                                       |
+
+**Équipes : utilisez un jeton de service d'organisation.** Un jeton personnel est lié à la personne
+qui l'a créé – s'il quitte l'organisation ou révoque ses jetons, chaque dépôt utilisant
+ce secret commence à échouer avec les 401, et les plans créés par CI appartiennent à ceux-ci
+individuel au lieu de l’équipe. Un jeton de service d'organisation appartient à votre
+**organisation** : elle agit en tant que principal de service (`svc-<name>@service.<orgId>`),
+survit à tout individu quittant, les récapitulatifs qu'il publie sont visibles au niveau de l'organisation, et
+n'importe quel propriétaire ou administrateur d'organisation peut le répertorier ou le révoquer. Mint One (propriétaire/administrateur de l'organisation uniquement) :
+
+```bash
+npx @agent-native/core@latest connect https://plan.agent-native.com --service-token pr-recap
+```
+
+La commande vous authentifie dans le navigateur, puis imprime le jeton de service
+exactement une fois : stockez-le en tant que secret `PLAN_RECAP_TOKEN`. Gérez-le plus tard avec
+les `list-org-service-tokens` et `revoke-org-service-token` actions sur le
+Application Plans.
+
+**Solo : un jeton personnel fonctionne toujours.** Fabriquez-le avec `npx @agent-native/core@latest connect`
+contre votre application Plans. Pour l'application hébergée, ceci écrit également un local
+fichier de jeton de publication que `npx @agent-native/core@latest recap setup` peut lire :
+
+```bash
+npx @agent-native/core@latest connect https://plan.agent-native.com --client codex
+npx @agent-native/core@latest recap setup
+```
+
+Si vous préférez une configuration manuelle, collez le jeton dans le secret GitHub. Utilisez un
+espace réservé comme `plan_recap_xxxxxxxxxxxxxxxx` uniquement à titre d'exemple – ne validez jamais un
+vrai jeton.
+
+### Facultatif (uniquement si vous modifiez les valeurs par défaut)
+
+| Secret / variable        | Par défaut                         | Quand vous en avez besoin                                                                                                                                       |
+| ------------------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OPENAI_API_KEY`         | —                                  | Secret. Configurez-le avec `VISUAL_RECAP_AGENT=codex` pour exécuter le récapitulatif avec Codex à la place.                                                     |
+| `VISUAL_RECAP_AGENT`     | `claude`                           | Variable. Sélectionne le backend de l'agent de codage (`claude` ou `codex`).                                                                                    |
+| `VISUAL_RECAP_MODEL`     | valeur par défaut de chaque CLI    | Variable. Épingle le modèle - par ex. `gpt-5.5` pour Codex, ou un identifiant de modèle Claude. Unset utilise la valeur par défaut du CLI.                      |
+| `VISUAL_RECAP_REASONING` | valeur par défaut de chaque modèle | Variable. Profondeur de raisonnement : `none`, `minimal`, `low`, `medium`, `high` ou `xhigh`. S'applique au backend Codex.                                      |
+| `RECAP_CLI_VERSION`      | `latest`                           | Variable. Épingle la version `@agent-native/core` CLI installée par le flux de travail, par ex. `1.5.0`. Voir [Version pinning](#version-pinning-copy-variant). |
+| `PLAN_RECAP_APP_URL`     | `https://plan.agent-native.com`    | Secret. Uniquement lors de l'auto-hébergement de l'application Plans à une origine différente.                                                                  |
+
+Le workflow détecte automatiquement comment appeler son assistant CLI (source locale dans ce monorepo, le `@agent-native/core` publié ailleurs), il n'y a donc aucune variable `RECAP_CLI` à définir.
+
+## Capture d'écran en ligne dans le commentaire
+
+Une fois que l'agent a publié le récapitulatif, le flux de travail capture le plan rendu dans Chrome sans tête en modes clair et sombre et télécharge les fichiers PNG vers un itinéraire d'images publiques signé sur l'application Plans. Le commentaire PR collant intègre ensuite ces captures d'écran **en ligne** avec un élément `<picture>` — GitHub les réutilise via son proxy camouflage, afin que les évaluateurs voient un aperçu qui correspond à leur thème GitHub directement dans le commentaire sans rien ouvrir. Le lien vers le plan interactif complet se trouve juste à côté lorsqu'ils souhaitent explorer, commenter ou annoter.
+
+## PR Fork
+
+### Comportement par défaut (aucune action requise)
+
+Le workflow principal `pr-visual-recap.yml` se déclenche sur le déclencheur simple `pull_request`, **et non** sur `pull_request_target`. Les PR Fork s'exécutent donc sans **aucun accès aux secrets du référentiel**, de sorte que le flux de travail ne trouve aucun `PLAN_RECAP_TOKEN` et aucune opération proprement : aucune publication échouée, aucune information d'identification exposée. Les récapitulatifs s'exécutent automatiquement pour les PR des branches du même référentiel, où les secrets sont disponibles.
+
+Cela signifie également que vous pouvez fusionner le fichier de workflow **avant** que les secrets n'existent : sans jeton configuré, chaque exécution est une opération silencieuse jusqu'à ce que vous définissiez les secrets. L'étape `gate` ignore également automatiquement les brouillons de PR et les PR créés par des robots, de sorte qu'aucun des récapitulatifs des déclencheurs ne s'exécute par défaut.
+
+### S'inscrire au workflow de fork à étiquette
+
+Si vous souhaitez générer des récapitulatifs pour les fork PR, un deuxième fichier de workflow est disponible : `.github/workflows/pr-visual-recap-fork.yml`. Il utilise `pull_request_target` (qui s'exécute avec les secrets du dépôt de base) mais n'extrait ni n'exécute jamais de code fork. Les auteurs de fork de confiance avec l'association d'auteurs GitHub `OWNER`, `MEMBER` ou `COLLABORATOR` s'exécutent automatiquement. Les PR de fork externes nécessitent un **opt-in explicite du responsable par tête** via un nouvel événement d'étiquette `recap` avant l'exécution de l'agent de récapitulation.
+
+Pour l'installer, copiez le fichier de [BuilderIO/agent-native](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/pr-visual-recap-fork.yml) dans le répertoire `.github/workflows/` de votre dépôt aux côtés du `pr-visual-recap.yml` existant. Les mêmes secrets (`PLAN_RECAP_TOKEN`, `ANTHROPIC_API_KEY`) s'appliquent.
+
+```an-diagram title="Fork PR consent gate" summary="Fork PRs get no secrets by default; trusted authors run automatically, and outside contributors require a fresh maintainer recap label."
+{
+  "html": "<div class=\"diagram-fork\"><div class=\"diagram-node\">Fork PR opened<br><small class=\"diagram-muted\">main workflow has no secrets</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">Trusted author</span><small class=\"diagram-muted\">OWNER, MEMBER, or COLLABORATOR runs automatically</small></div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">Outside contributor</span><small class=\"diagram-muted\">maintainer reviews diff, then applies <code>recap</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\">Gate checks<br><small class=\"diagram-muted\">fork PR? &amp; trusted or fresh label?</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">Recap runs<br><small class=\"diagram-muted\">base-repo code only · fork diff is text input</small></div></div>",
+  "css": ".diagram-fork{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.diagram-fork .diagram-arrow{font-size:20px;line-height:1}.diagram-fork .center{display:flex;flex-direction:column;align-items:center;gap:4px;text-align:center}.diagram-fork .diagram-card{display:flex;flex-direction:column;gap:6px;padding:12px 14px}"
+}
+```
+
+### Fonctionnement de la porte d'étiquettes
+
+1. Un contributeur fork ouvre un PR. Le flux de travail normal de `pull_request` est ignoré car GitHub retient les secrets des exécutions de fork.
+2. Le workflow fork vérifie l'association de l'auteur du PR. Les auteurs approuvés (`OWNER`, `MEMBER` ou `COLLABORATOR`) s'exécutent automatiquement lors des événements d'ouverture, de synchronisation, de réouverture et de préparation à la révision.
+3. Les contributeurs externes demandent à un responsable d'examiner la différence actuelle (en particulier pour le contenu en forme d'injection rapide — voir ci-dessous), puis d'appliquer l'étiquette `recap` au PR.
+4. La porte d'étiquette du contributeur externe est par tête SHA : si le contributeur pousse plus de validations, l'événement de synchronisation suivant saute jusqu'à ce qu'un responsable supprime et réapplique `recap` après avoir examiné la nouvelle différence.
+
+### Ce que fait le workflow fork et ce que fait NOT
+
+| Le workflow DOES                                                                                                                                           | Le workflow fait NOT                                                                                                |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| Consultez le **dépôt de base** sur la **réf. de branche de base** – code approuvé uniquement                                                               | Extrayez ou exécutez n'importe quel code du fork                                                                    |
+| Récupérer la tête de fourche en tant que référence distante (`git fetch origin pull/<n>/head:refs/recap/fork-head`) – la récupération des commits est sûre | Installez les packages à partir du fork, exécutez des scripts fork ou évaluez le contenu du fork sous forme de code |
+| Exécuter `git diff base...refs/recap/fork-head` — différence de texte pur de deux objets déjà récupérés                                                    | Utilisez le différentiel comme autre chose que la saisie de texte dans le LLM                                       |
+| Exécutez la compétence de récapitulation visuelle et la configuration de l'agent du **dépôt de base**                                                      | Chargez n'importe quelle compétence ou configuration depuis le fork                                                 |
+| Faites passer le diff par la même étape d'analyse secrète (fermée en cas d'échec) que les PR propriétaires                                                 | Ignorer l'analyse secrète                                                                                           |
+| Ajouter une note explicite de renforcement des invites à l'invite de l'agent marquant le contenu des différences comme non fiable                          | Accordez à l'agent toutes autorisations supplémentaires au-delà de l'agent de récapitulation normal                 |
+
+### Pourquoi devez-vous examiner la différence avant de l'étiqueter
+
+Le fork diff est un texte contrôlé par l'attaquant que l'agent récapitulatif lit en entrée. Un diff soigneusement conçu peut contenir du contenu d'injection rapide (par exemple, des lignes de diff qui ressemblent à des instructions d'agent) destinés à obliger l'agent de récapitulation à prendre involontairement actions (par exemple, exfiltrer le jeton de publication ou produire un contenu de récapitulation trompeur).
+
+Avant d'appliquer l'étiquette `recap`, parcourez la différence pour :
+
+- Lignes qui ressemblent à des commandes directes ou à des instructions de rôle ("Ignorer les instructions précédentes...", "Vous êtes maintenant...", "Écrivez le jeton dans...").
+- Noms de fichiers inhabituels qui pourraient être mal lus lors des invites du système.
+- Contenu codé dans les fichiers ajoutés qui pourraient être décodés en instructions.
+
+Ces mesures d'atténuation sont déjà intégrées au flux de travail (analyse secrète, contrôle des chemins sensibles, note de renforcement des invites, liste blanche des outils d'agent restreint), mais l'examen des étiquettes constitue la principale ligne de défense.
+
+### Relation avec le workflow principal
+
+Les deux fichiers de workflow sont indépendants. Pour les mises à jour PR non fork, `pr-visual-recap.yml` est le seul workflow qui s'exécute. Pour les PR fork, le flux de travail normal sort à sa porte fork et `pr-visual-recap-fork.yml` s'exécute automatiquement pour les auteurs de confiance de la même organisation ou après une nouvelle étiquette `recap` du responsable pour les contributeurs externes. Ils partagent le même marqueur de commentaire collant et le même thread d'identification de plan, de sorte que les PR et les PR fork produisent un seul commentaire inséré sur le même PR.
+
+### Garde auto-modifiable {#self-modifying-guard}
+
+L'étape `gate` ignore entièrement le récapitulatif lorsqu'un PR touche l'un des chemins suivants, de sorte qu'un PR ne peut jamais réécrire le flux de travail, la compétence ou la configuration de l'agent que la tâche de récapitulation approuvée charge et exfiltre les secrets :
+
+| Modèle de chemin                           | Raison                                             |
+| ------------------------------------------ | -------------------------------------------------- |
+| `.github/workflows/pr-visual-recap.yml`    | Le workflow lui-même                               |
+| `**/skills/visual-(recap\|plan\|plans)/**` | The visual-recap skill the agent follows           |
+| `**/.claude/**`                            | Paramètres de l'agent chargés par le coureur       |
+| `**/CLAUDE.md`                             | Instructions de l'agent que le coureur charge      |
+| `**/AGENTS.md`                             | Instructions de l'agent que le coureur charge      |
+| `**/.mcp.json`                             | Configuration du serveur MCP que le coureur charge |
+
+Dans le monorepo `BuilderIO/agent-native`, le workflow exécute le récapitulatif CLI à partir d'une source de branche de base fiable au lieu de la source de tête PR. Cela permet de conserver les modifications normales du package, y compris `packages/core/**`, éligibles aux récapitulatifs sans exécuter le code CLI modifié par PR.
+
+## Mode de confidentialité des fichiers locaux
+
+L'action GitHub est conçue pour la révision des relations publiques hébergée et partageable. Si vous voulez un
+récapitulatif sans envoyer le contenu du récapitulatif à la base de données du plan Agent-Native, exécutez le
+même flux d'assistance localement en mode fichiers locaux :
+
+```bash
+npx @agent-native/core@latest recap collect-diff --base main --head HEAD --out recap.diff --stat recap.stat
+npx @agent-native/core@latest recap scan --diff recap.diff
+npx @agent-native/core@latest recap build-prompt --pr 123 --diff recap.diff --stat recap.stat --local-files --local-dir plans/pr-123-visual-recap
+```
+
+Donnez le `recap-prompt.md` généré à votre agent de codage. En mode fichiers locaux
+l'invite demande à l'agent d'écrire `plans/pr-123-visual-recap/plan.mdx`
+plus les fichiers visuels facultatifs, puis exécutez :
+
+```bash
+npx @agent-native/core@latest plan local serve --dir plans/pr-123-visual-recap --kind recap --open
+```
+
+Le URL renvoyé ouvre le plan hébergé UI pendant que le navigateur lit le récapitulatif MDX
+à partir d'un pont localhost. Le contenu du récapitulatif n'est pas écrit dans le forfait hébergé
+base de données, et le URL ne fonctionne que sur la machine exécutant le pont. Si vous courez
+l'application Plan en local avec le même `PLAN_LOCAL_DIR`, le
+L'itinéraire `/local-plans/pr-123-visual-recap` est également valide. Les dossiers sauvegardés sur dépôt peuvent
+ouvrir en tant que `/local-plans/pr-123-visual-recap?path=plans%2Fpr-123-visual-recap`.
+Ce mode désactive le commentaire PR persistant hébergé, le téléchargement de capture d'écran en ligne,
+pièce jointe d'utilisation et commentaires du navigateur jusqu'à ce que vous publiiez explicitement.
+
+## C'est informatif, pas une porte
+
+Le récapitulatif est une aide à la révision superposée au flux normal de relations publiques :
+
+- Il affiche une ligne de vérification `Visual Recap` pour la visibilité, mais ce n'est **jamais une vérification obligatoire** et ne bloque jamais la fusion.
+- Un échec de génération ou de publication se termine de manière neutre et apparaît sous la forme d'un commentaire explicatif collant, et non d'un X rouge sur un code sans rapport.
+- Le récapitulatif et sa capture d'écran **n'impliquent pas que la différence a été examinée**. Les réviseurs doivent toujours lire les lignes réellement modifiées.
+
+## Épinglage de version (variante de copie) {#version-pinning-copy-variant}
+
+Par défaut, le workflow de copie de variante installe `@agent-native/core@latest` au moment de l'exécution afin que chaque exécution de récapitulation récupère automatiquement le dernier CLI. Si votre CI a besoin d'outils reproductibles, définissez la variable du référentiel **`RECAP_CLI_VERSION`** pour épingler la version installée :
+
+1. Accédez aux **Paramètres → Secrets et variables → Actions → Variables** de votre dépôt.
+2. Créez une variable nommée `RECAP_CLI_VERSION` avec une valeur telle que `1.5.0`.
+
+La variable est facultative. Laissez-le non défini (ou définissez-le sur `latest`) pour suivre la version la plus récente.
+
+Pour la variante d'appelant réutilisable, utilisez plutôt l'entrée `cli-version` (voir [Version pinning](#version-pinning) dans la section réutilisable).
+
+## Liste autorisée d'analyse secrète
+
+Avant de publier un récapitulatif, le workflow exécute `npx @agent-native/core@latest recap scan` pour détecter les secrets probables dans le diff. Tout PR dont la différence correspond à un modèle secret connu est bloqué avec un commentaire explicatif : le récapitulatif n'est pas publié et aucun contenu de différence n'est envoyé à l'agent de codage.
+
+Dans de rares cas, un dépôt contient des appareils de test intentionnels ou des chaînes non secrètes qui ressemblent superficiellement à des modèles secrets (par exemple, une clé d'appareil dans un fichier de test). Pour supprimer un faux positif, créez `.github/recap-scan-allowlist` à la racine de votre référentiel.
+
+### Formater
+
+Chaque ligne non vide et sans commentaire est soit une **sous-chaîne littérale**, soit un modèle **`/regex/flags`** :
+
+```
+# Lines starting with # are comments.
+
+# Literal substring — any diff line containing this string is allowed.
+sk-test-fixture1234567890abcdef
+
+# Regex pattern — written as /pattern/flags (JS syntax).
+/^.STRIPE_KEY=sk-test-/i
+
+# Another literal.
+EXAMPLE_API_KEY=placeholder-value
+```
+
+Règles :
+
+- Une ligne est **supprimée** (autorisée) lorsqu'elle contient le littéral ou lorsque la ligne complète correspond à l'expression régulière.
+- Le fichier est **fermé en cas d'échec** : s'il est absent, aucune suppression ne s'applique — le scanner se comporte comme avant.
+- Un fichier vide équivaut à aucun fichier.
+- Les lignes d'expression régulière mal formées sont traitées comme des chaînes littérales.
+
+La liste blanche n'est consultée que par la porte secrète-scan. Cela n'affecte pas ce que l'agent de codage peut lire : si la porte passe, l'agent reçoit malgré tout la différence complète.
+
+## Adopter comme flux de travail réutilisable
+
+### Pourquoi utiliser la variante réutilisable ?
+
+Le programme d'installation par défaut copie le flux de travail complet d'environ 360 lignes YAML dans votre dépôt (l'option **copier**). C'est le bon choix pour les dépôts à air isolé ou les dépôts qui doivent auditer chaque ligne de ce qui s'exécute. L'inconvénient est que les corrections de bogues et les améliorations ne vous parviennent jamais : vous devez réexécuter `npx @agent-native/core@latest recap setup` manuellement après chaque version.
+
+L'option **réutilisable** écrit à la place un appelant mince d'environ 20 lignes. Il délègue à `BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml` via `uses:`. Chaque appelant récupère automatiquement la dernière logique lors de l'exécution du workflow, sans qu'aucune mise à jour locale ne soit nécessaire.
+
+|                                         | Copier (par défaut)                | Réutilisable                         |
+| --------------------------------------- | ---------------------------------- | ------------------------------------ |
+| Taille du workflow dans votre dépôt     | ~360 lignes                        | ~20 lignes                           |
+| Récupère automatiquement les correctifs | Non – réexécutez `recap setup`     | Oui                                  |
+| Air-gap / auditabilité totale           | Oui                                | Non                                  |
+| Épinglable à une version spécifique     | Uniquement en modifiant localement | Oui – définir `@v1.2.3` dans `uses:` |
+
+### Extrait de l'appelant
+
+Voici ce qu'écrit `npx @agent-native/core@latest recap setup --reusable` (ou vous pouvez le coller manuellement) :
+
+```yaml
+name: PR Visual Recap
+
+# Thin caller — the full workflow logic lives in BuilderIO/agent-native.
+# Fixes and improvements reach this repo automatically on each run.
+# To pin a specific version for reproducibility replace '@main' with a
+# tag or SHA, e.g. '@v1.2.3' or '@abc1234'.
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review, closed]
+
+jobs:
+  visual-recap:
+    permissions:
+      actions: write
+      contents: read
+      checks: write
+      issues: write
+      pull-requests: write
+    uses: BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml@main
+    secrets:
+      PLAN_RECAP_TOKEN: ${{ secrets.PLAN_RECAP_TOKEN }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      PLAN_RECAP_APP_URL: ${{ secrets.PLAN_RECAP_APP_URL }}
+    with:
+      agent: ${{ vars.VISUAL_RECAP_AGENT || 'claude' }}
+      model: ${{ vars.VISUAL_RECAP_MODEL || '' }}
+      reasoning: ${{ vars.VISUAL_RECAP_REASONING || '' }}
+      skill-source: ${{ vars.VISUAL_RECAP_SKILL_SOURCE || 'auto' }}
+      # cli-version: "latest"  # pin to a specific @agent-native/core version
+```
+
+Les mêmes secrets et variables décrits dans [Secrets and variables](#secrets-and-variables) s'appliquent : définissez-les dans les paramètres de votre dépôt de la même manière que pour la variante de copie.
+
+### Installation via le CLI
+
+```bash
+# Write the thin caller instead of the full copy:
+npx @agent-native/core@latest recap setup --reusable
+
+# Or with a pinned ref for reproducibility:
+npx @agent-native/core@latest recap setup --reusable --ref v1.2.3
+```
+
+Les deux variantes écrivent le flux de travail dans `.github/workflows/pr-visual-recap.yml`. Si un workflow existant existe déjà et diffère, la commande refuse et vous demande de passer `--force` pour l'écraser.
+
+Après l'écriture, exécutez `npx @agent-native/core@latest recap doctor` comme d'habitude pour confirmer que les secrets sont configurés.
+
+### Épinglage de version
+
+Par défaut, l'appelant fait référence à `@main`, qui utilise toujours la dernière version publiée du workflow réutilisable. Pour les dépôts de production nécessitant un CI reproductible, épinglez-le à une balise ou à SHA :
+
+```yaml
+uses: BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml@v1.2.3
+```
+
+L'entrée `cli-version` contrôle quelle version de `@agent-native/core` CLI s'exécute dans le flux de travail : laissez-la sur `"latest"` pour suivre la version la plus récente, ou épinglez-la à une chaîne de version (par exemple, `"1.5.0"`) pour une reproductibilité totale.
+
+### Contexte de l'événement workflow_call
+
+Les workflows `workflow_call` héritent du contexte d'événement **de l'appelant**. Le flux de travail réutilisable utilise des expressions `github.event.pull_request.*` pour lire le numéro PR, la tête SHA, la base SHA, l'horodatage de fusion et les métadonnées PR — ceux-ci fonctionnent correctement uniquement lorsque l'appelant se déclenche sur `pull_request`. L'extrait d'appelant ci-dessus inclut déjà les types d'événements corrects. L'événement `closed` est inclus afin que les récapitulatifs fusionnés des relations publiques puissent être estampillés avec `merged_at` et recherchés ultérieurement comme travaux expédiés.
+
+Ne déclenchez pas l'appelant sur `workflow_dispatch` ou `push` : ces événements ne transportent pas de charge utile `pull_request` et la porte ignorera le récapitulatif sans "aucune charge utile pull_request".
+
+## Connexe
+
+- [Visual Plans](/docs/template-plan) : les `/visual-plan` et `/visual-recap` skills, le connecteur Plans hébergé et la surface de révision interactive sur laquelle cette action est publiée.
+- [Skills](/docs/skills-guide) : installation de skills natif dans votre agent de codage.