specrails-desktop 2.12.0 → 2.13.0

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

@@ -0,0 +1,91 @@
+# Il Loop Builder
+
+Un **rail esegue un Loop**. I loop integrati (`Implement`, `Batch`, `Ultracode`) coprono i casi di tutti i giorni, ma il **Loop Builder** ti permette di progettare i tuoi — un editor visuale in stile n8n per automazioni che si ripetono finché un obiettivo non è raggiunto. Questa pagina spiega cos'è un loop, come costruirne uno e come eseguirlo su un rail.
+
+## Loop e rail — la relazione
+
+Un **loop** è la *ricetta* del lavoro; un **rail** è la *corsia* che lo esegue sulle tue spec.
+
+```
+   Loop Builder (sidebar sinistra)         Rail (destra)
+   ───────────────────────────             ─────────────
+   Implement   (integrato)                 Rail 1
+   Batch       (integrato)     scegli su ►    Loop: Verify-until-green
+   Ultracode   (integrato)                    ▶ Play
+   Verify-until-green (tuo)
+```
+
+- I loop vivono nella sezione **Loops** (sidebar sinistra, accanto ai tuoi progetti) — sono **globali**, condivisi tra tutti i progetti.
+- Un rail **sceglie un loop** nel suo header (il selettore Loop) e lo esegue quando premi Play.
+- È il **rail** a decidere provider, modello e reasoning effort — *non* gli step del loop. Lo stesso loop gira su Claude, Codex o Gemini a seconda del rail.
+
+Quindi: costruisci un loop una volta, poi scegli quel loop su qualsiasi rail in qualsiasi progetto.
+
+## Aprire il builder
+
+Clicca **Loops** nella sidebar sinistra per vedere la libreria: i tre loop integrati più tutti i tuoi. Aprine uno per visualizzarlo, oppure clicca **New loop** per partire da una tela bianca.
+
+Non puoi modificare facilmente un integrato in modo diretto — invece fanne un **Fork**. Ti dà una copia modificabile di un grafo funzionante da cui partire, ed è il modo più semplice per imparare.
+
+## Di cosa è fatto un loop
+
+Un loop è un grafo di **nodi** collegati da **archi** (le frecce). Ogni nodo è uno step:
+
+| Nodo | Cosa fa |
+|------|--------------|
+| **Start** | Dove inizia l'esecuzione. Esattamente uno per loop. |
+| **AI Step** | Esegue un turno AI — un prompt che scrivi tu, o un *magic command* come `{{cmd:implement}}`, `{{cmd:verify}}`, `{{cmd:fix}}`. È qui che accade il lavoro vero. |
+| **Shell** | Esegue un comando shell (es. `npm test`) e ne cattura l'output per gli step successivi. |
+| **Loop Decider** | Il cervello di un loop. A ogni passaggio legge un **obiettivo** che scrivi tu e decide **continue** (torna indietro e riprova) o **stop** (esci). È ciò che alimenta *verify → fix → verify finché non è verde*. |
+| **End** | Un nodo terminale. Marca l'esecuzione come successo o fallimento. |
+
+Gli archi collegano gli step in ordine. Il **Loop Decider** ha due uscite etichettate — **continue** e **stop** — così colleghi "non ancora finito" di nuovo nel lavoro e "fatto" verso un End.
+
+### Scrivere il testo di uno step
+
+Dentro qualsiasi AI Step o Decider puoi fare riferimento a:
+
+- **Dati della spec** — `{{spec.title}}`, `{{spec.description}}`, `{{spec.ids}}` (gli ID dei ticket del rail). Riempiti dalle spec sul rail al momento dell'esecuzione.
+- **Magic command** — `{{cmd:implement}}` e simili si espandono nel comando della pipeline corrispondente.
+- **Costanti** — `{{const:NAME}}` attinge dalla **libreria di costanti** globale (trascinale dalla palette). Sentinelle integrate come i marcatori PASS/FAIL di verifica sono sempre disponibili; puoi aggiungere le tue e riusarle in ogni loop.
+
+## Tenere un loop entro i limiti
+
+Un loop che non si ferma mai brucerebbe soldi per sempre, quindi ogni esecuzione ha tre guardie (impostate nella toolbar del builder):
+
+| Guardia | Cosa fa |
+|-------|--------------|
+| **Max iterations** | Tetto massimo di quante volte il Decider può tornare indietro, indipendentemente dal suo verdetto. |
+| **Timeout (min)** | Limite di tempo reale per l'intera esecuzione. |
+| **Max cost ($)** | *Opzionale.* Ferma il loop quando il costo accumulato supera il tuo budget. Controllato **tra uno step e l'altro** (il costo di uno step si conosce solo quando finisce), quindi può sforare di uno step. Su Claude il costo è esatto; su Codex e Gemini è una stima. Lascialo vuoto per nessun tetto. |
+
+## Costruire con sicurezza
+
+Il builder ti aiuta a far girare bene un loop prima ancora che venga eseguito:
+
+- **Validazione dal vivo** — i problemi (nessuno Start, uno step orfano, un prompt vuoto, un Decider con rami mancanti) sono segnalati sulla tela e in un pannello dei problemi.
+- **Anteprima dry-run** — risolve il testo esatto di ogni step (dati della spec, costanti, comandi tutti espansi) **senza avviare nulla**, così vedi con precisione cosa invierebbe ogni step.
+- **Auto-arrange** — riordina la tela in verticale, orizzontale o a griglia; la tua scelta è salvata per loop.
+- **Copia / incolla** — `Cmd/Ctrl + C` / `V` per copiare step dentro o tra i loop.
+- **Import / export** — salva i loop in un file `.json` e reimportali (i nomi duplicati vengono saltati, il resto viene importato).
+- **Rinomina step** — dai a ogni nodo un'etichetta personalizzata così il grafo si legge chiaro.
+
+## Pubblicare ed eseguire
+
+Un loop nasce come **Draft**. Quando il grafo è valido, fai **Publish** — i loop pubblicati sono quelli che compaiono nel selettore Loop di un rail. (Fai Unpublish per toglierlo dalla circolazione senza eliminarlo.)
+
+Per eseguire un loop personalizzato:
+
+1. Apri un progetto e trascina una spec su un rail.
+2. Nell'header del rail, apri il **selettore Loop** e scegli il tuo loop pubblicato.
+3. Premi **▶ Play**.
+
+L'esecuzione scorre dal vivo nella vista **Jobs** esattamente come un job di rail integrato — stessi log, stesse metriche, stesso tracciamento del costo. Un loop che si ferma perché ha raggiunto il suo tetto di iterazioni o di costo viene riportato con quell'esito anziché con un semplice successo.
+
+> **Attenzione mentre un loop gira.** Non puoi modificare o eliminare un loop mentre una delle sue esecuzioni è in corso — ferma prima l'esecuzione.
+
+## Dove andare poi
+
+- [Rail e job](rails-and-jobs) — avviare i rail e la coda dei job.
+- [La vista Dettaglio job](the-job-detail-view) — seguire un'esecuzione dal vivo.
+- [Scegliere un engine per rail](picking-an-engine-per-rail) — è il rail (non il loop) a scegliere il provider.

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

