@growthub/cli 0.3.52 → 0.3.53

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

@@ -0,0 +1,207 @@
+# PDF Report Input Data — Sample (GrowthHub.com)
+
+> Example: `examples/pdf-report-sample.md`
+> This shows the input data structure passed to `scripts/generate_pdf_report.py` to produce a branded PDF.
+> In local-fork mode, this JSON is written to `output/<client-slug>/<project-slug>/geo_score_data.json`
+> and then consumed by the ReportLab PDF generator.
+
+---
+
+## How to Trigger PDF Generation
+
+```bash
+# From your geo-seo-claude fork directory:
+python scripts/generate_pdf_report.py \
+  --input output/growthub/studio-launch-reference/geo_score_data.json \
+  --output output/growthub/studio-launch-reference/GrowthHub_GeoScoreReport_v1_20260414.pdf \
+  --brand "Growthub" \
+  --logo brands/growthub/assets/logo.png
+```
+
+In agent-only mode: skip PDF generation and produce the Markdown equivalent instead (GeoScoreSummary).
+
+---
+
+## Input Data Structure (geo_score_data.json)
+
+```json
+{
+  "report_meta": {
+    "client_name": "Growthub",
+    "client_slug": "growthub",
+    "target_url": "https://thegrowthub.com",
+    "audit_date": "2026-04-14",
+    "report_version": "1",
+    "prepared_by": "Antonio",
+    "execution_mode": "local-fork"
+  },
+  "geo_score": {
+    "composite": 68,
+    "grade": "C",
+    "previous_composite": null,
+    "score_change": null
+  },
+  "components": [
+    {
+      "name": "AI Citability & Visibility",
+      "weight": 0.25,
+      "raw_score": 58,
+      "weighted_score": 14.5,
+      "grade": "C",
+      "status": "weak",
+      "primary_issue": "No llms.txt — AI crawlers have no explicit content guidance. GPTBot not explicitly permitted."
+    },
+    {
+      "name": "Brand Authority",
+      "weight": 0.20,
+      "raw_score": 66,
+      "weighted_score": 13.2,
+      "grade": "C",
+      "status": "adequate",
+      "primary_issue": "LinkedIn company page exists but has <200 followers. No Wikipedia presence. GitHub absent."
+    },
+    {
+      "name": "Content Quality & E-E-A-T",
+      "weight": 0.20,
+      "raw_score": 71,
+      "weighted_score": 14.2,
+      "grade": "B",
+      "status": "adequate",
+      "primary_issue": "Statistical density low (7.0 data points per 1,000 words). No published original research."
+    },
+    {
+      "name": "Technical Foundations",
+      "weight": 0.15,
+      "raw_score": 84,
+      "weighted_score": 12.6,
+      "grade": "B",
+      "status": "strong",
+      "primary_issue": "Strong overall. Minor issue: Sitemap directive missing from robots.txt."
+    },
+    {
+      "name": "Structured Data",
+      "weight": 0.10,
+      "raw_score": 42,
+      "weighted_score": 4.2,
+      "grade": "D",
+      "status": "weak",
+      "primary_issue": "Only Organization schema present. Missing FAQPage, Article, BreadcrumbList, WebSite."
+    },
+    {
+      "name": "Platform Optimization",
+      "weight": 0.10,
+      "raw_score": 61,
+      "weighted_score": 6.1,
+      "grade": "C",
+      "status": "adequate",
+      "primary_issue": "Google AI Overviews readiness limited by missing FAQPage schema. Perplexity readiness moderate."
+    }
+  ],
+  "citability": {
+    "score": 71,
+    "grade": "B",
+    "components": {
+      "answer_block_quality": 82,
+      "self_containment": 74,
+      "structural_readability": 79,
+      "statistical_density": 47,
+      "uniqueness_signals": 52
+    }
+  },
+  "crawler_access": {
+    "total_crawlers": 14,
+    "fully_allowed": 10,
+    "partially_blocked": 2,
+    "blocked": 0,
+    "not_mentioned": 2,
+    "llms_txt_present": false,
+    "llms_full_txt_present": false
+  },
+  "top_findings": [
+    {
+      "rank": 1,
+      "title": "No llms.txt file",
+      "description": "thegrowthub.com does not have an llms.txt file. AI crawlers are using robots.txt rules only, with no explicit content guidance. This is the highest-impact single fix available.",
+      "component": "AI Citability & Visibility",
+      "priority": "P0",
+      "expected_score_gain": 8,
+      "effort": "Low"
+    },
+    {
+      "rank": 2,
+      "title": "Missing FAQPage and Article schema",
+      "description": "Only Organization schema is present. FAQPage schema would directly feed Google AI Overviews. Article schema is required for blog post citation by AI systems.",
+      "component": "Structured Data",
+      "priority": "P0",
+      "expected_score_gain": 12,
+      "effort": "Medium"
+    },
+    {
+      "rank": 3,
+      "title": "Low statistical density on homepage",
+      "description": "Homepage averages 7.0 data points per 1,000 words (target: 8–15). Adding quantified client results and performance benchmarks would improve citability score.",
+      "component": "Content Quality & E-E-A-T",
+      "priority": "P1",
+      "expected_score_gain": 6,
+      "effort": "Medium"
+    },
+    {
+      "rank": 4,
+      "title": "11 paragraph openers with unresolved pronouns",
+      "description": "Paragraphs beginning with 'It,' 'This,' or 'They' without a prior noun anchor reduce self-containment score. Quick rewrite task.",
+      "component": "Content Quality & E-E-A-T",
+      "priority": "P1",
+      "expected_score_gain": 4,
+      "effort": "Low"
+    },
+    {
+      "rank": 5,
+      "title": "No Wikipedia or GitHub presence",
+      "description": "Brand authority is limited by absence of Wikipedia article and GitHub organization. These are high-authority signals for AI brand knowledge graphs.",
+      "component": "Brand Authority",
+      "priority": "P2",
+      "expected_score_gain": 5,
+      "effort": "High"
+    }
+  ],
+  "remediation_summary": {
+    "score_before": 68,
+    "score_after_projected": 83,
+    "grade_before": "C",
+    "grade_after_projected": "B",
+    "sprint_weeks": 4,
+    "rescore_date": "2026-05-14"
+  },
+  "pdf_config": {
+    "template": "branded-audit",
+    "color_primary": "#1A1A2E",
+    "color_accent": "#E94560",
+    "logo_path": "brands/growthub/assets/logo.png",
+    "include_charts": true,
+    "include_roadmap": true,
+    "include_code_snippets": false,
+    "page_size": "Letter"
+  }
+}
+```
+
+---
+
+## PDF Sections Generated
+
+The `generate_pdf_report.py` script produces the following sections in the output PDF:
+
+| Section | Pages | Content |
+|---|---|---|
+| Cover page | 1 | Client logo, GEO Score gauge, grade, date |
+| Executive summary | 1 | 3-bullet summary, score vs. benchmark |
+| Component breakdown | 2 | Visual bar chart for 6 components |
+| Citability analysis | 1 | 5-metric breakdown with letter grade |
+| Crawler access matrix | 1 | 14-crawler table with color-coded status |
+| Top 5 findings | 2 | Ranked findings with impact and effort |
+| 4-week roadmap | 1 | Sprint table with actions and owners |
+| Back cover | 1 | Growthub contact, next steps |
+
+**Total pages:** 10
+
+**Output file:** `GrowthHub_GeoScoreReport_v1_20260414.pdf`

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

