ima2-gen 1.1.14 → 1.1.17

package/config.js

@@ -164,6 +164,22 @@ export const config = {
         defaultSize: pickStr(env.IMA2_API_IMAGE_SIZE, fileCfg.apiProvider?.defaultSize, "1024x1024"),
         allowWebSearch: pickBool(env.IMA2_API_ALLOW_WEB_SEARCH, fileCfg.apiProvider?.allowWebSearch, true),
     },
+    grokProvider: {
+        proxyPort: pickInt(env.IMA2_GROK_PROXY_PORT, fileCfg.grokProvider?.proxyPort, 18645),
+        proxyHost: pickStr(env.IMA2_GROK_PROXY_HOST, fileCfg.grokProvider?.proxyHost, "127.0.0.1"),
+        autoStart: !pickBool(env.IMA2_NO_GROK_PROXY, fileCfg.grokProvider?.disableAutoStart, false),
+        restartDelayMs: pickInt(env.IMA2_GROK_RESTART_DELAY_MS, fileCfg.grokProvider?.restartDelayMs, 2000),
+        plannerModel: pickStr(env.IMA2_GROK_PLANNER_MODEL, fileCfg.grokProvider?.plannerModel, "grok-4.3"),
+        plannerTimeoutMs: pickInt(env.IMA2_GROK_PLANNER_TIMEOUT_MS, fileCfg.grokProvider?.plannerTimeoutMs, 60_000),
+        defaultImageModel: pickStr(env.IMA2_GROK_IMAGE_MODEL_DEFAULT, fileCfg.grokProvider?.defaultImageModel, "grok-imagine-image"),
+        generationTimeoutMs: pickInt(env.IMA2_GROK_GENERATION_TIMEOUT_MS, fileCfg.grokProvider?.generationTimeoutMs, 120_000),
+        statusTimeoutMs: pickInt(env.IMA2_GROK_STATUS_TIMEOUT_MS, fileCfg.grokProvider?.statusTimeoutMs, 3000),
+        defaultVideoModel: pickStr(env.IMA2_GROK_VIDEO_MODEL_DEFAULT, fileCfg.grokProvider?.defaultVideoModel, "grok-imagine-video"),
+        videoStartTimeoutMs: pickInt(env.IMA2_GROK_VIDEO_START_TIMEOUT_MS, fileCfg.grokProvider?.videoStartTimeoutMs, 60_000),
+        videoPollIntervalMs: pickInt(env.IMA2_GROK_VIDEO_POLL_INTERVAL_MS, fileCfg.grokProvider?.videoPollIntervalMs, 5_000),
+        videoTimeoutMs: pickInt(env.IMA2_GROK_VIDEO_TIMEOUT_MS, fileCfg.grokProvider?.videoTimeoutMs, 900_000),
+        videoDownloadTimeoutMs: pickInt(env.IMA2_GROK_VIDEO_DOWNLOAD_TIMEOUT_MS, fileCfg.grokProvider?.videoDownloadTimeoutMs, 120_000),
+    },
     log: {
         level: pickStr(env.IMA2_LOG_LEVEL, fileCfg.log?.level, defaultLogLevelForEnv(env)),
         pretty: env.NODE_ENV !== "production",

package/config.ts

@@ -277,6 +277,22 @@ export const config = {
     defaultSize: pickStr(env.IMA2_API_IMAGE_SIZE, fileCfg.apiProvider?.defaultSize, "1024x1024"),
     allowWebSearch: pickBool(env.IMA2_API_ALLOW_WEB_SEARCH, fileCfg.apiProvider?.allowWebSearch, true),
   },
+  grokProvider: {
+    proxyPort: pickInt(env.IMA2_GROK_PROXY_PORT, fileCfg.grokProvider?.proxyPort, 18645),
+    proxyHost: pickStr(env.IMA2_GROK_PROXY_HOST, fileCfg.grokProvider?.proxyHost, "127.0.0.1"),
+    autoStart: !pickBool(env.IMA2_NO_GROK_PROXY, fileCfg.grokProvider?.disableAutoStart, false),
+    restartDelayMs: pickInt(env.IMA2_GROK_RESTART_DELAY_MS, fileCfg.grokProvider?.restartDelayMs, 2000),
+    plannerModel: pickStr(env.IMA2_GROK_PLANNER_MODEL, fileCfg.grokProvider?.plannerModel, "grok-4.3"),
+    plannerTimeoutMs: pickInt(env.IMA2_GROK_PLANNER_TIMEOUT_MS, fileCfg.grokProvider?.plannerTimeoutMs, 60_000),
+    defaultImageModel: pickStr(env.IMA2_GROK_IMAGE_MODEL_DEFAULT, fileCfg.grokProvider?.defaultImageModel, "grok-imagine-image"),
+    generationTimeoutMs: pickInt(env.IMA2_GROK_GENERATION_TIMEOUT_MS, fileCfg.grokProvider?.generationTimeoutMs, 120_000),
+    statusTimeoutMs: pickInt(env.IMA2_GROK_STATUS_TIMEOUT_MS, fileCfg.grokProvider?.statusTimeoutMs, 3000),
+    defaultVideoModel: pickStr(env.IMA2_GROK_VIDEO_MODEL_DEFAULT, fileCfg.grokProvider?.defaultVideoModel, "grok-imagine-video"),
+    videoStartTimeoutMs: pickInt(env.IMA2_GROK_VIDEO_START_TIMEOUT_MS, fileCfg.grokProvider?.videoStartTimeoutMs, 60_000),
+    videoPollIntervalMs: pickInt(env.IMA2_GROK_VIDEO_POLL_INTERVAL_MS, fileCfg.grokProvider?.videoPollIntervalMs, 5_000),
+    videoTimeoutMs: pickInt(env.IMA2_GROK_VIDEO_TIMEOUT_MS, fileCfg.grokProvider?.videoTimeoutMs, 900_000),
+    videoDownloadTimeoutMs: pickInt(env.IMA2_GROK_VIDEO_DOWNLOAD_TIMEOUT_MS, fileCfg.grokProvider?.videoDownloadTimeoutMs, 120_000),
+  },
   log: {
     level: pickStr(env.IMA2_LOG_LEVEL, fileCfg.log?.level, defaultLogLevelForEnv(env)),
     pretty: env.NODE_ENV !== "production",

package/docs/API.md

@@ -10,14 +10,21 @@ http://localhost:3333
 
 ## Provider Policy
 
-Image generation supports both OAuth and API-key providers.
+Image generation supports OAuth, API-key, and Grok 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.
 - 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`.
 - Mask edits are mask/selection guided edits, not pixel-perfect inpaint guarantees.
 
+Grok video generation (T2V/I2V) is not part of the `1.1.15` runtime API. The
+`docs/grok-video-i2v-plan.md` and `docs/grok-video-i2v-research.md` files are
+planning and research notes only; no `/api/video` route or Grok video endpoint
+wrapper is shipped in this release.
+
 ## Health And Status
 
 | Method | Path | Notes |
@@ -25,6 +32,7 @@ Image generation supports both OAuth and API-key providers.
 | `GET` | `/api/health` | Server health, version, paths, provider policy |
 | `GET` | `/api/providers` | Provider availability and runtime ports |
 | `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 |
 
 ## Storage
@@ -104,12 +112,60 @@ Supported moderation values: `auto`, `low`.
 
 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
+`grok-imagine-image-quality`. The server uses `grok-4.3` as the search/planner
+model by default (`IMA2_GROK_PLANNER_MODEL`) and times the mandatory search and
+planner steps separately from the image call (`IMA2_GROK_PLANNER_TIMEOUT_MS`).
+For `n > 1`, search and planning run once and the planned prompt is reused for
+the image requests. Successful Grok classic generations report one mandatory
+web-search call in metadata.
+
+If `references` are present on a Grok classic request, ima2 still performs the
+mandatory search and `grok-4.3` planning phases. The planner receives the
+reference images as multimodal `image_url` inputs, and its forced
+`generate_image.prompt` argument is instructed to be English-only except for
+exact visible text requested by the user. The final image call then uses xAI
+`/v1/images/edits` with the same reference images instead of
+`/v1/images/generations`. This keeps image-to-image/reference context alive
+through the three-phase pipeline. xAI currently documents up to three source
+images for image editing, so Grok classic requests with more than three
+references return `GROK_REF_TOO_MANY`.
+
+Grok size mapping:
+
+| Requested size | xAI `aspect_ratio` | xAI `resolution` |
+|---|---|---|
+| `1024x1024` | `1:1` | `1k` |
+| `1536x1024` | `3:2` | `1k` |
+| `1024x1536` | `2:3` | `1k` |
+| `1360x1024` | `4:3` | `1k` |
+| `1024x1360` | `3:4` | `1k` |
+| `1824x1024` | `16:9` | `1k` |
+| `1024x1824` | `9:16` | `1k` |
+| `2048x2048` | `1:1` | `2k` |
+| `2048x1152` | `16:9` | `2k` |
+| `1152x2048` | `9:16` | `2k` |
+| `3840x2160` | `16:9` | `2k` |
+| `2160x3840` | `9:16` | `2k` |
+| `auto` | `auto` | omitted |
+
+Custom sizes are reduced to the closest xAI-supported aspect ratio and use
+`2k` when the requested longest edge or pixel budget is closer to a 2K image.
+
 ### `POST /api/edit`
 
 Image edit / image-to-image generation.
 
 The request includes a prompt and image payload. `provider: "api"` sends the prompt and image through the shared Responses image adapter. Optional masks are forwarded as mask guidance, not a pixel-perfect edit guarantee.
 
+With `provider: "grok"`, edit requests are sent to xAI `/v1/images/edits`
+through the bundled progrok proxy. Masked Grok edits are rejected before
+upstream with `GROK_MASK_UNSUPPORTED`.
+
+Grok multimode currently sends each image request directly to xAI Images API
+with the mapped `aspect_ratio`/`resolution`; the mandatory search + planner
+pipeline is limited to classic `/api/generate`.
+
 ### `POST /api/node/generate`
 
 Node-mode generation and child edits.
@@ -124,20 +180,24 @@ Body fields:
   "size": "1024x1024",
   "format": "png",
   "moderation": "low",
-  "model": "gpt-5.4",
+  "model": "grok-imagine-image",
   "references": [],
   "externalSrc": "optional-history-url",
   "sessionId": "session-id",
   "clientNodeId": "client-node-id",
   "requestId": "request-id",
-  "provider": "oauth"
+  "provider": "grok"
 }
 ```
 
 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.
 
+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`.
 
+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.
+
 ### `GET /api/node/:nodeId`
 
 Fetch stored node metadata and asset URL.
@@ -156,6 +216,8 @@ Server-side validation may return these reference codes:
 | `REF_EMPTY` | A reference item was empty |
 | `REF_TOO_LARGE` | A reference exceeded the configured base64 size |
 | `REF_NOT_BASE64` | A reference was not valid base64 |
+| `GROK_REF_TOO_MANY` | Grok classic generation received more than three reference images |
+| `GROK_MASK_UNSUPPORTED` | Grok edit was requested with a mask; xAI mask edit is not wired in this release |
 
 ## History
 
@@ -223,16 +285,20 @@ Style-sheet extraction can require an API key/openai client. Image generation al
 | `GRAPH_VERSION_CONFLICT` | Stale graph version |
 | `GRAPH_TOO_LARGE` | Graph exceeds node/edge limits |
 | `NODE_NOT_FOUND` | Node metadata was not found |
+| `INVALID_GROK_IMAGE_MODEL` | A Grok request used a model outside `grok-imagine-image` or `grok-imagine-image-quality` |
+| `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 |
 
 ## Endpoint → CLI Mapping
 
-As of 0.09.x, every server route under `/api/*` has a CLI wrapper. Use this table to find the command that calls a given endpoint. (See README.md "Client" section for full flag lists.)
+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.)
 
 | Endpoint | CLI |
 |---|---|
 | `POST /api/generate` | `ima2 gen` |
 | `POST /api/edit` | `ima2 edit` |
-| `POST /api/generate/multi` (SSE) | `ima2 multimode` |
+| `POST /api/generate/multimode` (SSE) | `ima2 multimode` |
 | `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]` |
@@ -246,14 +312,17 @@ As of 0.09.x, every server route under `/api/*` has a CLI wrapper. Use this tabl
 | `GET/PUT/DELETE /api/annotations/:name` | `ima2 annotate get/set/rm` |
 | `POST /api/canvas-versions` / `PUT /api/canvas-versions/:name` | `ima2 canvas-versions save/update` |
 | `GET/POST/PUT/DELETE /api/prompts[/…]` | `ima2 prompt …` |
-| `GET/POST/PUT/DELETE /api/prompt-folders[/…]` | `ima2 prompt folder …` |
-| `…/api/prompt-import/…` | `ima2 prompt import sources/refresh/curated/discovery/folder` |
+| `GET/POST/PATCH/DELETE /api/prompts/folders[/…]` | `ima2 prompt folder …` |
+| `…/api/prompts/import/…` | `ima2 prompt import sources/refresh/curated/discovery/folder` |
 | `…/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/storage/status` / `POST /api/storage/open-generated-dir` | `ima2 storage status` / `ima2 storage open` |
-| `GET /api/billing` / `GET /api/providers` / `GET /api/oauth/status` | `ima2 billing` / `ima2 providers` / `ima2 oauth status` |
+| `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/health` | `ima2 ping` |
+| `GET /api/capabilities` | `ima2 capabilities` |
+| `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.

package/docs/CLI.md

@@ -1,6 +1,6 @@
 # CLI Reference
 
-Every server route under `/api/*` has a CLI wrapper. 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`, `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`, 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).
 
@@ -14,6 +14,7 @@ For a quick start, see the [main README](../README.md). For endpoint mapping, se
 | `ima2 doctor` | Diagnose Node, package, config, and auth |
 | `ima2 doctor image-probe [--json]` | Run live sanitized Responses image probes for `EMPTY_RESPONSE` support |
 | `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 |
 
 ## Common flags
@@ -51,16 +52,36 @@ 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>`, `--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>`, `--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.
 - `auto` preserves route default behavior and currently resolves to OAuth unless server routing changes.
 
+`ima2 serve` starts the bundled Grok proxy automatically. No separate `progrok`
+install is required. Use `ima2 grok login` once to authorize xAI OAuth, or
+`ima2 grok login --device-code` on a remote shell. Set `IMA2_NO_GROK_PROXY=1`
+only if you want to manage the proxy yourself.
+
+Grok size mapping follows xAI's image API, not OpenAI's `size` field. ima2
+keeps the requested size in local metadata, but sends `aspect_ratio` such as
+`1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, or `2:3`, plus `resolution:
+"1k"` or `"2k"` where applicable. The 3840 presets map to `resolution: "2k"`
+because xAI currently exposes `1k` and `2k` resolution controls.
+
+For Grok classic generation with `--ref`, ima2 sends up to three references into
+the `grok-4.3` planner as image inputs, asks the planner for an English final
+image prompt, then sends the same references to xAI image editing. More than
+three Grok references are rejected with `GROK_REF_TOO_MANY`, matching xAI's
+documented multi-image editing limit.
+
 ```bash
 ima2 gen "a poster of a samurai cat" --model gpt-5.4 --provider api --reasoning-effort high
+ima2 grok login
+ima2 gen "a cinematic neon city" --provider grok --model grok-imagine-image-quality
 ima2 edit input.png --prompt "make it rainy" --provider oauth --web-search
 ima2 multimode "two cats playing" --max-images 2 --ref cat.png --mode direct
 ima2 node generate --node n_abc --prompt "add neon lights" --no-stream
@@ -82,7 +103,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>`, 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>`, 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.
 
 ## Diagnostics
 
@@ -169,6 +190,8 @@ Windows DNS/fragmentation bypass tool such as SecretDNS is in use.
 | `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 |
+| `ima2 prompt build --message <text> [--ref <file>] [--model <id>] [--json]` | Build a structured image prompt through `/api/prompt-builder/chat` |
+| `ima2 prompt build --messages <file\|@file\|-> [--json]` | Build from a message transcript file or stdin |
 
 ## Card News (gated)
 
@@ -199,6 +222,7 @@ Card News requires the server to be started with `IMA2_CARD_NEWS=1` (or `feature
 | `ima2 billing` | API usage / quota |
 | `ima2 providers` | Configured providers |
 | `ima2 oauth status` | OAuth proxy state |
+| `ima2 grok status` | Bundled progrok / xAI image-model probe state |
 | `ima2 ping` | Health-check the running server |
 
 ## Config
@@ -231,6 +255,8 @@ Allowed keys (whitelist):
 ```
 imageModels.default          imageModels.reasoningEffort
 apiProvider.defaultImageModel apiProvider.defaultReasoningEffort
+grokProvider.plannerModel     grokProvider.plannerTimeoutMs
+grokProvider.defaultImageModel
 log.level                    features.cardNews
 cardNewsPlanner.{enabled,model,timeoutMs,deterministicFallback}
 comfy.{defaultUrl,uploadTimeoutMs,maxUploadBytes}

package/docs/README.ko.md

@@ -6,11 +6,13 @@
 
 > 🌐 **Live site**: [lidge-jun.github.io/ima2-gen](https://lidge-jun.github.io/ima2-gen/) · [한국어 페이지](https://lidge-jun.github.io/ima2-gen/ko/)
 >
+> 📖 **개발자 문서**: [문서 사이트](https://lidge-jun.github.io/ima2-gen/ko/docs) · [English](https://lidge-jun.github.io/ima2-gen/docs)
+>
 > **다른 언어로 읽기**: [English](../README.md) · [日本語](README.ja.md) · [简体中文](README.zh-CN.md)
 
 `ima2-gen`은 ChatGPT/Codex OAuth 이미지 생성 흐름을 로컬 웹앱처럼 쓸 수 있게 만든 이미지 생성 스튜디오입니다.
 
-`npx`로 실행하고, Codex OAuth로 로그인한 뒤, 프롬프트를 입력하면서 히스토리, 레퍼런스, 노드 브랜치, 멀티모드 배치, Canvas Mode 정리 작업으로 계속 이어갈 수 있습니다. 기본 이미지 생성 경로에서는 OpenAI API 키가 필요하지 않습니다.
+`npx`로 실행하고, Codex OAuth로 로그인한 뒤, 프롬프트를 입력하면서 히스토리, 레퍼런스, 노드 브랜치, 멀티모드 배치, Canvas Mode 정리 작업으로 계속 이어갈 수 있습니다. 기본 이미지 생성 경로에서는 OpenAI API 키가 필요하지 않으며, 설정된 경우 OpenAI API-key 경로와 번들 Grok 경로도 사용할 수 있습니다.
 
 ![프롬프트 작성창, 생성 이미지, 모델 표시, 결과 메타데이터가 보이는 ima2-gen 클래식 생성 화면](../assets/screenshots/classic-generate-light.png)
 
@@ -50,13 +52,19 @@ ima2 serve
 - **Mobile shell**: 작은 화면에서는 app bar, compose sheet, compact settings toggle로 조작합니다.
 - **Observable jobs**: 진행 중인 작업과 최근 완료된 작업을 request ID로 추적합니다.
 
-## 이미지 생성은 OAuth와 API Key를 지원합니다
+## 이미지 생성 공급자
+
+이미지 생성은 로컬 Codex/ChatGPT OAuth, OpenAI API key, 번들 Grok 공급자를 지원합니다.
+
+- `provider: "oauth"`는 로컬 Codex OAuth 프록시를 사용합니다.
+- `provider: "api"`는 OpenAI Responses API의 `image_generation` 도구를 사용합니다.
+- `provider: "grok"`는 번들 `progrok`을 `127.0.0.1:18645`에서 띄우고, xAI Web Search와 `grok-4.3` planner를 거친 뒤 xAI Images API를 호출합니다.
 
-기본 이미지 생성은 로컬 Codex/ChatGPT OAuth 경로로 실행됩니다.
+Grok은 Classic, Node, Agent 흐름을 지원합니다. Classic 레퍼런스, Node 부모 이미지, Agent 현재 이미지가 있으면 최종 Grok 호출은 xAI image edit 경로로 전환되어 image-to-image 맥락을 유지합니다. 기본 모델은 `grok-imagine-image`이고, `quality: "high"`에서는 `grok-imagine-image-quality`를 사용합니다.
 
-API 키가 env/config에 있으면 생성 엔드포인트에서 `provider: "api"`를 보내 Responses API `image_generation` 도구를 사용할 수 있습니다.
+Grok video 생성(T2V/I2V)은 `1.1.15`에 포함되지 않았습니다. `docs/grok-video-i2v-plan.md`와 `docs/grok-video-i2v-research.md`는 구현 계획과 조사 문서이며, 공개 런타임은 아직 이미지 생성만 지원합니다.
 
-설정 화면에 **API key provider available**이 보이면, API 키가 감지됐고 생성/편집/멀티모드/노드 요청에 사용할 수 있다는 뜻입니다.
+설정 화면에 **API key provider available**이나 **Grok provider available**이 보이면 해당 공급자가 감지됐고 생성 요청에 사용할 수 있다는 뜻입니다.
 
 ![OAuth 활성화와 API 키 비활성 상태를 보여주는 설정 화면](../assets/screenshots/settings-oauth-generation.png)
 
@@ -176,9 +184,14 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_GENERATED_DIR` | `~/.ima2/generated` | 생성 이미지 저장 위치 |
 | `IMA2_IMAGE_MODEL_DEFAULT` | `gpt-5.4-mini` | 서버 fallback 이미지 모델 |
 | `IMA2_NO_OAUTH_PROXY` | — | `1`이면 OAuth 프록시 자동 시작 비활성화 |
+| `IMA2_GROK_PROXY_HOST` | `127.0.0.1` | 번들 progrok 프록시 host |
+| `IMA2_GROK_PROXY_PORT` | `18645` | 번들 progrok 프록시 port |
+| `IMA2_NO_GROK_PROXY` | — | `1`이면 progrok 자동 시작 비활성화 |
+| `IMA2_GROK_PLANNER_MODEL` | `grok-4.3` | 최종 이미지 호출 전 Grok 검색/planner 모델 |
+| `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` | 디버그용 최근 작업 보존 시간 |
-| `OPENAI_API_KEY` | — | 보조 기능용 API 키. 이미지 생성용은 아님 |
+| `OPENAI_API_KEY` | — | `provider: "api"` Responses 이미지 경로와 보조 기능용 API 키 |
 
 ### 로그 모드