ima2-gen 1.1.13 → 1.1.14

package/bin/ima2.ts

@@ -3,13 +3,11 @@ import { createInterface } from "readline/promises";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
-import { createRequire } from "module";
 import { spawn, execSync } from "child_process";
 import { confirmDestructiveAction } from "./lib/destructive-confirm.js";
-import { buildHardeningDoctorLines } from "./lib/doctor-checks.js";
+import { doctor } from "./commands/doctor.js";
 import { openUrl, resolveBin } from "./lib/platform.js";
 import { maybePromptGithubStar } from "./lib/star-prompt.js";
-import { buildStorageDoctorLines } from "./lib/storage-doctor.js";
 import { ensureFreshUiDist } from "./lib/ui-build.js";
 import { detectCodexAuth } from "../lib/codexDetect.js";
 import { config as runtimeConfig } from "../config.js";
@@ -17,7 +15,6 @@ import { config as runtimeConfig } from "../config.js";
 import { errInfo } from "../lib/errInfo.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, "..");
-const requireFromRoot = createRequire(join(ROOT, "package.json"));
 // Config lives under runtimeConfig.storage.configDir (honors IMA2_CONFIG_DIR).
 // Legacy installs that stored config at <packageRoot>/.ima2/config.json will be
 // migrated on first write.
@@ -62,18 +59,6 @@ function advertisedServerUrl() {
   return adv?.backend?.url || adv?.url || (adv?.port ? `http://localhost:${adv.port}` : null);
 }
 
