From 5c311603441430192f22367c2603ced436931515 Mon Sep 17 00:00:00 2001
From: Nabil Derouiche <nabil@bolbol.tn>
Date: Wed, 24 Jun 2026 14:46:42 +0000
Subject: [PATCH] runbook: rich_messages Telegram flag + Portainer API restart

---
 _INDEX.md                        |  1 +
 common/rich-messages-telegram.md | 97 ++++++++++++++++++++++++++++++++
 2 files changed, 98 insertions(+)
 create mode 100644 common/rich-messages-telegram.md

diff --git a/_INDEX.md b/_INDEX.md
index 0181194..15d2013 100644
--- a/_INDEX.md
+++ b/_INDEX.md
@@ -36,3 +36,4 @@
 - **Lecture** : tous les dossiers sont lisibles par toutes les instances
 - **Format** : utiliser RUNBOOK-TEMPLATE.md
 - **Apres chaque runbook** : poster une note NyoraNotes avec tag [infra, runbook]
+- [common/rich-messages-telegram.md](common/rich-messages-telegram.md) — Telegram rich_messages flag + restart Portainer API (2026-06-24)
diff --git a/common/rich-messages-telegram.md b/common/rich-messages-telegram.md
new file mode 100644
index 0000000..b520fb8
--- /dev/null
+++ b/common/rich-messages-telegram.md
@@ -0,0 +1,97 @@
+# RUNBOOK — Telegram rich_messages + restart via Portainer API
+
+**Statut** : Validé 2026-06-24  
+**Scope** : Toutes instances Hermes (tt / nyora / perso / Desktop MacBook)
+
+---
+
+## Symptôme
+
+Instance Hermes envoie des messages Telegram en texte brut : pas de MD tables, pas de gras, pas d'emoji. Une autre instance fonctionne bien.
+
+## Cause racine
+
+Flag `rich_messages: false` dans `config.yaml` de l'instance.
+
+```yaml
+# /opt/data/config.yaml (vue depuis le container)
+# = /mnt/docker/hermes-platform/<instance>/data/config.yaml (vue depuis le NAS)
+telegram:
+  extra:
+    rich_messages: false   # ← coupable
+```
+
+## Fix (30 secondes)
+
+```bash
+# Depuis le NAS ou mcp-nas :
+sed -i 's/rich_messages: false/rich_messages: true/' \
+  /mnt/docker/hermes-platform/<instance>/data/config.yaml
+
+# Vérifier :
+grep rich_messages /mnt/docker/hermes-platform/<instance>/data/config.yaml
+# → rich_messages: true
+```
+
+Puis redémarrer l'agent (voir section ci-dessous).
+
+## Effet de rich_messages: true
+
+- Pipe tables MD rendues nativement dans Telegram
+- Gras, italique, emoji fonctionnels
+- Messages **texte** (pas d'image/screenshot) → légers, sélectionnables, copiables, modifiables
+- Méthode `telegram-output` skill : pipe MD direct, sans pipeline HTML → Browser → Screenshot
+
+## Redémarrer un agent Hermes depuis mcp-nas (sans SSH)
+
+SSH inaccessible depuis mcp-nas. Pas d'endpoint `/reload` sur l'agent. **Solution : Portainer API.**
+
+```bash
+# 1. Authentification
+TOKEN=$(curl -s -X POST http://172.17.0.1:9000/api/auth \
+  -H "Content-Type: application/json" \
+  -d '{"username":"bestof","password":"<PORTAINER_PASSWORD>"}' \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['jwt'])")
+
+# 2. Trouver l'ID du container
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "http://172.17.0.1:9000/api/endpoints/2/docker/containers/json?all=true" \
+  | python3 -c "
+import sys, json
+for c in json.load(sys.stdin):
+    name = c['Names'][0].lstrip('/')
+    if 'hermes' in name:
+        print(c['Id'][:12], name, c['State'])
+"
+
+# 3. Restart
+curl -s -o /dev/null -w "%{http_code}" -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  "http://172.17.0.1:9000/api/endpoints/2/docker/containers/<ID>/restart"
+# → 204 = succès
+
+# 4. Vérifier santé (attendre ~15s)
+sleep 15 && curl -s http://hermes-agent-<instance>:8642/health
+# → {"status": "ok", ...}
+```
+
+## IDs containers (juin 2026 — peuvent changer après recreate)
+
+| Container | ID court |
+|---|---|
+| hermes-agent-tt | eb44e9c8225f |
+| hermes-agent-nyora | d5f198348abb |
+| hermes-agent-perso | 91f7d7cec688 |
+
+> ⚠️ Les IDs changent après `docker compose up --force-recreate`. Toujours re-lister si le restart renvoie 404/500.
+
+## Application MacBook Hermes Desktop
+
+Même mécanique, même `config.yaml`, même flag. **Vérifier `rich_messages: true` en premier** avant tout debug Telegram sur une nouvelle instance.
+
+Les credentials Portainer sont dans `/volume1/docker/hermes-platform/.env` (NAS) ou l'équivalent local sur le Mac.
+
+---
+
+**Runbook lié** : `common/portainer-api-container-ops.md` (à créer si besoin)  
+**Note NyoraNotes** : vault hermes-perso, tags [infra, runbook, telegram]