specrails-desktop 2.7.0 → 2.9.0

package/docs/guide/ja/getting-started/3-adding-your-first-project.md

@@ -0,0 +1,58 @@
+# 最初のプロジェクトを追加する
+
+プロジェクトとは、コードベースを収めたコンピュータ上のフォルダにすぎません。さっそく、ひとつ接続してみましょう。
+
+## プロジェクト追加ダイアログを開く
+
+ウェルカム画面で **最初のプロジェクトを追加** をクリックします（あとからなら、左サイドバーの **プロジェクトを追加** ボタンでも開けます）。小さなダイアログが表示されます。
+
+## 内容を入力する
+
+**プロジェクトフォルダ** *(必須)*
+
+コードが入っているフォルダを specrails に指定します。デスクトップアプリでは、フォルダアイコンをクリックして視覚的に参照・選択するか、フルパスを貼り付けられます。指定するのはリポジトリのルート — コードと（通常は）`.git` ディレクトリを含むフォルダです。
+
+**プロジェクト名** *(任意)*
+
+サイドバーに表示される分かりやすいラベルです。空欄のままにすると、specrails はフォルダ名を使います。
+
+**プロバイダー**
+
+このプロジェクトで使う AI プロバイダーを選びます。specrails は、あなたのマシン上で検出したものを表示します。
+
+- 🤖 **Claude**
+- ⚡ **Codex**
+- ✨ **Gemini**
+
+見つからなかったプロバイダーはグレーアウトされ、*not found* と表示されます。どれかをインストールしてサインインしたうえで、ダイアログを開き直してください。デフォルトでは利用可能なプロバイダーがすべて事前選択されていますが、使いたいものだけに絞り込むこともできます。複数選んだ場合は、**最初の** プロバイダーがプロジェクトのデフォルトになります。タスクごとの選択は、あとから行えます。
+
+> 必要なツールがそろっているかを確認するため、バックグラウンドで簡単なチェックが走ります。何か欠かせないものが足りない場合は、**追加** ボタンが無効のままになり、**詳細情報** リンクが正確なインストールコマンドを案内します。
+
+**追加** をクリックして進みましょう。
+
+## 数秒で終わるセットアップ
+
+そのフォルダにすでに specrails が設定済みなら、これで完了です。プロジェクトが瞬時にサイドバーに現れます。
+
+まっさらなプロジェクトの場合は、短い **セットアップウィザード** が走ります。ステップは 3 つです。
+
+1. **設定** — 選んだ各プロバイダーについて、基本的な内容を確認します。
+2. **インストール** — specrails がプロジェクトを自動でセットアップします。これは *クイック* インストールで、すぐに使えるテンプレートのエージェントが数秒のうちに配置されます。実行中の様子はライブログで確認できます。
+3. **完了** — すべて準備できたことを伝えるサマリーが表示されます。
+
+複数プロバイダーのプロジェクトでは、インストールがプロバイダーごとに 1 回ずつ順番に実行され、完了ステップにはそれぞれのカードが表示されます。
+
+## インストールされるもの
+
+セットアップは意図的に軽量で、**非侵襲的** です。specrails は、パイプラインが実行方法を把握できるよう、プロジェクトにごく少量の設定を追加します。
+
+- プロジェクトのエージェントプロファイルとローカル設定を収める `.specrails/` フォルダ。
+- Architect → Developer → Reviewer → Ship パイプラインを動かす、`.claude/agents/` 配下のエージェント定義。
+
+それだけです。specrails がセットアップ中にあなたのソースコードを書き換えることはありません。これらのファイルは、設定をチームと共有したければコミットしても安全です。
+
+> **もっと踏み込んだセットアップがしたい?** このアプリは、あえて高速なテンプレートインストールを採用しています。AI による拡張フロー（コードベースの分析やカスタムエージェントのペルソナ生成）がよければ、プロジェクトフォルダのターミナルで `npx specrails-core@latest init` を実行できます。
+
+## これで準備完了
+
+セットアップが終わると、specrails はあなたをプロジェクトのダッシュボードへ案内します。さあ、ツアーの時間です。[The dashboard tour](the-dashboard-tour) をご覧ください。

package/docs/guide/ja/getting-started/4-the-dashboard-tour.md

