feat(tui): support light terminal backgrounds with adaptive theme (#265)

* feat(tui): support light terminal backgrounds with adaptive theme

Replace the hardcoded dark-only color constants in theme.rs with a
runtime Theme struct that has dark() and light() factory constructors.
The active theme is stored on App and threaded through all draw
functions, enabling the TUI to render correctly on both dark and light
terminal backgrounds.

- Add Theme struct with 16 semantic style fields and ThemeMode enum
- Detect terminal background via COLORFGBG env var at startup
- Add --theme dark|light|auto CLI flag and OPENSHELL_THEME env var
- Migrate all 499 styles:: references across 11 UI files to app.theme
- Clean up 9 inline Style constructions that bypassed the theme system
- Add unit tests verifying dark/light palettes and legacy regression

Closes #264

* fix(tui): use OSC 11 query for reliable light/dark terminal detection

Replace COLORFGBG env var heuristic with terminal-colorsaurus crate,
which sends an OSC 11 query to read the actual background color. This
fixes auto-detection in iTerm2 and other terminals that don't set
COLORFGBG.

Author: johntmyers

.agents/skills/tui-development/SKILL.md

@@ -20,7 +20,7 @@ The OpenShell TUI is a ratatui-based terminal UI for the OpenShell platform. It
   - `tokio` — async runtime for event loop, spawned tasks, and mpsc channels
   - `navigator-core` — proto-generated types (`NavigatorClient`, request/response structs)
   - `navigator-bootstrap` — cluster discovery (`list_clusters()`)
-- **Theme:** NVIDIA-branded green on dark terminal background
+- **Theme:** Adaptive dark/light via `Theme` struct — NVIDIA-branded green accents. Controlled by `--theme` flag, `OPENSHELL_THEME` env var, or auto-detection.
 
 ## 2. Domain Object Hierarchy
 
@@ -172,44 +172,82 @@ tokio::time::timeout(Duration::from_secs(5), client.health(req)).await
 
 ## 5. Style Guide & Colors
 
-### NVIDIA Green Theme (`theme.rs`)
+### Theme System (`theme.rs`)
 
-All colors and styles are defined in `crates/navigator-tui/src/theme.rs`.
+Colors and styles are defined in `crates/navigator-tui/src/theme.rs` via the `Theme` struct. The TUI supports dark and light terminal backgrounds.
 
-#### Colors (`theme::colors`)
+#### Theme selection
+
+Theme mode is controlled by three mechanisms (highest priority first):
+
+1. `--theme dark|light|auto` CLI flag on `openshell term`
+2. `OPENSHELL_THEME` environment variable
+3. Auto-detection via `COLORFGBG` env var (falls back to dark)
+
+The `ThemeMode` enum (`Auto`, `Dark`, `Light`) is resolved at startup via `theme::detect()` before entering raw mode.
+
+#### Brand colors (`theme::brand`)
 
 | Constant | Value | Usage |
 | --- | --- | --- |
-| `NVIDIA_GREEN` | `Color::Rgb(118, 185, 0)` | Primary accent — selections, active items, key hints |
-| `EVERGLADE` | `Color::Rgb(18, 49, 35)` | Dark green — borders (unfocused), title bar background |
-| `BG` | `Color::Black` | Terminal background |
-| `FG` | `Color::White` | Default foreground text |
+| `NVIDIA_GREEN` | `Color::Rgb(118, 185, 0)` | Primary accent (dark theme) |
+| `NVIDIA_GREEN_DARK` | `Color::Rgb(80, 140, 0)` | Primary accent (light theme — darker for contrast) |
+| `EVERGLADE` | `Color::Rgb(18, 49, 35)` | Dark green — borders, title bar bg (dark theme) |
+| `MAROON` | `Color::Rgb(128, 0, 0)` | Pacman chase animation |
+
+#### Theme struct fields
+
+The `Theme` struct has 16 `Style` fields, accessed at runtime via `app.theme`:
+
+| Field | Dark value | Light value | Usage |
+| --- | --- | --- | --- |
+| `text` | White fg | Near-black fg | Default body text |
+| `muted` | White + DIM | Gray fg | Secondary info, separators |
+| `heading` | White + BOLD | Near-black + BOLD | Panel titles, names |
+| `accent` | NVIDIA_GREEN fg | NVIDIA_GREEN_DARK fg | Selected row marker, source labels |
+| `accent_bold` | NVIDIA_GREEN + BOLD | NVIDIA_GREEN_DARK + BOLD | Brand text, command prompt |
+| `selected` | BOLD only | BOLD only | Selected row emphasis |
+| `border` | EVERGLADE fg | Light sage fg | Unfocused panel borders |
+| `border_focused` | NVIDIA_GREEN fg | NVIDIA_GREEN_DARK fg | Focused panel borders |
+| `status_ok` | NVIDIA_GREEN fg | NVIDIA_GREEN_DARK fg | Healthy, INFO, Ready |
+| `status_warn` | Yellow fg | Dark yellow fg | Degraded, WARN, Provisioning |
+| `status_err` | Red fg | Dark red fg | Unhealthy, ERROR |
+| `key_hint` | NVIDIA_GREEN fg | NVIDIA_GREEN_DARK fg | Keyboard shortcut labels |
+| `log_cursor` | EVERGLADE bg | Light green bg | Selected log line highlight |
+| `claw` | MAROON + BOLD | MAROON + BOLD | Pacman animation |
+| `title_bar` | White on EVERGLADE + BOLD | Near-black on light green + BOLD | Title bar strip |
+| `badge` | Black on NVIDIA_GREEN + BOLD | White on NVIDIA_GREEN_DARK + BOLD | Notification badges |
+
+#### Accessing the theme in draw functions
+
+The `Theme` is stored on `App` and accessed via a local alias:
+
+```rust
+fn draw_my_widget(frame: &mut Frame<'_>, app: &App, area: Rect) {
+    let t = &app.theme;
+    frame.render_widget(
+        Paragraph::new(Span::styled("Hello", t.text)),
+        area,
+    );
+}
+```
 
-#### Styles (`theme::styles`)
+For functions that don't take `&App` (e.g., detail popups, helpers), pass `&Theme` as a parameter:
 
-| Constant | Definition | Usage |
-| --- | --- | --- |
-| `TEXT` | White foreground | Default body text |
-| `MUTED` | White + DIM modifier | Secondary info, separators (`│`), unfocused items |
-| `HEADING` | White + BOLD | Panel titles, sandbox/cluster names when active |
-| `ACCENT` | NVIDIA_GREEN foreground | Selected row marker (`▌`), sandbox source labels |
-| `ACCENT_BOLD` | NVIDIA_GREEN + BOLD | "OpenShell" brand text, command prompt `:` |
-| `SELECTED` | BOLD modifier only | Selected row text emphasis |
-| `BORDER` | EVERGLADE foreground | Unfocused panel borders |
-| `BORDER_FOCUSED` | NVIDIA_GREEN foreground | Focused panel borders |
-| `STATUS_OK` | NVIDIA_GREEN foreground | Healthy status, INFO log level, Ready phase |
-| `STATUS_WARN` | Yellow foreground | Degraded status, WARN log level, Provisioning phase |
-| `STATUS_ERR` | Red foreground | Unhealthy status, ERROR log level, Error phase |
-| `KEY_HINT` | NVIDIA_GREEN foreground | Keyboard shortcut labels in nav bar (e.g., `[Tab]`) |
-| `TITLE_BAR` | White on EVERGLADE + BOLD | Title bar background strip |
+```rust
+fn draw_detail_popup(frame: &mut Frame<'_>, data: &MyData, area: Rect, theme: &Theme) {
+    let t = theme;
+    // ...
+}
+```
 
 #### Visual conventions
 
 - **Selected row**: Green `▌` left-border marker on the selected row. Active gateway also gets a green `●` dot.
-- **Focused panel**: Border changes from `EVERGLADE` to `NVIDIA_GREEN`.
+- **Focused panel**: Border changes from `border` to `border_focused` style.
 - **Status indicators**: Green for healthy/ready/info, yellow for degraded/provisioning/warn, red for unhealthy/error.
 - **Separators**: Muted `│` characters between title bar segments and nav bar sections.
-- **Log source labels**: `"sandbox"` source renders in `ACCENT` (green), `"gateway"` in `MUTED`.
+- **Log source labels**: `"sandbox"` source renders in `accent` (green), `"gateway"` in `muted`.
 
 ## 6. UX Conventions
 

Cargo.lock

@@ -46,6 +46,7 @@ indicatif = "0.17"
 owo-colors = "4"
 ratatui = "0.26"
 crossterm = "0.28"
+terminal-colorsaurus = "1.0"
 
 # Error handling
 miette = { version = "7", features = ["fancy"] }

Cargo.toml

@@ -450,7 +450,11 @@ enum Commands {
     // ===================================================================
     /// Launch the `OpenShell` interactive TUI.
     #[command(help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")]
-    Term,
+    Term {
+        /// Color theme for the TUI: auto, dark, or light.
+        #[arg(long, default_value = "auto", env = "OPENSHELL_THEME")]
+        theme: navigator_tui::ThemeMode,
+    },
 
     /// Generate shell completions.
     #[command(after_long_help = COMPLETIONS_HELP, help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")]
@@ -2024,12 +2028,12 @@ async fn main() -> Result<()> {
                 }
             }
         }
