# BOUCLE-DESIGN.md - Boucle autonome de copie pixel-perfect des templates (Ketamyn)

> Calquée sur `../BOUCLE-DEV.md` (boucle de Max), mais **dédiée à la banque de templates**.
> À chaque réveil : livre **UN template complet et vérifié** (desktop + mobile), puis laisse le
> prochain réveil enchaîner. **Périmètre STRICT : `templates/` uniquement. Ne JAMAIS toucher `src/`**
> (c'est le moteur de Max). Commits signés **[Ulysse]**. Modèle : **Opus 4.8**.

## Auth (le Claude headless n'a PAS l'outil Figma interactif)
- Le pipeline utilise l'**API REST Figma** via `FIGMA_TOKEN` (variable utilisateur Windows, cf `_pipeline/obtenir-cle-figma.bat`). C'est ce qui rend la boucle possible sans session interactive.
- Le Claude headless a besoin de `CLAUDE_CODE_OAUTH_TOKEN` (abonnement, pas de facturation API). Sans lui : logger « AUTH MANQUANTE » et sauter.
- Lancer les scripts Python avec `FIGMA_TOKEN` injecté + `PYTHONIOENCODING=utf-8` (sinon crash console cp1252).

## Une itération = ces étapes, dans l'ordre

1. **Se synchroniser** : `cd ulysse && git pull --rebase`. Lire `COORDINATION.md` (ce que fait Max), `templates/PROGRESS.md`, `templates/_pipeline/queue.json`.
2. **Choisir LE prochain template** : la 1re entrée `status:"todo"` de `queue.json` (plus petit `seq`). On suit l'ordre des kits.
3. **Déclarer** dans `COORDINATION.md` (ligne EN COURS « Ulysse » → `templates/<slug>`), commit + push immédiat (`coord: <slug> en cours [Ulysse]`).
4. **Récupérer le design-pack** : `python _pipeline/figma_pack.py <seq>` → crée `templates/<folder>/ref/` (`desktop.png`, `mobile.png` = **cibles**, `nodes.json` = texte/couleurs/géométrie/fills) + `images/fill-*.png` (**photos brutes**).
5. **Reproduire au pixel** (un seul `index.html` autonome par template) :
   - **Lire la cible** `ref/desktop.png` et `ref/mobile.png` (à l'œil) **+** `ref/nodes.json` (valeurs exactes : textes, couleurs hex, polices, tailles, positions, rayons).
   - **Desktop ET mobile pixel-perfect.** Si le kit a une frame mobile dédiée (dans `queue.json`, `mobile != null`), la reproduire à l'identique ; sinon adaptation responsive propre.
   - **Photos = BRUTES + masque CSS** (jamais de détourage/PNG pré-masqué) : photo rectangulaire (issue de `images/fill-*`, renommée/optimisée en `.jpg`/`.png`) dans un conteneur masqué CSS (`mask-image` pour une forme libre, `border-radius:50%`+`object-fit:cover` pour un cercle). Calage : détecter un repère dans la photo brute et la cible, OU recherche PIL de la position (diff dans la zone masquée). Le client doit pouvoir remplacer la photo.
   - **Textes traduits en FR** (vrais contenus métier cohérents, jamais de lorem). **Garder les illustrations/mockups** du template (exports PNG OK, ce ne sont pas des photos).
   - **ACCENTS OBLIGATOIRES** (é è ê à â ç ù ô î ë œ...) : ne JAMAIS écrire le français sans accents (« Découvrez » et pas « Decouvrez », « créer » pas « creer », « données » pas « donnees »). Le garde-fou `verify.py` BLOQUE tout texte FR non accentué.
   - Polices Google équivalentes, couleurs/espacements exacts des `nodes.json`. Sections à fond coloré = pleine largeur sans bandes blanches ni déformation.
   - En tête du fichier : commentaire de **crédit en source uniquement** (« Reproduction du template Figma d'Ulysse Ruez, Community »), **jamais visible** côté client. **Aucune mention d'IA.**
6. **Vérifier** (méthode Playwright, fiable - le headless `--screenshot` plafonne à ~482px en mobile, NE PAS s'y fier) :
   - **GATE OBLIGATOIRE** : `python _pipeline/verify.py templates/<folder>` DOIT afficher `VERDICT: OK` (exit 0). Il bloque automatiquement : débordement horizontal, **em-dash (interdit PARTOUT, même dans les commentaires : utiliser `-` ou `:`)**, mention d'IA, `lang` != fr. Tant que ce n'est pas OK, **on NE committe PAS** : corriger et relancer.
   - Regarder les comparaisons générées `_work/cmp-desktop.png` et `_work/cmp-mobile.png` (Figma à gauche, repro à droite) et **itérer** jusqu'à correspondance fidèle.
   - Relire le **français** (accents + grammaire : « vos » pas « vous », etc.).
7. **Finaliser** : optimiser les images, puis `python _pipeline/apercu.py templates/<folder>` qui génère les **aperçus versionnés** (rendus du template copié, vus sur GitHub) : `apercu-desktop.png` (PC, réduit 720px) **+** `apercu-mobile/mobile-NN.png` (mobile 393px tranché). Supprimer les `_work/` temporaires. (`ref/` reste en local, gitignoré.)
8. **Marquer fait** : `status:"done"` + `folder` dans `queue.json`, recalculer le compteur (`python _pipeline/prepare_queue.py` ou maj directe), maj `PROGRESS.md` (X/350).
9. **Livrer** : `git pull --rebase` + commit `templates: <slug> « <nom> » pixel-perfect desktop+mobile [N/350] [Ulysse]` + push.
10. **Déployer + tester en ligne** (comme Max ne se contente pas de git) : pousser sur le VPS de façon **statique et légère** (`ssh vps-ulysse "cd /opt/ulysse && git pull --ff-only"`) - **PAS** le `deploy.sh` complet de Max (build+migrate+restart de son app = risque pour ketamyn.fr en prod). Les templates sont servis en statique par un bloc Caddy dédié (path/sous-domaine showroom, à mettre en place 1 fois). **Tester** : `curl -sI <url_live>/<slug>/` doit répondre 200. **Noter l'URL live** du template (dans `PROGRESS.md` + `COORDINATION.md`). Si le VPS n'est pas accessible (clé SSH absente / Caddy showroom pas encore en place), logger « VPS non configuré » et continuer en git-only (le déploiement s'activera tout seul une fois l'accès en place).
11. Passer la ligne `COORDINATION.md` EN COURS au template suivant (ou TERMINÉ), commit + push.

## Portes qualité (non négociables)
- Desktop **et** mobile correspondent à la cible Figma (vérif Playwright côte à côte).
- **Aucune photo cuite/détourée** : toujours photo brute + masque CSS (remplaçable au CMS).
- Aucun débordement horizontal. FR correct (accents), **pas d'em-dash**, aucune mention d'IA.
- Un template = livrable **complet et vérifié** (jamais de demi-template laissé en plan).

## Garde-fous
- **`templates/` uniquement.** Ne jamais éditer `src/` ni les fichiers du moteur de Max.
- `git pull --rebase` avant tout push ; jamais `--force` ; commits signés **[Ulysse]**.
- Ne pas versionner `**/ref/` ni `**/images/fill-*` (cf `.gitignore`) : lourdes captures/intermédiaires.
- Si un template ne converge pas en ~quelques essais → le noter `status:"bloque"` dans `queue.json` (raison), passer au suivant, signaler dans `COORDINATION.md`.

## Relance 24/7 (Windows, hors repo)
Tâche planifiée `Ketamyn-Design-Loop` → `C:\Users\ulyss\ketamyn-loop\boucle-design.ps1` toutes les 30 min : un Claude **headless** (`claude -p ... --dangerously-skip-permissions --model opus`) fait UNE itération de ce protocole. Verrou anti-chevauchement. Log : `...\ketamyn-loop\design-loop.log`.

## État vivant
Source de vérité de l'avancement : `templates/_pipeline/queue.json` (statuts) + `templates/PROGRESS.md` + `COORDINATION.md`.