bmad-plus 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to BMAD+ 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).
 
+## [0.3.1] — 2026-03-19
+
+### 🔧 SEO Engine Enhancements (Sprint 1)
+
+### Added
+- **SKILL.md orchestrator** — Single entry point routing 15 `/seo` commands to the right agents
+- **seo_apis.py** — Google APIs client (PageSpeed Insights, CrUX field data, Rich Results Test)
+- **requirements.txt** — Python dependencies (requests, beautifulsoup4, lxml)
+- **install.sh + install.ps1** — Cross-platform dependency installer with venv support
+
+---
+
 ## [0.3.0] — 2026-03-19
 
 ### 🚀 SEO Engine v2.0 — Complete Rewrite

package/oveanet-pack/seo-audit-360/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: seo-engine
+description: >
+  BMAD+ SEO Engine v2.1 — Complete SEO audit engine with 3 multi-role agents,
+  6-phase workflow, Python toolkit, Google API integration, and PageSpeed
+  perfection loop. Use when user says /seo or any SEO-related command.
+---
+
+# SEO Engine — Orchestrator
+
+> By Laurent Rochetta | BMAD+ SEO Engine v2.1
+
+## Quick Start
+
+This skill orchestrates 3 specialized agents through a structured workflow.
+Load the full agent files only when activating that agent's phase.
+
+## Command Router
+
+When the user issues a `/seo` command, route as follows:
+
+| Command | Agent(s) | Action |
+|---------|----------|--------|
+| `/seo full <url>` | Scout → Judge → Chief | Run all 6 phases |
+| `/seo quick <url>` | Scout → Judge → Chief | Run phases 1–4 only |
+| `/seo technical <url>` | Scout (Inspector) | Phase 2 technical only |
+| `/seo content <url>` | Judge (Content Expert) | Phase 2 content only |
+| `/seo geo <url>` | Judge (GEO Analyst) | Phase 3 only |
+| `/seo schema <url>` | Judge (Schema Master) | Schema detection + validation |
+| `/seo images <url>` | Judge (Content Expert) | Image audit subset |
+| `/seo hreflang <url>` | Scout (Inspector) | Hreflang audit, ref: `ref/hreflang-rules.md` |
+| `/seo pagespeed <url>` | Scout + Chief | PageSpeed perfection loop |
+| `/seo plan <type>` | Chief (Strategist) | Strategic plan by industry |
+| `/seo fix` | Chief (Strategist) | Auto-generate fixes from last audit |
+| `/seo history` | Chief (Reporter) | Show score history |
+| `/seo compare` | Chief (Reporter) | Compare with previous audit |
+| `/seo competitor <url1> <url2>` | Scout + Judge + Chief | Benchmark two sites |
+| `/seo api <url>` | (script) | Run Google APIs (PSI + CrUX + Rich Results) |
+
+## Full Audit Orchestration (`/seo full`)
+
+### Phase 1 — Reconnaissance
+**Agent**: Scout (Crawler role)
+**Load**: `agent/seo-scout.md`
+
+1. Run `scripts/seo_fetch.py <url> --json` to fetch homepage
+2. Run `scripts/seo_crawl.py <url> --depth 2 --max 25 --json` to discover structure
+3. Detect business type from content analysis:
+   - **SaaS**: pricing page, features page, signup CTA
+   - **E-commerce**: product pages, cart, categories
+   - **Local business**: address, phone, map, opening hours
+   - **Publisher**: articles, blog, news, RSS feed
+   - **Agency**: services, portfolio, case studies
+4. Check for `/robots.txt`, `/sitemap.xml`, `/llms.txt`
+
+**Checkpoint**: Report discovery summary, ask "Continue with full audit?"
+
+### Phase 2 — Deep Scan (PARALLEL)
+**Agents**: Scout (Inspector) + Judge (Content Expert + Schema Master)
+**Load**: `agent/seo-scout.md` + `agent/seo-judge.md`
+
+Run Scout and Judge **simultaneously** on each discovered page:
+
+**Scout checks** (9 categories — see `agent/seo-scout.md`):
+- Crawlability, Indexability, Security, URL Structure, Mobile
+- Core Web Vitals, Structured Data detection, JS Rendering, IndexNow
+
+**Judge checks** (see `agent/seo-judge.md`):
+- E-E-A-T evaluation (ref: `ref/eeat-criteria.md`)
+- Content quality (ref: `ref/quality-gates.md`)
+- Schema validation (ref: `ref/schema-catalog.md`)
+- Image audit
+- Internal/external link analysis
+
+**Optional**: Run `scripts/seo_apis.py --all <url>` for live PageSpeed + CrUX data.
+
+Use `scripts/seo_parse.py <file> --url <url> --json` on fetched HTML.
+Use `scripts/seo_screenshot.py <url> --viewport mobile` for visual audit.
+
+### Phase 3 — AI Readiness & GEO
+**Agent**: Judge (GEO Analyst role)
+**Reference**: `ref/geo-signals.md`
+
+- Check AI crawler access (GPTBot, ClaudeBot, PerplexityBot)
+- Verify llms.txt compliance
+- Score passage citability (134–167 word blocks)
+- Compute AI Readiness Score (0–100)
+
+### Phase 4 — Scoring
+**Agent**: Chief (Scorer role)
+**Load**: `agent/seo-chief.md`
+
+Compute SEO Health Score (0–100):
+
+| Category | Weight |
+|----------|--------|
+| Technical SEO | 20% |
+| Content & E-E-A-T | 22% |
+| On-Page SEO | 18% |
+| Schema | 10% |
+| Performance (CWV) | 12% |
+| AI Readiness (GEO) | 12% |
+| Images | 6% |
+
+### Phase 5 — Action Plan
+**Agent**: Chief (Strategist role)
+
+1. Classify issues: 🔴 Critical → 🟠 High → 🟡 Medium → 🟢 Low
+2. Identify quick wins (highest impact/effort ratio)
+3. Generate 30/60/90-day roadmap
+4. Auto-generate code fixes (meta tags, schema JSON-LD, robots.txt, llms.txt)
+
+**Checkpoint**: "Here's the plan. Apply fixes automatically?"
+
+### Phase 5b — PageSpeed Perfection Loop
+**Agents**: Scout + Chief
+**Reference**: `pagespeed-playbook.md` + `checklist.md`
+
+Use `scripts/seo_apis.py --pagespeed <url>` for live scores.
+Loop: fix one issue → re-test → verify improvement → next issue.
+Target: 100% on all 4 categories (Performance, Accessibility, Best Practices, SEO).
+
+### Phase 6 — Monitoring (optional)
+**Agent**: Scout (Crawler role)
+
+Save results to `.bmad-seo/history/<domain>-<date>.json`.
+On re-audit: compare with previous, show deltas.
+
+---
+
+## Python Toolkit
+
+| Script | Usage | Dependencies |
+|--------|-------|-------------|
+| `seo_fetch.py` | `python scripts/seo_fetch.py <url> [--ua googlebot] [--json]` | requests |
+| `seo_parse.py` | `python scripts/seo_parse.py <file> --url <url> --json` | beautifulsoup4, lxml |
+| `seo_crawl.py` | `python scripts/seo_crawl.py <url> --depth 2 --max 25 --json` | requests |
+| `seo_screenshot.py` | `python scripts/seo_screenshot.py <url> --viewport mobile` | playwright |
+| `seo_apis.py` | `python scripts/seo_apis.py --pagespeed <url>` | requests |
+
+**Install dependencies**: `pip install -r requirements.txt`
+
+**Environment**: Set `GOOGLE_API_KEY` for Google API access (free, no OAuth).
+
+---
+
+## Reference Files (lazy-load)
+
+Only load these when the relevant agent needs them:
+- `ref/cwv-thresholds.md` — Core Web Vitals 2026
+- `ref/schema-catalog.md` — Schema.org v29.4 types
+- `ref/eeat-criteria.md` — E-E-A-T scoring grid
+- `ref/geo-signals.md` — AI search signals
+- `ref/quality-gates.md` — Content thresholds
+- `ref/schema-templates.json` — 14 JSON-LD templates
+
+---
+
+## Industry-Specific Plans (`/seo plan <type>`)
+
+| Type | Focus |
+|------|-------|
+| `saas` | Pricing pages, feature comparison, trial CTAs, documentation SEO |
+| `ecommerce` | Product schema, category pages, faceted navigation, review markup |
+| `local` | LocalBusiness schema, Google Business Profile, location pages, NAP consistency |
+| `publisher` | Article schema, author E-E-A-T, news sitemap, pagination |
+| `agency` | Service schema, portfolio, case studies, city-specific landing pages |
+
+---
+
+*BMAD+ SEO Engine v2.1 — By Laurent Rochetta*