@@ -23,7 +23,7 @@ SpecsBoard（左）            レール（右）
 ## スペックでレールを起動する
 
 1. **スペックカードをドラッグ**して、SpecsBoard からレールへ移します。スペックの ID がそのレールのスペック一覧に表示されます。（ドラッグが苦手ですか？ スペックカードの **レールに移動** ポップオーバーを使えば、レールごとにステータスのドットが表示されるので、ふさがっているレーンに作業を落としてしまう心配がありません。）
-2. デフォルト以外にしたいときは、**モードを選びます** — レールヘッダーのセグメントコントロールで `Implement`、`Batch`、そして（Claude レール限定で）`Ultra` を選べます。
+2. レールヘッダーで **Loop を選びます**。レールは **Loop** を実行します — それがレールの行う作業そのものです。デフォルトは組み込みの `Implement` Loop ですが、`Batch`、`Ultracode`、あるいは自分で作ったカスタム Loop を選ぶこともできます。[Loop Builder](the-loop-builder) を参照してください。
 3. **▶ Play を押します。**
 
 これだけです。レールがあなたのプロジェクト内で AI CLI プロセスを立ち上げ、パイプラインを開始します。
@@ -34,20 +34,24 @@ SpecsBoard（左）            レール（右）
 |---------|--------------|
 | **ステータスピル** | `idle`、`running`、`failed` のいずれか。「completed」という別ステータスはありません — ジョブがきれいに完了すると、レールは `idle` に戻ります。 |
 | **スペック一覧** | このレールに割り当てられた ID。さらにドラッグして追加したり、ドラッグして外したりできます。 |
-| **モードコントロール** | `Implement` / `Batch` / `Ultra` — 下の表を参照してください。レールごとに保持されます。 |
+| **Loop ピッカー** | このレールが実行する Loop — 組み込み（`Implement` / `Batch` / `Ultracode`）かカスタム Loop。下の表を参照してください。レールごとに保持されます。 |
 | **プロファイルピッカー** | どのエージェントプロファイルを実行するか（Claude レール限定）。プロジェクトにプロファイルが 1 つ以上あるときだけ表示されます。 |
 | **エンジンセレクター** | このレールをどのインストール済みプロバイダーで実行するか — Claude、Codex、Gemini。プロジェクトに複数のプロバイダーがある場合だけ表示されます。[レールごとのエンジン選択](picking-an-engine-per-rail) を参照してください。 |
 | **▶ Play / ■ Stop** | 開始またはキャンセル。 |
 
-### 3 つのレールモード
+### レールが実行するもの: Loop
 
-| モード | コマンド | 役割 |
+レールは **Loop** を実行します — それが作業のレシピです。3 つの Loop が **組み込み** で、よくあるケースをカバーします。
+
+| 組み込み Loop | コマンド | 役割 |
 |------|---------|--------------|
 | **Implement** | `/specrails:implement` | レール上のすべてのスペックをまとめた 1 つのジョブ。Architect → Developer → Reviewer → Ship のフルパイプラインを実行します。日常的に使うデフォルトです。 |
 | **Batch** | `/specrails:batch-implement` | レール上のスペックを、依存関係を考慮したウェーブで順番に処理する 1 つのジョブ。関連する複数のスペックに最適です。 |
-| **Ultra** | Ultracode | Claude が各スペックをパイプラインを**バイパス**して自律的に実装します。スペックごとに独立したジョブが 1 つずつ作られます。Claude 専用。 |
+| **Ultracode** | Ultracode | Claude が各スペックをパイプラインを**バイパス**して自律的に実装します。スペックごとに独立したジョブが 1 つずつ作られます。Claude 専用。 |
+
+Ultracode は少し毛色が違います。エージェントチェーンを飛ばし、生のスペックを Claude に渡してネイティブツールで作業させます。自由度が高いぶん、Play を押すとまず確認ダイアログが開き、レールごとのモデルピッカーで Haiku / Sonnet / Opus を選べます。Ultracode はレールのエンジンが Claude のときだけ表示されます。
 
-Ultra は少し毛色が違います。エージェントチェーンを飛ばし、生のスペックを Claude に渡してネイティブツールで作業させます。自由度が高いぶん、Play を押すとまず確認ダイアログが開き、レールごとのモデルピッカーで Haiku / Sonnet / Opus を選べます。Ultra はレールのエンジンが Claude のときだけ表示されます。
+組み込みのほかにも、**自分だけの Loop を作る** ことができます — verify → fix → verify のサイクルを目標が達成されるまで繰り返したり、AI ステップの間にシェルコマンドを連ねたり、さらにいろいろなことができます。そうしたカスタム Loop は同じ Loop ピッカーに表示されます。それが次の大きなアイデア、[Loop Builder](the-loop-builder) です。
 
 ## ジョブのキュー
 
