docs(themes): add authoring guide for TOML theme system

docs/guide_themes.md

@@ -0,0 +1,52 @@
+# Themes — Authoring Guide
+
+## File Layout
+
+- Global themes: `themes.toml` (single multi-theme file) OR `themes/<name>.toml` (one file per theme)
+- Project-specific overrides: `<project>/project_themes.toml`
+
+Both layouts are scanned and merged; project themes with the same name as a global theme override it.
+
+Override the global path via the `SLOP_GLOBAL_THEMES` env var.
+
+## Schema
+
+```toml
+# human-readable label
+description = "Solarized Dark by Ethan Schoonover"
+
+# one of: dark | light | mariana | retro_blue
+# selects which built-in imgui_color_text_edit palette to apply
+syntax_palette = "dark"
+
+[colors]
+# RGB triples, 0-255
+window_bg    = [  0,  43,  54]
+text         = [147, 161, 161]
+button_hovered = [ 38, 139, 210]
+# ... any imgui.Col_ key is accepted
+```
+
+`[colors]` is required. Missing required section is a hard error (logged to stderr, theme skipped).
+
+## Available Color Keys
+
+All keys are imgui `Col_` enum members in snake_case. The loader does best-effort mapping; unknown keys are silently ignored. Common ones: `window_bg`, `child_bg`, `popup_bg`, `border`, `frame_bg`, `title_bg`, `menu_bar_bg`, `scrollbar_bg`, `button`, `header`, `separator`, `tab`, `text`, `text_disabled`, `check_mark`, `slider_grab`, `table_header_bg`.
+
+## Syntax Palette Mapping
+
+`imgui-bundle` ships four built-in `imgui_color_text_edit` palettes and exposes no API to define new ones. We pick the closest match per theme:
+
+| UI Theme | Syntax Palette |
+|---|---|
+| Solarized Dark | `dark` |
+| Solarized Light | `light` |
+| Gruvbox Dark | `retro_blue` |
+| Moss | `mariana` |
+| (anything else) | `dark` |
+
+You can override the mapping per theme by setting the `syntax_palette` field in the TOML.
+
+## Hot Reload
+
+Theme TOMLs are loaded once at module init. To pick up a new file, call `theme.load_themes_from_disk()` (or restart the app).