Bump version from 3.8.0 to 3.8.1

Pin omarchy-reinstall-git to master branch

AGENTS.md

@@ -6,10 +6,15 @@
 - Prefer `(( ))` over numeric operators inside `[[ ]]` (e.g., `(( count < 50 ))`, not `[[ $count -lt 50 ]]`)
 - For strings/paths with spaces, quote them instead of escaping spaces with `\ ` (e.g., `"$APP_DIR/Disk Usage.desktop"`, not `$APP_DIR/Disk\ Usage.desktop`)
 - Shebangs must use `#!/bin/bash` consistently (never `#!/usr/bin/env bash`)
+- Scripts under `install/` and `migrations/` may be sourced and intentionally omit shebangs
 
 # Command Naming
 
-All commands start with `omarchy-`. Prefixes indicate purpose:
+All commands start with `omarchy-`. Prefixes indicate purpose.
+
+The authoritative command group list lives in `bin/omarchy` in `GROUP_DESCRIPTIONS`. Keep `GROUP_DESCRIPTIONS` updated when adding a new command prefix.
+
+Common prefixes include:
 
 - `cmd-` - check if commands exist, misc utility commands
 - `capture-` - screenshots, screen recordings, and other capture tools
@@ -24,6 +29,52 @@ All commands start with `omarchy-`. Prefixes indicate purpose:
 - `theme-` - theme management
 - `update-` - update components
 
+Other current prefixes include:
+
+- `ac-`, `audio-`, `battery-`, `branch-`, `brightness-`, `channel-`, `config-`, `debug-`, `dev-`, `drive-`, `first-`, `font-`, `haptic-`, `hibernation-`, `hook-`, `hyprland-`, `menu-`, `migrate-`, `notification-`, `npx-`, `plymouth-`, `powerprofiles-`, `reinstall-`, `remove-`, `screensaver-`, `show-`, `snapshot-`, `state-`, `sudo-`, `swayosd-`, `system-`, `transcode-`, `tui-`, `tz-`, `upload-`, `version-`, `voxtype-`, `webapp-`, `wifi-`, `windows-`
+
+# Command Metadata
+
+Commands in `bin/` can declare CLI metadata in comments near the top of the file. `bin/omarchy` scans the first 80 lines, and tests expect command metadata to remain valid.
+
+Supported metadata keys:
+
+- `# omarchy:summary=...` - short help text
+- `# omarchy:group=...` - command group when it differs from the filename-derived prefix
+- `# omarchy:name=...` - command name within the group
+- `# omarchy:args=...` - usage arguments
+- `# omarchy:examples=...` - examples separated with ` | `
+- `# omarchy:alias=...` / `# omarchy:aliases=...` - alternate routes
+- `# omarchy:hidden=true` - hide from default command listings
+- `# omarchy:requires-sudo=true` - mark commands that require sudo
+
+Prefer explicit metadata for user-facing commands. Keep routes consistent with the filename unless there is a deliberate alias or compatibility route.
+
+Example:
+
+```bash
+# omarchy:summary=Take a screenshot
+# omarchy:group=capture
+# omarchy:args=[smart|region|windows|fullscreen] [slurp|copy]
+# omarchy:examples=omarchy screenshot | omarchy capture screenshot region
+# omarchy:aliases=omarchy screenshot
+```
+
+# Install Scripts
+
+Install entry points (`install.sh`, `boot.sh`) use `#!/bin/bash`. Many scripts under `install/` are sourced via `run_logged` and intentionally do not have shebangs.
+
+Install stage files follow this pattern:
+
+- `install/*/all.sh` lists scripts in execution order
+- leaf scripts are sourced by `run_logged $OMARCHY_INSTALL/path/to/script.sh`
+- avoid `exit` in sourced install scripts unless intentionally aborting the install
+- use `$OMARCHY_INSTALL` and `$OMARCHY_PATH` instead of hard-coded Omarchy paths
+- keep hardware-specific logic under `install/config/hardware/`
+- prefer helper commands for package and command checks where available
+
+Raw `command -v`, `pacman`, and `pacman-key` are acceptable in bootstrap/preflight/package-helper contexts where the helper commands may not be available yet or where direct package-manager behavior is the point of the script.
+
 # Helper Commands
 
 Use these instead of raw shell commands:
@@ -33,12 +84,18 @@ Use these instead of raw shell commands:
 - `omarchy-pkg-add` - install packages (handles both pacman and AUR)
 - `omarchy-hw-asus-rog` - detect ASUS ROG hardware (and similar `hw-*` commands)
 
+Exceptions are allowed for bootstrap, preflight, migration, and package-helper scripts where the helper may not be available yet, where the helper itself is being implemented, or where direct package-manager behavior is required.
+
 # Config Structure
 
 - `config/` - default configs copied to `~/.config/`
 - `default/themed/*.tpl` - templates with `{{ variable }}` placeholders for theme colors
 - `themes/*/colors.toml` - theme color definitions (accent, background, foreground, color0-15)
 
+# Visual Changes
+
+When making visual changes, such as Waybar styles or desktop appearance, always take and analyze a screenshot after applying the change to verify the result. Use `omarchy capture screenshot fullscreen save` for fullscreen screenshots.
+
 # Refresh Pattern
 
 To copy a default config to user config with automatic backup:
@@ -53,10 +110,16 @@ This copies `~/.local/share/omarchy/config/hypr/hyprlock.conf` to `~/.config/hyp
 
 To create a new migration, run `omarchy-dev-add-migration --no-edit`. This creates a migration file named after the unix timestamp of the last commit.
 
-Migration format:
+New migration format:
+- File permissions must be `0644` (`-rw-r--r--`); migrations are sourced, not executed directly
 - No shebang line
 - Start with an `echo` describing what the migration does
 - Use `$OMARCHY_PATH` to reference the omarchy directory
+- Prefer helper commands such as `omarchy-cmd-present`, `omarchy-cmd-missing`, `omarchy-pkg-present`, and `omarchy-pkg-missing`
+
+Some older migrations predate these rules. Do not copy older migrations that start with shebangs, omit the leading `echo`, or hard-code `~/.local/share/omarchy`.
+
+Migrations may use raw `pacman`, `command -v`, or direct config edits when needed for historical compatibility or one-off repair work.
 
 Example:
 ```bash

applications/hidden/foot-server.desktop

@@ -0,0 +1,2 @@
+[Desktop Entry]
+Hidden=true

applications/hidden/footclient.desktop

@@ -0,0 +1,2 @@
+[Desktop Entry]
+Hidden=true

bin/omarchy-ac-present

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Returns true if AC power is connected.
+# omarchy:summary=Returns true if AC power is connected.
 
 for ac in /sys/class/power_supply/AC* /sys/class/power_supply/ADP*; do
   [[ -r $ac/online && $(cat "$ac/online") == "1" ]] && exit 0

bin/omarchy-audio-input-mute

@@ -1,11 +1,21 @@
 #!/bin/bash
 
-# Toggle microphone mute. Dell XPS and ThinkPad systems get special handling for the hardware LED.
+# omarchy:summary=Toggle microphone mute. Drives the hardware mic-mute LED on laptops that expose one.
 
-if omarchy-hw-match "XPS"; then
-  omarchy-audio-input-mute-xps
-elif omarchy-hw-match "ThinkPad"; then
-  omarchy-audio-input-mute-thinkpad
+wpctl set-mute @DEFAULT_AUDIO_SOURCE@ toggle >/dev/null
+
+if pactl get-source-mute @DEFAULT_SOURCE@ | rg -q 'yes'; then
+  led=on
+  osd_message='Microphone muted'
+  osd_icon='microphone-sensitivity-muted-symbolic'
 else
-  omarchy-swayosd-client --input-volume mute-toggle
+  led=off
+  osd_message='Microphone on'
+  osd_icon='audio-input-microphone-symbolic'
 fi
+
+omarchy-brightness-keyboard-mute "$led"
+
+omarchy-swayosd-client \
+  --custom-message "$osd_message" \
+  --custom-icon "$osd_icon"

bin/omarchy-audio-input-mute-thinkpad

@@ -1,22 +0,0 @@
-#!/bin/bash
-
-# Toggle microphone mute on ThinkPad systems. Uses wpctl for reliable toggling
-# and syncs the platform::micmute LED via brightnessctl.
-
-wpctl set-mute @DEFAULT_AUDIO_SOURCE@ toggle >/dev/null
-
-if pactl get-source-mute @DEFAULT_SOURCE@ | grep -q 'yes'; then
-  osd_message='Microphone muted'
-  osd_icon='microphone-sensitivity-muted-symbolic'
-  led_value=1
-else
-  osd_message='Microphone on'
-  osd_icon='audio-input-microphone-symbolic'
-  led_value=0
-fi
-
-brightnessctl --device="platform::micmute" set "$led_value" >/dev/null 2>&1 || true
-
-omarchy-swayosd-client \
-  --custom-message "$osd_message" \
-  --custom-icon "$osd_icon"

bin/omarchy-audio-input-mute-xps

@@ -1,43 +0,0 @@
-#!/bin/bash
-
-# Toggle microphone mute on Dell XPS systems. Uses wpctl for reliable toggling
-# and syncs the ALSA capture switch so the hardware mic mute LED follows state.
-
-wpctl set-mute @DEFAULT_AUDIO_SOURCE@ toggle >/dev/null
-
-if pactl get-source-mute @DEFAULT_SOURCE@ | rg -q 'yes'; then
-  alsa_value='off,off'
-  osd_message='Microphone muted'
-  osd_icon='microphone-sensitivity-muted-symbolic'
-else
-  alsa_value='on,on'
-  osd_message='Microphone on'
-  osd_icon='audio-input-microphone-symbolic'
-fi
-
-if [[ -e /sys/class/leds/platform::micmute/brightness ]]; then
-  default_source=$(pactl get-default-source)
-  alsa_card=$(pactl -f json list sources | jq -r --arg source "$default_source" '
-    .[] | select(.name == $source) |
-    .properties["alsa.card"] // .properties["api.alsa.card"] // .properties["api.alsa.pcm.card"] // empty
-  ' | head -1)
-
-  if [[ -n $alsa_card ]]; then
-    cards=("$alsa_card")
-  else
-    mapfile -t cards < <(compgen -G '/proc/asound/card*' | rg -o 'card[0-9]+' | sed 's/card//' | sort -u)
-  fi
-
-  for card in "${cards[@]}"; do
-    while IFS= read -r control; do
-      if [[ $control != *"Jack Microphone"* ]]; then
-        amixer -c "$card" cset "$control" "$alsa_value" >/dev/null 2>&1 || true
-        break 2
-      fi
-    done < <(amixer -c "$card" controls 2>/dev/null | rg -o "name='[^']*Microphone Capture Switch'")
-  done
-fi
-
-omarchy-swayosd-client \
-  --custom-message "$osd_message" \
-  --custom-icon "$osd_icon"

bin/omarchy-audio-output-switch

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Switch between audio outputs while preserving the mute status. By default mapped to Super + Mute.
+# omarchy:summary=Switch between audio outputs while preserving the mute status. By default mapped to Super + Mute.
 
 sinks=$(pactl -f json list sinks | jq '[.[] | select((.ports | length == 0) or ([.ports[]? | .availability != "not available"] | any))]')
 sinks_count=$(echo "$sinks" | jq '. | length')

bin/omarchy-battery-capacity

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Returns the battery full capacity in Wh (rounded to whole number).
-# Used by omarchy-battery-status for displaying battery capacity.
+# omarchy:summary=Returns the battery full capacity in Wh (rounded to whole number).
 
 battery_info=$(upower -i $(upower -e | grep BAT))
 

bin/omarchy-battery-monitor

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Designed to be run by systemd timer every 30 seconds and alerts if battery is low
+# omarchy:summary=Designed to be run by systemd timer every 30 seconds and alerts if battery is low
+# omarchy:hidden=true
 
 BATTERY_THRESHOLD=10
 NOTIFICATION_FLAG="/run/user/$UID/omarchy_battery_notified"

bin/omarchy-battery-present

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Returns true if a battery is present on the system.
-# Used by the battery monitor and other battery-related checks.
+# omarchy:summary=Returns true if a battery is present on the system.
 
 for bat in /sys/class/power_supply/BAT*; do
   [[ -r $bat/present ]] &&

bin/omarchy-battery-remaining

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Returns the battery percentage remaining as an integer.
-# Used by the battery monitor and the Ctrl + Shift + Super + B hotkey.
+# omarchy:summary=Returns the battery percentage remaining as an integer.
 
 upower -i $(upower -e | grep BAT) | awk '/percentage/ { 
     print int($2)

bin/omarchy-battery-remaining-time

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Returns the battery time remaining (to empty or full) in a compact format.
+# omarchy:summary=Returns the battery time remaining (to empty or full) in a compact format.
 
 battery_info=$(upower -i $(upower -e | grep BAT))
 

bin/omarchy-battery-status

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Returns a formatted battery status string with percentage and power draw/charge.
-# Used by the battery notification hotkey (Ctrl + Shift + Super + B).
+# omarchy:summary=Returns a formatted battery status string with percentage and power draw/charge.
 
 battery_info=$(upower -i $(upower -e | grep BAT))
 

bin/omarchy-branch-set

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Set the branch for Omarchy's git repository.
+# omarchy:summary=Set the branch for Omarchy's git repository.
+# omarchy:args=<master|rc|dev>
 
 if (($# == 0)); then
   echo "Usage: omarchy-branch-set [master|rc|dev]"

bin/omarchy-branding-about

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+# omarchy:summary=Edit, set, or reset About branding
+# omarchy:group=branding
+# omarchy:name=about
+# omarchy:args=<image|text|reset>
+# omarchy:examples=omarchy branding about image | omarchy branding about text | omarchy branding about reset
+
+set -euo pipefail
+
+case "${1:-}" in
+image)
+  image=$(omarchy-menu-file "Logo image" "$HOME" "svg png")
+  if [[ -n $image ]] && omarchy-transcode-ascii "$image" ~/.config/omarchy/branding/about.txt --width 54 --height 26 --mode block; then
+    omarchy-launch-about >/dev/null 2>&1
+  fi
+  ;;
+text)
+  omarchy-launch-editor ~/.config/omarchy/branding/about.txt >/dev/null 2>&1 && omarchy-launch-about >/dev/null 2>&1
+  ;;
+reset)
+  cp "$OMARCHY_PATH/icon.txt" ~/.config/omarchy/branding/about.txt && omarchy-launch-about >/dev/null 2>&1
+  ;;
+*)
+  echo "Usage: omarchy-branding-about <image|text|reset>" >&2
+  exit 1
+  ;;
+esac

