0.5.1-pre.004

docs/guides/CONFIGURATION.md

@@ -1,5 +1,5 @@
 <!-- file: docs/guides/CONFIGURATION.md -->
-<!-- version: 3 -->
+<!-- version: 4 -->
 
 # Guide de configuration
 
@@ -11,32 +11,28 @@ Ce guide décrit le chargement et l’utilisation de la configuration bot3. La r
 
 - `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`, ou le fichier sélectionné par `KS_ENV_FILE` : 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`.
+L’API recommandée est `read_config_json_file_with_environment`. Elle :
+
+1. charge `.env`, ou le fichier explicitement sélectionné par `KS_ENV_FILE`, sans écraser les variables du processus ;
+2. lit le JSON ;
+3. résout les placeholders namespacés `${KS_*}` / `${KB_*}` et les fallbacks éventuels ;
+4. valide le schéma JSON ;
+5. désérialise les types de configuration et applique les invariants métier ;
+6. laisse ensuite `active_profile` sélectionner le profil actif.
 
 ## Exemple opérateur
 
 ```rust
-let environment = match ks_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 ks_config::load_config_from_path(
+let config = match ks_config::read_config_json_file_with_environment(
     std::path::Path::new("config/example.config.json"),
+    std::path::Path::new("."),
 ) {
     std::result::Result::Ok(value) => value,
     std::result::Result::Err(error) => return std::result::Result::Err(error),
@@ -47,7 +43,6 @@ let profile = match ks_config::active_profile(&config) {
     std::result::Result::Err(error) => return std::result::Result::Err(error),
 };
 
-println!("loaded environment files={}", environment.loaded_files.len());
 println!("active profile={}", profile.name);
 ```
 
@@ -56,7 +51,7 @@ println!("active profile={}", profile.name);
 - 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 ;
+- tant que `0.5.1-pre.006` n’a pas introduit les DTO publics sûrs, la configuration runtime résolue reste strictement backend et ne doit pas être exposée telle quelle ;
 - les noms de profils et rôles d’endpoints doivent rester cohérents avec leurs consommateurs.
 
 ## Quotas HTTP cumulés