@growthub/cli 0.14.5 → 0.14.6

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

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

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

@@ -1,29 +0,0 @@
-# `helpers/` — safe shell tool layer (primitive #6)
-
-A **helper** is a small, deterministic script an agent invokes via one shell call instead of reconstructing a raw pipeline inline. Helpers are reviewable, deterministic, and safer than raw commands.
-
-## Convention
-
-```
-helpers/
-├── README.md                 # this file
-├── <verb>.sh                 # single-purpose shell scripts
-├── <verb>.mjs                # optional: Node-based helper
-└── <verb>.py                 # optional: Python-based helper
-```
-
-Every helper:
-
-1. Carries a one-line header comment: what it does + how to invoke it.
-2. Uses `set -euo pipefail` (or equivalent) — no silent failures.
-3. Has a matching row in the parent `SKILL.md`'s `helpers[]` frontmatter.
-4. Is referenced from `skills.md` at the step the agent should invoke it (no duplicated shell bodies).
-
-## When to promote an inline snippet
-
-- Appears more than once in `skills.md`.
-- Has fragile quoting or path interpolation.
-- Calls a side-effecting binary (ffmpeg, git, gh, npm install).
-- Multiple sub-skills invoke it.
-
-See the parent `SKILL.md` `helpers[]` array for the current roster.

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

@@ -1,123 +0,0 @@
-{
-  "schemaVersion": 2,
-  "kit": {
-    "id": "growthub-geo-seo-v1",
-    "version": "1.0.0",
-    "name": "Growthub Agent Worker Kit \u2014 GEO SEO Studio",
-    "description": "Self-contained local execution environment for GEO + SEO auditing using geo-seo-claude. Produces AI search visibility audits, citability scores, crawler access reports, brand mention scans, remediation roadmaps, and client-ready PDF deliverables via 14 specialized commands and 5 parallel subagents.",
-    "type": "worker",
-    "visibility": "public-open-source",
-    "sourceRepo": "growthub-local",
-    "family": "studio"
-  },
-  "entrypoint": {
-    "workerId": "geo-seo-operator",
-    "path": "workers/geo-seo-operator/CLAUDE.md"
-  },
-  "workerIds": [
-    "geo-seo-operator"
-  ],
-  "agentContractPath": "workers/geo-seo-operator/CLAUDE.md",
-  "brandTemplatePath": "brands/_template/brand-kit.md",
-  "publicExampleBrandPaths": [
-    "brands/growthub/brand-kit.md"
-  ],
-  "frozenAssetPaths": [
-    "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",
-    "SKILL.md",
-    "templates/project.md",
-    "templates/self-eval.md",
-    "helpers/README.md",
-    "skills/README.md"
-  ],
-  "setupPaths": {
-    "quickstart": "QUICKSTART.md",
-    "envExample": ".env.example",
-    "setupDir": "setup/",
-    "outputDir": "output/"
-  },
-  "outputStandard": {
-    "type": "working-directory",
-    "description": "Exported folder is intended to be pointed at directly by the agent Working Directory. All outputs are Markdown files written to output/<client-slug>/<project-slug>/.",
-    "requiredPaths": [
-      "QUICKSTART.md",
-      ".env.example",
-      "kit.json",
-      "bundles/growthub-geo-seo-v1.json",
-      "skills.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",
-      "docs",
-      "growthub-meta",
-      "SKILL.md",
-      "templates/project.md",
-      "templates/self-eval.md",
-      "helpers",
-      "helpers/README.md",
-      "skills",
-      "skills/README.md"
-    ]
-  },
-  "bundles": [
-    {
-      "id": "growthub-geo-seo-v1",
-      "version": "1.0.0",
-      "path": "bundles/growthub-geo-seo-v1.json"
-    }
-  ],
-  "executionMode": "export",
-  "activationModes": [
-    "export"
-  ],
-  "compatibility": {
-    "cliMinVersion": "0.3.50"
-  },
-  "provenance": {
-    "sourceRepo": "growthub-local",
-    "frozenAt": "2026-04-14T00:00:00.000Z"
-  },
-  "workspaceVisibility": "addon",
-  "workspaceCompatible": false,
-  "workspaceCategory": "studio"
-}

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

