veogent 1.1.4 → 1.4.0

package/README.md

@@ -10,8 +10,6 @@ Perfectly engineered for **Agentic workflows** — enabling tools like OpenClaw,
 
 ## 🚀 Installation
 
-Install globally via npm:
-
 ```bash
 npm install -g veogent
 ```
@@ -20,23 +18,12 @@ npm install -g veogent
 
 ## 🔐 Authentication
 
-Veogent CLI supports both browser callback login and headless device-code login.
-
 ```bash
-# Browser callback flow (desktop)
-veogent login
-
-# Device-code flow (VM/server/headless — recommended for AI Agents)
-veogent login --device
-
-# Verify your session
-veogent status
-
-# Clear saved credentials
-veogent logout
-
-# Setup/update Google Flow Key (required for video generation & AI features)
-veogent setup-flow --flowkey "ya29.a0AW..." --tier "PAYGATE_TIER_TWO"
+veogent login              # Browser callback (desktop)
+veogent login --device     # Device-code flow (VM/server/headless — recommended for AI Agents)
+veogent status             # Verify session
+veogent logout             # Clear credentials
+veogent setup-flow --flowkey "ya29.a0AW..." --tier "PAYGATE_TIER_TWO"   # Setup Flow Key
 ```
 
 ---
@@ -45,323 +32,234 @@ veogent setup-flow --flowkey "ya29.a0AW..." --tier "PAYGATE_TIER_TWO"
 
 | Flag | Description |
 |------|-------------|
-| `--json` | Output machine-readable JSON only (suppress emoji/human text) |
-| `--agent-safe` | Agent-safe mode — no emoji, no browser surprises, stable output. Auto-enables `--device` for login. |
+| `--json` | Output machine-readable JSON only |
+| `--agent-safe` | Agent-safe mode — no emoji, no browser surprises, stable JSON output |
 | `--version` | Print CLI version |
 
-> **For AI Agents:** always use `--agent-safe` to guarantee deterministic, parseable JSON output with no interactive prompts.
+> **For AI Agents:** always use `--agent-safe` for deterministic, parseable JSON output.
 
 ---
 
-## 📋 Complete Command Reference
-
-### Authentication & Configuration
-
-| Command | Description |
-|---------|-------------|
-| `login` | Login via browser callback or device code flow (`--device`) |
-| `logout` | Clear saved credentials and remove stored access token |
-| `status` | Show authenticated user, Flow Key details, and payment tier |
-| `setup-flow` | Setup/update Google Flow Key and User Payment Tier |
-
-### Capabilities & Discovery
-
-| Command | Description |
-|---------|-------------|
-| `capabilities` | Get backend capabilities (models, orientations, speed modes, queue) |
-| `image-models` | List supported image generation models |
-| `video-models` | List supported video generation models |
-| `image-materials` | Get all available Image Material styles (e.g., `CINEMATIC`, `PIXAR_3D`) |
-| `custom-prompts` | Get custom prompt templates and story directives |
-
-### Project Management
+## 🎯 Recommended Workflow
 
-| Command | Description |
-|---------|-------------|
-| `projects` | List all your available projects |
-| `project <id>` | Get details for a specific project |
-| `create-project-description` | Generate AI description for a new project based on keywords |
-| `create-project` | Create a new project with name, keywords, material, chapters, objects |
-
-### Chapters
+### How VEOGENT Works — The Mental Model
 
-| Command | Description |
-|---------|-------------|
-| `chapters <projectId>` | Get all chapters for a project |
-| `recent-chapters` | Get recently created or updated chapters |
-| `create-chapter-content` | Generate content for a chapter (synchronous AI generation) |
-
-### Characters
-
-| Command | Description |
-|---------|-------------|
-| `characters <projectId>` | Get all characters with readiness info |
-| `edit-character` | Update character description or edit generated image via AI prompt |
-
-### Scenes
-
-| Command | Description |
-|---------|-------------|
-| `scenes <projectId> <chapterId>` | Get all scenes for a chapter |
-| `create-scene` | Create new scene(s) from text content |
-| `add-scene` | Add a single scene to a chapter with a user prompt |
-| `edit-scene` | Edit scene image prompt via AI assistance |
-
-### Generation Requests (Project-scoped)
-
-> **Clarification:** `request` (singular) = **CREATE** a new job. `requests` (plural) = **LIST** existing jobs.
-
-| Command | Description |
-|---------|-------------|
-| `request` | Create a generation job: `GENERATE_IMAGES`, `GENERATE_VIDEO`, or `VIDEO_UPSCALE` |
-| `requests` | List generation requests (filterable by project, chapter, status) |
-| `upscale` | Upscale video output for a scene (shortcut for `request --type VIDEO_UPSCALE`) |
-| `assets <projectId> <chapterId> <sceneId> <type>` | Check generated assets history/status for a scene |
+```
+--idea → AI Description → Project + Characters (reference images)
+                                  → Chapter Content (storyboard)
+                                  → Scenes → Images → Videos
+```
 
