ima2-gen 2.0.4 → 2.0.5

package/README.md

@@ -16,7 +16,7 @@
 
 `ima2-gen` is a local image generation studio for people who want the ChatGPT/Codex image workflow in a small desktop-like web app.
 
-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.
+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. Default OAuth paths need no API key; optional API-key providers (`api`, `grok-api`, `gemini-api`, `agy`) are also supported.
 
 ![ima2-gen video playback with gallery sidebar showing generated images and videos.](assets/screenshots/classic-generate-light.png)
 
@@ -108,6 +108,7 @@ Image generation can run through the local Codex/ChatGPT OAuth path, a configure
 - `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: "grok-api"` calls the xAI Images API directly with `XAI_API_KEY` (no bundled progrok OAuth 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.
@@ -117,7 +118,7 @@ If no provider is specified, the app keeps the current GPT OAuth/default behavio
 
 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).
+Grok video generation uses `grok-imagine-video` (default) or canonical `grok-imagine-video-1.5`; the legacy `grok-imagine-video-1.5-preview` string is accepted as an alias. 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). 1080p is available for `grok-imagine-video-1.5` prompt-only text-to-video and single image/frame image-to-video; prompt-only 1.5 uses the internal white-canvas I2V shim before the upstream request. 1.5 does not add `reference_images` Ref2V, V2V edit, or extension support, so those paths remain base-model only. Video controls include duration (1-15s), resolution (480p, 720p, 1080p when supported), 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)
 
@@ -255,6 +256,7 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_LOG_LEVEL` | `info` | Normal serve defaults to `info`; dev mode defaults to `debug`; supports `debug`, `info`, `warn`, `error`, or `silent` |
 | `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `300000` | Recent terminal job retention for debug views |
 | `OPENAI_API_KEY` | — | API key for the `provider: "api"` Responses API image path and auxiliary API-key features |
+| `XAI_API_KEY` | — | API key for `provider: "grok-api"` direct xAI Images API path |
 | `IMA2_API_IMAGE_MODEL_DEFAULT` | `gpt-5.4-mini` | Default image model for `provider: "api"` |
 | `IMA2_API_REASONING_EFFORT` | `low` | Default reasoning effort for `provider: "api"` |
 | `IMA2_API_IMAGE_SIZE` | `1024x1024` | Default size for `provider: "api"` |
@@ -269,6 +271,8 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `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 |
+| `IMA2_AGY_BIN` | `agy` on PATH | Explicit path to the Antigravity CLI binary for `provider: "agy"` |
+| `IMA2_MAX_PARALLEL` | `24` | Server-wide parallel generation cap |
 
 ### Logging modes
 

package/bin/commands/video.js

@@ -5,10 +5,21 @@ import { out, die, color, json, exitCodeForError } from "../lib/output.js";
 import { config } from "../../config.js";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
-const VALID_RESOLUTIONS = new Set(["480p", "720p"]);
+import { deriveVideoMode, GROK_VIDEO_MODEL_15, GROK_VIDEO_MODEL_15_PREVIEW_ALIAS, GROK_VIDEO_MODEL_BASE, validateVideoResolutionForRequest, } from "../../lib/imageModels.js";
+const VALID_RESOLUTIONS = new Set(["480p", "720p", "1080p"]);
 const VALID_ASPECT_RATIOS = new Set(["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "auto"]);
-const VALID_MODELS = new Set(["grok-imagine-video", "grok-imagine-video-1.5-preview"]);
+const VALID_MODELS = new Set([GROK_VIDEO_MODEL_BASE, GROK_VIDEO_MODEL_15, GROK_VIDEO_MODEL_15_PREVIEW_ALIAS]);
 const ACTIVE_VIDEO_PROMPT_GUIDANCE = "Active video prompt required: describe visual flow, motion flow, sound/no-music intent, dialogue/no-dialogue intent, and the desired ending frame. Pace the scene to naturally fill the selected duration with an opening composition, connected motion/emotion change, and stable ending frame.";
+function canonicalVideoModel(model) {
+    return model === GROK_VIDEO_MODEL_15_PREVIEW_ALIAS ? GROK_VIDEO_MODEL_15 : model;
+}
+function validateCliVideoResolution(model, resolution, mode) {
+    const check = validateVideoResolutionForRequest(canonicalVideoModel(model), resolution, mode, {
+        allowTextCanvasShim: true,
+    });
+    if (!("ok" in check))
+        die(2, check.error);
+}
 function parseIntegerFlag(value, fallback, label) {
     const raw = value === undefined ? String(fallback) : String(value);
     if (!/^\d+$/.test(raw))
@@ -91,9 +102,9 @@ const HELP = `
 
   Options (generate mode):
         --duration <1..15>              Duration in seconds. Default: 5. Prompt motion should naturally fill this length
-        --resolution <480p|720p>        Default: 480p
+        --resolution <480p|720p|1080p>  Default: 480p. 1080p requires --model grok-imagine-video-1.5; prompt-only uses a white-canvas I2V shim
         --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, grok-imagine-video-1.5-preview
