ki-fwi/BRIEF-CLAUDE-CODE_ki-fwi.md

MISSION : créer « KI FWI SA YÉ ? » selon le PLAYBOOK UNIFIÉ OKI × SVELTEKIT

Mode d'emploi. Colle ce fichier entier dans Claude Code, en joignant : playbook-oki-sveltekit.md (méthode + marque, fait autorité), AGENTS.md, svelte_core_bestpractices.md, PRD_AI_Overview_SEO_Recommandations.md, pack_complet_game_fruit.txt (matière première, à corriger, pas à appliquer tel quel), fruits.seed.json (données d'amorçage), GITEA.md (déploiement). Ajuste « Périmètre de cette session » (§6) à chaque nouvelle session.

---

Tu es un agent de code senior. Tu construis un jeu éducatif libre qui apprend aux enfants des Antilles à reconnaître les fruits, les arbres et les plantes de leurs îles.

Le playbook-oki-sveltekit.md fait autorité : la marque (§1) prime pour couleurs, typographie, voix et iconographie ; la méthode (§2) prime pour la technique ; les budgets (§2.7) et l'accessibilité (§2.8) ne se négocient jamais. Les conventions Svelte 5 du §3 sont obligatoires. Ce brief ne remplace le playbook nulle part : il le spécialise.

---

1. Contexte

• Projet : ki-fwi — nouveau dépôt, création ex nihilo (type de mission B du playbook §0).
• Porteur : ORGANISATION KA INTERNATIONALE (o-k-i.net), Martinique/Guadeloupe.
• Problème : une partie des enfants antillais ne sait plus nommer ni reconnaître les fruits de leur île, ni les arbres qui les portent. Le jeu vise à restituer cette connaissance.
• Public : 7–12 ans, lecture parfois fragile, téléphone Android d'entrée de gamme, 4G ou wifi d'école instable. Le jeu doit être jouable hors ligne et installable.
• Positionnement : logiciel libre, aucun compte, aucune publicité, aucun tracker, aucune requête vers un domaine tiers au runtime.

2. Règle n°1 du projet — la vérité visuelle

Le jeu enseigne la reconnaissance du réel. Deux filières d'assets, régimes séparés, jamais mélangés :

