ima2-gen 2.0.0 → 2.0.2

package/docs/API.md

@@ -10,11 +10,14 @@ http://localhost:3333
 
 ## Provider Policy
 
-Image generation supports OAuth, API-key, and Grok providers.
+Image generation supports OAuth, API-key, Grok, and Gemini (`agy` and `gemini-api`) providers.
 
 - `provider: "oauth"` uses the local Codex OAuth proxy.
 - `provider: "api"` uses the OpenAI Responses API with the hosted `image_generation` tool.
 - `provider: "grok"` uses the bundled progrok xAI proxy. Classic, Node, and Agent generation run mandatory xAI Web Search through `/v1/responses`, then run a `grok-4.3` planner call with a forced local `generate_image` function, then ima2 executes xAI `/v1/images/generations`. If reference images, a Node parent image, or an Agent current image are attached, the final step switches to xAI `/v1/images/edits` so image-to-image context is preserved.
+- `provider: "agy"` spawns the Antigravity CLI (`agy -p`) to generate images via Google Gemini's `default_api:generate_image` tool. Model is `nano-banana-2`. Output is fixed at 1024×1024 JPEG. Max 3 reference images (i2i). No web search, quality, size, or mask controls. Multimode returns a single image. Video is unsupported (`AGY_VIDEO_UNSUPPORTED`).
+- `provider: "grok-api"` uses a direct xAI API key instead of the bundled progrok OAuth proxy. Same pipeline as `grok` (Web Search → planner → `/v1/images/generations`), same aspect ratio and resolution options. Requires an xAI API key configured via the web UI key management or `XAI_API_KEY` env var. Also supports video generation.
+- `provider: "gemini-api"` calls the Google Generative Language API directly (or Vertex AI with a service account JSON). Supports models `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). Supports variable aspect ratios (1:1 through 21:9) and four resolution tiers (512px, 1K, 2K, 4K); these are honored only on the direct API path — the Vertex AI endpoint (`aiplatform.googleapis.com`) rejects the `response_format` field and always returns a default 1K/1:1 image regardless of requested size. Auth: `GEMINI_API_KEY` env var, web UI key management (`/api/keys/gemini`), or a Vertex AI service account JSON (`VERTEX_SERVICE_ACCOUNT_JSON` or `/api/keys/vertex`). When both Vertex credentials and an API key are configured, Vertex takes priority. The chosen auth mode (`apikey` or `vertex`) persists to `~/.ima2/config.json` as `geminiAuthMode` and is restored on server startup. Per-model cost: `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 covers classic generate, edit, mask-guided edit, multimode, and node generation.
 - If `provider: "api"` is requested without an API key, routes fail before upstream with `401` and `API_KEY_REQUIRED`.
 - Grok generation maps `size` to xAI `aspect_ratio` and `resolution`; it does not send an OpenAI-style `size` field upstream. Grok edit uses xAI `/v1/images/edits`; Grok mask edit remains unsupported and returns `GROK_MASK_UNSUPPORTED`.
@@ -32,6 +35,16 @@ Generation section below for the full endpoint specification.
 | `GET` | `/api/oauth/status` | OAuth proxy status and visible models |
 | `GET` | `/api/grok/status` | Bundled progrok status and visible xAI image models |
 | `GET` | `/api/billing` | Billing/status probe, including API key source when configured |
+| `GET` | `/api/quota` | Provider quota: returns `{ codex, grok }`. Grok result includes `billing: { usedUsd, limitUsd }` and a `monthly` percent window drawn from the xAI billing API. |
+
+## Account Switching
+
+| Method | Path | Notes |
+|---|---|---|
+| `POST` | `/api/auth/switch` | Start a device-code OAuth flow. Body: `{ "provider": "grok" \| "codex" }`. Returns `{ sessionId, userCode, verificationUrl }`. |
+| `GET` | `/api/auth/switch/:sessionId` | Poll switch-account session status. Returns `{ status }` where status is `pending`, `complete`, `error`, or `expired`. |
+
+The Switch Account flow opens a browser verification URL. Once the user completes the device-code step, the server saves the new credentials (Grok: `~/.progrok/auth.json`; Codex: via `codex login --device-auth`) and the session transitions to `complete`. This endpoint is surfaced as a **Switch Account** button in the Settings QuotaCard for Grok and Codex providers.
 
 ## Storage
 
@@ -81,9 +94,81 @@ Storage `state` values:
 | `GET` | `/api/inflight` | Active jobs only by default |
 | `GET` | `/api/inflight?includeTerminal=1` | Includes recent terminal jobs for debugging |
 | `DELETE` | `/api/inflight/:requestId` | Cancel or forget an active job |
+| `GET` | `/api/events` | Persistent SSE multiplex channel for all async generation progress (see below) |
 
 In-flight logs and responses use `requestId` for correlation. Logs should not include raw prompts, reference data URLs, generated base64, tokens, cookies, auth headers, or raw upstream bodies.
 