@@ -0,0 +1,53 @@
+# ダッシュボードツアー
+
+プロジェクトを追加したあなたが今見ているのが、**プロジェクトダッシュボード** — スペックを出荷済みのコードへと変えていくための拠点です。それでは、画面の見方を案内しましょう。
+
+## 全体像
+
+ウィンドウは 3 つのゾーンに分かれています。
+
+- **左サイドバー** — プロジェクトの一覧です。どのプロジェクトをクリックしても瞬時に切り替わり、ウィンドウのほかの部分もそれに合わせて更新されます。**プロジェクトを追加** ボタンもここにあります。
+- **メインエリア** — アクティブなプロジェクトのダッシュボードです。スペックと、それを実行するパイプラインが表示されます。
+- **右サイドバー** — 現在のプロジェクトの各セクション間を移動するためのナビゲーションです。
+
+## メインダッシュボード
+
+ここが作業の中心です。ダッシュボードには次のものが表示されます。
+
+- **スペック** — あなたが作成したチケットが、ステータス（Backlog/Todo から完了まで）ごとに整理されています。リスト、グリッド、付箋カードのいずれか、お好みの表示で見られます。
+- **スペックの追加手段** — 新しい作業を始めます。クイックなスペックを直接書くことも、会話を通して形を整え、チケットの下書きまで仕上げてくれるガイド付きの **Explore** チャットを開くこともできます。
+- **レール** — スペックが実装されるレーンです。レールにスペックを置いて起動すると、Architect → Developer → Reviewer → Ship パイプラインに送られます。複数のレールを同時に走らせられるので、いくつもの作業を並行して進められます。
+
+スペックが実行中のときは、そのパイプラインの進捗とライブログ — 設計・実装・レビューをしている AI のリアルタイム出力 — が表示されます。
+
+## 右サイドバー: プロジェクトのセクション
+
+右サイドバーは、現在のプロジェクトの切り替えスイッチです。ホバーすると展開し、開いたままピン留めもできます。表示されるセクションは次のとおりです。
+
+- **ダッシュボード** — スペックボードとレール（さきほどまでいた場所）です。
+- **ジョブ** — このプロジェクトのすべてのパイプライン実行を、過去・現在を問わず一覧表示します。ステータス・所要時間が分かり、任意の実行の詳細やログを掘り下げられます。
+- **分析** — AI の利用にかかっているコストです。日別・アクティビティ別・モデル別・チケット別に内訳が出るので、想定外の出費はありません。
+- **エージェント** — プロジェクトのエージェントプロファイルです。どのエージェントがパイプラインで動き、どの AI モデルを使うかを管理します。*（Claude で動くプロジェクトのみ。）*
+- **コード** — 平易な言葉による AI のサマリー付きの読み取り専用ファイルブラウザで、AI が触れたファイルを示すチップが表示されます。流れを追いたい非開発者の方にも最適です。
+- **インテグレーション** — 任意のアドオンです。スペックを **Jira** ボードに接続したり、AI 向けの追加ツールを有効にしたりできます。
+- **設定** — プロジェクトごとのオプション（テレメトリ、予算、プロバイダー設定など）です。
+
+> 一部のセクションは、選んだプロバイダーにとって意味があるときだけ表示されます。たとえば **エージェント** は Claude 専用です。あるセクションが見当たらない場合は、単にこのプロジェクトの構成には当てはまらないだけです。
+
+## ステータスバー
+
+ウィンドウのいちばん下に、細い帯が走っています。小さいながらも便利です。
+
+- **接続インジケーター**（左） — アプリが稼働していることを示す色付きのドットとラベルです。*接続済み* は緑、*再接続中* は黄色、再接続直後の *同期中* は青です。出番は多くありませんが、いざというとき安心できます。
+- **合計支出**（右） — これまでの支出の累計です。コストが常にひと目で分かります。
+- **ターミナル切り替え**（いちばん右） — 内蔵のターミナルパネルを開きます。**Cmd+J**（macOS）または **Ctrl+J**（Windows/Linux）でいつでも開閉できます。プロジェクトフォルダで開く、本格的なシェルです。
+
+## 便利なショートカット
+
+- **Cmd/Ctrl+B** — サイドバーをピン留め／折りたたみます。
+- **Cmd/Ctrl+J** — ターミナルパネルを開閉します。
+- **Cmd/Ctrl+K** — 検索を開きます。
+
+## 次に向かう先
+
+これで全体像はつかめました。ここからの自然な第一歩は、**スペックを追加** してレールで起動し、パイプラインが最初から最後まで走る様子を眺め、それから **分析** でコストを確認してみることです。ようこそ、specrails へ。

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