-function missingRuntimeDeps() {
-  const deps = ["express", "better-sqlite3", "openai", "openai-oauth"];
-  return deps.filter((dep) => {
-    try {
-      requireFromRoot.resolve(dep);
-      return false;
-    } catch {
-      return true;
-    }
-  });
-}
-
 async function setup() {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
 
@@ -221,97 +206,6 @@ async function showStatus() {
   console.log("");
 }
 
-async function doctor() {
-  console.log(`\n  ${pkg.name} v${pkg.version} — Doctor\n`);
-
-  let ok = 0;
-  let fail = 0;
-
-  // Node version
-  const nodeVersion = process.version;
-  const nodeMajor = parseInt(nodeVersion.slice(1).split(".")[0]);
-  if (nodeMajor >= 20) {
-    console.log(`  ✓ Node.js ${nodeVersion} (>= 20)`);
-    ok++;
-  } else {
-    console.log(`  ✗ Node.js ${nodeVersion} (requires >= 20)`);
-    fail++;
-  }
-
-  // package.json exists
-  if (existsSync(join(ROOT, "package.json"))) {
-    console.log("  ✓ package.json found");
-    ok++;
-  } else {
-    console.log("  ✗ package.json missing");
-    fail++;
-  }
-
-  // Runtime dependencies may be hoisted by npm, pnpm, or Yarn. Resolve the
-  // packages instead of requiring a package-local node_modules folder.
-  const missingDeps = missingRuntimeDeps();
-  if (missingDeps.length === 0) {
-    console.log("  ✓ runtime dependencies resolvable");
-    ok++;
-  } else {
-    console.log(`  ✗ missing runtime dependencies: ${missingDeps.join(", ")}`);
-    fail++;
-  }
-
-  // .env
-  if (existsSync(join(ROOT, ".env"))) {
-    console.log("  ✓ .env file exists");
-    ok++;
-  } else {
-    console.log("  ⚠ .env file not found (optional — copy from .env.example)");
-  }
-
-  // Config
-  const config = loadConfig();
-  if (config.provider) {
-    console.log(`  ✓ Configured: ${config.provider}`);
-    ok++;
-  } else {
-    console.log("  ⚠ Not configured — run 'ima2 setup'");
-  }
-
-  // Port availability (simple check)
-  const adv = loadAdvertisement();
-  console.log(`  ℹ Preferred backend port: ${runtimeConfig.server.port}`);
-  if (adv?.backend || adv?.port) {
-    console.log(`  ℹ Backend actual URL: ${adv?.backend?.url || adv?.url || `http://localhost:${adv.port}`}`);
-    if (adv?.oauth) {
-      console.log(`  ℹ OAuth actual URL: ${adv.oauth.url} (${adv.oauth.status || "unknown"})`);
-    }
-  }
-
-  const hardeningLines = await buildHardeningDoctorLines({
-    root: ROOT,
-    configFile: CONFIG_FILE,
-    fileConfig: config,
-  });
-  for (const line of hardeningLines) {
-    const prefix =
-      line.kind === "pass" ? "✓"
-      : line.kind === "fail" ? "✗"
-      : line.kind === "warn" ? "⚠"
-      : "ℹ";
-    console.log(`  ${prefix} ${line.text}`);
-    if (line.kind === "pass") ok++;
-    if (line.kind === "fail") fail++;
-  }
-
-  const storageLines = await buildStorageDoctorLines({
-    rootDir: ROOT,
-    config: runtimeConfig,
-  });
-  console.log("");
-  for (const line of storageLines) console.log(line);
-
-  console.log(`\n  ${ok} passed, ${fail} failed\n`);
-  process.exit(fail > 0 ? 1 : 0);
-}
-
 function openBrowser() {
   const url = advertisedServerUrl() || `http://localhost:${runtimeConfig.server.port}`;
   const res = openUrl(url);
@@ -400,7 +294,7 @@ if (args.includes("-v") || args.includes("--version")) {
 }
 
 if ((!command || args.includes("-h") || args.includes("--help"))
-    && !["gen", "edit", "ls", "show", "ps", "cancel", "session", "history", "prompt", "multimode", "node", "annotate", "canvas-versions", "metadata", "comfy", "cardnews", "inflight", "storage", "billing", "providers", "oauth", "config", "defaults", "capabilities", "skill", "ping"].includes(command)) {
+    && !["doctor", "gen", "edit", "ls", "show", "ps", "cancel", "session", "history", "prompt", "multimode", "node", "annotate", "canvas-versions", "metadata", "comfy", "cardnews", "inflight", "storage", "billing", "providers", "oauth", "config", "defaults", "capabilities", "skill", "ping"].includes(command)) {
   showHelp();
   process.exit(command ? 0 : 1);
 }
@@ -417,7 +311,7 @@ switch (command) {
     showStatus();
     break;
   case "doctor":
-    await doctor();
+    await doctor(args.slice(1));
     break;
   case "open":
     openBrowser();

package/config.js

@@ -112,6 +112,7 @@ export const config = {
         restartDelayMs: pickInt(env.IMA2_OAUTH_RESTART_DELAY_MS, fileCfg.oauth?.restartDelayMs, 5000),
         // Provider-backed masked edit is off until upstream STEP-0 verification is recorded.
         maskedEditEnabled: pickBool(env.IMA2_OAUTH_MASKED_EDIT_ENABLED, 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, "\n\nIf factual visual accuracy is required and the user's prompt or attached visual context is not already sufficient, use at least one concise web_search call for references before generating. If the user's prompt is already visually sufficient, do not search, rewrite, translate, summarize, or add clarifiers; pass the user's prompt through as the image_generation prompt argument."),
         validModeration: new Set(Array.isArray(fileCfg.oauth?.validModeration) && fileCfg.oauth.validModeration.length
             ? fileCfg.oauth.validModeration

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,

package/docs/CLI.md

@@ -12,6 +12,7 @@ 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 reset` | Remove saved config |
 
@@ -83,6 +84,41 @@ small text, and pixel-perfect typography can still need iteration or post-editin
 
 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.
 
+## 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
 
 | Command | Description |

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

package/docs/PROMPT_STUDIO.ko.md

@@ -0,0 +1,111 @@
+# Prompt Studio 사용 설명서
+
+Prompt Studio는 이미지를 반복해서 뽑고 비교하는 Classic 작업공간 프로필입니다.
+가운데에는 이미지 뷰어, 옆에는 최근 생성, 아래에는 프롬프트 작성창과 생성
+컨트롤을 둡니다.
+
+어떤 기능인지 헷갈리거나, 작업공간 문제를 재현해서 제보해야 할 때 이 문서를
+먼저 확인하세요.
+
+## 기능 지도
+
+| 영역 | 하는 일 | 참고 |
+|---|---|---|
+| 프롬프트 작성창 | 다음 생성 요청에 보낼 프롬프트를 보관합니다. | 기존 이미지를 선택하는 동작은 보기 전용입니다. 작성창을 덮어쓰면 안 됩니다. |
+| 멀티모드 | 현재 프롬프트로 여러 개의 이미지 요청을 시작합니다. | 각 슬롯은 후보 이미지입니다. 콜라주 칸이나 보장된 연속 장면이 아닙니다. |
+| 1:1 Direct | 앱이 프롬프트를 덜 바꾸고 원문에 가깝게 전달합니다. | 정확한 문구 비교, 엄격한 템플릿, provider 쪽 prompt syntax 실험에 씁니다. |
+| 모델 빠른 메뉴 | 사이드바 상단에서 모델과 추론 강도를 바로 바꿉니다. | 자세한 설명과 전체 설정은 Settings 작업공간에 남아 있습니다. |
+| 최근 생성 | Prompt Studio에서 보이는 최근 생성 범위를 보여줍니다. | 화살표 이동은 화면에 보이는 최근 생성 범위와 맞아야 합니다. |
+| 갤러리 | 로컬 저장 이미지, 전체/즐겨찾기 탭, 폴더를 봅니다. | 즐겨찾기 추가/제거는 보고 있던 갤러리 위치를 유지해야 합니다. |
+| 프롬프트 라이브러리 | 저장된 프롬프트를 의도적으로 작성창에 넣습니다. | 라이브러리 삽입/이어가기 같은 명시적 액션만 프롬프트를 가져옵니다. |
+
+## 멀티모드 프롬프트 작성법
+
+멀티모드는 하나의 요청 형태를 여러 후보 슬롯에 반복해서 보냅니다. 여러 대안을
+뽑는 기능이지, 한 장 안에 여러 칸을 만드는 기능은 아닙니다.
+
+서로 관련 있는 후보를 원하면 공통 대상을 먼저 적고, 바뀌어도 되는 요소를 뒤에
+적으세요.
+
+```text
+모든 이미지에서 같은 캐릭터 디자인: 은발의 배달원, 빨간 우비, 작은 검은 가방.
+4개의 대안을 만들되 카메라 각도, 조명, 배경 골목만 바꿔 주세요.
+얼굴, 옷, 나이, 색감은 유지해 주세요.
+```
+
+서로 관계없는 후보를 원하면 그 점을 직접 적으세요.
+
+```text
+로컬 이미지 생성 앱을 위한 서로 관계없는 스티커 아이디어 4개.
+각 이미지는 마스코트, 색상, 구도가 모두 달라야 합니다.
+```
+
+2컷 만화, 전후 비교, 콜라주, 접촉 시트처럼 한 장 안의 구성이 필요하면
+멀티모드가 아니라 일반 한 장 생성에서 그렇게 요청하세요.
+
+```text
+한 장의 2패널 비교 이미지를 만들어 주세요. 왼쪽은 거친 스케치 UI,
+오른쪽은 다듬어진 Prompt Studio UI. 각 패널 안에 작은 라벨을 넣어 주세요.
+```
+
+## 1:1 Direct
+
+**1:1 Direct**는 프롬프트의 정확한 문구가 중요할 때 켭니다.
+
+- 문구 차이를 비교할 때
+- 구조화된 프롬프트 템플릿을 유지할 때
+- provider 쪽 지시문 스타일을 실험할 때
+- 문제 재현 중 앱의 문구 보정을 줄이고 싶을 때
+
+Direct와 멀티모드를 동시에 켤 수 있습니다. 이때 각 멀티모드 슬롯은 같은 Direct
+프롬프트 요청 형태를 받습니다.
+
+## 추론 강도
+
+추론 강도는 선택한 모델이 생성 전후로 얼마나 많은 계획을 쓰는지에 가까운
+설정입니다. 평소에는 기본값으로 시작하고, 제약이 많거나 레퍼런스/구도 조건이
+복잡할 때 올리세요.
+
+사이드바의 모델 표시를 누르면 모델과 추론 강도를 빠르게 바꿀 수 있습니다.
+자세한 설명과 전체 모델 설정은 Settings 작업공간에 남아 있습니다.
+
+## 갤러리와 프롬프트 안전
+
+Prompt Studio는 보기와 작성을 분리합니다.
+
+- 단순 이미지 선택은 보기 전용입니다.
+- 히스토리나 갤러리 이미지를 클릭하면 이미지를 보는 데만 초점이 갑니다.
+- 즐겨찾기 추가/제거는 저장 이미지의 metadata만 바꾸며, 보던 갤러리 위치를
+  튀게 만들면 안 됩니다.
+- 전체/즐겨찾기 탭 전환은 탐색 필터입니다. 프롬프트를 가져오는 동작이 아닙니다.
+- 프롬프트 라이브러리 삽입, "이 이미지에서 이어가기", 명시적인 재사용 액션은
+  작성창을 바꾸는 의도적 액션입니다.
+
+명시적 프롬프트 가져오기 액션을 썼다면 생성 전에 작성창을 한 번 확인하세요.
+단순 이미지 선택은 작성 중인 초안을 건드리지 않아야 합니다.
+
+## Issue #75 정리
+
+v1.1.13 Prompt Studio 문제를 고치면서 아래 동작을 계약으로 고정했습니다.
+
+- 동시에 끝나는 멀티모드 결과는 각 슬롯/request identity를 유지합니다.
+- 키보드 이동은 화면에 보이는 최근 생성 범위를 따릅니다.
+- 갤러리 버튼은 최근 생성 옆에서 계속 접근 가능해야 합니다.
+- 긴 프롬프트가 기본 이미지 뷰어 영역을 과하게 빼앗지 않습니다.
+- Direct와 멀티모드 상태를 동시에 볼 수 있어야 합니다.
+- 갤러리 즐겨찾기 토글과 탭 전환은 보고 있던 위치를 유지합니다.
+- 기존 이미지를 보기 위해 선택하는 것만으로 작성창이 자동 변경되지 않습니다.
+
+## Prompt Studio 문제 제보 방법
+
+이슈를 열 때는 아래를 포함해 주세요.
+
+- `ima2-gen` 버전과 운영체제
+- 레이아웃 문제라면 브라우저와 화면 크기
+- 작업공간 프로필, 모드 토글, 모델, 추론 강도, 이미지 개수
+- 새 `ima2 serve` 세션에서 재현하는 순서
+- 전체/즐겨찾기/최근 생성 중 어느 화면에서 생겼는지
+- 개인 프롬프트가 드러나지 않는 안전한 스크린샷 또는 화면 녹화
+
+ChatGPT 쿠키, OAuth token 파일, API key, raw upstream response, private prompt
+history, generated base64 data는 공유하지 마세요.