specrails-desktop 2.64.2 → 2.65.0

package/docs/guide/it/integrations/8-flow-mode.md

@@ -0,0 +1,69 @@
+# Flow: prima costruisci, poi la spec {#flow-mode}
+
+Flow è un modo di costruire con un agente quando non sai ancora esattamente cosa vuoi. Parli con l’agente nella tua missione, lui scrive ed esegue codice reale sul suo branch del Flow (una copia separata del tuo progetto) e, quando il risultato è quello giusto, premi **Affida**: un rail prende le tue modifiche, ricava la spec ed esegue la verifica, la revisione e la consegna di sempre.
+
+Implement serve a delegare un lavoro che sai già descrivere. Flow serve a scoprirlo.
+
+## Come inizia un Flow
+
+Non devi mai chiedere Flow per nome. Quando descrivi qualcosa di esplorativo o visivo («voglio provare…», «non so come dovrebbe apparire»), la missione mostra una scheda con due strade:
+
+- **Flow**: costruirlo insieme ora; la spec arriva alla fine.
+- **Spec + Implement**: concordare prima una spec, poi delegarla a un rail.
+
+Le due strade hanno lo stesso peso e compaiono sempre nello stesso ordine: nessuna è consigliata, scegli tu. In **Perché l’agente lo chiede** l’agente spiega in una frase cosa lo ha spinto a chiedere, e non insisterà qualunque strada tu scelga o se premi **Non ora**.
+
+Scegliendo Flow si apre una conferma: Specrails crea una copia separata del progetto su un branch del Flow tutto suo, dove l’agente può scrivere codice, e il tuo branch principale non viene toccato. Premi **Avvia Flow**. Sulla board compare una spec provvisoria con l’etichetta **In Flow** (cliccala per tornare alla missione).
+
+Se il tuo Specrails Core non può ancora eseguire Flow, Avvia è disattivato e la scheda elenca cosa manca. Di solito basta aggiornare Specrails Core.
+
+## Avviare un Flow da una spec esistente
+
+Qualsiasi spec si può costruire in Flow, non solo una nuova idea. Flow e Implement restano due modi equivalenti di lavorarci:
+
+- nella board, fai clic destro su una spec e scegli **Avvia in Flow** (accanto al trascinarla su un rail); nel dettaglio della spec, **Avvia in Flow** è accanto a **Sposta su rail**;
+- in una missione, quando chiedi di implementare una spec senza nominare un rail, l’agente mostra la stessa scheda a due percorsi per quella spec: **Flow** ci lavora con te, **Spec + Implement** la avvia su un rail;
+- una scheda di avvio su rail per una sola spec offre anche **Avvia in Flow** accanto al suo avvio.
+
+La spec stessa diventa **In Flow**: non viene creata nessuna spec segnaposto e il primo turno dell’agente riceve la spec (criteri di accettazione, Contract Layer, esclusioni e addenda aperti). Avviato dalla board, il Flow si apre nella missione della spec oppure in una nuova missione con il nome della spec. In un progetto con più repository Git, quando la spec non ne indica esattamente uno, una piccola finestra chiede prima dove eseguire il Flow: sono elencati solo i repository Git, è preselezionato il repository della spec (altrimenti il principale) e le frecce cambiano la scelta. **Avvia in Flow** è disattivato, con il motivo al passaggio del mouse, quando la spec è già in Flow, completata o annullata, si trova su un rail o Flow non è disponibile.
+
+**Scarta** restituisce la spec esattamente com’era, con il suo stato precedente: la tua spec non viene mai eliminata. Alla consegna del Flow, la spec viene riscritta da ciò che è stato costruito e prima il suo testo originale resta come commento, **Original spec before Flow**, così non si perde nulla. Una spec già collegata a Jira aggiorna lo stesso issue e lo porta allo stato associato alla revisione; non viene creato un secondo issue.
+
+## Durante il Flow
+
+La modalità Flow è nominata dove guardi, con il suo colore di Flow: il compositore mostra un chip **Flow** accanto a quello dell’autonomia e il suggerimento *Di’ all’agente cosa cambiare in questo Flow…*; il titolo della missione indica **In Flow**, così come la sua riga nell’elenco delle missioni. La conversazione segna dove sei entrato e uscito da Flow, e le risposte dell’agente scritte in Flow hanno un piccolo segno **Flow** accanto all’ora.
+
+La striscia subito sopra il compositore mostra il Flow in una riga breve: il suo stato, **Flow · 7 file**, **Sospendi Flow** e l’azione principale, **Affida**. Quando un’azione non è disponibile (il Flow sta ancora salvando, è in corso un’altra azione), passandoci sopra si legge perché. Apri la riga con la sua freccia, come qualsiasi altra esecuzione, per vedere il resto:
+
+- il **branch** (clic per copiarne il nome), le **modifiche** con le righe aggiunte e rimosse (clic per elencare ogni file modificato con il suo stato e i +/−) e il **costo finora** come fatturato dal provider. Mostra `—` finché un turno non ha un costo comunicato, mai una stima; un `*` segnala un totale che esclude turni senza prezzo, con una nota che dice quanti;
+- **Anteprima** mentre l’app del Flow è in esecuzione (vedi sotto);
+- **Scarta**, in disparte, elimina le modifiche del Flow, il suo branch e la spec provvisoria. La conferma elenca cosa perdi: i file modificati con i loro +/−, il branch e la spec.
+
+**Sospendi Flow** ferma l’agente e conserva le tue modifiche e la spec. La riga mostra quindi **Riprendi Flow**.
+
+Puoi scrivere mentre l’agente lavora: in Flow il tuo messaggio **interrompe** il passo in corso (il pulsante di invio diventa un fulmine) e l’agente prosegue subito con le nuove informazioni. Finché il Flow è aperto, la striscia git sotto il compositore si fa da parte: il pannello del Flow mostra già il suo branch.
+
+## Prova l’app
+
+L’agente di Flow esegue da solo il typecheck e i test per controllare il suo lavoro. Quando c’è qualcosa da provare, chiede con tre scelte: **Start the app**, **Start and expose on the local network** o **Not now**. Esporla ti permette di aprire l’app da un telefono sulla stessa Wi-Fi o VPN, e chiunque su quella rete può raggiungerla.
+
+Quando l’app è in ascolto, l’agente ti dà i suoi indirizzi come link e il pannello del Flow mostra **Anteprima** con un punto verde: apre l’app nel browser. Il suo menu ha l’indirizzo di rete e **Arresta app**. L’app gira dalla copia del Flow, mai dal tuo checkout principale, e Specrails la arresta quando metti in pausa, scarti o consegni il Flow.
+
+## Affida {#flow-hand-off}
+
+Quando il risultato ti convince, premi **Affida**. La riga indica **Pronto a diventare una PR** e apre una sola riga sopra: *Rail 2 trasformerà i tuoi 7 file modificati in una PR revisionata. Se fallisce, il tuo lavoro è al sicuro.* Premi **Lancia**, oppure **Non ancora** per tornare al Flow; **Esc** equivale a **Non ancora**; un clic altrove si limita a ripiegare la riga, che resta su **Pronto a diventare una PR** con **Lancia**. Se il motore della conversazione non può eseguire l’affidamento su questo computer, una nota subito sotto la riga lo dice e si usa il motore predefinito del rail.
+
+Rail, motore, modello e sforzo sono già scelti per te (un rail libero e il motore della tua conversazione). Per cambiarli, apri **Cambia impostazioni**; lì vedi anche cosa è cambiato. Il costo finora è sulla riga principale. Le tue scelte restano se premi **Non ancora** e affidi di nuovo più tardi. Durante l’avvio la striscia mostra il lancio senza vuoti e poi segue l’esecuzione passo per passo. Se si raggiunge il limite di revisione o un budget, la riga lo dice e non parte nulla. Se l’esecuzione non compare entro 45 secondi, la striscia smette di girare e mostra **Affidamento a Rail 2 ancora in corso…** con **Aggiorna**, che ricontrolla e continua ad attendere finché l’esecuzione non compare.
+
+Il rail ricava la spec e la sua modifica della spec da ciò che hai costruito, la verifica e la revisiona, e la scheda di consegna compare nella missione come per qualsiasi esecuzione.
+
+Se l’esecuzione fallisce per un motivo tecnico, il lavoro torna da solo in questo Flow, intatto: la scheda dice con parole semplici cosa è fallito (i codici restano in **Dettagli tecnici**) e l’agente riceve l’errore e lo spiega. Se la revisione chiede modifiche, la scheda offre **Torna in Flow** o **Rilancia**. Quando la consegna si conclude, la missione chiude il Flow con un riepilogo: la pull request, la spec riscritta da ciò che hai costruito, la modifica della spec archiviata e il ticket Jira, se c’è.
+
+## Buono a sapersi
+
+- Flow scrive solo sul suo branch. Fuori da Flow le missioni restano in sola lettura.
+- Un Flow per missione alla volta. La pausa sopravvive al riavvio dell’app.
+- Se la copia del progetto del Flow scompare, il Flow viene segnato come **va controllato** (per informazione, niente da decidere) e non si cancella nulla.
+- La striscia non cambia mai l’esecuzione che stai guardando. Se un’altra inizia ad aver bisogno di te nel frattempo, il suo nome nel selettore della striscia dice **ti aspetta**.
+- Jira non riceve nulla mentre sei in Flow né se lo scarti.
+- Il costo di Flow compare in Analisi come superficie a sé, **Flow**, e nel blocco delle missioni dell’agente.

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

