specrails-desktop 2.8.0 → 2.9.1

package/docs/guide/fr/pipeline/3-batch-implement-and-multi-feature.md

@@ -0,0 +1,78 @@
+# Batch implement et multi-fonctionnalité
+
+Une spec à la fois, c'est très bien, mais beaucoup de travail réel arrive par grappes — une fonctionnalité plus ses tests plus sa migration, ou un backlog que vous voulez vider d'une traite. Cette page couvre l'exécution de plusieurs specs ensemble : le mode Batch, les vagues de dépendances, et comment le pipeline empêche le travail concurrent d'entrer en collision.
+
+## Exécuter plusieurs specs à la fois
+
+La façon la plus simple de lancer une pile de specs depuis un seul rail, c'est le mode **Batch** :
+
+1. **Glissez toutes les specs** que vous voulez sur un même rail. Elles s'empilent dans la liste de specs de ce rail.
+2. **Basculez le mode du rail sur Batch** (le sélecteur segmenté dans l'en-tête du rail).
+3. **Appuyez sur ▶ Play.**
+
+Le rail lance **un** job `/specrails:batch-implement` qui traite chaque spec assignée. Suivez-le comme n'importe quel autre job sur la page Jobs — c'est un seul job couvrant tout l'ensemble, pas un job par spec.
+
+C'est important à cause de la **file d'attente d'un job par projet**. Puisqu'un projet n'exécute qu'un job de rail à la fois, le mode Batch est aussi le moyen le plus propre d'*enchaîner* une liste de specs sans jongler avec plusieurs rails ni attendre que chacun se vide.
+
+### Implement vs Batch — quel mode ?
+
+| | **Implement** | **Batch** |
+|---|---|---|
+| Commande | `/specrails:implement` | `/specrails:batch-implement` |
+| Specs par job | Toutes celles du rail, traitées comme une seule unité de travail | Toutes celles du rail, traitées **séquentiellement** |
+| Idéal pour | Un changement fortement couplé | Plusieurs fonctionnalités distinctes que vous voulez traiter dans l'ordre |
+| Ordonnancement | s/o | Vagues tenant compte des dépendances (voir ci-dessous) |
+
+Si les specs ne forment réellement qu'un seul changement, utilisez **Implement**. Si c'est une liste de fonctionnalités séparées, utilisez **Batch** et laissez-le les séquencer.
+
+## Vagues de dépendances
+
+Le mode Batch ne se contente pas d'exécuter les specs de haut en bas — il calcule un **ordre d'exécution tenant compte des dépendances** et regroupe les specs en *vagues*. L'orchestrateur (`/specrails:batch-implement`) détermine quelles specs dépendent de quelles autres, puis les planifie de sorte que rien ne s'exécute avant le travail sur lequel il s'appuie.
+
+Conceptuellement :
+
+```
+Vague 1 :  #2 (modèle de données)   ← aucune dépendance, s'exécute en premier
+Vague 2 :  #4 (API sur le modèle)   ← attend #2
+           #5 (CLI sur le modèle)   ← attend #2
+Vague 3 :  #7 (docs sur l'ensemble) ← attend #4 et #5
+```
+
+Au sein du job, les specs de chaque vague sont implémentées avant que la vague suivante ne commence. Vous ne configurez rien à la main — l'orchestrateur déduit les vagues à partir des specs elles-mêmes. Regardez-le se dérouler dans la [vue détaillée du job](the-job-detail-view) : le log en streaming raconte sur quelle spec le batch travaille, et l'en-tête de ticket affiche chaque spec touchée par le job.
+
+## Isolation par worktree
+
+Lorsque plusieurs specs sont implémentées en une seule exécution, le pipeline garde chaque unité de travail isolée pour que les changements concurrents ou séquentiels ne piétinent pas les fichiers des autres. L'orchestrateur de batch exécute l'implémentation de chaque spec dans son propre contexte de travail propre, puis intègre les résultats — ainsi une spec à moitié finie ne laisse jamais votre arbre dans un état intermédiaire cassé et visible par la suivante.
+
+En pratique, cela signifie :
+
+- Chaque spec part d'une page blanche pour son implémentation, plutôt que d'hériter des modifications en cours de la spec précédente.
+- Les relectures et les étapes de ship opèrent sur un instantané cohérent, pas sur une cible mouvante.
+- Un échec dans une vague est contenu — il ne corrompt pas silencieusement les specs déjà livrées.
+
+L'application enregistre, par job, exactement quels fichiers ont été touchés et quel ticket les a touchés (vous verrez cela apparaître sous forme de puces de provenance dans la section **Code** et de liste « Fichiers touchés par ce ticket » dans la fenêtre de détail de chaque spec). Cette attribution est ce qui vous permet de faire confiance à une exécution multi-spec : vous pouvez toujours remonter d'une modification de fichier jusqu'à la spec qui l'a provoquée.
+
+## Multi-fonctionnalité entre projets
+
+Si vous voulez un vrai parallélisme — deux grosses fonctionnalités qui se construisent en même temps — répartissez-les **entre projets**, pas entre rails d'un même projet. Chaque projet possède sa propre file d'attente indépendante, donc :
+
+```
+Projet A   ▶ Rail exécutant la fonctionnalité X   ┐
+                                                  ├─ s'exécutent simultanément
+Projet B   ▶ Rail exécutant la fonctionnalité Y   ┘
+```
+
+Il n'y a aucune limite globale de concurrence et aucune contention entre projets. Ouvrez les deux, lancez un rail dans chacun, et ils progressent ensemble. Le seul régulateur partagé est votre plafond de budget, qui met les files en pause par projet ou pour toute l'application dès que la dépense du jour atteint la limite.
+
+## Conseils pour les gros batchs
+
+- **Regroupez les specs liées sur un seul rail** avant de basculer en Batch — les vagues de dépendances ne voient que ce qui se trouve sur ce rail.
+- **Définissez un budget quotidien** avant un gros batch pour qu'une exécution inopinément coûteuse se mette en pause automatiquement au lieu de s'emballer. Configurez-le sous [Budget](../settings/customizing).
+- **Utilisez le bouton Comparer** sur la page Jobs ensuite pour comparer deux exécutions de batch côte à côte.
+- **Exportez un diagnostic** (si la télémétrie était active) pour obtenir l'instantané exact du profil et des plugins de tout le batch.
+
+## Où aller ensuite
+
+- [Rails et jobs](rails-and-jobs) — le modèle de file d'attente en détail.
+- [La vue détaillée du job](the-job-detail-view) — regarder un batch s'exécuter en direct.
+- [Choisir un moteur par rail](picking-an-engine-per-rail) — notez que Batch fonctionne sur n'importe quel fournisseur ; Ultra est réservé à Claude.

package/docs/guide/fr/pipeline/4-picking-an-engine-per-rail.md

@@ -0,0 +1,60 @@
+# Choisir un moteur par rail
+
+Specrails desktop traite **Claude Code**, **Codex CLI** et **Gemini CLI** comme des moteurs de premier plan. Un projet peut en avoir un, deux ou les trois installés — et lorsque plus d'un est présent, vous choisissez quel moteur exécute chaque rail. Cette page couvre le sélecteur de moteur par rail et le moment où choisir chacun.
+
+## Quand le sélecteur apparaît
+
+Le **sélecteur de moteur** se trouve dans l'en-tête du rail, juste à côté du contrôle de mode. Il ne s'affiche que lorsque le projet possède **plus d'un** fournisseur installé.
+
+> **Les projets mono-fournisseur se comportent de manière strictement identique.** Si un projet n'a qu'un seul moteur, aucun sélecteur n'apparaît et rien ne change quant à la sélection du fournisseur — il s'exécute simplement sur ce moteur. Le sélecteur est purement réservé aux projets multi-fournisseurs.
+
+Quand il apparaît, votre choix se fait **par rail et par lancement** — différents rails peuvent exécuter différents moteurs, et votre choix est mémorisé par projet (avec, par défaut, le moteur principal du projet).
+
+## Comment choisir un moteur
+
+1. Assurez-vous que le sélecteur de moteur du rail est visible (le projet a 2 fournisseurs ou plus).
+2. Cliquez dessus et choisissez **Claude**, **Codex** ou **Gemini**.
+3. Lancez le rail avec **▶ Play**.
+
+Le moteur sélectionné exécute chaque phase du pipeline de ce rail. Si la CLI du moteur choisi n'est pas installée, le lancement échoue immédiatement — rien ne démarre. Installez la CLI manquante et réessayez.
+
+## Les points forts de chaque moteur
+
+Les trois exécutent les pipelines standards **Implement** et **Batch**. Voici un guide pratique pour choisir :
+
+| Moteur | À privilégier quand… | Notes |
+|--------|--------------------|-------|
+| **Claude** | Vous voulez l'ensemble complet des fonctionnalités : profils d'agents, Ultracode, rapport de coût natif, le support d'outils le plus riche. Le choix par défaut pour la plupart du travail. | Le seul moteur qui prend en charge les **profils d'agents**, **Ultracode**, et quelques fonctionnalités de spec réservées à Claude (Contract Layer, SMASH). |
+| **Codex** | Vous préférez la CLI Codex d'OpenAI ou vous voulez comparer les implémentations entre fournisseurs. | `codex` ≥ 0.128.0. Pas de rapport de coût natif — l'application complète le coût à partir de sa table de tarifs. Les profils ne s'appliquent pas. |
+| **Gemini** | Vous voulez la CLI Gemini de Google, la télémétrie native, ou une exécution moins chère pour les specs de routine. | `gemini` ≥ 0.11.0 (définissez `GEMINI_API_KEY`). Télémétrie OTLP native. Les profils ne s'appliquent pas. |
+
+### Les fonctionnalités réservées à Claude
+
+Quelques éléments ne fonctionnent que sur les rails Claude — choisissez Claude si vous en avez besoin :
+
+- **Profils d'agents** — routage de modèle par agent. Sur les rails Codex ou Gemini, l'exécution utilise toujours le mode legacy et tout profil sélectionné est **ignoré**. Le sélecteur de profil est masqué pour les moteurs non-Claude.
+- **Ultracode (mode `Ultra`)** — le mode autonome qui contourne le pipeline. Le segment `Ultra` et son sélecteur de modèle Haiku/Sonnet/Opus n'apparaissent que lorsque le moteur du rail est Claude.
+- **Contract Layer et SMASH** — fonctionnalités de raffinement de spec réservées à Claude (ce sont des options d'Add Spec, pas des options de rail, mais la même contrainte s'applique).
+
+Si un projet mélange les moteurs, la barre latérale droite n'affiche que les sections prises en charge par **tous** les fournisseurs installés — la section **Agents** disparaît donc entièrement sur un projet qui inclut un fournisseur non-Claude, car les profils sont spécifiques à Claude.
+
+## Un flux de travail pratique
+
+Les projets multi-fournisseurs brillent lorsque vous voulez **comparer** ou **optimiser les coûts** :
+
+- **Comparer les implémentations.** Mettez la même spec sur deux rails, réglez l'un sur Claude et l'autre sur Codex, lancez les deux (entre projets, ou l'un après l'autre dans la file du même projet), puis utilisez le bouton **Comparer** sur la page Jobs pour comparer les résultats.
+- **Optimiser le coût par spec.** Exécutez les specs à fort enjeu sur Claude avec un profil `max` ; exécutez les specs de nettoyage de routine sur Gemini pour économiser. Filtrez `/analytics` par moteur pour voir la répartition.
+- **Définir un défaut judicieux.** Désignez votre moteur le plus utilisé comme moteur principal du projet pour que les rails l'utilisent par défaut, et ne changez par rail que lorsqu'une spec particulière demande un moteur différent.
+
+## Points à garder en tête
+
+- **La sélection des fournisseurs est immuable après la création du projet** (v1). Vous choisissez les fournisseurs installés au moment d'ajouter le projet ; il n'y a aucun réglage dans les Paramètres pour en ajouter ou en retirer un plus tard.
+- **Le coût est toujours suivi**, même pour les moteurs sans rapport de coût natif — l'application se rabat sur une table de tarifs, de sorte que les exécutions Codex et Gemini apparaissent quand même dans les [analytics](../analytics/tracking-cost).
+- **Le bouton « Open AI CLI » du terminal** propose également un sélecteur de fournisseur sur les projets multi-fournisseurs, si vous préférez piloter une CLI à la main.
+
+## Où aller ensuite
+
+- [Utiliser Codex](../integrations/using-codex) — installation et connexion.
+- [Utiliser Gemini](../integrations/using-gemini) — installation, `GEMINI_API_KEY`, télémétrie.
+- [Rails et jobs](rails-and-jobs) — la file d'attente et le flux de lancement.
+- [Suivre le coût](../analytics/tracking-cost) — répartition du coût par moteur.

package/docs/guide/fr/settings/1-themes.md

@@ -0,0 +1,37 @@
+# Thèmes
+
+Donnez à Specrails l'allure qui vous plaît. L'application est livrée avec cinq thèmes peaufinés à la main que vous pouvez changer instantanément — sans redémarrage, sans recompilation, sans rien à configurer.
+
+## Les cinq thèmes intégrés
+
+| Thème | Ambiance |
+| --- | --- |
+| **Specrails** | Le thème par défaut. Équilibré, apaisant, fidèle à la marque. |
+| **Dracula** | Le grand classique sombre et violet. Doux pour les yeux la nuit. |
+| **Aurora Light** | Un thème clair, lumineux et aéré pour travailler en journée. |
+| **Obsidian Dark** | Un mode sombre profond et très contrasté. |
+| **Matrix** | Du vert sur fond noir, pour quand vous avez envie de vous sentir dans le mainframe. |
+
+## Comment changer de thème
+
+1. Ouvrez les **Paramètres** (la fenêtre de paramètres globale de l'application).
+2. Rendez-vous dans la section **Apparence**.
+3. Choisissez un thème. Il s'applique immédiatement à toute l'application.
+
+C'est tout. Le changement prend effet dès que vous cliquez — l'interface se recolore en direct.
+
+## Là où il s'applique
+
+Votre choix de thème est valable pour **toute l'application**, pas projet par projet. Chaque projet, chaque page, chaque panneau suit le même thème. Il atteint même les endroits auxquels vous ne penseriez pas :
+
+- **Le panneau de terminal** se recolore en direct, tout en préservant votre historique de défilement et toute session shell en cours.
+- **Les graphiques** de la page Analytics se reteintent pour rester assortis.
+- **La coloration syntaxique du code** dans la visionneuse Code suit elle aussi le thème.
+
+## Il se souvient de votre choix
+
+Votre sélection est enregistrée avec l'application, donc elle reste en place d'un démarrage à l'autre. Pour éviter ce bref flash de mauvaises couleurs à la première ouverture, Specrails applique votre thème enregistré avant même que l'interface ait fini de charger — ce que vous voyez est donc correct dès la toute première image.
+
+## Une note pour les curieux
+
+Les thèmes reposent sur un petit ensemble de rôles de couleur sémantiques (une couleur « accent », une couleur « surface », etc.) plutôt que sur des teintes codées en dur. C'est pour cela qu'ajouter le prochain thème est si simple et que chaque thème reste cohérent de l'intérieur — il lui suffit de réassigner ces rôles. Vous n'avez pas besoin de penser à tout cela pour l'utiliser ; c'est simplement la raison pour laquelle le thème paraît si fluide.

package/docs/guide/fr/settings/2-language.md

@@ -0,0 +1,39 @@
+# Langue
+
+Specrails parle votre langue. L'interface est entièrement traduite en huit langues et, par défaut, elle suit la langue configurée sur votre ordinateur — pour la plupart des gens, elle s'affiche donc d'emblée dans la bonne langue dès le premier lancement.
+
+## Langues prises en charge
+
+- English
+- Español (Spanish)
+- Français (French)
+- Deutsch (German)
+- Português (Portuguese)
+- Italiano (Italian)
+- 中文 (Chinese)
+- 日本語 (Japanese)
+
+## Elle démarre dans la langue de votre système
+
+La première fois que vous ouvrez Specrails, l'application regarde les préférences linguistiques de votre système d'exploitation et les associe à la langue prise en charge la plus proche. Si votre Mac ou votre PC est en espagnol, vous verrez l'espagnol. S'il est réglé sur une variante régionale (comme `es-ES` ou `zh-Hans-CN`), Specrails la fait automatiquement correspondre à la bonne langue de base.
+
+Vous n'avez rien à faire — et si vous ne touchez jamais au réglage de langue, Specrails continue de suivre votre système. Changez plus tard la langue de votre ordinateur, et Specrails s'aligne aussitôt.
+
+## Choisir une langue vous-même
+
+Vous voulez autre chose que la langue de votre système ? Choisissez-la explicitement :
+
+1. Ouvrez les **Paramètres**.
+2. Rendez-vous dans la section **Langue**.
+3. Choisissez votre langue.
+
+Le changement est **instantané** — toute l'interface se réaffiche dans la nouvelle langue, sans redémarrage. Dès que vous faites un choix explicite, Specrails le mémorise et cesse de suivre le système, si bien que votre préférence est respectée à chaque ouverture de l'application.
+
+## Ce qui est traduit
+
+Tout ce que vous lisez dans l'interface — boutons, libellés, messages d'état, titres de page, boîtes de dialogue. Les dates s'adaptent elles aussi à la langue choisie, et sont donc formatées de la façon attendue dans cette langue.
+
+## Bon à savoir
+
+- **L'anglais est la langue source.** Si une toute nouvelle fonctionnalité arrive avant la fin de sa traduction, vous pourrez voir brièvement un libellé en anglais ici ou là — il sera traduit dans une mise à jour suivante.
+- Votre choix de langue vaut pour **toute l'application**, à l'identique sur tous vos projets.

package/docs/guide/fr/settings/3-pipeline-telemetry-and-diagnostics.md

@@ -0,0 +1,46 @@
+# Télémétrie & diagnostics du pipeline
+
+Quand un job de pipeline ne se déroule pas comme prévu, la télémétrie vous offre un compte rendu détaillé et en coulisses de ce que la CLI d'IA a réellement fait. Elle est **désactivée par défaut** et entièrement optionnelle, projet par projet — ne l'activez que lorsque vous en avez besoin.
+
+## De quoi s'agit-il
+
+La télémétrie capture des signaux de diagnostic structurés (traces, métriques et logs) émis par la CLI d'IA pendant qu'elle exécute un job de pipeline. Voyez-la comme une boîte noire de vos exécutions de pipeline : minutages, usage de tokens et activité étape par étape, capturés localement pour que vous puissiez inspecter un job après coup.
+
+Elle repose sur **OpenTelemetry**, un format ouvert et standard — vos données ne sont donc pas enfermées dans une boîte propriétaire.
+
+## L'activer
+
+La télémétrie se configure **par projet** :
+
+1. Ouvrez la page **Paramètres** du projet (la route de paramètres propre au projet).
+2. Repérez l'interrupteur **Télémétrie du pipeline**.
+3. Activez-le.
+
+À partir de là, les jobs de pipeline de ce projet enregistrent la télémétrie. Les autres projets ne sont pas affectés — chaque projet décide pour lui-même.
+
+### Ce qui est couvert
+
+La télémétrie s'applique aux **jobs de pipeline** (les exécutions de rail en file Architect → Developer → Reviewer → Ship). Les sessions interactives comme le chat et l'assistant de configuration en sont volontairement exclues — la télémétrie est conçue pour les exécutions de pipeline répétables et inspectables, pas pour les conversations ponctuelles.
+
+## Où vivent les données
+
+Tout reste sur votre machine, sous votre dossier personnel (`~/.specrails/`) — jamais dans votre dépôt. Les enregistrements bruts sont stockés compressés à côté de leur job, et les plus anciens sont automatiquement condensés en résumés compacts au bout d'une semaine pour garder le tout bien rangé. Vous n'avez jamais à gérer quoi que ce soit à la main.
+
+## Exporter un bundle de diagnostic
+
+Le plus utile que débloque la télémétrie, c'est l'**export de diagnostic** — une unique archive ZIP qui rassemble tout ce qui concerne un job, pour le dépannage ou le partage.
+
+Lorsqu'un job a de la télémétrie enregistrée, un **bouton d'export** apparaît sur sa carte de job. Cliquez dessus pour télécharger un ZIP contenant :
+
+- **`job-metadata.json`** — l'identité et les paramètres du job
+- **`telemetry.ndjson`** — les signaux bruts enregistrés
+- **`logs.txt`** — la sortie de logs capturée
+- **`summary.md`** — un résumé lisible de l'exécution
+
+Si le projet utilise des plugins, le bundle inclut aussi un instantané des plugins qui étaient actifs pour ce job.
+
+C'est le bundle à récupérer quand vous voulez comprendre une exécution délicate, en garder une trace, ou transmettre des détails à quelqu'un qui vous aide à déboguer.
+
+## Le désactiver
+
+Remettez l'interrupteur en position désactivée à tout moment. Les nouveaux jobs cessent d'enregistrer immédiatement. Tout ce qui a déjà été capturé reste sur le disque jusqu'à sa compaction ou jusqu'à ce que vous supprimiez le projet — rien n'est envoyé où que ce soit ni perdu à votre insu.

package/docs/guide/fr/settings/4-where-your-data-lives.md

@@ -0,0 +1,48 @@
+# Où vivent vos données
+
+En résumé : **Specrails garde vos dépôts impeccables.** Quand vous pointez l'application vers l'un de vos projets, elle ne s'y installe pas, n'éparpille pas des fichiers de configuration partout et ne réécrit rien que vous n'ayez demandé. Votre code reste le vôtre, et propre.
+
+## Votre dépôt reste propre
+
+Les fichiers propres à Specrails — ses bases de données, l'état par projet, les définitions d'agents, les paramètres, la télémétrie, les résumés et tout le reste de ce dont il a besoin pour fonctionner — vivent dans un unique foyer bien rangé sous votre dossier personnel :
+
+```
+~/.specrails/
+```
+
+Ce dossier est l'espace de travail privé de l'application. C'est là que résident le registre des projets, les bases de données par projet, l'outillage embarqué et tous les rouages opérationnels. Vos véritables dépôts de code ne servent jamais de décharge pour quoi que ce soit de tout cela.
+
+Cela signifie :
+
+- Le `.gitignore` de votre dépôt n'est **pas** réécrit par l'application.
+- Votre dépôt n'est pas encombré de configs d'outils ni de répertoires d'état cachés.
+- Retirer un projet de Specrails ne laisse aucun désordre derrière lui dans votre code.
+
+Si vous avez déjà utilisé des outils qui ajoutaient discrètement des dossiers et des fichiers un peu partout dans votre projet, c'est ici une rupture assumée. Specrails est conçu pour que pointer l'application vers un dépôt soit un **non-événement** pour l'historique git de ce dépôt.
+
+## La seule chose qui *est* commitée — et c'est voulu
+
+Il existe exactement une exception intentionnelle, et c'est tout l'intérêt de l'outil : **vos specs OpenSpec.**
+
+Les specs vivent dans votre dépôt, sous :
+
+```
+openspec/
+```
+
+C'est volontaire. Vos specs sont un **livrable** — un enregistrement versionné et revuable de ce que vous avez décidé de construire et pourquoi. Elles ont leur place à côté de votre code, suivies dans git, visibles dans les pull requests, partagées avec votre équipe. C'est là toute la valeur : les specs ne sont pas un brouillon jetable, elles font partie de l'histoire de votre projet.
+
+La règle est donc simple et honnête :
+
+- **`openspec/`** → vit dans votre dépôt, commité, par conception.
+- **Tout le reste dont Specrails a besoin** → vit sous `~/.specrails/`, hors de votre chemin.
+
+## Pourquoi ça marche ainsi
+
+Specrails exécute l'outillage d'IA depuis son propre espace de travail privé (sous `~/.specrails/`) et ne revient dans votre véritable dépôt que pour les choses qui ont réellement besoin d'y toucher — lire votre code, et écrire les specs que vous avez demandées. L'outillage, les définitions du framework et toute la comptabilité restent dans le dossier personnel de l'application.
+
+Le bénéfice pour vous : vous pouvez ajouter un projet, lancer des pipelines, explorer des specs et faire des essais en toute confiance, sachant que l'arborescence de travail et l'historique git de votre dépôt ne changent jamais que de la façon attendue — vos specs commitées, et le code que vos pipelines écrivent. Rien d'autre ne se glisse à l'intérieur.
+
+## Retirer un projet
+
+Quand vous retirez un projet de Specrails, l'application nettoie son propre état par projet sous `~/.specrails/`. Les specs déjà commitées dans votre dépôt restent là où elles doivent être — dans votre dépôt — parce qu'elles sont à vous.

package/docs/guide/fr/specs/1-specs-and-the-backlog.md

@@ -0,0 +1,52 @@
+# Les specs et le backlog
+
+Une **spec** est l'unité de travail que le pipeline IA met en œuvre. Voyez-la comme un ticket : un titre, une description de ce que vous voulez réaliser, une priorité et, en option, des labels. Quand vous lancez le pipeline, les agents IA lisent la spec et agissent à partir d'elle — une spec claire est donc l'élément le plus important pour obtenir un bon résultat.
+
+Dans l'app, les specs sont parfois appelées **tickets** — les deux mots désignent exactement la même chose.
+
+## Le tableau
+
+Chaque projet s'ouvre sur son **Dashboard**, qui affiche le **SpecsBoard** — la liste de toutes les specs du projet. C'est votre backlog. C'est d'ici que vous créez de nouvelles specs, définissez leur priorité, les glissez sur un rail pour les mettre en œuvre, et suivez l'évolution de leur statut au fil du travail.
+
+Le tableau propose deux modes d'affichage, basculables depuis un bouton de la barre d'outils et mémorisés par projet :
+
+- **Vue post-it** (par défaut) — des tuiles façon cartes avec de courts résumés.
+- **Vue liste** — des lignes compactes sur une seule ligne.
+
+Vous pouvez aussi filtrer par **statut** (Tous / À faire / Terminé) et par **label**, et trier par **Par défaut**, **Ticket #** ou **Priorité** (chacun avec un sens croissant/décroissant).
+
+## Les statuts
+
+Une spec traverse un petit ensemble de statuts. Le tableau donne à chacun un repère visuel cohérent, pour que vous lisiez l'état de votre backlog d'un seul coup d'œil :
+
+| Statut | Ce que ça signifie |
+|--------|---------------|
+| **Brouillon** | Une idée en cours, enregistrée depuis une conversation Explore. Pas encore prête à être mise en œuvre — vous pouvez y revenir et continuer à la façonner. Affiche une pastille `Draft`. |
+| **À faire** | Prête à être prise en charge. C'est là qu'atterrit une spec finalisée lors de sa création. |
+| **En cours** | Le pipeline travaille actuellement dessus (un point bleu qui pulse). |
+| **Terminé** | Achevée par le pipeline (une coche verte). |
+| **Annulé** | Abandonnée (une croix rouge). |
+
+Les brouillons vivent dans le même groupe actif que les specs À faire — il n'y a pas de colonne séparée pour eux — mais ils arborent une bordure subtilement teintée et une pastille `Draft` pour être facilement repérables. Voir [Les brouillons et le Contract Layer](drafts-and-contract-layer.md) pour tout savoir sur les brouillons.
+
+## Les priorités
+
+Toute spec non-brouillon possède une priorité : **Critique**, **Haute**, **Moyenne** ou **Basse**. La priorité est purement un outil d'organisation — elle vous aide à décider quoi mettre en œuvre ensuite et permet de trier le tableau. Vous la définissez à la création d'une spec, et vous pouvez la changer à tout moment via un clic droit sur la carte de la spec, en choisissant **Définir la priorité**.
+
+Les brouillons sont la seule exception : un brouillon peut n'avoir *aucune* priorité, car c'est encore une idée en cours. La priorité est verrouillée au moment où vous validez le brouillon en spec à part entière.
+
+## Créer une spec
+
+Pour créer une spec, cliquez sur **Ajouter** (le bouton Plus de la barre d'outils du SpecsBoard). La fenêtre **Ajouter une spec** s'ouvre, avec plusieurs façons de travailler :
+
+- **Mode Quick** — vous décrivez ce que vous voulez et l'IA écrit la spec complète en un seul coup. Voir [Ajouter une spec — mode Quick](add-spec-quick-mode.md).
+- **Mode Explore** — vous échangez avec l'IA, qui vous aide à façonner la spec tour après tour. Voir [Ajouter une spec — mode Explore](add-spec-explore-mode.md).
+- **Mode Raw** — ce que vous tapez est enregistré tel quel comme spec, sans aucune intervention de l'IA. À utiliser quand vous avez déjà rédigé le texte de la spec.
+
+Le choix dépend du degré de clarté de votre idée. Vous savez exactement ce que vous voulez ? Quick. Vous êtes encore en train d'y réfléchir ? Explore. Vous avez déjà le texte ? Raw.
+
+## Pour aller plus loin
+
+- [Ajouter une spec — mode Quick](add-spec-quick-mode.md) — la façon la plus rapide de transformer une idée en spec.
+- [Ajouter une spec — mode Explore](add-spec-explore-mode.md) — façonner une spec par la conversation.
+- [Les brouillons et le Contract Layer](drafts-and-contract-layer.md) — enregistrer un travail en cours et enrichir les specs pour le pipeline.

package/docs/guide/fr/specs/2-add-spec-quick-mode.md

@@ -0,0 +1,45 @@
+# Ajouter une spec — mode Quick
+
+Le mode Quick, c'est pour quand vous savez déjà ce que vous voulez. Vous tapez votre idée, l'IA écrit la spec complète, et elle atterrit sur votre tableau au statut **À faire**. Aucun aller-retour — vous décrivez et c'est parti.
+
+## Créer une spec en mode Quick
+
+Pour créer une spec rapidement :
+
+1. Sur le Dashboard, cliquez sur **Ajouter** (le bouton Plus de la barre d'outils du SpecsBoard).
+2. Choisissez le mode **Quick**.
+3. Tapez votre idée dans le champ de texte — une phrase ou un paragraphe, ce qui la capture le mieux.
+4. Cliquez pour générer.
+
+Pendant que la spec est rédigée, un petit toast dans le coin affiche le nom du projet, un extrait de votre idée et le **temps écoulé** (« Génération… 0:12 »). Une fois terminé, le toast bascule sur « Généré en <durée> » avec une action **Voir** qui vous emmène directement à votre nouvelle spec.
+
+C'est tout le déroulé. Tout ce qui suit n'est qu'un réglage fin optionnel.
+
+## Ce que vous pouvez ajuster
+
+**Modèle** — par défaut, l'IA choisit un modèle adapté. Vous pouvez le surcharger spec par spec depuis le sélecteur de modèle, si vous en voulez un plus rapide ou plus performant.
+
+**Moteur** — si votre projet a plus d'un fournisseur IA installé (n'importe quelle combinaison de Claude, Codex et Gemini), un sélecteur de moteur figure en haut de la fenêtre pour choisir lequel génère cette spec. Votre choix est mémorisé par projet. Les projets à fournisseur unique ne l'affichent pas — il n'y a rien à choisir.
+
+**Contexte** — le mode Quick s'exécute en général en un seul tour, car il n'a pas besoin de lire votre base de code pour rédiger une spec à partir de votre description. Mais un curseur de contexte lui permet de disposer de plus d'éléments :
+
+- Au réglage le plus bas, il lit simplement votre description.
+- Aux réglages plus élevés, il peut lire vos specs existantes, les specs OpenSpec de votre projet, et même l'intégralité de votre base de code avant de rédiger.
+
+Plus vous lui donnez de contexte, plus la génération est longue (il passe en multi-tour pour pouvoir lire d'abord), mais la spec revient ancrée dans votre projet réel. Optez pour un contexte plus élevé quand la spec doit faire référence à du vrai code, à des noms de fichiers ou à un comportement existant.
+
+**Pièces jointes** — déposez des maquettes, des briefs ou des fichiers de données dans le champ d'idée. L'IA les lit dans le cadre de la rédaction de la spec. (Les pièces jointes font aussi passer la génération en multi-tour.)
+
+**Enrichir avec le Contract Layer** — un interrupteur qui ajoute un bloc structuré à la spec générée, pour que le pipeline en aval n'ait pas à deviner les noms ni les formes de données. C'est optionnel et désactivé par défaut ; votre dernier choix est mémorisé par projet. Voir [Les brouillons et le Contract Layer](drafts-and-contract-layer.md) pour ce qu'il apporte et quand cela en vaut la peine.
+
+## Quand utiliser le mode Quick plutôt qu'Explore
+
+Utilisez **Quick** quand l'idée est déjà claire dans votre tête — vous pourriez écrire la spec vous-même, vous préférez juste que l'IA le fasse. Utilisez [**Explore**](add-spec-explore-mode.md) quand vous êtes encore en pleine réflexion et que vous voulez un partenaire pour vous aider à la façonner.
+
+Une spec créée en mode Quick est une spec tout à fait normale : vous pouvez plus tard l'ouvrir et **Continuer l'édition** dans une session Explore si elle a besoin d'être affinée.
+
+## Pour aller plus loin
+
+- [Ajouter une spec — mode Explore](add-spec-explore-mode.md) — pour les specs qui ont besoin d'être façonnées.
+- [Les brouillons et le Contract Layer](drafts-and-contract-layer.md) — l'enrichissement Contract Layer expliqué.
+- [Exécuter les pipelines](running-pipelines.md) — glissez votre nouvelle spec sur un rail et mettez-la en œuvre.

package/docs/guide/fr/specs/3-add-spec-explore-mode.md

@@ -0,0 +1,68 @@
+# Ajouter une spec — mode Explore
+
+Le mode Explore, c'est une conversation. Au lieu d'écrire la spec vous-même, vous discutez de l'idée avec l'IA — elle joue les partenaires de réflexion, pose des questions, propose une structure et construit un **brouillon vivant** de la spec au fil de l'échange. Quand le résultat vous convient, vous validez le brouillon en spec à part entière.
+
+Optez pour Explore quand l'idée n'est pas encore complètement formée, quand il y a des compromis à débattre, ou quand vous voulez que l'IA examine votre vrai code avant de figer la spec.
+
+## Créer une spec en mode Explore
+
+Pour façonner une spec en mode Explore :
+
+1. Sur le Dashboard, cliquez sur **Ajouter**, puis choisissez **Explore**.
+2. Tapez votre premier message — l'idée, une question, ou une pensée encore brute.
+3. Lisez la réponse de l'IA et continuez à répondre. À chaque tour, elle affine sa compréhension.
+4. Observez le **brouillon vivant** se mettre à jour à côté du chat — c'est la spec qui prend forme.
+5. Quand le brouillon vous convient, cliquez sur **Créer la spec**.
+
+La conversation reste dans votre historique : vous pouvez toujours y revenir pour voir comment la spec a été façonnée.
+
+## Le brouillon vivant
+
+Au fil de l'échange, un volet de brouillon affiche la spec dans son état actuel — titre, description, priorité, labels, critères d'acceptation. Il se réécrit à chaque tour en fonction de ce que vous avez discuté. Vous ne l'éditez pas directement ; vous le pilotez par la conversation (« en fait, mets la priorité en haute », « ajoute un critère sur la gestion des erreurs », et ainsi de suite).
+
+C'est tout le cœur du mode Explore : vous n'êtes jamais face à un formulaire vide. Vous regardez toujours une spec réelle, qui évolue.
+
+## Ce que l'IA voit : le curseur de contexte
+
+Avant que l'IA ne réponde, vous décidez quelle part de votre projet elle peut voir. Un curseur de préréglages de contexte vous laisse arbitrer entre vitesse et profondeur :
+
+| Préréglage | Ce que l'IA voit |
+|--------|------------------|
+| **Minimal** | Juste votre message. Le plus rapide et le moins cher. |
+| **Léger** | + vos specs existantes. |
+| **Standard** | + vos specs et les specs OpenSpec de votre projet. |
+| **Riche** | + un accès en lecture à toute votre base de code, pour ancrer ses réponses dans du vrai code. |
+| **Max** | Riche, plus une passe d'enrichissement Contract Layer à la validation. |
+| **Desktop** | Max, plus les serveurs MCP de votre projet et vos propres serveurs MCP approuvés. |
+
+Commencez bas pour un brainstorming rapide ; montez quand vous voulez que l'IA vérifie ses suggestions face à votre vrai code. Le choix est enregistré sur la conversation, il ne déborde donc pas sur les autres sessions Explore.
+
+Si vous voulez un contrôle plus fin, cliquez sur **Réglages fins** pour basculer les options sous-jacentes à la main — y compris **Mes MCP approuvés**, qui charge les serveurs MCP que vous avez déjà approuvés localement sans ralentir la session.
+
+## Les boutons du panneau Explore
+
+- **Créer la spec** — promeut le brouillon vivant en spec à part entière, au statut **À faire**. (Quand vous éditez une spec existante, ce bouton affiche plutôt **Mettre à jour la spec** et applique les modifications à cette spec en place.)
+- **Vérifier →** — ouvre une surcouche de vérification qui montre la spec proposée comparée à la version de référence avant validation, pour éviter toute surprise.
+- **Enregistrer comme brouillon** — conserve la conversation comme ticket brouillon pour la reprendre plus tard. Disponible dès que vous avez envoyé au moins un message. Voir ci-dessous.
+- **Réduire** — range la conversation sous forme de pastille dans le dock des chats réduits, en bas à gauche. Cliquez sur la pastille à tout moment pour replonger directement dans la conversation — rien n'est perdu.
+- **Abandonner** — jette la conversation (avec une demande de confirmation au préalable).
+
+## Enregistrer comme brouillon
+
+Pas prêt à valider, mais vous ne voulez pas perdre votre réflexion ? Cliquez sur **Enregistrer comme brouillon**. La conversation devient une **spec brouillon** sur votre tableau, et le brouillon reste lié à la conversation qui le sous-tend.
+
+Plus tard, ouvrez le brouillon depuis le tableau et cliquez sur **Continuer l'édition** — la conversation d'origine se rouvre avec tout son historique de chat intact, et vous reprenez exactement là où vous vous étiez arrêté. Les brouillons ne sont jamais supprimés automatiquement ; ils vous attendent.
+
+C'est ce qui rend Explore sans risque pour les idées à moitié cuites : démarrez une conversation, avancez un peu, enregistrez-la comme brouillon, et revenez demain.
+
+Pour tout savoir sur les brouillons — y compris l'enrichissement Contract Layer — voir [Les brouillons et le Contract Layer](drafts-and-contract-layer.md).
+
+## Note multi-fournisseur
+
+Si votre projet a plus d'un fournisseur IA installé, un sélecteur de moteur vous laisse choisir lequel pilote la conversation Explore. Les projets à fournisseur unique ne l'affichent pas.
+
+## Pour aller plus loin
+
+- [Les brouillons et le Contract Layer](drafts-and-contract-layer.md) — enregistrer un travail en cours et enrichir les specs pour le pipeline.
+- [Ajouter une spec — mode Quick](add-spec-quick-mode.md) — quand l'idée est déjà claire.
+- [Exécuter les pipelines](running-pipelines.md) — mettez votre spec en œuvre une fois qu'elle est prête.

package/docs/guide/fr/specs/4-drafts-and-contract-layer.md

@@ -0,0 +1,81 @@
+# Les brouillons et le Contract Layer
+
+Cette page couvre deux façons de tirer davantage de vos specs : les **brouillons** (enregistrer une idée en cours pour la reprendre plus tard) et le **Contract Layer** (un enrichissement optionnel qui rend les specs plus précises pour le pipeline IA).
+
+## Les brouillons : enregistrer une idée en cours
+
+Un **brouillon** est une conversation [Explore](add-spec-explore-mode.md) en cours, enregistrée comme spec. Il vous permet de vous arrêter au milieu d'une réflexion sans rien perdre, et de revenir quand vous êtes prêt.
+
+### Enregistrer un brouillon
+
+Pendant une conversation Explore, cliquez sur **Enregistrer comme brouillon** (disponible dès que vous avez envoyé au moins un message). L'app :
+
+- Crée une spec au statut **Brouillon** sur votre tableau.
+- Lui attribue un titre automatiquement si vous n'en avez pas défini (un court résumé de la conversation).
+- La relie à la conversation, de sorte que tout l'historique de chat est préservé.
+
+L'enregistrement est idempotent — si vous enregistrez deux fois la même conversation, le brouillon existant est mis à jour au lieu de créer un doublon.
+
+### À quoi ressemblent les brouillons sur le tableau
+
+Les brouillons vivent dans le même groupe actif que vos specs À faire — il n'y a pas de colonne séparée. Vous les repérez grâce à :
+
+- Une pastille `Draft` à l'emplacement où se trouve habituellement la pastille de priorité.
+- Une bordure subtilement teintée sur la carte.
+
+Un brouillon a le droit de n'avoir *aucune priorité* — vous définissez la priorité au moment où vous le validez en spec à part entière.
+
+### Reprendre un brouillon
+
+Pour reprendre là où vous vous étiez arrêté :
+
+1. Ouvrez le brouillon depuis le tableau.
+2. Cliquez sur **Continuer l'édition** dans la fenêtre de détail.
+3. La conversation Explore d'origine se rouvre avec tout son historique de chat, et le volet de brouillon vivant pré-rempli avec tout ce que vous aviez déjà façonné.
+4. Continuez à discuter. Quand vous avez terminé, **Créer la spec** promeut le brouillon en spec à part entière (statut **À faire**, avec la priorité que vous choisissez).
+
+### Abandonner un brouillon
+
+Les brouillons ne sont **jamais supprimés automatiquement**. Ils ne disparaissent que lorsque vous les abandonnez explicitement, ou lorsque vous les validez vers un vrai statut. Abandonner un brouillon nettoie aussi la conversation qui lui est liée lorsque plus rien d'autre n'y fait référence.
+
+> Astuce : quand vous n'êtes pas sûr qu'une spec vaille le coup, enregistrez-la comme brouillon et laissez-la reposer. Rouvrez-la le lendemain matin, parcourez la description, et décidez avec un regard neuf.
+
+## Le Contract Layer : de la précision pour le pipeline
+
+Le **Contract Layer** est un enrichissement optionnel qui ajoute un bloc structuré à la description d'une spec. Son rôle est de supprimer les devinettes pour les agents IA qui mettent en œuvre la spec — afin qu'ils réutilisent les bons noms, respectent les formes de données attendues et touchent aux bons fichiers, au lieu d'inventer les leurs.
+
+### Ce qu'il ajoute
+
+Le Contract Layer se compose de cinq courtes sections ajoutées à la spec :
+
+- **Naming Contract** — les identifiants exacts (fonctions, champs, routes) que l'implémentation devrait réutiliser.
+- **Data Shapes** — les payloads façon JSON impliqués.
+- **State Machine** — les transitions ou états que la fonctionnalité traverse.
+- **Invariants** — les propriétés qui doivent toujours rester vraies.
+- **File Touch List** — les fichiers que l'implémentation est censée modifier.
+
+Voyez-le comme remettre au pipeline un plan précis plutôt qu'une esquisse. C'est particulièrement précieux pour les specs qui s'intègrent à du code existant, où l'IA, en devinant un nom ou une forme, causerait du retravail.
+
+### Comment l'ajouter
+
+Le Contract Layer s'applique de trois façons :
+
+- **Mode Quick** — activez l'interrupteur **Enrichir avec le Contract Layer** avant de générer. Votre dernier choix est mémorisé par projet. (Voir [Ajouter une spec — mode Quick](add-spec-quick-mode.md).)
+- **Mode Explore** — choisissez le préréglage de contexte **Max** ou **Desktop** (qui exécutent l'enrichissement automatiquement à la validation), ou ouvrez **Réglages fins** et activez-le à la main. (Voir [Ajouter une spec — mode Explore](add-spec-explore-mode.md).)
+- **Sur une spec existante** — ouvrez la fenêtre de détail de la spec et relancez l'enrichissement depuis là.
+
+### Où il apparaît
+
+Une fois qu'une spec dispose d'un Contract Layer, la fenêtre de détail l'affiche sous forme de bloc dépliable avec un badge du type `3/5 renseignés` — qui vous indique combien des cinq sections ont effectivement été remplies (certaines fonctionnalités n'ont tout simplement pas, par exemple, de state machine, et ces sections sont marquées comme non applicables). Dépliez-le pour lire le contrat complet ; repliez-le pour garder la description épurée.
+
+Si l'enrichissement échoue un jour, l'app affiche une notification avec une action **Réessayer** pour le relancer.
+
+### Est-ce que ça en vaut toujours la peine ?
+
+Pas toujours. Pour une petite spec autonome, l'IA peut très bien la mettre en œuvre sans. Le Contract Layer prouve sa valeur sur les specs qui s'intègrent étroitement à du code existant, là où les noms et les formes exacts comptent — c'est dans ces cas que figer le contrat en amont vous épargne une série de corrections plus tard.
+
+## Pour aller plus loin
+
+- [Ajouter une spec — mode Explore](add-spec-explore-mode.md) — d'où viennent les brouillons.
+- [Ajouter une spec — mode Quick](add-spec-quick-mode.md) — l'interrupteur Contract Layer en mode Quick.
+- [Exécuter les pipelines](running-pipelines.md) — mettez une spec en œuvre une fois qu'elle est prête.

package/docs/guide/it/agents/1-meet-the-agents.md

@@ -0,0 +1,38 @@
+# Conosci gli agenti
+
+Quando avvii un rail di tipo **Implement**, Specrails non affida la tua spec a una singola AI sperando che vada bene. Mette al lavoro una piccola squadra di *agenti* specializzati, ognuno con un compito preciso, in un ordine ben pensato. Questa pagina ti presenta chi fa parte della squadra e di cosa si occupa ciascuno.
+
+## Il trio di base
+
+Ogni esecuzione della pipeline usa questi tre agenti: sono la colonna portante, e un progetto non può avviare un rail senza di loro.
+
+| Agente | Ruolo | Cosa fa |
+|-------|------|--------------|
+| **sr-architect** | Il pianificatore | Legge la tua spec, ispeziona il codice e produce un piano di implementazione concreto: quali file toccare, che forma assume la modifica, a cosa fare attenzione. Pensa prima che qualcuno scriva una riga di codice. |
+| **sr-developer** | Il costruttore | Prende il piano dell'architect e scrive davvero il codice: nuovi file, modifiche, test. È qui che la tua spec si trasforma in un diff reale. |
+| **sr-reviewer** | Il critico | Valida il lavoro del developer rispetto alla spec e al piano, intercetta le regressioni e si oppone quando qualcosa non torna. È il controllo di qualità prima che la modifica sia considerata conclusa. |
+
+Pensalo come **progetta → costruisci → revisiona**, lo stesso ciclo che seguirebbe una squadra umana attenta. Ogni agente passa il proprio risultato al successivo, così il developer non lavora mai alla cieca e il reviewer ha sempre l'intento originale con cui fare il confronto.
+
+## Agenti specialisti
+
+Oltre al trio, un progetto può includere **agenti specialisti** opzionali che si occupano di tipi di lavoro specifici. Il più comune che ti capiterà di vedere è:
+
+- **sr-merge-resolver** — un agente di utilità che aiuta a districare i conflitti di merge e a riconciliare modifiche che si sovrappongono. È opzionale: i profili lo includono solo se lo desideri, e non blocca mai la pipeline quando è assente.
+
+Gli specialisti sono opzionali. Un progetto appena creato gira con il solo trio; aggiungi gli specialisti (e i tuoi **agenti custom** — vedi [Agenti custom e il catalogo](custom-agents-catalog)) quando il flusso di lavoro di un progetto lo richiede.
+
+## Come i task raggiungono l'agente giusto
+
+All'interno di un'esecuzione, il lavoro viene *instradato*. Un task porta con sé dei tag, e le regole di routing di un profilo inviano i task taggati all'agente più adatto a gestirli — con una regola finale "cattura-tutto" che manda tutto il resto al developer. Per l'uso normale non devi preoccupartene: la configurazione predefinita instrada ogni cosa in modo sensato già di default. Quando vorrai indirizzare tipi di lavoro specifici verso agenti specifici, dai un'occhiata a [Personalizzare i modelli per agente](customizing-models-per-agent).
+
+## Un'idea importante, da subito
+
+La *definizione* di ciascun agente — le sue istruzioni, la sua personalità, ciò che gli è consentito fare — è **condivisa**. Queste definizioni vivono come file (`.claude/agents/<id>.md`) che viaggiano insieme al tuo repository, così tutta la tua squadra usa lo stesso architect, lo stesso reviewer.
+
+Ciò che invece è **per progetto** è la *configurazione* che ci sta sopra: con quale modello gira ciascun agente e quale combinazione di agenti scegli per un dato rail. È a questo che servono i profili — ed è proprio l'argomento della prossima pagina.
+
+## Dove andare adesso
+
+- [Profili e il default bilanciato](profiles-and-the-balanced-default) — come la configurazione della squadra viene impacchettata e selezionata.
+- [Personalizzare i modelli per agente](customizing-models-per-agent) — bilancia costo e qualità.