ima2-gen 2.0.0 → 2.0.2

package/CHANGELOG.md

@@ -0,0 +1,150 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **SSE multiplexing** — shared `GET /api/events` endpoint with ring-buffer replay and `Last-Event-ID` reconnect support (`lib/eventBus.ts`, `routes/events.ts`).
+- **Async POST generation mode** — multimode, node, and video routes accept async POST and dual-emit progress on both per-request SSE and the shared event bus.
+- **Frontend event channel** — singleton `EventSource` client (`ui/src/lib/eventChannel.ts`) replaces per-request SSE streams for UI generation flows.
+- **Subscribe-before-fetch contract** — `tests/async-stream-subscribe-order.test.js` locks the race where ultra-fast server publish could arrive before client handler registration.
+- Store modularization — split monolithic `useAppStore` into focused impl modules (`storeGenImpl`, `storeNodeGenImpl`, `storeVideoImpl`, `storeInflightImpl`, etc.).
+- Frontend/API barrel splits — `ui/src/lib/api.ts` and `ui/src/index.css` decomposed into ≤500-line modules.
+- Storyboard workflow — 9-panel grid with black Panel 1 lead-in for image and video generation.
+- Gallery hang fix — video decoder/connection exhaustion on focus change (RCA 01).
+
+### Changed
+
+- UI clients migrated from per-request SSE to `eventChannel` + async POST for multimode, node, and video generation.
+- Multimode concurrency tracking uses `activeFlightIds` Set instead of `multimodeAbortControllers`.
+- Test suite grew to **968** cases across **186** files (65 runtime-importing, 121 contract-only).
+
+### Fixed
+
+- SSE multiplexing hardening — inflight cancel/done race guards, replay-gap handling, subscribe/timeout/requestId races, and frontend reconnect/error parsing (`sseStreamError.ts`).
+- Node route validation order — `startJob`/202 response moved after request validation.
+- CI typecheck — unused imports in card-news tests and store split type mismatches.
+- Thumbnail backfill failure reporting (#94).
+- AGY Windows pipe handling, Gemini API aspect ratio string values, multimode same-prompt batching.
+- Moderation over-filtering — removed safety tags and added error enrichment.
+
+## [2.0.1] - 2026-06-03
+
+### Added
+
+- **Gemini API provider** (`provider: "gemini-api"`) — direct Generative Language API and Vertex AI paths with `nano-banana-2` / `nano-banana-pro` model picker, aspect ratio, and resolution controls.
+- **Grok billing quota bar** — `$used/$limit` on QuotaCard via `GET /api/quota`.
+- **Switch Account** — device-code OAuth re-auth for Grok and Codex without leaving the app.
+- **Grok video model picker** — V / V1.5 selection in video controls.
+- Image/video thumbnails and history sidebar cards.
+- Centralized recursive thumbnail backfill.
+- Gemini/Vertex API key management routes and web UI.
+
+### Changed
+
+- Provider plumbing and CLI parity for gemini-api, grok-api, and vertex paths.
+- Grok model/size pickers and adapter updates.
+- Pages and developer docs reorganized to be feature-centric.
+
+### Fixed
+
+- Preserve video metadata in sequence history and thumbnail fallbacks in history UI.
+- Vertex AI integration — auth mode persistence, skip unsupported `response_format`, prefer Vertex over API key when both configured.
+- Gemini image cost corrected to official pricing; aspect ratio/resolution UI layout polish.
+- Skip GPT pixel-limit size confirm for Grok/Gemini providers.
+- Reap orphaned codex device-auth child on abandoned Switch Account flow.
+- Document Gemini providers in CLI help; harden provider paths and CLI metadata.
+
+### Security
+
+- Atomic `config.json` writes in keys routes; atomic token write with codex env scrubbing.
+- Cap sharp input pixels to prevent decompression bombs.
+- Audit fixes — crypto session IDs, session cap, double-click guard, API key in header only.
+
+## [2.0.0] - 2026-06-02
+
+### Added
+
+- Major version bump packaging the Gemini API, Grok API key, Vertex AI, and expanded provider surface shipped in the 1.1.x preview line.
+
+## [1.1.23] - 2026-06-02
+
+### Added
+
+- Gallery skeleton shimmer and F5 refresh fix (#93).
+- Hero one-click install scripts on the documentation site.
+
+## [1.1.22] - 2026-06-02
+
+### Fixed
+
+- Graceful shutdown releases file handles on Windows (EBUSY fix).
+- Ctrl+C clean shutdown — database close, child process stop, file lock release.
+
+## [1.1.21] - 2026-05-31
+
+### Changed
+
+- Bump bundled progrok 0.1.1 → 0.2.0 (video edit + extend commands).
+
+## [1.1.15] - 2026-05-31
+
+### Added
+
+- **Agent Mode** — conversational image workspace with sessions, turns, durable queue, slash commands (`/api/agent/*`).
+- **Grok provider** — bundled progrok, Classic/Node/Agent through search + planner + xAI Images API.
+- **Video generation** — text/image/reference-to-video via Grok, edit/extend/frame/analyze routes, branch-local last-frame continuation.
+- `GET /api/capabilities` discovery endpoint (#62).
+- `POST /api/prompt-builder/chat` assistant and `ima2 prompt build` CLI wrapper.
+- Grok model/size pickers, billing API, and `ima2 grok` helpers.
+
+### Fixed
+
+- Prompt Studio regression (#75), long-prompt preview (#77), prompt autofill perf (#78).
+- Per-image metadata persistence (#79), batch comparison matrix (#80).
+
+## [1.1.10] - 2026-05-06
+
+### Added
+
+- API-key provider Responses parity for generate/edit/multimode/node (#49).
+- Masked-edit feature flag groundwork (`IMA2_OAUTH_MASKED_EDIT_ENABLED`, #31).
+- Gallery default-to-current-session with All Images toggle (#42).
+- Centralized `persistenceRegistry` for `ima2.*` localStorage keys (#43).
+- `typecheck:tests` and `test:inventory` quality gates.
+
+### Changed
+
+- Split `lib/oauthProxy.ts` into `lib/oauthProxy/*` subtree.
+- Added `lib/runtimeContext.ts`, `lib/responsesImageAdapter.ts`, `lib/providerOptions.ts`, `lib/errInfo.ts`, `lib/promptSafetyPolicy.ts`.
+
+## [1.1.0] - 2026-04-25
+
+### Added
+
+- TypeScript migration complete — route, lib, server, config, and bin sources are `*.ts` with committed build artifacts.
+- CLI feature parity with server API (#45).
+- Canvas Mode workspace split and dual-mask cleanup.
+- OS-trash soft-delete for history.
+
+## [1.0.3] - 2026-04-23
+
+### Added
+
+- Initial npm publish of `ima2-gen` — local OAuth image generation studio with Classic mode, Node mode, Canvas Mode, and CLI.
+
+[Unreleased]: https://github.com/lidge-jun/ima2-gen/compare/v2.0.1...HEAD
+[2.0.1]: https://github.com/lidge-jun/ima2-gen/compare/v2.0.0...v2.0.1
+[2.0.0]: https://github.com/lidge-jun/ima2-gen/compare/v1.1.23...v2.0.0
+[1.1.23]: https://github.com/lidge-jun/ima2-gen/compare/v1.1.22...v1.1.23
+[1.1.22]: https://github.com/lidge-jun/ima2-gen/compare/v1.1.21...v1.1.22
+[1.1.21]: https://github.com/lidge-jun/ima2-gen/compare/v1.1.20...v1.1.21
+[1.1.15]: https://github.com/lidge-jun/ima2-gen/compare/v1.1.14...v1.1.15
+[1.1.10]: https://github.com/lidge-jun/ima2-gen/compare/v1.1.9...v1.1.10
+[1.1.0]: https://github.com/lidge-jun/ima2-gen/compare/v1.0.11...v1.1.0
+[1.0.3]: https://github.com/lidge-jun/ima2-gen/releases/tag/v1.0.3

package/README.md

@@ -69,7 +69,7 @@ Each script checks for nvm/fnm/brew/winget, installs Node LTS through the best a
 1. **GPT OAuth** — login with ChatGPT account (free, images only)
 2. **Grok OAuth** — login with xAI/Grok account (images + video)
 3. **Both** — GPT OAuth + Grok OAuth (full feature access)
-4. **API Key** — paste your OpenAI API key (paid)
+4. **Web setup** — configure everything in the web UI
 
 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.
 
@@ -83,16 +83,6 @@ npm install -g ima2-gen@latest
 
 Ctrl+C now performs a clean shutdown — closing the database, stopping child processes, and releasing file locks. On older versions (< 1.1.22) or if you see `EBUSY` on Windows, use the install script which handles stale process cleanup automatically.
 
-## What's New in v1.1.22
-
-- **Storyboard mode**: composer toggle for maintaining character/scene continuity across sequential frames. Works in both image and video pipelines.
-- **Planner model selection**: choose the Grok planner model (grok-4.3 default) from video settings or via `--planner-model` CLI flag.
-- **Video frame copy**: First/Mid/Last frame extraction buttons on video results for easy keyframe copying.
-- **Multi-character dialogue**: video/image planners now identify characters by visual appearance (clothing + physique + props) instead of names, improving dialogue attribution.
-- **Graceful shutdown**: Ctrl+C now properly closes DB, server sockets, and child processes — fixes Windows EBUSY on npm update.
-- **Cross-platform install scripts**: one-click install for macOS, Windows, and Linux (auto-detects nvm/fnm/brew/winget).
-- **Atomic sidecar writes**: metadata files now use temp+rename to prevent corruption on crash.
-
 ## What It Does
 
 - **Classic mode**: generate, edit, reuse the current image, paste references, and continue from history.
@@ -107,18 +97,26 @@ Ctrl+C now performs a clean shutdown — closing the database, stopping child pr
 - **Mobile shell**: use the app bar, compose sheet, and compact settings toggle on smaller screens.
 - **Observable jobs**: active and recent jobs are tracked with safe logs and request IDs.
 
+### SSE Multiplexing
+
+The web UI uses a single `GET /api/events` Server-Sent Events connection for all generation progress. Multimode, node, and video requests are submitted as async POST (`202 { requestId }`) and progress events are multiplexed through a shared event bus. This eliminates the browser 6-connection limit that previously caused gallery hangs during concurrent generation. CLI clients that do not send `async: true` still receive per-request SSE streams for backward compatibility.
+
 ## Provider Paths
 
-Image generation can run through the local Codex/ChatGPT OAuth path, a configured OpenAI API key, or the bundled Grok provider.
+Image generation can run through the local Codex/ChatGPT OAuth path, a configured OpenAI API key, the bundled Grok provider, or the Gemini provider via Antigravity CLI.
 
 - `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 planner pass (default: `grok-4.3`, configurable in settings or via `--planner-model`), then calls xAI Images API through the local proxy.
+- `provider: "agy"` spawns the Antigravity CLI (`agy -p`) to generate images via Google Gemini's `default_api:generate_image` tool (model: `nano-banana-2`). Output is fixed at 1024×1024 JPEG, max 3 reference images. No web search, quality, or size controls.
+- `provider: "gemini-api"` calls the Google Generative Language API directly. Supports two models: `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). Auth is via `GEMINI_API_KEY` env var, web UI key management, or a Vertex AI service account JSON (`VERTEX_SERVICE_ACCOUNT_JSON`). When both an API key and Vertex credentials are configured, Vertex takes priority. Supports variable aspect ratios (1:1 through 21:9) and four resolution tiers (512px, 1K, 2K, 4K); these controls are only honored on the direct API path — the Vertex AI endpoint ignores aspect/size because it does not accept the `response_format` field. Per-model cost differs: `nano-banana-2` (Flash): 512=$0.001, 1K=$0.003, 2K=$0.004, 4K=$0.006; `nano-banana-pro`: 1K=$0.007, 2K=$0.007, 4K=$0.013. No web search or mask controls.
 - 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 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 image generation exposes a model picker (`grok-imagine-image` / `grok-imagine-image-quality`) and a size picker (aspect ratio + 1k/2k resolution). The Settings page shows a billing/quota bar with `$used/$limit` drawn from the Grok billing API, and a **Switch Account** button that starts a device-code OAuth flow (`POST /api/auth/switch`) for re-authenticating without leaving the app.
+
 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 GPT OAuth active and API key provider available.](assets/screenshots/settings-oauth-generation.png)
@@ -269,6 +267,8 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `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) |
+| `GEMINI_API_KEY` | — | API key for `provider: "gemini-api"` direct Generative Language API path |
+| `VERTEX_SERVICE_ACCOUNT_JSON` | — | Google service account JSON for Vertex AI auth with `provider: "gemini-api"`; takes priority over `GEMINI_API_KEY` when both are set |
 
 ### Logging modes
 

package/bin/commands/backfillThumbs.js

@@ -0,0 +1,24 @@
+import { config } from "../../config.js";
+import { backfillThumbnails } from "../../lib/thumbBackfill.js";
+import { invalidateHistoryIndex } from "../../lib/historyIndex.js";
+export async function backfillThumbs() {
+    const dir = config.storage.generatedDir;
+    console.log(`[thumbs] Scanning ${dir} (recursive) for missing thumbnails...`);
+    let r;
+    try {
+        r = await backfillThumbnails(dir);
+    }
+    catch (e) {
+        console.error("[thumbs] Backfill failed:", e instanceof Error ? e.message : e);
+        return;
+    }
+    if (r.created > 0)
+        invalidateHistoryIndex();
+    console.log(`[thumbs] Done: ${r.created} created, ${r.skipped} skipped (already exist), ${r.failed} failed out of ${r.total} media files.`);
+    if (r.failures.length > 0) {
+        console.log(`[thumbs] Showing ${r.failures.length} thumbnail failure(s):`);
+        for (const failure of r.failures) {
+            console.log(`  - ${failure.kind}: ${failure.file} (${failure.reason})`);
+        }
+    }
+}

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", "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 VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok", "grok-api", "agy", "gemini-api"]);
+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", "nano-banana-2", "nano-banana-pro"]);
 const SPEC = {
     flags: {
         prompt: { short: "p", type: "string" },
@@ -40,8 +40,9 @@ const HELP = `
     -s, --size <WxH>
     -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 (oauth = GPT OAuth; grok = xAI Grok)
+        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini|grok-imagine-image|grok-imagine-image-quality|nano-banana-2|nano-banana-pro>
+        --provider <auto|oauth|api|grok|grok-api|agy|gemini-api>
+                                      Provider (oauth = GPT OAuth; grok = xAI Grok; agy/gemini-api = Gemini)
         --mode <auto|direct>       Prompt handling mode. Default: auto
         --moderation <auto|low>    Default: low
         --session <id>             Apply session style sheet if enabled
@@ -64,10 +65,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, grok");
+        die(2, "--provider must be one of: auto, oauth, api, grok, grok-api, agy, gemini-api");
     }
     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, grok-imagine-image, grok-imagine-image-quality");
+        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, nano-banana-2, nano-banana-pro");
     }
     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", "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 VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok", "grok-api", "agy", "gemini-api"]);
+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", "nano-banana-2", "nano-banana-pro"]);
 const SPEC = {
     flags: {
         quality: { short: "q", type: "string", default: "low" },
@@ -39,6 +39,11 @@ const HELP = `
 
   Generate image(s) via the running ima2 server.
 
+  Batch/async note:
+    Use -n <N> for multiple candidates in one request. Independent CLI
+    commands can run concurrently against the server; monitor active requestIds
+    with 'ima2 ps --json' and stop one with 'ima2 cancel <requestId>'.
+
   Options:
     -q, --quality <low|medium|high>         Default: low
     -s, --size <WxH | auto>                 Default: 1024x1024
@@ -51,8 +56,9 @@ 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|grok-imagine-image|grok-imagine-image-quality>
-        --provider <auto|oauth|api|grok>    Provider (oauth = GPT OAuth; grok = xAI Grok)
+        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini|grok-imagine-image|grok-imagine-image-quality|nano-banana-2|nano-banana-pro>
+        --provider <auto|oauth|api|grok|grok-api|agy|gemini-api>
+                                            Provider (oauth = GPT OAuth; grok = xAI Grok; agy/gemini-api = Gemini)
         --mode <auto|direct>                Prompt handling mode. Default: auto
         --moderation <auto|low>             Default: low
         --session <id>                      Apply session style sheet if enabled
@@ -62,6 +68,7 @@ const HELP = `
 
   Examples:
     ima2 gen "a shiba in space"
+    ima2 gen "a shiba in space" -n 4 -d ./out
     ima2 gen "poster" --model gpt-5.4 --mode direct --moderation low
     ima2 gen "merge" --ref a.png --ref b.png -q high -o out.png
     cat prompt.txt | ima2 gen --stdin -n 2 -d ./out
@@ -88,10 +95,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, grok");
+        die(2, "--provider must be one of: auto, oauth, api, grok, grok-api, agy, gemini-api");
     }
     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, grok-imagine-image, grok-imagine-image-quality");
+        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, nano-banana-2, nano-banana-pro");
     }
     const VALID_REASONING = new Set(["none", "low", "medium", "high", "xhigh"]);
     if (args["reasoning-effort"] && !VALID_REASONING.has(String(args["reasoning-effort"]))) {

package/bin/commands/multimode.js

@@ -40,8 +40,9 @@ const HELP = `
     -o, --out <file>                    First image (implies --max-images 1)
     -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 (oauth = GPT OAuth; grok = xAI Grok)
+        --model <gpt-5.5|gpt-5.4|gpt-5.4-mini|grok-imagine-image|grok-imagine-image-quality|nano-banana-2|nano-banana-pro>
+        --provider <auto|oauth|api|grok|grok-api|agy|gemini-api>
+                                      Provider (oauth = GPT OAuth; grok = xAI Grok; agy/gemini-api = Gemini)
         --mode <auto|direct>            Prompt handling mode. Default: auto
         --ref <file>                    Attach reference image (repeatable, max 5)
         --reasoning-effort <none|low|medium|high|xhigh>
@@ -60,11 +61,11 @@ export default async function multimodeCmd(argv) {
     const prompt = args.positional.join(" ");
     if (!prompt)
         die(2, "prompt required");
-    const VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok"]);
+    const VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok", "grok-api", "agy", "gemini-api"]);
     const VALID_MODES = new Set(["auto", "direct"]);
     const VALID_REASONING = new Set(["none", "low", "medium", "high", "xhigh"]);
     if (args.provider && !VALID_PROVIDERS.has(String(args.provider))) {
-        die(2, "--provider must be one of: auto, oauth, api, grok");
+        die(2, "--provider must be one of: auto, oauth, api, grok, grok-api, agy, gemini-api");
     }
     if (!VALID_MODES.has(String(args.mode)))
         die(2, "--mode must be one of: auto, direct");

package/bin/commands/node.js

@@ -8,11 +8,11 @@ const HELP = `
   ima2 node <subcommand> [options]
 
   Subcommands:
-    generate <prompt...> [--parent <nodeId>] [--ref <file>...] [--provider <auto|oauth|api|grok>] [--no-stream] [...gen-style flags]
+    generate <prompt...> [--parent <nodeId>] [--ref <file>...] [--provider <auto|oauth|api|grok|grok-api|agy|gemini-api>] [--no-stream] [...gen-style flags]
     show <nodeId> [--json]
 
   Generate options:
-        --provider <auto|oauth|api|grok>  Provider for this request; grok uses progrok proxy
+        --provider <auto|oauth|api|grok|grok-api|agy|gemini-api>  Provider for this request
 `;
 const GEN_FLAGS = {
     quality: { short: "q", type: "string", default: "low" },
@@ -58,10 +58,10 @@ async function generateSub(argv) {
     if (!prompt)
         die(2, "prompt required");
     const refs = (Array.isArray(args.ref) ? args.ref : []);
-    const VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok"]);
+    const VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok", "grok-api", "agy", "gemini-api"]);
     const VALID_REASONING = new Set(["none", "low", "medium", "high", "xhigh"]);
     if (args.provider && !VALID_PROVIDERS.has(String(args.provider))) {
-        die(2, "--provider must be one of: auto, oauth, api, grok");
+        die(2, "--provider must be one of: auto, oauth, api, grok, grok-api, agy, gemini-api");
     }
     if (args["reasoning-effort"] && !VALID_REASONING.has(String(args["reasoning-effort"]))) {
         die(2, "--reasoning-effort must be one of: none, low, medium, high, xhigh");

package/bin/ima2.js

@@ -65,20 +65,15 @@ async function setup() {
     console.log("    1) GPT OAuth   — login with ChatGPT account (free, images only)");
     console.log("    2) Grok OAuth  — login with xAI/Grok account (images + video)");
     console.log("    3) Both        — GPT OAuth + Grok OAuth");
-    console.log("    4) API Key     — paste your OpenAI API key (paid)\n");
+    console.log("    4) Web setup   — configure everything in the web UI\n");
     const choice = await rl.question("  Enter 1-4: ");
     const config = loadConfig();
     if (choice.trim() === "4") {
-        const key = await rl.question("  OpenAI API Key: ");
-        if (!key.startsWith("sk-")) {
-            console.log("  Invalid API key format. Expected sk-...");
-            rl.close();
-            process.exit(1);
-        }
-        config.provider = "api";
-        config.apiKey = key.trim();
+        config.provider = "oauth";
+        delete config.apiKey;
         saveConfig(config);
-        console.log("\n  API key saved. Starting server...\n");
+        console.log("\n  You can set up everything from the web UI.");
+        console.log("  Run 'ima2 serve', then open Settings in the browser to sign in or add API keys.\n");
     }
     else if (choice.trim() === "2") {
         config.provider = "grok";
@@ -260,6 +255,12 @@ function showHelp() {
 
   Usage: ima2 <command> [options]
 
+  Generation workflow:
+    Image/video jobs run on the server. For multiple candidates, prefer
+    'ima2 gen -n <N>' or 'ima2 multimode <prompt>' instead of repeating
+    one-image prompts. Start independent CLI jobs concurrently when needed;
+    use 'ima2 ps --json' to monitor requestIds and 'ima2 cancel <id>' to stop.
+
   Server commands:
     serve [--dev]  Start the image generation server
     setup, login   Configure API key or GPT OAuth (interactive)
@@ -288,6 +289,7 @@ function showHelp() {
     cancel <id>    Mark an in-flight job canceled (ima2 cancel --help)
     inflight <sub> Inflight jobs (ls / rm)         (ima2 inflight --help)
     storage <sub>  Storage status / open-dir       (ima2 storage --help)
+    backfill-thumbs  Generate missing thumbnails for gallery performance
     billing        API usage / quota
     providers      Configured providers
     oauth <sub>    GPT OAuth proxy status              (ima2 oauth --help)
@@ -315,6 +317,9 @@ function showHelp() {
     ima2 serve                       Start server
     ima2 serve --dev                 Start with verbose server diagnostics
     ima2 gen "a shiba in space"      Generate from CLI
+    ima2 gen "a shiba in space" -n 4 -d ./out
+                                      Generate 4 candidates in one request
+    ima2 ps --json                    Watch active async generation jobs
     ima2 gen "merge" --ref a.png --ref b.png -q high -o out.png
     ima2 video "a cat playing piano" --duration 10
     ima2 ls -n 10                    Last 10 generations
@@ -332,7 +337,7 @@ if (args.includes("-v") || args.includes("--version")) {
     process.exit(0);
 }
 if ((!command || args.includes("-h") || args.includes("--help"))
-    && !["doctor", "gen", "video", "edit", "ls", "show", "ps", "cancel", "session", "history", "prompt", "multimode", "node", "annotate", "canvas-versions", "metadata", "comfy", "cardnews", "inflight", "storage", "billing", "providers", "oauth", "grok", "config", "defaults", "capabilities", "skill", "ping"].includes(command)) {
+    && !["doctor", "gen", "video", "edit", "ls", "show", "ps", "cancel", "session", "history", "prompt", "multimode", "node", "annotate", "canvas-versions", "metadata", "comfy", "cardnews", "inflight", "storage", "billing", "providers", "oauth", "grok", "config", "defaults", "capabilities", "skill", "ping", "backfill-thumbs"].includes(command)) {
     showHelp();
     process.exit(command ? 0 : 1);
 }
@@ -406,6 +411,11 @@ switch (command) {
         await mod.default(args.slice(1));
         break;
     }
+    case "backfill-thumbs": {
+        const { backfillThumbs } = await import("./commands/backfillThumbs.js");
+        await backfillThumbs();
+        break;
+    }
     case "storage":
     case "billing":
     case "providers":

package/bin/lib/config-store.js

@@ -102,7 +102,7 @@ export function envOverrideForKey(key) {
     return { envVar, value: String(process.env[envVar]) };
 }
 export function displayPath(p) {
-    const home = process.env.HOME || "";
+    const home = process.env.HOME || process.env.USERPROFILE || "";
     return home && p.startsWith(home) ? p.replace(home, "~") : p;
 }
 export function restartNotice() {