bin/omarchy-branding-screensaver

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+# omarchy:summary=Edit, set, or reset screensaver branding
+# omarchy:group=branding
+# omarchy:name=screensaver
+# omarchy:args=<image|text|reset>
+# omarchy:examples=omarchy branding screensaver image | omarchy branding screensaver text | omarchy branding screensaver reset
+
+set -euo pipefail
+
+case "${1:-}" in
+image)
+  image=$(omarchy-menu-file "Logo image" "$HOME" "svg png")
+  if [[ -n $image ]] && omarchy-transcode-ascii "$image" ~/.config/omarchy/branding/screensaver.txt; then
+    omarchy-launch-screensaver force >/dev/null 2>&1
+  fi
+  ;;
+text)
+  omarchy-launch-editor ~/.config/omarchy/branding/screensaver.txt >/dev/null 2>&1 && omarchy-launch-screensaver force >/dev/null 2>&1
+  ;;
+reset)
+  cp "$OMARCHY_PATH/logo.txt" ~/.config/omarchy/branding/screensaver.txt && omarchy-launch-screensaver force >/dev/null 2>&1
+  ;;
+*)
+  echo "Usage: omarchy-branding-screensaver <image|text|reset>" >&2
+  exit 1
+  ;;
+esac

bin/omarchy-brightness-display

@@ -1,7 +1,8 @@
 #!/bin/bash
 
-# Adjust brightness on the most likely display device.
-# Usage: omarchy-brightness-display <step>
+# omarchy:summary=Adjust brightness on the most likely display device.
+# omarchy:args=<+N%|N%-|N%|off|on>
+# omarchy:examples=omarchy brightness display +5% | omarchy brightness display 5%- | omarchy brightness display 50% | omarchy brightness display off | omarchy brightness display on
 
 step="${1:-+5%}"
 
@@ -14,6 +15,19 @@ for candidate in amdgpu_bl* intel_backlight acpi_video*; do
   fi
 done
 
+if [[ $step == "off" ]]; then
+  hyprctl dispatch dpms off >/dev/null 2>&1
+  exit 0
+elif [[ $step == "on" ]]; then
+  hyprctl dispatch dpms on >/dev/null 2>&1
+  exit 0
+fi
+
+if omarchy-hyprland-monitor-focused-apple; then
+  omarchy-brightness-display-apple "$step"
+  exit
+fi
+
 # Current brightness percentage
 current=$(brightnessctl -d "$device" -m | cut -d',' -f4 | tr -d '%')
 

bin/omarchy-brightness-display-apple

@@ -1,12 +1,34 @@
 #!/bin/bash
 
