veogent 1.0.21 → 1.0.25

package/README.md

@@ -69,8 +69,13 @@ veogent create-project -n "Cyberpunk T-Rex" -k "T-rex, Neon, Sci-fi" -d "A massi
 # Get all chapters within a project ID
 veogent chapters <projectId>
 
-# View characters cast for the project
+# View characters cast for the project (includes readiness info)
 veogent characters <projectId>
+# Response includes: { characters: [{id, name, imageUri, ready}], characterReadiness: {total, ready, allReady} }
+
+# Check scene materialization status (how many scenes are ready)
+veogent scene-materialization-status -p <projectId> -c <chapterId>
+# Response: { expectedScenes, materializedScenes, status: "PROCESSING"|"READY"|"EMPTY" }
 
 # Create scenes automatically using AI-generated narrative scripts
 veogent create-scene -p <projectId> -c <chapterId> --flowkey -C "The T-Rex looks up at the sky." "A meteor shower begins."
@@ -91,8 +96,12 @@ Queue generation jobs directly from the terminal.
 *Note: VEOGENT uses strict validation depending on the request type.*
 
 ```bash
+# List supported models
+veogent image-models   # → { models: ["imagen3.5"] }
+veogent video-models   # → { models: ["veo_3_1_fast", "veo_3_1_fast_r2v"] }
+
 # Generate Image (Supports: imagen3.5)
-veogent request -t "GENERATE_IMAGES" -p <proj> -c <chap> -s <scene> -i "imagen4"
+veogent request -t "GENERATE_IMAGES" -p <proj> -c <chap> -s <scene> -i "imagen3.5"
 
 # Generate Video (Supports: veo_3_1_fast, veo_3_1_fast_r2v)
 # Default/recommended model: veo_3_1_fast
@@ -105,6 +114,43 @@ veogent request -t "VIDEO_UPSCALE" -p <proj> -c <chap> -s <scene> -o "HORIZONTAL
 veogent upscale -p <proj> -c <chap> -s <scene> -o "VERTICAL" -r "VIDEO_RESOLUTION_4K"
 ```
 
+### 📊 Monitoring & Status
+```bash
+# View all requests (most recent first)
+veogent requests
+
+# Get N most recent requests
+veogent requests -n 10
+
+# Filter by project / chapter / status
+veogent requests -p <projectId> -c <chapterId> -n 5
+veogent requests -s FAILED -n 20
+veogent requests -s COMPLETED -p <projectId>
+
+# Scene-level status with embedded asset URLs (image + video)
+veogent scene-status -p <projectId> -c <chapterId>
+# Each scene returns: { sceneId, image: { status, url }, video: { status, url } }
+
+# Full workflow snapshot (scenes + requests + assets)
+veogent workflow-status -p <projectId> -c <chapterId>
+
+# Wait for all images to finish processing
+veogent wait-images -p <projectId> -c <chapterId>
+
+# Wait and verify all images succeeded (not just finished)
+veogent wait-images -p <projectId> -c <chapterId> --require-success
+
+# Same for videos
+veogent wait-videos -p <projectId> -c <chapterId> --require-success
+
+# Queue concurrency status
+veogent queue-status
+
+# Google Flow credit/plan info (requires flow key)
+veogent flow-credits
+veogent flow-credits -f "ya29.a0ATk..."
+```
+
 ---
 
 ## 🤖 For AI Agents
@@ -126,8 +172,9 @@ Veogent CLI ships with a comprehensive **[`skills/SKILL.md`](./skills/SKILL.md)*
 6. Create scenes from returned script list:
    - `veogent create-scene -p <projectId> -c <chapterId> -C "scene 1" "scene 2" ... --flowkey`
 7. Wait for character generation completion (`imageUri` required for all characters):
-   - `veogent characters <projectId>`
-   - If missing/fail: inspect `veogent requests`, recover via `veogent edit-character`.
+   - `veogent characters <projectId>` — check `characterReadiness.allReady === true`
+   - `veogent scene-materialization-status -p <projectId> -c <chapterId>` — verify `status: "READY"`
+   - If missing/fail: inspect `veogent requests -n 20`, recover via `veogent edit-character`.
 8. Generate scene images:
    - `veogent request -t "GENERATE_IMAGES" ...`
    - If image is reported wrong, decode image to Base64 and send to AI reviewer for evaluation.
@@ -140,6 +187,9 @@ Veogent CLI ships with a comprehensive **[`skills/SKILL.md`](./skills/SKILL.md)*
 > 📖 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.
+- Use `-n <N>` to get only the N most recent requests.
+- Use `-s FAILED` / `-s COMPLETED` to filter by status.
+- Use `--require-success` on `wait-images` / `wait-videos` to ensure assets actually exist (not just "finished").
 
 **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

@@ -6,7 +6,7 @@ import { setConfig, clearConfig, getToken } from './config.js';
 
 const program = new Command();
 
