@growthub/cli 0.3.52 → 0.3.53

package/assets/worker-kits/growthub-geo-seo-v1/docs/subagent-dispatch.md

@@ -0,0 +1,273 @@
+# Subagent Dispatch — 5-Parallel Orchestration
+
+---
+
+## Overview
+
+Phase 2 of the GEO audit runs 5 specialized subagents in parallel. Each subagent receives the Phase 1 fetch data as input and returns a component score (0–100) plus a findings list. The operator synthesizes all 5 results into the composite GEO Score.
+
+---
+
+## When Phase 2 Triggers
+
+Phase 2 begins after Phase 1 fetch completes successfully.
+
+**Phase 1 required outputs (all must be present before dispatching):**
+
+- robots.txt contents (or confirmed 404)
+- llms.txt status (present/missing/malformed)
+- Rendered page HTML
+- HTTP response headers
+- Page word count and heading structure
+- JSON-LD structured data (or confirmed absent)
+
+If Phase 1 fails to fetch the target URL entirely (connection refused, server error), stop and report the error. Do not dispatch Phase 2 with no data.
+
+If Phase 1 produces partial data (e.g., llms.txt returns 404), dispatch Phase 2 anyway and note the missing data in the relevant subagent's output.
+
+---
+
+## Subagent Definitions
+
+### 1. geo-ai-visibility
+
+**File:** `agents/geo-ai-visibility.md` (in fork)
+**Scope:** AI crawler access and citation format quality
+**GEO Score weight:** 25%
+
+**Inputs from Phase 1:**
+- robots.txt full text
+- llms.txt full text (or `null` if missing)
+- llms-full.txt status
+- X-Robots-Tag header value
+- Page canonical URL
+
+**What it evaluates:**
+
+| Signal | Method | Score Contribution |
+|---|---|---|
+| GPTBot access | Parse `User-agent: GPTBot` in robots.txt | High |
+| ClaudeBot access | Parse `User-agent: ClaudeBot` | High |
+| PerplexityBot access | Parse `User-agent: PerplexityBot` | High |
+| Google-Extended access | Parse `User-agent: Google-Extended` | High |
+| Bingbot access | Parse `User-agent: Bingbot` | Medium |
+| Applebot-Extended access | Parse `User-agent: Applebot-Extended` | Medium |
+| Anthropic-AI access | Parse `User-agent: anthropic-ai` | Medium |
+| cohere-ai access | Parse `User-agent: cohere-ai` | Medium |
+| Meta-ExternalFetcher access | Parse `User-agent: meta-externalagent` | Low |
+| YouBot access | Parse `User-agent: YouBot` | Low |
+| DuckAssistBot access | Parse `User-agent: DuckAssistBot` | Low |
+| Scrapy access | Parse `User-agent: Scrapy` | Low |
+| CCBot access | Parse `User-agent: CCBot` | Low |
+| ia_archiver access | Parse `User-agent: ia_archiver` | Low |
+| llms.txt present | File exists and returns 200 | High |
+| llms.txt valid format | No parsing errors | Medium |
+| llms-full.txt present | File exists | Medium |
+| Citation format quality | Clean canonical, no JS-only content walls | High |
+| X-Robots-Tag noai | Penalize heavily if present | Critical |
+
+**Output format:**
+```json
+{
+  "subagent": "geo-ai-visibility",
+  "score": 0-100,
+  "crawler_results": { "GPTBot": "allowed|blocked|partial", ... },
+  "llms_txt_present": true|false,
+  "llms_full_txt_present": true|false,
+  "top_findings": ["finding 1", "finding 2", "finding 3"]
+}
+```
+
+---
+
+### 2. geo-content
+
+**File:** `agents/geo-content.md` (in fork)
+**Scope:** E-E-A-T signals, answer block quality, content self-containment
+**GEO Score weight:** 20%
+
+**Inputs from Phase 1:**
+- Rendered page HTML (full text)
+- Page word count
+- Heading hierarchy (H1, H2, H3 counts)
+- Any author markup found
+
+**What it evaluates:**
+- Experience signals (case studies, original data, first-person examples)
+- Expertise signals (author bylines, credentials, domain terminology depth)
+- Authoritativeness signals (external citations, authority domain references)
+- Trustworthiness signals (HTTPS confirmed in Phase 1, contact info, privacy policy presence)
+- Answer block quality (5-metric citability algorithm — see `docs/scoring-methodology.md`)
+
+**Output format:**
+```json
+{
+  "subagent": "geo-content",
+  "score": 0-100,
+  "eeat_scores": { "experience": 0-10, "expertise": 0-10, "authoritativeness": 0-10, "trustworthiness": 0-10 },
+  "citability_score": 0-100,
+  "top_findings": ["finding 1", "finding 2", "finding 3"]
+}
+```
+
+---
+
+### 3. geo-platform-analysis
+
+**File:** `agents/geo-platform-analysis.md` (in fork)
+**Scope:** Readiness for 4 major AI search platforms
+**GEO Score weight:** 10%
+
+**Inputs from Phase 1:**
+- Page HTML structure
+- Schema markup found
+- llms.txt status (from geo-ai-visibility)
+- Content signals (from geo-content)
+
+**What it evaluates:**
+
+| Platform | Key Signals Checked |
+|---|---|
+| ChatGPT (Browse mode) | Clean URL, no crawler block, answer-block format, Bing indexability |
+| Perplexity AI | Direct URL crawlability, self-contained paragraphs, citation format |
+| Google AI Overviews | FAQPage schema, E-E-A-T signals, featured snippet optimization, structured data |
+| Gemini | Google entity graph signals, Knowledge Panel readiness, broad schema coverage |
+
+**Output format:**
+```json
+{
+  "subagent": "geo-platform-analysis",
+  "score": 0-100,
+  "platform_scores": {
+    "chatgpt": 0-100,
+    "perplexity": 0-100,
+    "google_ai_overviews": 0-100,
+    "gemini": 0-100
+  },
+  "top_findings": ["finding 1", "finding 2", "finding 3"]
+}
+```
+
+---
+
+### 4. geo-schema
+
+**File:** `agents/geo-schema.md` (in fork)
+**Scope:** Structured data coverage and validation
+**GEO Score weight:** 10%
+
+**Inputs from Phase 1:**
+- All JSON-LD blocks from page source
+- Microdata and RDFa markup (if present)
+- Page type determination
+
+**What it evaluates:**
+- Which schema types are present
+- Required property completeness for each type
+- Validation errors (missing required fields, incorrect value types)
+- Missing recommended schema types for the detected page type
+- Schema richness score (types × completeness)
+
+**Output format:**
+```json
+{
+  "subagent": "geo-schema",
+  "score": 0-100,
+  "types_found": ["Organization", "WebSite"],
+  "types_missing": ["FAQPage", "Article", "BreadcrumbList"],
+  "validation_errors": [
+    { "type": "Organization", "property": "contactPoint", "error": "missing required property" }
+  ],
+  "top_findings": ["finding 1", "finding 2", "finding 3"]
+}
+```
+
+---
+
+### 5. geo-technical
+
+**File:** `agents/geo-technical.md` (in fork)
+**Scope:** Technical SEO and server health
+**GEO Score weight:** 15%
+
+**Inputs from Phase 1:**
+- Full HTTP response headers
+- HTTPS status
+- robots.txt validity
+- sitemap.xml accessibility
+- Page HTML (for Core Web Vitals structural signals)
+
+**What it evaluates:**
+
+| Signal | Check Method | Weight |
+|---|---|---|
+| HTTPS enforced | HTTP→HTTPS redirect + HSTS header | High |
+| HSTS present | `Strict-Transport-Security` header | Medium |
+| Mobile viewport | `<meta name="viewport">` present | Medium |
+| robots.txt valid syntax | Parser runs without errors | High |
+| Sitemap in robots.txt | `Sitemap:` directive present | Medium |
+| sitemap.xml accessible | HTTP 200 response | Medium |
+| llms.txt accessible | HTTP 200 response | High |
+| Canonical tag present | `<link rel="canonical">` in source | Medium |
+| Render-blocking scripts | `<script>` in `<head>` without defer/async | Medium |
+| Images have dimensions | `width` and `height` attributes | Low |
+| Content-Encoding | gzip or brotli present | Low |
+| Cache-Control | public caching enabled | Low |
+
+**Output format:**
+```json
+{
+  "subagent": "geo-technical",
+  "score": 0-100,
+  "https_enforced": true|false,
+  "hsts_present": true|false,
+  "mobile_ready": true|false,
+  "robots_valid": true|false,
+  "sitemap_accessible": true|false,
+  "critical_issues": ["issue 1", "issue 2"],
+  "top_findings": ["finding 1", "finding 2", "finding 3"]
+}
+```
+
+---
+
+## Collecting Results
+
+After all 5 subagents return, the operator:
+
+1. Validates that all 5 responses are present
+2. Extracts the `score` from each response
+3. Applies the GEO Score formula (see `docs/scoring-methodology.md`)
+4. Collects all `top_findings` arrays into a unified findings list
+5. Ranks findings by impact for the Remediation Roadmap
+
+---
+
+## Error Handling
+
+If a subagent fails or returns incomplete data:
+
+| Scenario | Action |
+|---|---|
+| Subagent returns no score | Use 50 as neutral default. Flag component as `data-gap` in GeoScoreSummary. |
+| robots.txt fetch fails (404/500) | Mark all crawler statuses as "unknown (robots.txt inaccessible)". Do not assume blocked or allowed. |
+| llms.txt returns 500 error | Treat as "missing" rather than "blocked". Note the error in CrawlerAccessReport. |
+| Page fetch fails entirely | Stop Phase 2. Report to user. Do not produce scores. |
+| One subagent times out | Log the timeout. Use 50 as default for that component. Note in output. |
+
+Never invent scores. A `data-gap` flag is more useful than a fabricated number.
+
+---
+
+## Brand Authority (Separate Pass)
+
+Brand Authority (20% weight) is not a Phase 2 parallel subagent — it is a separate `/geo brands` command pass that runs `scripts/brand_scanner.py` against the 8 target platforms.
+
+Run it after Phase 2 completes:
+```bash
+python scripts/brand_scanner.py --brand "Client Name" --domain example.com
+```
+
+Or trigger it via: `/geo brands`
+
+The Brand Authority score is then incorporated into the final GEO Score calculation.

