@growthub/cli 0.3.37 → 0.3.39

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

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

@@ -0,0 +1,47 @@
+# Kit Standard — Open Higgsfield Studio v1
+
+This document defines the locked contract for this kit.
+
+---
+
+## Required files contract
+
+Every path in `kit.json -> frozenAssetPaths` must exist in every valid release.
+
+---
+
+## Bundle contract
+
+The bundle manifest must remain aligned with `kit.json`:
+- `bundle.kitId` matches `kit.id`
+- `bundle.workerId` matches `entrypoint.workerId`
+- `requiredFrozenAssets` stays a subset of `frozenAssetPaths`
+
+---
+
+## Agent operating rules
+
+The entrypoint file is the operating law. `skills.md` is the methodology.
+
+Required invariants:
+- strict workflow order
+- repo inspection before planning when a fork exists
+- one primary studio selection
+- model recommendation with fallback
+- explicit provider adapter assumptions
+- operational output artifacts, not ideation-only text
+
+---
+
+## Runtime rules
+
+- no secrets stored in kit files
+- Muapi is the reference adapter, not a permanent monopoly
+- browser, desktop, and local-fork modes are all first-class
+- outputs are Markdown only
+
+---
+
+## Versioning rules
+
+Additive template/docs changes are minor-version work. Entry-point path changes or export-name changes require a major version bump.

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

@@ -0,0 +1,106 @@
+{
+  "schemaVersion": 2,
+  "kit": {
+    "id": "growthub-open-higgsfield-studio-v1",
+    "version": "1.0.0",
+    "name": "Growthub Agent Worker Kit — Open Higgsfield Studio",
+    "description": "Self-contained local execution environment for Open Higgsfield AI visual production. Produces implementation-ready visual briefs, prompt systems, shot plans, generation batches, model selections, and execution handoff artifacts for browser, desktop, and local fork workflows.",
+    "type": "worker",
+    "visibility": "public-open-source",
+    "sourceRepo": "growthub-local"
+  },
+  "entrypoint": {
+    "workerId": "open-higgsfield-studio-operator",
+    "path": "workers/open-higgsfield-studio-operator/CLAUDE.md"
+  },
+  "workerIds": [
+    "open-higgsfield-studio-operator"
+  ],
+  "agentContractPath": "workers/open-higgsfield-studio-operator/CLAUDE.md",
+  "brandTemplatePath": "brands/_template/brand-kit.md",
+  "publicExampleBrandPaths": [
+    "brands/growthub/brand-kit.md"
+  ],
+  "frozenAssetPaths": [
+    "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"
+  ],
+  "setupPaths": {
+    "quickstart": "QUICKSTART.md",
+    "envExample": ".env.example",
+    "setupDir": "setup/",
+    "outputDir": "output/"
+  },
+  "outputStandard": {
+    "type": "working-directory",
+    "description": "Exported folder is intended to be pointed at directly by the agent Working Directory. All outputs are Markdown files written to output/<client-slug>/<project-slug>/.",
+    "requiredPaths": [
+      "QUICKSTART.md",
+      ".env.example",
+      "kit.json",
+      "bundles/growthub-open-higgsfield-studio-v1.json",
+      "skills.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",
+      "docs",
+      "growthub-meta"
+    ]
+  },
+  "bundles": [
+    {
+      "id": "growthub-open-higgsfield-studio-v1",
+      "version": "1.0.0",
+      "path": "bundles/growthub-open-higgsfield-studio-v1.json"
+    }
+  ],
+  "executionMode": "export",
+  "activationModes": ["export"],
+  "compatibility": {
+    "cliMinVersion": "0.3.37"
+  },
+  "provenance": {
+    "sourceRepo": "growthub-local",
+    "frozenAt": "2026-04-10T00:00:00.000Z"
+  }
+}

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

