# Onboarding Wizard — Implementation Plan

**Status**: Planned (à coder dans session dédiée 1-2 jours focus)
**Priority**: P0 (bloquant pour lancement Phase 1)
**Target version**: Livada SEO 1.10.0

---

## 1. Pourquoi cet onboarding wizard

> *"Time-to-Value 2 min — wow moment avant que l'user referme l'onglet."*

À la première activation du plugin, l'utilisateur arrive sur le dashboard et doit deviner où configurer quoi. **80% abandonnent dans les 5 premières minutes**. Yoast/Rank Math/AIOSEO ont tous un wizard 6-8 étapes — c'est la norme du marché.

**Conversion attendue avec wizard correct** : +35-50% sur le passage trial→paid (selon SaaS data industry SEO/marketing).

---

## 2. Principes UX

1. **Pré-rempli au max** : tout ce qui peut être deviné depuis le site (locale, titre, description home, schema_type) est rempli automatiquement avec confirmation utilisateur.
2. **6 étapes maximum** : au-delà, drop-off > 60%.
3. **Skippable** : bouton "Skip" sur chaque étape (mais discret), bouton "Skip wizard" visible globalement → renvoie sur dashboard normal.
4. **Progress bar visible** : "Étape 3 / 6 — Schema markup"
5. **Mobile-friendly** : 30% des admins WP sont sur mobile/tablette.
6. **AEO mis en valeur** : c'est notre différenciateur, ne pas le cacher en étape 7.
7. **Wow moment final** : à la fin, montrer un preview SERP optimisé + un preview schéma validé. **Tangible, pas abstrait.**

---

## 3. Architecture technique

### Fichiers à créer

```
includes/
├── admin/
│   └── class-onboarding-wizard.php          ← Logique principale, AJAX handlers, etat
│   └── views/
│       └── onboarding/
│           ├── wizard-shell.php             ← HTML shell (modal/fullscreen)
│           ├── step-1-welcome.php           ← Welcome + détection site type
│           ├── step-2-site-info.php         ← Locale + Site name + Schema type
│           ├── step-3-schema.php            ← LocalBusiness fields (adaptatif selon type)
│           ├── step-4-aeo.php               ← AEO native (llms.txt + AI markers) toggle + explain
│           ├── step-5-ai.php                ← Anthropic API key + preview AI generation
│           ├── step-6-celebrate.php         ← Wow moment + SERP preview + next-step CTAs
└── assets/
    ├── css/
    │   └── onboarding-wizard.css            ← Style premium gradient indigo→violet
    └── js/
        └── onboarding-wizard.js             ← Steps navigation + AJAX save + live preview
```

### Hooks WordPress

- `Livada_SEO_Onboarding::detect_first_activation()` sur `admin_init` → si `livada_seo_settings['onboarding_completed'] !== true` ET pas en cours `?page=livada-seo-onboarding`, redirect vers wizard
- `Livada_SEO_Onboarding::render_wizard()` sur `admin_menu` (page hidden : pas dans le menu)
- AJAX handlers : `wp_ajax_livada_seo_onboarding_save_step`, `wp_ajax_livada_seo_onboarding_skip`, `wp_ajax_livada_seo_onboarding_complete`

### État sauvegardé

Option `livada_seo_onboarding` (array) :
```php
[
    'current_step' => 1..6,
    'started_at' => timestamp,
    'completed_at' => null | timestamp,
    'skipped' => bool,
    'steps_data' => [ /* données soumises par étape */ ]
]
```

À la fin (`completed_at` set), `livada_seo_settings['onboarding_completed'] = true` → plus jamais affiché.

---

## 4. Les 6 étapes — détail UX

### Étape 1 — Welcome & Détection automatique

**Header** : "Bienvenue dans Livada SEO."
**Tagline** : "Be found by Google. And by AI."

**Body** :
- Logo Livada centré, gradient
- Sous-titre : "Configurons ton site en 2 minutes. Je devine déjà l'essentiel."

**Auto-détection** (affichée comme cadeau, modifiable) :
- Locale : `get_locale()` → "Français (France)"
- Type de site détecté heuristique : si home contient mots-clés "hôtel" "camping" "restaurant" "spa" → suggère LocalBusiness/Restaurant/Campground/etc.
- Multi-location détecté : si TranslatePress/Polylang/WPML actif → propose schemas multi-loc
- Stack détectée : Elementor / Jet / WooCommerce — affiche petites icônes "Compatible ✓"

