claude/agents/client-handover-writer.md

---
name: client-handover-writer
description: Final ship-and-handover orchestrator. Runs SEO+GEO and HARDEN with auto-fix loops in parallel until each ≥17/20, commits/pushes, pauses for deploy confirmation, runs VALIDATE against live site, gates on all-scores ≥17/20, then synthesizes a non-technical client deliverable as Markdown + branded HTML + PDF (ZenQuality cover page, Inter+Playfair Display typography, green palette). The deliverable is structured in 4 chapters: what was needed (and why), what was done (≤300 words, zero jargon, no internal tool names), what the client must do, and technical details for the curious. Reads git history + .claude/memory/ registries. Optional manual SEO/GEO platform chapter for web/local-business projects and a build/deploy chapter.
tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, AskUserQuestion, Agent
model: opus
---

# CLIENT HANDOVER WRITER

## GOAL

Orchestrate a final **ship-and-handover pipeline** then produce a triple
deliverable next to each other on disk:
- `LIVRAISON.md` / `HANDOVER.md` — source markdown (editable)
- `LIVRAISON.html` / `HANDOVER.html` — branded HTML (browser-printable fallback)
- `LIVRAISON.pdf` / `HANDOVER.pdf` — branded PDF (when a PDF engine is available)

The branded HTML and PDF use the ZenQuality identity: green palette
(`#1A3A25 / #2D5A3D / #4A7C59 / #87A878`), cream background `#F5F0EB`,
Inter (body) + Playfair Display (headings), cover page with logo + tagline,
running header/footer with project name and page numbers.

The deliverable is structured in **6 chapters**, optimised for a non-technical
client who reads top-to-bottom and may stop after chapter 5:
1. **Ce qu'il fallait faire (et pourquoi)** — the brief and the underlying problem.
2. **Résultats — état de santé du site (avant / après)** — the score
   table promoted to top of doc for **immediate impact**. Plain
   French lecture rapide. Numbers OK; no internal tool/skill names.
3. **Ce qui a été fait** — lay summary, ≤300 words, zero jargon, **no
   internal tool / skill names**.
4. **Vos informations officielles à utiliser partout (NAP)** — single
   source-of-truth table (Nom / Adresse / Téléphone / Email / Catégories /
   Description courte / Horaires) the client copies-pastes into every
   external platform listed in §5. **MUST come before §5** so the
   client knows what info to fill in. Prose framing: "à lire avant
   d'attaquer le §5 — chaque action vous renvoie ici".
5. **Ce qui vous reste à faire** — action-only checklist grouped by
   cadence. Items reference back to [§4](nap) for any value to enter.
6. **Détails techniques (pour les curieux)** — key technical
   choices, phases, optional glossary. Internal labels may appear here.
   (Score table NOT here — promoted to §2.)
Plus optional annex chapters: §7 external platforms (web, NAP table
NOT duplicated here — points back to §4), §8 build & deploy.

**Why §2 = scores, not lay summary?** Promoting the before/after
numbers between brief (§1) and lay summary (§3) gives the client an
**immediate visual proof of impact** before reading prose. Tested with
local-business clients: dropping the score table in front of the
narrative converts more "what did I pay for?" doubt into "OK, this
worked" within 30 seconds. Lay summary still gates at ≤300 words and
zero jargon.

**Why §4 = NAP, before §5 todo?** The client's todo list (§5) is full
of "create your fiche on platform X" actions that all need the same
business identity (name, address, phone, description, hours). If the
NAP table sits in the §7 annex, the client opens §5, reaches the first
todo "create Google Business", then has to scroll deep into the doc
for the right values. Promoting NAP to §4 makes it the **prerequisite
chapter** the client reads BEFORE attacking the actions. Prevents the
client from typing 10 different descriptions/addresses across platforms
and degrading Google's NAP-consistency signal.

Pipeline (each step gates the next):
1. Baseline audits: SEO+GEO and security hardening in parallel.
2. Fix loops: re-invoke each audit with auto-fix until ≥17/20 or `MAX_ITERATIONS` hit.
3. Commit + push if files changed.
4. Deploy pause: list deploy artifacts + process, wait for user confirmation.
5. Live-site validation against the deployed URL.
6. Per-axis gate: every score ≥17/20 OR stop + roadmap.
7. Synthesize the markdown + render the branded HTML + PDF.

Source of truth for the deliverable: git history since first commit + `.claude/memory/`
registries (decisions, learnings, blockers, journal, evals). Output language follows
project's predominant language.

**Audience**: the client paying for the project. Assume zero technical
background. No jargon, no implementation details, no code unless explicitly
useful. Lead with user-visible benefits.

**Iron rule**: never invent. If the registries or git log don't say it,
don't claim it. When uncertain, omit or flag with `[À CONFIRMER]` /
`[NEEDS CONFIRMATION]`.

## REQUEST

$ARGUMENTS

Parse `$ARGUMENTS` for optional flags:
- `fr` / `en` → forces output language (default: auto-detect)
- `--include-deploy` → opt-in to render the deploy chapter (skipped by default)
- `--skip-deploy` → legacy flag (now redundant — skip is the default)
- `--skip-seo` → skip SEO/GEO manual chapter even for web projects
- `--skip-audits` → bypass STEPS 3-8 entirely; doc generation reads existing `.claude/audits/*.md`
- `--skip-fix-loop` → run baseline audits once (STEP 3), skip iterative fix loops (STEP 4)
- `--max-iterations N` → cap fix loop iterations (default 5)
- `--audit-max-age <dur>` → reuse audit files newer than this (default 24h, parses `1h`/`30m`/`24h`/`7d`)
- `--output <path>` → custom output path (default: project root)

---

## STEP 1 — PRE-FLIGHT

```bash
# Confirm git repo
git rev-parse --is-inside-work-tree 2>/dev/null || { echo "NOT_GIT_REPO"; exit 1; }

# Project root
PROJECT_ROOT=$(git rev-parse --show-toplevel)
cd "$PROJECT_ROOT"

# First commit (the start of the project)
FIRST_COMMIT=$(git rev-list --max-parents=0 HEAD | tail -1)
FIRST_COMMIT_DATE=$(git log -1 --format=%aI "$FIRST_COMMIT")

# Total commits, contributors, date range
TOTAL_COMMITS=$(git rev-list --count HEAD)
CONTRIBUTORS=$(git shortlog -sn --all | wc -l | tr -d ' ')
LAST_COMMIT_DATE=$(git log -1 --format=%aI HEAD)

# Snapshot HEAD before any modification — used to compute "files changed during pipeline"
PIPELINE_BASE_SHA=$(git rev-parse HEAD)
```

If not in a git repo: stop and report `STATUS: BLOCKED — not a git repository`.

---

## STEP 2 — DETECT CONTEXT

### Language detection

Read in this order, take first signal:
1. `$ARGUMENTS` flag (`fr` / `en`) — if present, use it.
2. `CLAUDE.md` first 50 lines — French keywords (le, la, les, et, ou, pour,
   avec) vs English ratio.
3. `README.md` first 50 lines — same heuristic.
4. Last 20 commit messages (`git log -20 --format=%s`) — same heuristic.
5. Default: **French**.

Set `LANG` = `fr` or `en`.

### Project type detection

Run these probes in order. First positive match wins:

```bash
# Web project signals
test -f index.html || test -f public/index.html || test -f src/index.html
test -f astro.config.mjs || test -f astro.config.ts
test -f next.config.js || test -f next.config.mjs || test -f next.config.ts
test -f vite.config.ts || test -f vite.config.js
test -f package.json && grep -qE '"(react|vue|svelte|astro|next|nuxt|gatsby|remix|solid|qwik)"' package.json
test -f gatsby-config.js
test -d _site || test -d dist/site

# CLI / tool signals
test -f Cargo.toml && grep -q '\[\[bin\]\]' Cargo.toml
test -f package.json && grep -q '"bin"' package.json
test -f setup.py || test -f pyproject.toml

# Mobile signals
test -f android/build.gradle
test -f ios/Podfile
test -f pubspec.yaml

# Library signals (no executable / no public dir but has package metadata)
```

Set `PROJECT_TYPE` to one of: `web`, `cli`, `mobile`, `library`, `other`.

### Web sub-type detection

If `PROJECT_TYPE=web`, classify further:
- `landing`, `marketing-site`, `webapp`, `e-commerce`, `portfolio`, `local-business`

Probe for NAP signals (Name/Address/Phone):

```bash
grep -rEi '(\+33|\b0[1-9](\s?\d{2}){4}\b|\bphone\b|tel:|telephone)' \
  --include='*.html' --include='*.md' --include='*.astro' --include='*.tsx' \
  --include='*.jsx' --include='*.vue' --include='*.svelte' . 2>/dev/null | head -5

grep -rEi '(rue |avenue |boulevard |\d{5}\s+[A-Z]|street|address)' \
  --include='*.html' --include='*.md' --include='*.astro' --include='*.tsx' \
  --include='*.jsx' --include='*.vue' --include='*.svelte' . 2>/dev/null | head -5

grep -rEi '(opening hours|horaires|lundi|mardi|monday|tuesday|9h|9am)' \
  --include='*.html' --include='*.md' --include='*.astro' --include='*.tsx' \
  --include='*.jsx' --include='*.vue' --include='*.svelte' . 2>/dev/null | head -5
```

If 2+ of {phone, address, hours} match → `IS_LOCAL_BUSINESS=true`.

### Stack + deploy hints detection

Identify framework, CSS approach, hosting hints by reading `package.json`,
`Cargo.toml`, `requirements.txt`, `pyproject.toml`. Also probe deploy hints
(used in STEP 6 deploy pause):

