# Scénarios d'utilisation

La documentation utilisateur d'Ustagammon : un fichier par tâche réelle d'un
joueur, écrit pour lui. Ces fichiers sont la seule source (ADR 0008) :
l'application les met en forme comme pages d'aide, et ils sont exécutés comme
tests d'intégration sur le domaine et le moteur réel.

`make site` copie ce dossier dans le site publié (`docs/scenarios/`) ; l'aide
de l'application (bouton « Aide ») lit ces copies à l'exécution
(`app/src/ui/help.ts`). Les fichiers affichés dans l'aide sont ceux de la
liste `FEATURES` de `help.ts`.

`make test` les exécute avec Cucumber : les étapes, définies dans
`app/tests/steps/`, pilotent le domaine branché sur le vrai moteur
WebAssembly, avec des dés imposés pour que chaque exécution soit identique. Une
étape sans définition fait échouer les tests.

## Format

Gherkin standard (`.feature`), en français, validé par l'analyseur officiel de
Cucumber (`make test`) :

```gherkin
# language: fr
Fonctionnalité: <la tâche>

  Un court paragraphe qui explique au joueur à quoi elle sert.

  Scénario: <un cas précis>
    Étant donné que <la situation de départ>
    Quand <ce que fait le joueur>
    Alors <ce qu'il constate>
    Et <autre constat>
```

Dans l'aide, chaque scénario devient une question repliable : son titre est
la question, formulée comme le joueur se la pose (« Comment jouer un
coup ? ») ; le paragraphe sous le titre est la réponse, qui doit se lire
seule ; les étapes ne s'affichent pas. Une étiquette
`@position:<Position ID>` au-dessus du scénario ajoute à la réponse le lien
« Voir sur le plateau ». L'adresse d'une question (`#/aide/<identifiant>`)
est tirée de son titre : changer un titre change son adresse, et les titres
cités par `app/src/ui/help-context.ts` sont vérifiés par `make test`.

Règles d'écriture :

- la deuxième personne (« vous ») et les mots du glossaire (`docs/glossaire/`) ;
- des intentions, pas des gestes d'interface : « vous commencez une nouvelle
  partie », pas « vous touchez le bouton Nouvelle partie ». Le même scénario
  reste vrai quelle que soit l'interface, et peut piloter directement le
  domaine ;
- des constats vérifiables par le joueur, sans détail technique.

## Scénarios

| Fichier | Tâche | Depuis |
| --- | --- | --- |
| [jouer-une-partie.feature](jouer-une-partie.feature) | Jouer une partie contre l'ordinateur | Étape 0d |
| [jouer-un-match.feature](jouer-un-match.feature) | Choisir sa partie (libre ou match, niveau) et jouer un match | Étape 1c |
| [comprendre-mes-coups.feature](comprendre-mes-coups.feature) | Comprendre ses coups avec le conseil du maître | Étape 1d |
| [revoir-ma-partie.feature](revoir-ma-partie.feature) | Revoir sa partie : bilan, coup à revoir, analyse, rejouer d'ici | Étape 1e |
| [demander-a-une-ia.feature](demander-a-une-ia.feature) | Demander à une IA d'expliquer un coup, une partie ou un mot | Étape 1f |
| [mes-parties.feature](mes-parties.feature) | Retrouver mes parties, leurs branches, les exporter en SGF | Étape 1b |
| [partager-une-position.feature](partager-une-position.feature) | Ouvrir et partager le lien d'une position | Étape 0e.4 |
| [regler-l-application.feature](regler-l-application.feature) | Régler l'application (menu), la mettre à jour | Étape 0e |
| [decouvrir-l-application.feature](decouvrir-l-application.feature) | Premier lancement et accueil | Étape 0e.5 |
| [apprendre-les-regles.feature](apprendre-les-regles.feature) | Apprendre les règles avec le tutoriel | Étape 0e.5 |
| [suivre-une-lecon.feature](suivre-une-lecon.feature) | Progresser avec les leçons, garder sa progression | Étape 1g |
| [suivre-ma-progression.feature](suivre-ma-progression.feature) | Suivre sa progression : courbe du taux d'erreur, parties, exercices | Étape 1h |
| [installer-l-application.feature](installer-l-application.feature) | Installer l'application | Étape 0e.5 |