Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

Initial commit — toprank SEO & Google Ads skills for Claude Code

Tongac331b888541
diff --git a/.agents/skills/toprank-content-writer/SKILL.md b/.agents/skills/toprank-content-writer/SKILL.md
new file mode 120000
index 00000000..ebcdb779
--- /dev/null
+++ b/.agents/skills/toprank-content-writer/SKILL.md
@@ -0,0 +1 @@
+/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/content-writer/SKILL.md
\ No newline at end of file
diff --git a/.agents/skills/toprank-content-writer/agents/openai.yaml b/.agents/skills/toprank-content-writer/agents/openai.yaml
new file mode 100644
index 00000000..0ebf11fb
--- /dev/null
+++ b/.agents/skills/toprank-content-writer/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+ display_name: "toprank-content-writer"
+ short_description: "Write SEO-optimized blog posts, landing pages, and content improvements following Google's E-E-A-T and Helpful Content"
+ default_prompt: "Use toprank-content-writer for this task."
+policy:
+ allow_implicit_invocation: true
diff --git a/.agents/skills/toprank-content-writer/references b/.agents/skills/toprank-content-writer/references
new file mode 120000
index 00000000..56eeab48
--- /dev/null
+++ b/.agents/skills/toprank-content-writer/references
@@ -0,0 +1 @@
+/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/content-writer/references
\ No newline at end of file
diff --git a/.agents/skills/toprank-keyword-research/SKILL.md b/.agents/skills/toprank-keyword-research/SKILL.md
new file mode 120000
index 00000000..66411967
--- /dev/null
+++ b/.agents/skills/toprank-keyword-research/SKILL.md
@@ -0,0 +1 @@
+/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/keyword-research/SKILL.md
\ No newline at end of file
diff --git a/.agents/skills/toprank-keyword-research/agents/openai.yaml b/.agents/skills/toprank-keyword-research/agents/openai.yaml
new file mode 100644
index 00000000..752ad956
--- /dev/null
+++ b/.agents/skills/toprank-keyword-research/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+ display_name: "toprank-keyword-research"
+ short_description: "Discover, analyze, and prioritize keywords for SEO and GEO content strategies. Identifies high-value opportunities bas"
+ default_prompt: "Use toprank-keyword-research for this task."
+policy:
+ allow_implicit_invocation: true
diff --git a/.agents/skills/toprank-keyword-research/references b/.agents/skills/toprank-keyword-research/references
new file mode 120000
index 00000000..491b0fc9
--- /dev/null
+++ b/.agents/skills/toprank-keyword-research/references
@@ -0,0 +1 @@
+/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/keyword-research/references
\ No newline at end of file
diff --git a/.agents/skills/toprank-meta-tags-optimizer/SKILL.md b/.agents/skills/toprank-meta-tags-optimizer/SKILL.md
new file mode 120000
index 00000000..72dc9179
--- /dev/null
+++ b/.agents/skills/toprank-meta-tags-optimizer/SKILL.md
@@ -0,0 +1 @@
+/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/meta-tags-optimizer/SKILL.md
\ No newline at end of file
diff --git a/.agents/skills/toprank-meta-tags-optimizer/agents/openai.yaml b/.agents/skills/toprank-meta-tags-optimizer/agents/openai.yaml
new file mode 100644
index 00000000..d9c5badf
--- /dev/null
+++ b/.agents/skills/toprank-meta-tags-optimizer/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+ display_name: "toprank-meta-tags-optimizer"
+ short_description: "Optimize title tags, meta descriptions, Open Graph, and Twitter cards for maximum click-through rate. Generates multip"
+ default_prompt: "Use toprank-meta-tags-optimizer for this task."
+policy:
+ allow_implicit_invocation: true
diff --git a/.agents/skills/toprank-meta-tags-optimizer/references b/.agents/skills/toprank-meta-tags-optimizer/references
new file mode 120000
index 00000000..30219818
--- /dev/null
+++ b/.agents/skills/toprank-meta-tags-optimizer/references
@@ -0,0 +1 @@
+/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/meta-tags-optimizer/references
\ No newline at end of file
diff --git a/.agents/skills/toprank-schema-markup-generator/SKILL.md b/.agents/skills/toprank-schema-markup-generator/SKILL.md
new file mode 120000
index 00000000..25e24dd4
--- /dev/null
+++ b/.agents/skills/toprank-schema-markup-generator/SKILL.md
@@ -0,0 +1 @@
+/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/schema-markup-generator/SKILL.md
\ No newline at end of file
diff --git a/.agents/skills/toprank-schema-markup-generator/agents/openai.yaml b/.agents/skills/toprank-schema-markup-generator/agents/openai.yaml
new file mode 100644
index 00000000..7d1e49c2
--- /dev/null
+++ b/.agents/skills/toprank-schema-markup-generator/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+ display_name: "toprank-schema-markup-generator"
+ short_description: "Generate JSON-LD structured data markup for rich results in Google Search. Supports FAQ, HowTo, Article, Product, Loca"
+ default_prompt: "Use toprank-schema-markup-generator for this task."
+policy:
+ allow_implicit_invocation: true
diff --git a/.agents/skills/toprank-schema-markup-generator/references b/.agents/skills/toprank-schema-markup-generator/references
new file mode 120000
index 00000000..f1715344
--- /dev/null
+++ b/.agents/skills/toprank-schema-markup-generator/references
@@ -0,0 +1 @@
+/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/schema-markup-generator/references
\ No newline at end of file
diff --git a/.agents/skills/toprank-seo-analysis/SKILL.md b/.agents/skills/toprank-seo-analysis/SKILL.md
new file mode 120000
index 00000000..5b68fff8
--- /dev/null
+++ b/.agents/skills/toprank-seo-analysis/SKILL.md
@@ -0,0 +1 @@
+/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/seo-analysis/SKILL.md
\ No newline at end of file
diff --git a/.agents/skills/toprank-seo-analysis/agents/openai.yaml b/.agents/skills/toprank-seo-analysis/agents/openai.yaml
new file mode 100644
index 00000000..ab71d020
--- /dev/null
+++ b/.agents/skills/toprank-seo-analysis/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+ display_name: "toprank-seo-analysis"
+ short_description: "Full SEO audit: Google Search Console data + URL Inspection API + technical crawl + keyword research + metadata audit "
+ default_prompt: "Use toprank-seo-analysis for this task."
+policy:
+ allow_implicit_invocation: true
diff --git a/.agents/skills/toprank-seo-analysis/references b/.agents/skills/toprank-seo-analysis/references
new file mode 120000
index 00000000..525a6eac
--- /dev/null
+++ b/.agents/skills/toprank-seo-analysis/references
@@ -0,0 +1 @@
+/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/seo-analysis/references
\ No newline at end of file
diff --git a/.agents/skills/toprank-seo-analysis/scripts b/.agents/skills/toprank-seo-analysis/scripts
new file mode 120000
index 00000000..561bba82
--- /dev/null
+++ b/.agents/skills/toprank-seo-analysis/scripts
@@ -0,0 +1 @@
+/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/seo-analysis/scripts
\ No newline at end of file
diff --git a/.agents/skills/toprank-toprank-upgrade/SKILL.md b/.agents/skills/toprank-toprank-upgrade/SKILL.md
new file mode 120000
index 00000000..759d9515
--- /dev/null
+++ b/.agents/skills/toprank-toprank-upgrade/SKILL.md
@@ -0,0 +1 @@
+/Users/tongchen/Documents/Projects/ads-agent/.claude/skills/toprank/toprank-upgrade/SKILL.md
\ No newline at end of file
diff --git a/.agents/skills/toprank-toprank-upgrade/agents/openai.yaml b/.agents/skills/toprank-toprank-upgrade/agents/openai.yaml
new file mode 100644
index 00000000..f2b73b2b
--- /dev/null
+++ b/.agents/skills/toprank-toprank-upgrade/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+ display_name: "toprank-toprank-upgrade"
+ short_description: "Upgrade toprank skills to the latest version. Detects global vs vendored install, runs the upgrade, and shows what's n"
+ default_prompt: "Use toprank-toprank-upgrade for this task."
+policy:
+ allow_implicit_invocation: true
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 00000000..02caf1b5
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+
+# Credentials — never commit these
+credentials.json
+token.json
+service-account*.json
+*-credentials.json
+.env
+.env.local
+
+# GSC output files
+/tmp/
+
+# macOS
+.DS_Store
+
+# Editor
+.vscode/
+.idea/
+*.swp
+
+# Test artifacts
+.pytest_cache/
+
+# Security reports and local tool state (never commit)
+.gstack/
+
+# Skill eval workspaces — local scratch data, not for repo
+*-workspace/
+
+# Git worktrees and Claude worktrees
+.git/worktrees/
+.claude/worktrees/
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 00000000..163d7eaf
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,265 @@
+# Changelog
+
+All notable changes to Toprank will be documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [0.8.0] — 2026-03-31
+
+### Added
+- **`/setup-cms` skill** — interactive wizard to connect WordPress, Strapi, Contentful, or Ghost. Detects existing config, collects credentials, tests the connection, and writes to `.env.local`.
+- **WordPress CMS integration** (Phase 3.6) — `preflight_wordpress.py` + `fetch_wordpress_content.py`. REST API with Application Password auth. Extracts SEO fields from Yoast SEO (`yoast_head_json`) or RankMath (`meta.rank_math_title`).
+- **Contentful CMS integration** (Phase 3.6) — `preflight_contentful.py` + `fetch_contentful_content.py`. Delivery API with Bearer token auth. Resolves linked SEO component entries (`include=1`), supports pagination up to 1000 entries/page.
+- **Ghost CMS integration** (Phase 3.6) — `preflight_ghost.py` + `fetch_ghost_content.py`. Content API with auto-detection between v4+ (`/ghost/api/content/`) and v3 (`/ghost/api/v3/content/`). Uses native `meta_title`/`meta_description` fields.
+- **`cms_detect.py`** — lightweight CMS routing script. Checks env vars in priority order (WP_URL → Contentful → Ghost → Strapi), exits 0 with CMS name if found, exits 2 if none configured.
+- **56 unit tests** (`test/unit/test_cms_scripts.py`) covering SEO field extraction, entry normalisation, SEO audit aggregation, SSRF protection, and WordPress auth header encoding across all 4 CMSes.
+
+### Changed
+- **`seo-analysis` Phase 3.6** — rewritten from Strapi-specific to CMS-agnostic. Now routes through `cms_detect.py` and runs the appropriate preflight + fetch script via `case` statement. All CMSes produce the same normalized JSON format.
+- Report template: "Strapi SEO Field Audit" → "CMS SEO Field Audit" (supports WordPress, Strapi, Contentful, Ghost).
+
+### Fixed
+- **Ghost/WordPress/Contentful false negatives** — SEO extraction no longer falls back to the content title when no explicit meta title is set. Entries with no SEO plugin / no meta title override are now correctly flagged as `missing_meta_title=True`.
+- **Ghost `detect_api_path` sys.exit trap** — replaced `ghost_get()` probe (which calls `sys.exit(1)` on errors) with inline `urllib` probe, allowing the v3 API path fallback to actually run.
+- **Ghost `PAGE_SIZE`** — changed from 15 (display default) to 100 (actual API max).
+
+---
+
+## [0.7.1] — 2026-04-01
+
+### Fixed
+- **`seo-analysis` — GSC display crash** — added `show_gsc.py` display utility to replace fragile inline Python scripts. Fixes `TypeError: string indices must be integers, not 'str'` that occurred when iterating `comparison` dict fields (which mixes string metadata and list data at the same level). Also fixes CTR being displayed as 474% instead of 4.74% (was being multiplied by 100 twice).
+
+---
+
+## [0.7.0] — 2026-04-01
+
+### Added
+- **`seo-analysis` — URL-first flow** — Step 0 now asks for the target website URL before running any preflight or API calls. The URL is stored and used throughout the entire audit for URL Inspection, technical crawl, and metadata fetching.
+- **`seo-analysis` — URL Inspection API** (Phase 3.5) — new `url_inspection.py` script calls `POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect` for the top pages. Returns per-page indexing status (`INDEXED`, `NOT_INDEXED`, `DUPLICATE_WITHOUT_CANONICAL`, etc.), mobile usability verdict, rich result status, last crawl time, and referring sitemaps. Results surface immediately as critical flags in the report.
+- **`seo-analysis` — Keyword Gap Analysis** (Phase 4.5) — finds keyword orphans (queries ranking 4-20 with no dedicated page), builds topic clusters from GSC data with pillar page recommendations, and identifies business-relevant keywords the site should rank for but has no impressions for.
+- **`seo-analysis` — Deep Metadata Audit** — for each audited page, fetches the live `<title>` and `<meta description>`, cross-references against top GSC queries for title/query alignment, checks character counts, detects duplicate titles, and audits Open Graph tags. Outputs a structured per-page table.
+- **`seo-analysis` — Deep Schema Markup Audit** — detects site type (E-commerce, SaaS, Local Business, etc.), defines expected schema types per site type, audits each page's `<script type="application/ld+json">` blocks, and flags missing high-impact schema and errors in existing schema. Cross-references with URL Inspection rich result findings.
+- **`seo-analysis` — Skill Handoffs** (Phase 7) — after delivering the report, surfaces targeted follow-up actions: `/meta-tags-optimizer` for pages with metadata issues, `/schema-markup-generator` for schema gaps, `/keyword-research` with seed terms from the gap analysis.
+- **Branded vs non-branded segmentation** (`branded_split`) — pass `--brand-terms "Acme,AcmeCorp"` to split all GSC traffic into branded and non-branded segments. Each segment gets its own clicks, impressions, CTR, average position, query count, and top-20 queries. Non-branded metrics become the true baseline for Quick Wins and content recommendations. Returns `null` if no brand terms provided.
+- **Page group clustering** (`page_groups`) — automatically buckets top pages by URL path pattern (/blog/, /products/, /locations/, /services/, /pricing/, /docs/, /about/, /faq/, /lp/, /case-studies/) with per-section aggregate stats. Exposes template-level problems: "all /products/ pages have 0.8% CTR" can be fixed once, not 50 times.
+- **Winner/loser scoring for cannibalization** — each `cannibalization` entry now includes `winner_page`, `winner_reason`, `loser_pages`, and `recommended_action` ("consolidate: 301 redirect..." or "monitor: possible SERP domination").
+- **`test/unit/test_url_inspection.py`** — 25 unit tests covering `normalize_site_url_for_inspection`, `parse_inspection_result`, and `summarize_findings`.
+- **35 new unit tests** covering `classify_branded`, `derive_branded_split`, `cluster_page_groups`, and all new cannibalization fields.
+- **Strapi CMS integration** (Phase 3.6) — the `/seo-analysis` skill now cross-references your published Strapi content against GSC data. Three new scripts:
+ - **`preflight_strapi.py`** — validates config, tests connectivity, detects Strapi v4 vs v5. Exit code 2 = not configured (non-fatal skip).
+ - **`fetch_strapi_content.py`** — paginates all published entries, extracts SEO fields from the official `strapi-community/plugin-seo` component and root-level fallbacks, writes a structured JSON audit.
+ - **`push_strapi_seo.py`** — batch write-back with before/after diff preview, stale-write guard, and locale support for v5 localized content.
+- **59 new unit tests** for the Strapi scripts — version detection, entry normalisation, SEO audit counting, payload building, stale-write guard logic, and SSRF IP classification.
+
+### Changed
+- **`seo-analysis` — `analyze_gsc.py` parallelized** — all 9 GSC API calls now run concurrently via `ThreadPoolExecutor`, cutting wall-clock data collection time by ~70%. Each worker has an exception guard so a single failed call logs an error and continues rather than crashing the script.
+- **`url_inspection.py` — parallel URL inspection** — inspections run with `--concurrency 3` (default). `--max-urls` default reduced from 20 to 5 to stay well within the 2000/day API quota. Worker failures are caught and logged without aborting the run.
+- **`seo-analysis` — technical crawl capped at 5 pages** — Phase 5 now has a hard cap of 5 pages (homepage first, then top by clicks, then flagged pages) to keep the audit fast without losing insight.
+- **`seo-analysis` — broader OAuth scope** — re-auth instructions throughout the skill now include both `webmasters` and `webmasters.readonly` scopes, required for the URL Inspection API.
+- **`seo-analysis`** Phase 2 now asks for brand terms before pulling data.
+- **`seo-analysis`** Phase 4 adds "Branded vs Non-Branded Split" and "Page Group Performance" sections.
+- **`seo-analysis/evals/evals.json`** — 3-scenario test suite covering URL-first behavior, no-GSC technical fallback, and comprehensive GSC+inspection audit.
+- Cannibalization `competing_pages` now sorted by position ascending (best first) instead of clicks descending.
+- Strapi integration is **opt-in and non-blocking** — if `STRAPI_URL` is not configured, Phase 3.6 skips silently.
+
+---
+
+## [0.6.1] — 2026-03-31
+
+### Added
+- **`test/install.test.sh`** — mock-HOME install test suite for `./setup`. 61 assertions across 6 scenarios: Claude Code global install (symlinks, targets, preamble injection), auto-detect via path, idempotency, real-directory protection, Codex install (openai.yaml + SKILL.md symlinks), and invalid `--host` flag handling. Includes a count-guard that fails fast if a new skill is added to the repo without updating the test's SKILLS array.
+
+### Changed
+- **`seo-analysis`** — deeper Google Search Console data in every audit. The script now pulls four additional data sets from a single API session:
+ - **Cannibalization** (`cannibalization`) — queries where multiple pages compete, with per-page click/impression breakdown. Previously the skill inferred this from single-dimension data; now it uses the real `[query, page]` dimension so every recommendation names specific URLs.
+ - **CTR gaps by page** (`ctr_gaps_by_page`) — high-impression, low-CTR pairs at the query+page level. Replaces query-only CTR opportunities so every title/meta rewrite suggestion includes the exact page to fix.
+ - **Country split** (`country_split`) — top 20 countries by clicks with CTR and position. Surfaces geo opportunities and region-specific ranking problems.
+ - **Search type breakdown** (`search_type_split`) — web, image, video, news, Discover, and Google News traffic shown separately. Many sites have Discover or image traffic they don't know about.
+- `device_split` now includes CTR and position alongside clicks and impressions.
+- Phase 4 analysis guidance updated to use the new data fields directly.
+- New "Segment Analysis" subsection added to Phase 4 for device, country, and search type interpretation.
+- Unit tests: 49 → 79 (+30 tests covering all new functions with boundary and edge case coverage).
+
+---
+
+## [0.6.0] — 2026-03-30
+
+### Added
+- **`keyword-research`** — new skill for keyword discovery, intent classification, difficulty assessment, opportunity scoring, and topic clustering. Includes reference materials for intent taxonomy, prioritization framework, cluster templates, and example reports.
+- **`meta-tags-optimizer`** — new skill for creating and optimizing title tags, meta descriptions, Open Graph, and Twitter Card tags with A/B test variations and CTR analysis. Includes reference materials for tag formulas, CTR benchmarks, and code templates.
+- **`schema-markup-generator`** — new skill for generating JSON-LD structured data (FAQ, HowTo, Article, Product, LocalBusiness, etc.) with validation guidance and rich result eligibility checks. Includes reference materials for schema templates, decision tree, and validation guide.
+- **`geo-content-optimizer`** — new skill for optimizing content to appear in AI-generated responses (ChatGPT, Perplexity, Google AI Overviews, Claude). Scores GEO readiness and applies citation, authority, and structure optimization techniques. Includes reference materials for AI citation patterns, GEO techniques, and quotable content examples.
+
+### Changed
+- **README.md** — updated with documentation for all 4 new skills, expanded install instructions and directory tree
+
+---
+
+## [0.5.1] — 2026-03-27
+
+### Security
+- **Predictable /tmp paths** — `analyze_gsc.py` and `list_gsc_sites.py` now use `gsc_analysis_{uid}.json` / `gsc_sites_{uid}.json` via `tempfile.gettempdir()` + `os.getuid()`, preventing cross-user data exposure on multi-user systems
+- **`.gstack/` gitignored** — local security audit reports excluded from git history
+- **Test dependency lockfile** — added `requirements-test.lock` (pip-compiled) to pin test dependencies and prevent supply-chain drift
+
+---
+
+## [0.5.0] — 2026-03-27
+
+### Added
+- **`preflight.py`** — pre-flight check that runs before any GSC operations; detects gcloud with OS-specific install instructions (Homebrew / apt / dnf / curl / winget), auto-triggers `gcloud auth` browser flow if no ADC credentials found
+- **`setup.py`** — cross-platform Python equivalent of `./setup` for Windows users who can't run bash; falls back to directory junctions (no admin rights required) when symlinks are unavailable
+- **Phase 0 in SKILL.md** — preflight step added before GSC access check; also restores the "skip GSC → Phase 5" escape hatch for technical-only audits
+
+### Changed
+- **`seo-analysis/SKILL.md`** — Phase 1 simplified (error cases now handled by preflight); Phase 1 bash block is self-contained (no shell variable leak from Phase 0)
+
+---
+
+## [0.4.2] — 2026-03-27
+
+### Added
+- **README demo section** — "See It Work" example conversation showing end-to-end `/seo-analysis` flow for clearer onboarding
+
+### Changed
+- **Auto-upgrade on every skill use** — removed the 4-option prompt (Yes / Always / Not now / Never); updates now apply automatically whenever `UPGRADE_AVAILABLE` is detected
+- **Update check frequency** — reduced UP_TO_DATE cache TTL from 60 min to 5 min so checks run on nearly every skill invocation
+- **Zero-dependency GSC auth** — removed `google-auth` Python package requirement; reverts 0.4.1 approach; scripts now call `gcloud auth application-default print-access-token` directly via subprocess and use stdlib `urllib` for HTTP, eliminating the `pip install` setup step
+- **`gsc_auth.py` removed** — auth logic inlined in `list_gsc_sites.py` and `analyze_gsc.py`; simpler, no shared module
+- **SKILL.md Phase 1** — GSC setup instructions updated to reflect the simpler auth flow
+
+### Security
+- **Predictable /tmp paths** — GSC output files now use `gsc_analysis_{uid}.json` and `gsc_sites_{uid}.json` instead of shared paths, preventing cross-user data exposure on multi-user systems
+- **`.gstack/` gitignored** — security audit reports are now excluded from git commits
+- **Test dependency lockfile** — added `requirements-test.lock` (pip-compiled) to pin exact versions and prevent supply-chain drift
+
+---
+
+## [0.4.1] — 2026-03-27
+
+### Fixed
+- **GSC quota project header** — replaced raw `urllib` HTTP calls with `google-auth` library (`AuthorizedSession`), which automatically sends the `x-goog-user-project` header required for ADC user credentials; this was the root cause of 403 errors during onboarding
+- **Auto-detect quota project** — scripts now read `quota_project_id` from ADC credentials and fall back to `gcloud config get-value project` if missing, eliminating the manual `set-quota-project` step
+
+### Changed
+- **Shared auth module** — extracted `gsc_auth.py` with `get_credentials()`, `get_session()`, and `_ensure_quota_project()` to eliminate duplicated auth logic between `list_gsc_sites.py` and `analyze_gsc.py`
+- **SKILL.md Phase 1** — streamlined GSC setup instructions from ~50 lines to ~25 lines for faster onboarding and lower token usage
+- **gsc_setup.md** — updated setup guide to reflect 2-step process (`pip install google-auth` + `gcloud auth application-default login`) and documented new troubleshooting entries
+
+### Added
+- **`google-auth` dependency** — new pip requirement for proper Google API authentication
+- **4 new unit tests** for `_ensure_quota_project()` covering: already-set, auto-detect from gcloud, gcloud not found, gcloud returns empty
+
+---
+
+## [0.4.0] — 2026-03-27
+
+### Added
+- **`content-writer` skill** — standalone SEO content creation, directly invocable without running a full SEO audit
+ - Handles three jobs: new blog posts, new landing pages, and improving existing pages
+ - 6-step workflow: determine job → gather context → read guidelines → research & plan → write → quality gate
+ - Follows Google's E-E-A-T and Helpful Content guidelines via shared reference doc
+ - Outputs publication-ready content with SEO metadata, JSON-LD structured data, internal linking plan, and publishing checklist
+ - Smart content type detection from user intent (informational → blog, transactional → landing page)
+- **`content-writing.md` reference doc** — single source of truth for Google content best practices (E-E-A-T framework, helpful content signals, blog/landing page templates, search intent matching, on-page SEO checklist, anti-patterns including AI content pitfalls)
+- **`seo-analysis` Phase 7** — optional content generation after audit; spawns up to 5 content agents in parallel when content gaps are identified, each reading the shared `content-writing.md` guidelines
+
+### Changed
+- **CONTRIBUTING.md** — expanded with detailed SKILL.md structure, script requirements, reference file guidelines, and skill ideas table
+- **README.md** — added `content-writer` to skills table and updated project description
+
+---
+
+## [0.3.0] — 2026-03-27
+
+### Added
+- **Python test suite** — full pytest infrastructure under `test/` replacing the prior TypeScript/Bun approach; no build step required
+ - `test/unit/` — 42 fast unit tests (stdlib only, no API calls); covers date math, GSC data processing, report structure, and skill SKILL.md content validation
+ - `test/test_skill_e2e.py` — E2E skill tests gated behind `EVALS=1`; uses mock `gcloud` + mock `analyze_gsc.py` fixture to run the full skill workflow without real credentials
+ - `test/test_skill_llm_eval.py` — LLM-as-judge quality evals gated behind `EVALS=1`; scores report clarity, actionability, and phase coverage on a 1–5 scale
+ - `test/test_skill_routing_e2e.py` — routing evals verify the skill triggers on SEO prompts and stays silent on unrelated requests
+ - `test/helpers/` — session runner (spawns `claude -p --output-format stream-json`), LLM judge, eval store, and diff-based test selection
+ - `test/fixtures/` — mock gcloud binary, mock analyze_gsc.py, and sample GSC JSON fixture data
+ - `conftest.py` — root-level pytest config for import path setup
+ - `requirements-test.txt` — minimal test dependencies
+
+### Fixed
+- **Routing tests** — added harness failure guard; `should-not-trigger` tests no longer silently pass when the subprocess times out or crashes
+- **Env isolation** — test subprocess now strips `ANTHROPIC_*` vars (in addition to `CLAUDE_*`) to prevent `ANTHROPIC_BASE_URL` or `ANTHROPIC_MODEL` from redirecting evals to an unintended endpoint
+- **LLM judge retry** — exponential backoff (3 attempts: 1s, 2s, 4s) replaces single-retry on rate limit
+- **Mock gcloud** — removed fall-through to real `gcloud` binary that caused infinite recursion when mock was first in PATH
+- **`.gitignore`** — restored credential patterns (`credentials.json`, `token.json`, `.env`, etc.) accidentally dropped in initial commit
+
+---
+
+## [0.2.3] — 2026-03-27
+
+### Changed
+- Simplified CONTRIBUTING.md — removed skill ideas table and verbose guidelines, kept essentials for getting started
+
+---
+
+## [0.2.2] — 2026-03-27
+
+### Changed
+- Rewrote README intro for clarity and power — headline now communicates that Toprank analyzes, recommends, and fixes SEO issues directly in your repo
+
+---
+
+## [0.2.0] — 2026-03-27
+
+### Added
+- **Autoupdate system** — skills now check GitHub for new versions on every invocation
+ - `bin/toprank-update-check` — fetches `VERSION` from GitHub with 60-min cache; outputs `UPGRADE_AVAILABLE <old> <new>` or nothing
+ - `bin/toprank-config` — read/write `~/.toprank/config.yaml`; supports `update_check`, `auto_upgrade` keys
+ - `toprank-upgrade/SKILL.md` — upgrade skill with inline and standalone flows, snooze (24h/48h/7d backoff), auto-upgrade mode, changelog diff
+ - Preamble in `seo-analysis` and auto-inject via `setup` for all future skills
+ - `bin/preamble.md` — single source of truth for the preamble template
+- `VERSION` file — tracks current release for update checks
+
+### Fixed
+- `toprank-update-check`: validate local VERSION format before writing cache; exit after `JUST_UPGRADED` to prevent dual stdout output; move `mkdir -p` to top of script
+- `setup`: atomic SKILL.md writes via temp file + `os.replace()`; add `pipefail` to catch silent Python errors
+- `toprank-upgrade`: clear stale `.bak` before vendored upgrade to prevent collision
+
+---
+
+## [0.2.1] — 2026-03-27
+
+### Changed
+- **`seo-analysis` Phase 1** — replaced two-step auth check (token print + separate site list) with single `list_gsc_sites.py` call that tests auth, scopes, and GSC access in one shot; added distinct handling for each failure mode (wrong account, wrong scopes, API not enabled, gcloud not installed)
+- **`seo-analysis` script paths** — replaced hardcoded `~/.claude/skills/seo-analysis/scripts/` with a `find`-based `SKILL_SCRIPTS` lookup that works for Claude Code, Codex, and custom install paths; added guard for empty result so missing installs fail with a clear error instead of a confusing path error
+- **`seo-analysis` property selection** — added explicit rule to prefer domain property (`sc-domain:example.com`) over URL-prefix when both exist for the same site
+- **`gsc_setup.md`** — moved "Which Google Account" guidance to top (most common failure cause); replaced broken `oauth_setup.py` Option B with Linux (Debian/Ubuntu, RPM) and Windows install instructions; fixed deprecated `apt-key` with `gpg --dearmor` for Debian 12+/Ubuntu 24.04+; expanded troubleshooting to cover `insufficient_scope` 403s
+
+### Fixed
+- **`list_gsc_sites.py`** — unhandled `FileNotFoundError` when gcloud is not installed now shows a clean error message; added `URLError` handling for network failures (DNS, TLS, proxy)
+- **`analyze_gsc.py`** — same `FileNotFoundError` and `URLError` fixes
+- **`gsc_setup.md`** — removed reference to `oauth_setup.py` which did not exist
+- **`seo-analysis` SKILL.md** — corrected error-branch description from "Python traceback" to "ERROR: gcloud not found" to match the actual script output
+
+---
+
+## [0.1.1] — 2026-03-27
+
+### Changed
+- **README intro** — rewritten to lead with user outcome ("Finally know what to do about your SEO") and emphasize zero-risk install; blockquote examples now show real questions users would type
+
+---
+
+## [0.1.0] — 2026-03-26
+
+### Added
+- **`seo-analysis` skill** — comprehensive SEO audit powered by Google Search Console
+ - Phase 1: GSC API setup detection and guided auth via `gcloud` Application Default Credentials
+ - Phase 2: Auto-detect site URL from website repo (`package.json`, `next.config.js`, `astro.config.*`, etc.) or prompt for URL
+ - Phase 3: Data collection — top queries, top pages, position buckets (1–3, 4–10, 11–20, 21+), CTR opportunities, 28-day period comparison, device split
+ - Phase 4a: Search Console analysis — quick wins, content gaps, traffic drops
+ - Phase 4b: Technical SEO audit — indexability, meta tags, heading structure, structured data, performance signals
+ - Phase 5: Structured report with executive summary, traffic snapshot, and 30-day action plan
+- `scripts/list_gsc_sites.py` — list all GSC properties for the authenticated account
+- `scripts/analyze_gsc.py` — pull and process GSC data, output structured JSON
+- `references/gsc_setup.md` — complete setup guide for gcloud ADC and OAuth fallback
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..41b51e9c
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,53 @@
+# Contributing
+
+Thanks for wanting to contribute! Here's how to get started.
+
+## Adding a Skill
+
+Each skill lives in its own folder under a category directory:
+
+```
+seo/ <- SEO skills go here
+└── your-skill-name/
+ ├── SKILL.md <- required
+ ├── scripts/ <- optional
+ └── references/ <- optional
+
+google-ads/ <- Google Ads skills go here
+└── your-skill-name/
+ ├── SKILL.md <- required
+ └── mcporter.json <- optional (for MCP server config)
+```
+
+### SKILL.md
+
+Every skill needs a frontmatter header:
+
+```yaml
+---
+name: your-skill-name
+description: >
+ One paragraph. Explain what the skill does AND when to trigger it.
+ Be specific about trigger phrases.
+---
+```
+
+Then the body: step-by-step instructions Claude will follow. Write in the imperative.
+
+> The update-check preamble is auto-injected by `./setup` — you don't need to add it manually.
+
+### Scripts
+
+- Python 3.8+ stdlib only (or `requests`)
+- Accept `--output` for file output
+- stderr for progress, stdout for data
+
+## Pull Requests
+
+1. One skill per PR
+2. Test your skill before submitting
+3. Bump `VERSION` and update `CHANGELOG.md`
+
+## Questions
+
+Open an issue. We're friendly.
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 00000000..854bbb3a
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toprank Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..5d5cde4b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,327 @@
+# Toprank
+
+**SEO + Google Ads skills for Claude Code and Codex. Data-driven decisions, not dashboards.**
+
+Toprank gives your AI agent direct access to Google Search Console and Google Ads. It analyzes your traffic, surfaces what's hurting your rankings, finds wasted ad spend, and tells you exactly what to fix. When you have access to the repo, it goes further: rewriting meta tags, fixing headings, adding structured data, and shipping the changes.
+
+> *"Why did my traffic drop last month?"*
+> *"What keywords am I almost ranking for?"*
+> *"How are my ads doing? Find wasted spend."*
+
+Free, open-source. Install in 30 seconds.
+
+---
+
+## See It Work
+
+### Google Ads
+
+```
+You: /ads-audit
+
+Claude: Connected to your Google Ads account (MyStore).
+
+ 3 campaigns active. $2,400 spent this month.
+
+ Scorecard:
+ ┌──────────────────────┬──────────┬──────────────────────────────┐
+ │ Dimension │ Status │ Summary │
+ ├──────────────────────┼──────────┼──────────────────────────────┤
+ │ Conversion tracking │ OK │ 3 actions firing correctly │
+ │ Keyword health │ Critical │ 8 keywords burning cash │
+ │ Search term quality │ Warning │ 12 irrelevant queries │
+ │ Impression share │ Warning │ Losing 35% to rank │
+ │ Spend efficiency │ Critical │ $340/mo wasted │
+ └──────────────────────┴──────────┴──────────────────────────────┘
+
+ Top 3 actions:
+ 1. Pause 3 keywords ($210/mo, zero conversions)
+ 2. Add 12 negative keywords ($130/mo wasted on irrelevant terms)
+ 3. Increase bids 15% on 2 high-converting keywords losing IS
+
+ Business context saved — /ads-copy and /ads will use it.
+
+You: Do it all.
+
+ [paused 3 wasteful keywords — saved $210/mo]
+ [added 12 negative keywords — saved $130/mo]
+ [increased bids on 2 high-performers]
+
+ Done. All changes are reversible within 7 days.
+```
+
+```
+You: Write new ad copy for my boarding service
+
+Claude: [reads your business context — knows your brand voice,
+ differentiators, seasonal peaks, keyword landscape]
+
+ [pulls current ad performance and search term language]
+
+ VARIANT A: "Safety-First"
+ H1 [Pin 1]: Dog Boarding in Seattle (25 chars)
+ H2: Cage-Free, Supervised Care (26 chars)
+ H3: Book Your Pet's Stay (20 chars)
+ D1: Safe, cage-free boarding. Supervised play, daily updates.
+ D2: Open 7 days. 3 locations. Book online now.
+
+ VARIANT B: "Convenience"
+ H1 [Pin 1]: Dog Boarding Near SeaTac (25 chars)
+ H2: Drop Off Anytime, 7 Days (24 chars)
+ ...
+
+ Deploy Variant A?
+
+You: Yes, both as an A/B test.
+
+ [created 2 RSAs in ad group, both paused]
+ [enabled both — A/B test running]
+
+ Check back in 2 weeks or after 100 clicks per variant.
+```
+
+### SEO
+
+```
+You: /seo-analysis
+
+Claude: Found your site at mystore.com — pulling Search Console data now.
+
+ [90 days of real traffic data loaded]
+ [pages crawled for technical issues]
+
+ Three things hurting you most:
+
+ Your homepage lives at two addresses. Google splits your ranking
+ power between them. Easy fix.
+
+ Two pages targeting the same search terms — they compete against
+ each other and neither wins.
+
+ One page gets 400 monthly impressions but ranks #52. The title
+ doesn't match what people actually search for.
+
+ Here's your 30-day plan, most impactful first.
+
+You: Implement all of it.
+
+ [fixes duplicate homepage — 2 lines of config]
+ [consolidates competing pages, updates all internal links]
+ [rewrites page titles to match real search queries]
+
+ Done. Ready to ship.
+```
+
+---
+
+## Google Ads Skills
+
+### [`ads-audit`](google-ads/ads-audit/) — Account Audit & Business Context Setup
+
+**Run this first.** Audits your Google Ads account health and builds a business context profile that all other ads skills reuse.
+
+**What it does:**
+- Pulls all account data (campaigns, keywords, search terms, ads, impression share, conversions)
+- Scores 7 health dimensions: conversion tracking, campaign structure, keyword health, search term quality, ad copy, impression share, spend efficiency
+- Identifies wasted spend with specific keywords and dollar amounts
+- Builds and saves business context (brand voice, seasonality, competitors, keyword landscape) to `~/.adsagent/business-context.json`
+- Produces a prioritized action plan — top 3 things to fix first
+
+**How to trigger:**
+> "audit my ads", "ads audit", "set up my ads", "account overview", "how's my account", "ads health check", "what should I fix"
+
+### [`ads`](google-ads/ads/) — Google Ads Management
+
+Manage your Google Ads campaigns directly from Claude. Read performance data, optimize keywords, adjust bids and budgets, add negative keywords, and more. Powered by [AdsAgent](https://www.adsagent.org)'s free MCP server.
+
+**What it does:**
+- Reads campaign performance, keywords, search terms, impression share
+- Pauses wasteful keywords and adds negative keywords
+- Adjusts bids (within guardrails) and campaign budgets
+- Creates campaigns, ad groups, and responsive search ads
+- Every change is reversible within 7 days via `undoChange`
+
+**How to trigger:**
+> "how are my ads doing", "find wasted spend", "optimize bids", "add negative keywords", "pause campaign", "Google Ads performance", "check my ads"
+
+### [`ads-copy`](google-ads/ads-copy/) — Ad Copy Generator & A/B Testing
+
+Write Google Ads RSA copy grounded in your performance data and business context. Generates multiple variants with distinct messaging angles, deploys them, and tracks A/B test results.
+
+**What it does:**
+- Reads business context and current ad performance before writing
+- Generates RSA headlines (≤30 chars) and descriptions (≤90 chars) with character counts
+- Presents 2-3 named variants with pin positions and messaging angles
+- Deploys approved variants directly via `createAd` / `updateAdAssets`
+- Sets up and evaluates A/B tests with clear winner criteria
+
+**How to trigger:**
+> "write ad copy", "new headlines", "improve my ads CTR", "A/B test my ads", "RSA copy", "ad variants", "write me an ad"
+
+**Setup:** All Google Ads skills need a free token from [adsagent.org](https://www.adsagent.org). The setup script or `/ads-audit` will walk you through it.
+
+---
+
+## SEO Skills
+
+### [`seo-analysis`](seo/seo-analysis/) — SEO Audit & Search Console Analysis
+
+A full SEO audit in one command. Connects to Google Search Console, auto-detects your site, and produces a prioritized action plan.
+
+**What it does:**
+- Guides you through GSC API setup if needed (one `gcloud` command)
+- Auto-detects your site URL if you're inside a website repo
+- Pulls 90 days of query/page performance data
+- Surfaces **quick wins**: position 4–10 queries, high-impression low-CTR pages
+- Flags **traffic drops** with period-over-period comparison
+- **Technical audit**: indexability, meta tags, headings, structured data, canonical URLs
+- Outputs a structured report with a 30-day action plan
+
+**How to trigger:**
+> "analyze my SEO", "SEO audit", "why is my traffic down", "what keywords am I ranking for", "check my search console", "improve my rankings", "technical SEO audit"
+
+### [`content-writer`](seo/content-writer/) — SEO Content Creation
+
+Write blog posts, landing pages, or improve existing content following Google's E-E-A-T and Helpful Content guidelines. Works standalone or spawned automatically by `seo-analysis` when content gaps are found.
+
+**What it does:**
+- Determines content type from context (blog post, landing page, or content improvement)
+- Researches search intent and SERP landscape before writing
+- Produces publication-ready content with SEO metadata, JSON-LD structured data, and internal linking plan
+- Quality gate checks: "last click" test, E-E-A-T signals, anti-pattern detection
+- When spawned by `seo-analysis`, writes multiple pieces in parallel for identified content gaps
+
+**How to trigger:**
+> "write a blog post about X", "create a landing page for Y", "improve this page", "content for keyword X", "draft an article", "rewrite this page"
+
+### [`keyword-research`](seo/keyword-research/) — Keyword Discovery & Analysis
+
+Discover high-value keywords, assess difficulty, classify search intent, and build topic clusters. Works standalone or feeds directly into `content-writer`.
+
+**What it does:**
+- Generates keyword lists from seed terms with long-tail variations
+- Classifies search intent (informational, navigational, commercial, transactional)
+- Scores keyword difficulty and calculates opportunity (volume x intent / difficulty)
+- Groups keywords into topic clusters with pillar/cluster relationships
+- Produces a prioritized content calendar
+
+**How to trigger:**
+> "keyword research", "find keywords", "what should I write about", "keyword analysis", "content ideas", "search volume", "keyword difficulty"
+
+### [`meta-tags-optimizer`](seo/meta-tags-optimizer/) — Title Tags, Meta Descriptions & Social Tags
+
+Create and optimize meta tags for better click-through rates in search results and social sharing.
+
+**What it does:**
+- Writes compelling title tags (50–60 chars) with keyword placement and power words
+- Creates meta descriptions (150–160 chars) with clear CTAs
+- Generates Open Graph and Twitter Card tags for social previews
+- Provides multiple A/B test variations with CTR impact estimates
+- Validates character lengths for proper SERP display
+
+**How to trigger:**
+> "optimize title tag", "write meta description", "improve CTR", "Open Graph tags", "fix my meta tags", "social media preview", "my click rate is low"
+
+### [`schema-markup-generator`](seo/schema-markup-generator/) — JSON-LD Structured Data
+
+Generate valid JSON-LD schema markup for rich results in Google Search.
+
+**What it does:**
+- Selects appropriate schema types based on content (FAQ, HowTo, Article, Product, LocalBusiness, etc.)
+- Generates ready-to-paste JSON-LD with all required properties
+- Handles complex multi-type schemas on a single page
+- Provides SERP preview showing expected rich result appearance
+- Includes validation guidance and implementation instructions
+
+**How to trigger:**
+> "add schema markup", "generate structured data", "JSON-LD", "rich snippets", "FAQ schema", "product markup"
+
+---
+
+## Install — 30 seconds
+
+**Requirements:** Python 3.8+, `gcloud` CLI (`brew install google-cloud-sdk`), and one of:
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+- [Codex](https://github.com/openai/codex) (`npm install -g @openai/codex`)
+
+### Claude Code
+
+Open Claude Code and paste this. Claude does the rest.
+
+> Install toprank: run **`git clone --single-branch --depth 1 https://github.com/nowork-studio/toprank.git ~/.claude/skills/toprank && cd ~/.claude/skills/toprank && ./setup`** then add a "toprank" section to CLAUDE.md that lists the available skills: /seo-analysis, /content-writer, /keyword-research, /meta-tags-optimizer, /schema-markup-generator, /ads-audit, /ads, /ads-copy.
+
+Add to your repo so teammates get it (optional):
+
+> Add toprank to this project: run **`cp -Rf ~/.claude/skills/toprank .claude/skills/toprank && cd .claude/skills/toprank && ./setup`** then add a "toprank" section to this project's CLAUDE.md that lists the available skills: /seo-analysis, /content-writer, /keyword-research, /meta-tags-optimizer, /schema-markup-generator, /ads-audit, /ads, /ads-copy.
+
+### Codex
+
+Install to one repo:
+
+```bash
+git clone --single-branch --depth 1 https://github.com/nowork-studio/toprank.git .agents/skills/toprank
+cd .agents/skills/toprank && ./setup --host codex
+```
+
+Install globally:
+
+```bash
+git clone --single-branch --depth 1 https://github.com/nowork-studio/toprank.git ~/toprank
+cd ~/toprank && ./setup --host codex
+```
+
+Setup auto-detects which agents you have when you use `--host auto` (the default).
+
+---
+
+## How Skills Work
+
+Each skill is a `SKILL.md` file that your agent loads as an instruction set. The agent reads the skill and follows its workflow, calling scripts, crawling pages, querying APIs, to produce a structured output.
+
+Skills are discovered automatically. Claude Code reads from `~/.claude/skills/`, Codex reads from `.agents/skills/`. The `./setup` script handles both.
+
+```
+toprank/
+├── setup <- run this to register skills
+├── seo/ <- SEO skills
+│ ├── seo-analysis/
+│ │ ├── SKILL.md <- SEO audit workflow
+│ │ ├── scripts/ <- Python scripts for GSC API
+│ │ └── references/
+│ ├── content-writer/
+│ │ ├── SKILL.md <- content creation workflow
+│ │ └── references/
+│ ├── keyword-research/
+│ │ ├── SKILL.md <- keyword discovery & analysis
+│ │ └── references/
+│ ├── meta-tags-optimizer/
+│ │ ├── SKILL.md <- title/description/OG optimization
+│ │ └── references/
+│ ├── schema-markup-generator/
+│ │ ├── SKILL.md <- JSON-LD structured data
+│ │ └── references/
+│ └── setup-cms/
+│ └── SKILL.md <- CMS configuration wizard
+├── google-ads/ <- Google Ads skills
+│ ├── ads-audit/
+│ │ └── SKILL.md <- account audit + business context
+│ ├── ads/
+│ │ ├── SKILL.md <- Google Ads management
+│ │ └── mcporter.json <- MCP server config
+│ └── ads-copy/
+│ └── SKILL.md <- RSA copy generator + A/B testing
+└── toprank-upgrade/
+ └── SKILL.md <- auto-upgrade workflow
+```
+
+---
+
+## Contributing
+
+Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.
+
+---
+
+## License
+
+[MIT](LICENSE)
diff --git a/VERSION b/VERSION
new file mode 100644
index 00000000..ac39a106
--- /dev/null
+++ b/VERSION
@@ -0,0 +1 @@
+0.9.0
diff --git a/bin/preamble.md b/bin/preamble.md
new file mode 100755
index 00000000..cd38a6a1
--- /dev/null
+++ b/bin/preamble.md
@@ -0,0 +1,14 @@
+## Preamble (run first)
+
+```bash
+_UPD=$(~/.claude/skills/toprank/bin/toprank-update-check 2>/dev/null || \
+ ~/.claude/skills/stockholm/bin/toprank-update-check 2>/dev/null || true)
+[ -n "$_UPD" ] && echo "$_UPD" || true
+```
+
+If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/toprank-upgrade` skill (Step 1 onward) to auto-upgrade, then return here and continue.
+
+If the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded from v{old} to v{new}" briefly, then continue.
+
+---
+
diff --git a/bin/toprank-config b/bin/toprank-config
new file mode 100755
index 00000000..cc0d0a5e
--- /dev/null
+++ b/bin/toprank-config
@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# toprank-config — read/write ~/.toprank/config.yaml
+#
+# Usage:
+# toprank-config get <key> — read a config value
+# toprank-config set <key> <value> — write a config value
+# toprank-config list — show all config
+#
+# Env overrides (for testing):
+# TOPRANK_STATE_DIR — override ~/.toprank state directory
+set -euo pipefail
+
+STATE_DIR="${TOPRANK_STATE_DIR:-$HOME/.toprank}"
+CONFIG_FILE="$STATE_DIR/config.yaml"
+
+case "${1:-}" in
+ get)
+ KEY="${2:?Usage: toprank-config get <key>}"
+ grep -E "^${KEY}:" "$CONFIG_FILE" 2>/dev/null | tail -1 | awk '{print $2}' | tr -d '[:space:]' || true
+ ;;
+ set)
+ KEY="${2:?Usage: toprank-config set <key> <value>}"
+ VALUE="${3:?Usage: toprank-config set <key> <value>}"
+ mkdir -p "$STATE_DIR"
+ if grep -qE "^${KEY}:" "$CONFIG_FILE" 2>/dev/null; then
+ _tmpfile="$(mktemp "${CONFIG_FILE}.XXXXXX")"
+ sed "s/^${KEY}:.*/${KEY}: ${VALUE}/" "$CONFIG_FILE" > "$_tmpfile" && mv "$_tmpfile" "$CONFIG_FILE"
+ else
+ echo "${KEY}: ${VALUE}" >> "$CONFIG_FILE"
+ fi
+ ;;
+ list)
+ cat "$CONFIG_FILE" 2>/dev/null || true
+ ;;
+ *)
+ echo "Usage: toprank-config {get|set|list} [key] [value]"
+ exit 1
+ ;;
+esac
diff --git a/bin/toprank-update-check b/bin/toprank-update-check
new file mode 100755
index 00000000..a089d31f
--- /dev/null
+++ b/bin/toprank-update-check
@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+# toprank-update-check — periodic version check for toprank skills.
+#
+# Output (one line, or nothing):
+# JUST_UPGRADED <old> <new> — marker found from recent upgrade
+# UPGRADE_AVAILABLE <old> <new> — remote VERSION differs from local
+# (nothing) — up to date, snoozed, disabled, or check skipped
+#
+# Env overrides (for testing):
+# TOPRANK_DIR — override auto-detected toprank root
+# TOPRANK_REMOTE_URL — override remote VERSION URL
+# TOPRANK_STATE_DIR — override ~/.toprank state directory
+set -euo pipefail
+
+TOPRANK_DIR="${TOPRANK_DIR:-$(cd "$(dirname "$0")/.." && pwd)}"
+STATE_DIR="${TOPRANK_STATE_DIR:-$HOME/.toprank}"
+CACHE_FILE="$STATE_DIR/last-update-check"
+MARKER_FILE="$STATE_DIR/just-upgraded-from"
+SNOOZE_FILE="$STATE_DIR/update-snoozed"
+VERSION_FILE="$TOPRANK_DIR/VERSION"
+REMOTE_URL="${TOPRANK_REMOTE_URL:-https://raw.githubusercontent.com/nowork-studio/toprank/main/VERSION}"
+CONFIG_BIN="$TOPRANK_DIR/bin/toprank-config"
+VERSION_RE='^[0-9]+(\.[0-9]+)+$'
+
+# State dir must exist early so any writes below succeed.
+mkdir -p "$STATE_DIR"
+
+# ─── Force flag (busts cache + snooze for standalone /toprank-upgrade) ──
+if [ "${1:-}" = "--force" ]; then
+ rm -f "$CACHE_FILE"
+ rm -f "$SNOOZE_FILE"
+fi
+
+# ─── Step 0: Check if updates are disabled ────────────────────
+_UC=$("$CONFIG_BIN" get update_check 2>/dev/null || true)
+if [ "$_UC" = "false" ]; then
+ exit 0
+fi
+
+# ─── Snooze helper ──────────────────────────────────────────
+# check_snooze <remote_version>
+# Returns 0 if snoozed (stay quiet), 1 if not snoozed (should output).
+#
+# Snooze file format: <version> <level> <epoch>
+# Level durations: 1=24h, 2=48h, 3+=7d
+# New version resets snooze.
+check_snooze() {
+ local remote_ver="$1"
+ if [ ! -f "$SNOOZE_FILE" ]; then
+ return 1
+ fi
+ local snoozed_ver snoozed_level snoozed_epoch
+ snoozed_ver="$(awk '{print $1}' "$SNOOZE_FILE" 2>/dev/null || true)"
+ snoozed_level="$(awk '{print $2}' "$SNOOZE_FILE" 2>/dev/null || true)"
+ snoozed_epoch="$(awk '{print $3}' "$SNOOZE_FILE" 2>/dev/null || true)"
+
+ if [ -z "$snoozed_ver" ] || [ -z "$snoozed_level" ] || [ -z "$snoozed_epoch" ]; then
+ return 1
+ fi
+ case "$snoozed_level" in *[!0-9]*) return 1 ;; esac
+ case "$snoozed_epoch" in *[!0-9]*) return 1 ;; esac
+
+ if [ "$snoozed_ver" != "$remote_ver" ]; then
+ return 1
+ fi
+
+ local duration
+ case "$snoozed_level" in
+ 1) duration=86400 ;; # 24 hours
+ 2) duration=172800 ;; # 48 hours
+ *) duration=604800 ;; # 7 days (level 3+)
+ esac
+
+ local now
+ now="$(date +%s)"
+ local expires=$(( snoozed_epoch + duration ))
+ if [ "$now" -lt "$expires" ]; then
+ return 0 # still snoozed
+ fi
+ return 1 # snooze expired
+}
+
+# ─── Step 1: Read and validate local version ─────────────────
+LOCAL=""
+if [ -f "$VERSION_FILE" ]; then
+ LOCAL="$(cat "$VERSION_FILE" 2>/dev/null | tr -d '[:space:]')"
+fi
+if [ -z "$LOCAL" ]; then
+ exit 0
+fi
+# Reject malformed local VERSION to avoid writing garbage to cache.
+if ! echo "$LOCAL" | grep -qE "$VERSION_RE"; then
+ exit 0
+fi
+
+# ─── Step 2: Check "just upgraded" marker ─────────────────────
+# Exit immediately after printing JUST_UPGRADED — do not fall through
+# to the network fetch or we'd produce two output lines.
+if [ -f "$MARKER_FILE" ]; then
+ OLD="$(cat "$MARKER_FILE" 2>/dev/null | tr -d '[:space:]')"
+ rm -f "$MARKER_FILE"
+ rm -f "$SNOOZE_FILE"
+ if [ -n "$OLD" ]; then
+ echo "JUST_UPGRADED $OLD $LOCAL"
+ fi
+ exit 0
+fi
+
+# ─── Step 3: Check cache freshness ──────────────────────────
+# UP_TO_DATE: 60 min TTL. UPGRADE_AVAILABLE: 720 min TTL (keep notifying).
+if [ -f "$CACHE_FILE" ]; then
+ CACHED="$(cat "$CACHE_FILE" 2>/dev/null || true)"
+ case "$CACHED" in
+ UP_TO_DATE*) CACHE_TTL=5 ;;
+ UPGRADE_AVAILABLE*) CACHE_TTL=720 ;;
+ *) CACHE_TTL=0 ;;
+ esac
+
+ STALE=$(find "$CACHE_FILE" -mmin +$CACHE_TTL 2>/dev/null || true)
+ if [ -z "$STALE" ] && [ "$CACHE_TTL" -gt 0 ]; then
+ case "$CACHED" in
+ UP_TO_DATE*)
+ CACHED_VER="$(echo "$CACHED" | awk '{print $2}')"
+ if [ "$CACHED_VER" = "$LOCAL" ]; then
+ exit 0
+ fi
+ ;;
+ UPGRADE_AVAILABLE*)
+ CACHED_OLD="$(echo "$CACHED" | awk '{print $2}')"
+ if [ "$CACHED_OLD" = "$LOCAL" ]; then
+ CACHED_NEW="$(echo "$CACHED" | awk '{print $3}')"
+ if check_snooze "$CACHED_NEW"; then
+ exit 0
+ fi
+ echo "$CACHED"
+ exit 0
+ fi
+ ;;
+ esac
+ fi
+fi
+
+# ─── Step 4: Slow path — fetch remote version ────────────────
+REMOTE="$(curl -sf --max-time 5 "$REMOTE_URL" 2>/dev/null || true)"
+REMOTE="$(echo "$REMOTE" | tr -d '[:space:]')"
+
+# Validate: must look like a version number (reject HTML error pages, etc.)
+if ! echo "$REMOTE" | grep -qE "$VERSION_RE"; then
+ _TMP="$CACHE_FILE.$$.tmp"
+ echo "UP_TO_DATE $LOCAL" > "$_TMP" && mv "$_TMP" "$CACHE_FILE" || rm -f "$_TMP"
+ exit 0
+fi
+
+if [ "$LOCAL" = "$REMOTE" ]; then
+ _TMP="$CACHE_FILE.$$.tmp"
+ echo "UP_TO_DATE $LOCAL" > "$_TMP" && mv "$_TMP" "$CACHE_FILE" || rm -f "$_TMP"
+ exit 0
+fi
+
+# Versions differ — upgrade available
+_TMP="$CACHE_FILE.$$.tmp"
+echo "UPGRADE_AVAILABLE $LOCAL $REMOTE" > "$_TMP" && mv "$_TMP" "$CACHE_FILE" || rm -f "$_TMP"
+if check_snooze "$REMOTE"; then
+ exit 0
+fi
+
+echo "UPGRADE_AVAILABLE $LOCAL $REMOTE"
diff --git a/conftest.py b/conftest.py
new file mode 100644
index 00000000..1f67b344
--- /dev/null
+++ b/conftest.py
@@ -0,0 +1,5 @@
+"""Root conftest — makes test/helpers/ importable as `helpers.*`."""
+import sys
+import os
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'test'))
diff --git a/google-ads/ads-audit/SKILL.md b/google-ads/ads-audit/SKILL.md
new file mode 100644
index 00000000..f0e7a6a1
--- /dev/null
+++ b/google-ads/ads-audit/SKILL.md
@@ -0,0 +1,266 @@
+---
+name: ads-audit
+description: Google Ads account audit and business context setup. Run this first — it gathers business information, analyzes account health, and saves context that all other ads skills reuse. Trigger on "audit my ads", "ads audit", "set up my ads", "onboard", "account overview", "how's my account", "ads health check", "what should I fix in my ads", or when the user is new to AdsAgent and hasn't run an audit before. Also trigger proactively when other ads skills detect that business-context.json is missing.
+---
+
+# Google Ads Audit + Business Context Setup
+
+This is the starting point for any Google Ads account. It does two things:
+
+1. **Audits the account** — surfaces what's working, what's wasting money, and what to fix first
+2. **Builds business context** — gathers and saves business information to `~/.adsagent/business-context.json` so every other ads skill (copy, landing pages, competitive analysis) can use it without re-asking
+
+Run this before anything else. If another ads skill finds `business-context.json` missing, it should point the user here.
+
+## Setup
+
+Before anything else, verify the user has the AdsAgent MCP server connected and a token configured. Follow these steps in order — stop at the first issue and resolve it before continuing.
+
+### Step 1: Check for the AdsAgent MCP server
+
+Try calling `mcp__adsagent__listConnectedAccounts`. If the tool exists and responds, the MCP server is connected — skip to Step 2.
+
+If the tool doesn't exist (not in available tools), the MCP server isn't configured. Guide the user:
+
+> The AdsAgent MCP server isn't connected yet. To set it up:
+>
+> 1. **Get a free token** at [adsagent.org](https://www.adsagent.org)
+> 2. **Add the MCP server** to your Claude settings. Open your Claude Code settings (or Claude Desktop config) and add this to `mcpServers`:
+>
+> ```json
+> {
+> "adsagent": {
+> "command": "npx",
+> "args": [
+> "-y", "mcp-remote",
+> "https://www.adsagent.org/api/mcp",
+> "--transport", "http-first",
+> "--header", "Authorization:Bearer YOUR_API_KEY"
+> ]
+> }
+> }
+> ```
+>
+> Replace `YOUR_API_KEY` with the token from step 1.
+>
+> 3. **Restart Claude** to pick up the new MCP server.
+>
+> Alternatively, if you installed toprank via the setup script, re-run `./setup --api-key YOUR_KEY` and it will configure everything automatically.
+
+Wait for the user to complete setup before proceeding.
+
+### Step 2: Check for token and account
+
+Read `~/.adsagent/config.json` for `apiKey` (the token) and `accountId`.
+
+- If `apiKey` is missing, ask the user for their token and save it as `apiKey` in `~/.adsagent/config.json`.
+- If `accountId` is missing, run `mcp__adsagent__listConnectedAccounts`:
+ - **One account** → save it automatically
+ - **Multiple accounts** → show list, ask user to pick
+ - **Zero accounts** → direct user to [adsagent.org](https://www.adsagent.org) to connect a Google Ads account
+
+## Phase 1: Pull Account Data
+
+Gather everything in parallel before asking the user a single question. The goal is to show up informed.
+
+**Account basics:**
+- `mcp__adsagent__getAccountInfo` — business name, currency, timezone
+- `mcp__adsagent__getAccountSettings` — auto-tagging, tracking template, conversion setup
+
+**Campaign structure:**
+- `mcp__adsagent__listCampaigns` — all campaigns with spend, clicks, conversions
+- `mcp__adsagent__listAdGroups` — ad groups per campaign (focus on top-spend campaigns)
+
+**Performance data:**
+- `mcp__adsagent__getCampaignPerformance` — daily trends for the last 30 days
+- `mcp__adsagent__getKeywords` — top keywords with quality scores, bids, conversions
+- `mcp__adsagent__getSearchTermReport` — actual search queries triggering ads
+- `mcp__adsagent__getImpressionShare` — search IS, top IS, budget-lost IS, rank-lost IS
+
+**Ads and conversions:**
+- `mcp__adsagent__listAds` — ad copy, status, and per-ad metrics
+- `mcp__adsagent__getConversionActions` — what conversions are set up and how they're configured
+- `mcp__adsagent__getNegativeKeywords` — existing negative keyword coverage
+
+**Recommendations:**
+- `mcp__adsagent__getRecommendations` — Google's optimization suggestions (evaluate critically, don't blindly follow)
+
+## Phase 2: Analyze and Score
+
+Work through each dimension. For each one, assign a quick status: OK / Needs Work / Critical.
+
+### Account Health Dimensions
+
+**1. Conversion tracking**
+- Are conversion actions set up? Are they firing?
+- Is auto-tagging enabled?
+- Red flag: spending money with no conversion tracking = flying blind
+
+**2. Campaign structure**
+- Are campaigns organized by service/product and location?
+- Are ad groups tightly themed (5-20 keywords each)?
+- Red flag: one ad group with 200 keywords = poor relevance
+
+**3. Keyword health**
+- What's the average quality score? (Below 5 = problems)
+- Any high-spend, zero-conversion keywords?
+- Are match types appropriate? (Broad match without negatives = waste)
+- Are there enough negatives blocking irrelevant queries?
+
+**4. Search term quality**
+- What % of search terms are relevant?
+- Are there obvious negatives missing?
+- Are there high-converting search terms not yet added as keywords?
+
+**5. Ad copy**
+- How many RSAs per ad group? (Should have at least 2 for testing)
+- Are headlines and descriptions varied or repetitive?
+- Are there ads with low CTR that need refreshing?
+
+**6. Impression share**
+- How much traffic are you losing to budget vs. rank?
+- Budget-lost IS > 20% = you're leaving money on the table or need to tighten targeting
+- Rank-lost IS > 50% = quality score or bid issues
+
+**7. Spend efficiency**
+- What's the overall CPA? How does it compare across campaigns?
+- Any campaigns with high spend but low conversions?
+- What % of spend goes to converting keywords vs. non-converting?
+
+## Phase 3: Build Business Context
+
+Now that you understand the account, fill in the business context. Pull as much as possible from the data you already have — only ask the user for what you can't infer.
+
+### What to infer from account data
+
+| Field | Source |
+|-------|--------|
+| `business_name` | `getAccountInfo` |
+| `services` | Campaign and ad group names, keyword themes |
+| `locations` | Campaign geo-targeting, location extensions |
+| `brand_voice` | Existing ad copy tone and word choices |
+| `keyword_landscape.high_intent_terms` | Top-converting keywords |
+| `keyword_landscape.competitive_terms` | Low impression share keywords with high CPC |
+| `keyword_landscape.long_tail_opportunities` | Converting search terms not yet added as keywords |
+
+### What to ask the user
+
+Present what you inferred, then ask for what's missing. Frame it conversationally, not as a checklist.
+
+**Always ask:**
+- "What makes you different from competitors?" → `differentiators`
+- "Who are your main competitors?" → `competitors`
+- "Is your business seasonal? When's your busiest time?" → `seasonality`
+- "What's your website URL?" → for landing page context
+
+**Ask if not obvious from data:**
+- Industry (if campaign names don't make it clear)
+- Target audience (if search terms don't reveal it)
+- Current offers or promotions
+- Social proof (reviews, awards, years in business)
+
+### Website analysis
+
+If the user provides their website URL (or it's visible in ad final URLs):
+
+- Note the URL in `landing_pages`
+- Look at what the ads link to — do headlines match landing page content?
+- Note any offers, trust signals, or CTAs visible on the site that could inform ad copy
+
+### Save the context
+
+Write the complete business context to `~/.adsagent/business-context.json`:
+
+```json
+{
+ "business_name": "",
+ "industry": "",
+ "website": "",
+ "services": [],
+ "locations": [],
+ "target_audience": "",
+ "brand_voice": {
+ "tone": "",
+ "words_to_avoid": [],
+ "words_to_use": []
+ },
+ "differentiators": [],
+ "competitors": [],
+ "seasonality": {
+ "peak_months": [],
+ "slow_months": [],
+ "seasonal_hooks": []
+ },
+ "keyword_landscape": {
+ "high_intent_terms": [],
+ "competitive_terms": [],
+ "long_tail_opportunities": []
+ },
+ "social_proof": [],
+ "offers_or_promotions": [],
+ "landing_pages": {},
+ "notes": "",
+ "audit_date": "",
+ "account_id": ""
+}
+```
+
+Include `audit_date` (today's date) and `account_id` so future skills know when this was last refreshed.
+
+## Phase 4: Deliver the Audit Report
+
+Present findings as a concise, actionable report. No fluff — every line should either inform a decision or recommend an action.
+
+### Report format
+
+```
+# Google Ads Audit: [Business Name]
+**Account:** [ID] | **Period:** Last 30 days | **Date:** [today]
+
+## Scorecard
+| Dimension | Status | Summary |
+|----------------------|-------------|--------------------------------------|
+| Conversion tracking | OK / Needs Work / Critical | [one line] |
+| Campaign structure | ... | ... |
+| Keyword health | ... | ... |
+| Search term quality | ... | ... |
+| Ad copy | ... | ... |
+| Impression share | ... | ... |
+| Spend efficiency | ... | ... |
+
+## Key Numbers
+- **Total spend (30d):** $X,XXX
+- **Conversions:** XX at $XX CPA
+- **Top campaign:** [name] — XX% of spend, XX% of conversions
+- **Wasted spend:** ~$XXX on non-converting keywords/terms
+
+## Top 3 Actions (do these first)
+1. **[Action]** — [why, expected impact]
+2. **[Action]** — [why, expected impact]
+3. **[Action]** — [why, expected impact]
+
+## Detailed Findings
+[Organized by dimension — only include dimensions that need work.
+For each, state the problem, show the data, recommend the fix.]
+
+## Business Context Saved
+Saved to ~/.adsagent/business-context.json — other ads skills
+(/ads-copy, /ads-landing, /ads-compete) will use this automatically.
+[List any fields that are incomplete and need user input later.]
+```
+
+### What makes a good action item
+
+- **Specific:** "Pause keyword 'free dog food' — $847 spent, 0 conversions" not "Review underperforming keywords"
+- **Quantified:** Include the spend, impressions, or conversions at stake
+- **Prioritized:** Highest-impact items first. Stopping waste > starting new things
+- **Actionable with /ads:** Every recommendation should be something the user can execute immediately using the `/ads` skill
+
+## Rules
+
+1. **Data first, questions second.** Pull all account data before asking the user anything. Show up informed.
+2. **Infer before asking.** Don't ask "what industry are you in?" if the campaigns clearly say "plumbing services."
+3. **Be specific.** Name the campaigns, keywords, and dollar amounts. Vague advice is useless.
+4. **Prioritize by money.** The biggest waste or biggest opportunity comes first.
+5. **Save the context.** Always write `business-context.json` — this is the handoff to every other ads skill.
+6. **Don't fix things here.** This skill diagnoses and recommends. The user executes fixes with `/ads`. Offer to switch to `/ads` for implementation.
diff --git a/google-ads/ads-copy/SKILL.md b/google-ads/ads-copy/SKILL.md
new file mode 100644
index 00000000..1b100e44
--- /dev/null
+++ b/google-ads/ads-copy/SKILL.md
@@ -0,0 +1,206 @@
+---
+name: ads-copy
+description: Generate and A/B test Google Ads copy. Use when asked to write ad copy, headlines, descriptions, create ad variants, test ad messaging, improve CTR, or generate RSA (Responsive Search Ad) components. Trigger on "ad copy", "write ads", "headlines", "descriptions", "RSA", "responsive search ad", "ad text", "ad creative", "improve CTR", "ad A/B test", "ad variants", "write me an ad", or when the user wants to improve click-through rate on existing ads.
+---
+
+# Ad Copy Generator + A/B Tester
+
+Write Google Ads RSA copy and run structured A/B tests to find winning messaging.
+
+## Setup
+
+This skill requires the AdsAgent MCP server. Try calling `mcp__adsagent__listConnectedAccounts` to verify it's connected.
+
+- **If the tool doesn't exist** → the MCP server isn't configured. Run `/ads-audit` which walks the user through full setup (MCP server, token, account selection, and business context).
+- **If the tool works** → read `~/.adsagent/config.json` for `apiKey` and `accountId`. If missing, run `/ads-audit` for onboarding.
+
+## Business Context — Read First, Ask Once
+
+Every ad copy decision depends on understanding the business. This skill stores business context in `~/.adsagent/business-context.json` so it only needs to be gathered once.
+
+### On every invocation:
+
+1. **Read `~/.adsagent/business-context.json`**. If it exists and has content, use it — skip the intake interview.
+2. **If missing or empty**, run the intake interview below, then save the result.
+3. **If the user volunteers new info** (new service, changed positioning, seasonal update), merge it into the existing file.
+
+### Intake interview
+
+Gather these fields. Don't ask them as a rigid checklist — pull what you can from context (the account's existing ads, website, campaign names) and only ask what's missing.
+
+```json
+{
+ "business_name": "",
+ "industry": "",
+ "services": [""],
+ "locations": [""],
+ "target_audience": "",
+ "brand_voice": {
+ "tone": "",
+ "words_to_avoid": [""],
+ "words_to_use": [""]
+ },
+ "differentiators": [""],
+ "competitors": [""],
+ "seasonality": {
+ "peak_months": [""],
+ "slow_months": [""],
+ "seasonal_hooks": [""]
+ },
+ "keyword_landscape": {
+ "high_intent_terms": [""],
+ "competitive_terms": [""],
+ "long_tail_opportunities": [""]
+ },
+ "social_proof": [""],
+ "offers_or_promotions": [""],
+ "landing_pages": {},
+ "notes": ""
+}
+```
+
+**Why each field matters for copy:**
+
+| Field | How it shapes copy |
+|-------|-------------------|
+| `industry` | Sets baseline competitive intensity and CPC expectations |
+| `services` | Determines headline categories and description angles |
+| `locations` | Geo-specific headlines get higher quality scores and CTR |
+| `brand_voice` | Tone, forbidden words, preferred language |
+| `differentiators` | These ARE the value prop headlines — the reason someone picks you |
+| `competitors` | Knowing who you're against sharpens positioning (without naming them in ads) |
+| `seasonality` | Tells you WHEN to push urgency copy vs. evergreen, which months to bid up |
+| `keyword_landscape` | High-intent terms go in headlines; competitive terms need sharper differentiation; long-tail = cheaper, more specific copy angles |
+| `social_proof` | Reviews, awards, years in business — trust signal headlines and descriptions |
+| `offers_or_promotions` | Time-sensitive copy angles, CTA variations |
+| `landing_pages` | Copy must match the page or conversions drop — know what's there |
+
+### Bootstrapping from existing data
+
+Before asking the user anything, try to fill fields from what's already available:
+
+- `mcp__adsagent__getAccountInfo` → business name, location hints
+- `mcp__adsagent__listCampaigns` → service categories, geo targeting
+- `mcp__adsagent__listAds` → current voice, headlines in use
+- `mcp__adsagent__getKeywords` → keyword landscape
+- `mcp__adsagent__getSearchTermReport` → real user language, long-tail opportunities
+- `mcp__adsagent__getImpressionShare` → competitive pressure signals
+
+Present what you found and ask the user to confirm/correct/fill gaps. This is faster and more accurate than starting from zero.
+
+## Workflow
+
+### 1. Understand the brief
+
+Detect or ask:
+- What product/service is this ad for?
+- Target audience or segment?
+- Which campaign/ad group? (pull with `mcp__adsagent__listCampaigns` → `mcp__adsagent__listAdGroups`)
+- Landing page URL?
+- Any geographic targeting?
+
+Cross-reference against the business context — if the user says "write copy for boarding" and context has boarding details, you already know the angles.
+
+### 2. Research what's working
+
+Pull data before writing — copy should be grounded in what converts, not guesses.
+
+**Current ad performance:**
+- `mcp__adsagent__listAds` — existing headlines/descriptions and their metrics
+- `mcp__adsagent__getKeywords` — active keywords
+- `mcp__adsagent__getSearchTermReport` — actual user queries (reveals real language and intent)
+- `mcp__adsagent__getCampaignPerformance` — CTR/conversion benchmarks to beat
+
+**Use seasonality context.** If business context shows peak months, factor that into copy urgency. During slow months, lean on evergreen value props. During peaks, lean on scarcity and timeliness.
+
+**Use keyword landscape context.** For competitive terms (high CPC, many bidders), copy must differentiate harder — lead with what's unique, not what everyone says. For long-tail terms, match the specific intent closely.
+
+**If the user has a database with lead/conversion data**, query it to find which keywords and messaging actually convert. The language paying customers use is the language your ads should mirror.
+
+### 3. Generate RSA components
+
+Google RSA: up to **15 headlines** (30 chars max) and **4 descriptions** (90 chars max). Google's AI mixes and matches them.
+
+**Always count characters. Flag any that exceed limits.**
+
+Generate 3-4 headlines per category:
+
+| Category | Purpose | Pin guidance |
+|----------|---------|-------------|
+| Product/Service + Location | Relevance, match search intent | **Pin to position 1** |
+| Value proposition | Why this business over competitors | Position 2 candidate |
+| Trust signals | Credibility (ratings, years, locations) | Any position |
+| Call to action | Drive the click | Position 3 candidate |
+
+Descriptions (one per angle):
+1. **Core value prop** + location specificity
+2. **Differentiator** + CTA
+3. **Trust signal** + social proof
+4. **Urgency** or seasonal angle
+
+### 4. Present variants
+
+Show 2-3 variants, each with a distinct messaging angle. Name the angle so it's clear what's being tested.
+
+```
+VARIANT A: "[Angle Name]"
+ H1 [Pin 1]: [Service] in [Location] (XX chars)
+ H2: [Value prop headline] (XX chars)
+ H3: [CTA headline] (XX chars)
+ D1: [Value prop description — max 90 chars]
+ D2: [Trust/CTA description — max 90 chars]
+
+VARIANT B: "[Different Angle]"
+ H1 [Pin 1]: ...
+ ...
+```
+
+Always show character counts. Always show pin positions.
+
+### 5. Deploy
+
+After user approves a variant, push it live:
+
+- **New ad:** `mcp__adsagent__createAd` — create the RSA in the target ad group (created paused)
+- **Update existing:** `mcp__adsagent__updateAdAssets` — replace headlines/descriptions on a live ad
+- **Enable when ready:** `mcp__adsagent__enableAd`
+
+Always confirm before any write operation. Note the `changeId` returned — user can undo within 7 days via `mcp__adsagent__undoChange`.
+
+### 6. A/B test (if running one)
+
+1. **Identify the variable** — messaging angle, CTA style, emotional vs. practical
+2. **Deploy both variants** as separate ads in the same ad group (both paused, enable together)
+3. **Minimum run:** 2 weeks or 100 clicks per variant, whichever comes first
+4. **Success metric:** CTR for awareness campaigns, conversion rate for bottom-funnel
+
+### 7. Check results
+
+After the test period, pull results:
+
+```
+mcp__adsagent__listAds → compare metrics for each variant
+```
+
+| Variant | Impressions | Clicks | CTR | Conversions | Conv Rate | Winner? |
+|---------|------------|--------|-----|-------------|-----------|---------|
+| A | | | | | | |
+| B | | | | | | |
+
+**Interpret:**
+- Higher CTR + higher conversion rate → clear winner, pause the loser
+- Higher CTR + lower conversion rate → ad attracts clicks but landing page doesn't match the promise. Suggest `/ads-landing` to fix alignment
+- No statistical difference → need more volume or a bolder variant
+
+After deciding a winner: pause the loser with `mcp__adsagent__pauseAd`, keep the winner running.
+
+## Rules
+
+1. **Business context first.** Read `~/.adsagent/business-context.json` before doing anything. If it doesn't exist, build it.
+2. **Research before writing.** Always pull current performance data. Don't write copy in a vacuum.
+3. **Character limits are hard.** Count every headline (≤30) and description (≤90). No exceptions.
+4. **Never deploy without confirmation.** Show the exact copy, get a yes, then create/update.
+5. **Note changeIds.** Every write returns one. Tell the user they can undo within 7 days.
+6. **Ground copy in conversion data.** If conversion data is available, use the language that converts.
+7. **Seasonal awareness.** Check the business context for peak/slow months. Adjust urgency and messaging accordingly.
+8. **Defer to /ads for account management.** This skill writes copy and deploys ads. For bid/budget/keyword work, use `/ads`.
diff --git a/google-ads/ads/SKILL.md b/google-ads/ads/SKILL.md
new file mode 100644
index 00000000..fc00aba6
--- /dev/null
+++ b/google-ads/ads/SKILL.md
@@ -0,0 +1,200 @@
+---
+name: ads
+description: Manage Google Ads campaigns — read performance, optimize keywords, adjust bids and budgets, add negatives, pause/enable campaigns, manage ads/ad groups, tracking templates, and undo changes. Use this skill whenever the user mentions Google Ads, campaigns, keywords, ad spend, CPA, ROAS, search terms, negative keywords, bids, budgets, or ads performance — even if they don't say "ads" explicitly.
+version: 2.0.0
+triggers:
+ - google ads
+ - campaigns
+ - keywords
+ - ad spend
+ - CPA
+ - ROAS
+ - search terms
+ - negative keywords
+ - bid
+ - budget
+ - pause campaign
+ - ads performance
+---
+
+# AdsAgent — Google Ads Management
+
+Call Google Ads tools using the bundled CLI client.
+
+## Configuration
+
+All persistent config lives in `~/.adsagent/config.json`. This file survives across sessions and works in every context — Claude Code, Claude Desktop, MCP servers, etc.
+
+The config file has this shape:
+
+```json
+{
+ "apiKey": "asa_...",
+ "accountId": "1234567890"
+}
+```
+
+## Onboarding
+
+Before doing anything else, check whether the user is set up. Follow these steps in order — stop at the first issue and resolve it before continuing.
+
+### Step 0: Check for the AdsAgent MCP server
+
+Try calling `mcp__adsagent__listConnectedAccounts`. If it responds, the MCP server is connected — skip to Step 1.
+
+If the tool doesn't exist, the MCP server isn't configured yet. Guide the user:
+
+> The AdsAgent MCP server isn't connected. To set it up:
+>
+> 1. **Get a free token** at [adsagent.org](https://www.adsagent.org)
+> 2. **Add the MCP server** to your Claude settings (`mcpServers`):
+>
+> ```json
+> {
+> "adsagent": {
+> "command": "npx",
+> "args": [
+> "-y", "mcp-remote",
+> "https://www.adsagent.org/api/mcp",
+> "--transport", "http-first",
+> "--header", "Authorization:Bearer YOUR_API_KEY"
+> ]
+> }
+> }
+> ```
+>
+> Replace `YOUR_API_KEY` with the token from step 1.
+>
+> 3. **Restart Claude** to pick up the new MCP server.
+>
+> If you installed toprank via the setup script, re-run `./setup --api-key YOUR_KEY` to configure everything automatically.
+
+Note: This skill can also call tools via the bundled mcporter CLI (see "Calling tools" section below), which works without MCP server configuration. But the MCP server is recommended because other ads skills (`/ads-copy`, `/ads-audit`, `/ads-compete`) depend on it.
+
+### Step 1: Check for token
+
+Read `~/.adsagent/config.json` (create `~/.adsagent/` if it doesn't exist).
+
+Look for `apiKey` (the token) in the config file. If it's present, skip to Step 2.
+
+If it's missing, tell the user:
+
+> To use AdsAgent, you need a free token. You can get one from [adsagent.org](https://www.adsagent.org).
+> Once you have it, paste it here and I'll save it for you.
+
+When the user provides the key, save it to `~/.adsagent/config.json`.
+
+Then continue to Step 2.
+
+### Step 2: Select a Google Ads account
+
+Look for `accountId` in the config file. If it's present, proceed to fulfil the user's request.
+
+If `accountId` is not set:
+
+1. Run `listConnectedAccounts` to get all connected Google Ads accounts.
+2. **If there is exactly one account**, save it automatically — no need to bother the user. Write `accountId` to `~/.adsagent/config.json` and tell the user which account was selected (show account name and ID).
+3. **If there are multiple accounts**, present them as a numbered list showing account name and ID, then ask the user to pick one. Save their choice to `~/.adsagent/config.json`.
+4. **If there are zero accounts**, tell the user they don't have any Google Ads accounts connected yet and direct them to [adsagent.org](https://www.adsagent.org) to connect one.
+
+### Switching accounts
+
+If the user wants to switch accounts, run `listConnectedAccounts`, let them pick, and update `accountId` in `~/.adsagent/config.json`.
+
+## Calling tools
+
+Before calling any tool, read `~/.adsagent/config.json` and export the API key so mcporter can use it:
+
+```bash
+export ADS_AGENT_KEY="<apiKey from config>"
+```
+
+Then call tools via mcporter using the bundled config. String parameters must be quoted with double quotes inside single quotes to avoid type errors:
+
+```bash
+export ADS_AGENT_KEY="<apiKey from config>"
+npx mcporter call 'google-ads.<toolName>(accountId: "<accountId from config>")' --config ~/.claude/skills/ads/mcporter.json
+```
+
+**Examples:**
+
+```bash
+# List campaigns
+npx mcporter call 'google-ads.listCampaigns(accountId: "1234567890")' --config ~/.claude/skills/ads/mcporter.json
+
+# Get keywords for a campaign
+npx mcporter call 'google-ads.getKeywords(accountId: "1234567890", campaignId: "111222333")' --config ~/.claude/skills/ads/mcporter.json
+
+# No-parameter tools
+npx mcporter call google-ads.listConnectedAccounts --config ~/.claude/skills/ads/mcporter.json
+```
+
+Always pass `accountId` from `~/.adsagent/config.json` to every tool call (except `listConnectedAccounts`). All responses are JSON.
+
+## Available Tools
+
+### Read (safe, no side effects)
+- **getAccountInfo** — Account name, currency, timezone, test status
+- **listCampaigns** — All campaigns with impressions, clicks, cost, conversions
+- **getCampaignPerformance** — Daily metrics over a date range
+- **getKeywords** — Top keywords with quality scores
+- **getSearchTermReport** — Actual search queries triggering ads
+- **runGaqlQuery** — Run a custom read-only GAQL SELECT query (max 50 rows)
+- **getChanges** — Recent AdsAgent changes with `changeId`s for undo
+- **listConnectedAccounts** — All connected Google Ads accounts
+- **getTrackingTemplate** — Current tracking template at account/campaign/ad-group/ad level
+- **listAdGroups** — Ad groups in a campaign with metrics
+- **listAds** — Ads in a campaign/ad group with copy, URLs, status, metrics
+- **getImpressionShare** — Search/top/abs-top IS and budget/rank-lost IS
+- **getConversionActions** — Conversion actions and settings
+- **getAccountSettings** — Auto-tagging, tracking template, conversion tracking IDs
+- **getCampaignSettings** — Bidding, network, locations, schedule
+- **getRecommendations** — Google optimization recommendations
+
+### Write (mutates the account — always confirm with user first)
+All write tools return a `changeId` on success. Use this with `undoChange` to reverse the operation within 7 days.
+- **pauseKeyword** — Stop a keyword
+- **enableKeyword** — Re-enable a paused keyword
+- **addKeyword** — Add a new keyword to an ad group
+- **updateBid** — Change CPC bid (manual/enhanced CPC only, max 25% change)
+- **bulkUpdateBids** — Update multiple CPC bids in one call
+- **addNegativeKeyword** — Block irrelevant search terms (phrase match)
+- **removeNegativeKeyword** — Remove a negative keyword
+- **updateCampaignBudget** — Change daily budget (max 50% change)
+- **createCampaign** — Create a full paused search campaign
+- **pauseCampaign** — Pause all ads in a campaign
+- **enableCampaign** — Re-enable a paused campaign
+- **setTrackingTemplate** — Set/clear tracking template
+- **createAdGroup** — Create a new ad group
+- **createAd** — Create a new Responsive Search Ad
+- **pauseAd** — Pause an ad
+- **enableAd** — Re-enable an ad
+- **updateAdFinalUrl** — Change an ad's landing page URL
+- **updateAdAssets** — Replace an RSA's headlines/descriptions
+- **undoChange** — Reverse a previous write by `changeId`
+
+## Rules
+
+1. **Never make write changes without explicit user confirmation.** Always show what you plan to change, the current value, and the new value before executing.
+2. **Start with reads.** When the user asks about ads, begin with `getAccountInfo` and `listCampaigns` to build context.
+3. **Show numbers clearly.** Format cost as dollars, show CTR as percentages, include date ranges.
+4. **Recommend before acting.** When you spot waste (high-spend zero-conversion keywords, irrelevant search terms), recommend the action and wait for approval.
+5. **Guardrails are server-side.** Bid changes >25% and budget changes >50% will be rejected by the server. Don't try to circumvent this.
+6. **After every write, note the `changeId`.** Tell the user they can undo the change within 7 days. Use `getChanges` to review recent operations.
+
+## Common Workflows
+
+### "How are my ads doing?"
+1. `getAccountInfo` → `listCampaigns` → summarize top spenders, best/worst performers, total spend
+
+### "Find wasted spend"
+1. `listCampaigns` → pick top-spend campaigns
+2. `getKeywords` for each → find high-spend, zero-conversion keywords
+3. `getSearchTermReport` → find irrelevant search terms
+4. Recommend: pause wasteful keywords + add negative keywords
+
+### "Optimize bids"
+1. `getKeywords` → find keywords with good conversion rates but low impression share
+2. `getImpressionShare` / `getCampaignSettings` as needed for context
+3. Recommend bid increases (within 25% limit) for high-performers
+4. Recommend bid decreases for underperformers
diff --git a/google-ads/ads/mcporter.json b/google-ads/ads/mcporter.json
new file mode 100644
index 00000000..a83ee5ec
--- /dev/null
+++ b/google-ads/ads/mcporter.json
@@ -0,0 +1,19 @@
+{
+ "mcpServers": {
+ "google-ads": {
+ "command": "npx",
+ "args": [
+ "-y",
+ "mcp-remote",
+ "https://www.adsagent.org/api/mcp",
+ "--transport",
+ "http-first",
+ "--header",
+ "Authorization:Bearer ${ADS_AGENT_KEY}"
+ ],
+ "env": {
+ "ADS_AGENT_KEY": "${ADS_AGENT_KEY}"
+ }
+ }
+ }
+}
diff --git a/requirements-test.lock b/requirements-test.lock
new file mode 100644
index 00000000..734317a6
--- /dev/null
+++ b/requirements-test.lock
@@ -0,0 +1,63 @@
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+# pip-compile --output-file=requirements-test.lock requirements-test.txt
+#
+annotated-types==0.7.0
+ # via pydantic
+anthropic==0.86.0
+ # via -r requirements-test.txt
+anyio==4.13.0
+ # via
+ # anthropic
+ # httpx
+certifi==2026.2.25
+ # via
+ # httpcore
+ # httpx
+distro==1.9.0
+ # via anthropic
+docstring-parser==0.17.0
+ # via anthropic
+h11==0.16.0
+ # via httpcore
+httpcore==1.0.9
+ # via httpx
+httpx==0.28.1
+ # via anthropic
+idna==3.11
+ # via
+ # anyio
+ # httpx
+iniconfig==2.3.0
+ # via pytest
+jiter==0.13.0
+ # via anthropic
+packaging==26.0
+ # via pytest
+pluggy==1.6.0
+ # via pytest
+pydantic==2.12.5
+ # via anthropic
+pydantic-core==2.41.5
+ # via pydantic
+pygments==2.19.2
+ # via pytest
+pytest==9.0.2
+ # via
+ # -r requirements-test.txt
+ # pytest-timeout
+pytest-timeout==2.4.0
+ # via -r requirements-test.txt
+sniffio==1.3.1
+ # via anthropic
+typing-extensions==4.15.0
+ # via
+ # anthropic
+ # anyio
+ # pydantic
+ # pydantic-core
+ # typing-inspection
+typing-inspection==0.4.2
+ # via pydantic
diff --git a/requirements-test.txt b/requirements-test.txt
new file mode 100644
index 00000000..df83eb78
--- /dev/null
+++ b/requirements-test.txt
@@ -0,0 +1,3 @@
+anthropic>=0.40.0
+pytest>=8.0.0
+pytest-timeout>=2.3.0
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 00000000..450cff36
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,3 @@
+google-auth>=2.0.0
+google-auth-httplib2>=0.2.0
+requests>=2.28.0
diff --git a/seo/content-writer/SKILL.md b/seo/content-writer/SKILL.md
new file mode 100644
index 00000000..cb24b02c
--- /dev/null
+++ b/seo/content-writer/SKILL.md
@@ -0,0 +1,268 @@
+---
+name: content-writer
+description: >
+ Write SEO-optimized blog posts, landing pages, and content improvements
+ following Google's E-E-A-T and Helpful Content guidelines. Handles new content
+ creation from a keyword or topic, and improving existing pages. Use when asked
+ to "write a blog post", "create a landing page", "improve this page", "write
+ content about X", "content for keyword X", "draft an article", "blog post
+ about", "landing page for", "service page", "product page copy", "rewrite
+ this page", "make this page rank better", "content brief", "how-to guide",
+ "listicle", or any content creation or improvement task for a website.
+---
+
+## Preamble (run first)
+
+```bash
+_UPD=$(~/.claude/skills/toprank/bin/toprank-update-check 2>/dev/null || \
+ ~/.claude/skills/stockholm/bin/toprank-update-check 2>/dev/null || true)
+[ -n "$_UPD" ] && echo "$_UPD" || true
+```
+
+If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/toprank-upgrade` skill (Step 1 onward) to auto-upgrade, then return here and continue.
+
+If the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded from v{old} to v{new}" briefly, then continue.
+
+---
+
+# Content Writer
+
+You are a senior content strategist who writes content that ranks on Google AND
+genuinely helps readers. You combine SEO best practices with strong editorial
+standards. Every piece must pass Google's "helpful content" bar — it should be
+the last click the reader needs.
+
+You handle three jobs:
+1. **New blog post** — from a keyword or topic
+2. **New landing page** — service, product, location, or comparison page
+3. **Content improvement** — audit and rewrite an existing page
+
+---
+
+## Step 1 — Determine the Job
+
+Infer from the user's message. If obvious, skip asking.
+
+**Signals:**
+- "blog post about X", "how-to guide", "article about X", "listicle" → **Blog post**
+- "landing page", "service page", "product page", "pricing page", "location page" → **Landing page**
+- "improve this page", "rewrite", "make this better", URL or file path provided → **Content improvement**
+
+If ambiguous: "Are you looking for a blog post (educational), a landing page
+(conversion-focused), or improving an existing page?"
+
+---
+
+## Step 2 — Gather Context
+
+Collect what you need. Don't ask for things you can infer.
+
+### For new content (blog post or landing page):
+- **Target keyword** (required) — the primary query to rank for
+- **Audience** — who is this for?
+- **Site/brand context** — what does the business do, value prop?
+- **Existing pages** — related pages on the site to link to?
+- **Competitors** — what currently ranks? (offer to research if you have web access)
+
+### For content improvement:
+- **The content** — read the existing page (URL via firecrawl/web, or file path)
+- **Target keyword** — ask if not obvious from the content
+- **Goal** — better rankings, better conversion, or both?
+
+If spawned by seo-analysis, this context is already provided. Use it directly.
+
+---
+
+## Step 3 — Read the Guidelines
+
+Locate and read the content writing reference:
+
+```bash
+CONTENT_REF=$(find ~/.claude/skills ~/.codex/skills .agents/skills -name "content-writing.md" -path "*content-writer*" 2>/dev/null | head -1)
+if [ -z "$CONTENT_REF" ]; then
+ echo "WARNING: Could not find content-writing.md reference"
+else
+ echo "Reference at: $CONTENT_REF"
+fi
+```
+
+Read `$CONTENT_REF` (or `references/content-writing.md` if invoked directly).
+Follow the guidelines precisely throughout Steps 4-6.
+
+---
+
+## Step 4 — Research & Plan
+
+### Blog posts
+
+1. **Classify search intent** — informational or commercial investigation.
+ If the intent is transactional, tell the user a landing page would rank better.
+2. **SERP analysis** — if you have web access (firecrawl, WebSearch, browse), search
+ the target keyword. Note what the top 5 results use: format, depth, subtopics
+ covered, what they miss.
+3. **Define your angle** — what makes this post different? Original data, first-hand
+ experience, a more actionable approach, a specific niche. Never write a post that
+ just restates what's already ranking.
+4. **Create an outline:**
+
+```
+# [Title] (< 60 chars, keyword front-loaded)
+
+Meta description: [120-160 chars, keyword + CTA]
+Target keyword: [primary]
+Secondary keywords: [2-4 related terms]
+Search intent: [type]
+Content angle: [differentiator]
+
+## [H2 — answers the core question first]
+## [H2 — next most important subtopic]
+## [H2 — practical examples / case studies]
+## [H2 — common mistakes]
+## FAQ
+```
+
+5. **Present outline for approval** before writing. If spawned by seo-analysis with
+ clear context, proceed directly but show the outline as you go.
+
+### Landing pages
+
+1. **Verify intent** — must be transactional or commercial. If informational, suggest
+ a blog post instead.
+2. **Determine page type** — service, product, location, or comparison. Use the
+ matching template from the guidelines.
+3. **Define conversion strategy:**
+ - Primary CTA (the one action you want)
+ - Key objections to address
+ - Trust signals needed (testimonials, logos, case studies, guarantees)
+ - Differentiation (why this over competitors — be specific)
+4. **Create page structure** using the guidelines template for the page type.
+5. **Present for approval.**
+
+### Content improvement
+
+1. **Audit the existing content** against the full guidelines — On-Page SEO Checklist,
+ Anti-Patterns, E-E-A-T signals, heading structure, keyword usage, search intent match.
+2. **Classify what's wrong:**
+ - Intent mismatch (wrong content type for the keyword)
+ - Thin content (not enough depth)
+ - Missing E-E-A-T signals (no examples, data, or experience)
+ - Poor structure (no headings, wall of text)
+ - Keyword issues (stuffing, missing, or wrong target)
+ - Stale information (outdated stats, methods, pricing)
+3. **Present gap analysis:**
+ - What's working (keep)
+ - What's missing (add)
+ - What's hurting (remove or rewrite)
+ - Structural changes needed
+4. **Get approval** before rewriting.
+
+---
+
+## Step 5 — Write
+
+Follow the writing rules from the guidelines for the content type. Key principles
+that apply to all content:
+
+**Lead with value.** First paragraph directly addresses the search intent. No
+throat-clearing ("In today's digital landscape...").
+
+**Show experience.** Specific examples, data, scenarios. "We found that..." and
+"In our testing..." signal first-hand knowledge. If the site has its own data,
+weave it in.
+
+**Be concrete.** Every recommendation includes the what, why, and how. "Add a
+sticky CTA bar — we saw a 23% increase on mobile" not "improve your CTAs."
+
+**Structure for scanning.** Short paragraphs (2-4 sentences), bullet lists, bold
+key phrases, tables for comparisons. One idea per paragraph.
+
+**Keyword placement.** Primary keyword in: title tag (front-loaded), H1, first
+100 words, 1-2 H2s naturally, meta description. After that: synonyms and natural
+language. No stuffing.
+
+### Deliverables for blog posts:
+1. Full post in markdown with heading hierarchy (H1 → H2 → H3)
+2. SEO metadata: title tag (< 60 chars), meta description (120-160 chars), URL slug
+3. JSON-LD structured data (`Article`/`BlogPosting` + `FAQPage` if FAQ included)
+4. Internal linking plan (pages to link to and from)
+5. Publishing checklist
+
+### Deliverables for landing pages:
+1. Full page copy in markdown with heading hierarchy and CTA placements marked
+2. SEO metadata: title tag, meta description, URL slug
+3. Conversion strategy: primary CTA, objections addressed, trust signals
+4. JSON-LD structured data (`Service`/`Product`/`LocalBusiness` + `FAQPage`)
+5. Internal linking plan + navigation placement suggestion
+6. Publishing checklist
+
+### Deliverables for content improvement:
+1. Rewritten content in markdown (full replacement, not patches)
+2. Change summary: what changed and why (tied to specific guideline violations)
+3. Updated SEO metadata if needed
+4. Updated structured data if needed
+
+### Output Format
+
+```
+# [Content Type]: [Title]
+
+## SEO Metadata
+- **Title tag:** [< 60 chars]
+- **Meta description:** [120-160 chars]
+- **URL slug:** /[slug]
+- **Target keyword:** [primary]
+- **Secondary keywords:** [list]
+
+## Content
+[Full content in markdown with proper heading hierarchy]
+
+## Structured Data
+[JSON-LD ready to paste]
+
+## Internal Linking Plan
+- **Link TO this page from:** [existing pages + suggested anchor text]
+- **This page links to:** [internal links in the content]
+
+## Publishing Checklist
+- [ ] Title tag and meta description set
+- [ ] URL slug configured
+- [ ] Structured data added
+- [ ] Internal links placed (both directions)
+- [ ] Open Graph image added
+- [ ] Canonical URL set to self
+- [ ] Mobile rendering verified
+```
+
+---
+
+## Step 6 — Quality Gate
+
+Before delivering, verify against every check. Fix failures before presenting.
+
+### The "Last Click" Test
+Would the reader need to search again? If yes, the content isn't done.
+
+### E-E-A-T Check
+- Does it contain specific examples only someone with experience would include?
+- Is there original analysis or insight — not just restated common knowledge?
+- Are claims backed by sources or data?
+
+### Anti-Pattern Check (from guidelines)
+- No keyword stuffing
+- No filler paragraphs (every paragraph earns its place)
+- No generic AI hedging ("it depends", "many factors" without committing)
+- No wall of text (headings, bullets, bold key phrases throughout)
+- No duplicate intent with existing pages on the site
+
+### Format Match
+Does the content type match what Google shows for this query?
+
+### On-Page SEO (from guidelines checklist)
+Title, meta description, H1, heading hierarchy, keyword placement, internal links,
+image alt text, URL slug — all present and correct.
+
+### Landing Page Extra Checks
+- Would you convert after reading this? What's missing if not?
+- Are vague claims replaced with specifics?
+- Is every major objection addressed?
+- Is the CTA immediately clear?
diff --git a/seo/content-writer/references/content-writing.md b/seo/content-writer/references/content-writing.md
new file mode 100644
index 00000000..54c48161
--- /dev/null
+++ b/seo/content-writer/references/content-writing.md
@@ -0,0 +1,237 @@
+# Content Writing Guidelines — Google Best Practices
+
+Reference for writing content that ranks. Derived from Google's Helpful Content
+System, E-E-A-T quality rater guidelines, and Search Central documentation.
+
+---
+
+## Table of Contents
+
+1. [E-E-A-T Framework](#e-e-a-t-framework)
+2. [Helpful Content Signals](#helpful-content-signals)
+3. [Blog Posts](#blog-posts)
+4. [Landing Pages](#landing-pages)
+5. [Search Intent Matching](#search-intent-matching)
+6. [On-Page SEO Checklist](#on-page-seo-checklist)
+7. [Anti-Patterns](#anti-patterns)
+
+---
+
+## E-E-A-T Framework
+
+Google evaluates content on four axes:
+
+### Experience
+- Show first-hand experience — specific examples, scenarios, case studies
+- Use language that reflects direct involvement ("we found", "in our testing")
+- Reference real data, outcomes, or results
+
+### Expertise
+- Go beyond surface-level — cover edge cases only a practitioner would know
+- Use precise terminology correctly but define it for the reader
+- Link to authoritative sources for factual claims
+
+### Authoritativeness
+- Establish why this source is credible on this topic
+- Include author bios with relevant credentials
+- Build topical authority via internal linking to related content
+
+### Trustworthiness
+- Be transparent about limitations and conflicts of interest
+- Cite sources for statistics and claims
+- Keep content accurate and up to date
+
+**YMYL topics** (health, finance, safety, legal) require the highest E-E-A-T bar.
+
+---
+
+## Helpful Content Signals
+
+### Content IS helpful when it:
+- Has a clear, specific audience in mind
+- Leaves the reader feeling they've learned enough to achieve their goal
+- Provides original value — analysis, insight, research, not just compilation
+- Has a satisfying amount of information (not thin, not padded)
+
+### The "Last Click" Test
+After reading, would the reader need to search again? If yes, the content isn't
+done. The goal is to be the last click.
+
+---
+
+## Blog Posts
+
+### When to Use
+Informational and commercial-investigation intent: "how to", "what is", "best X",
+"X vs Y", guides, tutorials, listicles, reviews.
+
+### Structure
+```
+H1: Primary topic (one per page, includes primary keyword)
+ H2: Major section (answer core question first — don't bury the lead)
+ H3: Supporting detail
+ H2: Practical examples / case studies
+ H2: Common mistakes
+ H2: FAQ (targets People Also Ask)
+```
+
+### Writing Rules
+1. **Open with the answer** — first paragraph directly addresses search intent
+2. **Show experience** — specific examples, data, "we found that..." language
+3. **Be concrete** — "Add a sticky CTA bar — we saw 23% lift on mobile" not "improve your CTA"
+4. **Structure for scanning** — short paragraphs (2-4 sentences), bullets, bold key phrases
+5. **Link internally** — 3-5 related pages, descriptive anchor text
+6. **Cite sources** — link to data sources and authoritative references
+7. **Write to completeness, not word count** — cover the topic fully, then stop
+
+### Keyword Placement
+- Title tag (front-loaded, < 60 chars)
+- H1
+- First 100 words
+- 1-2 H2 headings naturally
+- Meta description (120-160 chars)
+- After that: synonyms and natural language — no stuffing
+
+### Required Sections
+1. Opening hook — state the problem, signal you'll answer concretely
+2. Core content — main answer with clear H2/H3 structure
+3. Practical examples — at least one real scenario
+4. Common mistakes — what people get wrong
+5. Next steps / CTA
+6. FAQ (3-5 questions targeting related searches)
+
+### Metadata
+- **Title tag:** < 60 chars, keyword front-loaded, includes value prop
+- **Meta description:** 120-160 chars, keyword + reason to click
+- **URL slug:** short, readable, keyword-rich. `/blog/optimize-title-tags`
+- **Structured data:** `Article` or `BlogPosting`; add `HowTo` for tutorials, `FAQPage` for FAQ sections
+
+---
+
+## Landing Pages
+
+### When to Use
+Transactional and commercial intent: "buy", "pricing", "near me", "[service] in
+[city]", "best [product] for [use case]".
+
+### Core Principles
+1. **Specificity converts** — replace every vague claim with numbers or examples
+2. **Benefits over features** — lead with what the customer gets, not what it does
+3. **Address objections directly** — price, trust, switching costs, "does it work?"
+4. **One page, one job** — every element moves toward the CTA
+5. **Social proof is mandatory** — testimonials, logos, stats, case studies
+
+### Structure by Page Type
+
+**Service page:**
+```
+H1: Service + Primary Benefit
+Hero subhead + Primary CTA
+H2: The Problem (show you understand their situation)
+H2: How It Works (3-4 clear steps)
+H2: Results (specific outcomes with numbers)
+H2: Social Proof (testimonials, logos, case studies)
+H2: Pricing (if applicable)
+H2: FAQ (5-8 objection-handling questions)
+Final CTA
+```
+
+**Product page:**
+```
+H1: Product + Key Benefit
+Hero + CTA
+H2: Features → Benefits (not just feature lists)
+H2: How It Works
+H2: Who It's For (specific use cases)
+H2: Reviews / Social Proof
+H2: Pricing
+H2: FAQ
+Final CTA
+```
+
+**Location page:**
+```
+H1: [Service] in [City]
+Local value prop + CTA
+H2: Local-specific content (NOT generic copy with city swapped)
+H2: Why Choose Us in [City] (local presence, case studies)
+H2: Service Areas
+H2: FAQ (local-specific concerns)
+CTA with local contact
+```
+
+### SEO for Landing Pages
+- Lighter keyword density than blog posts
+- Primary keyword in: title, H1, first paragraph, 1 H2, meta description
+- 500-1500 words of genuine content (thin pages with just a headline + form don't rank)
+- FAQ section serves dual purpose: conversion (objection handling) + SEO (long-tail queries)
+
+### Metadata
+- **Title tag:** "[Service/Product] — [Benefit] | [Brand]" (< 60 chars)
+- **Meta description:** 120-160 chars, includes CTA ("Get started free", "See pricing")
+- **URL slug:** `/[service-name]`, `/products/[product-name]`, `/[service]-[city]`
+- **Structured data:** Service page → `Service` + `FAQPage`; Product → `Product` + `Offer` + `FAQPage`; Local → `LocalBusiness` + `FAQPage`
+
+---
+
+## Search Intent Matching
+
+| Intent | Keyword Signals | Content Type |
+|--------|----------------|-------------|
+| **Informational** | "how to", "what is", "guide" | Blog post, tutorial |
+| **Commercial** | "best", "vs", "review", "top" | Comparison, listicle |
+| **Transactional** | "buy", "price", "near me" | Landing/product page |
+| **Navigational** | brand name, product name | Homepage, product page |
+
+**How to verify:** search the keyword incognito, look at top 5 results. Match
+that format — don't fight the SERP.
+
+**Mismatch = won't rank:**
+- Blog post targeting "buy [product]" → should be product page
+- Product page targeting "how to [task]" → should be tutorial
+- Generic page targeting "[service] in [city]" → should be location page
+
+---
+
+## On-Page SEO Checklist
+
+### Must-Have
+- [ ] Title tag with primary keyword, < 60 chars
+- [ ] Meta description with keyword + CTA, 120-160 chars
+- [ ] Single H1 with primary keyword
+- [ ] Logical heading hierarchy (H1 → H2 → H3)
+- [ ] Primary keyword in first 100 words naturally
+- [ ] Internal links to 3-5 related pages
+- [ ] Images have descriptive alt text
+- [ ] URL is short, readable, includes keyword slug
+
+### Should-Have
+- [ ] Structured data (Article, Product, Service, HowTo, FAQPage)
+- [ ] Table of contents for long content (> 1500 words)
+- [ ] External links to authoritative sources
+- [ ] Author byline with credentials
+- [ ] Last-updated date for evergreen content
+- [ ] Open Graph + Twitter Card meta tags
+
+---
+
+## Anti-Patterns
+
+### Content Anti-Patterns
+- **Keyword stuffing** — use the keyword naturally; synonyms after the first few placements
+- **Thin content** — pages under 300 words competing for hard terms
+- **Content for content's sake** — topics with no real expertise behind them
+- **Wall of text** — no headings, no lists, no visual breaks
+- **Duplicate intent** — two pages targeting same keyword = cannibalization
+- **Stale content** — outdated stats, deprecated methods, old pricing
+
+### AI Content Anti-Patterns
+Google doesn't penalize AI content per se — it penalizes unhelpful content.
+Common AI failure modes:
+- Generic summaries restating common knowledge
+- Excessive hedging ("it depends", "many factors") without commitments
+- Missing experience signals — no examples, data, or first-hand knowledge
+- Perfect grammar, zero original insight
+
+**Fix:** inject real data, specific examples, original analysis, concrete
+recommendations. Make it something only someone with actual expertise could write.
diff --git a/seo/keyword-research/SKILL.md b/seo/keyword-research/SKILL.md
new file mode 100644
index 00000000..c92541e5
--- /dev/null
+++ b/seo/keyword-research/SKILL.md
@@ -0,0 +1,314 @@
+---
+name: keyword-research
+description: >
+ Discover, analyze, and prioritize keywords for SEO and GEO content strategies.
+ Identifies high-value opportunities based on search volume, competition,
+ intent, and business relevance. Generates topic clusters and content calendars.
+ Use when asked to "find keywords", "keyword research", "what should I write
+ about", "keyword analysis", "find me topics to write", "search volume",
+ "keyword difficulty", "content ideas", or any keyword discovery task.
+---
+
+## Preamble (run first)
+
+```bash
+_UPD=$(~/.claude/skills/toprank/bin/toprank-update-check 2>/dev/null || \
+ ~/.claude/skills/stockholm/bin/toprank-update-check 2>/dev/null || true)
+[ -n "$_UPD" ] && echo "$_UPD" || true
+```
+
+If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/toprank-upgrade` skill (Step 1 onward) to auto-upgrade, then return here and continue.
+
+If the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded from v{old} to v{new}" briefly, then continue.
+
+---
+
+# Keyword Research
+
+
+
+Discovers, analyzes, and prioritizes keywords for SEO and GEO content strategies. Identifies high-value opportunities based on search volume, competition, intent, and business relevance.
+
+## When This Must Trigger
+
+Use this when the conversation involves any of these situations — even if the user does not use SEO terminology:
+
+Use this whenever the task needs reusable market intelligence that should influence strategy, not just an ad hoc answer.
+
+- Starting a new content strategy or campaign
+- Expanding into new topics or markets
+- Finding keywords for a specific product or service
+- Identifying long-tail keyword opportunities
+- Understanding search intent for your industry
+- Planning content calendars
+- Researching keywords for GEO optimization
+
+## What This Skill Does
+
+1. **Keyword Discovery**: Generates comprehensive keyword lists from seed terms
+2. **Intent Classification**: Categorizes keywords by user intent (informational, navigational, commercial, transactional)
+3. **Difficulty Assessment**: Evaluates competition level and ranking difficulty
+4. **Opportunity Scoring**: Prioritizes keywords by potential ROI
+5. **Clustering**: Groups related keywords into topic clusters
+6. **GEO Relevance**: Identifies keywords likely to trigger AI responses
+
+## Quick Start
+
+Start with one of these prompts.
+
+### Basic Keyword Research
+
+```
+Research keywords for [topic/product/service]
+```
+
+```
+Find keyword opportunities for a [industry] business targeting [audience]
+```
+
+### With Specific Goals
+
+```
+Find low-competition keywords for [topic] with commercial intent
+```
+
+```
+Identify question-based keywords for [topic] that AI systems might answer
+```
+
+### Competitive Research
+
+```
+What keywords is [competitor URL] ranking for that I should target?
+```
+
+## Data Sources
+
+> **Note:** All integrations are optional. This skill works without any API keys — users provide data manually when no tools are connected.
+
+**With ~~SEO tool + ~~search console connected:**
+Automatically pull historical search volume data, keyword difficulty scores, SERP analysis, current rankings from ~~search console, and competitor keyword overlap. The skill will fetch seed keyword metrics, related keyword suggestions, and search trend data.
+
+**With manual data only:**
+Ask the user to provide:
+1. Seed keywords or topic description
+2. Target audience and geographic location
+3. Business goals (traffic, leads, sales)
+4. Current domain authority (if known) or site age
+5. Any known keyword performance data or search volume estimates
+
+Proceed with the full analysis using provided data. Note in the output which metrics are from automated collection vs. user-provided data.
+
+## Instructions
+
+When a user requests keyword research:
+
+1. **Understand the Context**
+
+ Ask clarifying questions if not provided:
+ - What is your product/service/topic?
+ - Who is your target audience?
+ - What is your business goal? (traffic, leads, sales)
+ - What is your current domain authority? (new site, established, etc.)
+ - Any specific geographic targeting?
+ - Preferred language?
+
+2. **Generate Seed Keywords**
+
+ Start with:
+ - Core product/service terms
+ - Problem-focused keywords (what issues do you solve?)
+ - Solution-focused keywords (how do you help?)
+ - Audience-specific terms
+ - Industry terminology
+
+3. **Expand Keyword List**
+
+ For each seed keyword, generate variations:
+
+ ```markdown
+ ## Keyword Expansion Patterns
+
+ ### Modifiers
+ - Best [keyword]
+ - Top [keyword]
+ - [keyword] for [audience]
+ - [keyword] near me
+ - [keyword] [year]
+ - How to [keyword]
+ - What is [keyword]
+ - [keyword] vs [alternative]
+ - [keyword] examples
+ - [keyword] tools
+
+ ### Long-tail Variations
+ - [keyword] for beginners
+ - [keyword] for small business
+ - Free [keyword]
+ - [keyword] software/tool/service
+ - [keyword] template
+ - [keyword] checklist
+ - [keyword] guide
+ ```
+
+4. **Classify Search Intent**
+
+ Categorize each keyword:
+
+ | Intent | Signals | Example | Content Type |
+ |--------|---------|---------|--------------|
+ | Informational | what, how, why, guide, learn | "what is SEO" | Blog posts, guides |
+ | Navigational | brand names, specific sites | "google analytics login" | Homepage, product pages |
+ | Commercial | best, review, vs, compare | "best SEO tools [current year]" | Comparison posts, reviews |
+ | Transactional | buy, price, discount, order | "buy SEO software" | Product pages, pricing |
+
+5. **Assess Keyword Difficulty**
+
+ Score each keyword (1-100 scale):
+
+ ```markdown
+ ### Difficulty Factors
+
+ **High Difficulty (70-100)**
+ - Major brands ranking
+ - High domain authority competitors
+ - Established content (1000+ backlinks)
+ - Paid ads dominating SERP
+
+ **Medium Difficulty (40-69)**
+ - Mix of authority and niche sites
+ - Some opportunities for quality content
+ - Moderate backlink requirements
+
+ **Low Difficulty (1-39)**
+ - Few authoritative competitors
+ - Thin or outdated content ranking
+ - Long-tail variations
+ - New or emerging topics
+ ```
+
+6. **Calculate Opportunity Score**
+
+ Formula: `Opportunity = (Volume × Intent Value) / Difficulty`
+
+ **Intent Value** assigns a numeric weight by search intent:
+ - Informational = 1
+ - Navigational = 1
+ - Commercial = 2
+ - Transactional = 3
+
+ ```markdown
+ ### Opportunity Matrix
+
+ | Scenario | Volume | Difficulty | Intent | Priority |
+ |----------|--------|------------|--------|----------|
+ | Quick Win | Low-Med | Low | High | ⭐⭐⭐⭐⭐ |
+ | Growth | High | Medium | High | ⭐⭐⭐⭐ |
+ | Long-term | High | High | High | ⭐⭐⭐ |
+ | Research | Low | Low | Low | ⭐⭐ |
+ ```
+
+7. **Identify GEO Opportunities**
+
+ Keywords likely to trigger AI responses:
+
+ ```markdown
+ ### GEO-Relevant Keywords
+
+ **High GEO Potential**
+ - Question formats: "What is...", "How does...", "Why is..."
+ - Definition queries: "[term] meaning", "[term] definition"
+ - Comparison queries: "[A] vs [B]", "difference between..."
+ - List queries: "best [category]", "top [number] [items]"
+ - How-to queries: "how to [action]", "steps to [goal]"
+
+ **AI Answer Indicators**
+ - Query is factual/definitional
+ - Answer can be summarized concisely
+ - Topic is well-documented online
+ - Low commercial intent
+ ```
+
+8. **Create Topic Clusters**
+
+ Group keywords into content clusters:
+
+ ```markdown
+ ## Topic Cluster: [Main Topic]
+
+ **Pillar Content**: [Primary keyword]
+ - Search volume: [X]
+ - Difficulty: [X]
+ - Content type: Comprehensive guide
+
+ **Cluster Content**:
+
+ ### Sub-topic 1: [Secondary keyword]
+ - Volume: [X]
+ - Difficulty: [X]
+ - Links to: Pillar
+ - Content type: [Blog post/Tutorial/etc.]
+
+ ### Sub-topic 2: [Secondary keyword]
+ - Volume: [X]
+ - Difficulty: [X]
+ - Links to: Pillar + Sub-topic 1
+ - Content type: [Blog post/Tutorial/etc.]
+
+ [Continue for all cluster keywords...]
+ ```
+
+9. **Generate Output Report**
+
+ Produce a report containing: Executive Summary, Top Keyword Opportunities (Quick Wins, Growth, GEO), Topic Clusters, Content Calendar, and Next Steps.
+
+ > **Reference**: See [references/example-report.md](references/example-report.md) for the full report template and example.
+
+## Validation Checkpoints
+
+### Input Validation
+- [ ] Seed keywords or topic description clearly provided
+- [ ] Target audience and business goals specified
+- [ ] Geographic and language targeting confirmed
+- [ ] Domain authority or site maturity level established
+
+### Output Validation
+- [ ] Every recommendation cites specific data points (not generic advice)
+- [ ] Search volume and difficulty scores included for each keyword
+- [ ] Keywords grouped by intent and mapped to content types
+- [ ] Topic clusters show clear pillar-to-cluster relationships
+- [ ] Source of each data point clearly stated (~~SEO tool data, user-provided, or estimated)
+
+## Example
+
+> **Reference**: See [references/example-report.md](references/example-report.md) for a complete example report for "project management software for small businesses".
+
+### Advanced Usage
+
+- **Intent Mapping**: `Map all keywords for [topic] by search intent and funnel stage`
+- **Seasonal Analysis**: `Identify seasonal keyword trends for [industry]`
+- **Competitor Gap**: `What keywords do [competitor 1], [competitor 2] rank for that I'm missing?`
+- **Local Keywords**: `Research local keywords for [business type] in [city/region]`
+
+## Tips for Success
+
+1. **Start with seed keywords** that describe your core offering
+2. **Don't ignore long-tail** - they often have highest conversion rates
+3. **Match content to intent** - informational queries need guides, not sales pages
+4. **Group into clusters** for topical authority
+5. **Prioritize quick wins** to build momentum and credibility
+6. **Include GEO keywords** in your strategy for AI visibility
+7. **Review quarterly** - keyword dynamics change over time
+
+
+
+## Reference Materials
+
+- [Keyword Intent Taxonomy](references/keyword-intent-taxonomy.md) — Complete intent classification with signal words and content strategies
+- [Topic Cluster Templates](references/topic-cluster-templates.md) — Hub-and-spoke architecture templates for pillar and cluster content
+- [Keyword Prioritization Framework](references/keyword-prioritization-framework.md) — Priority scoring matrix, categories, and seasonal keyword patterns
+- [Example Report](references/example-report.md) — Complete example keyword research report for project management software
+
+## Next Best Skill
+
+- **Primary**: [content-writer](../content-writer/SKILL.md) — turn keyword opportunities into optimized content.
diff --git a/seo/keyword-research/references/example-report.md b/seo/keyword-research/references/example-report.md
new file mode 100644
index 00000000..3c0a0f49
--- /dev/null
+++ b/seo/keyword-research/references/example-report.md
@@ -0,0 +1,96 @@
+# Keyword Research — Example Report
+
+This is a complete example output showing the expected format for keyword research deliverables.
+
+## Prompt
+
+**User**: "Research keywords for a project management software company targeting small businesses"
+
+## Example Output
+
+```markdown
+# Keyword Research Report: Project Management Software
+
+**Generated**: [current month and year]
+**Target Audience**: Small business owners and teams
+**Business Goal**: Software signups and trials
+
+## Executive Summary
+
+- Total keywords analyzed: 150+
+- High-priority opportunities: 23
+- Estimated traffic potential: 45,000/month
+- Recommended focus areas:
+ - Task management workflows
+ - Team collaboration
+ - Small business productivity
+
+## Top Keyword Opportunities
+
+### Quick Wins (Priority: Immediate)
+
+| Keyword | Volume | Difficulty | Intent | Score |
+|---------|--------|------------|--------|-------|
+| project management for small teams | 1,200 | 28 | Commercial | 92 |
+| simple task management software | 890 | 25 | Commercial | 89 |
+| best free project management tool | 2,400 | 35 | Commercial | 85 |
+| how to manage remote team projects | 720 | 22 | Informational | 82 |
+| project tracking spreadsheet alternative | 480 | 18 | Commercial | 80 |
+
+### Growth Keywords (Priority: 3-6 months)
+
+| Keyword | Volume | Difficulty | Intent | Score |
+|---------|--------|------------|--------|-------|
+| project management software | 18,000 | 72 | Commercial | 65 |
+| best project management tools [current year] | 8,500 | 65 | Commercial | 62 |
+| project management app | 12,000 | 68 | Commercial | 58 |
+
+### GEO Opportunities (AI-citation potential)
+
+| Keyword | Type | AI Potential | Recommended Format |
+|---------|------|--------------|-------------------|
+| what is project management | Definition | ⭐⭐⭐⭐⭐ | Clear definition + methodology |
+| agile vs waterfall | Comparison | ⭐⭐⭐⭐⭐ | Side-by-side comparison table |
+| project management methodologies | List | ⭐⭐⭐⭐ | Comprehensive list with pros/cons |
+| how to create a project plan | How-to | ⭐⭐⭐⭐ | Step-by-step guide |
+| project management best practices | List | ⭐⭐⭐⭐ | Numbered best practices |
+
+## Topic Clusters
+
+### Cluster 1: Project Management Fundamentals
+
+**Pillar**: "Complete Guide to Project Management" (8,500 volume)
+
+Cluster articles:
+1. What is project management? (2,200 volume)
+2. Project management methodologies explained (1,800 volume)
+3. How to create a project plan (1,400 volume)
+4. Project management best practices (1,200 volume)
+5. Project management roles and responsibilities (890 volume)
+
+### Cluster 2: Team Collaboration
+
+**Pillar**: "Team Collaboration Tools Guide" (4,200 volume)
+
+Cluster articles:
+1. How to improve team communication (1,600 volume)
+2. Remote team management tips (1,400 volume)
+3. Best practices for distributed teams (920 volume)
+4. Team productivity tools comparison (780 volume)
+
+## Content Calendar Recommendations
+
+| Month | Content | Target Keyword | Type |
+|-------|---------|----------------|------|
+| Week 1 | Simple Task Management Guide | simple task management software | Blog + Demo |
+| Week 2 | Project Management for Small Teams | project management for small teams | Pillar Page |
+| Week 3 | Agile vs Waterfall: Complete Comparison | agile vs waterfall | Comparison |
+| Week 4 | Free PM Tools Roundup | best free project management tool | Listicle |
+
+## Next Steps
+
+1. **Immediate**: Create landing pages for top 5 quick-win keywords
+2. **Week 1-2**: Write pillar content for "Project Management Fundamentals"
+3. **Week 3-4**: Build out cluster content with internal linking
+4. **Ongoing**: Track rankings and adjust strategy based on performance
+```
diff --git a/seo/keyword-research/references/keyword-intent-taxonomy.md b/seo/keyword-research/references/keyword-intent-taxonomy.md
new file mode 100644
index 00000000..7e5f3625
--- /dev/null
+++ b/seo/keyword-research/references/keyword-intent-taxonomy.md
@@ -0,0 +1,324 @@
+# Keyword Intent Taxonomy
+
+A comprehensive classification system for understanding search intent, mapping keywords to content strategies, and aligning with conversion funnels.
+
+## Overview
+
+Search intent (also called user intent or query intent) is the underlying goal a user has when typing a query into a search engine or AI system. Correctly classifying intent determines content format, tone, depth, and conversion strategy.
+
+This taxonomy defines **4 primary intent types**, each with **3-4 sub-categories**, along with signal words, SERP feature correlations, and content format recommendations.
+
+---
+
+## Primary Intent Types
+
+### 1. Informational Intent
+
+The user wants to **learn something**. They are seeking knowledge, not a product.
+
+#### Sub-categories
+
+| Sub-category | Description | Example Queries |
+|-------------|------------|----------------|
+| **Educational** | Broad learning about a topic | "what is SEO", "content marketing explained", "how search engines work" |
+| **Instructional** | Step-by-step guidance on completing a task | "how to set up Google Analytics", "how to write a meta description", "how to do keyword research" |
+| **Exploratory** | Open-ended research to understand options | "types of SEO strategies", "content marketing trends", "link building techniques" |
+| **Troubleshooting** | Diagnosing and fixing a problem | "why is my site not ranking", "Google indexing issues", "404 error fix" |
+
+#### Signal Words and Modifiers
+
+**Strong informational signals:**
+- what, what is, what are, what does
+- how, how to, how does, how do I
+- why, why is, why does, why do
+- when, when to, when should
+- who, who is, who does
+- where, where to, where can I
+- guide, tutorial, learn, explain
+- examples, tips, ideas, ways
+- definition, meaning, difference between
+- history of, basics of, introduction to
+- pros and cons, advantages, disadvantages
+- best practices, checklist, steps
+
+**Weak informational signals (may overlap with commercial):**
+- overview, comparison, review (can be commercial)
+- list of, types of, methods
+
+#### SERP Feature Correlation
+
+| SERP Feature | Frequency for Informational | Notes |
+|-------------|---------------------------|-------|
+| Featured Snippet | Very High | Especially for "what is" and "how to" queries |
+| People Also Ask | Very High | Almost always present for informational queries |
+| Knowledge Panel | High | For entity-related informational queries |
+| AI Overview | Very High | AI systems prioritize informational answers |
+| Video Carousel | Medium-High | Especially for instructional queries |
+| Image Pack | Medium | For visual/diagram-seeking queries |
+| Shopping Results | Very Low | Rarely appears for pure informational |
+
+#### Content Format Recommendations
+
+| Sub-category | Best Formats | Target Length | Key Elements |
+|-------------|-------------|--------------|-------------|
+| Educational | Definitive guides, explainers, glossary entries | 1,500-3,000 words | Clear definitions, examples, visuals |
+| Instructional | Step-by-step tutorials, how-to guides, video walkthroughs | 2,000-4,000 words | Numbered steps, screenshots, code samples |
+| Exploratory | Listicles, roundups, trend reports, comparison tables | 2,000-3,500 words | Categories, pros/cons, use cases |
+| Troubleshooting | FAQ pages, debug guides, knowledge base articles | 800-2,000 words | Problem-solution pairs, error codes, screenshots |
+
+---
+
+### 2. Navigational Intent
+
+The user wants to **find a specific website, page, or resource**. They already know where they want to go.
+
+#### Sub-categories
+
+| Sub-category | Description | Example Queries |
+|-------------|------------|----------------|
+| **Brand Search** | Looking for a specific company or product | "Ahrefs", "HubSpot CRM", "Moz Pro" |
+| **Product/Feature Search** | Looking for a specific feature or tool within a known brand | "Ahrefs keyword explorer", "Google Search Console coverage report" |
+| **Login/Access** | Trying to access an account or dashboard | "Ahrefs login", "Google Analytics sign in", "SEMrush dashboard" |
+| **Support/Docs** | Seeking help documentation for a known product | "Ahrefs API documentation", "Google Search Console help" |
+
+#### Signal Words and Modifiers
+
+**Strong navigational signals:**
+- [brand name] (standalone)
+- [brand name] login, sign in, sign up
+- [brand name] pricing, plans
+- [brand name] support, help, docs
+- [brand name] [feature name]
+- [brand name] download, app
+- official, website, site
+- [brand name] alternatives (borderline commercial)
+
+#### SERP Feature Correlation
+
+| SERP Feature | Frequency for Navigational | Notes |
+|-------------|---------------------------|-------|
+| Sitelinks | Very High | Brand queries almost always show sitelinks |
+| Knowledge Panel | High | For established brands with Google entity |
+| Featured Snippet | Low | Rarely for pure navigational |
+| People Also Ask | Medium | Often brand-related questions |
+| AI Overview | Low | AI usually defers to direct navigation |
+
+#### Content Format Recommendations
+
+| Sub-category | Best Formats | Key Elements |
+|-------------|-------------|-------------|
+| Brand Search | Homepage, about page, landing pages | Clear branding, value prop, navigation |
+| Product/Feature Search | Product pages, feature pages | Feature details, CTAs, screenshots |
+| Login/Access | Login page, getting started guide | Fast load, clear login form, password reset |
+| Support/Docs | Knowledge base, documentation hub | Search functionality, categorized articles |
+
+---
+
+### 3. Commercial Investigation Intent
+
+The user is **researching before making a purchase decision**. They are comparing options, reading reviews, and evaluating alternatives.
+
+#### Sub-categories
+
+| Sub-category | Description | Example Queries |
+|-------------|------------|----------------|
+| **Comparison** | Evaluating two or more specific options | "Ahrefs vs SEMrush", "WordPress vs Squarespace for SEO" |
+| **Review-seeking** | Looking for opinions and evaluations | "Ahrefs review 2026", "best SEO tool reviews", "is Moz worth it" |
+| **Best-of Research** | Seeking curated top options in a category | "best SEO tools", "top keyword research tools", "best free backlink checkers" |
+| **Evaluation** | Assessing fit for a specific need | "SEO tools for small business", "enterprise SEO platform features", "SEO tool for agencies" |
+
+#### Signal Words and Modifiers
+
+**Strong commercial signals:**
+- best, top, leading
+- vs, versus, compared to, comparison
+- review, reviews, rating, ratings
+- alternative, alternatives to
+- like [brand], similar to
+- for [audience], for [use case]
+- pros and cons (when about products)
+- worth it, is [product] good
+- features, capabilities, integrations
+- pricing, cost, how much
+- free vs paid, premium
+
+**Seasonal/temporal commercial signals:**
+- [product] [year] (e.g., "best SEO tools 2026")
+- new, latest, updated
+
+#### SERP Feature Correlation
+
+| SERP Feature | Frequency for Commercial | Notes |
+|-------------|------------------------|-------|
+| People Also Ask | Very High | Comparison and evaluation questions |
+| Featured Snippet | High | Especially for "best" and comparison queries |
+| AI Overview | High | AI often synthesizes comparisons |
+| Shopping Results | Medium | When products have direct purchase path |
+| Video Carousel | Medium | Review and comparison videos |
+| Ads (top) | Very High | Advertisers target commercial intent heavily |
+
+#### Content Format Recommendations
+
+| Sub-category | Best Formats | Target Length | Key Elements |
+|-------------|-------------|--------------|-------------|
+| Comparison | Side-by-side comparison pages, "X vs Y" articles | 2,500-4,000 words | Feature tables, pricing tables, verdict |
+| Review-seeking | In-depth reviews, user testimonials, case studies | 2,000-3,500 words | Honest pros/cons, screenshots, scoring |
+| Best-of Research | Ranked listicles, category roundups | 3,000-5,000 words | Criteria explanation, mini-reviews, comparison table |
+| Evaluation | Buying guides, use-case guides, ROI calculators | 2,000-3,500 words | Decision criteria, audience segmentation, recommendations |
+
+---
+
+### 4. Transactional Intent
+
+The user wants to **complete a specific action**, typically a purchase, signup, or download.
+
+#### Sub-categories
+
+| Sub-category | Description | Example Queries |
+|-------------|------------|----------------|
+| **Purchase** | Ready to buy a product or service | "buy Ahrefs subscription", "SEMrush pricing plans", "order SEO audit" |
+| **Signup/Trial** | Ready to create an account or start a trial | "Ahrefs free trial", "sign up for Moz", "create Google Search Console account" |
+| **Download** | Wants to download software, template, or resource | "download Screaming Frog", "SEO checklist PDF download", "free keyword template" |
+| **Hire/Engage** | Ready to hire a professional or agency | "hire SEO consultant", "SEO agency near me", "freelance SEO expert" |
+
+#### Signal Words and Modifiers
+
+**Strong transactional signals:**
+- buy, purchase, order, subscribe
+- price, pricing, cost, discount, coupon, deal
+- free trial, demo, signup, sign up, register
+- download, install, get
+- hire, book, schedule, request quote
+- near me, in [location]
+- cheap, affordable, budget
+- premium, pro, enterprise
+- [product] discount code, [product] coupon
+
+#### SERP Feature Correlation
+
+| SERP Feature | Frequency for Transactional | Notes |
+|-------------|---------------------------|-------|
+| Shopping Results | Very High | Dominant for product purchase queries |
+| Ads (top + bottom) | Very High | Maximum ad coverage |
+| Local Pack | High | For service-based transactional queries |
+| Sitelinks | Medium | For brand-specific transactional |
+| Featured Snippet | Low | Rarely for pure transactional |
+| AI Overview | Low-Medium | Sometimes for pricing/comparison |
+
+#### Content Format Recommendations
+
+| Sub-category | Best Formats | Key Elements |
+|-------------|-------------|-------------|
+| Purchase | Product pages, pricing pages, checkout | Clear pricing, CTAs, trust signals, reviews |
+| Signup/Trial | Landing pages, signup forms, onboarding | Minimal friction, benefits, social proof |
+| Download | Resource landing pages, gated content | Preview, form, instant delivery |
+| Hire/Engage | Service pages, contact forms, portfolios | Credentials, case studies, clear next step |
+
+---
+
+## Intent Mapping to Conversion Funnel
+
+### Full Funnel Alignment
+
+```
+FUNNEL STAGE INTENT TYPE CONTENT GOAL
+─────────────────────────────────────────────────────────────
+Awareness → Informational Attract & educate
+ (Educational, Exploratory)
+
+Interest → Informational Deepen engagement
+ (Instructional)
+
+Consideration → Commercial Investigation Build preference
+ (Best-of, Comparison)
+
+Evaluation → Commercial Investigation Overcome objections
+ (Review, Evaluation)
+
+Decision → Transactional Convert
+ (Purchase, Signup, Hire)
+
+Retention → Navigational Support & retain
+ (Support/Docs, Login)
+
+Advocacy → Informational Enable sharing
+ (Educational — about you)
+```
+
+### Conversion Potential by Intent
+
+| Intent Type | Avg. Conversion Rate | Typical CTA | Nurture Length |
+|------------|---------------------|-------------|---------------|
+| Informational | 0.5-2% | Newsletter signup, content download | Long (weeks-months) |
+| Navigational | N/A (already engaged) | Login, access feature | N/A |
+| Commercial Investigation | 2-5% | Free trial, demo request, comparison download | Medium (days-weeks) |
+| Transactional | 5-15% | Buy now, subscribe, hire | Short (immediate-days) |
+
+---
+
+## Mixed Intent Queries
+
+Many real-world queries blend multiple intent types. Recognize and address the dominant + secondary intent.
+
+### Common Mixed Intent Patterns
+
+| Query Pattern | Primary Intent | Secondary Intent | Content Strategy |
+|--------------|---------------|-----------------|-----------------|
+| "best [product] for [use case]" | Commercial | Informational | Buying guide with educational context |
+| "how to [task] with [product]" | Instructional | Navigational | Tutorial featuring the product |
+| "[product] review and pricing" | Commercial | Transactional | Review with clear pricing CTAs |
+| "what is [concept] tools" | Informational | Commercial | Explainer that transitions to tool recommendations |
+| "[product] free download" | Transactional | Navigational | Landing page with download + product info |
+
+### Handling Mixed Intent in Content
+
+1. **Lead with the primary intent** -- answer the dominant question first
+2. **Bridge to the secondary intent** -- naturally transition to the secondary need
+3. **Match SERP format** -- if SERPs show mixed results, your content should too
+4. **Segment CTAs** -- provide different CTAs for different intent segments within the page
+
+---
+
+## SEO-Specific Keyword Intent Examples
+
+### SEO Industry Keyword Classification
+
+| Keyword | Intent | Sub-category | Recommended Content |
+|---------|--------|-------------|-------------------|
+| what is SEO | Informational | Educational | Definitive guide with visuals |
+| how to do keyword research | Informational | Instructional | Step-by-step tutorial |
+| best SEO tools 2026 | Commercial | Best-of Research | Ranked listicle with mini-reviews |
+| Ahrefs vs SEMrush | Commercial | Comparison | Side-by-side feature comparison |
+| buy Ahrefs subscription | Transactional | Purchase | Pricing/product page |
+| Google Search Console login | Navigational | Login/Access | Login page or redirect |
+| why is my site not indexing | Informational | Troubleshooting | Debug guide with solutions |
+| SEO agency for ecommerce | Transactional | Hire/Engage | Service page with portfolio |
+| is Moz worth it | Commercial | Review-seeking | Honest review with alternatives |
+| SEO checklist template | Transactional | Download | Gated resource landing page |
+| types of backlinks | Informational | Exploratory | Categorized explainer |
+| SEMrush pricing | Commercial | Evaluation | Pricing breakdown page |
+
+---
+
+## Applying Intent Taxonomy in Keyword Research
+
+### Step-by-Step Classification Process
+
+1. **Read the query literally** -- what is the user asking for?
+2. **Check for signal words** -- match against the signal word tables above
+3. **Verify against SERP** -- what does Google actually show? The SERP is the ground truth
+4. **Identify sub-category** -- narrow from primary intent to sub-category
+5. **Check for mixed intent** -- does the query blend two types?
+6. **Map to content format** -- select format based on intent + sub-category
+7. **Assign funnel stage** -- determine where this fits in the buyer journey
+8. **Set conversion expectation** -- align CTA and goals with intent type
+
+### Common Classification Mistakes
+
+| Mistake | Example | Why It's Wrong | Correct Classification |
+|---------|---------|---------------|----------------------|
+| Treating all "best" queries as informational | "best CRM software" | User is comparing products to buy | Commercial Investigation |
+| Treating all questions as informational | "how much does Ahrefs cost" | User is evaluating a purchase | Commercial / Transactional |
+| Ignoring local intent | "SEO services" | May have strong local intent in many contexts | Transactional (local) |
+| Missing navigational intent | "HubSpot blog" | User wants a specific page | Navigational |
+| Assuming single intent | "SEO tools" | Could be informational OR commercial | Mixed -- check SERP |
diff --git a/seo/keyword-research/references/keyword-prioritization-framework.md b/seo/keyword-research/references/keyword-prioritization-framework.md
new file mode 100644
index 00000000..e32b7dda
--- /dev/null
+++ b/seo/keyword-research/references/keyword-prioritization-framework.md
@@ -0,0 +1,41 @@
+# Keyword Prioritization Framework
+
+Systematic scoring methodology for ranking keywords by strategic value.
+
+## Relationship to Opportunity Score
+
+**Which score to use**: Use the Priority Score (below) for initial keyword triage and shortlisting. Use the Opportunity Score (Step 6 in the main workflow) for final content calendar prioritization, where the additional GEO and competitive factors provide more nuanced ranking.
+
+## Priority Scoring Matrix
+
+Score each keyword 1-5 on these factors, then calculate weighted total:
+
+| Factor | Weight | Score 1 (Low) | Score 5 (High) |
+|--------|--------|---------------|----------------|
+| Search Volume | 20% | <100/mo | >10,000/mo |
+| Keyword Difficulty | 25% | KD >80 (hard) | KD <20 (easy) |
+| Business Relevance | 30% | Tangential to offering | Core to offering |
+| Search Intent Match | 15% | Informational only | Transactional/commercial |
+| Trend Direction | 10% | Declining | Growing |
+
+**Priority Score** = Σ(Factor Weight × Score) / 5
+
+## Priority Categories
+
+| Priority | Score Range | Action |
+|----------|------------|--------|
+| P0 — Must Target | 4.0-5.0 | Create content immediately |
+| P1 — High Value | 3.0-3.9 | Queue for next content sprint |
+| P2 — Opportunity | 2.0-2.9 | Plan for future content calendar |
+| P3 — Monitor | 1.0-1.9 | Track but don't prioritize |
+
+## Seasonal Keyword Patterns
+
+### Seasonal Analysis Framework
+
+| Season Trigger | Example Keywords | Planning Lead Time | Content Strategy |
+|---------------|-----------------|-------------------|-----------------|
+| Calendar events | "Black Friday SEO", "New Year marketing plan" | 3-4 months ahead | Publish 6-8 weeks before peak |
+| Industry events | "[Conference] takeaways", "Google algorithm update" | 1-2 months / reactive | Pre-plan templates, react quickly |
+| Budget cycles | "marketing budget template Q1", "SEO ROI report" | 2-3 months ahead | Target planning season (Oct-Dec) |
+| Seasonal demand | "summer marketing ideas", "holiday email campaigns" | 2-3 months ahead | Refresh annually with new data |
diff --git a/seo/keyword-research/references/topic-cluster-templates.md b/seo/keyword-research/references/topic-cluster-templates.md
new file mode 100644
index 00000000..da6ec594
--- /dev/null
+++ b/seo/keyword-research/references/topic-cluster-templates.md
@@ -0,0 +1,286 @@
+# Topic Cluster Templates
+
+Planning worksheets, architecture patterns, and measurement frameworks for building topic clusters that establish topical authority and drive organic traffic.
+
+## Overview
+
+A topic cluster is a group of interlinked content pieces organized around a central pillar page. The pillar covers a broad topic comprehensively, while cluster pages dive deep into specific subtopics. Internal links bind the cluster together, signaling topical authority to search engines and AI systems.
+
+---
+
+## Topic Cluster Planning Worksheet
+
+### Step 1: Define the Pillar Topic
+
+Use this template to evaluate whether a topic deserves a full cluster:
+
+| Field | Your Input |
+|-------|-----------|
+| **Pillar Topic** | [Broad topic name] |
+| **Pillar Keyword** | [Head keyword, typically 1-3 words] |
+| **Monthly Search Volume** | [Volume] |
+| **Keyword Difficulty** | [KD score] |
+| **Business Relevance** | [1-5 scale: how core is this to your product/service?] |
+| **Current Ranking** | [Your current position, or "Not ranking"] |
+| **Competitor Coverage** | [How many competitors have pillar content on this?] |
+| **Estimated Cluster Size** | [How many subtopics can you identify?] |
+| **Content Assets Available** | [Existing content you can repurpose or link] |
+
+**Pillar viability checklist:**
+- [ ] At least 8-12 subtopics can be identified
+- [ ] Combined cluster keyword volume exceeds 5,000/month
+- [ ] Topic is directly relevant to your product or service
+- [ ] You can provide unique expertise or data on this topic
+- [ ] Competitors have not yet built a dominant cluster
+
+### Step 2: Map Cluster Subtopics
+
+| # | Subtopic | Target Keyword | Volume | KD | Intent | Content Format | Status |
+|---|---------|---------------|--------|-----|--------|---------------|--------|
+| 1 | [Subtopic name] | [Long-tail keyword] | [Vol] | [KD] | [I/N/C/T] | [Guide/Tutorial/List/etc.] | [Idea/Draft/Published] |
+| 2 | [Subtopic name] | [Long-tail keyword] | [Vol] | [KD] | [I/N/C/T] | [Guide/Tutorial/List/etc.] | [Idea/Draft/Published] |
+| 3 | [Subtopic name] | [Long-tail keyword] | [Vol] | [KD] | [I/N/C/T] | [Guide/Tutorial/List/etc.] | [Idea/Draft/Published] |
+| 4 | [Subtopic name] | [Long-tail keyword] | [Vol] | [KD] | [I/N/C/T] | [Guide/Tutorial/List/etc.] | [Idea/Draft/Published] |
+| 5 | [Subtopic name] | [Long-tail keyword] | [Vol] | [KD] | [I/N/C/T] | [Guide/Tutorial/List/etc.] | [Idea/Draft/Published] |
+| 6 | [Subtopic name] | [Long-tail keyword] | [Vol] | [KD] | [I/N/C/T] | [Guide/Tutorial/List/etc.] | [Idea/Draft/Published] |
+| 7 | [Subtopic name] | [Long-tail keyword] | [Vol] | [KD] | [I/N/C/T] | [Guide/Tutorial/List/etc.] | [Idea/Draft/Published] |
+| 8 | [Subtopic name] | [Long-tail keyword] | [Vol] | [KD] | [I/N/C/T] | [Guide/Tutorial/List/etc.] | [Idea/Draft/Published] |
+
+### Step 3: Define Internal Linking Map
+
+| Source Page | Links To | Anchor Text Strategy |
+|------------|---------|---------------------|
+| Pillar | Cluster 1, 2, 3... (all) | Descriptive, keyword-relevant anchors |
+| Cluster 1 | Pillar + Cluster 2, 3 | Natural contextual links |
+| Cluster 2 | Pillar + Cluster 1, 4 | Natural contextual links |
+| Cluster 3 | Pillar + Cluster 1 | Natural contextual links |
+
+**Linking rules:**
+- Every cluster page MUST link to the pillar page
+- The pillar page MUST link to every cluster page
+- Cluster pages SHOULD link to 2-3 related cluster pages where contextually relevant
+- Use descriptive anchor text (not "click here" or bare URLs)
+- Link placement should be within body content, not just in a footer list
+
+---
+
+## Hub-and-Spoke Architecture Patterns
+
+### Pattern 1: Classic Hub-Spoke (Best for Educational Topics)
+
+```
+ ┌──────────────────┐
+ ┌────│ What is [Topic]? │
+ │ └──────────────────┘
+ │ ┌──────────────────┐
+ ├────│ [Topic] Benefits │
+ │ └──────────────────┘
+┌───────────────┐ │ ┌──────────────────┐
+│ PILLAR: │───┼────│ [Topic] Examples │
+│ Complete │ │ └──────────────────┘
+│ Guide to │ │ ┌──────────────────┐
+│ [Topic] │ ├────│ [Topic] Tools │
+└───────────────┘ │ └──────────────────┘
+ │ ┌──────────────────┐
+ ├────│ [Topic] Mistakes │
+ │ └──────────────────┘
+ │ ┌──────────────────┐
+ └────│ [Topic] Checklist │
+ └──────────────────┘
+```
+
+**Best for:** Broad educational topics where subtopics don't overlap much.
+**Example:** "Content Marketing" pillar with spokes for strategy, types, examples, tools, metrics, mistakes.
+
+### Pattern 2: Layered Cluster (Best for Technical Topics)
+
+```
+ ┌─────────────────────────────┐
+ ┌────│ BEGINNER CLUSTER │
+ │ │ - Getting Started │
+ │ │ - Basic Concepts │
+ │ │ - First Steps Tutorial │
+ │ └─────────────────────────────┘
+┌──────────┐ │ ┌─────────────────────────────┐
+│ PILLAR: │───┼────│ INTERMEDIATE CLUSTER │
+│ Complete │ │ │ - Advanced Techniques │
+│ Guide │ │ │ - Common Patterns │
+└──────────┘ │ │ - Optimization Strategies │
+ │ └─────────────────────────────┘
+ │ ┌─────────────────────────────┐
+ └────│ ADVANCED CLUSTER │
+ │ - Expert Strategies │
+ │ - Edge Cases │
+ │ - Integration Guides │
+ └─────────────────────────────┘
+```
+
+**Best for:** Topics with clear skill progressions (programming, technical SEO, data analysis).
+**Example:** "Technical SEO" pillar with beginner (crawling basics), intermediate (JavaScript rendering), advanced (log file analysis) layers.
+
+### Pattern 3: Use-Case Cluster (Best for Product/Service Topics)
+
+```
+ ┌──────────────────────┐
+ ┌────│ [Topic] for SMBs │
+ │ └──────────────────────┘
+ │ ┌──────────────────────┐
+┌──────────┐ ├────│ [Topic] for Enterprise│
+│ PILLAR: │───┤ └──────────────────────┘
+│ [Topic] │ │ ┌──────────────────────┐
+│ Guide │ ├────│ [Topic] for Agencies │
+└──────────┘ │ └──────────────────────┘
+ │ ┌──────────────────────┐
+ ├────│ [Topic] for Ecommerce │
+ │ └──────────────────────┘
+ │ ┌──────────────────────┐
+ └────│ [Topic] for SaaS │
+ └──────────────────────┘
+```
+
+**Best for:** Products/services with distinct audience segments.
+**Example:** "SEO Strategy" pillar with spokes for different business types (ecommerce SEO, SaaS SEO, local SEO, B2B SEO).
+
+### Pattern 4: Process Cluster (Best for How-To Topics)
+
+```
+┌──────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
+│ PILLAR: │────→│ Step 1: │────→│ Step 2: │────→│ Step 3: │────→│ Step 4: │
+│ How to │ │ Research │ │ Plan │ │ Execute │ │ Measure │
+│ [Process]│ └─────────┘ └─────────┘ └─────────┘ └─────────┘
+└──────────┘ │ │ │ │
+ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
+ │Sub-guide │ │Template │ │Tutorial │ │Dashboard │
+ │ 1a │ │ 2a │ │ 3a │ │ Guide │
+ └─────────┘ └─────────┘ └─────────┘ └─────────┘
+```
+
+**Best for:** Multi-step processes where each step is complex enough for its own article.
+**Example:** "Link Building" pillar with sequential steps (prospecting, outreach, content creation, tracking).
+
+---
+
+## Internal Linking Patterns Within Clusters
+
+### Linking Density Guidelines
+
+| Cluster Size | Min Links Per Cluster Page | Max Links Per Cluster Page | Pillar Link Density |
+|-------------|--------------------------|--------------------------|-------------------|
+| 5-8 pages | 2-3 internal links | 5-6 internal links | Link to every cluster page |
+| 9-15 pages | 3-4 internal links | 6-8 internal links | Link to every cluster page |
+| 16+ pages | 4-5 internal links | 8-10 internal links | Link to top cluster pages, categorize rest |
+
+### Anchor Text Strategy
+
+| Link Type | Anchor Text Approach | Example |
+|-----------|---------------------|---------|
+| Cluster → Pillar | Broad keyword or branded | "our complete guide to keyword research" |
+| Pillar → Cluster | Specific keyword for that cluster page | "learn about long-tail keyword strategies" |
+| Cluster → Cluster | Contextual, conversational | "this connects to how you assess keyword difficulty" |
+
+### Linking Anti-Patterns to Avoid
+
+| Anti-Pattern | Why It's Bad | Fix |
+|-------------|-------------|-----|
+| Footer-only links to cluster pages | Low link equity, poor UX | Move links into body content |
+| Generic anchors ("click here", "read more") | No keyword signal | Use descriptive, keyword-relevant anchors |
+| Orphan cluster pages (no inbound links) | Search engines can't discover/value them | Add contextual links from pillar and related clusters |
+| Over-linking (20+ internal links per page) | Dilutes link equity, feels spammy | Keep to 5-10 relevant internal links |
+| Linking only to pillar (ignoring sibling clusters) | Misses cross-cluster relevance | Link to 2-3 related sibling pages |
+
+---
+
+## Content Calendar Integration
+
+### Cluster Build Sequence
+
+The order you publish cluster content matters. Follow this sequence for maximum impact:
+
+| Phase | What to Publish | Why This Order |
+|-------|----------------|---------------|
+| **Phase 1: Pillar** | Publish the pillar page first | Establishes the hub; cluster pages need something to link to |
+| **Phase 2: Quick-win clusters** | Publish 3-4 lowest-difficulty cluster pages | Build early traffic and indexing momentum |
+| **Phase 3: High-value clusters** | Publish highest-volume cluster pages | Leverage pillar authority for competitive terms |
+| **Phase 4: Long-tail clusters** | Publish remaining niche subtopics | Fill coverage gaps, capture long-tail traffic |
+| **Phase 5: Update cycle** | Refresh pillar with new links; update outdated clusters | Maintain freshness signals |
+
+### Sample Content Calendar for One Cluster
+
+| Week | Content Piece | Type | Target Keyword | Word Count | Dependencies |
+|------|--------------|------|---------------|-----------|-------------|
+| 1 | Complete Guide to [Pillar Topic] | Pillar | [Head keyword] | 3,500-5,000 | None |
+| 2 | What is [Subtopic A]? | Cluster | [Long-tail A] | 1,500-2,000 | Pillar published |
+| 3 | How to [Subtopic B] | Cluster | [Long-tail B] | 2,000-2,500 | Pillar published |
+| 4 | [Subtopic C] vs [Subtopic D] | Cluster | [Long-tail C] | 2,000-2,500 | Pillar published |
+| 5 | Best [Subtopic E] Tools | Cluster | [Long-tail E] | 2,500-3,000 | Pillar published |
+| 6 | [Subtopic F] for Beginners | Cluster | [Long-tail F] | 1,500-2,000 | Pillar published |
+| 7 | [Subtopic G] Checklist | Cluster | [Long-tail G] | 1,000-1,500 | Pillar published |
+| 8 | Update Pillar + add all internal links | Update | -- | -- | All clusters published |
+
+### Publishing Cadence Recommendations
+
+| Team Size | Cluster Build Time | Recommended Cadence |
+|-----------|-------------------|-------------------|
+| Solo content creator | 6-8 weeks per cluster | 1 cluster per quarter |
+| Small team (2-3 writers) | 3-4 weeks per cluster | 1 cluster per month |
+| Content team (4-6 writers) | 2-3 weeks per cluster | 2 clusters per month |
+| Large team (7+ writers) | 1-2 weeks per cluster | 1 cluster per week |
+
+---
+
+## Cluster Performance Measurement Framework
+
+### Key Metrics by Level
+
+#### Cluster-Level Metrics
+
+| Metric | What It Measures | Target | How to Track |
+|--------|-----------------|--------|-------------|
+| Total cluster traffic | Aggregate organic visits to all pages in cluster | Growing month-over-month | Analytics: filter by URL folder/tag |
+| Keyword coverage | Number of keywords cluster ranks for | 50+ keywords per mature cluster | SEO tool: filter by cluster URLs |
+| Average position | Mean ranking across all cluster keywords | Improving trend toward top 10 | SEO tool: average position report |
+| Internal link equity | PageRank flow within cluster | Pillar has highest internal links | Site audit tool: internal link report |
+| Cluster completeness | Percentage of planned subtopics published | 100% within planned timeframe | Content calendar tracking |
+
+#### Page-Level Metrics (Per Cluster Page)
+
+| Metric | Pillar Target | Cluster Page Target |
+|--------|-------------|-------------------|
+| Organic traffic | Highest in cluster | Proportional to keyword volume |
+| Keywords ranking | 50-200+ | 10-50 |
+| Backlinks | Attracts most links | Some organic links |
+| Avg. time on page | 4-8 minutes | 2-5 minutes |
+| Bounce rate | <60% | <70% |
+| Internal CTR | High clicks to cluster pages | Clicks to pillar + sibling pages |
+
+### Performance Review Cadence
+
+| Timeframe | What to Review | Action If Underperforming |
+|-----------|---------------|--------------------------|
+| 2 weeks post-publish | Indexing status, initial impressions | Fix indexing issues, check for crawl errors |
+| 1 month post-publish | Early ranking signals, traffic | Optimize titles/metas, add internal links |
+| 3 months post-publish | Ranking positions, traffic trends | Content refresh, add missing subtopics, build links |
+| 6 months post-publish | Full performance assessment | Major content update or strategic pivot |
+| Quarterly (ongoing) | Cluster-level aggregate trends | Identify declining pages, plan refreshes |
+
+### Cluster Health Scorecard
+
+Rate each cluster quarterly on these dimensions:
+
+| Dimension | Score 1 (Poor) | Score 3 (Average) | Score 5 (Excellent) |
+|-----------|---------------|-------------------|-------------------|
+| Traffic growth | Declining | Flat | Growing 10%+ MoM |
+| Keyword coverage | <20 keywords | 20-50 keywords | 50+ keywords |
+| Top 10 rankings | 0 keywords in top 10 | 1-5 in top 10 | 5+ in top 10 |
+| Content freshness | Not updated in 12+ months | Updated within 6 months | Updated within 3 months |
+| Internal linking | Missing links, orphan pages | Basic linking in place | Full cross-linking with relevant anchors |
+| Completeness | <50% of subtopics covered | 50-80% covered | 80-100% covered |
+
+**Cluster Health Score** = Average of all dimension scores
+
+| Score Range | Health Status | Action |
+|------------|--------------|--------|
+| 4.0-5.0 | Healthy | Maintain cadence, expand to adjacent clusters |
+| 3.0-3.9 | Needs attention | Refresh outdated content, fill subtopic gaps |
+| 2.0-2.9 | At risk | Major content update, link building campaign |
+| 1.0-1.9 | Failing | Strategic review -- consider merging, rewriting, or retiring |
diff --git a/seo/meta-tags-optimizer/SKILL.md b/seo/meta-tags-optimizer/SKILL.md
new file mode 100644
index 00000000..c4ae951c
--- /dev/null
+++ b/seo/meta-tags-optimizer/SKILL.md
@@ -0,0 +1,326 @@
+---
+name: meta-tags-optimizer
+description: >
+ Optimize title tags, meta descriptions, Open Graph, and Twitter cards for
+ maximum click-through rate. Generates multiple A/B test variations with
+ character counting and SERP preview. Use when asked to "optimize title tag",
+ "write meta description", "improve CTR", "Open Graph tags", "fix my meta
+ tags", "social media preview", "my click rate is low", "title optimization",
+ or any meta tag task.
+---
+
+## Preamble (run first)
+
+```bash
+_UPD=$(~/.claude/skills/toprank/bin/toprank-update-check 2>/dev/null || \
+ ~/.claude/skills/stockholm/bin/toprank-update-check 2>/dev/null || true)
+[ -n "$_UPD" ] && echo "$_UPD" || true
+```
+
+If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/toprank-upgrade` skill (Step 1 onward) to auto-upgrade, then return here and continue.
+
+If the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded from v{old} to v{new}" briefly, then continue.
+
+---
+
+# Meta Tags Optimizer
+
+This skill creates compelling, optimized meta tags that improve click-through rates from search results and enhance social media sharing. It covers title tags, meta descriptions, and social meta tags.
+
+## When This Must Trigger
+
+Use this when the conversation involves any of these situations — even if the user does not use SEO terminology:
+
+Use this whenever the task needs a shippable asset or transformation that should feed directly into quality review, deployment, or monitoring.
+
+- Creating meta tags for new pages
+- Optimizing existing meta tags for better CTR
+- Preparing pages for social media sharing
+- Fixing duplicate or missing meta tags
+- A/B testing title and description variations
+- Optimizing for specific SERP features
+- Creating meta tags for different page types
+
+## What This Skill Does
+
+1. **Title Tag Creation**: Writes compelling, keyword-optimized titles
+2. **Meta Description Writing**: Creates click-worthy descriptions
+3. **Open Graph Optimization**: Prepares pages for social sharing
+4. **Twitter Card Setup**: Optimizes Twitter-specific meta tags
+5. **CTR Analysis**: Suggests improvements for better click rates
+6. **Character Counting**: Ensures proper length for SERP display
+7. **A/B Test Suggestions**: Provides variations for testing
+
+## Quick Start
+
+Start with one of these prompts.
+
+### Create Meta Tags
+
+```
+Create meta tags for a page about [topic] targeting [keyword]
+```
+
+```
+Write title and meta description for this content: [content/URL]
+```
+
+### Optimize Existing Tags
+
+```
+Improve these meta tags for better CTR: [current tags]
+```
+
+### Social Media Tags
+
+```
+Create Open Graph and Twitter card tags for [page/URL]
+```
+
+## Data Sources
+
+**With ~~search console + ~~SEO tool connected:**
+Automatically pull current meta tags, CTR data by query, competitor title/description patterns, SERP preview data, and impression/click metrics to identify optimization opportunities.
+
+**With manual data only:**
+Ask the user to provide:
+1. Current title and meta description (if optimizing existing)
+2. Target primary keyword and 2-3 secondary keywords
+3. Page URL and main content/value proposition
+4. Competitor URLs or examples of well-performing titles in the SERP
+
+Proceed with the full workflow using provided data. Note in the output which metrics are from automated collection vs. user-provided data.
+
+## Instructions
+
+When a user requests meta tag optimization:
+
+1. **Gather Page Information**
+
+ ```markdown
+ ### Page Analysis
+
+ **Page URL**: [URL]
+ **Page Type**: [blog/product/landing/service/homepage]
+ **Primary Keyword**: [keyword]
+ **Secondary Keywords**: [keywords]
+ **Target Audience**: [audience]
+ **Primary CTA**: [action you want users to take]
+ **Unique Value Prop**: [what makes this page special]
+ ```
+
+2. **Create Optimized Title Tag**
+
+ ```markdown
+ ### Title Tag Optimization
+
+ **Requirements**:
+ - Length: 50-60 characters (displays fully in SERP)
+ - Include primary keyword (preferably near front)
+ - Make it compelling and click-worthy
+ - Match search intent
+ - Include brand name if appropriate
+
+ **Title Tag Formula Options**:
+
+ 1. **Keyword | Benefit | Brand**
+ "[Primary Keyword]: [Benefit] | [Brand Name]"
+
+ 2. **Number + Keyword + Promise**
+ "[Number] [Keyword] That [Promise/Result]"
+
+ 3. **How-to Format**
+ "How to [Keyword]: [Benefit/Result]"
+
+ 4. **Question Format**
+ "What is [Keyword]? [Brief Answer/Hook]"
+
+ 5. **Year + Keyword**
+ "[Keyword] in [Year]: [Hook/Update]"
+
+ **Generated Title Options**:
+
+ | Option | Title | Length | Power Words | Keyword Position |
+ |--------|-------|--------|-------------|------------------|
+ | 1 | [Title] | [X] chars | [words] | [Front/Middle] |
+ | 2 | [Title] | [X] chars | [words] | [Front/Middle] |
+ | 3 | [Title] | [X] chars | [words] | [Front/Middle] |
+
+ **Recommended**: Option [X]
+ **Reasoning**: [Why this option is best]
+
+ **Title Tag Code**:
+ ```html
+ <title>[Selected Title]</title>
+ ```
+ ```
+
+3. **Write Meta Description**
+
+ ```markdown
+ ### Meta Description Optimization
+
+ **Requirements**:
+ - Length: 150-160 characters (displays fully in SERP)
+ - Include primary keyword naturally
+ - Include clear call-to-action
+ - Match page content accurately
+ - Create urgency or curiosity
+ - Avoid duplicate descriptions
+
+ **Meta Description Formula**:
+
+ [What the page offers] + [Benefit to user] + [Call-to-action]
+
+ **Power Elements to Include**:
+ - Numbers and statistics
+ - Current year
+ - Emotional triggers
+ - Action verbs
+ - Unique value proposition
+
+ **Generated Description Options**:
+
+ | Option | Description | Length | CTA | Emotional Trigger |
+ |--------|-------------|--------|-----|-------------------|
+ | 1 | [Description] | [X] chars | [CTA] | [Trigger] |
+ | 2 | [Description] | [X] chars | [CTA] | [Trigger] |
+ | 3 | [Description] | [X] chars | [CTA] | [Trigger] |
+
+ **Recommended**: Option [X]
+ **Reasoning**: [Why this option is best]
+
+ **Meta Description Code**:
+ ```html
+ <meta name="description" content="[Selected Description]">
+ ```
+ ```
+
+4. **Create Open Graph, Twitter Card, and Additional Meta Tags**
+
+ Generate OG tags (og:type, og:url, og:title, og:description, og:image), Twitter Card tags, canonical URL, robots, viewport, author, and article-specific tags. Then combine into a complete meta tag block.
+
+ > **Reference**: See [references/meta-tag-code-templates.md](references/meta-tag-code-templates.md) for OG type selection guide, Twitter card type selection, all HTML code templates, and the complete meta tag block template.
+
+5. **CORE-EEAT Alignment Check**
+
+ Verify meta tags align with content quality standards (CORE-EEAT Benchmark).
+
+ ```markdown
+ ### CORE-EEAT Meta Tag Alignment
+
+ | Check | Status | Notes |
+ |-------|--------|-------|
+ | **C01 Intent Alignment**: Title promise matches actual content delivery | ✅/⚠️/❌ | [Does the title accurately represent what the page delivers?] |
+ | **C02 Direct Answer**: Meta description reflects the core answer available in first 150 words | ✅/⚠️/❌ | [Does the description preview the direct answer?] |
+
+ **If C01 fails**: Title is misleading — rewrite to match actual content.
+ **If C02 fails**: Content may need restructuring to front-load the answer, or description should better reflect available content.
+ ```
+
+9. **Provide CTR Optimization Tips**
+
+ ```markdown
+ ## CTR Optimization Analysis
+
+ ### Power Words Used
+ - [Word 1] - Creates [emotion/action]
+ - [Word 2] - Creates [emotion/action]
+
+ ### CTR Boosting Elements
+
+ | Element | Present | Impact |
+ |---------|---------|--------|
+ | Numbers | Yes/No | +20-30% CTR |
+ | Current Year | Yes/No | +15-20% CTR |
+ | Power Words | Yes/No | +10-15% CTR |
+ | Question | Yes/No | +10-15% CTR |
+ | Brackets | Yes/No | +10% CTR |
+
+ ### A/B Test Suggestions
+
+ Test these variations:
+
+ **Version A** (Current):
+ - Title: [Title]
+ - Description: [Description]
+
+ **Version B** (Test):
+ - Title: [Alternative title]
+ - Description: [Alternative description]
+ - Hypothesis: [Why this might perform better]
+ ```
+
+## Validation Checkpoints
+
+### Input Validation
+- [ ] Primary keyword confirmed and matches page content
+- [ ] Page type identified (blog/product/landing/service/homepage)
+- [ ] Target audience and search intent clearly defined
+- [ ] Unique value proposition articulated
+
+### Output Validation
+- [ ] Title length 50-60 characters (displays fully in SERP)
+- [ ] Meta description length 150-160 characters
+- [ ] Primary keyword appears in both title and description
+- [ ] Open Graph image specified (1200x630px recommended)
+- [ ] All HTML syntax valid (no unclosed quotes or tags)
+- [ ] Source of each data point clearly stated (~~search console CTR data, ~~SEO tool competitor data, user-provided, or estimated)
+
+## Example
+
+**User**: "Create meta tags for a blog post about 'how to start a podcast in [current year]'"
+
+**Output**:
+
+```markdown
+## Meta Tags: How to Start a Podcast ([current year])
+
+### Title Tag
+```html
+<title>How to Start a Podcast in [current year]: Complete Beginner's Guide</title>
+```
+**Length**: ~55 characters ✅
+**Keyword**: "how to start a podcast" at front ✅
+**Power Words**: "Complete", "Beginner's" ✅
+
+### Meta Description
+```html
+<meta name="description" content="Learn how to start a podcast in [current year] with our step-by-step guide. Covers equipment, hosting, recording, and launching your first episode. Start podcasting today!">
+```
+**Length**: ~163 characters ✅
+**Keyword**: Included naturally ✅
+**CTA**: "Start podcasting today!" ✅
+
+_Complete meta tag block (with OG, Twitter, Article tags) generated using template from [references/meta-tag-code-templates.md](references/meta-tag-code-templates.md)._
+
+### A/B Test Variations
+
+**Title Variation B**:
+"Start a Podcast in [current year]: Step-by-Step Guide (+ Free Checklist)"
+
+**Title Variation C**:
+"How to Start a Podcast: [current year] Guide [Equipment + Software + Tips]"
+
+**Description Variation B**:
+"Want to start a podcast in [current year]? This guide covers everything: equipment ($100 budget option), best hosting platforms, recording tips, and how to get your first 1,000 listeners."
+```
+
+## Tips for Success
+
+1. **Front-load keywords** - Put important terms at the beginning
+2. **Match intent** - Description should preview what page delivers
+3. **Be specific** - Vague descriptions get ignored
+4. **Test variations** - Small changes can significantly impact CTR
+5. **Update regularly** - Add current year, refresh messaging
+6. **Check competitors** - See what's working in your SERP
+
+
+## Reference Materials
+
+- [Meta Tag Formulas](references/meta-tag-formulas.md) — Proven title and description formulas
+- [CTR and Social Reference](references/ctr-and-social-reference.md) — Page-type templates, CTR data, OG best practices
+
+## Next Best Skill
+
+- **Primary**: [schema-markup-generator](../schema-markup-generator/SKILL.md) — complete the SERP packaging with structured data.
diff --git a/seo/meta-tags-optimizer/references/ctr-and-social-reference.md b/seo/meta-tags-optimizer/references/ctr-and-social-reference.md
new file mode 100644
index 00000000..8fc5205c
--- /dev/null
+++ b/seo/meta-tags-optimizer/references/ctr-and-social-reference.md
@@ -0,0 +1,149 @@
+# CTR Optimization, Social Tags, and Page-Type Templates
+
+Reference tables for click-through rate optimization, Open Graph best practices, meta description copywriting frameworks, and page-type meta tag templates.
+
+---
+
+## Page-Type Meta Tag Templates
+
+### Homepage
+
+```html
+<title>[Brand Name] - [Primary Value Proposition]</title>
+<meta name="description" content="[Brand] helps [audience] [achieve goal]. [Key feature/benefit]. [CTA]">
+```
+
+### Product Page
+
+```html
+<title>[Product Name] - [Key Benefit] | [Brand]</title>
+<meta name="description" content="[Product] [key features]. [Price/offer if applicable]. [Social proof]. [CTA]">
+```
+
+### Blog Post
+
+```html
+<title>[How to/What is/Number] [Keyword] [Benefit/Year]</title>
+<meta name="description" content="[What they'll learn]. [Key points covered]. [CTA]">
+```
+
+### Service Page
+
+```html
+<title>[Service] in [Location] - [Brand] | [Differentiator]</title>
+<meta name="description" content="[Service description]. [Experience/credentials]. [Key benefit]. [CTA]">
+```
+
+---
+
+## Title Tag Formula Patterns
+
+### Proven Title Formulas
+
+| Formula | Template | Example | Best For |
+|---------|----------|---------|---------|
+| How-To | How to [Achieve Result] ([Year]) | How to Improve SEO Rankings (2026) | Informational guides |
+| Number List | [Number] [Adjective] [Topic] for [Audience] | 15 Proven SEO Strategies for E-commerce | Listicles |
+| Question | [Question]? Here's [Answer Preview] | What Is Technical SEO? Complete Guide | Definition content |
+| Comparison | [Option A] vs [Option B]: [Differentiator] | Ahrefs vs SEMrush: Which SEO Tool Wins? | Comparison pages |
+| Year-Based | Best [Topic] in [Year] ([Tested/Ranked]) | Best SEO Tools in 2026 (Expert Tested) | Evergreen + fresh |
+| Benefit-Driven | [Benefit]: [How to Achieve It] | Rank #1 on Google: 10-Step SEO Checklist | High-CTR pages |
+| Parenthetical | [Topic] ([Modifier]) | Link Building Guide (With Templates) | Adding value signal |
+| Negative | [Number] [Topic] Mistakes [Consequence] | 7 SEO Mistakes That Kill Your Rankings | Problem-awareness content |
+
+### Title Tag Power Words
+
+| Category | Power Words | Use Sparingly |
+|----------|-----------|---------------|
+| Urgency | Now, Today, Quick, Fast, Instant, 2026 | Don't overuse; pair with substance |
+| Value | Free, Proven, Complete, Essential, Ultimate | Avoid hyperbole without backing |
+| Specificity | [Exact number], Step-by-Step, Checklist, Template | More specific = more clicks |
+| Curiosity | Secret, Little-Known, Surprising, Actually | Must deliver on the promise |
+| Authority | Expert, Research-Backed, Data-Driven, Tested | Only use when genuinely expert content |
+| Emotional | Best, Worst, Mistakes, Warning, Powerful | Balance emotion with credibility |
+
+### Title Tag Length Optimization
+
+| Length Range | SERP Behavior | Recommendation |
+|-------------|--------------|----------------|
+| <30 characters | May appear thin | Expand with modifier or brand |
+| 30-50 characters | Fully displayed on all devices | Ideal for mobile-first |
+| 50-60 characters | Full display on desktop, may truncate mobile | Sweet spot for desktop |
+| 60-65 characters | Truncated on some devices | Front-load keywords |
+| >65 characters | Truncated everywhere | Avoid — key info gets cut |
+
+---
+
+## Meta Description Copywriting Frameworks
+
+### AIDA Framework
+
+| Element | What It Does | Example |
+|---------|-------------|---------|
+| **A**ttention | Hook with a bold claim or question | "Want to double your organic traffic?" |
+| **I**nterest | Build relevance | "This guide covers 15 proven strategies..." |
+| **D**esire | Show benefit | "...used by top-ranking sites to increase traffic by 200%." |
+| **A**ction | CTA | "Read the full guide now." |
+
+**Full Example**: "Want to double your organic traffic? This guide covers 15 proven SEO strategies used by top-ranking sites to increase traffic by 200%. Read the full guide now." (158 chars)
+
+### PAS Framework
+
+| Element | What It Does | Example |
+|---------|-------------|---------|
+| **P**roblem | Identify pain point | "Struggling to rank on Google?" |
+| **A**gitate | Amplify the problem | "Most SEO guides are outdated and miss key ranking factors." |
+| **S**olution | Offer the solution | "Our 2026 guide covers what actually works. Read now." |
+
+### Benefit-Proof-CTA Framework
+
+| Element | Example |
+|---------|---------|
+| Benefit | "Learn the exact SEO process that grew our traffic 5x" |
+| Proof | "— with real data from 200+ audits." |
+| CTA | "Get the free checklist." |
+
+---
+
+## CTR Optimization Data
+
+### Factors That Increase Organic CTR
+
+| Factor | CTR Impact | Implementation |
+|--------|-----------|----------------|
+| Number in title | +20-30% | "7 Ways", "15 Tips", "2026" |
+| Question in title | +14% | Start with How, What, Why |
+| Emotional words | +7% | "Proven", "Essential", "Mistake" |
+| Brackets/parentheses | +38% | "[Guide]", "(With Examples)" |
+| Current year | +10-15% | "Best SEO Tools 2026" |
+| Power words | +12% | See Power Words table above |
+| Match search intent | +15-25% | Align title with SERP expectations |
+| Rich results (schema) | +30% | FAQ, HowTo, Review stars |
+
+---
+
+## Open Graph Best Practices by Platform
+
+### Platform-Specific OG Optimization
+
+| Platform | Image Size | Title Length | Description Length | Special Tags |
+|----------|-----------|-------------|-------------------|-------------|
+| Facebook | 1200x630px | 40-60 chars | 125-155 chars | og:type, og:locale |
+| Twitter/X | 1200x600px | 70 chars max | 200 chars | twitter:card, twitter:site |
+| LinkedIn | 1200x627px | 70 chars | 150 chars | Standard OG tags |
+| Pinterest | 1000x1500px (2:3) | 100 chars | 500 chars | og:type=article preferred |
+| Slack | 500x500px min | Full title | First ~300 chars | Standard OG tags |
+
+### OG Tag Checklist
+
+| Tag | Required? | Notes |
+|-----|----------|-------|
+| og:title | Yes | Can differ from HTML title; optimize for social sharing |
+| og:description | Yes | Social-optimized; can differ from meta description |
+| og:image | Yes | Must be absolute URL; minimum 200x200px, ideal 1200x630px |
+| og:url | Yes | Canonical URL |
+| og:type | Yes | "website" for homepage, "article" for blog posts |
+| og:site_name | Recommended | Your brand name |
+| og:locale | Recommended | e.g., "en_US" |
+| twitter:card | Recommended | "summary_large_image" for articles |
+| twitter:site | Recommended | @yourbrand |
diff --git a/seo/meta-tags-optimizer/references/meta-tag-code-templates.md b/seo/meta-tags-optimizer/references/meta-tag-code-templates.md
new file mode 100644
index 00000000..88d5b628
--- /dev/null
+++ b/seo/meta-tags-optimizer/references/meta-tag-code-templates.md
@@ -0,0 +1,153 @@
+# Meta Tag Code Templates
+
+HTML code templates for Open Graph tags, Twitter cards, additional meta tags, and complete meta tag blocks.
+
+---
+
+## Open Graph Tags (Facebook, LinkedIn, etc.)
+
+**Required OG Tags**:
+
+```html
+<!-- Primary Open Graph Tags -->
+<meta property="og:type" content="[article/website/product]">
+<meta property="og:url" content="[Full canonical URL]">
+<meta property="og:title" content="[OG-optimized title - up to 60 chars]">
+<meta property="og:description" content="[OG description - up to 200 chars]">
+<meta property="og:image" content="[Image URL - 1200x630px recommended]">
+
+<!-- Optional but Recommended -->
+<meta property="og:site_name" content="[Website Name]">
+<meta property="og:locale" content="en_US">
+```
+
+**OG Type Selection Guide**:
+
+| Page Type | og:type |
+|-----------|---------|
+| Blog post | article |
+| Homepage | website |
+| Product | product |
+| Video | video.other |
+| Profile | profile |
+
+**OG Title Considerations**:
+- Can be different from title tag
+- Optimize for social sharing context
+- More conversational tone acceptable
+- Up to 60 characters ideal
+
+**OG Description Considerations**:
+- Can be longer than meta description (up to 200 chars)
+- Focus on shareability
+- What would make someone click when shared?
+
+**OG Image Requirements**:
+- Recommended size: 1200x630 pixels
+- Minimum size: 600x315 pixels
+- Format: JPG or PNG
+- Keep text to less than 20% of image
+- Include branding subtly
+
+---
+
+## Twitter Card Tags
+
+**Card Type Selection**:
+
+| Card Type | Best For | Image Size |
+|-----------|----------|------------|
+| summary | Articles, blogs | 144x144 min |
+| summary_large_image | Visual content | 300x157 min |
+| player | Video/audio | 640x360 min |
+| app | Mobile apps | 800x418 |
+
+**Twitter Card Code**:
+
+```html
+<!-- Twitter Card Tags -->
+<meta name="twitter:card" content="[summary_large_image/summary]">
+<meta name="twitter:site" content="@[YourTwitterHandle]">
+<meta name="twitter:creator" content="@[AuthorTwitterHandle]">
+<meta name="twitter:title" content="[Title - 70 chars max]">
+<meta name="twitter:description" content="[Description - 200 chars max]">
+<meta name="twitter:image" content="[Image URL]">
+<meta name="twitter:image:alt" content="[Image description for accessibility]">
+```
+
+**Twitter-Specific Considerations**:
+- Shorter titles work better (under 70 chars)
+- Include @mentions if relevant
+- Hashtag-relevant terms can help discovery
+- Test with Twitter Card Validator
+
+---
+
+## Additional Recommended Meta Tags
+
+**Canonical URL** (Prevent duplicates):
+```html
+<link rel="canonical" href="[Preferred URL]">
+```
+
+**Robots Tag** (Indexing control):
+```html
+<meta name="robots" content="index, follow">
+```
+
+**Viewport** (Mobile optimization):
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1">
+```
+
+**Author** (For articles):
+```html
+<meta name="author" content="[Author Name]">
+```
+
+**Language**:
+```html
+<html lang="en">
+```
+
+**Article-Specific** (For blog posts):
+```html
+<meta property="article:published_time" content="[ISO 8601 date]">
+<meta property="article:modified_time" content="[ISO 8601 date]">
+<meta property="article:author" content="[Author URL]">
+<meta property="article:section" content="[Category]">
+<meta property="article:tag" content="[Tag 1]">
+```
+
+---
+
+## Complete Meta Tag Block Template
+
+Copy and paste this complete meta tag block:
+
+```html
+<!-- Primary Meta Tags -->
+<title>[Optimized Title]</title>
+<meta name="title" content="[Optimized Title]">
+<meta name="description" content="[Optimized Description]">
+<link rel="canonical" href="[Canonical URL]">
+
+<!-- Open Graph / Facebook -->
+<meta property="og:type" content="[type]">
+<meta property="og:url" content="[URL]">
+<meta property="og:title" content="[OG Title]">
+<meta property="og:description" content="[OG Description]">
+<meta property="og:image" content="[Image URL]">
+<meta property="og:site_name" content="[Site Name]">
+
+<!-- Twitter -->
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:url" content="[URL]">
+<meta name="twitter:title" content="[Twitter Title]">
+<meta name="twitter:description" content="[Twitter Description]">
+<meta name="twitter:image" content="[Image URL]">
+
+<!-- Additional -->
+<meta name="robots" content="index, follow">
+<meta name="author" content="[Author]">
+```
diff --git a/seo/meta-tags-optimizer/references/meta-tag-formulas.md b/seo/meta-tags-optimizer/references/meta-tag-formulas.md
new file mode 100644
index 00000000..dd1399f2
--- /dev/null
+++ b/seo/meta-tags-optimizer/references/meta-tag-formulas.md
@@ -0,0 +1,355 @@
+# Meta Tag Formulas Reference
+
+Extended title tag formulas, meta description templates, A/B testing methodology, seasonal patterns, CTR benchmarks, and multi-language optimization guidance.
+
+---
+
+## Title Tag Formulas by Content Type
+
+### Informational Content
+
+| # | Formula | Template | Example |
+|---|---------|----------|---------|
+| 1 | How-To + Year | How to [Action] in [Year] | How to Build Backlinks in 2026 |
+| 2 | How-To + Result | How to [Action] ([Result]) | How to Write Meta Tags (Rank Higher) |
+| 3 | Definitive Guide | The Definitive Guide to [Topic] | The Definitive Guide to Technical SEO |
+| 4 | Complete Guide | [Topic]: The Complete Guide ([Year]) | Schema Markup: The Complete Guide (2026) |
+| 5 | Beginner's Guide | [Topic] for Beginners: [Promise] | SEO for Beginners: Rank in 30 Days |
+| 6 | What Is | What Is [Topic]? [Short Clarifier] | What Is E-E-A-T? Google's Quality Standard |
+| 7 | Everything You Need | Everything You Need to Know About [Topic] | Everything You Need to Know About Core Web Vitals |
+| 8 | Step-by-Step | [Topic]: A Step-by-Step Guide | Link Building: A Step-by-Step Guide |
+
+### Listicle Content
+
+| # | Formula | Template | Example |
+|---|---------|----------|---------|
+| 9 | Numbered Tips | [N] [Topic] Tips That [Result] | 12 On-Page SEO Tips That Boost Rankings |
+| 10 | Best Of | [N] Best [Items] in [Year] ([Qualifier]) | 9 Best SEO Tools in 2026 (Expert Tested) |
+| 11 | Ways To | [N] Ways to [Achieve Goal] [Timeframe] | 7 Ways to Increase Organic Traffic This Month |
+| 12 | Strategies | [N] [Adjective] [Topic] Strategies for [Audience] | 15 Proven Content Strategies for SaaS |
+| 13 | Examples | [N] [Topic] Examples [Value Add] | 20 Meta Description Examples (+ Templates) |
+| 14 | Mistakes | [N] [Topic] Mistakes [Negative Consequence] | 10 Title Tag Mistakes That Hurt Your CTR |
+| 15 | Secrets | [N] [Topic] Secrets [Experts/Pros] Use | 5 SEO Secrets Top Agencies Use |
+| 16 | Reasons | [N] Reasons [Why/To] [Statement] | 8 Reasons Your Site Isn't Ranking |
+
+### Comparison Content
+
+| # | Formula | Template | Example |
+|---|---------|----------|---------|
+| 17 | A vs B | [A] vs [B]: [Differentiator] | Ahrefs vs SEMrush: Which Tool Is Better? |
+| 18 | A vs B + Year | [A] vs [B] ([Year]): [Angle] | WordPress vs Webflow (2026): Honest Comparison |
+| 19 | A vs B + Winner | [A] vs [B]: Which [Category] Wins? | Yoast vs Rank Math: Which SEO Plugin Wins? |
+| 20 | Alternatives | [N] Best [Product] Alternatives in [Year] | 7 Best Ahrefs Alternatives in 2026 |
+
+### Commercial / Transactional Content
+
+| # | Formula | Template | Example |
+|---|---------|----------|---------|
+| 21 | Product + Benefit | [Product] - [Primary Benefit] \| [Brand] | SEO Audit Tool - Find Issues in Minutes \| SiteChecker |
+| 22 | Pricing | [Product] Pricing: [Value Statement] | Semrush Pricing: Plans from $119/mo (2026) |
+| 23 | Review | [Product] Review ([Year]): [Verdict] | Surfer SEO Review (2026): Worth the Price? |
+| 24 | Free Tool | Free [Tool Type]: [What It Does] | Free Meta Tag Generator: Preview Your SERP Listing |
+
+### Local SEO Content
+
+| # | Formula | Template | Example |
+|---|---------|----------|---------|
+| 25 | Service + Location | [Service] in [City] - [Brand] \| [Differentiator] | Plumber in Austin - FastFix \| Same-Day Service |
+| 26 | Best + Location | Best [Service] in [City] ([Year]) | Best Coffee Shops in Portland (2026) |
+| 27 | Near Me Style | [Service] Near [Location]: [Value] | SEO Agency Near Chicago: Free Site Audit |
+| 28 | Location Guide | [Topic] in [Location]: [Qualifier] Guide | Restaurants in Brooklyn: The Local's Guide |
+
+### Problem-Awareness Content
+
+| # | Formula | Template | Example |
+|---|---------|----------|---------|
+| 29 | Warning | Warning: [Problem] [Consequence] | Warning: These SEO Tactics Will Get You Penalized |
+| 30 | Why + Problem | Why [Problem Exists] (And How to Fix It) | Why Your Meta Descriptions Are Ignored (And How to Fix It) |
+| 31 | Stop Doing | Stop [Bad Practice]: [Better Alternative] | Stop Keyword Stuffing: What to Do Instead |
+| 32 | Truth About | The Truth About [Topic] [Revelation] | The Truth About SEO in 2026: What Changed |
+
+---
+
+## Meta Description Templates
+
+### By Content Type
+
+#### Blog Posts / Articles
+
+| # | Template | Character Count |
+|---|----------|-----------------|
+| 1 | Learn [topic] with our [qualifier] guide. Covers [point 1], [point 2], and [point 3]. [CTA]. | ~140-155 |
+| 2 | [Question]? This [year] guide explains [what], [why], and [how]. Get actionable tips now. | ~130-150 |
+| 3 | Discover [N] [adjective] [topic] strategies that [result]. Backed by [proof element]. Read the full guide. | ~145-160 |
+| 4 | [Bold claim about topic]. We tested [N] [methods/tools] and found what works. See the results. | ~130-150 |
+
+#### Product / Service Pages
+
+| # | Template | Character Count |
+|---|----------|-----------------|
+| 5 | [Product] helps you [benefit]. [Feature 1], [Feature 2], [Feature 3]. [Price/offer]. [CTA]. | ~140-155 |
+| 6 | Looking for [solution]? [Product] [key differentiator]. Trusted by [social proof]. [CTA]. | ~130-150 |
+| 7 | [Product] - [primary benefit] in [timeframe]. [Star rating] from [N]+ reviews. [CTA]. | ~130-145 |
+
+#### E-commerce / Category Pages
+
+| # | Template | Character Count |
+|---|----------|-----------------|
+| 8 | Shop [category] from [Brand]. [N]+ [items] starting at $[price]. Free shipping on orders over $[amount]. | ~145-160 |
+| 9 | Browse our [adjective] collection of [products]. [Unique selling point]. [Guarantee/offer]. Order today. | ~140-155 |
+
+#### Comparison Pages
+
+| # | Template | Character Count |
+|---|----------|-----------------|
+| 10 | [A] vs [B]: which is better for [use case]? We compared [criteria]. See the winner + detailed breakdown. | ~145-160 |
+| 11 | Comparing [A] and [B] on [criteria 1], [criteria 2], and price. Our [year] verdict inside. | ~130-145 |
+
+#### Local Business Pages
+
+| # | Template | Character Count |
+|---|----------|-----------------|
+| 12 | [Service] in [City] by [Brand]. [Experience] years of experience. [N]-star rated. [CTA] — call [phone] today. | ~150-160 |
+| 13 | Need [service] in [location]? [Brand] offers [differentiator]. [Guarantee]. Book your [offer] now. | ~140-155 |
+
+---
+
+## A/B Testing Methodology for Titles and Descriptions
+
+### Pre-Test Preparation
+
+1. **Baseline metrics** — Record current CTR, average position, impressions, and clicks for the target page (minimum 30 days of data from ~~search console).
+2. **Hypothesis** — State what you expect to change and why: "Adding a number to the title will increase CTR by X% because listicle titles outperform generic ones at this SERP position."
+3. **Single variable** — Change only ONE element per test (title OR description, not both).
+4. **Minimum sample** — Wait until the page has accumulated at least 1,000 impressions in the test period before drawing conclusions.
+
+### Test Execution Steps
+
+| Step | Action | Duration |
+|------|--------|----------|
+| 1 | Record baseline CTR for 30 days | 30 days |
+| 2 | Implement title/description change | Day 0 |
+| 3 | Allow Google to re-crawl and update SERP | 3-7 days |
+| 4 | Monitor new CTR (exclude first 7 days) | 30+ days |
+| 5 | Compare new CTR vs. baseline at same avg. position | — |
+| 6 | Decide: keep, revert, or iterate | — |
+
+### What to Test (Priority Order)
+
+| Priority | Element | Test Variable | Expected Impact |
+|----------|---------|--------------|-----------------|
+| 1 | Title tag | Add/remove number | +15-25% CTR |
+| 2 | Title tag | Add/remove year | +10-15% CTR |
+| 3 | Title tag | Add brackets/parentheses | +10-38% CTR |
+| 4 | Title tag | Change power word | +5-12% CTR |
+| 5 | Title tag | Reorder keyword placement | +5-10% CTR |
+| 6 | Meta description | Add CTA | +5-10% CTR |
+| 7 | Meta description | Add numbers/statistics | +5-15% CTR |
+| 8 | Meta description | Change emotional tone | +3-8% CTR |
+
+### Interpreting Results
+
+| Scenario | Interpretation | Action |
+|----------|---------------|--------|
+| CTR up, position stable | Title/description change is working | Keep the change |
+| CTR up, position up | Improved engagement signals helping rankings | Keep and document |
+| CTR down, position stable | Change was negative | Revert immediately |
+| CTR flat, position stable | Change had no impact | Try a bolder variation |
+| CTR up, position down | Higher CTR but lower impressions | Evaluate net click change |
+
+### Statistical Significance Checklist
+
+- [ ] Minimum 1,000 impressions in test period
+- [ ] Test ran for at least 30 days (after re-crawl)
+- [ ] Average position did not shift more than 2 positions
+- [ ] No major algorithm updates during test period
+- [ ] No seasonal bias (compare similar months year-over-year)
+- [ ] CTR change exceeds 10% relative difference
+
+---
+
+## Seasonal Title Patterns
+
+### Calendar-Driven Updates
+
+| Season/Event | Title Modifier | Example |
+|-------------|---------------|---------|
+| New Year (Jan) | [Year] Edition, Updated for [Year] | SEO Checklist: 2026 Edition |
+| Q1 Planning | [Year] Strategy, Q1 [Year] | Content Strategy for Q1 2026 |
+| Spring | Spring [Year], Fresh | Spring 2026 SEO Audit Checklist |
+| Back to School (Aug-Sep) | Fall [Year], New Season | Fall 2026 Marketing Trends |
+| Black Friday (Nov) | Black Friday [Year], Holiday | Black Friday SEO Prep Guide (2026) |
+| End of Year (Dec) | [Year] Wrap-Up, [Next Year] Preview | 2026 SEO Wrap-Up + 2027 Predictions |
+| Any month | [Month] [Year] | Best SEO Tools (February 2026) |
+
+### Evergreen + Fresh Hybrid Strategy
+
+Keep the core title evergreen but append a freshness signal:
+
+| Base Title (Evergreen) | Freshness Signal | Combined |
+|-----------------------|------------------|----------|
+| How to Start a Blog | (Updated Feb 2026) | How to Start a Blog (Updated Feb 2026) |
+| Best CRM Software | [2026 Rankings] | Best CRM Software [2026 Rankings] |
+| SEO Beginner's Guide | - Latest Edition | SEO Beginner's Guide - Latest Edition |
+
+**Update cadence**: Refresh the year/date modifier every 3-6 months for pages targeting "best", "top", or year-based queries.
+
+---
+
+## CTR Benchmarks by Industry
+
+### Average Organic CTR by SERP Position (All Industries)
+
+| Position | Desktop CTR | Mobile CTR | Combined Avg |
+|----------|------------|------------|-------------|
+| 1 | 31.7% | 26.9% | 29.3% |
+| 2 | 17.5% | 15.1% | 16.3% |
+| 3 | 11.3% | 10.2% | 10.8% |
+| 4 | 7.9% | 7.1% | 7.5% |
+| 5 | 5.8% | 5.2% | 5.5% |
+| 6 | 4.4% | 3.9% | 4.2% |
+| 7 | 3.5% | 3.1% | 3.3% |
+| 8 | 2.9% | 2.5% | 2.7% |
+| 9 | 2.5% | 2.1% | 2.3% |
+| 10 | 2.2% | 1.8% | 2.0% |
+
+### CTR Variation by Industry Vertical
+
+| Industry | Avg CTR (Pos 1) | Avg CTR (Pos 1-3) | Notes |
+|----------|----------------|-------------------|-------|
+| Technology / SaaS | 25-30% | 50-55% | High competition; rich results common |
+| E-commerce | 20-25% | 40-45% | Shopping results reduce organic CTR |
+| Healthcare | 28-35% | 55-60% | Users seek authoritative sources |
+| Finance | 22-28% | 45-50% | Featured snippets capture clicks |
+| Travel | 18-24% | 38-44% | Maps and hotel packs reduce CTR |
+| Legal | 30-38% | 58-65% | High intent; fewer SERP features |
+| Education | 26-32% | 52-58% | Informational queries; high trust needed |
+| Real Estate | 20-26% | 42-48% | Local packs reduce organic CTR |
+| Food / Recipes | 15-22% | 35-42% | Recipe carousels dominate top positions |
+| B2B Services | 28-34% | 55-62% | Less SERP competition; niche queries |
+
+### When Your CTR Is Below Benchmark
+
+| CTR vs. Benchmark | Likely Cause | Recommended Action |
+|-------------------|-------------|-------------------|
+| 50%+ below | Title does not match intent | Rewrite title to align with query intent |
+| 25-50% below | Weak title or strong SERP features | Add power words, numbers, or brackets |
+| 10-25% below | Competitors have better titles | Analyze top 3 competitor titles and differentiate |
+| At benchmark | Performing as expected | Test incremental improvements |
+| Above benchmark | Strong title; optimize further | Protect current title; test description instead |
+
+---
+
+## Multi-Language Title Optimization
+
+### General Principles
+
+1. **Do not translate literally** -- Adapt the title formula to the target language's natural phrasing and cultural norms.
+2. **Character limits vary** -- CJK characters are wider; effective SERP display length is shorter by character count.
+3. **Keyword research per locale** -- Search volume and intent differ across languages. Always do locale-specific keyword research.
+4. **Brand name placement** -- Some markets prefer brand-first; others prefer keyword-first.
+
+### Language-Specific Considerations
+
+| Language | Max Chars (SERP) | Key Differences | Example Adaptation |
+|----------|-----------------|-----------------|-------------------|
+| English | 55-60 | Standard baseline | How to Learn SEO (2026 Guide) |
+| Spanish | 55-60 | Longer phrases; use abbreviations | Como Aprender SEO: Guia Completa 2026 |
+| French | 55-60 | Accented characters count same | Guide SEO Complet : Comment se Classer en 2026 |
+| German | 50-55 | Compound words are long | SEO-Leitfaden 2026: Schritt-fur-Schritt |
+| Japanese | 30-35 | CJK characters take ~2x width | SEO対策ガイド2026【初心者向け】 |
+| Chinese (Simplified) | 28-32 | CJK characters; brackets common | SEO优化指南(2026完整版) |
+| Korean | 30-35 | CJK width; particles add length | SEO 최적화 가이드 2026 [초보자용] |
+| Arabic | 50-55 | RTL display; test SERP rendering | دليل تحسين محركات البحث 2026 |
+| Portuguese (BR) | 55-60 | Similar to Spanish | Guia de SEO 2026: Como Ranquear no Google |
+| Hindi | 45-50 | Devanagari takes more width | SEO कैसे करें: 2026 गाइड |
+
+### Multi-Language Meta Description Tips
+
+| Principle | Detail |
+|-----------|--------|
+| Localize the CTA | "Learn more" may not translate well; use culturally appropriate CTAs |
+| Adjust character targets | For CJK, aim for 70-80 characters; for Latin-script languages, 150-160 |
+| Use local proof points | Reference local statistics, regulations, or market leaders |
+| Test SERP rendering | Use Google's SERP preview in the target locale to check truncation |
+| Separate hreflang tags | Ensure each language version has the correct hreflang annotation |
+
+---
+
+## Title Tag Modifier Library
+
+### Modifiers by Purpose
+
+| Purpose | Modifiers |
+|---------|----------|
+| Freshness | 2026, Updated, Latest, New, This Month, This Week |
+| Comprehensiveness | Complete, Ultimate, Definitive, A-to-Z, Full, In-Depth |
+| Ease | Easy, Simple, Quick, Beginner, No-Code, DIY |
+| Speed | Fast, Instant, [N]-Minute, Today, Quick-Start |
+| Authority | Expert, Pro, Advanced, Research-Backed, Data-Driven |
+| Value | Free, Cheap, Budget, Affordable, Open-Source |
+| Format | Guide, Checklist, Template, Cheat Sheet, Playbook, Toolkit |
+| Exclusivity | Insider, Members-Only, Exclusive, First Look, Early Access |
+| Social Proof | Trusted, [N]+ Users, Award-Winning, #1 Rated |
+| Scarcity | Limited, Last Chance, Ending Soon, Only [N] Left |
+
+### Modifier Placement Rules
+
+| Position | When to Use | Example |
+|----------|------------|---------|
+| Front | When modifier IS the keyword ("Free", "Best") | Free SEO Audit Tool for Small Business |
+| Middle | When clarifying the topic | SEO Tools (Free) for Small Business |
+| End (parenthetical) | When adding value signal | SEO Tools for Small Business (Free) |
+| End (pipe/dash) | When adding brand | SEO Tools for Small Business \| Brand |
+
+---
+
+## Common Title Tag Mistakes
+
+| Mistake | Why It Hurts | Fix |
+|---------|-------------|-----|
+| Keyword stuffing | Google may rewrite your title | Use primary keyword once; vary phrasing |
+| Too generic ("Home", "Welcome") | Zero CTR differentiation | Write a benefit-driven title |
+| All caps | Looks spammy; may be rewritten | Use title case or sentence case |
+| Missing primary keyword | Misses ranking signal | Include target keyword naturally |
+| Duplicate titles across pages | Cannibalization; Google may pick wrong page | Unique title per page |
+| Brand name first (non-branded query) | Wastes prime keyword space | Put brand at end after pipe |
+| No emotional hook | Blends in with competitors | Add one power word or number |
+| Exceeding 60 characters | Key info truncated in SERP | Front-load; keep under 60 chars |
+| Misleading clickbait | High bounce rate hurts rankings | Title must match content delivery |
+| Ignoring SERP context | Title doesn't stand out among competitors | Check live SERP before finalizing |
+
+---
+
+## Quick-Reference: Title Formula Selection Flowchart
+
+```
+START: What type of content is this?
+|
++-- Informational (how-to, guide, tutorial)
+| +-- Is it step-by-step? --> Use Formula #2 or #8
+| +-- Is it a definition? --> Use Formula #6
+| +-- Is it comprehensive? --> Use Formula #3 or #4
+| +-- Is it for beginners? --> Use Formula #5
+|
++-- Listicle (tips, tools, examples)
+| +-- Is it "best of"? --> Use Formula #10
+| +-- Is it mistakes/warnings? --> Use Formula #14 or #29
+| +-- Is it tips/strategies? --> Use Formula #9 or #12
+| +-- Is it examples? --> Use Formula #13
+|
++-- Comparison
+| +-- Two products/tools? --> Use Formula #17 or #18
+| +-- Multiple alternatives? --> Use Formula #20
+|
++-- Commercial / Product
+| +-- Product page? --> Use Formula #21
+| +-- Pricing page? --> Use Formula #22
+| +-- Review? --> Use Formula #23
+| +-- Free tool? --> Use Formula #24
+|
++-- Local
+| +-- Service page? --> Use Formula #25
+| +-- Best-of local? --> Use Formula #26
+| +-- Near me? --> Use Formula #27
+```
diff --git a/seo/schema-markup-generator/SKILL.md b/seo/schema-markup-generator/SKILL.md
new file mode 100644
index 00000000..c991163f
--- /dev/null
+++ b/seo/schema-markup-generator/SKILL.md
@@ -0,0 +1,322 @@
+---
+name: schema-markup-generator
+description: >
+ Generate JSON-LD structured data markup for rich results in Google Search.
+ Supports FAQ, HowTo, Article, Product, LocalBusiness, and multi-type schemas.
+ Validates against Google requirements and provides implementation guidance.
+ Use when asked to "add schema markup", "generate structured data", "JSON-LD",
+ "rich snippets", "FAQ schema", "product markup", "add structured data to my
+ page", "how to get rich snippets", or any structured data task.
+---
+
+## Preamble (run first)
+
+```bash
+_UPD=$(~/.claude/skills/toprank/bin/toprank-update-check 2>/dev/null || \
+ ~/.claude/skills/stockholm/bin/toprank-update-check 2>/dev/null || true)
+[ -n "$_UPD" ] && echo "$_UPD" || true
+```
+
+If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/toprank-upgrade` skill (Step 1 onward) to auto-upgrade, then return here and continue.
+
+If the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded from v{old} to v{new}" briefly, then continue.
+
+---
+
+# Schema Markup Generator
+
+This skill creates Schema.org structured data markup in JSON-LD format to help search engines understand your content and enable rich results in SERPs.
+
+## When This Must Trigger
+
+Use this when the conversation involves any of these situations — even if the user does not use SEO terminology:
+
+Use this whenever the task needs a shippable asset or transformation that should feed directly into quality review, deployment, or monitoring.
+
+- Adding FAQ schema for expanded SERP presence
+- Creating How-To schema for step-by-step content
+- Adding Product schema for e-commerce pages
+- Implementing Article schema for blog posts
+- Adding Local Business schema for location pages
+- Creating Review/Rating schema
+- Implementing Organization schema for brand presence
+- Any page where rich results would improve visibility
+
+## What This Skill Does
+
+1. **Schema Type Selection**: Recommends appropriate schema types
+2. **JSON-LD Generation**: Creates valid structured data markup
+3. **Property Mapping**: Maps your content to schema properties
+4. **Validation Guidance**: Ensures schema meets requirements
+5. **Nested Schema**: Handles complex, multi-type schemas
+6. **Rich Result Eligibility**: Identifies which rich results you can target
+
+## Quick Start
+
+Start with one of these prompts.
+
+### Generate Schema for Content
+
+```
+Generate schema markup for this [content type]: [content/URL]
+```
+
+```
+Create FAQ schema for these questions and answers: [Q&A list]
+```
+
+### Specific Schema Types
+
+```
+Create Product schema for [product name] with [details]
+```
+
+```
+Generate LocalBusiness schema for [business name and details]
+```
+
+### Audit Existing Schema
+
+```
+Review and improve this schema markup: [existing schema]
+```
+
+## Data Sources
+
+**With ~~web crawler connected:**
+Automatically crawl and extract page content (visible text, headings, lists, tables), existing schema markup, page metadata, and structured content elements that map to schema properties.
+
+**With manual data only:**
+Ask the user to provide:
+1. Page URL or full HTML content
+2. Page type (article, product, FAQ, how-to, local business, etc.)
+3. Specific data needed for schema (prices, dates, author info, Q&A pairs, etc.)
+4. Current schema markup (if optimizing existing)
+
+Proceed with the full workflow using provided data. Note in the output which data is from automated extraction vs. user-provided data.
+
+## Instructions
+
+When a user requests schema markup:
+
+1. **Identify Content Type and Rich Result Opportunity**
+
+ Reference the CORE-EEAT Benchmark item **O05 (Schema Markup)** for content-type to schema mapping:
+
+ ```markdown
+ ### CORE-EEAT Schema Mapping (O05)
+
+ | Content Type | Required Schema | Conditional Schema |
+ |-------------|----------------|--------------------|
+ | Blog (guides) | Article, Breadcrumb | FAQ, HowTo |
+ | Blog (tools) | Article, Breadcrumb | FAQ, Review |
+ | Blog (insights) | Article, Breadcrumb | FAQ |
+ | Alternative | Comparison*, Breadcrumb, FAQ | AggregateRating |
+ | Best-of | ItemList, Breadcrumb, FAQ | AggregateRating per tool |
+ | Use-case | WebPage, Breadcrumb, FAQ | — |
+ | FAQ | FAQPage, Breadcrumb | — |
+ | Landing | SoftwareApplication, Breadcrumb, FAQ | WebPage |
+ | Testimonial | Review, Breadcrumb | FAQ, Person |
+
+ *Use the mapping above to ensure schema type matches content type (CORE-EEAT O05: Pass criteria).*
+ ```
+
+ ```markdown
+ ### Schema Analysis
+
+ **Content Type**: [blog/product/FAQ/how-to/local business/etc.]
+ **Page URL**: [URL]
+
+ **Eligible Rich Results**:
+
+ | Rich Result Type | Eligibility | Impact |
+ |------------------|-------------|--------|
+ | FAQ | ✅/❌ | High - Expands SERP presence |
+ | How-To | ✅/❌ | Medium - Shows steps in SERP |
+ | Product | ✅/❌ | High - Shows price, availability |
+ | Review | ✅/❌ | High - Shows star ratings |
+ | Article | ✅/❌ | Medium - Shows publish date, author |
+ | Breadcrumb | ✅/❌ | Medium - Shows navigation path |
+ | Video | ✅/❌ | High - Shows video thumbnail |
+
+ **Recommended Schema Types**:
+ 1. [Primary schema type] - [reason]
+ 2. [Secondary schema type] - [reason]
+ ```
+
+2. **Generate Schema Markup**
+
+ Based on the identified content type, generate the appropriate JSON-LD schema. Supported types: FAQPage, HowTo, Article/BlogPosting/NewsArticle, Product, LocalBusiness, Organization, BreadcrumbList, Event, Recipe, and combined multi-type schemas.
+
+ > **Reference**: See [references/schema-templates.md](references/schema-templates.md) for complete, copy-ready JSON-LD templates for all schema types with required and optional properties.
+
+ For each schema generated, include:
+ - All required properties for the chosen type
+ - Rich result preview showing expected SERP appearance
+ - Notes on which properties are required vs. optional
+
+ When combining multiple schema types on one page, wrap them in a JSON array inside a single `<script type="application/ld+json">` tag.
+
+3. **Provide Implementation and Validation**
+
+ ```markdown
+ ## Implementation Guide
+
+ ### Adding Schema to Your Page
+
+ **Option 1: In HTML <head>**
+ ```html
+ <head>
+ <script type="application/ld+json">
+ [Your JSON-LD schema here]
+ </script>
+ </head>
+ ```
+
+ **Option 2: Before closing </body>**
+ ```html
+ <script type="application/ld+json">
+ [Your JSON-LD schema here]
+ </script>
+ </body>
+ ```
+
+ ### Validation Steps
+
+ 1. **~~schema validator**
+ - Test your live URL or paste code
+ - Check for errors and warnings
+
+ 2. **Schema.org Validator**
+ - URL: https://validator.schema.org/
+ - Validates against Schema.org spec
+
+ 3. **~~search console**
+ - Monitor rich results in ~~search console
+ - Check Enhancements reports for issues
+
+ ### Validation Checklist
+
+ - [ ] JSON syntax is valid (no trailing commas)
+ - [ ] All required properties present
+ - [ ] URLs are absolute, not relative
+ - [ ] Dates are in ISO 8601 format
+ - [ ] Content matches visible page content
+ - [ ] No policy violations
+ ```
+
+## Validation Checkpoints
+
+### Input Validation
+- [ ] Page URL or content provided
+- [ ] Schema type appropriate for content (Article for blog, Product for e-commerce, etc.)
+- [ ] All required data available (author, dates, prices, etc. depending on schema type)
+- [ ] Content eligibility for rich results confirmed
+
+### Output Validation
+- [ ] JSON syntax validates (no trailing commas, proper quotes)
+- [ ] All required properties present for chosen schema type
+- [ ] URLs are absolute, not relative
+- [ ] Dates in ISO 8601 format (YYYY-MM-DDTHH:MM:SS+00:00)
+- [ ] Schema content matches visible page content exactly
+- [ ] Passes ~~schema validator with no errors
+- [ ] Source of each data point clearly stated (~~web crawler extraction, user-provided, or manual entry)
+
+## Example
+
+**User**: "Generate FAQ schema for a page about SEO with 3 questions"
+
+**Output**:
+
+```markdown
+## FAQ Schema for SEO Page
+
+### Schema Markup
+
+```json
+{
+ "@context": "https://schema.org",
+ "@type": "FAQPage",
+ "mainEntity": [
+ {
+ "@type": "Question",
+ "name": "What is SEO?",
+ "acceptedAnswer": {
+ "@type": "Answer",
+ "text": "SEO (Search Engine Optimization) is the practice of optimizing websites and content to rank higher in search engine results pages (SERPs). It involves technical optimizations, content creation, and link building to increase organic visibility and drive qualified traffic to your website."
+ }
+ },
+ {
+ "@type": "Question",
+ "name": "How long does SEO take to work?",
+ "acceptedAnswer": {
+ "@type": "Answer",
+ "text": "SEO typically takes 3-6 months to show significant results, though this varies based on competition, domain authority, and effort invested. New websites may take 6-12 months, while established sites with existing authority can see improvements in 1-3 months for less competitive keywords."
+ }
+ },
+ {
+ "@type": "Question",
+ "name": "Is SEO better than paid advertising?",
+ "acceptedAnswer": {
+ "@type": "Answer",
+ "text": "SEO and paid advertising serve different purposes. SEO provides sustainable, long-term traffic without per-click costs but takes time to build. Paid advertising delivers immediate results but stops when you stop paying. Most successful businesses use both: paid ads for immediate leads and SEO for long-term growth."
+ }
+ }
+ ]
+}
+```
+
+_Implementation: Wrap the above JSON-LD in `<script type="application/ld+json">...</script>` and place in `<head>` or before `</body>`. Test with ~~schema validator._
+
+### SERP Preview
+
+```
+SEO Guide: Complete Beginner's Tutorial
+yoursite.com/seo-guide/
+Learn SEO from scratch with our comprehensive guide...
+
+▼ What is SEO?
+ SEO (Search Engine Optimization) is the practice of optimizing...
+▼ How long does SEO take to work?
+ SEO typically takes 3-6 months to show significant results...
+▼ Is SEO better than paid advertising?
+ SEO and paid advertising serve different purposes...
+```
+```
+
+## Schema Type Quick Reference
+
+| Content Type | Schema Type | Key Properties |
+|--------------|-------------|----------------|
+| Blog Post | BlogPosting/Article | headline, datePublished, author |
+| Product | Product | name, price, availability |
+| FAQ | FAQPage | Question, Answer |
+| How-To | HowTo | step, totalTime |
+| Local Business | LocalBusiness | address, geo, openingHours |
+| Recipe | Recipe | ingredients, cookTime |
+| Event | Event | startDate, location |
+| Video | VideoObject | uploadDate, duration |
+| Course | Course | provider, name |
+| Review | Review | itemReviewed, ratingValue |
+
+## Tips for Success
+
+1. **Match visible content** - Schema must reflect what users see
+2. **Don't spam** - Only add schema for relevant content
+3. **Keep updated** - Update dates and prices when they change
+4. **Test thoroughly** - Validate before deploying
+5. **Monitor Search Console** - Watch for errors and warnings
+
+## Schema Type Decision Tree
+
+> **Reference**: See [references/schema-decision-tree.md](references/schema-decision-tree.md) for the full decision tree (content-to-schema mapping), industry-specific recommendations, implementation priority tiers (P0-P4), and validation quick reference.
+
+
+## Reference Materials
+
+- [Schema Templates](references/schema-templates.md) - Copy-ready JSON-LD templates for all schema types
+- [Validation Guide](references/validation-guide.md) - Common errors, required properties, testing workflow
+
+## Next Best Skill
+
+- **Primary**: [seo-analysis](../seo-analysis/SKILL.md) — verify implementation with a technical SEO audit.
diff --git a/seo/schema-markup-generator/references/schema-decision-tree.md b/seo/schema-markup-generator/references/schema-decision-tree.md
new file mode 100644
index 00000000..6ba8a175
--- /dev/null
+++ b/seo/schema-markup-generator/references/schema-decision-tree.md
@@ -0,0 +1,65 @@
+# Schema Type Decision Tree
+
+Guidelines for selecting the right schema types based on content, industry, and implementation priority.
+
+---
+
+## When to Use Which Schema
+
+| Your Content | Primary Schema | Add If Applicable | Rich Result Eligibility |
+|-------------|---------------|-------------------|----------------------|
+| Blog post / article | Article | FAQ, HowTo, Speakable | Article carousel, FAQ rich result |
+| Product page | Product | Review, Offer, AggregateRating | Product snippet with price/rating |
+| Service page | Service | FAQ, LocalBusiness | Service snippet |
+| How-to guide | HowTo | Article, FAQ | How-to rich result with steps |
+| FAQ page | FAQPage | Article | FAQ accordion in SERP |
+| Recipe | Recipe | Video, AggregateRating | Recipe carousel |
+| Event | Event | Offer, Organization | Event snippet with date/location |
+| Video | VideoObject | Article | Video carousel, key moments |
+| Local business | LocalBusiness | Review, OpeningHoursSpecification | Local pack, knowledge panel |
+| Person/author | Person | Organization | Knowledge panel |
+| Organization | Organization | ContactPoint, Logo | Knowledge panel |
+| Course | Course | Organization | Course rich result |
+| Job posting | JobPosting | Organization | Google for Jobs listing |
+| Breadcrumb | BreadcrumbList | (Always add alongside other schema) | Breadcrumb trail in SERP |
+| Software/App | SoftwareApplication | Review, Offer | App snippet |
+
+---
+
+## Industry-Specific Schema Recommendations
+
+| Industry | Essential Schema | High-Value Additions |
+|----------|-----------------|---------------------|
+| E-commerce | Product, BreadcrumbList, Organization | AggregateRating, FAQ, Review |
+| SaaS | SoftwareApplication, FAQPage, Organization | HowTo, VideoObject, Review |
+| Local Services | LocalBusiness, Service | FAQ, Review, Event |
+| Publishing/Media | Article, Person, Organization | FAQ, Speakable, VideoObject |
+| Education | Course, Organization | FAQ, HowTo, Event |
+| Healthcare | MedicalWebPage, Organization | FAQ, Physician, MedicalClinic |
+| Real Estate | RealEstateListing, Organization | LocalBusiness, FAQ |
+| Restaurants | Restaurant, Menu | Review, Event, FAQ |
+
+---
+
+## Schema Implementation Priority
+
+| Priority | Schema Types | Why |
+|----------|-------------|-----|
+| P0 -- Always | Organization, BreadcrumbList, WebSite (SearchAction) | Foundation for all sites |
+| P1 -- Content | Article, FAQPage, HowTo | Direct rich result eligibility |
+| P2 -- Commercial | Product, Review, AggregateRating, Offer | Revenue-impacting rich results |
+| P3 -- Authority | Person, SameAs, Speakable | E-E-A-T signals, AI citation |
+| P4 -- Specialized | Industry-specific types | Niche rich results |
+
+---
+
+## Schema Validation Quick Reference
+
+| Issue | Impact | Fix |
+|-------|--------|-----|
+| Missing required property | Schema ignored by Google | Add all required fields (check schema.org) |
+| Invalid date format | Warning, may lose rich result | Use ISO 8601: "2026-02-11" |
+| Incorrect @type | Schema misinterpreted | Match @type exactly to schema.org |
+| Self-referencing sameAs | Warning | sameAs should link to EXTERNAL profiles |
+| Missing image for Article | Loses article rich result | Add image property with valid URL |
+| Review without itemReviewed | Review not connected | Nest review inside Product/Service/etc. |
diff --git a/seo/schema-markup-generator/references/schema-templates.md b/seo/schema-markup-generator/references/schema-templates.md
new file mode 100644
index 00000000..bb4925cf
--- /dev/null
+++ b/seo/schema-markup-generator/references/schema-templates.md
@@ -0,0 +1,631 @@
+# Schema.org JSON-LD Templates
+
+Complete, copy-ready structured data templates for all major schema types. Customize the bracketed values to match your content.
+
+## FAQPage Schema
+
+For pages with frequently asked questions. Minimum 2 Q&A pairs required.
+
+```json
+{
+ "@context": "https://schema.org",
+ "@type": "FAQPage",
+ "mainEntity": [
+ {
+ "@type": "Question",
+ "name": "[Question text - exactly as shown on page]",
+ "acceptedAnswer": {
+ "@type": "Answer",
+ "text": "[Complete answer text - must match visible content]"
+ }
+ },
+ {
+ "@type": "Question",
+ "name": "[Question 2]",
+ "acceptedAnswer": {
+ "@type": "Answer",
+ "text": "[Answer 2]"
+ }
+ },
+ {
+ "@type": "Question",
+ "name": "[Question 3]",
+ "acceptedAnswer": {
+ "@type": "Answer",
+ "text": "[Answer 3]"
+ }
+ }
+ ]
+}
+```
+
+**Requirements**: Questions must be complete questions, answers must be comprehensive, content must match visible page content.
+
+---
+
+## HowTo Schema
+
+For step-by-step instructional content.
+
+```json
+{
+ "@context": "https://schema.org",
+ "@type": "HowTo",
+ "name": "[How-to title - what will users learn]",
+ "description": "[Brief description of what this tutorial teaches]",
+ "image": {
+ "@type": "ImageObject",
+ "url": "[Main image URL]",
+ "height": "[height in pixels]",
+ "width": "[width in pixels]"
+ },
+ "totalTime": "PT[X]H[Y]M",
+ "estimatedCost": {
+ "@type": "MonetaryAmount",
+ "currency": "USD",
+ "value": "[estimated cost or 0]"
+ },
+ "supply": [
+ {
+ "@type": "HowToSupply",
+ "name": "[Supply item 1]"
+ },
+ {
+ "@type": "HowToSupply",
+ "name": "[Supply item 2]"
+ }
+ ],
+ "tool": [
+ {
+ "@type": "HowToTool",
+ "name": "[Tool 1]"
+ },
+ {
+ "@type": "HowToTool",
+ "name": "[Tool 2]"
+ }
+ ],
+ "step": [
+ {
+ "@type": "HowToStep",
+ "position": 1,
+ "name": "[Step 1 title]",
+ "text": "[Step 1 detailed instructions]",
+ "url": "[Page URL]#step1",
+ "image": "[Step 1 image URL - optional]"
+ },
+ {
+ "@type": "HowToStep",
+ "position": 2,
+ "name": "[Step 2 title]",
+ "text": "[Step 2 detailed instructions]",
+ "url": "[Page URL]#step2",
+ "image": "[Step 2 image URL - optional]"
+ },
+ {
+ "@type": "HowToStep",
+ "position": 3,
+ "name": "[Step 3 title]",
+ "text": "[Step 3 detailed instructions]",
+ "url": "[Page URL]#step3",
+ "image": "[Step 3 image URL - optional]"
+ }
+ ]
+}
+```
+
+**Time format**: PT[X]H[Y]M where X = hours, Y = minutes. Example: PT1H30M = 1 hour 30 minutes.
+
+---
+
+## Article / BlogPosting / NewsArticle Schema
+
+For blog posts, articles, and news content.
+
+```json
+{
+ "@context": "https://schema.org",
+ "@type": "BlogPosting",
+ "headline": "[Article title - max 110 characters for best display]",
+ "description": "[Article summary or excerpt]",
+ "image": [
+ "[Featured image URL - 1200px wide recommended]",
+ "[Alternative image URL - 4:3 ratio]",
+ "[Alternative image URL - 16:9 ratio]"
+ ],
+ "datePublished": "[ISO 8601 date: 2024-01-15T08:00:00+00:00]",
+ "dateModified": "[ISO 8601 date - same as published if never modified]",
+ "author": {
+ "@type": "Person",
+ "name": "[Author Full Name]",
+ "url": "[Author profile URL]",
+ "jobTitle": "[Author job title - optional]"
+ },
+ "publisher": {
+ "@type": "Organization",
+ "name": "[Publisher/Company Name]",
+ "logo": {
+ "@type": "ImageObject",
+ "url": "[Publisher logo URL - max 600px wide, 60px high]",
+ "width": "[width]",
+ "height": "[height]"
+ }
+ },
+ "mainEntityOfPage": {
+ "@type": "WebPage",
+ "@id": "[Canonical URL of this article]"
+ },
+ "articleBody": "[Full article text - optional but recommended]",
+ "wordCount": "[word count - optional]"
+}
+```
+
+**Type variants**: Use `Article` for general articles, `BlogPosting` for blog posts, `NewsArticle` for news content, `TechArticle` for technical documentation.
+
+---
+
+## Product Schema
+
+For e-commerce product pages.
+
+```json
+{
+ "@context": "https://schema.org",
+ "@type": "Product",
+ "name": "[Product Name]",
+ "image": [
+ "[Product image URL 1]",
+ "[Product image URL 2]",
+ "[Product image URL 3]"
+ ],
+ "description": "[Product description]",
+ "sku": "[SKU code]",
+ "mpn": "[Manufacturer Part Number - optional]",
+ "brand": {
+ "@type": "Brand",
+ "name": "[Brand Name]"
+ },
+ "offers": {
+ "@type": "Offer",
+ "url": "[Product page URL]",
+ "priceCurrency": "USD",
+ "price": "[Price as number: 29.99]",
+ "priceValidUntil": "[Date price is valid until: 2024-12-31]",
+ "availability": "https://schema.org/InStock",
+ "seller": {
+ "@type": "Organization",
+ "name": "[Seller/Store Name]"
+ },
+ "shippingDetails": {
+ "@type": "OfferShippingDetails",
+ "shippingRate": {
+ "@type": "MonetaryAmount",
+ "value": "[shipping cost]",
+ "currency": "USD"
+ },
+ "shippingDestination": {
+ "@type": "DefinedRegion",
+ "addressCountry": "US"
+ }
+ }
+ },
+ "aggregateRating": {
+ "@type": "AggregateRating",
+ "ratingValue": "[4.5]",
+ "reviewCount": "[89]",
+ "bestRating": "5",
+ "worstRating": "1"
+ },
+ "review": [
+ {
+ "@type": "Review",
+ "reviewRating": {
+ "@type": "Rating",
+ "ratingValue": "[5]",
+ "bestRating": "5"
+ },
+ "author": {
+ "@type": "Person",
+ "name": "[Reviewer Name]"
+ },
+ "reviewBody": "[Review text]",
+ "datePublished": "[Review date: 2024-01-15]"
+ }
+ ]
+}
+```
+
+**Availability options**: `InStock`, `OutOfStock`, `PreOrder`, `Discontinued`, `LimitedAvailability`, `OnlineOnly`, `InStoreOnly`, `SoldOut`
+
+---
+
+## LocalBusiness Schema
+
+For local business pages with physical locations.
+
+```json
+{
+ "@context": "https://schema.org",
+ "@type": "LocalBusiness",
+ "name": "[Business Name]",
+ "image": "[Business image or logo URL]",
+ "@id": "[Business page URL]",
+ "url": "[Website URL]",
+ "telephone": "[Phone number: +1-555-555-5555]",
+ "priceRange": "[$$$ or price range like $10-$50]",
+ "address": {
+ "@type": "PostalAddress",
+ "streetAddress": "[Street address]",
+ "addressLocality": "[City]",
+ "addressRegion": "[State/Province]",
+ "postalCode": "[ZIP/Postal code]",
+ "addressCountry": "US"
+ },
+ "geo": {
+ "@type": "GeoCoordinates",
+ "latitude": "[latitude as number: 40.7128]",
+ "longitude": "[longitude as number: -74.0060]"
+ },
+ "openingHoursSpecification": [
+ {
+ "@type": "OpeningHoursSpecification",
+ "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
+ "opens": "09:00",
+ "closes": "17:00"
+ },
+ {
+ "@type": "OpeningHoursSpecification",
+ "dayOfWeek": "Saturday",
+ "opens": "10:00",
+ "closes": "15:00"
+ }
+ ],
+ "aggregateRating": {
+ "@type": "AggregateRating",
+ "ratingValue": "[4.5]",
+ "reviewCount": "[123]"
+ },
+ "servesCuisine": "[Cuisine type - for restaurants only]"
+}
+```
+
+**Type variants**: Use more specific types when applicable: `Restaurant`, `Store`, `AutoRepair`, `HealthAndBeautyBusiness`, `LegalService`, etc.
+
+---
+
+## Organization Schema
+
+For brand/company homepage.
+
+```json
+{
+ "@context": "https://schema.org",
+ "@type": "Organization",
+ "name": "[Organization Name]",
+ "url": "[Website URL]",
+ "logo": "[Logo URL - recommended 112x112px or larger]",
+ "description": "[Company description]",
+ "sameAs": [
+ "[Facebook URL]",
+ "[Twitter URL]",
+ "[LinkedIn URL]",
+ "[Instagram URL]",
+ "[YouTube URL]"
+ ],
+ "contactPoint": {
+ "@type": "ContactPoint",
+ "telephone": "[Phone number]",
+ "contactType": "customer service",
+ "email": "[Email address]",
+ "availableLanguage": ["English", "Spanish"],
+ "areaServed": "US"
+ },
+ "founder": {
+ "@type": "Person",
+ "name": "[Founder name - optional]"
+ },
+ "foundingDate": "[YYYY-MM-DD - optional]",
+ "address": {
+ "@type": "PostalAddress",
+ "streetAddress": "[Street address]",
+ "addressLocality": "[City]",
+ "addressRegion": "[State]",
+ "postalCode": "[ZIP]",
+ "addressCountry": "US"
+ }
+}
+```
+
+---
+
+## BreadcrumbList Schema
+
+For navigation breadcrumbs.
+
+```json
+{
+ "@context": "https://schema.org",
+ "@type": "BreadcrumbList",
+ "itemListElement": [
+ {
+ "@type": "ListItem",
+ "position": 1,
+ "name": "Home",
+ "item": "[Homepage URL]"
+ },
+ {
+ "@type": "ListItem",
+ "position": 2,
+ "name": "[Category Name]",
+ "item": "[Category URL]"
+ },
+ {
+ "@type": "ListItem",
+ "position": 3,
+ "name": "[Subcategory Name]",
+ "item": "[Subcategory URL]"
+ },
+ {
+ "@type": "ListItem",
+ "position": 4,
+ "name": "[Current Page Name]",
+ "item": "[Current Page URL]"
+ }
+ ]
+}
+```
+
+**Important**: Position numbers must be sequential starting from 1. Last item should be the current page.
+
+---
+
+## VideoObject Schema
+
+For video content.
+
+```json
+{
+ "@context": "https://schema.org",
+ "@type": "VideoObject",
+ "name": "[Video title]",
+ "description": "[Video description]",
+ "thumbnailUrl": "[Video thumbnail URL - minimum 160x90px]",
+ "uploadDate": "[ISO 8601 date: 2024-01-15T08:00:00+00:00]",
+ "duration": "PT[X]M[Y]S",
+ "contentUrl": "[Video file URL]",
+ "embedUrl": "[Video embed URL]",
+ "interactionStatistic": {
+ "@type": "InteractionCounter",
+ "interactionType": { "@type": "WatchAction" },
+ "userInteractionCount": "[view count]"
+ }
+}
+```
+
+**Duration format**: PT[X]M[Y]S where X = minutes, Y = seconds. Example: PT5M30S = 5 minutes 30 seconds.
+
+---
+
+## Event Schema
+
+For events, conferences, concerts, etc.
+
+```json
+{
+ "@context": "https://schema.org",
+ "@type": "Event",
+ "name": "[Event Name]",
+ "description": "[Event description]",
+ "image": "[Event image URL]",
+ "startDate": "[ISO 8601 date: 2024-06-15T19:00:00-05:00]",
+ "endDate": "[ISO 8601 date: 2024-06-15T22:00:00-05:00]",
+ "eventStatus": "https://schema.org/EventScheduled",
+ "eventAttendanceMode": "https://schema.org/OfflineEventAttendanceMode",
+ "location": {
+ "@type": "Place",
+ "name": "[Venue Name]",
+ "address": {
+ "@type": "PostalAddress",
+ "streetAddress": "[Street address]",
+ "addressLocality": "[City]",
+ "addressRegion": "[State]",
+ "postalCode": "[ZIP]",
+ "addressCountry": "US"
+ }
+ },
+ "offers": {
+ "@type": "Offer",
+ "url": "[Ticket purchase URL]",
+ "price": "[ticket price]",
+ "priceCurrency": "USD",
+ "availability": "https://schema.org/InStock",
+ "validFrom": "[Sale start date]"
+ },
+ "organizer": {
+ "@type": "Organization",
+ "name": "[Organizer name]",
+ "url": "[Organizer website]"
+ }
+}
+```
+
+**Event status options**: `EventScheduled`, `EventCancelled`, `EventPostponed`, `EventRescheduled`, `EventMovedOnline`
+
+**Attendance mode**: `OfflineEventAttendanceMode`, `OnlineEventAttendanceMode`, `MixedEventAttendanceMode`
+
+---
+
+## Course Schema
+
+For online courses and educational content.
+
+```json
+{
+ "@context": "https://schema.org",
+ "@type": "Course",
+ "name": "[Course Name]",
+ "description": "[Course description]",
+ "provider": {
+ "@type": "Organization",
+ "name": "[Provider name]",
+ "sameAs": "[Provider URL]"
+ },
+ "offers": {
+ "@type": "Offer",
+ "category": "Paid",
+ "price": "[price]",
+ "priceCurrency": "USD"
+ },
+ "hasCourseInstance": {
+ "@type": "CourseInstance",
+ "courseMode": "online",
+ "courseWorkload": "PT[X]H",
+ "instructor": {
+ "@type": "Person",
+ "name": "[Instructor name]"
+ }
+ }
+}
+```
+
+---
+
+## Recipe Schema
+
+For cooking recipes.
+
+```json
+{
+ "@context": "https://schema.org",
+ "@type": "Recipe",
+ "name": "[Recipe name]",
+ "image": "[Recipe image URL]",
+ "author": {
+ "@type": "Person",
+ "name": "[Author name]"
+ },
+ "datePublished": "[ISO 8601 date]",
+ "description": "[Recipe description]",
+ "prepTime": "PT[X]M",
+ "cookTime": "PT[X]M",
+ "totalTime": "PT[X]M",
+ "recipeYield": "[Servings: e.g., '4 servings']",
+ "recipeCategory": "[Category: e.g., 'Dinner']",
+ "recipeCuisine": "[Cuisine: e.g., 'Italian']",
+ "keywords": "[comma, separated, keywords]",
+ "nutrition": {
+ "@type": "NutritionInformation",
+ "calories": "[calories per serving]"
+ },
+ "recipeIngredient": [
+ "[Ingredient 1 with quantity]",
+ "[Ingredient 2 with quantity]",
+ "[Ingredient 3 with quantity]"
+ ],
+ "recipeInstructions": [
+ {
+ "@type": "HowToStep",
+ "text": "[Step 1 instructions]"
+ },
+ {
+ "@type": "HowToStep",
+ "text": "[Step 2 instructions]"
+ }
+ ],
+ "aggregateRating": {
+ "@type": "AggregateRating",
+ "ratingValue": "[4.5]",
+ "reviewCount": "[number of reviews]"
+ }
+}
+```
+
+---
+
+## SoftwareApplication Schema
+
+For software, apps, and tools.
+
+```json
+{
+ "@context": "https://schema.org",
+ "@type": "SoftwareApplication",
+ "name": "[Software name]",
+ "operatingSystem": "[Windows, macOS, iOS, Android, Web]",
+ "applicationCategory": "BusinessApplication",
+ "offers": {
+ "@type": "Offer",
+ "price": "[price or 0 for free]",
+ "priceCurrency": "USD"
+ },
+ "aggregateRating": {
+ "@type": "AggregateRating",
+ "ratingValue": "[4.5]",
+ "reviewCount": "[number of reviews]"
+ },
+ "screenshot": "[Screenshot URL - optional]",
+ "softwareVersion": "[version number]",
+ "fileSize": "[file size with units: e.g., '50MB']",
+ "datePublished": "[Release date]",
+ "downloadUrl": "[Download URL - optional]"
+}
+```
+
+---
+
+## Multiple Schema Types (Combined Array)
+
+To include multiple schema types on one page, wrap them in an array:
+
+```html
+<script type="application/ld+json">
+[
+ {
+ "@context": "https://schema.org",
+ "@type": "Article",
+ "headline": "[Article title]",
+ "author": {
+ "@type": "Person",
+ "name": "[Author]"
+ }
+ },
+ {
+ "@context": "https://schema.org",
+ "@type": "FAQPage",
+ "mainEntity": [
+ {
+ "@type": "Question",
+ "name": "[Question]",
+ "acceptedAnswer": {
+ "@type": "Answer",
+ "text": "[Answer]"
+ }
+ }
+ ]
+ },
+ {
+ "@context": "https://schema.org",
+ "@type": "BreadcrumbList",
+ "itemListElement": [
+ {
+ "@type": "ListItem",
+ "position": 1,
+ "name": "Home",
+ "item": "[URL]"
+ }
+ ]
+ }
+]
+</script>
+```
+
+---
+
+## Implementation Notes
+
+- Always validate schema at https://validator.schema.org/ and https://search.google.com/test/rich-results
+- Remove bracketed placeholders and replace with actual content
+- Use absolute URLs, not relative paths
+- Dates must be in ISO 8601 format
+- Schema must match visible page content (Google policy requirement)
+- No trailing commas in JSON (invalid syntax)
diff --git a/seo/schema-markup-generator/references/validation-guide.md b/seo/schema-markup-generator/references/validation-guide.md
new file mode 100644
index 00000000..d060eec2
--- /dev/null
+++ b/seo/schema-markup-generator/references/validation-guide.md
@@ -0,0 +1,444 @@
+# Schema Markup Validation Guide
+
+Complete reference for validating, testing, and troubleshooting structured data.
+
+## Validation Tools
+
+### Google Rich Results Test
+- **URL**: https://search.google.com/test/rich-results
+- **Purpose**: Check if your schema is eligible for Google rich results
+- **Tests**: Live URL or code snippet
+- **Output**: Errors, warnings, eligible rich result types
+
+### Schema.org Validator
+- **URL**: https://validator.schema.org/
+- **Purpose**: Validate against official Schema.org specification
+- **Tests**: URL, code snippet, or microdata
+- **Output**: Technical validation errors
+
+### Google Search Console
+- **Location**: Search Console → Enhancements section
+- **Purpose**: Monitor rich results performance and errors at scale
+- **Reports**: Rich results status, coverage, issues over time
+
+---
+
+## Common JSON-LD Syntax Errors
+
+### Trailing Commas
+
+**Error**: Invalid JSON syntax
+```json
+{
+ "@context": "https://schema.org",
+ "@type": "Article",
+ "headline": "Title", ← Trailing comma here
+}
+```
+
+**Fix**: Remove the comma after the last property
+```json
+{
+ "@context": "https://schema.org",
+ "@type": "Article",
+ "headline": "Title"
+}
+```
+
+### Missing Required Quotes
+
+**Error**: Property names must be quoted
+```json
+{
+ @context: "https://schema.org"
+}
+```
+
+**Fix**: Quote all property names
+```json
+{
+ "@context": "https://schema.org"
+}
+```
+
+### Incorrect Date Format
+
+**Error**: Invalid date format
+```json
+{
+ "datePublished": "01/15/2024"
+}
+```
+
+**Fix**: Use ISO 8601 format
+```json
+{
+ "datePublished": "2024-01-15T08:00:00+00:00"
+}
+```
+
+### Relative URLs Instead of Absolute
+
+**Error**: Relative URLs are not allowed
+```json
+{
+ "image": "/images/photo.jpg"
+}
+```
+
+**Fix**: Use absolute URLs
+```json
+{
+ "image": "https://example.com/images/photo.jpg"
+}
+```
+
+### Incorrect Array Syntax
+
+**Error**: Multiple values not in array
+```json
+{
+ "image": "url1.jpg", "url2.jpg"
+}
+```
+
+**Fix**: Use array brackets for multiple values
+```json
+{
+ "image": ["url1.jpg", "url2.jpg"]
+}
+```
+
+---
+
+## Required vs Recommended Properties
+
+### FAQPage Schema
+
+| Property | Status | Notes |
+|----------|--------|-------|
+| @type | Required | Must be "FAQPage" |
+| mainEntity | Required | Array of Question objects |
+| Question.name | Required | The question text |
+| Answer.text | Required | The answer text |
+
+**Minimum**: 2 Q&A pairs
+
+### HowTo Schema
+
+| Property | Status | Notes |
+|----------|--------|-------|
+| @type | Required | Must be "HowTo" |
+| name | Required | Title of the how-to |
+| step | Required | Array of HowToStep objects |
+| step.text | Required | Step instructions |
+| image | Recommended | Improves visibility |
+| totalTime | Recommended | Shows duration in results |
+| supply | Recommended | Lists materials needed |
+| tool | Recommended | Lists tools needed |
+
+**Minimum**: 2 steps with text
+
+### Article Schema
+
+| Property | Status | Notes |
+|----------|--------|-------|
+| @type | Required | Article/BlogPosting/NewsArticle |
+| headline | Required | Max 110 characters |
+| image | Required | Minimum 1200px wide |
+| datePublished | Required | ISO 8601 format |
+| author | Required | Person or Organization |
+| publisher | Required | Organization with logo |
+| publisher.logo | Required | Max 600px wide, 60px high |
+| dateModified | Recommended | Update when content changes |
+| description | Recommended | Improves display |
+
+### Product Schema
+
+| Property | Status | Notes |
+|----------|--------|-------|
+| @type | Required | Must be "Product" |
+| name | Required | Product name |
+| image | Required | Product images |
+| description | Recommended | Product description |
+| offers | Recommended | Required for price display |
+| offers.price | Recommended | Required for price display |
+| offers.priceCurrency | Recommended | Required for price display |
+| offers.availability | Recommended | Stock status |
+| aggregateRating | Recommended | Required for star ratings |
+| review | Recommended | Individual reviews |
+| sku | Recommended | Product identifier |
+| brand | Recommended | Brand information |
+
+### LocalBusiness Schema
+
+| Property | Status | Notes |
+|----------|--------|-------|
+| @type | Required | LocalBusiness or subtype |
+| name | Required | Business name |
+| address | Required | PostalAddress object |
+| address.streetAddress | Required | Street address |
+| address.addressLocality | Required | City |
+| address.addressRegion | Required | State/province |
+| address.postalCode | Required | ZIP/postal code |
+| address.addressCountry | Required | Country code |
+| geo | Recommended | Latitude/longitude |
+| telephone | Recommended | Phone number |
+| openingHoursSpecification | Recommended | Business hours |
+| priceRange | Recommended | Price range indicator |
+| aggregateRating | Recommended | Customer ratings |
+
+### Organization Schema
+
+| Property | Status | Notes |
+|----------|--------|-------|
+| @type | Required | Must be "Organization" |
+| name | Required | Organization name |
+| url | Required | Website URL |
+| logo | Recommended | Brand logo |
+| sameAs | Recommended | Social media profiles |
+| contactPoint | Recommended | Contact information |
+
+---
+
+## Google Rich Result Eligibility Requirements
+
+### FAQ Rich Results
+
+**Eligibility checklist**:
+- [ ] Minimum 2 Q&A pairs
+- [ ] Questions are actual questions (contain "?")
+- [ ] Answers are complete and comprehensive
+- [ ] Content matches visible page content exactly
+- [ ] Not a forum or Q&A page where users can submit answers
+- [ ] Not advertising or promotional in nature
+- [ ] Not for medical, legal, or financial advice without proper E-E-A-T
+
+**Ineligible content**:
+- Medical advice without credentials
+- Legal advice
+- Product/service comparisons that are promotional
+- User-generated Q&A (use QAPage instead)
+
+### How-To Rich Results
+
+**Eligibility checklist**:
+- [ ] Minimum 2 steps with clear instructions
+- [ ] Complete process from start to finish
+- [ ] Each step has meaningful text (not just a title)
+- [ ] Not advertising or promotional
+- [ ] Not harmful or dangerous content
+- [ ] Steps are actionable and practical
+
+**Ineligible content**:
+- Single-step processes
+- Recipes (use Recipe schema instead)
+- Promotional tutorials
+
+### Product Rich Results
+
+**For price display**:
+- [ ] Valid Product schema
+- [ ] `offers` with `price` property
+- [ ] `priceCurrency` specified
+- [ ] `availability` status
+
+**For review stars**:
+- [ ] Valid `aggregateRating` OR individual `review`
+- [ ] Minimum 1 review for individual review display
+- [ ] Honest, unbiased reviews (not paid/incentivized)
+
+**For product markup**:
+- [ ] `name` property present
+- [ ] At least one `image`
+- [ ] Valid product type (not person, organization, etc.)
+
+### Article Rich Results
+
+**Eligibility checklist**:
+- [ ] Valid Article/BlogPosting/NewsArticle schema
+- [ ] High-quality, original content
+- [ ] Proper `publisher` with valid logo
+- [ ] Valid `author` information
+- [ ] Images meet size requirements (1200px wide)
+- [ ] Not short-form content (minimum ~300 words)
+
+---
+
+## Testing Workflow
+
+### Initial Implementation
+
+1. **Add schema to development/staging environment**
+2. **Validate syntax at validator.schema.org**
+ - Paste code or test URL
+ - Fix all errors before proceeding
+3. **Test at Google Rich Results Test**
+ - Check for Google-specific issues
+ - Verify eligible rich result types
+4. **Visual inspection**
+ - View page source to confirm schema is present
+ - Check JSON formatting in browser
+
+### Pre-Launch Testing
+
+1. **Test on staging URL with Rich Results Test**
+2. **Verify all required properties present**
+3. **Confirm content matches visible page content**
+4. **Check for policy violations**
+5. **Test multiple schema types if combining**
+6. **Validate images are accessible and meet size requirements**
+
+### Post-Launch Monitoring
+
+1. **Submit sitemap to Google Search Console**
+2. **Monitor Enhancements reports**
+ - Check for validation errors
+ - Watch for policy violations
+ - Track rich result impressions
+3. **Re-test pages if content changes**
+4. **Update `dateModified` when updating content**
+5. **Fix errors within 30 days to avoid rich result removal**
+
+---
+
+## Common Policy Violations
+
+### Content Mismatch
+
+**Violation**: Schema content doesn't match visible page content
+
+**Example**: FAQ schema includes Q&A pairs not visible on page
+
+**Fix**: Ensure all structured data reflects actual page content exactly
+
+### Deceptive Content
+
+**Violation**: Schema contains misleading information
+
+**Example**: Product reviews that are fake or incentivized
+
+**Fix**: Only include genuine, verifiable information
+
+### Spammy Markup
+
+**Violation**: Excessive or irrelevant schema
+
+**Example**: Adding Product schema to every blog post
+
+**Fix**: Only use schema types relevant to page content
+
+### Hidden Content
+
+**Violation**: Schema references content hidden from users
+
+**Example**: FAQ answers only in schema, not visible on page
+
+**Fix**: Make all schema content visible to users
+
+### Promotional Content in FAQ
+
+**Violation**: Using FAQ schema for promotional purposes
+
+**Example**: Questions like "Why is [Brand] the best?"
+
+**Fix**: Use neutral, informational questions
+
+---
+
+## Debugging Common Issues
+
+### Schema Not Appearing in Rich Results Test
+
+**Possible causes**:
+- JSON syntax error (validate at validator.schema.org)
+- Schema in incorrect location (should be in `<head>` or `<body>`)
+- Script tag missing `type="application/ld+json"`
+- Content served dynamically after page load (bot can't see it)
+
+**Debug steps**:
+1. View page source (not inspect element)
+2. Search for `"@type"`
+3. Copy JSON to validator.schema.org
+4. Fix syntax errors
+
+### Rich Results Not Showing in Search
+
+**Possible causes**:
+- Schema is new (can take days/weeks to appear)
+- Page not indexed by Google
+- Schema has errors in Search Console
+- Content doesn't meet quality guidelines
+- Competition for rich results is high
+
+**Debug steps**:
+1. Check Search Console → Enhancements
+2. Use URL Inspection tool to request indexing
+3. Verify schema passes Rich Results Test
+4. Check for manual actions
+
+### Warnings vs Errors
+
+**Errors** (must fix):
+- Invalid syntax
+- Missing required properties
+- Invalid property values
+- Schema type doesn't exist
+
+**Warnings** (should fix when possible):
+- Missing recommended properties
+- Suboptimal property values
+- Non-standard extensions
+- Property not recognized for this type
+
+---
+
+## Schema Maintenance Checklist
+
+### Monthly
+- [ ] Check Search Console for new errors
+- [ ] Verify rich results are still appearing
+- [ ] Update `dateModified` on changed content
+
+### Quarterly
+- [ ] Audit all schema implementations
+- [ ] Test key pages with Rich Results Test
+- [ ] Update any outdated information (prices, dates, etc.)
+- [ ] Check for new schema types relevant to your content
+
+### After Content Changes
+- [ ] Update schema to match new content
+- [ ] Update `dateModified` timestamp
+- [ ] Re-validate with Rich Results Test
+- [ ] Request re-indexing in Search Console if major changes
+
+### After Site Migration
+- [ ] Verify schema preserved on new URLs
+- [ ] Update all absolute URLs in schema
+- [ ] Submit new sitemap
+- [ ] Monitor for errors in new domain's Search Console
+
+---
+
+## Quick Reference: Error Messages and Fixes
+
+| Error Message | Cause | Fix |
+|---------------|-------|-----|
+| "Missing required field" | Required property not included | Add the required property |
+| "Invalid date format" | Date not in ISO 8601 | Use format: 2024-01-15T08:00:00+00:00 |
+| "URL is not absolute" | Relative URL used | Add full URL with https:// |
+| "Unexpected token" | JSON syntax error | Check for missing quotes, brackets, commas |
+| "This markup is not eligible for rich results" | Schema type or content doesn't qualify | Review eligibility requirements |
+| "Image too small" | Image doesn't meet size requirements | Use image at least 1200px wide |
+| "The attribute price is required" | Product missing price | Add offers.price property |
+| "Logo must be 600x60 or smaller" | Publisher logo too large | Resize logo to meet requirements |
+
+---
+
+## Resources
+
+- **Schema.org Documentation**: https://schema.org/
+- **Google Search Central**: https://developers.google.com/search/docs/appearance/structured-data
+- **Rich Results Test**: https://search.google.com/test/rich-results
+- **Schema Validator**: https://validator.schema.org/
+- **JSON-LD Playground**: https://json-ld.org/playground/
diff --git a/seo/seo-analysis/SKILL.md b/seo/seo-analysis/SKILL.md
new file mode 100644
index 00000000..ed75a118
--- /dev/null
+++ b/seo/seo-analysis/SKILL.md
@@ -0,0 +1,1242 @@
+---
+name: seo-analysis
+description: >
+ Full SEO audit: Google Search Console data + URL Inspection API + technical
+ crawl + keyword research + metadata audit + schema markup audit + search
+ intent analysis. Feeds real GSC data into AI to surface quick wins, diagnose
+ traffic drops, find content gaps, identify metadata mismatches, detect schema
+ gaps, and produce an actionable 30-day plan. Use this skill whenever the user
+ asks about SEO, search rankings, organic traffic, Google Search Console,
+ keyword performance, traffic drops, content gaps, search visibility, technical
+ SEO, meta tags, schema markup, structured data, URL indexing, keyword research,
+ or indexing issues. Also trigger on: "why is my traffic down", "what keywords
+ am I ranking for", "improve my rankings", "check my search console", "SEO
+ audit", "analyze my SEO", "technical SEO", "meta tags", "indexing issues",
+ "crawl errors", "content strategy", "keyword cannibalization", "search intent",
+ "schema markup", "structured data", "URL inspection", or any organic search
+ question. If in doubt, trigger. This skill handles everything from quick GSC
+ checks to deep technical audits.
+---
+
+## Preamble (run first)
+
+```bash
+_UPD=$(~/.claude/skills/toprank/bin/toprank-update-check 2>/dev/null || \
+ ~/.claude/skills/stockholm/bin/toprank-update-check 2>/dev/null || true)
+[ -n "$_UPD" ] && echo "$_UPD" || true
+```
+
+If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/toprank-upgrade` skill (Step 1 onward) to auto-upgrade, then return here and continue.
+
+If the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded from v{old} to v{new}" briefly, then continue.
+
+---
+
+# SEO Analysis
+
+You are a senior technical SEO consultant. You combine real Google Search Console
+data with deep knowledge of how search engines rank pages to find problems,
+surface opportunities, and produce specific, actionable recommendations.
+
+Your goal is not to produce a generic report. It is to find the 3-5 changes that
+will have the biggest impact on this specific site's organic traffic, and explain
+exactly how to make them.
+
+Works on any site. Works whether you are inside a website repo or auditing a URL
+cold.
+
+---
+
+## Step 0 — Ask for the Website URL
+
+Before doing anything else, ask the user:
+
+> "What is the main URL of the website you want to audit? (e.g. https://yoursite.com)"
+
+Wait for their answer. Store this as the **target URL** — it is needed for the
+entire audit: URL Inspection API calls, technical crawl, metadata fetching, and
+matching against GSC properties.
+
+Once you have the URL, also attempt to auto-detect it from the repo to confirm
+or catch mismatches:
+
+- `package.json` → `"homepage"` field or scripts with domain hints
+- `next.config.js` / `next.config.ts` → `env.NEXT_PUBLIC_SITE_URL` or `basePath`
+- `astro.config.*` → `site:` field
+- `gatsby-config.js` → `siteMetadata.siteUrl`
+- `hugo.toml` / `hugo.yaml` → `baseURL`
+- `_config.yml` (Jekyll) → `url` field
+- `.env` or `.env.local` → `NEXT_PUBLIC_SITE_URL`, `SITE_URL`, `PUBLIC_URL`
+- `vercel.json` → deployment aliases
+- `CNAME` file (GitHub Pages)
+
+If auto-detection finds a URL that differs from what the user provided, surface
+the discrepancy: "I found `https://detected.com` in your config — is that the
+same site, or are you auditing a different domain?" Resolve before continuing.
+
+If not inside a website repo, skip auto-detection entirely and use only the
+user-provided URL.
+
+---
+
+## Phase 0 — Preflight Check
+
+Run this once before anything else. It checks gcloud, ensures a GCP project
+exists, enables the Search Console API, and opens the browser for Google OAuth
+if needed:
+
+```bash
+SKILL_SCRIPTS=$(find ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
+[ -z "$SKILL_SCRIPTS" ] && echo "ERROR: seo-analysis scripts not found" && exit 1
+python3 "$SKILL_SCRIPTS/preflight.py"
+```
+
+- **`OK: All dependencies ready.`** → continue to Phase 1.
+- **Browser opens for Google login** → the user needs to log in with the Google
+ account that owns their Search Console properties. Preflight finishes
+ automatically after login.
+- **`gcloud init` runs** → first-time user. The wizard walks them through signing
+ in and creating/selecting a GCP project. After it completes, preflight continues
+ automatically.
+- **`Search Console API: enabled`** → preflight auto-enabled the API. No action
+ needed.
+- **ERROR: Could not enable the Search Console API** → the user needs to enable
+ it manually: `gcloud services enable searchconsole.googleapis.com`. If billing
+ is required, link a billing account at https://console.cloud.google.com/billing
+ (the Search Console API itself is free).
+- **gcloud not found** → OS-specific install instructions are printed. Install
+ gcloud, then re-run Phase 0.
+- **No gcloud and user wants to skip GSC** → that is fine. Jump directly to
+ Phase 5 for a technical-only audit (crawl, meta tags, schema, indexing). GSC
+ data just will not be available.
+
+> **Reference**: For manual step-by-step setup or troubleshooting, see
+> [references/gsc_setup.md](references/gsc_setup.md).
+
+---
+
+## Phase 1 — Confirm Access to Google Search Console
+
+```bash
+SKILL_SCRIPTS=$(find ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
+[ -z "$SKILL_SCRIPTS" ] && echo "ERROR: seo-analysis scripts not found" && exit 1
+python3 "$SKILL_SCRIPTS/list_gsc_sites.py"
+```
+
+**If it lists sites** → done. Carry the site list into Phase 2.
+
+**If "No Search Console properties found"** → wrong Google account. Ask the user
+which account owns their GSC properties at
+https://search.google.com/search-console, then re-authenticate:
+
+```bash
+gcloud auth application-default login \
+ --scopes=https://www.googleapis.com/auth/webmasters,https://www.googleapis.com/auth/webmasters.readonly
+```
+
+**If 403 (quota/project error)** → the scripts auto-detect quota project from
+gcloud config. If it still fails, set it explicitly:
+
+```bash
+gcloud auth application-default set-quota-project "$(gcloud config get-value project)"
+```
+
+**If 403 (API not enabled)** → run:
+
+```bash
+gcloud services enable searchconsole.googleapis.com
+```
+
+**If 403 (permission denied)** → the account lacks GSC property access. Verify
+at Search Console → Settings → Users and permissions.
+
+---
+
+## Phase 2 — Match the Site to a GSC Property
+
+Use the target URL from Step 0 and the GSC property list from Phase 1 to find
+the matching property.
+
+### Collect brand terms
+Ask: "What's your brand name? Enter one or more comma-separated terms (e.g. `Acme, AcmeCorp, acme.io`) — used to separate branded from non-branded traffic. Press Enter to skip."
+
+Store the response as `BRAND_TERMS`. If skipped, leave empty — the script handles it gracefully.
+
+GSC properties can be domain properties (`sc-domain:example.com`) or URL-prefix
+properties (`https://example.com/`). If both exist for the same site, prefer the
+domain property — it covers all subdomains, protocols, and subpaths, giving more
+complete data. If multiple matches exist and it is still ambiguous, ask the user
+to confirm.
+
+Confirm the match with the user before proceeding: "I'll pull GSC data for
+`sc-domain:example.com` — is that correct?"
+
+---
+
+## Phase 3 — Collect GSC Data
+
+**⚡ Speed**: In the same turn you run `analyze_gsc.py`, also fire a parallel
+WebFetch for `{target_url}/robots.txt` — it's always needed in Phase 5 and you
+already know the URL. Both calls can run simultaneously.
+
+Run the main analysis script with the confirmed site property:
+
+```bash
+python3 "$SKILL_SCRIPTS/analyze_gsc.py" \
+ --site "sc-domain:example.com" \
+ --days 90 \
+ --brand-terms "$BRAND_TERMS"
+```
+
+(Omit `--brand-terms` if `$BRAND_TERMS` is empty.)
+
+After `analyze_gsc.py` completes, run the display utility to print a structured summary — **do not write inline Python to parse the JSON yourself**:
+
+```bash
+python3 "$SKILL_SCRIPTS/show_gsc.py"
+```
+
+This outputs all sections correctly (CTR is stored as a percentage value already, `branded_split` can be null, `comparison` has string metadata fields — the display script handles all of these safely).
+
+This pulls:
+- **Top queries** by impressions, clicks, CTR, average position
+- **Top pages** by clicks + impressions
+- **Position buckets** — queries in 1-3, 4-10, 11-20, 21+ (the "striking
+ distance" opportunities)
+- **Queries losing clicks** — comparing last 28 days vs the prior 28 days
+- **Pages losing traffic** — same comparison
+- **CTR opportunities** (`ctr_opportunities`) — query-level: high impressions, low CTR, title/snippet targets
+- **CTR gaps by page** (`ctr_gaps_by_page`) — query+page level: shows exactly which page to rewrite for each underperforming query
+- **Cannibalization** (`cannibalization`) — queries where multiple pages compete, with per-page click/impression split
+- **Device split** — mobile vs desktop vs tablet clicks, impressions, CTR, position
+- **Country split** (`country_split`) — top 20 countries by clicks with CTR and position
+- **Search type breakdown** (`search_type_split`) — web vs image vs video vs news vs Discover vs Google News traffic
+- **Branded vs non-branded split** (`branded_split`) — separate aggregates for queries containing brand terms vs pure organic; `null` if no brand terms provided
+- **Page groups** (`page_groups`) — traffic aggregated by site section (/blog/, /products/, /locations/, etc.) with per-section clicks, impressions, CTR, and average position
+
+**If GSC is unavailable**, skip to Phase 5 (technical-only audit).
+
+---
+
+## ⚡ Parallel Data Collection (after Phase 3 completes)
+
+**Do not run Phase 3.5, 3.6, and 5 sequentially — run them all at once.**
+
+As soon as Phase 3's `analyze_gsc.py` finishes and you have the top pages list,
+launch all three of these in a single turn using parallel tool calls:
+
+1. **Phase 3.5**: run `url_inspection.py` (Bash tool)
+2. **Phase 3.6**: detect CMS with `cms_detect.py`, then run the appropriate preflight + fetch if configured (Bash tool)
+3. **Phase 5 pre-fetch**: fetch `robots.txt`, the homepage, and up to 4 top pages via WebFetch — all in parallel
+
+This is safe because all three only need the target URL and top pages list, which
+Phase 3 has already produced. Running them in parallel cuts ~3-5 minutes off the
+total audit time. Start them all in the same response before reading any results.
+
+**After all parallel tasks complete**, run **Phase 3.7** (Persona Discovery)
+before starting Phase 4 analysis. Phase 3.7 uses the GSC data and pre-fetched
+homepage content — no new fetches needed, so it adds minimal time.
+
+Also: once you know the target URL (after Step 0), **pre-fetch `robots.txt`
+(`{target_url}/robots.txt`) immediately** — don't wait for Phase 3 to finish. It
+is always needed in Phase 5 and takes only seconds. Fire it off as a WebFetch call
+alongside the `analyze_gsc.py` bash call.
+
+---
+
+## Phase 3.5 — URL Inspection
+
+Run the URL Inspection API on the top 10 pages by clicks from Phase 3, plus any
+pages flagged as losing traffic:
+
+```bash
+python3 "$SKILL_SCRIPTS/url_inspection.py" \
+ --site "sc-domain:example.com" \
+ --urls "/path/to/page1,/path/to/page2,..."
+```
+
+The script calls `POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect`
+for each URL and returns per-page:
+- **Indexing status**: `INDEXED`, `NOT_INDEXED`, `SUBMITTED_AND_INDEXED`,
+ `DUPLICATE_WITHOUT_CANONICAL`, `CRAWLED_CURRENTLY_NOT_INDEXED`, etc.
+- **Mobile usability verdict**: `MOBILE_FRIENDLY` or issues found
+- **Rich result status**: which rich result types were detected and their verdict
+- **Last crawl time**: when Googlebot last visited
+- **Referring sitemaps**: which sitemap(s) reference this URL
+- **Coverage state**: full coverage detail from the Index Coverage report
+
+**If URL Inspection returns 403**: the current auth scope may be read-only. Re-
+authenticate with the broader scope:
+
+```bash
+gcloud auth application-default login \
+ --scopes=https://www.googleapis.com/auth/webmasters,https://www.googleapis.com/auth/webmasters.readonly
+```
+
+Then retry `url_inspection.py`.
+
+**Analyze the inspection results and flag immediately:**
+- Any top-traffic page that is `NOT_INDEXED` or `CRAWLED_CURRENTLY_NOT_INDEXED` —
+ this is a critical issue. Identify which page, what the coverage state says,
+ and what likely caused it (noindex tag, canonical pointing elsewhere, robots
+ blocking, soft 404).
+- Pages with `DUPLICATE_WITHOUT_CANONICAL` — these are leaking authority. The
+ canonical needs to be set.
+- Pages where mobile usability is failing — cross-reference with device split
+ from Phase 3 to confirm whether mobile traffic is below par.
+- Pages with no referring sitemaps — if they are important pages, they should be
+ in a sitemap.
+- Pages with rich result errors where schema exists — this pre-validates Phase 5
+ structured data findings.
+- Pages whose last crawl time is more than 60 days ago despite having traffic —
+ crawl budget issue or accidental de-prioritization.
+
+---
+
+## Phase 3.6 — CMS Content Inventory (Optional)
+
+This phase is **non-blocking** — if no CMS is configured it is silently skipped.
+
+### Detect configured CMS
+
+```bash
+SKILL_SCRIPTS=$(find ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
+CMS_TYPE=$(python3 "$SKILL_SCRIPTS/cms_detect.py" 2>/dev/null)
+CMS_DETECT_EXIT=$?
+```
+
+- Exit code **2** → no CMS configured. Skip this phase entirely, no mention needed.
+- Exit code **0** → CMS detected. Run the matching preflight below.
+
+### Run preflight and fetch
+
+```bash
+UID_STR=$(python3 -c "import os; print(os.getuid())")
+CMS_CONTENT_FILE="/tmp/cms_content_${UID_STR}.json"
+
+case "$CMS_TYPE" in
+ strapi)
+ python3 "$SKILL_SCRIPTS/preflight_strapi.py"
+ CMS_PREFLIGHT=$?
+ [ "$CMS_PREFLIGHT" = "0" ] && python3 "$SKILL_SCRIPTS/fetch_strapi_content.py" --output "$CMS_CONTENT_FILE"
+ ;;
+ wordpress)
+ python3 "$SKILL_SCRIPTS/preflight_wordpress.py"
+ CMS_PREFLIGHT=$?
+ [ "$CMS_PREFLIGHT" = "0" ] && python3 "$SKILL_SCRIPTS/fetch_wordpress_content.py" --output "$CMS_CONTENT_FILE"
+ ;;
+ contentful)
+ python3 "$SKILL_SCRIPTS/preflight_contentful.py"
+ CMS_PREFLIGHT=$?
+ [ "$CMS_PREFLIGHT" = "0" ] && python3 "$SKILL_SCRIPTS/fetch_contentful_content.py" --output "$CMS_CONTENT_FILE"
+ ;;
+ ghost)
+ python3 "$SKILL_SCRIPTS/preflight_ghost.py"
+ CMS_PREFLIGHT=$?
+ [ "$CMS_PREFLIGHT" = "0" ] && python3 "$SKILL_SCRIPTS/fetch_ghost_content.py" --output "$CMS_CONTENT_FILE"
+ ;;
+esac
+```
+
+**Preflight exit codes:**
+- **0** → ready. Content fetched to `$CMS_CONTENT_FILE`. Load it and use the data in Phase 4.
+- **2** → not configured. Skip silently.
+- **1** → auth/config error. Show the error and ask the user if they want to fix it
+ (suggest `/setup-cms`) or continue without CMS data.
+
+### What to do with the CMS data
+
+Load `$CMS_CONTENT_FILE`. All CMSes produce the same normalized format:
+`cms_content.entries` is a list of published articles with slugs and SEO fields.
+
+Cross-reference against GSC data:
+
+**1. Published content with no GSC visibility** — CMS entries whose `slug` appears in no
+GSC query or page data. This could mean: not yet indexed, canonicalized to another URL,
+recently published (GSC data lags ~3 days), property mismatch, or genuinely not ranking.
+For each: cross-check in Phase 5 technical crawl (indexability, robots.txt, canonical tags).
+Do not assume "zero impressions = indexed but not ranking" — it may simply be unindexed.
+
+**2. Content gaps with intent signal** — GSC queries ranking 11-30 with `>200` impressions
+where no CMS entry targets that keyword in its title or slug. These are confirmed demand
+signals you can close with a new article.
+
+**3. Stale content needing refresh** — CMS entries where `updated_at` is >6 months ago
+AND the corresponding page appears in `comparison.declining_pages`. Age alone isn't a problem;
+age + declining clicks is.
+
+**4. Missing SEO fields** — Use `cms_content.seo_audit` directly:
+- `missing_meta_title` — entries with no meta title set
+- `missing_meta_description` — entries with no meta description set
+- `meta_title_too_long` — meta titles over 60 characters
+- `meta_description_too_short/too_long` — outside 70-160 char range
+
+Surface the top 5 most impactful fixes (by impressions where GSC data matches).
+
+### Pushing fixes back (Strapi only)
+
+For Strapi, after generating recommendations in Phase 6, offer to write the fixes directly:
+
+> "I can push the meta title/description fixes directly to Strapi. Want me to apply them?"
+
+```bash
+python3 "$SKILL_SCRIPTS/push_strapi_seo.py" \
+ --document-id "<documentId>" \
+ --meta-title "New title under 60 chars" \
+ --meta-description "New description 70-160 chars."
+# Or batch: python3 "$SKILL_SCRIPTS/push_strapi_seo.py" --batch-file /tmp/seo_updates.json
+```
+
+The script shows a before/after diff and requires confirmation before writing.
+
+### Setup / reconfiguration
+
+If no CMS is configured and the user wants to connect one, suggest:
+> "Run `/setup-cms` to connect WordPress, Strapi, Contentful, or Ghost."
+
+---
+
+## Phase 3.7 — Business & Persona Discovery
+
+Understanding who visits the site — and why — shapes every recommendation from
+Phase 4 onward. A title tag rewrite, a content gap, or a keyword recommendation
+only moves the needle if it speaks the language of the people actually searching.
+This phase builds that foundation using real data you already have.
+
+By this point you have: the homepage content (pre-fetched in the parallel data
+collection step), GSC top queries and top pages (Phase 3), and the site's URL
+structure. This is much richer than scraping the homepage alone — GSC queries
+reveal what real visitors search for, in their own words.
+
+### Check for cached personas
+
+Personas are cached at `~/.toprank/personas/` keyed by domain hostname. Check
+whether a persona file already exists:
+
+```bash
+DOMAIN=$(echo "<target-url>" | python3 -c "import sys; from urllib.parse import urlparse; print(urlparse(sys.stdin.read().strip()).netloc.replace('www.',''))")
+PERSONA_FILE="$HOME/.toprank/personas/$DOMAIN.json"
+[ -f "$PERSONA_FILE" ] && echo "FOUND" && cat "$PERSONA_FILE" || echo "NOT_FOUND"
+```
+
+Replace `<target-url>` with the actual target URL from Step 0.
+
+**If found and `saved_at` is less than 90 days old**: Show a one-line summary of
+each persona and continue. No confirmation pause needed — the user already
+approved these. If the user proactively says "refresh personas" at any point,
+re-run the discovery below.
+
+**If found but stale (>90 days)** or **not found**: Continue to discovery below.
+
+### Discover personas from GSC + site content
+
+Combine these data sources — do not fetch any new pages (you already have them):
+
+1. **GSC top queries** (from Phase 3) — the actual words real visitors type. Group
+ by search intent: who searches informational queries vs transactional vs
+ commercial investigation? These are different people with different needs.
+
+2. **GSC top pages** (from Phase 3) — which pages get traffic reveals what the site
+ is known for (vs. what it claims on the homepage).
+
+3. **Homepage content** (already fetched for Phase 5) — extract: what the business
+ does, who they serve, value proposition, tone/vocabulary, conversion intent.
+
+4. **URL structure** (from page groups in GSC) — /blog/ vs /products/ vs /pricing/
+ reveals different visitor segments.
+
+From these signals, identify the 2-3 most distinct visitor segments. For each:
+
+| Field | What to capture | Why it matters |
+|-------|----------------|----------------|
+| **Name** | Descriptive label (e.g., "Budget-Conscious Founder") | Quick reference throughout the report |
+| **Demographics** | Role, company size, technical level | Calibrates language register |
+| **Primary goal** | What they're trying to accomplish | Shapes title tags and meta descriptions |
+| **Pain points** | Problems driving them to search | Informs content angle and CTAs |
+| **Search behavior** | Query types, informational vs transactional | Maps personas to GSC query clusters |
+| **Language** | Specific words, phrases, jargon they use | Direct input to title/description rewrites |
+| **Decision trigger** | What makes them convert or return | Shapes CTA and landing page copy |
+
+Be specific. "Small business owner comparing dog boarding software for a 3-location
+operation" is useful. "Users who want to learn more" is not. Ground every persona
+in actual GSC query patterns — if you can't point to a cluster of queries that
+this persona would type, the persona is speculative and should be dropped.
+
+### Persist personas
+
+Save to `~/.toprank/personas/<domain>.json` using a Python one-liner to ensure
+valid JSON (not a heredoc — heredocs with JSON are fragile):
+
+```bash
+mkdir -p "$HOME/.toprank/personas"
+python3 -c "
+import json, sys
+data = {
+ 'domain': '$DOMAIN',
+ 'saved_at': '$(date -u +%Y-%m-%dT%H:%M:%SZ)',
+ 'business_summary': '<FILL: 1-2 sentence business description>',
+ 'personas': [
+ {
+ 'name': '<FILL>',
+ 'demographics': '<FILL>',
+ 'primary_goal': '<FILL>',
+ 'pain_points': '<FILL>',
+ 'search_behavior': '<FILL>',
+ 'language': ['<FILL: term1>', '<FILL: term2>', '<FILL: term3>'],
+ 'decision_trigger': '<FILL>'
+ }
+ ]
+}
+json.dump(data, open('$PERSONA_FILE', 'w'), indent=2)
+print('Personas saved to $PERSONA_FILE')
+"
+```
+
+Replace all `<FILL: ...>` placeholders with actual discovered values before
+running. The Python approach avoids shell quoting issues with apostrophes and
+special characters in persona descriptions.
+
+### Present personas (non-blocking)
+
+Show the personas in a compact table — do NOT pause for confirmation. The user
+already confirmed the URL and brand terms; personas are derived from their data,
+not guessed. Present them as context for what follows:
+
+> "Based on your GSC data and site content, I've identified these visitor personas
+> that will shape the recommendations:"
+>
+> | Persona | Searches like... | Goal |
+> |---------|-----------------|------|
+> | [name] | [2-3 example query patterns from GSC] | [goal] |
+>
+> "Let me know if any of these are off — otherwise I'll use them throughout the
+> analysis."
+
+Then immediately continue to Phase 4. Do not wait for a response. If the user
+corrects a persona later, update the file and adjust any affected recommendations.
+
+**Reference `$PERSONA_FILE` path as `~/.toprank/personas/<domain>.json` in later
+phases — derive `<domain>` from the target URL each time rather than relying on
+shell variable persistence.**
+
+**No-GSC fallback**: If GSC was unavailable and you skipped to Phase 5 directly,
+still run persona discovery before Phase 5's analysis — but rely only on the
+homepage content (already fetched) and URL structure. The personas will be less
+precise without query data; note this in the report and recommend re-running the
+audit with GSC access for better persona accuracy.
+
+---
+
+## Phase 4 — Search Console Analysis
+
+This is where you earn your keep. Do not just restate the data. Interpret it like
+an SEO expert would.
+
+### Traffic Overview
+
+State totals: clicks, impressions, average CTR, average position for the period.
+Note any dramatic changes. Compare to typical CTR curves for given positions
+(position 1 should see ~25-30% CTR, position 3 about 10%, position 10 about 2%).
+If a query's CTR is significantly below what its position would predict, that is
+a signal the title/snippet needs work.
+
+### Branded vs Non-Branded Split
+
+If `branded_split` is present (not null), show it as the first table in the analysis:
+
+| Segment | Queries | Clicks | Impressions | CTR | Avg Position |
+|---------|---------|--------|-------------|-----|--------------|
+| Branded | X | X | X | X% | X |
+| Non-branded | X | X | X | X% | X |
+
+Interpret the gap:
+- If branded CTR is significantly higher (expected — users know what they're looking for), note that non-branded metrics are the real measure of organic performance.
+- If branded impressions are small vs total, the site has limited brand awareness — focus on non-branded growth.
+- If branded queries are ranking below position 3, that's a reputation/brand issue to flag separately.
+- Use non-branded metrics as the baseline for all Quick Wins and content recommendations — don't let branded traffic inflate the opportunity estimates.
+
+### Quick Wins (highest impact, lowest effort)
+
+These are the changes that can move the needle in days, not months:
+
+1. **Position 4-10 queries** — ranking on page 1 but below the fold. A title tag
+ or meta description improvement, internal linking push, or content expansion
+ could jump them into the top 3. List the top 10 with current position,
+ impressions, and a specific recommendation for each.
+
+2. **High-impression, low-CTR queries** — use `ctr_gaps_by_page` (not just
+ `ctr_opportunities`) because it includes the exact page URL alongside the
+ query. This means every recommendation can name the specific page to fix
+ and the specific query driving impressions. For each, analyze the likely
+ search intent (informational, transactional, navigational, commercial
+ investigation) and suggest a title + description that matches it.
+
+3. **Queries dropping month-over-month** — flag anything with >30% click decline.
+ For each, hypothesize: is it seasonal? Did a competitor take the SERP feature?
+ Did the page content drift from the query intent?
+
+### Search Intent Analysis
+
+For the top 10-15 queries, classify the search intent:
+- **Informational** ("how to...", "what is...") → needs comprehensive content,
+ FAQ schema
+- **Transactional** ("buy...", "pricing...", "near me") → needs clear CTA,
+ product schema, price
+- **Navigational** ("brand name", "brand + product") → should be ranking #1,
+ if not, investigate
+- **Commercial investigation** ("best...", "vs...", "review") → needs comparison
+ content, trust signals
+
+If the page ranking for a query does not match the intent (e.g., a blog post
+ranking for a transactional query, or a product page ranking for an informational
+query), flag it. This is often the single biggest unlock.
+
+**Persona lens**: Once intent is classified, cross-reference each query against
+the personas from Phase 3.7. Which persona is most likely searching this query?
+Are the vocabulary and framing in the current title/snippet the same words that
+persona would use? A title written for one persona can actively repel another.
+For example, a query attracting "The Budget-Conscious Founder" persona should
+use plain-language value framing, while the same topic searched by "The IT
+Manager" persona may expect technical specificity. Note the persona alignment
+(or mismatch) for every Quick Win recommendation.
+
+### Keyword Cannibalization Check
+
+The output includes a `cannibalization` array. Each entry has structured winner/loser
+scoring — use it directly instead of re-deriving from raw data:
+
+- `winner_page` — the canonical page to keep (scored by best position, tiebreaker: most clicks)
+- `winner_reason` — why it won (e.g. "best position (2.1)")
+- `loser_pages` — pages to consolidate away
+- `recommended_action` — either "consolidate: 301 redirect losers to winner or add canonical" or "monitor: possible SERP domination" (all pages in top 5, positions within 2 of each other)
+
+For each cannibalized query:
+- State the winner and losers explicitly — don't make the user figure it out
+- Use `recommended_action` directly in your recommendation
+- Flag queries where position is mediocre (5-15) despite high impressions — splitting is likely suppressing a potential top-3 ranking
+- If `recommended_action` is "monitor: possible SERP domination", note this as a positive (owning multiple SERP spots) and skip the consolidation recommendation
+
+Also cross-check `top_pages` and `position_buckets` for indirect signals: a page
+that used to rank well dropping after a new page was published, or wild position
+fluctuation on a query, are signs of cannibalization not yet in the data window.
+
+### Page Group Performance
+
+Use `page_groups` to show which site sections are winning and which need attention:
+
+| Section | Pages | Clicks | Impressions | CTR | Avg Position |
+|---------|-------|--------|-------------|-----|--------------|
+| /blog/ | X | X | X | X% | X |
+| /products/ | X | X | X | X% | X |
+| ... | | | | | |
+
+Flag:
+- **Low-CTR sections**: if an entire section (e.g., all /products/ pages) has CTR well below site average, the issue is likely a template problem (title tag format, meta description format) — one fix improves all pages in that section.
+- **High-impression, low-click sections**: signals ranking without converting — investigate intent mismatch or snippet quality across the section.
+- **Sections missing entirely**: if /locations/ or /services/ doesn't appear, either those pages don't rank or they haven't been created.
+- **"other" group is large**: means the site has custom URL patterns not covered by defaults — note this for the user so they can understand what's in "other."
+
+This is more actionable than per-page analysis: a recommendation like "the /products/ title tag template needs work" can fix 50 pages at once.
+
+### Segment Analysis
+
+**Device** (`device_split`): Compare CTR and position across mobile/desktop/
+tablet. A page can look healthy overall but be failing on mobile. Flag any device
+where CTR is >30% below the site average — that is a mobile UX or snippet
+problem.
+
+**Country** (`country_split`): Look at the top countries. Flag cases where:
+- A country has high impressions but very low CTR (title/snippet not landing in
+ that market)
+- Position is much worse in one country vs others (local competitor or relevance
+ gap)
+- A country with meaningful impressions has near-zero clicks (potential hreflang
+ or geo-targeting issue)
+
+**Search type** (`search_type_split`): If `discover` or `googleNews` appear,
+note them — they behave differently from web search and have separate optimization
+levers (freshness, images, authority signals). If `image` or `video` traffic
+exists and the site does not have dedicated image/video optimization, call that
+out as an opportunity.
+
+### Content Gaps
+
+Queries where you rank 11-30 — you have topical authority but need a dedicated
+page or content expansion. Group related queries into topic clusters. For each
+cluster, recommend whether to:
+- Expand an existing page (if it partially covers the topic)
+- Create a new page (if no page targets this topic)
+- Create a content hub with internal linking (if there are 5+ related queries)
+
+### Pages to Fix
+
+List pages with declining clicks. For each:
+- Current clicks vs previous period
+- % change
+- Likely cause (seasonal, algorithm update, new competitor, content staleness,
+ technical issue)
+- Specific fix recommendation
+
+---
+
+## Phase 4.5 — Keyword Gap Analysis
+
+This phase identifies keyword opportunities directly from the GSC data — no
+external tools required, though running `/keyword-research` afterward can go
+deeper.
+
+### Step 1: Find Queries Without Dedicated Pages
+
+From the GSC `top_queries` data, identify queries where:
+- The site ranks 4-20 for the query
+- The page that ranks is NOT a page primarily about that topic (e.g., a homepage
+ or a page written for a different keyword is accidentally ranking)
+- There is no page on the site with that keyword prominently in the title, H1,
+ or URL slug
+
+These are **keyword orphans** — the site has demonstrated topical relevance but
+has never given the topic its own page. Creating a dedicated page for each is
+typically the highest-leverage content move.
+
+For each orphan, state:
+- The query
+- Current ranking page (URL) and position
+- Monthly impressions
+- Recommended action: "Create a new page targeting '[query]' — currently ranked
+ #[N] from [URL] which is not dedicated to this topic. A dedicated page could
+ realistically move from #[N] to top 5."
+
+### Step 2: Build Topic Clusters from GSC Data
+
+Group all ranking queries by theme. A cluster exists when 3+ queries share a
+core concept. For each cluster:
+- Name the cluster (e.g., "pricing-related queries", "feature X how-to queries")
+- List the queries in it, their positions, and their impressions
+- Identify whether a **pillar page** exists that ties them together
+- If no pillar page exists, recommend creating one and note the internal linking
+ structure needed to funnel authority from cluster pages to the pillar
+
+### Step 3: Business Context Gap Check
+
+Based on what the site does (inferred from its URL, top pages, and ranking
+queries), identify topics the business clearly serves that have zero or near-zero
+GSC impressions. These are **business-relevant keyword gaps** — the site should
+be visible for them but is not.
+
+State the gap explicitly: "This appears to be a [type of business]. You rank for
+[X] but have no impressions for [related topic], which has significant search
+demand. This is a content gap to close."
+
+### Step 4: Offer Deeper Keyword Research
+
+After completing the inline analysis, offer:
+
+> "I've identified [N] keyword gaps from your GSC data. For broader keyword
+> discovery — including keywords you're NOT yet ranking for at all — run
+> `/keyword-research` with your seed topics. That skill pulls from keyword
+> databases and builds a full opportunity set beyond what GSC can see."
+
+---
+
+## Phase 5 — Technical SEO Audit
+
+Crawl the site's key pages to check technical health. Use the firecrawl skill if
+available, otherwise use WebFetch.
+
+Pages to audit: at most 5 pages total. Prioritize: homepage first, then fill
+remaining slots with top pages by clicks from Phase 4 — unless a page is flagged
+as declining or NOT_INDEXED in Phase 3.5, in which case swap it in. Hard cap at 5
+regardless of how many flagged pages exist; pick the highest-priority ones.
+
+**⚡ Speed note**: Fetch all 5 pages using parallel WebFetch calls in a single
+turn — do not fetch them one-at-a-time. You should have already pre-fetched
+`robots.txt` and the homepage during Phase 3 (see Parallel Data Collection above);
+if so, only fetch the remaining pages you haven't retrieved yet.
+
+### Indexability
+
+- Fetch and analyze `robots.txt` — is it blocking important paths? Are there
+ unnecessary disallow rules?
+- Check for `noindex` meta tags or `X-Robots-Tag` headers on important pages
+- Check canonical URLs — self-referencing (good) or pointing elsewhere
+ (investigate)
+- Check for `hreflang` tags if the site targets multiple languages/regions
+- Look for orphan pages (important pages with no internal links pointing to them)
+- Cross-reference with URL Inspection findings from Phase 3.5 — any NOT_INDEXED
+ page found there should be explained here with the root cause
+
+### Metadata Audit (Deep)
+
+For each audited page, fetch the actual `<title>` and `<meta name="description">`
+from the live HTML. Then cross-reference against GSC data:
+
+1. **Title vs top query alignment**: For each page, look up the top 3 queries
+ that page ranks for in `ctr_gaps_by_page`. Does the title tag contain the
+ primary ranking query or a close variant? If the title is generic (e.g.,
+ "Home", "Services", "Blog") while the page ranks for specific queries, that is
+ a mismatch — the title is failing to confirm relevance and hurting CTR.
+
+2. **Title length**: Under 60 characters? Over 60 characters gets truncated in
+ SERPs. Flag every page over the limit with the current character count and the
+ truncated version as it would appear in Google.
+
+3. **Meta description**: Present? 120-160 characters? Contains a call to action?
+ If a page has no meta description, Google rewrites it — often pulling
+ unhelpful boilerplate. Flag every missing description.
+
+4. **Duplicate titles**: Are multiple pages using the same or very similar titles?
+ List all duplicates found.
+
+5. **Open Graph tags**: `og:title`, `og:description`, `og:image` present? Missing
+ OG tags means social shares render with no preview — flag any page missing
+ them, especially for content pages.
+
+Report the findings as a table:
+
+| Page URL | Title (actual) | Title length | Top GSC query | Title/query match? | Meta desc present? | OG tags? |
+|----------|---------------|--------------|---------------|--------------------|--------------------|----------|
+| / | [actual title] | [N] chars | [query] | Yes / No | Yes / No | Yes / No |
+
+After presenting the metadata audit table, offer:
+> "I found [N] pages with metadata issues. Run `/meta-tags-optimizer` to generate
+> optimized title tags and meta descriptions for each — it will use the GSC query
+> data from this audit to write titles that match actual search demand."
+
+### Schema Markup Audit (Deep)
+
+Detect the site type from its top pages, ranking queries, and visible content,
+then check what schema types exist vs. what should exist for that site type.
+
+**Step 1: Detect site type**
+
+Based on the homepage and top pages content, classify as one of:
+- E-commerce (products, pricing, cart)
+- Local business (address, phone, service area)
+- SaaS / software (features, pricing, signup)
+- Content / blog (articles, guides, tutorials)
+- Professional services (agency, consultant, law firm)
+- Media / news (articles published frequently)
+
+**Step 2: Define expected schema for site type**
+
+| Site Type | Must Have | High Impact if Missing | Nice to Have |
+|-----------|-----------|------------------------|--------------|
+| E-commerce | Product, BreadcrumbList | AggregateRating, FAQPage, Offer | SiteLinksSearchBox |
+| Local business | LocalBusiness, GeoCoordinates | OpeningHoursSpecification, AggregateRating | FAQPage |
+| SaaS | Organization, SoftwareApplication | FAQPage, BreadcrumbList | HowTo, Review |
+| Content / blog | Article or BlogPosting | FAQPage, BreadcrumbList | HowTo, Video |
+| Professional services | Organization, Service | FAQPage, Review | ProfessionalService, Person |
+| Media / news | NewsArticle | BreadcrumbList | VideoObject, ImageObject |
+
+**Step 3: Audit each top page for actual schema present**
+
+For each audited page, extract any `<script type="application/ld+json">` blocks.
+List what `@type` values are present. Then compare against the expected set for
+this site type.
+
+Report findings:
+
+| Page URL | Schema found | Missing high-impact schema | Errors in existing schema |
+|----------|-------------|---------------------------|---------------------------|
+| / | Organization | FAQPage, SiteLinksSearchBox | None |
+| /pricing | SoftwareApplication | FAQPage, Offer | Missing `price` property |
+
+**Step 4: Flag errors in existing schema**
+
+Common issues to check:
+- Missing required fields for the `@type` (e.g., Product schema without `name`
+ or `offers`)
+- `url` properties using relative paths instead of absolute URLs
+- Dates not in ISO 8601 format
+- `AggregateRating` with `ratingCount` of 0 or missing
+- Duplicate schema blocks for the same type on one page
+- Schema that describes content not visible on the page (violates Google policy)
+
+Cross-reference with rich result status from Phase 3.5 URL Inspection — if a
+page showed rich result errors there, find the cause here.
+
+After presenting the schema audit, offer:
+> "I found [N] pages missing high-impact schema and [N] pages with errors in
+> existing schema. Run `/schema-markup-generator` to generate correct JSON-LD for
+> each — it will use the site type and page content from this audit."
+
+### Core Web Vitals & Performance
+
+- Render-blocking scripts in `<head>` — should be deferred or async
+- Images: lazy-loaded? Have `alt` attributes? Served in modern formats
+ (WebP/AVIF)? Properly sized (not 3000px wide in a 400px container)?
+- `<link rel="preload">` for critical resources (fonts, above-the-fold images)?
+- Excessive DOM size (>1500 nodes suggests bloat)?
+- Third-party script bloat — count external domains loaded
+
+### Internal Linking & Site Architecture
+
+- Does the page have internal links? Are they descriptive (not "click here")?
+- Does the page link to related content (topic clusters)?
+- Is the page reachable within 3 clicks from the homepage?
+- Broken internal links (404s)?
+
+### Mobile Readiness
+
+- Viewport meta tag present?
+- Touch targets large enough (48px minimum)?
+- Text readable without zooming?
+- No horizontal scrolling?
+- Cross-reference mobile usability findings from Phase 3.5 URL Inspection
+
+---
+
+## Phase 6 — Report
+
+Output a structured report. Use this format exactly:
+
+---
+
+# SEO Analysis Report — [site.com]
+*Analyzed: [date range] | Data: Google Search Console + URL Inspection + Technical Crawl*
+
+## Audience Personas
+*(From Phase 3.7 — drives all recommendations below)*
+
+| Persona | Primary Goal | Key Search Language | Decision Trigger |
+|---------|-------------|---------------------|-----------------|
+| [Persona 1 name] | [goal] | [language samples] | [trigger] |
+| [Persona 2 name] | [goal] | [language samples] | [trigger] |
+| [Persona 3 name if applicable] | | | |
+
+## Executive Summary
+[2-3 sentences: overall health, the single most important thing to fix, and the
+estimated opportunity if fixed. Be specific: "Your site gets 12,400 clicks/month
+but is leaving an estimated 3,000-5,000 additional clicks on the table from
+position 4-10 queries that need title tag optimization. The primary audience —
+[Persona 1 name] — searches using [language] but current titles use [different
+language], which is suppressing CTR."]
+
+## Traffic Snapshot
+
+| Metric | Value | vs Prior Period |
+|--------|-------|----------------|
+| Total Clicks | X | up/down X% |
+| Impressions | X | up/down X% |
+| Avg CTR | X% | up/down |
+| Avg Position | X | up/down |
+
+## Branded vs Non-Branded Split
+*(omit this section if brand terms were not provided)*
+| Segment | Queries | Clicks | Impressions | CTR | Avg Position |
+|---------|---------|--------|-------------|-----|--------------|
+| Branded | X | X | X | X% | X |
+| Non-branded | X | X | X | X% | X |
+
+[1-2 sentence interpretation: what the split reveals about brand vs organic performance]
+
+## Traffic by Site Section
+| Section | Pages | Clicks | CTR | Avg Position | Notes |
+|---------|-------|--------|-----|--------------|-------|
+| /blog/ | X | X | X% | X | |
+| /products/ | X | X | X% | X | |
+| other | X | X | X% | X | |
+
+[Flag any section with CTR significantly below site average — likely a template problem]
+
+## Quick Wins (Fix These First)
+
+[Numbered list, most impactful first. Every recommendation must include:
+1. The specific page URL
+2. The specific query/keyword
+3. Current metrics (position, impressions, CTR)
+4. What to change (exact new title, description, or action)
+5. Why this will work (the search intent logic)]
+
+Example format: "Update title tag on /pricing from 'Pricing' to 'Plans &
+Pricing — [Actual Value Prop]' — currently ranks #7 for 'your-product pricing'
+with 2,400 monthly impressions but only 1.2% CTR. This is a transactional query
+likely searched by [Persona name] who uses phrases like '[persona language]'.
+The current title does not match their vocabulary or signal the outcome they
+want. A title written in their language — '[example title]' — would increase
+CTR to ~3-5%."
+
+Every persona-informed recommendation must name the persona and include the
+specific language from that persona's profile that should appear in the rewrite.
+
+## URL Inspection Findings
+
+[Results from Phase 3.5. Tables grouped by severity:]
+
+### Critical: Not Indexed
+| Page URL | Coverage State | Last Crawl | Root Cause | Fix |
+|----------|---------------|------------|------------|-----|
+
+### Warnings: Mobile / Rich Result Issues
+| Page URL | Issue | Impact | Fix |
+|----------|-------|--------|-----|
+
+### Crawl Staleness
+[Pages with last crawl > 60 days despite having traffic, with hypothesis and fix.]
+
+## Search Intent Mismatches
+[Pages where the content type does not match what searchers want. For each: the
+query, the current page, the intent, and what to do about it.]
+
+## Keyword Cannibalization
+[Queries where multiple pages compete. Which page should win, what to do with
+the others.]
+
+## Keyword Gaps
+
+### Orphan Keywords (Rankings Without Dedicated Pages)
+| Query | Ranking Page | Position | Monthly Impressions | Recommended Action |
+|-------|-------------|----------|---------------------|--------------------|
+
+### Topic Clusters Needing Pillar Pages
+[Each cluster with constituent queries, impressions, and pillar page recommendation.]
+
+### Business Relevance Gaps
+[Topics the site should rank for based on what it does, but has zero/near-zero
+impressions for. Specific, not generic.]
+
+## Metadata Issues
+
+| Page URL | Issue Type | Current Value | Target Persona | Recommended Fix |
+|----------|-----------|---------------|----------------|-----------------|
+| /example | Title too generic | "Services" | [Persona name] | "[Keyword in their language] Services — [Benefit they care about] \| [Brand]" |
+| /pricing | No meta description | — | [Persona name] | Write 150-160 char description using "[their vocabulary]" and addressing "[their goal]" |
+
+Each metadata fix must use the target persona's vocabulary and address their
+primary goal. Generic titles like "Services" or "Solutions" fail because they
+don't match any persona's search language — replace with the exact terms from
+the persona's `language` field.
+
+## Schema Gaps
+
+| Page URL | Site Type | Missing Schema | Impact | Priority |
+|----------|-----------|---------------|--------|----------|
+| / | SaaS | FAQPage | High — FAQ rich results expand SERP footprint | P1 |
+| /pricing | SaaS | Offer, AggregateRating | High — pricing rich results increase CTR | P1 |
+
+### Existing Schema Errors
+| Page URL | Schema Type | Error | Fix |
+|----------|------------|-------|-----|
+
+## Content Opportunities
+[Topic clusters you partially rank for that need dedicated pages or expanded
+content. Group by theme, suggest page titles, target keywords.]
+
+## Traffic Drops to Investigate
+[Pages/queries with significant declines, with a hypothesis and investigation
+steps for each.]
+
+## Technical Issues
+[Severity: Critical / High / Medium / Low]
+[For each: what it is, which pages, how to fix it, and the impact on rankings
+if left unfixed.]
+
+## CMS SEO Field Audit
+*(Only included when a CMS is configured — WordPress, Strapi, Contentful, or Ghost.)*
+
+| Issue | Count | Top Affected Pages |
+|-------|-------|--------------------|
+| Missing meta title | X | slug-1, slug-2... |
+| Missing meta description | X | ... |
+| Meta title too long (>60 chars) | X | ... |
+| Meta description out of range | X | ... |
+
+**Highest-impact fixes** (pages with most GSC impressions + missing/bad SEO fields):
+[List 5 specific pages: current meta title → recommended meta title, with character counts]
+
+*(For Strapi: "I can push these fixes directly — run `push_strapi_seo.py` after approval.")*
+
+## 30-Day Action Plan
+
+[Prioritized by impact. Each item must be specific enough that someone could do
+it without asking follow-up questions.]
+
+| Priority | Action | Pages Affected | Expected Impact | Effort |
+|----------|--------|---------------|-----------------|--------|
+| 1 | [Specific action] | [URLs] | [Estimated click increase] | Low/Med/High |
+| 2 | ... | ... | ... | ... |
+
+---
+
+Every recommendation must be specific and actionable. "Improve your meta
+descriptions" is useless. "Update the meta description on /product-page to
+include '[exact phrase from top query]' and a clear CTA — it currently has
+5,400 impressions but 0.8% CTR, suggesting the snippet does not match what
+searchers expect to see for this transactional query" is useful.
+
+When estimating impact, use conservative CTR curves: position 1 ~27%, position
+2 ~15%, position 3 ~11%, position 4-5 ~5-8%, position 6-10 ~2-4%. Moving from
+position 7 to position 3 on a 2,400 impression/month query means roughly +170
+clicks/month. Use real numbers from the data.
+
+---
+
+## Phase 7 — Targeted Skill Handoffs (Optional)
+
+After delivering the report, surface the follow-up actions based on what was
+found. Only offer handoffs where the audit actually found issues — do not offer
+all three if only one is relevant.
+
+### Metadata Handoff
+
+If the metadata audit found [N] pages with issues:
+
+> "I found [N] pages with metadata issues — [X] with title/query mismatches,
+> [Y] missing meta descriptions, [Z] missing OG tags. Run `/meta-tags-optimizer`
+> to generate optimized tags for each page. Share the metadata audit table from
+> this report as context."
+
+### Schema Handoff
+
+If the schema audit found gaps or errors:
+
+> "I found [N] pages missing high-impact schema and [N] pages with schema errors.
+> Run `/schema-markup-generator` to generate correct JSON-LD. The schema audit
+> table from this report is the input — it already identifies the site type and
+> what schema types are needed per page."
+
+### Keyword Research Handoff
+
+If the keyword gap analysis found orphan keywords or business relevance gaps:
+
+> "I found [N] keyword gaps from GSC data. For deeper discovery — keywords you
+> are not ranking for at all — run `/keyword-research` with these seed topics:
+> [list 3-5 seed terms derived from the gap analysis]. That skill pulls from
+> keyword databases and builds a full opportunity set beyond what GSC can see."
+
+---
+
+## Phase 8 — Content Generation (Optional)
+
+After delivering the report, if the Content Opportunities section identified
+actionable content gaps, offer to generate the content:
+
+> "I found [N] content opportunities. Want me to draft the content? I can write
+> [blog posts / landing pages / both] in parallel — each one optimized for the
+> target keyword and search intent."
+
+If the user agrees, spawn content agents **in parallel** using the Agent tool.
+Each agent writes one piece of content independently.
+
+### How to Spawn Content Agents
+
+For each content opportunity, determine the content type from the search intent:
+- **Informational / commercial investigation** → blog post agent
+- **Transactional / commercial** → landing page agent
+
+Spawn agents in parallel. Each agent receives:
+1. The content writing guidelines (located via find — see below)
+2. The specific opportunity data from the analysis
+
+Before spawning agents, locate the content writing reference:
+
+```bash
+CONTENT_REF=$(find ~/.claude/skills ~/.codex/skills .agents/skills -name "content-writing.md" -path "*content-writer*" 2>/dev/null | head -1)
+if [ -z "$CONTENT_REF" ]; then
+ echo "WARNING: content-writing.md not found. Content agents will use built-in knowledge only."
+else
+ echo "Content reference at: $CONTENT_REF"
+fi
+```
+
+Pass `$CONTENT_REF` as the path in each agent prompt below. If not found, omit
+the "Read the content writing guidelines" line — the agents will still produce
+good content using built-in knowledge.
+
+Use this prompt template for each agent:
+
+#### Blog Post Agent Prompt
+
+```
+You are a senior content strategist writing a blog post that ranks on Google.
+
+Read the content writing guidelines at: $CONTENT_REF
+Follow the "Blog Posts" section exactly.
+
+## Assignment
+
+Target keyword: [keyword]
+Current position: [position] (query ranked but no dedicated content)
+Monthly impressions: [impressions]
+Search intent: [informational / commercial investigation]
+Site context: [what the site is about, its audience]
+Existing pages to link to: [relevant internal pages from the analysis]
+[If available] Competitor context: [what currently ranks for this keyword]
+
+## Target Personas
+Write primarily for: [Primary persona name]
+Their goal: [primary goal]
+Their language: [key terms and phrases they use — use these naturally in headings, intro, and body]
+Their pain points: [pain points — address these directly, don't make them search for answers]
+Secondary audience: [Secondary persona name if applicable] — [brief note on how to serve both without diluting focus]
+
+## Deliverables
+
+Write the complete blog post following the guidelines, including:
+1. Full post in markdown with proper heading hierarchy
+2. SEO metadata (title tag, meta description, URL slug)
+3. JSON-LD structured data (Article/BlogPosting + FAQPage if FAQ included)
+4. Internal linking plan (which existing pages to link to/from)
+5. Publishing checklist
+
+## Quality Gate
+Before finishing, verify:
+- Would the reader need to search again? (If yes, not done)
+- Does the post contain specific examples only an expert would include?
+- Does the format match what Google shows for this query?
+- Is every paragraph earning its place? (No filler)
+```
+
+#### Landing Page Agent Prompt
+
+```
+You are a senior conversion copywriter writing a landing page that ranks AND converts.
+
+Read the content writing guidelines at: $CONTENT_REF
+Follow the "Landing Pages" section exactly.
+
+## Assignment
+
+Target keyword: [keyword]
+Current position: [position]
+Monthly impressions: [impressions]
+Search intent: [transactional / commercial]
+Page type: [service / product / location / comparison]
+Site context: [what the site is about, value prop, target customer]
+Existing pages to link to: [relevant internal pages]
+[If available] Competitor context: [what currently ranks]
+
+## Target Personas
+Write primarily for: [Primary persona name]
+Their goal: [primary goal when landing here]
+Their language: [terms they use — mirror this in headlines, subheads, and CTAs]
+Their decision trigger: [what makes them convert — address this prominently above the fold]
+Their objections: [pain points and doubts — address each explicitly, don't leave them wondering]
+
+## Deliverables
+
+Write the complete landing page following the guidelines, including:
+1. Full page copy in markdown with proper heading hierarchy and CTA placements
+2. SEO metadata (title tag, meta description, URL slug)
+3. Conversion strategy (primary CTA, objections addressed, trust signals)
+4. JSON-LD structured data
+5. Internal linking plan
+6. Publishing checklist
+
+## Quality Gate
+Before finishing, verify:
+- Would you convert after reading this? (If not, what is missing?)
+- Are there vague claims that should be replaced with specifics?
+- Is every objection addressed?
+- Is it clear what the visitor should do next?
+```
+
+### Spawning Rules
+
+- Spawn up to **5 content agents in parallel** (more than 5 gets unwieldy —
+ prioritize by impact)
+- Prioritize opportunities by: impressions x position-improvement-potential
+- Each agent works independently — they do not need to coordinate
+- As agents complete, present each piece of content to the user with its metadata
+- After all agents finish, provide a summary: what was generated, suggested
+ publishing order (highest impact first), and any cross-linking between new pages
diff --git a/seo/seo-analysis/evals/evals.json b/seo/seo-analysis/evals/evals.json
new file mode 100644
index 00000000..5be08710
--- /dev/null
+++ b/seo/seo-analysis/evals/evals.json
@@ -0,0 +1,48 @@
+{
+ "skill_name": "seo-analysis",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "Can you run an SEO audit for me?",
+ "expected_output": "The skill asks for the website URL upfront before doing anything else (before running preflight, before trying to list GSC properties). It should not assume a URL or proceed without one.",
+ "files": [],
+ "expectations": [
+ "The response asks the user for their website URL before taking any action",
+ "The skill does not proceed with preflight or GSC steps without first getting the URL",
+ "The question is friendly and gives an example format (e.g. https://yoursite.com)"
+ ]
+ },
+ {
+ "id": 2,
+ "prompt": "My site is https://acme-saas.com. I want a full SEO audit but I don't have gcloud installed or Google Search Console set up. What can you do?",
+ "expected_output": "The skill gracefully handles missing gcloud/GSC by falling back to a technical-only audit. It should still perform metadata audit, schema markup audit, technical crawl of the homepage and key pages, and offer to run /meta-tags-optimizer and /schema-markup-generator based on what it finds. It should be honest about what it can and can't do without GSC data.",
+ "files": [],
+ "expectations": [
+ "The skill acknowledges the URL https://acme-saas.com and confirms it will use this",
+ "The skill does not fail or stop when gcloud is unavailable — it falls back to Phase 5 technical audit",
+ "The response includes a crawl or fetch of the site's homepage",
+ "The response includes a metadata audit section (title tags, meta descriptions)",
+ "The response includes a schema markup audit section",
+ "The response offers to run /meta-tags-optimizer or /schema-markup-generator as follow-up"
+ ]
+ },
+ {
+ "id": 3,
+ "prompt": "My website is https://flowmetrics.io (a SaaS analytics tool). Here is my Google Search Console data from the past 90 days:\n\n```json\n{\"site\": \"sc-domain:flowmetrics.io\", \"period\": {\"start\": \"2025-12-22\", \"end\": \"2026-03-21\", \"days\": 90}, \"summary\": {\"clicks\": 8240, \"impressions\": 412000, \"ctr\": 2.0, \"position\": 14.3}, \"top_queries\": [{\"query\": \"analytics dashboard software\", \"clicks\": 890, \"impressions\": 42000, \"ctr\": 2.1, \"position\": 8.4}, {\"query\": \"flowmetrics\", \"clicks\": 720, \"impressions\": 3200, \"ctr\": 22.5, \"position\": 1.2}, {\"query\": \"saas metrics dashboard\", \"clicks\": 610, \"impressions\": 38000, \"ctr\": 1.6, \"position\": 9.1}, {\"query\": \"mrr tracking tool\", \"clicks\": 480, \"impressions\": 28000, \"ctr\": 1.7, \"position\": 11.2}, {\"query\": \"churn rate calculator\", \"clicks\": 320, \"impressions\": 19000, \"ctr\": 1.7, \"position\": 12.8}, {\"query\": \"best saas analytics tools\", \"clicks\": 280, \"impressions\": 31000, \"ctr\": 0.9, \"position\": 7.2}, {\"query\": \"ltv cac ratio tool\", \"clicks\": 180, \"impressions\": 14000, \"ctr\": 1.3, \"position\": 15.4}, {\"query\": \"subscription analytics software\", \"clicks\": 170, \"impressions\": 22000, \"ctr\": 0.8, \"position\": 6.8}, {\"query\": \"how to reduce saas churn\", \"clicks\": 150, \"impressions\": 18000, \"ctr\": 0.8, \"position\": 8.9}, {\"query\": \"arr tracking spreadsheet\", \"clicks\": 90, \"impressions\": 12000, \"ctr\": 0.75, \"position\": 13.1}], \"top_pages\": [{\"page\": \"https://flowmetrics.io/\", \"clicks\": 2100, \"impressions\": 85000, \"ctr\": 2.5, \"position\": 7.2}, {\"page\": \"https://flowmetrics.io/features\", \"clicks\": 1200, \"impressions\": 62000, \"ctr\": 1.9, \"position\": 11.4}, {\"page\": \"https://flowmetrics.io/pricing\", \"clicks\": 980, \"impressions\": 44000, \"ctr\": 2.2, \"position\": 9.8}, {\"page\": \"https://flowmetrics.io/blog/reduce-saas-churn\", \"clicks\": 620, \"impressions\": 38000, \"ctr\": 1.6, \"position\": 8.1}, {\"page\": \"https://flowmetrics.io/blog/mrr-vs-arr\", \"clicks\": 440, \"impressions\": 29000, \"ctr\": 1.5, \"position\": 12.3}], \"position_buckets\": {\"1-3\": [{\"query\": \"flowmetrics\", \"clicks\": 720, \"impressions\": 3200, \"ctr\": 22.5, \"position\": 1.2}], \"4-10\": [{\"query\": \"analytics dashboard software\", \"clicks\": 890, \"impressions\": 42000, \"ctr\": 2.1, \"position\": 8.4}, {\"query\": \"saas metrics dashboard\", \"clicks\": 610, \"impressions\": 38000, \"ctr\": 1.6, \"position\": 9.1}, {\"query\": \"best saas analytics tools\", \"clicks\": 280, \"impressions\": 31000, \"ctr\": 0.9, \"position\": 7.2}, {\"query\": \"subscription analytics software\", \"clicks\": 170, \"impressions\": 22000, \"ctr\": 0.8, \"position\": 6.8}, {\"query\": \"how to reduce saas churn\", \"clicks\": 150, \"impressions\": 18000, \"ctr\": 0.8, \"position\": 8.9}], \"11-20\": [{\"query\": \"mrr tracking tool\", \"clicks\": 480, \"impressions\": 28000, \"ctr\": 1.7, \"position\": 11.2}, {\"query\": \"churn rate calculator\", \"clicks\": 320, \"impressions\": 19000, \"ctr\": 1.7, \"position\": 12.8}, {\"query\": \"ltv cac ratio tool\", \"clicks\": 180, \"impressions\": 14000, \"ctr\": 1.3, \"position\": 15.4}, {\"query\": \"arr tracking spreadsheet\", \"clicks\": 90, \"impressions\": 12000, \"ctr\": 0.75, \"position\": 13.1}], \"21+\": []}, \"ctr_opportunities\": [{\"query\": \"best saas analytics tools\", \"clicks\": 280, \"impressions\": 31000, \"ctr\": 0.9, \"position\": 7.2}, {\"query\": \"subscription analytics software\", \"clicks\": 170, \"impressions\": 22000, \"ctr\": 0.8, \"position\": 6.8}, {\"query\": \"how to reduce saas churn\", \"clicks\": 150, \"impressions\": 18000, \"ctr\": 0.8, \"position\": 8.9}], \"ctr_gaps_by_page\": [{\"query\": \"best saas analytics tools\", \"page\": \"https://flowmetrics.io/\", \"clicks\": 280, \"impressions\": 31000, \"ctr\": 0.9, \"position\": 7.2}, {\"query\": \"subscription analytics software\", \"page\": \"https://flowmetrics.io/features\", \"clicks\": 170, \"impressions\": 22000, \"ctr\": 0.8, \"position\": 6.8}, {\"query\": \"how to reduce saas churn\", \"page\": \"https://flowmetrics.io/blog/reduce-saas-churn\", \"clicks\": 150, \"impressions\": 18000, \"ctr\": 0.8, \"position\": 8.9}], \"cannibalization\": [{\"query\": \"saas analytics\", \"competing_pages\": [{\"page\": \"https://flowmetrics.io/\", \"clicks\": 310, \"impressions\": 18000, \"ctr\": 1.7, \"position\": 8.2}, {\"page\": \"https://flowmetrics.io/features\", \"clicks\": 190, \"impressions\": 14000, \"ctr\": 1.4, \"position\": 11.8}], \"total_impressions\": 32000, \"total_clicks\": 500}], \"comparison\": {\"period\": \"2026-02-22 to 2026-03-21\", \"prior_period\": \"2026-01-24 to 2026-02-21\", \"declining_pages\": [{\"page\": \"https://flowmetrics.io/blog/mrr-vs-arr\", \"clicks_now\": 110, \"clicks_prev\": 220, \"change_pct\": -50.0}], \"declining_queries\": [{\"query\": \"mrr arr difference\", \"clicks_now\": 40, \"clicks_prev\": 95, \"change_pct\": -57.9}]}, \"device_split\": [{\"device\": \"DESKTOP\", \"clicks\": 5340, \"impressions\": 264000, \"ctr\": 2.0, \"position\": 13.8}, {\"device\": \"MOBILE\", \"clicks\": 2620, \"impressions\": 138000, \"ctr\": 1.9, \"position\": 15.1}, {\"device\": \"TABLET\", \"clicks\": 280, \"impressions\": 10000, \"ctr\": 2.8, \"position\": 12.4}], \"country_split\": [{\"country\": \"usa\", \"clicks\": 4120, \"impressions\": 198000, \"ctr\": 2.1, \"position\": 13.2}, {\"country\": \"gbr\", \"clicks\": 920, \"impressions\": 48000, \"ctr\": 1.9, \"position\": 14.8}, {\"country\": \"can\", \"clicks\": 680, \"impressions\": 34000, \"ctr\": 2.0, \"position\": 14.1}, {\"country\": \"ind\", \"clicks\": 310, \"impressions\": 52000, \"ctr\": 0.6, \"position\": 18.4}, {\"country\": \"aus\", \"clicks\": 290, \"impressions\": 14000, \"ctr\": 2.1, \"position\": 14.6}], \"search_type_split\": [{\"type\": \"web\", \"clicks\": 8100, \"impressions\": 408000, \"ctr\": 2.0, \"position\": 14.3}, {\"type\": \"image\", \"clicks\": 140, \"impressions\": 4000, \"ctr\": 3.5, \"position\": 8.2}]}\n```\n\nPlease give me a full SEO analysis. I want to understand my quick wins, keyword gaps, metadata issues, and schema problems.",
+ "expected_output": "A comprehensive SEO analysis report that includes: Traffic Snapshot table, Quick Wins section with specific actionable recommendations tied to exact queries and pages, Keyword Gaps section (orphan keywords + topic clusters + business gaps), Metadata Issues table, Schema Gaps table, Content Opportunities, Traffic Drops section (specifically about the blog/mrr-vs-arr 50% drop), cannibalization analysis, and a prioritized 30-Day Action Plan. Also offers /meta-tags-optimizer, /schema-markup-generator, and /keyword-research as follow-up actions.",
+ "files": [],
+ "expectations": [
+ "Report has a Traffic Snapshot table with the correct metrics (8240 clicks, 412000 impressions, 2.0% CTR, position 14.3)",
+ "Quick Wins section specifically mentions 'best saas analytics tools' (position 7.2, 31000 impressions, 0.9% CTR) with a specific fix recommendation",
+ "Quick Wins section specifically mentions 'subscription analytics software' (position 6.8, 22000 impressions, 0.8% CTR)",
+ "Keyword Gaps section includes orphan keywords — specifically 'mrr tracking tool', 'churn rate calculator', or 'ltv cac ratio tool' as queries without dedicated pages",
+ "Keyword Cannibalization section addresses 'saas analytics' competing between homepage and /features",
+ "Traffic Drops section addresses the blog/mrr-vs-arr page dropping 50% (-110 clicks)",
+ "Metadata Issues section is present (checks real page metadata or notes it needs crawling)",
+ "Schema Gaps section is present with site type identified as SaaS and expected schema types listed",
+ "The report offers to run /meta-tags-optimizer, /schema-markup-generator, or /keyword-research as follow-up",
+ "30-Day Action Plan table is present with at least 3 prioritized actions"
+ ]
+ }
+ ]
+}
diff --git a/seo/seo-analysis/references/gsc_setup.md b/seo/seo-analysis/references/gsc_setup.md
new file mode 100644
index 00000000..adea5a30
--- /dev/null
+++ b/seo/seo-analysis/references/gsc_setup.md
@@ -0,0 +1,199 @@
+# Google Search Console API Setup Guide
+
+## Step 0 — Which Google Account Has GSC Access?
+
+This is the most common source of confusion. You need to authenticate with the
+**exact Google account** that has access to Search Console for this site.
+
+Check which account it is:
+1. Go to https://search.google.com/search-console
+2. Note which Google account you're logged in as (top-right corner)
+3. Use that same account in all the steps below
+
+If you have multiple Google accounts (work email, personal Gmail, different org),
+make sure you pick the right one. A valid gcloud token from the wrong account will
+appear to work but return no GSC properties.
+
+---
+
+## Step 1 — Install the gcloud CLI
+
+Skip this step if you already have gcloud installed (`gcloud --version` to check).
+
+### macOS (Homebrew)
+
+```bash
+brew install google-cloud-sdk
+```
+
+### Linux (Debian/Ubuntu)
+
+```bash
+# Install prerequisites
+sudo apt-get install -y curl apt-transport-https ca-certificates gnupg
+
+# Add the Google Cloud GPG key (modern keyring method, works on Debian 12+/Ubuntu 22.04+)
+curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg \
+ | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
+
+# Add the Cloud SDK apt repository
+echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] \
+ https://packages.cloud.google.com/apt cloud-sdk main" \
+ | sudo tee /etc/apt/sources.list.d/google-cloud-sdk.list
+
+sudo apt-get update && sudo apt-get install -y google-cloud-cli
+```
+
+### Linux (RPM/Fedora/RHEL)
+
+```bash
+sudo tee /etc/yum.repos.d/google-cloud-sdk.repo << EOM
+[google-cloud-cli]
+name=Google Cloud CLI
+baseurl=https://packages.cloud.google.com/yum/repos/cloud-sdk-el8-x86_64
+enabled=1
+gpgcheck=1
+repo_gpgcheck=0
+gpgkey=https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
+EOM
+sudo dnf install google-cloud-cli
+```
+
+### Windows
+
+```powershell
+winget install Google.CloudSDK
+```
+
+Or download the installer:
+https://cloud.google.com/sdk/docs/install#windows
+
+---
+
+## Step 2 — Initialize gcloud (First-Time Users)
+
+Skip this step if you've used gcloud before and already have a project configured
+(`gcloud config get-value project` to check).
+
+```bash
+gcloud init
+```
+
+This interactive wizard will:
+1. **Log you into Google** — a browser window opens. Sign in with the account from Step 0.
+2. **Select or create a GCP project** — if you don't have one, choose "Create a new project" and give it any name (e.g., `my-seo-tools`). The project is free — it's just a container for API access.
+
+After `gcloud init` completes, verify:
+```bash
+gcloud config get-value project
+# Should print your project name, e.g. "my-seo-tools"
+```
+
+---
+
+## Step 3 — Enable the Search Console API
+
+The Search Console API must be enabled in your GCP project before you can pull data.
+
+```bash
+gcloud services enable searchconsole.googleapis.com
+```
+
+This is a one-time step per project. It's free — the Search Console API has no charges.
+
+**If you get a billing error**: Some GCP projects require a billing account even for free APIs. Either:
+- Link a billing account at https://console.cloud.google.com/billing (you won't be charged for Search Console API usage)
+- Or create a new project at https://console.cloud.google.com/projectcreate and try again
+
+---
+
+## Step 4 — Authenticate for Search Console Access (OAuth)
+
+This is the key step. You need Application Default Credentials (ADC) with the
+Search Console scopes. The `--scopes` flag is required — omitting it defaults to
+the broad `cloud-platform` scope, which asks for access to BigQuery, Compute Engine,
+and other services you don't need.
+
+```bash
+gcloud auth application-default login \
+ --scopes=https://www.googleapis.com/auth/webmasters,https://www.googleapis.com/auth/webmasters.readonly
+```
+
+A browser window opens. **Log in with the Google account from Step 0** — the one
+that has access to Search Console for your site.
+
+You'll see a consent screen asking to grant "Search Console API" access.
+Click **Allow**.
+
+The token is stored at `~/.config/gcloud/application_default_credentials.json`
+and auto-refreshes — you won't need to do this again unless the token is revoked.
+
+The scripts auto-detect the quota project from your gcloud config, so no extra
+setup is needed.
+
+---
+
+## Step 5 — Verify Everything Works
+
+```bash
+SKILL_SCRIPTS=$(find ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
+python3 "$SKILL_SCRIPTS/list_gsc_sites.py"
+```
+
+This should list your Search Console properties. If it does, you're done.
+
+---
+
+## Property Types in Search Console
+
+GSC has two types of properties:
+
+- **Domain property**: `sc-domain:example.com` — covers all URLs, protocols, subdomains
+- **URL-prefix property**: `https://example.com/` — covers only that exact prefix
+
+Domain properties are better (more complete data). The analysis scripts handle both.
+
+---
+
+## Troubleshooting
+
+**"No Search Console properties found"**: gcloud is working but the wrong Google
+account is authenticated. Re-run Step 4 and log in with the account that has GSC
+access (see Step 0).
+
+**"Access Not Configured" / HTTP 403 with "API not enabled"**: The Search Console
+API isn't enabled in your GCP project. Run Step 3:
+```bash
+gcloud services enable searchconsole.googleapis.com
+```
+
+**"The caller does not have permission"**: The authenticated account doesn't have
+access to the specific GSC property. Verify at
+https://search.google.com/search-console → Settings → Users and permissions.
+
+**"insufficient_scope" or 403 on API calls despite valid token**: Your ADC token
+was created without `--scopes` (which defaults to `cloud-platform`), or was set up
+for a different Google service. The preflight script now detects this automatically
+and re-authenticates. To fix manually, re-run Step 4:
+```bash
+gcloud auth application-default login \
+ --scopes=https://www.googleapis.com/auth/webmasters,https://www.googleapis.com/auth/webmasters.readonly
+```
+
+**"quota project not set" / 403 with quota error**: The scripts auto-detect the
+quota project from `gcloud config`. If this still fails, set it explicitly:
+```bash
+gcloud auth application-default set-quota-project "$(gcloud config get-value project)"
+```
+
+**"No project configured" / gcloud init never run**: Run Step 2:
+```bash
+gcloud init
+```
+
+**Token expired**: ADC tokens auto-refresh. If you get persistent auth errors,
+re-run Step 4.
+
+**Billing required error when enabling API**: Link a billing account at
+https://console.cloud.google.com/billing — the Search Console API is free, but
+some GCP projects require billing to be configured.
diff --git a/seo/seo-analysis/scripts/analyze_gsc.py b/seo/seo-analysis/scripts/analyze_gsc.py
new file mode 100644
index 00000000..f59ced89
--- /dev/null
+++ b/seo/seo-analysis/scripts/analyze_gsc.py
@@ -0,0 +1,607 @@
+#!/usr/bin/env python3
+"""
+Pull and analyze Google Search Console data.
+Outputs structured JSON for the seo-analysis skill to process.
+
+Usage:
+ python3 analyze_gsc.py --site "sc-domain:example.com" --days 90
+ python3 analyze_gsc.py --site "https://example.com/" --days 28
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import urllib.parse
+import urllib.request
+import urllib.error
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from datetime import date, timedelta
+
+
+DEFAULT_PAGE_GROUPS = [
+ ("blog", r"/blog/"),
+ ("products", r"/product"),
+ ("locations", r"/location"),
+ ("services", r"/service"),
+ ("pricing", r"/pricing"),
+ ("docs", r"/docs?/"),
+ ("about", r"/about"),
+ ("faq", r"/faq"),
+ ("landing", r"/lp/"),
+ ("case-studies", r"/case-studi"),
+]
+
+
+def get_quota_project():
+ """Return the quota_project_id from the ADC JSON file, or None."""
+ adc_dir = os.environ.get("CLOUDSDK_CONFIG") or os.path.join(
+ os.path.expanduser("~"), ".config", "gcloud"
+ )
+ adc_path = os.path.join(adc_dir, "application_default_credentials.json")
+ try:
+ with open(adc_path) as f:
+ data = json.load(f)
+ if isinstance(data, dict):
+ return data.get("quota_project_id") or None
+ except (OSError, ValueError):
+ pass
+ return None
+
+
+def get_access_token():
+ try:
+ result = subprocess.run(
+ ["gcloud", "auth", "application-default", "print-access-token"],
+ capture_output=True, text=True, timeout=15
+ )
+ except FileNotFoundError:
+ print("ERROR: gcloud not found. Install it and authenticate:", file=sys.stderr)
+ print(" https://cloud.google.com/sdk/docs/install", file=sys.stderr)
+ sys.exit(1)
+ except subprocess.TimeoutExpired:
+ print("ERROR: gcloud timed out after 15s. Check your network or gcloud installation.", file=sys.stderr)
+ sys.exit(1)
+ if result.returncode != 0:
+ print("ERROR: Not authenticated. Run:", file=sys.stderr)
+ print(" gcloud auth application-default login \\", file=sys.stderr)
+ print(" --scopes=https://www.googleapis.com/auth/webmasters,"
+ "https://www.googleapis.com/auth/webmasters.readonly", file=sys.stderr)
+ sys.exit(1)
+ token = result.stdout.strip()
+ if not token:
+ print("ERROR: gcloud returned an empty token. Re-authenticate:", file=sys.stderr)
+ print(" gcloud auth application-default login \\", file=sys.stderr)
+ print(" --scopes=https://www.googleapis.com/auth/webmasters,"
+ "https://www.googleapis.com/auth/webmasters.readonly", file=sys.stderr)
+ sys.exit(1)
+ return token
+
+
+def gsc_query(token, site_url, body):
+ """Call the Search Analytics query endpoint."""
+ encoded = urllib.parse.quote(site_url, safe="")
+ url = f"https://searchconsole.googleapis.com/webmasters/v3/sites/{encoded}/searchAnalytics/query"
+ data = json.dumps(body).encode()
+ headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
+ quota_project = get_quota_project()
+ if quota_project:
+ headers["x-goog-user-project"] = quota_project
+ req = urllib.request.Request(url, data=data, headers=headers)
+ try:
+ with urllib.request.urlopen(req, timeout=30) as resp:
+ return json.loads(resp.read())
+ except urllib.error.HTTPError as e:
+ err_body = e.read().decode() if e.fp else "(no body)"
+ print(f"GSC API error {e.code}: {err_body}", file=sys.stderr)
+ return {"rows": []}
+ except urllib.error.URLError as e:
+ print(f"GSC API network error: {e.reason}", file=sys.stderr)
+ return {"rows": []}
+
+
+def date_range(days_ago_start, days_ago_end=3):
+ """Return (start, end) date strings. GSC data typically lags ~3 days."""
+ end = date.today() - timedelta(days=days_ago_end)
+ start = end - timedelta(days=days_ago_start)
+ return start.isoformat(), end.isoformat()
+
+
+def pull_top_queries(token, site, start, end, row_limit=50):
+ body = {
+ "startDate": start, "endDate": end,
+ "dimensions": ["query"],
+ "rowLimit": row_limit,
+ "orderBy": [{"fieldName": "impressions", "sortOrder": "DESCENDING"}]
+ }
+ data = gsc_query(token, site, body)
+ rows = []
+ for r in data.get("rows", []):
+ rows.append({
+ "query": r["keys"][0],
+ "clicks": r["clicks"],
+ "impressions": r["impressions"],
+ "ctr": round(r["ctr"] * 100, 2),
+ "position": round(r["position"], 1)
+ })
+ return rows
+
+
+def pull_top_pages(token, site, start, end, row_limit=50):
+ body = {
+ "startDate": start, "endDate": end,
+ "dimensions": ["page"],
+ "rowLimit": row_limit,
+ "orderBy": [{"fieldName": "clicks", "sortOrder": "DESCENDING"}]
+ }
+ data = gsc_query(token, site, body)
+ rows = []
+ for r in data.get("rows", []):
+ rows.append({
+ "page": r["keys"][0],
+ "clicks": r["clicks"],
+ "impressions": r["impressions"],
+ "ctr": round(r["ctr"] * 100, 2),
+ "position": round(r["position"], 1)
+ })
+ return rows
+
+
+def pull_position_buckets(token, site, start, end):
+ """Queries by position bucket: 1-3 (winners), 4-10 (low-hanging fruit), 11-20 (almost there), 21+."""
+ body = {
+ "startDate": start, "endDate": end,
+ "dimensions": ["query"],
+ "rowLimit": 1000,
+ "orderBy": [{"fieldName": "impressions", "sortOrder": "DESCENDING"}]
+ }
+ data = gsc_query(token, site, body)
+ buckets = {"1-3": [], "4-10": [], "11-20": [], "21+": []}
+ for r in data.get("rows", []):
+ pos = r["position"]
+ entry = {
+ "query": r["keys"][0],
+ "clicks": r["clicks"],
+ "impressions": r["impressions"],
+ "ctr": round(r["ctr"] * 100, 2),
+ "position": round(pos, 1)
+ }
+ if pos <= 3:
+ buckets["1-3"].append(entry)
+ elif pos <= 10:
+ buckets["4-10"].append(entry)
+ elif pos <= 20:
+ buckets["11-20"].append(entry)
+ else:
+ buckets["21+"].append(entry)
+ return buckets
+
+
+def pull_period_comparison(token, site, days):
+ """Compare current period vs prior period to find declines."""
+ end_curr = date.today() - timedelta(days=3)
+ start_curr = end_curr - timedelta(days=days)
+ end_prev = start_curr - timedelta(days=1)
+ start_prev = end_prev - timedelta(days=days)
+
+ def fetch(start, end, dim):
+ body = {
+ "startDate": start.isoformat(), "endDate": end.isoformat(),
+ "dimensions": [dim], "rowLimit": 200,
+ "orderBy": [{"fieldName": "clicks", "sortOrder": "DESCENDING"}]
+ }
+ data = gsc_query(token, site, body)
+ return {r["keys"][0]: r for r in data.get("rows", [])}
+
+ # Pages comparison
+ curr_pages = fetch(start_curr, end_curr, "page")
+ prev_pages = fetch(start_prev, end_prev, "page")
+
+ page_changes = []
+ for page, curr in curr_pages.items():
+ if page in prev_pages:
+ prev = prev_pages[page]
+ delta = curr["clicks"] - prev["clicks"]
+ pct = round((delta / max(prev["clicks"], 1)) * 100, 1)
+ if pct < -20 and prev["clicks"] > 10: # Only flag meaningful drops
+ page_changes.append({
+ "page": page,
+ "clicks_now": curr["clicks"],
+ "clicks_prev": prev["clicks"],
+ "change_pct": pct
+ })
+ page_changes.sort(key=lambda x: x["change_pct"])
+
+ # Queries comparison
+ curr_q = fetch(start_curr, end_curr, "query")
+ prev_q = fetch(start_prev, end_prev, "query")
+
+ query_changes = []
+ for q, curr in curr_q.items():
+ if q in prev_q:
+ prev = prev_q[q]
+ delta = curr["clicks"] - prev["clicks"]
+ pct = round((delta / max(prev["clicks"], 1)) * 100, 1)
+ if pct < -25 and prev["clicks"] > 5:
+ query_changes.append({
+ "query": q,
+ "clicks_now": curr["clicks"],
+ "clicks_prev": prev["clicks"],
+ "change_pct": pct
+ })
+ query_changes.sort(key=lambda x: x["change_pct"])
+
+ return {
+ "period": f"{start_curr.isoformat()} to {end_curr.isoformat()}",
+ "prior_period": f"{start_prev.isoformat()} to {end_prev.isoformat()}",
+ "declining_pages": page_changes[:20],
+ "declining_queries": query_changes[:20]
+ }
+
+
+def pull_summary(token, site, start, end):
+ """Overall totals."""
+ body = {"startDate": start, "endDate": end, "dimensions": []}
+ data = gsc_query(token, site, body)
+ rows = data.get("rows", [{}])
+ r = rows[0] if rows else {}
+ return {
+ "clicks": r.get("clicks", 0),
+ "impressions": r.get("impressions", 0),
+ "ctr": round(r.get("ctr", 0) * 100, 2),
+ "position": round(r.get("position", 0), 1)
+ }
+
+
+def pull_device_split(token, site, start, end):
+ body = {
+ "startDate": start, "endDate": end,
+ "dimensions": ["device"],
+ "rowLimit": 10
+ }
+ data = gsc_query(token, site, body)
+ return [
+ {"device": r["keys"][0], "clicks": r["clicks"], "impressions": r["impressions"],
+ "ctr": round(r["ctr"] * 100, 2), "position": round(r["position"], 1)}
+ for r in data.get("rows", [])
+ ]
+
+
+def pull_country_split(token, site, start, end, row_limit=20):
+ """Top countries by clicks. Surfaces geo opportunities and region-specific problems."""
+ body = {
+ "startDate": start, "endDate": end,
+ "dimensions": ["country"],
+ "rowLimit": row_limit,
+ "orderBy": [{"fieldName": "clicks", "sortOrder": "DESCENDING"}]
+ }
+ data = gsc_query(token, site, body)
+ return [
+ {"country": r["keys"][0], "clicks": r["clicks"], "impressions": r["impressions"],
+ "ctr": round(r["ctr"] * 100, 2), "position": round(r["position"], 1)}
+ for r in data.get("rows", [])
+ ]
+
+
+def pull_search_type_split(token, site, start, end):
+ """Breakdown by search type: web, image, video, news, discover, googleNews.
+ Many sites have Discover or image traffic they don't know about."""
+ search_types = ["web", "image", "video", "news", "discover", "googleNews"]
+ results = []
+ for stype in search_types:
+ body = {
+ "startDate": start, "endDate": end,
+ "dimensions": [],
+ "type": stype
+ }
+ data = gsc_query(token, site, body)
+ rows = data.get("rows", [{}])
+ r = rows[0] if rows else {}
+ clicks = r.get("clicks", 0)
+ if clicks > 0:
+ results.append({
+ "type": stype,
+ "clicks": clicks,
+ "impressions": r.get("impressions", 0),
+ "ctr": round(r.get("ctr", 0) * 100, 2),
+ "position": round(r.get("position", 0), 1)
+ })
+ results.sort(key=lambda x: x["clicks"], reverse=True)
+ return results
+
+
+def pull_query_page_rows(token, site, start, end, row_limit=2000):
+ """Pull [query, page] dimension data in one call. Expensive — reused for both
+ cannibalization detection and page-level CTR gap analysis."""
+ body = {
+ "startDate": start, "endDate": end,
+ "dimensions": ["query", "page"],
+ "rowLimit": row_limit,
+ "orderBy": [{"fieldName": "impressions", "sortOrder": "DESCENDING"}]
+ }
+ data = gsc_query(token, site, body)
+ return data.get("rows", [])
+
+
+def _cannibalization_winner(pages):
+ """Pick the canonical winner page. Primary: best (lowest) position. Tiebreaker: most clicks."""
+ return min(pages, key=lambda p: (p["position"], -p["clicks"]))
+
+
+def derive_cannibalization(rows, min_impressions=100):
+ """Find queries where multiple pages compete for the same keyword.
+ Returns structured winner/loser scoring and recommended action.
+ Input: raw rows from pull_query_page_rows."""
+ query_pages = {}
+ for r in rows:
+ query, page = r["keys"]
+ if query not in query_pages:
+ query_pages[query] = []
+ query_pages[query].append({
+ "page": page,
+ "clicks": r["clicks"],
+ "impressions": r["impressions"],
+ "ctr": round(r["ctr"] * 100, 2),
+ "position": round(r["position"], 1)
+ })
+
+ cannibalized = []
+ for query, pages in query_pages.items():
+ if len(pages) > 1:
+ total_impressions = sum(p["impressions"] for p in pages)
+ if total_impressions >= min_impressions:
+ winner = _cannibalization_winner(pages)
+ winner_page = winner["page"]
+ loser_pages = [p["page"] for p in pages if p["page"] != winner_page]
+
+ # Possible SERP domination: all pages in top 5, positions within 2 of each other
+ positions = [p["position"] for p in pages]
+ is_domination = max(positions) <= 5 and (max(positions) - min(positions)) <= 2.0
+ action = ("monitor: possible SERP domination"
+ if is_domination else
+ "consolidate: 301 redirect losers to winner or add canonical")
+
+ # Determine the actual deciding factor for the winner reason
+ all_same_position = all(p["position"] == winner["position"] for p in pages)
+ winner_reason = (f"most clicks ({winner['clicks']})" if all_same_position
+ else f"best position ({winner['position']})")
+
+ cannibalized.append({
+ "query": query,
+ "winner_page": winner_page,
+ "winner_reason": winner_reason,
+ "loser_pages": loser_pages,
+ "recommended_action": action,
+ "competing_pages": sorted(pages, key=lambda x: x["position"]),
+ "total_impressions": total_impressions,
+ "total_clicks": sum(p["clicks"] for p in pages)
+ })
+
+ cannibalized.sort(key=lambda x: x["total_impressions"], reverse=True)
+ return cannibalized[:30]
+
+
+def derive_ctr_gaps_by_page(rows, min_impressions=200, max_ctr=3.0, max_position=20):
+ """High-impression, low-CTR at query+page level — pinpoints exactly which page
+ to rewrite the title/meta for. Input: raw rows from pull_query_page_rows."""
+ gaps = []
+ for r in rows:
+ ctr_pct = r["ctr"] * 100
+ if r["impressions"] >= min_impressions and ctr_pct < max_ctr and r["position"] <= max_position:
+ gaps.append({
+ "query": r["keys"][0],
+ "page": r["keys"][1],
+ "clicks": r["clicks"],
+ "impressions": r["impressions"],
+ "ctr": round(ctr_pct, 2),
+ "position": round(r["position"], 1)
+ })
+ gaps.sort(key=lambda x: x["impressions"], reverse=True)
+ return gaps[:25]
+
+
+def classify_branded(query, brand_terms):
+ """Return True if query contains any brand term (case-insensitive substring match)."""
+ if not brand_terms:
+ return False
+ q = query.lower()
+ return any(term.lower() in q for term in brand_terms)
+
+
+def derive_branded_split(rows, brand_terms):
+ """Split query+page traffic into branded vs non-branded segments.
+ Input: raw rows from pull_query_page_rows. Returns None if no brand_terms provided."""
+ if not brand_terms:
+ return None
+
+ # Aggregate per unique query (qp_rows can have multiple rows per query across pages)
+ query_stats = {}
+ for r in rows:
+ query = r["keys"][0]
+ imp = r["impressions"]
+ if query not in query_stats:
+ query_stats[query] = {
+ "clicks": 0, "impressions": 0, "weighted_pos": 0.0,
+ "branded": classify_branded(query, brand_terms)
+ }
+ query_stats[query]["clicks"] += r["clicks"]
+ query_stats[query]["impressions"] += imp
+ query_stats[query]["weighted_pos"] += r["position"] * imp
+
+ branded, non_branded = [], []
+ for query, s in query_stats.items():
+ imp = s["impressions"]
+ pos = round(s["weighted_pos"] / imp, 1) if imp > 0 else 0.0
+ ctr = round(s["clicks"] / imp * 100, 2) if imp > 0 else 0.0
+ entry = {"query": query, "clicks": s["clicks"], "impressions": imp,
+ "ctr": ctr, "position": pos}
+ (branded if s["branded"] else non_branded).append(entry)
+
+ def summarize(query_list):
+ if not query_list:
+ return {"clicks": 0, "impressions": 0, "ctr": 0.0, "position": 0.0,
+ "query_count": 0, "top_queries": []}
+ total_clicks = sum(q["clicks"] for q in query_list)
+ total_imp = sum(q["impressions"] for q in query_list)
+ ctr = round(total_clicks / total_imp * 100, 2) if total_imp > 0 else 0.0
+ weighted_pos = sum(q["position"] * q["impressions"] for q in query_list)
+ pos = round(weighted_pos / total_imp, 1) if total_imp > 0 else 0.0
+ top = sorted(query_list, key=lambda x: x["impressions"], reverse=True)[:20]
+ return {"clicks": total_clicks, "impressions": total_imp, "ctr": ctr,
+ "position": pos, "query_count": len(query_list), "top_queries": top}
+
+ return {"branded": summarize(branded), "non_branded": summarize(non_branded)}
+
+
+def _url_path(url):
+ """Extract lowercase path from a full URL or path string."""
+ try:
+ path = urllib.parse.urlparse(url).path
+ except Exception:
+ path = url
+ return path.rstrip("/").lower() or "/"
+
+
+def cluster_page_groups(pages, groups=None):
+ """Group pages by URL path pattern. Returns per-group aggregate stats sorted by clicks.
+ pages: list of dicts with 'page', 'clicks', 'impressions', 'ctr', 'position' keys."""
+ patterns = groups or DEFAULT_PAGE_GROUPS
+ buckets = {name: {"clicks": 0, "impressions": 0, "pos_weighted": 0.0, "count": 0}
+ for name, _ in patterns}
+ buckets["other"] = {"clicks": 0, "impressions": 0, "pos_weighted": 0.0, "count": 0}
+
+ for p in pages:
+ path = _url_path(p["page"])
+ group = "other"
+ for name, pattern in patterns:
+ if re.search(pattern, path):
+ group = name
+ break
+ imp = p["impressions"]
+ buckets[group]["clicks"] += p["clicks"]
+ buckets[group]["impressions"] += imp
+ buckets[group]["pos_weighted"] += p["position"] * imp
+ buckets[group]["count"] += 1
+
+ results = []
+ for name, b in buckets.items():
+ if b["count"] == 0:
+ continue
+ imp = b["impressions"]
+ ctr = round(b["clicks"] / imp * 100, 2) if imp > 0 else 0.0
+ pos = round(b["pos_weighted"] / imp, 1) if imp > 0 else 0.0
+ results.append({"group": name, "page_count": b["count"],
+ "clicks": b["clicks"], "impressions": imp, "ctr": ctr, "position": pos})
+
+ results.sort(key=lambda x: x["clicks"], reverse=True)
+ return results
+
+
+def main():
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--site", required=True, help="GSC property URL")
+ parser.add_argument("--days", type=int, default=90, help="Days of data to pull")
+ parser.add_argument("--brand-terms", default="",
+ help="Comma-separated brand names for branded vs non-branded split, e.g. 'Acme,AcmeCorp'")
+ _default_out = os.path.join(tempfile.gettempdir(), f"gsc_analysis_{os.getuid()}.json")
+ parser.add_argument("--output", default=_default_out, help="Output file")
+ args = parser.parse_args()
+ brand_terms = [t.strip() for t in args.brand_terms.split(",") if t.strip()]
+
+ print(f"Pulling {args.days} days of GSC data for: {args.site}", file=sys.stderr)
+
+ token = get_access_token()
+ start, end = date_range(args.days)
+
+ # All GSC calls are independent — run them concurrently to cut wall-clock
+ # time from ~9 sequential round-trips down to the slowest single call.
+ tasks = {
+ "summary": lambda: pull_summary(token, args.site, start, end),
+ "queries": lambda: pull_top_queries(token, args.site, start, end),
+ "pages": lambda: pull_top_pages(token, args.site, start, end),
+ "buckets": lambda: pull_position_buckets(token, args.site, start, end),
+ "comparison": lambda: pull_period_comparison(token, args.site, 28),
+ "devices": lambda: pull_device_split(token, args.site, start, end),
+ "countries": lambda: pull_country_split(token, args.site, start, end),
+ "search_types": lambda: pull_search_type_split(token, args.site, start, end),
+ "qp_rows": lambda: pull_query_page_rows(token, args.site, start, end),
+ }
+
+ results = {}
+ print(f"Fetching {len(tasks)} data sets in parallel...", file=sys.stderr)
+ with ThreadPoolExecutor(max_workers=len(tasks)) as pool:
+ futures = {pool.submit(fn): name for name, fn in tasks.items()}
+ for future in as_completed(futures):
+ name = futures[future]
+ try:
+ results[name] = future.result()
+ print(f" ✓ {name}", file=sys.stderr)
+ except Exception as exc:
+ print(f" ✗ {name}: {exc}", file=sys.stderr)
+ results[name] = {}
+
+ summary = results["summary"]
+ queries = results["queries"]
+ pages = results["pages"]
+ buckets = results["buckets"]
+ comparison = results["comparison"]
+ devices = results["devices"]
+ countries = results["countries"]
+ search_types = results["search_types"]
+ qp_rows = results["qp_rows"]
+
+ cannibalization = derive_cannibalization(qp_rows)
+ ctr_gaps_by_page = derive_ctr_gaps_by_page(qp_rows)
+
+ # High-impression, low-CTR queries (query-level, for quick title/snippet targeting)
+ ctr_opportunities = [
+ q for q in queries
+ if q["impressions"] > 500 and q["ctr"] < 3.0 and q["position"] <= 20
+ ]
+ ctr_opportunities.sort(key=lambda x: x["impressions"], reverse=True)
+
+ print("Deriving branded/non-branded split...", file=sys.stderr)
+ branded_split = derive_branded_split(qp_rows, brand_terms)
+
+ print("Clustering pages by section...", file=sys.stderr)
+ page_groups = cluster_page_groups(pages)
+
+ result = {
+ "site": args.site,
+ "period": {"start": start, "end": end, "days": args.days},
+ "summary": summary,
+ "top_queries": queries[:30],
+ "top_pages": pages[:30],
+ "position_buckets": {
+ k: sorted(v, key=lambda x: x["impressions"], reverse=True)[:20]
+ for k, v in buckets.items()
+ },
+ "ctr_opportunities": ctr_opportunities[:20],
+ "ctr_gaps_by_page": ctr_gaps_by_page,
+ "cannibalization": cannibalization,
+ "comparison": comparison,
+ "device_split": devices,
+ "country_split": countries,
+ "search_type_split": search_types,
+ "branded_split": branded_split,
+ "page_groups": page_groups
+ }
+
+ with open(args.output, "w") as f:
+ json.dump(result, f, indent=2)
+
+ print(f"\nDone. Results saved to {args.output}", file=sys.stderr)
+ print(f"\nSummary: {summary['clicks']:,} clicks | {summary['impressions']:,} impressions | "
+ f"CTR {summary['ctr']}% | Avg position {summary['position']}", file=sys.stderr)
+ if cannibalization:
+ print(f"Cannibalization: {len(cannibalization)} queries with competing pages found", file=sys.stderr)
+ if search_types:
+ type_summary = ", ".join(f"{t['type']}={t['clicks']:,}" for t in search_types)
+ print(f"Search types: {type_summary}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/seo/seo-analysis/scripts/cms_detect.py b/seo/seo-analysis/scripts/cms_detect.py
new file mode 100644
index 00000000..c5ec3239
--- /dev/null
+++ b/seo/seo-analysis/scripts/cms_detect.py
@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Detect which CMS is configured via environment variables.
+
+Checks for CMS-specific env vars and prints the detected CMS type to stdout.
+Used by seo-analysis to determine which preflight/fetch scripts to run.
+
+No external dependencies — uses only Python stdlib.
+
+Exit codes:
+ 0 — CMS found (prints: wordpress | contentful | ghost | strapi)
+ 2 — No CMS configured
+"""
+
+import os
+import sys
+
+
+def load_env_file(path):
+ env = {}
+ try:
+ with open(path) as f:
+ for line in f:
+ line = line.strip()
+ if not line or line.startswith("#") or "=" not in line:
+ continue
+ key, _, raw_value = line.partition("=")
+ key = key.strip()
+ value = raw_value.strip().strip('"').strip("'")
+ if key:
+ env[key] = value
+ except (OSError, PermissionError):
+ pass
+ return env
+
+
+def find_and_load_env():
+ env = {}
+ search = os.path.abspath(os.getcwd())
+ for _ in range(6):
+ for name in (".env.local", ".env"):
+ candidate = os.path.join(search, name)
+ if os.path.isfile(candidate):
+ env.update(load_env_file(candidate))
+ parent = os.path.dirname(search)
+ if parent == search:
+ break
+ search = parent
+ return env
+
+
+def main():
+ file_env = find_and_load_env()
+
+ def get(key):
+ return os.environ.get(key) or file_env.get(key, "")
+
+ # Check each CMS by its unique required env var.
+ # Order matters when multiple are set: prefer the most recently added CMSes
+ # (WordPress, Contentful, Ghost) over the original Strapi support, so that
+ # users who migrate don't silently fall back to Strapi.
+ if get("WP_URL"):
+ print("wordpress")
+ sys.exit(0)
+ if get("CONTENTFUL_SPACE_ID"):
+ print("contentful")
+ sys.exit(0)
+ if get("GHOST_URL"):
+ print("ghost")
+ sys.exit(0)
+ if get("STRAPI_URL"):
+ print("strapi")
+ sys.exit(0)
+
+ sys.exit(2)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/seo/seo-analysis/scripts/fetch_contentful_content.py b/seo/seo-analysis/scripts/fetch_contentful_content.py
new file mode 100644
index 00000000..f3cc4ed0
--- /dev/null
+++ b/seo/seo-analysis/scripts/fetch_contentful_content.py
@@ -0,0 +1,398 @@
+#!/usr/bin/env python3
+"""Fetch published content from Contentful for SEO analysis.
+
+Paginates through all entries of a content type, resolves linked SEO entries,
+and outputs structured JSON in the normalized CMS content format.
+
+Contentful's Delivery API only returns published content by default.
+No external dependencies — uses only Python stdlib.
+
+Usage:
+ python3 fetch_contentful_content.py
+ python3 fetch_contentful_content.py --content-type blogPost --output /tmp/cf.json
+
+Environment variables (or .env / .env.local):
+ CONTENTFUL_SPACE_ID Required. Space ID from Settings → General Settings.
+ CONTENTFUL_DELIVERY_TOKEN Required. Content Delivery API access token.
+ CONTENTFUL_CONTENT_TYPE Required. API Identifier for your content type.
+ CONTENTFUL_ENVIRONMENT Optional. Environment ID (default: master).
+"""
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+PAGE_SIZE = 1000 # Contentful max per request
+_RETRY_CODES = {429, 502, 503, 504}
+_CONTENTFUL_API = "https://cdn.contentful.com"
+
+
+# ── Config loading ────────────────────────────────────────────────────────────
+
+def load_env_file(path):
+ env = {}
+ try:
+ with open(path) as f:
+ for line in f:
+ line = line.strip()
+ if not line or line.startswith("#") or "=" not in line:
+ continue
+ key, _, raw_value = line.partition("=")
+ key = key.strip()
+ value = raw_value.strip().strip('"').strip("'")
+ if key:
+ env[key] = value
+ except (OSError, PermissionError):
+ pass
+ return env
+
+
+def find_and_load_env():
+ env = {}
+ search = os.path.abspath(os.getcwd())
+ for _ in range(6):
+ for name in (".env.local", ".env"):
+ candidate = os.path.join(search, name)
+ if os.path.isfile(candidate):
+ env.update(load_env_file(candidate))
+ parent = os.path.dirname(search)
+ if parent == search:
+ break
+ search = parent
+ return env
+
+
+def get_config():
+ file_env = find_and_load_env()
+
+ def get(key):
+ return os.environ.get(key) or file_env.get(key, "")
+
+ return (
+ get("CONTENTFUL_SPACE_ID"),
+ get("CONTENTFUL_DELIVERY_TOKEN"),
+ get("CONTENTFUL_CONTENT_TYPE"),
+ get("CONTENTFUL_ENVIRONMENT") or "master",
+ )
+
+
+# ── HTTP helper with retry ────────────────────────────────────────────────────
+
+def contentful_get(token, path, params=None, timeout=30, retries=3):
+ full_url = f"{_CONTENTFUL_API}{path}"
+ if params:
+ full_url = f"{full_url}?{urllib.parse.urlencode(params)}"
+ req = urllib.request.Request(
+ full_url,
+ headers={"Authorization": f"Bearer {token}"},
+ )
+ last_exc = None
+ for attempt in range(retries):
+ try:
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ return json.loads(resp.read())
+ except urllib.error.HTTPError as e:
+ if e.code in _RETRY_CODES and attempt < retries - 1:
+ wait = 2 ** attempt
+ print(f" HTTP {e.code} — retrying in {wait}s...", file=sys.stderr)
+ time.sleep(wait)
+ last_exc = e
+ continue
+ body = e.read().decode()[:200] if e.fp else "(no body)"
+ print(f"ERROR: Contentful API {e.code}: {body}", file=sys.stderr)
+ sys.exit(1)
+ except urllib.error.URLError as e:
+ if attempt < retries - 1:
+ wait = 2 ** attempt
+ print(f" Network error ({e.reason}) — retrying in {wait}s...", file=sys.stderr)
+ time.sleep(wait)
+ last_exc = e
+ continue
+ print(f"ERROR: Network error reaching Contentful: {e.reason}", file=sys.stderr)
+ sys.exit(1)
+ raise last_exc
+
+
+# ── SEO field extraction ──────────────────────────────────────────────────────
+
+def extract_seo_fields(fields, includes_by_id):
+ """Extract SEO meta title and description from a Contentful entry's fields.
+
+ Tries three patterns in priority order:
+ 1. Linked SEO entry: fields.seo → linked entry with fields.title + fields.description
+ 2. Direct SEO fields: fields.seoTitle, fields.metaTitle, fields.seo_title, etc.
+ 3. Content fields fallback: fields.title, fields.description, fields.excerpt
+ """
+ meta_title = ""
+ meta_description = ""
+ has_meta_image = False
+ has_meta_social = False
+
+ # Pattern 1: linked SEO component entry
+ seo_ref = fields.get("seo")
+ if isinstance(seo_ref, dict) and seo_ref.get("sys", {}).get("type") == "Link":
+ linked_id = seo_ref.get("sys", {}).get("id")
+ linked = includes_by_id.get(linked_id, {})
+ linked_fields = linked.get("fields", {})
+ meta_title = linked_fields.get("title") or linked_fields.get("metaTitle") or ""
+ meta_description = linked_fields.get("description") or linked_fields.get("metaDescription") or ""
+ has_meta_image = bool(linked_fields.get("image") or linked_fields.get("ogImage"))
+ has_meta_social = bool(linked_fields.get("openGraphTitle") or linked_fields.get("twitterTitle"))
+
+ # Pattern 2: direct SEO fields
+ if not meta_title:
+ meta_title = (
+ fields.get("seoTitle") or
+ fields.get("metaTitle") or
+ fields.get("seo_title") or
+ fields.get("meta_title") or
+ ""
+ )
+ if not meta_description:
+ meta_description = (
+ fields.get("seoDescription") or
+ fields.get("metaDescription") or
+ fields.get("seo_description") or
+ fields.get("meta_description") or
+ ""
+ )
+
+ # Do NOT fall back to fields["title"] — that's the content title, not an SEO
+ # meta title override. Entries without explicit SEO titles should be flagged
+ # as missing_meta_title=True so the audit surfaces them. The "title" field
+ # is preserved in the normalised entry for display purposes.
+
+ return {
+ "meta_title": meta_title,
+ "meta_description": meta_description,
+ "has_meta_image": has_meta_image,
+ "has_meta_social": has_meta_social,
+ }
+
+
+# ── Response normalisation ────────────────────────────────────────────────────
+
+def normalise_entry(item, includes_by_id):
+ """Normalise a Contentful entry to the shared CMS entry format."""
+ sys_data = item.get("sys", {})
+ fields = item.get("fields", {})
+
+ document_id = sys_data.get("id", "")
+ published_at = sys_data.get("createdAt") or "" # Delivery API = publishedAt equivalent
+ updated_at = sys_data.get("updatedAt") or ""
+ locale = sys_data.get("locale") or ""
+
+ # Slug: try slug, then title-derived, then id
+ slug = fields.get("slug") or fields.get("url") or fields.get("path") or ""
+ title = fields.get("title") or fields.get("name") or fields.get("heading") or ""
+
+ seo = extract_seo_fields(fields, includes_by_id)
+
+ meta_title_len = len(seo["meta_title"])
+ meta_desc_len = len(seo["meta_description"])
+
+ return {
+ "document_id": document_id,
+ "id": document_id,
+ "title": title,
+ "slug": slug,
+ "published_at": published_at,
+ "updated_at": updated_at,
+ "created_at": published_at,
+ "locale": locale,
+ "seo": seo,
+ "missing_meta_title": not seo["meta_title"],
+ "missing_meta_description": not seo["meta_description"],
+ "meta_title_too_long": meta_title_len > 60,
+ "meta_description_too_long": meta_desc_len > 160,
+ "meta_description_too_short": 0 < meta_desc_len < 70,
+ }
+
+
+# ── Pagination ────────────────────────────────────────────────────────────────
+
+def fetch_all_entries(space_id, token, content_type, environment):
+ """Paginate through all entries. Returns list of normalised entries."""
+ path = f"/spaces/{space_id}/environments/{environment}/entries"
+ all_entries = []
+ skip = 0
+ total = None
+
+ while True:
+ params = {
+ "content_type": content_type,
+ "limit": PAGE_SIZE,
+ "skip": skip,
+ "include": 1, # Resolve one level of linked entries (SEO components)
+ "order": "-sys.updatedAt",
+ }
+
+ page_num = skip // PAGE_SIZE + 1
+ print(f" Fetching page {page_num}...", file=sys.stderr)
+ data = contentful_get(token, path, params)
+
+ if total is None:
+ total = data.get("total", 0)
+ print(f" {total} entries total", file=sys.stderr)
+
+ items = data.get("items", [])
+ if not items:
+ break
+
+ # Build a lookup of included entries (linked SEO components, etc.)
+ includes = data.get("includes", {})
+ includes_by_id = {}
+ for entry in includes.get("Entry", []):
+ entry_id = entry.get("sys", {}).get("id")
+ if entry_id:
+ includes_by_id[entry_id] = entry
+ for asset in includes.get("Asset", []):
+ asset_id = asset.get("sys", {}).get("id")
+ if asset_id:
+ includes_by_id[asset_id] = asset
+
+ for item in items:
+ all_entries.append(normalise_entry(item, includes_by_id))
+
+ skip += len(items)
+ print(f" {len(all_entries)}/{total} entries fetched", file=sys.stderr)
+
+ if skip >= total:
+ break
+
+ return all_entries
+
+
+# ── SEO audit ─────────────────────────────────────────────────────────────────
+
+def build_seo_audit(entries):
+ missing_title = []
+ missing_desc = []
+ title_long = []
+ desc_too_long = []
+ desc_too_short = []
+ broken_ids = set()
+
+ for e in entries:
+ broken = False
+ if e["missing_meta_title"]:
+ missing_title.append(e)
+ broken = True
+ if e["missing_meta_description"]:
+ missing_desc.append(e)
+ broken = True
+ if e["meta_title_too_long"]:
+ title_long.append(e)
+ broken = True
+ if e["meta_description_too_long"]:
+ desc_too_long.append(e)
+ broken = True
+ if e["meta_description_too_short"]:
+ desc_too_short.append(e)
+ broken = True
+ if broken:
+ broken_ids.add(e["document_id"])
+
+ return {
+ "total": len(entries),
+ "missing_meta_title": len(missing_title),
+ "missing_meta_description": len(missing_desc),
+ "meta_title_too_long": len(title_long),
+ "meta_description_too_short": len(desc_too_short),
+ "meta_description_too_long": len(desc_too_long),
+ "complete_seo": len(entries) - len(broken_ids),
+ "entries_missing_meta_title": [
+ {"document_id": e["document_id"], "title": e["title"], "slug": e["slug"]}
+ for e in missing_title[:20]
+ ],
+ "entries_missing_meta_description": [
+ {"document_id": e["document_id"], "title": e["title"], "slug": e["slug"]}
+ for e in missing_desc[:20]
+ ],
+ "entries_title_too_long": [
+ {
+ "document_id": e["document_id"],
+ "title": e["title"],
+ "meta_title": e["seo"]["meta_title"],
+ "length": len(e["seo"]["meta_title"]),
+ }
+ for e in title_long[:20]
+ ],
+ }
+
+
+def main():
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--content-type", help="Override CONTENTFUL_CONTENT_TYPE env var")
+ parser.add_argument("--output", help="Output JSON file path (default: secure tempfile)")
+ args = parser.parse_args()
+
+ space_id, token, content_type, environment = get_config()
+ if args.content_type:
+ content_type = args.content_type
+
+ if not space_id:
+ print("CONTENTFUL_NOT_CONFIGURED: Set CONTENTFUL_SPACE_ID and CONTENTFUL_DELIVERY_TOKEN.", file=sys.stderr)
+ sys.exit(2)
+ if not token:
+ print("ERROR: CONTENTFUL_DELIVERY_TOKEN is not set.", file=sys.stderr)
+ sys.exit(1)
+ if not content_type:
+ print("ERROR: CONTENTFUL_CONTENT_TYPE is not set.", file=sys.stderr)
+ sys.exit(1)
+
+ print(f"Fetching {content_type} from Contentful space {space_id}...", file=sys.stderr)
+ entries = fetch_all_entries(space_id, token, content_type, environment)
+
+ seo_audit = build_seo_audit(entries)
+
+ result = {
+ "cms_type": "contentful",
+ "cms_url": f"https://app.contentful.com/spaces/{space_id}",
+ "content_type": content_type,
+ "total_published": len(entries),
+ "seo_audit": seo_audit,
+ "entries": entries,
+ }
+
+ if args.output:
+ out_path = args.output
+ out_dir = os.path.dirname(out_path) or "."
+ else:
+ out_dir = tempfile.gettempdir()
+ out_path = os.path.join(out_dir, f"cms_content_{os.getuid()}.json")
+
+ fd, tmp_path = tempfile.mkstemp(dir=out_dir, suffix=".json.tmp")
+ try:
+ os.chmod(tmp_path, 0o600)
+ with os.fdopen(fd, "w") as f:
+ json.dump(result, f, indent=2)
+ os.replace(tmp_path, out_path)
+ except Exception:
+ os.unlink(tmp_path)
+ raise
+
+ print(f"\nDone. {len(entries)} entries saved to {out_path}", file=sys.stderr)
+ print(
+ f"SEO completeness: {seo_audit['complete_seo']}/{seo_audit['total']} entries fully complete",
+ file=sys.stderr,
+ )
+ if seo_audit["missing_meta_title"]:
+ print(f" Missing meta title: {seo_audit['missing_meta_title']}", file=sys.stderr)
+ if seo_audit["missing_meta_description"]:
+ print(f" Missing meta description: {seo_audit['missing_meta_description']}", file=sys.stderr)
+ if seo_audit["meta_title_too_long"]:
+ print(f" Meta title too long (>60): {seo_audit['meta_title_too_long']}", file=sys.stderr)
+ if seo_audit["meta_description_too_short"]:
+ print(f" Meta desc too short (<70): {seo_audit['meta_description_too_short']}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/seo/seo-analysis/scripts/fetch_ghost_content.py b/seo/seo-analysis/scripts/fetch_ghost_content.py
new file mode 100644
index 00000000..df12365f
--- /dev/null
+++ b/seo/seo-analysis/scripts/fetch_ghost_content.py
@@ -0,0 +1,403 @@
+#!/usr/bin/env python3
+"""Fetch published content from Ghost for SEO analysis.
+
+Paginates through all published posts or pages, extracts Ghost's native SEO
+fields (meta_title, meta_description), and outputs structured JSON in the
+normalized CMS content format consumed by seo-analysis.
+
+Ghost has native meta_title and meta_description fields on every post/page —
+no plugin needed.
+
+Supports Ghost 4.x+ (/ghost/api/content/) and 3.x (/ghost/api/v3/content/).
+No external dependencies — uses only Python stdlib.
+
+Usage:
+ python3 fetch_ghost_content.py
+ python3 fetch_ghost_content.py --content-type pages --output /tmp/ghost.json
+
+Environment variables (or .env / .env.local):
+ GHOST_URL Required. Ghost instance URL, e.g. https://myblog.ghost.io
+ GHOST_CONTENT_KEY Required. Content API key from Settings → Integrations.
+ GHOST_CONTENT_TYPE Optional. 'posts' or 'pages' (default: posts)
+"""
+
+import argparse
+import ipaddress
+import json
+import os
+import socket
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+PAGE_SIZE = 100 # Ghost supports up to at least 100 per request
+_RETRY_CODES = {429, 502, 503, 504}
+_API_PATHS = ["/ghost/api/content", "/ghost/api/v3/content"]
+
+_SEO_FIELDS = "id,title,slug,published_at,updated_at,meta_title,meta_description,og_image,og_title,og_description,twitter_title,twitter_description"
+
+
+# ── Config loading ────────────────────────────────────────────────────────────
+
+def load_env_file(path):
+ env = {}
+ try:
+ with open(path) as f:
+ for line in f:
+ line = line.strip()
+ if not line or line.startswith("#") or "=" not in line:
+ continue
+ key, _, raw_value = line.partition("=")
+ key = key.strip()
+ value = raw_value.strip().strip('"').strip("'")
+ if key:
+ env[key] = value
+ except (OSError, PermissionError):
+ pass
+ return env
+
+
+def find_and_load_env():
+ env = {}
+ search = os.path.abspath(os.getcwd())
+ for _ in range(6):
+ for name in (".env.local", ".env"):
+ candidate = os.path.join(search, name)
+ if os.path.isfile(candidate):
+ env.update(load_env_file(candidate))
+ parent = os.path.dirname(search)
+ if parent == search:
+ break
+ search = parent
+ return env
+
+
+def get_config():
+ file_env = find_and_load_env()
+
+ def get(key):
+ return os.environ.get(key) or file_env.get(key, "")
+
+ return (
+ get("GHOST_URL").rstrip("/"),
+ get("GHOST_CONTENT_KEY"),
+ get("GHOST_CONTENT_TYPE") or "posts",
+ )
+
+
+def _is_private_ip(ip_str):
+ try:
+ addr = ipaddress.ip_address(ip_str)
+ return addr.is_loopback or addr.is_private or addr.is_link_local or addr.is_reserved
+ except ValueError:
+ return False
+
+
+def validate_url(url):
+ try:
+ parsed = urllib.parse.urlparse(url)
+ except Exception:
+ print("ERROR: GHOST_URL is not a valid URL.", file=sys.stderr)
+ sys.exit(1)
+ if parsed.scheme not in ("http", "https"):
+ print("ERROR: GHOST_URL must use http:// or https://", file=sys.stderr)
+ sys.exit(1)
+ hostname = parsed.hostname or ""
+ if not hostname:
+ print("ERROR: GHOST_URL has no hostname.", file=sys.stderr)
+ sys.exit(1)
+ if _is_private_ip(hostname):
+ print(f"ERROR: GHOST_URL is a private/local address ('{hostname}').", file=sys.stderr)
+ sys.exit(1)
+ if hostname.lower() == "localhost":
+ print("ERROR: GHOST_URL points to localhost.", file=sys.stderr)
+ sys.exit(1)
+ try:
+ for info in socket.getaddrinfo(hostname, None, type=socket.SOCK_STREAM):
+ if _is_private_ip(info[4][0]):
+ print(f"ERROR: GHOST_URL resolves to an internal address ({info[4][0]}).", file=sys.stderr)
+ sys.exit(1)
+ except (socket.gaierror, OSError):
+ pass
+
+
+# ── HTTP helper with retry ────────────────────────────────────────────────────
+
+def ghost_get(base_url, api_path, content_key, resource, params, timeout=30, retries=3):
+ all_params = {"key": content_key, **params}
+ full_url = f"{base_url}{api_path}/{resource}/?{urllib.parse.urlencode(all_params)}"
+ req = urllib.request.Request(full_url, headers={"Accept-Version": "v5.0"})
+ last_exc = None
+ for attempt in range(retries):
+ try:
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ return json.loads(resp.read())
+ except urllib.error.HTTPError as e:
+ if e.code in _RETRY_CODES and attempt < retries - 1:
+ wait = 2 ** attempt
+ print(f" HTTP {e.code} — retrying in {wait}s...", file=sys.stderr)
+ time.sleep(wait)
+ last_exc = e
+ continue
+ body = e.read().decode()[:200] if e.fp else "(no body)"
+ print(f"ERROR: Ghost API {e.code}: {body}", file=sys.stderr)
+ sys.exit(1)
+ except urllib.error.URLError as e:
+ if attempt < retries - 1:
+ wait = 2 ** attempt
+ print(f" Network error ({e.reason}) — retrying in {wait}s...", file=sys.stderr)
+ time.sleep(wait)
+ last_exc = e
+ continue
+ print(f"ERROR: Network error reaching Ghost: {e.reason}", file=sys.stderr)
+ sys.exit(1)
+ raise last_exc
+
+
+def detect_api_path(base_url, content_key, content_type):
+ """Try API paths in order, return the first that works.
+
+ Uses a direct urllib probe so that 404s on the first path don't terminate
+ the process — ghost_get calls sys.exit on errors, which would prevent
+ the fallback from running.
+ """
+ for api_path in _API_PATHS:
+ try:
+ url = (
+ f"{base_url}{api_path}/{content_type}/?"
+ f"{urllib.parse.urlencode({'key': content_key, 'limit': 1, 'fields': 'id'})}"
+ )
+ req = urllib.request.Request(url, headers={"Accept-Version": "v5.0"})
+ with urllib.request.urlopen(req, timeout=10) as resp:
+ resp.read()
+ return api_path
+ except urllib.error.HTTPError as e:
+ if e.code == 403:
+ print("ERROR: Ghost returned 403 Forbidden.", file=sys.stderr)
+ print("Your GHOST_CONTENT_KEY is invalid or has been revoked.", file=sys.stderr)
+ print("Regenerate it in: Settings → Integrations", file=sys.stderr)
+ sys.exit(1)
+ # 404 = wrong API path; try next
+ continue
+ except urllib.error.URLError as e:
+ print(f"ERROR: Cannot reach Ghost at {base_url}", file=sys.stderr)
+ print(f" Network error: {e.reason}", file=sys.stderr)
+ sys.exit(1)
+ print(f"ERROR: Could not find Ghost Content API at {base_url}", file=sys.stderr)
+ print("Check that GHOST_URL points to your Ghost instance.", file=sys.stderr)
+ sys.exit(1)
+
+
+# ── Response normalisation ────────────────────────────────────────────────────
+
+def normalise_entry(item):
+ """Normalise a Ghost post/page to the shared CMS entry format."""
+ # Ghost returns null for meta_title/meta_description when not explicitly set.
+ # Do NOT fall back to item["title"] here — that would hide the fact that no
+ # SEO override exists, causing missing_meta_title to be False for posts that
+ # have never been SEO-optimized. The entry's "title" field is preserved
+ # separately for display purposes.
+ meta_title = item.get("meta_title") or ""
+ meta_description = item.get("meta_description") or ""
+ has_meta_image = bool(item.get("og_image"))
+ has_meta_social = bool(item.get("og_title") or item.get("twitter_title"))
+
+ seo = {
+ "meta_title": meta_title,
+ "meta_description": meta_description,
+ "has_meta_image": has_meta_image,
+ "has_meta_social": has_meta_social,
+ }
+
+ meta_title_len = len(seo["meta_title"])
+ meta_desc_len = len(seo["meta_description"])
+
+ return {
+ "document_id": item.get("id", ""),
+ "id": item.get("id"),
+ "title": item.get("title") or "",
+ "slug": item.get("slug") or "",
+ "published_at": item.get("published_at") or "",
+ "updated_at": item.get("updated_at") or "",
+ "created_at": item.get("published_at") or "",
+ "locale": "",
+ "seo": seo,
+ "missing_meta_title": not meta_title,
+ "missing_meta_description": not meta_description,
+ "meta_title_too_long": meta_title_len > 60,
+ "meta_description_too_long": meta_desc_len > 160,
+ "meta_description_too_short": 0 < meta_desc_len < 70,
+ }
+
+
+# ── Pagination ────────────────────────────────────────────────────────────────
+
+def fetch_all_entries(base_url, content_key, content_type):
+ """Paginate through all published entries. Returns list of normalised entries."""
+ api_path = detect_api_path(base_url, content_key, content_type)
+ all_entries = []
+ page = 1
+ total_pages = None
+
+ while True:
+ params = {
+ "limit": PAGE_SIZE,
+ "page": page,
+ "fields": _SEO_FIELDS,
+ "order": "published_at desc",
+ }
+
+ print(f" Fetching page {page}...", file=sys.stderr)
+ data = ghost_get(base_url, api_path, content_key, content_type, params)
+
+ items = data.get(content_type, [])
+ if not items:
+ break
+
+ pagination = data.get("meta", {}).get("pagination", {})
+ if total_pages is None:
+ total_pages = pagination.get("pages", 1)
+ total = pagination.get("total", 0)
+ print(f" {total} published {content_type} across {total_pages} page(s)", file=sys.stderr)
+
+ for item in items:
+ all_entries.append(normalise_entry(item))
+
+ print(f" Page {page}/{total_pages} — {len(all_entries)} fetched", file=sys.stderr)
+
+ if page >= total_pages:
+ break
+ page += 1
+
+ return all_entries
+
+
+# ── SEO audit ─────────────────────────────────────────────────────────────────
+
+def build_seo_audit(entries):
+ missing_title = []
+ missing_desc = []
+ title_long = []
+ desc_too_long = []
+ desc_too_short = []
+ broken_ids = set()
+
+ for e in entries:
+ broken = False
+ if e["missing_meta_title"]:
+ missing_title.append(e)
+ broken = True
+ if e["missing_meta_description"]:
+ missing_desc.append(e)
+ broken = True
+ if e["meta_title_too_long"]:
+ title_long.append(e)
+ broken = True
+ if e["meta_description_too_long"]:
+ desc_too_long.append(e)
+ broken = True
+ if e["meta_description_too_short"]:
+ desc_too_short.append(e)
+ broken = True
+ if broken:
+ broken_ids.add(e["document_id"])
+
+ return {
+ "total": len(entries),
+ "missing_meta_title": len(missing_title),
+ "missing_meta_description": len(missing_desc),
+ "meta_title_too_long": len(title_long),
+ "meta_description_too_short": len(desc_too_short),
+ "meta_description_too_long": len(desc_too_long),
+ "complete_seo": len(entries) - len(broken_ids),
+ "entries_missing_meta_title": [
+ {"document_id": e["document_id"], "title": e["title"], "slug": e["slug"]}
+ for e in missing_title[:20]
+ ],
+ "entries_missing_meta_description": [
+ {"document_id": e["document_id"], "title": e["title"], "slug": e["slug"]}
+ for e in missing_desc[:20]
+ ],
+ "entries_title_too_long": [
+ {
+ "document_id": e["document_id"],
+ "title": e["title"],
+ "meta_title": e["seo"]["meta_title"],
+ "length": len(e["seo"]["meta_title"]),
+ }
+ for e in title_long[:20]
+ ],
+ }
+
+
+def main():
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--content-type", help="Override GHOST_CONTENT_TYPE (posts or pages)")
+ parser.add_argument("--output", help="Output JSON file path (default: secure tempfile)")
+ args = parser.parse_args()
+
+ base_url, content_key, content_type = get_config()
+ if args.content_type:
+ content_type = args.content_type
+
+ if not base_url:
+ print("GHOST_NOT_CONFIGURED: Set GHOST_URL and GHOST_CONTENT_KEY to enable Ghost integration.", file=sys.stderr)
+ sys.exit(2)
+ if not content_key:
+ print("ERROR: GHOST_CONTENT_KEY is not set.", file=sys.stderr)
+ sys.exit(1)
+
+ validate_url(base_url)
+
+ print(f"Fetching {content_type} from {base_url}...", file=sys.stderr)
+ entries = fetch_all_entries(base_url, content_key, content_type)
+
+ seo_audit = build_seo_audit(entries)
+
+ result = {
+ "cms_type": "ghost",
+ "cms_url": base_url,
+ "content_type": content_type,
+ "total_published": len(entries),
+ "seo_audit": seo_audit,
+ "entries": entries,
+ }
+
+ if args.output:
+ out_path = args.output
+ out_dir = os.path.dirname(out_path) or "."
+ else:
+ out_dir = tempfile.gettempdir()
+ out_path = os.path.join(out_dir, f"cms_content_{os.getuid()}.json")
+
+ fd, tmp_path = tempfile.mkstemp(dir=out_dir, suffix=".json.tmp")
+ try:
+ os.chmod(tmp_path, 0o600)
+ with os.fdopen(fd, "w") as f:
+ json.dump(result, f, indent=2)
+ os.replace(tmp_path, out_path)
+ except Exception:
+ os.unlink(tmp_path)
+ raise
+
+ print(f"\nDone. {len(entries)} entries saved to {out_path}", file=sys.stderr)
+ print(
+ f"SEO completeness: {seo_audit['complete_seo']}/{seo_audit['total']} entries fully complete",
+ file=sys.stderr,
+ )
+ if seo_audit["missing_meta_title"]:
+ print(f" Missing meta title: {seo_audit['missing_meta_title']}", file=sys.stderr)
+ if seo_audit["missing_meta_description"]:
+ print(f" Missing meta description: {seo_audit['missing_meta_description']}", file=sys.stderr)
+ if seo_audit["meta_title_too_long"]:
+ print(f" Meta title too long (>60): {seo_audit['meta_title_too_long']}", file=sys.stderr)
+ if seo_audit["meta_description_too_short"]:
+ print(f" Meta desc too short (<70): {seo_audit['meta_description_too_short']}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/seo/seo-analysis/scripts/fetch_strapi_content.py b/seo/seo-analysis/scripts/fetch_strapi_content.py
new file mode 100644
index 00000000..4f6a811e
--- /dev/null
+++ b/seo/seo-analysis/scripts/fetch_strapi_content.py
@@ -0,0 +1,437 @@
+#!/usr/bin/env python3
+"""Fetch published content from Strapi for SEO analysis.
+
+Paginates through all published entries, extracts SEO fields (official
+strapi-community/plugin-seo component + common custom field names),
+and outputs structured JSON for the seo-analysis skill.
+
+Supports Strapi v4 (nested attributes) and v5 (flat response).
+No external dependencies — uses only Python stdlib.
+
+Usage:
+ python3 fetch_strapi_content.py
+ python3 fetch_strapi_content.py --content-type blog-posts --output /tmp/strapi.json
+
+Environment variables (or .env / .env.local):
+ STRAPI_URL Required. Base URL, e.g. https://cms.example.com
+ STRAPI_API_KEY Required. Full-access API token.
+ STRAPI_CONTENT_TYPE Optional. Plural API ID (default: articles)
+ STRAPI_VERSION Optional. Force '4' or '5' if auto-detection is wrong.
+"""
+
+import argparse
+import ipaddress
+import json
+import os
+import socket
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+PAGE_SIZE = 100 # Strapi default max; configurable up to 250 in config/api.js
+
+_RETRY_CODES = {429, 502, 503, 504}
+
+
+# ── SSRF protection ───────────────────────────────────────────────────────────
+
+def _is_private_ip(ip_str):
+ try:
+ addr = ipaddress.ip_address(ip_str)
+ return addr.is_loopback or addr.is_private or addr.is_link_local or addr.is_reserved
+ except ValueError:
+ return False
+
+
+def validate_url(url):
+ """Block SSRF targets. Called before any HTTP requests are made."""
+ try:
+ parsed = urllib.parse.urlparse(url)
+ except Exception:
+ print("ERROR: STRAPI_URL is not a valid URL.", file=sys.stderr)
+ sys.exit(1)
+ if parsed.scheme not in ("http", "https"):
+ print(f"ERROR: STRAPI_URL must use http:// or https://", file=sys.stderr)
+ sys.exit(1)
+ hostname = parsed.hostname or ""
+ if not hostname:
+ print("ERROR: STRAPI_URL has no hostname.", file=sys.stderr)
+ sys.exit(1)
+ if _is_private_ip(hostname):
+ print(f"ERROR: STRAPI_URL is a private/local address ('{hostname}').", file=sys.stderr)
+ sys.exit(1)
+ if hostname.lower() == "localhost":
+ print("ERROR: STRAPI_URL points to localhost.", file=sys.stderr)
+ sys.exit(1)
+ # DNS-based check (best-effort)
+ try:
+ for info in socket.getaddrinfo(hostname, None, type=socket.SOCK_STREAM):
+ if _is_private_ip(info[4][0]):
+ print(f"ERROR: STRAPI_URL resolves to an internal address ({info[4][0]}).", file=sys.stderr)
+ sys.exit(1)
+ except (socket.gaierror, OSError):
+ pass # non-fatal; let the request fail naturally
+
+
+# ── Config loading ────────────────────────────────────────────────────────────
+
+def load_env_file(path):
+ env = {}
+ try:
+ with open(path) as f:
+ for line in f:
+ line = line.strip()
+ if not line or line.startswith("#") or "=" not in line:
+ continue
+ key, _, raw_value = line.partition("=")
+ key = key.strip()
+ value = raw_value.strip().strip('"').strip("'")
+ if key:
+ env[key] = value
+ except (OSError, PermissionError):
+ pass
+ return env
+
+
+def find_and_load_env():
+ env = {}
+ search = os.path.abspath(os.getcwd())
+ for _ in range(6):
+ for name in (".env.local", ".env"):
+ candidate = os.path.join(search, name)
+ if os.path.isfile(candidate):
+ env.update(load_env_file(candidate))
+ parent = os.path.dirname(search)
+ if parent == search:
+ break
+ search = parent
+ return env
+
+
+def get_config():
+ file_env = find_and_load_env()
+
+ def get(key):
+ return os.environ.get(key) or file_env.get(key, "")
+
+ return (
+ get("STRAPI_URL").rstrip("/"),
+ get("STRAPI_API_KEY"),
+ get("STRAPI_CONTENT_TYPE") or "articles",
+ get("STRAPI_VERSION"), # "4" or "5" explicit override
+ )
+
+
+# ── HTTP helper with retry ────────────────────────────────────────────────────
+
+def strapi_get(base_url, api_key, path, params, timeout=30, retries=3):
+ full_url = f"{base_url}{path}?{urllib.parse.urlencode(params)}"
+ req = urllib.request.Request(
+ full_url,
+ headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+ )
+ last_exc = None
+ for attempt in range(retries):
+ try:
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ return json.loads(resp.read())
+ except urllib.error.HTTPError as e:
+ if e.code in _RETRY_CODES and attempt < retries - 1:
+ wait = 2 ** attempt
+ print(f" HTTP {e.code} on page — retrying in {wait}s...", file=sys.stderr)
+ time.sleep(wait)
+ last_exc = e
+ continue
+ body = e.read().decode()[:200] if e.fp else "(no body)"
+ print(f"ERROR: Strapi API {e.code} on {path}: {body}", file=sys.stderr)
+ sys.exit(1)
+ except urllib.error.URLError as e:
+ if attempt < retries - 1:
+ wait = 2 ** attempt
+ print(f" Network error ({e.reason}) — retrying in {wait}s...", file=sys.stderr)
+ time.sleep(wait)
+ last_exc = e
+ continue
+ print(f"ERROR: Network error on {base_url}{path}: {e.reason}", file=sys.stderr)
+ sys.exit(1)
+ raise last_exc
+
+
+# ── Version detection ─────────────────────────────────────────────────────────
+
+def detect_version(data, version_hint):
+ """Return 4 or 5. Explicit hint wins; otherwise infer from response structure."""
+ if version_hint in ("4", "5"):
+ return int(version_hint)
+ items = data.get("data", [])
+ if items:
+ return 4 if "attributes" in items[0] else 5
+ # Empty collection: fall back to v5. Set STRAPI_VERSION=4 to override.
+ return 5
+
+
+def publication_params(version):
+ """Return the correct publication filter for the Strapi version."""
+ if version == 4:
+ return {"publicationState": "live"}
+ return {"status": "published"}
+
+
+# ── Response normalisation ────────────────────────────────────────────────────
+
+def extract_seo_component(seo_val):
+ """Normalise the SEO component from plugin-seo. Returns {} if absent."""
+ if not seo_val or not isinstance(seo_val, dict):
+ return {}
+ # v4 may wrap under .data.attributes; v5 is already flat
+ attrs = seo_val.get("attributes", seo_val)
+ return {
+ "meta_title": attrs.get("metaTitle") or "",
+ "meta_description": attrs.get("metaDescription") or "",
+ "has_meta_image": bool(attrs.get("metaImage")),
+ "has_meta_social": bool(attrs.get("metaSocial")),
+ }
+
+
+def normalise_entry(raw, v4):
+ """Return a flat dict regardless of v4/v5 response format."""
+ if v4:
+ document_id = str(raw.get("id", ""))
+ attrs = raw.get("attributes", {})
+ else:
+ document_id = raw.get("documentId", "")
+ attrs = raw
+
+ item_id = raw.get("id")
+ title = attrs.get("title") or attrs.get("name") or attrs.get("heading") or ""
+ slug = attrs.get("slug") or attrs.get("url") or ""
+ published_at = attrs.get("publishedAt") or ""
+ updated_at = attrs.get("updatedAt") or ""
+ created_at = attrs.get("createdAt") or ""
+ locale = attrs.get("locale") or ""
+
+ # Official plugin-seo component
+ seo_component = extract_seo_component(attrs.get("seo"))
+
+ # Fallback: common root-level custom fields when plugin is not installed
+ if not seo_component.get("meta_title"):
+ seo_component["meta_title"] = (
+ attrs.get("metaTitle") or attrs.get("seoTitle") or
+ attrs.get("meta_title") or attrs.get("seo_title") or ""
+ )
+ if not seo_component.get("meta_description"):
+ seo_component["meta_description"] = (
+ attrs.get("metaDescription") or attrs.get("seoDescription") or
+ attrs.get("meta_description") or attrs.get("seo_description") or ""
+ )
+
+ # Detect which schema was used — push_strapi_seo.py needs this to write correctly
+ seo_schema = "component" if attrs.get("seo") else "root_fields"
+
+ meta_title_len = len(seo_component.get("meta_title", ""))
+ meta_desc_len = len(seo_component.get("meta_description", ""))
+
+ return {
+ "document_id": document_id,
+ "id": item_id,
+ "title": title,
+ "slug": slug,
+ "published_at": published_at,
+ "updated_at": updated_at,
+ "created_at": created_at,
+ "locale": locale,
+ "seo": seo_component,
+ "seo_schema": seo_schema, # "component" | "root_fields"
+ "missing_meta_title": not seo_component.get("meta_title"),
+ "missing_meta_description": not seo_component.get("meta_description"),
+ "meta_title_too_long": meta_title_len > 60,
+ "meta_description_too_long": meta_desc_len > 160,
+ "meta_description_too_short": 0 < meta_desc_len < 70,
+ }
+
+
+# ── Pagination ────────────────────────────────────────────────────────────────
+
+def fetch_all_entries(base_url, api_key, content_type, version_hint):
+ """Paginate through all published entries. Returns (entries, strapi_version)."""
+ path = f"/api/{content_type}"
+ all_entries = []
+
+ # Version detection: skip probe when version_hint is already explicit
+ if version_hint in ("4", "5"):
+ strapi_version = int(version_hint)
+ print(f" Strapi v{strapi_version} (from STRAPI_VERSION)", file=sys.stderr)
+ else:
+ # Probe without publication filter so response structure reveals v4 vs v5
+ probe_data = strapi_get(base_url, api_key, path, {"pagination[page]": 1, "pagination[pageSize]": 1})
+ strapi_version = detect_version(probe_data, version_hint)
+ print(f" Strapi v{strapi_version} detected", file=sys.stderr)
+
+ pub_filter = publication_params(strapi_version)
+ page = 1
+
+ while True:
+ params = {
+ "populate": "seo,seo.metaImage,seo.metaSocial",
+ **pub_filter,
+ "pagination[page]": page,
+ "pagination[pageSize]": PAGE_SIZE,
+ "sort[0]": "publishedAt:desc",
+ }
+
+ print(f" Fetching page {page}...", file=sys.stderr)
+ data = strapi_get(base_url, api_key, path, params)
+
+ items = data.get("data", [])
+ if not items:
+ break
+
+ for raw in items:
+ all_entries.append(normalise_entry(raw, v4=(strapi_version == 4)))
+
+ pagination = data.get("meta", {}).get("pagination", {})
+ page_count = pagination.get("pageCount", 1)
+ total = pagination.get("total", len(all_entries))
+
+ print(
+ f" Page {page}/{page_count} — {len(all_entries)}/{total} entries fetched",
+ file=sys.stderr,
+ )
+
+ if page >= page_count:
+ break
+ page += 1
+
+ return all_entries, strapi_version
+
+
+# ── SEO completeness audit ────────────────────────────────────────────────────
+
+def build_seo_audit(entries):
+ missing_title = []
+ missing_desc = []
+ title_long = []
+ desc_too_long = []
+ desc_too_short = []
+ broken_ids = set()
+
+ for e in entries:
+ broken = False
+ if e["missing_meta_title"]:
+ missing_title.append(e)
+ broken = True
+ if e["missing_meta_description"]:
+ missing_desc.append(e)
+ broken = True
+ if e["meta_title_too_long"]:
+ title_long.append(e)
+ broken = True
+ if e["meta_description_too_long"]:
+ desc_too_long.append(e)
+ broken = True
+ if e["meta_description_too_short"]:
+ desc_too_short.append(e)
+ broken = True
+ if broken:
+ broken_ids.add(e["document_id"])
+
+ return {
+ "total": len(entries),
+ "missing_meta_title": len(missing_title),
+ "missing_meta_description": len(missing_desc),
+ "meta_title_too_long": len(title_long),
+ "meta_description_too_short": len(desc_too_short),
+ "meta_description_too_long": len(desc_too_long),
+ "complete_seo": len(entries) - len(broken_ids),
+ "entries_missing_meta_title": [
+ {"document_id": e["document_id"], "title": e["title"], "slug": e["slug"]}
+ for e in missing_title[:20]
+ ],
+ "entries_missing_meta_description": [
+ {"document_id": e["document_id"], "title": e["title"], "slug": e["slug"]}
+ for e in missing_desc[:20]
+ ],
+ "entries_title_too_long": [
+ {
+ "document_id": e["document_id"],
+ "title": e["title"],
+ "meta_title": e["seo"]["meta_title"],
+ "length": len(e["seo"]["meta_title"]),
+ }
+ for e in title_long[:20]
+ ],
+ }
+
+
+def main():
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--content-type", help="Override STRAPI_CONTENT_TYPE env var")
+ parser.add_argument("--output", help="Output JSON file path (default: secure tempfile)")
+ args = parser.parse_args()
+
+ base_url, api_key, content_type, version_hint = get_config()
+ if args.content_type:
+ content_type = args.content_type
+
+ if not base_url:
+ print("STRAPI_NOT_CONFIGURED: Set STRAPI_URL and STRAPI_API_KEY to enable Strapi integration.", file=sys.stderr)
+ sys.exit(2)
+ if not api_key:
+ print("ERROR: STRAPI_API_KEY is not set.", file=sys.stderr)
+ sys.exit(1)
+
+ validate_url(base_url)
+
+ print(f"Fetching {content_type} from {base_url}...", file=sys.stderr)
+ entries, version = fetch_all_entries(base_url, api_key, content_type, version_hint)
+
+ seo_audit = build_seo_audit(entries)
+
+ result = {
+ "strapi_url": base_url,
+ "content_type": content_type,
+ "strapi_version": version,
+ "total_published": len(entries),
+ "seo_audit": seo_audit,
+ "entries": entries,
+ }
+
+ # Atomic write to a private tempfile, then rename into place
+ if args.output:
+ out_path = args.output
+ out_dir = os.path.dirname(out_path) or "."
+ else:
+ out_dir = tempfile.gettempdir()
+ out_path = os.path.join(out_dir, f"strapi_content_{os.getuid()}.json")
+
+ fd, tmp_path = tempfile.mkstemp(dir=out_dir, suffix=".json.tmp")
+ try:
+ os.chmod(tmp_path, 0o600)
+ with os.fdopen(fd, "w") as f:
+ json.dump(result, f, indent=2)
+ os.replace(tmp_path, out_path)
+ except Exception:
+ os.unlink(tmp_path)
+ raise
+
+ print(f"\nDone. {len(entries)} entries saved to {out_path}", file=sys.stderr)
+ print(
+ f"SEO completeness: {seo_audit['complete_seo']}/{seo_audit['total']} entries fully complete",
+ file=sys.stderr,
+ )
+ if seo_audit["missing_meta_title"]:
+ print(f" Missing meta title: {seo_audit['missing_meta_title']}", file=sys.stderr)
+ if seo_audit["missing_meta_description"]:
+ print(f" Missing meta description: {seo_audit['missing_meta_description']}", file=sys.stderr)
+ if seo_audit["meta_title_too_long"]:
+ print(f" Meta title too long (>60): {seo_audit['meta_title_too_long']}", file=sys.stderr)
+ if seo_audit["meta_description_too_short"]:
+ print(f" Meta desc too short (<70): {seo_audit['meta_description_too_short']}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/seo/seo-analysis/scripts/fetch_wordpress_content.py b/seo/seo-analysis/scripts/fetch_wordpress_content.py
new file mode 100644
index 00000000..30eff026
--- /dev/null
+++ b/seo/seo-analysis/scripts/fetch_wordpress_content.py
@@ -0,0 +1,416 @@
+#!/usr/bin/env python3
+"""Fetch published content from WordPress REST API for SEO analysis.
+
+Paginates through all published posts (or pages/custom types), extracts SEO
+fields from Yoast SEO or RankMath if present, and outputs structured JSON
+in the normalized CMS content format consumed by seo-analysis.
+
+No external dependencies — uses only Python stdlib.
+
+Usage:
+ python3 fetch_wordpress_content.py
+ python3 fetch_wordpress_content.py --content-type pages --output /tmp/wp.json
+
+Environment variables (or .env / .env.local):
+ WP_URL Required. Base URL, e.g. https://myblog.com
+ WP_USERNAME Required. WordPress username.
+ WP_APP_PASSWORD Required. Application Password (spaces OK).
+ WP_CONTENT_TYPE Optional. REST API slug (default: posts)
+"""
+
+import argparse
+import base64
+import ipaddress
+import json
+import os
+import socket
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+PAGE_SIZE = 100
+_RETRY_CODES = {429, 502, 503, 504}
+
+
+# ── SSRF protection ───────────────────────────────────────────────────────────
+
+def _is_private_ip(ip_str):
+ try:
+ addr = ipaddress.ip_address(ip_str)
+ return addr.is_loopback or addr.is_private or addr.is_link_local or addr.is_reserved
+ except ValueError:
+ return False
+
+
+def validate_url(url):
+ try:
+ parsed = urllib.parse.urlparse(url)
+ except Exception:
+ print("ERROR: WP_URL is not a valid URL.", file=sys.stderr)
+ sys.exit(1)
+ if parsed.scheme not in ("http", "https"):
+ print("ERROR: WP_URL must use http:// or https://", file=sys.stderr)
+ sys.exit(1)
+ hostname = parsed.hostname or ""
+ if not hostname:
+ print("ERROR: WP_URL has no hostname.", file=sys.stderr)
+ sys.exit(1)
+ if _is_private_ip(hostname):
+ print(f"ERROR: WP_URL is a private/local address ('{hostname}').", file=sys.stderr)
+ sys.exit(1)
+ if hostname.lower() == "localhost":
+ print("ERROR: WP_URL points to localhost.", file=sys.stderr)
+ sys.exit(1)
+ try:
+ for info in socket.getaddrinfo(hostname, None, type=socket.SOCK_STREAM):
+ if _is_private_ip(info[4][0]):
+ print(f"ERROR: WP_URL resolves to an internal address ({info[4][0]}).", file=sys.stderr)
+ sys.exit(1)
+ except (socket.gaierror, OSError):
+ pass
+
+
+# ── Config loading ────────────────────────────────────────────────────────────
+
+def load_env_file(path):
+ env = {}
+ try:
+ with open(path) as f:
+ for line in f:
+ line = line.strip()
+ if not line or line.startswith("#") or "=" not in line:
+ continue
+ key, _, raw_value = line.partition("=")
+ key = key.strip()
+ value = raw_value.strip().strip('"').strip("'")
+ if key:
+ env[key] = value
+ except (OSError, PermissionError):
+ pass
+ return env
+
+
+def find_and_load_env():
+ env = {}
+ search = os.path.abspath(os.getcwd())
+ for _ in range(6):
+ for name in (".env.local", ".env"):
+ candidate = os.path.join(search, name)
+ if os.path.isfile(candidate):
+ env.update(load_env_file(candidate))
+ parent = os.path.dirname(search)
+ if parent == search:
+ break
+ search = parent
+ return env
+
+
+def get_config():
+ file_env = find_and_load_env()
+
+ def get(key):
+ return os.environ.get(key) or file_env.get(key, "")
+
+ return (
+ get("WP_URL").rstrip("/"),
+ get("WP_USERNAME"),
+ get("WP_APP_PASSWORD"),
+ get("WP_CONTENT_TYPE") or "posts",
+ )
+
+
+def make_auth_header(username, app_password):
+ password = app_password.replace(" ", "")
+ credentials = base64.b64encode(f"{username}:{password}".encode()).decode()
+ return f"Basic {credentials}"
+
+
+# ── HTTP helper with retry ────────────────────────────────────────────────────
+
+def wp_get(base_url, auth_header, path, params, timeout=30, retries=3):
+ full_url = f"{base_url}{path}?{urllib.parse.urlencode(params)}"
+ req = urllib.request.Request(
+ full_url,
+ headers={"Authorization": auth_header, "Accept": "application/json"},
+ )
+ last_exc = None
+ for attempt in range(retries):
+ try:
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ body = json.loads(resp.read())
+ total = int(resp.headers.get("X-WP-Total", 0))
+ total_pages = int(resp.headers.get("X-WP-TotalPages", 1))
+ return body, total, total_pages
+ except urllib.error.HTTPError as e:
+ if e.code in _RETRY_CODES and attempt < retries - 1:
+ wait = 2 ** attempt
+ print(f" HTTP {e.code} — retrying in {wait}s...", file=sys.stderr)
+ time.sleep(wait)
+ last_exc = e
+ continue
+ body = e.read().decode()[:200] if e.fp else "(no body)"
+ print(f"ERROR: WordPress API {e.code} on {path}: {body}", file=sys.stderr)
+ sys.exit(1)
+ except urllib.error.URLError as e:
+ if attempt < retries - 1:
+ wait = 2 ** attempt
+ print(f" Network error ({e.reason}) — retrying in {wait}s...", file=sys.stderr)
+ time.sleep(wait)
+ last_exc = e
+ continue
+ print(f"ERROR: Network error on {base_url}{path}: {e.reason}", file=sys.stderr)
+ sys.exit(1)
+ raise last_exc
+
+
+# ── SEO field extraction ──────────────────────────────────────────────────────
+
+def extract_seo_fields(item):
+ """Extract meta title and description from WordPress post/page.
+
+ Priority:
+ 1. Yoast SEO — yoast_head_json.title / yoast_head_json.description
+ 2. RankMath — meta.rank_math_title / meta.rank_math_description
+ 3. Title — title.rendered (raw page title, no SEO override)
+ """
+ meta_title = ""
+ meta_description = ""
+ has_meta_image = False
+ has_meta_social = False
+
+ yoast = item.get("yoast_head_json") or {}
+ if yoast:
+ meta_title = yoast.get("title") or ""
+ meta_description = yoast.get("description") or ""
+ has_meta_image = bool(yoast.get("og_image"))
+ has_meta_social = bool(yoast.get("og_title") or yoast.get("twitter_title"))
+
+ if not meta_title or not meta_description:
+ meta_obj = item.get("meta") or {}
+ if not meta_title:
+ meta_title = (
+ meta_obj.get("rank_math_title") or
+ meta_obj.get("_yoast_wpseo_title") or
+ ""
+ )
+ if not meta_description:
+ meta_description = (
+ meta_obj.get("rank_math_description") or
+ meta_obj.get("_yoast_wpseo_metadesc") or
+ ""
+ )
+
+ # Do NOT fall back to title.rendered — a post with no Yoast/RankMath title
+ # should be flagged as missing_meta_title=True, not silently pass because it
+ # has a page title. The entry's "title" field is preserved for display.
+
+ return {
+ "meta_title": meta_title,
+ "meta_description": meta_description,
+ "has_meta_image": has_meta_image,
+ "has_meta_social": has_meta_social,
+ }
+
+
+# ── Response normalisation ────────────────────────────────────────────────────
+
+def normalise_entry(item):
+ """Normalise a WordPress REST API post/page to the shared CMS entry format."""
+ seo = extract_seo_fields(item)
+
+ title_obj = item.get("title") or {}
+ slug = item.get("slug") or ""
+ published_at = item.get("date_gmt") or item.get("date") or ""
+ updated_at = item.get("modified_gmt") or item.get("modified") or ""
+
+ meta_title_len = len(seo["meta_title"])
+ meta_desc_len = len(seo["meta_description"])
+
+ return {
+ "document_id": str(item.get("id", "")),
+ "id": item.get("id"),
+ "title": title_obj.get("rendered") or "",
+ "slug": slug,
+ "published_at": published_at,
+ "updated_at": updated_at,
+ "created_at": published_at, # WP doesn't separate creation from publish
+ "locale": "",
+ "seo": seo,
+ "missing_meta_title": not seo["meta_title"],
+ "missing_meta_description": not seo["meta_description"],
+ "meta_title_too_long": meta_title_len > 60,
+ "meta_description_too_long": meta_desc_len > 160,
+ "meta_description_too_short": 0 < meta_desc_len < 70,
+ }
+
+
+# ── Pagination ────────────────────────────────────────────────────────────────
+
+def fetch_all_entries(base_url, auth_header, content_type):
+ """Paginate through all published entries. Returns list of normalised entries."""
+ path = f"/wp-json/wp/v2/{content_type}"
+ all_entries = []
+ page = 1
+ total_pages = None
+
+ while True:
+ params = {
+ "status": "publish",
+ "per_page": PAGE_SIZE,
+ "page": page,
+ # Fetch fields needed for SEO extraction plus pagination headers
+ "_fields": "id,slug,title,date,date_gmt,modified,modified_gmt,yoast_head_json,meta",
+ }
+
+ print(f" Fetching page {page}...", file=sys.stderr)
+ items, total, tp = wp_get(base_url, auth_header, path, params)
+
+ if total_pages is None:
+ total_pages = tp
+ print(f" {total} published {content_type} across {total_pages} page(s)", file=sys.stderr)
+
+ if not items:
+ break
+
+ for item in items:
+ all_entries.append(normalise_entry(item))
+
+ print(f" Page {page}/{total_pages} — {len(all_entries)}/{total} fetched", file=sys.stderr)
+
+ if page >= total_pages:
+ break
+ page += 1
+
+ return all_entries
+
+
+# ── SEO audit ─────────────────────────────────────────────────────────────────
+
+def build_seo_audit(entries):
+ missing_title = []
+ missing_desc = []
+ title_long = []
+ desc_too_long = []
+ desc_too_short = []
+ broken_ids = set()
+
+ for e in entries:
+ broken = False
+ if e["missing_meta_title"]:
+ missing_title.append(e)
+ broken = True
+ if e["missing_meta_description"]:
+ missing_desc.append(e)
+ broken = True
+ if e["meta_title_too_long"]:
+ title_long.append(e)
+ broken = True
+ if e["meta_description_too_long"]:
+ desc_too_long.append(e)
+ broken = True
+ if e["meta_description_too_short"]:
+ desc_too_short.append(e)
+ broken = True
+ if broken:
+ broken_ids.add(e["document_id"])
+
+ return {
+ "total": len(entries),
+ "missing_meta_title": len(missing_title),
+ "missing_meta_description": len(missing_desc),
+ "meta_title_too_long": len(title_long),
+ "meta_description_too_short": len(desc_too_short),
+ "meta_description_too_long": len(desc_too_long),
+ "complete_seo": len(entries) - len(broken_ids),
+ "entries_missing_meta_title": [
+ {"document_id": e["document_id"], "title": e["title"], "slug": e["slug"]}
+ for e in missing_title[:20]
+ ],
+ "entries_missing_meta_description": [
+ {"document_id": e["document_id"], "title": e["title"], "slug": e["slug"]}
+ for e in missing_desc[:20]
+ ],
+ "entries_title_too_long": [
+ {
+ "document_id": e["document_id"],
+ "title": e["title"],
+ "meta_title": e["seo"]["meta_title"],
+ "length": len(e["seo"]["meta_title"]),
+ }
+ for e in title_long[:20]
+ ],
+ }
+
+
+def main():
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--content-type", help="Override WP_CONTENT_TYPE env var")
+ parser.add_argument("--output", help="Output JSON file path (default: secure tempfile)")
+ args = parser.parse_args()
+
+ base_url, username, app_password, content_type = get_config()
+ if args.content_type:
+ content_type = args.content_type
+
+ if not base_url:
+ print("WP_NOT_CONFIGURED: Set WP_URL, WP_USERNAME, and WP_APP_PASSWORD to enable WordPress integration.", file=sys.stderr)
+ sys.exit(2)
+ if not username or not app_password:
+ print("ERROR: WP_USERNAME and WP_APP_PASSWORD must both be set.", file=sys.stderr)
+ sys.exit(1)
+
+ validate_url(base_url)
+ auth_header = make_auth_header(username, app_password)
+
+ print(f"Fetching {content_type} from {base_url}...", file=sys.stderr)
+ entries = fetch_all_entries(base_url, auth_header, content_type)
+
+ seo_audit = build_seo_audit(entries)
+
+ result = {
+ "cms_type": "wordpress",
+ "cms_url": base_url,
+ "content_type": content_type,
+ "total_published": len(entries),
+ "seo_audit": seo_audit,
+ "entries": entries,
+ }
+
+ if args.output:
+ out_path = args.output
+ out_dir = os.path.dirname(out_path) or "."
+ else:
+ out_dir = tempfile.gettempdir()
+ out_path = os.path.join(out_dir, f"cms_content_{os.getuid()}.json")
+
+ fd, tmp_path = tempfile.mkstemp(dir=out_dir, suffix=".json.tmp")
+ try:
+ os.chmod(tmp_path, 0o600)
+ with os.fdopen(fd, "w") as f:
+ json.dump(result, f, indent=2)
+ os.replace(tmp_path, out_path)
+ except Exception:
+ os.unlink(tmp_path)
+ raise
+
+ print(f"\nDone. {len(entries)} entries saved to {out_path}", file=sys.stderr)
+ print(
+ f"SEO completeness: {seo_audit['complete_seo']}/{seo_audit['total']} entries fully complete",
+ file=sys.stderr,
+ )
+ if seo_audit["missing_meta_title"]:
+ print(f" Missing meta title: {seo_audit['missing_meta_title']}", file=sys.stderr)
+ if seo_audit["missing_meta_description"]:
+ print(f" Missing meta description: {seo_audit['missing_meta_description']}", file=sys.stderr)
+ if seo_audit["meta_title_too_long"]:
+ print(f" Meta title too long (>60): {seo_audit['meta_title_too_long']}", file=sys.stderr)
+ if seo_audit["meta_description_too_short"]:
+ print(f" Meta desc too short (<70): {seo_audit['meta_description_too_short']}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/seo/seo-analysis/scripts/list_gsc_sites.py b/seo/seo-analysis/scripts/list_gsc_sites.py
new file mode 100644
index 00000000..a4210328
--- /dev/null
+++ b/seo/seo-analysis/scripts/list_gsc_sites.py
@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""List all Google Search Console properties for the authenticated account."""
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import urllib.request
+import urllib.error
+
+
+def get_quota_project():
+ """Return the quota_project_id from the ADC JSON file, or None."""
+ adc_dir = os.environ.get("CLOUDSDK_CONFIG") or os.path.join(
+ os.path.expanduser("~"), ".config", "gcloud"
+ )
+ adc_path = os.path.join(adc_dir, "application_default_credentials.json")
+ try:
+ with open(adc_path) as f:
+ data = json.load(f)
+ if isinstance(data, dict):
+ return data.get("quota_project_id") or None
+ except (OSError, ValueError):
+ pass
+ return None
+
+
+def get_access_token():
+ try:
+ result = subprocess.run(
+ ["gcloud", "auth", "application-default", "print-access-token"],
+ capture_output=True, text=True, timeout=15
+ )
+ except FileNotFoundError:
+ print("ERROR: gcloud not found. Install it and authenticate:", file=sys.stderr)
+ print(" https://cloud.google.com/sdk/docs/install", file=sys.stderr)
+ sys.exit(1)
+ except subprocess.TimeoutExpired:
+ print("ERROR: gcloud timed out after 15s. Check your network or gcloud installation.", file=sys.stderr)
+ sys.exit(1)
+ if result.returncode != 0:
+ print("ERROR: Could not get access token. Run:", file=sys.stderr)
+ print(" gcloud auth application-default login \\", file=sys.stderr)
+ print(" --scopes=https://www.googleapis.com/auth/webmasters,"
+ "https://www.googleapis.com/auth/webmasters.readonly", file=sys.stderr)
+ sys.exit(1)
+ token = result.stdout.strip()
+ if not token:
+ print("ERROR: gcloud returned an empty token. Re-authenticate:", file=sys.stderr)
+ print(" gcloud auth application-default login \\", file=sys.stderr)
+ print(" --scopes=https://www.googleapis.com/auth/webmasters,"
+ "https://www.googleapis.com/auth/webmasters.readonly", file=sys.stderr)
+ sys.exit(1)
+ return token
+
+
+def list_sites(token):
+ url = "https://searchconsole.googleapis.com/webmasters/v3/sites"
+ headers = {"Authorization": f"Bearer {token}"}
+ quota_project = get_quota_project()
+ if quota_project:
+ headers["x-goog-user-project"] = quota_project
+ req = urllib.request.Request(url, headers=headers)
+ try:
+ with urllib.request.urlopen(req, timeout=30) as resp:
+ data = json.loads(resp.read())
+ return data.get("siteEntry", [])
+ except urllib.error.HTTPError as e:
+ err_body = e.read().decode() if e.fp else "(no body)"
+ print(f"ERROR {e.code}: {err_body}", file=sys.stderr)
+ sys.exit(1)
+ except urllib.error.URLError as e:
+ print(f"ERROR: Network failure: {e.reason}", file=sys.stderr)
+ sys.exit(1)
+
+
+def main():
+ token = get_access_token()
+ sites = list_sites(token)
+
+ if not sites:
+ print("No Search Console properties found for this account.")
+ print("Make sure you're logged in with the right Google account.")
+ sys.exit(0)
+
+ print(f"Found {len(sites)} Search Console properties:\n")
+ for i, site in enumerate(sites, 1):
+ ptype = "Domain" if site["siteUrl"].startswith("sc-domain:") else "URL-prefix"
+ level = site.get("permissionLevel", "unknown")
+ print(f" {i}. {site['siteUrl']}")
+ print(f" Type: {ptype} | Permission: {level}")
+
+ # Also output as JSON for machine parsing
+ sites_path = os.path.join(tempfile.gettempdir(), f"gsc_sites_{os.getuid()}.json")
+ with open(sites_path, "w") as f:
+ json.dump(sites, f, indent=2)
+ print(f"\n(Full list saved to {sites_path})")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/seo/seo-analysis/scripts/preflight.py b/seo/seo-analysis/scripts/preflight.py
new file mode 100644
index 00000000..b15b7f49
--- /dev/null
+++ b/seo/seo-analysis/scripts/preflight.py
@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+"""Pre-flight check for seo-analysis skill.
+
+Verifies gcloud is installed, a GCP project is configured, the Search Console
+API is enabled, and Google ADC credentials are configured with the correct scope.
+No external dependencies — uses only Python stdlib and the gcloud CLI.
+
+Exit codes:
+ 0 — all dependencies ready
+ 1 — unrecoverable error (gcloud missing, auth failed, etc.)
+"""
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import urllib.request
+
+
+def check_python_version():
+ if sys.version_info < (3, 8):
+ print(f"ERROR: Python 3.8+ required (you have {sys.version.split()[0]})", file=sys.stderr)
+ print(" Upgrade: https://python.org/downloads", file=sys.stderr)
+ sys.exit(1)
+
+
+def check_gcloud():
+ """Verify gcloud CLI is installed; print OS-specific install instructions if not."""
+ if shutil.which("gcloud"):
+ return
+
+ system = platform.system()
+ print("ERROR: gcloud CLI not found.", file=sys.stderr)
+ print("", file=sys.stderr)
+
+ if system == "Darwin":
+ print("Install with Homebrew (recommended):", file=sys.stderr)
+ print(" brew install google-cloud-sdk", file=sys.stderr)
+ print("", file=sys.stderr)
+ print("Or download the installer:", file=sys.stderr)
+ print(" https://cloud.google.com/sdk/docs/install#mac", file=sys.stderr)
+ elif system == "Linux":
+ distro = ""
+ try:
+ with open("/etc/os-release") as f:
+ distro = f.read().lower()
+ except FileNotFoundError:
+ pass
+
+ if "ubuntu" in distro or "debian" in distro:
+ print("Install with apt:", file=sys.stderr)
+ print(" sudo apt-get install google-cloud-cli", file=sys.stderr)
+ elif "fedora" in distro or "rhel" in distro or "centos" in distro:
+ print("Install with dnf:", file=sys.stderr)
+ print(" sudo dnf install google-cloud-cli", file=sys.stderr)
+ else:
+ print("Install via curl:", file=sys.stderr)
+ print(" curl https://sdk.cloud.google.com | bash", file=sys.stderr)
+ print("", file=sys.stderr)
+ print("Full guide: https://cloud.google.com/sdk/docs/install#linux", file=sys.stderr)
+ elif system == "Windows":
+ print("Install with winget:", file=sys.stderr)
+ print(" winget install Google.CloudSDK", file=sys.stderr)
+ print("", file=sys.stderr)
+ print("Or download the installer:", file=sys.stderr)
+ print(" https://dl.google.com/dl/cloudsdk/channels/rapid/GoogleCloudSDKInstaller.exe", file=sys.stderr)
+ else:
+ print("See: https://cloud.google.com/sdk/docs/install", file=sys.stderr)
+
+ sys.exit(1)
+
+
+def check_gcloud_project():
+ """Ensure gcloud has an active project. Run gcloud init if not."""
+ try:
+ result = subprocess.run(
+ ["gcloud", "config", "get-value", "project"],
+ capture_output=True, text=True, timeout=15,
+ )
+ except subprocess.TimeoutExpired:
+ print("ERROR: gcloud timed out. Check your network.", file=sys.stderr)
+ sys.exit(1)
+
+ project = result.stdout.strip()
+ # gcloud prints "(unset)" to stderr when no project is set
+ if project and project != "(unset)":
+ print(f"GCP project: {project}", file=sys.stderr)
+ return
+
+ # No project configured — first-time gcloud user
+ print("No GCP project configured.", file=sys.stderr)
+
+ if not sys.stdin.isatty():
+ print("Run in an interactive terminal:", file=sys.stderr)
+ print(" gcloud init", file=sys.stderr)
+ print("This will create or select a Google Cloud project.", file=sys.stderr)
+ sys.exit(1)
+
+ print("Running 'gcloud init' to set up your project...", file=sys.stderr)
+ print("", file=sys.stderr)
+ init_result = subprocess.run(["gcloud", "init"])
+ if init_result.returncode != 0:
+ print("", file=sys.stderr)
+ print("ERROR: gcloud init failed or was cancelled.", file=sys.stderr)
+ print("Run 'gcloud init' manually and try again.", file=sys.stderr)
+ sys.exit(1)
+
+ # Verify project was set
+ verify = subprocess.run(
+ ["gcloud", "config", "get-value", "project"],
+ capture_output=True, text=True, timeout=15,
+ )
+ project = verify.stdout.strip()
+ if not project or project == "(unset)":
+ print("ERROR: No project selected during gcloud init.", file=sys.stderr)
+ print("Run 'gcloud init' again and select or create a project.", file=sys.stderr)
+ sys.exit(1)
+
+ print(f"GCP project: {project}", file=sys.stderr)
+
+
+def check_search_console_api():
+ """Ensure the Search Console API is enabled in the active project."""
+ try:
+ result = subprocess.run(
+ ["gcloud", "services", "list", "--enabled",
+ "--filter=config.name:searchconsole.googleapis.com",
+ "--format=value(config.name)"],
+ capture_output=True, text=True, timeout=30,
+ )
+ except subprocess.TimeoutExpired:
+ print("WARNING: Timed out checking Search Console API status.", file=sys.stderr)
+ print("If you get API errors later, run:", file=sys.stderr)
+ print(" gcloud services enable searchconsole.googleapis.com", file=sys.stderr)
+ return # non-fatal — let it fail later with a clear error
+
+ if "searchconsole.googleapis.com" in result.stdout:
+ print("Search Console API: enabled", file=sys.stderr)
+ return
+
+ # API not enabled — try to enable it automatically
+ print("Search Console API is not enabled. Enabling it now...", file=sys.stderr)
+ enable_result = subprocess.run(
+ ["gcloud", "services", "enable", "searchconsole.googleapis.com"],
+ capture_output=True, text=True, timeout=60,
+ )
+ if enable_result.returncode == 0:
+ print("Search Console API: enabled", file=sys.stderr)
+ return
+
+ # Enable failed — print manual instructions
+ print("", file=sys.stderr)
+ print("ERROR: Could not enable the Search Console API automatically.", file=sys.stderr)
+ stderr_msg = enable_result.stderr.strip()
+ if stderr_msg:
+ print(f" Reason: {stderr_msg}", file=sys.stderr)
+ print("", file=sys.stderr)
+ print("Enable it manually:", file=sys.stderr)
+ print(" gcloud services enable searchconsole.googleapis.com", file=sys.stderr)
+ print("", file=sys.stderr)
+ print("Or via the Cloud Console:", file=sys.stderr)
+ print(" https://console.cloud.google.com/apis/library/searchconsole.googleapis.com", file=sys.stderr)
+ sys.exit(1)
+
+
+_GSC_SCOPES = (
+ "https://www.googleapis.com/auth/webmasters",
+ "https://www.googleapis.com/auth/webmasters.readonly",
+)
+_GSC_SCOPES_ARG = ",".join(_GSC_SCOPES)
+
+
+def _token_has_gsc_scope(token):
+ """Return True if the token includes at least one Search Console scope.
+
+ Calls the Google tokeninfo endpoint to inspect the granted scopes.
+ Returns None if the check cannot be completed (network error, etc.).
+ """
+ try:
+ url = f"https://oauth2.googleapis.com/tokeninfo?access_token={token}"
+ with urllib.request.urlopen(url, timeout=10) as resp:
+ data = json.loads(resp.read().decode())
+ granted = set(data.get("scope", "").split())
+ return bool(granted & set(_GSC_SCOPES))
+ except Exception:
+ return None # can't verify — caller decides what to do
+
+
+def check_adc_credentials():
+ """Check ADC credentials exist with correct Search Console scope.
+
+ If credentials are missing or have the wrong scope (e.g. cloud-platform from
+ a prior bare `gcloud auth application-default login`), re-authenticates with
+ the correct scopes.
+ """
+ try:
+ result = subprocess.run(
+ ["gcloud", "auth", "application-default", "print-access-token"],
+ capture_output=True, text=True, timeout=15,
+ )
+ except subprocess.TimeoutExpired:
+ print("ERROR: gcloud timed out checking credentials. Check your network.", file=sys.stderr)
+ sys.exit(1)
+
+ needs_auth = True
+ if result.returncode == 0 and result.stdout.strip():
+ token = result.stdout.strip()
+ has_scope = _token_has_gsc_scope(token)
+ if has_scope is True:
+ print("Google credentials: OK (Search Console scope confirmed)", file=sys.stderr)
+ return
+ elif has_scope is None:
+ # tokeninfo unreachable — assume credentials are fine, let the API call fail
+ print("Google credentials: found (scope check skipped — no network)", file=sys.stderr)
+ return
+ else:
+ # Credentials exist but have the wrong scope (e.g. cloud-platform)
+ print("WARNING: Existing credentials are missing the Search Console scope.", file=sys.stderr)
+ print(" This happens when `gcloud auth application-default login` was run", file=sys.stderr)
+ print(" without --scopes, granting broad cloud-platform access instead.", file=sys.stderr)
+ print(" Re-authenticating with the correct scope now...", file=sys.stderr)
+ print("", file=sys.stderr)
+ needs_auth = True
+
+ if needs_auth and not sys.stdin.isatty():
+ print("ERROR: No Application Default Credentials with Search Console scope.", file=sys.stderr)
+ print("Run in an interactive terminal:", file=sys.stderr)
+ print(" gcloud auth application-default login \\", file=sys.stderr)
+ print(f" --scopes={_GSC_SCOPES_ARG}", file=sys.stderr)
+ sys.exit(1)
+
+ print("Opening browser for Google authentication...", file=sys.stderr)
+ print("(Log in with the Google account that has access to Search Console.)", file=sys.stderr)
+ print("", file=sys.stderr)
+ auth_result = subprocess.run(
+ ["gcloud", "auth", "application-default", "login",
+ f"--scopes={_GSC_SCOPES_ARG}"],
+ )
+ if auth_result.returncode != 0:
+ print("", file=sys.stderr)
+ print("ERROR: Authentication failed or was cancelled.", file=sys.stderr)
+ print("Run this manually and try again:", file=sys.stderr)
+ print(" gcloud auth application-default login \\", file=sys.stderr)
+ print(f" --scopes={_GSC_SCOPES_ARG}", file=sys.stderr)
+ sys.exit(1)
+ print("Authentication successful.", file=sys.stderr)
+
+
+def _get_adc_quota_project():
+ """Return the quota_project_id from the ADC JSON file, or None if absent."""
+ adc_dir = os.environ.get("CLOUDSDK_CONFIG") or os.path.join(
+ os.path.expanduser("~"), ".config", "gcloud"
+ )
+ adc_path = os.path.join(adc_dir, "application_default_credentials.json")
+ if not os.path.isfile(adc_path):
+ return None
+ try:
+ with open(adc_path) as f:
+ data = json.load(f)
+ if not isinstance(data, dict):
+ return None
+ return data.get("quota_project_id") or None
+ except (OSError, ValueError):
+ return None
+
+
+def check_quota_project():
+ """Ensure ADC has a quota project set; auto-configure it from the active gcloud project.
+
+ Without a quota project, user-credential ADC calls to Search Console return 403:
+ "The searchconsole.googleapis.com API requires a quota project."
+ Fix: gcloud auth application-default set-quota-project PROJECT_ID
+
+ Returns True if quota project is confirmed set, False if it could not be configured.
+ """
+ if _get_adc_quota_project():
+ return True # already configured
+
+ # Look up the active gcloud project
+ try:
+ result = subprocess.run(
+ ["gcloud", "config", "get-value", "project"],
+ capture_output=True, text=True, timeout=15,
+ )
+ except subprocess.TimeoutExpired:
+ print("WARNING: gcloud timed out getting project for quota setup.", file=sys.stderr)
+ return False
+
+ project = result.stdout.strip() if result.returncode == 0 else ""
+ if not project or project == "(unset)":
+ print("WARNING: Cannot set quota project — no active GCP project.", file=sys.stderr)
+ print(" Run: gcloud auth application-default set-quota-project YOUR_PROJECT_ID", file=sys.stderr)
+ return False
+
+ print(f"Setting ADC quota project to '{project}'...", file=sys.stderr)
+ try:
+ set_result = subprocess.run(
+ ["gcloud", "auth", "application-default", "set-quota-project", project],
+ capture_output=True, text=True, timeout=30,
+ )
+ except subprocess.TimeoutExpired:
+ print("WARNING: gcloud timed out setting quota project.", file=sys.stderr)
+ print(f" Run manually: gcloud auth application-default set-quota-project '{project}'", file=sys.stderr)
+ return False
+ if set_result.returncode == 0:
+ print(f"ADC quota project: {project}", file=sys.stderr)
+ return True
+ else:
+ print("WARNING: Could not set quota project automatically.", file=sys.stderr)
+ print(f" Run manually: gcloud auth application-default set-quota-project '{project}'", file=sys.stderr)
+ stderr_msg = set_result.stderr.strip()
+ if stderr_msg:
+ print(f" Reason: {stderr_msg}", file=sys.stderr)
+ return False
+
+
+def main():
+ check_python_version()
+ check_gcloud()
+ check_gcloud_project()
+ check_search_console_api()
+ check_adc_credentials()
+ quota_ok = check_quota_project()
+ if quota_ok:
+ print("OK: All dependencies ready.", file=sys.stderr)
+ else:
+ print("OK: All dependencies ready (quota project not confirmed — GSC may return 403).", file=sys.stderr)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/seo/seo-analysis/scripts/preflight_contentful.py b/seo/seo-analysis/scripts/preflight_contentful.py
new file mode 100644
index 00000000..9711c629
--- /dev/null
+++ b/seo/seo-analysis/scripts/preflight_contentful.py
@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""Pre-flight check for Contentful Content Delivery API integration.
+
+Verifies CONTENTFUL_SPACE_ID, CONTENTFUL_DELIVERY_TOKEN, and
+CONTENTFUL_CONTENT_TYPE are set, tests the Delivery API, and reports the
+total published entry count for the configured content type.
+
+No external dependencies — uses only Python stdlib.
+
+Exit codes:
+ 0 — Contentful connection ready
+ 1 — unrecoverable error (missing config, auth failed, wrong content type, etc.)
+ 2 — Contentful not configured (CONTENTFUL_SPACE_ID not set) — non-fatal, caller skips
+"""
+
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+_RETRY_CODES = {429, 502, 503, 504}
+_CONTENTFUL_API = "https://cdn.contentful.com"
+
+
+# ── Config loading ────────────────────────────────────────────────────────────
+
+def load_env_file(path):
+ env = {}
+ try:
+ with open(path) as f:
+ for line in f:
+ line = line.strip()
+ if not line or line.startswith("#") or "=" not in line:
+ continue
+ key, _, raw_value = line.partition("=")
+ key = key.strip()
+ value = raw_value.strip().strip('"').strip("'")
+ if key:
+ env[key] = value
+ except (OSError, PermissionError):
+ pass
+ return env
+
+
+def find_and_load_env():
+ env = {}
+ search = os.path.abspath(os.getcwd())
+ for _ in range(6):
+ for name in (".env.local", ".env"):
+ candidate = os.path.join(search, name)
+ if os.path.isfile(candidate):
+ env.update(load_env_file(candidate))
+ parent = os.path.dirname(search)
+ if parent == search:
+ break
+ search = parent
+ return env
+
+
+def get_config():
+ file_env = find_and_load_env()
+
+ def get(key):
+ return os.environ.get(key) or file_env.get(key, "")
+
+ return (
+ get("CONTENTFUL_SPACE_ID"),
+ get("CONTENTFUL_DELIVERY_TOKEN"),
+ get("CONTENTFUL_CONTENT_TYPE"),
+ get("CONTENTFUL_ENVIRONMENT") or "master",
+ )
+
+
+# ── HTTP helper with retry ────────────────────────────────────────────────────
+
+def contentful_get(token, path, params=None, timeout=15, retries=3):
+ """GET {_CONTENTFUL_API}{path}?{params} with Bearer auth."""
+ full_url = f"{_CONTENTFUL_API}{path}"
+ if params:
+ full_url = f"{full_url}?{urllib.parse.urlencode(params)}"
+ req = urllib.request.Request(
+ full_url,
+ headers={"Authorization": f"Bearer {token}"},
+ )
+ last_exc = None
+ for attempt in range(retries):
+ try:
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ return json.loads(resp.read())
+ except urllib.error.HTTPError as e:
+ if e.code in _RETRY_CODES and attempt < retries - 1:
+ wait = 2 ** attempt
+ print(f" HTTP {e.code} — retrying in {wait}s...", file=sys.stderr)
+ time.sleep(wait)
+ last_exc = e
+ continue
+ raise
+ except urllib.error.URLError as e:
+ if attempt < retries - 1:
+ wait = 2 ** attempt
+ print(f" Network error ({e.reason}) — retrying in {wait}s...", file=sys.stderr)
+ time.sleep(wait)
+ last_exc = e
+ continue
+ raise
+ raise last_exc
+
+
+# ── Validation checks ─────────────────────────────────────────────────────────
+
+def check_config(space_id, token, content_type):
+ if not space_id:
+ print("CONTENTFUL_NOT_CONFIGURED: Set CONTENTFUL_SPACE_ID and CONTENTFUL_DELIVERY_TOKEN to enable Contentful integration.", file=sys.stderr)
+ sys.exit(2)
+
+ if not token:
+ print("ERROR: CONTENTFUL_DELIVERY_TOKEN is not set.", file=sys.stderr)
+ print("", file=sys.stderr)
+ print("Create a Content Delivery API key in Contentful:", file=sys.stderr)
+ print(" Settings → API Keys → Add API Key → copy Content Delivery API - access token", file=sys.stderr)
+ print("", file=sys.stderr)
+ print("Then set it in .env.local:", file=sys.stderr)
+ print(" CONTENTFUL_DELIVERY_TOKEN=your_token_here", file=sys.stderr)
+ sys.exit(1)
+
+ if not content_type:
+ print("ERROR: CONTENTFUL_CONTENT_TYPE is not set.", file=sys.stderr)
+ print("Set the content type API ID in .env.local:", file=sys.stderr)
+ print(" CONTENTFUL_CONTENT_TYPE=blogPost", file=sys.stderr)
+ print("Find it in: Content model → [your type] → API Identifier", file=sys.stderr)
+ sys.exit(1)
+
+ print(f"Contentful space: {space_id}", file=sys.stderr)
+
+
+def check_connectivity(space_id, token, content_type, environment):
+ """Probe the space and content type, return total entry count."""
+ # First verify auth by fetching the space
+ try:
+ contentful_get(token, f"/spaces/{space_id}")
+ except urllib.error.HTTPError as e:
+ if e.code == 401:
+ print("ERROR: Contentful returned 401 Unauthorized.", file=sys.stderr)
+ print("Your CONTENTFUL_DELIVERY_TOKEN is invalid or expired.", file=sys.stderr)
+ print("Regenerate it in: Settings → API Keys", file=sys.stderr)
+ sys.exit(1)
+ if e.code == 404:
+ print(f"ERROR: Space '{space_id}' not found (404).", file=sys.stderr)
+ print("Check CONTENTFUL_SPACE_ID in Settings → General Settings.", file=sys.stderr)
+ sys.exit(1)
+ # Non-fatal for space check — content type check below will surface the real error
+ except urllib.error.URLError as e:
+ print(f"ERROR: Cannot reach Contentful API.", file=sys.stderr)
+ print(f" Network error: {e.reason}", file=sys.stderr)
+ sys.exit(1)
+
+ # Verify content type and get count
+ try:
+ data = contentful_get(token, f"/spaces/{space_id}/environments/{environment}/entries", {
+ "content_type": content_type,
+ "limit": 1,
+ })
+ except urllib.error.HTTPError as e:
+ body = e.read().decode()[:300] if e.fp else "(no body)"
+ if e.code == 400:
+ print(f"ERROR: Contentful returned 400 Bad Request.", file=sys.stderr)
+ print(f"Content type '{content_type}' may not exist.", file=sys.stderr)
+ print("Check CONTENTFUL_CONTENT_TYPE — find it in: Content model → [your type] → API Identifier", file=sys.stderr)
+ sys.exit(1)
+ if e.code == 404:
+ print(f"ERROR: Environment '{environment}' not found.", file=sys.stderr)
+ print(f"Check CONTENTFUL_ENVIRONMENT (default: master).", file=sys.stderr)
+ sys.exit(1)
+ print(f"ERROR: Contentful API error {e.code}. Response: {body}", file=sys.stderr)
+ sys.exit(1)
+
+ total = data.get("total", 0)
+ print(f"Contentful ready | space: {space_id} | env: {environment} | content type: {content_type} | {total} entries", file=sys.stderr)
+ return total
+
+
+def main():
+ space_id, token, content_type, environment = get_config()
+ check_config(space_id, token, content_type)
+ total = check_connectivity(space_id, token, content_type, environment)
+ if total == 0:
+ print(f"WARNING: No entries found in content type '{content_type}'.", file=sys.stderr)
+ print(f"OK: Contentful ready ({content_type}, {total} entries)", file=sys.stderr)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/seo/seo-analysis/scripts/preflight_ghost.py b/seo/seo-analysis/scripts/preflight_ghost.py
new file mode 100644
index 00000000..e0a75f57
--- /dev/null
+++ b/seo/seo-analysis/scripts/preflight_ghost.py
@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""Pre-flight check for Ghost Content API integration.
+
+Verifies GHOST_URL and GHOST_CONTENT_KEY are set, tests connectivity
+via the Ghost Content API, and reports the total published entry count.
+
+Supports Ghost 4.x+ (/ghost/api/content/) and 3.x (/ghost/api/v3/content/).
+No external dependencies — uses only Python stdlib.
+
+Exit codes:
+ 0 — Ghost connection ready
+ 1 — unrecoverable error (missing config, auth failed, etc.)
+ 2 — Ghost not configured (GHOST_URL not set) — non-fatal, caller skips
+"""
+
+import ipaddress
+import json
+import os
+import socket
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+_RETRY_CODES = {429, 502, 503, 504}
+# API path candidates: try newest first, fall back to v3
+_API_PATHS = ["/ghost/api/content", "/ghost/api/v3/content"]
+
+
+# ── Config loading ────────────────────────────────────────────────────────────
+
+def load_env_file(path):
+ env = {}
+ try:
+ with open(path) as f:
+ for line in f:
+ line = line.strip()
+ if not line or line.startswith("#") or "=" not in line:
+ continue
+ key, _, raw_value = line.partition("=")
+ key = key.strip()
+ value = raw_value.strip().strip('"').strip("'")
+ if key:
+ env[key] = value
+ except (OSError, PermissionError):
+ pass
+ return env
+
+
+def find_and_load_env():
+ env = {}
+ search = os.path.abspath(os.getcwd())
+ for _ in range(6):
+ for name in (".env.local", ".env"):
+ candidate = os.path.join(search, name)
+ if os.path.isfile(candidate):
+ env.update(load_env_file(candidate))
+ parent = os.path.dirname(search)
+ if parent == search:
+ break
+ search = parent
+ return env
+
+
+def get_config():
+ file_env = find_and_load_env()
+
+ def get(key):
+ return os.environ.get(key) or file_env.get(key, "")
+
+ url = get("GHOST_URL").rstrip("/")
+ content_key = get("GHOST_CONTENT_KEY")
+ content_type = get("GHOST_CONTENT_TYPE") or "posts"
+ return url, content_key, content_type
+
+
+# ── Security: SSRF protection ─────────────────────────────────────────────────
+
+def _is_private_ip(ip_str):
+ try:
+ addr = ipaddress.ip_address(ip_str)
+ return addr.is_loopback or addr.is_private or addr.is_link_local or addr.is_reserved
+ except ValueError:
+ return False
+
+
+def validate_url(url):
+ try:
+ parsed = urllib.parse.urlparse(url)
+ except Exception:
+ print("ERROR: GHOST_URL is not a valid URL.", file=sys.stderr)
+ sys.exit(1)
+
+ if parsed.scheme not in ("http", "https"):
+ print(f"ERROR: GHOST_URL must use http:// or https:// (got '{parsed.scheme}://')", file=sys.stderr)
+ sys.exit(1)
+
+ hostname = parsed.hostname or ""
+ if not hostname:
+ print("ERROR: GHOST_URL has no hostname.", file=sys.stderr)
+ sys.exit(1)
+
+ if _is_private_ip(hostname):
+ print(f"ERROR: GHOST_URL is a private/local address ('{hostname}'). Use a public Ghost URL.", file=sys.stderr)
+ sys.exit(1)
+
+ if hostname.lower() == "localhost":
+ print("ERROR: GHOST_URL points to localhost. Use a reachable Ghost URL.", file=sys.stderr)
+ sys.exit(1)
+
+ try:
+ for info in socket.getaddrinfo(hostname, None, type=socket.SOCK_STREAM):
+ if _is_private_ip(info[4][0]):
+ print(f"ERROR: GHOST_URL resolves to an internal address ({info[4][0]}). Use a public Ghost URL.", file=sys.stderr)
+ sys.exit(1)
+ except (socket.gaierror, OSError):
+ pass
+
+
+# ── HTTP helper with retry ────────────────────────────────────────────────────
+
+def ghost_get(url, api_path, content_key, resource, params=None, timeout=15, retries=3):
+ """GET {url}{api_path}/{resource}/?key={key}&{params}."""
+ all_params = {"key": content_key, **(params or {})}
+ full_url = f"{url}{api_path}/{resource}/?{urllib.parse.urlencode(all_params)}"
+ req = urllib.request.Request(full_url, headers={"Accept-Version": "v5.0"})
+ last_exc = None
+ for attempt in range(retries):
+ try:
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ return json.loads(resp.read())
+ except urllib.error.HTTPError as e:
+ if e.code in _RETRY_CODES and attempt < retries - 1:
+ wait = 2 ** attempt
+ print(f" HTTP {e.code} — retrying in {wait}s...", file=sys.stderr)
+ time.sleep(wait)
+ last_exc = e
+ continue
+ raise
+ except urllib.error.URLError as e:
+ if attempt < retries - 1:
+ wait = 2 ** attempt
+ print(f" Network error ({e.reason}) — retrying in {wait}s...", file=sys.stderr)
+ time.sleep(wait)
+ last_exc = e
+ continue
+ raise
+ raise last_exc
+
+
+# ── Validation checks ─────────────────────────────────────────────────────────
+
+def check_config(url, content_key):
+ if not url:
+ print("GHOST_NOT_CONFIGURED: Set GHOST_URL and GHOST_CONTENT_KEY to enable Ghost integration.", file=sys.stderr)
+ sys.exit(2)
+
+ if not content_key:
+ print("ERROR: GHOST_CONTENT_KEY is not set.", file=sys.stderr)
+ print("", file=sys.stderr)
+ print("Create a Content API key in Ghost admin:", file=sys.stderr)
+ print(" Settings → Integrations → Add custom integration → copy Content API Key", file=sys.stderr)
+ print("", file=sys.stderr)
+ print("Then set it in .env.local:", file=sys.stderr)
+ print(" GHOST_CONTENT_KEY=your_key_here", file=sys.stderr)
+ sys.exit(1)
+
+ validate_url(url)
+ print(f"Ghost URL: {url}", file=sys.stderr)
+
+
+def check_connectivity(url, content_key, content_type):
+ """Try each API path version; return (api_path, total)."""
+ last_error = None
+
+ for api_path in _API_PATHS:
+ try:
+ data = ghost_get(url, api_path, content_key, content_type, {"limit": 1, "fields": "id"})
+ total = data.get("meta", {}).get("pagination", {}).get("total", 0)
+ version = "v4+" if "/v3/" not in api_path else "v3"
+ print(f"Ghost {version} detected | content type: {content_type} | {total} published entries", file=sys.stderr)
+ return api_path, total
+ except urllib.error.HTTPError as e:
+ if e.code == 403:
+ print("ERROR: Ghost returned 403 Forbidden.", file=sys.stderr)
+ print("Your GHOST_CONTENT_KEY is invalid or has been revoked.", file=sys.stderr)
+ print("Regenerate it in: Settings → Integrations", file=sys.stderr)
+ sys.exit(1)
+ if e.code == 404 and api_path == _API_PATHS[-1]:
+ print(f"ERROR: Could not find Ghost Content API at {url}", file=sys.stderr)
+ print("Check that GHOST_URL points to your Ghost instance (not a CDN/proxy URL).", file=sys.stderr)
+ sys.exit(1)
+ last_error = e
+ continue
+ except urllib.error.URLError as e:
+ print(f"ERROR: Cannot reach Ghost at {url}", file=sys.stderr)
+ print(f" Network error: {e.reason}", file=sys.stderr)
+ sys.exit(1)
+
+ if last_error:
+ body = last_error.read().decode()[:200] if last_error.fp else "(no body)"
+ print(f"ERROR: Ghost API error {last_error.code}. Response: {body}", file=sys.stderr)
+ sys.exit(1)
+
+
+def main():
+ url, content_key, content_type = get_config()
+ check_config(url, content_key)
+ api_path, total = check_connectivity(url, content_key, content_type)
+ if total == 0:
+ print(f"WARNING: No published entries found in '{content_type}'.", file=sys.stderr)
+ print(f"OK: Ghost ready ({content_type}, {total} published)", file=sys.stderr)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/seo/seo-analysis/scripts/preflight_strapi.py b/seo/seo-analysis/scripts/preflight_strapi.py
new file mode 100644
index 00000000..948200dc
--- /dev/null
+++ b/seo/seo-analysis/scripts/preflight_strapi.py
@@ -0,0 +1,275 @@
+#!/usr/bin/env python3
+"""Pre-flight check for Strapi integration.
+
+Verifies STRAPI_URL and STRAPI_API_KEY are set, tests connectivity,
+detects API version (v4 or v5), and confirms the content type is accessible.
+Credentials are loaded from environment variables or .env files.
+
+No external dependencies — uses only Python stdlib.
+
+Exit codes:
+ 0 — Strapi connection ready
+ 1 — unrecoverable error (missing config, auth failed, wrong content type, etc.)
+ 2 — Strapi not configured (STRAPI_URL not set) — non-fatal, caller skips
+"""
+
+import ipaddress
+import json
+import os
+import socket
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+# ── Config loading ────────────────────────────────────────────────────────────
+
+def load_env_file(path):
+ env = {}
+ try:
+ with open(path) as f:
+ for line in f:
+ line = line.strip()
+ if not line or line.startswith("#") or "=" not in line:
+ continue
+ key, _, raw_value = line.partition("=")
+ key = key.strip()
+ value = raw_value.strip().strip('"').strip("'")
+ if key:
+ env[key] = value
+ except (OSError, PermissionError):
+ pass
+ return env
+
+
+def find_and_load_env():
+ env = {}
+ search = os.path.abspath(os.getcwd())
+ for _ in range(6):
+ for name in (".env.local", ".env"):
+ candidate = os.path.join(search, name)
+ if os.path.isfile(candidate):
+ env.update(load_env_file(candidate))
+ parent = os.path.dirname(search)
+ if parent == search:
+ break
+ search = parent
+ return env
+
+
+def get_config():
+ file_env = find_and_load_env()
+
+ def get(key):
+ return os.environ.get(key) or file_env.get(key, "")
+
+ url = get("STRAPI_URL").rstrip("/")
+ api_key = get("STRAPI_API_KEY")
+ content_type = get("STRAPI_CONTENT_TYPE") or "articles"
+ version_hint = get("STRAPI_VERSION") # "4" or "5" — explicit override
+ return url, api_key, content_type, version_hint
+
+
+# ── Security: SSRF protection ─────────────────────────────────────────────────
+
+def _is_private_ip(ip_str):
+ """Return True if the IP is loopback, private, link-local, or reserved."""
+ try:
+ addr = ipaddress.ip_address(ip_str)
+ return addr.is_loopback or addr.is_private or addr.is_link_local or addr.is_reserved
+ except ValueError:
+ return False
+
+
+def _hostname_resolves_to_internal(hostname):
+ """Resolve hostname and check if any address is internal. Non-fatal on DNS failure."""
+ try:
+ infos = socket.getaddrinfo(hostname, None, type=socket.SOCK_STREAM)
+ for info in infos:
+ ip = info[4][0]
+ if _is_private_ip(ip):
+ return True, ip
+ except (socket.gaierror, OSError):
+ pass
+ return False, None
+
+
+def validate_url(url):
+ """Validate URL scheme and block SSRF targets (localhost, RFC1918, link-local)."""
+ try:
+ parsed = urllib.parse.urlparse(url)
+ except Exception:
+ print("ERROR: STRAPI_URL is not a valid URL.", file=sys.stderr)
+ sys.exit(1)
+
+ if parsed.scheme not in ("http", "https"):
+ print(f"ERROR: STRAPI_URL must use http:// or https:// (got '{parsed.scheme}://')", file=sys.stderr)
+ sys.exit(1)
+
+ hostname = parsed.hostname or ""
+ if not hostname:
+ print("ERROR: STRAPI_URL has no hostname.", file=sys.stderr)
+ sys.exit(1)
+
+ # If the hostname is a literal IP, check it directly via ipaddress (no DNS needed).
+ # If it's a hostname, fall through to the DNS-based check below.
+ if _is_private_ip(hostname):
+ print(f"ERROR: STRAPI_URL is a private/local address ('{hostname}'). Use a public CMS URL.", file=sys.stderr)
+ sys.exit(1)
+
+ if hostname.lower() in ("localhost",):
+ print(f"ERROR: STRAPI_URL points to localhost. Use a reachable CMS URL.", file=sys.stderr)
+ sys.exit(1)
+
+ # DNS-based check for hostnames that resolve to internal IPs (best-effort)
+ is_internal, resolved_ip = _hostname_resolves_to_internal(hostname)
+ if is_internal:
+ print(f"ERROR: STRAPI_URL resolves to an internal address ({resolved_ip}). Use a public CMS URL.", file=sys.stderr)
+ sys.exit(1)
+
+
+# ── HTTP helper with retry ────────────────────────────────────────────────────
+
+_RETRY_CODES = {429, 502, 503, 504}
+
+
+def strapi_get(url, api_key, path, params=None, timeout=15, retries=3):
+ """GET {url}{path}?{params}. Retries on transient failures with backoff."""
+ full_url = f"{url}{path}"
+ if params:
+ full_url = f"{full_url}?{urllib.parse.urlencode(params)}"
+ req = urllib.request.Request(
+ full_url,
+ headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+ )
+ last_exc = None
+ for attempt in range(retries):
+ try:
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ return json.loads(resp.read())
+ except urllib.error.HTTPError as e:
+ if e.code in _RETRY_CODES and attempt < retries - 1:
+ wait = 2 ** attempt
+ print(f" HTTP {e.code} — retrying in {wait}s...", file=sys.stderr)
+ time.sleep(wait)
+ last_exc = e
+ continue
+ raise
+ except urllib.error.URLError as e:
+ if attempt < retries - 1:
+ wait = 2 ** attempt
+ print(f" Network error ({e.reason}) — retrying in {wait}s...", file=sys.stderr)
+ time.sleep(wait)
+ last_exc = e
+ continue
+ raise
+ raise last_exc # all retries exhausted
+
+
+# ── Version detection ─────────────────────────────────────────────────────────
+
+def detect_version(data, version_hint):
+ """Return 4 or 5. Explicit hint wins; otherwise infer from response structure."""
+ if version_hint in ("4", "5"):
+ return int(version_hint)
+ items = data.get("data", [])
+ if items:
+ return 4 if "attributes" in items[0] else 5
+ # Empty collection: cannot infer from items. Check pagination meta shape.
+ # v4 pagination has "total", v5 also has "total" — not distinguishable here.
+ # Fall back to v5 (newer default). User can override with STRAPI_VERSION=4.
+ return 5
+
+
+def publication_param(version):
+ """Return the correct publication filter param for the detected Strapi version."""
+ if version == 4:
+ return {"publicationState": "live"}
+ return {"status": "published"}
+
+
+# ── Validation checks ─────────────────────────────────────────────────────────
+
+def check_config(url, api_key):
+ if not url:
+ print("STRAPI_NOT_CONFIGURED: Set STRAPI_URL and STRAPI_API_KEY to enable Strapi integration.", file=sys.stderr)
+ sys.exit(2)
+
+ if not api_key:
+ print("ERROR: STRAPI_API_KEY is not set.", file=sys.stderr)
+ print("", file=sys.stderr)
+ print("Create a Full-access API token in Strapi admin:", file=sys.stderr)
+ print(" Settings → Global settings → API Tokens → Create new API Token", file=sys.stderr)
+ print("", file=sys.stderr)
+ print("Then set it in .env.local:", file=sys.stderr)
+ print(" STRAPI_API_KEY=your_token_here", file=sys.stderr)
+ sys.exit(1)
+
+ validate_url(url)
+ print(f"Strapi URL: {url}", file=sys.stderr)
+
+
+def check_connectivity(url, api_key, content_type, version_hint):
+ """Probe the content type, detect version, return (version, total)."""
+ # Probe without publication filter first — lets us detect version from response.
+ probe_params = {"pagination[page]": 1, "pagination[pageSize]": 1}
+ try:
+ data = strapi_get(url, api_key, f"/api/{content_type}", probe_params)
+ except urllib.error.HTTPError as e:
+ body = e.read().decode()[:200] if e.fp else "(no body)" # truncate — don't leak stack traces
+ if e.code == 401:
+ print("ERROR: Strapi returned 401 Unauthorized.", file=sys.stderr)
+ print("Your STRAPI_API_KEY is invalid or expired.", file=sys.stderr)
+ print("Regenerate it in: Settings → API Tokens", file=sys.stderr)
+ sys.exit(1)
+ if e.code == 403:
+ print("ERROR: Strapi returned 403 Forbidden.", file=sys.stderr)
+ print(f"The API token lacks permission to read '{content_type}'.", file=sys.stderr)
+ print("Use a Full-access token or grant find/findOne permissions.", file=sys.stderr)
+ sys.exit(1)
+ if e.code == 404:
+ print(f"ERROR: Content type '{content_type}' not found (404).", file=sys.stderr)
+ print("Check the plural API ID in Strapi admin:", file=sys.stderr)
+ print(" Content-Type Builder → [your type] → API ID (plural)", file=sys.stderr)
+ print("Override with: STRAPI_CONTENT_TYPE=blog-posts (in .env.local)", file=sys.stderr)
+ sys.exit(1)
+ print(f"ERROR: Strapi API error {e.code}. Response: {body}", file=sys.stderr)
+ sys.exit(1)
+ except urllib.error.URLError as e:
+ print(f"ERROR: Cannot reach Strapi at {url}", file=sys.stderr)
+ print(f" Network error: {e.reason}", file=sys.stderr)
+ sys.exit(1)
+
+ version = detect_version(data, version_hint)
+
+ # Now fetch published count with the correct version-specific param
+ pub_params = {"pagination[page]": 1, "pagination[pageSize]": 1, **publication_param(version)}
+ try:
+ pub_data = strapi_get(url, api_key, f"/api/{content_type}", pub_params)
+ except Exception:
+ pub_data = data # fall back to probe result
+
+ total = pub_data.get("meta", {}).get("pagination", {}).get("total", 0)
+
+ if version_hint and version_hint not in ("4", "5"):
+ print(f"WARNING: STRAPI_VERSION='{version_hint}' is invalid. Use '4' or '5'. Detected v{version}.", file=sys.stderr)
+
+ print(f"Strapi v{version} detected | content type: {content_type} | {total} published entries", file=sys.stderr)
+ return version, total
+
+
+def main():
+ url, api_key, content_type, version_hint = get_config()
+ check_config(url, api_key)
+ version, total = check_connectivity(url, api_key, content_type, version_hint)
+ if total == 0:
+ print(f"WARNING: No published entries found in '{content_type}'.", file=sys.stderr)
+ if not version_hint:
+ print(" If this is a v4 instance with live content, set STRAPI_VERSION=4 in .env.local", file=sys.stderr)
+ print(f"OK: Strapi ready (v{version}, {content_type}, {total} published)", file=sys.stderr)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/seo/seo-analysis/scripts/preflight_wordpress.py b/seo/seo-analysis/scripts/preflight_wordpress.py
new file mode 100644
index 00000000..d41a719c
--- /dev/null
+++ b/seo/seo-analysis/scripts/preflight_wordpress.py
@@ -0,0 +1,263 @@
+#!/usr/bin/env python3
+"""Pre-flight check for WordPress REST API integration.
+
+Verifies WP_URL, WP_USERNAME, and WP_APP_PASSWORD are set, tests connectivity
+via the WordPress REST API, detects installed SEO plugins (Yoast, RankMath),
+and reports the total published entry count.
+
+Uses WordPress Application Passwords (WP 5.6+) for authentication.
+No external dependencies — uses only Python stdlib.
+
+Exit codes:
+ 0 — WordPress connection ready
+ 1 — unrecoverable error (missing config, auth failed, wrong content type, etc.)
+ 2 — WordPress not configured (WP_URL not set) — non-fatal, caller skips
+"""
+
+import base64
+import ipaddress
+import json
+import os
+import socket
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+_RETRY_CODES = {429, 502, 503, 504}
+
+
+# ── Config loading ────────────────────────────────────────────────────────────
+
+def load_env_file(path):
+ env = {}
+ try:
+ with open(path) as f:
+ for line in f:
+ line = line.strip()
+ if not line or line.startswith("#") or "=" not in line:
+ continue
+ key, _, raw_value = line.partition("=")
+ key = key.strip()
+ value = raw_value.strip().strip('"').strip("'")
+ if key:
+ env[key] = value
+ except (OSError, PermissionError):
+ pass
+ return env
+
+
+def find_and_load_env():
+ env = {}
+ search = os.path.abspath(os.getcwd())
+ for _ in range(6):
+ for name in (".env.local", ".env"):
+ candidate = os.path.join(search, name)
+ if os.path.isfile(candidate):
+ env.update(load_env_file(candidate))
+ parent = os.path.dirname(search)
+ if parent == search:
+ break
+ search = parent
+ return env
+
+
+def get_config():
+ file_env = find_and_load_env()
+
+ def get(key):
+ return os.environ.get(key) or file_env.get(key, "")
+
+ url = get("WP_URL").rstrip("/")
+ username = get("WP_USERNAME")
+ app_password = get("WP_APP_PASSWORD")
+ content_type = get("WP_CONTENT_TYPE") or "posts"
+ return url, username, app_password, content_type
+
+
+# ── Security: SSRF protection ─────────────────────────────────────────────────
+
+def _is_private_ip(ip_str):
+ try:
+ addr = ipaddress.ip_address(ip_str)
+ return addr.is_loopback or addr.is_private or addr.is_link_local or addr.is_reserved
+ except ValueError:
+ return False
+
+
+def validate_url(url):
+ """Validate URL scheme and block SSRF targets."""
+ try:
+ parsed = urllib.parse.urlparse(url)
+ except Exception:
+ print("ERROR: WP_URL is not a valid URL.", file=sys.stderr)
+ sys.exit(1)
+
+ if parsed.scheme not in ("http", "https"):
+ print(f"ERROR: WP_URL must use http:// or https:// (got '{parsed.scheme}://')", file=sys.stderr)
+ sys.exit(1)
+
+ hostname = parsed.hostname or ""
+ if not hostname:
+ print("ERROR: WP_URL has no hostname.", file=sys.stderr)
+ sys.exit(1)
+
+ if _is_private_ip(hostname):
+ print(f"ERROR: WP_URL is a private/local address ('{hostname}'). Use a public WordPress URL.", file=sys.stderr)
+ sys.exit(1)
+
+ if hostname.lower() == "localhost":
+ print("ERROR: WP_URL points to localhost. Use a reachable WordPress URL.", file=sys.stderr)
+ sys.exit(1)
+
+ try:
+ for info in socket.getaddrinfo(hostname, None, type=socket.SOCK_STREAM):
+ if _is_private_ip(info[4][0]):
+ print(f"ERROR: WP_URL resolves to an internal address ({info[4][0]}). Use a public WordPress URL.", file=sys.stderr)
+ sys.exit(1)
+ except (socket.gaierror, OSError):
+ pass # non-fatal; let the request fail naturally
+
+
+# ── HTTP helper ───────────────────────────────────────────────────────────────
+
+def wp_get(url, auth_header, path, params=None, timeout=15, retries=3):
+ """GET {url}{path}?{params} with Basic auth. Retries on transient failures."""
+ full_url = f"{url}{path}"
+ if params:
+ full_url = f"{full_url}?{urllib.parse.urlencode(params)}"
+ req = urllib.request.Request(
+ full_url,
+ headers={"Authorization": auth_header, "Accept": "application/json"},
+ )
+ last_exc = None
+ for attempt in range(retries):
+ try:
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ body = json.loads(resp.read())
+ total = int(resp.headers.get("X-WP-Total", 0))
+ total_pages = int(resp.headers.get("X-WP-TotalPages", 1))
+ return body, total, total_pages
+ except urllib.error.HTTPError as e:
+ if e.code in _RETRY_CODES and attempt < retries - 1:
+ wait = 2 ** attempt
+ print(f" HTTP {e.code} — retrying in {wait}s...", file=sys.stderr)
+ time.sleep(wait)
+ last_exc = e
+ continue
+ raise
+ except urllib.error.URLError as e:
+ if attempt < retries - 1:
+ wait = 2 ** attempt
+ print(f" Network error ({e.reason}) — retrying in {wait}s...", file=sys.stderr)
+ time.sleep(wait)
+ last_exc = e
+ continue
+ raise
+ raise last_exc
+
+
+def make_auth_header(username, app_password):
+ """Build Basic auth header from WP username + Application Password."""
+ # Application Passwords are displayed with spaces for readability — strip them.
+ password = app_password.replace(" ", "")
+ credentials = base64.b64encode(f"{username}:{password}".encode()).decode()
+ return f"Basic {credentials}"
+
+
+# ── Validation checks ─────────────────────────────────────────────────────────
+
+def check_config(url, username, app_password):
+ if not url:
+ print("WP_NOT_CONFIGURED: Set WP_URL, WP_USERNAME, and WP_APP_PASSWORD to enable WordPress integration.", file=sys.stderr)
+ sys.exit(2)
+
+ if not username:
+ print("ERROR: WP_USERNAME is not set.", file=sys.stderr)
+ print("", file=sys.stderr)
+ print("Set your WordPress username in .env.local:", file=sys.stderr)
+ print(" WP_USERNAME=your_username", file=sys.stderr)
+ sys.exit(1)
+
+ if not app_password:
+ print("ERROR: WP_APP_PASSWORD is not set.", file=sys.stderr)
+ print("", file=sys.stderr)
+ print("Create an Application Password in WordPress admin:", file=sys.stderr)
+ print(" Users → Profile → Application Passwords → Add New Application Password", file=sys.stderr)
+ print("", file=sys.stderr)
+ print("Then set it in .env.local:", file=sys.stderr)
+ print(" WP_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx", file=sys.stderr)
+ sys.exit(1)
+
+ validate_url(url)
+ print(f"WordPress URL: {url}", file=sys.stderr)
+
+
+def check_connectivity(url, auth_header, content_type):
+ """Probe the REST API, detect SEO plugins, return total published count."""
+ try:
+ items, total, _ = wp_get(url, auth_header, f"/wp-json/wp/v2/{content_type}", {
+ "status": "publish",
+ "per_page": 1,
+ "_fields": "id,yoast_head_json",
+ })
+ except urllib.error.HTTPError as e:
+ body = e.read().decode()[:300] if e.fp else "(no body)"
+ if e.code == 401:
+ print("ERROR: WordPress returned 401 Unauthorized.", file=sys.stderr)
+ print("Your WP_USERNAME or WP_APP_PASSWORD is invalid.", file=sys.stderr)
+ print("Regenerate the Application Password in: Users → Profile → Application Passwords", file=sys.stderr)
+ sys.exit(1)
+ if e.code == 403:
+ print("ERROR: WordPress returned 403 Forbidden.", file=sys.stderr)
+ print(f"The user '{content_type}' may not have REST API access.", file=sys.stderr)
+ sys.exit(1)
+ if e.code == 404:
+ print(f"ERROR: Content type '{content_type}' not found (404).", file=sys.stderr)
+ print("Check the content type slug. Common values: posts, pages.", file=sys.stderr)
+ print("Override with: WP_CONTENT_TYPE=your-type (in .env.local)", file=sys.stderr)
+ sys.exit(1)
+ print(f"ERROR: WordPress API error {e.code}. Response: {body}", file=sys.stderr)
+ sys.exit(1)
+ except urllib.error.URLError as e:
+ print(f"ERROR: Cannot reach WordPress at {url}", file=sys.stderr)
+ print(f" Network error: {e.reason}", file=sys.stderr)
+ sys.exit(1)
+
+ # Detect SEO plugins from first item's fields
+ seo_plugin = "none detected"
+ if items:
+ item = items[0] if isinstance(items, list) else items
+ if "yoast_head_json" in item:
+ seo_plugin = "Yoast SEO"
+
+ if seo_plugin == "none detected":
+ # Check REST API namespaces for plugin detection
+ try:
+ ns_data, _, _ = wp_get(url, auth_header, "/wp-json/", timeout=10, retries=1)
+ namespaces = ns_data.get("namespaces", [])
+ if any(ns.startswith("yoast") for ns in namespaces):
+ seo_plugin = "Yoast SEO"
+ elif any(ns.startswith("rankmath") for ns in namespaces):
+ seo_plugin = "RankMath"
+ except Exception:
+ pass
+
+ print(f"WordPress REST API ready | content type: {content_type} | {total} published | SEO plugin: {seo_plugin}", file=sys.stderr)
+ return total, seo_plugin
+
+
+def main():
+ url, username, app_password, content_type = get_config()
+ check_config(url, username, app_password)
+ auth_header = make_auth_header(username, app_password)
+ total, seo_plugin = check_connectivity(url, auth_header, content_type)
+ if total == 0:
+ print(f"WARNING: No published entries found in '{content_type}'.", file=sys.stderr)
+ print(f"OK: WordPress ready ({content_type}, {total} published, {seo_plugin})", file=sys.stderr)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/seo/seo-analysis/scripts/push_strapi_seo.py b/seo/seo-analysis/scripts/push_strapi_seo.py
new file mode 100644
index 00000000..3af4de7b
--- /dev/null
+++ b/seo/seo-analysis/scripts/push_strapi_seo.py
@@ -0,0 +1,480 @@
+#!/usr/bin/env python3
+"""Push SEO metadata updates back to Strapi.
+
+Reads a batch of recommended SEO updates, shows a diff of proposed changes,
+and writes them to Strapi after confirmation.
+
+Supports Strapi v4 (PUT /api/{type}/{id}) and v5 (PUT /api/{type}/{documentId}).
+Locale-aware: for localized v5 content, pass --locale or include 'locale' in batch.
+No external dependencies — uses only Python stdlib.
+
+Usage — single entry:
+ python3 push_strapi_seo.py \\
+ --document-id clkgylmcc000008lcdd868feh \\
+ --meta-title "New Title | Brand" \\
+ --meta-description "Compelling 120-char description."
+
+ # Localized v5:
+ python3 push_strapi_seo.py \\
+ --document-id clkgylmcc000008lcdd868feh \\
+ --locale fr \\
+ --meta-title "Nouveau titre | Marque"
+
+Usage — batch from file:
+ python3 push_strapi_seo.py --batch-file /tmp/seo_updates.json [--yes]
+
+Batch file format (JSON array):
+ [
+ {
+ "document_id": "clkgylmcc000008lcdd868feh", // v5
+ "id": 42, // v4 fallback
+ "locale": "en", // optional, v5 localized
+ "seo_schema": "component", // "component" | "root_fields"
+ "meta_title": "New Title | Brand",
+ "meta_description": "New description.",
+ "updated_at": "2024-01-20T14:30:00.000Z" // optional: refuse if stale
+ }
+ ]
+
+Environment variables (or .env / .env.local):
+ STRAPI_URL Required.
+ STRAPI_API_KEY Required. Must be Full-access token (not read-only).
+ STRAPI_CONTENT_TYPE Optional (default: articles).
+ STRAPI_VERSION Optional. Force '4' or '5'.
+"""
+
+import argparse
+import ipaddress
+import json
+import os
+import socket
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+_RETRY_CODES = {429, 502, 503, 504}
+
+
+# ── SSRF protection ───────────────────────────────────────────────────────────
+
+def _is_private_ip(ip_str):
+ try:
+ addr = ipaddress.ip_address(ip_str)
+ return addr.is_loopback or addr.is_private or addr.is_link_local or addr.is_reserved
+ except ValueError:
+ return False
+
+
+def validate_url(url):
+ """Block SSRF targets. Called before any HTTP requests are made."""
+ try:
+ parsed = urllib.parse.urlparse(url)
+ except Exception:
+ print("ERROR: STRAPI_URL is not a valid URL.", file=sys.stderr)
+ sys.exit(1)
+ if parsed.scheme not in ("http", "https"):
+ print(f"ERROR: STRAPI_URL must use http:// or https://", file=sys.stderr)
+ sys.exit(1)
+ hostname = parsed.hostname or ""
+ if not hostname:
+ print("ERROR: STRAPI_URL has no hostname.", file=sys.stderr)
+ sys.exit(1)
+ if _is_private_ip(hostname):
+ print(f"ERROR: STRAPI_URL is a private/local address ('{hostname}').", file=sys.stderr)
+ sys.exit(1)
+ if hostname.lower() == "localhost":
+ print("ERROR: STRAPI_URL points to localhost.", file=sys.stderr)
+ sys.exit(1)
+ # DNS-based check (best-effort)
+ try:
+ for info in socket.getaddrinfo(hostname, None, type=socket.SOCK_STREAM):
+ if _is_private_ip(info[4][0]):
+ print(f"ERROR: STRAPI_URL resolves to an internal address ({info[4][0]}).", file=sys.stderr)
+ sys.exit(1)
+ except (socket.gaierror, OSError):
+ pass # non-fatal; let the request fail naturally
+
+
+# ── Config loading ────────────────────────────────────────────────────────────
+
+def load_env_file(path):
+ env = {}
+ try:
+ with open(path) as f:
+ for line in f:
+ line = line.strip()
+ if not line or line.startswith("#") or "=" not in line:
+ continue
+ key, _, raw_value = line.partition("=")
+ key = key.strip()
+ value = raw_value.strip().strip('"').strip("'")
+ if key:
+ env[key] = value
+ except (OSError, PermissionError):
+ pass
+ return env
+
+
+def find_and_load_env():
+ env = {}
+ search = os.path.abspath(os.getcwd())
+ for _ in range(6):
+ for name in (".env.local", ".env"):
+ candidate = os.path.join(search, name)
+ if os.path.isfile(candidate):
+ env.update(load_env_file(candidate))
+ parent = os.path.dirname(search)
+ if parent == search:
+ break
+ search = parent
+ return env
+
+
+def get_config():
+ file_env = find_and_load_env()
+
+ def get(key):
+ return os.environ.get(key) or file_env.get(key, "")
+
+ return (
+ get("STRAPI_URL").rstrip("/"),
+ get("STRAPI_API_KEY"),
+ get("STRAPI_CONTENT_TYPE") or "articles",
+ get("STRAPI_VERSION"),
+ )
+
+
+# ── HTTP helpers with retry ───────────────────────────────────────────────────
+
+def _headers(api_key):
+ return {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
+
+
+def strapi_get(base_url, api_key, path, params=None, timeout=15, retries=3):
+ full_url = f"{base_url}{path}"
+ if params:
+ full_url = f"{full_url}?{urllib.parse.urlencode(params)}"
+ req = urllib.request.Request(full_url, headers=_headers(api_key))
+ last_exc = None
+ for attempt in range(retries):
+ try:
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ return json.loads(resp.read())
+ except urllib.error.HTTPError as e:
+ if e.code in _RETRY_CODES and attempt < retries - 1:
+ time.sleep(2 ** attempt)
+ last_exc = e
+ continue
+ raise
+ except urllib.error.URLError as e:
+ if attempt < retries - 1:
+ time.sleep(2 ** attempt)
+ last_exc = e
+ continue
+ raise
+ raise last_exc
+
+
+def strapi_put(base_url, api_key, path, payload, timeout=30, retries=3):
+ full_url = f"{base_url}{path}"
+ data = json.dumps(payload).encode()
+ req = urllib.request.Request(
+ full_url, data=data, method="PUT", headers=_headers(api_key)
+ )
+ last_exc = None
+ for attempt in range(retries):
+ try:
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ return json.loads(resp.read())
+ except urllib.error.HTTPError as e:
+ if e.code in _RETRY_CODES and attempt < retries - 1:
+ time.sleep(2 ** attempt)
+ last_exc = e
+ continue
+ raise
+ except urllib.error.URLError as e:
+ if attempt < retries - 1:
+ time.sleep(2 ** attempt)
+ last_exc = e
+ continue
+ raise
+ raise last_exc
+
+
+# ── Version detection ─────────────────────────────────────────────────────────
+
+def detect_version(raw, version_hint):
+ """Detect v4 vs v5 from a single-entry GET response."""
+ if version_hint in ("4", "5"):
+ return int(version_hint)
+ data = raw.get("data", {})
+ return 4 if "attributes" in data else 5
+
+
+# ── Current SEO value fetching ────────────────────────────────────────────────
+
+def fetch_current_seo(base_url, api_key, content_type, entry_id, locale, version):
+ params = {"populate": "seo"}
+ if version == 5 and locale:
+ params["locale"] = locale
+ try:
+ data = strapi_get(base_url, api_key, f"/api/{content_type}/{entry_id}", params)
+ except Exception as e:
+ print(f" WARNING: Could not fetch current values for {entry_id}: {e}", file=sys.stderr)
+ return {}, {}
+
+ raw = data.get("data", {})
+ attrs = raw.get("attributes", raw) # works for both v4 and v5
+
+ seo = attrs.get("seo") or {}
+ if isinstance(seo, dict) and "data" in seo:
+ seo = seo["data"].get("attributes", seo)
+
+ current_seo = {
+ "meta_title": seo.get("metaTitle") or attrs.get("metaTitle") or "",
+ "meta_description": seo.get("metaDescription") or attrs.get("metaDescription") or "",
+ "updated_at": attrs.get("updatedAt") or "",
+ }
+ return current_seo, attrs
+
+
+# ── Payload builder ───────────────────────────────────────────────────────────
+
+def build_payload(update, current_attrs, seo_schema):
+ """Build the PUT payload. Respects the schema in use (component vs root fields)."""
+ seo_patch = {}
+ if "meta_title" in update:
+ seo_patch["metaTitle"] = update["meta_title"]
+ if "meta_description" in update:
+ seo_patch["metaDescription"] = update["meta_description"]
+
+ if not seo_patch:
+ return None
+
+ # Determine schema: prefer explicit flag from fetch output, else detect from attrs
+ use_component = seo_schema == "component"
+ if seo_schema not in ("component", "root_fields"):
+ # Auto-detect: if current attrs have a 'seo' key, use component schema
+ use_component = "seo" in (current_attrs or {})
+
+ if use_component:
+ # Merge with existing SEO component to avoid clobbering unrelated fields
+ existing_seo = (current_attrs or {}).get("seo") or {}
+ if isinstance(existing_seo, dict) and "data" in existing_seo:
+ existing_seo = existing_seo["data"].get("attributes", {})
+ merged_seo = {**{k: v for k, v in existing_seo.items()
+ if k not in ("metaImage", "metaSocial")},
+ **seo_patch}
+ return {"data": {"seo": merged_seo}}
+ else:
+ # Root-level SEO fields
+ return {"data": seo_patch}
+
+
+# ── Diff display ──────────────────────────────────────────────────────────────
+
+def print_diff(entry_id, update, current, locale=None):
+ loc_label = f" [{locale}]" if locale else ""
+ print(f"\n Entry: {entry_id}{loc_label}", file=sys.stderr)
+ for field in ("meta_title", "meta_description"):
+ if field not in update:
+ continue
+ old_val = current.get(field) or "(empty)"
+ new_val = update[field]
+ label = "Meta Title" if field == "meta_title" else "Meta Description"
+ char_limit = 60 if field == "meta_title" else 160
+ print(f" {label}:", file=sys.stderr)
+ print(f" - {old_val}", file=sys.stderr)
+ print(f" + {new_val}", file=sys.stderr)
+ if len(new_val) > char_limit:
+ print(f" WARNING: exceeds {char_limit} chars ({len(new_val)})", file=sys.stderr)
+ if len(new_val) == 0:
+ print(f" WARNING: new value is empty — will blank this field", file=sys.stderr)
+
+
+# ── Confirmation ──────────────────────────────────────────────────────────────
+
+def confirm_batch(count, auto_yes=False):
+ if auto_yes:
+ return True
+ if not sys.stdin.isatty():
+ print("ERROR: --yes flag required in non-interactive mode.", file=sys.stderr)
+ sys.exit(1)
+ print(f"\nApply {count} SEO update(s) to Strapi? [y/N] ", end="", file=sys.stderr, flush=True)
+ return input().strip().lower() in ("y", "yes")
+
+
+# ── Core update logic ─────────────────────────────────────────────────────────
+
+def process_updates(base_url, api_key, content_type, updates, version_hint, auto_yes=False):
+ if not updates:
+ print("No updates to apply.", file=sys.stderr)
+ return
+
+ # Short-circuit: if version_hint is explicit, skip the probe entirely
+ if version_hint in ("4", "5"):
+ version = int(version_hint)
+ else:
+ version = 5 # default; probe to confirm
+ for upd in updates:
+ entry_id = upd.get("document_id") or str(upd.get("id", ""))
+ if not entry_id:
+ continue
+ try:
+ probe = strapi_get(base_url, api_key, f"/api/{content_type}/{entry_id}")
+ version = detect_version(probe, version_hint)
+ break
+ except Exception:
+ continue
+
+ print(f"Strapi v{version} | {content_type}", file=sys.stderr)
+
+ # Build diffs
+ print(f"\nProposed changes ({len(updates)} entries):", file=sys.stderr)
+ print("-" * 60, file=sys.stderr)
+
+ enriched = []
+ skipped = 0
+ for upd in updates:
+ entry_id = upd.get("document_id") or str(upd.get("id", ""))
+ locale = upd.get("locale") or ""
+ seo_schema = upd.get("seo_schema") or "auto"
+
+ if not entry_id:
+ print(f" SKIP: entry missing document_id/id: {upd}", file=sys.stderr)
+ skipped += 1
+ continue
+
+ current_seo, current_attrs = fetch_current_seo(
+ base_url, api_key, content_type, entry_id, locale, version
+ )
+
+ # Stale-write guard: refuse if entry was modified since the batch was generated
+ expected_updated_at = upd.get("updated_at") or ""
+ live_updated_at = current_seo.get("updated_at") or ""
+ if expected_updated_at and live_updated_at and expected_updated_at != live_updated_at:
+ print(
+ f" SKIP {entry_id}: entry was modified since analysis "
+ f"(expected {expected_updated_at}, got {live_updated_at}). "
+ f"Re-run analysis before pushing.",
+ file=sys.stderr,
+ )
+ skipped += 1
+ continue
+
+ print_diff(entry_id, upd, current_seo, locale)
+ enriched.append((entry_id, upd, current_seo, current_attrs, locale, seo_schema))
+
+ print("-" * 60, file=sys.stderr)
+
+ if not enriched:
+ print("No valid entries to update after review.", file=sys.stderr)
+ sys.exit(0 if skipped == 0 else 1)
+
+ if not confirm_batch(len(enriched), auto_yes):
+ print("Aborted. No changes written.", file=sys.stderr)
+ sys.exit(0)
+
+ # Apply updates
+ success = 0
+ failed = 0
+ for entry_id, upd, _current, current_attrs, locale, seo_schema in enriched:
+ payload = build_payload(upd, current_attrs, seo_schema)
+ if not payload:
+ print(f" SKIP {entry_id}: nothing to update", file=sys.stderr)
+ continue
+
+ path = f"/api/{content_type}/{entry_id}"
+ params = {}
+ if version == 5 and locale:
+ params["locale"] = locale
+ if params:
+ path = f"{path}?{urllib.parse.urlencode(params)}"
+
+ try:
+ strapi_put(base_url, api_key, path, payload)
+ loc_label = f" [{locale}]" if locale else ""
+ print(f" OK {entry_id}{loc_label}", file=sys.stderr)
+ success += 1
+ except urllib.error.HTTPError as e:
+ body = e.read().decode()[:200] if e.fp else "(no body)"
+ print(f" FAIL {entry_id}: HTTP {e.code}: {body}", file=sys.stderr)
+ failed += 1
+ except urllib.error.URLError as e:
+ print(f" FAIL {entry_id}: network error: {e.reason}", file=sys.stderr)
+ failed += 1
+
+ print(f"\nDone. {success} updated, {failed} failed, {skipped} skipped.", file=sys.stderr)
+ if failed:
+ sys.exit(1)
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────────
+
+def main():
+ parser = argparse.ArgumentParser(description="Push SEO updates to Strapi")
+ parser.add_argument("--content-type", help="Override STRAPI_CONTENT_TYPE")
+ parser.add_argument("--document-id", help="Strapi v5 documentId (single entry)")
+ parser.add_argument("--id", type=int, help="Strapi v4 numeric id (single entry)")
+ parser.add_argument("--locale", help="Locale for v5 localized content (e.g. 'fr', 'en')")
+ parser.add_argument("--meta-title", help="New meta title (max 60 chars)")
+ parser.add_argument("--meta-description", help="New meta description (70-160 chars)")
+ parser.add_argument("--batch-file", help="JSON file with array of update objects")
+ parser.add_argument("--yes", "-y", action="store_true", help="Skip confirmation prompt")
+ args = parser.parse_args()
+
+ base_url, api_key, content_type, version_hint = get_config()
+ if args.content_type:
+ content_type = args.content_type
+
+ if not base_url:
+ print("ERROR: STRAPI_URL is not set.", file=sys.stderr)
+ sys.exit(1)
+ if not api_key:
+ print("ERROR: STRAPI_API_KEY is not set.", file=sys.stderr)
+ sys.exit(1)
+
+ validate_url(base_url)
+
+ if args.batch_file:
+ try:
+ with open(args.batch_file) as f:
+ updates = json.load(f)
+ if not isinstance(updates, list):
+ print("ERROR: batch file must contain a JSON array.", file=sys.stderr)
+ sys.exit(1)
+ except (OSError, json.JSONDecodeError) as e:
+ print(f"ERROR: Could not read batch file: {e}", file=sys.stderr)
+ sys.exit(1)
+ elif args.document_id or args.id:
+ if not args.meta_title and not args.meta_description:
+ print("ERROR: Provide --meta-title and/or --meta-description.", file=sys.stderr)
+ sys.exit(1)
+ update = {}
+ if args.document_id:
+ update["document_id"] = args.document_id
+ if args.id:
+ update["id"] = args.id
+ if args.locale:
+ import re
+ if not re.match(r"^[a-z]{2}(-[A-Z]{2})?$", args.locale):
+ print(f"ERROR: Invalid locale '{args.locale}'. Expected format: 'en' or 'en-US'.", file=sys.stderr)
+ sys.exit(1)
+ update["locale"] = args.locale
+ if args.meta_title:
+ update["meta_title"] = args.meta_title
+ if args.meta_description:
+ update["meta_description"] = args.meta_description
+ updates = [update]
+ else:
+ parser.print_help()
+ sys.exit(1)
+
+ process_updates(base_url, api_key, content_type, updates, version_hint, auto_yes=args.yes)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/seo/seo-analysis/scripts/show_gsc.py b/seo/seo-analysis/scripts/show_gsc.py
new file mode 100644
index 00000000..38f7b41c
--- /dev/null
+++ b/seo/seo-analysis/scripts/show_gsc.py
@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""
+Display a human-readable summary of the GSC analysis JSON output.
+
+Usage:
+ python3 show_gsc.py [path/to/gsc_analysis.json]
+
+If no path is given, reads from the default temp file location.
+"""
+
+import json
+import os
+import sys
+import tempfile
+
+DEFAULT_PATH = os.path.join(tempfile.gettempdir(), f"gsc_analysis_{os.getuid()}.json")
+
+
+def fmt_ctr(ctr):
+ """CTR is stored as a percentage (e.g. 4.79 means 4.79%)."""
+ return f"{ctr:.2f}%"
+
+
+def show(path):
+ with open(path) as f:
+ data = json.load(f)
+
+ summary = data.get("summary", {})
+ print(f"\nSite: {data.get('site', '?')}")
+ period = data.get("period", {})
+ print(f"Period: {period.get('start', '?')} to {period.get('end', '?')} ({period.get('days', '?')} days)")
+ print(f"\nSummary: {summary.get('clicks', 0):,} clicks | {summary.get('impressions', 0):,} impressions "
+ f"| CTR {fmt_ctr(summary.get('ctr', 0))} | Avg position {summary.get('position', 0)}")
+
+ # Top pages
+ top_pages = data.get("top_pages", [])
+ if top_pages:
+ print(f"\n=== TOP {len(top_pages)} PAGES ===")
+ for i, p in enumerate(top_pages, 1):
+ print(f" {i:2}. {p['clicks']:5,} clk | {p['impressions']:7,} imp "
+ f"| CTR {fmt_ctr(p['ctr'])} | pos {p['position']} | {p['page']}")
+
+ # Top queries
+ top_queries = data.get("top_queries", [])
+ if top_queries:
+ print(f"\n=== TOP {len(top_queries)} QUERIES ===")
+ for i, q in enumerate(top_queries, 1):
+ print(f" {i:2}. {q['clicks']:5,} clk | {q['impressions']:7,} imp "
+ f"| CTR {fmt_ctr(q['ctr'])} | pos {q['position']} | {q['query']}")
+
+ # Position buckets
+ buckets = data.get("position_buckets", {})
+ if buckets:
+ print("\n=== POSITION BUCKETS ===")
+ for bucket_name in ["1-3", "4-10", "11-20", "21+"]:
+ rows = buckets.get(bucket_name, [])
+ print(f" [{bucket_name}]: {len(rows)} queries")
+
+ # CTR opportunities
+ ctr_opps = data.get("ctr_opportunities", [])
+ if ctr_opps:
+ print(f"\n=== CTR OPPORTUNITIES (high impressions, low CTR) ===")
+ for q in ctr_opps[:10]:
+ print(f" {q['impressions']:6,} imp | CTR {fmt_ctr(q['ctr'])} | pos {q['position']} | {q['query']}")
+
+ # Cannibalization
+ cannib = data.get("cannibalization", [])
+ if cannib:
+ print(f"\n=== CANNIBALIZATION ({len(cannib)} queries) ===")
+ for c in cannib[:5]:
+ print(f" '{c['query']}' → winner: {c['winner_page']}")
+ print(f" losers: {', '.join(c['loser_pages'])}")
+ print(f" action: {c['recommended_action']}")
+
+ # Declining pages/queries
+ comparison = data.get("comparison", {})
+ declining_pages = comparison.get("declining_pages", [])
+ declining_queries = comparison.get("declining_queries", [])
+ comp_period = comparison.get("period", "?")
+ comp_prior = comparison.get("prior_period", "?")
+ if declining_pages or declining_queries:
+ print(f"\n=== TRAFFIC CHANGES ({comp_period} vs {comp_prior}) ===")
+ if declining_pages:
+ print(f" Declining pages ({len(declining_pages)}):")
+ for p in declining_pages[:5]:
+ print(f" {p['change_pct']:+.1f}% | {p['clicks_now']:,} → {p['clicks_prev']:,} | {p['page']}")
+ if declining_queries:
+ print(f" Declining queries ({len(declining_queries)}):")
+ for q in declining_queries[:5]:
+ print(f" {q['change_pct']:+.1f}% | {q['clicks_now']:,} → {q['clicks_prev']:,} | {q['query']}")
+
+ # Device split
+ devices = data.get("device_split", [])
+ if devices:
+ print("\n=== DEVICE SPLIT ===")
+ for d in devices:
+ print(f" {d['device']:10} {d['clicks']:6,} clk | CTR {fmt_ctr(d['ctr'])} | pos {d['position']}")
+
+ # Search type split
+ search_types = data.get("search_type_split", [])
+ if search_types:
+ print("\n=== SEARCH TYPE SPLIT ===")
+ for t in search_types:
+ print(f" {t['type']:12} {t['clicks']:6,} clk | CTR {fmt_ctr(t['ctr'])} | pos {t['position']}")
+
+ # Branded split
+ branded = data.get("branded_split")
+ if branded:
+ b = branded.get("branded", {})
+ nb = branded.get("non_branded", {})
+ print("\n=== BRANDED vs NON-BRANDED ===")
+ print(f" Branded: {b.get('clicks', 0):6,} clk | {b.get('impressions', 0):,} imp "
+ f"| CTR {fmt_ctr(b.get('ctr', 0))} | {b.get('query_count', 0)} queries")
+ print(f" Non-branded: {nb.get('clicks', 0):6,} clk | {nb.get('impressions', 0):,} imp "
+ f"| CTR {fmt_ctr(nb.get('ctr', 0))} | {nb.get('query_count', 0)} queries")
+
+ # Page groups
+ page_groups = data.get("page_groups", [])
+ if page_groups:
+ print("\n=== PAGE GROUPS ===")
+ for g in page_groups:
+ print(f" {g['group']:15} {g['page_count']:3} pages | {g['clicks']:6,} clk "
+ f"| CTR {fmt_ctr(g['ctr'])} | pos {g['position']}")
+
+ print()
+
+
+if __name__ == "__main__":
+ path = sys.argv[1] if len(sys.argv) > 1 else DEFAULT_PATH
+ if not os.path.exists(path):
+ print(f"ERROR: GSC data file not found: {path}", file=sys.stderr)
+ print("Run analyze_gsc.py first to generate it.", file=sys.stderr)
+ sys.exit(1)
+ show(path)
diff --git a/seo/seo-analysis/scripts/url_inspection.py b/seo/seo-analysis/scripts/url_inspection.py
new file mode 100644
index 00000000..7b46bfda
--- /dev/null
+++ b/seo/seo-analysis/scripts/url_inspection.py
@@ -0,0 +1,358 @@
+#!/usr/bin/env python3
+"""
+Run the Google Search Console URL Inspection API on a list of URLs.
+Outputs structured JSON for the seo-analysis skill to process.
+
+The URL Inspection API returns per-page: indexing status, mobile usability verdict,
+rich result status, last crawl time, referring sitemaps, and coverage state.
+
+Required OAuth scope: https://www.googleapis.com/auth/webmasters
+(Not just webmasters.readonly — URL Inspection requires the broader scope.)
+
+Usage:
+ python3 url_inspection.py --site "sc-domain:example.com" \\
+ --urls "https://example.com/,https://example.com/pricing"
+
+ python3 url_inspection.py --site "https://example.com/" \\
+ --urls-file /tmp/urls.txt
+
+ python3 url_inspection.py --site "sc-domain:example.com" \\
+ --urls "https://example.com/,https://example.com/blog" \\
+ --output /tmp/inspection_results.json
+"""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.parse
+import urllib.request
+import urllib.error
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+
+def get_quota_project():
+ """Return the quota_project_id from the ADC JSON file, or None."""
+ adc_dir = os.environ.get("CLOUDSDK_CONFIG") or os.path.join(
+ os.path.expanduser("~"), ".config", "gcloud"
+ )
+ adc_path = os.path.join(adc_dir, "application_default_credentials.json")
+ try:
+ with open(adc_path) as f:
+ data = json.load(f)
+ if isinstance(data, dict):
+ return data.get("quota_project_id") or None
+ except (OSError, ValueError):
+ pass
+ return None
+
+
+def get_access_token():
+ try:
+ result = subprocess.run(
+ ["gcloud", "auth", "application-default", "print-access-token"],
+ capture_output=True, text=True, timeout=15
+ )
+ except FileNotFoundError:
+ print("ERROR: gcloud not found. Install it from https://cloud.google.com/sdk/docs/install",
+ file=sys.stderr)
+ sys.exit(1)
+ except subprocess.TimeoutExpired:
+ print("ERROR: gcloud timed out after 15s.", file=sys.stderr)
+ sys.exit(1)
+
+ if result.returncode != 0:
+ print("ERROR: Not authenticated. Run:", file=sys.stderr)
+ print(" gcloud auth application-default login \\", file=sys.stderr)
+ print(" --scopes=https://www.googleapis.com/auth/webmasters,"
+ "https://www.googleapis.com/auth/webmasters.readonly", file=sys.stderr)
+ sys.exit(1)
+
+ token = result.stdout.strip()
+ if not token:
+ print("ERROR: gcloud returned an empty token.", file=sys.stderr)
+ sys.exit(1)
+ return token
+
+
+def inspect_url(token, site_url, inspection_url):
+ """Call the URL Inspection API for one URL. Returns the raw API response dict."""
+ endpoint = "https://searchconsole.googleapis.com/v1/urlInspection/index:inspect"
+ body = json.dumps({
+ "inspectionUrl": inspection_url,
+ "siteUrl": site_url
+ }).encode()
+
+ headers = {
+ "Authorization": f"Bearer {token}",
+ "Content-Type": "application/json",
+ }
+ quota_project = get_quota_project()
+ if quota_project:
+ headers["x-goog-user-project"] = quota_project
+ req = urllib.request.Request(endpoint, data=body, headers=headers)
+
+ try:
+ with urllib.request.urlopen(req, timeout=30) as resp:
+ return json.loads(resp.read()), None
+ except urllib.error.HTTPError as e:
+ err_body = e.read().decode() if e.fp else ""
+ if e.code == 403:
+ return None, (
+ f"403 Forbidden for {inspection_url}. "
+ "The URL Inspection API requires the broader 'webmasters' OAuth scope "
+ "(not just 'webmasters.readonly'). Re-authenticate with:\n"
+ " gcloud auth application-default login \\\n"
+ " --scopes=https://www.googleapis.com/auth/webmasters,"
+ "https://www.googleapis.com/auth/webmasters.readonly"
+ )
+ return None, f"HTTP {e.code} for {inspection_url}: {err_body[:200]}"
+ except urllib.error.URLError as e:
+ return None, f"Network error for {inspection_url}: {e.reason}"
+
+
+def normalize_site_url_for_inspection(site_url, url):
+ """
+ For domain properties (sc-domain:example.com), the inspectionUrl must be
+ an absolute URL. For URL-prefix properties, it must start with the prefix.
+ If the caller passes a path like '/pricing', resolve it against the site URL.
+ """
+ if url.startswith("http://") or url.startswith("https://"):
+ return url
+
+ # Strip the sc-domain: prefix to get the bare domain
+ if site_url.startswith("sc-domain:"):
+ domain = site_url[len("sc-domain:"):]
+ return f"https://{domain.rstrip('/')}{url}"
+ else:
+ base = site_url.rstrip("/")
+ return f"{base}{url}"
+
+
+def parse_inspection_result(raw, url):
+ """Extract the fields we care about from the API response."""
+ ir = raw.get("inspectionResult", {})
+
+ # Index status
+ index_result = ir.get("indexStatusResult", {})
+ indexing_state = index_result.get("coverageState", "UNKNOWN")
+ verdict = index_result.get("verdict", "UNKNOWN")
+ last_crawl = index_result.get("lastCrawlTime", None)
+ referring_sitemaps = index_result.get("referringSitemaps", [])
+ crawled_as = index_result.get("crawledAs", None)
+ google_canonical = index_result.get("googleCanonical", None)
+ user_canonical = index_result.get("userDeclaredCanonical", None)
+ page_fetch_state = index_result.get("pageFetchState", None)
+ robots_txt_state = index_result.get("robotsTxtState", None)
+ indexing_state_value = index_result.get("indexingState", None)
+
+ # Mobile usability
+ mobile_result = ir.get("mobileUsabilityResult", {})
+ mobile_verdict = mobile_result.get("verdict", "VERDICT_UNSPECIFIED")
+ mobile_issues = [
+ issue.get("issueType", "UNKNOWN")
+ for issue in mobile_result.get("issues", [])
+ ]
+
+ # Rich results
+ rich_result = ir.get("richResultsResult", {})
+ rich_verdict = rich_result.get("verdict", "VERDICT_UNSPECIFIED")
+ rich_items = []
+ for item in rich_result.get("detectedItems", []):
+ for ri in item.get("items", []):
+ item_entry = {
+ "name": ri.get("name", ""),
+ "issues": [i.get("issueMessage", "") for i in ri.get("issues", [])]
+ }
+ rich_items.append(item_entry)
+
+ return {
+ "url": url,
+ "index_status": {
+ "verdict": verdict,
+ "coverage_state": indexing_state,
+ "last_crawl_time": last_crawl,
+ "crawled_as": crawled_as,
+ "indexing_state": indexing_state_value,
+ "page_fetch_state": page_fetch_state,
+ "robots_txt_state": robots_txt_state,
+ "referring_sitemaps": referring_sitemaps,
+ "google_canonical": google_canonical,
+ "user_declared_canonical": user_canonical,
+ },
+ "mobile_usability": {
+ "verdict": mobile_verdict,
+ "issues": mobile_issues
+ },
+ "rich_results": {
+ "verdict": rich_verdict,
+ "detected_items": rich_items
+ }
+ }
+
+
+def summarize_findings(results):
+ """Produce a high-level summary flags for easy parsing by the skill."""
+ not_indexed = [r for r in results if r.get("index_status", {}).get("verdict") not in ("PASS", "NEUTRAL", "VERDICT_UNSPECIFIED")]
+ mobile_issues = [r for r in results if r.get("mobile_usability", {}).get("verdict") not in ("MOBILE_FRIENDLY", "VERDICT_UNSPECIFIED")]
+ rich_errors = [r for r in results if r.get("rich_results", {}).get("verdict") == "FAIL"]
+ no_sitemaps = [r for r in results if not r.get("index_status", {}).get("referring_sitemaps")]
+
+ import datetime
+ stale_crawl = []
+ for r in results:
+ lc = r.get("index_status", {}).get("last_crawl_time")
+ if lc:
+ try:
+ crawl_dt = datetime.datetime.fromisoformat(lc.replace("Z", "+00:00"))
+ now = datetime.datetime.now(datetime.timezone.utc)
+ days_since = (now - crawl_dt).days
+ if days_since > 60:
+ stale_crawl.append({
+ "url": r["url"],
+ "last_crawl_time": lc,
+ "days_since_crawl": days_since
+ })
+ except (ValueError, TypeError):
+ pass
+
+ return {
+ "total_urls_inspected": len(results),
+ "not_indexed_count": len(not_indexed),
+ "mobile_issues_count": len(mobile_issues),
+ "rich_result_errors_count": len(rich_errors),
+ "no_sitemap_count": len(no_sitemaps),
+ "stale_crawl_count": len(stale_crawl),
+ "not_indexed_urls": [r["url"] for r in not_indexed],
+ "mobile_issue_urls": [r["url"] for r in mobile_issues],
+ "rich_error_urls": [r["url"] for r in rich_errors],
+ "stale_crawl_urls": stale_crawl
+ }
+
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="Run GSC URL Inspection API on a list of URLs."
+ )
+ parser.add_argument("--site", required=True,
+ help="GSC property (sc-domain:example.com or https://example.com/)")
+ parser.add_argument("--urls",
+ help="Comma-separated list of URLs to inspect")
+ parser.add_argument("--urls-file",
+ help="File with one URL per line")
+ parser.add_argument("--max-urls", type=int, default=5,
+ help="Maximum number of URLs to inspect (API limit: 2000/day). Default: 5")
+ _default_out = os.path.join(tempfile.gettempdir(),
+ f"url_inspection_{os.getuid()}.json")
+ parser.add_argument("--output", default=_default_out,
+ help="Output JSON file path")
+ parser.add_argument("--delay", type=float, default=0.1,
+ help="Seconds between concurrent API calls to avoid rate limiting. Default: 0.1")
+ parser.add_argument("--concurrency", type=int, default=3,
+ help="Number of concurrent URL inspections. Default: 3")
+ args = parser.parse_args()
+
+ # Collect URLs
+ urls = []
+ if args.urls:
+ urls.extend([u.strip() for u in args.urls.split(",") if u.strip()])
+ if args.urls_file:
+ with open(args.urls_file) as f:
+ urls.extend([line.strip() for line in f if line.strip()])
+
+ if not urls:
+ print("ERROR: Provide --urls or --urls-file", file=sys.stderr)
+ sys.exit(1)
+
+ # Deduplicate and cap
+ seen = set()
+ deduped = []
+ for u in urls:
+ if u not in seen:
+ seen.add(u)
+ deduped.append(u)
+ urls = deduped[:args.max_urls]
+
+ if len(deduped) > args.max_urls:
+ print(f"Note: Capped at {args.max_urls} URLs (had {len(deduped)}). "
+ f"Pass --max-urls N to inspect more.", file=sys.stderr)
+
+ print(f"Inspecting {len(urls)} URLs for site: {args.site} "
+ f"(concurrency={args.concurrency})", file=sys.stderr)
+
+ token = get_access_token()
+
+ # Normalize all URLs upfront
+ absolute_urls = [normalize_site_url_for_inspection(args.site, u) for u in urls]
+
+ results = []
+ errors = []
+ abort_403 = False
+
+ def _inspect_one(absolute_url):
+ time.sleep(args.delay) # small stagger to avoid thundering herd
+ return absolute_url, inspect_url(token, args.site, absolute_url)
+
+ with ThreadPoolExecutor(max_workers=args.concurrency) as pool:
+ futures = {pool.submit(_inspect_one, url): url for url in absolute_urls}
+ for future in as_completed(futures):
+ try:
+ absolute_url, (raw, error) = future.result()
+ except Exception as exc:
+ absolute_url = futures[future]
+ print(f" ERROR [{absolute_url}]: unexpected error: {exc}", file=sys.stderr)
+ errors.append({"url": absolute_url, "error": str(exc)})
+ continue
+ if error:
+ print(f" ERROR [{absolute_url}]: {error[:80]}", file=sys.stderr)
+ errors.append({"url": absolute_url, "error": error})
+ if "403" in str(error):
+ abort_403 = True
+ else:
+ parsed = parse_inspection_result(raw, absolute_url)
+ results.append(parsed)
+ verdict = parsed["index_status"]["verdict"]
+ mobile = parsed["mobile_usability"]["verdict"]
+ print(f" ✓ {absolute_url} — Index: {verdict} | Mobile: {mobile}",
+ file=sys.stderr)
+
+ if abort_403:
+ print("\nOne or more 403 errors — URL Inspection requires 'webmasters' scope.",
+ file=sys.stderr)
+ print("Re-authenticate with the broader scope and retry:", file=sys.stderr)
+ print(" gcloud auth application-default login \\", file=sys.stderr)
+ print(" --scopes=https://www.googleapis.com/auth/webmasters,"
+ "https://www.googleapis.com/auth/webmasters.readonly", file=sys.stderr)
+
+ summary = summarize_findings(results)
+
+ output = {
+ "site": args.site,
+ "inspected_at": __import__("datetime").datetime.utcnow().isoformat() + "Z",
+ "summary": summary,
+ "results": results,
+ "errors": errors
+ }
+
+ with open(args.output, "w") as f:
+ json.dump(output, f, indent=2)
+
+ print(f"\nDone. Results saved to {args.output}", file=sys.stderr)
+ print(f"Summary: {summary['total_urls_inspected']} inspected | "
+ f"{summary['not_indexed_count']} not indexed | "
+ f"{summary['mobile_issues_count']} mobile issues | "
+ f"{summary['rich_result_errors_count']} rich result errors | "
+ f"{summary['stale_crawl_count']} stale crawl",
+ file=sys.stderr)
+
+ if errors:
+ print(f"\n{len(errors)} URL(s) failed inspection:", file=sys.stderr)
+ for e in errors:
+ print(f" {e['url']}: {e['error'][:100]}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/seo/setup-cms/SKILL.md b/seo/setup-cms/SKILL.md
new file mode 100644
index 00000000..3079b942
--- /dev/null
+++ b/seo/setup-cms/SKILL.md
@@ -0,0 +1,302 @@
+---
+name: setup-cms
+description: >
+ Connect a CMS to toprank SEO tools. Guides users through configuring
+ WordPress, Strapi, Contentful, or Ghost — tests the connection, and writes
+ credentials to .env.local. Once set up, seo-analysis automatically cross-
+ references CMS content against Google Search Console data. Use whenever the
+ user says "connect my CMS", "set up WordPress", "configure Strapi", "add
+ Contentful", "connect Ghost", or "CMS setup". Also trigger if the user asks
+ why no CMS data appears in a seo-analysis report.
+allowed-tools:
+ - Bash
+ - Read
+ - Write
+ - AskUserQuestion
+---
+
+# /setup-cms
+
+Guide the user through connecting their CMS to toprank's SEO analysis tools.
+
+Once configured, `/seo-analysis` automatically pulls published content from
+the CMS and cross-references it against Google Search Console data — finding
+invisible pages, content gaps, stale articles, and missing SEO fields.
+
+---
+
+## Preamble (run first)
+
+```bash
+_UPD=$(~/.claude/skills/toprank/bin/toprank-update-check 2>/dev/null || \
+ ~/.claude/skills/stockholm/bin/toprank-update-check 2>/dev/null || true)
+[ -n "$_UPD" ] && echo "$_UPD" || true
+```
+
+If the output contains `UPGRADE_AVAILABLE <old> <new>`: follow the inline
+upgrade flow in `/toprank-upgrade`, then return here and continue.
+
+---
+
+## Step 1 — Detect existing CMS configuration
+
+```bash
+SKILL_SCRIPTS=$(find ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
+CMS_TYPE=$(python3 "$SKILL_SCRIPTS/cms_detect.py" 2>/dev/null)
+CMS_STATUS=$?
+echo "CMS_TYPE=$CMS_TYPE EXIT=$CMS_STATUS"
+```
+
+- `CMS_STATUS=0` → a CMS is already configured (`$CMS_TYPE` is the name).
+ Show the user: "You already have **[$CMS_TYPE]** connected. Would you like to
+ reconfigure it, or switch to a different CMS?"
+ Wait for their reply. If they say reconfigure/switch, continue to Step 2.
+ If they say test or verify, jump to Step 5 (skip to connection test).
+
+- `CMS_STATUS=2` → nothing configured yet. Continue to Step 2.
+
+---
+
+## Step 2 — Choose a CMS
+
+Ask the user:
+
+> "Which CMS are you connecting? I support:
+>
+> 1. **WordPress** — self-hosted or WordPress.com (uses REST API + Application Password)
+> 2. **Strapi** — v4 or v5, self-hosted (uses API Token)
+> 3. **Contentful** — cloud headless CMS (uses Delivery API key)
+> 4. **Ghost** — Ghost.org or self-hosted (uses Content API key)
+>
+> Reply with the name or number."
+
+Wait for their answer. Map to: `wordpress`, `strapi`, `contentful`, `ghost`.
+
+---
+
+## Step 3 — Credential setup by CMS
+
+Jump to the sub-section for the chosen CMS.
+
+---
+
+### 3A — WordPress
+
+WordPress uses the built-in **Application Passwords** feature (introduced in WP 5.6).
+This is the safest way to grant API access — it never exposes your main password
+and can be revoked at any time.
+
+Tell the user:
+
+> "I need three things to connect WordPress:
+>
+> 1. **Your WordPress URL** (e.g. `https://myblog.com`)
+> 2. **Your WordPress username** (the one you log in with)
+> 3. **An Application Password** — create one in:
+> WordPress Admin → Users → Profile → scroll to **Application Passwords**
+> → enter a name like "toprank" → click **Add New** → copy the generated password
+>
+> Paste each value when ready."
+
+Collect values one at a time:
+1. Ask for `WP_URL` → validate it starts with `http://` or `https://`
+2. Ask for `WP_USERNAME`
+3. Ask for `WP_APP_PASSWORD`
+4. Ask for `WP_CONTENT_TYPE`:
+ > "What content type should I analyze? Common values: `posts`, `pages`.
+ > Press Enter to use `posts` (default), or enter a custom post type slug."
+
+Once all four are collected, continue to Step 4 (test connection).
+
+Write to `.env.local`:
+```
+WP_URL=<value>
+WP_USERNAME=<value>
+WP_APP_PASSWORD=<value>
+WP_CONTENT_TYPE=<value or posts>
+```
+
+---
+
+### 3B — Strapi
+
+Tell the user:
+
+> "I need two things to connect Strapi:
+>
+> 1. **Your Strapi URL** (e.g. `https://cms.example.com`)
+> 2. **A Full-access API Token** — create one in:
+> Strapi Admin → Settings → Global settings → API Tokens → Create new API Token
+> → Type: **Full access** → copy the token
+>
+> Optionally:
+> - **Content type** — the plural API ID of your content collection (default: `articles`).
+> Find it in: Content-Type Builder → [your type] → API ID (plural)
+> - **Strapi version** — `4` or `5` (auto-detected if omitted)
+>
+> Paste each value when ready."
+
+Collect:
+1. `STRAPI_URL`
+2. `STRAPI_API_KEY`
+3. `STRAPI_CONTENT_TYPE` (optional, default: `articles`)
+4. `STRAPI_VERSION` (optional)
+
+Write to `.env.local`:
+```
+STRAPI_URL=<value>
+STRAPI_API_KEY=<value>
+STRAPI_CONTENT_TYPE=<value or articles>
+```
+Include `STRAPI_VERSION=<value>` only if the user specified it.
+
+---
+
+### 3C — Contentful
+
+Tell the user:
+
+> "I need three things to connect Contentful:
+>
+> 1. **Space ID** — find it in: Contentful → Settings → General Settings → Space ID
+> 2. **Content Delivery API token** — find it in:
+> Settings → API Keys → [your key] → Content Delivery API - access token
+> (If no key exists, create one under Settings → API Keys → Add API Key)
+> 3. **Content type ID** — the API identifier for your content type.
+> Find it in: Content model → [your type] → API Identifier
+>
+> Optionally:
+> - **Environment** (default: `master`)
+>
+> Paste each value when ready."
+
+Collect:
+1. `CONTENTFUL_SPACE_ID`
+2. `CONTENTFUL_DELIVERY_TOKEN`
+3. `CONTENTFUL_CONTENT_TYPE`
+4. `CONTENTFUL_ENVIRONMENT` (optional, default: `master`)
+
+Write to `.env.local`:
+```
+CONTENTFUL_SPACE_ID=<value>
+CONTENTFUL_DELIVERY_TOKEN=<value>
+CONTENTFUL_CONTENT_TYPE=<value>
+CONTENTFUL_ENVIRONMENT=<value or master>
+```
+
+---
+
+### 3D — Ghost
+
+Tell the user:
+
+> "I need two things to connect Ghost:
+>
+> 1. **Your Ghost URL** (e.g. `https://myblog.ghost.io`)
+> 2. **Content API key** — create one in:
+> Ghost Admin → Settings → Integrations → Add custom integration
+> → copy the **Content API Key**
+>
+> Optionally:
+> - **Content type**: `posts` (default) or `pages`
+>
+> Paste each value when ready."
+
+Collect:
+1. `GHOST_URL`
+2. `GHOST_CONTENT_KEY`
+3. `GHOST_CONTENT_TYPE` (optional, default: `posts`)
+
+Write to `.env.local`:
+```
+GHOST_URL=<value>
+GHOST_CONTENT_KEY=<value>
+GHOST_CONTENT_TYPE=<value or posts>
+```
+
+---
+
+## Step 4 — Write .env.local
+
+Find the project's `.env.local` file. Search for it:
+```bash
+ENV_FILE=""
+for candidate in ".env.local" "$HOME/.env.local"; do
+ [ -f "$candidate" ] && ENV_FILE="$candidate" && break
+done
+[ -z "$ENV_FILE" ] && ENV_FILE=".env.local"
+echo "Writing to: $ENV_FILE"
+```
+
+**Merge strategy** — do not overwrite the entire file. For each env var:
+1. If the key already exists in the file, replace that line.
+2. If it does not exist, append it to the end.
+
+Read the file first (if it exists), then update key by key, then write back.
+
+If the file doesn't exist yet, create it.
+
+After writing, confirm:
+> "Credentials written to `[path]`. Testing connection now..."
+
+---
+
+## Step 5 — Test connection
+
+Run the appropriate preflight script and capture the exit code:
+
+```bash
+# WordPress
+python3 "$SKILL_SCRIPTS/preflight_wordpress.py" 2>&1; PREFLIGHT_EXIT=$?
+
+# Strapi
+python3 "$SKILL_SCRIPTS/preflight_strapi.py" 2>&1; PREFLIGHT_EXIT=$?
+
+# Contentful
+python3 "$SKILL_SCRIPTS/preflight_contentful.py" 2>&1; PREFLIGHT_EXIT=$?
+
+# Ghost
+python3 "$SKILL_SCRIPTS/preflight_ghost.py" 2>&1; PREFLIGHT_EXIT=$?
+```
+
+The `2>&1` redirect surfaces error messages in the output so you can show them.
+
+**`PREFLIGHT_EXIT=0`** — connection successful. Show the "OK: …" line to the user,
+then continue to Step 6.
+
+**`PREFLIGHT_EXIT=1`** — connection failed. Show the full error output verbatim.
+Help the user diagnose:
+- `401 Unauthorized` → wrong token/password — suggest regenerating
+- `403 Forbidden` → token lacks permission — suggest a Full Access / unrestricted token
+- `404 Not Found` → wrong URL or wrong content type slug
+- Network error → URL unreachable — check the URL in a browser first
+
+Ask: "Want to fix the credentials and try again (I'll go back to Step 3), or skip CMS setup for now?"
+
+**`PREFLIGHT_EXIT=2`** → credentials were removed from `.env.local` between steps. Restart from Step 3.
+
+---
+
+## Step 6 — Confirm and summarize
+
+Once the connection succeeds, show a summary:
+
+```
+CMS connected successfully!
+
+ CMS: [WordPress/Strapi/Contentful/Ghost]
+ URL: [cms_url]
+ Content type: [content_type]
+ Published: [N] entries found
+
+What this enables in /seo-analysis:
+ • Cross-reference [N] published articles against Google Search Console data
+ • Find published content with zero GSC impressions (unindexed or invisible)
+ • Identify content gaps: queries ranking 11-30 with no matching article
+ • Flag stale content: articles >6 months old with declining clicks
+ • Audit SEO fields: missing meta titles/descriptions, length violations
+```
+
+Then offer:
+> "Run `/seo-analysis` to see a full audit with your CMS content included,
+> or type `/setup-cms` again to connect a different CMS."
diff --git a/setup b/setup
new file mode 100755
index 00000000..4b33611e
--- /dev/null
+++ b/setup
@@ -0,0 +1,507 @@
+#!/usr/bin/env python3
+"""
+toprank setup — register skills with Claude Code, Codex, and/or OpenClaw.
+
+Cross-platform (Windows, macOS, Linux).
+Usage: ./setup [--host claude|codex|openclaw|auto] [--skill NAME] [--api-key KEY]
+"""
+
+import argparse
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import tempfile
+
+TOPRANK_DIR = os.path.dirname(os.path.abspath(__file__))
+TOPRANK_NAME = os.path.basename(TOPRANK_DIR)
+SKILLS_DIR = os.path.dirname(TOPRANK_DIR)
+
+# Subdirectories that contain skills (each subdir may hold multiple skill folders)
+SKILL_CATEGORIES = ["seo", "google-ads"]
+
+
+def parse_args():
+ parser = argparse.ArgumentParser(description="Register toprank skills with your agent")
+ parser.add_argument(
+ "--host",
+ choices=["claude", "codex", "openclaw", "auto"],
+ default="auto",
+ help="Target host (default: auto-detect)",
+ )
+ parser.add_argument(
+ "--skill",
+ default="",
+ help="Only setup a single skill by name",
+ )
+ parser.add_argument(
+ "--api-key",
+ default="",
+ help="API key for MCP server configuration",
+ )
+ return parser.parse_args()
+
+
+def make_bin_executable():
+ bin_dir = os.path.join(TOPRANK_DIR, "bin")
+ if not os.path.isdir(bin_dir):
+ return
+ if platform.system() == "Windows":
+ return # Windows uses file associations, not executable bits
+ for fname in os.listdir(bin_dir):
+ fpath = os.path.join(bin_dir, fname)
+ if os.path.isfile(fpath):
+ try:
+ os.chmod(fpath, os.stat(fpath).st_mode | 0o111)
+ except OSError:
+ pass
+
+
+def discover_skills():
+ """Find all skills and return (name, relative_path) tuples.
+
+ Scans category subdirectories (seo/, google-ads/) and the root for
+ directories containing a SKILL.md file.
+ """
+ skills = []
+
+ # Scan category subdirectories
+ for category in SKILL_CATEGORIES:
+ cat_dir = os.path.join(TOPRANK_DIR, category)
+ if not os.path.isdir(cat_dir):
+ continue
+ for entry in sorted(os.listdir(cat_dir)):
+ skill_dir = os.path.join(cat_dir, entry)
+ if os.path.isdir(skill_dir) and os.path.isfile(os.path.join(skill_dir, "SKILL.md")):
+ rel_path = os.path.join(category, entry)
+ skills.append((entry, rel_path))
+
+ # Scan root level (for toprank-upgrade and any other root-level skills)
+ for entry in sorted(os.listdir(TOPRANK_DIR)):
+ skill_dir = os.path.join(TOPRANK_DIR, entry)
+ if entry in SKILL_CATEGORIES:
+ continue # already scanned
+ if os.path.isdir(skill_dir) and os.path.isfile(os.path.join(skill_dir, "SKILL.md")):
+ skills.append((entry, entry))
+
+ return skills
+
+
+def inject_preamble(skills):
+ preamble_file = os.path.join(TOPRANK_DIR, "bin", "preamble.md")
+ if not os.path.isfile(preamble_file):
+ return []
+
+ with open(preamble_file) as f:
+ preamble = f.read()
+
+ injected = []
+ for skill_name, rel_path in skills:
+ if skill_name in ("toprank-upgrade", "ads"):
+ continue
+ skill_path = os.path.join(TOPRANK_DIR, rel_path, "SKILL.md")
+ if not os.path.isfile(skill_path):
+ continue
+ with open(skill_path) as f:
+ content = f.read()
+ if "toprank-update-check" in content:
+ continue
+
+ parts = content.split("---", 2)
+ if len(parts) < 3:
+ continue
+
+ new_content = parts[0] + "---" + parts[1] + "---\n\n" + preamble + parts[2].lstrip("\n")
+ skill_dir_path = os.path.dirname(skill_path)
+ fd, tmp_path = tempfile.mkstemp(dir=skill_dir_path)
+ try:
+ with os.fdopen(fd, "w") as f:
+ f.write(new_content)
+ os.replace(tmp_path, skill_path)
+ except Exception:
+ try:
+ os.unlink(tmp_path)
+ except OSError:
+ pass
+ raise
+ injected.append(skill_name)
+
+ return injected
+
+
+def _symlink(src, dst):
+ """Create symlink src->dst. Falls back to copy on Windows if symlinks fail."""
+ if os.path.islink(dst):
+ os.unlink(dst)
+
+ try:
+ os.symlink(src, dst)
+ return "symlinked"
+ except (OSError, NotImplementedError):
+ full_src = src if os.path.isabs(src) else os.path.join(SKILLS_DIR, src)
+ if platform.system() == "Windows":
+ result = subprocess.run(
+ ["cmd", "/c", "mklink", "/J", dst, full_src],
+ capture_output=True,
+ )
+ if result.returncode == 0:
+ return "junctioned"
+ # Last resort: copy
+ if os.path.isdir(full_src):
+ shutil.copytree(full_src, dst)
+ else:
+ shutil.copy2(full_src, dst)
+ return "copied"
+
+
+def setup_claude(skills):
+ print("Claude Code:")
+ linked = []
+ for skill_name, rel_path in skills:
+ src = os.path.join(TOPRANK_NAME, rel_path) # relative path for portability
+ dst = os.path.join(SKILLS_DIR, skill_name)
+
+ if os.path.exists(dst) and not os.path.islink(dst):
+ print(f" skipped {skill_name} (real directory exists at {dst})")
+ continue
+
+ method = _symlink(src, dst)
+ linked.append(f"{skill_name} ({method})")
+
+ if linked:
+ print(f" linked skills: {', '.join(linked)}")
+ for skill_name, _ in skills:
+ print(f" -> {os.path.join(SKILLS_DIR, skill_name)}")
+ else:
+ print(" no new skills to link")
+
+
+def setup_codex(skills):
+ print("Codex:")
+ try:
+ result = subprocess.run(
+ ["git", "rev-parse", "--show-toplevel"],
+ capture_output=True, text=True, cwd=TOPRANK_DIR,
+ )
+ repo_root = result.stdout.strip() if result.returncode == 0 else ""
+ except FileNotFoundError:
+ repo_root = ""
+
+ agents_dir = (
+ os.path.join(repo_root, ".agents", "skills")
+ if repo_root
+ else os.path.join(os.path.expanduser("~"), ".codex", "skills")
+ )
+
+ linked = []
+ for skill_name, rel_path in skills:
+ codex_skill_name = f"toprank-{skill_name}"
+ codex_dir = os.path.join(agents_dir, codex_skill_name)
+ os.makedirs(os.path.join(codex_dir, "agents"), exist_ok=True)
+
+ # Read description from frontmatter
+ skill_md = os.path.join(TOPRANK_DIR, rel_path, "SKILL.md")
+ desc = f"Toprank {skill_name} skill"
+ if os.path.isfile(skill_md):
+ with open(skill_md) as f:
+ content = f.read()
+ in_desc = False
+ desc_lines = []
+ for line in content.splitlines():
+ if line.startswith("description:"):
+ rest = line[len("description:"):].strip()
+ if rest and rest != ">":
+ desc = rest[:120]
+ break
+ in_desc = True
+ elif in_desc:
+ if line.startswith("---") or (line and not line.startswith(" ")):
+ break
+ desc_lines.append(line.strip())
+ if desc_lines:
+ desc = " ".join(desc_lines)[:120]
+
+ yaml_path = os.path.join(codex_dir, "agents", "openai.yaml")
+ with open(yaml_path, "w") as f:
+ f.write(f"""interface:
+ display_name: "toprank-{skill_name}"
+ short_description: "{desc}"
+ default_prompt: "Use toprank-{skill_name} for this task."
+policy:
+ allow_implicit_invocation: true
+""")
+
+ # Copy SKILL.md and asset directories (not symlink — Codex rejects external symlinks)
+ for asset in ["SKILL.md", "scripts", "references"]:
+ asset_src = os.path.join(TOPRANK_DIR, rel_path, asset)
+ asset_dst = os.path.join(codex_dir, asset)
+ if not os.path.exists(asset_src):
+ continue
+ if os.path.islink(asset_dst):
+ os.unlink(asset_dst)
+ if os.path.isdir(asset_src):
+ if os.path.exists(asset_dst):
+ shutil.rmtree(asset_dst)
+ shutil.copytree(asset_src, asset_dst)
+ else:
+ shutil.copy2(asset_src, asset_dst)
+
+ linked.append(codex_skill_name)
+
+ if linked:
+ print(f" linked skills: {', '.join(linked)}")
+ for codex_skill_name in linked:
+ print(f" -> {os.path.join(agents_dir, codex_skill_name)}")
+ else:
+ print(" no new skills to link")
+
+
+def setup_openclaw(skills):
+ """OpenClaw rejects symlinks that resolve outside the skills root, so we copy."""
+ print("OpenClaw:")
+ openclaw_skills = os.path.join(os.path.expanduser("~"), ".openclaw", "workspace", "skills")
+ os.makedirs(openclaw_skills, exist_ok=True)
+
+ installed = []
+ for skill_name, rel_path in skills:
+ src = os.path.join(TOPRANK_DIR, rel_path)
+ dst = os.path.join(openclaw_skills, skill_name)
+ if os.path.islink(dst):
+ os.unlink(dst)
+ os.makedirs(dst, exist_ok=True)
+ for entry in os.listdir(src):
+ s = os.path.join(src, entry)
+ d = os.path.join(dst, entry)
+ if os.path.isdir(s):
+ if os.path.exists(d):
+ shutil.rmtree(d)
+ shutil.copytree(s, d)
+ else:
+ shutil.copy2(s, d)
+ installed.append(skill_name)
+
+ if installed:
+ print(f" installed skills: {', '.join(installed)}")
+ for skill_name in installed:
+ print(f" -> {os.path.join(openclaw_skills, skill_name)}")
+ else:
+ print(" no new skills to install")
+
+
+def detect_hosts(host_arg):
+ install_claude = False
+ install_codex = False
+ install_openclaw = False
+
+ if host_arg == "claude":
+ install_claude = True
+ elif host_arg == "codex":
+ install_codex = True
+ elif host_arg == "openclaw":
+ install_openclaw = True
+ else:
+ claude_skills = os.path.join(".claude", "skills")
+ if SKILLS_DIR.endswith(claude_skills) or SKILLS_DIR.replace("\\", "/").endswith(claude_skills):
+ install_claude = True
+ if shutil.which("codex"):
+ install_codex = True
+ openclaw_skills = os.path.join(".openclaw", "workspace", "skills")
+ if SKILLS_DIR.endswith(openclaw_skills) or SKILLS_DIR.replace("\\", "/").endswith(openclaw_skills):
+ install_openclaw = True
+ if shutil.which("openclaw"):
+ install_openclaw = True
+ if not install_claude and not install_codex and not install_openclaw:
+ install_claude = True
+
+ return install_claude, install_codex, install_openclaw
+
+
+def _replace_key(obj, key):
+ """Recursively replace ${ADS_AGENT_KEY} placeholders with the actual key."""
+ if isinstance(obj, str):
+ return obj.replace("${ADS_AGENT_KEY}", key)
+ if isinstance(obj, list):
+ return [_replace_key(v, key) for v in obj]
+ if isinstance(obj, dict):
+ return {k: _replace_key(v, key) for k, v in obj.items()}
+ return obj
+
+
+def setup_mcp(skills, api_key):
+ """Configure MCP servers in Claude Desktop settings."""
+ for skill_name, rel_path in skills:
+ mcporter_path = os.path.join(TOPRANK_DIR, rel_path, "mcporter.json")
+ if not os.path.isfile(mcporter_path):
+ continue
+
+ key = api_key
+ if not key:
+ config_path = os.path.join(os.path.expanduser("~"), ".adsagent", "config.json")
+ if os.path.isfile(config_path):
+ try:
+ with open(config_path) as f:
+ key = json.load(f).get("apiKey", "")
+ except Exception:
+ pass
+ if not key:
+ continue
+
+ with open(mcporter_path) as f:
+ mcporter = json.load(f)
+
+ new_servers = mcporter.get("mcpServers", {})
+ if not new_servers:
+ continue
+
+ new_servers = _replace_key(new_servers, key)
+
+ print("MCP servers:")
+ configs_written = []
+
+ system = platform.system()
+ if system == "Darwin":
+ desktop_config = os.path.join(
+ os.path.expanduser("~"), "Library", "Application Support", "Claude", "claude_desktop_config.json"
+ )
+ elif system == "Linux":
+ desktop_config = os.path.join(
+ os.path.expanduser("~"), ".config", "Claude", "claude_desktop_config.json"
+ )
+ elif system == "Windows":
+ desktop_config = os.path.join(os.environ.get("APPDATA", ""), "Claude", "claude_desktop_config.json")
+ else:
+ desktop_config = ""
+
+ if desktop_config:
+ os.makedirs(os.path.dirname(desktop_config), exist_ok=True)
+ config = {}
+ if os.path.isfile(desktop_config):
+ with open(desktop_config) as f:
+ config = json.load(f)
+ config.setdefault("mcpServers", {}).update(new_servers)
+ with open(desktop_config, "w") as f:
+ json.dump(config, f, indent=2)
+ configs_written.append("Claude Desktop")
+
+ if configs_written:
+ print(f" configured: {', '.join(configs_written)}")
+ for name in new_servers:
+ print(f" + {name}")
+
+
+def prompt_google_ads_setup(skills):
+ """Interactively set up Google Ads if the user wants it and stdin is a TTY."""
+ # Check if any skill has a mcporter.json (i.e., needs MCP config)
+ has_ads = any(
+ os.path.isfile(os.path.join(TOPRANK_DIR, rel_path, "mcporter.json"))
+ for _, rel_path in skills
+ )
+ if not has_ads:
+ return ""
+
+ # Check if API key already exists
+ config_path = os.path.join(os.path.expanduser("~"), ".adsagent", "config.json")
+ if os.path.isfile(config_path):
+ try:
+ with open(config_path) as f:
+ existing_key = json.load(f).get("apiKey", "")
+ if existing_key:
+ return existing_key # Already configured
+ except Exception:
+ pass
+
+ # Only prompt if stdin is a TTY (skip for piped installs)
+ # TOPRANK_FORCE_INTERACTIVE=1 overrides the TTY check (for testing)
+ if not sys.stdin.isatty() and not os.environ.get("TOPRANK_FORCE_INTERACTIVE"):
+ return ""
+
+ print()
+ try:
+ use_ads = input("Do you use Google Ads? (y/n): ").strip().lower()
+ except (EOFError, KeyboardInterrupt):
+ print()
+ return ""
+
+ if use_ads not in ("y", "yes"):
+ return ""
+
+ print()
+ print(" Get your free API key at: https://www.adsagent.org")
+ print()
+ try:
+ api_key = input(" Paste your API key: ").strip()
+ except (EOFError, KeyboardInterrupt):
+ print()
+ return ""
+
+ if not api_key:
+ return ""
+
+ # Save the key
+ config_dir = os.path.join(os.path.expanduser("~"), ".adsagent")
+ os.makedirs(config_dir, exist_ok=True)
+ with open(os.path.join(config_dir, "config.json"), "w") as f:
+ json.dump({"apiKey": api_key}, f)
+ print(" saved to ~/.adsagent/config.json")
+
+ return api_key
+
+
+def main():
+ args = parse_args()
+
+ print("toprank setup")
+ print("─────────────")
+ print()
+
+ make_bin_executable()
+
+ skills = discover_skills()
+ if not skills:
+ print(" no skills found")
+ return
+
+ if args.skill:
+ match = [(name, rel) for name, rel in skills if name == args.skill]
+ if not match:
+ print(f" skill '{args.skill}' not found", file=sys.stderr)
+ sys.exit(1)
+ skills = match
+
+ injected = inject_preamble(skills)
+ if injected:
+ print(f" injected preamble: {' '.join(injected)}")
+
+ install_claude, install_codex, install_openclaw = detect_hosts(args.host)
+
+ if install_claude:
+ setup_claude(skills)
+ if install_codex:
+ setup_codex(skills)
+ if install_openclaw:
+ setup_openclaw(skills)
+
+ # Google Ads API key: use --api-key flag, or prompt interactively
+ api_key = args.api_key
+ if api_key:
+ config_dir = os.path.join(os.path.expanduser("~"), ".adsagent")
+ os.makedirs(config_dir, exist_ok=True)
+ with open(os.path.join(config_dir, "config.json"), "w") as f:
+ json.dump({"apiKey": api_key}, f)
+ print(" wrote ~/.adsagent/config.json")
+ else:
+ api_key = prompt_google_ads_setup(skills)
+
+ setup_mcp(skills, api_key)
+
+ seo_count = sum(1 for _, rel in skills if rel.startswith("seo/"))
+ ads_count = sum(1 for _, rel in skills if rel.startswith("google-ads/"))
+ print()
+ print(f"Done. {seo_count} SEO skills and {ads_count} Google Ads skill(s) installed.")
+ print(" Try: /seo-analysis or /ads")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/test/fixtures/mock-analyze-gsc.py b/test/fixtures/mock-analyze-gsc.py
new file mode 100644
index 00000000..668f80a5
--- /dev/null
+++ b/test/fixtures/mock-analyze-gsc.py
@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""
+Mock analyze_gsc.py for E2E tests.
+
+Reads sample_gsc_data.json from the test fixtures directory instead of
+calling the real GSC API. Used to test the full skill workflow without
+needing real Google credentials.
+
+Usage (same interface as real script):
+ python3 mock-analyze-gsc.py --site "sc-domain:example-saas.com" --days 90
+"""
+
+import argparse
+import json
+import os
+import shutil
+import sys
+
+FIXTURE_PATH = os.path.join(os.path.dirname(__file__), 'sample_gsc_data.json')
+
+
+def main():
+ parser = argparse.ArgumentParser()
+ parser.add_argument('--site', required=True)
+ parser.add_argument('--days', type=int, default=90)
+ parser.add_argument('--output', default='/tmp/gsc_analysis.json')
+ args = parser.parse_args()
+
+ print(f'[mock] Loading fixture data for: {args.site}', file=sys.stderr)
+ print(f'[mock] (No real GSC call — using test fixture)', file=sys.stderr)
+
+ with open(FIXTURE_PATH) as f:
+ data = json.load(f)
+
+ # Override site in fixture to match requested site
+ data['site'] = args.site
+ data['period']['days'] = args.days
+
+ with open(args.output, 'w') as f:
+ json.dump(data, f, indent=2)
+
+ summary = data['summary']
+ print(f'\nDone. Results saved to {args.output}', file=sys.stderr)
+ print(
+ f'\nSummary: {summary["clicks"]:,} clicks | {summary["impressions"]:,} impressions | '
+ f'CTR {summary["ctr"]}% | Avg position {summary["position"]}',
+ file=sys.stderr,
+ )
+
+
+if __name__ == '__main__':
+ main()
diff --git a/test/fixtures/mock-gcloud.sh b/test/fixtures/mock-gcloud.sh
new file mode 100755
index 00000000..dc4faea1
--- /dev/null
+++ b/test/fixtures/mock-gcloud.sh
@@ -0,0 +1,13 @@
+#!/bin/bash
+# Mock gcloud binary for E2E tests.
+# Returns a fake access token when called with auth credentials subcommands.
+# All other subcommands are passed through to the real gcloud (if available).
+
+if [[ "$*" == *"application-default print-access-token"* ]]; then
+ echo "ya29.mock-token-for-testing-only"
+ exit 0
+fi
+
+# Unknown subcommands: exit cleanly (don't fall through — mock is first in PATH
+# so `command -v gcloud` would resolve back to this script causing infinite recursion)
+exit 0
diff --git a/test/fixtures/sample_gsc_data.json b/test/fixtures/sample_gsc_data.json
new file mode 100644
index 00000000..05bdfb30
--- /dev/null
+++ b/test/fixtures/sample_gsc_data.json
@@ -0,0 +1,125 @@
+{
+ "site": "sc-domain:example-saas.com",
+ "period": {
+ "start": "2025-12-17",
+ "end": "2026-03-17",
+ "days": 90
+ },
+ "summary": {
+ "clicks": 14823,
+ "impressions": 389400,
+ "ctr": 3.81,
+ "position": 18.4
+ },
+ "top_queries": [
+ { "query": "project management software", "clicks": 1240, "impressions": 9800, "ctr": 12.65, "position": 2.1 },
+ { "query": "team collaboration tools", "clicks": 890, "impressions": 7200, "ctr": 12.36, "position": 2.4 },
+ { "query": "task management app", "clicks": 780, "impressions": 6100, "ctr": 12.79, "position": 2.8 },
+ { "query": "project management tool free", "clicks": 420, "impressions": 8900, "ctr": 4.72, "position": 5.2 },
+ { "query": "best project management software 2025", "clicks": 380, "impressions": 12400, "ctr": 3.06, "position": 6.8 },
+ { "query": "agile project management", "clicks": 360, "impressions": 5800, "ctr": 6.21, "position": 4.1 },
+ { "query": "project management software for small teams", "clicks": 310, "impressions": 7600, "ctr": 4.08, "position": 5.9 },
+ { "query": "kanban board software", "clicks": 290, "impressions": 4200, "ctr": 6.90, "position": 3.8 },
+ { "query": "project tracking software", "clicks": 260, "impressions": 9100, "ctr": 2.86, "position": 7.3 },
+ { "query": "project management software pricing", "clicks": 240, "impressions": 6300, "ctr": 3.81, "position": 6.1 },
+ { "query": "asana alternative", "clicks": 220, "impressions": 4800, "ctr": 4.58, "position": 8.4 },
+ { "query": "jira alternative", "clicks": 210, "impressions": 5100, "ctr": 4.12, "position": 7.9 },
+ { "query": "monday.com alternative", "clicks": 190, "impressions": 4400, "ctr": 4.32, "position": 8.1 },
+ { "query": "team task management", "clicks": 180, "impressions": 3900, "ctr": 4.62, "position": 9.2 },
+ { "query": "project management gantt chart", "clicks": 170, "impressions": 6800, "ctr": 2.50, "position": 11.4 },
+ { "query": "remote team project management", "clicks": 160, "impressions": 5200, "ctr": 3.08, "position": 12.1 },
+ { "query": "project management software review", "clicks": 150, "impressions": 8700, "ctr": 1.72, "position": 14.2 },
+ { "query": "online project management", "clicks": 140, "impressions": 7400, "ctr": 1.89, "position": 13.8 },
+ { "query": "simple project management tool", "clicks": 130, "impressions": 5900, "ctr": 2.20, "position": 15.6 },
+ { "query": "project management app for startups", "clicks": 120, "impressions": 4100, "ctr": 2.93, "position": 16.9 }
+ ],
+ "top_pages": [
+ { "page": "https://example-saas.com/", "clicks": 3240, "impressions": 28400, "ctr": 11.41, "position": 2.8 },
+ { "page": "https://example-saas.com/features", "clicks": 2180, "impressions": 19600, "ctr": 11.12, "position": 3.1 },
+ { "page": "https://example-saas.com/pricing", "clicks": 1890, "impressions": 18200, "ctr": 10.38, "position": 4.2 },
+ { "page": "https://example-saas.com/blog/project-management-tips", "clicks": 980, "impressions": 31400, "ctr": 3.12, "position": 8.4 },
+ { "page": "https://example-saas.com/alternatives/asana", "clicks": 760, "impressions": 12800, "ctr": 5.94, "position": 5.6 },
+ { "page": "https://example-saas.com/blog/agile-vs-waterfall", "clicks": 680, "impressions": 24100, "ctr": 2.82, "position": 9.7 },
+ { "page": "https://example-saas.com/templates", "clicks": 540, "impressions": 16300, "ctr": 3.31, "position": 11.2 },
+ { "page": "https://example-saas.com/integrations", "clicks": 420, "impressions": 9800, "ctr": 4.29, "position": 7.8 },
+ { "page": "https://example-saas.com/blog/remote-team-management", "clicks": 380, "impressions": 19400, "ctr": 1.96, "position": 13.1 },
+ { "page": "https://example-saas.com/enterprise", "clicks": 320, "impressions": 7100, "ctr": 4.51, "position": 6.4 }
+ ],
+ "position_buckets": {
+ "1-3": [
+ { "query": "project management software", "clicks": 1240, "impressions": 9800, "ctr": 12.65, "position": 2.1 },
+ { "query": "team collaboration tools", "clicks": 890, "impressions": 7200, "ctr": 12.36, "position": 2.4 },
+ { "query": "task management app", "clicks": 780, "impressions": 6100, "ctr": 12.79, "position": 2.8 },
+ { "query": "kanban board software", "clicks": 290, "impressions": 4200, "ctr": 6.90, "position": 3.8 }
+ ],
+ "4-10": [
+ { "query": "project management tool free", "clicks": 420, "impressions": 8900, "ctr": 4.72, "position": 5.2 },
+ { "query": "best project management software 2025", "clicks": 380, "impressions": 12400, "ctr": 3.06, "position": 6.8 },
+ { "query": "agile project management", "clicks": 360, "impressions": 5800, "ctr": 6.21, "position": 4.1 },
+ { "query": "project management software for small teams", "clicks": 310, "impressions": 7600, "ctr": 4.08, "position": 5.9 },
+ { "query": "project tracking software", "clicks": 260, "impressions": 9100, "ctr": 2.86, "position": 7.3 },
+ { "query": "project management software pricing", "clicks": 240, "impressions": 6300, "ctr": 3.81, "position": 6.1 },
+ { "query": "asana alternative", "clicks": 220, "impressions": 4800, "ctr": 4.58, "position": 8.4 },
+ { "query": "jira alternative", "clicks": 210, "impressions": 5100, "ctr": 4.12, "position": 7.9 },
+ { "query": "monday.com alternative", "clicks": 190, "impressions": 4400, "ctr": 4.32, "position": 8.1 },
+ { "query": "team task management", "clicks": 180, "impressions": 3900, "ctr": 4.62, "position": 9.2 }
+ ],
+ "11-20": [
+ { "query": "project management gantt chart", "clicks": 170, "impressions": 6800, "ctr": 2.50, "position": 11.4 },
+ { "query": "remote team project management", "clicks": 160, "impressions": 5200, "ctr": 3.08, "position": 12.1 },
+ { "query": "project management software review", "clicks": 150, "impressions": 8700, "ctr": 1.72, "position": 14.2 },
+ { "query": "online project management", "clicks": 140, "impressions": 7400, "ctr": 1.89, "position": 13.8 }
+ ],
+ "21+": [
+ { "query": "project management certification", "clicks": 80, "impressions": 12400, "ctr": 0.65, "position": 24.1 },
+ { "query": "project management methodology", "clicks": 70, "impressions": 9800, "ctr": 0.71, "position": 27.3 }
+ ]
+ },
+ "ctr_opportunities": [
+ { "query": "best project management software 2025", "clicks": 380, "impressions": 12400, "ctr": 3.06, "position": 6.8 },
+ { "query": "project tracking software", "clicks": 260, "impressions": 9100, "ctr": 2.86, "position": 7.3 },
+ { "query": "project management software review", "clicks": 150, "impressions": 8700, "ctr": 1.72, "position": 14.2 },
+ { "query": "project management tool free", "clicks": 420, "impressions": 8900, "ctr": 4.72, "position": 5.2 },
+ { "query": "online project management", "clicks": 140, "impressions": 7400, "ctr": 1.89, "position": 13.8 },
+ { "query": "project management software for small teams", "clicks": 310, "impressions": 7600, "ctr": 4.08, "position": 5.9 },
+ { "query": "project management gantt chart", "clicks": 170, "impressions": 6800, "ctr": 2.50, "position": 11.4 },
+ { "query": "project management software pricing", "clicks": 240, "impressions": 6300, "ctr": 3.81, "position": 6.1 }
+ ],
+ "comparison": {
+ "period": "2026-02-17 to 2026-03-17",
+ "prior_period": "2026-01-20 to 2026-02-16",
+ "declining_pages": [
+ {
+ "page": "https://example-saas.com/blog/agile-vs-waterfall",
+ "clicks_now": 420,
+ "clicks_prev": 680,
+ "change_pct": -38.2
+ },
+ {
+ "page": "https://example-saas.com/templates",
+ "clicks_now": 310,
+ "clicks_prev": 540,
+ "change_pct": -42.6
+ }
+ ],
+ "declining_queries": [
+ {
+ "query": "agile vs waterfall",
+ "clicks_now": 180,
+ "clicks_prev": 390,
+ "change_pct": -53.8
+ },
+ {
+ "query": "project management templates",
+ "clicks_now": 95,
+ "clicks_prev": 210,
+ "change_pct": -54.8
+ }
+ ]
+ },
+ "device_split": [
+ { "device": "DESKTOP", "clicks": 9840, "impressions": 218600 },
+ { "device": "MOBILE", "clicks": 4280, "impressions": 152300 },
+ { "device": "TABLET", "clicks": 703, "impressions": 18500 }
+ ]
+}
diff --git a/test/helpers/__init__.py b/test/helpers/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/test/helpers/eval_store.py b/test/helpers/eval_store.py
new file mode 100644
index 00000000..3ec06b60
--- /dev/null
+++ b/test/helpers/eval_store.py
@@ -0,0 +1,134 @@
+"""
+Eval result persistence for toprank tests.
+
+Accumulates test results, writes them to ~/.toprank-evals/, prints a summary table.
+"""
+
+import atexit
+import json
+import subprocess
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+EVAL_DIR = Path.home() / '.toprank-evals'
+
+
+@dataclass
+class EvalTestEntry:
+ name: str
+ suite: str
+ tier: str # 'e2e', 'llm-judge', 'routing'
+ passed: bool
+ duration_ms: int
+ cost_usd: float
+
+ # E2E
+ output: Optional[str] = None
+ turns_used: Optional[int] = None
+
+ # LLM judge
+ judge_scores: Optional[dict[str, float]] = None
+ judge_reasoning: Optional[str] = None
+
+ # Routing
+ should_trigger: Optional[bool] = None
+ did_trigger: Optional[bool] = None
+
+ # Diagnostics
+ exit_reason: Optional[str] = None
+ model: Optional[str] = None
+ error: Optional[str] = None
+
+
+def _git_info() -> tuple[str, str]:
+ try:
+ branch = subprocess.run(
+ ['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
+ capture_output=True, text=True, timeout=3,
+ ).stdout.strip() or 'unknown'
+ sha = subprocess.run(
+ ['git', 'rev-parse', '--short', 'HEAD'],
+ capture_output=True, text=True, timeout=3,
+ ).stdout.strip() or 'unknown'
+ return branch, sha
+ except Exception:
+ return 'unknown', 'unknown'
+
+
+def _version() -> str:
+ version_file = Path(__file__).parent.parent.parent / 'VERSION'
+ try:
+ return version_file.read_text().strip()
+ except Exception:
+ return 'unknown'
+
+
+class EvalCollector:
+ def __init__(self, tier: str):
+ self.tier = tier
+ self.tests: list[EvalTestEntry] = []
+ self._finalized = False
+ # Register finalize() so results are persisted even on process crash.
+ atexit.register(self.finalize)
+
+ def add_test(self, entry: EvalTestEntry) -> None:
+ self.tests.append(entry)
+
+ def finalize(self) -> str:
+ if self._finalized:
+ return ''
+ self._finalized = True
+
+ branch, sha = _git_info()
+ version = _version()
+ timestamp = datetime.now(timezone.utc).isoformat()
+ passed = sum(1 for t in self.tests if t.passed)
+ total_cost = sum(t.cost_usd for t in self.tests)
+ total_duration = sum(t.duration_ms for t in self.tests)
+
+ result = {
+ 'version': version,
+ 'branch': branch,
+ 'git_sha': sha,
+ 'timestamp': timestamp,
+ 'tier': self.tier,
+ 'total_tests': len(self.tests),
+ 'passed': passed,
+ 'failed': len(self.tests) - passed,
+ 'total_cost_usd': round(total_cost, 2),
+ 'total_duration_ms': total_duration,
+ 'tests': [vars(t) for t in self.tests],
+ }
+
+ EVAL_DIR.mkdir(parents=True, exist_ok=True)
+ date_str = timestamp.replace(':', '').replace('.', '').replace('+', '')[:15]
+ safe_branch = branch.replace('/', '-').replace('@', '-')
+ filename = f'{version}-{safe_branch}-{self.tier}-{date_str}.json'
+ filepath = EVAL_DIR / filename
+ filepath.write_text(json.dumps(result, indent=2) + '\n')
+
+ self._print_summary(result, filepath, branch, sha)
+ return str(filepath)
+
+ def _print_summary(self, result: dict, filepath: Path, branch: str, sha: str) -> None:
+ lines = ['']
+ lines.append(f"Eval Results — v{result['version']} @ {branch} ({sha}) — {self.tier}")
+ lines.append('═' * 65)
+
+ for t in self.tests:
+ status = ' PASS ' if t.passed else ' FAIL '
+ cost = f"${t.cost_usd:.3f}"
+ dur = f"{round(t.duration_ms / 1000)}s" if t.duration_ms else ''
+ name = t.name[:35] + '...' if len(t.name) > 38 else t.name.ljust(38)
+ lines.append(f" {name} {status} {cost.rjust(7)} {dur.rjust(5)}")
+
+ lines.append('─' * 65)
+ lines.append(
+ f" Total: {result['passed']}/{result['total_tests']} passed "
+ f"${result['total_cost_usd']:.2f} {round(result['total_duration_ms'] / 1000)}s"
+ )
+ lines.append(f'Saved: {filepath}')
+ print('\n'.join(lines), file=sys.stderr)
diff --git a/test/helpers/llm_judge.py b/test/helpers/llm_judge.py
new file mode 100644
index 00000000..e0d773d6
--- /dev/null
+++ b/test/helpers/llm_judge.py
@@ -0,0 +1,149 @@
+"""
+LLM-as-judge helpers for toprank evals.
+
+Requires: ANTHROPIC_API_KEY env var and `anthropic` package installed.
+"""
+
+import json
+import re
+import time
+from dataclasses import dataclass
+
+_client = None
+
+
+def _get_client():
+ global _client
+ if _client is None:
+ try:
+ import anthropic
+ except ImportError:
+ raise ImportError(
+ 'anthropic package required for LLM judge — run: pip install anthropic'
+ )
+ _client = anthropic.Anthropic()
+ return _client
+
+
+def call_judge(prompt: str) -> dict:
+ """Call claude-sonnet-4-6, return parsed JSON. Retries up to 3 times on rate limit."""
+ client = _get_client()
+
+ def make_request():
+ return client.messages.create(
+ model='claude-sonnet-4-6',
+ max_tokens=1024,
+ messages=[{'role': 'user', 'content': prompt}],
+ )
+
+ last_exc: Exception | None = None
+ for attempt in range(3):
+ try:
+ response = make_request()
+ break
+ except Exception as e:
+ if getattr(e, 'status_code', None) == 429 or 'rate' in str(e).lower():
+ last_exc = e
+ time.sleep(2 ** attempt) # 1s, 2s, 4s
+ else:
+ raise
+ else:
+ raise last_exc # all retries exhausted
+
+ text = response.content[0].text if response.content[0].type == 'text' else ''
+ match = re.search(r'\{[\s\S]*\}', text)
+ if not match:
+ raise ValueError(f'Judge returned non-JSON: {text[:200]}')
+ return json.loads(match.group(0))
+
+
+@dataclass
+class JudgeScore:
+ clarity: int # 1–5: can an agent understand what to do?
+ completeness: int # 1–5: is all needed info present?
+ actionability: int # 1–5: can an agent act without guessing?
+ reasoning: str
+
+
+@dataclass
+class SeoReportScore:
+ has_quick_wins: bool # Report includes a Quick Wins section
+ recommendations_specific: bool # Recommendations include specific URLs and query names
+ has_action_plan: bool # Report includes a 30-day action plan
+ quantified_impact: bool # At least one recommendation quantifies impact
+ score: int # 1–5 overall quality
+ reasoning: str
+
+
+def judge(section: str, content: str) -> JudgeScore:
+ """Score a SKILL.md section for documentation quality."""
+ result = call_judge(f"""You are evaluating instructions for an AI agent performing SEO analysis.
+
+The agent reads these instructions to learn how to run a structured SEO audit. It needs to:
+1. Know what steps to take and in what order
+2. Know what tools/scripts to call and with what arguments
+3. Know what the output should look like and what to include
+
+Rate the following {section} on three dimensions (1–5):
+
+- **clarity** (1–5): Can an agent understand what each step does from the description alone?
+- **completeness** (1–5): Are commands, arguments, and expected behavior documented? Would an agent need to guess anything?
+- **actionability** (1–5): Can an agent execute this section correctly without asking follow-up questions?
+
+Scoring guide:
+- 5: Excellent — no ambiguity, all info present
+- 4: Good — minor gaps an experienced agent can infer
+- 3: Adequate — some guessing required
+- 2: Poor — significant info missing
+- 1: Unusable — agent would fail without external help
+
+Respond with ONLY valid JSON:
+{{"clarity": N, "completeness": N, "actionability": N, "reasoning": "brief explanation"}}
+
+Content to evaluate:
+
+{content}""")
+
+ return JudgeScore(
+ clarity=result['clarity'],
+ completeness=result['completeness'],
+ actionability=result['actionability'],
+ reasoning=result.get('reasoning', ''),
+ )
+
+
+def seo_report_judge(report: str) -> SeoReportScore:
+ """Evaluate a generated SEO report against quality criteria."""
+ result = call_judge(f"""You are evaluating the quality of an SEO analysis report generated by an AI agent.
+
+A high-quality SEO report must:
+1. Include a "Quick Wins" section with specific page URLs and query names
+2. Make recommendations that are specific and actionable (not vague like "improve your SEO")
+3. Include a 30-day action plan with prioritized steps
+4. Quantify expected impact (e.g. estimated click increases) for at least one recommendation
+
+Evaluate the following report:
+
+---
+{report[:6000]}
+---
+
+Respond with ONLY valid JSON:
+{{
+ "has_quick_wins": true/false,
+ "recommendations_specific": true/false,
+ "has_action_plan": true/false,
+ "quantified_impact": true/false,
+ "score": 1-5,
+ "reasoning": "brief explanation"
+}}
+""")
+
+ return SeoReportScore(
+ has_quick_wins=bool(result.get('has_quick_wins')),
+ recommendations_specific=bool(result.get('recommendations_specific')),
+ has_action_plan=bool(result.get('has_action_plan')),
+ quantified_impact=bool(result.get('quantified_impact')),
+ score=int(result.get('score', 0)),
+ reasoning=result.get('reasoning', ''),
+ )
diff --git a/test/helpers/session_runner.py b/test/helpers/session_runner.py
new file mode 100644
index 00000000..0a6b4958
--- /dev/null
+++ b/test/helpers/session_runner.py
@@ -0,0 +1,179 @@
+"""
+Claude CLI subprocess runner for skill E2E testing.
+
+Spawns `claude -p` as an independent process. Pipes the prompt via -p,
+captures stream-json NDJSON output.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+import time
+from dataclasses import dataclass
+from typing import Any, Optional
+
+# Strip these env var prefixes so nested sessions don't inherit outer context.
+# ANTHROPIC_API_KEY is re-added below — the subprocess needs it.
+# Strip ANTHROPIC_* too so ANTHROPIC_BASE_URL / ANTHROPIC_MODEL can't redirect
+# the subprocess to a different model or endpoint.
+_STRIP_PREFIXES = ('CLAUDE_', 'ANTHROPIC_')
+
+
+@dataclass
+class ToolCall:
+ tool: str
+ input: dict[str, Any]
+ output: str = ''
+
+
+@dataclass
+class CostEstimate:
+ turns_used: int
+ estimated_cost: float # USD
+ estimated_tokens: int = 0
+
+
+@dataclass
+class SkillTestResult:
+ output: str
+ exit_reason: str # 'success', 'timeout', 'error_api', 'exit_code_N', ...
+ tool_calls: list[ToolCall]
+ cost_estimate: CostEstimate
+ duration: int # ms
+ model: str
+ transcript: list[Any]
+
+
+def parse_ndjson(lines: list[str]) -> tuple[list[Any], Any, int, list[ToolCall]]:
+ """Parse NDJSON lines from claude stream-json output.
+
+ Returns (transcript, result_line, turn_count, tool_calls).
+ """
+ transcript: list[Any] = []
+ result_line = None
+ turn_count = 0
+ tool_calls: list[ToolCall] = []
+
+ for line in lines:
+ line = line.strip()
+ if not line:
+ continue
+ try:
+ event = json.loads(line)
+ except json.JSONDecodeError:
+ continue
+
+ transcript.append(event)
+
+ if event.get('type') == 'assistant':
+ turn_count += 1
+ for item in event.get('message', {}).get('content', []):
+ if item.get('type') == 'tool_use':
+ tool_calls.append(ToolCall(
+ tool=item.get('name', 'unknown'),
+ input=item.get('input', {}),
+ ))
+
+ if event.get('type') == 'result':
+ result_line = event
+
+ return transcript, result_line, turn_count, tool_calls
+
+
+def create_skill_workdir(skill_path: str, skill_name: str) -> str:
+ """Copy skill into a temp dir so Claude auto-discovers it at .claude/skills/<name>."""
+ tmpdir = tempfile.mkdtemp(prefix=f'toprank-test-')
+ dest = os.path.join(tmpdir, '.claude', 'skills', skill_name)
+ shutil.copytree(skill_path, dest)
+ return tmpdir
+
+
+def run_skill_test(
+ prompt: str,
+ working_directory: Optional[str] = None,
+ max_turns: int = 30,
+ timeout_ms: int = 5 * 60 * 1000,
+ test_name: str = 'test',
+ env_overrides: Optional[dict[str, str]] = None,
+) -> SkillTestResult:
+ """Run claude -p in a subprocess and return parsed results."""
+ if working_directory is None:
+ working_directory = tempfile.gettempdir()
+
+ # Build environment: strip CLAUDE_* vars, keep ANTHROPIC_API_KEY
+ env = {k: v for k, v in os.environ.items()
+ if not any(k.startswith(p) for p in _STRIP_PREFIXES)}
+ if os.environ.get('ANTHROPIC_API_KEY'):
+ env['ANTHROPIC_API_KEY'] = os.environ['ANTHROPIC_API_KEY']
+ if env_overrides:
+ env.update(env_overrides)
+
+ cmd = [
+ 'claude',
+ '--output-format', 'stream-json',
+ '--verbose',
+ '--max-turns', str(max_turns),
+ '-p', prompt,
+ ]
+
+ start = time.time()
+ timed_out = False
+
+ try:
+ proc = subprocess.run(
+ cmd,
+ capture_output=True,
+ text=True,
+ cwd=working_directory,
+ env=env,
+ timeout=timeout_ms / 1000,
+ )
+ stdout = proc.stdout
+ exit_code = proc.returncode
+ except subprocess.TimeoutExpired as e:
+ timed_out = True
+ stdout = (e.stdout or b'').decode('utf-8', errors='replace') if isinstance(e.stdout, bytes) else (e.stdout or '')
+ exit_code = -1
+
+ duration = int((time.time() - start) * 1000)
+ lines = stdout.splitlines()
+ transcript, result_line, turn_count, tool_calls = parse_ndjson(lines)
+
+ # Determine exit reason
+ if timed_out:
+ exit_reason = 'timeout'
+ elif result_line:
+ if result_line.get('is_error'):
+ exit_reason = 'error_api'
+ else:
+ exit_reason = result_line.get('subtype', 'success')
+ elif exit_code == 0:
+ exit_reason = 'success'
+ else:
+ exit_reason = f'exit_code_{exit_code}'
+
+ turns_used = result_line.get('num_turns', 0) if result_line else 0
+ estimated_cost = result_line.get('total_cost_usd', 0.0) if result_line else 0.0
+ usage = result_line.get('usage', {}) if result_line else {}
+ estimated_tokens = (
+ usage.get('input_tokens', 0) +
+ usage.get('output_tokens', 0) +
+ usage.get('cache_read_input_tokens', 0)
+ )
+ model = result_line.get('model', 'unknown') if result_line else 'unknown'
+
+ return SkillTestResult(
+ output=result_line.get('result', '') if result_line else '',
+ exit_reason=exit_reason,
+ tool_calls=tool_calls,
+ cost_estimate=CostEstimate(
+ turns_used=turns_used,
+ estimated_cost=round(estimated_cost, 4),
+ estimated_tokens=estimated_tokens,
+ ),
+ duration=duration,
+ model=model,
+ transcript=transcript,
+ )
diff --git a/test/helpers/touchfiles.py b/test/helpers/touchfiles.py
new file mode 100644
index 00000000..af814b47
--- /dev/null
+++ b/test/helpers/touchfiles.py
@@ -0,0 +1,88 @@
+"""
+Diff-based test selection.
+
+Each test declares which files it depends on. If none of those files
+changed relative to the base branch, the test is skipped.
+Set EVALS_ALL=1 to run everything regardless of diffs.
+"""
+
+import re
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+E2E_TOUCHFILES: dict[str, list[str]] = {
+ 'seo-no-gsc-technical-audit': ['seo/seo-analysis/**'],
+ 'seo-fixture-full-audit': ['seo/seo-analysis/**', 'test/fixtures/sample_gsc_data.json'],
+ 'seo-report-quality': ['seo/seo-analysis/**', 'test/fixtures/sample_gsc_data.json'],
+}
+
+LLM_JUDGE_TOUCHFILES: dict[str, list[str]] = {
+ 'seo-phases-clarity': ['seo/seo-analysis/SKILL.md'],
+ 'seo-report-format-clarity': ['seo/seo-analysis/SKILL.md'],
+ 'seo-quick-wins-clarity': ['seo/seo-analysis/SKILL.md'],
+}
+
+ROUTING_TOUCHFILES: dict[str, list[str]] = {
+ 'routing-seo-triggers': ['seo/seo-analysis/SKILL.md'],
+ 'routing-seo-non-triggers': ['seo/seo-analysis/SKILL.md'],
+}
+
+# Changes to these files trigger all tests
+GLOBAL_TOUCHFILES = ['test/helpers/**']
+
+
+def detect_base_branch(repo_root: str) -> Optional[str]:
+ for branch in ('main', 'master', 'develop'):
+ result = subprocess.run(
+ ['git', 'rev-parse', '--verify', branch],
+ cwd=repo_root, capture_output=True, timeout=3,
+ )
+ if result.returncode == 0:
+ return branch
+ return None
+
+
+def get_changed_files(base_branch: str, repo_root: str) -> list[str]:
+ result = subprocess.run(
+ ['git', 'diff', '--name-only', f'{base_branch}...HEAD'],
+ cwd=repo_root, capture_output=True, text=True, timeout=5,
+ )
+ if result.returncode != 0:
+ return []
+ return [f for f in result.stdout.strip().split('\n') if f]
+
+
+def match_glob(file: str, pattern: str) -> bool:
+ regex = (
+ pattern
+ .replace('.', r'\.')
+ .replace('**', '\x00')
+ .replace('*', '[^/]*')
+ .replace('\x00', '.*')
+ )
+ return bool(re.fullmatch(regex, file))
+
+
+def select_tests(
+ changed_files: list[str],
+ touchfile_map: dict[str, list[str]],
+ global_touchfiles: list[str],
+) -> dict:
+ """Returns {'selected': [...], 'skipped': [...], 'reason': '...'}"""
+ # If any global file changed, run all tests
+ if any(match_glob(f, g) for f in changed_files for g in global_touchfiles):
+ return {
+ 'selected': list(touchfile_map.keys()),
+ 'skipped': [],
+ 'reason': 'global touchfile changed',
+ }
+
+ selected, skipped = [], []
+ for test_name, patterns in touchfile_map.items():
+ if any(match_glob(f, p) for f in changed_files for p in patterns):
+ selected.append(test_name)
+ else:
+ skipped.append(test_name)
+
+ return {'selected': selected, 'skipped': skipped, 'reason': 'diff-based selection'}
diff --git a/test/install.test.sh b/test/install.test.sh
new file mode 100755
index 00000000..62ec85c6
--- /dev/null
+++ b/test/install.test.sh
@@ -0,0 +1,281 @@
+#!/usr/bin/env bash
+# test/install.test.sh — mock-$HOME install tests for ./setup
+#
+# Usage:
+# ./test/install.test.sh
+#
+# Tests run in isolated temp directories. No system state is modified.
+
+set -eo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PASS=0
+FAIL=0
+
+# ─── Helpers ─────────────────────────────────────────────────
+
+pass() { echo " PASS $1"; PASS=$((PASS + 1)); }
+fail() { echo " FAIL $1"; FAIL=$((FAIL + 1)); }
+
+assert_link() {
+ local path="$1" label="$2"
+ [ -L "$path" ] && pass "$label" || fail "$label — expected symlink at $path"
+}
+
+assert_no_link() {
+ local path="$1" label="$2"
+ [ ! -L "$path" ] && pass "$label" || fail "$label — unexpected symlink at $path"
+}
+
+assert_file() {
+ local path="$1" label="$2"
+ [ -f "$path" ] && pass "$label" || fail "$label — expected file at $path"
+}
+
+assert_contains() {
+ local path="$1" needle="$2" label="$3"
+ grep -q "$needle" "$path" 2>/dev/null && pass "$label" || fail "$label — '$needle' not in $path"
+}
+
+assert_exit_nonzero() {
+ local code="$1" label="$2"
+ [ "$code" -ne 0 ] && pass "$label" || fail "$label — expected non-zero exit"
+}
+
+run_setup() {
+ (cd "$1" && ./setup "${@:2}") >/dev/null 2>&1
+}
+
+# Skills that should be registered (everything with a SKILL.md).
+# This list is intentionally explicit — new skills must be added here consciously.
+# The count-check below will catch a mismatch if a skill is added to the repo
+# without updating this list.
+#
+# Format: skill_name:relative_path (name is what gets symlinked, path is source)
+SKILLS_WITH_PATHS=(
+ "seo-analysis:seo/seo-analysis"
+ "content-writer:seo/content-writer"
+ "keyword-research:seo/keyword-research"
+ "meta-tags-optimizer:seo/meta-tags-optimizer"
+ "schema-markup-generator:seo/schema-markup-generator"
+ "setup-cms:seo/setup-cms"
+ "ads:google-ads/ads"
+ "toprank-upgrade:toprank-upgrade"
+)
+
+# Extract just skill names for iteration
+SKILLS=()
+for entry in "${SKILLS_WITH_PATHS[@]}"; do
+ SKILLS+=("${entry%%:*}")
+done
+
+# Build associative-style lookup: skill_name -> relative_path
+skill_rel_path() {
+ local name="$1"
+ for entry in "${SKILLS_WITH_PATHS[@]}"; do
+ if [ "${entry%%:*}" = "$name" ]; then
+ echo "${entry#*:}"
+ return
+ fi
+ done
+}
+
+# Guard: actual SKILL.md count must match the SKILLS array above.
+actual_skill_count=$(find "$REPO_ROOT" -maxdepth 3 -name "SKILL.md" | wc -l | tr -d ' ')
+if [ "$actual_skill_count" -ne "${#SKILLS[@]}" ]; then
+ echo "ERROR: SKILLS array has ${#SKILLS[@]} entries but repo has $actual_skill_count SKILL.md files."
+ echo " Update the SKILLS array in this file to match."
+ exit 1
+fi
+
+# Make a fresh copy of the repo in a subdirectory of TMP (exclude .git to
+# avoid confusing git rev-parse in tests that set up their own git repo)
+clone_into() {
+ local dest="$1"
+ mkdir -p "$dest"
+ rsync -a --exclude='.git' --exclude='.claude' "$REPO_ROOT/" "$dest/"
+}
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+# ─── Test 1: Claude Code global install (--host claude) ───────
+
+echo ""
+echo "=== 1. Claude Code global install ==="
+
+T1="$TMP/t1"
+SKILLS_DIR="$T1/.claude/skills"
+TOPRANK_DIR="$SKILLS_DIR/toprank"
+
+clone_into "$TOPRANK_DIR"
+run_setup "$TOPRANK_DIR" --host claude
+
+for skill in "${SKILLS[@]}"; do
+ assert_link "$SKILLS_DIR/$skill" "symlink created: $skill"
+done
+
+# Each symlink must point to toprank/<relative_path>
+for skill in "${SKILLS[@]}"; do
+ rel=$(skill_rel_path "$skill")
+ expected_target="toprank/$rel"
+ target="$(readlink "$SKILLS_DIR/$skill" 2>/dev/null || echo '')"
+ [ "$target" = "$expected_target" ] \
+ && pass "symlink target correct: $skill -> $expected_target" \
+ || fail "symlink target wrong for $skill — got '$target', want '$expected_target'"
+done
+
+# SKILL.md files (except toprank-upgrade and ads) must have preamble injected
+for skill in "${SKILLS[@]}"; do
+ [ "$skill" = "toprank-upgrade" ] && continue
+ [ "$skill" = "ads" ] && continue
+ rel=$(skill_rel_path "$skill")
+ assert_contains "$TOPRANK_DIR/$rel/SKILL.md" "toprank-update-check" "preamble injected: $skill"
+done
+
+# ─── Test 2: Auto-detect via path (no --host flag) ────────────
+
+echo ""
+echo "=== 2. Auto-detect: path ends in .claude/skills ==="
+
+T2="$TMP/t2"
+SKILLS_DIR2="$T2/.claude/skills"
+TOPRANK_DIR2="$SKILLS_DIR2/toprank"
+
+clone_into "$TOPRANK_DIR2"
+run_setup "$TOPRANK_DIR2" # no --host flag
+
+for skill in "${SKILLS[@]}"; do
+ assert_link "$SKILLS_DIR2/$skill" "auto-detected and linked: $skill"
+done
+
+# ─── Test 3: Idempotency — running setup twice is safe ────────
+
+echo ""
+echo "=== 3. Idempotency (setup runs twice) ==="
+
+run_setup "$TOPRANK_DIR" --host claude # second run on T1
+
+for skill in "${SKILLS[@]}"; do
+ assert_link "$SKILLS_DIR/$skill" "symlink still valid after re-run: $skill"
+done
+
+# No extra symlinks created
+actual_count="$(find "$SKILLS_DIR" -maxdepth 1 -type l | wc -l | tr -d ' ')"
+expected_count="${#SKILLS[@]}"
+[ "$actual_count" -eq "$expected_count" ] \
+ && pass "no duplicate links ($actual_count total)" \
+ || fail "wrong link count — got $actual_count, want $expected_count"
+
+# ─── Test 4: Real directory is not overwritten ────────────────
+
+echo ""
+echo "=== 4. Existing real directory is not overwritten ==="
+
+T4="$TMP/t4"
+SKILLS_DIR4="$T4/.claude/skills"
+TOPRANK_DIR4="$SKILLS_DIR4/toprank"
+
+clone_into "$TOPRANK_DIR4"
+mkdir -p "$SKILLS_DIR4/seo-analysis" # real dir, not a symlink
+
+output="$(cd "$TOPRANK_DIR4" && ./setup --host claude 2>&1 || true)"
+
+assert_no_link "$SKILLS_DIR4/seo-analysis" "real dir not overwritten"
+echo "$output" | grep -q "skipped seo-analysis" \
+ && pass "skip message shown for existing real dir" \
+ || fail "no skip message for existing real dir"
+
+# Other skills still get linked
+for skill in "${SKILLS[@]}"; do
+ [ "$skill" = "seo-analysis" ] && continue
+ assert_link "$SKILLS_DIR4/$skill" "other skills linked despite skip: $skill"
+done
+
+# ─── Test 5: Codex install (--host codex) ─────────────────────
+
+echo ""
+echo "=== 5. Codex install ==="
+
+T5="$TMP/t5"
+REPO="$T5/myproject"
+TOPRANK_DIR5="$REPO/.agents/skills/toprank"
+AGENTS_DIR="$REPO/.agents/skills"
+
+git init "$REPO" >/dev/null 2>&1
+clone_into "$TOPRANK_DIR5"
+run_setup "$TOPRANK_DIR5" --host codex
+
+for skill in "${SKILLS[@]}"; do
+ codex_name="toprank-$skill"
+ assert_file "$AGENTS_DIR/$codex_name/agents/openai.yaml" "openai.yaml created: $codex_name"
+ assert_file "$AGENTS_DIR/$codex_name/SKILL.md" "SKILL.md copied: $codex_name"
+done
+
+# openai.yaml must have required fields
+yaml="$AGENTS_DIR/toprank-seo-analysis/agents/openai.yaml"
+assert_contains "$yaml" "display_name" "openai.yaml has display_name"
+assert_contains "$yaml" "allow_implicit_invocation" "openai.yaml has allow_implicit_invocation"
+assert_contains "$yaml" "toprank-seo-analysis" "openai.yaml has correct skill name"
+
+# ─── Test 6: Invalid --host value exits non-zero ──────────────
+
+echo ""
+echo "=== 6. Invalid --host exits non-zero ==="
+
+T6="$TMP/t6"
+clone_into "$T6/toprank"
+exit_code=0
+(cd "$T6/toprank" && ./setup --host badvalue) >/dev/null 2>&1 || exit_code=$?
+assert_exit_nonzero "$exit_code" "--host badvalue exits non-zero"
+
+# ─── Test 7: Google Ads interactive setup ─────────────────────
+
+echo ""
+echo "=== 7. Google Ads interactive setup ==="
+
+T7="$TMP/t7"
+SKILLS_DIR7="$T7/.claude/skills"
+TOPRANK_DIR7="$SKILLS_DIR7/toprank"
+HOME7="$T7/home"
+
+clone_into "$TOPRANK_DIR7"
+
+# Simulate interactive input: "y" then a test API key
+# TOPRANK_FORCE_INTERACTIVE bypasses the isatty() check for piped input
+printf 'y\nasa_test_key_123\n' | HOME="$HOME7" TOPRANK_FORCE_INTERACTIVE=1 \
+ bash -c 'cd "'"$TOPRANK_DIR7"'" && ./setup --host claude' >/dev/null 2>&1
+
+# Verify config was written
+config_file="$HOME7/.adsagent/config.json"
+assert_file "$config_file" "ads config file created"
+if [ -f "$config_file" ]; then
+ assert_contains "$config_file" "asa_test_key_123" "ads config has correct API key"
+fi
+
+# ─── Test 8: Google Ads setup with --api-key flag ─────────────
+
+echo ""
+echo "=== 8. Google Ads --api-key flag ==="
+
+T8="$TMP/t8"
+SKILLS_DIR8="$T8/.claude/skills"
+TOPRANK_DIR8="$SKILLS_DIR8/toprank"
+HOME8="$T8/home"
+
+clone_into "$TOPRANK_DIR8"
+HOME="$HOME8" bash -c 'cd "'"$TOPRANK_DIR8"'" && ./setup --host claude --api-key asa_flag_key_456' >/dev/null 2>&1
+
+config_file8="$HOME8/.adsagent/config.json"
+assert_file "$config_file8" "ads config created via --api-key"
+if [ -f "$config_file8" ]; then
+ assert_contains "$config_file8" "asa_flag_key_456" "ads config has flag API key"
+fi
+
+# ─── Results ──────────────────────────────────────────────────
+
+echo ""
+echo "─────────────────────────────"
+echo " $PASS passed | $FAIL failed"
+echo "─────────────────────────────"
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1
diff --git a/test/test_skill_e2e.py b/test/test_skill_e2e.py
new file mode 100644
index 00000000..691567bf
--- /dev/null
+++ b/test/test_skill_e2e.py
@@ -0,0 +1,235 @@
+"""
+End-to-end tests for the seo-analysis skill.
+
+Spawns `claude -p` with the skill installed in a temp working directory.
+Uses mock scripts and fixture data so no real Google credentials are needed.
+
+Run: EVALS=1 pytest test/test_skill_e2e.py
+"""
+
+import os
+import shutil
+import sys
+import time
+from pathlib import Path
+
+import pytest
+
+from helpers.session_runner import run_skill_test, create_skill_workdir
+from helpers.llm_judge import seo_report_judge
+from helpers.eval_store import EvalCollector, EvalTestEntry
+from helpers.touchfiles import (
+ select_tests, detect_base_branch, get_changed_files,
+ E2E_TOUCHFILES, GLOBAL_TOUCHFILES,
+)
+
+ROOT = Path(__file__).parent.parent
+SKILL_PATH = ROOT / 'seo' / 'seo-analysis'
+FIXTURES_DIR = ROOT / 'test' / 'fixtures'
+
+EVALS = bool(os.environ.get('EVALS'))
+pytestmark = pytest.mark.skipif(not EVALS, reason='Set EVALS=1 to run E2E evals')
+
+# Diff-based selection
+_selected: list[str] | None = None
+if EVALS and not os.environ.get('EVALS_ALL'):
+ _base = os.environ.get('EVALS_BASE') or detect_base_branch(str(ROOT)) or 'main'
+ _changed = get_changed_files(_base, str(ROOT))
+ if _changed:
+ _sel = select_tests(_changed, E2E_TOUCHFILES, GLOBAL_TOUCHFILES)
+ _selected = _sel['selected']
+ print(
+ f"\nE2E selection ({_sel['reason']}): "
+ f"{len(_selected)}/{len(E2E_TOUCHFILES)} tests",
+ file=sys.stderr,
+ )
+
+
+def _should_run(name: str) -> bool:
+ return EVALS and (_selected is None or name in _selected)
+
+
+_tmp_dirs: list[str] = []
+_collector = EvalCollector('e2e') if EVALS else None
+
+
+def _create_fixture_workdir() -> tuple[str, str]:
+ """Create workdir with mock GSC scripts pre-installed."""
+ workdir = create_skill_workdir(str(SKILL_PATH), 'seo-analysis')
+ _tmp_dirs.append(workdir) # register before any further setup so cleanup runs on error
+
+ skill_scripts_dir = Path(workdir) / '.claude' / 'skills' / 'seo-analysis' / 'scripts'
+ shutil.copy(FIXTURES_DIR / 'mock-analyze-gsc.py', skill_scripts_dir / 'analyze_gsc.py')
+ shutil.copy(FIXTURES_DIR / 'sample_gsc_data.json', skill_scripts_dir / 'sample_gsc_data.json')
+
+ mock_bin = Path(workdir) / 'bin'
+ mock_bin.mkdir(exist_ok=True)
+ mock_gcloud = mock_bin / 'gcloud'
+ shutil.copy(FIXTURES_DIR / 'mock-gcloud.sh', mock_gcloud)
+ mock_gcloud.chmod(0o755)
+
+ return workdir, str(mock_bin)
+
+
[email protected](not _should_run('seo-no-gsc-technical-audit'), reason='not selected')
+def test_seo_no_gsc_technical_audit():
+ t0 = time.time()
+ workdir = create_skill_workdir(str(SKILL_PATH), 'seo-analysis')
+ _tmp_dirs.append(workdir) # register before run so cleanup happens on error
+
+ result = run_skill_test(
+ prompt=(
+ 'Use the seo-analysis skill to do a technical SEO audit. '
+ "I don't have GSC access — skip that, just audit the URL directly. "
+ 'Site: https://example-saas.com '
+ 'Focus on the technical audit (Phase 5) and produce the report (Phase 6). '
+ 'Keep it brief — you can skip pulling real data, just audit what you can from the URL structure.'
+ ),
+ working_directory=workdir,
+ max_turns=20,
+ timeout_ms=3 * 60 * 1000,
+ test_name='seo-no-gsc-technical-audit',
+ )
+
+ duration = int((time.time() - t0) * 1000)
+
+ if _collector:
+ _collector.add_test(EvalTestEntry(
+ name='seo-no-gsc-technical-audit',
+ suite='seo-analysis skill E2E',
+ tier='e2e',
+ passed=result.exit_reason == 'success',
+ duration_ms=duration,
+ cost_usd=result.cost_estimate.estimated_cost,
+ output=result.output[:1000] if result.output else None,
+ turns_used=result.cost_estimate.turns_used,
+ exit_reason=result.exit_reason,
+ model=result.model,
+ ))
+
+ assert result.exit_reason == 'success'
+ assert len(result.tool_calls) > 0
+ assert any(kw in result.output.lower() for kw in ('seo', 'technical', 'audit'))
+
+
[email protected](not _should_run('seo-fixture-full-audit'), reason='not selected')
+def test_seo_fixture_full_audit():
+ t0 = time.time()
+ workdir, mock_bin = _create_fixture_workdir()
+
+ result = run_skill_test(
+ prompt=(
+ 'Run the seo-analysis skill for sc-domain:example-saas.com. '
+ "Use the skill's full workflow including the GSC data pull. "
+ 'The analysis data is available — go through all phases.'
+ ),
+ working_directory=workdir,
+ max_turns=35,
+ timeout_ms=5 * 60 * 1000,
+ test_name='seo-fixture-full-audit',
+ env_overrides={'PATH': f"{mock_bin}:{os.environ.get('PATH', '/usr/local/bin:/usr/bin:/bin')}"},
+ )
+
+ duration = int((time.time() - t0) * 1000)
+
+ report_score = None
+ if result.exit_reason == 'success' and len(result.output) > 200:
+ try:
+ report_score = seo_report_judge(result.output)
+ except Exception:
+ pass
+
+ if _collector:
+ _collector.add_test(EvalTestEntry(
+ name='seo-fixture-full-audit',
+ suite='seo-analysis skill E2E',
+ tier='e2e',
+ passed=result.exit_reason == 'success',
+ duration_ms=duration,
+ cost_usd=result.cost_estimate.estimated_cost,
+ output=result.output[:2000] if result.output else None,
+ turns_used=result.cost_estimate.turns_used,
+ exit_reason=result.exit_reason,
+ model=result.model,
+ judge_scores={'score': report_score.score} if report_score else None,
+ judge_reasoning=report_score.reasoning if report_score else None,
+ ))
+
+ assert result.exit_reason == 'success'
+ bash_calls = [c for c in result.tool_calls if c.tool == 'Bash']
+ assert len(bash_calls) > 0
+ assert 'quick win' in result.output.lower()
+
+
[email protected](not _should_run('seo-report-quality'), reason='not selected')
+def test_seo_report_quality():
+ t0 = time.time()
+ workdir, mock_bin = _create_fixture_workdir()
+
+ result = run_skill_test(
+ prompt=(
+ 'Use the seo-analysis skill for sc-domain:example-saas.com. '
+ 'The fixture data has position 4-10 quick wins and traffic drops — find them. '
+ 'Produce a full report with specific recommendations.'
+ ),
+ working_directory=workdir,
+ max_turns=35,
+ timeout_ms=5 * 60 * 1000,
+ test_name='seo-report-quality',
+ env_overrides={'PATH': f"{mock_bin}:{os.environ.get('PATH', '/usr/local/bin:/usr/bin:/bin')}"},
+ )
+
+ duration = int((time.time() - t0) * 1000)
+
+ if result.exit_reason != 'success':
+ if _collector:
+ _collector.add_test(EvalTestEntry(
+ name='seo-report-quality',
+ suite='seo-analysis skill E2E',
+ tier='e2e',
+ passed=False,
+ duration_ms=duration,
+ cost_usd=result.cost_estimate.estimated_cost,
+ exit_reason=result.exit_reason,
+ model=result.model,
+ error=f'Skill failed: {result.exit_reason}',
+ ))
+ assert result.exit_reason == 'success'
+ return
+
+ report_score = seo_report_judge(result.output)
+ passed = report_score.has_quick_wins and report_score.recommendations_specific and report_score.score >= 3
+
+ if _collector:
+ _collector.add_test(EvalTestEntry(
+ name='seo-report-quality',
+ suite='seo-analysis skill E2E',
+ tier='e2e',
+ passed=passed,
+ duration_ms=duration,
+ cost_usd=result.cost_estimate.estimated_cost,
+ output=result.output[:2000] if result.output else None,
+ turns_used=result.cost_estimate.turns_used,
+ exit_reason=result.exit_reason,
+ model=result.model,
+ judge_scores={
+ 'score': report_score.score,
+ 'has_quick_wins': int(report_score.has_quick_wins),
+ 'recommendations_specific': int(report_score.recommendations_specific),
+ },
+ judge_reasoning=report_score.reasoning,
+ ))
+
+ assert report_score.has_quick_wins
+ assert report_score.recommendations_specific
+ assert report_score.score >= 3
+
+
+def teardown_module(module):
+ if _collector:
+ _collector.finalize()
+ for d in _tmp_dirs:
+ shutil.rmtree(d, ignore_errors=True)
diff --git a/test/test_skill_llm_eval.py b/test/test_skill_llm_eval.py
new file mode 100644
index 00000000..835bcdb4
--- /dev/null
+++ b/test/test_skill_llm_eval.py
@@ -0,0 +1,144 @@
+"""
+LLM-as-a-Judge evals for seo-analysis SKILL.md quality.
+
+Guards against regressions — if someone edits SKILL.md in a way that
+makes instructions ambiguous, these tests will catch it.
+
+Run: EVALS=1 pytest test/test_skill_llm_eval.py
+Cost: ~$0.05 per run
+"""
+
+import os
+import sys
+import time
+from pathlib import Path
+
+import pytest
+
+from helpers.llm_judge import judge
+from helpers.eval_store import EvalCollector, EvalTestEntry
+from helpers.touchfiles import (
+ select_tests, detect_base_branch, get_changed_files,
+ LLM_JUDGE_TOUCHFILES, GLOBAL_TOUCHFILES,
+)
+
+ROOT = Path(__file__).parent.parent
+SKILL_MD = ROOT / 'seo' / 'seo-analysis' / 'SKILL.md'
+
+EVALS = bool(os.environ.get('EVALS'))
+pytestmark = pytest.mark.skipif(not EVALS, reason='Set EVALS=1 to run LLM-judge evals')
+
+# Diff-based selection
+_selected: list[str] | None = None
+if EVALS and not os.environ.get('EVALS_ALL'):
+ _base = os.environ.get('EVALS_BASE') or detect_base_branch(str(ROOT)) or 'main'
+ _changed = get_changed_files(_base, str(ROOT))
+ if _changed:
+ _sel = select_tests(_changed, LLM_JUDGE_TOUCHFILES, GLOBAL_TOUCHFILES)
+ _selected = _sel['selected']
+ print(
+ f"\nLLM-judge selection ({_sel['reason']}): "
+ f"{len(_selected)}/{len(LLM_JUDGE_TOUCHFILES)} tests",
+ file=sys.stderr,
+ )
+
+
+def _should_run(name: str) -> bool:
+ return EVALS and (_selected is None or name in _selected)
+
+
+_skill_md = SKILL_MD.read_text() if EVALS else ''
+_collector = EvalCollector('llm-judge') if EVALS else None
+
+
+def _extract_section(md: str, start_marker: str, end_marker: str = '') -> str:
+ start = md.find(start_marker)
+ if start == -1:
+ return ''
+ if end_marker:
+ end = md.find(end_marker, start + len(start_marker))
+ return md[start:end].strip() if end != -1 else md[start:].strip()
+ return md[start:].strip()
+
+
[email protected](not _should_run('seo-phases-clarity'), reason='not selected')
+def test_seo_phases_clarity():
+ t0 = time.time()
+ section = _extract_section(_skill_md, '## Phase 1', '## Phase 4')
+ assert len(section) > 100
+
+ scores = judge('Phase 1–3 (setup & data collection)', section)
+ print('Phases 1-3 scores:', scores)
+
+ if _collector:
+ _collector.add_test(EvalTestEntry(
+ name='seo-phases-clarity',
+ suite='seo-analysis SKILL.md quality',
+ tier='llm-judge',
+ passed=scores.clarity >= 4 and scores.completeness >= 4 and scores.actionability >= 4,
+ duration_ms=int((time.time() - t0) * 1000),
+ cost_usd=0.02,
+ judge_scores={'clarity': scores.clarity, 'completeness': scores.completeness, 'actionability': scores.actionability},
+ judge_reasoning=scores.reasoning,
+ ))
+
+ assert scores.clarity >= 4
+ assert scores.completeness >= 4
+ assert scores.actionability >= 4
+
+
[email protected](not _should_run('seo-quick-wins-clarity'), reason='not selected')
+def test_seo_quick_wins_clarity():
+ t0 = time.time()
+ section = _extract_section(_skill_md, '### Quick Wins', '### Search Intent')
+ assert len(section) > 50
+
+ scores = judge('Quick Wins analysis instructions', section)
+ print('Quick Wins scores:', scores)
+
+ if _collector:
+ _collector.add_test(EvalTestEntry(
+ name='seo-quick-wins-clarity',
+ suite='seo-analysis SKILL.md quality',
+ tier='llm-judge',
+ passed=scores.clarity >= 4 and scores.completeness >= 4 and scores.actionability >= 4,
+ duration_ms=int((time.time() - t0) * 1000),
+ cost_usd=0.02,
+ judge_scores={'clarity': scores.clarity, 'completeness': scores.completeness, 'actionability': scores.actionability},
+ judge_reasoning=scores.reasoning,
+ ))
+
+ assert scores.clarity >= 4
+ assert scores.completeness >= 4
+ assert scores.actionability >= 4
+
+
[email protected](not _should_run('seo-report-format-clarity'), reason='not selected')
+def test_seo_report_format_clarity():
+ t0 = time.time()
+ section = _extract_section(_skill_md, '## Phase 6')
+ assert len(section) > 100
+
+ scores = judge('Phase 6 report format', section)
+ print('Report format scores:', scores)
+
+ if _collector:
+ _collector.add_test(EvalTestEntry(
+ name='seo-report-format-clarity',
+ suite='seo-analysis SKILL.md quality',
+ tier='llm-judge',
+ passed=scores.clarity >= 4 and scores.completeness >= 3 and scores.actionability >= 4,
+ duration_ms=int((time.time() - t0) * 1000),
+ cost_usd=0.02,
+ judge_scores={'clarity': scores.clarity, 'completeness': scores.completeness, 'actionability': scores.actionability},
+ judge_reasoning=scores.reasoning,
+ ))
+
+ assert scores.clarity >= 4
+ assert scores.completeness >= 3
+ assert scores.actionability >= 4
+
+
+def teardown_module(module):
+ if _collector:
+ _collector.finalize()
diff --git a/test/test_skill_routing_e2e.py b/test/test_skill_routing_e2e.py
new file mode 100644
index 00000000..7613b34a
--- /dev/null
+++ b/test/test_skill_routing_e2e.py
@@ -0,0 +1,180 @@
+"""
+Routing E2E tests — does the seo-analysis skill trigger on the right prompts?
+
+Run: EVALS=1 pytest test/test_skill_routing_e2e.py
+"""
+
+import os
+import shutil
+import sys
+from pathlib import Path
+
+import pytest
+
+from helpers.session_runner import run_skill_test, create_skill_workdir
+from helpers.eval_store import EvalCollector, EvalTestEntry
+from helpers.touchfiles import (
+ select_tests, detect_base_branch, get_changed_files,
+ ROUTING_TOUCHFILES, GLOBAL_TOUCHFILES,
+)
+
+ROOT = Path(__file__).parent.parent
+SKILL_PATH = ROOT / 'seo' / 'seo-analysis'
+
+EVALS = bool(os.environ.get('EVALS'))
+pytestmark = pytest.mark.skipif(not EVALS, reason='Set EVALS=1 to run routing evals')
+
+_selected: list[str] | None = None
+if EVALS and not os.environ.get('EVALS_ALL'):
+ _base = os.environ.get('EVALS_BASE') or detect_base_branch(str(ROOT)) or 'main'
+ _changed = get_changed_files(_base, str(ROOT))
+ if _changed:
+ _sel = select_tests(_changed, ROUTING_TOUCHFILES, GLOBAL_TOUCHFILES)
+ _selected = _sel['selected']
+ print(
+ f"\nRouting E2E selection ({_sel['reason']}): "
+ f"{len(_selected)}/{len(ROUTING_TOUCHFILES)} tests",
+ file=sys.stderr,
+ )
+
+
+def _should_run(name: str) -> bool:
+ return EVALS and (_selected is None or name in _selected)
+
+
+_tmp_dirs: list[str] = []
+_collector = EvalCollector('routing') if EVALS else None
+
+SHOULD_TRIGGER = [
+ {'name': 'traffic-drop-question',
+ 'prompt': "My website traffic dropped 40% last month and I don't know why. I'm getting way fewer clicks from Google. Can you figure out what happened?"},
+ {'name': 'seo-audit-explicit',
+ 'prompt': "Can you run an SEO audit on my site? I want to know what's hurting my Google rankings."},
+ {'name': 'keyword-rankings',
+ 'prompt': "What keywords am I ranking for in Google? I want to see which queries are bringing traffic to my site."},
+ {'name': 'search-console-analysis',
+ 'prompt': "I have Google Search Console connected. Can you pull my search data and tell me what opportunities I'm missing?"},
+ {'name': 'improve-organic-traffic',
+ 'prompt': "I need to improve my organic search traffic. Where should I focus first to get more clicks from Google?"},
+]
+
+SHOULD_NOT_TRIGGER = [
+ {'name': 'css-debugging',
+ 'prompt': "My CSS grid layout is broken on mobile — the columns aren't stacking correctly. Can you help me debug it?"},
+ {'name': 'python-refactoring',
+ 'prompt': "I need to refactor this Python function to be more efficient. It's currently O(n²) and I need it to be O(n log n)."},
+ {'name': 'google-ads-performance',
+ 'prompt': "My Google Ads CPA jumped from $12 to $28 this week. What happened and how do I fix it?"},
+ {'name': 'content-writing',
+ 'prompt': "Can you write a blog post about the benefits of using project management software for remote teams?"},
+ {'name': 'database-query',
+ 'prompt': "This SQL query is timing out — it's taking 8 seconds on a 2M row table. Can you optimize it?"},
+]
+
+_SEO_MARKERS = [
+ 'phase 1', 'phase 2', 'phase 3',
+ 'google search console',
+ 'quick wins',
+ 'position 4',
+ 'gcloud',
+ 'analyze_gsc',
+ 'sc-domain:',
+]
+
+
+def _did_use_seo_skill(result) -> bool:
+ if any(m in result.output.lower() for m in _SEO_MARKERS):
+ return True
+ return any(c.tool == 'Bash' and 'analyze_gsc' in str(c.input) for c in result.tool_calls)
+
+
+def _run_routing_test(prompt_config: dict, should_trigger: bool) -> None:
+ workdir = create_skill_workdir(str(SKILL_PATH), 'seo-analysis')
+ _tmp_dirs.append(workdir)
+
+ result = run_skill_test(
+ prompt=prompt_config['prompt'],
+ working_directory=workdir,
+ max_turns=8,
+ timeout_ms=90 * 1000,
+ test_name=prompt_config['name'],
+ )
+
+ # Hard harness failure (timeout/crash) must not silently pass "should not trigger" tests
+ if result.exit_reason in ('timeout', 'error_api') or result.exit_reason.startswith('exit_code_'):
+ if _collector:
+ _collector.add_test(EvalTestEntry(
+ name=prompt_config['name'],
+ suite='should-trigger' if should_trigger else 'should-not-trigger',
+ tier='routing',
+ passed=False,
+ duration_ms=result.duration,
+ cost_usd=result.cost_estimate.estimated_cost,
+ exit_reason=result.exit_reason,
+ model=result.model,
+ error=f'Harness failure: {result.exit_reason}',
+ ))
+ assert False, f'Routing harness failed: {result.exit_reason}'
+
+ triggered = _did_use_seo_skill(result)
+ passed = triggered if should_trigger else not triggered
+ label = 'SHOULD' if should_trigger else 'SHOULD NOT'
+
+ if not passed:
+ print(
+ f"ROUTING FAIL: \"{prompt_config['name']}\" {label} have triggered seo-analysis "
+ f"but {'DID' if triggered else 'DID NOT'}",
+ file=sys.stderr,
+ )
+
+ if _collector:
+ _collector.add_test(EvalTestEntry(
+ name=prompt_config['name'],
+ suite='should-trigger' if should_trigger else 'should-not-trigger',
+ tier='routing',
+ passed=passed,
+ duration_ms=result.duration,
+ cost_usd=result.cost_estimate.estimated_cost,
+ should_trigger=should_trigger,
+ did_trigger=triggered,
+ exit_reason=result.exit_reason,
+ model=result.model,
+ output=result.output[:500] if result.output else None,
+ ))
+
+ assert triggered == should_trigger
+
+
[email protected](not _should_run('routing-seo-triggers'), reason='not selected')
+def test_routing_seo_triggers():
+ # Run all prompts before asserting so one failure doesn't hide the rest.
+ failures: list[str] = []
+ for p in SHOULD_TRIGGER:
+ try:
+ _run_routing_test(p, True)
+ except AssertionError as e:
+ failures.append(str(e))
+ if failures:
+ raise AssertionError('\n'.join(failures))
+
+
[email protected](not _should_run('routing-seo-non-triggers'), reason='not selected')
+def test_routing_seo_non_triggers():
+ # Run all prompts before asserting so one failure doesn't hide the rest.
+ failures: list[str] = []
+ for p in SHOULD_NOT_TRIGGER:
+ try:
+ _run_routing_test(p, False)
+ except AssertionError as e:
+ failures.append(str(e))
+ if failures:
+ raise AssertionError('\n'.join(failures))
+
+
+def teardown_module(module):
+ if _collector:
+ _collector.finalize()
+ for d in _tmp_dirs:
+ shutil.rmtree(d, ignore_errors=True)
diff --git a/test/unit/test_analyze_gsc.py b/test/unit/test_analyze_gsc.py
new file mode 100644
index 00000000..8053f31f
--- /dev/null
+++ b/test/unit/test_analyze_gsc.py
@@ -0,0 +1,958 @@
+"""
+Unit tests for seo-analysis/scripts/analyze_gsc.py
+
+Tests the pure logic functions — no GSC API calls, no gcloud needed.
+These run instantly and catch bugs in the data processing pipeline.
+
+Run: pytest test/unit/test_analyze_gsc.py -v
+"""
+
+import importlib.util
+import json
+import os
+import sys
+import unittest
+from datetime import date, timedelta
+from unittest.mock import MagicMock, patch
+
+# Load analyze_gsc.py as a module without executing main()
+_SCRIPT_PATH = os.path.join(
+ os.path.dirname(__file__), '..', '..', 'seo', 'seo-analysis', 'scripts', 'analyze_gsc.py'
+)
+spec = importlib.util.spec_from_file_location('analyze_gsc', _SCRIPT_PATH)
+gsc = importlib.util.module_from_spec(spec)
+# Don't run __main__ block
+spec.loader.exec_module(gsc)
+
+
+class TestDateRange(unittest.TestCase):
+ """date_range() returns the correct window with the 3-day GSC lag."""
+
+ def test_returns_two_strings(self):
+ start, end = gsc.date_range(90)
+ self.assertIsInstance(start, str)
+ self.assertIsInstance(end, str)
+
+ def test_end_is_three_days_ago(self):
+ _, end = gsc.date_range(90)
+ expected_end = (date.today() - timedelta(days=3)).isoformat()
+ self.assertEqual(end, expected_end)
+
+ def test_start_is_days_before_end(self):
+ start, end = gsc.date_range(90)
+ start_d = date.fromisoformat(start)
+ end_d = date.fromisoformat(end)
+ delta = end_d - start_d
+ self.assertEqual(delta.days, 90)
+
+ def test_28_day_window(self):
+ start, end = gsc.date_range(28)
+ start_d = date.fromisoformat(start)
+ end_d = date.fromisoformat(end)
+ self.assertEqual((end_d - start_d).days, 28)
+
+ def test_custom_lag(self):
+ # With days_ago_end=7, end should be 7 days ago
+ _, end = gsc.date_range(90, days_ago_end=7)
+ expected = (date.today() - timedelta(days=7)).isoformat()
+ self.assertEqual(end, expected)
+
+
+class TestPositionBuckets(unittest.TestCase):
+ """Position bucket assignment must be correct at all boundary values."""
+
+ def _make_row(self, query, position, clicks=100, impressions=1000):
+ return {
+ 'keys': [query],
+ 'position': position,
+ 'clicks': clicks,
+ 'impressions': impressions,
+ 'ctr': clicks / impressions,
+ }
+
+ def _run_buckets(self, rows):
+ token = 'fake-token'
+ mock_data = {'rows': rows}
+
+ with patch.object(gsc, 'gsc_query', return_value=mock_data):
+ return gsc.pull_position_buckets(token, 'sc-domain:test.com', '2025-01-01', '2025-03-31')
+
+ def test_position_1_goes_to_1_3(self):
+ buckets = self._run_buckets([self._make_row('q1', 1.0)])
+ self.assertEqual(len(buckets['1-3']), 1)
+ self.assertEqual(buckets['1-3'][0]['query'], 'q1')
+
+ def test_position_3_goes_to_1_3(self):
+ buckets = self._run_buckets([self._make_row('q3', 3.0)])
+ self.assertEqual(len(buckets['1-3']), 1)
+
+ def test_position_3_point_9_goes_to_4_10(self):
+ # 3.9 average > 3, so it's in the 4-10 bucket
+ buckets = self._run_buckets([self._make_row('q4', 3.9)])
+ self.assertEqual(len(buckets['4-10']), 1)
+ self.assertEqual(len(buckets['1-3']), 0)
+
+ def test_position_4_goes_to_4_10(self):
+ buckets = self._run_buckets([self._make_row('q5', 4.0)])
+ self.assertEqual(len(buckets['4-10']), 1)
+
+ def test_position_10_goes_to_4_10(self):
+ buckets = self._run_buckets([self._make_row('q10', 10.0)])
+ self.assertEqual(len(buckets['4-10']), 1)
+
+ def test_position_10_point_1_goes_to_11_20(self):
+ buckets = self._run_buckets([self._make_row('q11', 10.1)])
+ self.assertEqual(len(buckets['11-20']), 1)
+ self.assertEqual(len(buckets['4-10']), 0)
+
+ def test_position_20_goes_to_11_20(self):
+ buckets = self._run_buckets([self._make_row('q20', 20.0)])
+ self.assertEqual(len(buckets['11-20']), 1)
+
+ def test_position_21_goes_to_21_plus(self):
+ buckets = self._run_buckets([self._make_row('q21', 21.0)])
+ self.assertEqual(len(buckets['21+']), 1)
+
+ def test_position_50_goes_to_21_plus(self):
+ buckets = self._run_buckets([self._make_row('q50', 50.0)])
+ self.assertEqual(len(buckets['21+']), 1)
+
+ def test_mixed_positions_distributed_correctly(self):
+ rows = [
+ self._make_row('a', 1.5), # 1-3
+ self._make_row('b', 3.5), # 4-10
+ self._make_row('c', 7.2), # 4-10
+ self._make_row('d', 15.0), # 11-20
+ self._make_row('e', 25.0), # 21+
+ ]
+ buckets = self._run_buckets(rows)
+ self.assertEqual(len(buckets['1-3']), 1)
+ self.assertEqual(len(buckets['4-10']), 2)
+ self.assertEqual(len(buckets['11-20']), 1)
+ self.assertEqual(len(buckets['21+']), 1)
+
+ def test_empty_input_returns_empty_buckets(self):
+ buckets = self._run_buckets([])
+ for bucket in buckets.values():
+ self.assertEqual(len(bucket), 0)
+
+ def test_bucket_entries_have_correct_fields(self):
+ buckets = self._run_buckets([self._make_row('test', 5.0, clicks=50, impressions=500)])
+ entry = buckets['4-10'][0]
+ self.assertIn('query', entry)
+ self.assertIn('clicks', entry)
+ self.assertIn('impressions', entry)
+ self.assertIn('ctr', entry)
+ self.assertIn('position', entry)
+ self.assertEqual(entry['query'], 'test')
+ self.assertEqual(entry['clicks'], 50)
+
+ def test_ctr_is_rounded_to_2_decimals(self):
+ # ctr = 50/500 = 0.1 = 10.0%
+ buckets = self._run_buckets([self._make_row('ctr-test', 5.0, clicks=50, impressions=500)])
+ entry = buckets['4-10'][0]
+ self.assertEqual(entry['ctr'], 10.0)
+
+
+class TestCtrOpportunities(unittest.TestCase):
+ """CTR opportunity filtering: impressions > 500, ctr < 3.0%, position ≤ 20."""
+
+ def _make_query(self, impressions, ctr, position):
+ return {
+ 'query': f'q-{impressions}-{ctr}-{position}',
+ 'clicks': int(impressions * ctr / 100),
+ 'impressions': impressions,
+ 'ctr': ctr,
+ 'position': position,
+ }
+
+ def _get_opportunities(self, queries):
+ """Replicate the CTR opportunity filtering logic from analyze_gsc.main()."""
+ return [
+ q for q in queries
+ if q['impressions'] > 500 and q['ctr'] < 3.0 and q['position'] <= 20
+ ]
+
+ def test_qualifies_when_all_criteria_met(self):
+ q = self._make_query(impressions=1000, ctr=2.5, position=8)
+ opps = self._get_opportunities([q])
+ self.assertEqual(len(opps), 1)
+
+ def test_excluded_when_impressions_too_low(self):
+ q = self._make_query(impressions=400, ctr=2.5, position=8)
+ opps = self._get_opportunities([q])
+ self.assertEqual(len(opps), 0)
+
+ def test_excluded_when_ctr_too_high(self):
+ q = self._make_query(impressions=1000, ctr=3.5, position=8)
+ opps = self._get_opportunities([q])
+ self.assertEqual(len(opps), 0)
+
+ def test_excluded_when_position_too_deep(self):
+ q = self._make_query(impressions=1000, ctr=2.5, position=21)
+ opps = self._get_opportunities([q])
+ self.assertEqual(len(opps), 0)
+
+ def test_boundary_impressions_501(self):
+ q = self._make_query(impressions=501, ctr=2.5, position=8)
+ opps = self._get_opportunities([q])
+ self.assertEqual(len(opps), 1)
+
+ def test_boundary_impressions_500_excluded(self):
+ q = self._make_query(impressions=500, ctr=2.5, position=8)
+ opps = self._get_opportunities([q])
+ self.assertEqual(len(opps), 0)
+
+ def test_boundary_position_20_included(self):
+ q = self._make_query(impressions=1000, ctr=2.5, position=20)
+ opps = self._get_opportunities([q])
+ self.assertEqual(len(opps), 1)
+
+ def test_boundary_ctr_exactly_3_excluded(self):
+ q = self._make_query(impressions=1000, ctr=3.0, position=8)
+ opps = self._get_opportunities([q])
+ self.assertEqual(len(opps), 0)
+
+ def test_ctr_2_99_included(self):
+ q = self._make_query(impressions=1000, ctr=2.99, position=8)
+ opps = self._get_opportunities([q])
+ self.assertEqual(len(opps), 1)
+
+
+class TestPeriodComparison(unittest.TestCase):
+ """Period comparison drop detection thresholds."""
+
+ def _make_row(self, key, clicks):
+ return {'keys': [key], 'clicks': clicks, 'impressions': clicks * 10,
+ 'ctr': 0.1, 'position': 5.0}
+
+ def _run_comparison(self, curr_pages, prev_pages, curr_queries, prev_queries):
+ """Patch gsc_query to return controlled data, run pull_period_comparison."""
+ call_count = {'n': 0}
+
+ def fake_query(token, site, body):
+ n = call_count['n']
+ call_count['n'] += 1
+ # Calls: curr_pages, prev_pages, curr_queries, prev_queries
+ if n == 0: return {'rows': [self._make_row(k, v) for k, v in curr_pages.items()]}
+ if n == 1: return {'rows': [self._make_row(k, v) for k, v in prev_pages.items()]}
+ if n == 2: return {'rows': [self._make_row(k, v) for k, v in curr_queries.items()]}
+ if n == 3: return {'rows': [self._make_row(k, v) for k, v in prev_queries.items()]}
+ return {'rows': []}
+
+ with patch.object(gsc, 'gsc_query', side_effect=fake_query):
+ return gsc.pull_period_comparison('fake-token', 'sc-domain:test.com', 28)
+
+ def test_page_drop_above_20pct_flagged(self):
+ result = self._run_comparison(
+ curr_pages={'/blog/post': 50},
+ prev_pages={'/blog/post': 100}, # -50% drop
+ curr_queries={},
+ prev_queries={},
+ )
+ self.assertEqual(len(result['declining_pages']), 1)
+ self.assertEqual(result['declining_pages'][0]['page'], '/blog/post')
+
+ def test_page_drop_below_20pct_not_flagged(self):
+ result = self._run_comparison(
+ curr_pages={'/blog/post': 85},
+ prev_pages={'/blog/post': 100}, # -15% drop (< 20% threshold)
+ curr_queries={},
+ prev_queries={},
+ )
+ self.assertEqual(len(result['declining_pages']), 0)
+
+ def test_page_with_low_previous_clicks_not_flagged(self):
+ # prev_clicks must be > 10 to be flagged (avoids noise from low-traffic pages)
+ result = self._run_comparison(
+ curr_pages={'/low-traffic': 3},
+ prev_pages={'/low-traffic': 8}, # -62.5% but prev < 10
+ curr_queries={},
+ prev_queries={},
+ )
+ self.assertEqual(len(result['declining_pages']), 0)
+
+ def test_query_drop_above_25pct_flagged(self):
+ result = self._run_comparison(
+ curr_pages={},
+ prev_pages={},
+ curr_queries={'keyword phrase': 30},
+ prev_queries={'keyword phrase': 60}, # -50% drop
+ )
+ self.assertEqual(len(result['declining_queries']), 1)
+
+ def test_query_drop_at_25pct_not_flagged(self):
+ result = self._run_comparison(
+ curr_pages={},
+ prev_pages={},
+ curr_queries={'keyword phrase': 75},
+ prev_queries={'keyword phrase': 100}, # exactly -25%
+ )
+ # -25% is not strictly < -25%, so should not be flagged
+ self.assertEqual(len(result['declining_queries']), 0)
+
+ def test_query_drop_below_threshold_not_flagged(self):
+ result = self._run_comparison(
+ curr_pages={},
+ prev_pages={},
+ curr_queries={'keyword phrase': 90},
+ prev_queries={'keyword phrase': 100}, # -10% drop
+ )
+ self.assertEqual(len(result['declining_queries']), 0)
+
+ def test_query_min_previous_clicks(self):
+ # prev_clicks must be > 5 to be flagged
+ result = self._run_comparison(
+ curr_pages={},
+ prev_pages={},
+ curr_queries={'rare query': 1},
+ prev_queries={'rare query': 4}, # -75% but prev ≤ 5
+ )
+ self.assertEqual(len(result['declining_queries']), 0)
+
+ def test_drop_pct_is_negative(self):
+ result = self._run_comparison(
+ curr_pages={'/page': 40},
+ prev_pages={'/page': 100},
+ curr_queries={},
+ prev_queries={},
+ )
+ self.assertLess(result['declining_pages'][0]['change_pct'], 0)
+
+ def test_result_sorted_by_change_pct_ascending(self):
+ result = self._run_comparison(
+ curr_pages={'/a': 20, '/b': 10},
+ prev_pages={'/a': 100, '/b': 100}, # /b drops more
+ curr_queries={},
+ prev_queries={},
+ )
+ pages = result['declining_pages']
+ if len(pages) >= 2:
+ self.assertLessEqual(pages[0]['change_pct'], pages[1]['change_pct'])
+
+
+class TestGscQueryErrorHandling(unittest.TestCase):
+ """gsc_query() returns empty rows on HTTP errors instead of crashing."""
+
+ def test_http_error_returns_empty_rows(self):
+ import urllib.error
+ with patch('urllib.request.urlopen', side_effect=urllib.error.HTTPError(
+ url='https://api.google.com', code=403, msg='Forbidden', hdrs=None, fp=None # type: ignore
+ )):
+ result = gsc.gsc_query('fake-token', 'sc-domain:test.com', {'dimensions': ['query']})
+ self.assertEqual(result, {'rows': []})
+
+ def test_url_error_returns_empty_rows(self):
+ import urllib.error
+ with patch('urllib.request.urlopen', side_effect=urllib.error.URLError('Network unreachable')):
+ result = gsc.gsc_query('fake-token', 'sc-domain:test.com', {'dimensions': ['query']})
+ self.assertEqual(result, {'rows': []})
+
+ def test_network_exception_returns_empty_rows(self):
+ mock_session = MagicMock()
+ mock_session.post.side_effect = Exception("Network unreachable")
+ result = gsc.gsc_query(mock_session, 'sc-domain:test.com', {'dimensions': ['query']})
+ self.assertEqual(result, {'rows': []})
+
+ def test_successful_response_parsed_correctly(self):
+ mock_body = json.dumps({
+ 'rows': [
+ {'keys': ['test query'], 'clicks': 100, 'impressions': 1000, 'ctr': 0.1, 'position': 5.0}
+ ]
+ }).encode()
+
+ mock_resp = MagicMock()
+ mock_resp.__enter__ = lambda s: s
+ mock_resp.__exit__ = MagicMock(return_value=False)
+ mock_resp.read.return_value = mock_body
+
+ with patch('urllib.request.urlopen', return_value=mock_resp):
+ result = gsc.gsc_query('fake-token', 'sc-domain:test.com', {'dimensions': ['query']})
+
+ self.assertEqual(len(result['rows']), 1)
+ self.assertEqual(result['rows'][0]['keys'][0], 'test query')
+
+
+class TestTopQueriesFormatting(unittest.TestCase):
+ """pull_top_queries() formats API response correctly."""
+
+ def test_rounds_position_to_one_decimal(self):
+ mock_data = {'rows': [
+ {'keys': ['test'], 'clicks': 50, 'impressions': 500, 'ctr': 0.1234, 'position': 4.567}
+ ]}
+ with patch.object(gsc, 'gsc_query', return_value=mock_data):
+ result = gsc.pull_top_queries('token', 'sc-domain:test.com', '2025-01-01', '2025-03-31')
+
+ self.assertEqual(result[0]['position'], 4.6)
+
+ def test_converts_ctr_to_percentage(self):
+ mock_data = {'rows': [
+ {'keys': ['test'], 'clicks': 100, 'impressions': 1000, 'ctr': 0.1, 'position': 3.0}
+ ]}
+ with patch.object(gsc, 'gsc_query', return_value=mock_data):
+ result = gsc.pull_top_queries('token', 'sc-domain:test.com', '2025-01-01', '2025-03-31')
+
+ # ctr 0.1 → 10.0%
+ self.assertEqual(result[0]['ctr'], 10.0)
+
+ def test_empty_response_returns_empty_list(self):
+ with patch.object(gsc, 'gsc_query', return_value={'rows': []}):
+ result = gsc.pull_top_queries('token', 'sc-domain:test.com', '2025-01-01', '2025-03-31')
+ self.assertEqual(result, [])
+
+ def test_missing_rows_returns_empty_list(self):
+ with patch.object(gsc, 'gsc_query', return_value={}):
+ result = gsc.pull_top_queries('token', 'sc-domain:test.com', '2025-01-01', '2025-03-31')
+ self.assertEqual(result, [])
+
+
+class TestGetAccessToken(unittest.TestCase):
+ """get_access_token() wraps gcloud and exits cleanly on failure."""
+
+ def test_returns_token_on_success(self):
+ mock_result = MagicMock()
+ mock_result.returncode = 0
+ mock_result.stdout = 'ya29.my-token\n'
+ with patch('subprocess.run', return_value=mock_result):
+ token = gsc.get_access_token()
+ self.assertEqual(token, 'ya29.my-token')
+
+ def test_exits_when_gcloud_not_found(self):
+ with patch('subprocess.run', side_effect=FileNotFoundError):
+ with self.assertRaises(SystemExit):
+ gsc.get_access_token()
+
+ def test_exits_when_gcloud_returns_nonzero(self):
+ mock_result = MagicMock()
+ mock_result.returncode = 1
+ mock_result.stdout = ''
+ with patch('subprocess.run', return_value=mock_result):
+ with self.assertRaises(SystemExit):
+ gsc.get_access_token()
+
+ def test_exits_when_gcloud_times_out(self):
+ import subprocess as sp
+ with patch('subprocess.run', side_effect=sp.TimeoutExpired(cmd='gcloud', timeout=15)):
+ with self.assertRaises(SystemExit):
+ gsc.get_access_token()
+
+ def test_exits_when_token_is_empty(self):
+ mock_result = MagicMock()
+ mock_result.returncode = 0
+ mock_result.stdout = ' \n' # whitespace only
+ with patch('subprocess.run', return_value=mock_result):
+ with self.assertRaises(SystemExit):
+ gsc.get_access_token()
+
+
+class TestDeriveCannibalization(unittest.TestCase):
+ """derive_cannibalization() finds queries where multiple pages compete."""
+
+ def _make_row(self, query, page, clicks, impressions, ctr=0.05, position=8.0):
+ return {'keys': [query, page], 'clicks': clicks, 'impressions': impressions,
+ 'ctr': ctr, 'position': position}
+
+ def test_single_page_per_query_not_flagged(self):
+ rows = [self._make_row('seo tips', '/blog/seo', 100, 1000)]
+ result = gsc.derive_cannibalization(rows)
+ self.assertEqual(len(result), 0)
+
+ def test_two_pages_same_query_flagged(self):
+ rows = [
+ self._make_row('seo tips', '/blog/seo', 100, 1000),
+ self._make_row('seo tips', '/guide/seo', 50, 800),
+ ]
+ result = gsc.derive_cannibalization(rows)
+ self.assertEqual(len(result), 1)
+ self.assertEqual(result[0]['query'], 'seo tips')
+
+ def test_competing_pages_sorted_by_position_asc(self):
+ rows = [
+ self._make_row('seo tips', '/blog/seo', 30, 500, position=8.0),
+ self._make_row('seo tips', '/guide/seo', 100, 800, position=3.0),
+ ]
+ result = gsc.derive_cannibalization(rows)
+ pages = result[0]['competing_pages']
+ self.assertEqual(pages[0]['page'], '/guide/seo') # best position first
+ self.assertEqual(pages[1]['page'], '/blog/seo')
+
+ def test_total_impressions_and_clicks_summed(self):
+ rows = [
+ self._make_row('keyword', '/a', 80, 900),
+ self._make_row('keyword', '/b', 40, 600),
+ ]
+ result = gsc.derive_cannibalization(rows)
+ self.assertEqual(result[0]['total_impressions'], 1500)
+ self.assertEqual(result[0]['total_clicks'], 120)
+
+ def test_min_impressions_filter(self):
+ rows = [
+ self._make_row('rare query', '/a', 5, 40),
+ self._make_row('rare query', '/b', 3, 30),
+ ]
+ # total impressions = 70, below default min of 100
+ result = gsc.derive_cannibalization(rows)
+ self.assertEqual(len(result), 0)
+
+ def test_min_impressions_at_boundary_included(self):
+ rows = [
+ self._make_row('edge query', '/a', 5, 60),
+ self._make_row('edge query', '/b', 3, 40),
+ ]
+ # total = 100, exactly at min_impressions threshold
+ result = gsc.derive_cannibalization(rows)
+ self.assertEqual(len(result), 1)
+
+ def test_results_sorted_by_total_impressions_desc(self):
+ rows = [
+ self._make_row('small', '/a', 10, 200),
+ self._make_row('small', '/b', 5, 150),
+ self._make_row('large', '/x', 50, 800),
+ self._make_row('large', '/y', 30, 600),
+ ]
+ result = gsc.derive_cannibalization(rows)
+ self.assertGreater(result[0]['total_impressions'], result[1]['total_impressions'])
+
+ def test_results_capped_at_30(self):
+ rows = []
+ for i in range(35):
+ rows.append(self._make_row(f'query-{i}', '/a', 50, 300))
+ rows.append(self._make_row(f'query-{i}', '/b', 30, 200))
+ result = gsc.derive_cannibalization(rows)
+ self.assertLessEqual(len(result), 30)
+
+ def test_empty_rows_returns_empty(self):
+ self.assertEqual(gsc.derive_cannibalization([]), [])
+
+ def test_competing_pages_have_correct_fields(self):
+ rows = [
+ self._make_row('test', '/a', 100, 1000, ctr=0.1, position=5.2),
+ self._make_row('test', '/b', 50, 800, ctr=0.06, position=9.1),
+ ]
+ result = gsc.derive_cannibalization(rows)
+ page = result[0]['competing_pages'][0]
+ self.assertIn('page', page)
+ self.assertIn('clicks', page)
+ self.assertIn('impressions', page)
+ self.assertIn('ctr', page)
+ self.assertIn('position', page)
+ self.assertEqual(page['ctr'], round(0.1 * 100, 2))
+
+ def test_winner_page_is_best_position(self):
+ rows = [
+ self._make_row('keyword', '/a', 50, 500, position=8.0),
+ self._make_row('keyword', '/b', 20, 400, position=3.0),
+ ]
+ result = gsc.derive_cannibalization(rows)
+ self.assertEqual(result[0]['winner_page'], '/b') # /b has position 3.0
+
+ def test_winner_tiebreaker_is_most_clicks(self):
+ rows = [
+ self._make_row('keyword', '/a', 80, 500, position=5.0),
+ self._make_row('keyword', '/b', 30, 400, position=5.0),
+ ]
+ result = gsc.derive_cannibalization(rows)
+ self.assertEqual(result[0]['winner_page'], '/a') # same position, /a has more clicks
+
+ def test_loser_pages_excludes_winner(self):
+ rows = [
+ self._make_row('kw', '/winner', 100, 800, position=2.0),
+ self._make_row('kw', '/loser1', 40, 400, position=7.0),
+ self._make_row('kw', '/loser2', 20, 300, position=9.0),
+ ]
+ result = gsc.derive_cannibalization(rows)
+ self.assertEqual(result[0]['winner_page'], '/winner')
+ self.assertIn('/loser1', result[0]['loser_pages'])
+ self.assertIn('/loser2', result[0]['loser_pages'])
+ self.assertNotIn('/winner', result[0]['loser_pages'])
+
+ def test_domination_flag_when_all_top5_close_positions(self):
+ rows = [
+ self._make_row('brand query', '/a', 100, 800, position=2.0),
+ self._make_row('brand query', '/b', 80, 600, position=3.5),
+ ]
+ result = gsc.derive_cannibalization(rows)
+ self.assertIn('domination', result[0]['recommended_action'])
+
+ def test_consolidate_recommended_when_positions_spread(self):
+ rows = [
+ self._make_row('keyword', '/a', 100, 800, position=2.0),
+ self._make_row('keyword', '/b', 30, 500, position=9.0),
+ ]
+ result = gsc.derive_cannibalization(rows)
+ self.assertIn('consolidate', result[0]['recommended_action'])
+
+ def test_winner_reason_shows_position_when_positions_differ(self):
+ rows = [
+ self._make_row('kw', '/a', 100, 800, position=3.0),
+ self._make_row('kw', '/b', 50, 600, position=7.0),
+ ]
+ result = gsc.derive_cannibalization(rows)
+ self.assertIn('winner_reason', result[0])
+ self.assertIn('3.0', result[0]['winner_reason'])
+ self.assertIn('position', result[0]['winner_reason'])
+
+ def test_winner_reason_shows_clicks_when_positions_tied(self):
+ rows = [
+ self._make_row('kw', '/a', 100, 800, position=5.0),
+ self._make_row('kw', '/b', 40, 600, position=5.0),
+ ]
+ result = gsc.derive_cannibalization(rows)
+ self.assertIn('clicks', result[0]['winner_reason'])
+ self.assertIn('100', result[0]['winner_reason'])
+
+
+class TestDeriveCtrGapsByPage(unittest.TestCase):
+ """derive_ctr_gaps_by_page() finds high-impression, low-CTR query+page pairs."""
+
+ def _make_row(self, query, page, impressions, ctr_decimal, position):
+ return {'keys': [query, page], 'clicks': int(impressions * ctr_decimal),
+ 'impressions': impressions, 'ctr': ctr_decimal, 'position': position}
+
+ def test_qualifies_when_all_criteria_met(self):
+ rows = [self._make_row('best seo tool', '/tools', 500, 0.02, 8)]
+ result = gsc.derive_ctr_gaps_by_page(rows)
+ self.assertEqual(len(result), 1)
+ self.assertEqual(result[0]['query'], 'best seo tool')
+ self.assertEqual(result[0]['page'], '/tools')
+
+ def test_excluded_when_impressions_below_min(self):
+ rows = [self._make_row('low traffic', '/page', 100, 0.02, 8)]
+ result = gsc.derive_ctr_gaps_by_page(rows)
+ self.assertEqual(len(result), 0)
+
+ def test_excluded_when_ctr_above_max(self):
+ rows = [self._make_row('good ctr', '/page', 500, 0.05, 8)]
+ # ctr_pct = 5.0, max is 3.0
+ result = gsc.derive_ctr_gaps_by_page(rows)
+ self.assertEqual(len(result), 0)
+
+ def test_excluded_when_position_too_deep(self):
+ rows = [self._make_row('deep ranking', '/page', 500, 0.02, 21)]
+ result = gsc.derive_ctr_gaps_by_page(rows)
+ self.assertEqual(len(result), 0)
+
+ def test_boundary_impressions_200_included(self):
+ rows = [self._make_row('edge', '/page', 200, 0.02, 8)]
+ result = gsc.derive_ctr_gaps_by_page(rows)
+ self.assertEqual(len(result), 1)
+
+ def test_boundary_impressions_199_excluded(self):
+ rows = [self._make_row('edge', '/page', 199, 0.02, 8)]
+ result = gsc.derive_ctr_gaps_by_page(rows)
+ self.assertEqual(len(result), 0)
+
+ def test_boundary_position_20_included(self):
+ rows = [self._make_row('edge position', '/page', 500, 0.02, 20)]
+ result = gsc.derive_ctr_gaps_by_page(rows)
+ self.assertEqual(len(result), 1)
+
+ def test_ctr_stored_as_percentage(self):
+ rows = [self._make_row('test', '/page', 500, 0.02, 8)]
+ result = gsc.derive_ctr_gaps_by_page(rows)
+ # 0.02 decimal → 2.0% stored
+ self.assertAlmostEqual(result[0]['ctr'], 2.0, places=1)
+
+ def test_sorted_by_impressions_desc(self):
+ rows = [
+ self._make_row('q1', '/a', 300, 0.02, 8),
+ self._make_row('q2', '/b', 1000, 0.01, 5),
+ ]
+ result = gsc.derive_ctr_gaps_by_page(rows)
+ self.assertGreater(result[0]['impressions'], result[1]['impressions'])
+
+ def test_results_capped_at_25(self):
+ rows = [self._make_row(f'q{i}', f'/page-{i}', 500, 0.02, 8) for i in range(30)]
+ result = gsc.derive_ctr_gaps_by_page(rows)
+ self.assertLessEqual(len(result), 25)
+
+ def test_empty_rows_returns_empty(self):
+ self.assertEqual(gsc.derive_ctr_gaps_by_page([]), [])
+
+ def test_output_includes_page_field(self):
+ rows = [self._make_row('kw', '/landing', 500, 0.02, 8)]
+ result = gsc.derive_ctr_gaps_by_page(rows)
+ self.assertEqual(result[0]['page'], '/landing')
+
+
+class TestPullCountrySplit(unittest.TestCase):
+ """pull_country_split() returns rows with CTR and position fields."""
+
+ def test_formats_rows_correctly(self):
+ mock_data = {'rows': [
+ {'keys': ['usa'], 'clicks': 500, 'impressions': 5000, 'ctr': 0.1, 'position': 4.2}
+ ]}
+ with patch.object(gsc, 'gsc_query', return_value=mock_data):
+ result = gsc.pull_country_split('token', 'sc-domain:test.com', '2025-01-01', '2025-03-31')
+ self.assertEqual(len(result), 1)
+ self.assertEqual(result[0]['country'], 'usa')
+ self.assertEqual(result[0]['ctr'], 10.0)
+ self.assertEqual(result[0]['position'], 4.2)
+
+ def test_empty_response_returns_empty_list(self):
+ with patch.object(gsc, 'gsc_query', return_value={'rows': []}):
+ result = gsc.pull_country_split('token', 'sc-domain:test.com', '2025-01-01', '2025-03-31')
+ self.assertEqual(result, [])
+
+ def test_ctr_converted_to_percentage(self):
+ mock_data = {'rows': [
+ {'keys': ['gbr'], 'clicks': 100, 'impressions': 1000, 'ctr': 0.05, 'position': 7.0}
+ ]}
+ with patch.object(gsc, 'gsc_query', return_value=mock_data):
+ result = gsc.pull_country_split('token', 'sc-domain:test.com', '2025-01-01', '2025-03-31')
+ self.assertEqual(result[0]['ctr'], 5.0)
+
+
+class TestPullSearchTypeSplit(unittest.TestCase):
+ """pull_search_type_split() only includes search types with clicks > 0."""
+
+ def test_excludes_zero_click_types(self):
+ def fake_query(token, site, body):
+ stype = body.get('type', 'web')
+ if stype == 'web':
+ return {'rows': [{'clicks': 1000, 'impressions': 50000, 'ctr': 0.02, 'position': 5.0}]}
+ return {'rows': [{}]} # empty rows → clicks defaults to 0
+
+ with patch.object(gsc, 'gsc_query', side_effect=fake_query):
+ result = gsc.pull_search_type_split('token', 'sc-domain:test.com', '2025-01-01', '2025-03-31')
+ self.assertEqual(len(result), 1)
+ self.assertEqual(result[0]['type'], 'web')
+
+ def test_includes_discover_when_traffic_exists(self):
+ def fake_query(token, site, body):
+ stype = body.get('type', 'web')
+ if stype == 'discover':
+ return {'rows': [{'clicks': 500, 'impressions': 20000, 'ctr': 0.025, 'position': 0.0}]}
+ return {'rows': [{}]}
+
+ with patch.object(gsc, 'gsc_query', side_effect=fake_query):
+ result = gsc.pull_search_type_split('token', 'sc-domain:test.com', '2025-01-01', '2025-03-31')
+ self.assertEqual(len(result), 1)
+ self.assertEqual(result[0]['type'], 'discover')
+
+ def test_sorted_by_clicks_desc(self):
+ def fake_query(token, site, body):
+ stype = body.get('type', 'web')
+ if stype == 'web':
+ return {'rows': [{'clicks': 5000, 'impressions': 100000, 'ctr': 0.05, 'position': 4.0}]}
+ if stype == 'image':
+ return {'rows': [{'clicks': 1000, 'impressions': 20000, 'ctr': 0.05, 'position': 3.0}]}
+ return {'rows': [{}]}
+
+ with patch.object(gsc, 'gsc_query', side_effect=fake_query):
+ result = gsc.pull_search_type_split('token', 'sc-domain:test.com', '2025-01-01', '2025-03-31')
+ self.assertEqual(result[0]['type'], 'web') # web has more clicks
+ self.assertGreater(result[0]['clicks'], result[1]['clicks'])
+
+ def test_all_zero_returns_empty_list(self):
+ with patch.object(gsc, 'gsc_query', return_value={'rows': [{}]}):
+ result = gsc.pull_search_type_split('token', 'sc-domain:test.com', '2025-01-01', '2025-03-31')
+ self.assertEqual(result, [])
+
+ def test_ctr_converted_to_percentage(self):
+ def fake_query(token, site, body):
+ if body.get('type') == 'web':
+ return {'rows': [{'clicks': 100, 'impressions': 1000, 'ctr': 0.1, 'position': 5.0}]}
+ return {'rows': [{}]}
+
+ with patch.object(gsc, 'gsc_query', side_effect=fake_query):
+ result = gsc.pull_search_type_split('token', 'sc-domain:test.com', '2025-01-01', '2025-03-31')
+ self.assertEqual(result[0]['ctr'], 10.0)
+
+
+class TestClassifyBranded(unittest.TestCase):
+ """classify_branded() detects brand terms case-insensitively."""
+
+ def test_exact_match(self):
+ self.assertTrue(gsc.classify_branded('acme pricing', ['acme']))
+
+ def test_case_insensitive(self):
+ self.assertTrue(gsc.classify_branded('Acme Corp pricing', ['acme']))
+
+ def test_brand_uppercase_term(self):
+ self.assertTrue(gsc.classify_branded('acmecorp review', ['AcmeCorp']))
+
+ def test_non_branded_query(self):
+ self.assertFalse(gsc.classify_branded('best seo tools', ['acme']))
+
+ def test_empty_brand_terms_returns_false(self):
+ self.assertFalse(gsc.classify_branded('acme pricing', []))
+
+ def test_none_brand_terms_returns_false(self):
+ self.assertFalse(gsc.classify_branded('acme pricing', None))
+
+ def test_multiple_brand_terms_any_match(self):
+ self.assertTrue(gsc.classify_branded('toprank seo tool', ['acme', 'toprank']))
+
+ def test_multiple_brand_terms_none_match(self):
+ self.assertFalse(gsc.classify_branded('best content marketing', ['acme', 'toprank']))
+
+ def test_partial_word_match(self):
+ # "acmecorp" contains "acme" — should match
+ self.assertTrue(gsc.classify_branded('acmecorp login', ['acme']))
+
+
+class TestDeriveBrandedSplit(unittest.TestCase):
+ """derive_branded_split() aggregates qp_rows into branded vs non-branded segments."""
+
+ def _make_row(self, query, page, clicks, impressions, position=5.0):
+ return {'keys': [query, page], 'clicks': clicks, 'impressions': impressions,
+ 'ctr': clicks / impressions, 'position': position}
+
+ def test_returns_none_when_no_brand_terms(self):
+ rows = [self._make_row('acme pricing', '/pricing', 100, 1000)]
+ self.assertIsNone(gsc.derive_branded_split(rows, []))
+
+ def test_returns_none_when_brand_terms_is_none(self):
+ rows = [self._make_row('acme pricing', '/pricing', 100, 1000)]
+ self.assertIsNone(gsc.derive_branded_split(rows, None))
+
+ def test_splits_into_branded_and_non_branded(self):
+ rows = [
+ self._make_row('acme pricing', '/pricing', 100, 1000),
+ self._make_row('seo tools', '/blog', 50, 800),
+ ]
+ result = gsc.derive_branded_split(rows, ['acme'])
+ self.assertEqual(result['branded']['clicks'], 100)
+ self.assertEqual(result['non_branded']['clicks'], 50)
+
+ def test_branded_impressions_correct(self):
+ rows = [
+ self._make_row('acme login', '/login', 200, 2000),
+ self._make_row('acme pricing', '/pricing', 100, 1000),
+ ]
+ result = gsc.derive_branded_split(rows, ['acme'])
+ self.assertEqual(result['branded']['impressions'], 3000)
+
+ def test_query_count_correct(self):
+ rows = [
+ self._make_row('acme tool', '/a', 50, 500),
+ self._make_row('generic query', '/b', 30, 300),
+ self._make_row('another generic', '/c', 20, 200),
+ ]
+ result = gsc.derive_branded_split(rows, ['acme'])
+ self.assertEqual(result['branded']['query_count'], 1)
+ self.assertEqual(result['non_branded']['query_count'], 2)
+
+ def test_same_query_multiple_pages_deduped(self):
+ # Same query on two pages → only 1 unique query, but clicks/impressions summed
+ rows = [
+ self._make_row('acme tool', '/a', 50, 500),
+ self._make_row('acme tool', '/b', 30, 300),
+ ]
+ result = gsc.derive_branded_split(rows, ['acme'])
+ self.assertEqual(result['branded']['query_count'], 1)
+ self.assertEqual(result['branded']['clicks'], 80)
+
+ def test_empty_segment_returns_zero_stats(self):
+ rows = [self._make_row('generic query', '/page', 100, 1000)]
+ result = gsc.derive_branded_split(rows, ['acme'])
+ self.assertEqual(result['branded']['clicks'], 0)
+ self.assertEqual(result['branded']['query_count'], 0)
+ self.assertEqual(result['branded']['top_queries'], [])
+
+ def test_top_queries_sorted_by_impressions(self):
+ rows = [
+ self._make_row('acme cheap', '/a', 10, 200),
+ self._make_row('acme popular', '/b', 50, 5000),
+ ]
+ result = gsc.derive_branded_split(rows, ['acme'])
+ top = result['branded']['top_queries']
+ self.assertEqual(top[0]['query'], 'acme popular')
+
+ def test_ctr_computed_correctly(self):
+ # 200 clicks / 1000 impressions = 20.0%
+ rows = [self._make_row('acme', '/home', 200, 1000)]
+ result = gsc.derive_branded_split(rows, ['acme'])
+ self.assertAlmostEqual(result['branded']['ctr'], 20.0, places=1)
+
+
+class TestClusterPageGroups(unittest.TestCase):
+ """cluster_page_groups() groups pages by URL path pattern."""
+
+ def _make_page(self, page, clicks, impressions, position=5.0):
+ return {'page': page, 'clicks': clicks, 'impressions': impressions,
+ 'ctr': round(clicks / impressions * 100, 2), 'position': position}
+
+ def test_blog_pages_grouped(self):
+ pages = [self._make_page('https://example.com/blog/post-1', 100, 1000)]
+ result = gsc.cluster_page_groups(pages)
+ blog = next((g for g in result if g['group'] == 'blog'), None)
+ self.assertIsNotNone(blog)
+ self.assertEqual(blog['clicks'], 100)
+
+ def test_products_pages_grouped(self):
+ pages = [self._make_page('/products/widget', 50, 500)]
+ result = gsc.cluster_page_groups(pages)
+ products = next((g for g in result if g['group'] == 'products'), None)
+ self.assertIsNotNone(products)
+
+ def test_unmatched_pages_go_to_other(self):
+ pages = [self._make_page('/custom-path/something', 20, 200)]
+ result = gsc.cluster_page_groups(pages)
+ other = next((g for g in result if g['group'] == 'other'), None)
+ self.assertIsNotNone(other)
+ self.assertEqual(other['clicks'], 20)
+
+ def test_multiple_pages_same_group_aggregated(self):
+ pages = [
+ self._make_page('/blog/post-1', 100, 1000),
+ self._make_page('/blog/post-2', 80, 800),
+ ]
+ result = gsc.cluster_page_groups(pages)
+ blog = next((g for g in result if g['group'] == 'blog'), None)
+ self.assertEqual(blog['clicks'], 180)
+ self.assertEqual(blog['page_count'], 2)
+
+ def test_sorted_by_clicks_desc(self):
+ pages = [
+ self._make_page('/blog/post', 50, 500),
+ self._make_page('/products/item', 300, 3000),
+ ]
+ result = gsc.cluster_page_groups(pages)
+ self.assertGreater(result[0]['clicks'], result[1]['clicks'])
+
+ def test_empty_groups_not_returned(self):
+ pages = [self._make_page('/blog/post', 100, 1000)]
+ result = gsc.cluster_page_groups(pages)
+ groups_with_pages = [g for g in result if g['page_count'] > 0]
+ self.assertEqual(len(result), len(groups_with_pages))
+
+ def test_empty_pages_returns_empty(self):
+ self.assertEqual(gsc.cluster_page_groups([]), [])
+
+ def test_ctr_computed_correctly(self):
+ # 100 clicks / 1000 impressions = 10%
+ pages = [self._make_page('/blog/post', 100, 1000)]
+ result = gsc.cluster_page_groups(pages)
+ blog = next(g for g in result if g['group'] == 'blog')
+ self.assertAlmostEqual(blog['ctr'], 10.0, places=1)
+
+ def test_position_is_weighted_average(self):
+ # Two blog posts: position 2.0 with 1000 imps, position 8.0 with 1000 imps → avg 5.0
+ pages = [
+ self._make_page('/blog/a', 100, 1000, position=2.0),
+ self._make_page('/blog/b', 80, 1000, position=8.0),
+ ]
+ result = gsc.cluster_page_groups(pages)
+ blog = next(g for g in result if g['group'] == 'blog')
+ self.assertAlmostEqual(blog['position'], 5.0, places=1)
+
+ def test_first_matching_group_wins(self):
+ # /blog/products/ could match both 'blog' and 'products' — first pattern wins
+ pages = [self._make_page('/blog/products/item', 100, 1000)]
+ result = gsc.cluster_page_groups(pages)
+ matched_groups = [g['group'] for g in result if g['page_count'] > 0]
+ # Should only be in one group
+ self.assertEqual(len([g for g in result if g['page_count'] > 0 and g['group'] in ('blog', 'products')]), 1)
+
+ def test_custom_groups_override_defaults(self):
+ custom = [("guides", r"/guide/")]
+ pages = [self._make_page('/guide/seo-basics', 100, 1000)]
+ result = gsc.cluster_page_groups(pages, groups=custom)
+ guides = next((g for g in result if g['group'] == 'guides'), None)
+ self.assertIsNotNone(guides)
+
+
+if __name__ == '__main__':
+ unittest.main()
diff --git a/test/unit/test_cms_scripts.py b/test/unit/test_cms_scripts.py
new file mode 100644
index 00000000..798fec4c
--- /dev/null
+++ b/test/unit/test_cms_scripts.py
@@ -0,0 +1,548 @@
+"""
+Unit tests for WordPress, Contentful, and Ghost integration scripts.
+
+Tests pure logic functions — no API calls, no credentials needed.
+Covers SEO field extraction, entry normalisation, SEO audit, and
+SSRF protection for all three new CMS integrations.
+
+Run: pytest test/unit/test_cms_scripts.py -v
+"""
+
+import importlib.util
+import os
+import sys
+import unittest
+
+# ── Load scripts without executing main() ────────────────────────────────────
+
+def _load(name):
+ path = os.path.join(
+ os.path.dirname(__file__), '..', '..', 'seo', 'seo-analysis', 'scripts', name
+ )
+ spec = importlib.util.spec_from_file_location(name.replace('.py', ''), path)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ return mod
+
+
+wp_fetch = _load('fetch_wordpress_content.py')
+cf_fetch = _load('fetch_contentful_content.py')
+ghost_fetch = _load('fetch_ghost_content.py')
+cms_detect = _load('cms_detect.py')
+
+
+# ── cms_detect.py ─────────────────────────────────────────────────────────────
+
+class TestCmsDetectEnvParsing(unittest.TestCase):
+ """load_env_file() correctly parses .env file lines."""
+
+ def test_parses_simple_key_value(self):
+ import tempfile, os
+ with tempfile.NamedTemporaryFile(mode='w', suffix='.env', delete=False) as f:
+ f.write("WP_URL=https://example.com\n")
+ tmp = f.name
+ try:
+ result = cms_detect.load_env_file(tmp)
+ self.assertEqual(result.get("WP_URL"), "https://example.com")
+ finally:
+ os.unlink(tmp)
+
+ def test_strips_quotes(self):
+ import tempfile, os
+ with tempfile.NamedTemporaryFile(mode='w', suffix='.env', delete=False) as f:
+ f.write('WP_URL="https://quoted.com"\n')
+ tmp = f.name
+ try:
+ result = cms_detect.load_env_file(tmp)
+ self.assertEqual(result.get("WP_URL"), "https://quoted.com")
+ finally:
+ os.unlink(tmp)
+
+ def test_skips_comments(self):
+ import tempfile, os
+ with tempfile.NamedTemporaryFile(mode='w', suffix='.env', delete=False) as f:
+ f.write("# This is a comment\nWP_URL=https://example.com\n")
+ tmp = f.name
+ try:
+ result = cms_detect.load_env_file(tmp)
+ self.assertNotIn("# This is a comment", result)
+ self.assertIn("WP_URL", result)
+ finally:
+ os.unlink(tmp)
+
+ def test_skips_lines_without_equals(self):
+ import tempfile, os
+ with tempfile.NamedTemporaryFile(mode='w', suffix='.env', delete=False) as f:
+ f.write("JUST_A_VALUE\nWP_URL=https://example.com\n")
+ tmp = f.name
+ try:
+ result = cms_detect.load_env_file(tmp)
+ self.assertNotIn("JUST_A_VALUE", result)
+ finally:
+ os.unlink(tmp)
+
+ def test_missing_file_returns_empty(self):
+ result = cms_detect.load_env_file("/nonexistent/.env")
+ self.assertEqual(result, {})
+
+
+# ── fetch_wordpress_content.py ────────────────────────────────────────────────
+
+class TestWordPressExtractSeoFields(unittest.TestCase):
+ """extract_seo_fields() pulls SEO data from Yoast and RankMath."""
+
+ def _item(self, **kwargs):
+ return kwargs
+
+ def test_yoast_head_json_extracted(self):
+ item = {
+ "yoast_head_json": {
+ "title": "SEO Title | Site",
+ "description": "A 120-char meta description for this post.",
+ "og_image": [{"url": "https://example.com/img.jpg"}],
+ "og_title": "OG Title",
+ }
+ }
+ result = wp_fetch.extract_seo_fields(item)
+ self.assertEqual(result["meta_title"], "SEO Title | Site")
+ self.assertEqual(result["meta_description"], "A 120-char meta description for this post.")
+ self.assertTrue(result["has_meta_image"])
+ self.assertTrue(result["has_meta_social"])
+
+ def test_rank_math_meta_extracted_when_no_yoast(self):
+ item = {
+ "meta": {
+ "rank_math_title": "RankMath Title",
+ "rank_math_description": "RankMath description here.",
+ }
+ }
+ result = wp_fetch.extract_seo_fields(item)
+ self.assertEqual(result["meta_title"], "RankMath Title")
+ self.assertEqual(result["meta_description"], "RankMath description here.")
+
+ def test_yoast_takes_priority_over_rank_math(self):
+ item = {
+ "yoast_head_json": {"title": "Yoast Title", "description": "Yoast desc."},
+ "meta": {"rank_math_title": "RankMath Title"},
+ }
+ result = wp_fetch.extract_seo_fields(item)
+ self.assertEqual(result["meta_title"], "Yoast Title")
+
+ def test_no_seo_plugin_returns_empty_meta_title(self):
+ """Without Yoast or RankMath, meta_title should be empty — NOT the post title."""
+ item = {
+ "title": {"rendered": "Post Title"},
+ "yoast_head_json": None,
+ }
+ result = wp_fetch.extract_seo_fields(item)
+ self.assertEqual(result["meta_title"], "")
+ self.assertEqual(result["meta_description"], "")
+
+ def test_partial_yoast_missing_description(self):
+ item = {"yoast_head_json": {"title": "Title Only"}}
+ result = wp_fetch.extract_seo_fields(item)
+ self.assertEqual(result["meta_title"], "Title Only")
+ self.assertEqual(result["meta_description"], "")
+ self.assertFalse(result["has_meta_image"])
+ self.assertFalse(result["has_meta_social"])
+
+
+class TestWordPressNormaliseEntry(unittest.TestCase):
+ """normalise_entry() produces the shared CMS entry format."""
+
+ def _wp_item(self, **overrides):
+ base = {
+ "id": 123,
+ "slug": "hello-world",
+ "title": {"rendered": "Hello World"},
+ "date_gmt": "2024-01-15T10:00:00",
+ "modified_gmt": "2024-02-01T12:00:00",
+ "yoast_head_json": {
+ "title": "Hello World | Blog",
+ "description": "A short description for this post.",
+ },
+ }
+ base.update(overrides)
+ return base
+
+ def test_document_id_is_string(self):
+ result = wp_fetch.normalise_entry(self._wp_item())
+ self.assertEqual(result["document_id"], "123")
+ self.assertIsInstance(result["document_id"], str)
+
+ def test_slug_extracted(self):
+ result = wp_fetch.normalise_entry(self._wp_item())
+ self.assertEqual(result["slug"], "hello-world")
+
+ def test_seo_fields_extracted(self):
+ result = wp_fetch.normalise_entry(self._wp_item())
+ self.assertEqual(result["seo"]["meta_title"], "Hello World | Blog")
+ self.assertFalse(result["missing_meta_title"])
+
+ def test_missing_meta_title_flagged(self):
+ item = self._wp_item()
+ item.pop("yoast_head_json")
+ result = wp_fetch.normalise_entry(item)
+ self.assertTrue(result["missing_meta_title"])
+ # Must not fall back to post title
+ self.assertEqual(result["seo"]["meta_title"], "")
+
+ def test_meta_title_too_long_flagged(self):
+ item = self._wp_item()
+ item["yoast_head_json"]["title"] = "A" * 61
+ result = wp_fetch.normalise_entry(item)
+ self.assertTrue(result["meta_title_too_long"])
+
+ def test_meta_title_exactly_60_not_flagged(self):
+ item = self._wp_item()
+ item["yoast_head_json"]["title"] = "A" * 60
+ result = wp_fetch.normalise_entry(item)
+ self.assertFalse(result["meta_title_too_long"])
+
+ def test_meta_description_too_short_flagged(self):
+ item = self._wp_item()
+ item["yoast_head_json"]["description"] = "Too short."
+ result = wp_fetch.normalise_entry(item)
+ self.assertTrue(result["meta_description_too_short"])
+
+ def test_meta_description_too_long_flagged(self):
+ item = self._wp_item()
+ item["yoast_head_json"]["description"] = "A" * 161
+ result = wp_fetch.normalise_entry(item)
+ self.assertTrue(result["meta_description_too_long"])
+
+ def test_meta_description_in_range_not_flagged(self):
+ item = self._wp_item()
+ item["yoast_head_json"]["description"] = "A" * 100
+ result = wp_fetch.normalise_entry(item)
+ self.assertFalse(result["meta_description_too_short"])
+ self.assertFalse(result["meta_description_too_long"])
+
+
+class TestWordPressSeoAudit(unittest.TestCase):
+ """build_seo_audit() correctly counts SEO issues across entries."""
+
+ def _entry(self, meta_title="", meta_description=""):
+ tlen = len(meta_title)
+ dlen = len(meta_description)
+ return {
+ "document_id": "1",
+ "title": "Post",
+ "slug": "post",
+ "seo": {"meta_title": meta_title, "meta_description": meta_description},
+ "missing_meta_title": not meta_title,
+ "missing_meta_description": not meta_description,
+ "meta_title_too_long": tlen > 60,
+ "meta_description_too_long": dlen > 160,
+ "meta_description_too_short": 0 < dlen < 70,
+ }
+
+ def test_complete_entry_counted(self):
+ entries = [self._entry("Good Title", "A" * 100)]
+ audit = wp_fetch.build_seo_audit(entries)
+ self.assertEqual(audit["complete_seo"], 1)
+ self.assertEqual(audit["missing_meta_title"], 0)
+
+ def test_missing_title_counted(self):
+ entries = [self._entry("", "A" * 100)]
+ audit = wp_fetch.build_seo_audit(entries)
+ self.assertEqual(audit["missing_meta_title"], 1)
+ self.assertEqual(audit["complete_seo"], 0)
+
+ def test_multiple_issues_on_same_entry_counts_once_in_complete(self):
+ entries = [self._entry("", "")] # missing both
+ audit = wp_fetch.build_seo_audit(entries)
+ self.assertEqual(audit["missing_meta_title"], 1)
+ self.assertEqual(audit["missing_meta_description"], 1)
+ self.assertEqual(audit["complete_seo"], 0) # only 1 broken entry, not 2
+
+
+# ── fetch_contentful_content.py ───────────────────────────────────────────────
+
+class TestContentfulExtractSeoFields(unittest.TestCase):
+ """extract_seo_fields() handles Contentful SEO patterns."""
+
+ def test_direct_seo_fields_extracted(self):
+ fields = {"seoTitle": "Contentful SEO Title", "seoDescription": "A good description here."}
+ result = cf_fetch.extract_seo_fields(fields, {})
+ self.assertEqual(result["meta_title"], "Contentful SEO Title")
+ self.assertEqual(result["meta_description"], "A good description here.")
+
+ def test_meta_title_field_names(self):
+ for key in ("metaTitle", "seoTitle", "seo_title", "meta_title"):
+ with self.subTest(key=key):
+ fields = {key: f"Title via {key}"}
+ result = cf_fetch.extract_seo_fields(fields, {})
+ self.assertEqual(result["meta_title"], f"Title via {key}")
+
+ def test_meta_description_field_names(self):
+ for key in ("metaDescription", "seoDescription", "seo_description", "meta_description"):
+ with self.subTest(key=key):
+ fields = {key: f"Desc via {key}"}
+ result = cf_fetch.extract_seo_fields(fields, {})
+ self.assertEqual(result["meta_description"], f"Desc via {key}")
+
+ def test_linked_seo_entry_resolved(self):
+ """fields.seo link → resolved entry with title/description."""
+ seo_entry_id = "seo123"
+ fields = {
+ "seo": {"sys": {"type": "Link", "linkType": "Entry", "id": seo_entry_id}}
+ }
+ includes_by_id = {
+ seo_entry_id: {
+ "fields": {
+ "title": "Linked SEO Title",
+ "description": "Linked SEO description text here.",
+ }
+ }
+ }
+ result = cf_fetch.extract_seo_fields(fields, includes_by_id)
+ self.assertEqual(result["meta_title"], "Linked SEO Title")
+ self.assertEqual(result["meta_description"], "Linked SEO description text here.")
+
+ def test_linked_seo_entry_not_in_includes_returns_empty(self):
+ """If the linked entry isn't in includes, fall through gracefully."""
+ fields = {
+ "seo": {"sys": {"type": "Link", "linkType": "Entry", "id": "missing-id"}}
+ }
+ result = cf_fetch.extract_seo_fields(fields, {})
+ self.assertEqual(result["meta_title"], "")
+ self.assertEqual(result["meta_description"], "")
+
+ def test_no_seo_fields_returns_empty_meta_title(self):
+ """When no explicit SEO fields exist, meta_title must be empty — not the content title.
+ An entry using only its content title should be flagged as missing_meta_title=True."""
+ fields = {"title": "Content Title Only"}
+ result = cf_fetch.extract_seo_fields(fields, {})
+ self.assertEqual(result["meta_title"], "")
+
+ def test_no_fields_returns_empty(self):
+ result = cf_fetch.extract_seo_fields({}, {})
+ self.assertEqual(result["meta_title"], "")
+ self.assertEqual(result["meta_description"], "")
+
+
+class TestContentfulNormaliseEntry(unittest.TestCase):
+ """normalise_entry() maps Contentful entry shape to shared format."""
+
+ def _cf_item(self, **field_overrides):
+ fields = {
+ "title": "My Article",
+ "slug": "my-article",
+ "seoTitle": "My Article | Brand",
+ "seoDescription": "A" * 100,
+ **field_overrides,
+ }
+ return {
+ "sys": {
+ "id": "cf123",
+ "createdAt": "2024-01-01T00:00:00Z",
+ "updatedAt": "2024-02-01T00:00:00Z",
+ "locale": "en-US",
+ },
+ "fields": fields,
+ }
+
+ def test_document_id_from_sys_id(self):
+ result = cf_fetch.normalise_entry(self._cf_item(), {})
+ self.assertEqual(result["document_id"], "cf123")
+
+ def test_slug_extracted(self):
+ result = cf_fetch.normalise_entry(self._cf_item(), {})
+ self.assertEqual(result["slug"], "my-article")
+
+ def test_seo_title_extracted(self):
+ result = cf_fetch.normalise_entry(self._cf_item(), {})
+ self.assertEqual(result["seo"]["meta_title"], "My Article | Brand")
+ self.assertFalse(result["missing_meta_title"])
+
+ def test_missing_seo_title_flagged(self):
+ result = cf_fetch.normalise_entry(self._cf_item(seoTitle=None), {})
+ self.assertTrue(result["missing_meta_title"])
+
+ def test_locale_from_sys(self):
+ result = cf_fetch.normalise_entry(self._cf_item(), {})
+ self.assertEqual(result["locale"], "en-US")
+
+ def test_url_field_used_as_slug_fallback(self):
+ item = self._cf_item()
+ del item["fields"]["slug"]
+ item["fields"]["url"] = "/my-url"
+ result = cf_fetch.normalise_entry(item, {})
+ self.assertEqual(result["slug"], "/my-url")
+
+
+# ── fetch_ghost_content.py ────────────────────────────────────────────────────
+
+class TestGhostNormaliseEntry(unittest.TestCase):
+ """normalise_entry() maps Ghost post/page to shared format."""
+
+ def _ghost_item(self, **overrides):
+ base = {
+ "id": "ghost-id-abc",
+ "title": "My Ghost Post",
+ "slug": "my-ghost-post",
+ "published_at": "2024-01-15T10:00:00.000Z",
+ "updated_at": "2024-02-01T12:00:00.000Z",
+ "meta_title": "Ghost SEO Title | Brand",
+ "meta_description": "A" * 100,
+ "og_image": "https://example.com/og.jpg",
+ "og_title": "OG Title",
+ }
+ base.update(overrides)
+ return base
+
+ def test_document_id_from_id(self):
+ result = ghost_fetch.normalise_entry(self._ghost_item())
+ self.assertEqual(result["document_id"], "ghost-id-abc")
+
+ def test_slug_extracted(self):
+ result = ghost_fetch.normalise_entry(self._ghost_item())
+ self.assertEqual(result["slug"], "my-ghost-post")
+
+ def test_meta_title_extracted(self):
+ result = ghost_fetch.normalise_entry(self._ghost_item())
+ self.assertEqual(result["seo"]["meta_title"], "Ghost SEO Title | Brand")
+ self.assertFalse(result["missing_meta_title"])
+
+ def test_null_meta_title_flagged_as_missing(self):
+ """Ghost returns null for meta_title when not set — must flag as missing."""
+ item = self._ghost_item(meta_title=None)
+ result = ghost_fetch.normalise_entry(item)
+ self.assertTrue(result["missing_meta_title"])
+ # Must NOT fall back to the post title
+ self.assertEqual(result["seo"]["meta_title"], "")
+
+ def test_og_image_detected(self):
+ result = ghost_fetch.normalise_entry(self._ghost_item())
+ self.assertTrue(result["seo"]["has_meta_image"])
+
+ def test_no_og_image(self):
+ item = self._ghost_item(og_image=None)
+ result = ghost_fetch.normalise_entry(item)
+ self.assertFalse(result["seo"]["has_meta_image"])
+
+ def test_og_title_marks_has_meta_social(self):
+ result = ghost_fetch.normalise_entry(self._ghost_item())
+ self.assertTrue(result["seo"]["has_meta_social"])
+
+ def test_no_social_fields(self):
+ item = self._ghost_item(og_title=None, og_image=None)
+ # twitter_title not in item either
+ result = ghost_fetch.normalise_entry(item)
+ self.assertFalse(result["seo"]["has_meta_social"])
+
+ def test_meta_title_too_long_flagged(self):
+ item = self._ghost_item(meta_title="A" * 61)
+ result = ghost_fetch.normalise_entry(item)
+ self.assertTrue(result["meta_title_too_long"])
+
+ def test_meta_description_too_short_flagged(self):
+ item = self._ghost_item(meta_description="Short.")
+ result = ghost_fetch.normalise_entry(item)
+ self.assertTrue(result["meta_description_too_short"])
+
+ def test_missing_meta_description_not_flagged_as_too_short(self):
+ """Empty description should be missing_meta_description=True, not too_short."""
+ item = self._ghost_item(meta_description=None)
+ result = ghost_fetch.normalise_entry(item)
+ self.assertTrue(result["missing_meta_description"])
+ self.assertFalse(result["meta_description_too_short"]) # 0 chars → not "too short"
+
+
+# ── SSRF protection (shared logic, tested via WordPress) ──────────────────────
+
+class TestSsrfProtection(unittest.TestCase):
+ """_is_private_ip() blocks loopback, RFC1918, link-local addresses."""
+
+ def test_loopback_blocked(self):
+ self.assertTrue(wp_fetch._is_private_ip("127.0.0.1"))
+ self.assertTrue(wp_fetch._is_private_ip("::1"))
+
+ def test_private_rfc1918_blocked(self):
+ self.assertTrue(wp_fetch._is_private_ip("10.0.0.1"))
+ self.assertTrue(wp_fetch._is_private_ip("192.168.1.1"))
+ self.assertTrue(wp_fetch._is_private_ip("172.16.0.1"))
+ self.assertTrue(wp_fetch._is_private_ip("172.31.255.255"))
+
+ def test_public_ip_allowed(self):
+ self.assertFalse(wp_fetch._is_private_ip("8.8.8.8"))
+ self.assertFalse(wp_fetch._is_private_ip("104.21.1.1"))
+
+ def test_invalid_ip_returns_false(self):
+ self.assertFalse(wp_fetch._is_private_ip("not-an-ip"))
+ self.assertFalse(wp_fetch._is_private_ip(""))
+
+
+# ── WordPress auth header ─────────────────────────────────────────────────────
+
+class TestWordPressAuthHeader(unittest.TestCase):
+ """make_auth_header() strips spaces from Application Passwords."""
+
+ def test_spaces_stripped_from_password(self):
+ header = wp_fetch.make_auth_header("admin", "xxxx xxxx xxxx xxxx")
+ import base64
+ decoded = base64.b64decode(header.split(" ")[1]).decode()
+ self.assertEqual(decoded, "admin:xxxxxxxxxxxxxxxx")
+
+ def test_password_without_spaces_unchanged(self):
+ header = wp_fetch.make_auth_header("user", "plainpassword")
+ import base64
+ decoded = base64.b64decode(header.split(" ")[1]).decode()
+ self.assertEqual(decoded, "user:plainpassword")
+
+ def test_header_is_basic_scheme(self):
+ header = wp_fetch.make_auth_header("u", "p")
+ self.assertTrue(header.startswith("Basic "))
+
+
+# ── SEO audit (Ghost, same logic as WordPress) ────────────────────────────────
+
+class TestGhostSeoAudit(unittest.TestCase):
+
+ def _entry(self, meta_title="", meta_description=""):
+ tlen = len(meta_title)
+ dlen = len(meta_description)
+ return {
+ "document_id": "1",
+ "title": "Post",
+ "slug": "post",
+ "seo": {"meta_title": meta_title, "meta_description": meta_description},
+ "missing_meta_title": not meta_title,
+ "missing_meta_description": not meta_description,
+ "meta_title_too_long": tlen > 60,
+ "meta_description_too_long": dlen > 160,
+ "meta_description_too_short": 0 < dlen < 70,
+ }
+
+ def test_empty_list_returns_zeroes(self):
+ audit = ghost_fetch.build_seo_audit([])
+ self.assertEqual(audit["total"], 0)
+ self.assertEqual(audit["complete_seo"], 0)
+ self.assertEqual(audit["missing_meta_title"], 0)
+
+ def test_all_complete_returns_full_count(self):
+ entries = [self._entry("Good Title", "A" * 100) for _ in range(5)]
+ audit = ghost_fetch.build_seo_audit(entries)
+ self.assertEqual(audit["complete_seo"], 5)
+ self.assertEqual(audit["missing_meta_title"], 0)
+
+ def test_mixed_entries_correctly_counted(self):
+ # Each entry needs a unique document_id — build_seo_audit uses a set of
+ # broken IDs to count complete entries, so duplicate IDs would collapse.
+ entries = [
+ {**self._entry("Title", "A" * 100), "document_id": "1"}, # complete
+ {**self._entry("", "A" * 100), "document_id": "2"}, # missing title
+ {**self._entry("Title", ""), "document_id": "3"}, # missing desc
+ {**self._entry("A" * 61, "A" * 100), "document_id": "4"}, # title too long
+ ]
+ audit = ghost_fetch.build_seo_audit(entries)
+ self.assertEqual(audit["total"], 4)
+ self.assertEqual(audit["complete_seo"], 1)
+ self.assertEqual(audit["missing_meta_title"], 1)
+ self.assertEqual(audit["missing_meta_description"], 1)
+ self.assertEqual(audit["meta_title_too_long"], 1)
+
+
+if __name__ == "__main__":
+ unittest.main(verbosity=2)
diff --git a/test/unit/test_strapi_scripts.py b/test/unit/test_strapi_scripts.py
new file mode 100644
index 00000000..e0cce0dd
--- /dev/null
+++ b/test/unit/test_strapi_scripts.py
@@ -0,0 +1,414 @@
+"""
+Unit tests for Strapi integration scripts.
+
+Tests pure logic functions — no Strapi API calls, no credentials needed.
+Covers version detection, entry normalisation, SEO audit, payload building,
+SSRF protection, and stale-write guard.
+
+Run: pytest test/unit/test_strapi_scripts.py -v
+"""
+
+import importlib.util
+import json
+import os
+import sys
+import unittest
+
+# ── Load scripts without executing main() ────────────────────────────────────
+
+def _load(name):
+ path = os.path.join(
+ os.path.dirname(__file__), '..', '..', 'seo', 'seo-analysis', 'scripts', name
+ )
+ spec = importlib.util.spec_from_file_location(name.replace('.py', ''), path)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ return mod
+
+
+fetch = _load('fetch_strapi_content.py')
+push = _load('push_strapi_seo.py')
+preflight = _load('preflight_strapi.py')
+
+
+# ── fetch_strapi_content.py ───────────────────────────────────────────────────
+
+class TestDetectVersionFetch(unittest.TestCase):
+ """detect_version() in fetch_strapi_content: explicit hint overrides response."""
+
+ def test_explicit_v4_hint(self):
+ data = {"data": [{"id": 1, "attributes": {"title": "x"}}]}
+ self.assertEqual(fetch.detect_version(data, "4"), 4)
+
+ def test_explicit_v5_hint(self):
+ data = {"data": [{"id": 1, "attributes": {"title": "x"}}]}
+ self.assertEqual(fetch.detect_version(data, "5"), 5)
+
+ def test_infer_v4_from_attributes_key(self):
+ data = {"data": [{"id": 1, "attributes": {"title": "x"}}]}
+ self.assertEqual(fetch.detect_version(data, ""), 4)
+
+ def test_infer_v5_from_flat_item(self):
+ data = {"data": [{"id": 1, "title": "x", "documentId": "abc"}]}
+ self.assertEqual(fetch.detect_version(data, ""), 5)
+
+ def test_empty_collection_defaults_to_v5(self):
+ data = {"data": []}
+ self.assertEqual(fetch.detect_version(data, ""), 5)
+
+ def test_missing_data_key_defaults_to_v5(self):
+ data = {}
+ self.assertEqual(fetch.detect_version(data, ""), 5)
+
+
+class TestExtractSeoComponent(unittest.TestCase):
+ """extract_seo_component() normalises plugin-seo data."""
+
+ def test_returns_empty_dict_for_none(self):
+ result = fetch.extract_seo_component(None)
+ self.assertEqual(result, {})
+
+ def test_returns_empty_dict_for_empty_dict(self):
+ result = fetch.extract_seo_component({})
+ self.assertEqual(result, {})
+
+ def test_extracts_flat_v5_seo(self):
+ seo = {"metaTitle": "My Title", "metaDescription": "Desc", "metaImage": {"url": "x"}}
+ result = fetch.extract_seo_component(seo)
+ self.assertEqual(result["meta_title"], "My Title")
+ self.assertEqual(result["meta_description"], "Desc")
+ self.assertTrue(result["has_meta_image"])
+
+ def test_extracts_v4_nested_attributes(self):
+ seo = {"attributes": {"metaTitle": "v4 Title", "metaDescription": "v4 Desc"}}
+ result = fetch.extract_seo_component(seo)
+ self.assertEqual(result["meta_title"], "v4 Title")
+
+ def test_missing_fields_default_to_empty_string(self):
+ result = fetch.extract_seo_component({"metaTitle": "Title"})
+ self.assertEqual(result["meta_description"], "")
+ self.assertFalse(result["has_meta_image"])
+ self.assertFalse(result["has_meta_social"])
+
+
+class TestNormaliseEntry(unittest.TestCase):
+ """normalise_entry() produces a flat dict for both v4 and v5 shapes."""
+
+ def _v4_raw(self, **overrides):
+ attrs = {
+ "title": "Hello", "slug": "hello",
+ "publishedAt": "2024-01-01T00:00:00.000Z",
+ "updatedAt": "2024-01-02T00:00:00.000Z",
+ "createdAt": "2023-12-01T00:00:00.000Z",
+ "locale": "en",
+ **overrides,
+ }
+ return {"id": 42, "attributes": attrs}
+
+ def _v5_raw(self, **overrides):
+ return {
+ "id": 42, "documentId": "abc123",
+ "title": "Hello", "slug": "hello",
+ "publishedAt": "2024-01-01T00:00:00.000Z",
+ "updatedAt": "2024-01-02T00:00:00.000Z",
+ "createdAt": "2023-12-01T00:00:00.000Z",
+ "locale": "en",
+ **overrides,
+ }
+
+ def test_v4_sets_document_id_from_id(self):
+ entry = fetch.normalise_entry(self._v4_raw(), v4=True)
+ self.assertEqual(entry["document_id"], "42")
+
+ def test_v5_sets_document_id_from_document_id(self):
+ entry = fetch.normalise_entry(self._v5_raw(), v4=False)
+ self.assertEqual(entry["document_id"], "abc123")
+
+ def test_title_extracted(self):
+ entry = fetch.normalise_entry(self._v4_raw(), v4=True)
+ self.assertEqual(entry["title"], "Hello")
+
+ def test_title_fallback_to_name(self):
+ raw = self._v4_raw()
+ raw["attributes"].pop("title")
+ raw["attributes"]["name"] = "Name Fallback"
+ entry = fetch.normalise_entry(raw, v4=True)
+ self.assertEqual(entry["title"], "Name Fallback")
+
+ def test_missing_meta_title_flag(self):
+ entry = fetch.normalise_entry(self._v4_raw(), v4=True)
+ self.assertTrue(entry["missing_meta_title"])
+
+ def test_meta_title_present(self):
+ raw = self._v4_raw()
+ raw["attributes"]["seo"] = {"metaTitle": "Good Title (50 chars ok)"}
+ entry = fetch.normalise_entry(raw, v4=True)
+ self.assertFalse(entry["missing_meta_title"])
+
+ def test_meta_title_too_long(self):
+ raw = self._v5_raw()
+ raw["seo"] = {"metaTitle": "A" * 61}
+ entry = fetch.normalise_entry(raw, v4=False)
+ self.assertTrue(entry["meta_title_too_long"])
+
+ def test_meta_description_too_short(self):
+ raw = self._v5_raw()
+ raw["seo"] = {"metaTitle": "T", "metaDescription": "Short"}
+ entry = fetch.normalise_entry(raw, v4=False)
+ self.assertTrue(entry["meta_description_too_short"])
+
+ def test_meta_description_too_long(self):
+ raw = self._v5_raw()
+ raw["seo"] = {"metaDescription": "D" * 161}
+ entry = fetch.normalise_entry(raw, v4=False)
+ self.assertTrue(entry["meta_description_too_long"])
+
+ def test_root_field_fallback_for_meta_title(self):
+ raw = self._v5_raw()
+ raw["metaTitle"] = "Root Field Title"
+ entry = fetch.normalise_entry(raw, v4=False)
+ self.assertEqual(entry["seo"]["meta_title"], "Root Field Title")
+ self.assertEqual(entry["seo_schema"], "root_fields")
+
+ def test_seo_schema_component_when_seo_key_present(self):
+ raw = self._v5_raw()
+ raw["seo"] = {"metaTitle": "T"}
+ entry = fetch.normalise_entry(raw, v4=False)
+ self.assertEqual(entry["seo_schema"], "component")
+
+ def test_all_fields_present_with_valid_seo(self):
+ raw = self._v5_raw()
+ raw["seo"] = {
+ "metaTitle": "Good Title",
+ "metaDescription": "A" * 100,
+ }
+ entry = fetch.normalise_entry(raw, v4=False)
+ self.assertFalse(entry["missing_meta_title"])
+ self.assertFalse(entry["missing_meta_description"])
+ self.assertFalse(entry["meta_title_too_long"])
+ self.assertFalse(entry["meta_description_too_long"])
+ self.assertFalse(entry["meta_description_too_short"])
+
+
+class TestBuildSeoAudit(unittest.TestCase):
+ """build_seo_audit() counts correctly even when one entry has multiple issues."""
+
+ def _entry(self, missing_title=False, missing_desc=False, title_long=False,
+ desc_too_long=False, desc_too_short=False, doc_id="x"):
+ return {
+ "document_id": doc_id,
+ "title": "T", "slug": "s",
+ "seo": {"meta_title": "" if missing_title else "Title"},
+ "missing_meta_title": missing_title,
+ "missing_meta_description": missing_desc,
+ "meta_title_too_long": title_long,
+ "meta_description_too_long": desc_too_long,
+ "meta_description_too_short": desc_too_short,
+ }
+
+ def test_empty_entries(self):
+ audit = fetch.build_seo_audit([])
+ self.assertEqual(audit["total"], 0)
+ self.assertEqual(audit["complete_seo"], 0)
+
+ def test_all_complete(self):
+ entries = [self._entry(doc_id=str(i)) for i in range(3)]
+ audit = fetch.build_seo_audit(entries)
+ self.assertEqual(audit["complete_seo"], 3)
+ self.assertEqual(audit["missing_meta_title"], 0)
+
+ def test_one_missing_title(self):
+ entries = [self._entry(missing_title=True, doc_id="1"), self._entry(doc_id="2")]
+ audit = fetch.build_seo_audit(entries)
+ self.assertEqual(audit["missing_meta_title"], 1)
+ self.assertEqual(audit["complete_seo"], 1)
+
+ def test_entry_with_multiple_issues_counted_once_in_complete(self):
+ # One entry has both missing title AND missing desc — should reduce complete_seo by 1.
+ entries = [
+ self._entry(missing_title=True, missing_desc=True, doc_id="bad"),
+ self._entry(doc_id="good"),
+ ]
+ audit = fetch.build_seo_audit(entries)
+ self.assertEqual(audit["complete_seo"], 1) # only the "good" one
+ self.assertEqual(audit["missing_meta_title"], 1)
+ self.assertEqual(audit["missing_meta_description"], 1)
+
+ def test_entries_missing_meta_title_capped_at_20(self):
+ entries = [self._entry(missing_title=True, doc_id=str(i)) for i in range(25)]
+ audit = fetch.build_seo_audit(entries)
+ self.assertLessEqual(len(audit["entries_missing_meta_title"]), 20)
+
+
+# ── push_strapi_seo.py ────────────────────────────────────────────────────────
+
+class TestDetectVersionPush(unittest.TestCase):
+ """detect_version() in push reads from single-entry GET response."""
+
+ def test_explicit_v4_hint(self):
+ raw = {"data": {"id": 1, "attributes": {}}}
+ self.assertEqual(push.detect_version(raw, "4"), 4)
+
+ def test_explicit_v5_hint(self):
+ raw = {"data": {"id": 1}}
+ self.assertEqual(push.detect_version(raw, "5"), 5)
+
+ def test_infer_v4_from_attributes(self):
+ raw = {"data": {"id": 1, "attributes": {"title": "T"}}}
+ self.assertEqual(push.detect_version(raw, ""), 4)
+
+ def test_infer_v5_flat(self):
+ raw = {"data": {"id": 1, "title": "T", "documentId": "abc"}}
+ self.assertEqual(push.detect_version(raw, ""), 5)
+
+
+class TestBuildPayload(unittest.TestCase):
+ """build_payload() constructs correct Strapi PUT body."""
+
+ def test_component_schema_wraps_in_seo(self):
+ update = {"meta_title": "New Title"}
+ payload = push.build_payload(update, {}, "component")
+ self.assertIn("seo", payload["data"])
+ self.assertEqual(payload["data"]["seo"]["metaTitle"], "New Title")
+
+ def test_root_fields_schema_flat(self):
+ update = {"meta_description": "New desc"}
+ payload = push.build_payload(update, {}, "root_fields")
+ self.assertIn("metaDescription", payload["data"])
+ self.assertNotIn("seo", payload["data"])
+
+ def test_returns_none_when_nothing_to_update(self):
+ payload = push.build_payload({}, {}, "component")
+ self.assertIsNone(payload)
+
+ def test_merges_existing_seo_component(self):
+ current_attrs = {"seo": {"metaTitle": "Old", "canonicalURL": "https://x.com"}}
+ update = {"meta_title": "New Title"}
+ payload = push.build_payload(update, current_attrs, "component")
+ seo = payload["data"]["seo"]
+ self.assertEqual(seo["metaTitle"], "New Title")
+ self.assertEqual(seo["canonicalURL"], "https://x.com")
+
+ def test_both_fields_in_update(self):
+ update = {"meta_title": "T", "meta_description": "D"}
+ payload = push.build_payload(update, {}, "component")
+ seo = payload["data"]["seo"]
+ self.assertEqual(seo["metaTitle"], "T")
+ self.assertEqual(seo["metaDescription"], "D")
+
+ def test_auto_detect_component_from_current_attrs(self):
+ current_attrs = {"seo": {"metaTitle": "Old"}}
+ update = {"meta_title": "New"}
+ payload = push.build_payload(update, current_attrs, "auto")
+ self.assertIn("seo", payload["data"])
+
+ def test_auto_detect_root_when_no_seo_key(self):
+ current_attrs = {"metaTitle": "Old"}
+ update = {"meta_title": "New"}
+ payload = push.build_payload(update, current_attrs, "auto")
+ self.assertNotIn("seo", payload["data"])
+ self.assertIn("metaTitle", payload["data"])
+
+ def test_none_current_attrs_handled(self):
+ update = {"meta_title": "T"}
+ payload = push.build_payload(update, None, "component")
+ self.assertEqual(payload["data"]["seo"]["metaTitle"], "T")
+
+
+class TestStaleWriteGuard(unittest.TestCase):
+ """Stale-write guard logic embedded in process_updates."""
+
+ def test_guard_skips_when_timestamps_match(self):
+ # Both sides same — should NOT skip (no stale detection)
+ ts = "2024-01-01T00:00:00.000Z"
+ self.assertFalse(ts and ts and ts != ts)
+
+ def test_guard_fires_when_timestamps_differ(self):
+ expected = "2024-01-01T00:00:00.000Z"
+ live = "2024-01-02T00:00:00.000Z"
+ should_skip = expected and live and expected != live
+ self.assertTrue(should_skip)
+
+ def test_guard_skips_check_when_expected_empty(self):
+ # No updated_at in batch — guard should be bypassed
+ expected = ""
+ live = "2024-01-01T00:00:00.000Z"
+ should_skip = expected and live and expected != live
+ self.assertFalse(should_skip)
+
+ def test_guard_skips_check_when_live_empty(self):
+ expected = "2024-01-01T00:00:00.000Z"
+ live = ""
+ should_skip = expected and live and expected != live
+ self.assertFalse(should_skip)
+
+
+# ── preflight_strapi.py — SSRF protection ─────────────────────────────────────
+
+class TestIsPrivateIp(unittest.TestCase):
+ """_is_private_ip() correctly identifies non-public addresses."""
+
+ def test_loopback_127(self):
+ self.assertTrue(preflight._is_private_ip("127.0.0.1"))
+
+ def test_loopback_ipv6(self):
+ self.assertTrue(preflight._is_private_ip("::1"))
+
+ def test_rfc1918_10(self):
+ self.assertTrue(preflight._is_private_ip("10.0.0.1"))
+
+ def test_rfc1918_172(self):
+ self.assertTrue(preflight._is_private_ip("172.16.0.1"))
+
+ def test_rfc1918_192(self):
+ self.assertTrue(preflight._is_private_ip("192.168.1.100"))
+
+ def test_link_local(self):
+ self.assertTrue(preflight._is_private_ip("169.254.1.1"))
+
+ def test_public_ip_is_not_private(self):
+ self.assertFalse(preflight._is_private_ip("8.8.8.8"))
+
+ def test_public_ip_2(self):
+ self.assertFalse(preflight._is_private_ip("104.21.0.1"))
+
+ def test_invalid_string_returns_false(self):
+ self.assertFalse(preflight._is_private_ip("not-an-ip"))
+
+
+class TestDetectVersionPreflight(unittest.TestCase):
+ """detect_version() in preflight_strapi has same v4/v5 logic."""
+
+ def test_explicit_v4(self):
+ data = {"data": [{"attributes": {}}]}
+ self.assertEqual(preflight.detect_version(data, "4"), 4)
+
+ def test_infer_v4(self):
+ data = {"data": [{"id": 1, "attributes": {"title": "T"}}]}
+ self.assertEqual(preflight.detect_version(data, ""), 4)
+
+ def test_infer_v5(self):
+ data = {"data": [{"id": 1, "title": "T"}]}
+ self.assertEqual(preflight.detect_version(data, ""), 5)
+
+ def test_empty_collection_fallback_v5(self):
+ data = {"data": []}
+ self.assertEqual(preflight.detect_version(data, ""), 5)
+
+
+class TestPublicationParam(unittest.TestCase):
+ """publication_param() returns the version-correct filter."""
+
+ def test_v4_returns_publication_state(self):
+ param = preflight.publication_param(4)
+ self.assertIn("publicationState", param)
+ self.assertEqual(param["publicationState"], "live")
+
+ def test_v5_returns_status(self):
+ param = preflight.publication_param(5)
+ self.assertIn("status", param)
+ self.assertEqual(param["status"], "published")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/test/unit/test_url_inspection.py b/test/unit/test_url_inspection.py
new file mode 100644
index 00000000..06bb91ba
--- /dev/null
+++ b/test/unit/test_url_inspection.py
@@ -0,0 +1,222 @@
+"""
+Unit tests for seo-analysis/scripts/url_inspection.py
+
+Tests the pure logic functions — no GSC API calls, no gcloud needed.
+Run: pytest test/unit/test_url_inspection.py -v
+"""
+
+import importlib.util
+import os
+import sys
+import unittest
+
+# Load url_inspection.py as a module without executing main()
+_SCRIPT_PATH = os.path.join(
+ os.path.dirname(__file__), '..', '..', 'seo', 'seo-analysis', 'scripts', 'url_inspection.py'
+)
+spec = importlib.util.spec_from_file_location('url_inspection', _SCRIPT_PATH)
+ui = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(ui)
+
+
+class TestNormalizeSiteUrlForInspection(unittest.TestCase):
+ """normalize_site_url_for_inspection() resolves paths to absolute URLs."""
+
+ def test_absolute_url_returned_unchanged(self):
+ result = ui.normalize_site_url_for_inspection("sc-domain:example.com", "https://example.com/page")
+ self.assertEqual(result, "https://example.com/page")
+
+ def test_absolute_http_url_returned_unchanged(self):
+ result = ui.normalize_site_url_for_inspection("sc-domain:example.com", "http://example.com/page")
+ self.assertEqual(result, "http://example.com/page")
+
+ def test_path_resolved_against_sc_domain(self):
+ result = ui.normalize_site_url_for_inspection("sc-domain:example.com", "/pricing")
+ self.assertEqual(result, "https://example.com/pricing")
+
+ def test_path_resolved_against_sc_domain_with_trailing_slash(self):
+ result = ui.normalize_site_url_for_inspection("sc-domain:example.com/", "/blog")
+ self.assertEqual(result, "https://example.com/blog")
+
+ def test_path_resolved_against_url_prefix_property(self):
+ result = ui.normalize_site_url_for_inspection("https://example.com/", "/features")
+ self.assertEqual(result, "https://example.com/features")
+
+ def test_path_resolved_against_url_prefix_without_trailing_slash(self):
+ result = ui.normalize_site_url_for_inspection("https://example.com", "/about")
+ self.assertEqual(result, "https://example.com/about")
+
+ def test_root_path_resolved_against_sc_domain(self):
+ result = ui.normalize_site_url_for_inspection("sc-domain:example.com", "/")
+ self.assertEqual(result, "https://example.com/")
+
+
+class TestParseInspectionResult(unittest.TestCase):
+ """parse_inspection_result() extracts structured data from the raw API response."""
+
+ def _minimal_raw(self, **overrides):
+ """Build a minimal valid API response."""
+ data = {
+ "inspectionResult": {
+ "indexStatusResult": {
+ "verdict": "PASS",
+ "coverageState": "Submitted and indexed",
+ "lastCrawlTime": "2026-03-01T10:00:00Z",
+ "crawledAs": "DESKTOP",
+ "pageFetchState": "SUCCESSFUL",
+ "robotsTxtState": "ALLOWED",
+ "indexingState": "INDEXING_ALLOWED",
+ "referringSitemaps": ["https://example.com/sitemap.xml"],
+ "googleCanonical": "https://example.com/page",
+ "userDeclaredCanonical": "https://example.com/page",
+ },
+ "mobileUsabilityResult": {
+ "verdict": "MOBILE_FRIENDLY",
+ "issues": [],
+ },
+ "richResultsResult": {
+ "verdict": "VERDICT_UNSPECIFIED",
+ "detectedItems": [],
+ },
+ }
+ }
+ data["inspectionResult"]["indexStatusResult"].update(overrides)
+ return data
+
+ def test_parses_full_response(self):
+ raw = self._minimal_raw()
+ result = ui.parse_inspection_result(raw, "https://example.com/page")
+ self.assertEqual(result["url"], "https://example.com/page")
+ self.assertEqual(result["index_status"]["verdict"], "PASS")
+ self.assertEqual(result["index_status"]["coverage_state"], "Submitted and indexed")
+ self.assertEqual(result["index_status"]["last_crawl_time"], "2026-03-01T10:00:00Z")
+ self.assertEqual(result["mobile_usability"]["verdict"], "MOBILE_FRIENDLY")
+ self.assertEqual(result["mobile_usability"]["issues"], [])
+ self.assertEqual(result["rich_results"]["verdict"], "VERDICT_UNSPECIFIED")
+
+ def test_empty_raw_returns_unknowns(self):
+ result = ui.parse_inspection_result({}, "https://example.com/page")
+ self.assertEqual(result["url"], "https://example.com/page")
+ self.assertEqual(result["index_status"]["verdict"], "UNKNOWN")
+ self.assertEqual(result["index_status"]["coverage_state"], "UNKNOWN")
+ self.assertIsNone(result["index_status"]["last_crawl_time"])
+ self.assertEqual(result["mobile_usability"]["verdict"], "VERDICT_UNSPECIFIED")
+ self.assertEqual(result["rich_results"]["verdict"], "VERDICT_UNSPECIFIED")
+
+ def test_mobile_issues_extracted(self):
+ raw = self._minimal_raw()
+ raw["inspectionResult"]["mobileUsabilityResult"] = {
+ "verdict": "MOBILE_UNFRIENDLY",
+ "issues": [{"issueType": "USES_INCOMPATIBLE_PLUGINS"}, {"issueType": "SMALL_FONT_SIZE"}],
+ }
+ result = ui.parse_inspection_result(raw, "https://example.com/page")
+ self.assertEqual(result["mobile_usability"]["verdict"], "MOBILE_UNFRIENDLY")
+ self.assertEqual(result["mobile_usability"]["issues"], ["USES_INCOMPATIBLE_PLUGINS", "SMALL_FONT_SIZE"])
+
+ def test_rich_result_items_extracted(self):
+ raw = self._minimal_raw()
+ raw["inspectionResult"]["richResultsResult"] = {
+ "verdict": "PASS",
+ "detectedItems": [
+ {
+ "items": [
+ {"name": "FAQ schema", "issues": [{"issueMessage": "Missing required field"}]}
+ ]
+ }
+ ],
+ }
+ result = ui.parse_inspection_result(raw, "https://example.com/page")
+ self.assertEqual(result["rich_results"]["verdict"], "PASS")
+ self.assertEqual(len(result["rich_results"]["detected_items"]), 1)
+ self.assertEqual(result["rich_results"]["detected_items"][0]["name"], "FAQ schema")
+ self.assertEqual(result["rich_results"]["detected_items"][0]["issues"], ["Missing required field"])
+
+ def test_no_referring_sitemaps_returns_empty_list(self):
+ raw = self._minimal_raw()
+ del raw["inspectionResult"]["indexStatusResult"]["referringSitemaps"]
+ result = ui.parse_inspection_result(raw, "https://example.com/page")
+ self.assertEqual(result["index_status"]["referring_sitemaps"], [])
+
+
+class TestSummarizeFindings(unittest.TestCase):
+ """summarize_findings() aggregates inspection results into high-level counts."""
+
+ def _result(self, verdict="PASS", mobile_verdict="MOBILE_FRIENDLY", rich_verdict="VERDICT_UNSPECIFIED",
+ referring_sitemaps=None, last_crawl=None):
+ return {
+ "url": "https://example.com/page",
+ "index_status": {
+ "verdict": verdict,
+ "referring_sitemaps": referring_sitemaps if referring_sitemaps is not None else ["https://example.com/sitemap.xml"],
+ "last_crawl_time": last_crawl,
+ },
+ "mobile_usability": {"verdict": mobile_verdict},
+ "rich_results": {"verdict": rich_verdict},
+ }
+
+ def test_empty_results(self):
+ summary = ui.summarize_findings([])
+ self.assertEqual(summary["total_urls_inspected"], 0)
+ self.assertEqual(summary["not_indexed_count"], 0)
+ self.assertEqual(summary["mobile_issues_count"], 0)
+ self.assertEqual(summary["stale_crawl_count"], 0)
+
+ def test_pass_verdict_not_counted_as_not_indexed(self):
+ summary = ui.summarize_findings([self._result(verdict="PASS")])
+ self.assertEqual(summary["not_indexed_count"], 0)
+
+ def test_neutral_verdict_not_counted_as_not_indexed(self):
+ summary = ui.summarize_findings([self._result(verdict="NEUTRAL")])
+ self.assertEqual(summary["not_indexed_count"], 0)
+
+ def test_fail_verdict_counted_as_not_indexed(self):
+ summary = ui.summarize_findings([self._result(verdict="FAIL")])
+ self.assertEqual(summary["not_indexed_count"], 1)
+
+ def test_verdict_unspecified_not_counted_as_not_indexed(self):
+ # VERDICT_UNSPECIFIED is excluded — not a definitive not-indexed signal
+ summary = ui.summarize_findings([self._result(verdict="VERDICT_UNSPECIFIED")])
+ self.assertEqual(summary["not_indexed_count"], 0)
+
+ def test_mobile_unfriendly_counted(self):
+ summary = ui.summarize_findings([self._result(mobile_verdict="MOBILE_UNFRIENDLY")])
+ self.assertEqual(summary["mobile_issues_count"], 1)
+
+ def test_mobile_friendly_not_counted(self):
+ summary = ui.summarize_findings([self._result(mobile_verdict="MOBILE_FRIENDLY")])
+ self.assertEqual(summary["mobile_issues_count"], 0)
+
+ def test_rich_fail_counted(self):
+ summary = ui.summarize_findings([self._result(rich_verdict="FAIL")])
+ self.assertEqual(summary["rich_result_errors_count"], 1)
+
+ def test_no_sitemap_counted(self):
+ summary = ui.summarize_findings([self._result(referring_sitemaps=[])])
+ self.assertEqual(summary["no_sitemap_count"], 1)
+
+ def test_stale_crawl_over_60_days(self):
+ import datetime
+ stale_date = (datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=61)).isoformat()
+ summary = ui.summarize_findings([self._result(last_crawl=stale_date)])
+ self.assertEqual(summary["stale_crawl_count"], 1)
+
+ def test_recent_crawl_not_flagged(self):
+ import datetime
+ recent_date = (datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=30)).isoformat()
+ summary = ui.summarize_findings([self._result(last_crawl=recent_date)])
+ self.assertEqual(summary["stale_crawl_count"], 0)
+
+ def test_malformed_crawl_time_does_not_raise(self):
+ summary = ui.summarize_findings([self._result(last_crawl="not-a-date")])
+ self.assertEqual(summary["stale_crawl_count"], 0)
+
+ def test_crawl_exactly_60_days_not_flagged(self):
+ import datetime
+ boundary = (datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=60)).isoformat()
+ summary = ui.summarize_findings([self._result(last_crawl=boundary)])
+ # 60 days is NOT > 60, so should not be flagged
+ self.assertEqual(summary["stale_crawl_count"], 0)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/toprank-upgrade/SKILL.md b/toprank-upgrade/SKILL.md
new file mode 100644
index 00000000..6006e66a
--- /dev/null
+++ b/toprank-upgrade/SKILL.md
@@ -0,0 +1,127 @@
+---
+name: toprank-upgrade
+description: >
+ Upgrade toprank skills to the latest version. Detects global vs vendored
+ install, runs the upgrade, and shows what's new. Use when asked to "upgrade
+ toprank", "update toprank skills", or "get latest version". Also handles
+ inline upgrade prompts when a skill detects UPGRADE_AVAILABLE at startup.
+allowed-tools:
+ - Bash
+ - Read
+ - AskUserQuestion
+---
+
+# /toprank-upgrade
+
+Upgrade toprank skills to the latest version and show what's new.
+
+---
+
+## Inline upgrade flow
+
+This section is used when a skill preamble outputs `UPGRADE_AVAILABLE`.
+
+### Step 1: Auto-upgrade
+
+Log "Auto-upgrading toprank v{old} → v{new}..." and proceed to Step 2.
+
+If `./setup` fails, restore from backup (`.bak` directory) and warn: "Auto-upgrade failed — restored previous version. Run `/toprank-upgrade` manually."
+
+---
+
+### Step 2: Detect install type
+
+```bash
+if [ -d "$HOME/.claude/skills/toprank/.git" ]; then
+ INSTALL_TYPE="global-git"; INSTALL_DIR="$HOME/.claude/skills/toprank"
+elif [ -d "$HOME/.claude/skills/stockholm/.git" ]; then
+ INSTALL_TYPE="global-git"; INSTALL_DIR="$HOME/.claude/skills/stockholm"
+elif [ -d ".claude/skills/toprank/.git" ]; then
+ INSTALL_TYPE="local-git"; INSTALL_DIR=".claude/skills/toprank"
+elif [ -d ".claude/skills/stockholm/.git" ]; then
+ INSTALL_TYPE="local-git"; INSTALL_DIR=".claude/skills/stockholm"
+elif [ -d "$HOME/.claude/skills/toprank" ]; then
+ INSTALL_TYPE="vendored-global"; INSTALL_DIR="$HOME/.claude/skills/toprank"
+elif [ -d "$HOME/.claude/skills/stockholm" ]; then
+ INSTALL_TYPE="vendored-global"; INSTALL_DIR="$HOME/.claude/skills/stockholm"
+else
+ echo "ERROR: toprank skills not found"; exit 1
+fi
+echo "Install type: $INSTALL_TYPE at $INSTALL_DIR"
+```
+
+### Step 3: Save old version
+
+```bash
+OLD_VERSION=$(cat "$INSTALL_DIR/VERSION" 2>/dev/null || echo "unknown")
+```
+
+### Step 4: Upgrade
+
+**For git installs** (global-git, local-git):
+```bash
+cd "$INSTALL_DIR"
+STASH_OUTPUT=$(git stash 2>&1)
+git fetch origin
+git reset --hard origin/main
+./setup
+```
+If the stash output contains "Saved working directory", warn: "Note: local changes were stashed. Run `git stash pop` in the install directory to restore them."
+
+**For vendored installs** (vendored, vendored-global):
+```bash
+TMP_DIR=$(mktemp -d)
+git clone --depth 1 https://github.com/nowork-studio/toprank.git "$TMP_DIR/toprank"
+# Remove stale backup from a previous failed upgrade if present.
+rm -rf "$INSTALL_DIR.bak"
+mv "$INSTALL_DIR" "$INSTALL_DIR.bak"
+mv "$TMP_DIR/toprank" "$INSTALL_DIR"
+cd "$INSTALL_DIR" && ./setup
+rm -rf "$INSTALL_DIR.bak" "$TMP_DIR"
+```
+If `./setup` fails, restore: `rm -rf "$INSTALL_DIR" && mv "$INSTALL_DIR.bak" "$INSTALL_DIR"` and warn the user.
+
+### Step 5: Write marker + clear cache
+
+```bash
+mkdir -p ~/.toprank
+echo "$OLD_VERSION" > ~/.toprank/just-upgraded-from
+rm -f ~/.toprank/last-update-check
+rm -f ~/.toprank/update-snoozed
+```
+
+### Step 6: Show What's New
+
+Read `$INSTALL_DIR/CHANGELOG.md`. Find all version entries between the old version and the new version. Summarize as 3-7 bullets grouped by theme — focus on user-facing changes, skip internal refactors.
+
+Format:
+```
+toprank v{new} — upgraded from v{old}!
+
+What's new:
+- [bullet 1]
+- [bullet 2]
+- ...
+
+Enjoy the new skills!
+```
+
+### Step 7: Continue
+
+After showing What's New, continue with whatever skill the user originally invoked.
+
+---
+
+## Standalone usage
+
+When invoked directly as `/toprank-upgrade`:
+
+1. Force a fresh update check (bypass cache and snooze):
+```bash
+~/.claude/skills/toprank/bin/toprank-update-check --force 2>/dev/null || \
+~/.claude/skills/stockholm/bin/toprank-update-check --force 2>/dev/null || true
+```
+
+2. If `UPGRADE_AVAILABLE <old> <new>`: follow Steps 2–6 above.
+
+3. If no `UPGRADE_AVAILABLE` output: tell the user "You're already on the latest version (v{LOCAL})."