@@ -38,13 +38,14 @@ Tutto qui. Il rail avvia un processo CLI AI nel contesto di esecuzione corretto
 | **Selettore engine** | Quale provider esegue il rail — Claude o Codex. |
 | **▶ Play / ■ Stop** | Avvia o annulla. |
 
-### Cosa esegue un rail: i Loop
+### Cosa esegue un rail: i Loop {#rail-loops}
 
 Un rail esegue un **Loop** — la ricetta del lavoro. Due loop sono **integrati** e coprono i casi più comuni:
 
 | Loop integrato | 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. |
+| **Freestyle** | Freestyle | Il provider del rail implementa ogni spec in autonomia, **saltando** la pipeline; poi la verifica e il Loop Decider la rifiniscono finché tutto è verde. Un'esecuzione indipendente per spec. Funziona con Claude, Codex, Gemini, Kimi e gli engine locali; la chat interattiva nel job è solo per Claude. |
 
 Per eseguire più spec, metti quelle correlate (fino a 3) su un unico rail — `Implement` le esegue come un solo job aggregato — oppure distribuisci le spec indipendenti su più rail: ogni rail con git gira in parallelo nel proprio worktree isolato.
 
@@ -86,6 +87,25 @@ Se qualcosa sembra non andare:
 - **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`.
 
+## Integrare in locale con modifiche non committate
+
+**Integra in locale** unisce una consegna approvata nel tuo branch di integrazione (ad esempio `main`) su questo computer, senza PR. Non serve un checkout pulito:
+
+- Le modifiche non committate che non toccano i file consegnati restano dove sono.
+- Se le tue modifiche toccano gli stessi file, Specrails le salva in un git stash chiamato `specrails: before integrating #N (…)`, integra e le rimette al loro posto. La notifica dice *Ho salvato le tue modifiche locali, integrato #N e le ho ripristinate.*
+- Se rimetterle va in conflitto con il codice integrato, Specrails lascia il branch esattamente come integrato e **conserva lo stash**: non si perde nulla. La scheda mostra *Le tue modifiche locali sono salvate in uno stash* con i file in conflitto, **Ripristina le mie modifiche** (nuovo tentativo, ad esempio dopo aver cambiato il codice) e il nome dello stash da copiare. Poi Specrails le ripristina da solo su un nuovo branch `specrails/restore-local-<id>` in un worktree separato: se lì si applicano senza conflitti, fa commit; altrimenti un risolutore di conflitti IA lavora solo dentro quel worktree, mantenendo la tua intenzione e il codice integrato, e Specrails fa commit del risultato. La scheda elenca i file ripristinati; **Riportale su <branch>** le porta sul tuo branch (solo allora lo stash viene eliminato) e **Scarta il branch ripristinato** rimuove il branch e conserva lo stash. Una missione viene solo informata; non deve mai eseguire nulla. Le skill e i comandi OpenSpec generati da Specrails (ad esempio `.claude/skills/openspec-*/SKILL.md`) non contano come tue modifiche: in caso di conflitto mantengono la versione integrata.
+- I file ignorati non vengono mai messi nello stash: se uno di essi entra in conflitto con la consegna, Specrails ti chiede di spostarlo prima.
+- Se l'app si ferma tra il salvataggio e il ripristino, ripristina le tue modifiche alla successiva apertura del progetto (solo se è ancora attivo lo stesso branch).
+
+## Previsione di tempo e costo {#launch-forecast}
+
+Prima di premere Avvia, un rail può mostrare quanto durano di solito le esecuzioni come questa e, quando ha senso, quanto costano di solito, ad esempio *Di solito 6–9 min · $2–4 per esecuzioni come questa*.
+
+L’intervallo è la metà centrale della tua cronologia: dal 25º al 75º percentile delle esecuzioni completate in questo progetto con lo stesso loop o comando e lo stesso motore. Servono almeno 5 esecuzioni confrontabili. Fino ad allora la riga dice *Cronologia ancora insufficiente* invece di tirare a indovinare. Contano solo i costi comunicati dal provider; i costi stimati restano fuori. È una stima, mai un addebito.
+
+L’importo in dollari compare solo quando si sa che il motore fattura a consumo (per esempio con una chiave API). Con un piano in abbonamento, o finché la modalità di fatturazione non è nota, compare solo il tempo. Se il rail contiene più spec, l’intervallo vale per una spec e lo dice con *(per spec)*. Se la spesa di oggi più il limite alto dell’intervallo potesse raggiungere il tuo budget giornaliero, la riga aggiunge *Potrebbe fermarsi al budget* con un link alle impostazioni del budget. Se il budget di oggi è già esaurito, Avvia chiede prima una conferma, perché l’esecuzione resterebbe in pausa fino al ripristino.
+
+
 ## Dove andare ora
 
 - [Il Loop Builder](the-loop-builder) — cosa esegue un rail e come costruire i tuoi loop.

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

@@ -107,6 +107,18 @@ Se la [telemetria](../settings/customizing) era abilitata per il job, nell'intes
 
 Comodo per condividere un'esecuzione con un collega, o per inviare una segnalazione di bug precisa.
 
