Wire up cache, file watcher, and Unix socket daemon

Adds a gen_server cache holding the rendered menu, an fs/inotify-based
watcher that debounces changes and invalidates it, a Unix domain
socket serving the cached binary, and the escript client Openbox
invokes (with an inline render fallback if the daemon isn't running).
Also documents local deployment (systemd user unit, Openbox menu.xml
wiring) in the README.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

1 files changed, 48 insertions, 0 deletions

diff --git a/README.md b/README.md
index 5a7da3b..fbf610c 100644
--- a/README.md
+++ b/README.md
@@ -7,3 +7,51 @@ Build
 -----
 
     $ rebar3 compile
+
+Live-reload (rebuilding the menu when `.desktop` files change) uses
+the `fs` library, which on Linux shells out to `inotifywait`. Install
+the `inotify-tools` package for this to work; without it the daemon
+still serves the menu it built at startup, it just won't notice
+later changes until restarted.
+
+Running locally
+----------------
+
+The app is a long-running daemon: it scans your XDG application
+directories once at startup, caches the rendered menu in memory, and
+serves it over a Unix domain socket at
+`$XDG_RUNTIME_DIR/er_xdg_pipe_menu.sock` (falling back to
+`/tmp/er_xdg_pipe_menu-$USER.sock` if `XDG_RUNTIME_DIR` isn't set),
+rebuilding the cache whenever a watched `.desktop` file changes.
+
+For a quick manual run (e.g. while developing):
+
+    $ rebar3 shell --eval "application:ensure_all_started(er_xdg_pipe_menu)."
+
+To have it start automatically with your session, add a systemd
+user unit, e.g. `~/.config/systemd/user/er-xdg-pipe-menu.service`:
+
+    [Unit]
+    Description=XDG pipe menu daemon
+
+    [Service]
+    WorkingDirectory=/path/to/er-xdg-pipe-menu
+    ExecStart=/usr/bin/rebar3 shell --eval "application:ensure_all_started(er_xdg_pipe_menu)."
+    Restart=on-failure
+
+    [Install]
+    WantedBy=default.target
+
+then enable it with `systemctl --user enable --now er-xdg-pipe-menu`.
+
+Openbox itself doesn't talk to the socket directly -- it invokes
+`bin/er_xdg_pipe_menu_menu` as the pipe menu command, which connects
+to the daemon's socket and prints whatever comes back (or, if the
+daemon isn't running, falls back to scanning/rendering inline so the
+menu still works). Point a pipe menu at it in `~/.config/openbox/menu.xml`:
+
+    <menu id="apps" label="Applications" execute="/path/to/er-xdg-pipe-menu/bin/er_xdg_pipe_menu_menu" />
+
+The script resolves its own location to find the compiled code, so
+it works from an absolute path as long as the repo's `_build`
+directory (from `rebar3 compile`) is alongside it.