specrails-desktop 2.7.0 → 2.9.0

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

@@ -0,0 +1,48 @@
+# Dove vivono i tuoi dati
+
+In breve: **Specrails mantiene i tuoi repository immacolati.** Quando punti l'app a uno dei tuoi progetti, non ci si insedia, non sparpaglia file di configurazione in giro e non riscrive nulla che non gli abbia chiesto. Il tuo codice resta tuo, e pulito.
+
+## Il tuo repo resta pulito
+
+I file di Specrails — i suoi database, lo stato per progetto, le definizioni degli agent, le impostazioni, la telemetria, i riassunti e tutto il resto che gli serve per funzionare — vivono in un'unica casa ordinata sotto la tua home directory:
+
+```
+~/.specrails/
+```
+
+Quella cartella è il workspace privato dell'app. È dove vivono il registro dei progetti, i database per progetto, gli strumenti integrati e tutte le parti operative. I tuoi repository di codice veri e propri non vengono mai usati come discarica per nulla di tutto ciò.
+
+Questo significa che:
+
+- Il `.gitignore` del tuo repo **non** viene riscritto dall'app.
+- Il tuo repo non viene riempito di configurazioni di strumenti o directory di stato nascoste.
+- Rimuovere un progetto da Specrails non lascia disordine nel tuo codice.
+
+Se in passato hai usato strumenti che aggiungevano silenziosamente cartelle e file in giro per il tuo progetto, qui si tratta di una scelta deliberatamente diversa. Specrails è costruito in modo che puntarlo a un repo sia un **non-evento** per la storia git di quel repo.
+
+## L'unica cosa che *viene* committata — di proposito
+
+C'è esattamente un'eccezione voluta, ed è il senso stesso dello strumento: **le tue spec OpenSpec.**
+
+Le spec vivono nel tuo repository, sotto:
+
+```
+openspec/
+```
+
+E questo è voluto. Le tue spec sono un **deliverable** — un resoconto versionato e revisionabile di cosa hai deciso di costruire e perché. Devono stare accanto al tuo codice, tracciate in git, visibili nelle pull request, condivise con il tuo team. È lì il valore: le spec non sono stato temporaneo da buttare via, sono parte della storia del tuo progetto.
+
+Quindi la regola è semplice e onesta:
+
+- **`openspec/`** → vive nel tuo repo, committata, di proposito.
+- **Tutto il resto di cui Specrails ha bisogno** → vive sotto `~/.specrails/`, fuori dai piedi.
+
+## Perché funziona così
+
+Specrails esegue gli strumenti AI dal proprio workspace privato (sotto `~/.specrails/`) e raggiunge il tuo repository reale solo per le cose che hanno davvero bisogno di toccarlo — leggere il tuo codice e scrivere le spec che hai richiesto. Gli strumenti, le definizioni del framework e tutta la contabilità restano nella cartella di casa dell'app.
+
+Il vantaggio per te: puoi aggiungere un progetto, eseguire pipeline, esplorare spec e fare esperimenti con la certezza che il working tree e la storia git del tuo repository cambino solo nei modi che ti aspetteresti — le tue spec committate e il codice che le tue pipeline scrivono. Nient'altro si intrufola.
+
+## Rimuovere un progetto
+
+Quando rimuovi un progetto da Specrails, l'app fa pulizia del proprio stato per progetto sotto `~/.specrails/`. Le spec già committate nel tuo repo restano dove devono stare — nel tuo repo — perché sono tue.

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

@@ -0,0 +1,52 @@
+# Le spec e il backlog
+
+Una **spec** è l'unità di lavoro che la pipeline AI realizza. Puoi immaginarla come un ticket: un titolo, una descrizione di ciò che vuoi ottenere, una priorità ed eventuali etichette. Quando avvii la pipeline, gli agenti AI leggono la spec e agiscono su di essa — quindi una spec chiara è di gran lunga l'input più importante per ottenere un buon risultato.
+
+Nell'app le spec vengono talvolta chiamate **ticket**: i due termini significano la stessa cosa.
+
+## La board
+
+Ogni progetto si apre sulla sua **Dashboard**, che mostra la **SpecsBoard** — l'elenco di tutte le spec del progetto. Questo è il tuo backlog. Da qui crei nuove spec, ne imposti la priorità, le trascini su un rail per realizzarle e osservi il loro stato cambiare man mano che il lavoro procede.
+
+La board ha due modalità di visualizzazione, che si alternano con un toggle nella toolbar e vengono ricordate per ogni progetto:
+
+- **Vista post-it** (quella predefinita) — riquadri in stile card con brevi riepiloghi.
+- **Vista elenco** — righe compatte su una sola riga.
+
+Puoi anche filtrare per **stato** (Tutti / Da fare / Completati) e per **etichetta**, oltre a ordinare per **Predefinito**, **Ticket #** o **Priorità** (ciascuno con un toggle crescente/decrescente).
+
+## Stati
+
+Una spec attraversa un piccolo insieme di stati. La board associa a ciascuno un segnale visivo coerente, così puoi leggere lo stato del tuo backlog a colpo d'occhio:
+
+| Stato | Cosa significa |
+|--------|---------------|
+| **Bozza** | Un'idea in corso salvata da una conversazione in modalità Explore. Non ancora pronta da realizzare — puoi tornarci e continuare a darle forma. Mostra un badge `Draft`. |
+| **Da fare** | Pronta per essere presa in carico. È qui che atterra una spec finita quando la crei. |
+| **In corso** | La pipeline ci sta lavorando in questo momento (un punto blu pulsante). |
+| **Completato** | Portata a termine dalla pipeline (un segno di spunta verde). |
+| **Annullato** | Abbandonata (una X rossa). |
+
+Le bozze vivono nello stesso gruppo attivo delle spec Da fare — non c'è una colonna separata per loro — ma hanno un bordo dalla tinta sottile e un badge `Draft` che le rende facili da individuare. Consulta [Le bozze e il Contract Layer](drafts-and-contract-layer.md) per tutta la storia sulle bozze.
+
+## Priorità
+
+Ogni spec non-bozza ha una priorità: **Critica**, **Alta**, **Media** o **Bassa**. La priorità è puramente uno strumento organizzativo — ti aiuta a decidere cosa realizzare per primo e ti permette di ordinare la board. La imposti quando crei una spec e puoi cambiarla in qualsiasi momento facendo clic con il tasto destro sulla card della spec e scegliendo **Imposta priorità**.
+
+Le bozze sono l'unica eccezione: una bozza può non avere *alcuna* priorità, perché è ancora un'idea in lavorazione. La priorità viene fissata quando confermi la bozza trasformandola in una spec vera e propria.
+
+## Creare una spec
+
+Per creare una spec, clicca su **Aggiungi** (il pulsante Più nella toolbar della SpecsBoard). Si apre il dialog **Aggiungi spec**, con diversi modi di lavorare:
+
+- **Modalità Quick** — descrivi ciò che vuoi e l'AI scrive la spec completa in un colpo solo. Vedi [Aggiungi spec — Modalità Quick](add-spec-quick-mode.md).
+- **Modalità Explore** — conversi con l'AI, che ti aiuta a dare forma alla spec turno dopo turno. Vedi [Aggiungi spec — Modalità Explore](add-spec-explore-mode.md).
+- **Modalità Raw** — qualunque cosa scrivi viene salvata testualmente come spec, senza alcun coinvolgimento dell'AI. Usala quando hai già pronto il testo della spec.
+
+Quale scegliere dipende da quanto è già chiara l'idea. Sai esattamente cosa vuoi? Quick. La stai ancora mettendo a fuoco? Explore. Hai già il testo? Raw.
+
+## Dove andare adesso
+
+- [Aggiungi spec — Modalità Quick](add-spec-quick-mode.md) — il modo più rapido per trasformare un'idea in una spec.
+- [Aggiungi spec — Modalità Explore](add-spec-explore-mode.md) — dai forma a una spec conversando.
+- [Le bozze e il Contract Layer](drafts-and-contract-layer.md) — salva il lavoro in corso e arricchisci le spec per la pipeline.

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

