Update documentation for v1.4.0 cache system

- Add --cache-size flag documentation with examples
- Document cache IPC commands (cache-list, cache-stats, unload, listactive)
- Remove outdated 'Future Commands' section
- Add 'Instant Switching' to key features
- Add cache usage example to quick-start guide
- Add internal dev docs to gitignore

Author: Nomadcxx

.gitignore

@@ -74,9 +74,13 @@ opencode.json
 gslapper-*.tar.gz
 gslapper-*.tar.gz.opencode.json
 
-# Development documentation
+# Development documentation (internal research/notes - not for public docs)
 docs/plans/
 docs/VERIFICATION_*.md
+docs/README.md
+docs/development/*-analysis.md
+docs/development/*-comparison.md
+docs/development/gstreamer-*.md
 CODE_REVIEW.md
 GAP_ANALYSIS.md
 IMPLEMENTATION_PLAN.md

docs/getting-started/quick-start.md

@@ -38,6 +38,27 @@ Run in the background:
 gslapper -f -o "loop" DP-1 /path/to/video.mp4
 ```
 
+## With Image Cache (Instant Switching)
+
+Cache images in RAM for near-instant wallpaper changes:
+
+```bash
+# Start with cache enabled (256 MB)
+gslapper --cache-size 256 -I /tmp/gslapper.sock DP-1 /path/to/image1.jpg
+
+# Switch to another image instantly (via IPC)
+echo "change /path/to/image2.jpg" | nc -U /tmp/gslapper.sock
+
+# Check cache usage
+echo "cache-stats" | nc -U /tmp/gslapper.sock
+```
+
+**What happens:**
+- First image is automatically cached when displayed
+- Subsequent `change` commands cache new images on-the-fly
+- Switching back to a cached image is near-instant (no re-decode)
+- LRU eviction removes least-recently-used images when cache is full
+
 ## Making Wallpapers Persistent
 
 To make your wallpaper survive reboots and logins, see the [Persistent Wallpapers](../user-guide/persistent-wallpapers.md) guide. It covers:

docs/index.md

@@ -22,6 +22,7 @@
 
 - **Video Wallpapers** - Plays MP4, MKV, WebM, and other video formats
 - **Static Images** - Supports JPEG, PNG, WebP, and GIF
+- **Instant Switching** - RAM cache for near-instant wallpaper changes
 - **Fade Transitions** - Smooth transitions between wallpapers
 - **Multi-Monitor** - Works with multiple displays independently
 - **IPC Control** - Change wallpapers at runtime via Unix socket

docs/user-guide/command-line-options.md

@@ -78,6 +78,38 @@ Enable IPC control via Unix socket.
 gslapper -I /tmp/gslapper.sock DP-1 video.mp4
 ```
 
+## Cache Options
+
+### `--cache-size SIZE_MB`
+
+Enable image cache with specified size in MB. Caches decoded RGBA image data in RAM for instant wallpaper switching.
+
+```bash
+# 256 MB cache (recommended for ~10-30 images depending on resolution)
+gslapper --cache-size 256 -I /tmp/gslapper.sock DP-1 /path/to/image.jpg
+
+# Switch images instantly via IPC
+echo "change /path/to/other.jpg" | nc -U /tmp/gslapper.sock
+```
+
+**Default:** `0` (disabled)
+
+**Recommended Values:**
+- `128` MB - For smaller image collections (~5-15 images at 4K)
+- `256` MB - General purpose (~10-30 images at 4K)
+- `512` MB - Large collections or many high-resolution images
+
+**Features:**
+- Automatic caching when images are displayed
+- LRU (Least Recently Used) eviction when cache is full
+- Cache hits result in near-instant wallpaper changes
+- Query cache usage via IPC: `cache-stats`, `cache-list`
+
+**Notes:**
+- Only works with static images (JPEG, PNG, WebP, etc.)
+- Videos are not cached (use GStreamer pipeline directly)
+- Cache is cleared on exit
+
 ## Video Options
 
 ### `-o, --gst-options "OPTIONS"`

docs/user-guide/ipc-control.md

@@ -148,10 +148,59 @@ case "$1" in
 esac
 ```
 
-## Future Commands
+## Cache Management Commands
 
-The following commands are planned for future releases:
+These commands require `--cache-size` to be enabled.
 
-- `preload <path>` - Preload image into cache
-- `unload <path>` - Remove image from cache
-- `list` - List preloaded images
+### `cache-list`
+
+List all cached images with dimensions and sizes.
+
+```bash
+echo "cache-list" | nc -U /tmp/gslapper.sock
+```
+
+**Response:** List of cached images, one per line:
+```
+/path/to/image1.jpg 3840x2160 31.64 MB [*]
+/path/to/image2.png 2560x1440 14.06 MB
+```
+
+The `[*]` marker indicates currently displayed image.
+
+### `cache-stats`
+
+Show cache usage statistics.
+
+```bash
+echo "cache-stats" | nc -U /tmp/gslapper.sock
+```
+
+**Response:** `45.70/256.00 MB (2 images)` or `Cache disabled`
+
+### `unload <target>`
+
+Remove images from cache. Target can be:
+- `unused` - Remove all images not currently displayed
+- `all` - Clear entire cache (including displayed image)
+- `<path>` - Remove specific image by path
+
+```bash
+echo "unload unused" | nc -U /tmp/gslapper.sock
+echo "unload all" | nc -U /tmp/gslapper.sock
+echo "unload /path/to/image.jpg" | nc -U /tmp/gslapper.sock
+```
+
+**Response:** `OK: Unloaded N image(s)` or `ERROR: <message>`
+
+### `listactive`
+
+Show currently displayed wallpaper(s) and output(s).
+
+```bash
+echo "listactive" | nc -U /tmp/gslapper.sock
+```
+
+**Response:** `ACTIVE: <output> <type> <path>`
+
+Example: `ACTIVE: DP-1 image /home/user/wallpaper.jpg`