specrails-desktop 2.8.0 → 2.9.0

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

@@ -0,0 +1,94 @@
+# レールとジョブ
+
+ボードにスペックがそろいました。ここからが、それを実際のコードに変えていく場所です。**レール**は、スペックをパイプライン全体（Architect → Developer → Reviewer → Ship）に通していくためのレーンで、本物の AI エージェントをあなたのプロジェクトディレクトリの中で動かします。このページでは、レールの起動、ジョブのキュー、そして作業がライブで進んでいく様子の見方を紹介します。
+
+## レールとは
+
+画面が左右に分かれているところを思い浮かべてください。
+
+```
+SpecsBoard（左）            レール（右）
+─────────────────            ─────────────────
+#1 Login flow      ─┐
+#2 Webhook retry    │  ドラッグして
+#3 Cost limits      │ ────────────►   レール 1   ▶ Play
+#4 Audit log        │
+                    └────────────►   レール 2   ▶ Play
+```
+
+レールは**実行レーン**です。SpecsBoard からスペックカードをレールにドラッグし、**▶ Play** を押します。するとレールがパイプラインを起動し、あなたのプロジェクトの作業ディレクトリの中で、ファイルの編集やテストの実行まで含めて、スペックを最初から最後までやり遂げます。
+
+レールは複数持てるので、名前付きのレーンとして作業を整理できます（いま集中している機能用のレールと、その後ろに控えさせておくレールといった具合に）。複数レールやバッチ処理については [バッチ実装とマルチフィーチャー](batch-implement-and-multi-feature) で詳しく説明します。
+
+## スペックでレールを起動する
+
+1. **スペックカードをドラッグ**して、SpecsBoard からレールへ移します。スペックの ID がそのレールのスペック一覧に表示されます。（ドラッグが苦手ですか？ スペックカードの **レールに移動** ポップオーバーを使えば、レールごとにステータスのドットが表示されるので、ふさがっているレーンに作業を落としてしまう心配がありません。）
+2. デフォルト以外にしたいときは、**モードを選びます** — レールヘッダーのセグメントコントロールで `Implement`、`Batch`、そして（Claude レール限定で）`Ultra` を選べます。
+3. **▶ Play を押します。**
+
+これだけです。レールがあなたのプロジェクト内で AI CLI プロセスを立ち上げ、パイプラインを開始します。
+
+### レールヘッダーにあるもの
+
+| コントロール | 役割 |
+|---------|--------------|
+| **ステータスピル** | `idle`、`running`、`failed` のいずれか。「completed」という別ステータスはありません — ジョブがきれいに完了すると、レールは `idle` に戻ります。 |
+| **スペック一覧** | このレールに割り当てられた ID。さらにドラッグして追加したり、ドラッグして外したりできます。 |
+| **モードコントロール** | `Implement` / `Batch` / `Ultra` — 下の表を参照してください。レールごとに保持されます。 |
+| **プロファイルピッカー** | どのエージェントプロファイルを実行するか（Claude レール限定）。プロジェクトにプロファイルが 1 つ以上あるときだけ表示されます。 |
+| **エンジンセレクター** | このレールをどのインストール済みプロバイダーで実行するか — Claude、Codex、Gemini。プロジェクトに複数のプロバイダーがある場合だけ表示されます。[レールごとのエンジン選択](picking-an-engine-per-rail) を参照してください。 |
+| **▶ Play / ■ Stop** | 開始またはキャンセル。 |
+
+### 3 つのレールモード
+
+| モード | コマンド | 役割 |
+|------|---------|--------------|
+| **Implement** | `/specrails:implement` | レール上のすべてのスペックをまとめた 1 つのジョブ。Architect → Developer → Reviewer → Ship のフルパイプラインを実行します。日常的に使うデフォルトです。 |
+| **Batch** | `/specrails:batch-implement` | レール上のスペックを、依存関係を考慮したウェーブで順番に処理する 1 つのジョブ。関連する複数のスペックに最適です。 |
+| **Ultra** | Ultracode | Claude が各スペックをパイプラインを**バイパス**して自律的に実装します。スペックごとに独立したジョブが 1 つずつ作られます。Claude 専用。 |
+
+Ultra は少し毛色が違います。エージェントチェーンを飛ばし、生のスペックを Claude に渡してネイティブツールで作業させます。自由度が高いぶん、Play を押すとまず確認ダイアログが開き、レールごとのモデルピッカーで Haiku / Sonnet / Opus を選べます。Ultra はレールのエンジンが Claude のときだけ表示されます。
+
+## ジョブのキュー
+
+Play を押すたびに、そのレールの実行は **ジョブ** になります。ぜひ頭に入れておいてほしい一番大事なルールがこれです。
+
+> **1 プロジェクトにつき、同時に動くジョブは 1 つだけ。** 各プロジェクトはキューを 1 つ持っています。1 つのプロジェクト内では、レールのジョブは一度に 1 つしか実行されません — 残りはその後ろで待機し、スロットが空くと自動的に開始されます。
+
+レールを 3 つ追加すれば並列で動くと思っていた人は、たいてい驚きます。同じプロジェクト内では並列にはなりません。レールを追加するのは作業をレーンに**整理する**ためで、それらのレーンを同時に走らせるためのものではありません。
+
+**本当の並列処理はプロジェクトをまたいで行われます。** 各プロジェクトは独立したキューを持つので、プロジェクト A のレールとプロジェクト B のレールは、互いに競合することなく同時に動きます。もっとスループットがほしいですか？ プロジェクトをもっと開きましょう。
+
+調整できるグローバルな同時実行のつまみはありません。唯一の自動スロットルは予算ベースのものです。1 日の予算（プロジェクト単位またはアプリ全体）を設定していれば、その日の支出が上限に達した時点でキューが自動的に一時停止します。
+
+## 実行を見守る
+
+すべてのジョブは、プロジェクトの右サイドバーの **ジョブ** から確認できます — 新しいものが上に来るカードのリストです。各カードには、ステータスバッジ、プロファイルバッジ、優先度バッジ、所要時間、コスト、起動したコマンドが表示されます。リストの上部には次のものがあります。
+
+- **ステータスフィルターチップ** — 指定したステータスのジョブだけを表示します。
+- **日付範囲フィルター** — 期間で絞り込みます。
+- **比較** — 2 つのジョブを選んで並べて表示します。
+
+どれかのカードをクリックすると **ジョブ詳細ビュー** が開きます。ここにライブのストリーミングログとライブのメトリクスがあります。それが次のページ、[ジョブ詳細ビュー](the-job-detail-view) です。
+
+## ジョブをキャンセルする
+
+レールヘッダーの **■ Stop** をクリックします。アプリはサブプロセスに `SIGTERM` を送り、**5 秒間** クリーンな終了を待ってから `SIGKILL` します。中途半端に生成されたものが残ることはありません。
+
+## レールが起動しないとき
+
+CLI がマシンにインストールされていないエンジンを選ぶと、起動は壊れたジョブを始めるのではなく **即座に失敗** します — 何も生成されません。足りないプロバイダー CLI をインストールして（[Codex を使う](../integrations/using-codex)、[Gemini を使う](../integrations/using-gemini)）、もう一度起動してください。Claude や Codex が見つからない場合は「*<provider> CLI not found*」という正確なメッセージが出ます。Gemini が見つからない場合は現時点では一般的な起動エラーが表示されますが、結果は同じです。
+
+## すべてを止める
+
+何かおかしいと感じたら、
+
+- **1 つのレール** — そのヘッダーの **■ Stop** をクリック。
+- **予算による自動一時停止** — 1 日の予算を設定しておけば、その日の支出が上限に達した時点でキューが自動で一時停止します。
+- **すべて** — デスクトップアプリを終了するか、`specrails-desktop stop` を実行します。
+
+## 次に読むもの
+
+- [ジョブ詳細ビュー](the-job-detail-view) — フェーズ、ライブメトリクス、チケットカード。
+- [バッチ実装とマルチフィーチャー](batch-implement-and-multi-feature) — 複数のスペックをまとめて実行する。
+- [レールごとのエンジン選択](picking-an-engine-per-rail) — Claude / Codex / Gemini の使い分け。

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