package/oveanet-pack/seo-audit-360/requirements.txt

@@ -0,0 +1,14 @@
+# BMAD+ SEO Engine — Python Dependencies
+# Install: pip install -r requirements.txt
+# Author: Laurent Rochetta
+
+# Core (required)
+requests>=2.31.0
+beautifulsoup4>=4.12.0
+
+# Fast HTML parser (recommended)
+lxml>=5.0.0
+
+# Screenshot capture (optional — only for seo_screenshot.py)
+# Uncomment and run: playwright install chromium
+# playwright>=1.40.0

package/oveanet-pack/seo-audit-360/scripts/install.ps1

@@ -0,0 +1,53 @@
+# BMAD+ SEO Engine — Dependency Installer (Windows)
+# Author: Laurent Rochetta
+
+$ErrorActionPreference = "Stop"
+
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$ParentDir = Split-Path -Parent $ScriptDir
+
+Write-Host "🔧 BMAD+ SEO Engine — Installing dependencies..." -ForegroundColor Cyan
+Write-Host ""
+
+# Check Python
+$Python = $null
+if (Get-Command python -ErrorAction SilentlyContinue) {
+    $Python = "python"
+} elseif (Get-Command py -ErrorAction SilentlyContinue) {
+    $Python = "py -3"
+} else {
+    Write-Host "❌ Python not found. Please install Python 3.10+" -ForegroundColor Red
+    exit 1
+}
+
+Write-Host "Using: $(& $Python --version)"
+
+# Create venv if not exists
+$VenvPath = Join-Path $ParentDir ".venv"
+if (-not (Test-Path $VenvPath)) {
+    Write-Host "📦 Creating virtual environment..."
+    & $Python -m venv $VenvPath
+}
+
+# Activate venv
+$ActivateScript = Join-Path $VenvPath "Scripts\Activate.ps1"
+if (Test-Path $ActivateScript) {
+    & $ActivateScript
+}
+
+# Install dependencies
+Write-Host "📥 Installing core dependencies..."
+$RequirementsPath = Join-Path $ParentDir "requirements.txt"
+& $Python -m pip install --quiet -r $RequirementsPath
+
+Write-Host ""
+Write-Host "✅ Core dependencies installed!" -ForegroundColor Green
+Write-Host ""
+Write-Host "Optional: To enable screenshots (seo_screenshot.py):"
+Write-Host "  pip install playwright; playwright install chromium"
+Write-Host ""
+Write-Host "Set your Google API key for live data:"
+Write-Host '  $env:GOOGLE_API_KEY = "your_key_here"'
+Write-Host "  Get one free: https://console.cloud.google.com/apis/credentials"
+Write-Host ""
+Write-Host "🚀 Ready! — BMAD+ SEO Engine by Laurent Rochetta" -ForegroundColor Cyan

