diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx
index 39f8940932..2eb24f8f0b 100644
--- a/.storybook/preview.tsx
+++ b/.storybook/preview.tsx
@@ -1,6 +1,6 @@
 import React from "react";
 import type { Preview } from "@storybook/react-vite";
-import { ThemeProvider, type ThemeMode } from "../src/browser/contexts/ThemeContext";
+import { ThemeProvider, type ResolvedThemeMode } from "../src/browser/contexts/ThemeContext";
 import "../src/browser/styles/globals.css";
 import {
   TUTORIAL_STATE_KEY,
@@ -91,7 +91,7 @@ const preview: Preview = {
     // Theme provider
     (Story, context) => {
       // Default to dark if mode not set (e.g., Chromatic headless browser defaults to light)
-      const mode = (context.globals.theme as ThemeMode | undefined) ?? "dark";
+      const mode = (context.globals.theme as ResolvedThemeMode | undefined) ?? "dark";
 
       // Apply theme synchronously before React renders - critical for Chromatic snapshots
       if (typeof document !== "undefined") {
diff --git a/index.html b/index.html
index 20943cff1f..de6d634810 100644
--- a/index.html
+++ b/index.html
@@ -106,13 +106,13 @@
     <script>
       (function () {
         const THEME_KEY = "uiTheme";
-        const VALID_THEMES = new Set([
+        const VALID_PREFERENCES = new Set([
+          "system",
           "light",
           "dark",
           "flexoki-light",
           "flexoki-dark",
         ]);
-
         const THEME_COLORS = {
           dark: "#1e1e1e",
           light: "#f5f6f8",
@@ -121,7 +121,7 @@
         };
 
         function getColorScheme(theme) {
-          return theme === "light" || theme.endsWith("-light") ? "light" : "dark";
+          return theme === "light" || theme === "flexoki-light" ? "light" : "dark";
         }
 
         try {
@@ -137,23 +137,16 @@
             }
           }
 
-          const prefersLight = window.matchMedia
-            ? window.matchMedia("(prefers-color-scheme: light)").matches
-            : false;
-
-          const fallbackTheme = prefersLight ? "light" : "dark";
-          let theme = fallbackTheme;
-
-          if (typeof parsed === "string") {
-            if (VALID_THEMES.has(parsed)) {
-              theme = parsed;
-            } else if (parsed.endsWith("-light")) {
-              theme = "light";
-            } else if (parsed.endsWith("-dark")) {
-              theme = "dark";
-            }
-          }
+          // Normalize preference (unknown → "system")
+          const preference =
+            typeof parsed === "string" && VALID_PREFERENCES.has(parsed) ? parsed : "system";
 
+          // Resolve system preference to actual theme
+          const systemTheme =
+            window.matchMedia && window.matchMedia("(prefers-color-scheme: light)").matches
+              ? "light"
+              : "dark";
+          const theme = preference === "system" ? systemTheme : preference;
           const colorScheme = getColorScheme(theme);
 
           document.documentElement.dataset.theme = theme;
@@ -161,10 +154,7 @@
 
           const metaThemeColor = document.querySelector('meta[name="theme-color"]');
           if (metaThemeColor) {
-            metaThemeColor.setAttribute(
-              "content",
-              THEME_COLORS[theme] ?? THEME_COLORS[colorScheme] ?? "#1e1e1e"
-            );
+            metaThemeColor.setAttribute("content", THEME_COLORS[theme] ?? "#1e1e1e");
           }
         } catch (error) {
           console.warn("Failed to apply preferred theme early", error);
diff --git a/src/browser/App.tsx b/src/browser/App.tsx
index b06870061a..1b3e67b587 100644
--- a/src/browser/App.tsx
+++ b/src/browser/App.tsx
@@ -23,7 +23,7 @@ import { useStableReference, compareMaps } from "./hooks/useStableReference";
 import { CommandRegistryProvider, useCommandRegistry } from "./contexts/CommandRegistryContext";
 import { useOpenTerminal } from "./hooks/useOpenTerminal";
 import type { CommandAction } from "./contexts/CommandRegistryContext";
-import { useTheme, type ThemeMode } from "./contexts/ThemeContext";
+import { useTheme } from "./contexts/ThemeContext";
 import { CommandPalette } from "./components/CommandPalette";
 import { buildCoreSources, type BuildSourcesParams } from "./utils/commands/sources";
 
@@ -77,12 +77,6 @@ function AppInner() {
   } = useWorkspaceContext();
   const { theme, setTheme, toggleTheme } = useTheme();
   const { open: openSettings } = useSettings();
-  const setThemePreference = useCallback(
-    (nextTheme: ThemeMode) => {
-      setTheme(nextTheme);
-    },
-    [setTheme]
-  );
   const { api, status, error, authenticate } = useAPI();
 
   const {
@@ -455,7 +449,7 @@ function AppInner() {
       });
     },
     onToggleTheme: toggleTheme,
-    onSetTheme: setThemePreference,
+    onSetTheme: setTheme,
     onOpenSettings: openSettings,
     onClearTimingStats: (workspaceId: string) => workspaceStore.clearTimingStats(workspaceId),
     api,
diff --git a/src/browser/components/Messages/MarkdownComponents.tsx b/src/browser/components/Messages/MarkdownComponents.tsx
index 4a65e2fd3d..1c29f7e803 100644
--- a/src/browser/components/Messages/MarkdownComponents.tsx
+++ b/src/browser/components/Messages/MarkdownComponents.tsx
@@ -42,7 +42,7 @@ interface CodeBlockProps {
  */
 const CodeBlock: React.FC<CodeBlockProps> = ({ code, language }) => {
   const [highlightedLines, setHighlightedLines] = useState<string[] | null>(null);
-  const { theme: themeMode } = useTheme();
+  const { resolvedTheme } = useTheme();
 
   // Split code into lines, removing trailing empty line
   const plainLines = code
@@ -51,7 +51,7 @@ const CodeBlock: React.FC<CodeBlockProps> = ({ code, language }) => {
 
   useEffect(() => {
     let cancelled = false;
-    const isLight = themeMode === "light" || themeMode.endsWith("-light");
+    const isLight = resolvedTheme === "light" || resolvedTheme.endsWith("-light");
     const theme = isLight ? "light" : "dark";
 
     setHighlightedLines(null);
@@ -78,7 +78,7 @@ const CodeBlock: React.FC<CodeBlockProps> = ({ code, language }) => {
     return () => {
       cancelled = true;
     };
-  }, [code, language, themeMode]);
+  }, [code, language, resolvedTheme]);
 
   const lines = highlightedLines ?? plainLines;
   const isSingleLine = lines.length === 1;
diff --git a/src/browser/components/ProjectSidebar.tsx b/src/browser/components/ProjectSidebar.tsx
index 7b984a46e4..a013af86f2 100644
--- a/src/browser/components/ProjectSidebar.tsx
+++ b/src/browser/components/ProjectSidebar.tsx
@@ -245,8 +245,9 @@ const ProjectSidebarInner: React.FC<ProjectSidebarProps> = ({
   } = useProjectContext();
 
   // Theme for logo variant
-  const { theme } = useTheme();
-  const MuxLogo = theme === "dark" || theme.endsWith("-dark") ? MuxLogoDark : MuxLogoLight;
+  const { resolvedTheme } = useTheme();
+  const MuxLogo =
+    resolvedTheme === "dark" || resolvedTheme.endsWith("-dark") ? MuxLogoDark : MuxLogoLight;
 
   // Mobile breakpoint for auto-closing sidebar
   const MOBILE_BREAKPOINT = 768;
diff --git a/src/browser/components/RightSidebar/FileViewer/TextFileViewer.tsx b/src/browser/components/RightSidebar/FileViewer/TextFileViewer.tsx
index f294a2c790..633bc4e4c7 100644
--- a/src/browser/components/RightSidebar/FileViewer/TextFileViewer.tsx
+++ b/src/browser/components/RightSidebar/FileViewer/TextFileViewer.tsx
@@ -137,7 +137,7 @@ function buildUnifiedView(content: string, diffText: string): UnifiedLine[] | nu
 }
 
 export const TextFileViewer: React.FC<TextFileViewerProps> = (props) => {
-  const { theme: themeMode } = useTheme();
+  const { resolvedTheme } = useTheme();
   const language = getLanguageFromPath(props.filePath);
   const languageDisplayName = getLanguageDisplayName(language);
 
@@ -160,7 +160,7 @@ export const TextFileViewer: React.FC<TextFileViewerProps> = (props) => {
       ? unifiedLines.map((l) => l.content)
       : fileLines.filter((l, i, arr) => i < arr.length - 1 || l !== "");
 
-    const theme = themeMode === "light" || themeMode.endsWith("-light") ? "light" : "dark";
+    const theme = resolvedTheme === "light" || resolvedTheme.endsWith("-light") ? "light" : "dark";
 
     let cancelled = false;
 
@@ -181,7 +181,7 @@ export const TextFileViewer: React.FC<TextFileViewerProps> = (props) => {
     return () => {
       cancelled = true;
     };
-  }, [unifiedLines, fileLines, language, themeMode]);
+  }, [unifiedLines, fileLines, language, resolvedTheme]);
 
   const addedCount = unifiedLines?.filter((l) => l.type === "added").length ?? 0;
   const removedCount = unifiedLines?.filter((l) => l.type === "removed").length ?? 0;
diff --git a/src/browser/components/ThemeToggleButton.tsx b/src/browser/components/ThemeToggleButton.tsx
index 12ddfdfd7c..4bb5c48965 100644
--- a/src/browser/components/ThemeToggleButton.tsx
+++ b/src/browser/components/ThemeToggleButton.tsx
@@ -3,8 +3,8 @@ import { useTheme } from "@/browser/contexts/ThemeContext";
 import { Tooltip, TooltipTrigger, TooltipContent } from "./ui/tooltip";
 
 export function ThemeToggleButton() {
-  const { theme, toggleTheme } = useTheme();
-  const isLightTheme = theme === "light" || theme.endsWith("-light");
+  const { resolvedTheme, toggleTheme } = useTheme();
+  const isLightTheme = resolvedTheme === "light" || resolvedTheme === "flexoki-light";
   const label = isLightTheme ? "Switch to dark theme" : "Switch to light theme";
   const Icon = isLightTheme ? MoonStar : SunMedium;
 
diff --git a/src/browser/components/shared/DiffRenderer.tsx b/src/browser/components/shared/DiffRenderer.tsx
index de08c38341..9c8f739eef 100644
--- a/src/browser/components/shared/DiffRenderer.tsx
+++ b/src/browser/components/shared/DiffRenderer.tsx
@@ -500,13 +500,19 @@ export const DiffRenderer: React.FC<DiffRendererProps> = ({
   className,
 }) => {
   // Detect language for syntax highlighting (memoized to prevent repeated detection)
-  const { theme } = useTheme();
+  const { resolvedTheme } = useTheme();
   const language = React.useMemo(
     () => (filePath ? getLanguageFromPath(filePath) : "text"),
     [filePath]
   );
 
-  const highlightedChunks = useHighlightedDiff(content, language, oldStart, newStart, theme);
+  const highlightedChunks = useHighlightedDiff(
+    content,
+    language,
+    oldStart,
+    newStart,
+    resolvedTheme
+  );
 
   const lineNumberWidths = React.useMemo(() => {
     if (!showLineNumbers || !highlightedChunks) {
@@ -866,7 +872,7 @@ export const SelectableDiffRenderer = React.memo<SelectableDiffRendererProps>(
         window.removeEventListener("blur", stopDragging);
       };
     }, []);
-    const { theme } = useTheme();
+    const { resolvedTheme } = useTheme();
     const [selection, setSelection] = React.useState<LineSelection | null>(null);
 
     // Notify parent when composition state changes
@@ -895,7 +901,7 @@ export const SelectableDiffRenderer = React.memo<SelectableDiffRendererProps>(
       enableHighlighting ? language : "text",
       oldStart,
       newStart,
-      theme
+      resolvedTheme
     );
 
     // Parse raw lines once for use in lineData
diff --git a/src/browser/components/tools/shared/HighlightedCode.tsx b/src/browser/components/tools/shared/HighlightedCode.tsx
index 1b2d4bcef2..2deb4e59b8 100644
--- a/src/browser/components/tools/shared/HighlightedCode.tsx
+++ b/src/browser/components/tools/shared/HighlightedCode.tsx
@@ -25,13 +25,13 @@ export const HighlightedCode: React.FC<HighlightedCodeProps> = ({
   startLineNumber = 1,
 }) => {
   const [highlightedLines, setHighlightedLines] = useState<string[] | null>(null);
-  const { theme: themeMode } = useTheme();
+  const { resolvedTheme } = useTheme();
 
   const plainLines = code.split("\n").filter((line, i, arr) => i < arr.length - 1 || line !== "");
 
   useEffect(() => {
     let cancelled = false;
-    const theme = themeMode === "light" || themeMode.endsWith("-light") ? "light" : "dark";
+    const theme = resolvedTheme === "light" || resolvedTheme.endsWith("-light") ? "light" : "dark";
 
     setHighlightedLines(null);
 
@@ -53,7 +53,7 @@ export const HighlightedCode: React.FC<HighlightedCodeProps> = ({
     return () => {
       cancelled = true;
     };
-  }, [code, language, themeMode]);
+  }, [code, language, resolvedTheme]);
 
   const lines = highlightedLines ?? plainLines;
 
diff --git a/src/browser/contexts/ThemeContext.test.tsx b/src/browser/contexts/ThemeContext.test.tsx
index f04542468f..bb86827a37 100644
--- a/src/browser/contexts/ThemeContext.test.tsx
+++ b/src/browser/contexts/ThemeContext.test.tsx
@@ -19,13 +19,12 @@ import { UI_THEME_KEY } from "@/common/constants/storage";
 
 // Helper to access internals
 const TestComponent = () => {
-  const { theme, toggleTheme } = useTheme();
+  const { theme, resolvedTheme, toggleTheme } = useTheme();
   return (
     <div>
-      <span data-testid="theme-value">{theme}</span>
-      <button onClick={toggleTheme} data-testid="toggle-btn">
-        Toggle
-      </button>
+      <span data-testid="theme">{theme}</span>
+      <span data-testid="resolved">{resolvedTheme}</span>
+      <button onClick={toggleTheme}>Toggle</button>
     </div>
   );
 };
@@ -66,44 +65,26 @@ describe("ThemeContext", () => {
     }
   });
 
-  test("uses persisted state by default", () => {
+  test("defaults to system theme", () => {
     const { getByTestId } = render(
       <ThemeProvider>
         <TestComponent />
       </ThemeProvider>
     );
-    // If matchMedia matches is false (default mock), resolveSystemTheme returns 'dark' (since it checks prefers-color-scheme: light)
-    // resolveSystemTheme logic: window.matchMedia("(prefers-color-scheme: light)").matches ? "light" : "dark"
-    expect(getByTestId("theme-value").textContent).toBe("dark");
+    // Default is "system", which resolves to "dark" when matchMedia returns false for prefers-color-scheme: light
+    expect(getByTestId("theme").textContent).toBe("system");
+    expect(getByTestId("resolved").textContent).toBe("dark");
   });
 
-  test("respects forcedTheme prop", () => {
-    const { getByTestId, rerender } = render(
-      <ThemeProvider forcedTheme="light">
-        <TestComponent />
-      </ThemeProvider>
-    );
-    expect(getByTestId("theme-value").textContent).toBe("light");
-
-    rerender(
-      <ThemeProvider forcedTheme="dark">
-        <TestComponent />
-      </ThemeProvider>
-    );
-    expect(getByTestId("theme-value").textContent).toBe("dark");
-  });
-
-  test("forcedTheme overrides persisted state", () => {
+  test("forcedTheme overrides resolved theme without changing preference", () => {
     window.localStorage.setItem(UI_THEME_KEY, JSON.stringify("light"));
-
     const { getByTestId } = render(
       <ThemeProvider forcedTheme="dark">
         <TestComponent />
       </ThemeProvider>
     );
-    expect(getByTestId("theme-value").textContent).toBe("dark");
-
-    // Check that localStorage is still light (since forcedTheme doesn't write to storage by itself)
-    expect(JSON.parse(window.localStorage.getItem(UI_THEME_KEY)!)).toBe("light");
+    // Preference unchanged, but resolved theme is forced
+    expect(getByTestId("theme").textContent).toBe("light");
+    expect(getByTestId("resolved").textContent).toBe("dark");
   });
 });
diff --git a/src/browser/contexts/ThemeContext.tsx b/src/browser/contexts/ThemeContext.tsx
index 52238a574e..95ab07d4c6 100644
--- a/src/browser/contexts/ThemeContext.tsx
+++ b/src/browser/contexts/ThemeContext.tsx
@@ -2,16 +2,23 @@ import React, {
   createContext,
   useCallback,
   useContext,
+  useEffect,
   useLayoutEffect,
   useMemo,
+  useState,
   type ReactNode,
 } from "react";
 import { usePersistedState } from "@/browser/hooks/usePersistedState";
 import { UI_THEME_KEY } from "@/common/constants/storage";
 
-export type ThemeMode = "light" | "dark" | "flexoki-light" | "flexoki-dark";
+/** User's theme selection (includes "system" for OS-matching) */
+export type ThemeMode = "system" | "light" | "dark" | "flexoki-light" | "flexoki-dark";
+
+/** Concrete theme applied to the document (never "system") */
+export type ResolvedThemeMode = Exclude<ThemeMode, "system">;
 
 export const THEME_OPTIONS: Array<{ value: ThemeMode; label: string }> = [
+  { value: "system", label: "System" },
   { value: "light", label: "Light" },
   { value: "dark", label: "Dark" },
   { value: "flexoki-light", label: "Flexoki Light" },
@@ -20,30 +27,20 @@ export const THEME_OPTIONS: Array<{ value: ThemeMode; label: string }> = [
 
 const THEME_VALUES = THEME_OPTIONS.map((t) => t.value);
 
-function normalizeThemeMode(value: unknown): ThemeMode | undefined {
-  if (typeof value !== "string") {
-    return undefined;
-  }
-
-  if (THEME_VALUES.includes(value as ThemeMode)) {
+function normalizeTheme(value: unknown): ThemeMode {
+  if (typeof value === "string" && THEME_VALUES.includes(value as ThemeMode)) {
     return value as ThemeMode;
   }
-
-  // Preserve intent for removed themes (e.g. legacy solarized-light/dark).
-  if (value.endsWith("-light")) {
-    return "light";
-  }
-
-  if (value.endsWith("-dark")) {
-    return "dark";
-  }
-
-  return undefined;
+  // Self-heal: unknown/legacy values become "system"
+  return "system";
 }
 
 interface ThemeContextValue {
+  /** The user's theme selection (system, light, dark, etc.) */
   theme: ThemeMode;
-  setTheme: React.Dispatch<React.SetStateAction<ThemeMode>>;
+  /** The resolved theme applied to the document (never "system") */
+  resolvedTheme: ResolvedThemeMode;
+  setTheme: (theme: ThemeMode) => void;
   toggleTheme: () => void;
   /** True if this provider has a forcedTheme - nested providers should not override */
   isForced: boolean;
@@ -51,7 +48,7 @@ interface ThemeContextValue {
 
 const ThemeContext = createContext<ThemeContextValue | null>(null);
 
-const THEME_COLORS: Record<ThemeMode, string> = {
+const THEME_COLORS: Record<ResolvedThemeMode, string> = {
   dark: "#1e1e1e",
   light: "#f5f6f8",
   "flexoki-light": "#fffcf0",
@@ -59,19 +56,18 @@ const THEME_COLORS: Record<ThemeMode, string> = {
 };
 
 /** Map theme mode to CSS color-scheme value */
-function getColorScheme(theme: ThemeMode): "light" | "dark" {
+function getColorScheme(theme: ResolvedThemeMode): "light" | "dark" {
   return theme === "light" || theme === "flexoki-light" ? "light" : "dark";
 }
 
-function resolveSystemTheme(): ThemeMode {
+function getSystemTheme(): ResolvedThemeMode {
   if (typeof window === "undefined" || !window.matchMedia) {
     return "dark";
   }
-
   return window.matchMedia("(prefers-color-scheme: light)").matches ? "light" : "dark";
 }
 
-function applyThemeToDocument(theme: ThemeMode) {
+function applyThemeToDocument(theme: ResolvedThemeMode) {
   if (typeof document === "undefined") {
     return;
   }
@@ -97,72 +93,96 @@ export function ThemeProvider({
   forcedTheme,
 }: {
   children: ReactNode;
-  forcedTheme?: ThemeMode;
+  forcedTheme?: ResolvedThemeMode;
 }) {
   // Check if we're nested inside a forced theme provider
   const parentContext = useContext(ThemeContext);
   const isNestedUnderForcedProvider = parentContext?.isForced ?? false;
 
-  const [persistedTheme, setTheme] = usePersistedState<ThemeMode>(
-    UI_THEME_KEY,
-    resolveSystemTheme(),
-    {
-      listener: true,
+  // Track OS theme for "system" preference
+  const [systemTheme, setSystemTheme] = useState<ResolvedThemeMode>(getSystemTheme);
+
+  // Persist the user's theme selection
+  const [rawTheme, setRawTheme] = usePersistedState<ThemeMode>(UI_THEME_KEY, "system", {
+    listener: true,
+  });
+
+  const theme = normalizeTheme(rawTheme);
+
+  // Self-heal invalid persisted values
+  useEffect(() => {
+    if (rawTheme !== theme) {
+      setRawTheme(theme);
     }
-  );
+  }, [rawTheme, theme, setRawTheme]);
+
+  // Subscribe to OS theme changes (only when authoritative provider)
+  useEffect(() => {
+    if (isNestedUnderForcedProvider || typeof window === "undefined" || !window.matchMedia) {
+      return;
+    }
+
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: light)");
+    const handleChange = () => {
+      setSystemTheme(mediaQuery.matches ? "light" : "dark");
+    };
+
+    mediaQuery.addEventListener("change", handleChange);
+    return () => mediaQuery.removeEventListener("change", handleChange);
+  }, [isNestedUnderForcedProvider]);
 
-  const parsedPersistedTheme = normalizeThemeMode(persistedTheme);
-  const normalizedPersistedTheme = parsedPersistedTheme ?? resolveSystemTheme();
+  // Resolve the actual theme to apply (never "system")
+  const resolved: ResolvedThemeMode =
+    theme === "system" ? systemTheme : (theme as ResolvedThemeMode);
 
-  // If nested under a forced provider, use parent's theme
-  // Otherwise, use forcedTheme (if provided) or persistedTheme
-  const theme =
+  // If nested under a forced provider, use parent's resolved theme
+  // Otherwise, use forcedTheme (if provided) or resolved preference
+  const resolvedTheme: ResolvedThemeMode =
     isNestedUnderForcedProvider && parentContext
-      ? parentContext.theme
-      : (forcedTheme ?? normalizedPersistedTheme);
+      ? parentContext.resolvedTheme
+      : (forcedTheme ?? resolved);
 
   const isForced = forcedTheme !== undefined || isNestedUnderForcedProvider;
 
-  // Only apply to document if we're the authoritative provider
+  // Apply theme to document (authoritative provider only)
   useLayoutEffect(() => {
-    if (isNestedUnderForcedProvider) {
-      return;
-    }
-
-    // Self-heal legacy or invalid themes persisted in localStorage.
-    if (forcedTheme === undefined && parsedPersistedTheme !== persistedTheme) {
-      setTheme(normalizedPersistedTheme);
+    if (!isNestedUnderForcedProvider) {
+      applyThemeToDocument(resolvedTheme);
     }
+  }, [resolvedTheme, isNestedUnderForcedProvider]);
+
+  const setTheme = useCallback(
+    (newTheme: ThemeMode) => {
+      if (!isNestedUnderForcedProvider) {
+        setRawTheme(newTheme);
+      }
+    },
+    [setRawTheme, isNestedUnderForcedProvider]
+  );
 
-    applyThemeToDocument(theme);
-  }, [
-    forcedTheme,
-    isNestedUnderForcedProvider,
-    normalizedPersistedTheme,
-    parsedPersistedTheme,
-    persistedTheme,
-    setTheme,
-    theme,
-  ]);
-
+  // Toggle between light and dark variants of the current theme family.
+  // This gives intuitive behavior: if it looks light, toggle to dark (and vice versa).
   const toggleTheme = useCallback(() => {
     if (!isNestedUnderForcedProvider) {
-      setTheme((current) => {
-        const currentIndex = THEME_VALUES.indexOf(current);
-        const nextIndex = (currentIndex + 1) % THEME_VALUES.length;
-        return THEME_VALUES[nextIndex];
-      });
+      const themeMap: Record<ResolvedThemeMode, ResolvedThemeMode> = {
+        light: "dark",
+        dark: "light",
+        "flexoki-light": "flexoki-dark",
+        "flexoki-dark": "flexoki-light",
+      };
+      setRawTheme(themeMap[resolvedTheme]);
     }
-  }, [setTheme, isNestedUnderForcedProvider]);
+  }, [resolvedTheme, setRawTheme, isNestedUnderForcedProvider]);
 
   const value = useMemo<ThemeContextValue>(
     () => ({
       theme,
+      resolvedTheme,
       setTheme,
       toggleTheme,
       isForced,
     }),
-    [setTheme, theme, toggleTheme, isForced]
+    [theme, resolvedTheme, setTheme, toggleTheme, isForced]
   );
 
   return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
diff --git a/src/browser/terminal-window.tsx b/src/browser/terminal-window.tsx
index f19f084662..4fb673e5f9 100644
--- a/src/browser/terminal-window.tsx
+++ b/src/browser/terminal-window.tsx
@@ -10,6 +10,7 @@ import ReactDOM from "react-dom/client";
 import { TerminalView } from "@/browser/components/TerminalView";
 import { APIProvider } from "@/browser/contexts/API";
 import { TerminalRouterProvider } from "@/browser/terminal/TerminalRouterContext";
+import { ThemeProvider } from "@/browser/contexts/ThemeContext";
 import "./styles/globals.css";
 
 // Get workspace ID from query parameter
@@ -30,10 +31,12 @@ if (!workspaceId || !sessionId) {
   // StrictMode intentionally double-mounts components in dev, which causes
   // race conditions with WebSocket connections and terminal lifecycle
   ReactDOM.createRoot(document.getElementById("root")!).render(
-    <APIProvider>
-      <TerminalRouterProvider>
-        <TerminalView workspaceId={workspaceId} sessionId={sessionId} visible={true} />
-      </TerminalRouterProvider>
-    </APIProvider>
+    <ThemeProvider>
+      <APIProvider>
+        <TerminalRouterProvider>
+          <TerminalView workspaceId={workspaceId} sessionId={sessionId} visible={true} />
+        </TerminalRouterProvider>
+      </APIProvider>
+    </ThemeProvider>
   );
 }
diff --git a/terminal.html b/terminal.html
index 40bce29ac8..4136788ce5 100644
--- a/terminal.html
+++ b/terminal.html
@@ -3,12 +3,16 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#1e1e1e" />
     <style>
       body {
         margin: 0;
         padding: 0;
         overflow: hidden;
-        background: #1e1e1e;
+        background: var(--color-background, #1e1e1e);
+      }
+      :root[data-theme="light"] body {
+        background: #f5f6f8;
       }
       #root {
         height: 100vh;
@@ -16,6 +20,59 @@
         overflow: hidden;
       }
     </style>
+    <script>
+      (function () {
+        const THEME_KEY = "uiTheme";
+        const VALID_PREFERENCES = new Set([
+          "system",
+          "light",
+          "dark",
+          "flexoki-light",
+          "flexoki-dark",
+        ]);
+        const THEME_COLORS = {
+          dark: "#1e1e1e",
+          light: "#f5f6f8",
+          "flexoki-light": "#fffcf0",
+          "flexoki-dark": "#100f0f",
+        };
+
+        function getColorScheme(theme) {
+          return theme === "light" || theme === "flexoki-light" ? "light" : "dark";
+        }
+
+        try {
+          const stored = window.localStorage.getItem(THEME_KEY);
+          let parsed = null;
+          if (stored) {
+            try {
+              parsed = JSON.parse(stored);
+            } catch {
+              parsed = stored;
+            }
+          }
+          const preference =
+            typeof parsed === "string" && VALID_PREFERENCES.has(parsed) ? parsed : "system";
+          const systemTheme =
+            window.matchMedia && window.matchMedia("(prefers-color-scheme: light)").matches
+              ? "light"
+              : "dark";
+          const theme = preference === "system" ? systemTheme : preference;
+          const colorScheme = getColorScheme(theme);
+
+          document.documentElement.dataset.theme = theme;
+          document.documentElement.style.colorScheme = colorScheme;
+
+          const metaThemeColor = document.querySelector('meta[name="theme-color"]');
+          if (metaThemeColor) {
+            metaThemeColor.setAttribute("content", THEME_COLORS[theme] ?? "#1e1e1e");
+          }
+        } catch {
+          document.documentElement.dataset.theme = "dark";
+          document.documentElement.style.colorScheme = "dark";
+        }
+      })();
+    </script>
   </head>
   <body>
     <div id="root"></div>