@@ -0,0 +1,90 @@
+# ジョブ詳細ビュー
+
+**ジョブ** ページでどれかのジョブカードをクリックすると、ここにたどり着きます。1 回のレール実行のためのコックピットです。このビューはたった 1 つの約束を軸に作られています — **あなたが目にするライブの数値は本物であり、決して推測ではありません。** このページでは、フェーズ、ライブメトリクス、チケットカードをひととおり見ていきます。
+
+## レイアウト
+
+ストリーミングログ全体の上に、2 つのパネルが並びます。
+
+```
+┌─────────────────────────────────────────────┐
+│  ステータスヘッダー  (アイコン · ライブ所要時間 · …)  │
+├─────────────────────────────────────────────┤
+│  チケットヘッダー  ( #12  #14  #15 )           │
+├─────────────────────────────────────────────┤
+│                                             │
+│  ストリーミングログ  (自動スクロール · 検索 · …)  │
+│                                             │
+└─────────────────────────────────────────────┘
+```
+
+## パイプラインのフェーズ
+
+`Implement` と `Batch` のジョブでは、スラッシュコマンドが定義するフェーズに沿って実行が進みます — デフォルトでは次のとおりです。
+
+```
+Architect ──► Developer ──► Reviewer ──► Ship
+```
+
+各フェーズは、レールのエンジンがあなたのプロジェクトディレクトリ内で呼び出す専用エージェントです。
+
+| フェーズ | エージェント | 役割 |
+|-------|-------|--------------|
+| **Architect** | `sr-architect` | 実装を設計します。 |
+| **Developer** | `sr-developer` | コードを書きます。 |
+| **Reviewer** | `sr-reviewer` | 出力をレビューします。 |
+| **Ship** | （状況による） | 最終仕上げ: テスト、コミット、PR ドラフト。 |
+
+どのフェーズをどのエージェントが担当するかは、プロジェクトの **エージェントプロファイル** で決まります。基本の 3 つ（`sr-architect`、`sr-developer`、`sr-reviewer`）は常に存在し、プロファイル内のルーティングルールでエージェントを追加したり、あるフェーズを担当するエージェントを差し替えたりできます。フェーズの進捗バーは、コマンドが実際にフェーズを定義しているときだけ表示されます — パイプラインをバイパスする Ultracode ジョブでは表示されません。
+
+## ライブメトリクス — 設計からして誠実
+
+ステータスヘッダーが主役です。ステータスアイコン、ジョブが*いままさに*何をしているかを表すアクティビティ行、踏んだステップ数、そしてメトリクスの一行が表示されます。
+
+| メトリクス | 本物の値が見えるタイミング |
+|--------|------------------------------|
+| **所要時間** | **ライブ。** ジョブの実行中、1 秒ごとのティッカーがカウントアップします — これが唯一、純粋にライブな数値です。 |
+| **ターン数** | 届いたストリーミングのアシスタントイベントから逐次的に算出されます。 |
+| **トークン** | 同じストリームから逐次的に集計されます（usage フィールドが欠けているイベントにも耐えます）。 |
+| **コスト** | ジョブが終了するまで `—` と表示され、終了時に信頼できる `total_cost_usd` として明かされます。 |
+
+設計思想はこうです — **実行中に概算値や推定値を出さない。** 所要時間が本物なのは、それがただの時計だからです。ターン数とトークンは、実際にストリーミングされたアクティビティから積み上げられます。コストは実行中はあえて推定しません — 保留として表示し、ジョブ終了時にプロバイダーが報告して初めて、最終的で信頼できる数値に確定します。数値が待機しているように見えるなら、それは意図したものです — あなたに見せているのは予測ではなく真実なのです。
+
+ヘッダーのラベルとアイコンはジョブのステータスに対応し、このパネルは `running`、`completed`、`failed` のいずれのジョブでも描画されます — つまり、終わったジョブの詳細ビューでも、最終値で固定された同じメトリクスが見られます。
+
+## チケットカード
+
+**チケットヘッダー** は、ステータスヘッダーとログの間にあります。これはプレミアムな識別カードで、ジョブが触れたすべてのスペックのチップを表示します — 起動したコマンドから照合されるので、この実行がどのチケットに関するものだったかを正確に反映します。
+
+- **2〜3 件のチケット** — チップのリストとして表示されます。
+- **4 件以上** — コンパクトな `+ N more` 表示に折りたたまれ、展開用のシェブロンが付くので、ヘッダーがすっきりと保たれます。
+
+チップをクリックすると、そのスペックの詳細が **ジョブページの上に重ねて** 開きます — 自分の居場所を見失うことも、ルートが変わることもありません。ジョブが何を届けるはずなのかを、作業を見守りながらサッと読み返すのに便利です。（タブレット幅の画面では、チケットモーダルを横にドラッグして 2 つのスペックを並べて比較することもできます。）
+
+## ストリーミングログ
+
+パネルの下には、WebSocket 越しにリアルタイムでストリーミングされる実行の全ログがあります。
+
+- **自動スクロール** で最新の出力を視界に保ちます（上にスクロールすると一時停止するので、じっくり読めます）。
+- **検索** でフレーズへジャンプできます。
+- **コピー** でログ全体をつかめます。
+
+これは AI が何をしているかの生の真実です — すべてのツール呼び出し、すべてのファイル編集、すべてのテスト実行が映ります。
+
+## 診断のエクスポート
+
+そのジョブで [テレメトリ](../settings/customizing) が有効になっていた場合、ヘッダーに **診断をエクスポート** ボタンが表示されます。クリックすると次のものを含む ZIP がダウンロードされます。
+
+- `job-metadata.json` — コマンド、ステータス、プロファイル、プラグイン。
+- `telemetry.ndjson` — 非圧縮の OTLP/JSON シグナル。
+- `logs.txt` — ストリーミングログの全文。
+- `summary.md` — 人が読みやすいハイライト。
+- `profile.json`、`plugins.json` — 実際に動いたものの正確なスナップショット（存在する場合）。
+
+実行内容を仲間と共有したり、正確なバグレポートを提出したりするのに便利です。
+
+## 次に読むもの
+
+- [レールとジョブ](rails-and-jobs) — 起動とキューイング。
+- [バッチ実装とマルチフィーチャー](batch-implement-and-multi-feature) — 多数のスペックと依存ウェーブ。
+- [コストの追跡](../analytics/tracking-cost) — ジョブごとのコストをプロジェクト分析へ。

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

