ima2-gen 3.20.0 → 3.21.0

package/docs/README.ja.md

@@ -1,33 +1,98 @@
-# ima2-gen
+<p align="center">
+  <img src="../assets/brand/banner.png" alt="ima2 — 人とコーディングエージェントのためのローカル画像・動画スタジオ" width="100%">
+</p>
 
-<!-- runtime-install:generated:start -->
-| Contract | Value |
-|---|---|
-| Node engine | `>=22` |
-| npm toolchain | `npm@11.18.0` |
-| Release Node | `24.17.0` |
-| CLI entry | `bin/ima2.js` |
-| OpenAI SDK | `^7.4.0` |
-| Express | `^5.1.0` |
-<!-- runtime-install:generated:end -->
+<h3 align="center">画像と動画を、自分のマシンで生成し、枝分かれさせ、仕上げる。</h3>
+<p align="center">GPT、Grok、Gemini、NovelAI、ComfyUI をひとつにまとめたローカルスタジオです。<br>ブラウザ、Mac アプリ、CLI から使うことも、コーディングエージェントに任せることもできます。</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/ima2-gen"><img src="https://img.shields.io/npm/v/ima2-gen?style=flat-square&labelColor=18181b&color=3f3f46&logo=npm&label=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/ima2-gen"><img src="https://img.shields.io/npm/dm/ima2-gen?style=flat-square&labelColor=18181b&color=3f3f46&label=downloads" alt="npm downloads"></a>
+  <img src="https://img.shields.io/node/v/ima2-gen?style=flat-square&labelColor=18181b&color=3f3f46&logo=node.js&label=node" alt="Node.js version">
+  <a href="https://github.com/lidge-ai/ima2-gen/stargazers"><img src="https://img.shields.io/github/stars/lidge-ai/ima2-gen?style=flat-square&labelColor=18181b&color=3f3f46&logo=github&label=stars" alt="GitHub stars"></a>
+  <a href="../LICENSE"><img src="https://img.shields.io/badge/license-MIT-3f3f46?style=flat-square&labelColor=18181b" alt="MIT license"></a>
+</p>
+
+```bash
+npm install -g ima2-gen
+ima2 serve
+```
+
+<p align="center">
+  <a href="https://github.com/lidge-ai/ima2-gen/releases?q=desktop&expanded=true"><img src="https://img.shields.io/badge/macOS-Apple%20Silicon%20.dmg-18181b?style=for-the-badge&logo=apple&logoColor=white" alt="Mac アプリをダウンロード (.dmg)"></a>
+  <a href="#one-line-installers"><img src="https://img.shields.io/badge/Windows%20%C2%B7%20Linux-one--line%20installer-18181b?style=for-the-badge&logo=gnubash&logoColor=white" alt="Windows と Linux 向けワンライナーインストール"></a>
+</p>
+
+<table>
+<tr>
+<td width="42%" valign="middle">
+
+### 作成
+
+プロンプトを書き、参照画像を添えて、レーンとモデルを選ぶだけです。結果ごとにプロンプト、所要時間、設定が残るので、そのままコピーしたり、続きから作ったり、動画にしたりできます。
+
+</td>
+<td width="58%">
+  <img src="../assets/screenshots/readme-create.webp" alt="ダークモードの作成画面。左にプロンプト入力、中央にクロームの彫刻、右に GPT OAuth 設定" width="100%">
+</td>
+</tr>
+<tr>
+<td width="42%" valign="middle">
+
+### ノードグラフで枝分かれ
+
+気に入った一枚を残したまま、複数の方向へ同時に広げられます。各ブランチは親を覚えているので、元画像が上書きされることはありません。
+
+</td>
+<td width="58%">
+  <img src="../assets/screenshots/readme-node.webp" alt="クロームの彫刻から金、大理石、森の3つに分岐したノードグラフ" width="100%">
+</td>
+</tr>
+<tr>
+<td width="42%" valign="middle">
+
+### Canvas Mode で仕上げ
+
+注釈、消しゴム、背景除去を行い、本物のアルファチャンネルで書き出せます。GPT 透過ボタンは、サーバーが実際の透明度を確認してから結果を伝えます。
 
-インストーラーはパッケージメタデータから Node.js の最低バージョンを読み、サーバー起動前にオフライン検査を行います。
+</td>
+<td width="58%">
+  <img src="../assets/screenshots/readme-canvas.webp" alt="市松模様の上に透過背景のカメラが置かれた Canvas Mode とツールバー" width="100%">
+</td>
+</tr>
+<tr>
+<td width="42%" valign="middle">
 
