From 82b715304f6ad8bc734aa84960c08423f9d5bbdd Mon Sep 17 00:00:00 2001
From: argenis de la rosa <theonlyhennygod@gmail.com>
Date: Wed, 4 Mar 2026 05:43:40 -0500
Subject: [PATCH] docs(config): clarify fallback_api_keys contract

---
 src/config/schema.rs | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/config/schema.rs b/src/config/schema.rs
index 78a88ac0d..db21d2a3d 100644
--- a/src/config/schema.rs
+++ b/src/config/schema.rs
@@ -4022,6 +4022,12 @@ pub struct ReliabilityConfig {
     pub fallback_providers: Vec<String>,
     /// Optional per-fallback provider API keys keyed by fallback entry name.
     /// This allows distinct credentials for multiple `custom:<url>` endpoints.
+    ///
+    /// Contract:
+    /// - Default/omitted (`{}` via `#[serde(default)]`): no per-entry override is used.
+    /// - Compatibility: additive and non-breaking for existing configs that omit this field.
+    /// - Rollback/migration: remove this map (or specific entries) to revert to provider/env-based
+    ///   credential resolution.
     #[serde(default)]
     pub fallback_api_keys: std::collections::HashMap<String, String>,
     /// Additional API keys for round-robin rotation on rate-limit (429) errors.