ima2-gen 1.1.7 → 1.1.9

package/docs/FAQ.md

@@ -12,7 +12,7 @@ For Korean, see [FAQ.ko.md](FAQ.ko.md).
 |---|---|
 | The server is unreachable | Run `ima2 serve`, then `ima2 ping`. |
 | OAuth login fails | Run `npx @openai/codex login`, then restart `ima2 serve`. |
-| API key generation is disabled | Use OAuth for image generation. API keys are only used by auxiliary paths. |
+| API key provider says `API_KEY_REQUIRED` | Configure an API key, or switch back to the OAuth provider. |
 | Old gallery images look missing | Run `ima2 doctor`, then see [Recover Old Generated Images](RECOVER_OLD_IMAGES.md). |
 | `gpt-5.5` fails | Update Codex CLI first, then try `gpt-5.4` as the stable fallback. |
 | Reference upload fails | Use JPEG/PNG, lower the resolution, and keep references to 5 images or fewer. |
@@ -76,13 +76,13 @@ again.
 
 ### Do I need an OpenAI API key?
 
-No for image generation. The normal generation path uses your local Codex/ChatGPT OAuth session.
+No for the default generation path. The normal path uses your local Codex/ChatGPT OAuth session.
 
-You may still see an API key detected in settings. That only means an API key exists in env/config. Image generation routes still reject `provider: "api"` with `APIKEY_DISABLED`.
+If you configure an API key, image generation routes can also use `provider: "api"` through the Responses API `image_generation` tool.
 
-### Why does the settings page say "Configured but disabled"?
+### Why does the settings page say "API key provider available"?
 
-It means `ima2-gen` found an API key, but API-key image generation is intentionally disabled in this build. Use OAuth for generation.
+It means `ima2-gen` found a valid API key. API-key mode can generate, edit, run multimode, and create node outputs. If no key is configured, `provider: "api"` fails before upstream with `API_KEY_REQUIRED`.
 
 ### If Codex CLI is already logged in, does ima2-gen reuse it?
 

package/docs/README.ja.md

@@ -4,11 +4,13 @@
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-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-CN.md)
 
 `ima2-gen` は、ChatGPT/Codex OAuth の画像生成ワークフローをローカルの小さなデスクトップアプリのように使える画像生成スタジオです。
 
-`npx` で起動し、Codex OAuth でログインして、プロンプトを書きながら履歴、参照画像、スタイルシート、ノード分岐で反復できます。通常の画像生成には OpenAI API key は不要です。
+`npx` で起動し、Codex OAuth でログインして、プロンプトを書きながら履歴や参照画像、ノード分岐、multimode batch、Canvas Mode cleanup を活用して試行錯誤（イテレーション）が可能です。通常の画像生成には OpenAI API key は不要です。
 
 ![プロンプト入力、生成画像、モデル表示、結果メタデータが見える ima2-gen classic 画面](../assets/screenshots/classic-generate-light.png)
 
@@ -27,6 +29,8 @@ npx @openai/codex login
 npx ima2-gen serve
 ```
 
+`3333` がすでに使われている場合、次に空いているポートで起動し、実際の URL は `~/.ima2/server.json` に書き込まれます。ポートを決め打ちせず、terminal に表示された URL または `ima2 open` を使ってください。
+
 グローバルインストールもできます。
 
 ```bash
@@ -38,28 +42,31 @@ ima2 serve
 
 - **Classic mode**: すばやく生成し、編集し、現在の画像を次の参照として使えます。
 - **Node mode**: 良い画像を起点に、複数の方向へ分岐して試せます。
+- **Multimode batches**: 1つのプロンプトから複数候補を同時に走らせ、slot ごとの進行を見ながら最も良い結果から作業を継続できます。
+- **Canvas Mode**: zoom/pan、annotation、eraser、background cleanup、transparent checkerboard preview、alpha/matte export をサポートします。
 - **Local gallery**: 生成物をローカルに保存し、セッションごとの履歴として確認できます。
 - **Reference images**: 参照画像を drag/drop、paste、file picker で追加できます。大きな画像は送信前に圧縮されます。
-- **Style sheets**: 一度決めた見た目の方向性を classic/node プロンプトに再利用できます。
+- **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 で追跡できます。
 
-## 画像生成は OAuth 専用です
+## 画像生成は OAuth と API key をサポートします
 
-現在の画像生成は、ローカルの Codex/ChatGPT OAuth 経路で実行されます。
+既定の画像生成は、ローカルの Codex/ChatGPT OAuth 経路で実行されます。
 
-API key が env/config に存在していても、billing 確認や style-sheet 抽出などの補助機能に使われるだけです。生成エンドポイントで `provider: "api"` を送ると `APIKEY_DISABLED` が返ります。
+API key が env/config に存在する場合、生成エンドポイントで `provider: "api"` を指定すると Responses API の `image_generation` tool を使用できます。
 
-Settings に **Configured but disabled** と表示される場合、API key は検出されていますが、画像生成は OAuth で動いているという意味です。
+Settings に **API key provider available** と表示される場合、API key が検出され、生成・編集・multimode・node request に使用できるという意味です。
 
-![OAuth active と API key disabled の状態を示す settings 画面](../assets/screenshots/settings-oauth-generation.png)
+![OAuth active と API key provider available の状態を示す settings 画面](../assets/screenshots/settings-oauth-generation.png)
 
 ## モデルの選び方
 