-        Some(Commands::Term) => {
+        Some(Commands::Term { theme }) => {
             let ctx = resolve_gateway(&cli.gateway, &cli.gateway_endpoint)?;
             let mut tls = tls.with_gateway_name(&ctx.name);
             apply_edge_auth(&mut tls, &ctx.name);
             let channel = navigator_cli::tls::build_channel(&ctx.endpoint, &tls).await?;
-            navigator_tui::run(channel, &ctx.name, &ctx.endpoint).await?;
+            navigator_tui::run(channel, &ctx.name, &ctx.endpoint, theme).await?;
         }
         Some(Commands::Completions { shell }) => {
             let exe = std::env::current_exe()

crates/navigator-cli/src/main.rs

@@ -18,6 +18,7 @@ navigator-providers = { path = "../navigator-providers" }
 
 ratatui = { workspace = true }
 crossterm = { workspace = true }
+terminal-colorsaurus = { workspace = true }
 tokio = { workspace = true }
 tonic = { workspace = true, features = ["tls"] }
 miette = { workspace = true }

crates/navigator-tui/Cargo.toml

@@ -274,6 +274,9 @@ pub struct App {
     pub focus: Focus,
     pub command_input: String,
 
+    /// Active color theme (dark or light).
+    pub theme: crate::theme::Theme,
+
     /// When the splash screen was shown (for auto-dismiss timing).
     pub splash_start: Option<Instant>,
 
@@ -380,13 +383,19 @@ pub struct App {
 }
 
 impl App {
-    pub fn new(client: NavigatorClient<Channel>, gateway_name: String, endpoint: String) -> Self {
+    pub fn new(
+        client: NavigatorClient<Channel>,
+        gateway_name: String,
+        endpoint: String,
+        theme: crate::theme::Theme,
+    ) -> Self {
         Self {
             running: true,
             screen: Screen::Splash,
             input_mode: InputMode::Normal,
             focus: Focus::Gateways,
             command_input: String::new(),
+            theme,
             splash_start: Some(Instant::now()),
             gateway_name,
             endpoint,