@@ -0,0 +1,78 @@
+# アナリティクスとコスト追跡
+
+Specrails があなたの代わりに AI CLI を実行するたびに — パイプラインのジョブ、クイックスペック、Explore セッション、AI リファイン、ファイル要約のいずれであっても — 何が起きたかを記録しています。どのモデルが動いたか、入出力のトークン数はいくつか、どれくらい時間がかかったか、そしていくらかかったか。**アナリティクス**セクションは、それらすべてを 1 枚のダッシュボードにまとめ、AI コストの行き先をいつでも把握できるようにします。
+
+右サイドバーから開けます（**アナリティクス**というラベルです）。表示される内容はすべて、現在開いているプロジェクトに限定されます。プロジェクトを切り替えれば、数字もそれに追従します。
+
+## 何が「支出」としてカウントされるのか
+
+Specrails は 5 種類の AI アクティビティを追跡しており、これらを*サーフェス*と呼びます。それぞれのサーフェスは、すべてのチャートで一貫して色分けされているので、ひと目で見分けられます。
+
+- **ジョブ** — Architect → Developer → Reviewer → Ship を実行するパイプラインのレール。
+- **クイックスペック** — 高速な Add Spec から生成したスペック。
+- **Explore スペック** — 会話を通じてスペックを形にする Explore セッション。
+- **AI リファイン** — エージェントやファイルに対する AI 支援のリファイン。
+- **ファイル要約** — Code エクスプローラーを支える、平易な言葉による要約。
+
+意図的に*追跡しない*ものもいくつかあります。チャットサイドバーとセットアップウィザードはどちらも AI CLI を起動しますが、これらは支出には一切表れません。そのおかげで、ダッシュボードには付随的なやり取りではなく、実際の、繰り返し行われる作業だけが反映されます。
+
+## ダッシュボードの読み方
+
+ページは、上から下へいくつかのブロックで構成されています。
+
+### バーンメーター（Hero）
+
+一番上の大きな数字は、選択した期間の合計支出です。**前期間比**のデルタが添えられているので、前の期間と比べて増加傾向なのか減少傾向なのかをひと目で判断できます。プロジェクトを使い始めたばかりの場合は、空の状態の表示が、いつトラッキングが始まったかを教えてくれます（「トラッキング開始: YYYY-MM-DD」）。過去データの遡及取り込みは行わないので、メーターはこのバージョンを使っている間に発生した実行のことしか把握しません。
+
+### 日次タイムライン
+
+1 日ごとの支出をサーフェス別に分けて積み上げた棒グラフです。アクティビティのない日はスキップせずにゼロとして表示されるので、1 週間の形が正直に見えます。コストのかかったバッチが*いつ*実行されたかを把握するには、これが一番手っ取り早い方法です。
+
+### クイック vs Explore
+
+2 つのスペック作成スタイルを並べて比較するカードです。Explore セッションの実行回数が 5 回未満の場合は、誤解を招く平均値を出す代わりに、やさしい行動の促し（CTA）を表示します。サンプルが少ないと、信頼できる比較にはならないからです。
+
+### モデル別
+
+支出の多いモデルを上位 10 件まで表示します。任意のモデルをクリックすると、ダッシュボード全体をそのモデルだけに絞り込めます。特定のハイエンドモデルが実際どれくらいかかっているのかを知りたいときに便利です。
+
+### コスト vs ターンの散布図
+
+各点が 1 回の呼び出しを表し、コストとターン数をプロットしています。外れ値 — つまり高コストでターン数の多い実行 — がはっきりと浮かび上がります。（散布図は応答性を保つため、直近 500 件の点を表示します。）
+
+### 上位チケット
+
+*すべての*サーフェスを合算したうえで、最もコストのかかったチケットを上位 10 件表示します。そのため、Explore で少しだけかかり、ジョブで大きくかかったチケットも、本当の合計が見えます。削除済みチケットと割り当て不能な実行はそれぞれ専用のバケットにまとめられるので、合計から何かが黙って消えてしまうことはありません。
+
+### 生データの呼び出しテーブル
+
+これが真実です。1 回の呼び出しにつき 1 行が並びます。このブロックにはテーブルだけに作用する独自のサブフィルターがあるので、上のチャートを乱すことなく詳細を掘り下げられます。
+
+## 絞り込み
+
+一番上の固定ヘッダーには、2 つの主要フィルター — **期間**と**サーフェス** — があり、どちらもページの URL に保存されます。つまり、絞り込んだビュー（「直近 30 日、ジョブのみ」など）をブックマークしたり共有したりでき、開き直したときも残したとおりに再現されます。生データテーブルのフィルターは別物で、そのブロック内だけに留まります。
+
+正確さについて一言。失敗した実行と中断した実行は*コストの平均値*からは除外されます（1 回あたりの数値が歪んでしまうため）が、合計実行回数と失敗率にはきちんとカウントされます。こうすることで、平均値はクリーンに保たれつつ、信頼性の全体像は欠けることなく示されます。
+
+## チケットごとのコスト
+
+スペックにいくらかかったかを見るために、わざわざアナリティクスページに来る必要はありません。どのチケットでも開けば、支出が紐づいている場合はタイトルのすぐ下に 1 行のサマリーが表示されます。
+
+> $0.42 · 6 ターン · 稼働 1m 12s · 内訳
+
+それをクリックすると、すでにそのチケットで絞り込まれた状態のアナリティクスページに着地します。「この機能にいくらかかったのか？」から完全な内訳へと、最短で辿り着けます。
+
+## データのエクスポート
+
+数字をアプリの外で使いたいとき — スプレッドシート、財務レポート、独自の分析など — は、**エクスポート**ドロップダウンを使います。4 つの形式が用意されています。
+
+- **サマリー CSV** — 合計、日次タイムライン、サーフェス別、モデル別、上位チケットを含む複数セクションのファイル。
+- **サマリー JSON** — 同じサマリーを構造化したもの。
+- **生データ CSV** — すべての呼び出し行（最大 10,000 件。切り捨てが発生した場合はその旨が記載されます）。
+- **生データ JSON** — 同じ生データ行を構造化したもの。
+
+エクスポートは、その時点で適用している期間・サーフェスのフィルターを尊重します。ファイル名はきれいに並ぶように付けられます: `<project>-analytics-<period>-<date>.csv`。エクスポートする対象がないときはボタンが無効になり、ダウンロードに失敗した場合は分かりやすいエラートーストが表示されます。
+
+## 常にライブ
+
+更新（リフレッシュ）の必要はありません。プロジェクト内のどこかで新しい呼び出しが記録されると、開いているダッシュボードが少し後で静かに再取得を行うので、作業が完了するのに合わせてバーンメーターが追従し続けます。

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