@@ -89,6 +93,7 @@ CLI がマシンにインストールされていないエンジンを選ぶと
 
 ## 次に読むもの
 
+- [Loop Builder](the-loop-builder) — レールが実行するもの、そして自分だけの Loop を作る方法。
 - [ジョブ詳細ビュー](the-job-detail-view) — フェーズ、ライブメトリクス、チケットカード。
 - [バッチ実装とマルチフィーチャー](batch-implement-and-multi-feature) — 複数のスペックをまとめて実行する。
 - [レールごとのエンジン選択](picking-an-engine-per-rail) — Claude / Codex / Gemini の使い分け。

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

@@ -0,0 +1,91 @@
+# Loop Builder
+
+**レールは Loop を実行します。** 組み込みの Loop（`Implement`、`Batch`、`Ultracode`）は日常的なケースをカバーしますが、**Loop Builder** を使えば自分だけの Loop を設計できます — 目標が達成されるまで繰り返す自動化のための、n8n スタイルのビジュアルエディターです。このページでは、Loop とは何か、どう作るのか、そしてレールでどう実行するのかを説明します。
+
+## Loop とレール — その関係
+
+**Loop** は作業の *レシピ* で、**レール** はそれをあなたのスペックに対して実行する *レーン* です。
+
+```
+   Loop Builder（左サイドバー）             レール（右）
+   ───────────────────────────             ─────────────
+   Implement   （組み込み）                  レール 1
+   Batch       （組み込み）      ► で選ぶ      Loop: Verify-until-green
+   Ultracode   （組み込み）                    ▶ Play
+   Verify-until-green （あなたの作ったもの）
+```
+
+- Loop は **Loops** セクション（左サイドバー、プロジェクトの隣）にあります — これらは **グローバル** で、すべてのプロジェクトで共有されます。
+- レールはヘッダー（Loop ピッカー）で **Loop を選び**、Play を押すとそれを実行します。
+- プロバイダー、モデル、推論の労力（reasoning effort）を決めるのは **レール** であって、Loop のステップではありません。同じ Loop が、レール次第で Claude、Codex、Gemini のいずれでも実行されます。
+
+つまり、Loop を一度作ってしまえば、どのプロジェクトのどのレールでもそれを選べます。
+
+## ビルダーを開く
+
+左サイドバーの **Loops** をクリックすると、ライブラリが表示されます。3 つの組み込み Loop に加えて、あなた自身の Loop が並びます。どれかを開いて中身を見るか、**New loop** をクリックして真っ白なキャンバスから始めます。
+
+組み込みの Loop を直接編集するのは簡単ではありません — 代わりに **Fork** します。そうすると、ちゃんと動くグラフの編集可能なコピーが手に入るので、そこから始められます。これが一番手っ取り早い学び方です。
+
+## Loop を構成するもの
+
+Loop は **ノード** を **エッジ**（矢印）でつないだグラフです。各ノードが 1 つのステップです。
+
+| ノード | 役割 |
+|------|--------------|
+| **Start** | 実行が始まる場所。1 つの Loop につきちょうど 1 つ。 |
+| **AI Step** | AI のターンを実行します — あなたが書くプロンプト、または `{{cmd:implement}}`、`{{cmd:verify}}`、`{{cmd:fix}}` のような *マジックコマンド*。ここで本物の作業が行われます。 |
+| **Shell** | シェルコマンド（例: `npm test`）を実行し、その出力を後続のステップ用にキャプチャします。 |
+| **Loop Decider** | Loop の頭脳。各パスで、あなたが書いた **目標（goal）** を読み、**continue**（ループバックしてもう一度試す）か **stop**（抜ける）かを判断します。*verify → fix → verify until green* を動かしているのがこれです。 |
+| **End** | 終端ノード。実行を成功または失敗としてマークします。 |
+
+エッジはステップを順番につなぎます。**Loop Decider** には **continue** と **stop** という 2 つのラベル付き出力があるので、「まだ終わっていない」を作業へ配線して戻し、「終わった」を End へ配線して出します。
+
+### ステップのテキストを書く
+
+AI Step や Decider の中では、次のものを参照できます。
+
+- **スペックデータ** — `{{spec.title}}`、`{{spec.description}}`、`{{spec.ids}}`（レールのチケット ID）。実行時にレール上のスペックから埋め込まれます。
+- **マジックコマンド** — `{{cmd:implement}}` とその仲間は、対応するパイプラインコマンドに展開されます。
+- **定数（Constants）** — `{{const:NAME}}` はグローバルな **定数ライブラリ** から値を引き込みます（パレットからドラッグして追加します）。検証の PASS/FAIL マーカーのような組み込みのセンチネルは常に利用できます。自分で追加して、すべての Loop で再利用することもできます。
+
+## Loop を有界に保つ
+
+止まらない Loop はお金を永遠に燃やし続けてしまうので、すべての実行に 3 つのガードがあります（ビルダーのツールバーで設定します）。
+
+| ガード | 役割 |
+|-------|--------------|
+| **Max iterations** | Decider が判断にかかわらずループバックできる回数のハードキャップ。 |
+| **Timeout (min)** | 実行全体に対する実時間（壁時計）の上限。 |
+| **Max cost ($)** | *任意。* 累積コストが予算を超えた時点で Loop を停止します。**ステップとステップの間** でチェックされるため（あるステップのコストはそれが終わってからしかわかりません）、1 ステップ分だけオーバーシュートすることがあります。Claude ではコストは正確で、Codex と Gemini では見積もりです。上限を設けないなら空のままにしておきます。 |
+
+## 自信を持って組み立てる
+
+ビルダーは、Loop が実行される前に正しく仕上げる手助けをしてくれます。
+
+- **ライブバリデーション** — 問題（Start がない、孤立したステップ、空のプロンプト、ブランチの欠けた Decider など）がキャンバス上と問題パネルにフラグ表示されます。
+- **ドライランプレビュー** — **何も起動せずに** 各ステップの正確なテキスト（スペックデータ、定数、コマンドがすべて展開された状態）を解決するので、各ステップが何を送ることになるのかを正確に確認できます。
+- **自動整列（Auto-arrange）** — キャンバスを縦・横・グリッドのいずれかにすっきり並べます。選択は Loop ごとに保存されます。
+- **コピー / ペースト** — `Cmd/Ctrl + C` / `V` で、Loop の内部や Loop をまたいでステップをコピーします。
+- **インポート / エクスポート** — Loop を `.json` ファイルに保存し、また読み込めます（名前が重複するものはスキップされ、残りはインポートされます）。
+- **ステップの名前変更** — 各ノードにカスタムラベルを付けて、グラフが読みやすくなるようにします。
+
+## 公開して実行する
+
+Loop は最初は **Draft** です。グラフが有効になったら **Publish** します — 公開された Loop が、レールの Loop ピッカーに表示されるものです。（削除せずに流通から外したいときは Unpublish します。）
+
+カスタム Loop を実行するには、
+
+1. プロジェクトを開いて、スペックをレールにドラッグします。
+2. レールヘッダーで **Loop ピッカー** を開き、公開したあなたの Loop を選びます。
+3. **▶ Play** を押します。
+
+実行は **ジョブ** ビューで、組み込みのレールジョブとまったく同じようにライブでストリーミングされます — 同じログ、同じメトリクス、同じコストトラッキングです。反復回数やコストの上限に達して停止した Loop は、ただの成功ではなく、その結果とともに報告されます。
+
+> **Loop の実行中の注意点。** いずれかの実行が動いている間は、その Loop を編集したり削除したりできません — 先に実行を止めてください。
+
+## 次に読むもの
+
+- [レールとジョブ](rails-and-jobs) — レールの起動とジョブのキュー。
+- [ジョブ詳細ビュー](the-job-detail-view) — 実行をライブで見守る。
+- [レールごとのエンジン選択](picking-an-engine-per-rail) — プロバイダーを選ぶのは（Loop ではなく）レール。

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

