diff --git a/AGENTS.md b/AGENTS.md
index 6531c3b..915d9c4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -523,6 +523,21 @@ supérieures n'affecte pas les couches inférieures. Voir `docs/SAFETY.md` pour
    `Doxyfile` (frontière = un répertoire) et se documentent à la main. Leur inventaire
    est tenu dans `energyplugin/smartchargingmanager.h`, au marqueur `[ETM] BEGIN` —
    toute nouvelle marque `[ETM]` dans un en-tête amont s'y ajoute.
+6. **Génération de la doc : `./tools/gen-doc.sh`, et rien d'autre.** Une commande
+   unique, le `Doxyfile` du dépôt, épinglé. Un compte d'avertissements ne vaut que
+   rattaché à une configuration exacte — 163 sans générateur de sortie contre 113 avec
+   HTML+XML sur le même arbre — donc un chiffre produit « à sa façon » ne se compare à
+   rien. Le script signale aussi une version de doxygen différente de la référence.
+   - **Dépendances : `doxygen` et `graphviz`, de la CIBLE DOC uniquement.** Le paquet se
+     construit sans elles ; le conteneur `build-cross-arm64` n'a rien à faire de
+     Graphviz. Ne pas les ajouter aux `Build-Depends`.
+   - `CALL_GRAPH`/`CALLER_GRAPH` restent à `NO` **délibérément** : le moteur est
+     signal-driven, `powerBalanceChanged → verifyOverloadProtection()` est une connexion
+     Qt et non un appel. Un graphe d'appel montrerait `update()` en point d'entrée
+     orphelin et raterait le mécanisme principal de la couche L4.
+   - Le graphe d'héritage est **tronqué par construction** : `SmartChargingManager` est
+     hors `INPUT`. Ne pas élargir le périmètre pour « réparer » — cela ferait entrer tout
+     l'amont dans la mesure.
 
 ## ROADMAP — configuration des priorités par l'utilisateur (post-beta)
 
diff --git a/Doxyfile b/Doxyfile
index 6d67a6a..0d0b8c2 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -11,6 +11,14 @@
 # sont peu nombreux, déjà marqués, et documentés à la main — cf. la définition
 # de fait dans AGENTS.md.
 #
+# ATTENTION — le graphe d'héritage sera TRONQUÉ, et c'est voulu.
+# « class EnergyArbitrator : public SmartChargingManager » est l'arête la plus
+# intéressante du dépôt, et elle n'apparaîtra pas : la classe de base vit dans
+# energyplugin/, hors INPUT, donc doxygen ne la résout pas. Élargir INPUT pour
+# « réparer » le graphe ferait entrer tout le code amont dans la mesure et
+# ferait exploser le compte d'avertissements — exactement ce que le périmètre
+# ci-dessus évite. Le graphe est incomplet par choix, pas par oubli.
+#
 # ATTENTION — le nombre d'avertissements dépend des générateurs de sortie
 # activés. Sans aucun générateur, doxygen 1.9.8 émet des « not documented » sur
 # des membres qui SONT documentés (constaté : 163 sans sortie, 113 avec
@@ -82,4 +90,36 @@ MARKDOWN_SUPPORT       = YES
 OPTIMIZE_OUTPUT_FOR_C  = NO
 HIDE_UNDOC_MEMBERS     = NO
 HIDE_UNDOC_CLASSES     = NO
