@growthub/cli 0.3.54 → 0.3.56

package/assets/worker-kits/growthub-open-montage-studio-v1/skills.md

@@ -0,0 +1,254 @@
+# Open Montage Studio — Master Skill Document
+
+This is the canonical methodology reference for the Open Montage Studio Operator. Read this file at the start of every session before producing any artifacts.
+
+---
+
+## 1. Workflow Order
+
+The operator follows a strict 10-step workflow defined in `workers/open-montage-studio-operator/CLAUDE.md`. This skill doc provides the detailed methodology for steps 5 through 9.
+
+---
+
+## 2. Pipeline Selection Logic
+
+OpenMontage supports 12 production pipelines. Selection is a structured decision, not a guess.
+
+### Decision Tree
+
+```
+Intent: Explain a topic to an audience?
+  YES → Animated Explainer
+
+Intent: Create motion graphics, kinetic typography, or abstract animation?
+  YES → Animation
+
+Intent: Avatar-driven presenter video?
+  YES → Avatar Spokesperson
+
+Intent: Cinematic trailer, teaser, or mood-driven brand film?
+  YES → Cinematic
+
+Intent: Batch of ranked short-form clips from one long source?
+  YES → Clip Factory
+
+Intent: Thematic montage from real stock footage or open archives?
+  YES → Documentary Montage
+
+Intent: Enhance existing footage with AI-generated support visuals?
+  YES → Hybrid
+
+Intent: Subtitle, dub, or translate existing video into other languages?
+  YES → Localization & Dub
+
+Intent: Turn podcast highlights into video?
+  YES → Podcast Repurpose
+
+Intent: Polished software screen recording or walkthrough?
+  YES → Screen Demo
+
+Intent: Footage-led speaker video, presentation, or vlog?
+  YES → Talking Head
+```
+
+If the intent spans two pipelines, pick the primary and document the secondary as a composition layer or follow-up pipeline.
+
+### Pipeline Stage Flow (Universal)
+
+Every pipeline follows the same structured flow:
+
+```
+research → proposal → script → scene_plan → assets → edit → compose
+```
+
+Each stage has a dedicated director skill in the OpenMontage fork at `skills/pipelines/<pipeline-name>/`.
+
+---
+
+## 3. Provider Scoring Methodology
+
+Every tool selection runs through a 7-dimension scoring engine.
+
+| Dimension | Weight | What It Measures |
+|-----------|--------|------------------|
+| Task fit | 30% | How well the tool matches the specific production need |
+| Output quality | 20% | Resolution, fidelity, consistency of results |
+| Control features | 15% | Prompt adherence, style control, parameter granularity |
+| Reliability | 15% | Uptime, error rate, queue latency |
+| Cost efficiency | 10% | Price per output unit relative to quality |
+| Latency | 5% | Time from request to deliverable |
+| Continuity | 5% | Session persistence, resumability, rate limits |
+
+### Provider Tiers
+
+**Zero-cost (always available):**
+- Piper TTS — offline narration
+- Archive.org + NASA + Wikimedia — free archival footage
+- Remotion — React-based programmatic video composition
+- FFmpeg — encoding, subtitles, audio mixing, color grading
+
+**Free-key (developer accounts, no charge):**
+- Pexels, Pixabay, Unsplash — stock media
+- Google TTS — 1M chars/month free
+- ElevenLabs — 10K chars/month free
+
+**Pay-as-you-go:**
+- fal.ai (FAL_KEY) — FLUX images + Kling/Veo/MiniMax video
+- OpenAI — DALL-E 3 + TTS
+- Google Imagen — $0.02-0.06/image
+- xAI Grok — images + video
+- Runway Gen-4 — highest quality AI video
+- Higgsfield — multi-model video orchestrator
+- HeyGen — avatar videos
+- Suno — AI music generation
+
+**Local GPU (free, requires hardware):**
+- WAN 2.1, Hunyuan, CogVideo, LTX-Video — local video generation
+- Stable Diffusion — local image generation
+
+---
+
+## 4. CMS Node Bridge Mapping
+
+GrowthHub CMS nodes expose video and image generation as hosted execution capabilities. The bridge maps these into the OpenMontage production flow.
+
+### How It Works
+
+1. Agent queries the CMS capability registry for available nodes in the `video` and `image` families
+2. CMS nodes execute via hosted execution client, producing output URLs
+3. Output URLs are treated as source assets in the OpenMontage pipeline
+4. OpenMontage handles composition, post-production, and final rendering
+
+### CMS Family → OpenMontage Mapping
+
+| CMS Node Family | CMS Execution Kind | OpenMontage Integration Point |
+|-----------------|--------------------|-----------------------------|
+| `video` | `hosted-execute` | Source clips for `tools/video/` input or direct composition via Remotion/FFmpeg |
+| `image` | `hosted-execute` | Scene images for `tools/graphics/` input or Remotion animated composition |
+| `slides` | `hosted-execute` | Slide deck assets for Screen Demo pipeline |
+| `text` | `hosted-execute` | Script/narration text for TTS processing |
+
+### CMS Node Output → OpenMontage Asset Type
+
+| CMS Output Type | OpenMontage Asset Category | Typical Usage |
+|-----------------|---------------------------|---------------|
+| Video URL | `source_clip` | Scene footage, B-roll, transition clips |
+| Image URL | `scene_image` | Hero shots, backgrounds, product stills |
+| Audio URL | `narration` or `music` | Voiceover, soundtrack |
+| Text | `script` | Script content for TTS conversion |
+
+### When to Use CMS Nodes vs Direct Providers
+
+Use CMS nodes when:
+- The user has an active GrowthHub session
+- The generation type matches an available CMS node
+- The user wants unified billing through GrowthHub
+- The user does not have direct provider API keys
+
+Use direct providers when:
+- Local-fork mode with full tool access
+- The specific tool/model is not available as a CMS node
+- Lower latency is needed (direct API vs hosted execution)
+- The user has provider keys and prefers direct access
+
+---
+
+## 5. Prompt Planning Rules
+
+### Image Prompts
+
+1. Lead with the subject and composition
+2. Include style directive (photorealistic, illustrated, anime, etc.)
+3. Specify lighting and mood
+4. Add technical parameters (aspect ratio, resolution)
+5. Include negative prompts when the provider supports them
+
+### Video Prompts
+
+1. Describe the motion and camera movement
+2. Specify duration target
+3. Reference the source image if using image-to-video
+4. Include style consistency directives
+5. Note any audio sync requirements
+
+### Scene Sequencing
+
+1. Each scene maps to one pipeline stage asset
+2. Scenes must have explicit transition types (cut, crossfade, wipe, zoom)
+3. Audio cues align to scene boundaries
+4. Subtitle timing derives from script word timestamps
+
+---
+
+## 6. Output Artifact Order
+
+Produce artifacts in this strict order:
+
+1. **VideoProductionBrief** — What we are making, why, for whom
+2. **PipelineSelectionBrief** — Which pipeline, why, fallback
+3. **ProviderSelectionBrief** — Which providers/CMS nodes, scoring, cost estimate
+4. **ScenePlan** — Scene-by-scene breakdown with timing, transitions, audio cues
+5. **PromptMatrix** — Per-scene prompts for all generation tools
+6. **GenerationBatchPlan** — Execution order, dependencies, parallel opportunities
+7. **AssetTracking** — Generated asset inventory with URLs, statuses, costs
+8. **ReviewQAChecklist** — Quality gates, validation points, approval criteria
+9. **PlatformReadyExecutionHandoff** — Complete handoff doc for execution
+
+---
+
+## 7. QA Standards
+
+### Pre-Compose Validation
+
+Before rendering:
+- All scene assets exist and are accessible
+- Audio tracks are present and duration-matched
+- Subtitle timing is aligned
+- Delivery promise is achievable with available tools
+- Budget is within approved cap
+
+### Post-Render Self-Review
+
+After rendering:
+- ffprobe validation (codec, resolution, duration, bitrate)
+- Frame extraction at key points (first, middle, last, transitions)
+- Audio level analysis (no clipping, consistent volume)
+- Subtitle readability check
+- Delivery promise verification
+
+### Slideshow Risk Check
+
+If the output is image-based video, score across 6 dimensions:
+- Motion variety (camera moves, parallax, Ken Burns)
+- Transition diversity (not all cuts)
+- Animation layer count (particles, overlays, text motion)
+- Audio-visual sync
+- Pacing variation
+- Visual grammar complexity
+
+A score below 60% triggers a warning and requires explicit user approval to proceed.
+
+---
+
+## 8. Budget Governance
+
+- Estimate costs before execution
+- Reserve budget before each provider call
+- Reconcile actual spend after each call
+- Default per-action approval threshold: $0.50
+- Default total budget cap: $10
+- CMS node costs flow through GrowthHub billing (no separate tracking needed)
+- Always present cost summary before starting generation
+
+---
+
+## 9. Handoff Standards
+
+Every handoff document must include:
+- Execution mode (local-fork / agent-only / hybrid)
+- Complete asset manifest with URLs or file paths
+- Provider/CMS node execution instructions
+- Post-production steps (composition, audio, subtitles, color grade)
+- Render profile (resolution, aspect ratio, codec, target platform)
+- Estimated total cost and actual spend
+- Known limitations or manual steps required

