antigravity-seo-kit 2.0.0

package/.agent/skills/seo-google/SKILL.md

@@ -0,0 +1,405 @@
+---
+name: seo-google
+description: >
+  Google SEO APIs: Search Console (Search Analytics, URL Inspection, Sitemaps),
+  PageSpeed Insights v5, CrUX field data with 25-week history, Indexing API v3,
+  and GA4 organic traffic. Provides real Google field data for Core Web Vitals,
+  indexation status, search performance, and organic traffic trends. Use when
+  user says "search console", "GSC", "PageSpeed", "CrUX", "field data",
+  "indexing API", "GA4 organic", "URL inspection", "google api setup",
+  "real CWV data", "impressions", "clicks", "CTR", "position data",
+  "LCP", "INP", "CLS", "FCP", "TTFB", or "Lighthouse scores".
+---
+
+# Google SEO APIs
+
+Direct access to Google's own SEO data. Bridges the gap between crawl-based
+analysis (existing seo-kit skills) and Google's real-time field data: actual
+Chrome user metrics, real indexation status, search performance, and organic traffic.
+
+All APIs are free. Setup requires a Google Cloud project with API key and/or
+service account -- run `/seo google setup` for step-by-step instructions.
+
+## Prerequisites
+
+Before executing any command, check credentials:
+```bash
+python scripts/google_auth.py --check --json
+```
+
+Config file: `.agent/skills/seo-google/config/google-api.json`
+```json
+{
+  "service_account_path": "/path/to/service_account.json",
+  "api_key": "AIzaSy...",
+  "default_property": "sc-domain:example.com",
+  "ga4_property_id": "properties/123456789"
+}
+```
+
+If missing, read `references/auth-setup.md` and walk the user through setup.
+
+### Credential Tiers
+
+| Tier | Detection | Available Commands |
+|------|-----------|-------------------|
+| **0** (API Key) | `api_key` present | `pagespeed`, `crux`, `crux-history`, `youtube`, `nlp` |
+| **1** (OAuth/SA) | + OAuth token or service account | Tier 0 + `gsc`, `inspect`, `sitemaps`, `index` |
+| **2** (Full) | + `ga4_property_id` configured | Tier 1 + `ga4`, `ga4-pages` |
+| **3** (Ads) | + `ads_developer_token` + `ads_customer_id` | Tier 2 + `keywords`, `volume` |
+
+Always communicate the detected tier before running commands.
+
+## Quick Reference
+
+| Command | What it does | Tier |
+|---------|-------------|------|
+| `/seo google setup` | Check/configure API credentials | -- |
+| `/seo google pagespeed <url>` | PSI Lighthouse + CrUX field data | 0 |
+| `/seo google crux <url>` | CrUX field data only (p75 metrics) | 0 |
+| `/seo google crux-history <url>` | 25-week CWV trend analysis | 0 |
+| `/seo google gsc <property>` | Search Console: clicks, impressions, CTR, position | 1 |
+| `/seo google inspect <url>` | URL Inspection: index status, canonical, crawl info | 1 |
+| `/seo google inspect-batch <file>` | Batch URL Inspection from file | 1 |
+| `/seo google sitemaps <property>` | GSC sitemap status | 1 |
+| `/seo google index <url>` | Submit URL to Indexing API | 1 |
+| `/seo google index-batch <file>` | Batch submit up to 200 URLs | 1 |
+| `/seo google ga4 [property-id]` | GA4 organic traffic report | 2 |
+| `/seo google ga4-pages [property-id]` | Top organic landing pages | 2 |
+| `/seo google youtube <query>` | YouTube video search (views, likes, duration) | 0 |
+| `/seo google youtube-video <id>` | YouTube video details + top comments | 0 |
+| `/seo google nlp <url-or-text>` | NLP entity extraction + sentiment + classification | 0 |
+| `/seo google entities <url-or-text>` | Entity analysis only (for E-E-A-T) | 0 |
+| `/seo google keywords <seed>` | Keyword ideas from Google Ads Keyword Planner | 3 |
+| `/seo google volume <keywords>` | Search volume lookup from Keyword Planner | 3 |
+| `/seo google entity <query>` | Knowledge Graph entity check | 0 |
+| `/seo google safety <url>` | Web Risk URL safety check | 0 |
+| `/seo google quotas` | Show rate limits for all APIs | -- |
+
+---
+
+## PageSpeed + CrUX
+
+### `/seo google pagespeed <url>`
+
+Combined Lighthouse lab data + CrUX field data.
+
+**Script:** `python scripts/pagespeed_check.py <url> --json`
+**Reference:** `references/pagespeed-crux-api.md`
+**Default:** Both mobile + desktop strategies, all Lighthouse categories.
+
+Output merges lab scores (point-in-time Lighthouse) with field data (28-day
+Chrome user metrics). CrUX tries URL-level first, falls back to origin-level.
+
+### `/seo google crux <url>`
+
+CrUX field data only (no Lighthouse run). Faster.
+
+**Script:** `python scripts/pagespeed_check.py <url> --crux-only --json`
+
+### `/seo google crux-history <url>`
+
+25-week CrUX History trends. Shows whether CWV metrics are improving, stable, or degrading.
+
+**Script:** `python scripts/crux_history.py <url> --json`
+**Reference:** `references/pagespeed-crux-api.md`
+
+Output includes per-metric trend direction, percentage change, and weekly p75 values.
+
+---
+
+## Search Console
+
+### `/seo google gsc <property>`
+
+Search Analytics: clicks, impressions, CTR, position for last 28 days.
+
+**Script:** `python scripts/gsc_query.py --property <property> --json`
+**Reference:** `references/search-console-api.md`
+**Default:** 28 days, dimensions=query,page, type=web, limit=1000.
+
+Includes quick-win detection: queries at position 4-10 with high impressions.
+
+### `/seo google inspect <url>`
+
+URL Inspection: real indexation status from Google.
+
+**Script:** `python scripts/gsc_inspect.py <url> --json`
+
+Returns: verdict (PASS/FAIL), coverage state, robots.txt status, indexing state,
+page fetch state, canonical selection, mobile usability, rich results.
+
+### `/seo google inspect-batch <file>`
+
+Batch inspection from a file (one URL per line). Rate limited to 2,000/day per site.
+
+**Script:** `python scripts/gsc_inspect.py --batch <file> --json`
+
+### `/seo google sitemaps <property>`
+
+List submitted sitemaps with status, errors, warnings.
+
+**Script:** `python scripts/gsc_query.py sitemaps --property <property> --json`
+
+---
+
+## Indexing API
+
+### `/seo google index <url>`
+
+Notify Google of a URL update.
+
+**Script:** `python scripts/indexing_notify.py <url> --json`
+**Reference:** `references/indexing-api.md`
+
+The Indexing API is officially for JobPosting and BroadcastEvent/VideoObject pages.
+Always inform the user of this restriction. Daily quota: 200 publish requests.
+
+### `/seo google index-batch <file>`
+
+Batch submit URLs from a file. Tracks quota usage.
+
+**Script:** `python scripts/indexing_notify.py --batch <file> --json`
+
+---
+
+## GA4 Traffic
+
+### `/seo google ga4 [property-id]`
+
+Organic traffic report: daily sessions, users, pageviews, bounce rate, engagement.
+
+**Script:** `python scripts/ga4_report.py --property <id> --json`
+**Reference:** `references/ga4-data-api.md`
+**Default:** 28 days, filtered to Organic Search channel group.
+
+### `/seo google ga4-pages [property-id]`
+
+Top organic landing pages ranked by sessions.
+
+**Script:** `python scripts/ga4_report.py --property <id> --report top-pages --json`
+
+---
+
+## YouTube (Video SEO)
+
+YouTube mentions have the strongest AI visibility correlation (0.737). Free, API key only.
+
+### `/seo google youtube <query>`
+
+Search YouTube for videos. Returns title, channel, views, likes, duration.
+
+**Script:** `python scripts/youtube_search.py search "<query>" --json`
+**Reference:** `references/youtube-api.md`
+**Quota:** 100 units per search (10,000 units/day free).
+
+### `/seo google youtube-video <video_id>`
+
+Detailed video info + tags + top 10 comments.
+
+**Script:** `python scripts/youtube_search.py video <video_id> --json`
+**Quota:** 2 units (video details + comments).
+
+---
+
+## NLP Content Analysis
+
+Google's own entity/sentiment analysis. Enhances E-E-A-T scoring.
+
+### `/seo google nlp <url-or-text>`
+
+Full NLP analysis: entities, sentiment, content classification.
+
+**Script:** `python scripts/nlp_analyze.py --url <url> --json` or `--text "..."`
+**Reference:** `references/nlp-api.md`
+**Free tier:** 5,000 units/month. Requires billing enabled on GCP project.
+
+### `/seo google entities <url-or-text>`
+
+Entity extraction only (faster, less quota).
+
+**Script:** `python scripts/nlp_analyze.py --url <url> --features entities --json`
+
+---
+
+## Keyword Research (Google Ads)
+
+Gold-standard keyword volume data. Requires Google Ads account.
+
+### `/seo google keywords <seed>`
+
+Generate keyword ideas from seed terms.
+
+**Script:** `python scripts/keyword_planner.py ideas "<seed>" --json`
+**Reference:** `references/keyword-planner-api.md`
+**Requires:** Ads developer token + customer ID in config (Tier 3).
+
+### `/seo google volume <keywords>`
+
+Search volume for specific keywords (comma-separated).
+
+**Script:** `python scripts/keyword_planner.py volume "<kw1>,<kw2>" --json`
+
+---
+
+## Supplementary
+
+### `/seo google entity <query>`
+
+Knowledge Graph entity check. Verifies brand presence.
+
+**Reference:** `references/supplementary-apis.md`
+Uses Knowledge Graph Search API with API key.
+
+### `/seo google safety <url>`
+
+Web Risk API check for malware/social engineering flags.
+
+**Reference:** `references/supplementary-apis.md`
+
+### `/seo google quotas`
+
+Display rate limits table. Read `references/rate-limits-quotas.md`.
+
+---
+
+## Reports
+
+After any analysis command, offer to generate a PDF/HTML report.
+
+### `/seo google report <type>`
+
+Generate a professional PDF report with charts and analytics.
+
+**Script:** `python scripts/google_report.py --type <type> --data <json> --domain <domain> --format pdf`
+
+| Type | Input | Output |
+|------|-------|--------|
+| `cwv-audit` | PSI + CrUX + CrUX History data | Core Web Vitals audit with gauges, timelines, distributions |
+| `gsc-performance` | GSC query data | Search Console report with query tables, quick wins |
+| `indexation` | Batch inspection data | Indexation status with coverage donut chart |
+| `full` | All data combined | Comprehensive Google SEO report (all sections) |
+
+**Workflow:**
+1. Run data collection commands (pagespeed, gsc, inspect-batch, etc.)
+2. Save JSON output to file: `python scripts/pagespeed_check.py <url> --json > data.json`
+3. Generate report: `python scripts/google_report.py --type cwv-audit --data data.json --domain <domain>`
+
+**Convention:** After completing analysis, suggest: "Generate a report? Use `/seo google report <type>`"
+
+---
+
+## Rate Limits
+
+| API | Per-Minute | Per-Day | Auth |
+|-----|-----------|---------|------|
+| PSI v5 | 240 QPM | 25,000 QPD | API Key |
+| CrUX + History | 150 QPM (shared) | Unlimited | API Key |
+| GSC Search Analytics | 1,200 QPM/site | 30M QPD | Service Account |
+| GSC URL Inspection | 600 QPM | 2,000 QPD/site | Service Account |
+| Indexing API | 380 RPM | 200 publish/day | Service Account |
+| GA4 Data API | 10 concurrent | ~25K tokens/day | Service Account |
+
+## Cross-Skill Integration
+
+- **seo-audit**: Activates `seo-google` agent for live CWV + indexation data (conditional)
+- **seo-technical**: Uses pagespeed_check.py for real CWV field data
+- **seo-performance**: CrUX field data supplements Lighthouse lab data
+- **seo-sitemap**: GSC sitemap status shows real crawl/index coverage
+- **seo-content**: GSC query data informs keyword targeting
+- **seo-geo**: GSC search appearance data includes AI Overview references
+
+## Output Format
+
+- CWV metrics: traffic-light rating (Good / Needs Improvement / Poor)
+- Performance reports: tables with sortable columns
+- Always include data freshness note
+- Save reports as `GOOGLE-API-REPORT-{domain}.md`
+- Use templates from `assets/templates/` for structured output
+
+## Technical Notes
+
+- INP replaced FID on March 12, 2024. Never reference FID.
+- CLS values from CrUX are string-encoded (e.g., "0.05"). Scripts handle parsing.
+- CrUX 404 = insufficient traffic, not an auth error.
+- Search Analytics data has 2-3 day lag.
+- `round_trip_time` replaced `effectiveConnectionType` in CrUX (Feb 2025).
+- Custom Search JSON API is closed to new customers (2025).
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| No credentials configured | Run `/seo google setup`. List Tier 0 commands that work with just an API key. |
+| Service account lacks GSC access | Report error. Instruct: add `client_email` to GSC > Settings > Users > Add. |
+| CrUX data unavailable (404) | Report insufficient Chrome traffic. Suggest PSI lab data as fallback. |
+| GA4 property not found | Report error. Show how to find property ID in GA4 Admin > Property Details. |
+| Indexing API quota exceeded | Report 200/day limit. Suggest prioritizing most important URLs. |
+| Rate limit (429) | Wait and retry with exponential backoff. Report which API hit the limit. |
+
+
+## Specialist Role Instructions
+
+When operating as a specialist during audits:
+
+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 seo-kit 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 seo-kit 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