@@ -1,94 +1,99 @@
 # Rails e jobs
 
-Já tem specs no quadro. É aqui que elas se transformam em código. Um **rail** é a faixa que conduz uma spec por todo o pipeline — Architect → Developer → Reviewer → Ship — executando agentes de IA reais dentro da diretoria do seu projeto. Esta página cobre o lançamento de um rail, a fila de jobs e como acompanhar o trabalho a acontecer ao vivo.
+Você já tem specs no quadro. É aqui que elas viram código. Um **rail** é a pista que conduz uma spec por todo o pipeline — Architect → Developer → Reviewer → Ship — executando agentes de IA reais dentro do diretório do seu projeto. Esta página cobre como lançar um rail, a fila de jobs e como acompanhar o trabalho acontecendo ao vivo.
 
 ## O que é um rail
 
-Imagine o seu ecrã dividido em dois:
+Imagine sua tela dividida em duas:
 
 ```
 SpecsBoard (esquerda)       Rails (direita)
 ─────────────────           ─────────────────
 #1 Login flow      ─┐
-#2 Webhook retry    │  arrastar para
+#2 Webhook retry    │  arraste para
 #3 Cost limits      │ ────────────►   Rail 1   ▶ Play
 #4 Audit log        │
                     └────────────►   Rail 2   ▶ Play
 ```
 
-Um rail é uma **faixa de execução**. Arrasta um cartão de spec do SpecsBoard para um rail e depois carrega em **▶ Play**. O rail lança o pipeline e trabalha a spec de ponta a ponta, mesmo na diretoria de trabalho do seu projeto — editando ficheiros, correndo testes, tudo.
+Um rail é uma **pista de execução**. Você arrasta um cartão de spec do SpecsBoard para um rail e depois aperta **▶ Play**. O rail dispara o pipeline e trabalha a spec de ponta a ponta, bem no diretório de trabalho do seu projeto — editando arquivos, rodando testes, tudo.
 
-Pode ter vários rails para organizar o trabalho em faixas com nome (uma para a feature em que está focado, outra em fila atrás dela). Mais sobre múltiplos rails e batches em [Batch implement e multi-feature](batch-implement-and-multi-feature).
+Você pode ter vários rails para organizar o trabalho em pistas nomeadas (uma para a feature em que está focado, outra na fila atrás dela). Mais sobre multi-rail e batching em [Batch implement e multi-feature](batch-implement-and-multi-feature).
 
-## Lançar um rail sobre uma spec
+## Lançando um rail sobre uma spec
 
-1. **Arraste um cartão de spec** do SpecsBoard para um rail. O ID da spec aparece na lista de specs do rail. (Prefere não arrastar? Use o popover **Mover para um rail** no cartão de spec — mostra um ponto de estado por rail para que não largue trabalho numa faixa ocupada.)
-2. **Escolha um modo** se quiser algo diferente do default — o controlo segmentado no cabeçalho do rail oferece `Implement`, `Batch` e (apenas rails Claude) `Ultra`.
-3. **Carregue em ▶ Play.**
+1. **Arraste um cartão de spec** do SpecsBoard para um rail. O ID da spec aparece na lista de specs do rail. (Prefere não arrastar? Use o popover **Mover para o rail** no cartão da spec — ele mostra um indicador de status por rail, para você não soltar trabalho numa pista ocupada.)
+2. **Escolha um Loop** no cabeçalho do rail. Um rail roda um **Loop** — é o trabalho que ele realiza. O padrão é o Loop `Implement` embutido; você também pode escolher `Batch`, `Ultracode` ou um loop personalizado que você mesmo construiu. Veja [O Loop Builder](the-loop-builder).
+3. **Aperte ▶ Play.**
 
