@growthub/cli 0.3.54 → 0.3.56

package/README.md

@@ -1,12 +1,6 @@
 # @growthub/cli
 
-`@growthub/cli` is the published CLI for Growthub Local. It covers five shipped user flows:
-
-- full local app discovery and onboarding
-- worker kit discovery, export, inspection, and validation
-- shared template discovery and extraction
-- hosted workflows, capabilities, dynamic pipelines, and artifacts
-- hosted Growthub auth + machine profile bridge
+`@growthub/cli` is the public CLI for Growthub Local.
 
 ## Install
 
@@ -14,201 +8,107 @@
 npm install -g @growthub/cli
 ```
 
-You can also install through the guided installer:
+Or use the guided installer:
 
 ```bash
 npm create growthub-local@latest
 ```
 
-Or jump directly to a profile:
-
-```bash
-npm create growthub-local@latest -- --profile gtm
-npm create growthub-local@latest -- --profile dx
-```
-
-## CLI Editions
+## At a Glance
 
-The current CLI exposes five user-facing flows through `growthub discover` and direct subcommands.
+The CLI ships these user flows:
 
-### 1. Full Local App
+- `Agent Harness` (Paperclip Local App, Open Agents, Qwen Code CLI)
+- `Worker Kits`
+- `Templates`
+- `Workflows`
+- `Local Intelligence`
+- `Hosted Auth Bridge`
 
-Use this when you want to create or reopen a full Growthub local surface.
+## Quick Commands
 
 ```bash
+# Discovery
 growthub
-growthub list
 growthub discover
+
+# Agent Harness
 growthub onboard
 growthub run
-```
-
-User flow:
-
-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.
+growthub open-agents
+growthub qwen-code
 
-### 2. Worker Kits
-
-Use this when you want a working-directory-ready environment for an agent.
-
-### Discovery
-
-```bash
-# Interactive discovery hub
-growthub list
-
-# Interactive browser — type filter → kit selector → actions
+# Worker Kits
 growthub kit
-
-# All kits grouped by family with descriptions and inline commands
 growthub kit list
+growthub kit inspect <kit-id>
+growthub kit download <kit-id>
+growthub kit validate <path>
 
-# Filter by family
-growthub kit list --family studio
-growthub kit list --family studio,operator
+# Templates
+growthub template
+growthub template list
+growthub template get <slug>
 
-# Machine-readable output
-growthub kit list --json
+# Workflows
+growthub workflow
+growthub workflow saved
+growthub pipeline assemble
 
-# Family taxonomy
-growthub kit families
+# Hosted Auth Bridge
+growthub auth login
+growthub auth whoami
+growthub auth logout
 ```
 
-### Inspect, download, and validate
+## Worker Kit Command Surface
 
 ```bash
+growthub kit list
 growthub kit inspect creative-strategist-v1
 growthub kit inspect growthub-open-higgsfield-studio-v1
-growthub kit inspect growthub-email-marketing-v1 --json
-
 growthub kit download creative-strategist-v1
 growthub kit download growthub-open-higgsfield-studio-v1
-growthub kit download higgsfield --yes
-
 growthub kit path creative-strategist-v1
 growthub kit validate /absolute/path/to/kit
 ```
 
-### After download
-
-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 bundled kits
-
-| Kit | Family | Description |
-|---|---|---|
-| `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 execute inside the agent `Working directory` path. Worker kits are designed to plug into that path directly:
+1. Download or resolve a kit path from the CLI.
+2. Point the agent working directory at the exported folder.
+3. Start a new session so the kit contract loads from `CLAUDE.md`.
 