package/assets/worker-kits/growthub-geo-seo-v1/examples/citability-sample.md

@@ -0,0 +1,155 @@
+# Citability Analysis — Sample (GrowthHub.com)
+
+> Example: `examples/citability-sample.md`
+> This is a filled sample based on a fictitious citability analysis of thegrowthub.com.
+> Use this as a reference for what a completed CitabilityAnalysis looks like in production.
+
+---
+
+## URL Audited
+
+| Field | Value |
+|---|---|
+| Target URL | https://thegrowthub.com |
+| Client | Growthub |
+| Analysis Date | 2026-04-14 |
+| Execution Mode | local-fork |
+| Script Used | scripts/citability_scorer.py |
+
+---
+
+## Citability Score
+
+| Metric | Value |
+|---|---|
+| Raw Score | **71 / 100** |
+| Letter Grade | **B** |
+| Percentile Estimate | Top 33% of audited pages |
+| Score Date | 2026-04-14 |
+| Previous Score | N/A (first audit) |
+
+---
+
+## Component Breakdown
+
+| Metric | Raw Score (0–100) | Weight | Weighted Score | Status |
+|---|---|---|---|---|
+| Answer Block Quality | 82 | 30% | 24.6 | Strong |
+| Self-Containment | 74 | 25% | 18.5 | Adequate |
+| Structural Readability | 79 | 20% | 15.8 | Strong |
+| Statistical Density | 47 | 15% | 7.05 | Weak |
+| Uniqueness Signals | 52 | 10% | 5.2 | Adequate |
+| **TOTAL** | | **100%** | **71.15** | **B** |
+
+---
+
+## Answer Block Quality Detail
+
+**Score: 82 / 100**
+
+Paragraphs evaluated: 24
+
+| Paragraph # | Subject Clear | Evidence Present | No Unresolved Pronouns | Score |
+|---|---|---|---|---|
+| 1 (Hero intro) | Yes | No | Yes | 7 |
+| 2 (Problem statement) | Yes | Yes | Yes | 9 |
+| 3 (Solution description) | Yes | Yes | No | 7 |
+| 4 (Feature 1) | Yes | Yes | Yes | 9 |
+| 5 (Feature 2) | Yes | No | No | 5 |
+| 6 (Social proof) | Yes | Yes | Yes | 10 |
+
+Average across 24 paragraphs: 8.2 / 10 (normalized to 82 / 100)
+
+**Best answerable paragraph:**
+> "GrowthHub's AI-enabled worker kits reduce campaign production time by 65% — from 12 hours of manual brief-writing and asset coordination to 4 hours of structured operator execution. Each kit ships with pre-built templates, brand kit integration, and a step-by-step workflow that any team member can follow without prior AI training."
+
+**Weakest paragraph (needs rewrite):**
+> "It integrates seamlessly with your existing tools. This means you don't have to change how you work — it just makes everything faster and more consistent for your team."
+
+*Problem: "It" and "This" in the opening sentences are unresolved. What does "it" refer to? AI systems cannot cleanly cite this paragraph.*
+
+---
+
+## Self-Containment Check
+
+| Signal | Value | Status |
+|---|---|---|
+| Total word count | 1,847 words | Good (within 800–2,500 range) |
+| Pronoun count | 94 instances | |
+| Noun count | 412 instances | |
+| Pronoun-to-noun ratio | 0.23 : 1 | Good (< 0.3) |
+| Optimal word count range | 800–2,500 words | On target |
+| Contextual dependency score | 27 / 100 | Low dependency — good |
+
+**Self-containment score: 74 / 100**
+
+Primary drag: 11 paragraphs open with "This," "It," or "They" without a prior noun anchor in the same sentence. These are individually readable but drop the raw self-containment score.
+
+---
+
+## Structural Readability Check
+
+| Signal | Status | Notes |
+|---|---|---|
+| H1 present | Yes | "Growthub — AI-Enabled Growth Infrastructure" |
+| H2 count | 7 | Well-structured — above the ≥2 minimum |
+| H3 count | 12 | Good depth |
+| Numbered lists | Yes | 3 numbered lists found |
+| Bulleted lists | Yes | 8 bulleted lists found |
+| Average paragraph length | 77 words | Well within the ≤150 word target |
+| Wall-of-text sections | No | Longest unbroken block is 134 words (acceptable) |
+
+**Structural readability score: 79 / 100**
+
+Strong performance. Minor deduction: 2 of the 7 H2 sections have only a single H3 child — slight structural thinness.
+
+---
+
+## Statistical Density Check
+
+| Signal | Value | Status |
+|---|---|---|
+| Percentage references | 4 instances | Low |
+| Numbered data points | 6 instances | Low |
+| Dollar/currency figures | 0 instances | Missing |
+| Year/date references | 3 instances | |
+| Data points per 1,000 words | 7.0 | Slightly below optimal (8–15) |
+| Statistical density score | 47 / 100 | Weak |
+
+**Key finding:** Statistical density is the weakest component. The homepage copy is benefit-focused but lacks specific performance numbers, client results, or category statistics. Adding 6–8 concrete data points (e.g., "reduces production time by 65%," "used by 120+ agencies") would push this score above 70.
+
+---
+
+## Uniqueness Signals Check
+
+| Signal | Present | Example |
+|---|---|---|
+| First-party study or research | No | — |
+| Proprietary data references | No | — |
+| Original methodology | Yes | "Worker kit architecture" is a proprietary concept defined on the page |
+| Unique terminology | Yes | "operator execution," "worker kit," "GEO Score" — distinctive phrasing |
+| Non-generic claims | Partial | "AI-enabled growth infrastructure" is specific but unquantified |
+
+**Uniqueness score: 52 / 100**
+
+Growthub has genuine intellectual property in its worker kit architecture. The terminology is distinctive. The score is limited by the absence of original research or first-party data claims.
+
+---
+
+## Key Findings
+
+1. **Answer Block Quality is the standout strength.** The homepage copy is well-structured for AI citation — paragraphs are clear, evidence-backed, and readable. The top 40% of paragraphs score 9–10/10 individually.
+
+2. **Statistical Density is the primary drag on the citability score.** With 7.0 data points per 1,000 words (target: 8–15), the page is slightly data-thin. Adding quantified client results or performance benchmarks would be the highest-leverage single edit.
+
+3. **Self-containment is solid but improvable.** The pronoun-to-noun ratio of 0.23 is healthy, but 11 paragraphs open with unresolved pronoun references. Fixing these 11 opening sentences would add approximately 5–6 points to the self-containment score.
+
+---
+
+## Top 3 Improvements
+
+| Priority | Action | Expected Score Gain | Effort |
+|---|---|---|---|
+| 1 | Add 6 quantified performance claims (%, numbers, client results) throughout the homepage | +8 to +12 points (Statistical Density) | Medium — 2–3 hours of content editing |
+| 2 | Rewrite 11 paragraph openers that begin with "It," "This," or "They" to use explicit noun subjects | +5 to +7 points (Self-Containment + Answer Block Quality) | Low — 45 minutes |
+| 3 | Publish one original data report or methodology explainer (e.g., "Worker Kit Performance Report Q1 2026") | +4 to +6 points (Uniqueness Signals) | High — 1–2 weeks of content production |

