@ferrflow/doc 7.17.0

package/docs-fr-v5/quickstart.md

@@ -0,0 +1,63 @@
+---
+title: Démarrage rapide
+description: De zéro à votre première release automatisée en moins de 5 minutes.
+---
+
+<ol>
+<li><p><strong>Générer la configuration</strong></p>
+<p>Exécutez <code>ferrflow init</code> à la racine de votre repository. Il détecte vos fichiers de version et génère un fichier <code>.ferrflow</code> :</p>
+<pre><code class="language-bash">ferrflow init
+</code></pre>
+<p>Pour un projet Rust, cela produit :</p>
+<pre><code class="language-json">{
+  &quot;$schema&quot;: &quot;https://ferrflow.com/schema/ferrflow.json&quot;,
+  &quot;workspace&quot;: {
+    &quot;tagTemplate&quot;: &quot;v{version}&quot;
+  },
+  &quot;package&quot;: [
+    {
+      &quot;name&quot;: &quot;my-app&quot;,
+      &quot;path&quot;: &quot;.&quot;,
+      &quot;changelog&quot;: &quot;CHANGELOG.md&quot;,
+      &quot;versionedFiles&quot;: [
+        { &quot;path&quot;: &quot;Cargo.toml&quot;, &quot;format&quot;: &quot;toml&quot; }
+      ]
+    }
+  ]
+}
+</code></pre>
+</li>
+<li><p><strong>Prévisualiser le résultat</strong></p>
+<p>Avant de toucher à quoi que ce soit, lancez un dry-run pour voir ce que FerrFlow ferait :</p>
+<pre><code class="language-bash">ferrflow check
+</code></pre>
+<p>Sortie :</p>
+<pre><code>Scanning . ...
+→ feat: add user authentication
+→ fix: correct pagination offset
+
+Bump my-app 0.1.0 → 0.2.0
+Tag v0.2.0
+</code></pre>
+</li>
+<li><p><strong>Lancer la release</strong></p>
+<pre><code class="language-bash">ferrflow release
+</code></pre>
+<p>FerrFlow va :</p>
+<ul>
+<li>Mettre à jour <code>Cargo.toml</code> à <code>0.2.0</code></li>
+<li>Compléter <code>CHANGELOG.md</code></li>
+<li>Committer les changements</li>
+<li>Créer et pousser <code>v0.2.0</code></li>
+<li>Créer une release GitHub (si <code>GITHUB_TOKEN</code> est défini)</li>
+</ul>
+</li>
+</ol>
+
+## Étapes suivantes
+
+- Configurez [GitHub Actions](/fr/docs/ci/github-actions) pour lancer les releases automatiquement sur push vers `main`
+- Configurez un [monorepo](/fr/docs/configuration/monorepo) si vous avez plusieurs packages
+- Ajoutez des [hooks pre/post-release](/fr/docs/configuration/config-file#hooks) pour des scripts personnalisés pendant le cycle de release
+- Utilisez `ferrflow version` et `ferrflow tag` dans vos scripts CI — voir la [référence CLI](/fr/docs/reference/cli)
+- Consultez la [référence de configuration](/fr/docs/configuration/config-file) complète

package/docs-fr-v5/reference/api.md

@@ -0,0 +1,106 @@
+---
+title: API FerrFlow
+description: Endpoints HTTP hébergés pour FerrFlow — valider une config, prévisualiser les montées de version, résoudre la dernière release et récupérer le schéma de config.
+---
+
+L'API FerrFlow expose un petit ensemble d'endpoints HTTP hébergés sous `https://api.ferrflow.com/v1/ferrflow/*`. Ils s'appuient sur le même cœur FerrFlow que le CLI : `validate` et `preview` renvoient donc des résultats identiques à `ferrflow validate` et `ferrflow check` — aucune seconde implémentation qui pourrait diverger.
+
+Chaque endpoint est public (sans authentification) et sûr à appeler depuis la CI, un éditeur ou un navigateur. Le contrat lisible par machine est servi sur [`/v1/ferrflow/openapi.json`](https://api.ferrflow.com/v1/ferrflow/openapi.json) (OpenAPI 3.1).
+
+`https://api.ferrlabs.com/v1/ferrflow/*` atteint les mêmes endpoints et continuera de fonctionner indéfiniment — c'est là que l'API a été publiée en premier, et les versions du CLI déjà diffusées l'appellent toujours. Préférez `api.ferrflow.com` pour tout nouvel usage.
+
+## `GET /v1/ferrflow/health`
+
+Sonde de disponibilité et de version. Alimente les tableaux de bord d'état.
+
+```json
+{ "status": "ok", "service": "ferrflow-api", "version": "10.17.0", "time": "2026-07-21T15:00:00Z" }
+```
+
+## `GET /v1/ferrflow/schema`
+
+Renvoie le schéma JSON de la config (`Content-Type: application/schema+json`), servi depuis le schéma embarqué dans la release FerrFlow — les octets exacts que le CLI utilise pour valider. Envoie un `ETag` fort et un `Cache-Control`, alors pointez le `$schema` de votre éditeur ici :
+
+```json
+{ "$schema": "https://api.ferrflow.com/v1/ferrflow/schema" }
+```
+
+`GET /v1/ferrflow/schema/v{major}` renvoie le schéma figé à un majeur du CLI (par ex. `/schema/v5`). Seul le majeur courant est servi aujourd'hui ; les majeurs plus anciens renvoient `404` jusqu'à l'arrivée des instantanés par majeur.
+
+## `GET /v1/ferrflow/latest`
+
+Résout la dernière release FerrFlow depuis GitHub, mise en cache côté serveur. Passez `platform` pour obtenir un seul artefact :
+
+```bash
+curl "https://api.ferrflow.com/v1/ferrflow/latest?platform=linux-x64"
+```
+
+```json
+{
+  "version": "5.48.0",
+  "tag": "v5.48.0",
+  "platform": "linux-x64",
+  "download_url": "https://github.com/FerrLabs/FerrFlow/releases/download/v5.48.0/ferrflow-linux-x64.tar.gz",
+  "bundle_url": "https://github.com/FerrLabs/FerrFlow/releases/download/v5.48.0/ferrflow-linux-x64.tar.gz.bundle",
+  "published_at": "2026-07-27T19:20:00Z"
+}
+```
+
+Les releases sont signées avec [Sigstore](/fr/verifying-releases/) — vérifiez le `.bundle` plutôt qu'une somme de contrôle (les releases jusqu'à v5.47.4 embarquent une paire `.sig` + `.crt`). Sans `platform`, la réponse liste les `assets` de chaque plateforme. Plateformes valides : `linux-x64`, `linux-arm64`, `linux-arm`, `darwin-x64`, `darwin-arm64`, `win32-x64`, `win32-arm64`.
+
+## `POST /v1/ferrflow/validate`
+
+Valide une config sans dépôt — vous envoyez le texte de la config et, en option, le contenu des fichiers versionnés qu'elle référence pour que les vérifications d'existence et de cohérence des versions s'exécutent. Le résultat est identique à `ferrflow validate --json`.
+
+```bash
+curl -X POST https://api.ferrflow.com/v1/ferrflow/validate \
+  -H 'content-type: application/json' \
+  -d '{
+    "config": "{\"package\":[{\"name\":\"app\",\"path\":\".\",\"versionedFiles\":[{\"path\":\"package.json\",\"format\":\"json\"}]}]}",
+    "files": { "package.json": "{\"version\":\"1.0.0\"}" }
+  }'
+```
+
+```json
+{
+  "valid": true,
+  "config_file": null,
+  "package_count": 1,
+  "errors": [],
+  "warnings": [],
+  "suggestions": []
+}
+```
+
+Une config invalide reste une validation réussie : la réponse est `200` avec `"valid": false` et les entrées fautives. Seul un corps de requête malformé renvoie `400`. Le champ optionnel `format` (`json` | `json5` | `toml`) court-circuite la détection de format.
+
+## `POST /v1/ferrflow/preview`
+
+Calcule les montées de version et le changelog pour une liste explicite de commits — la même logique que `ferrflow check`, sous forme de service. Aucun accès au dépôt ; vous passez les commits.
+
+```bash
+curl -X POST https://api.ferrflow.com/v1/ferrflow/preview \
+  -H 'content-type: application/json' \
+  -d '{
+    "config": "{\"package\":[{\"name\":\"api\",\"path\":\".\"}]}",
+    "commits": [{ "message": "feat(api): add endpoint", "hash": "a1b2" }],
+    "current_versions": { "api": "1.2.3" }
+  }'
+```
+
+```json
+{
+  "packages": [
+    {
+      "name": "api",
+      "current": "1.2.3",
+      "next": "1.3.0",
+      "bump": "minor",
+      "commits": [{ "hash": "a1b2", "type": "feat", "scope": "api", "breaking": false }],
+      "changelog": "### Features\n- ..."
+    }
+  ]
+}
+```
+
+Dans une config monorepo, chaque commit est affecté à un package quand ses `files` se trouvent sous le `path` de ce package. Les packages sans commit publiable sont omis.

package/docs-fr-v5/reference/cli.md

@@ -0,0 +1,356 @@
+---
+title: Commandes CLI
+description: Référence complète de toutes les commandes et options du CLI FerrFlow.
+---
+
+## `ferrflow release`
+
+Lance le pipeline complet de release : bump des versions, mise à jour des changelogs, commit, tag, push et création de la release.
+
+```bash
+ferrflow release [OPTIONS]
+```
+
+| Option                      | Description                                                                                                                                                                                 |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--force`                   | Autoriser les floating tags à reculer vers une version inférieure                                                                                                                           |
+| `--force-version <VERSION>` | Forcer une version spécifique, sans analyser les commits. Format : `VERSION` (repo simple) ou `NAME@VERSION` (monorepo)                                                                     |
+| `--channel <NAME>`          | Canal de pré-release à utiliser (ex. `beta`, `rc`, `dev`)                                                                                                                                   |
+| `--draft`                   | Créer les releases en brouillon (GitHub uniquement). Un `ferrflow release` ultérieur sans `--draft` détecte et publie automatiquement les brouillons existants                              |
+| `--force-unlock`            | Forcer la levée d'un verrou `.git/ferrflow.lock` existant. À n'utiliser que si aucun autre `ferrflow release` n'est en cours — par exemple après un crash ayant laissé le fichier de verrou |
+
+**Ce que ça fait :**
+
+1. Scanne les commits depuis le dernier tag pour chaque package
+2. Détermine l'incrément de version à partir des Conventional Commits
+3. Met à jour tous les `versionedFiles` avec la nouvelle version
+4. Ajoute la nouvelle section au `CHANGELOG.md`
+5. Crée un commit git, ouvre une PR, ou passe (selon `releaseCommitMode`)
+6. Crée et pousse le tag git
+7. Crée une release GitHub/GitLab avec le changelog comme notes
+
+---
+
+## `ferrflow check`
+
+Prévisualiser ce que `ferrflow release` ferait sans effectuer de changements.
+
+```bash
+ferrflow check [OPTIONS]
+```
+
+| Option             | Description                                                     |
+| ------------------ | --------------------------------------------------------------- |
+| `--json`           | Sortie au format JSON                                           |
+| `--channel <NAME>` | Canal de pré-release à utiliser (ex. `beta`, `rc`, `dev`)       |
+| `--comment`        | Poster un commentaire de prévisualisation sur la PR/MR courante |
+
+---
+
+## `ferrflow publish`
+
+Exécuter les [publishers](/fr/docs/configuration/config-file/#publishers) configurés pour la version actuellement publiée de chaque package — sans bumper, committer ni tagger. `ferrflow release` exécute déjà vos publishers à la fin d'une release ; `ferrflow publish` sert lorsque vous préférez les exécuter dans un **job CI séparé** disposant de la toolchain de build et de l'authentification registre dont les publishers ont besoin (docker buildx, helm, un `dist/` compilé, …) — ce que votre job de release n'a pas forcément.
+
+```bash
+ferrflow publish [PACKAGES...]
+```
+
+| Argument / option | Description                                                                                                                                                                                                   |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[PACKAGES...]`   | Publier ces packages par leur nom (séparés par des espaces). Omettre pour auto-détecter depuis le tag déclencheur (`GITHUB_REF` / `CI_COMMIT_TAG`), avec repli sur chaque package qui déclare des publishers. |
+| `--all`, `-a`     | Publier tous les packages, en ignorant tout scope de tag déclencheur.                                                                                                                                         |
+
+Il lit la version actuelle de chaque package depuis ses `versionedFiles` (ou le dernier tag correspondant pour les packages tag-only), donc à exécuter **après** que `ferrflow release` a coupé la version. Les publishers sont idempotents : tout ce qui est déjà sur le registre est ignoré, donc une ré-exécution est sûre. Utilisez l'option globale `--dry-run` pour prévisualiser sans publier.
+
+**Résolution du scope.** Sans argument, si le run a été déclenché par un tag de package (ex. `api@v2.2.1`), seul ce package est publié — un seul workflow déclenché par tag publie ainsi chaque package sur son propre tag, sans câblage par package. Sans tag correspondant (par exemple la ref de branche du job de release), tous les packages sont publiés, comme avant. Passez des noms de packages pour cibler un sous-ensemble, ou `--all` pour forcer tous les packages même sous un tag.
+
+L'Action GitHub l'expose via `mode: publish` — elle installe le binaire et exécute `ferrflow publish` pour vous, en se scopant automatiquement au tag déclencheur (ou passez l'input `package` pour forcer). Un job déclenché par le tag n'a plus qu'à mettre en place la toolchain dont ses publishers ont besoin :
+
+```yaml title=".github/workflows/publish.yml"
+on:
+  push:
+    # `v*` pour les repos mono-package ; `*@v*` pour les tags par-package en monorepo
+    tags: ['v*', '*@v*']
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: docker/setup-buildx-action@v4
+      - uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: FerrLabs/FerrFlow@v5
+        with:
+          mode: publish
+```
+
+---
+
+## `ferrflow changelog`
+
+Générer ou mettre à jour `CHANGELOG.md` uniquement, sans bumper les versions ni créer de tags.
+
+```bash
+ferrflow changelog
+```
+
+Ne prend aucune option spécifique. Utilisez l'option globale `--dry-run` pour afficher l'entrée sans l'écrire.
+
+---
+
+## `ferrflow init`
+
+Générer un fichier de configuration pour le repository courant. Détecte les fichiers de version existants (`Cargo.toml`, `package.json`, etc.) et génère la configuration appropriée.
+
+```bash
+ferrflow init [OPTIONS]
+```
+
+| Option              | Description                                                    |
+| ------------------- | -------------------------------------------------------------- |
+| `--format <FORMAT>` | Format du fichier de configuration : `json`, `json5` ou `toml` |
+
+---
+
+## `ferrflow migrate`
+
+Générer une configuration FerrFlow à partir de celle d'un autre outil de release. Lancez cette commande dans votre repo et elle écrit le `ferrflow.json` équivalent.
+
+```bash
+ferrflow migrate [OPTIONS]
+```
+
+| Option           | Description                                                                                            |
+| ---------------- | ------------------------------------------------------------------------------------------------------ |
+| `--from <OUTIL>` | Source : `semantic-release`, `changesets`, `release-please`, `standard-version`. Auto-détecté si omis. |
+
+### Sources
+
+| Outil              | Lit                             | Ce qui est converti (extraits)                                                                                                                                                           |
+| ------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `semantic-release` | `.releaserc`, `.releaserc.json` | `tagFormat` → `tagTemplate` ; `branches` → canaux ; `@semantic-release/exec` → `hooks` ; plugins `changelog` / `github` / `gitlab` (voir la table ci-dessous)                            |
+| `release-please`   | `release-please-config.json`    | la map `packages` → packages FerrFlow (le `release-type` de chaque package → le bon fichier de version) ; `include-component-in-tag` → `tagTemplate` ; flux PR → `releaseCommitMode: pr` |
+| `standard-version` | `.versionrc`, `.versionrc.json` | `tagPrefix` → `tagTemplate` ; `bumpFiles` / `packageFiles` → `versionedFiles`                                                                                                            |
+| `changesets`       | `.changeset/config.json`        | `baseBranch` → `branch` ; `linked` / `fixed` → groupes de versions (voir la note)                                                                                                        |
+
+Mapping des plugins semantic-release :
+
+| semantic-release                      | FerrFlow                                                                                                                                                  |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tagFormat: "v${version}"`            | `tagTemplate: "v{{version}}"`                                                                                                                             |
+| `branches`                            | `branches` — `main`/`master` deviennent la ligne stable, une branche `prerelease: true` (ou nommée) devient un canal                                      |
+| `@semantic-release/changelog`         | le chemin `changelog` du package                                                                                                                          |
+| `@semantic-release/exec`              | `hooks` (`prepareCmd` → `preBump`, `publishCmd` → `postPublish`, `successCmd` → `onSuccess`, `failCmd` → `onError`, `verifyConditionsCmd` → `preRelease`) |
+| `@semantic-release/github` / `gitlab` | `forge`                                                                                                                                                   |
+
+Tout ce qui n'a pas d'équivalent FerrFlow est **signalé, jamais deviné**. Chaque exécution affiche ce qui a été converti, ignoré, et ce qui demande une revue manuelle — par exemple `@semantic-release/npm` (configurez `publishers` à la main), des règles `commit-analyzer` personnalisées (les règles de bump de FerrFlow sont fixes), et `repositoryUrl` (FerrFlow déduit le remote depuis git). Elle n'écrase pas une configuration FerrFlow existante.
+
+<aside class="ferr-aside ferr-aside--note"><div class="ferr-aside__body"><p><strong>changesets.</strong> changesets versionne à partir de fichiers <code>.changeset/*.md</code> écrits à la main, alors que FerrFlow versionne depuis les commits conventionnels — après migration, adoptez les Conventional Commits, vos fichiers changeset existants ne sont pas lus. FerrFlow lit votre déclaration de workspace (<code>workspaces</code> dans <code>package.json</code>, ou <code>pnpm-workspace.yaml</code>) et génère une entrée <code>package</code> par package découvert : vos groupes <code>linked</code>/<code>fixed</code> référencent donc déjà de vrais packages et la config migrée valide telle quelle. Un dépôt sans déclaration de workspace obtient un seul package racine.</p>
+</div></aside>
+
+```bash
+ferrflow migrate                        # auto-détection
+ferrflow migrate --from release-please
+```
+
+Les configurations source JSON, YAML et JavaScript fonctionnent toutes — une configuration JavaScript (`.releaserc.js`, `release.config.js`, `.versionrc.js`) est évaluée avec `node` (Node.js doit donc être dans le PATH), et une configuration YAML (`.releaserc.yaml`, `.versionrc.yaml`) est parsée directement. Après migration, relisez la configuration générée, puis lancez `ferrflow validate` et `ferrflow check`.
+
+---
+
+## `ferrflow status`
+
+Afficher la version actuelle de chaque package et si une release serait déclenchée.
+
+```bash
+ferrflow status [OPTIONS]
+```
+
+| Option              | Description                                  |
+| ------------------- | -------------------------------------------- |
+| `--output <FORMAT>` | Format de sortie : `text` (défaut) ou `json` |
+
+Exemple de sortie :
+
+```
+api    1.2.3   minor bump pending (1 feat commit)
+site   0.4.1   no release (only chore commits)
+```
+
+---
+
+## `ferrflow diff`
+
+Comparer deux versions d'un package : les commits qui y sont entrés, l'incrément de chaque commit, les fichiers modifiés, et le changelog que FerrFlow générerait pour l'intervalle. Pratique pour auditer une release, comprendre pourquoi une version a bumpé ainsi, ou rédiger des notes de release a posteriori pour un intervalle.
+
+```bash
+ferrflow diff [PACKAGE] <FROM>..<TO> [--json]
+```
+
+| Argument / option | Description                                                                                                  |
+| ----------------- | ------------------------------------------------------------------------------------------------------------ |
+| `<FROM>..<TO>`    | L'intervalle de versions. Chaque borne est un tag ou une version — `v1.4.0`, ou un tag complet `api@v1.6.0`. |
+| `[PACKAGE]`       | Nom du package — requis en monorepo, optionnel (et déduit) dans un repo mono-package.                        |
+| `--json`          | Émettre la comparaison en objet JSON structuré au lieu de la vue humaine.                                    |
+
+Chaque borne est résolue en essayant d'abord la chaîne comme tag (un vrai tag, ou `v1.4.0` en mono-package), puis comme le tag du package pour cette version (`api@v1.4.0`).
+
+```bash
+ferrflow diff v1.4.0..v1.6.0            # repo mono-package
+ferrflow diff api v1.4.0..v1.6.0        # monorepo — nommez le package
+```
+
+La sortie liste chaque commit de l'intervalle avec son incrément (`major` / `minor` / `patch` / `none`), met en évidence les breaking changes, résume les fichiers modifiés, et rend la section de changelog pour l'intervalle. En monorepo, l'intervalle couvre pour l'instant tous les commits entre les deux tags (pas encore restreint aux chemins du package nommé).
+
+---
+
+## `ferrflow version`
+
+Afficher la version actuelle d'un ou de tous les packages. Utile dans les scripts CI.
+
+```bash
+ferrflow version [PACKAGE] [OPTIONS]
+```
+
+| Option   | Description           |
+| -------- | --------------------- |
+| `--json` | Sortie au format JSON |
+
+Retourne la version depuis le dernier tag git correspondant au modèle de tag du package.
+
+---
+
+## `ferrflow tag`
+
+Afficher le dernier tag pour un ou tous les packages.
+
+```bash
+ferrflow tag [PACKAGE] [OPTIONS]
+```
+
+| Option   | Description           |
+| -------- | --------------------- |
+| `--json` | Sortie au format JSON |
+
+---
+
+## `ferrflow validate`
+
+Valider la configuration et les fichiers versionnés qu'elle référence, sans rien bumper. Utilisez `--repo` pour valider un dépôt distant plutôt que l'arbre de travail.
+
+```bash
+ferrflow validate [OPTIONS]
+```
+
+| Option          | Description                                                                       |
+| --------------- | --------------------------------------------------------------------------------- |
+| `--json`        | Sortie au format JSON                                                             |
+| `--repo <REPO>` | Dépôt distant à valider (ex. `owner/repo` pour GitHub, ou `gitlab:group/project`) |
+| `--ref <REF>`   | Ref git pour la validation distante (branche, tag ou commit)                      |
+
+---
+
+## `ferrflow doctor`
+
+Lancer un diagnostic en lecture seule sur le dépôt, la configuration et la forge, puis afficher un rapport par catégories — la commande « est-ce que ma config est saine ? ». Utilisez-la sur un checkout tout neuf pour voir ce qui manque avant la première release, ou quand une exécution se comporte mal et que vous devriez sinon scruter les logs `--verbose`.
+
+```bash
+ferrflow doctor [OPTIONS]
+```
+
+| Option           | Description                                                                    |
+| ---------------- | ------------------------------------------------------------------------------ |
+| `--format <FMT>` | `human` (défaut) ou `json`                                                     |
+| `--online`       | Sonder aussi l'API de la forge (rate limit / auth GitHub) ; nécessite un token |
+
+Le rapport groupe les vérifications en cinq sections — **Repo** (dépôt git, historique de commits, arbre de travail propre, remote, tags), **Config** (quel fichier de config l'emporte, s'il parse, plus toute la suite de vérifications de `ferrflow validate`), **Versioning** (stratégie et version sur disque de chaque package), **Forge** (forge détectée et présence d'un token d'auth dans l'environnement) et **CI** (fichiers de workflow, et si un workflow épingle l'action `FerrLabs/FerrFlow`). Chaque vérification est verte, un avertissement, ou une erreur.
+
+Le code de sortie est scriptable : `0` quand tout est vert, `1` s'il n'y a que des avertissements, `2` si une vérification est en erreur. La sortie `--format json` a une forme stable — `{ status, exit_code, sections: [{ title, checks: [{ name, status, detail }] }] }` — pour que la CI puisse s'appuyer dessus.
+
+```bash
+ferrflow doctor                 # rapport lisible
+ferrflow doctor --format json   # lisible par machine, stable pour la CI
+ferrflow doctor --online        # vérifie aussi le rate limit de l'API GitHub
+```
+
+---
+
+## `ferrflow completions`
+
+Générer un script de complétion shell et l'afficher sur la sortie standard.
+
+```bash
+ferrflow completions <SHELL>
+```
+
+`<SHELL>` est l'un de `bash`, `elvish`, `fish`, `powershell` ou `zsh`.
+
+---
+
+## `ferrflow schema`
+
+Afficher le schéma JSON du fichier de configuration ferrflow. Le schéma est embarqué dans le binaire : la commande fonctionne donc hors ligne, sans appel réseau à `ferrflow.com/schema/ferrflow.json`.
+
+```bash
+ferrflow schema [OPTIONS]
+```
+
+| Option            | Description                                                      |
+| ----------------- | ---------------------------------------------------------------- |
+| `--pretty`        | Formater la sortie au lieu d'un JSON compact sur une seule ligne |
+| `--output <FILE>` | Écrire dans un fichier plutôt que sur la sortie standard         |
+
+Utilisez-la pour pointer un éditeur vers une copie locale, ou pour valider `.ferrflow.json` dans un hook pre-commit sans accès internet :
+
+```bash
+ferrflow schema --pretty --output ferrflow.schema.json
+```
+
+Puis renseignez `"$schema": "./ferrflow.schema.json"` dans votre configuration. La commande parse le schéma embarqué avant de l'afficher : elle sort donc avec un code non nul si l'artefact de build est corrompu.
+
+---
+
+## Options globales
+
+Ces options fonctionnent avec toutes les commandes :
+
+| Option                  | Description                                                                                                                                                                                                               |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--dry-run`             | Montrer ce qui se passerait sans effectuer de changements                                                                                                                                                                 |
+| `--verbose`, `-v`       | Sortie détaillée, incluant les hashes de commits et les diffs de fichiers                                                                                                                                                 |
+| `--log-format <FORMAT>` | Format de la sortie de diagnostic sur stderr : `human` (défaut, coloré) ou `json` (un événement structuré par ligne). Les **données** des commandes (`--json`, valeurs de `version` / `tag`) restent toujours sur stdout. |
+| `--config <PATH>`       | Chemin vers un fichier de configuration personnalisé (défaut : auto-détecté). Accepte aussi la variable d'environnement `FERRFLOW_CONFIG`.                                                                                |
+| `--jobs <N>`            | Nombre max de threads pour le travail CPU-parallèle (planification par paquet). Défaut : tous les cœurs logiques ; `1` force le mono-thread. Accepte aussi la variable d'environnement `FERRFLOW_JOBS`.                   |
+| `--version`             | Afficher la version de FerrFlow et quitter                                                                                                                                                                                |
+| `--help`, `-h`          | Afficher l'aide                                                                                                                                                                                                           |
+
+## Logging & sortie
+
+FerrFlow sépare les **données** des **logs** sur les deux flux de sortie :
+
+- **stdout** porte les données — la sortie `--json` de `check` / `release` / `status` / `validate`, et la valeur affichée par `version` et `tag`. Capturez-la dans vos scripts : `V=$(ferrflow version)`.
+- **stderr** porte le rapport humain et chaque événement de diagnostic.
+
+Vous pouvez ainsi capturer le résultat machine et le journal d'exécution indépendamment :
+
+```bash
+ferrflow check --json > result.json 2> run.log
+```
+
+`--log-format json` rend chaque diagnostic sous forme d'un événement JSON structuré par ligne sur stderr, prêt pour Datadog / Loki / CloudWatch :
+
+```json
+{
+  "timestamp": "2026-01-01T00:00:00Z",
+  "level": "INFO",
+  "fields": { "message": "✓ Updated CHANGELOG.md" },
+  "target": "ferrflow::changelog"
+}
+```
+
+`--verbose` (ou un filtre `RUST_LOG` comme `RUST_LOG=ferrflow::git=trace`) contrôle les niveaux affichés.

package/docs-fr-v5/reference/conventional-commits.md

@@ -0,0 +1,88 @@
+---
+title: Conventional Commits
+description: Comment FerrFlow interprète les messages de commit pour déterminer les incréments de version.
+---
+
+FerrFlow suit la spécification [Conventional Commits](https://www.conventionalcommits.org/) pour déterminer de combien incrémenter la version.
+
+## Règles d'incrément
+
+| Type de commit                | Incrément de version | Exemple                             |
+| ----------------------------- | -------------------- | ----------------------------------- |
+| `feat:`                       | **minor**            | `feat: add wallet subscriptions`    |
+| `fix:`                        | patch                | `fix: correct pagination offset`    |
+| `perf:`                       | patch                | `perf: cache user queries`          |
+| `refactor:`                   | patch                | `refactor: extract auth middleware` |
+| `feat!:` ou `BREAKING CHANGE` | **major**            | `feat!: remove deprecated endpoint` |
+| `chore:`                      | aucun                | `chore: update dependencies`        |
+| `docs:`                       | aucun                | `docs: update README`               |
+| `ci:`                         | aucun                | `ci: add linting step`              |
+| `style:`                      | aucun                | `style: format code`                |
+| `test:`                       | aucun                | `test: add unit tests`              |
+
+## Breaking changes
+
+Un breaking change peut être indiqué de deux manières :
+
+**Suffixe point d'exclamation :**
+
+```
+feat!: remove the /v1/users endpoint
+fix!: change authentication header format
+```
+
+**Footer `BREAKING CHANGE` :**
+
+```
+feat: redesign the API
+
+BREAKING CHANGE: The /v1/users endpoint has been removed. Use /v2/users instead.
+```
+
+Les deux produisent un incrément **major**.
+
+### Variantes de footer acceptées
+
+FerrFlow reconnaît les orthographes courantes du footer, pas seulement la forme stricte de la spec :
+
+| Footer                                      | Détecté                     |
+| ------------------------------------------- | --------------------------- |
+| `BREAKING CHANGE: …`                        | oui (spec)                  |
+| `BREAKING-CHANGE: …`                        | oui (synonyme de la spec)   |
+| `breaking-change: …` / `breaking change: …` | oui (insensible à la casse) |
+| `Breaking Change: …`                        | oui (insensible à la casse) |
+
+Il traite aussi un `!` placé **à l'intérieur** du scope — `feat(api!):`, une faute de frappe courante pour `feat(api)!:` — comme un marqueur breaking. Le footer peut se trouver après n'importe quel nombre de paragraphes de corps.
+
+### Ce qui n'est _pas_ un breaking change
+
+La détection reste stricte, pour qu'une mention de passage ne déclenche jamais un incrément major accidentel :
+
+- Le footer doit débuter une ligne, utiliser une seule espace ou un tiret (`BREAKING CHANGE` / `BREAKING-CHANGE`), et être suivi d'un deux-points **et d'une espace**. `BREAKING CHANGE:sans-espace` et le pluriel `BREAKING CHANGES:` sont ignorés.
+- Une mention en prose au milieu d'une ligne — « ceci corrige un breaking change dans le parseur » — n'est pas un footer.
+- Un `!` qui n'est pas immédiatement avant la parenthèse fermante — `feat(a!b):` — n'est pas un marqueur.
+
+## Scope
+
+Les scopes sont optionnels et ignorés pour le calcul de l'incrément. Ils sont utiles pour la lisibilité :
+
+```
+feat(auth): add OAuth2 support       → incrément minor
+fix(db): correct index on user table  → incrément patch
+```
+
+## Pas de release
+
+Les commits de type `chore`, `docs`, `ci`, `style` ou `test` ne déclenchent pas de release. Si tous les commits depuis le dernier tag sont de ces types, FerrFlow se termine sans créer de nouvelle version.
+
+## Commits multiples
+
+Lorsque plusieurs commits sont présents depuis le dernier tag, FerrFlow prend l'incrément le **plus élevé** parmi tous :
+
+```
+fix: correct typo       → patch
+feat: add export button → minor   ← gagne
+chore: lint             → aucun
+```
+
+Résultat : incrément **minor**.