@@ -0,0 +1,45 @@
+# Aggiungi spec — Modalità Quick
+
+La modalità Quick è pensata per quando sai già cosa vuoi. Scrivi la tua idea, l'AI redige la spec completa e questa atterra sulla tua board come **Da fare**. Niente botta e risposta — basta descriverla e partire.
+
+## Creare una spec in modalità Quick
+
+Per creare rapidamente una spec:
+
+1. Nella Dashboard, clicca su **Aggiungi** (il pulsante Più nella toolbar della SpecsBoard).
+2. Scegli la modalità **Quick**.
+3. Scrivi la tua idea nel campo di testo — una frase o un paragrafo, qualunque cosa la descriva.
+4. Clicca per generare.
+
+Mentre la spec viene scritta, un piccolo toast nell'angolo mostra il nome del progetto, un frammento della tua idea e il **tempo trascorso** ("Generazione… 0:12"). Al termine, il toast passa a "Generata in <tempo>" con un'azione **Vedi** che ti porta direttamente alla nuova spec.
+
+Questo è tutto il flusso. Tutto ciò che segue è una rifinitura facoltativa.
+
+## Cosa puoi regolare
+
+**Modello** — per impostazione predefinita l'AI sceglie un modello sensato. Puoi sovrascriverlo per ogni spec dal selettore di modello, se ne vuoi uno più veloce o più capace.
+
+**Engine** — se il tuo progetto ha installato più di un provider AI (una qualsiasi combinazione di Claude, Codex e Gemini), un selettore di engine si trova in cima al dialog, così puoi scegliere quale generi questa spec. La tua scelta viene ricordata per ogni progetto. I progetti con un solo provider non lo mostrano — non c'è nulla tra cui scegliere.
+
+**Contesto** — la modalità Quick di solito viene eseguita come un singolo turno, perché non ha bisogno di leggere il tuo codebase per scrivere una spec a partire dalla tua descrizione. Ma uno slider di contesto ti permette di darle più materiale su cui lavorare:
+
+- Al livello più basso legge solo la tua descrizione.
+- Ai livelli più alti può leggere le tue spec esistenti, le spec OpenSpec del tuo progetto e persino l'intero codebase prima di scrivere.
+
+Più contesto le dai, più tempo richiede la generazione (passa a multi-turno per poter leggere prima), ma la spec torna ancorata al tuo progetto reale. Punta a un contesto più alto quando la spec deve far riferimento a codice reale, nomi di file o comportamenti esistenti.
+
+**Allegati** — trascina mockup, brief o file di dati nel campo dell'idea. L'AI li legge come parte della scrittura della spec. (Anche gli allegati fanno passare la generazione a multi-turno.)
+
+**Arricchisci con Contract Layer** — un toggle che aggiunge un blocco strutturato alla spec generata, così la pipeline a valle non deve indovinare nomi o forme dei dati. È facoltativo e disattivato per impostazione predefinita; la tua ultima scelta viene ricordata per ogni progetto. Consulta [Le bozze e il Contract Layer](drafts-and-contract-layer.md) per scoprire cosa aggiunge e quando vale la pena.
+
+## Quando usare la modalità Quick e quando Explore
+
+Usa **Quick** quando l'idea è già chiara nella tua testa — potresti scrivere la spec da solo, preferisci solo che lo faccia l'AI. Usa [**Explore**](add-spec-explore-mode.md) quando la stai ancora pensando e vuoi un partner che ti aiuti a darle forma.
+
+Una spec creata in modalità Quick è una spec del tutto normale: in seguito puoi aprirla e usare **Continua a modificare** in una sessione Explore se ha bisogno di rifiniture.
+
+## Dove andare adesso
+
+- [Aggiungi spec — Modalità Explore](add-spec-explore-mode.md) — per le spec che hanno bisogno di essere modellate.
+- [Le bozze e il Contract Layer](drafts-and-contract-layer.md) — l'arricchimento Contract Layer spiegato.
+- [Esecuzione delle pipeline](running-pipelines.md) — trascina la tua nuova spec su un rail e realizzala.

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