-# Adjust the brightness on Apple Studio Displays and Apple XDR Displays using asdcontrol.
+# omarchy:summary=Adjust the brightness on Apple Studio Displays and Apple XDR Displays using asdcontrol.
+# omarchy:args=<+N%|N%-|N%>
+# omarchy:examples=omarchy brightness display apple +5% | omarchy brightness display apple 5%- | omarchy brightness display apple 50%
 
 if (( $# == 0 )); then
-  echo "Adjust Apple Display Brightness by passing +5000 or -5000 (or any range from 0-60000)"
+  echo "Adjust Apple Display brightness by passing +5%, 5%-, or 100%"
 else
-  device="$(sudo asdcontrol --detect /dev/usb/hiddev* | grep ^/dev/usb/hiddev | cut -d: -f1)"
-  sudo asdcontrol "$device" -- "$1" >/dev/null
+  step="$1"
+  if [[ $step =~ ^([0-9]+)%-$ ]]; then
+    step="-${BASH_REMATCH[1]}%"
+  fi
+
+  devices=()
+  for path in /dev/usb/hiddev* /dev/hiddev*; do
+    [[ -e $path ]] && devices+=("$path")
+  done
+
+  if (( ${#devices[@]} == 0 )); then
+    echo "No Apple Display HID device found"
+    exit 1
+  fi
+
+  device="$(sudo asdcontrol --detect "${devices[@]}" | grep -E '^/dev/(usb/)?hiddev' | cut -d: -f1 | head -n1)"
+  if [[ -z $device ]]; then
+    echo "No Apple Display HID device found"
+    exit 1
+  fi
+
+  sudo asdcontrol "$device" -- "$step" >/dev/null
   value="$(sudo asdcontrol "$device" | awk -F= '/BRIGHTNESS=/{print $2+0}')"
   omarchy-swayosd-brightness "$(( value * 100 / 60000 ))"
 fi

bin/omarchy-brightness-keyboard

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Adjust keyboard backlight brightness using available steps.
-# Usage: omarchy-brightness-keyboard <up|down|cycle>
+# omarchy:summary=Adjust keyboard backlight brightness using available steps.
+# omarchy:args=<up|down|cycle|off|restore>
 
 direction="${1:-up}"
 
@@ -19,6 +19,14 @@ if [[ -z $device ]]; then
   exit 1
 fi
 
+if [[ $direction == "off" ]]; then
+  brightnessctl -sd "$device" set 0 >/dev/null
+  exit 0
+elif [[ $direction == "restore" ]]; then
+  brightnessctl -rd "$device" >/dev/null
+  exit 0
+fi
+
 # Get current and max brightness to determine step size.
 max_brightness="$(brightnessctl -d "$device" max)"
 current_brightness="$(brightnessctl -d "$device" get)"

bin/omarchy-brightness-keyboard-mute

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+# omarchy:summary=Set the mic-mute indicator LED on laptops that expose a platform::micmute LED node.
+# omarchy:args=<on|off>
+
+if [[ -e /sys/class/leds/platform::micmute/brightness ]]; then
+  case "$1" in
+    on)  value=1 ;;
+    off) value=0 ;;
+    *)   echo "Usage: $(basename "$0") <on|off>" >&2; exit 1 ;;
+  esac
+
+  brightnessctl --device="platform::micmute" set "$value" >/dev/null 2>&1 || true
+fi

bin/omarchy-capture-screenrecording

@@ -1,9 +1,22 @@
 #!/bin/bash
 
-# Start and stop a screenrecording, which will be saved to ~/Videos by default.
-# Alternative location can be set via OMARCHY_SCREENRECORD_DIR or XDG_VIDEOS_DIR ENVs.
-# Resolution is capped to 4K for monitors above 4K, native otherwise.
-# Override via --resolution= (e.g. --resolution=1920x1080, --resolution=0x0 for native).
+# omarchy:summary=Start or stop screen recording
+# omarchy:group=capture
+# omarchy:args=[--with-desktop-audio] [--with-microphone-audio] [--with-webcam] [--webcam-device=<device>] [--resolution=<size>] [--stop-recording]
+# omarchy:examples=omarchy screenrecord | omarchy capture screenrecord --with-desktop-audio
+# omarchy:aliases=omarchy screenrecord
+#
+# Env: OMARCHY_SCREENRECORD_USE_PORTAL=true skips the built-in slurp picker and
+# uses gpu-screen-recorder's xdg-desktop-portal capture backend instead. The
+# portal backend was originally added (PR #3401) for HDR-aware capture, support
+# for monitors driven by external GPUs, and window capture — enable it if any
+# of those matter to you. Off by default because the portal path can fail EGL
+# DMA-BUF modifier import on some configurations, leaving recording unable to
+# start.
+#
+# Env: OMARCHY_SCREENRECORD_DEBUG=true appends gpu-screen-recorder's stderr (and
+# the picker target it was launched with) to /tmp/omarchy-screenrecord.log so
+# users can attach a log when reporting capture failures.
 
 [[ -f ~/.config/user-dirs.dirs ]] && source ~/.config/user-dirs.dirs
 OUTPUT_DIR="${OMARCHY_SCREENRECORD_DIR:-${XDG_VIDEOS_DIR:-$HOME/Videos}}"
@@ -20,6 +33,7 @@ WEBCAM_DEVICE=""
 RESOLUTION=""
 STOP_RECORDING="false"
 RECORDING_FILE="/tmp/omarchy-screenrecord-filename"
+LOG_FILE=$([[ ${OMARCHY_SCREENRECORD_DEBUG:-false} == "true" ]] && echo "/tmp/omarchy-screenrecord.log" || echo "/dev/null")
 
 for arg in "$@"; do
   case "$arg" in
@@ -86,7 +100,92 @@ default_resolution() {
   fi
 }
 
+# Monitor + window rectangles on the focused workspace, in slurp's "X,Y WxH" format.
+# Mirrors omarchy-capture-screenshot so the picker UX is identical.
+get_rectangles() {
+  local active_workspace=$(hyprctl monitors -j | jq -r '.[] | select(.focused == true) | .activeWorkspace.id')
+  hyprctl monitors -j | jq -r --arg ws "$active_workspace" '
+    .[] | select(.activeWorkspace.id == ($ws | tonumber)) |
+    "\(.x),\(.y) \(.width / .scale | floor)x\(.height / .scale | floor)"'
+  hyprctl clients -j | jq -r --arg ws "$active_workspace" '
+    .[] | select(.workspace.id == ($ws | tonumber)) |
+    "\(.at[0]),\(.at[1]) \(.size[0])x\(.size[1])"'
+}
+
+# Echoes "monitor:NAME" when the selection matches an entire monitor, otherwise
+# "region:WxH+X+Y" with physical-pixel coordinates ready for gpu-screen-recorder.
+# Returns non-zero if the user cancelled the picker.
+select_capture_target() {
+  local rects=$(get_rectangles)
+  hyprpicker -r -z >/dev/null 2>&1 &
+  local picker_pid=$!
+  sleep .1
+  local selection=$(echo "$rects" | slurp 2>/dev/null)
+  kill $picker_pid 2>/dev/null
+
+  # X and Y can be negative (Hyprland monitor positions in multi-display layouts);
+  # widths and heights are always positive.
+  [[ $selection =~ ^(-?[0-9]+),(-?[0-9]+)[[:space:]]([0-9]+)x([0-9]+)$ ]] || return 1
+  local sx=${BASH_REMATCH[1]} sy=${BASH_REMATCH[2]}
+  local sw=${BASH_REMATCH[3]} sh=${BASH_REMATCH[4]}
+
+  # A bare click (area < 20px²) snaps to whichever rectangle the click landed
+  # inside, so users don't end up with accidental 2px recordings.
+  if ((sw * sh < 20)); then
+    while IFS= read -r rect; do
+      [[ $rect =~ ^(-?[0-9]+),(-?[0-9]+)[[:space:]]([0-9]+)x([0-9]+)$ ]] || continue
+      local rx=${BASH_REMATCH[1]} ry=${BASH_REMATCH[2]}
+      local rw=${BASH_REMATCH[3]} rh=${BASH_REMATCH[4]}
+      if ((sx >= rx && sx < rx + rw && sy >= ry && sy < ry + rh)); then
+        sx=$rx sy=$ry sw=$rw sh=$rh
+        break
+      fi
+    done <<<"$rects"
+  fi
+
+  # When the selection exactly matches a monitor, prefer -w <monitor> over a
+  # region capture — same kms backend, but no scaling math and full native res.
+  local monitor=$(hyprctl monitors -j | jq -r --argjson x "$sx" --argjson y "$sy" --argjson w "$sw" --argjson h "$sh" '
+    .[] | select(.x == $x and .y == $y and (.width / .scale | floor) == $w and (.height / .scale | floor) == $h) | .name' | head -1)
+
+  if [[ -n $monitor ]]; then
+    echo "monitor:$monitor"
+    return
+  fi
+
+  # gpu-screen-recorder wants region geometry in the compositor's logical
+  # coordinate space — same space slurp returns — so pass the values through
+  # untouched. (gsr scales to physical pixels itself based on the monitor.)
+  echo "region:${sw}x${sh}+${sx}+${sy}"
+}
+
 start_screenrecording() {
+  local capture_args=()
+  local target
+
+  # Opt-in path for HDR, external-GPU monitors, and window capture (all things
+  # the portal backend supports and the kms backend doesn't). Default flow uses
+  # slurp + the kms backend, which avoids the EGL DMA-BUF modifier import
+  # failures the portal path can hit on some configurations.
+  if [[ ${OMARCHY_SCREENRECORD_USE_PORTAL:-false} == "true" ]]; then
+    target="portal"
+    capture_args=(-w portal -s "${RESOLUTION:-$(default_resolution)}")
+  else
+    target=$(select_capture_target) || return 1
+
+    case $target in
+    monitor:*)
+      capture_args=(-w "${target#monitor:}" -s "${RESOLUTION:-$(default_resolution)}")
+      ;;
+    region:*)
+      capture_args=(-w "${target#region:}")
+      [[ -n $RESOLUTION ]] && capture_args+=(-s "$RESOLUTION")
+      ;;
+    esac
+  fi
+
+  [[ $WEBCAM == "true" ]] && start_webcam_overlay
+
   local filename="$OUTPUT_DIR/screenrecording-$(date +'%Y-%m-%d_%H-%M-%S').mp4"
   local audio_devices=""
   local audio_args=()
@@ -101,12 +200,10 @@ start_screenrecording() {
 
   [[ -n $audio_devices ]] && audio_args+=(-a "$audio_devices" -ac aac)
 
-  local resolution="${RESOLUTION:-$(default_resolution)}"
-
-  gpu-screen-recorder -w portal -k auto -s "$resolution" -f 60 -fm cfr -fallback-cpu-encoding yes -o "$filename" "${audio_args[@]}" &
+  echo "===== $(date '+%F %T') args: $* target: $target =====" >>"$LOG_FILE"
+  gpu-screen-recorder "${capture_args[@]}" -k auto -f 60 -fm cfr -fallback-cpu-encoding yes -o "$filename" "${audio_args[@]}" 2>>"$LOG_FILE" &
   local pid=$!
 
-  # Wait for recording to actually start (file appears after portal selection)
   while kill -0 $pid 2>/dev/null && [[ ! -f $filename ]]; do
     sleep 0.2
   done
@@ -136,6 +233,7 @@ stop_screenrecording() {
   else
     finalize_recording
     local filename=$(cat "$RECORDING_FILE" 2>/dev/null)
+    echo "$filename"
     local preview="${filename%.mp4}-preview.png"
 
     # Generate a preview thumbnail from the first frame
@@ -174,7 +272,10 @@ finalize_recording() {
   # Trim the first frame, and normalize audio to -14 LUFS if present, in a single pass
   local args=(-y -ss 0.1 -i "$latest" "${video_codec[@]}")
   if ffprobe -v error -select_streams a -show_entries stream=codec_type -of csv=p=0 "$latest" 2>/dev/null | grep -q audio; then
-    args+=(-af loudnorm=I=-14:TP=-1.5:LRA=11)
+    # Hard-mute the first 400ms to drop the PipeWire capture-open pop (a near-clipping
+    # transient around 130-200ms that a gentle fade-in can't attenuate enough), then a
+    # 50ms fade avoids a click at the boundary before loudnorm normalizes the rest.
+    args+=(-af "volume=enable='lt(t,0.4)':volume=0,afade=t=in:st=0.4:d=0.05,loudnorm=I=-14:TP=-1.5:LRA=11")
   fi
 
   local processed="${latest%.mp4}-processed.mp4"
@@ -190,7 +291,5 @@ if screenrecording_active; then
 elif [[ $STOP_RECORDING == "true" ]]; then
   exit 1
 else
-  [[ $WEBCAM == "true" ]] && start_webcam_overlay
-
   start_screenrecording || cleanup_webcam
 fi

bin/omarchy-capture-screenshot

@@ -1,8 +1,10 @@
 #!/bin/bash
 
-# Take a screenshot of the whole screen, a specific window, or a user-drawn region.
-# Saves to ~/Pictures by default, but that can be changed via OMARCHY_SCREENSHOT_DIR or XDG_PICTURES_DIR ENVs.
-# Editor defaults to Satty but can be changed via --editor=<name> or OMARCHY_SCREENSHOT_EDITOR env
+# omarchy:summary=Take a screenshot
+# omarchy:group=capture
+# omarchy:args=[smart|region|windows|fullscreen] [slurp|copy|save] [--editor=<name>]
+# omarchy:examples=omarchy screenshot | omarchy capture screenshot region
+# omarchy:aliases=omarchy screenshot
 
 [[ -f ~/.config/user-dirs.dirs ]] && source ~/.config/user-dirs.dirs
 OUTPUT_DIR="${OMARCHY_SCREENSHOT_DIR:-${XDG_PICTURES_DIR:-$HOME/Pictures}}"
@@ -124,14 +126,22 @@ esac
 FILENAME="screenshot-$(date +'%Y-%m-%d_%H-%M-%S').png"
 FILEPATH="$OUTPUT_DIR/$FILENAME"
 
-if [[ $PROCESSING == "slurp" ]]; then
-  grim -g "$SELECTION" "$FILEPATH" || exit 1
-  wl-copy <"$FILEPATH"
+case "$PROCESSING" in
+  slurp)
+    grim -g "$SELECTION" "$FILEPATH" || exit 1
+    echo "$FILEPATH"
+    wl-copy <"$FILEPATH"
 
-  (
-    ACTION=$(notify-send "Screenshot saved to clipboard and file" "Edit with Super + Alt + , (or click this)" -t 10000 -i "$FILEPATH" -A "default=edit")
-    [[ $ACTION == "default" ]] && open_editor "$FILEPATH"
-  ) &
-else
-  grim -g "$SELECTION" - | wl-copy
-fi
+    (
+      ACTION=$(notify-send "Screenshot saved to clipboard and file" "Edit with Super + Alt + , (or click this)" -t 10000 -i "$FILEPATH" -A "default=edit")
+      [[ $ACTION == "default" ]] && open_editor "$FILEPATH"
+    ) >/dev/null 2>&1 &
+    ;;
+  copy)
+    grim -g "$SELECTION" - | wl-copy
+    ;;
+  save)
+    grim -g "$SELECTION" "$FILEPATH" || exit 1
+    echo "$FILEPATH"
+    ;;
+esac

bin/omarchy-capture-text-extraction

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+# omarchy:summary=Extract text from a screenshot region with OCR
+# omarchy:group=capture
+# omarchy:examples=omarchy capture ocr
+
+# Keep hyprpicker alive until after grim captures so the screenshot sees the
+# frozen overlay rather than live content shifting during teardown.
+cleanup_freeze() {
+  [[ -n $PID ]] && kill $PID 2>/dev/null
+}
+trap cleanup_freeze EXIT
+
+hyprpicker -r -z >/dev/null 2>&1 &
+PID=$!
+sleep .1
+SELECTION=$(slurp 2>/dev/null)
+
+[[ -z $SELECTION ]] && exit 0
+
+TEXT=$(grim -g "$SELECTION" - | tesseract stdin stdout --oem 1 --psm 6 -l "${OMARCHY_OCR_LANGS:-eng}" --dpi 300 -c preserve_interword_spaces=1 2>/dev/null) || exit 1
+
+[[ -z $TEXT ]] && exit 1
+
+printf "%s" "$TEXT" | wl-copy
+notify-send "󰴑    Copied text from selection to clipboard"

bin/omarchy-channel-set

@@ -1,17 +1,8 @@
 #!/bin/bash
 
-# Set the Omarchy channel, which dictates what git branch and package repository is used.
-#
-# Stable uses the master branch, which only sees updates on official releases, and
-# the stable package repository, which typically lags the edge by a month to ensure
-# better compatibility.
-#
-# Edge tracks the latest package repository, but still relies on the master branch,
-# so new packages which require config changes may cause conflicts or errors.
-#
-# Dev tracks the active development dev branch, which may include partial or broken updates,
-# as well as the latest package repository. This should only be used by Omarchy developers
-# and people with a lot of experience managing Linux systems.
+# omarchy:summary=Set the Omarchy channel, which dictates what git branch and package repository is used.
+# omarchy:args=<stable|rc|edge|dev>
+# omarchy:requires-sudo=true
 
 if (($# == 0)); then
   echo "Usage: omarchy-channel-set [stable|rc|edge|dev]"

bin/omarchy-cmd-missing

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Returns true if any of the commands passed in as arguments are missing on the system.
+# omarchy:summary=Check whether any required commands are missing
 
 for cmd in "$@"; do
   if ! command -v "$cmd" &>/dev/null; then

bin/omarchy-cmd-present

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Returns true if all the commands passed in as arguments exit on the system.
+# omarchy:summary=Check whether all required commands are available
 
 for cmd in "$@"; do
   command -v "$cmd" &>/dev/null || exit 1

bin/omarchy-cmd-terminal-cwd

@@ -1,9 +1,8 @@
 #!/bin/bash
 
-# Returns the current working directory of the active terminal window,
-# so a new terminal window can be started in the same directory.
+# omarchy:summary=Print the current working directory of the active terminal window
+# omarchy:hidden=true
 
-# Go from current active terminal to its child shell process and run cwd there
 terminal_pid=$(hyprctl activewindow | awk '/pid:/ {print $2}')
 shell_pid=$(pgrep -P "$terminal_pid" | tail -n1)
 

bin/omarchy-config-direct-boot

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Add or remove an EFI boot entry for the Omarchy UKI, allowing the system to boot directly
-# without a bootloader like Limine. Requires UEFI firmware and a built UKI.
+# omarchy:summary=Add or remove an EFI boot entry for the Omarchy UKI, allowing the system to boot directly
+# omarchy:requires-sudo=true
 
 if [[ ! -d /sys/firmware/efi ]]; then
   echo "Error: System is not booted in UEFI mode" >&2

bin/omarchy-debug

@@ -1,6 +1,9 @@
 #!/bin/bash
 
-# Return exhaustive debugging information about the system to help diagnose problems.
+# omarchy:summary=Print debugging information
+# omarchy:args=[--no-sudo] [--print]
+# omarchy:examples=omarchy debug --print --no-sudo
+# omarchy:requires-sudo=true
 
 NO_SUDO=false
 PRINT_ONLY=false

bin/omarchy-default-browser

@@ -0,0 +1,40 @@
+#!/bin/bash
+
+# omarchy:summary=Set the default browser for Omarchy and XDG handlers
+# omarchy:args=[chromium|chrome|brave|brave-origin|edge|firefox|zen]
+# omarchy:examples=omarchy default browser firefox | omarchy default browser brave
+
+if (($# == 0)); then
+  case "$(xdg-settings get default-web-browser)" in
+  chromium.desktop) echo "chromium" ;;
+  google-chrome.desktop) echo "chrome" ;;
+  brave-browser.desktop) echo "brave" ;;
+  brave-origin-beta.desktop) echo "brave-origin" ;;
+  microsoft-edge.desktop) echo "edge" ;;
+  firefox.desktop) echo "firefox" ;;
+  zen.desktop) echo "zen" ;;
+  *) xdg-settings get default-web-browser ;;
+  esac
+  exit 0
+fi
+
+case "$1" in
+chromium) desktop_id="chromium.desktop"; name="Chromium"; glyph="" ;;
+chrome) desktop_id="google-chrome.desktop"; name="Chrome"; glyph="󰊯" ;;
+brave) desktop_id="brave-browser.desktop"; name="Brave"; glyph="󰖟" ;;
+brave-origin) desktop_id="brave-origin-beta.desktop"; name="Brave Origin"; glyph="󰖟" ;;
+edge) desktop_id="microsoft-edge.desktop"; name="Edge"; glyph="󰇩" ;;
+firefox) desktop_id="firefox.desktop"; name="Firefox"; glyph="󰈹" ;;
+zen) desktop_id="zen.desktop"; name="Zen"; glyph="󰰷" ;;
+*)
+  echo "Usage: omarchy-default-browser <chromium|chrome|brave|brave-origin|edge|firefox|zen>"
+  exit 1
+  ;;
+esac
+
+xdg-settings set default-web-browser "$desktop_id"
+xdg-mime default "$desktop_id" x-scheme-handler/http
+xdg-mime default "$desktop_id" x-scheme-handler/https
+xdg-mime default "$desktop_id" text/html
+
+notify-send -u low "$glyph    $name is now the default browser"