-### Standalone Generation (No Project Needed)
+**Key concept:** Names in `--idea` become character/entity references with image URIs at project level. These references ensure visual consistency across ALL chapters and scenes.
 
-> These commands generate images/videos without a project. Ideal for quick one-off generations.
+### The Pipeline (4 Phases)
 
-| Command | Description |
-|---------|-------------|
-| `gen-image` | Generate image from text prompt (standalone, 3 credits, Imagen 3.5) |
-| `gen-video` | Generate video from text prompt (standalone, 5 credits, Veo 3.1 Fast) |
-| `standalone-requests` | List your standalone generation requests |
-| `standalone-request <requestId>` | Get details of a specific standalone request |
+#### Phase 1: Create Project
 
-### Monitoring & Status
+```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
+```
 
-| Command | Description |
-|---------|-------------|
-| `scene-status` | Scene-level status with embedded asset URLs (image + video per scene) |
-| `workflow-status` | Full workflow snapshot: scenes + requests + assets (agent helper) |
-| `scene-materialization-status` | Check how many scenes have materialized for a chapter |
-| `failed-requests` | List failed/error/rejected requests for a project/chapter (agent helper) |
-| `wait-images` | Poll until all image requests in a chapter finish |
-| `wait-videos` | Poll until all video requests in a chapter finish |
-| `queue-status` | Get current queue/concurrency status |
+**What happens internally:**
+1. CLI calls `/app/description` with --idea → VEOGENT AI generates rich story description
+2. CLI calls `/app/project` with rich description → creates project + auto-generates characters from names in --idea
 
-### YouTube Integration
+**--idea rules:**
+- ✅ Include specific names: characters, locations, props, creatures
+- ✅ Include visual traits: "white Bichon Frisé", "black suits", "luxury mall"
+- ❌ Don't be vague: "cute dog shopping" → VEOGENT will invent random characters
+- Names in --idea → appear in storyboard → VEOGENT creates reference images → consistent across N chapters
 
-| Command | Description |
-|---------|-------------|
-| `generate-yt-metadata` | Generate YouTube metadata (Title, Description, Tags) for a chapter |
-| `generate-yt-thumbnail` | Trigger request to generate a YouTube thumbnail |
-| `yt-thumbnails <projectId> <chapterId>` | Get generated YouTube thumbnails for a chapter |
+#### Phase 2: Generate Storyboard + Scenes
 
-### Flow Token & Credits
+```bash
+# Get chapter ID
+veogent chapters <projectId>
 
-| Command | Description |
-|---------|-------------|
-| `obtain-flow` | Auto-extract Flow Token (ya29.) using secure browser overlay |
-| `flow-credits` | Fetch plan and credit info from Google AI Sandbox |
+# Generate storyboard (VEOGENT AI writes scene scripts from the rich description)
+veogent create-chapter-content --project <projectId> --chapter <chapterId> --scenes 5
 
-### Utility
+# Create scenes from storyboard scripts
+veogent create-scene --project <projectId> --chapter <chapterId> \
+  --content "Scene 1 script..." "Scene 2 script..." "Scene 3..." "Scene 4..." "Scene 5..." \
+  --flowkey
 
-| Command | Description |
-|---------|-------------|
-| `skill` | Print the native Agent SKILL.md guide |
+# Wait for materialization (~30s per scene)
+# Poll: veogent scenes <projectId> <chapterId> until all scenes have scriptSegment
 
----
+# Wait for characters to be ready (reference images generated)
+# Poll: veogent characters <projectId> until characterReadiness.allReady === true
+```
 
-## 🛠️ Usage Examples
+  --lang English --material CINEMATIC --scenes 5 --wait
+```
 
-### Project Management
+#### Phase 3: Generate Images + Videos
 
 ```bash
