Add headless streaming mode + Mac client + full docs

Headless mode (new) — for KVM-attached hosts streaming to disconnected clients
- --headless / --mirror flags; default headless on hostname JARVIS, mirror elsewhere
- New lib/headless.sh installs prep-cmd hooks to ~/.local/share/omarchy-moonlight/bin
- bin/sunshine-stream-do.sh creates/resizes a Hyprland HEADLESS-1 output to the
  connecting client's resolution and migrates the active workspace onto it
- bin/sunshine-stream-undo.sh tears down the headless output on disconnect and
  returns the workspace to a non-headless monitor when one is available
- lib/config.sh writes capture=wlr, output_name=HEADLESS-1, and the JSON
  global_prep_cmd entry referencing the installed hook paths
- lib/preflight.sh adds a preflight_headless step that checks hyprctl, jq, and
  a running Hyprland session (warn-only, install can proceed)
- lib/verify.sh adds checks for the hook scripts and the wlr/global_prep_cmd
  config lines

Mac client
- client/install-macos.sh: Darwin guard, Homebrew presence check, brew cask
  install of Moonlight, idempotent
- client/README.md: per-platform install (macOS / Android / iOS / Apple TV /
  Linux + Steam Deck) and the five-step first-pair walkthrough

Other
- jq added to the helper install set in lib/packages.sh (hooks parse Hyprland
  JSON output)
- README.md rewritten to cover both modes, the new flags, the tuned defaults
  per mode + per vendor, the headless internals, and the client pointer

install.sh

@@ -24,6 +24,8 @@ source "$SCRIPT_DIR/lib/firewall.sh"
 source "$SCRIPT_DIR/lib/service.sh"
 # shellcheck source=lib/verify.sh
 source "$SCRIPT_DIR/lib/verify.sh"
+# shellcheck source=lib/headless.sh
+source "$SCRIPT_DIR/lib/headless.sh"
 
 usage() {
   cat <<EOF
@@ -38,6 +40,8 @@ Options:
   --no-sunshine     Don't install sunshine (client-only setup)
   --no-config       Don't write a tuned sunshine.conf
   --from-source     Build Sunshine from source (equivalent to SUNSHINE_PKG=sunshine)
+  --headless        Force headless streaming mode (wlr capture of HEADLESS-1)
+  --mirror          Force mirror mode (KMS capture of the real display)
   --doctor          Run only the post-install verification checks
   -h, --help        Show this help
 
@@ -53,6 +57,7 @@ INSTALL_SUNSHINE=1
 INSTALL_MOONLIGHT=1
 WRITE_CONFIG=1
 DOCTOR_ONLY=0
+MODE_OVERRIDE=""
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -62,6 +67,8 @@ while [[ $# -gt 0 ]]; do
     --no-sunshine)   INSTALL_SUNSHINE=0 ;;
     --no-config)     WRITE_CONFIG=0 ;;
     --from-source)   export SUNSHINE_PKG=sunshine ;;
+    --headless)      MODE_OVERRIDE="headless" ;;
+    --mirror)        MODE_OVERRIDE="mirror" ;;
     --doctor)        DOCTOR_ONLY=1 ;;
     -h|--help)       usage; exit 0 ;;
     *)               err "Unknown option: $1"; usage; exit 2 ;;
@@ -69,6 +76,21 @@ while [[ $# -gt 0 ]]; do
   shift
 done
 
+# Pick streaming mode: explicit flag wins; otherwise default to headless on
+# JARVIS (the KVM-attached primary target) and mirror everywhere else.
+compute_stream_mode() {
+  if [[ -n "$MODE_OVERRIDE" ]]; then
+    STREAM_MODE="$MODE_OVERRIDE"
+    return 0
+  fi
+  local host_lc="${HOSTNAME_SHORT,,}"
+  if [[ "$host_lc" == "jarvis" ]]; then
+    STREAM_MODE="headless"
+  else
+    STREAM_MODE="mirror"
+  fi
+}
+
 main() {
   require_not_root
   require_arch
@@ -76,7 +98,10 @@ main() {
 
   step "Detecting system"
   detect_all
+  compute_stream_mode
+  export STREAM_MODE
   info "Host: $HOSTNAME_SHORT   GPU: $GPU_VENDOR   Session: $SESSION_TYPE"
+  info "Mode: $STREAM_MODE"
 
   if [[ $DOCTOR_ONLY -eq 1 ]]; then
     verify_install
@@ -96,9 +121,14 @@ main() {
     ensure_uinput_udev_rule
     set_sunshine_capabilities
 
+    if [[ "$STREAM_MODE" == "headless" ]]; then
+      step "Installing headless prep-cmd hooks"
+      install_headless_hooks
+    fi
+
     if [[ $WRITE_CONFIG -eq 1 ]]; then
       step "Writing tuned sunshine.conf"
-      write_sunshine_config
+      write_sunshine_config "$STREAM_MODE"
     else
       info "Skipping sunshine.conf (--no-config)"
     fi