khadhroony-bot3/docs/guides/CONFIGURATION.md

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

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.