From d118c02e75755b31dc4ecfbb66617f077706054d Mon Sep 17 00:00:00 2001
From: AramJonghu <aramjonghu@tutamail.com>
Date: Sat, 23 May 2026 17:52:06 +0200
Subject: [PATCH] README: document scheme CLI and shell subcommands

---
 README.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 49 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 7f0f323..a38843c 100644
--- a/README.md
+++ b/README.md
@@ -216,12 +216,56 @@ Action-driven flows (`>` prefix by default) include calculator, wallpaper picker
 
 `zshell-cli` provides these subcommands:
 
-- `shell` - start/kill/log/IPC calls
-- `screenshot` - open area picker (`start`, `start-freeze`)
-- `wallpaper` - set wallpaper + generate lockscreen blur image
-- `scheme` - generate and apply dynamic/preset color schemes
+### `shell` — daemon management
 
-Note: `cli/src/zshell/subcommands/scheme.py` uses Jinja2 templating for `~/.config/zshell/templates` rendering.
+| Command | Description |
+|---------|-------------|
+| `start` | Start the shell daemon (pass `--no-daemon` to run in foreground) |
+| `kill`  | Kill the running shell daemon |
+| `restart` | Kill then restart the daemon |
+| `lock`  | Lock the session via IPC |
+| `show`  | Show the shell window via IPC |
+| `log`   | Print daemon logs |
+
+### `scheme` — color scheme generation
+
+```
+Usage: zshell-cli scheme generate [--preset <scheme>:<variant>] [--accent <accent>]
+                                   [--mode <dark|light>] [--image-path <path>]
+
+Generate a color scheme from a wallpaper image (Material You) or from
+a built-in preset.
+
+Preset selection:
+  --preset <scheme>:<variant>    Pick a built-in scheme (e.g. catppuccin:mocha)
+  --accent <name>                Accent color for schemes that support it
+                                   (catppuccin accepts: blue, green, mauve,
+                                   peach, pink, red, rosewater, etc.)
+  --mode <dark|light>            Override variant mode
+
+  If variant has both dark and light modes, the mode is auto-detected from
+  the current system or config preference.
+
+  List all available presets:
+    zshell-cli scheme list-presets         # human-readable
+    zshell-cli scheme list-presets --json  # machine-readable (QML UI)
+
+  Examples:
+    zshell-cli scheme generate --preset gruvbox:medium
+    zshell-cli scheme generate --preset catppuccin:mocha --accent green
+    zshell-cli scheme generate --preset everforest:medium --mode light
+```
+
+Note: Template rendering (Jinja2) applies generated colors to `~/.config/zshell/templates/*`.
+
+### `screenshot` — area picker
+
+- `start` — open interactive area picker
+- `start-freeze` — freeze screen then pick
+
+### `wallpaper` — wallpaper management
+
+- Set wallpaper and generate lockscreen blur background
 
 ## Greeter