ima2-gen 1.1.13 → 1.1.16

package/config.ts

@@ -195,6 +195,11 @@ export const config = {
       fileCfg.oauth?.maskedEditEnabled,
       false,
     ),
+    forceImageToolChoice: pickBool(
+      env.IMA2_OAUTH_FORCE_IMAGE_TOOL_CHOICE,
+      fileCfg.oauth?.forceImageToolChoice,
+      true,
+    ),
     researchSuffix: pickStr(
       env.IMA2_RESEARCH_SUFFIX,
       fileCfg.oauth?.researchSuffix,
@@ -272,6 +277,22 @@ export const config = {
     defaultSize: pickStr(env.IMA2_API_IMAGE_SIZE, fileCfg.apiProvider?.defaultSize, "1024x1024"),
     allowWebSearch: pickBool(env.IMA2_API_ALLOW_WEB_SEARCH, fileCfg.apiProvider?.allowWebSearch, true),
   },
+  grokProvider: {
+    proxyPort: pickInt(env.IMA2_GROK_PROXY_PORT, fileCfg.grokProvider?.proxyPort, 18645),
+    proxyHost: pickStr(env.IMA2_GROK_PROXY_HOST, fileCfg.grokProvider?.proxyHost, "127.0.0.1"),
+    autoStart: !pickBool(env.IMA2_NO_GROK_PROXY, fileCfg.grokProvider?.disableAutoStart, false),
+    restartDelayMs: pickInt(env.IMA2_GROK_RESTART_DELAY_MS, fileCfg.grokProvider?.restartDelayMs, 2000),
+    plannerModel: pickStr(env.IMA2_GROK_PLANNER_MODEL, fileCfg.grokProvider?.plannerModel, "grok-4.3"),
+    plannerTimeoutMs: pickInt(env.IMA2_GROK_PLANNER_TIMEOUT_MS, fileCfg.grokProvider?.plannerTimeoutMs, 60_000),
+    defaultImageModel: pickStr(env.IMA2_GROK_IMAGE_MODEL_DEFAULT, fileCfg.grokProvider?.defaultImageModel, "grok-imagine-image"),
+    generationTimeoutMs: pickInt(env.IMA2_GROK_GENERATION_TIMEOUT_MS, fileCfg.grokProvider?.generationTimeoutMs, 120_000),
+    statusTimeoutMs: pickInt(env.IMA2_GROK_STATUS_TIMEOUT_MS, fileCfg.grokProvider?.statusTimeoutMs, 3000),
+    defaultVideoModel: pickStr(env.IMA2_GROK_VIDEO_MODEL_DEFAULT, fileCfg.grokProvider?.defaultVideoModel, "grok-imagine-video"),
+    videoStartTimeoutMs: pickInt(env.IMA2_GROK_VIDEO_START_TIMEOUT_MS, fileCfg.grokProvider?.videoStartTimeoutMs, 60_000),
+    videoPollIntervalMs: pickInt(env.IMA2_GROK_VIDEO_POLL_INTERVAL_MS, fileCfg.grokProvider?.videoPollIntervalMs, 5_000),
+    videoTimeoutMs: pickInt(env.IMA2_GROK_VIDEO_TIMEOUT_MS, fileCfg.grokProvider?.videoTimeoutMs, 900_000),
+    videoDownloadTimeoutMs: pickInt(env.IMA2_GROK_VIDEO_DOWNLOAD_TIMEOUT_MS, fileCfg.grokProvider?.videoDownloadTimeoutMs, 120_000),
+  },
   log: {
     level: pickStr(env.IMA2_LOG_LEVEL, fileCfg.log?.level, defaultLogLevelForEnv(env)),
     pretty: env.NODE_ENV !== "production",

package/docs/API.md

@@ -10,14 +10,21 @@ http://localhost:3333
 
 ## Provider Policy
 
-Image generation supports both OAuth and API-key providers.
+Image generation supports OAuth, API-key, and Grok providers.
 
 - `provider: "oauth"` uses the local Codex OAuth proxy.
 - `provider: "api"` uses the OpenAI Responses API with the hosted `image_generation` tool.
+- `provider: "grok"` uses the bundled progrok xAI proxy. Classic, Node, and Agent generation run mandatory xAI Web Search through `/v1/responses`, then run a `grok-4.3` planner call with a forced local `generate_image` function, then ima2 executes xAI `/v1/images/generations`. If reference images, a Node parent image, or an Agent current image are attached, the final step switches to xAI `/v1/images/edits` so image-to-image context is preserved.
 - API-key generation covers classic generate, edit, mask-guided edit, multimode, and node generation.
 - If `provider: "api"` is requested without an API key, routes fail before upstream with `401` and `API_KEY_REQUIRED`.
+- Grok generation maps `size` to xAI `aspect_ratio` and `resolution`; it does not send an OpenAI-style `size` field upstream. Grok edit uses xAI `/v1/images/edits`; Grok mask edit remains unsupported and returns `GROK_MASK_UNSUPPORTED`.
 - Mask edits are mask/selection guided edits, not pixel-perfect inpaint guarantees.
 
+Grok video generation (T2V/I2V) is not part of the `1.1.15` runtime API. The
+`docs/grok-video-i2v-plan.md` and `docs/grok-video-i2v-research.md` files are
+planning and research notes only; no `/api/video` route or Grok video endpoint
+wrapper is shipped in this release.
+
 ## Health And Status
 
 | Method | Path | Notes |
@@ -25,6 +32,7 @@ Image generation supports both OAuth and API-key providers.
 | `GET` | `/api/health` | Server health, version, paths, provider policy |
 | `GET` | `/api/providers` | Provider availability and runtime ports |
 | `GET` | `/api/oauth/status` | OAuth proxy status and visible models |
+| `GET` | `/api/grok/status` | Bundled progrok status and visible xAI image models |
 | `GET` | `/api/billing` | Billing/status probe, including API key source when configured |
 
 ## Storage
@@ -104,12 +112,60 @@ Supported moderation values: `auto`, `low`.
 
 Recommended model: `gpt-5.4`. Current app default: `gpt-5.4-mini`. `gpt-5.5` is the strongest quality option when supported, but callers should expect higher quota pressure and possible Codex CLI/backend capability requirements.
 
+When `provider` is `"grok"`, supported models are `grok-imagine-image` and
+`grok-imagine-image-quality`. The server uses `grok-4.3` as the search/planner
+model by default (`IMA2_GROK_PLANNER_MODEL`) and times the mandatory search and
+planner steps separately from the image call (`IMA2_GROK_PLANNER_TIMEOUT_MS`).
+For `n > 1`, search and planning run once and the planned prompt is reused for
+the image requests. Successful Grok classic generations report one mandatory
+web-search call in metadata.
+
+If `references` are present on a Grok classic request, ima2 still performs the
+mandatory search and `grok-4.3` planning phases. The planner receives the
+reference images as multimodal `image_url` inputs, and its forced
+`generate_image.prompt` argument is instructed to be English-only except for
+exact visible text requested by the user. The final image call then uses xAI
+`/v1/images/edits` with the same reference images instead of
+`/v1/images/generations`. This keeps image-to-image/reference context alive
+through the three-phase pipeline. xAI currently documents up to three source
+images for image editing, so Grok classic requests with more than three
+references return `GROK_REF_TOO_MANY`.
+
+Grok size mapping:
+
+| Requested size | xAI `aspect_ratio` | xAI `resolution` |
+|---|---|---|
+| `1024x1024` | `1:1` | `1k` |
+| `1536x1024` | `3:2` | `1k` |
+| `1024x1536` | `2:3` | `1k` |
+| `1360x1024` | `4:3` | `1k` |
+| `1024x1360` | `3:4` | `1k` |
+| `1824x1024` | `16:9` | `1k` |
+| `1024x1824` | `9:16` | `1k` |
+| `2048x2048` | `1:1` | `2k` |
+| `2048x1152` | `16:9` | `2k` |
+| `1152x2048` | `9:16` | `2k` |
+| `3840x2160` | `16:9` | `2k` |
+| `2160x3840` | `9:16` | `2k` |
+| `auto` | `auto` | omitted |
+
+Custom sizes are reduced to the closest xAI-supported aspect ratio and use
+`2k` when the requested longest edge or pixel budget is closer to a 2K image.
+
 ### `POST /api/edit`
 
 Image edit / image-to-image generation.
 
 The request includes a prompt and image payload. `provider: "api"` sends the prompt and image through the shared Responses image adapter. Optional masks are forwarded as mask guidance, not a pixel-perfect edit guarantee.
 
+With `provider: "grok"`, edit requests are sent to xAI `/v1/images/edits`
+through the bundled progrok proxy. Masked Grok edits are rejected before
+upstream with `GROK_MASK_UNSUPPORTED`.
+
+Grok multimode currently sends each image request directly to xAI Images API
+with the mapped `aspect_ratio`/`resolution`; the mandatory search + planner
+pipeline is limited to classic `/api/generate`.
+
 ### `POST /api/node/generate`
 
 Node-mode generation and child edits.
@@ -124,20 +180,24 @@ Body fields:
   "size": "1024x1024",
   "format": "png",
   "moderation": "low",
-  "model": "gpt-5.4",
+  "model": "grok-imagine-image",
   "references": [],
   "externalSrc": "optional-history-url",
   "sessionId": "session-id",
   "clientNodeId": "client-node-id",
   "requestId": "request-id",
-  "provider": "oauth"
+  "provider": "grok"
 }
 ```
 
 When `parentNodeId` is present, the server loads the stored parent node image and uses the edit path. Extra node references are currently supported only for root nodes.
 
+With `provider: "grok"`, Node Mode uses the same xAI search + `grok-4.3` planner + Images API pipeline as classic generation. A parent node image, `externalSrc`, or extra references are passed to the planner and then to xAI `/v1/images/edits`; otherwise the final call uses `/v1/images/generations`. Grok Node requests are capped at three total input images, counting the parent/current image plus references, and return `GROK_REF_TOO_MANY` before upstream when that limit is exceeded. `quality: "high"` promotes the final image model to `grok-imagine-image-quality`.
+
 The route can stream Server-Sent Events when the client sends `Accept: text/event-stream`. Possible events include `phase`, `partial`, `done`, and `error`.
 
+Grok Node SSE responses do not include Responses API `partial` image events because the xAI Images API call is synchronous JSON. They still emit `phase` and `done`/`error` events so the Node UI can use the same in-flight lifecycle.
+
 ### `GET /api/node/:nodeId`
 
 Fetch stored node metadata and asset URL.
@@ -156,6 +216,8 @@ Server-side validation may return these reference codes:
 | `REF_EMPTY` | A reference item was empty |
 | `REF_TOO_LARGE` | A reference exceeded the configured base64 size |
 | `REF_NOT_BASE64` | A reference was not valid base64 |
+| `GROK_REF_TOO_MANY` | Grok classic generation received more than three reference images |
+| `GROK_MASK_UNSUPPORTED` | Grok edit was requested with a mask; xAI mask edit is not wired in this release |
 
 ## History
 
@@ -223,16 +285,20 @@ Style-sheet extraction can require an API key/openai client. Image generation al
 | `GRAPH_VERSION_CONFLICT` | Stale graph version |
 | `GRAPH_TOO_LARGE` | Graph exceeds node/edge limits |
 | `NODE_NOT_FOUND` | Node metadata was not found |
+| `INVALID_GROK_IMAGE_MODEL` | A Grok request used a model outside `grok-imagine-image` or `grok-imagine-image-quality` |
+| `GROK_RATE_LIMITED` | xAI returned a rate-limit response through progrok |
+| `GROK_AUTH_FAILED` | progrok could not authenticate the xAI request |
+| `GROK_SEARCH_TIMEOUT` / `GROK_PLANNER_TIMEOUT` / `GROK_IMAGE_TIMEOUT` | The Grok search, planner, or image API step exceeded its timeout budget |
 
 ## Endpoint → CLI Mapping
 
-As of 0.09.x, every server route under `/api/*` has a CLI wrapper. Use this table to find the command that calls a given endpoint. (See README.md "Client" section for full flag lists.)
+Most server routes under `/api/*` have a CLI wrapper. The exception is **Agent Mode** (`/api/agent/*`), which is server + web-UI-only and has no `ima2` subcommand. The prompt builder HTTP route (`POST /api/prompt-builder/chat`) is wrapped by `ima2 prompt build`. Use this table to find the command that calls a given endpoint. (See README.md "Client" section for full flag lists.)
 
 | Endpoint | CLI |
 |---|---|
 | `POST /api/generate` | `ima2 gen` |
 | `POST /api/edit` | `ima2 edit` |
-| `POST /api/generate/multi` (SSE) | `ima2 multimode` |
+| `POST /api/generate/multimode` (SSE) | `ima2 multimode` |
 | `POST /api/node/generate` (SSE) / `GET /api/node/:id` | `ima2 node generate` / `ima2 node show` |
 | `GET /api/history` | `ima2 ls` |
 | `DELETE /api/history/:name` / `…/permanent` | `ima2 history rm [--permanent]` |
@@ -246,14 +312,17 @@ As of 0.09.x, every server route under `/api/*` has a CLI wrapper. Use this tabl
 | `GET/PUT/DELETE /api/annotations/:name` | `ima2 annotate get/set/rm` |
 | `POST /api/canvas-versions` / `PUT /api/canvas-versions/:name` | `ima2 canvas-versions save/update` |
 | `GET/POST/PUT/DELETE /api/prompts[/…]` | `ima2 prompt …` |
-| `GET/POST/PUT/DELETE /api/prompt-folders[/…]` | `ima2 prompt folder …` |
-| `…/api/prompt-import/…` | `ima2 prompt import sources/refresh/curated/discovery/folder` |
+| `GET/POST/PATCH/DELETE /api/prompts/folders[/…]` | `ima2 prompt folder …` |
+| `…/api/prompts/import/…` | `ima2 prompt import sources/refresh/curated/discovery/folder` |
 | `…/api/cardnews/…` (gated on `features.cardNews`) | `ima2 cardnews …` |
 | `POST /api/comfy/export-image` | `ima2 comfy export` |
 | `GET /api/inflight` / `DELETE /api/inflight/:id` | `ima2 inflight ls` (alias `ps`) / `ima2 inflight rm` (alias `cancel`) |
 | `GET /api/storage/status` / `POST /api/storage/open-generated-dir` | `ima2 storage status` / `ima2 storage open` |
-| `GET /api/billing` / `GET /api/providers` / `GET /api/oauth/status` | `ima2 billing` / `ima2 providers` / `ima2 oauth status` |
+| `GET /api/billing` / `GET /api/providers` / `GET /api/oauth/status` / `GET /api/grok/status` | `ima2 billing` / `ima2 providers` / `ima2 oauth status` / `ima2 grok status` |
 | `GET /api/health` | `ima2 ping` |
+| `GET /api/capabilities` | `ima2 capabilities` |
+| `GET/POST/PATCH/DELETE /api/agent/*` (sessions, turns, queue) | — (Agent Mode; web UI only, no CLI) |
+| `POST /api/prompt-builder/chat` | `ima2 prompt build` |
 
 Notes:
 - `ima2 history favorite` and `ima2 annotate …` send `X-Ima2-Browser-Id: cli-<sha1prefix>` derived from the config dir, so CLI activity does not collide with browser sessions.

package/docs/CLI.md

@@ -1,6 +1,6 @@
 # CLI Reference
 
-Every server route under `/api/*` has a CLI wrapper. The CLI is a thin shell over the local server, so most commands require a running `ima2 serve` (the few exceptions — `serve`, `setup`, `doctor`, `status`, `open`, `reset`, `config`, `skill`, `capabilities`, and local `defaults` inspection — work without a live server).
+Most server routes under `/api/*` have a CLI wrapper; Agent Mode (`/api/agent/*`) is web-UI-only and has no `ima2` subcommand. The prompt builder HTTP route (`POST /api/prompt-builder/chat`) is available through `ima2 prompt build`. The CLI is a thin shell over the local server, so most commands require a running `ima2 serve` (the few exceptions — `serve`, `setup`, `doctor`, `status`, `open`, `reset`, `config`, `grok`, `skill`, `capabilities`, and local `defaults` inspection — work without a live server).
 
 For a quick start, see the [main README](../README.md). For endpoint mapping, see [API.md](API.md).
 
@@ -12,7 +12,9 @@ For a quick start, see the [main README](../README.md). For endpoint mapping, se
 | `ima2 setup` / `ima2 login` | Reconfigure saved auth (interactive) |
 | `ima2 status` | Show config and OAuth status |
 | `ima2 doctor` | Diagnose Node, package, config, and auth |
+| `ima2 doctor image-probe [--json]` | Run live sanitized Responses image probes for `EMPTY_RESPONSE` support |
 | `ima2 open` | Open the web UI in a browser |
+| `ima2 grok login/status/models/proxy` | Manage the bundled progrok runtime used by the Grok provider |
 | `ima2 reset` | Remove saved config |
 
 ## Common flags
@@ -50,16 +52,36 @@ Agents should start from the packaged skill and capability commands instead of g
 | `ima2 node generate` | Node-mode generate (SSE; supports `--no-stream`) |
 | `ima2 node show <nodeId>` | Read node metadata |
 
-Generation flags include `--provider <auto|oauth|api>`, `--reasoning-effort {none\|low\|medium\|high\|xhigh}`, `--web-search` / `--no-web-search`, `--model`, `--mode`, `--moderation`, `--ref <file>` (repeatable, up to 5 where supported), `-q low|medium|high`, `-n <count>`, `-o <file>`.
+Generation flags include `--provider <auto|oauth|api|grok>`, `--reasoning-effort {none\|low\|medium\|high\|xhigh}`, `--web-search` / `--no-web-search`, `--model`, `--mode`, `--moderation`, `--ref <file>` (repeatable, up to 5 where supported), `-q low|medium|high`, `-n <count>`, `-o <file>`.
 
 Provider override semantics:
 
 - `api` forces the API-key Responses path and requires a configured API key.
 - `oauth` forces the local OAuth proxy path.
+- `grok` uses the bundled progrok xAI proxy (`127.0.0.1:18645`). Classic generation first runs mandatory xAI Web Search through Responses API, then asks `grok-4.3` to call ima2's local `generate_image` tool, then ima2 executes xAI `/v1/images/generations`. If `--ref` images are attached, the final step uses xAI `/v1/images/edits` instead so image-to-image/reference context is preserved. Models: `grok-imagine-image`, `grok-imagine-image-quality`. Size is mapped to xAI `aspect_ratio` and `resolution`; the UI web-search toggle is OpenAI-provider-only because Grok search is always on in this path.
 - `auto` preserves route default behavior and currently resolves to OAuth unless server routing changes.
 
+`ima2 serve` starts the bundled Grok proxy automatically. No separate `progrok`
+install is required. Use `ima2 grok login` once to authorize xAI OAuth, or
+`ima2 grok login --device-code` on a remote shell. Set `IMA2_NO_GROK_PROXY=1`
+only if you want to manage the proxy yourself.
+
+Grok size mapping follows xAI's image API, not OpenAI's `size` field. ima2
+keeps the requested size in local metadata, but sends `aspect_ratio` such as
+`1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, or `2:3`, plus `resolution:
+"1k"` or `"2k"` where applicable. The 3840 presets map to `resolution: "2k"`
+because xAI currently exposes `1k` and `2k` resolution controls.
+
+For Grok classic generation with `--ref`, ima2 sends up to three references into
+the `grok-4.3` planner as image inputs, asks the planner for an English final
+image prompt, then sends the same references to xAI image editing. More than
+three Grok references are rejected with `GROK_REF_TOO_MANY`, matching xAI's
+documented multi-image editing limit.
+
 ```bash
 ima2 gen "a poster of a samurai cat" --model gpt-5.4 --provider api --reasoning-effort high
+ima2 grok login
+ima2 gen "a cinematic neon city" --provider grok --model grok-imagine-image-quality
 ima2 edit input.png --prompt "make it rainy" --provider oauth --web-search
 ima2 multimode "two cats playing" --max-images 2 --ref cat.png --mode direct
 ima2 node generate --node n_abc --prompt "add neon lights" --no-stream
@@ -81,7 +103,42 @@ mockup`.
 For dense or critical text, keep the text large and explicit. Exact placement,
 small text, and pixel-perfect typography can still need iteration or post-editing.
 
-Multimode-specific flags include `--max-images <1..8>`, `--ref <file>` (repeatable, max 5), `--mode <auto|direct>`, `--provider <auto|oauth|api>`, and `--show-partial`. `ima2 edit --mask` remains intentionally deferred to #31 because current mask plumbing is guided edit rather than guaranteed true masked/inpaint semantics.
+Multimode-specific flags include `--max-images <1..8>`, `--ref <file>` (repeatable, max 5), `--mode <auto|direct>`, `--provider <auto|oauth|api|grok>`, and `--show-partial`. `ima2 edit --mask` remains intentionally deferred to #31 because current mask plumbing is guided edit rather than guaranteed true masked/inpaint semantics.
+
+## Diagnostics
+
+`ima2 doctor image-probe` runs live Responses probes that help classify image
+generation failures such as `EMPTY_RESPONSE`. It is intended for support
+bundles, especially when OAuth is green but a simple prompt produces no image.
+
+```bash
+ima2 doctor image-probe --json > ima2-image-probe.json
+```
+
+Use `--matrix` when a maintainer asks for current-payload comparison probes:
+
+```bash
+ima2 doctor image-probe --matrix --json > ima2-image-probe.json
+```
+
+The JSON output is sanitized for issue attachments. It includes diagnostic
+codes, event counts, tool-call summaries, byte counts, provider/model labels,
+and probe statuses. It does not include prompt text, auth tokens, URLs with
+credentials, raw upstream responses, or base64 image data.
+
+For OAuth no-image reports, a useful support bundle is:
+
+```bash
+ima2 doctor
+ima2 doctor image-probe --json > ima2-image-probe.json
+ima2 gen "고양이" --no-web-search --json > ima2-cat-no-search.json
+ima2 gen "고양이" --json > ima2-cat-current.json
+```
+
+Do not share ChatGPT cookies, OAuth token files, API keys, prompt history, raw
+upstream responses, or generated base64. Share `ima2-gen` version, OS version,
+and whether VPN, corporate proxy, antivirus TLS inspection, a custom CA, or a
+Windows DNS/fragmentation bypass tool such as SecretDNS is in use.
 
 ## History and metadata
 
@@ -133,6 +190,8 @@ Multimode-specific flags include `--max-images <1..8>`, `--ref <file>` (repeatab
 | `ima2 prompt import folder <localpath>` | Import a local folder of prompts |
 | `ima2 prompt import json <file\|@file\|-> [--folder <id>]` | Import a JSON export body through `/api/prompts/import` |
 | `ima2 prompt import preview <file\|@file\|-> [--filename <name>]` | Preview local markdown/text candidates without committing |
+| `ima2 prompt build --message <text> [--ref <file>] [--model <id>] [--json]` | Build a structured image prompt through `/api/prompt-builder/chat` |
+| `ima2 prompt build --messages <file\|@file\|-> [--json]` | Build from a message transcript file or stdin |
 
 ## Card News (gated)
 
@@ -163,6 +222,7 @@ Card News requires the server to be started with `IMA2_CARD_NEWS=1` (or `feature
 | `ima2 billing` | API usage / quota |
 | `ima2 providers` | Configured providers |
 | `ima2 oauth status` | OAuth proxy state |
+| `ima2 grok status` | Bundled progrok / xAI image-model probe state |
 | `ima2 ping` | Health-check the running server |
 
 ## Config
@@ -195,6 +255,8 @@ Allowed keys (whitelist):
 ```
 imageModels.default          imageModels.reasoningEffort
 apiProvider.defaultImageModel apiProvider.defaultReasoningEffort
+grokProvider.plannerModel     grokProvider.plannerTimeoutMs
+grokProvider.defaultImageModel
 log.level                    features.cardNews
 cardNewsPlanner.{enabled,model,timeoutMs,deterministicFallback}
 comfy.{defaultUrl,uploadTimeoutMs,maxUploadBytes}

package/docs/FAQ.ko.md

@@ -1,6 +1,6 @@
 # ima2-gen 자주 묻는 질문
 
-마지막 확인: 2026-04-25
+마지막 확인: 2026-05-26
 
 이 문서는 설치, 업데이트, OAuth, 갤러리, 레퍼런스 이미지 관련 질문을 모아둔 FAQ입니다. README는 짧게 유지하고, 자세한 설명은 이곳에 둡니다.
 
@@ -16,6 +16,8 @@ English version: [FAQ.md](FAQ.md)
 | 업데이트 후 예전 이미지가 안 보임 | `ima2 doctor`를 실행한 뒤 [예전 이미지 복구 안내](RECOVER_OLD_IMAGES.md)를 확인합니다. |
 | `gpt-5.5`만 실패함 | Codex CLI를 업데이트하고, 안정 대안으로 `gpt-5.4`를 사용합니다. |
 | 레퍼런스 업로드 실패 | JPEG/PNG로 변환하고 해상도를 낮춰 보세요. 레퍼런스는 최대 5장입니다. |
+| Prompt Studio 기능이 헷갈림 | [Prompt Studio 사용 설명서](PROMPT_STUDIO.ko.md)에서 멀티모드, Direct, 추론 강도, 갤러리 동작을 확인하세요. |
+| 이미지 생성이 `EMPTY_RESPONSE` 또는 no image data로 끝남 | `ima2 doctor image-probe --json`을 실행한 뒤 아래의 안전한 지원 번들을 모아 주세요. |
 | Windows에서 `10531` 포트 관련 OAuth/proxy 오류가 남 | `ima2 doctor`를 실행하고, 필요하면 `IMA2_OAUTH_PROXY_PORT=11531 ima2 serve`로 시작하세요. |
 | 프록시/VPN 환경에서 `fetch failed`가 반복됨 | 프록시 클라이언트의 TUN/TURN류 모드를 켜거나, 같은 터미널에 `HTTP_PROXY` / `HTTPS_PROXY`를 설정하세요. |
 
@@ -118,6 +120,36 @@ ima2 serve
 
 커뮤니티에서 말하는 숫자를 보장으로 받아들이면 안 됩니다. OAuth 생성은 계정, 백엔드 capability, 트래픽, 정책 변경의 영향을 받을 수 있습니다. `ima2-gen` 문서에서는 고정된 Plus/Pro 생성 횟수를 약속하지 않습니다.
 
+## Prompt Studio와 멀티모드
+
+### Prompt Studio 상세 설명서가 있나요?
+
+네. [Prompt Studio 사용 설명서](PROMPT_STUDIO.ko.md)를 확인하세요. 작성창,
+멀티모드 슬롯, 1:1 Direct, 모델/추론 빠른 설정, 최근 생성, 갤러리 즐겨찾기,
+어떤 액션이 프롬프트를 의도적으로 가져오는지 정리했습니다.
+
+### 멀티모드 이미지가 서로 관계없게 나오는 이유는 뭔가요?
+
+멀티모드는 같은 프롬프트로 여러 개의 독립 이미지 요청을 시작합니다. 각 슬롯은
+후보 이미지이지, 한 캔버스 안의 패널이나 보장된 연속 장면이 아닙니다. 서로
+관련 있는 대안을 원하면 공통 대상을 먼저 쓰고 바뀌어도 되는 요소를 따로
+적어 주세요. 한 장 안의 2패널, 콜라주, contact sheet가 필요하면 일반 한 장
+생성에서 그렇게 요청하는 편이 맞습니다.
+
+### 갤러리 이미지를 선택하면 현재 프롬프트가 바뀌어야 하나요?
+
+단순 이미지 선택은 보기 전용입니다. 선택 이미지를 보여줄 뿐 작성창을 바꾸지
+않아야 합니다. 프롬프트 라이브러리 삽입, "이 이미지에서 이어가기", 명시적인
+재사용 액션만 프롬프트를 의도적으로 바꾸는 동작입니다.
+
+### Issue #75에서 무엇이 정리됐나요?
+
+Prompt Studio의 navigation/state coupling 회귀를 정리했습니다. 키보드 이동은
+보이는 최근 생성 범위를 따르고, 갤러리 진입 버튼은 계속 접근 가능하며, 긴
+프롬프트가 이미지 뷰어를 과하게 줄이지 않고, Direct와 멀티모드 상태가 동시에
+보이며, 갤러리 즐겨찾기와 탭 전환은 보던 위치를 유지하고, 단순 이미지 선택은
+작성창을 자동으로 채우지 않습니다.
+
 ## 갤러리와 생성 파일
 
 ### 생성 이미지는 어디에 저장되나요?
@@ -214,6 +246,7 @@ VITE_IMA2_API_TARGET=http://localhost:3334 npm run ui:dev
 - 로컬 OAuth 프록시가 아직 준비되지 않았습니다.
 - 서버가 재시작되었습니다.
 - VPN, 프록시, 방화벽이 요청을 막았습니다.
+- Windows에서 자동 실행되는 DNS/파편화 우회 프로그램(예: SecretDNS)이 OAuth 또는 스트리밍 이미지 응답을 깨뜨렸습니다.
 - Codex/ChatGPT OAuth 사용 중 네트워크가 끊겼습니다.
 
 먼저 확인하세요.
@@ -225,6 +258,53 @@ ima2 ping
 
 필요하면 `ima2 serve`를 다시 시작합니다.
 
+### OAuth 이미지 생성이 이미지 없이 끝나면 무엇을 공유해야 하나요?
+
+먼저 moderation으로 단정하지 말고 image probe를 실행하세요. `EMPTY_RESPONSE`는
+Responses 경로에서 `ima2-gen`이 사용할 수 있는 이미지 데이터가 나오지 않았다는
+뜻입니다. 원인은 OAuth capability, stream parsing, web-search/tool-choice
+상호작용, 로컬 프록시/네트워크 transport, 지원되지 않는 옵션, 실제 refusal 등으로
+나뉠 수 있습니다.
+
+먼저 실행하세요.
+
+```bash
+ima2 doctor
+ima2 doctor image-probe --json > ima2-image-probe.json
+```
+
+`ima2 serve`가 실행 중이면 검색을 끈 생성과 일반 생성 결과도 하나씩 저장하세요.
+
+```bash
+ima2 gen "고양이" --no-web-search --json > ima2-cat-no-search.json
+ima2 gen "고양이" --json > ima2-cat-current.json
+```
+
+probe JSON은 공개 이슈에 첨부할 수 있도록 설계되어 있습니다. 진단 코드,
+event count, tool-call 요약, byte count는 담지만 prompt text, auth token,
+credential URL, base64 image data는 담지 않습니다.
+
+이슈를 열 때 포함해 주세요.
+
+- `ima2 doctor` 출력
+- `ima2-image-probe.json`
+- 저장했다면 `ima2-cat-no-search.json`, `ima2-cat-current.json`
+- `ima2-gen` 버전과 Windows 버전
+- VPN, 회사 프록시, 백신 TLS 검사, custom CA 사용 여부
+- Windows에서 SecretDNS 같은 DNS/파편화 우회 프로그램이 자동 실행 중인지 여부
+- API 키가 이미 설정되어 있다면 같은 PC에서 `provider: "api"`가 동작하는지
+
+ChatGPT 쿠키, OAuth token 파일, API key, raw upstream response, prompt history,
+generated base64는 공유하지 마세요.
+
+결과는 이렇게 분류합니다.
+
+- text probe도 실패: OAuth 재로그인, 프록시, 모델 접근성을 먼저 봅니다.
+- text는 되지만 minimal non-stream image가 실패: 계정, OAuth backend, model, image-tool capability 가능성이 큽니다.
+- non-stream image는 되지만 stream image가 실패: stream parsing 또는 transport 가능성이 큽니다.
+- 검색 끈 생성은 되지만 일반 생성이 실패: web-search/tool-choice 상호작용 가능성이 큽니다.
+- bytes는 읽었지만 event가 없음: SSE delimiter 또는 `data:` parsing 가능성이 큽니다.
+
 ### 프록시나 VPN 뒤에서 `fetch failed`가 계속 나면 어떻게 하나요?
 
 대부분 로컬 OAuth 프록시가 현재 네트워크 경로로 upstream 서비스에 닿지 못하는 상황입니다. `openai-oauth`는 보통 `10531` 포트의 localhost 프록시로 실행됩니다.
@@ -235,7 +315,7 @@ ima2 ping
 npx openai-oauth --port 10531
 ```
 
-프록시가 필요한 네트워크라면 터미널 프로세스도 프록시를 타도록 프록시 클라이언트의 TUN/TURN류 모드를 켜세요. 그래도 안 되면 `openai-oauth` 또는 `ima2 serve`를 실행하는 같은 터미널에 프록시 환경 변수를 설정합니다.
+프록시가 필요한 네트워크라면 터미널 프로세스도 프록시를 타도록 프록시 클라이언트의 TUN/TURN류 모드를 켜세요. Windows에서는 SecretDNS처럼 부팅 때 자동 실행되는 DNS/파편화 우회 프로그램도 잠시 끄고 재시도해 보세요. 그래도 안 되면 `openai-oauth` 또는 `ima2 serve`를 실행하는 같은 터미널에 프록시 환경 변수를 설정합니다.
 
 ```bash
 export HTTP_PROXY=http://127.0.0.1:7890

package/docs/FAQ.md

@@ -1,6 +1,6 @@
 # ima2-gen FAQ
 
-Last reviewed: 2026-04-25
+Last reviewed: 2026-05-26
 
 This FAQ collects the questions that tend to come up after installing or updating `ima2-gen`. The README stays short; this page is the place for practical details and recovery steps.
 
@@ -16,6 +16,8 @@ For Korean, see [FAQ.ko.md](FAQ.ko.md).
 | 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. |
+| Prompt Studio controls are unclear | Read the [Prompt Studio manual](PROMPT_STUDIO.md) for multimode, Direct, reasoning, and gallery behavior. |
+| Image generation returns `EMPTY_RESPONSE` or no image data | Run `ima2 doctor image-probe --json`, then collect the safe support bundle below. |
 | Windows reports OAuth/proxy failures around port `10531` | Run `ima2 doctor`; if needed start with `IMA2_OAUTH_PROXY_PORT=11531 ima2 serve`. |
 | `fetch failed` repeats on a proxy/VPN network | Enable proxy TUN/TURN-style mode, or set `HTTP_PROXY` / `HTTPS_PROXY` in the same terminal. |
 
@@ -124,6 +126,37 @@ Start with `gpt-5.4` for the safest balanced workflow.
 
 Do not treat any community number as a guarantee. OAuth generation can be limited by account, backend capability, traffic, and policy changes. `ima2-gen` does not publish a fixed Plus/Pro image count because that number is not stable enough to document as a promise.
 
+## Prompt Studio and multimode
+
+### Is there a detailed Prompt Studio manual?
+
+Yes. See the [Prompt Studio manual](PROMPT_STUDIO.md). It explains the composer,
+multimode slots, 1:1 Direct, model/reasoning quick settings, recent history,
+gallery favorites, and which actions intentionally import prompt text.
+
+### Why did multimode images look unrelated?
+
+Multimode starts several separate image requests from the same prompt. The slots
+are candidate outputs, not panels inside one shared canvas and not a guaranteed
+story sequence. To get related alternatives, write the common subject first and
+then name the allowed variations. To get one multi-panel image, use a normal
+single-image request and ask for a two-panel, collage, or contact-sheet layout.
+
+### Should selecting a gallery image change my current prompt?
+
+Passive image selection is view-only. It should focus the selected image without
+rewriting the composer. Prompt Library insert, "continue from this image", and
+other explicit reuse actions are the actions that intentionally change prompt
+text.
+
+### What changed for issue #75?
+
+The Prompt Studio closeout fixed navigation and state-coupling regressions:
+keyboard movement now follows the visible recent history domain, the gallery
+entry remains reachable, long prompts no longer starve the image viewer,
+Direct and Multimode states are visible together, gallery favorites preserve the
+browsing viewport, and passive image selection does not refill the composer.
+
 ## Gallery and generated files
 
 ### Where are generated images stored?
@@ -222,6 +255,8 @@ Usually one of these:
 - the local OAuth proxy is not ready,
 - the server was restarted,
 - a VPN/proxy/firewall blocked the request,
+- an auto-start Windows network interception tool, including a DNS/fragmentation
+  bypass tool such as SecretDNS, broke OAuth or streaming image transport,
 - the network dropped while Codex/ChatGPT OAuth was being used.
 
 Try:
@@ -233,6 +268,54 @@ ima2 ping
 
 Then restart `ima2 serve` if needed.
 
+### What should I share when OAuth image generation returns no image?
+
+Use the image probe before assuming moderation. `EMPTY_RESPONSE` means the
+Responses path did not produce image data that `ima2-gen` could use; it can be
+caused by OAuth capability, stream parsing, web-search/tool-choice behavior,
+local proxy/network transport, unsupported options, or a real refusal.
+
+Run this first:
+
+```bash
+ima2 doctor
+ima2 doctor image-probe --json > ima2-image-probe.json
+```
+
+If `ima2 serve` is running, also capture one search-off and one normal cat
+generation result:
+
+```bash
+ima2 gen "고양이" --no-web-search --json > ima2-cat-no-search.json
+ima2 gen "고양이" --json > ima2-cat-current.json
+```
+
+The probe JSON is designed to be safe to attach to a public issue. It reports
+diagnostic codes, event counts, tool-call summaries, and byte counts, but not
+prompt text, auth tokens, credential URLs, or base64 image data.
+
+When opening an issue, include:
+
+- `ima2 doctor` output.
+- `ima2-image-probe.json`.
+- `ima2-cat-no-search.json` and `ima2-cat-current.json`, if you captured them.
+- `ima2-gen` version and Windows version.
+- Whether you use VPN, corporate proxy, antivirus TLS inspection, or a custom CA.
+- Whether a Windows DNS/fragmentation bypass tool such as SecretDNS is running
+  automatically.
+- Whether `provider: "api"` works on the same machine, if you already have an API key configured.
+
+Do not share ChatGPT cookies, OAuth token files, API keys, raw upstream
+responses, prompt history, or generated base64.
+
+How to read the result:
+
+- Text probe fails: refresh OAuth and inspect proxy/model availability first.
+- Text works but minimal non-stream image fails: likely account, OAuth backend, model, or image-tool capability.
+- Non-stream image works but stream image fails: likely stream parsing or transport.
+- Search-off generation works but normal generation fails: likely web-search/tool-choice interaction.
+- Bytes were read but no events were parsed: likely SSE delimiter or `data:` parsing.
+
 ### What if `fetch failed` keeps happening behind a proxy or VPN?
 
 This usually means the local OAuth proxy cannot reach the upstream service through your network path. `openai-oauth` runs as a local localhost proxy, commonly on port `10531`.
@@ -243,7 +326,7 @@ Try:
 npx openai-oauth --port 10531
 ```
 
-If your network requires a proxy, enable your proxy client's TUN/TURN-style mode so terminal processes can use it. If that is not enough, set the proxy variables in the same terminal that runs `openai-oauth` or `ima2 serve`:
+If your network requires a proxy, enable your proxy client's TUN/TURN-style mode so terminal processes can use it. On Windows, also temporarily disable auto-start DNS or fragmentation bypass tools such as SecretDNS and retry. If that is not enough, set the proxy variables in the same terminal that runs `openai-oauth` or `ima2 serve`:
 
 ```bash
 export HTTP_PROXY=http://127.0.0.1:7890