-[![npm version](https://img.shields.io/npm/v/ima2-gen)](https://www.npmjs.com/package/ima2-gen)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../LICENSE)
+### ホームから始める
 
-> 🌐 **Live site**: [lidge-jun.github.io/ima2-gen](https://lidge-jun.github.io/ima2-gen/) · [한국어](https://lidge-jun.github.io/ima2-gen/ko/)
->
-> **他の言語で読む**: [English](../README.md) · [한국어](README.ko.md) · [正體中文](README.zh-TW.md) · [简体中文](README.zh-CN.md)
+準備できたレーンを確認し、すぐにプロンプトを入力し、最近の作品をフォルダを探さずに再開できます。
 
-`ima2-gen` は、人とコーディングエージェント向けのローカルファーストなビジュアル生成ランタイム兼スタジオです。複数プロバイダーで再現可能な画像・動画ワークフローを扱います。
+</td>
+<td width="58%">
+  <img src="../assets/screenshots/readme-home.webp" alt="レーンの準備状況、プロンプト入力、最近の作品グリッドが並ぶホーム画面" width="100%">
+</td>
+</tr>
+</table>
 
-グローバルインストール後、OpenAI OAuth/API、Grok OAuth/API、Antigravity CLI、Gemini API、AtlasCloud、MiniMax の 8 つの core lane で画像と動画を生成できます。Runway と Higgsfield は別枠の MCP integration です。
+<p align="center">
+  <a href="../README.md">English</a> · <a href="README.ko.md">한국어</a> · <b>日本語</b> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.zh-TW.md">正體中文</a> · <a href="https://lidge-ai.github.io/ima2-gen/"><b>Web サイト</b></a> · <a href="https://lidge-ai.github.io/ima2-gen/docs"><b>ドキュメント →</b></a>
+</p>
 
-![プロンプト入力、生成画像、モデル表示、結果メタデータが見える ima2-gen classic 画面](../assets/screenshots/classic-generate-light.png)
+`ima2-gen` は、人とコーディングエージェントが複数のプロバイダーで再現可能な画像・動画ワークフローを実行するための、ローカルファーストなビジュアル生成ランタイム兼スタジオです。自分のマシンで小さなサーバーを動かし、すべての成果物を `~/.ima2/generated` に保存し、接続したプロバイダーとだけ通信します。対応先は OpenAI OAuth/API、Grok OAuth/API、Antigravity CLI、Gemini API、AtlasCloud、MiniMax、NovelAI、登録済みの ComfyUI ワークフローで、Runway と Higgsfield は別の MCP 連携です。プロンプトと参照画像は、ジョブごとに選んだプロバイダーにだけ送られます。
 
-## Quick Start
+## クイックスタート
+
+### Mac アプリ (Apple Silicon)
+
+デスクトップアプリは、同じローカルサーバーとスタジオを Mac のウィンドウとメニューバーアイコンで動かします。Developer ID で署名され Apple の公証を受けており、ランタイムを同梱しているので Node.js は不要です。
+
+1. 最新の [ima2 Desktop リリース](https://github.com/lidge-ai/ima2-gen/releases?q=desktop&expanded=true) から `ima2-<version>-mac-arm64.dmg` をダウンロードします。
+2. DMG を開き、**ima2** を **アプリケーション** フォルダへドラッグします。
+3. ima2 を起動し、ウェルカム画面でプロバイダーを選びます。
+
+チェックサム、アップデート、設定は [Mac アプリガイド](https://lidge-ai.github.io/ima2-gen/docs/desktop) にあります。Intel Mac、Windows、Linux では npm かワンライナーを使ってください。
+
+### npm
 
 ```bash
 npm install -g ima2-gen
@@ -35,270 +100,357 @@ ima2 setup
 ima2 serve
 ```
 
-その後、`http://localhost:3333` を開きます。
+その後 `http://localhost:3333` を開きます。`3333` が使用中なら次の空きポートで起動し、実際の URL を `~/.ima2/server.json` に書き込むので、`ima2 open` は常に正しいアドレスを開きます。
+
+### CLI で最初の一枚
 
-CLI で動画生成:
+画像と動画のデフォルトを一度だけ決めてから生成します。
 
 ```bash
-ima2 video "猫がピアノを弾く" --duration 5 --resolution 720p
-ima2 video "このシーンをアニメ化" --ref photo.png --duration 10
+ima2 models
+ima2 defaults set image oauth/gpt-6-luna
+ima2 defaults set video grok/grok-imagine-video-1.5
+ima2 gen "a clean product photo of a red guitar pedal"
+ima2 video "a cat playing piano" --duration 5 --resolution 720p
 ```
 
-`3333` がすでに使われている場合、次に空いているポートで起動し、実際の URL は `~/.ima2/server.json` に書き込まれます。ポートを決め打ちせず、terminal に表示された URL または `ima2 open` を使ってください。
+`ima2 gen` と生成モードの `ima2 video` は、CLI の対象が決まるまで `NO_DEFAULT_MODEL` で停止します。呼び出しに `--model <lane>/<model>` か `--provider <lane>` を明示した場合は例外です。アップグレードでプロバイダーや課金レーンが勝手に切り替わることはありません。
+
+<a id="one-line-installers"></a>
 
-> **npx を使いたい場合は?** [NPX_QUICKSTART.md](NPX_QUICKSTART.md) を参照してください。
+### ワンライナーインストール (npm 不要)
 
-### ワンクリックインストール（npm 不要）
+各スクリプトはパッケージが定める Node.js の最低バージョンを確認し、必要なら Node LTS を入れ、ima2-gen を一度インストールし、オフラインのインストール検査を通してから `ima2 serve` を起動します。無関係なプロセスを止めたり、グローバルロックを消したりはしません。
 
-Node.js や npm がなくても、プラットフォーム用インストールスクリプトが環境を検出し、必要なら Node LTS を入れてから ima2-gen をインストールします。
+**macOS**
 
-**macOS:**
 ```bash
-curl -fsSL https://lidge-jun.github.io/ima2-gen/install-mac.sh | bash
+curl -fsSL https://lidge-ai.github.io/ima2-gen/install-mac.sh | bash
 ```
 
-**Windows (PowerShell):**
+**Windows (PowerShell)**
+
 ```powershell
-irm https://lidge-jun.github.io/ima2-gen/install-windows.ps1 | iex
+irm https://lidge-ai.github.io/ima2-gen/install-windows.ps1 | iex
+```
+
+**Linux / WSL**
+
+```bash
+curl -fsSL https://lidge-ai.github.io/ima2-gen/install-linux.sh | bash
 ```
 
-**Linux / WSL:**
+<details>
+<summary><b>Docker</b></summary>
+
 ```bash
-curl -fsSL https://lidge-jun.github.io/ima2-gen/install-linux.sh | bash
+docker build -t ima2-gen .
+docker run -d -p 3333:3333 -e IMA2_LAN_TOKEN=change-me -v ima2-data:/data ima2-gen
 ```
 
-各スクリプトは対応する Node バージョンを確認し、必要に応じて nvm/fnm/brew/winget で Node LTS を入れます。npm のインストールは一度だけ試し、`ima2 doctor --installation --json` が成功してからサーバーを起動します。プロセスの強制終了やグローバルロックの削除は行いません。
+compose の使い方、必要な環境変数、制限は [DOCKER ドキュメント](DOCKER.md) を参照してください。
 
-### セットアップ
+</details>
 
-`ima2 setup` では認証方式を4つ選べます:
+<details>
+<summary><b>セットアップ、アップデート、npx</b></summary>
 
-1. **GPT OAuth** — ChatGPT アカウントでログイン（無料、画像のみ）
-2. **Grok OAuth** — xAI/Grok アカウントでログイン（画像 + 動画）
-3. **Both** — GPT + Grok 両方（全機能）
-4. **Web setup** — Web UI で設定
+`ima2 setup` では4つの認証方法から選べます。
 
-動画生成には Grok OAuth（2 または 3）が必要です。GPT OAuth だけ設定済みで動画を追加する場合は `ima2 grok login` を別途実行してください。
+1. **GPT OAuth** — ChatGPT アカウントでログイン (画像)
+2. **Grok OAuth** — xAI/Grok アカウントでログイン (画像と動画)
+3. **Both** — GPT OAuth と Grok OAuth の両方
+4. **Web setup** — Web UI ですべて設定
 
-### アップデート
+動画生成には Grok OAuth (2 か 3) が必要です。すでに GPT OAuth を使っている場合は `ima2 grok login` で動画を追加できます。既定は手動貼り付け方式です。
 
-実行中の server を Ctrl+C で止めてから:
+アップデートするには Ctrl+C でサーバーを止め (別のターミナルなら `ima2 stop`)、次を実行します。
 
 ```bash
 npm install -g ima2-gen@latest
 ```
 
-Ctrl+C は DB クローズ、子プロセス停止、ファイルロック解放まで行うクリーンシャットダウンです。インストールに失敗した場合は表示された npm 権限を確認するか、対象の `ima2` プロセスを手動で停止してください。インストーラーは無関係なプロセスやグローバルロックを操作しません。
+Ctrl+C はデータベースを閉じ、子プロセスを止め、ファイルロックを解放してきれいに終了します。インストールに失敗したら npm の権限メッセージを確認するか、該当する `ima2` プロセスを自分で止めてください。インストーラーがプロセスを一括で片付けることはありません。
+
+npx で使う場合は [npx クイックスタート](NPX_QUICKSTART.md) を参照してください。
+
+</details>
 
 ## できること
 
-- **Classic mode**: すばやく生成し、編集し、現在の画像を次の参照として使えます。
-- **Node mode**: 良い画像を起点に、複数の方向へ分岐して試せます。
-- **Multimode batches**: 1つのプロンプトから複数候補を同時に走らせ、slot ごとの進行を見ながら最も良い結果から作業を継続できます。
-- **Canvas Mode**: zoom/pan、annotation、eraser、background cleanup、transparent checkerboard preview、alpha/matte export をサポートします。
-- **Video generation**: テキスト、画像、複数参照から短い動画を生成。SSE で planning→submitted→progress→done。First/Mid/Last フレームコピー対応。
-- **Storyboard mode**: コンポーザーの storyboard トグルで連続フレームのキャラクター・シーン連続性を維持（画像・動画両対応）。
-- **Local gallery**: 生成物をローカル保存。デフォルトは現在セッション、All Images トグルで全履歴。生成時間と reasoning effort をメタデータに記録。
-- **Reference images**: ドラッグ/ペースト/ファイル選択。画像最大5、動画最大7。大きい画像は自動圧縮。
-- **Prompt library imports**: local prompt pack、GitHub folder、curated GPT-image hint を built-in prompt library に取り込めます。
-- **Mobile shell**: 小さい画面では app bar、compose sheet、compact settings toggle で操作できます。
-- **Observable jobs**: 進行中の生成と最近の生成を request ID で追跡できます。
+- **作成**: 生成、編集、現在の画像の再利用、参照画像の貼り付け、履歴からの続き。マルチモードをオンにすると、ひとつのプロンプトから複数の候補を同時に走らせ、枠ごとに埋まっていく様子を見られます。すべてのコントロール、マルチモードのレシピ、Direct モード、reasoning effort は [Prompt Studio マニュアル](PROMPT_STUDIO.md) にまとまっています。 参照画像は画像生成で最大5枚、動画で最大14枚まで添付でき、大きな画像はアップロード前に圧縮されます。
+- **ノードグラフ**: 良い画像を複数の方向へ枝分かれさせます。ルートノードはローカルの参照画像を、子ノードは親の画像を元にします。完了したジョブはリクエスト ID でノードに戻されるので、リロードやグラフのバージョン競合があっても結果は失われません。
+- **Canvas Mode**: ズーム、パン、ホバーでハイライトされる注釈、消しゴム、グループ、元に戻す、付箋、背景の整理、アルファ保持またはマット色での書き出し。自己完結したキャンバス文書には **SVG (embedded raster)**、本物のベクターパスには **Trace to SVG (vector)** を選びます。**GPT transparency** ボタンは OAuth i2i レーンで背景を消し、デコードしたバイトから `alphaVerified` を報告します。 保存したキャンバスのバージョンはギャラリーと履歴ストリップには出ませんが、Canvas Mode で開き直したり、次の参照画像として添付したりできます。
+- **動画**: Grok の動画モデルでテキスト→動画、画像→動画、参照→動画を作成し、進捗表示と First/Mid/Last フレームのコピーボタンを備えます。**Storyboard mode** は連続するフレームで人物とシーンの一貫性を保ちます。 進捗は SSE で planning → submitted → 進捗率 → done の順に表示されます。ストーリーボードでは画像のキーフレームを動画制作向けに構成し、動画クリップは人物と環境の固定ルールを引き継ぎます。
+- **ラスター→ベクター**: `ima2 vectorize`、AssetGen/Assets、Canvas の書き出しから、フラットなラスター画像を本物の SVG パスに変換します。
+- **NovelAI のデュアルプロンプト**: NovelAI を選ぶと、作成、ホーム、モバイルの作成シートに **Positive prompt** と **Undesired content** が並んで表示されます。 作成エリアが 719px より狭いときは上下に積み重なります。
+- **プロンプトライブラリ**: ローカルのプロンプトパック、GitHub フォルダ、厳選した GPT-image ヒントを取り込み、ローカルで検索できます。
+- **Prompt Builder**: テキストバックエンドで意図を磨きます。Settings > Providers で Auto のままにするか、バックエンドとモデルを固定でき、**via &lt;backend&gt;** バッジが実際に応答したバックエンドを示します。 GPT バックエンドを選んだときの既定モデルは `gpt-6-luna` です。
+- **ローカルギャラリー**: すべての画像と動画が手元に残り、セッション別の履歴、生成時間、reasoning effort がメタデータに記録されます。 既定では現在のセッションだけを表示し、All Images トグルで全履歴を開けます。選んだ既定の範囲はセッションをまたいで維持されます。
+- **ライト・ダークテーマ**: AA コントラストを守るトークンベースのパレットで、ライト・ダーク・システムをちらつきなく切り替えられます。
+- **モバイルシェル**と**ジョブの可視化**: 小さな画面向けのアプリバー、作成シート、コンパクトな設定トグル、安全なログとリクエスト ID 付きの実行中・最近のジョブ一覧。
+
+Card News は開発用の実験機能で、公開ランタイムでは非表示です。
 
-### SSE マルチプレキシング
+### エージェントスキル
 
-Web UI は単一の `GET /api/events` Server-Sent Events 接続で全生成の進行を受信します。Multimode、node、video リクエストは非同期 POST（`202 { requestId }`）で送信され、共有イベントバス経由で進行イベントがマルチプレクスされます。これにより、同時生成時のブラウザ 6 接続制限によるギャラリー hang が解消されます。`async: true` を送らない CLI クライアントは、後方互換のため従来どおりリクエストごとの SSE ストリームを受け取れます。
+ima2-gen には、コーディングエージェントが読み込む Markdown スキルが3つ同梱されています。画像・動画生成、フロントエンド用アセット、デザインの方向性探しを手順立てて案内します。
 
-## 画像生成は OAuth と API key をサポートします
+| スキル | コマンド | 内容 |
+|------|------|------|
+| **Core** | `ima2 skill` | CLI リファレンス、プロンプトの書き方、プロバイダーの振り分け、韓国語テキスト、動画ワークフロー |
+| **Frontend** | `ima2 skill front` | アセットパイプライン (並列生成、候補選択、プロバイダーの振り分け)、Web 向けモーションと動画、レスポンシブ、アクセシビリティ、anti-slop、30以上の参照ファイル |
+| **UI/UX Design** | `ima2 skill uiux` | 画像起点のデザイン方向探索、UX の状態、design-ism、プロダクトの性格、DESIGN.md ワークフロー、21の参照ファイル |
 
-既定の画像生成は、ローカルの Codex/ChatGPT OAuth 経路で実行されます。
+```bash
+ima2 skill ls                   # スキル一覧
+ima2 skill front path          # ファイルパスを表示 (エージェント向け)
+ima2 skill front --json        # JSON ラッパー (エージェント向け)
+ima2 skill front refs           # 参照モジュール一覧
+ima2 skill front ref motion     # 参照モジュールをひとつ読み込む
+ima2 skill install --dir <path> # エージェントのスキルフォルダにインストール
+ima2 skill install --tmp        # 一時フォルダにインストール (代替)
+```
 
-API key が env/config に存在する場合、生成エンドポイントで `provider: "api"` を指定すると Responses API の `image_generation` tool を使用できます。
+## プロバイダーとモデル
 
-- `provider: "grok-api"` — `XAI_API_KEY` で xAI Images API を直接呼び出し
-- `provider: "agy"` — ローカル Antigravity CLI (`IMA2_AGY_BIN`)
-- `provider: "gemini-api"` — `GEMINI_API_KEY` または Vertex (`VERTEX_SERVICE_ACCOUNT_JSON`、Vertex 優先)
+| レーン | 認証 | 画像 | 動画 | メモ |
+|---|---|:-:|:-:|---|
+| `oauth` | ChatGPT ログイン、ima2 が ChatGPT を直接呼び出し | ✓ | | 既定のレーン。GPT-6 が構成し `gpt-image-2` が描画、`gpt-6-luna` |
+| `api` | `OPENAI_API_KEY` | ✓ | | Responses API の `image_generation` ツール、マスク・マルチモード・ノード |
+| `grok` | xAI OAuth (`ima2 grok login`) | ✓ | ✓ | Images API の前に Web 検索とプランナー |
+| `grok-api` | `XAI_API_KEY` | ✓ | ✓ | xAI Images API を直接呼び出し |
+| `gemini-api` | `GEMINI_API_KEY` または Vertex サービスアカウント | ✓ | | `nano-banana-2`、`nano-banana-pro`、512px〜4K |
+| `agy` | Antigravity CLI | ✓ | | `agy -p` で Gemini `nano-banana-2` / `nano-banana-pro` |
+| `nai` | NovelAI API トークン | ✓ | | NAI Diffusion モデル4種、テキスト→画像 |
+| `comfy` | ローカル ComfyUI | ✓ | ✓ | 登録済みの画像・動画ワークフロー |
+| `atlascloud` | AtlasCloud API キー | ✓ | | `openai/gpt-image-2` の生成と編集 |
+| `minimax` | MiniMax API キー | ✓ | | `image-01`、`image-01-live` |
+| `runway`、`higgsfield` | MCP 接続 | ✓ | ✓ | 別の MCP 連携 |
 
-Settings に **API key provider available** と表示される場合、API key が検出され、生成・編集・multimode・node request に使用できるという意味です。
+GPT OAuth レーンは GPT-6 の 3 モデルを使います。既定は **`gpt-6-luna`** で、`gpt-6-sol` と、最も長く推論するぶん最も遅い `gpt-6-astra` を選べます。選んだモデルが画像を構成し、`gpt-image-2` が描画します。`gpt-5.6-luna` などの旧 OAuth モデル ID は保存済みの設定やスクリプトでもそのまま動き、対応する GPT-6 モデルに置き換わります。API キーのレーンは独自の一覧を保ちます: `gpt-5.6-luna` (既定)、`gpt-6-astra`、`gpt-5.6-terra`、`gpt-5.6-sol`、`gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini`。アプリでは品質 (`low`、`medium`、`high`) とモデレーション (`auto`、`low`) も選べます。
 
-Grok 動画の既定値は正式名 `grok-imagine-video-1.5` です。`grok-imagine-video` は Ref2V、V2V edit、extension の互換パスで引き続き使用し、従来の `grok-imagine-video-1.5-preview` も互換 alias として受け付けます。参照数に応じて T2V(0)、I2V(1)、Ref2V(2-14、grok-imagine-video-1.5 は最大15秒 / grok-imagine-video は最大10秒)が自動選択され、1080p は `grok-imagine-video-1.5` の prompt-only T2V と単一画像/フレーム I2V で有効です。duration(1-15s)、resolution(480p/720p/対応時 1080p)、aspect ratio を設定できます。
+<details>
+<summary><b>プロバイダーの詳細 (English)</b></summary>
 
-設定画面の QuotaCard に Grok billing `$used/$limit` バーと **Switch Account** ボタン（`POST /api/auth/switch`）が表示されます。
+- `provider: "oauth"` signs in with your ChatGPT session and calls ChatGPT's Codex backend from the ima2 server process, with no separate proxy. A GPT-6 model plans the prompt and `gpt-image-2` renders it; Direct mode skips the planner. Transparent backgrounds and image edits run on the same lane.
+- `provider: "api"` calls the OpenAI Responses API with the hosted `image_generation` tool.
+- `provider: "grok"` calls `https://api.x.ai` directly with the xAI OAuth session stored in `~/.progrok/auth.json`, running mandatory xAI Web Search plus a planner pass (default: `grok-4.3`, configurable in settings or via `--planner-model`) before the xAI Images API call. `grok-4.5` and `grok-4.6` are also selectable. Log in once with `ima2 grok login` or the Settings **Switch Account** button; the session refreshes itself two minutes before expiry.
+- `provider: "grok-api"` calls the xAI Images API directly with `XAI_API_KEY` (no OAuth session involved).
+- `provider: "nai"` calls the NovelAI image API with a persistent API token (saved in Settings > API Keys or `NOVELAI_API_KEY`; no fixed token prefix is required). Four models: `nai-diffusion-5-full`, `nai-diffusion-5-curated`, `nai-diffusion-4-5-full`, `nai-diffusion-4-5-curated`. Responses arrive as a ZIP archive that ima2 decodes to PNG. Text-to-image only — reference images, edits, and masks are refused rather than silently dropped. Browser and CLI surfaces expose negative prompt, sampler/schedule, steps/guidance/CFG rescale, seed, presets, Auto SMEA, Decrisper, Variety+, and V5 alpha.
+- `provider: "agy"` spawns the Antigravity CLI (`agy -p`) to generate images via Google Gemini's `default_api:generate_image` tool (models: `nano-banana-2` and `nano-banana-pro`). Output is fixed at 1024×1024 JPEG, max 3 reference images. No web search, quality, or size controls.
+- `provider: "gemini-api"` calls the Google Generative Language API directly. Supports two models: `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). Auth is via `GEMINI_API_KEY` env var, web UI key management, or a Vertex AI service account JSON (`VERTEX_SERVICE_ACCOUNT_JSON`). When both an API key and Vertex credentials are configured, Vertex takes priority. Supports variable aspect ratios (1:1 through 21:9) and four resolution tiers (512px, 1K, 2K, 4K); these controls are only honored on the direct API path — the Vertex AI endpoint ignores aspect/size because it does not accept the `response_format` field. Per-model cost differs: `nano-banana-2` (Flash): 512=$0.001, 1K=$0.003, 2K=$0.004, 4K=$0.006; `nano-banana-pro`: 1K=$0.007, 2K=$0.007, 4K=$0.013. No web search or mask controls.
+- API-key generation supports classic generate, edit, mask-guided edit, multimode, and node generation.
+- Grok generation supports Classic, Node, and Agent flows. If a Classic reference, Node parent image, or Agent current image is present, ima2 switches the final Grok call to xAI image edit so image-to-image context is preserved.
 
-![OAuth active と API key provider available の状態を示す settings 画面](../assets/screenshots/settings-oauth-generation.png)
+If no provider is specified, the app keeps the current GPT OAuth/default behavior. GPT OAuth defaults to `gpt-6-luna` and API-key generation to `gpt-5.6-luna`; the API-key path also defaults to `low` reasoning and `1024x1024` unless the request passes validated options. Grok image generation defaults to `grok-imagine-image-2.0`.
 
-## モデルの選び方
+One caveat on the OAuth Grok lane: xAI documents only `/v1/me` as accepting an OAuth token, so image and video calls to `api.x.ai` with that token ride an undocumented path. It works today — progrok relied on the same path — but it carries no compatibility promise. If xAI closes it, `provider: "grok-api"` with `XAI_API_KEY` is the documented route and stays unaffected.
 
-画像生成と Prompt Builder の既定値は **`gpt-5.6-luna`** です。旧モデルは互換オプションとして残ります。
+Grok image generation exposes a Fast/Best model picker (`grok-imagine-image` / `grok-imagine-image-quality`; new sessions start on `grok-imagine-image-2.0`) and a size picker (aspect ratio + 1k/2k resolution). The Settings page prefers the Grok Build weekly credits percentage and reset time from `GET /v1/billing?format=credits`; if that source is unavailable, it falls back to the legacy monthly billing window and `$used/$limit`. A **Switch Account** button starts a device-code OAuth flow (`POST /api/auth/switch`) for re-authenticating without leaving the app.
 
-- `gpt-5.6-luna` — 現在の画像・Prompt Builder 既定値。
-- `gpt-6-astra` — 最新の GPT 画像モデル。選択できますが既定値ではありません。
-- `gpt-5.6-terra` / `gpt-5.6-sol` — アカウントで利用できる GPT-5.6 オプション。
-- `gpt-5.5` / `gpt-5.4` / `gpt-5.4-mini` — 互換オプション。
+Grok video generation defaults to canonical `grok-imagine-video-1.5`; `grok-imagine-video` remains available for base-model-only Ref2V, V2V edit, and extension paths, and the legacy `grok-imagine-video-1.5-preview` string is accepted as an alias. Three modes are auto-detected from reference count: text-to-video (0 refs), image-to-video (1 ref), and reference-to-video (2-14 refs; up to 15s on grok-imagine-video-1.5, 10s on grok-imagine-video). 1080p is available for `grok-imagine-video-1.5` prompt-only text-to-video and single image/frame image-to-video; prompt-only 1.5 uses the internal white-canvas I2V shim before the upstream request. Video controls include duration (1-15s), resolution (480p, 720p, 1080p when supported), and aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto).
 
-Quality は `low`, `medium`, `high`、moderation は `auto`, `low` をサポートします。
+</details>
 
-## ワークフロー
+## CLI
 
-### Classic mode
+<details>
+<summary><b>サーバーコマンド (English)</b></summary>
 
-1枚をすばやく作って調整したいときに使います。
+| Command | Description |
+|---|---|
+| `ima2 serve [--dev]` | Start the local web server; `--dev` enables verbose server diagnostics |
+| `ima2 stop [--force]` | Stop the running server safely — graceful admin-API stop first, then SIGTERM/SIGKILL; verifies the advertised pid against `/api/health` so a recycled pid is never killed |
+| `ima2 service <sub>` | Background service: `install`/`uninstall`/`start`/`stop`/`restart`/`status`/`logs`/`repair` — launchd on macOS, systemd user unit on Linux, auto-start on login with crash restart |
+| `ima2 setup` | Reconfigure saved auth |
+| `ima2 status` | Show config and OAuth status |
+| `ima2 doctor` | Diagnose Node, package, config, and auth |
+| `ima2 doctor image-probe [--json]` | Run sanitized image probes for no-image diagnostics |
+| `ima2 open` | Open the web UI |
+| `ima2 reset` | Remove saved config |
 
-1. プロンプトを書きます。
-2. 必要なら参照画像を追加します。
-3. モデル、quality、size、format、moderation を選びます。
-4. 1枚を生成するか、multimode で同じプロンプトから複数候補を出します。
-5. 生成後、copy、download、continue、Canvas Mode cleanup を選べます。
+</details>
 
-![1つのプロンプトから4つの candidate slot が生成中で、sidebar に active job history が見える multimode sequence 画面](../assets/screenshots/multimode-sequence.png)
+<details>
+<summary><b>クライアントコマンド (English)</b></summary>
 
-### Node mode
+These require a running `ima2 serve`. The CLI covers every server route. The most common ones are below — the [full CLI reference](CLI.md) lists everything (generation, history, sessions, prompt library, annotations, Card News, observability, config).
 
-アイデアを枝分かれさせながら比較したいときに使います。
+| Command | Description |
+|---|---|
+| `ima2 models [--kind image\|video] [--lane <lane>] [--json]` | List live lanes, status, model IDs, and capabilities |
+| `ima2 defaults set image\|video <lane>/<model>` | Persist the fail-closed CLI target for image or video generation |
+| `ima2 defaults reset image\|video` | Remove a persisted CLI generation target |
+| `ima2 gen <prompt> [--model <lane>/<model>]` | Generate from the CLI; requires an explicit target or saved image default |
+| `ima2 edit <file> --prompt <text>` | Edit an existing image |
+| `ima2 vectorize <input.png> [-o output.svg]` | Trace PNG/JPEG/WebP into a real SVG locally; no server or provider required |
+| `ima2 prompt build --message <text> [--backend <backend>] [--model <model>]` | Refine prompt intent through the configured or explicitly selected Prompt Builder backend; requires the local server |
+| `ima2 multimode <prompt>` | Multi-image SSE generation |
+| `ima2 video <prompt> [--model <lane>/<model>]` | Generate video through a Grok or MCP lane; requires an explicit target or saved video default |
+| `ima2 ls [--session <id>] [--favorites]` | List recent history |
+| `ima2 show <name> [--metadata]` | Reveal a generated asset |
+| `ima2 prompt ls -q <search>` | Search the prompt library |
+| `ima2 inflight ls [--terminal]` | List active and recent jobs (alias of `ps`) |
+| `ima2 config set <key> <value>` | Write to `~/.ima2/config.json` |
+| `ima2 ping` | Health-check the running server |
+
+The server advertises its actual port at `~/.ima2/server.json`. If `3333` is busy, the backend falls back to `3334+` and CLI commands follow the advertised URL. Override discovery with `--server <url>` or `IMA2_SERVER=http://localhost:3333`.
 
-![接続された生成カードとノードごとのメタデータが見える Node mode 画面](../assets/screenshots/node-graph-branching.png)
+```bash
+ima2 models --kind image
+ima2 gen "poster" --model oauth/gpt-6-luna --reasoning-effort high
+ima2 gen "1girl, blue hair" --model nai/nai-diffusion-5-full --nai-negative-prompt "lowres, watermark"
+ima2 vectorize logo.png -o logo.svg --json
+ima2 prompt build --message "Make this prompt production-ready" --backend auto --model auto
+ima2 edit input.png --prompt "make it rainy" --web-search
+ima2 multimode "two cats playing" -n 2
+ima2 video "a cat playing piano" --model grok/grok-imagine-video-1.5 --duration 5 --resolution 720p
+ima2 video "animate this" --model grok/grok-imagine-video-1.5 --ref photo.png --aspect-ratio 16:9
+ima2 inflight ls --terminal
+ima2 config set imageModels.reasoningEffort high
+```
 
-各ノードは独自のプロンプトと結果を持ちます。ルートノードにはローカル参照画像を付けられ、子ノードは親画像をソースとして使います。完了した生成は request ID で再接続されるため、リロードや graph version conflict の後でも結果を復元できます。
+Full reference: [CLI.md](CLI.md).
 
-### Canvas Mode
+</details>
 
-生成結果がほぼ良いが、部分的な修正や背景整理が必要なときに使います。
+## 設定
 
-- ズーム状態でのビューポート移動（Pan）と選択ツールが分離されているため、アノテーションを誤操作することなく画面を移動できます。
-- annotation、eraser、multiselect、group、undo/redo、sticky note を使えます。
-- background cleanup seed を選び、mask preview を確認して canvas version として保存できます。
-- 透明画像は checkerboard preview で確認でき、export は alpha 保持または matte color 合成を選べます。
-- 保存された canvas version は Gallery/HistoryStrip には表示されませんが、Canvas Mode では再利用したり次の reference として添付できます。
+設定の優先順位は `環境変数 > ~/.ima2/config.json > 既定値` です。Prompt Builder の設定は `promptBuilder.backend` (`auto`、`oauth`、`grok`、`api`、`grok-api`) と `promptBuilder.model` に保存されます。Auto では GPT OAuth、Grok、OpenAI API、Grok API の順に試し、最初に準備できたレーンを使います。明示的に選んだバックエンドは固定され、使えないときは型付きのエラーを返します。
 
-![zoom controls, annotation marks, sticky note, canvas toolbar が見える Canvas Mode 画面](../assets/screenshots/canvas-mode-cleanup.png)
+<details>
+<summary><b>環境変数 (English)</b></summary>
 
-### Prompt library と import
+| Variable | Default | Description |
+|---|---:|---|
+| `IMA2_PORT` / `PORT` | `3333` | Web server port |
+| `IMA2_HOST` | `127.0.0.1` | Web server bind host |
+| `IMA2_OAUTH_PROXY_PORT` / `OAUTH_PORT` | `10531` | Port of the external GPT OAuth endpoint used with `IMA2_NO_OAUTH_PROXY=1` |
+| `IMA2_SERVER` | — | CLI target override |
+| `IMA2_CONFIG_DIR` | `~/.ima2` | Config and SQLite location |
+| `IMA2_ADVERTISE_FILE` | `~/.ima2/server.json` | Runtime discovery file |
+| `IMA2_GENERATED_DIR` | `~/.ima2/generated` | Generated image directory |
+| `IMA2_IMAGE_MODEL_DEFAULT` | `gpt-6-luna` | Server fallback image model |
+| `IMA2_PROMPT_BUILDER_BACKEND` | `auto` | Prompt Builder text backend (`auto`, `oauth`, `grok`, `api`, or `grok-api`); Settings persists the same value as `promptBuilder.backend` |
+| `IMA2_PROMPT_BUILDER_MODEL` | `auto` with Auto backend | Backend-scoped Builder model; Settings persists the same value as `promptBuilder.model` |
+| `IMA2_REASONING_EFFORT` | `medium` | Default reasoning effort for the default (GPT OAuth) path; one of `none`, `low`, `medium`, `high`, `xhigh`, `max` |
+| `IMA2_NO_OAUTH_PROXY` | — | Set `1` to send GPT OAuth calls to an OpenAI-compatible endpoint on `127.0.0.1:IMA2_OAUTH_PROXY_PORT` instead of ChatGPT directly |
+| `IMA2_CODEX_CLIENT_VERSION` | latest `@openai/codex` | Codex client version sent to ChatGPT; the automatic value is never lower than `0.157.0` |
+| `IMA2_LOG_LEVEL` | `info` | Normal serve defaults to `info`; dev mode defaults to `debug`; supports `debug`, `info`, `warn`, `error`, or `silent` |
+| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `300000` | Recent terminal job retention for debug views |
+| `OPENAI_API_KEY` | — | API key for the `provider: "api"` Responses API image path and auxiliary API-key features |
+| `XAI_API_KEY` | — | API key for `provider: "grok-api"` direct xAI Images API path |
+| `NOVELAI_API_KEY` | — | NovelAI persistent API token for `provider: "nai"` |
+| `IMA2_NAI_IMAGE_MODEL_DEFAULT` | `nai-diffusion-5-full` | Default NovelAI image model |
+| `IMA2_NAI_DEFAULT_AUTO_SMEA` | `false` | Default NovelAI Auto SMEA state |
+| `IMA2_NAI_DEFAULT_DECRISPER` | `false` | Default NovelAI Decrisper (`dynamic_thresholding`) state |
+| `IMA2_API_IMAGE_MODEL_DEFAULT` | `gpt-5.6-luna` | Default image model for `provider: "api"` |
+| `IMA2_API_REASONING_EFFORT` | `low` | Default reasoning effort for `provider: "api"` |
+| `IMA2_API_IMAGE_SIZE` | `1024x1024` | Default size for `provider: "api"` |
+| `IMA2_API_ALLOW_WEB_SEARCH` | `true` | Toggle web search for `provider: "api"` |
+| `IMA2_GROK_PLANNER_MODEL` | `grok-4.3` | Grok search/planner model; `grok-4.5`, `grok-4.6` and GPT planners are selectable (settings UI or `--planner-model`) |
+| `IMA2_GROK_PLANNER_TIMEOUT_MS` | `900000` | Timeout for the Grok planner call |
+| `IMA2_GROK_SEARCH_TIMEOUT_MS` | `300000` | Timeout for the Grok web-search brief (degrades instead of failing) |
+| `IMA2_GROK_VIDEO_PLAN_TOTAL_TIMEOUT_MS` | `1500000` | Ceiling on the whole video planning phase (clamped above search + planner) |
+| `IMA2_GROK_IMAGE_MODEL_DEFAULT` | `grok-imagine-image-2.0` | Default final Grok image model |
+| `IMA2_GROK_VIDEO_MODEL_DEFAULT` | `grok-imagine-video-1.5` | Default Grok video model |
+| `IMA2_GROK_GENERATION_TIMEOUT_MS` | `300000` | Timeout for the final Grok Images API call |
+| `IMA2_OAUTH_MASKED_EDIT_ENABLED` | `false` | Opt-in feature flag for masked-edit requests on the OAuth path (#31, groundwork only) |
+| `GEMINI_API_KEY` | — | API key for `provider: "gemini-api"` direct Generative Language API path |
+| `VERTEX_SERVICE_ACCOUNT_JSON` | — | Google service account JSON for Vertex AI auth with `provider: "gemini-api"`; takes priority over `GEMINI_API_KEY` when both are set |
+| `IMA2_AGY_BIN` | `agy` on PATH | Explicit path to the Antigravity CLI binary for `provider: "agy"` |
+| `IMA2_MAX_PARALLEL` | `24` | Server-wide parallel generation cap |
 
-Prompt library は local files、GitHub folders、curated sources、GPT-image hint packs から取り込めます。取り込んだ prompt は local index に保存され、毎セッション再 import しなくても検索と ranking に使えます。
+`IMA2_GROK_PROXY_HOST`, `IMA2_GROK_PROXY_PORT`, `IMA2_NO_GROK_PROXY`, and `IMA2_GROK_RESTART_*` were removed in 3.16 together with the local Grok proxy; they are no longer read, and setting them is harmless.
 
-![Prompt library に取り込む前に GitHub folder、curated sources、検索候補 prompt を確認する prompt import dialog](../assets/screenshots/prompt-import-dialog.png)
+</details>
 
-### Experimental Card News Mode
+<details>
+<summary><b>ログモード (English)</b></summary>
 
-Card News はまだ開発用の実験機能です。既定の公開ランタイムでは、開発用途として明示的に有効化しない限り非表示であり、安定した公開機能として扱うべきではありません。
+`ima2 serve` keeps terminal output intentionally quiet: startup URLs, warnings, and errors stay visible, while request/node/OAuth structured logs are hidden by default.
 
-### Settings
+Use `ima2 serve --dev`, `npm run dev`, or `IMA2_LOG_LEVEL=debug ima2 serve` when you need request IDs, node generation phases, OAuth stream diagnostics, or inflight state transitions. Explicit `IMA2_LOG_LEVEL` and `~/.ima2/config.json` values still override the built-in defaults.
 
-Settings ワークスペースでは、アカウント、モデル、テーマ、言語設定が生成パネルから独立しています。
+</details>
 
-![Account と Generation model controls が見える Settings workspace](../assets/screenshots/settings-workspace.png)
+## トラブルシューティング
 
-## CLI commands
+<details>
+<summary><b><code>ima2 ping</code> がサーバーにつながらない</b></summary>
 
-### Server
+先に `ima2 serve` を起動し、`~/.ima2/server.json` を確認してください。`ima2 ping --server http://localhost:3333` で直接指定することもできます。
 
-| Command | Description |
-|---|---|
-| `ima2 serve [--dev]` | ローカル Web サーバーを起動。`--dev` は詳細な server diagnostics を表示 |
-| `ima2 setup` | 認証設定を再構成 |
-| `ima2 status` | config と OAuth 状態を表示 |
-| `ima2 doctor` | Node、package、config、auth を診断 |
-| `ima2 doctor image-probe [--json]` | 画像なし診断用 sanitized probe |
-| `ima2 open` | Web UI を開く |
-| `ima2 reset` | 保存済み config を削除 |
+</details>
 
-### Client
+<details>
+<summary><b>GPT OAuth でログインできない</b></summary>
 
-以下は `ima2 serve` が起動しているときに使えます。CLI はサーバーのすべてのルートを ラップしています。よく使うコマンドのみ抜粋しました。完全なリストは [CLI リファレンス（英語）](CLI.md) を参照してください（generation、history、sessions、prompt library、annotations、Card News、observability、config を網羅）。
+`ima2 setup` を再実行し (1番)、`ima2 status` を確認してから `ima2 serve` を再起動してください。
 
-| Command | Description |
-|---|---|
-| `ima2 gen <prompt>` | CLI から画像生成 |
-| `ima2 edit <file> --prompt <text>` | 既存画像を編集 |
-| `ima2 multimode <prompt>` | マルチイメージ SSE 生成 |
-| `ima2 video <prompt>` | Grok 動画生成（SSE 進捗） |
-| `ima2 ls [--session <id>] [--favorites]` | ローカル履歴を表示 |
-| `ima2 show <name> [--metadata]` | 生成ファイルを開く |
-| `ima2 prompt ls -q <検索>` | プロンプトライブラリ検索 |
-| `ima2 inflight ls [--terminal]` | 進行中 / 直近完了ジョブ（`ps` のエイリアス）|
-| `ima2 config set <key> <value>` | `~/.ima2/config.json` に書き込み |
-| `ima2 ping` | サーバー疎通確認 |
+</details>
 
-サーバーポートは `~/.ima2/server.json` に保存されます。`3333` が埋まっている場合は `3334+` に fallback するため、terminal に表示された URL または `ima2 open` を優先してください。`--server <url>` または `IMA2_SERVER=http://localhost:3333` で上書きできます。
+<details>
+<summary><b>プロキシ/VPN 環境で <code>fetch failed</code> が繰り返される</b></summary>
 
-完全なコマンド一覧とフラグは [docs/CLI.md](CLI.md) にあります。
+GPT OAuth のリクエストは `ima2 serve` のプロセスから `chatgpt.com` へ直接送られます。プロキシが必要なネットワークでは、プロキシクライアントの TUN/TURN 系モードを有効にしてください。それが難しい場合は、サーバーを起動するターミナルで `HTTPS_PROXY` と `NODE_USE_ENV_PROXY=1` を両方設定します。Node.js 22.21 以降と 24 以降は 2 つ目の変数があるときだけ `HTTPS_PROXY` を読みます。それより古い Node.js はどちらも無視するので、TUN モードを使ってください。Windows では SecretDNS のような DNS・パケット分割回避ツールを含む、自動起動のネットワーク傍受ツールも確認してください。ブラウザがつながって見えても、OAuth や画像の応答が壊れることがあります。
 
-## Configuration
+</details>
 
-優先順位:
+<details>
+<summary><b><code>API_KEY_REQUIRED</code> で失敗する</b></summary>
 
-```text
-environment variables > ~/.ima2/config.json > built-in defaults
-```
+`provider: "api"` を使うには `OPENAI_API_KEY` を設定するか API キーを登録してください。既定の GPT OAuth 経路は API キーなしで動きます。
 
-| Variable | Default | Description |
-|---|---:|---|
-| `IMA2_PORT` / `PORT` | `3333` | Web server port |
-| `IMA2_HOST` | `127.0.0.1` | Web server bind host |
-| `IMA2_OAUTH_PROXY_PORT` / `OAUTH_PORT` | `10531` | OAuth proxy port |
-| `IMA2_SERVER` | — | CLI target override |
-| `IMA2_CONFIG_DIR` | `~/.ima2` | Config and SQLite location |
-| `IMA2_ADVERTISE_FILE` | `~/.ima2/server.json` | Runtime discovery file |
-| `IMA2_GENERATED_DIR` | `~/.ima2/generated` | Generated image directory |
-| `IMA2_IMAGE_MODEL_DEFAULT` | `gpt-5.6-luna` | Server fallback image model |
-| `IMA2_NO_OAUTH_PROXY` | — | `1` で OAuth proxy の自動起動を無効化 |
-| `IMA2_LOG_LEVEL` | `info` | 通常の `serve` は `info`、dev mode は `debug`。`debug`, `info`, `warn`, `error`, `silent` をサポート |
-| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `300000` | デバッグ用の recent job retention |
-| `OPENAI_API_KEY` | — | `provider: "api"` の Responses 画像パスと補助機能用 |
-| `XAI_API_KEY` | — | `provider: "grok-api"` 直接 xAI Images API |
-| `GEMINI_API_KEY` | — | `provider: "gemini-api"` Generative Language API |
-| `VERTEX_SERVICE_ACCOUNT_JSON` | — | Vertex AI サービスアカウント JSON（API キーより優先） |
-| `IMA2_AGY_BIN` | PATH の `agy` | `provider: "agy"` バイナリパス |
+</details>
 
-### Logging modes
+<details>
+<summary><b><code>EMPTY_RESPONSE</code> が返る、または画像データがない</b></summary>
 
-`ima2 serve` は通常ユーザー向けに terminal output を静かに保ちます。起動 URL、warning、error は表示されますが、request/node/OAuth structured logs は既定で隠されます。
+`ima2 doctor image-probe --json > ima2-image-probe.json` を実行し、サニタイズ済みの JSON を Issue に添付してください。GPT OAuth の場合は、`ima2 serve` を起動した状態で `ima2 gen "고양이" --model oauth/gpt-6-luna --no-web-search --json` と `ima2 gen "고양이" --model oauth/gpt-6-luna --json` の結果も残してください。ChatGPT の Cookie、OAuth token ファイル、API キー、生のアップストリーム応答、プロンプト履歴、生成された base64 は共有しないでください。詳しくは [FAQ のサポートバンドル](FAQ.md#what-should-i-share-when-gpt-oauth-image-generation-returns-no-image) を参照してください。
 
-request ID、Node generation phases、OAuth stream diagnostics、inflight state transitions を確認したい場合は、`ima2 serve --dev`、`npm run dev`、または `IMA2_LOG_LEVEL=debug ima2 serve` を使ってください。
+</details>
 
-## API Reference
+<details>
+<summary><b>大きな参照画像が失敗する</b></summary>
 
-Endpoint 一覧は [API Reference](API.md) に分離しました。
+大きな JPEG/PNG はアップロード前に自動で圧縮されます。それでも失敗する場合は、解像度を下げた JPEG か PNG に変換して再試行してください。ブラウザ経路では HEIC/HEIF に対応していません。
 
-詳しいFAQは [FAQ](FAQ.md) にまとめています。アップデート後に以前のギャラリー画像が見えない場合は、まず [Recover Old Generated Images](RECOVER_OLD_IMAGES.md) を確認してください。
+</details>
 
-## Troubleshooting
+<details>
+<summary><b>アップデート後に以前のギャラリー画像が見えない</b></summary>
 
-**`ima2 ping` が server unreachable になる**
-まず `ima2 serve` を起動し、`~/.ima2/server.json` を確認してください。`ima2 ping --server http://localhost:3333` も使えます。
+最近のバージョンは生成画像をインストール先のパッケージフォルダから `~/.ima2/generated` へ移しました。`ima2 doctor` を実行し、[以前の画像の復旧](RECOVER_OLD_IMAGES.md) を参照してください。
 
-**OAuth login がうまくいかない**
-`ima2 setup` を再実行（オプション 1）し、`ima2 status` を確認してから `ima2 serve` を再起動してください。
+</details>
 
-**proxy/VPN 環境で `fetch failed` が繰り返される**
-ローカル OAuth proxy に到達できるか確認してください。プロキシ必須のネットワークでは、プロキシクライアントの TUN/TURN 系モードを有効にしてから `openai-oauth --port 10531` を再試行してください。それでも失敗する場合は、`ima2 serve` や `openai-oauth` を実行する同じ terminal で `HTTP_PROXY` と `HTTPS_PROXY` を設定してください。Windows では SecretDNS など DNS/断片化バイパス系ツールが OAuth やストリーミング画像応答を壊すことがあります。
+<details>
+<summary><b>GPT OAuth レーンで GPT-6 モデルが見つからない、または拒否される</b></summary>
 
-**画像生成が `API_KEY_REQUIRED` で失敗する**
-`provider: "api"` request に使う API key が設定されていません。API key を設定するか OAuth provider に切り替えてください。
+GPT OAuth レーンは ChatGPT のプランで使える GPT-6 モデルを使います。ima2-gen を更新し、`ima2 gpt login` でログインし直してから `ima2 models --kind image` で確認してください。特定のモデルだけ失敗し続ける場合は、既定の `gpt-6-luna` に切り替えてください。
 
-**画像生成が `EMPTY_RESPONSE` になる、または画像データが返らない**
-`ima2 doctor image-probe --json > ima2-image-probe.json` を実行し、issue 作成時に安全な JSON を添付してください。GPT OAuth の場合は、`ima2 serve` 実行中に `ima2 gen "猫" --no-web-search --json` と `ima2 gen "猫" --json` も取得してください。ChatGPT cookie、OAuth トークンファイル、API key、生の upstream 応答、プロンプト履歴、生成 base64 は共有しないでください。詳細は [FAQ サポートバンドル](FAQ.md#what-should-i-share-when-oauth-image-generation-returns-no-image) を参照してください。
+</details>
 
-**大きな参照画像が失敗する**
-JPEG/PNG は送信前に自動圧縮されます。それでも失敗する場合は、解像度を下げた JPEG/PNG に変換してください。HEIC/HEIF は browser path ではサポートしていません。
+<details>
+<summary><b>アプリが別のポートで開いた</b></summary>
 
-**更新後に以前のギャラリー画像が見えない**
-最近のバージョンでは、生成画像の保存先がインストール済みパッケージ内から `~/.ima2/generated` に移動しました。`ima2 doctor` を実行し、[古い画像の復旧ガイド](RECOVER_OLD_IMAGES.md) を確認してください。
+要求したポートが使用中だと次の空きポートで起動し、`~/.ima2/server.json` に記録します。ポートが予期せず `3457` なら、シェルが別のローカルツールから `PORT=3457` を引き継いでいる可能性があります。`unset PORT` を実行するか、`IMA2_PORT=3333 ima2 serve` で起動してください。
 
-**`gpt-5.5` だけ失敗する**
-まず Codex CLI を最新版に更新してから再試行してください。それでも失敗する場合は、現在のアカウントやバックエンド経路で `gpt-5.5` の image capability または使用量枠がまだ異なる可能性があります。安定した代替として `gpt-5.4` を使ってください。
+</details>
 
-**別のポートでアプリが開く**
-要求した server ポートが使用中の場合、ima2-gen は次の空きポートに fallback し、`~/.ima2/server.json` に記録します。ポートが想定外の `3457` になる場合、shell が別ツールの `PORT=3457` を引き継いでいる可能性があります。`unset PORT` するか、`IMA2_PORT=3333 ima2 serve` で起動してください。
+その他の回答は [FAQ](FAQ.md) にあります。
 
-**Windows でポート `10531` が既に使われている**
-Windows のセキュリティツール（`AnySign4PC.exe` など）が既定 OAuth proxy ポートを占有することがあります。現在のビルドは実際の fallback OAuth ポートを追跡します。手動上書きが必要な場合は `IMA2_OAUTH_PROXY_PORT=11531 ima2 serve` で起動し、`ima2 doctor` で確認してください。
+## ドキュメント
 
-より詳しい確認手順は [FAQ](FAQ.md) を参照してください。
+- [開発者ドキュメントサイト](https://lidge-ai.github.io/ima2-gen/docs) — 概要、クイックスタート、アーキテクチャ、モード、プロバイダー、CLI、設定、サーバー API
+- [CLI リファレンス](CLI.md) · [API リファレンス](API.md) · [Prompt Studio](PROMPT_STUDIO.md) · [FAQ](FAQ.md) · [以前の画像の復旧](RECOVER_OLD_IMAGES.md)
 
-## Development
+## 開発
 
 ```bash
-git clone https://github.com/lidge-jun/ima2-gen.git
+git clone https://github.com/lidge-ai/ima2-gen.git
 cd ima2-gen
 npm install
 npm run dev
@@ -307,8 +459,65 @@ npm test
 npm run build
 ```
 
-`npm run dev` は UI を build し、TypeScript server entry を `--watch` で起動して verbose diagnostics を表示します。`npm run typecheck`, `npm run build:server`, `npm run build:cli` で TypeScript migration と package emit path を確認できます。
+`npm run dev` は UI をビルドし、TypeScript サーバーを `--watch` と詳細な診断ログで起動します。`npm run typecheck`、`npm run build:server`、`npm run build:cli` で TypeScript のビルド経路を確認できます。 Node mode と Canvas Mode は既定でパッケージ UI に含まれています。
+
+Web UI はすべての進捗を `GET /api/events` の Server-Sent Events 接続ひとつで受け取ります。マルチモード、ノード、動画のリクエストは非同期 POST (`202 { requestId }`) で送られ、共有イベントバスで多重化されるので、同時実行のジョブがブラウザの接続数上限6に引っかかることはありません。`async: true` を送らない CLI クライアントは、これまでどおりリクエストごとの SSE ストリームを受け取ります。
+
+### 動作要件
+
+<!-- runtime-install:generated:start -->
+| Contract | Value |
+|---|---|
+| Node engine | `>=22` |
+| npm toolchain | `npm@11.18.0` |
+| Release Node | `24.17.0` |
+| CLI entry | `bin/ima2.js` |
+| OpenAI SDK | `^7.4.0` |
+| Express | `^5.1.0` |
+<!-- runtime-install:generated:end -->
+
+インストーラーはパッケージのメタデータから Node.js の最低バージョンを読み取り、サーバーを起動する前にオフラインのインストール検査を行います。
+
+<details>
+<summary><b>デスクトップアプリのビルド (Electron, English)</b></summary>
+
+`desktop/` wraps the same local server and UI in a menubar/tray app for macOS, Windows, and Linux. It supervises `server.js` as a child process (attaching to an already-running server on the configured port instead of starting a second one) and adds a native settings window: port, open at login, start hidden, menubar-only (macOS), keep-server-on-close, log level, config directory.
+
+```bash
+cd desktop
+npm install
+npm run prepare:app     # builds server + CLI + UI at the repo root
+npm start               # run unpackaged
+npm run dist:mac        # dmg + zip (Apple Silicon / arm64)
+npm run dist:win        # nsis + zip
+npm run dist:linux      # AppImage + deb
+```
+
+Only the macOS app is distributed today, for Apple Silicon. `.github/workflows/desktop.yml` runs in three ways: a push to `dev` builds an unsigned macOS validation build, a manual dispatch builds signed and notarized installers without publishing anything, and a `desktop-v*` tag push builds, verifies, and publishes the desktop release. Trusted macOS builds require `MAC_CSC_LINK`, `MAC_CSC_KEY_PASSWORD`, `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, and `APPLE_TEAM_ID`; missing or invalid authentication fails the build instead of producing an unsigned success.
+
+For a signed macOS verification build without publishing, run:
+
+```bash
+gh workflow run desktop.yml --ref <reviewed-branch> -f platform=mac
+```
+
+The workflow verifies Developer ID, team, architecture (arm64), hardened runtime, secure timestamp, nested signatures, Gatekeeper and stapled notarization tickets. It checks the apps recovered from the final ZIP and DMG against the original signed content, then exports `ima2-macos-signature-proof` reports and installer SHA-256 hashes. Failed verification blocks installer upload. Only a `desktop-v*` tag push creates and publishes a release.
+
+Signing credential imports run on disposable GitHub-hosted macOS. The builder cleans successfully imported keychains; if import/setup fails before its cleanup registration, runner destruction is the final cleanup boundary. Local recovery should reuse an existing login-keychain identity in the same unlocked session, rather than importing credential packages into a persistent machine. This does not require changing automatic locking or key access rules.
+
+Windows Authenticode remains separate and uses `WIN_CSC_LINK` / `WIN_CSC_KEY_PASSWORD`; Windows builds without them are unsigned.
+
+</details>
+
+## コントリビューター
+
+- [@lidge-jun](https://github.com/lidge-jun) — maintainer
+- [@ree9622](https://github.com/ree9622) — moderation controls, Windows fixes, structured logging
+- [@Charley-Peng](https://github.com/Charley-Peng) — API cache fix (#74)
+- [@philiptaron](https://github.com/philiptaron) — Nix flake (#81)
+- [@aorying](https://github.com/aorying) — upstream validation error surfacing (informed TS migration direction)
+- [@PARKJONGMlN](https://github.com/PARKJONGMlN) — batch comparison matrix design (#80)
 
-## License
+## ライセンス
 
 MIT