diff --git a/common/nyora-doc-api-hermes-guide.md b/common/nyora-doc-api-hermes-guide.md
new file mode 100644
index 0000000..bd43bac
--- /dev/null
+++ b/common/nyora-doc-api-hermes-guide.md
@@ -0,0 +1,128 @@
+# nyora-doc-api — Guide d'usage pour Hermes (v3 Premium)
+
+Service : `http://nyora-doc-api:8000` (interne réseau `n8n`) ou `http://172.17.0.1:3050` (depuis un container hors réseau n8n).
+Auth : header `x-api-key: nyora-doc-2026`.
+Endpoint unique : `POST /v1/generate` (multipart/form-data).
+
+## Formats disponibles sans aucun fichier joint (mode "données pures")
+
+XLSX, PPTX, DOCX et PDF peuvent tous être générés à partir de JSON seul,
+sans template Word/Excel préexistant. C'est le mode à utiliser par défaut
+pour tout Hermes qui génère un rapport, une note ou un tableau à la volée.
+
+Champs de formulaire communs :
+- `format` : `xlsx` | `docx` | `pptx` | `pdf`
+- `data` : JSON (voir schémas ci-dessous)
+- `options` : JSON, ex. `{"theme": "nyora"}` (ou `"tt"` pour la palette Tunisie Telecom)
+- `output_name` : nom de fichier sans extension
+
+## Schéma unifié DOCX / PDF ("sections")
+
+Le même JSON produit un DOCX ou un PDF selon le `format` demandé — pas besoin
+de réécrire le contenu deux fois.
+
+```json
+{
+  "title": "Titre du document",
+  "subtitle": "Sous-titre optionnel",
+  "date": "01/07/2026",
+  "sections": [
+    {"heading": "Titre de section", "level": 1, "text": "Paragraphe.\n\nDeuxième paragraphe (séparer par une ligne vide)."},
+    {"bullet_list": ["Point 1", "Point 2"]},
+    {"numbered_list": ["Étape 1", "Étape 2"]},
+    {"table": {
+      "headers": ["Region", "Budget", "Réalisé"],
+      "rows": [["Sfax", 1250000, 987654.321]],
+      "totals": true
+    }}
+  ]
+}
+```
+
+## Schéma XLSX ("sheets")
+
+```json
+{
+  "title": "Titre optionnel (affiché en en-tête fusionné de la feuille)",
+  "sheets": [
+    {
+      "name": "Budget",
+      "totals": true,
+      "headers": ["Region", "Budget", "Réalisé", "Ecart %"],
+      "rows": [["Sfax", 1250000, 987654.321, -21.048]]
+    }
+  ]
+}
+```
+
+## Schéma PPTX ("slides")
+
+```json
+{
+  "title": "Titre (génère une slide de couverture automatique)",
+  "subtitle": "Sous-titre optionnel",
+  "cover": true,
+  "slides": [
+    {"title": "Titre de slide", "kpis": [{"label": "Budget", "value": 1250000}]},
+    {"title": "Détail", "table": {"headers": [...], "rows": [...], "totals": true}},
+    {"title": "Texte", "content": "Paragraphe de contenu libre."}
+  ]
+}
+```
+
+## Formatage numérique automatique
+
+Toute valeur numérique dans un tableau ou un KPI est automatiquement
+formatée en convention française premium : séparateur de milliers
+(espace insécable) + 3 décimales, ex. `1 250 000,000`.
+Si l'en-tête de colonne contient `%`, `pourcent` ou `taux`, un suffixe
+`%` est ajouté automatiquement : `-21,048 %`.
+Pas besoin de pré-formater les nombres côté Hermes — envoyer les valeurs
+brutes (int ou float).
+
+Pour XLSX, le format Excel natif est appliqué (`#,##0.000`), donc le
+séparateur affiché suit la langue d'Excel de l'utilisateur — c'est le
+comportement standard et correct.
+
+## Totaux automatiques
+
+Ajouter `"totals": true` sur un `sheet` (xlsx), un `table` (docx/pdf/pptx)
+calcule et affiche automatiquement la somme de chaque colonne numérique,
+avec un style visuellement distinct (fond gris-or, gras).
+
+## Mode template (documents officiels TT)
+
+Pour les documents avec en-tête officiel (lettre TT, note interne), utiliser
+`template_name` au lieu de laisser DOCX en mode données :
+- `template_name=papier-entete-tt`
+- `template_name=note-tt-template`
+
+Dans ce cas, `data` doit correspondre aux variables Jinja du template
+(`{{ destinataire }}`, `{{ objet }}`, etc. — voir le contenu du template
+pour la liste exacte), pas au schéma "sections" ci-dessus.
+
+## Exemple d'appel curl (référence pour construire l'appel HTTP depuis n8n/Hermes)
+
+```bash
+curl -X POST http://nyora-doc-api:8000/v1/generate \
+  -H "x-api-key: nyora-doc-2026" \
+  -F "format=pdf" \
+  -F 'data={"title":"Note","sections":[{"heading":"Contexte","text":"..."}]}' \
+  -F "output_name=ma_note" \
+  -o ma_note.pdf
+```
+
+## Limitations connues (non bloquantes)
+
+- `generate_csv` a une signature incompatible avec l'appel générique dans
+  `main.py` (`GENERATORS[fmt](template_path, ...)` passe 4 arguments à une
+  fonction qui n'en attend que 3) — le format `csv` échoue actuellement.
+  Non corrigé à ce stade (hors périmètre de la mise à niveau premium du
+  01/07/2026), à traiter séparément si `csv` devient nécessaire.
+- Mode template DOCX/PPTX (fichier Word/PPTX existant) : le restyle de
+  police ne s'applique qu'aux styles de paragraphe, pas au formatage direct
+  des runs déjà présents dans le template (limitation structurelle de
+  Word/PowerPoint, déjà documentée en mémoire depuis le 30/06/2026).
+
+---
+*Document créé le 01/07/2026 lors de la mise à niveau premium v3 de nyora-doc-api.*