veogent 1.3.0 → 1.4.0

package/skills/SKILL.md

@@ -1,819 +1,399 @@
 ---
 name: veogent
-description: Full CLI skill guide for the VEOGENT API — AI-powered movie/story project management, image & video generation, and YouTube publishing.
+description: "Operate the VEOGENT CLI for AI video/story production workflows: authentication, project setup, chapters, scenes, character readiness, image/video generation, scene repair, and YouTube metadata/thumbnail flows."
 ---
 
 # VEOGENT CLI — Agent Skill Guide
 
-The `veogent` command-line interface interacts with the **VEOGENT API** for managing AI movie/story projects, chapters, scenes, characters, and media generation requests (images, videos, upscales). All data outputs are strict **JSON** — designed for AI agent parsing and chaining.
+Use the `veogent` CLI as the source of truth for VEOGENT workflows. Always use `--agent-safe` for automation-friendly JSON output.
 
 ---
 
-## Table of Contents
-
-1. [Authentication & Configuration](#-authentication--configuration)
-2. [Projects & Assets](#-projects--assets)
-3. [Chapters](#-chapters)
-4. [Scenes](#-scenes)
-5. [Characters & Readiness](#-characters)
-6. [Scene Editing & Prompt Crafting](#-scene-editing--prompt-crafting)
-7. [Generation Requests (Images / Videos / Upscale)](#-generation-requests)
-8. [Monitoring & Status](#-monitoring--status)
-9. [YouTube Metadata & Thumbnails](#-youtube-metadata--thumbnails)
-10. [Flow Token & Credits](#-flow-token-management)
-11. [The Complete VEOGENT Pipeline (Best Practices)](#-the-complete-veogent-pipeline)
-12. [Error Handling](#-error-handling)
+## How VEOGENT Works — The Mental Model
 
----
-
-## 🔐 Authentication & Configuration
-
-### Skill: `login`
-- **Description:** Login to obtain access token via Web Browser. Opens a local browser for **Google Firebase OAuth** — agents **cannot** authenticate automatically.
-- **Guidelines:** If `veogent status` returns `{"error": "Not logged in"}`, instruct the user to run `veogent login` manually in their desktop terminal and wait for confirmation.
-- **Example:**
-  ```bash
-  veogent login
-  ```
-
-### Skill: `logout`
-- **Description:** Clear saved credentials and remove the stored access token.
-- **Example:**
-  ```bash
-  veogent logout
-  ```
-
-### Skill: `status`
-- **Description:** Show current authenticated user, Flow Key details, and payment tier.
-- **Guidelines:** Always call this first to verify the agent has valid authentication before making API calls.
-- **Example:**
-  ```bash
-  veogent status
-  # Output: { "authenticated": true, "flowKey": "ya29.xxx", "paymentTier": "PAYGATE_TIER_TWO" }
-  ```
-
-### Skill: `setup-flow`
-- **Description:** Setup/update the Google Flow Key and User Payment Tier. Required for video generation and AI-assisted features.
-- **Guidelines:**
-  - If any VEOGENT API request fails with a `"status code 401"` or Flow error, the Flow Key has expired.
-  - Prompt the user for a new key and update it via `setup-flow` before retrying.
-- **Options:**
-  | Flag | Required | Description | Default |
-  |------|----------|-------------|---------|
-  | `--flowkey <key>` | ✅ | The Google access token (ya29...) | — |
-  | `--tier <tier>` | ❌ | User payment tier | `PAYGATE_TIER_TWO` |
-- **Example:**
-  ```bash
-  veogent setup-flow --flowkey "ya29.a0AW..." --tier "PAYGATE_TIER_TWO"
-  ```
-
-### Skill: `obtain-flow`
-- **Description:** Auto-extract your labs.google Flow Token (`ya29.`) using a secure Chromium browser overlay.
-- **Guidelines:** This opens a Chromium window to `https://labs.google/fx/tools/flow` and captures the Bearer Token from network traffic. The user must click "Create with Flow" and login if requested.
-- **Example:**
-  ```bash
-  veogent obtain-flow
-  # Output: 🎉 Extracted Flow Token: ya29.xxx
-  # Then apply it:
-  veogent setup-flow --flowkey "ya29.xxx"
-  ```
-
----
-
-## 📁 Projects & Assets
-
-### Skill: `image-materials`
-- **Description:** Get all available Image Material styles (e.g., `CINEMATIC`, `PIXAR_3D`, `Anime style`).
-- **Guidelines:** **Always call this before creating a project** to know which material strings are valid. `CINEMATIC` is an acceptable default if unsure.
-- **Example:**
-  ```bash
-  veogent image-materials
-  ```
-
-### Skill: `custom-prompts`
-- **Description:** Get all custom prompt templates / story directives.
-- **Guidelines:** Call this to find a matching `customPromptId` if a custom stylistic prompt is needed when creating a project or generating descriptions.
-- **Example:**
-  ```bash
-  veogent custom-prompts
-  ```
-
-### Skill: `projects`
-- **Description:** List all your available projects.
-- **Guidelines:**
-  - IDs are **Firebase Document Strings** (e.g., `APQF6Ay0kLeXLhpctTdD`), not simple integers.
-  - Always use the field `"id"` from the JSON response array.
-- **Example:**
-  ```bash
-  veogent projects
-  ```
-
-### Skill: `project`
-- **Description:** Get details for a specific project including its progress status, characters, and configuration.
-- **Example:**
-  ```bash
-  veogent project <projectId>
-  veogent project APQF6Ay0kLeXLhpctTdD
-  ```
-
-### Skill: `create-project-description`
-- **Description:** Generate an AI-powered description for a new project based on keywords. This should be called **before** `create-project` to build the story payload.
-- **Options:**
-  | Flag | Required | Description |
-  |------|----------|-------------|
-  | `--keyword <keyword>` | ✅ | Keywords for the project |
-  | `--lang <lang>` | ✅ | Story language (e.g., `English`, `Vietnamese`) |
-  | `--promptId <promptId>` | ✅ | Custom Prompt ID from `custom-prompts` |
-  | `--objects <json>` | ❌ | Objects JSON array (characters/visual assets) |
-  | `--objects-file <path>` | ❌ | Path to JSON file containing objects array |
-- **Example:**
-  ```bash
-  veogent create-project-description --keyword "T-rex, Neon, Tokyo" --lang "English" --promptId "promptId123"
-  # With objects:
-  veogent create-project-description --keyword "A knight saves a dragon" --lang "English" \
-    --objects '[{"name":"Knight","entityType":"character","description":"A brave medieval knight"}]'
-  ```
-
-### Skill: `create-project`
-- **Description:** Create a new AI movie/story project with full configuration.
-- **Options:**
-  | Flag | Required | Description | Default |
-  |------|----------|-------------|---------|
-  | `--name <name>` | ✅ | Project name | — |
-  | `--keyword <keyword>` | ✅ | Keywords | — |
-  | `--desc <desc>` | ✅ | Description (use output from `create-project-description`) | — |
-  | `--lang <lang>` | ✅ | Story language | — |
-  | `--sound` | ✅ | Sound effects | `true` |
-  | `--material <material>` | ✅ | Image material (from `image-materials`) | — |
-  | `--chapters <count>` | ✅ | Number of chapters | `1` |
-  | `--customPromptId <id>` | ❌ | Custom Prompt ID | — |
-  | `--objects <json>` | ❌ | Objects JSON array (inline) | — |
-  | `--objects-file <path>` | ❌ | Path to JSON file with objects array | — |
-  | `--object-images <paths...>` | ❌ | Image files to auto-convert (use with `--object-names`) | — |
-  | `--object-names <names...>` | ❌ | Names for each object image | — |
-  | `--object-types <types...>` | ❌ | Entity types per object (`character`\|`visual_asset`) | `character` |
-
-- **Objects format** (max 4 image objects, max 10 JSON objects):
-  ```json
-  [
-    {"name": "Hero", "entityType": "character", "description": "A brave knight", "file": "data:image/jpeg;base64,..."},
-    {"name": "Castle", "entityType": "visual_asset", "description": "Medieval castle"}
-  ]
-  ```
-
-- **Examples:**
-  ```bash
-  # Basic (no objects)
-  veogent create-project --name "Cyberpunk T-Rex" --keyword "T-rex, Neon, Sci-fi" \
-    --desc "A massive T-rex walking inside Tokyo at night..." \
-    --lang "English" --material "CINEMATIC" --chapters 5
-
-  # With inline objects JSON
-  veogent create-project --name "Knight Story" --keyword "medieval knight dragon" \
-    --desc "A brave knight..." --lang "English" --material "CINEMATIC" --chapters 3 \
-    --objects '[{"name":"Knight","entityType":"character","description":"A brave knight","file":"data:image/jpeg;base64,..."}]'
-
-  # With objects from file
-  veogent create-project --name "Knight Story" --keyword "medieval" \
-    --desc "desc..." --lang "English" --material "CINEMATIC" --chapters 3 \
-    --objects-file ./my-objects.json
-
-  # Auto-convert image files
-  veogent create-project --name "Knight Story" --keyword "medieval" \
-    --desc "desc..." --lang "English" --material "CINEMATIC" --chapters 3 \
-    --object-images hero.jpg castle.png \
-    --object-names "Hero" "Castle" \
-    --object-types "character" "visual_asset"
-  ```
+```
+--idea → AI Description → Project + Character References (image URIs)
+                        → Storyboard (scene scripts)
+                        → Scenes → Images → Videos
+```
 
----
+**The key insight:** Names in `--idea` become character/entity references with image URIs at **project level**. These references ensure visual consistency across ALL chapters and scenes.
 
-## 📖 Chapters
-
-### Skill: `chapters`
-- **Description:** Get all chapters for a specific project.
-- **Example:**
-  ```bash
-  veogent chapters <projectId>
-  ```
-
-### Skill: `recent-chapters`
-- **Description:** Get recently created or updated chapters across all projects.
-- **Options:**
-  | Flag | Required | Description | Default |
-  |------|----------|-------------|---------|
-  | `--limit <limit>` | ❌ | Maximum number of recent chapters to return | `10` |
-- **Example:**
-  ```bash
-  veogent recent-chapters --limit 5
-  ```
-
-### Skill: `create-chapter-content`
-- **Description:** Generate AI story/narrative content for a specific chapter, producing scene scripts.
-- **Guidelines:**
-  - This is a **synchronous AI generation call** — use the `chapterContent` array from the returned response directly.
-  - Do NOT poll chapter state for contents; the canonical output is the response itself.
-  - Each scene maps to approximately an **~8-second video clip**. The returned scene-script array should be **immediately** passed to `create-scene`.
-- **Response:**
-  ```json
-  { "status": "success", "chapterContent": ["Scene 1 script...", "Scene 2 script..."] }
-  ```
-- **Options:**
-  | Flag | Required | Description | Default |
-  |------|----------|-------------|---------|
-  | `--project <project>` | ✅ | Project ID | — |
-  | `--chapter <chapter>` | ✅ | Chapter ID | — |
-  | `--scenes <count>` | ✅ | Number of scenes to generate | `1` |
-- **Example:**
-  ```bash
-  veogent create-chapter-content --project "projID" --chapter "chapID" --scenes 5
-  # → { "status": "success", "chapterContent": ["...", "..."] }
-  ```
+That's why you use character **NAMES only** in prompts — never describe appearance. The reference images already define exactly how each character looks.
 
 ---
 
-## 🎬 Scenes
-
-### Skill: `scenes`
-- **Description:** Get all scenes for a specific chapter within a project.
-- **Example:**
-  ```bash
-  veogent scenes <projectId> <chapterId>
-  ```
-
-### Skill: `create-scene`
-- **Description:** Create new scenes from an array of text content/script lines.
-- **Guidelines:** Pass the scene-script array returned from `create-chapter-content` directly. Use `--flowkey` to sync context via Firebase.
-- **Options:**
-  | Flag | Required | Description | Default |
-  |------|----------|-------------|---------|
-  | `--project <project>` | ✅ | Project ID | — |
-  | `--chapter <chapter>` | ✅ | Chapter ID | — |
-  | `--content <content...>` | ✅ | Array of scene text scripts | — |
-  | `--flowkey` | ❌ | Enable useFlowKey to sync context via Firebase | `false` |
-- **Example:**
-  ```bash
-  veogent create-scene --project "projID" --chapter "chapID" \
-    --content "The T-Rex looks up at the sky." "A meteor shower begins." "Explosions rock the city." \
-    --flowkey
-  ```
-
-### Skill: `add-scene`
-- **Description:** Add a single new scene to a chapter using a user prompt. Unlike `create-scene` (which bulk-creates from script arrays), this inserts one scene at a specific position.
-- **Guidelines:**
-  - Use this to insert additional scenes into an existing chapter after initial scene creation.
-  - By default, `regenerateImage` is `true` — the backend will auto-generate the scene image.
-  - Use `--after-scene-id` to control insertion order; omit to append at the end.
-- **Options:**
-  | Flag | Required | Description | Default |
-  |------|----------|-------------|---------|
-  | `--project <project>` | ✅ | Project ID | — |
-  | `--chapter <chapter>` | ✅ | Chapter ID | — |
-  | `--userprompt <userPrompt>` | ✅ | User narrative prompt for the new scene | — |
-  | `--no-regenerate-image` | ❌ | Skip automatic image regeneration | `false` (images regenerated by default) |
-  | `--after-scene-id <afterSceneId>` | ❌ | Scene ID to insert after (appends to end if omitted) | — |
-- **Examples:**
-  ```bash
-  # Add a scene at the end of the chapter
-  veogent add-scene --project "projID" --chapter "chapID" \
-    --userprompt "A meteor crashes into the city, sending shockwaves across the skyline."
-
-  # Insert after a specific scene
-  veogent add-scene --project "projID" --chapter "chapID" \
-    --userprompt "The hero turns and runs toward the explosion." \
-    --after-scene-id "ayeaOIYYlpY0o7xeRtRu"
-
-  # Add without auto image generation
-  veogent add-scene --project "projID" --chapter "chapID" \
-    --userprompt "A quiet moment before the storm." --no-regenerate-image
-  ```
+## Recommended Workflow (4 Phases)
 
----
+### Phase 1: Create Project
 
-## 🧑‍🎨 Characters
-
-### Skill: `characters`
-- **Description:** Get all characters for a specific project, including `imageUri` status and readiness info.
-- **Guidelines:** After creating scenes, the system **auto-generates characters**. Poll this command until `characterReadiness.allReady === true` before proceeding to image/video generation.
-- **Response:**
-  ```json
-  {
-    "status": "success",
-    "characters": [
-      { "id": "...", "name": "...", "imageUri": "https://...", "ready": true }
-    ],
-    "characterReadiness": { "total": 4, "ready": 4, "allReady": true }
-  }
-  ```
-- **Example:**
-  ```bash
-  veogent characters <projectId>
-  # Poll until: characterReadiness.allReady === true
-  ```
-
-### Skill: `scene-materialization-status`
-- **Description:** Check how many scenes have been materialized (created on the backend) for a chapter.
-- **Guidelines:** Use this after `create-scene` to verify all scenes are ready before starting image generation. Poll until `status === "READY"`.
-- **Options:**
-  | Flag | Required | Description |
-  |------|----------|-------------|
-  | `--project <project>` | ✅ | Project ID |
-  | `--chapter <chapter>` | ✅ | Chapter ID |
-- **Response:**
-  ```json
-  { "expectedScenes": 5, "materializedScenes": 5, "status": "READY" }
-  ```
-  Status values: `"PROCESSING"` | `"READY"` | `"EMPTY"`
-- **Example:**
-  ```bash
-  veogent scene-materialization-status --project "projID" --chapter "chapID"
-  # Poll until: status === "READY"
-  ```
-
-### Skill: `edit-character`
-- **Description:** Update a character's description/traits or edit their generated image directly via AI prompt.
-- **Guidelines:**
-  - **Regenerate Profile Mode** (default): Updates description/traits and generates a new portrait base.
-  - **Direct Image Edit Mode** (`--editimage` flag): Applies changes directly to the existing generated portrait image via in-painting.
-- **Options:**
-  | Flag | Required | Description | Default |
-  |------|----------|-------------|---------|
-  | `--project <project>` | ✅ | Project ID | — |
-  | `--character <character>` | ✅ | Character ID (e.g., `drelenavance`) | — |
-  | `--userprompt <userprompt>` | ✅ | User instruction to modify the character | — |
-  | `--editimage` | ❌ | Enable direct Image Editing Mode | `false` |
-  | `--flowkey` | ❌ | Enable useFlowKey to sync context via Firebase | `true` |
-- **Examples:**
-  ```bash
-  # Regenerate character profile with new traits
-  veogent edit-character --project "projID" --character "drelenavance" --userprompt "change outfit to lab coat"
-
-  # Direct image edit (in-paint on existing portrait)
-  veogent edit-character --project "projID" --character "drelenavance" --userprompt "change shoes to black boots" --editimage
-  ```
+```bash
+veogent create-project \
+  --idea "Bella the white Bichon Frisé CEO in pink blazer, two Doberman bodyguards Rex and Duke in black suits, luxury shopping mall Saigon" \
+  --name "Boss Babe in Fur" \
+  --lang English --material CINEMATIC
+```
 
----
+Internally: CLI calls `/app/description` → generates rich AI description from --idea → creates project with character references.
 
-## 🖌️ Scene Editing & Prompt Crafting
-
-### Skill: `edit-scene`
-- **Description:** Edit an existing scene's image prompt via AI assistance, hitting the `updateScriptSegment` workflow.
-- **Guidelines:**
-  - You are editing the **Image Prompt for Frame 0** (the starting image) used for video generation.
-  - By default, editing a scene auto-regenerates the image. Use `--no-regenerate` to skip.
-  - To edit a specific past generated image, pass the previous `requestId` using `--request`.
-
-#### 📐 Prompting Guide for Scene Image Prompts
-
-Beside the main visual description, you **CAN** include minor action descriptions (e.g., "bus speeding over cliff", "smoke rising"). You **SHOULD** heavily leverage camera terminology to steer frame composition:
-
-**Shot Types:**
-| Shot Type | Description | Vietnamese |
-|-----------|-------------|------------|
-| Close-up | Tight framing on subject | Cận cảnh |
-| Wide shot | Full environment visible | Toàn cảnh |
-| Medium shot | Waist-up framing | Trung cảnh |
-| Extreme close-up | Detail-level (face, object) | Cận mặt |
-| Long shot | Subject small in frame | Tầm trung xa |
-
-**Camera Angles:**
-| Angle | Description |
-|-------|-------------|
-| High angle | Looking down on subject (Góc cao) |
-| Low angle | Looking up at subject (Góc thấp) |
-| Bird's-eye | Directly overhead (Góc chim) |
-| Eye-level | Neutral perspective (Góc ngang mắt) |
-| Over-the-shoulder | Behind a character looking forward |
-| POV | First-person perspective |
-
-**Camera Movements:**
-| Movement | Symbol | Description |
-|----------|--------|-------------|
-| Pan left | ← | Horizontal sweep left |
-| Pan right | → | Horizontal sweep right |
-| Tilt up | ↑ | Vertical sweep up |
-| Tilt down | ↓ | Vertical sweep down |
-| Zoom in | + | Push closer |
-| Zoom out | - | Pull farther |
-
-- **Options:**
-  | Flag | Required | Description |
-  |------|----------|-------------|
-  | `--project <project>` | ✅ | Project ID |
-  | `--chapter <chapter>` | ✅ | Chapter ID |
-  | `--scene <scene>` | ✅ | Scene ID |
-  | `--userprompt <userprompt>` | ✅ | User narrative prompt to modify the scene |
-  | `--no-regenerate` | ❌ | Skip auto-regeneration of image |
-  | `--request <request>` | ❌ | Target a specific past Request ID to edit its output |
-
-- **Examples:**
-  ```bash
-  # Modify image prompt (auto-regenerates)
-  veogent edit-scene --project "projID" --chapter "chapID" --scene "sceneID" \
-    --userprompt "Low angle shot of a yellow school bus speeding over a cliff, wide angle, dramatic lighting. Camera tilts down."
-
-  # Modify image prompt WITHOUT auto-regeneration
-  veogent edit-scene --project "projID" --chapter "chapID" --scene "sceneID" \
-    --userprompt "child seat behind Paulo" --no-regenerate
-
-  # Edit a specific past generated image directly
-  veogent edit-scene --project "projID" --chapter "chapID" --scene "sceneID" \
-    --userprompt "make the car red" --request "requestId123"
-  ```
+**--idea rules:**
+- ✅ Specific character names + species/role: `"Mochi the Shiba Inu"`, `"Chef Gordon the Bulldog"`
+- ✅ Location names: `"Grand Luxury Mall Saigon"`, `"Tokyo Night Market"`
+- ✅ Visual traits: `"pink blazer"`, `"black tactical suit"`
+- ✅ Props/creatures: `"robot vacuum"`, `"durian toy"`, `"golden shopping bags"`
+- ❌ Vague: `"cute dog shopping"` → VEOGENT invents random characters
 
----
+### Phase 2: Storyboard + Scenes
 
-## 🎬 Generation Requests
+```bash
+veogent chapters <projectId>
+veogent create-chapter-content --project <projectId> --chapter <chapterId> --scenes 5
+veogent create-scene --project <projectId> --chapter <chapterId> \
+  --content "Scene 1 script" "Scene 2 script" "Scene 3" "Scene 4" "Scene 5" --flowkey
+veogent characters <projectId>   # poll until allReady === true
+```
 
-### Skill: `request`
-- **Description:** Create a generation job request. Supports `GENERATE_IMAGES`, `GENERATE_VIDEO`, and `VIDEO_UPSCALE`.
-- **Guidelines:**
-  > ⚠️ **CRITICAL VALIDATION RULES (Strict DTO):** Do not pass unsupported flags for a specific type, or the server will return a `400 Bad Request` or `Validation Error`.
+NEVER skip `create-chapter-content` — always let VEOGENT AI generate the storyboard.
 
-#### 1. Generate Images (`GENERATE_IMAGES`)
+### Phase 3: Generate Images + Videos
 
-| Flag | Required | Description | Allowed Values |
-|------|----------|-------------|----------------|
-| `--type` | ✅ | `GENERATE_IMAGES` | — |
-| `--project` | ✅ | Project ID | — |
-| `--chapter` | ✅ | Chapter ID | — |
-| `--scene` | ✅ | Scene ID | — |
-| `--imagemodel` | ✅ | Image model | `imagen3.5` |
+```bash
+veogent batch-request --type GENERATE_IMAGES \
+  --project X --chapter Y --all --orientation VERTICAL --wait
+veogent batch-request --type GENERATE_VIDEO \
+  --project X --chapter Y --all --orientation VERTICAL --wait
+```
 
-> 🚫 **Prohibited flags:** Do NOT pass `--orientation`, `--videomodel`, or `--speed`.
+### Phase 4: QA + Fix Loop
 
 ```bash
-veogent request --type "GENERATE_IMAGES" --project "projID" --chapter "chapID" --scene "sceneID" --imagemodel "imagen3.5"
+veogent workflow-status --project X --chapter Y
 ```
 
-#### 2. Generate Video (`GENERATE_VIDEO`)
+Then fix using edit-scene modes and video regen (see Scene Management below).
 
-| Flag | Required | Description | Allowed Values |
-|------|----------|-------------|----------------|
-| `--type` | ✅ | `GENERATE_VIDEO` | — |
-| `--project` | ✅ | Project ID | — |
-| `--chapter` | ✅ | Chapter ID | — |
-| `--scene` | ✅ | Scene ID | — |
-| `--videomodel` | ✅ | Video model | `veo_3_1_fast` (recommended), `veo_3_1_fast_r2v` |
-| `--speed` | ✅ | Video speed | `normal`, `timelapse`, `slowmotion` |
-| `--imagemodel` | ✅ | Image model for video context | `imagen3.5` |
-| `--orientation` | ✅ | Orientation | `HORIZONTAL`, `VERTICAL` |
-| `--endscene` | ❌ | End Scene ID for continuous video generation (interpolation to next frame) | — |
+---
 
-> ℹ️ `useFlowKey` is **locked natively to `true`** — you must have a valid Flow Key.
-> ℹ️ Only run `GENERATE_VIDEO` **after** the scene already has a successful matching-orientation image.
+## Scene Management
 
-```bash
-veogent request --type "GENERATE_VIDEO" --project "projID" --chapter "chapID" --scene "sceneA" \
-  --endscene "sceneB" --orientation "VERTICAL" --imagemodel "imagen3.5" --videomodel "veo_3_1_fast" --speed "normal"
-```
+### insert-scene — Add a scene to an existing chapter
 
-#### 3. Video Upscale (`VIDEO_UPSCALE`)
+```bash
+# Append to end
+veogent insert-scene --project X --chapter Y --prompt "Bella exits the mall into sunset"
 
-| Flag | Required | Description | Allowed Values |
-|------|----------|-------------|----------------|
-| `--type` | ✅ | `VIDEO_UPSCALE` | — |
-| `--project` | ✅ | Project ID | — |
-| `--chapter` | ✅ | Chapter ID | — |
-| `--scene` | ✅ | Scene ID | — |
-| `--orientation` | ✅ | Orientation | `HORIZONTAL`, `VERTICAL` |
+# Insert after a specific scene
+veogent insert-scene --project X --chapter Y \
+  --prompt "Bella checks phone in lobby" --after <sceneId>
+```
 
-> 🚫 **Prohibited flags:** Do NOT pass `--imagemodel` or `--videomodel`.
+### edit-scene — Two modes
 
+**Mode A — Edit storyboard/prompt only (no image regen):**
 ```bash
-veogent request --type "VIDEO_UPSCALE" --project "projID" --chapter "chapID" --scene "sceneID" --orientation "HORIZONTAL"
+veogent edit-scene --project X --chapter Y --scene Z \
+  --prompt "Bella walks through mall on all four paws, steady tracking shot"
 ```
+→ Updates scene storyboard + image prompt text only. No image generated.
+→ You trigger image gen separately: `request --type GENERATE_IMAGES --scene Z --wait`
+→ **Use when:** image is fundamentally wrong, OR fixing video (image fine, update prompt then regen video)
 
-### Skill: `upscale` (Shortcut)
-- **Description:** Shortcut command for upscaling video output for a specific scene.
-- **Options:**
-  | Flag | Required | Description | Default |
-  |------|----------|-------------|---------|
-  | `--project` | ✅ | Project ID | — |
-  | `--chapter` | ✅ | Chapter ID | — |
-  | `--scene` | ✅ | Scene ID | — |
-  | `--orientation` | ❌ | Orientation | `VERTICAL` |
-  | `--resolution` | ❌ | Target resolution | `VIDEO_RESOLUTION_4K` |
-- **Example:**
-  ```bash
-  veogent upscale --project "projID" --chapter "chapID" --scene "sceneID" --orientation VERTICAL --resolution VIDEO_RESOLUTION_4K
-  ```
+**Mode B — Regenerate image directly (with request ID):**
+```bash
+veogent edit-scene --project X --chapter Y --scene Z \
+  --prompt "adjust lighting to warmer tones, shift camera right" \
+  --request <requestId> --wait
+```
+→ VEOGENT AI edits the existing generated image using your instruction
+→ **Use when:** image is close but needs a tweak (lighting, pose, angle, crop)
 
----
+**Decision guide:**
 
-## 📊 Monitoring & Status
-
-### Skill: `requests`
-- **Description:** Get generation requests/jobs status for the current user. This is the **primary status board** for all generation workflows (image/video/character-edit).
-- **Guidelines:**
-  - Always check this before retrying any generation.
-  - Results are sorted by `createdAt` descending (most recent first).
-  - Use `--limit` to limit results for efficiency in agent loops.
-- **Options:**
-  | Flag | Required | Description |
-  |------|----------|-------------|
-  | `--limit <n>` | ❌ | Return only the N most recent requests |
-  | `--project <projectId>` | ❌ | Filter by project ID |
-  | `--chapter <chapterId>` | ❌ | Filter by chapter ID |
-  | `--status <status>` | ❌ | Filter by status (`COMPLETED`, `FAILED`, `PROCESSING`, `PENDING`) |
-- **Response:** `{ "status": "success", "total": N, "data": [...] }`
-- **Examples:**
-  ```bash
-  veogent requests                                                   # all requests, newest first
-  veogent requests --limit 10                                         # 10 most recent
-  veogent requests --project <projId> --chapter <chapId>              # filter by project/chapter
-  veogent requests --status FAILED --limit 20                         # 20 most recent failures
-  ```
-
-### Skill: `scene-status`
-- **Description:** Get scene status snapshot for a chapter, with **embedded asset URLs** (image + video) per scene.
-- **Guidelines:** Use this as the canonical status view for scenes — no need for separate asset-history lookup.
-- **Options:**
-  | Flag | Required | Description |
-  |------|----------|-------------|
-  | `--project <project>` | ✅ | Project ID |
-  | `--chapter <chapter>` | ✅ | Chapter ID |
-- **Response per scene:**
-  ```json
-  {
-    "sceneId": "...",
-    "image": { "status": "COMPLETED", "url": "https://...", "completedAt": 1234567890 },
-    "video": { "status": "COMPLETED", "url": "https://...", "completedAt": 1234567890 }
-  }
-  ```
-- **Example:**
-  ```bash
-  veogent scene-status --project "projID" --chapter "chapID"
-  ```
-
-### Skill: `workflow-status`
-- **Description:** Export a full workflow snapshot — scenes, requests, and embedded asset URLs — for a project/chapter.
-- **Guidelines:** The most comprehensive single-command status view for agents. Use this to audit progress before and after generation steps.
-- **Options:**
-  | Flag | Required | Description |
-  |------|----------|-------------|
-  | `--project <project>` | ✅ | Project ID |
-  | `--chapter <chapter>` | ✅ | Chapter ID |
-- **Example:**
-  ```bash
-  veogent workflow-status --project "projID" --chapter "chapID"
-  ```
-
-### Skill: `wait-images`
-- **Description:** Wait until all image requests in a chapter finish processing.
-- **Guidelines:**
-  - Default: waits until queue is drained (no longer pending/processing).
-  - `--require-success`: after queue drains, also verifies every scene has at least one `COMPLETED` image asset. Exits non-zero if any scene lacks a successful asset.
-  - **Distinction:** "finished" ≠ "succeeded". Always use `--require-success` in automated pipelines.
-- **Options:**
-  | Flag | Required | Description |
-  |------|----------|-------------|
-  | `--project <project>` | ✅ | Project ID |
-  | `--chapter <chapter>` | ✅ | Chapter ID |
-  | `--require-success` | ❌ | Fail if any scene has no completed image asset |
-- **Example:**
-  ```bash
-  veogent wait-images --project "projID" --chapter "chapID" --require-success
-  ```
-
-### Skill: `wait-videos`
-- **Description:** Wait until all video requests in a chapter finish processing.
-- **Options:**
-  | Flag | Required | Description |
-  |------|----------|-------------|
-  | `--project <project>` | ✅ | Project ID |
-  | `--chapter <chapter>` | ✅ | Chapter ID |
-  | `--require-success` | ❌ | Fail if any scene has no completed video asset |
-- **Example:**
-  ```bash
-  veogent wait-videos --project "projID" --chapter "chapID" --require-success
-  ```
-
-### Skill: `image-models`
-- **Description:** List all supported image generation models.
-- **Example:**
-  ```bash
-  veogent image-models
-  # → { "status": "success", "models": ["imagen3.5"] }
-  ```
-
-### Skill: `video-models`
-- **Description:** List all supported video generation models.
-- **Example:**
-  ```bash
-  veogent video-models
-  # → { "status": "success", "models": ["veo_3_1_fast", "veo_3_1_fast_r2v"] }
-  ```
-
-### Skill: `flow-credits`
-- **Description:** Fetch plan and credit balance from Google AI Sandbox using your Flow key (Bearer token).
-- **Options:**
-  | Flag | Required | Description |
-  |------|----------|-------------|
-  | `--flowkey <flowkey>` | ❌ | Flow key (`ya29.` token). Defaults to stored key. |
-- **Response:**
-  ```json
-  { "status": "success", "plan": "...", "credits": 100, "totalCredits": 200, "usedCredits": 100, "resetAt": "..." }
-  ```
-- **Example:**
-  ```bash
-  veogent flow-credits
-  veogent flow-credits --flowkey "ya29.a0ATk..."
-  ```
-
-### Skill: `assets`
-- **Description:** Check generated assets history/status for a specific scene.
-- **Guidelines:**
-  - **Anti-Spam Rule:** If status is `PENDING` or `PROCESSING`, **WAIT** and do not duplicate requests.
-  - **Concurrency:** Maximum **5 requests** can be processed simultaneously. `"maximum request limit reached"` means the queue is full — wait and retry later.
-- **Example:**
-  ```bash
-  # Types: GENERATE_IMAGES, GENERATE_VIDEO, EDIT_IMAGE
-  veogent assets <projectId> <chapterId> <sceneId> GENERATE_IMAGES
-  veogent assets <projectId> <chapterId> <sceneId> GENERATE_VIDEO
-  ```
+| Situation | Action |
+|-----------|--------|
+| Image fundamentally wrong | Mode A → regen image → regen video |
+| Image close, needs tweak | Mode B (--request) → regen video |
+| Image fine, video wrong | Mode A (update prompt) → regen video only |
 
 ---
 
-## 📺 YouTube Metadata & Thumbnails
-
-### Skill: `generate-yt-metadata`
-- **Description:** Generate YouTube metadata (Title, Description, Tags) for a chapter using AI.
-- **Options:**
-  | Flag | Required | Description |
-  |------|----------|-------------|
-  | `--project` | ✅ | Project ID |
-  | `--chapter` | ✅ | Chapter ID |
-  | `--lang` | ✅ | Story language |
-- **Example:**
-  ```bash
-  veogent generate-yt-metadata --project "projID" --chapter "chapID" --lang "English"
-  ```
-
-### Skill: `generate-yt-thumbnail`
-- **Description:** Triggers a request to generate a YouTube thumbnail for a chapter.
-- **Options:**
-  | Flag | Required | Description |
-  |------|----------|-------------|
-  | `--project` | ✅ | Project ID |
-  | `--chapter` | ✅ | Chapter ID |
-  | `--lang` | ✅ | Story language |
-- **Example:**
-  ```bash
-  veogent generate-yt-thumbnail --project "projID" --chapter "chapID" --lang "English"
-  ```
-
-### Skill: `yt-thumbnails`
-- **Description:** Retrieve generated YouTube thumbnails for a chapter.
-- **Example:**
-  ```bash
-  veogent yt-thumbnails <projectId> <chapterId>
-  ```
+## Character Management
 
----
+Characters are project-level — shared across all chapters for visual consistency.
 
-## 🗝️ Flow Token Management
-
-### Skill: `obtain-flow`
-- **Description:** Auto-extract the Google Flow Token (`ya29.`) by opening a secure Chromium browser overlay to `https://labs.google/fx/tools/flow`.
-- **Guidelines:**
-  1. This opens a Chromium window automatically.
-  2. The user must click **"Create with Flow"** and login if requested.
-  3. The tool captures the underlying Bearer Token from network traffic.
-  4. After extraction, apply the token with `veogent setup-flow --flowkey "<token>"`.
-- **Example:**
-  ```bash
-  veogent obtain-flow
-  # Then:
-  veogent setup-flow --flowkey "ya29.a0AW..."
-  ```
+### 3 Commands:
 
----
+**Add character to project (no image yet):**
+```bash
+veogent add-character --project X --name "Bella" --type character
+```
+Entity types: `character`, `creature`, `location`, `visual_asset`, `faction`, `generic_troop`
 
-## 💡 The Complete VEOGENT Pipeline
+**Generate reference image (first time):**
+```bash
+veogent generate-character --project X --character bella \
+  --prompt "A small white Bichon Frisé wearing a pink blazer, regal and confident"
+```
+→ This image defines how the character looks in ALL scenes
 
-Follow this 11-step production pipeline for end-to-end AI movie generation:
+**Edit existing reference image:**
+```bash
+veogent edit-character --project X --character bella \
+  --prompt "change blazer color to red"
+```
+→ Modifies existing image directly (preserves identity)
 
-### Step 0: Resolve IDs
-If not provided by the user, fetch style/template IDs first:
+**List characters + check readiness:**
 ```bash
-veogent custom-prompts     # → get customPromptId
-veogent image-materials    # → get material ID (default: CINEMATIC)
+veogent characters <projectId>
+# → allReady === true means all characters have reference images
 ```
 
-### Step 1: Prepare Story Input
-Build your story arc, summary, and key notes **before** making API calls. This is the creative foundation.
+**Rules:**
+- Characters from `--idea` are auto-created (no manual add needed)
+- `add-character` only for characters NOT in original --idea
+- ⚠️ NEVER edit-character mid-project when scenes already generated
+- More references = better consistency (locations, props, troops too)
+- Mention a reference name in edit-scene → that entity appears in the scene
 
-### Step 2: Description First
-Generate an AI description from story input, then use that payload for project creation:
+---
+
+## Video Generation
+
+**Single scene:**
 ```bash
-veogent create-project-description --keyword "keywords" --lang "English" --promptId "promptId"
-# Use the returned description in create-project
+veogent request --type GENERATE_VIDEO --project X --chapter Y --scene Z \
+  --videomodel veo_3_1_fast --orientation VERTICAL --wait
 ```
 
-### Step 3: Create Project
+**Batch all scenes:**
 ```bash
-veogent create-project --name "Name" --keyword "keywords" --desc "AI-generated description" --lang "English" --material "CINEMATIC" --chapters 5
+veogent batch-request --type GENERATE_VIDEO --project X --chapter Y \
+  --all --orientation VERTICAL --wait
 ```
 
-### Step 4: Chapter & Scene Content
-Generate chapter narrative content, then **immediately** pass the returned `chapterContent` array to `create-scene`:
-```bash
-veogent create-chapter-content --project <projId> --chapter <chapId> --scenes 5
-# → { "status": "success", "chapterContent": ["scene 1...", "scene 2...", ...] }
-# Use chapterContent directly — do NOT poll chapter state
+### Speed Modes
 
-veogent create-scene --project <projId> --chapter <chapId> --content "script 1" "script 2" "script 3" --flowkey
-```
+| Mode | Flag | Use case |
+|------|------|----------|
+| Normal | `--speed normal` (default) | Most scenes |
+| Timelapse | `--speed timelapse` | Sunrise, cooking montage, traffic, cloud movement |
+| Slow motion | `--speed slowmotion` | Impact, water splash, dramatic reveal, emotional beat |
 
-### Step 4b: Verify Scene Materialization
-After `create-scene`, scenes appear incrementally. Poll until ready:
 ```bash
-veogent scene-materialization-status --project <projId> --chapter <chapId>
-# Poll until: { "status": "READY", "expectedScenes": N, "materializedScenes": N }
+veogent request --type GENERATE_VIDEO --project X --chapter Y --scene Z \
+  --speed slowmotion --videomodel veo_3_1_fast --orientation VERTICAL --wait
 ```
 
-### Step 5: Await Character Casting (⚠️ CRITICAL)
-The system **auto-generates characters**. Do NOT rush to image/video generation.
-```bash
-# Poll until characterReadiness.allReady === true
-veogent characters <projectId>
-# → { "characterReadiness": { "total": 4, "ready": 4, "allReady": true } }
+### Chained Video (endScene)
 
-# Alternative: check project progress object
-veogent project <projectId>
-# Look at: progress → if FAILED/PROCESSING/PENDING, wait. Avoid spam retries.
+Smooth transition between two consecutive scenes:
+```bash
+veogent request --type GENERATE_VIDEO --project X --chapter Y --scene sceneA \
+  --endscene sceneB --videomodel veo_3_1_fast --orientation VERTICAL --wait
 ```
+Uses sceneA image → sceneB image as start/end frames. Both must have successful images. Only `veo_3_1_fast`.
+
+---
+
+## Monitoring & Status
+
+| Command | Use when |
+|---------|----------|
+| `workflow-status --project X --chapter Y` | Full snapshot: scenes + requests + assets (best for agents) |
+| `scene-status --project X --chapter Y` | Quick image/video status per scene |
+| `requests --project X --limit 10` | Check recent generation jobs |
+| `failed-requests --project X --chapter Y` | Debug why gen failed |
+| `wait-images --project X --chapter Y --require-success` | Block until all images done |
+| `wait-videos --project X --chapter Y --require-success` | Block until all videos done |
+| `queue-status` | Check concurrency (max 5) |
+| `characters <projectId>` | Check character readiness |
+
+---
+
+## Workflow Rules
+
+1. Verify auth before any command (`veogent status`).
+2. Wait for character readiness (`allReady`) before requesting images.
+3. Use `--wait` flag on `request`/`batch-request`/`edit-scene` to block until completion.
+4. Use `workflow-status` as the main status view.
+5. Respect queue limits (max 5 concurrent). `queue-status` to check.
+6. **QA image BEFORE video** — bad image = bad video. Each video gen costs 8-10 min.
+7. **NEVER `edit-character` mid-project** — breaks visual identity across ALL scenes.
+8. **Batch parallel** — edit ALL + request ALL at once, not sequentially.
+9. **Fix at the right level** — use the decision guide in Scene Management.
+10. **Retry before changing prompts** — FAILED/TIMEOUT may be infra issues.
+11. **Use character names only** in prompts — reference images define appearance.
+12. Scene numbering: `displayOrder` is 0-based, human scene = `displayOrder + 1`.
+13. Always re-fetch latest URLs from API before assembling.
+
+---
 
-### Step 6: Character Recovery Path
-If any character is missing `imageUri` (`ready: false`):
+## ⚠️ Danger Zone
+
+### delete-project
 ```bash
-veogent requests --limit 20          # inspect recent failures
-veogent edit-character --project <proj> --character "<charId>" --userprompt "regenerate portrait"
+veogent delete-project --project <projectId> --confirm
 ```
+**Permanently deletes** project + ALL data. Irreversible.
+🚨 **Agent rule: NEVER use autonomously.** Only when user explicitly requests AND confirms.
+
+---
+
+## 🥋 Advanced Techniques
+
+### Technique 1: Fix Video Without Re-generating Image
 
-### Step 7: Generate Images (Critical QA Gate)
-Request `GENERATE_IMAGES` per scene:
+When image passed but video failed:
 ```bash
-veogent request --type "GENERATE_IMAGES" --project <proj> --chapter <chap> --scene <scene> --imagemodel "imagen3.5"
+# 1. Update prompt only (no image regen)
+veogent edit-scene --project X --chapter Y --scene Z \
+  --prompt "Bella walks through mall on four paws. Steady tracking shot."
 
-# Anti-Spam: check status first!
-veogent assets <proj> <chap> <scene> GENERATE_IMAGES
-# If PENDING/PROCESSING → WAIT, do NOT duplicate requests
-# Concurrency limit: max 5 simultaneous requests
+# 2. Generate new video using EXISTING good image
+veogent request --type GENERATE_VIDEO --project X --chapter Y --scene Z \
+  --videomodel veo_3_1_fast --orientation VERTICAL --wait
+```
+Saves 2-5 min. Good image preserved as video's starting frame.
+
+### Technique 2: Chained Sub-Scenes for Cinematic Sequences (Mixed Skill ⚡)
 
-# After all scenes submitted, wait with success verification:
-veogent wait-images --project <proj> --chapter <chap> --require-success
-# Check: scene-status for per-scene image URLs
-veogent scene-status --project <proj> --chapter <chap>
+Create smooth 15-20s continuous sequences from a single scene's image:
+
+```
+Scene 1: Good image (passed QA)
+    │
+    ├─ insert-scene 1.1 (after scene 1)
+    │   └─ edit-scene 1.1 --request <scene1_requestId>
+    │      --prompt "camera shifts to reveal escalator"
+    │      → Edits scene 1's image → scene 1.1 inherits environment
+    │
+    ├─ Chain video: scene 1 → scene 1.1
+    │   └─ request --type GENERATE_VIDEO --scene scene1 --endscene scene1.1
+    │
+    ├─ insert-scene 1.2 (after scene 1.1)
+    │   └─ edit-scene 1.2 --request <scene1.1_requestId>
+    │      --prompt "steps off escalator at food court"
+    │
+    └─ Chain video: scene 1.1 → scene 1.2
 ```
 
-### Step 8: AI Review on Image Mismatch
-If a generated image is reported as incorrect:
-1. Decode/export the image to Base64 and send to an AI reviewer agent for visual evaluation.
-2. If mismatch confirmed → refine prompt:
-   ```bash
-   veogent edit-scene --project <proj> --chapter <chap> --scene <scene> --userprompt "refined prompt..."
-   ```
-3. For direct correction on a specific generated image:
-   ```bash
-   veogent edit-scene --project <proj> --chapter <chap> --scene <scene> --userprompt "make the car red" --request <requestId>
-   ```
-
-### Step 9: Art Directing & QA
-Continue the visual QA loop until the scene image is **director-approved**. Iterate between `edit-scene` and `GENERATE_IMAGES` as needed.
-
-### Step 10: Animate
-Only run `GENERATE_VIDEO` **after** the scene already has a successful matching-orientation image:
+**Step-by-step:**
 ```bash
-veogent request --type "GENERATE_VIDEO" --project <proj> --chapter <chap> --scene <scene> \
-  --videomodel "veo_3_1_fast" --speed "normal" --imagemodel "imagen3.5" --orientation "HORIZONTAL"
+# 1. Get scene 1's requestId
+veogent workflow-status --project X --chapter Y
 
-# Wait for all videos with success verification:
-veogent wait-videos --project <proj> --chapter <chap> --require-success
-# Full snapshot:
-veogent workflow-status --project <proj> --chapter <chap>
+# 2. Insert sub-scene
+veogent insert-scene --project X --chapter Y \
+  --prompt "Camera follows Bella inside mall" --after <scene1_id>
+
+# 3. Edit sub-scene image FROM scene 1's image
+veogent edit-scene --project X --chapter Y --scene <scene1.1_id> \
+  --prompt "Same mall entrance, camera shifts right to reveal escalator" \
+  --request <scene1_requestId> --wait
+
+# 4. Chain video
+veogent request --type GENERATE_VIDEO --project X --chapter Y \
+  --scene <scene1_id> --endscene <scene1.1_id> \
+  --videomodel veo_3_1_fast --orientation VERTICAL --wait
+
+# 5. Continue: insert 1.2, edit from 1.1, chain 1.1→1.2...
 ```
 
-### Step 11: YouTube Publishing Assets
-Finalize with metadata and thumbnails:
+**Why powerful:** Each sub-scene inherits environment via direct image edit. endScene chaining = smooth continuous motion. One good image → entire cinematic sequence.
+
+### Technique 3: Speed Mode for Storytelling
+
 ```bash
-veogent generate-yt-metadata --project <proj> --chapter <chap> --lang "English"
-veogent generate-yt-thumbnail --project <proj> --chapter <chap> --lang "English"
-veogent yt-thumbnails <proj> <chap>
+# Timelapse: passage of time
+veogent request --type GENERATE_VIDEO --project X --chapter Y --scene Z \
+  --speed timelapse --wait
+
+# Slowmotion: dramatic emphasis
+veogent request --type GENERATE_VIDEO --project X --chapter Y --scene Z \
+  --speed slowmotion --wait
 ```
 
 ---
 
-## ⚠️ Error Handling
-
-The CLI returns JSON for all responses:
-
-| Pattern | Meaning | Action |
-|---------|---------|--------|
-| `{"status": "success", ...}` | Operation completed | Proceed to next step |
-| `{"status": "error", "message": "..."}` | Operation failed | Read the message, fix inputs, retry |
-| `{"error": "Not logged in"}` | No valid auth token | Have user run `veogent login` |
-| `400 Bad Request` | Invalid flags/payload for DTO | Review your flags — likely passing prohibited options for the request type |
-| `401` / Flow error | Flow Key expired | Get new key via `veogent obtain-flow` or user, then `veogent setup-flow` |
-| `"maximum request limit reached"` | Queue full (5 max concurrent) | Wait and retry later — not a hard failure |
+## Command Reference
+
+### Project Commands
+
+| Command | Description | Key Options |
+|---------|-------------|-------------|
+| `create-project` | Create project (auto-gen description from --idea) | `--idea`, `--name`, `--lang`, `--material`, `--chapters` |
+| `projects` | List all projects | — |
+| `project <id>` | Get project details | — |
+| `delete-project` | ⚠️ Delete project permanently | `--project`, `--confirm` |
+
+### Chapter Commands
+
+| Command | Description | Key Options |
+|---------|-------------|-------------|
+| `chapters <projectId>` | List chapters | — |
+| `recent-chapters` | Recently updated chapters | `--limit` |
+| `create-chapter-content` | Generate storyboard via AI | `--project`, `--chapter`, `--scenes` |
+
+### Scene Commands
+
+| Command | Description | Key Options |
+|---------|-------------|-------------|
+| `create-scene` | Create scenes from storyboard | `--project`, `--chapter`, `--content`, `--flowkey` |
+| `insert-scene` | Insert single scene into chapter | `--project`, `--chapter`, `--prompt`, `--after` |
+| `edit-scene` | Edit prompt or regen image | `--project`, `--chapter`, `--scene`, `--prompt`, `--request`, `--wait` |
+| `scenes <proj> <chap>` | List all scenes | — |
+
+### Character Commands
+
+| Command | Description | Key Options |
+|---------|-------------|-------------|
+| `add-character` | Add character (no image) | `--project`, `--name`, `--type` |
+| `generate-character` | Gen reference image (first time) | `--project`, `--character`, `--prompt` |
+| `edit-character` | Edit existing reference image | `--project`, `--character`, `--prompt` |
+| `characters <projectId>` | List + readiness check | — |
+
+### Generation Commands
+
+| Command | Description | Key Options |
+|---------|-------------|-------------|
+| `request` | Single generation job | `--type`, `--project`, `--chapter`, `--scene`, `--orientation`, `--speed`, `--endscene`, `--wait` |
+| `batch-request` | Batch generation | `--type`, `--project`, `--chapter`, `--all`/`--scenes`, `--orientation`, `--speed`, `--wait` |
+
+### Monitoring Commands
+
+| Command | Description | Key Options |
+|---------|-------------|-------------|
+| `workflow-status` | Full snapshot (best for agents) | `--project`, `--chapter` |
+| `scene-status` | Per-scene image/video status | `--project`, `--chapter` |
+| `requests` | List generation jobs | `--project`, `--chapter`, `--status`, `--limit` |
+| `failed-requests` | Failed jobs only | `--project`, `--chapter` |
+| `wait-images` | Poll until images done | `--project`, `--chapter`, `--require-success` |
+| `wait-videos` | Poll until videos done | `--project`, `--chapter`, `--require-success` |
+| `queue-status` | Concurrency check | — |
+
+### Auth & Config
+
+| Command | Description | Key Options |
+|---------|-------------|-------------|
+| `login` | Authenticate | `--device` (headless) |
+| `logout` | Clear credentials | — |
+| `status` | Session + Flow Key info | — |
+| `setup-flow` | Setup Google Flow Key | `--flowkey`, `--tier` |
+| `obtain-flow` | Auto-extract Flow Token | — |
+| `flow-credits` | Check plan + credits | `--flowkey` |
+
+### YouTube
+
+| Command | Description | Key Options |
+|---------|-------------|-------------|
+| `generate-yt-metadata` | Generate Title/Desc/Tags | `--project`, `--chapter`, `--lang` |
+| `generate-yt-thumbnail` | Trigger thumbnail gen | `--project`, `--chapter`, `--lang` |
+| `yt-thumbnails <proj> <chap>` | Get generated thumbnails | — |
+
+### Discovery
+
+| Command | Description |
+|---------|-------------|
+| `image-materials` | List available image styles |
+| `custom-prompts` | List custom prompt templates |