@growthub/cli 0.3.38 → 0.3.40

package/README.md

@@ -27,7 +27,9 @@ They should be understood as packaged execution environments. A kit can carry pr
 ```bash
 growthub kit list
 growthub kit inspect creative-strategist-v1
+growthub kit inspect growthub-open-higgsfield-studio-v1
 growthub kit download creative-strategist-v1
+growthub kit download growthub-open-higgsfield-studio-v1
 growthub kit path creative-strategist-v1
 growthub kit validate /absolute/path/to/kit
 ```
@@ -35,9 +37,9 @@ growthub kit validate /absolute/path/to/kit
 V1 is intentionally narrow:
 
 - bundled catalog plus local export only
-- one downloadable Creative Strategist kit
+- downloadable worker kits for creative strategy, email strategy, and Open Higgsfield AI visual production
 - deterministic zip plus expanded export folder
-- public `solawave` example brand included
+- public example brand kits only
 - no heartbeat wiring, app install flow, server registry, plugin lifecycle, or database kit records
 
 ### How local adapters use worker kits

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/.env.example

@@ -0,0 +1,9 @@
+# Growthub Open Higgsfield Studio — Environment Config
+# Copy this file to .env and fill in your values.
+# Never commit .env to version control.
+
+# Your Muapi API key — get one at https://muapi.ai/dashboard
+MUAPI_API_KEY=your_muapi_key_here
+
+# Muapi base URL — do not change unless self-hosting
+MUAPI_BASE_URL=https://api.muapi.io

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/QUICKSTART.md