bin/omarchy-default-editor

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+# omarchy:summary=Set the default editor for $EDITOR
+# omarchy:args=[code|cursor|zed|sublime_text|helix|vim|emacs|nvim]
+# omarchy:examples=omarchy default editor | omarchy default editor code | omarchy default editor helix
+
+if (($# == 0)); then
+  sed -n 's/^export EDITOR=//p' ~/.config/uwsm/default | head -n 1
+  exit 0
+fi
+
+case "$1" in
+code) editor="code"; name="VSCode"; glyph="" ;;
+cursor) editor="cursor"; name="Cursor"; glyph="" ;;
+zed | zeditor) editor="zeditor"; name="Zed"; glyph="" ;;
+sublime_text) editor="sublime_text"; name="Sublime Text"; glyph="" ;;
+helix) editor="helix"; name="Helix"; glyph="" ;;
+vim) editor="vim"; name="Vim"; glyph="" ;;
+emacs) editor="emacs"; name="Emacs"; glyph="" ;;
+nvim) editor="nvim"; name="Neovim"; glyph="" ;;
+*)
+  echo "Usage: omarchy-default-editor <code|cursor|zed|sublime_text|helix|vim|emacs|nvim>"
+  exit 1
+  ;;
+esac
+
+sed -i "s/^export EDITOR=.*/export EDITOR=$editor/" ~/.config/uwsm/default
+
+export EDITOR="$editor"
+notify-send -u low "$glyph    $name is now the default editor" "      Effective after logging out"

bin/omarchy-default-terminal

@@ -0,0 +1,36 @@
+#!/bin/bash
+
+# omarchy:summary=Set the default terminal used by xdg-terminal-exec
+# omarchy:args=[alacritty|foot|ghostty|kitty]
+# omarchy:examples=omarchy default terminal ghostty | omarchy default terminal kitty
+
+if (($# == 0)); then
+  desktop_id=$(grep -vE '^($|#)' ~/.config/xdg-terminals.list 2>/dev/null | head -n 1)
+  case "$desktop_id" in
+  Alacritty.desktop) echo "alacritty" ;;
+  foot.desktop) echo "foot" ;;
+  com.mitchellh.ghostty.desktop) echo "ghostty" ;;
+  kitty.desktop) echo "kitty" ;;
+  *) echo "$desktop_id" ;;
+  esac
+  exit 0
+fi
+
+case "$1" in
+alacritty) desktop_id="Alacritty.desktop"; name="Alacritty"; glyph="" ;;
+foot) desktop_id="foot.desktop"; name="Foot"; glyph="" ;;
+ghostty) desktop_id="com.mitchellh.ghostty.desktop"; name="Ghostty"; glyph="" ;;
+kitty) desktop_id="kitty.desktop"; name="Kitty"; glyph="" ;;
+*)
+  echo "Usage: omarchy-default-terminal <alacritty|foot|ghostty|kitty>"
+  exit 1
+  ;;
+esac
+
+cat >~/.config/xdg-terminals.list <<EOF
+# Terminal emulator preference order for xdg-terminal-exec
+# The first found and valid terminal will be used
+$desktop_id
+EOF
+
+notify-send -u low "$glyph    $name is now the default terminal"

bin/omarchy-dev-add-migration

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Creates a new Omarchy migration named after the unix timestamp of the last commit.
-# Only intended for Omarchy developers.
+# omarchy:summary=Creates a new Omarchy migration named after the unix timestamp of the last commit.
 
 cd ~/.local/share/omarchy
 migration_file="$HOME/.local/share/omarchy/migrations/$(git log -1 --format=%cd --date=unix).sh"

bin/omarchy-dev-benchmark

@@ -0,0 +1,111 @@
+#!/bin/bash
+
+# omarchy:summary=Measure Omarchy CLI response times
+# omarchy:args=[--repeat=<count>]
+# omarchy:examples=omarchy dev benchmark | omarchy dev benchmark --repeat=10
+
+set -euo pipefail
+
+OMARCHY_BIN_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+CLI="$OMARCHY_BIN_DIR/omarchy"
+REPEAT=5
+
+show_help() {
+  cat <<'EOF'
+Usage:
+  omarchy dev benchmark [--repeat=<count>]
+
+Measure response times for common Omarchy CLI surfaces.
+
+Options:
+  --repeat=<count>  Number of times to run each case (default: 5)
+EOF
+}
+
+now_us() {
+  local now="${EPOCHREALTIME/./}"
+  printf '%s' "$now"
+}
+
+format_ms() {
+  local us="$1"
+  printf '%d.%03d' "$(( us / 1000 ))" "$(( us % 1000 ))"
+}
+
+run_case() {
+  local label="$1"
+  shift
+  local total_us=0
+  local min_us=0
+  local max_us=0
+  local elapsed_us=0
+  local start_us=0
+  local end_us=0
+  local status=0
+
+  for (( i = 1; i <= REPEAT; i++ )); do
+    start_us=$(now_us)
+    if "$@" >/dev/null; then
+      status=0
+    else
+      status=$?
+    fi
+    end_us=$(now_us)
+
+    if (( status != 0 )); then
+      printf '%-34s failed (exit %d)\n' "$label" "$status"
+      return "$status"
+    fi
+
+    elapsed_us=$(( end_us - start_us ))
+    total_us=$(( total_us + elapsed_us ))
+
+    if (( i == 1 || elapsed_us < min_us )); then
+      min_us=$elapsed_us
+    fi
+
+    if (( elapsed_us > max_us )); then
+      max_us=$elapsed_us
+    fi
+  done
+
+  printf '%-34s avg %8s ms  min %8s ms  max %8s ms\n' \
+    "$label" \
+    "$(format_ms "$(( total_us / REPEAT ))")" \
+    "$(format_ms "$min_us")" \
+    "$(format_ms "$max_us")"
+}
+
+while (( $# > 0 )); do
+  case "$1" in
+  --repeat=*)
+    REPEAT="${1#*=}"
+    ;;
+  --help | -h)
+    show_help
+    exit 0
+    ;;
+  *)
+    echo "Unknown option: $1" >&2
+    show_help >&2
+    exit 2
+    ;;
+  esac
+  shift
+done
+
+if [[ ! $REPEAT =~ ^[0-9]+$ ]] || (( REPEAT < 1 )); then
+  echo "--repeat must be a positive integer" >&2
+  exit 2
+fi
+
+printf 'Omarchy CLI benchmark (%d runs each)\n\n' "$REPEAT"
+run_case "omarchy" "$CLI"
+run_case "omarchy --help" "$CLI" --help
+run_case "omarchy commands" "$CLI" commands
+run_case "omarchy commands --json" "$CLI" commands --json
+run_case "omarchy commands --all --json" "$CLI" commands --all --json
+run_case "omarchy theme set --help" "$CLI" theme set --help
+run_case "omarchy screenshot --help" "$CLI" screenshot --help
+run_case "omarchy restart --help" "$CLI" restart --help
+run_case "omarchy theme current" "$CLI" theme current

bin/omarchy-dev-bin-metadata

@@ -0,0 +1,89 @@
+#!/bin/bash
+
+# omarchy:summary=Show Omarchy bin metadata fields and defaults
+# omarchy:args=[--json]
+
+set -euo pipefail
+
+show_json() {
+  jq -n '{
+    ok: true,
+    defaults: {
+      group: "first filename segment after omarchy-",
+      name: "remaining filename segments with dashes converted to spaces",
+      route: "omarchy <group> <name>",
+      binary: "filename",
+      requires_sudo: false
+    },
+    fields: [
+      {name: "summary", required: true, type: "string", note: "One-line human and agent-facing description."},
+      {name: "group", required: false, type: "string", note: "Only set when the route group should differ from the filename-derived group."},
+      {name: "name", required: false, type: "string", note: "Only set when the route name should differ from the filename-derived name. May be empty for root commands."},
+      {name: "args", required: false, type: "string", note: "Only set when the command accepts arguments."},
+      {name: "examples", required: false, type: "string", note: "Pipe-separated examples."},
+      {name: "aliases", required: false, type: "string", note: "Pipe-separated alternate routes, e.g. omarchy screenshot."},
+      {name: "requires-sudo", required: false, type: "true", default: false, note: "Only include when true."},
+      {name: "hidden", required: false, type: "true", default: false, note: "Hide from default command listings; visible with --all."}
+    ]
+  }'
+}
+
+show_help() {
+  cat <<'EOF'
+Omarchy bin metadata
+
+Metadata lives in the top comment block of each executable bin/omarchy-* file.
+Keep it slim: define only fields that are required or override defaults.
+
+Required:
+  # omarchy:summary=<one-line description>
+
+Inferred defaults:
+  group         first filename segment after omarchy-
+  name          remaining filename segments, with dashes converted to spaces
+  route         omarchy <group> <name>
+  binary        filename
+  requires-sudo false
+  hidden        false
+
+Optional fields:
+  # omarchy:group=<group>                  route override only
+  # omarchy:name=<name>                    route override only; may be empty
+  # omarchy:args=<args>                    only if the command accepts args
+  # omarchy:examples=<cmd> | <cmd>         pipe-separated examples
+  # omarchy:aliases=<route> | <route>      pipe-separated alternate routes
+  # omarchy:requires-sudo=true             only when true
+  # omarchy:hidden=true                    hide from default command listings
+
+Do not define:
+  binary      inferred from filename
+  usage       derived from route + args
+  false flags or empty args
+
+Examples:
+  # omarchy:summary=Restart Walker and related user services
+
+  # omarchy:summary=Take a screenshot
+  # omarchy:group=capture
+  # omarchy:args=[smart|region|windows|fullscreen] [slurp|copy] [--editor=<name>]
+  # omarchy:examples=omarchy screenshot | omarchy capture screenshot region
+  # omarchy:aliases=omarchy screenshot
+EOF
+}
+
+case "${1:-}" in
+--json)
+  show_json
+  ;;
+--help | -h)
+  show_help
+  ;;
+"")
+  show_help
+  ;;
+*)
+  echo "Unknown option: $1" >&2
+  show_help >&2
+  exit 2
+  ;;
+esac

