FND-002 : Documentation intentionnelle : normes, structure et stratégie d’i18n

À partir de v0.7.0 · Type : Documentation · Rév. 7

Référence canonique · Ratifiée par l’équipe · Rév. 7 Discussion RFC d’origine : #5576

Une note à l’équipe avant que vous lisiez ceci.

La documentation n’est pas ce que l’on écrit une fois le code terminé. C’est une surface de produit à part entière, l’interface entre le projet et chaque personne qui y contribuera, l’utilisera ou s’appuiera dessus. Une base de code sans documentation oblige chaque nouvelle personne à tout redécouvrir à partir de zéro. Une base de code avec une mauvaise documentation est souvent pire, car elle donne aux gens une fausse confiance. Cette RFC propose de traiter la documentation avec la même intentionnalité que celle que nous appliquons à l’architecture : la vision d’abord, puis la structure, puis le contenu.

Table des matières

1. La philosophie de la documentation
2. Évaluation honnête : où nous en sommes aujourd’hui
3. Un cadre de classification : les artefacts EA sur une page
4. Le problème de l’i18n
5. La séparation du dépôt / wiki
6. Standards ADR
7. AGENTS.md en tant que couche de développement IA
8. La structure cible
9. Le contrat de documentation de remplacement
10. Standards que nous devrions adopter
11. Feuille de route par phases

Historique des révisions

Politique de révision de Foundation

Les métadonnées de révision de Foundation conservent les révisions de brouillon intégrées à la base ratifiée et consignent l’évolution des décisions normatives après la ratification. Incrémentez la révision affichée et ajoutez une ligne chronologique lorsqu’une modification fusionnée altère l’architecture, le processus requis, les contrats de mise en production, le comportement des contributeurs ou la propriété d’une source faisant autorité. Un retour ultérieur à l’état précédent constitue une révision distincte, car les deux états ont successivement régi le projet. Les brouillons portant uniquement sur des problèmes et exclus de la ratification ne comptent pas.

N’augmentez pas la révision pour les déplacements, la mise en forme, la ponctuation, la normalisation des titres, la réparation des liens ou les mises à jour de chemins qui ne modifient pas le contrat. Lorsqu’un document fondateur délègue explicitement les détails opérationnels à une autre source maintenue, les modifications limitées à ces détails ne révisent pas le document fondateur.

Les deux valeurs de révision affichées et la ligne de l’historique local des révisions ayant la valeur la plus élevée doivent être mises à jour ensemble dans la même modification. Les lignes ajoutées avec un amendement conservent la date de révision attribuée à l’amendement. Lorsque l’historique est complété ultérieurement a posteriori, utilisez la date à laquelle la modification est entrée dans master.

1. La philosophie de la documentation

Les problèmes de documentation proviennent presque toujours du fait d’avoir sauté une question qui aurait dû être posée avant de rédiger la première phrase : quel type de document s’agit-il, et à qui s’adresse-t-il ?

Sans réponse à cette question, la documentation s’accumule en une pile de pages qui sont toutes des variantes légèrement différentes d’une même catégorie vague : « tout ce qui concerne le projet ». Les guides d’installation côtoient les décisions architecturales. Les tutoriels destinés aux utilisateurs se trouvent à côté des normes de codage internes. Trente traductions du README se disputent l’espace avec le seul document de politique de sécurité. Personne ne trouve rien, tout devient obsolète à des rythmes différents, et chaque PR qui touche à la documentation devient une négociation sur les pages qui doivent être mises à jour.

La solution n’est pas d’écrire davantage de documentation. Il faut plutôt décider, avant de commencer à rédiger, quel type d’artefact vous créez. Le type détermine le format, le public cible, l’emplacement, le cycle de vie et la personne responsable de sa mise à jour. Une fois le type défini, le reste s’organise naturellement.

