specrails-desktop 2.7.0 → 2.9.0

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

@@ -0,0 +1,45 @@
+# Añadir spec — Modo Quick
+
+El modo Quick es para cuando ya sabes lo que quieres. Escribes tu idea, la IA redacta la spec completa y esta aterriza en tu tablero como **Por hacer**. Sin idas y venidas: solo descríbela y listo.
+
+## Crear una spec en modo Quick
+
+Para crear una spec rápidamente:
+
+1. En el Dashboard, haz clic en **Añadir** (el botón Más de la barra de herramientas del SpecsBoard).
+2. Elige el modo **Quick**.
+3. Escribe tu idea en el campo de texto: una frase o un párrafo, lo que la capture.
+4. Haz clic para generar.
+
+Mientras se redacta la spec, un pequeño aviso en la esquina muestra el nombre del proyecto, un fragmento de tu idea y el **tiempo transcurrido** («Generando… 0:12»). Cuando termina, el aviso cambia a «Generada en <tiempo>» con una acción **Ver** que te lleva directamente a tu nueva spec.
+
+Ese es todo el flujo. Todo lo que viene a continuación son ajustes opcionales.
+
+## Qué puedes ajustar
+
+**Modelo**: por defecto, la IA elige un modelo razonable. Puedes sobrescribirlo por spec desde el selector de modelo si quieres uno más rápido o más capaz.
+
+**Motor**: si tu proyecto tiene instalado más de un proveedor de IA (cualquier combinación de Claude, Codex y Gemini), un selector de motor aparece en la parte superior del diálogo para que elijas cuál genera esta spec. Tu elección se recuerda por proyecto. Los proyectos con un solo proveedor no muestran esto: no hay entre qué elegir.
+
+**Contexto**: el modo Quick normalmente se ejecuta en un solo turno, porque no necesita leer tu código para escribir una spec a partir de tu descripción. Pero un control deslizante de contexto te permite darle más material con el que trabajar:
+
+- En el nivel más bajo solo lee tu descripción.
+- En niveles más altos puede leer tus specs existentes, las specs de OpenSpec de tu proyecto e incluso todo tu código antes de escribir.
+
+Cuanto más contexto le des, más tarda la generación (pasa a varios turnos para poder leer primero), pero la spec vuelve fundamentada en tu proyecto real. Recurre a un contexto más alto cuando la spec necesite referirse a código real, nombres de archivo o comportamiento existente.
+
+**Adjuntos**: arrastra mockups, briefs o archivos de datos al campo de la idea. La IA los lee como parte de la redacción de la spec. (Los adjuntos también hacen que la generación pase a varios turnos.)
+
+**Enriquecer con Contract Layer**: un interruptor que añade un bloque estructurado a la spec generada para que el pipeline posterior no tenga que adivinar nombres ni formas de datos. Es opcional y está desactivado por defecto; tu última elección se recuerda por proyecto. Consulta [Borradores y la Contract Layer](drafts-and-contract-layer.md) para ver qué añade y cuándo merece la pena.
+
+## Cuándo usar el modo Quick frente a Explore
+
+Usa **Quick** cuando la idea ya está clara en tu cabeza: podrías escribir la spec tú mismo, pero prefieres que lo haga la IA. Usa [**Explore**](add-spec-explore-mode.md) cuando todavía le estás dando vueltas y quieres un compañero que te ayude a darle forma.
+
+Una spec creada en modo Quick es una spec totalmente normal: más adelante puedes abrirla y **Seguir editando** en una sesión de Explore si necesita refinarse.
+
+## Adónde ir después
+
+- [Añadir spec — Modo Explore](add-spec-explore-mode.md): para specs que necesitan darse forma.
+- [Borradores y la Contract Layer](drafts-and-contract-layer.md): el enriquecimiento con Contract Layer explicado.
+- [Ejecutar pipelines](running-pipelines.md): arrastra tu nueva spec a un rail e impleméntala.

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