-安定したバランスを重視するなら、まず **`gpt-5.4`** をおすすめします。
+アプリの既定値は、高速なローカルでの試行錯誤に適した **`gpt-5.4-mini`** です。安定したバランスを重視するなら **`gpt-5.4`** に切り替えることをおすすめします。
 
 - `gpt-5.4` — 推奨のバランス型モデル。
-- `gpt-5.4-mini` — 現在のアプリ既定値で、速い下書き向きです。
-- `gpt-5.5` — 対応環境では最も高品質な選択肢です。ただし使用量の消費が大きくなる場合があり、Codex CLI の更新やアカウント/バックエンド側の image capability が必要になることがあります。
+- `gpt-5.4-mini` — 現在のアプリ既定値で、素早いドラフト作成に向いています。
+- `gpt-5.5` — 対応環境では最も高品質な出力が得られる選択肢です。ただし使用量の消費が大きくなる場合があり、Codex CLI の更新やアカウント/バックエンド側の image capability が必要になることがあります。
 
 Quality は `low`, `medium`, `high`、moderation は `auto`, `low` をサポートします。
 
@@ -72,7 +79,10 @@ Quality は `low`, `medium`, `high`、moderation は `auto`, `low` をサポー
 1. プロンプトを書きます。
 2. 必要なら参照画像を追加します。
 3. モデル、quality、size、format、moderation を選びます。
-4. 生成後、copy、download、continue を選べます。
+4. 1枚を生成するか、multimode で同じプロンプトから複数候補を出します。
+5. 生成後、copy、download、continue、Canvas Mode cleanup を選べます。
+
+![1つのプロンプトから4つの candidate slot が生成中で、sidebar に active job history が見える multimode sequence 画面](../assets/screenshots/multimode-sequence.png)
 
 ### Node mode
 
@@ -82,15 +92,33 @@ Quality は `low`, `medium`, `high`、moderation は `auto`, `low` をサポー
 
 各ノードは独自のプロンプトと結果を持ちます。ルートノードにはローカル参照画像を付けられ、子ノードは親画像をソースとして使います。完了した生成は request ID で再接続されるため、リロードや graph version conflict の後でも結果を復元できます。
 
-### Settings と Style sheets
+### Canvas Mode
 
-Settings workspace は、アカウント、モデル、テーマ、言語設定を生成パネルから分離します。
+生成結果がほぼ良いが、部分的な修正や背景整理が必要なときに使います。
 
-![Account と Generation model controls が見える Settings workspace](../assets/screenshots/settings-workspace.png)
+- ズーム状態でのビューポート移動（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 として添付できます。
+
+![zoom controls, annotation marks, sticky note, canvas toolbar が見える Canvas Mode 画面](../assets/screenshots/canvas-mode-cleanup.png)
+
+### Prompt library と import
+
+Prompt library は local files、GitHub folders、curated sources、GPT-image hint packs から取り込めます。取り込んだ prompt は local index に保存され、毎セッション再 import しなくても検索と ranking に使えます。
+
+![Prompt library に取り込む前に GitHub folder、curated sources、検索候補 prompt を確認する prompt import dialog](../assets/screenshots/prompt-import-dialog.png)
+
+### Experimental Card News Mode
 
-Style sheet は、繰り返し使いたい視覚方向を保存するための機能です。
+Card News はまだ開発用の実験機能です。既定の公開ランタイムでは、開発用途として明示的に有効化しない限り非表示であり、安定した公開機能として扱うべきではありません。
 
-![medium, composition, mood, subject, palette, negative fields を持つ style sheet editor](../assets/screenshots/style-sheet-editor.png)
+### Settings
+
+Settings ワークスペースでは、アカウント、モデル、テーマ、言語設定が生成パネルから独立しています。
+
+![Account と Generation model controls が見える Settings workspace](../assets/screenshots/settings-workspace.png)
 
 ## CLI commands
 
@@ -98,7 +126,7 @@ Style sheet は、繰り返し使いたい視覚方向を保存するための
 
 | Command | Description |
 |---|---|
-| `ima2 serve` | ローカル Web サーバーを起動 |
+| `ima2 serve [--dev]` | ローカル Web サーバーを起動。`--dev` は詳細な server diagnostics を表示 |
 | `ima2 setup` | 認証設定を再構成 |
 | `ima2 status` | config と OAuth 状態を表示 |
 | `ima2 doctor` | Node、package、config、auth を診断 |
@@ -107,18 +135,23 @@ Style sheet は、繰り返し使いたい視覚方向を保存するための
 
 ### Client
 
-以下は `ima2 serve` が起動しているときに使えます。
+以下は `ima2 serve` が起動しているときに使えます。CLI はサーバーのすべてのルートを ラップしています。よく使うコマンドのみ抜粋しました。完全なリストは [CLI リファレンス（英語）](CLI.md) を参照してください（generation、history、sessions、prompt library、annotations、Card News、observability、config を網羅）。
 
 | Command | Description |
 |---|---|
 | `ima2 gen <prompt>` | CLI から画像生成 |
 | `ima2 edit <file> --prompt <text>` | 既存画像を編集 |
