# Ustagammon — Document de cadrage

Version du 1er novembre 2026. Version vivante et commentée : https://claude.ai/artifact/HAhVos4LEL7F2S2uCaZyMJ
Identité visuelle et nom : voir le brief créatif, https://claude.ai/artifact/36WMwZWqvMxXvSSVBJTgwd

## Vision et objectifs

Une application mobile de backgammon, entièrement hors ligne, qui fait progresser le joueur du premier lancer de dés jusqu'au niveau expert. Elle s'appuie sur le moteur GNU Backgammon pour tout ce qui est calculable, et sur l'IA générative (hors de l'app en V1) pour tout ce qui relève de l'explication.

Constat de départ : les apps existantes basées sur GNU Backgammon (CBG notamment) ont un moteur excellent mais une interface peu intuitive. Les chiffres sont là, la pédagogie manque.

**Objectifs de la V1**
- Jouer contre GNU Backgammon dans une interface fluide et agréable, avec des niveaux adaptés à chaque profil.
- Comprendre chaque partie grâce à une analyse visuelle, au niveau des rapports illustrés déjà produits avec le skill d'analyse.
- Apprendre selon un parcours structuré, des règles aux concepts avancés.
- Prolonger l'explication dans une IA tierce par un bouton qui copie un prompt contenant tout le contexte de la position.

**Hors périmètre V1** : jeu en ligne, comptes utilisateurs, IA générative intégrée, version iOS (non prévue), version web (décidée après le prototype).

## Profils et parcours

Quatre parcours successifs. Le joueur choisit son point d'entrée au premier lancement (court questionnaire), puis l'app propose le palier suivant quand il atteint l'objectif du sien.

| Parcours | Pour qui | Contenu principal | Niveau de l'IA | Objectif de sortie |
| --- | --- | --- | --- | --- |
| 1. Découvrir | Curieux, jamais joué | Règles en tutoriel interactif, parties guidées, coups légaux surlignés, annulation libre | Débutant, très bridé | Finir une partie seul sans aide aux règles |
| 2. Comprendre | Connaît les règles, joue au feeling | Leçons par concept (ouvertures, construction, prime, blitz, course, sortie, bases du videau), positions d'entraînement | Intermédiaire | Moins de 20 d'erreur moyenne par partie (unité GNU, à calibrer) |
| 3. Se perfectionner | Joueur de club | Analyse de chaque partie, exercices tirés de ses erreurs, videau et tables d'équité de match | Fort | Moins de 10 d'erreur moyenne |
| 4. Aller plus haut | Joueur confirmé | Rollouts, révision espacée des gaffes, statistiques par type de position, défis | Maximal | Progression continue |

**Principe transversal** : à chaque palier, le joueur peut demander pourquoi. Le moteur donne la réponse chiffrée, l'app la met en image, un bouton copie un prompt pour obtenir une explication en langage naturel.

## Principes d'expérience

1. **Le plateau d'abord** : plein écran en jeu, informations secondaires en tiroir.
2. **Gestes naturels** : glisser un pion, ou toucher pion puis destination ; double toucher pour le seul coup évident.
3. **Aide dosée selon le parcours** : beaucoup de guidage au début, retiré progressivement, réactivable.
4. **Chiffres traduits** : chaque équité a un libellé (bon, imprécision, erreur, gaffe), une couleur et une phrase courte.
5. **Retour non intrusif** : un discret indicateur après chaque coup ; le détail seulement à la demande.
6. **Comparaison visuelle** : coup joué et meilleur coup côte à côte, pions animés.
7. **Vocabulaire progressif** : glossaire intégré, chaque terme technique est touchable.
8. **Direction artistique** cohérente avec les rapports existants : thème clair et sombre, palette sobre, typographie lisible.

## Fonctionnalités par module