-# List all your active projects
-veogent projects
-
-# View available Image Material styles (e.g., CINEMATIC, PIXAR_3D)
-veogent image-materials
-
-# Create a brand new AI Story Project
-veogent create-project --name "Cyberpunk T-Rex" --keyword "T-rex, Neon, Sci-fi" \
-  --desc "A massive T-rex walking inside Tokyo" --lang "English" --material "CINEMATIC" --chapters 5 \
-  --objects '{"name":"Hero","entityType":"character","description":"brave knight"}'
+# Generate all images
+veogent batch-request --type GENERATE_IMAGES \
+  --project <projectId> --chapter <chapterId> --all \
+  --orientation VERTICAL --wait
+
+# Generate all videos
+veogent batch-request --type GENERATE_VIDEO \
+  --project <projectId> --chapter <chapterId> --all \
+  --orientation VERTICAL --wait
 ```
 
-### Storyboard, Chapters & Scenes
+#### Phase 4: QA + Fix Loop
 
 ```bash
-# Get all chapters within a project
-veogent chapters <projectId>
-
-# View characters (includes readiness info)
-veogent characters <projectId>
-# → { characters: [...], characterReadiness: {total, ready, allReady} }
-
-# Check scene materialization status
-veogent scene-materialization-status --project <projectId> --chapter <chapterId>
-# → { expectedScenes, materializedScenes, status: "PROCESSING"|"READY"|"EMPTY" }
-
-# Create scenes from narrative scripts
-veogent create-scene --project <projectId> --chapter <chapterId> --flowkey \
-  --content "The T-Rex looks up at the sky." "A meteor shower begins."
-
-# Add a single scene to an existing chapter
-veogent add-scene --project <projectId> --chapter <chapterId> \
-  --userprompt "A meteor crashes into the city." --after-scene-id <sceneId>
+# Check results
+veogent workflow-status --project <projectId> --chapter <chapterId>
 ```
 
-### Directing & Editing
+**edit-scene has TWO modes:**
 
+**Mode A — Edit storyboard/prompt only (no image regen):**
 ```bash
-# Edit scene image prompt with camera direction
-veogent edit-scene --project <projectId> --chapter <chapterId> --scene <sceneId> \
-  --userprompt "Low angle shot of the T-Rex, dramatic lighting."
-
-# Edit character image directly via AI
-veogent edit-character --project <projectId> --character "drelenavance" \
-  --userprompt "change outfit to dark leather jacket" --editimage
+veogent edit-scene --project X --chapter Y --scene Z \
+  --prompt "Bella walks through mall on all four paws"
+# Then trigger image gen separately:
+veogent request --type GENERATE_IMAGES --project X --chapter Y --scene Z --orientation VERTICAL --wait
 ```
+Use when image is fundamentally wrong (wrong character, wrong scene).
 
-### Media Generation (Project-scoped)
-
+**Mode B — Regenerate image directly (with request ID):**
 ```bash
-# List supported models
-veogent image-models   # → { models: ["imagen3.5"] }
-veogent video-models   # → { models: ["veo_3_1_fast", "veo_3_1_fast_r2v"] }
+veogent edit-scene --project X --chapter Y --scene Z \
+  --prompt "adjust lighting to warmer tones" --request <requestId> --wait
+```
+Use when image is close but needs a tweak (lighting, pose, angle).
 
-# Generate Image (project-scoped)
-veogent request --type "GENERATE_IMAGES" --project <projectId> --chapter <chapterId> --scene <sceneId> --imagemodel "imagen3.5"
+**Fix video only (image is fine):**
+```bash
+veogent request --type GENERATE_VIDEO \
+  --project X --chapter Y --scene Z \
+  --videomodel veo_3_1_fast --orientation VERTICAL --wait
+```
 
-# Generate Video (project-scoped)
-veogent request --type "GENERATE_VIDEO" --project <projectId> --chapter <chapterId> --scene <sceneId> --videomodel "veo_3_1_fast"
+---
 
-# Upscale Video
-veogent upscale --project <projectId> --chapter <chapterId> --scene <sceneId> --orientation "VERTICAL" --resolution "VIDEO_RESOLUTION_4K"
-```
+## 📋 Command Reference
 
-### Standalone Generation (No Project)
+### Authentication & Config
 