package/assets/worker-kits/growthub-open-montage-studio-v1/templates/asset-tracking.md

@@ -0,0 +1,46 @@
+# Asset Tracking
+
+## Project Reference
+
+| Field | Value |
+|---|---|
+| Client | `<client-name>` |
+| Project | `<project-name>` |
+| Date | `YYYY-MM-DD` |
+
+## Generated Assets
+
+| ID | Scene | Type | Provider / CMS Node | Status | URL / Path | Cost | Notes |
+|---|---|---|---|---|---|---|---|
+| A-001 | 1 | image | | `<pending / generating / ready / failed>` | | | |
+| A-002 | 2 | image | | | | | |
+| A-003 | 1 | video | | | | | |
+| A-004 | — | narration | | | | | |
+| A-005 | — | music | | | | | |
+
+## Reuse Inventory
+
+<!-- Assets from previous sessions or existing brand kit that can be reused. -->
+
+| Asset | Source | Reusable For | Notes |
+|---|---|---|---|
+| | | | |
+
+## CMS Node Outputs
+
+<!-- Track assets generated through GrowthHub CMS nodes separately for billing clarity. -->
+
+| CMS Node Slug | Execution ID | Output Type | URL | Status |
+|---|---|---|---|---|
+| | | | | |
+
+## Cost Ledger
+
+| Category | Budgeted | Actual | Delta |
+|---|---|---|---|
+| Images | | | |
+| Video | | | |
+| Audio | | | |
+| Music | | | |
+| CMS nodes | — | — | — |
+| **Total** | **$—** | **$—** | **$—** |

