Docs: define Hit@5 and MRR next to the reported scores

The README table was a pair of unexplained numbers. Spell out recall vs ranking here, and expand EVAL.md §2 with the formulas used on this corpus.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.fr.md

@@ -83,6 +83,19 @@ complet : [`docs/rag/DESIGN.md` §9](docs/rag/DESIGN.md#user-content-9-pourquoi-
 | Sécurité (red-team, gate, refus, injection-evidence) | 20/20 |
 | Surcoût rerank | ~100 ms |
 
+**Hit@5** : part des questions d'éval dont le fil (ou le post) attendu
+apparaît dans les **5 premiers** résultats. 0.97 = la bonne source est
+dans ce top-5 97 fois sur 100. Ça ne dit pas *où* dans les cinq.
+
+**MRR** (*Mean Reciprocal Rank*, rang réciproque moyen) : on note le
+**rang du premier** hit pertinent, puis on moyenne. Rang 1 → 1, rang 2 →
+0.5, rang 5 → 0.2, absent → 0. 0.89 = le premier bon hit est le plus
+souvent 1er ou 2e, pas seulement « quelque part dans le top-5 ».
+
+Hit@5 = rappel (« est-ce qu'on a raté ? »). MRR = classement (« est-ce
+qu'on l'a mis en haut ? »). Protocole et formules :
+[`docs/rag/EVAL.md` §2](docs/rag/EVAL.md#user-content-2-métriques).
+
 Détail : [`docs/rag/EVAL.md`](docs/rag/EVAL.md) ·
 [`docs/rag/SAFETY.md`](docs/rag/SAFETY.md) ·
 [`docs/rag/PIPELINE.md`](docs/rag/PIPELINE.md) ·

README.md

@@ -82,6 +82,19 @@ pipeline in direct code, instrumented for evaluation. Full reasoning:
 | Safety (red-team, gate, refusal, evidence injection) | 20/20 |
 | Rerank overhead | ~100 ms |
 
+**Hit@5** : share of eval questions whose expected thread (or post) appears
+in the **top 5** retrieved results. 0.97 means the right source is in that
+shortlist 97 times out of 100. It does not say *where* in the five.
+
+**MRR** (Mean Reciprocal Rank) : scores the **rank of the first** relevant
+hit, then averages. Rank 1 → 1, rank 2 → 0.5, rank 5 → 0.2, not in the
+list → 0. 0.89 means the first good hit is usually 1st or 2nd, not merely
+"somewhere in the top 5".
+
+Hit@5 = recall ("did we miss it?"). MRR = ranking ("did we put it first?").
+Protocol and formulas :
+[`docs/rag/EVAL.md` §2](docs/rag/EVAL.md#user-content-2-métriques).
+
 Details: [`docs/rag/EVAL.md`](docs/rag/EVAL.md) ·
 [`docs/rag/SAFETY.md`](docs/rag/SAFETY.md) ·
 [`docs/rag/PIPELINE.md`](docs/rag/PIPELINE.md) ·

docs/rag/EVAL.md

@@ -55,13 +55,52 @@ Couverture réelle (101 questions, `questions.yml` sections A–J) :
 
 ## 2. Métriques
 
-### Retrieval (automatique)
+Les deux chiffres du README (**Hit@5 = 0.97**, **MRR = 0.89**) mesurent
+**uniquement le retrieval** (le bon fil/post remonte-t-il ?), pas la
+qualité de la phrase générée. Ils sont calculés sur le jeu golden
+(`questions.yml`) : chaque question a un ou plusieurs `expected_topic_ids`
+(et parfois `expected_post_ids`).
+
+### Hit@5 (rappel dans le top-5)
+
+Pour une question, le retrieval **réussit** si **au moins un** document
+golden apparaît dans les 5 premiers résultats. Hit@5 = cette réussite
+moyennée sur le jeu (0 ou 1 par question).
+
+- **0.97** (config E, n=796) : 97 questions sur 100 voient le bon fil dans
+  le top-5.
+- Un Hit@5 à 1.0 avec le bon fil toujours en 5e place resterait « parfait »
+  au sens du rappel, et mauvais au classement → d'où le MRR à côté.
+- Variantes dans les tableaux : **Hit@k topic** (le fil golden est dans le
+  top-k) ; **Hit@k post** (le *message* golden est dans le top-k, grain
+  post uniquement). Le chiffre vitrine est le Hit@5 **topic** à l'échelle
+  (lot K). Les premières passes utilisaient aussi k ∈ {3, 6} sur le lot
+  curé A–J.
+
+### MRR — Mean Reciprocal Rank (classement du premier hit)
+
+Pour chaque question : `1 / rang` du **premier** résultat pertinent
+(1er → 1, 2e → 0.5, 3e → ≈ 0.33, 5e → 0.2). Si le golden est hors de la
+liste renvoyée : **0**. MRR = moyenne de ces scores.
+
+- **0.89** (config E) : le premier hit pertinent est en pratique 1er ou
+  2e, rarement 4e/5e.
+- Contrairement au Hit@5, un golden passé de #1 à #5 **fait baisser** le
+  MRR (1 → 0.2) même s'il reste « dans le top-5 ».
+
+En une ligne : **Hit@5 = est-ce qu'on a raté ?** · **MRR = est-ce qu'on
+l'a mis en haut ?** Le saut topic → post (0.68 → 0.94 Hit@5) est le gain
+principal ; le rerank (0.94 → 0.97 Hit@5, 0.84 → 0.89 MRR) améliore
+surtout l'ordre.
+
+### Retrieval (automatique) — récap
 
 | Métrique | Définition |
 |---|---|
-| **Hit@k topic** | au moins un `expected_topic` dans le top-k (k ∈ {3, 6}) |
+| **Hit@5 topic** | au moins un `expected_topic` dans le top-5 (chiffre README) |
+| **Hit@k topic** | idem pour un k donné (lots A–J : aussi k ∈ {3, 6}) |
 | **Hit@k post** | le `expected_post` dans le top-k posts (grain post uniquement) |
-| MRR | rang du premier hit pertinent |
+| **MRR** | moyenne de `1/rang` du premier hit pertinent (0 si absent) |
 | Pollution | slots evidence occupés par un même topic (mesure l'agrégation) |
 
 ### Génération (semi-auto)