# Design Spec — Audit complet SEO + création section GEO (vault Obsidian)

**Date** : 2026-05-16
**Auteur** : Claude + Bastien (brainstorming session)
**Statut** : design validé, en attente review utilisateur avant `writing-plans`
**Hors vault** : ce spec vit dans `/Users/humperdoo/Documents/Claude/specs/` conformément à la règle "no Claude notes in vault" (mémoire `feedback_no_notes_in_vault`).

---

## 1. Contexte & objectif

Le vault Obsidian de l'utilisateur contient ~24 notes SEO mature pour template Next.js, mais :
- Aucune note dédiée GEO / AI search / AI Overviews
- Gaps majeurs côté SEO classique : canonicalization, redirects/migrations, JavaScript SEO, mobile-first indexing, crawl management
- Notes existantes pas alignées avec la doc Google Search Central 2026

**Objectif** : auditer + réécrire toutes les notes SEO, créer une section GEO complète, à partir d'un corpus de 53 docs Google Search Central scrapées (Mai 2026).

**Périmètre acté en brainstorming** :
- Audit complet SEO + création GEO (pas "GEO seul" ni "patches ciblés")
- Top-level `GEO/` séparé de `SEO/` (pas sous-dossier)
- Réécriture complète des notes SEO existantes **affectées par le corpus** (les notes non couvertes — Netlinking, Tailwind, Manifest, MCP GSC, etc. — restent inchangées)
- Exécution en phases (pas tout en parallèle, pas séquentiel pur)

---

## 2. Pipeline d'ingestion documentaire (nouveau)

Capture la mécanique pour ingérer ce corpus **et tous les futurs corpus** (Vercel, Cloudflare, etc.).

### 2.1 Structure folders

```
/Users/humperdoo/Documents/Claude/Docs/
  queue.md          ← User-managed : URLs à scraper, 1 ligne par URL (format libre)
  inbox/            ← Originaux scrapés, en attente d'intégration vault
    google-<slug>.md
  processed/        ← Originaux après intégration (archive)
    google-<slug>.md
    .queue-archive-YYYY-MM-DD.md   ← Snapshots du queue.md vidé
```

### 2.2 Flow utilisateur ↔ Claude

| Action | Acteur | Trigger |
|---|---|---|
| Ajouter URLs | User | Édite `queue.md` |
| Scrape parallèle URLs → inbox/ | Claude | Demande "process queue" |
| Vider queue (archive snapshot) | Claude | Auto après scrape réussi |
| Extract skeleton + delta mapping | Claude | Demande "ingest inbox" |
| Synthèse note vault + intégration | Claude | Auto après mapping |
| Archive original vers processed/ | Claude | Auto après note vault commitée |
| Review commits | User | Manuel |

### 2.3 État courant (post-bootstrap)

- `queue.md` : contient la liste des 53 URLs initiales (pour traçabilité — sera vidée lors du processing par phases)
- `inbox/` : 58 fichiers `google-*.md` (53 docs initiaux + scrapes du brainstorming = même corpus)
- `processed/` : vide

---

## 3. Architecture cible du vault

### 3.1 Layout

