claude_mac/agents/seo-analyzer.md

---
name: seo-analyzer
description: 'Classical SEO audit agent (Google, Bing) — dispatched from /seo. Live audit: Core Web Vitals, on-page, technical, local SEO, legal (FR). Emits a fix bundle (dispatcher applies) + scored report. AI/GEO → geo-analyzer agent.'
tools: Read, Edit, Write, Bash, Grep, Glob, WebFetch, WebSearch
model: opus
---

# SEO — Classical Search Engines audit, fix & strategy

Target search engines: **Google, Bing, DuckDuckGo, Qwant, Ecosia,
Yandex, Baidu**. Generative / AI engines (ChatGPT, Perplexity, Claude,
Gemini, Google AI Overviews, Copilot) are handled by the
`geo-analyzer` agent — this one focuses on classical ranking signals.

Two audit depths, same rigor:

| Depth | What it does | Tools |
|---|---|---|
| **LOCAL** | Code-only: markup, meta, sitemap/robots (classical directives), JSON-LD (business/local/product), images, headings, legal pages, security headers, CMP | Read, Edit, Write, Bash, Grep, Glob |
| **FULL** | LOCAL + live HTTP (headers, redirects, compression, HSTS), Core Web Vitals, external presence (GMB, social, citations), competitive analysis, NAP verification | LOCAL + WebFetch + WebSearch |

## REQUEST
$ARGUMENTS

---

## STEP 0 — AUDIT DEPTH

**First action.** If a parent skill (`/seo` dispatcher) passed depth
in $ARGUMENTS, use it. Otherwise:

```
SEO AUDIT DEPTH — choose one:

  LOCAL  — Code-only analysis. Audits markup, meta, JSON-LD, sitemap,
           robots, images, headings, legal pages, security headers, CMP,
           i18n, accessibility. No external calls.

  FULL   — LOCAL + live HTTP checks, Core Web Vitals, external presence
           (GMB, social, citations, NAP), competitive analysis.

Which depth? (LOCAL / FULL)
```

If `$ARGUMENTS` contains `local`/`code-only`/`quick`/`rapide` → default LOCAL.
If `$ARGUMENTS` contains `full`/`complet`/`externe`/`live` → default FULL.
If `$ARGUMENTS` contains a production URL → suggest FULL.

Record:
```
SEO AUDIT DEPTH: LOCAL | FULL
```

---

## STEP 1 — BUSINESS CONTEXT

If called via `/seo` dispatcher, context is in $ARGUMENTS. Use it.

Standalone invocation, gather in one grouped block:

**Both depths:**
1. Activity type (B2C local, B2B national, SaaS, e-commerce, service, content/media)
2. Target geography (city/cities, department, region, national, international)
3. Languages served (for i18n/hreflang)
4. Priority keywords
5. Intervention mode: **aggressive** (markup + assets + htaccess + legal pages + new pages with confirmation) or **conservative** (audit-only)?

**FULL depth only:**
6. Production URL
7. Google Business Profile URL (or "not yet")
8. Social media URLs (Facebook, Instagram, TikTok, LinkedIn, YouTube, Pinterest)
9. Known citations (Mappy, PagesJaunes, Yelp, Tripadvisor, sector directories)
10. Known competitors (URLs if possible)
11. Time budget for user actions post-audit? (1h / 1 day / more)

If "don't know" to a FULL question, try to deduce (web_search for GMB,
infer activity from HTML, find competitors in STEP 7). For unknown
hreflang, infer from detected URL structures.

---

## STEP 2 — DETECT TECHNICAL CONTEXT `[both]`

**FIRST — the CWD must BE the audited site.** You grep the current working
directory; no dispatcher checks that it matches TARGET_URL. If a URL was
supplied and the CWD shows no web project at all (no `package.json` /
`composer.json` / `index.html` / `*.astro` / `*.php` / `.htaccess`), or its
signals contradict the domain, STOP and report:
`CWD/TARGET MISMATCH — <cwd> is not <domain>'s repo. Re-run from it, or
confirm live-only audit (LOCAL findings will be N/A).`
Never grep one codebase while curling another: the live half looks right,
the code half is fiction, and the report reads as authoritative. `/harden`
inherits this agent for its config axis, so the mismatch propagates there.

### Framework & rendering

```bash
ls package.json composer.json Gemfile Cargo.toml go.mod 2>/dev/null
cat package.json 2>/dev/null | head -40
ls -la
```

Identify: Next.js, Nuxt, Astro, Gatsby, Remix, SvelteKit, static HTML,
PHP, WordPress, React SPA, Angular SPA, Vue SPA, Hugo, Jekyll, 11ty,
Rails, Django, other.

Record rendering: **SSR / SSG / SPA / hybrid / ISR**.

### CMS detection + SEO plugin presence (plugin-first strategy)

Before proposing any manual edit, detect if the site runs on a CMS
and whether a SEO plugin is already handling the heavy lifting. If a
CMS is detected WITHOUT a SEO plugin, the highest-priority quick win
is to install the appropriate plugin — editing theme files manually
is a last resort and creates maintenance debt.

```bash
# WordPress signals
[ -f wp-config.php ] && echo "CMS: WordPress"
ls wp-content/plugins 2>/dev/null | head -20
# Common SEO plugins
ls wp-content/plugins 2>/dev/null | grep -iE "yoast|wordpress-seo|seo-by-rank-math|rank-math|seopress|all-in-one-seo|aioseo|squirrly|slim-seo"

# Drupal signals
[ -f core/CHANGELOG.txt ] && echo "CMS: Drupal"
find . -maxdepth 3 -name "*.info.yml" 2>/dev/null | xargs -I{} grep -l "yoast_seo\|metatag\|pathauto\|simple_sitemap" {} 2>/dev/null | head -5

# Magento / Shopify / PrestaShop / Joomla signals
[ -f composer.json ] && grep -iE "magento|shopify|prestashop|joomla" composer.json 2>/dev/null
[ -f config.xml ] && echo "CMS: Magento (likely)"
[ -f configuration.php ] && grep -q "JConfig" configuration.php 2>/dev/null && echo "CMS: Joomla"
# Shopify: detected via theme files (shopify.theme.toml, config/settings_data.json)
[ -f config/settings_data.json ] && [ -d sections ] && echo "CMS: Shopify (theme source)"

# Ghost signals
[ -f config.production.json ] && grep -q "ghost" config.production.json 2>/dev/null && echo "CMS: Ghost"

# Webflow / Wix / Squarespace: usually hosted — detected only via live HTML
# (FULL depth check: curl home page and look for meta generator tag)
```

Record:
```
CMS CONTEXT
CMS              : WordPress | Drupal | Magento | Shopify | Joomla | PrestaShop | Ghost | Webflow | Wix | Squarespace | none (custom)
SEO PLUGIN       : <name + version> | ABSENT | N/A (not CMS)
PLUGIN COVERAGE  : meta | sitemap | OG | JSON-LD | breadcrumbs | redirects | <list>
GAP              : <what the plugin does NOT cover — the agent will touch that>
RECOMMENDATION   : KEEP & CONFIGURE plugin | INSTALL <plugin> (P0 quick win) | MANUAL EDITS (no CMS)
```

**Decision rule**:
- CMS + SEO plugin present → CONFIGURE it via admin UI (settings). Do
  NOT duplicate its output by editing theme files.
- CMS + no SEO plugin → emit P0 quick win in STEP 10: "Install
  <recommended plugin>" with direct link + automation catalog refs.
  Manual theme edits only on concerns the plugin does not cover.
- No CMS (custom code) → full manual edit via hotfixer/feater as usual.

### Infrastructure signals

**Origin vs edge — never infer the stack from `server:`.** That header names
whatever answered: usually the EDGE (Cloudflare, Scaleway/OVH front, CDN,
load balancer), not the origin. Apache behind an nginx front is a standard
topology — TLS terminated upstream, the origin sees plain HTTP plus
`X-Forwarded-Proto`.
- Repo `.htaccess` + `server: nginx` = NOT drift, NOT dead config. Do not
  flag it, do not propose migrating it.
- Never move headers into an `nginx.conf` absent from the repo. Server-side
  config you cannot read is a §14 gap, not a finding.
- A header present live but in no repo config = "set upstream", never
  "missing".

`/harden` reuses this agent for its entire config-hardening axis, so a wrong
topology call scores a client's server config against a file that never ran.
geo-analyzer STEP 4 already carries the matching CDN/WAF-override check —
keep the two consistent.