+## Events (SSE Multiplexing)
+
+### `GET /api/events` (SSE Multiplexing)
+
+Single persistent Server-Sent Events channel that carries progress for all async generation jobs. The browser UI opens one `EventSource` here instead of holding a per-request SSE connection for each job, avoiding browser per-origin connection limits.
+
+| Query | Notes |
+|---|---|
+| `lastEventId` | Optional. Reconnect cursor; also accepted via the `Last-Event-ID` request header |
+
+**Response**: `text/event-stream` (persistent). Each frame uses standard SSE fields `id`, `event`, and `data` (JSON).
+
+**Connection limits**: When active listeners reach 512, the server returns `503` with `SSE_CAPACITY` before opening the stream.
+
+**Heartbeat**: Every 15 seconds the server writes a comment frame:
+
+```text
+: ping
+```
+
+**Replay**: On reconnect, the server replays events from an in-memory ring buffer (size 2000) for IDs newer than `lastEventId`. Large image payloads (>1000 characters) are omitted from replay with `_imageOmitted: true` in the `data` payload. If the requested ID is older than the oldest buffered event, the server emits a `replay-gap` event before live fan-out:
+
+| Event | Data | Description |
+|---|---|---|
+| `replay-gap` | `{ lastEventId, oldestAvailableId }` | Client should reconcile inflight state (for example via `GET /api/inflight`) |
+
+**Job routing**: Every `data` payload includes `jobId` (same value as the job's `requestId`). Event bodies also carry `requestId` where applicable. Clients filter events by matching `data.jobId` or `data.requestId` to the job they started.
+
+**Event types** (fan-out to all connected clients):
+
+| Event | Emitted by | Description |
+|---|---|---|
+| `phase` | node, multimode, video | Lifecycle phase change |
+| `partial` | node, multimode | Progressive preview image (base64 data URL) |
+| `image` | multimode | Final saved `GenerateItem` for one sequence image |
+| `done` | node, multimode, video | Terminal success payload (route-specific shape) |
+| `error` | all generation routes | Terminal failure |
+| `submitted` | video | Job submitted to xAI |
+| `progress` | video | Progress fraction 0.0–1.0 |
+| `planning` | video | Video planner running |
+
+Example SSE frame:
+
+```text
+id: 42
+event: phase
+data: {"requestId":"req_abc","jobId":"req_abc","phase":"streaming"}
+```
+
+### Async generation mode
+
+`POST /api/node/generate`, `POST /api/generate/multimode`, and `POST /api/video/generate` support an async POST mode for clients that already hold `GET /api/events`:
+
+```json
+{
+  "async": true,
+  "requestId": "req_xxx",
+  "...": "other route fields"
+}
+```
+
+| Outcome | HTTP | Body |
+|---|---|---|
+| Accepted | `202` | `{ "requestId": "req_xxx" }` |
+| Duplicate active `requestId` | `409` | `REQUEST_ID_IN_USE` |
+| More than 12 concurrent active jobs | `429` | `TOO_MANY_JOBS` with `Retry-After: 5` |
+
+Progress events are published on `GET /api/events`. The POST response returns immediately; clients must not expect SSE on the POST connection when `async: true`.
+
+CLI and legacy clients omit `async` and keep the original behavior: per-request SSE on the same POST response (`Accept: text/event-stream` where applicable). The server dual-emits in that mode — it writes SSE to the POST response and also publishes the same events on `GET /api/events`.
+
 ## Generation
 
 ### `POST /api/generate`
@@ -100,7 +185,8 @@ Text-to-image and reference-guided root generation.
   "provider": "oauth",
   "model": "gpt-5.4",
   "references": [],
-  "requestId": "optional-client-id"
+  "requestId": "optional-client-id",
+  "storyboard": false
 }
 ```
 
@@ -108,6 +194,9 @@ Supported quality values: `low`, `medium`, `high`.
 
 Supported moderation values: `auto`, `low`.
 
+When `storyboard` is `true`, the server prepends storyboard keyframe instructions so image
+generations maintain character and scene continuity for multi-shot video production.
+
 Recommended model: `gpt-5.4`. Current app default: `gpt-5.4-mini`. `gpt-5.5` is the strongest quality option when supported, but callers should expect higher quota pressure and possible Codex CLI/backend capability requirements.
 
 When `provider` is `"grok"`, supported models are `grok-imagine-image` and
@@ -188,14 +277,46 @@ Body fields:
 }
 ```
 
-When `parentNodeId` is present, the server loads the stored parent node image and uses the edit path. Extra node references are currently supported only for root nodes.
+When `parentNodeId` is present, the server loads the stored parent node image and uses the edit path. Node-local references are allowed on both root and child/edit nodes; for child/edit nodes the parent image is sent first, then references, then the text prompt.
 
 With `provider: "grok"`, Node Mode uses the same xAI search + `grok-4.3` planner + Images API pipeline as classic generation. A parent node image, `externalSrc`, or extra references are passed to the planner and then to xAI `/v1/images/edits`; otherwise the final call uses `/v1/images/generations`. Grok Node requests are capped at three total input images, counting the parent/current image plus references, and return `GROK_REF_TOO_MANY` before upstream when that limit is exceeded. `quality: "high"` promotes the final image model to `grok-imagine-image-quality`.
 
-The route can stream Server-Sent Events when the client sends `Accept: text/event-stream`. Possible events include `phase`, `partial`, `done`, and `error`.
+The route can stream Server-Sent Events when the client sends `Accept: text/event-stream`. Possible events include `phase`, `partial`, `done`, and `error`. Alternatively, send `{ "async": true, "requestId": "req_xxx" }` in the body to receive `202 { requestId }` immediately and follow progress on `GET /api/events` (see Events section).
 
 Grok Node SSE responses do not include Responses API `partial` image events because the xAI Images API call is synchronous JSON. They still emit `phase` and `done`/`error` events so the Node UI can use the same in-flight lifecycle.
 
