feat: v1.7.0 - Google SEO APIs, PDF reports, security hardening

Add complete Google SEO APIs skill with 11 Python scripts, 10 reference
files, and seo-google subagent. Enterprise PDF report generator with
WeasyPrint + matplotlib charts. 4-tier credential system (API key,
OAuth, GA4, Ads). SSRF protection via validate_url() in all API scripts.
.gitignore hardened for credential files. OAuth tokens no longer store
client_secret. README and CLAUDE.md updated with report rules, color
palette, and cross-skill enforcement.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: AgriciDaniel

.claude-plugin/marketplace.json

@@ -16,9 +16,9 @@
       "homepage": "https://github.com/AgriciDaniel/claude-seo",
       "repository": "https://github.com/AgriciDaniel/claude-seo",
       "license": "MIT",
-      "keywords": ["seo", "technical-seo", "e-e-a-t", "schema-markup", "local-seo", "geo", "ai-search"],
+      "keywords": ["seo", "technical-seo", "e-e-a-t", "schema-markup", "local-seo", "geo", "ai-search", "google-api", "search-console", "pagespeed", "crux"],
       "category": "seo",
-      "tags": ["seo", "audit", "technical", "content", "schema", "local", "geo"]
+      "tags": ["seo", "audit", "technical", "content", "schema", "local", "geo", "google-api"]
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-seo",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Comprehensive SEO analysis skill for Claude Code. Covers technical SEO, content quality (E-E-A-T), schema markup, image optimization, sitemap architecture, AI search optimization (GEO), local SEO (GBP, citations, reviews, map pack), maps intelligence, and strategic planning across all industries.",
   "author": {
     "name": "AgriciDaniel",
@@ -21,6 +21,10 @@
     "ai-search",
     "sitemap",
     "image-optimization",
-    "hreflang"
+    "hreflang",
+    "google-search-console",
+    "pagespeed",
+    "crux",
+    "ga4"
   ]
 }

.gitignore

@@ -31,6 +31,16 @@ venv/
 env/
 .env/
 
+# Secrets and credentials (NEVER commit these)
+.env
+.env.*
+*.env
+**/.env
+**/client_secret*.json
+**/service_account*.json
+**/oauth-token.json
+**/.google-token.json
+
 # Node (if any)
 node_modules/
 
@@ -86,6 +96,10 @@ seo audit demo.gif
 seo command demo.gif
 .github-audit/
 
+# Generated Google SEO reports
+Google-SEO-Report-*.html
+Google-SEO-Report-*.pdf
+
 # Site-specific analysis outputs
 LOCAL-SEO-ANALYSIS-*.md
 LOCAL-SEO-ANALYSIS-*.html

CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.0] - 2026-03-28
+
+### Added
+- **Google SEO APIs skill**: `skills/seo-google/SKILL.md` with 21 commands across 4 credential tiers
+- **Google subagent**: `agents/seo-google.md` for enriched audit data (CWV field data, indexation status, organic traffic)
+- **11 Python scripts**: google_auth.py, gsc_query.py, gsc_inspect.py, pagespeed_check.py, crux_history.py, indexing_notify.py, ga4_report.py, google_report.py, youtube_search.py, nlp_analyze.py, keyword_planner.py
+- **10 reference files**: auth-setup.md, search-console-api.md, pagespeed-crux-api.md, indexing-api.md, ga4-data-api.md, youtube-api.md, nlp-api.md, keyword-planner-api.md, supplementary-apis.md, rate-limits-quotas.md
+- **PDF report generator**: `scripts/google_report.py` with enterprise A4 template, WeasyPrint + matplotlib charts, post-generation quality review
+- **OAuth web credential flow**: Browser-based auth with localhost:8085 callback, token refresh, manual code exchange fallback
+- **4-tier credential system**: Tier 0 (API key: PSI/CrUX), Tier 1 (+OAuth/SA: GSC/Indexing), Tier 2 (+GA4), Tier 3 (+Ads Keyword Planner)
+- **Python dependencies**: google-api-python-client, google-auth, google-auth-oauthlib, google-auth-httplib2, google-analytics-data, matplotlib, weasyprint
+
+### Security
+- SSRF protection: `validate_url()` blocks private IPs, loopback, and GCP metadata endpoints in all Google API scripts
+- `.gitignore` hardened with 8 credential patterns: `.env`, `client_secret*.json`, `oauth-token.json`, `service_account*.json`
+- OAuth tokens no longer store `client_secret` (reads from client_secret.json file only)
+- Removed hardcoded user paths from all scripts (mobile_analysis.py, capture scripts)
+
+### Changed
+- Sub-skill count: 14 -> 15 core (+ 2 extensions)
+- Subagent count: 9 -> 10 core (+ 2 extension) with conditional Google API spawning
+- seo-audit spawns seo-google agent when Google API credentials detected
+- seo-technical and seo-performance can use CrUX field data when available
+- Report Generation Rules added to CLAUDE.md with color palette, dependency, and cross-skill enforcement
+- README updated with Google APIs, local SEO, maps, and PDF report features
+
+---
+
 ## [1.6.1] - 2026-03-27
 
 ### Added

CLAUDE.md

@@ -4,8 +4,8 @@
 
 This repository contains **Claude SEO**, a Tier 4 Claude Code skill for comprehensive
 SEO analysis across all industries. It follows the Agent Skills open standard and the
-3-layer architecture (directive, orchestration, execution). 14 core sub-skills (+ 2
-extensions), 9 core subagents (+ 2 extension agents), and an extensible reference
+3-layer architecture (directive, orchestration, execution). 15 core sub-skills (+ 2
+extensions), 10 core subagents (+ 2 extension agents), and an extensible reference
 system cover technical SEO, content quality,
 schema markup, image optimization, sitemap architecture, AI search optimization,
 local SEO (GBP, citations, reviews, map pack), and maps intelligence (geo-grid
@@ -17,7 +17,7 @@ rank tracking, GBP auditing, review intelligence, competitor radius mapping).
 claude-seo/
   CLAUDE.md                          # Project instructions (this file)
   .claude-plugin/
-    plugin.json                    # Plugin manifest (v1.6.1)
+    plugin.json                    # Plugin manifest (v1.7.0)
     marketplace.json               # Marketplace catalog for distribution
   skills/                            # 17 skills (auto-discovered)
     seo/                           # Main orchestrator skill
@@ -37,11 +37,14 @@ claude-seo/
     seo-programmatic/SKILL.md    # Programmatic SEO at scale
     seo-competitor-pages/SKILL.md # Competitor comparison pages
     seo-hreflang/SKILL.md       # International SEO / hreflang
+    seo-google/                  # Google SEO APIs
+      SKILL.md
+      references/                # API reference files (7 files)
     seo-dataforseo/SKILL.md     # Live SEO data via DataForSEO MCP
     seo-image-gen/              # AI image generation for SEO assets
       SKILL.md
       references/                # Image gen reference files (7 files)
-  agents/                          # 11 subagents (auto-discovered)
+  agents/                          # 12 subagents (auto-discovered)
     seo-technical.md             # Crawlability, indexability, security
     seo-content.md               # E-E-A-T, readability, thin content
     seo-schema.md                # Structured data validation
@@ -51,6 +54,7 @@ claude-seo/
     seo-geo.md                   # AI crawler access, GEO, citability
     seo-local.md                 # GBP, NAP, citations, reviews, local schema
     seo-maps.md                  # Geo-grid, GBP audit, reviews, competitor radius
+    seo-google.md                # Google API analyst (CrUX, GSC, GA4)
     seo-dataforseo.md            # DataForSEO data analyst
     seo-image-gen.md             # SEO image audit analyst
   hooks/                           # Quality gate hooks
