@growthub/cli 0.14.5 → 0.14.6

package/README.md

@@ -2,7 +2,7 @@
 
 `@growthub/cli` is the local control plane for Growthub Local and Agent Workspace as Code (AWaC).
 
-It turns repos, skills, starters, kits, and templates into governed **Workspaces** that can be exported, forked, inspected, operated by agents, kept current, and optionally connected to hosted authority. The Workspace is the top-level product object; the CLI is the executor that moves it through the lifecycle.
+It turns repos, skills, starters, and templates into governed **Workspaces** that can be exported, forked, inspected, operated by agents, kept current, and optionally connected to hosted authority. The Workspace is the top-level product object; the CLI is the executor that moves it through the lifecycle.
 
 ## Start here: create a governed Workspace
 
@@ -40,20 +40,19 @@ Growthub Local keeps the Workspace as the owned artifact: a forkable app, `growt
 
 The CLI is the machine-readable path through that architecture:
 
-- **Export** a starter, repo, skill, template, or worker kit into a local Workspace.
+- **Export** a starter, repo, skill, or template into a local Workspace.
 - **Register and inspect forks** so customization carries identity, policy, and trace instead of becoming an untracked copy.
 - **Operate ongoing lifecycle checks** for workspace status, QA, deploy readiness, upstream drift, surface detection, and portal preparation.
 - **Connect optional authority** through Growthub auth, bridge-backed integrations, hosted agents, and capability activation when local value is already clear.
 - **Expose the same contracts to agents and humans** through structured commands, JSON output, skill manifests, helper scripts, and the Workspace Builder.
 
-## Profile-first setup (recommended)
+## Workspace-first setup (recommended)
 
-The guided flow is profile-first before deeper harness/workflow choices:
+The guided flow starts at the governed workspace export path before deeper harness/workflow choices:
 
 ```bash
-npm create @growthub/growthub-local@latest -- --profile gtm
-npm create @growthub/growthub-local@latest -- --profile dx
 npm create @growthub/growthub-local@latest -- --profile workspace --out ./my-workspace
+npm create @growthub/growthub-local@latest -- --profile self-improving --out ./my-workspace
 ```
 
 ## Discovery lanes
@@ -66,7 +65,7 @@ growthub discover
 
 Core lanes:
 
-1. Worker Kits
+1. Workspace Templates
 2. Templates
 3. Workflows
 4. Local Intelligence
@@ -119,19 +118,17 @@ Compatibility examples used by package validation:
 
 ```bash
 growthub kit list
-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
-growthub kit path creative-strategist-v1
+growthub kit inspect growthub-custom-workspace-starter-v1
+growthub kit download growthub-custom-workspace-starter-v1
+growthub kit path growthub-custom-workspace-starter-v1
 growthub kit validate /absolute/path/to/kit
 ```
 
-### How local adapters use worker kits
+### How local adapters use workspace exports
 
-1. Download or resolve a kit path from the CLI.
+1. Export or resolve a workspace 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`.
+3. Start a new session so the workspace contract loads from `AGENTS.md` / `SKILL.md`.
 
 ### Workflows + pipelines
 
