ima2-gen 1.1.19 → 1.1.21

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 に切り替えてください。

package/docs/README.ko.md

@@ -12,33 +12,23 @@
 
 `ima2-gen`은 무료 ChatGPT와 SuperGrok만으로 이미지와 영상을 만드는 로컬 AI 스튜디오입니다.
 
-`npx` 한 줄로 실행하고, ChatGPT 또는 Grok OAuth로 로그인하면 바로 시작됩니다. API 키 없이 이미지 생성, 비디오 생성, 노드 분기, 멀티모드 배치, Canvas 정리까지 전부 가능합니다.
+전역 설치 후 ChatGPT 또는 Grok OAuth로 로그인하면 바로 시작됩니다. API 키 없이 이미지 생성, 비디오 생성, 노드 분기, 멀티모드 배치, Canvas 정리까지 전부 가능합니다.
 
 ![프롬프트 작성창, 생성 이미지, 모델 표시, 결과 메타데이터가 보이는 ima2-gen 클래식 생성 화면](../assets/screenshots/classic-generate-light.png)
 
 ## 빠른 시작
 
 ```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`에 기록됩니다. 포트를 추측하지 말고 터미널에 출력된 URL이나 `ima2 open`을 사용하세요.
 
-전역 설치도 가능합니다.
-
-```bash
-npm install -g ima2-gen
-ima2 serve
-```
+> **npx로 실행하고 싶다면?** [NPX_QUICKSTART.md](NPX_QUICKSTART.md)를 참고하세요.
 
 ### 설정
 
@@ -78,7 +68,7 @@ Grok video 생성(T2V/I2V/ref2v)은 v1.1.16부터 사용 가능합니다. 텍스
 
 설정 화면에 **API key provider available**이나 **Grok provider available**이 보이면 해당 공급자가 감지됐고 생성 요청에 사용할 수 있다는 뜻입니다.
 
-![OAuth 활성화와 API 키 비활성 상태를 보여주는 설정 화면](../assets/screenshots/settings-oauth-generation.png)
+![GPT OAuth 활성화와 API 키 비활성 상태를 보여주는 설정 화면](../assets/screenshots/settings-oauth-generation.png)
 
 ## 모델 안내
 
@@ -225,14 +215,14 @@ environment variables > ~/.ima2/config.json > built-in defaults
 **`ima2 ping`이 서버에 연결하지 못한다고 나와요**
 `ima2 serve`를 먼저 실행하고 `~/.ima2/server.json`을 확인하세요. `ima2 ping --server http://localhost:3333`도 사용할 수 있습니다.
 
-**OAuth 로그인이 안 돼요**
-`npx @openai/codex login`을 실행하고, `ima2 status`를 확인한 뒤 `ima2 serve`를 다시 시작하세요.
+**GPT OAuth 로그인이 안 돼요**
+`ima2 setup`을 다시 실행하고(옵션 1), `ima2 status`를 확인한 뒤 `ima2 serve`를 다시 시작하세요.
 
 **프록시/VPN 환경에서 `fetch failed`가 반복돼요**
-로컬 OAuth 프록시가 접근 가능한지 확인하세요. 프록시가 필요한 네트워크라면 프록시 클라이언트의 TUN/TURN류 모드를 켠 뒤 `npx openai-oauth --port 10531`을 다시 시도하세요. 그래도 실패하면 `ima2 serve` 또는 `openai-oauth`를 실행하는 같은 터미널에 `HTTP_PROXY`와 `HTTPS_PROXY`를 설정하세요.
+로컬 OAuth 프록시가 접근 가능한지 확인하세요. 프록시가 필요한 네트워크라면 프록시 클라이언트의 TUN/TURN류 모드를 켠 뒤 `openai-oauth --port 10531`을 다시 시도하세요. 그래도 실패하면 `ima2 serve` 또는 `openai-oauth`를 실행하는 같은 터미널에 `HTTP_PROXY`와 `HTTPS_PROXY`를 설정하세요.
 
 **이미지 생성이 `API_KEY_REQUIRED`로 실패해요**
