@growthub/cli 0.3.39 → 0.3.41

package/README.md

@@ -16,67 +16,127 @@ Later:
 npx create-growthub-local --profile gtm
 ```
 
-## Worker Kits V1
+## Worker Kits
 
-The CLI ships a bundled Worker Kit export surface for local adapter environments.
-These kits are not server installs or database records. They are frozen, working-directory-ready
-artifacts that local adapters can run inside directly.
+Worker kits are frozen, working-directory-ready execution environments for local AI agents.
+Each kit bundles prompts, templates, output standards, brand guides, setup scripts, and a
+`CLAUDE.md` operator contract — everything an agent needs to run a vertical workflow immediately.
 
-They should be understood as packaged execution environments. A kit can carry prompts, templates, examples, output standards, and local runtime assumptions together as one reusable environment.
+### Discovery
 
 ```bash
+# Interactive browser — family filter → searchable selector → preview → download
+growthub kit
+
+# All kits grouped by family with descriptions and inline download commands
 growthub kit list
+
+# Filter by family (studio · workflow · operator · ops)
+growthub kit list --family studio
+growthub kit list --family studio,operator
+
+# Machine-readable output for scripting / agent use
+growthub kit list --json
+
+# Official family taxonomy — taglines, surfaces, and examples
+growthub kit families
+```
+
+### Download
+
+```bash
+# Interactive (picker if no kit-id given)
+growthub kit download
+
+# Fuzzy slug — partial IDs resolve automatically
+growthub kit download higgsfield           # → growthub-open-higgsfield-studio-v1
+growthub kit download email                # → growthub-email-marketing-v1
+growthub kit download studio-v1            # → growthub-open-higgsfield-studio-v1
+
+# Full ID
+growthub kit download growthub-open-higgsfield-studio-v1
+
+# Custom output directory
+growthub kit download higgsfield --out ~/my-kits
+
+# Skip confirmation prompt (scripting / agent use)
+growthub kit download higgsfield --yes
+```
+
+### Inspect & validate
+
+```bash
+# Pretty manifest output with family badge and required paths
+growthub kit inspect higgsfield-studio-v1
 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
+
+# Raw JSON for scripting
+growthub kit inspect growthub-email-marketing-v1 --json
+
+# Resolve export folder path without exporting
 growthub kit path creative-strategist-v1
+
+# Validate a kit directory against the schema
 growthub kit validate /absolute/path/to/kit