**CTA** : "Continuer →" (gros bouton primary)

**Skip** : "Skip wizard" en lien discret bottom-right

---

### Étape 2 — Infos du site

**Header** : "Comment Google voit ton site"

**Fields** :
- `Nom du site` (pré-rempli `get_bloginfo('name')`)
- `Tagline` (pré-rempli `get_bloginfo('description')`)
- `Logo` (drag-drop ou bouton WP Media Library — pré-rempli si custom_logo défini)
- `Langue principale` (pré-rempli `get_locale()`)
- `Séparateur titres` (radio : `|`, `—`, `·`, `›`)
- `Type d'établissement principal` (select adaptatif) :
  - Site éditorial / blog
  - Boutique e-commerce (WooCommerce)
  - **Hôtel / Hébergement** (LodgingBusiness)
  - **Camping / Camping-car** (Campground)
  - **Spa / Bien-être** (HealthAndBeautyBusiness)
  - **Restaurant / Café / Bar** (FoodEstablishment)
  - Service local (LocalBusiness)
  - Organisation / Association (Organization)
  - Autre — préciser

**Live preview** à droite : titre SERP qui se met à jour en live selon les choix.

**CTA** : "Continuer →"

---

### Étape 3 — Schema LocalBusiness (adaptatif)

**Header** : "Aide Google à comprendre ton activité"

**Affiché conditionnellement selon Étape 2 type** :

Si type = LocalBusiness/Hotel/Restaurant/Campground/Spa :
- Adresse complète (street, city, postal, country)
- Téléphone
- Email contact
- Horaires (compact, 7 toggles jour avec hours)
- Prix range (radio $, $$, $$$, $$$$)
- Coordonnées GPS (auto-géocode via Nominatim free API si vide)
- Photos (option upload max 3, sert pour `image` du LocalBusiness schema)

Si type = e-commerce :
- "Tes produits WooCommerce sont auto-détectés. Configure le schema Product/Offer plus tard dans les Settings."

Si type = éditorial :
- "Pas besoin de LocalBusiness. On configure Person/Organization à la place."

**Multi-location** : si TP/Polylang/WPML détecté ET type local-friendly → toggle "J'ai plusieurs établissements" → bouton "+Ajouter une location" (limit 3 ici, plus dans settings après).

**CTA** : "Continuer →" + "Skip cette étape" (discret)

---

### Étape 4 — AEO (Answer Engine Optimization) ⭐ DIFFÉRENCIATEUR

**Header** : "Sois trouvé par ChatGPT, Perplexity et AI Overviews"

**Body explicatif** :
> "En 2026, 30% des recherches passent par des IA (ChatGPT, Perplexity, Google AI). Yoast et Rank Math ne sont pas prêts. Livada SEO l'est."

**Toggles** (tous ON par défaut, expliqués) :
- ☑ **Servir `/llms.txt`** : *"Index spécial pour les LLMs. Comme un sitemap.xml mais pour les IA."*
- ☑ **Servir `/llms-full.txt`** : *"Version complète de ton contenu pour entraînement/citation par les IA."*
- ☑ **AI content markers HTML** : *"Marqueurs invisibles qui aident les IA à extraire ton contenu correctement."*
- ☑ **Schema Speakable** : *"Pour les assistants vocaux et IA. Tes infos importantes accessibles oral."*
- ☑ **Person/Author E-A-T schema** : *"Crédibilité auteur pour Google E-A-T et IA."*

**Preview** : "Voici à quoi ressemblera ton `/llms.txt`" → snippet de code généré live.

**CTA** : "Continuer →"

---

### Étape 5 — AI Claude integration (optionnel)

**Header** : "Génère titres, descriptions et alt-text avec Claude"

**Body** :
> "Connecte ta clé API Anthropic pour activer la génération AI : titres SEO, méta-descriptions, mots-clés, et alt-text d'images (vision Claude) en 1 clic."

**Field** :
- `Clé API Anthropic` (password input + lien "Comment obtenir une clé ?" → tuto)
- Bouton "Tester la clé" → ping API, retour vert/rouge

