Plan 0e.5 : accueil, installation, tutoriel, aide

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

docs/adr/0013-position-dans-l-adresse.md

@@ -0,0 +1,49 @@
+# 0013. Une position du plateau dans l'adresse de la page
+
+- **Statut** : accepté
+- **Date** : 2026-11-03
+- **Décideurs** : Pierre (besoin), Claude Code (format)
+
+## Contexte
+
+Pierre a demandé, au premier test sur le téléphone (2026-11-03), qu'avec la
+seule adresse on arrive à une position du plateau : chaque position devient un
+lien direct, à partager, à mettre dans une leçon ou dans un prompt pour une IA.
+GNU Backgammon décrit déjà toute position par deux identifiants publics et
+documentés : le Position ID (14 caractères, les pions) et le Match ID
+(12 caractères : videau, score, longueur du match, joueur au trait, dés). Le
+moteur sait les lire et les écrire (`engine.h`).
+
+## Décision
+
+- L'adresse porte la position dans le fragment (après `#`) :
+  `https://ustagammon.sans.pub/#position=<Position ID>&match=<Match ID>`,
+  chaque identifiant encodé avec `encodeURIComponent` (le base64 de gnubg
+  contient `+` et `/`). `match` est facultatif : sans lui, partie libre, videau
+  au centre, joueur du bas au trait, sans dés.
+- Ouvrir un tel lien affiche la position, non jouable, avec deux actions :
+  « Jouer à partir d'ici » (nouvelle partie contre l'ordinateur depuis cette
+  position, sans toucher à la partie en cours) et « Retour à ma partie ».
+- Toute position affichée (partie, coup de l'ordinateur, analyse, leçon) peut
+  être copiée en lien (« Copier le lien de la position »).
+- Un identifiant illisible pour le moteur donne un message clair et le retour
+  à la partie, jamais une page cassée.
+
+## Alternatives écartées
+
+- **Paramètres de requête (`?position=`)** : ils changent l'adresse demandée
+  au serveur et au service worker ; hors ligne, la page en cache ne
+  correspondrait plus. Le fragment ne quitte jamais le navigateur.
+- **XGID (format d'eXtreme Gammon)** : répandu, mais un seul identifiant de
+  plus à décoder ; gnubg l'importe, son import pourra s'ajouter plus tard
+  (outil « import d'un identifiant GNU ou XGID » du cadrage).
+- **Format maison plus lisible** : il faudrait le décoder sans le moteur, donc
+  réimplémenter une règle de représentation (ADR 0007).
+
+## Conséquences
+
+- Le fragment est lu au chargement et à chaque changement (`hashchange`) ; le
+  domaine reçoit une position et un Match ID, le moteur les valide.
+- Les liens restent valables tant que GNU Backgammon garde ces formats, stables
+  depuis des années.
+- Les liens contiennent la position, rien d'autre : pas de donnée personnelle.

docs/adr/README.md

@@ -19,3 +19,4 @@ l'ancien passe au statut « remplacé par NNNN ». Voir l'ADR 0001.
 | [0010](0010-identite-visuelle.md) | Identité visuelle : symbole, logotype, palette | accepté |
 | [0011](0011-lecons-conseil-et-bilan.md) | Leçons numérotées, conseil du maître après le coup, bilan de fin de partie | accepté |
 | [0012](0012-mode-immersif.md) | Mode immersif : le plateau en paysage, sur demande | accepté |
+| [0013](0013-position-dans-l-adresse.md) | Une position du plateau dans l'adresse de la page | accepté |

docs/feuille-de-route.md

@@ -24,8 +24,8 @@ Demandes de Pierre du 2026-11-03, traitées avant d'ouvrir l'étape 1.
 | Sous-étape | Contenu | État | Plan |
 | --- | --- | --- | --- |
 | 0e.3 | Révision UX arbitrée (session « identité », sur délégation de Pierre) : portrait stable, bandeaux de compte de points, menu en feuille et nouvelle partie annulable, vibrations, écran allumé, paysage « plateau = écran » dès la rotation (ADR 0012 amendé) | ⏳ | `plans/2026-11-03-revision-ux.md` |
-| 0e.4 | Position dans l'adresse : chaque position du plateau a un lien direct (nouvel ADR pour le format) | ⏳ | |
-| 0e.5 | Page d'accueil, installation en un toucher (« Ajouter à l'écran d'accueil », proposée par l'app), tutoriel des règles très didactique avec plateaux illustrés, aide réécrite sur un ton plus humain ; textes à valider par Pierre | ⏳ | |
+| 0e.4 | Position dans l'adresse : chaque position du plateau a un lien direct (ADR 0013) | ⏳ | `plans/2026-11-03-position-dans-l-adresse.md` |
+| 0e.5 | Page d'accueil, installation en un toucher (« Ajouter à l'écran d'accueil », proposée par l'app), tutoriel des règles très didactique avec plateaux illustrés, aide réécrite sur un ton plus humain ; textes à valider par Pierre | ⏳ | `plans/2026-11-03-accueil-tutoriel-aide.md` |
 
 ## Étapes suivantes
 

docs/identite/charte/README.md

@@ -14,6 +14,7 @@ Décisions : ADR 0010. Fichiers du logo et des icônes : `../logo/`.
 | Fichier | Contenu |
 | --- | --- |
 | `guide-de-marque.md` | Règles d'usage : ton, couleurs, typographie, formes, mouvement, icônes, composants |
+| `accueil-tutoriel-aide.md` | Accueil, installation sans intrusion, tutoriel des règles (forme et première version du texte), aide en questions |
 | `recette-ux.md` | Critères de recette design de l'écran de jeu, à cocher sur les captures et sur le téléphone |
 | `interaction.md` | Comportement : réponse immédiate, annuler plutôt que confirmer, mouvement, vibrations, clavier, mises en page de l'écran de jeu (portrait, paysage, ordinateur), pictogrammes |
 | `tokens.json` | Toutes les valeurs, thèmes clair et sombre, avec une note d'usage par couleur |

docs/identite/charte/accueil-tutoriel-aide.md

@@ -0,0 +1,153 @@
+# Accueil, installation, tutoriel et aide
+
+Règles de l'étape 0e.5 (et 1g pour le tutoriel). Maquettes : rangée « Étape
+0e.5 » du canevas https://claude.ai/artifact/CQw6vbDpi6XQqVWQa4sANe et
+l'artboard « Accueil ». Les textes sont une **première version, à valider par
+Pierre**. Comportement général : `interaction.md`.
+
+## Accueil
+
+**Premier lancement** (aucune partie ni leçon enregistrée) : le logo, le
+plateau en position de départ, « Bienvenue à la table », une phrase, puis deux
+grands choix :
+
+- **« Je découvre »** (action principale) → le tutoriel, étape 1 ;
+- **« Je connais les règles »** → une partie tout de suite.
+
+Le choix ne revient plus. Le tutoriel reste dans le menu.
+
+**Ensuite**, de haut en bas :
+
+1. **La partie en cours** : miniature du plateau, comptes de points,
+   « Reprendre la partie » (seule action principale de l'écran) et
+   « Nouvelle partie ». Sans partie en cours : « Nouvelle partie » devient
+   l'action principale.
+2. **L'invitation à installer**, si elle doit apparaître (voir plus bas).
+3. **La prochaine leçon** : une seule carte (titre, état, progression,
+   « Continuer » en secondaire), avec le lien « Toutes les leçons ».
+4. **La progression résumée**, en une ligne `caption` : « 1 leçon terminée
+   sur 8 · 12 parties jouées · 4 gagnées ».
+5. En pied de page, la phrase de l'Atelier du Huit.
+
+Pas de chiffres d'erreur ou d'équité sur l'accueil : ils viennent avec
+l'analyse.
+
+## Installation
+
+Le but : proposer l'installation au bon moment, une fois, sans jamais
+interrompre.
+
+- **Jamais** au premier lancement, jamais pendant une partie, jamais en
+  fenêtre qui s'impose.
+- **Quand** : à partir de la fin de la **première partie terminée**, quand le
+  joueur a vu ce que vaut l'app.
+- **Où** : une carte compacte sur l'accueil (symbole, « Installer
+  Ustagammon », « Sur l'écran d'accueil, en plein écran, sans réseau. »,
+  bouton « Installer » et croix « Plus tard »), et une ligne « Installer
+  l'application » dans le menu, toujours présente tant que l'app n'est pas
+  installée.
+- **« Plus tard »** masque la carte ; elle revient une seule fois, après
+  trois parties de plus. Ensuite, seul le menu la propose.
+- **Chrome Android** : le bouton déclenche l'invite du système, gardée depuis
+  l'événement `beforeinstallprompt`. Sans cet événement (navigateur qui ne
+  propose pas l'installation), le même bouton ouvre la marche à suivre.
+- **Firefox Android** : une feuille en trois étapes numérotées (menu ⋮,
+  « Installer » ou « Ajouter à l'écran d'accueil », confirmer), qui se ferme
+  par « J'ai compris ».
+- **iPhone (Safari)** : même feuille, avec ces étapes : bouton de partage,
+  « Sur l'écran d'accueil », « Ajouter ».
+- **Une fois installée** (`display-mode: standalone`, ou événement
+  `appinstalled`) : plus aucune proposition, la ligne du menu disparaît.
+
+## Tutoriel des règles
+
+### Forme
+
+- Huit étapes, chacune en **écrans courts** : un titre, un plateau illustré,
+  deux ou trois phrases. Une étape sur deux finit par un écran **« à vous »**
+  où le joueur fait le geste sur le vrai plateau, contrôlé par le moteur.
+- En haut : une barre de progression en huit segments (`accent` pour les
+  étapes faites) et « Passer » à droite. En bas : « Retour » et
+  « Continuer ».
+- Les positions sont données par leurs identifiants gnubg (ADR 0013) ; le
+  plateau est le composant de l'app, non jouable sauf sur les écrans
+  « à vous ». Aucune règle n'est codée hors du moteur : un écran « à vous »
+  demande au moteur si le coup du joueur fait partie des coups permis attendus.
+- **Les pions bougent** : sur un écran d'explication, le coup illustré se joue
+  tout seul après une seconde, pion par pion (`duration-fast`), puis reste
+  affiché ; « Revoir » le rejoue. Sur les écrans à flèches (sens du jeu), un
+  tracé en pointillés `text` sur un liseré ivoire, jamais en brique (la brique
+  veut dire « à faire »).
+- Un geste juste : coche `verdict-good`, vibration « pion posé », phrase
+  courte, « Continuer » devient l'action principale. Un geste faux : le pion
+  revient, et une phrase dit pourquoi, sans le mot « erreur ».
+- Chaque terme nouveau est un lien vers sa fiche du glossaire, à sa première
+  apparition.
+
+### Texte, première version
+
+1. **Le but du jeu.** « Vous avez quinze pions ivoire, l'ordinateur quinze
+   pions noyer. Chacun fait faire le tour du plateau à ses pions, puis les
+   sort. Le premier qui a sorti tous les siens gagne la partie. »
+2. **Dans quel sens avancer.** « Vos pions ivoire font le tour du plateau dans
+   le sens des pointillés : ils partent d'en haut à droite, passent à gauche,
+   puis reviennent en bas jusqu'aux six dernières flèches, en bas à droite.
+   C'est là que vous les rassemblerez avant de les sortir. Les pions noyer de
+   l'ordinateur font le même chemin, en sens inverse. »
+3. **Les dés et les doubles.** « Chaque dé déplace un pion d'autant de
+   flèches. Avec 5 et 2, vous jouez un pion de 5 et un pion de 2, ou le même
+   pion de 5 puis de 2. Un double se joue quatre fois : avec 4-4, vous avancez
+   quatre fois de 4. » *À vous* : jouer 3-1 en faisant le point 5 (8/5 6/5).
+4. **Frapper un pion seul.** « Un pion seul sur une flèche s'appelle un blot.
+   Si vous vous posez dessus, vous le frappez : il part sur la barre et devra
+   refaire tout le chemin. Une flèche où l'adversaire a deux pions ou plus est
+   fermée : vous ne pouvez pas vous y poser. » *À vous* : frapper le blot du
+   point 7 avec 6-1.
+5. **Rentrer depuis la barre.** « Votre pion frappé attend sur la barre, au
+   milieu. Avant de jouer quoi que ce soit d'autre, il doit rentrer dans le
+   camp adverse, en haut à droite. Chaque dé indique une flèche d'entrée :
+   avec 3 et 4, la 22 ou la 21. Si les deux flèches sont fermées, votre tour
+   passe. »
+6. **Sortir ses pions.** « Quand vos quinze pions sont dans les six dernières
+   flèches, vous pouvez commencer à les sortir : un 6 sort un pion de la
+   flèche 6, un 1 un pion de la flèche 1. Touchez le pion, puis la sortie à
+   droite. » *À vous* : sortir deux pions avec 6-3.
+7. **Gammon et backgammon.** « Une partie gagnée vaut 1 point. Si
+   l'adversaire n'a sorti aucun pion quand vous finissez, c'est un gammon :
+   2 points. S'il lui reste en plus un pion sur la barre ou dans votre camp,
+   c'est un backgammon : 3 points. »
+8. **Le videau.** « Le cube aux faces 2, 4, 8, 16, 32 et 64 sert à miser.
+   Avant de lancer vos dés, vous pouvez proposer de doubler la valeur de la
+   partie. L'ordinateur prend, et la partie continue en valant le double, ou il
+   passe, et vous gagnez tout de suite. Celui qui a pris garde le cube : lui
+   seul pourra redoubler. » *À vous* : décider de prendre ou passer, avec une
+   phrase du maître ensuite.
+
+Fin du tutoriel : « Vous connaissez les règles. Le reste s'apprend en jouant,
+et le maître vous accompagne. » → « Jouer ma première partie ».
+
+## Aide
+
+L'aide n'est plus une copie brute des fichiers : c'est une page organisée en
+questions, avec un ton. **La source reste unique** (ADR 0008) : les mêmes
+fichiers servent d'aide et de tests.
+
+- **Trois onglets** : « Jouer » (les scénarios), « Les mots du jeu » (le
+  glossaire), « À propos ». Le tutoriel est proposé en tête de page.
+- **« Jouer »** : un scénario = une question repliable (`details`), fermée par
+  défaut sauf celle qui correspond à l'écran d'où l'on vient.
+  - Le **titre du scénario** est la question, formulée comme le joueur se la
+    pose : « Comment jouer un coup ? », « Je me suis trompé de pion », « Je ne
+    peux rien jouer avec mes dés ». C'est un changement de titre dans les
+    `.feature` : les tests n'en dépendent pas.
+  - La **description du scénario** (le paragraphe sous le titre) est la
+    réponse affichée. Elle se lit seule, au présent, au « vous ».
+  - Les **étapes Gherkin** ne s'affichent pas dans l'aide : elles restent la
+    preuve que l'app fait ce que dit la réponse. « Voir sur le plateau » ouvre
+    la position de l'exemple quand le scénario en donne une (lien ADR 0013).
+  - La **description de la fonctionnalité** sert d'introduction à l'onglet.
+- **« Les mots du jeu »** : une fiche du glossaire = une carte (le mot, son nom
+  anglais en `caption` italique, « En bref », les renvois), triées par ordre
+  alphabétique, avec un champ de recherche en tête.
+- **Ton** : celui du maître de café, patient et concret. Pas de « Étant
+  donné que », pas de vocabulaire technique (moteur, scénario, événement).

docs/plans/2026-11-03-accueil-tutoriel-aide.md

@@ -0,0 +1,59 @@
+# Accueil, installation, tutoriel des règles, aide (0e.5)
+
+- **Date** : 2026-11-03
+- **Étape** : 0e.5 (feuille de route), qui couvre aussi le tutoriel de 1g
+- **Statut** : prévu (après la fusion de 0e.4)
+- **Exécutant** : sous-agent general-purpose, dans un worktree
+
+## Objectif
+
+Traiter les points 2 et 3 du message de Pierre du 2026-11-03 et sa demande d'installation en un toucher :
+- une page d'accueil ;
+- l'installation proposée par l'app ;
+- un tutoriel des règles très didactique, illustré par le plateau ;
+- une aide plus humaine.
+
+## Références
+
+- Règles : `docs/identite/charte/accueil-tutoriel-aide.md`. Le texte du tutoriel y figure en première version, à faire valider par Pierre.
+- Maquettes : https://claude.ai/artifact/CQw6vbDpi6XQqVWQa4sANe, rangée « Étape 0e.5 » et artboard « Accueil ».
+- ADR 0008 (source unique), ADR 0013 (positions par identifiants gnubg).
+
+## Consignes
+
+1. **Accueil**, selon la charte :
+   - au premier lancement, et une seule fois, le choix entre « Je découvre » et « Je connais les règles » ;
+   - ensuite : la partie en cours, la carte d'installation, la prochaine leçon et la progression résumée. La leçon et la progression restent en attente tant que 1g et 1h n'existent pas : n'afficher que ce qui existe.
+2. **Installation** :
+   - sous Chrome, garder l'invite reçue avec `beforeinstallprompt` ;
+   - sous Firefox et sur iPhone, une feuille en 3 étapes ;
+   - la carte n'apparaît qu'à partir de la première partie terminée. « Plus tard » la masque, et elle ne revient qu'une fois, après 3 parties. Le menu garde une ligne tant que l'app n'est pas installée ;
+   - plus rien en `display-mode: standalone` ni après l'événement `appinstalled`.
+3. **Tutoriel**, en 8 étapes :
+   - le texte vit dans un fichier source unique sous `docs/` (par exemple `docs/tutoriel/`), copié dans le site par `make site` comme le glossaire, sous licence CC BY-SA 4.0 ;
+   - positions données par leurs identifiants gnubg ;
+   - sur les écrans « à vous », le moteur vérifie le coup joué en le comparant aux coups attendus de l'étape ;
+   - le coup illustré se joue seul après 1 s, avec « Revoir » ;
+   - un test vérifie que chaque position du tutoriel est valide pour le moteur et que chaque coup attendu est légal ;
+   - ajouter la fiche du glossaire « camp ».
+4. **Aide**, en trois onglets :
+   - « Jouer » : les scénarios deviennent des questions repliables. Le titre est la question et la description la réponse ; les étapes Gherkin sont cachées. Reformuler les titres des `.feature` sans casser les tests ;
+   - « Les mots du jeu » : les cartes du glossaire, avec une recherche ;
+   - « À propos » : licence, crédits, version ;
+   - le tutoriel est proposé en tête de l'aide.
+5. **Scénarios Gherkin** : premier lancement, installation, suivre le tutoriel.
+6. **`make test-browser`** :
+   - premier lancement, tutoriel complet avec ses écrans « à vous », aide ;
+   - `beforeinstallprompt` simulé dans Chromium ;
+   - captures dans `build/browser-shots/accueil-tutoriel/` pour la recette design.
+
+`make lint`, `make test` et `make test-browser` doivent passer. Aucune nouvelle dépendance.
+
+## Critères de réussite
+
+- Un débutant suit le tutoriel jusqu'au bout sur le téléphone, et chaque écran « à vous » accepte le bon coup et refuse les autres.
+- Les trois commandes passent, et les captures sont livrées pour la recette.
+
+## Résultat
+
+À remplir à la clôture.

docs/plans/2026-11-03-position-dans-l-adresse.md

@@ -0,0 +1,39 @@
+# Position dans l'adresse (0e.4)
+
+- **Date** : 2026-11-03
+- **Étape** : 0e.4 (feuille de route)
+- **Statut** : prévu (après la fusion de la révision UX, qui touche les mêmes fichiers)
+- **Exécutant** : sous-agent general-purpose, dans un worktree
+
+## Objectif
+
+Appliquer l'ADR 0013 : chaque position du plateau a un lien direct.
+
+## Consignes
+
+ADR 0007, 0008 et 0013. Aucune nouvelle dépendance.
+
+1. Lecture du fragment `#position=…&match=…` au chargement et sur
+   `hashchange` ; validation par le moteur ; message clair si illisible.
+2. Vue de la position, non jouable, avec « Jouer à partir d'ici » (nouvelle
+   partie depuis la position, la partie en cours restant reprenable) et
+   « Retour à ma partie ».
+3. Domaine : démarrer une partie depuis une position et un Match ID donnés
+   (événement GameStarted étendu de façon rétrocompatible, ou équivalent
+   justifié), sans règle réimplémentée.
+4. « Copier le lien de la position » depuis le menu de la partie et depuis la
+   vue du coup de l'ordinateur ; le lien copié rouvre exactement la même
+   position (test aller-retour).
+5. Scénarios Gherkin (« Ouvrir un lien vers une position », « Partager la
+   position »), fiches du glossaire (Position ID, Match ID si absentes).
+6. `make lint`, `make test`, `make test-browser` (ouvrir un lien, jouer à
+   partir d'ici, revenir, lien invalide).
+
+## Critères de réussite
+
+Un lien copié depuis l'app, ouvert dans un nouvel onglet, montre la même
+position ; les trois commandes passent.
+
+## Résultat
+
+À remplir à la clôture.