@@ -0,0 +1,78 @@
+# バッチ実装とマルチフィーチャー
+
+1 つずつスペックを進めるのも悪くありませんが、実際の作業はまとまってやってくることが多いものです — ある機能とそのテストとマイグレーション、あるいは一気に片づけてしまいたいバックログ、といった具合に。このページでは、複数のスペックをまとめて実行する方法を扱います — バッチモード、依存ウェーブ、そして同時並行の作業が衝突しないようパイプラインがどう守っているか、です。
+
+## 複数のスペックを一度に実行する
+
+1 つのレールから大量のスペックを実行する一番シンプルな方法が **バッチ** モードです。
+
+1. 実行したいスペックを**すべて 1 つのレールにドラッグ**します。そのレールのスペック一覧に積み上がっていきます。
+2. **レールのモードを Batch に切り替えます**（レールヘッダーのセグメントコントロール）。
+3. **▶ Play を押します。**
+
+レールは **1 つ** の `/specrails:batch-implement` ジョブを起動し、割り当てられたすべてのスペックを順に処理します。他のジョブと同じようにジョブページで監視できます — スペックごとに別ジョブが立つのではなく、セット全体をカバーする 1 つのジョブです。
+
+これが効いてくるのは、**1 プロジェクトにつきジョブは 1 つ** というキューがあるからです。プロジェクトは一度に 1 つのレールジョブしか実行しないので、バッチモードは複数のレールを抱え込んで一つひとつ空くのを待たずに、スペックのリストを*連鎖的に*処理する一番すっきりした方法でもあります。
+
+### Implement と Batch — どちらのモード？
+
+| | **Implement** | **Batch** |
+|---|---|---|
+| コマンド | `/specrails:implement` | `/specrails:batch-implement` |
+| ジョブあたりのスペック | レール上のすべてを 1 つの作業単位として扱う | レール上のすべてを**順番に**処理 |
+| 向いている場面 | 密に結合した 1 つの変更 | 順番に片づけたい複数の独立した機能 |
+| 順序 | 該当なし | 依存関係を考慮したウェーブ（下記参照） |
+
+スペックが本当に 1 つの変更なら **Implement** を使ってください。別々の機能のリストなら **Batch** を使って、順序づけは任せてしまいましょう。
+
+## 依存ウェーブ
+
+バッチモードはスペックを上から下へ流すだけではありません — **依存関係を考慮した実行順序** を計算し、スペックを*ウェーブ*にまとめます。オーケストレーター（`/specrails:batch-implement`）がどのスペックがどのスペックに依存するかを見極め、土台となる作業より先に何も走らないようにスケジュールします。
+
+イメージとしては、
+
+```
+ウェーブ 1:  #2 (データモデル)        ← 依存なし、最初に実行
+ウェーブ 2:  #4 (モデル上の API)       ← #2 を待つ
+            #5 (モデル上の CLI)       ← #2 を待つ
+ウェーブ 3:  #7 (全体のドキュメント)    ← #4 と #5 を待つ
+```
+
+ジョブ内では、各ウェーブのスペックが実装されてから次のウェーブが始まります。これを手で設定する必要はありません — オーケストレーターがスペックそのものからウェーブを導き出します。その様子は [ジョブ詳細ビュー](the-job-detail-view) で見られます。ストリーミングログがバッチがいまどのスペックに取り組んでいるかを語り、チケットヘッダーがジョブの触れたすべてのスペックを表示します。
+
+## ワークツリーの隔離
+
+複数のスペックが 1 回の実行で実装されるとき、パイプラインは各作業単位を隔離し、同時または逐次の変更が互いのファイルを踏み荒らさないようにします。バッチオーケストレーターは各スペックの実装を、それ専用のクリーンな作業コンテキストで走らせ、その結果を統合します — だから、途中までしかできていないスペックが、次のスペックから見える壊れた中間状態をツリーに残すことはありません。
+
+実際のところ、これは次を意味します。
+
+- 各スペックは、前のスペックの進行中の編集を途中から引き継ぐのではなく、まっさらな状態から実装に取りかかれます。
+- レビューと ship ステップは、動く標的ではなく、一貫したスナップショットに対して動作します。
+- あるウェーブでの失敗は封じ込められます — すでに ship 済みのスペックを密かに壊すことはありません。
+
+アプリはジョブごとに、どのファイルが触れられ、どのチケットがそれに触れたかを正確に記録します（これは **コード** セクションでは provenance チップとして、各スペックの詳細モーダルでは「このチケットが触れたファイル」リストとして表面化します）。この帰属づけこそが、複数スペックの実行を信頼できるものにしています — ファイルの変更を、それを引き起こしたスペックまでいつでもたどれるのです。
+
+## プロジェクトをまたいだマルチフィーチャー
+
+本物の並列処理がほしいなら — 大きな機能を 2 つ同時にビルドしたいなら — 1 つのプロジェクト内のレールにまたがせるのではなく、**プロジェクトをまたいで** 分けてください。各プロジェクトは独立したキューを持つので、
+
+```
+プロジェクト A   ▶ 機能 X を実行中のレール   ┐
+                                        ├─ 同時に実行
+プロジェクト B   ▶ 機能 Y を実行中のレール   ┘
+```
+
+グローバルな同時実行の上限はなく、プロジェクト間の競合もありません。両方を開き、それぞれでレールを起動すれば、いっしょに進みます。共有されるスロットルは予算上限だけで、その日の支出が上限に達するとプロジェクト単位またはアプリ全体でキューを一時停止します。
+
+## 大きなバッチのためのヒント
+
+- **関連するスペックを 1 つのレールにまとめてから** Batch に切り替えてください — 依存ウェーブはそのレール上にあるものしか見ません。
+- 大きなバッチの前に **1 日の予算を設定** しておけば、思いがけず高くついた実行が暴走せず自動で一時停止します。[予算](../settings/customizing) から設定できます。
+- 実行後にジョブページの **比較ボタン** を使えば、2 つのバッチ実行を並べて差分を確認できます。
+- （テレメトリが有効だった場合は）**診断をエクスポート** すれば、バッチ全体の正確なプロファイル + プラグインのスナップショットが手に入ります。
+
+## 次に読むもの
+
+- [レールとジョブ](rails-and-jobs) — キューモデルを掘り下げて。
+- [ジョブ詳細ビュー](the-job-detail-view) — バッチ実行をライブで見守る。
+- [レールごとのエンジン選択](picking-an-engine-per-rail) — Batch はどのプロバイダーでも動きますが、Ultra は Claude 専用である点に注意。

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

