veogent 1.0.15 → 1.0.16

package/README.md

@@ -76,7 +76,7 @@ Queue generation jobs directly from the terminal.
 *Note: VEOGENT uses strict validation depending on the request type.*
 
 ```bash
-# Generate Image (Supports: imagen4, imagen3.5)
+# Generate Image (Supports: imagen3.5)
 veogent request -t "GENERATE_IMAGES" -p <proj> -c <chap> -s <scene> -i "imagen4"
 
 # Generate Video (Supports: veo_3_1_fast, veo_3_1_fast_r2v)
@@ -94,12 +94,7 @@ veogent upscale -p <proj> -c <chap> -s <scene> -o "VERTICAL" -r "VIDEO_RESOLUTIO
 
 ## 🤖 For AI Agents
 
-Veogent CLI comes with a built-in guide optimized for LLM/Coding Agents context processing. Just run:
-
-```bash
-veogent skill
-```
-This prints out a comprehensive Markdown `SKILL.md` cheat sheet defining our exact DTO validations, model enumerations, logic pipelines, and required variables for orchestrating complete projects without hitting `400 Bad Request`.
+Veogent CLI ships with a comprehensive **[`skills/SKILL.md`](./skills/SKILL.md)** guide optimized for LLM/Coding Agents context processing. It defines exact DTO validations, model enumerations, camera prompting techniques, the full production pipeline, and error handling — everything an agent needs to orchestrate complete projects without hitting `400 Bad Request`.
 
 ### Recommended Agent Workflow (Production)
 
@@ -127,6 +122,8 @@ This prints out a comprehensive Markdown `SKILL.md` cheat sheet defining our exa
 9. Generate video only after matching-orientation image exists successfully:
    - `veogent request -t "GENERATE_VIDEO" ...`
 
+> 📖 For the full detailed guide with all commands, options tables, and examples, see **[`skills/SKILL.md`](./skills/SKILL.md)**.
+
 **Important:** `veogent requests` is the primary status board for image/video/edit workflows.
 
 **Concurrency:** maximum **5** requests can be processed simultaneously. If the API reports maximum limit reached, treat it as queue-full (wait/retry), not a hard failure.

package/index.js

@@ -473,115 +473,6 @@ program
     });
 
 // --- System ---
-program
-    .command('skill')
-    .description('Print the native Agent SKILL.md guide for VEOGENT CLI')
-    .action(() => {
-        const skillContent = `# VEOGENT CLI Agent Skill
-
-The \`veogent\` command-line interface interacts with the VEOGENT API for managing movie/story projects, chapters, scenes, and media generation requests (images, videos). 
-This CLI is designed with AI agents in mind: all data outputs are in raw JSON format for easy parsing and chaining.
-
-## 🛠 Authentication & Configuration
-Agents **CANNOT** authenticate automatically because \`veogent login\` opens a local browser for Google Firebase OAuth.
-*   **Check Auth & Config:** \`veogent status\`
-*   **Setup Integration:** If a new Google Flow token needs to be applied, use \`veogent setup-flow -f "ya29.xx" -t "PAYGATE_TIER_TWO"\`.
-    *(Note: If any VEOGENT API request fails with a \`"status code 401"\` Flow error, the Flow Key has expired. Prompt the user for a new key and update it via \`setup-flow\` before retrying).*
-*   **Action:** If status returns \`{"error": "Not logged in"}\`, instruct the user to run \`veogent login\` on their desktop terminal manually. Wait for them to confirm success.
-
-## 📁 Projects & Assets
-*   **List Image Materials:** \`veogent image-materials\` (e.g., \`CINEMATIC\`, \`PIXAR_3D\`) -> *(Call this to get allowed material options before creating a project).*
-*   **List Custom Prompts:** \`veogent custom-prompts\` -> *(Call this to find a matching ID if a custom stylistic prompt is needed).*
-*   **List Projects:** \`veogent projects\` 
-    *   *Note: IDs are Firebase Document Strings (e.g., \`APQF6Ay0kLeXLhpctTdD\`), not simple integers. Always use the field \`"id"\` from the JSON response array.*
-*   **Get Project Details:** \`veogent project <projectId>\`
-*   **Create Project:** \`veogent create-project -n "Name" -k "Scifi" -d "Description" -l "English" -m "Anime style" -c 1 -C "customPromptId"\`
-    *(Requires image material. Optionally pass \`-C <customPromptId>\` if listed via \`custom-prompts\`)*
-
-## 📖 Chapters & Scenes
-*   **List Chapters for a Project:** \`veogent chapters <projectId>\`
-*   **List Recent Chapters globally:** \`veogent recent-chapters -l 5\`
-*   **List Scenes for a Chapter:** \`veogent scenes <projectId> <chapterId>\`
-*   **Create Chapter Content:** \`veogent create-chapter-content -p <projectId> -c <chapterId> -s 5\` (Generates text/story content for 5 scenes)
-*   **Create Scene (from script list):** \`veogent create-scene -p <projectId> -c <chapterId> -C "scene script 1" "scene script 2" --flowkey\`
-
-## 🎬 Generation Requests
-To initiate generation jobs, use \`veogent request\`. 
-**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\`.
-
-1.  **Generate Images** (\`GENERATE_IMAGES\`):
-    *   **Required Options:** \`-t GENERATE_IMAGES\`, \`-p <proj>\`, \`-c <chap>\`, \`-s <scene>\`, \`-i <imagemodel>\`
-    *   **Allowed Models:** \`imagen4\`, \`imagen3.5\`
-    *   **Prohibited:** Do NOT pass \`-o\` (orientation) or \`-v\` (videomodel) or \`-S\` (speed).
-    *   \`veogent request -t "GENERATE_IMAGES" -p "projID" -c "chapID" -s "sceneID" -i "imagen4"\`
-
-2.  **Generate Video** (\`GENERATE_VIDEO\`):
-    *   **Required Options:** \`-t GENERATE_VIDEO\`, \`-p <proj>\`, \`-c <chap>\`, \`-s <scene>\`, \`-v <videomodel>\`, \`-S <speed>\`, \`-i <imagemodel>\`, \`-o <orientation>\`
-    *   **Optional Option:** \`-E <endSceneId>\` (to connect/interpolate to the next frame directly).
-    *   **Allowed Models:** \`veo_3_1_fast\`, \`veo_3_1_fast_r2v\`
-    *   **Default Model (recommended):** \`veo_3_1_fast\`
-    *   **Allowed Speeds:** \`normal\`, \`timelapse\`, \`slowmotion\`
-    *   **Rule:** \`useFlowKey\` is locked natively to true. You must pass orientation and imageModel for video context.
-    *   \`veogent request -t "GENERATE_VIDEO" -p "projID" -c "chapID" -s "sceneA" -E "sceneB" -o "VERTICAL" -i "imagen3.5" -v "veo_3_1_fast" -S "normal"\`
-
-3.  **Video Upscale** (\`VIDEO_UPSCALE\`):
-    *   **Required Options:** \`-t VIDEO_UPSCALE\`, \`-p <proj>\`, \`-c <chap>\`, \`-s <scene>\`, \`-o <orientation>\`
-    *   **Allowed Orientations:** \`HORIZONTAL\`, \`VERTICAL\`
-    *   **Prohibited:** Do NOT pass \`-i\` (image model) or \`-v\` (video model).
-    *   \`veogent request -t "VIDEO_UPSCALE" -p "projID" -c "chapID" -s "sceneID" -o "HORIZONTAL"\`
-    *   **Shortcut command:** \`veogent upscale -p <proj> -c <chap> -s <scene> -o VERTICAL -r VIDEO_RESOLUTION_4K\`
-
-## 🖌️ Character Editing
-Characters generated within a project can be updated or re-sketched via text prompts using \`veogent edit-character\`.
-*   **List all Characters in a Project:** 
-    *   \`veogent characters <projectId>\`
-*   **Regenerate Character Profile:** (Updates description/traits and generates a new portrait base)
-    *   \`veogent edit-character -p <proj> -c "drelenavance" -u "change outfit to lab coat"\`
-*   **Direct Image Edit Mode:** (Applies changes directly to the existing generated portrait)
-    *   \`veogent edit-character -p <proj> -c "drelenavance" -u "change shoe to black" -e\`
-
-## 🖌️ Scene Editing
-If a generated image prompt needs adjustment by the AI, use \`veogent edit-scene\` to hit the \`updateScriptSegment\` workflow:
-*   **Context:** Note that you are editing the Image Prompt for **Frame 0 (the starting image)** used for video generation. 
-*   **Prompting Guide:** Beside the main visual description, you CAN include minor action descriptions (e.g., "bus speeding over cliff", "smoke rising"). You SHOULD heavily leverage Camera Angles and Camera Movements to steer the frame composition:
-    *   **Shot Types:** Close-up (Cận cảnh), Wide shot (Toàn cảnh), Medium shot (Trung cảnh), Extreme close-up (Cận mặt), Long shot (Tầm trung xa).
-    *   **Angles:** High angle (Góc cao), Low angle (Góc thấp), Bird-eye (Góc chim), Eye-level (Góc ngang mắt), Over-the-shoulder, POV.
-    *   **Camera Tracking:** Pan left (←), Pan right (→), Tilt up (↑), Tilt down (↓), Zoom in (+), Zoom out (-).
-*   **Modify Image Prompt (Default creates auto-regen):**
-    *   \`veogent edit-scene -p <proj> -c <chap> -s <scene> -u "Low angle shot of a yellow school bus speeding over a cliff, wide angle, dramatic lighting. Camera tilts down."\`
-*   **Modify Image Prompt (Cancel Auto-Regen):**
-    *   \`veogent edit-scene -p <proj> -c <chap> -s <scene> -u "child seat behind Paulo" --no-regenerate\`
-*   **Edit a specific past generated image:** Pass the previous generated \`requestId\` using \`-R\`.
-    *   \`veogent edit-scene -p <proj> -c <chap> -s <scene> -u "make the car red" -R <requestId>\`
-
-*   **List All Generation Requests/Jobs Status:** \`veogent requests\`
-    *   This is the primary status board for generation workflows (image/video/character-edit related jobs). Always check this before retries.
-
-## 💡 Best Practices for AI Agents (The VEOGENT Pipeline)
-0. **Step 0: Resolve IDs first.** If not provided, fetch style IDs:
-   - \`veogent custom-prompts\` (custom prompt ID)
-   - \`veogent image-materials\` (material ID; \`CINEMATIC\` is an acceptable default)
-1. **Step 1: Prepare story input.** Build story arc + summary + key notes before API calls.
-2. **Step 2: Description First.** Run \`veogent create-project-description\` from the story input, then use that payload for \`veogent create-project\`.
-3. **Step 3: Chapter & Scene Content.** Run \`veogent create-chapter-content -s <sceneCount>\` (each scene maps to ~8s clip), then IMMEDIATELY pass the returned scene-script array to \`veogent create-scene ... -C ... --flowkey\`.
-4. **Step 4: Await Casting (CRITICAL).** The system auto-generates characters. Do NOT rush to image/video generation. Poll \`veogent characters <projectId>\` until EVERY character has an \`imageUri\`.
-   *(Alternative check: \`veogent project <projectId>\` -> \`progress\` object. If a character is FAILED/PROCESSING/PENDING, wait and avoid spam retries.)*
-5. **Step 5: Character recovery path.** If any character is missing \`imageUri\`, inspect \`veogent requests\` for failure/success, then regenerate with \`veogent edit-character\` where needed.
-6. **Step 6: Generate Images (Critical QA Gate).** Request \`GENERATE_IMAGES\` per scene/orientation.
-   *(Anti-Spam: Use \`veogent assets <projId> <chapId> <sceneId> <type>\`; if status is PENDING/PROCESSING, WAIT and do not duplicate requests.)*
-   *(Concurrency: maximum 5 requests can be processed simultaneously. "maximum request limit reached" means queue-full; wait and retry later.)*
-7. **Step 7: AI Review on image mismatch.** If generated image is reported as incorrect, decode/export the image to Base64 and send it to an AI reviewer agent for visual evaluation.
-   - If review indicates mismatch: refine prompt via \`veogent edit-scene -u "..."\` and regenerate.
-   - For direct correction on a specific generated image, pass prior \`requestId\` via \`veogent edit-scene -R <requestId>\`.
-8. **Step 8: Art Directing & QA.** Continue visual QA loop until scene image is director-approved.
-9. **Step 9: Animate.** Only run \`GENERATE_VIDEO\` after the scene already has a successful matching-orientation image.
-10. **Step 10: YouTube Publishing Assets.** Finalize with \`veogent generate-yt-metadata\` + \`veogent generate-yt-thumbnail\`; retrieve via \`veogent yt-thumbnails <proj> <chap>\`.
-
-**Error Handling:** The CLI returns JSON like \`{"status": "error", "message": "..."}\`. Check this before proceeding with the next logic block. If an API request returns \`400 Bad Request\`, review your flags.`;
-        console.log(skillContent);
-    });
-
 program
     .command('obtain-flow')
     .description('Auto-extract your labs.google Flow Token (ya29.) using a secure browser overlay')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veogent",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "description": "The official CLI to interact with the VEOGENT API - AI Video and Image generation platform",
   "main": "index.js",
   "bin": {

package/skills/SKILL.md

@@ -0,0 +1,585 @@
+---
+name: veogent
+description: Full CLI skill guide for the VEOGENT API — AI-powered movie/story project management, image & video generation, and YouTube publishing.
+---
+
+# 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.
+
+---
+
+## Table of Contents
+
+1. [Authentication & Configuration](#-authentication--configuration)
+2. [Projects & Assets](#-projects--assets)
+3. [Chapters](#-chapters)
+4. [Scenes](#-scenes)
+5. [Characters](#-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 Management](#-flow-token-management)
+11. [The Complete VEOGENT Pipeline (Best Practices)](#-the-complete-veogent-pipeline)
+12. [Error Handling](#-error-handling)
+
+---
+
+## 🔐 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 |
+  |------|----------|-------------|---------|
+  | `-f, --flowkey <key>` | ✅ | The Google access token (ya29...) | — |
+  | `-t, --tier <tier>` | ❌ | User payment tier | `PAYGATE_TIER_TWO` |
+- **Example:**
+  ```bash
+  veogent setup-flow -f "ya29.a0AW..." -t "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 -f "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 |
+  |------|----------|-------------|
+  | `-k, --keyword <keyword>` | ✅ | Keywords for the project |
+  | `-l, --lang <lang>` | ✅ | Story language (e.g., `English`, `Vietnamese`) |
+  | `-p, --promptId <promptId>` | ✅ | Custom Prompt ID from `custom-prompts` |
+- **Example:**
+  ```bash
+  veogent create-project-description -k "T-rex, Neon, Tokyo" -l "English" -p "promptId123"
+  ```
+
+### Skill: `create-project`
+- **Description:** Create a new AI movie/story project with full configuration.
+- **Options:**
+  | Flag | Required | Description | Default |
+  |------|----------|-------------|---------|
+  | `-n, --name <name>` | ✅ | Project name | — |
+  | `-k, --keyword <keyword>` | ✅ | Keywords | — |
+  | `-d, --desc <desc>` | ✅ | Description (use output from `create-project-description`) | — |
+  | `-l, --lang <lang>` | ✅ | Story language | — |
+  | `-s, --sound` | ✅ | Sound effects | `true` |
+  | `-m, --material <material>` | ✅ | Image material (from `image-materials`) | — |
+  | `-c, --chapters <count>` | ✅ | Number of chapters | `1` |
+  | `-C, --customPromptId <id>` | ❌ | Custom Prompt ID | — |
+- **Example:**
+  ```bash
+  veogent create-project -n "Cyberpunk T-Rex" -k "T-rex, Neon, Sci-fi" \
+    -d "A massive T-rex walking inside Tokyo at night..." \
+    -l "English" -m "CINEMATIC" -c 5
+  ```
+
+---
+
+## 📖 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 |
+  |------|----------|-------------|---------|
+  | `-l, --limit <limit>` | ❌ | Maximum number of recent chapters to return | `10` |
+- **Example:**
+  ```bash
+  veogent recent-chapters -l 5
+  ```
+
+### Skill: `create-chapter-content`
+- **Description:** Generate AI story/narrative content for a specific chapter, producing scene scripts.
+- **Guidelines:** Each scene maps to approximately an **~8-second video clip**. The returned scene-script array should be **immediately** passed to `create-scene`.
+- **Options:**
+  | Flag | Required | Description | Default |
+  |------|----------|-------------|---------|
+  | `-p, --project <project>` | ✅ | Project ID | — |
+  | `-c, --chapter <chapter>` | ✅ | Chapter ID | — |
+  | `-s, --scenes <count>` | ✅ | Number of scenes to generate | `1` |
+- **Example:**
+  ```bash
+  veogent create-chapter-content -p "projID" -c "chapID" -s 5
+  ```
+
+---
+
+## 🎬 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 |
+  |------|----------|-------------|---------|
+  | `-p, --project <project>` | ✅ | Project ID | — |
+  | `-c, --chapter <chapter>` | ✅ | Chapter ID | — |
+  | `-C, --content <content...>` | ✅ | Array of scene text scripts | — |
+  | `--flowkey` | ❌ | Enable useFlowKey to sync context via Firebase | `false` |
+- **Example:**
+  ```bash
+  veogent create-scene -p "projID" -c "chapID" \
+    -C "The T-Rex looks up at the sky." "A meteor shower begins." "Explosions rock the city." \
+    --flowkey
+  ```
+
+---
+
+## 🧑‍🎨 Characters
+
+### Skill: `characters`
+- **Description:** Get all characters for a specific project, including their `imageUri` status.
+- **Guidelines:** After creating scenes, the system **auto-generates characters**. Poll this command until every character has an `imageUri` before proceeding to image/video generation.
+- **Example:**
+  ```bash
+  veogent characters <projectId>
+  ```
+
+### 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** (`-e` flag): Applies changes directly to the existing generated portrait image via in-painting.
+- **Options:**
+  | Flag | Required | Description | Default |
+  |------|----------|-------------|---------|
+  | `-p, --project <project>` | ✅ | Project ID | — |
+  | `-c, --character <character>` | ✅ | Character ID (e.g., `drelenavance`) | — |
+  | `-u, --userprompt <userprompt>` | ✅ | User instruction to modify the character | — |
+  | `-e, --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 -p "projID" -c "drelenavance" -u "change outfit to lab coat"
+
+  # Direct image edit (in-paint on existing portrait)
+  veogent edit-character -p "projID" -c "drelenavance" -u "change shoes to black boots" -e
+  ```
+
+---
+
+## 🖌️ 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 `-R`.
+
+#### 📐 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 |
+  |------|----------|-------------|
+  | `-p, --project <project>` | ✅ | Project ID |
+  | `-c, --chapter <chapter>` | ✅ | Chapter ID |
+  | `-s, --scene <scene>` | ✅ | Scene ID |
+  | `-u, --userprompt <userprompt>` | ✅ | User narrative prompt to modify the scene |
+  | `--no-regenerate` | ❌ | Skip auto-regeneration of image |
+  | `-R, --request <request>` | ❌ | Target a specific past Request ID to edit its output |
+
+- **Examples:**
+  ```bash
+  # Modify image prompt (auto-regenerates)
+  veogent edit-scene -p "projID" -c "chapID" -s "sceneID" \
+    -u "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 -p "projID" -c "chapID" -s "sceneID" \
+    -u "child seat behind Paulo" --no-regenerate
+
+  # Edit a specific past generated image directly
+  veogent edit-scene -p "projID" -c "chapID" -s "sceneID" \
+    -u "make the car red" -R "requestId123"
+  ```
+
+---
+
+## 🎬 Generation Requests
+
+### 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`.
+
+#### 1. Generate Images (`GENERATE_IMAGES`)
+
+| Flag | Required | Description | Allowed Values |
+|------|----------|-------------|----------------|
+| `-t, --type` | ✅ | `GENERATE_IMAGES` | — |
+| `-p, --project` | ✅ | Project ID | — |
+| `-c, --chapter` | ✅ | Chapter ID | — |
+| `-s, --scene` | ✅ | Scene ID | — |
+| `-i, --imagemodel` | ✅ | Image model | `imagen4`, `imagen3.5` |
+
+> 🚫 **Prohibited flags:** Do NOT pass `-o` (orientation), `-v` (videomodel), or `-S` (speed).
+
+```bash
+veogent request -t "GENERATE_IMAGES" -p "projID" -c "chapID" -s "sceneID" -i "imagen4"
+```
+
+#### 2. Generate Video (`GENERATE_VIDEO`)
+
+| Flag | Required | Description | Allowed Values |
+|------|----------|-------------|----------------|
+| `-t, --type` | ✅ | `GENERATE_VIDEO` | — |
+| `-p, --project` | ✅ | Project ID | — |
+| `-c, --chapter` | ✅ | Chapter ID | — |
+| `-s, --scene` | ✅ | Scene ID | — |
+| `-v, --videomodel` | ✅ | Video model | `veo_3_1_fast` (recommended), `veo_3_1_fast_r2v` |
+| `-S, --speed` | ✅ | Video speed | `normal`, `timelapse`, `slowmotion` |
+| `-i, --imagemodel` | ✅ | Image model for video context | `imagen4`, `imagen3.5` |
+| `-o, --orientation` | ✅ | Orientation | `HORIZONTAL`, `VERTICAL` |
+| `-E, --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.
+
+```bash
+veogent request -t "GENERATE_VIDEO" -p "projID" -c "chapID" -s "sceneA" \
+  -E "sceneB" -o "VERTICAL" -i "imagen3.5" -v "veo_3_1_fast" -S "normal"
+```
+
+#### 3. Video Upscale (`VIDEO_UPSCALE`)
+
+| Flag | Required | Description | Allowed Values |
+|------|----------|-------------|----------------|
+| `-t, --type` | ✅ | `VIDEO_UPSCALE` | — |
+| `-p, --project` | ✅ | Project ID | — |
+| `-c, --chapter` | ✅ | Chapter ID | — |
+| `-s, --scene` | ✅ | Scene ID | — |
+| `-o, --orientation` | ✅ | Orientation | `HORIZONTAL`, `VERTICAL` |
+
+> 🚫 **Prohibited flags:** Do NOT pass `-i` (image model) or `-v` (video model).
+
+```bash
+veogent request -t "VIDEO_UPSCALE" -p "projID" -c "chapID" -s "sceneID" -o "HORIZONTAL"
+```
+
+### Skill: `upscale` (Shortcut)
+- **Description:** Shortcut command for upscaling video output for a specific scene.
+- **Options:**
+  | Flag | Required | Description | Default |
+  |------|----------|-------------|---------|
+  | `-p, --project` | ✅ | Project ID | — |
+  | `-c, --chapter` | ✅ | Chapter ID | — |
+  | `-s, --scene` | ✅ | Scene ID | — |
+  | `-o, --orientation` | ❌ | Orientation | `VERTICAL` |
+  | `-r, --resolution` | ❌ | Target resolution | `VIDEO_RESOLUTION_4K` |
+- **Example:**
+  ```bash
+  veogent upscale -p "projID" -c "chapID" -s "sceneID" -o VERTICAL -r VIDEO_RESOLUTION_4K
+  ```
+
+---
+
+## 📊 Monitoring & Status
+
+### Skill: `requests`
+- **Description:** Get all 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. Look for `PENDING`, `PROCESSING`, `SUCCESS`, or `FAILED` statuses.
+- **Example:**
+  ```bash
+  veogent requests
+  ```
+
+### 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
+  ```
+
+---
+
+## 📺 YouTube Metadata & Thumbnails
+
+### Skill: `generate-yt-metadata`
+- **Description:** Generate YouTube metadata (Title, Description, Tags) for a chapter using AI.
+- **Options:**
+  | Flag | Required | Description |
+  |------|----------|-------------|
+  | `-p, --project` | ✅ | Project ID |
+  | `-c, --chapter` | ✅ | Chapter ID |
+  | `-l, --lang` | ✅ | Story language |
+- **Example:**
+  ```bash
+  veogent generate-yt-metadata -p "projID" -c "chapID" -l "English"
+  ```
+
+### Skill: `generate-yt-thumbnail`
+- **Description:** Triggers a request to generate a YouTube thumbnail for a chapter.
+- **Options:**
+  | Flag | Required | Description |
+  |------|----------|-------------|
+  | `-p, --project` | ✅ | Project ID |
+  | `-c, --chapter` | ✅ | Chapter ID |
+  | `-l, --lang` | ✅ | Story language |
+- **Example:**
+  ```bash
+  veogent generate-yt-thumbnail -p "projID" -c "chapID" -l "English"
+  ```
+
+### Skill: `yt-thumbnails`
+- **Description:** Retrieve generated YouTube thumbnails for a chapter.
+- **Example:**
+  ```bash
+  veogent yt-thumbnails <projectId> <chapterId>
+  ```
+
+---
+
+## 🗝️ 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 -f "<token>"`.
+- **Example:**
+  ```bash
+  veogent obtain-flow
+  # Then:
+  veogent setup-flow -f "ya29.a0AW..."
+  ```
+
+---
+
+## 💡 The Complete VEOGENT Pipeline
+
+Follow this 11-step production pipeline for end-to-end AI movie generation:
+
+### Step 0: Resolve IDs
+If not provided by the user, fetch style/template IDs first:
+```bash
+veogent custom-prompts     # → get customPromptId
+veogent image-materials    # → get material ID (default: CINEMATIC)
+```
+
+### Step 1: Prepare Story Input
+Build your story arc, summary, and key notes **before** making API calls. This is the creative foundation.
+
+### Step 2: Description First
+Generate an AI description from story input, then use that payload for project creation:
+```bash
+veogent create-project-description -k "keywords" -l "English" -p "promptId"
+# Use the returned description in create-project
+```
+
+### Step 3: Create Project
+```bash
+veogent create-project -n "Name" -k "keywords" -d "AI-generated description" -l "English" -m "CINEMATIC" -c 5
+```
+
+### Step 4: Chapter & Scene Content
+Generate chapter narrative content, then **immediately** pass the returned scene-script array to `create-scene`:
+```bash
+veogent create-chapter-content -p <projId> -c <chapId> -s 5
+# Each scene ≈ 8-second clip
+
+veogent create-scene -p <projId> -c <chapId> -C "script 1" "script 2" "script 3" --flowkey
+```
+
+### Step 5: Await Character Casting (⚠️ CRITICAL)
+The system **auto-generates characters**. Do NOT rush to image/video generation.
+```bash
+# Poll until EVERY character has an imageUri
+veogent characters <projectId>
+
+# Alternative: check project progress object
+veogent project <projectId>
+# Look at: progress → if FAILED/PROCESSING/PENDING, wait. Avoid spam retries.
+```
+
+### Step 6: Character Recovery Path
+If any character is missing `imageUri`:
+```bash
+veogent requests                # inspect for failure/success
+veogent edit-character -p <proj> -c "<charId>" -u "regenerate portrait"
+```
+
+### Step 7: Generate Images (Critical QA Gate)
+Request `GENERATE_IMAGES` per scene:
+```bash
+veogent request -t "GENERATE_IMAGES" -p <proj> -c <chap> -s <scene> -i "imagen4"
+
+# 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
+```
+
+### 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 -p <proj> -c <chap> -s <scene> -u "refined prompt..."
+   ```
+3. For direct correction on a specific generated image:
+   ```bash
+   veogent edit-scene -p <proj> -c <chap> -s <scene> -u "make the car red" -R <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:
+```bash
+veogent request -t "GENERATE_VIDEO" -p <proj> -c <chap> -s <scene> \
+  -v "veo_3_1_fast" -S "normal" -i "imagen4" -o "HORIZONTAL"
+```
+
+### Step 11: YouTube Publishing Assets
+Finalize with metadata and thumbnails:
+```bash
+veogent generate-yt-metadata -p <proj> -c <chap> -l "English"
+veogent generate-yt-thumbnail -p <proj> -c <chap> -l "English"
+veogent yt-thumbnails <proj> <chap>
+```
+
+---
+
+## ⚠️ 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 |