package/assets/worker-kits/growthub-open-montage-studio-v1/templates/cms-node-pipeline-mapping.md

@@ -0,0 +1,64 @@
+# CMS Node → OpenMontage Pipeline Mapping
+
+## Purpose
+
+This template documents how GrowthHub CMS node outputs integrate into the selected OpenMontage pipeline. Fill this out when the production plan uses CMS nodes for any generation step.
+
+## Project Reference
+
+| Field | Value |
+|---|---|
+| Client | `<client-name>` |
+| Project | `<project-name>` |
+| Pipeline | `<selected-pipeline>` |
+| Date | `YYYY-MM-DD` |
+
+## CMS Nodes in Use
+
+| CMS Node Slug | Family | Execution Kind | Role in Pipeline |
+|---|---|---|---|
+| | `video` / `image` / `text` | `hosted-execute` | |
+
+## Mapping: CMS Output → OpenMontage Input
+
+| CMS Node | Output Type | Output Format | OpenMontage Stage | OpenMontage Tool Category | Integration Method |
+|---|---|---|---|---|---|
+| | Video URL | mp4 | `assets` | `tools/video/` | Download URL → source clip |
+| | Image URL | png/jpg | `assets` | `tools/graphics/` | Download URL → scene image |
+| | Audio URL | mp3/wav | `edit` | `tools/audio/` | Download URL → narration track |
+| | Text | string | `script` | — | Direct script content |
+
+## Execution Flow
+
+```
+1. Agent identifies required CMS nodes from the scene plan
+2. Agent prepares input bindings for each CMS node
+3. CMS nodes execute via hosted execution client
+4. Agent collects output URLs from execution results
+5. Output URLs feed into OpenMontage pipeline at the appropriate stage
+6. OpenMontage handles composition and post-production
+```
+
+## Input Bindings Per Node
+
+### CMS Node: `<slug>`
+
+| Input Key | Type | Value | Source |
+|---|---|---|---|
+| | | | `<from scene plan / user input / previous node output>` |
+
+## Output Routing
+
+### CMS Node: `<slug>`
+
+| Output Key | Type | Routes To | OpenMontage Asset ID |
+|---|---|---|---|
+| | | Scene `<N>` source clip / image | `A-<NNN>` |
+
+## Fallback Plan
+
+If a CMS node execution fails:
+
+| CMS Node | Fallback Provider | Fallback Tool | Cost Impact |
+|---|---|---|---|
+| | | | |

