@growthub/cli 0.3.41 → 0.3.43

package/README.md

@@ -1,287 +1,154 @@
-# growthub-core — Agent Swarm Command Center
+# @growthub/cli
 
-> Growthub is a full-featured DX platform for orchestrating AI agent swarms across sequential ticket pipelines.
+`@growthub/cli` is the published CLI for Growthub Local. It covers three shipped workflows:
 
----
+- full local app discovery and onboarding
+- worker kit discovery, export, inspection, and validation
+- shared template discovery and extraction
 
 ## Install
 
 ```bash
-npx create-growthub-local --profile dx
+npm install -g @growthub/cli
+```
+
+You can also install through the guided installer:
+
+```bash
+npx create-growthub-local
 ```
 
-Later:
+Or jump directly to a profile:
 
 ```bash
 npx create-growthub-local --profile gtm
+npx create-growthub-local --profile dx
 ```
 
-## Worker Kits
+## CLI Editions
 
-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.
+The current CLI exposes three user-facing editions through `growthub discover` and direct subcommands.
 
-### Discovery
+### 1. Full Local App
+
+Use this when you want to create or reopen a full Growthub local surface.
 
 ```bash
-# Interactive browser — family filter → searchable selector → preview → download
-growthub kit
+growthub
+growthub discover
+growthub onboard
+growthub run
+```
 
-# All kits grouped by family with descriptions and inline download commands
-growthub kit list
+User flow:
 
-# Filter by family (studio · workflow · operator · ops)
-growthub kit list --family studio
-growthub kit list --family studio,operator
+1. Open the discovery hub.
+2. Choose `Full Local App`.
+3. Create a new `gtm` or `dx` profile, or load an existing local profile.
+4. Complete onboarding.
+5. Start the local server and finish the hosted authentication bridge.
 
-# Machine-readable output for scripting / agent use
-growthub kit list --json
+### 2. Worker Kits
 
-# Official family taxonomy — taglines, surfaces, and examples
-growthub kit families
-```
+Use this when you want a working-directory-ready environment for an agent.
 
-### Download
+### Discovery
 
 ```bash
-# Interactive (picker if no kit-id given)
-growthub kit download
+# Interactive browser — type filter → kit selector → actions
+growthub kit
 
-# 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
+# All kits grouped by family with descriptions and inline commands
+growthub kit list
 
-# Full ID
-growthub kit download growthub-open-higgsfield-studio-v1
+# Filter by family
+growthub kit list --family studio
+growthub kit list --family studio,operator
 
-# Custom output directory
-growthub kit download higgsfield --out ~/my-kits
+# Machine-readable output
+growthub kit list --json
 
-# Skip confirmation prompt (scripting / agent use)
-growthub kit download higgsfield --yes
+# Family taxonomy
+growthub kit families
 ```
 
-### Inspect & validate
+### Inspect, download, and 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
-
-# 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
-```
-
-```bash
-# Full ID download examples
 growthub kit download creative-strategist-v1
 growthub kit download growthub-open-higgsfield-studio-v1
-```
-
-### After download
+growthub kit download higgsfield --yes
 
-```
-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
+growthub kit path creative-strategist-v1
+growthub kit validate /absolute/path/to/kit
 ```
 
-### Kit families
+### After download
 
-| 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. Point Growthub local or your local adapter `Working directory` at the exported folder.
+2. Add runtime-only environment variables required by the kit.
+3. Start a new session so the operator contract loads from `CLAUDE.md`.
 
-### Available kits
+### Available bundled kits
 
 | 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 |
+| `growthub-email-marketing-v1` | operator | Brand-aware email campaigns, sequences, and campaign planning |
+| `growthub-open-higgsfield-studio-v1` | studio | Open Higgsfield visual production workflows |
 
 ### How local adapters use worker kits
 
