# Livada SEO — Guide de Référence pour Claude

> **Ce document est destiné à Claude Code** lorsqu'il travaille sur un site WordPress
> qui a Livada SEO installé. Il explique ce qu'est le plugin, comment il fonctionne,
> comment le configurer pour un rendement maximal, et pourquoi il remplace Yoast/Rank Math.

---

## 1. Qu'est-ce que Livada SEO ?

Livada SEO est un plugin WordPress SEO complet, **gratuit et GPL**, concu pour les sites
tourisme, hotellerie et commerces locaux. Il remplace Yoast Premium + Yoast Local +
Rank Math PRO en une seule extension sans upsell, sans bloat frontend, et avec des
fonctionnalites qu'aucun concurrent n'offre en 2026 (AEO, MCP server, multi-location
inclus).

**Version actuelle : 1.8.4** | PHP 7.4+ | WordPress 6.0+ | Teste jusqu'a WP 6.7

### Philosophie

- **Zero JS/CSS en frontend** (sauf breadcrumbs.css opt-in, < 1 KB)
- **Une seule requete DB** par page-vue (`get_option` unique, cache statique)
- **Modulaire** : chaque feature est un module activable/desactivable
- **AI-native** : suggestions de titres/descriptions/mots-cles + alt-text images via Claude API
- **Developer-friendly** : REST API complete, WP-CLI, MCP server, filtres partout

### Source du plugin