-HAVE_DOT               = NO
+
+# --- Graphes (Graphviz) ----------------------------------------------------
+# graphviz est une dépendance de la CIBLE DOC, pas du build du paquet : rien à
+# installer dans le conteneur build-cross-arm64, qui n'a que faire de dot.
+#   Debian/Ubuntu : apt install graphviz
+HAVE_DOT               = YES
+
+# CALL_GRAPH / CALLER_GRAPH restent à NO, et ce n'est pas une question de coût.
+# Le moteur est SIGNAL-DRIVEN : powerBalanceChanged → verifyOverloadProtection()
+# n'est pas un appel mais une connexion Qt, invisible à l'analyse statique. Un
+# graphe d'appel montrerait update() comme un point d'entrée orphelin et
+# raterait le mécanisme principal de la couche L4. Un schéma faux vaut moins
+# que pas de schéma.
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+
+# Ce que dot apporte réellement ici : héritage, collaboration, inclusions.
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = NO
+DIRECTORY_GRAPH        = YES
+TEMPLATE_RELATIONS     = NO
+
+# SVG : lisible à toute échelle et diffable, contrairement au PNG.
+DOT_IMAGE_FORMAT       = svg
+INTERACTIVE_SVG        = YES
+
+# Au-delà, doxygen tronque plutôt que de produire un pavé illisible — un graphe
+# qu'on ne peut pas lire ne documente rien.
+DOT_GRAPH_MAX_NODES    = 60
+MAX_DOT_GRAPH_DEPTH    = 3
+DOT_CLEANUP            = YES
diff --git a/tools/gen-doc.sh b/tools/gen-doc.sh
new file mode 100755
index 0000000..1342e61
--- /dev/null
+++ b/tools/gen-doc.sh
@@ -0,0 +1,81 @@
+#!/bin/bash
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2025 - 2026, Patrick Schurig / ETM PowerSync
+#
+# Génération reproductible de la documentation — UNE seule commande, le Doxyfile
+# du dépôt, épinglé.
+#
+#   ./tools/gen-doc.sh
+#
+# Pourquoi une commande unique plutôt qu'un « doxygen » lancé à la main : le
+# nombre d'avertissements NE VEUT RIEN DIRE hors de sa configuration exacte. Le
+# piège a déjà été rencontré — 163 avertissements sans générateur de sortie
+# contre 113 avec HTML+XML, sur le même arbre. Un chiffre de référence ne se
+# compare qu'à un chiffre produit de la même façon ; ce script est cette façon.
+#
+# DÉPENDANCES — de la CIBLE DOC uniquement, jamais du build du paquet :
+#     apt install doxygen graphviz
+# Le conteneur build-cross-arm64 n'a rien à faire de Graphviz : il compile, il
+# ne dessine pas.
+
+set -u
+
+RACINE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DOXYFILE="$RACINE/Doxyfile"
+SORTIE="$RACINE/doc-generated"
+VERSION_ATTENDUE="1.9.8"
+
+cd "$RACINE" || exit 1
+
+manquant=0
+for outil in doxygen dot; do
+    if ! command -v "$outil" >/dev/null 2>&1; then
+        echo "MANQUANT : $outil" >&2
+        manquant=1
+    fi
+done
+if [ "$manquant" -ne 0 ]; then
+    echo "" >&2
+    echo "Dépendances de la cible doc : apt install doxygen graphviz" >&2
+    exit 127
+fi
+
+VERSION_REELLE="$(doxygen --version | cut -d' ' -f1)"
+if [ "$VERSION_REELLE" != "$VERSION_ATTENDUE" ]; then
+    # Avertissement et non erreur : la génération reste utile, mais le compte
+    # d'avertissements n'est plus comparable au chiffre de référence.
+    echo "ATTENTION : doxygen $VERSION_REELLE, référence établie sous $VERSION_ATTENDUE." >&2
+    echo "            Les graphes restent valables ; le COMPTE d'avertissements," >&2
+    echo "            lui, n'est pas comparable d'une version à l'autre." >&2
+fi
+
+rm -rf "$SORTIE"
+JOURNAL="$(mktemp)"
+trap 'rm -f "$JOURNAL"' EXIT
+
+doxygen "$DOXYFILE" 2>"$JOURNAL"
+code=$?
+
+# Le Doxyfile écrit déjà ses avertissements dans WARN_LOGFILE ; on compte ici ce
+# qui est réellement remonté, quelle que soit la destination.
+LOGFILE="$(sed -n 's/^WARN_LOGFILE *= *//p' "$DOXYFILE" | tr -d ' ')"
+if [ -n "$LOGFILE" ] && [ -f "$RACINE/$LOGFILE" ]; then
+    JOURNAL_EFFECTIF="$RACINE/$LOGFILE"
+else
+    JOURNAL_EFFECTIF="$JOURNAL"
+fi
+AVERTISSEMENTS="$(grep -c -i "warning" "$JOURNAL_EFFECTIF" 2>/dev/null || echo 0)"
+
+echo ""
+echo "  doxygen        $VERSION_REELLE   (référence $VERSION_ATTENDUE)"
+echo "  graphviz       $(dot -V 2>&1 | sed 's/^dot - graphviz version //; s/ .*//')"
+echo "  configuration  $DOXYFILE"
+echo "  sortie         $SORTIE  (html/ + xml/)"
+echo "  avertissements $AVERTISSEMENTS"
+echo ""
+echo "  Rappel : ce compte n'est comparable qu'à un compte produit par CE script."
+echo "  Rappel : le graphe d'héritage est tronqué par construction — la classe de"
+echo "           base amont SmartChargingManager est hors INPUT. Voir l'en-tête du"
+echo "           Doxyfile ; ne pas « réparer » en élargissant le périmètre."
+
+exit $code