bin/omarchy-drive-info

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Returns drive information about a given volumne, like /dev/nvme0, which is used by omarchy-drive-select.
+# omarchy:summary=Print drive information such as size, model, and mount details
+# omarchy:args=<drive>
 
 if (($# == 0)); then
   echo "Usage: omarchy-drive-info [/dev/drive]"

bin/omarchy-drive-password

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Set a new encryption password for a drive selected.
+# omarchy:summary=Set a new encryption password for a drive selected.
+# omarchy:requires-sudo=true
 
 encrypted_drives=$(blkid -t TYPE=crypto_LUKS -o device)
 

bin/omarchy-drive-select

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Select a drive from a list with info that includes space and brand. Used by omarchy-drive-set-password.
+# omarchy:summary=Select a drive from a list with info that includes space and brand. Used by omarchy-drive-password.
 
 if (($# == 0)); then
   drives=$(lsblk -dpno NAME | grep -E '/dev/(sd|hd|vd|nvme|mmcblk|xv)')

bin/omarchy-first-run

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Finish the installation of Omarchy with items that can only be done after logging in.
+# omarchy:summary=Finish the installation of Omarchy with items that can only be done after logging in.
+# omarchy:requires-sudo=true
 
 set -e
 
@@ -15,7 +16,10 @@ if [[ -f $FIRST_RUN_MODE ]]; then
   bash "$OMARCHY_PATH/install/first-run/firewall.sh"
   bash "$OMARCHY_PATH/install/first-run/dns-resolver.sh"
   bash "$OMARCHY_PATH/install/first-run/gnome-theme.sh"
+  bash "$OMARCHY_PATH/install/first-run/swayosd.sh"
+  bash "$OMARCHY_PATH/install/first-run/gtk-primary-paste.sh"
   bash "$OMARCHY_PATH/install/first-run/elephant.sh"
+  omarchy-hook-install post-update "$OMARCHY_PATH/install/first-run/install-voxtype.hook"
   sudo rm -f /etc/sudoers.d/first-run
 
   bash "$OMARCHY_PATH/install/first-run/welcome.sh"

bin/omarchy-font-current

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Returns the name of the current monospace font being used by extracting it from the Waybar stylesheet.
-# This can be changed using omarchy-font-set.
+# omarchy:summary=Show current monospace font
+# omarchy:examples=omarchy font current
 
 grep -oP 'font-family:\s*["'\'']?\K[^;"'\'']+' ~/.config/waybar/style.css | head -n1

bin/omarchy-font-list

@@ -1,5 +1,6 @@
 #!/bin/bash
 
-# Returns a list of all the monospace fonts available on the system that can be set using omarchy-font-set.
+# omarchy:summary=List available monospace fonts
+# omarchy:examples=omarchy font list | omarchy font set "CaskaydiaMono Nerd Font"
 
 fc-list :spacing=100 -f "%{family[0]}\n" | grep -v -i -E 'emoji|signwriting|omarchy' | sort -u

bin/omarchy-font-set

@@ -1,7 +1,8 @@
 #!/bin/bash
 
-# Set the system-wide monospace font that should be used by the terminal, hyprlock, waybar, swayosd, etc.
-# The font name must be one of the ones returned by omarchy-font-list.
+# omarchy:summary=Set the system monospace font
+# omarchy:args=<font-name>
+# omarchy:examples=omarchy font list | omarchy font set "CaskaydiaMono Nerd Font"
 
 font_name="$1"
 
@@ -21,6 +22,10 @@ if [[ -n $font_name ]]; then
       pkill -SIGUSR2 ghostty
     fi
 
+    if [[ -f ~/.config/foot/foot.ini ]]; then
+      sed -i "s/^font=.*/font=$font_name:size=9/g" ~/.config/foot/foot.ini
+    fi
+
     sed -i "s/font_family = .*/font_family = $font_name/g" ~/.config/hypr/hyprlock.conf
     sed -i "s/font-family: .*/font-family: '$font_name';/g" ~/.config/waybar/style.css
     sed -i "s/font-family: .*/font-family: '$font_name';/g" ~/.config/swayosd/style.css
@@ -36,6 +41,10 @@ if [[ -n $font_name ]]; then
       notify-send -u low "    You must restart Ghostty to see font change"
     fi
 
+    if pgrep -x foot; then
+      notify-send -u low "    You must restart Foot to see font change"
+    fi
+
     omarchy-hook font-set "$font_name"
   else
     echo "Font '$font_name' not found."

bin/omarchy-haptic-touchpad

@@ -1,94 +0,0 @@
-#!/usr/bin/env python3
-
-"""Haptic feedback daemon for Synaptics touchpads with Manual Trigger.
-
-Monitors touchpad button press events and sends haptic pulses via HID
-feature reports. Required because the kernel's HID haptic subsystem only
-supports Auto Trigger with waveform enumeration, not the simpler Manual
-Trigger protocol used by these Synaptics touchpads.
-"""
-
-import fcntl, glob, os, struct, sys
-
-VENDOR = "06CB"
-REPORT_ID = 0x37
-INTENSITY = 40  # 0-100
-
-# input_event: struct timeval (16 bytes on 64-bit) + type(H) + code(H) + value(i)
-EVENT_FORMAT = "llHHi"
-EVENT_SIZE = struct.calcsize(EVENT_FORMAT)
-EV_KEY = 0x01
-BTN_LEFT = 272
-BTN_RIGHT = 273
-BTN_MIDDLE = 274
-
-# ioctl: HIDIOCSFEATURE(len) = _IOC(_IOC_WRITE|_IOC_READ, 'H', 0x06, len)
-def HIDIOCSFEATURE(length):
-    return 0xC0000000 | (length << 16) | (ord("H") << 8) | 0x06
-
-
-def find_hidraw():
-    for path in sorted(glob.glob("/sys/class/hidraw/hidraw*")):
-        uevent = os.path.join(path, "device", "uevent")
-        try:
-            with open(uevent) as f:
-                content = f.read().upper()
-            if f"0000{VENDOR}" in content:
-                return os.path.join("/dev", os.path.basename(path))
-        except OSError:
-            continue
-    return None
-
-
-def find_touchpad_event():
-    for path in sorted(glob.glob("/sys/class/input/event*/device/name")):
-        try:
-            with open(path) as f:
-                name = f.read().strip().upper()
-            if VENDOR in name and "TOUCHPAD" in name:
-                event = path.split("/")[-3]
-                return os.path.join("/dev/input", event)
-        except OSError:
-            continue
-    return None
-
-
-def main():
-    hidraw = find_hidraw()
-    if not hidraw:
-        print("No Synaptics haptic touchpad hidraw device found", file=sys.stderr)
-        sys.exit(1)
-
-    event = find_touchpad_event()
-    if not event:
-        print("No Synaptics haptic touchpad input device found", file=sys.stderr)
-        sys.exit(1)
-
-    print(f"Haptic touchpad: hidraw={hidraw} input={event} intensity={INTENSITY}", flush=True)
-
-    haptic_report = struct.pack("BB", REPORT_ID, INTENSITY)
-    ioctl_req = HIDIOCSFEATURE(len(haptic_report))
-
-    hidraw_fd = os.open(hidraw, os.O_RDWR)
-    event_fd = os.open(event, os.O_RDONLY)
-
-    try:
-        while True:
-            data = os.read(event_fd, EVENT_SIZE)
-            if len(data) < EVENT_SIZE:
-                continue
-            _, _, ev_type, code, value = struct.unpack(EVENT_FORMAT, data)
-            if ev_type == EV_KEY and code in (BTN_LEFT, BTN_RIGHT, BTN_MIDDLE) and value == 1:
-                try:
-                    fcntl.ioctl(hidraw_fd, ioctl_req, haptic_report)
-                except OSError:
-                    pass
-    except KeyboardInterrupt:
-        pass
-    finally:
-        os.close(event_fd)
-        os.close(hidraw_fd)
-
-
-if __name__ == "__main__":
-    main()

bin/omarchy-hibernation-available

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Check if hibernation is supported
+# omarchy:summary=Check if hibernation is supported
+
 if [[ ! -f /sys/power/image_size ]]; then
   exit 1
 fi

bin/omarchy-hibernation-remove

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Removes hibernation setup: disables swap, removes swapfile, removes fstab entry,
-# removes resume hook, and removes suspend-then-hibernate configuration.
+# omarchy:summary=Remove hibernation setup including swap and boot resume settings
+# omarchy:requires-sudo=true
 
 MKINITCPIO_CONF="/etc/mkinitcpio.conf.d/omarchy_resume.conf"
 

bin/omarchy-hibernation-setup

@@ -1,14 +1,27 @@
 #!/bin/bash
 
-# Creates a swap file in the btrfs subvolume, adds the swap file to /etc/fstab,
-# adds a resume hook to mkinitcpio, and configures suspend-then-hibernate.
+# omarchy:summary=Set up hibernation with swap and boot resume configuration
+# omarchy:requires-sudo=true
+# omarchy:args=[--force] [--no-rebuild]
+
+FORCE=false
+NO_REBUILD=false
+for arg in "$@"; do
+  case "$arg" in
+    --force) FORCE=true ;;
+    --no-rebuild) NO_REBUILD=true ;;
+  esac
+done
 
 if [[ ! -f /sys/power/image_size ]]; then
   echo -e "Hibernation is not supported on your system" >&2
   exit 0
 fi
 
-if ! command -v limine-mkinitcpio &>/dev/null; then
+# When --no-rebuild is set, the caller is responsible for the UKI rebuild
+# (e.g. running before limine-mkinitcpio-hook is installed during initial
+# install), so we only require limine-mkinitcpio when we'd invoke it ourselves.
+if ! $NO_REBUILD && ! command -v limine-mkinitcpio &>/dev/null; then
   echo "Skipping hibernation setup (requires Limine bootloader)"
   exit 0
 fi
@@ -26,15 +39,14 @@ if [[ -f $MKINITCPIO_CONF ]] && grep -q "^HOOKS+=(resume)$" "$MKINITCPIO_CONF";
       echo "Fixing empty resume_offset ($RESUME_OFFSET)"
       sudo sed -i "s/resume_offset=\"$/resume_offset=$RESUME_OFFSET\"/" "$RESUME_DROP_IN"
       sudo sed -i "s/resume_offset=\"$/resume_offset=$RESUME_OFFSET\"/" /etc/default/limine
-      sudo limine-mkinitcpio
-      sudo limine-update
+      $NO_REBUILD || sudo limine-mkinitcpio
     fi
   fi
   echo "Hibernation is already set up"
   exit 0
 fi
 
-if [[ $1 != "--force" ]]; then
+if ! $FORCE; then
   MEM_TOTAL_HUMAN=$(free --human | awk '/Mem/ {print $2}')
   if ! gum confirm "Use $MEM_TOTAL_HUMAN on boot drive to make hibernation available?"; then
     exit 0
@@ -105,13 +117,16 @@ if grep -q "\[s2idle\]" /sys/power/mem_sleep 2>/dev/null; then
   fi
 fi
 
-# Regenerate initramfs and boot entry
-echo "Regenerating initramfs..."
-sudo limine-mkinitcpio
-sudo limine-update
+if ! $NO_REBUILD; then
+  # limine-mkinitcpio rebuilds initramfs/UKI for all kernels and updates the
+  # /boot/limine.conf entries via limine-entry-tool. The limine bootloader
+  # binary on the ESP doesn't change here, so we don't need limine-update
+  # (which would also re-deploy the binary and rebuild a second time).
+  echo "Regenerating initramfs..."
+  sudo limine-mkinitcpio
+  echo
+fi
 
-echo
-
-if [[ $1 != "--force" ]] && gum confirm "Reboot to enable hibernation?"; then
+if ! $FORCE && ! $NO_REBUILD && gum confirm "Reboot to enable hibernation?"; then
   omarchy-system-reboot
 fi

bin/omarchy-hook

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Run a named hook, like post-update (available in ~/.config/omarchy/hooks/post-update).
+# omarchy:summary=Run a named hook from ~/.config/omarchy/hooks/<name> and ~/.config/omarchy/hooks/<name>.d/.
+# omarchy:args=[name] [args...]
 
 set -e
 
@@ -11,8 +12,17 @@ fi
 
 HOOK=$1
 HOOK_PATH="$HOME/.config/omarchy/hooks/$1"
+HOOK_DIR="$HOOK_PATH.d"
 shift
 
 if [[ -f $HOOK_PATH ]]; then
-  bash "$HOOK_PATH" "$@"
+  bash "$HOOK_PATH" "$@" || echo "Hook failed: $HOOK_PATH"
+fi
+
+if [[ -d $HOOK_DIR ]]; then
+  for hook in "$HOOK_DIR"/*; do
+    [[ -f $hook ]] || continue
+    [[ $hook == *.sample ]] && continue
+    bash "$hook" "$@" || echo "Hook failed: $hook"
+  done
 fi

bin/omarchy-hook-install

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+# omarchy:summary=Install a hook into ~/.config/omarchy/hooks/<type>.d/
+# omarchy:group=hook
+# omarchy:name=install
+# omarchy:args=<type> <file>
+# omarchy:examples=omarchy hook install post-update ~/my-hook
+
+set -e
+
+if (( $# != 2 )); then
+  echo "Usage: omarchy-hook-install <type> <file>"
+  exit 1
+fi
+
+HOOK_TYPE=$1
+HOOK_FILE=$2
+HOOK_DIR="$HOME/.config/omarchy/hooks/$HOOK_TYPE.d"
+HOOK_NAME=$(basename "$HOOK_FILE")
+HOOK_PATH="$HOOK_DIR/$HOOK_NAME"
+
+if [[ ! -f $HOOK_FILE ]]; then
+  echo "Hook file not found: $HOOK_FILE"
+  exit 1
+fi
+
+mkdir -p "$HOOK_DIR"
+cp "$HOOK_FILE" "$HOOK_PATH"
+chmod 755 "$HOOK_PATH"
+
+echo "Installed $HOOK_TYPE hook: $HOOK_PATH"

bin/omarchy-hw-asus-expertbook-b9406

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-# Detect ASUS ExpertBook B9406 series laptops on Intel Panther Lake.
+# omarchy:summary=Detect ASUS ExpertBook B9406 series laptops on Intel Panther Lake.
 
 omarchy-hw-match "B9406" && omarchy-hw-intel-ptl

bin/omarchy-hw-asus-rog

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Detect whether the computer is an Asus ROG machine.
+# omarchy:summary=Detect whether the computer is an Asus ROG machine.
 
 [[ $(cat /sys/class/dmi/id/sys_vendor 2>/dev/null) == "ASUSTeK COMPUTER INC." ]] &&
    grep -q "ROG" /sys/class/dmi/id/product_family 2>/dev/null

bin/omarchy-hw-asus-zenbook-ux5406aa

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+# omarchy:summary=Detect ASUS Zenbook UX5406AA series laptops on Intel Panther Lake.
+
+omarchy-hw-match "ux5406aa" && omarchy-hw-intel-ptl

bin/omarchy-hw-dell-xps-haptic-touchpad

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+# omarchy:summary=Match Dell XPS systems with the Synaptics haptic touchpad.
+
+omarchy-hw-match "XPS" && [[ -e /sys/bus/i2c/devices/i2c-VEN_06CB:00 ]]

bin/omarchy-hw-dell-xps-oled

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Match Dell XPS systems with LG OLED panel on Intel Panther Lake (Xe3) GPU.
+# omarchy:summary=Match Dell XPS systems with LG OLED panel on Intel Panther Lake (Xe3) GPU.
 
 omarchy-hw-match "XPS" \
   && omarchy-hw-intel-ptl \

bin/omarchy-hw-external-monitors

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Returns true when an external monitor is physically connected.
-# Uses kernel DRM state so the result is independent of Hyprland's startup timing.
+# omarchy:summary=Returns true when an external monitor is physically connected.
 
 for status in /sys/class/drm/card*-*/status; do
   [[ "$status" == *-eDP-*/status ]] && continue

bin/omarchy-hw-framework16

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Detect whether the computer is a Framework Laptop 16.
+# omarchy:summary=Detect whether the computer is a Framework Laptop 16.
 
 [[ $(cat /sys/class/dmi/id/sys_vendor 2>/dev/null) == "Framework" ]] &&
   omarchy-hw-match "Laptop 16"

bin/omarchy-hw-hybrid-gpu

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# supergfxctl is authoritative: in Integrated mode the dGPU is unbound and
-# hidden from lspci, so the controller count would undercount on those systems.
+# omarchy:summary=Detect whether the system has an active hybrid GPU configuration
+
 if command -v supergfxctl &>/dev/null; then
   supergfxctl -s 2>/dev/null | grep -qw Hybrid
 else

bin/omarchy-hw-intel

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-# Detect whether the computer has an Intel CPU.
+# omarchy:summary=Detect whether the computer has an Intel CPU.
 
 [[ $(grep -m1 "vendor_id" /proc/cpuinfo 2>/dev/null | cut -d: -f2 | tr -d ' ') == "GenuineIntel" ]]

bin/omarchy-hw-intel-ptl

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-# Detect whether the computer has an Intel Panther Lake GPU.
+# omarchy:summary=Detect whether the computer has an Intel Panther Lake GPU.
 
 lspci | grep -iE 'vga|3d|display' | grep -qi 'panther lake'

bin/omarchy-hw-match

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Match against the computer's DMI product name or product family (case-insensitive).
-# Usage: omarchy-hw-match "XPS" or omarchy-hw-match "ThinkPad"
+# omarchy:summary=Match against the computer's DMI product name or product family (case-insensitive).
+# omarchy:args=<pattern>
 
 grep -qi "$1" /sys/class/dmi/id/product_name 2>/dev/null ||
 grep -qi "$1" /sys/class/dmi/id/product_family 2>/dev/null

bin/omarchy-hw-nvidia-gsp

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+# omarchy:summary=Detect whether the computer has an NVIDIA GPU with GSP firmware (Turing or newer).
+
+# GTX 16xx, RTX 20xx-50xx, RTX Pro, Quadro RTX, datacenter A/H/T/L series.
+lspci | grep -i 'nvidia' | grep -qE "GTX 16[0-9]{2}|RTX [2-5][0-9]{3}|RTX PRO [0-9]{4}|Quadro RTX|RTX A[0-9]{4}|A[1-9][0-9]{2}|H[1-9][0-9]{2}|T4|L[0-9]+"

bin/omarchy-hw-nvidia-without-gsp

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+# omarchy:summary=Detect whether the computer has an NVIDIA GPU without GSP firmware (Maxwell/Pascal/Volta).
+
+# GTX 9xx/10xx, GT 10xx, Quadro P/M/GV, MX series, Titan X/Xp/V, Tesla V100.
+lspci | grep -i 'nvidia' | grep -qE "GTX (9[0-9]{2}|10[0-9]{2})|GT 10[0-9]{2}|Quadro [PM][0-9]{3,4}|Quadro GV100|MX *[0-9]+|Titan (X|Xp|V)|Tesla V100"

bin/omarchy-hw-recover-internal-monitor

@@ -1,8 +1,6 @@
 #!/bin/bash
 
-# Clear the internal-monitor-disable toggle if no external display is connected.
-# Runs before the graphical session so Hyprland doesn't block on having no output
-# to render to when the user rebooted with the external unplugged.
+# omarchy:summary=Clear the internal-monitor-disable toggle if no external display is connected.
 
 TOGGLE="$HOME/.local/state/omarchy/toggles/hypr/internal-monitor-disable.conf"
 

bin/omarchy-hw-surface

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Detect whether the computer is a Microsoft Surface device.
+# omarchy:summary=Detect whether the computer is a Microsoft Surface device.
 
 [[ $(cat /sys/class/dmi/id/sys_vendor 2>/dev/null) == "Microsoft Corporation" ]] &&
   omarchy-hw-match "Surface"

bin/omarchy-hw-touchpad

@@ -1,4 +1,6 @@
 #!/bin/bash
 
+# omarchy:summary=Print the detected Hyprland touchpad or trackpad device name
+
 device=$(hyprctl devices -j | jq -r '[.mice[] | .name | select(test("touchpad|trackpad"; "i"))] | first // empty')
 [[ -n $device ]] && echo "$device"

bin/omarchy-hw-touchscreen

@@ -1,4 +1,6 @@
 #!/bin/bash
 
+# omarchy:summary=Print the detected Hyprland touchscreen or tablet device name
+
 device=$(hyprctl devices -j | jq -r '[.touch[]?.name, .tablets[]?.name] | first // empty')
 [[ -n $device ]] && echo "$device"

bin/omarchy-hw-vulkan

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Detect whether Vulkan is available.
+# omarchy:summary=Detect whether Vulkan is available.
 
 [[ -d /usr/share/vulkan/icd.d ]] &&
   find /usr/share/vulkan/icd.d -maxdepth 1 -name "*.json" -print -quit | grep -q .

bin/omarchy-hyprland-monitor-focused

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-# Print the name of the currently focused Hyprland monitor.
+# omarchy:summary=Print the name of the currently focused Hyprland monitor.
 
 hyprctl monitors -j | jq -r '.[] | select(.focused == true).name'

bin/omarchy-hyprland-monitor-focused-apple

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+# omarchy:summary=Return success if the focused Hyprland monitor is an Apple display.
+
+hyprctl monitors -j | jq -e '.[] | select(.focused == true) | select(.make == "Apple Computer Inc" and (.model | test("StudioDisplay|ProDisplayXDR|Studio XDR")))' >/dev/null

bin/omarchy-hyprland-monitor-internal

@@ -1,5 +1,8 @@
 #!/bin/bash
 
+# omarchy:summary=Enable, disable, toggle, or recover the internal laptop display
+# omarchy:args=<on|off|toggle|recover>
+
 TOGGLE="internal-monitor-disable"
 TOGGLE_FLAG="$HOME/.local/state/omarchy/toggles/hypr/$TOGGLE.conf"
 MIRROR_TOGGLE="internal-monitor-mirror"

bin/omarchy-hyprland-monitor-internal-mirror

@@ -1,5 +1,8 @@
 #!/bin/bash
 
+# omarchy:summary=Enable, disable, toggle, or recover mirroring the internal display to an external monitor
+# omarchy:args=<on|off|toggle|recover>
+
 TOGGLE="internal-monitor-mirror"
 TOGGLE_FLAG="$HOME/.local/state/omarchy/toggles/hypr/$TOGGLE.conf"
 DISABLE_TOGGLE="internal-monitor-disable"

bin/omarchy-hyprland-monitor-scaling-cycle

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Get the active monitor (the one with the cursor)
+# omarchy:summary=Cycle focused Hyprland monitor scaling through 1x, 1.25x, 1.6x, 2x, 3x, and 4x
+
 MONITOR_INFO=$(hyprctl monitors -j | jq -r '.[] | select(.focused == true)')
 ACTIVE_MONITOR=$(echo "$MONITOR_INFO" | jq -r '.name')
 CURRENT_SCALE=$(echo "$MONITOR_INFO" | jq -r '.scale')
@@ -8,8 +9,8 @@ WIDTH=$(echo "$MONITOR_INFO" | jq -r '.width')
 HEIGHT=$(echo "$MONITOR_INFO" | jq -r '.height')
 REFRESH_RATE=$(echo "$MONITOR_INFO" | jq -r '.refreshRate')
 
-# Cycle through scales: 1 → 1.25 → 1.6 → 2 → 3 → 1 (or reverse with --reverse)
-SCALES=(1 1.25 1.6 2 3)
+# Cycle through scales: 1 → 1.25 → 1.6 → 2 → 3 → 4 → 1 (or reverse with --reverse)
+SCALES=(1 1.25 1.6 2 3 4)
 
 # Find the index of the scale closest to the current one (Hyprland may
 # snap fractional scales to nearby values, so we can't match exactly)
@@ -32,4 +33,15 @@ fi
 NEW_SCALE=${SCALES[$NEW_IDX]}
 
 hyprctl keyword monitor "$ACTIVE_MONITOR,${WIDTH}x${HEIGHT}@${REFRESH_RATE},auto,$NEW_SCALE"
+
+# Persist to monitors.conf if the user has a single generic catch-all line
+# (ignoring disabled monitors), so the scale survives reboots.
+MONITOR_CONF="$HOME/.config/hypr/monitors.conf"
+if [[ -f $MONITOR_CONF ]]; then
+  mapfile -t ACTIVE_LINES < <(grep -E '^[[:space:]]*monitor=' "$MONITOR_CONF" | grep -vE 'disable[[:space:]]*$')
+  if [[ ${#ACTIVE_LINES[@]} -eq 1 ]] && [[ "${ACTIVE_LINES[0]}" =~ ^monitor=,preferred,auto, ]]; then
+    sed -i -E "s|^(monitor=,preferred,auto,).*|\\1${NEW_SCALE}|" "$MONITOR_CONF"
+  fi
+fi
+
 notify-send -u low "󰍹    Display scaling set to ${NEW_SCALE}x"

bin/omarchy-hyprland-monitor-watch

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Listen on Hyprland's event socket and recover monitor toggles whenever a
-# monitor is removed.
+# omarchy:summary=Watch Hyprland monitor events and recover monitor toggles when a monitor is removed
 
 SOCKET="$XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket2.sock"
 

bin/omarchy-hyprland-toggle

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Toggle permanent Hyprland flags by copying them into a directory that's sourced entirely.
+# omarchy:summary=Toggle permanent Hyprland flags by copying them into a directory that's sourced entirely.
+# omarchy:args=[--enabled-notification <text>] [--disabled-notification <text>] <flag-name>
 
 ENABLED_NOTIFICATION=""
 DISABLED_NOTIFICATION=""

bin/omarchy-hyprland-toggle-disabled

@@ -1,5 +1,6 @@
 #!/bin/bash
 
-# Check if a Hyprland toggle is currently disabled (missing).
+# omarchy:summary=Check if a Hyprland toggle is currently disabled (missing).
+# omarchy:args=<flag-name>
 
 [[ ! -f "$HOME/.local/state/omarchy/toggles/hypr/$1.conf" ]]

bin/omarchy-hyprland-toggle-enabled

@@ -1,5 +1,6 @@
 #!/bin/bash
 
-# Check if a Hyprland toggle is currently enabled.
+# omarchy:summary=Check if a Hyprland toggle is currently enabled.
+# omarchy:args=<flag-name>
 
 [[ -f "$HOME/.local/state/omarchy/toggles/hypr/$1.conf" ]]

bin/omarchy-hyprland-window-close-all

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Close all open windows
+# omarchy:summary=Close all open windows
+
 hyprctl clients -j | \
   jq -r ".[].address" | \
   xargs -I{} hyprctl dispatch closewindow address:{}

bin/omarchy-hyprland-window-gaps-toggle

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-# Toggles the window gaps globally between no gaps and the default.
+# omarchy:summary=Toggles the window gaps globally between no gaps and the default.
 
 omarchy-hyprland-toggle window-no-gaps

bin/omarchy-hyprland-window-pop

@@ -1,19 +1,7 @@
 #!/bin/bash
 
-# Toggle to pop-out a tile to stay fixed on a display basis.
-
-# Usage:
-# omarchy-hyprland-window-pop [width height [x y]]
-#
-# Arguments:
-#   width   Optional. Width of the floating window. Default: 1300
-#   height  Optional. Height of the floating window. Default: 900
-#   x       Optional. X position of the window. Must provide both X and Y to take effect.
-#   y       Optional. Y position of the window. Must provide both X and Y to take effect.
-#
-# Behavior:
-#   - If the window is already pinned, it will be unpinned and removed from the pop layer.
-#   - If the window is not pinned, it will be floated, resized, moved/centered, pinned, brought to top, and popped.
+# omarchy:summary=Toggle to pop-out a tile to stay fixed on a display basis.
+# omarchy:args=[width height x y]
 
 width=${1:-1300}
 height=${2:-900}

bin/omarchy-hyprland-window-single-square-aspect-toggle

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Toggle single-window square aspect ratio.
+# omarchy:summary=Toggle single-window square aspect ratio.
 
 omarchy-hyprland-toggle \
   --enabled-notification "      Enable single-window square aspect ratio" \

bin/omarchy-hyprland-window-transparency-toggle

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-# Toggles transparency for the currently focused window.
+# omarchy:summary=Toggles transparency for the currently focused window.
 
 hyprctl dispatch setprop "address:$(hyprctl activewindow -j | jq -r '.address')" opaque toggle

bin/omarchy-hyprland-workspace-layout-toggle

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Toggle the layout on the current active workspace between dwindle and scrolling
+# omarchy:summary=Toggle the layout on the current active workspace between dwindle and scrolling
 
 ACTIVE_WORKSPACE=$(hyprctl activeworkspace -j | jq -r '.id')
 CURRENT_LAYOUT=$(hyprctl activeworkspace -j | jq -r '.tiledLayout')

bin/omarchy-install-browser

@@ -0,0 +1,93 @@
+#!/bin/bash
+
+# omarchy:summary=Install a supported browser
+# omarchy:args=<chrome|brave|brave-origin|edge|firefox|zen>
+# omarchy:examples=omarchy install browser firefox | omarchy install browser brave
+
+setup_policy_directory() {
+  sudo mkdir -p "$1"
+  sudo chmod a+rw "$1"
+}
+
+announce_browser_installed() {
+  echo ""
+  echo "$1 browser installed. Make it the default via Setup > Defaults > Browser."
+}
+
+copy_chromium_flags() {
+  mkdir -p ~/.config
+  cp -f "${OMARCHY_PATH:-$HOME/.local/share/omarchy}/config/chromium-flags.conf" "$1"
+}
+
+setup_firefox_preferences() {
+  local distribution_dir="$1"
+
+  setup_policy_directory "$distribution_dir"
+  sudo cp -f "$OMARCHY_PATH/default/firefox/policies.json" "$distribution_dir/policies.json"
+}
+
+setup_firefox_wayland() {
+  mkdir -p ~/.config/environment.d
+  echo "MOZ_ENABLE_WAYLAND=1" > ~/.config/environment.d/omarchy-firefox-wayland.conf
+}
+
+case $1 in
+chrome)
+  echo "Installing Chrome..."
+  omarchy-pkg-aur-add google-chrome || exit 1
+
+  setup_policy_directory /etc/opt/chrome/policies/managed
+  copy_chromium_flags ~/.config/chrome-flags.conf
+  omarchy-theme-set-browser
+  announce_browser_installed "Chrome"
+  ;;
+edge)
+  echo "Installing Edge..."
+  omarchy-pkg-aur-add microsoft-edge-stable-bin || exit 1
+
+  setup_policy_directory /etc/opt/edge/policies/managed
+  copy_chromium_flags ~/.config/microsoft-edge-stable-flags.conf
+  omarchy-theme-set-browser
+  announce_browser_installed "Edge"
+  ;;
+brave)
+  echo "Installing Brave..."
+  omarchy-pkg-aur-add brave-bin || exit 1
+
+  setup_policy_directory /etc/brave/policies/managed
+  copy_chromium_flags ~/.config/brave-flags.conf
+  omarchy-theme-set-browser
+  announce_browser_installed "Brave"
+  ;;
+brave-origin)
+  echo "Installing Brave Origin..."
+  omarchy-pkg-aur-add brave-origin-beta-bin || exit 1
+
+  setup_policy_directory /etc/brave/policies/managed
+  mkdir -p ~/.config
+  # FIXME: Use normal chromium flags when Brave Origin wrapper has been fixed
+  echo "--load-extension=~/.local/share/omarchy/default/chromium/extensions/copy-url" > ~/.config/brave-origin-beta-flags.conf
+  omarchy-theme-set-browser
+  announce_browser_installed "Brave Origin"
+  ;;
+firefox)
+  echo "Installing Firefox..."
+  omarchy-pkg-add firefox || exit 1
+
+  setup_firefox_preferences /usr/lib/firefox/distribution
+  setup_firefox_wayland
+  announce_browser_installed "Firefox"
+  ;;
+zen)
+  echo "Installing Zen..."
+  omarchy-pkg-aur-add zen-browser-bin || exit 1
+
+  setup_firefox_preferences /opt/zen-browser/distribution
+  setup_firefox_wayland
+  announce_browser_installed "Zen"
+  ;;
+*)
+  echo "Usage: omarchy-install-browser <chrome|brave|brave-origin|edge|firefox|zen>"
+  exit 1
+  ;;
+esac

