@growthub/cli 0.7.9 → 0.8.1

package/assets/worker-kits/growthub-agency-portal-starter-v1/apps/agency-portal/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "growthub-agency-portal-app",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "next": "16.2.4",
+    "react": "19.2.4",
+    "react-dom": "19.2.4"
+  }
+}

package/assets/worker-kits/growthub-agency-portal-starter-v1/apps/agency-portal/postcss.config.mjs

@@ -0,0 +1,3 @@
+export default {
+  plugins: {},
+};

package/assets/worker-kits/growthub-agency-portal-starter-v1/apps/agency-portal/vercel.json

@@ -0,0 +1,5 @@
+{
+  "framework": "nextjs",
+  "buildCommand": "npm run build",
+  "installCommand": "npm install"
+}

package/assets/worker-kits/growthub-agency-portal-starter-v1/brands/NEW-CLIENT.md

@@ -0,0 +1,10 @@
+# New Client — Onboarding
+
+When the operator starts a new project:
+
+1. Create `brands/<client-slug>/brand-kit.md` from the `_template` scaffold.
+2. Fill in the Identity, Voice, Visual, Assets sections.
+3. Append a `registered` event to `.growthub-fork/trace.jsonl` with `{clientSlug}` in the detail.
+4. Run `growthub kit fork status <fork-id>` to confirm no drift was introduced.
+
+The `_template/` brand is upstream-owned; all real client work lives under `brands/<client-slug>/`.

package/assets/worker-kits/growthub-agency-portal-starter-v1/brands/_template/brand-kit.md

@@ -0,0 +1,27 @@
+# Brand Kit — Template
+
+Copy this template to `brands/<slug>/brand-kit.md` and fill in the fields.
+
+## Identity
+
+- Display name:
+- Slug:
+- Tagline:
+
+## Voice
+
+- Tone:
+- Vocabulary:
+- Anti-patterns to avoid:
+
+## Visual
+
+- Primary colour:
+- Secondary colour:
+- Typography pairing:
+
+## Assets
+
+- Logo URL:
+- Favicon URL:
+- Open Graph image URL:

package/assets/worker-kits/growthub-agency-portal-starter-v1/brands/growthub/brand-kit.md

@@ -0,0 +1,25 @@
+# Growthub — Reference Brand Kit
+
+A worked example of a fully-populated brand kit. The `growthub/` brand is owned by upstream — if you want to customize, create your own brand under `brands/<your-slug>/brand-kit.md`.
+
+## Identity
+
+- Display name: Growthub
+- Slug: growthub
+- Tagline: Local DX and GTM runtime for AI-native teams.
+
+## Voice
+
+- Tone: Direct, technical, no filler.
+- Vocabulary: "Worker kit", "custom workspace", "kernel packet", "fork-sync", "heal".
+- Anti-patterns: marketing fluff, redundant adjectives, overpromising.
+
+## Visual
+
+- Primary colour: #0a0a0a
+- Secondary colour: #4ade80
+- Typography: Inter for UI, JetBrains Mono for code.
+
+## Assets
+
+- See `ui/public/` in the main repository.

package/assets/worker-kits/growthub-agency-portal-starter-v1/bundles/growthub-agency-portal-starter-v1.json