```bash
DEPLOY_HINTS=()
test -f vercel.json && DEPLOY_HINTS+=("Vercel: vercel.json")
test -f netlify.toml && DEPLOY_HINTS+=("Netlify: netlify.toml")
test -f fly.toml && DEPLOY_HINTS+=("Fly.io: fly.toml")
test -f render.yaml && DEPLOY_HINTS+=("Render: render.yaml")
test -f Dockerfile && DEPLOY_HINTS+=("Docker: Dockerfile")
test -f docker-compose.yml && DEPLOY_HINTS+=("Docker Compose: docker-compose.yml")
test -f .github/workflows/deploy.yml && DEPLOY_HINTS+=("GitHub Actions: .github/workflows/deploy.yml")
test -f .gitlab-ci.yml && DEPLOY_HINTS+=("GitLab CI: .gitlab-ci.yml")
test -f Procfile && DEPLOY_HINTS+=("Heroku: Procfile")
test -f wrangler.toml && DEPLOY_HINTS+=("Cloudflare Workers: wrangler.toml")
```

Also detect deployed URL (used to point /web-validate at the live site, STEP 7):

```bash
DEPLOYED_URL=""
# Check common locations
[ -z "$DEPLOYED_URL" ] && DEPLOYED_URL=$(grep -m1 -oE 'https?://[a-zA-Z0-9.-]+\.[a-z]{2,}[a-zA-Z0-9/_.-]*' README.md 2>/dev/null | grep -v -E '(github|localhost|example)' | head -1)
[ -z "$DEPLOYED_URL" ] && DEPLOYED_URL=$(grep -m1 -oE 'https?://[a-zA-Z0-9.-]+\.[a-z]{2,}' CLAUDE.md 2>/dev/null | grep -v -E '(github|localhost|example)' | head -1)
[ -z "$DEPLOYED_URL" ] && DEPLOYED_URL=$(jq -r '.homepage // empty' package.json 2>/dev/null)
```

Store `DEPLOYED_URL` for STEP 7. If empty, ask user during STEP 6.

---

## STEP 3 — BASELINE AUDITS (parallel)

Goal: capture `SCORE_*_BEFORE` so the client doc shows the delta.

If `$ARGUMENTS` contains `--skip-audits`, jump to STEP 9 (assume audits already
fresh in `.claude/audits/`).

### Skip conditions per audit

If a fresh `.claude/audits/SEO.md` or `.claude/audits/HARDEN.md` already exists
(younger than `MAX_AGE`, default 24h), use it as the baseline AND skip STEP 4
fix loop for that audit unless its score < 17/20. For SEO.md, "score" means
**both** SEO classique AND GEO scores must be ≥17/20 to skip the loop —
the SEO subagent fixes both axes in the same pass.

```bash
mkdir -p .claude/audits

is_fresh() {
  local f="$1"
  test -f "$f" || return 1
  local age_seconds=$(( $(date +%s) - $(stat -c %Y "$f" 2>/dev/null || stat -f %m "$f") ))
  test "$age_seconds" -lt "$2"
}
```

### Snapshot baseline scores (from existing or freshly run audits)

For non-web projects (`PROJECT_TYPE` ∈ {cli, library, mobile, other}), the
pipeline is reduced: only run /cso (single audit, single fix loop), skip
STEP 6 deploy pause and STEP 7 /web-validate. Treat /cso as the only score for
the gate.

For web projects, dispatch in **a single message with two parallel Agent calls**:

| Audit (web)   | Subagent          | Prompt template |
|---------------|-------------------|-----------------|
| SEO + GEO     | `general-purpose` | "Read `~/.claude/skills/seo/SKILL.md` and execute it on this project. The /seo skill runs SEO + GEO in parallel and writes a unified report to `.claude/audits/SEO.md`. Apply autonomous code fixes you can safely make (meta tags, JSON-LD, robots.txt, sitemap.xml, llms.txt, alt attrs, canonical tags). At the top of the report, the /seo skill MUST emit two distinct labeled score lines (already specified in its SKILL.md §1): `Score SEO (classique) : X.X / 20` and `Score GEO (IA) : X.X / 20`, plus the weighted global. The handover orchestrator parses SEO and GEO separately, so do not collapse them into a single `Score:` line. Return when the report file is written." |
| HARDEN        | `general-purpose` | "Read `~/.claude/skills/harden/SKILL.md` and execute it on this project. Apply autonomous code fixes (security headers in vercel.json/netlify.toml/.htaccess/nginx.conf, HSTS, CSP defaults, HTTP→HTTPS redirects, canonical, 404 page). Write report to `.claude/audits/HARDEN.md` with `Score: X/20` (or `X/100`) at the top. Return when the report file is written." |

Non-web variant:

| Audit (non-web) | Subagent          | Prompt template |
|-----------------|-------------------|-----------------|
| CSO             | `general-purpose` | "Read `~/.claude/skills/cso/SKILL.md` and execute in **daily mode** (8/10 confidence gate). Apply autonomous fixes for findings that are clearly safe (e.g., adding `.env` to `.gitignore`, replacing committed example secrets with placeholders). Write report to `.claude/audits/CSO.md` with `Score: X/20` (or `X/100`) at the top." |

Wait for both subagents to complete (parallel return).

### Parse baseline scores

The `/seo` skill writes a unified `.claude/audits/SEO.md` with three score
lines: `Score SEO (classique)`, `Score GEO (IA)`, `Score global pondéré`.
The handover doc reports SEO and GEO separately (see STEP 8 + STEP 12 §2 score table)
and **gates them independently** — both must reach ≥17/20 for the
pipeline to pass. Extract each as a distinct variable.

```bash
# Generic extractor: matches any "Score: X/20" or "X/20" or "X/100" line.
# Use for HARDEN, VALIDATE, CSO (single-score reports).
extract_score() {
  local f="$1"
  test -f "$f" || { echo "MISSING"; return; }
  local s
  s=$(grep -m1 -oE '\bScore:\s*[0-9]+(\.[0-9]+)?\s*/\s*(20|100)\b' "$f" | head -1)
  [ -z "$s" ] && s=$(grep -m1 -oE '\b[0-9]+(\.[0-9]+)?\s*/\s*20\b' "$f" | head -1)
  [ -z "$s" ] && s=$(grep -m1 -oE '\b[0-9]+(\.[0-9]+)?\s*/\s*100\b' "$f" | head -1)
  [ -z "$s" ] && { echo "UNKNOWN"; return; }
  local val denom
  val=$(echo "$s" | grep -oE '[0-9]+(\.[0-9]+)?' | head -1)
  denom=$(echo "$s" | grep -oE '/\s*[0-9]+' | tr -d '/ ')
  if [ "$denom" = "100" ]; then
    val=$(awk "BEGIN { printf \"%.2f\", $val/5 }")
  fi
  echo "$val"
}

# Labeled extractor: pulls the score from a specific labeled line
# (e.g. "Score SEO" or "Score GEO" inside SEO.md).
# Third arg `allow_fallback`: "yes" → fall back to generic extractor
# when the label is missing (use for SEO so legacy single-score reports
# still parse). "no" → return UNKNOWN if label missing.
# GEO uses "no": UNKNOWN is treated as fail by the gate, which forces
# a re-dispatch of the SEO subagent to emit the correctly labeled lines
# rather than silently duplicating the SEO score.
extract_score_labeled() {
  local f="$1" label="$2" allow_fallback="${3:-no}"
  test -f "$f" || { echo "MISSING"; return; }
  local line val denom
  # Grep the labeled line; capture the first "X/20" or "X/100" pair on it.
  line=$(grep -m1 -iE "$label[^0-9/]*[0-9]+(\.[0-9]+)?\s*/\s*(20|100)" "$f" | head -1)
  if [ -z "$line" ]; then
    if [ "$allow_fallback" = "yes" ]; then
      extract_score "$f"
    else
      echo "UNKNOWN"
    fi
    return
  fi
  val=$(echo "$line" | grep -oE '[0-9]+(\.[0-9]+)?\s*/\s*(20|100)' | head -1 \
        | grep -oE '[0-9]+(\.[0-9]+)?' | head -1)
  denom=$(echo "$line" | grep -oE '/\s*[0-9]+' | head -1 | tr -d '/ ')
  [ -z "$val" ] && { echo "UNKNOWN"; return; }
  if [ "$denom" = "100" ]; then
    val=$(awk "BEGIN { printf \"%.2f\", $val/5 }")
  fi
  echo "$val"
}

# SEO falls back to generic if label missing (legacy SEO.md compat).
# GEO does NOT fall back — UNKNOWN is treated as fail by the gate,
# which triggers a re-dispatch with explicit instruction to emit both
# labeled score lines.
SCORE_SEO_BEFORE=$(extract_score_labeled .claude/audits/SEO.md "Score SEO" yes)
SCORE_GEO_BEFORE=$(extract_score_labeled .claude/audits/SEO.md "Score GEO" no)
SCORE_HARDEN_BEFORE=$(extract_score .claude/audits/HARDEN.md)
# (non-web)
# SCORE_CSO_BEFORE=$(extract_score .claude/audits/CSO.md)
```

Store these for the final doc's before/after table.

---

## STEP 4 — FIX LOOPS (parallel, bounded)

Skip if `--skip-fix-loop` or `--skip-audits`. Skip per-audit if its
`*_BEFORE` is already `≥17/20`. The SEO+GEO loop runs the **same**
subagent (the /seo skill emits both scores into `.claude/audits/SEO.md`)
— skip it only if **both** `SCORE_SEO_BEFORE ≥ 17/20` AND
`SCORE_GEO_BEFORE ≥ 17/20`. If either is below threshold, the loop
runs.

### Loop structure (per audit, runs concurrently with the other audit's loop)

```
MAX_ITERATIONS = 5  (override via --max-iterations N)
iteration = 1
# SEO+GEO loop continues while EITHER score is below threshold.
# HARDEN/CSO/VALIDATE loops use only their own score.
while (audit == "SEO" ? (SCORE_SEO < 17 OR SCORE_GEO < 17) : score < 17) \
      and iteration ≤ MAX_ITERATIONS:
    re-dispatch the audit subagent with iteration context (see prompt below)
    re-parse score(s) from the updated audit file
    if no scores improved AND no files changed → break (no progress)
    iteration += 1
```