-| `ima2 ls` | ローカル履歴を表示 |
-| `ima2 show <name>` | 生成ファイルを開く |
-| `ima2 ps` | 進行中ジョブを表示 |
-| `ima2 ping` | 実行中サーバーを確認 |
+| `ima2 multimode <prompt>` | マルチイメージ 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` | サーバー疎通確認 |
+
+サーバーポートは `~/.ima2/server.json` に保存されます。`3333` が埋まっている場合は `3334+` に fallback するため、terminal に表示された URL または `ima2 open` を優先してください。`--server <url>` または `IMA2_SERVER=http://localhost:3333` で上書きできます。
 
-サーバーポートは `~/.ima2/server.json` に保存されます。`--server <url>` または `IMA2_SERVER=http://localhost:3333` で上書きできます。
+完全なコマンド一覧とフラグは [docs/CLI.md](CLI.md) にあります。
 
 ## Configuration
 
@@ -131,14 +164,24 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | 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.4-mini` | Server fallback image model |
 | `IMA2_NO_OAUTH_PROXY` | — | `1` で OAuth proxy の自動起動を無効化 |
+| `IMA2_LOG_LEVEL` | `warn` | 通常の `serve` は `warn`、dev mode は `debug`。`debug`, `info`, `warn`, `error`, `silent` をサポート |
 | `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `30000` | デバッグ用の recent job retention |
 | `OPENAI_API_KEY` | — | 補助機能用。画像生成用ではありません |
 
+### Logging modes
+
+`ima2 serve` は通常ユーザー向けに terminal output を静かに保ちます。起動 URL、warning、error は表示されますが、request/node/OAuth structured logs は既定で隠されます。
+
+request ID、Node generation phases、OAuth stream diagnostics、inflight state transitions を確認したい場合は、`ima2 serve --dev`、`npm run dev`、または `IMA2_LOG_LEVEL=debug ima2 serve` を使ってください。
+
 ## API Reference
 
 Endpoint 一覧は [API Reference](API.md) に分離しました。
@@ -153,8 +196,8 @@ Endpoint 一覧は [API Reference](API.md) に分離しました。
 **OAuth login がうまくいかない**
 `npx @openai/codex login` を実行し、`ima2 status` を確認してから `ima2 serve` を再起動してください。
 
-**画像生成が `APIKEY_DISABLED` で失敗する**
-この build では OAuth で生成してください。API-key image generation は意図的に無効化されています。
+**画像生成が `API_KEY_REQUIRED` で失敗する**
+`provider: "api"` request に使う API key が設定されていません。API key を設定するか OAuth provider に切り替えてください。
 
 **大きな参照画像が失敗する**
 JPEG/PNG は送信前に自動圧縮されます。それでも失敗する場合は、解像度を下げた JPEG/PNG に変換してください。HEIC/HEIF は browser path ではサポートしていません。
@@ -177,10 +220,13 @@ git clone https://github.com/lidge-jun/ima2-gen.git
 cd ima2-gen
 npm install
 npm run dev
+npm run typecheck
 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 を確認できます。
+
 ## License
 
 MIT

package/docs/README.ko.md

@@ -4,11 +4,13 @@
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-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.ja.md) · [简体中文](README.zh-CN.md)
 
 `ima2-gen`은 ChatGPT/Codex OAuth 이미지 생성 흐름을 로컬 웹앱처럼 쓸 수 있게 만든 이미지 생성 스튜디오입니다.
 
-`npx`로 실행하고, Codex OAuth로 로그인한 뒤, 프롬프트를 입력하면서 히스토리, 레퍼런스, 스타일 시트, 노드 브랜치로 계속 이어갈 수 있습니다. 기본 이미지 생성 경로에서는 OpenAI API 키가 필요하지 않습니다.
+`npx`로 실행하고, Codex OAuth로 로그인한 뒤, 프롬프트를 입력하면서 히스토리, 레퍼런스, 노드 브랜치, 멀티모드 배치, Canvas Mode 정리 작업으로 계속 이어갈 수 있습니다. 기본 이미지 생성 경로에서는 OpenAI API 키가 필요하지 않습니다.
 
 ![프롬프트 작성창, 생성 이미지, 모델 표시, 결과 메타데이터가 보이는 ima2-gen 클래식 생성 화면](../assets/screenshots/classic-generate-light.png)
 
@@ -27,6 +29,8 @@ npx @openai/codex login
 npx ima2-gen serve
 ```
 
+`3333`이 이미 사용 중이면 다음 사용 가능한 포트로 열리고 실제 URL은 `~/.ima2/server.json`에 기록됩니다. 포트를 추측하지 말고 터미널에 출력된 URL이나 `ima2 open`을 사용하세요.
+
 전역 설치도 가능합니다.
 
 ```bash
@@ -38,26 +42,29 @@ ima2 serve
 
 - **Classic mode**: 빠르게 이미지를 만들고, 수정하고, 현재 결과를 다시 레퍼런스로 사용합니다.
 - **Node mode**: 마음에 드는 이미지를 여러 방향으로 분기해 실험합니다.