@@ -0,0 +1,184 @@
+# Client Proposal — Sample (UrbanCycle.com)
+
+> Example: `examples/prospect-proposal-sample.md`
+> This is a filled sample proposal for a fictitious e-commerce client, UrbanCycle.com.
+> Use this as a reference for what a completed ClientProposal looks like in production.
+
+---
+
+## Prospect
+
+| Field | Value |
+|---|---|
+| Company | UrbanCycle Co. |
+| Website | https://urbancycle.com |
+| Industry | E-commerce — Urban Mobility / Electric Bikes |
+| Contact | Sarah Chen, Head of Marketing |
+| Proposal Date | 2026-04-14 |
+| Prepared By | Antonio |
+| Proposal Valid Until | 2026-05-14 |
+
+---
+
+## GEO Audit Summary
+
+We ran a preliminary GEO (Generative Engine Optimization) scan on `urbancycle.com`. Here is what we found at a glance:
+
+| Metric | Score | Grade | Benchmark Average |
+|---|---|---|---|
+| Overall GEO Score | 44 / 100 | D | 58 / 100 |
+| AI Citability | 38 / 100 | F | 54 / 100 |
+| Crawler Access | 6 / 14 crawlers | | 9 / 14 |
+| Schema Coverage | 1 type found (WebSite only) | | 3 types |
+| llms.txt Present | No | | 22% of sites |
+
+---
+
+## Why GEO Matters Now
+
+AI search is changing where e-commerce traffic comes from — and urban mobility is one of the fastest-growing query categories in AI search.
+
+- **"Best electric bike for commuting"** now returns an AI-generated answer in Google AI Overviews for 89% of US searchers (Q1 2026) — bypassing traditional organic results entirely.
+- **ChatGPT Shopping** (launched Q4 2025) now surfaces product recommendations directly in chat — and it cites pages, not ads.
+- **Perplexity AI** drove 41% more e-commerce referral traffic to its cited sources in Q1 2026 vs. Q3 2025. Sites not optimized for citability received zero of this traffic.
+- Sites with a GEO Score above 75 receive **5.27× more AI-referred traffic** than sites scoring below 55 — a 527% gap that compounds monthly as AI search adoption grows.
+
+UrbanCycle is currently a D-grade site for AI search visibility. Competitors like ElectrifyBikes.com (GEO Score: 79) and UrbanVolt.co (GEO Score: 71) are already capturing the AI-referred traffic that UrbanCycle is leaving on the table.
+
+---
+
+## Current Visibility Gap
+
+Based on our preliminary scan of `urbancycle.com`:
+
+**What AI systems can access:**
+- 6 of 14 AI crawlers have explicit access — GPTBot (ChatGPT), ClaudeBot (Anthropic), PerplexityBot, and Google-Extended are **blocked** by a wildcard Disallow rule in robots.txt that was likely added to block scraper bots but inadvertently blocks AI systems as well.
+
+**What AI systems can cite:**
+- Citability score of 38/100 (F grade) — product pages use heavy JavaScript rendering that Playwright confirms is not crawler-readable. Page descriptions are thin (avg. 47 words per product page) with high pronoun density. No answer blocks found.
+
+**Structured data gaps:**
+- Only `WebSite` schema detected. No `Product`, `BreadcrumbList`, `FAQPage`, or `Organization` schema — meaning Google AI Overviews and ChatGPT Shopping cannot surface UrbanCycle product data in structured format.
+
+---
+
+## What We Found — 3 Critical Issues
+
+### Issue 1: GPTBot and Major AI Crawlers Are Blocked
+
+A wildcard rule in `robots.txt` (`User-agent: * Disallow: /products/`) prevents GPTBot, ClaudeBot, PerplexityBot, and Google-Extended from accessing product pages — the most valuable content on the site for AI citation.
+
+**Impact:** ChatGPT, Claude, and Perplexity cannot see UrbanCycle products. When a user asks "what's the best e-bike under $2,000?", UrbanCycle will never appear — even if the products are objectively competitive.
+
+### Issue 2: Product Pages Are Not AI-Citable
+
+Product page copy averages 47 words with high pronoun density ("It features," "This model includes," "They are designed for"). There are no answer blocks — no self-contained paragraphs that AI systems can quote as authoritative product descriptions.
+
+**Impact:** Even when AI crawlers can access the pages, they cannot extract clean, quotable product information. The AI system skips to a competitor whose product pages contain specific, data-rich descriptions ("The UrbanVolt S3 delivers 65Nm of torque and a 55-mile range on a single charge").
+
+### Issue 3: No Product Schema — ChatGPT Shopping Cannot Surface Products
+
+The site uses zero `Product` schema markup. ChatGPT Shopping, Google AI Overviews for commerce, and Perplexity's product finder all require structured `Product` schema (name, price, availability, description, image, brand, rating) to include a product in AI-generated shopping results.
+
+**Impact:** UrbanCycle is invisible to every AI-powered shopping surface — a growing channel that drove $2.1B in AI-attributed e-commerce revenue in Q1 2026 (Similarweb AI Commerce Report, March 2026).
+
+---
+
+## Recommended Engagement
+
+### Option A — Quick GEO Audit
+
+**Best for:** Validating the scope of the problem before committing to a full engagement.
+
+| Deliverable | Details |
+|---|---|
+| GEO Score Snapshot | Composite score with all 6 components |
+| Crawler Unblock Plan | Exact robots.txt edits needed, ready to implement |
+| Top 3 Critical Gaps | Product schema, citability, llms.txt |
+| Quick Wins Checklist | Fixes executable in under 2 hours by your dev team |
+| Delivery Format | Markdown report |
+| Turnaround | 48 hours |
+
+**Investment: $1,800**
+
+---
+
+### Option B — Full GEO + SEO Audit
+
+**Best for:** Teams ready to act with a complete, implementation-ready remediation plan.
+
+| Deliverable | Details |
+|---|---|
+| Full GEO Score Report | All 6 components, all 14 crawlers checked |
+| Citability Analysis | Page-by-page breakdown for top 10 product pages |
+| Crawler Access Report | Full robots.txt review and rewrite recommendation |
+| Product Schema Package | Code-ready JSON-LD for top 20 products |
+| llms.txt + llms-full.txt | Files ready to deploy at domain root |
+| Technical Foundations | Server headers, Core Web Vitals, HTTPS status |
+| Remediation Roadmap | 4-week sprint with owner assignments |
+| PDF Report | Branded deliverable for stakeholder presentation |
+| Turnaround | 7 business days |
+
+**Investment: $3,500**
+
+---
+
+### Option C — Monthly GEO Monitoring + Remediation Retainer
+
+**Best for:** E-commerce teams launching new products regularly who need continuous AI search visibility management.
+
+| Included Monthly | Details |
+|---|---|
+| GEO Rescore | Full audit run each month — track score trend |
+| Product Page Citability Reviews | Up to 10 product pages reviewed and improved per month |
+| Schema Maintenance | New product schema as SKUs are added |
+| Crawler Access Monitoring | Weekly automated check — alerts on blocks |
+| Brand Authority Tasks | Platform seeding, mention monitoring (Reddit, YouTube) |
+| Monthly Report | Score trend, wins, next month plan |
+| Slack Access | Async support Mon–Fri |
+
+**Investment: $2,800 / month**
+**Minimum term: 3 months**
+
+---
+
+## ROI Projection
+
+Based on UrbanCycle's current D-grade GEO Score and the identified gaps, completing the Full Audit remediation roadmap is projected to produce:
+
+| Metric | Current State | After Remediation | Change |
+|---|---|---|---|
+| GEO Score | 44 / 100 (D) | 76 / 100 (B) | +32 points |
+| AI-referred traffic | ~0.3% of total | ~2.1% of total | +600% |
+| Product pages citable by AI | ~0 of top pages | ~18 of top 20 pages | +18 pages |
+| AI crawlers with full access | 6 / 14 | 13 / 14 | +7 crawlers |
+| ChatGPT Shopping visibility | None | Active (Product schema live) | New channel |
+
+**Conservative AI traffic uplift estimate:** If UrbanCycle currently receives 40,000 monthly visitors, moving from 0.3% to 2.1% AI-referred traffic = **+720 additional monthly visitors** from AI search alone — at $0 ad spend. At a 2.8% e-commerce conversion rate and an average order value of $1,400, that is **$28,224 in incremental monthly revenue potential** (rough estimate, results depend on implementation quality and product competitiveness).
+
+> Projection grounded in geo-seo-claude audit data and Similarweb AI Commerce Report Q1 2026. Actual results vary by site, category, and implementation speed.
+
+---
+
+## Next Steps
+
+1. **Review and sign** the proposal by 2026-05-14
+2. **Kickoff call** (30 min) — Sarah + Antonio confirm scope, target pages, and delivery format
+3. **Audit begins** — operator runs `/geo audit https://urbancycle.com` with all secondary commands
+4. **Week 1 delivery** — Crawler Access Report and Quick Wins delivered first for immediate action
+5. **Full delivery** — Complete audit package delivered within 7 business days
+
+To proceed, reply to this proposal or email antonio@thegrowthub.com.
+
+---
+
+## Guarantee / Risk Reversal
+
+If we complete the Full GEO Audit and your development team implements all P0 and P1 remediation items within 30 days without seeing measurable improvement in AI crawler access (verifiable via `/geo crawlers` rescore), we will provide a second full audit at no charge.
+
+We do not produce generic SEO advice. Every finding is backed by data from your actual pages, your robots.txt, and your live site structure — verified by geo-seo-claude running against the real URL.
+
+---
+
+*Prepared by Antonio · Growthub · 2026-04-14*
+*geo-seo-claude audit run: 2026-04-14 14:03 UTC · Execution mode: local-fork · GEO Score: 44/100 (D)*

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

