ki-fwi/ANALYSE-et-PLAN_ki-fwi.md

# KI FWI SA YÉ ? — Analyse du pack, décisions d'architecture et plan de sessions

> Document destiné à l'humain (toi). Le fichier `BRIEF-CLAUDE-CODE_ki-fwi.md` est le prompt à coller
> dans Claude Code. `fruits.seed.json` est le jeu de données d'amorçage.
>
> Contexte : ORGANISATION KA INTERNATIONALE · Martinique/Guadeloupe · doctrine souveraineté numérique
> (playbook unifié OKI × SvelteKit, juillet 2026).

---

## 1. Ce que vaut le pack `pack_complet_game_fruit`

**Ce qui est bon et à garder :**

- La **taxonomie d'assets en 4 vues** (arbre · fruit entier · coupe · feuille) est exactement la bonne
  découpe pédagogique. C'est le meilleur apport du document : elle correspond aux quatre indices que
  l'on apprend réellement à lire sur le terrain.
- Le **prompt négatif universel** est réutilisable tel quel.
- L'**automatisation par l'API HTTP de ComfyUI** (`POST /prompt`) est la bonne méthode, et elle est
  compatible avec la doctrine : la génération est une opération **hors ligne, au build**, jamais au
  runtime. Aucun appel tiers ne subsiste dans le jeu livré (P2 du playbook : *bake au build*).

**Ce qui est faux, risqué ou manquant — par ordre de gravité :**

### 1.1 La contradiction pédagogique centrale (bloquant)

Le but est que des enfants **reconnaissent des fruits et des arbres réels**. Un jeu dont 100 % des
visuels sont générés par IA leur apprend à reconnaître les hallucinations d'un modèle de diffusion.
Le problème est concret : SDXL et FLUX connaissent mal le corossol, à peine la quenette, presque pas
le zikak, la pomme-liane ou le cachiman cœur-de-bœuf. Sur les espèces peu représentées dans les jeux
d'entraînement, le modèle produit un fruit *plausible et faux*.

**Règle à graver dans le projet — deux filières d'assets, deux régimes :**

| Filière | Contenu | Source autorisée | Rôle |
|---|---|---|---|
| **A — Vérité** | photo de fruit, de coupe, de feuille, d'écorce, de port de l'arbre | **photographie réelle** (Commons, iNaturalist, herbier, ton propre appareil) | tout ce qui sert à **identifier** : épreuves, fiches, indices |
| **B — Décor** | fonds, personnages, UI, sprites arcade, badges, écrans de titre | IA (Krea2 / FLUX via ComfyUI) | tout ce qui **ne sert pas** à identifier |

Un sprite IA peut illustrer le mode arcade (fruits qui tombent), à condition qu'il soit **validé
contre au moins deux photos réelles** et que l'épreuve d'identification, elle, se joue toujours sur
la photo. Une photo prise par toi au marché de Fort-de-France vaut mieux que n'importe quel FLUX.

### 1.2 « Ressources libres de droit » : l'expression est fausse, et c'est un risque juridique réel

- **Wikimedia Commons** n'est pas « libre de droit ». La plupart des fichiers sont **CC BY-SA 4.0** :
  attribution nominative obligatoire + partage à l'identique. Le partage à l'identique contamine les
  œuvres dérivées — si tu composites une photo CC BY-SA dans un sprite, le sprite devient CC BY-SA.