-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`.
+## Harness Notes
 
-### 3. Shared Templates
+### Open Agents
 
-Use this when you need a reusable artifact primitive without exporting a full kit.
+- upstream: [vercel-labs/open-agents](https://github.com/vercel-labs/open-agents)
+- secure auth mode support: `none`, `api-key`, `vercel-managed`
+- prompt/chat commands: `growthub open-agents prompt`, `growthub open-agents chat`
 
-```bash
-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
-```
+### Qwen Code CLI
 
-User flow:
+- upstream: [QwenLM/qwen-code](https://github.com/QwenLM/qwen-code)
+- secure local key setup from `growthub qwen-code` configure flow
+- prompt/chat session commands: `growthub qwen-code prompt`, `growthub qwen-code session`
 
-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.
+## Extension Model
 
-### 4. Hosted Workflows
+Content extensions:
 
-Use this when you want CMS node contract discovery, dynamic hosted pipeline creation, and saved workflow lifecycle management.
+- worker kits: `cli/assets/worker-kits/`
+- shared templates: `cli/assets/shared-templates/`
 
-```bash
-growthub workflow
-growthub workflow saved
-growthub pipeline assemble
-```
-
-### 5. Hosted Auth Bridge
-
-Use this when you want the hosted Growthub account to remain the top-level identity while syncing safe local-machine metadata into the CLI runtime.
-
-```bash
-growthub auth login
-growthub auth whoami
-growthub auth logout
-growthub profile status
-growthub profile pull
-growthub profile push
-```
-
-Contract:
-
-1. Hosted Growthub auth remains the source of truth for the user identity.
-2. Local workspace config stays local-first and is not overwritten by hosted state.
-3. Hosted machine linkage is stored separately from `instances/<id>/config.json`.
-4. `growthub` and `paperclipai` remain intentional side-by-side surfaces rather than auto-loading one another.
-
-## Workflows Discovery V1
-
-The public CLI now supports a hosted workflow discovery flow inside the interactive hub for all Growthub Auth Users:
-
-```bash
-growthub discover
-growthub workflow
-growthub workflow saved
-```
-
-Use this when you want to:
-
-- inspect CMS node contracts from the interactive contracts browser
-- list hosted saved workflows and inspect detail
-- create/save hosted workflows through Dynamic Pipelines
-- execute a hosted saved workflow from the CLI
-- manage workflow lifecycle actions (archive/delete) from CLI
-
-The full public usage and architecture notes live here:
+Governance/reference docs:
 
+- [Worker Kits](../docs/WORKER_KITS.md)
 - [CLI Workflows Discovery V1](../docs/CLI_WORKFLOWS_DISCOVERY_V1.md)
-
-## Contribution Model
-
-The CLI has two extension surfaces for content:
-
-- worker kits in `cli/assets/worker-kits/`
-- shared templates in `cli/assets/shared-templates/`
-
-Use shared templates for reusable cross-kit primitives. Use worker kits for full opinionated environments with prompts, standards, examples, and runtime assumptions.
-
-For the agent-facing extension workflow, see [docs/CLI_TEMPLATE_CONTRIBUTION_EXTENSION_WORKFLOWS.md](../docs/CLI_TEMPLATE_CONTRIBUTION_EXTENSION_WORKFLOWS.md).
-
-## Development Notes
-
-- `@growthub/cli` version: `0.3.49`
-- Node.js: `>=20`
-- Source of truth repo: [Growthub Local](https://github.com/Growthub-ai/growthub-local)
+- [Agent Harness Auth Primitive](../docs/AGENT_HARNESS_AUTH_PRIMITIVE.md)
+- [Kernel Packet Registry](../docs/kernel-packets/README.md)
 
 ## Links
 
-- [GitHub README](https://github.com/Growthub-ai/growthub-local#readme)
+- [Growthub Local Repository](https://github.com/Growthub-ai/growthub-local)
+- [Root README](https://github.com/Growthub-ai/growthub-local#readme)
 - [Contributing](https://github.com/Growthub-ai/growthub-local/blob/main/CONTRIBUTING.md)
-- [Growthub Authentication Bridge](https://github.com/Growthub-ai/growthub-local/blob/main/docs/GROWTHUB_AUTH_BRIDGE.md)
-- [CLI Workflows Discovery V1](https://github.com/Growthub-ai/growthub-local/blob/main/docs/CLI_WORKFLOWS_DISCOVERY_V1.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/worker-kits/growthub-ai-website-cloner-v1/.env.example

@@ -0,0 +1,7 @@
+# AI Website Cloner Worker Kit — Environment Config
+# Copy this file to .env and adjust values only if needed.
+# No API key is required for this kit.
+
+# Optional: override local fork path.
+# Default: ~/ai-website-cloner-template
+AI_CLONER_FORK_PATH=~/ai-website-cloner-template

package/assets/worker-kits/growthub-ai-website-cloner-v1/QUICKSTART.md

@@ -0,0 +1,116 @@
+# AI Website Cloner — Quickstart
+
+**Kit:** `growthub-ai-website-cloner-v1`  
+**Fork:** [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
+
+---
+
+## Prerequisites
+
+- Node.js 24+ — [nodejs.org](https://nodejs.org/)
+- An AI coding agent (Claude Code recommended) — `npm install -g @anthropic-ai/claude-code`
+- Git
+
+---
+
+## Step 1 — Set up the fork
+
+```bash
+bash setup/clone-fork.sh
+```
+
+This clones the `ai-website-cloner-template` fork to `~/ai-website-cloner-template` and runs `npm install`.
+
+---
+
+## Step 2 — Copy the env file (optional — no API key required)
+
+```bash
+cp .env.example .env
+```
+
+The cloner works without an API key. The `.env` file is used for optional configuration (custom fork path, default agent).
+
+---
+
+## Step 3 — Verify the environment
+
+```bash
+node setup/verify-env.mjs
+```
+
+---
+
+## Step 4 — Point your AI agent at this kit
+
+In Claude Code:
+```bash
+cd <path-to-this-kit>
+claude --chrome
+```
+
+In Cursor or other agents, open this directory as the project root.
+
+---
+
+## Step 5 — Run the clone skill
+
+In your AI agent chat:
+```
+/clone-website https://example.com
+```
+
+Or provide multiple URLs for a multi-page clone:
+```
+/clone-website https://example.com https://example.com/about https://example.com/pricing
+```
+
+---
+
+## What happens next
+
+The agent will:
+1. Screenshot the target at desktop, tablet, and mobile viewports
+2. Extract all design tokens using `getComputedStyle()`
+3. Inventory all assets (images, videos, fonts, SVGs)
+4. Write a component spec for every section
+5. Dispatch parallel builder agents in git worktrees
+6. Assemble and merge all builder outputs
+7. Run visual QA against the original screenshots
+8. Produce a platform handoff document
+
+---
+
+## Output location
+
+All artifacts land in:
+```
+~/ai-website-cloner-template/output/<client-slug>/<project-slug>/
+```
+
+The cloned Next.js components live in:
+```
+~/ai-website-cloner-template/src/components/
+```
+
+---
+
+## Running the cloned site
+
+```bash
+cd ~/ai-website-cloner-template
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to view the clone.
+
+---
+
+## Docs
+
+- `skills.md` — Full skill and pipeline reference
+- `docs/ai-website-cloner-fork-integration.md` — Fork integration details
+- `docs/multi-phase-pipeline.md` — Pipeline architecture deep-dive
+- `docs/parallel-builder-dispatch.md` — Worktree builder system
+- `docs/design-token-system.md` — Token extraction and Tailwind v4 mapping
+- `validation-checklist.md` — Pre-handoff validation checklist

