diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5a7c4d73..d7bf35f3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,18 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **Custom theme registry** — scan `{appSupport}/themes/` for `querya.theme.v1` and VS Code JSON/JSONC; **Theme** picker with search, preview, refresh, and **Open themes folder** (Preferences → Appearance).
+- **Built-in bundled themes** — e.g. **Querya Cyberpunk Neon** from `assets/themes/` (no manual install).
+- **Theme import** — **Import theme…** copies into the user themes directory with hash/id deduplication; selection persists across restarts.
+- **Startup safety** — missing or broken selected theme falls back to Querya Dark with a Preferences error; settings are not auto-deleted.
+- **Window chrome** — title bar and window controls follow active `QueryaThemeScope` workbench tokens.
+- **Docs / QA** — [theme-custom-json.md](docs/theme-custom-json.md), updated [theme-import.md](docs/theme-import.md), custom-theme section in [release-checklist.md](docs/release-checklist.md).
+- **Tests** — registry/parser/controller coverage, 60-theme picker performance guard, end-to-end import flow (`theme_import_flow_test.dart`).
+
 ## [0.4.1] - 2026-06-13
 
 Performance and UX release ([#93](https://github.com/QueryaHub/Querya-Desktop/issues/93)). Git tag **`0.4.1`**.
diff --git a/docs/release-checklist.md b/docs/release-checklist.md
index 63db411b..6885ee2a 100644
--- a/docs/release-checklist.md
+++ b/docs/release-checklist.md
@@ -10,6 +10,20 @@ Use this before tagging or running the **Release** workflow.
 - [ ] **Connection → New Database Connection** from the menu saves and shows in the tree.
 - [ ] **Driver Manager** shows only built-in drivers (no misleading JDBC requirement).
 
+## Custom themes (manual QA)
+
+Use **Preferences → Appearance** unless noted. Fixtures for copy/import tests live under
+`test/fixtures/themes/`; bundled built-in sample: **Querya Cyberpunk Neon** in the theme picker.
+
+- [ ] **Import valid custom dark** — import `test/fixtures/themes/querya_custom_dark.json` (or copy to themes folder + **Refresh themes**). Theme appears in picker; UI uses custom primary (`#38BDF8`).
+- [ ] **Import valid custom light** — import `test/fixtures/themes/querya_custom_light.json`. App switches to light brightness; readable text on cards and sidebar.
+- [ ] **Import VS Code JSONC** — import `test/fixtures/themes/querya_custom_jsonc.jsonc` or `themes/samples/cyberpunk-neon.jsonc`. Parser accepts comments/trailing commas; theme applies without crash.
+- [ ] **Picker with many themes** — install 50+ themes (copy fixtures with unique ids, or duplicate renamed files) → open theme picker: no overflow, list scrolls, search filters rows.
+- [ ] **Restart persists selection** — select a registry theme (not only Querya Dark/Light), quit and relaunch: same theme active, no error in Preferences.
+- [ ] **Missing file fallback** — with a registry theme selected, delete its file from `{appSupport}/themes/`, restart: app starts on **Querya Dark**, Preferences shows *Selected theme failed to load. Using Querya Dark.*; saved selection id remains until user picks another theme.
+- [ ] **Title bar / window controls** — switch Querya Dark, Querya Light, Cyberpunk Neon, and a custom theme: title bar background and minimize/maximize/close hover colors track the active theme.
+- [ ] **SQL / JSON syntax** — open SQL editor with a theme that defines `tokenColors` (e.g. cyberpunk sample): comments, keywords, and strings use distinct colors; changing theme updates highlighting after editor refresh.
+
 ## Automated
 
 - [ ] `flutter analyze` — clean (on Linux, if the analyzer crashes with **Too many open files**, try `ulimit -n 8192`; see [CONTRIBUTING.md](../CONTRIBUTING.md)).
diff --git a/docs/theme-custom-json.md b/docs/theme-custom-json.md
index b77f3991..924632e5 100644
--- a/docs/theme-custom-json.md
+++ b/docs/theme-custom-json.md
@@ -283,6 +283,17 @@ Invalid files are skipped (logged in debug builds). Required fields: `schema`, `
 Built-in bundled themes (under `assets/themes/`) ship with the app and do not require
 manual installation.
 
+## Troubleshooting
+
+| Symptom | Likely cause | What to do |
+|---------|----------------|------------|
+| Theme file not in picker | Invalid JSON, missing required fields, or wrong extension | Fix `schema`, `id`, `name`, `type`, `shadcn_colors`, `editor_colors`; use `.json` or `.jsonc`; click **Refresh themes**. In debug builds, skipped files log to the console. |
+| Import dialog reports an error | Parse failure or empty VS Code `colors` | Open the file in an editor; validate JSON/JSONC; for VS Code format ensure a non-empty `colors` object. |
+| *Selected theme failed to load. Using Querya Dark.* | Persisted theme id points to a missing or broken file | Restore the file under `themes/`, or pick another theme in Preferences. Settings are kept so you can fix the file and **Refresh themes**. |
+| Colors look wrong or default | Invalid hex for a key | Invalid optional colors are **skipped** (preset fallback used). Check `#RRGGBB` / `#RRGGBBAA` formats in [Color string formats](#color-string-formats). |
+| Duplicate theme names in picker | Same `id` with different content imported twice | Registry suffixes ids (`my-theme-2`). Rename files or ids to avoid confusion. |
+| Dropped file not visible | No folder watcher | Use **Refresh themes** after copying into `themes/` (restart not required). |
+
 ## Related docs
 
 - [Theme import (VS Code)](theme-import.md)
diff --git a/docs/theme-import.md b/docs/theme-import.md
index 675a25d0..d61c36f7 100644
--- a/docs/theme-import.md
+++ b/docs/theme-import.md
@@ -96,6 +96,18 @@ duplicate ids get a numeric suffix). Themes picked up from disk use the file bas
 Legacy single-file import (`themes/imported.json` under older builds) is still migrated
 into the registry on load when present.
 
+## Troubleshooting
+
+| Symptom | Likely cause | What to do |
+|---------|----------------|------------|
+| Theme missing from picker after copy | Scan not run or file skipped as invalid | Click **Refresh themes**; verify `.json`/`.jsonc` and valid root object. Debug builds log skipped paths. |
+| Import fails immediately | Unsupported file or empty `colors` (VS Code) | Use VS Code theme JSON with a `colors` section, or Querya custom JSON per [theme-custom-json.md](theme-custom-json.md). |
+| JSONC import fails | Trailing commas/comments in strict JSON tool | Querya strips JSONC on import; ensure the file still has a single root object after stripping. |
+| *Selected theme failed to load. Using Querya Dark.* on startup | Selected file deleted or corrupted | Replace or remove the file; select a working theme. See [theme-custom-json.md](theme-custom-json.md#troubleshooting). |
+| Picker slow with many themes | Large registry list | Expected: picker uses `ListView.builder` and search; report regressions if opening Preferences lags with 50+ themes. |
+| SQL colors unchanged | Theme has no `tokenColors` | Add VS Code-style `tokenColors` to the file; only imported/registry themes with rules affect syntax highlighting. |
+| Title bar wrong color | Window chrome not synced | Switch theme again; file an issue if title bar stays on preset colors with a custom registry theme active. |
+
 ## User overrides (#45)
 
 User customizations are stored as VS Code keys → hex strings in