package/oveanet-pack/seo-audit-360/scripts/install.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# BMAD+ SEO Engine — Dependency Installer (Linux/macOS)
+# Author: Laurent Rochetta
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PARENT_DIR="$(dirname "$SCRIPT_DIR")"
+
+echo "🔧 BMAD+ SEO Engine — Installing dependencies..."
+echo ""
+
+# Check Python
+if command -v python3 &>/dev/null; then
+    PYTHON=python3
+elif command -v python &>/dev/null; then
+    PYTHON=python
+else
+    echo "❌ Python not found. Please install Python 3.10+"
+    exit 1
+fi
+
+echo "Using: $($PYTHON --version)"
+
+# Create venv if not exists
+if [ ! -d "$PARENT_DIR/.venv" ]; then
+    echo "📦 Creating virtual environment..."
+    $PYTHON -m venv "$PARENT_DIR/.venv"
+fi
+
+# Activate venv
+source "$PARENT_DIR/.venv/bin/activate" 2>/dev/null || true
+
+# Install core dependencies
+echo "📥 Installing core dependencies..."
+$PYTHON -m pip install --quiet -r "$PARENT_DIR/requirements.txt"
+
+echo ""
+echo "✅ Core dependencies installed!"
+echo ""
+echo "Optional: To enable screenshots (seo_screenshot.py):"
+echo "  pip install playwright && playwright install chromium"
+echo ""
+echo "Set your Google API key for live data:"
+echo "  export GOOGLE_API_KEY=your_key_here"
+echo "  Get one free: https://console.cloud.google.com/apis/credentials"
+echo ""
+echo "🚀 Ready! — BMAD+ SEO Engine by Laurent Rochetta"