package/.agent/skills/seo-google/assets/templates/cwv-audit-report.md

@@ -0,0 +1,48 @@
+# Core Web Vitals Audit
+
+**URL/Origin:** {target}
+**Strategy:** {strategy}
+
+## CrUX Field Data (28-day rolling average)
+
+Real Chrome user experience data from the Chrome UX Report.
+
+| Metric | p75 Value | Rating | Good Threshold | Distribution |
+|--------|-----------|--------|----------------|-------------|
+| LCP | {lcp_value} | {lcp_rating} | ≤ 2,500ms | Good: {lcp_good}% / NI: {lcp_ni}% / Poor: {lcp_poor}% |
+| INP | {inp_value} | {inp_rating} | ≤ 200ms | Good: {inp_good}% / NI: {inp_ni}% / Poor: {inp_poor}% |
+| CLS | {cls_value} | {cls_rating} | ≤ 0.1 | Good: {cls_good}% / NI: {cls_ni}% / Poor: {cls_poor}% |
+| FCP | {fcp_value} | {fcp_rating} | ≤ 1,800ms | Good: {fcp_good}% / NI: {fcp_ni}% / Poor: {fcp_poor}% |
+| TTFB | {ttfb_value} | {ttfb_rating} | ≤ 800ms | Good: {ttfb_good}% / NI: {ttfb_ni}% / Poor: {ttfb_poor}% |
+
+**Collection Period:** {collection_start} to {collection_end}
+
+## Lighthouse Lab Scores
+
+| Category | Score |
+|----------|-------|
+| Performance | {perf_score}/100 |
+| Accessibility | {a11y_score}/100 |
+| Best Practices | {bp_score}/100 |
+| SEO | {seo_score}/100 |
+
+## CrUX History Trends (25-week)
+
+| Metric | Direction | Change | Earliest → Latest |
+|--------|-----------|--------|-------------------|
+{trends_table}
+
+## Top Opportunities
+
+| Opportunity | Estimated Savings |
+|-------------|-------------------|
+{opportunities_table}
+
+## Recommendations
+
+{recommendations}
+
+---
+*CrUX data updated daily ~04:00 UTC. 28-day rolling average.*
+*INP replaced FID as the responsiveness Core Web Vital on March 12, 2024.*
+*Generated {timestamp}.*

