Plan — Finalisation du wizard « boutique clé en main »

Objectif : depuis le seul onboarding, livrer une boutique Shopify prête à vendre à +90 % de façon autonome, et faire passer le marchand sur les derniers % obligatoirement humains via une expérience guidée, auto-détectée, sans friction ni erreur.

Statut : phases 1 et 2 livrées (août 2026), et non « plan à valider (aucun code écrit) » comme cette page l'a annoncé longtemps après coup : le re-cadrage du §3 est appliqué (29 jalons, 13 auto, 16 human), le champ guide, la passe de sondes de launch-tick et le rendu guidé du cockpit existent, et 13 exécuteurs sont câblés. Ce qui n'a PAS suivi le plan : markets, shipping, tax, consent, search et le branding checkout ne sont pas devenus des exécuteurs, ce sont des checkpoints humains guidés. Décisions de périmètre du §3 et du §10 : tranchées.

1. Périmètre (validé)

Le wizard prépare la boutique elle-même. Tout ce qui est post-lancement et continu (emails marketing, publicité, suivi/analytics) est géré ailleurs par la plateforme et ses agents (Maya, Faye…), pas par le wizard turnkey.

2. État actuel (sur quoi on construit)

Tout le socle d'exécution autonome existe déjà et fonctionne :

• Playbook typé — src/features/ai/chat/runtime/_wizard/launch-playbook.ts : 29 jalons (13 auto + 16 human) en 9 sections, chacun avec id / section / agent / kind / summary / skill / dependsOn (DAG).
• Contrat d'exécuteur — wizard-skills/types.ts : SkillExecutor = (ctx) => Promise<{summary, details?}>. ctx porte shopifyAccessToken (déjà déchiffré + auto-rafraîchi), shopDomain, apiVersion, spec (onboarding), brandKit. On throw en cas d'échec.
• Registre — wizard-skills/registry.ts : map skill → exécuteur. 13 exécuteurs câblés (thème, produits, collections, pages, menu, blog, légal, meta SEO, JSON-LD, pricing, accessibilité, webhooks, surfaces de crawl) : un par jalon auto, aucun jalon auto sans exécuteur. En ajouter un = déposer un fichier + l'enregistrer. C'est tout.
• Runner partagé — wizard-skills/run-milestone.ts : cycle de vie queued → running → done/failed, claim atomique anti-double-exécution, retries exponentiels (max 5, backoff stampé), refus des jalons humains, statut not_implemented pour les skills non câblés.
• Cron launch-tick : parcourt le DAG, dispatche les jalons prêts, re-queue les failed/running périmés. Détecte déjà l'acceptation du transfert de boutique en sondant shop.json (modèle réutilisable pour l'auto-détection des étapes humaines : cf. §5).
• Plomberie Shopify — wizard-skills/shopify-admin.ts : adminRest / adminGraphql (retry 429/5xx + throttling GraphQL), assertNoUserErrors, upsertShopifyPage (idempotent), stripHtmlFences, assertUsableDraft, localeDirective.
• Cockpit — GET /api/wizard/store/launch (fusionne playbook + activité, calcule statut + %), POST /skill/run (relancer un jalon), POST /store/checkpoint (approuver un jalon humain, gaté sur dependsOn), et l'UI launch-checklist.tsx (panneau flottant, polling 20 s, boutons Run/Retry/Approve).

Conclusion : il ne reste pas à inventer un moteur, il reste à (a) re-cadrer le playbook, (b) écrire les exécuteurs manquants réalisables par API, et (c) transformer les approbations « à l'aveugle » en étapes guidées auto-détectées.

3. Re-cadrage du playbook (décision à valider)

→ Le wizard passe d'un playbook « ambitieux mais en partie infaisable » à un playbook honnête : chaque jalon auto est réellement faisable par API, et chaque jalon irréductiblement humain devient une étape guidée.

4. Les trois paniers

