veogent 1.3.0 → 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,390 +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 |
-|---------|-------------|
-| `image-materials` | Get all available Image Material styles (e.g., `CINEMATIC`, `PIXAR_3D`) |
-| `custom-prompts` | Get custom prompt templates and story directives |
-
-> **Removed in v1.3.0:** `capabilities`, `image-models`, `video-models` — hardcoded values are: imagen3.5, veo_3_1_fast/veo_3_1_fast_r2v, HORIZONTAL/VERTICAL
-
-### Project Management
-
-| Command | Description |
-|---------|-------------|
-| `projects` | List all your available projects |
-| `project <id>` | Get details for a specific project |
-| ~~`create-project-description`~~ | Removed — use `quick-project` instead |
-| `create-project` | Create a new project with name, keywords, material, chapters, objects |
-
-### Chapters
-
-| 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 |
-| `edit-scene` | Edit scene image prompt via AI assistance |
-
-### Compound Commands (v1.3.0+)
-
-| Command | Description |
-|---------|-------------|
-| `quick-project` | Create a full project in one command: description → project → chapter content → scenes → wait materialization + characters |
-| `batch-request` | Create generation jobs for multiple/all scenes at once with `--all` or `--scenes id1,id2,...` |
-
-> **`--wait` flag:** Available on `request`, `batch-request`, `edit-scene`, and `quick-project`. Blocks until the operation completes, so you don't need separate `wait-images`/`wait-videos` calls.
-
-### Generation Requests (Project-scoped)
+## 🎯 Recommended Workflow
 
-> **Clarification:** `request` (singular) = **CREATE** a new job. `requests` (plural) = **LIST** existing jobs.
+### How VEOGENT Works — The Mental Model
 
-| Command | Description |
-|---------|-------------|
-| `request` | Create a generation job: `GENERATE_IMAGES`, `GENERATE_VIDEO`, or `VIDEO_UPSCALE`. Supports `--wait` |
-| `batch-request` | Batch generation for multiple scenes. Supports `--all`, `--wait`, `--concurrency` |
-| `requests` | List generation requests (filterable by project, chapter, status) |
-
-### ~~Standalone Generation~~ (Removed in v1.3.0)
-
-> Standalone commands (`gen-image`, `gen-video`, `standalone-requests`, `standalone-request`) have been removed.
-> Use project-scoped workflows for all generation. For quick starts, use `quick-project --wait`.
-
-### Monitoring & Status
-
-| 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) |
-| `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 |
-
-### YouTube Integration
-
-| 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 |
-
-### Flow Token & Credits
-
-| Command | Description |
-|---------|-------------|
-| `obtain-flow` | Auto-extract Flow Token (ya29.) using secure browser overlay |
-| `flow-credits` | Fetch plan and credit info from Google AI Sandbox |
-
-### Utility
-
-| Command | Description |
-|---------|-------------|
-| `skill` | Print the native Agent SKILL.md guide |
+```
+--idea → AI Description → Project + Characters (reference images)
+                                  → Chapter Content (storyboard)
+                                  → Scenes → Images → Videos
+```
 
----
+**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.
 
-## 🛠️ Usage Examples
+### The Pipeline (4 Phases)
 
-### Project Management
+#### Phase 1: Create Project
 
 ```bash
-# List all your active projects
-veogent projects
+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
+```
 
-# View available Image Material styles (e.g., CINEMATIC, PIXAR_3D)
-veogent image-materials
+**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
 
-# 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"}'
-```
+**--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
 
-### Storyboard, Chapters & Scenes
+#### Phase 2: Generate Storyboard + Scenes
 
 ```bash
-# Get all chapters within a project
+# Get chapter ID
 veogent chapters <projectId>
 
-# View characters (includes readiness info)
-veogent characters <projectId>
-# → { characters: [...], characterReadiness: {total, ready, allReady} }
+# Generate storyboard (VEOGENT AI writes scene scripts from the rich description)
+veogent create-chapter-content --project <projectId> --chapter <chapterId> --scenes 5
 
-# Check scene materialization status
-veogent scene-materialization-status --project <projectId> --chapter <chapterId>
-# → { expectedScenes, materializedScenes, status: "PROCESSING"|"READY"|"EMPTY" }
+# 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
 
-# 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."
+# Wait for materialization (~30s per scene)
+# Poll: veogent scenes <projectId> <chapterId> until all scenes have scriptSegment
 
-# 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>
+# Wait for characters to be ready (reference images generated)
+# Poll: veogent characters <projectId> until characterReadiness.allReady === true
 ```
 