package/assets/worker-kits/growthub-geo-seo-v1/examples/geo-audit-sample.md

@@ -0,0 +1,126 @@
+# GEO Audit Brief — Sample (GrowthHub.com)
+
+> Example: `examples/geo-audit-sample.md`
+> This is a filled sample based on a fictitious full audit run of thegrowthub.com.
+> Use this as a reference for what a completed GeoAuditBrief looks like in production.
+
+---
+
+## Project Overview
+
+| Field | Value |
+|---|---|
+| Client | Growthub |
+| Target URL | https://thegrowthub.com |
+| Audit Scope | Full audit — all 6 GEO components |
+| Execution Mode | local-fork |
+| Primary Command | `/geo audit` |
+| Requested By | Antonio |
+| Date | 2026-04-14 |
+| Brand Kit | brands/growthub/brand-kit.md |
+| Project Slug | studio-launch-reference |
+
+---
+
+## Audit Objective
+
+Establish a baseline GEO Score for thegrowthub.com as the studio launch reference audit. Determine which AI search platforms can currently access and cite Growthub content, identify the top structural barriers to AI citability, and produce a complete remediation roadmap that can serve as both an internal reference and a client-facing demo of the GEO SEO Studio kit.
+
+---
+
+## Current Visibility Context
+
+**Known strengths:**
+- Site is on HTTPS with a valid SSL certificate
+- robots.txt exists and has valid syntax
+- Core Web Vitals signals are healthy based on PageSpeed data from March 2026
+- Homepage has basic Organization schema in JSON-LD
+
+**Known concerns:**
+- llms.txt has never been created — AI crawlers have no explicit content guidance
+- GPTBot and ClaudeBot were found to be implicitly allowed but not explicitly listed in robots.txt
+- No FAQPage or Article schema on blog posts
+- Content citability has not been measured previously — pronoun density unknown
+
+**Prior audit outputs:**
+| Date | Audit Type | Output Location |
+|---|---|---|
+| N/A | First audit | N/A |
+
+---
+
+## Competitor Reference URLs
+
+| Competitor | URL | Notes |
+|---|---|---|
+| Jasper.ai | https://jasper.ai | AI content tool competitor — strong brand authority |
+| Copy.ai | https://copy.ai | High GEO Score expected — large content library |
+| Writesonic | https://writesonic.com | Active blog with strong E-E-A-T signals |
+
+---
+
+## Existing Assets
+
+| Asset | Status | Location |
+|---|---|---|
+| robots.txt | Present | https://thegrowthub.com/robots.txt |
+| sitemap.xml | Present | https://thegrowthub.com/sitemap.xml |
+| llms.txt | Missing | https://thegrowthub.com/llms.txt (404) |
+| llms-full.txt | Missing | https://thegrowthub.com/llms-full.txt (404) |
+| Existing schema markup | JSON-LD (Organization only) | Homepage `<head>` |
+| Previous GEO report | No | N/A |
+
+---
+
+## Command Selection Plan
+
+**Primary command:** `/geo audit`
+
+**Rationale:** Full audit selected because this is the baseline reference run for the studio kit. All 6 components must be scored, all 14 crawlers must be checked, and the full remediation roadmap must be produced. A quick scan would not produce the depth required for a reference example.
+
+**Secondary commands (full audit sequence):**
+
+| Command | Purpose | Sequence |
+|---|---|---|
+| `/geo audit` | Full composite audit entrypoint | 1 |
+| `/geo crawlers` | AI crawler permission check — verify robots.txt rules per crawler | 2 |
+| `/geo brands` | Brand authority scan — 8 platforms | 3 |
+| `/geo schema` | Structured data validation — full JSON-LD review | 4 |
+| `/geo technical` | Technical health check — headers, HTTPS, Core Web Vitals signals | 5 |
+| `/geo llmstxt` | llms.txt generation plan — file does not exist | 6 |
+| `/geo report` | Final Markdown report compilation | 7 |
+
+---
+
+## Delivery Requirements
+
+| Requirement | Value |
+|---|---|
+| Delivery format | Both (Markdown + PDF) |
+| PDF report needed | Yes — branded PDF for internal stakeholder reference |
+| Client-facing proposal | No — internal reference only |
+| Output deadline | Same-day (reference run) |
+| Stakeholder recipient | Antonio |
+
+---
+
+## Success Criteria
+
+- [x] GEO Score composite produced with all 6 components scored
+- [x] Crawler access status confirmed for all 14 AI crawlers
+- [x] Citability analysis completed with letter grade assigned
+- [x] At least 5 actionable remediation items identified and prioritized
+- [x] llms.txt plan produced — file does not exist, full plan required
+- [x] Remediation roadmap covers 4-week sprint with owner assignments
+- [x] All output files saved to `output/growthub/studio-launch-reference/`
+- [x] Brand kit DELIVERABLES LOG updated
+
+---
+
+## Audit Notes (Operator)
+
+This audit was run in local-fork mode with geo-seo-claude cloned at `~/geo-seo-claude`. Python 3.11 was used. All 14 /geo skills confirmed present in `skills/` directory. Playwright chromium installed and verified. `fetch_page.py` ran successfully against thegrowthub.com — page renders fully in Playwright (no JS rendering issues detected).
+
+Phase 2 subagents dispatched in parallel at 14:03:22. All 5 subagents returned results within 90 seconds. Brand authority scan (`/geo brands`) run separately as sequential command — completed in 45 seconds using `brand_scanner.py`.
+
+PDF generation triggered at end of session using `python scripts/generate_pdf_report.py --input output/growthub/studio-launch-reference/geo_score_data.json`.