docs(index): repair broken links + lock against drift

docs/index.md est l'index canonique de la documentation, référencé
depuis le README et utilisé comme première porte d'entrée pour les
nouveaux contributeurs. Il contenait 5 liens cassés survivants du
rewrite, aucun test ne les détectait :

- tutorials/first-benchmark.md (absent)
- tutorials/writing-a-pipeline-module.md (absent)
- user/writing-a-pipeline-module.md (dossier user/ absent)
- developer/narrative-engine.md(.en.md) (existe seulement dans explanation/)
- migration/rewrite-status-s46.md (en réalité dans archives/migration/)

Plus 3 affirmations fausses dans la section Conventions :
- "reports_v2" (renommé "reports" en Sprint H.3)
- "L'arbo legacy reste exécutable" (supprimée à v2.0)
- "baseline 73, doit décroître" (vrai baseline = 164)

Réparations :
- Création de docs/tutorials/first-benchmark.md (tutoriel d'entrée,
~110 lignes, agrège install + demo + premier benchmark + interface
web) qui était référencé par index.md depuis longtemps mais
n'existait pas.
- Création de docs/tutorials/writing-a-pipeline-module.md (tutoriel
par l'exemple) qui pointe vers developer/module-policy.md pour
les détails normatifs.
- Corrections des liens narrative-engine vers explanation/ (où ils
existent réellement).
- Correction du lien rewrite-status-s46.md vers archives/migration/.
- Réécriture de la section Conventions pour refléter v2.0.

Nouveau test tests/docs/test_index_links_resolve.py qui parse tous
les liens markdown internes de docs/index.md et vérifie qu'ils
résolvent vers un fichier ou dossier réel. Empêche structurellement
le retour de cette classe de mensonge silencieux.

docs/index.md

@@ -50,8 +50,8 @@ Vous ajoutez un adapter, une vue, une métrique, un détecteur narratif.
 4. Étendre un sous-système :
    [glossaire](developer/extending-glossary.md) ([EN](developer/extending-glossary.en.md)) ·
    [i18n](developer/extending-i18n.md) ([EN](developer/extending-i18n.en.md)) ·
-   [moteur narratif](developer/narrative-engine.md) ([EN](developer/narrative-engine.en.md))
-5. Écrire un module pour le banc d'essai : [`user/writing-a-pipeline-module.md`](user/writing-a-pipeline-module.md)
+   [moteur narratif](explanation/narrative-engine.md) ([EN](explanation/narrative-engine.en.md))
+5. Écrire un module pour le banc d'essai : [`tutorials/writing-a-pipeline-module.md`](tutorials/writing-a-pipeline-module.md)
 
 ### …un mainteneur ou auditeur de sécurité
 
@@ -63,7 +63,7 @@ Vous évaluez Picarones avant un déploiement, un audit, une revue.
 3. Threat model STRIDE : [`security/threat-model.md`](security/threat-model.md)
 4. API publique stable et politique de versioning : [`reference/api-stable.md`](reference/api-stable.md)
 5. Audits historiques : [`audits/`](audits/)
-6. État du rewrite et migration : [`migration/rewrite-status-s46.md`](migration/rewrite-status-s46.md)
+6. État du rewrite et migration : [`archives/migration/rewrite-status-s46.md`](archives/migration/rewrite-status-s46.md)
 7. Reproductibilité bit-for-bit : [`reference/reproducibility-snapshots.md`](reference/reproducibility-snapshots.md)
 
 ### …un Délégué à la Protection des Données (DPO)
@@ -146,15 +146,18 @@ Vous évaluez les implications RGPD avant signature.
 
 ## Conventions
 
-- **Une seule arborescence canonique post-rewrite** :
-  `domain → formats → evaluation → pipeline → adapters → app → reports_v2 → interfaces`.
-  L'arbo legacy `picarones/{cli,web,engines,llm,pipelines,report}/`
-  reste exécutable mais n'accepte plus de nouveau code.
+- **Une seule arborescence canonique (v2.0)** :
+  `domain → formats → evaluation → pipeline → adapters → app → reports → interfaces`.
+  Les paquets legacy ont été supprimés en mai 2026.
 - **Tout chemin `picarones/.../X.py` cité dans la doc doit exister**.
-  Vérifié par `tests/architecture/test_doc_paths.py` (baseline 73,
-  doit décroître).
-- **Les chiffres en prose qui dépendent de l'état du code** (compte
-  de tests, nombre d'adapters) sont régénérés par
-  `scripts/gen_readme_tables.py` — modifier le code, pas la doc.
-- **Cohérence FR/EN** : un fichier `xxx.md` en FR + un fichier
-  `xxx.en.md` en EN miroir.  Pas de fragments mêlés.
+  Vérifié par `tests/architecture/test_doc_paths.py` (ratchet
+  strictement décroissant).
+- **Les tableaux générés** (engines, CLI, endpoints) sont régénérés
+  par `scripts/gen_readme_tables.py` — modifier le code, pas la doc.
+  Les compteurs en prose (nombre de tests, etc.) utilisent la
+  formulation approximative `N+ tests` pour absorber la dérive
+  OS-dépendante ; le chiffre exact vit dans le badge CI.
+- **Cohérence FR/EN** : la langue canonique est le français.  Une
+  surface EN réduite est listée dans
+  `tests/docs/test_translation_parity.py::TRANSLATION_PAIRS` —
+  toute paire FR/EN doit y figurer.

docs/tutorials/first-benchmark.md

@@ -0,0 +1,134 @@
+# Premier benchmark Picarones
+
+Ce tutoriel guide un nouvel utilisateur — chercheur, archiviste,
+conservateur — à travers son **premier benchmark OCR** complet, de
+l'installation jusqu'à la lecture du rapport produit. Comptez 15
+minutes pour la première fois, 2 minutes une fois familier.
+
+> **Pré-requis** : Python 3.11+ et `pip`. Sur Linux, le binaire
+> `tesseract` est nécessaire pour le moteur OCR par défaut
+> (`apt-get install tesseract-ocr tesseract-ocr-fra` sur Debian/Ubuntu).
+
+---
+
+## 1. Installation
+
+```bash
+pip install -e ".[dev,web]"
+```
+
+L'extra `dev` apporte la suite de tests, `web` apporte l'interface
+FastAPI (utile dès la deuxième session). Pour une installation
+minimale en production, voir [`how-to/install.md`](../how-to/install.md).
+
+Vérifiez :
+
+```bash
+picarones info
+picarones engines
+```
+
+Si `picarones engines` liste au moins `tesseract`, vous êtes prêt.
+
+---
+
+## 2. Générer un rapport de démonstration
+
+Le mode `demo` produit un rapport HTML synthétique sans aucun moteur
+installé. C'est le moyen le plus rapide de voir ce que Picarones
+produit.
+
+```bash
+picarones demo --output rapport_demo.html
+```
+
+Ouvrez `rapport_demo.html` dans un navigateur. Vous obtenez un
+rapport complet avec :
+
+- agrégat CER/WER global ;
+- diff caractère à caractère sur les documents ;
+- diagramme CD (Critical Difference) si plus de 2 moteurs ;
+- moteur narratif qui résume les faits saillants en prose.
+
+Voir [`reading-a-report.md`](reading-a-report.md) pour la lecture
+détaillée.
+
+---
+
+## 3. Benchmark sur un vrai corpus
+
+Préparez un dossier `mon_corpus/` qui contient :
+
+```
+mon_corpus/
+├── doc1.jpg
+├── doc1.gt.txt          # transcription de référence
+├── doc2.jpg
+└── doc2.gt.txt
+```
+
+Le format des transcriptions de référence est documenté dans
+[`reference/normalization-profiles.md`](../reference/normalization-profiles.md).
+
+Lancez le benchmark :
+
+```bash
+picarones run \
+  --corpus mon_corpus/ \
+  --engines tesseract \
+  --output rapport.html \
+  --json rapport.json
+```
+
+`rapport.html` contient le rendu visuel ; `rapport.json` contient
+l'agrégat machine-lisible (utile pour CI ou comparaisons
+longitudinales — voir
+[`reference/reproducibility-snapshots.md`](../reference/reproducibility-snapshots.md)).
+
+---
+
+## 4. Comparer plusieurs moteurs
+
+```bash
+picarones run \
+  --corpus mon_corpus/ \
+  --engines tesseract,pero_ocr,mistral_ocr \
+  --output comparaison.html
+```
+
+Le rapport affiche désormais :
+
+- une ligne par moteur avec CER moyen + IC95 ;
+- le diagramme CD (qui domine statistiquement qui) ;
+- les diffs côte à côte ;
+- les coûts (si moteurs cloud).
+
+Le moteur narratif énonce les écarts significatifs, ne désigne
+jamais un « gagnant ».
+
+---
+
+## 5. Interface web (optionnelle)
+
+```bash
+picarones serve --port 7860
+```
+
+Ouvre `http://localhost:7860`. L'interface permet d'upload un ZIP
+de corpus et de lancer un benchmark interactif. Pour le déploiement
+institutionnel, voir
+[`operations/deployment-institutional.md`](../operations/deployment-institutional.md).
+
+---
+
+## Étapes suivantes
+
+- Comprendre les métriques :
+  [`reference/views.md`](../reference/views.md),
+  [`reference/normalization-profiles.md`](../reference/normalization-profiles.md)
+- Lire un rapport en détail :
+  [`reading-a-report.md`](reading-a-report.md)
+- Écrire un module pour la pipeline :
+  [`writing-a-pipeline-module.md`](writing-a-pipeline-module.md)
+- Étudier des cas d'usage :
+  [`case-studies/`](../case-studies/)