@@ -0,0 +1,65 @@
+{
+  "schemaVersion": 2,
+  "bundle": {
+    "id": "growthub-agency-portal-starter-v1",
+    "version": "1.0.0",
+    "kitId": "growthub-agency-portal-starter-v1",
+    "workerId": "agency-portal-operator"
+  },
+  "briefType": "agency-portal-workspace",
+  "capabilityType": "worker",
+  "executionMode": "export",
+  "activationModes": [
+    "export"
+  ],
+  "export": {
+    "folderName": "growthub-agent-worker-kit-agency-portal-starter-v1",
+    "zipFileName": "growthub-agent-worker-kit-agency-portal-starter-v1.zip"
+  },
+  "publicExampleBrandPaths": [
+    "brands/growthub/brand-kit.md"
+  ],
+  "requiredFrozenAssets": [
+    "QUICKSTART.md",
+    ".env.example",
+    "SKILL.md",
+    "skills.md",
+    "output-standards.md",
+    "runtime-assumptions.md",
+    "validation-checklist.md",
+    "workers/agency-portal-operator/CLAUDE.md",
+    "brands/_template/brand-kit.md",
+    "brands/growthub/brand-kit.md",
+    "brands/NEW-CLIENT.md",
+    "setup/verify-env.mjs",
+    "setup/check-deps.sh",
+    "output/README.md",
+    "templates/workspace-brief.md",
+    "templates/portal-brief.md",
+    "templates/client-onboarding-plan.md",
+    "templates/agent-contract.md",
+    "templates/deployment-plan.md",
+    "templates/deployment-handoff.md",
+    "templates/supabase-setup-plan.md",
+    "templates/project.md",
+    "templates/self-eval.md",
+    "helpers/README.md",
+    "skills/README.md",
+    "examples/portal-brief-sample.md",
+    "docs/governed-workspace-primitives.md",
+    "docs/adapter-contracts.md",
+    "docs/vercel-serverless-deployment.md",
+    "studio/package.json",
+    "studio/package-lock.json",
+    "apps/agency-portal/package.json",
+    "apps/agency-portal/package-lock.json",
+    "apps/agency-portal/next.config.js",
+    "apps/agency-portal/app/settings/integrations/page.jsx",
+    "apps/agency-portal/lib/adapters/env.js",
+    "apps/agency-portal/lib/adapters/integrations/index.js",
+    "apps/agency-portal/lib/adapters/integrations/growthub-connection-normalizer.js",
+    "apps/agency-portal/lib/domain/integrations.js",
+    "growthub-meta/README.md",
+    "growthub-meta/kit-standard.md"
+  ]
+}

package/assets/worker-kits/growthub-agency-portal-starter-v1/docs/adapter-contracts.md