-`provider: "api"` 요청에 사용할 API 키가 설정되어 있지 않다는 뜻입니다. API 키를 설정하거나 OAuth 공급자로 전환하세요.
+`provider: "api"` 요청에 사용할 API 키가 설정되어 있지 않다는 뜻입니다. API 키를 설정하거나 GPT OAuth 공급자로 전환하세요.
 
 **큰 레퍼런스 이미지가 실패해요**
 JPEG/PNG는 업로드 전에 자동 압축됩니다. 그래도 실패하면 해상도를 낮춘 JPEG/PNG로 바꿔 다시 시도하세요. HEIC/HEIF는 브라우저 경로에서 지원하지 않습니다.

package/docs/README.zh-CN.md

@@ -10,33 +10,23 @@
 
 `ima2-gen` 是一个本地 AI 工作室，只需免费 ChatGPT 和 SuperGrok 即可生成图像和视频。
 
-用 `npx` 启动，通过 ChatGPT 或 Grok OAuth 登录即可开始生成图像和视频。无需 API 密钥，节点分支、multimode 批量、Grok Video、Canvas Mode 全部可用。
+全局安装后，通过 ChatGPT 或 Grok OAuth 登录即可开始生成图像和视频。无需 API 密钥，节点分支、multimode 批量、Grok Video、Canvas Mode 全部可用。
 
 ![显示 prompt 输入区、生成图片、模型标签和结果元数据的 ima2-gen classic 界面](../assets/screenshots/classic-generate-light.png)
 
 ## 快速开始
 
 ```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` 已经被占用，server 会绑定下一个可用端口，并把实际 URL 写入 `~/.ima2/server.json`。不要假设端口固定，请使用终端输出的 URL 或 `ima2 open`。
 
-也可以全局安装：
-
-```bash
-npm install -g ima2-gen
-ima2 serve
-```
+> **想用 npx 运行？** 请参阅 [NPX_QUICKSTART.md](NPX_QUICKSTART.md)。
 
 ## 能做什么
 
@@ -194,10 +184,10 @@ environment variables > ~/.ima2/config.json > built-in defaults
 先启动 `ima2 serve`，再检查 `~/.ima2/server.json`。也可以运行 `ima2 ping --server http://localhost:3333`。
 
 **OAuth 登录失败**
-运行 `npx @openai/codex login`，用 `ima2 status` 确认状态，然后重启 `ima2 serve`。
+重新运行 `ima2 setup`（选项 1），用 `ima2 status` 确认状态，然后重启 `ima2 serve`。
 
 **在代理/VPN 网络下反复出现 `fetch failed`**
-请先确认本地 OAuth proxy 可以访问。如果你的网络需要代理，请在代理客户端里开启 TUN/TURN 类似的转发模式，然后重试 `npx openai-oauth --port 10531`。如果仍然失败，请在运行 `ima2 serve` 或 `openai-oauth` 的同一个终端里设置 `HTTP_PROXY` 和 `HTTPS_PROXY`。
+请先确认本地 OAuth proxy 可以访问。如果你的网络需要代理，请在代理客户端里开启 TUN/TURN 类似的转发模式，然后重试 `openai-oauth --port 10531`。如果仍然失败，请在运行 `ima2 serve` 或 `openai-oauth` 的同一个终端里设置 `HTTP_PROXY` 和 `HTTPS_PROXY`。
 
 **生成图片时返回 `API_KEY_REQUIRED`**
 `provider: "api"` 请求没有可用 API key。请配置 API key，或切换到 OAuth provider。

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: 167 (runtime: 54, contract: 113)
+Total: 175 (runtime: 60, contract: 115)
 
 ## Runtime-importing tests
 - `tests/agent-mode-auto-planner-contract.test.ts`
@@ -13,6 +13,7 @@ Total: 167 (runtime: 54, contract: 113)
 - `tests/agent-mode-queue-migration-contract.test.ts`
 - `tests/agent-mode-runtime-contract.test.ts`
 - `tests/agent-mode-slash-command-contract.test.ts`