```
SEO/                                           (étendu, audité)
  SEO.md (MOC)
  Architecture/
    Architecture Next.js & Siloing.md          (rewrite light)
    Structure URL.md                            (rewrite)
    Migrations & 301 Redirects.md              ← NEW
    Astro6-vs-Nextjs16-Benchmark.md            (unchanged)
  Techniques/
    Metadata.md                                 (rewrite)
    JSON-LD.md                                  (rewrite)
    OG Images.md                                (rewrite light)
    Sitemap.md                                  (rewrite, fusion i18n)
    Sitemap Image & Video & News.md            ← NEW
    Robots.md                                   (rewrite)
    Robots.txt - spec complète.md              ← NEW
    Headers HTTP.md                             (rewrite, fusion Vercel postmortem)
    RSS Feed.md                                 (unchanged)
    Canonicalization.md                         ← NEW
    noindex & block-indexing.md                ← NEW
    rel attributes (nofollow, sponsored, ugc).md ← NEW
    JavaScript SEO (Next.js).md                ← NEW
    Mobile-First Indexing.md                   ← NEW
    Indexable File Types.md                    ← NEW
  Bonnes Pratiques/
    Core Web Vitals.md                          (rewrite light)
    Tailwind Typography & SEO.md               (unchanged)
    Frontmatter & Contenu.md                    (rewrite)
    Manifest & PWA.md                           (unchanged)
    Helpful Content & E-E-A-T.md               ← NEW
    Search Essentials & Spam Policies.md       ← NEW
  Crawl & Indexation/                           ← NOUVELLE SECTION
    How Search Works.md                        ← NEW
    Liste des Googlebots.md                    ← NEW
    Reduce Crawl Rate.md                       ← NEW
    Verify Googlebot.md                        ← NEW
    Ask Google to Recrawl.md                   ← NEW
    Troubleshoot Crawl Errors.md               ← NEW
    Control What You Share.md                  ← NEW
    Page & Image Removals.md                   ← NEW
    Pause Website Temporarily.md               ← NEW
    A/B Testing SEO.md                         ← NEW
  Netlinking/                                   (inchangé — pas couvert par corpus actuel)
  Outils/
    Bonnes Pratiques MCP GSC.md                (unchanged)
    Search Console (overview).md               ← NEW
  Archive/                                      ← NOUVEAU
    AMP - dépréciation 2026.md                 ← NEW (synthèse 5 docs AMP)
  Stale Check.md                                ← NEW (Dataview query péremption)

GEO/                                           ← NOUVEAU TOP-LEVEL
  GEO.md (MOC)
  Fondamentaux/
    AI Overviews & AI Mode.md                  ← NEW
    RAG & Query Fan-out.md                     ← NEW
    Mythbusting (llms.txt, chunking, AEO).md   ← NEW
  Contenu/
    Contenu Gen-AI & Spam Policy.md            ← NEW
    Disclosure & Contexte utilisateur.md       ← NEW
  Technique/
    Bots IA & Crawlers.md                      ← NEW
    Agents Web & UCP.md                        ← NEW
  Ecommerce/
    Merchant Center & AI Product Data.md       ← NEW
    IPTC DigitalSourceType pour images AI.md   ← NEW
```

### 3.2 Notes supprimées (fusion)

- `SEO/Techniques/Sitemap Nextjs i18n.md` → contenu fusionné dans `Sitemap.md` (section i18n)
- `SEO/Vercel-X-Robots-Tag-Postmortem-2026.md` → contenu fusionné dans `Headers HTTP.md` (callout Étude de cas)

### 3.3 Récap quantitatif

| Catégorie | Count |
|---|---|
| Notes neuves (NEW) | 34 |
| Notes réécrites (REW) | 7 |
| Notes patches légers (LIGHT) | 3 |
| Notes inchangées (KEEP) | ~10 (Netlinking 5-6, RSS, Tailwind, Manifest, Astro, MCP GSC) |
| Notes supprimées (DEL) | 2 |
| **Total final vault SEO+GEO** | **~54 notes** |

Détail : 34 NEW = 1 (Architecture) + 8 (Techniques) + 2 (Bonnes Pratiques) + 10 (Crawl & Indexation) + 1 (Outils) + 1 (Archive) + 1 (Stale Check) + 11 (GEO incl. MOC) = 34 (avec MOC GEO comptée).
Notes touchées (NEW + REW + LIGHT) = 44.
Notes intactes (KEEP) = ~10.

---

## 4. Mapping notes → docs Google source

### 4.1 SEO/Architecture/
| Note | Action | Sources |
|---|---|---|
| Architecture Next.js & Siloing | LIGHT | seo-starter-guide, links-crawlable |
| Structure URL | REW | url-structure |
| Migrations & 301 Redirects | NEW | 301-redirects + site-move-no-urls + site-move-with-urls |

