Étape 1 découpée ; plan du moteur pour l'analyse

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/etape-1.md

@@ -0,0 +1,47 @@
+# Étape 1 — V1 « Jouer et comprendre »
+
+Document temporaire : il décrit l'étape en cours et sera supprimé à sa clôture,
+après report de ce qui est durable dans les ADR et le journal.
+
+**Critère de fin** (cadrage) : un débutant apprend et joue seul ; un joueur de
+club comprend ses erreurs. Livré avec un plan de test (`docs/guide-test-etape-1.md`)
+que Pierre déroule sur le Fairphone 4.
+
+**Préalable** : les sous-étapes 0e (retours du premier test) de la feuille de
+route, dont la revue UX validée par Pierre.
+
+## Périmètre
+
+Repris du cadrage (modules, écrans clés, IA générative en V1) et des ADR 0010,
+0011 et 0012. Ce qui n'y figure pas est hors de l'étape 1.
+
+| Sous-étape | Contenu | Dépend de |
+| --- | --- | --- |
+| 1a. Moteur pour l'analyse | Niveaux de jeu (plis et bruit de GNU Backgammon : débutant à expert), classement des coups d'un jet avec équités, analyse d'un coup joué et d'une décision de videau, chance d'un jet ; exposés par `engine.h`, `engine-cli` et le Worker, avec positions de référence comparées à gnubg de bureau | — |
+| 1b. Parties enregistrées | Stockage IndexedDB derrière l'interface de stockage existante : plusieurs parties, reprise automatique, branches (« Rejouer d'ici » crée une branche, l'originale reste intacte et rechargeable), export SGF avec variantes | — |
+| 1c. Match et réglages | Partie libre ou match en N points, règle Crawford, règle Jacoby, choix du niveau de l'ordinateur, conseil du maître activable ou non ; écran de nouvelle partie | 1a, 1b |
+| 1d. Conseil du maître | Après chaque coup du joueur, jamais avant (ADR 0011) : appréciation du moteur (bon coup, imprécision, erreur, gaffe) avec mot, icône et couleur, phrase du maître fondée sur les chiffres du moteur, coup recommandé montré sur demande ; aussi pour les décisions de videau ; calcul en arrière-plan sans retarder le jeu | 1a |
+| 1e. Fin de partie et analyse | Bilan (ADR 0011) : résultat, coups par appréciation, taux d'erreur comparé à la chance, « le coup à revoir » ; écran d'analyse : graphe d'équité (toucher un point ouvre la position), liste des erreurs filtrable, visualiseur pas à pas coup joué contre meilleur coup, « Rejouer d'ici » | 1a, 1b, 1d |
+| 1f. Prompts à copier | Gabarits versionnés et testés (`docs/prompts/` ou équivalent, source unique), bouton « Demander à une IA » sur le plateau, le conseil du maître, l'analyse et la fin de partie ; le moteur décide, l'IA explique | 1d, 1e |
+| 1g. Accueil, tutoriel et leçons | Accueil (reprendre, nouvelle partie, prochaine leçon, progression résumée), tutoriel des règles interactif et illustré (0e.5), cinq premières leçons numérotées (ADR 0011) avec positions et « à vous de jouer », progression locale ; contenus CC BY-SA 4.0 en brouillon, à relire par un joueur fort | 0e.5, 1a |
+| 1h. Progression | Historique des parties et courbe du taux d'erreur | 1b, 1e |
+| 1i. Plateau soigné | Dessin du plateau aligné sur la charte (`docs/identite/charte/board.js`), animations des pions, glisser-déposer en plus du toucher, double toucher pour le seul coup évident | 0e.3 |
+| 1j. Plan de test | `docs/guide-test-etape-1.md` : parcours du débutant et du joueur de club sur le téléphone, avec ce qu'il faut rapporter | toutes |
+
+## Questions pour Pierre (ne bloquent pas le démarrage)
+
+- **Indice** : le cadrage le liste dans le module Jeu, l'ADR 0011 l'a laissé
+  « à concevoir séparément ». Il n'est pas dans l'étape 1 sans décision.
+- **Questionnaire de premier lancement** (choix du parcours) : le parcours 1
+  seul existe en V1 ; proposé : un simple choix « Je découvre » / « Je connais
+  les règles » qui oriente vers le tutoriel ou la partie.
+- **Seuils des appréciations** : proposés d'après ceux de GNU Backgammon
+  (douteux 0,04, mauvais 0,08, très mauvais 0,16 d'équité), à calibrer.
+- **Relecture des leçons** par un joueur fort de l'Atelier du Huit.
+
+## Ordre de réalisation
+
+1a et 1b d'abord (fondations, sans conflit avec l'interface), en parallèle des
+sous-étapes 0e. Puis 1c, 1d, 1e, 1f dans cet ordre ; 1g après la validation des
+maquettes d'accueil et de tutoriel par Pierre ; 1h et 1i ; 1j en dernier. Chaque
+sous-étape a son plan dans `docs/plans/` et sa merge request.