+- `tests/agent-video-intent.test.ts`
 - `tests/api-cache-policy.test.ts`
 - `tests/api-provider-parity.test.ts`
 - `tests/billing-source.test.ts`
@@ -22,8 +23,11 @@ Total: 167 (runtime: 54, contract: 113)
 - `tests/comfy-bridge-contract.test.ts`
 - `tests/error-classify.test.ts`
 - `tests/generate-route-validation-error.test.ts`
+- `tests/generated-static-privacy.test.ts`
 - `tests/generation-errors.test.ts`
+- `tests/grok-command-login-contract.test.ts`
 - `tests/grok-planner-adapter.test.ts`
+- `tests/grok-proxy-launcher.test.ts`
 - `tests/grok-size-mapper.test.ts`
 - `tests/grokVideoAdapter.test.ts`
 - `tests/history-metadata-fallback.test.ts`
@@ -60,6 +64,8 @@ Total: 167 (runtime: 54, contract: 113)
 - `tests/star-prompt.test.ts`
 - `tests/storage-migration.test.ts`
 - `tests/style-sheet.test.ts`
+- `tests/videoContinuity.test.ts`
+- `tests/videoExtendedRoute.test.ts`
 - `tests/videoRoute.test.ts`
 
 ## Contract-only tests
@@ -109,6 +115,7 @@ Total: 167 (runtime: 54, contract: 113)
 - `tests/cli-prompt-builder-contract.test.js`
 - `tests/cli-prompt-import-contract.test.js`
 - `tests/cli-skill-command-contract.test.js`
+- `tests/cli-video-command-contract.test.js`
 - `tests/comfy-export-ui-contract.test.js`
 - `tests/comfyui-custom-node-contract.test.js`
 - `tests/config.test.js`
@@ -174,5 +181,6 @@ Total: 167 (runtime: 54, contract: 113)
 - `tests/style-feature-removal-contract.test.js`
 - `tests/toast-stack-contract.test.js`
 - `tests/ui-error-code-contract.test.js`
+- `tests/video-continuity-ui-contract.test.js`
 - `tests/vite-dev-port-contract.test.js`
 - `tests/web-search-toggle-contract.test.js`

package/lib/agentGenerationPlanner.js

@@ -196,7 +196,26 @@ function cleanCount(value, fallback, min, max) {
 function clampCount(value, max) {
     return Math.max(1, Math.min(max, Math.round(value)));
 }
-const VIDEO_INTENT_PATTERN = /\b(?:video|animate|animation|동영상|비디오|영상|애니메이트|움직이|클립)\b/iu;
+const VIDEO_INTENT_PATTERN = /(?:^|\s|[^\p{L}])(?:video|animate|animation)(?:\s|[^\p{L}]|$)|(?:동영상|비디오|영상|애니메이트|움직이|클립)/iu;
 function isVideoIntent(prompt) {
     return VIDEO_INTENT_PATTERN.test(prompt);
 }
+const DURATION_PATTERN = /(\d{1,2})\s*(?:s|sec|seconds?|초)/i;
+const RESOLUTION_PATTERN = /(720p|480p)/i;
+const ASPECT_PATTERN = /(16:9|9:16|4:3|3:4|3:2|2:3|1:1)/;
+export function parseVideoParams(prompt) {
+    const params = {};
+    const durMatch = DURATION_PATTERN.exec(prompt);
+    if (durMatch) {
+        const d = parseInt(durMatch[1]);
+        if (d >= 1 && d <= 15)
+            params.duration = d;
+    }
+    const resMatch = RESOLUTION_PATTERN.exec(prompt);
+    if (resMatch)
+        params.resolution = resMatch[1].toLowerCase();
+    const aspMatch = ASPECT_PATTERN.exec(prompt);
+    if (aspMatch)
+        params.aspectRatio = aspMatch[1];
+    return params;
+}