-const IMAGE_MODELS = ['imagen3.5', 'imagen4'];
+const IMAGE_MODELS = ['imagen3.5'];
 const VIDEO_MODELS = ['veo_3_1_fast', 'veo_3_1_fast_r2v'];
 
 function globalOpts() {
@@ -170,9 +170,9 @@ program
         try {
             const data = await api.get('/app/capabilities');
             const caps = unwrapData(data);
-            emitJson({ data: caps?.imageModels || IMAGE_MODELS });
+            emitJson({ status: 'success', models: caps?.imageModels || IMAGE_MODELS });
         } catch {
-            emitJson({ data: IMAGE_MODELS });
+            emitJson({ status: 'success', models: IMAGE_MODELS });
         }
     });
 
@@ -183,9 +183,9 @@ program
         try {
             const data = await api.get('/app/capabilities');
             const caps = unwrapData(data);
-            emitJson({ data: caps?.videoModels || VIDEO_MODELS });
+            emitJson({ status: 'success', models: caps?.videoModels || VIDEO_MODELS });
         } catch {
-            emitJson({ data: VIDEO_MODELS });
+            emitJson({ status: 'success', models: VIDEO_MODELS });
         }
     });
 
@@ -316,7 +316,7 @@ program
 
 program
     .command('create-chapter-content')
-    .description('Generate content for a specific chapter')
+    .description('Generate content for a specific chapter. This is a synchronous AI generation call — use the returned chapterContent directly.')
     .requiredOption('-p, --project <project>', 'Project ID')
     .requiredOption('-c, --chapter <chapter>', 'Chapter ID')
     .option('-s, --scenes <count>', 'Number of scenes', '1')
@@ -328,9 +328,15 @@ program
                 numberScene: parseInt(options.scenes),
             };
             const data = await api.post('/app/chapter/content', payload);
-            console.log(JSON.stringify({ status: "success", chapterContent: unwrapData(data) }, null, 2));
+            const raw = unwrapData(data);
+            // Normalize: always return chapterContent as array of strings
+            let chapterContent = raw;
+            if (raw?.chapterContent) chapterContent = raw.chapterContent;
+            else if (raw?.content) chapterContent = raw.content;
+            if (!Array.isArray(chapterContent)) chapterContent = [chapterContent];
+            emitJson({ status: "success", chapterContent });
         } catch (error) {
-            console.log(JSON.stringify({ status: "error", ...formatCliError(error) }));
+            emitJson({ status: "error", ...formatCliError(error) });
         }
     });
 
@@ -338,13 +344,34 @@ program
 // --- Characters ---
 program
     .command('characters <projectId>')
-    .description('Get all characters for a specific project')
+    .description('Get all characters for a specific project (includes readiness info)')
     .action(async (projectId) => {
         try {
             const data = await api.get(`/app/characters/${projectId}`);
-            console.log(JSON.stringify(unwrapData(data), null, 2));
+            const raw = unwrapData(data);
+            const chars = Array.isArray(raw) ? raw : (raw?.characters || raw?.items || []);
+
+            const characters = chars.map((ch) => ({
+                id: ch?.id || ch?.characterId || null,
+                name: ch?.name || ch?.characterName || null,
+                imageUri: ch?.imageUri || ch?.imageUrl || ch?.image || null,
+                ready: !!(ch?.imageUri || ch?.imageUrl || ch?.image),
+                ...ch,
+            }));
+
+            const readyCount = characters.filter((c) => c.ready).length;
+            const result = {
+                status: 'success',
+                characters,
+                characterReadiness: {
+                    total: characters.length,
+                    ready: readyCount,
+                    allReady: characters.length > 0 && readyCount === characters.length,
+                },
+            };
+            emitJson(result);
         } catch (error) {
-            console.log(JSON.stringify({ status: "error", ...formatCliError(error) }));
+            emitJson({ status: "error", ...formatCliError(error) });
         }
     });
 
@@ -414,13 +441,66 @@ program
 
 program
     .command('scene-status')
