site-visibility-report

name: site-visibility-report description: > Generate a polished, client-ready SEO / GEO / AEO website "visibility" report (standalone HTML + PDF) for any URL. Runs live measurement scripts, an AI-visibility benchmark across AI engines (ChatGPT/Perplexity/Gemini/Google AI Overviews), and automatic competitor analysis, then assembles a 12-section flagship HTML report and a 9-section PDF. Use whenever the user wants to audit a site's search + AI visibility, build a "витрина" / showcase report for a prospect, analyze how well a site is found by Google and cited by AI engines, benchmark a site vs competitors on SEO/GEO/AEO, or asks "почему сайт не находят", "проверь SEO/GEO", "сделай отчёт по сайту".

Site Visibility Report (SEO · GEO · AEO)

Produces a premium, agency-grade audit of how well a website is found in classic search (SEO), cited by generative AI engines (GEO), and surfaced as direct answers / voice (AEO) — grounded in live measurement, not guesses. Built for repeatable "показал клиенту → продал" showcase reports.

What it produces (per site)

1. <domain>-report.html — flagship 12-section HTML report (the deliverable).
2. <domain>-report.standalone.html — same, single self-contained file (CSS + screenshot inlined). Send this to clients.
3. <domain>-report.pdf — 9-section PDF in the SEO-GEO-AEO format (navy cover, 1–10 scoring) for download/print.
4. data/*.json — raw measured signals, for reproducibility + the appendix.

See examples/mobilexy-report.standalone.html + examples/mobilexy-report.pdf for a finished reference.

Step 0 — Confirm scope (ask once)

Before measuring, confirm three things (skip any the user already stated):

1. Language — RU / EN / bilingual. (Match the audience; showcase reports for EN brands → EN.)
2. Measurement depth:
   • Free, no keys (default): scriptable HTML/robots/sitemap/llms checks, site: index checks + live AI-engine reads via WebSearch/Chrome MCP, competitor discovery via SERP overlap. CWV may be unavailable (PSI keyless throttles). Nothing blocks the build.
   • Free + free keys: add Google PSI key (real CWV), Gemini free-tier key (repeatable multi-query AI-visibility w/ citations), OpenPageRank key (domain authority). Still $0.
   • Paid precision: + DataForSEO / SerpAPI for exact Google AI-Overview citations, keyword volumes, backlink graphs.
3. Structure — default 12-section HTML + 9-section PDF (see templates/STRUCTURE.md); confirm or adjust.

If the report template itself is being reused as-is, you can skip the structure question.

Dependencies

• Python 3.10+ with requests, beautifulsoup4, lxml (python -c "import requests,bs4,lxml").
• geo-seo-claude scripts — fetch_page.py, citability_scorer.py, brand_scanner.py. Set GEO_SCRIPTS to that folder, e.g. C:\Users\Tim\Desktop\ВИТРИНЫ\geo-seo-claude\scripts.
• Google Chrome — used headless to render the PDF + cover screenshot (no LibreOffice needed).

Step 1 — Recon (profile the site)

Fetch the homepage + key pages; identify product, audience, languages, the money pages, the content systems (blog / help / catalog), and the page list to measure. A fan-out recon workflow is ideal here (profile + skill-capability catalog + tool inventory + competitor discovery + a quick GEO probe). Capture the 7-ish benchmark queries a real buyer would ask — they drive Step 2's AI-visibility benchmark.

Step 2 — Measure (run the scripts; this is the credibility layer)

Save everything to ./data/. Use scripts/collect.py (wraps the calls) or run directly:

# core pages + robots + llms + sitemap  (slug-named JSON in ./data/)
python scripts/collect.py --domain https://SITE --scripts-dir "%GEO_SCRIPTS%" \
  --pages "/,/pricing,/about,/<money-page>,/blog,/blog/<post>,/help" --out ./data

# citability (per page) — read its --help first; pass URL or piped blocks from fetch_page.py <url> blocks
python "%GEO_SCRIPTS%/citability_scorer.py" <url>

# earned brand authority (Wikipedia/Wikidata live)
python "%GEO_SCRIPTS%/brand_scanner.py" "<brand name>"

# Core Web Vitals (free, may 429 on keyless pool — then mark "not measured, recommend PSI key")
#   GET https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=<enc>&strategy=mobile&category=performance&category=seo

AI-visibility benchmark (the headline GEO measurement): run each benchmark query through WebSearch (and/or Chrome MCP for live AI Overviews / ChatGPT / Perplexity). Per query record: mentioned? cited? who dominates? Aggregate mention-rate, citation-rate, and share-of-voice vs competitors. Always also do a bare brand search to catch stale-index / name-collision problems.

Competitor matrix: auto-discover 4–6 competitors (SERP overlap + co-mention from the benchmark). For each, measure llms.txt presence, homepage schema types, sitemap size, Wikipedia, Trustpilot, AI-visibility.

Verify, don't trust briefs. Re-derive every claim from the data. If two probes disagree (e.g. one agent says "no robots.txt" but fetch_page.py … robots returns 200), trust the direct measurement and drop the false claim. The mobilexy build caught exactly this.

Step 3 — Score (explicit rubrics → composites)

Sub-scores 0–100, then roll up. Weights used (tune per STRUCTURE.md):

Map to the 1–10 cover dimensions (SEO / GEO / AEO): 1–3 critical · 4–5 below avg · 6–7 decent · 8–9 strong · 10 exemplary. Status labels: ≤4 "Требует работы / Needs Work", 5–7 "На уровне / On Track", 8+ "Сильно / Strong". Combined = SEO+GEO+AEO out of 30.

The signature insight to surface when it applies: the GEO infrastructure vs authority split ("GEO-ready, GEO-invisible").

Step 4 — Assemble the HTML

Start from templates/report-template.html (links report.css) or copy the example report and replace content. Fill the 12 sections (see templates/STRUCTURE.md for the per-section data contract). Components live in report.css: gauges (<div class="ring" style="--v:84;--c:var(--green)">), status pills, severity callouts, bars for share-of-voice, meters for the GEO split, tbl tables. Keep prose specific and evidence-backed; calibrate tone to findings.

Step 5 — Render PDF + standalone

# 9-section PDF (write a print HTML from the PDF section of STRUCTURE.md, then:)
python scripts/render_pdf.py --html _pdf-source.html --pdf <domain>-report.pdf --shot assets/_qa.png

# single-file shareable HTML (inlines report.css + assets/* images as base64)
python scripts/make_standalone.py --html <domain>-report.html --out <domain>-report.standalone.html

Always visually verify by reading the QA screenshot before delivering.

Output folder layout (per site, under ВИТРИНЫ/)

<domain>/
  <domain>-report.html              # flagship (links ../site-visibility-report/templates/report.css OR inline)
  <domain>-report.standalone.html   # send this
  <domain>-report.pdf
  _pdf-source.html                  # PDF build source (keep for re-render)
  assets/<domain>-home.png          # cover screenshot
  data/*.json                       # raw measured signals

Honesty rules (carry into every report's appendix)

• State what was not measured (e.g. CWV when PSI 429'd) and how to fix it — never fake numbers.
• Competitor schema is understated when their pages are bot-protected (Airalo/Saily) — say so.
• Scores are external-signal estimates (no Search Console access unless the user owns the domain).
• The AI-visibility benchmark is a timestamped snapshot — engines drift; note the date.

Scoring reference (mobilexy, 2026-06-13) — sanity anchor

Technical 84 · On-Page 71 · Schema 72 · AEO 74 · llms.txt 78 · Crawler 100 · Content/E-E-A-T 48 · Citability 35 · Platform 47 · Brand Authority 6 → SEO 7/10, GEO 4/10, AEO 7/10 (18/30). Verdict: "GEO-ready, GEO-invisible."