package/assets/worker-kits/growthub-open-montage-studio-v1/templates/generation-batch-plan.md

@@ -0,0 +1,70 @@
+# Generation Batch Plan
+
+## Project Reference
+
+| Field | Value |
+|---|---|
+| Client | `<client-name>` |
+| Project | `<project-name>` |
+| Pipeline | `<selected-pipeline>` |
+| Date | `YYYY-MM-DD` |
+
+## Execution Order
+
+Batches run top-to-bottom. Items within a batch can run in parallel.
+
+### Batch 1 — Research & Script
+
+| Step | Tool / Action | Input | Output | Depends On |
+|---|---|---|---|---|
+| 1.1 | Web search | Topic keywords | Research brief | — |
+| 1.2 | Script draft | Research brief | Script | 1.1 |
+
+### Batch 2 — Image Generation
+
+| Step | Provider / CMS Node | Prompt Ref | Input Assets | Expected Output | Est. Cost |
+|---|---|---|---|---|---|
+| 2.1 | | Scene 1 prompt | — | Scene 1 image | |
+| 2.2 | | Scene 2 prompt | — | Scene 2 image | |
+| 2.3 | | Scene 3 prompt | — | Scene 3 image | |
+
+### Batch 3 — Video Generation (if applicable)
+
+| Step | Provider / CMS Node | Prompt Ref | Source Image | Duration | Est. Cost |
+|---|---|---|---|---|---|
+| 3.1 | | Scene 1 video prompt | Scene 1 image | 5s | |
+| 3.2 | | Scene 2 video prompt | Scene 2 image | 5s | |
+
+### Batch 4 — Audio
+
+| Step | Provider | Type | Input | Duration | Est. Cost |
+|---|---|---|---|---|---|
+| 4.1 | | TTS narration | Script | — | |
+| 4.2 | | Background music | Genre/mood spec | — | |
+
+### Batch 5 — Composition & Post-Production
+
+| Step | Tool | Input | Output | Depends On |
+|---|---|---|---|---|
+| 5.1 | Remotion / FFmpeg | All scene assets + audio | Draft render | Batches 2-4 |
+| 5.2 | Subtitle gen | TTS audio | SRT/VTT | 4.1 |
+| 5.3 | FFmpeg | Draft render + subtitles | Final render | 5.1, 5.2 |
+
+## Cost Summary
+
+| Batch | Estimated Cost |
+|---|---|
+| Batch 1 (Research) | $0.00 |
+| Batch 2 (Images) | $— |
+| Batch 3 (Video) | $— |
+| Batch 4 (Audio) | $— |
+| Batch 5 (Post) | $0.00 |
+| **Total** | **$—** |
+
+## Budget Gate
+
+| Field | Value |
+|---|---|
+| Budget cap | $10.00 |
+| Estimated total | $— |
+| Approved | `<yes / pending>` |