-É só isto. O rail arranca um processo de CLI de IA no seu projeto e inicia o pipeline.
+É isso. O rail sobe um processo de CLI de IA no seu projeto e começa o pipeline.
 
-### O que há no cabeçalho de um rail
+### O que tem no cabeçalho de um rail
 
-| Controlo | O que faz |
+| Controle | O que faz |
 |---------|--------------|
-| **Pílula de estado** | `idle`, `running` ou `failed`. Não há um "completed" separado — um rail volta a `idle` quando o seu job termina sem problemas. |
-| **Lista de specs** | Os IDs atribuídos a este rail. Arraste mais para dentro, arraste para fora para os desligar. |
-| **Controlo de modo** | `Implement` / `Batch` / `Ultra` — veja a tabela abaixo. Guardado por rail. |
-| **Seletor de perfil** | Que perfil de agentes corre (apenas rails Claude). Só aparece quando o projeto tem pelo menos um perfil. |
-| **Seletor de motor** | Que fornecedor instalado corre este rail — Claude, Codex ou Gemini. Só aparece quando o projeto tem mais do que um fornecedor. Veja [Escolher um motor por rail](picking-an-engine-per-rail). |
+| **Pílula de status** | `idle`, `running` ou `failed`. Não há um "completed" separado — um rail volta para `idle` quando seu job termina sem erros. |
+| **Lista de specs** | Os IDs atribuídos a este rail. Arraste mais para dentro, arraste para fora para desanexar. |
+| **Seletor de Loop** | O Loop que este rail roda — um embutido (`Implement` / `Batch` / `Ultracode`) ou um loop personalizado. Veja a tabela abaixo. Persistido por rail. |
+| **Seletor de perfil** | Qual perfil de agente roda (apenas rails Claude). Só aparece quando o projeto tem ao menos um perfil. |
+| **Seletor de motor** | Qual provedor instalado roda este rail — Claude, Codex ou Gemini. Só é renderizado quando o projeto tem mais de um provedor. Veja [Escolhendo um motor por rail](picking-an-engine-per-rail). |
 | **▶ Play / ■ Stop** | Iniciar ou cancelar. |
 
-### Os três modos de rail
+### O que um rail roda: Loops
 
-| Modo | Comando | O que faz |
+Um rail roda um **Loop** — a receita do trabalho. Três loops são **embutidos** e cobrem os casos comuns:
+
+| Loop embutido | Comando | O que faz |
 |------|---------|--------------|
-| **Implement** | `/specrails:implement` | Um único job que cobre todas as specs do rail. Corre o pipeline completo Architect → Developer → Reviewer → Ship. O default do dia a dia. |
-| **Batch** | `/specrails:batch-implement` | Um único job que trabalha as specs do rail sequencialmente, em ondas que respeitam as dependências. Ideal para várias specs relacionadas. |
-| **Ultra** | Ultracode | O Claude implementa cada spec de forma autónoma, **ignorando** o pipeline. Um job independente por spec. Só Claude. |
+| **Implement** | `/specrails:implement` | Um job cobrindo todas as specs do rail. Roda o pipeline completo Architect → Developer → Reviewer → Ship. O padrão do dia a dia. |
+| **Batch** | `/specrails:batch-implement` | Um job que percorre as specs do rail sequencialmente, em ondas que respeitam as dependências. Melhor para várias specs relacionadas. |
+| **Ultracode** | Ultracode | O Claude implementa cada spec de forma autônoma, **ignorando** o pipeline. Um job independente por spec. Apenas Claude. |
+
+O Ultracode é o caso atípico: ele pula a cadeia de agentes e entrega a spec crua ao Claude para trabalhar com suas ferramentas nativas. É aberto, então apertar Play abre primeiro uma confirmação, e um seletor de modelo por rail deixa você escolher Haiku / Sonnet / Opus. Ele só aparece quando o motor do rail é o Claude.
 
-O Ultra é o caso à parte: salta a cadeia de agentes e entrega ao Claude a spec em bruto para trabalhar com as suas ferramentas nativas. É aberto, por isso carregar em Play abre primeiro uma confirmação, e um seletor de modelo por rail deixa-o escolher Haiku / Sonnet / Opus. Só aparece quando o motor do rail é o Claude.
+Além dos embutidos, você pode **construir seus próprios loops** — repetir um ciclo verify → fix → verify até atingir uma meta, encadear comandos de shell entre AI Steps e muito mais. Esses loops personalizados aparecem no mesmo seletor de Loop. Essa é a próxima grande ideia: [O Loop Builder](the-loop-builder).
 
 ## A fila de jobs
 
-Sempre que carrega em Play, a execução do rail torna-se um **job**. A regra mais importante para interiorizar:
+Toda vez que você aperta Play, a execução do rail vira um **job**. A regra mais importante para internalizar:
 
-> **Um job de cada vez, por projeto.** Cada projeto tem uma única fila. Dentro de um projeto, só um job de rail corre de cada vez — os restantes ficam em fila atrás dele e arrancam automaticamente à medida que se libertam slots.
+> **Um job de cada vez, por projeto.** Cada projeto tem uma única fila. Dentro de um projeto, só um job de rail roda por vez — o resto fica na fila atrás dele e inicia automaticamente conforme os slots ficam livres.
 
-Isto surpreende quem adiciona três rails à espera de que corram em paralelo. Não correm — não dentro do mesmo projeto. Adicionar rails *organiza* o seu trabalho em faixas; não faz com que essas faixas corram em simultâneo.
+Isso surpreende quem adiciona três rails esperando que rodem em paralelo. Eles não vão — não dentro do mesmo projeto. Adicionar rails *organiza* seu trabalho em pistas; isso não faz essas pistas rodarem de forma concorrente.
 