+        --model <name>                  grok-imagine-video, grok-imagine-video-1.5 (preview alias accepted)
         --planner-model <name>          Planner model override (e.g. grok-4.3, gpt-5.5)
         --storyboard                    Enable storyboard mode (maintains character/scene continuity)
         --topic <text>                  Series topic for prompt chain continuity
@@ -149,18 +160,20 @@ export default async function videoCmd(argv) {
         die(2, "--duration must be between 1 and 15");
     const resolution = String(args.resolution);
     if (!VALID_RESOLUTIONS.has(resolution))
-        die(2, "--resolution must be one of: 480p, 720p");
+        die(2, "--resolution must be one of: 480p, 720p, 1080p");
     const aspectRatio = String(args["aspect-ratio"]);
     if (!VALID_ASPECT_RATIOS.has(aspectRatio))
         die(2, "--aspect-ratio must be one of: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto");
     if (args.model && !VALID_MODELS.has(String(args.model))) {
-        die(2, "--model must be one of: grok-imagine-video, grok-imagine-video-1.5-preview");
+        die(2, "--model must be one of: grok-imagine-video, grok-imagine-video-1.5");
     }
+    const model = args.model ? canonicalVideoModel(String(args.model)) : GROK_VIDEO_MODEL_BASE;
     const refs = (Array.isArray(args.ref) ? args.ref : []);
     if (refs.length > 7)
         die(2, "max 7 --ref attachments for video");
     if (refs.length >= 2 && duration > 10)
         die(2, "--duration must be between 1 and 10 when using 2 or more --ref attachments");
+    validateCliVideoResolution(model, resolution, deriveVideoMode(refs.length));
     const timeoutSeconds = parseIntegerFlag(args.timeout, 600, "--timeout");
     if (timeoutSeconds < 1)
         die(2, "--timeout must be at least 1");
@@ -187,7 +200,7 @@ export default async function videoCmd(argv) {
         requestId,
     };
     if (args.model)
-        body.model = args.model;
+        body.model = model;
     if (args["planner-model"])
         body.plannerModel = args["planner-model"];
     if (args.storyboard)
@@ -429,7 +442,7 @@ async function videoContinueCmd(argv) {
     const args = parseArgs(argv, spec);
     rejectUnknownFlags(args);
     if (args.help) {
-        out(`  ima2 video continue <prompt> --video <generated-file>\n\n  Generate a new clip from a generated video's last frame and carry branch-local revisedPrompt lineage.\n\n  Prompt must describe visual flow, motion, sound/music/no-music, dialogue/no-dialogue, ending frame, and how the selected duration should feel naturally filled.\n\n  Options:\n        --video <file>                 Generated .mp4 filename (required)\n        --duration <1..15>             Default: 5. Prompt motion should naturally fill this length\n        --resolution <480p|720p>       Default: 720p\n        --aspect-ratio <ratio|auto>    Default: auto\n        --model <name>                 grok-imagine-video, grok-imagine-video-1.5-preview\n    -o, --out <file>                   Download continued video to file\n        --output <file>                Alias for --out\n        --json                         Print JSON result\n        --timeout <sec>                Default: 600\n        --server <url>                 Override server URL`);
+        out(`  ima2 video continue <prompt> --video <generated-file>\n\n  Generate a new clip from a generated video's last frame and carry branch-local revisedPrompt lineage.\n\n  Prompt must describe visual flow, motion, sound/music/no-music, dialogue/no-dialogue, ending frame, and how the selected duration should feel naturally filled.\n\n  Options:\n        --video <file>                 Generated .mp4 filename (required)\n        --duration <1..15>             Default: 5. Prompt motion should naturally fill this length\n        --resolution <480p|720p|1080p> Default: 720p. 1080p requires --model grok-imagine-video-1.5\n        --aspect-ratio <ratio|auto>    Default: auto\n        --model <name>                 grok-imagine-video, grok-imagine-video-1.5 (preview alias accepted)\n    -o, --out <file>                   Download continued video to file\n        --output <file>                Alias for --out\n        --json                         Print JSON result\n        --timeout <sec>                Default: 600\n        --server <url>                 Override server URL`);
         return;
     }
     const prompt = args.positional.join(" ");
@@ -442,13 +455,15 @@ async function videoContinueCmd(argv) {
         die(2, "--duration must be between 1 and 15");
     const resolution = String(args.resolution);
     if (!VALID_RESOLUTIONS.has(resolution))
-        die(2, "--resolution must be one of: 480p, 720p");
+        die(2, "--resolution must be one of: 480p, 720p, 1080p");
     const aspectRatio = String(args["aspect-ratio"]);
     if (!VALID_ASPECT_RATIOS.has(aspectRatio))
         die(2, "--aspect-ratio must be one of: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto");
     if (args.model && !VALID_MODELS.has(String(args.model))) {
-        die(2, "--model must be one of: grok-imagine-video, grok-imagine-video-1.5-preview");
+        die(2, "--model must be one of: grok-imagine-video, grok-imagine-video-1.5");
     }
+    const model = args.model ? canonicalVideoModel(String(args.model)) : GROK_VIDEO_MODEL_BASE;
+    validateCliVideoResolution(model, resolution, "image-to-video");
     parseTimeoutSeconds(args.timeout);
     let server;
     try {
@@ -468,7 +483,7 @@ async function videoContinueCmd(argv) {
         continueFromVideo: args.video,
     };
     if (args.model)
-        body.model = args.model;
+        body.model = model;
     if (args["planner-model"])
         body.plannerModel = args["planner-model"];
     if (args.storyboard)

package/docs/API.md

@@ -362,7 +362,7 @@ Generate a video via the Grok video provider. Returns Server-Sent Events on the
 }
 ```
 
-**Models**: `grok-imagine-video` (default), `grok-imagine-video-1.5-preview`.
+**Models**: `grok-imagine-video` (default), `grok-imagine-video-1.5`. The legacy `grok-imagine-video-1.5-preview` string is accepted as a compatibility alias and normalized before the upstream request.
 
 **Mode** is auto-detected from reference inputs:
 
@@ -372,6 +372,8 @@ Generate a video via the Grok video provider. Returns Server-Sent Events on the
 | 1 image (`sourceImage` or `sourceFilename`) | image-to-video | 1–15s |
 | 2–7 images (`referenceImages` / `referenceFilenames`) | reference-to-video | 1–10s |
 
+1080p is accepted for `grok-imagine-video-1.5` prompt-only text-to-video and image-to-video with one image/frame source, including `continueFromVideo` after the server extracts the parent video's last frame. Prompt-only 1.5 text-to-video uses the internal white-canvas image-to-video shim before the upstream request. 1.5 does not add Ref2V, V2V edit, or extension support.
+
 **Parameters**:
 
 | Field | Type | Default | Notes |
@@ -380,7 +382,7 @@ Generate a video via the Grok video provider. Returns Server-Sent Events on the
 | `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` |
+| `resolution` | string | `"480p"` | `480p`, `720p`, or `1080p` (`1080p` uses 1.5 T2V canvas shim or I2V) |
 | `aspectRatio` | string | `"auto"` | 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto |
 | `sourceImage` | string | — | Base64 image for image-to-video |
 | `sourceFilename` | string | — | Existing generated file for image-to-video |
@@ -459,7 +461,7 @@ Grok prompt surfaces used by video APIs:
 | `VIDEO_PROVIDER_UNSUPPORTED` | Provider is not `"grok"` |
 | `PROMPT_REQUIRED` | Empty or missing prompt |
 | `INVALID_GROK_VIDEO_MODEL` | Model not in valid set |
-| `INVALID_VIDEO_RESOLUTION` | Resolution not 480p or 720p |
+| `INVALID_VIDEO_RESOLUTION` | Resolution is not 480p/720p/1080p, or 1080p was requested outside `grok-imagine-video-1.5` prompt-only T2V / I2V |
 | `INVALID_VIDEO_ASPECT_RATIO` | Aspect ratio not in valid set |
 | `INVALID_VIDEO_DURATION` | Duration not 1–15 integer |
 | `GROK_VIDEO_REF_TOO_MANY` | More than 7 reference images |
@@ -493,7 +495,7 @@ Extend a video from its last frame. This is a blocking JSON endpoint that starts
 }
 ```
 
-`duration` must be an integer from 2 to 10 seconds. Edit and extension support `grok-imagine-video` only; `grok-imagine-video-1.5-preview` is not accepted for these endpoints.
+`duration` must be an integer from 2 to 10 seconds. Edit and extension support `grok-imagine-video` only; `grok-imagine-video-1.5` and its preview alias are not accepted for these endpoints.
 
 ### `GET /api/video/frame`
 
@@ -516,6 +518,12 @@ Analyze first and last frames from a generated `.mp4` using Grok 4.3 image under
 
 Remote URLs and `data:` inputs are intentionally rejected to avoid server-side URL fetching through `ffmpeg`.
 
+## Generation Request Log
+
+| Method | Path | Notes |
+|---|---|---|
+| `GET` | `/api/generation-requests` | Returns `{ items: GenerationRequestLogEntry[] }` — the last 200 generation attempts (prompt, requested/succeeded flags, error). Surfaced in the web UI dev panel (`GenerationRequestLogPanel`); no CLI wrapper (#95). |
+
 ## History
 
 | Method | Path | Notes |
@@ -561,6 +569,62 @@ X-Ima2-Tab-Id
 
 Style-sheet extraction can require an API key/openai client. Image generation also supports `provider: "api"` through the shared Responses API image adapter when an API key is configured.
 
+## Prompt Library
+
+Backed by `routes/prompts.ts` and SQLite prompt tables in `lib/db.ts`.
+
+| Method | Path | Notes |
+|---|---|---|
+| `GET` | `/api/prompts` | List prompts (`folderId`, `q`, `favoritesOnly`, pagination) |
+| `POST` | `/api/prompts` | Create prompt |
+| `GET` | `/api/prompts/:id` | Fetch one prompt |
+| `PATCH` | `/api/prompts/:id` | Update prompt fields |
+| `DELETE` | `/api/prompts/:id` | Delete prompt |
+| `POST` | `/api/prompts/:id/favorite` | Toggle favorite |
+| `POST` | `/api/prompts/import` | Legacy bulk import (JSON body) |
+| `GET` | `/api/prompts/export` | Export prompt library JSON |
+| `GET` | `/api/prompts/folders` | List folders |
+| `POST` | `/api/prompts/folders` | Create folder |
+| `PATCH` | `/api/prompts/folders/:id` | Rename folder |
+| `DELETE` | `/api/prompts/folders/:id` | Delete folder |
+
+## Prompt Import
+
+Preview/commit import flow for local files, GitHub folders, curated sources, and discovery review. Implemented in `routes/promptImport.ts`.
+
+| Method | Path | Notes |
+|---|---|---|
+| `GET` | `/api/prompts/import/curated-sources` | List curated source registry entries |
+| `GET` | `/api/prompts/import/discovery` | List discovery review queue |
+| `POST` | `/api/prompts/import/discovery-search` | Search GitHub for prompt-pack candidates |
+| `POST` | `/api/prompts/import/discovery-review` | Approve/reject discovery candidate |
+| `POST` | `/api/prompts/import/curated-search` | Search indexed curated sources |
+| `POST` | `/api/prompts/import/curated-refresh` | Refresh curated index cache |
+| `POST` | `/api/prompts/import/folder-files` | List files in a GitHub folder |
+| `POST` | `/api/prompts/import/folder-preview` | Preview selected GitHub folder files |
+| `POST` | `/api/prompts/import/preview` | Preview local/GitHub import candidates |
+| `POST` | `/api/prompts/import/commit` | Commit selected candidates into the prompt library |
+
+## Card News (dev-gated)
+
+Registered only when `config.features.cardNews` is true (`routes/cardNews.ts`). Web UI requires `VITE_IMA2_CARD_NEWS=1` or `VITE_IMA2_DEV=1`; CLI uses `ima2 cardnews …`.
+
+| Method | Path | Notes |
+|---|---|---|
+| `GET` | `/api/cardnews/image-templates` | List image templates |
+| `GET` | `/api/cardnews/image-templates/:templateId/preview` | Template preview image |
+| `GET` | `/api/cardnews/role-templates` | Built-in role templates |
+| `GET` | `/api/cardnews/sets` | List card-news sets |
+| `GET` | `/api/cardnews/sets/:setId` | Fetch one set |
+| `GET` | `/api/cardnews/sets/:setId/manifest` | Set manifest JSON |
+| `POST` | `/api/cardnews/draft` | Create planner draft |
+| `POST` | `/api/cardnews/generate` | Start card generation job |
+| `POST` | `/api/cardnews/jobs` | Create job record |
+| `GET` | `/api/cardnews/jobs/:jobId` | Poll job status |
+| `POST` | `/api/cardnews/jobs/:jobId/retry` | Retry failed job |
+| `POST` | `/api/cardnews/cards/:cardId/regenerate` | Regenerate one card |
+| `POST` | `/api/cardnews/export` | Export completed set assets |
+
 ## Common Error Codes
 
 | Code | Meaning |
@@ -629,6 +693,28 @@ Keys saved via PUT are stored in `config.json` and hot-updated in the runtime co
 
 Thumbnails are also generated automatically on server startup for any media files that lack them.
 
+## Agent Mode
+
+Agent Mode is a conversational image workspace (web UI only — no CLI). All routes are under `/api/agent/*` and are backed by `routes/agent.ts` + `lib/agent*.ts`.
+
+| Method | Path | Notes |
+|---|---|---|
+| `GET` | `/api/agent/tools` | Slash-command and tool metadata |
+| `GET` | `/api/agent/sessions` | List sessions (`?limit=`) |
+| `POST` | `/api/agent/sessions` | Create session (`title`, `currentImage`, `webSearchEnabled`) → `201` |
+| `GET` | `/api/agent/sessions/:sessionId` | Fetch one session |
+| `PATCH` | `/api/agent/sessions/:sessionId` | Update title, `webSearchEnabled`, `generationSettings`, `currentImage`, locks |
+| `DELETE` | `/api/agent/sessions/:sessionId` | Delete session |
+| `POST` | `/api/agent/sessions/:sessionId/compact` | Session compaction |
+| `GET` | `/api/agent/sessions/:sessionId/manifest` | XML manifest export |
+| `POST` | `/api/agent/sessions/:sessionId/turns` | Synchronous turn (`prompt`, provider, quality, size, model, …) |
+| `GET` | `/api/agent/sessions/:sessionId/errors` | Recent errors (`?limit=`, default 10) |
+| `GET` | `/api/agent/sessions/:sessionId/queue` | Per-session queue items |
+| `POST` | `/api/agent/sessions/:sessionId/queue` | Enqueue async turn / slash command → `202` |
+| `GET` | `/api/agent/queue` | Global queue listing |
+| `POST` | `/api/agent/queue/:itemId/cancel` | Cancel queued item |
+| `POST` | `/api/agent/queue/:itemId/retry` | Retry failed item |
+
 ## Endpoint → CLI Mapping
 
 Most server routes under `/api/*` have a CLI wrapper. The exception is **Agent Mode** (`/api/agent/*`), which is server + web-UI-only and has no `ima2` subcommand. The prompt builder HTTP route (`POST /api/prompt-builder/chat`) is wrapped by `ima2 prompt build`. Use this table to find the command that calls a given endpoint. (See README.md "Client" section for full flag lists.)
@@ -665,7 +751,7 @@ Most server routes under `/api/*` have a CLI wrapper. The exception is **Agent M
 | `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`) |
+| `GET /api/quota` | Web UI only (Grok quota bar in Settings) |
 | `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` |

package/docs/CLI.md

@@ -126,9 +126,9 @@ Video generate flags:
 | Flag | Meaning |
 |---|---|
 | `--duration <1..15>` | Duration in seconds (default: 5) |
-| `--resolution <480p\|720p>` | Video resolution (default: 480p) |
+| `--resolution <480p\|720p\|1080p>` | Video resolution (default: 480p). 1080p requires `--model grok-imagine-video-1.5`; prompt-only 1.5 uses the internal white-canvas I2V shim |
 | `--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` |
+| `--model <name>` | `grok-imagine-video` or `grok-imagine-video-1.5`; `grok-imagine-video-1.5-preview` is accepted as a compatibility alias |
 | `--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) |
@@ -161,7 +161,7 @@ Video continue flags:
 |---|---|
 | `--video <generated-file>` | Parent generated `.mp4`; server extracts its last frame |
 | `--duration <1..15>` | New clip duration (default: 5) |
-| `--resolution <480p\|720p>` | New clip resolution (default: 720p) |
+| `--resolution <480p\|720p\|1080p>` | New clip resolution (default: 720p). 1080p requires `--model grok-imagine-video-1.5` |
 | `--aspect-ratio <ratio\|auto>` | New clip aspect ratio |
 | `--model <name>` | Optional video generation model |
 
@@ -175,13 +175,14 @@ Video mode is auto-detected from `--ref` count:
 | 1 | image-to-video |
 | 2–7 | reference-to-video (max 10s duration) |
 
-`grok-imagine-video-1.5-preview` supports image-to-video, but not `reference_images` reference-to-video. Prompt-only 1.5 text-to-video uses an internal white-canvas image-to-video anchor. For 2+ refs, use `grok-imagine-video`; if ima2 auto-retries from 1.5-preview to the base model, read `video.effectiveModel` and `video.modelFallback` from CLI `--json`, or `effectiveModel` and `modelFallback` from SSE. Video edit and extension are also base-model only.
+`grok-imagine-video-1.5` supports 1080p for prompt-only text-to-video and single image/frame image-to-video. Prompt-only 1.5 text-to-video is submitted through the internal white-canvas image-to-video shim because upstream 1.5 rejects raw T2V. The old `grok-imagine-video-1.5-preview` name is accepted as an alias and normalized before the upstream request. 1.5 does not support `reference_images` reference-to-video, V2V edit, or video extension. For 2+ refs, use `grok-imagine-video`; if ima2 auto-retries a 1.5 Ref2V request to the base model, read `video.effectiveModel` and `video.modelFallback` from CLI `--json`, or `effectiveModel` and `modelFallback` from SSE.
 
 SSE events: `planning` → `submitted` → `progress` (0–100%) → `done` or `error`.
 
 ```bash
 ima2 video "a cat playing piano"
 ima2 video "animate this" --ref photo.png --duration 10
+ima2 video "animate this in high detail" --ref photo.png --model grok-imagine-video-1.5 --resolution 1080p
 ima2 video "cinematic" --resolution 720p --aspect-ratio 16:9 -o out.mp4
 ima2 video "style transfer" --ref a.png --ref b.png --ref c.png --model grok-imagine-video
 ima2 video edit "make the lighting warm sunset" --video 1780226256355_50252101.mp4 -o edited.mp4
@@ -280,12 +281,12 @@ Windows DNS/fragmentation bypass tool such as SecretDNS is in use.
 | `ima2 prompt edit <id> [--name] [--text] [--folder] [--tags]` | Edit |
 | `ima2 prompt rm <id>` | Delete |
 | `ima2 prompt favorite <id>` | Toggle favorite |
-| `ima2 prompt export <id> [-o <file>]` | Export one prompt to JSON |
+| `ima2 prompt export [-o <file>]` | Export all prompts to JSON |
 | `ima2 prompt folder ls / create <name> / rename <id> <name> / rm <id> [--strategy moveToRoot\|deleteItems]` | Folder CRUD |
 | `ima2 prompt import sources` | List configured import sources |
 | `ima2 prompt import refresh --source <id>` | Re-index a source |
 | `ima2 prompt import curated --source <id> --q <query>` | Curated import (commits prompts) |
-| `ima2 prompt import discovery --q <query> --seeds <a,b,c>` | Discovery import (curator-only on some servers) |
+| `ima2 prompt import discovery --q <query> --seed <repo>...` | Discovery import (curator-only on some servers) |
 | `ima2 prompt import folder <localpath>` | Import a local folder of prompts |
 | `ima2 prompt import json <file\|@file\|-> [--folder <id>]` | Import a JSON export body through `/api/prompts/import` |
 | `ima2 prompt import preview <file\|@file\|-> [--filename <name>]` | Preview local markdown/text candidates without committing |
@@ -318,7 +319,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; Grok result includes `billing.usedUsd` / `billing.limitUsd` drawn from the xAI billing API |
+| `ima2 billing` | API usage probe via `/api/billing` (OpenAI/API-key credits when configured). Grok quota (`usedUsd`/`limitUsd`) is web-UI only via `GET /api/quota`. |
 | `ima2 providers` | Configured providers |
 | `ima2 oauth status` | OAuth proxy state |
 | `ima2 grok status` | Bundled progrok / xAI image-model probe state |

package/docs/README.ja.md

@@ -10,7 +10,7 @@
 
 `ima2-gen` は、無料の ChatGPT と SuperGrok だけで画像と動画を作れるローカル AI スタジオです。
 
-グローバルインストールし、ChatGPT または Grok OAuth でログインすれば、すぐに画像・動画生成を始められます。API キー不要で、ノード分岐、multimode batch、Grok Video、Canvas Mode まで全機能が使えます。
+グローバルインストールし、ChatGPT または Grok OAuth でログインすれば、すぐに画像・動画生成を始められます。デフォルトの OAuth パスは API キー不要です。オプションで API キー系プロバイダー（`api`, `grok-api`, `gemini-api`, `agy`）も利用できます。
 
 ![プロンプト入力、生成画像、モデル表示、結果メタデータが見える ima2-gen classic 画面](../assets/screenshots/classic-generate-light.png)
 
@@ -24,30 +24,93 @@ ima2 serve
 
 その後、`http://localhost:3333` を開きます。
 
+CLI で動画生成:
+
+```bash
+ima2 video "猫がピアノを弾く" --duration 5 --resolution 720p
+ima2 video "このシーンをアニメ化" --ref photo.png --duration 10
+```
+
 `3333` がすでに使われている場合、次に空いているポートで起動し、実際の URL は `~/.ima2/server.json` に書き込まれます。ポートを決め打ちせず、terminal に表示された URL または `ima2 open` を使ってください。
 
 > **npx を使いたい場合は?** [NPX_QUICKSTART.md](NPX_QUICKSTART.md) を参照してください。
 
+### ワンクリックインストール（npm 不要）
+
+Node.js や npm がなくても、プラットフォーム用インストールスクリプトが環境を検出し、必要なら Node LTS を入れてから ima2-gen をインストールします。
+
+**macOS:**
+```bash
+curl -fsSL https://lidge-jun.github.io/ima2-gen/install-mac.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://lidge-jun.github.io/ima2-gen/install-windows.ps1 | iex
+```
+
+**Linux / WSL:**
+```bash
+curl -fsSL https://lidge-jun.github.io/ima2-gen/install-linux.sh | bash
+```
+
+各スクリプトは nvm/fnm/brew/winget を確認し、最適な方法で Node LTS を入れ、古いプロセスのクリーンアップも自動で行います。
+
+### セットアップ
+
+`ima2 setup` では認証方式を4つ選べます:
+
+1. **GPT OAuth** — ChatGPT アカウントでログイン（無料、画像のみ）
+2. **Grok OAuth** — xAI/Grok アカウントでログイン（画像 + 動画）
+3. **Both** — GPT + Grok 両方（全機能）
+4. **Web setup** — Web UI で設定
+
+動画生成には Grok OAuth（2 または 3）が必要です。GPT OAuth だけ設定済みで動画を追加する場合は `ima2 grok login` を別途実行してください。
+
+### アップデート
+
+実行中の server を Ctrl+C で止めてから:
+
+```bash
+npm install -g ima2-gen@latest
+```
+
+Ctrl+C は DB クローズ、子プロセス停止、ファイルロック解放まで行うクリーンシャットダウンです。古いバージョン（< 1.1.22）や Windows で `EBUSY` が出る場合は、インストールスクリプトが stale プロセスを自動クリーンアップします。
+
 ## できること
 
 - **Classic mode**: すばやく生成し、編集し、現在の画像を次の参照として使えます。
 - **Node mode**: 良い画像を起点に、複数の方向へ分岐して試せます。
 - **Multimode batches**: 1つのプロンプトから複数候補を同時に走らせ、slot ごとの進行を見ながら最も良い結果から作業を継続できます。
 - **Canvas Mode**: zoom/pan、annotation、eraser、background cleanup、transparent checkerboard preview、alpha/matte export をサポートします。
-- **Local gallery**: 生成物をローカルに保存し、セッションごとの履歴として確認できます。
-- **Reference images**: 参照画像を drag/drop、paste、file picker で追加できます。大きな画像は送信前に圧縮されます。
+- **Video generation**: テキスト、画像、複数参照から短い動画を生成。SSE で planning→submitted→progress→done。First/Mid/Last フレームコピー対応。
+- **Storyboard mode**: コンポーザーの storyboard トグルで連続フレームのキャラクター・シーン連続性を維持（画像・動画両対応）。
+- **Local gallery**: 生成物をローカル保存。デフォルトは現在セッション、All Images トグルで全履歴。生成時間と reasoning effort をメタデータに記録。
+- **Reference images**: ドラッグ/ペースト/ファイル選択。画像最大5、動画最大7。大きい画像は自動圧縮。
 - **Prompt library imports**: local prompt pack、GitHub folder、curated GPT-image hint を built-in prompt library に取り込めます。
 - **Mobile shell**: 小さい画面では app bar、compose sheet、compact settings toggle で操作できます。
 - **Observable jobs**: 進行中の生成と最近の生成を request ID で追跡できます。
 
+### SSE マルチプレキシング
+
+Web UI は単一の `GET /api/events` Server-Sent Events 接続で全生成の進行を受信します。Multimode、node、video リクエストは非同期 POST（`202 { requestId }`）で送信され、共有イベントバス経由で進行イベントがマルチプレクスされます。これにより、同時生成時のブラウザ 6 接続制限によるギャラリー hang が解消されます。`async: true` を送らない CLI クライアントは、後方互換のため従来どおりリクエストごとの SSE ストリームを受け取れます。
+
 ## 画像生成は OAuth と API key をサポートします
 
 既定の画像生成は、ローカルの Codex/ChatGPT OAuth 経路で実行されます。
 
 API key が env/config に存在する場合、生成エンドポイントで `provider: "api"` を指定すると Responses API の `image_generation` tool を使用できます。
 
+- `provider: "grok-api"` — `XAI_API_KEY` で xAI Images API を直接呼び出し
+- `provider: "agy"` — ローカル Antigravity CLI (`IMA2_AGY_BIN`)
+- `provider: "gemini-api"` — `GEMINI_API_KEY` または Vertex (`VERTEX_SERVICE_ACCOUNT_JSON`、Vertex 優先)
+
 Settings に **API key provider available** と表示される場合、API key が検出され、生成・編集・multimode・node request に使用できるという意味です。
 
+Grok 動画は `grok-imagine-video`（既定）または正式名 `grok-imagine-video-1.5` を使用します。従来の `grok-imagine-video-1.5-preview` は互換 alias として受け付けます。参照数に応じて T2V(0)、I2V(1)、Ref2V(2-7、最大10秒)が自動選択され、1080p は `grok-imagine-video-1.5` の単一画像/フレーム I2V でのみ有効です。1.5 は Ref2V、V2V edit、extension を追加サポートしないため、それらは既定モデルのみです。duration(1-15s)、resolution(480p/720p/対応時 1080p)、aspect ratio を設定できます。
+
+設定画面の QuotaCard に Grok billing `$used/$limit` バーと **Switch Account** ボタン（`POST /api/auth/switch`）が表示されます。
+
 ![OAuth active と API key provider available の状態を示す settings 画面](../assets/screenshots/settings-oauth-generation.png)
 
 ## モデルの選び方
@@ -120,6 +183,7 @@ Settings ワークスペースでは、アカウント、モデル、テーマ
 | `ima2 setup` | 認証設定を再構成 |
 | `ima2 status` | config と OAuth 状態を表示 |
 | `ima2 doctor` | Node、package、config、auth を診断 |
+| `ima2 doctor image-probe [--json]` | 画像なし診断用 sanitized probe |
 | `ima2 open` | Web UI を開く |
 | `ima2 reset` | 保存済み config を削除 |
 
@@ -132,6 +196,7 @@ Settings ワークスペースでは、アカウント、モデル、テーマ
 | `ima2 gen <prompt>` | CLI から画像生成 |
 | `ima2 edit <file> --prompt <text>` | 既存画像を編集 |
 | `ima2 multimode <prompt>` | マルチイメージ SSE 生成 |
+| `ima2 video <prompt>` | Grok 動画生成（SSE 進捗） |
 | `ima2 ls [--session <id>] [--favorites]` | ローカル履歴を表示 |
 | `ima2 show <name> [--metadata]` | 生成ファイルを開く |
 | `ima2 prompt ls -q <検索>` | プロンプトライブラリ検索 |
@@ -162,9 +227,13 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_GENERATED_DIR` | `~/.ima2/generated` | Generated image directory |
 | `IMA2_IMAGE_MODEL_DEFAULT` | `gpt-5.4-mini` | Server fallback image model |
 | `IMA2_NO_OAUTH_PROXY` | — | `1` で OAuth proxy の自動起動を無効化 |
-| `IMA2_LOG_LEVEL` | `warn` | 通常の `serve` は `warn`、dev mode は `debug`。`debug`, `info`, `warn`, `error`, `silent` をサポート |
-| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `30000` | デバッグ用の recent job retention |
-| `OPENAI_API_KEY` | — | 補助機能用。画像生成用ではありません |
+| `IMA2_LOG_LEVEL` | `info` | 通常の `serve` は `info`、dev mode は `debug`。`debug`, `info`, `warn`, `error`, `silent` をサポート |
+| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `300000` | デバッグ用の recent job retention |
+| `OPENAI_API_KEY` | — | `provider: "api"` の Responses 画像パスと補助機能用 |
+| `XAI_API_KEY` | — | `provider: "grok-api"` 直接 xAI Images API |
+| `GEMINI_API_KEY` | — | `provider: "gemini-api"` Generative Language API |
+| `VERTEX_SERVICE_ACCOUNT_JSON` | — | Vertex AI サービスアカウント JSON（API キーより優先） |
+| `IMA2_AGY_BIN` | PATH の `agy` | `provider: "agy"` バイナリパス |
 
 ### Logging modes
 
@@ -186,9 +255,15 @@ Endpoint 一覧は [API Reference](API.md) に分離しました。
 **OAuth login がうまくいかない**
 `ima2 setup` を再実行（オプション 1）し、`ima2 status` を確認してから `ima2 serve` を再起動してください。
 
+**proxy/VPN 環境で `fetch failed` が繰り返される**
+ローカル OAuth proxy に到達できるか確認してください。プロキシ必須のネットワークでは、プロキシクライアントの TUN/TURN 系モードを有効にしてから `openai-oauth --port 10531` を再試行してください。それでも失敗する場合は、`ima2 serve` や `openai-oauth` を実行する同じ terminal で `HTTP_PROXY` と `HTTPS_PROXY` を設定してください。Windows では SecretDNS など DNS/断片化バイパス系ツールが OAuth やストリーミング画像応答を壊すことがあります。
+
 **画像生成が `API_KEY_REQUIRED` で失敗する**
 `provider: "api"` request に使う API key が設定されていません。API key を設定するか OAuth provider に切り替えてください。
 
+**画像生成が `EMPTY_RESPONSE` になる、または画像データが返らない**
+`ima2 doctor image-probe --json > ima2-image-probe.json` を実行し、issue 作成時に安全な JSON を添付してください。GPT OAuth の場合は、`ima2 serve` 実行中に `ima2 gen "猫" --no-web-search --json` と `ima2 gen "猫" --json` も取得してください。ChatGPT cookie、OAuth トークンファイル、API key、生の upstream 応答、プロンプト履歴、生成 base64 は共有しないでください。詳細は [FAQ サポートバンドル](FAQ.md#what-should-i-share-when-oauth-image-generation-returns-no-image) を参照してください。
+
 **大きな参照画像が失敗する**
 JPEG/PNG は送信前に自動圧縮されます。それでも失敗する場合は、解像度を下げた JPEG/PNG に変換してください。HEIC/HEIF は browser path ではサポートしていません。
 
@@ -198,8 +273,11 @@ JPEG/PNG は送信前に自動圧縮されます。それでも失敗する場
 **`gpt-5.5` だけ失敗する**
 まず Codex CLI を最新版に更新してから再試行してください。それでも失敗する場合は、現在のアカウントやバックエンド経路で `gpt-5.5` の image capability または使用量枠がまだ異なる可能性があります。安定した代替として `gpt-5.4` を使ってください。
 
-**Port が突然 `3457` になる**
-別のローカルツールから `PORT=3457` が引き継がれている可能性があります。`unset PORT` するか、`IMA2_PORT=3333 ima2 serve` で起動してください。
+**別のポートでアプリが開く**
+要求した server ポートが使用中の場合、ima2-gen は次の空きポートに fallback し、`~/.ima2/server.json` に記録します。ポートが想定外の `3457` になる場合、shell が別ツールの `PORT=3457` を引き継いでいる可能性があります。`unset PORT` するか、`IMA2_PORT=3333 ima2 serve` で起動してください。
+
+**Windows でポート `10531` が既に使われている**
+Windows のセキュリティツール（`AnySign4PC.exe` など）が既定 OAuth proxy ポートを占有することがあります。現在のビルドは実際の fallback OAuth ポートを追跡します。手動上書きが必要な場合は `IMA2_OAUTH_PROXY_PORT=11531 ima2 serve` で起動し、`ima2 doctor` で確認してください。
 
 より詳しい確認手順は [FAQ](FAQ.md) を参照してください。