specrails-desktop 2.8.0 → 2.9.1

package/docs/guide/it/integrations/2-plugins.md

@@ -0,0 +1,44 @@
+# Plugin (Integrazioni)
+
+La sezione **Integrazioni** è un marketplace per progetto di componenti aggiuntivi opzionali che ampliano ciò che l'AI può fare. Ogni progetto decide in autonomia quali plugin vuole — installare un plugin in un progetto non tocca mai gli altri.
+
+I plugin funzionano registrando in modo silenzioso un **server MCP** (Model Context Protocol) nel tuo progetto, dando all'AI nuovi strumenti da richiamare durante i rail e la chat. Non serve capire l'MCP per usarli — installa e saranno disponibili alla prossima esecuzione di un rail.
+
+## Cosa è disponibile oggi
+
+Questa versione è **solo inclusa**: i plugin che puoi installare sono quelli integrati nell'app. Non c'è un registro remoto, non ci sono plugin caricati dagli utenti, né caricamento di codice di terze parti — quindi tutto ciò che trovi nel catalogo è verificato e distribuito con Specrails.
+
+Il plugin di punta è:
+
+- **Serena** — navigazione semantica del codice. Dà all'AI una comprensione del tuo codebase basata su un language server (vai alla definizione, trova i riferimenti, ricerca consapevole dei simboli) invece di una semplice corrispondenza di testo. Ottimo per repository ampi o poco familiari, dove vuoi che l'agente ragioni su simboli reali.
+
+  Serena richiede lo strumento `uv` nel tuo `PATH` (viene eseguito tramite `uvx`). L'app rileva automaticamente se `uv` è presente e ti avvisa se manca.
+
+## Installare un plugin
+
+1. Apri **Integrazioni** dalla barra laterale destra.
+2. Trova il plugin nel catalogo. Ogni scheda mostra uno stato: **Non installato**, **Installato**, **Degradato** o **Orfano**.
+3. Entra nel plugin per **vedere l'anteprima dell'installazione** — ti mostra esattamente quali file cambieranno prima che succeda qualsiasi cosa.
+4. Clicca **Installa**. Vedrai l'avanzamento in tempo reale durante la configurazione.
+
+Dietro le quinte l'installazione è *chirurgica e additiva*: aggiunge soltanto le proprie voci al `.mcp.json` del tuo progetto (e, per alcuni plugin, un file frammento nel namespace protetto `.claude/agents/`). Non riscrive mai integralmente la tua configurazione, e l'aggiunta di un secondo plugin non può mai disturbare il primo. Se l'installazione non riesce a verificarsi come integra, viene annullata in modo pulito.
+
+## Gestire i plugin installati
+
+- **Salute.** Ogni plugin ha un controllo di salute su richiesta. Un plugin che si installa correttamente ma in seguito non riesce ad avviarsi viene contrassegnato come **Degradato** — non blocca i tuoi rail, vedrai solo il badge e un motivo.
+- **Disinstalla.** Rimuovere un plugin elimina in modo chirurgico solo le voci di sua proprietà, lasciando intatto il resto della configurazione.
+- **Orfani.** Se i file di un plugin rimangono indietro senza uno stato corretto (per esempio dopo una modifica interrotta), il plugin appare come **Orfano** e puoi ripulirlo con un clic.
+
+## Come i plugin compaiono nel tuo lavoro
+
+- **Rail.** Prima che un rail venga eseguito, Specrails controlla quali plugin sono installati e integri e rende quegli strumenti disponibili all'agente per quel job. Un plugin degradato viene semplicemente saltato per quell'esecuzione — il rail si avvia comunque normalmente. Ogni job registra uno snapshot di quali plugin erano attivi, che puoi vedere nell'esportazione diagnostica del job.
+- **Chat.** La chat eredita automaticamente la configurazione MCP del tuo progetto, quindi i plugin installati sono disponibili anche lì.
+- **Setup.** I plugin vengono ignorati mentre un progetto è ancora in fase di configurazione — entrano in gioco una volta che il progetto è pronto.
+
+## Note sui provider
+
+I plugin sono consapevoli del provider. Serena e i plugin MCP analoghi si risolvono per i provider che registrano l'MCP tramite il `.mcp.json` del progetto (Claude e Gemini). Per i progetti Codex, i server MCP vengono gestiti invece tramite la configurazione globale di Codex, quindi le voci dei plugin in **Integrazioni** vengono filtrate di conseguenza. La scheda Jira nelle Integrazioni è indipendente dal provider e viene mostrata a tutti — consulta la guida di Jira.
+
+## File riservati
+
+I plugin gestiscono un insieme ristretto e ben definito di file nel tuo progetto: il tuo `.mcp.json` (unito in modo chirurgico), un po' di stato sotto `.specrails/plugins/` e i frammenti agente specifici per plugin in `.claude/agents/custom-<plugin>.md`. Questi sono asset di team committabili, se vuoi condividere un'integrazione con i tuoi colleghi — l'app non li sovrascrive mai ciecamente.

package/docs/guide/it/integrations/3-jira-integration.md