@@ -0,0 +1,68 @@
+# Añadir spec — Modo Explore
+
+El modo Explore es una conversación. En lugar de escribir tú mismo la spec, hablas sobre la idea con la IA: actúa como compañero de reflexión, hace preguntas, propone estructura y construye un **borrador en vivo** de la spec sobre la marcha. Cuando estés a gusto, confirmas el borrador como una spec real.
+
+Recurre a Explore cuando la idea todavía no está del todo formada, cuando hay compromisos que conviene hablar o cuando quieres que la IA mire tu código real antes de fijar la spec.
+
+## Crear una spec en modo Explore
+
+Para dar forma a una spec en modo Explore:
+
+1. En el Dashboard, haz clic en **Añadir** y luego elige **Explore**.
+2. Escribe tu primer mensaje: la idea, una pregunta o un pensamiento a medio formar.
+3. Lee la respuesta de la IA y sigue contestando. En cada turno, refina su comprensión.
+4. Observa cómo se actualiza el **borrador en vivo** junto al chat: esta es la spec tomando forma.
+5. Cuando el borrador tenga buena pinta, haz clic en **Crear spec**.
+
+La conversación queda en tu historial, así que siempre puedes volver para ver cómo se le dio forma a la spec.
+
+## El borrador en vivo
+
+A medida que conversas, un panel de borrador muestra la spec tal como está en cada momento: título, descripción, prioridad, etiquetas y criterios de aceptación. Se reescribe en cada turno en función de lo que habéis comentado. No lo editas directamente; lo guías a través de la conversación («en realidad, pon la prioridad en alta», «añade un criterio sobre el manejo de errores», y así).
+
+Esto es el corazón del modo Explore: nunca estás mirando un formulario en blanco. Siempre tienes delante una spec real y en evolución.
+
+## Cuánto ve la IA: el control deslizante de contexto
+
+Antes de que la IA responda, decides cuánto de tu proyecto puede ver. Un control deslizante de presets de contexto te permite cambiar velocidad por profundidad:
+
+| Preset | Qué ve la IA |
+|--------|--------------|
+| **Mínimo** | Solo tu mensaje. Lo más rápido y barato. |
+| **Ligero** | + tus specs existentes. |
+| **Estándar** | + tus specs y las specs de OpenSpec de tu proyecto. |
+| **Amplio** | + acceso de lectura a todo tu código, para que pueda fundamentar las respuestas en código real. |
+| **Max** | Amplio, más una pasada de enriquecimiento con Contract Layer al confirmar. |
+| **Desktop** | Max, más los servidores MCP de tu proyecto y tus propios servidores MCP aprobados. |
+
+Empieza bajo para una lluvia de ideas rápida; sube cuando quieras que la IA verifique sus sugerencias contra tu código real. La elección se guarda en la conversación, así que no se filtra a otras sesiones de Explore.
+
+Si quieres un control más fino, haz clic en **Ajuste fino** para activar las opciones subyacentes a mano, incluida **Mis MCP aprobados**, que carga los servidores MCP que ya has aprobado en local sin ralentizar la sesión.
+
+## Botones del shell de Explore
+
+- **Crear spec**: promueve el borrador en vivo a una spec real con estado **Por hacer**. (Cuando estás editando una spec existente, este botón pasa a leer **Actualizar spec** y parchea esa spec en su sitio.)
+- **Revisar →**: abre una superposición de revisión que muestra la spec propuesta comparada con la línea base antes de confirmar, para que no haya sorpresas.
+- **Guardar como borrador**: conserva la conversación como un ticket de borrador para que puedas retomarlo más tarde. Disponible en cuanto hayas enviado al menos un mensaje. Ver más abajo.
+- **Minimizar**: aparca la conversación como un chip en el dock de chats minimizados, abajo a la izquierda. Haz clic en el chip en cualquier momento para volver directamente a la conversación: no se pierde nada.
+- **Descartar**: tira la conversación a la basura (pide confirmación primero).
+
+## Guardar como borrador
+
+¿No estás listo para confirmar, pero no quieres perder lo pensado? Haz clic en **Guardar como borrador**. La conversación se convierte en una **spec en borrador** en tu tablero, y el borrador queda vinculado a la conversación que hay detrás.
+
+Más tarde, abre el borrador desde el tablero y haz clic en **Seguir editando**: la conversación original se reabre con su historial de chat intacto y continúas exactamente donde lo dejaste. Los borradores nunca se borran automáticamente; te esperan.
+
+Esto hace que Explore sea seguro para ideas a medio cocer: empieza una conversación, llega a algún sitio, guárdala como borrador y vuelve mañana.
+
+Para todo lo relacionado con los borradores —incluido el enriquecimiento con Contract Layer— consulta [Borradores y la Contract Layer](drafts-and-contract-layer.md).
+
+## Nota sobre múltiples proveedores
+
+Si tu proyecto tiene instalado más de un proveedor de IA, un selector de motor te permite elegir cuál impulsa la conversación de Explore. Los proyectos con un solo proveedor no lo muestran.
+
+## Adónde ir después
+
+- [Borradores y la Contract Layer](drafts-and-contract-layer.md): guardar el trabajo en curso y enriquecer las specs para el pipeline.
+- [Añadir spec — Modo Quick](add-spec-quick-mode.md): cuando la idea ya está clara.
+- [Ejecutar pipelines](running-pipelines.md): implementa tu spec una vez esté lista.

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