@@ -0,0 +1,79 @@
+# Adapter Contracts — Agency Portal Starter
+
+The worker-kit contract is provider-agnostic. Concrete providers are configured through environment variables and adapter documentation, not through kit identity.
+
+## Persistence
+
+`AGENCY_PORTAL_DATA_ADAPTER` selects the persistence layer:
+
+| Value | Required env | Runtime target |
+|---|---|---|
+| `postgres` | `DATABASE_URL` | Any Postgres-compatible database |
+| `qstash-kv` | `QSTASH_KV_REST_URL`, `QSTASH_KV_REST_TOKEN` | Qstash/Vercel KV-style HTTP storage |
+| `provider-managed` | Provider-specific env in `.env` | Hosted database surface managed outside the kit |
+
+The app payload under `apps/agency-portal/` exposes these adapters as code-level interfaces. Treat any future provider-specific implementation as replaceable behind this contract.
+
+## Auth
+
+`AGENCY_PORTAL_AUTH_ADAPTER` selects the auth layer:
+
+| Value | Required env |
+|---|---|
+| `oidc` | `AUTH_SECRET`, `AUTH_ISSUER`, `AUTH_CLIENT_ID`, `AUTH_CLIENT_SECRET` |
+| `clerk` | provider-specific Clerk env |
+| `authjs` | Auth.js-compatible env |
+| `provider-managed` | provider-specific env |
+
+## Payments
+
+`AGENCY_PORTAL_PAYMENT_ADAPTER` selects payment support:
+
+| Value | Required env |
+|---|---|
+| `none` | none |
+| `stripe` | `PAYMENT_SECRET_KEY`, optional `PAYMENT_WEBHOOK_SECRET` |
+| `polar` | `PAYMENT_SECRET_KEY`, optional `PAYMENT_WEBHOOK_SECRET` |
+
+## Reporting
+
+`AGENCY_PORTAL_REPORTING_ADAPTER` is optional. Use `windsor` for the first-party reporting path. Windsor AI is treated as a reporting/data-source adapter, not as the database. The starter keeps persistence selected by `AGENCY_PORTAL_DATA_ADAPTER`.
+
+The intended Windsor pattern is:
+
+1. Connect Windsor AI through the Growthub GH app/MCP bridge.
+2. Use Windsor's blended data support to publish or sync blended marketing datasets into Google Sheets when spreadsheet-backed reporting is preferred.
+3. Read normalized connection state through the integration adapter rather than storing Windsor, Google Analytics, Shopify, or Meta credentials in the starter app.
+
+## Integrations
+
+`AGENCY_PORTAL_INTEGRATION_ADAPTER` selects how Settings resolves data sources and workspace integrations:
+
+| Value | Required env | Authority |
+|---|---|---|
+| `growthub-bridge` | `GROWTHUB_BRIDGE_BASE_URL`, `GROWTHUB_BRIDGE_ACCESS_TOKEN` | Growthub GH app MCP connection authority |
+| `byo-api-key` | `AGENCY_PORTAL_BYO_CONNECTIONS_JSON` or `WINDSOR_API_KEY` for Windsor-only setup | Workspace-owned explicit provider setup |
+| `static` | none | Local starter catalog for development and exported workspaces without hosted authority |
+
+The bridge adapter is intentionally thin. It expects a JSON endpoint configured by `GROWTHUB_BRIDGE_INTEGRATIONS_PATH` (default `/api/mcp/accounts`) and normalizes the response into two lanes:
+
+- **Data sources**: Windsor AI, Google Sheets blended data, Google Analytics, Shopify, Meta Facebook/Instagram.
+- **Workspace integrations**: Asana, Slack, GoHighLevel, Google Drive, Notion.
+
+The GH app authority pattern observed in `/Users/antonio/gh-app` is CMS catalog rows plus active `mcp_connections` rows. The starter does not query that database directly. It consumes the bridge API so the hosted app keeps ownership of user auth, tokens, verification, account IDs, scopes, and provider metadata.
+
+The kit-local primitive for this is `apps/agency-portal/lib/adapters/integrations/growthub-connection-normalizer.js`. It accepts the SDK/profile-style integration shape:
+
+```json
+{ "integrations": [{ "provider": "slack", "label": "Slack", "connectedAt": "...", "scopes": [], "handle": "...", "ready": true }] }
+```
+
+It also accepts the GH app MCP accounts shape returned by `/api/mcp/accounts`:
+
+```json
+{ "success": true, "accounts": [{ "id": "...", "provider": "slack", "connectionName": "Slack", "connectionType": "oauth_first_party", "isActive": true, "isVerified": true, "metadata": {}, "createdAt": "...", "updatedAt": "...", "appSlug": "slack" }] }
+```
+
+Both shapes normalize into the same `AgencyPortalIntegration` object used by the BYO path. Unknown connected providers are preserved as discovered workspace integrations instead of being dropped.
+
+The BYO path uses the same normalized object shape, but expects the workspace operator to provide the connection metadata and secret env names explicitly. Windsor is first-class: when `WINDSOR_API_KEY` is set with `AGENCY_PORTAL_INTEGRATION_ADAPTER=byo-api-key`, the app marks the Windsor AI data pipeline object as connected without requiring a larger JSON payload. The hosted Growthub bridge remains the lower-friction first-party path for user-owned MCP connections.

package/assets/worker-kits/growthub-agency-portal-starter-v1/docs/fork-sync-integration.md

@@ -0,0 +1,32 @@
+# Starter Kit — Fork Sync Integration
+
+The starter kit is the first bundled worker kit that is both a **template** and a **native consumer** of the Self-Healing Fork Sync Agent.
+
+## What the starter registers for you
+
+On `growthub starter init` the CLI:
+
+1. Materializes the bundled tree to `<out>` via `copyBundledKitSource`.
+2. Calls `registerKitFork({ forkPath, kitId, baseVersion })` — writes `<out>/.growthub-fork/fork.json` and appends an entry to the CLI-owned discovery index at `GROWTHUB_KIT_FORKS_HOME/index.json`.
+3. Seeds `<out>/.growthub-fork/policy.json` with conservative defaults (`autoApprove=additive`, `remoteSyncMode=off`, `interactiveConflicts=true`).
+4. Appends a `registered` event to `<out>/.growthub-fork/trace.jsonl`.
+5. Optionally binds a GitHub remote via `growthub kit fork create --upstream <owner/repo>` or `growthub kit fork connect --remote <owner/repo>`.
+
+## What you never have to do manually
+
+- Generate a forkId.
+- Write the initial policy.json.
+- Ensure `.growthub-fork/` is present and well-formed.
+- Add the fork to the discovery index.
+
+## When upstream ships a new version
+
+Exactly the same flow as every other kit-fork:
+
+```
+growthub kit fork status <fork-id>
+growthub kit fork heal <fork-id> --dry-run
+growthub kit fork heal <fork-id>
+```
+
+The heal plan honours your `policy.json`. User-modified files, `policy.untouchablePaths`, and `CUSTOM_SKILL_PATTERNS` are never overwritten.