+### `POST /api/generate/multimode` (SSE)
+
+Multi-image sequence generation. SSE-only on the POST response unless async mode is used.
+
+```json
+{
+  "prompt": "a story in four panels",
+  "maxImages": 4,
+  "quality": "medium",
+  "size": "1024x1024",
+  "format": "png",
+  "moderation": "low",
+  "model": "gpt-5.4",
+  "provider": "oauth",
+  "references": [],
+  "requestId": "optional-client-id",
+  "async": false
+}
+```
+
+Send `Accept: text/event-stream` for per-request SSE on the POST connection. Or set `"async": true` with a client `requestId` to get `202 { requestId }` and receive events on `GET /api/events`.
+
+**SSE events**:
+
+| Event | Data | Description |
+|---|---|---|
+| `phase` | `{ requestId, phase, sequenceId?, maxImages? }` | Lifecycle phase |
+| `partial` | `{ requestId, image, index }` | Progressive preview |
+| `image` | full `GenerateItem` | One saved sequence image |
+| `done` | route-specific summary; may include `status: "partial"` after timeout if at least one image was saved | Sequence complete |
+| `error` | `{ requestId, error, code?, status? }` | Generation failed |
+
 ### `GET /api/node/:nodeId`
 
 Fetch stored node metadata and asset URL.
@@ -221,7 +342,7 @@ Server-side validation may return these reference codes:
 
 ### `POST /api/video/generate` (SSE)
 
