diff --git a/apps/desktop-tauri/src/types/bridge.ts b/apps/desktop-tauri/src/types/bridge.ts
index 6387fcac..c1e1cb78 100644
--- a/apps/desktop-tauri/src/types/bridge.ts
+++ b/apps/desktop-tauri/src/types/bridge.ts
@@ -220,6 +220,7 @@ export interface SettingsSnapshot {
   enabledProviders: string[];
   providerOrder?: string[];
   refreshIntervalSecs: number;
+  /** Legacy compatibility field; opening a tray/menu surface does not force-refresh. */
   refreshAllProvidersOnMenuOpen: boolean;
   startAtLogin: boolean;
   startMinimized: boolean;
diff --git a/docs/SETTINGS_JSON.md b/docs/SETTINGS_JSON.md
index 93a6322e..97243815 100644
--- a/docs/SETTINGS_JSON.md
+++ b/docs/SETTINGS_JSON.md
@@ -13,7 +13,7 @@ fields marked safe, but Ceiling may overwrite the file when the app exits.
 |---|---|---|---|
 | `enabled_providers` | array of strings | `["claude","codex","cursor","grok"]` | Provider CLI names to monitor. Safe to edit. |
 | `refresh_interval_secs` | number | `300` | `0` means manual refresh only. Safe to edit. |
-| `refresh_all_providers_on_menu_open` | boolean | `false` | Force-refresh when a tray/menu surface opens. Safe to edit. |
+| `refresh_all_providers_on_menu_open` | boolean | `false` | Legacy compatibility field. Nothing reads this flag — opening a tray/menu surface does not force-refresh. Leave it unchanged. |
 | `start_minimized` | boolean | `false` | Start minimized. Safe to edit. |
 | `start_at_login` | boolean | `false` | Start at Windows sign-in. Safe to edit. |
 | `show_notifications` | boolean | `true` | Show usage notifications. Safe to edit. |
diff --git a/rust/src/settings.rs b/rust/src/settings.rs
index f0a43f0b..9a2a2d32 100755
--- a/rust/src/settings.rs
+++ b/rust/src/settings.rs
@@ -213,7 +213,8 @@ pub struct Settings {
     /// Refresh interval in seconds (0 = manual only)
     pub refresh_interval_secs: u64,
 
-    /// Force-refresh enabled providers whenever the tray/menu surface opens.
+    /// Legacy compatibility field. Opening a tray/menu surface does not
+    /// force-refresh; nothing reads this flag.
     #[serde(default)]
     pub refresh_all_providers_on_menu_open: bool,