+growthub kit validate ~/kits/growthub-open-higgsfield-studio-v1
 ```
 
-V1 is intentionally narrow:
+```bash
+# Full ID download examples
+growthub kit download creative-strategist-v1
+growthub kit download growthub-open-higgsfield-studio-v1
+```
 
-- bundled catalog plus local export only
-- downloadable worker kits for creative strategy, email strategy, and Open Higgsfield AI visual production
-- deterministic zip plus expanded export folder
-- public example brand kits only
-- no heartbeat wiring, app install flow, server registry, plugin lifecycle, or database kit records
+### After download
 
-### How local adapters use worker kits
+```
+1. Point Growthub local Working Directory at the exported folder
+   (or Claude Code Working Directory as an alternative)
+2. cp .env.example .env  →  add your API key
+3. bash setup/clone-fork.sh  →  boot local fork (studio kits only)
+4. Open a new session — the operator agent loads automatically from CLAUDE.md
+```
 
-Local adapters such as Claude, Codex, Cursor, Gemini, and OpenCode execute inside the agent
-`Working directory` path.
+### Kit families
 
-Growthub worker kits are designed to plug into that path directly:
+| Family | Description | Default surface |
+|---|---|---|
+| 🎬 **studio** | AI generation studio backed by a local fork | local-fork |
+| 🔄 **workflow** | Multi-step pipeline operator across tools or APIs | browser-hosted |
+| 🤖 **operator** | Domain vertical specialist — structured deliverables | browser-hosted |
+| ⚙️ **ops** | Infrastructure / toolchain operator | local-fork |
 
-1. Export a kit with `growthub kit download <kit-id>` or resolve its folder with `growthub kit path <kit-id>`.
-2. Take the expanded folder on disk.
-3. Put that absolute path into the agent's `Working directory` field.
-4. Run the local adapter against that exported environment.
+### Available kits
 
-This is the current integration surface for worker kits in Growthub. In other words, the worker kit
-becomes a specialized local execution environment that an agent can access and work within through
-its configured working directory.
+| Kit | Family | Description |
+|---|---|---|
+| `growthub-open-higgsfield-studio-v1` | studio | Open Higgsfield AI visual production (image, video, lip sync, cinema) |
+| `growthub-email-marketing-v1` | operator | Brand-aware email campaigns, nurture sequences, and content pillar plans |
+| `creative-strategist-v1` | workflow | Video creative briefs and campaign strategy |
 
-### Environment expansion model
+### How local adapters use worker kits
 
-The packaging model supports more than a single strategy kit.
+Local adapters (Claude Code, Codex, Cursor, Gemini, OpenCode) execute inside the agent
+`Working directory` path. Worker kits are designed to plug into that path directly:
 
-The same packaging model can support:
+1. `growthub kit download <id>` — exports the kit as a folder + zip
+2. Point the agent `Working directory` at the exported folder path
+3. The agent reads `CLAUDE.md` on session start and runs the operator workflow automatically
 
-- strategy environments
-- email marketing environments
-- browser-heavy GTM environments
-- local production environments such as motion or Remotion-based workflows
+### Adding new kits
 
-That means a new environment should usually be added as:
+Each new kit should be:
 
-1. a self-contained kit folder
-2. a manifest and bundle contract
-3. registered catalog metadata
-4. a real local adapter validation pass through `Working directory`
+1. A self-contained kit folder in `cli/assets/worker-kits/`
+2. A `kit.json` manifest (schema v2) with `family`, `frozenAssetPaths`, and `outputStandard`
+3. A bundle manifest in `bundles/`
+4. A catalog entry in `cli/src/kits/catalog.ts`
+5. Validated with `growthub kit validate ./path/to/kit`
 
-not as a new one-off CLI code path.
+The kit family factory layer (`cli/src/kits/core/factory/`) provides typed `createStudioKitConfig()`,
+`createWorkflowKitConfig()`, `createOperatorKitConfig()`, and `createOpsKitConfig()` builders that
+assemble a fully validated `ForkAdapterCoreConfig` from a small set of options.
 
 ## What this is
 

package/assets/worker-kits/creative-strategist-v1/kit.json

@@ -7,7 +7,8 @@
     "description": "Frozen Creative Strategist worker kit for exporting a working-directory-ready video creative brief worker.",
     "type": "worker",
     "visibility": "public-open-source",
-    "sourceRepo": "claude-workers"
+    "sourceRepo": "claude-workers",
+    "family": "workflow"
   },
   "entrypoint": {
     "workerId": "creative-strategist",
@@ -71,7 +72,9 @@
     }
   ],
   "executionMode": "export",
-  "activationModes": ["export"],
+  "activationModes": [
+    "export"
+  ],
   "compatibility": {
     "cliMinVersion": "0.3.35"
   },

package/assets/worker-kits/growthub-email-marketing-v1/kit.json

@@ -7,7 +7,8 @@
     "description": "Self-contained local execution environment for Growthub-focused email marketing. Produces brand-aware email campaigns, nurture sequences, broadcasts, and content-pillar-driven campaign plans with pluggable email platform integration.",
     "type": "worker",
     "visibility": "public-open-source",
-    "sourceRepo": "growthub-local"
+    "sourceRepo": "growthub-local",
+    "family": "operator"
   },
   "entrypoint": {
     "workerId": "email-marketing-strategist",
@@ -90,7 +91,9 @@
     }
   ],
   "executionMode": "export",
-  "activationModes": ["export"],
+  "activationModes": [
+    "export"
+  ],
   "compatibility": {
     "cliMinVersion": "0.3.37"
   },

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

@@ -50,7 +50,17 @@ Checks for `node`, `npm`, `git`, and `ffmpeg`. All four are required for local-f
 bash setup/clone-fork.sh
 ```
 
-Clones the Open Higgsfield AI repo to `~/open-higgsfield-ai`, installs dependencies, and starts the dev server at `http://localhost:3001`. Skip this if you are using browser-hosted or desktop-app mode.
+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.
 
 ---
 

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

@@ -7,7 +7,8 @@
     "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"
+    "sourceRepo": "growthub-local",
+    "family": "studio"
   },
   "entrypoint": {
     "workerId": "open-higgsfield-studio-operator",
@@ -33,6 +34,7 @@
     "brands/growthub/brand-kit.md",
     "brands/NEW-CLIENT.md",
     "setup/clone-fork.sh",
+    "setup/patch-cors-proxy.sh",
     "setup/verify-env.mjs",
     "setup/check-deps.sh",
     "output/README.md",
@@ -79,6 +81,7 @@
       "brands/growthub/brand-kit.md",
       "brands/NEW-CLIENT.md",
       "setup/clone-fork.sh",
+      "setup/patch-cors-proxy.sh",
       "setup/verify-env.mjs",
       "setup/check-deps.sh",
       "output/README.md",
@@ -95,7 +98,9 @@
     }
   ],
   "executionMode": "export",