-### Directing & Editing
-
-```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
+  --lang English --material CINEMATIC --scenes 5 --wait
 ```
 
-### Media Generation (Project-scoped)
+#### Phase 3: Generate Images + Videos
 
 ```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 (project-scoped)
-veogent request --type "GENERATE_IMAGES" --project <projectId> --chapter <chapterId> --scene <sceneId> --imagemodel "imagen3.5"
-
-# 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"
+# 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
 ```
 
-### Quick Project (replaces standalone)
+#### Phase 4: QA + Fix Loop
 
 ```bash
-# Create full project + scenes in one command
-veogent quick-project --keyword "A cat playing piano" --lang English \
-  --material CINEMATIC --scenes 1 --wait
+# Check results
+veogent workflow-status --project <projectId> --chapter <chapterId>
 ```
 
-### Monitoring & Status
+**edit-scene has TWO modes:**
 
+**Mode A — Edit storyboard/prompt only (no image regen):**
 ```bash
-# List recent requests
-veogent requests --limit 10
-
-# Filter by project/chapter/status
-veogent requests --project <projectId> --chapter <chapterId> --status FAILED
-
-# Scene-level status with asset URLs
-veogent scene-status --project <projectId> --chapter <chapterId>
-
-# Full workflow snapshot (agent helper)
-veogent workflow-status --project <projectId> --chapter <chapterId>
-
-# 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
-
-# Queue concurrency status
-veogent queue-status
-
-# Flow credit/plan info
-veogent flow-credits
+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).
 
-### YouTube Publishing
-
+**Mode B — Regenerate image directly (with request ID):**
 ```bash
-# Generate YouTube metadata
-veogent generate-yt-metadata --project <projectId> --chapter <chapterId> --flowkey
-
-# Generate YouTube thumbnail
-veogent generate-yt-thumbnail --project <projectId> --chapter <chapterId>
+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).
 
-# Retrieve generated thumbnails
-veogent yt-thumbnails <projectId> <chapterId>
+**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
 ```
 
 ---
 
-## Agent Orchestration Notes
+## 📋 Command Reference
 
-### Request/Scene Semantics
+### Authentication & Config
 
-- `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`.
+| 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 |
+
+### Project Management
+
+| Command | Description |
+|---------|-------------|
+| `projects` | List all projects |
+| `project <id>` | Get project details |
+| `create-project` | Create project (auto-generates description from `--idea`) |
 
-For robust automation:
-- Prefer `veogent scene-status` or `veogent workflow-status` for chapter-level overview.
-- Use `latestSuccessful*` fields when selecting canonical output URIs.
+### Chapters & Scenes
 
-### `request` (CREATE) vs `requests` (LIST)
+| 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` |
 
-- **`request`** — Creates a new generation job (POST). Requires `--type` flag.
-- **`requests`** — Lists existing jobs (GET). Filterable with `--project`, `--chapter`, `--status`, `--limit`.
+### Characters
 
-### Generation Commands
+| Command | Description |
+|---------|-------------|
+| `characters <projectId>` | List characters + readiness (reference images) |
+| `edit-character` | Update character description or edit image via AI |
 
-| Task | Command |
-|------|---------|
-| **Single image** | `request --type GENERATE_IMAGES --project ... --chapter ... --scene ... --wait` |
-| **Single video** | `request --type GENERATE_VIDEO --project ... --chapter ... --scene ... --wait` |
-| **All images** | `batch-request --type GENERATE_IMAGES --project ... --chapter ... --all --wait` |
-| **All videos** | `batch-request --type GENERATE_VIDEO --project ... --chapter ... --all --wait` |
-| **Full project** | `quick-project --keyword "..." --lang ... --material ... --scenes 5 --wait` |
+### Generation
 
-### Status Commands: When to Use Which
+| 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 |
 
-| 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) |
+### Monitoring
 
----
+| Command | Description |
+|---------|-------------|
+| `scene-status` | Scene-level image+video status with asset URLs |
+| `workflow-status` | Full snapshot: scenes + requests + assets (best for agents) |
 
