example: Add IPC remote control example.

examples/ipc-remote.md

@@ -0,0 +1,78 @@
+# IPC Remote Control
+
+Interactive demo of pikl's IPC socket. Run pikl in one terminal, control it
+from another. Watch the menu respond in real time.
+
+## Prerequisites
+
+- `socat` for socket I/O (`pacman -S socat` / `brew install socat`)
+- `python3` for pretty-printing JSON responses (optional, falls back to raw output)
+
+## Quick start
+
+**Terminal 1:** start pikl with IPC enabled.
+
+```sh
+echo -e "alpha\nbeta\ngamma\ndelta\nepsilon" | pikl --ipc --session demo
+```
+
+**Terminal 2:** connect the remote control.
+
+```sh
+./examples/ipc-remote.sh demo
+```
+
+## What you can do
+
+The remote gives you single-key commands:
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Move cursor down / up |
+| `g` / `G` | Jump to top / bottom |
+| `f` | Set filter text (then type the query) |
+| `F` | Clear filter |
+| `Space` | Toggle select on current item |
+| `a` | Select all |
+| `c` | Clear selections |
+| `s` | Print current menu state (JSON) |
+| `S` | Print current selection (JSON) |
+| `+` | Add new items interactively |
+| `r` | Replace all items |
+| `Enter` | Confirm selection (exits pikl) |
+| `q` | Cancel (exits pikl) |
+| `x` | Exit remote without affecting pikl |
+
+## Things to try
+
+1. Press `j` a few times and watch the cursor move in the pikl terminal.
+2. Press `s` to see the state, including cursor position and item count.
+3. Press `f`, type `al`, and watch the filter narrow the list.
+4. Press `F` to clear the filter.
+5. Press `+` and add a few items. They appear in the pikl terminal immediately.
+6. Press `Space` a couple times to toggle selections, then `S` to see what's selected.
+7. Press `Enter` to confirm. pikl exits and prints the selection.
+
+## How it works
+
+The remote sends newline-delimited JSON commands to pikl's Unix socket using
+`socat`. Write commands (move, filter, add items) are fire-and-forget. Read
+commands (get_state, get_selection) wait for a JSON response.
+
+The socket path for a named session is `/run/user/$UID/pikl-{session}.sock`.
+Without `--session`, pikl uses the PID: `/run/user/$UID/pikl-{pid}.sock`.
+
+## Using socat directly
+
+You don't need the remote script. Any tool that speaks Unix sockets works:
+
+```sh
+# Query state
+echo '{"action":"get_state","id":"1"}' | socat - UNIX-CONNECT:/run/user/$(id -u)/pikl-demo.sock
+
+# Move cursor down
+echo '{"action":"move_down"}' | socat -t 0.1 - UNIX-CONNECT:/run/user/$(id -u)/pikl-demo.sock
+
+# Add items
+echo '{"action":"add_items","items":["foo","bar"]}' | socat -t 0.1 - UNIX-CONNECT:/run/user/$(id -u)/pikl-demo.sock
+```