### 4.2 SEO/Techniques/
| Note | Action | Sources |
|---|---|---|
| Metadata | REW | page-metadata + special-tags |
| JSON-LD | REW | structured-data refs (croisées) |
| OG Images | LIGHT | image SEO refs |
| Sitemap | REW | sitemaps-overview + build + large-index + combine |
| Sitemap Image & Video & News | NEW | image-sitemaps + news-sitemaps + video-sitemaps |
| Robots | REW | robots-intro + control-share |
| Robots.txt - spec complète | NEW | robots-spec |
| Headers HTTP | REW | robots-meta-tag (X-Robots-Tag) + Vercel postmortem (fusion) |
| Canonicalization | NEW | canonicalization + rel-canonical + canonicalization-troubleshoot |
| noindex & block-indexing | NEW | noindex |
| rel attributes | NEW | rel-attributes |
| JavaScript SEO (Next.js) | NEW | js-seo-basics + js-fix-search + js-lazy-loading + js-dynamic-rendering |
| Mobile-First Indexing | NEW | mobile-first-indexing |
| Indexable File Types | NEW | indexable-file-types |

### 4.3 SEO/Bonnes Pratiques/
| Note | Action | Sources |
|---|---|---|
| Core Web Vitals | LIGHT | seo-starter-guide §page-experience |
| Frontmatter & Contenu | REW | helpful-content (E-E-A-T) |
| Helpful Content & E-E-A-T | NEW | helpful-content (full) |
| Search Essentials & Spam Policies | NEW | essentials + essentials-technical + spam-policies |

### 4.4 SEO/Crawl & Indexation/
| Note | Action | Sources |
|---|---|---|
| How Search Works | NEW | how-search-works |
| Liste des Googlebots | NEW | crawlers-list + googlebot |
| Reduce Crawl Rate | NEW | reduce-crawl-rate |
| Verify Googlebot | NEW | verifying-googlebot |
| Ask Google to Recrawl | NEW | ask-recrawl |
| Troubleshoot Crawl Errors | NEW | troubleshoot-crawl-errors |
| Control What You Share | NEW | control-share |
| Page & Image Removals | NEW | page-removals + image-removals + redacted-info |
| Pause Website Temporarily | NEW | pause-website |
| A/B Testing SEO | NEW | ab-testing |

### 4.5 SEO/Archive/
| Note | Action | Sources |
|---|---|---|
| AMP - dépréciation 2026 | NEW (synthèse) | amp + amp-about + amp-enhance + amp-validate + amp-remove |

### 4.6 SEO/Outils/
| Note | Action |
|---|---|
| Search Console (overview) | NEW (synthèse refs Search Console disséminées dans corpus) |

### 4.7 GEO/
| Note | Action | Sources |
|---|---|---|
| GEO.md (MOC) | NEW | — |
| AI Overviews & AI Mode | NEW | ai-optimization-guide §RAG + valuable-content + technical-structure |
| RAG & Query Fan-out | NEW | ai-optimization-guide §intro |
| Mythbusting (llms.txt, chunking, AEO) | NEW | ai-optimization-guide §mythbusting |
| Contenu Gen-AI & Spam Policy | NEW | using-gen-ai-content + spam-policies §scaled-content |
| Disclosure & Contexte utilisateur | NEW | using-gen-ai-content §give-users-context |
| Bots IA & Crawlers | NEW | crawlers-list (Google-Extended, GoogleOther) + refs externes OAI/Claude/Perplexity |
| Agents Web & UCP | NEW | ai-optimization-guide §agentic-experiences |
| Merchant Center & AI Product Data | NEW | using-gen-ai-content §ecommerce |
| IPTC DigitalSourceType pour images AI | NEW | using-gen-ai-content §IPTC |

---

## 5. Templates standard

### 5.1 Template A — Note technique (implémentation Next.js)

Pour : Metadata, Robots, Canonicalization, JS SEO, Sitemap, Headers HTTP, Migrations 301, etc.

````markdown
---
tags:
  - seo
  - seo/technique         # ou seo/crawl, seo/architecture
aliases:
  - <synonymes>
date_creation: 2026-05-16
date_maj_google: <YYYY-MM-DD>    # last-updated de la doc Google source
---

Retour à [[SEO]]

# <Titre>

> [!info] Quoi
> 1 phrase — but de la note.

## Fichiers
Chemins du template Next.js concernés.

## Fonctionnement
Synthèse + snippets TypeScript.

## Bonnes pratiques (Google 2026)
Règles condensées.

## Étude de cas Elevaseo
> [!example] Postmortem / anecdote
> Section optionnelle. Ex: Vercel X-Robots-Tag dans Headers HTTP.

