ima2-gen 1.1.13 → 1.1.16

package/README.md

@@ -10,11 +10,13 @@
 
 > 🌐 **Live site**: [lidge-jun.github.io/ima2-gen](https://lidge-jun.github.io/ima2-gen/) · [한국어](https://lidge-jun.github.io/ima2-gen/ko/)
 >
+> 📖 **Developer docs**: [Documentation site](https://lidge-jun.github.io/ima2-gen/docs) · [한국어](https://lidge-jun.github.io/ima2-gen/ko/docs)
+>
 > **Read in other languages**: [한국어](docs/README.ko.md) · [日本語](docs/README.ja.md) · [简体中文](docs/README.zh-CN.md)
 
 `ima2-gen` is a local image generation studio for people who want the ChatGPT/Codex image workflow in a small desktop-like web app.
 
-Run it with `npx`, sign in with Codex OAuth, type a prompt, and keep iterating with history, references, node branches, multimode batches, and Canvas Mode cleanup. No OpenAI API key is required for the default path, but API-key generation is also supported when configured.
+Run it with `npx`, sign in with Codex OAuth, type a prompt, and keep iterating with history, references, node branches, multimode batches, and Canvas Mode cleanup. No OpenAI API key is required for the default path, but API-key generation and bundled Grok generation are also supported when configured.
 
 ![ima2-gen classic generation screen with prompt composer, generated image, compact model label, and result metadata.](assets/screenshots/classic-generate-light.png)
 
@@ -53,7 +55,7 @@ persists, reboot and run the update before starting ima2 again.
 - **Node mode**: branch a good image into multiple directions without losing the original.
 - **Multimode batches**: launch several Classic outputs from one prompt, watch slot-by-slot progress, and continue from the best result.
 - **Canvas Mode**: zoom, pan, annotate, erase, clean backgrounds, keep transparent previews, and export either alpha or matte-backed versions.
-- **Local gallery**: keep generated assets on your machine with session-aware history. By default the gallery shows the current session and an All Images toggle reveals the full history; the default scope is sticky across sessions.
+- **Local gallery**: keep generated assets on your machine with session-aware history. By default the gallery shows the current session and an All Images toggle reveals the full history; the default scope is sticky across sessions. Each image records its generation time and reasoning effort in the result metadata, so they persist across reloads.
 - **Reference images**: drag, drop, paste, and attach up to 5 references; large images are compressed before upload.
 - **Prompt library imports**: import local prompt packs, GitHub folders, and curated GPT-image prompt hints into the built-in prompt library.
 - **Mobile shell**: use the app bar, compose sheet, and compact settings toggle on smaller screens.
@@ -61,13 +63,17 @@ persists, reboot and run the update before starting ima2 again.
 
 ## Provider Paths
 
-Image generation can run through either the local Codex/ChatGPT OAuth path or a configured OpenAI API key.
+Image generation can run through the local Codex/ChatGPT OAuth path, a configured OpenAI API key, or the bundled Grok provider.
 
 - `provider: "oauth"` uses the local Codex OAuth proxy.
 - `provider: "api"` calls the OpenAI Responses API with the hosted `image_generation` tool.
+- `provider: "grok"` starts bundled `progrok` on `127.0.0.1:18645`, runs mandatory xAI Web Search plus a `grok-4.3` planner pass, then calls xAI Images API through the local proxy.
 - 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.
+
+If no provider is specified, the app keeps the current OAuth/default behavior. API-key generation defaults to `gpt-5.4-mini`, `low` reasoning, and `1024x1024` unless the request passes validated model, reasoning, size, or web-search options. Grok defaults to `grok-imagine-image`; `quality: "high"` promotes the final image call to `grok-imagine-image-quality`.
 
-If no provider is specified, the app keeps the current OAuth/default behavior. API-key generation defaults to `gpt-5.4-mini`, `low` reasoning, and `1024x1024` unless the request passes validated model, reasoning, size, or web-search options.
+Grok video generation (T2V/I2V) is not shipped in `1.1.15`. The video files in `docs/grok-video-i2v-plan.md` and `docs/grok-video-i2v-research.md` are implementation planning and research notes only; the published runtime remains image-only.
 
 ![Settings workspace showing OAuth active and API key provider available.](assets/screenshots/settings-oauth-generation.png)
 
@@ -93,6 +99,10 @@ Use Classic when you want one strong result quickly.
 4. Generate one image, or enable multimode to fan out several candidate slots from the same prompt.
 5. Copy, download, continue from the result, or send it into Canvas Mode.
 
+For a control-by-control guide to Prompt Studio, multimode recipes, Direct mode,
+reasoning effort, and gallery favorite behavior, see the
+[Prompt Studio manual](docs/PROMPT_STUDIO.md).
+
 ![Multimode sequence with four candidate slots generating from one prompt and active job history in the sidebar.](assets/screenshots/multimode-sequence.png)
 
 ### Node Mode
@@ -143,6 +153,7 @@ The settings workspace keeps account, model, appearance, and language controls a
 | `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 |
 
@@ -192,14 +203,22 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `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_REASONING_EFFORT` | `medium` | Default reasoning effort for the default (OAuth) path; one of `none`, `low`, `medium`, `high`, `xhigh` |
 | `IMA2_NO_OAUTH_PROXY` | — | Set `1` to disable the auto-started OAuth proxy |
-| `IMA2_LOG_LEVEL` | `warn` | Normal serve defaults to `warn`; dev mode defaults to `debug`; supports `debug`, `info`, `warn`, `error`, or `silent` |
-| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `30000` | Recent terminal job retention for debug views |
+| `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 |
 | `IMA2_API_IMAGE_MODEL_DEFAULT` | `gpt-5.4-mini` | 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_PROXY_HOST` | `127.0.0.1` | Host for the bundled progrok proxy |
+| `IMA2_GROK_PROXY_PORT` | `18645` | Port for the bundled progrok proxy |
+| `IMA2_NO_GROK_PROXY` | — | Set `1` to disable automatic progrok startup |
+| `IMA2_GROK_PLANNER_MODEL` | `grok-4.3` | Grok search/planner model before the final Images API call |
+| `IMA2_GROK_PLANNER_TIMEOUT_MS` | `60000` | Timeout for Grok search and planner calls |
+| `IMA2_GROK_IMAGE_MODEL_DEFAULT` | `grok-imagine-image` | Default final Grok image model |
+| `IMA2_GROK_GENERATION_TIMEOUT_MS` | `120000` | 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) |
 
 ### Logging modes
@@ -214,8 +233,10 @@ The endpoint list moved to [docs/API.md](docs/API.md) so this README can stay fo
 
 Useful references:
 
+- [Developer documentation site](https://lidge-jun.github.io/ima2-gen/docs) — Overview, Quickstart, Architecture, Modes, Providers, CLI, Config, and Server API
 - [CLI Reference](docs/CLI.md)
 - [API Reference](docs/API.md)
+- [Prompt Studio manual](docs/PROMPT_STUDIO.md)
 - [FAQ](docs/FAQ.md)
 - [Recover old images](docs/RECOVER_OLD_IMAGES.md)
 - [Korean README](docs/README.ko.md)
@@ -231,11 +252,14 @@ Start `ima2 serve`, then check `~/.ima2/server.json`. You can also run `ima2 pin
 Run `npx @openai/codex login`, confirm `ima2 status`, then restart `ima2 serve`.
 
 **`fetch failed` repeats on a proxy/VPN network**
-Check that the local OAuth proxy is reachable. On networks that require a proxy, enable your proxy client's TUN/TURN-style mode, then retry `npx openai-oauth --port 10531`. If it still fails, set `HTTP_PROXY` and `HTTPS_PROXY` in the same terminal that runs `ima2 serve` or `openai-oauth`.
+Check that the local OAuth proxy is reachable. On networks that require a proxy, enable your proxy client's TUN/TURN-style mode, then retry `npx openai-oauth --port 10531`. If it still fails, set `HTTP_PROXY` and `HTTPS_PROXY` in the same terminal that runs `ima2 serve` or `openai-oauth`. On Windows, also check for auto-start network interception tools, including DNS/fragmentation bypass tools such as SecretDNS, because they can break OAuth or streaming image responses even when the browser appears connected.
 
 **Images fail with `API_KEY_REQUIRED`**
 Set `OPENAI_API_KEY` or configure an API key before using `provider: "api"`. The default OAuth path still works without an API key.
 
+**Image generation returns `EMPTY_RESPONSE` or no image data**
+Run `ima2 doctor image-probe --json > ima2-image-probe.json` and attach the safe JSON when opening an issue. For OAuth cases, also capture `ima2 gen "고양이" --no-web-search --json` and `ima2 gen "고양이" --json` while `ima2 serve` is running. Do not share ChatGPT cookies, OAuth token files, API keys, raw upstream responses, prompt history, or generated base64. See the [FAQ support bundle](docs/FAQ.md#what-should-i-share-when-oauth-image-generation-returns-no-image).
+
 **A large reference image fails**
 The app compresses large JPEG/PNG references before upload. If a file still fails, convert it to JPEG or PNG at a lower resolution and try again. HEIC/HEIF files are not supported by the browser path.
 

package/bin/commands/capabilities.js

@@ -62,9 +62,14 @@ function printText(capabilities) {
     out(`  oauth reasoning: ${capabilities.defaults?.oauth?.reasoningEffort}`);
     out(`  api model: ${capabilities.defaults?.api?.model}`);
     out(`  api reasoning: ${capabilities.defaults?.api?.reasoningEffort}`);
+    out(`  grok model: ${capabilities.defaults?.grok?.model}`);
+    out(`  grok planner: ${capabilities.defaults?.grok?.plannerModel}`);
     out("");
     out("valid:");
     out(`  models: ${capabilities.valid?.imageModels?.supported?.join(", ")}`);
+    if (capabilities.valid?.imageModels?.grokSupported?.length) {
+        out(`  grok models: ${capabilities.valid.imageModels.grokSupported.join(", ")}`);
+    }
     out(`  reasoning: ${capabilities.valid?.reasoningEfforts?.join(", ")}`);
     out(`  quality: ${capabilities.valid?.quality?.join(", ")}`);
     out(`  modes: ${capabilities.valid?.modes?.join(", ")}`);

package/bin/commands/capabilities.ts

@@ -66,9 +66,14 @@ function printText(capabilities: any): void {
   out(`  oauth reasoning: ${capabilities.defaults?.oauth?.reasoningEffort}`);
   out(`  api model: ${capabilities.defaults?.api?.model}`);
   out(`  api reasoning: ${capabilities.defaults?.api?.reasoningEffort}`);
+  out(`  grok model: ${capabilities.defaults?.grok?.model}`);
+  out(`  grok planner: ${capabilities.defaults?.grok?.plannerModel}`);
   out("");
   out("valid:");
   out(`  models: ${capabilities.valid?.imageModels?.supported?.join(", ")}`);
+  if (capabilities.valid?.imageModels?.grokSupported?.length) {
+    out(`  grok models: ${capabilities.valid.imageModels.grokSupported.join(", ")}`);
+  }
   out(`  reasoning: ${capabilities.valid?.reasoningEfforts?.join(", ")}`);
   out(`  quality: ${capabilities.valid?.quality?.join(", ")}`);
   out(`  modes: ${capabilities.valid?.modes?.join(", ")}`);

package/bin/commands/doctor.js

@@ -0,0 +1,195 @@
+import { createRequire } from "module";
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { buildHardeningDoctorLines } from "../lib/doctor-checks.js";
+import { buildStorageDoctorLines } from "../lib/storage-doctor.js";
+import { detectCodexAuth } from "../../lib/codexDetect.js";
+import { runImageDoctorProbe } from "../../lib/responsesDoctor.js";
+import { config as runtimeConfig } from "../../config.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "../..");
+const requireFromRoot = createRequire(join(ROOT, "package.json"));
+const CONFIG_FILE = runtimeConfig.storage.configFile;
+const LEGACY_CONFIG_FILE = join(ROOT, ".ima2", "config.json");
+let pkg = { version: "?", name: "ima2-gen" };
+try {
+    pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf-8"));
+}
+catch { }
+function loadConfig() {
+    if (existsSync(CONFIG_FILE)) {
+        return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+    }
+    if (existsSync(LEGACY_CONFIG_FILE)) {
+        try {
+            return JSON.parse(readFileSync(LEGACY_CONFIG_FILE, "utf-8"));
+        }
+        catch { }
+    }
+    return {};
+}
+function missingRuntimeDeps() {
+    const deps = ["express", "better-sqlite3", "openai", "openai-oauth", "progrok/package.json"];
+    return deps.filter((dep) => {
+        try {
+            requireFromRoot.resolve(dep);
+            return false;
+        }
+        catch {
+            return true;
+        }
+    }).map((dep) => dep === "progrok/package.json" ? "progrok" : dep);
+}
+function valueAfter(args, name) {
+    const index = args.indexOf(name);
+    if (index === -1)
+        return null;
+    return args[index + 1] || null;
+}
+function showImageProbeHelp() {
+    console.log(`
+  Usage: ima2 doctor image-probe [options]
+
+  Runs live, sanitized Responses probes for EMPTY_RESPONSE diagnosis.
+  The output never includes prompt text, auth tokens, URLs with credentials, or base64 image data.
+
+  Options:
+    --json                 Emit machine-readable JSON
+    --matrix               Add current-payload web_search/tool_choice probes
+    --provider <api|oauth> Override configured provider
+    --model <model>        Override image-capable Responses model
+    --size <size>          Default: 1024x1024
+    --quality <quality>    Default: low
+    --moderation <value>   Default: low
+    --prompt <text>        Override built-in cat prompt
+    --oauth-url <url>      Override OAuth proxy URL
+    --timeout-ms <ms>      Per-probe timeout
+`);
+}
+async function imageProbe(args) {
+    if (args.includes("-h") || args.includes("--help")) {
+        showImageProbeHelp();
+        return;
+    }
+    const fileConfig = loadConfig();
+    const result = await runImageDoctorProbe({
+        provider: valueAfter(args, "--provider") || fileConfig.provider || "oauth",
+        apiKey: typeof fileConfig.apiKey === "string" ? fileConfig.apiKey : undefined,
+        oauthUrl: valueAfter(args, "--oauth-url") || undefined,
+        model: valueAfter(args, "--model") || runtimeConfig.imageModels?.default || "gpt-5.4-mini",
+        size: valueAfter(args, "--size") || "1024x1024",
+        quality: valueAfter(args, "--quality") || "low",
+        moderation: valueAfter(args, "--moderation") || "low",
+        prompt: valueAfter(args, "--prompt") || undefined,
+        matrix: args.includes("--matrix"),
+        timeoutMs: Number(valueAfter(args, "--timeout-ms")) || undefined,
+        ctx: { config: runtimeConfig },
+    });
+    if (args.includes("--json")) {
+        console.log(JSON.stringify(result, null, 2));
+        process.exit(result.summary.ok ? 0 : 1);
+    }
+    console.log(`\n  ${pkg.name} v${pkg.version} — Image Probe\n`);
+    console.log(`  Provider: ${result.provider}`);
+    console.log(`  Model: ${result.model}`);
+    console.log(`  Prompt: ${result.promptId} (${result.promptChars} chars, redacted)`);
+    for (const probe of result.probes) {
+        const mark = probe.ok ? "✓" : "✗";
+        const reason = probe.diagnosticReason ? ` — ${probe.diagnosticReason}` : "";
+        console.log(`  ${mark} ${probe.id}${reason}`);
+        console.log(`      status=${probe.response.httpStatus ?? "n/a"} events=${probe.response.eventCount} images=${probe.response.imageResultCount} textChars=${probe.response.textOutputChars}`);
+    }
+    console.log(`\n  ${result.summary.passed} passed, ${result.summary.failed} failed\n`);
+    process.exit(result.summary.ok ? 0 : 1);
+}
+async function standardDoctor() {
+    console.log(`\n  ${pkg.name} v${pkg.version} — Doctor\n`);
+    let ok = 0;
+    let fail = 0;
+    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++;
+    }
+    if (existsSync(join(ROOT, "package.json"))) {
+        console.log("  ✓ package.json found");
+        ok++;
+    }
+    else {
+        console.log("  ✗ package.json missing");
+        fail++;
+    }
+    const missingDeps = missingRuntimeDeps();
+    if (missingDeps.length === 0) {
+        console.log("  ✓ runtime dependencies resolvable");
+        ok++;
+    }
+    else {
+        console.log(`  ✗ missing runtime dependencies: ${missingDeps.join(", ")}`);
+        fail++;
+    }
+    if (existsSync(join(ROOT, ".env"))) {
+        console.log("  ✓ .env file exists");
+        ok++;
+    }
+    else {
+        console.log("  ⚠ .env file not found (optional — copy from .env.example)");
+    }
+    const fileConfig = loadConfig();
+    if (fileConfig.provider) {
+        console.log(`  ✓ Configured: ${fileConfig.provider}`);
+        ok++;
+    }
+    else {
+        console.log("  ⚠ Not configured — run 'ima2 setup'");
+    }
+    const advPath = runtimeConfig.storage.advertiseFile;
+    const adv = existsSync(advPath) ? JSON.parse(readFileSync(advPath, "utf-8")) : null;
+    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,
+    });
+    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);
+    const auth = detectCodexAuth();
+    if (auth.platform === "win32")
+        console.log("  ℹ Windows OAuth note: use WSL2 for Codex login.");
+    console.log(`\n  ${ok} passed, ${fail} failed\n`);
+    process.exit(fail > 0 ? 1 : 0);
+}
+export async function doctor(args = []) {
+    if (args[0] === "image-probe") {
+        await imageProbe(args.slice(1));
+        return;
+    }
+    await standardDoctor();
+}

package/bin/commands/doctor.ts

@@ -0,0 +1,202 @@
+import { createRequire } from "module";
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { buildHardeningDoctorLines } from "../lib/doctor-checks.js";
+import { buildStorageDoctorLines } from "../lib/storage-doctor.js";
+import { detectCodexAuth } from "../../lib/codexDetect.js";
+import { runImageDoctorProbe } from "../../lib/responsesDoctor.js";
+import { config as runtimeConfig } from "../../config.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "../..");
+const requireFromRoot = createRequire(join(ROOT, "package.json"));
+const CONFIG_FILE = runtimeConfig.storage.configFile;
+const LEGACY_CONFIG_FILE = join(ROOT, ".ima2", "config.json");
+
+let pkg = { version: "?", name: "ima2-gen" };
+try {
+  pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf-8"));
+} catch {}
+
+function loadConfig() {
+  if (existsSync(CONFIG_FILE)) {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+  }
+  if (existsSync(LEGACY_CONFIG_FILE)) {
+    try { return JSON.parse(readFileSync(LEGACY_CONFIG_FILE, "utf-8")); } catch {}
+  }
+  return {};
+}
+
+function missingRuntimeDeps() {
+  const deps = ["express", "better-sqlite3", "openai", "openai-oauth", "progrok/package.json"];
+  return deps.filter((dep) => {
+    try {
+      requireFromRoot.resolve(dep);
+      return false;
+    } catch {
+      return true;
+    }
+  }).map((dep) => dep === "progrok/package.json" ? "progrok" : dep);
+}
+
+function valueAfter(args: string[], name: string) {
+  const index = args.indexOf(name);
+  if (index === -1) return null;
+  return args[index + 1] || null;
+}
+
+function showImageProbeHelp() {
+  console.log(`
+  Usage: ima2 doctor image-probe [options]
+
+  Runs live, sanitized Responses probes for EMPTY_RESPONSE diagnosis.
+  The output never includes prompt text, auth tokens, URLs with credentials, or base64 image data.
+
+  Options:
+    --json                 Emit machine-readable JSON
+    --matrix               Add current-payload web_search/tool_choice probes
+    --provider <api|oauth> Override configured provider
+    --model <model>        Override image-capable Responses model
+    --size <size>          Default: 1024x1024
+    --quality <quality>    Default: low
+    --moderation <value>   Default: low
+    --prompt <text>        Override built-in cat prompt
+    --oauth-url <url>      Override OAuth proxy URL
+    --timeout-ms <ms>      Per-probe timeout
+`);
+}
+
+async function imageProbe(args: string[]) {
+  if (args.includes("-h") || args.includes("--help")) {
+    showImageProbeHelp();
+    return;
+  }
+  const fileConfig = loadConfig();
+  const result = await runImageDoctorProbe({
+    provider: valueAfter(args, "--provider") || fileConfig.provider || "oauth",
+    apiKey: typeof fileConfig.apiKey === "string" ? fileConfig.apiKey : undefined,
+    oauthUrl: valueAfter(args, "--oauth-url") || undefined,
+    model: valueAfter(args, "--model") || runtimeConfig.imageModels?.default || "gpt-5.4-mini",
+    size: valueAfter(args, "--size") || "1024x1024",
+    quality: valueAfter(args, "--quality") || "low",
+    moderation: valueAfter(args, "--moderation") || "low",
+    prompt: valueAfter(args, "--prompt") || undefined,
+    matrix: args.includes("--matrix"),
+    timeoutMs: Number(valueAfter(args, "--timeout-ms")) || undefined,
+    ctx: { config: runtimeConfig },
+  });
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.summary.ok ? 0 : 1);
+  }
+  console.log(`\n  ${pkg.name} v${pkg.version} — Image Probe\n`);
+  console.log(`  Provider: ${result.provider}`);
+  console.log(`  Model: ${result.model}`);
+  console.log(`  Prompt: ${result.promptId} (${result.promptChars} chars, redacted)`);
+  for (const probe of result.probes) {
+    const mark = probe.ok ? "✓" : "✗";
+    const reason = probe.diagnosticReason ? ` — ${probe.diagnosticReason}` : "";
+    console.log(`  ${mark} ${probe.id}${reason}`);
+    console.log(
+      `      status=${probe.response.httpStatus ?? "n/a"} events=${probe.response.eventCount} images=${probe.response.imageResultCount} textChars=${probe.response.textOutputChars}`,
+    );
+  }
+  console.log(`\n  ${result.summary.passed} passed, ${result.summary.failed} failed\n`);
+  process.exit(result.summary.ok ? 0 : 1);
+}
+
+async function standardDoctor() {
+  console.log(`\n  ${pkg.name} v${pkg.version} — Doctor\n`);
+
+  let ok = 0;
+  let fail = 0;
+
+  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++;
+  }
+
+  if (existsSync(join(ROOT, "package.json"))) {
+    console.log("  ✓ package.json found");
+    ok++;
+  } else {
+    console.log("  ✗ package.json missing");
+    fail++;
+  }
+
+  const missingDeps = missingRuntimeDeps();
+  if (missingDeps.length === 0) {
+    console.log("  ✓ runtime dependencies resolvable");
+    ok++;
+  } else {
+    console.log(`  ✗ missing runtime dependencies: ${missingDeps.join(", ")}`);
+    fail++;
+  }
+
+  if (existsSync(join(ROOT, ".env"))) {
+    console.log("  ✓ .env file exists");
+    ok++;
+  } else {
+    console.log("  ⚠ .env file not found (optional — copy from .env.example)");
+  }
+
+  const fileConfig = loadConfig();
+  if (fileConfig.provider) {
+    console.log(`  ✓ Configured: ${fileConfig.provider}`);
+    ok++;
+  } else {
+    console.log("  ⚠ Not configured — run 'ima2 setup'");
+  }
+
+  const advPath = runtimeConfig.storage.advertiseFile;
+  const adv = existsSync(advPath) ? JSON.parse(readFileSync(advPath, "utf-8")) : null;
+  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,
+  });
+  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);
+
+  const auth = detectCodexAuth();
+  if (auth.platform === "win32") console.log("  ℹ Windows OAuth note: use WSL2 for Codex login.");
+
+  console.log(`\n  ${ok} passed, ${fail} failed\n`);
+  process.exit(fail > 0 ? 1 : 0);
+}
+
+export async function doctor(args: string[] = []) {
+  if (args[0] === "image-probe") {
+    await imageProbe(args.slice(1));
+    return;
+  }
+  await standardDoctor();
+}