Le code source se trouve dans : `D:\Slave H\Claude\plugins\livada-seo\`

Le plugin se deploie sur les sites comme une extension WP classique (upload zip ou FTP).

---

## 2. Architecture Modulaire

### Modules opt-in (activables dans Livada SEO > General)

| Module | Fichier | Ce qu'il fait |
|--------|---------|---------------|
| `meta` | class-meta.php | Titres SEO, meta description, canonical, robots directives |
| `sitemap` | class-sitemap.php | XML sitemap multi-index + Google News + cache 12h |
| `sitemap_html` | class-sitemap-html.php | Sitemap HTML accessible (opt-in) |
| `schema` | class-schema.php | JSON-LD @graph : WebSite, LocalBusiness (12 sous-types), Article, FAQPage, HowTo, Product, Event, Recipe, Review, Offer, Service, Person |
| `opengraph` | class-opengraph.php | Open Graph + Twitter Cards |
| `redirects` | class-redirects.php | 301/302 + compteur de hits + CSV import/export |
| `breadcrumbs` | class-breadcrumbs.php | Shortcode `[livada_breadcrumbs]` + JSON-LD BreadcrumbList |
| `analysis` | class-analysis.php | 16 checks SEO on-save + score Flesch + colonnes admin |
| `robots` | class-robots.php | Robots.txt virtuel avec directive Sitemap auto |
| `indexnow` | class-indexnow.php | Ping async Bing/Yandex via WP-Cron |
| `toc` | class-toc.php | Table des matieres (opt-in) |
| `image_seo` | class-image-seo.php | Optimisation SEO images frontend |
| `analytics` | class-analytics.php | Injection GA4 / Matomo / Clarity |
| `geo` | class-geo.php | Author expertise E-A-T + speakable schema |
| `aeo` | class-aeo.php | `/llms.txt`, `/llms-full.txt`, marqueurs AI, headers AI |
| `site_audit` | class-site-audit.php | Audit quotidien (8 checks/post + 5 site-wide) |
| `woocommerce` | class-woocommerce.php | Product/Offer/AggregateRating/Review schemas |
| `og_image` | class-og-image.php | Generateur OG image programmatique 1200x630 (GD) |

### Infrastructure (toujours chargee)

- **REST API** (`class-rest-api.php`) — ~30 endpoints sous `/wp-json/livada-seo/v1/`
- **WP-CLI** (`class-cli.php`) — `wp livada-seo settings|meta|redirects|import|sitemap|audit|analyze|doctor`
- **Importers** — Yoast SEO + SEOPress (batches, lossless)
- **404 Monitor** (`class-404-monitor.php`) — log throttle + conversion 1-click en 301
- **Hreflang** (`class-hreflang.php`) — Polylang, WPML, TranslatePress, JSON manuel
- **AI Suggestions** (`class-ai.php`) — titre/description/keyword/rewrite via Claude API
- **Bulk Editor** (`class-bulk-editor.php`) — edition en masse titres/desc/keyword/noindex + bulk AI fill
- **Image Bulk** (`class-image-bulk.php`) — alt-text en masse + generation AI via vision
- **Activity Log** (`class-activity-log.php`) — journal d'events, 1000 lignes, detection acteur (web/cli/rest/cron/ajax)
- **Self-hosted Updater** (`class-updater.php`) — verification de mise a jour via manifest JSON
- **Onboarding** (`class-onboarding.php`) — wizard 4 etapes a la premiere activation
- **Link Suggestions** (`class-link-suggestions.php`) — suggestions de liens internes live dans la metabox
- **Link Graph** (`class-link-graph.php`) — visualisation du maillage interne (orphelins, hubs)
- **GSC Import** (`class-gsc-import.php`) — import CSV de mots-cles Google Search Console

---

## 3. Configuration Optimale (pour tirer le maximum)

### Etape 1 : Activation et General Settings

1. Activer **tous les modules** (ils le sont par defaut)
2. Renseigner la **cle API Anthropic** dans General Settings pour debloquer :
   - Suggestions AI de titres/descriptions/mots-cles dans la metabox
   - Generation AI d'alt-text pour les images
   - Bulk AI fill dans le Bulk Editor
   - La cle est chiffree AES-256-CBC au repos (derivee de `wp_salt('auth')`)

### Etape 2 : Schema / Structured Data (PRIORITAIRE)

C'est **le coeur du SEO technique**. Aller dans Livada SEO > Schema :

1. **Business Type** : choisir le type le plus specifique
   - `Campground` pour un camping
   - `Hotel` pour un hotel
   - `BedAndBreakfast` pour un B&B
   - `Restaurant`, `Store`, `TouristAttraction` selon le cas
   - `LocalBusiness` en generique si rien ne colle

2. **Remplir TOUS les champs** :
   - Nom, adresse, ville, code postal, pays
   - Telephone, email, URL du site, logo
   - Coordonnees GPS (lat/lng) — crucial pour le local SEO
   - Tranche de prix (`schema_price_range` : ex. "€€")
   - Horaires d'ouverture (par jour)
   - Profils sociaux (`sameAs` : Facebook, Instagram, etc.)

3. **Champs tourisme** (actifs pour Campground/Hotel/LodgingBusiness/Resort/B&B) :
   - Nombre d'etoiles (`schema_star_rating`)
   - Nombre de chambres/emplacements (`schema_number_of_rooms`)
   - Animaux acceptes (`schema_pets_allowed`)
   - Heures check-in / check-out
   - Amenities (piscine, wifi, parking, etc.)
   - Note moyenne + nombre d'avis

4. **Services** : ajouter les services proposes (chaque service genere un noeud Service dans le @graph)

### Etape 3 : Multi-Location (si applicable)

Livada SEO > Locations — ajouter N emplacements sous un meme site WP.
Chaque location genere son propre noeud LocalBusiness dans le @graph.
**Gratuit** (Yoast Local = 79 EUR/an).

### Etape 4 : Titles & Meta

Livada SEO > Titles — configurer les templates :
- `%title% %sep% %sitename%` pour les posts/pages
- `%sitename% %sep% %tagline%` pour la homepage
- Variables dispo : `%title%`, `%sitename%`, `%sep%`, `%tagline%`, `%category%`, `%tag%`, `%term%`, `%date%`, `%page%`

### Etape 5 : AEO (AI Engine Optimization) — UNIQUE a Livada

C'est ce qui fait la difference en 2026. Le module AEO :
- Sert `/llms.txt` et `/llms-full.txt` — fichiers de decouverte pour ChatGPT, Perplexity, Gemini, Claude
- Ajoute des marqueurs AI dans le contenu (`the_content` filter)
- Emet un Knowledge Graph Organization en JSON-LD sur la front page
- Envoie des headers HTTP de discoverabilite AI
- Directive `max-snippet:-1` pour permettre aux AI d'utiliser le contenu

**Configurer dans les settings** :
- `aeo_org_description` : description de l'organisation
- `aeo_org_founding_date` : annee de creation
- `aeo_org_founder` : nom du fondateur
- `aeo_org_knows_about` : domaines d'expertise (array)

### Etape 6 : GEO (Author Expertise)

- `geo_author_expertise` : description de l'expertise de l'auteur (E-A-T)
- `geo_author_url` : URL de la page "A propos" de l'auteur
- `geo_speakable` : active le schema Speakable sur les articles
- `geo_citation_meta` : ajoute les meta de citation

### Etape 7 : Sitemap

- Selectionner les post types et taxonomies a inclure
- Configurer Google News (post types, nom de publication, langue)
- Le cache est de 12h, invalide automatiquement a chaque `save_post`
- Les CPT template (elementor_library, jkit-*, etc.) sont auto-exclus

### Etape 8 : Image SEO

1. Aller dans Livada SEO > Image SEO (page bulk)
2. Voir toutes les images sans alt-text
3. **Bouton AI** : genere un alt-text via Claude Vision (≤125 caracteres)
4. Edition inline + sauvegarde en masse

### Etape 9 : Redirections + 404 Monitor

- **404 Monitor** : log automatique des 404, top 200, conversion 1-click en 301
- **Redirections** : 301/302, compteur de hits, recherche, suppression en masse, CSV import/export
- **Detection de chaines** : le plugin detecte les boucles et chaines de redirections

### Etape 10 : Site Audit

- Audit quotidien automatique (WP-Cron)
- 8 checks par post : titre SEO, meta desc, focus keyword, score SEO, Flesch, image, liens internes, nombre de mots
- 5 checks site-wide : sitemap, robots.txt, schema, conflit SEO, template CPTs
- Dashboard avec cartes cliquables vers les posts a corriger

### Etape 11 : Hreflang (sites multilingues)

Si le site utilise Polylang, WPML ou TranslatePress :
- Le module detecte automatiquement le plugin de traduction actif
- Genere les balises hreflang correctes
- **TranslatePress** : seul plugin SEO qui supporte nativement TranslatePress
  (desactive le hreflang natif de TP pour eviter les doublons)
- Override possible par post via un champ JSON dans la metabox

### Etape 12 : WooCommerce (si applicable)

- Active automatiquement si WooCommerce est present
- Emet Product + Offer + AggregateRating + Review en JSON-LD
- Support des variations de produit
- Augmente le sitemap avec `product`, `product_cat`, `product_tag`

### Etape 13 : Analytics

- GA4 : renseigner l'ID `G-XXXXXXXXXX`
- Matomo : URL + Site ID
- Microsoft Clarity : ID du projet
- Slot `<head>` custom pour tout autre script
- Option d'exclure les admins du tracking

---

## 4. Metabox SEO (par post/page)

Chaque post/page a une metabox "Livada SEO" avec :

- **Titre SEO** custom (preview live desktop + mobile)
- **Meta description** custom (preview live)
- **Focus keyword** — declenche l'analyse de 16 checks
- **Score SEO** (0-100) avec detail par check
- **Score de lisibilite** Flesch
- **Canonical URL** custom
- **Robots** : noindex, nofollow
- **Image OG** custom
- **Type de schema** par post (Article, FAQPage, HowTo, Product, Event, Recipe, Review, etc.)
- **Cornerstone** : marquer comme article phare (booste les suggestions de liens internes)
- **Hreflang** : override JSON par post
- **Location** : associer a un emplacement specifique (multi-location)
- **Boutons AI** : generer titre/description/keyword via Claude

### Les 16 checks d'analyse

Le score est calcule a chaque sauvegarde. Checks (accent-insensitive, word-aware depuis v1.8.2) :

1. Mot-cle dans le titre SEO
2. Mot-cle dans la meta description
3. Mot-cle dans le H1
4. Mot-cle dans le premier paragraphe
5. Mot-cle dans le slug URL (word-by-word)
6. Densite du mot-cle (optimal : 1-3%)
7. Longueur du titre (50-60 caracteres)
8. Longueur de la meta description (120-160 caracteres)
9. Nombre de mots (minimum 300)
10. Images dans le contenu
11. Image a la une (featured image)
12. Liens internes dans le contenu
13. Liens externes dans le contenu
14. Attributs alt sur les images
15. Score de lisibilite Flesch (>= 30)
16. URL canonique

---

## 5. Conventions Techniques (pour Claude qui edite le code)

### Nommage

- Classe PHP : `Livada_SEO_{Module}`
- Fonction : `livada_seo_*`
- Hook : `livada_seo_*`
- Option WP : `livada_seo_settings` (array serialise unique)
- Multi-location : `livada_seo_locations`
- Post meta : `_livada_seo_{field}`
- Tables : `{prefix}livada_seo_redirects`, `{prefix}livada_seo_404_log`, `{prefix}livada_seo_activity_log`
- Transients : `livada_seo_*`

### Regles absolues

1. **Jamais** `get_option('livada_seo_settings')` dans le code module — utiliser `Livada_SEO_Loader::get_setting($key)`
2. **Jamais** de JS/CSS en frontend sauf breadcrumbs.css
3. **Jamais** de requete SQL directe sur les tables du plugin — utiliser les methodes CRUD des classes
4. Cle API Anthropic : lire via `Livada_SEO_Image_Bulk::get_anthropic_key()`, ecrire via `encrypt_key_for_storage()`
5. Modele AI : `claude-sonnet-4-5-20250929` (defini dans `Livada_SEO_AI::MODEL`)
6. Pour ajouter un module : l'ajouter dans `$feature_map` du Loader + dans `livada_seo_default_settings()`

### REST API (namespace `livada-seo/v1`)

Tous les endpoints requierent `manage_options`. Auth via Application Passwords.

| Methode | Path | Usage |
|---------|------|-------|
| GET/PUT | `/settings` | Lire/modifier les settings |
| GET/PUT | `/meta/{id}` | Meta SEO par post |
| PUT | `/meta/bulk` | Mise a jour en masse |
| GET/POST/PUT/DELETE | `/redirects` `/redirects/{id}` | CRUD redirections |
| GET/POST | `/audit` | Resultats audit / forcer un audit |
| GET/POST/PUT/DELETE | `/locations` `/locations/{i}` | CRUD emplacements |
| POST | `/ai/suggest/{id}` | Suggestion AI (titre/desc/keyword) |
| GET | `/images/missing-alt` | Images sans alt |
| PUT | `/images/{id}/alt` | Definir alt-text |
| POST | `/images/{id}/ai-alt` | Generer alt AI (vision) |
| GET | `/schema/preview/{id}` | Preview JSON-LD |
| GET | `/analysis/{id}` | Re-lancer l'analyse |
| POST | `/sitemap/flush` | Vider le cache sitemap |
| GET | `/sitemap/diagnose` | Diagnostic sitemap |
| POST | `/import/yoast` | Migration Yoast (batche) |
| POST | `/import/seopress` | Migration SEOPress (batche) |
| GET/DELETE | `/404` `/404/{id}` | Log 404 |
| POST | `/404/{id}/redirect` | Convertir 404 en 301 |
| POST | `/indexnow/ping` | Ping IndexNow |
| GET | `/dashboard` | Stats agregees |
| GET | `/woo/product/{id}/schema` | Preview Product JSON-LD |

### WP-CLI

```bash
wp livada-seo settings get                    # Afficher les settings
wp livada-seo settings set separator "—"      # Modifier un setting
wp livada-seo meta get 123                    # Lire meta SEO d'un post
wp livada-seo meta set 123 title "Mon titre"  # Modifier meta
wp livada-seo redirects list                  # Lister les redirections
wp livada-seo import yoast                    # Migrer depuis Yoast
wp livada-seo import seopress                 # Migrer depuis SEOPress
wp livada-seo sitemap regenerate              # Regenerer le sitemap
wp livada-seo audit                           # Lancer un audit
wp livada-seo analyze --all                   # Analyser tous les posts
wp livada-seo analyze --post_id=123           # Analyser un post
wp livada-seo doctor                          # Diagnostic complet
```

### MCP Server (pour Claude Code)

Le dossier `mcp-server/` contient un serveur MCP TypeScript (33 outils).
Setup une seule fois :

```bash
cd mcp-server && npm install && npm run build
claude mcp add livada-seo \
  --env WP_URL=https://example.com \
  --env WP_USER=admin \
  --env WP_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx" \
  -- node /path/to/livada-seo/mcp-server/dist/index.js