@@ -67,7 +71,7 @@ claude-seo/
 
 | Command | Purpose |
 |---------|---------|
-| `/seo audit <url>` | Full site audit with 9 parallel subagents |
+| `/seo audit <url>` | Full site audit with 10 parallel subagents |
 | `/seo page <url>` | Deep single-page analysis |
 | `/seo technical <url>` | Technical SEO audit (9 categories) |
 | `/seo content <url>` | E-E-A-T and content quality analysis |
@@ -81,6 +85,7 @@ claude-seo/
 | `/seo local <url>` | Local SEO analysis (GBP, citations, reviews, map pack) |
 | `/seo maps [command] [args]` | Maps intelligence (geo-grid, GBP audit, reviews, competitors) |
 | `/seo hreflang <url>` | International SEO / hreflang audit |
+| `/seo google [command] [url]` | Google SEO APIs (GSC, PageSpeed, CrUX, Indexing, GA4) |
 | `/seo image-gen [use-case] <desc>` | AI image generation for SEO assets (extension) |
 
 ## Development Rules
@@ -93,6 +98,21 @@ claude-seo/
 - Python dependencies install into `~/.claude/skills/seo/.venv/`
 - Test with `python -m pytest tests/` after changes (if applicable)
 
+## Report Generation Rules
+
+- **All SEO reports must use `scripts/google_report.py`** as the canonical report generator
+- **Dependencies**: `matplotlib>=3.8.0` (charts) + `weasyprint>=61.0` (HTML-to-PDF), both in `requirements.txt`
+- **Format**: A4 PDF via WeasyPrint + matplotlib charts at 200 DPI
+- **Style**: Clean white title page with navy (#1e3a5f) accent, Times New Roman body font
+- **Color palette**: Navy #1e3a5f (headers), dark gold #b8860b (accents), forest green #2d6a4f (pass), warm amber #d4740e (warnings), deep red #c53030 (fail), warm cream #faf9f7 (backgrounds)
+- **Structure**: Title page → TOC with scores → Executive Summary → Data sections → Recommendations → Methodology
+- **Charts**: 85% width, max-height 120mm, figure captions on every chart, saved to `charts/` at 200 DPI
+- **No `page-break-inside: avoid`** on any element (causes white gaps in WeasyPrint)
+- **Post-generation review**: `_review_pdf()` runs automatically, checking for empty images, thin sections, duplicates
+- **Before presenting any PDF to the user**: verify the review passes (`"status": "PASS"`)
+- **Cross-skill enforcement**: After completing ANY analysis command (audit, page, technical, content, schema, geo, local, maps), offer: "Generate a PDF report? Use `/seo google report`"
+- **Google logo** appears on title page when using Google API data ("Powered by Google APIs")
+
 ## Ecosystem
 
 Part of the Claude Code skill family:

README.md

@@ -1,10 +1,10 @@
-<!-- Updated: 2026-03-06 -->
+<!-- Updated: 2026-03-28 -->
 
 ![Claude SEO](screenshots/cover-image.jpeg)
 
 # Claude SEO - SEO Audit Skill for Claude Code
 
-Comprehensive SEO analysis skill for Claude Code. Covers technical SEO, on-page analysis, content quality (E-E-A-T), schema markup, image optimization, sitemap architecture, AI search optimization (GEO), and strategic planning.
+Comprehensive SEO analysis skill for Claude Code. Covers technical SEO, on-page analysis, content quality (E-E-A-T), schema markup, image optimization, sitemap architecture, AI search optimization (GEO), local SEO, maps intelligence, Google SEO APIs (Search Console, PageSpeed, CrUX, GA4), PDF report generation, and strategic planning.
 
 ![SEO Command Demo](screenshots/seo-command-demo.gif)
 
@@ -113,7 +113,11 @@ claude
 | `/seo plan <type>` | Strategic SEO planning (saas, local, ecommerce, publisher, agency) |
 | `/seo programmatic <url>` | Programmatic SEO analysis and planning |
 | `/seo competitor-pages <url>` | Competitor comparison page generation |
+| `/seo local <url>` | Local SEO analysis (GBP, citations, reviews, map pack) |
+| `/seo maps [command]` | Maps intelligence (geo-grid, GBP audit, reviews, competitors) |
 | `/seo hreflang <url>` | Hreflang/i18n SEO audit and generation |
+| `/seo google [command] [url]` | Google SEO APIs (GSC, PageSpeed, CrUX, Indexing, GA4) |
+| `/seo google report [type]` | Generate PDF/HTML report with charts (cwv-audit, gsc-performance, full) |
 
 ### `/seo programmatic [url|plan]`
 **Programmatic SEO Analysis & Planning**
@@ -183,6 +187,28 @@ New for 2026 - optimize for:
 - Perplexity
 - Other AI-powered search
 
+### Google SEO APIs (New in v1.7.0)
+Direct integration with Google's SEO data:
+- **PageSpeed Insights + CrUX**: Lab and field Core Web Vitals data
+- **Search Console**: Top queries, URL inspection, sitemap status
+- **Indexing API**: Notify Google of new/updated/removed URLs
+- **GA4**: Organic traffic, top landing pages, device/country breakdown
+- **PDF Reports**: Enterprise A4 reports with charts via WeasyPrint + matplotlib
+
+4-tier credential system — get value at every level:
+| Tier | Auth | APIs |
+|------|------|------|
+| 0 | API key | PSI, CrUX, CrUX History |
+| 1 | + OAuth/SA | + GSC, URL Inspection, Indexing |
+| 2 | + GA4 config | + GA4 organic traffic |
+| 3 | + Ads token | + Keyword Planner |
+
+### Local SEO & Maps Intelligence (New in v1.6.0)
+- Google Business Profile optimization
+- NAP consistency auditing
+- Citation and review analysis
+- Geo-grid rank tracking and competitor radius mapping
+
 ### Quality Gates
 - Warning at 30+ location pages
 - Hard stop at 50+ location pages
@@ -192,9 +218,9 @@ New for 2026 - optimize for:
 ## Architecture
 
 ```
-~/.claude/skills/seo/         # Main skill
-~/.claude/skills/seo-*/       # Sub-skills (12 total)
-~/.claude/agents/seo-*.md     # Subagents (7 total)
+~/.claude/skills/seo/         # Main orchestrator skill
+~/.claude/skills/seo-*/       # Sub-skills (15 + 2 extensions)
+~/.claude/agents/seo-*.md     # Subagents (10 + 2 extensions)
 ```
 
 ### Video & Live Schema (New)
@@ -219,6 +245,7 @@ See `schema/templates.json` for ready-to-use JSON-LD snippets.
 - Python 3.10+
 - Claude Code CLI
 - Optional: Playwright for screenshots
+- Optional: Google API credentials for enriched data (see `/seo google setup`)
 
 ## Uninstall
 

agents/seo-google.md

@@ -0,0 +1,69 @@
+---
+name: seo-google
+description: Google SEO API analyst. Fetches CWV field data via CrUX, indexation status via GSC, and organic traffic via GA4 for enriched audit data.
+model: sonnet
+maxTurns: 15
+tools: Read, Bash, Write, Glob, Grep  # Write needed for report/data file output
+---
+
+You are a Google SEO API data analyst. When delegated tasks during an SEO audit:
+
+1. Check credentials: `python scripts/google_auth.py --check --json`
+2. Determine tier (0 = API key, 1 = + service account, 2 = + GA4)
+3. Execute tier-appropriate analysis
+4. Format output to match claude-seo conventions
+
+## Tier-Based Workflow
+
+### Tier 0 (API Key Only)
+- Run PSI + CrUX on homepage: `python scripts/pagespeed_check.py <url> --json`
+- Run CrUX History for origin: `python scripts/crux_history.py <origin> --origin --json`
+- Report CWV field data with traffic-light ratings
+
+### Tier 1 (+ Service Account)
+- All Tier 0 checks
+- GSC top queries/pages (28 days): `python scripts/gsc_query.py --property <prop> --json`
+- URL Inspection on homepage + key pages: `python scripts/gsc_inspect.py <url> --json`
+- GSC sitemap status: `python scripts/gsc_query.py sitemaps --property <prop> --json`
+
+### Tier 2 (Full)
+- All Tier 1 checks
+- GA4 organic traffic (28 days): `python scripts/ga4_report.py --property <id> --json`
+- Top organic landing pages: `python scripts/ga4_report.py --property <id> --report top-pages --json`
+
+## Core Web Vitals Thresholds
+
+| Metric | Good | Needs Improvement | Poor |
+|--------|------|-------------------|------|
+| LCP | ≤ 2,500ms | 2,500-4,000ms | > 4,000ms |
+| INP | ≤ 200ms | 200-500ms | > 500ms |
+| CLS | ≤ 0.1 | 0.1-0.25 | > 0.25 |
+
+INP replaced FID on March 12, 2024. Never reference FID.
+
+## Output Format
+
+Match existing claude-seo patterns:
+- Tables for metrics with traffic-light ratings
+- Scores as XX/100
+- Priority: Critical > High > Medium > Low
+- Note data source as "Google API (field data)" to distinguish from static analysis
+- Include data freshness notes (CrUX: 28-day rolling, GSC: 2-3 day lag, GA4: 1 day lag)
+
+## Report Generation (MANDATORY)
+
+After completing data collection at any tier, ALWAYS offer to generate a PDF report.
+The report uses the enterprise template: white cover, navy accents, Times New Roman, charts at 85% width, Google logo on title page. No page-break-inside: avoid (causes white gaps).
+
+```bash
+python scripts/google_report.py --type full --data data.json --domain DOMAIN --format pdf --json
+```
+Report types: `cwv-audit`, `gsc-performance`, `indexation`, `full`.
+Before presenting: verify `"review": {"status": "PASS"}` in the JSON output.
+
+## Error Handling
+
+- If credentials are missing, report which tier is available and what can still be checked
+- If CrUX returns 404, note insufficient Chrome traffic and fall back to PSI lab data
+- If GSC returns 403, report the service account email and instruct on adding permissions
+- Never fail silently -- always report what succeeded and what failed

agents/seo-performance.md

@@ -71,6 +71,15 @@ curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=URL&key=API
 npx lighthouse URL --output json
 ```
 
+## Google API Integration (Optional)
+
+If Google API credentials are configured, prefer CrUX field data over Lighthouse lab data for CWV assessment:
+```bash
+python scripts/pagespeed_check.py URL --json
+python scripts/crux_history.py URL --json
+```
+Field data (28-day Chrome user average) is more representative than lab data (single Lighthouse run). Use lab data as fallback when CrUX returns 404 (insufficient traffic).
+
 ## Output Format
 
 Provide:

agents/seo-technical.md

@@ -3,7 +3,7 @@ name: seo-technical
 description: Technical SEO specialist. Analyzes crawlability, indexability, security, URL structure, mobile optimization, Core Web Vitals, and JavaScript rendering.
 model: sonnet
 maxTurns: 20
-tools: Read, Bash, Write, Glob, Grep
+tools: Read, Bash, Write, Glob, Grep  # Write needed for report/data file output
 ---
 
 You are a Technical SEO specialist. When given a URL or set of URLs:

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "claude-seo"
-version = "1.5.0"
+version = "1.7.0"
 description = "Comprehensive SEO analysis skill for Claude Code"
 requires-python = ">=3.11"
 license = "MIT"