@@ -0,0 +1,68 @@
+# Aggiungi spec — Modalità Explore
+
+La modalità Explore è una conversazione. Invece di scrivere tu stesso la spec, ragioni sull'idea insieme all'AI — che fa da partner di pensiero, pone domande, propone una struttura e costruisce una **bozza live** della spec man mano che procedete. Quando sei soddisfatto, confermi la bozza trasformandola in una spec vera e propria.
+
+Scegli Explore quando l'idea non è ancora del tutto definita, quando ci sono compromessi da discutere o quando vuoi che l'AI guardi il tuo codice reale prima di fissare la spec.
+
+## Creare una spec in modalità Explore
+
+Per dare forma a una spec in modalità Explore:
+
+1. Nella Dashboard, clicca su **Aggiungi**, poi scegli **Explore**.
+2. Scrivi il tuo primo messaggio — l'idea, una domanda o un pensiero ancora abbozzato.
+3. Leggi la risposta dell'AI e continua a rispondere. A ogni turno affina la sua comprensione.
+4. Osserva la **bozza live** aggiornarsi accanto alla chat — è la spec che prende forma.
+5. Quando la bozza ti sembra giusta, clicca su **Crea spec**.
+
+La conversazione resta nella tua cronologia, così puoi sempre tornarci per vedere come è stata modellata la spec.
+
+## La bozza live
+
+Mentre converssi, un pannello mostra la bozza così com'è in quel momento — titolo, descrizione, priorità, etichette, criteri di accettazione. Si riscrive a ogni turno in base a ciò che avete discusso. Non la modifichi direttamente; la guidi attraverso la conversazione ("anzi, metti la priorità alta", "aggiungi un criterio sulla gestione degli errori", e così via).
+
+Questo è il cuore della modalità Explore: non ti trovi mai davanti a un form vuoto. Stai sempre guardando una spec reale, in evoluzione.
+
+## Quanto vede l'AI: lo slider del contesto
+
+Prima che l'AI risponda, decidi tu quanto del tuo progetto può vedere. Uno slider di preset di contesto ti permette di scambiare velocità con profondità:
+
+| Preset | Cosa vede l'AI |
+|--------|------------------|
+| **Minimo** | Solo il tuo messaggio. Il più veloce ed economico. |
+| **Leggero** | + le tue spec esistenti. |
+| **Standard** | + le tue spec e le spec OpenSpec del tuo progetto. |
+| **Ricco** | + accesso in lettura all'intero codebase, così può ancorare le risposte al codice reale. |
+| **Max** | Ricco, più un passaggio di arricchimento Contract Layer alla conferma. |
+| **Desktop** | Max, più i server MCP del tuo progetto e i tuoi server MCP approvati. |
+
+Parti da un livello basso per un brainstorming veloce; sali quando vuoi che l'AI verifichi i suoi suggerimenti rispetto al tuo codice reale. La scelta viene salvata sulla conversazione, così non si riversa su altre sessioni Explore.
+
+Se vuoi un controllo più fine, clicca su **Fine-tune** per attivare manualmente le opzioni sottostanti — incluso **I miei MCP approvati**, che carica i server MCP che hai già approvato localmente senza rallentare la sessione.
+
+## Pulsanti nella shell Explore
+
+- **Crea spec** — promuove la bozza live a una spec vera e propria con stato **Da fare**. (Quando stai modificando una spec esistente, questo pulsante diventa **Aggiorna spec** e modifica quella spec sul posto.)
+- **Rivedi →** — apre un overlay di revisione che mostra la spec proposta confrontata con la baseline prima di confermare, così niente sorprese.
+- **Salva come bozza** — conserva la conversazione come ticket bozza per riprenderla in seguito. Disponibile non appena hai inviato almeno un messaggio. Vedi sotto.
+- **Riduci** — parcheggia la conversazione come chip nel dock delle chat ridotte in basso a sinistra. Clicca sul chip in qualsiasi momento per tornare dritto nella conversazione — non si perde nulla.
+- **Scarta** — getta via la conversazione (chiede prima conferma).
+
+## Salvare come bozza
+
+Non sei pronto a confermare, ma non vuoi perdere il ragionamento? Clicca su **Salva come bozza**. La conversazione diventa una **spec bozza** sulla tua board, e la bozza resta collegata alla conversazione che le sta dietro.
+
+In seguito, apri la bozza dalla board e clicca su **Continua a modificare** — la conversazione originale si riapre con la sua cronologia chat intatta, e riprendi esattamente da dove avevi lasciato. Le bozze non vengono mai eliminate automaticamente; ti aspettano.
+
+Questo rende Explore sicuro da usare per idee ancora acerbe: avvii una conversazione, arrivi da qualche parte, la salvi come bozza e torni domani.
+
+Per tutto ciò che riguarda le bozze — incluso l'arricchimento Contract Layer — consulta [Le bozze e il Contract Layer](drafts-and-contract-layer.md).
+
+## Nota multi-provider
+
+Se il tuo progetto ha installato più di un provider AI, un selettore di engine ti permette di scegliere quale guida la conversazione Explore. I progetti con un solo provider non lo mostrano.
+
+## Dove andare adesso
+
+- [Le bozze e il Contract Layer](drafts-and-contract-layer.md) — salvare il lavoro in corso e arricchire le spec per la pipeline.
+- [Aggiungi spec — Modalità Quick](add-spec-quick-mode.md) — quando l'idea è già chiara.
+- [Esecuzione delle pipeline](running-pipelines.md) — realizza la tua spec una volta che è pronta.

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