• Filière A — Vérité. Photographies réelles (Wikimedia Commons, iNaturalist, herbiers, photos du porteur). Seule filière autorisée pour tout ce qui sert à identifier : épreuves de reconnaissance, indices (feuille, écorce, coupe, port de l'arbre), fiches encyclopédiques.
• Filière B — Décor. Images générées par IA (ComfyUI/Krea2/FLUX) : fonds, personnages, sprites du mode arcade, badges, écrans de titre, iconographie. Jamais une épreuve d'identification.

Tout média porte un champ valide (booléen, false par défaut) et un champ source. Le build échoue si un média non validé est référencé par une épreuve. Écris ce contrôle comme un script de build, pas comme une consigne.

Justification, à ne pas oublier : les modèles de diffusion connaissent mal le corossol, à peine la quenette, presque pas le zikak ou le cachiman. Ils produisent des fruits plausibles et faux. Un jeu d'identification bâti sur des assets IA apprend l'erreur.

3. Règle n°2 — les licences

Rien n'est « libre de droit ». Avant d'embarquer le moindre média :

• Wikimedia Commons : majoritairement CC BY-SA 4.0 → attribution nominative et partage à l'identique, qui contamine les dérivés. Récupérer auteur, licence, URL du fichier, URL de la page de description, et les stocker par média dans les données.
• iNaturalist : souvent CC BY-NC. Acceptable pour un jeu non commercial ; à signaler explicitement dans CREDITS.md et dans l'ADR de licence.
• TRAMIL (tramil.net) : aucune licence accordée dans ses mentions légales → tous droits réservés. Utilisable comme source de vérification factuelle citée en référence, jamais comme source de fichiers. Rédige une lettre-type de demande d'autorisation que le porteur enverra.
• CIRAD / INRAE : régimes mixtes. Même traitement : vérification et demande, pas présomption.
• Wikidata / GBIF : à utiliser pour la taxonomie (Q-id, clé GBIF, nom scientifique accepté, famille) — c'est la colonne vertébrale factuelle du dataset.

Livrables associés : LICENSE (code : AGPL-3.0-or-later), LICENSE-CONTENT (contenu : CC BY-SA 4.0), CREDITS.md généré depuis les données, et un écran de crédits dans le jeu. Si un conflit de licence apparaît (NC vs commercial, SA vs compositing), arrête-toi et demande.

4. Stack

Défaut = §2.3 du playbook, avec ces précisions et ces écarts explicites :

SvelteKit 2 + Svelte 5 (runes) + TypeScript strict
@sveltejs/adapter-static, prerender intégral, trailingSlash 'always'
CSS vanilla : oki-tokens.css + base.css (pas de Tailwind)
vite-imagetools (AVIF/WebP responsive), vite-plugin-pwa (shell + packs hors ligne)
@fontsource → woff2 self-hébergés dans static/fonts/
phaser@^4  ← ÉCART DOCUMENTÉ, voir ci-dessous

Phaser 5 n'existe pas. La branche courante est Phaser 4 (4.0 « Caladan », avril 2026 ; 4.1 « Salusa » ; 4.2 « Giedi »), moteur WebGL réécrit en render nodes. Vérifie la dernière version publiée (npm view phaser version) avant d'installer. Ne pars pas de Phaser 3.

Frontière stricte Svelte / Phaser :

• Svelte porte la coquille : routes, i18n, SEO, menus, HUD, album, fiches, données, progression, audio, réglages, et trois des cinq modes de jeu (Rekonèt, Kaché, Sézon) en DOM/CSS pur.
• Phaser porte une seule scène : le mode arcade « Ranmasé ». Montée par import dynamique dans (jeu)/ranmase, jamais au layout racine, détruite au démontage (game.destroy(true)), communication par événements — pas d'état Svelte partagé par frame.
• Rendu AUTO (WebGL, repli canvas), DPR plafonné à 1.5, powerPreference: 'low-power', cible 30 fps stables sur Mali-G52.
• Miroir DOM sémantique obligatoire pour la scène (playbook §2.8, point 4).

Budgets : le shell reste ≤ 170 Ko JS gzip (non négociable). Phaser n'est téléchargé qu'à l'entrée dans la scène arcade, derrière un écran de chargement designé (P5). Consigne cet écart dans docs/adr/0002-phaser-hors-budget-initial.md : mesure réelle, justification, condition de réexamen. Entrée du site ≤ 2 Mo, LCP < 2,5 s, INP < 200 ms, CLS < 0,05.

5. Architecture produit — deux faces, un dataset

• /zerbaj/ — l'encyclopédie. Une page prérendue par fruit et par plante, lisible sans JavaScript, JSON-LD, hreflang, traitement conforme à PRD_AI_Overview_SEO_Recommandations.md. C'est la face indexable et citable du projet.
• /je/ — le jeu. PWA, hors ligne, sans compte, progression locale (localStorage + Cache-Storage), export/import de la progression en JSON.

Le jeu déverrouille les fiches ; les fiches renvoient au jeu. Un seul jeu de données alimente les deux : src/lib/data/fruits/*.json validés par fruits.schema.json à chaque build.

Langues : le kréyòl est la langue principale — le nom kréyòl est le nom du fruit, le français est sa traduction (choix assumé, à ne pas inverser). Routes / (GCF), /fr/, /en/. Routeur par dossiers + catalogues JSON, pas de middleware (playbook §5b.7). Attribut lang correct partout. L'orthographe kréyòl n'est pas de ton ressort : signale toute incertitude dans un fichier docs/kreyol-a-relire.md au lieu de trancher.

6. Les cinq modes

1. Rekonèt — photo réelle → 4 propositions. Répétition espacée (Leitner, 5 boîtes) persistée en local. C'est le mode qui fait apprendre : soigne-le en premier.
2. Kaché — indices dévoilés un à un : feuille → écorce → coupe → fruit entier, score dégressif.
3. Ranmasé — arcade Phaser : récolter le fruit demandé, éviter les plantes dangereuses.
4. Sézon — placer les fruits sur le calendrier annuel de l'île sélectionnée.
5. Pa touché — module sécurité : mancenillier, akée non mûr, coque de pomme-cajou, médicinier, laurier-jaune. Jamais chronométré, jamais scoré, jamais transformé en épreuve d'adresse. Ton sobre et factuel : on n'apprend pas le danger sous pression. Aucun visuel anxiogène.

Moment de révélation à la bonne réponse (leçon JWE du playbook §5b.12) : retournement de la photo, nom kréyòl prononcé, score en count-up (rAF → écriture DOM directe, span animé aria-hidden + valeur finale en .sr-only dans une région aria-live), fiche ajoutée à l'album.

Audio : chaque fruit a un fichier de prononciation kréyòl. Pas de synthèse vocale. Les enregistrements seront fournis par le porteur ; prévois le contrat (audio.gcf, format .opus, repli silencieux si le fichier manque) et un script de vérification listant les enregistrements manquants.

Accessibilité : cibles tactiles ≥ 44 px, navigation clavier complète, aucun mode chronométré en découverte, contraste AA sur le thème sombre, prefers-reduced-motion en gate unique au provider.

7. Pipeline d'assets IA (filière B uniquement)

Reprends le pack pack_complet_game_fruit.txt en corrigeant ses défauts :

• Seeds déterministes : hash() de Python est randomisé par exécution (PYTHONHASHSEED) — les seeds du script fourni ne sont pas reproductibles, contrairement à ce qu'il annonce. Utilise zlib.crc32(clé.encode()) & 0xFFFFFFFF. copy.deepcopy au lieu de json.loads(json.dumps(...)).
• Sortie : AVIF/WebP + atlas de textures par écran, jamais 80 PNG 512×512 en vrac. Packs par île.
• Porte de validation : chaque asset généré est comparé à ≥ 2 photos réelles ; valide: false tant qu'un humain n'a pas tranché ; le build refuse tout asset non validé.
• Licence du modèle rembg : vérifie la licence des poids, pas seulement du paquet.
• ComfyUI est piloté hors ligne, au build (P2). Aucun appel réseau ne subsiste au runtime.
• Le script vit dans tools/assets/, hors du bundle, avec son propre requirements.txt.

8. Périmètre de CETTE session

Session 0 — Cadre et données. Aucun code applicatif.

• git init + premier commit avant toute autre action (playbook §5b.1).
• Audit des sources : pour chacune (Commons, Wikidata, GBIF, iNaturalist, TRAMIL, CIRAD, INRAE), une fiche courte : ce qu'on y prend, sous quelle licence, avec quelle contrainte, comment on l'interroge. Rapport dans docs/audit-sources.md.
• ADR dans docs/adr/ : 0001 licences · 0002 Phaser 4 hors budget initial · 0003 frontière Svelte/Phaser · 0004 filières A/B des assets · 0005 kréyòl langue principale.
• fruits.schema.json (JSON Schema) + validateur exécutable en npm run validate:data.
• Dataset de 8 fruits, chaque champ taxonomique vérifié contre Wikidata et GBIF (pas contre ta mémoire) : nom scientifique accepté, famille, Q-id, clé GBIF, plus ≥ 2 photos Commons par fruit avec auteur, licence et URL. Point de départ : fruits.seed.json, dont tout est à vérifier, y compris l'orthographe kréyòl.
• SOURCES.md, CREDITS.md (généré), LICENSE, LICENSE-CONTENT.
• Lettre-type de demande d'autorisation TRAMIL et CIRAD (docs/courriers/).
• docs/plan.md : le plan des sessions 1 à 6 avec, pour chacune, sa porte de sortie mesurable.

Ne commence à coder l'application qu'après validation explicite du plan par le porteur.

9. Méthode de travail

• Vérifie git en premier, toujours (playbook §5b.1).
• Présente le plan avant d'écrire quoi que ce soit d'autre, et attends la validation.
• Après tout composant Svelte modifié : npx @sveltejs/mcp svelte-autofixer <fichier> jusqu'à silence, puis npm run check à 0 erreur / 0 warning avant tout commit (playbook §3).
• Aucune dépendance installée sans être importée et utilisée.
• Les données priment sur ce brief. Si fruits.seed.json ou Wikidata contredisent une affirmation écrite ici, les données gagnent — signale l'écart, ne le corrige pas en silence.
• Si une décision engage le juridique, la pédagogie ou la sécurité des enfants : arrête-toi et demande. Ce sont les trois domaines où une erreur ne se rattrape pas par un correctif.

10. Critères d'acceptation

• La DoD §8 du playbook est intégralement vraie, plus :
• Zéro requête tierce au runtime (onglet réseau, sur build de production).
• Chaque média porte source, auteur, licence, URL — vérifié par script.
• Aucune épreuve d'identification ne s'appuie sur un asset IA.
• Le jeu est entièrement jouable hors ligne après une première visite.
• /zerbaj/ est lisible et complet avec JavaScript désactivé.
• Bundle initial ≤ 170 Ko gzip, Phaser exclu du chemin critique et mesuré à part.
• Lighthouse mobile ≥ 90/95/95/95 sur l'accueil et sur une fiche.
• Navigation clavier complète sur les cinq modes, prefers-reduced-motion vérifié à la main.
• Le module « Pa touché » a été relu par un humain avant livraison.