@@ -0,0 +1,60 @@
+# レールごとのエンジン選択
+
+Specrails desktop は **Claude Code**、**Codex CLI**、**Gemini CLI** をいずれも一級のエンジンとして扱います。プロジェクトには 1 つ、2 つ、あるいは 3 つすべてをインストールできます — そして複数がある場合は、各レールをどのエンジンで実行するかをあなたが選びます。このページでは、レールごとのエンジンセレクターと、それぞれをどんなときに選ぶべきかを扱います。
+
+## セレクターが現れるとき
+
+**エンジンセレクター** はレールヘッダーの、モードコントロールのすぐ隣にあります。プロジェクトに **複数の** プロバイダーがインストールされているときだけ表示されます。
+
+> **単一プロバイダーのプロジェクトはバイト単位で同じ挙動になります。** プロジェクトにエンジンが 1 つしかなければ、セレクターは表示されず、プロバイダー選択まわりは何も変わりません — そのエンジンで実行されるだけです。セレクターはあくまで複数プロバイダーのプロジェクトのためのものです。
+
+セレクターが表示される場合、あなたの選択は **レールごと、起動ごと** です — レールごとに別のエンジンを動かせますし、選んだエンジンはプロジェクト単位で記憶されます（既定はプロジェクトの主エンジン）。
+
+## エンジンの選び方
+
+1. レールのエンジンセレクターが表示されていることを確認します（プロジェクトにプロバイダーが 2 つ以上）。
+2. クリックして **Claude**、**Codex**、**Gemini** のいずれかを選びます。
+3. **▶ Play** でレールを起動します。
+
+選んだエンジンが、そのレールのパイプラインの全フェーズを実行します。選んだエンジンの CLI がインストールされていない場合、起動は即座に失敗します — 何も生成されません。足りない CLI をインストールして、もう一度試してください。
+
+## それぞれのエンジンが得意なこと
+
+3 つすべてが、標準の **Implement** と **Batch** のパイプラインを実行します。選び方の実用的なガイドはこちらです。
+
+| エンジン | こんなときに | 補足 |
+|--------|--------------------|-------|
+| **Claude** | フルの機能セットがほしいとき: エージェントプロファイル、Ultracode、ネイティブのコスト報告、最も充実したツールサポート。たいていの作業のデフォルト。 | **エージェントプロファイル**、**Ultracode**、いくつかの Claude 専用スペック機能（Contract Layer、SMASH）をサポートする唯一のエンジン。 |
+| **Codex** | OpenAI Codex CLI を好むとき、あるいはプロバイダー間で実装を比べたいとき。 | `codex` ≥ 0.128.0。ネイティブのコスト報告なし — アプリが料金表からコストを補います。プロファイルは適用されません。 |
+| **Gemini** | Google の Gemini CLI を使いたいとき、ネイティブのテレメトリがほしいとき、あるいは日常的なスペックを安く実行したいとき。 | `gemini` ≥ 0.11.0（`GEMINI_API_KEY` を設定）。ネイティブの OTLP テレメトリ。プロファイルは適用されません。 |
+
+### Claude 専用の機能
+
+いくつかの機能は Claude レールでしか動きません — 必要なら Claude を選んでください。
+
+- **エージェントプロファイル** — エージェントごとのモデルルーティング。Codex や Gemini のレールでは、実行は常にレガシーモードになり、選んだプロファイルは **無視されます**。プロファイルピッカーは Claude 以外のエンジンでは非表示になります。
+- **Ultracode（`Ultra` モード）** — 自律的でパイプラインをバイパスするモード。`Ultra` セグメントと、その Haiku/Sonnet/Opus のモデルピッカーは、レールのエンジンが Claude のときだけ表示されます。
+- **Contract Layer と SMASH** — Claude 専用のスペック改良機能（これらはレールのオプションではなく Add-Spec のオプションですが、同じ制約が当てはまります）。
+
+プロジェクトが複数のエンジンを混在させると、右サイドバーにはインストール済みの **すべての** プロバイダーがサポートするセクションだけが表示されます — つまり、Claude 以外のプロバイダーを含むプロジェクトでは **エージェント** セクションがまるごと消えます。プロファイルは Claude 固有のものだからです。
+
+## 実用的なワークフロー
+
+複数プロバイダーのプロジェクトは、**比較** や **コスト調整** をしたいときに真価を発揮します。
+
+- **実装を比較する。** 同じスペックを 2 つのレールに乗せ、一方を Claude、もう一方を Codex に設定して両方を起動し（プロジェクトをまたいで、あるいは同じプロジェクトのキューで一つずつ）、ジョブページの **比較** ボタンで結果を差分表示します。
+- **スペック単位でコスト調整する。** 重要なスペックは `max` プロファイルの Claude で、日常的なクリーンアップ系のスペックは Gemini で実行して支出を抑えます。`/analytics` をエンジンで絞り込めば、内訳が見られます。
+- **賢くデフォルトを決める。** 一番よく使うエンジンをプロジェクトの主エンジンに設定してレールがそれを既定にするようにし、特定のスペックが別のエンジンを必要とするときだけレールごとに切り替えます。
+
+## 覚えておきたいこと
+
+- **プロバイダーの選択はプロジェクト作成後は変更できません**（v1）。インストールするプロバイダーはプロジェクトを追加するときに選びます。あとから追加・削除する設定トグルはありません。
+- **コストは常に追跡されます。** ネイティブのコスト報告を持たないエンジンでも、アプリが料金表にフォールバックするので、Codex や Gemini の実行も [分析](../analytics/tracking-cost) に表示されます。
+- **ターミナルの「Open AI CLI」ボタン** も、複数プロバイダーのプロジェクトではプロバイダーピッカーを表示します。自分の手で CLI を動かしたいときにどうぞ。
+
+## 次に読むもの
+
+- [Codex を使う](../integrations/using-codex) — インストールとサインイン。
+- [Gemini を使う](../integrations/using-gemini) — インストール、`GEMINI_API_KEY`、テレメトリ。
+- [レールとジョブ](rails-and-jobs) — キューと起動の流れ。
+- [コストの追跡](../analytics/tracking-cost) — エンジンごとのコスト内訳。

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