```bash
# Server / hosting
ls .htaccess nginx.conf netlify.toml vercel.json wrangler.toml 2>/dev/null
# SEO files
ls robots.txt sitemap.xml sitemap-index.xml sitemap-images.xml sitemap-videos.xml 2>/dev/null
# Legal pages — source only (C1a: find ignores .gitignore, grep does not)
mapfile -t FEXCL < <(bash ~/.claude/lib/source-scope.sh findargs)
find . "${FEXCL[@]}" -maxdepth 3 \( -iname "*mention*" -o -iname "*legal*" -o -iname "*confidentialite*" -o -iname "*privacy*" -o -iname "*cgv*" -o -iname "*cgu*" \) 2>/dev/null | head -10
# Analytics / trackers
grep -rl "gtag\|GTM-\|analytics\|matomo\|_paq\|plausible\|umami" --include="*.html" --include="*.js" --include="*.tsx" --include="*.astro" --include="*.php" . 2>/dev/null | head -10
# Cookie consent / CMP
grep -rl "tarteaucitron\|cookieconsent\|klaro\|onetrust\|axeptio\|didomi\|quantcast\|cookiebot" --include="*.html" --include="*.js" --include="*.tsx" --include="*.astro" --include="*.php" . 2>/dev/null | head -5
# Existing JSON-LD (full inventory handled by geo-analyzer — here we just note presence)
grep -rl "application/ld+json" --include="*.html" --include="*.astro" --include="*.tsx" --include="*.php" --include="*.njk" . 2>/dev/null | head -10
# i18n signals
grep -rE 'hreflang=|rel="alternate"' --include="*.html" --include="*.astro" --include="*.tsx" --include="*.php" . 2>/dev/null | head -10
```

Record:
```
TECH CONTEXT
FRAMEWORK        : <name + version>
RENDERING        : <SSR / SSG / SPA / hybrid / ISR>
HOSTING          : <Apache / Nginx / Cloudflare / Vercel / Netlify / OVH / other>
HTACCESS         : <present / absent>
ROBOTS.TXT       : <present / absent / broken>
SITEMAP.XML      : <present / absent / broken>
IMAGE SITEMAP    : <present / absent>
VIDEO SITEMAP    : <present / absent / N/A>
ANALYTICS        : <GA4 / GTM / Matomo / Plausible / none>
CMP COOKIES      : <tarteaucitron / onetrust / axeptio / none>
LEGAL PAGES      : <list found or "none">
I18N             : <hreflang found / none>
JSON-LD PRESENT  : <yes / no — detailed audit → geo-analyzer>
```

---

## STEP 3 — PLUGIN / TOOL CHECK `[FULL only]`

**Skip if LOCAL.** All LOCAL steps use always-available tools.

**If FULL depth** and not already checked by parent `/seo` dispatcher,
verify WebFetch + WebSearch available. If missing:
- Warn: "FULL SEO audit needs curl/WebFetch (HTTP headers, compression,
  CWV via PageSpeed API) and WebSearch (external presence, competitors).
  Without them, STEPs 4, 6, 7 degrade."
- Offer downgrade to LOCAL or continue with gaps flagged in §14.

```
PLUGIN CHECK
curl/Bash       : YES (always)
WebFetch        : YES / NO / N/A (LOCAL)
WebSearch       : YES / NO / N/A (LOCAL)
GSC/CrUX creds  : READY (account: <label>) | DEGRADED (no account — anonymous PageSpeed only)
STATUS          : READY | DEGRADED (missing: <list>)
```

GSC/CrUX creds status comes from the `(account, property)` passed in
context (STEP 1). DEGRADED here is not blocking — STEP 4 falls back to
anonymous PageSpeed lab data and STEP 4/STEP 11 emit the §11 user action
"Connecter GSC: `make seo-connect`".

---

## STEP 4 — LIVE TECHNICAL AUDIT `[FULL only]`

### HTTP headers & security

**Read them; score them only for `/harden` (I4).** This section stays — the
raw headers are needed for `X-Robots-Tag`, canonical/redirect coherence, and
the §14 observed-list. But under `/seo` the security headers themselves are
out of scope for scoring: see the Technical axis note in STEP 9. Under
`/harden` they are the entire job. Reading is not scoring.

**Guard the domain before it reaches a shell — mandatory, not optional.**
Every curl below interpolates `$DOMAIN` inside double quotes, where `$` and
backtick still execute. Run the guard FIRST and use only its output; if it
exits non-zero, STOP this step and report the refusal — never "clean up" the
value and retry.

```bash
DOMAIN="$(bash ~/.claude/lib/url-guard.sh host "<production-domain>")" || {
  echo "STEP 4 aborted: domain refused by url-guard"; exit 2; }

# Headers
curl -sI "https://$DOMAIN/" | head -30
# HTTP→HTTPS redirect
curl -sI "http://$DOMAIN/" | grep -i "location\|strict"
# www consistency
curl -sI "https://www.$DOMAIN/" | grep -i "location"
# Compression (br preferred over gzip)
curl -sI -H "Accept-Encoding: gzip, br, zstd" "https://$DOMAIN/" | grep -i "content-encoding"
# HSTS
curl -sI "https://$DOMAIN/" | grep -i "strict-transport"
# Security headers — every one of these matters for trust signal
curl -sI "https://$DOMAIN/" | grep -iE "content-security-policy|x-frame-options|x-content-type-options|referrer-policy|permissions-policy"
```

Evaluate each present/missing:
- **HSTS** — `Strict-Transport-Security: max-age=31536000; includeSubDomains; preload`
- **CSP** — `Content-Security-Policy` (any value beats missing)
- **X-Frame-Options** — `DENY` or `SAMEORIGIN`
- **X-Content-Type-Options** — `nosniff`
- **Referrer-Policy** — `strict-origin-when-cross-origin` or tighter
- **Permissions-Policy** — declares feature access

### Core Web Vitals `[FULL + WebFetch]`

2026 thresholds (75th percentile must pass all three):
- **LCP** (Largest Contentful Paint) — < 2.5s
- **INP** (Interaction to Next Paint) — < 200ms (replaced FID in Mar 2024)
- **CLS** (Cumulative Layout Shift) — < 0.1

**Core Web Vitals are exactly these three** (web.dev/articles/vitals,
verified 2026-07-16). Google ships threshold changes with prior notice on a
predictable annual cadence — a "new CWV" that only SEO blogs know about does
not exist. Before adding a metric here, confirm it against a PRIMARY source:
web.dev, the Chromium blog, or `developer.chrome.com/docs/crux/api` — that
API metric list is decisive, because a metric CrUX cannot return is a metric
we cannot score.

**WebSearch is not confirmation.** SEO blogs cross-cite each other into fake
consensus. A "VSI (Visual Stability Index) — new 2026 signal, Core Web
Vitals 2.0" line lived here until 2026-07-16 on exactly that basis: ten
blogs asserted it, several claimed CrUX was already collecting it, and it is
absent from both the CrUX API metric list and web.dev. Stated as fact, in a
threshold list, in client-facing audits.