```

Le MCP expose 33 outils couvrant : settings, meta, redirects, audit, locations,
images, AI alt-text, sitemap, IndexNow, imports, schema preview, 404, WooCommerce.

---

## 6. Migration depuis Yoast SEO

1. Garder Yoast **actif** pendant l'import
2. Livada SEO > Tools > Import from Yoast SEO > Start Import
3. Import batche (50 posts/requete) : titres, meta descriptions, focus keywords, canonical, OG images, robots flags, templates de titres, profils sociaux, redirections Yoast Premium
4. Apres succes : desactiver Yoast, verifier quelques posts, puis supprimer Yoast
5. Le plugin detecte et avertit des conflits SEO actifs

---

## 7. Pourquoi Livada SEO est superieur a Yoast / Rank Math

### Performance

| Metrique | Livada SEO | Yoast Free | Yoast Premium | Rank Math PRO |
|----------|-----------|------------|---------------|---------------|
| JS frontend | **0 KB** | ~80 KB | ~80 KB | ~60 KB |
| CSS frontend | **0 KB** (1 KB si breadcrumbs) | ~15 KB | ~15 KB | ~10 KB |
| Requetes DB/page | **1** (get_option) | 3-5 | 3-5 | 2-4 |
| Impact PageSpeed | **Nul** | -3 a -8 pts | -3 a -8 pts | -2 a -5 pts |

### Fonctionnalites exclusives (aucun concurrent ne les a)

1. **AEO natif** — `/llms.txt`, `/llms-full.txt`, marqueurs AI, headers de discoverabilite
   - En 2026, aucun des top-5 plugins SEO ne sert `/llms.txt`
   - Crucial pour etre cite par ChatGPT, Perplexity, Gemini, Claude

2. **MCP Server** — piloter le SEO depuis Claude Code via un protocole standard
   - Aucun autre plugin SEO au monde n'a d'integration MCP

3. **TranslatePress hreflang** — seul plugin SEO avec un adaptateur natif
   - Yoast et Rank Math ne supportent que Polylang/WPML

4. **Multi-location sans addon** — N emplacements dans le JSON-LD
   - Yoast Local = 79 EUR/an en supplement
   - Rank Math n'a pas d'equivalent

5. **AI integre via Claude** — titres, descriptions, keywords, alt-text vision
   - Une seule cle API, chiffree au repos
   - Yoast AI = uniquement Premium (99 EUR/an), pas de vision
   - Rank Math AI = credits limites

6. **Activity Log** avec detection d'acteur (web/ajax/rest/cron/cli)
   - Aucun concurrent n'a ca integre

7. **REST API CRUD complete** — chaque action du plugin est exposee
   - Yoast a une API partielle, Rank Math quasi rien

### Prix

| Plugin | Prix/an/site |
|--------|-------------|
| **Livada SEO** | **0 EUR** (GPL, tout inclus) |
| Yoast Premium | 99 EUR |
| Yoast Local (addon) | +79 EUR |
| Yoast + Local | 178 EUR |
| Rank Math PRO | 59 EUR |
| AIOSEO Pro | 99-299 EUR |
| SEOPress PRO | 49 EUR |

### Resume : matrice de parite

| Feature | Livada | Yoast Free | Yoast Premium | Rank Math Free | Rank Math PRO |
|---------|--------|------------|---------------|----------------|---------------|
| Meta tags | OK | OK | OK | OK | OK |
| XML Sitemap | OK | OK | OK | OK | OK |
| Google News Sitemap | OK | - | OK | - | OK |
| HTML Sitemap | OK | - | - | OK | OK |
| Schema Article/FAQ/HowTo | OK | OK | OK | OK | OK |
| Schema Product/Event/Recipe | OK | - | OK | - | OK |
| Multi-Location LocalBusiness | OK | - | 79 EUR/an | - | - |
| 12 sous-types LocalBusiness | OK | - | Partiel | OK | OK |
| Open Graph | OK | OK | OK | OK | OK |
| Redirections 301/302 | OK | - | OK | OK | OK |
| 404 Monitor | OK | - | - | OK | OK |
| Bulk Editor | OK | - | - | - | OK |
| Site Audit quotidien | OK | - | - | - | OK |
| 16 checks on-page | OK | OK | OK | OK | OK |
| Flesch readability | OK | OK | OK | - | OK |
| Hreflang | OK | Partiel | Partiel | Partiel | Partiel |
| TranslatePress hreflang | **OK** | - | - | - | - |
| AEO / llms.txt | **OK** | - | - | - | - |
| IndexNow | OK | OK | OK | OK | OK |
| AI suggestions | OK | - | OK | Limite | OK |
| AI alt-text (vision) | **OK** | - | - | - | - |
| WooCommerce schemas | OK | - | OK | OK | OK |
| MCP Server | **OK** | - | - | - | - |
| REST API complete | **OK** | Partiel | Partiel | - | - |
| WP-CLI complet | **OK** | Partiel | Partiel | - | - |
| Activity Log | **OK** | - | - | - | - |
| Import Yoast | OK | n/a | n/a | OK | OK |
| Import SEOPress | OK | - | - | - | - |
| OG Image auto-gen | OK | - | - | - | - |
| Onboarding wizard | OK | OK | OK | OK | OK |
| Link Graph interne | OK | - | - | - | OK |
| GSC keywords import | OK | - | - | - | OK |
| Self-hosted updater | OK | n/a | n/a | n/a | n/a |
| **Prix/an** | **0 EUR** | 0 EUR | 99 EUR | 0 EUR | 59 EUR |

---

## 8. Checklist de configuration rapide (copier-coller)

```
[ ] 1. Activer tous les modules (General Settings)
[ ] 2. Renseigner la cle API Anthropic (General Settings)
[ ] 3. Configurer le Business Type + tous les champs schema (Schema)
[ ] 4. Remplir les champs tourisme si applicable (etoiles, rooms, amenities)
[ ] 5. Ajouter les locations supplementaires si multi-site (Locations)
[ ] 6. Configurer les templates de titres (Titles)
[ ] 7. Remplir les profils sociaux (Social)
[ ] 8. Verifier les post types/taxonomies dans le sitemap (Sitemap)
[ ] 9. Configurer AEO : description org, expertise, founding date (AEO)
[ ] 10. Configurer GEO : auteur expertise + speakable (GEO auto)
[ ] 11. Ajouter les IDs analytics (GA4/Matomo/Clarity)
[ ] 12. Lancer le premier Site Audit (Site Audit)
[ ] 13. Parcourir les images sans alt-text (Image SEO bulk)
[ ] 14. Verifier le robots.txt (Robots)
[ ] 15. Configurer hreflang si multilingue (auto-detecte)
[ ] 16. Si migration : importer depuis Yoast/SEOPress (Tools)
```

---

## 9. Compatibilite

- **Elementor / JetEngine / ElementsKit** : OK. L'analyseur rend le contenu Elementor (y compris HTML widgets via `_elementor_data`). Le sitemap auto-exclut les CPT template.
- **WooCommerce** : OK. Schemas Product auto-emis.
- **TranslatePress / Polylang / WPML** : OK. Hreflang natif.
- **Plugins de cache** (LiteSpeed, FlyingPress, LWS Optimize, WP Super Cache) : OK. Les sitemaps definissent `DONOTCACHEPAGE`. Le 404 monitor a un throttle object-cache (60s/path).
- **Conflit SEO** : le plugin detecte et avertit si Yoast/Rank Math/AIOSEO/SEOPress est actif en meme temps. Un seul plugin SEO doit tourner en production.

---

## 10. Desinstallation propre

`uninstall.php` supprime tout :
- Option `livada_seo_settings` + `livada_seo_locations`
- Tous les post meta `_livada_seo_*`
- Tables `livada_seo_redirects`, `livada_seo_404_log`, `livada_seo_activity_log`
- Tous les transients `livada_seo_*`
- Cron hooks
- Object cache flush

Aucune trace residuelle apres suppression.