## Checklist
- [ ] Vérif 1
- [ ] Vérif 2

## Pièges
> [!warning] Pièges fréquents
> - Erreur 1
> - Erreur 2

## Voir aussi
[[Note 1]] · [[Note 2]]

> [!quote] Source
> Google Search Central — [<titre>](URL) · maj <date> · CC BY 4.0
````

### 5.2 Template B — Note conceptuelle / éditoriale

Pour : GEO/*, Helpful Content & E-E-A-T, Spam Policies, Mythbusting, etc.

````markdown
---
tags:
  - geo            # ou seo selon contexte
  - geo/fondamentaux    # ou geo/contenu, geo/technique, geo/ecommerce
aliases:
  - <synonymes>
date_creation: 2026-05-16
date_maj_google: <YYYY-MM-DD>
---

Retour à [[GEO]]

# <Titre>

> [!abstract] TL;DR
> 2-3 phrases — l'essentiel.

## Concept
Définitions clés. Pourquoi ça existe.

## Règles Google 2026
Liste hiérarchisée.

## Application pratique
Comment ça s'applique aux sites Elevaseo.

## Checklist
- [ ] À vérifier

## Pièges & mythes
> [!warning] Ce qu'il ne faut PAS faire

## Voir aussi
[[Note]]

> [!quote] Source
> Google Search Central — [<titre>](URL) · maj <date> · CC BY 4.0
````

### 5.3 Règles transversales

1. **Synthèse, pas transcription** — vault notes en mots propres, attribution via callout Source.
2. **Snippets TypeScript** issus du template Next.js Elevaseo, pas Google.
3. **`date_maj_google`** dans frontmatter pour traquer péremption (Dataview).
4. **Tags hiérarchiques** : `seo/technique`, `seo/crawl`, `seo/bonnes-pratiques`, `seo/architecture`, `seo/outils`, `geo/fondamentaux`, `geo/contenu`, `geo/technique`, `geo/ecommerce`.
5. **Callouts Obsidian** uniformes : `info` / `warning` / `quote` / `abstract` / `example`.
6. **Breadcrumb** retour MOC systématique.
7. **Section Pièges obligatoire** sur toutes notes.

### 5.4 Stale Check (note Dataview)

`SEO/Stale Check.md` — query Dataview listant les notes dont `date_maj_google` > 6 mois (signal de re-vérification recommandée).

````markdown
---
tags: [seo, outils]
---

# Stale Check — Péremption docs Google

\`\`\`dataview
TABLE date_maj_google AS "Maj Google", date(today) - date(date_maj_google) AS "Ancienneté"
FROM "SEO" OR "GEO"
WHERE date_maj_google
SORT date_maj_google ASC
\`\`\`
````

---

## 6. Phasage d'exécution

Chaque phase = 1 spec dérivé (court) + 1 plan d'implémentation + 1 cycle exécution + 1 commit.

| Phase | Périmètre | Notes | Parallélisme | Risque |
|---|---|---|---|---|
| 0 | Fondations (MOC update, GEO.md, Stale Check, tags) | 3 | non | min |
| 1 | GEO/ complet | 10 | 3 subagents | bas |
| 2 | SEO/Crawl & Indexation/ | 10 | 2 subagents | bas |
| 3 | SEO/Techniques/ (gros morceau) | 14 (+2 DEL) | séquentiel | **haut** |
| 4 | SEO/Bonnes Pratiques/ | 6 | 2 subagents | moyen |
| 5 | SEO/Architecture/ + Archive/ + Outils/ | 5 | 2 subagents | moyen |
| 6 | Skill capture `obsidian-doc-ingest` | 1 note + 1 skill | non | bas |

### 6.1 Validation gates entre phases

- Diff visuel du commit avant phase suivante
- Vérif frontmatter + breadcrumb sur chaque note touchée
- Smart Connections re-index recommandé
- Smoke test wikilinks : aucun [[lien cassé]] (Strange New Worlds plugin l'indique)

### 6.2 Ordre de rédaction Phase 3 (séquentiel)

Risque max car forte interdépendance (Robots ↔ Robots.txt spec ↔ Headers HTTP ↔ Canonicalization). Pas de subagents parallèles.

1. Indexable File Types → 2. Canonicalization → 3. noindex → 4. rel attributes → 5. Robots (rewrite) → 6. Robots.txt spec → 7. Headers HTTP (rewrite + fusion postmortem) → 8. Metadata (rewrite) → 9. JS SEO → 10. JSON-LD (rewrite) → 11. Sitemap (rewrite + fusion i18n) → 12. Sitemap Image/Video/News → 13. OG Images (light) → 14. Mobile-First Indexing

---

## 7. Skill capture (Phase 6)

### 7.1 Deliverables

- **Skill runnable** : `~/.claude/skills/obsidian-doc-ingest/`
  - `SKILL.md` (instructions principales)
  - `references/scrape-patterns.md` (batching, naming, parallel limits)
  - `references/integration-patterns.md` (skeleton extract, delta mapping)
  - `references/templates.md` (Templates A & B, règles transversales)
- **Note vault** : `Skills/Doc Ingestion Flow.md` (doc humaine du process, instruction utilisateur)

### 7.2 Déclencheurs (triggers)

Le skill s'active quand l'utilisateur :
- Demande de scraper une liste d'URLs documentaires
- Mentionne `queue.md`, `inbox/`, "ingest docs", "process queue"
- Demande d'intégrer une doc externe (Vercel, Cloudflare, Next.js, etc.) dans le vault Obsidian
- Demande "même flow que SEO/GEO sur tel autre corpus"

### 7.3 Étapes codifiées

1. **Pré-check** : `firecrawl --status` + dir `/Users/humperdoo/Documents/Claude/Docs/` existe
2. **Read queue.md** → extract URLs
3. **Scrape parallèle** → `inbox/google-<slug>.md` (ou `<provider>-<slug>.md`)
4. **Archive queue** → `processed/.queue-archive-YYYY-MM-DD.md`
5. **For each inbox file** : extract skeleton (grep headings) → propose delta vs vault → user validation
6. **Synthèse note vault** selon Template A ou B
7. **Move original** : `inbox/X.md` → `processed/X.md`
8. **Commit** vault + (optionally) update skill self if learnings emerged

### 7.4 Itération

Le skill commence simple en Phase 6. Améliorations futures captures au fil des corpus suivants :
- Vercel docs (probable prochain corpus)
- Cloudflare (probable)
- Next.js (probable)

Chaque corpus enrichit les `references/` du skill.

---

## 8. Critères d'acceptance globaux

1. Toutes les notes ont frontmatter conforme (tags, aliases, date_maj_google)
2. Aucun [[wikilink cassé]] (vérif via Strange New Worlds)
3. Tous les MOC (SEO.md, GEO.md, futurs sous-MOC) listent leurs enfants
4. `Stale Check.md` retourne 0 notes au moment du closing (toutes à jour)
5. `inbox/` vide à la fin (tout intégré)
6. `processed/` contient les 58 originaux Google
7. Skill `obsidian-doc-ingest` runnable et déclenchable sur futurs corpus

---

## 9. Hors scope

- Notes `SEO/Netlinking/` (Backlinks-Bulk, guest post, disavow) — pas couvertes par le corpus Google actuel
- Documentation utilisateur final (le vault est interne)
- Refactor `Templates/` Obsidian existants
- Migration des notes vers Bases (.base files)
- Internationalisation des notes (vault reste FR)

---

## 10. Risques & mitigations

| Risque | Mitigation |
|---|---|
| Phase 3 trop massive → fatigue review | Sous-commits par lots de 3-4 notes |
| Subagents drift (incohérence cross-refs) | Review wikilinks après chaque phase |
| Synthèse perd nuances Google | Callout Source obligatoire avec URL exact |
| AMP synthèse trop dense en 1 note | Si dépassement, split en 2 (overview / migration) |
| Skill capture trop tôt (Phase 6) | OK car patterns matures après 5 phases |

---

## 11. Prochaine étape

Une fois ce spec validé par l'utilisateur :
→ Invoquer `superpowers:writing-plans` pour produire le plan d'implémentation détaillé de la **Phase 0** (Fondations).

Les phases suivantes (1-6) feront chacune l'objet d'un cycle spec court → plan → implementation.