**Si clé valide** :
- Affiche preview AI : "Voici une suggestion de title pour ta home" — appel API Claude live avec le contenu de la home → affichage du résultat.
- ⭐ **Wow moment** — l'utilisateur voit que ça marche en LIVE.

**CTA** : "Continuer →" + "Skip (configurer plus tard)" (pas tout le monde a une clé Anthropic prête)

---

### Étape 6 — Célébration + next steps

**Header** : "Bravo ! Ton site est prêt pour l'ère AI." 🎉

**Wow blocks** (3 cartes côte à côte) :

**Carte 1 — Preview SERP optimisé** :
- Affiche un mock Google SERP avec le titre et meta description optimisés du site
- Badge "Schema validé ✓"

**Carte 2 — Préparation AI confirmée** :
- "/llms.txt actif" (lien cliquable → ouvre l'URL réelle)
- "Speakable schema actif"
- "AI markers actifs"

**Carte 3 — Prochaines actions** (3 CTAs) :
- "📝 Optimiser un article" → ouvre le bulk editor
- "🔗 Mes redirections" → ouvre redirects
- "🎁 Activer ma licence" → ouvre licence page (avec promo "30j trial actif jusqu'au [date]")

**Footer** :
- "Une question ? Écris-moi : florin@livada.fr — je réponds en 24h."
- Newsletter signup : "Reçois mes tips AEO chaque semaine"

**CTA principal** : "🎯 Aller au tableau de bord" → quitte wizard, marque `onboarding_completed`

---

## 5. Visual design — guidelines

### Couleurs

- Primary gradient : `linear-gradient(135deg, #6366F1, #8B5CF6)` (indigo→violet)
- Background wizard : `#FFFFFF` (light mode), `#0F1014` (dark mode)
- Accent positif : `#10B981` (vert)
- Accent attention : `#F59E0B` (orange)
- Text primary : `#0F172A`
- Text secondary : `#475569`

### Typography

- Font : `Inter, system-ui, sans-serif`
- H1 : 32px / 700 weight
- H2 : 24px / 600 weight
- Body : 16px / 400 weight
- Small : 14px / 400 weight

### Composants

- Boutons primaires : padding 12px 24px, border-radius 8px, gradient
- Boutons secondaires : padding 12px 24px, border-radius 8px, border #6366F1
- Inputs : padding 10px, border #E2E8F0, focus border #6366F1, border-radius 6px
- Cards : background #F8FAFC, border-radius 12px, padding 24px

### Animations

- Step transitions : slide-in left 250ms ease-out
- Progress bar : transition 400ms ease-in-out
- Success states : confetti burst 1s (utiliser canvas-confetti.js minified ~3KB)

---

## 6. Détection heuristique du type de site

Algorithme pour pré-sélectionner le `schema_type` en Étape 2 :

```php
private static function detect_site_type(): string {
    $home_url = home_url();
    $home_content = wp_remote_get( $home_url, [ 'timeout' => 5 ] );
    $body = is_wp_error($home_content) ? '' : strtolower(wp_remote_retrieve_body($home_content));
    
    $site_name = strtolower( get_bloginfo('name') . ' ' . get_bloginfo('description') );
    $signal = $body . ' ' . $site_name;
    
    $matchers = [
        'Restaurant'           => ['restaurant', 'menu du jour', 'réservation table', 'gastronomie', 'cuisine'],
        'CafeOrCoffeeShop'     => ['café', 'coffee shop', 'salon de thé'],
        'BarOrPub'             => ['bar', 'pub', 'cocktail', 'apéro'],
        'Hotel'                => ['hôtel', 'hotel', 'chambre', 'suite', 'réservation chambre'],
        'BedAndBreakfast'      => ['chambre d\'hôtes', 'gîte', 'b&b', 'bed and breakfast'],
        'Campground'           => ['camping', 'emplacement', 'mobilhome', 'tente'],
        'Resort'               => ['resort', 'all inclusive', 'pension complète'],
        'HealthAndBeautyBusiness' => ['spa', 'massage', 'bien-être', 'esthétique', 'sauna'],
        'Store'                => ['boutique', 'magasin', 'shop'],
        'LocalBusiness'        => ['service', 'artisan', 'professionnel', 'devis'],
    ];
    
    if ( class_exists('WooCommerce') ) return 'Store';
    
    $scores = [];
    foreach ( $matchers as $type => $keywords ) {
        $score = 0;
        foreach ( $keywords as $kw ) {
            if ( strpos( $signal, $kw ) !== false ) $score += 1;
        }
        if ( $score > 0 ) $scores[ $type ] = $score;
    }
    
    if ( empty($scores) ) return 'LocalBusiness'; // default safe
    arsort( $scores );
    return array_key_first( $scores );
}
```

---

## 7. Étapes d'implémentation (ordre)

### Sprint 1 — Squelette + Étape 1 (1 jour)
1. Créer `class-onboarding-wizard.php` avec init, detect_first_activation, render_wizard
2. Créer `wizard-shell.php` avec progress bar + navigation
3. Créer `onboarding-wizard.css` + `onboarding-wizard.js` (squelette)
4. Étape 1 (Welcome + détection) fonctionnelle
5. Test : nouveau site dev, désactiver/réactiver plugin → wizard apparaît

### Sprint 2 — Étapes 2, 3, 4 (1 jour)
1. Étape 2 (site info + live SERP preview)
2. Étape 3 (schema LocalBusiness adaptatif selon type) + intégration Nominatim
3. Étape 4 (AEO toggles + explication + preview llms.txt)

### Sprint 3 — Étapes 5, 6 + polish (1 jour)
1. Étape 5 (Anthropic key + test API + preview generation)
2. Étape 6 (célébration + 3 wow cards + CTAs)
3. Animations + transitions
4. Tests UX sur 3 navigateurs + mobile

### Sprint 4 — QA + edge cases (0.5 jour)
1. Test : utilisateur skip à chaque étape → comportement OK
2. Test : utilisateur abandonne mi-wizard (ferme onglet) → état préservé
3. Test : utilisateur clic "Skip wizard" → marque `onboarding_completed=true` mais avec `skipped=true`
4. Test : utilisateur réinstalle plugin → onboarding ne re-apparaît PAS (sauf si option `livada_seo_force_onboarding` true via WP-CLI)
5. Test : multi-site WP → wizard sur chaque sous-site indépendant

---

## 8. Tracking & analytics

À chaque step submitted, log dans `livada_seo_activity_log` :
- `onboarding_step_completed` : `{ step, time_spent_seconds, data_submitted_keys }`

À fin :
- `onboarding_completed` : `{ total_time_seconds, skipped_steps }`
- `onboarding_skipped` : si bouton skip global cliqué

Sert à mesurer le **drop-off par étape** plus tard et identifier les frictions.

---

## 9. Risques + edge cases

| Risque | Mitigation |
|---|---|
| User a déjà configuré le plugin manuellement | Détecter `livada_seo_settings` non-default → afficher "Tu sembles déjà configuré, veux-tu quand même refaire le wizard ?" |
| Wizard cassé par un plugin tiers (Gravity Forms, etc.) | Encadrer toute la sortie dans `try/catch`, fallback gracieux vers dashboard normal |
| API Anthropic indisponible Étape 5 | Permettre skip avec message "Tu pourras connecter ta clé plus tard dans Settings → AI" |
| Géocodage Nominatim échoue | Permettre saisie manuelle des coords GPS |
| Multi-site WP | Stocker `livada_seo_onboarding` en option per-blog (pas network) |
| Locale non FR | Toutes les chaînes via `__()` avec text-domain `livada-seo` |

---

## 10. Quand exécuter ce plan

**Pré-requis** :
- Session focus dev de 2-3 jours
- Plugin en état stable (1.9.6 ou 1.9.7 livré sur les 4 sites prod)
- Mockups visuels validés (optionnel mais accélère)

**Trigger pour démarrer** :
- User dit : "on attaque l'onboarding wizard" / "on code le wizard" / "Sprint Phase 1 onboarding"
- Ou démarrage Phase 1 du LAUNCH-PLAN (J-60 du lancement)

**Livraison** :
- Version 1.10.0 du plugin
- Tag git `v1.10.0-onboarding`
- Update info.json + CHANGELOG.md
- Mise à jour des 4 sites prod (install manuelle ou auto-update si 1.9.6 déjà déployée)

---

*Document vivant. À mettre à jour si UX/spec change.*

**Owner** : Florin Livada
**Estimated effort** : 2-3 jours focus
**Priority** : P0 — bloquant pour Phase 1 du lancement