+- **Multimode batches**: 하나의 프롬프트에서 여러 후보 슬롯을 동시에 만들고, 가장 좋은 결과에서 이어갑니다.
+- **Canvas Mode**: 확대/이동, 주석, 지우개, 배경 정리, 투명 체크보드 미리보기, alpha/matte export를 지원합니다.
 - **Local gallery**: 생성물을 내 컴퓨터에 저장하고 세션별 히스토리로 봅니다.
 - **Reference images**: 레퍼런스를 드래그, 붙여넣기, 파일 선택으로 추가합니다. 큰 이미지는 업로드 전에 자동 압축됩니다.
-- **Style sheets**: 한 번 잡은 시각적 방향을 classic/node 프롬프트에 재사용합니다.
-- **Observable jobs**: 진행 중 작업과 최근 작업을 request ID로 추적합니다.
+- **Prompt library imports**: 로컬 prompt pack, GitHub folder, curated GPT-image hint를 내장 prompt library로 가져옵니다.
+- **Mobile shell**: 작은 화면에서는 app bar, compose sheet, compact settings toggle로 조작합니다.
+- **Observable jobs**: 진행 중인 작업과 최근 완료된 작업을 request ID로 추적합니다.
 
-## 이미지 생성은 OAuth 전용입니다
+## 이미지 생성은 OAuth와 API Key를 지원합니다
 
-현재 이미지 생성은 로컬 Codex/ChatGPT OAuth 경로로 실행됩니다.
+기본 이미지 생성은 로컬 Codex/ChatGPT OAuth 경로로 실행됩니다.
 
-API 키가 env/config에 있어도 billing 확인이나 style-sheet 추출 같은 보조 기능에만 쓰일 수 있습니다. 생성 엔드포인트에서 `provider: "api"`를 보내면 `APIKEY_DISABLED`가 반환됩니다.
+API 키가 env/config에 있으면 생성 엔드포인트에서 `provider: "api"`를 보내 Responses API `image_generation` 도구를 사용할 수 있습니다.
 
-설정 화면에 **Configured but disabled**가 보이면, API 키는 감지됐지만 이미지 생성은 여전히 OAuth로 실행된다는 뜻입니다.
+설정 화면에 **API key provider available**이 보이면, API 키가 감지됐고 생성/편집/멀티모드/노드 요청에 사용할 수 있다는 뜻입니다.
 
 ![OAuth 활성화와 API 키 비활성 상태를 보여주는 설정 화면](../assets/screenshots/settings-oauth-generation.png)
 
 ## 모델 안내
 
-안정적인 균형을 원하면 **`gpt-5.4`**부터 써보는 것을 권장합니다.
+앱 기본값은 빠른 로컬 작업(테스트)에 맞춘 **`gpt-5.4-mini`**입니다. 안정적인 균형을 원하면 **`gpt-5.4`**로 전환하는 것을 권장합니다.
 
-- `gpt-5.4` — 추천 기본 선택지.
+- `gpt-5.4` — 추천 균형 선택지.
 - `gpt-5.4-mini` — 현재 앱 기본값이며 빠른 초안에 적합합니다.
 - `gpt-5.5` — 지원되는 환경에서는 가장 강한 품질 선택지입니다. 다만 더 많은 할당량을 쓸 수 있고, Codex CLI 업데이트가 필요하거나 계정/백엔드별 이미지 capability가 다를 수 있습니다.
 
@@ -72,7 +79,10 @@ API 키가 env/config에 있어도 billing 확인이나 style-sheet 추출 같
 1. 프롬프트를 씁니다.
 2. 필요하면 레퍼런스를 붙입니다.
 3. 모델, 품질, 크기, 포맷, 모더레이션을 고릅니다.
-4. 생성 후 복사, 다운로드, 이어서 작업을 선택합니다.
+4. 한 장을 만들거나, multimode를 켜서 같은 프롬프트에서 여러 후보 슬롯을 만듭니다.
+5. 생성 후 복사, 다운로드, 이어서 작업, Canvas Mode 정리를 선택합니다.
+
+![하나의 프롬프트에서 네 후보 슬롯이 생성 중이고 sidebar에 active job history가 보이는 multimode sequence 화면](../assets/screenshots/multimode-sequence.png)
 
 ### Node mode
 
@@ -82,15 +92,33 @@ API 키가 env/config에 있어도 billing 확인이나 style-sheet 추출 같
 
 각 노드는 자기 프롬프트와 결과를 가집니다. 루트 노드는 로컬 레퍼런스를 붙일 수 있고, 자식 노드는 부모 이미지를 소스로 사용합니다. 완료된 작업은 request ID로 다시 매칭되므로 새로고침이나 그래프 버전 충돌 뒤에도 결과를 복구할 수 있습니다.
 
-### Settings와 Style sheets
+### Canvas Mode
 
-설정 화면은 계정, 모델, 테마, 언어 설정을 생성 패널 밖으로 분리합니다.
+이미지가 거의 맞지만 부분 정리가 필요할 때 Canvas Mode를 사용합니다.
 