| Module | Fonctionnalités | V1 |
| --- | --- | --- |
| Jeu | Partie simple ou match en N points, videau, Crawford, Jacoby, niveaux, annulation (selon parcours), indice, sauvegarde et reprise automatique, branches de partie (reprendre depuis un coup précédent sans perdre la partie en cours, plusieurs branches rechargeables) | Oui |
| Coach en direct | Indicateur après chaque coup, comparaison avec le meilleur coup, conseil de videau, désactivable | Oui |
| Analyse de partie | Taux d'erreur, chance aux dés, moments décisifs, graphe d'équité, liste des erreurs avec visualiseur, export SGF | Oui |
| Leçons | Tutoriel des règles, leçons par concept avec positions animées, quiz | Règles et 5 premières leçons |
| Exercices | Positions à résoudre (coup ou videau), bibliothèque et ses propres erreurs, révision espacée | Bibliothèque de base |
| Progression | Historique, évolution du taux d'erreur, forces et faiblesses par type de position, badges | Historique et courbe d'erreur |

**Outils transverses** : saisie libre d'une position, import d'un identifiant GNU ou XGID, glossaire, réglages.

## Écrans clés

1. **Plateau de jeu** : plein écran, dés et videau tactiles, barre d'actions minimale (annuler, indice, menu), tiroir du coach replié.
2. **Fin de partie** : résultat, taux d'erreur comparé à la chance, trois moments décisifs, accès à l'analyse.
3. **Analyse** : graphe d'équité (toucher un point ouvre la position), liste des erreurs filtrable, visualiseur pas à pas coup joué contre meilleur coup. Depuis n'importe quel coup, « Rejouer d'ici » crée une branche ; la partie d'origine reste intacte et rechargeable.
4. **Accueil** : reprendre, nouvelle partie, prochaine leçon, exercice du jour, progression résumée.
5. **Parcours et leçons** : carte des leçons, chaque leçon en écrans courts (explication, position animée, à vous de jouer).
6. **Exercice** : une position, la consigne, le joueur joue, puis la correction du moteur.
7. **Progression** : courbe d'erreur, erreurs par thème, historique.

Sur les écrans 1, 3 et 6, chaque position porte le bouton « Demander à une IA ».

## IA générative en V1 : prompts à copier

L'app n'appelle aucune IA : un bouton copie dans le presse-papiers un prompt rempli avec le contexte exact. Règle d'or : **le moteur décide, l'IA explique**.

| Bouton | Où | Contexte injecté | Demande |
| --- | --- | --- | --- |
| Pourquoi ce coup est meilleur ? | Coach, analyse | Position, dés, coup joué, top 3 avec équités et probabilités | Expliquer la différence en concepts |
| Expliquer cette décision de videau | Coach, analyse | Position, score, videau, équités ND, D/P, D/T | Expliquer doubler, prendre ou passer |
| Bilan de ma partie | Fin de partie | Score, taux d'erreur, chance, erreurs et leur coût | Identifier 3 thèmes à travailler |
| Expliquer ce concept | Leçons, glossaire | Concept, niveau, position d'exemple | Expliquer simplement avec une analogie |
| Créer des exercices | Progression | Thèmes d'erreurs récurrents, niveau | Proposer des exercices ciblés |

Chaque prompt contient : le rôle (coach) et le niveau du joueur ; la position en identifiants GNU et en diagramme texte ; les chiffres du moteur avec le niveau d'évaluation ; la consigne de ne pas contredire ces évaluations ; la langue de réponse.

```text
Tu es un coach de backgammon. Je suis un joueur de niveau {niveau}.
Voici une position (GNU Position ID : {position_id}, Match ID : {match_id}) :
{diagramme_texte}
Score : {score}. Videau : {videau}. Dés : {des}.
J'ai joué {coup_joue} (équité {equite_joue}).
GNU Backgammon ({niveau_eval}) recommande :
{top3_coups_avec_equites_et_probabilites}
Explique-moi, sans recalculer ces évaluations, pourquoi le meilleur coup
est supérieur au mien : quels concepts sont en jeu et que retenir.
Réponds en {langue}, en moins de 200 mots.
```

Les gabarits sont des fichiers séparés, versionnés et testés. En V2, la même couche pourra appeler une IA directement sans modifier les écrans.

## Architecture technique

Le moteur est compilé en bibliothèque native et caché derrière une interface interne : aucun écran ne l'appelle directement.