@@ -1,114 +0,0 @@
-# Output Directory
-
-All GEO SEO audit artifacts are written here. Each client gets a subdirectory. Each engagement gets a project subdirectory.
-
----
-
-## Directory Structure
-
-```
-output/
-  <client-slug>/
-    <project-slug>/
-      GeoAuditBrief_v1_YYYYMMDD.md
-      CitabilityAnalysis_v1_YYYYMMDD.md
-      CrawlerAccessReport_v1_YYYYMMDD.md
-      BrandVisibilityReport_v1_YYYYMMDD.md
-      GeoScoreSummary_v1_YYYYMMDD.md
-      ContentAnalysis_v1_YYYYMMDD.md
-      SchemaValidation_v1_YYYYMMDD.md
-      TechnicalFoundations_v1_YYYYMMDD.md
-      LlmstxtPlan_v1_YYYYMMDD.md
-      RemediationRoadmap_v1_YYYYMMDD.md
-      ClientProposal_v1_YYYYMMDD.md        (if requested)
-      geo_score_data.json                  (machine-readable score data for PDF generation)
-      <ClientSlug>_GeoScoreReport_v1_YYYYMMDD.pdf  (if PDF delivery requested)
-```
-
----
-
-## File Naming Convention
-
-```
-<ClientSlug>_<OutputType>_v<N>_<YYYYMMDD>.md
-```
-
-| Part | Format | Example |
-|---|---|---|
-| ClientSlug | TitleCase, no spaces | `GrowthHub` |
-| OutputType | CamelCase artifact type | `GeoScoreSummary` |
-| Version | `v` + integer | `v1`, `v2` |
-| Date | `YYYYMMDD` | `20260414` |
-
-Full example: `GrowthHub_GeoScoreSummary_v1_20260414.md`
-
----
-
-## Artifact Types (9 Core + 2 Optional)
-
-| Artifact | File Name Pattern | Description |
-|---|---|---|
-| GEO Audit Brief | `GeoAuditBrief_v<N>_<YYYYMMDD>.md` | Project scope, objective, command plan |
-| Citability Analysis | `CitabilityAnalysis_v<N>_<YYYYMMDD>.md` | 5-metric citability score with component breakdown |
-| Crawler Access Report | `CrawlerAccessReport_v<N>_<YYYYMMDD>.md` | 14 AI crawler permission matrix |
-| Brand Visibility Report | `BrandVisibilityReport_v<N>_<YYYYMMDD>.md` | 8-platform brand mention scan |
-| GEO Score Summary | `GeoScoreSummary_v<N>_<YYYYMMDD>.md` | 6-component weighted composite score |
-| Content Analysis | `ContentAnalysis_v<N>_<YYYYMMDD>.md` | E-E-A-T, answer blocks, statistical density |
-| Schema Validation | `SchemaValidation_v<N>_<YYYYMMDD>.md` | Structured data coverage and errors |
-| Technical Foundations | `TechnicalFoundations_v<N>_<YYYYMMDD>.md` | Server headers, Core Web Vitals signals |
-| llms.txt Plan | `LlmstxtPlan_v<N>_<YYYYMMDD>.md` | llms.txt implementation plan and files |
-| Remediation Roadmap | `RemediationRoadmap_v<N>_<YYYYMMDD>.md` | 4-week sprint plan with owners |
-| Client Proposal | `ClientProposal_v<N>_<YYYYMMDD>.md` | Agency proposal with pricing and ROI |
-| PDF Report | `<ClientSlug>_GeoScoreReport_v<N>_<YYYYMMDD>.pdf` | Branded PDF for stakeholder delivery |
-
----
-
-## Usage Notes
-
-- **Never edit output files directly.** Always run a new audit and increment the version number.
-- **Version numbering:** Start at v1. Increment on each rescore or significant update.
-- **Rescore tracking:** Compare GEO Score Summary files across versions to track improvement.
-- **Brand kit log:** The operator appends a line to the brand kit's DELIVERABLES LOG after each package is delivered.
-
----
-
-## Deliverable Tracking Format
-
-Append this line to `brands/<client-slug>/brand-kit.md` after each delivery:
-
-```
-- YYYY-MM-DD | GEO SEO Audit Package v<N> — <Project Name> | output/<client-slug>/<project-slug>/
-```
-
-Examples:
-```
-- 2026-04-14 | GEO SEO Audit Package v1 — Studio Launch Reference | output/growthub/studio-launch-reference/
-- 2026-05-01 | GEO SEO Audit Package v1 — UrbanCycle Full Audit | output/urban-cycle/full-audit-q2-2026/
-- 2026-05-15 | GEO SEO Audit Package v2 — UrbanCycle Post-Remediation Rescore | output/urban-cycle/rescore-may-2026/
-```
-
----
-
-## Example Layout (Populated)
-
-```
-output/
-  growthub/
-    studio-launch-reference/
-      GeoAuditBrief_v1_20260414.md
-      CitabilityAnalysis_v1_20260414.md
-      CrawlerAccessReport_v1_20260414.md
-      BrandVisibilityReport_v1_20260414.md
-      GeoScoreSummary_v1_20260414.md
-      ContentAnalysis_v1_20260414.md
-      SchemaValidation_v1_20260414.md
-      TechnicalFoundations_v1_20260414.md
-      LlmstxtPlan_v1_20260414.md
-      RemediationRoadmap_v1_20260414.md
-      geo_score_data.json
-      GrowthHub_GeoScoreReport_v1_20260414.pdf
-  urban-cycle/
-    full-audit-q2-2026/
-      GeoAuditBrief_v1_20260501.md
-      ...
-```

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