-![계정 영역과 생성 모델 설정이 보이는 설정 워크스페이스](../assets/screenshots/settings-workspace.png)
+- 확대된 이미지에서 viewport 이동과 선택 도구가 분리되어 실수로 annotation을 바꾸지 않고 화면을 이동할 수 있습니다.
+- annotation, eraser, multiselect, group, undo/redo, sticky note를 사용할 수 있습니다.
+- 배경 정리용 시드(seed)를 지정하여 마스크를 미리 본 뒤 canvas version으로 저장할 수 있습니다.
+- 투명 이미지에는 checkerboard preview를 보여주고, export는 alpha 유지 또는 matte 색상 합성 중 선택할 수 있습니다.
+- 저장된 canvas version은 Gallery/HistoryStrip에는 보이지 않지만, Canvas Mode에서는 재사용하거나 다음 reference로 붙일 수 있습니다.
+
+![Zoom controls, annotation, sticky note, canvas toolbar가 보이는 Canvas Mode 화면](../assets/screenshots/canvas-mode-cleanup.png)
+
+### Prompt library와 Import
+
+Prompt library는 로컬 파일, GitHub folder, curated source, GPT-image hint pack에서 가져올 수 있습니다. 가져온 prompt는 로컬 index에 저장되어 매 세션 다시 import하지 않아도 검색과 ranking에 사용할 수 있습니다.
 
-Style sheet는 반복해서 쓰고 싶은 시각적 방향을 저장하는 기능입니다.
+![프롬프트를 라이브러리로 불러오기 전에 GitHub 폴더, 추천 소스, 검색된 후보를 검토하는 프롬프트 불러오기 다이얼로그](../assets/screenshots/prompt-import-dialog.png)
 
-![medium, composition, mood, subject, palette, negative 필드가 있는 스타일 시트 편집 화면](../assets/screenshots/style-sheet-editor.png)
+### Experimental Card News Mode
+
+Card News는 아직 개발 전용 실험 기능입니다. 기본 공개 런타임에서는 명시적으로 개발용으로 켜지 않는 한 숨겨져 있으며, 아직 안정적인 공개 기능으로 보면 안 됩니다.
+
+### Settings
+
+Settings 워크스페이스는 계정, 모델, 테마, 언어 설정을 생성 패널에서 독립시켜 관리합니다.
+
+![계정 영역과 생성 모델 설정이 보이는 설정 워크스페이스](../assets/screenshots/settings-workspace.png)
 
 ## CLI 명령어
 
@@ -107,18 +135,23 @@ Style sheet는 반복해서 쓰고 싶은 시각적 방향을 저장하는 기
 
 ### 클라이언트
 
-아래 명령어는 `ima2 serve`가 실행 중이어야 합니다.
+아래 명령어는 `ima2 serve`가 실행 중이어야 합니다. CLI는 모든 서버 라우트를 감쌉니다. 자주 쓰는 명령어만 추렸고, 전체 목록은 [CLI 레퍼런스(영문)](CLI.md)에 있습니다 (생성, 히스토리, 세션, 프롬프트 라이브러리, 어노테이션, Card News, observability, config 모두 포함).
 
 | 명령어 | 설명 |
 |---|---|
 | `ima2 gen <prompt>` | CLI에서 이미지 생성 |
 | `ima2 edit <file> --prompt <text>` | 기존 이미지 수정 |
-| `ima2 ls` | 로컬 히스토리 보기 |
-| `ima2 show <name>` | 생성 파일 열기 |
-| `ima2 ps` | 진행 중 작업 보기 |
-| `ima2 ping` | 실행 중인 서버 확인 |
+| `ima2 multimode <prompt>` | 멀티 이미지 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` | 서버 헬스 체크 |
+
+서버 포트는 `~/.ima2/server.json`에 기록됩니다. `3333`이 사용 중이면 `3334+`로 fallback할 수 있으니 터미널에 출력된 URL이나 `ima2 open`을 우선 사용하세요. `--server <url>` 또는 `IMA2_SERVER=http://localhost:3333`로 직접 지정할 수도 있습니다.
 
-서버 포트는 `~/.ima2/server.json`에 기록됩니다. `--server <url>` 또는 `IMA2_SERVER=http://localhost:3333`로 직접 지정할 수도 있습니다.
+전체 명령 목록과 플래그: [docs/CLI.md](CLI.md).
 
 ## 설정
 
@@ -131,10 +164,13 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | 변수 | 기본값 | 설명 |
 |---|---:|---|
 | `IMA2_PORT` / `PORT` | `3333` | 웹 서버 포트 |
+| `IMA2_HOST` | `127.0.0.1` | 웹 서버 bind host |
 | `IMA2_OAUTH_PROXY_PORT` / `OAUTH_PORT` | `10531` | OAuth 프록시 포트 |
 | `IMA2_SERVER` | — | CLI 대상 서버 직접 지정 |
 | `IMA2_CONFIG_DIR` | `~/.ima2` | config와 SQLite 저장 위치 |
+| `IMA2_ADVERTISE_FILE` | `~/.ima2/server.json` | 실행 중 서버 discovery 파일 |
 | `IMA2_GENERATED_DIR` | `~/.ima2/generated` | 생성 이미지 저장 위치 |
