@growthub/cli 0.3.52 → 0.3.53

package/assets/worker-kits/growthub-geo-seo-v1/.env.example

@@ -0,0 +1,12 @@
+# Growthub GEO SEO Studio — Environment Config
+# Copy this file to .env and fill in your values.
+# Never commit .env to version control.
+
+# Path to your local clone of the geo-seo-claude fork
+# Default is ~/geo-seo-claude — only set this if your fork is elsewhere
+# GEO_SEO_FORK_PATH=/path/to/your/geo-seo-claude
+
+# Anthropic API key — required for agent-enhanced analysis (Steps 5-9)
+# Core Python audit commands work without this key
+# Get one at https://console.anthropic.com
+ANTHROPIC_API_KEY=your_anthropic_key_here

package/assets/worker-kits/growthub-geo-seo-v1/QUICKSTART.md

@@ -0,0 +1,138 @@
+# Growthub GEO SEO Studio — Quickstart
+
+**Kit:** `growthub-geo-seo-v1`
+**Worker:** `geo-seo-operator`
+**Tool:** [geo-seo-claude](https://github.com/zubair-trabzada/geo-seo-claude)
+
+---
+
+## What This Kit Does
+
+The Growthub GEO SEO Studio is a self-contained AI agent environment that audits websites for AI search visibility, citability, and traditional SEO health. It wraps the open-source `geo-seo-claude` tool to produce:
+
+- GEO Scores (0–100 composite score across 6 components)
+- Citability analyses (5-metric algorithm measuring AI quotability)
+- AI crawler permission reports (14 major crawlers)
+- Brand visibility reports (8 platforms)
+- llms.txt implementation plans
+- 4-week remediation roadmaps
+- Client-ready PDF reports
+
+---
+
+## Setup — 6 Steps
+
+### Step 1 — Point Your Working Directory
+
+Export this kit to a local folder and point Claude Code's Working Directory at the kit root. All paths in the kit are relative to the kit root.
+
+### Step 2 — Copy the Environment File
+
+```bash
+cp .env.example .env
+```
+
+No API keys are required for core analysis. Python and Playwright handle all data collection locally. If you want agent-enhanced analysis, add your `ANTHROPIC_API_KEY` to `.env`.
+
+### Step 3 — Verify the Environment
+
+```bash
+node setup/verify-env.mjs
+```
+
+This checks:
+- Whether `geo-seo-claude` is cloned at `GEO_SEO_FORK_PATH` (default: `~/geo-seo-claude`)
+- Whether key Python scripts exist in the fork
+- Whether `ANTHROPIC_API_KEY` is valid format (if set)
+- No network calls are made during verification
+
+### Step 4 — Check Dependencies
+
+```bash
+bash setup/check-deps.sh
+```
+
+Verifies that `python3`, `pip`, `playwright`, `git`, and `node` are available. Checks Python version (3.8+ required). Checks Playwright chromium browser is installed.
+
+### Step 5 — Clone and Install the Fork (Local-Fork Mode Only)
+
+```bash
+bash setup/clone-fork.sh
+```
+
+This clones `geo-seo-claude` to `~/geo-seo-claude` (or `GEO_SEO_FORK_PATH` if set), runs `pip install -r requirements.txt`, and installs Playwright chromium.
+
+Skip this step if you are using **agent-only mode** — the operator can perform analysis without the local fork.
+
+### Step 6 — Start a Session
+
+Open Claude Code, set the Working Directory to this kit root, and start your session. The operator will guide you through the 10-step workflow.
+
+---
+
+## Execution Modes
+
+| Mode | Requirements | Use When |
+|---|---|---|
+| `local-fork` | Python 3.8+, Playwright, geo-seo-claude cloned | You want the full tool stack — Python scripts, PDF generation, real crawl data |
+| `agent-only` | Nothing — Claude handles everything | You need a quick analysis and don't have the fork installed |
+| `hybrid` | ANTHROPIC_API_KEY + fork | Best of both — agent reasoning with Python data collection |
+
+---
+
+## First Run
+
+1. Tell the operator: **"Run a full GEO audit on [your domain]"**
+2. The operator will ask 3 clarifying questions (target URL, scope, delivery format)
+3. The operator runs the 10-step workflow and produces all audit artifacts
+4. Output is saved to `output/<client-slug>/<project-slug>/`
+
+---
+
+## New Client Setup
+
+See `brands/NEW-CLIENT.md` for instructions on adding a new client brand kit.
+
+Quick version:
+```bash
+cp brands/_template/brand-kit.md brands/<client-slug>/brand-kit.md
+# Then fill in the fields in the new file
+```
+
+---
+
+## Available Commands
+
+The geo-seo-claude tool provides 14 commands. Tell the operator which you need:
+
+| Command | What It Does |
+|---|---|
+| `/geo audit` | Full GEO + SEO audit — all components |
+| `/geo citability` | Citability score only |
+| `/geo crawlers` | AI crawler permission check |
+| `/geo brands` | Brand mention and authority scan |
+| `/geo report` | Structured Markdown report |
+| `/geo report-pdf` | Branded PDF report |
+| `/geo content` | E-E-A-T and content quality |
+| `/geo schema` | Structured data validation |
+| `/geo technical` | Server headers and technical health |
+| `/geo llmstxt` | Generate llms.txt plan |
+| `/geo quick` | 60-second AI visibility snapshot |
+| `/geo proposal` | Client proposal with pricing |
+| `/geo prospect` | Prospect qualification scan |
+| `/geo compare` | Side-by-side URL comparison |
+
+---
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `workers/geo-seo-operator/CLAUDE.md` | Agent operating instructions (start here) |
+| `skills.md` | Full methodology — read at every session |
+| `brands/_template/brand-kit.md` | Blank brand kit template |
+| `brands/growthub/brand-kit.md` | Growthub reference example |
+| `output/README.md` | Output directory structure and naming |
+| `docs/geo-seo-fork-integration.md` | How this kit integrates with geo-seo-claude |
+| `docs/scoring-methodology.md` | GEO Score formula and citability algorithm |
+| `validation-checklist.md` | Pre-session checklist |

package/assets/worker-kits/growthub-geo-seo-v1/brands/NEW-CLIENT.md

@@ -0,0 +1,104 @@
+# New Client Brand Kit Setup
+
+Follow these steps to add a new client to the GEO SEO Studio.
+
+---
+
+## Step 1 — Copy the Template
+
+```bash
+# Replace <client-slug> with the client's URL-safe slug (lowercase, hyphens only)
+cp brands/_template/brand-kit.md brands/<client-slug>/brand-kit.md
+```
+
+Examples:
+```bash
+cp brands/_template/brand-kit.md brands/urban-cycle/brand-kit.md
+cp brands/_template/brand-kit.md brands/acme-saas/brand-kit.md
+cp brands/_template/brand-kit.md brands/coastal-dental/brand-kit.md
+```
+
+---
+
+## Step 2 — Fill In Required Fields
+
+Open `brands/<client-slug>/brand-kit.md` and fill in all fields. The required fields are:
+
+| Field | Location | Why It Matters |
+|---|---|---|
+| `client_name` | IDENTITY | Used in all output file names and reports |
+| `slug` | IDENTITY | Must match the directory name — used in output paths |
+| `industry` | IDENTITY | Context for tone calibration and benchmark comparison |
+| `primary_service` | IDENTITY | What GEO/SEO work is being done |
+| `date_onboarded` | IDENTITY | Tracks when the engagement started |
+| `account_owner` | IDENTITY | Who is responsible for this account |
+| `target_persona.pain_point` | AUDIENCE | Drives messaging tone in proposals and reports |
+| `geographic_target` | AUDIENCE | Informs platform and language scope |
+| `core_message` | MESSAGING | Used in client proposals |
+| `tone` | MESSAGING | Calibrates how the operator writes client-facing content |
+| `target_url` | AUDIT SCOPE | The domain to audit |
+| `audit_type` | AUDIT SCOPE | quick / full / report / specific-command |
+| `delivery_format` | AUDIT SCOPE | markdown / pdf / both |
+| `prospect_stage` | AGENCY CONTEXT | discovery / proposal-sent / active / etc. |
+
+Optional but recommended:
+- `competitor_urls` — enables `/geo compare` command
+- `monthly_retainer_range` — appears in proposals
+- `crm_notes` — any notes about the account
+
+---
+
+## Step 3 — Tell the Agent to Use It
+
+At the start of your session, tell the GEO SEO Operator:
+
+> "Use the brand kit at brands/<client-slug>/brand-kit.md for this session."
+
+Or the operator will automatically look for `brands/<client-slug>/brand-kit.md` based on the client name you provide.
+
+---
+
+## Step 4 — Update the Deliverables Log
+
+After each audit package is delivered, append a line to the brand kit's DELIVERABLES LOG:
+
+```
+- YYYY-MM-DD | GEO SEO Audit Package v<N> — <Project Name> | output/<client-slug>/<project-slug>/
+```
+
+The operator will do this automatically at Step 10 of the workflow.
+
+---
+
+## Multiple Clients
+
+Each client gets its own subdirectory under `brands/`:
+
+```
+brands/
+  _template/
+    brand-kit.md          ← blank template — never fill this in
+  growthub/
+    brand-kit.md          ← Growthub internal reference example
+  urban-cycle/
+    brand-kit.md          ← client brand kit
+  acme-saas/
+    brand-kit.md          ← client brand kit
+  NEW-CLIENT.md           ← this file
+```
+
+Do not modify `brands/_template/brand-kit.md` — it is the frozen template. Always copy it before filling in client details.
+
+---
+
+## Brand Kit Field Reference
+
+| Section | Fields |
+|---|---|
+| IDENTITY | client_name, slug, industry, primary_service, campaign_name, date_onboarded, account_owner |
+| AUDIENCE | target_persona (role, company_type, pain_point, intent), geographic_target, do_not_attract |
+| MESSAGING | core_message, tone, approved_phrases, messaging_guardrails, cta_text |
+| BRAND DESIGN | colors (primary, secondary, accent, dark, white), fonts, logo_file, logo_on_dark |
+| AUDIT SCOPE | target_url, competitor_urls, audit_type, delivery_format |
+| AGENCY CONTEXT | monthly_retainer_range, prospect_stage, crm_notes |
+| DELIVERABLES LOG | Running log of all delivered audit packages |

package/assets/worker-kits/growthub-geo-seo-v1/brands/_template/brand-kit.md

@@ -0,0 +1,116 @@
+# Brand Kit — [CLIENT NAME]
+
+> Copy to `brands/<client-slug>/brand-kit.md` and fill in all fields before producing outputs.
+> The GEO SEO Operator reads this file at Step 1 of every session.
+
+---
+
+## IDENTITY
+
+```yaml
+client_name: ""                # Full legal or trading name
+slug: ""                       # URL-safe slug, lowercase, hyphens only (e.g., "urban-cycle")
+industry: ""                   # Industry category (e.g., "e-commerce — electric bikes")
+primary_service: ""            # What GEO/SEO work is being done (e.g., "GEO + SEO audit and AI search visibility remediation")
+campaign_name: ""              # This engagement's name (e.g., "Q2 2026 AI Search Launch Audit")
+date_onboarded: ""             # YYYY-MM-DD
+account_owner: ""              # Growthub team member responsible for this account
+```
+
+---
+
+## AUDIENCE
+
+```yaml
+target_persona:
+  role: ""                     # Job title or role of the ideal website visitor / buyer
+  company_type: ""             # e.g., "DTC e-commerce brand", "B2B SaaS", "local service business"
+  pain_point: ""               # What they are struggling with (e.g., "losing organic traffic to AI search answers")
+  intent: ""                   # What they are trying to accomplish (e.g., "rank in AI-generated answers, not just Google blue links")
+
+geographic_target: ""          # e.g., "US, Canada, UK" or "Local — Chicago metro"
+
+do_not_attract:                # Who we are NOT trying to reach with this content
+  - ""
+  - ""
+```
+
+---
+
+## MESSAGING
+
+```yaml
+core_message: ""               # One sentence: what does this brand want to be known for in AI search?
+
+tone:                          # 3–5 adjectives describing the brand voice
+  - ""
+  - ""
+  - ""
+
+approved_phrases:              # Phrases that are on-brand and should appear in content
+  - ""
+  - ""
+  - ""
+
+messaging_guardrails:          # What NOT to say — claims to avoid, topics to sidestep
+  - ""
+  - ""
+
+cta_text: ""                   # Primary call-to-action (e.g., "Start your free GEO audit")
+```
+
+---
+
+## BRAND DESIGN
+
+```yaml
+colors:
+  primary: ""                  # Hex code (e.g., "#1A1A2E")
+  secondary: ""                # Hex code
+  accent: ""                   # Hex code
+  dark: ""                     # Hex code — for dark backgrounds
+  white: ""                    # Hex code — for light backgrounds (usually #FFFFFF)
+
+fonts:
+  heading: ""                  # Font name (e.g., "Inter Bold")
+  body: ""                     # Font name (e.g., "Inter Regular")
+
+logo_file: ""                  # Path to logo file (e.g., "brands/<slug>/assets/logo.png")
+logo_on_dark: ""               # Path to reversed logo for dark backgrounds
+```
+
+---
+
+## AUDIT SCOPE
+
+```yaml
+target_url: ""                 # Primary URL to audit (e.g., "https://domain.com")
+
+competitor_urls:               # Competitor domains for comparison — fill per engagement
+  - ""
+  - ""
+  - ""
+
+audit_type: ""                 # quick | full | report | specific-command
+
+delivery_format: ""            # markdown | pdf | both
+```
+
+---
+
+## AGENCY CONTEXT
+
+```yaml
+monthly_retainer_range: ""     # e.g., "$2,500–$4,000/month" or "N/A — project only"
+prospect_stage: ""             # discovery | proposal-sent | active | paused | churned | internal
+crm_notes: ""                  # Free text — any notes about the account, deal status, key contacts
+```
+
+---
+
+## DELIVERABLES LOG
+
+> Append a line here each time an audit package is delivered.
+> Format: `- YYYY-MM-DD | GEO SEO Audit Package v<N> — <Project Name> | output/<client-slug>/<project-slug>/`
+
+<!-- No deliverables yet. First entry goes here. -->

package/assets/worker-kits/growthub-geo-seo-v1/brands/growthub/brand-kit.md

@@ -0,0 +1,117 @@
+# Brand Kit — Growthub
+
+> Internal reference brand kit. Used as the example for all GEO SEO Studio demos and reference audits.
+
+---
+
+## IDENTITY
+
+```yaml
+client_name: "Growthub"
+slug: "growthub"
+industry: "AI-enabled growth infrastructure and creative operations"
+primary_service: "GEO + SEO audit and remediation for AI search visibility"
+campaign_name: "Studio Launch Reference Audit"
+date_onboarded: "2026-04-14"
+account_owner: "Antonio"
+```
+
+---
+
+## AUDIENCE
+
+```yaml
+target_persona:
+  role: "Growth lead, Head of Marketing, or Founder at a digital-native brand or agency"
+  company_type: "DTC e-commerce, B2B SaaS, or marketing agency — 10–200 employees"
+  pain_point: "Organic traffic is declining as AI search answers replace blue-link clicks. They have no strategy for AI search visibility."
+  intent: "Understand where they stand in AI search, fix the gaps, and capture AI-referred traffic before competitors do."
+
+geographic_target: "US, Canada, UK, Australia — English-language markets"
+
+do_not_attract:
+  - "Solo freelancers with no marketing budget"
+  - "Enterprise companies requiring procurement cycles >90 days"
+  - "Clients seeking black-hat SEO tactics"
+```
+
+---
+
+## MESSAGING
+
+```yaml
+core_message: "Growthub helps growth-focused brands become citable, visible, and recommended by AI search systems — not just Google."
+
+tone:
+  - "Direct"
+  - "Technical"
+  - "Confident"
+  - "Data-grounded"
+  - "No-fluff"
+
+approved_phrases:
+  - "AI search visibility"
+  - "GEO Score"
+  - "citability"
+  - "AI-referred traffic"
+  - "worker kit"
+  - "remediation roadmap"
+  - "crawlable, citable, and optimized"
+
+messaging_guardrails:
+  - "Do not promise specific traffic or ranking outcomes — frame as projections based on audit data"
+  - "Do not call it 'SEO' alone — always pair with 'GEO' to signal AI search differentiation"
+  - "Do not claim to game AI systems — frame work as making content genuinely better for AI citation"
+
+cta_text: "Get your free GEO Score"
+```
+
+---
+
+## BRAND DESIGN
+
+```yaml
+colors:
+  primary: "#1A1A2E"           # Deep navy — primary brand color
+  secondary: "#16213E"         # Darker navy — backgrounds
+  accent: "#E94560"            # Red-coral — CTAs, highlights
+  dark: "#0F3460"              # Dark blue — section backgrounds
+  white: "#EAEAEA"             # Off-white — body text on dark
+
+fonts:
+  heading: "Inter Bold"
+  body: "Inter Regular"
+
+logo_file: "brands/growthub/assets/logo.png"
+logo_on_dark: "brands/growthub/assets/logo-white.png"
+```
+
+---
+
+## AUDIT SCOPE
+
+```yaml
+target_url: "https://thegrowthub.com"
+
+competitor_urls:
+  - ""                         # Fill per engagement — no standing competitors for internal reference
+
+audit_type: "full"
+delivery_format: "both"
+```
+
+---
+
+## AGENCY CONTEXT
+
+```yaml
+monthly_retainer_range: "Internal reference — not sold externally for this domain"
+prospect_stage: "Internal"
+crm_notes: "This is the Growthub reference brand kit. Used for all studio demos, kit examples, and internal reference audits. Do not use as a template for external clients — copy brands/_template/brand-kit.md instead."
+```
+
+---
+
+## DELIVERABLES LOG
+
+- 2026-04-14 | GEO SEO Audit Package v1 — Studio Launch Reference | output/growthub/studio-launch-reference/

package/assets/worker-kits/growthub-geo-seo-v1/bundles/growthub-geo-seo-v1.json

@@ -0,0 +1,54 @@
+{
+  "schemaVersion": 2,
+  "bundle": {
+    "id": "growthub-geo-seo-v1",
+    "version": "1.0.0",
+    "kitId": "growthub-geo-seo-v1",
+    "workerId": "geo-seo-operator"
+  },
+  "briefType": "geo-seo-audit",
+  "publicExampleBrandPaths": ["brands/growthub/brand-kit.md"],
+  "requiredFrozenAssets": [
+    "QUICKSTART.md",
+    ".env.example",
+    "skills.md",
+    "output-standards.md",
+    "runtime-assumptions.md",
+    "validation-checklist.md",
+    "workers/geo-seo-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/geo-audit-brief.md",
+    "templates/citability-analysis.md",
+    "templates/crawler-access-report.md",
+    "templates/brand-visibility-report.md",
+    "templates/geo-score-summary.md",
+    "templates/content-analysis.md",
+    "templates/schema-validation.md",
+    "templates/technical-foundations.md",
+    "templates/llmstxt-plan.md",
+    "templates/remediation-roadmap.md",
+    "templates/client-proposal.md",
+    "examples/geo-audit-sample.md",
+    "examples/citability-sample.md",
+    "examples/pdf-report-sample.md",
+    "examples/prospect-proposal-sample.md",
+    "docs/geo-seo-fork-integration.md",
+    "docs/subagent-dispatch.md",
+    "docs/scoring-methodology.md",
+    "docs/pdf-report-layer.md",
+    "growthub-meta/README.md",
+    "growthub-meta/kit-standard.md"
+  ],
+  "optionalPresets": [],
+  "export": {
+    "folderName": "growthub-agent-worker-kit-geo-seo-v1",
+    "zipFileName": "growthub-agent-worker-kit-geo-seo-v1.zip"
+  },
+  "activationModes": ["export"]
+}