@@ -0,0 +1,37 @@
+# テーマ
+
+Specrails を、あなた好みの見た目に。アプリには丁寧に調整された 5 つのテーマが標準で用意されていて、いつでも一瞬で切り替えられます。再起動も、リビルドも、面倒な設定もいりません。
+
+## 5 つの組み込みテーマ
+
+| テーマ | 雰囲気 |
+| --- | --- |
+| **Specrails** | デフォルト。バランスが取れていて落ち着いた、ブランドに沿ったトーン。 |
+| **Dracula** | 定番のダークパープル。夜でも目にやさしい配色です。 |
+| **Aurora Light** | 明るく軽やかなライトテーマ。日中の作業にぴったり。 |
+| **Obsidian Dark** | 深く、コントラストの高いダークモード。 |
+| **Matrix** | 黒地に緑の文字。メインフレームに入り込んだような気分を味わいたいときに。 |
+
+## 切り替え方
+
+1. **Settings**（アプリ全体の設定モーダル）を開きます。
+2. **外観** セクションに移動します。
+3. テーマを選びます。アプリ全体に即座に適用されます。
+
+これだけです。クリックしたその瞬間に変更が反映され、インターフェースがその場で新しい見た目に切り替わります。
+
+## どこに適用されるか
+
+テーマの選択は **アプリ全体** に適用され、プロジェクトごとの設定ではありません。どのプロジェクトも、どのページも、どのパネルも、同じテーマに従います。さらに、思いがけない場所にも反映されます。
+
+- **ターミナルパネル** はその場で色が変わります。スクロールバックや実行中のシェルセッションはそのまま保たれます。
+- 分析ページの **チャート** も合わせて色味が調整されます。
+- Code ビューアの **コードのシンタックスハイライト** もテーマに従います。
+
+## 選択は記憶されます
+
+選んだテーマはアプリに保存されるので、再起動しても引き継がれます。アプリの起動直後に一瞬だけ違う色がちらつくことのないよう、Specrails はインターフェースの読み込みが終わる前に保存済みのテーマを適用します。だから最初の 1 フレーム目から、正しい見た目で表示されます。
+
+## 気になる方へ
+
+テーマは、固定の色を直接埋め込むのではなく、ごく少数の意味づけされた色の役割（「アクセント」色や「サーフェス」色など）の上に作られています。次のテーマを簡単に追加できるのも、どのテーマも内部的に一貫しているのも、このおかげです。それぞれのテーマは、これらの役割を別の色に割り当て直しているだけなのです。使ううえでこうした仕組みを意識する必要はまったくありません。テーマ切り替えがこれほど滑らかに感じられる、その理由というだけの話です。

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