@@ -0,0 +1,124 @@
+# Growthub Meta — growthub-geo-seo-v1
+
+---
+
+## Kit Identity
+
+| Field | Value |
+|---|---|
+| Kit ID | `growthub-geo-seo-v1` |
+| Version | `1.0.0` |
+| Schema Version | `2` |
+| Type | `worker` |
+| Family | `studio` |
+| Execution Mode | `export` |
+| Activation Modes | `["export"]` |
+| Visibility | `public-open-source` |
+| Source Repo | `growthub-local` |
+| Frozen At | `2026-04-14T00:00:00.000Z` |
+
+---
+
+## What This Kit Does
+
+The Growthub GEO SEO Studio is a worker kit that wraps the `geo-seo-claude` open-source tool (https://github.com/zubair-trabzada/geo-seo-claude) to produce AI search visibility audits, citability scores, and remediation roadmaps for websites.
+
+The kit provides a self-contained local execution environment. An operator exports the kit, points Claude Code's Working Directory at the kit root, and the `geo-seo-operator` worker handles the complete 10-step audit workflow.
+
+---
+
+## Folder Structure
+
+```
+growthub-geo-seo-v1/
+  kit.json                          ← Kit manifest (schemaVersion: 2)
+  QUICKSTART.md                     ← Setup guide
+  .env.example                      ← Environment template
+  skills.md                         ← Master methodology doc (read at every session)
+  output-standards.md               ← Output naming, structure, quality bar
+  runtime-assumptions.md            ← Frozen upstream assumptions
+  validation-checklist.md           ← Pre-session + kit validation checklists
+  bundles/
+    growthub-geo-seo-v1.json        ← Bundle manifest
+  workers/
+    geo-seo-operator/
+      CLAUDE.md                     ← Agent operating instructions (entrypoint)
+  brands/
+    _template/
+      brand-kit.md                  ← Blank client brand kit template
+    growthub/
+      brand-kit.md                  ← Growthub internal reference example
+    NEW-CLIENT.md                   ← Instructions for adding new clients
+  setup/
+    clone-fork.sh                   ← Clones geo-seo-claude fork
+    verify-env.mjs                  ← Verifies fork, API key, env config
+    check-deps.sh                   ← Verifies Python, Playwright, git, node
+  output/
+    README.md                       ← Output directory structure and naming
+  templates/                        ← 11 production-quality audit templates
+    geo-audit-brief.md
+    citability-analysis.md
+    crawler-access-report.md
+    brand-visibility-report.md
+    geo-score-summary.md
+    content-analysis.md
+    schema-validation.md
+    technical-foundations.md
+    llmstxt-plan.md
+    remediation-roadmap.md
+    client-proposal.md
+  examples/                         ← 4 filled samples for reference
+    geo-audit-sample.md
+    citability-sample.md
+    pdf-report-sample.md
+    prospect-proposal-sample.md
+  docs/                             ← 4 technical reference documents
+    geo-seo-fork-integration.md
+    subagent-dispatch.md
+    scoring-methodology.md
+    pdf-report-layer.md
+  growthub-meta/
+    README.md                       ← This file
+    kit-standard.md                 ← Kit rules and required-files contract
+```
+
+---
+
+## Activation
+
+This kit is activated in `export` mode:
+
+1. CLI exports the kit to a local folder
+2. User points Claude Code's Working Directory at the exported folder root
+3. `workers/geo-seo-operator/CLAUDE.md` is the agent entrypoint
+
+No server-side activation is required. The kit is fully self-contained.
+
+---
+
+## Supported Output Categories
+
+| Category | Templates | Examples |
+|---|---|---|
+| GEO Audit Briefs | `templates/geo-audit-brief.md` | `examples/geo-audit-sample.md` |
+| Citability Analysis | `templates/citability-analysis.md` | `examples/citability-sample.md` |
+| Crawler Access Reports | `templates/crawler-access-report.md` | — |
+| Brand Visibility Reports | `templates/brand-visibility-report.md` | — |
+| GEO Score Summaries | `templates/geo-score-summary.md` | — |
+| Content Analyses | `templates/content-analysis.md` | — |
+| Schema Validation Reports | `templates/schema-validation.md` | — |
+| Technical Foundations Reports | `templates/technical-foundations.md` | — |
+| llms.txt Plans | `templates/llmstxt-plan.md` | — |
+| Remediation Roadmaps | `templates/remediation-roadmap.md` | — |
+| Client Proposals | `templates/client-proposal.md` | `examples/prospect-proposal-sample.md` |
+| PDF Reports | (generated by `scripts/generate_pdf_report.py`) | `examples/pdf-report-sample.md` |
+
+---
+
+## Related Kits
+
+| Kit | Family | Purpose |
+|---|---|---|
+| `creative-strategist-v1` | workflow | Campaign strategy and creative briefs |
+| `growthub-email-marketing-v1` | operator | Email marketing campaigns |
+| `growthub-open-higgsfield-studio-v1` | studio | AI video generation via Open Higgsfield |

package/assets/worker-kits/growthub-geo-seo-v1/growthub-meta/kit-standard.md

@@ -0,0 +1,116 @@
+# Kit Standard — growthub-geo-seo-v1
+
+**These rules govern the kit's structure, agent behavior, and output contract. All operators and maintainers must follow them.**
+
+---
+
+## Required Files Contract
+
+The following files must be present in every valid kit installation. Any missing file constitutes a broken kit.
+
+| File | Purpose | Can Be Empty? |
+|---|---|---|
+| `kit.json` | Kit manifest | No — must be valid JSON with schemaVersion: 2 |
+| `QUICKSTART.md` | User-facing setup guide | No |
+| `.env.example` | Environment template | No |
+| `skills.md` | Master methodology doc | No — must contain all 10 steps |
+| `output-standards.md` | Output rules | No |
+| `runtime-assumptions.md` | Upstream assumptions | No |
+| `validation-checklist.md` | Pre-session checklist | No |
+| `workers/geo-seo-operator/CLAUDE.md` | Agent entrypoint | No |
+| `brands/_template/brand-kit.md` | Blank brand kit template | No |
+| `brands/growthub/brand-kit.md` | Example brand kit | No |
+| `brands/NEW-CLIENT.md` | New client instructions | No |
+| `setup/clone-fork.sh` | Fork installation script | No |
+| `setup/verify-env.mjs` | Environment verification | No |
+| `setup/check-deps.sh` | Dependency check | No |
+| `output/README.md` | Output directory guide | No |
+| All 11 template files | Audit output templates | No — each must have all sections |
+| All 4 example files | Reference samples | No — must contain realistic filled data |
+| All 4 doc files | Technical reference | No |
+| `bundles/growthub-geo-seo-v1.json` | Bundle manifest | No |
+| `growthub-meta/README.md` | Kit metadata | No |
+| `growthub-meta/kit-standard.md` | This file | No |
+
+---
+
+## Bundle Contract
+
+| Requirement | Rule |
+|---|---|
+| Bundle ID | Must match kit ID: `growthub-geo-seo-v1` |
+| Kit ID in bundle | Must be `growthub-geo-seo-v1` |
+| Worker ID in bundle | Must be `geo-seo-operator` |
+| Schema version | Must be `2` |
+| `requiredFrozenAssets` | Must list all files in `kit.json` `frozenAssetPaths` |
+| Export folder name | `growthub-agent-worker-kit-geo-seo-v1` |
+| Export zip name | `growthub-agent-worker-kit-geo-seo-v1.zip` |
+
+---
+
+## Agent Rules
+
+### Workflow Order
+The operator must follow the 10-step workflow in `workers/geo-seo-operator/CLAUDE.md` strictly. Steps must not be skipped or reordered. The environment gate (Step 0) must run before anything else.
+
+### Fork Inspection
+In local-fork mode, the operator must inspect the actual fork files before producing any audit plan or command selection. Assumptions cannot substitute for inspection. If the fork is unavailable, the session must be marked `agent-only` and every output file must note the execution mode.
+
+### One Primary Command Path
+Each audit session must select one primary `/geo` command. Mixed-mode outputs (e.g., simultaneously running `/geo audit` and `/geo quick`) are not permitted without explicit transition notes.
+
+### Scoring Formula
+The GEO Score must always use the exact formula defined in `docs/scoring-methodology.md`. Component weights must not be adjusted per-session. A different weighting scheme is not a valid substitution.
+
+### Citability Algorithm
+The citability score must apply all 5 metrics. Shortcutting to 2 or 3 metrics is not acceptable. If data for a metric is unavailable, use 50 as the neutral default and flag the metric as `data-gap`.
+
+### No Secrets in Outputs
+The operator must never include `ANTHROPIC_API_KEY`, `FLASK_SECRET_KEY`, or any other secret value in any output file. If a brand kit contains sensitive context in `crm_notes`, that section must not be included verbatim in client-facing outputs.
+
+### Template-Bound Outputs
+All output artifacts must use the templates in `templates/`. The operator must not invent new template schemas or change the required section structure.
+
+---
+
+## Runtime Rules
+
+### No Secrets in Kit
+The kit itself must never contain a real API key, password, or credential. `.env.example` uses placeholder comments only. The `.env` file (which may contain real keys) must never be committed or included in kit exports.
+
+### geo-seo-claude Is the Reference Substrate
+The Python scripts, CLI skills, and subagent definitions in geo-seo-claude are the source of truth for tool behavior. The kit documents and wraps that behavior — it does not redefine it. When the upstream fork changes, `runtime-assumptions.md` must be updated.
+
+### Three Execution Modes Are First-Class
+`local-fork`, `agent-only`, and `hybrid` are all valid execution modes. The kit must never require local-fork mode for a session to produce valid outputs. Agent-only mode is always a valid fallback.
+
+### Markdown Is the Primary Output Format
+All audit artifacts are Markdown files. PDF output is generated on request from `geo_score_data.json` using `generate_pdf_report.py`. Markdown is the canonical record — PDFs are presentation layers.
+
+---
+
+## Versioning Rules
+
+| Scenario | Action |
+|---|---|
+| Bug fix in a template or doc file | Patch version bump: `1.0.0` → `1.0.1` |
+| New template or command added | Minor version bump: `1.0.0` → `1.1.0` |
+| Scoring formula changed or workflow restructured | Major version bump: `1.0.0` → `2.0.0` |
+| Upstream fork adds new command | Minor bump + update `runtime-assumptions.md` |
+| Upstream fork changes script API | Major bump if breaking + update `runtime-assumptions.md` |
+
+Version bumps must update:
+- `kit.json` → `kit.version`
+- `bundles/growthub-geo-seo-v1.json` → `bundle.version`
+- `growthub-meta/README.md` → Version field
+- `runtime-assumptions.md` → Frozen date and changelog note
+
+---
+
+## What Makes a Good Kit Contribution
+
+- Every template section must be production-ready — no placeholder text except `<!-- fill in -->` markers
+- Every example file must contain realistic, fictitious-but-plausible data — no Lorem ipsum
+- Every doc file must be grounded in actual geo-seo-claude fork behavior at time of writing
+- Scoring rules must be internally consistent — weights in `skills.md`, `docs/scoring-methodology.md`, and `docs/subagent-dispatch.md` must all match
+- Setup scripts must be idempotent — running them twice must not break anything