docs(HOWTO): add Cas 2.5 — http forward handler (Phase 2a livrée)

HOWTO_ADD_BOT.md

@@ -98,19 +98,65 @@ Steps (humain ou session Claude avec accès au cluster + au repo) :
    - Si `requireAuth` est laissé à true : envoie un message → réponse `🔒 /auth chez @arcodange_factory_bot` ; fais `/auth <code>` chez factory ; renvoie un message → echo en < 2 s.
    - Si `requireAuth: false` : echo direct en < 2 s.
 
-**Limite Phase 1** : tous les bots ont le handler `echo` ou `auth`. Pas encore de routage vers une logique métier différente par bot — voir Cas 3.
+**Limite handler `echo`** : tous les bots `echo` répondent toujours pareil. Pour de la logique métier, voir Cas 2.5 (HTTP forward) ou Cas 3 (agent async).
 
 ---
 
-## Cas 3 — Bot interactif piloté par un agent (Phase 3, pas encore livré)
+## Cas 2.5 — Bot piloté par un service interne via HTTP forward (Phase 2a, livré)
 
-Cible : utilisateur DM le bot → gateway déclenche un wrapper shell (ex. `claude --print`, `mistral-vibe`, ou un script Python qui appelle Ollama) → la réponse est renvoyée via Telegram.
+Cible : un service du cluster (par ex. `webapp`, ou un mini-service Go/Python dédié) reçoit l'`Update` Telegram complet en POST JSON, traite sa logique, renvoie `{"text": "<reply>"}`. Le gateway envoie `text` au user.
 
-Pour l'instant **non supporté** côté gateway. Phases requises :
+Sync : le webhook ack attend la réponse (timeout par défaut 5 s, plafond 30 s — Telegram coupe vers 60 s). Pour des backends lents, voir Cas 3.
-- Phase 2 (queue Postgres + handler `http`) → permet à un service in-cluster d'être le handler
-- Phase 3 (handlers async `shell` / `script` / `ollama` + retry pour Macbook endormi)
 
-Quand Phase 3 sera up, le ajout d'un tel bot sera : steps Cas 2 + handler `shell`/`script`/`ollama` au lieu d'`echo`, plus la commande/script à exécuter.
+Setup côté gateway (suit Cas 2 pour le bot Telegram + le Secret) puis :
+
+1. **Déclarer le bot avec `handler: http`** dans `chart/values.yaml` :
+
+   ```yaml
+   bots:
+     webappbot:
+       handler: http
+       http:
+         url: http://webapp.webapp.svc.cluster.local:8080/telegram/update
+         timeout: 5s
+       # requireAuth: true  (implicite — défaut sécurisé)
+   ```
+
+2. **Côté service interne**, exposer un endpoint qui :
+   - Accepte `POST <url>` avec un body = JSON Telegram `Update` (champs : `update_id`, `message.text`, `message.from.id`, `message.chat.id`, etc.)
+   - Lit le header `X-Bot-Slug: <slug>` pour distinguer plusieurs bots qui forwarderaient au même service
+   - Renvoie `200 {"text": "réponse au user"}` (ou `200` body vide si pas de réponse à envoyer)
+   - Respecte le timeout configuré (le gateway coupe à `timeout`)
+
+3. **Push values.yaml + rollout** comme dans Cas 2.
+
+Exemple minimal de upstream service (Go) :
+
+```go
+http.HandleFunc("/telegram/update", func(w http.ResponseWriter, r *http.Request) {
+    var u struct {
+        Message struct {
+            Text string `json:"text"`
+            From struct{ ID int64 `json:"id"` } `json:"from"`
+        } `json:"message"`
+    }
+    json.NewDecoder(r.Body).Decode(&u)
+    reply := fmt.Sprintf("hello user %d, you said: %s", u.Message.From.ID, u.Message.Text)
+    json.NewEncoder(w).Encode(map[string]string{"text": reply})
+})
+```
+
+---
+
+## Cas 3 — Bot interactif piloté par un agent async (Phase 3, pas encore livré)
+
+Cible : utilisateur DM le bot → gateway enqueue le job → worker async exécute un wrapper shell (ex. `claude --print`, `mistral-vibe`, ou un script Python qui appelle Ollama) → la réponse est renvoyée via Telegram, **même si le backend (Macbook Ollama) dort au moment du DM** (retry exponentiel jusqu'à 1 h).
+
+Pour l'instant **non supporté**. Requiert :
+- Phase 2b (queue Postgres + worker — fondation async)
+- Phase 3 (handlers `shell` / `script` / `ollama` + WoL Macbook optionnel)
+
+Quand Phase 3 sera up, l'ajout d'un tel bot sera : steps Cas 2 + handler `shell`/`script`/`ollama` au lieu d'`echo`, plus la commande/script à exécuter.
 
 Plan complet : `~/.claude/plans/pour-les-notifications-on-inherited-seal.md`.
 
@@ -118,9 +164,9 @@ Plan complet : `~/.claude/plans/pour-les-notifications-on-inherited-seal.md`.
 
 ## Récap : quel cas choisir ?
 
-| Besoin | Cas | Gateway impliqué ? |
+| Besoin | Cas | État | Gateway impliqué ? |
-|---|---|---|
+|---|---|---|---|
-| Notifs sortantes one-way (Cowork → user) | Cas 1 | non, Bot API directe |
+| Notifs sortantes one-way (Cowork → user) | Cas 1 | livré | non, Bot API directe |
-| Bot qui répond toujours pareil (echo, ack, ping) | Cas 2 | oui (Phase 1) |
+| Bot qui répond toujours pareil (echo, ack, ping) | Cas 2 | livré (Phase 1) | oui |
-| Bot conversationnel piloté par agent (Claude / Mistral / Ollama / script) | Cas 3 | oui (Phase 3, futur) |
+| Bot piloté par un service interne du cluster (webapp, mini-service custom) | Cas 2.5 | **livré (Phase 2a)** | oui |
-| Bot qui forwarde au backend d'une app cluster (webapp, etc.) | Cas 3 | oui (Phase 2, futur) |
+| Bot conversationnel piloté par agent async (Claude / Mistral / Ollama / script, retry si backend dort) | Cas 3 | futur (Phase 3) | oui |