package/bin/commands/edit.js

@@ -7,8 +7,8 @@ import { createCliRequestId, recoverGeneratedOutputs, formatRecoveryHint } from
 import { errInfo } from "../../lib/errInfo.js";
 const VALID_MODES = new Set(["auto", "direct"]);
 const VALID_MODERATION = new Set(["auto", "low"]);
-const VALID_PROVIDERS = new Set(["auto", "oauth", "api"]);
-const KNOWN_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark"]);
+const VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok"]);
+const KNOWN_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark", "grok-imagine-image", "grok-imagine-image-quality"]);
 const SPEC = {
     flags: {
         prompt: { short: "p", type: "string" },
@@ -40,8 +40,8 @@ const HELP = `
     -s, --size <WxH>
     -o, --out <file>
         --json
-        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini>
-        --provider <auto|oauth|api>    Provider for this request; api requires a configured API key
+        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini|grok-imagine-image|grok-imagine-image-quality>
+        --provider <auto|oauth|api|grok>  Provider for this request; grok uses progrok proxy
         --mode <auto|direct>       Prompt handling mode. Default: auto
         --moderation <auto|low>    Default: low
         --session <id>             Apply session style sheet if enabled
@@ -64,10 +64,10 @@ export default async function editCmd(argv) {
     if (!VALID_MODERATION.has(String(args.moderation)))
         die(2, "--moderation must be one of: auto, low");
     if (args.provider && !VALID_PROVIDERS.has(String(args.provider))) {
-        die(2, "--provider must be one of: auto, oauth, api");
+        die(2, "--provider must be one of: auto, oauth, api, grok");
     }
     if (args.model && !KNOWN_IMAGE_MODELS.has(String(args.model))) {
-        die(2, "--model must be one of: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark");
+        die(2, "--model must be one of: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark, grok-imagine-image, grok-imagine-image-quality");
     }
     const VALID_REASONING = new Set(["none", "low", "medium", "high", "xhigh"]);
     if (args["reasoning-effort"] && !VALID_REASONING.has(String(args["reasoning-effort"]))) {

package/bin/commands/edit.ts

@@ -8,8 +8,8 @@ import { createCliRequestId, recoverGeneratedOutputs, formatRecoveryHint } from
 import { errInfo } from "../../lib/errInfo.js";
 const VALID_MODES = new Set(["auto", "direct"]);
 const VALID_MODERATION = new Set(["auto", "low"]);
-const VALID_PROVIDERS = new Set(["auto", "oauth", "api"]);
-const KNOWN_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark"]);
+const VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok"]);
+const KNOWN_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark", "grok-imagine-image", "grok-imagine-image-quality"]);
 
 const SPEC = {
   flags: {
@@ -43,8 +43,8 @@ const HELP = `
     -s, --size <WxH>
     -o, --out <file>
         --json
-        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini>
-        --provider <auto|oauth|api>    Provider for this request; api requires a configured API key
+        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini|grok-imagine-image|grok-imagine-image-quality>
+        --provider <auto|oauth|api|grok>  Provider for this request; grok uses progrok proxy
         --mode <auto|direct>       Prompt handling mode. Default: auto
         --moderation <auto|low>    Default: low
         --session <id>             Apply session style sheet if enabled
@@ -61,10 +61,10 @@ export default async function editCmd(argv: string[]) {
   if (!VALID_MODES.has(String(args.mode))) die(2, "--mode must be one of: auto, direct");
   if (!VALID_MODERATION.has(String(args.moderation))) die(2, "--moderation must be one of: auto, low");
   if (args.provider && !VALID_PROVIDERS.has(String(args.provider))) {
-    die(2, "--provider must be one of: auto, oauth, api");
+    die(2, "--provider must be one of: auto, oauth, api, grok");
   }
   if (args.model && !KNOWN_IMAGE_MODELS.has(String(args.model))) {
-    die(2, "--model must be one of: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark");
+    die(2, "--model must be one of: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark, grok-imagine-image, grok-imagine-image-quality");
   }
   const VALID_REASONING = new Set(["none", "low", "medium", "high", "xhigh"]);
   if (args["reasoning-effort"] && !VALID_REASONING.has(String(args["reasoning-effort"]))) {

package/bin/commands/gen.js

@@ -7,8 +7,8 @@ import { createCliRequestId, recoverGeneratedOutputs, formatRecoveryHint } from
 import { errInfo } from "../../lib/errInfo.js";
 const VALID_MODES = new Set(["auto", "direct"]);
 const VALID_MODERATION = new Set(["auto", "low"]);
-const VALID_PROVIDERS = new Set(["auto", "oauth", "api"]);
-const KNOWN_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark"]);
+const VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok"]);
+const KNOWN_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark", "grok-imagine-image", "grok-imagine-image-quality"]);
 const SPEC = {
     flags: {
         quality: { short: "q", type: "string", default: "low" },
@@ -51,8 +51,8 @@ const HELP = `
         --stdin                              Read prompt from stdin
         --timeout <sec>                     Default: 180
         --server <url>                      Override server URL
-        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini>
-        --provider <auto|oauth|api>         Provider for this request; api requires a configured API key
+        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini|grok-imagine-image|grok-imagine-image-quality>
+        --provider <auto|oauth|api|grok>    Provider for this request; grok uses progrok proxy
         --mode <auto|direct>                Prompt handling mode. Default: auto
         --moderation <auto|low>             Default: low
         --session <id>                      Apply session style sheet if enabled
@@ -88,10 +88,10 @@ export default async function genCmd(argv) {
     if (!VALID_MODERATION.has(String(args.moderation)))
         die(2, "--moderation must be one of: auto, low");
     if (args.provider && !VALID_PROVIDERS.has(String(args.provider))) {
-        die(2, "--provider must be one of: auto, oauth, api");
+        die(2, "--provider must be one of: auto, oauth, api, grok");
     }
     if (args.model && !KNOWN_IMAGE_MODELS.has(String(args.model))) {
-        die(2, "--model must be one of: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark");
+        die(2, "--model must be one of: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark, grok-imagine-image, grok-imagine-image-quality");
     }
     const VALID_REASONING = new Set(["none", "low", "medium", "high", "xhigh"]);
     if (args["reasoning-effort"] && !VALID_REASONING.has(String(args["reasoning-effort"]))) {