specrails-desktop 2.16.0 → 2.18.0

package/docs/guide/es/integrations/5-mcp-server.md

@@ -0,0 +1,74 @@
+# Controla Specrails desde cualquier IA (servidor MCP)
+
+Specrails puede exponerse **a sí mismo** a cualquier asistente de IA que hable el [Model Context Protocol](https://modelcontextprotocol.io) — Claude Desktop, Claude Code, Cursor, Cline o tu propio agente. Actívalo, apunta tu asistente a Specrails y podrás manejar toda la app conversando: *"lista mis proyectos", "crea una spec para login social en el proyecto de la API", "lanza el rail 0 y avísame cuando termine", "¿cuánto he gastado esta semana?"*. Tu asistente llama por debajo a las herramientas de Specrails en lugar de que tú andes haciendo clics.
+
+Esta es la dirección opuesta a las funciones de plugins y "Mis MCPs aprobados": esas dejan que Specrails *use* otros servidores MCP; esta deja que otras apps usen **Specrails**.
+
+## Cómo activarlo
+
+Está **desactivado por defecto**. Abre **Configuración ▸ MCP** y activa **Habilitar MCP**. Eso es todo — el servidor arranca de inmediato, sin reiniciar.
+
+Tú mantienes el control de *qué* puede hacer una IA externa mediante un conjunto de niveles de permiso:
+
+| Nivel | Qué permite | Por defecto |
+|---|---|---|
+| **Lectura** | Listar e inspeccionar proyectos, specs, trabajos, analíticas… | Siempre activo (cuando MCP está habilitado) |
+| **Escritura** | Crear y editar specs, cambiar la configuración y la config de los rails | Desactivado — actívalo tú |
+| **Lanzar IA** | Acciones que ejecutan una IA y **cuestan dinero** (lanzar un rail, generar una spec, enviar un turno de chat) | Desactivado — actívalo tú |
+| **Destructivo** | Borrar proyectos/specs/trabajos, detener trabajo en curso | Desactivado — actívalo tú |
+
+Si tu asistente intenta algo que cubre un nivel desactivado, Specrails lo rechaza con un mensaje claro que te indica qué nivel activar. Así puedes empezar en modo solo lectura y abrir exactamente lo que necesites.
+
+## Conectar tu asistente
+
+El panel muestra un bloque de configuración listo para pegar. La vía más sencilla y universal es el **puente** (bridge) incluido (`specrails-mcp`): tu asistente lo ejecuta y este se encarga de retransmitir a Specrails por ti. El puente lee el token de acceso localmente, así que **el token nunca aparece en la configuración de tu asistente**.
+
+En un cliente como Claude Desktop o Cursor, la configuración tiene este aspecto:
+
+```json
+{ "mcpServers": { "specrails": { "command": "specrails-mcp" } } }
+```
+
+Los clientes que admiten servidores MCP remotos por HTTP pueden, en su lugar, apuntar directamente a `http://127.0.0.1:4200/api/mcp` con el token del panel.
+
+Una vez conectado, tu asistente ve unas **18 herramientas** que cubren toda la app — proyectos, specs, rails y trabajos, chat/Explore, agentes, plugins, Jira, loops, el explorador de código, analíticas, configuración — más una herramienta de **guía** incorporada que lee primero para entender cómo funciona Specrails sin que tú tengas que explicar nada.
+
+## Qué puedes hacer con él
+
+Unas cuantas recetas una vez que tu asistente está conectado. Empieza con **Lectura** activado y, cuando quieras que de verdad cree y lance trabajo, activa **Escritura** y **Lanzar IA**.
+
+**Convierte en specs el trabajo de tus otras herramientas.** Si tu asistente también tiene conectados GitHub, Jira, Gmail o Slack, puede traerte el trabajo a Specrails:
+> *"Coge las incidencias abiertas de GitHub de esta semana con la etiqueta 'bug', crea una spec para cada una en el proyecto de la API y lánzalas."*
+>
+> *"Lee mis últimos correos de feedback de clientes, agrúpalos por tema y crea una spec por tema."*
+
+**Piloto automático nocturno.** Déjalo en marcha con la app en la bandeja y vuelve a un informe:
+> *"Aquí tienes 12 ideas. Convierte cada una en una spec, lánzalas de tres en tres por los rails, vigila cada trabajo y mañana dame un resumen de lo que terminó, lo que falló y lo que costó."*
+
+Mantén **Destructivo** desactivado y podrá trabajar toda la noche sin borrar nada nunca.
+
+**En todos tus proyectos.** Algo que el panel no hace por sí solo:
+> *"Revisa todos mis proyectos. Dime cuáles tienen specs en el backlog y ningún rail en marcha, y arranca el de mayor prioridad en cada uno."*
+
+**Sin manos mientras programas.** Maneja Specrails desde tu editor o por voz, sin cambiar de ventana:
+> *"Lanza el rail 0 en modo ultracode con Opus para el ticket #42 y avísame cuando termine."*
+
+**Pregunta por el coste y el historial.** Tus analíticas, en lenguaje natural:
+> *"¿Dónde he gastado más en IA esta semana, por proyecto y por modelo? Enséñame los cinco tickets más caros."*
+
+**Tu standup diario.**
+> *"Escribe mi standup: qué rails se ejecutaron ayer, qué se completó, qué falló y el coste total — en viñetas listas para pegar en Slack."*
+
+**Entiende el código.** Sin necesidad de editor:
+> *"¿Qué archivos tocó el ticket #38? Resume en una línea qué cambió en cada uno."*
+
+Como tu asistente lee primero la guía incorporada, rara vez necesitas nombrar herramientas ni specs — describe el resultado que quieres y él se encarga de las llamadas.
+
+## Algunas cosas que conviene saber
+
+- **Specrails tiene que estar en ejecución.** El servidor MCP vive dentro de la app, así que tu asistente solo puede alcanzarlo mientras Specrails esté abierto. Gracias al icono de la bandeja, cerrar la ventana lo mantiene en ejecución en segundo plano — solo **Salir** desde la bandeja (barra de menú de Mac / bandeja del sistema de Windows) lo detiene de verdad.
+- **Las acciones largas se transmiten.** Lanzar un rail o generar una spec devuelve el control de inmediato y termina en segundo plano; tu asistente puede "vigilarlo" e informarte cuando se resuelva.
+- **Seguridad.** El MCP usa su propio token de acceso, separado de todo lo demás, y solo escucha en tu propia máquina (loopback). Puedes copiar o regenerar ese token en cualquier momento desde el panel.
+- **No expuesto (v1).** Por seguridad, unas pocas capacidades de alto riesgo se dejan fuera a propósito: ejecutar comandos de shell en la terminal, el navegador integrado, la edición de archivos dentro de la app y la instalación de prerrequisitos del sistema. Todo lo que *gestiona* Specrails está disponible; el acceso directo a la máquina, no.
+
+Puedes desactivar MCP en cualquier momento desde el mismo panel — tu asistente simplemente pierde el acceso y nada más cambia.

package/docs/guide/es/integrations/6-agent-chat.md

@@ -0,0 +1,64 @@
+# Maneja Specrails conversando (Agent Chat)
+
+El **Agent Chat** es un copiloto que vive *dentro* de Specrails y puede manejar toda la app por ti. En lugar de ir haciendo clic por proyectos, specs, raíles y analítica, basta con que preguntes: *«¿cuántos trabajos salieron bien esta semana?»*, *«crea una spec para el inicio de sesión social en el proyecto de la API»*, *«lanza los tres tickets de mayor prioridad y avísame cuando terminen»*. Lleva a cabo el trabajo llamando a las propias herramientas de Specrails —las mismas que expone el [servidor MCP](./5-mcp-server.md)— mientras ves el panel actualizarse en directo detrás de él.
+
+> **No lo confundas con los agentes del pipeline.** La sección *Agentes* (Architect → Developer → Reviewer) trata de *cómo un raíl implementa una spec*. El **Agent Chat** es un único asistente que *maneja la propia app*. Cosas distintas, misma palabra.
+
+## Cómo abrirlo
+
+Hay una **burbuja** flotante en la parte inferior de la ventana: haz clic en ella para abrir el panel, o pulsa **⌘⇧A** (**Ctrl+Shift+A** en Windows/Linux) desde cualquier sitio. El panel es una ventana de verdad que puedes mover, redimensionar, maximizar y devolver a la burbuja; recuerda dónde lo dejaste.
+
+Es **no modal a propósito**: el panel de detrás sigue vivo, así que cuando el agente lanza un raíl o crea una spec lo ves aparecer en tiempo real; no estás mirando una pantalla congelada.
+
+## Requisito previo: el servidor MCP
+
+El Agent Chat maneja la app a través del **servidor MCP de Specrails** integrado, así que tiene que estar activo. Si no lo está, el panel se abre con un banner de **Activar Specrails MCP** de un solo clic: púlsalo y ya está listo (sin reiniciar). Consulta [Controla Specrails desde cualquier IA](./5-mcp-server.md) para los detalles; no se instala nada, todo es local en tu máquina.
+
+## Elegir sobre qué trabaja
+
+La cabecera tiene un **selector de proyecto** (como el de Cursor). Elige un proyecto y todo lo que pidas queda acotado a él: *«lanza los de alta prioridad»* se resuelve contra ese proyecto. Déjalo en **Inicio** y el agente trabaja sobre todo tu conjunto: puede listar o crear proyectos y responder preguntas que abarquen todo. Si pides algo específico de un proyecto estando en Inicio, te preguntará cuál (o se ofrecerá a crear uno) en lugar de adivinar.
+
+Elegir un proyecto aquí **no** mueve tu panel: el objetivo del agente y lo que estás mirando son independientes.
+
+## Proveedor y modelo
+
+Justo encima del cuadro de mensaje eliges el **proveedor** (Claude, Codex o Gemini) y su **modelo**. Cada proveedor tiene su propia lista de modelos, y cambiar de proveedor inicia una sesión nueva con el modelo por defecto de ese proveedor, así que puedes, por ejemplo, manejar la app con Claude y pasar a Codex para otra conversación sin que se mezcle nada.
+
+## Niveles de permiso: tú llevas las riendas
+
+El agente puede tocar toda la app, así que tú decides cuánta libertad tiene con un **nivel** que cambias en vivo pulsando **Shift+Tab** (el mismo ciclo que usa Claude Code). Cada nivel incluye todo lo que hay por debajo:
+
+| Nivel | Qué puede hacer |
+|---|---|
+| 👀 **Observa** | Solo lectura: listar e inspeccionar proyectos, specs, trabajos, analítica. No cambia nada. |
+| ✍️ **Edita** | Lo anterior **+** crear y editar (specs, ajustes, configuración de raíles): cambios reversibles. |
+| ⚡ **Opera** | Lo anterior **+** lanzar trabajo de IA que **cuesta dinero** (raíles, generación de specs). |
+| 🔥 **Autónomo** | Lo anterior **+** borrar y detener cosas: acciones irreversibles. |
+
+Empieza en **Observa** y sube el nivel solo cuando quieras que el agente actúe. Si intenta algo por encima del nivel actual, se detiene y te dice exactamente qué nivel activar; nunca sortea el límite. Esto es independiente de los niveles de Ajustes ▸ MCP, que rigen a los asistentes *externos*; el nivel de aquí es solo para este agente interno de la app.
+
+## Algunas cosas que puedes pedir
+
+Cuando estés en **Opera**, prueba con:
+
+> *«Lista todas las specs pendientes del proyecto de la API y luego lanza las tres de mayor prioridad en raíles separados y vigílalas.»*
+>
+> *«¿Cuánto he gastado esta semana, desglosado por proyecto?»*
+>
+> *«Crea una spec para un interruptor de modo oscuro en el proyecto web, con Contract Layer.»*
+>
+> *«Algo ha fallado en el último lote: encuentra los trabajos fallidos y resume por qué.»*
+
+Las respuestas llegan fluidas y ya formateadas (encabezados, tablas, listas), cada una con un pequeño botón de **copiar**. Una etiqueta de estado abajo muestra lo que el agente está haciendo ahora mismo —*Pensando…*, *MCP · jobs*, *Terminal*— para que siempre sepas en qué estado está.
+
+## Detalles prácticos
+
+- **Historial de prompts.** Con el cuadro vacío, pulsa **↑**/**↓** para recorrer lo que preguntaste antes (se muestra atenuado mientras te desplazas); empieza a escribir para editarlo, o pulsa Intro para enviarlo.
+- **Minimiza sin perder nada.** Haz clic en la ✕ para devolver el panel a la burbuja: la conversación sigue en marcha. Vuelve a abrirlo y aterrizas en el último mensaje; no hay que reescribir nada.
+- **Nueva conversación.** El botón **+** inicia un hilo limpio; el historial vive a nivel de app, por encima de cualquier proyecto concreto.
+
+## Algunas cosas que conviene saber
+
+- **Opera y Autónomo cuestan dinero** porque ejecutan IA. El agente saca a la luz las acciones que generan coste antes de hacerlas; mantén el nivel en Observa o Edita si solo quieres mirar y ordenar.
+- **El agente es de toda la app**, no está ligado al proyecto que tengas abierto; por eso tiene su propio selector y su historial no es por proyecto.
+- **Es tan capaz como le permita el MCP.** Si toda un área parece vetada, comprueba que el servidor MCP esté activado.

package/docs/guide/fr/integrations/5-mcp-server.md

@@ -0,0 +1,74 @@
+# Piloter Specrails depuis n'importe quelle IA (serveur MCP)
+
+Specrails peut s'exposer **lui-même** à n'importe quel assistant IA qui parle le [Model Context Protocol](https://modelcontextprotocol.io) — Claude Desktop, Claude Code, Cursor, Cline, ou votre propre agent. Activez-le, pointez votre assistant vers Specrails, et vous pouvez piloter toute l'app en discutant : *« liste mes projets », « crée une spec pour la connexion sociale dans le projet API », « lance le rail 0 et préviens-moi quand c'est terminé », « combien ai-je dépensé cette semaine ? »*. Votre assistant appelle les outils de Specrails en coulisses, plutôt que de vous faire cliquer partout.
+
+C'est la direction inverse des fonctionnalités plugins et « Mes MCP approuvés » : celles-ci permettent à Specrails d'*utiliser* d'autres serveurs MCP ; ceci permet à d'autres apps d'utiliser **Specrails**.
+
+## L'activer
+
+C'est **désactivé par défaut**. Ouvrez **Paramètres ▸ MCP** et basculez **Activer MCP**. C'est tout — le serveur démarre immédiatement, sans redémarrage.
+
+Vous gardez le contrôle de *ce qu'*une IA externe peut faire grâce à un ensemble de niveaux de permission :
+
+| Niveau | Ce qu'il autorise | Par défaut |
+|---|---|---|
+| **Lecture** | Lister et inspecter les projets, specs, jobs, analyses… | Toujours actif (lorsque MCP est activé) |
+| **Écriture** | Créer et modifier des specs, changer les paramètres et la configuration des rails | Désactivé — à activer |
+| **Lancement d'IA** | Actions qui exécutent une IA et **coûtent de l'argent** (lancer un rail, générer une spec, envoyer un tour de chat) | Désactivé — à activer |
+| **Destructif** | Supprimer des projets/specs/jobs, arrêter un travail en cours | Désactivé — à activer |
+
+Si votre assistant tente quelque chose que couvre un niveau désactivé, Specrails refuse avec un message clair vous indiquant quel niveau activer. Vous pouvez donc commencer en lecture seule et ouvrir exactement ce dont vous avez besoin.
+
+## Connecter votre assistant
+
+Le panneau affiche un bloc de configuration prêt à coller. La voie la plus simple et universelle est le **pont** (« bridge ») embarqué (`specrails-mcp`) : votre assistant l'exécute, et il relaie vers Specrails pour vous. Le pont lit le jeton d'accès localement, donc **le jeton n'apparaît jamais dans la configuration de votre assistant**.
+
+Dans un client comme Claude Desktop ou Cursor, la configuration ressemble à ceci :
+
+```json
+{ "mcpServers": { "specrails": { "command": "specrails-mcp" } } }
+```
+
+Les clients qui prennent en charge les serveurs MCP HTTP distants peuvent à la place pointer directement vers `http://127.0.0.1:4200/api/mcp` avec le jeton du panneau.
+
+Une fois connecté, votre assistant voit environ **18 outils** couvrant toute l'app — projets, specs, rails et jobs, chat/Explore, agents, plugins, Jira, loops, l'explorateur de code, les analyses, les paramètres — plus un outil **guide** intégré qu'il lit en premier afin de comprendre le fonctionnement de Specrails sans que vous ayez à expliquer quoi que ce soit.
+
+## Ce que vous pouvez en faire
+
+Quelques recettes une fois votre assistant connecté. Commencez avec **Lecture** activée, puis activez **Écriture** et **Lancement d'IA** quand vous voulez qu'il crée et lance réellement du travail.
+
+**Transformez le travail de vos autres outils en specs.** Si votre assistant a aussi GitHub, Jira, Gmail ou Slack connectés, il peut amener le travail jusqu'à Specrails pour vous :
+> *« Prends les issues GitHub ouvertes cette semaine étiquetées "bug", crée une spec pour chacune dans le projet API, et lance-les. »*
+>
+> *« Lis mes derniers e-mails de retours clients, regroupe-les par thème, et crée une spec par thème. »*
+
+**Pilote automatique nocturne.** Laissez-le tourner avec l'app dans la zone de notification et revenez à un rapport :
+> *« Voici 12 idées. Transforme chacune en une spec, lance-les trois par trois à travers les rails, surveille chaque job, et demain donne-moi un résumé de ce qui s'est terminé, ce qui a échoué et ce que ça a coûté. »*
+
+Gardez **Destructif** désactivé et il peut construire toute la nuit sans jamais rien supprimer.
+
+**À travers tous vos projets.** Quelque chose que le tableau de bord ne fait pas tout seul :
+> *« Vérifie tous mes projets. Dis-moi lesquels ont des specs dans le backlog sans aucun rail en cours, et démarre la plus prioritaire dans chacun. »*
+
+**Sans les mains pendant que vous codez.** Pilotez Specrails depuis votre éditeur ou à la voix, sans changer de fenêtre :
+> *« Lance le rail 0 en mode ultracode avec Opus pour le ticket #42 et préviens-moi quand c'est terminé. »*
+
+**Interrogez les coûts et l'historique.** Vos analyses, en langage clair :
+> *« Où ai-je le plus dépensé en IA cette semaine, par projet et par modèle ? Montre-moi les cinq tickets les plus coûteux. »*
+
+**Votre point quotidien.**
+> *« Rédige mon point quotidien : quels rails ont tourné hier, ce qui s'est terminé, ce qui a échoué, le coût total — sous forme de puces prêtes à coller dans Slack. »*
+
+**Comprenez le code.** Aucun éditeur nécessaire :
+> *« Quels fichiers le ticket #38 a-t-il touchés ? Résume en une ligne ce qui a changé dans chacun. »*
+
+Parce que votre assistant lit d'abord le guide intégré, vous avez rarement besoin de nommer des outils ou des specs — décrivez le résultat voulu et il trouve les appels à faire.
+
+## Quelques points à connaître
+
+- **Specrails doit être en cours d'exécution.** Le serveur MCP vit à l'intérieur de l'app, donc votre assistant ne peut l'atteindre que tant que Specrails est ouvert. Grâce à la zone de notification, fermer la fenêtre laisse l'app tourner en arrière-plan — seul **Quitter** depuis la zone de notification (barre de menus Mac / zone de notification Windows) l'arrête réellement.
+- **Les actions longues sont diffusées en flux.** Lancer un rail ou générer une spec renvoie une réponse immédiate et se termine en arrière-plan ; votre assistant peut le « surveiller » et vous faire un retour une fois l'action stabilisée.
+- **Sécurité.** Le MCP utilise son propre jeton d'accès, distinct de tout le reste, et n'écoute que sur votre propre machine (boucle locale). Vous pouvez copier ou régénérer ce jeton à tout moment depuis le panneau.
+- **Non exposé (v1).** Par sécurité, quelques capacités à haut risque sont volontairement laissées de côté : exécuter des commandes shell dans le terminal, le navigateur embarqué, l'édition de fichiers dans l'app, et l'installation des prérequis système. Tout ce qui *gère* Specrails est disponible ; l'accès brut à la machine ne l'est pas.
+
+Vous pouvez désactiver MCP à tout moment depuis le même panneau — votre assistant perd simplement l'accès, et rien d'autre ne change.

package/docs/guide/fr/integrations/6-agent-chat.md

@@ -0,0 +1,64 @@
+# Pilotez Specrails en discutant (Agent Chat)
+
+L'**Agent Chat** est un copilote qui vit *à l'intérieur* de Specrails et peut piloter toute l'application à votre place. Au lieu de cliquer à travers projets, specs, rails et analyses, il vous suffit de demander : *« combien de jobs ont réussi cette semaine ? »*, *« crée une spec pour la connexion sociale dans le projet API »*, *« lance les trois tickets les plus prioritaires et préviens-moi quand ils sont finis »*. Il exécute le travail en appelant les propres outils de Specrails — les mêmes que ceux exposés par le [serveur MCP](./5-mcp-server.md) — pendant que vous voyez le tableau de bord se mettre à jour en direct derrière lui.
+
+> **À ne pas confondre avec les agents du pipeline.** La section *Agents* (Architect → Developer → Reviewer) concerne *la manière dont un rail implémente une spec*. L'**Agent Chat** est un unique assistant qui *pilote l'application elle-même*. Deux choses différentes, un même mot.
+
+## Comment l'ouvrir
+
+Une **bulle** flottante se trouve en bas de la fenêtre : cliquez dessus pour ouvrir le panneau, ou appuyez sur **⌘⇧A** (**Ctrl+Shift+A** sous Windows/Linux) depuis n'importe où. Le panneau est une vraie fenêtre que vous pouvez déplacer, redimensionner, agrandir et renvoyer dans la bulle ; il se souvient de l'endroit où vous l'avez laissé.
+
+Il est **non modal, volontairement** : le tableau de bord derrière lui reste vivant, donc quand l'agent lance un rail ou crée une spec vous le voyez apparaître en temps réel — vous ne regardez pas un écran figé.
+
+## Prérequis : le serveur MCP
+
+L'Agent Chat pilote l'application via le **serveur MCP Specrails** intégré, il faut donc que celui-ci soit actif. S'il ne l'est pas, le panneau s'ouvre avec une bannière **Activer Specrails MCP** en un clic : appuyez dessus et c'est prêt (sans redémarrage). Voir [Contrôlez Specrails depuis n'importe quelle IA](./5-mcp-server.md) pour les détails ; rien n'est installé, tout est local sur votre machine.
+
+## Choisir ce sur quoi il travaille
+
+L'en-tête comporte un **sélecteur de projet** (comme celui de Cursor). Choisissez un projet et tout ce que vous demandez s'y rapporte : *« lance ceux qui sont hautement prioritaires »* se résout pour ce projet. Laissez-le sur **Accueil** et l'agent travaille sur l'ensemble de votre configuration : il peut lister ou créer des projets et répondre à des questions qui embrassent tout. Si vous demandez quelque chose de spécifique à un projet en étant sur Accueil, il vous demandera lequel (ou proposera d'en créer un) plutôt que de deviner.
+
+Choisir un projet ici **ne déplace pas** votre tableau de bord : la cible de l'agent et ce que vous regardez sont indépendants.
+
+## Fournisseur et modèle
+
+Juste au-dessus de la zone de message, vous choisissez le **fournisseur** (Claude, Codex ou Gemini) et son **modèle**. Chaque fournisseur a sa propre liste de modèles, et changer de fournisseur démarre une nouvelle session avec le modèle par défaut de ce fournisseur — vous pouvez ainsi, par exemple, piloter l'application avec Claude et passer à Codex pour une autre conversation sans que rien ne se mélange.
+
+## Niveaux d'autorisation — c'est vous qui tenez la laisse
+
+L'agent peut toucher à toute l'application, c'est donc à vous de décider quelle liberté vous lui accordez, via un **niveau** que vous changez en direct en appuyant sur **Shift+Tab** (le même cycle que celui de Claude Code). Chaque niveau inclut tout ce qui se trouve en dessous :
+
+| Niveau | Ce qu'il peut faire |
+|---|---|
+| 👀 **Observer** | Lecture seule — lister et inspecter projets, specs, jobs, analyses. Rien ne change. |
+| ✍️ **Modifier** | Ce qui précède **+** créer et modifier (specs, réglages, configuration de rails) — changements réversibles. |
+| ⚡ **Opérer** | Ce qui précède **+** lancer du travail d'IA qui **coûte de l'argent** (rails, génération de specs). |
+| 🔥 **Autonome** | Ce qui précède **+** supprimer et arrêter des choses — actions irréversibles. |
+
+Commencez sur **Observer** et n'élevez le niveau que lorsque vous voulez que l'agent agisse. S'il tente quelque chose au-dessus du niveau actuel, il s'arrête et vous indique exactement quel niveau activer — il ne contourne jamais la limite. C'est distinct des niveaux de Réglages ▸ MCP, qui régissent les assistants *externes* ; le niveau ici ne concerne que cet agent intégré à l'application.
+
+## Quelques exemples de demandes
+
+Une fois sur **Opérer**, essayez :
+
+> *« Liste toutes les specs à faire du projet API, puis lance les trois plus prioritaires sur des rails séparés et surveille-les. »*
+>
+> *« Combien ai-je dépensé cette semaine, ventilé par projet ? »*
+>
+> *« Crée une spec pour un bouton de bascule mode sombre dans le projet web, avec une Contract Layer. »*
+>
+> *« Quelque chose a échoué dans le dernier lot — trouve les jobs en échec et résume pourquoi. »*
+
+Les réponses arrivent en flux fluide et s'affichent déjà mises en forme (titres, tableaux, listes), chacune avec un petit bouton **copier**. Une étiquette d'état en bas montre ce que fait l'agent en ce moment — *Réflexion…*, *MCP · jobs*, *Terminal* — pour que vous connaissiez toujours son état.
+
+## Petits plus pratiques
+
+- **Historique des prompts.** Avec la zone vide, appuyez sur **↑**/**↓** pour parcourir ce que vous avez demandé auparavant (affiché en grisé pendant que vous défilez) ; commencez à taper pour le modifier, ou appuyez sur Entrée pour l'envoyer.
+- **Réduire sans rien perdre.** Cliquez sur la ✕ pour renvoyer le panneau dans la bulle — la conversation continue de tourner. Rouvrez-le et vous atterrissez sur le dernier message ; rien n'est à retaper.
+- **Nouvelle conversation.** Le bouton **+** démarre un fil vierge ; l'historique vit au niveau de l'application, au-dessus de tout projet individuel.
+
+## Quelques points à savoir
+
+- **Opérer et Autonome coûtent de l'argent** car ils exécutent de l'IA. L'agent met en avant les actions génératrices de coût avant de les réaliser ; gardez le niveau sur Observer ou Modifier si vous voulez juste regarder et ranger.
+- **L'agent couvre toute l'application**, il n'est pas lié au projet que vous avez ouvert — c'est pourquoi il a son propre sélecteur et que son historique n'est pas par projet.
+- **Il n'est capable que dans la mesure où le MCP le permet.** Si tout un domaine semble interdit, vérifiez que le serveur MCP est bien activé.

package/docs/guide/it/integrations/5-mcp-server.md

@@ -0,0 +1,74 @@
+# Controlla Specrails da qualsiasi AI (server MCP)
+
+Specrails può esporre **se stesso** a qualsiasi assistente AI che parli il [Model Context Protocol](https://modelcontextprotocol.io) — Claude Desktop, Claude Code, Cursor, Cline o un tuo agente. Attivalo, punta il tuo assistente verso Specrails e potrai pilotare l'intera app chiacchierando: *"elenca i miei progetti", "crea una spec per il login social nel progetto API", "lancia il rail 0 e dimmi quando ha finito", "quanto ho speso questa settimana?"*. Il tuo assistente richiama gli strumenti di Specrails dietro le quinte, al posto tuo che clicchi qua e là.
+
+Questa è la direzione opposta rispetto alle funzionalità dei plugin e degli "MCP approvati da me": quelle permettono a Specrails di *usare* altri server MCP; questa permette ad altre app di usare **Specrails**.
+
+## Come attivarlo
+
+È **disattivato di default**. Apri **Impostazioni ▸ MCP** e attiva **Abilita MCP**. Fatto — il server si avvia immediatamente, senza riavvii.
+
+Resti tu a controllare *cosa* può fare un'AI esterna tramite una serie di livelli di permesso:
+
+| Livello | Cosa consente | Default |
+|---|---|---|
+| **Lettura** | Elencare e ispezionare progetti, spec, job, analisi… | Sempre attivo (quando l'MCP è abilitato) |
+| **Scrittura** | Creare e modificare spec, cambiare impostazioni e configurazione dei rail | Disattivato — da abilitare |
+| **AI-spawn** | Azioni che eseguono un'AI e **costano denaro** (lanciare un rail, generare una spec, inviare un turno di chat) | Disattivato — da abilitare |
+| **Distruttivo** | Eliminare progetti/spec/job, fermare il lavoro in corso | Disattivato — da abilitare |
+
+Se il tuo assistente prova a fare qualcosa coperto da un livello disattivato, Specrails rifiuta con un messaggio chiaro che ti indica quale livello attivare. Così puoi partire in sola lettura e aprire esattamente ciò che ti serve.
+
+## Collegare il tuo assistente
+
+Il pannello mostra un blocco di configurazione pronto da incollare. Il percorso più semplice e universale è il **bridge** incluso (`specrails-mcp`): il tuo assistente lo esegue e quello fa da tramite verso Specrails per te. Il bridge legge il token di accesso in locale, quindi **il token non compare mai nella configurazione del tuo assistente**.
+
+In un client come Claude Desktop o Cursor, la configurazione si presenta così:
+
+```json
+{ "mcpServers": { "specrails": { "command": "specrails-mcp" } } }
+```
+
+I client che supportano i server MCP HTTP remoti possono invece puntare direttamente a `http://127.0.0.1:4200/api/mcp` con il token preso dal pannello.
+
+Una volta collegato, il tuo assistente vede circa **18 strumenti** che coprono l'intera app — progetti, spec, rail e job, chat/Explore, agenti, plugin, Jira, loop, l'esploratore del codice, le analisi, le impostazioni — più uno strumento **guida** integrato che legge per primo, così capisce come funziona Specrails senza che tu debba spiegargli nulla.
+
+## Cosa puoi farci
+
+Qualche ricetta una volta collegato il tuo assistente. Parti con la **Lettura** attiva, poi accendi **Scrittura** e **AI-spawn** quando vuoi che crei e lanci davvero il lavoro.
+
+**Trasforma il lavoro degli altri tuoi strumenti in spec.** Se il tuo assistente ha collegati anche GitHub, Jira, Gmail o Slack, può portare il lavoro dentro Specrails al posto tuo:
+> *"Prendi le issue GitHub aperte di questa settimana con etichetta 'bug', crea una spec per ognuna nel progetto API e lanciale."*
+>
+> *"Leggi le ultime email di feedback dei clienti, raggruppale per tema e crea una spec per ogni tema."*
+
+**Pilota automatico notturno.** Lascialo in esecuzione con l'app nella barra di sistema e torna a un resoconto:
+> *"Ecco 12 idee. Trasforma ognuna in una spec, lanciale tre alla volta sui rail, tieni d'occhio ogni job e domani dammi un riepilogo di cosa è finito, cosa è fallito e quanto è costato."*
+
+Tieni **Distruttivo** disattivato e potrà lavorare tutta la notte senza mai eliminare nulla.
+
+**Su tutti i tuoi progetti.** Qualcosa che la dashboard da sola non fa:
+> *"Controlla tutti i miei progetti. Dimmi quali hanno spec nel backlog e nessun rail in esecuzione, e avvia in ognuno quella a priorità più alta."*
+
+**Senza mani mentre programmi.** Pilota Specrails dal tuo editor o a voce, senza cambiare finestra:
+> *"Lancia il rail 0 in modalità ultracode con Opus per il ticket #42 e dimmi quando ha finito."*
+
+**Chiedi di costi e cronologia.** Le tue analisi, in linguaggio naturale:
+> *"Dove ho speso di più in AI questa settimana, per progetto e per modello? Mostrami i cinque ticket più costosi."*
+
+**Il tuo standup quotidiano.**
+> *"Scrivi il mio standup: quali rail hanno girato ieri, cosa è stato completato, cosa è fallito, costo totale — come elenco puntato pronto da incollare in Slack."*
+
+**Capire il codice.** Senza bisogno di un editor:
+> *"Quali file ha toccato il ticket #38? Riassumi in una riga cosa è cambiato in ognuno."*
+
+Dato che il tuo assistente legge per prima la guida integrata, raramente devi nominare strumenti o spec — descrivi il risultato e lui calcola le chiamate da fare.
+
+## Qualche cosa da sapere
+
+- **Specrails deve essere in esecuzione.** Il server MCP vive dentro l'app, quindi il tuo assistente può raggiungerlo solo finché Specrails è aperto. Grazie all'icona nella barra di sistema, chiudere la finestra lo mantiene attivo in background — solo **Esci** dall'icona (barra dei menu su Mac / barra di sistema su Windows) lo ferma davvero.
+- **Le azioni lunghe trasmettono in streaming.** Lanciare un rail o generare una spec restituisce subito il controllo e termina in background; il tuo assistente può "tenerlo d'occhio" e riferirti quando si conclude.
+- **Sicurezza.** L'MCP usa un proprio token di accesso, separato da tutto il resto, e ascolta soltanto sulla tua macchina (loopback). Puoi copiare o rigenerare quel token in qualsiasi momento dal pannello.
+- **Non esposto (v1).** Per sicurezza, alcune capacità ad alto rischio sono volutamente escluse: eseguire comandi shell nel terminale, il browser integrato, la modifica dei file nell'app e l'installazione dei prerequisiti di sistema. Tutto ciò che *gestisce* Specrails è disponibile; l'accesso diretto alla macchina no.
+
+Puoi disattivare l'MCP in qualsiasi momento dallo stesso pannello — il tuo assistente perde semplicemente l'accesso e nient'altro cambia.

package/docs/guide/it/integrations/6-agent-chat.md

@@ -0,0 +1,64 @@
+# Gestisci Specrails conversando (Agent Chat)
+
+L'**Agent Chat** è un copilota che vive *dentro* Specrails e può pilotare l'intera app al posto tuo. Invece di navigare a clic tra progetti, spec, binari e analisi, basta che chiedi: *«quanti job sono andati a buon fine questa settimana?»*, *«crea una spec per il login social nel progetto API»*, *«lancia i tre ticket a priorità più alta e avvisami quando finiscono»*. Porta a termine il lavoro chiamando gli strumenti stessi di Specrails — gli stessi che espone il [server MCP](./5-mcp-server.md) — mentre vedi la dashboard aggiornarsi dal vivo dietro di lui.
+
+> **Da non confondere con gli agenti della pipeline.** La sezione *Agenti* (Architect → Developer → Reviewer) riguarda *come un binario implementa una spec*. L'**Agent Chat** è un unico assistente che *gestisce l'app stessa*. Cose diverse, stessa parola.
+
+## Come aprirlo
+
+C'è una **bolla** fluttuante in fondo alla finestra: cliccala per aprire il pannello, oppure premi **⌘⇧A** (**Ctrl+Shift+A** su Windows/Linux) da qualsiasi punto. Il pannello è una finestra vera che puoi spostare, ridimensionare, massimizzare e rimettere nella bolla; ricorda dove l'hai lasciato.
+
+È **non modale di proposito**: la dashboard dietro resta viva, così quando l'agente lancia un binario o crea una spec la vedi comparire in tempo reale — non stai guardando uno schermo congelato.
+
+## Prerequisito: il server MCP
+
+L'Agent Chat gestisce l'app tramite il **server MCP di Specrails** integrato, quindi deve essere attivo. Se non lo è, il pannello si apre con un banner **Attiva Specrails MCP** con un clic: premilo e sei pronto (senza riavvio). Vedi [Controlla Specrails da qualsiasi IA](./5-mcp-server.md) per i dettagli; non viene installato nulla, è tutto locale sulla tua macchina.
+
+## Scegliere su cosa lavora
+
+L'intestazione ha un **selettore di progetto** (come quello di Cursor). Scegli un progetto e tutto ciò che chiedi è circoscritto a esso — *«lancia quelli ad alta priorità»* si risolve su quel progetto. Lascialo su **Home** e l'agente lavora sull'intera configurazione: può elencare o creare progetti e rispondere a domande che abbracciano tutto. Se chiedi qualcosa di specifico di un progetto stando su Home, ti chiederà quale (o si offrirà di crearne uno) invece di indovinare.
+
+Scegliere un progetto qui **non** sposta la tua dashboard: l'obiettivo dell'agente e ciò che stai guardando sono indipendenti.
+
+## Provider e modello
+
+Proprio sopra la casella del messaggio scegli il **provider** (Claude, Codex o Gemini) e il suo **modello**. Ogni provider ha la propria lista di modelli, e cambiare provider avvia una sessione nuova con il modello predefinito di quel provider — così puoi, ad esempio, pilotare l'app con Claude e passare a Codex per un'altra conversazione senza che nulla si incroci.
+
+## Livelli di permesso — le redini le tieni tu
+
+L'agente può toccare tutta l'app, quindi decidi tu quanta libertà ha tramite un **livello** che cambi dal vivo premendo **Shift+Tab** (lo stesso ciclo usato da Claude Code). Ogni livello include tutto ciò che sta sotto:
+
+| Livello | Cosa può fare |
+|---|---|
+| 👀 **Osserva** | Sola lettura — elencare e ispezionare progetti, spec, job, analisi. Nulla cambia. |
+| ✍️ **Modifica** | Quanto sopra **+** creare e modificare (spec, impostazioni, configurazione dei binari) — modifiche reversibili. |
+| ⚡ **Opera** | Quanto sopra **+** avviare lavoro di IA che **costa denaro** (binari, generazione di spec). |
+| 🔥 **Autonomo** | Quanto sopra **+** eliminare e fermare cose — azioni irreversibili. |
+
+Inizia da **Osserva** e alza il livello solo quando vuoi che l'agente agisca. Se prova qualcosa oltre il livello attuale, si ferma e ti dice esattamente quale livello attivare — non aggira mai il limite. Questo è distinto dai livelli di Impostazioni ▸ MCP, che regolano gli assistenti *esterni*; il livello qui riguarda solo questo agente interno all'app.
+
+## Alcune cose che puoi chiedere
+
+Una volta su **Opera**, prova:
+
+> *«Elenca ogni spec da fare nel progetto API, poi lancia le tre a priorità più alta su binari separati e tienile d'occhio.»*
+>
+> *«Quanto ho speso questa settimana, suddiviso per progetto?»*
+>
+> *«Crea una spec per un interruttore modalità scura nel progetto web, con Contract Layer.»*
+>
+> *«Qualcosa è fallito nell'ultimo lotto — trova i job falliti e riassumi il perché.»*
+
+Le risposte arrivano fluide e già formattate (titoli, tabelle, elenchi), ciascuna con un piccolo pulsante **copia**. Un'etichetta di stato in basso mostra cosa sta facendo l'agente in questo momento — *Sto pensando…*, *MCP · jobs*, *Terminal* — così conosci sempre il suo stato.
+
+## Dettagli pratici
+
+- **Cronologia dei prompt.** Con la casella vuota, premi **↑**/**↓** per scorrere ciò che hai chiesto prima (mostrato attenuato mentre scorri); inizia a scrivere per modificarlo, oppure premi Invio per inviarlo.
+- **Riduci a icona, senza perdere nulla.** Clicca la ✕ per rimettere il pannello nella bolla — la conversazione continua a girare. Riaprilo e atterri sull'ultimo messaggio; nulla viene riscritto.
+- **Nuova conversazione.** Il pulsante **+** avvia un thread pulito; la cronologia vive a livello di app, sopra qualunque singolo progetto.
+
+## Alcune cose da sapere
+
+- **Opera e Autonomo costano denaro** perché eseguono IA. L'agente mette in evidenza le azioni che generano costi prima di eseguirle; tieni il livello su Osserva o Modifica se vuoi solo guardare e mettere in ordine.
+- **L'agente vale per tutta l'app**, non è legato al progetto che hai aperto — ecco perché ha un proprio selettore e la sua cronologia non è per progetto.
+- **È capace solo quanto glielo consente l'MCP.** Se un'intera area sembra off-limits, verifica che il server MCP sia attivato.

package/docs/guide/ja/integrations/5-mcp-server.md

@@ -0,0 +1,74 @@
+# 任意の AI から Specrails を操作する（MCP サーバー）
+
+Specrails は、[Model Context Protocol](https://modelcontextprotocol.io) を話す任意の AI アシスタント（Claude Desktop、Claude Code、Cursor、Cline、あるいは自作のエージェント）に対して、**自分自身**を公開できます。これをオンにしてアシスタントを Specrails に向ければ、チャットするだけでアプリ全体を操作できます。たとえば *「プロジェクト一覧を見せて」「API プロジェクトにソーシャルログインのスペックを作って」「レール 0 を起動して、終わったら教えて」「今週はいくら使った？」* といった具合です。あなたがあちこちクリックする代わりに、アシスタントが裏側で Specrails のツールを呼び出します。
+
+これは、プラグインや「My approved MCPs」機能とは逆方向の働きをします。それらは Specrails が*ほかの* MCP サーバーを*使う*ためのものですが、こちらは他のアプリに **Specrails** を使わせるためのものです。
+
+## オンにする
+
+これは**デフォルトでオフ**です。**Settings ▸ MCP** を開いて **Enable MCP** を切り替えてください。それだけです — サーバーは即座に起動し、再起動は不要です。
+
+外部の AI がどんな操作をできるかは、一連の権限ティアで*あなた*がコントロールできます。
+
+| ティア | 許可される内容 | デフォルト |
+|---|---|---|
+| **Read**（読み取り） | プロジェクト、スペック、ジョブ、アナリティクスなどの一覧表示と確認 | 常時オン（MCP が有効なとき） |
+| **Write**（書き込み） | スペックの作成・編集、設定やレール構成の変更 | オフ — 任意で有効化 |
+| **AI-spawn**（AI 起動） | AI を走らせて**お金がかかる**操作（レールの起動、スペックの生成、チャットターンの送信） | オフ — 任意で有効化 |
+| **Destructive**（破壊的操作） | プロジェクト／スペック／ジョブの削除、実行中の作業の停止 | オフ — 任意で有効化 |
+
+無効なティアに該当する操作をアシスタントが試みると、Specrails はそれを拒否し、どのティアをオンにすればよいかを明確なメッセージで知らせます。ですから、まずは読み取り専用から始め、必要なものだけをぴったり開放できます。
+
+## アシスタントを接続する
+
+パネルには、そのまま貼り付けられる構成ブロックが表示されます。最もシンプルで汎用的な方法は、同梱の**ブリッジ**（`specrails-mcp`）を使うことです。アシスタントがこれを実行し、ブリッジがあなたに代わって Specrails に中継します。ブリッジはアクセストークンをローカルで読み取るので、**トークンがアシスタントの設定に現れることはありません**。
+
+Claude Desktop や Cursor のようなクライアントでは、設定は次のようになります。
+
+```json
+{ "mcpServers": { "specrails": { "command": "specrails-mcp" } } }
+```
+
+リモートの HTTP MCP サーバーに対応しているクライアントなら、代わりにパネルのトークンを使って `http://127.0.0.1:4200/api/mcp` を直接指すこともできます。
+
+接続が完了すると、アシスタントにはアプリ全体をカバーする約 **18 個のツール**が見えるようになります — プロジェクト、スペック、レールとジョブ、チャット／Explore、エージェント、プラグイン、Jira、ループ、コードエクスプローラー、アナリティクス、設定など。さらに、最初に読み込む組み込みの**ガイド**ツールも含まれているので、あなたが何も説明しなくても、アシスタントは Specrails の仕組みを理解できます。
+
+## これで何ができるか
+
+アシスタントを接続したあとの、いくつかのレシピを紹介します。まずは **Read**（読み取り）をオンにして始め、実際に作業を作成・起動させたくなったら **Write**（書き込み）と **AI-spawn**（AI 起動）をオンにしてください。
+
+**ほかのツールにある作業をスペックに変える。** アシスタントが GitHub、Jira、Gmail、Slack にも接続されていれば、その作業をあなたの代わりに Specrails へ持ち込めます。
+> *「今週の 'bug' ラベルの付いた未解決の GitHub Issue を取り込んで、API プロジェクトにそれぞれスペックを作って、起動して。」*
+>
+> *「最新の顧客フィードバックのメールを読んで、テーマごとにまとめて、テーマごとにスペックを 1 つずつ作って。」*
+
+**夜通しのオートパイロット。** アプリをトレイに置いたまま走らせておけば、戻ってきたときにはレポートができています。
+> *「アイデアが 12 個あります。それぞれをスペックにして、レールで 3 つずつ起動して、すべてのジョブを見守って、明日になったら何が完了して、何が失敗して、いくらかかったかをまとめて教えて。」*
+
+**Destructive**（破壊的操作）をオフにしておけば、何ひとつ削除することなく一晩中ビルドを続けられます。
+
+**すべてのプロジェクトをまたいで。** ダッシュボードだけでは単独でできないことです。
+> *「私のプロジェクトを全部チェックして。バックログにスペックがあるのにレールが 1 つも動いていないものを教えて、それぞれで最も優先度の高いものを 1 つ起動して。」*
+
+**コーディング中も手を止めずに。** エディタからでも音声でも、ウィンドウを切り替えずに Specrails を操作できます。
+> *「チケット #42 のためにレール 0 を Opus で ultracode モードで起動して、終わったら教えて。」*
+
+**コストと履歴について尋ねる。** あなたのアナリティクスを、普通の言葉で。
+> *「今週、AI に一番お金を使ったのはどこ？ プロジェクト別とモデル別で。最もコストのかかったチケットを 5 つ見せて。」*
+
+**毎日のスタンドアップ。**
+> *「私のスタンドアップを書いて。昨日どのレールが走って、何が完了して、何が失敗して、合計コストはいくらか — Slack にそのまま貼れる箇条書きで。」*
+
+**コードを理解する。** エディタは不要です。
+> *「チケット #38 がどのファイルに触れたか教えて。それぞれ何が変わったかを 1 行で要約して。」*
+
+アシスタントはまず組み込みのガイドを読むので、ツールやスペックの名前をあなたが指定する必要はめったにありません — 望む結果を伝えれば、アシスタントが呼び出しを組み立ててくれます。
+
+## 知っておきたいこと
+
+- **Specrails が起動している必要があります。** MCP サーバーはアプリの内部に存在するため、アシスタントが到達できるのは Specrails が開いている間だけです。トレイのおかげで、ウィンドウを閉じてもバックグラウンドで動き続けます — 実際に停止させるには、トレイ（Mac のメニューバー／Windows のシステムトレイ）から **Exit** を選ぶ必要があります。
+- **長い操作はストリームされます。** レールの起動やスペックの生成はすぐに戻り、バックグラウンドで完了します。アシスタントはそれを「見守り」、決着したときに報告してくれます。
+- **セキュリティ。** MCP は他のすべてとは分離された専用のアクセストークンを使い、あなた自身のマシン上（ループバック）でのみ待ち受けます。このトークンはパネルからいつでもコピー、または再生成できます。
+- **公開されていないもの（v1）。** 安全のため、いくつかの高リスクな機能は意図的に除外されています。ターミナルでのシェルコマンド実行、組み込みブラウザ、アプリ内でのファイル編集、システム前提条件のインストールなどです。Specrails を*管理する*ものはすべて利用できますが、マシンへの生のアクセスはできません。
+
+MCP は同じパネルからいつでも無効にできます — アシスタントはアクセスを失うだけで、それ以外は何も変わりません。

package/docs/guide/ja/integrations/6-agent-chat.md

@@ -0,0 +1,64 @@
+# チャットで Specrails を操作する（Agent Chat）
+
+**Agent Chat** は Specrails の*内部*に住むコパイロットで、アプリ全体をあなたの代わりに動かせます。プロジェクト、スペック、レール、分析画面をクリックで渡り歩く代わりに、ただ頼むだけです。*「今週は成功したジョブがいくつ？」*、*「API プロジェクトにソーシャルログインのスペックを作って」*、*「優先度が最も高い 3 件のチケットを起動して、終わったら教えて」*。それは Specrails 自身のツール——[MCP サーバー](./5-mcp-server.md)が公開しているのと同じもの——を呼び出して作業を進め、その裏でダッシュボードがライブに更新されていく様子をあなたは見ていられます。
+
+> **パイプラインのエージェントと混同しないでください。** *エージェント*セクション（Architect → Developer → Reviewer）は*レールがどのようにスペックを実装するか*の話です。**Agent Chat** は*アプリそのものを操作する*単一のアシスタントです。別物ですが、同じ言葉です。
+
+## 開き方
+
+ウィンドウ下部に浮かぶ**バブル**があります——クリックするとパネルが開きます。あるいはどこからでも **⌘⇧A**（Windows/Linux では **Ctrl+Shift+A**）を押してください。パネルは移動・リサイズ・最大化ができ、バブルへ戻せる本物のウィンドウで、最後に置いた場所を覚えています。
+
+これは**意図的に非モーダル**です。背後のダッシュボードは生きたままなので、エージェントがレールを起動したりスペックを作成したりすると、それがリアルタイムで現れるのが見えます——固まった画面を眺めているわけではありません。
+
+## 前提条件：MCP サーバー
+
+Agent Chat は組み込みの **Specrails MCP サーバー**を通じてアプリを操作するため、それがオンになっている必要があります。オンでない場合、パネルはワンクリックの **Specrails MCP を有効化** バナー付きで開きます——押せば準備完了です（再起動不要）。詳細は[任意の AI から Specrails を操作する](./5-mcp-server.md)を参照してください。何もインストールされず、すべてはあなたのマシン内でローカルに動きます。
+
+## 何に対して作業するかを選ぶ
+
+ヘッダーには**プロジェクトセレクター**（Cursor のようなもの）があります。プロジェクトを選ぶと、頼んだことはすべてそれに限定されます——*「優先度の高いものを起動して」*はそのプロジェクトに対して解決されます。**ホーム**のままにしておくと、エージェントはあなたの環境全体にまたがって作業します。プロジェクトを一覧表示したり作成したりでき、全体に及ぶ質問にも答えられます。ホームにいながらプロジェクト固有のことを頼むと、推測ではなくどのプロジェクトかを尋ねてきます（あるいは新規作成を提案します）。
+
+ここでプロジェクトを選んでも、あなたのダッシュボードは**動きません**——エージェントの対象と、あなたが見ているものは互いに独立しています。
+
+## プロバイダーとモデル
+
+メッセージ欄のすぐ上で、**プロバイダー**（Claude、Codex、Gemini）とその**モデル**を選びます。各プロバイダーには独自のモデル一覧があり、プロバイダーを切り替えるとそのプロバイダーの既定モデルで新しいセッションが始まります——ですから、たとえば Claude でアプリを操作しつつ、別の会話では Codex に切り替える、といったことが何も混ざらずにできます。
+
+## 権限レベル——手綱はあなたが握る
+
+エージェントはアプリ全体に触れられるので、どこまで自由を与えるかはあなたが決めます。**Shift+Tab** を押してその場で切り替える**レベル**でコントロールします（Claude Code が使うのと同じ循環です）。各レベルはその下のすべてを含みます。
+
+| レベル | できること |
+|---|---|
+| 👀 **観察** | 読み取り専用——プロジェクト、スペック、ジョブ、分析の一覧表示と確認。何も変わりません。 |
+| ✍️ **編集** | 上記 **+** 作成と編集（スペック、設定、レール構成）——元に戻せる変更。 |
+| ⚡ **操作** | 上記 **+** **料金が発生する** AI 作業の起動（レール、スペック生成）。 |
+| 🔥 **自律** | 上記 **+** 削除や停止——取り消せない操作。 |
+
+**観察**から始め、エージェントに動いてほしいときだけレベルを上げてください。現在のレベルを超えることを試みると、エージェントは止まり、どのレベルに切り替えればよいかを正確に伝えます——制限を回避することは決してありません。これは*外部*アシスタントを統制する 設定 ▸ MCP のティアとは別物で、ここのレベルはこのアプリ内エージェント専用です。
+
+## 頼めることの例
+
+**操作**にしたら、試してみてください。
+
+> *「API プロジェクトの todo スペックをすべて一覧表示して、それから優先度が最も高い 3 件を別々のレールで起動して見守って。」*
+>
+> *「今週いくら使った？プロジェクトごとに内訳を出して。」*
+>
+> *「web プロジェクトにダークモード切り替えのスペックを、Contract Layer 付きで作って。」*
+>
+> *「直近のバッチで何かが失敗した——失敗したジョブを見つけて、原因をまとめて。」*
+
+返信は滑らかにストリーミングされ、整形済みで届き（見出し、表、リスト）、それぞれに小さな**コピー**ボタンが付きます。下部のステータスチップが、エージェントが今まさに何をしているか——*考え中…*、*MCP · jobs*、*Terminal*——を示すので、その状態が常に分かります。
+
+## 気の利いた工夫
+
+- **プロンプト履歴。** 入力欄が空のとき、**↑**/**↓** を押すと以前に頼んだ内容をたどれます（スクロール中は薄く表示されます）。入力を始めれば編集でき、Enter で送信できます。
+- **最小化しても失わない。** ✕ をクリックするとパネルはバブルへ戻ります——会話はそのまま動き続けます。開き直すと最新のメッセージに着地します。何も打ち直す必要はありません。
+- **新しい会話。** **+** ボタンでまっさらなスレッドを始めます。履歴はアプリ全体にわたって存在し、個々のプロジェクトの上位にあります。
+
+## 知っておくとよいこと
+
+- **操作と自律は料金が発生します**。AI を実行するからです。エージェントは料金の発生する操作を実行する前に前面に示します。眺めて整理したいだけなら、レベルは観察か編集にしておいてください。
+- **エージェントはアプリ全体のもの**であり、開いているプロジェクトに縛られません——だからこそ独自のセレクターを持ち、その履歴はプロジェクト単位ではないのです。
+- **その能力は MCP が許す範囲までです。** ある領域が丸ごと使えないように見える場合は、MCP サーバーが有効になっているか確認してください。