Panier A — automatisable par API Admin (→ écrire l'exécuteur)

Réutilise adminGraphql/adminRest + themeFilesUpsert. Chaque exécuteur : idempotent (lookup-then-write ou clé stable), throw en cas d'échec (le runner gère retry/backoff), et tag/marqueur boostecom-* quand pertinent.

Panier B — uniquement par automatisation navigateur (Browserbase) : à éviter

Réglages sans API publique (certains comportements checkout/comptes, overrides fiscaux fins). Plus lents, fragiles (cassent si l'UI Shopify change). Recommandation : ne PAS en mettre dans le chemin critique. Si vraiment nécessaire un jour, derrière garde-fous stricts. Par défaut → on les bascule en humain guidé (Panier C).

Panier C — obligatoirement humain (→ étape guidée auto-détectée)

Shopify interdit au custom app de faire ces actions (sécurité/légal). On ne les automatise pas : on les rend les plus simples possibles.

5. Grande amélioration UX — l'« étape guidée auto-détectée »

Aujourd'hui, un jalon humain = un bouton « Approve » à l'aveugle (pas d'instruction, pas de lien, pas de vérification). C'est le principal manque pour une expérience « clé en main ». Proposition :

1. Métadonnée guide sur les jalons humains (dans launch-playbook.ts, via extension du type LaunchMilestone) :
   guide?: {
     instructions: string        // « Active Shopify Payments pour encaisser »
     deepLinkPath: string         // « /admin/settings/payments » → URL construite depuis shopDomain
     docHref?: string             // aide BoostEcom
     detect?: string              // id d'une sonde (probe) d'auto-détection
   }
   

2. Liens directs : le cockpit construit https://{shopDomain}/admin/... → un clic ouvre exactement le bon écran Shopify. Zéro recherche.
3. Auto-détection : extension de launch-tick avec une passe de sondes (réutilise le pattern shop.json existant). Quand la sonde confirme (paiement actif, domaine branché, app installée, mot de passe retiré), la ligne passe pending → approved automatiquement — le marchand n'a même pas à cliquer « Approve ». Fallback : bouton manuel « J'ai fait ça » s'il refuse l'auto-détection.
4. Jamais bloquant : une étape humaine en attente n'arrête aucune étape auto (déjà le cas via le DAG).

6. Changements moteur nécessaires (chiffrage des fichiers)

7. Score « prête à vendre à X % »

Aujourd'hui le % = autoDone / auto. Après re-cadrage, on définit un score de mise en vente lisible pour le marchand :

• Dénominateur = jalons de store-readiness (Paniers A + C).
• « Prête à vendre » = thème + ≥1 produit publiable + pages + légal + livraison + marchés + (paiement, domaine, publication = les 3 finaux humains).
• Le cockpit affiche « Votre boutique est prête à 92 %, il reste : activer le paiement, connecter le domaine, publier ». Clair, motivant, honnête.

8. Plan de livraison (phases)

1. Phase 1 — Re-cadrage + socle guidé (faible risque, gros impact UX) : appliquer §3, ajouter le champ guide, l'auto-détection dans launch-tick, le rendu guidé dans le cockpit, le score §7. Livrable : le dernier 10 % devient une expérience guidée propre, même avant d'écrire les exécuteurs.
2. Phase 2 — Exécuteurs Panier A « sûrs » : markets, shipping (forfait + seuil gratuit), webhook-wiring, crawl-surface-builder, accessibility-audit. APIs solides, fort gain sur le %.
3. Phase 3 — Panier A « à confirmer » : tax (side-effect markets), checkout-branding (selon gating Plus), consent-native, search-configurator (si l'API metaobject tient la route).
4. Phase 4 — Polish : doc, tests, télémétrie du score, messages d'aide.

Chaque phase = livrable autonome, testé (typecheck + next build + tests), poussé pour validation. Une seule fonctionnalité par PR.

9. Garde-fous (principes non négociables)

• Idempotent : tout exécuteur re-jouable sans doublon (lookup-then-write).
• Fail-soft : un jalon qui échoue n'arrête jamais les autres (DAG + retries déjà en place).
• Honnête : on ne promet jamais d'automatiser ce que Shopify interdit ; c'est une étape guidée, clairement étiquetée.
• Vérif API au build : avant d'écrire chaque exécuteur Panier A, valider la mutation exacte + le gating de plan via @shopify/dev-mcp (zéro erreur en prod). Les cases « à confirmer » du §4 sont marquées comme telles.
• Token boundary : jamais la colonne chiffrée brute, toujours ctx.shopifyAccessToken (déjà résolu par le runner).

10. Points à valider avant de coder

1. Re-cadrage §3 : OK pour retirer emails + pixels/analytics + créative pub du wizard, et reclasser les installs d'apps en étapes guidées ?
2. Consentement RGPD : on garde une version native minimale dans le wizard (recommandé, car nécessaire pour vendre en UE) ?
3. Avis clients (reviews) : étape guidée dans le wizard, ou totalement hors wizard ?
4. Ordre : on démarre par la Phase 1 (socle guidé + re-cadrage, gros impact, faible risque), recommandé ?