+| `IMA2_IMAGE_MODEL_DEFAULT` | `gpt-5.4-mini` | 서버 fallback 이미지 모델 |
 | `IMA2_NO_OAUTH_PROXY` | — | `1`이면 OAuth 프록시 자동 시작 비활성화 |
 | `IMA2_LOG_LEVEL` | `warn` | 일반 `serve`는 `warn`, dev 모드는 `debug`. `debug`, `info`, `warn`, `error`, `silent` 지원 |
 | `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `30000` | 디버그용 최근 작업 보존 시간 |
@@ -163,8 +199,8 @@ environment variables > ~/.ima2/config.json > built-in defaults
 **프록시/VPN 환경에서 `fetch failed`가 반복돼요**
 로컬 OAuth 프록시가 접근 가능한지 확인하세요. 프록시가 필요한 네트워크라면 프록시 클라이언트의 TUN/TURN류 모드를 켠 뒤 `npx openai-oauth --port 10531`을 다시 시도하세요. 그래도 실패하면 `ima2 serve` 또는 `openai-oauth`를 실행하는 같은 터미널에 `HTTP_PROXY`와 `HTTPS_PROXY`를 설정하세요.
 
-**이미지 생성이 `APIKEY_DISABLED`로 실패해요**
-현재 빌드에서는 OAuth로 생성해야 합니다. API-key 이미지 생성은 의도적으로 비활성화되어 있습니다.
+**이미지 생성이 `API_KEY_REQUIRED`로 실패해요**
+`provider: "api"` 요청에 사용할 API 키가 설정되어 있지 않다는 뜻입니다. API 키를 설정하거나 OAuth 공급자로 전환하세요.
 
 **큰 레퍼런스 이미지가 실패해요**
 JPEG/PNG는 업로드 전에 자동 압축됩니다. 그래도 실패하면 해상도를 낮춘 JPEG/PNG로 바꿔 다시 시도하세요. HEIC/HEIF는 브라우저 경로에서 지원하지 않습니다.
@@ -187,11 +223,12 @@ git clone https://github.com/lidge-jun/ima2-gen.git
 cd ima2-gen
 npm install
 npm run dev
+npm run typecheck
 npm test
 npm run build
 ```
 
-`npm run dev`는 UI를 빌드한 뒤 `server.js`를 `--watch`로 실행하고, 서버 진단 로그를 자세히 표시합니다.
+`npm run dev`는 UI를 빌드한 뒤 TypeScript 서버 entry를 `--watch`로 실행하고, 서버 진단 로그를 자세히 표시합니다. `npm run typecheck`, `npm run build:server`, `npm run build:cli`로 TypeScript migration과 package emit 경로를 확인할 수 있습니다.
 
 ## 라이선스
 

package/docs/README.zh-CN.md

@@ -4,11 +4,13 @@
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-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.ja.md)
 
-`ima2-gen` 是一个本地图像生成工作室，让你像使用小型桌面应用一样使用 ChatGPT/Codex OAuth 图像生成流程。
+`ima2-gen` 是一个本地图像生成工作室，为你提供类似小型桌面应用的 ChatGPT/Codex OAuth 图像生成体验。
 
-用 `npx` 启动，登录 Codex OAuth，输入 prompt，然后通过历史记录、参考图、style sheet 和节点分支持续迭代。默认图像生成路径不需要 OpenAI API key。
+用 `npx` 启动，登录 Codex OAuth，输入 prompt，然后通过历史记录、参考图、节点分支、multimode 批量候选和 Canvas Mode 清理持续迭代。默认图像生成路径不需要 OpenAI API key。
 
 ![显示 prompt 输入区、生成图片、模型标签和结果元数据的 ima2-gen classic 界面](../assets/screenshots/classic-generate-light.png)
 
@@ -27,6 +29,8 @@ npx @openai/codex login
 npx ima2-gen serve
 ```
 
+如果 `3333` 已经被占用，server 会绑定下一个可用端口，并把实际 URL 写入 `~/.ima2/server.json`。不要假设端口固定，请使用终端输出的 URL 或 `ima2 open`。
+
 也可以全局安装：
 
 ```bash
@@ -38,28 +42,31 @@ ima2 serve
 
 - **Classic mode**：快速生成、编辑，并把当前图片继续作为参考图使用。
 - **Node mode**：从一张满意的图出发，向多个方向分支探索。
-- **Local gallery**：把生成结果保存在本机，并按 session 查看历史。
+- **Multimode batches**：用同一个 prompt 同时生成多个候选 slot，并从最好的结果继续。
+- **Canvas Mode**：支持缩放/平移、标注、橡皮擦、背景清理、透明 checkerboard 预览，以及 alpha/matte export。
+- **Local gallery**：将生成结果保存在本地，并按会话 (session) 查看历史。
 - **Reference images**：支持拖放、粘贴和文件选择；大图会在上传前自动压缩。
-- **Style sheets**：保存一套视觉方向，并复用到 classic/node prompt。
+- **Prompt library imports**：把本地 prompt pack、GitHub folder、curated GPT-image hint 导入内置 prompt library。
+- **Mobile shell**：小屏幕使用 app bar、compose sheet 和 compact settings toggle。
 - **Observable jobs**：用 request ID 追踪进行中和最近完成的任务。
 
-## 图像生成只走 OAuth
+## 图像生成支持 OAuth 和 API key
 
-当前图像生成通过本地 Codex/ChatGPT OAuth 路径执行。
+默认图像生成通过本地 Codex/ChatGPT OAuth 路径执行。
 
-即使 env/config 里有 API key，它也只可能用于 billing 检查或 style-sheet 提取等辅助功能。生成接口收到 `provider: "api"` 时会返回 `APIKEY_DISABLED`。
+如果 env/config 里有 API key，生成接口可以通过 `provider: "api"` 使用 Responses API 的 `image_generation` tool。
 