package/.agent/skills/seo-google/assets/templates/gsc-performance-report.md

@@ -0,0 +1,44 @@
+# Google Search Console Performance Report
+
+**Property:** {property}
+**Date Range:** {start_date} — {end_date}
+**Search Type:** {search_type}
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Total Clicks | {total_clicks} |
+| Total Impressions | {total_impressions} |
+| Average CTR | {avg_ctr}% |
+| Average Position | {avg_position} |
+
+## Top Queries
+
+| # | Query | Clicks | Impressions | CTR | Position |
+|---|-------|--------|-------------|-----|----------|
+{queries_table}
+
+## Top Pages
+
+| # | Page | Clicks | Impressions | CTR | Position |
+|---|------|--------|-------------|-----|----------|
+{pages_table}
+
+## Quick Wins (Position 4-10, High Impressions)
+
+These queries rank on page 1 but below position 3. A small ranking improvement could yield significant traffic gains.
+
+| Query | Position | Impressions | Clicks | CTR | Opportunity |
+|-------|----------|-------------|--------|-----|-------------|
+{quick_wins_table}
+
+## Device Breakdown
+
+| Device | Clicks | Impressions | CTR | Position |
+|--------|--------|-------------|-----|----------|
+{device_table}
+
+---
+*Data freshness: Search Analytics has a 2-3 day lag. Data available for ~16 months.*
+*Generated {timestamp} via Google Search Console API.*

