v1.4.0: Supply chain security, GEO agent, URL normalization, SPA Phase 2

Security:
- Replace irm|iex Windows install with git clone + powershell -File as primary
  method. Claude Code's own guardrails flagged the old pattern as supply chain
  risk (community-reported). Added collapsible review-before-running option.
- Version pin install.sh and install.ps1 to REPO_TAG (v1.3.0 default) instead
  of cloning main branch silently
- Harden Invoke-External in install.ps1 with PSNativeCommandUseErrorActionPreference
  handling (incorporates fixes from PR #13 and PR #15)

GEO:
- Deploy agents/seo-geo.md — /seo audit now spawns 7 parallel agents (was 6)
- Add seo-geo to orchestrator spawn list and Subagents section in seo/SKILL.md
- Increase AI Search Readiness weight from 5% to 10% (Technical 25→22%, Content 25→23%)
- Nuanced FAQPage guidance in SKILL.md, seo-schema.md, schema-types.md — existing
  FAQPage on commercial sites is Info not Critical (GEO/LLM citation benefit)

Fixes (from community PRs):
- URL normalization in capture_screenshot.py and analyze_visual.py via shared
  normalize_url() helper — bare domains now work (from PR #16 by @shuofengzhang)
- Googlebot UA flag in fetch_page.py for prerender/SPA detection (Issue #11 Phase 2)
- Python requirement corrected to 3.10+ in README and docs/INSTALLATION.md
- seo-geo added to uninstall.sh and uninstall.ps1 agent removal lists

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: AgriciDaniel

.gitignore

@@ -47,3 +47,24 @@ screenshots/
 # Temporary analysis files
 *-AUDIT-REPORT.md
 *-ACTION-PLAN.md
+FULL-AUDIT-REPORT.md
+ACTION-PLAN.md
+GEO-ANALYSIS.md
+SCHEMA-REPORT.md
+SITEMAP-REPORT*.md
+VALIDATION-REPORT.md
+
+# Generated artifacts from audits
+charts/
+*.pdf
+report.html
+generated-schema.json
+rankenstein-schema-audit.md
+capture_closeups.py
+capture_desktop.py
+generate_charts.py
+generate_pdf.py
+
+# Debug logs
+firebase-debug.log
+firebase-debug.*.log

CHANGELOG.md

@@ -5,6 +5,30 @@ 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.4.0] - 2026-03-12
+
+### Security
+- **Install script supply chain fix**: Replaced `irm | iex` Windows PowerShell one-liner with `git clone + powershell -File` as primary install method. Claude Code's own security guardrails flagged the old pattern as a supply chain risk (reported by community member). Added collapsible "review before running" section for Unix curl method.
+- **Version pinning**: `install.sh` and `install.ps1` now clone a specific release tag (`v1.3.0`) by default rather than `main`, preventing silent updates. Override with `CLAUDE_SEO_TAG=main`.
+- **PowerShell Invoke-External hardening**: Comprehensive `PSNativeCommandUseErrorActionPreference` handling in `Invoke-External` wrapper (fixes Windows git clone stderr false-positive termination, from PR #13 + PR #15).
+
+### Added
+- **GEO agent deployed**: `agents/seo-geo.md` created — `/seo audit` now spawns 7 parallel agents (was 6). GEO analysis covers AI crawler access, llms.txt, passage-level citability, brand mention signals, platform-specific scoring (Google AI Overviews, ChatGPT, Perplexity, Bing Copilot).
+- **`--googlebot` flag in `fetch_page.py`**: Detect prerender/dynamic rendering services by comparing response size with default UA vs Googlebot UA. First phase of SPA/CSR support (Issue #11).
+
+### Fixed
+- **URL normalization**: `capture_screenshot.py` and `analyze_visual.py` now accept bare domains (`example.com` → `https://example.com`) via shared `normalize_url()` helper (from PR #16 by @shuofengzhang).
+- **GEO weight**: AI Search Readiness weight increased from 5% to 10% in overall SEO Health Score. Technical SEO adjusted to 22%, Content Quality to 23%.
+- **FAQPage guidance**: Blanket "remove FAQPage on commercial sites" updated to nuanced guidance — existing FAQPage → Info priority (not Critical), noting AI/LLM citation benefit. Adding new FAQPage → not recommended for Google, note AI benefit. Updated in `seo/SKILL.md`, `agents/seo-schema.md`, `seo/references/schema-types.md`.
+- **Uninstall agents list**: Added `seo-geo` to `uninstall.sh` and `uninstall.ps1` removal lists.
+- **Python requirement**: Corrected from `3.8+` to `3.10+` in `README.md` and `docs/INSTALLATION.md`.
+
+### Changed
+- Subagent count: 6 → 7 (added seo-geo to core audit pipeline)
+- `.gitignore`: Added generated audit artifacts (charts/, PDFs, report.html, firebase-debug.log, generated-schema.json)
+
+---
+
 ## [1.3.0] - 2026-03-06
 
 ### Added

README.md

@@ -13,7 +13,15 @@ Comprehensive SEO analysis skill for Claude Code. Covers technical SEO, on-page
 
 ## Installation
 
-### One-Command Install (Unix/macOS/Linux)
+### Recommended Install (Unix/macOS/Linux)
+
+```bash
+git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
+bash claude-seo/install.sh
+```
+
+<details>
+<summary>One-liner (curl)</summary>
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh | bash
@@ -25,20 +33,26 @@ Or via [install.cat](https://install.cat):
 curl -fsSL install.cat/AgriciDaniel/claude-seo | bash
 ```
 
-### Manual Install
+Prefer to review the script before running?
 
 ```bash
-git clone https://github.com/AgriciDaniel/claude-seo.git
-cd claude-seo
-./install.sh
+curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh > install.sh
+cat install.sh        # review
+bash install.sh       # run when satisfied
+rm install.sh
 ```
 
-### Windows
+</details>
+
+### Windows (PowerShell)
 
 ```powershell
-irm https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.ps1 | iex
+git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
+powershell -ExecutionPolicy Bypass -File claude-seo\install.ps1
 ```
 
+> **Why git clone instead of `irm | iex`?** Claude Code's own security guardrails flag `irm ... | iex` as a supply chain risk (downloading and executing remote code with no verification). The git clone approach lets you inspect the script at `claude-seo\install.ps1` before running it.
+
 ## Quick Start
 
 ```bash
@@ -186,16 +200,26 @@ See `schema/templates.json` for ready-to-use JSON-LD snippets.
 
 ## Requirements
 
-- Python 3.8+
+- Python 3.10+
 - Claude Code CLI
 - Optional: Playwright for screenshots
 
 ## Uninstall
 
+```bash
+git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
+bash claude-seo/uninstall.sh
+```
+
+<details>
+<summary>One-liner (curl)</summary>
+
 ```bash
 curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/uninstall.sh | bash
 ```
 
+</details>
+
 ### MCP Integrations
 
 Integrates with MCP servers for live SEO data — including official servers from **Ahrefs** (`@ahrefs/mcp`) and **Semrush**, plus community servers for Google Search Console, PageSpeed Insights, and DataForSEO. See [MCP Integration Guide](docs/MCP-INTEGRATION.md) for setup.

TODO.md

@@ -49,6 +49,25 @@
 - [ ] **Brand mention analysis Python implementation** (Priority: Low)
   Currently documented in `seo-geo/SKILL.md` but no programmatic scoring.
 
+## SPA / Client-Side Rendering Support (Issue #11)
+
+Phase 2 (merged in v1.4.0):
+- [x] **`--googlebot` flag in fetch_page.py** — Compare response size with default UA vs Googlebot UA to detect prerender services
+
+Remaining phases (deferred):
+
+- [ ] **Phase 1: render_page.py** (Priority: High) — Playwright-based page renderer that exports fully-rendered DOM HTML. CLI: `python render_page.py https://example.com --output rendered.html`. Drop-in complement to `fetch_page.py`.
+
+- [ ] **Phase 3: Screenshot DOM export** (Priority: Medium) — Add `--export-html` flag to `capture_screenshot.py` so rendered DOM is available to other agents without a second browser launch.
+
+- [ ] **Phase 4: Orchestrator SPA detection** (Priority: High) — Add 6 SPA detection signals to `seo/SKILL.md` (empty root div, minimal body, prerenderReady, framework markers, large JS bundles, React/Vue/Angular attributes). Route agents to raw vs rendered HTML based on detection result.
+
+- [ ] **Phase 5: Agent updates** (Priority: High) — Update seo-technical, seo-content, seo-schema, seo-performance, seo-visual to use rendered DOM when SPA detected. Add WRS (Web Rendering Service) dependency risk deductions.
+
+- [ ] **Phase 6: SPA scoring methodology** (Priority: Medium) — Separate scoring paths for SPAs with/without prerender. New "Rendering Architecture Assessment" report section.
+
+- [ ] **Phase 7: Reference file updates** (Priority: Low) — Add SPA section to quality-gates.md, eeat-framework.md, cwv-thresholds.md (Soft Navigations API guidance).
+
 ---
 
-*Last updated: February 19, 2026*
+*Last updated: March 12, 2026*

agents/seo-geo.md

@@ -0,0 +1,62 @@
+---
+name: seo-geo
+description: GEO and AI search specialist. Analyzes AI crawler accessibility, llms.txt compliance, passage-level citability, brand mention signals, and platform-specific optimization for Google AI Overviews, ChatGPT, Perplexity, and Bing Copilot.
+tools: Read, Bash, WebFetch, Glob, Grep
+---
+
+You are a Generative Engine Optimization (GEO) specialist. When given a URL:
+
+1. Fetch the page and check robots.txt for AI crawler rules
+2. Check for `/llms.txt` and RSL 1.0 licensing
+3. Analyze content citability (passage length, structure, directness)
+4. Evaluate authority signals (authorship, dates, citations, entity presence)
+5. Assess technical accessibility for AI crawlers (SSR vs CSR)
+6. Score across 5 dimensions and generate prioritized recommendations
+
+## GEO Health Score (0-100)
+
+| Dimension | Weight |
+|-----------|--------|
+| Citability | 25% |
+| Structural Readability | 20% |
+| Multi-Modal Content | 15% |
+| Authority & Brand Signals | 20% |
+| Technical Accessibility | 20% |
+
+## AI Crawlers to Check in robots.txt
+
+Allow for AI search visibility: GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot
+Optional block (training only): CCBot, anthropic-ai, cohere-ai
+
+## Key Citability Signals
+
+- Optimal passage length: **134-167 words** for AI citation
+- Direct answers in first 40-60 words of each section
+- Question-based H2/H3 headings
+- Specific statistics with source attribution
+- Self-contained answer blocks (extractable without context)
+
+## Brand Mention Correlation with AI Citations
+
+| Signal | Correlation |
+|--------|-------------|
+| YouTube mentions | ~0.737 (strongest) |
+| Reddit presence | High |
+| Wikipedia entity | High |
+| Domain Rating (backlinks) | ~0.266 (weak) |
+
+Only 11% of domains are cited by both ChatGPT and Google AI Overviews — platform optimization matters.
+
+## DataForSEO Integration (Optional)
+
+If DataForSEO MCP tools are available, use `ai_optimization_chat_gpt_scraper` for live ChatGPT visibility and `ai_opt_llm_ment_search` for LLM mention tracking.
+
+## Output Format
+
+Provide a structured report with:
+- GEO Readiness Score (0-100) with dimension breakdown
+- AI Crawler Access Status (allowed/blocked per crawler)
+- llms.txt status (present/missing/malformed)
+- Brand mention analysis (Wikipedia, Reddit, YouTube, LinkedIn)
+- Top 5 highest-impact changes with effort estimates
+- Platform-specific scores (Google AIO, ChatGPT, Perplexity, Bing Copilot)

agents/seo-schema.md

@@ -22,7 +22,9 @@ When analyzing pages:
 - **CourseInfo, EstimatedSalary, LearningVideo**: Retired June 2025
 
 ### Restricted Schema:
-- **FAQ**: ONLY for government and healthcare authority sites (restricted August 2023)
+- **FAQ**: Google rich results restricted to government and healthcare sites (August 2023).
+  - **Existing FAQPage on commercial sites**: Flag as Info priority (not Critical) — FAQPage still benefits AI/LLM citations even without Google rich results.
+  - **Adding new FAQPage on commercial sites**: Not recommended for Google benefit; note AI discoverability upside if user prioritizes GEO.
 
 ### Always Prefer:
 - JSON-LD format over Microdata or RDFa

docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-- **Python 3.8+** with pip
+- **Python 3.10+** with pip
 - **Git** for cloning the repository
 - **Claude Code CLI** installed and configured
 

install.ps1

@@ -30,8 +30,26 @@ function Invoke-External {
         [switch]$Quiet
     )
 
-    $output = & $Exe @Args 2>&1
-    $exitCode = $LASTEXITCODE
+    $previousErrorActionPreference = $ErrorActionPreference
+    $hasNativePreference = $null -ne (Get-Variable -Name PSNativeCommandUseErrorActionPreference -ErrorAction SilentlyContinue)
+    if ($hasNativePreference) {
+        $previousNativePreference = $PSNativeCommandUseErrorActionPreference
+    }
+
+    try {
+        $ErrorActionPreference = 'Continue'
+        if ($hasNativePreference) {
+            $PSNativeCommandUseErrorActionPreference = $false
+        }
+
+        $output = & $Exe @Args 2>&1 | ForEach-Object { $_.ToString() }
+        $exitCode = $LASTEXITCODE
+    } finally {
+        $ErrorActionPreference = $previousErrorActionPreference
+        if ($hasNativePreference) {
+            $PSNativeCommandUseErrorActionPreference = $previousNativePreference
+        }
+    }
 
     if (-not $Quiet -and $null -ne $output -and $output.Count -gt 0) {
         $output | ForEach-Object { Write-Host $_ }
@@ -67,6 +85,9 @@ try {
 $SkillDir = "$env:USERPROFILE\.claude\skills\seo"
 $AgentDir = "$env:USERPROFILE\.claude\agents"
 $RepoUrl = "https://github.com/AgriciDaniel/claude-seo"
+# Pin to a specific release tag to prevent silent updates from main.
+# Override: $env:CLAUDE_SEO_TAG = 'main'; .\install.ps1
+$RepoTag = if ($env:CLAUDE_SEO_TAG) { $env:CLAUDE_SEO_TAG } else { 'v1.3.0' }
 
 # Create directories
 New-Item -ItemType Directory -Force -Path $SkillDir | Out-Null
@@ -81,8 +102,8 @@ if (Test-Path $TempDir) {
 $keepTemp = ($env:CLAUDE_SEO_KEEP_TEMP -eq '1')
 
 try {
-    Write-Host "↓ Downloading Claude SEO..." -ForegroundColor Yellow
-    $clone = Invoke-External -Exe 'git' -Args @('clone','--depth','1',$RepoUrl,$TempDir) -Quiet
+    Write-Host "↓ Downloading Claude SEO ($RepoTag)..." -ForegroundColor Yellow
+    $clone = Invoke-External -Exe 'git' -Args @('clone','--depth','1','--branch',$RepoTag,$RepoUrl,$TempDir) -Quiet
     if ($clone.ExitCode -ne 0) {
         throw "git clone failed. Output:`n$($clone.Output -join "`n")"
     }

install.sh

@@ -8,6 +8,9 @@ main() {
     SKILL_DIR="${HOME}/.claude/skills/seo"
     AGENT_DIR="${HOME}/.claude/agents"
     REPO_URL="https://github.com/AgriciDaniel/claude-seo"
+    # Pin to a specific release tag to prevent silent updates from main.
+    # Override: CLAUDE_SEO_TAG=main bash install.sh
+    REPO_TAG="${CLAUDE_SEO_TAG:-v1.3.0}"
 
     echo "════════════════════════════════════════"
     echo "║   Claude SEO - Installer             ║"
@@ -36,8 +39,8 @@ main() {
     TEMP_DIR=$(mktemp -d)
     trap "rm -rf ${TEMP_DIR}" EXIT
 
-    echo "↓ Downloading Claude SEO..."
-    git clone --depth 1 "${REPO_URL}" "${TEMP_DIR}/claude-seo" 2>/dev/null
+    echo "↓ Downloading Claude SEO (${REPO_TAG})..."
+    git clone --depth 1 --branch "${REPO_TAG}" "${REPO_URL}" "${TEMP_DIR}/claude-seo" 2>/dev/null
 
     # Copy skill files
     echo "→ Installing skill files..."

scripts/analyze_visual.py

@@ -11,7 +11,7 @@
 import json
 import socket
 import sys
-from urllib.parse import urlparse
+from urllib.parse import ParseResult, urlparse
 
 try:
     from playwright.sync_api import sync_playwright, TimeoutError as PlaywrightTimeout
@@ -20,6 +20,21 @@
     sys.exit(1)
 
 
+def normalize_url(url: str) -> tuple[str, ParseResult]:
+    """Normalize URL and return (url, parsed_url)."""
+    parsed = urlparse(url)
+    if not parsed.scheme:
+        url = f"https://{url}"
+        parsed = urlparse(url)
+
+    if parsed.scheme not in ("http", "https"):
+        raise ValueError(f"Invalid URL scheme: {parsed.scheme}")
+    if not parsed.hostname:
+        raise ValueError("Invalid URL: missing hostname")
+
+    return url, parsed
+
+
 def analyze_visual(url: str, timeout: int = 30000) -> dict:
     """
     Analyze visual aspects of a web page.
@@ -54,15 +69,21 @@ def analyze_visual(url: str, timeout: int = 30000) -> dict:
         "error": None,
     }
 
+    try:
+        url, parsed = normalize_url(url)
+        result["url"] = url
+    except ValueError as e:
+        result["error"] = str(e)
+        return result
+
     # SSRF prevention: block private/internal IPs
     try:
-        parsed = urlparse(url)
         resolved_ip = socket.gethostbyname(parsed.hostname)
         ip = ipaddress.ip_address(resolved_ip)
         if ip.is_private or ip.is_loopback or ip.is_reserved:
             result["error"] = f"Blocked: URL resolves to private/internal IP ({resolved_ip})"
             return result
-    except (socket.gaierror, ValueError):
+    except socket.gaierror:
         pass
 
     try: