From 44ef09da9ba89ac90b74c642dae00c905ee69fab 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

(cherry picked from commit dd0cc10e37c8d763de7ea5884552f79a1f8b8828)
---
 src/config/schema.rs | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/config/schema.rs b/src/config/schema.rs
index 630320237..e90024d55 100644
--- a/src/config/schema.rs
+++ b/src/config/schema.rs
@@ -2888,6 +2888,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.