Polish docs and harden plugin loading

bin/omarchy-shell-ipc

@@ -3,15 +3,37 @@
 # omarchy:summary=Send an IPC call to omarchy-shell, starting it if not running
 # omarchy:hidden=true
 
+if [[ $# -eq 0 || $1 == "-h" || $1 == "--help" ]]; then
+  cat <<USAGE
+Usage: omarchy-shell-ipc <target> <method> [args...]
+
+Starts omarchy-shell if not running, then forwards a quickshell ipc call.
+
+Examples:
+  omarchy-shell-ipc shell ping
+  omarchy-shell-ipc shell summon omarchy.bar-settings "{}"
+  omarchy-shell-ipc shell hide omarchy.background-switcher
+  omarchy-shell-ipc shell listPlugins
+  omarchy-shell-ipc shell rescanPlugins
+USAGE
+  exit 0
+fi
+
 OMARCHY_PATH="${OMARCHY_PATH:-$HOME/.local/share/omarchy}"
 SHELL_DIR="$OMARCHY_PATH/default/quickshell/omarchy-shell"
 
-if ! quickshell list -p "$SHELL_DIR" 2>/dev/null | grep -q '^Instance '; then
-  setsid uwsm-app -- env OMARCHY_PATH="$OMARCHY_PATH" quickshell -p "$SHELL_DIR" >/dev/null 2>&1 &
-  for _ in 1 2 3 4 5 6 7 8 9 10; do
-    sleep 0.2
-    quickshell list -p "$SHELL_DIR" 2>/dev/null | grep -q '^Instance ' && break
-  done
-fi
+# Serialize concurrent invocations so two CLI callers don't both spawn the shell
+# when no instance is running yet.
+lockfile="${XDG_RUNTIME_DIR:-/tmp}/omarchy-shell-ipc.lock"
+{
+  flock 9
+  if ! quickshell list -p "$SHELL_DIR" 2>/dev/null | grep -q '^Instance '; then
+    setsid uwsm-app -- env OMARCHY_PATH="$OMARCHY_PATH" quickshell -p "$SHELL_DIR" >/dev/null 2>&1 &
+    for _ in 1 2 3 4 5 6 7 8 9 10; do
+      sleep 0.2
+      quickshell list -p "$SHELL_DIR" 2>/dev/null | grep -q '^Instance ' && break
+    done
+  fi
+} 9>"$lockfile"
 
 exec quickshell ipc -p "$SHELL_DIR" call "$@"