@@ -0,0 +1,46 @@
+# 統合ターミナル
+
+Specrails には本物のターミナルが組み込まれています — ウィンドウの下からせり上がってくる、あの VS Code や Cursor とまったく同じ感覚のパネルです。実際のシェルを、実際のプロジェクトディレクトリで動かすので、アプリを離れることなく `git`、`npm`、テスト、その他なんでも実行できます。
+
+## 開く・閉じる
+
+一番速いのはキーボードです。**Cmd+J**（macOS）または **Ctrl+J**（Windows/Linux）でパネルの開閉が切り替わり、表示された瞬間にターミナルへフォーカスが移るので、すぐに入力を始められます。ステータスバーのシェブロンを使うこともできます。
+
+パネルには 3 つの状態があります。
+
+- **非表示** — しまわれている状態。
+- **復元** — 通常の分割高さのパネル。
+- **最大化** — 出力をじっくり読むために場所が必要なとき、作業領域を占有する状態。
+
+パネルを最小化しても（シェブロン）、何かが**止まることはありません**。シェルはバックグラウンドで動き続けます。セッションを実際に終わらせる唯一の操作は、閉じること（ゴミ箱アイコン、またはタブごとの ✕）です。
+
+## 複数セッション
+
+同じプロジェクト内で、複数のターミナルを同時に — 最大 10 件まで — 動かせます。それぞれが独自のタブを持ち、名前を変更できるので「dev サーバー」と「テスト」が混ざる心配もありません。すべてプロジェクトフォルダで起動し、シェルのプロファイル（`.zshrc`、`.bashrc` など）を読み込むので、エイリアスや PATH は思ったとおりのものになります。
+
+ここが大事なところです。あなたのターミナルは**プロジェクトやタブを切り替えても生き残ります**。Specrails は各セッションを裏側で生かしたまま、そのまま保ちます — スクロールバックも、実行中のプロセスも、すべて。だからアナリティクスに切り替えて戻ってきても、シェルがリセットされることも、長時間実行中のコマンドが中断されることもありません。セッションが終わるのは、明示的に閉じたとき（またはプロジェクトごと削除したとき）だけです。
+
+## プロジェクトごとに記憶される
+
+パネルが開いているかどうか、どれくらいの高さにドラッグしたか、どのタブが存在するか — そのすべてが**プロジェクトごと**に記憶されます。プロジェクトに戻ってくれば、離れたときのままのレイアウトになっています。
+
+## プレミアムな機能
+
+これは飾り気のないコンソールではありません。このターミナルには、一級品に求めたくなる気の利いた機能がそろっています。
+
+- **高速で鮮明な描画** — WebGL による描画（壊れないよう自動フォールバックあり）、Unicode の幅を正しく扱う処理、そしてフォントのリガチャ。
+- **スクロールバックの検索** — **Cmd+F** で、500 行も上に埋もれたエラーを見つけ出せます。
+- **フォントズーム** — **Cmd+=**、**Cmd+-** で拡大縮小、**Cmd+0** でリセット。
+- **クリップボードのショートカット** — Cmd+C / Cmd+V でコピー＆ペースト、Cmd+K でクリア — さらに右クリックのコンテキストメニューも。
+- **ファイルパスのドラッグ＆ドロップ**（デスクトップアプリの場合）— ファイルをターミナルにドロップすると、シェルに合わせて正しくクオートされたパスが挿入されます。
+- **滑らかなリサイズ** — パネルの高さをドラッグしたり、サイドバーを折りたたんだりしても、出力がガタつきません。
+- **インライン画像** — Sixel や iTerm2 形式の画像を出力するターミナルは、その場で画像を描画します。
+- **シェル統合** — Specrails は各コマンドの開始位置と終了位置を把握しているので、コマンド履歴を追跡し、長時間実行中のコマンドが完了したときに通知できます（デスクトップ通知、ブラウザでのフォールバックあり）。何らかの理由でシェルに計装できない場合は、静かにフォールバックし、一度だけその旨を知らせます。
+
+## 設定
+
+ターミナルの設定は 2 層になっています。アプリ全体のデフォルトと、任意のプロジェクトごとの上書きです。プロジェクトごとの設定があればそちらが優先されるので、全体としては統一感のある見た目・操作感を保ちつつ、特別な対応が必要な 1 つのプロジェクトだけを調整できます。
+
+## 無効にする
+
+ターミナルはデフォルトで有効です。もし使いたくない場合は、`VITE_FEATURE_TERMINAL_PANEL`（クライアント側）または `SPECRAILS_TERMINAL_PANEL`（サーバー側）のフラグで無効にできます — どちらかを `false` に設定してください。とはいえ、ほとんどの方はそのまま有効にしておくでしょう。

package/docs/guide/ja/insights/3-code-explorer.md

@@ -0,0 +1,50 @@
+# Code エクスプローラー
+
+**Code** セクションは、リポジトリをのぞける親しみやすい読み取り専用の窓を提供します — エディタに張り付かなくても、AI が何を作ってきたのかを理解したい人のために特別に設計されています。左にファイルツリー、右にコードビューア、そしてコードの上には、各ファイルが実際に何をしているのかを平易な言葉で説明した要約が表示されます。
+
+このバージョンでは厳密に読み取り専用です。ここで何をしてもファイルが変更されることはありません。作業場ではなく、読書室だと考えてください。
+
+右サイドバー（**Code**）から開けます。他のすべてと同様に、現在のプロジェクトに限定されます。
+
+## ファイルツリー
+
+左ペインは、プロジェクトのファイルを仮想化して表示したツリーです — 大きなリポジトリでも高速です。`.gitignore` と組み込みの拒否リストを尊重するので、ビルド成果物や `node_modules` の海ではなく、本当に重要なファイルが見えます。
+
+ファイルの隣には**来歴チップ（provenance chip）**が表示されることがあります — そのファイルが*AI によって変更された*ことを示す小さなマーカーです。これこそが Code エクスプローラーの核心です。Specrails は、各パイプラインジョブがどのファイルを作成・変更したかを記録し、それを作業のきっかけとなったチケットに紐づけます。だから「これは AI が書いたのか、それとも自分が書いたのか？」をひと目で答えられます。
+
+ツリーの一番上にはフィルターがあります。
+
+- **AI が変更 / Touched by AI**（デフォルト）— AI が変更したファイルのみ。
+- **すべてのファイル** — ツリー全体。
+
+選んだ内容はプロジェクトごとに記憶されるので、主に AI が書いた変更を気にしているなら、毎回それが最初に目に入ります。
+
+## コードビューア
+
+ファイルをクリックすると、本格的なビューアで開きます（VS Code と同じエンジンである Monaco を使用）。あなたが選んだアプリのテーマに合わせた、適切なシンタックスハイライトが付きます。動作を軽快に保つための、ちょっとした賢い制限もあります。バイナリファイルは丁寧にお断りし、非常に大きなファイル（2 MB 超）は読み込みません。
+
+現在開いているファイルはページの URL に保存されるので、特定のファイルへのリンクをブックマークしたり共有したりできます。
+
+このバージョンでは編集機能がないため、ビューアには**外部エディタで編集**ボタンが用意されており、ファイルの絶対パスをコピーできます — お好みのエディタに貼り付けて、そこから作業を続けてください。
+
+## AI 要約
+
+コードの上には、ファイルの**平易な言葉による要約** — 何のためのものか、何をしているのか — が表示されます。開発者でない人でも追えるように書かれています。これらはあなたのために生成され、キャッシュされるので、以前に見たファイルを開くと即座に表示されます。
+
+要約は鮮度を保つことに賢く対応します。ファイルの内容を鍵にしているので、ファイルが本当に変わったときには要約が再生成されますが、変わっていないファイルが無駄に再要約されることはありません。あなた自身がファイルを編集した場合、その要約は黙って再生成されるのではなく「古い」とマークされます — いつ更新するかはあなたの判断に委ねられます。必要なときに新しい結果が欲しければ、**再生成**アクションがあります。
+
+コストを健全に保つためのガードレールもいくつかあります。要約の生成は**月次の予算**（デフォルトでは数ドル、設定で変更可能）の範囲内で動き、1 つのジョブが起動できる要約の数にも上限があります。要約がスキップされた場合、アプリはその理由を教えてくれます — 予算に達した、ジョブごとの上限、あるいは単にファイルが見つからなかった、など。
+
+また、グローバル設定の*Code section*の領域で、**要約の言語**（英語またはスペイン語）を選べます。
+
+## コードをスペックへ結びつける
+
+来歴のリンクは双方向に機能します。Code エクスプローラーの中で、ファイル上のチケットチップをクリックすると、そのチケットの詳細が開きます。逆方向では、**チケット詳細**ビューに*このチケットが変更したファイル*セクションがあり — そこでファイルをクリックすると、そのファイルが開いた状態の Code エクスプローラーへ直接ジャンプします。「これが私たちの書いたスペック」と「これがそこから生まれたコード」の間のループを、きちんと閉じてくれます。
+
+## まだできないこと
+
+期待値を明確にするために言うと、この最初のバージョンでは意図的にいくつかの機能を見送っています。アプリ内での編集、シンボル単位やディレクトリ単位の要約、説明的な差分ビュー、そして「このファイルについて AI に聞く」という対話機能です。来歴は、ファイルをその主たるチケットにのみ帰属させます。これらは今後、時間をかけて育っていく類いのものです。
+
+## 無効にする
+
+Code エクスプローラーはデフォルトで有効です。`VITE_FEATURE_CODE_EXPLORER`（クライアント側）または `SPECRAILS_CODE_EXPLORER`（サーバー側）のフラグで無効にできます — どちらかを `false` に設定してください。無効にしても、記録済みのデータや要約はすべてディスク上に安全に残り、手つかずのままなので、また有効に戻したときにそのまま使えます。