-  "activationModes": ["export"],
+  "activationModes": [
+    "export"
+  ],
   "compatibility": {
     "cliMinVersion": "0.3.37"
   },

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

@@ -34,6 +34,43 @@ If the local fork differs, the fork wins.
 
 ---
 
+## KNOWN FORK ISSUE — CORS POLICY (local-fork mode)
+
+**Status:** Fixed. Patch is applied automatically by `setup/clone-fork.sh`.
+
+**Root cause:** The upstream repo hardcodes `const BASE_URL = 'https://api.muapi.ai'` in
+`packages/studio/src/muapi.js`. All browser fetch/XHR calls go directly to the external
+API. `api.muapi.ai` does not return `Access-Control-Allow-Origin` headers, so every call
+from `localhost:3001` is blocked by the browser's CORS policy.
+
+**Errors you will see without the patch:**
+```
+Access to fetch at 'https://api.muapi.ai/api/v1/account/balance'
+from origin 'http://localhost:3001' has been blocked by CORS policy:
+No 'Access-Control-Allow-Origin' header is present on the requested resource.
+```
+
+**The fix:**
+1. `next.config.mjs` — rewrites `/muapi-proxy/:path*` → `https://api.muapi.ai/:path*` server-side
+2. `packages/studio/src/muapi.js` — `BASE_URL` changed to `'/muapi-proxy'`
+
+All browser calls now hit `localhost:3001/muapi-proxy/...` (same origin, no CORS).
+Next.js proxies them to `api.muapi.ai` from the server where CORS does not apply.
+
+**To apply manually if not already patched:**
+```bash
+bash setup/patch-cors-proxy.sh [path-to-fork]
+# defaults to ~/open-higgsfield-ai
+```
+
+**Affected functions in muapi.js:**
+- `getUserBalance` — `/api/v1/account/balance`
+- `submitAndPoll` — `/api/v1/${endpoint}`
+- `pollForResult` — `/api/v1/predictions/${requestId}/result`
+- `uploadFile` (XHR) — `/api/v1/upload_file`
+
+---
+
 ## EXECUTION SURFACES
 
 ### Local fork

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

@@ -20,6 +20,19 @@ cd "$FORK_DIR"
 echo "Installing dependencies..."
 npm install
 
