ima2-gen 1.1.20 → 1.1.21

package/README.md

@@ -16,25 +16,20 @@
 
 `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 ChatGPT OAuth or Grok OAuth, and start generating images and videos. Iterate with history, references, node branches, multimode batches, Canvas Mode cleanup, and Grok Video generation. No API key required — free ChatGPT OAuth and SuperGrok subscription cover everything.
+Install globally, sign in with ChatGPT OAuth or Grok OAuth, and start generating images and videos. Iterate with history, references, node branches, multimode batches, Canvas Mode cleanup, and Grok Video generation. No API key required — free ChatGPT OAuth and SuperGrok subscription cover everything.
 
 ![ima2-gen video playback with gallery sidebar showing generated images and videos.](assets/screenshots/classic-generate-light.png)
 
 ## Quick Start
 
 ```bash
-npx ima2-gen serve
+npm install -g ima2-gen
+ima2 setup
+ima2 serve
 ```
 
 Then open `http://localhost:3333`.
 
-If Codex is not logged in yet:
-
-```bash
-npx @openai/codex login
-npx ima2-gen serve
-```
-
 To generate a video from the CLI:
 
 ```bash
@@ -44,12 +39,7 @@ ima2 video "animate this scene" --ref photo.png --duration 10
 
 If `3333` is already occupied, `ima2-gen` binds the next available port and writes the actual URL to `~/.ima2/server.json`. Use `ima2 open` or the URL printed in the terminal instead of assuming the port.
 
-You can also install it globally:
-
-```bash
-npm install -g ima2-gen
-ima2 serve
-```
+> **Using npx?** See [docs/NPX_QUICKSTART.md](docs/NPX_QUICKSTART.md) for the `npx ima2-gen serve` workflow.
 
 ### Setup
 
@@ -60,7 +50,7 @@ ima2 serve
 3. **Both** — GPT OAuth + Grok OAuth (full feature access)
 4. **API Key** — paste your OpenAI API key (paid)
 
-Video generation requires Grok OAuth (option 2 or 3). Run `ima2 grok login` separately if you already have GPT OAuth configured and want to add video support.
+Video generation requires Grok OAuth (option 2 or 3). Run `ima2 grok login` separately if you already have GPT OAuth configured and want to add video support; it defaults to the manual-paste flow.
 
 Before updating a global install on Windows, stop any running `ima2 serve`
 process. If npm reports `EBUSY` or `resource busy or locked`, close ima2
@@ -90,11 +80,11 @@ Image generation can run through the local Codex/ChatGPT OAuth path, a configure
 - 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 GPT 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`.
 
-Grok video generation uses `grok-imagine-video` (default) or `grok-imagine-video-1.5-preview`. Three modes are auto-detected from reference count: text-to-video (0 refs), image-to-video (1 ref), and reference-to-video (2–7 refs, max 10s duration). Video controls include duration (1–15s), resolution (480p, 720p), and aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto).
+Grok video generation uses `grok-imagine-video` (default) or `grok-imagine-video-1.5-preview`. Three modes are auto-detected from reference count: text-to-video (0 refs), image-to-video (1 ref), and reference-to-video (2–7 refs, max 10s duration). `grok-imagine-video-1.5-preview` supports image-to-video but not `reference_images` Ref2V, so 2+ refs use `grok-imagine-video` as the effective model. Video edit and extension are also base-model only. Video controls include duration (1–15s), resolution (480p, 720p), and aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto).
 
-![Settings workspace showing OAuth active and API key provider available.](assets/screenshots/settings-oauth-generation.png)
+![Settings workspace showing GPT OAuth active and API key provider available.](assets/screenshots/settings-oauth-generation.png)
 
 ## Model Guidance
 
@@ -225,7 +215,7 @@ 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_REASONING_EFFORT` | `medium` | Default reasoning effort for the default (GPT 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` | `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 |
@@ -270,17 +260,17 @@ Useful references:
 **`ima2 ping` says the server is unreachable**
 Start `ima2 serve`, then check `~/.ima2/server.json`. You can also run `ima2 ping --server http://localhost:3333`.
 
-**OAuth login does not work**
-Run `npx @openai/codex login`, confirm `ima2 status`, then restart `ima2 serve`.
+**GPT OAuth login does not work**
+Re-run `ima2 setup` (option 1), 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`. 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.
+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 `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.
+Set `OPENAI_API_KEY` or configure an API key before using `provider: "api"`. The default GPT 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).
+Run `ima2 doctor image-probe --json > ima2-image-probe.json` and attach the safe JSON when opening an issue. For GPT 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