@@ -0,0 +1,34 @@
+# Output Directory
+
+All agent-generated deliverables are written here, organized by client and project.
+
+## Structure
+
+```
+output/
+  <client-slug>/
+    <project-slug>/
+      visual-campaign-brief.md
+      studio-selection-brief.md
+      model-selection-recommendation.md
+      shot-plan.md
+      prompt-matrix.md
+      generation-batch-plan.md
+      asset-tracking.md
+      review-qa-checklist.md
+      platform-ready-execution-handoff.md
+```
+
+## Usage
+
+The agent creates this structure automatically when it writes its first deliverable. You do not need to create folders manually.
+
+Use the `<client-slug>` to match your brand kit name (e.g. `growthub`, `acme-corp`) and the `<project-slug>` to identify the campaign or shoot (e.g. `q2-product-launch`, `founder-brand-video`).
+
+## Tracking deliverables
+
+Each completed package is logged in the active brand kit under `Deliverable History`:
+
+```
+- 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/output-standards.md

@@ -0,0 +1,133 @@
+# Output Standards — Open Higgsfield Studio v1
+
+This document defines the output contract for every artifact produced by this kit.
+
+---
+
+## OUTPUT FOLDER STRUCTURE
+
+```text
+output/
+└── <client-slug>/
+    └── <project-slug>/
+        ├── <ClientSlug>_VisualCampaignBrief_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_StudioSelectionBrief_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_ModelSelectionRecommendation_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_ShotPlan_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_PromptMatrix_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_GenerationBatchPlan_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_AssetTracking_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_ReviewQAChecklist_v<N>_<YYYYMMDD>.md
+        └── <ClientSlug>_PlatformReadyExecutionHandoff_v<N>_<YYYYMMDD>.md
+```
+
+---
+
+## REQUIRED OUTPUT TYPES
+
+Every full package must include:
+- visual campaign brief
+- studio selection brief
+- model selection recommendation
+- shot plan
+- prompt matrix
+- generation batch plan
+- asset tracking
+- review QA checklist
+- platform-ready execution handoff
+
+---
+
+## REQUIRED SECTIONS
+
+### Visual campaign brief
+1. Goal and deliverable
+2. Audience and platform context
+3. Brand and visual rules
+4. Content objective to visual strategy translation
+5. Asset inventory
+6. Studio hypothesis
+7. Output package summary
+
+### Studio selection brief
+1. Requested outcome
+2. Recommended studio
+3. Why this studio fits
+4. Input requirements
+5. Risks and fallback studio
+
+### Model selection recommendation
+1. Primary model table
+2. Fallback model table
+3. Endpoint and control assumptions
+4. Constraint notes
+
+### Shot plan
+1. Shot table
+2. Narrative arc notes
+3. Asset dependencies
+4. Review gates
+
+### Prompt matrix
+1. Prompt set metadata
+2. One row per output or shot
+3. Base prompt
+4. Variation prompt
+5. Negative / exclusion language
+6. Control settings
+
+### Generation batch plan
+1. Batch sequence table
+2. Submit order
+3. Polling / review cadence
+4. Retry rules
+
+### Asset tracking
+1. Asset inventory table
+2. Reuse status
+3. Upload status
+4. Ownership / notes
+
+### Review QA checklist
+1. Creative review
+2. Technical review
+3. Studio-specific review
+4. Handoff sign-off
+
+### Platform-ready execution handoff
+1. Runtime mode
+2. Repo inspection summary
+3. Provider adapter assumptions
+4. Exact execution steps
+5. Expected outputs
+6. Open questions
+
+---
+
+## FILE NAMING RULES
+
+Pattern:
+
+```text
+<ClientSlug>_<OutputType>_v<N>_<YYYYMMDD>.md
+```
+
+Rules:
+- `ClientSlug` is PascalCase
+- never overwrite an existing version
+- keep one artifact per file
+- Markdown only
+
+---
+
+## QUALITY BAR
+
+An output is complete when:
+- no placeholder text remains
+- the primary studio is explicit
+- the model recommendation includes a fallback
+- prompts are paste-ready
+- every shot has a defined asset path or asset request
+- batch sequencing reflects async submit/poll execution
+- browser / desktop / local-fork mode is named
+- review checklist is filled, not empty

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

@@ -0,0 +1,108 @@
+# Runtime Assumptions — Open Higgsfield Studio v1
+
+This document defines the runtime boundary for this kit.
+
+---
+
+## OVERVIEW
+
+This kit targets a self-contained local working directory used by an agent operating against one of three execution surfaces:
+
+| Mode | When to use | Assumption |
+|---|---|---|
+| `local-fork` | local checkout of Open Higgsfield AI is available | repo files can be inspected before planning |
+| `browser-hosted` | operator uses the hosted browser app | studio behavior follows the public hosted workflow |
+| `desktop-app` | operator uses the Electron app | same shared studio substrate, local desktop packaging |
+
+Default planning mode is `local-fork` when a checkout exists. Otherwise use `browser-hosted`.
+
+---
+
+## OPEN HIGGSFIELD AI ASSUMPTIONS
+
+Frozen upstream assumptions for this kit:
+- repo exposes four studios: image, video, lip sync, cinema
+- browser and desktop workflows both exist
+- `packages/studio/src/models.js` is the model source of truth
+- Muapi is the reference provider engine
+- API auth uses `x-api-key`
+- request flow is submit -> poll -> result
+- uploads are first-class for image-conditioned and audio-conditioned workflows
+- generation history and upload history matter to repeatability
+
+If the local fork differs, the fork wins.
+
+---
+
+## EXECUTION SURFACES
+
+### Local fork
+
+Expected operator flow:
+1. inspect `README.md`
+2. inspect `packages/studio/src/models.js`
+3. inspect `packages/studio/src/muapi.js`
+4. inspect relevant studio component
+5. prepare prompts, assets, and batch order
+6. execute through the local app surface the fork provides
+
+### Browser-hosted
+
+Expected operator flow:
+1. open hosted app
+2. load or enter API key
+3. select studio
+4. upload or reuse assets
+5. submit prompts in planned order
+6. poll and review results
+7. save result links and notes into output docs
+
+### Desktop app
+
+Expected operator flow:
+1. launch Electron app
+2. confirm API key availability
+3. select studio
+4. reuse locally stored asset history when possible
+5. run generation batches
+6. collect outputs and review notes
+
+---
+
+## LOCAL STATE ASSUMPTIONS
+
+The upstream repo describes persistent local state for:
+- API key storage
+- upload history
+- generation history
+- lip sync pending-job recovery
+
+The agent should treat these as workflow assets:
+- prefer reuse before re-upload
+- document when history should be checked
+- avoid assuming server-side persistence beyond the provider result URL
+
+---
+
+## FRAME ANALYSIS PRIMITIVE
+
+When a local reference video exists, frame extraction can be used for shot planning:
+
+```bash
+mkdir -p /tmp/open_higgsfield_frames
+ffmpeg -i "/path/to/reference.mp4" -vf fps=1/2 /tmp/open_higgsfield_frames/frame_%04d.jpg
+```
+
+Use this only when a local file is available. Do not promise it from a remote social URL alone.
+
+---
+
+## OUTPUT WRITING ASSUMPTION
+
+All deliverables are written as Markdown in:
+
+```text
+output/<client-slug>/<project-slug>/
+```
+
+The kit does not require its own npm install or custom CLI to be operational.