+echo ""
+echo "Applying CORS proxy patch..."
+# The upstream repo calls api.muapi.ai directly from the browser, which is blocked
+# by CORS policy. This patch routes all API calls through the Next.js server.
+# See setup/patch-cors-proxy.sh for full explanation.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "$SCRIPT_DIR/patch-cors-proxy.sh" ]; then
+  bash "$SCRIPT_DIR/patch-cors-proxy.sh" "$FORK_DIR"
+else
+  echo "WARNING: patch-cors-proxy.sh not found — skipping CORS patch."
+  echo "You may hit CORS errors when the studio calls api.muapi.ai from the browser."
+fi
+
 echo ""
 echo "Starting dev server on http://localhost:$PORT"
 echo "Press Ctrl+C to stop."

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/setup/patch-cors-proxy.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# patch-cors-proxy.sh — Apply Next.js CORS proxy patch to the Open Higgsfield AI local fork
+#
+# WHY THIS EXISTS
+# ---------------
+# The upstream repo calls api.muapi.ai directly from the browser (BASE_URL in muapi.js).
+# api.muapi.ai does not return Access-Control-Allow-Origin headers, so every browser
+# request from localhost:3001 is blocked by CORS policy.
+#
+# THE FIX
+# -------
+# 1. next.config.mjs — adds a rewrites() block:
+#      /muapi-proxy/:path* → https://api.muapi.ai/:path*   (server-side, no CORS)
+#
+# 2. packages/studio/src/muapi.js — changes BASE_URL:
+#      'https://api.muapi.ai'  →  '/muapi-proxy'
+#
+# All fetch/XHR calls now hit the local Next.js server which proxies them server-side.
+# No browser cross-origin request is made. CORS policy never fires.
+#
+# USAGE
+# -----
+#   bash setup/patch-cors-proxy.sh [path-to-fork]
+#
+# Defaults to ~/open-higgsfield-ai if no path given.
+# Safe to run multiple times — idempotent.
+
+set -e
+
+FORK_DIR="${1:-$HOME/open-higgsfield-ai}"
+NEXT_CONFIG="$FORK_DIR/next.config.mjs"
+MUAPI_JS="$FORK_DIR/packages/studio/src/muapi.js"
+
+echo ""
+echo "=== CORS Proxy Patch ==="
+echo "Fork: $FORK_DIR"
+echo ""
+
+# ── Guard: fork must exist ──────────────────────────────────────────────────
+if [ ! -d "$FORK_DIR" ]; then
+  echo "ERROR: Fork not found at $FORK_DIR"
+  echo "Run setup/clone-fork.sh first."
+  exit 1
+fi
+
+if [ ! -f "$NEXT_CONFIG" ]; then
+  echo "ERROR: next.config.mjs not found at $NEXT_CONFIG"
+  exit 1
+fi
+
+if [ ! -f "$MUAPI_JS" ]; then
+  echo "ERROR: muapi.js not found at $MUAPI_JS"
+  exit 1
+fi
+
+# ── Idempotency check ───────────────────────────────────────────────────────
+if grep -q "muapi-proxy" "$NEXT_CONFIG" 2>/dev/null; then
+  echo "✓ next.config.mjs already patched — skipping."
+  NEXT_DONE=1
+else
+  NEXT_DONE=0
+fi
+
+if grep -q "muapi-proxy" "$MUAPI_JS" 2>/dev/null; then
+  echo "✓ muapi.js already patched — skipping."
+  MUAPI_DONE=1
+else
+  MUAPI_DONE=0
+fi
+
+if [ "$NEXT_DONE" -eq 1 ] && [ "$MUAPI_DONE" -eq 1 ]; then
+  echo ""
+  echo "Both files already patched. Nothing to do."
+  exit 0
+fi
+
+# ── Backup originals ────────────────────────────────────────────────────────
+if [ "$NEXT_DONE" -eq 0 ]; then
+  cp "$NEXT_CONFIG" "$NEXT_CONFIG.orig"
+fi
+if [ "$MUAPI_DONE" -eq 0 ]; then
+  cp "$MUAPI_JS" "$MUAPI_JS.orig"
+fi
+
+# ── Patch next.config.mjs ───────────────────────────────────────────────────
+if [ "$NEXT_DONE" -eq 0 ]; then
+  cat > "$NEXT_CONFIG" << 'NEXTEOF'
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ['studio'],
+
+  // CORS proxy — forward all Muapi API calls through the Next.js server so
+  // the browser never makes cross-origin requests to api.muapi.ai directly.
+  // muapi.js uses BASE_URL = '/muapi-proxy', so every fetch/XHR hits
+  // /muapi-proxy/api/v1/... which Next.js rewrites to api.muapi.ai server-side.
+  async rewrites() {
+    return [
+      {
+        source: '/muapi-proxy/:path*',
+        destination: 'https://api.muapi.ai/:path*',
+      },
+    ];
+  },
+};
+
+export default nextConfig;
+NEXTEOF
+  echo "✓ next.config.mjs patched — added /muapi-proxy rewrites()"
+fi
+
+# ── Patch muapi.js ──────────────────────────────────────────────────────────
+if [ "$MUAPI_DONE" -eq 0 ]; then
+  # Replace the BASE_URL line only (targeted sed, not full file rewrite)
+  sed -i.bak \
+    "s|const BASE_URL = 'https://api.muapi.ai';|// Proxy through Next.js to avoid CORS. All calls route through /muapi-proxy/:path*\n// which next.config.mjs rewrites to api.muapi.ai server-side — no CORS headers needed.\nconst BASE_URL = '/muapi-proxy';|" \
+    "$MUAPI_JS"
+  # Remove sed backup (we already made our own)
+  rm -f "$MUAPI_JS.bak"
+  echo "✓ muapi.js patched — BASE_URL changed to '/muapi-proxy'"
+fi
+
+# ── Verify ───────────────────────────────────────────────────────────────────
+echo ""
+echo "Verifying patch..."
+
+if grep -q "muapi-proxy" "$NEXT_CONFIG" && grep -q "muapi-proxy" "$MUAPI_JS"; then
+  echo "✓ Patch verified. Both files updated correctly."
+else
+  echo "ERROR: Patch verification failed. Check the files manually."
+  echo "  $NEXT_CONFIG"
+  echo "  $MUAPI_JS"
+  exit 1
+fi
+
+echo ""
+echo "CORS proxy patch complete."
+echo "Restart the dev server to pick up next.config.mjs changes:"
+echo "  npm run dev -- --port 3001"
+echo ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growthub/cli",
-  "version": "0.3.39",
+  "version": "0.3.41",
   "description": "Growthub CLI — orchestrate AI agent teams to run a business",
   "type": "module",
   "bin": {