-如果设置页显示 **Configured but disabled**，意思是检测到了 API key，但图像生成仍然使用 OAuth。
+如果设置页显示 **API key provider available**，意思是检测到了 API key，并且可用于生成、编辑、multimode 和 node 请求。
 
-![显示 OAuth active 与 API key disabled 状态的设置页](../assets/screenshots/settings-oauth-generation.png)
+![显示 OAuth active 与 API key provider available 状态的设置页](../assets/screenshots/settings-oauth-generation.png)
 
 ## 模型建议
 
-如果想要稳定、均衡的结果，建议先从 **`gpt-5.4`** 开始。
+应用默认使用适合快速本地迭代的 **`gpt-5.4-mini`**。如果想要更稳定、均衡的结果，建议切换到 **`gpt-5.4`**。
 
 - `gpt-5.4` — 推荐的均衡选择。
 - `gpt-5.4-mini` — 当前应用默认值，适合快速草稿。
-- `gpt-5.5` — 在支持的环境中是质量最强的选择。但它可能消耗更多额度，也可能需要更新 Codex CLI，或依赖账号/后端路径是否开放对应的图像 capability。
+- `gpt-5.5` — 在支持的环境中是质量最高的选择。但它可能消耗更多额度，也可能需要更新 Codex CLI，或依赖账号/后端路径是否开放对应的图像 capability。
 
 Quality 支持 `low`, `medium`, `high`；moderation 支持 `auto`, `low`。
 
@@ -72,25 +79,46 @@ Quality 支持 `low`, `medium`, `high`；moderation 支持 `auto`, `low`。
 1. 写 prompt。
 2. 需要时添加参考图。
 3. 选择模型、quality、size、format、moderation。
-4. 生成后复制、下载，或继续从当前结果迭代。
+4. 生成一张图，或打开 multimode 从同一个 prompt 生成多个候选 slot。
+5. 生成后复制、下载、继续迭代，或进入 Canvas Mode 清理。
+
+![一个 prompt 正在生成四个 candidate slot，sidebar 中显示 active job history 的 multimode sequence 界面](../assets/screenshots/multimode-sequence.png)
 
 ### Node mode
 
-适合把想法分叉后对比。
+适合将创意分支发散并进行直观对比。
 
 ![显示连接节点、生成卡片和节点元数据的 Node mode 界面](../assets/screenshots/node-graph-branching.png)
 
-每个节点都有自己的 prompt 和结果。根节点可以附加本地参考图；子节点会使用父图作为来源。完成的任务会通过 request ID 重新匹配，因此刷新或 graph version conflict 后也能恢复结果。
+每个节点都有自己的 prompt 和结果。根节点可以附加本地参考图；子节点将使用父节点图片作为参考来源。完成的任务会通过 request ID 重新匹配，因此刷新或 graph version conflict 后也能恢复结果。
 
-### Settings 和 Style sheets
+### Canvas Mode
 
-Settings workspace 会把账号、模型、主题和语言设置从生成面板中分离出来。
+当生成结果已经接近目标，但还需要局部清理或背景处理时使用 Canvas Mode。
 
-![显示账号区域和生成模型设置的 Settings workspace](../assets/screenshots/settings-workspace.png)
+- 缩放后的图片中，viewport pan 与 selection tool 分离，避免在移动画面时误触或修改 annotation。
+- 支持 annotation、eraser、multiselect、group、undo/redo 和 sticky note。
+- 可点击指定 background cleanup seed，预览 mask，并保存为 canvas version。
+- 透明图会显示 checkerboard preview，export 可选择保留 alpha 或合成指定 matte color。
+- 保存的 canvas version 不会出现在 Gallery/HistoryStrip 中，但 Canvas Mode 可以复用它，也可以把它作为下一次 reference。
+
+![显示 zoom controls、annotation marks、sticky note 和 canvas toolbar 的 Canvas Mode 界面](../assets/screenshots/canvas-mode-cleanup.png)
+
+### Prompt library 和 Import
+
+Prompt library 可以从 local files、GitHub folders、curated sources 和 GPT-image hint packs 导入。导入后的 prompt 会写入本地 index，因此下次启动后仍可搜索和 ranking。
+
+![导入到 prompt library 前用于查看 GitHub folder、curated sources 和搜索候选 prompt 的 prompt import dialog](../assets/screenshots/prompt-import-dialog.png)
+
+### Experimental Card News Mode
 
-Style sheet 用来保存可复用的视觉方向。
+Card News 仍是开发专用的实验功能。默认公开运行环境中，除非明确以开发用途启用，否则它会保持隐藏；目前不应将其视为稳定的公开功能。
 
-![包含 medium、composition、mood、subject、palette、negative 字段的 style sheet editor](../assets/screenshots/style-sheet-editor.png)
+### Settings
+
+Settings workspace 会把账号、模型、主题和语言设置从生成面板中分离出来。
+
+![显示账号区域和生成模型设置的 Settings workspace](../assets/screenshots/settings-workspace.png)
 
 ## CLI 命令
 
@@ -98,7 +126,7 @@ Style sheet 用来保存可复用的视觉方向。
 
 | Command | Description |
 |---|---|