docs/tutorials/writing-a-pipeline-module.md

@@ -0,0 +1,150 @@
+# Écrire un module pour le banc d'essai
+
+Ce tutoriel montre **par l'exemple** comment écrire un module
+Picarones qui peut être chargé dans une pipeline composée, audité,
+et inclus dans un rapport. Pour la **politique normative complète**
+(contrat d'interface, métadonnées obligatoires, règles d'audit),
+voir [`developer/module-policy.md`](../developer/module-policy.md).
+
+---
+
+## Cas d'usage
+
+Vous avez écrit un script qui post-corrige du texte OCR avec une
+heuristique métier (par exemple : règles de normalisation propres
+à un fonds d'archives donné). Vous voulez le brancher dans
+Picarones pour mesurer son apport vs un baseline.
+
+C'est exactement le cas que cible l'axe B (banc d'essai de
+pipelines composées).
+
+---
+
+## Module minimal
+
+Un module Picarones est une **classe Python** qui hérite de
+`BaseModule` et implémente `run(...)`.
+
+```python
+# my_corrector.py
+from picarones.domain.module_protocol import BaseModule
+from picarones.domain.artifacts import ArtifactType, Artifact
+
+
+class MyCorrector(BaseModule):
+    """Post-corrige le texte OCR avec une règle métier."""
+
+    input_types = (ArtifactType.TEXT,)
+    output_types = (ArtifactType.TEXT,)
+
+    def run(self, artifact: Artifact) -> Artifact:
+        text = artifact.payload
+        # Votre logique métier ici.
+        corrected = text.replace(" l'", " l'").replace("  ", " ")
+        return Artifact(
+            type=ArtifactType.TEXT,
+            payload=corrected,
+        )
+```
+
+Quatre points à retenir :
+
+1. `input_types` et `output_types` doivent être déclarés au niveau
+   classe (le planner les lit avant exécution).
+2. `run` prend un `Artifact` et en retourne un. Pas d'effet de
+   bord, pas de mutation.
+3. Le type de sortie peut différer du type d'entrée (par exemple
+   `IMAGE → TEXT` pour un OCR).
+4. La classe ne doit rien savoir de Picarones au-delà de
+   `BaseModule` — c'est du Python ordinaire.
+
+---
+
+## Manifeste
+
+Pour être chargé, le module doit déclarer un manifeste avec
+**5 champs obligatoires** :
+
+```python
+from picarones.domain.module_protocol import ModuleManifest
+
+MANIFEST = ModuleManifest(
+    name="my-corrector",
+    version="0.1.0",
+    author="Vous <vous@institution.fr>",
+    license="MIT",
+    description="Post-correction par règles métier.",
+)
+```
+
+Le manifeste sert à tracer **qui** est responsable du module dans
+le rapport et à versionner les comparaisons longitudinales.
+
+---
+
+## Audit
+
+Avant exécution, le module passe un audit statique :
+
+```python
+from picarones.evaluation.metrics.module_policy import audit_module
+
+issues = audit_module(MyCorrector, MANIFEST)
+assert not issues, f"Module non conforme : {issues}"
+```
+
+Si l'audit échoue, le module n'est **pas chargé** dans la pipeline
+— pas d'exception silencieuse en production. Les règles d'audit
+sont énumérées dans
+[`developer/module-policy.md`](../developer/module-policy.md).
+
+---
+
+## Brancher dans une pipeline
+
+Une pipeline est décrite par un `PipelineSpec`. Le module est
+référencé par son chemin Python :
+
+```python
+from picarones.domain.pipeline_spec import PipelineSpec, PipelineStep
+
+spec = PipelineSpec(
+    name="ocr-puis-correction",
+    steps=[
+        PipelineStep(
+            name="ocr",
+            module="picarones.adapters.ocr.tesseract:TesseractAdapter",
+        ),
+        PipelineStep(
+            name="post-correction",
+            module="my_corrector:MyCorrector",
+        ),
+    ],
+)
+```
+
+Lancez le benchmark avec ce pipeline :
+
+```bash
+picarones run \
+  --corpus mon_corpus/ \
+  --pipeline ocr-puis-correction.yaml \
+  --output rapport.html
+```
+
+Le rapport présente alors **la pipeline complète** comme un
+« moteur » à part entière, comparable aux autres dans le tableau
+récapitulatif et le diagramme CD.
+
+---
+
+## Étapes suivantes
+
+- Politique normative et règles d'audit :
+  [`developer/module-policy.md`](../developer/module-policy.md)
+- Étendre le moteur narratif pour commenter votre module :
+  [`developer/extending-i18n.md`](../developer/extending-i18n.md)
+- Reproductibilité de la comparaison :
+  [`reference/reproducibility-snapshots.md`](../reference/reproducibility-snapshots.md)
+- Architecture en cercles (où se branche un module) :
+  [`explanation/architecture.md`](../explanation/architecture.md)