bin/omarchy-install-chromium-google-account

@@ -1,9 +1,9 @@
 #!/bin/bash
 
-# Allow Chromium to sign in to Google accounts by adding the correct
-# oauth client id and secret to ~/.config/chromium-flags.conf.
+# omarchy:summary=Allow Chromium to sign in to Google accounts by adding the required OAuth credentials
 
 if [[ -f ~/.config/chromium-flags.conf ]]; then
+  echo "Installing Chromium Google account support..."
   CONF=~/.config/chromium-flags.conf
 
   grep -qxF -- "--oauth2-client-id=77185425430.apps.googleusercontent.com" "$CONF" ||

bin/omarchy-install-dev-env

@@ -1,6 +1,10 @@
 #!/bin/bash
 
-# Install one of the supported development environments. Usually called via Install > Development > * in the Omarchy Menu.
+# omarchy:summary=Install a supported development environment
+# omarchy:name=dev-env
+# omarchy:args=<ruby|node|bun|deno|go|laravel|symfony|php|python|elixir|phoenix|rust|java|zig|ocaml|dotnet|clojure|scala>
+# omarchy:examples=omarchy install dev-env ruby | omarchy install dev-env node
+# omarchy:requires-sudo=true
 
 if [[ -z $1 ]]; then
   echo "Usage: omarchy-install-dev-env <ruby|node|bun|deno|go|laravel|symfony|php|python|elixir|phoenix|rust|java|zig|ocaml|dotnet|clojure|scala>" >&2