-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:
-
-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
-
-### Adding new kits
-
-Each new kit should be:
-
-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`
-
-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
-
-**growthub-core** is an opinionated, self-hosted developer experience platform that treats every unit of work as a **Ticket** — a sequential pipeline of stages (planning → execution → review → qa → human) — where each stage is owned by a specific AI agent. Designed for **parallel multi-ticket execution** with real-time agent status, live heartbeat tracking, and full pipeline control from a single command center dashboard.
-
----
-
-## Architecture
-
-```
-┌──────────────────────────────────────────────────────────┐
-│                    growthub-core                         │
-│                                                          │
-│  ┌───────────────────────────────────────────────────┐   │
-│  │  Ticket Command Center (Dashboard)                │   │
-│  │  Kanban │ List │ Roadmap (Week / Month)           │   │
-│  └───────────────────────────────────────────────────┘   │
-│                         │                                │
-│               ┌──────────┴─────────┐                     │
-│               │   Ticket TKT-N     │                     │
-│               │  stageOrder[]      │                     │
-│               │  currentStage      │                     │
-│               └──────────┬─────────┘                     │
-│                          │                               │
-│       ┌──────────────────┼──────────────────┐           │
-│       │                  │                  │           │
-│   Planning           Execution         Review / QA       │
-│   Agent              Codex /           Claude /          │
-│   (pm role)          Claude Code       Codex             │
-│                          │                               │
-│             Issues (GRO-NNN) per stage                   │
-│             assigned to specific agents                  │
-│                                                          │
-│  ┌───────────────────────────────────────────────────┐   │
-│  │  Embedded PostgreSQL (port 54329)                 │   │
-│  │  Drizzle ORM — auto-migration on startup          │   │
-│  │  TanStack Query + queryKeys registry              │   │
-│  │  Vite dev middleware + tsx watch hot-reload        │   │
-│  └───────────────────────────────────────────────────┘   │
-└──────────────────────────────────────────────────────────┘
-```
-
-### Stack
-
-| Layer | Technology |
-|---|---|
-| Server | Node.js + Fastify, TypeScript, `tsx` watch |
-| Database | Embedded PostgreSQL via `embedded-postgres` (port 54329) |
-| ORM | Drizzle ORM — SQL migrations in `packages/db/src/migrations/` |
-| UI | React 18, Vite, TailwindCSS, shadcn/ui |
-| Data fetching | TanStack Query v5 — single `queryKeys.ts` registry |
-| Agents | Claude Code (local), Codex (local), HTTP adapter |
-| Auth | Local trusted mode (no auth wall in dev) |
-
----
-
-## Ticket Pipeline
-
-Tickets are the primary organizing unit. Each ticket has a fully user-configurable `stageOrder` array:
-
-```
-planning → execution → review → qa → human
-```
+Local adapters execute inside the agent `Working directory` path. Worker kits are designed to plug into that path directly:
 
-- Stage **colors** are assigned by index position in `stageOrder` — never keyed by name
-- **Issues** (tasks) are spawned per stage and assigned to specific agents
-- Pipeline is **sequential** — only the active stage has live work; future stages are "up next"
-- **Advancing** moves `currentStage` forward; completed stages remain as history
-- Stage names, colors, and order are **fully editable inline** from the ticket detail page
+1. `growthub kit download <id>` exports the kit as a folder plus zip.
+2. Point the agent `Working directory` at the exported folder.
+3. Start a new session so the agent reads the kit contract from `CLAUDE.md`.
 
-| Status | Meaning |
-|---|---|
-| `active` | Work in progress |
-| `paused` | Manually paused |
-| `done` | All stages completed |
-| `cancelled` | Abandoned |
+### 3. Shared Templates
 
----
-
-## Canonical Agents
-
-| Agent | Role | Adapter | Purpose |
-|---|---|---|---|
-| **Planning Agent** | `pm` | `claude_local` | Breaks tickets into issues, writes specs |
-| **Execution — Codex** | `general` | `codex_local` | Implements features from issues |
-| **Execution — Claude Code** | `general` | `claude_local` | Implements features, debugging |
-| **Review — Claude** | `qa` | `claude_local` | Code review, correctness checks |
-| **QA/Debugger — Codex** | `qa` | `codex_local` | Test runs, regression debugging |
-
-All agents have `canCreateAgents: true` and `canAssignTasks: true` for sub-agent spawning.
-
----
-
-## Running locally
+Use this when you need a reusable artifact primitive without exporting a full kit.
 
 ```bash
