diff --git a/README.md b/README.md
index 1ab602e..a359b85 100644
--- a/README.md
+++ b/README.md
@@ -303,6 +303,23 @@ PROMPT_THEME_DIR = ~/.mythemes   # optional: custom search directory
 Built-in themes: `default`, `dark`, `light`, `solarized`, `solarized-light`,
 `monokai`, `monochrome`, `abyss`, `plasma`, `adwaita`.
 
+**Runtime theme switching (`set_theme`):**
+
+```bash
+set_theme --list            # list available themes
+set_theme dark              # apply theme for current shell session
+set_theme --preview dark    # preview theme colors without applying
+set_theme --save            # save currently active theme to config
+set_theme --save dark       # apply and save the given theme
+```
+
+`set_theme --save` writes `PROMPT_THEME` in `[prompt]` to:
+
+- `~/.profile.conf` when present
+- otherwise `profile.conf` in the profile installation directory
+
+`--preview` and `--save` are mutually exclusive.
+
 **Overriding individual prompt colour slots:**
 
 ```ini