```
Interface (Kotlin natif ou web)
        │
Services de l'app (partie, coach, parcours, progression, stockage) ──► Générateur de prompts ──copier──► IA tierce (hors app)
        │
Interface moteur (abstraction)
        │
GNU Backgammon : bibliothèque Android (NDK)  ou  WebAssembly (PWA)
```

- **Moteur** : code C compilé pour ARM64 (NDK) ou WebAssembly (Emscripten). Les optimisations SSE sont remplacées par NEON, SIMD WebAssembly ou du C générique. Le portage de CBG sert de point de départ ; son APK pèse environ 35 Mo.
- **Données du moteur** : réseaux, base de fin de partie, tables d'équité de match, embarqués et chargés une fois.
- **Interface moteur** : coups légaux, meilleur coup par niveau, décision de videau, évaluation, analyse de partie. Positions au format identifiant GNU.
- **Niveaux de l'IA** : profondeur d'évaluation et bruit volontaire de GNU Backgammon.
- **Calcul en arrière-plan** : hors du fil d'affichage, annulable ; analyse de fin de partie progressive.
- **Stockage local** : SQLite (ou IndexedDB en web) ; parties stockées en arbre pour les branches (chaque branche pointe vers sa partie et son coup d'origine) ; export SGF avec variantes ; leçons en fichiers versionnés.
- **Tests** : positions de référence évaluées avec GNU Backgammon de bureau, comparées automatiquement à la version embarquée.

## Licence et distribution

- Code sous **GPLv3**, condition de GNU Backgammon ; permet aussi de reprendre le travail de CBG.
- **Android (V1)** : F-Droid et Play Store. Code source public, hébergé sur le Gitea personnel du projet ; builds et tests en local via make, sans service cloud.
- **Version web (option)** : PWA installable, hors ligne, moteur en WebAssembly, sous GPLv3. Aucune version iOS prévue.
- **Contenus** pédagogiques sous CC BY-SA.
- **Diffusion initiale** : la communauté de l'Atelier du Huit (café associatif, Cugnaux).

## Découpage en versions

| Étape | Contenu | Critère de fin | Durée estimée |
| --- | --- | --- | --- |
| 0. Prototype technique | Moteur appelé depuis l'app, test WebAssembly, plateau minimal | Partie complète sur le Fairphone 4, moins de 2 s par coup | 2 à 3 semaines |
| 1. V1 Jouer et comprendre | Plateau soigné, niveaux, coach, fin de partie, analyse, branches, tutoriel des règles, prompts, sauvegarde | Un débutant apprend et joue seul ; un joueur de club comprend ses erreurs | 2 à 3 mois |
| 2. V1.5 Apprendre | Parcours 2 complet, exercices, progression | Parcours 1 et 2 complets | 2 mois |
| 3. V2 Perfectionnement et IA | Parcours 3 et 4, rollouts, révision espacée, IA intégrée en option | Parcours complets | À définir |

## Risques

| Risque | Parade |
| --- | --- |
| Moteur difficile à isoler en bibliothèque | Repartir de CBG ou gnubg-nn ; valider dès l'étape 0 |
| Évaluations profondes lentes sur téléphone | Arrière-plan, niveaux adaptés, analyse progressive |
| Contenus pédagogiques longs à produire | Peu de leçons très soignées ; brouillons par IA relus par un joueur fort |
| Explications d'IA tierces erronées | Prompts qui imposent les chiffres du moteur |
| Moteur trop lent ou lourd en WebAssembly | Mesurer dès l'étape 0 ; à défaut, Android seul |
| PC de développement ancien | Docker, `-j2`, pas d'émulateur, recompilation minimale |

## Questions ouvertes

- [ ] Socle : PWA (moteur WebAssembly) ou Kotlin natif ? Décidé à la fin de l'étape 0.
- [ ] Moteur : reprendre CBG ou repartir de gnubg-nn ?
- [ ] Seuils d'erreur des parcours, à calibrer sur de vraies parties.
- [ ] Relecture des contenus pédagogiques (par exemple Philippe, à l'Atelier du Huit ?).
- [x] Nom de l'application : **Ustagammon** (voir le brief créatif).