-**O paralelismo real é entre projetos.** Cada projeto tem a sua fila independente, por isso um rail no Projeto A e um rail no Projeto B correm ao mesmo tempo sem disputar recursos. Quer mais throughput? Abra mais projetos.
+**O paralelismo de verdade é entre projetos.** Cada projeto tem sua própria fila independente, então um rail no Projeto A e um rail no Projeto B rodam ao mesmo tempo sem disputar recursos. Quer mais throughput? Abra mais projetos.
 
-Não há um botão global de concorrência para afinar. O único limitador automático é baseado no orçamento: se definiu um orçamento diário (do projeto ou da app), a fila pausa automaticamente assim que o gasto desse dia atinge o limite.
+Não há um botão global de concorrência para ajustar. O único limite automático é baseado em orçamento: se você definiu um orçamento diário (do projeto ou da app), a fila se autopausa assim que o gasto do dia atinge o teto.
 
-## Acompanhar a execução
+## Acompanhando a execução
 
-Encontra todos os jobs em **Jobs**, na barra lateral direita do projeto — uma lista de cartões, do mais recente para o mais antigo. Cada cartão mostra um selo de estado, o selo do perfil, um selo de prioridade, a duração, o custo e o comando lançado. Por cima da lista:
+Encontre todos os jobs em **Jobs**, na barra lateral direita do projeto — uma lista de cartões, os mais recentes primeiro. Cada cartão mostra um selo de status, o selo de perfil, um selo de prioridade, duração, custo e o comando lançado. Acima da lista:
 
-- **Chips de filtro por estado** — mostram apenas os jobs num dado estado.
-- **Filtro por intervalo de datas** — restringe a uma janela temporal.
-- **Comparar** — escolhe dois jobs e vê-os lado a lado.
+- **Chips de filtro de status** — mostram apenas jobs em um dado status.
+- **Filtro por intervalo de datas** — restringe a uma janela de tempo.
+- **Comparar** — escolha dois jobs e veja-os lado a lado.
 
-Clique em qualquer cartão para abrir a **vista de detalhe do job**, onde vivem o log em streaming ao vivo e as métricas ao vivo. É a próxima página: [A vista de detalhe do job](the-job-detail-view).
+Clique em qualquer cartão para abrir a **vista de detalhe do Job**, onde ficam o log em streaming ao vivo e as métricas ao vivo. Essa é a próxima página: [A vista de detalhe do job](the-job-detail-view).
 
-## Cancelar um job
+## Cancelando um job
 
-Carregue em **■ Stop** no cabeçalho do rail. A app envia `SIGTERM` ao subprocesso, espera **5 segundos** por uma saída limpa e depois faz `SIGKILL`. Nada fica criado pela metade.
+Clique em **■ Stop** no cabeçalho do rail. A app envia `SIGTERM` ao subprocesso, espera **5 segundos** por uma saída limpa e então faz `SIGKILL`. Nada fica spawnado pela metade.
 
-## Se um rail não arrancar
+## Se um rail não lançar
 
-Se escolher um motor cuja CLI não está instalada na sua máquina, o lançamento **falha de imediato** em vez de iniciar um job partido — nada é criado. Instale a CLI do fornecedor em falta ([Usar o Codex](../integrations/using-codex), [Usar o Gemini](../integrations/using-gemini)) e lance de novo. A falta de Claude ou Codex devolve uma mensagem precisa "*<provider> CLI not found*"; a falta de Gemini mostra hoje um erro de lançamento genérico, mas o resultado é o mesmo.
+Se você escolher um motor cuja CLI não está instalada na sua máquina, o lançamento **falha rápido** em vez de iniciar um job quebrado — nada é spawnado. Instale a CLI do provedor que falta ([Usando Codex](../integrations/using-codex), [Usando Gemini](../integrations/using-gemini)) e lance de novo. Claude ou Codex ausentes dão uma mensagem precisa "*<provider> CLI not found*"; o Gemini ausente exibe um erro genérico de lançamento por enquanto, mas o resultado é o mesmo.
 
-## Parar tudo
+## Parando tudo
 
 Se algo parecer errado:
 
-- **Um rail** — carregue em **■ Stop** no seu cabeçalho.
-- **Auto-pausa por orçamento** — defina um orçamento diário e a fila pausa-se a si própria quando o gasto desse dia atinge o limite.
-- **Tudo** — feche a app desktop, ou execute `specrails-desktop stop`.
+- **Um rail** — clique em **■ Stop** no cabeçalho dele.
+- **Autopausa por orçamento** — defina um orçamento diário e a fila se pausa sozinha quando o gasto do dia atinge o teto.
+- **Tudo** — feche o app desktop, ou rode `specrails-desktop stop`.
 
-## Para onde ir a seguir
+## Para onde ir agora
 
+- [O Loop Builder](the-loop-builder) — o que um rail roda, e como construir seus próprios loops.
 - [A vista de detalhe do job](the-job-detail-view) — fases, métricas ao vivo, cartões de ticket.
-- [Batch implement e multi-feature](batch-implement-and-multi-feature) — correr várias specs ao mesmo tempo.
-- [Escolher um motor por rail](picking-an-engine-per-rail) — Claude vs Codex vs Gemini.
+- [Batch implement e multi-feature](batch-implement-and-multi-feature) — rode várias specs de uma vez.
+- [Escolhendo um motor por rail](picking-an-engine-per-rail) — Claude vs Codex vs Gemini.

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