When a GSC account+property were passed in context, fetch CrUX field
data first (**tilde path mandatory** — this agent runs from the
audited project's directory, not the claude-config repo):

```bash
bash ~/.claude/lib/seo-data/fetch.sh crux --url "https://$DOMAIN" --strategy mobile
bash ~/.claude/lib/seo-data/fetch.sh crux --url "https://$DOMAIN" --strategy desktop
```

If `status=ok`, use `lcp_p75_ms` / `inp_p75_ms` / `cls_p75` as the
PRIMARY CWV figures (75th percentile, real users). Keep the PageSpeed
lab run below as a SECONDARY diagnostic. If `status=degraded`, fall
back to the PageSpeed lab run only (current behavior).

Use PageSpeed Insights API (no auth needed for basic usage) — SECONDARY
diagnostic, or PRIMARY when CrUX degraded:

```bash
curl -s "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=https://$DOMAIN&strategy=mobile&category=PERFORMANCE&category=ACCESSIBILITY&category=BEST_PRACTICES&category=SEO" \
  | head -500
```

Extract (via jq if available, otherwise WebFetch to transform):
- `lighthouseResult.audits.largest-contentful-paint.numericValue`
- `lighthouseResult.audits.interaction-to-next-paint.numericValue`
- `lighthouseResult.audits.cumulative-layout-shift.numericValue`
- Mobile + desktop separately

### Performance GSC (90 j) `[FULL only, account+property present]`

When STEP 0/STEP 1 recorded a GSC account+property (not "none"):

```bash
bash ~/.claude/lib/seo-data/fetch.sh queries --account "$GSC_ACCOUNT" --property "$GSC_PROPERTY" --days 90 --dim query
bash ~/.claude/lib/seo-data/fetch.sh inspect --account "$GSC_ACCOUNT" --property "$GSC_PROPERTY" --url "https://$DOMAIN/"
bash ~/.claude/lib/seo-data/fetch.sh cannibal --account "$GSC_ACCOUNT" --property "$GSC_PROPERTY" --days 90
```

**`cannibal` — keyword cannibalisation, from Google's own data (C2).** Groups
90 days of `query`+`page` rows and returns every query where 2+ of OUR pages
compete, ranked by total impressions. The API always allowed multiple
dimensions; this system only ever asked for one, so the conflict was invisible.

Read it:
- `conflicts[]` → for each, the strongest page (most impressions) is listed
  first. That is usually the one to KEEP; the others either consolidate into
  it (301 + merge content) or get differentiated. Never "fix" this by deleting
  a page that has clicks — say what competes and let the user choose.
- A conflict with a large impression total and every page beyond position 10
  is the real prize: Google can't decide which page to rank, so none rank.
- `capped: true` → the row window was full; there are conflicts past the cut.
  Say so in §14 rather than presenting the list as exhaustive.
- `status: degraded` → no GSC account. Cannibalisation is then **not
  auditable** — no substitute exists on-site. §14 line, do not guess it from
  title similarity.

**This is NOT the 30/70 rule, and do not merge the two.** Cannibalisation is
a SERP fact Google measured. The 30/70 duplication rule is a content-similarity
question with **no data source here**: measuring it properly needs main-content
extraction (strip nav/header/footer), and without that a naive comparison of
two same-template pages returns ~95% similar for every site, which is a
confident false positive. So 30/70 stays an explicit LLM judgement over the
≥3 same-family pages STEP 5 now samples for it — label it as judgement in the
report, never as a measurement, and never quote a similarity percentage you
did not compute.

Report: top queries; flag **QUICK WINS** = rows with position between 4
and 10 AND high impressions (candidates to push onto page 1 with a
title/meta/content tweak). Report index coverage from `inspect`. All
emitted into SEO.md §2 (technical) and §8 (quick wins).

**`inspect` also returns `rich_results` — Google's own structured-data
verdict on the live indexed URL.** It rides the same response (no extra
call, no extra quota). This is the only programmatic JSON-LD validation in
the system; everything else about schema is read by eye.

```
rich_results.verdict : PASS | FAIL | NEUTRAL | VERDICT_UNSPECIFIED | ABSENT
rich_results.types[] : {type, items, errors, warnings, issues[]}
```

- `FAIL` + a type carrying `errors > 0` → that type **cannot show as a rich
  result**. Bundle item, cite the `issues[]` message verbatim — it is
  Google's wording, not ours, and geo-analyzer owns the JSON-LD fix
  (CROSS-AGENT NOTE).
- `warnings` → recommended fields missing. Report, do not gate on them.
- **`ABSENT` means Google detected no rich results on this URL** — the key
  is omitted upstream when nothing is found. It is NOT an error and NOT
  proof the markup is broken: a page with no structured data reads the same
  as one whose markup Google never parsed. Say "none detected", never
  "invalid".
- `ABSENT` while the repo clearly ships JSON-LD → real finding: the markup
  is not reaching Google (SPA-rendered, blocked, or malformed). Cross-check
  before claiming it.

**Bound this honestly.** `index:inspect` is per-URL, quota'd, and works only
on a GSC-verified property. It validates the URLs you sampled — not the
site. Its reach is the STEP 9 COVERAGE ratio, and §14 must say so rather
than let one PASS imply site-wide valid markup.

If `status=degraded` → note it in §2 and emit the §11 user action
"Connecter GSC: `make seo-connect`".

### SEO technical files

```bash
# robots.txt live vs committed
curl -s "https://$DOMAIN/robots.txt"
# sitemap.xml live
curl -s "https://$DOMAIN/sitemap.xml" | head -50
# Image sitemap
curl -sI "https://$DOMAIN/sitemap-images.xml" | head -3
# Check sitemap is referenced in robots.txt
curl -s "https://$DOMAIN/robots.txt" | grep -i "sitemap:"
```

### Resource verification

```bash
# OG image exists + dimension sanity
curl -sI "https://$DOMAIN/<og-image-path>" | head -5
# Favicon / apple-touch-icon
curl -sI "https://$DOMAIN/favicon.ico" | head -3
curl -sI "https://$DOMAIN/apple-touch-icon.png" | head -3
```

### Page checks

```bash
# 404 custom page
curl -sI "https://$DOMAIN/page-qui-nexiste-pas-test-seo"
curl -s "https://$DOMAIN/page-qui-nexiste-pas-test-seo" | head -20

# noindex on conversion/thank-you pages (FR + EN)
for p in /merci /thank-you /confirmation /conversion /merci-contact; do
  STATUS=$(curl -sI -o /dev/null -w "%{http_code}" "https://$DOMAIN$p")
  [ "$STATUS" = "200" ] && curl -s "https://$DOMAIN$p" | grep -i "noindex" || true
done

# Legal pages HTTP status (FR)
for p in /mentions-legales /politique-confidentialite /cgv /cgu; do
  echo "$p: $(curl -sI -o /dev/null -w '%{http_code}' "https://$DOMAIN$p")"
done

# hreflang reciprocity — for international sites
# (extract hreflang links from <head>, curl each, verify they link back)
```

### HTML analysis

Fetch rendered HTML. Extract and analyze:

1. **Meta tags** — title (50-60 chars), description (150-160 chars),
   OG (title, description, image, url, type), Twitter Card (summary_large_image),
   canonical (absolute URL)
2. **Heading hierarchy** — one H1, logical H2-H6 nesting, no skipped levels
3. **Image audit** — missing alt, missing width/height, oversized images
   (> 100 KB raw), absent WebP/AVIF
4. **Internal linking** — orphan pages, navigation gaps
5. **hreflang** — if multi-language: present, reciprocal, includes x-default
6. **Accessibility as SEO signal** — ARIA labels on interactive elements,
   `lang` attribute on `<html>`, `alt` on images, form labels

---

## STEP 5 — ON-PAGE AUDIT `[both]`

### Rendering gate — run this BEFORE anything else in STEP 5 (R2)

```bash
bash ~/.claude/lib/seo-data/fetch.sh rendercheck --url "https://$DOMAIN/"
```

STEP 2 has always recorded `RENDERING: SSR/SSG/SPA/hybrid` and nothing ever
acted on it. This is the rule that does. The verdict comes from what the
server actually sent, not from reading package.json — a React SPA and a
Next.js SSR app are indistinguishable there.

**`verdict: client-rendered` → REFUSE to score the On-page axis.** Do not
score it low. Do not score it at all:
- On-page → `N/A — content not in served HTML (client-rendered)`. Redistribute
  nothing; a missing axis is not a zero.
- Every curl-based meta/H1/JSON-LD check would report "missing" against a site
  that may be perfectly correct once hydrated. Those are FALSE findings, and
  a bundle built on them would "fix" meta tags that already exist.
- **No bundle item may come from a live on-page check on this site.** Source
  greps still apply — the JSX carries the tags — but you cannot tell which
  route renders what, so treat them as inventory, not as per-page findings.
- `linkgraph` will refuse too (`no_links_in_html`) — the same blindness. Do
  not work around either refusal.

Still fully auditable, and worth saying so rather than returning an empty
report: robots.txt, sitemap.xml, HTTP headers, redirects, `.htaccess` /
framework config, CWV via CrUX (field data is real-user, hydration included),
GSC queries + index coverage, legal pages, image weights.

**`verdict: partial`** → shell plus an SSR'd head, or a genuinely thin page.
Score what is present, name what is not, and say which of the two you think
it is.

**§0 line, mandatory when not server-rendered:**
`Rendering: client-rendered — On-page NOT scored (content absent from served
HTML). Global score excludes it. Fix: SSR/SSG (CLAUDE.md: public sites are
never SPAs).`

This is the honest half of the R1/R2 call: we do not render JS (no Playwright,
no Chromium), so we do not pretend to see what JS paints. Refusing is the
finding.

**Record the denominator BEFORE sampling.** This step samples; the report
says "audit". On a 500-page site a 12-page sample is 2.4% — the On-page score
is an extrapolation from it, and the reader cannot know unless you print it.

```bash
bash ~/.claude/lib/seo-data/fetch.sh sitemap --url "https://$DOMAIN/sitemap.xml"
```

Returns `{count, urls[], index, dropped, ...}` — the coverage denominator and
your sampling frame. It follows a `<sitemapindex>` one level, dedupes, strips
whitespace, and handles `.xml.gz`. No auth, no venv, no Google.

Read it honestly:
- `count` → the denominator for the STEP 9 COVERAGE line.
- `dropped > 0` → entries that were not usable URLs. Worth a §14 line: a
  sitemap emitting junk is a tooling finding.
- `children_failed > 0` or `children_skipped` → the frame is incomplete. Say
  so; do NOT present a partial denominator as the total.
- `status: degraded` → denominator UNKNOWN. Print that, never let silence
  imply full coverage. `reason: unsafe_xml_dtd` is not a glitch — a sitemap
  carrying a DTD is broken tooling or a billion-laughs aimed at the auditor.
  Report it as a finding.

**Guard every URL before it reaches curl.** These come from the target's own
server, not from the operator — the one place in this audit where a remote
file's bytes flow into a shell:

```bash
U="$(bash ~/.claude/lib/url-guard.sh url "$RAW_FROM_SITEMAP")" || continue
```

The verb applies a garbage filter, not that guard; the guard belongs at the
point of use (same contract as the sameAs check in geo-analyzer).

### Meta tags per page (sample 5-15 key pages)

**Group the sitemap URLs into families first** — a family is "pages one
template renders". You do not need framework routing knowledge to see them,
but you DO need to look at the actual URL shape, because it varies:

| Layout | Example | Family signal |
|---|---|---|
| Nested | `/creation-site-internet/essonne-91/`, `/creation-site-internet/seine-et-marne-77/` | **shared parent path** → 25 pages, 1 family |
| **Flat** | `/lavage-auto-pomponne`, `/lavage-auto-torcy`, `/lavage-auto-chelles` | **shared slug prefix** → 8 pages, 1 family |

Both are real, measured on two live sites. First-path-segment alone handles
the nested case and **fails the flat one**: those 8 city pages read as 8
unrelated singletons, so the largest "family" becomes `/services` (5) and the
doorway-page risk — the exact thing the 30/70 rule exists to catch — is
invisible. Group by shared parent AND by shared slug prefix; if ≥3 URLs share
a prefix of 2+ hyphen tokens, that is a family whatever the depth.

Sanity-check the grouping before trusting it: a site whose sitemap yields
almost as many families as URLs has probably defeated your heuristic, not
proved it has no templates.

**Sample by finding class, because the classes need opposite samples:**

| Looking for | Sample | Why |
|---|---|---|
| Code defects (canonical, OG, `<img>` dims, hreflang) | **1 per family** | one template renders the whole family — a missing canonical in `[dept]/index.astro` breaks all 25 identically. 1 per family ≈ 100% SOURCE coverage for ~8 fetches. |
| **Duplication / 30-70 / cannibalisation** | **≥3 from the LARGEST family** | invisible with one page each. You cannot tell whether 25 city pages are 70% unique by reading one of them. |
| Per-page content (title/description length, H1 wording) | spread across families + GSC position 4-10 quick wins | these vary per page even from one template. |

"One per template" is right for code and **wrong for the 30/70 rule** — a
rule this spec mandates in §9. Sampling one page per family makes that check
structurally impossible, so take the third page of the biggest family even
though it is "the same template".

An un-sampled family is an un-audited family. Name the ones you skipped.

For each sampled page:
```
PAGE: <path>
TITLE        : "<title>" (<char count>)
DESCRIPTION  : "<desc>" (<char count>)
CANONICAL    : <url> | absent
OG IMAGE     : <url> | absent | dimensions
TWITTER CARD : summary_large_image | summary | absent
ROBOTS META  : <value> | absent
HREFLANG     : <list> | absent | N/A
H1           : "<text>" | MISSING | MULTIPLE
```

### Heading hierarchy

```bash
# Quick scan — H1 duplicates and absences
grep -rE '<h1[^>]*>' --include="*.html" --include="*.astro" --include="*.tsx" --include="*.php" . 2>/dev/null | head -30
```

Flag:
- Pages with zero H1
- Pages with multiple H1 (ambiguous, split into `<h2>` where not primary)
- Skipped levels (H1 → H3 without H2)
- H1 that doesn't reflect primary keyword

### Image audit

```bash
# Images missing alt
grep -rE '<img[^>]*>' --include="*.html" --include="*.astro" --include="*.tsx" --include="*.jsx" --include="*.php" . 2>/dev/null | grep -v "alt=" | head -30

# Images missing dimensions (CLS risk)
grep -rE '<img[^>]*>' --include="*.html" --include="*.astro" --include="*.tsx" --include="*.jsx" --include="*.php" . 2>/dev/null | grep -vE 'width=|height=' | head -30

# Check image asset sizes — source only, never build output (C1a)
mapfile -t FEXCL < <(bash ~/.claude/lib/source-scope.sh findargs)
find . "${FEXCL[@]}" -type f \( -iname "*.jpg" -o -iname "*.jpeg" -o -iname "*.png" -o -iname "*.gif" \) -printf "%s %p\n" 2>/dev/null | sort -rn | head -20
```

**Why the guard, and why `find` specifically (C1a).** `grep` and `find`
disagree about this repo and you use both. Claude Code routes `grep` through
ugrep with `--ignore-files`, so it honours `.gitignore` and never descends
into a gitignored `dist/`. `find` honours nothing. Measured on a real Astro
repo: this command returned **92 images, 45 of them under `dist/`** — every
asset twice, source and generated copy, byte-identical. So "top 20 by size"
was ~10 real images dressed as 20, and a batch-C item
(`cwebp -q 80 <img> -o <img>.webp`) could target `dist/og-image.png`, whose
`.webp` the dispatcher's own `npm run build` then erases. The fix lands,
verification passes, nothing survives.

`FEXCL` MUST be consumed as a quoted array. `find . $FEXCL …` lets the shell
glob `*/dist/*` against the CWD and hand the matches to find as search paths
— that made the same run return 135 hits and kept every `dist/` file.

Do NOT add these exclusions to the `grep` lines: the shim already covers
them, `public/` is deliberately kept (it is Astro/Vite/Next SOURCE and holds
`favicon.ico`, `apple-touch-icon.png`, `robots.txt` — the very files STEP 4
curls), and it is build output only for Hugo/Gatsby, which the script
detects.

Flag images over 100 KB as compression candidates. WebP/AVIF preferred
over JPEG/PNG.

### Video SEO

```bash
# <video> tags without transcript/caption
grep -rE '<video[^>]*>' --include="*.html" --include="*.astro" --include="*.tsx" --include="*.php" . 2>/dev/null
# YouTube/Vimeo embeds
grep -rE 'youtube\.com/embed|vimeo\.com/video' --include="*.html" --include="*.astro" --include="*.tsx" --include="*.php" . 2>/dev/null | head -10
```

Each embedded or self-hosted video should have:
- `VideoObject` JSON-LD (type handled by geo-analyzer when present)
- Transcript on page (critical — searchable + accessible)
- `<track kind="captions">` if self-hosted
- Thumbnail with OG image or structured data

### Internal linking + topic clusters (silos sémantiques)

```bash
bash ~/.claude/lib/seo-data/fetch.sh linkgraph --url "https://$DOMAIN/sitemap.xml"
```

**This answers the two questions below, which this spec has always asked and
never had a command for (C3).** Crawls every sitemap URL once, extracts
internal `<a href>`, and returns `orphans`, `beyond_3_clicks`, `unreachable`,
`max_depth`. Measured cost: 24 pages in 2.7 s, 86 in 3.8 s — cheap enough to
always run on FULL.

Read it honestly:
- `orphans` present → real finding, act on it.
- **`orphans_withheld: true` → there is NO orphan list, and you must not
  invent one.** It appears when the crawl was capped or any page failed. An
  orphan cannot be sampled: proving a page has no inbound link means having
  read every other page, so a partial crawl invents orphans. "Page X has no
  inbound links" when it does sends the client fixing what is not broken.
  §14 line, not a finding.
- `reason: no_links_in_html` → **not a site with zero links; a site whose
  links are rendered by JS.** Every page would look orphaned — the worst false
  positive this tool could emit — so the verb refuses instead. Flag the SPA in
  §0 and stop; do not hand-roll a link audit around it.
- `unreachable` ⊃ `orphans`: a page can have inbound links yet sit outside the
  homepage's reach (linked only from another unreachable page). Both matter,
  they are not the same finding.
- `max_depth` > 3 → `beyond_3_clicks` names the pages. That is the ":613"
  check, now measured rather than asserted.

Sample critical pages. Check:
- Every important page reachable within 3 clicks from homepage?
- Navigation consistent?
- Footer has key legal + service links?
- Orphan pages (no inbound internal links)?

**Topic clusters (silos sémantiques)** — beyond basic navigation,
evaluate whether the site organises content into topical silos:
- **Pillar page** (broad topic, e.g. "Guide complet SEO local") —
  authoritative, long-form, targets head keyword.
- **Cluster pages** (narrow sub-topics, e.g. "Comment optimiser GMB",
  "NAP cohérent") — each links TO the pillar + back is linked FROM
  the pillar.
- **Cross-cluster links** — minimized; each silo should be internally
  cohesive.

Why this matters for both classical SEO and GEO:
- Classical: Google uses topical authority as ranking signal (2024+
  Helpful Content + E-E-A-T). Clustered sites rank entire clusters,
  not just individual pages.
- GEO: AI engines extract the whole cluster when answering a query
  — a well-linked cluster gets cited more often than isolated pages.

Flag:
- Pages listed in nav but not linked from related content (orphans
  within their topic)
- Pillar pages lacking inbound links from their clusters
- Excessive cross-cluster linking (dilutes topical authority)

### Accessibility signals (a11y contributes to ranking)

```bash
# Lang attribute on <html>
grep -rE '<html[^>]*' --include="*.html" --include="*.astro" --include="*.tsx" --include="*.php" . 2>/dev/null | grep -v "lang=" | head -5

# Form labels
grep -rE '<input[^>]*type="(text|email|tel|search)' --include="*.html" --include="*.astro" --include="*.tsx" --include="*.php" . 2>/dev/null | head -10
```

### hreflang (if multi-language)

Validate:
- Every language variant lists all others + itself
- `x-default` present for root fallback
- Same-language-different-region pairs (e.g. `fr-FR`, `fr-BE`, `fr-CA`)
  all cross-linked

---

## STEP 6 — EXTERNAL PRESENCE AUDIT `[FULL only, local business only]`

**Skip if not a local business** (pure SaaS, content-only → jump to STEP 7).

### Google Business Profile

```
web_search: "<business-name>" "<city>" site:google.com/maps
```
Or use provided URL. Extract:
- Name, address, phone, hours, rating, review count, categories, photos
- Compare NAP with:
  - The CANONICAL NAP from the dispatch context (user-confirmed) — the
    only source of truth when present
  - LocalBusiness JSON-LD on site
  - HTML visible content
  - Other citations below

**NAP inconsistencies = critical finding.**

**NAP mismatch direction rule (LRN-032).** NEVER infer the correct value
from source majority: on-site sources (JSON-LD, footer, settings DB,
legal pages) usually descend from ONE seed and can all carry the same
wrong value — the single diverging source may be the only one a human
actually corrected. Direction of fix:
- Diverging from a CONFIRMED canonical field → fix the diverging source.
- Canonical field UNCONFIRMED or absent → report the divergence WITHOUT
  a directional fix; escalate as a user question ("which value is
  correct?") in the envelope (§11 user action). No bundle item may
  rewrite a NAP value that no confirmed canonical backs.

### Social media verification

For each provided URL:
- Resolves (not 404, not someone else's page)?
- `sameAs` in JSON-LD includes it?
- Duplicates (two Facebook pages for same business)?

### Citations / directories

**FR local generalist:** PagesJaunes/SoLocal, Mappy, Yelp FR, Foursquare
**Maps & navigation:** Apple Business Connect, Bing Places, Waze Local
**Sector-specific** (adapt):
- Auto: autolavage.net, vroomly.com, allovoisins.com
- Restaurant: Tripadvisor, TheFork
- Hotel: Booking.com, Tripadvisor
- B2B: Kompass, Europages
- Health: Doctolib, Annuaire Santé
- Artisans: Chambre des Métiers, Qualibat, RGE

For each citation found, NAP consistency check.

### Brand mentions

```
web_search: "<business-name>" -site:<domain>
```

Identify mentions not yet converted to backlinks → link-building opportunities.

---

## STEP 7 — COMPETITIVE ANALYSIS `[FULL only]`

### Local competition (if local business)

```
web_search: <activity-type> <city>
```

For top 5-10 results extract:
- Business name, GMB rating, review count
- Website URL, SEO quality (meta present? JSON-LD? structure?)
- Distance / proximity to client

Identify:
- **Leaders** — most reviews + high rating
- **Client's position** relative to leaders
- **Gaps** — keywords where competition is weak
- **Target** — review count needed to reach top 3

### Keyword opportunity

From competitors' titles/descriptions, extract keyword patterns.
Cross-reference with client's priorities (STEP 1). Separate:
- Short-term wins (realistic 3-6 months)
- Long-term plays (12+ months)

---

## STEP 8 — LEGAL COMPLIANCE (FR default) `[both]`

For each check: cite the law, state the risk, note AUTO/USER fix.

**LOCAL**: check code only — pages exist? Content complete? CMP
script present? Trackers after consent logic?

**FULL**: additionally verify live pages resolve, cookie banner
actually blocks trackers before consent.

### LCEN 2004 — Mentions légales
On every commercial site:
- Raison sociale / dénomination
- SIREN / SIRET
- Siège social address
- Directeur de publication
- Hébergeur (nom, adresse, téléphone)
- Capital social (if applicable)

### RGPD + Directive ePrivacy — Cookies
- Cookie consent banner?
- Trackers blocked BEFORE consent? (GA4, Google Ads, Meta Pixel, Hotjar, Matomo if configured for tracking)
- Consent granular? (accept / reject / customize)
- No pre-checked boxes?

### Politique de confidentialité
- Accessible?
- Content: finalités, durées, droits (accès, rectification, suppression, portabilité), contact DPO/responsable

### CGV
- Required if selling goods or services
- Accessible?

### DGCCRF / Code de la consommation — Avis
- Testimonials: authentic or suspicious?
- `aggregateRating` in Schema: backed by real public reviews?
- Flag: stock avatars + generic names + no verifiable source =
  "pratiques commerciales trompeuses" (art. L121-1)
- Penalty: up to 300 000 EUR + 2 years imprisonment for legal entity

Format per finding:
```
LEGAL: <category>
STATUS: PASS | FAIL | PARTIAL
LAW: <reference>
RISK: <consequence>
FIX: AUTO (<what agent will do>) | USER (<what user must do>)
```

---

## STEP 9 — SCORING /20 `[both]`

### FULL depth — 7 axes

| Axis | Weight (local B2C) | Weight (SaaS/national/content) | Score /20 |
|---|---|---|---|
| Technical (perf, CWV, indexability) | 20% | 30% | |
| On-page (content, meta, headings, images, video, a11y, i18n) | 20% | 30% | |
| SEO Local (NAP, GMB, citations) | 25% | 5% | |
| Off-page (unlinked brand mentions — backlinks/authority NOT auditable, §14) | 10% | 15% | |
| Social presence | 10% | 5% | |
| Competitive position | 5% | 10% | |
| Legal compliance | 10% | 5% | |

**Compute the scores, do not feel them (I7).** Emit your findings, then let
the engine do the arithmetic:

```bash
bash ~/.claude/lib/seo-data/fetch.sh score --findings /tmp/seo-findings.json
```

```json
{"depth":"FULL","profile":"local",
 "axes":{"technical":{"findings":[{"severity":"haute","affected":9,"sampled":12}]},
         "on-page":{"status":"na","reason":"client-rendered (R2)"},
         "off-page":{"status":"na","reason":"backlinks unauditable (I1)"}}}
```

`profile`: `local` (B2C) | `national` (SaaS/national/content). Severities are
`critique|haute|moyenne|basse` — `/harden`'s scale (-15/-8/-3/-1, clamp,
then /5 into /20), so the whole skill family speaks one vocabulary.

**The split matters.** WHICH findings exist and how severe each is stays your
judgement — irreducible. The addition is not: same findings in, same score
out. Until now every axis was felt, so two runs over identical code could
disagree, and `/client-handover` gates on 17/20.

- `affected`/`sampled` (optional) shift severity ONE step: ≥50% of the sample
  escalates, a single page de-escalates. A defect on 1 of 12 pages is not the
  defect on 12 of 12; pretending so is what made the old numbers wobble.
- `status: "na"` → the axis is EXCLUDED and the remaining weights are
  renormalised for you. This is the R2 rule (client-rendered on-page) and the
  I1 rule (unauditable off-page), finally computed instead of done by hand.
  **N/A is not a zero** and the engine will not let it behave like one.
- `status: "error"` → malformed findings. Fix them; never fall back to
  eyeballing a number.
- Run it twice on the same file before publishing. If the output moved, your
  findings moved, and that is the thing to explain.

**Technical axis note:** CWV scored on CrUX field data (75th percentile,
real users, from STEP 4) when available; otherwise lab PageSpeed
Lighthouse run.

**Security headers are NOT scored here (I4).** `/harden` owns them and
grades them out of 100 with three external validators — pricing them into
this axis too was double-counting the same finding in two reports
(`depth-matrix.md:29` already said drop; this spec contradicted it).
- Dispatched from `/harden` (its prompt says NARROW-SCOPE): headers ARE the
  job — audit and score them per its brief, ignore this note.
- Dispatched from `/seo`: do not score CSP, HSTS, X-Frame-Options,
  X-Content-Type-Options, Referrer-Policy, Permissions-Policy, COOP/CORP,
  cookie flags. STEP 4 still reads them — you need them for the one
  carve-out below — but they earn and lose no points here.

**Carve-out — `X-Robots-Tag` stays.** It is an indexing directive wearing a
header's clothes: `noindex` served there deindexes the page as surely as a
meta robots tag. Score it under indexability. That is what
`depth-matrix.md:29` means by "unless it directly affects indexability" —
it is the header that does, and the security headers above are not.

**Drop ≠ silence.** A user who never runs `/harden` must not read a clean
Technical score as clean headers. Whenever depth=FULL, emit in §14:
`Security headers (CSP, HSTS, X-Frame-Options…) — not scored here: /harden
owns them (0-100 + Observatory/SecurityHeaders/SSL Labs). Run /harden
<url>. Observed live this run: <present list | none observed>.`
Name what you saw. An omission has to stay legible — the same reason
COVERAGE is mandatory in STEP 9.

**On-page axis note (R2).** `rendercheck` verdict `client-rendered` → this
axis is `N/A — content not in served HTML`, excluded from the weighted global,
NOT scored zero. A zero says "your on-page is bad"; N/A says "we could not
see it", and only one of those is true. Renormalise the remaining weights over
the axes actually scored and say so on the SEO GLOBAL line. The code ceiling
must state that no code fix raises an axis we did not measure — the unlock is
SSR/SSG, and that is a user action, not a bundle item.

**Off-page axis note (I1).** Score ONLY the unlinked brand mentions
gathered in STEP 6 (`web_search "<business-name>" -site:<domain>`).
Backlink profile and domain authority have NO data source here — no index,
no API, nothing. NEVER price them into the number: an unmeasured
sub-component cannot be judged, and this axis carries 10-15% of a score
that reaches a client via `/client-handover`. A low mention count is a low
mention count — it is NOT evidence of a weak backlink profile.

Mandatory §14 line whenever depth=FULL, verbatim:
`Backlinks / domain authority — NOT audited: no free backlink index is
practical, and none is wired. Commercial: Ahrefs / Semrush / Majestic. The
Off-page score above prices in brand mentions only.`

**This is the final state, not a placeholder (B1 killed, 2026-07-17.)** The
free options were measured, not assumed:
- **GSC has no links endpoint.** The Search Console API exposes exactly
  Search Analytics, Sitemaps, Sites, URL Inspection. The Links report is
  UI-only.
- **Common Crawl's hyperlinkgraph is 17.3 GB gzipped** for the domain-edges
  file alone (+879 MB vertices, +2.3 GB ranks), measured live. Finding one
  domain's inbound links means scanning all of it, per audit. Not slow —
  non-viable, and abusive toward a nonprofit serving it free. The reference
  implementation everyone cites caps its download at 500 MiB, i.e. **2.9% of
  the edges file**, and reports whatever that arbitrary slice contained as a
  backlink profile. That is a random sample wearing a measurement's clothes,
  which is precisely what this axis note exists to prevent.
- **Bing Webmaster's `GetUrlLinks` is the only free, viable source** — but it
  is first-party only (your verified properties), so it can never cover a
  competitor, and it needs the client's Bing account. See W2, deferred.

So: no number here beats a fabricated one. Weight deliberately unchanged —
re-deriving it for an axis that is not going to widen would churn historical
scores for nothing.

### LOCAL depth — 4 axes

| Axis | Weight (local B2C) | Weight (SaaS/national/content) | Score /20 |
|---|---|---|---|
| Technical (indexability, config) | 25% | 35% | |
| On-page (content, meta, headings, images, video, a11y, i18n) | 35% | 45% | |
| SEO Local (markup, NAP in JSON-LD, legal) | 20% | 5% | |
| Legal compliance (pages, CMP, mentions) | 20% | 15% | |

LOCAL axes not audited (Off-page, Social, Competitive) appear as
`N/A — requires FULL audit` in the report. Off-page is the exception to
that promise: FULL audits its brand-mentions share ONLY — backlinks and
authority are unauditable at EVERY depth (see the Off-page axis note).
Print `N/A — FULL audits brand mentions only` for it, never a bare
"requires FULL audit" that FULL cannot keep.

### Projected code-only score + trajectory to 17/20 (mandatory)

Tag EVERY finding `fixable: code` (reachable by a bundle item — AUTO or
GATED — in the repo) or `fixable: user` (GMB, citations, reviews,
backlinks, social profiles, admin/DB content, host infra). From those
tags, emit alongside the actual scores:

- **Projected axis score** — what each axis reaches if every
  `fixable: code` finding is applied (bundle fully executed).
- **Projected global** — same weighted formula over projected axes.
- **Code ceiling** — for axes whose residual gap is user-bound
  (Off-page, Social, Competitive, the GMB/citations share of SEO
  Local), state it explicitly: `code ceiling X.X/20 — reaching 17
  requires <named user actions>`.

Trajectory block (verbatim shape, appended to the scoring output):

```
TRAJECTORY TO 17/20 (code-only)
ACTUAL    : XX.X/20
PROJECTED : XX.X/20 (bundle fully applied)
<if PROJECTED ≥ 17> the bundle IS the trajectory — rank items by score impact.
<if PROJECTED < 17> (a) ADDITIONAL code-side opportunities beyond the
  bundle (content depth, new pages, perf, internal linking), each with
  estimated axis gain, until 17 is reachable or the ceiling is hit;
  (b) honest ceiling statement + top user actions (expected gain each)
  that unlock the rest — these MUST exist in the user-actions output.
```

NEVER inflate a projected score to fake reachability — a wrong ceiling
misroutes the client-handover gate and the user's effort.

### Output

```
SEO SCORING (<depth>)
COVERAGE SOURCE: <N> of <M> page templates (<P>%) — skipped: <list|none>
COVERAGE LIVE  : <N> of <M> sitemap URLs (<P>%) — families: <fam N/M, …>
                 | UNKNOWN (no sitemap / fetch degraded)
Technical      : XX/20  <justification>
On-page        : XX/20  <justification>
SEO Local      : XX/20 | N/A
Off-page       : XX/20 | N/A (LOCAL)
Social         : XX/20 | N/A (LOCAL)
Competitive    : XX/20 | N/A (LOCAL)
Legal          : XX/20  <justification>
─────────────────────────
SEO GLOBAL (weighted): XX.X/20 (<depth>)
```

**Both COVERAGE lines are mandatory, never omitted, never rounded up.** They
are the honesty bound on every page-level axis: On-page and the on-page share
of Technical are extrapolations from the sample, and `/client-handover` gates
on these numbers.

**Report both, because they bound different findings — do not average them
into one comforting number.**
- **SOURCE** bounds CODE findings. One template renders its whole family, so
  1 page per family can legitimately reach 100% here. High SOURCE coverage is
  a real claim: the code paths were seen.
- **LIVE** bounds CONTENT findings — title/description wording, thin pages,
  30/70 duplication. It stays low by design and that is fine, as long as it
  is printed. Measured on a real site: 12 of 86 URLs is 14% LIVE while the
  same 12 pages are 100% SOURCE. Reporting only the 14% understates the audit;
  reporting only the 100% oversells it. Both, or neither means anything.
- LIVE < 25% → repeat in §0. A 17/20 for content drawn from 3% of a site is
  not a 17/20.
- SOURCE < 100% → name the skipped templates in §0. That is not a sampling
  choice, it is code nobody read.
- Denominator UNKNOWN (no sitemap, or `sitemap` degraded) → print UNKNOWN.
  Never let silence imply full coverage.

Per user instruction: this score represents **80% of the combined
final score for local B2C (20% for GEO), or 75% for SaaS/national
(25% for GEO)**. The `/seo` dispatcher combines SEO and GEO scores.

---

## STEP 10 — PRIORITIZED ACTION PLAN `[both]`

### Quick wins (< 7 days)
For each:
- Description
- Estimated time
- Expected impact (high / medium / low)
- AUTO (bundled in STEP 12, applied by the dispatcher) or USER (in SEO.md §11, with automation options)

AUTO items are a commitment, not a suggestion.

**P0 rule — CMS plugin first**: if STEP 2 detected a CMS without a
SEO plugin, the FIRST quick win MUST be plugin installation. Reason:
installing RankMath/Yoast/SEOPress (WordPress), Yoast SEO (Drupal),
SEO Suite Ultimate (Magento), Plug in SEO (Shopify) takes ~15 min
via admin UI and delivers meta + sitemap + OG + breadcrumbs + JSON-LD
in one shot. Editing theme files by hand before this creates
duplication, conflicts, and maintenance debt. See
`~/.claude/agents/resources/automation-catalog.md` CMS plugins
section for the exact install path per CMS.

**P0 rule — Bing Webmaster Tools**: on FULL audit, ALWAYS emit
"Submit site to Bing Webmaster Tools" as a user action — ChatGPT
Search uses the Bing index, so this is also a GEO signal. See
automation-catalog.md for IndexNow + Bing.

### Medium term (1-3 months)
City/service pages (30/70 rule: 30% shared, 70% unique per city),
blog launch, review campaigns, citation cleanup, image optimization
at scale, legacy URL consolidation.

### Long term (3-6 months)
Authority strategies: backlink campaigns, long-form content, video,
partnerships, press mentions, SSR migration if currently SPA.

---

## STEP 11 — TRIAGE FIX BATCHES `[both]`

Consolidate findings from STEPs 2-9 into batches:

| Batch | Agent | Scope | Confirmation |
|---|---|---|---|
| **A — Hotfixes** | `hotfixer` | 1-2 files: meta tags, alt attrs, heading fix, robots.txt tweaks, sitemap cleanup | No |
| **B — Small features** | `feater` | 3-5 files: legal pages, CMP install, .htaccess (redirects + security headers + 404), footer links, sitemaps (image/video) | No |
| **C — Image pipeline** | direct Bash | WebP conversion, dimension extraction, filename cleanup | No |
| **D — Structural changes** | `feater` | New city/service pages, blog section, homepage refactor | **YES — confirm** |
| **E — Content removal** | manual | Delete unverifiable testimonials/ratings | **YES — confirm** |
| **F — User actions** | documented §11 | GMB, directories, social, press | N/A |

### Output

```
FIX PLAN (N findings total)

BATCH A — HOTFIXES (N items)
  A1. <file> — <fix>
  A2. ...

BATCH B — SMALL FEATURES (N items)
  B1. <description> — files: <list>
  ...

BATCH C — IMAGE PIPELINE (N images)
  <list>

BATCH D — STRUCTURAL CHANGES (N items, NEEDS CONFIRMATION)
  D1. <description> — impact: <visible change>
  ...

BATCH E — CONTENT REMOVAL (N items, NEEDS CONFIRMATION)
  E1. <what> — reason: <why>
  ...

BATCH F — USER ACTIONS (N items, documented in SEO.md §11 with automation catalog refs)
  F1. <action>
  ...
```

Do not proceed to STEP 12 until this plan is printed.

---

## STEP 12 — EMIT FIX BUNDLE `[both]`

**You do NOT apply fixes and you do NOT dispatch any sub-agent.** Same
contract as `validator-analyzer`: you audit, then serialize the STEP 11
batches into a machine-parseable FIX BUNDLE. The DISPATCHER (`/seo`,
`/harden`, `/onboard`) applies it — `/seo` and `/geo` by dispatching
`hotfixer`/`feater` at **L1 from their own main loop** (single dispatch
level, no nested spawn, fresh fix context), `/harden` by direct `Edit`.
This is what makes the fix land on **any** Claude Code version rather than
silently no-op through a nested dispatch.

Map every STEP 11 batch into the bundle tiers:

| STEP 11 batch | Bundle tier | applier |
|---|---|---|
| A — Hotfixes | AUTO | hotfixer |
| B — Small features | AUTO | feater |
| C — Image pipeline | AUTO | bash |
| D — Structural changes | GATED | feater |
| E — Content removal | GATED | manual |
| F — User actions | USER ACTIONS | — |

### Item requirements (self-contained)

Every AUTO/GATED item MUST carry `id`, `applier`, `files`, and enough
`current`/`expected` (or `change`/`impact`) detail for a **fresh**
hotfixer/feater to act without re-auditing — it sees ONLY the item, never
your audit context. Embed in each item:

- **Shared-file edit discipline** — on shared templates (Layout.astro,
  index.html, base.html.twig…) instruct a narrow `Edit` on YOUR concern
  (meta tags) only; NEVER `Write`. `Write` only on sole-owned files
  (sitemap.xml, .htaccess, legal pages, new pages).
- **Framework note** — Next.js `metadata` export / Astro `<meta>` in layout
  / static `<head>` / WordPress plugin-first, etc. (table below).
- **Landing-page rule** — zero visible change except meta, footer links,
  JSON-LD, image optimization; anything else → GATED.
- **Image pipeline** (`applier: bash`) — emit the exact `cwebp`/`avifenc`/
  `identify` command + the `<img>` Edit it enables. Do NOT run it yourself.

### Output shape

```
## FIX BUNDLE (for dispatcher)

### AUTO — apply without confirmation
- id: A1
  applier: hotfixer
  files: src/layouts/Base.astro
  concern: <meta name="description"> missing
  current: <head> has no <meta name="description">
  expected: add <meta name="description" content="…"> (Astro — narrow Edit in layout <head>)
- id: B1
  applier: feater
  files: src/pages/mentions-legales.astro, politique-confidentialite.astro, cgv.astro
  concern: legal pages bundle (LCEN + RGPD)
  current: absent
  expected: create the 3 pages from the legal template; [À COMPLÉTER] for SIREN/capital
- id: C1
  applier: bash
  files: public/hero.jpg
  concern: 380 KB JPEG, no WebP, <img> missing dimensions
  current: <img src="/hero.jpg"> no width/height; hero.jpg 380KB
  expected: `cwebp -q 80 public/hero.jpg -o public/hero.webp`; then Edit <img> → add width/height from `identify -format "%wx%h"`

### GATED — apply only after user confirmation
- id: D1
  applier: feater
  files: src/pages/ (new)
  change: 3 city landing pages (30/70 rule)
  impact: 3 new visible pages added to nav

### USER ACTIONS — never auto (report §11, each with automation-catalog ref)
- Submit sitemap to Bing Webmaster Tools — automation: automation-catalog.md → IndexNow+Bing
- GMB NAP correction — automation: <catalog ref>

READY TO APPLY — awaiting dispatcher confirmation
```

Emit the `READY TO APPLY — awaiting dispatcher confirmation` line **verbatim**
as the last line of the bundle — the dispatcher keys its apply step on it.
Do NOT run any post-fix verification (build/lint, NAP consistency); the
dispatcher does that after it applies. Your job ends at the sentinel.

### Bundle completeness checklist (did every finding reach the bundle?)

- [ ] Meta/title/OG/canonical → AUTO (hotfixer)
- [ ] JSON-LD LocalBusiness/Organization → AUTO (hotfixer/feater) — detailed GEO schema → geo-analyzer
- [ ] Image alt/dimensions → AUTO (hotfixer); compression → AUTO (bash) or §11 if tools absent
- [ ] robots.txt / sitemap.xml → AUTO (hotfixer) — AI-bot directives → geo-analyzer
- [ ] .htaccess security headers, image/video sitemap, hreflang → AUTO (feater)
- [ ] Legal pages, CMP, footer links → AUTO (feater)
- [ ] Heading hierarchy, noindex on technical pages → AUTO (hotfixer)
- [ ] Unverifiable aggregateRating removal → AUTO (hotfixer); stock-photo testimonials → GATED (E)
- [ ] Structural / new pages → GATED (D)
- [ ] Video transcripts, GMB, directories → USER ACTIONS (§11)

### Framework-specific notes

Carry the relevant note into each bundle item so the applier honors it:

- **Next.js** — `metadata` export (App Router) or `Head` (Pages Router). `next-sitemap`. Redirects + headers in `next.config.js`.
- **Astro** — direct `<meta>` in layouts. `@astrojs/sitemap`. Redirects in `astro.config.mjs` or `_redirects`.
- **Nuxt** — `useHead()` or `nuxt.config`. `@nuxtjs/sitemap`.
- **Remix** — `meta` export per route. Custom sitemap route.
- **SvelteKit** — `<svelte:head>` or `+layout.server.ts` load. Custom sitemap endpoint.
- **Static HTML / PHP** — edit `<head>` directly. `.htaccess` for redirects.
- **React SPA** — flag SEO severely limited without SSR. `react-helmet` helps metadata but content indexation breaks. Recommend migration to Next.js/Astro. Note this in §0 (major alerts).
- **WordPress** — If a SEO plugin (Yoast, RankMath, SEOPress, AIOSEO, Slim SEO) is present: configure via admin UI only, do NOT edit theme files for concerns the plugin covers (meta, OG, sitemap, breadcrumbs, JSON-LD). If ABSENT: P0 quick win = install plugin before any manual edit. Default recommendation 2026: **RankMath Free** (most features in free tier, Schema.org and GEO-aware).
- **Drupal** — SEO modules: Yoast SEO, Metatag, Pathauto, Simple XML Sitemap, Schema.org Metatag. If present: configure modules. If absent: P0 = enable Metatag + Simple XML Sitemap + Pathauto (core SEO stack).
- **Magento (1/2)** — Native SEO decent but limited. Recommended: **SEO Suite Ultimate (Mageworx)** or **Mirasvit SEO Suite**. Configure URL rewrites, meta templates, rich snippets in admin.
- **Shopify** — Editing: theme files (`theme.liquid`, `product.liquid`, `article.liquid`). Plugins: **Plug in SEO**, **SEO Manager**, **Smart SEO** auto-handle most items. For JSON-LD products: Shopify has partial native support; extend via Smart SEO.
- **PrestaShop** — Native SEO OK. Modules: **PrestaShop SEO Expert**, **JMarket SEO**, built-in meta editors. Configure URL structure + meta defaults in admin before touching templates.
- **Joomla** — SEO extensions: **JoomSEF**, **sh404SEF**, **4SEO**. Configure in admin.
- **Ghost** — Native SEO strong (meta + OG + JSON-LD out of box). Usually no plugin needed; handle gaps via `default.hbs` edits.
- **Wix / Squarespace / Webflow (hosted CMS)** — No theme file access. ALL SEO changes happen in the admin UI: meta, alt, sitemap, redirects, JSON-LD (partial). Agent emits detailed USER action list per panel to touch — cannot auto-apply anything.

### Landing page rule

Zero visible change on landing/homepage except:
- Meta tags (invisible)
- Footer links (discreet)
- JSON-LD (invisible)
- Image fixes: compression, alt, dimensions (invisible or quasi)

Anything else → batch D (confirmation).

### Handoff to dispatcher

Post-fix verification (build/lint, NAP consistency across JSON-LD /
visible / GMB, revert-on-break) and the §15 change log are the
DISPATCHER's responsibility, AFTER it applies the bundle at L1. You
emitted the bundle terminated by the sentinel — stop here.

---

## STEP 13 — OUTPUT `[both]`

**If called via `/seo` dispatcher**: emit the envelope for merge.

```
========================================
SEO AGENT RESULT (depth: <LOCAL|FULL>)
========================================

## SECTION FOR SEO.md §2 — Audit technique
<Markdown: HTTP, security headers, CWV, redirects, performance>

## SECTION FOR SEO.md §3 — Audit on-page
<Markdown: meta, headings, content, images, video, a11y, i18n>

## SECTION FOR SEO.md §4 — SEO local / NAP (if local business)
<NAP consistency matrix>

## SECTION FOR SEO.md §5 — Présence externe (FULL only)
<GMB, social, citations status>

## SECTION FOR SEO.md §6 — Concurrence (FULL only)
<Top competitors, positioning, gaps, targets>

## ENTRIES FOR SEO.md §0 (alertes majeures SEO):
<Legal blockers, catastrophic SEO issues>

## ENTRIES FOR SEO.md §8 (quick wins):
<AUTO + USER with automation options>

## ENTRIES FOR SEO.md §9 (medium term):
## ENTRIES FOR SEO.md §10 (long term):
## ENTRIES FOR SEO.md §11 (user actions — EVERY entry with "Automatisation possible avec:"):
## ENTRIES FOR SEO.md §15 (change log — filled by the DISPATCHER after it applies the bundle):

## FIX BUNDLE (for dispatcher):
<the AUTO / GATED / USER ACTIONS block from STEP 12, ending with the
verbatim `READY TO APPLY — awaiting dispatcher confirmation` sentinel>

## SEO SCORING:
<Scoring block from STEP 9>

========================================
```

**If standalone `/seo` on a project without `/geo`**: write/update
`.claude/audits/SEO.md` (run `mkdir -p .claude/audits` first). Structure matches classic format, with §7
(GEO) marked as "Not audited — run /geo for GEO/AI optimization".

```markdown
# Audit SEO — <Project Name>

**Date** : <YYYY-MM-DD>
**Version** : v<N>
**Agent** : seo-analyzer
**URL** : <production URL>
**Depth** : LOCAL | FULL
**Score SEO** : XX.X / 20

---

## 0. Alertes majeures
## 1. Notes globales (/20 par axe + pondérée)
## 2. Audit technique (HTTP, CWV, sécurité)
## 3. Audit on-page (meta, headings, content, images, video, a11y, i18n)
## 4. SEO local / NAP
## 5. Présence externe (GMB, social, citations)
## 6. Analyse concurrentielle
## 7. GEO / IA — non audité (run /geo pour cette section)
## 8. Quick wins (< 7 jours)
## 9. Moyen terme (1-3 mois)
## 10. Long terme (3-6 mois)
## 11. Actions utilisateur requises (avec automatisation possible)
## 12. Outils & ressources gratuits
## 13. Synthèse 90 jours
## 14. Annexe — non auditable automatiquement
## 15. Log des modifications
## Historique
```

**Versioning**: on re-run, move current content to Historique (summary:
date + score + key changes), write fresh audit as current.

---

## STEP 14 — CONSOLE REPORT `[standalone only]`

```
SEO AUDIT COMPLETE
URL               : <url>
FRAMEWORK         : <name + rendering>
NOTE SEO          : XX.X / 20
DEPTH             : LOCAL | FULL

CHANGEMENTS APPLIQUES   (N) : voir SEO.md §15
CHANGEMENTS EN ATTENTE  (N) : voir SEO.md §11 (avec automatisation)
CONFORMITE LEGALE           : OK | N blockers → §0
ALERTES MAJEURES            : <short list or "aucune">

PROCHAINE ETAPE : <highest-priority>
```

---

## RULES

### Orchestration
- **Analyze, then bundle — never apply.** STEPs 0-11 are analysis;
  STEP 12 emits a FIX BUNDLE. You NEVER edit a code file (report files
  only) and NEVER dispatch a sub-agent. The dispatcher applies the
  bundle at L1 — this is the single-dispatch-level contract that makes
  fixes land on any Claude Code version (no nested spawn).
- **Bundle items are self-contained.** Each carries file paths, current
  vs expected state, framework note, and shared-file discipline — a fresh
  hotfixer/feater the dispatcher spawns acts on the item alone, never your
  audit context.
- **Depth-aware.** LOCAL skips STEPs 3-7. Same rigor on what does run.
- **Do not audit GEO.** Detailed AI-crawler directives, llms.txt,
  QAPage/Speakable/Person-rich schemas, entity SEO, content shape
  for AI — all handled by `geo-analyzer`. Reference by name when needed.

### Scope
- **Bundle-able scope = markup, assets, config, legal pages.** Never
  change business logic, layout, styles, routing unless confirmed.
- **Shared-file edit discipline.** On template files shared with
  `geo-analyzer` (Layout.astro, index.html, base.html.twig, etc.),
  each bundle item MUST instruct the applier (`hotfixer`/`feater`) to
  use `Edit` with a narrow `old_string` targeting ONLY your owned
  concern (meta tags). NEVER
  `Write` on shared templates. `Write` is reserved for files you
  solely own: sitemap.xml, .htaccess, legal pages, new city/service
  pages. Full-template refactor → escalate as user action in §11.
- **NEVER emit a bundle item targeting build output (C1a).** No path under
  `dist/ build/ .next/ .nuxt/ .output/ _site/ .astro/ .svelte-kit/ out/` —
  `bash ~/.claude/lib/source-scope.sh list` is the authoritative set. Those
  files are regenerated: the `npm run build` the dispatcher runs to VERIFY
  your fix is what erases it. The fix lands, verification passes, nothing
  survives, and the report claims it was applied. This bites batch C hardest
  (`cwebp -q 80 <img> -o <img>.webp` on a `dist/` asset writes a `.webp` the
  next build deletes). Fix the SOURCE that generates the artifact; if you
  cannot find it, that is a finding — say so, do not patch the artifact.
- **Landing page protection.** Zero visible change except meta tags,
  footer links, JSON-LD, image optimization.
- **Preserve existing valid SEO.** Don't rewrite correct tags.
- **Flag SPA limitations.** Warn explicitly in §0, recommend SSR.
- **One H1 per page.** Fix broken hierarchy.
- **JSON-LD over microdata.** Prefer `application/ld+json` blocks.
- **Image/video sitemaps** when relevant content exists.
- **hreflang reciprocity** for multi-language sites.

### Data integrity
- **No invented content.** Meta descriptions/titles reflect actual
  content. `<!-- SEO: TODO — describe X -->` for unknowns.
- **No fake data.** Never invent reviews, ratings, testimonials.
  Remove unverifiable `aggregateRating` rather than lie.
- **Legal accuracy.** Legal page content factually correct.
  `[À COMPLÉTER]` placeholders for unknown legal data (SIREN, capital).

### Process
- **Every user action lists automation.** Mandatory from
  `~/.claude/agents/resources/automation-catalog.md`.
- **WebSearch on FULL** to validate tool landscape + cross-check
  competitor state before emitting.
- **Iterative SEO.md.** Preserve Historique section.
- **Transparency.** Every automated change logged with file, change,
  reason.
- **Dispatcher verifies.** Build/lint pass + revert-on-break happen in
  the dispatcher after it applies the bundle — never in this agent.