package/docs/guide/ja/integrations/1-ai-providers.md

@@ -0,0 +1,64 @@
+# AI プロバイダー（Claude、Codex、Gemini）
+
+Specrails は特定の AI に縛られません。アプリの中で AI とやり取りするすべての部分 — Explore Spec、クイックスペック、レール、チャット、AI 編集、ターミナルの「Open AI CLI」ボタン — は、3 つのファーストクラスなプロバイダーのいずれかを通して動かせます。プロジェクトごとにどのプロバイダーを使うかを選べますし、タスク単位で切り替えることもできます。
+
+## 3 つのプロバイダー
+
+| プロバイダー | CLI | 提供元 | 備考 |
+|---|---|---|---|
+| **Claude** | `claude` | Anthropic | 最も機能が充実しています。エージェント（プロファイル）と Ultracode レール、そして Contract Refine を使えるのは Claude だけです。 |
+| **Codex** | `codex` | OpenAI | codex `0.128.0+` が必要です。MCP サーバーはグローバルな `~/.codex/config.toml` から読み込みます。 |
+| **Gemini** | `gemini` | Google | gemini `0.11.0+` が必要です。ネイティブのテレメトリと `GEMINI.md` 指示ファイルを使用します。 |
+
+3 つとも**デフォルトで有効**です。プロバイダーは、その CLI がインストールされていて `PATH` 上にあれば **Add Project** に表示されます。ですので、最初のステップはいつも同じです。使いたい CLI をインストールし、そのツール自身のドキュメントの手順どおりにログインしてください。ターミナルで `claude --version`（または `codex`、`gemini`）が動くようになれば、Specrails はそれを使えるようになります。
+
+## プロジェクトに 1 つのプロバイダーをインストールする
+
+プロジェクトを追加すると、セットアップウィザードがどのプロバイダーをインストールするか尋ねます。1 つ選んでインストールのステップを進めれば完了です。あとはそのプロジェクトがそのプロバイダーを*持っている*状態になり、それ以降は意識する必要はありません。スペック、レール、チャット、アナリティクスは、どれを選んでも同じように動きます。
+
+使いたい CLI が Add Project に出てこない場合、ほとんどはその CLI がインストールされていないか、`PATH` 上にないのが原因です。インストールしてから Add Project を開き直してください。
+
+## 1 つのプロジェクトに複数のプロバイダーをインストールする
+
+同じプロジェクトに**複数**のプロバイダーをインストールできます — たとえば Claude *と* Gemini を一緒に、といった具合です。**Add Project** では、プロバイダーの一覧がチェックボックスになるので、使いたいものをすべてチェックしてください。最初に選んだものがそのプロジェクトの**プライマリ**（デフォルト）プロバイダーになり、残りは代替として使えるようになります。
+
+マルチプロバイダーのプロジェクトについて、知っておくとよいことがいくつかあります。
+
+- **プロバイダーが 1 つなら、これまでとまったく同じ挙動です。** プロジェクトにプロバイダーが 1 つしかなければ、プロバイダーの選択 UI はどこにも表示されません — アプリはすっきりシンプルなままです。
+- **右サイドバーには、インストール済みのすべてのプロバイダーが対応しているセクションだけが表示されます。** エージェント（プロファイル）は Claude 専用の概念なので、プロジェクトに Claude 以外のプロバイダーが含まれた瞬間に **Agents** セクションは消えます。それ以外（Specs、Code、Analytics、Integrations、Terminal、Chat）はそのまま残ります。
+- **プロバイダーの選択は作成後に固定されます。** このバージョンでは、プロジェクトを追加するときにプロバイダーを選び、あとから設定で変更することはできません。別の組み合わせが必要になったら、新しいプロジェクトを作成してください。
+
+## 呼び出しごとにプロバイダーを選ぶ
+
+マルチプロバイダーのプロジェクトの真価は、グローバル設定を一切変えずに、タスクごとに最適な AI を選べることにあります。AI が動くところには、小さなプロバイダー選択 UI が現れます（プロジェクトに複数のプロバイダーがあるときだけです）。
+
+- **Add Spec** — エンジンセレクターで、好きなプロバイダーを使ってスペックを Explore したりクイック生成したりできます。
+- **レールのヘッダー** — その特定のレールを起動する前に、使うエンジンを選べます。
+- **ターミナル** — 「Open AI CLI」（Sparkles）ボタンを押すとプロバイダーメニューが開き、そのプロジェクトのディレクトリで任意のインストール済み CLI に入れます。
+
+選んだエンジンはプロジェクトごとに記憶され、デフォルトはプライマリプロバイダーです。毎回選び直す必要はありません。
+
+## Claude だけができること
+
+いくつかの機能はその性質上 Claude 専用なので、ほかのプロバイダーが使われているときは非表示になるかスキップされます。
+
+- **エージェント（プロファイル）** — プロジェクトごとのエージェントカタログとモデルルーティング。Claude 以外のプロバイダーを含むプロジェクトでは非表示になります。
+- **Ultracode レール** — 常に Claude で実行されます。
+- **Contract Refine** — コミット済みスペックに対する「Contract Layer」の追加パスは、会話のプロバイダーが Claude のときだけ実行されます。
+- **Add Spec の高度なモード**（SMASH / Contract Layer） — Claude 以外のエンジンでは非表示になります。
+
+それ以外 — Explore、クイックスペック、レールパイプライン全体、AI 編集、チャット、コストのアナリティクス — は 3 つすべてで動作します。
+
+## プロバイダー横断のコスト追跡
+
+**Analytics** ページは、プロバイダーに関係なく、課金対象となるすべての呼び出しを追跡します。マルチプロバイダーのプロジェクトでは、エンジンのフィルターチップが追加され、プロバイダーごとに支出を比較できます。Claude は自身の正確なコストを報告しますが、Codex と Gemini については、Specrails が組み込みの料金表からコストを推定します。そのため、これらの数値は請求額そのものではなく、おおよその近似値です。
+
+## トラブルシューティング
+
+- **インストールしたプロバイダーが表示されない。** その CLI が `PATH` 上にあるか確認してください（新しいターミナルで `claude --version` / `codex --version` / `gemini --version` を試してみてください）。アプリはシステムの `PATH` を通してプロバイダー CLI を検出します。
+- **チャットで Codex の MCP サーバーが読み込まれない。** Codex は MCP サーバーをグローバルな `~/.codex/config.toml` から読み込みます — `codex mcp add` でそこに登録してください。
+- **緊急時の無効化。** プロバイダーは環境変数（`SPECRAILS_CODEX_BETA=0` または `SPECRAILS_GEMINI_BETA=0`）でアプリ全体から無効にできます。これはプロバイダーを*選択肢*から隠すだけで、めったに必要にはなりません。
+
+## 関連項目
+
+各 CLI をさらに詳しく解説した専用のプロバイダーガイドがあります。Codex ガイドと Gemini ガイドでは、それぞれセットアップ方法、使える機能、プロバイダー固有のクセを取り上げています。

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