@@ -0,0 +1,39 @@
+# 言語
+
+Specrails は、あなたの言語で話します。インターフェースは 8 つの言語に完全対応していて、初期状態ではお使いのコンピューターの言語設定にそのまま合わせます。だからほとんどの方は、初回起動の時点で正しい言語で表示されます。
+
+## 対応言語
+
+- English
+- Español (Spanish)
+- Français (French)
+- Deutsch (German)
+- Português (Portuguese)
+- Italiano (Italian)
+- 中文 (Chinese)
+- 日本語 (Japanese)
+
+## まずは OS の言語で始まります
+
+Specrails を初めて開くと、OS の言語設定を確認して、対応している言語の中から最も近いものに合わせます。Mac や PC がスペイン語に設定されていればスペイン語で表示されますし、地域バリアント（`es-ES` や `zh-Hans-CN` など）が設定されている場合も、Specrails が自動的に適切な基本言語に対応づけます。
+
+何も操作する必要はありません。言語設定にいっさい手を触れなければ、Specrails は OS の言語に従い続けます。あとからコンピューターの言語を変更すれば、Specrails もそれに追従します。
+
+## 自分で言語を選ぶ
+
+OS のデフォルトとは違う言語にしたいですか？ 明示的に選択できます。
+
+1. **Settings** を開きます。
+2. **言語** セクションに移動します。
+3. 言語を選びます。
+
+切り替えは **即座** に行われます。再起動なしで、インターフェース全体が新しい言語で再描画されます。一度明示的に選択すると、Specrails はその選択を記憶して OS への追従をやめるので、アプリを開くたびにあなたの選んだ言語が尊重されます。
+
+## 翻訳される範囲
+
+インターフェースで目にするものすべて — ボタン、ラベル、ステータスメッセージ、ページタイトル、ダイアログ。日付も選んだ言語に合わせて整形されるので、その言語の流儀に沿った表示になります。
+
+## 知っておくとよいこと
+
+- **英語が元になる言語です。** 真新しい機能が翻訳の完了前にリリースされた場合、ところどころで一時的に英語のラベルが見えることがあります。続くアップデートで翻訳されます。
+- 言語の選択は **アプリ全体** に適用され、すべてのプロジェクトで共通です。

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

@@ -0,0 +1,46 @@
+# パイプラインテレメトリと診断
+
+パイプラインのジョブが思いどおりに進まなかったとき、テレメトリは AI CLI が実際に何をしたのかを、舞台裏まで詳しく記録して見せてくれます。**デフォルトはオフ** で、プロジェクトごとに完全に任意です。必要なときだけオンにしてください。
+
+## テレメトリとは
+
+テレメトリは、AI CLI がパイプラインのジョブを実行している間に発する構造化された診断シグナル（トレース、メトリクス、ログ）を記録します。パイプライン実行のフライトレコーダーのようなものだと考えてください。タイミング、トークン使用量、ステップごとの活動がローカルに記録されるので、ジョブを後から振り返って調べられます。
+
+これは **OpenTelemetry** というオープンな標準フォーマットの上に作られています。だからデータが独自の閉じた仕組みに囲い込まれることはありません。
+
+## オンにする
+
+テレメトリは **プロジェクトごと** に設定します。
+
+1. プロジェクトの **Settings** ページ（プロジェクト別の設定ルート）を開きます。
+2. **パイプラインテレメトリ** のトグルを見つけます。
+3. オンに切り替えます。
+
+これ以降、そのプロジェクトのパイプラインジョブはテレメトリを記録します。ほかのプロジェクトには影響しません。プロジェクトごとに自分で決められます。
+
+### 対象となるもの
+
+テレメトリの対象は **パイプラインジョブ**（キューに入った Architect → Developer → Reviewer → Ship のレール実行）です。チャットやセットアップウィザードのような対話的なセッションは、あえて対象外にしています。テレメトリは、繰り返し実行できて検証できるパイプライン実行のためのもので、一度きりの会話のためのものではないからです。
+
+## データの保存先
+
+すべてはあなたのマシン上、ホームディレクトリ配下（`~/.specrails/`）にとどまり、リポジトリに入ることはありません。生の記録はそれぞれのジョブとともに圧縮して保存され、古い記録は 1 週間後に自動でコンパクトな要約にまとめられて、すっきりした状態が保たれます。これらを手作業で管理する必要は一切ありません。
+
+## 診断バンドルのエクスポート
+
+テレメトリで使える機能の中でいちばん役立つのが **診断のエクスポート** です。ジョブに関するあらゆる情報を 1 つの ZIP にまとめ、トラブルシューティングや共有に使えるようにします。
+
+ジョブにテレメトリが記録されていると、そのジョブカードに **エクスポートボタン** が表示されます。クリックすると、次の内容を含む ZIP がダウンロードされます。
+
+- **`job-metadata.json`** — ジョブの識別情報とパラメータ
+- **`telemetry.ndjson`** — 記録された生のシグナル
+- **`logs.txt`** — 取得されたログ出力
+- **`summary.md`** — 人が読める実行サマリー
+
+プロジェクトがプラグインを使用している場合は、そのジョブで有効だったプラグインのスナップショットもバンドルに含まれます。
+
+このバンドルは、扱いにくい実行内容を理解したいとき、記録を残しておきたいとき、デバッグを手伝ってくれる人に詳細を渡したいときに取得するものです。
+
+## オフにする
+
+トグルはいつでもオフに戻せます。新しいジョブは直ちに記録をやめます。すでに記録済みのものは、コンパクト化されるか、プロジェクトを削除するまでディスク上に残ります。どこかに送信されることも、知らないうちに失われることもありません。

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