@@ -0,0 +1,81 @@
+# Borradores y la Contract Layer
+
+Esta página cubre dos formas de sacarle más partido a tus specs: los **borradores** (guardar una idea en curso para retomarla más tarde) y la **Contract Layer** (un enriquecimiento opcional que hace las specs más precisas para el pipeline de IA).
+
+## Borradores: guardar una idea en curso
+
+Un **borrador** es una conversación de [Explore](add-spec-explore-mode.md) en curso guardada como spec. Te permite parar a mitad de pensamiento sin perder nada y volver cuando estés listo.
+
+### Guardar un borrador
+
+Mientras estás en una conversación de Explore, haz clic en **Guardar como borrador** (disponible en cuanto hayas enviado al menos un mensaje). La app:
+
+- Crea una spec con estado **Borrador** en tu tablero.
+- Le pone un título automáticamente si no estableciste uno (un resumen breve de la conversación).
+- La vincula de vuelta a la conversación, para conservar todo el historial del chat.
+
+Guardar es idempotente: si guardas la misma conversación dos veces, actualiza el borrador existente en lugar de crear un duplicado.
+
+### Cómo se ven los borradores en el tablero
+
+Los borradores viven en el mismo grupo activo que tus specs Por hacer: no hay una columna separada. Los distinguirás por:
+
+- Una píldora `Draft` donde normalmente está la píldora de prioridad.
+- Un borde con un tinte sutil en la tarjeta.
+
+Un borrador puede *no tener prioridad*: la prioridad la defines cuando lo confirmas como una spec real.
+
+### Retomar un borrador
+
+Para continuar donde lo dejaste:
+
+1. Abre el borrador desde el tablero.
+2. Haz clic en **Seguir editando** en el modal de detalle.
+3. La conversación original de Explore se reabre con su historial de chat completo, y el panel del borrador en vivo se rellena con todo lo que habías ido dando forma.
+4. Sigue hablando. Cuando termines, **Crear spec** promueve el borrador a una spec real (estado **Por hacer**, con la prioridad que elijas).
+
+### Descartar un borrador
+
+Los borradores **nunca se borran automáticamente**. Solo desaparecen cuando los descartas explícitamente, o cuando los confirmas en un estado real. Descartar un borrador también limpia su conversación vinculada cuando nada más la referencia.
+
+> Consejo: cuando no tengas claro si una spec merece la pena, guárdala como borrador y déjala reposar. Ábrela a la mañana siguiente, echa un vistazo a la descripción y decide con la mente fresca.
+
+## La Contract Layer: precisión para el pipeline
+
+La **Contract Layer** es un enriquecimiento opcional que añade un bloque estructurado a la descripción de una spec. Su función es eliminar las conjeturas para los agentes de IA que implementan la spec, de modo que reutilicen los nombres correctos, respeten las formas de datos esperadas y toquen los archivos adecuados en lugar de inventar los suyos.
+
+### Qué añade
+
+La Contract Layer consta de cinco secciones breves que se añaden a la spec:
+
+- **Naming Contract**: los identificadores exactos (funciones, campos, rutas) que la implementación debe reutilizar.
+- **Data Shapes**: los payloads tipo JSON involucrados.
+- **State Machine**: las transiciones o estados por los que pasa la funcionalidad.
+- **Invariants**: propiedades que siempre deben cumplirse.
+- **File Touch List**: los archivos que se espera que la implementación edite.
+
+Piénsalo como entregarle al pipeline un plano preciso en lugar de un boceto. Resulta especialmente valioso para specs que se conectan con código existente, donde que la IA adivine un nombre o una forma provocaría retrabajo.
+
+### Cómo añadirla
+
+Hay tres formas de aplicar la Contract Layer:
+
+- **Modo Quick**: activa el interruptor **Enriquecer con Contract Layer** antes de generar. Tu última elección se recuerda por proyecto. (Consulta [Añadir spec — Modo Quick](add-spec-quick-mode.md).)
+- **Modo Explore**: elige el preset de contexto **Max** o **Desktop** (que ejecutan el enriquecimiento automáticamente al confirmar), o abre **Ajuste fino** y actívalo a mano. (Consulta [Añadir spec — Modo Explore](add-spec-explore-mode.md).)
+- **En una spec existente**: abre el modal de detalle de la spec y vuelve a ejecutar el enriquecimiento desde ahí.
+
+### Dónde aparece
+
+Una vez que una spec tiene Contract Layer, el modal de detalle la muestra como un bloque desplegable con una insignia tipo `3/5 populated`, que te indica cuántas de las cinco secciones se han rellenado realmente (algunas funcionalidades simplemente no tienen, por ejemplo, una máquina de estados, y esas secciones se marcan como no aplicables). Despliégalo para leer el contrato completo; pliégalo para mantener la descripción ordenada.
+
+Si el enriquecimiento alguna vez falla al ejecutarse, la app muestra una notificación con una acción **Reintentar** para que puedas volver a lanzarlo.
+
+### ¿Siempre merece la pena?
+
+No siempre. Para una spec pequeña y autocontenida, la IA puede implementarla bien sin ella. La Contract Layer demuestra su valor en specs que se integran estrechamente con código existente, donde los nombres y formas exactos importan: ahí es cuando fijar el contrato por adelantado te ahorra una ronda de correcciones más tarde.
+
+## Adónde ir después
+
+- [Añadir spec — Modo Explore](add-spec-explore-mode.md): de donde salen los borradores.
+- [Añadir spec — Modo Quick](add-spec-quick-mode.md): el interruptor de Contract Layer en el modo Quick.
+- [Ejecutar pipelines](running-pipelines.md): implementa una spec una vez esté lista.

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

@@ -0,0 +1,38 @@
+# Faites connaissance avec les agents
+
+Quand vous lancez un rail **Implement**, Specrails ne confie pas votre spec à une seule IA en croisant les doigts. Il fait tourner une petite équipe d'*agents* spécialisés, chacun avec une mission précise, dans un ordre bien pensé. Cette page vous présente qui compose cette équipe et le rôle de chacun.
+
+## Le trio de base
+
+Chaque exécution du pipeline s'appuie sur ces trois agents — ils en sont la colonne vertébrale, et un projet ne peut pas lancer de rail sans eux.
+
+| Agent | Rôle | Ce qu'il fait |
+|-------|------|--------------|
+| **sr-architect** | Le planificateur | Lit votre spec, inspecte la base de code et produit un plan d'implémentation concret — quels fichiers toucher, quelle forme prend le changement, à quoi faire attention. Il réfléchit avant que quiconque n'écrive du code. |
+| **sr-developer** | Le bâtisseur | Reprend le plan de l'architecte et écrit réellement le code : nouveaux fichiers, modifications, tests. C'est ici que votre spec se transforme en un vrai diff. |
+| **sr-reviewer** | Le critique | Valide le travail du développeur au regard de la spec et du plan, repère les régressions et fait machine arrière quand quelque chose ne va pas. C'est le contrôle qualité avant que le changement soit considéré comme terminé. |
+
+Voyez cela comme une boucle **conception → construction → relecture**, exactement celle qu'une équipe humaine soigneuse suivrait. Chaque agent transmet son résultat au suivant : le développeur ne travaille jamais à l'aveugle, et le relecteur a toujours l'intention de départ pour s'y référer.
+
+## Les agents spécialistes
+
+Au-delà du trio, un projet peut inclure des **agents spécialistes** optionnels qui prennent en charge des types de travail bien précis. Le plus courant que vous croiserez est :
+
+- **sr-merge-resolver** — un agent utilitaire qui aide à démêler les conflits de merge et à concilier les modifications qui se chevauchent. Il est optionnel : les profils ne l'incluent que si vous le souhaitez, et il ne bloque jamais le pipeline en son absence.
+
+Les spécialistes fonctionnent sur la base du volontariat. Un nouveau projet démarre avec le seul trio ; vous ajoutez des spécialistes (et vos propres **agents personnalisés** — voir [Agents personnalisés et le catalogue](custom-agents-catalog)) quand le workflow d'un projet l'exige.
+
+## Comment les tâches atteignent le bon agent
+
+Au sein d'une exécution, le travail est *routé*. Une tâche porte des tags, et les règles de routage d'un profil envoient les tâches taguées vers l'agent le mieux placé pour s'en occuper — avec une règle fourre-tout finale qui dirige tout le reste vers le développeur. Vous n'avez pas à vous en préoccuper pour un usage normal ; la configuration par défaut route tout de manière sensée dès le départ. Quand vous serez prêt à orienter certains types de travail vers certains agents, consultez [Personnaliser les modèles par agent](customizing-models-per-agent).
+
+## Une idée importante, dès le départ
+
+La *définition* de chaque agent — ses instructions, sa personnalité, ce qu'il a le droit de faire — est **partagée**. Elle vit dans des fichiers (`.claude/agents/<id>.md`) qui voyagent avec votre dépôt, si bien que toute votre équipe fait tourner le même architecte, le même relecteur.
+
+Ce qui est **propre à chaque projet**, c'est la *configuration* qui se superpose : quel modèle chaque agent utilise, et quelle combinaison d'agents vous choisissez pour un rail donné. C'est précisément à cela que servent les profils — et c'est l'objet de la page suivante.
+
+## Pour aller plus loin
+
+- [Profils et le défaut équilibré](profiles-and-the-balanced-default) — comment la configuration de l'équipe est empaquetée et sélectionnée.
+- [Personnaliser les modèles par agent](customizing-models-per-agent) — ajustez coût et qualité.