@@ -58,8 +58,8 @@ function printText(capabilities) {
     out(`server: ${capabilities.server || "none"}`);
     out("");
     out("defaults:");
-    out(`  oauth model: ${capabilities.defaults?.oauth?.model}`);
-    out(`  oauth reasoning: ${capabilities.defaults?.oauth?.reasoningEffort}`);
+    out(`  gpt-oauth model: ${capabilities.defaults?.oauth?.model}`);
+    out(`  gpt-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}`);

package/bin/commands/capabilities.ts

@@ -62,8 +62,8 @@ function printText(capabilities: any): void {
   out(`server: ${capabilities.server || "none"}`);
   out("");
   out("defaults:");
-  out(`  oauth model: ${capabilities.defaults?.oauth?.model}`);
-  out(`  oauth reasoning: ${capabilities.defaults?.oauth?.reasoningEffort}`);
+  out(`  gpt-oauth model: ${capabilities.defaults?.oauth?.model}`);
+  out(`  gpt-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}`);

package/bin/commands/defaults.js

@@ -12,8 +12,8 @@ const HELP = `
 
   Subcommands:
     ls                         Show effective defaults
-    set model <model>          Persist default model for OAuth and API paths
-    set reasoning <effort>     Persist default reasoning effort for OAuth and API paths
+    set model <model>          Persist default model for GPT OAuth and API paths
+    set reasoning <effort>     Persist default reasoning effort for GPT OAuth and API paths
     reset model                Remove persisted model defaults
     reset reasoning            Remove persisted reasoning defaults
 

package/bin/commands/defaults.ts

@@ -25,8 +25,8 @@ const HELP = `
 
   Subcommands:
     ls                         Show effective defaults
-    set model <model>          Persist default model for OAuth and API paths
-    set reasoning <effort>     Persist default reasoning effort for OAuth and API paths
+    set model <model>          Persist default model for GPT OAuth and API paths
+    set reasoning <effort>     Persist default reasoning effort for GPT OAuth and API paths
     reset model                Remove persisted model defaults
     reset reasoning            Remove persisted reasoning defaults
 

package/bin/commands/doctor.js

@@ -63,7 +63,7 @@ function showImageProbeHelp() {
     --quality <quality>    Default: low
     --moderation <value>   Default: low
     --prompt <text>        Override built-in cat prompt
-    --oauth-url <url>      Override OAuth proxy URL
+    --oauth-url <url>      Override GPT OAuth proxy URL
     --timeout-ms <ms>      Per-probe timeout
 `);
 }
@@ -155,7 +155,7 @@ async function standardDoctor() {
     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"})`);
+            console.log(`  ℹ GPT OAuth actual URL: ${adv.oauth.url} (${adv.oauth.status || "unknown"})`);
     }
     const hardeningLines = await buildHardeningDoctorLines({
         root: ROOT,
@@ -182,7 +182,7 @@ async function standardDoctor() {
         console.log(line);
     const auth = detectCodexAuth();
     if (auth.platform === "win32")
-        console.log("  ℹ Windows OAuth note: use WSL2 for Codex login.");
+        console.log("  ℹ Windows GPT OAuth note: use WSL2 for Codex login.");
     console.log(`\n  ${ok} passed, ${fail} failed\n`);
     process.exit(fail > 0 ? 1 : 0);
 }

package/bin/commands/doctor.ts

@@ -63,7 +63,7 @@ function showImageProbeHelp() {
     --quality <quality>    Default: low
     --moderation <value>   Default: low
     --prompt <text>        Override built-in cat prompt
-    --oauth-url <url>      Override OAuth proxy URL
+    --oauth-url <url>      Override GPT OAuth proxy URL
     --timeout-ms <ms>      Per-probe timeout
 `);
 }
@@ -160,7 +160,7 @@ async function standardDoctor() {
   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"})`);
+    if (adv?.oauth) console.log(`  ℹ GPT OAuth actual URL: ${adv.oauth.url} (${adv.oauth.status || "unknown"})`);
   }
 
   const hardeningLines = await buildHardeningDoctorLines({
@@ -187,7 +187,7 @@ async function standardDoctor() {
   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.");
+  if (auth.platform === "win32") console.log("  ℹ Windows GPT OAuth note: use WSL2 for Codex login.");
 
   console.log(`\n  ${ok} passed, ${fail} failed\n`);
   process.exit(fail > 0 ? 1 : 0);

package/bin/commands/edit.js

@@ -41,7 +41,7 @@ const HELP = `
     -o, --out <file>
         --json
         --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
+        --provider <auto|oauth|api|grok>  Provider (oauth = GPT OAuth; grok = xAI Grok)
         --mode <auto|direct>       Prompt handling mode. Default: auto
         --moderation <auto|low>    Default: low
         --session <id>             Apply session style sheet if enabled

package/bin/commands/edit.ts

@@ -44,7 +44,7 @@ const HELP = `
     -o, --out <file>
         --json
         --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
+        --provider <auto|oauth|api|grok>  Provider (oauth = GPT OAuth; grok = xAI Grok)
         --mode <auto|direct>       Prompt handling mode. Default: auto
         --moderation <auto|low>    Default: low
         --session <id>             Apply session style sheet if enabled

package/bin/commands/gen.js

@@ -52,7 +52,7 @@ const HELP = `
         --timeout <sec>                     Default: 180
         --server <url>                      Override server URL
         --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
+        --provider <auto|oauth|api|grok>    Provider (oauth = GPT OAuth; grok = xAI Grok)
         --mode <auto|direct>                Prompt handling mode. Default: auto
         --moderation <auto|low>             Default: low
         --session <id>                      Apply session style sheet if enabled

package/bin/commands/gen.ts

@@ -55,7 +55,7 @@ const HELP = `
         --timeout <sec>                     Default: 180
         --server <url>                      Override server URL
         --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
+        --provider <auto|oauth|api|grok>    Provider (oauth = GPT OAuth; grok = xAI Grok)
         --mode <auto|direct>                Prompt handling mode. Default: auto
         --moderation <auto|low>             Default: low
         --session <id>                      Apply session style sheet if enabled

package/bin/commands/grok.js

@@ -20,8 +20,11 @@ const HELP = `
 
   Notes:
     ima2 serve auto-starts the bundled proxy on 127.0.0.1:18645 by default.
+    ima2 grok login defaults to --manual-paste for reliable copy/paste auth.
     Use IMA2_NO_GROK_PROXY=1 to disable automatic proxy startup.
 `;
+const MANUAL_PASTE_FLAG = "--manual-paste";
+const NON_MANUAL_LOGIN_FLOW_FLAGS = new Set(["--device-code", "--browser"]);
 function localBinPath() {
     return join(ROOT, "node_modules", ".bin");
 }
@@ -39,6 +42,15 @@ function spawnProgrok(argv, env) {
         child.on("close", resolve);
     });
 }
+export function normalizeGrokLoginArgs(argv) {
+    const sub = argv[0];
+    if (sub !== "login")
+        return argv;
+    const normalized = argv.filter((arg) => !NON_MANUAL_LOGIN_FLOW_FLAGS.has(arg));
+    if (normalized.includes(MANUAL_PASTE_FLAG))
+        return normalized;
+    return [...normalized, MANUAL_PASTE_FLAG];
+}
 export default async function grokCmd(argv) {
     const sub = argv[0];
     if (!sub || sub === "--help" || sub === "-h") {
@@ -50,20 +62,13 @@ export default async function grokCmd(argv) {
         PATH: `${localBinPath()}${delimiter}${process.env.PATH || ""}`,
     };
     try {
-        // Default to --manual-paste for login (most reliable across platforms).
-        // Users can still pass --device-code or --browser explicitly.
-        if (sub === "login" && !argv.includes("--device-code") && !argv.includes("--browser") && !argv.includes("--manual-paste")) {
-            argv = [...argv, "--manual-paste"];
-        }
+        argv = normalizeGrokLoginArgs(argv);
         const code = await spawnProgrok(argv, env);
         if (code && code !== 0) {
-            // progrok 0.1.1+ defaults to device-code flow already.
-            // Do NOT auto-retry with --device-code — it issues a NEW code that
-            // invalidates the one the user may already be looking at in their browser.
-            if (sub === "login" && !argv.includes("--device-code")) {
+            if (sub === "login") {
                 out(color.yellow("⚠ ") + "Login failed. Try again with:\n");
-                out("  ima2 grok login --device-code\n");
-                die(code, "bundled progrok login failed");
+                out("  ima2 grok login\n");
+                die(code, "bundled Grok OAuth login failed");
             }
             else {
                 die(code, `bundled progrok exited with code ${code}`);

package/bin/commands/grok.ts

@@ -21,9 +21,13 @@ const HELP = `
 
   Notes:
     ima2 serve auto-starts the bundled proxy on 127.0.0.1:18645 by default.
+    ima2 grok login defaults to --manual-paste for reliable copy/paste auth.
     Use IMA2_NO_GROK_PROXY=1 to disable automatic proxy startup.
 `;
 
+const MANUAL_PASTE_FLAG = "--manual-paste";
+const NON_MANUAL_LOGIN_FLOW_FLAGS = new Set(["--device-code", "--browser"]);
+
 function localBinPath() {
   return join(ROOT, "node_modules", ".bin");
 }
@@ -43,6 +47,14 @@ function spawnProgrok(argv: string[], env: NodeJS.ProcessEnv): Promise<number |
   });
 }
 
+export function normalizeGrokLoginArgs(argv: string[]): string[] {
+  const sub = argv[0];
+  if (sub !== "login") return argv;
+  const normalized = argv.filter((arg) => !NON_MANUAL_LOGIN_FLOW_FLAGS.has(arg));
+  if (normalized.includes(MANUAL_PASTE_FLAG)) return normalized;
+  return [...normalized, MANUAL_PASTE_FLAG];
+}
+
 export default async function grokCmd(argv: string[]) {
   const sub = argv[0];
   if (!sub || sub === "--help" || sub === "-h") {
@@ -56,21 +68,14 @@ export default async function grokCmd(argv: string[]) {
   };
 
   try {
-    // Default to --manual-paste for login (most reliable across platforms).
-    // Users can still pass --device-code or --browser explicitly.
-    if (sub === "login" && !argv.includes("--device-code") && !argv.includes("--browser") && !argv.includes("--manual-paste")) {
-      argv = [...argv, "--manual-paste"];
-    }
+    argv = normalizeGrokLoginArgs(argv);
 
     const code = await spawnProgrok(argv, env);
     if (code && code !== 0) {
-      // progrok 0.1.1+ defaults to device-code flow already.
-      // Do NOT auto-retry with --device-code — it issues a NEW code that
-      // invalidates the one the user may already be looking at in their browser.
-      if (sub === "login" && !argv.includes("--device-code")) {
+      if (sub === "login") {
         out(color.yellow("⚠ ") + "Login failed. Try again with:\n");
-        out("  ima2 grok login --device-code\n");
-        die(code, "bundled progrok login failed");
+        out("  ima2 grok login\n");
+        die(code, "bundled Grok OAuth login failed");
       } else {
         die(code, `bundled progrok exited with code ${code}`);
       }

package/bin/commands/multimode.js

@@ -41,7 +41,7 @@ const HELP = `
     -d, --out-dir <dir>                 Output dir for multiple images
         --json
         --model <gpt-5.5|gpt-5.4|gpt-5.4-mini>
-        --provider <auto|oauth|api|grok>  Provider for this request; grok uses progrok proxy
+        --provider <auto|oauth|api|grok>  Provider (oauth = GPT OAuth; grok = xAI Grok)
         --mode <auto|direct>            Prompt handling mode. Default: auto
         --ref <file>                    Attach reference image (repeatable, max 5)
         --reasoning-effort <none|low|medium|high|xhigh>

package/bin/commands/multimode.ts

@@ -43,7 +43,7 @@ const HELP = `
     -d, --out-dir <dir>                 Output dir for multiple images
         --json
         --model <gpt-5.5|gpt-5.4|gpt-5.4-mini>
-        --provider <auto|oauth|api|grok>  Provider for this request; grok uses progrok proxy
+        --provider <auto|oauth|api|grok>  Provider (oauth = GPT OAuth; grok = xAI Grok)
         --mode <auto|direct>            Prompt handling mode. Default: auto
         --ref <file>                    Attach reference image (repeatable, max 5)
         --reasoning-effort <none|low|medium|high|xhigh>

package/bin/commands/observability.js

@@ -8,10 +8,10 @@ const HELP = `
     storage status [--json]                  Storage inspection
     storage open                             Open generated-dir in OS file manager
 
-  Billing / Providers / OAuth:
+  Billing / Providers / GPT OAuth:
     billing [--json]                         API usage / quota
     providers [--json]                       Configured providers
-    oauth status [--json]                    OAuth proxy state
+    oauth status [--json]                    GPT OAuth proxy state
 
   Inflight jobs:
     inflight ls [--kind classic|node|multimode] [--session <id>] [--terminal] [--json]

package/bin/commands/observability.ts

@@ -9,10 +9,10 @@ const HELP = `
     storage status [--json]                  Storage inspection
     storage open                             Open generated-dir in OS file manager
 
-  Billing / Providers / OAuth:
+  Billing / Providers / GPT OAuth:
     billing [--json]                         API usage / quota
     providers [--json]                       Configured providers
-    oauth status [--json]                    OAuth proxy state
+    oauth status [--json]                    GPT OAuth proxy state
 
   Inflight jobs:
     inflight ls [--kind classic|node|multimode] [--session <id>] [--terminal] [--json]