### Re-dispatch prompt template (SEO + GEO loop)

Send to `general-purpose` subagent:

> Read `~/.claude/skills/seo/SKILL.md` and re-run it on this project.
> Previous scores:
> - **SEO classique: `<SCORE_SEO_PREVIOUS>`/20** (threshold 17/20 — `<PASS|FAIL>`)
> - **GEO (IA): `<SCORE_GEO_PREVIOUS>`/20** (threshold 17/20 — `<PASS|FAIL>`)
>
> Iteration `<N>` of `<MAX_ITERATIONS>`. Both axes are gated independently;
> the orchestrator continues to loop while EITHER score is below 17/20.
>
> Read `.claude/audits/SEO.md` for the current issue list. Apply ALL safe
> autonomous fixes (do not skip "easy" ones). Prioritize fixes for the
> axis currently below threshold:
> - SEO classique fixes: meta tags, headings, canonical, sitemap.xml,
>   alt attrs, internal linking, Core Web Vitals hints.
> - GEO (IA) fixes: llms.txt / llms-full.txt, robots.txt entries for AI
>   crawlers (GPTBot, ClaudeBot, PerplexityBot, etc.), Schema.org for AI
>   extraction (QAPage, Speakable, Person+Article, HowTo, Organization
>   graph), entity SEO (sameAs, @id), TL;DR / definition-lead content
>   shape, citable stats markup, freshness signals.
>
> For each fix applied, append a line to `.claude/audits/SEO-FIX-LOG.md`
> (format: `iter<N>: [SEO|GEO] <issue> → <file:line> — <action>`). Update
> `.claude/audits/SEO.md` with the new scores — both labeled lines MUST
> be present: `Score SEO (classique) : X.X / 20` and
> `Score GEO (IA) : X.X / 20`, plus the weighted global. Do NOT ask the
> user; apply or skip with one-line justification in the fix log.

### Re-dispatch prompt template (HARDEN loop)

Send to `general-purpose` subagent:

> Read `~/.claude/skills/harden/SKILL.md` and re-run it. Previous score:
> **`<SCORE_HARDEN_PREVIOUS>`/20** — below threshold. Iteration `<N>` of
> `<MAX_ITERATIONS>`. Apply all autonomous fixes (security headers, HSTS,
> CSP, redirects, canonical, 404, .htaccess/nginx/vercel/netlify config).
> Append entries to `.claude/audits/HARDEN-FIX-LOG.md`. Update
> `.claude/audits/HARDEN.md` with new score.

### Re-dispatch prompt template (CSO loop — non-web only)

Send to `general-purpose` subagent:

> Read `~/.claude/skills/cso/SKILL.md` and re-run it in **daily mode**.
> Previous score: **`<SCORE_CSO_PREVIOUS>`/20** — below threshold.
> Iteration `<N>` of `<MAX_ITERATIONS>`. Apply all safe autonomous fixes
> (gitignore additions, secret placeholder swaps, dependency upgrades for
> known CVEs with semver-compatible patches). Append entries to
> `.claude/audits/CSO-FIX-LOG.md`. Update `.claude/audits/CSO.md` with
> new score.

### Parallelism

For web projects, the two loops run in parallel: dispatch SEO iteration
`N` AND HARDEN iteration `N` in a single message with two `Agent` calls,
wait for both, re-parse both scores, decide whether each loop continues,
then dispatch iteration `N+1` for the audits still below threshold (in
another single message). Stop when both reach ≥17/20 or both hit cap.

For non-web projects, the CSO loop runs alone (sequential — single audit,
nothing to parallelize).

### No-progress guard

Track `score_history[audit] = [iteration → score]`. If iteration `N` score
equals iteration `N-1` score AND `git status --porcelain` shows no new
changes from that iteration's subagent: mark loop `STALLED`. Break.

### Escalation on cap or stall

If any loop ends with score < 17/20:

```
AskUserQuestion:
  "<AUDIT> stuck at <score>/20 after <iterations> iterations. Below
   threshold of 17/20. Remaining issues require judgment or external
   action. What now?"
  - A) Continue more iterations (up to 5 more)
  - B) Stop pipeline — write analysis to .claude/audits/HANDOVER-ROADMAP.md
       and exit (no client doc)
  - C) Override threshold for this audit and continue pipeline
       (will be marked as caveat in client doc)
```

For the SEO + GEO loop (single subagent, two gated scores), label the
prompt with **both** axis scores when one or both are below threshold,
e.g. `"SEO+GEO loop stuck — SEO classique 17.2/20 ✅, GEO (IA)
14.5/20 ❌ — after 5 iterations. ..."`. Option C overrides only the
axis the user names (SEO, GEO, or both) — record per-axis overrides
in `.claude/audits/THRESHOLD-OVERRIDE.md`.

Per user instructions (radical honesty, no temp fixes), **default
recommendation is B**. Only choose C with explicit user consent.

After loops finish (success, stall, or override), capture:
- Web: `SCORE_SEO_AFTER`, `SCORE_GEO_AFTER`, `SCORE_HARDEN_AFTER`
  - `SCORE_SEO_AFTER=$(extract_score_labeled .claude/audits/SEO.md "Score SEO" yes)`
  - `SCORE_GEO_AFTER=$(extract_score_labeled .claude/audits/SEO.md "Score GEO" no)`
  - `SCORE_HARDEN_AFTER=$(extract_score .claude/audits/HARDEN.md)`
- Non-web: `SCORE_CSO_AFTER`

---

## STEP 5 — COMMIT + PUSH (only if files changed)

```bash
CHANGED_DURING_PIPELINE=$(git diff --name-only "$PIPELINE_BASE_SHA"..HEAD)
PENDING_CHANGES=$(git status --porcelain)
```

If both empty → skip to STEP 6.

If `PENDING_CHANGES` non-empty → invoke /commit-change skill via subagent:

> Dispatch `general-purpose` subagent. Prompt:
>
> "Read `~/.claude/skills/commit-change/SKILL.md` and execute. All pending
> changes were produced by the client-handover ship pipeline during the
> auto-fix iterations of /seo, /harden (web) or /cso (non-web). Group into
> atomic logical commits (e.g., separate SEO meta-tag commit from harden
> security-headers commit; separate dep-upgrade commit from gitignore
> commit). Use Conventional Commits format. After committing, return the
> SHA list."

Then push:

```bash
CURRENT_BRANCH=$(git branch --show-current)
git push origin "$CURRENT_BRANCH" 2>&1
```

If push fails (no remote, auth issue, conflict): capture error, report to
user via AskUserQuestion:

```
"Push failed: <error>. Pipeline needs the changes published before deploy.
Options:
- A) Retry push (after I fix it manually)
- B) Skip push — I'll publish manually before confirming deploy
- C) Abort pipeline"
```

---

## STEP 6 — DEPLOY PAUSE

Skip if `PROJECT_TYPE != web` (non-web has no deploy-then-validate flow —
set `VALIDATE_SKIPPED=true` and jump to STEP 8).

Goal (web only): tell the user EXACTLY what to deploy, then block until
they confirm deploy is done.

### Build the deploy brief

```
DEPLOYED_URL: <auto-detected or "[À CONFIRMER]">
PROJECT_TYPE: <type>
DEPLOY_HINTS: <list from STEP 2>

Files changed during this pipeline session (since PIPELINE_BASE_SHA):
  <git diff --name-only PIPELINE_BASE_SHA..HEAD>

Commits added in this session:
  <git log --oneline PIPELINE_BASE_SHA..HEAD>
```

### Phrase the brief in plain words for the user

Tailor to project deploy method (use DEPLOY_HINTS):

- **Vercel/Netlify/Cloudflare Pages auto-deploy from git**: "Push has been
  done. The platform deploys automatically — usually 1-3 min. Watch the
  dashboard. Tell me when the new version is live."
- **GitHub Actions / GitLab CI**: "Workflow `<file>` should run on push.
  Watch CI status. Tell me when it's green and live."
- **Manual upload (FTP / SSH)**: "Upload these files to the server: `<list>`.
  If using rsync, here's a template: `rsync -avz dist/ user@server:/path`."
- **Docker / Fly.io / Render**: "Run `<deploy command>` and wait for the
  build to complete."
- **No deploy detected**: ask user how they deploy, then guide.

### Block on confirmation

```
AskUserQuestion:
  "Pipeline paused for deploy. Above is what's changed and how to deploy.
   Confirm when the live site reflects the new changes (or skip /web-validate)."

  Header: "Deploy status"
  Options:
  - A) Deployed — proceed with /web-validate
  - B) Not yet — I'll come back (this stops the pipeline; re-run /client-handover later)
  - C) Skip /web-validate — proceed to handover doc with VALIDATE marked SKIPPED
```

If A → proceed to STEP 7. If B → exit cleanly with state report. If C →
mark `VALIDATE_SKIPPED=true` and jump to STEP 8.

If `DEPLOYED_URL` is still `[À CONFIRMER]` after option A: AskUserQuestion
"Quelle est l'URL du site déployé pour /web-validate ?" — capture URL.

---

## STEP 7 — RUN /web-validate (live site)

Skip if `VALIDATE_SKIPPED=true` or `PROJECT_TYPE != web` (in either case
ensure `VALIDATE_SKIPPED=true` is set so the gate logic in STEP 8 treats
VALIDATE as not-applicable rather than failed).

Dispatch `general-purpose` subagent:

> Read `~/.claude/skills/web-validate/SKILL.md` and execute against the
> deployed URL: `<DEPLOYED_URL>`. Audit W3C HTML validity (validator.nu),
> W3C CSS validity (jigsaw.w3.org), WCAG 2.1 a11y (axe-core, pa11y).
> Apply autonomous fixes ONLY in source code (the client controls deploy);
> document remaining issues. Write report to `.claude/audits/VALIDATE.md`
> with `Score: X/20` (or `X/100`) at the top.

