@@ -77,6 +77,8 @@ create the tools it needs based on how you actually work.
   Simplified Chinese and Spanish are built in. Add a language ThinkRail doesn't ship yet by dropping a
   translated `en.json` into `~/.thinkrail/locales` — it applies as you save. Agent replies and tool
   output stay as the agent wrote them.
+- **Your themes.** Settings → Appearance ships dark, light, minimal and high-contrast themes. Make your own
+  by copying a bundled `*.theme.json`, changing its id and colors, and saving it to `~/.thinkrail/themes`.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset=".github/readme-assets/specs-dark.png">
 
@@ -170,7 +170,7 @@ change. `dist/` therefore has no profiler timers (`actualStartTime` is absent fr
   the runtime graph is acyclic), `lib` (plain-HTTP-safe random page identity)
 - `components` → `lib` (`ErrorBoundary`'s `shallowEqualArrays` for its reset keys) and `constants` (`RunningIcon` draws the shared brand monogram) — both leaves, so any region can still wrap in it; presentational controls consume `ui`
 - `lib` → `themes` (the lazy highlighter uses the one generic CSS-variable Shiki registration), React (the phone-viewport hook only), and `contracts` (types only, e.g. the MCP state vocabulary's `McpServerState`)
-- `themes` → `constants` (the branding storage prefix scopes the first-paint hint), `clientPreferences` (native-stable hint storage)
+- `themes` → `constants` (the branding storage prefix scopes the first-paint hint and the user-theme cache), `clientPreferences` (native-stable hint storage); `transport` hydrates the store's user-theme snapshot and `shell`'s theme effect installs it
 - `i18n` → `store`, `contracts` (types), `@thinkrail/locales`; `transport` hydrates the store's local-language snapshot, `main.tsx`'s `App` mounts `useLocaleSync` once and `panels` renders the Language page from its pure derivations
 - **Any module may → `@thinkrail/locales/react`** (`useT`, `<T>`, `currentLocale`) for its UI text — the one cross-cutting edge besides `lib`; user-facing text is never a literal ([[architecture]] Decision 23)
 - leaves (`clientPreferences`, `constants`, `utils`, `styles`) → none internal
@@ -278,6 +278,8 @@ themselves.
   only nullable color slots (`null` retains the consumer default). A build-time glob validates the set at
   bootstrap (our files — a bad one fails loudly), so adding a theme changes only that file — never
   contracts, a label map, CSS selectors, editor imports, tests, or specs — and appears after a rebuild.
+  A user adds a theme the same way at runtime: the same manifest in `~/.thinkrail/themes`, served by
+  [[submodule-server-themes]] and validated here, where an unusable file is reported, not fatal.
   Manifests are self-contained (no inheritance), contain canonical color data only, and cannot alter
   layout/type/motion or inject CSS/code. The engine derives repetitive tints/effects and atomically
   writes the mapped custom properties before changing `[data-theme]`; `@theme inline` keeps every utility
 
@@ -12,15 +12,15 @@ import { initFilesTreePersistence } from "./panels/filesTreeState";
 import { initProjectExpansionPersistence } from "./panels/projectExpansion";
 import { AppResourceHost } from "./shell/AppResourceHost";
 import { Shell } from "./shell/Shell";
-import { applyThemePreference, initializeBundledThemes, readThemeHint } from "./themes";
+import { applyThemePreference, initializeThemes, readThemeHint } from "./themes";
 import {
 	clientErrorReport,
 	initTransport,
 	installClientErrorReporting,
 	reportClientError,
 } from "./transport";
 
-initializeBundledThemes();
+initializeThemes();
 applyThemePreference(readThemeHint());
 initTransport();
 installClientErrorReporting();
 
@@ -24,18 +24,22 @@ import {
 } from "@thinkrail/ui/dropdown-menu";
 import { cn } from "@thinkrail/ui/utils";
 import { type ReactNode, useState, useSyncExternalStore } from "react";
+import { copyText } from "@/lib";
 import { toast, useAppStore } from "@/store";
 import {
 	deriveSystemThemePair,
 	getThemes,
+	getUserThemeIssues,
 	onSystemAppearanceChange,
+	onThemesChange,
 	readSystemAppearance,
 	resolveTheme,
 	resolveThemePreference,
 	type ThemeDescriptor,
 	type ThemeResolution,
 } from "@/themes";
 import { errorText, getTransport } from "@/transport";
+import { CustomThemesGroup } from "./CustomThemesSettings";
 import { LineWidthControl } from "./LineWidthSettings";
 import { SegmentedControl, type SegmentedControlOption } from "./SegmentedControl";
 import { SettingsGroup, SettingsPageContainer } from "./SettingsGroup";
@@ -56,7 +60,9 @@ const BUNDLED_THEME_LABELS: Readonly<Record<string, MessageKey>> = {
 };
 
 function themeLabel(t: Translator, theme: Pick<ThemeDescriptor, "id" | "label">): string {
-	const key = BUNDLED_THEME_LABELS[theme.id];
+	const key = Object.hasOwn(BUNDLED_THEME_LABELS, theme.id)
+		? BUNDLED_THEME_LABELS[theme.id]
+		: undefined;
 	return key ? t(key) : theme.label;
 }
 
@@ -237,8 +243,11 @@ export function AppearanceSettings() {
 	const [pending, setPending] = useState(false);
 	const [expanded, setExpanded] = useState(false);
 	const systemAppearance = useSyncExternalStore(onSystemAppearanceChange, readSystemAppearance);
+	const themes = useSyncExternalStore(onThemesChange, getThemes);
+	const userThemeIssues = useSyncExternalStore(onThemesChange, getUserThemeIssues);
+	const userThemes = useAppStore((state) => state.userThemes);
+	const appVersion = useAppStore((state) => state.hostAppVersion);
 
-	const themes = getThemes();
 	const systemSupported = (protocolVersion ?? 0) >= THEME_SYSTEM_PROTOCOL_VERSION;
 	const activeTheme = resolveTheme(theme);
 	const fixedResolution = resolveThemePreference({ theme, themeMode: "fixed" });
@@ -350,6 +359,16 @@ export function AppearanceSettings() {
 		if (next.light !== pair.light || next.dark !== pair.dark) update({ systemThemePair: next });
 	};
 
+	const copyThemesFolder = async (folder: string) => {
+		if (await copyText(folder)) toast.success(t("settings.language.folderCopied"));
+	};
+
+	const revealThemesFolder = () => {
+		getTransport()
+			.request("themes.reveal", {})
+			.catch((error) => toast.error(errorText(error, t("settings.language.openFolderFailed"))));
+	};
+
 	const fallbacks = systemMode
 		? [
 				{ appearance: "light", resolution: lightResolution },
@@ -484,6 +503,13 @@ export function AppearanceSettings() {
 					}
 				/>
 			</SettingsGroup>
+			<CustomThemesGroup
+				snapshot={userThemes}
+				issues={userThemeIssues}
+				appVersion={appVersion}
+				onCopyFolder={(folder) => void copyThemesFolder(folder)}
+				onRevealFolder={revealThemesFolder}
+			/>
 			<SettingsGroup title={t("settings.appearance.editorGroup")}>
 				<LineWidthControl kind="file" />
 			</SettingsGroup>
 
@@ -0,0 +1,34 @@
+import { expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import { CustomThemesGroup } from "./CustomThemesSettings";
+
+test("shows the theme folder, the example link, and one notice per broken file", () => {
+	const markup = renderToStaticMarkup(
+		<CustomThemesGroup
+			snapshot={{ dir: "/home/me/.thinkrail/themes", files: [] }}
+			issues={[{ fileName: "copy.theme.json", error: "duplicate-id", detail: "ocean" }]}
+			appVersion="1.2.3"
+			onCopyFolder={() => {}}
+			onRevealFolder={() => {}}
+		/>,
+	);
+	expect(markup).toContain("/home/me/.thinkrail/themes");
+	expect(markup).toContain('data-testid="custom-themes-open-folder"');
+	expect(markup).toContain("/blob/v1.2.3/apps/web/src/themes/bundled/dark.theme.json");
+	expect(markup).toContain('data-testid="custom-theme-issue-copy.theme.json"');
+	expect(markup).toContain("Another theme file already uses this id");
+});
+
+test("renders nothing when the host cannot serve theme files", () => {
+	expect(
+		renderToStaticMarkup(
+			<CustomThemesGroup
+				snapshot={null}
+				issues={[]}
+				appVersion={null}
+				onCopyFolder={() => {}}
+				onRevealFolder={() => {}}
+			/>,
+		),
+	).toBe("");
+});
@@ -0,0 +1,122 @@
+import { RiFileCopyLine as Copy, RiFolderOpenLine as FolderOpen } from "@remixicon/react";
+import type { UserThemesSnapshot } from "@thinkrail/contracts";
+import { T, type Translator, useT } from "@thinkrail/locales/react";
+import { Button } from "@thinkrail/ui/button";
+import type { ReactNode } from "react";
+import type { UserThemeIssue } from "@/themes";
+import { repoSourceUrl } from "./LanguageSettings";
+import { SettingsGroup } from "./SettingsGroup";
+import { SettingsNotice } from "./SettingsNotice";
+import { SettingsRow } from "./SettingsRow";
+
+const EXAMPLE_THEME_PATH = "apps/web/src/themes/bundled/dark.theme.json";
+
+function issueLabel(t: Translator, issue: UserThemeIssue): string {
+	switch (issue.error) {
+		case "invalid-json":
+			return t("settings.appearance.custom.error.invalidJson");
+		case "invalid-theme":
+			return t("settings.appearance.custom.error.invalidTheme");
+		case "id-too-long":
+			return t("settings.appearance.custom.error.idTooLong");
+		case "duplicate-id":
+			return t("settings.appearance.custom.error.duplicateId");
+		case "too-large":
+			return t("settings.appearance.custom.error.tooLarge");
+		case "too-many":
+			return t("settings.appearance.custom.error.tooMany");
+		case "unreadable":
+			return t("settings.appearance.custom.error.unreadable");
+	}
+}
+
+function ExampleLink({ href, children }: { href: string; children?: ReactNode }) {
+	return (
+		<a
+			data-testid="custom-themes-example"
+			href={href}
+			target="_blank"
+			rel="noopener noreferrer"
+			className="text-primary underline underline-offset-2 hover:opacity-80"
+		>
+			{children}
+		</a>
+	);
+}
+
+export interface CustomThemesGroupProps {
+	snapshot: UserThemesSnapshot | null;
+	issues: readonly UserThemeIssue[];
+	appVersion: string | null;
+	onCopyFolder: (folder: string) => void;
+	onRevealFolder: () => void;
+}
+
+export function CustomThemesGroup({
+	snapshot,
+	issues,
+	appVersion,
+	onCopyFolder,
+	onRevealFolder,
+}: CustomThemesGroupProps) {
+	const t = useT();
+	if (!snapshot) return null;
+	const folder = snapshot.dir;
+	return (
+		<SettingsGroup title={t("settings.appearance.custom.title")} testId="custom-themes">
+			<p className="py-12 tr-text-metadata text-text-muted">
+				<T
+					i18nKey="settings.appearance.custom.steps"
+					components={[
+						<ExampleLink key="example" href={repoSourceUrl(appVersion, EXAMPLE_THEME_PATH)} />,
+					]}
+				/>
+			</p>
+			<SettingsRow
+				label={t("settings.appearance.custom.folder")}
+				description={
+					<code data-testid="custom-themes-folder-path" className="tr-code-text break-all">
+						{folder}
+					</code>
+				}
+				noBorder={issues.length === 0}
+				control={
+					<div className="flex gap-8">
+						<Button variant="outline" size="sm" onClick={() => onCopyFolder(folder)}>
+							<Copy className="size-14" />
+							{t("settings.language.folder.copy")}
+						</Button>
+						<Button
+							variant="outline"
+							size="sm"
+							data-testid="custom-themes-open-folder"
+							onClick={onRevealFolder}
+						>
+							<FolderOpen className="size-14" />
+							{t("settings.language.folder.open")}
+						</Button>
+					</div>
+				}
+			/>
+			{issues.length > 0 ? (
+				<div className="flex flex-col gap-4 py-12">
+					{issues.map((issue) => (
+						<SettingsNotice
+							key={issue.fileName}
+							variant="warning"
+							testId={`custom-theme-issue-${issue.fileName}`}
+						>
+							<span className="flex flex-col gap-4">
+								<span className="tr-code-text">{issue.fileName}</span>
+								<span>{issueLabel(t, issue)}</span>
+								{issue.detail ? (
+									<span className="break-words text-text-muted">{issue.detail}</span>
+								) : null}
+							</span>
+						</SettingsNotice>
+					))}
+				</div>
+			) : null}
+		</SettingsGroup>
+	);
+}
@@ -25,10 +25,14 @@ import { SettingsRow } from "./SettingsRow";
 const REPO_URL = "https://github.com/JetBrains/thinkrail";
 export const CONTRIBUTE_TRANSLATIONS_URL = `${REPO_URL}/blob/main/CONTRIBUTING.md#translations`;
 
-export function englishSourceUrl(appVersion: string | null): string {
+export function repoSourceUrl(appVersion: string | null, path: string): string {
 	const released =
 		appVersion && /^\d+\.\d+\.\d+(?:-[\w.]+)?$/.test(appVersion) && appVersion !== "0.0.0";
-	return `${REPO_URL}/blob/${released ? `v${appVersion}` : "main"}/packages/locales/en.json`;
+	return `${REPO_URL}/blob/${released ? `v${appVersion}` : "main"}/${path}`;
+}
+
+export function englishSourceUrl(appVersion: string | null): string {
+	return repoSourceUrl(appVersion, "packages/locales/en.json");
 }
 
 function InlineLink({ href, children }: { href: string; children?: ReactNode }) {
 
@@ -737,7 +737,12 @@ a project picker, the prompt hero, and the reused
   disclosed by a warning notice under the mode control — outside the disclosure, so it is always visible —
   naming the effective same-appearance fallback, and is never silently written back. The panel never owns
   a theme list, media-query logic, pair derivation, or fallback — all come from `themes`; it derives only
-  the family/contrast counterpart the two controls move to. An **Editor** group hosts the file
+  the family/contrast counterpart the two controls move to. A **Custom themes** group
+  (`CustomThemesSettings.tsx`, props-driven like `LanguagePage`, hidden below
+  `USER_THEMES_PROTOCOL_VERSION`) gives the copy-a-bundled-file steps with a version-pinned link to
+  `dark.theme.json`, the `<dataDir>/themes` folder with **Copy path** / **Open folder** (`themes.reveal`),
+  and one warning notice per unusable file (`themes`' issue list). The page reads the catalog and issues
+  through `onThemesChange`, so a dropped file appears in the lists without reopening. An **Editor** group hosts the file
   `LineWidthControl`); **`LineWidthControl({kind})`** (`LineWidthSettings.tsx`, no page of its own — the
   `chat` control sits in Chat, the `file` one in Appearance → Editor — a 40–240 integer **Line width** field
   on the auto-save input pattern plus an independent host-synchronized **Fit to pane** switch
 
@@ -23,11 +23,18 @@ import {
 } from "../store";
 import {
 	applyThemePreference,
+	clearUserThemes,
+	installUserThemes,
 	onSystemAppearanceChange,
 	readThemeHint,
 	writeThemeHint,
 } from "../themes";
-import { type ConnectionStatus, runHostUpdate, supportsHostUpdateRun } from "../transport";
+import {
+	type ConnectionStatus,
+	runHostUpdate,
+	supportsHostUpdateRun,
+	supportsUserThemes,
+} from "../transport";
 import { UpdateInstallSurfaces, UpdateReadyButton, UpdateSettings, useUpdates } from "../updates";
 import { AppShortcuts } from "./AppShortcuts";
 import { BrandLogo } from "./BrandLogo";
@@ -90,7 +97,11 @@ export function Shell() {
 	const theme = useAppStore((s) => s.theme);
 	const themeMode = useAppStore((s) => s.themeMode);
 	const systemThemePair = useAppStore((s) => s.systemThemePair);
+	const userThemes = useAppStore((s) => s.userThemes);
+	const userThemesUnsupported = welcomeGeneration > 0 && !supportsUserThemes(protocolVersion);
 	useEffect(() => {
+		if (userThemes) installUserThemes(userThemes.files);
+		else if (userThemesUnsupported) clearUserThemes();
 		const preference =
 			welcomeGeneration === 0
 				? themeHint
@@ -99,7 +110,15 @@ export function Shell() {
 		apply();
 		if (welcomeGeneration > 0) writeThemeHint(preference);
 		return preference.themeMode === "system" ? onSystemAppearanceChange(apply) : undefined;
-	}, [themeHint, welcomeGeneration, theme, themeMode, systemThemePair]);
+	}, [
+		themeHint,
+		welcomeGeneration,
+		theme,
+		themeMode,
+		systemThemePair,
+		userThemes,
+		userThemesUnsupported,
+	]);
 	useGlobalHotkeys({
 		onProjects: hasActiveWorkspace
 			? () => {
 
@@ -35,6 +35,7 @@ import type {
 	ThinkingLevel,
 	TurnChangeSet,
 	UserMessage,
+	UserThemesSnapshot,
 	WireModel,
 	Workspace,
 	WorkspaceFsChangedPayload,
@@ -1064,6 +1065,8 @@ interface AppState {
 	locale: string;
 	localLocales: LocalLocalesSnapshot | null;
 	installLocalLocales: (snapshot: LocalLocalesSnapshot | null) => void;
+	userThemes: UserThemesSnapshot | null;
+	installUserThemes: (snapshot: UserThemesSnapshot | null) => void;
 	customLayoutPresets: LayoutPreset[];
 	toasts: Toast[];
 	setStatus: (status: ConnectionStatus) => void;
@@ -2320,6 +2323,8 @@ export const useAppStore = create<AppState>((set, get) => ({
 	locale: DEFAULT_CONFIG.locale,
 	localLocales: null,
 	installLocalLocales: (snapshot) => set({ localLocales: snapshot }),
+	userThemes: null,
+	installUserThemes: (snapshot) => set({ userThemes: snapshot }),
 	toasts: [],
 	resourceSnapshots: {},
 	resourceRevision: 0,