package/oveanet-pack/seo-audit-360/scripts/seo_apis.py

@@ -0,0 +1,464 @@
+#!/usr/bin/env python3
+"""
+SEO APIs — Google free API client for live SEO data.
+
+Connects to:
+- PageSpeed Insights API v5 (lab scores + audits)
+- Chrome UX Report (CrUX) API (field CWV data)
+- Rich Results Test API (schema validation)
+
+Requires: GOOGLE_API_KEY environment variable (free, no OAuth).
+Get one at: https://console.cloud.google.com/apis/credentials
+
+Author: Laurent Rochetta
+License: MIT
+"""
+
+import argparse
+import json
+import os
+import sys
+from typing import Optional
+
+try:
+    import requests
+except ImportError:
+    print("Error: requests required. Install: pip install requests", file=sys.stderr)
+    sys.exit(1)
+
+
+API_KEY = os.environ.get("GOOGLE_API_KEY", "")
+
+PSI_ENDPOINT = "https://www.googleapis.com/pagespeedonline/v5/runPagespeed"
+CRUX_ENDPOINT = "https://chromeuxreport.googleapis.com/v1/records:queryRecord"
+RICH_RESULTS_ENDPOINT = "https://searchconsole.googleapis.com/v1/urlTestingTools/mobileFriendlyTest:run"
+
+
+# ── PageSpeed Insights ─────────────────────────────────────────────
+
+def run_pagespeed(url: str, strategy: str = "mobile", categories: Optional[list] = None) -> dict:
+    """
+    Run PageSpeed Insights audit.
+
+    Args:
+        url: URL to audit
+        strategy: "mobile" or "desktop"
+        categories: List of categories (PERFORMANCE, ACCESSIBILITY, BEST_PRACTICES, SEO)
+
+    Returns:
+        Structured result with scores, audits, and opportunities
+    """
+    if not API_KEY:
+        return {"error": "GOOGLE_API_KEY not set. Get one at https://console.cloud.google.com/apis/credentials"}
+
+    if categories is None:
+        categories = ["PERFORMANCE", "ACCESSIBILITY", "BEST_PRACTICES", "SEO"]
+
+    params = {
+        "url": url,
+        "key": API_KEY,
+        "strategy": strategy,
+    }
+    for cat in categories:
+        params.setdefault("category", [])
+        if isinstance(params["category"], list):
+            params["category"].append(cat)
+
+    # requests needs category as repeated param
+    param_str = f"url={url}&key={API_KEY}&strategy={strategy}"
+    for cat in categories:
+        param_str += f"&category={cat}"
+
+    try:
+        response = requests.get(f"{PSI_ENDPOINT}?{param_str}", timeout=120)
+        response.raise_for_status()
+        data = response.json()
+    except requests.RequestException as e:
+        return {"error": f"PSI API request failed: {e}"}
+
+    # Extract scores
+    result = {
+        "url": url,
+        "strategy": strategy,
+        "scores": {},
+        "cwv": {},
+        "failing_audits": [],
+        "opportunities": [],
+    }
+
+    # Category scores
+    categories_data = data.get("lighthouseResult", {}).get("categories", {})
+    for cat_id, cat_data in categories_data.items():
+        score = cat_data.get("score", 0)
+        result["scores"][cat_id] = round(score * 100)
+
+    # Core Web Vitals from Lighthouse
+    audits = data.get("lighthouseResult", {}).get("audits", {})
+
+    cwv_metrics = {
+        "largest-contentful-paint": "LCP",
+        "interaction-to-next-paint": "INP",
+        "cumulative-layout-shift": "CLS",
+        "first-contentful-paint": "FCP",
+        "total-blocking-time": "TBT",
+        "speed-index": "SI",
+    }
+
+    for audit_id, label in cwv_metrics.items():
+        if audit_id in audits:
+            audit = audits[audit_id]
+            result["cwv"][label] = {
+                "value": audit.get("numericValue"),
+                "display": audit.get("displayValue", ""),
+                "score": round(audit.get("score", 0) * 100),
+            }
+
+    # Failing audits (score < 1.0)
+    for audit_id, audit in audits.items():
+        score = audit.get("score")
+        if score is not None and score < 0.9 and audit.get("title"):
+            severity = "critical" if score < 0.5 else "warning"
+            result["failing_audits"].append({
+                "id": audit_id,
+                "title": audit.get("title", ""),
+                "description": audit.get("description", "")[:200],
+                "score": round(score * 100),
+                "severity": severity,
+                "display_value": audit.get("displayValue", ""),
+            })
+
+    # Sort failures by score (worst first)
+    result["failing_audits"].sort(key=lambda x: x["score"])
+
+    # Opportunities (have savings)
+    for audit_id, audit in audits.items():
+        details = audit.get("details", {})
+        if details.get("type") == "opportunity" and details.get("overallSavingsMs", 0) > 0:
+            result["opportunities"].append({
+                "id": audit_id,
+                "title": audit.get("title", ""),
+                "savings_ms": details.get("overallSavingsMs", 0),
+                "savings_bytes": details.get("overallSavingsBytes", 0),
+            })
+
+    result["opportunities"].sort(key=lambda x: x["savings_ms"], reverse=True)
+
+    # Field data (CrUX from PSI response)
+    loading_exp = data.get("loadingExperience", {})
+    if loading_exp.get("metrics"):
+        result["field_data"] = {}
+        for metric_id, metric_data in loading_exp["metrics"].items():
+            result["field_data"][metric_id] = {
+                "percentile": metric_data.get("percentile"),
+                "category": metric_data.get("category"),
+            }
+
+    return result
+
+
+# ── CrUX API ───────────────────────────────────────────────────────
+
+def run_crux(url: str, form_factor: str = "PHONE") -> dict:
+    """
+    Query Chrome UX Report for real-world performance data.
+
+    Args:
+        url: URL or origin to query
+        form_factor: PHONE, DESKTOP, or ALL_FORM_FACTORS
+
+    Returns:
+        Field CWV data at 75th percentile
+    """
+    if not API_KEY:
+        return {"error": "GOOGLE_API_KEY not set"}
+
+    # Try URL-level first, fall back to origin
+    from urllib.parse import urlparse
+    parsed = urlparse(url)
+    origin = f"{parsed.scheme}://{parsed.netloc}"
+
+    payload = {
+        "url": url,
+        "formFactor": form_factor,
+    }
+
+    try:
+        response = requests.post(
+            f"{CRUX_ENDPOINT}?key={API_KEY}",
+            json=payload,
+            timeout=30,
+        )
+
+        if response.status_code == 404:
+            # No URL-level data, try origin
+            payload = {"origin": origin, "formFactor": form_factor}
+            response = requests.post(
+                f"{CRUX_ENDPOINT}?key={API_KEY}",
+                json=payload,
+                timeout=30,
+            )
+
+        if response.status_code == 404:
+            return {"error": f"No CrUX data available for {url} (not enough traffic)"}
+
+        response.raise_for_status()
+        data = response.json()
+    except requests.RequestException as e:
+        return {"error": f"CrUX API request failed: {e}"}
+
+    result = {
+        "url": url,
+        "form_factor": form_factor,
+        "metrics": {},
+        "collection_period": {},
+    }
+
+    # Extract metrics
+    metrics = data.get("record", {}).get("metrics", {})
+
+    metric_map = {
+        "largest_contentful_paint": "LCP",
+        "interaction_to_next_paint": "INP",
+        "cumulative_layout_shift": "CLS",
+        "first_contentful_paint": "FCP",
+        "experimental_time_to_first_byte": "TTFB",
+    }
+
+    for api_name, label in metric_map.items():
+        if api_name in metrics:
+            m = metrics[api_name]
+            p75 = m.get("percentiles", {}).get("p75")
+            histogram = m.get("histogram", [])
+
+            # Calculate good/needs-improvement/poor distribution
+            distribution = {}
+            for bucket in histogram:
+                density = bucket.get("density", 0)
+                if bucket.get("end"):
+                    distribution["good"] = distribution.get("good", 0) + density
+                elif "start" in bucket and "end" not in bucket:
+                    distribution["poor"] = density
+                else:
+                    distribution["needs_improvement"] = density
+
+            result["metrics"][label] = {
+                "p75": p75,
+                "distribution": distribution,
+            }
+
+    # Collection period
+    period = data.get("record", {}).get("collectionPeriod", {})
+    result["collection_period"] = {
+        "first_date": period.get("firstDate", {}),
+        "last_date": period.get("lastDate", {}),
+    }
+
+    return result
+
+
+# ── Rich Results Test ──────────────────────────────────────────────
+
+def run_rich_results_test(url: str) -> dict:
+    """
+    Check if a URL is eligible for rich results.
+
+    Note: This uses the URL Testing Tools API (Mobile-Friendly Test)
+    which also returns rich results information. The dedicated Rich Results
+    Test API requires OAuth2, so we use this free alternative.
+
+    Args:
+        url: URL to test
+
+    Returns:
+        Mobile-friendly status and detected structured data
+    """
+    if not API_KEY:
+        return {"error": "GOOGLE_API_KEY not set"}
+
+    payload = {"url": url}
+
+    try:
+        response = requests.post(
+            f"{RICH_RESULTS_ENDPOINT}?key={API_KEY}",
+            json=payload,
+            timeout=60,
+        )
+        response.raise_for_status()
+        data = response.json()
+    except requests.RequestException as e:
+        return {"error": f"URL Testing API request failed: {e}"}
+
+    result = {
+        "url": url,
+        "mobile_friendly": data.get("mobileFriendliness") == "MOBILE_FRIENDLY",
+        "issues": [],
+    }
+
+    for issue in data.get("mobileFriendlyIssues", []):
+        result["issues"].append({
+            "rule": issue.get("rule", ""),
+        })
+
+    return result
+
+
+# ── Unified Runner ─────────────────────────────────────────────────
+
+def run_all(url: str) -> dict:
+    """Run all available API checks and merge results."""
+    print(f"Running PageSpeed Insights (mobile)...", file=sys.stderr)
+    psi_mobile = run_pagespeed(url, strategy="mobile")
+
+    print(f"Running PageSpeed Insights (desktop)...", file=sys.stderr)
+    psi_desktop = run_pagespeed(url, strategy="desktop")
+
+    print(f"Running CrUX API...", file=sys.stderr)
+    crux = run_crux(url)
+
+    print(f"Running Mobile-Friendly Test...", file=sys.stderr)
+    rich = run_rich_results_test(url)
+
+    return {
+        "url": url,
+        "timestamp": __import__("datetime").datetime.utcnow().isoformat() + "Z",
+        "pagespeed": {
+            "mobile": psi_mobile,
+            "desktop": psi_desktop,
+        },
+        "crux": crux,
+        "mobile_friendly": rich,
+    }
+
+
+# ── CLI ────────────────────────────────────────────────────────────
+
+def print_psi_summary(result: dict, label: str):
+    """Print a human-readable PSI summary."""
+    if result.get("error"):
+        print(f"  Error: {result['error']}")
+        return
+
+    scores = result.get("scores", {})
+    print(f"\n  {label} Scores:")
+    for cat, score in scores.items():
+        icon = "🟢" if score >= 90 else "🟡" if score >= 50 else "🔴"
+        cat_name = cat.replace("_", " ").replace("-", " ").title()
+        print(f"    {icon} {cat_name}: {score}/100")
+
+    cwv = result.get("cwv", {})
+    if cwv:
+        print(f"\n  Core Web Vitals:")
+        for metric, data in cwv.items():
+            icon = "🟢" if data["score"] >= 90 else "🟡" if data["score"] >= 50 else "🔴"
+            print(f"    {icon} {metric}: {data['display']} ({data['score']}/100)")
+
+    failures = result.get("failing_audits", [])[:5]
+    if failures:
+        print(f"\n  Top Failing Audits:")
+        for audit in failures:
+            icon = "🔴" if audit["severity"] == "critical" else "🟠"
+            print(f"    {icon} {audit['title']} ({audit['score']}/100)")
+
+    opps = result.get("opportunities", [])[:3]
+    if opps:
+        print(f"\n  Top Opportunities:")
+        for opp in opps:
+            print(f"    💡 {opp['title']} (save {opp['savings_ms']}ms)")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="SEO APIs — Google free API client (BMAD+ SEO Engine)"
+    )
+    parser.add_argument("url", nargs="?", help="URL to analyze")
+    parser.add_argument("--pagespeed", action="store_true", help="Run PageSpeed Insights")
+    parser.add_argument("--crux", action="store_true", help="Run CrUX API")
+    parser.add_argument("--richtest", action="store_true", help="Run Rich Results Test")
+    parser.add_argument("--all", action="store_true", help="Run all APIs")
+    parser.add_argument("--strategy", choices=["mobile", "desktop"], default="mobile",
+                        help="PSI strategy (default: mobile)")
+    parser.add_argument("--json", "-j", action="store_true", help="Output as JSON")
+
+    args = parser.parse_args()
+
+    if not args.url:
+        parser.print_help()
+        sys.exit(1)
+
+    if not API_KEY:
+        print("⚠️  GOOGLE_API_KEY not set!", file=sys.stderr)
+        print("   Get a free key: https://console.cloud.google.com/apis/credentials", file=sys.stderr)
+        print("   Enable: PageSpeed Insights API + Chrome UX Report API", file=sys.stderr)
+        print("   Set: export GOOGLE_API_KEY=your_key", file=sys.stderr)
+        sys.exit(1)
+
+    if args.all:
+        result = run_all(args.url)
+        if args.json:
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(f"\n{'='*60}")
+            print(f"SEO API Report: {args.url}")
+            print(f"{'='*60}")
+            print_psi_summary(result["pagespeed"]["mobile"], "📱 Mobile")
+            print_psi_summary(result["pagespeed"]["desktop"], "🖥️  Desktop")
+
+            crux = result["crux"]
+            if not crux.get("error"):
+                print(f"\n  📊 CrUX Field Data:")
+                for metric, data in crux.get("metrics", {}).items():
+                    print(f"    {metric}: p75 = {data['p75']}")
+            else:
+                print(f"\n  📊 CrUX: {crux['error']}")
+
+            mf = result["mobile_friendly"]
+            if not mf.get("error"):
+                icon = "✅" if mf["mobile_friendly"] else "❌"
+                print(f"\n  📱 Mobile-Friendly: {icon}")
+            else:
+                print(f"\n  📱 Mobile-Friendly: {mf['error']}")
+
+    elif args.pagespeed:
+        result = run_pagespeed(args.url, strategy=args.strategy)
+        if args.json:
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print_psi_summary(result, f"{'📱 Mobile' if args.strategy == 'mobile' else '🖥️  Desktop'}")
+
+    elif args.crux:
+        result = run_crux(args.url)
+        if args.json:
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            if result.get("error"):
+                print(f"Error: {result['error']}")
+            else:
+                print(f"\nCrUX Field Data: {args.url}")
+                for metric, data in result.get("metrics", {}).items():
+                    print(f"  {metric}: p75 = {data['p75']}")
+
+    elif args.richtest:
+        result = run_rich_results_test(args.url)
+        if args.json:
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            if result.get("error"):
+                print(f"Error: {result['error']}")
+            else:
+                icon = "✅" if result["mobile_friendly"] else "❌"
+                print(f"Mobile-Friendly: {icon}")
+                if result["issues"]:
+                    for issue in result["issues"]:
+                        print(f"  ⚠️ {issue['rule']}")
+
+    else:
+        # Default: run pagespeed
+        result = run_pagespeed(args.url, strategy=args.strategy)
+        if args.json:
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print_psi_summary(result, f"{'📱 Mobile' if args.strategy == 'mobile' else '🖥️  Desktop'}")
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-plus",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "BMAD+ — Augmented AI-Driven Development Framework with multi-role agents, autopilot, and parallel execution",
   "keywords": [
     "bmad",