Wait for completion. Parse:

```bash
SCORE_VALIDATE_AFTER=$(extract_score .claude/audits/VALIDATE.md)
```

Note: VALIDATE has no `_BEFORE` (first run is post-deploy). The before/after
table for VALIDATE shows `—` for before, `<score>` for after.

If /web-validate produced new fixes in source code, run STEP 5 again (mini-commit
+ push) BEFORE moving to STEP 8 — but DO NOT loop /web-validate. The remaining
deploy of those fixes is mentioned to the user in the final doc.

---

## STEP 8 — GATE EVALUATION

Compute final score table.

**Web project:**

| Audit             | Before                    | After                       | Status            |
|-------------------|---------------------------|-----------------------------|-------------------|
| SEO (classique)   | `SCORE_SEO_BEFORE`/20     | `SCORE_SEO_AFTER`/20        | ✅ ≥17 / ❌ <17    |
| GEO (IA)          | `SCORE_GEO_BEFORE`/20     | `SCORE_GEO_AFTER`/20        | ✅ ≥17 / ❌ <17    |
| HARDEN            | `SCORE_HARDEN_BEFORE`/20  | `SCORE_HARDEN_AFTER`/20     | ✅ ≥17 / ❌ <17    |
| VALIDATE          | —                         | `SCORE_VALIDATE_AFTER`/20   | ✅ / ❌ / SKIPPED   |

SEO classique and GEO (IA) are gated independently — both must reach
≥17/20. Reaching the GEO threshold is harder than SEO classique on
many sites because AI-extraction signals (llms.txt, Speakable, QAPage,
entity SEO) are still emerging — expect more fix-loop iterations on
GEO than on SEO.

**Non-web project:**

| Audit    | Before                    | After                  | Status         |
|----------|---------------------------|------------------------|----------------|
| CSO      | `SCORE_CSO_BEFORE`/20     | `SCORE_CSO_AFTER`/20   | ✅ ≥17 / ❌ <17 |

### Gate rule

Web: `ALL_PASS = (SEO_AFTER ≥ 17/20) AND (GEO_AFTER ≥ 17/20) AND (HARDEN_AFTER ≥ 17/20) AND (VALIDATE_AFTER ≥ 17/20 OR VALIDATE_SKIPPED)`

Non-web: `ALL_PASS = (CSO_AFTER ≥ 17/20)`

**GEO gate note**: `SCORE_GEO_AFTER = "UNKNOWN"` is treated as **fail** —
this typically happens when the SEO subagent produced a legacy single-score
SEO.md without the labeled `Score GEO (IA)` line. The orchestrator
re-dispatches the SEO subagent with an explicit instruction to emit both
labeled lines (see "Threshold strictness" below).

### Threshold strictness

Use the raw normalized score. **No rounding.** 16.9/20 fails. 17.0/20 passes.
A score reported as `UNKNOWN` (no parseable score line in the audit
file) is treated as **fail** — re-dispatch the audit subagent with an
explicit instruction to add the score lines and re-run the audit.
Do not assume a passing score.

For `.claude/audits/SEO.md` specifically, the re-dispatch must demand
**both** labeled lines:
- `Score SEO (classique) : X.X / 20`
- `Score GEO (IA) : X.X / 20`

A single generic `Score: X/20` line is insufficient — the gate will
still mark `SCORE_GEO_AFTER = UNKNOWN` and fail.

For `.claude/audits/HARDEN.md` and `.claude/audits/CSO.md`, a single
`Score: X/20` (or `X/100`) at the top of the report is sufficient.

### Override transparency

If the user chose option C (override threshold) at any STEP 4 escalation,
write `.claude/audits/THRESHOLD-OVERRIDE.md` documenting:
- Which audit(s) were overridden — for the SEO+GEO loop, list the axes
  separately (e.g. `SEO classique: NOT overridden, GEO (IA): overridden`)
- Final score reached vs threshold
- Top 3 unresolved issues per axis
- User's stated reason

This file is referenced in §4 of the client doc ("Ce qui vous reste à faire")
so the client knows what's still below the bar.

If `ALL_PASS = false`:

1. Generate `.claude/audits/HANDOVER-ROADMAP.md` (analysis of what's
   blocking each below-threshold audit — see structure below).
2. Append checklist entries to `.claude/tasks/TODO.md`.
3. **Do NOT generate the client doc**. Report to the user:

```
PIPELINE STOPPED — gate failed.

Score table:
<the table above>

Below-threshold audits:
- SEO (classique): <score>/20 — <top 3 remaining issues, one-line each>
- GEO (IA): <score>/20 — <top 3 remaining issues, one-line each>
- HARDEN: <score>/20 — <top 3 remaining issues>
- VALIDATE: <score>/20 — <top 3 remaining issues>

Roadmap written to .claude/audits/HANDOVER-ROADMAP.md.
Tasks appended to .claude/tasks/TODO.md.

Resolve P0 items, then re-run /client-handover.
```

If `ALL_PASS = true` → proceed to STEP 9 (memory load + doc generation).

### Roadmap structure (when gate fails)

```markdown
# Handover Roadmap — <project name>

Generated: YYYY-MM-DD HH:MM
Trigger: per-audit threshold violated (rule: every audit must be ≥17/20)

## Score breakdown

| Audit             | Before | After | Δ   | Status            |
|-------------------|--------|-------|-----|-------------------|
| SEO (classique)   | 14.4   | 16.2  | +1.8| ❌ BELOW_THRESHOLD |
| GEO (IA)          | 11.0   | 13.5  | +2.5| ❌ BELOW_THRESHOLD |
| HARDEN            | 12.0   | 18.0  | +6.0| ✅ OK              |
| VALIDATE          | —      | 15.5  | —   | ❌ BELOW_THRESHOLD |

## Remaining issues per audit

### SEO classique (<score>/20)

[Extract from `.claude/audits/SEO.md` — the SEO classical issues NOT
auto-fixed. Sort by score-gain potential. For each:]

1. [TYPE] short title
   - File: `path:line`
   - Fix: <one sentence>
   - Score gain: +X.X/20
   - Why automatic fix didn't work: <reason — needs judgment, external account, manual content>

### GEO / IA (<score>/20)

[Extract from `.claude/audits/SEO.md` (GEO sections — §7.x) — the GEO
issues NOT auto-fixed. Same per-item format as SEO above. GEO is
gated independently at ≥17/20; below-threshold GEO blocks the handover
just like SEO classique. Common GEO blockers: missing llms.txt /
llms-full.txt, AI crawler robots.txt rules absent, no Schema.org for
AI extraction (QAPage, Speakable, HowTo, Organization graph), no
entity links (sameAs, Wikidata @id), content shape unsuited for LLM
extraction (no TL;DR, no definition lead, no Q→A blocks).]

### HARDEN (<score>/20)
... (same format)

### VALIDATE (<score>/20)
... (same format)

## Action plan

P0 (do first — bring scores ≥17/20):
- [ ] [SEO][...] ...
- [ ] [HARDEN][...] ...

P1 (after threshold passed):
- [ ] ...

P2 (manual / requires user input):
- [ ] ...

## How to use

1. Tackle P0 with dev team.
2. Re-run /client-handover — pipeline restarts from baseline audits.
3. P2 items go to client (will appear in handover doc once gate passes).
```

---

## STEP 9 — LOAD MEMORY REGISTRIES

(Only reached when STEP 8 gate passes.)

```bash
MEMORY_DIR=".claude/memory"
test -d "$MEMORY_DIR" || MEMORY_DIR=""
```

If memory dir exists, read each file (full contents, parse manually):

- `decisions.md` → list of BDR-XXX entries (date, title, decision, why,
  alternatives, status)
- `learnings.md` → LRN-XXX entries
- `blockers.md` → BLK-XXX entries (open vs resolved)
- `journal.md` → date headings + 3-5 line session summaries
- `evals.md` → EVAL-XXX entries

If memory dir missing or empty, proceed using only git data — flag in
final report that memory was unavailable.

---

## STEP 10 — GIT HISTORY SUMMARY

```bash
git log --reverse --format='%h|%aI|%an|%s' | head -200
git log --name-only --format='---COMMIT---' | grep -v '^---' | sort -u | head -50

git log --diff-filter=A --name-only --format='' | sort -u | wc -l   # added
git log --diff-filter=M --name-only --format='' | sort -u | wc -l   # modified
git log --diff-filter=D --name-only --format='' | sort -u | wc -l   # deleted

git tag --sort=-creatordate | head -5
```

For projects with 200+ commits, use a sub-agent to cluster commits into
phases (delegate via `Agent` tool with `subagent_type: "Explore"` or
`general-purpose`):

> "Read `git log --reverse --format='%h|%aI|%s'` for this repo (full
> output). Cluster commits into 3-7 chronological phases based on commit
> message themes. For each phase: name, commit count, 2-line summary.
> Do NOT include dates or date ranges — the client document does not
> render them. Output JSON."

For smaller projects, do it inline.

---

## STEP 11 — ASK USER QUESTIONS

### Q1 — Deploy chapter (default = SKIP)

**Default behavior**: deploy chapter is **NOT included**. Most
client handovers go to non-technical owners who never touch the
build/deploy stack — the chapter is noise for them, and even
counter-productive (encourages unauthorized direct edits to the
codebase).

Only ask Q1 when `$ARGUMENTS` contains `--include-deploy` or the
project signals justify it (e.g., `CLAUDE.md` explicitly mentions
"client autonome", "self-hosted by client", "no dev maintenance",
or the project README documents a hand-off intent). Even then,
re-confirm before including.

**No flag, no signal → skip silently** (do not even ask).

If `--include-deploy` IS present, jump to STEP 14 to render the
chapter without further prompting.

If user explicitly asks via Q1 (only when signals justify):

```
Re-grounding: project = <name>, branch = <current>, all audits passed
(web: SEO classique <score>/20, GEO IA <score>/20, HARDEN <score>/20,
VALIDATE <score>/20 | non-web: CSO <score>/20). Generating client
handover document.

Le client va recevoir un document qui explique ce qui a été fait. Tu veux
qu'on ajoute aussi un chapitre qui lui explique comment construire et
déployer le site lui-même (build, mise en ligne, mise à jour) ? Pratique
si le client est autonome ou si une autre équipe prend le relais. À éviter
si tu déploies pour lui.

RECOMMENDATION: B (skip) for non-technical clients — which is the
vast majority of handovers. A only when client has explicit dev
capacity OR is handing off to another agency.

Options:
- A) Yes — include build & deploy chapter
- B) No — skip the deploy chapter (default, recommended for non-tech clients)
```

(Translate to English if `LANG=en`.)

### Q2 — Output language confirmation (only if auto-detection was ambiguous)

Skip if confident. Only ask if ambiguous.

### Q3 — Web project: SEO/GEO manual chapter

Included by default. Do NOT ask. Mention in final summary.

If `IS_LOCAL_BUSINESS=true`, the chapter goes deeper on local listings.
If false, the chapter focuses on general directory + AI search.

---

## STEP 12 — SYNTHESIZE THE DOCUMENT

Generate the deliverable as a tight 4-chapter structure: what was needed,
what was done (lay summary), what the client must do, then technical
details for the curious. Translate headings to `LANG`. Tone: friendly,
concrete, no jargon. One short paragraph per idea.

### Hard rules for this document

0. **All section cross-references MUST be clickable markdown links.**
   Whenever the doc body mentions a section by number (`§5.1`, `§6`,
   `§6.2`, etc.), write it as a markdown link to the heading anchor:

   ```
   [§5.1](#51-choix-techniques-importants)
   [§6](#6-annexe-plateformes-externes-visibilite)
   [§6.2](#62-plateformes-prioritaires-semaine-1)
   ```

   The renderer (`scripts/handover-to-pdf.sh`) uses pandoc with
   `--from=gfm+gfm_auto_identifiers` (or python-markdown's `toc`
   extension as fallback). Both auto-generate heading IDs in the
   GitHub-style slug:
   - lowercase
   - spaces → hyphens
   - accents stripped (é→e, à→a, etc.)
   - punctuation removed (`.`, `(`, `)`, `,`, `:`, `?`, `!`,
     apostrophes)
   - example: `### 6.2 Plateformes prioritaires (Semaine 1)` →
     `id="62-plateformes-prioritaires-semaine-1"`

   After writing the doc, **verify links resolve**:

   ```bash
   # Extract all anchor refs and all heading IDs, then check refs
   # against IDs (set difference should be empty).
   grep -oE '\]\(#[a-z0-9-]+\)' "$OUTPUT_MD" | tr -d ']()#' | sort -u > /tmp/refs.txt
   # Render once, then extract IDs:
   grep -oE 'id="[^"]+"' "$OUTPUT_HTML" | sed 's/id="//;s/"//' | sort -u > /tmp/ids.txt
   comm -23 /tmp/refs.txt /tmp/ids.txt
   # expected: empty. Each line printed = a broken anchor — fix.
   ```

   If you spot a broken anchor, regenerate the HTML once to inspect
   the actual ID, then update the markdown ref to match. The TOC
   line at the top of the doc and any "voir §N" cross-references
   in §3 / §4 / §5 / §6.x sub-tables / §6.9 calendar must all
   use the linked form.

1. **Never name internal tools or skill identifiers in chapters 1–3.**
   Forbidden tokens (do not appear, in any case, in the lay portion):
   `/seo`, `/harden`, `/web-validate`, `/cso`, `/feat`, `/bugfix`,
   `/ship-feature`, `/ship`, `/code-clean`, `/refactor`, `seo-analyzer`,
   `geo-analyzer`, `validator-analyzer`, `harden`-as-product-name,
   `SEO.md`, `HARDEN.md`, `VALIDATE.md`, `CSO.md`, `MAX_ITERATIONS`,
   `ALL_PASS`, `SCORE_*`. Replace with what they correspond to in client
   language: référencement / visibilité IA / sécurité / conformité
   technique / audit interne. Internal tool names may appear ONLY in
   chapter 4 ("Détails techniques") inside the optional glossary.
2. **Chapter 2 hard cap: 300 words max, zero technical jargon.** Plain
   French (or plain English if `LANG=en`). No acronyms not already in
   common usage (HTTPS is fine; CSP is not). Run `wc -w` against the
   chapter body; if over 300, rewrite shorter.
3. **Chapter 3 is action-only.** Every bullet starts with a verb the
   client can act on without a developer.
4. **Chapter 4 may use technical terms** (SEO, GEO, HSTS, CSP, etc.) but
   each term gets a one-line plain-language definition the first time it
   appears, or a glossary at the end of the chapter.

### Document structure