@@ -0,0 +1,95 @@
+# Quick Start — Open Higgsfield Studio Worker Kit
+
+This folder is your self-contained agent working directory for Open Higgsfield AI visual production.
+
+---
+
+## Step 1 — Point your Working Directory at this folder
+
+**Growthub local (primary):** Open Growthub local and set the **Working Directory** to this folder in your project settings. Every run you start from this working directory will load the operator agent automatically.
+
+**Claude Code (alternative):** Open Claude Code settings and set the **Working Directory** to this folder. The operator agent loads from `workers/open-higgsfield-studio-operator/CLAUDE.md` on session start.
+
+---
+
+## Step 2 — Add your MUAPI key
+
+```bash
+cp .env.example .env
+```
+
+Open `.env` and replace `your_muapi_key_here` with your key from [muapi.ai/dashboard](https://muapi.ai/dashboard).
+
+The agent checks for this key at the start of every session (Step 0 of the workflow). It will not proceed without it.
+
+---
+
+## Step 3 — Verify your key works (optional but recommended)
+
+```bash
+node setup/verify-env.mjs
+```
+
+Runs a lightweight ping against the Muapi API with your key. Exits 0 on success. Prints a clear error if the key is invalid or unreachable.
+
+---
+
+## Step 4 — Check local dependencies (local-fork mode only)
+
+```bash
+bash setup/check-deps.sh
+```
+
+Checks for `node`, `npm`, `git`, and `ffmpeg`. All four are required for local-fork execution and frame-analysis workflows.
+
+---
+
+## Step 5 — Boot the local fork (local-fork mode only)
+
+```bash
+bash setup/clone-fork.sh
+```
+
+Clones the Open Higgsfield AI repo to `~/open-higgsfield-ai`, installs dependencies, **automatically applies the CORS proxy patch** (see `setup/patch-cors-proxy.sh`), and starts the dev server at `http://localhost:3001`.
+
+The CORS patch is required — the upstream repo calls `api.muapi.ai` directly from the browser, which modern browsers block. The patch routes all API calls through the local Next.js server instead.
+
+Skip this step if you are using browser-hosted or desktop-app mode.
+
+**Already cloned but hitting CORS errors?** Run the patch standalone:
+```bash
+bash setup/patch-cors-proxy.sh
+```
+Then restart your dev server.
+
+---
+
+## Step 6 — Start a new session
+
+**Growthub local:** Start a new run from this working directory. The agent loads automatically.
+
+**Claude Code:** Open a new session with this folder as the Working Directory. The agent reads `skills.md` and the methodology automatically.
+
+In both cases the agent will ask you 3 clarifying questions before generating anything.
+
+---
+
+## Execution modes
+
+| Mode | When to use |
+|---|---|
+| `local-fork` | Local checkout running at localhost:3001 |
+| `browser-hosted` | Hosted app at muapi.ai/open-higgsfield-ai |
+| `desktop-app` | Electron app installed locally |
+
+---
+
+## First-run checklist
+
+See `validation-checklist.md` for the full pre-session checklist before your first generation run.
+
+---
+
+## Creating a brand kit for a new client
+
+See `brands/NEW-CLIENT.md`.

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/brands/NEW-CLIENT.md

@@ -0,0 +1,46 @@
+# Creating a New Client Brand Kit
+
+Each client you run campaigns for should have their own brand kit. The agent uses this as its primary brand reference during Step 1 of every session.
+
+---
+
+## Setup
+
+```bash
+cp brands/_template/brand-kit.md brands/<client-slug>/brand-kit.md
+```
+
+Replace `<client-slug>` with a lowercase hyphenated identifier (e.g. `acme-corp`, `solo-founder`, `ecom-brand-x`).
+
+---
+
+## Required fields to fill in
+
+Open your new `brands/<client-slug>/brand-kit.md` and complete:
+
+| Field | What to write |
+|---|---|
+| Brand name | Full brand name as it appears in content |
+| Visual identity | Colors, typography, logo usage notes |
+| Tone and voice | Adjectives that describe how the brand communicates |
+| Target audience | Who the content is for |
+| Content restrictions | What to avoid in visuals or copy |
+| Reference assets | Paths to existing brand images, videos, or logo files |
+
+Fill in every section. Incomplete brand kits result in generic outputs.
+
+---
+
+## Telling the agent to use your brand kit
+
+At the start of your session, say:
+
+> "Use `brands/<client-slug>/brand-kit.md` as the active brand kit."
+
+The agent will load it in Step 1 instead of the Growthub default.
+
+---
+
+## Multiple clients
+
+Keep one subdirectory per client under `brands/`. Each session uses exactly one active brand kit.

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/brands/_template/brand-kit.md

@@ -0,0 +1,89 @@
+# Brand Kit — [CLIENT NAME]
+
+Copy to `brands/<client-slug>/brand-kit.md` and fill before producing outputs.
+
+---
+
+## IDENTITY
+
+```yaml
+client_name: "[CLIENT NAME]"
+slug: "[client-slug]"
+industry: "[industry]"
+primary_offer: "[offer]"
+campaign_owner: "[owner]"
+date_onboarded: "YYYY-MM-DD"
+```
+
+## AUDIENCE
+
+```yaml
+primary_persona:
+  role: "[role]"
+  company_type: "[company type]"
+  pain_point: "[pain]"
+  desired_outcome: "[desired outcome]"
+  awareness_level: "[awareness]"
+```
+
+## POSITIONING
+
+```yaml
+core_positioning: "[one-sentence positioning]"
+what_they_buy: "[outcome they actually want]"
+unique_mechanism: "[why this works]"
+proof_points:
+  - "[approved proof only]"
+```
+
+## VISUAL SYSTEM
+
+```yaml
+visual_identity:
+  palette:
+    primary: "#000000"
+    secondary: "#FFFFFF"
+    accent: "#CCCCCC"
+  visual_adjectives:
+    - "[cinematic]"
+    - "[premium]"
+    - "[clean]"
+  prohibited_visuals:
+    - "[visual no-go]"
+    - "[visual no-go]"
+  reference_styles:
+    - "[director / campaign / style]"
+```
+
+## MESSAGING
+
+```yaml
+voice_and_tone:
+  - "[direct]"
+  - "[clear]"
+approved_phrases:
+  - "[approved phrase]"
+messaging_guardrails:
+  - "[no-go claim]"
+cta_language:
+  primary: "[primary CTA]"
+  secondary: "[secondary CTA]"
+```
+
+## ASSET LIBRARY
+
+```yaml
+available_assets:
+  product_stills: "[path or URL]"
+  brand_guidelines: "[path or URL]"
+  source_video: "[path or URL]"
+  portrait_assets: "[path or URL]"
+  audio_assets: "[path or URL]"
+  prior_generations: "[path or URL]"
+```
+
+## DELIVERABLES LOG
+
+```text
+- YYYY-MM-DD | Open Higgsfield Visual Package v<N> — <Project Name> | output/<client-slug>/<project-slug>/
+```

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/brands/growthub/brand-kit.md

@@ -0,0 +1,96 @@
+# Brand Kit — Growthub
+
+Reference example brand kit for visual-generation work.
+
+---
+
+## IDENTITY
+
+```yaml
+client_name: "Growthub"
+slug: "growthub"
+industry: "AI-enabled growth infrastructure and creative operations"
+primary_offer: "Creative velocity systems, visual strategy, and execution support for paid-media operators"
+campaign_owner: "Growthub"
+date_onboarded: "2026-04-10"
+```
+
+## AUDIENCE
+
+```yaml
+primary_persona:
+  role: "performance lead, agency owner, or growth operator"
+  company_type: "DTC brand, agency, or startup running paid acquisition"
+  pain_point: "creative throughput is too slow to sustain testing velocity"
+  desired_outcome: "more winning concepts without slower turnaround or more headcount"
+  awareness_level: "problem-aware"
+```
+
+## POSITIONING
+
+```yaml
+core_positioning: "Growthub is the operating layer that removes the bottleneck between creative ideas and campaign execution."
+what_they_buy: "speed to winning creative with more control and less chaos"
+unique_mechanism: "operator-grade planning plus AI-assisted visual production workflows"
+proof_points:
+  - "Use only approved client-result examples already cleared by Growthub"
+```
+
+## VISUAL SYSTEM
+
+```yaml
+visual_identity:
+  palette:
+    primary: "#0E1726"
+    secondary: "#F4F1E8"
+    accent: "#D8613C"
+  visual_adjectives:
+    - "decisive"
+    - "cinematic"
+    - "premium"
+    - "high-signal"
+  prohibited_visuals:
+    - "generic SaaS gradient slop"
+    - "empty dashboard glamour shots with no human tension"
+  reference_styles:
+    - "high-contrast product-led motion"
+    - "operator POV"
+    - "documentary-meets-performance-marketing"
+```
+
+## MESSAGING
+
+```yaml
+voice_and_tone:
+  - "direct"
+  - "operator-level"
+  - "confident"
+approved_phrases:
+  - "creative velocity"
+  - "remove the bottleneck between ideas and execution"
+  - "speed to winning ads"
+messaging_guardrails:
+  - "Do not promise guaranteed revenue outcomes"
+  - "Do not reduce Growthub to just an AI tool"
+cta_language:
+  primary: "Book your growth call"
+  secondary: "Review the plan and approve the batch"
+```
+
+## ASSET LIBRARY
+
+```yaml
+available_assets:
+  product_stills: "[fill per engagement]"
+  brand_guidelines: "[fill per engagement]"
+  source_video: "[fill per engagement]"
+  portrait_assets: "[fill per engagement]"
+  audio_assets: "[fill per engagement]"
+  prior_generations: "[fill per engagement]"
+```
+
+## DELIVERABLES LOG
+
+```text
+- 2026-04-10 | Open Higgsfield Visual Package v1 — Studio Launch Reference | output/growthub/studio-launch-reference/
+```

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/bundles/growthub-open-higgsfield-studio-v1.json

@@ -0,0 +1,57 @@
+{
+  "schemaVersion": 2,
+  "bundle": {
+    "id": "growthub-open-higgsfield-studio-v1",
+    "version": "1.0.0",
+    "kitId": "growthub-open-higgsfield-studio-v1",
+    "workerId": "open-higgsfield-studio-operator"
+  },
+  "briefType": "open-higgsfield-visual-production",
+  "publicExampleBrandPaths": [
+    "brands/growthub/brand-kit.md"
+  ],
+  "requiredFrozenAssets": [
+    "QUICKSTART.md",
+    ".env.example",
+    "skills.md",
+    "output-standards.md",
+    "runtime-assumptions.md",
+    "validation-checklist.md",
+    "workers/open-higgsfield-studio-operator/CLAUDE.md",
+    "brands/_template/brand-kit.md",
+    "brands/growthub/brand-kit.md",
+    "brands/NEW-CLIENT.md",
+    "setup/clone-fork.sh",
+    "setup/verify-env.mjs",
+    "setup/check-deps.sh",
+    "output/README.md",
+    "templates/visual-campaign-brief.md",
+    "templates/studio-selection-brief.md",
+    "templates/model-selection-recommendation.md",
+    "templates/shot-plan.md",
+    "templates/prompt-matrix.md",
+    "templates/generation-batch-plan.md",
+    "templates/asset-tracking.md",
+    "templates/review-qa-checklist.md",
+    "templates/platform-ready-execution-handoff.md",
+    "templates/frame-analysis.md",
+    "templates/prompt-templates/image-generation.md",
+    "templates/prompt-templates/video-generation.md",
+    "templates/prompt-templates/lip-sync-generation.md",
+    "templates/prompt-templates/cinema-generation.md",
+    "examples/visual-campaign-brief-sample.md",
+    "examples/shot-plan-sample.md",
+    "examples/prompt-matrix-sample.md",
+    "examples/platform-ready-handoff-sample.md",
+    "docs/open-higgsfield-fork-integration.md",
+    "docs/provider-adapter-layer.md",
+    "growthub-meta/README.md",
+    "growthub-meta/kit-standard.md"
+  ],
+  "optionalPresets": [],
+  "export": {
+    "folderName": "growthub-agent-worker-kit-open-higgsfield-studio-v1",
+    "zipFileName": "growthub-agent-worker-kit-open-higgsfield-studio-v1.zip"
+  },
+  "activationModes": ["export"]
+}

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/docs/open-higgsfield-fork-integration.md

@@ -0,0 +1,63 @@
+# Open Higgsfield Fork Integration Notes
+
+This document tells the agent what to inspect in a maintained local fork before it commits to a plan.
+
+---
+
+## EXPECTED REPO LAYOUT
+
+Based on the upstream repository:
+
+```text
+app/
+components/
+electron/
+packages/studio/src/
+README.md
+package.json
+```
+
+The agent should treat these as the runtime-critical zones:
+- `packages/studio/src/models.js`
+- `packages/studio/src/muapi.js`
+- `packages/studio/src/components/*.jsx`
+- `components/StandaloneShell.js`
+- `components/ApiKeyModal.js`
+- `electron/`
+
+---
+
+## WHAT TO INSPECT BEFORE GENERATING
+
+1. Which studios are actually rendered in the current fork
+2. Whether model ids or endpoint names differ from upstream
+3. Which controls the UI exposes for the chosen model
+4. Whether prompt is optional for the chosen mode
+5. How many input images are supported
+6. Whether upload history and generation history are available
+7. Whether browser and desktop packaging diverge
+
+---
+
+## SOURCE OF TRUTH RULES
+
+- `models.js` is the model source of truth
+- `muapi.js` is the provider request-flow source of truth
+- the relevant studio component is the UI behavior source of truth
+- `README.md` is the environment and packaging overview
+- `electron/` is the desktop-specific behavior source of truth
+
+If these conflict, prefer:
+1. studio component behavior
+2. provider client behavior
+3. model registry
+4. README summary
+
+---
+
+## FORK-AWARE OUTPUT RULE
+
+Every handoff should say whether it was:
+- `fork-verified`
+- `upstream-verified`
+- `assumption-based`

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/docs/provider-adapter-layer.md

@@ -0,0 +1,67 @@
+# Provider Adapter Layer Notes
+
+Muapi is the reference implementation for this kit because the upstream Open Higgsfield AI workflow is built around it. The adapter layer must remain pluggable.
+
+---
+
+## REFERENCE PROVIDER — MUAPI
+
+| Field | Value |
+|---|---|
+| Provider name | Muapi |
+| Auth pattern | `x-api-key` header |
+| Upload flow | file upload first when image, video, or audio assets are required |
+| Submit flow | `POST /api/v1/{model-endpoint}` |
+| Poll flow | `GET /api/v1/predictions/{request_id}/result` |
+| Result flow | completed payload yields output URL(s) and status |
+
+---
+
+## ADAPTER CONTRACT
+
+Every provider adapter should support:
+- `UPLOAD_ASSET`
+- `SUBMIT_GENERATION`
+- `POLL_RESULT`
+- `NORMALIZE_RESULT`
+- `LIST_MODEL_CAPABILITIES`
+
+Optional:
+- `CANCEL_JOB`
+- `LIST_HISTORY`
+- `HEALTHCHECK`
+
+---
+
+## MODEL ENDPOINT MAPPING ASSUMPTION
+
+The agent should assume that a model entry maps to:
+- a studio category
+- an endpoint id
+- accepted inputs
+- exposed controls
+- output class
+
+Do not recommend a model without naming the endpoint or the endpoint assumption.
+
+---
+
+## FALLBACK MODES
+
+When the reference provider path fails:
+- fallback to a second model in the same studio if available
+- fallback to a neighboring studio only if output intent can still be preserved
+- mark the handoff with the exact fallback trigger
+
+---
+
+## FUTURE PROVIDER EXTENSION PATH
+
+New providers should be added by implementing the same contract and documenting:
+- auth
+- endpoint mapping
+- submit / poll rhythm
+- file upload behavior
+- result normalization
+
+Do not rewrite this kit around one provider-specific prompt schema.

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/examples/platform-ready-handoff-sample.md

@@ -0,0 +1,24 @@
+# Growthub Platform-Ready Execution Handoff v1
+
+## Runtime Mode
+
+local-fork
+
+## Repo Inspection Summary
+
+- `packages/studio/src/models.js` reviewed for available video and lip-sync models
+- `packages/studio/src/muapi.js` reviewed for submit and poll behavior
+- `packages/studio/src/components/VideoStudio.jsx` reviewed for i2v vs t2v switching
+
+## Provider Adapter Assumptions
+
+- provider: Muapi
+- auth: `x-api-key`
+- flow: submit -> poll -> result
+
+## Execution Steps
+
+1. open video studio and load prompt `P01`
+2. submit batch `B01`
+3. poll until complete and review for continuity
+4. move to lip-sync batch after hook clip is approved

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/examples/prompt-matrix-sample.md

@@ -0,0 +1,6 @@
+# Growthub Prompt Matrix v1
+
+| Prompt ID | Shot / Output | Studio | Model | Base Prompt | Variation Prompt | Negative / Exclusions | Controls | Assets |
+|---|---|---|---|---|---|---|---|---|
+| P01 | Hook reveal | video | Kling-class T2V | premium operator desk, kinetic startup energy, handheld push-in, warm key light, high-contrast branded palette | same beat with slower dolly and cleaner desk styling | warped hands, brand-off colors, text artifacts | 9:16, 5s | logo stills |
+| P02 | Talking operator | lip-sync | Infinite Talk-class I2V | direct-to-camera founder, calm authority, subtle head motion, realistic office background | increase urgency in expression only | rubber mouth, eye drift, over-animated cheeks | 9:16, 720p | portrait + audio |

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/examples/shot-plan-sample.md

@@ -0,0 +1,7 @@
+# Growthub Shot Plan v1
+
+| Shot ID | Beat | Studio | Model | Assets | Camera Intent | Prompt Key | Ratio / Duration | Passes | Review Note |
+|---|---|---|---|---|---|---|---|---|---|
+| S01 | Hook reveal | video | Kling-class T2V | logo stills | handheld push-in | P01 | 9:16 / 5s | 3 | keep motion tight |
+| S02 | Operator close-up | lip-sync | Infinite Talk-class I2V | portrait + VO | static medium close | P02 | 9:16 / 6s | 2 | check mouth sync |
+| S03 | Hero payoff | cinema | cinema-native | product stills | 50mm dolly-in | P03 | 16:9 / keyframe | 4 | protect palette |

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/examples/visual-campaign-brief-sample.md

@@ -0,0 +1,22 @@
+# Growthub Visual Campaign Brief v1
+
+## Project Overview
+
+| Field | Value |
+|---|---|
+| Client | Growthub |
+| Project | AI UGC launch teaser |
+| Objective | Produce 3 vertical concept clips and 1 cinematic hero still |
+| Primary platform | Meta / TikTok |
+| Runtime mode | local-fork |
+
+## Studio Hypothesis
+
+Primary studio: `video` for motion clips.  
+Fallback studio: `cinema` for hero still and controlled frame development.
+
+## Output Package
+
+- 3 motion concepts
+- 1 hero keyframe
+- 1 asset reuse plan

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/growthub-meta/README.md

@@ -0,0 +1,67 @@
+# Growthub Agent Worker Kit — Open Higgsfield Studio v1
+
+**Kit ID:** `growthub-open-higgsfield-studio-v1`  
+**Version:** `1.0.0`  
+**Type:** `worker`  
+**Execution mode:** `export`
+
+---
+
+## What this kit does
+
+This kit gives an agent a self-contained environment for visual-generation planning and execution support around Open Higgsfield AI.
+
+It packages:
+- agent operating instructions
+- a locked methodology
+- fork/runtime assumptions
+- provider adapter notes
+- visual production templates
+- examples
+- output standards
+- contributor metadata
+
+The intended operator is an AI visual content operator, cinematic prompt strategist, or browser-assisted creative producer working against a local fork, browser-hosted surface, or desktop app workflow.
+
+---
+
+## Folder structure
+
+```text
+growthub-open-higgsfield-studio-v1/
+├── kit.json
+├── bundles/
+├── workers/
+├── brands/
+├── templates/
+├── examples/
+├── docs/
+├── growthub-meta/
+├── skills.md
+├── output-standards.md
+├── runtime-assumptions.md
+└── validation-checklist.md
+```
+
+---
+
+## Activation
+
+1. Export the kit.
+2. Point the agent working directory at the expanded folder.
+3. The agent reads `workers/open-higgsfield-studio-operator/CLAUDE.md`.
+4. `skills.md` provides the working method for every session.
+
+---
+
+## Supported output categories
+
+- visual campaign brief
+- studio selection brief
+- shot plan
+- prompt matrix
+- generation batch plan
+- model selection recommendation
+- asset reuse/reference plan
+- review notes
+- platform-ready execution handoff