bin/omarchy-install-docker-dbs

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Install one of the supported databases in a Docker container with the suitable development options.
-# Usually called via Install > Development > Docker DB from the Omarchy Menu.
+# omarchy:summary=Install one of the supported databases in a Docker container with the suitable development options.
+# omarchy:requires-sudo=true
 
 options=("MySQL" "PostgreSQL" "Redis" "MongoDB" "MariaDB" "MSSQL")
 
@@ -13,6 +13,7 @@ fi
 
 if [[ -n $choices ]]; then
   for db in $choices; do
+    echo "Installing $db..."
     case $db in
     MySQL) sudo docker run -d --restart unless-stopped -p "127.0.0.1:3306:3306" --name=mysql8 -e MYSQL_ROOT_PASSWORD= -e MYSQL_ALLOW_EMPTY_PASSWORD=true mysql:8.4 ;;
     PostgreSQL) sudo docker run -d --restart unless-stopped -p "127.0.0.1:5432:5432" --name=postgres18 -e POSTGRES_HOST_AUTH_METHOD=trust postgres:18 ;;

bin/omarchy-install-dropbox

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Install and start the Dropbox service. Must then be authenticated via the web.
+# omarchy:summary=Install and start the Dropbox service. Must then be authenticated via the web.
 
 echo "Installing all dependencies..."
 omarchy-pkg-add dropbox dropbox-cli libappindicator-gtk3 python-gpgme nautilus-dropbox