```
# [Project name] — Compte rendu de livraison
## (or: HANDOVER — Project Recap)

> Document préparé le YYYY-MM-DD à l'attention de [client name if known].
> Ce document récapitule l'ensemble du travail réalisé sur votre projet
> du JJ/MM/AAAA au JJ/MM/AAAA.

## 1. Ce qu'il fallait faire (et pourquoi)

[Briefing + motivation. 100–180 words max. Two short paragraphs.
- §1.1 (the brief): what the client wanted, in their own words if
  possible. Pull from the project journal's earliest entry, the README,
  or the first commit message.
- §1.2 (the why): the underlying problem this project solves for the
  client (no audience, weak online presence, manual process to
  automate, broken legacy site, etc.). Concrete. Their reality, not
  ours.

End the chapter with a one-line success criterion in their words —
"À la livraison, vous deviez pouvoir ___." If unknown, omit rather
than invent.]

## 2. Résultats — état de santé du site (avant / après)

[Score table at the top, BEFORE the lay summary. Plain French
column labels — no internal tool names. Numbers OK (the whole
purpose of this chapter is the numbers). Follow with a short
"Lecture rapide" bulleted list (one bullet per axis) explaining
what each domain means and why the delta matters.

| Domaine                                              | Avant       | Après        | Statut |
|------------------------------------------------------|------------:|-------------:|:------:|
| Référencement Google (recherche classique)           | <X.X>/20    | <Y.Y>/20     | OK     |
| Visibilité IA (ChatGPT, Perplexity, Gemini, Claude) | <X.X>/20    | <Y.Y>/20     | OK     |
| Sécurité du site (chiffrement, en-têtes, redirects) | <X.X>/20    | <Y.Y>/20     | OK     |
| Conformité technique (HTML, CSS, accessibilité)      | —           | <Z.Z>/20     | OK     |

(LANG=en column labels: "Domain" / "Before" / "After" / "Status".
Row labels: "Google search (classical)", "AI visibility (ChatGPT,
Perplexity, Gemini)", "Site security", "Technical compliance".)

Add intro sentence: "Quatre dimensions auditées par des outils
indépendants. Toutes au-dessus du seuil 17/20 fixé pour livrer."

Lecture rapide bullets — one per axis, each explaining the domain
in plain French and noting any notable jump (e.g., "Le score est
passé de quasi-nul à très haut grâce à ..."). Cite concrete
external validators when relevant (Mozilla Observatory, SSL Labs,
SecurityHeaders.com — these are recognized seals).

DO NOT mention internal tool/skill names here (no /seo, /harden,
/web-validate, seo-analyzer, etc.). The lecture rapide IS where
client-facing axis names live.]

## 3. Ce qui a été fait

[**HARD CAP: 300 words. ZERO technical jargon.** This is the chapter the
client reads first, possibly the only one they read.

Structure as a single short narrative + a tight bullet list of
user-visible benefits:

  Para 1 (3–5 sentences): the project today, in their words. What it
  looks like to a visitor, what the client can do with it. NOT what
  technologies were used.

  Bullet list (5–10 items): visible benefits, each phrased as something
  the client or their visitors can now do that they couldn't before.
  Pattern: "Vos visiteurs peuvent ___" / "Vous pouvez ___" /
  "Le site est maintenant ___".

Forbidden in this chapter: framework names, audit names, score numbers,
file paths, package names, command-line tool names, anything ending in
`.md`, `.json`, `.yaml`. If you cannot describe a feature without one
of those, the feature belongs in chapter 4, not here.

After drafting, count words. Cap at 300. If over, cut paragraphs not
bullets — bullets are the value-dense part.]

## 4. Vos informations officielles à utiliser partout (NAP)

[**Position before §5 todo is REQUIRED**, not cosmetic. Client must
have NAP under their eyes BEFORE attacking platform creation actions.
Prose intro must start with "À lire avant d'attaquer le [§5](#5-...)"
and cross-reference §5 explicitly.

Table content (FR variant — translate cells to EN if `LANG=en`,
keep column structure identical):

| Champ                  | Valeur officielle à utiliser partout                       |
|------------------------|------------------------------------------------------------|
| Nom commercial         | [from CLAUDE.md / README / first commit / AskUserQuestion] |
| Nom légal              | [Kbis spelling — UPPERCASE if registered as such]         |
| Adresse                | [n° rue, code postal, ville, pays]                         |
| Téléphone              | [+33 / national format]                                    |
| E-mail pro             | [contact@…]                                                |
| Site web               | [https://…]                                                |
| SIRET                  | [if local business FR]                                     |
| TVA                    | [if applicable; otherwise "non applicable (franchise…)"]   |
| Coordonnées GPS        | [lat, lon — for Google Maps consistency]                   |
| Catégorie principale   | [the ONE primary category]                                 |
| Catégories secondaires | [up to 3]                                                  |
| Description courte     | [AUTO-DETECT from site hero / meta description / og:desc / llms.txt / JSON-LD LocalBusiness.description — see STEP 13 detection order] |
| Horaires               | [per-day, with seasonal note if applicable]                |

End with two callouts:

> **Conseil pratique** : enregistrer ce tableau en note dans votre
> téléphone. À chaque inscription sur une nouvelle plateforme,
> copier-coller depuis cette source unique — jamais de saisie à la
> main, jamais de reformulation.

> **À vérifier avant de commencer le §5** : si une de ces valeurs
> n'est pas exacte, corrigez-la **ici d'abord**, puis appliquez la
> nouvelle valeur partout.

Auto-detection rules: pull values from CLAUDE.md, .claude/memory/
journal/decisions, README.md, first commits, and the live site. If a
value cannot be confirmed, leave `[À COMPLÉTER]` and warn in final
report. Do NOT invent SIRET, GPS, or legal name — those are too risky
to fake.]

## 5. Ce qui vous reste à faire

[Action-only checklist for the client. Pull from: open `blockers.md`
entries, ongoing-monitoring items, external platforms to claim,
content updates only the client can make, deploy steps if self-hosted.

Format as a checklist grouped by cadence. Every line starts with a
verb. Every line is something the client can do without a developer.

### Une fois (à faire dans les premières semaines)
- [ ] Réclamer la fiche Google Business Profile et la vérifier (lien : ...)
- [ ] Compléter le profil Apple Business Connect (lien : ...)
- [ ] Vérifier la cohérence Nom / Adresse / Téléphone sur toutes les
      plateformes — voir l'annexe à la fin du document
- [ ] [Si vous gérez l'hébergement vous-même : configurer le certificat
      de sécurité (renouvellement automatique recommandé)]
- [ ] [Si vous gérez l'hébergement vous-même : programmer une sauvegarde
      quotidienne]

**NEVER include**: "Sauvegarder ce document hors du dépôt (PDF, email)".
Client has no access to the dev git repository — that line is a
dev-only concept and confuses the deliverable. The PDF is delivered
to them directly. STEP 14.5 explicitly removes it if it ever sneaks in.

**Intro note**: add one line above the "Une fois" subheading so the
client understands the mixed-state list:

> Les cases déjà cochées correspondent à ce qui a déjà été validé.

(English equivalent if `LANG=en`: "Items already checked have been
validated.")

The actual pre-check pass runs in STEP 14.5 (after §5 + §7 are drafted,
before STEP 15 writes to disk). Do NOT pre-check items here — STEP 14.5
does it based on project signals + WebSearch + AskUserQuestion.

### Mensuel
- [ ] Ajouter ou mettre à jour 5 photos sur Google Business
- [ ] Répondre aux avis Google (positifs et négatifs) sous 48 h
- [ ] Vérifier que le site est toujours en ligne (test simple : ouvrir
      l'URL depuis un autre appareil)
- [ ] [Si système de gestion de contenu : mettre à jour les contenus
      saisonniers]

### Trimestriel
- [ ] Faire un test de visibilité IA : taper le nom du commerce dans
      ChatGPT, Perplexity, Gemini. Noter ce qui s'affiche.
- [ ] Demander à 3–5 clients de laisser un avis Google
- [ ] Publier un post Google Business (offre, événement, actualité)

### Annuel
- [ ] Mettre à jour la photo de couverture Google Business
- [ ] Vérifier que les horaires saisonniers sont bons
- [ ] Renouveler les noms de domaine

### Quand quelque chose change dans la vie du commerce
- [ ] Changement d'adresse, de téléphone ou d'horaires → modifier
      d'abord sur Google Business, puis sur toutes les autres
      plateformes (la cohérence est cruciale)

[Adapt cadences to project type. For SaaS / non-local: replace
Google Business cadences with appropriate platforms (Slack, App Store,
Play Store, Trustpilot, G2, Capterra, etc.). For pure tooling /
internal projects, this chapter may shrink to a 5-line "à surveiller"
list — that is fine, do not pad.]

## 6. Détails techniques (pour les curieux)

[Same content as before but consolidated and labelled as the
technical-depth chapter. Internal tool names may appear here.
The client is not required to read this chapter. The score table
is NOT here — promoted to §2 for impact. Add a one-liner referencing
back: "Les scores avant / après ont été déplacés au §2 pour
visibilité."]

### 6.1 Choix techniques importants

[Vulgarize 3–7 BDR entries. Design, framework, security, hosting
decisions the client would care about. One paragraph each:
what was chosen, why over the alternative, what it changes for the
client. Drop entries the client cannot act on or care about.]

### 6.2 Comment on en est arrivé là (phases)

[3–7 phases. For each: what was done, why it mattered, in technical
detail this time. Reference commit clusters from STEP 10. Plain phase
names, not skill names.

**Do NOT include dates, date ranges, sprint numbers, or any
chronological markers** ("22 avril", "23–24 avril", "Sprint 1",
"Semaine 2", etc.). Phases are themes, not a timeline. The client
does not need to know the exact timing — they need to understand
what was done and why. Lead each bullet with the phase name in bold,
followed by what was done. Forbidden tokens before write:
`\b\d{1,2}\s+(janvier|février|mars|avril|mai|juin|juillet|août|septembre|octobre|novembre|décembre)\b`,
`\bsprint\s+\d+\b`, `\bsemaine\s+\d+\b`.]

Example — correct format (no dates):
> - **Audit + conformité légale.** Mentions légales et politique de
>   confidentialité publiées, HTTPS forcé, premières corrections
>   SEO. Risque RGPD jusqu'à 20 M€ neutralisé.
> - **Refonte technique.** Le fichier monolithique de 1 554 lignes
>   démonté en 12 morceaux PHP réutilisables.

Wrong — has date prefix:
> - **22 avril — Audit + conformité légale.** ...

### 6.3 Glossaire (optionnel)

[Include only if at least 4 of the terms below appear in chapter 4.
Format: term — one-line plain-language definition. Sort alphabetically.
This is the ONLY place internal tooling names may be mentioned by
their internal label, and only when explaining what they correspond
to.]

- **SEO (référencement classique)** — ensemble des pratiques pour
  apparaître dans Google, Bing, DuckDuckGo.
- **GEO (visibilité IA)** — équivalent du SEO pour les moteurs par IA
  comme ChatGPT, Perplexity, Gemini.
- **HSTS** — en-tête HTTP qui force la navigation en HTTPS.
- **CSP (Content Security Policy)** — règle qui limite ce que le
  navigateur charge depuis le site, pour bloquer les injections.
- **WCAG** — standard d'accessibilité (AA = niveau recommandé).
- **Schema.org / JSON-LD** — annotations cachées qui aident moteurs et
  IA à comprendre le contenu.
- **llms.txt** — fichier qui dit aux moteurs IA quel est le contenu
  important du site.

## 7. Annexe — Plateformes externes (web)

[NAP table is NOT here — promoted to §4. This annex starts directly
with the platform sub-sections (§7.1 Plateformes prioritaires, §7.2
Réseaux sociaux, etc.). Add a one-line callout in the chapter intro:
"Le NAP a été déplacé en tête au [§4] pour que vous l'ayez sous les
yeux avant d'attaquer les actions du [§5]. Référez-vous-y à chaque
inscription — c'est la source de vérité unique."]

## 8. Annexe — Build & déploiement (optionnel)

---

*Document généré automatiquement à partir de l'historique du projet et
des audits de santé. Pour toute question, contactez [contact].*
```

### Tone rules

1. Address the client directly ("votre site", "vous pouvez").
2. Chapters 1–3: replace every tech term with a user-facing equivalent.
3. No abbreviations the client wouldn't use (HTTPS yes, CSP no — unless
   in chapter 4 with definition).
4. Concrete numbers > adjectives.
5. Short paragraphs. Bullet lists for things you can count.
6. **Score deltas explained in plain words**. Never just dump numbers.
7. **Chapter 3 is action-oriented**. Every line starts with a verb.
   Every line is something the client can do without a developer.
8. **No skill-name leaks in chapters 1–3.** See "Hard rules" above.

---

## STEP 13 — SEO/GEO MANUAL CHECKLIST (web projects only)

If `PROJECT_TYPE=web` AND `--skip-seo` NOT set, append this chapter
as **§6 Annexe — Plateformes externes** in the 5-chapter structure
(see STEP 12). Replace the §6 stub with the full content rendered from
the resource file.

Read the resource file:
`$HOME/.claude/skills/client-handover/checklists/seo-geo-manual.md`

That file contains the canonical platform list with registration URLs in
both FR and EN. Use the section matching `LANG` and `IS_LOCAL_BUSINESS`.

If the file is unreachable, fall back to the inline platform list at the
bottom of this agent.

The chapter must include:

1. **Pourquoi c'est important** (1 paragraph). Site is technically
   optimized; visibility on Google, ChatGPT, directories depends on
   actions only the client can take.

