bmad-plus 0.4.1 → 0.4.3

package/src/bmad-plus/agents/pack-seo/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/src/bmad-plus/agents/pack-seo/checklist.md

@@ -0,0 +1,140 @@
+# SEO/GEO 360° Audit Checklist
+
+## Usage
+Use this checklist as a template for any website audit. Copy it to your project's output folder and check items as you go.
+
+---
+
+## 1. Technical SEO
+- [ ] `robots.txt` exists and is correctly configured
+- [ ] `sitemap.xml` exists with all pages, `lastmod`, `changefreq`, `priority`
+- [ ] Sitemap includes `xhtml:link` hreflang alternates (if multilingual)
+- [ ] Canonical URLs present on all pages
+- [ ] Hreflang tags for each language variant
+- [ ] Meta robots: `index, follow, max-image-preview:large, max-snippet:-1`
+- [ ] HTTPS enforced
+- [ ] No render-blocking resources (fonts preloaded, CSS inlined or local)
+- [ ] Mobile viewport meta tag present
+- [ ] Favicon present (SVG preferred, fallback PNG)
+- [ ] 404 error page exists
+- [ ] Page load time < 3 seconds
+
+## 2. On-Page SEO
+- [ ] `<title>` tag: 50-60 chars, contains primary keyword, unique per page
+- [ ] `<meta description>`: 150-160 chars, contains CTA, unique per page
+- [ ] `<meta keywords>`: relevant long-tail keywords
+- [ ] `<meta author>`: present
+- [ ] Single `<h1>` per page, descriptive, keyword-rich
+- [ ] Logical H2-H6 hierarchy
+- [ ] Images: `alt` tags, `width`/`height`, `loading="lazy"`, WebP format
+- [ ] Internal linking between pages
+- [ ] External links: `rel="noopener"` on `target="_blank"`
+- [ ] Content length adequate (300+ words for landing pages)
+
+## 3. Schema.org / Structured Data
+- [ ] Primary schema type (Organization/LocalBusiness/ProfessionalService)
+- [ ] Service schema for each service offered
+- [ ] FAQPage schema with real Q&As (minimum 5 questions)
+- [ ] WebPage schema (datePublished, dateModified, inLanguage)
+- [ ] BreadcrumbList schema
+- [ ] Person schema for founder/team (if applicable)
+- [ ] Review/AggregateRating schema (if applicable)
+- [ ] Validated with Google Rich Results Test
+
+## 4. GEO (Generative Engine Optimization)
+- [ ] `llms.txt` file at site root with structured business info
+- [ ] Content uses clear headings with question-based format
+- [ ] FAQ section with expandable answers
+- [ ] Concise, factual content per section (answers visible without interaction)
+- [ ] AI crawlers allowed in `robots.txt`:
+  - [ ] GPTBot
+  - [ ] ChatGPT-User
+  - [ ] PerplexityBot
+  - [ ] ClaudeBot
+  - [ ] Google-Extended
+- [ ] Content freshness: `dateModified` in schema, visible update dates
+- [ ] E-E-A-T signals: author credentials, "About" info, LinkedIn links
+- [ ] Tested queries in ChatGPT, Perplexity, and Gemini
+
+## 5. Local SEO
+- [ ] Geo meta tags: `geo.region`, `geo.placename`, `geo.position`, `ICBM`
+- [ ] NAP (Name, Address, Phone/Email) in footer
+- [ ] `<address>` HTML element used
+- [ ] Schema includes `geo` (GeoCoordinates), `areaServed`, `address`
+- [ ] Google Business Profile created and optimized
+- [ ] Local keywords in title, description, and H1
+- [ ] Citations on directories (Pages Jaunes, Google Maps, etc.)
+
+## 6. Accessibility
+- [ ] Skip navigation link
+- [ ] `aria-hidden="true"` on decorative SVGs and elements
+- [ ] `aria-label` on `<section>` and `<nav>` elements
+- [ ] `aria-pressed` on toggle buttons
+- [ ] Color contrast WCAG AA (4.5:1 minimum)
+- [ ] Keyboard-navigable form elements
+- [ ] `<html lang>` attribute set correctly (dynamic for multilingual)
+- [ ] `prefers-reduced-motion` media query support
+
+## 7. Social & Sharing
+- [ ] Open Graph: `og:title`, `og:description`, `og:image`, `og:url`, `og:type`
+- [ ] `og:site_name` present
+- [ ] `og:locale` with `og:locale:alternate` for other languages
+- [ ] `og:image` dimensions 1200×630px
+- [ ] Twitter Card: `twitter:card` (summary_large_image)
+- [ ] Social preview tested with sharing debugger tools
+
+## 8. Multilingual SEO (if applicable)
+- [ ] `<html lang>` dynamic based on selected language
+- [ ] Bilingual `<title>` and `<meta description>` (via server-side logic)
+- [ ] Hreflang tags for each page × each language
+- [ ] `x-default` hreflang set
+- [ ] Schema.org `description` in correct language
+- [ ] OG tags in correct language (`og:locale`)
+- [ ] Sitemap includes hreflang alternates per URL
+- [ ] Language preference persisted (localStorage/cookie)
+- [ ] Auto-detection of browser language (`navigator.language`)
+- [ ] Legal pages (Privacy, Terms) translated
+
+## 9. Content & Keywords
+- [ ] Primary keyword identified per page
+- [ ] Long-tail keyword variants in content
+- [ ] Location-based keywords (city, region, country)
+- [ ] Service-specific keywords
+- [ ] Competitor keyword gap analysis
+- [ ] Content matches search intent (informational, transactional, navigational)
+
+## 10. PageSpeed 100% — Performance Perfection Loop
+> Reference: See `pagespeed-playbook.md` for complete technique catalog with code examples.
+
+### Performance (Impact-Ordered)
+- [ ] Self-hosted fonts (woff2) — no Google CDN
+- [ ] Font preload with `fetchpriority="high"` for critical weight
+- [ ] `font-display: swap` on all `@font-face` rules
+- [ ] ALL CSS inlined in production HTML (zero render-blocking)
+- [ ] `.htaccess` cache headers: 1yr for static assets, 1hr for HTML
+- [ ] Gzip/Brotli compression enabled (mod_deflate)
+- [ ] ALL `<img>` tags have explicit `width` and `height` attributes
+- [ ] Below-fold images have `loading="lazy"`
+- [ ] LCP image has `fetchpriority="high"`
+- [ ] Third-party scripts use `async defer`
+- [ ] CLS = 0 (no layout shifts during load)
+
+### Accessibility (WCAG AA)
+- [ ] ALL text/background combos ≥ 4.5:1 contrast ratio
+- [ ] White text on orange backgrounds replaced with dark text (#1a0800)
+- [ ] Dim/muted text on dark backgrounds brightened to ≥ #a0b0b8
+- [ ] Badge text with transparency backgrounds ≥ #d4dde3
+- [ ] Checked: CTA buttons, active nav states, badges, footer, form labels, tags
+
+### Best Practices
+- [ ] No console errors from own code
+- [ ] Third-party console errors documented as known limitations
+- [ ] All external links have `rel="noopener noreferrer"`
+- [ ] All resources loaded over HTTPS
+
+### Anti-Patterns (NEVER DO)
+- [ ] ❌ Never use `media="print" onload` for CSS (causes CLS 0.936)
+- [ ] ❌ Never load fonts from external CDN without local fallback
+- [ ] ❌ Never leave `<img>` tags without width/height dimensions
+- [ ] ❌ Never fix contrast issues one at a time (batch ALL at once)
+

package/src/bmad-plus/agents/pack-seo/pagespeed-playbook.md

@@ -0,0 +1,320 @@
+# 🎯 PageSpeed Perfection Playbook — Battle-Tested Guide
+
+> **Version 1.0.0** — Based on 6+ real-world iterations achieving 99-100% on oveanet.ch, montpellier.ai, and oveanet.fr
+> By Laurent ROCHETTA × AI
+
+---
+
+## 📐 Architecture: The 4-Phase Protocol
+
+```
+Phase 1: DIAGNOSTIC → Extract scores, identify all failing audits
+Phase 2: PERFORMANCE → Self-host fonts → Inline CSS → Cache → CLS
+Phase 3: ACCESSIBILITY → WCAG AA contrast fixes (systematic)
+Phase 4: BEST PRACTICES & SEO → Console errors, security, meta tags
+```
+
+Each phase runs sequentially. **Backup before each phase.** Re-test after each phase.
+
+---
+
+## ⚠️ Anti-Patterns — Things That BREAK Scores
+
+> [!CAUTION]
+> These are real mistakes made during optimization that caused score REGRESSIONS.
+
+### 🔴 NEVER: Async CSS Loading
+```html
+<!-- ❌ DISASTER — causes CLS 0.936 on mobile -->
+<link rel="stylesheet" href="styles.css" media="print" onload="this.media='all'"/>
+<noscript><link rel="stylesheet" href="styles.css"/></noscript>
+```
+**What happens:** The page renders with no styles, then FLASHES when CSS loads. PageSpeed measures this as a massive Cumulative Layout Shift (0.936 — nearly maximum). Performance dropped from 86 to 75.
+
+**Fix:** Either load CSS synchronously or inline it entirely.
+
+### 🔴 NEVER: External Font CDN Without Fallback
+```html
+<!-- ❌ Adds 300-800ms to LCP on mobile 4G -->
+<link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;600;700" rel="stylesheet"/>
+```
+**What happens:** DNS lookup + TLS handshake to `fonts.googleapis.com`, then another to `fonts.gstatic.com`. On 4G simulation, this adds 500ms+ to LCP.
+
+### 🔴 NEVER: Images Without Dimensions
+```html
+<!-- ❌ Causes CLS because browser doesn't know the space to reserve -->
+<img src="logo.svg" alt="Logo"/>
+```
+**Fix:** Always add `width` and `height`:
+```html
+<img src="logo.svg" alt="Logo" width="100" height="20"/>
+```
+
+---
+
+## 🏆 Technique Catalog — Ordered by Impact
+
+### [P1] Self-Host Fonts (Biggest LCP Win)
+
+**Impact:** LCP -30-50% on mobile, eliminates 2 external requests
+
+**Step 1:** Download fonts from Google Fonts API or copy from existing projects:
+```
+fonts/
+├── space-grotesk-400-latin.woff2
+├── space-grotesk-600-latin.woff2
+└── space-grotesk-700-latin.woff2
+```
+
+**Step 2:** Update CSS `@font-face` declarations:
+```css
+/* ✅ Self-hosted — zero external requests */
+@font-face {
+  font-family: 'Space Grotesk';
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url('fonts/space-grotesk-400-latin.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Space Grotesk';
+  font-style: normal;
+  font-weight: 600;
+  font-display: swap;
+  src: url('fonts/space-grotesk-600-latin.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Space Grotesk';
+  font-style: normal;
+  font-weight: 700;
+  font-display: swap;
+  src: url('fonts/space-grotesk-700-latin.woff2') format('woff2');
+}
+```
+
+**Step 3:** Preload critical fonts in HTML `<head>`:
+```html
+<link rel="preload" href="fonts/space-grotesk-400-latin.woff2"
+      as="font" type="font/woff2" crossorigin fetchpriority="high"/>
+<link rel="preload" href="fonts/space-grotesk-600-latin.woff2"
+      as="font" type="font/woff2" crossorigin/>
+```
+
+**Step 4:** Remove ALL Google Fonts CDN references:
+```diff
+-<link rel="preconnect" href="https://fonts.googleapis.com"/>
+-<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin/>
+-<link href="https://fonts.googleapis.com/css2?..." rel="stylesheet"/>
++<!-- Fonts are self-hosted, no external CDN needed -->
+```
+
+### How to get woff2 files from Google Fonts:
+```bash
+# Method 1: Use google-webfonts-helper
+# https://gwfh.mranftl.com/fonts
+
+# Method 2: Direct download with curl (set woff2 user-agent)
+curl -H "User-Agent: Mozilla/5.0" \
+  "https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;600;700&display=swap" \
+  | grep -oP 'url\(\K[^)]+' | while read url; do
+    wget "$url" -P fonts/
+  done
+```
+
+---
+
+### [P2] Inline ALL CSS (Zero Render-Blocking)
+
+**Impact:** Eliminates render-blocking CSS request, reduces FCP by 100-300ms
+
+**For PHP sites** (like montpellier.ai):
+```php
+<!-- ✅ CSS inlined at build time — zero render-blocking -->
+<style><?php echo file_get_contents(__DIR__ . '/styles.css'); ?></style>
+```
+
+**For static HTML sites** (build script):
+
+PowerShell build script:
+```powershell
+# build-dist.ps1 — Inline CSS into HTML for production
+$css = Get-Content "styles.css" -Raw
+$html = Get-Content "index.html" -Raw
+
+$cssInline = "  <style>`n$css`n  </style>"
+
+# Replace the critical CSS + external link with full inline
+$pattern = '  <!-- Critical CSS.*?</style>\s*\r?\n.*?<link rel="stylesheet" href="styles.css"/>'
+$html = $html -replace $pattern, $cssInline
+
+$html | Set-Content "dist/index.html" -Encoding UTF8
+```
+
+Bash build script:
+```bash
+#!/bin/bash
+# build-dist.sh — Inline CSS into HTML for production
+CSS=$(cat styles.css)
+sed -e '/<!-- Critical CSS/,/<link rel="stylesheet"/c\  <style>'"$CSS"'</style>' \
+    index.html > dist/index.html
+```
+
+> [!IMPORTANT]
+> Keep source files separate (index.html + styles.css) for development.
+> Only the dist/ version gets the inlined CSS for production.
+
+---
+
+### [P3] Cache Headers (.htaccess Template)
+
+**Impact:** Fixes "Use efficient cache policy" audit
+
+```apache
+# === PageSpeed Cache & Compression — Ready to Deploy ===
+
+<IfModule mod_expires.c>
+  ExpiresActive On
+  ExpiresDefault "access plus 1 month"
+  ExpiresByType text/html "access plus 1 hour"
+  ExpiresByType text/css "access plus 1 year"
+  ExpiresByType application/javascript "access plus 1 year"
+  ExpiresByType image/svg+xml "access plus 1 year"
+  ExpiresByType image/png "access plus 1 year"
+  ExpiresByType image/webp "access plus 1 year"
+  ExpiresByType font/woff2 "access plus 1 year"
+  ExpiresByType application/font-woff2 "access plus 1 year"
+</IfModule>
+
+<IfModule mod_headers.c>
+  <FilesMatch "\.(css|js|svg|png|webp|woff2|ico)$">
+    Header set Cache-Control "public, max-age=31536000, immutable"
+  </FilesMatch>
+  <FilesMatch "\.(html|php)$">
+    Header set Cache-Control "public, max-age=3600, must-revalidate"
+  </FilesMatch>
+  <FilesMatch "\.(txt|xml)$">
+    Header set Cache-Control "public, max-age=86400"
+  </FilesMatch>
+</IfModule>
+
+# Gzip Compression
+<IfModule mod_deflate.c>
+  AddOutputFilterByType DEFLATE text/html text/css application/javascript
+  AddOutputFilterByType DEFLATE text/javascript application/json text/xml
+  AddOutputFilterByType DEFLATE image/svg+xml text/plain
+</IfModule>
+```
+
+---
+
+### [P4] CLS Prevention Checklist
+
+| Element | Required Fix |
+|---------|-------------|
+| `<img>` tags | Add `width` and `height` attributes |
+| CSS-loaded fonts | Use `font-display: swap` |
+| CSS loading | NEVER use `media="print" onload` trick |
+| Dynamic content | Reserve space with min-height |
+| Embeds/iframes | Set explicit dimensions |
+
+---
+
+## 🎨 Accessibility — Contrast Ratio Reference
+
+### The Rule
+WCAG AA requires **4.5:1** contrast ratio for normal text, **3:1** for large text (18px+ or 14px+ bold).
+
+### Common Color Combos on Dark Backgrounds (#0B0C15)
+
+| Text Color | Hex | Ratio vs #0B0C15 | Pass? |
+|-----------|-----|:-----------------:|:-----:|
+| Pure white | `#ffffff` | 19.2:1 | ✅ |
+| Light gray | `#d4dde3` | 12.5:1 | ✅ |
+| Medium gray | `#a0b0b8` | 6.5:1 | ✅ |
+| Muted gray | `#b0bec5` | 8.0:1 | ✅ |
+| Dim gray | `#6b7b8a` | 3.7:1 | ❌ |
+| Very dim | `#4a5568` | 2.3:1 | ❌ |
+
+### Common Color Combos on Orange (#E8632B)
+
+| Text Color | Hex | Ratio vs #E8632B | Pass? |
+|-----------|-----|:-----------------:|:-----:|
+| White | `#ffffff` | 3.3:1 | ❌ FAIL |
+| Light cream | `#fff5e6` | 3.1:1 | ❌ FAIL |
+| Dark brown | `#1a0800` | 8.5:1 | ✅ |
+| Black | `#000000` | 4.0:1 | ✅ (large) |
+
+> [!WARNING]
+> **White text on orange buttons is a classic fail.** Ratio is only 3.3:1.
+> Use dark text (`#1a0800`) instead for buttons, badges, and active states with orange backgrounds.
+
+### Elements Commonly Flagged by PageSpeed
+1. **CTA buttons** (`.btn-primary`) — white on primary color
+2. **Active language buttons** (`.lang-btn.active`) — white on primary
+3. **Pricing badges** ("Most Popular") — white on primary
+4. **Footer text** — dim on very dark background
+5. **Form labels** — muted on dark
+6. **Badge text** (partner badges, sponsor badges) — muted on dark with transparency
+
+---
+
+## 📊 Score Tracking Template
+
+```markdown
+| Iteration | Perf (M) | A11y (M) | Perf (D) | A11y (D) | BP  | SEO | Changes |
+|:---------:|:--------:|:--------:|:--------:|:--------:|:---:|:---:|---------|
+| Baseline  | ?        | ?        | ?        | ?        | ?   | ?   | Initial |
+| #1        |          |          |          |          |     |     |         |
+| #2        |          |          |          |          |     |     |         |
+```
+
+---
+
+## 🔧 PageSpeed JavaScript Extraction Snippets
+
+Use these in the browser to extract structured data from PageSpeed results:
+
+### Extract All Scores
+```javascript
+JSON.stringify({
+  gauges: Array.from(document.querySelectorAll('.lh-gauge__percentage'))
+    .map(g => g.textContent.trim()),
+  labels: Array.from(document.querySelectorAll('.lh-gauge__label'))
+    .map(l => l.textContent.trim())
+});
+```
+
+### Extract Core Web Vitals
+```javascript
+JSON.stringify({
+  metrics: Array.from(document.querySelectorAll('.lh-metric'))
+    .map(m => ({
+      name: m.querySelector('.lh-metric__title')?.textContent?.trim(),
+      value: m.querySelector('.lh-metric__value')?.textContent?.trim()
+    }))
+});
+```
+
+### Extract Failing Audits
+```javascript
+JSON.stringify({
+  failed: Array.from(document.querySelectorAll('.lh-audit--fail .lh-audit__title'))
+    .map(a => a.textContent.trim().substring(0, 150)),
+  warnings: Array.from(document.querySelectorAll('.lh-audit--average .lh-audit__title'))
+    .map(a => a.textContent.trim().substring(0, 150))
+});
+```
+
+---
+
+## 🏁 Exit Conditions
+
+The PageSpeed Perfection Loop STOPS when:
+- ✅ **ALL 4 scores = 100/100** → Perfection achieved
+- ⚠️ **After 8 iterations** → Report remaining issues with root cause analysis
+- 🟡 **Only server-side issues remain** (TTFB, CDN, HTTP/2) → Report as "requires server-side changes"
+- 🟡 **Only third-party script issues remain** (Cloudflare Turnstile, analytics) → Report as "not fixable client-side"
+
+---
+
+*Built with ❤️ in Montpellier, France — by Laurent ROCHETTA × AI*