ima2-gen 1.1.20 → 1.1.22

package/docs/API.md

@@ -234,6 +234,8 @@ Generate a video via the Grok video provider. Returns Server-Sent Events.
   "sourceImage": "<base64>",
   "referenceImages": ["<base64>", "<base64>"],
   "referenceFilenames": ["existing-file.png"],
+  "continueFromVideo": "1780226256355_50252101.mp4",
+  "continuityLineage": { "lineageId": "optional-client-hint", "entries": [] },
   "sessionId": "optional",
   "requestId": "optional-client-id"
 }
@@ -263,16 +265,67 @@ Generate a video via the Grok video provider. Returns Server-Sent Events.
 | `sourceFilename` | string | — | Existing generated file for image-to-video |
 | `referenceImages` | string[] | — | Base64 images for reference-to-video |
 | `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 |
+
+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.
+
+When `continueFromVideo` is present, the server treats the generated `.mp4`
+sidecar as authoritative. Client `continuityLineage` cannot override it. The
+saved child sidecar includes `videoContinuity`, a branch-local max-4 stack using
+`keep-start-plus-latest-3` retention.
+
+`videoContinuity` shape:
+
+```json
+{
+  "lineageId": "lineage:parent",
+  "parentFilename": "parent.mp4",
+  "sourceFrame": "last",
+  "maxEntries": 4,
+  "retention": "keep-start-plus-latest-3",
+  "entries": [
+    {
+      "id": "clip:parent.mp4",
+      "ordinal": 1,
+      "role": "start",
+      "filename": "parent.mp4",
+      "userPrompt": "original user prompt",
+      "revisedPrompt": "planner prompt actually sent to Grok video",
+      "createdAt": 1780300000000
+    }
+  ]
+}
+```
+
+Entry `role` is `start`, `ancestor`, `parent`, or `current`. The first clip is
+kept as the start anchor; later generations keep only the latest three entries.
+`lineageId` uses the generated video basename without the `.mp4` extension.
+This metadata is stored in the generated `.mp4.json` sidecar and returned in
+history rows and video `done` events; `/generated/*.json` remains private.
+
+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 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. |
 
 **SSE events**:
 
 | Event | Data | Description |
 |---|---|---|
 | `planning` | `{ requestId }` | Preparing video generation |
-| `submitted` | `{ requestId, xaiVideoRequestId }` | Submitted to xAI |
+| `submitted` | `{ requestId, xaiVideoRequestId, requestedModel, effectiveModel, modelFallback }` | Submitted to xAI |
 | `progress` | `{ requestId, progress, stalled }` | Progress 0.0–1.0 |
-| `done` | `{ requestId, filename, url, mediaType, revisedPrompt, elapsed, usage, video }` | Video ready |
-| `error` | `{ error, code, status, requestId }` | Generation failed |
+| `done` | `{ requestId, filename, url, mediaType, revisedPrompt, elapsed, usage, requestedModel, effectiveModel, modelFallback, video, videoContinuity }` | Video ready |
+| `error` | `{ error, code, status, requestId, guidance? }` | Generation failed |
 
 **Video error codes**:
 
@@ -286,6 +339,57 @@ Generate a video via the Grok video provider. Returns Server-Sent Events.
 | `INVALID_VIDEO_DURATION` | Duration not 1–15 integer |
 | `GROK_VIDEO_REF_TOO_MANY` | More than 7 reference images |
 | `GROK_VIDEO_FAILED` | Upstream xAI video generation failed |
+| `GROK_VIDEO_FRAME_FAILED` | Server could not extract the parent video's last frame |
+
+### `POST /api/video/edit`
+
+Edit an existing video via Grok V2V. This is a blocking JSON endpoint that starts the xAI edit job, polls it, downloads the final MP4, and saves it as a generated video artifact.
+
+```json
+{
+  "prompt": "make it sunset",
+  "videoUrl": "https://vidgen.x.ai/.../clip.mp4",
+  "model": "grok-imagine-video"
+}
+```
+
+`videoUrl` may be an HTTPS video URL, xAI `file_id`, `data:video/*` URL, or generated `.mp4` filename. Generated-file inputs are restricted to real `.mp4` files under the generated directory.
+
+### `POST /api/video/extend`
+
+Extend a video from its last frame. This is a blocking JSON endpoint that starts the xAI extension job, polls it, downloads the combined output MP4, and saves it as a generated video artifact.
+
+```json
+{
+  "prompt": "camera pulls back",
+  "videoUrl": "1780226256355_50252101.mp4",
+  "duration": 6,
+  "model": "grok-imagine-video"
+}
+```
+
+`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.
+
+### `GET /api/video/frame`
+
+Extract a PNG frame from a generated `.mp4` file.
+
+| Query | Notes |
+|---|---|
+| `file` | Required generated `.mp4` filename or generated-dir absolute path |
+| `position` | `last` (default) or non-negative seconds |
+
+### `POST /api/video/analyze`
+
+Analyze first and last frames from a generated `.mp4` using Grok 4.3 image understanding. This does not upload the video as temporal video; it extracts two PNG frames and asks the vision model to infer likely motion.
+
+```json
+{
+  "videoUrl": "1780226256355_50252101.mp4"
+}
+```
+
+Remote URLs and `data:` inputs are intentionally rejected to avoid server-side URL fetching through `ffmpeg`.
 
 ## History
 
@@ -368,6 +472,11 @@ Most server routes under `/api/*` have a CLI wrapper. The exception is **Agent M
 | `POST /api/edit` | `ima2 edit` |
 | `POST /api/generate/multimode` (SSE) | `ima2 multimode` |
 | `POST /api/video/generate` (SSE) | `ima2 video` |
+| `POST /api/video/generate` with `continueFromVideo` | `ima2 video continue` |
+| `POST /api/video/edit` | `ima2 video edit` |
+| `POST /api/video/extend` | `ima2 video extend` |
+| `GET /api/video/frame` | `ima2 video frame` |
+| `POST /api/video/analyze` | `ima2 video analyze` |
 | `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]` |

package/docs/CLI.md

@@ -60,12 +60,13 @@ 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.
+- `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`
-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.
+install is required. Use `ima2 grok login` once to authorize xAI OAuth. Login
+defaults to `--manual-paste` so PowerShell, Terminal, and remote shells all use
+the same copy/paste flow. 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
@@ -111,8 +112,13 @@ Multimode-specific flags include `--max-images <1..8>`, `--ref <file>` (repeatab
 | Command | Description |
 |---|---|
 | `ima2 video <prompt>` | Generate a video via Grok (SSE streaming with progress) |
+| `ima2 video edit <prompt> --video <value>` | Edit an existing video (V2V); saves the result as a generated video artifact |
+| `ima2 video extend <prompt> --video <value> [--duration 6]` | Extend an existing video from its last frame |
+| `ima2 video continue <prompt> --video <generated-file>` | Generate a new clip from a generated video's last frame with branch-local `revisedPrompt` lineage |
+| `ima2 video frame <generated-file> [--last] [-o frame.png]` | Extract a PNG frame from a generated `.mp4` |
+| `ima2 video analyze <generated-file>` | Analyze first/last frames from a generated `.mp4` with Grok 4.3 vision |
 
-Video flags:
+Video generate flags:
 
 | Flag | Meaning |
 |---|---|
@@ -126,6 +132,34 @@ Video flags:
 | `--timeout <sec>` | Timeout in seconds (default: 600) |
 | `--session <id>` | Session ID |
 
+Blank video prompts are rejected. Prompts should include visual flow, camera or
+subject motion, sound/no-music intent, dialogue/no-dialogue intent, ending
+frame, and duration pacing. The selected seconds should feel naturally filled:
+opening composition, connected motion/emotion change, then a stable ending
+frame. Example: `from the last frame, she turns toward camera, rain grows
+louder, no background music, says "기다려", use the full duration for the turn
+and rain build, end on a still close-up after the line finishes`.
+
+Video edit/extend flags:
+
+| Flag | Meaning |
+|---|---|
+| `--video <value>` | Source video HTTPS URL, xAI `file_id`, data URL, or generated filename |
+| `--duration <2..10>` | Extension duration only (default: 6) |
+| `-o, --out <file>` | Download the edited or extended video to a file |
+| `--json` | Print JSON result |
+| `--timeout <sec>` | Timeout in seconds (default: 600) |
+
+Video continue flags:
+
+| Flag | Meaning |
+|---|---|
+| `--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) |
+| `--aspect-ratio <ratio\|auto>` | New clip aspect ratio |
+| `--model <name>` | Optional video generation model |
+
 Video mode is auto-detected from `--ref` count:
 
 | Refs | Mode |
@@ -134,15 +168,35 @@ 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.
+
 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 "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-1.5-preview
+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
+ima2 video extend "camera slowly pulls back" --video 1780226256355_50252101.mp4 --duration 6
+ima2 video continue "from the last frame, the actor crosses the room, footsteps only, no dialogue, end on the door closing" --video 1780226256355_50252101.mp4
+ima2 video frame 1780226256355_50252101.mp4 --last -o lastframe.png
+ima2 video analyze 1780226256355_50252101.mp4 --json
 ```
 
+Edit/extend accept HTTPS URLs, xAI `file_id`, `data:video/*` URLs, or generated `.mp4` filenames. Generated-file inputs are limited to real `.mp4` files under the generated directory. `ima2 video continue`, `ima2 video analyze`, and `ima2 video frame` intentionally accept generated `.mp4` files only; remote analysis URLs are rejected so the server does not fetch arbitrary URLs through `ffmpeg`.
+
+`ima2 video continue` differs from `ima2 video extend`: `extend` calls xAI's
+native extension endpoint and returns a combined original+extension video.
+`continue` calls ima2 generation with the parent video's server-extracted last
+frame and persists a `videoContinuity` stack of up to four `revisedPrompt`
+entries (`keep-start-plus-latest-3`) for future continuations.
+
+JSON output note: `ima2 video --json` wraps the final result with local
+download fields such as `ok`, `path`, and `filename`. `ima2 video continue
+--json` prints the server SSE `done` payload directly, including `filename`,
+`url`, `video`, `revisedPrompt`, and `videoContinuity`.
+
 ## Diagnostics
 
 `ima2 doctor image-probe` runs live Responses probes that help classify image
@@ -164,7 +218,7 @@ codes, event counts, tool-call summaries, byte counts, provider/model labels,
 and probe statuses. It does not include prompt text, auth tokens, URLs with
 credentials, raw upstream responses, or base64 image data.
 
-For OAuth no-image reports, a useful support bundle is:
+For GPT OAuth no-image reports, a useful support bundle is:
 
 ```bash
 ima2 doctor

package/docs/FAQ.ko.md

@@ -2,7 +2,7 @@
 
 마지막 확인: 2026-05-26
 
-이 문서는 설치, 업데이트, OAuth, 갤러리, 레퍼런스 이미지 관련 질문을 모아둔 FAQ입니다. README는 짧게 유지하고, 자세한 설명은 이곳에 둡니다.
+이 문서는 설치, 업데이트, GPT OAuth, 갤러리, 레퍼런스 이미지 관련 질문을 모아둔 FAQ입니다. README는 짧게 유지하고, 자세한 설명은 이곳에 둡니다.
 
 English version: [FAQ.md](FAQ.md)
 
@@ -11,8 +11,8 @@ English version: [FAQ.md](FAQ.md)
 | 증상 | 먼저 해볼 것 |
 |---|---|
 | 서버에 연결되지 않음 | `ima2 serve`를 켠 뒤 `ima2 ping`을 실행합니다. |
-| OAuth 로그인이 안 됨 | `npx @openai/codex login`을 실행하고 `ima2 serve`를 다시 시작합니다. |
-| API key provider가 `API_KEY_REQUIRED`를 반환함 | API 키를 설정하거나 OAuth 공급자로 다시 전환합니다. |
+| GPT OAuth 로그인이 안 됨 | `ima2 setup`을 다시 실행하고(옵션 1) `ima2 serve`를 다시 시작합니다. |
+| API key provider가 `API_KEY_REQUIRED`를 반환함 | API 키를 설정하거나 GPT OAuth 공급자로 다시 전환합니다. |
 | 업데이트 후 예전 이미지가 안 보임 | `ima2 doctor`를 실행한 뒤 [예전 이미지 복구 안내](RECOVER_OLD_IMAGES.md)를 확인합니다. |
 | `gpt-5.5`만 실패함 | Codex CLI를 업데이트하고, 안정 대안으로 `gpt-5.4`를 사용합니다. |
 | 레퍼런스 업로드 실패 | JPEG/PNG로 변환하고 해상도를 낮춰 보세요. 레퍼런스는 최대 5장입니다. |
@@ -27,22 +27,17 @@ English version: [FAQ.md](FAQ.md)
 
 Node.js 20 이상을 권장합니다. 패키지 요구사항은 Node `>=20`입니다.
 
-### `npx`와 전역 설치 중 무엇을 쓰면 되나요?
+### 어떻게 설치하나요?
 
-둘 다 가능합니다.
-
-```bash
-npx ima2-gen serve
-```
-
-또는:
+npm 전역 설치를 권장합니다.
 
 ```bash
 npm install -g ima2-gen
+ima2 setup
 ima2 serve
 ```
 
-예전 전역 설치가 이상하게 동작하면 먼저 최신 버전으로 올려 주세요.
+예전 설치가 이상하게 동작하면 먼저 최신 버전으로 올려 주세요.
 
 ```bash
 npm install -g ima2-gen@latest
@@ -82,10 +77,10 @@ API 키를 설정하면 이미지 생성 엔드포인트도 `provider: "api"`로
 
 ### Codex CLI에 이미 로그인되어 있으면 자동으로 잡히나요?
 
-네. `ima2-gen`은 기존 Codex 로그인 상태를 확인하고 로컬 OAuth 경로를 사용합니다. 감지에 실패하거나 토큰이 만료되면 다음을 실행하세요.
+네. `ima2-gen`은 기존 Codex 로그인 상태를 확인하고 로컬 GPT OAuth 경로를 사용합니다. 감지에 실패하거나 토큰이 만료되면 다음을 실행하세요.
 
 ```bash
-npx @openai/codex login
+ima2 setup     # 옵션 1 (GPT OAuth) 다시 실행
 ima2 doctor
 ```
 
@@ -96,7 +91,7 @@ ima2 doctor
 Codex/ChatGPT OAuth 세션을 다시 로그인해야 합니다.
 
 ```bash
-npx @openai/codex login
+ima2 setup     # 옵션 1 (GPT OAuth) 다시 실행
 ima2 serve
 ```
 
@@ -118,7 +113,7 @@ ima2 serve
 
 ### Plus/Pro는 몇 장까지 생성할 수 있나요?
 
-커뮤니티에서 말하는 숫자를 보장으로 받아들이면 안 됩니다. OAuth 생성은 계정, 백엔드 capability, 트래픽, 정책 변경의 영향을 받을 수 있습니다. `ima2-gen` 문서에서는 고정된 Plus/Pro 생성 횟수를 약속하지 않습니다.
+커뮤니티에서 말하는 숫자를 보장으로 받아들이면 안 됩니다. GPT OAuth 생성은 계정, 백엔드 capability, 트래픽, 정책 변경의 영향을 받을 수 있습니다. `ima2-gen` 문서에서는 고정된 Plus/Pro 생성 횟수를 약속하지 않습니다.
 
 ## Prompt Studio와 멀티모드
 
@@ -258,7 +253,7 @@ ima2 ping
 
 필요하면 `ima2 serve`를 다시 시작합니다.
 
-### OAuth 이미지 생성이 이미지 없이 끝나면 무엇을 공유해야 하나요?
+### GPT OAuth 이미지 생성이 이미지 없이 끝나면 무엇을 공유해야 하나요?
 
 먼저 moderation으로 단정하지 말고 image probe를 실행하세요. `EMPTY_RESPONSE`는
 Responses 경로에서 `ima2-gen`이 사용할 수 있는 이미지 데이터가 나오지 않았다는
@@ -312,7 +307,7 @@ generated base64는 공유하지 마세요.
 먼저 시도하세요.
 
 ```bash
-npx openai-oauth --port 10531
+openai-oauth --port 10531
 ```
 
 프록시가 필요한 네트워크라면 터미널 프로세스도 프록시를 타도록 프록시 클라이언트의 TUN/TURN류 모드를 켜세요. Windows에서는 SecretDNS처럼 부팅 때 자동 실행되는 DNS/파편화 우회 프로그램도 잠시 끄고 재시도해 보세요. 그래도 안 되면 `openai-oauth` 또는 `ima2 serve`를 실행하는 같은 터미널에 프록시 환경 변수를 설정합니다.
@@ -326,7 +321,7 @@ export HTTPS_PROXY=http://127.0.0.1:7890
 
 ### 회사 컴퓨터에서는 무엇을 확인해야 하나요?
 
-OAuth는 OpenAI와 ChatGPT/Codex 관련 호스트 접근이 필요할 수 있습니다. 회사 방화벽, TLS 검사, VPN, 프록시가 흐름을 깨뜨릴 수 있습니다. 로그인 실패와 `failed to fetch`가 반복되면 다른 네트워크에서도 시도해 보세요.
+GPT OAuth는 OpenAI와 ChatGPT/Codex 관련 호스트 접근이 필요할 수 있습니다. 회사 방화벽, TLS 검사, VPN, 프록시가 흐름을 깨뜨릴 수 있습니다. 로그인 실패와 `failed to fetch`가 반복되면 다른 네트워크에서도 시도해 보세요.
 
 ## CLI 점검 순서
 
@@ -337,7 +332,7 @@ ima2 doctor
 ima2 status
 ima2 ping
 ima2 ps
-npx @openai/codex login
+ima2 setup
 npm install -g ima2-gen@latest
 ```
 

package/docs/FAQ.md

@@ -11,8 +11,8 @@ For Korean, see [FAQ.ko.md](FAQ.ko.md).
 | Symptom | Try first |
 |---|---|
 | The server is unreachable | Run `ima2 serve`, then `ima2 ping`. |
-| OAuth login fails | Run `npx @openai/codex login`, then restart `ima2 serve`. |
-| API key provider says `API_KEY_REQUIRED` | Configure an API key, or switch back to the OAuth provider. |
+| GPT OAuth login fails | Re-run `ima2 setup` (option 1), then restart `ima2 serve`. |
+| API key provider says `API_KEY_REQUIRED` | Configure an API key, or switch back to the GPT OAuth provider. |
 | Old gallery images look missing | Run `ima2 doctor`, then see [Recover Old Generated Images](RECOVER_OLD_IMAGES.md). |
 | `gpt-5.5` fails | Update Codex CLI first, then try `gpt-5.4` as the stable fallback. |
 | Reference upload fails | Use JPEG/PNG, lower the resolution, and keep references to 5 images or fewer. |
@@ -27,22 +27,17 @@ For Korean, see [FAQ.ko.md](FAQ.ko.md).
 
 Use Node.js 20 or newer. The package declares Node `>=20`, and the README badge follows that requirement.
 
-### Should I use `npx` or a global install?
+### How do I install?
 
-Both are supported.
-
-```bash
-npx ima2-gen serve
-```
-
-or:
+Install globally with npm:
 
 ```bash
 npm install -g ima2-gen
+ima2 setup
 ima2 serve
 ```
 
-If an old global install behaves strangely, update first:
+If an old install behaves strangely, update first:
 
 ```bash
 npm install -g ima2-gen@latest
@@ -88,10 +83,10 @@ It means `ima2-gen` found a valid API key. API-key mode can generate, edit, run
 
 ### If Codex CLI is already logged in, does ima2-gen reuse it?
 
-Yes. `ima2-gen` checks for an existing Codex login and uses the local OAuth path. If detection fails or the token expires, run:
+Yes. `ima2-gen` checks for an existing Codex login and uses the local GPT OAuth path. If detection fails or the token expires, run:
 
 ```bash
-npx @openai/codex login
+ima2 setup     # re-run option 1 (GPT OAuth)
 ima2 doctor
 ```
 
@@ -102,7 +97,7 @@ Then restart `ima2 serve`.
 Your Codex/ChatGPT OAuth session needs to be refreshed.
 
 ```bash
-npx @openai/codex login
+ima2 setup     # re-run option 1 (GPT OAuth)
 ima2 serve
 ```
 
@@ -124,7 +119,7 @@ Start with `gpt-5.4` for the safest balanced workflow.
 
 ### How many images can Plus or Pro generate?
 
-Do not treat any community number as a guarantee. OAuth generation can be limited by account, backend capability, traffic, and policy changes. `ima2-gen` does not publish a fixed Plus/Pro image count because that number is not stable enough to document as a promise.
+Do not treat any community number as a guarantee. GPT OAuth generation can be limited by account, backend capability, traffic, and policy changes. `ima2-gen` does not publish a fixed Plus/Pro image count because that number is not stable enough to document as a promise.
 
 ## Prompt Studio and multimode
 
@@ -268,7 +263,7 @@ ima2 ping
 
 Then restart `ima2 serve` if needed.
 
-### What should I share when OAuth image generation returns no image?
+### What should I share when GPT OAuth image generation returns no image?
 
 Use the image probe before assuming moderation. `EMPTY_RESPONSE` means the
 Responses path did not produce image data that `ima2-gen` could use; it can be
@@ -323,7 +318,7 @@ This usually means the local OAuth proxy cannot reach the upstream service throu
 Try:
 
 ```bash
-npx openai-oauth --port 10531
+openai-oauth --port 10531
 ```
 
 If your network requires a proxy, enable your proxy client's TUN/TURN-style mode so terminal processes can use it. On Windows, also temporarily disable auto-start DNS or fragmentation bypass tools such as SecretDNS and retry. If that is not enough, set the proxy variables in the same terminal that runs `openai-oauth` or `ima2 serve`:
@@ -337,7 +332,7 @@ Use the host and port from your proxy client. If `ima2-gen` still fails after th
 
 ### What should I check on a company computer?
 
-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.
+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.
 
 ## CLI troubleshooting checklist
 
@@ -348,7 +343,7 @@ ima2 doctor
 ima2 status
 ima2 ping
 ima2 ps
-npx @openai/codex login
+ima2 setup
 npm install -g ima2-gen@latest
 ```
 

package/docs/NPX_QUICKSTART.md

@@ -0,0 +1,40 @@
+# npx Quickstart
+
+> The recommended install method is `npm install -g ima2-gen`. This page covers
+> the alternative `npx` workflow for one-shot usage without a global install.
+
+## Run without installing
+
+```bash
+npx ima2-gen serve
+```
+
+Then open `http://localhost:3333`.
+
+If ChatGPT OAuth is not logged in yet:
+
+```bash
+npx @openai/codex login
+npx ima2-gen serve
+```
+
+## Notes
+
+- `npx` downloads the package to a temporary cache. Each run may re-download if
+  the cache is cold, which is slower than a global install.
+- Generated images are stored in `~/.ima2/generated` regardless of install
+  method. They are not lost when the npx cache expires.
+- `ima2 setup`, `ima2 grok login`, and other CLI commands still work after
+  `npx ima2-gen serve` starts the server, as long as the npx session is active.
+- For a stable, faster experience, use the global install:
+
+```bash
+npm install -g ima2-gen
+ima2 setup
+ima2 serve
+```
+
+## Recovering images from an old npx cache
+
+If you used `npx` in earlier versions and your images were saved inside the npx
+cache instead of `~/.ima2/generated`, see [Recover Old Images](RECOVER_OLD_IMAGES.md).

package/docs/PROMPT_STUDIO.ko.md

@@ -15,7 +15,7 @@ Prompt Studio는 이미지를 반복해서 뽑고 비교하는 Classic 작업공
 | 멀티모드 | 현재 프롬프트로 여러 개의 이미지 요청을 시작합니다. | 각 슬롯은 후보 이미지입니다. 콜라주 칸이나 보장된 연속 장면이 아닙니다. |
 | 1:1 Direct | 앱이 프롬프트를 덜 바꾸고 원문에 가깝게 전달합니다. | 정확한 문구 비교, 엄격한 템플릿, provider 쪽 prompt syntax 실험에 씁니다. |
 | 모델 빠른 메뉴 | 사이드바 상단에서 모델과 추론 강도를 바로 바꿉니다. | 자세한 설명과 전체 설정은 Settings 작업공간에 남아 있습니다. |
-| 최근 생성 | Prompt Studio에서 보이는 최근 생성 범위를 보여줍니다. | 화살표 이동은 화면에 보이는 최근 생성 범위와 맞아야 합니다. |
+| 최근 생성 | Prompt Studio에서 보이는 최근 생성 범위를 보여줍니다. | 화살표 이동은 화면에 보이는 최근 생성 범위와 맞아야 합니다. 영상 항목은 비디오 썸네일로 표시됩니다. 썸네일을 작성창으로 드래그해 참조 이미지로 추가할 수 있습니다. |
 | 갤러리 | 로컬 저장 이미지, 전체/즐겨찾기 탭, 폴더를 봅니다. | 즐겨찾기 추가/제거는 보고 있던 갤러리 위치를 유지해야 합니다. |
 | 프롬프트 라이브러리 | 저장된 프롬프트를 의도적으로 작성창에 넣습니다. | 라이브러리 삽입/이어가기 같은 명시적 액션만 프롬프트를 가져옵니다. |
 

package/docs/PROMPT_STUDIO.md

@@ -15,7 +15,7 @@ you want a reproducible way to report a workspace issue.
 | 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. |
+| 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. |
 | 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.ja.md

@@ -10,33 +10,23 @@
 
 `ima2-gen` は、無料の ChatGPT と SuperGrok だけで画像と動画を作れるローカル AI スタジオです。
 
-`npx` で起動し、ChatGPT または Grok OAuth でログインすれば、すぐに画像・動画生成を始められます。API キー不要で、ノード分岐、multimode batch、Grok Video、Canvas Mode まで全機能が使えます。
+グローバルインストールし、ChatGPT または Grok OAuth でログインすれば、すぐに画像・動画生成を始められます。API キー不要で、ノード分岐、multimode batch、Grok Video、Canvas Mode まで全機能が使えます。
 
 ![プロンプト入力、生成画像、モデル表示、結果メタデータが見える ima2-gen classic 画面](../assets/screenshots/classic-generate-light.png)
 
 ## Quick Start
 
 ```bash
-npx ima2-gen serve
+npm install -g ima2-gen
+ima2 setup
+ima2 serve
 ```
 
 その後、`http://localhost:3333` を開きます。
 
-Codex にまだログインしていない場合:
-
-```bash
-npx @openai/codex login
-npx ima2-gen serve
-```
-
 `3333` がすでに使われている場合、次に空いているポートで起動し、実際の URL は `~/.ima2/server.json` に書き込まれます。ポートを決め打ちせず、terminal に表示された URL または `ima2 open` を使ってください。
 
-グローバルインストールもできます。
-
-```bash
-npm install -g ima2-gen
-ima2 serve
-```
+> **npx を使いたい場合は?** [NPX_QUICKSTART.md](NPX_QUICKSTART.md) を参照してください。
 
 ## できること
 
@@ -194,7 +184,7 @@ Endpoint 一覧は [API Reference](API.md) に分離しました。
 まず `ima2 serve` を起動し、`~/.ima2/server.json` を確認してください。`ima2 ping --server http://localhost:3333` も使えます。
 
 **OAuth login がうまくいかない**
-`npx @openai/codex login` を実行し、`ima2 status` を確認してから `ima2 serve` を再起動してください。
+`ima2 setup` を再実行（オプション 1）し、`ima2 status` を確認してから `ima2 serve` を再起動してください。
 
 **画像生成が `API_KEY_REQUIRED` で失敗する**
 `provider: "api"` request に使う API key が設定されていません。API key を設定するか OAuth provider に切り替えてください。