@@ -0,0 +1,91 @@
+# O Loop Builder
+
+Um **rail roda um Loop**. Os loops embutidos (`Implement`, `Batch`, `Ultracode`) cobrem os casos do dia a dia, mas o **Loop Builder** deixa você desenhar os seus próprios — um editor visual, no estilo n8n, para automação que se repete até atingir uma meta. Esta página explica o que é um loop, como construir um e como rodá-lo em um rail.
+
+## Loops e rails — a relação
+
+Um **loop** é a *receita* do trabalho; um **rail** é a *pista* que o roda contra as suas specs.
+
+```
+   Loop Builder (barra lateral esq.)        Rails (direita)
+   ───────────────────────────             ─────────────
+   Implement   (embutido)                  Rail 1
+   Batch       (embutido)      escolha ►      Loop: Verify-until-green
+   Ultracode   (embutido)                     ▶ Play
+   Verify-until-green (seu)
+```
+
+- Os loops vivem na seção **Loops** (barra lateral esquerda, ao lado dos seus projetos) — eles são **globais**, compartilhados por todos os projetos.
+- Um rail **escolhe um loop** no cabeçalho (o seletor de Loop) e o roda quando você aperta Play.
+- O **rail** decide o provedor, o modelo e o esforço de raciocínio — *não* os passos do loop. O mesmo loop roda em Claude, Codex ou Gemini dependendo do rail.
+
+Ou seja: construa um loop uma vez e depois escolha-o em qualquer rail, em qualquer projeto.
+
+## Abrindo o builder
+
+Clique em **Loops** na barra lateral esquerda para ver a biblioteca: os três loops embutidos mais os seus próprios. Abra um para vê-lo, ou clique em **New loop** para começar de uma tela em branco.
+
+Você não consegue editar um embutido diretamente com facilidade — em vez disso, faça **Fork** dele. Isso te dá uma cópia editável de um grafo que funciona como ponto de partida, que é a forma mais fácil de aprender.
+
+## Do que um loop é feito
+
+Um loop é um grafo de **nós** conectados por **arestas** (as setas). Cada nó é um passo:
+
+| Nó | O que faz |
+|------|--------------|
+| **Start** | Onde a execução começa. Exatamente um por loop. |
+| **AI Step** | Roda um turno de IA — um prompt que você escreve, ou um *comando mágico* como `{{cmd:implement}}`, `{{cmd:verify}}`, `{{cmd:fix}}`. É aqui que o trabalho de verdade acontece. |
+| **Shell** | Roda um comando de shell (ex.: `npm test`) e captura sua saída para passos posteriores. |
+| **Loop Decider** | O cérebro de um loop. A cada passagem ele lê uma **meta** que você escreve e decide **continue** (voltar e tentar de novo) ou **stop** (sair). É isto que faz funcionar o *verify → fix → verify até ficar verde*. |
+| **End** | Um nó terminal. Marca a execução como sucesso ou falha. |
+
+As arestas conectam os passos em ordem. O **Loop Decider** tem duas saídas rotuladas — **continue** e **stop** — então você liga o "ainda não terminei" de volta ao trabalho e o "terminei" para um End.
+
+### Escrevendo o texto dos passos
+
+Dentro de qualquer AI Step ou Decider você pode referenciar:
+
+- **Dados da spec** — `{{spec.title}}`, `{{spec.description}}`, `{{spec.ids}}` (os IDs dos tickets do rail). Preenchidos a partir da(s) spec(s) do rail em tempo de execução.
+- **Comandos mágicos** — `{{cmd:implement}}` e seus companheiros expandem para o comando de pipeline correspondente.
+- **Constantes** — `{{const:NAME}}` puxa da **biblioteca de constantes** global (arraste-as da paleta). Sentinelas embutidos como os marcadores de PASS/FAIL da verificação estão sempre disponíveis; você pode adicionar os seus e reutilizá-los em todos os loops.
+
+## Mantendo um loop limitado
+
+Um loop que nunca para queimaria dinheiro para sempre, então toda execução tem três proteções (definidas na barra de ferramentas do builder):
+
+| Proteção | O que faz |
+|-------|--------------|
+| **Max iterations** | Teto rígido de quantas vezes o Decider pode voltar atrás, independentemente do seu veredito. |
+| **Timeout (min)** | Limite de tempo de relógio para toda a execução. |
+| **Max cost ($)** | *Opcional.* Para o loop quando o custo acumulado cruza o seu orçamento. Verificado **entre passos** (o custo de um passo só é conhecido quando ele termina), então pode ultrapassar em um passo. No Claude o custo é exato; no Codex e no Gemini é uma estimativa. Deixe vazio para não ter teto. |
+
+## Construindo com confiança
+
+O builder ajuda você a acertar um loop antes mesmo de ele rodar:
+
+- **Validação ao vivo** — problemas (sem Start, um passo órfão, um prompt vazio, um Decider com ramos faltando) são sinalizados na tela e em um painel de problemas.
+- **Pré-visualização de dry-run** — resolve o texto exato de cada passo (dados da spec, constantes e comandos todos expandidos) **sem spawnar nada**, para você ver com precisão o que cada passo enviaria.
+- **Auto-arrange** — organize a tela na vertical, na horizontal ou em grade; sua escolha é salva por loop.
+- **Copiar / colar** — `Cmd/Ctrl + C` / `V` para copiar passos dentro de um loop ou entre loops.
+- **Importar / exportar** — salve loops em um arquivo `.json` e importe-os de volta (nomes duplicados são ignorados, o resto é importado).
+- **Renomear passos** — dê a cada nó um rótulo personalizado para que o grafo fique legível.
+
+## Publicando e rodando
+
+Um loop começa como um **Draft**. Quando o grafo está válido, faça **Publish** — os loops publicados são os que aparecem no seletor de Loop de um rail. (Faça Unpublish para tirá-lo de circulação sem apagá-lo.)
+
+Para rodar um loop personalizado:
+
+1. Abra um projeto e arraste uma spec para um rail.
+2. No cabeçalho do rail, abra o **seletor de Loop** e escolha o seu loop publicado.
+3. Aperte **▶ Play**.
+
+A execução transmite ao vivo na vista **Jobs**, exatamente como um job de rail embutido — mesmos logs, mesmas métricas, mesmo rastreamento de custo. Um loop que para porque atingiu seu teto de iterações ou de custo é reportado com esse resultado, em vez de um simples sucesso.
+
+> **Atenção enquanto um loop roda.** Você não pode editar nem apagar um loop enquanto uma de suas execuções está rodando — pare a execução primeiro.
+
+## Para onde ir agora
+
+- [Rails e jobs](rails-and-jobs) — lançando rails e a fila de jobs.
+- [A vista de detalhe do job](the-job-detail-view) — acompanhando uma execução ao vivo.
+- [Escolhendo um motor por rail](picking-an-engine-per-rail) — o rail (não o loop) escolhe o provedor.

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