@@ -0,0 +1,48 @@
+# データの保存場所
+
+手短に言うと、**Specrails はあなたのリポジトリをきれいなまま保ちます。** アプリをいずれかのプロジェクトに向けても、そこに住み着いたり、設定ファイルをあちこちに散らかしたり、頼んでいないものを勝手に書き換えたりはしません。あなたのコードはあなたのもののまま、きれいに保たれます。
+
+## リポジトリはきれいなまま
+
+Specrails 自身のファイル — データベース、プロジェクト別の状態、エージェント定義、設定、テレメトリ、要約、その他動作に必要なすべて — は、ホームディレクトリ配下の、すっきりまとまった 1 か所に置かれます。
+
+```
+~/.specrails/
+```
+
+このフォルダがアプリのプライベートなワークスペースです。プロジェクトレジストリ、プロジェクト別のデータベース、同梱ツール、運用に関わる細々したものはすべてここに置かれます。あなたの実際のコードリポジトリが、これらの置き場として使われることは決してありません。
+
+つまり、こういうことです。
+
+- リポジトリの `.gitignore` がアプリによって書き換えられることは **ありません**。
+- リポジトリがツールの設定ファイルや隠しの状態ディレクトリで散らかることはありません。
+- Specrails からプロジェクトを削除しても、コードの中に散らかったものが残ることはありません。
+
+これまで、プロジェクトのあちこちにフォルダやファイルをこっそり追加するツールを使ってきた方にとって、これは意図的な方針転換です。Specrails は、リポジトリに向けて使い始めても、そのリポジトリの git 履歴にとっては **何も起きていないのと同じ** になるように作られています。
+
+## 唯一コミットされるもの — それも意図的に
+
+意図的な例外がちょうど 1 つだけあります。そしてそれこそがこのツールの核心です。**あなたの OpenSpec スペック** です。
+
+スペックはあなたのリポジトリの中、次の場所に置かれます。
+
+```
+openspec/
+```
+
+これは意図的なものです。スペックは **成果物** です。何を作ると決めたのか、なぜそう決めたのかを、バージョン管理され、レビュー可能な形で記録したものです。スペックはコードの隣にあるべきもので、git で追跡され、プルリクエストで見え、チームで共有されます。それこそが価値です。スペックは使い捨ての一時的な状態ではなく、プロジェクトの歴史の一部なのです。
+
+ですからルールはシンプルで、正直です。
+
+- **`openspec/`** → リポジトリに置かれ、コミットされます。意図的にそうしています。
+- **Specrails が必要とするその他すべて** → `~/.specrails/` 配下に置かれ、あなたの邪魔をしません。
+
+## なぜこの仕組みなのか
+
+Specrails は AI ツール群を自身のプライベートなワークスペース（`~/.specrails/` 配下）から実行し、本当に触れる必要があるもの — あなたのコードを読むこと、そして頼まれたスペックを書くこと — のためにだけ、あなたの実際のリポジトリに手を伸ばします。ツール群、フレームワーク定義、各種の記録は、すべてアプリのホームフォルダにとどまります。
+
+あなたにとっての結論はこうです。プロジェクトを追加し、パイプラインを実行し、スペックを探求し、いろいろ試してみても、リポジトリの作業ツリーと git 履歴が変わるのは、あなたが予想できる範囲だけ — つまりコミットしたスペックと、パイプラインが書いたコードだけ、という安心感を持てます。それ以外のものが紛れ込むことはありません。
+
+## プロジェクトを削除する
+
+Specrails からプロジェクトを削除すると、アプリは `~/.specrails/` 配下にある自身のプロジェクト別の状態を片付けます。すでにリポジトリにコミットされたスペックは、本来あるべき場所 — あなたのリポジトリの中 — にそのまま残ります。それらはあなたのものだからです。

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

@@ -0,0 +1,52 @@
+# スペックとバックログ
+
+**スペック**は、AI パイプラインが実装する作業の単位です。チケットのようなものだと考えてください。タイトル、やってほしいことの説明、優先度、そして任意のラベルで構成されます。パイプラインを起動すると、AI エージェントたちがこのスペックを読んでそれに沿って動きます。つまり、わかりやすいスペックこそが、よい結果を生むための一番大切な入力なのです。
+
+アプリ内ではスペックを**チケット**と呼ぶこともありますが、どちらも同じものを指しています。
+
+## ボード
+
+どのプロジェクトも、開くとまず**ダッシュボード**が表示され、そこに**SpecsBoard**（プロジェクトのすべてのスペックの一覧）が並びます。これがあなたのバックログです。ここから新しいスペックを作成したり、優先度を設定したり、スペックをレールにドラッグして実装したり、作業が進むにつれて変わっていくステータスを眺めたりできます。
+
+ボードには 2 つの表示モードがあり、ツールバーのトグルで切り替えられます。設定はプロジェクトごとに記憶されます。
+
+- **付箋表示**（デフォルト）— 短い概要が添えられたカード形式のタイル。
+- **リスト表示** — 1 行ずつのコンパクトな表示。
+
+さらに**ステータス**（すべて / ToDo / 完了）や**ラベル**で絞り込んだり、**デフォルト**・**チケット #**・**優先度**で並べ替えたり（それぞれ昇順／降順を切り替え可能）できます。
+
+## ステータス
+
+スペックは、いくつかのステータスの間を移っていきます。ボードはそれぞれに一貫した視覚的な目印を付けてくれるので、バックログの状態をひと目で把握できます。
+
+| ステータス | 意味 |
+|--------|---------------|
+| **下書き** | Explore の会話から保存した、作りかけのアイデア。まだ実装の準備はできていません。あとから戻ってきて、引き続き形にしていけます。`Draft` のピルが表示されます。 |
+| **Todo** | これから着手できる状態。スペックを作り終えると、ここに着地します。 |
+| **進行中** | パイプラインが現在作業中です（青い点が点滅します）。 |
+| **完了** | パイプラインによって完了しました（緑のチェックマーク）。 |
+| **キャンセル** | 取りやめになりました（赤い X）。 |
+
+下書きは Todo のスペックと同じアクティブな枠に並びます（専用の列はありません）が、ほんのり色づいたボーダーと `Draft` ピルが付いているので、すぐに見分けられます。下書きについての詳しい話は[下書きと Contract Layer](drafts-and-contract-layer.md)をご覧ください。
+
+## 優先度
+
+下書き以外のすべてのスペックには、**クリティカル**・**高**・**中**・**低**のいずれかの優先度が付きます。優先度はあくまで整理のための道具で、次に何を実装するか決めたり、ボードを並べ替えたりするのに役立ちます。スペックを作成するときに設定でき、あとからでもスペックカードを右クリックして**優先度を設定**を選べばいつでも変更できます。
+
+下書きだけは例外で、優先度をまったく持たないことができます。まだ作りかけのアイデアだからです。優先度は、下書きを本物のスペックとしてコミットしたときに確定します。
+
+## スペックを作成する
+
+スペックを作成するには、**追加**（SpecsBoard ツールバーのプラスボタン）をクリックします。**スペックを追加**ダイアログが開き、いくつかの方法から選べます。
+
+- **クイックモード** — やりたいことを記述すると、AI が一発でスペック全文を書き上げます。[スペックを追加 — クイックモード](add-spec-quick-mode.md)を参照。
+- **Explore モード** — AI と対話しながら、ターンを重ねてスペックを形にしていきます。[スペックを追加 — Explore モード](add-spec-explore-mode.md)を参照。
+- **Raw モード** — 入力した内容がそのままスペックとして保存されます。AI は一切関与しません。すでにスペックの文章が手元にあるときに使ってください。
+
+どれを選ぶかは、アイデアがどれだけ固まっているかによります。やりたいことがはっきり見えているならクイック、まだ考えをまとめている途中なら Explore、すでに文章があるなら Raw です。
+
+## 次はこちら
+
+- [スペックを追加 — クイックモード](add-spec-quick-mode.md) — アイデアを最速でスペックにする方法。
+- [スペックを追加 — Explore モード](add-spec-explore-mode.md) — 対話しながらスペックを形にする。
+- [下書きと Contract Layer](drafts-and-contract-layer.md) — 作りかけの作業を保存し、パイプライン向けにスペックを充実させる。

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