-Generate a video via the Grok video provider. Returns Server-Sent Events.
+Generate a video via the Grok video provider. Returns Server-Sent Events on the POST connection, or accepts async mode (`{ "async": true, "requestId": "req_xxx" }`) for `202 { requestId }` with progress on `GET /api/events` (see Events section).
 
 ```json
 {
@@ -256,7 +377,7 @@ Generate a video via the Grok video provider. Returns Server-Sent Events.
 | Field | Type | Default | Notes |
 |---|---|---|---|
 | `prompt` | string | — | Required |
-| `provider` | string | `"grok"` | Must be `"grok"` |
+| `provider` | string | `"grok"` | `"grok"` or `"grok-api"` |
 | `model` | string | `grok-imagine-video` | Video model |
 | `duration` | integer | `5` | 1–15 seconds (clamped to 10 for reference-to-video) |
 | `resolution` | string | `"480p"` | `480p` or `720p` |
@@ -267,13 +388,17 @@ Generate a video via the Grok video provider. Returns Server-Sent Events.
 | `referenceFilenames` | string[] | — | Existing generated files for reference-to-video |
 | `continueFromVideo` | string | — | Generated `.mp4` parent; server extracts its last frame and rebuilds lineage from sidecar |
 | `continuityLineage` | object | — | Optional client hint; used only when `continueFromVideo` is absent |
+| `plannerModel` | string | `grok-4.3` | Grok video planner model override (also via settings UI or `IMA2_GROK_PLANNER_MODEL`) |
+| `storyboard` | boolean | `false` | Enable storyboard mode — maintains character/scene continuity across sequential clips |
 
 Blank prompts return `PROMPT_REQUIRED` with a `guidance` string. The active
 prompt should describe visual flow, motion flow, sound/music/no-music,
 dialogue/no-dialogue, ending frame, and duration pacing. The video planner uses
 the selected duration as the full clip runtime and expands short requests into a
 production-level sequence with opening composition, connected motion/emotion
-change, and a stable ending frame suitable for continuation.
+change, and a stable ending frame suitable for continuation. For multi-character
+scenes, the planner identifies speakers by visual appearance (clothing, physique,
+position, props) rather than names, and attributes each dialogue line accordingly.
 
 When `continueFromVideo` is present, the server treats the generated `.mp4`
 sidecar as authoritative. Client `continuityLineage` cannot override it. The
@@ -313,7 +438,7 @@ Grok prompt surfaces used by video APIs:
 
 | Surface | Model | Responsibility |
 |---|---|---|
-| Video planner | `grok-4.3` | Converts user prompt, search context, refs, and optional continuity lineage into the final English video prompt. It must structure core subject, action/motion, camera/composition, environment/style, dialogue/audio, ending-frame handoff, and constraints. |
+| Video planner | `grok-4.3` (override via `plannerModel`) | Converts user prompt, search context, refs, and optional continuity lineage into the final English video prompt. It must structure core subject, action/motion, camera/composition, environment/style, dialogue/audio, ending-frame handoff, and constraints. Multi-character dialogue uses appearance-based speaker identification. |
 | Video generation | xAI video model | Receives the planner prompt plus `sourceImage` or `referenceImages` when present. |
 | Video analysis | `grok-4.3` | Reads first/last frame images from `/api/video/analyze` and returns recreation/continuation guidance. |
 
@@ -461,6 +586,47 @@ Style-sheet extraction can require an API key/openai client. Image generation al
 | `GROK_RATE_LIMITED` | xAI returned a rate-limit response through progrok |
 | `GROK_AUTH_FAILED` | progrok could not authenticate the xAI request |
 | `GROK_SEARCH_TIMEOUT` / `GROK_PLANNER_TIMEOUT` / `GROK_IMAGE_TIMEOUT` | The Grok search, planner, or image API step exceeded its timeout budget |
+| `AGY_GENERATION_FAILED` | Gemini (agy) image generation failed |
+| `AGY_TIMEOUT` | Agy CLI process exceeded its 360-second timeout |
+| `AGY_PROCESS_ERROR` | Agy CLI binary failed to start or crashed |
+| `AGY_QUOTA_EXHAUSTED` | Gemini API quota exhausted (rate limit) |
+| `AGY_PARSE_FAILED` | Could not parse artifact path from agy output |
+| `AGY_ARTIFACT_NOT_FOUND` | Agy reported an artifact path that does not exist |
+| `AGY_PATH_REJECTED` | Agy artifact path was outside allowed directories |
+| `AGY_VIDEO_UNSUPPORTED` | Video generation is not supported by the Gemini (agy) provider |
+| `AGY_MASK_UNSUPPORTED` | Mask-based editing is not supported by the Gemini (agy) provider |
+| `AGY_REF_TOO_MANY` | Too many reference images for agy (max 3) |
+| `GEMINI_API_KEY_MISSING` | Gemini API key or Vertex AI credentials not configured |
+| `GEMINI_API_RATE_LIMITED` | Gemini API rate limited (429) |
+| `GEMINI_API_BAD_REQUEST` | Gemini API bad request (400/403) |
+| `GEMINI_API_SAFETY_BLOCKED` | Gemini API generation blocked by safety filter |
+| `GEMINI_API_NO_IMAGE` | Gemini API returned no image in response |
+| `VIDEO_PROVIDER_UNSUPPORTED` | Video generation requires provider `"grok"` or `"grok-api"` |
+| `SSE_CAPACITY` | More than 512 concurrent `GET /api/events` listeners |
+| `REQUEST_ID_IN_USE` | Async POST used a `requestId` that already has an active job |
+| `TOO_MANY_JOBS` | More than 12 concurrent active generation jobs (`Retry-After: 5`) |
+
+## Key Management
+
+API key management endpoints for configuring provider credentials at runtime through the web UI or HTTP API.
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/api/keys/status` | GET | Returns configured/valid/maskedKey status for all providers (openai, xai, gemini, vertex) |
+| `/api/keys/:provider` | PUT | Save an API key. Body: `{ "apiKey": "..." }`. Validates key format and upstream before saving to config.json. Provider: `openai`, `xai`, or `gemini`. |
+| `/api/keys/:provider` | DELETE | Remove a config-sourced API key. Env-sourced keys cannot be removed (`ENV_KEY_IMMUTABLE`). |
+| `/api/keys/vertex` | PUT | Save a Vertex AI service account JSON. Body: `{ "serviceAccountJson": "..." }`. Validates JSON structure (`type: "service_account"`, `project_id` required). |
+| `/api/keys/vertex` | DELETE | Remove a config-sourced Vertex AI service account. |
+
+Keys saved via PUT are stored in `config.json` and hot-updated in the runtime context (no server restart required). Keys loaded from environment variables (`OPENAI_API_KEY`, `XAI_API_KEY`, `GEMINI_API_KEY`, `VERTEX_SERVICE_ACCOUNT_JSON`) take precedence and are immutable through the API.
+
+## Thumbnail Backfill
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/api/history/backfill-thumbnails` | POST | Generate missing `.thumb.jpg` thumbnails for all images and videos in the generated directory. Returns `{ ok, total, created, skipped, failed }`. Also available offline via `ima2 backfill-thumbs`. |
+
+Thumbnails are also generated automatically on server startup for any media files that lack them.
 
 ## Endpoint → CLI Mapping
 
@@ -480,7 +646,7 @@ Most server routes under `/api/*` have a CLI wrapper. The exception is **Agent M
 | `POST /api/node/generate` (SSE) / `GET /api/node/:id` | `ima2 node generate` / `ima2 node show` |
 | `GET /api/history` | `ima2 ls` |
 | `DELETE /api/history/:name` / `…/permanent` | `ima2 history rm [--permanent]` |
-| `POST /api/history/restore` | `ima2 history restore --trash-id` |
+| `POST /api/history/:filename/restore` | `ima2 history restore --trash-id` |
 | `POST /api/history/favorite` | `ima2 history favorite` |
 | `POST /api/history/import-local` | `ima2 history import` |
 | `POST /api/metadata/read` | `ima2 metadata` / `ima2 show --metadata` |
@@ -495,17 +661,25 @@ Most server routes under `/api/*` have a CLI wrapper. The exception is **Agent M
 | `…/api/cardnews/…` (gated on `features.cardNews`) | `ima2 cardnews …` |
 | `POST /api/comfy/export-image` | `ima2 comfy export` |
 | `GET /api/inflight` / `DELETE /api/inflight/:id` | `ima2 inflight ls` (alias `ps`) / `ima2 inflight rm` (alias `cancel`) |
+| `GET /api/events` (SSE multiplex) | Web UI only (persistent `EventSource`; no CLI wrapper) |
 | `GET /api/storage/status` / `POST /api/storage/open-generated-dir` | `ima2 storage status` / `ima2 storage open` |
 | `GET /api/billing` / `GET /api/providers` / `GET /api/oauth/status` / `GET /api/grok/status` | `ima2 billing` / `ima2 providers` / `ima2 oauth status` / `ima2 grok status` |
+| `GET /api/quota` | `ima2 billing` (includes Grok `usedUsd`/`limitUsd`) |
+| `POST /api/auth/switch` / `GET /api/auth/switch/:sessionId` | Web UI only (Settings > QuotaCard > Switch Account) |
 | `GET /api/health` | `ima2 ping` |
 | `GET /api/capabilities` | `ima2 capabilities` |
+| `GET /api/config/grok-planner` | — (Grok planner model query) |
+| `PATCH /api/config/grok-planner` | — (Grok planner model update) |
+| `GET /api/agy/status` | — (Antigravity CLI install status) |
+| `POST /api/history/backfill-thumbnails` | `ima2 backfill-thumbs` |
+| `GET /api/keys/status`, `PUT/DELETE /api/keys/:provider`, `PUT/DELETE /api/keys/vertex` | Web UI only (Settings > API Keys) |
 | `GET/POST/PATCH/DELETE /api/agent/*` (sessions, turns, queue) | — (Agent Mode; web UI only, no CLI) |
 | `POST /api/prompt-builder/chat` | `ima2 prompt build` |
 
 Notes:
 - `ima2 history favorite` and `ima2 annotate …` send `X-Ima2-Browser-Id: cli-<sha1prefix>` derived from the config dir, so CLI activity does not collide with browser sessions.
 - `ima2 session graph save` performs a GET-then-PUT with `If-Match: "<version>"` to guard against `GRAPH_VERSION_CONFLICT`.
-- `ima2 history import` and `ima2 canvas-versions save/update` send raw bytes with `Content-Type: image/<png|jpeg|webp>`; the SSE endpoints (`multimode`, `node generate`) use `Accept: text/event-stream`.
+- `ima2 history import` and `ima2 canvas-versions save/update` send raw bytes with `Content-Type: image/<png|jpeg|webp>`; the SSE endpoints (`multimode`, `node generate`, `video`) use `Accept: text/event-stream`. The web UI instead uses `GET /api/events` plus `async: true` on POST routes.
 - `ima2 cardnews …` checks `runtimeConfig.features.cardNews` before calling the gated endpoints; when disabled the CLI exits 2 with a clear message instead of producing a 404.
 
 ## CLI Discovery

package/docs/CLI.md

@@ -1,6 +1,6 @@
 # CLI Reference
 
-Most server routes under `/api/*` have a CLI wrapper; Agent Mode (`/api/agent/*`) is web-UI-only and has no `ima2` subcommand. The prompt builder HTTP route (`POST /api/prompt-builder/chat`) is available through `ima2 prompt build`. The CLI is a thin shell over the local server, so most commands require a running `ima2 serve` (the few exceptions — `serve`, `setup`, `doctor`, `status`, `open`, `reset`, `config`, `grok`, `skill`, `capabilities`, and local `defaults` inspection — work without a live server).
+Most server routes under `/api/*` have a CLI wrapper; Agent Mode (`/api/agent/*`) is web-UI-only and has no `ima2` subcommand. The prompt builder HTTP route (`POST /api/prompt-builder/chat`) is available through `ima2 prompt build`. The CLI is a thin shell over the local server, so most commands require a running `ima2 serve` (the few exceptions — `serve`, `setup`, `doctor`, `status`, `open`, `reset`, `config`, `grok`, `skill`, `capabilities`, `backfill-thumbs`, and local `defaults` inspection — work without a live server).
 
 For a quick start, see the [main README](../README.md). For endpoint mapping, see [API.md](API.md).
 
@@ -16,6 +16,7 @@ For a quick start, see the [main README](../README.md). For endpoint mapping, se
 | `ima2 open` | Open the web UI in a browser |
 | `ima2 grok login/status/models/proxy` | Manage the bundled progrok runtime used by the Grok provider |
 | `ima2 reset` | Remove saved config |
+| `ima2 backfill-thumbs` | Generate missing gallery thumbnails for images and videos (offline, no running server needed) |
 
 ## Common flags
 
@@ -53,13 +54,15 @@ Agents should start from the packaged skill and capability commands instead of g
 | `ima2 node generate` | Node-mode generate (SSE; supports `--no-stream`) |
 | `ima2 node show <nodeId>` | Read node metadata |
 
-Generation flags include `--provider <auto|oauth|api|grok>`, `--reasoning-effort {none\|low\|medium\|high\|xhigh}`, `--web-search` / `--no-web-search`, `--model`, `--mode`, `--moderation`, `--ref <file>` (repeatable, up to 5 where supported), `-q low|medium|high`, `-n <count>`, `-o <file>`.
+Generation flags include `--provider <auto|oauth|api|grok|grok-api|agy|gemini-api>`, `--reasoning-effort {none\|low\|medium\|high\|xhigh}`, `--web-search` / `--no-web-search`, `--model`, `--mode`, `--moderation`, `--ref <file>` (repeatable, up to 5 where supported), `-q low|medium|high`, `-n <count>`, `-o <file>`.
 
 Provider override semantics:
 
 - `api` forces the API-key Responses path and requires a configured API key.
 - `oauth` forces the local OAuth proxy path.
 - `grok` uses the bundled progrok xAI proxy (`127.0.0.1:18645`). Classic generation first runs mandatory xAI Web Search through Responses API, then asks `grok-4.3` to call ima2's local `generate_image` tool, then ima2 executes xAI `/v1/images/generations`. If `--ref` images are attached, the final step uses xAI `/v1/images/edits` instead so image-to-image/reference context is preserved. Models: `grok-imagine-image`, `grok-imagine-image-quality`. Size is mapped to xAI `aspect_ratio` and `resolution`; the UI web-search toggle is OpenAI-provider-only because Grok search is always on in this path.
+- `agy` spawns the Antigravity CLI to generate via Google Gemini (`nano-banana-2`). Fixed 1024×1024 JPEG output, max 3 refs. No web search, quality, size, or mask controls.
+- `gemini-api` calls the Google Generative Language API directly. Models: `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). Use `--model nano-banana-2` or `--model nano-banana-pro` to select. Supports `--size` for aspect ratio and resolution (512px–4K) on the direct API path; Vertex AI ignores aspect/size. Requires `GEMINI_API_KEY` or a Vertex AI service account (`VERTEX_SERVICE_ACCOUNT_JSON`). Switching from `agy` or `gemini-api` provider auto-selects the corresponding Gemini model; switching away resets to the GPT default.
 - `auto` preserves route default behavior and currently resolves to GPT OAuth unless server routing changes.
 
 `ima2 serve` starts the bundled Grok proxy automatically. No separate `progrok`
@@ -105,7 +108,7 @@ mockup`.
 For dense or critical text, keep the text large and explicit. Exact placement,
 small text, and pixel-perfect typography can still need iteration or post-editing.
 
-Multimode-specific flags include `--max-images <1..8>`, `--ref <file>` (repeatable, max 5), `--mode <auto|direct>`, `--provider <auto|oauth|api|grok>`, and `--show-partial`. `ima2 edit --mask` remains intentionally deferred to #31 because current mask plumbing is guided edit rather than guaranteed true masked/inpaint semantics.
+Multimode-specific flags include `--max-images <1..8>`, `--ref <file>` (repeatable, max 5), `--mode <auto|direct>`, `--provider <auto|oauth|api|grok|grok-api|agy|gemini-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.
 
 ## Video
 
@@ -126,6 +129,8 @@ Video generate flags:
 | `--resolution <480p\|720p>` | Video resolution (default: 480p) |
 | `--aspect-ratio <ratio\|auto>` | 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto (default: auto) |
 | `--model <name>` | `grok-imagine-video` or `grok-imagine-video-1.5-preview` |
+| `--planner-model <name>` | Grok planner override (default: `grok-4.3`; also in settings UI and `IMA2_GROK_PLANNER_MODEL`) |
+| `--storyboard` | Enable storyboard mode — maintains character/scene continuity across sequential clips |
 | `--ref <file>` | Attach source/reference image (repeatable, max 7) |
 | `-o, --out <file>` | Output file path |
 | `-d, --out-dir <dir>` | Output directory |
@@ -160,6 +165,8 @@ Video continue flags:
 | `--aspect-ratio <ratio\|auto>` | New clip aspect ratio |
 | `--model <name>` | Optional video generation model |
 
+Video continue also accepts `--planner-model` and `--storyboard`.
+
 Video mode is auto-detected from `--ref` count:
 
 | Refs | Mode |
@@ -311,7 +318,7 @@ Card News requires the server to be started with `IMA2_CARD_NEWS=1` (or `feature
 | `ima2 inflight rm <requestId>` | Force-remove a stuck job |
 | `ima2 storage status` | Storage inspection (richer than `doctor`) |
 | `ima2 storage open` | Open the generated dir in the OS file manager (POST) |
-| `ima2 billing` | API usage / quota |
+| `ima2 billing` | API usage / quota; Grok result includes `billing.usedUsd` / `billing.limitUsd` drawn from the xAI billing API |
 | `ima2 providers` | Configured providers |
 | `ima2 oauth status` | OAuth proxy state |
 | `ima2 grok status` | Bundled progrok / xAI image-model probe state |

package/docs/FAQ.ko.md

@@ -323,6 +323,22 @@ export HTTPS_PROXY=http://127.0.0.1:7890
 
 GPT OAuth는 OpenAI와 ChatGPT/Codex 관련 호스트 접근이 필요할 수 있습니다. 회사 방화벽, TLS 검사, VPN, 프록시가 흐름을 깨뜨릴 수 있습니다. 로그인 실패와 `failed to fetch`가 반복되면 다른 네트워크에서도 시도해 보세요.
 
+## SSE 멀티플렉싱
+
+### 왜 웹 UI가 단일 SSE 연결을 쓰나요?
+
+브라우저는 같은 origin에 대해 동시 HTTP 연결 수를 제한합니다(보통 6개). 여러 이미지를 동시에 생성할 때 각 요청이 SSE 연결을 점유하면, multimode+node+video가 동시에 돌아갈 때 연결이 포화되어 갤러리 썸네일이 멈췄습니다.
+
+이제 웹 UI는 `GET /api/events`로 하나의 SSE 연결만 열고, 모든 생성 진행 이벤트를 멀티플렉싱합니다. 생성 요청은 `async: true`로 보내면 즉시 `202 { requestId }` 응답을 받아 연결을 바로 해제합니다. CLI는 영향 없이 기존 per-request SSE를 그대로 사용합니다.
+
+### SSE 연결이 끊기면 어떻게 되나요?
+
+이벤트 채널 클라이언트가 지수 백오프로 자동 재연결합니다. 재연결 시 `Last-Event-ID`를 보내서 서버의 링 버퍼(최대 2000건)에서 놓친 이벤트를 재전송받습니다. 버퍼에서 이미 사라진 이벤트가 있으면 `replay-gap` 이벤트로 알려줍니다.
+
+### 동시 작업 상한은 얼마인가요?
+
+서버는 동시 생성 작업을 12건(`MAX_CONCURRENT_JOBS`)으로 제한합니다. 초과 요청은 `429`와 `Retry-After: 5`를 받습니다. SSE 엔드포인트 자체는 512개 동시 연결까지 지원합니다.
+
 ## CLI 점검 순서
 
 아래 순서대로 확인해 보세요.

package/docs/FAQ.md

@@ -103,6 +103,20 @@ ima2 serve
 
 If this happens on a company network, a firewall, VPN, proxy, or captive portal may also be blocking the OAuth flow.
 
+### How do I use the Gemini providers?
+
+Two Gemini providers are available:
+
+- **`agy`** — uses the Antigravity CLI (`agy -p`) with no API key needed. Requires the `agy` binary to be installed and logged in. Model is `nano-banana-2`, output is fixed at 1024×1024.
+
+- **`gemini-api`** — calls the Google Generative Language API directly. Add a `GEMINI_API_KEY` env var, or configure a key via Settings > API Keys. For Vertex AI, add a service account JSON via Settings or the `VERTEX_SERVICE_ACCOUNT_JSON` env var. When both an API key and Vertex credentials are present, Vertex takes priority. Use the auth-mode dropdown in Settings to switch between `apikey` and `vertex`; the choice is saved and restored automatically.
+
+The `gemini-api` provider supports two models: `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). The web UI shows aspect-ratio and resolution controls (512px–4K) for `gemini-api`; these are honored only on the direct Gemini API path and are ignored by Vertex AI.
+
+### How do I re-authenticate Grok or Codex without restarting?
+
+Use the **Switch Account** button in Settings > QuotaCard for the provider. This starts a device-code OAuth flow: a new browser tab opens the verification URL, you complete the login, and the server automatically picks up the new credentials. The Grok quota bar also shows `$used / $limit` (in USD) drawn from the xAI billing API.
+
 ## Models and quota
 
 ### Which model should I use?
@@ -334,6 +348,22 @@ Use the host and port from your proxy client. If `ima2-gen` still fails after th
 
 GPT OAuth may require access to OpenAI and ChatGPT/Codex-related hosts. A corporate firewall, TLS inspection, VPN, or proxy can break the flow. Try a different network if login and `failed to fetch` errors keep repeating.
 
+## SSE Multiplexing
+
+### Why does the web UI use a single SSE connection?
+
+Browsers limit the number of concurrent HTTP connections to the same origin (typically 6). When generating multiple images at once, each generation request used to hold a Server-Sent Events connection open. With multimode, node, and video running simultaneously, the browser would run out of connections and gallery thumbnails would hang.
+
+The web UI now opens a single persistent `GET /api/events` SSE connection and all generation progress is multiplexed through it. Generation requests use `async: true` and receive an immediate `202 { requestId }` response, freeing the connection immediately. The CLI is unaffected — it still uses per-request SSE when `async` is not set.
+
+### What happens if the SSE connection drops?
+
+The event channel client reconnects automatically with exponential backoff. On reconnect, it sends `Last-Event-ID` so the server can replay missed events from its ring buffer (up to 2000 entries). If events have been evicted from the buffer, the server sends a `replay-gap` event so the client knows some updates may have been lost.
+
+### What is the maximum number of concurrent jobs?
+
+The server caps concurrent generation jobs at 12 (`MAX_CONCURRENT_JOBS`). Additional requests receive `429` with `Retry-After: 5`. The SSE endpoint itself caps at 512 simultaneous connections.
+
 ## CLI troubleshooting checklist
 
 Run these in order:

package/docs/PROMPT_STUDIO.md

@@ -12,10 +12,12 @@ you want a reproducible way to report a workspace issue.
 | Area | What it does | Notes |
 |---|---|---|
 | Composer | Holds the prompt for the next request. | Selecting an existing image is view-only. It should not overwrite the composer. |
+| Storyboard | Maintains character and scene continuity across sequential frames. | Toggle in the composer. Works for image and video generation; image keyframes are composed for video production. |
 | Multimode | Starts several separate image requests from the current prompt. | Each slot is a candidate output, not a collage panel or a guaranteed scene sequence. |
 | 1:1 Direct | Sends the prompt through with less rewriting by the app. | Use it for exact wording, strict prompt experiments, or provider-side prompt syntax. |
 | Model quick menu | Changes the image model and reasoning effort from the sidebar header. | The full Settings workspace remains the detailed configuration page. |
-| Recent generations | Shows the visible Prompt Studio history domain. | Arrow keys move inside the same visible recent domain instead of hidden older rows. Video items render as video thumbnails. Drag any thumbnail to the composer to add it as a reference image. |
+| Recent generations | Shows the visible Prompt Studio history domain. | Arrow keys move inside the same visible recent domain instead of hidden older rows. Video items render as video thumbnails. Drag any thumbnail to the composer to add it as a reference image. Video results expose First, Mid, and Last frame buttons to copy keyframes. |
+| Video settings | Controls Grok video duration, resolution, aspect ratio, and planner model. | Default planner model is `grok-4.3`; override per request when needed. |
 | Gallery | Browses saved local images, All/Favorites tabs, and folders. | Favorite toggles should preserve the gallery viewport you were browsing. |
 | Prompt library | Imports saved prompt text into the composer intentionally. | Library insert/continue actions are explicit prompt imports; passive image selection is not. |
 

package/docs/README.ko.md

@@ -78,7 +78,7 @@ v1.1.22부터 Ctrl+C가 DB, 소켓, 자식 프로세스를 깨끗하게 정리
 1. **GPT OAuth** — ChatGPT 계정으로 로그인 (무료, 이미지만)
 2. **Grok OAuth** — xAI/Grok 계정으로 로그인 (이미지 + 영상)
 3. **Both** — GPT + Grok 둘 다 (전체 기능)
-4. **API Key** — OpenAI API 키 입력 (유료)
+4. **Web setup** — 웹 UI에서 전체 설정
 
 영상 생성은 Grok OAuth(2번 또는 3번)가 필요합니다.
 
@@ -95,6 +95,10 @@ v1.1.22부터 Ctrl+C가 DB, 소켓, 자식 프로세스를 깨끗하게 정리
 - **Mobile shell**: 작은 화면에서는 app bar, compose sheet, compact settings toggle로 조작합니다.
 - **Observable jobs**: 진행 중인 작업과 최근 완료된 작업을 request ID로 추적합니다.
 
+### SSE 멀티플렉싱
+
+웹 UI는 단일 `GET /api/events` Server-Sent Events 연결로 모든 생성 진행 상황을 수신합니다. Multimode, node, video 요청은 비동기 POST(`202 { requestId }`)로 제출되고, 이벤트 버스를 통해 진행 이벤트가 멀티플렉싱됩니다. 기존 브라우저 6-연결 제한으로 인한 동시 생성 시 갤러리 hang 문제가 해결됩니다. `async: true`를 보내지 않는 CLI 클라이언트는 기존 per-request SSE 스트림을 그대로 사용할 수 있습니다.
+
 ## 이미지 생성 공급자
 
 이미지 생성은 로컬 Codex/ChatGPT OAuth, OpenAI API key, 번들 Grok 공급자를 지원합니다.
@@ -232,8 +236,8 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_NO_GROK_PROXY` | — | `1`이면 progrok 자동 시작 비활성화 |
 | `IMA2_GROK_PLANNER_MODEL` | `grok-4.3` | Grok 플래너 모델 (설정 UI 또는 `--planner-model` CLI 플래그로도 변경 가능) |
 | `IMA2_GROK_IMAGE_MODEL_DEFAULT` | `grok-imagine-image` | 기본 Grok 이미지 모델 |
-| `IMA2_LOG_LEVEL` | `warn` | 일반 `serve`는 `warn`, dev 모드는 `debug`. `debug`, `info`, `warn`, `error`, `silent` 지원 |
-| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `30000` | 디버그용 최근 작업 보존 시간 |
+| `IMA2_LOG_LEVEL` | `info` | 일반 `serve`는 `info`, dev 모드는 `debug`. `debug`, `info`, `warn`, `error`, `silent` 지원 |
+| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `300000` | 디버그용 최근 작업 보존 시간 (5분) |
 | `OPENAI_API_KEY` | — | `provider: "api"` Responses 이미지 경로와 보조 기능용 API 키 |
 
 ### 로그 모드

package/docs/migration/runtime-test-inventory.md

@@ -4,7 +4,7 @@ Generated by `npm run test:inventory` (script: `scripts/classify-tests.mjs`).
 
 _Tests considered "runtime-importing" if they import from `../lib/`, `../routes/`, `../bin/`, `../server`, or `../config`._
 
-Total: 175 (runtime: 60, contract: 115)
+Total: 191 (runtime: 66, contract: 125)
 
 ## Runtime-importing tests
 - `tests/agent-mode-auto-planner-contract.test.ts`
@@ -18,10 +18,14 @@ Total: 175 (runtime: 60, contract: 115)
 - `tests/api-provider-parity.test.ts`
 - `tests/billing-source.test.ts`
 - `tests/card-news-contract.test.ts`
+- `tests/card-news-template.test.ts`
+- `tests/classic-generate-async.test.ts`
 - `tests/cli-error-hints.test.ts`
 - `tests/cli-lib.test.ts`
 - `tests/comfy-bridge-contract.test.ts`
 - `tests/error-classify.test.ts`
+- `tests/event-bus.test.ts`
+- `tests/events-channel-contract.test.ts`
 - `tests/generate-route-validation-error.test.ts`
 - `tests/generated-static-privacy.test.ts`
 - `tests/generation-errors.test.ts`
@@ -36,6 +40,7 @@ Total: 175 (runtime: 60, contract: 115)
 - `tests/image-metadata-route.test.ts`
 - `tests/image-metadata-xmp.test.ts`
 - `tests/image-model.test.ts`
+- `tests/inflight-guard-contract.test.ts`
 - `tests/inflight-persistence.test.ts`
 - `tests/inflight.test.ts`
 - `tests/local-import-contract.test.ts`
@@ -64,6 +69,7 @@ Total: 175 (runtime: 60, contract: 115)
 - `tests/star-prompt.test.ts`
 - `tests/storage-migration.test.ts`
 - `tests/style-sheet.test.ts`
+- `tests/thumb-backfill.test.ts`
 - `tests/videoContinuity.test.ts`
 - `tests/videoExtendedRoute.test.ts`
 - `tests/videoRoute.test.ts`
@@ -74,6 +80,9 @@ Total: 175 (runtime: 60, contract: 115)
 - `tests/agent-mode-right-sidebar-contract.test.js`
 - `tests/agent-mode-tool-folding-contract.test.js`
 - `tests/app-weight-splitting-contract.test.js`
+- `tests/async-capacity-retry-behavior.test.ts`
+- `tests/async-capacity-retry-contract.test.js`
+- `tests/async-stream-subscribe-order.test.js`
 - `tests/background-cleanup-brush-rasterize.test.js`
 - `tests/background-cleanup-mask-compose.test.js`
 - `tests/bin.test.js`
@@ -122,8 +131,12 @@ Total: 175 (runtime: 60, contract: 115)
 - `tests/current-image-actions-readiness-contract.test.js`
 - `tests/direct-mode-visual-contract.test.js`
 - `tests/edit-mask-api-contract.test.js`
+- `tests/frontend-connection-state-contract.test.js`
+- `tests/frontend-sse-risk-contract.test.js`
+- `tests/gallery-hang-regression-contract.test.ts`
 - `tests/gallery-load-older-contract.test.js`
 - `tests/gallery-navigation-ux-contract.test.js`
+- `tests/gallery-selection-during-generation-contract.test.js`
 - `tests/gallery-session-scope-contract.test.js`
 - `tests/gallery-shortcuts-behavior.test.js`
 - `tests/gallery-shortcuts-visible-domain-contract.test.js`
@@ -144,6 +157,7 @@ Total: 175 (runtime: 60, contract: 115)
 - `tests/multimode-backend-contract.test.js`
 - `tests/multimode-concurrent-store-contract.test.js`
 - `tests/multimode-ui-contract.test.js`
+- `tests/node-async-eventbus-contract.test.js`
 - `tests/node-batch-contract.test.js`
 - `tests/node-child-refs-contract.test.js`
 - `tests/node-child-refs-payload.test.js`
@@ -155,6 +169,7 @@ Total: 175 (runtime: 60, contract: 115)
 - `tests/node-layout-contract.test.js`
 - `tests/node-pending-recovery-contract.test.js`
 - `tests/node-regen-actions-contract.test.js`
+- `tests/node-session-evaporation-contract.test.js`
 - `tests/node-ui-contract.test.js`
 - `tests/oauth-masked-edit-contract.test.js`
 - `tests/oauth-proxy-edit-mask-contract.test.js`
@@ -182,5 +197,6 @@ Total: 175 (runtime: 60, contract: 115)
 - `tests/toast-stack-contract.test.js`
 - `tests/ui-error-code-contract.test.js`
 - `tests/video-continuity-ui-contract.test.js`
+- `tests/video-gallery-refresh-contract.test.ts`
 - `tests/vite-dev-port-contract.test.js`
 - `tests/web-search-toggle-contract.test.js`