package/docs/guide/fr/agents/2-profiles-and-the-balanced-default.md

@@ -0,0 +1,45 @@
+# Profils et le défaut équilibré
+
+Un **profil** est une recette enregistrée pour une exécution de pipeline. Il répond à trois questions au même endroit :
+
+1. **Quels agents** participent (le trio de base, plus d'éventuels spécialistes ou agents personnalisés).
+2. **Quel modèle** chaque agent utilise.
+3. **Comment les tâches sont routées** vers ces agents.
+
+Vous trouverez les profils dans la section **Agents** de n'importe quel projet (barre latérale droite → **Agents** → onglet **Profils**).
+
+## Le défaut équilibré
+
+Par défaut, un projet se rabat sur un profil **default** sensé. Il inclut le trio de base — `sr-architect`, `sr-developer`, `sr-reviewer` — et route chaque tâche vers le développeur via une unique règle fourre-tout. Les modèles sont équilibrés pour le travail quotidien : un modèle compétent là où ça compte, sans dégainer l'option la plus chère à chaque étape.
+
+Si votre projet avait déjà des modèles d'agents configurés à l'ancienne (dans le frontmatter des fichiers d'agents), le bouton **Migrer** les lit et construit un profil `default` qui reproduit exactement le comportement actuel — aucune perte, rien ne change tant que vous ne décidez pas de l'ajuster.
+
+L'essentiel à retenir : **vous n'avez pas besoin de créer un profil pour utiliser Specrails.** Le défaut fait simplement le travail. Les profils, c'est la manière d'aller plus loin.
+
+## Comment un profil est choisi pour une exécution
+
+Quand vous lancez un rail, Specrails choisit un profil dans cet ordre :
+
+1. **Votre choix explicite** dans l'en-tête du rail (voir ci-dessous).
+2. Votre **préférence par développeur** — un profil que vous avez marqué comme votre défaut personnel pour ce projet (il est local à vous et n'est pas commité).
+3. Le profil **`default`** du projet.
+
+Le profil est *figé en snapshot au lancement*, si bien que chaque rail d'un lot peut faire tourner un profil différent, et modifier un profil plus tard ne réécrit jamais les jobs déjà démarrés.
+
+## Sélectionner un profil par rail
+
+La sélection du profil se fait là où vous lancez — dans l'**en-tête du rail**, via le sélecteur de profil.
+
+- Choisissez un profil dans le menu déroulant pour l'utiliser **pour ce lancement uniquement**.
+- Utilisez l'option de persistance pour faire d'un profil le choix permanent du rail à l'avenir.
+
+Voilà tout le flux : choisir un profil, lancer, terminé. Des rails simultanés dans un même lot peuvent chacun porter leur propre profil, si bien qu'un correctif rapide et une grosse fonctionnalité peuvent tourner côte à côte avec des configurations différentes.
+
+## Quand la section Agents reste silencieuse
+
+Les profils sont une capacité de Claude. Sur un projet qui inclut un provider non-Claude (Codex ou Gemini), la section Agents est masquée et les rails tournent sans profils — c'est le comportement attendu, pas un bug. Les profils exigent aussi un `specrails-core` suffisamment récent dans le projet ; s'il est plus ancien, vous verrez une bannière jaune. Les profils que vous créez sont tout de même **enregistrés** — ils n'affectent simplement pas le pipeline tant que core n'est pas mis à jour. Mettez à jour avec la commande indiquée dans la bannière pour les débloquer.
+
+## Pour aller plus loin
+
+- [Personnaliser les modèles par agent](customizing-models-per-agent) — construisez des profils `fast` et `max`.
+- [Agents personnalisés et le catalogue](custom-agents-catalog) — visualisez et étendez l'équipe.

package/docs/guide/fr/agents/3-customizing-models-per-agent.md

@@ -0,0 +1,60 @@
+# Personnaliser les modèles par agent
+
+La chose la plus utile que les profils vous permettent de faire, c'est de **choisir le bon modèle pour chaque étape**. Une étape de planification mérite peut-être votre modèle le plus puissant ; une étape de construction routinière sera sans doute parfaitement à l'aise avec quelque chose de plus rapide et moins cher. Les profils vous permettent d'exprimer exactement cela.
+
+C'est ici que la distinction partagé / propre au projet porte ses fruits :
+
+- Les *définitions* des agents restent partagées au sein de votre équipe.
+- Le *modèle utilisé par chaque agent* se configure **par projet**, à l'intérieur d'un profil, et n'affecte que votre projet.
+
+Changez un modèle et vous changez le coût et le comportement pour ce projet — sans toucher à la configuration de quiconque ni aux instructions sous-jacentes de l'agent.
+
+## Changer le modèle utilisé par un agent
+
+Dans **Agents → Profils**, sélectionnez un profil et ouvrez son éditeur de chaîne d'agents. Chaque agent de la chaîne dispose d'un champ modèle. Il y a aussi un modèle **orchestrateur** qui assure la coordination de haut niveau du pipeline.
+
+Les valeurs de modèle sont des alias — pour Claude, ce sont `opus`, `sonnet` et `haiku` (du plus capable au plus rapide). Définissez l'alias souhaité par agent :
+
+- Laissez le modèle d'un agent **vide** pour revenir au défaut propre au fichier de l'agent.
+- Définissez-le explicitement pour le surcharger uniquement pour ce profil.
+
+Enregistrez, et le prochain rail lancé avec ce profil utilisera les nouveaux modèles. Les jobs déjà en cours conservent leur snapshot.
+
+## Créer des profils comme `fast` et `max`
+
+Le schéma naturel consiste à avoir deux ou trois profils nommés vers lesquels vous vous tournez selon le travail :
+
+**Un profil `fast`** — pour les petits changements à faible risque où vous voulez de la vitesse et une facture allégée :
+
+- Architecte : un modèle intermédiaire ou rapide — le plan est simple.
+- Développeur : un modèle rapide — le changement est mécanique.
+- Relecteur : gardez-le solide, mais vous pouvez aussi alléger ici.
+
+**Un profil `max`** — pour les fonctionnalités épineuses et à fort enjeu où vous voulez que chaque étape soit la plus pointue possible :
+
+- Architecte, développeur et relecteur : votre modèle le plus puissant sur toute la ligne.
+
+### Deux façons d'en construire un
+
+1. **Dupliquer et ajuster** *(recommandé).* Sélectionnez votre profil `default`, **Dupliquez**-le, donnez à la copie un nom en kebab-case comme `fast` ou `max`, puis ajustez le modèle de chaque agent. Vous héritez d'une chaîne et d'un routage éprouvés et ne changez que ce que vous visez.
+2. **Partir de zéro.** Créez un **profil vierge** et assemblez la chaîne vous-même. Vous devez toujours inclure le trio de base (`sr-architect`, `sr-developer`, `sr-reviewer`) — le pipeline dépend des trois — et exactement une règle de routage fourre-tout terminale, qui doit être en dernier.
+
+Les noms de profils sont en kebab-case minuscule (par ex. `fast`, `max`, `cheap-and-cheerful`).
+
+## Router les tâches vers des agents précis
+
+Les **règles de routage** d'un profil décident quel agent prend en charge une tâche taguée. Chaque règle liste des tags de tâche et un agent cible ; la première règle dont les tags correspondent l'emporte, et une unique règle `default: true` en fin de liste attrape tout le reste. Seuls les agents réellement présents dans la chaîne du profil peuvent être des cibles de routage — l'éditeur l'impose.
+
+Pour un usage quotidien, vous ne toucherez pas au routage : la règle fourre-tout envoie le travail au développeur et c'est très bien ainsi. Recourez aux règles de tags quand vous voulez, par exemple, que le travail tagué `migration` aille vers un spécialiste à la place.
+
+## Choisir le profil au lancement
+
+Tout cela se rejoint au lancement : dans l'en-tête du rail, choisissez `fast`, `max` ou `default` par rail. Un lot peut les mélanger — un minuscule correctif en `fast`, une grosse fonctionnalité en `max`, les deux tournant en même temps. Voir [Profils et le défaut équilibré](profiles-and-the-balanced-default) pour le flux de sélection.
+
+## Un mot sur la sécurité
+
+Supprimer un profil est sans danger pour le travail en cours : les jobs déjà lancés avec lui conservent leur snapshot, et les prochains lancements se rabattent simplement sur l'ordre de résolution. Expérimentez librement.
+
+## Pour aller plus loin
+
+- [Agents personnalisés et le catalogue](custom-agents-catalog) — ajoutez des agents à placer dans vos chaînes.

package/docs/guide/fr/agents/4-custom-agents-catalog.md

@@ -0,0 +1,43 @@
+# Agents personnalisés et le catalogue
+
+Les profils décident *quels agents s'exécutent et avec quels modèles*. Mais d'où viennent les agents eux-mêmes ? C'est tout l'objet du **catalogue d'agents**.
+
+Ouvrez **Agents → Catalogue** dans n'importe quel projet. C'est un visualiseur en lecture seule de tous les agents disponibles pour ce projet, répartis en deux groupes :
+
+- **Agents upstream** — les agents fournis avec `specrails-core` : le trio de base (`sr-architect`, `sr-developer`, `sr-reviewer`) et d'éventuels spécialistes comme `sr-merge-resolver`.
+- **Agents personnalisés** — les agents que vous avez ajoutés vous-même, nommés `custom-*`.
+
+Chaque entrée du catalogue indique à quoi sert l'agent et son modèle par défaut, ce qui vous permet de voir l'effectif complet avant de câbler des agents dans la chaîne d'un profil.
+
+## Ajouter un agent personnalisé
+
+Les agents personnalisés sont de simples fichiers Markdown dans votre dépôt, sous `.claude/agents/`, nommés `custom-<quelque-chose>.md`. Le fichier contient les instructions de l'agent (son system prompt) et un petit en-tête frontmatter qui inclut un `model:` par défaut.
+
+Dès que le fichier existe dans le projet, il apparaît dans le catalogue comme agent personnalisé, et vous pouvez ajouter son id à la chaîne d'agents de n'importe quel profil (et y router des tâches). L'id doit correspondre au nom du fichier — une entrée `custom-docs` correspond à `.claude/agents/custom-docs.md`.
+
+Parce qu'ils vivent dans votre dépôt, les agents personnalisés sont des **ressources d'équipe commitables** : commitez le fichier et toute votre équipe récupère l'agent. Cela reflète l'idée centrale qui traverse toute la section Agents —
+
+> **Les définitions d'agents sont partagées (elles vivent dans le dépôt et voyagent avec `git`). La configuration des modèles est propre au projet (elle vit dans les profils).**
+
+L'espace de noms `custom-*` est réservé et protégé : les commandes `init` et `update` de `specrails-core` ne touchent jamais à `.claude/agents/custom-*.md`, si bien que vos agents personnalisés survivent intacts aux mises à jour de core. (La même protection couvre les fragments contribués par les plugins, comme `custom-serena.md`.)
+
+## Mettre un agent personnalisé au travail
+
+Le flux typique :
+
+1. Rédigez `.claude/agents/custom-<nom>.md` avec des instructions et un modèle par défaut.
+2. Vérifiez qu'il apparaît bien dans **Agents → Catalogue** sous Personnalisés.
+3. Dans **Agents → Profils**, ajoutez l'agent à la chaîne d'un profil (en surchargeant éventuellement son modèle pour ce profil).
+4. Ajoutez une règle de routage pour que les tâches portant les bons tags l'atteignent — ou reposez-vous sur l'ordre de la chaîne.
+5. Lancez un rail avec ce profil depuis l'en-tête du rail.
+
+## Suivre les performances des profils
+
+La section Agents dispose aussi d'un onglet **Utilisation** — une répartition par profil du nombre de jobs lancés sous chaque profil sur une période sélectionnée. C'est un moyen rapide de confirmer que votre répartition `fast`/`max` est réellement utilisée comme vous l'aviez prévu, et de repérer le profil vers lequel votre équipe gravite.
+
+## Récapitulatif de toute la section
+
+- Les **agents** sont les membres spécialisés de l'équipe — le trio partagé, plus les spécialistes et vos agents personnalisés. ([Faites connaissance avec les agents](meet-the-agents))
+- Les **profils** empaquettent quels agents s'exécutent, avec quels modèles, et comment les tâches sont routées — sélectionnés par rail au lancement. Le profil par défaut est le choix équilibré du quotidien. ([Profils et le défaut équilibré](profiles-and-the-balanced-default))
+- Les **modèles** sont ajustés par agent, par projet, à l'intérieur des profils — construisez `fast` et `max` pour coller au travail. ([Personnaliser les modèles par agent](customizing-models-per-agent))
+- **Le catalogue** montre chaque agent, et l'espace de noms `custom-*` vous permet d'agrandir l'équipe — définitions partagées, configuration propre au projet.

package/docs/guide/fr/getting-started/1-what-is-specrails.md

@@ -0,0 +1,49 @@
+# Qu'est-ce que specrails
+
+Bienvenue dans **specrails** — une application de bureau qui transforme un assistant de codage IA en une véritable équipe de développement qui travaille sur *vos* projets, sur *votre* machine.
+
+Au lieu de copier-coller des prompts dans tous les sens, vous décrivez ce que vous voulez sous la forme d'une **spec**, et specrails la fait passer dans un pipeline de développement complet — conception, construction, relecture et livraison de la modification — pendant que vous regardez tout se dérouler en direct.
+
+## Le développement IA piloté par les specs
+
+Le cœur de specrails repose sur une idée simple : **la meilleure façon d'obtenir du bon code d'une IA, c'est de partir d'une spec claire.**
+
+Une *spec*, c'est une description courte et structurée d'un seul morceau de travail — une fonctionnalité, un correctif, un refactoring. Vous pouvez en rédiger une en quelques secondes, ou la façonner au fil d'un chat guidé qui pose les bonnes questions et la rédige pour vous. Chaque spec devient un **ticket** sur le tableau de votre projet, tout comme une tâche dans n'importe quel outil de suivi.
+
+À partir de là, vous confiez la spec au pipeline et vous laissez l'IA faire le gros du travail.
+
+## Le pipeline : Architect → Developer → Reviewer → Ship
+
+Quand vous lancez une spec, specrails la fait passer par quatre étapes, chacune jouée par un agent IA spécialisé :
+
+1. **Architect** — lit votre spec et le code environnant, puis planifie la modification : quels fichiers toucher, quelle forme doit prendre la solution.
+2. **Developer** — écrit le code lui-même, en suivant le plan.
+3. **Reviewer** — vérifie le travail pour la justesse et la qualité, et repère les problèmes avant vous.
+4. **Ship** — finalise la modification pour qu'elle soit prête à être commitée.
+
+Vous voyez chaque étape au moment où elle s'exécute, avec des logs en direct diffusés directement depuis l'IA. Rien n'est caché — si quelque chose dérape, vous verrez exactement où.
+
+## Les projets
+
+Tout dans specrails s'organise autour des **projets**. Un projet est simplement un dossier sur votre ordinateur qui contient une base de code. Vous pouvez ajouter autant de projets que vous le souhaitez et basculer de l'un à l'autre instantanément — chacun conserve ses propres specs, son historique de jobs, ses analytics et ses paramètres.
+
+Specrails ne touche jamais à du code que vous ne lui avez pas demandé de toucher. Il travaille à l'intérieur de votre dépôt existant, et vous gardez le contrôle de ce qui finit par être commité.
+
+## Choisissez votre fournisseur d'IA
+
+Specrails fonctionne avec les principales CLI de codage IA :
+
+- **Claude** (Claude Code)
+- **Codex** (Codex CLI)
+- **Gemini** (Gemini CLI)
+
+Choisissez celui que vous utilisez déjà — ou installez-en plusieurs et choisissez selon la tâche. Un projet peut tourner sur un seul fournisseur ou sur plusieurs à la fois, vous n'êtes donc jamais enfermé.
+
+## Pourquoi vous allez l'adorer
+
+- **De la vitesse sans le chaos** — les specs gardent l'IA concentrée, vous obtenez donc des modifications utiles plutôt que des suppositions tous azimuts.
+- **Une visibilité totale** — des logs en direct, une vue claire du pipeline et des analytics par projet vous montrent exactement ce qui s'est passé et ce que ça a coûté.
+- **Votre machine, votre code** — tout tourne en local sur votre vrai dépôt.
+- **Tout au même endroit** — specs, jobs, chat, un terminal intégré et le suivi des coûts, le tout dans une seule fenêtre.
+
+Prêt à vous lancer ? La suite : [Installation et premier lancement](installing-and-first-run).

package/docs/guide/fr/getting-started/2-installing-and-first-run.md

@@ -0,0 +1,42 @@
+# Installation et premier lancement
+
+Installer specrails sur votre machine ne prend que quelques minutes. Voici le déroulé complet.
+
+## 1. Télécharger et installer
+
+Récupérez l'installateur correspondant à votre plateforme :
+
+- **macOS (Apple Silicon)** — un fichier `.dmg`. Ouvrez-le et glissez **specrails** dans votre dossier Applications.
+- **Windows** — un installateur `.exe`. Lancez-le et suivez les indications.
+
+> **À noter sur les avertissements de sécurité macOS et Windows**
+>
+> - Sous **Windows**, l'installateur n'est pas encore signé, SmartScreen peut donc afficher un avertissement. Cliquez sur **Informations complémentaires → Exécuter quand même** pour continuer.
+> - Sous **macOS**, l'application est signée et notariée, elle devrait donc s'ouvrir sans problème.
+
+## 2. Ce dont vous aurez besoin (prérequis)
+
+Specrails exécute des pipelines de développement IA en pilotant de vrais outils en ligne de commande ; quelques éléments doivent donc être disponibles. La bonne nouvelle : l'application de bureau **intègre la plupart d'entre eux pour vous** (Node.js, npm et Git sont fournis dans l'application), donc sur une machine neuve il n'y a en général rien à installer.
+
+La seule chose que specrails ne peut pas intégrer, c'est la **CLI du fournisseur d'IA** elle-même. Il vous faudra au moins l'une de celles-ci :
+
+- **Claude Code**
+- **Codex CLI**
+- **Gemini CLI**
+
+Installez celle que vous comptez utiliser, connectez-vous une fois depuis votre terminal, et le tour est joué. Specrails détecte automatiquement les fournisseurs présents.
+
+> Si un outil est signalé comme manquant, l'application affiche un lien **Informations complémentaires** avec des commandes d'installation à copier-coller, adaptées à votre système d'exploitation (Homebrew sur macOS, winget sur Windows, apt/dnf sur Linux). Vous pouvez relancer la vérification à tout moment, sans redémarrer.
+
+## 3. Premier lancement — l'écran d'accueil
+
+La première fois que vous ouvrez specrails, vous arrivez sur un **écran d'accueil** épuré. Il n'y a encore aucun projet, l'application vous invite donc à ajouter le premier.
+
+Vous y verrez :
+
+- Une courte description de ce que fait specrails.
+- Un unique bouton **Ajouter votre premier projet**.
+
+C'est tout l'onboarding — aucun compte à créer, aucune inscription. Specrails fonctionne entièrement sur votre machine.
+
+Cliquez sur **Ajouter votre premier projet** et passez à [Ajouter votre premier projet](adding-your-first-project).

package/docs/guide/fr/getting-started/3-adding-your-first-project.md

@@ -0,0 +1,58 @@
+# Ajouter votre premier projet
+
+Un projet, c'est simplement un dossier sur votre ordinateur qui contient une base de code. Connectons-en un.
+
+## Ouvrir la boîte de dialogue Ajouter un projet
+
+Cliquez sur **Ajouter votre premier projet** sur l'écran d'accueil (ou plus tard sur le bouton **Ajouter un projet** dans la barre latérale gauche). Une petite boîte de dialogue apparaît.
+
+## Renseigner les détails
+
+**Dossier du projet** *(requis)*
+
+Indiquez à specrails le dossier qui contient votre code. Dans l'application de bureau, vous pouvez cliquer sur l'icône de dossier pour le parcourir et le sélectionner visuellement, ou bien coller le chemin complet. Il doit s'agir de la racine de votre dépôt — le dossier qui contient votre code et (généralement) un répertoire `.git`.
+
+**Nom du projet** *(facultatif)*
+
+Un libellé convivial affiché dans la barre latérale. Si vous le laissez vide, specrails utilise le nom du dossier.
+
+**Fournisseurs**
+
+Choisissez le ou les fournisseurs d'IA que ce projet doit utiliser. Specrails vous présente ceux qu'il a détectés sur votre machine :
+
+- 🤖 **Claude**
+- ⚡ **Codex**
+- ✨ **Gemini**
+
+Les fournisseurs qu'il n'a pas trouvés sont grisés et marqués *introuvable* — installez-en un et connectez-vous, puis rouvrez la boîte de dialogue. Par défaut, chaque fournisseur disponible est présélectionné, mais vous pouvez tout désélectionner pour ne garder que celui que vous voulez. Si vous en choisissez plusieurs, le **premier** devient le fournisseur par défaut du projet ; vous pourrez choisir selon la tâche plus tard.
+
+> Une vérification rapide tourne en arrière-plan pour confirmer que les outils requis sont présents. S'il manque quelque chose d'essentiel, le bouton **Ajouter** reste désactivé et un lien **Informations complémentaires** vous donne les commandes d'installation exactes.
+
+Cliquez sur **Ajouter** pour continuer.
+
+## Une configuration qui se fait en quelques secondes
+
+Si le dossier est déjà configuré avec specrails, c'est terminé — le projet apparaît instantanément dans votre barre latérale.
+
+S'il s'agit d'un projet vierge, un court **assistant de configuration** se lance. Il comporte trois étapes :
+
+1. **Configurer** — confirmez les bases pour chaque fournisseur que vous avez choisi.
+2. **Installer** — specrails configure le projet automatiquement. C'est l'installation *rapide* : des agents prédéfinis prêts à l'emploi, en place en quelques secondes. Vous verrez un log en direct pendant l'exécution.
+3. **Terminé** — un récapitulatif qui confirme que tout est prêt.
+
+Pour un projet multi-fournisseurs, l'installation s'exécute une fois par fournisseur, l'une après l'autre, et l'étape Terminé affiche une carte pour chacun.
+
+## Ce qui est installé
+
+La configuration est volontairement légère et **non intrusive**. Specrails ajoute une petite quantité de configuration à votre projet pour que le pipeline sache comment s'exécuter :
+
+- Un dossier `.specrails/` qui contient les profils d'agents et les paramètres locaux de votre projet.
+- Des définitions d'agents sous `.claude/agents/` qui alimentent le pipeline Architect → Developer → Reviewer → Ship.
+
+C'est tout — specrails ne réécrit pas votre code source pendant la configuration, et ces fichiers peuvent être commités sans risque si vous souhaitez partager la configuration avec votre équipe.
+
+> **Vous préférez la configuration approfondie ?** L'application propose l'installation rapide par templates à dessein. Si vous préférez le flux enrichi par l'IA (analyse de la base de code et personas d'agents personnalisés), vous pouvez exécuter `npx specrails-core@latest init` depuis le dossier de votre projet dans un terminal.
+
+## Vous y êtes
+
+Une fois la configuration terminée, specrails vous dépose dans le tableau de bord de votre projet. Place à la visite — voir [La visite du tableau de bord](the-dashboard-tour).

package/docs/guide/fr/getting-started/4-the-dashboard-tour.md

@@ -0,0 +1,53 @@
+# La visite du tableau de bord
+
+Un projet ajouté, vous voilà devant votre **tableau de bord de projet** — votre camp de base pour transformer les specs en code livré. Voici comment vous y retrouver.
+
+## La vue d'ensemble
+
+La fenêtre comporte trois zones :
+
+- **Barre latérale gauche** — la liste de vos projets. Cliquez sur n'importe quel projet pour y basculer instantanément ; tout le reste de la fenêtre se met à jour pour correspondre. Le bouton **Ajouter un projet** se trouve ici aussi.
+- **Zone principale** — le tableau de bord du projet actif : vos specs et le pipeline qui les exécute.
+- **Barre latérale droite** — la navigation entre les sections du projet courant.
+
+## Le tableau de bord principal
+
+C'est là que le travail se fait. Le tableau de bord affiche :
+
+- **Vos specs** — les tickets que vous avez créés, organisés par statut (Backlog/À faire jusqu'à Terminé). Vous pouvez les visualiser sous forme de liste, de grille ou de cartes type post-it, selon votre préférence.
+- **Un moyen d'ajouter une spec** — démarrez un nouveau morceau de travail. Vous pouvez rédiger une spec rapide directement, ou ouvrir un chat **Explore** guidé qui vous aide à la façonner par la conversation et rédige le ticket pour vous.
+- **Les rails** — ce sont les couloirs où les specs se construisent. Déposez une spec sur un rail et lancez-la pour la faire passer dans le pipeline Architect → Developer → Reviewer → Ship. Plusieurs rails peuvent tourner en même temps, vous pouvez donc travailler sur plusieurs choses en parallèle.
+
+Quand une spec s'exécute, vous voyez la progression de son pipeline et ses logs en direct — la sortie en temps réel de l'IA pendant qu'elle conçoit, code et relit votre modification.
+
+## La barre latérale droite : les sections du projet
+
+La barre latérale droite est votre tableau d'aiguillage pour le projet courant. Survolez-la pour la déplier, ou épinglez-la ouverte. Les sections que vous y trouverez :
+
+- **Tableau de bord** — le tableau des specs et les rails (là d'où vous venez).
+- **Jobs** — chaque exécution de pipeline pour ce projet, passée et présente, avec son statut, sa durée et la possibilité de plonger dans le détail et les logs de n'importe quelle exécution.
+- **Analytics** — ce que coûte votre usage de l'IA. Les dépenses ventilées par jour, par activité, par modèle et par ticket — pour éviter les mauvaises surprises.
+- **Agents** — les profils d'agents de votre projet : quels agents s'exécutent dans le pipeline et quels modèles d'IA ils utilisent. *(Projets propulsés par Claude uniquement.)*
+- **Code** — un explorateur de fichiers en lecture seule, avec des résumés IA en langage clair et des badges indiquant quels fichiers l'IA a touchés. Idéal pour les non-développeurs qui veulent suivre.
+- **Intégrations** — des extensions facultatives, comme connecter vos specs à un tableau **Jira** ou activer des outils supplémentaires pour l'IA.
+- **Paramètres** — les options par projet (télémétrie, budgets, configuration des fournisseurs, et plus encore).
+
+> Certaines sections n'apparaissent que lorsqu'elles ont du sens pour les fournisseurs que vous avez choisis — par exemple, **Agents** est spécifique à Claude. Si vous ne voyez pas une section, c'est simplement qu'elle ne s'applique pas à la configuration de ce projet.
+
+## La barre de statut
+
+Un fin bandeau court tout en bas de la fenêtre. Discret mais bien pratique :
+
+- **Indicateur de connexion** (à gauche) — un point coloré et un libellé qui montrent que l'application est en ligne : vert pour *connecté*, ambre pendant la *reconnexion*, bleu pendant la *synchronisation* juste après une reconnexion. Vous en aurez rarement besoin, mais c'est rassurant le moment venu.
+- **Dépense totale** (à droite) — un cumul en temps réel de ce que vous avez dépensé, pour que le coût soit toujours à portée de regard.
+- **Bascule du terminal** (tout à droite) — ouvre le panneau de terminal intégré. Appuyez sur **Cmd+J** (macOS) ou **Ctrl+J** (Windows/Linux) pour l'afficher ou le masquer à tout moment. C'est un vrai shell, ouvert directement dans le dossier de votre projet.
+
+## Quelques raccourcis bien pratiques
+
+- **Cmd/Ctrl+B** — épingler ou replier les barres latérales.
+- **Cmd/Ctrl+J** — afficher ou masquer le panneau de terminal.
+- **Cmd/Ctrl+K** — ouvrir la recherche.
+
+## Et maintenant ?
+
+Voilà pour le tour du propriétaire. À partir d'ici, le réflexe naturel est d'**ajouter une spec** et de la lancer sur un rail — regardez le pipeline se dérouler de bout en bout, puis consultez **Analytics** pour voir ce que ça a coûté. Bienvenue à bord.