@@ -168,7 +165,7 @@ When ready, activate deeper hosted lanes:
 ## Docs
 
 - [Growthub Local README](https://github.com/Growthub-ai/growthub-local#readme)
-- [Worker Kits](https://github.com/Growthub-ai/growthub-local/blob/main/docs/WORKER_KITS.md)
+- [First-Run Paths](https://github.com/Growthub-ai/growthub-local/blob/main/docs/FIRST_RUN_PATHS.md)
 - [CLI Workflows Discovery](https://github.com/Growthub-ai/growthub-local/blob/main/docs/CLI_WORKFLOWS_DISCOVERY_V1.md)
 - [Agent Harness Auth Primitive](https://github.com/Growthub-ai/growthub-local/blob/main/docs/AGENT_HARNESS_AUTH_PRIMITIVE.md)
 - [Contributing](https://github.com/Growthub-ai/growthub-local/blob/main/CONTRIBUTING.md)

package/assets/worker-kits/growthub-custom-workspace-starter-v1/QUICKSTART.md

@@ -29,14 +29,13 @@ growthub starter init \
 
 After export, set `NANGO_SECRET_KEY` in the workspace runtime, complete provider OAuth, then fill `providerConfigKey`, `connectionIds`, and project identifiers in the Data Model before running the workflow.
 
-## Run the bundled Vite UI shell
+## Run the workspace app
 
 ```bash
-cd studio
+cd apps/workspace
 npm install
-npm run dev          # local dev server
-npm run build        # produces studio/dist
-node serve.mjs       # serves the built shell
+npm run dev          # local workspace builder
+npm run build        # production build
 ```
 
 ## Build out the agent contract
@@ -57,7 +56,7 @@ growthub kit fork trace --fork-id <fork-id> --tail 50
 ```bash
 growthub kit fork policy --fork-id <fork-id> --set \
   autoApprove=additive \
-  untouchablePaths+=studio/src/views/MyFeature.jsx \
+  untouchablePaths+=apps/workspace/app/custom/MyFeature.jsx \
   confirmBeforeChange+=workers/custom-workspace-operator/CLAUDE.md \
   remoteSyncMode=pr
 ```

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/api/workspace/apps/route.js

@@ -68,7 +68,7 @@ function safeRuntime(warnings) {
 
 // Mirrors the CLI probe (cli/src/commands/workspace-surface.ts) so detection
 // lives inside the artifact too — the bridge roadmap Item 4 called for.
-const KNOWN_APP_DIRS = ["apps/workspace", "apps/agency-portal", "apps/portal", "studio", "app", "src"];
+const KNOWN_APP_DIRS = ["apps/workspace"];
 
 function detectFramework(absPath) {
   try {

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/workspace-activation.js

@@ -1229,9 +1229,8 @@ function deriveAppBuildLensState(input = {}) {
 }
 
 /**
- * Fleet lens (roadmap Item 4 — now un-staged). The precondition named in
- * docs/ROADMAP_IMPACT_ITEMS_V1.md is satisfied: the runtime surface-metadata
- * source is the governed `workspace-app-registry` Data Model object
+ * Fleet lens. The runtime surface-metadata source is the governed
+ * `workspace-app-registry` Data Model object
  * (lib/workspace-app-registry.js). Each registered application derives one
  * step: status from its health rollup (linked workflows/APIs/data sources +
  * persistence/deploy flags), description from its computed next action, href

package/assets/worker-kits/growthub-custom-workspace-starter-v1/bundles/growthub-custom-workspace-starter-v1.json

@@ -46,16 +46,8 @@
     "examples/workspace-sample.md",
     "docs/starter-kit-overview.md",
     "docs/fork-sync-integration.md",
-    "docs/vite-ui-shell-guide.md",
     "docs/adapter-contracts.md",
     "docs/vercel-serverless-deployment.md",
-    "studio/index.html",
-    "studio/package.json",
-    "studio/vite.config.js",
-    "studio/serve.mjs",
-    "studio/src/main.jsx",
-    "studio/src/App.jsx",
-    "studio/src/app.css",
     "apps/workspace/package.json",
     "apps/workspace/package-lock.json",
     "apps/workspace/next.config.js",

package/assets/worker-kits/growthub-custom-workspace-starter-v1/docs/starter-kit-overview.md

@@ -1,9 +1,9 @@
 # Starter Kit — Overview
 
-The Growthub Custom Workspace Starter Kit is the canonical v1 primitive for forking a single worker kit without the rest of the repository. It combines:
+The Growthub Custom Workspace Starter Kit is the canonical v1 primitive for exporting a governed workspace without the rest of the repository. It combines:
 
 1. **Bundled asset tree** — the full custom-workspace kernel-packet surface (kit.json, frozen assets, brand scaffolds, setup, templates, examples, docs, growthub-meta).
-2. **Vite-bundled UI shell** — a minimal React + Vite 5 studio at `studio/` that users extend with their own views.
+2. **Workspace Builder app** — the config-backed Next.js app at `apps/workspace` that users run, customize, and deploy.
 3. **First-class Self-Healing Fork Sync Agent wiring** — `growthub starter init` materializes this tree at a user-chosen path and auto-registers it as a kit-fork with a dedicated `forkId`.
 
 ## Why a dedicated primitive

package/assets/worker-kits/growthub-custom-workspace-starter-v1/docs/vercel-serverless-deployment.md

@@ -6,11 +6,7 @@ The clean cloud deployment lane is the app payload:
 apps/workspace/
 ```
 
-The Growthub local-first workspace remains the kit root, and the Vite operator shell remains:
-
-```text
-studio/
-```
+The Growthub local-first workspace remains the kit root. The deployable app lives under `apps/workspace`.
 
 ## Vercel project settings
 
@@ -24,11 +20,11 @@ studio/
 At minimum, set:
 
 ```text
-AGENCY_PORTAL_DEPLOY_TARGET=vercel
-AGENCY_PORTAL_DATA_ADAPTER=<postgres|qstash-kv|provider-managed>
-AGENCY_PORTAL_AUTH_ADAPTER=<oidc|clerk|authjs|provider-managed>
-AGENCY_PORTAL_PAYMENT_ADAPTER=<none|stripe|polar>
-AGENCY_PORTAL_INTEGRATION_ADAPTER=<static|growthub-bridge|byo-api-key>
+WORKSPACE_DEPLOY_TARGET=vercel
+WORKSPACE_DATA_ADAPTER=<postgres|qstash-kv|provider-managed>
+WORKSPACE_AUTH_ADAPTER=<oidc|clerk|authjs|provider-managed>
+WORKSPACE_PAYMENT_ADAPTER=<none|stripe|polar>
+WORKSPACE_INTEGRATION_ADAPTER=<static|growthub-bridge|byo-api-key>
 ```
 
 Then set the provider-specific env required by `docs/adapter-contracts.md`.
@@ -43,4 +39,4 @@ GROWTHUB_BRIDGE_ACCESS_TOKEN=<bridge-token-issued-by-growthub-authority>
 
 The deployed app reads normalized integration state from the bridge. It does not require raw Shopify, Meta, Google Analytics, Asana, Slack, GoHighLevel, Google Drive, Notion, Windsor, or Google Sheets secrets.
 
-If `AGENCY_PORTAL_INTEGRATION_ADAPTER=byo-api-key`, set `AGENCY_PORTAL_BYO_CONNECTIONS_JSON` with the same normalized integration object fields and secret env names. This is more detailed setup, but keeps the worker kit contract composable.
+If `WORKSPACE_INTEGRATION_ADAPTER=byo-api-key`, set `WORKSPACE_BYO_CONNECTIONS_JSON` with the same normalized integration object fields and secret env names.

package/assets/worker-kits/growthub-custom-workspace-starter-v1/kit.json

@@ -4,7 +4,7 @@
     "id": "growthub-custom-workspace-starter-v1",
     "version": "1.0.0",
     "name": "Growthub Custom Workspace Starter Kit",
-    "description": "Canonical v1 starter primitive for a Growthub custom workspace worker kit. Ships a minimal Vite-bundled UI shell, a worker agent contract, the full custom-workspace kernel-packet asset surface, and first-class wiring into the Self-Healing Fork Sync Agent. Users can fork just this one kit without the rest of the repository and the CLI will register the new directory as a self-describing fork with a dedicated forkId, honouring every v1 policy, trace, and remote-sync invariant.",
+    "description": "Canonical v1 starter primitive for a Growthub custom workspace. Ships the apps/workspace builder, a worker agent contract, the full custom-workspace kernel-packet asset surface, and first-class wiring into the Self-Healing Fork Sync Agent. Users can fork this workspace starter without the rest of the repository and the CLI will register the new directory as a self-describing fork with a dedicated forkId, honouring every v1 policy, trace, and remote-sync invariant.",
     "type": "worker",
     "visibility": "public-open-source",
     "sourceRepo": "growthub-local",
@@ -58,16 +58,8 @@
     "examples/workspace-sample.md",
     "docs/starter-kit-overview.md",
     "docs/fork-sync-integration.md",
-    "docs/vite-ui-shell-guide.md",
     "docs/adapter-contracts.md",
     "docs/vercel-serverless-deployment.md",
-    "studio/index.html",
-    "studio/package.json",
-    "studio/vite.config.js",
-    "studio/serve.mjs",
-    "studio/src/main.jsx",
-    "studio/src/App.jsx",
-    "studio/src/app.css",
     "apps/workspace/docs/sandbox-environment-primitive.md",
     "apps/workspace/README.md",
     "apps/workspace/.env.example",
@@ -164,7 +156,7 @@
   },
   "outputStandard": {
     "type": "working-directory",
-    "description": "Fork the starter kit directly with `growthub starter init` \u2014 the CLI materializes this bundled asset tree to the user's chosen path, auto-registers the destination as a kit-fork (canonical state under `<forkPath>/.growthub-fork/fork.json`), optionally binds it to a GitHub remote, and hands off the forkId. Every downstream customization flows through the v1 Self-Healing Fork Sync Agent.",
+    "description": "Fork the starter kit directly with `growthub starter init` — the CLI materializes this bundled asset tree to the user's chosen path, auto-registers the destination as a kit-fork (canonical state under `<forkPath>/.growthub-fork/fork.json`), optionally binds it to a GitHub remote, and hands off the forkId. Every downstream customization flows through the v1 Self-Healing Fork Sync Agent.",
     "requiredPaths": [
       "QUICKSTART.md",
       "kit.json",
@@ -180,7 +172,6 @@
       "setup/verify-env.mjs",
       "setup/check-deps.sh",
       "output/README.md",
-      "studio",
       "templates",
       "templates/project.md",
       "templates/self-eval.md",

package/assets/worker-kits/growthub-custom-workspace-starter-v1/runtime-assumptions.md

@@ -2,7 +2,7 @@
 
 - **Node**: >= v20 (the Growthub CLI ships `resolveCliVersion()` which is tested against the same minimum).
 - **Git**: required on PATH for fork-sync remote operations.
-- **Vite**: `studio/` uses Vite 5 + React 18; any compatible toolchain is fine.
+- **Workspace app**: `apps/workspace` is the exported Next.js builder and the only bundled app surface.
 - **Fork registration**: the CLI expects `<forkPath>/.growthub-fork/fork.json` to exist and be readable. Do not commit this file to version control if you are publishing your fork — `.growthub-fork/` is developer-local state and should be added to `.gitignore`.
 - **Policy defaults**: `autoApprove=additive`, `autoApproveDepUpdates=additive`, `remoteSyncMode=off`, `interactiveConflicts=true`.
 - **Bundled sources**: everything under `frozenAssetPaths` in `kit.json` is upstream-owned. Modify at your own risk — the Self-Healing Fork Sync Agent flags every change there for confirmation.

package/assets/worker-kits/growthub-custom-workspace-starter-v1/skills.md

@@ -4,8 +4,7 @@ This file catalogues the skills the Custom Workspace Operator offers out of the
 
 ## Built-in skills (upstream-owned, heal will update)
 
-- **scaffold-view** — generate a new Vite view under `studio/src/views/<Name>.jsx`
-- **scaffold-api** — stub an API adapter under `studio/src/api/<slug>.js`
+- **workspace-mutation** — use the governed `PATCH /api/workspace` lane for dashboards, widgets, canvas, and Data Model edits.
 - **emit-brand-scaffold** — clone `brands/_template/brand-kit.md` to `brands/<slug>/brand-kit.md`
 - **trace-inspect** — summarise the last N events in `.growthub-fork/trace.jsonl`
 

package/assets/worker-kits/growthub-custom-workspace-starter-v1/validation-checklist.md

@@ -7,7 +7,7 @@ Run before declaring a workspace ready for production:
 - [ ] `.growthub-fork/fork.json` is present and `growthub kit fork status <fork-id>` returns severity = none
 - [ ] `policy.json` reflects the intended safety envelope
 - [ ] `trace.jsonl` contains at minimum `registered` + `policy_updated` + one `status_ran` event
-- [ ] `studio/` builds with `npm run build` (no errors)
+- [ ] `apps/workspace` builds with `npm run build` (no errors)
 - [ ] `growthub kit fork heal <fork-id> --dry-run` produces zero errors
 - [ ] When `policy.remoteSyncMode === "pr"`: the GitHub remote is reachable and the last heal opened a draft PR
 - [ ] `growthub status --super-admin` shows all critical services operational

package/assets/worker-kits/growthub-custom-workspace-starter-v1/workers/custom-workspace-operator/CLAUDE.md

@@ -10,7 +10,7 @@ You are the Custom Workspace Operator — the agent wired to this Growthub custo
 - `bundles/growthub-custom-workspace-starter-v1.json` — the bundle contract
 - `brands/_template/brand-kit.md` — empty brand scaffold
 - `brands/growthub/brand-kit.md` — reference brand
-- `studio/` — the Vite UI shell (React + Vite 5)
+- `apps/workspace/` — the Next.js workspace builder and `/api/workspace` runtime
 - `templates/project.md` — session-memory template (seed for `.growthub-fork/project.md`)
 - `templates/self-eval.md` — self-evaluation pattern
 - `helpers/` — safe shell tool layer (starts empty; promote inline shell here over time)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growthub/cli",
-  "version": "0.14.5",
+  "version": "0.14.6",
   "description": "CLI control plane for Growthub Local and Agent Workspace as Code: export, fork, inspect, operate, sync, and optionally activate governed AI workspaces.",
   "type": "module",
   "bin": {
@@ -37,13 +37,12 @@
   },
   "devDependencies": {
     "@types/node": "^24.6.0",
-    "typescript": "^5.7.3",
-    "vitest": "^3.0.5"
+    "typescript": "^5.7.3"
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.888.0",
     "@clack/prompts": "^0.10.0",
-    "@growthub/api-contract": "1.5.1",
+    "@growthub/api-contract": "1.5.2",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",
     "better-auth": "1.4.18",

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

@@ -1,94 +0,0 @@
-# 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*

package/assets/shared-templates/ad-formats/bedroom-minimic-talk.md

@@ -1,197 +0,0 @@
-# Ad Format: Bedroom Mini-Mic Talk
-> ID: `bedroom-minimic-talk`
-> Category: Skincare / Beauty Tech / Consumer Product (any)
-> Length: 20–30 seconds (proven at 23s)
-> Scene Count: 6
-> Hook Variations: 5 (A–E)
-> Status: ✅ PROVEN — Solawave BOGO brief, April 2026
-> Aspect Ratios: 9:16 primary, 1:1 secondary
-
----
-
-## MUSE REFERENCE
-
-- **Creator:** @frankyshaw (Instagram / TikTok)
-- **URL:** https://www.instagram.com/reels/DU1lWOeDsdg/
-- **Original product featured:** Dr. Melaxin Cemenrete (Korean skincare)
-- **Local muse file:** `~/Downloads/Korean skincare truth…mp4`
-- **Runtime:** 23 seconds | 720×1280 | 9:16 vertical
-- **Why it works:** High-spend, high-persuasion skincare category. Meme-bookend (opens tired/closes approving) creates an emotional payoff that feels earned. Mini-mic prop signals authenticity without production cost. TikTok comment overlay intercepts the #1 objection before it forms. Self-aware humor prevents it from feeling like an ad.
-
----
-
-## FORMAT SIGNALS (non-negotiable)
-
-These elements define the format. Remove any one and the format stops working.
-
-1. **Mini-mic prop** — silver condenser-style microphone held at chin/chest level in every close-up. This is the TikTok "I'm about to tell you the truth" signal.
-2. **Meme bookend** — viral meme overlay opens the ad (relatable problem) and closes it (approving/satisfied). Same meme character, emotional state flips from tired → happy. DW from Arthur was the original; any relatable viral character works.
-3. **Bedroom / cozy desk setting** — warm ambient light, slightly messy background. Specifically NOT a studio. Authenticity depends on this.
-4. **Karaoke-style captions** — white text, black outline, key words bolded. Bottom third. Essential — 70%+ views are silent.
-5. **Product shown 3× minimum** — held casually (Scene 2), in use/active state (Scene 4), flat lay with arrows (Scene 5). Never just once.
-6. **"this is the real deal."** — this exact phrase with arrows pointing at the product in the flat lay scene (Scene 5). Proven persuasion trigger. Do not paraphrase.
-7. **TikTok comment overlay** — "Is this legit?" comment bubble overlaid in Scene 3. Addresses skepticism from inside the format, not as a defensive rebuttal.
-
----
-
-## PROVEN SCENE STRUCTURE
-
-| # | Scene Name | Timecode | Beat | Sacred Element |
-|---|------------|----------|------|----------------|
-| 1 | Opening Hook | 0–3s | Pattern interrupt — scroll stop | Meme overlay + problem statement. 5 variations (A–E). |
-| 2 | Authority & Problem | 3–8s | Shared experience builds credibility | Mini-mic, product held casually, "$X spent, nothing worked" |
-| 3 | Skeptic Pivot | 8–13s | Disarm objection before it forms | TikTok comment "Is this legit?" overlay + product reveal |
-| 4 | Product Demo | 13–18s | Product in action — visual proof | Active visual effect (red light, glow, motion). Product in use. |
-| 5 | Before/After + Authority | 18–21s | Receipt / social proof | Split screen + flat lay + arrows + "this is the real deal." |
-| 6 | CTA Close | 21–23s | Convert | Meme bookend (approving) + offer overlay + "link in bio" |
-
----
-
-## SCENE MODULES USED IN THIS FORMAT
-
-Plug these directly from `scene-modules/`:
-
-| Scene | Module ID | File |
-|-------|-----------|------|
-| 1 | `meme-overlay` OR `tiktok-comment` OR `pov-confession` OR `dollar-amount` | `hooks/<id>.md` |
-| 2 | `minimic-problem` | `body/minimic-problem.md` |
-| 3 | `tiktok-skeptic-pivot` | `body/tiktok-skeptic-pivot.md` |
-| 4 | `product-demo-glow` | `body/product-demo-glow.md` |
-| 5 | `before-after-flatlay` | `body/before-after-flatlay.md` |
-| 6 | `bogo-meme-bookend` | `cta/bogo-meme-bookend.md` |
-
----
-
-## ADAPTATION RULES
-
-### Keep (sacred)
-- Scene count: exactly 6
-- Mini-mic prop in Scenes 1, 2, 3, 6
-- Meme overlay in Scene 1 (hook) AND Scene 6 (approving bookend) — same meme, emotional flip
-- TikTok comment overlay in Scene 3
-- "this is the real deal." + arrows in Scene 5
-- Self-aware humor beat — one moment in Scene 3–4 (breaks 4th wall)
-- Bedroom/cozy setting throughout — never studio
-
-### Swap (per brand)
-- The specific meme character (DW from Arthur → any relatable viral character)
-- The product shown — must have a visually active state (glow, motion, transformation)
-- The dollar amount in Scene 2 ("$300 on serums" → "$X on [category product]")
-- The TikTok comment text — keep structure, swap the product reference
-- The offer text in Scene 6 ("BOGO" → "50% off" → "Free trial" → etc.)
-
-### Never
-- Studio lighting or production set — ruins the UGC authenticity
-- Full-frame video meme cuts — meme must be overlay on creator's frame (eyes always visible above)
-- Voiceover-only — the actor must be on screen speaking (this format is UGC dialogue, not VO)
-- More than 3 seconds of uninterrupted talking head — always break with a visual
-- Product shown without active state — for beauty tech, the glow/effect IS the product
-
----
-
-## AI ACTOR SPEC (default — adapt per brand)
-
-```yaml
-age_range:      "22–32"
-gender:         "Female-presenting"
-look:           "Natural, warm skin tone. Light or no visible makeup. Hair loosely pulled back or down."
-outfit:         "Oversized hoodie or neutral crew-neck top. Bedroom-casual — NOT styled."
-setting:        "Cozy desk or bedroom. Warm ambient light (lamp or diffused window). Slight background clutter (books, skincare items, etc.) — NOT minimalist."
-prop:           "Silver condenser-style mini microphone. Essential. Always in hand for Scenes 1–3 and 6."
-energy:         "Conspiratorial best-friend energy. 'I looked this up so you don't have to.' NOT spokesperson."
-```
-
----
-
-## DOCX JS STUBS
-
-Paste these sceneBlock() calls into the brief JS file. Replace `[PLACEHOLDERS]`.
-
-```js
-// SCENE 1 — Hook Window (use for the shared scene setup above the 5 hook cards)
-sceneBlock("SCENE 1 — HOOK WINDOW", "0–3 seconds  |  MUST stop the scroll", [
-  ["Visual Direction", "AI actor at desk/bedroom. Meme overlay fills lower 60% of frame. Actor's eyes visible above meme. Mini-mic in hand at chin level. Warm ambient lighting."],
-  ["On-Screen Text",   "[Hook line from variation — white bold caption, bottom third]"],
-  ["AI Actor VO",      "[Hook line from active variation — natural delivery, not scripted]"],
-  ["Purpose",          "Stop the scroll. Pattern-interrupt with meme format. Identify pain point before viewer can tap away."],
-])
-
-// SCENE 2 — Authority & Problem
-sceneBlock("SCENE 2 — AUTHORITY & PROBLEM", "3–8 seconds  |  Consistent across all variations", [
-  ["Visual Direction",  "AI actor close-up. Mini-mic in one hand, [PRODUCT_NAME] held casually in the other. Skincare shelf visible, slightly out-of-focus background."],
-  ["Actor Line",        "'I've tried [CATEGORY_PRODUCTS]. [DOLLAR_SPENT] later. Nothing gave me what I actually needed for [PAIN_POINT].'"],
-  ["On-Screen Text",    "'[products listed].' — caption. Key words bold."],
-  ["Purpose",           "Build credibility through shared experience. She's not naive — she's tried everything. Positions [PRODUCT_NAME] reveal as earned discovery."],
-  ["Transition",        "Direct cut to close-up of [PRODUCT_NAME] being lifted into frame."],
-])
-
-// SCENE 3 — Skeptic Pivot + Product Intro
-sceneBlock("SCENE 3 — SKEPTIC PIVOT + PRODUCT INTRO", "8–13 seconds  |  Consistent across all variations", [
-  ["Visual Direction",  "TikTok comment bubble overlaid: 'Is this legit tho?' — actor glances at it, smiles, looks back at camera. [PRODUCT_NAME] now held up, [ACTIVE_STATE]."],
-  ["Actor Line",        "'That's literally what I said. So I looked it up. [MECHANISM] — [WHAT IT DOES] — in [PRODUCT_FORM] you use at home.'"],
-  ["On-Screen Text",    "TikTok comment: 'Is this legit tho?' → clears. Caption: '[MECHANISM]. at home.' — bold highlight on [MECHANISM]."],
-  ["Purpose",           "Intercept #1 objection ('is this a gimmick?') before viewer consciously forms it. [ACTIVE_STATE] = visual proof it does something."],
-  ["Transition",        "Cut to [PRODUCT_NAME] in use — [ACTIVE_STATE] in motion."],
-])
-
-// SCENE 4 — Product Demo
-sceneBlock("SCENE 4 — PRODUCT DEMO", "13–18 seconds  |  Consistent across all variations", [
-  ["Visual Direction",  "Close-up of [PRODUCT_NAME] in use: [USE_AREA_1], [USE_AREA_2], [USE_AREA_3]. [ACTIVE_STATE] visible and cinematic. Skin looks luminous, dewy."],
-  ["Actor Line",        "'[MECHANISM_SHORT] — [BENEFIT]. You use it for [TIME]. Done.'"],
-  ["On-Screen Text",    "'[MECHANISM_SHORT]' — caption. Then: '[TIME]. That's it.' — bold, centered."],
-  ["Purpose",           "Show the product WORKING. [ACTIVE_STATE] is [BRAND]'s visual superpower. Make viewer want that effect on their own skin."],
-  ["Transition",        "Cut to split-screen: before LEFT — [PRODUCT_NAME] in use RIGHT."],
-])
-
-// SCENE 5 — Before/After + Product Authority
-sceneBlock("SCENE 5 — BEFORE/AFTER + PRODUCT AUTHORITY", "18–21 seconds  |  Consistent across all variations", [
-  ["Visual Direction",  "(1) Split-screen 1.5s: bare skin LEFT — same with [PRODUCT_NAME] in use RIGHT.\n\n(2) Product flat lay: [PRODUCT_NAME] centered on clean surface. [ACTIVE_STATE]. 3 white arrows point down at product. Warm lighting."],
-  ["Actor Line",        "'This is the real deal. [PERSONAL_RESULT_STATEMENT].'"],
-  ["On-Screen Text",    "Split: LEFT 'before [BRAND_NAME]' / RIGHT '[TIMEFRAME]'\n\nFlat lay: 'this is the real deal.' — bold white + 3 animated arrows pointing down. '[BRAND_NAME]' below."],
-  ["Purpose",           "Social proof + product authority. Split-screen is the receipt. 'this is the real deal.' closes the credibility loop before the CTA."],
-  ["Transition",        "Hard cut to CTA frame."],
-])
-
-// SCENE 6 — CTA Close
-sceneBlock("SCENE 6 — CTA + OFFER CLOSE", "21–23 seconds  |  Consistent across all variations", [
-  ["Visual Direction",  "Actor back on camera, mini-mic in hand, [PRODUCT_NAME] raised toward camera ([ACTIVE_STATE]). Approving/confident expression. Optional: meme bookend (approving version of Scene 1 meme) for 0.5–1s."],
-  ["Actor Line",        "'[OFFER_TEXT] right now — link in bio.'"],
-  ["On-Screen Text",    "'[OFFER_TEXT]' — large bold\n'[LANDING_PAGE]' — below\n'Shop Now →'\n(Optional: 'Limited time | Results may vary')"],
-  ["Purpose",           "Drive the one action: click. [OFFER] is the urgency mechanism. 2 seconds max — viewer already knows. Just close."],
-])
-```
-
----
-
-## AI GENERATION PROMPTS (per-scene stubs)
-
-Replace `[PLACEHOLDERS]` with brand-specific values.
-
-```
-SCENE 1 — Muse Hook
-Photoreal female creator, [AI_ACTOR_AGE], natural look, warm skin tone. Bedroom desk. Casual [OUTFIT]. Silver condenser mini-mic in hand. [MEME_CHARACTER] overlay fills lower 60% — creator's eyes visible above. She glances at meme, looks up with knowing half-smile. Authentic TikTok creator bedroom reel. 9:16. 3 seconds.
-
-SCENE 2 — Authority & Problem
-Same creator. Mini-mic in left hand. [PRODUCT_NAME] held casually in right (not presenting). [CATEGORY_ITEMS] slightly out-of-focus on shelf behind. She speaks candidly, slightly frustrated then resolving. Warm golden light. Tight angles: face / hands / shelf. 9:16. 5 seconds.
-
-SCENE 3 — Skeptic Pivot + Reveal
-Same creator. TikTok comment bubble overlaid: 'Is this legit tho?' — she glances at it, smiles, looks at camera. Turns [PRODUCT_NAME] toward lens — [ACTIVE_STATE] faces camera. [ACTIVE_STATE] cinematic and warm. Handheld feel. 9:16. 5 seconds.
-
-SCENE 4 — Product Demo
-Extreme close-up of [PRODUCT_NAME] gliding along skin: [USE_AREA_1], [USE_AREA_2], [USE_AREA_3]. [ACTIVE_STATE] warm and cinematic. Dewy healthy skin texture. Micro-clips, cut every 1.5–2s. Creator's voice continues over. 9:16. 5 seconds.
-
-SCENE 5 — Before/After + Flat Lay
-CLIP 1: Split-screen. LEFT bare natural skin label 'before [BRAND_NAME]' / RIGHT [PRODUCT_NAME] in use label '[TIMEFRAME]'. Matching warm light both sides.
-CLIP 2: [PRODUCT_NAME] centered on white/marble surface. [ACTIVE_STATE]. 3 white arrows pointing down. 'this is the real deal.' bold white text. 9:16. 3 seconds.
-
-SCENE 6 — CTA
-Creator energized, [PRODUCT_NAME] raised toward camera ([ACTIVE_STATE]). Warm, direct smile. Optional: meme bookend 0.5s. Fades to: '[OFFER_TEXT]' bold + '[LANDING_PAGE]' + 'Shop Now →'. 9:16. 2 seconds.
-```
-
----
-
-## FIRST DEPLOYED — Solawave BOGO Campaign
-
-- Brief: `~/Downloads/Solawave_VideoBrief_KoreanSkincaretruth_v1_20260409.docx`
-- Brand kit: `brands/solawave/brand-kit.md`
-- Script: `/tmp/docx_work/solawave_brief_v1.js`