-    .description('Get scene status snapshot by chapter')
+    .description('Get scene status snapshot by chapter (with embedded asset URLs)')
     .requiredOption('-p, --project <project>', 'Project ID')
     .requiredOption('-c, --chapter <chapter>', 'Chapter ID')
     .action(async (options) => {
         try {
             const data = await api.get(`/app/scene-status/${options.project}/${options.chapter}`);
-            emitJson({ status: 'success', data: unwrapData(data) });
+            const rawData = unwrapData(data);
+
+            // Try to enrich each scene with asset URLs
+            const scenes = Array.isArray(rawData) ? rawData : (rawData?.scenes || rawData?.items || [rawData]);
+            const enriched = await Promise.all(scenes.map(async (scene) => {
+                const sceneId = scene?.id || scene?.sceneId;
+                if (!sceneId) return scene;
+
+                let imageAsset = { status: scene?.imageStatus || null, url: scene?.imageUrl || scene?.imageVerticalUri || scene?.imageHorizontalUri || null };
+                let videoAsset = { status: scene?.videoStatus || null, url: scene?.videoUrl || scene?.videoVerticalUri || scene?.videoHorizontalUri || null };
+
+                // Fetch assets if URLs not already present
+                try {
+                    if (!imageAsset.url) {
+                        const imgData = unwrapData(await api.get(`/app/request/assets/${options.project}/${options.chapter}/${sceneId}?type=GENERATE_IMAGES`));
+                        const imgItems = Array.isArray(imgData) ? imgData : (imgData?.items || []);
+                        const completed = imgItems.find((r) => String(r?.status || '').toUpperCase() === 'COMPLETED');
+                        if (completed) {
+                            imageAsset = {
+                                status: 'COMPLETED',
+                                url: completed?.imageVerticalUri || completed?.imageHorizontalUri || completed?.imageUrl || completed?.outputUrl || null,
+                                createdAt: completed?.createdAt || null,
+                                completedAt: completed?.completedAt || completed?.updatedAt || null,
+                            };
+                        }
+                    }
+                } catch { /* asset fetch optional */ }
+
+                try {
+                    if (!videoAsset.url) {
+                        const vidData = unwrapData(await api.get(`/app/request/assets/${options.project}/${options.chapter}/${sceneId}?type=GENERATE_VIDEO`));
+                        const vidItems = Array.isArray(vidData) ? vidData : (vidData?.items || []);
+                        const completed = vidItems.find((r) => String(r?.status || '').toUpperCase() === 'COMPLETED');
+                        if (completed) {
+                            videoAsset = {
+                                status: 'COMPLETED',
+                                url: completed?.videoVerticalUri || completed?.videoHorizontalUri || completed?.videoUrl || completed?.outputUrl || null,
+                                createdAt: completed?.createdAt || null,
+                                completedAt: completed?.completedAt || completed?.updatedAt || null,
+                            };
+                        }
+                    }
+                } catch { /* asset fetch optional */ }
+
+                return {
+                    sceneId,
+                    displayOrder: scene?.displayOrder ?? null,
+                    image: imageAsset,
+                    video: videoAsset,
+                    raw: scene,
+                };
+            }));
+
+            emitJson({ status: 'success', data: enriched });
         } catch (error) {
             emitJson({ status: 'error', ...formatCliError(error) });
         }
@@ -428,13 +508,49 @@ program
 
 program
     .command('workflow-status')
-    .description('Export workflow snapshot for a project/chapter (agent helper)')
+    .description('Export workflow snapshot for a project/chapter with embedded asset URLs (agent helper)')
     .requiredOption('-p, --project <project>', 'Project ID')
     .requiredOption('-c, --chapter <chapter>', 'Chapter ID')
     .action(async (options) => {
         try {
             const data = await api.get(`/app/workflow-status/${options.project}/${options.chapter}`);
-            emitJson({ status: 'success', data: unwrapData(data) });
+            const rawData = unwrapData(data);
+
+            // Enrich scenes with asset URLs
+            const scenes = Array.isArray(rawData?.scenes) ? rawData.scenes : (Array.isArray(rawData) ? rawData : []);
+            const enrichedScenes = await Promise.all(scenes.map(async (scene) => {
+                const sceneId = scene?.id || scene?.sceneId;
+                if (!sceneId) return scene;
+
+                let imageAsset = { status: scene?.imageStatus || null, url: scene?.imageUrl || scene?.imageVerticalUri || scene?.imageHorizontalUri || null };
+                let videoAsset = { status: scene?.videoStatus || null, url: scene?.videoUrl || scene?.videoVerticalUri || scene?.videoHorizontalUri || null };
+
+                try {
+                    if (!imageAsset.url) {
+                        const imgData = unwrapData(await api.get(`/app/request/assets/${options.project}/${options.chapter}/${sceneId}?type=GENERATE_IMAGES`));
+                        const imgItems = Array.isArray(imgData) ? imgData : (imgData?.items || []);
+                        const completed = imgItems.find((r) => String(r?.status || '').toUpperCase() === 'COMPLETED');
+                        if (completed) {
+                            imageAsset = { status: 'COMPLETED', url: completed?.imageVerticalUri || completed?.imageHorizontalUri || completed?.imageUrl || completed?.outputUrl || null };
+                        }
+                    }
+                } catch { /* optional */ }
+
+                try {
+                    if (!videoAsset.url) {
+                        const vidData = unwrapData(await api.get(`/app/request/assets/${options.project}/${options.chapter}/${sceneId}?type=GENERATE_VIDEO`));
+                        const vidItems = Array.isArray(vidData) ? vidData : (vidData?.items || []);
+                        const completed = vidItems.find((r) => String(r?.status || '').toUpperCase() === 'COMPLETED');
+                        if (completed) {
+                            videoAsset = { status: 'COMPLETED', url: completed?.videoVerticalUri || completed?.videoHorizontalUri || completed?.videoUrl || completed?.outputUrl || null };
+                        }
+                    }
+                } catch { /* optional */ }
+
+                return { sceneId, image: imageAsset, video: videoAsset, raw: scene };
+            }));
+
+            emitJson({ status: 'success', data: { ...rawData, scenes: enrichedScenes } });
         } catch (error) {
             // Backward-compatible fallback for old backend
             try {
@@ -451,13 +567,77 @@ program
                     (r?.chapter_id === options.chapter || r?.chapterId === options.chapter)
                 );
 
-                emitJson({ status: 'success', data: { projectId: options.project, chapterId: options.chapter, scenes, requests: chapterRequests } });
+                // Enrich fallback scenes too
+                const enrichedFallback = await Promise.all(scenes.map(async (scene) => {
+                    const sceneId = scene?.id || scene?.sceneId;
+                    if (!sceneId) return scene;
+
+                    let imageAsset = { status: null, url: null };
+                    let videoAsset = { status: null, url: null };
+
+                    try {
+                        const imgData = unwrapData(await api.get(`/app/request/assets/${options.project}/${options.chapter}/${sceneId}?type=GENERATE_IMAGES`));
+                        const imgItems = Array.isArray(imgData) ? imgData : (imgData?.items || []);
+                        const completed = imgItems.find((r) => String(r?.status || '').toUpperCase() === 'COMPLETED');
+                        if (completed) {
+                            imageAsset = { status: 'COMPLETED', url: completed?.imageVerticalUri || completed?.imageHorizontalUri || completed?.imageUrl || null };
+                        }
+                    } catch { /* optional */ }
+
+                    try {
+                        const vidData = unwrapData(await api.get(`/app/request/assets/${options.project}/${options.chapter}/${sceneId}?type=GENERATE_VIDEO`));
+                        const vidItems = Array.isArray(vidData) ? vidData : (vidData?.items || []);
+                        const completed = vidItems.find((r) => String(r?.status || '').toUpperCase() === 'COMPLETED');
+                        if (completed) {
+                            videoAsset = { status: 'COMPLETED', url: completed?.videoVerticalUri || completed?.videoHorizontalUri || completed?.videoUrl || null };
+                        }
+                    } catch { /* optional */ }
+
+                    return { sceneId, image: imageAsset, video: videoAsset, raw: scene };
+                }));
+
+                emitJson({ status: 'success', data: { projectId: options.project, chapterId: options.chapter, scenes: enrichedFallback, requests: chapterRequests } });
             } catch (fallbackError) {
                 emitJson({ status: 'error', ...formatCliError(fallbackError) });
             }
         }
     });
 
+program
+    .command('scene-materialization-status')
+    .description('Check how many scenes have been materialized for a chapter')
+    .requiredOption('-p, --project <project>', 'Project ID')
+    .requiredOption('-c, --chapter <chapter>', 'Chapter ID')
+    .action(async (options) => {
+        try {
+            // Get chapter data to determine expected scenes
+            let expectedScenes = 0;
+            try {
+                const chapterData = unwrapData(await api.get(`/app/chapters/${options.project}`));
+                const chapters = Array.isArray(chapterData) ? chapterData : (chapterData?.chapters || chapterData?.items || []);
+                const chapter = chapters.find((ch) => (ch?.id || ch?.chapterId) === options.chapter);
+                expectedScenes = chapter?.numberScene || chapter?.sceneCount || chapter?.expectedScenes || 0;
+            } catch { /* fallback: expectedScenes stays 0 */ }
+
+            // Get actual scenes
+            const scenesRaw = unwrapData(await api.get(`/app/scenes/${options.project}/${options.chapter}`));
+            const scenes = Array.isArray(scenesRaw) ? scenesRaw : (scenesRaw?.scenes || scenesRaw?.items || []);
+            const materializedScenes = scenes.length;
+
+            // If we couldn't get expectedScenes from chapter, use materialized as fallback
+            if (expectedScenes === 0) expectedScenes = materializedScenes;
+
+            let status;
+            if (materializedScenes === 0) status = 'EMPTY';
+            else if (materializedScenes >= expectedScenes) status = 'READY';
+            else status = 'PROCESSING';
+
+            emitJson({ status: 'success', expectedScenes, materializedScenes, materialization: status });
+        } catch (error) {
+            emitJson({ status: 'error', ...formatCliError(error) });
+        }
+    });
+
 program
     .command('create-scene')
     .description('Create a new scene from text content')
@@ -516,7 +696,7 @@ program
     .requiredOption('-c, --chapter <chapter>', 'Chapter ID')
     .requiredOption('-s, --scene <scene>', 'Scene ID')
     .option('-o, --orientation <orientation>', 'Request orientation (HORIZONTAL, VERTICAL)')
-    .option('-i, --imagemodel <imagemodel>', 'Image Model (imagen4, imagen3.5)', 'imagen4')
+    .option('-i, --imagemodel <imagemodel>', 'Image Model (imagen3.5)', 'imagen3.5')
     .option('-v, --videomodel <videomodel>', 'Video Model (veo_3_1_fast, veo_3_1_fast_r2v). Default: veo_3_1_fast', 'veo_3_1_fast')
     .option('-S, --speed <speed>', 'Video Speed (normal, timelapse, slowmotion)', 'normal')
     .option('-E, --endscene <endscene>', 'End Scene ID for continuous video generation')
@@ -564,7 +744,13 @@ program
             }
 
             const data = await api.post('/app/request', payload);