package/assets/worker-kits/growthub-ai-website-cloner-v1/brands/NEW-CLIENT.md

@@ -0,0 +1,22 @@
+# New Client Setup
+
+To start a project for a new client:
+
+1. Create a brand kit directory:
+   ```bash
+   mkdir -p brands/<client-slug>
+   cp brands/_template/brand-kit.md brands/<client-slug>/brand-kit.md
+   ```
+
+2. Edit `brands/<client-slug>/brand-kit.md` with the client's details.
+
+3. Create the output directory:
+   ```bash
+   mkdir -p output/<client-slug>/<project-slug>/research
+   mkdir -p output/<client-slug>/<project-slug>/specs
+   mkdir -p output/<client-slug>/<project-slug>/qa
+   ```
+
+4. Start your AI agent session and point it at this kit directory.
+
+5. Run the clone skill: `/clone-website <target-url>`

package/assets/worker-kits/growthub-ai-website-cloner-v1/brands/_template/brand-kit.md

@@ -0,0 +1,27 @@
+# Brand Kit — [CLIENT NAME]
+
+**Created:** YYYY-MM-DD  
+**Kit:** `growthub-ai-website-cloner-v1`
+
+---
+
+## Client details
+
+- **Client:** [CLIENT NAME]
+- **Website:** [https://example.com]
+- **Industry:** [Industry]
+- **Primary contact:** [Name / email]
+
+---
+
+## Project history
+
+| Date | Deliverable | Output path |
+|---|---|---|
+| YYYY-MM-DD | AI Website Clone v1 — [Project Name] | `output/<client-slug>/<project-slug>/` |
+
+---
+
+## Notes
+
+[Any standing notes about this client's preferences, constraints, or requirements]

package/assets/worker-kits/growthub-ai-website-cloner-v1/brands/growthub/brand-kit.md

@@ -0,0 +1,26 @@
+# Brand Kit — Growthub
+
+**Created:** 2026-04-15  
+**Kit:** `growthub-ai-website-cloner-v1`
+
+---
+
+## Client details
+
+- **Client:** Growthub
+- **Website:** [https://growthub.com](https://growthub.com)
+- **Industry:** AI-powered growth tooling
+
+---
+
+## Project history
+
+| Date | Deliverable | Output path |
+|---|---|---|
+| — | — | — |
+
+---
+
+## Notes
+
+Example brand kit for operator reference. Replace with your client's details.

package/assets/worker-kits/growthub-ai-website-cloner-v1/bundles/growthub-ai-website-cloner-v1.json

@@ -0,0 +1,53 @@
+{
+  "schemaVersion": 2,
+  "bundle": {
+    "id": "growthub-ai-website-cloner-v1",
+    "version": "1.0.0",
+    "kitId": "growthub-ai-website-cloner-v1",
+    "workerId": "ai-website-cloner-operator"
+  },
+  "briefType": "ai-website-clone-project",
+  "publicExampleBrandPaths": [
+    "brands/growthub/brand-kit.md"
+  ],
+  "requiredFrozenAssets": [
+    "QUICKSTART.md",
+    ".env.example",
+    "skills.md",
+    "output-standards.md",
+    "runtime-assumptions.md",
+    "validation-checklist.md",
+    "workers/ai-website-cloner-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/clone-brief.md",
+    "templates/reconnaissance-report.md",
+    "templates/component-spec.md",
+    "templates/builder-dispatch-plan.md",
+    "templates/asset-manifest.md",
+    "templates/visual-qa-checklist.md",
+    "templates/platform-handoff.md",
+    "templates/design-token-extraction.md",
+    "examples/clone-brief-sample.md",
+    "examples/component-spec-sample.md",
+    "examples/visual-qa-sample.md",
+    "examples/platform-handoff-sample.md",
+    "docs/ai-website-cloner-fork-integration.md",
+    "docs/multi-phase-pipeline.md",
+    "docs/parallel-builder-dispatch.md",
+    "docs/design-token-system.md",
+    "growthub-meta/README.md",
+    "growthub-meta/kit-standard.md"
+  ],
+  "optionalPresets": [],
+  "export": {
+    "folderName": "growthub-agent-worker-kit-ai-website-cloner-v1",
+    "zipFileName": "growthub-agent-worker-kit-ai-website-cloner-v1.zip"
+  },
+  "activationModes": ["export"]
+}

package/assets/worker-kits/growthub-ai-website-cloner-v1/docs/ai-website-cloner-fork-integration.md

@@ -0,0 +1,118 @@
+# AI Website Cloner — Fork Integration
+
+**Kit:** `growthub-ai-website-cloner-v1`  
+**Fork:** [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
+
+---
+
+## What the fork is
+
+`ai-website-cloner-template` is a production-grade Next.js 16 + shadcn/ui + Tailwind CSS v4 template purpose-built for AI coding agents. It provides:
+
+- A pre-scaffolded Next.js codebase at the correct version and configuration
+- The `/clone-website` skill — a multi-phase pipeline for cloning any website
+- Built-in multi-agent / parallel worktree support for builder dispatch
+- Support for 13+ AI coding agents (Claude Code, Cursor, Copilot, Codex, Gemini CLI, etc.)
+
+The template is a **git repository you clone locally** — the AI agent operates inside it as its working directory.
+
+---
+
+## How this kit integrates with the fork
+
+This Growthub worker kit provides the **operator layer** on top of the fork:
+
+| Layer | What it does |
+|---|---|
+| Fork (`ai-website-cloner-template`) | Scaffold, skill definitions, parallel builder infrastructure |
+| This kit (Growthub operator) | Workflow methodology, templates, QA standards, brand management |
+
+The Growthub operator (`workers/ai-website-cloner-operator/CLAUDE.md`) reads the fork's skill definition and applies a structured 8-phase workflow with:
+- Strict phase ordering
+- Mandatory reconnaissance before spec writing
+- Explicit builder dispatch plan with worktree isolation
+- Formal QA standards with diff requirements
+- Brand kit management
+
+---
+
+## Fork setup path
+
+The fork is set up by `setup/clone-fork.sh`:
+
+```
+git clone https://github.com/JCodesMore/ai-website-cloner-template.git ~/ai-website-cloner-template
+cd ~/ai-website-cloner-template
+npm install
+```
+
+Default path: `~/ai-website-cloner-template`  
+Override: set `AI_CLONER_FORK_PATH` environment variable.
+
+---
+
+## Fork tech stack (locked)
+
+| Layer | Version |
+|---|---|
+| Next.js | 16 (App Router, React 19) |
+| TypeScript | strict mode |
+| shadcn/ui | Latest at fork commit |
+| Tailwind CSS | v4 |
+| Design tokens | oklch color space |
+| Icons | Lucide React + extracted SVGs |
+| Node.js requirement | 24+ |
+
+---
+
+## Agent support
+
+The fork's skill is defined in `.claude/skills/clone-website/SKILL.md` (synced to other agents). Supported agents:
+
+- Claude Code (recommended — `--chrome` flag enables browser automation)
+- Cursor, Windsurf, Copilot, Cline, Roo Code, Continue, Codex, OpenCode, Gemini CLI, Amazon Q, Augment Code, Aider
+
+---
+
+## How the `/clone-website` skill works
+
+When invoked, the skill:
+
+1. Opens Chrome (Claude Code) or uses Playwright/browser integration for other agents
+2. Navigates to each target URL
+3. Takes screenshots at desktop (1440px), tablet (768px), mobile (375px)
+4. Executes `getComputedStyle()` extraction in the browser console
+5. Downloads all external assets to `public/`
+6. Writes component spec files to `docs/research/components/`
+7. Dispatches parallel builder subagents — each works in a `git worktree` branch
+8. Merges all builder branches and assembles the page
+9. Runs `npm run build`, `npm run lint`, and `npm run typecheck`
+
+---
+
+## Fork structure (relevant paths for the operator)
+
+```
+~/ai-website-cloner-template/
+  .claude/
+    skills/
+      clone-website/
+        SKILL.md             # The core skill definition
+  AGENTS.md                  # Agent project instructions
+  src/
+    app/
+      page.tsx               # Main cloned page (written by orchestrator)
+      layout.tsx             # Root layout
+      globals.css            # Design tokens and base styles
+    components/
+      <section-slug>/        # One directory per cloned section (written by builders)
+      icons.tsx              # Extracted SVG icons
+    lib/
+      utils.ts               # cn() utility
+  public/
+    images/                  # Downloaded images
+    videos/                  # Downloaded videos
+    seo/                     # Favicon, OG, webmanifest
+  docs/
+    research/                # Reconnaissance output (created by operator)
+```