bmad-plus 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.2] — 2026-03-19
+
+### 📊 SEO Engine — Reports, Competitor & Hreflang (Sprint 2)
+
+### Added
+- **seo_report.py** — Professional HTML report generator with inline SVG radar chart, color-coded issue cards, quick wins section, and print-friendly CSS
+- **Benchmarker role** — Added to Chief agent for `/seo competitor` command (side-by-side site comparison with delta scoring)
+- **hreflang-rules.md** — Complete hreflang audit reference with 7 validation rules, 6 common error patterns, and 12-point checklist
+
+---
+
+## [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/agent/seo-chief.md

@@ -29,6 +29,25 @@ You are **Chief**, the strategist and reporting agent of the BMAD+ SEO Engine. Y
 - Generate executive summary for non-technical stakeholders
 - Create monitoring comparison reports (vs previous audit)
 - Format reports for different audiences (developer, marketing, executive)
+- Generate **HTML reports** via `scripts/seo_report.py` from audit JSON
+
+### Role: Benchmarker
+**Trigger**: `/seo competitor`, competitive analysis, benchmark
+- Run full audit on **two sites simultaneously** (Scout + Judge on each)
+- Compare scores side-by-side with delta indicators:
+
+| Metric | My Site | Competitor | Delta |
+|--------|---------|-----------|-------|
+| SEO Score | 72 | 85 | -13 🔴 |
+| E-E-A-T | 65 | 78 | -13 🔴 |
+| Schema types | 3 | 7 | -4 🟠 |
+| GEO/AI Score | 55 | 70 | -15 🔴 |
+| PageSpeed | 92 | 88 | +4 🟢 |
+
+- Identify **competitive gaps** (where rival is better)
+- Identify **competitive advantages** (where we're better)
+- Generate actionable plan: "To match competitor, prioritize: ..."
+- Output: Markdown comparison report + optional HTML via `seo_report.py`
 
 ---
 

package/oveanet-pack/seo-audit-360/ref/hreflang-rules.md

@@ -0,0 +1,153 @@
+# Hreflang — Audit Rules & Best Practices (March 2026)
+
+> Author: Laurent Rochetta | BMAD+ SEO Engine v2.0
+
+## What is Hreflang?
+
+`hreflang` tells search engines which language/region version of a page to serve.
+Errors cause wrong language indexing, duplicate content penalties, and lost organic traffic.
+
+---
+
+## Implementation Methods
+
+| Method | Best For | Max Pages |
+|--------|----------|-----------|
+| `<link>` in `<head>` | Small sites (<50 pages) | ~50 |
+| HTTP header `Link:` | Non-HTML files (PDFs) | ~50 |
+| Sitemap `<xhtml:link>` | Large sites (50+) | Unlimited |
+
+> **Recommendation**: Use sitemap for sites with 50+ pages. HTTP headers for non-HTML resources.
+
+---
+
+## Validation Rules
+
+### Rule 1: Valid Language Codes
+- Use **ISO 639-1** (2-letter): `en`, `fr`, `de`, `es`, `ja`, `zh`
+- Optional **ISO 3166-1 Alpha-2** for region: `en-US`, `en-GB`, `fr-FR`, `fr-CA`, `pt-BR`
+- **Case insensitive** but convention is lowercase lang, uppercase country
+
+| ✅ Valid | ❌ Invalid | Why |
+|---------|-----------|-----|
+| `en` | `english` | Must be ISO 639-1 |
+| `fr-FR` | `fr-FRA` | Country must be 2-letter |
+| `zh-Hans` | `cn` | `cn` is not a valid language code |
+| `x-default` | `default` | Must use exact `x-default` |
+
+### Rule 2: Self-Referencing (MANDATORY)
+Every page MUST include a hreflang tag pointing to itself.
+
+```html
+<!-- On the English page (example.com/en/) -->
+<link rel="alternate" hreflang="en" href="https://example.com/en/" />
+<link rel="alternate" hreflang="fr" href="https://example.com/fr/" />
+<link rel="alternate" hreflang="x-default" href="https://example.com/en/" />
+```
+
+**Error if missing**: Google may ignore all hreflang tags on that page.
+
+### Rule 3: Return Tags (MANDATORY)
+If page A links to page B with hreflang, page B MUST link back to page A.
+
+```
+Page A (en) → hreflang="fr" → Page B (fr)
+Page B (fr) → hreflang="en" → Page A (en)   ← MANDATORY
+```
+
+**Error if missing**: Called "orphan hreflang" — Google ignores the one-way tag.
+
+### Rule 4: x-default (STRONGLY RECOMMENDED)
+Designate a fallback page for users whose language/region doesn't match any variant.
+
+```html
+<link rel="alternate" hreflang="x-default" href="https://example.com/" />
+```
+
+Common choices for x-default:
+- Language selector/redirect page
+- English version (most common)
+- Homepage of the main domain
+
+### Rule 5: Canonical + Hreflang Consistency
+- Each hreflang URL **must be the canonical version** (not a redirect, not a URL with parameters)
+- If a page has `rel="canonical"` pointing elsewhere, hreflang tags on that page are **ignored**
+- Canonical and hreflang must agree: don't have hreflang point to a URL that canonicalizes to a different URL
+
+### Rule 6: Absolute URLs Only
+```html
+<!-- ✅ Correct -->
+<link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
+
+<!-- ❌ Wrong -->
+<link rel="alternate" hreflang="fr" href="/fr/page" />
+```
+
+### Rule 7: No Hreflang on Non-200 Pages
+- Don't include hreflang tags on pages that return 3xx, 4xx, or 5xx
+- Don't point hreflang to pages that redirect
+
+---
+
+## Common Error Patterns
+
+### Error 1: Missing Return Tags
+**Symptom**: hreflang is configured on the main language but not on alternate versions.
+**Fix**: Add reciprocal hreflang tags on ALL language variants.
+
+### Error 2: Wrong Canonical + Hreflang
+**Symptom**: Page A hreflang → Page B, but Page B canonical → Page C.
+**Fix**: Align canonical and hreflang targets.
+
+### Error 3: Missing Self-Reference
+**Symptom**: Page lists other language versions but not itself.
+**Fix**: Add `hreflang` tag with the current page's own language/URL.
+
+### Error 4: Inconsistent URLs
+**Symptom**: hreflang uses `http://` but site is on `https://`, or trailing slash mismatch.
+**Fix**: Use exact canonical URL (protocol, www/non-www, trailing slash).
+
+### Error 5: Language vs Region Confusion
+**Symptom**: Using `hreflang="fr"` for France and `hreflang="fr"` for Canada.
+**Fix**: Use `hreflang="fr-FR"` and `hreflang="fr-CA"` to differentiate.
+
+### Error 6: Missing x-default
+**Symptom**: Users in unsupported regions see random language version.
+**Fix**: Add `x-default` pointing to language selector or English version.
+
+---
+
+## Sitemap Implementation (Recommended for 50+ pages)
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
+        xmlns:xhtml="http://www.w3.org/1999/xhtml">
+  <url>
+    <loc>https://example.com/en/page</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/page"/>
+    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page"/>
+    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/page"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/en/page"/>
+  </url>
+</urlset>
+```
+
+---
+
+## Audit Checklist
+
+| # | Check | Priority |
+|---|-------|----------|
+| 1 | All hreflang language codes are valid ISO 639-1 | 🔴 Critical |
+| 2 | All hreflang country codes are valid ISO 3166-1 | 🔴 Critical |
+| 3 | Every page has self-referencing hreflang | 🔴 Critical |
+| 4 | All hreflang tags have return tags | 🔴 Critical |
+| 5 | All hreflang URLs are absolute | 🔴 Critical |
+| 6 | x-default is specified | 🟠 High |
+| 7 | Hreflang URLs match canonical URLs | 🟠 High |
+| 8 | No hreflang on non-200 pages | 🟠 High |
+| 9 | No hreflang pointing to redirecting URLs | 🟠 High |
+| 10 | Consistent protocol (https) and www/non-www | 🟡 Medium |
+| 11 | Language/region differentiation correct | 🟡 Medium |
+| 12 | Sitemap implementation for 50+ pages | 🟡 Medium |

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/oveanet-pack/seo-audit-360/scripts/seo_report.py

@@ -0,0 +1,403 @@
+#!/usr/bin/env python3
+"""
+SEO Report — Professional HTML audit report generator.
+
+Features:
+- Single-file HTML with inline CSS (no external deps)
+- SVG radar chart for score visualization
+- Color-coded issue cards (Critical/High/Medium/Low)
+- Quick Wins section
+- Print-friendly (@media print)
+- Responsive (mobile-readable)
+
+Author: Laurent Rochetta
+License: MIT
+"""
+
+import argparse
+import json
+import math
+import os
+import sys
+from datetime import datetime
+
+
+def generate_radar_svg(scores: dict, size: int = 300) -> str:
+    """Generate an SVG radar chart for the 7 score categories."""
+    categories = list(scores.keys())
+    values = list(scores.values())
+    n = len(categories)
+
+    if n == 0:
+        return ""
+
+    cx, cy = size // 2, size // 2
+    radius = size // 2 - 40
+
+    # Short labels for display
+    short_labels = {
+        "technical": "Tech",
+        "content_eeat": "E-E-A-T",
+        "on_page": "On-Page",
+        "schema": "Schema",
+        "performance": "Perf",
+        "ai_readiness": "AI/GEO",
+        "images": "Images",
+    }
+
+    def point(angle_deg, r):
+        angle_rad = math.radians(angle_deg - 90)
+        x = cx + r * math.cos(angle_rad)
+        y = cy + r * math.sin(angle_rad)
+        return x, y
+
+    svg_parts = [f'<svg viewBox="0 0 {size} {size}" xmlns="http://www.w3.org/2000/svg" style="max-width:{size}px;margin:auto;display:block;">']
+
+    # Background circles
+    for pct in [25, 50, 75, 100]:
+        r = radius * pct / 100
+        svg_parts.append(f'<circle cx="{cx}" cy="{cy}" r="{r}" fill="none" stroke="#e2e8f0" stroke-width="1" opacity="0.5"/>')
+
+    # Axis lines + labels
+    for i in range(n):
+        angle = (360 / n) * i
+        x1, y1 = point(angle, 0)
+        x2, y2 = point(angle, radius)
+        svg_parts.append(f'<line x1="{cx}" y1="{cy}" x2="{x2}" y2="{y2}" stroke="#e2e8f0" stroke-width="1"/>')
+
+        lx, ly = point(angle, radius + 20)
+        label = short_labels.get(categories[i], categories[i][:6])
+        svg_parts.append(f'<text x="{lx}" y="{ly}" text-anchor="middle" font-size="11" fill="#64748b" font-family="Inter,sans-serif">{label}</text>')
+
+    # Data polygon
+    data_points = []
+    for i in range(n):
+        angle = (360 / n) * i
+        r = radius * min(values[i], 100) / 100
+        x, y = point(angle, r)
+        data_points.append(f"{x},{y}")
+
+    poly = " ".join(data_points)
+    svg_parts.append(f'<polygon points="{poly}" fill="rgba(59,130,246,0.2)" stroke="#3b82f6" stroke-width="2"/>')
+
+    # Data points
+    for i in range(n):
+        angle = (360 / n) * i
+        r = radius * min(values[i], 100) / 100
+        x, y = point(angle, r)
+        color = "#22c55e" if values[i] >= 80 else "#f59e0b" if values[i] >= 50 else "#ef4444"
+        svg_parts.append(f'<circle cx="{x}" cy="{y}" r="4" fill="{color}" stroke="white" stroke-width="2"/>')
+
+    svg_parts.append('</svg>')
+    return "\n".join(svg_parts)
+
+
+def severity_color(severity: str) -> str:
+    """Get color for severity level."""
+    return {
+        "critical": "#ef4444",
+        "high": "#f97316",
+        "medium": "#f59e0b",
+        "low": "#22c55e",
+    }.get(severity, "#64748b")
+
+
+def severity_icon(severity: str) -> str:
+    return {
+        "critical": "🔴",
+        "high": "🟠",
+        "medium": "🟡",
+        "low": "🟢",
+    }.get(severity, "⚪")
+
+
+def score_color(score: int) -> str:
+    if score >= 90:
+        return "#22c55e"
+    elif score >= 70:
+        return "#84cc16"
+    elif score >= 50:
+        return "#f59e0b"
+    else:
+        return "#ef4444"
+
+
+def generate_html_report(audit_data: dict) -> str:
+    """Generate a complete HTML report from audit JSON data."""
+
+    domain = audit_data.get("domain", "Unknown")
+    timestamp = audit_data.get("timestamp", datetime.now().isoformat())
+    total_score = audit_data.get("score", {}).get("total", 0)
+    categories = audit_data.get("score", {}).get("categories", {})
+    issues = audit_data.get("issues", [])
+    pages = audit_data.get("pages", [])
+
+    # Generate radar chart
+    radar_svg = generate_radar_svg(categories) if categories else ""
+
+    # Sort issues by severity
+    severity_order = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+    sorted_issues = sorted(issues, key=lambda x: severity_order.get(x.get("severity", "low"), 4))
+
+    # Count by severity
+    counts = {"critical": 0, "high": 0, "medium": 0, "low": 0}
+    for issue in issues:
+        sev = issue.get("severity", "low")
+        counts[sev] = counts.get(sev, 0) + 1
+
+    # Quick wins
+    quick_wins = [i for i in issues if i.get("quick_win", False)][:5]
+
+    # Build issue cards HTML
+    issue_cards = ""
+    for issue in sorted_issues:
+        sev = issue.get("severity", "low")
+        fix_html = ""
+        if issue.get("fix"):
+            fix_html = f'<div class="fix-block"><strong>Fix:</strong><pre><code>{issue["fix"]}</code></pre></div>'
+
+        issue_cards += f'''
+        <div class="issue-card" style="border-left: 4px solid {severity_color(sev)}">
+            <div class="issue-header">
+                <span class="severity-badge" style="background:{severity_color(sev)}">{sev.upper()}</span>
+                <span class="issue-category">{issue.get("category", "")}</span>
+            </div>
+            <h4>{issue.get("title", "")}</h4>
+            <p>{issue.get("description", "")}</p>
+            {fix_html}
+        </div>'''
+
+    # Quick wins HTML
+    qw_html = ""
+    if quick_wins:
+        qw_items = ""
+        for qw in quick_wins:
+            qw_items += f'<li>{severity_icon(qw.get("severity", ""))} {qw.get("title", "")}</li>'
+        qw_html = f'<div class="quick-wins"><h3>⚡ Quick Wins</h3><ul>{qw_items}</ul></div>'
+
+    # Category scores table
+    cat_rows = ""
+    for cat, score in categories.items():
+        cat_name = cat.replace("_", " ").title()
+        cat_rows += f'''
+        <tr>
+            <td>{cat_name}</td>
+            <td>
+                <div class="score-bar-bg">
+                    <div class="score-bar" style="width:{score}%;background:{score_color(score)}"></div>
+                </div>
+            </td>
+            <td style="color:{score_color(score)};font-weight:700">{score}</td>
+        </tr>'''
+
+    html = f'''<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>SEO Audit Report — {domain}</title>
+    <style>
+        @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
+
+        * {{ margin: 0; padding: 0; box-sizing: border-box; }}
+        body {{
+            font-family: 'Inter', -apple-system, sans-serif;
+            background: #f8fafc;
+            color: #1e293b;
+            line-height: 1.6;
+        }}
+        .container {{ max-width: 900px; margin: 0 auto; padding: 2rem; }}
+
+        /* Header */
+        .header {{
+            background: linear-gradient(135deg, #0f172a 0%, #1e3a5f 100%);
+            color: white;
+            padding: 3rem 2rem;
+            border-radius: 16px;
+            margin-bottom: 2rem;
+            text-align: center;
+        }}
+        .header h1 {{ font-size: 2rem; margin-bottom: 0.5rem; }}
+        .header .domain {{ font-size: 1.2rem; opacity: 0.8; }}
+        .header .date {{ font-size: 0.85rem; opacity: 0.6; margin-top: 0.5rem; }}
+
+        /* Score circle */
+        .score-hero {{
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            gap: 3rem;
+            margin: 2rem 0;
+            flex-wrap: wrap;
+        }}
+        .score-circle {{
+            width: 150px;
+            height: 150px;
+            border-radius: 50%;
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            border: 6px solid {score_color(total_score)};
+            background: white;
+            box-shadow: 0 4px 24px rgba(0,0,0,0.08);
+        }}
+        .score-number {{ font-size: 3rem; font-weight: 700; color: {score_color(total_score)}; }}
+        .score-label {{ font-size: 0.75rem; text-transform: uppercase; color: #64748b; letter-spacing: 1px; }}
+
+        /* Summary cards */
+        .summary-grid {{
+            display: grid;
+            grid-template-columns: repeat(4, 1fr);
+            gap: 1rem;
+            margin-bottom: 2rem;
+        }}
+        .summary-card {{
+            background: white;
+            border-radius: 12px;
+            padding: 1.2rem;
+            text-align: center;
+            box-shadow: 0 2px 8px rgba(0,0,0,0.04);
+        }}
+        .summary-card .count {{ font-size: 2rem; font-weight: 700; }}
+        .summary-card .label {{ font-size: 0.8rem; color: #64748b; }}
+
+        /* Sections */
+        .section {{ background: white; border-radius: 12px; padding: 2rem; margin-bottom: 1.5rem; box-shadow: 0 2px 8px rgba(0,0,0,0.04); }}
+        .section h2 {{ margin-bottom: 1rem; font-size: 1.3rem; }}
+        .section h3 {{ margin-bottom: 0.8rem; font-size: 1.1rem; }}
+
+        /* Score bars */
+        table {{ width: 100%; border-collapse: collapse; }}
+        td {{ padding: 0.6rem 0; }}
+        .score-bar-bg {{ width: 100%; height: 8px; background: #e2e8f0; border-radius: 4px; overflow: hidden; margin: 0 1rem; }}
+        .score-bar {{ height: 100%; border-radius: 4px; transition: width 0.5s ease; }}
+
+        /* Issue cards */
+        .issue-card {{
+            border: 1px solid #e2e8f0;
+            border-radius: 8px;
+            padding: 1rem;
+            margin-bottom: 0.8rem;
+        }}
+        .issue-header {{ display: flex; gap: 0.5rem; margin-bottom: 0.3rem; align-items: center; }}
+        .severity-badge {{ color: white; padding: 2px 8px; border-radius: 4px; font-size: 0.7rem; font-weight: 600; }}
+        .issue-category {{ font-size: 0.8rem; color: #64748b; }}
+        .issue-card h4 {{ margin-bottom: 0.3rem; }}
+        .issue-card p {{ color: #475569; font-size: 0.9rem; }}
+        .fix-block {{ background: #f1f5f9; border-radius: 6px; padding: 0.8rem; margin-top: 0.5rem; }}
+        .fix-block pre {{ overflow-x: auto; font-size: 0.8rem; }}
+
+        /* Quick wins */
+        .quick-wins {{ background: #f0fdf4; border: 1px solid #bbf7d0; border-radius: 12px; padding: 1.5rem; margin-bottom: 1.5rem; }}
+        .quick-wins ul {{ list-style: none; padding: 0; }}
+        .quick-wins li {{ padding: 0.3rem 0; }}
+
+        /* Footer */
+        .footer {{ text-align: center; color: #94a3b8; font-size: 0.8rem; padding: 2rem 0; }}
+
+        /* Print */
+        @media print {{
+            body {{ background: white; }}
+            .container {{ max-width: 100%; padding: 0; }}
+            .header {{ break-after: avoid; }}
+            .section {{ break-inside: avoid; box-shadow: none; border: 1px solid #e2e8f0; }}
+        }}
+
+        /* Mobile */
+        @media (max-width: 640px) {{
+            .summary-grid {{ grid-template-columns: repeat(2, 1fr); }}
+            .score-hero {{ flex-direction: column; gap: 1.5rem; }}
+        }}
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="header">
+            <h1>SEO Audit Report</h1>
+            <div class="domain">{domain}</div>
+            <div class="date">{timestamp[:10]}</div>
+        </div>
+
+        <div class="score-hero">
+            <div class="score-circle">
+                <div class="score-number">{total_score}</div>
+                <div class="score-label">SEO Score</div>
+            </div>
+            <div>
+                {radar_svg}
+            </div>
+        </div>
+
+        <div class="summary-grid">
+            <div class="summary-card">
+                <div class="count" style="color:#ef4444">{counts["critical"]}</div>
+                <div class="label">Critical</div>
+            </div>
+            <div class="summary-card">
+                <div class="count" style="color:#f97316">{counts["high"]}</div>
+                <div class="label">High</div>
+            </div>
+            <div class="summary-card">
+                <div class="count" style="color:#f59e0b">{counts["medium"]}</div>
+                <div class="label">Medium</div>
+            </div>
+            <div class="summary-card">
+                <div class="count" style="color:#22c55e">{counts["low"]}</div>
+                <div class="label">Low</div>
+            </div>
+        </div>
+
+        {qw_html}
+
+        <div class="section">
+            <h2>📊 Category Scores</h2>
+            <table>{cat_rows}</table>
+        </div>
+
+        <div class="section">
+            <h2>🔍 Issues ({len(issues)})</h2>
+            {issue_cards}
+        </div>
+
+        <div class="footer">
+            Generated by BMAD+ SEO Engine v2.1 — By Laurent Rochetta
+        </div>
+    </div>
+</body>
+</html>'''
+
+    return html
+
+
+# ── CLI ────────────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="SEO Report — HTML audit report generator (BMAD+ SEO Engine)"
+    )
+    parser.add_argument("input", help="Audit JSON file")
+    parser.add_argument("--output", "-o", default="seo-report.html", help="Output HTML file")
+
+    args = parser.parse_args()
+
+    if not os.path.isfile(args.input):
+        print(f"Error: File not found: {args.input}", file=sys.stderr)
+        sys.exit(1)
+
+    with open(args.input, "r", encoding="utf-8") as f:
+        audit_data = json.load(f)
+
+    html = generate_html_report(audit_data)
+
+    with open(args.output, "w", encoding="utf-8") as f:
+        f.write(html)
+
+    print(f"✅ Report generated: {args.output}", file=sys.stderr)
+    print(f"   Domain: {audit_data.get('domain', 'Unknown')}")
+    print(f"   Score: {audit_data.get('score', {}).get('total', 0)}/100")
+    print(f"   Issues: {len(audit_data.get('issues', []))}")
+
+
+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.2",
   "description": "BMAD+ — Augmented AI-Driven Development Framework with multi-role agents, autopilot, and parallel execution",
   "keywords": [
     "bmad",