-            console.log(JSON.stringify({ status: "success", request: unwrapData(data) }, null, 2));
+            const requestResult = unwrapData(data);
+            // P2-7: Persist endScene metadata when chained video generation
+            if (options.endscene) {
+                requestResult.end_scene_id = options.endscene;
+                requestResult.generationMode = 'CHAINED_VIDEO';
+            }
+            console.log(JSON.stringify({ status: "success", request: requestResult }, null, 2));
         } catch (error) {
             console.log(JSON.stringify({ status: "error", ...formatCliError(error) }));
         }
@@ -572,13 +758,45 @@ program
 
 program
     .command('requests')
-    .description('Get all generation requests/jobs status for the current user')
-    .action(async () => {
+    .description('Get generation requests/jobs status for the current user')
+    .option('-n, --limit <n>', 'Return only the N most recent requests', null)
+    .option('-p, --project <projectId>', 'Filter by project ID')
+    .option('-c, --chapter <chapterId>', 'Filter by chapter ID')
+    .option('-s, --status <status>', 'Filter by status (e.g. COMPLETED, FAILED, PROCESSING)')
+    .action(async (options) => {
         try {
             const data = await api.get('/app/requests');
-            console.log(JSON.stringify(unwrapData(data), null, 2));
+            let items = unwrapData(data);
+            items = Array.isArray(items) ? items : (items?.items || []);
+
+            // Filter by project
+            if (options.project) {
+                items = items.filter((r) => r?.projectId === options.project || r?.project_id === options.project);
+            }
+            // Filter by chapter
+            if (options.chapter) {
+                items = items.filter((r) => r?.chapterId === options.chapter || r?.chapter_id === options.chapter);
+            }
+            // Filter by status
+            if (options.status) {
+                const s = options.status.toUpperCase();
+                items = items.filter((r) => String(r?.status || '').toUpperCase() === s);
+            }
+            // Sort by createdAt desc (most recent first)
+            items = items.sort((a, b) => {
+                const ta = a?.createdAt || a?.created_at || 0;
+                const tb = b?.createdAt || b?.created_at || 0;
+                return (Number(tb) || 0) - (Number(ta) || 0);
+            });
+            // Limit to N most recent
+            if (options.limit !== null && options.limit !== undefined) {
+                const n = parseInt(options.limit, 10);
+                if (!isNaN(n) && n > 0) items = items.slice(0, n);
+            }
+
+            emitJson({ status: 'success', total: items.length, data: items });
         } catch (error) {
-            console.log(JSON.stringify({ status: "error", ...formatCliError(error) }));
+            emitJson({ status: 'error', ...formatCliError(error) });
         }
     });
 
@@ -622,6 +840,7 @@ program
     .requiredOption('-c, --chapter <chapter>', 'Chapter ID')
     .option('-i, --interval <sec>', 'Polling interval in seconds', '10')
     .option('-t, --timeout <sec>', 'Timeout in seconds', '1800')
+    .option('--require-success', 'Exit non-zero if any scene lacks a successful image asset')
     .action(async (options) => {
         const intervalMs = Math.max(1, Number(options.interval || 10)) * 1000;
         const timeoutMs = Math.max(30, Number(options.timeout || 1800)) * 1000;
@@ -640,6 +859,24 @@ program
 
                 const pending = filtered.filter((r) => ['PENDING', 'PROCESSING', 'RUNNING'].includes(String(r?.status || '').toUpperCase()));
                 if (pending.length === 0) {
+                    // --require-success: verify each scene has at least one COMPLETED request with asset URL
+                    if (options.requireSuccess) {
+                        const sceneIds = [...new Set(filtered.map((r) => r?.scene || r?.sceneId).filter(Boolean))];
+                        const failedScenes = [];
+                        for (const sid of sceneIds) {
+                            const sceneReqs = filtered.filter((r) => (r?.scene === sid || r?.sceneId === sid));
+                            const hasSuccess = sceneReqs.some((r) => {
+                                const st = String(r?.status || '').toUpperCase();
+                                const hasUrl = !!(r?.imageVerticalUri || r?.imageHorizontalUri || r?.imageUrl || r?.outputUrl);
+                                return st === 'COMPLETED' && hasUrl;
+                            });
+                            if (!hasSuccess) failedScenes.push(sid);
+                        }
+                        if (failedScenes.length > 0) {
+                            console.log(JSON.stringify({ status: 'error', code: 'ASSETS_NOT_SUCCESS', message: 'Some scenes did not produce successful assets', failedScenes }, null, 2));
+                            process.exit(1);
+                        }
+                    }
                     console.log(JSON.stringify({ status: 'success', data: filtered, message: 'All image requests finished' }, null, 2));
                     return;
                 }
@@ -660,6 +897,7 @@ program
     .requiredOption('-c, --chapter <chapter>', 'Chapter ID')
     .option('-i, --interval <sec>', 'Polling interval in seconds', '10')
     .option('-t, --timeout <sec>', 'Timeout in seconds', '3600')
+    .option('--require-success', 'Exit non-zero if any scene lacks a successful video asset')
     .action(async (options) => {
         const intervalMs = Math.max(1, Number(options.interval || 10)) * 1000;
         const timeoutMs = Math.max(30, Number(options.timeout || 3600)) * 1000;
@@ -678,6 +916,24 @@ program
 
                 const pending = filtered.filter((r) => ['PENDING', 'PROCESSING', 'RUNNING'].includes(String(r?.status || '').toUpperCase()));
                 if (pending.length === 0) {
+                    // --require-success: verify each scene has at least one COMPLETED request with asset URL
+                    if (options.requireSuccess) {
+                        const sceneIds = [...new Set(filtered.map((r) => r?.scene || r?.sceneId).filter(Boolean))];
+                        const failedScenes = [];
+                        for (const sid of sceneIds) {
+                            const sceneReqs = filtered.filter((r) => (r?.scene === sid || r?.sceneId === sid));
+                            const hasSuccess = sceneReqs.some((r) => {
+                                const st = String(r?.status || '').toUpperCase();
+                                const hasUrl = !!(r?.videoVerticalUri || r?.videoHorizontalUri || r?.videoUrl || r?.outputUrl);
+                                return st === 'COMPLETED' && hasUrl;
+                            });
+                            if (!hasSuccess) failedScenes.push(sid);
+                        }
+                        if (failedScenes.length > 0) {
+                            console.log(JSON.stringify({ status: 'error', code: 'ASSETS_NOT_SUCCESS', message: 'Some scenes did not produce successful assets', failedScenes }, null, 2));
+                            process.exit(1);
+                        }
+                    }
                     console.log(JSON.stringify({ status: 'success', data: filtered, message: 'All video requests finished' }, null, 2));
                     return;
                 }
@@ -697,9 +953,21 @@ program
     .action(async (projectId, chapterId, sceneId, type) => {
         try {
             const data = await api.get(`/app/request/assets/${projectId}/${chapterId}/${sceneId}?type=${type}`);
-            console.log(JSON.stringify(unwrapData(data), null, 2));
+            const raw = unwrapData(data);
+            // Enrich with lifecycle metadata
+            const items = Array.isArray(raw) ? raw : (raw?.items || [raw]);
+            const enriched = items.map((r) => ({
+                ...r,
+                createdAt: r?.createdAt || null,
+                startedAt: r?.startedAt || null,
+                updatedAt: r?.updatedAt || null,
+                completedAt: r?.completedAt || null,
+                deducted: r?.deducted ?? null,
+                retryable: typeof r?.retryable === 'boolean' ? r.retryable : (r?.status && ['FAILED', 'ERROR'].includes(String(r.status).toUpperCase())),
+            }));
+            emitJson({ status: 'success', data: enriched });
         } catch (error) {
-            console.log(JSON.stringify({ status: "error", ...formatCliError(error) }));
+            emitJson({ status: "error", ...formatCliError(error) });
         }
     });
 
@@ -834,4 +1102,70 @@ program
         }
     });
 
+// Flow Credits — fetch plan and credit info from Google AI Sandbox using flow key
+program
+    .command('flow-credits')
+    .description('Fetch plan and credit info from Google AI Sandbox using your Flow key (Bearer token)')
+    .option('-f, --flowkey <flowkey>', 'Flow key (ya29. token). If omitted, uses stored flow key from account.')
+    .action(async (options) => {
+        try {
+            // Determine which flow key to use
+            let flowKey = options.flowkey;
+
+            if (!flowKey) {
+                // Try to get from stored account
+                const token = getToken();
+                if (!token) {
+                    emitJson({ status: 'error', code: 'NO_TOKEN', message: 'Not logged in. Run: veogent login' });
+                    process.exit(1);
+                }
+                const accountData = unwrapData(await api.get('/app/flow-key'));
+                flowKey = accountData?.flowKey;
+                if (!flowKey) {
+                    emitJson({ status: 'error', code: 'NO_FLOW_KEY', message: 'No flow key found. Set one with: veogent setup-flow -f <token>' });
+                    process.exit(1);
+                }
+            }
+
+            const response = await fetch('https://aisandbox-pa.googleapis.com/v1/credits', {
+                method: 'GET',
+                headers: {
+                    'accept': '*/*',
+                    'accept-language': 'en-US,en;q=0.9',
+                    'authorization': `Bearer ${flowKey}`,
+                    'content-type': 'application/json',
+                    'origin': 'https://veogent.com',
+                    'referer': 'https://veogent.com/',
+                    'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36',
+                    'x-browser-channel': 'stable',
+                    'x-browser-year': '2026',
+                },
+            });
+
+            if (!response.ok) {
+                const errText = await response.text();
+                emitJson({ status: 'error', code: `HTTP_${response.status}`, message: errText || response.statusText });
+                process.exit(1);
+            }
+
+            const data = await response.json();
+
+            // Normalize output
+            const result = {
+                status: 'success',
+                plan: data?.plan || data?.tier || data?.subscriptionTier || null,
+                credits: data?.credits ?? data?.remainingCredits ?? data?.balance ?? null,
+                totalCredits: data?.totalCredits ?? data?.maxCredits ?? null,
+                usedCredits: data?.usedCredits ?? null,
+                resetAt: data?.resetAt ?? data?.renewalDate ?? null,
+                raw: data,
+            };
+
+            emitJson(result);
+        } catch (error) {
+            emitJson({ status: 'error', ...formatCliError(error) });
+            process.exit(1);
+        }
+    });
+
 program.parse(process.argv);

package/package.json

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

package/skills/SKILL.md

@@ -15,12 +15,12 @@ The `veogent` command-line interface interacts with the **VEOGENT API** for mana
 2. [Projects & Assets](#-projects--assets)
 3. [Chapters](#-chapters)
 4. [Scenes](#-scenes)
-5. [Characters](#-characters)
+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 Management](#-flow-token-management)
+10. [Flow Token & Credits](#-flow-token-management)
 11. [The Complete VEOGENT Pipeline (Best Practices)](#-the-complete-veogent-pipeline)
 12. [Error Handling](#-error-handling)
 
@@ -173,7 +173,14 @@ The `veogent` command-line interface interacts with the **VEOGENT API** for mana
 
 ### 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`.
+- **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 |
   |------|----------|-------------|---------|
@@ -183,6 +190,7 @@ The `veogent` command-line interface interacts with the **VEOGENT API** for mana
 - **Example:**
   ```bash
   veogent create-chapter-content -p "projID" -c "chapID" -s 5
+  # → { "status": "success", "chapterContent": ["...", "..."] }
   ```
 
 ---
@@ -218,11 +226,41 @@ The `veogent` command-line interface interacts with the **VEOGENT API** for mana
 ## 🧑‍🎨 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.
+- **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 |
+  |------|----------|-------------|
+  | `-p, --project <project>` | ✅ | Project ID |
+  | `-c, --chapter <chapter>` | ✅ | Chapter ID |
+- **Response:**
+  ```json
+  { "expectedScenes": 5, "materializedScenes": 5, "status": "READY" }
+  ```
+  Status values: `"PROCESSING"` | `"READY"` | `"EMPTY"`
+- **Example:**
+  ```bash
+  veogent scene-materialization-status -p "projID" -c "chapID"
+  # Poll until: status === "READY"
   ```
 
 ### Skill: `edit-character`
@@ -333,12 +371,12 @@ Beside the main visual description, you **CAN** include minor action description
 | `-p, --project` | ✅ | Project ID | — |
 | `-c, --chapter` | ✅ | Chapter ID | — |
 | `-s, --scene` | ✅ | Scene ID | — |
-| `-i, --imagemodel` | ✅ | Image model | `imagen4`, `imagen3.5` |
+| `-i, --imagemodel` | ✅ | Image model | `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"
+veogent request -t "GENERATE_IMAGES" -p "projID" -c "chapID" -s "sceneID" -i "imagen3.5"
 ```
 
 #### 2. Generate Video (`GENERATE_VIDEO`)
@@ -351,7 +389,7 @@ veogent request -t "GENERATE_IMAGES" -p "projID" -c "chapID" -s "sceneID" -i "im
 | `-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` |
+| `-i, --imagemodel` | ✅ | Image model for video context | `imagen3.5` |
 | `-o, --orientation` | ✅ | Orientation | `HORIZONTAL`, `VERTICAL` |
 | `-E, --endscene` | ❌ | End Scene ID for continuous video generation (interpolation to next frame) | — |
 
@@ -399,11 +437,121 @@ veogent request -t "VIDEO_UPSCALE" -p "projID" -c "chapID" -s "sceneID" -o "HORI
 ## 📊 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.
+- **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 `-n` to limit results for efficiency in agent loops.
+- **Options:**
+  | Flag | Required | Description |
+  |------|----------|-------------|
+  | `-n, --limit <n>` | ❌ | Return only the N most recent requests |
+  | `-p, --project <projectId>` | ❌ | Filter by project ID |
+  | `-c, --chapter <chapterId>` | ❌ | Filter by chapter ID |
+  | `-s, --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 -n 10                       # 10 most recent
+  veogent requests -p <projId> -c <chapId>    # filter by project/chapter
+  veogent requests -s FAILED -n 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 |
+  |------|----------|-------------|
+  | `-p, --project <project>` | ✅ | Project ID |
+  | `-c, --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 -p "projID" -c "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 |
+  |------|----------|-------------|
+  | `-p, --project <project>` | ✅ | Project ID |
+  | `-c, --chapter <chapter>` | ✅ | Chapter ID |
+- **Example:**
+  ```bash
+  veogent workflow-status -p "projID" -c "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 |
+  |------|----------|-------------|
+  | `-p, --project <project>` | ✅ | Project ID |
+  | `-c, --chapter <chapter>` | ✅ | Chapter ID |
+  | `--require-success` | ❌ | Fail if any scene has no completed image asset |
+- **Example:**
+  ```bash
+  veogent wait-images -p "projID" -c "chapID" --require-success
+  ```
+
+### Skill: `wait-videos`
+- **Description:** Wait until all video requests in a chapter finish processing.
+- **Options:**
+  | Flag | Required | Description |
+  |------|----------|-------------|
+  | `-p, --project <project>` | ✅ | Project ID |
+  | `-c, --chapter <chapter>` | ✅ | Chapter ID |
+  | `--require-success` | ❌ | Fail if any scene has no completed video asset |
+- **Example:**
+  ```bash
+  veogent wait-videos -p "projID" -c "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 requests
+  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 |
+  |------|----------|-------------|
+  | `-f, --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 -f "ya29.a0ATk..."
   ```
 
 ### Skill: `assets`
@@ -502,19 +650,28 @@ veogent create-project -n "Name" -k "keywords" -d "AI-generated description" -l
 ```
 
 ### Step 4: Chapter & Scene Content
-Generate chapter narrative content, then **immediately** pass the returned scene-script array to `create-scene`:
+Generate chapter narrative content, then **immediately** pass the returned `chapterContent` array to `create-scene`:
 ```bash
 veogent create-chapter-content -p <projId> -c <chapId> -s 5
-# Each scene ≈ 8-second clip
+# → { "status": "success", "chapterContent": ["scene 1...", "scene 2...", ...] }
+# Use chapterContent directly — do NOT poll chapter state
 
 veogent create-scene -p <projId> -c <chapId> -C "script 1" "script 2" "script 3" --flowkey
 ```
 
+### Step 4b: Verify Scene Materialization
+After `create-scene`, scenes appear incrementally. Poll until ready:
+```bash
+veogent scene-materialization-status -p <projId> -c <chapId>
+# Poll until: { "status": "READY", "expectedScenes": N, "materializedScenes": N }
+```
+
 ### 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
+# Poll until characterReadiness.allReady === true
 veogent characters <projectId>
+# → { "characterReadiness": { "total": 4, "ready": 4, "allReady": true } }
 
 # Alternative: check project progress object
 veogent project <projectId>
@@ -522,21 +679,26 @@ veogent project <projectId>
 ```
 
 ### Step 6: Character Recovery Path
-If any character is missing `imageUri`:
+If any character is missing `imageUri` (`ready: false`):
 ```bash
-veogent requests                # inspect for failure/success
+veogent requests -n 20          # inspect recent failures
 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"
+veogent request -t "GENERATE_IMAGES" -p <proj> -c <chap> -s <scene> -i "imagen3.5"
 
 # 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
+
+# After all scenes submitted, wait with success verification:
+veogent wait-images -p <proj> -c <chap> --require-success
+# Check: scene-status for per-scene image URLs
+veogent scene-status -p <proj> -c <chap>
 ```
 
 ### Step 8: AI Review on Image Mismatch
@@ -558,7 +720,12 @@ Continue the visual QA loop until the scene image is **director-approved**. Iter
 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"
+  -v "veo_3_1_fast" -S "normal" -i "imagen3.5" -o "HORIZONTAL"
+
+# Wait for all videos with success verification:
+veogent wait-videos -p <proj> -c <chap> --require-success
+# Full snapshot:
+veogent workflow-status -p <proj> -c <chap>
 ```
 
 ### Step 11: YouTube Publishing Assets