@@ -0,0 +1,71 @@
+# Integrazione Jira
+
+Vuoi che le tue spec vivano su una vera **board Jira** invece che dentro Specrails? L'integrazione Jira appoggia le spec di un progetto ai ticket Jira, mantiene gli stati sincronizzati man mano che i rail vengono eseguiti e per il resto resta fuori dai piedi. Ogni progetto si sincronizza con la **propria** board Jira.
+
+## Come funziona (in breve)
+
+Specrails funge da **livello di sincronizzazione** tra Jira e il tuo progetto. L'idea di fondo: il tuo archivio locale delle spec resta l'elemento canonico che la pipeline legge, e Specrails è responsabile di mantenerlo allineato con Jira.
+
+- Quando avvii un rail, Specrails sposta il ticket Jira collegato su **In corso**.
+- Quando un job termina, Specrails fa transitare il ticket (su **Fatto**, o di nuovo su **Da fare** se è fallito) e pubblica un commento di completamento con l'id del job, il costo e la durata.
+- Periodicamente Specrails interroga (**polling**) Jira per le modifiche apportate da chiunque sulla board e le riporta nelle tue spec.
+
+Tutti i riscritti verso Jira passano attraverso un outbox durevole e resistente ai crash, così un'interruzione momentanea di Jira non blocca mai un job — l'aggiornamento viene semplicemente ritentato.
+
+## Connettere una board
+
+Ti connetti dalla pagina **Impostazioni** di un progetto (c'è anche un passo facoltativo "Configura Jira" alla fine della procedura guidata di Add Project). La procedura guidata di connessione ti accompagna passo dopo passo:
+
+1. **Prova** — inserisci l'URL e le credenziali di Jira, e Specrails verifica la connessione.
+2. **Scegli un progetto** — scegli con quale progetto Jira sincronizzarti.
+3. **Mappa degli stati (facoltativo)** — associa gli stati del tuo workflow Jira agli stati di Specrails se il rilevamento automatico ha bisogno di un aiuto (più sotto).
+4. **Connetti** — fatto. Le tue spec ora rispecchiano quella board.
+
+### Autenticazione
+
+Questa versione usa l'autenticazione con **incollatura del token** — veloce, sul dispositivo e senza alcun backend coinvolto:
+
+- **Jira Cloud:** l'email del tuo account più un token API.
+- **Jira Data Center / Server:** un Personal Access Token (PAT).
+
+Il tuo token viene memorizzato **cifrato sulla tua macchina** e non la lascia mai. L'app mostra soltanto se un token è presente, mai il token stesso.
+
+## Mappatura degli stati
+
+La parte più delicata di qualsiasi sincronizzazione con Jira è far corrispondere il *tuo* workflow agli stati semplici di Specrails (Da fare / In corso / Fatto, più le varianti di annullamento e di rilascio). Specrails risolve la cosa su due livelli:
+
+1. **La tua mappa degli stati esplicita**, se ne hai impostata una nella procedura guidata — vince sempre.
+2. **Il rilevamento automatico** dalla categoria di ciascuno stato (nuovo / in corso / fatto) più un'associazione intelligente per gli stati di tipo annullamento e rilascio.
+
+Quando deve spostare un ticket attraverso un workflow con transizioni vincolate, trova un percorso valido passo dopo passo e compila lungo il tragitto eventuali campi obbligatori (come una risoluzione). Se uno stato è davvero irraggiungibile, l'operazione viene parcheggiata come dead-letter e ti viene segnalata invece di fallire silenziosamente — vedrai un indicatore **degradato** e potrai riprovare.
+
+## Hot-swap: attivala e disattivala in tutta sicurezza
+
+Il collegamento Jira è **per spec**, catturato nel momento in cui avvii un rail — non un interruttore globale, tutto-o-niente, sulla board. Questo lo rende sicuro da attivare e disattivare:
+
+- **Abilitare o disabilitare** l'integrazione non riassegna mai le tue spec esistenti.
+- **Disconnettere** riporta il tuo progetto al normale comportamento con spec locali.
+- Le spec che hanno già un collegamento Jira mantengono il loro riscritto; quelle che non lo hanno restano intatte.
+
+Così puoi sperimentare liberamente — attivala, esegui qualche rail, disattivala — senza scombussolare la tua board o le tue spec locali.
+
+## Il giorno per giorno
+
+Una volta connesso, la pagina Impostazioni del progetto mostra una **scheda di connessione** dove puoi:
+
+- **Sincronizza ora** — forza un polling immediato invece di aspettare il timer.
+- **Riprova i dead-letter** — riesegui qualsiasi riscritto rimasto bloccato.
+- **Interruttore hot-swap** — metti temporaneamente in pausa/riprendi l'integrazione.
+- **Disconnetti** — stacca la board in modo pulito.
+
+Le spec appoggiate a Jira mostrano un **badge con la chiave Jira** (come `PROJ-123`) sulla loro scheda, e cliccandolo si torna al ticket. Riceverai anche piccole notifiche quando una sincronizzazione si completa, quando un token di autenticazione scade (così puoi rinnovarlo) o quando l'integrazione entra in stato degradato.
+
+## Cose da tenere a mente
+
+- **Polling, non webhook.** Poiché Specrails gira in locale, interroga Jira per le modifiche in arrivo invece di ricevere notifiche push. Le modifiche compaiono entro l'intervallo di polling, non istantaneamente.
+- **Una board per progetto.** Progetti diversi possono sincronizzarsi con board diverse; un singolo progetto si sincronizza con esattamente una board.
+- **L'ultima scrittura vince in caso di conflitti** per il caso raro in cui due schede modificano contemporaneamente la stessa bozza.
+
+## Disattivarla
+
+Se in qualsiasi momento vuoi tornare completamente indietro, basta **Disconnettere** dalle Impostazioni. Le tue spec tornano al comportamento solo-locale e i metadati Jira semplicemente restano inutilizzati — niente viene distrutto.

package/docs/guide/it/integrations/4-mobile-companion.md

@@ -0,0 +1,38 @@
+# L'app companion per il telefono
+
+Specrails ha un'app companion per il telefono così puoi tenere d'occhio i tuoi rail anche quando sei lontano dalla scrivania — guarda i job in esecuzione, vedili terminare e resta aggiornato senza dover stare davanti alla dashboard.
+
+## A cosa serve
+
+La companion è una superficie di **monitoraggio**. Si connette alla tua app desktop Specrails in esecuzione tramite la rete locale e rispecchia in tempo reale l'attività di progetti e job sul tuo telefono. Pensala come una finestra a colpo d'occhio sugli stessi rail che altrimenti seguiresti dalla dashboard.
+
+## Abbinare il telefono
+
+L'abbinamento ruota attorno a un **codice QR**, così non devi digitare nulla di scomodo:
+
+1. Assicurati che la tua app desktop Specrails sia in esecuzione e che il telefono sia sulla **stessa rete locale** (stessa Wi-Fi).
+2. Nell'app desktop, apri la schermata di abbinamento per mostrare un codice QR.
+3. Nell'app companion sul telefono, scansiona quel codice.
+4. Il telefono individua l'app desktop sulla rete e si connette.
+
+Da quel momento in poi la companion mantiene una connessione in tempo reale e trasmette gli elenchi dei progetti e gli aggiornamenti dei job man mano che avvengono.
+
+## Come funziona la connessione
+
+L'app desktop si annuncia sulla tua rete locale così il telefono può trovarla, e il codice QR contiene i dettagli di cui il telefono ha bisogno per connettersi in modo sicuro. Tutto resta sulla tua rete locale — la companion dialoga direttamente con la tua macchina, non attraverso alcun servizio cloud.
+
+Poiché si basa sulla rete locale, i due dispositivi devono potersi raggiungere a vicenda. Se l'abbinamento non riesce:
+
+- Verifica che entrambi i dispositivi siano sulla **stessa Wi-Fi** (e che la rete non isoli i client l'uno dall'altro).
+- Assicurati che l'app desktop sia **in esecuzione** quando esegui la scansione.
+- Riapri la schermata di abbinamento per aggiornare il codice QR e prova a scansionare di nuovo.
+
+## Cosa vedrai
+
+Una volta abbinata, la companion mostra i tuoi progetti e la loro attività di job in tempo reale, così ottieni gli stessi aggiornamenti dei rail in tempo reale che confluiscono nella dashboard desktop — inviati al tuo telefono nel momento in cui avvengono. È il modo più semplice per sapere nell'istante in cui un rail di lunga durata si conclude.
+
+## Buono a sapersi
+
+- **Prima il monitoraggio.** La companion è pensata per tenere d'occhio i rail, non per gestire l'intero flusso di lavoro desktop dal telefono.
+- **Solo in locale.** Nessun account, nessun relay cloud — la tua macchina e il tuo telefono, sulla tua rete.
+- **Tieni il desktop attivo.** La companion rispecchia un'app desktop in esecuzione; se la tua macchina va in sospensione o l'app si chiude, gli aggiornamenti in tempo reale si fermano finché non torna attiva.

package/docs/guide/it/pipeline/1-rails-and-jobs.md

@@ -0,0 +1,94 @@
+# Rail e job
+
+Hai le tue spec sulla board. È qui che si trasformano in codice. Un **rail** è la corsia che porta una spec attraverso l'intera pipeline — Architect → Developer → Reviewer → Ship — eseguendo veri agenti AI dentro la cartella del tuo progetto. Questa pagina spiega come avviare un rail, come funziona la coda dei job e come seguire il lavoro dal vivo mentre accade.
+
+## Cos'è un rail
+
+Immagina lo schermo diviso in due:
+
+```
+SpecsBoard (sinistra)       Rail (destra)
+─────────────────            ─────────────────
+#1 Login flow      ─┐
+#2 Webhook retry    │  trascina su
+#3 Cost limits      │ ────────────►   Rail 1   ▶ Play
+#4 Audit log        │
+                    └────────────►   Rail 2   ▶ Play
+```
+
+Un rail è una **corsia di esecuzione**. Trascini una scheda spec dalla SpecsBoard su un rail e poi premi **▶ Play**. Il rail avvia la pipeline e lavora la spec dall'inizio alla fine, direttamente nella cartella di lavoro del tuo progetto — modificando file, eseguendo test, tutto quanto.
+
+Puoi avere diversi rail per organizzare il lavoro in corsie con un nome (una per la feature su cui sei concentrato, un'altra in attesa dietro). Trovi più dettagli su multi-rail e batching in [Batch implement e multi-feature](batch-implement-and-multi-feature).
+
+## Avviare un rail su una spec
+
+1. **Trascina una scheda spec** dalla SpecsBoard su un rail. L'ID della spec compare nell'elenco di spec del rail. (Preferisci non trascinare? Usa il popover **Sposta su un rail** sulla scheda spec — mostra un pallino di stato per ogni rail, così non scarichi del lavoro su una corsia già occupata.)
+2. **Scegli una modalità** se vuoi qualcosa di diverso da quella predefinita — il controllo segmentato nell'intestazione del rail offre `Implement`, `Batch` e (solo per i rail Claude) `Ultra`.
+3. **Premi ▶ Play.**
+
+Tutto qui. Il rail avvia un processo CLI AI nel tuo progetto e dà il via alla pipeline.
+
+### Cosa c'è nell'intestazione di un rail
+
+| Controllo | Cosa fa |
+|---------|--------------|
+| **Pillola di stato** | `idle`, `running` o `failed`. Non esiste uno stato "completed" separato — un rail torna a `idle` quando il suo job termina senza errori. |
+| **Elenco spec** | Gli ID assegnati a questo rail. Trascinane altri dentro, oppure fuori per staccarli. |
+| **Controllo modalità** | `Implement` / `Batch` / `Ultra` — vedi la tabella più sotto. Viene salvato per ogni rail. |
+| **Selettore profilo** | Quale profilo agente viene eseguito (solo per i rail Claude). Compare solo quando il progetto ha almeno un profilo. |
+| **Selettore engine** | Quale provider installato esegue questo rail — Claude, Codex o Gemini. Viene mostrato solo quando il progetto ha più di un provider. Vedi [Scegliere un engine per ogni rail](picking-an-engine-per-rail). |
+| **▶ Play / ■ Stop** | Avvia o annulla. |
+
+### Le tre modalità di un rail
+
+| Modalità | Comando | Cosa fa |
+|------|---------|--------------|
+| **Implement** | `/specrails:implement` | Un unico job che copre tutte le spec sul rail. Esegue l'intera pipeline Architect → Developer → Reviewer → Ship. L'impostazione predefinita di tutti i giorni. |
+| **Batch** | `/specrails:batch-implement` | Un unico job che lavora le spec del rail in sequenza, in ondate consapevoli delle dipendenze. Ideale per più spec correlate. |
+| **Ultra** | Ultracode | Claude implementa ogni spec in autonomia, **bypassando** la pipeline. Un job indipendente per ogni spec. Solo Claude. |
+
+Ultra è la modalità a sé stante: salta la catena di agenti e affida a Claude la spec grezza, lasciandolo lavorare con i suoi strumenti nativi. È a finalità aperta, quindi premendo Play si apre prima una conferma, e un selettore di modello per rail ti permette di scegliere tra Haiku / Sonnet / Opus. Compare solo quando l'engine del rail è Claude.
+
+## La coda dei job
+
+Ogni volta che premi Play, l'esecuzione del rail diventa un **job**. La regola più importante da fare propria:
+
+> **Un job alla volta, per progetto.** Ogni progetto ha un'unica coda. All'interno di un progetto viene eseguito un solo job di rail alla volta — gli altri si mettono in coda dietro e partono automaticamente man mano che si liberano gli slot.
+
+Questo sorprende chi aggiunge tre rail aspettandosi che vadano in parallelo. Non succede — non all'interno dello stesso progetto. Aggiungere rail *organizza* il tuo lavoro in corsie; non fa sì che quelle corsie vadano in contemporanea.
+
+**Il vero parallelismo è tra progetti diversi.** Ogni progetto ha la sua coda indipendente, quindi un rail nel Progetto A e un rail nel Progetto B vengono eseguiti nello stesso momento senza contendersi le risorse. Vuoi più throughput? Apri più progetti.
+
+Non c'è una manopola globale di concorrenza da regolare. L'unico freno automatico è basato sul budget: se hai impostato un budget giornaliero (di progetto o per tutta l'app), la coda si mette automaticamente in pausa quando la spesa della giornata raggiunge il limite.
+
+## Seguire l'esecuzione
+
+Trovi ogni job in **Job**, nella barra laterale destra del progetto — un elenco di schede, dalla più recente. Ogni scheda mostra un badge di stato, il badge del profilo, un badge di priorità, la durata, il costo e il comando avviato. Sopra l'elenco:
+
+- **Chip di filtro per stato** — mostra solo i job in un determinato stato.
+- **Filtro per intervallo di date** — restringi a una finestra temporale.
+- **Confronta** — scegli due job e visualizzali fianco a fianco.
+
+Clicca su una scheda qualsiasi per aprire la **vista Dettaglio job**, dove vivono il log in streaming in tempo reale e le metriche live. È la pagina successiva: [La vista Dettaglio job](the-job-detail-view).
+
+## Annullare un job
+
+Clicca su **■ Stop** nell'intestazione del rail. L'app invia `SIGTERM` al sottoprocesso, attende **5 secondi** un'uscita pulita e poi gli invia `SIGKILL`. Niente resta avviato a metà.
+
+## Se un rail non parte
+
+Se scegli un engine la cui CLI non è installata sulla tua macchina, l'avvio **fallisce subito** invece di avviare un job difettoso — non viene avviato nulla. Installa la CLI del provider mancante ([Usare Codex](../integrations/using-codex), [Usare Gemini](../integrations/using-gemini)) e riprova ad avviare. Se mancano Claude o Codex compare un messaggio preciso "*<provider> CLI not found*"; se manca Gemini oggi viene mostrato un errore di avvio generico, ma il risultato è lo stesso.
+
+## Fermare tutto
+
+Se qualcosa sembra non andare:
+
+- **Un solo rail** — clicca su **■ Stop** nella sua intestazione.
+- **Pausa automatica sul budget** — imposta un budget giornaliero e la coda si mette in pausa da sola quando la spesa della giornata raggiunge il limite.
+- **Tutto** — chiudi l'app desktop, oppure esegui `specrails-desktop stop`.
+
+## Dove andare ora
+
+- [La vista Dettaglio job](the-job-detail-view) — fasi, metriche live, schede ticket.
+- [Batch implement e multi-feature](batch-implement-and-multi-feature) — esegui più spec insieme.
+- [Scegliere un engine per ogni rail](picking-an-engine-per-rail) — Claude vs Codex vs Gemini.

package/docs/guide/it/pipeline/2-the-job-detail-view.md

@@ -0,0 +1,90 @@
+# La vista Dettaglio job
+
+Clicca su una qualsiasi scheda job nella pagina **Job** e arrivi qui: la cabina di pilotaggio di una singola esecuzione di rail. È costruita attorno a una promessa — **i numeri live che vedi sono reali, mai ipotesi.** Questa pagina ti accompagna tra le fasi, le metriche live e le schede ticket.
+
+## Il layout
+
+Due pannelli stanno sopra il log completo in streaming:
+
+```
+┌─────────────────────────────────────────────┐
+│  Intestazione di stato (icona · durata live · …) │
+├─────────────────────────────────────────────┤
+│  Intestazione ticket  ( #12  #14  #15 )     │
+├─────────────────────────────────────────────┤
+│                                             │
+│  Log in streaming (auto-scroll · ricerca · …) │
+│                                             │
+└─────────────────────────────────────────────┘
+```
+
+## Fasi della pipeline
+
+Per i job `Implement` e `Batch`, l'esecuzione attraversa le fasi definite dallo slash command — per impostazione predefinita:
+
+```
+Architect ──► Developer ──► Reviewer ──► Ship
+```
+
+Ogni fase è un agente specializzato che l'engine del rail invoca nella cartella del tuo progetto:
+
+| Fase | Agente | Cosa fa |
+|-------|-------|--------------|
+| **Architect** | `sr-architect` | Pianifica l'implementazione. |
+| **Developer** | `sr-developer` | Scrive il codice. |
+| **Reviewer** | `sr-reviewer` | Revisiona il risultato. |
+| **Ship** | (variabile) | Conclusione finale: test, commit, bozza di PR. |
+
+Quale agente gestisce ogni fase lo decide il **profilo agente** del progetto. Il trio di base (`sr-architect`, `sr-developer`, `sr-reviewer`) è sempre presente; le regole di routing in un profilo possono aggiungere agenti o cambiare quale di essi esegue una fase. La barra di avanzamento delle fasi compare solo quando il comando definisce effettivamente delle fasi — i job Ultracode (che bypassano la pipeline) non ne mostrano alcuna.
+
+## Metriche live — oneste per scelta
+
+L'intestazione di stato è il titolo principale. Mostra un'icona di stato, una riga di attività che descrive cosa sta facendo il job *in questo momento*, un conteggio dei passi compiuti e una riga di metriche:
+
+| Metrica | Quando vedi il valore reale |
+|--------|------------------------------|
+| **Durata** | **Live.** Un ticker da 1 secondo conta in avanti mentre il job è in esecuzione — è l'unico numero davvero live. |
+| **Turni** | Derivati in modo incrementale dagli eventi assistant in streaming man mano che arrivano. |
+| **Token** | Aggregati in modo incrementale dallo stesso stream (tollera gli eventi privi dei campi di utilizzo). |
+| **Costo** | Mostrato come `—` finché il job non termina, poi rivelato come l'autorevole `total_cost_usd`. |
+
+Il principio di progettazione: **nessun numero approssimato o stimato durante l'esecuzione.** La durata è reale perché è semplicemente un orologio. Turni e token vengono accumulati dall'attività realmente trasmessa in streaming. Il costo deliberatamente *non* viene stimato durante l'esecuzione — appare come in attesa e si risolve solo nel suo valore finale e autorevole quando il provider lo riporta all'uscita del job. Se un numero sembra in attesa, è intenzionale — ti viene mostrata la verità, non una proiezione.
+
+L'etichetta e l'icona dell'intestazione corrispondono allo stato del job, e il pannello viene mostrato per i job `running`, `completed` e `failed` allo stesso modo — così la vista di dettaglio di un job concluso mostra le stesse metriche congelate ai loro valori finali.
+
+## Le schede ticket
+
+L'**intestazione ticket** sta tra l'intestazione di stato e il log. È una scheda d'identità premium che mostra un chip per ogni spec toccata dal job — ricavati dal comando avviato, così riflette esattamente quali ticket riguardava questa esecuzione.
+
+- **2–3 ticket** — mostrati come elenco di chip.
+- **4 o più** — si comprimono in una modalità compatta `+ N more` con un chevron per espandere, così l'intestazione resta ordinata.
+
+Cliccando su un chip si apre il dettaglio di quella spec **sopra la pagina del job** — non perdi il segno né cambi pagina. È un modo rapido per rileggere cosa un job dovrebbe consegnare mentre lo guardi lavorare. (Sugli schermi in formato tablet puoi persino trascinare di lato una modale ticket per confrontare due spec fianco a fianco.)
+
+## Il log in streaming
+
+Sotto i pannelli c'è il log completo dell'esecuzione, trasmesso in tempo reale tramite WebSocket:
+
+- L'**auto-scroll** mantiene in vista l'output più recente (scorri verso l'alto e si mette in pausa così puoi leggere).
+- La **ricerca** per saltare a una frase.
+- **Copia** per prendere l'intero log.
+
+Questa è la verità grezza di ciò che l'AI sta facendo — ogni chiamata a uno strumento, ogni modifica a un file, ogni test eseguito.
+
+## Esportazione diagnostica
+
+Se la [telemetria](../settings/customizing) era abilitata per il job, nell'intestazione compare un pulsante **Esporta diagnostica**. Scarica uno ZIP che contiene:
+
+- `job-metadata.json` — comando, stato, profilo, plugin.
+- `telemetry.ndjson` — segnali OTLP/JSON non compressi.
+- `logs.txt` — il log completo in streaming.
+- `summary.md` — i punti salienti in formato leggibile.
+- `profile.json`, `plugins.json` — snapshot esatti di ciò che è stato eseguito (quando presenti).
+
+Comodo per condividere un'esecuzione con un collega, o per inviare una segnalazione di bug precisa.
+
+## Dove andare ora
+
+- [Rail e job](rails-and-jobs) — avvio e accodamento.
+- [Batch implement e multi-feature](batch-implement-and-multi-feature) — molte spec, ondate di dipendenze.
+- [Tracciare i costi](../analytics/tracking-cost) — trasforma i costi per job in analytics di progetto.

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

@@ -0,0 +1,78 @@
+# Batch implement e multi-feature
+
+Una spec alla volta va benissimo, ma molto del lavoro reale arriva a grappoli — una feature più i suoi test più la sua migrazione, oppure un backlog che vuoi smaltire in un'unica sessione. Questa pagina spiega come eseguire più spec insieme: la modalità Batch, le ondate di dipendenze e come la pipeline evita che il lavoro concorrente entri in collisione.
+
+## Eseguire più spec in una volta sola
+
+Il modo più semplice per eseguire un mucchio di spec da un unico rail è la modalità **Batch**:
+
+1. **Trascina tutte le spec** che vuoi su un singolo rail. Si accumulano nell'elenco di spec di quel rail.
+2. **Imposta la modalità del rail su Batch** (il controllo segmentato nell'intestazione del rail).
+3. **Premi ▶ Play.**
+
+Il rail avvia **un solo** job `/specrails:batch-implement` che lavora ogni spec assegnata. Monitoralo come qualsiasi altro job nella pagina Job — è un unico job che copre l'intero gruppo, non un job per ogni spec.
+
+Questo è importante per via della **coda a un job per progetto**. Dato che un progetto esegue un solo job di rail alla volta, la modalità Batch è anche il modo più pulito per *concatenare* un elenco di spec senza dover gestire più rail e aspettare che ciascuno si svuoti.
+
+### Implement vs Batch — quale modalità?
+
+| | **Implement** | **Batch** |
+|---|---|---|
+| Comando | `/specrails:implement` | `/specrails:batch-implement` |
+| Spec per job | Tutte sul rail, trattate come un'unica unità di lavoro | Tutte sul rail, lavorate **in sequenza** |
+| Ideale per | Una modifica strettamente accoppiata | Più feature distinte che vuoi smaltire in ordine |
+| Ordinamento | n/d | Ondate consapevoli delle dipendenze (vedi sotto) |
+
+Se le spec sono davvero un'unica modifica, usa **Implement**. Se sono un elenco di feature separate, usa **Batch** e lascia che le metta in sequenza.
+
+## Ondate di dipendenze
+
+La modalità Batch non si limita a eseguire le spec dall'alto verso il basso — calcola un **ordine di esecuzione consapevole delle dipendenze** e raggruppa le spec in *ondate*. L'orchestratore (`/specrails:batch-implement`) capisce quali spec dipendono da quali altre, poi le pianifica in modo che nulla parta prima del lavoro su cui si appoggia.
+
+Concettualmente:
+
+```
+Ondata 1:  #2 (modello dati)        ← nessuna dipendenza, parte per prima
+Ondata 2:  #4 (API sul modello)     ← attende #2
+           #5 (CLI sul modello)     ← attende #2
+Ondata 3:  #7 (docs su tutto)       ← attende #4 e #5
+```
+
+All'interno del job, le spec di ogni ondata vengono implementate prima che inizi l'ondata successiva. Non lo configuri a mano — l'orchestratore ricava le ondate dalle spec stesse. Guarda tutto svolgersi nella [vista Dettaglio job](the-job-detail-view): il log in streaming racconta su quale spec sta lavorando il batch, e l'intestazione ticket mostra ogni spec toccata dal job.
+
+## Isolamento worktree
+
+Quando più spec vengono implementate in un'unica esecuzione, la pipeline mantiene isolata ogni unità di lavoro, così che le modifiche concorrenti o sequenziali non si calpestino i file a vicenda. L'orchestratore del batch esegue l'implementazione di ogni spec nel suo contesto di lavoro pulito, poi integra i risultati — così una spec lasciata a metà non lascia mai il tuo tree in uno stato intermedio rotto visibile alla successiva.
+
+In pratica questo significa:
+
+- Ogni spec parte da una tabula rasa su cui implementare, invece di ereditare le modifiche ancora in corso della spec precedente.
+- Le revisioni e i passi di ship operano su uno snapshot coerente, non su un bersaglio in movimento.
+- Un fallimento in un'ondata viene contenuto — non corrompe in silenzio le spec già consegnate.
+
+L'app registra, per ogni job, esattamente quali file sono stati toccati e quale ticket li ha toccati (lo vedrai comparire come chip di provenance nella sezione **Code** e come elenco "File toccati da questo ticket" nella modale di dettaglio di ogni spec). È proprio questa attribuzione a renderti possibile fidarti di un'esecuzione multi-spec: puoi sempre risalire da una modifica a un file alla spec che l'ha causata.
+
+## Multi-feature tra progetti
+
+Se vuoi un vero parallelismo — due grandi feature che vengono costruite nello stesso momento — dividile **tra progetti diversi**, non tra rail nello stesso progetto. Ogni progetto ha la sua coda indipendente, quindi:
+
+```
+Progetto A   ▶ Rail che esegue la feature X   ┐
+                                              ├─ vengono eseguiti in contemporanea
+Progetto B   ▶ Rail che esegue la feature Y   ┘
+```
+
+Non c'è alcun limite globale di concorrenza né contesa tra progetti. Apri entrambi, avvia un rail in ciascuno e procedono insieme. L'unico freno condiviso è il tuo limite di budget, che mette in pausa le code per progetto o per tutta l'app quando la spesa della giornata raggiunge il limite.
+
+## Consigli per i batch grandi
+
+- **Raggruppa le spec correlate su un unico rail** prima di passare a Batch — le ondate di dipendenze vedono solo ciò che si trova su quel rail.
+- **Imposta un budget giornaliero** prima di un batch grande, così un'esecuzione inaspettatamente costosa va in pausa automatica invece di andare fuori controllo. Configuralo in [Budget](../settings/customizing).
+- **Usa il pulsante Confronta** nella pagina Job dopo l'esecuzione per mettere a confronto due batch fianco a fianco.
+- **Esporta una diagnostica** (se la telemetria era attiva) per ottenere lo snapshot esatto di profilo + plugin dell'intero batch.
+
+## Dove andare ora
+
+- [Rail e job](rails-and-jobs) — il modello della coda in dettaglio.
+- [La vista Dettaglio job](the-job-detail-view) — guarda un batch in esecuzione dal vivo.
+- [Scegliere un engine per ogni rail](picking-an-engine-per-rail) — nota che il Batch gira su qualsiasi provider; Ultra è solo Claude.

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

@@ -0,0 +1,60 @@
+# Scegliere un engine per ogni rail
+
+Specrails desktop tratta **Claude Code**, **Codex CLI** e **Gemini CLI** come engine di prima classe. Un progetto può averne installato uno, due o tutti e tre — e quando ne è presente più di uno, scegli quale engine esegue ogni rail. Questa pagina spiega il selettore di engine per rail e quando ricorrere a ciascuno.
+
+## Quando compare il selettore
+
+Il **selettore di engine** vive nell'intestazione del rail, proprio accanto al controllo della modalità. Viene mostrato solo quando il progetto ha installato **più di un** provider.
+
+> **I progetti con un solo provider si comportano in modo byte-identico.** Se un progetto ha un solo engine, non compare alcun selettore e nulla cambia nella selezione del provider — gira semplicemente su quell'engine. Il selettore è pensato esclusivamente per i progetti multi-provider.
+
+Quando compare, la tua scelta è **per rail e per avvio** — rail diversi possono usare engine diversi, e la tua scelta viene ricordata per ogni progetto (con default sull'engine primario del progetto).
+
+## Come scegliere un engine
+
+1. Assicurati che il selettore di engine del rail sia visibile (il progetto ha 2+ provider).
+2. Cliccaci sopra e scegli **Claude**, **Codex** o **Gemini**.
+3. Avvia il rail con **▶ Play**.
+
+L'engine selezionato esegue ogni fase della pipeline di quel rail. Se la CLI dell'engine scelto non è installata, l'avvio fallisce subito — non viene avviato nulla. Installa la CLI mancante e riprova.
+
+## In cosa è bravo ciascun engine
+
+Tutti e tre eseguono le pipeline standard **Implement** e **Batch**. Ecco una guida pratica alla scelta:
+
+| Engine | Scegli questo quando… | Note |
+|--------|--------------------|-------|
+| **Claude** | Vuoi l'intero set di funzionalità: profili agente, Ultracode, reportistica nativa dei costi, il supporto agli strumenti più ricco. L'impostazione predefinita per la maggior parte del lavoro. | L'unico engine che supporta i **profili agente**, **Ultracode** e alcune funzionalità delle spec esclusive di Claude (Contract Layer, SMASH). |
+| **Codex** | Preferisci la CLI Codex di OpenAI o vuoi confrontare le implementazioni tra provider diversi. | `codex` ≥ 0.128.0. Nessuna reportistica nativa dei costi — l'app ricava il costo dalla sua tabella prezzi. I profili non si applicano. |
+| **Gemini** | Vuoi la CLI Gemini di Google, telemetria nativa o un'esecuzione più economica per le spec di routine. | `gemini` ≥ 0.11.0 (imposta `GEMINI_API_KEY`). Telemetria OTLP nativa. I profili non si applicano. |
+
+### Le funzionalità esclusive di Claude
+
+Alcune cose funzionano solo sui rail Claude — scegli Claude se ne hai bisogno:
+
+- **Profili agente** — routing del modello per ogni agente. Sui rail Codex o Gemini l'esecuzione usa sempre la modalità legacy e qualsiasi profilo selezionato viene **ignorato**. Il selettore di profilo è nascosto per gli engine diversi da Claude.
+- **Ultracode (modalità `Ultra`)** — la modalità autonoma che bypassa la pipeline. Il segmento `Ultra` e il suo selettore di modello Haiku/Sonnet/Opus compaiono solo quando l'engine del rail è Claude.
+- **Contract Layer e SMASH** — funzionalità di affinamento delle spec esclusive di Claude (sono opzioni di Add Spec, non opzioni del rail, ma vale lo stesso vincolo).
+
+Se un progetto mescola engine, la barra laterale destra mostra solo le sezioni supportate da **ogni** provider installato — quindi la sezione **Agenti** sparisce del tutto su un progetto che include un provider diverso da Claude, perché i profili sono specifici di Claude.
+
+## Un flusso di lavoro pratico
+
+I progetti multi-provider danno il meglio quando vuoi **confrontare** o **ottimizzare i costi**:
+
+- **Confronta le implementazioni.** Metti la stessa spec su due rail, imposta uno su Claude e uno su Codex, avviali entrambi (su progetti diversi, oppure uno dopo l'altro nella coda dello stesso progetto), poi usa il pulsante **Confronta** nella pagina Job per mettere a confronto i risultati.
+- **Ottimizza i costi per spec.** Esegui le spec ad alto rischio su Claude con un profilo `max`; esegui le spec di pulizia di routine su Gemini per risparmiare. Filtra `/analytics` per engine per vedere la ripartizione.
+- **Imposta un default sensato.** Imposta l'engine che usi più spesso come primario del progetto, così i rail partono da quello, e cambia per ogni rail solo quando una spec specifica vuole un engine diverso.
+
+## Cose da tenere a mente
+
+- **La selezione del provider è immutabile dopo la creazione del progetto** (v1). Scegli i provider installati quando aggiungi il progetto; non c'è alcun interruttore nelle Impostazioni per aggiungerne o rimuoverne uno in seguito.
+- **Il costo viene sempre tracciato**, anche per gli engine privi di reportistica nativa dei costi — l'app ripiega su una tabella prezzi, così anche le esecuzioni Codex e Gemini compaiono in [analytics](../analytics/tracking-cost).
+- **Il pulsante "Open AI CLI" del terminale** offre anch'esso un selettore di provider sui progetti multi-provider, se preferisci pilotare una CLI a mano.
+
+## Dove andare ora
+
+- [Usare Codex](../integrations/using-codex) — installazione e accesso.
+- [Usare Gemini](../integrations/using-gemini) — installazione, `GEMINI_API_KEY`, telemetria.
+- [Rail e job](rails-and-jobs) — la coda e il flusso di avvio.
+- [Tracciare i costi](../analytics/tracking-cost) — ripartizione dei costi per engine.

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

@@ -0,0 +1,37 @@
+# Temi
+
+Dai a Specrails l'aspetto che preferisci. L'app include cinque temi rifiniti a mano tra cui passare all'istante — senza riavvii, senza ricompilazioni, senza niente da configurare.
+
+## I cinque temi integrati
+
+| Tema | Atmosfera |
+| --- | --- |
+| **Specrails** | Quello predefinito. Equilibrato, sobrio, in linea con il brand. |
+| **Dracula** | Il classico viola scuro. Riposante per gli occhi di notte. |
+| **Aurora Light** | Un tema chiaro luminoso e arioso per lavorare di giorno. |
+| **Obsidian Dark** | Modalità scura profonda e ad alto contrasto. |
+| **Matrix** | Verde su nero, per quando vuoi sentirti dentro il mainframe. |
+
+## Come cambiarlo
+
+1. Apri le **Impostazioni** (la finestra delle impostazioni globali dell'app).
+2. Vai alla sezione **Aspetto**.
+3. Scegli un tema. Si applica subito a tutta l'app.
+
+Tutto qui. La modifica ha effetto nell'istante in cui clicchi — l'interfaccia si riveste dal vivo.
+
+## Dove si applica
+
+La scelta del tema è **valida per tutta l'app**, non per singolo progetto. Ogni progetto, ogni pagina, ogni pannello segue lo stesso tema. E raggiunge anche posti che forse non ti aspetti:
+
+- **Il pannello terminale** si ricolora dal vivo, mantenendo intatti lo scrollback e qualsiasi sessione di shell in corso.
+- **I grafici** della pagina Analytics si ritingono di conseguenza.
+- **L'evidenziazione della sintassi del codice** nel visualizzatore Code segue anch'essa il tema.
+
+## Ricorda la tua scelta
+
+La tua selezione viene salvata insieme all'app, quindi resta anche dopo i riavvii. Per evitare quel breve lampo dei colori sbagliati quando l'app si apre, Specrails applica il tema salvato ancora prima che l'interfaccia finisca di caricarsi — così quello che vedi è già corretto fin dal primo fotogramma.
+
+## Una nota per i curiosi
+
+I temi sono costruiti su un piccolo insieme di ruoli cromatici semantici (un colore "accent", un colore "surface" e così via) anziché su tonalità fisse e codificate a mano. È per questo che aggiungere il tema successivo è semplice ed è per questo che ogni tema resta coerente al suo interno — ciascuno si limita a rimappare quei ruoli. Non devi pensare a nulla di tutto questo per usarlo; è semplicemente il motivo per cui il theming risulta così fluido.

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

@@ -0,0 +1,39 @@
+# Lingua
+
+Specrails parla la tua lingua. L'interfaccia è interamente tradotta in otto lingue e, per impostazione predefinita, segue la lingua impostata sul tuo computer — così per la maggior parte delle persone appare già nella lingua giusta al primo avvio.
+
+## Lingue supportate
+
+- English
+- Español (Spagnolo)
+- Français (Francese)
+- Deutsch (Tedesco)
+- Português (Portoghese)
+- Italiano
+- 中文 (Cinese)
+- 日本語 (Giapponese)
+
+## Parte nella lingua del tuo sistema operativo
+
+La prima volta che apri Specrails, l'app guarda le preferenze di lingua del tuo sistema operativo e le abbina alla lingua supportata più vicina. Se il tuo Mac o PC è impostato in spagnolo, vedrai lo spagnolo. Se è impostato su una variante regionale (come `es-ES` o `zh-Hans-CN`), Specrails lo mappa automaticamente sulla lingua di base corretta.
+
+Non devi fare nulla — e se non tocchi mai l'impostazione della lingua, Specrails continua a seguire il tuo sistema operativo. Cambi la lingua del computer in seguito? Specrails si adegua di conseguenza.
+
+## Scegliere la lingua da te
+
+Vuoi qualcosa di diverso dalla lingua predefinita del sistema? Scegliela esplicitamente:
+
+1. Apri le **Impostazioni**.
+2. Vai alla sezione **Lingua**.
+3. Scegli la tua lingua.
+
+Il cambio è **istantaneo** — l'intera interfaccia viene ridisegnata nella nuova lingua senza riavvii. Una volta fatta una scelta esplicita, Specrails la ricorda e smette di seguire il sistema operativo, così la tua preferenza viene rispettata ogni volta che apri l'app.
+
+## Cosa viene tradotto
+
+Tutto ciò che leggi nell'interfaccia — pulsanti, etichette, messaggi di stato, titoli delle pagine, finestre di dialogo. Anche le date si adattano alla lingua scelta, quindi sono formattate secondo le convenzioni di quella lingua.
+
+## Buono a sapersi
+
+- **L'inglese è la lingua di partenza.** Se una funzionalità nuova di zecca esce prima che la sua traduzione sia pronta, potresti vedere brevemente qua e là un'etichetta in inglese — verrà tradotta in un aggiornamento successivo.
+- La scelta della lingua è **valida per tutta l'app**, identica su tutti i tuoi progetti.

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

@@ -0,0 +1,46 @@
+# Telemetria della pipeline e diagnostica
+
+Quando un job della pipeline non va come ti aspettavi, la telemetria ti offre un resoconto dettagliato e dietro le quinte di ciò che la AI CLI ha realmente fatto. È **disattivata per impostazione predefinita** e completamente opzionale, per ogni progetto — attivala solo quando ti serve.
+
+## Cos'è
+
+La telemetria cattura segnali diagnostici strutturati (traces, metriche e log) emessi dalla AI CLI mentre esegue un job della pipeline. Pensala come una scatola nera per le tue esecuzioni della pipeline: tempistiche, uso dei token e attività passo dopo passo, catturati localmente così da poter ispezionare un job a posteriori.
+
+È costruita su **OpenTelemetry**, un formato aperto e standard — quindi i dati non restano rinchiusi in una scatola proprietaria.
+
+## Come attivarla
+
+La telemetria si configura **per singolo progetto**:
+
+1. Apri la pagina **Impostazioni** del progetto (la route delle impostazioni di progetto).
+2. Trova l'interruttore **Telemetria della pipeline**.
+3. Attivalo.
+
+Da quel momento in poi, i job della pipeline in quel progetto registrano la telemetria. Gli altri progetti non ne sono toccati — ciascun progetto decide per conto suo.
+
+### Cosa viene coperto
+
+La telemetria si applica ai **job della pipeline** (le esecuzioni dei rail Architect → Developer → Reviewer → Ship messi in coda). Le sessioni interattive come la chat e il wizard di setup sono lasciate fuori di proposito — la telemetria è pensata per le esecuzioni ripetibili e ispezionabili della pipeline, non per le conversazioni occasionali.
+
+## Dove vivono i dati
+
+Tutto resta sulla tua macchina, sotto la tua home directory (`~/.specrails/`) — mai nel tuo repository. Le registrazioni grezze sono salvate in forma compressa accanto al loro job e, dopo una settimana, quelle più vecchie vengono automaticamente condensate in riassunti compatti per mantenere tutto in ordine. Non devi mai gestire nulla di tutto questo a mano.
+
+## Esportare un bundle diagnostico
+
+La cosa più utile che la telemetria sblocca è l'**export diagnostico** — un singolo ZIP che racchiude tutto ciò che riguarda un job, per il troubleshooting o per condividerlo.
+
+Quando un job ha la telemetria registrata, sulla sua card compare un **pulsante di esportazione**. Cliccalo per scaricare uno ZIP contenente:
+
+- **`job-metadata.json`** — l'identità e i parametri del job
+- **`telemetry.ndjson`** — i segnali grezzi registrati
+- **`logs.txt`** — l'output di log catturato
+- **`summary.md`** — un riassunto leggibile dell'esecuzione
+
+Se il progetto usa plugin, il bundle include anche uno snapshot di quali plugin erano attivi per quel job.
+
+Questo è il bundle da prendere quando vuoi capire un'esecuzione complicata, conservare una traccia o passare i dettagli a qualcuno che ti aiuta con il debug.
+
+## Come disattivarla
+
+Riporta l'interruttore su off in qualsiasi momento. I nuovi job smettono di registrare immediatamente. Tutto ciò che è già stato catturato resta su disco finché non viene compattato o non rimuovi il progetto — niente viene inviato da nessuna parte né perso alle tue spalle.