per-monitor wallpapers

docs/IPC.md

@@ -238,23 +238,90 @@ qs -c dms ipc call inhibit enable
 
 ## Target: `wallpaper`
 
-Wallpaper management and retrieval.
+Wallpaper management and retrieval with support for per-monitor configurations.
 
-### Functions
+### Legacy Functions (Global Wallpaper Mode)
 
 **`get`**
 - Get current wallpaper path
-- Returns: Full path to current wallpaper file
+- Returns: Full path to current wallpaper file, or error if per-monitor mode is enabled
 
 **`set <path>`**
 - Set wallpaper to specified path
 - Parameters: `path` - Absolute or relative path to image file
-- Returns: Confirmation message or error
+- Returns: Confirmation message or error if per-monitor mode is enabled
+
+**`clear`**
+- Clear all wallpapers and disable per-monitor mode
+- Returns: Success confirmation
+
+**`next`**
+- Cycle to next wallpaper in the same directory
+- Returns: Success confirmation or error if per-monitor mode is enabled
+
+**`prev`**
+- Cycle to previous wallpaper in the same directory
+- Returns: Success confirmation or error if per-monitor mode is enabled
+
+### Per-Monitor Functions
+
+**`getFor <screenName>`**
+- Get wallpaper path for specific monitor
+- Parameters: `screenName` - Monitor name (e.g., "DP-2", "eDP-1")
+- Returns: Full path to wallpaper file for the specified monitor
+
+**`setFor <screenName> <path>`**
+- Set wallpaper for specific monitor (automatically enables per-monitor mode)
+- Parameters: 
+  - `screenName` - Monitor name (e.g., "DP-2", "eDP-1")
+  - `path` - Absolute or relative path to image file
+- Returns: Success confirmation with monitor and path info
+
+**`nextFor <screenName>`**
+- Cycle to next wallpaper for specific monitor
+- Parameters: `screenName` - Monitor name (e.g., "DP-2", "eDP-1")
+- Returns: Success confirmation
+
+**`prevFor <screenName>`**
+- Cycle to previous wallpaper for specific monitor
+- Parameters: `screenName` - Monitor name (e.g., "DP-2", "eDP-1")
+- Returns: Success confirmation
 
 ### Examples
+
+**Global wallpaper mode:**
 ```bash
 qs -c dms ipc call wallpaper get
 qs -c dms ipc call wallpaper set /path/to/image.jpg
+qs -c dms ipc call wallpaper next
+qs -c dms ipc call wallpaper clear
+```
+
+**Per-monitor wallpaper mode:**
+```bash
+# Set different wallpapers for each monitor
+qs -c dms ipc call wallpaper setFor DP-2 /path/to/image1.jpg
+qs -c dms ipc call wallpaper setFor eDP-1 /path/to/image2.jpg
+
+# Get wallpaper for specific monitor
+qs -c dms ipc call wallpaper getFor DP-2
+
+# Cycle wallpapers for specific monitor
+qs -c dms ipc call wallpaper nextFor eDP-1
+qs -c dms ipc call wallpaper prevFor DP-2
+
+# Clear all wallpapers and return to global mode
+qs -c dms ipc call wallpaper clear
+```
+
+**Error handling:**
+When per-monitor mode is enabled, legacy functions will return helpful error messages:
+```bash
+qs -c dms ipc call wallpaper get
+# Returns: "ERROR: Per-monitor mode enabled. Use getFor(screenName) instead."
+
+qs -c dms ipc call wallpaper set /path/to/image.jpg
+# Returns: "ERROR: Per-monitor mode enabled. Use setFor(screenName, path) instead."
 ```
 
 ## Target: `profile`