@@ -1,143 +0,0 @@
-# Output Standards
-
-**All GEO SEO Operator outputs must meet these standards before being delivered to a client.**
-
----
-
-## Output Directory Structure
-
-```
-output/
-  <client-slug>/
-    <project-slug>/
-      GeoAuditBrief_v<N>_<YYYYMMDD>.md
-      CitabilityAnalysis_v<N>_<YYYYMMDD>.md
-      CrawlerAccessReport_v<N>_<YYYYMMDD>.md
-      BrandVisibilityReport_v<N>_<YYYYMMDD>.md
-      GeoScoreSummary_v<N>_<YYYYMMDD>.md
-      ContentAnalysis_v<N>_<YYYYMMDD>.md
-      SchemaValidation_v<N>_<YYYYMMDD>.md
-      TechnicalFoundations_v<N>_<YYYYMMDD>.md
-      LlmstxtPlan_v<N>_<YYYYMMDD>.md
-      RemediationRoadmap_v<N>_<YYYYMMDD>.md
-      ClientProposal_v<N>_<YYYYMMDD>.md       (if requested)
-      geo_score_data.json                     (always — powers PDF and rescores)
-      <ClientSlug>_GeoScoreReport_v<N>_<YYYYMMDD>.pdf  (if PDF requested)
-```
-
----
-
-## File Naming Convention
-
-```
-<ClientSlug>_<OutputType>_v<N>_<YYYYMMDD>.md
-```
-
-| Part | Rules | Example |
-|---|---|---|
-| ClientSlug | TitleCase, no spaces, no special chars | `UrbanCycle` |
-| OutputType | CamelCase from the list below | `GeoScoreSummary` |
-| Version | `v` + integer, starting at 1 | `v1` |
-| Date | `YYYYMMDD` format | `20260414` |
-
-**Output type names:**
-
-| Artifact | OutputType string |
-|---|---|
-| GEO Audit Brief | `GeoAuditBrief` |
-| Citability Analysis | `CitabilityAnalysis` |
-| Crawler Access Report | `CrawlerAccessReport` |
-| Brand Visibility Report | `BrandVisibilityReport` |
-| GEO Score Summary | `GeoScoreSummary` |
-| Content Analysis | `ContentAnalysis` |
-| Schema Validation | `SchemaValidation` |
-| Technical Foundations | `TechnicalFoundations` |
-| llms.txt Plan | `LlmstxtPlan` |
-| Remediation Roadmap | `RemediationRoadmap` |
-| Client Proposal | `ClientProposal` |
-
----
-
-## Required Sections Per Artifact
-
-Each artifact must include all sections from its template. Incomplete sections must be marked `<!-- data-gap: reason -->` — never left blank without explanation.
-
-| Artifact | Minimum Required Sections |
-|---|---|
-| GeoAuditBrief | Project Overview table, Audit Objective, Command Selection Plan, Success Criteria |
-| CitabilityAnalysis | URL Audited, Citability Score table, Component Breakdown table, Top 3 Improvements |
-| CrawlerAccessReport | URL Audited, Crawler Permission Matrix (all 14 rows), Summary, Recommended Actions |
-| BrandVisibilityReport | Brand Audited, Platform Scan table (all 8 rows), Brand Authority Score, Gap Analysis |
-| GeoScoreSummary | Overall GEO Score (number + grade), Component Scores table, Score Narrative, Priority Recommendations |
-| ContentAnalysis | E-E-A-T Assessment table, Answer Block Analysis, Self-Containment Check, Content Quality Score |
-| SchemaValidation | Schema Types Found table, Validation Errors table, Missing Recommended Types, Implementation Priority |
-| TechnicalFoundations | Server Headers table, Core Signals table, Technical Score, Critical Fixes |
-| LlmstxtPlan | Current Status, Proposed llms.txt content, Proposed llms-full.txt content, Implementation Steps |
-| RemediationRoadmap | Current vs. Target Score, 4-Week Sprint Plan (all 4 weeks), Estimated Score After Roadmap |
-| ClientProposal | GEO Audit Summary, Why GEO Matters Now, 3 Critical Issues, Recommended Engagement (all 3 tiers), ROI Projection |
-
----
-
-## Quality Bar
-
-### Data-Grounded
-
-- Every score must be derived from actual page data, not estimated without basis
-- If a score cannot be determined (e.g., robots.txt returns 500), use 50 and flag as `data-gap`
-- Never invent a score to complete a section — a flagged gap is more useful than a fabricated number
-
-### No Filler
-
-- Every sentence must either present data, explain a finding, or specify an action
-- Remove phrases like "This is an important area to consider" — replace with the actual consideration
-- Recommendations must be specific: name the exact robots.txt line, the exact schema type, the exact paragraph to rewrite
-
-### Actionable
-
-- Every finding must have a corresponding action in the Remediation Roadmap
-- Actions must include: what to do, who should do it, how long it should take, what the expected impact is
-- Code snippets in SchemaValidation must be copy-pasteable
-
-### Consistent
-
-- All scores in all artifacts must match — the GEO Score in GeoScoreSummary must equal the calculated composite from all component scores
-- Dates must be consistent across all artifacts
-- Client name and URL must match the brand kit exactly
-
-### Output Order
-
-Artifacts must be produced and numbered in this order:
-
-1. GeoAuditBrief
-2. CitabilityAnalysis
-3. CrawlerAccessReport
-4. BrandVisibilityReport
-5. GeoScoreSummary
-6. ContentAnalysis
-7. SchemaValidation
-8. TechnicalFoundations
-9. LlmstxtPlan
-10. RemediationRoadmap
-11. ClientProposal (if requested)
-
----
-
-## Versioning Rules
-
-| Scenario | Action |
-|---|---|
-| First audit for a client | All files at v1 |
-| Rescore after remediation | Increment all files to v2 (or current version + 1) |
-| Partial update (one artifact revised) | Increment only the revised artifact's version |
-| Major scope change | Start new project-slug, all files at v1 |
-
----
-
-## geo_score_data.json
-
-This file must always be written to the output directory. It is the machine-readable record of the audit and is required for:
-- PDF generation (`generate_pdf_report.py`)
-- Rescore comparison (load v1 data, compare to v2)
-- CRM dashboard import (`crm_dashboard.py`)
-
-See `examples/pdf-report-sample.md` for the complete format.