@@ -7,10 +7,10 @@
 可以把你的屏幕想象成左右两半：
 
 ```
-SpecsBoard (left)            Rails (right)
+SpecsBoard (左)             Rails (右)
 ─────────────────            ─────────────────
 #1 Login flow      ─┐
-#2 Webhook retry    │  drag onto
+#2 Webhook retry    │  拖拽到
 #3 Cost limits      │ ────────────►   Rail 1   ▶ Play
 #4 Audit log        │
                     └────────────►   Rail 2   ▶ Play
@@ -23,7 +23,7 @@ rail 是一条**执行通道**。你从 SpecsBoard 上拖一张 spec 卡片放
 ## 在某个 spec 上启动一条 rail
 
 1. **把一张 spec 卡片拖**到某条 rail 上。该 spec 的 ID 会出现在这条 rail 的 spec 列表里。（不想拖？用 spec 卡片上的 **放入 Rail** 弹窗——它会为每条 rail 显示一个状态圆点，避免你把活儿丢进一条正忙的通道。）
-2. 如果你不想用默认模式，就**挑一个模式**——rail 头部的分段控件提供了 `Implement`、`Batch`，以及（仅限 Claude rail 的）`Ultra`。
+2. **在 rail 头部挑一个 Loop。** 一条 rail 运行的是一个 **Loop**——也就是它要做的活儿。默认是内置的 `Implement` loop；你也可以挑 `Batch`、`Ultracode`，或者你自己搭的某个自定义 loop。见 [Loop Builder](the-loop-builder)。
 3. **按下 ▶ Play。**
 
 就这么简单。rail 会在你的项目里启动一个 AI CLI 进程，开始跑流水线。
@@ -34,20 +34,24 @@ rail 是一条**执行通道**。你从 SpecsBoard 上拖一张 spec 卡片放
 |---------|--------------|
 | **状态标签** | `idle`、`running` 或 `failed`。这里没有单独的"completed"——任务干净地跑完后，rail 会回到 `idle`。 |
 | **spec 列表** | 分配给这条 rail 的 ID。可以再拖进来，也可以拖出去解除关联。 |
-| **模式控件** | `Implement` / `Batch` / `Ultra`——见下表。按 rail 单独记忆。 |
+| **Loop 选择器** | 这条 rail 运行的 Loop——内置的（`Implement` / `Batch` / `Ultracode`）或某个自定义 loop。见下表。按 rail 单独记忆。 |
 | **Profile 选择器** | 运行哪个 Agent Profile（仅限 Claude rail）。只有当项目至少有一个 Profile 时才会出现。 |
 | **引擎选择器** | 这条 rail 用哪个已安装的提供方来跑——Claude、Codex 或 Gemini。仅当项目装有不止一个提供方时才显示。见 [为每条 rail 选择引擎](picking-an-engine-per-rail)。 |
 | **▶ Play / ■ Stop** | 启动或取消。 |
 
-### 三种 rail 模式
+### rail 运行的是什么：Loop
 
-| 模式 | 命令 | 作用 |
+一条 rail 运行的是一个 **Loop**——干活的配方。有三个 loop 是**内置**的，覆盖了常见情况：
+
+| 内置 loop | 命令 | 作用 |
 |------|---------|--------------|
 | **Implement** | `/specrails:implement` | 一个任务覆盖这条 rail 上的所有 spec。跑完整的 Architect → Developer → Reviewer → Ship 流水线。日常默认选项。 |
 | **Batch** | `/specrails:batch-implement` | 一个任务，按依赖感知的批次（wave）依次处理 rail 上的各个 spec。最适合一组相关的 spec。 |
-| **Ultra** | Ultracode | Claude 自主实现每个 spec，**绕过**流水线。每个 spec 一个独立任务。仅限 Claude。 |
+| **Ultracode** | Ultracode | Claude 自主实现每个 spec，**绕过**流水线。每个 spec 一个独立任务。仅限 Claude。 |
+
+Ultracode 是个特例：它跳过 Agent 链条，把原始 spec 直接交给 Claude，让它用自己的原生工具去做。因为它比较"放飞"，所以按下 Play 会先弹出一个确认框，而且有一个按 rail 单独的模型选择器，让你在 Haiku / Sonnet / Opus 之间挑选。只有当 rail 的引擎是 Claude 时它才会出现。
 
-Ultra 是个特例：它跳过 Agent 链条，把原始 spec 直接交给 Claude，让它用自己的原生工具去做。因为它比较"放飞"，所以按下 Play 会先弹出一个确认框，而且有一个按 rail 单独的模型选择器，让你在 Haiku / Sonnet / Opus 之间挑选。只有当 rail 的引擎是 Claude 时它才会出现。
+除了这些内置 loop，你还可以**搭建自己的 loop**——重复一个 verify → fix → verify 的循环直到目标达成、在 AI 步骤之间串联 shell 命令，等等。这些自定义 loop 会出现在同一个 Loop 选择器里。这就是下一个大点子：[Loop Builder](the-loop-builder)。
 
 ## 任务队列
 
@@ -89,6 +93,7 @@ Ultra 是个特例：它跳过 Agent 链条，把原始 spec 直接交给 Claude
 
 ## 接下来去哪儿
 
+- [Loop Builder](the-loop-builder)——rail 运行的是什么，以及如何搭建你自己的 loop。
 - [任务详情视图](the-job-detail-view)——阶段、实时指标、工单卡片。
 - [批量实现与多功能](batch-implement-and-multi-feature)——一次跑多个 spec。
 - [为每条 rail 选择引擎](picking-an-engine-per-rail)——Claude、Codex 还是 Gemini。