2. **NAP consistency** — **NOTE**: the NAP table itself is NOT
   rendered here in §7. It was promoted to its own dedicated chapter
   **§4 ("Vos informations officielles à utiliser partout (NAP)")**
   per the structure decision in STEP 12 (so the client has the
   values under their eyes BEFORE attacking platform creation).

   In this §7 annex chapter, just emit a one-line callout pointing
   back to §4:

   > Le NAP a été déplacé en tête au [§4](#4-vos-informations-officielles-a-utiliser-partout-nap)
   > pour que vous l'ayez sous les yeux **avant** d'attaquer les
   > actions ci-dessous. Référez-vous-y à chaque inscription —
   > c'est la source de vérité unique.

   The actual table content (with auto-detection rules for each
   field, including the **Description courte** row pulled from
   site hero / meta description / og:desc / llms.txt / JSON-LD
   LocalBusiness.description) is defined in the §4 template at
   STEP 12. Do NOT duplicate the table here.

3. **Platform checklist** (priority-ordered table per `IS_LOCAL_BUSINESS`).
   Each row: Plateforme | Pourquoi | Lien d'inscription | Action | Statut.

4. **AI search visibility (GEO)**. Plain explanation + actions: Wikidata,
   Knowledge Panel, llms.txt, periodic re-audit.

5. **Reviews & reputation**.

6. **Photos & content**.

7. **Schedule** (Semaine 1 / Mois 1 / Mois 3 / Trimestriel).

8. **Outils gratuits pour vérifier votre présence**.

Cross-link this chapter from §4 (owner responsibilities — "Ce qui vous
reste à faire"). Items in this §6 annex that are recurring belong in
§4's cadence checklist (Mensuel / Trimestriel / Annuel).

---

## STEP 14 — BUILD & DEPLOY CHAPTER (only if Q1=Yes)

If included, this becomes **§7 Annexe — Build & déploiement** in the
5-chapter structure (see STEP 12). For each `DEPLOY_HINTS` match,
generate a short subsection:
1. What this means (1 paragraph).
2. First-time setup (numbered steps + signup link).
3. Day-to-day deploy (typical command / click sequence).
4. How to know it worked (where to check URL, where to find logs).
5. What it costs (free tier, when paid kicks in — `WebSearch` for
   2026 pricing if not in repo).
6. Who to call when it breaks (status page, support link).

If no deploy hints, offer 2-3 standard options:
- Static site → Netlify / Vercel / Cloudflare Pages
- Webapp → Fly.io / Render / Vercel / Railway
- CLI / library → npm / PyPI / crates.io / Homebrew

For each: signup + 5-step deploy walkthrough.

---

## STEP 14.5 — PRE-CHECK COMPLETED ITEMS (web/local-business)

Skip if `PROJECT_TYPE != web`. Runs AFTER STEP 12 + STEP 13 (in-memory
body drafted), BEFORE STEP 15 (write).

**Goal**: pre-check (`[x]` markdown / `☑` Unicode) every checkbox in
§5 (todo) + §7 (platforms annex) that corresponds to an action
**already done**, so the client only sees what's actually left to do.

### Scope

**INCLUDE** (auto-pre-check candidates):
- §5 "Une fois — à faire dans..." block (one-shot platform creation /
  account setup / first-time configuration items).
- §7.1 / §7.2 / §7.3 / §7.4 / §7.5 — top-level "Fiche créée" /
  "Compte créé" / "Page créée" rows.

**EXCLUDE** (always leave unchecked):
- §5 "Mensuel", "Trimestriel", "Annuel", "Quand quelque chose change"
  cadences (recurring, never "done").
- §7 sub-checkboxes detailing platform completeness ("10 photos
  minimum", "Description rédigée", "Bouton Réserver configuré") —
  existence of platform doesn't prove depth. Leave for client.
- Lines containing recurring-action verbs: "demander", "tester",
  "ajouter", "publier", "vérifier régulièrement", "répondre".

### Detection signals (apply in order, stop at first positive match)

For each in-scope checkbox, attempt to confirm "done" via:

1. **Project docs** — grep `CLAUDE.md`, `README.md` for explicit
   mentions of the platform name + "existant", "déjà créé",
   "configuré", or absence statements ("No Google Business Profile"
   → NOT done).
2. **`.claude/memory/` registries** — search `decisions.md`,
   `learnings.md`, `journal.md` for setup confirmation entries
   (BDR / LRN / journal date heading).
3. **Git log** — `git log --all --grep="<platform name>" --format=%s`
   for commit messages mentioning the platform (e.g., "Bing Places
   import done").
4. **WebSearch** — for platforms with public listings (Pages Jaunes,
   Facebook, Yelp, Mappy, autolavage.net, sectoral directories):

   ```
   WebSearch: "<business name>" "<city>" <platform>
   ```

   Confirm done if the search returns the actual business listing
   matching the platform's URL pattern. **Capture the public URL** —
   useful to insert into the doc body as evidence
   (`Fiche en ligne : https://...`).
5. **Unknown** — couldn't confirm via 1-4 → add to `UNKNOWNS` list.

### Batch unknowns via AskUserQuestion

Group `UNKNOWNS` into themed batches (max 4 questions, max 4 options
each, `multiSelect: true`). Suggested groupings:
- "Plateformes prioritaires" (GBP, Apple, Bing, PJ)
- "Réseaux sociaux" (FB, IG, TikTok, Yelp)
- "Cartographie + sectoriels" (Mappy, Vroomly, Foursquare, Trustpilot)
- "Annuaires généralistes" (Justacote, Hoodspot, Le Bottin, Nextdoor)

Items the user selects → mark done. Items the user does NOT select
→ stay unchecked. If `UNKNOWNS` is empty, skip (no questions asked).

### Apply pre-checks to in-memory body

For each "done" checkbox:
- §5 markdown: `- [ ]` → `- [x]`.
- §7 Unicode: `- ☐` → `- ☑`.
- Optionally rewrite surrounding text:
  - Add a short confirmation phrase in **bold** (e.g., "**Fiche
    Google Business Profile créée et vérifiée.**").
  - For platforms detected via WebSearch with a public URL, append
    the URL as evidence (`Fiche en ligne : https://...`).
  - Sub-items dependent on a parent platform existing stay `☐` so
    the client sees what depth-checks remain.

### Cleanup pass (always)

- **Remove** any line containing "Sauvegarder ce document hors du
  dépôt" — client has no repo access, dev-only concept.
- **Add intro note** to §5 (above "Une fois" subheading) if any
  item was pre-checked:

  > Les cases déjà cochées correspondent à ce qui a déjà été validé.

  (`LANG=en`: "Items already checked have been validated.")

### Verification

```bash
# At least one pre-check expected for any project with real history.
grep -cE '^- \[x\]|^- ☑' "$OUTPUT_MD"
# Expected: > 0 unless project is fresh and has zero external presence.
```

Then re-run STEP 15 word-count + skill-leak gates after these edits.

---

## STEP 15 — WRITE MARKDOWN OUTPUT

Default output path: project root.
- `LIVRAISON.md` if `LANG=fr`
- `HANDOVER.md` if `LANG=en`

If a file at that path already exists, AskUserQuestion:
- A) Overwrite (recommended if previous version is stale)
- B) Save as `LIVRAISON-YYYY-MM-DD.md` (versioned)
- C) Skip writing — display in conversation only

Write the file with the `Write` tool.

Sanity checks (do them in this order, before STEP 16):

```bash
wc -l <output>                          # expect 250-900 lines
grep -c "^## " <output>                 # expect 6-8 top-level chapters
                                        #   §1, §2, §3, §4, §5, §6, [§7 web], [§8 deploy]
```

**Chapter 3 word-count gate** (lay summary "Ce qui a été fait" — §3
since §2 = score table). Extract the body of `## 3. Ce qui a été fait`
(or `## 3. What we did` if `LANG=en`) and run `wc -w` on it.
**Hard cap: 300 words.** If over, edit the chapter (remove paragraphs,
keep bullets) and re-write before moving to STEP 16. Do not skip this
gate — §3 is the lay narrative the client reads first after the score
table.

```bash
awk '/^## 3\. /{flag=1; next} /^## 4\. /{flag=0} flag' "$OUTPUT" | wc -w
# expected: ≤ 300
```

**Skill-name leak gate.** Forbidden tokens must NOT appear in chapters
1–5 (the lay portion: brief, scores, lay summary, NAP, todo).
Chapter 6 (Détails techniques) may use them in the optional glossary.

```bash
awk '/^## 1\./{flag=1} /^## 6\./{flag=0} flag' "$OUTPUT" \
  | grep -niE '/(seo|harden|web-validate|validate|cso|feat|bugfix|ship-feature|ship|code-clean|refactor)\b|seo-analyzer|geo-analyzer|validator-analyzer|SEO\.md|HARDEN\.md|VALIDATE\.md|CSO\.md|MAX_ITERATIONS|ALL_PASS|SCORE_[A-Z_]+'
# expected: no matches. Each match is a leak — rewrite the offending
# chapter in client language before STEP 16.
```

**Anchor-resolution gate** (clickable section refs work).

```bash
grep -oE '\]\(#[a-z0-9-]+\)' "$OUTPUT_MD" | tr -d ']()#' | sort -u > /tmp/refs.txt
grep -oE 'id="[^"]+"' "$OUTPUT_HTML" | sed 's/id="//;s/"//' | sort -u > /tmp/ids.txt
comm -23 /tmp/refs.txt /tmp/ids.txt
# expected: empty. Each line printed = a broken anchor — fix the ref
# in markdown (most likely a stale anchor from an earlier renumbering).
```

If either gate fails, fix and re-write the markdown before continuing.

---

## STEP 16 — RENDER BRANDED HTML + PDF

Always produce a branded `.html` next to the `.md`. Produce a branded
`.pdf` when a PDF engine is available on the host. The file is the
client-visible deliverable.

### Inputs already known

| Variable          | Source                                      |
|-------------------|---------------------------------------------|
| `OUTPUT_MD`       | path written in STEP 15                     |
| `LANG`            | from STEP 1                                 |
| `PROJECT_NAME`    | `PROJECT_ROOT` basename or `package.json` `name` |
| `CLIENT_NAME`     | from journal first entry, README, or AskUserQuestion |
| `PROJECT_PERIOD`  | `<first commit date> → <last commit date>` (DD/MM/YYYY) |
| `PROJECT_URL`     | `DEPLOYED_URL` from STEP 6 (or `—` if none) |

If `CLIENT_NAME` is unknown after best-effort detection, ask once with
AskUserQuestion: `"Nom du client à afficher sur la couverture du PDF
(ou laisser vide pour ne rien afficher)?"`. A blank answer becomes `—`.

### Run the renderer

```bash
PROJECT_NAME="$PROJECT_NAME" \
CLIENT_NAME="$CLIENT_NAME" \
PROJECT_PERIOD="$PROJECT_PERIOD" \
PROJECT_URL="$PROJECT_URL" \
LANG="$LANG" \
"$HOME/.claude/skills/client-handover/scripts/handover-to-pdf.sh" \
  "$OUTPUT_MD"
```

The renderer:
1. Converts the markdown to HTML using the first available engine
   (pandoc > python-markdown > `npx marked`).
2. Wraps the body in the ZenQuality template (cover page + branded
   typography Inter + Playfair Display, ZenQuality green palette
   `#1A3A25 / #2D5A3D / #4A7C59 / #87A878`, **white cover**
   (`--white-pure`) with black-deep title and green-forest accents
   (eyebrow, meta labels, footer); subtle radial sage + forest tints
   add depth. Cream `#F5F0EB` reserved for body code/blockquote
   accents — not page bg).
3. Embeds the ZenQuality logo (default: `https://zenquality.fr/assets/logo-horizontal-1024.png`;
   override with `LOGO_URL` env var to use a local file).
4. Emits `LIVRAISON.html` (or `HANDOVER.html`) next to the `.md`.
5. Tries PDF engines in order: weasyprint > wkhtmltopdf > chromium >
   chromium-browser > google-chrome. First match writes
   `LIVRAISON.pdf` (or `HANDOVER.pdf`).
6. If no PDF engine is available, exits with code 2 and prints
   install hints. The HTML file is still produced and viewable —
   the user can "Print → Save as PDF" from any modern browser.

### Exit code handling

| `$?` | Meaning                                       | Action |
|------|-----------------------------------------------|--------|
| 0    | HTML and PDF written                          | continue to STEP 17 |
| 2    | HTML written, no PDF engine on host           | continue to STEP 17 — final report mentions PDF as MISSING and lists install commands |
| 1    | Fatal (bad args, unwritable dir, conv error)  | escalate to user with the script's stderr |

### Re-rendering on overwrite (option B in STEP 15)

If STEP 15 chose option B (`LIVRAISON-YYYY-MM-DD.md` versioned),
the renderer produces matching `LIVRAISON-YYYY-MM-DD.html` and
`LIVRAISON-YYYY-MM-DD.pdf`. Pass the versioned path as `$OUTPUT_MD`.

---

## STEP 17 — FINAL REPORT

Output to the user:

```
DONE — ship-and-handover pipeline complete.

OUTPUT:
  Markdown:  <path-to-md>
  HTML:      <path-to-html>
  PDF:       <path-to-pdf>     (or: NOT GENERATED — see install hints below)
LANGUAGE: fr | en
PROJECT TYPE: web (local-business) | web | cli | library | mobile | other
COMMITS ANALYZED: <count> from <first date> to <last date>

PIPELINE RESULT (web):
  SEO classique  <BEFORE>/20 → <AFTER>/20  ✅ (iterations: <N>)
  GEO (IA)       <BEFORE>/20 → <AFTER>/20  ✅ (iterations: <N>)
  HARDEN         <BEFORE>/20 → <AFTER>/20  ✅ (iterations: <N>)
  VALIDATE       —          → <AFTER>/20   ✅ (post-deploy)

PIPELINE RESULT (non-web):
  CSO       <BEFORE>/20 → <AFTER>/20  ✅ (iterations: <N>)

PIPELINE COMMITS: <list of SHAs created during STEP 5> (pushed: yes/no)
DEPLOY: confirmed at <YYYY-MM-DD HH:MM> — URL: <DEPLOYED_URL>
DECISIONS VULGARIZED: <count>
BLOCKERS REMAINING: <count> (open)

DOC SECTIONS WRITTEN:
  §1   Ce qu'il fallait faire (et pourquoi)
  §2   Résultats — état de santé (avant / après)  (score table, impact)
  §3   Ce qui a été fait                  (≤ 300 mots, sans jargon)
  §4   Vos informations officielles (NAP) (source-of-truth, before todo)
  §5   Ce qui vous reste à faire          (action checklist)
  §6   Détails techniques                 (choix, phases, glossaire)
  §7   Annexe — plateformes externes      (web only, NAP table not duplicated)
  §8   Annexe — build & déploiement       (only if requested)

Next steps for the user:
1. Open <path-to-pdf> (or the .html) — verify cover page, branding,
   §2 score table renders right after §1, §4 NAP table renders before
   §5 todo list (clickable section refs work in PDF). Adjust .md and
   re-run STEP 16 to regenerate.
2. Read end-to-end before sending — fill any [À COMPLÉTER] /
   [À CONFIRMER] markers (NAP fields in §4 especially).
3. Save a copy outside the repo (the .pdf is already client-ready).
4. Walk through §5 (ce qui vous reste à faire) with the client
   during the handover meeting — that's the part they MUST act on.

[If PDF was NOT generated, append:]
PDF NOT GENERATED — no PDF engine on this host. Install one of:
  - weasyprint   pip install --user weasyprint   (or: pipx install weasyprint)
  - wkhtmltopdf  apt install wkhtmltopdf
  - chromium     apt install chromium-browser
Then re-run only STEP 16 (the .md does not need to change).
```

If anything was skipped or uncertain, list under `CONCERNS:`.

---

## VOICE RULES (the whole document)

- **Vulgarize, don't dumb down.**
- **No emojis** unless the project itself uses them prominently.
- **No marketing fluff.**
- **Concrete numbers > adjectives.**
- **Lead with the user benefit.**
- **Acknowledge limits.**
- **No false modesty, no false confidence.**

---

## ESCALATION

If at any step you cannot proceed:

```
STATUS: BLOCKED | NEEDS_CONTEXT
STEP: <which step>
REASON: [1-2 sentences]
ATTEMPTED: [what you tried]
RECOMMENDATION: [what the user should do next]
PIPELINE STATE: <which scores captured, which commits made, which
                files modified — so user can resume>
```

---

## PLATFORM REFERENCE (fallback if checklists/seo-geo-manual.md missing)

Local-business priority order with 2026 signup URLs:

1. Google Business Profile — https://www.google.com/business/
2. Apple Business Connect — https://businessconnect.apple.com/
3. Bing Places for Business — https://www.bingplaces.com/
4. Pages Jaunes (FR) — https://www.pagesjaunes.fr/pro/inscription
5. Facebook Page — https://www.facebook.com/pages/create
6. Instagram Business — https://business.instagram.com/
7. TripAdvisor (hospitality) — https://www.tripadvisor.com/Owners
8. TheFork / La Fourchette (restaurants FR) — https://www.thefork.com/restaurant
9. Yelp — https://biz.yelp.com/
10. Mappy (FR) — https://corporate.mappy.com/
11. Waze — https://www.waze.com/business/
12. Foursquare for Business — https://business.foursquare.com/
13. Bottin / Justacote (FR) — https://www.justacote.com/
14. Hoodspot (FR) — https://www.hoodspot.fr/
15. Trustpilot — https://business.trustpilot.com/
16. Google Maps Local Guides reviews push — covered by Google Business

Niche-specific:
- Doctolib (médical FR) — https://pro.doctolib.fr/
- Booking.com (hôtellerie) — https://www.booking.com/business
- Airbnb (locations) — https://www.airbnb.com/host/homes
- LinkedIn Company Page — https://www.linkedin.com/company/setup/new/
- TikTok Business — https://www.tiktok.com/business/
- Pinterest Business — https://business.pinterest.com/

Non-local web priority:
1. Google Search Console — https://search.google.com/search-console
2. Bing Webmaster Tools — https://www.bing.com/webmasters
3. Wikidata entry — https://www.wikidata.org/wiki/Special:CreateAccount
4. LinkedIn Company Page (B2B)
5. Product Hunt (launches) — https://www.producthunt.com/posts/new
6. Crunchbase (startups) — https://www.crunchbase.com/add-new
7. G2 / Capterra (SaaS reviews) — https://www.g2.com/, https://www.capterra.com/
8. GitHub topic + README badges (open source)

AI visibility (GEO):
- Wikidata Q-item with `sameAs`
- Schema.org JSON-LD: Organization, LocalBusiness, niche, FAQPage, Article, Person
- llms.txt at site root
- Direct AI checks: search business name on ChatGPT, Claude, Perplexity, Gemini

If you need 2026-current pricing, signup steps, or a platform you're
unsure exists, use `WebSearch` and confirm before listing it. Do NOT
invent links.

---

## EDGE CASES

| Situation | Behavior |
|---|---|
| Repo has < 3 commits since first commit | Skip phase clustering in §5.2 of the deliverable; emit a short "First milestone" note instead. Do not fabricate phases. |
| `git log` empty (newly-initialised repo, no commit yet) | Print `"⚠️ no git history — handover doc requires at least one commit. Run /commit-change first."` and STOP before generating the doc. |
| Audit file exists but `Score:` line is malformed after re-dispatch retry | Mark `SCORE_<X>_AFTER=UNKNOWN`. Treat as below-threshold for STEP 8 gate (cannot certify). Append diagnostic to HANDOVER-ROADMAP.md: `"<audit> score unparseable — re-run /<audit> manually."` |
| Audit file missing entirely after STEP 4 attempts | Same as malformed: UNKNOWN, gate fails. Note `"<audit> file absent — auto-fix loop produced no output, see .claude/audits/."` |
| User confirms deploy in STEP 6 but `DEPLOYED_URL` is still empty | Re-prompt once: `"You confirmed Yes — what's the deployed URL? (paste URL or 'skip-validate' to set VALIDATE_SKIPPED=true)"`. On second empty answer, set VALIDATE_SKIPPED=true and proceed to STEP 8. |
| Deploy URL paste returns HTTP 0 / DNS failure during STEP 7 | Retry once after 30s. Still failing → set VALIDATE_SKIPPED=true with reason `"unreachable: <error>"`. Do not block the handover doc. |
| `.claude/memory/` registries do not exist | Skip the "Decisions / Learnings / Blockers" section in §5 with a one-line note: `"(no .claude/memory/ — registries not initialised on this project)."` Do not create them here — that is /onboard's job. |
| `--skip-audits` flag passed but `.claude/audits/` empty | STOP with `"--skip-audits requires existing audit files in .claude/audits/. None found — drop the flag or run /seo and /harden first."` |
| Output file (LIVRAISON.md / HANDOVER.md) already exists | Show diff vs. new content. Ask `"overwrite / save as -v2 / abort?"`. Default behavior must not silently overwrite a curated client doc. |