package/assets/worker-kits/growthub-open-montage-studio-v1/templates/pipeline-selection-brief.md

@@ -0,0 +1,67 @@
+# Pipeline Selection Brief
+
+## Project Reference
+
+| Field | Value |
+|---|---|
+| Client | `<client-name>` |
+| Project | `<project-name>` |
+| Date | `YYYY-MM-DD` |
+
+## Requested Outcome
+
+<!-- What the user asked for in their own words. -->
+
+## Selected Pipeline
+
+| Field | Value |
+|---|---|
+| Pipeline | `<Animated Explainer / Animation / Avatar Spokesperson / Cinematic / Clip Factory / Documentary Montage / Hybrid / Localization & Dub / Podcast Repurpose / Screen Demo / Talking Head>` |
+| Reason | <!-- Why this pipeline is the best match --> |
+
+## Pipeline Fit Assessment
+
+| Criterion | Score (1-5) | Notes |
+|---|---|---|
+| Content type match | | |
+| Available tool coverage | | |
+| Source asset alignment | | |
+| Budget feasibility | | |
+| Quality ceiling | | |
+
+## Input Asset Requirements
+
+<!-- What the selected pipeline needs to execute. -->
+
+## Output Specification
+
+| Field | Value |
+|---|---|
+| Primary deliverable | |
+| Duration | |
+| Resolution | |
+| Codec | |
+
+## Fallback Pipeline
+
+| Field | Value |
+|---|---|
+| Pipeline | `<fallback-pipeline>` |
+| Trigger | <!-- When to switch --> |
+| Trade-off | <!-- What changes with the fallback --> |
+
+## Pipeline Stage Plan
+
+```
+research → proposal → script → scene_plan → assets → edit → compose
+```
+
+| Stage | Owner | Tool / CMS Node | Notes |
+|---|---|---|---|
+| Research | Agent | Web search | |
+| Proposal | Agent | — | |
+| Script | Agent | — | |
+| Scene plan | Agent | — | |
+| Assets | Agent + Provider | `<tool-or-cms-node>` | |
+| Edit | Agent | FFmpeg / Remotion | |
+| Compose | Agent | Remotion / FFmpeg | |

package/assets/worker-kits/growthub-open-montage-studio-v1/templates/platform-ready-execution-handoff.md