@@ -0,0 +1,81 @@
+# Le bozze e il Contract Layer
+
+Questa pagina copre due modi per sfruttare meglio le tue spec: le **bozze** (salvare un'idea in corso così da riprenderla in seguito) e il **Contract Layer** (un arricchimento facoltativo che rende le spec più precise per la pipeline AI).
+
+## Bozze: salvare un'idea in corso
+
+Una **bozza** è una conversazione [Explore](add-spec-explore-mode.md) in corso, salvata come spec. Ti permette di fermarti a metà ragionamento senza perdere nulla e di tornarci quando sei pronto.
+
+### Salvare una bozza
+
+Mentre sei in una conversazione Explore, clicca su **Salva come bozza** (disponibile una volta che hai inviato almeno un messaggio). L'app:
+
+- Crea una spec con stato **Bozza** sulla tua board.
+- Le assegna automaticamente un titolo se non ne hai impostato uno (un breve riepilogo della conversazione).
+- La ricollega alla conversazione, così l'intera cronologia chat viene conservata.
+
+Il salvataggio è idempotente — se salvi la stessa conversazione due volte, aggiorna la bozza esistente invece di crearne una duplicata.
+
+### Come appaiono le bozze sulla board
+
+Le bozze vivono nello stesso gruppo attivo delle tue spec Da fare — non c'è una colonna separata. Le riconosci da:
+
+- Un badge `Draft` dove normalmente si trova il badge della priorità.
+- Un bordo dalla tinta sottile sulla card.
+
+Una bozza può non avere *alcuna priorità* — la priorità la imposti quando la confermi trasformandola in una spec vera e propria.
+
+### Riprendere una bozza
+
+Per riprendere da dove avevi lasciato:
+
+1. Apri la bozza dalla board.
+2. Clicca su **Continua a modificare** nel modale di dettaglio.
+3. La conversazione Explore originale si riapre con la sua cronologia chat completa, e il pannello della bozza live precompilato con tutto ciò che avevi modellato fino a quel momento.
+4. Continua a conversare. Quando hai finito, **Crea spec** promuove la bozza a una spec vera e propria (stato **Da fare**, con la priorità che scegli).
+
+### Scartare una bozza
+
+Le bozze **non vengono mai eliminate automaticamente**. Spariscono solo quando le scarti esplicitamente, oppure quando le confermi in uno stato non-bozza. Scartare una bozza ripulisce anche la sua conversazione collegata, quando nient'altro vi fa riferimento.
+
+> Suggerimento: quando non sei sicuro che una spec valga la pena, salvala come bozza e lasciala lì. Aprila il mattino dopo, dai un'occhiata alla descrizione e decidi con occhi freschi.
+
+## Il Contract Layer: precisione per la pipeline
+
+Il **Contract Layer** è un arricchimento facoltativo che aggiunge un blocco strutturato alla descrizione di una spec. Il suo compito è eliminare le incertezze per gli agenti AI che realizzano la spec — così riutilizzano i nomi giusti, rispettano le forme dei dati attese e toccano i file giusti invece di inventarne di propri.
+
+### Cosa aggiunge
+
+Il Contract Layer è composto da cinque brevi sezioni aggiunte alla spec:
+
+- **Naming Contract** — gli identificatori esatti (funzioni, campi, route) che l'implementazione dovrebbe riutilizzare.
+- **Data Shapes** — i payload in stile JSON coinvolti.
+- **State Machine** — le transizioni o gli stati attraverso cui passa la funzionalità.
+- **Invariants** — le proprietà che devono sempre rimanere vere.
+- **File Touch List** — i file che l'implementazione dovrebbe modificare.
+
+Pensalo come consegnare alla pipeline un progetto preciso invece di uno schizzo. È particolarmente prezioso per le spec che si innestano in codice esistente, dove un nome o una forma indovinata dall'AI causerebbe del lavoro da rifare.
+
+### Come aggiungerlo
+
+Ci sono tre modi in cui il Contract Layer viene applicato:
+
+- **Modalità Quick** — attiva il toggle **Arricchisci con Contract Layer** prima di generare. La tua ultima scelta viene ricordata per ogni progetto. (Vedi [Aggiungi spec — Modalità Quick](add-spec-quick-mode.md).)
+- **Modalità Explore** — scegli il preset di contesto **Max** o **Desktop** (che eseguono l'arricchimento automaticamente alla conferma), oppure apri **Fine-tune** e attivalo manualmente. (Vedi [Aggiungi spec — Modalità Explore](add-spec-explore-mode.md).)
+- **Su una spec esistente** — apri il modale di dettaglio della spec e ri-esegui l'arricchimento da lì.
+
+### Dove appare
+
+Una volta che una spec ha un Contract Layer, il modale di dettaglio lo mostra come una sezione comprimibile con un badge tipo `3/5 compilate` — che ti dice quante delle cinque sezioni sono state effettivamente compilate (alcune funzionalità semplicemente non hanno, ad esempio, una state machine, e quelle sezioni vengono contrassegnate come non applicabili). Espandila per leggere il contratto completo; comprimila per mantenere ordinata la descrizione.
+
+Se l'arricchimento dovesse fallire, l'app mostra una notifica con un'azione **Riprova** così puoi rilanciarlo.
+
+### Vale sempre la pena?
+
+Non sempre. Per una spec piccola e autonoma l'AI riesce a implementarla bene anche senza. Il Contract Layer dà il suo valore sulle spec che si integrano strettamente con il codice esistente, dove nomi e forme esatti contano — è lì che fissare il contratto in anticipo ti risparmia un giro di correzioni più avanti.
+
+## Dove andare adesso
+
+- [Aggiungi spec — Modalità Explore](add-spec-explore-mode.md) — da dove arrivano le bozze.
+- [Aggiungi spec — Modalità Quick](add-spec-quick-mode.md) — il toggle del Contract Layer in modalità Quick.
+- [Esecuzione delle pipeline](running-pipelines.md) — realizza una spec una volta che è pronta.

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

@@ -0,0 +1,38 @@
+# エージェントの紹介
+
+**Implement** レールを起動するとき、Specrails はあなたのスペックを1つの AI に丸投げして結果を祈る、ということはしません。それぞれ1つの役割だけを担う小さな専門 *エージェント* チームを、意図された順番で動かします。このページでは、そのチームのメンバーと、それぞれが何をするのかを紹介します。
+
+## 基本のトリオ
+
+すべてのパイプライン実行で、この3つのエージェントが使われます。これらはまさに屋台骨であり、プロジェクトはこの3つなしにレールを実行できません。
+
+| エージェント | 役割 | 何をするか |
+|-------|------|--------------|
+| **sr-architect** | プランナー | あなたのスペックを読み、コードベースを調べ、具体的な実装プランを作成します — どのファイルに手を入れるか、変更がどんな形になるか、何に気をつけるべきか。誰かがコードを書く前に、まず考えます。 |
+| **sr-developer** | ビルダー | アーキテクトのプランを受け取り、実際にコードを書きます: 新しいファイル、編集、テスト。ここであなたのスペックが本物の差分（diff）に変わります。 |
+| **sr-reviewer** | 批評家 | デベロッパーの成果をスペックとプランに照らして検証し、リグレッションを見つけ、何かおかしいときには差し戻します。変更が完了と見なされる前の品質ゲートです。 |
+
+これは **設計 → ビルド → レビュー** ——慎重な人間のチームがたどるのと同じループ——だと考えてください。各エージェントは自分の成果物を次のエージェントへ手渡すので、デベロッパーが手探りで作業することはなく、レビュアーは常に元々の意図と照らし合わせてチェックできます。
+
+## スペシャリストエージェント
+
+トリオに加えて、プロジェクトには特定の種類の作業を担う任意の **スペシャリストエージェント** を含めることもできます。最もよく見かけるのは次のものです。
+
+- **sr-merge-resolver** — マージコンフリクトを解きほぐし、重なり合う変更を調整するのを助けるユーティリティエージェントです。任意の存在で、欲しいときだけプロファイルに含めればよく、いなくてもパイプラインを止めることは決してありません。
+
+スペシャリストはオプトイン方式です。新しいプロジェクトはトリオだけで動き、プロジェクトのワークフローが必要とするときに、スペシャリスト（そしてあなた自身の **カスタムエージェント** ——[カスタムエージェントとカタログ](custom-agents-catalog) を参照）を追加します。
+
+## タスクが正しいエージェントに届く仕組み
+
+1回の実行の中では、作業は *ルーティング* されます。タスクはタグを持ち、プロファイルのルーティングルールが、タグ付きのタスクをそれに最も適したエージェントへ送ります — そして最後に、それ以外のすべてをデベロッパーへ送る包括ルールがあります。通常の使い方ではこれを意識する必要はありません。デフォルト設定が、最初からすべてを適切にルーティングしてくれます。特定の種類の作業を特定のエージェントへ向けたくなったら、[エージェントごとのモデルのカスタマイズ](customizing-models-per-agent) を参照してください。
+
+## 最初に押さえておきたい大切な考え方
+
+各エージェントの *定義* ——その指示内容、その個性、できることの範囲—— は **共有** されます。これらはファイル（`.claude/agents/<id>.md`）として存在し、リポジトリと一緒に移動します。そのため、チーム全体が同じアーキテクト、同じレビュアーを動かすことになります。
+
+一方、**プロジェクトごと** になるのは、その上に重なる *設定* です: 各エージェントがどのモデルで動くか、そしてあるレールにどのエージェントの組み合わせを選ぶか。それこそがプロファイルの役割です —— そしてそれが次のページの話題です。
+
+## 次に読むなら
+
+- [プロファイルとバランスの取れたデフォルト](profiles-and-the-balanced-default) — チームの設定がどうパッケージされ、選ばれるのか。
+- [エージェントごとのモデルのカスタマイズ](customizing-models-per-agent) — コストと品質を調整する。

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

@@ -0,0 +1,45 @@
+# プロファイルとバランスの取れたデフォルト
+
+**プロファイル** とは、パイプライン実行のために保存されたレシピです。次の3つの問いに、ひとつの場所でまとめて答えてくれます。
+
+1. **どのエージェント** が参加するか（基本のトリオ、それに加えてスペシャリストやカスタムエージェント）。
+2. 各エージェントが **どのモデル** で動くか。
+3. タスクがそれらのエージェントへ **どうルーティングされるか**。
+
+プロファイルは、どのプロジェクトでも **Agents** セクションにあります（右サイドバー → **Agents** → **Profiles** タブ）。
+
+## バランスの取れたデフォルト
+
+最初の状態では、プロジェクトは適切な **default** プロファイルに解決されます。これは基本のトリオ —— `sr-architect`、`sr-developer`、`sr-reviewer` —— を含み、単一の包括ルールを通じて、すべてのタスクをデベロッパーへルーティングします。モデルは日々の作業に向けてバランスよく選ばれており、肝心なところでは有能なモデルを使いつつ、すべてのステップで最も高価な選択肢に手を伸ばすことはありません。
+
+もしプロジェクトで、すでに従来の方法（エージェントファイルのフロントマター）でエージェントのモデルを設定していた場合は、**Migrate** ボタンがそれらを読み取り、今の動作をそのまま忠実に再現する `default` プロファイルを作成します —— 損失ゼロで、あなたが調整しようと決めるまで何も変わりません。
+
+要点はこうです: **Specrails を使うのにプロファイルを作る必要はありません。** デフォルトのままでちゃんと動きます。プロファイルは、そこからさらに踏み込むための手段です。
+
+## 実行ごとにプロファイルが選ばれる仕組み
+
+レールを起動すると、Specrails は次の順番でプロファイルを選びます。
+
+1. レールヘッダーでの **あなたの明示的な選択**（後述）。
+2. あなたの **開発者ごとの優先設定** —— このプロジェクトで自分用のデフォルトとして指定したプロファイル（あなたローカルのもので、コミットされません）。
+3. プロジェクトの **`default`** プロファイル。
+
+プロファイルは *起動時にスナップショット* されるため、バッチ内の各レールはそれぞれ異なるプロファイルを実行でき、後からプロファイルを変更しても、すでに開始済みのジョブが書き換わることは決してありません。
+
+## レールごとにプロファイルを選ぶ
+
+プロファイルの選択は、起動するまさにその場所 —— **レールヘッダー** のプロファイルセレクター —— で行います。
+
+- ドロップダウンからプロファイルを選ぶと、**この起動だけ** に使われます。
+- 固定オプションを使うと、そのプロファイルをそのレールの今後の標準の選択にできます。
+
+これが流れのすべてです: プロファイルを選び、起動し、おしまい。同じバッチ内で並行するレールは、それぞれ自分のプロファイルを持てるので、ちょっとした修正と重めの機能を、別々の設定で並べて走らせることができます。
+
+## Agents セクションが静かなとき
+
+プロファイルは Claude の機能です。Claude 以外のプロバイダー（Codex または Gemini）を含むプロジェクトでは、Agents セクションは非表示になり、レールはプロファイルなしで実行されます —— これはバグではなく想定どおりの動作です。プロファイルにはまた、プロジェクトに十分新しい `specrails-core` も必要です。古い場合は黄色のバナーが表示されます。作成したプロファイルは引き続き **保存** されます —— ただし core が更新されるまではパイプラインに影響しません。バナーに表示されたコマンドで更新すると、それらが有効になります。
+
+## 次に読むなら
+
+- [エージェントごとのモデルのカスタマイズ](customizing-models-per-agent) — `fast` と `max` のプロファイルを作る。
+- [カスタムエージェントとカタログ](custom-agents-catalog) — チームを眺め、拡張する。

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

@@ -0,0 +1,60 @@
+# エージェントごとのモデルのカスタマイズ
+
+プロファイルがもたらす最も役立つ機能は、ひとつだけ挙げるなら **各ステップに合ったモデルを選べること** です。プランニングのステップにはいちばん強力なモデルが値するかもしれませんが、ありふれたビルドのステップなら、もっと速くて安価なモデルでまったく問題ないかもしれません。プロファイルを使えば、それをそのまま表現できます。
+
+ここで「共有」と「プロジェクトごと」の切り分けが効いてきます。
+
+- エージェントの *定義* は、チーム全体で共有されたままです。
+- *各エージェントが動くモデル* は、プロファイルの中で **プロジェクトごと** に設定され、あなたのプロジェクトだけに影響します。
+
+モデルを変えると、そのプロジェクトのコストと振る舞いが変わります —— 他の誰かの設定や、エージェントの根底にある指示内容には一切触れずに。
+
+## エージェントが使うモデルを変更する
+
+**Agents → Profiles** でプロファイルを選び、そのエージェントチェーンエディターを開きます。チェーン内の各エージェントにはモデルフィールドがあります。さらに、パイプラインのトップレベルの調整を担う **orchestrator**（オーケストレーター）のモデルもあります。
+
+モデルの値はエイリアスです —— Claude の場合は `opus`、`sonnet`、`haiku`（最も有能 → 最も高速）です。エージェントごとに、使いたいエイリアスを設定してください。
+
+- エージェントのモデルを **空欄** のままにすると、そのエージェントファイル自身のデフォルトにフォールバックします。
+- 明示的に設定すると、このプロファイルだけで上書きします。
+
+保存すれば、そのプロファイルで次に起動されるレールは新しいモデルを使います。すでに実行中のジョブは、自分のスナップショットを保持します。
+
+## `fast` や `max` のようなプロファイルを作る
+
+自然なやり方は、ジョブに応じて使い分けられる、名前付きのプロファイルをいくつか用意することです。
+
+**`fast` プロファイル** —— 小さくリスクの低い変更で、速さと小さめの請求額が欲しいとき:
+
+- アーキテクト: 中程度または高速のモデル —— プランはシンプルなので。
+- デベロッパー: 高速のモデル —— 変更は機械的なので。
+- レビュアー: しっかりさせておきつつ、ここも少し削ってよいでしょう。
+
+**`max` プロファイル** —— 厄介で失敗できない機能で、すべてのステップをできる限り鋭くしたいとき:
+
+- アーキテクト、デベロッパー、レビュアー: すべてにわたって、いちばん強力なモデルを。
+
+### 作り方は2通り
+
+1. **複製して調整する** *(おすすめ)*。`default` プロファイルを選び、**Duplicate** で複製し、コピーに `fast` や `max` のようなケバブケースの名前を付けてから、各エージェントのモデルを調整します。動作実績のあるチェーンとルーティングを引き継いだうえで、変えたいところだけを変えられます。
+2. **空から始める。** **Blank profile**（空のプロファイル）を作り、チェーンを自分で組み立てます。その場合でも基本のトリオ（`sr-architect`、`sr-developer`、`sr-reviewer`）はすべて含める必要があり —— パイプラインは3つすべてに依存しています —— さらに、終端の包括ルーティングルールをちょうど1つ、必ず最後に置く必要があります。
+
+プロファイル名は小文字のケバブケースです（例: `fast`、`max`、`cheap-and-cheerful`）。
+
+## タスクを特定のエージェントへルーティングする
+
+プロファイルの **ルーティングルール** は、タグ付きタスクをどのエージェントが処理するかを決めます。各ルールはタスクのタグとターゲットエージェントを列挙し、タグが最初にマッチしたルールが勝ち、末尾にある単一の `default: true` ルールがそれ以外のすべてを受け止めます。ルーティング先に指定できるのは、実際にそのプロファイルのチェーンに含まれるエージェントだけです —— エディターがこれを強制します。
+
+日々の使い方ではルーティングに触れることはありません: 包括ルールが作業をデベロッパーへ送り、それで正しいのです。たとえば `migration` タグの付いた作業をデベロッパーではなくスペシャリストへ送りたい、といったときにタグルールの出番です。
+
+## 起動時にプロファイルを選ぶ
+
+これらすべてが起動時に集約されます: レールヘッダーで、レールごとに `fast`、`max`、`default` を選びます。バッチではこれらを混在させられます —— ちょっとした修正は `fast` で、大きな機能は `max` で、両方同時に。選択の流れについては [プロファイルとバランスの取れたデフォルト](profiles-and-the-balanced-default) を参照してください。
+
+## 安全性についてのひとこと
+
+プロファイルの削除は、進行中の作業にとって安全です: すでにそのプロファイルで起動済みのジョブはスナップショットを保持し、今後の起動は解決順序に沿って単にフォールバックします。気軽に試してください。
+
+## 次に読むなら
+
+- [カスタムエージェントとカタログ](custom-agents-catalog) — チェーンに組み込むエージェントを追加する。

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

@@ -0,0 +1,43 @@
+# カスタムエージェントとカタログ
+
+プロファイルは *どのエージェントがどのモデルで動くか* を決めます。では、エージェントそのものはどこから来るのでしょうか？ それが **Agents カタログ** です。
+
+どのプロジェクトでも **Agents → Catalog** を開いてください。そのプロジェクトで利用できるすべてのエージェントを、2つのグループに分けて表示する読み取り専用のビューアーです。
+
+- **アップストリームエージェント** —— `specrails-core` に付属するエージェント: 基本のトリオ（`sr-architect`、`sr-developer`、`sr-reviewer`）と、`sr-merge-resolver` のようなスペシャリストです。
+- **カスタムエージェント** —— あなた自身が追加した、`custom-*` という名前のエージェントです。
+
+各カタログ項目には、そのエージェントが何のためのもので、どのデフォルトモデルを使うかが表示されるので、エージェントをプロファイルのチェーンに組み込む前に、全員の顔ぶれを確認できます。
+
+## カスタムエージェントを追加する
+
+カスタムエージェントは、リポジトリの `.claude/agents/` 配下にある、`custom-<something>.md` という名前のただの Markdown ファイルです。そのファイルには、エージェントの指示内容（そのシステムプロンプト）と、デフォルトの `model:` を含む小さなフロントマターヘッダーが入っています。
+
+ファイルがプロジェクトに存在すると、カタログにカスタムエージェントとして現れ、その id を任意のプロファイルのエージェントチェーンに追加できる（そしてそこへタスクをルーティングできる）ようになります。id はファイル名と一致している必要があります —— `custom-docs` という項目は `.claude/agents/custom-docs.md` に対応します。
+
+カスタムエージェントはリポジトリの中に住んでいるので、**コミット可能なチームの資産** です: ファイルをコミットすれば、チーム全員がそのエージェントを手に入れます。これは Agents セクション全体を貫く中心的な考え方を映したものです ——
+
+> **エージェントの定義は共有されます（リポジトリの中に住み、`git` とともに移動します）。モデルの設定はプロジェクトごとです（プロファイルの中に住みます）。**
+
+`custom-*` の名前空間は予約され、保護されています: `specrails-core` の `init` コマンドと `update` コマンドは `.claude/agents/custom-*.md` に決して触れないので、あなたのカスタムエージェントは core のアップグレードを無傷で生き延びます。（同じ保護は、`custom-serena.md` のようなプラグイン提供のフラグメントにも及びます。）
+
+## カスタムエージェントを実際に使う
+
+典型的な流れは次のとおりです。
+
+1. 指示内容とデフォルトモデルを記した `.claude/agents/custom-<name>.md` を書く。
+2. それが **Agents → Catalog** の Custom に現れることを確認する。
+3. **Agents → Profiles** で、そのエージェントをプロファイルのチェーンに追加する（必要なら、そのプロファイル用にモデルを上書きする）。
+4. 適切なタグの付いたタスクがそのエージェントに届くようにルーティングルールを追加する —— あるいはチェーンの順序に任せる。
+5. レールヘッダーから、そのプロファイルでレールを起動する。
+
+## プロファイルの成績を観察する
+
+Agents セクションには **Usage** タブもあります —— 選んだ期間のあいだに、各プロファイルでいくつのジョブが実行されたかを、プロファイルごとに内訳表示するものです。`fast` / `max` の使い分けが本当に意図どおりに使われているかをさっと確認したり、チームがどのプロファイルに引き寄せられているかを見つけたりするのに便利です。
+
+## セクション全体のおさらい
+
+- **エージェント** は専門のチームメンバーです —— 共有のトリオに加えて、スペシャリストとあなたのカスタムエージェント。（[エージェントの紹介](meet-the-agents)）
+- **プロファイル** は、どのエージェントがどのモデルで動き、タスクがどうルーティングされるかをパッケージし、起動時にレールごとに選択されます。デフォルトプロファイルは、日々のためのバランスの取れた選択肢です。（[プロファイルとバランスの取れたデフォルト](profiles-and-the-balanced-default)）
+- **モデル** はプロファイルの中で、エージェントごと・プロジェクトごとに調整されます —— ジョブに合わせて `fast` と `max` を作りましょう。（[エージェントごとのモデルのカスタマイズ](customizing-models-per-agent)）
+- **カタログ** はすべてのエージェントを表示し、`custom-*` の名前空間がチームを成長させてくれます —— 定義は共有、設定はプロジェクトごとに。

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

@@ -0,0 +1,49 @@
+# specrails とは
+
+**specrails** へようこそ。これは、AI コーディングアシスタントを、*あなた自身*のプロジェクトのために*あなた自身*のマシン上で働く本物のソフトウェアチームへと変えてくれるデスクトップアプリです。
+
+プロンプトを行ったり来たりコピペする代わりに、やりたいことを **スペック**（spec）として記述するだけ。あとは specrails が、設計・実装・レビュー・出荷という完全な開発パイプラインにそれを通し、その様子をライブで見守れます。
+
+## スペック駆動の AI 開発
+
+specrails の核にあるのは、とてもシンプルな考え方です。**AI から良いコードを引き出す一番の方法は、明確なスペックから始めること。**
+
+*スペック* とは、ひとつの作業 — 機能追加、修正、リファクタリングなど — を簡潔かつ構造化して記述したものです。数秒で書くこともできますし、適切な問いを投げかけながら下書きまで仕上げてくれるガイド付きチャットで形にすることもできます。各スペックは、ほかの課題管理ツールのタスクと同じように、プロジェクトボード上の **チケット** になります。
+
+あとは、そのスペックをパイプラインに渡し、面倒な作業を AI に任せるだけです。
+
+## パイプライン: Architect → Developer → Reviewer → Ship
+
+スペックを起動すると、specrails はそれを 4 つのステージに通します。それぞれを、役割に特化した AI エージェントが担当します。
+
+1. **Architect** — スペックと周辺コードを読み込み、変更を計画します。どのファイルに手を入れるか、解決策の形はどうあるべきかを設計します。
+2. **Developer** — その計画に沿って、実際のコードを書きます。
+3. **Reviewer** — 成果物の正しさと品質をチェックし、あなたが気づく前に問題を見つけ出します。
+4. **Ship** — 変更を仕上げ、コミットできる状態に整えます。
+
+各ステージは実行中にそのまま表示され、AI からのログがリアルタイムでストリーミングされます。何も隠されていません。もし何かがおかしくなっても、どこで起きたのかが正確に分かります。
+
+## プロジェクト
+
+specrails のすべては **プロジェクト** を中心に整理されています。プロジェクトとは、要するにコードベースを収めたコンピュータ上のフォルダのこと。好きなだけプロジェクトを追加でき、瞬時に切り替えられます。それぞれが独自のスペック、ジョブ履歴、分析、設定を保持します。
+
+specrails が、あなたが頼んでもいないコードに手を出すことはありません。既存のリポジトリの中で動作し、何をコミットするかは常にあなたがコントロールします。
+
+## AI プロバイダーを選ぶ
+
+specrails は、主要な AI コーディング CLI に対応しています。
+
+- **Claude**（Claude Code）
+- **Codex**（Codex CLI）
+- **Gemini**（Gemini CLI）
+
+すでに使っているものを選んでも、複数インストールしてタスクごとに使い分けてもかまいません。プロジェクトは単一のプロバイダーでも、複数同時でも動かせるので、特定のツールに縛られることはありません。
+
+## ここが気に入るはず
+
+- **混乱のないスピード** — スペックが AI の焦点を保つので、当て推量の散らかった結果ではなく、役に立つ変更が得られます。
+- **完全な可視性** — ライブログ、分かりやすいパイプラインビュー、プロジェクトごとの分析が、何が起きてコストがいくらだったかを正確に示します。
+- **あなたのマシン、あなたのコード** — すべてがローカルで、実際のリポジトリに対して実行されます。
+- **すべてが一か所に** — スペック、ジョブ、チャット、内蔵ターミナル、コスト追跡が、すべて 1 つのウィンドウにまとまっています。
+
+さあ、始めましょう。次は [Installing & first run](installing-and-first-run) へ。

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

@@ -0,0 +1,42 @@
+# インストールと初回起動
+
+specrails をマシンに導入するのは、ほんの数分で終わります。ここでは、その流れをまるごと紹介します。
+
+## 1. ダウンロードしてインストールする
+
+お使いのプラットフォーム用のインストーラーを入手しましょう。
+
+- **macOS（Apple Silicon）** — `.dmg` ファイルです。開いて、**specrails** をアプリケーションフォルダにドラッグします。
+- **Windows** — `.exe` セットアップインストーラーです。実行して、画面の指示に従ってください。
+
+> **macOS と Windows のセキュリティ警告について**
+>
+> - **Windows** では、インストーラーがまだコード署名されていないため、SmartScreen が警告を表示することがあります。**詳細情報 → 実行** をクリックして続行してください。
+> - **macOS** では、アプリは署名・公証済みなので、問題なく開けるはずです。
+
+## 2. 用意しておくもの（前提条件）
+
+specrails は、実際のコマンドラインツールを動かして AI 開発パイプラインを実行します。そのため、いくつかのツールが利用できる状態になっている必要があります。うれしいことに、デスクトップアプリは **そのほとんどをあらかじめ同梱しています**（Node.js、npm、Git がアプリ内に含まれています）。なので、まっさらなマシンでも、たいていは何もインストールせずに済みます。
+
+specrails が同梱できない唯一のものが、**AI プロバイダーの CLI** 本体です。次のうち、少なくともひとつが必要になります。
+
+- **Claude Code**
+- **Codex CLI**
+- **Gemini CLI**
+
+使う予定のものをインストールし、ターミナルから一度サインインしておけば準備完了です。どのプロバイダーが入っているかは specrails が自動で検出します。
+
+> もしどれかのツールが「見つからない」と表示された場合は、アプリが **詳細情報** リンクを示し、お使いの OS に合わせたコピペ用のインストールコマンド（macOS なら Homebrew、Windows なら winget、Linux なら apt/dnf）を案内します。再チェックはいつでも、再起動なしで行えます。
+
+## 3. 初回起動 — ウェルカム画面
+
+specrails を初めて開くと、すっきりした **ウェルカム画面** が表示されます。まだプロジェクトがないので、最初のプロジェクトを追加するよう案内されます。
+
+ここには次のものが表示されます。
+
+- specrails が何をするものかの簡単な説明
+- ひとつだけの **最初のプロジェクトを追加** ボタン
+
+オンボーディングはこれだけ。アカウント作成もサインアップもありません。specrails はすべてあなたのマシン上で動作します。
+
+**最初のプロジェクトを追加** をクリックして、[Adding your first project](adding-your-first-project) へ進みましょう。