bin/omarchy-install-gaming-geforce-now

@@ -1,9 +1,10 @@
 #!/bin/bash
 
-# Install and launch Geforce Now.
+# omarchy:summary=Install and launch Geforce Now.
 
 set -e
 
+echo "Installing GeForce NOW..."
 omarchy-pkg-add flatpak
 cd /tmp
 

bin/omarchy-install-gaming-gpu-lib32

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+# omarchy:summary=Install lib32 graphics drivers (Vulkan + NVIDIA) for any detected GPUs.
+# omarchy:requires-sudo=true
+
+set -e
+
+echo "Installing lib32 graphics drivers..."
+
+PACKAGES=()
+
+declare -A VULKAN_DRIVERS=(
+  [Intel]=lib32-vulkan-intel
+  [AMD]=lib32-vulkan-radeon
+)
+for vendor in "${!VULKAN_DRIVERS[@]}"; do
+  if lspci | grep -iE "(VGA|Display).*$vendor" >/dev/null; then
+    PACKAGES+=("${VULKAN_DRIVERS[$vendor]}")
+  fi
+done
+
+if omarchy-hw-nvidia-gsp; then
+  PACKAGES+=(lib32-nvidia-utils)
+elif omarchy-hw-nvidia-without-gsp; then
+  PACKAGES+=(lib32-nvidia-580xx-utils)
+fi
+
+[[ ${#PACKAGES[@]} -gt 0 ]] && omarchy-pkg-add "${PACKAGES[@]}"

bin/omarchy-install-gaming-heroic

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+# omarchy:summary=Install Heroic Games Launcher (Epic, GOG, Amazon Prime Gaming) with graphics drivers.
+# omarchy:requires-sudo=true
+
+set -e
+
+echo "Installing Heroic Games Launcher..."
+omarchy-pkg-add heroic-games-launcher-bin
+omarchy-install-gaming-gpu-lib32
+
+setsid gtk-launch heroic >/dev/null 2>&1 &

bin/omarchy-install-gaming-lutris

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+# omarchy:summary=Install Lutris with Wine + DXVK for running Windows games (Battle.net, EA, Ubisoft Connect, etc.)
+# omarchy:requires-sudo=true
+
+set -e
+
+echo "Installing Lutris..."
+omarchy-pkg-add lutris umu-launcher wine-staging wine-mono wine-gecko winetricks python-protobuf
+omarchy-install-gaming-gpu-lib32
+
+# Lutris ships with `#!/usr/bin/env python3`, which resolves to mise's Python and
+# fails to import the lutris module. Pin the shebang to the system Python.
+sudo sed -i '/env python3/ c\#!/bin/python3' /usr/bin/lutris
+
+cat <<'EOF'
+
+Lutris will open and auto-fetch its DXVK and VKD3D runtimes in the background
+(watch the bottom status bar). Once that finishes, click the + to add or install games.
+
+EOF
+
+setsid lutris >/dev/null 2>&1 &

bin/omarchy-install-gaming-moonlight

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+# omarchy:summary=Install Moonlight (NVIDIA GameStream / Sunshine client) for streaming games to this PC.
+# omarchy:requires-sudo=true
+
+set -e
+
+echo "Installing Moonlight..."
+omarchy-pkg-add moonlight-qt
+
+setsid gtk-launch com.moonlight_stream.Moonlight.desktop >/dev/null 2>&1 &

bin/omarchy-install-gaming-retroarch

@@ -0,0 +1,85 @@
+#!/bin/bash
+
+# omarchy:summary=Install RetroArch with the full libretro core set plus FBNeo and a ~/Games ROM directory.
+
+set -e
+
+echo "Installing RetroArch..."
+omarchy-pkg-add \
+  retroarch \
+  retroarch-assets-glui retroarch-assets-ozone retroarch-assets-xmb \
+  libretro-beetle-pce libretro-beetle-pce-fast libretro-beetle-psx libretro-beetle-psx-hw libretro-beetle-supergrafx \
+  libretro-blastem \
+  libretro-bsnes libretro-bsnes-hd libretro-bsnes2014 \
+  libretro-core-info \
+  libretro-desmume libretro-dolphin libretro-flycast \
+  libretro-gambatte libretro-genesis-plus-gx \
+  libretro-kronos \
+  libretro-mame libretro-mame2016 libretro-melonds libretro-mesen libretro-mesen-s libretro-mgba libretro-mupen64plus-next \
+  libretro-nestopia \
+  libretro-overlays \
+  libretro-parallel-n64 libretro-picodrive libretro-play libretro-ppsspp \
+  libretro-sameboy libretro-scummvm libretro-shaders-slang libretro-snes9x \
+  libretro-yabause \
+  libretro-cap32-git libretro-fbneo-git libretro-uae-git \
+  libretro-vice-x128-git libretro-vice-x64-git libretro-vice-x64dtv-git libretro-vice-x64sc-git \
+  libretro-vice-xcbm2-git libretro-vice-xcbm5x0-git libretro-vice-xpet-git \
+  libretro-vice-xplus4-git libretro-vice-xscpu64-git libretro-vice-xvic-git \
+  libretro-database-git \
+  retroarch-joypad-autoconfig-git
+
+# Set up ~/Games for BIOS files and ROMs
+mkdir -p "$HOME/Games/bios" "$HOME/Games/roms"
+
+CFG="$HOME/.config/retroarch/retroarch.cfg"
+mkdir -p "$(dirname "$CFG")"
+touch "$CFG"
+
+set_cfg() {
+  local key=$1 value=$2
+  if grep -q "^$key = " "$CFG"; then
+    sed -i "s|^$key = .*|$key = \"$value\"|" "$CFG"
+  else
+    echo "$key = \"$value\"" >>"$CFG"
+  fi
+}
+
+set_cfg rgui_browser_directory "$HOME/Games/roms"
+set_cfg system_directory "$HOME/Games/bios"
+
+# Point at the cores and assets installed by pacman
+set_cfg libretro_directory "/usr/lib/libretro"
+set_cfg libretro_info_path "/usr/share/libretro/info"
+set_cfg overlay_directory "/usr/share/libretro/overlays"
+set_cfg osk_overlay_directory "/usr/share/libretro/overlays/keyboards"
+set_cfg video_shader_dir "/usr/share/libretro/shaders/shaders_slang"
+set_cfg joypad_autoconfig_dir "/usr/share/libretro/autoconfig"
+
+# Point at the database, cheats, and cursors from libretro-database-git
+set_cfg content_database_path "/usr/share/libretro/database/rdb"
+set_cfg cheat_database_path "/usr/share/libretro/database/cht"
+set_cfg cursor_directory "/usr/share/libretro/database/cursors"
+
+# Vulkan is required for slang shaders and unlocks hardware renderers in beetle-psx-hw, parallel-n64, dolphin
+set_cfg video_driver "vulkan"
+
+# XMB is the classic PS3-style menu (vs. ozone/rgui/glui)
+set_cfg menu_driver "xmb"
+
+# Default to crt-royale shader for that classic CRT look. The global preset is
+# auto-loaded by RetroArch when auto_shaders_enable is true and no per-core/per-game
+# preset takes precedence — setting video_shader alone in retroarch.cfg is not enough.
+set_cfg video_shader_enable "true"
+set_cfg auto_shaders_enable "true"
+mkdir -p ~/.config/retroarch/config
+echo '#reference "/usr/share/libretro/shaders/shaders_slang/crt/crt-royale.slangp"' \
+  > ~/.config/retroarch/config/global.slangp
+
+# Hide Images and Video tabs in the main menu sidebar
+set_cfg content_show_images "false"
+set_cfg content_show_video "false"
+
+echo ""
+echo "Put your roms and bios files in ~/Games. Then start RetroArch from the app launcher (Super + Space)."
+
+setsid nautilus "$HOME/Games" >/dev/null 2>&1 &

bin/omarchy-install-gaming-steam

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+# omarchy:summary=Install Steam and graphics drivers selected for this system
+# omarchy:requires-sudo=true
+
+set -e
+
+echo "Installing Steam..."
+omarchy-pkg-add steam
+omarchy-install-gaming-gpu-lib32
+
+echo ""
+echo "Steam will start automatically now. This might take a while..."
+
+setsid gtk-launch steam >/dev/null 2>&1 &

bin/omarchy-install-gaming-xbox-cloud

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+# omarchy:summary=Install Xbox Cloud Gaming as a web app and launch it.
+
+set -e
+
+echo "Installing Xbox Cloud Gaming..."
+omarchy-webapp-install "Xbox Cloud Gaming" "https://www.xbox.com/en-US/play" "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/xbox.png"
+
+setsid omarchy-launch-webapp "https://www.xbox.com/en-US/play" >/dev/null 2>&1 &

bin/omarchy-install-gaming-xbox-controllers

@@ -0,0 +1,37 @@
+#!/bin/bash
+
+# omarchy:summary=Install support for using Xbox controllers with Steam/RetroArch/etc.
+# omarchy:requires-sudo=true
+
+set -e
+
+echo "Installing Xbox controller Bluetooth support..."
+
+# Install xpadneo to ensure controllers work out of the box
+omarchy-pkg-add linux-headers xpadneo-dkms
+
+# Prevent xpad/xpadneo driver conflict
+echo blacklist xpad | sudo tee /etc/modprobe.d/blacklist-xpad.conf >/dev/null
+echo hid_xpadneo | sudo tee /etc/modules-load.d/xpadneo.conf >/dev/null
+
+# Ensure user is in the input group (controllers need it)
+needs_reboot=false
+if ! id -nG "$USER" | grep -qw input; then
+  sudo usermod -aG input "$USER"
+  needs_reboot=true
+fi
+
+# Swap drivers in the running kernel so a reboot isn't needed otherwise
+if lsmod | grep -q '^xpad '; then
+  sudo modprobe -r xpad 2>/dev/null || needs_reboot=true
+fi
+
+if $needs_reboot; then
+  gum confirm "Reboot needed to finish setup. Reboot now?" && sudo reboot now
+  exit 0
+fi
+
+sudo modprobe hid_xpadneo
+
+echo ""
+echo "Now you can pair your Xbox controller with Bluetooth using Super + Ctrl + B."

bin/omarchy-install-helix

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+# omarchy:summary=Install Helix and configure it to use the current Omarchy theme
+
+echo "Installing Helix..."
+omarchy-pkg-add helix
+
+mkdir -p ~/.config/helix/themes
+
+# Symlink the rendered Omarchy theme so Helix tracks the active theme
+ln -sf ~/.config/omarchy/current/theme/helix.toml ~/.config/helix/themes/omarchy.toml
+
+# Only seed a config.toml if the user does not already have one
+if [[ ! -f ~/.config/helix/config.toml ]]; then
+  cat >~/.config/helix/config.toml <<'EOF'
+theme = "omarchy"
+EOF
+fi
+
+# Ensure the symlink target exists for users whose current theme predates this template
+if [[ ! -e ~/.config/omarchy/current/theme/helix.toml ]]; then
+  omarchy-theme-refresh
+fi
+
+# Arch-based distros ship Helix as 'helix' rather than the upstream 'hx'.
+if ! grep -q '^alias hx="helix"' ~/.bashrc 2>/dev/null; then
+  echo 'alias hx="helix"' >>~/.bashrc
+fi

bin/omarchy-install-nordvpn

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Install the NordVPN service with optional GUI.
+# omarchy:summary=Install the NordVPN service with optional GUI.
+# omarchy:requires-sudo=true
 
 echo "Installing NordVPN..."
 omarchy-pkg-aur-add nordvpn-bin