@@ -0,0 +1,44 @@
+# プラグイン（Integrations）
+
+**Integrations** セクションは、AI にできることを広げる任意のアドオンを集めた、プロジェクトごとのマーケットプレイスです。どのプラグインを使うかは各プロジェクトが独立して決めます — あるプロジェクトにプラグインをインストールしても、ほかのプロジェクトには一切影響しません。
+
+プラグインは、**MCP サーバー**（Model Context Protocol）をプロジェクトにそっと登録することで機能し、レールやチャットの最中に AI が呼び出せる新しいツールを提供します。使うにあたって MCP を理解している必要はありません — インストールすれば、次にレールが走るときから利用できます。
+
+## いま使えるもの
+
+このバージョンは**同梱版のみ**を提供します。インストールできるプラグインは、アプリに組み込まれているものだけです。リモートのレジストリも、ユーザーがアップロードするプラグインも、サードパーティのコード読み込みもありません — つまり、カタログにあるものはすべて検証済みで、Specrails と一緒に出荷されています。
+
+目玉となるプラグインはこちらです。
+
+- **Serena** — セマンティックなコードナビゲーション。言語サーバーに裏付けられたコードベースの理解（定義へのジャンプ、参照の検索、シンボルを意識した検索）を AI に与え、単なるテキストマッチングを超えます。大規模なリポジトリや不慣れなリポジトリで、エージェントに本物のシンボルについて考えてほしいときに最適です。
+
+  Serena は `PATH` 上に `uv` ツールが必要です（`uvx` 経由で動作します）。アプリは `uv` があるかどうかを自動検出し、見つからない場合は知らせてくれます。
+
+## プラグインをインストールする
+
+1. 右サイドバーから **Integrations** を開きます。
+2. カタログでプラグインを見つけます。各カードには **Not installed**（未インストール）、**Installed**（インストール済み）、**Degraded**（劣化）、**Orphan**（孤立）のいずれかのステータスが表示されます。
+3. プラグインをクリックして**インストールのプレビュー**を確認します — 何かが起こる前に、どのファイルが変更されるのかを正確に確認できます。
+4. **Install** をクリックします。セットアップの進行状況がリアルタイムで表示されます。
+
+内部的には、インストールは*外科的かつ追加的*です。プロジェクトの `.mcp.json`（および一部のプラグインでは、保護された `.claude/agents/` 名前空間内のフラグメントファイル）に、自分自身のエントリだけを追加します。設定全体を書き換えることは決してなく、2 つ目のプラグインを追加しても 1 つ目を乱すことはありません。インストールが自身の正常性を検証できなかった場合は、きれいにロールバックされます。
+
+## インストール済みプラグインを管理する
+
+- **正常性。** 各プラグインにはオンデマンドの正常性チェックがあります。インストールは問題なくできたのに、あとで起動できなくなったプラグインは **Degraded**（劣化）とマークされます — レールをブロックすることはなく、バッジと理由が表示されるだけです。
+- **アンインストール。** プラグインを削除すると、そのプラグインが所有するエントリだけが外科的に削除され、設定の残りの部分は手つかずのまま残ります。
+- **孤立（Orphan）。** プラグインのファイルが、適切な状態を伴わずに残ってしまった場合（たとえば変更が中断されたあとなど）、それは **Orphan**（孤立）として表示され、ワンクリックでクリーンアップできます。
+
+## プラグインが作業にどう現れるか
+
+- **レール。** レールが走る前に、Specrails はどのプラグインがインストールされていて正常かを確認し、そのジョブのエージェントにそれらのツールを利用可能にします。劣化したプラグインはその実行ではスキップされるだけで、レールは通常どおり起動します。各ジョブは、どのプラグインが有効だったかのスナップショットを記録し、ジョブの診断エクスポートで確認できます。
+- **チャット。** チャットはプロジェクトの MCP 設定を自動的に取り込むので、インストール済みのプラグインはそこでも利用できます。
+- **セットアップ。** プロジェクトのセットアップ中はプラグインは無視されます — プロジェクトの準備が整ってから登場します。
+
+## プロバイダーに関する注意
+
+プラグインはプロバイダーを意識します。Serena のような MCP プラグインは、プロジェクトの `.mcp.json` を通して MCP を登録するプロバイダー（Claude と Gemini）で解決されます。Codex のプロジェクトでは、MCP サーバーは Codex 自身のグローバル設定で管理されるため、**Integrations** 内のプラグインエントリはそれに応じてフィルタリングされます。Integrations 内の Jira カードはプロバイダーに依存せず、誰にでも表示されます — Jira ガイドを参照してください。
+
+## 予約ファイル
+
+プラグインは、プロジェクト内の小さく明確に定義されたファイル群を管理します。`.mcp.json`（外科的にマージされます）、`.specrails/plugins/` 配下の一部の状態、そして `.claude/agents/custom-<plugin>.md` にあるプラグインごとのエージェントフラグメントです。インテグレーションをチームと共有したい場合、これらはコミットできるチーム資産です — アプリがこれらを無造作に上書きすることは決してありません。

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