tests/docs/test_index_links_resolve.py

@@ -0,0 +1,100 @@
+"""Garde-fou : tout lien interne dans ``docs/index.md`` doit pointer
+vers un fichier réel.
+
+Pourquoi ce test existe
+-----------------------
+
+``docs/index.md`` est l'**index canonique** de la documentation : il
+est référencé depuis le README, depuis mkdocs.yml, et c'est la
+première porte d'entrée pour un nouveau contributeur.
+
+Avant Phase 1, ce fichier contenait 4 liens cassés (``first-benchmark``,
+``writing-a-pipeline-module``, ``developer/narrative-engine``,
+``user/...``) qui ont survécu pendant le rewrite parce qu'aucun test
+ne validait ses propres liens.  Ce garde-fou élimine la classe
+d'erreur : si l'index ment, la CI échoue.
+
+Périmètre
+---------
+
+On parse les liens markdown ``[texte](cible)`` et on vérifie que la
+``cible`` :
+
+- soit pointe vers un fichier existant (résolution relative à
+  ``docs/`` ou à la racine pour les ``../X``) ;
+- soit est une URL externe (``http://...``, ``mailto:...``) — non
+  vérifiée ici, c'est le rôle de tests externes ;
+- soit est une ancre intra-document (``#section``) — non vérifiée.
+
+Les liens vers des dossiers (``case-studies/``, ``audits/``) sont
+vérifiés comme l'existence du dossier.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+INDEX = REPO_ROOT / "docs" / "index.md"
+
+#: Pattern markdown standard : ``[texte](cible)``.  On capture la
+#: cible (groupe 2) qu'on évaluera comme chemin.
+_LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
+
+
+def _resolve_link(target: str) -> Path | None:
+    """Résout une cible de lien relativement à ``docs/index.md``.
+
+    Retourne ``None`` si :
+    - URL externe (``http``, ``mailto``, ``#``) ;
+    - cible vide ;
+    - chemin qui ne se résout pas.
+    """
+    target = target.strip()
+
+    # URL externe — pas notre problème ici.
+    if target.startswith(("http://", "https://", "mailto:", "#")):
+        return None
+
+    # Retirer l'ancre éventuelle (``foo.md#section``)
+    target = target.split("#", 1)[0]
+    if not target:
+        return None
+
+    # Les liens dans index.md sont relatifs à ``docs/``.
+    # Les liens vers la racine (``../GOVERNANCE.md``) doivent
+    # remonter au repo root.
+    base = INDEX.parent
+    resolved = (base / target).resolve()
+    return resolved
+
+
+def test_index_md_exists() -> None:
+    assert INDEX.exists(), (
+        f"{INDEX} absent — c'est l'index canonique de la doc, il "
+        "ne peut pas manquer."
+    )
+
+
+def test_all_internal_links_in_index_resolve() -> None:
+    """Tout lien interne dans ``docs/index.md`` doit pointer vers
+    un fichier ou dossier existant."""
+    text = INDEX.read_text(encoding="utf-8")
+    offenders: list[str] = []
+    for match in _LINK_RE.finditer(text):
+        target = match.group(2)
+        resolved = _resolve_link(target)
+        if resolved is None:
+            continue  # URL externe / ancre — pas notre périmètre
+        if not resolved.exists():
+            offenders.append(
+                f"  « {match.group(1)} » → {target!r} "
+                f"(résolu vers {resolved.relative_to(REPO_ROOT) if resolved.is_relative_to(REPO_ROOT) else resolved})"
+            )
+
+    assert not offenders, (
+        f"{len(offenders)} lien(s) cassé(s) dans docs/index.md :\n"
+        + "\n".join(offenders)
+        + "\n\n→ Soit créer le fichier cible, soit corriger le lien."
+    )