+## Quando un'esecuzione fallisce
+
+Quando un job fallisce, si ferma o è bloccato, lo stato finale inizia con una **scheda di diagnosi** che dice in parole semplici cos'è successo, per esempio *I test sono falliti nella fase Reviewer dopo 4 giri di correzioni*, e perché quando l'app lo sa:
+
+- **Test falliti**: i controlli continuano a fallire dopo i giri di correzioni.
+- **Limite del provider**: è stato raggiunto il limite d'uso del provider IA. La scheda riporta quando si azzera, con le parole del provider.
+- **Ambiente**: la macchina non riesce a eseguire i controlli (credenziali, uno strumento mancante, un comando di preparazione che fallisce). *Sistema l'ambiente* mostra esattamente cosa eseguire o cambiare.
+- **Bloccata**, **senza tempo**, **in silenzio** e **fermata all'improvviso** indicano il limite o il processo che ha fermato l'esecuzione.
+- **Causa sconosciuta**: l'app non tira a indovinare. Mostra la fine del log perché lo legga tu.
+
+Sotto la diagnosi ci sono fino a tre rimedi in ordine, e solo quelli che qui possono funzionare: **Riprendi da** la fase che si è fermata, **Esegui di nuovo**, **Modifica la spec e rilancia** (gli addendum della spec portano la tua modifica all'esecuzione successiva), **Sistema l'ambiente** e **Apri il log al punto del guasto**. La stessa causa compare come etichetta di una riga nella [elenco Da gestire](../getting-started/the-dashboard-tour), e la scheda di esecuzione della missione mostra la stessa scheda.
+
 ## Dove andare ora
 
 - [Rail e job](rails-and-jobs) — avvio e accodamento.

package/docs/guide/it/pipeline/3-reviewing-a-delivery.md

@@ -0,0 +1,43 @@
+<!-- guide-revision: mission-first-v1 -->
+
+# Rivedi una consegna nell'app {#review-a-delivery}
+
+Una consegna pronta per la revisione ha due viste: **Panoramica** (il verdetto, le prove e i pulsanti di decisione) e **Modifiche** (ciò che la consegna ha davvero cambiato). Apri la revisione dal pulsante **Rivedi** della consegna e scegli **Modifiche**.
+
+## Leggi le modifiche
+
+L'elenco dei file a sinistra mostra ogni file modificato con il suo stato (aggiunto, modificato, eliminato, rinominato), i conteggi di righe `+` e `−` e un segno quando lo contrassegni come visto. Il diff a destra carica un file alla volta, quindi anche una modifica grande resta fluida. Passa tra i layout **Unificato** e **Affiancato**; Specrails ricorda la tua scelta. Un file molto grande mostra le prime righe con **Carica il diff completo del file**; un file binario è indicato come binario.
+
+Le modifiche sono misurate dal punto in cui la consegna si è staccata dal branch di base, quindi ciò che è arrivato sulla base dopo non compare. Se la consegna non ha ancora un branch combinato, puoi scegliere il branch di quale spec leggere.
+
+## Note del revisore sul codice
+
+I rilievi del revisore, i rischi segnalati e i commenti di revisione che l'esecuzione doveva risolvere compaiono sotto la riga a cui si riferiscono. Le note che non indicano file né riga sono elencate sopra l'elenco dei file, quindi nulla resta nascosto. Le consegne più vecchie, e i revisori che non hanno indicato un punto, mostrano i rilievi in quell'elenco.
+
+## Chiedi all'agente di cambiare qualcosa
+
+Seleziona le righe cliccando sui loro numeri (Maiusc-clic estende l'intervallo), scegli **Chiedi una modifica all'agente** e descrivi la modifica. Specrails la salva come feedback di revisione sulla spec, con il file, l'intervallo di righe e il codice selezionato, e mostra un messaggio con un link alla spec. La prossima esecuzione su quella spec lo riceverà. Per avviarla subito usa **Chiedi modifiche** nella Panoramica. Qui non ci sono thread di commenti tra persone; confrontati con il tuo team su GitHub.
+
+## Aprilo nel tuo editor
+
+**Apri nell'editor** apre il file, alla riga selezionata, in VS Code, Cursor o in un IDE JetBrains. Scegli l'editor in **Impostazioni → Codice → Editor**. Il file si apre dalla tua copia del progetto, dove il branch della revisione potrebbe non essere attivo.
+
+## Scegliere cosa succede a una consegna {#pr-decision}
+
+Un'esecuzione conclusa ti chiede una sola cosa: cosa fare del risultato. La scheda mostra un pulsante principale per il passo successivo (creare la PR, pubblicarla o verificarla) e, accanto, **Rivedi**, che apre il pacchetto di revisione in linguaggio semplice. Tutto il resto è sotto **Altre azioni**:
+
+- **Passa al branch** porta il branch nella cartella del progetto così puoi provarlo.
+- **Integra in locale** unisce il risultato al branch di base su questo computer. Non serve GitHub e confermi prima.
+- **Scarta** elimina il risultato e il suo branch. Confermi prima.
+
+Se un'azione fallisce, l'avviso dice cosa non è andato a buon fine e offre **Riprova**.
+
+## Tastiera
+
+| Tasto | Azione |
+| --- | --- |
+| `j` / `k` | File modificato successivo / precedente |
+| `n` / `p` | Nota del revisore successiva / precedente |
+| `v` | Segna il file come visto |
+
+I tasti sono ignorati mentre scrivi in un campo. Segnare un file come visto è privato: se il file cambia in una revisione successiva mostra **Modificato da quando l'hai visto** e torna a contare come non visto.

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

@@ -1,4 +1,4 @@
-# Scegliere un engine per ogni rail
+# Scegliere un engine per ogni rail {#provider-capabilities}
 
 ## Quando compare il selettore
 
@@ -19,7 +19,7 @@ Tutti e quattro eseguono **Implement**:
 | Engine | Scegli questo quando… | Note |
 |--------|--------------------|-------|
 | **Claude** | Servono costi nativi, interazione persistente o tool policy rigorose. | Profili, Freestyle e transform strutturati. |
-| **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. |
+| **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. Freestyle funziona, senza chat interattiva. |
 
 ## Un flusso di lavoro pratico
 

package/docs/guide/it/pipeline/5-the-loop-builder.md

@@ -1,4 +1,4 @@
-# Il Loop Builder
+# Il Loop Builder {#loop-builder}
 
 ## Workflow Core
 

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

@@ -1,4 +1,4 @@
-# Temi
+# Temi {#themes}
 
 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.
 

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

@@ -1,4 +1,4 @@
-# Telemetria della pipeline e diagnostica
+# Telemetria della pipeline e diagnostica {#telemetry}
 
 La telemetria registra i dati diagnostici della pipeline in locale. È **attivata per impostazione predefinita** nei progetti senza una preferenza salvata. Puoi disattivarla per progetto; le scelte salvate esplicitamente vengono rispettate.
 
@@ -20,7 +20,7 @@ Da quel momento in poi, i job della pipeline in quel progetto registrano la tele
 
 ### 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.
+La telemetria si applica ai job che passano dalla **coda dei job** del progetto: le esecuzioni della pipeline della CLI (i rail quando i Loop sono disattivati e i comandi `implement` inviati dalla CLI `specrails-desktop`). Le esecuzioni di loop — il modo predefinito in cui girano i rail — e le sessioni interattive come chat, Explore e missioni non vengono strumentate.
 
 ## Dove vivono i dati
 

package/docs/guide/it/settings/5-project-environment.md

@@ -1,4 +1,4 @@
-# Ambiente del progetto
+# Ambiente del progetto {#project-environment}
 
 Alcuni progetti hanno bisogno di una credenziale durante l'esecuzione, come `NODE_AUTH_TOKEN` per i pacchetti npm privati. In **Impostazioni del progetto → Ambiente**, aggiungi i **nomi** delle variabili che servono ai tuoi rail e loop. Specrails salva solo i nomi, mai i valori.
 

package/docs/guide/it/settings/6-updates.md

@@ -0,0 +1,24 @@
+# Aggiornamenti {#updates}
+
+Specrails mantiene aggiornate due cose: l'app **Specrails Desktop** e il framework **specrails-core** usato dai tuoi progetti. Entrambe si trovano in **Impostazioni ▸ Aggiornamenti**.
+
+## Canale di aggiornamento
+
+Scegli quanto in fretta ricevere le nuove versioni:
+
+- **Ultima** (predefinito): ogni versione appena pubblicata. Ricevi per primo novità e correzioni.
+- **Stabile**: solo versioni rimaste almeno una settimana su Ultima con CI verde e poi promosse dai maintainer. Sceglilo se il tuo team preferisce aggiornamenti meno frequenti e ben collaudati.
+
+Il canale vale sia per l'app sia per specrails-core. Se specrails-core non ha ancora una versione stabile, Core segue Ultima e la scheda di Core te lo segnala.
+
+Su Stabile, se nessuna versione è stata ancora promossa, **Cerca aggiornamenti** te lo dice invece di proporti una versione di Ultima.
+
+## Come arrivano gli aggiornamenti
+
+- **Specrails Desktop** controlla all'avvio e ogni 6 ore. Quando c'è un aggiornamento compare una scheda da cui scaricare, installare e riavviare. Puoi anche fare clic su **Cerca aggiornamenti**.
+- **specrails-core** non si aggiorna mai da solo. Fai clic su **Cerca aggiornamenti** nella scheda di Core e poi su **Aggiorna**. I tuoi progetti passano al nuovo framework senza riavviare l'app.
+
+## Da sapere
+
+- Passare da Ultima a Stabile non ti riporta mai a una versione precedente. Resti sulla tua finché Stabile non la raggiunge.
+- Ogni aggiornamento è firmato e verificato prima dell'installazione, su entrambi i canali.

package/docs/guide/it/settings/7-existing-projects.md

@@ -0,0 +1,33 @@
+# Lavorare in un progetto esistente {#existing-projects}
+
+Queste funzioni aiutano i run a rispettare un progetto che esiste già: ciò che una spec lascia fuori, le domande dell'architetto prima di pianificare, quali requisiti un test dimostra davvero, come descrivere il codice esistente prima di cambiarlo e le regole che il tuo team ha già scritto. Ognuna richiede una versione di specrails-core che la supporti; nel frattempo il suo interruttore è disattivato con una nota per aggiornare Core.
+
+## Fuori ambito
+
+Ogni spec può elencare ciò che volutamente **non** cambia. Quick ed Explore lo compilano per te; nella finestra della spec appare come **Fuori ambito** sotto la descrizione, un elemento per riga, e si modifica come qualsiasi altro campo. Gli agenti lo ricevono con la spec a ogni avvio.
+
+## Domande dell'architetto su Jira
+
+In **Impostazioni ▸ Ancoraggio nei progetti esistenti**, attiva **Pubblica i chiarimenti dell'architetto su Jira**. Quando un run si ferma perché l'architetto ha bisogno di una risposta, o prosegue su ipotesi, Specrails le pubblica come un commento sull'issue Jira collegata. Rispondi a quel commento in Jira: la risposta viene aggiunta alla spec come chiarimento e il run successivo della spec la legge. Puoi comunque rispondere a un run in pausa dall'app.
+
+## Requisiti dimostrati
+
+Quando un test nomina il requisito che dimostra (`[spec:<capability>/<requisito>]` nel titolo), la pagina di revisione mostra **Requisiti dimostrati X/Y**: quali requisiti dimostra un test riuscito, quali non ne hanno ancora uno e quali ha toccato la modifica stessa. Le analisi mostrano lo stesso per loop. Per far fallire la CI quando un requisito modificato non ha test, aggiungi `specrails-core pipeline trace --check --tests-passed` dopo i tuoi test.
+
+La libreria dei loop offre anche **Controllo del drift**, un loop di sola lettura che confronta ciò che dice ogni spec con ciò che fa il codice ed elenca ogni contraddizione. Non modifica nulla.
+
+## Baseline al contatto
+
+Attiva **Baseline al contatto** perché una modifica che raggiunge codice non descritto da nessuna spec cominci descrivendolo: test del comportamento attuale, dimostrati sul codice invariato, e una breve spec dell'esistente. La pagina di revisione mostra **Spec creata dove è passato il lavoro** con il modulo, i requisiti e i test, e il suo costo è mostrato a parte. Se quei test falliscono sul codice invariato, il run si ferma prima di modificare il modulo e lo segnala.
+
+## Regole del progetto {#project-rules}
+
+**Impostazioni ▸ Regole del progetto** elenca i controlli che il tuo progetto esegue già (lint, tipi, test, CI) e ogni regola scritta in file come `CLAUDE.md` o `AGENTS.md`, suddivise in:
+
+- **Applicata**: un controllo la garantisce già.
+- **Automatizzabile**: un controllo potrebbe farlo. **Crea spec** la trasforma in spec con un clic.
+- **Solo umana**: qualcuno deve guardarla. Compaiono in ogni pagina di revisione sotto **Serve un occhio umano**.
+
+Le regole che Core non ha ancora potuto classificare (per esempio subito dopo aver aggiunto il progetto, quando l'inventario gira offline) compaiono come **Non classificata**; **Riesegui l'inventario** con un provider configurato le classifica.
+
+**Riesegui l'inventario** aggiorna l'elenco. Quando un progetto non ha ancora comandi di verifica, le impostazioni dell'agent runtime propongono per primi questi controlli.

package/docs/guide/it/settings/8-accessibility.md

@@ -0,0 +1,23 @@
+# Accessibilità e personalizzazione {#accessibility}
+
+Specrails si adatta al tuo modo di lavorare. Tutto si trova in **Impostazioni ▸ Aspetto**, vale subito e viene salvato su questo computer.
+
+## Densità {#density}
+
+**Comoda** mantiene schede e righe ariose. **Compatta** ne mostra di più: la bacheca delle spec parte con righe compatte, l'elenco dei job usa righe più strette e la storia del job stringe la sua linea del tempo. Una vista salvata della bacheca mantiene il proprio layout, quindi una vista salvata con schede post-it si apre ancora come schede post-it. Se la bacheca di questo progetto ha già una sua disposizione, **Usala anche per la bacheca**, sotto la scelta, le fa seguire di nuovo la densità.
+
+## Riduci movimento {#reduce-motion}
+
+**Segui il sistema** rispetta il tuo sistema operativo. **Riduci** disattiva animazioni e transizioni dentro Specrails qualunque cosa dica il sistema: la pillola del rail resta ferma alla sua posizione, i punti live smettono di pulsare e l'alone del Builder e gli effetti del tema restano immobili. **Movimento completo** anima anche quando il sistema ne chiede meno.
+
+## Spostare una spec da tastiera {#keyboard-moves}
+
+Porta il focus su una scheda spec nella bacheca (Tab o frecce) e premi **M**. Un piccolo selettore elenca gli stati e i rail; scegli con le frecce e **Invio**. Fa lo stesso che trascinarvi la scheda, comprese le spec collegate a Jira, che si spostano nel tuo workflow Jira. Se la scheda fa parte di una selezione multipla (**X** seleziona la scheda a fuoco), lo spostamento vale per tutte le spec selezionate. La palette dei comandi offre lo stesso come **Sposta la spec a fuoco…**. **M** non fa nulla mentre scrivi in un campo.
+
+## Annunci dei run per gli screen reader {#live-status}
+
+Specrails annuncia i cambiamenti dei run tramite una regione live educata, per il progetto che stai guardando: un run avviato, in pausa, che ha bisogno di te, fallito, terminato o con la revisione pronta. Le raffiche vengono unite e le ripetizioni scartate, così un rail molto attivo non sommerge mai il lettore. Gli avvisi di annullamento si annunciano già da soli.
+
+## Focus da tastiera {#focus}
+
+Ogni pulsante, link, voce di menu, scheda e riga di albero mostra un anello di focus visibile quando lo raggiungi da tastiera. Le informazioni che prima stavano solo in un tooltip, come il riferimento della spec sulla fascia di un rail, sono disponibili anche a chi usa tastiera e screen reader.

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

@@ -1,4 +1,4 @@
-# Le spec e il backlog
+# Le spec e il backlog {#specs-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.
 
@@ -13,7 +13,27 @@ La board ha due modalità di visualizzazione, che si alternano con un toggle nel
 - **Vista post-it** (quella predefinita) — riquadri in stile card con brevi riepiloghi.
 - **Vista elenco** — righe compatte su una sola riga.
 
-Il **selettore di stati** della toolbar mostra ogni stato come chip dedicato con un conteggio in tempo reale — più due gruppi intelligenti: **Attive** (il predefinito — tutto ciò che è ancora in movimento: bozze, da fare, in corso e in revisione) e **Tutti** (tutto, con Completato fissato in fondo). La scelta viene ricordata per progetto e riflessa nell'URL, così un refresh o un link condiviso ripristina esattamente la stessa vista. Nei progetti collegati a Jira compare in più un menu a tendina **stato Jira**, che elenca gli stati *reali* del workflow della board (i nomi grezzi, es. "Code Review", ciascuno con il proprio conteggio in tempo reale) raggruppati sotto lo stato a cui mappano — si combina con i chip di stato. Puoi anche filtrare per **etichetta**, oltre a ordinare per **Predefinito**, **Ticket #** o **Priorità** (ciascuno con un toggle crescente/decrescente).
+La toolbar delle Spec ha due righe. La prima contiene un campo di **ricerca** (premi `/` per raggiungerlo; cerca per titolo, `#numero`, etichetta o chiave Jira), un unico pulsante **Filtri**, i controlli di ordinamento e vista, e **Nuova spec**. La seconda riga è il **selettore di stati**: ogni stato come segmento dedicato con un conteggio in tempo reale, più due gruppi intelligenti, **Attive** (il predefinito: tutto ciò che è ancora in movimento, cioè bozze, da fare, in corso e in revisione) e **Tutti** (tutto, con Completato fissato in fondo). Quando la colonna è stretta, gli stati meno usati si raccolgono in un menu **Altro**, e lo stato scelto resta sempre visibile. La scelta viene ricordata per progetto e riflessa nell'URL, così un refresh o un link condiviso ripristina esattamente la stessa vista. **Filtri** apre un unico pannello con una sezione per dimensione: **etichette** (selezione multipla) e, nei progetti collegati a Jira, **epic**, **sprint** e **stato Jira** (gli stati *reali* del workflow della board, es. "Code Review", raggruppati sotto lo stato a cui mappano e combinati con il selettore di stati). Finché una ricerca o un filtro restringe la board, una terza riga mostra ciascuno come chip rimovibile, indica "x di y" spec e offre **Cancella tutto** (che mantiene lo stato scelto). Ordina per **Predefinito**, **Ticket #** o **Priorità**, ciascuno con un toggle crescente/decrescente.
+
+### Selezionare più spec
+
+Fai la triage in blocco invece di una spec alla volta. Premi `x` su una scheda a fuoco, fai clic su una scheda con `Ctrl`/`⌘`, oppure fai clic con `Maiusc` per selezionare un intervallo (un intervallo resta dentro una colonna: le spec attive o il gruppo Completate). `Ctrl`/`⌘`+`A` seleziona l'intera colonna in cui ti trovi e `Esc` deseleziona tutto. Ogni scheda mostra una casella al passaggio del mouse o quando ha il fuoco, e quelle selezionate hanno il bordo evidenziato. Nessuno di questi tasti agisce mentre scrivi nel campo di ricerca.
+
+Appena una spec è selezionata, in basso nella board compare una barra mobile con il conteggio e le azioni:
+
+- **Sposta in** cambia lo stato. Le spec locali ricevono gli stati locali; quelle che arrivano da Jira ricevono i veri stati del workflow della board Jira e passano dalla stessa coda Jira di uno spostamento singolo.
+- **Etichetta** aggiunge un'etichetta alla selezione, oppure ne rimuove una presente nelle spec.
+- **Priorità** imposta la stessa priorità per tutte.
+- **Aggiungi a un rail** mette la selezione su un rail.
+- **Avvia tutto** assegna a ogni spec selezionata un rail libero tutto suo e le avvia in parallelo, dopo la stessa conferma e lo stesso controllo del budget giornaliero di *Avvia tutto* dei rail. Le spec che non possono ancora partire (per esempio in revisione senza PR aperta) o che non trovano un rail libero vengono saltate e contate nel riepilogo.
+- **Elimina** le sposta in *Eliminate di recente*.
+- **Deseleziona** (o `Esc`) scarta la selezione.
+
+Eliminazione e modifiche di stato, etichette o priorità si annullano in un solo passaggio: un unico avviso *Annulla* (o `⌘Z`) ripristina ogni spec modificata. Se alcune falliscono, un solo avviso indica quante sono riuscite e quante no. La selezione contiene solo spec visibili: un filtro che nasconde una spec selezionata la toglie dalla selezione.
+
+### Viste salvate
+
+Il pulsante **Viste**, accanto a **Filtri**, salva la board così com'è ora: il selettore di stato, i filtri, l'ordinamento e la densità (non il testo di ricerca). Scegli **Salva la vista attuale…**, dalle un nome («Pronte da avviare», «Sprint 42», «Fallite questa settimana») e scegliila poi dallo stesso menu. **Gestisci le viste…** rinomina una vista, la aggiorna con la board attuale, ne copia il link o la elimina. Le viste appartengono al progetto. Un link copiato (`?view=…`) applica la vista quando viene aperto in questa app, e la palette dei comandi (`⌘K`) può salvare la vista attuale o passare a un'altra.
 
 ## Stati
 
@@ -38,7 +58,7 @@ Le bozze sono l'unica eccezione: una bozza può non avere *alcuna* priorità, pe
 
 ## 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:
+Per creare una spec, clicca su **Nuova spec** (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).
@@ -50,6 +70,24 @@ Quale scegliere dipende da quanto è già chiara l'idea. Sai esattamente cosa vu
 
 Quando una spec ha già del lavoro alle spalle — una PR in revisione, una funzionalità già unita — e vuoi *di più*, non riscriverne la descrizione: snatura la spec (e sincronizza la deriva su Jira) e costringe l'esecuzione successiva a ripianificare tutto. Apri la spec e aggiungi invece un **addendum**: una breve nota con un tipo (richiesta di modifica, feedback di revisione, chiarimento, vincolo) e le tue parole. Gli addenda aperti viaggiano automaticamente con il prossimo lancio di quella spec su qualsiasi loop — Implement, SDD Quick, Freestyle — così l'esecuzione cambia solo ciò che hai chiesto, e il pacchetto di revisione riporta ciascuno come applicato, parzialmente applicato o bloccato. Se l'esecuzione fallisce o scarti la consegna, tornano da soli ad **Aperto**. L'agente di missione può aggiungerli per te quando gli chiedi di cambiare qualcosa in una spec esistente.
 
+## Rivedere una consegna: cosa guardare per primo
+
+Quando un'esecuzione termina, il suo pacchetto di revisione si apre con **Cosa guardare**: la breve nota del revisore IA che elenca prima i punti più rischiosi (alto, poi medio, poi basso, ciascuno con file e riga), il comportamento che cambia, le regole su cui la modifica si appoggia, i percorsi di codice che nessun test esercita e i controlli che solo una persona può fare. Gli stessi rischi, percorsi senza test e controlli compaiono in un breve blocco in cima alla pull request, e la scheda della missione mostra il rischio principale in una riga. La nota aiuta la revisione, non è un risultato di verifica: non blocca mai Accetta. Le esecuzioni fatte con uno Specrails Core precedente non hanno la nota e il loro pacchetto resta come prima.
+
+## Annulla e Eliminati di recente {#recently-deleted}
+
+Eliminare una spec, spostarla in un altro stato, cambiarne le etichette o toglierla da un rail avviene subito: nessun "Sei sicuro?" prima. Al suo posto, una notifica offre **Annulla** per circa otto secondi, e **⌘Z** (**Ctrl+Z** su Windows e Linux) fa lo stesso finché non stai scrivendo in un campo. Annulla vale per progetto: cambiando progetto la finestra si chiude.
+
+Una spec eliminata (e una missione eliminata) non sparisce. Va in **Impostazioni → Eliminati di recente**, nelle impostazioni del progetto, dove puoi **Ripristinarla** per 30 giorni o **Eliminarla definitivamente**, che chiede prima conferma. Dopo 30 giorni viene rimossa per sempre. Scartare lavoro non pushato, chiudere con la forza una pull request e rimuovere un progetto chiedono ancora conferma, perché non si possono annullare. Una spec collegata a Jira si sposta ancora con **Sposta in** invece di essere eliminata.
+
+## La cronologia della spec e il passaggio di consegne {#spec-timeline}
+
+Apri una spec e passa alla scheda **Cronologia** per leggere tutta la sua storia in un unico posto: le modifiche e gli addenda, le missioni che l’hanno toccata, ogni esecuzione con le sue fasi e le azioni dell’agente, gli eventi della pull request e il verdetto del revisore con i suoi rilievi. Le voci sono raggruppate per giorno, i chip filtrano per tipo e ogni voce rimanda alla missione, all’esecuzione o alla revisione da cui proviene. I gruppi lunghi (fasi, azioni dell’agente, turni di missione) sono compressi con un contatore e si espandono sul posto.
+
+Il costo compare accanto alla voce che lo ha generato, con i due tipi tenuti separati: una cifra riportata dal provider e una stimata dalla tabella prezzi locale (segnata «stim.»). Se un provider è fatturato tramite abbonamento, la cronologia e le esportazioni mostrano i turni, mai i dollari; un’esecuzione che non ha riportato costo semplicemente non ne mostra.
+
+**Esporta passaggio di consegne** (il menu accanto alle schede, o ⌘K → *Esporta passaggio di #N*) scrive un file Markdown o una pagina HTML autonoma con il riepilogo, le decisioni (addenda, chiarimenti, verdetti del revisore), le statistiche del diff, il costo e ciò che resta aperto (addenda aperti e rilievi di revisione non risolti). **Copia come descrizione della PR** (anche in ⌘K) mette negli appunti una versione più breve in Markdown. Le intestazioni seguono la lingua dell’app. Tutto passa per la stessa oscuratura dei segreti usata dall’audit delle azioni dell’agente, e la notifica ti dice quando qualcosa è stato oscurato.
+
 ## Dove andare adesso
 
 - [Aggiungi spec — Modalità Quick](add-spec-quick-mode.md) — il modo più rapido per trasformare un'idea in una spec.

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

@@ -6,7 +6,7 @@ La modalità Quick è pensata per quando sai già cosa vuoi. Scrivi la tua idea,
 
 Per creare rapidamente una spec:
 
-1. Nella Dashboard, clicca su **Aggiungi** (il pulsante Più nella toolbar della SpecsBoard).
+1. Nella Dashboard, clicca su **Nuova spec** (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.

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

@@ -22,7 +22,7 @@ Mentre converssi, un pannello mostra la bozza così com'è in quel momento — t
 
 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
+## Quanto vede l'AI: lo slider del contesto {#context-scope}
 
 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à:
 

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

@@ -1,4 +1,4 @@
-# エージェントの紹介
+# エージェントの紹介 {#agents}
 
 **Implement** レールを起動するとき、Specrails はあなたのスペックを1つの AI に丸投げして結果を祈る、ということはしません。それぞれ1つの役割だけを担う小さな専門 *エージェント* チームを、意図された順番で動かします。このページでは、そのチームのメンバーと、それぞれが何をするのかを紹介します。
 

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

@@ -39,3 +39,5 @@ specrails を初めて開くと、すっきりした **ウェルカム画面**
 オンボーディングはこれだけ。アカウント作成もサインアップもありません。specrails はすべてあなたのマシン上で動作します。
 
 **最初のプロジェクトを追加** をクリックして、[Adding your first project](adding-your-first-project) へ進みましょう。
+
+または、[サンプルプロジェクト](try-the-sample-project)から始めましょう。小さなゲームと用意済みの3つのスペックで、費用は事前に示されます。

package/docs/guide/ja/getting-started/3-try-the-sample-project.md

@@ -0,0 +1,35 @@
+# サンプルプロジェクトを試す
+
+自分のコードに specrails を向ける前に、スペックがレビュー済みの変更になる様子を見てみたいですか？**サンプルプロジェクト**は、3つの用意済みスペックが付いた小さな○×ゲームの Web アプリです。数分で終わり、本物の**レビューパケット**にたどり着きます。
+
+## 始める
+
+ウェルカム画面で**サンプルプロジェクトで試す**（**最初のプロジェクトを追加**の隣）をクリックします。何かが起きる前に、ダイアログが次を伝えます。
+
+- **作成されるもの**：専用の git リポジトリに入った小さな Web ゲームと、ボードに並ぶ3つのスペック。
+- **作成場所**：既定ではホームフォルダ内の `~/Specrails Samples/tic-tac-toe`。フォルダは変更できます。既存のフォルダが上書きされることはありません。
+- **実行にかかる費用**：「≈ $0.30–$1 · 約 3–5 分」のような見積もり。プロバイダーが従量課金の場合にのみドルで表示されます。サブスクリプションプランでは追加料金なし、ローカルエンジンでは API 料金なしと表示されます。
+
+サンプルの作成は無料で、何も実行しません。**サンプルプロジェクトを作成**をクリックすると、ボードに移動します。
+
+## 3つのステップ
+
+小さなガイドカードが、実際のボードを1ステップずつ指し示します。いつでも閉じることができ、**サンプルプロジェクト**のピルに折りたたまれます。**ガイドを表示**で元に戻せます。
+
+1. **スペック。** 3つのスペックはあらかじめ書かれています。それぞれ、何を作るか、何をもって完了とするかが書かれています。
+2. **レール。** **最初のスペックを実行**をクリックします。サンプルは低コストで上限付きに設定されています。クイックモード、利用可能な最も安いモデル、実行ごとのソフト上限（$1 を超える前に一時停止して確認）です。ローカルエンジンを設定している場合は、API 料金なしでそちらを選べます。
+3. **レビュー。** 何も勝手にマージされません。実行が終わると、**レビューパケット**が変更内容を示し、承認か破棄を選べます。
+
+## 使える AI プロバイダーがない場合
+
+実行を提示する前に、specrails はプロバイダーがインストールされ、サインインしているかを確認します。準備できていない場合は、代わりに**録画された実行を見る**が表示されます。完了した実行をレビューパケットまで再生するものです。録画であることが明示され、何も実行されず、課金もされません。プロバイダーをインストールまたはサインインしてから**再確認**を選ぶと、実際の実行に切り替わります。
+
+## そして、自分のプロジェクトへ
+
+ガイドは**自分のプロジェクトを追加**で終わります。サンプルが不要になったら、**サンプルを削除**でワンクリックで登録解除できます。**サンプルのフォルダも削除する**にチェックを入れない限り、フォルダはディスクに残ります。この削除は元に戻せません。
+
+## プラットフォームツアーをもう一度見る
+
+ツアーはウェルカム画面から移動しました。**ドキュメント**を開いて**ツアーをもう一度見る**を選ぶか、コマンドパレットを開いて「ツアーをもう一度見る」と入力します。**設定 ▸ 外観**にもあります。
+
+次へ：[最初のプロジェクトを追加する](adding-your-first-project)。

package/docs/guide/ja/getting-started/{4-the-dashboard-tour.md → 5-the-dashboard-tour.md}

@@ -37,11 +37,15 @@
 - **合計支出**（右） — これまでの支出の累計です。コストが常にひと目で分かります。
 - **ターミナル切り替え**（いちばん右） — 内蔵のターミナルパネルを開きます。**Cmd+J**（macOS）または **Ctrl+J**（Windows/Linux）でいつでも開閉できます。プロジェクトフォルダで開く、本格的なシェルです。
 
-## 便利なショートカット
+## 便利なショートカット {#shortcuts}
 
-- **Cmd/Ctrl+B** — サイドバーをピン留め／折りたたみます。
+- **Cmd/Ctrl+B** — 左サイドバーをピン留め／折りたたみます。**Option+Cmd+B**（**Ctrl+Alt+B**）は右サイドバーに同じ操作をします。
 - **Cmd/Ctrl+J** — ターミナルパネルを開閉します。
-- **Cmd/Ctrl+K** — 検索を開きます。
+- **Cmd/Ctrl+K** — コマンドパレット。ミッション、プロジェクト、ジョブを検索し、**アクションを実行**できます。動詞（「新規」「起動」「移動」「切り替え」など）を入力するか、**>** で始めるとアクションが一覧表示されます。新しい Spec（探索モードも可）、Spec の起動・移動、そのレビューを開く、Flow の引き継ぎ・一時停止、新しいミッション、テーマの切り替え、ミッションモードとボードモードの切り替え、アプリ設定・プロジェクト設定を特定のセクションで開く、ループの実行、サイドバーの切り替え、戻る・進む、直前の変更を元に戻す、最近削除した項目、などです。選択が必要なアクション（Rail、ステータス、テーマ、セクション）は 2 ページ目を開きます。検索欄が空のときに **Backspace** を押すと戻ります。各アクションにはキーボードショートカットが表示されるので、パレットがキーを教えてくれます。今いる場所で使えるものだけが表示され、ボタンと同じルールに従います（起動できない Spec は表示されません）。検索欄が空のときは、**最近のアクション**と**最近の場所**が表示されます。
+- **Cmd+[ / Cmd+]**（Windows/Linux では **Alt+← / Alt+→**）、タイトルバーの **←  →** ボタン、またはマウスの戻る/進むボタン — 訪れた場所（スペック、ミッション、ジョブ、プロジェクト、全画面パネル）を戻ったり進んだりします。ボタンを右クリック（または長押し）すると最近の場所が表示されます。
+- **Cmd+Shift+I**（Windows と Linux では **Ctrl+Alt+I**）またはタイトルバーの**対応待ち**ボタン — **対応待ち**リスト：すべてのプロジェクトであなたを待っているものを、プロジェクトごとにまとめた 1 つのリストで表示します。判断できるレビュー、エージェントが待っている質問、失敗またはブロックされた実行、1 日の予算で一時停止した実行、同期できなかった Jira の更新を集めます。各行にはその場で使える主な操作（**レビューを開く**、**回答**、**再開**、**再試行**）に加え、**後で通知**（1 時間または明日まで）と**完了**があります。後回しにした項目や完了した項目は、状態が変わると自動的に戻ります。ボタンには待機中の件数が表示され、プロバイダーの上限通知からもリストを開けます。このリストはリンク（`?inbox=1`）でもあり、コマンドパレットの操作でもあります。
+- **M** — ボード上でスペックカードにフォーカスしているときに、ステータスやレールへ移動する選択画面を開きます。ドラッグ&ドロップのキーボード版で、複数選択にも使え、パレットでは**フォーカス中のスペックを移動…**として表示されます。
+- **?** — ショートカットの一覧。検索ボックスに入力すると、ショートカットを絞り込めるほか、このガイドの該当するページやセクションも見つかり、画面を離れずにガイドで開けます。設定、レール、Flow、コンテキストスライダー、予算の横にある小さな **ⓘ** アイコンや**詳しく見る**リンクも、同じ方法で対応するセクションを開きます。
 
 ## 次に向かう先
 

package/docs/guide/ja/getting-started/6-universal-search.md

@@ -0,0 +1,34 @@
+# ユニバーサル検索（⌘K）
+
+**⌘K**（Windows と Linux では **Ctrl+K**）を押すと、ミッション、スペック、ジョブログ、ファイル、設定、このガイドなど、Specrails のほぼすべてを 1 か所から検索できます。通常の検索語を入力すると、これまでどおりミッション、プロジェクト、スペック、最近のジョブを検索します。**プレフィックス**で始めると、1 つの対象だけを検索します。
+
+## プレフィックス
+
+| 入力 | 検索対象 | Enter で開くもの |
+| --- | --- | --- |
+| `#` | スペック：タイトル、概要、説明、ラベル、対象外メモ、追記、コメント。`#12` は 12 番のスペックを見つけます。 | そのスペック |
+| `@` | ミッション：タイトルと会話の内容。 | そのミッション |
+| `/` | 設定（Desktop とプロジェクト）。名前や呼び方で探せます。 | 該当ブロックにスクロールしてフォーカスした設定画面 |
+| `f:` | プロジェクトのファイル（名前またはパス）。 | コードエクスプローラーでそのファイル |
+| `log:` | ジョブログ：コマンド、ループ名、フェーズ名、失敗の診断。 | そのジョブ |
+| `?` | このガイド：ページ名と見出し。 | ガイドのその見出し |
+
+プレフィックスを入力すると検索ボックス内の**チップ**になり、ボックスには検索語だけが残ります。ボックスが空のときに **Backspace**（またはチップの × をクリック）で範囲を解除できます。ボックスが空のときは、パレットがボックスの下にプレフィックスを一覧表示します。クリックして開始できます。`>` は従来どおりアクションを一覧表示します。
+
+## ハイライト
+
+結果には最初の一致箇所の前後の短い抜粋が表示され、一致した部分が強調されます。検索では大文字小文字とアクセントを区別しないため、`revision` で「Révision」が見つかります。
+
+## 設定
+
+`/` は、テーマ、言語、エディタ、予算、通知、Webhook、アップデート、ブランチ、環境、テレメトリ、ルールなど、主要な設定ブロックをお使いの言語で把握しています。プロジェクト設定は、プロジェクトを開いているときに表示されます。選ぶと、該当ブロックで正しい画面が開きます。プレフィックスなしでも、強い一致（3 文字以上）があれば、通常の結果に設定が最大 3 件追加されます。`/budget` は予算パネル（上限・予測・もしも）も見つけます。週間・月間の上限はそこにあります。`/implement` のようなスラッシュコマンドは設定の下に専用のグループで表示されるため、`/` プレフィックスで隠れることはありません。
+
+## ジョブログ
+
+`log:` は、実行の生の出力ではなく、コンパクトなインデックスを検索します。コマンド、ループ名、フェーズ名、失敗・ブロック・停止した実行の短い診断が対象です。トークンストリームやツール出力は保存しないため、小さく高速なままです。プロジェクトごとに保持され、最新の実行を含みます。
+
+## 知っておくと便利なこと
+
+- `#`、`f:`、`log:` はアクティブなプロジェクトを検索します。先にプロジェクトを開いてください。
+- ファイルの範囲は、コードエクスプローラーの除外ルールに従います。
+- 各グループには上位の結果だけが表示されます。検索語を絞り込んでください。

package/docs/guide/ja/insights/1-analytics-and-cost-tracking.md

@@ -6,15 +6,17 @@ Specrails があなたの代わりに AI CLI を実行するたびに — パイ
 
 ## 何が「支出」としてカウントされるのか
 
-Specrails は 5 種類の AI アクティビティを追跡しており、これらを*サーフェス*と呼びます。それぞれのサーフェスは、すべてのチャートで一貫して色分けされているので、ひと目で見分けられます。
+Specrails はすべての AI 実行に*サーフェス*（その支出を発生させたアプリ内の場所）のタグを付けます。主要なサーフェスにはそれぞれ固定の色と専用のフィルターチップがあるので、ひと目で見分けられます。
 
-- **ジョブ** — Architect → Developer → Reviewer → Ship を実行するパイプラインのレール。
+- **ジョブ** — キューに入ったパイプラインジョブ（Architect → Developer → Reviewer → Ship）。Freestyle の実行も含みます。
+- **ループ** — ループ実行の各 AI ステップ。レールはデフォルトでループとして実行されるため、レールの支出の大半はここに計上されます。
 - **クイックスペック** — 高速な Add Spec から生成したスペック。
 - **Explore スペック** — 会話を通じてスペックを形にする Explore セッション。
 - **AI リファイン** — エージェントやファイルに対する AI 支援のリファイン。
-- **ファイル要約** — Code エクスプローラーを支える、平易な言葉による要約。
+- **SMASH** — エピックのスペックを小さなスペックに分割する処理。
+- **ファイル要約** — Code エクスプローラーを支える、平易な言葉の要約とファイルストーリー。
 
-意図的に*追跡しない*ものもいくつかあります。チャットサイドバーとセットアップウィザードはどちらも AI CLI を起動しますが、これらは支出には一切表れません。そのおかげで、ダッシュボードには付随的なやり取りではなく、実際の、繰り返し行われる作業だけが反映されます。
+専用のチップはありませんが、小さなサーフェスも記録されます。チャットサイドバー、OpenSpec のスペックランチャー、スペック提案、Agent Studio、旧来のセットアップチャットです。プロジェクトにピン留めされたミッションも、そのプロジェクトの支出に含まれます。AI CLI を実行するものは何ひとつ除外されないため、合計はプロジェクトのすべての AI アクティビティを反映します。
 
 ## ダッシュボードの読み方
 
@@ -76,3 +78,15 @@ Specrails は 5 種類の AI アクティビティを追跡しており、これ
 ## 常にライブ
 
 更新（リフレッシュ）の必要はありません。プロジェクト内のどこかで新しい呼び出しが記録されると、開いているダッシュボードが少し後で静かに再取得を行うので、作業が完了するのに合わせてバーンメーターが追従し続けます。
+
+## 1 日の予算 {#daily-budget}
+
+1 日の予算を設定すると、1 日にかけられる費用に上限を設けられます。すべての上限（日次・週間・月間・実行ごと）は 1 か所、**分析 → 予算** で編集します。**設定 → 詳細設定** と **プロジェクト設定 → 予算** には現在の日次上限だけが表示され、**予算を開く** ボタンでそこへ移動できます。
+
+その日に記録された支出が予算に達すると、キューは自動で一時停止し、レールとループの実行は*1 日の予算に達しました*と表示されて起動しません。実行中のループはステップの合間で止まり、予算のため一時停止になります。予算を引き上げるか解除するか、毎日のリセットを待ってから再開してください。
+
+プロジェクトの予算はローカルの 1 日、アプリ全体の予算は UTC の 1 日で数えます。ジョブごとの費用アラートは別の設定です。
+
+**週間・月間・実行ごとの上限.** より長い期間の上限も同じように動作します。**分析 → 予算**で、プロジェクトごと、およびアプリ全体の**週間**上限と**月間**上限、そして**実行ごとのソフト上限**（*$X で一時停止して確認*）を設定できます。週は月曜日、月は 1 日に始まり、ローカル時間で数えます。週間・月間の上限は 1 日の予算とまったく同じように、キューを一時停止し、起動を拒否し、実行中のループを一時停止します。そこで引き上げるか解除するか、リセットを待ってください。実行自身が報告したコストが実行ごとの上限に達すると一時停止し、**再開**では上限なしで続行するか引き上げるかを確認します。いずれかの上限に達すると、受信トレイにも**上限を引き上げる**項目が追加されます。
+
+予算パネルには、今日・今週・今月が各上限と並べて表示されます。月末の**予測**は見積もりです（直近 14 日分の完了した日の平均に残り日数を掛け、これまでの支出を加えたもの）。請求済みの支出には加算されません。**もしも**は、記録された過去 30 日のトークン使用量をアプリの料金表で別のモデルとして再計算し、料金のないモデルには*料金がありません*と表示します。サブスクリプションのプランでは利用ごとのドル費用がないため、パネルはドルの代わりにターン数とプランの利用枠を表示します。

package/docs/guide/ja/insights/2-the-integrated-terminal.md

@@ -1,4 +1,4 @@
-# 統合ターミナル
+# 統合ターミナル {#integrated-terminal}
 
 Specrails には本物のターミナルが組み込まれています — ウィンドウの下からせり上がってくる、あの VS Code や Cursor とまったく同じ感覚のパネルです。実際のシェルを、実際のプロジェクトディレクトリで動かすので、アプリを離れることなく `git`、`npm`、テスト、その他なんでも実行できます。