-## Video Speed Modes
+### YouTube
 
-VEOGENT supports three video speed modes via `--speed` on `request` and `batch-request`:
+| Command | Description |
+|---------|-------------|
+| `generate-yt-metadata` | Generate Title/Description/Tags for a chapter |
+| `generate-yt-thumbnail` | Trigger thumbnail generation |
+| `yt-thumbnails` | Get generated thumbnails |
 
-| Mode | Description | Use case |
-|------|-------------|----------|
-| `normal` | Standard playback speed (default) | Most scenes, dialogue, actions |
-| `timelapse` | Accelerated time compression | Sunrise/sunset, city traffic, cooking montage, cloud movement |
-| `slowmotion` | Slow-motion playback | Impact moments, water splash, dramatic reveal, emotional beats |
+### Utility
 
-```bash
-# Normal speed (default)
-veogent request --type GENERATE_VIDEO --project X --chapter Y --scene Z --speed normal
+| 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 |
 
-# Timelapse
-veogent request --type GENERATE_VIDEO --project X --chapter Y --scene Z --speed timelapse
+---
 
-# Slow motion for dramatic effect
-veogent request --type GENERATE_VIDEO --project X --chapter Y --scene Z --speed slowmotion
-```
+## Video Speed Modes
 
-> **Tip:** Speed mode affects Veo's generation. Timelapse tends to produce more camera movement and environmental change. Slowmotion emphasizes subject detail and motion blur.
+| 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 |
 
 ---
 
-## Chained Video Generation (endScene)
+## Chained Video (endScene)
 
-Generate continuous video that transitions smoothly from one scene to the next using `--endscene`:
+Smooth transition between two consecutive scenes:
 
 ```bash
 veogent request --type GENERATE_VIDEO --project X --chapter Y --scene sceneA \
-  --endscene sceneB --orientation VERTICAL --videomodel veo_3_1_fast
+  --endscene sceneB --videomodel veo_3_1_fast --orientation VERTICAL
 ```
 
-### How it works
-1. Veo uses **sceneA's image** as the starting frame
-2. Veo uses **sceneB's image** as the ending frame
-3. The generated video transitions smoothly between both scenes
-4. Response includes `generationMode: "CHAINED_VIDEO"` and `end_scene_id`
-
-### When to use
-- Scene transitions that need visual continuity (character walks from location A to B)
-- Smooth camera movements between setups
-- Story beats that connect two distinct moments
-
-### Requirements
-- Both sceneA and sceneB must have successful images (matching orientation)
-- Uses the same Flow Key / credit system as regular video generation
+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`.
 
 ---
 
-## 🤖 For AI Agents
+## Concurrency
 
-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`.
+Maximum **5** concurrent requests. If queue is full (E10071), CLI auto-retries once after 30s.
 
-### Recommended Agent Workflow (Production)
+`batch-request` respects the 5-request limit with inter-batch throttling.
 
-**Option A: Quick Start (v1.3.0+ compound commands)**
-```bash
-# 1. Create full project in one command (steps 1-6 combined)
-veogent quick-project --keyword "shiba night market" --lang Vietnamese \
-  --material CINEMATIC --scenes 5 --wait
-
-# 2. Generate all images at once
-veogent batch-request --type GENERATE_IMAGES --project X --chapter Y \
-  --all --orientation VERTICAL --wait
-
-# 3. QA images → fix with edit-scene
-veogent edit-scene --project X --chapter Y --scene Z \
-  --userprompt "Mochi walks through the market gate" --wait
-
-# 4. Generate all videos at once
-veogent batch-request --type GENERATE_VIDEO --project X --chapter Y \
-  --all --orientation VERTICAL --wait
+---
 
-# 5. QA videos → fix and regenerate
-```
+## 🤖 For AI Agents
 
-**Option B: Step-by-step (full control)**
-
-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" ... --wait`
-   - If image is reported wrong, fix via:
-     - `veogent edit-scene --userprompt "..." --wait` (prompt refinement), or
-     - `veogent edit-scene --request <requestId> ... --wait` (direct edit on prior generated image)
-9. Generate video only after matching-orientation image exists successfully:
-   - `veogent request --type "GENERATE_VIDEO" ... --wait`
-
-> 📖 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
 
 ---