package/assets/worker-kits/growthub-agency-portal-starter-v1/docs/governed-workspace-primitives.md

@@ -0,0 +1,182 @@
+# Governed-Workspace Primitives — How Your Workspace Coordinates Agents at Enterprise Scale
+
+Every workspace you create with Growthub Local — greenfield via `growthub starter init`, or imported via `growthub starter import-repo` / `import-skill`, or materialised from any worker kit via `growthub kit download` — inherits six architectural primitives that make the workspace **self-describing to agents**, **continuous across sessions**, and **auditable for enterprise operators**.
+
+This doc explains **why** each primitive exists and **what it buys your team**. The protocol reference lives at [`docs/SKILLS_MCP_DISCOVERY.md`](../../../../docs/SKILLS_MCP_DISCOVERY.md) at the repo level; this file is written for the human and the agent who are about to operate inside the workspace you just exported.
+
+> TL;DR — The primitives turn a folder of files into a **coordinated execution substrate** that Claude, Cursor, Codex, and custom harnesses all read the same way, that remembers what has happened across sessions, and that refuses to run away on a retry loop.
+
+---
+
+## The problem these primitives solve
+
+Most agent stacks give you one of:
+
+- a raw repo an agent can edit, with no governance;
+- a prompt pack that works once and then decays;
+- a hosted product that locks your customisation behind a vendor.
+
+None of those scale to enterprise work where many agents, many sessions, and many operators act on the same substrate over time. You need a **workspace** that is:
+
+- **discoverable** — agents know what's here without reading everything
+- **continuous** — day 3 of a brief remembers day 1
+- **bounded** — a broken generation doesn't loop forever
+- **auditable** — every material change produces a receipt a human can review
+- **composable** — heavy work spawns into its own lane without poisoning the parent context
+- **safe** — side-effecting shell calls are reviewable files, not one-off prompts
+
+The six primitives below each answer one of those needs, and the Growthub SDK (`@growthub/api-contract/skills`) is the capability-agnostic contract that lets every worker kit, every fork, and every agent harness read them the same way.
+
+---
+
+## 1. `SKILL.md` — The Discovery Entry
+
+**What it is.** A single file at the root of every kit with YAML frontmatter (`name`, `description`, `triggers`, `sessionMemory`, `selfEval`, `helpers`, `subSkills`, `mcpTools`) and a short markdown routing body.
+
+**Why it exists.** Claude / Cursor / Codex agents scan the frontmatter at session start to catalog what's available — they do **not** load the full runbook (`skills.md`) until the user actually engages the skill. That cuts token cost on discovery and lets an agent know, within milliseconds, that your workspace has a Creative Strategist, a Hyperframes studio, and a Postiz social scheduler available — without reading a single line of the detailed operator runbook.
+
+**What it buys you.**
+- Agents route faster and more predictably across many kits.
+- A new team member (or a fresh agent session) gets oriented without re-explaining the repo.
+- Cross-agent compatibility is automatic — the same `SKILL.md` is read identically by Claude, Cursor, Codex, and custom harnesses.
+
+**Enterprise use case.** A creative ops team with 30 worker kits across 6 brands can expose all 30 to every agent surface in the org without a custom integration per tool. The manifest *is* the integration.
+
+---
+
+## 2. Symlinked Pointer — AGENTS.md as Single Source of Truth
+
+**What it is.** The repo root has exactly one authoritative agent contract (`AGENTS.md`). `CLAUDE.md` and `.cursorrules` are plain-text pointers that say "see AGENTS.md". No duplicated rules, no drift.
+
+**Why it exists.** Multi-agent environments drift the second a rule lives in two places. Someone updates the Cursor file and forgets the Claude file. The pointer pattern makes that impossible: there is only one file to edit.
+
+**What it buys you.**
+- Agent rules updated in one place, picked up by every surface on next session load.
+- Audit is simpler — reviewers look at one file, not three.
+- Cross-OS safety — pointer files work on Windows clones where symlinks don't.
+
+**Enterprise use case.** Compliance or InfoSec can sign off on one agent-behaviour file; no more "but the Cursor rules differ from the Claude rules" gaps.
+
+---
+
+## 3. `.growthub-fork/project.md` — Session Memory
+
+**What it is.** A human-readable, append-only journal seeded inside the fork's governed state directory (alongside `fork.json`, `policy.json`, `trace.jsonl`, optional `authority.json`). Written by the CLI at init/import time from the kit's `templates/project.md`.
+
+**Why it exists.** The machine-readable `trace.jsonl` is perfect for systems to replay history, but it is lossy to humans. `project.md` is the narrative layer — "what we tried, what we approved, what we rejected, where we stopped" — so the next session (yours or another agent's) can resume without re-explaining.
+
+**What it buys you.**
+- Day 3 of a multi-day brief opens with yesterday's context already in scope.
+- Approvals, rejections, and self-eval outcomes are preserved across handoffs.
+- Operators who return to a workspace after a month see exactly where work paused.
+
+**Enterprise use case.** Hand-offs between a contract creative team and an in-house team stop losing context. An agent in the in-house session reads the last 3 entries in `project.md` and picks up where the contractor left off.
+
+---
+
+## 4. Self-Evaluation — Bounded Retry Loop
+
+**What it is.** Every `SKILL.md` declares `selfEval.criteria[]` (what good looks like) and `selfEval.maxRetries` (default `3`). The agent runs `generate → apply → evaluate → record`, records each attempt to both `project.md` and `trace.jsonl`, and **must stop** when it hits the retry ceiling. The CLI primitive `recordSelfEval()` (`cli/src/skills/self-eval.ts`) is the single place that writes both surfaces.
+
+**Why it exists.** Unbounded agent loops are the #1 source of cost overruns and silent failures. A governed self-eval contract guarantees every attempt is observable *and* gives the agent a principled stopping point.
+
+**What it buys you.**
+- Runaway jobs are impossible — the ceiling is enforced in the bookkeeping primitive.
+- Every retry produces a receipt a human can read.
+- The Fork Sync Agent's existing `preview → apply → trace` loop is reused, not reinvented — so operators who already trust Fork Sync get the same governance here.
+
+**Enterprise use case.** A marketing ops team approves "at most 3 retries per creative unit" as policy. The SDK enforces it. Failed attempts surface in `project.md` immediately; nobody has to write a watchdog.
+
+---
+
+## 5. Sub-Skills — Parallel Agent Lanes
+
+**What it is.** A kit can declare nested skills under `<kit>/skills/<slug>/SKILL.md`. The parent skill spawns a sub-agent for a sub-skill when the work is (a) heavy enough to pollute the parent's context, or (b) narrow enough to benefit from a specialist lane. Both parent and sub-skill share the same `project.md` journal — so the parent reads the sub-agent's outcome on return without losing continuity.
+
+**Why it exists.** Heavy work (frame extraction, Manim render, PIL compositing, audit passes) shouldn't share the parent's context budget. And specialist work is easier to govern as its own unit.
+
+**What it buys you.**
+- Lower token cost on the parent — the parent stays focused on the user-facing artifact.
+- Clean audit trail — each sub-skill run appends to `project.md::subSkillRuns` with its own start/result.
+- Reusable lanes — a sub-skill like `frame-analysis` can be shared across multiple parent kits.
+
+**Enterprise use case.** Video / creative pipelines get the EDL-per-cut pattern as a sub-skill spawned by the parent brief skill, while non-video kits (CRM, email, SEO) stay on a simple flat loop — one SDK, both patterns, same governance.
+
+---
+
+## 6. `helpers/` — Safe Shell Tool Layer
+
+**What it is.** Small, deterministic scripts (`helpers/<verb>.{sh,mjs,py}`) that agents invoke via one shell call instead of reconstructing a raw pipeline inline.
+
+**Why it exists.** Raw shell in a prompt is fragile, unreviewable, and drifts every session. Moving the same snippets into reviewable files in the kit makes them (a) inspectable, (b) testable, (c) safer — and agents read *one line* ("run helpers/grep-hooks.sh") instead of reconstructing a 4-line pipeline.
+
+**What it buys you.**
+- Reliability — the same inputs always produce the same outputs.
+- Reviewable by security — helpers live in the repo and diff cleanly.
+- Lower cognitive load for agents — one invocation is easier than four.
+
+**Enterprise use case.** A security review of your agent workflow doesn't require reading agent transcripts — it reads the `helpers/` folder once. That's the full list of side-effecting operations.
+
+---
+
+## How the primitives compose: the export guarantee
+
+Every kit export (`scripts/export-worker-kit.mjs --qa`) asserts all six primitives are present before shipping. The assertions are:
+
+1. `SKILL.md` exists with well-formed frontmatter (`name`, `description`).
+2. `templates/project.md` exists (session memory seed).
+3. `templates/self-eval.md` exists (self-eval pattern).
+4. `helpers/README.md` exists (safe-shell convention).
+5. `skills/README.md` exists (sub-skill convention).
+6. `kit.json.frozenAssetPaths` declares all five paths.
+
+A kit that forgets any of these **cannot ship** — the export script refuses to produce a bundle. That guarantee is what makes the primitive layer trustworthy at scale: every workspace your team exports will have them, every time.
+
+---
+
+## How to operate inside this workspace
+
+1. **At session start.** Read `.growthub-fork/project.md` (what happened last time) → `SKILL.md` (what's here) → `skills.md` (how to do the work).
+2. **During work.** After every material change, write a dated bullet to `project.md`'s "Session log" AND call `appendKitForkTraceEvent` for the machine log. The CLI primitive `recordSelfEval` does both in one call — use it.
+3. **On retry.** Every attempt goes to both surfaces. At `attempt === maxRetries`, park with a `needs_confirmation` note and stop.
+4. **On heavy work.** Spawn a sub-skill from `skills/<slug>/` when context isolation helps. The sub-skill shares this fork's `project.md` — no separate journal.
+5. **On side effects.** Use a helper from `helpers/`. If you're about to write raw shell for the third time, promote it to a helper first.
+
+---
+
+## Command surface from inside the workspace
+
+```bash
+# Catalog every SKILL.md reachable from here (root + nested sub-skills)
+growthub skills list [--json]
+
+# Strict shape check — frontmatter + helper/sub-skill path existence
+growthub skills validate
+
+# Read the session memory for this fork
+growthub skills session show [--body]
+
+# (Re-)seed the session memory if it is missing
+growthub skills session init [--kit <id>]
+```
+
+## What this substrate is NOT
+
+- **Not a sandbox.** It's a set of conventions. The filesystem is still yours to edit.
+- **Not a lock-in.** Every primitive file is plain markdown or JSON — readable without Growthub tooling.
+- **Not a replacement for policy.** `policy.json` and the Fork Sync Agent remain the safety envelope. The primitives ride on top.
+- **Not capability-specific.** The SDK contract (`@growthub/api-contract/skills::SkillSelfEval`) is intentionally agnostic. Creative, code, content, CRM, social, audit — all specialise inside their own `skills.md` without changing the contract.
+
+---
+
+## Further reading
+
+- [`../SKILL.md`](../SKILL.md) — the discovery entry for this kit
+- [`../skills.md`](../skills.md) — the operator runbook (the deep how-to)
+- [`../workers/agency-portal-operator/CLAUDE.md`](../workers/agency-portal-operator/CLAUDE.md) — the worker agent contract
+- [`../templates/project.md`](../templates/project.md) — session-memory template
+- [`../templates/self-eval.md`](../templates/self-eval.md) — self-evaluation template
+- [`../helpers/README.md`](../helpers/README.md) — safe-shell convention
+- [`../skills/README.md`](../skills/README.md) — sub-skill convention
+- Repo-level protocol reference: `docs/SKILLS_MCP_DISCOVERY.md`
+- SDK source of truth: `@growthub/api-contract/skills`

package/assets/worker-kits/growthub-agency-portal-starter-v1/docs/starter-kit-overview.md

@@ -0,0 +1,30 @@
+# Agency Portal Starter Kit — Overview
+
+The Growthub Agency Portal Starter Kit specializes the custom workspace starter primitive into a first-party agency portal workspace. It combines:
+
+1. **Governed workspace substrate** — kit manifest, frozen assets, brand scaffolds, setup, templates, docs, growthub-meta, session memory, self-eval, helpers, and sub-skill conventions.
+2. **Vite-bundled local shell** — a React + Vite studio at `studio/` that remains the Growthub Local operator surface.
+3. **Vercel-ready app payload** — a Next.js app at `apps/agency-portal/` with adapter-first persistence, auth, and payment contracts.
+4. **First-class Self-Healing Fork Sync Agent wiring** — exports register as kit-forks with policy, trace, and a dedicated `forkId`.
+
+## Why a dedicated primitive
+
+Users who want a production agency portal should not inherit a provider-locked app as their worker-kit contract. This kit gives them:
+
+- A governed workspace that satisfies every custom-workspace kernel invariant.
+- Local-first operation through the Vite shell.
+- Clean Vercel deployment through `apps/agency-portal/`.
+- Configurable persistence through Postgres, Qstash KV, or provider-managed adapters.
+- An auto-registered fork with policy, trace, and (optionally) a GitHub remote.
+- A guaranteed upgrade path back to upstream via the Self-Healing Fork Sync Agent.
+
+## End-to-end flow
+
+```
+growthub kit download growthub-agency-portal-starter-v1 --out ./exports
+  └→ copyBundledKitSource('growthub-agency-portal-starter-v1', './my-workspace')
+  └→ registerKitFork({ forkPath: './my-workspace', kitId: '...', baseVersion: '1.0.0' })
+  └→ writeKitForkPolicy(forkPath, default)
+  └→ appendKitForkTraceEvent(forkPath, 'registered')
+  └→ (optional) growthub kit fork create --upstream owner/repo  → GitHub remote
+```

package/assets/worker-kits/growthub-agency-portal-starter-v1/docs/vercel-serverless-deployment.md

@@ -0,0 +1,46 @@
+# Vercel Serverless Deployment
+
+The clean cloud deployment lane is the app payload:
+
+```text
+apps/agency-portal/
+```
+
+The Growthub local-first workspace remains the kit root, and the Vite operator shell remains:
+
+```text
+studio/
+```
+
+## Vercel project settings
+
+- Root directory: `apps/agency-portal`
+- Build command: `npm run build`
+- Install command: `npm install`
+- Framework preset: Next.js
+
+## Required adapter env
+
+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>
+```
+
+Then set the provider-specific env required by `docs/adapter-contracts.md`.
+
+For hosted Growthub authority, set:
+
+```text
+GROWTHUB_BRIDGE_BASE_URL=<growthub-gh-app-url>
+GROWTHUB_BRIDGE_INTEGRATIONS_PATH=/api/mcp/accounts
+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.

package/assets/worker-kits/growthub-agency-portal-starter-v1/docs/vite-ui-shell-guide.md

@@ -0,0 +1,24 @@
+# Starter Kit — Vite UI Shell Guide
+
+The `studio/` directory ships a minimal Vite 5 + React 18 shell. It is intentionally tiny — a single `App.jsx` view that introspects the fork state.
+
+## Extend it
+
+Add views under `studio/src/views/<Name>.jsx`. Import them in `App.jsx`. Vite's hot-module-replacement handles the dev loop; the Self-Healing Fork Sync Agent treats any file you add under `studio/src/` as user-authored (it may still update upstream-owned files in `studio/src/` — protect yours via `policy.untouchablePaths`).
+
+## Build + serve
+
+```bash
+cd studio
+npm install
+npm run dev          # dev server
+npm run build        # production build -> studio/dist
+node serve.mjs       # serve studio/dist on localhost
+```
+
+## Why Vite, not Next.js
+
+- Zero server coupling — a static `dist/` directory ships anywhere.
+- Fast dev loop (HMR).
+- No vendor lock-in at the framework level.
+- Mirrors the pattern already in production for `growthub-zernio-social-v1`.

package/assets/worker-kits/growthub-agency-portal-starter-v1/examples/portal-brief-sample.md

@@ -0,0 +1,44 @@
+# Portal Brief Sample
+
+Client: Acme Growth Studio  
+Workspace: agency-portal-v1  
+Goal: operate client reporting, task follow-up, and campaign visibility from a governed Growthub worker-kit fork.
+
+## Runtime Choice
+
+- Local operator shell: `studio/`
+- Deployable app: `apps/agency-portal/`
+- Vercel root: `apps/agency-portal`
+- GitHub/Vercel deployment: connected through the user's normal GitHub and Vercel project flow.
+
+## Adapter Choice
+
+- Persistence: `provider-managed`
+- Auth: `provider-managed`
+- Payments: `none`
+- Integrations: `growthub-bridge`
+- Reporting: `windsor`
+
+## Data Pipeline Objects
+
+- Windsor AI: connected through Growthub bridge.
+- Google Sheets blended data: enabled as the Windsor blended data destination.
+- Google Analytics: active through GH app MCP connection authority.
+- Shopify: active through GH app MCP connection authority.
+- Meta Facebook/Instagram: active through GH app MCP connection authority.
+
+## MCP Connection Integrations
+
+- Asana: active.
+- Slack: active.
+- GoHighLevel: pending.
+- Google Drive: active.
+- Notion: pending.
+
+## Production Readiness
+
+- `node setup/verify-env.mjs` passes.
+- `studio/` builds.
+- `apps/agency-portal/` builds.
+- `/settings/integrations` shows active badges for bridge-returned connections.
+- `growthub kit fork status <fork-id>` has been captured in `output/acme/agency-portal-v1/trace-summary.md`.

package/assets/worker-kits/growthub-agency-portal-starter-v1/examples/workspace-sample.md

@@ -0,0 +1,10 @@
+# Workspace Sample — Reference Output
+
+A worked example of the artifact shape a finished workspace produces. Use this as a comparison benchmark when validating a custom workspace run.
+
+- Client: growthub
+- Project slug: starter-reference
+- Goals: (1) demonstrate the starter contract; (2) validate fork-sync wiring; (3) produce a minimal but complete workspace tree
+- First heal checkpoint: `status_ran` at registration, overall severity = none.
+
+See `output/growthub/starter-reference/` after running the starter init + first heal.

package/assets/worker-kits/growthub-agency-portal-starter-v1/growthub-meta/README.md

@@ -0,0 +1,11 @@
+# Growthub Meta — growthub-agency-portal-starter-v1
+
+Upstream-owned metadata that travels with the agency portal starter kit. Do not edit these files in a fork unless the change is intentionally part of the upstream kit contract.
+
+| Field | Value |
+|---|---|
+| Kit ID | `growthub-agency-portal-starter-v1` |
+| Worker ID | `agency-portal-operator` |
+| Local shell | `studio/` |
+| Vercel app | `apps/agency-portal/` |
+| Adapter contract | `docs/adapter-contracts.md` |

package/assets/worker-kits/growthub-agency-portal-starter-v1/growthub-meta/kit-standard.md

@@ -0,0 +1,16 @@
+# Kit Standard — growthub-agency-portal-starter-v1
+
+This starter is a custom-workspace-derived agency portal worker kit with:
+
+- `schemaVersion: 2` in `kit.json`
+- `family: "studio"`
+- `executionMode: "export"`
+- `activationModes: ["export"]`
+
+Every bundled worker kit under `cli/assets/worker-kits/` conforms to the same shape. See `docs/kernel-packets/KERNEL_PACKET_CUSTOM_WORKSPACES.md` for the full invariant list.
+
+Additional invariants:
+
+- `studio/` remains the local-first Vite operator shell.
+- `apps/agency-portal/` remains the Vercel app payload.
+- Persistence/auth/payment selection stays behind adapter env and docs.