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