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 (fait)	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 (fait)	Après chaque coup du joueur, jamais avant (ADR 0011) : appréciation du moteur (bon coup, imprécision, erreur, grosse erreur) 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 (fait)	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 (fait)	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 (fait)	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 livrés sans relecture préalable, sous les garde-fous du moteur (décision du 2026-11-09)	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
1k. Retours des joueurs, 2e lot	Crawford signalé sur la barre ; abandon (simple, gammon, backgammon) accepté ou refusé par l'ordinateur selon GNU Backgammon (plan 2026-11-12-retours-joueurs-2.md)	1c, 1e
1l. Analyse du match	Bilan et courbe d'un match entier (chances de gagner le match), erreurs de videau sur tout le match, prompt et export SGF du match (plan 2026-11-12-analyse-du-match.md)	1c, 1e, 1f
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.

Décisions de Pierre (2026-11-09)

• Indice avant le coup : pas en V1 (« l'idée est bonne »), à reprendre en V1.5 ou V2. Le conseil du maître après le coup reste le seul mécanisme de l'étape 1.
• Premier lancement : un choix « Je découvre » / « Je connais les règles » (fait en 0e.5).
• Seuils des appréciations : ceux de GNU Backgammon (douteux 0,03, mauvais 0,06, très mauvais 0,12, arSkillLevel), exposés par le moteur depuis 1a ; à recalibrer après les retours de Pierre sur de vraies parties. Le niveau le plus grave se dit « Grosse erreur », pas « gaffe ».
• Leçons : pas de relecture préalable par un joueur fort ; elles sont livrées telles quelles et améliorées sur retours d'experts. Garde-fous maintenus : chaque réponse attendue est le meilleur coup du moteur, vérifié par un test, et le texte n'affirme rien que le moteur ne confirme.
• Plein écran par défaut dans l'app installée : non (pas de display_override fullscreen) ; la barre d'état reste visible en portrait.
• Validés : le texte du tutoriel et toutes les maquettes du canevas (accueil, installation, tutoriel, aide, écrans 1c à 1i), ainsi que le cadre des phrases du maître (section « Les phrases du maître » de docs/identite/charte/ecrans-etape-1.md).

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 (maquettes validées par Pierre) ; 1h et 1i ; 1j en dernier. Chaque sous-étape a son plan dans docs/plans/ et sa merge request.