-| `ima2 serve` | 启动本地 Web server |
+| `ima2 serve [--dev]` | 启动本地 Web server；`--dev` 显示更详细的 server diagnostics |
 | `ima2 setup` | 重新配置认证 |
 | `ima2 status` | 查看 config 和 OAuth 状态 |
 | `ima2 doctor` | 诊断 Node、package、config、auth |
@@ -107,18 +135,23 @@ Style sheet 用来保存可复用的视觉方向。
 
 ### Client
 
-这些命令需要先运行 `ima2 serve`。
+这些命令需要先运行 `ima2 serve`。CLI 已覆盖所有服务端路由，下面只列出最常用的命令。完整列表见 [CLI 参考（英文）](CLI.md)（包含 generation、history、sessions、prompt library、annotations、Card News、observability、config）。
 
 | Command | Description |
 |---|---|
 | `ima2 gen <prompt>` | 从 CLI 生成图片 |
 | `ima2 edit <file> --prompt <text>` | 编辑已有图片 |
-| `ima2 ls` | 查看本地历史 |
-| `ima2 show <name>` | 打开生成文件 |
-| `ima2 ps` | 查看进行中的任务 |
+| `ima2 multimode <prompt>` | 多图 SSE 生成 |
+| `ima2 ls [--session <id>] [--favorites]` | 查看本地历史 |
+| `ima2 show <name> [--metadata]` | 打开生成文件 |
+| `ima2 prompt ls -q <搜索>` | 搜索 prompt library |
+| `ima2 inflight ls [--terminal]` | 查看进行中 / 最近完成任务（`ps` 别名）|
+| `ima2 config set <key> <value>` | 写入 `~/.ima2/config.json` |
 | `ima2 ping` | 检查 server 是否可用 |
 
-Server 端口会写入 `~/.ima2/server.json`。也可以用 `--server <url>` 或 `IMA2_SERVER=http://localhost:3333` 覆盖。
+Server 端口会写入 `~/.ima2/server.json`。如果 `3333` 已被占用，server 可能 fallback 到 `3334+`，请优先使用终端输出的 URL 或 `ima2 open`。也可以用 `--server <url>` 或 `IMA2_SERVER=http://localhost:3333` 覆盖。
+
+完整命令与标志见 [docs/CLI.md](CLI.md)。
 
 ## 配置
 
@@ -131,14 +164,24 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | 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 和 SQLite 位置 |
+| `IMA2_ADVERTISE_FILE` | `~/.ima2/server.json` | 运行时 server discovery 文件 |
 | `IMA2_GENERATED_DIR` | `~/.ima2/generated` | 生成图片目录 |
+| `IMA2_IMAGE_MODEL_DEFAULT` | `gpt-5.4-mini` | Server fallback 图像模型 |
 | `IMA2_NO_OAUTH_PROXY` | — | 设为 `1` 时关闭 OAuth proxy 自动启动 |
+| `IMA2_LOG_LEVEL` | `warn` | 普通 `serve` 默认为 `warn`，dev mode 默认为 `debug`；支持 `debug`, `info`, `warn`, `error`, `silent` |
 | `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `30000` | 调试用 recent job 保留时间 |
 | `OPENAI_API_KEY` | — | 辅助功能用 API key，不用于图像生成 |
 
+### Logging modes
+
+`ima2 serve` 默认保持终端输出安静：启动 URL、warning 和 error 会显示，但 request/node/OAuth structured logs 默认隐藏。
+
+如果需要 request ID、Node generation phases、OAuth stream diagnostics 或 inflight state transitions，请使用 `ima2 serve --dev`、`npm run dev`，或 `IMA2_LOG_LEVEL=debug ima2 serve`。
+
 ## API 文档
 
 接口列表已移到 [API Reference](API.md)。
@@ -156,8 +199,8 @@ environment variables > ~/.ima2/config.json > built-in defaults
 **在代理/VPN 网络下反复出现 `fetch failed`**
 请先确认本地 OAuth proxy 可以访问。如果你的网络需要代理，请在代理客户端里开启 TUN/TURN 类似的转发模式，然后重试 `npx openai-oauth --port 10531`。如果仍然失败，请在运行 `ima2 serve` 或 `openai-oauth` 的同一个终端里设置 `HTTP_PROXY` 和 `HTTPS_PROXY`。
 
-**生成图片时返回 `APIKEY_DISABLED`**
-当前 build 需要使用 OAuth 生成。API-key image generation 是有意关闭的。
+**生成图片时返回 `API_KEY_REQUIRED`**
+`provider: "api"` 请求没有可用 API key。请配置 API key，或切换到 OAuth provider。
 
 **大参考图上传失败**
 JPEG/PNG 会在上传前自动压缩。如果仍然失败，请转成更低分辨率的 JPEG/PNG。HEIC/HEIF 不支持浏览器路径。
@@ -180,10 +223,13 @@ git clone https://github.com/lidge-jun/ima2-gen.git
 cd ima2-gen
 npm install
 npm run dev
+npm run typecheck
 npm test
 npm run build
 ```
 
+`npm run dev` 会构建 UI，并用 `--watch` 启动 TypeScript server entry，同时显示详细 server diagnostics。`npm run typecheck`、`npm run build:server`、`npm run build:cli` 可验证 TypeScript migration 和 package emit path。
+
 ## License
 
 MIT