-```bash
-# Quick image generation (3 credits)
-veogent gen-image --prompt "A futuristic city at sunset" --orientation "HORIZONTAL"
+| Command | Description |
+|---------|-------------|
+| `login [--device]` | Login (use `--device` for headless/VM) |
+| `logout` | Clear credentials |
+| `status` | Show session + Flow Key details |
+| `setup-flow` | Setup Google Flow Key + payment tier |
 
-# Quick video generation (5 credits)
-veogent gen-video --prompt "A cat playing piano" --orientation "HORIZONTAL"
+### Project Management
 
-# Check standalone request status
-veogent standalone-requests
-veogent standalone-request <requestId>
-```
+| Command | Description |
+|---------|-------------|
+| `projects` | List all projects |
+| `project <id>` | Get project details |
+| `create-project` | Create project (auto-generates description from `--idea`) |
 
-### Monitoring & Status
+### Chapters & Scenes
 
-```bash
-# List recent requests
-veogent requests --limit 10
+| Command | Description |
+|---------|-------------|
+| `chapters <projectId>` | List chapters |
+| `recent-chapters` | Recently updated chapters |
+| `create-chapter-content` | Generate storyboard (scene scripts) via AI |
+| `scenes <projectId> <chapterId>` | List scenes |
+| `create-scene` | Create scenes from script content |
+| `edit-scene` | Edit scene storyboard/prompt, or regenerate image with `--request` |
 
-# Filter by project/chapter/status
-veogent requests --project <projectId> --chapter <chapterId> --status FAILED
+### Characters
 
-# Scene-level status with asset URLs
-veogent scene-status --project <projectId> --chapter <chapterId>
+| Command | Description |
+|---------|-------------|
+| `characters <projectId>` | List characters + readiness (reference images) |
+| `edit-character` | Update character description or edit image via AI |
 
-# Full workflow snapshot (agent helper)
-veogent workflow-status --project <projectId> --chapter <chapterId>
+### Generation
 
-# Wait for all images/videos to complete (with success verification)
-veogent wait-images --project <projectId> --chapter <chapterId> --require-success
-veogent wait-videos --project <projectId> --chapter <chapterId> --require-success
+| Command | Description |
+|---------|-------------|
+| `request` | Create a single generation job (`GENERATE_IMAGES` / `GENERATE_VIDEO`) |
+| `batch-request` | Batch generation for multiple/all scenes (`--all`) |
+| `requests` | List existing generation jobs |
+| `failed-requests` | List failed requests for a chapter |
+| `wait-images` | Poll until all image jobs finish |
+| `wait-videos` | Poll until all video jobs finish |
+| `queue-status` | Current queue/concurrency status |
 
-# Queue concurrency status
-veogent queue-status
+### Monitoring
 
-# Flow credit/plan info
-veogent flow-credits
-```
+| Command | Description |
+|---------|-------------|
+| `scene-status` | Scene-level image+video status with asset URLs |
+| `workflow-status` | Full snapshot: scenes + requests + assets (best for agents) |
 
-### YouTube Publishing
+### YouTube
 
-```bash
-# Generate YouTube metadata
-veogent generate-yt-metadata --project <projectId> --chapter <chapterId> --flowkey
+| Command | Description |
+|---------|-------------|
+| `generate-yt-metadata` | Generate Title/Description/Tags for a chapter |
+| `generate-yt-thumbnail` | Trigger thumbnail generation |
+| `yt-thumbnails` | Get generated thumbnails |
 
-# Generate YouTube thumbnail
-veogent generate-yt-thumbnail --project <projectId> --chapter <chapterId>
+### Utility
 
-# Retrieve generated thumbnails
-veogent yt-thumbnails <projectId> <chapterId>
-```
+| Command | Description |
+|---------|-------------|
+| `image-materials` | List available image styles |
+| `custom-prompts` | List custom prompt templates |
+| `obtain-flow` | Auto-extract Flow Token via browser |
+| `flow-credits` | Check plan + credit info |
+| `skill` | Print the Agent SKILL.md guide |
 
 ---
 
-## Agent Orchestration Notes
+## Video Speed Modes
+
+| Mode | Flag | Use case |
+|------|------|----------|
+| `normal` | `--speed normal` (default) | Most scenes |
+| `timelapse` | `--speed timelapse` | Sunrise, cooking montage, traffic |
+| `slowmotion` | `--speed slowmotion` | Impact, water splash, dramatic reveal |
 
-### Request/Scene Semantics
+---
 
