v0.1.0-pre.073

docs/guides/CONFIGURATION.md

@@ -0,0 +1,79 @@
+<!-- file: docs/guides/CONFIGURATION.md -->
+<!-- version: 1 -->
+
+# Guide de configuration
+
+## Objectif
+
+Ce guide décrit le chargement et l’utilisation de la configuration bot3. La référence d’API détaillée reste `kb-config/USAGE.md`.
+
+## Fichiers actifs
+
+- `config/example.config.json` : exemple utilisateur complet ;
+- `config/schema.config.json` : contrat JSON formel ;
+- `.env` et variantes locales : valeurs d’environnement non versionnées ;
+- `.env.example` : noms de variables attendues sans secrets.
+
+Le format actif est JSON. Le futur split de configuration prévu en `0.5.x` ne modifie pas le contrat actuel.
+
+## Séquence de chargement
+
+1. charger les fichiers d’environnement autorisés avec `load_workspace_environment` ;
+2. lire le fichier JSON ;
+3. résoudre les placeholders `${NAME}` ou `${NAME:-fallback}` ;
+4. parser avec `load_config_from_str` ou `load_config_from_path` ;
+5. valider le schéma et les invariants typés ;
+6. sélectionner le profil actif avec `active_profile`.
+
+## Exemple opérateur
+
+```rust
+let environment = match kb_config::load_workspace_environment(
+    std::path::Path::new("."),
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+
+let config = match kb_config::load_config_from_path(
+    std::path::Path::new("config/example.config.json"),
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+
+let profile = match kb_config::active_profile(&config) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+
+println!("loaded environment files={}", environment.loaded_files.len());
+println!("active profile={}", profile.name);
+```
+
+## Invariants
+
+- aucun secret ne doit être ajouté à l’exemple versionné ;
+- les placeholders non résolus doivent provoquer un diagnostic explicite ;
+- le schéma embarqué et `config/schema.config.json` doivent rester identiques ;
+- une sérialisation publique doit être précédée d’une validation ;
+- les noms de profils et rôles d’endpoints doivent rester cohérents avec leurs consommateurs.
+
+## Diagnostic
+
+Pour isoler une erreur :
+
+1. afficher la liste des fichiers d’environnement chargés ;
+2. résoudre le JSON sans l’écrire dans les logs s’il contient des secrets ;
+3. valider le schéma ;
+4. valider le modèle typé ;
+5. vérifier le profil actif ;
+6. vérifier les rôles HTTP, WebSocket, stockage et logging.
+
+## Références
+
+- `kb-config/README.md` ;
+- `kb-config/USAGE.md` ;
+- `kb-config/TODO.md` ;
+- `config/README.md` ;
+- `docs/decisions/WINCODE_COMPATIBILITY_POLICY.md`.