Guide d'utilisateur GUI ; Recoverable statement/Persp Gemini generation

docs/statement_recovery.md

@@ -0,0 +1,55 @@
+# Reprendre la génération Gemini de l’énoncé
+
+Relancez la même commande après une erreur ou une interruption :
+
+```sh
+python -m copienator statement Interro05
+```
+
+Sans `--restart`, les sources sont supposées inchangées. Les questions,
+solutions et contextes validés sont conservés dans `Cache/statement_*.json`.
+Une réponse lisible contenant un élément invalide conserve ses autres éléments
+valides. Les solutions et contextes incomplets sont redemandés pour leurs labels
+manquants. Une réponse JSON illisible reste archivée, mais ses éléments ne sont
+pas récupérés automatiquement.
+
+Les questions sont redemandées sous forme d’une liste complète et ordonnée :
+avant leur extraction, aucun inventaire indépendant de labels n’est disponible.
+Les labels déjà observés doivent rester présents. Vérifiez la liste contre
+`enonce.pdf` dans l’éditeur de groupes avant de l’approuver, notamment pour
+repérer une question que Gemini aurait entièrement omise.
+
+Les modifications de `Tmp/exam_items.txt` survivent à une interruption de
+l’éditeur. Après approbation, les groupes sont enregistrés dans
+`Cache/statement_grouping.json` ; une reprise utilise ce checkpoint sans rouvrir
+l’éditeur. Les fichiers générés déjà présents sont conservés, les fichiers
+manquants sont complétés, et seuls les PDF manquants, échoués ou plus anciens
+que leur source générée sont recompilés. Les contextes ne sont pas ajoutés une
+seconde fois lors d’une reprise.
+
+Les barèmes `Persp` valides sont conservés, y compris ceux des autres questions
+d’une réponse dont un barème est invalide. Les labels et groupes sont écrits
+avant la génération des barèmes et la compilation, ce qui permet aussi une
+reprise par `statement Interro05 --persp-only`.
+
+Toutes les réponses d’extraction sont archivées avant décodage dans
+`Cache/statement_responses/`. Les erreurs, avec le texte échappé et le chemin
+de la réponse, sont affichées et ajoutées à `Cache/statement_errors.log`.
+Les barèmes utilisent `Cache/rubric_responses/` et `Cache/rubric_errors.log`.
+Les anciens caches `gemini_questions.json`, `gemini_solutions.json` et
+`gemini_context.json` sont importés une fois : une réponse invalide n’est pas
+rechargée indéfiniment.
+
+Pour recommencer explicitement depuis les sources, notamment après les avoir
+modifiées :
+
+```sh
+python -m copienator statement Interro05 --restart
+```
+
+Les checkpoints et modifications des groupes précédents sont déplacés dans
+`Cache/statement_history/`. Les anciennes sorties y sont également déplacées
+quand la nouvelle extraction et les groupes sont prêts, avant leur remplacement.
+Une erreur d’extraction conserve donc les anciennes sorties. Les réponses brutes
+restent disponibles. Si ce nouveau départ échoue, relancez sans `--restart`
+pour reprendre sa progression.