- **TRAMIL** : les mentions légales du site n'accordent **aucune licence**. Par défaut : tous droits
  réservés. La TRAMILothèque (photos, scans, planches d'herbier, coupes microscopiques) est une
  ressource magnifique et **inutilisable sans autorisation écrite**. TRAMIL est hébergé par le SCD de
  l'Université des Antilles à Schœlcher — tu es à quinze minutes. **Va les voir.** Un partenariat
  TRAMIL × OKI sur un jeu scolaire martiniquais est une demande qui a toutes les chances d'aboutir,
  et il transforme le projet : accès à des images d'herbier vouchées, et une caution scientifique.
- **CIRAD / INRAE** : régimes mixtes, majoritairement © avec des cas d'usage pédagogique négociables.
  Agritrop (dépôt ouvert du CIRAD) contient de l'open access exploitable. À demander, pas à présumer.
- **iNaturalist** : beaucoup de CC BY-**NC**. Compatible avec un jeu gratuit et non commercial ;
  incompatible si tu veux un jour vendre une version. Décide maintenant.

→ **Décision à prendre avant la première ligne de code** : licence du code (AGPL-3.0 ou GPL-3.0),
licence du contenu (CC BY-SA 4.0 recommandé, cohérent avec Commons), et registre `CREDITS.md` +
métadonnée de licence **par média** dans les données, avec un écran de crédits dans le jeu.

### 1.3 Aucune boucle de validation botanique

Le pack génère 76 images et passe directement à la production. Il faut une **porte** : chaque asset
porte un champ `valide` qui vaut `false` par défaut, et rien d'invalidé n'est embarqué dans le build.
La validation se fait par comparaison à deux photos de référence, idéalement contresignée par
quelqu'un qui connaît (TRAMIL, un enseignant SVT, un agriculteur, ta grand-mère).

### 1.4 Un bug réel dans le script fourni

```python
workflow["4"]["inputs"]["seed"] = hash(fruit["id"] + asset_type) % 2**32
```

En Python 3, `hash()` sur une chaîne est **randomisé à chaque exécution** (`PYTHONHASHSEED`). Les
seeds ne sont donc pas reproductibles d'un lancement à l'autre — exactement l'inverse de l'argument
« même seed = même style » vendu dans le pack. Utiliser `zlib.crc32(s.encode()) & 0xFFFFFFFF` ou
`int(hashlib.sha256(s.encode()).hexdigest()[:8], 16)`.

Accessoirement : `json.loads(json.dumps(x))` → `copy.deepcopy(x)` ; et vérifier la licence du modèle
utilisé par `rembg` (les poids ne suivent pas toujours la licence MIT du paquet).

### 1.5 Le format de sortie est hostile au mobile 4G

80 PNG en 512×512 = plusieurs mégaoctets, hors budget du playbook (≤ 2 Mo pour l'entrée). Il faut :
AVIF/WebP, **atlas de textures** par écran de jeu, et chargement par paquet (un pack de fruits par
île, téléchargeable et mis en cache par le service worker).

### 1.6 Ce qui manque entièrement

- **Le son.** Un jeu qui enseigne les noms kréyòl sans les faire *entendre* rate sa cible : les
  enfants visés lisent mal le kréyòl écrit, dont l'orthographe leur est peu familière. Chaque fruit
  doit avoir son nom prononcé par une **voix humaine locale** (pas de TTS). C'est du terrain, pas du
  code : une après-midi d'enregistrement vaut dix heures de développement.
- **Le game design.** Le pack ne parle que d'assets. Il n'y a ni boucle de jeu, ni progression, ni
  mesure de l'apprentissage.
- **La sécurité.** Un jeu antillais sur les fruits qui ne parle pas du **mancenillier** est
  incomplet et, à la limite, irresponsable. Idem : akée non mûr, coque de pomme-cajou, graines de
  médicinier, laurier-jaune. Un module « **Pa touché** » transforme un jeu sympathique en outil que
  les écoles ont une raison d'installer.
- **La saisonnalité.** Savoir *quand* un fruit se trouve fait partie de la connaissance perdue,
  autant que le nom.

---

## 2. Décisions d'architecture

### 2.1 Phaser 5 n'existe pas

La branche courante est **Phaser 4** (4.0 « Caladan », avril 2026 ; 4.1 « Salusa » ; 4.2 « Giedi »),
avec un moteur WebGL réécrit et une architecture de *render nodes*. Cibler `phaser@^4`, vérifier la
dernière version publiée au démarrage (`npm view phaser version`), et **ne pas partir de Phaser 3**.

### 2.2 Phaser ne doit pas porter tout le jeu

Trois des cinq modes de jeu (QCV photo, indices progressifs, calendrier) sont des interfaces de
cartes et de boutons : Svelte + CSS les fait mieux, plus léger, plus accessible au clavier et au
lecteur d'écran. Phaser gagne sa place sur **une seule scène** : le jaden arcade, où il y a de la
physique, des particules et du *game feel*.

**Architecture retenue — hybride, à frontière stricte :**

```
Svelte 5 (coquille)          Phaser 4 (îlot)
├─ routes, i18n, SEO         └─ scène « Ranmasé » uniquement
├─ menus, HUD, album            · montée en import dynamique
├─ fiches encyclopédie          · dans (jeu)/ranmase, jamais au layout racine
├─ données, progression         · détruite au démontage (game.destroy(true))
└─ audio, réglages              · communique par événements, pas par état partagé
```

Conséquence sur les budgets : le shell reste **≤ 170 Ko JS** (règle du playbook, non négociable) ;
Phaser (~300–400 Ko gzip selon le build) n'est téléchargé **qu'à l'entrée dans la scène arcade**,
derrière un écran de chargement designé (P5). C'est un écart au budget, il doit être **documenté
comme tel** dans un ADR, pas subi.

### 2.3 WebGL : oui, mais borné

Phaser en mode `AUTO` (WebGL avec repli canvas), `resolution`/DPR plafonné à **1.5**,
`powerPreference: 'low-power'`, cible **30 fps stables sur Mali-G52**. Aucun WebGL ailleurs dans le
site. Le miroir DOM sémantique de la scène reste obligatoire (ladder §2.8 du playbook).

### 2.4 Deux produits dans un dépôt

C'est la synthèse qui rend le projet cohérent avec le reste de ton écosystème :

- **`/zerbaj/`** — l'encyclopédie : une page prérendue par fruit, SSR complet, lisible **sans
  JavaScript**, avec JSON-LD, hreflang et le traitement AI-Overview de ton `PRD_AI_Overview`. C'est
  ce qui sera trouvé par les moteurs, cité par les assistants, et lu par les enseignants.
- **`/je/`** — le jeu : PWA hors ligne, aucun compte, aucun tracker, progression en local.

Le jeu déverrouille les fiches ; les fiches ramènent au jeu. Un seul jeu de données pour les deux.

### 2.5 Hors ligne d'abord

Contrainte réelle : le wifi des écoles. Le jeu doit être **entièrement jouable hors ligne** après une
première visite, et installable. Packs d'assets par île, téléchargés à la demande, `Cache-Storage`.

---

## 3. Le jeu proposé — « KI FWI SA YÉ ? »

**Public :** 7–12 ans, Guadeloupe · Martinique · Guyane · Réunion (extensible).
**Langues :** kréyòl en premier (le nom kréyòl est le nom *principal*, le français est la traduction —
c'est un choix politique, pas cosmétique), FR, EN. `lang` correct partout.

**Cinq modes :**

1. **Rekonèt** — photo réelle → 4 propositions. Répétition espacée façon Leitner (5 boîtes) persistée
   en local. C'est le cœur : c'est lui qui fait apprendre.
2. **Kaché** — indices dévoilés un à un : feuille → écorce → coupe → fruit entier. Score dégressif.
   Enseigne la lecture botanique, pas la reconnaissance de vignette.
3. **Ranmasé** (Phaser) — récolte dans le jaden : cueillir uniquement le fruit demandé, esquiver les
   plantes dangereuses. Le seul mode d'adresse.
4. **Sézon** — placer les fruits sur le calendrier de l'année. Connaissance rare, facile à jouer.
5. **Pa touché** — module sécurité : mancenillier, akée non mûr, coque de cajou, médicinier,
   laurier-jaune. Jamais chronométré, jamais scoré. On n'apprend pas le danger sous pression.

**Progression :** un album (`Lakou`) de fiches à débloquer, badges en KA, zéro monnaie, zéro pub,
zéro compte, zéro notification. Export de la progression en JSON (utile pour un enseignant).

**Le « moment de révélation »** (leçon JWE du playbook) : à la bonne réponse — la photo qui se
retourne, le nom kréyòl **prononcé**, le compteur en count-up, la fiche qui s'ajoute à l'album.

---

## 4. Plan en 7 sessions

Chaque session se termine par un build vert, un commit et une note de session. Ne pas enchaîner deux
sessions sans relire ce qui a été produit.

| # | Session | Livrable | Porte de sortie |
|---|---|---|---|
| **0** | **Cadre & données** — aucun code applicatif | ADR (licences, Phaser 4, hybride, sources), `fruits.schema.json`, dataset de 8 fruits vérifiés contre Wikidata/GBIF, `CREDITS.md`, `SOURCES.md`, lettre-type de demande TRAMIL/CIRAD | Le plan est validé **par toi** avant tout code |
| **1** | **Socle** — SvelteKit 2 + Svelte 5 + TS strict, tokens OKI, thème sombre, fonts self-hébergées, PWA, i18n GCF/FR/EN, `/zerbaj/` prérendu avec JSON-LD | 8 fiches en ligne, Lighthouse ≥ 90/95/95/95, lisible sans JS |
| **2** | **Moteur pédagogique** en Svelte pur — modes Rekonèt, Kaché, Sézon + Leitner + audio + album | **Le jeu est déjà amusant sans Phaser.** Si non, ne pas passer à la suite |
| **3** | **Pipeline assets** — client ComfyUI (seeds déterministes), porte de validation, AVIF/WebP, atlas, packs par île | 0 asset non validé dans le build, ≤ 2 Mo à l'entrée |
| **4** | **Ranmasé** (Phaser 4) + module **Pa touché** | Phaser absent du bundle initial, 30 fps sur mobile d'entrée de gamme, miroir DOM |
| **5** | **Contenu** — 24 fruits + 5 plantes dangereuses, audio kréyòl enregistré, relecture orthographique kréyòl | Contenu validé par une personne compétente, pas par un modèle |
| **6** | **Finition** — perf, a11y, DoD §8, `.htaccess`/`_headers`, déploiement, crédits, tag, push Gitea | DoD intégralement vraie |

**Test en classe entre la 5 et la 6.** Six enfants, trente minutes, tu regardes sans intervenir.
C'est la seule mesure qui compte, et elle invalidera une partie de ce document — tant mieux.

---

## 5. Ce qui ne se délègue pas à Claude Code

- Aller voir TRAMIL à Schœlcher.
- Enregistrer les voix kréyòl.
- Photographier les fruits qui manquent sur Commons (il en manquera).
- Faire relire l'orthographe kréyòl par un humain (GEREC-F ou l'usage local — et l'orthographe
  gwadloupéyen et matinitjé diffèrent : choisir, documenter, ne pas mélanger).
- Le test en classe.

Le code est la partie facile.