Ustagammon/docs/etape-1.md

É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 (fait)	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 (fait)	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

Orientation donnée par Pierre

• Un coach bienveillant, mis en avant mais discret (2026-11-03) : le conseil du maître et les conseils sont une signature de l'app, présents à chaque partie, sans jamais interrompre le jeu ni culpabiliser le joueur. Le ton des phrases du maître est encourageant ; l'espace qu'il occupe est réservé dans la mise en page (revue UX 0e.2), pas en fenêtre surgissante.

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 : ceux de GNU Backgammon (douteux 0,03, mauvais 0,06, très mauvais 0,12 d'équité, arSkillLevel), exposés par le moteur depuis 1a ; à calibrer sur de vraies parties.
• 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.