ci(optimiseur): récupération du moteur, génération et --check de la référence optimiseur

Nouvelle étape : clone --depth 1 de la branche par défaut du moteur
(même jeton, branche lue par l'API Gitea, comme pour les plugins) dans
.engine-src/ ; un échec de clone fait échouer le build, faute de quoi la
référence serait générée sans source. Génération avant mkdocs build,
--check avec les autres contrôles d'idempotence.

README : ligne du tableau des générateurs, commandes locales, pipeline,
et la règle de langue de ce bloc (cadre anglais, descriptions du
contrat en français, non traduites).

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

.gitea/workflows/docs.yml

@@ -56,6 +56,31 @@ jobs:
               || echo "WARNING: ${repo} introuvable ou inaccessible — ignoré"
           done
 
+      # ── Récupération du contrat optimiseur depuis le moteur ──────────────
+      # Source de vérité de la section Optimiseur : le contrat OpenRPC du moteur.
+      # Pas de « || echo WARNING » ici : sans contrat, le générateur échoue et
+      # rien n'est publié (mieux qu'une référence muette).
+      - name: Fetch engine (optimizer protocol contract)
+        env:
+          GITEA_TOKEN: ${{ secrets.MKDOCS_TOKEN }}
+        run: |
+          cd /root/_work/powersync-docs
+          GITEA_BASE="https://git.etm-powersync.fr"
+          AUTH_BASE="https://pakutz79:${GITEA_TOKEN}@git.etm-powersync.fr"
+          repo=etm-powersync-energy-plugin-etm
+          mkdir -p .engine-src
+
+          BRANCH=$(curl -sf \
+            -H "Authorization: token ${GITEA_TOKEN}" \
+            "${GITEA_BASE}/api/v1/repos/ETM-Schurig/${repo}" \
+            | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('default_branch','main'))" \
+            2>/dev/null) || BRANCH="main"
+
+          echo "→ ${repo} (branche: ${BRANCH})"
+          git clone --depth 1 --branch "${BRANCH}" \
+            "${AUTH_BASE}/ETM-Schurig/${repo}.git" \
+            ".engine-src/${repo}"
+
       # ── Génération de la doc ──────────────────────────────────────────────
       - name: Generate device reference + SUMMARY.md
         run: |
@@ -73,6 +98,13 @@ jobs:
             --src introspect.json \
             --docs docs
 
+      - name: Generate optimizer protocol reference
+        run: |
+          cd /root/_work/powersync-docs
+          python3 scripts/gen_optimizer_reference.py \
+            --src .engine-src/etm-powersync-energy-plugin-etm \
+            --docs docs
+
       # ── Build MkDocs ──────────────────────────────────────────────────────
       # i18n construit les trois langues en une passe : site/ (fr), site/de/, site/en/.
       - name: MkDocs build --strict
@@ -90,6 +122,10 @@ jobs:
             --lang fr \
             --locales fr,de,en \
             --check
+          python3 scripts/gen_optimizer_reference.py \
+            --src .engine-src/etm-powersync-energy-plugin-etm \
+            --docs docs \
+            --check
 
       # ── SSH ───────────────────────────────────────────────────────────────
       - name: Setup SSH deploy key

.gitignore

@@ -2,3 +2,4 @@
 site/
 .plugins-src/
 .claude/
+.engine-src/

README.md

@@ -23,6 +23,7 @@ est produit par un script depuis une source de vérité, et **écrasé à chaque
 |---|---|---|
 | `scripts/gen_device_reference.py` | `PORTING_STATUS.yaml` + les `integrationplugin*.json` et `meta.json` des 5 dépôts de plugins | fiches appareils, index de catégorie, matrice de compatibilité, `appareils/SUMMARY.md` |
 | `scripts/gen_api_reference.py` | `introspect.json` (introspection nymea) | référence JSON-RPC (23 pages), `api/SUMMARY.md` |
+| `scripts/gen_optimizer_reference.py` | `docs/etm-powersync-optimizer-protocol.openrpc.json` du moteur (`etm-powersync-energy-plugin-etm`, branche par défaut) | tableaux de messages, listes fermées, règles nommées et machine de repli de `optimiseur/protocole*.md`, fiche de `optimiseur/contrat*.md`, copie servie du contrat ; garde-fou de contenu (IP privées, « cloud », « Héos ») |
 
 ## Multi-langue — où passe la frontière
 
@@ -35,6 +36,10 @@ Deux régimes, et ils ne se traitent pas pareil :
   pour `fr_FR`, `de_DE` et `en_US`. Les noms de modèles, de registres et d'unités sont donc
   déjà en anglais ; traduire les seuls en-têtes de colonnes autour aurait fabriqué des pages
   bilingues sans rien gagner. Le vocabulaire vit dans le dict `REF` de chaque générateur.
+  **Cas particulier, la référence optimiseur** (2026-10-18) : le cadre est en anglais
+  comme partout, mais les descriptions viennent du contrat du moteur, écrit en
+  français. Les traduire ici ferait une seconde vérité : elles sont reprises telles
+  quelles, et l'en-tête de colonne le dit (« from the contract, French »).
 - **La prose et la navigation se TRADUISENT.** Fichiers suffixés (`page.md` = fr,
   `page.de.md`, `page.en.md`), libellés de nav par `nav_translations` dans `mkdocs.yml`,
   échafaudage des pages créées par le dict `SCAFFOLD` du générateur appareils.
@@ -70,10 +75,17 @@ python3 scripts/gen_device_reference.py --src .plugins-src --docs docs \
 # Régénérer la référence API
 python3 scripts/gen_api_reference.py --src introspect.json --docs docs
 
+# Régénérer la référence du protocole optimiseur — exige le contrat OpenRPC du moteur
+# (la CI clone le moteur dans .engine-src/ ; en local, --src accepte le clone,
+# un dossier qui contient le fichier, ou le fichier lui-même)
+python3 scripts/gen_optimizer_reference.py --src .engine-src/etm-powersync-energy-plugin-etm --docs docs
+
 # Ce que vérifie la CI : rien ne doit changer après régénération
 mkdocs build --strict
 python3 scripts/gen_device_reference.py --src .plugins-src --docs docs \
         --lang fr --locales fr,de,en --check
+python3 scripts/gen_optimizer_reference.py --src .engine-src/etm-powersync-energy-plugin-etm \
+        --docs docs --check
 ```
 
 ### Le sélecteur de langue
@@ -100,8 +112,9 @@ contextuel du sélecteur de langue de `mkdocs-static-i18n`. Le commentaire est d
 
 CI Gitea (`.gitea/workflows/docs.yml`) sur push vers `main`, plus un passage nocturne à 3 h
 (les `meta.json` des dépôts de plugins bougent sans que ce dépôt-ci bouge). Pipeline :
-clone des 5 dépôts de plugins → génération appareils → génération API → `mkdocs build
---strict` → contrôle d'idempotence → `rsync` vers le serveur.
+clone des 5 dépôts de plugins et du moteur → génération appareils → génération API →
+génération optimiseur → `mkdocs build --strict` → contrôle d'idempotence → `rsync` vers
+le serveur.
 
 Le build produit `site/` (fr), `site/de/` et `site/en/` en une passe ; le `rsync --delete`
 pousse l'ensemble.