package/.agent/skills/seo-google/assets/templates/indexation-status-report.md

@@ -0,0 +1,43 @@
+# URL Indexation Status Report
+
+**Property:** {property}
+**URLs Inspected:** {total_urls}
+
+## Summary
+
+| Status | Count | Percentage |
+|--------|-------|-----------|
+| Indexed (PASS) | {pass_count} | {pass_pct}% |
+| Not Indexed (FAIL) | {fail_count} | {fail_pct}% |
+| Neutral | {neutral_count} | {neutral_pct}% |
+| Errors | {error_count} | {error_pct}% |
+
+## Detailed Results
+
+| URL | Verdict | Coverage State | Fetch State | Google Canonical | Last Crawl |
+|-----|---------|---------------|-------------|-----------------|------------|
+{results_table}
+
+## Canonical Mismatches
+
+URLs where Google selected a different canonical than declared:
+
+| URL | User Canonical | Google Canonical |
+|-----|---------------|-----------------|
+{canonical_mismatches_table}
+
+## Common Issues
+
+| Issue | Count | Priority | Action |
+|-------|-------|----------|--------|
+{issues_table}
+
+## Rich Results Detected
+
+| URL | Rich Result Type | Status |
+|-----|-----------------|--------|
+{rich_results_table}
+
+---
+*URL Inspection API: 2,000 inspections/day per site, 600/min.*
+*Generated {timestamp} via Google Search Console URL Inspection API.*

