@growthub/cli 0.3.38 → 0.3.39

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.

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/setup/check-deps.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# check-deps.sh — Verify local dependencies required for local-fork and frame-analysis workflows.
+# Run before your first local-fork session.
+set -e
+
+PASS=0
+FAIL=0
+
+check() {
+  local name="$1"
+  local cmd="$2"
+  local install_hint="$3"
+  if command -v "$cmd" >/dev/null 2>&1; then
+    echo "OK   $name ($(command -v "$cmd"))"
+    PASS=$((PASS + 1))
+  else
+    echo "MISSING  $name — $install_hint"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "=== Growthub Open Higgsfield — Dependency Check ==="
+echo ""
+check "git"    "git"    "https://git-scm.com/downloads"
+check "node"   "node"   "https://nodejs.org"
+check "npm"    "npm"    "Comes with Node.js"
+check "ffmpeg" "ffmpeg" "brew install ffmpeg  OR  https://ffmpeg.org/download.html"
+echo ""
+echo "Passed: $PASS  |  Missing: $FAIL"
+
+if [ "$FAIL" -gt 0 ]; then
+  echo ""
+  echo "Install missing tools before running local-fork or frame-analysis workflows."
+  exit 1
+fi
+
+echo "All dependencies present. You are ready for local-fork execution."

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/setup/clone-fork.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# clone-fork.sh — Clone and boot the Open Higgsfield AI local fork
+# Run from any location. Installs to ~/open-higgsfield-ai and starts dev server on port 3001.
+set -e
+
+FORK_DIR="$HOME/open-higgsfield-ai"
+REPO_URL="https://github.com/Anil-matcha/Open-Higgsfield-AI"
+PORT=3001
+
+if [ -d "$FORK_DIR" ]; then
+  echo "Fork already exists at $FORK_DIR — skipping clone."
+  echo "To re-clone, remove the directory first: rm -rf $FORK_DIR"
+else
+  echo "Cloning Open Higgsfield AI → $FORK_DIR"
+  git clone "$REPO_URL" "$FORK_DIR"
+fi
+
+cd "$FORK_DIR"
+
+echo "Installing dependencies..."
+npm install
+
+echo ""
+echo "Starting dev server on http://localhost:$PORT"
+echo "Press Ctrl+C to stop."
+echo ""
+npm run dev -- --port "$PORT"

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/setup/verify-env.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// verify-env.mjs — Validate MUAPI_API_KEY from .env before starting a generation session.
+// Usage: node setup/verify-env.mjs
+// Exit 0 = key is valid and reachable. Exit 1 = key missing, invalid, or API unreachable.
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const envPath = resolve(process.cwd(), ".env");
+
+function parseEnvFile(filePath) {
+  const vars = {};
+  const lines = readFileSync(filePath, "utf8").split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex === -1) continue;
+    const key = trimmed.slice(0, eqIndex).trim();
+    const value = trimmed.slice(eqIndex + 1).trim();
+    vars[key] = value;
+  }
+  return vars;
+}
+
+async function main() {
+  if (!existsSync(envPath)) {
+    console.error("ERROR: .env file not found.");
+    console.error("Run: cp .env.example .env  then add your MUAPI_API_KEY.");
+    process.exit(1);
+  }
+
+  const env = parseEnvFile(envPath);
+  const apiKey = env["MUAPI_API_KEY"];
+  const baseUrl = env["MUAPI_BASE_URL"] ?? "https://api.muapi.io";
+
+  if (!apiKey || apiKey === "your_muapi_key_here" || apiKey.trim() === "") {
+    console.error("ERROR: MUAPI_API_KEY is not set in .env.");
+    console.error("Get your key at https://muapi.ai/dashboard");
+    process.exit(1);
+  }
+
+  console.log(`Verifying key against ${baseUrl} ...`);
+
+  let res;
+  try {
+    res = await fetch(`${baseUrl}/v1/models`, {
+      method: "GET",
+      headers: { "x-api-key": apiKey },
+    });
+  } catch (err) {
+    console.error(`ERROR: Could not reach ${baseUrl}.`);
+    console.error(err.message);
+    process.exit(1);
+  }
+
+  if (res.status === 401 || res.status === 403) {
+    console.error(`ERROR: API key rejected (HTTP ${res.status}).`);
+    console.error("Check your MUAPI_API_KEY value at https://muapi.ai/dashboard");
+    process.exit(1);
+  }
+
+  if (!res.ok) {
+    console.error(`ERROR: Unexpected response from Muapi API (HTTP ${res.status}).`);
+    process.exit(1);
+  }
+
+  console.log("OK: MUAPI_API_KEY is valid and the API is reachable.");
+  process.exit(0);
+}
+
+main();