-- `scene.requestId`: backward-compatible legacy pointer; may refer to latest relevant request but is **not type-specific**.
-- `scene.latestImageRequestId`: latest image-related request (`GENERATE_IMAGES` / `EDIT_IMAGE`) regardless of status.
-- `scene.latestVideoRequestId`: latest video request (`GENERATE_VIDEO`) regardless of status.
-- `scene.latestSuccessfulImageRequestId`: latest image-related request in `COMPLETED`.
-- `scene.latestSuccessfulVideoRequestId`: latest video request in `COMPLETED`.
+## Chained Video (endScene)
 
-For robust automation:
-- Prefer `veogent scene-status` or `veogent workflow-status` for chapter-level overview.
-- Use `latestSuccessful*` fields when selecting canonical output URIs.
+Smooth transition between two consecutive scenes:
 
-### `request` (CREATE) vs `requests` (LIST)
+```bash
+veogent request --type GENERATE_VIDEO --project X --chapter Y --scene sceneA \
+  --endscene sceneB --videomodel veo_3_1_fast --orientation VERTICAL
+```
 
-- **`request`** — Creates a new generation job (POST). Requires `--type` flag.
-- **`requests`** — Lists existing jobs (GET). Filterable with `--project`, `--chapter`, `--status`, `--limit`.
+Uses sceneA's image as start frame, sceneB's image as end frame. Both scenes must have successful images. Only works with `veo_3_1_fast`.
 
-### Project-scoped vs Standalone Generation
+---
 
-| | Project-scoped | Standalone |
-|---|---|---|
-| **Image** | `request --type GENERATE_IMAGES --project ... --chapter ... --scene ...` | `gen-image --prompt "prompt"` |
-| **Video** | `request --type GENERATE_VIDEO --project ... --chapter ... --scene ...` | `gen-video --prompt "prompt"` |
-| **List** | `requests` | `standalone-requests` |
-| **Detail** | `requests` with filters | `standalone-request <id>` |
+## Concurrency
 
-### Status Commands: When to Use Which
+Maximum **5** concurrent requests. If queue is full (E10071), CLI auto-retries once after 30s.
 
-| Command | Use When |
-|---------|----------|
-| `requests` | Check individual request status, filter by status/project |
-| `scene-status` | Quick overview of image+video status per scene in a chapter |
-| `workflow-status` | Full snapshot with scenes + requests + assets (best for agents) |
-| `failed-requests` | Quick list of all failed/error/rejected requests for a chapter |
-| `wait-images` / `wait-videos` | Block until all generation jobs finish (polling) |
+`batch-request` respects the 5-request limit with inter-batch throttling.
 
 ---
 
 ## 🤖 For AI Agents
 
-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)
-
-1. Resolve optional IDs first (if missing):
-   - `veogent custom-prompts`
-   - `veogent image-materials` (default fallback: `CINEMATIC`)
-2. Prepare story input (arc, summary, key notes).
-3. Generate project description:
-   - `veogent create-project-description ...`
-4. Create project from generated payload.
-5. Create chapter content with scene count:
-   - `veogent create-chapter-content --scenes <sceneCount>`
-   - Rule: each scene maps to ~8s clip.
-6. Create scenes from returned script list:
-   - `veogent create-scene --project <projectId> --chapter <chapterId> --content "scene 1" "scene 2" ... --flowkey`
-7. Wait for character generation completion (`imageUri` required for all characters):
-   - `veogent characters <projectId>` — check `characterReadiness.allReady === true`
-   - `veogent scene-materialization-status --project <projectId> --chapter <chapterId>` — verify `status: "READY"`
-   - If missing/fail: inspect `veogent requests --limit 20`, recover via `veogent edit-character`.
-8. Generate scene images:
-   - `veogent request --type "GENERATE_IMAGES" ...`
-   - If image is reported wrong, decode image to Base64 and send to AI reviewer for evaluation.
-   - If mismatch persists, fix via:
-     - `veogent edit-scene --userprompt "..."` (prompt refinement), or
-     - `veogent edit-scene --request <requestId> ...` (direct edit on prior generated image)
-9. Generate video only after matching-orientation image exists successfully:
-   - `veogent request --type "GENERATE_VIDEO" ...`
-
-> 📖 For the full detailed guide with all commands, options tables, and examples, see **[`skills/SKILL.md`](./skills/SKILL.md)**.
-
-**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.
+- Always use `--agent-safe` flag
+- Use `workflow-status` for the most complete snapshot
+- Character reference images are created from names found in `--idea` and scene scripts
+- Use character NAMES only in prompts — never describe appearance (reference images define it)
+- See **[`skills/SKILL.md`](./skills/SKILL.md)** for the full agent guide
 
 ---