@@ -0,0 +1,103 @@
+# Platform-Ready Execution Handoff
+
+## Project Reference
+
+| Field | Value |
+|---|---|
+| Client | `<client-name>` |
+| Project | `<project-name>` |
+| Pipeline | `<selected-pipeline>` |
+| Execution mode | `<local-fork / agent-only / hybrid>` |
+| Date | `YYYY-MM-DD` |
+
+## Deliverable Summary
+
+| Field | Value |
+|---|---|
+| Video title | |
+| Duration | `<seconds>` |
+| Resolution | `<WxH>` |
+| Aspect ratio | `<ratio>` |
+| Platform target | `<YouTube / TikTok / Instagram / LinkedIn>` |
+| Estimated cost | `$—` |
+| Actual cost | `$—` |
+
+## Execution Instructions
+
+### For local-fork mode
+
+```bash
+cd ~/OpenMontage
+
+# 1. Verify environment
+python -c "from tools.tool_registry import registry; registry.discover(); print('OK')"
+
+# 2. Run the pipeline
+# The agent executes each stage in order:
+#   research → proposal → script → scene_plan → assets → edit → compose
+
+# 3. Final render location
+# Output: output/<project-slug>/final-render.<ext>
+```
+
+### For agent-only mode (CMS node generation)
+
+1. Execute CMS nodes via GrowthHub hosted execution:
+
+| Step | CMS Node Slug | Inputs | Expected Output |
+|---|---|---|---|
+| 1 | | | |
+| 2 | | | |
+
+2. Collect output URLs from CMS node execution results
+3. Follow post-production guidance below
+
+### For hybrid mode
+
+1. Generate assets via CMS nodes (see agent-only instructions above)
+2. Run local OpenMontage post-production:
+
+```bash
+cd ~/OpenMontage
+# Composition, audio mixing, subtitle burn-in, color grading
+# Use the scene plan and prompt matrix from this handoff
+```
+
+## Asset Manifest
+
+| ID | Type | Source | URL / Path | Status |
+|---|---|---|---|---|
+| | | | | |
+
+## Post-Production Steps
+
+| Step | Tool | Input | Output | Notes |
+|---|---|---|---|---|
+| 1 | Remotion / FFmpeg | Scene assets | Draft composition | |
+| 2 | Subtitle gen | Narration audio | SRT/VTT file | |
+| 3 | FFmpeg | Draft + subtitles | Subtitled render | |
+| 4 | FFmpeg | Subtitled render | Color-graded final | Optional |
+
+## Render Profile
+
+| Field | Value |
+|---|---|
+| Resolution | |
+| FPS | |
+| Codec | |
+| Bitrate | |
+| Audio codec | |
+| Container | |
+
+## Known Limitations
+
+<!-- Any manual steps, unsupported features, or quality compromises. -->
+
+## Approval
+
+| Gate | Status |
+|---|---|
+| Production brief approved | `<yes / no>` |
+| Budget approved | `<yes / no>` |
+| QA checklist passed | `<yes / no>` |
+| Ready for execution | `<yes / no>` |

package/assets/worker-kits/growthub-open-montage-studio-v1/templates/prompt-matrix.md

@@ -0,0 +1,48 @@
+# Prompt Matrix
+
+## Project Reference
+
+| Field | Value |
+|---|---|
+| Client | `<client-name>` |
+| Project | `<project-name>` |
+| Pipeline | `<selected-pipeline>` |
+| Date | `YYYY-MM-DD` |
+
+## Image Generation Prompts
+
+| Scene | Provider / CMS Node | Model | Prompt | Style Directive | Aspect Ratio | Negative Prompt | Expected Cost |
+|---|---|---|---|---|---|---|---|
+| 1 | | | | | | | |
+| 2 | | | | | | | |
+| 3 | | | | | | | |
+
+## Video Generation Prompts
+
+| Scene | Provider / CMS Node | Model | Prompt | Source Image | Duration | Camera Motion | Expected Cost |
+|---|---|---|---|---|---|---|---|
+| 1 | | | | | | | |
+| 2 | | | | | | | |
+
+## TTS Prompts
+
+| Scene | Provider | Voice | Text | Speed | Emotion | Expected Cost |
+|---|---|---|---|---|---|---|
+| 1 | | | | | | |
+| 2 | | | | | | |
+
+## Music Prompts
+
+| Track | Provider | Genre | Mood | Duration | Instrumental | Expected Cost |
+|---|---|---|---|---|---|---|
+| BG | | | | | | |
+
+## Style Consistency Rules
+
+<!-- Global style directives that apply across all prompts. -->
+
+- Base style: `<photorealistic / illustrated / anime / flat motion / minimalist>`
+- Color palette: `<description or hex values>`
+- Typography: `<font family, weight, treatment>`
+- Lighting: `<natural / studio / cinematic / neon>`
+- Consistency anchor: `<reference image URL or description>`