-pnpm install
-npm run dev
-# Server + UI: http://localhost:3100
+growthub template
+growthub template list
+growthub template list --type ad-formats
+growthub template list --type scene-modules --subtype hooks
+growthub template get villain-animation
+growthub template get meme-overlay --out ~/kit/hooks/
+growthub template get villain-animation --json
 ```
 
-**No manual migrations.** Auto-migrates on every startup. To add a migration: create a `.sql` file in `packages/db/src/migrations/` and update `_journal.json` — never run `drizzle-kit push`.
-
----
+User flow:
 
-## Key directories
+1. Browse by family and artifact group.
+2. Preview the selected artifact.
+3. Print it, copy it to a local workspace, or use the slug in another workflow.
 
-```
-packages/
-  db/src/
-    schema/        Drizzle table definitions
-    migrations/    SQL files (hand-written, never generated)
-  shared/src/
-    types/         TypeScript types (Ticket, Issue, Agent, ...)
-    validators/    Zod schemas
-    constants.ts   TICKET_STAGES, TICKET_STATUSES, ...
-
-server/src/
-  routes/          Fastify route handlers
-  services/        Business logic
-  app.ts           Route registration
-
-ui/src/
-  pages/           React pages (Dashboard, TicketDetail, Tickets, Archive, ...)
-  components/      Shared UI (NewTicketModal, Sidebar, ...)
-  api/             API client (tickets.ts, issues.ts, agents.ts, ...)
-  lib/
-    queryKeys.ts         Single source of truth for all query keys
-    company-routes.ts    Route prefix logic
-
-agents/            Agent config markdown files
-```
+## Contribution Model
 
----
+The CLI has two extension surfaces for content:
 
-## Archive
+- worker kits in `cli/assets/worker-kits/`
+- shared templates in `cli/assets/shared-templates/`
 
-Issues support soft-delete via `hiddenAt`. `/archive` page supports bulk archive and restore.
+Use shared templates for reusable cross-kit primitives. Use worker kits for full opinionated environments with prompts, standards, examples, and runtime assumptions.
 
-## GitHub PR binding
+For the agent-facing extension workflow, see [docs/CLI_TEMPLATE_CONTRIBUTION_EXTENSION_WORKFLOWS.md](../docs/CLI_TEMPLATE_CONTRIBUTION_EXTENSION_WORKFLOWS.md).
 
-New Ticket modal fetches open PRs from your GitHub repos and binds them to tickets. PR context is stored in `ticket.metadata.pr` and surfaced to agents as part of ticket instructions.
+## Development Notes
 
----
+- `@growthub/cli` version: `0.3.43`
+- Node.js: `>=20`
+- Source of truth repo: [Growthub Local](https://github.com/Growthub-ai/growthub-local)
 
-## Contributing
+## Links
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md).
+- [GitHub README](https://github.com/Growthub-ai/growthub-local#readme)
+- [Contributing](https://github.com/Growthub-ai/growthub-local/blob/main/CONTRIBUTING.md)
+- [Worker Kits](https://github.com/Growthub-ai/growthub-local/blob/main/docs/WORKER_KITS.md)
+- [CLI Template Contribution Extension Workflows](https://github.com/Growthub-ai/growthub-local/blob/main/docs/CLI_TEMPLATE_CONTRIBUTION_EXTENSION_WORKFLOWS.md)

package/assets/shared-templates/ad-formats/INDEX.md

@@ -0,0 +1,94 @@
+# Ad Format Template Library — INDEX
+> Read this file first. It tells you every frozen format and scene module available.
+> Pull the format file for full scene structure, JS stubs, and adaptation rules.
+
+---
+
+## HOW TO USE THIS LIBRARY
+
+**In a brief session:**
+1. User provides a muse or concept → check this index for matching format
+2. If a match exists → load that format file → it replaces Steps 2b–2b5 in `skills.md`
+3. If no match → extract frames as normal (Step 2b) → freeze new format after the brief
+
+**Interoperability rule:** Every format file + every scene module shares the same placeholder schema:
+`[BRAND_NAME]` `[PRODUCT_NAME]` `[PRICE]` `[OFFER]` `[LANDING_PAGE]` `[AI_ACTOR_AGE]`
+Swap these from the brand-kit.md and the module is production-ready.
+
+---
+
+## FORMAT LIBRARY
+
+| ID | Format Name | Length | Scenes | Category | Muse | Status |
+|----|-------------|--------|--------|----------|------|--------|
+| `bedroom-minimic-talk` | Bedroom Mini-Mic Talk | 23s | 6 | Skincare / Beauty Tech / Any | @frankyshaw Korean skincare Reel | ✅ PROVEN |
+| `villain-animation` | Villain Object Animation | 98s | 9 | Pet / Home / Supplement | TheraPet AI Animation | ✅ PROVEN |
+| `process-specialist-medical` | The Process Specialist | ~50s | 5 | Medical / Regenerative Medicine / Healthcare Authority | Greentree Medical Center original | ✅ PROVEN |
+
+**No match? → Use frame extraction methodology:** `templates/ad-formats/frame-analysis.md`
+After completing the brief, freeze the new format using that file's Phase 6 instructions.
+
+**Format files:** `templates/ad-formats/<ID>.md`
+
+---
+
+## SCENE MODULE LIBRARY
+
+Modules are plug-in components. Mix across formats. Each module has a JS stub ready to paste.
+
+### HOOKS (Scene 1 — swap per variation)
+
+| ID | Hook Name | Best Format | Trigger |
+|----|-----------|-------------|---------|
+| `meme-overlay` | Meme Overlay Hook | `bedroom-minimic-talk` | Relatable lifestyle meme (tired, broke, stressed) |
+| `tiktok-comment` | TikTok Comment "Is this legit?" | `bedroom-minimic-talk` | Skepticism-first, high-objection categories |
+| `pov-confession` | POV Mirror Confession | `bedroom-minimic-talk` | Mirror + candid skin moment |
+| `dollar-amount` | Dollar Amount Confession | `bedroom-minimic-talk` + `villain-animation` | "Spent $X. Didn't work." |
+| `villain-hook` | Villain Character Hook | `villain-animation` | Product objects as animated villain characters |
+
+**Module files:** `templates/scene-modules/hooks/<ID>.md`
+
+### BODY SCENES (Scenes 2–N)
+
+| ID | Module Name | Best Format | Beat |
+|----|-------------|-------------|------|
+| `minimic-problem` | Mini-Mic Problem Confession | `bedroom-minimic-talk` | Authority + failed solutions |
+| `tiktok-skeptic-pivot` | TikTok Skeptic Pivot | `bedroom-minimic-talk` | "Is this legit?" disarm + product intro |
+| `product-demo-glow` | Product Demo (Light/Glow) | `bedroom-minimic-talk` | Device with visible effect (red light, UV, glow) |
+| `villain-agitation` | Villain Agitation Stack | `villain-animation` | 1–4× stacked agitation scenes with villain objects |
+| `before-after-flatlay` | Before/After + Flat Lay | `bedroom-minimic-talk` | Split screen + product flat lay + "this is the real deal." |
+
+**Module files:** `templates/scene-modules/body/<ID>.md`
+
+### CTAs (Final Scene)
+
+| ID | CTA Name | Best Format | Offer Type |
+|----|----------|-------------|------------|
+| `bogo-meme-bookend` | BOGO + Meme Bookend Close | `bedroom-minimic-talk` | Buy 1 Get 1 / % Off / Flash Offer |
+| `guarantee-close` | Guarantee Calendar Close | `villain-animation` | 30/60-day satisfaction guarantee |
+
+**Module files:** `templates/scene-modules/cta/<ID>.md`
+
+---
+
+## QUICK BRIEF ASSEMBLY GUIDE
+
+| Brief Type | Start With | Hook Module | Body Modules | CTA Module |
+|------------|------------|-------------|--------------|------------|
+| Skincare UGC (23s) | `bedroom-minimic-talk` | `meme-overlay` OR `tiktok-comment` | `minimic-problem` + `tiktok-skeptic-pivot` + `product-demo-glow` + `before-after-flatlay` | `bogo-meme-bookend` |
+| Pet/Home Device (90s+) | `villain-animation` | `villain-hook` | `villain-agitation` × 3–4 + product reveal | `guarantee-close` |
+| Any brand, new muse | Extract frames → build new format → freeze here | — | — | — |
+
+---
+
+## FREEZING A NEW FORMAT
+
+After completing a muse-based brief, freeze the format:
+1. Create `templates/ad-formats/<new-id>.md` using the schema in any existing format file
+2. Add a row to this INDEX table
+3. Extract the reusable scene modules → add to `scene-modules/` if not already there
+4. Update `skills.md` QUICK REFERENCE table to include the new format
+
+---
+
+*Template Library — Creative Strategy Worker Kit — April 2026*