Contribuer à la documentation

La doc bfev/docs/ suit le cadre Diátaxis. Trois règles.

1. Un document = un mode

Choisis l'intention de lecture avant d'écrire, et ne la mélange pas :

Mode	Dossier	Question du lecteur	Ce qu'on n'y met PAS
Tutorial	tutorials/	« apprends-moi en faisant »	options exhaustives, justifications
How-to	how-to/	« comment je fais X ? »	théorie, découverte guidée
Reference	reference/	« quelle est la valeur/signature exacte ? »	le pourquoi, le ton narratif
Explanation	explanation/	« pourquoi c'est conçu ainsi ? »	étapes opératoires, listes d'API

Un document « fourre-tout » (ex. l'ancien skill-upgrades.md, qui mêlait table d'invariants et doctrine) doit être scindé : la référence d'un côté, le pourquoi de l'autre, reliés par un lien.

2. Source unique

Un fait vit une seule fois. On lie plutôt qu'on duplique (../reference/contracts.md#orchestrator). Si deux pages ont besoin du même contenu, c'est qu'il manque une page de référence à laquelle les deux pointent.

3. Langue & forme

• Français primaire pour la doc dev (la règle bilingue FR/EN ne concerne que les livrables client). Accents et diacritiques obligatoires.
• Les identifiants de code restent dans leur forme originale (bfev.fe_escalation, aggregates.json).
• Chemins relatifs pour les liens internes ; figures sous figures/.
• Les SKILL.md des skills restent le frontmatter opérationnel ; la doc longue migre vers how-to/ + reference/.

Où ranger un nouveau document

1. Quelle question le lecteur se pose-t-il ? → choisis le mode (table ci-dessus).
2. Crée le fichier dans le dossier correspondant.
3. Ajoute-le à index.md et à llms.txt.
4. Si tu modifies l'arborescence, mets à jour _inventory.md.