Cette RFC adopte le framework EA Artifacts on a Page de Svyatoslav Kotusev (https://eaonapage.com) comme grille de classification pour toute la documentation de ZeroClaw. Ce framework est fondé sur des données probantes, délibérément non prescriptif, et correspond directement aux types de documents dont un projet d’infrastructure open source a réellement besoin.

Le principe fondamental, emprunté à la philosophie de développement plus large que cette équipe adopte :

Les documents, comme le code, doivent tracer une ligne ascendante à travers Vision → Architecture → Conception → Implémentation. Si vous ne pouvez pas nommer le type d’artefact et son public avant de rédiger, vous n’êtes pas prêt à écrire.

2. Évaluation honnête : Où nous en sommes aujourd’hui

2.1 L’empreinte i18n

Le problème le plus immédiatement mesurable dans la documentation actuelle est le système de localisation :

Le système i18n crée une taxe de contribution sur chaque PR de documentation. Le fichier docs-contract.md actuel contient cette exigence :

Si une modification touche à la documentation IA, aux références du contrat d’exécution ou au texte visible par les utilisateurs dans les documents partagés, effectuez la mise à jour i18n pour les locales prises en charge dans la même PR.

Cela signifie qu’un contributeur qui corrige une coquille dans un guide d’installation doit mettre à jour jusqu’à six versions linguistiques de ce document, sinon la PR échoue lors de la revue. Il s’agit d’un obstacle important à la contribution, en particulier pour les étudiants et les ingénieurs en début de carrière qui constituent la majorité de la base de contributeurs de ce projet.

2.2 Le problème de la structure

La hiérarchie actuelle de docs/ mélange trois types de documents fondamentalement différents au même niveau :

• Documents connexes au code qui doivent être versionnés avec la base de code (ADRs, spécifications de l’API, politique de sécurité, processus de contribution)
• Documents opérationnels destinés aux utilisateurs qui doivent être mis à jour indépendamment des versions du code (guides d’installation, dépannage, guides de déploiement)
• Documents communautaires qui doivent être maintenus par la communauté et ne nécessitent pas de processus de révision formelle (traductions, FAQ, guides communautaires)

Les trois fichiers résident dans docs/ sans distinction structurelle entre eux. Le résultat est une pile plate avec un SUMMARY.md maintenu manuellement, qu’il faut mettre à jour à chaque modification.

2.3 Le fossé ADR

Lorsque cette RFC a été rédigée, le projet comptait deux Architecture Decision Records dans l’ancien arbre de documentation : ADR-003 pour les plugins WASM et ADR-004 pour la propriété de l’état partagé des outils. ADR-004 était un modèle particulièrement solide : bien structuré, avec des références au code, précis. Mais le projet avait pris au moins cinq ou six décisions architecturales d’égale ou de plus grande importance qui n’avaient jamais été consignées :

• Le choix de Rust par rapport à TypeScript
• Le modèle d’extensibilité piloté par les traits
• La conception du système de plugins WASM
• Le contrat de stockage mémoire indépendant du backend et la valeur par défaut SQLite
• Le modèle de sécurité (codes d’appairage, niveaux d’autonomie, couches de sandbox)

Sans ces enregistrements, chaque nouveau contributeur doit redécouvrir la logique sous-jacente grâce à l’archéologie du code. Chaque assistant de codage par IA qui lit la base de code obtient le quoi mais pas le pourquoi. Il s’agit de l’une des formes les plus coûteuses de dette technique non documentée.

2.4 Ce qui est déjà bien

Le concept docs-contract.md, traitant la documentation comme une surface produit gouvernée, est le bon instinct. Il a juste besoin des bonnes règles. Le AGENTS.md à la racine est excellent et établit le bon précédent pour le développement assisté par l’IA. ADR-004 a prouvé que l’équipe pouvait rédiger des enregistrements architecturaux de haute qualité.

3. Un cadre de classification : les artefacts EA sur une page

Le cadre Artéfacts EA sur une Page définit cinq familles d’artéfacts d’architecture. Chaque document du dépôt ZeroClaw doit appartenir à l’une de ces familles, et cette famille détermine tout ce qui concerne son emplacement, son formatage et le moment où il devient obsolète.

Ce qui est notablement absent de ce tableau : les guides utilisateur, les instructions d’installation, les tutoriels spécifiques à chaque canal, la résolution des problèmes, la FAQ. Il s’agit de contenu opérationnel, et non d’artefacts EA. Ils ne sont pas versionnés avec le code. Ils appartiennent au Wiki GitHub.

Utilisation du framework

Avant de rédiger tout document, posez et répondez à ces deux questions :

1. À quelle famille d’artefacts cela appartient-il ? Si vous ne pouvez pas répondre à cette question, vous n’êtes pas prêt à écrire.
2. Doit-il être versionné avec le code ? Si oui, il va dans le dépôt. Sinon, il va sur le Wiki.

Un test utile pour la deuxième question : ce document deviendrait-il erroné ou trompeur si quelqu’un le lisait en comparaison avec une autre version de la base de code ? Si oui, il se trouve dans le dépôt, versionné avec le code. Si non, il se trouve sur le Wiki.

4. Le problème de l’i18n

4.1 L’argument en faveur du retrait

La justification pour supprimer tout contenu non anglais du dépôt repose sur quatre piliers :

1. Le public dispose d’une traduction à la demande. Les utilisateurs principaux de ZeroClaw sont des personnes qui exécutent un assistant IA. Chacune de ces personnes a accès à une traduction automatique instantanée et de haute qualité, que ce soit via l’agent qu’elle exécute, via son navigateur, ou via l’un des dizaines de services de traduction gratuits. Le bénéfice pratique de livrer des traductions dans le dépôt est marginal.

2. Les traductions sont très probablement obsolètes. Le contenu généré par traduction automatique a probablement été produit une seule fois et n’a pas été mis à jour en synchronisation avec la source anglaise. Une documentation obsolète est pire qu’une absence de documentation pour le développement assisté par IA, car les modèles de langage tireront des conclusions incorrectes avec confiance à partir d’informations dépassées.

3. La taxe sur les contributeurs est réelle et mesurable. L’exigence de parité imposée par docs-contract.md signifie que chaque PR de documentation doit toucher jusqu’à six versions linguistiques. Cela rend les contributions à la documentation coûteuses et décourage précisément ce type d’améliorations mineures et incrémentales (correction d’une faute de frappe, clarification d’une étape, mise à jour d’une référence obsolète) qui maintiennent la documentation en bonne santé.

4. La localisation est un travail communautaire, pas un travail du projet principal. Les communautés les mieux placées pour maintenir la documentation en japonais sont les contributeurs japonais. Placer le contenu localisé dans le dépôt principal avec une exigence de parité impose la charge aux mainteneurs principaux plutôt qu’aux communautés qui en bénéficient. Le GitHub Wiki inverse correctement cette dynamique : les membres de la communauté peuvent modifier et maintenir les pages de leur langue sans ouvrir de PR.

4.2 Ce qui reste

Un point important à conserver : la structure de l’approche i18n. L’idée de rendre ZeroClaw accessible dans plusieurs langues est pertinente. Seule la localisation et le modèle de propriété sont incorrects.

4.3 La stratégie de remplacement

1. Supprimez tous les fichiers README.*.md du répertoire racine du dépôt, sauf README.md.

2. Supprimer docs/i18n/ entièrement

3. Supprimez tous les fichiers de hub non anglais de docs/ (par exemple docs/README.zh-CN.md)

4. Ajouter une section Languages au README.md principal :

   Des traductions maintenues par la communauté sont disponibles sur le Wiki GitHub. Pour contribuer avec une traduction ou améliorer une traduction existante, modifiez le Wiki directement. Toutes les langues sont les bienvenues.

5. Créer une page Translations sur le Wiki GitHub avec un tableau des langues disponibles, leur niveau de complétude et les contributeurs qui les maintiennent.

6. Optionnellement : ajoutez une fonctionnalité CLI zeroclaw docs --translate qui utilise le fournisseur LLM configuré pour traduire n’importe quelle page de documentation à la demande, un choix naturel pour un produit dont la raison d’être est l’assistance par IA

4.4 L’impact des AGENTS.md

Supprimez l’exigence de suivi i18n de docs-contract.md. Remplacez-la par : Les PR de documentation sont examinées uniquement en anglais. Les traductions sont maintenues par la communauté sur le Wiki et ne font pas l’objet d’un examen de PR.

5. La séparation du dépôt / Wiki

5.1 La règle de décision

Un document appartient au dépôt si son contenu deviendrait erroné lorsque le code évolue. Il appartient au Wiki dans le cas contraire.

Ceci n’est pas une règle floue. Appliquez-la littéralement.

Un ADR enregistre la raison pour laquelle une décision architecturale spécifique a été prise à un moment précis. Si le code change, l’ADR décrit toujours avec précision ce qui a été décidé et quand. Le code peut s’en être éloigné, mais le registre reste exact. → Dépôt.

Un guide de configuration du canal Telegram décrit les étapes qu’un utilisateur suit avec la version actuelle du logiciel. Si le format de configuration change, le guide devient erroné. → Cela semble devoir se trouver dans le dépôt, mais ce n’est pas le cas. Les guides de configuration doivent être mis à jour selon leur propre calendrier, et non être couplés aux commits de code. Le bon modèle est le suivant : la référence de l’API (qui correspond directement aux structs de configuration) réside dans le dépôt, et le guide de configuration qui accompagne l’utilisateur dans l’utilisation de cette API réside sur le Wiki, mis à jour par n’importe qui lorsque les étapes changent.

5.2 La séparation en pratique

Reste dans le dépôt (docs/book/src/) :

Déplacement vers le Wiki GitHub (proposé ; non encore exécuté) :

Supprimé (suppression de l’internationalisation) :

5.3 La structure du wiki

Home
│
├── Getting Started
│     ├── Installation
│     ├── Quick Start (TL;DR)
│     ├── Migrating from OpenClaw
│     └── Onboarding Walkthrough
│
├── Configuration
│     ├── Providers
│     ├── Channels
│     ├── Memory
│     ├── Security & Pairing
│     └── Tunnels
│
├── Channels
│     ├── Telegram
│     ├── Discord
│     ├── Slack
│     ├── WhatsApp
│     └── ... (one page per channel)
│
├── Operations
│     ├── Troubleshooting
│     ├── Deployment
│     ├── Network Setup
│     └── Performance Tuning
│
├── Hardware
│     ├── Getting Started with Peripherals
│     ├── ESP32 Setup
│     ├── STM32 Nucleo Setup
│     └── Arduino Setup
│
└── Community
      ├── FAQ
      ├── Translations
      └── How to Contribute

6. Normes ADR

6.1 Le format

Tous les Architecture Decision Records utilisent le format Nygard, étendu avec un frontmatter YAML pour la lisibilité machine. L’ADR-004 a été le modèle identifié par cette RFC. Cette section formalise cette structure.

Chaque ADR comporte trois sections et cinq champs frontmatter :

---
id: ADR-NNN
title: Phrase impérative courte décrisant la décision
date: YYYY-MM-DD
status: proposed | accepted | deprecated | superseded-by-ADR-NNN
relates-to:
  - ADR-XXX (facultatif, liste des décisions liées)
  - crates/zeroclaw-api (facultatif, chemins de code concernés)
---

# ADR-NNN: Titre

## Contexte

Quelle est la situation, la contrainte ou le problème qui a nécessité une décision ?
Quelles forces étaient en jeu ? Quelles options ont été envisagées ?

## Décision

Qu'a-t-on décidé ? Exprimez-le à la voix active.
« Nous allons... » plutôt que « Il a été décidé que... »

## Conséquences

Quels sont les résultats de cette décision ?
Listez à la fois les conséquences positives et négatives — chaque décision comporte des compromis.
Notez toute décision ou action suivante que cela engendre.

## Références

Liens vers les fichiers de code pertinents, les problèmes et les ressources externes.

6.2 Règles du cycle de vie des ADR

• Les ADR sont immuables une fois acceptés. Si une décision change, l’ADR ancien est marqué superseded-by-ADR-NNN et un nouvel ADR est rédigé pour décrire la nouvelle décision et expliquer pourquoi elle remplace l’ancienne.
• Les ADR sont numérotés de manière séquentielle et ne sont jamais renumérotés. Les lacunes dans la séquence sont acceptables (un ADR proposé qui a été rejeté peut être retiré, laissant ainsi une lacune).
• Les ADR se trouvent dans docs/book/src/architecture/decisions/. Ils sont nommés ADR-NNN-short-slug.md.
• Des changements architecturaux importants nécessitent un ADR. « Important » signifie : une décision qui surprendrait un nouveau contributeur, une décision qui contraint les choix futurs, ou une décision impliquant un compromis non évident.

6.3 Ensemble d’ADR fondamentaux

Les décisions fondamentales et les objectifs de feuille de route suivants disposent d’ADR durables. Les ADR-001 à ADR-005 sont des enregistrements rétroactifs d’une architecture qui existe déjà. Les ADR-006 et ADR-007 décrivent des objectifs conditionnés par l’implémentation issus de FND-001 et doivent rester à l’état proposé jusqu’à ce que leurs limites correspondantes soient livrées.

Les ADR rétroactifs doivent être marqués d’une note :

Ceci est un enregistrement rétroactif d’une décision prise avant le processus formel d’ADR. La date reflète le moment où la décision a été prise, et non celui où cet enregistrement a été rédigé.

Si la date de la décision initiale est inconnue, utilisez la date d’ajout de l’enregistrement ADR et indiquez-le dans la note. Si un ADR rétroactif a déjà été remplacé par une décision ultérieure, conservez l’ADR historique et documentez l’ADR de remplacement séparément.

6.4 Pourquoi cela est important pour le développement assisté par l’IA

Lorsqu’un assistant de codage par IA lit un dépôt, il voit le code tel qu’il est actuellement. Il ne voit pas les choix qui ont été rejetés, les compromis qui ont été évalués, ni les raisons pour lesquelles une structure particulière a été choisie plutôt que d’autres. Sans ADR, l’IA proposera des modifications qui violent des contraintes architecturales qu’elle ne peut pas connaître. Avec les ADR, le raisonnement est explicite et lisible par une machine. Le frontmatter rend les ADR interrogeables : un outil IA peut trouver tous les ADR liés à zeroclaw-api et les charger comme contexte avant de modifier ce crate.

7. AGENTS.md en tant que couche de développement IA

7.1 Le motif

Le fichier racine AGENTS.md constitue le contrat compact et systématiquement chargé du projet pour le développement assisté par IA. Il définit les politiques de sécurité, de confidentialité, d’autorisation, de contribution et de validation à l’échelle du projet. La cartographie de l’architecture et des contributions oriente les tâches non triviales vers leurs sources pertinentes, tandis que les directives de l’agent de codage contiennent des détails facultatifs tels que des exemples, les attributions de stabilité actuelles, la découverte de compétences et les documents opérationnels protégés. Ce contrat en couches reste précis et affirmé sans charger chaque détail dans chaque session.

À mesure que l’espace de travail se décompose en crates (conformément à la RFC sur l’architecture micronoyau), chaque crate devrait avoir son propre AGENTS.md. C’est le mécanisme par lequel les frontières architecturales deviennent applicables au niveau de l’assistance IA, non seulement au moment de la compilation via les dépendances entre crates, mais au niveau du raisonnement, avant même que le moindre code ne soit écrit.

7.2 Ce que contient chaque fichier AGENTS.md

Gardez-les courts. Un AGENTS.md de plus de 60 lignes ne sera pas lu. Chaque fichier répond à cinq questions :

# <crate-name>

## What this crate is
One or two sentences. What problem does this crate solve?

## What this crate is allowed to depend on
List the crates this crate may import. Be explicit.
If a dependency is not listed here, do not add it without an ADR.

## Extension points
Where can new implementations be added? What trait do they implement?
Link to the relevant traits.

## What does NOT belong here
Explicit anti-patterns. What would be a mistake to add to this crate?

## Related ADRs
- ADR-NNN: Short title

7.3 Exemples

Pour crates/zeroclaw-api (une fois extrait) :

# zeroclaw-api

## What this crate is
Trait definitions and shared data types for the ZeroClaw plugin and kernel
interfaces. This is the contract layer. Everything else depends on it.

## What this crate is allowed to depend on
- serde, serde_json (serialization)
- async-trait (async trait support)
- anyhow (error types)
- tokio (async runtime types, minimal)
Nothing else. No HTTP clients. No database drivers. No external services.

## Extension points
All traits in this crate are extension points:
- `Provider` (src/providers/traits.rs) — LLM provider implementations
- `Channel` (src/channels/traits.rs) — messaging platform integrations
- `Tool` (src/tools/traits.rs) — agent tool implementations
- `Memory` (src/memory/traits.rs) — persistence backends
- `Observer` (src/observability/traits.rs) — observability backends
- `RuntimeAdapter` (src/runtime/traits.rs) — execution environments
- `Peripheral` (src/peripherals/traits.rs) — hardware integrations

## What does NOT belong here
- Any concrete implementation of any trait
- Any dependency on a specific messaging platform, LLM provider, or database
- Any network I/O or filesystem access
- Any binary or executable target

## Related ADRs
- ADR-002: Trait-driven extensibility

Pour crates/zeroclaw-kernel (une fois extrait) :

# zeroclaw-kernel

## What this crate is
The orchestration engine. Runs the agent loop, manages the service registry,
exposes the local IPC API. The kernel knows nothing about specific channels,
providers, or tools — only their abstract interfaces.

## What this crate is allowed to depend on
- zeroclaw-api (traits only)
- zeroclaw-tool-call-parser (parsing, no agent state)
- Standard async/runtime crates (tokio, anyhow, tracing)
- Config and storage crates (toml, serde, rusqlite for core memory)
NOT: any specific channel, provider, or tool implementation crate.

## Extension points
- `Registry::register_channel()` — add a channel at startup
- `Registry::register_tool()` — add a tool at startup
- `Registry::set_provider()` — set the active provider at startup
Implementations are registered by the binary crate, not by the kernel.

## What does NOT belong here
- Any import of TelegramChannel, DiscordChannel, or any named channel
- Any import of AnthropicProvider, OpenAIProvider, or any named provider
- Any tool implementation beyond the 10-12 designated core tools
- The gateway HTTP server or any web serving code

## Related ADRs
- ADR-002: Trait-driven extensibility
- ADR-006: Optional channels migrate to runtime plugins
- ADR-007: Gateway extraction into a separate optional binary

7.4 La hiérarchie des AGENTS.md

Le fichier AGENTS.md racine définit la politique compacte à l’échelle du projet. La carte d’architecture et de contribution oriente les tâches vers les sources d’architecture, de fondation, de tests, de sécurité et de maintenance. Les directives pour les agents de codage fournissent des exemples et des registres détaillés à l’échelle du projet, utiles à la demande mais ne faisant pas partie du bootstrap chargé en permanence.

Les fichiers AGENTS.md au niveau des crates affinent cette politique pour leur périmètre spécifique. Lorsqu’un outil IA lit un fichier dans crates/zeroclaw-api/, il doit lire le contrat racine, suivre la carte d’architecture pour la tâche, et lire crates/zeroclaw-api/AGENTS.md si présent. La politique de crate est plus spécifique et a la priorité dans son périmètre, mais elle ne peut pas affaiblir les exigences de sécurité, de confidentialité ou d’autorisation définies à l’échelle du projet.

8. La structure cible

Après la migration vers mdBook, la structure des sources de la documentation adjacente au code du dépôt est :

docs/book/src/
│
├── README.md                    ← mdBook introduction
├── SUMMARY.md                   ← Canonical mdBook TOC
│
├── architecture/
│   ├── overview.md              ← Current system landscape
│   ├── decisions/               ← ADRs (immutable once accepted)
│   │   ├── ADR-001-rust-first.md
│   │   ├── ADR-002-trait-driven-extensibility.md
│   │   ├── ADR-003-wasm-plugin-model.md
│   │   ├── ADR-004-tool-shared-state-ownership.md
│   │   ├── ADR-005-pluggable-memory-backends.md
│   │   ├── ADR-006-runtime-channel-plugins.md
│   │   ├── ADR-007-gateway-extraction.md
│   │   └── ADR-009-wit-wasmtime-plugin-execution.md
│   └── diagrams/
│       ├── component-map.md     ← Mermaid: crate topology
│       └── data-flow.md         ← Mermaid: message lifecycle
│
├── contributing/
│   ├── index.md
│   ├── architecture-map.md
│   ├── rfcs.md
│   ├── testing.md
│   └── pr-review-protocol.md
│
├── reference/
│   ├── index.md
│   ├── cli.md
│   ├── config.md
│   └── providers.md
│
├── security/
│   ├── overview.md
│   ├── model.md
│   ├── sandboxing.md
│   └── tool-receipts.md
│
├── hardware/
│   ├── index.md
│   ├── subsystem.md
│   ├── adding-boards-and-tools.md
│   └── hardware-peripherals-design.md
│
└── foundations/
    ├── fnd-001-intentional-architecture.md
    ├── fnd-002-documentation-standards.md
    ├── fnd-003-governance.md
    ├── fnd-004-engineering-infrastructure.md
    ├── fnd-005-contribution-culture.md
    └── fnd-006-zero-compromise-in-practice.md

Supprimé de la structure actuelle :

docs/i18n/                       ← 169 files, 2.2 MB — removed entirely
docs/maintainers/                ← project snapshots and i18n coverage maps
                                   moved to Wiki (operational, not code-adjacent)
docs/setup-guides/               ← moved to Wiki
docs/ops/                        ← moved to Wiki
README.ar.md (and 30 others)     ← removed from repo root
docs/README.ar.md (and 30 others)← removed

Le répertoire racine du dépôt devient propre :

README.md
AGENTS.md
CHANGELOG.md
CLAUDE.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
SECURITY.md
LICENSE-APACHE
LICENSE-MIT
NOTICE
Cargo.toml
Cargo.lock
... (build and config files)

Aucune variante linguistique. Aucun README dupliqué. Un seul README principal en anglais qui renvoie vers le Wiki pour les guides utilisateur et vers l’arborescence docs/ pour la référence technique.

9. Le contrat de documentation de remplacement

Le fichier docs/contributing/docs-contract.md hérité définissait une exigence de parité i18n et une structure de répertoires que cet RFC rend obsolète. Il a été supprimé ; cette section en est le remplacement.

Le remplacement régit trois choses : la classification des artefacts, la séparation repo/wiki et la gouvernance des ADR. Il ne dit rien sur l’i18n : la parité des locales est désormais gérée par la page Maintainers → Docs & Translations.

Documentation de remplacement :

# Documentation Contract

## Document Classification

Every document in `docs/` belongs to one artifact family:

- **Considerations** — principles and standards that guide decisions
- **Landscapes** — descriptions of the current system state
- **Outlines** — proposals and roadmaps for future work
- **Designs** — ADRs, API specs, and detailed technical decisions
- **Standards** — specific rules for how we build and operate

If you cannot name the family before writing, do not write yet.

## The Repo / Wiki Rule

A document lives in the repository if it would become wrong when the
code changes. It lives on the Wiki if it would not.

Reference documentation (config reference, CLI reference) lives in the
repository because it maps directly to code structures.

User guides, setup instructions, and operational how-tos live on the Wiki
because they update on their own timeline.

## ADR Governance

See `docs/book/src/architecture/decisions/` for the ADR format and lifecycle rules.

Major architectural changes require an ADR before implementation begins,
not after.

## Language

All documents in this repository are written in English.
Community-maintained translations live on the GitHub Wiki.
Documentation PRs are reviewed in English only.

## Freshness

Documents should be updated in the same PR as the code change that makes
them stale. A PR that changes a configuration format must update the
config reference. A PR that adds a new command must update the CLI reference.

RFC issues and roadmap trackers are exempt - they describe intent and
may precede implementation by multiple releases.

10. Normes que nous devrions adopter

Ces normes spécifiques à la documentation complètent les normes plus larges proposées dans la RFC d’architecture.

Cadre Diátaxis (Structure de la documentation)

Ce que c’est : Diátaxis (https://diataxis.fr) est un framework systématique pour la documentation technique qui divise le contenu en quatre types : tutoriels, guides pratiques, référence et explication. C’est le framework de documentation derrière la documentation Python, la documentation Django et bien d’autres. Il est hautement compatible avec l’approche EA Artifacts : ils répondent à des questions différentes (Diátaxis : comment structurer le contenu d’un document ; EA Artifacts : quel type de document est-ce et où réside-t-il).

Comment cela s’applique : La documentation destinée aux utilisateurs sur le Wiki doit suivre la structure Diátaxis. La documentation liée au code dans le dépôt suit les Artéfacts EA. Les deux cadres opèrent à des niveaux différents et ne sont pas en conflit.

Métadonnées Markdown pour la lisibilité machine

Tous les fichiers dans docs/ doivent inclure un en-tête YAML. Cela les rend interrogeables par les outils d’IA, les vérifications CI et les futurs outils :

---
type: adr | proposition | référence | contribution | sécurité | matériel
état: brouillon | proposé | accepté | déprécié | remplacé
dernière révision: AAAA-MM-JJ
relates-to:
  - ADR-NNN
  - crates/zeroclaw-api
---

Une vérification CI devrait s’assurer que tous les documents dans docs/ possèdent un frontmatter valide. Cela empêche que des documents soient rédigés sans déclarer au préalable leur type et leur statut, en imposant la discipline de classification au niveau de l’outillage.

CommonMark + GitHub Flavored Markdown

Toute la documentation utilise CommonMark (la spécification Markdown standardisée) avec les extensions GitHub Flavored Markdown (tableaux, listes de tâches, blocs de code délimités, diagrammes Mermaid). Aucune extension personnalisée, pas de MDX, pas de ReStructuredText. Les diagrammes Mermaid sont préférés aux fichiers image pour les diagrammes d’architecture, car ils se versionnent proprement avec le code.

Vale pour la vérification de la prose

Ce que c’est : Vale (https://vale.sh) est un linter de prose : il vérifie le style d’écriture, la cohérence et la lisibilité à l’aide de règles configurables. Il peut faire respecter des règles comme : toujours utiliser « vous » et non « l’utilisateur », éviter la voix passive dans les sections impératives, utiliser une terminologie cohérente (« plugin » et non « extension » ni « module »).

Pourquoi c’est important : La documentation actuelle manque de cohérence en termes de ton, de terminologie et de style. Certaines pages utilisent le terme « plugin », d’autres « module » ou encore « extension ». Vale rend ces règles automatiques et les applique lors de l’intégration continue (CI), de la même manière que Clippy garantit la qualité du code.

11. Feuille de route par phases

La migration de la documentation suit le même motif Strangler Fig que la migration de l’architecture : incrémentale, toujours dans un état fonctionnel, sans réécritures radicales.

Phase 1 · v0.7.0 : « Nettoyer la racine »

Livrables :

• Supprimez tous les fichiers README.*.md de la racine du dépôt (gardez uniquement README.md).
• Supprimer entièrement docs/i18n/
• Supprimez tous les fichiers de hub non anglais de docs/
• Ajoutez la section Languages au fichier README.md avec un lien vers le Wiki.
• Créer le Wiki GitHub avec la structure de base (Accueil + pages de premier niveau, ébauches de contenu)
• Supprimer l’exigence de parité i18n de docs-contract.md
• Ajouter un en-tête YAML à tous les fichiers existants dans docs/
• Créer docs/book/src/architecture/decisions/, ajouter ADR-001 et ADR-002, restaurer ADR-003 et ADR-004, et ajouter ADR-009 en tant que record WIT/wasmtime remplaçant celui de ADR-003

Indicateurs de succès :

• Le répertoire racine du dépôt contient exactement un fichier README.
• Le répertoire docs/i18n/ n’existe pas.
• Tous les fichiers docs/ ont un frontmatter YAML valide (imposé par CI).
• Le Wiki GitHub est en ligne et publiquement lié depuis le README

Phase 2 · v0.7.0–v0.8.0 : « Rédiger les ADR manquants »

Livrables :

• Rédiger l’ADR-005 comme un enregistrement rétroactif du contrat actuel de stockage en mémoire

• Je ne dispose pas du contexte nécessaire concernant les documents ADR-006, ADR-007 et FND-001 auxquels vous faites référence — il s’agit de contenu à traduire, pas d’une demande de génération de contenu.

  Veuillez fournir la chaîne de documentation technique en anglais à traduire en français.

• Ajouter une configuration Vale (.vale.ini + règles de style) et une vérification CI

• Remplacez docs-contract.md en entier par la version spécifiée dans la Section 9

• Migrer le contenu de docs/setup-guides/ vers le Wiki GitHub

• Migrer le contenu de docs/ops/ vers le Wiki GitHub

• Mettez à jour SUMMARY.md pour refléter la nouvelle structure (contenu uniquement dans le dépôt).

• Rédiger le AGENTS.md racine pour crates/zeroclaw-api (en prévision de l’extraction)

Indicateurs de succès :

• ADR-001 à ADR-007 existent avec le statut accepted, proposed ou superseded selon le cas
• ADR-009 documente la décision WIT/wasmtime qui remplace ADR-003
• La vérification Vale CI est passée avec succès sur tous les documents.
• Le wiki contient le contenu complet pour toutes les sections migrées.
• Aucun lien mort dans docs/

Phase 3 · v0.8.0–v0.9.0 : « La couche IA »

Livrables :

• Rédigez AGENTS.md pour chaque nouveau crate au fur et à mesure que l’espace de travail se décompose (selon les phases du RFC d’architecture).
• Écrire docs/book/src/architecture/diagrams/component-map.md (Mermaid, reflète la topologie des crates cibles)
• Écrire docs/book/src/architecture/diagrams/data-flow.md (Mermaid, cycle de vie des messages)
• Rédigez la documentation du SDK du plugin dans docs/book/src/developing/plugin-sdk.md
• Rédigez la documentation de l’interface WIT en parallèle des fichiers wit/ (générés à partir de WIT + explication manuelle)
• Mettez à jour la documentation de la spécification OpenAPI au fur et à mesure que l’API IPC du noyau se stabilise.

Indicateurs de succès :

• Chaque crate de l’espace de travail possède un AGENTS.md.
• Les diagrammes d’architecture sont en Mermaid (aucun fichier image binaire dans docs/).
• La documentation du SDK du plugin est suffisante pour qu’un contributeur externe puisse écrire un plugin d’outil fonctionnel.

Phase 4 · v1.0.0 : « La plateforme stable »

Livrables :

• Marquer ADR-006 et ADR-007 comme accepted une fois que le code correspondant est livré
• Versionnez la documentation de l’API IPC du noyau à v1 avec une garantie de stabilité.
• Rédiger le document de gouvernance de Plugin Registry (qui contrôle le registre, comment les plugins sont examinés et comment les plugins compromis sont révoqués)
• Publiez le SDK du plugin en tant que site de documentation autonome (à partir de docs/book/src/developing/plugin-sdk.md)
• Définir le rôle de coordinateur de la traduction du Wiki (un membre de la communauté qui maintient la page des traductions et coordonne les traducteurs bénévoles)

Indicateurs de succès :

• Tous les ADR fondamentaux sont acceptés
• Le SDK du plugin est complet et lié de manière externe depuis le README.
• Le wiki dispose de traductions activement maintenues par la communauté dans au moins deux langues.
• La documentation CI (vérification du frontmatter + Vale) passe sur chaque PR.

Annexe A : Glossaire

ADR (Architecture Decision Record) : Un enregistrement immuable d’une décision architecturale significative : le contexte qui l’a motivée, ce qui a été décidé et les conséquences. Les ADR ne changent pas une fois acceptés ; les décisions remplacées sont consignées sous forme de nouveaux ADR.

Diátaxis : Un cadre systématique pour la structure de la documentation technique qui divise le contenu en tutoriels (apprentissage), guides pratiques (orientés objectifs), référence (information) et explication (compréhension). Voir https://diataxis.fr.

EA Artifacts on a Page : Un cadre de classification pour les documents d’architecture d’entreprise développé par Svyatoslav Kotusev. Classe les artefacts en cinq familles : Considerations, Landscapes, Outlines, Designs et Standards. Voir https://eaonapage.com.

Frontmatter : métadonnées YAML en haut d’un fichier Markdown, délimitées par ---. Rend les documents lisibles par machine et interrogeables par les outils, les vérifications CI et les assistants IA.

Format Nygard : le format d’ADR introduit par Michael Nygard : trois sections (Contexte, Décision, Conséquences) qui capturent le raisonnement essentiel sans cérémonie superflue.

Strangler Fig Pattern (patron du figuier étrangleur) : Une stratégie de migration dans laquelle la nouvelle structure est construite de manière incrémentale autour de l’ancienne, en la remplaçant pièce par pièce plutôt que d’un seul coup. Le système reste fonctionnel tout au long de la migration.

Vale : Un linter de prose pour la documentation technique. Applique des règles de style, de cohérence et de lisibilité au moment de la CI, de la même manière que Clippy applique les règles de qualité du code Rust. Voir https://vale.sh.

Annexe B : Lectures complémentaires

• Framework de documentation Diátaxis : la référence incontournable pour structurer la documentation technique par type.
• EA Artifacts on a Page (v2.2) : le cadre de classification utilisé dans la Section 3.
• “Docs for Developers” : Jared Bhatti et al. : Un guide pratique de la documentation technique rédigé par des ingénieurs ayant maintenu de grands systèmes de documentation.
• Documentation Vale : guide d’installation et référence de configuration pour le linter de prose proposé à la section 10.
• Michael Nygard sur les ADR : le billet original qui a introduit le format ADR utilisé dans la section 6.
• Documentation GitHub Wikis : référence pour la mise en place et la gouvernance du wiki GitHub proposé dans la section 5.

Cette proposition a été élaborée à partir d’une analyse directe du système de documentation de ZeroClaw en version 0.6.8. Les métriques citées (169 fichiers i18n, 2,2 Mo, 31 variantes de README dans différentes langues) sont basées sur des mesures directes. Les recommandations reflètent les pratiques établies en matière de documentation technique pour les projets d’infrastructure open source, adaptées aux contraintes et aux objectifs spécifiques de ZeroClaw.

Les retours, corrections et contre-propositions sont les bienvenus. Une bonne documentation est un effort communautaire, et la meilleure structure est celle que l’équipe maintiendra effectivement.