@@ -0,0 +1,45 @@
+# スペックを追加 — クイックモード
+
+クイックモードは、やりたいことがすでにわかっているときのためのモードです。アイデアを入力すれば AI がスペック全文を書き上げ、**Todo** としてボードに着地します。やり取りは不要。記述したら、あとは進むだけです。
+
+## クイックモードでスペックを作成する
+
+すばやくスペックを作成するには、次の手順で進めます。
+
+1. ダッシュボードで**追加**（SpecsBoard ツールバーのプラスボタン）をクリックします。
+2. **クイック**モードを選びます。
+3. テキスト欄にアイデアを入力します。一文でも一段落でも、伝わればかまいません。
+4. クリックして生成します。
+
+スペックの生成中は、画面の隅に小さなトーストが現れ、プロジェクト名・アイデアの抜粋・**経過時間**（「生成中… 0:12」）を表示します。完了すると、トーストは「<時間> で生成しました」に切り替わり、できたばかりのスペックへ直接ジャンプできる**表示**アクションが添えられます。
+
+これがフロー全体です。ここから先はすべて、任意の微調整です。
+
+## 調整できること
+
+**モデル** — デフォルトでは AI が手頃なモデルを選びます。より速いモデルやより高性能なモデルを使いたい場合は、モデルピッカーからスペックごとに上書きできます。
+
+**エンジン** — プロジェクトに複数の AI プロバイダー（Claude・Codex・Gemini のいずれかの組み合わせ）がインストールされている場合、ダイアログ上部にエンジンセレクターが現れ、このスペックをどのエンジンで生成するか選べます。選んだ内容はプロジェクトごとに記憶されます。プロバイダーが 1 つだけのプロジェクトでは、選ぶ余地がないため表示されません。
+
+**コンテキスト** — クイックモードは通常 1 ターンで動きます。あなたの説明からスペックを書くだけなら、コードベースを読む必要がないからです。ただし、コンテキストスライダーを使えば、AI が参照できる材料を増やせます。
+
+- 一番低い設定では、あなたの説明だけを読みます。
+- 設定を上げていくと、既存のスペック、プロジェクトの OpenSpec スペック、さらにはコードベース全体まで読んでから書けるようになります。
+
+与えるコンテキストが多いほど生成には時間がかかります（読み込みのためにマルチターンに切り替わります）が、その分スペックは実際のプロジェクトに根ざしたものになって返ってきます。実際のコードやファイル名、既存の挙動を参照する必要があるスペックでは、コンテキストを高めに設定するとよいでしょう。
+
+**添付ファイル** — モックアップ・ブリーフ・データファイルをアイデア欄にドロップします。AI はそれらをスペック執筆の一部として読み取ります。（添付ファイルがあると、生成もマルチターンに切り替わります。）
+
+**Contract Layer で強化** — 生成されるスペックに構造化されたブロックを追記するトグルです。これにより、下流のパイプラインが名前やデータの形を推測せずに済みます。任意の機能で、デフォルトはオフです。直前の選択はプロジェクトごとに記憶されます。何が追加されるのか、どんなときに価値があるのかは[下書きと Contract Layer](drafts-and-contract-layer.md)をご覧ください。
+
+## クイックモードと Explore モードの使い分け
+
+頭の中でアイデアがすでにはっきりしているとき（自分でスペックを書けるけれど、AI に任せたいだけのとき）は**クイック**を使いましょう。まだ考えをまとめている途中で、一緒に形にしてくれる相棒がほしいときは [**Explore**](add-spec-explore-mode.md) を使いましょう。
+
+クイックモードで作成したスペックは、ごく普通のスペックです。あとから開いて、もう少し練りたくなったら Explore セッションで**編集を続ける**ことができます。
+
+## 次はこちら
+
+- [スペックを追加 — Explore モード](add-spec-explore-mode.md) — 形を整える必要があるスペック向け。
+- [下書きと Contract Layer](drafts-and-contract-layer.md) — Contract Layer による強化の解説。
+- [パイプラインを実行する](running-pipelines.md) — できたばかりのスペックをレールにドラッグして実装する。