@@ -0,0 +1,71 @@
+# Jira インテグレーション
+
+スペックを Specrails の中ではなく、本物の **Jira ボード**で管理したいと思ったことはありませんか？ Jira インテグレーションは、プロジェクトのスペックを Jira の課題で裏付け、レールが走るのに合わせてステータスを同期し、それ以外のときは邪魔をせずにいてくれます。各プロジェクトは、**それぞれ専用の** Jira ボードと同期します。
+
+## 仕組み（かんたん版）
+
+Specrails は、Jira とプロジェクトのあいだの**同期レイヤー**として動きます。大きな考え方はこうです。パイプラインが読み込む正本はあくまでローカルのスペックストアであり、それと Jira を一致させ続ける責任を Specrails が担います。
+
+- レールを起動すると、Specrails はリンクされた Jira の課題を **In Progress** に移動します。
+- ジョブが終わると、Specrails は課題を遷移させ（**Done** へ、失敗した場合は **To Do** へ戻す）、ジョブ ID・コスト・所要時間を含む完了コメントを投稿します。
+- Specrails は定期的に Jira を**ポーリング**し、ボード上で誰かが行った変更を取り込んで、スペックに反映します。
+
+すべての書き戻しは、耐久性があってクラッシュに強いアウトボックスを通ります。そのため、一時的な Jira の不調がジョブを壊すことはなく、更新は再試行されるだけです。
+
+## ボードに接続する
+
+接続はプロジェクトの **Settings** ページから行います（Add Project ウィザードの最後にも、任意の「Configure Jira」ステップがあります）。接続ウィザードが次の手順を案内してくれます。
+
+1. **Test** — Jira の URL と認証情報を入力すると、Specrails が接続を検証します。
+2. **プロジェクトを選択** — 同期する Jira プロジェクトを選びます。
+3. **ステータスのマッピング（任意）** — 自動検出に少し手助けが必要な場合、Jira のワークフローステータスを Specrails の状態に対応付けます（詳しくは後述）。
+4. **Connect** — 完了です。これでスペックがそのボードを反映するようになります。
+
+### 認証
+
+このバージョンは**トークン貼り付け**による認証を使います — 手軽で、デバイス内に収まり、バックエンドを必要としません。
+
+- **Jira Cloud:** アカウントのメールアドレスと API トークン。
+- **Jira Data Center / Server:** Personal Access Token（PAT）。
+
+トークンは**ご自身のマシン上で暗号化して保存**され、外部に出ることはありません。アプリはトークンが存在するかどうかだけを表示し、トークンそのものを表示することはありません。
+
+## ステータスのマッピング
+
+どんな Jira 同期でも一番やっかいなのは、*あなたの*ワークフローを Specrails のシンプルな状態（To Do / In Progress / Done に加え、cancel / ship のバリエーション）に対応付けることです。Specrails はこれを 2 段階で解決します。
+
+1. **明示的なステータスマップ** — ウィザードで設定した場合は、常にこれが優先されます。
+2. **自動検出** — 各ステータスのカテゴリ（new / in-progress / done）に基づき、加えて cancel や ship 系のステータスのスマートなマッチングも行います。
+
+ゲートのある遷移を持つワークフローをまたいで課題を移動する必要がある場合、Specrails は有効な経路を一歩ずつ見つけ出し、その途中で必要なフィールド（resolution など）を埋めていきます。あるステータスに本当にたどり着けない場合は、その操作はデッドレターとして保留され、黙って失敗するのではなくあなたに知らされます — **degraded**（劣化）インジケーターが表示され、再試行できます。
+
+## ホットスワップ：安全にオン・オフを切り替える
+
+Jira のリンクは、ボード全体に対する「全部か無か」のグローバルなスイッチではなく、レールを起動したまさにその瞬間に捕捉される**スペック単位**のものです。だからこそ、安全に切り替えられます。
+
+- インテグレーションを**有効化・無効化**しても、既存のスペックが移し替えられることはありません。
+- **切断**すると、プロジェクトは通常のローカルスペックの挙動に戻ります。
+- すでに Jira リンクを持つスペックは書き戻しを保持し、持たないスペックはそのまま放置されます。
+
+ですので、気軽に試せます — オンにして、レールをいくつか走らせて、またオフにする — ボードやローカルのスペックをぐちゃぐちゃにする心配はありません。
+
+## 日々の使い方
+
+接続すると、プロジェクトの Settings ページに**接続済みカード**が表示され、次のことができます。
+
+- **Sync now** — タイマーを待たずに、その場で即時ポーリングを実行します。
+- **デッドレターの再試行** — 詰まってしまった書き戻しを再実行します。
+- **ホットスワップトグル** — インテグレーションを一時的に停止・再開します。
+- **切断** — ボードをきれいに切り離します。
+
+Jira に裏付けられたスペックは、カードに **Jira キーバッジ**（`PROJ-123` のようなもの）を表示し、クリックすると課題へリンクで戻れます。また、同期が完了したとき、認証トークンが期限切れになったとき（更新できるように）、インテグレーションが劣化状態に入ったときに、小さな通知が届きます。
+
+## 心に留めておきたいこと
+
+- **Webhook ではなくポーリング。** Specrails はローカルで動くため、プッシュ通知を受け取るのではなく、Jira をポーリングして受信側の変更を取得します。変更は即座にではなく、ポーリング間隔のうちに現れます。
+- **プロジェクトごとに 1 つのボード。** 別々のプロジェクトは別々のボードと同期できますが、1 つのプロジェクトはちょうど 1 つのボードと同期します。
+- **競合時はラストライト勝ち** — 2 つのタブが同じ下書きを同時に編集するというまれなケースでは、後から書き込んだほうが勝ちます。
+
+## オフにする
+
+完全に元へ戻したくなったら、Settings から **Disconnect** するだけです。スペックはローカルのみの挙動に戻り、Jira のメタデータは使われないまま残るだけです — 何も破壊されません。

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