package/.agent/skills/seo-google/references/auth-setup.md

@@ -0,0 +1,154 @@
+# Google API Authentication Setup
+
+## Overview
+
+Three credential types serve different APIs:
+
+| Type | Used By | Cost |
+|------|---------|------|
+| **API Key** | PageSpeed Insights, CrUX, CrUX History, Knowledge Graph | Free |
+| **Service Account** | Search Console, Indexing API, GA4 | Free |
+| **Both** | Full seo-google skill | Free |
+
+## Step 1: Create a Google Cloud Project
+
+1. Go to [console.cloud.google.com](https://console.cloud.google.com)
+2. Click **Select a project** > **New Project**
+3. Name it (e.g., "Claude SEO") and note the project ID
+4. Select the project after creation
+
+## Step 2: Enable APIs
+
+Navigate to **APIs & Services > Library** and enable:
+
+| API | Required For |
+|-----|-------------|
+| Google Search Console API | GSC Search Analytics, URL Inspection, Sitemaps |
+| PageSpeed Insights API | PSI Lighthouse lab data |
+| Chrome UX Report API | CrUX field data + History |
+| Web Search Indexing API | Indexing API v3 |
+| Google Analytics Data API | GA4 organic traffic |
+| Knowledge Graph Search API | Entity verification (optional) |
+
+## Step 3: Create an API Key
+
+1. **APIs & Services > Credentials > Create Credentials > API key**
+2. Click **Restrict key**:
+   - Under **API restrictions**, select: PageSpeed Insights API, Chrome UX Report API, Knowledge Graph Search API
+3. Copy the key (starts with `AIzaSy...`)
+
+## Step 4: Create a Service Account
+
+1. **IAM & Admin > Service Accounts > Create Service Account**
+2. Name: `claude-seo` (or similar)
+3. Skip optional permissions steps
+4. Click on the created service account > **Keys > Add Key > Create new key > JSON**
+5. Download the JSON file and store it securely (e.g., `~/.config/claude-seo/service_account.json`)
+
+The JSON file looks like:
+```json
+{
+  "type": "service_account",
+  "project_id": "your-project-id",
+  "private_key_id": "...",
+  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
+  "client_email": "claude-seo@your-project.iam.gserviceaccount.com",
+  "client_id": "...",
+  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+  "token_uri": "https://oauth2.googleapis.com/token"
+}
+```
+
+The `client_email` field is what you add to GSC and GA4.
+
+## Step 5: Grant Search Console Access
+
+1. Go to [Google Search Console](https://search.google.com/search-console)
+2. Select your property
+3. **Settings > Users and permissions > Add user**
+4. Paste the service account `client_email`
+5. Set permission level:
+   - **Full** for read-only (Search Analytics, URL Inspection, Sitemaps)
+   - **Owner** if you also need the Indexing API
+
+## Step 6: Grant GA4 Access
+
+1. Go to [Google Analytics](https://analytics.google.com)
+2. **Admin > Property Access Management > Add users** (the + icon)
+3. Paste the service account `client_email`
+4. Set role: **Viewer** (minimum for read-only reporting)
+5. Note the numeric property ID from **Admin > Property Details** (e.g., `123456789`)
+
+## Step 7: Create Config File
+
+```bash
+mkdir -p ~/.config/claude-seo
+```
+
+Save to `~/.config/claude-seo/google-api.json`:
+
+```json
+{
+  "service_account_path": "~/.config/claude-seo/service_account.json",
+  "api_key": "AIzaSy...",
+  "default_property": "sc-domain:example.com",
+  "ga4_property_id": "properties/123456789"
+}
+```
+
+### Property URL Formats
+
+| Format | Example | When to Use |
+|--------|---------|-------------|
+| Domain property | `sc-domain:example.com` | Covers all URLs on the domain (recommended) |
+| URL-prefix property | `https://example.com/` | Covers only that specific prefix |
+
+## Step 8: Verify Setup
+
+```bash
+python scripts/google_auth.py --check
+```
+
+Expected output at Tier 2 (full):
+```
+Credential Tier: 2 -- Full (API key + Service Account + GA4)
+
+  [OK] PageSpeed Insights v5
+  [OK] Chrome UX Report (CrUX) API
+  [OK] CrUX History API
+  [OK] Google Search Console API
+       Service account: claude-seo@your-project.iam.gserviceaccount.com
+  [OK] Google Indexing API v3
+  [OK] GA4 Data API v1beta
+```
+
+## Environment Variable Alternatives
+
+Instead of (or in addition to) the config file:
+
+| Variable | Purpose |
+|----------|---------|
+| `GOOGLE_API_KEY` | API key for PSI/CrUX |
+| `GOOGLE_APPLICATION_CREDENTIALS` | Path to service account JSON |
+| `GA4_PROPERTY_ID` | GA4 property (e.g., `properties/123456789`) |
+| `GSC_PROPERTY` | Default GSC property (e.g., `sc-domain:example.com`) |
+
+## OAuth Scopes Used
+
+| Scope | APIs |
+|-------|------|
+| `https://www.googleapis.com/auth/webmasters.readonly` | GSC (read) |
+| `https://www.googleapis.com/auth/webmasters` | GSC (read/write, needed for sitemap submission) |
+| `https://www.googleapis.com/auth/indexing` | Indexing API |
+| `https://www.googleapis.com/auth/analytics.readonly` | GA4 (read) |
+
+## Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| `403 Forbidden` on GSC | Service account email not added to GSC property, or wrong permission level |
+| `403 Forbidden` on GA4 | Service account email not added to GA4 property as Viewer |
+| `404 Not Found` on GSC | Wrong property URL format. Use `sc-domain:` or include trailing slash for URL-prefix |
+| `404 Not Found` on CrUX | Site has insufficient Chrome traffic. Not a credentials issue. |
+| `429 Rate Limit` | Wait and retry. See rate-limits-quotas.md for per-API limits |
+| `API not enabled` | Enable the specific API in GCP Console > APIs & Services > Library |