@@ -0,0 +1,38 @@
+# モバイルコンパニオン
+
+Specrails にはコンパニオンのスマホアプリがあり、デスクから離れているあいだもレールに目を配れます — ジョブが走るのを見て、終わるのを見届け、ダッシュボードの前に座っていなくても流れを把握できます。
+
+## 何のためのもの？
+
+コンパニオンは**モニタリング**のための画面です。動作中の Specrails デスクトップアプリにローカルネットワーク越しに接続し、ライブのプロジェクトとジョブの動きをスマホにミラーリングします。ふだんダッシュボードで眺めているのと同じレールを、ちらっと覗ける窓だと考えてください。
+
+## スマホをペアリングする
+
+ペアリングは **QR コード**を中心に作られているので、面倒な入力は不要です。
+
+1. デスクトップの Specrails アプリが動作していて、スマホが**同じローカルネットワーク**（同じ Wi-Fi）にあることを確認します。
+2. デスクトップアプリでペアリング画面を開き、QR コードを表示します。
+3. スマホのコンパニオンアプリで、そのコードをスキャンします。
+4. スマホがネットワーク上のデスクトップアプリを見つけて接続します。
+
+それ以降、コンパニオンはライブ接続を保ち、プロジェクトの一覧とジョブの更新が発生するたびにストリーミングします。
+
+## 接続の仕組み
+
+デスクトップアプリは、スマホが見つけられるように自身をローカルネットワーク上で告知し、QR コードには安全に接続するために必要な情報が含まれています。すべてはローカルネットワーク内で完結します — コンパニオンは、クラウドサービスを経由せず、あなたのマシンと直接やり取りします。
+
+ローカルネットワークをベースにしているため、2 つのデバイスはお互いに到達できる必要があります。ペアリングがうまくいかない場合は、次を確認してください。
+
+- 両方のデバイスが**同じ Wi-Fi** 上にあること（そして、ネットワークがクライアント同士を分離していないこと）を確認します。
+- スキャンするときにデスクトップアプリが**動作中**であることを確認します。
+- ペアリング画面を開き直して QR コードを更新し、もう一度スキャンしてみてください。
+
+## 何が見えるのか
+
+ペアリングが完了すると、コンパニオンはプロジェクトとそのライブのジョブ活動を表示します。デスクトップのダッシュボードに流れ込むのと同じリアルタイムのレール更新が、発生したその瞬間にスマホへ届きます。長時間走っていたレールが終わった瞬間を知るには、いちばん手軽な方法です。
+
+## 知っておくとよいこと
+
+- **まずはモニタリング。** コンパニオンは、デスクトップのワークフロー全体をスマホから操作するためではなく、レールを見守るために設計されています。
+- **ローカル限定。** アカウントもクラウド中継もありません — あなたのマシンとスマホが、あなたのネットワーク上でつながるだけです。
+- **デスクトップを起こしておく。** コンパニオンは動作中のデスクトップアプリをミラーリングします。マシンがスリープしたりアプリが閉じたりすると、復帰するまでライブ更新は一時停止します。