Completion should not include --help

The unified `omarchy` dispatcher is the user-facing entry point

AGENTS.md

@@ -0,0 +1,68 @@
+# Style
+
+- Two spaces for indentation, no tabs
+- Use bash 5 conditionals: use `[[ ]]` for string/file tests and `(( ))` for numeric tests
+- In `[[ ]]`, don't quote variables, but do quote string literals when comparing values (e.g., `[[ $branch == "dev" ]]`)
+- 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`)
+
+# Command Naming
+
+All commands start with `omarchy-`. Prefixes indicate purpose:
+
+- `cmd-` - check if commands exist, misc utility commands
+- `capture-` - screenshots, screen recordings, and other capture tools
+- `pkg-` - package management helpers
+- `hw-` - hardware detection (return exit codes for use in conditionals)
+- `refresh-` - copy default config to user's `~/.config/`
+- `restart-` - restart a component
+- `launch-` - open applications
+- `install-` - install optional software
+- `setup-` - interactive setup wizards
+- `toggle-` - toggle features on/off
+- `theme-` - theme management
+- `update-` - update components
+
+# Helper Commands
+
+Use these instead of raw shell commands:
+
+- `omarchy-cmd-missing` / `omarchy-cmd-present` - check for commands
+- `omarchy-pkg-missing` / `omarchy-pkg-present` - check for packages
+- `omarchy-pkg-add` - install packages (handles both pacman and AUR)
+- `omarchy-hw-asus-rog` - detect ASUS ROG hardware (and similar `hw-*` commands)
+
+# 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)
+
+# Refresh Pattern
+
+To copy a default config to user config with automatic backup:
+
+```bash
+omarchy-refresh-config hypr/hyprlock.conf
+```
+
+This copies `~/.local/share/omarchy/config/hypr/hyprlock.conf` to `~/.config/hypr/hyprlock.conf`.
+
+# Migrations
+
+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:
+- No shebang line
+- Start with an `echo` describing what the migration does
+- Use `$OMARCHY_PATH` to reference the omarchy directory
+
+Example:
+```bash
+echo "Disable fingerprint in hyprlock if fingerprint auth is not configured"
+
+if omarchy-cmd-missing fprintd-list || ! fprintd-list "$USER" 2>/dev/null | grep -q "finger"; then
+  sed -i 's/fingerprint:enabled = .*/fingerprint:enabled = false/' ~/.config/hypr/hyprlock.conf
+fi
+```

applications/Alacritty.desktop

@@ -0,0 +1,21 @@
+[Desktop Entry]
+Type=Application
+TryExec=alacritty
+Exec=alacritty
+Icon=Alacritty
+Terminal=false
+Categories=System;TerminalEmulator;
+Name=Alacritty
+GenericName=Terminal
+Comment=A fast, cross-platform, OpenGL terminal emulator
+StartupNotify=true
+StartupWMClass=Alacritty
+Actions=New;
+X-TerminalArgExec=-e
+X-TerminalArgAppId=--class=
+X-TerminalArgTitle=--title=
+X-TerminalArgDir=--working-directory=
+
+[Desktop Action New]
+Name=New Terminal
+Exec=alacritty

applications/hidden/limine-snapper-restore.desktop

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

applications/hidden/lstopo.desktop

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

applications/hidden/wiremix.desktop

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

bin/omarchy-ac-present

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+# 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
+done
+
+exit 1

bin/omarchy-audio-input-mute

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+# omarchy:summary=Toggle microphone mute. Dell XPS and ThinkPad systems get special handling for the hardware LED.
+
+if omarchy-hw-match "XPS"; then
+  omarchy-audio-input-mute-xps
+elif omarchy-hw-match "ThinkPad"; then
+  omarchy-audio-input-mute-thinkpad
+else
+  omarchy-swayosd-client --input-volume mute-toggle
+fi

bin/omarchy-audio-input-mute-thinkpad

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+# omarchy:summary=Toggle microphone mute on ThinkPad systems. Uses wpctl for reliable toggling
+
+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

@@ -0,0 +1,42 @@
+#!/bin/bash
+
+# omarchy:summary=Toggle microphone mute on Dell XPS systems. Uses wpctl for reliable toggling
+
+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

@@ -0,0 +1,62 @@
+#!/bin/bash
+
+# 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')
+
+if (( sinks_count == 0 )); then
+  omarchy-swayosd-client --custom-message "No audio devices found"
+  exit 1
+fi
+
+current_sink_name=$(pactl get-default-sink)
+current_sink_index=$(echo "$sinks" | jq -r --arg name "$current_sink_name" 'map(.name) | index($name)')
+
+if [[ $current_sink_index != "null" ]]; then
+  next_sink_index=$(((current_sink_index + 1) % sinks_count))
+else
+  next_sink_index=0
+fi
+
+next_sink=$(echo "$sinks" | jq -r ".[$next_sink_index]")
+next_sink_name=$(echo "$next_sink" | jq -r '.name')
+
+next_sink_description=$(echo "$next_sink" | jq -r '.description')
+if [[ $next_sink_description == "(null)" ]] || [[ $next_sink_description == "null" ]] || [[ -z $next_sink_description ]]; then
+  # For Bluetooth devices, the friendly name is on the Device entry (device.id), not the Sink entry (object.id)
+  device_id=$(echo "$next_sink" | jq -r '.properties."device.id"')
+  if [[ $device_id != "null" ]] && [[ -n $device_id ]]; then
+    next_sink_description=$(wpctl status | grep -E "^\s*│?\s+${device_id}\." | sed -E 's/^.*[0-9]+\.\s+//' | sed -E 's/\s+\[.*$//')
+  fi
+  # Fall back to object.id lookup if device.id didn't yield a result
+  if [[ -z $next_sink_description ]]; then
+    sink_id=$(echo "$next_sink" | jq -r '.properties."object.id"')
+    next_sink_description=$(wpctl status | grep -E "\s+\*?\s+${sink_id}\." | sed -E 's/^.*[0-9]+\.\s+//' | sed -E 's/\s+\[.*$//')
+  fi
+fi
+
+next_sink_volume=$(echo "$next_sink" | jq -r \
+  '.volume | to_entries[0].value.value_percent | sub("%"; "")')
+next_sink_is_muted=$(echo "$next_sink" | jq -r '.mute')
+
+if [[ $next_sink_is_muted = "true" ]] || (( next_sink_volume == 0 )); then
+  icon_state="muted"
+elif (( next_sink_volume <= 33 )); then
+  icon_state="low"
+elif (( next_sink_volume <= 66 )); then
+  icon_state="medium"
+else
+  icon_state="high"
+fi
+
+next_sink_volume_icon="sink-volume-${icon_state}-symbolic"
+
+if [[ $next_sink_name != $current_sink_name ]]; then
+  next_sink_wpid=$(echo "$next_sink" | jq -r '.properties."object.id"')
+  wpctl set-default "$next_sink_wpid"
+fi
+
+omarchy-swayosd-client \
+  --custom-message "$next_sink_description" \
+  --custom-icon "$next_sink_volume_icon"

bin/omarchy-battery-capacity

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+# omarchy:summary=Returns the battery full capacity in Wh (rounded to whole number).
+
+battery_info=$(upower -i $(upower -e | grep BAT))
+
+echo "$battery_info" | awk '/energy-full:/ {
+    printf "%d", $2
+    exit
+}'

bin/omarchy-battery-monitor

@@ -1,6 +1,6 @@
 #!/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
 
 BATTERY_THRESHOLD=10
 NOTIFICATION_FLAG="/run/user/$UID/omarchy_battery_notified"
@@ -9,10 +9,11 @@ BATTERY_STATE=$(upower -i $(upower -e | grep 'BAT') | grep -E "state" | awk '{pr
 
 send_notification() {
   notify-send -u critical "󱐋 Time to recharge!" "Battery is down to ${1}%" -i battery-caution -t 30000
+  omarchy-hook battery-low "$1"
 }
 
-if [[ -n "$BATTERY_LEVEL" && "$BATTERY_LEVEL" =~ ^[0-9]+$ ]]; then
-  if [[ $BATTERY_STATE == "discharging" && $BATTERY_LEVEL -le $BATTERY_THRESHOLD ]]; then
+if [[ -n $BATTERY_LEVEL && $BATTERY_LEVEL =~ ^[0-9]+$ ]]; then
+  if [[ $BATTERY_STATE == "discharging" ]] && (( BATTERY_LEVEL <= BATTERY_THRESHOLD )); then
     if [[ ! -f $NOTIFICATION_FLAG ]]; then
       send_notification $BATTERY_LEVEL
       touch $NOTIFICATION_FLAG

bin/omarchy-battery-present

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+# omarchy:summary=Returns true if a battery is present on the system.
+
+for bat in /sys/class/power_supply/BAT*; do
+  [[ -r $bat/present ]] &&
+  [[ $(cat $bat/present) == "1" ]] &&
+  [[ $(cat $bat/type) == "Battery" ]] &&
+  exit 0
+done
+
+exit 1

bin/omarchy-battery-remaining

@@ -1,12 +1,8 @@
 #!/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 -F: '/percentage/ {
-    gsub(/[%[:space:]]/, "", $2);
-    val=$2;
-    printf("%d\n", (val+0.5))
+upower -i $(upower -e | grep BAT) | awk '/percentage/ { 
+    print int($2)
     exit
-  }'
+}'

bin/omarchy-battery-remaining-time

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+# omarchy:summary=Returns the battery time remaining (to empty or full) in a compact format.
+
+battery_info=$(upower -i $(upower -e | grep BAT))
+
+echo "$battery_info" | awk '/time to (empty|full)/ {
+    value = $4
+    unit = $5
+    if (unit ~ /^minute/) {
+        printf "%dm", int(value)
+    } else {
+        hours = int(value)
+        minutes = int((value - hours) * 60)
+        if (minutes > 0) {
+            printf "%dh %dm", hours, minutes
+        } else {
+            printf "%dh", hours
+        }
+    }
+    exit
+}'

bin/omarchy-battery-status

@@ -0,0 +1,27 @@
+#!/bin/bash
+
+# omarchy:summary=Returns a formatted battery status string with percentage and power draw/charge.
+
+battery_info=$(upower -i $(upower -e | grep BAT))
+
+percentage=$(echo "$battery_info" | awk '/percentage/ {
+    print int($2)
+    exit
+}')
+
+power_rate=$(echo "$battery_info" | awk '/energy-rate/ {
+    rounded = sprintf("%.1f", $2)
+    sub(/\.0$/, "", rounded)
+    print rounded
+    exit
+}')
+
+state=$(echo "$battery_info" | awk '/state/ { print $2; exit }')
+time_remaining=$(omarchy-battery-remaining-time)
+capacity=$(omarchy-battery-capacity)
+
+if [[ $state == "charging" ]]; then
+    echo "󰁹    Battery ${percentage}%  ·  ${time_remaining} to full  ·   ${power_rate}W / ${capacity}Wh"
+else
+    echo "󰁹    Battery ${percentage}%  ·  ${time_remaining} left  ·   ${power_rate}W / ${capacity}Wh"
+fi

bin/omarchy-branch-set

@@ -1,16 +1,18 @@
 #!/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|dev]"
+  echo "Usage: omarchy-branch-set [master|rc|dev]"
   exit 1
 else
   branch="$1"
 fi
 
-case "$branch" in
-  "master") git -C $OMARCHY_PATH switch master ;;
-  "dev") git -C $OMARCHY_PATH switch dev ;;
-  *) echo "Unknown branch: $branch"; exit 1; ;;
-esac
+if [[ $branch != "master" && $branch != "rc" && $branch != "dev" ]]; then
+  echo "Error: Invalid branch '$branch'. Must be one of: master, rc, dev"
+  exit 1
+fi
+
+git -C $OMARCHY_PATH switch $branch

bin/omarchy-brightness-display

@@ -0,0 +1,46 @@
+#!/bin/bash
+
+# omarchy:summary=Adjust brightness on the most likely display device.
+# omarchy:args=<step>
+
+step="${1:-+5%}"
+
+# Start with the first possible output, then refine to the most likely given an order heuristic.
+device="$(ls -1 /sys/class/backlight 2>/dev/null | head -n1)"
+for candidate in amdgpu_bl* intel_backlight acpi_video*; do
+  if [[ -e /sys/class/backlight/$candidate ]]; then
+    device="$candidate"
+    break
+  fi
+done
+
+# Current brightness percentage
+current=$(brightnessctl -d "$device" -m | cut -d',' -f4 | tr -d '%')
+
+# Apply non-uniform step size: 1% steps if at or below 5%, otherwise set an
+# absolute target percentage to avoid raw backlight rounding causing uneven OSD steps.
+if [[ $step == "+5%" ]]; then
+  if (( current < 5 )); then
+    (( target = current + 1 ))
+  else
+    (( target = current + 5 ))
+  fi
+
+  (( target > 100 )) && target=100
+  step="$target%"
+elif [[ $step == "5%-" ]]; then
+  if (( current <= 5 )); then
+    (( target = current - 1 ))
+  else
+    (( target = current - 5 ))
+  fi
+
+  (( target < 1 )) && target=1
+  step="$target%"
+fi
+
+# Set the actual brightness of the display device.
+brightnessctl -d "$device" set "$step" >/dev/null
+
+# Use SwayOSD to display the new brightness setting.
+omarchy-swayosd-brightness "$(brightnessctl -d "$device" -m | cut -d',' -f4 | tr -d '%')"

bin/omarchy-brightness-display-apple

@@ -1,8 +1,9 @@
 #!/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:requires-sudo=true
 
-if [[ $# -eq 0 ]]; then
+if (( $# == 0 )); then
   echo "Adjust Apple Display Brightness by passing +5000 or -5000 (or any range from 0-60000)"
 else
   device="$(sudo asdcontrol --detect /dev/usb/hiddev* | grep ^/dev/usb/hiddev | cut -d: -f1)"

bin/omarchy-brightness-keyboard

@@ -0,0 +1,47 @@
+#!/bin/bash
+
+# omarchy:summary=Adjust keyboard backlight brightness using available steps.
+# omarchy:args=<up|down|cycle>
+
+direction="${1:-up}"
+
+# Find keyboard backlight device (look for *kbd_backlight* pattern in leds class).
+device=""
+for candidate in /sys/class/leds/*kbd_backlight*; do
+  if [[ -e $candidate ]]; then
+    device="$(basename "$candidate")"
+    break
+  fi
+done
+
+if [[ -z $device ]]; then
+  echo "No keyboard backlight device found" >&2
+  exit 1
+fi
+
+# Get current and max brightness to determine step size.
+max_brightness="$(brightnessctl -d "$device" max)"
+current_brightness="$(brightnessctl -d "$device" get)"
+
+# Calculate step as 10% of max brightness. Keyboards with many levels (e.g. 512)
+# need larger steps; keyboards with few levels (e.g. 3) fall back to step=1.
+step=$(( max_brightness / 10 ))
+(( step < 1 )) && step=1
+
+if [[ $direction == "cycle" ]]; then
+  new_brightness=$(( current_brightness + step ))
+  (( new_brightness > max_brightness )) && new_brightness=0
+elif [[ $direction == "up" ]]; then
+  new_brightness=$(( current_brightness + step ))
+  (( new_brightness > max_brightness )) && new_brightness=$max_brightness
+else
+  new_brightness=$(( current_brightness - step ))
+  (( new_brightness < 0 )) && new_brightness=0
+fi
+
+# Set the new brightness.
+brightnessctl -d "$device" set "$new_brightness" >/dev/null
+
+# Use SwayOSD to display the new brightness setting.
+percent=$((new_brightness * 100 / max_brightness))
+omarchy-swayosd-kbd-brightness "$percent"

bin/omarchy-capture-screenrecording

@@ -0,0 +1,197 @@
+#!/bin/bash
+
+# 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
+
+[[ -f ~/.config/user-dirs.dirs ]] && source ~/.config/user-dirs.dirs
+OUTPUT_DIR="${OMARCHY_SCREENRECORD_DIR:-${XDG_VIDEOS_DIR:-$HOME/Videos}}"
+
+if [[ ! -d $OUTPUT_DIR ]]; then
+  notify-send "Screen recording directory does not exist: $OUTPUT_DIR" -u critical -t 3000
+  exit 1
+fi
+
+DESKTOP_AUDIO="false"
+MICROPHONE_AUDIO="false"
+WEBCAM="false"
+WEBCAM_DEVICE=""
+RESOLUTION=""
+STOP_RECORDING="false"
+RECORDING_FILE="/tmp/omarchy-screenrecord-filename"
+
+for arg in "$@"; do
+  case "$arg" in
+  --with-desktop-audio) DESKTOP_AUDIO="true" ;;
+  --with-microphone-audio) MICROPHONE_AUDIO="true" ;;
+  --with-webcam) WEBCAM="true" ;;
+  --webcam-device=*) WEBCAM_DEVICE="${arg#*=}" ;;
+  --resolution=*) RESOLUTION="${arg#*=}" ;;
+  --stop-recording) STOP_RECORDING="true" ;;
+  esac
+done
+
+start_webcam_overlay() {
+  cleanup_webcam
+
+  # Auto-detect first available webcam if none specified
+  if [[ -z $WEBCAM_DEVICE ]]; then
+    WEBCAM_DEVICE=$(v4l2-ctl --list-devices 2>/dev/null | grep -m1 "^[[:space:]]*/dev/video" | tr -d '\t')
+    if [[ -z $WEBCAM_DEVICE ]]; then
+      notify-send "No webcam devices found" -u critical -t 3000
+      return 1
+    fi
+  fi
+
+  # Get monitor scale
+  local scale=$(hyprctl monitors -j | jq -r '.[] | select(.focused == true) | .scale')
+
+  # Target width (base 360px, scaled to monitor)
+  local target_width=$(awk "BEGIN {printf \"%.0f\", 360 * $scale}")
+
+  # Try preferred 16:9 resolutions in order, use first available
+  local preferred_resolutions=("640x360" "1280x720" "1920x1080")
+  local video_size_arg=""
+  local available_formats=$(v4l2-ctl --list-formats-ext -d "$WEBCAM_DEVICE" 2>/dev/null)
+
+  for resolution in "${preferred_resolutions[@]}"; do
+    if echo "$available_formats" | grep -q "$resolution"; then
+      video_size_arg="-video_size $resolution"
+      break
+    fi
+  done
+
+  ffplay -f v4l2 $video_size_arg -framerate 30 "$WEBCAM_DEVICE" \
+    -vf "crop=iw/2:ih,scale=${target_width}:-1" \
+    -window_title "WebcamOverlay" \
+    -noborder \
+    -fflags nobuffer -flags low_delay \
+    -probesize 32 -analyzeduration 0 \
+    -loglevel quiet &
+  sleep 1
+}
+
+cleanup_webcam() {
+  pkill -f "WebcamOverlay" 2>/dev/null
+}
+
+default_resolution() {
+  local width height
+  read -r width height < <(hyprctl monitors -j | jq -r '.[] | select(.focused == true) | "\(.width) \(.height)"')
+  if ((width > 3840 || height > 2160)); then
+    echo "3840x2160"
+  else
+    echo "0x0"
+  fi
+}
+
+start_screenrecording() {
+  local filename="$OUTPUT_DIR/screenrecording-$(date +'%Y-%m-%d_%H-%M-%S').mp4"
+  local audio_devices=""
+  local audio_args=()
+
+  [[ $DESKTOP_AUDIO == "true" ]] && audio_devices+="default_output"
+
+  if [[ $MICROPHONE_AUDIO == "true" ]]; then
+    # Merge audio tracks into one - separate tracks only play one at a time in most players
+    [[ -n $audio_devices ]] && audio_devices+="|"
+    audio_devices+="default_input"
+  fi
+
+  [[ -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[@]}" &
+  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
+
+  if kill -0 $pid 2>/dev/null; then
+    echo "$filename" >"$RECORDING_FILE"
+    toggle_screenrecording_indicator
+  fi
+}
+
+stop_screenrecording() {
+  pkill -SIGINT -f "^gpu-screen-recorder" # SIGINT required to save video properly
+
+  # Wait a maximum of 5 seconds to finish before hard killing
+  local count=0
+  while pgrep -f "^gpu-screen-recorder" >/dev/null && ((count < 50)); do
+    sleep 0.1
+    count=$((count + 1))
+  done
+
+  toggle_screenrecording_indicator
+  cleanup_webcam
+
+  if pgrep -f "^gpu-screen-recorder" >/dev/null; then
+    pkill -9 -f "^gpu-screen-recorder"
+    notify-send "Screen recording error" "Recording process had to be force-killed. Video may be corrupted." -u critical -t 5000
+  else
+    finalize_recording
+    local filename=$(cat "$RECORDING_FILE" 2>/dev/null)
+    local preview="${filename%.mp4}-preview.png"
+
+    # Generate a preview thumbnail from the first frame
+    ffmpeg -y -i "$filename" -ss 00:00:00.1 -vframes 1 -q:v 2 "$preview" -loglevel quiet 2>/dev/null
+
+    (
+      ACTION=$(notify-send "Screen recording saved" "Open with Super + Alt + , (or click this)" -t 10000 -i "${preview:-$filename}" -A "default=open")
+      [[ $ACTION == "default" ]] && mpv "$filename"
+      rm -f "$preview"
+    ) &
+  fi
+
+  rm -f "$RECORDING_FILE"
+}
+
+toggle_screenrecording_indicator() {
+  pkill -RTMIN+8 waybar
+}
+
+screenrecording_active() {
+  pgrep -f "^gpu-screen-recorder" >/dev/null
+}
+
+finalize_recording() {
+  local latest
+  latest=$(cat "$RECORDING_FILE" 2>/dev/null)
+  [[ -f $latest ]] || return
+
+  # Re-encode only when the first GOP contains discardable warmup packets — stream copy can't
+  # trim those (it rewinds to the keyframe). Clean recordings stay on the fast stream-copy path.
+  local video_codec=(-c:v copy)
+  if ffprobe -v error -select_streams v:0 -read_intervals %+0.2 -show_entries packet=flags -of csv=p=0 "$latest" 2>/dev/null | grep -q D; then
+    video_codec=(-c:v libx264 -preset veryfast -crf 20)
+  fi
+
+  # 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)
+  fi
+
+  local processed="${latest%.mp4}-processed.mp4"
+  if ffmpeg "${args[@]}" "$processed" -loglevel quiet 2>/dev/null; then
+    mv "$processed" "$latest"
+  else
+    rm -f "$processed"
+  fi
+}
+
+if screenrecording_active; then
+  stop_screenrecording
+elif [[ $STOP_RECORDING == "true" ]]; then
+  exit 1
+else
+  [[ $WEBCAM == "true" ]] && start_webcam_overlay
+
+  start_screenrecording || cleanup_webcam
+fi

bin/omarchy-capture-screenshot

@@ -0,0 +1,139 @@
+#!/bin/bash
+
+# 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
+
+[[ -f ~/.config/user-dirs.dirs ]] && source ~/.config/user-dirs.dirs
+OUTPUT_DIR="${OMARCHY_SCREENSHOT_DIR:-${XDG_PICTURES_DIR:-$HOME/Pictures}}"
+
+if [[ ! -d $OUTPUT_DIR ]]; then
+  mkdir -p "$OUTPUT_DIR"
+  notify-send "Created screenshot directory: $OUTPUT_DIR" -u normal -t 2000
+fi
+
+pkill slurp && exit 0
+
+SCREENSHOT_EDITOR="${OMARCHY_SCREENSHOT_EDITOR:-satty}"
+
+# Parse --editor flag from any position
+ARGS=()
+for arg in "$@"; do
+  if [[ $arg == --editor=* ]]; then
+    SCREENSHOT_EDITOR="${arg#--editor=}"
+  else
+    ARGS+=("$arg")
+  fi
+done
+set -- "${ARGS[@]}"
+
+open_editor() {
+  local filepath="$1"
+  if [[ $SCREENSHOT_EDITOR == "satty" ]]; then
+    satty --filename "$filepath" \
+      --output-filename "$filepath" \
+      --actions-on-enter save-to-clipboard \
+      --save-after-copy \
+      --copy-command 'wl-copy'
+  else
+    $SCREENSHOT_EDITOR "$filepath"
+  fi
+}
+
+MODE="${1:-smart}"
+PROCESSING="${2:-slurp}"
+
+# accounting for portrait/transformed displays
+JQ_MONITOR_GEO='
+  def format_geo:
+    .x as $x | .y as $y |
+    (.width / .scale | floor) as $w |
+    (.height / .scale | floor) as $h |
+    .transform as $t |
+    if $t == 1 or $t == 3 then
+      "\($x),\($y) \($h)x\($w)"
+    else
+      "\($x),\($y) \($w)x\($h)"
+    end;
+'
+
+get_rectangles() {
+  local active_workspace=$(hyprctl monitors -j | jq -r '.[] | select(.focused == true) | .activeWorkspace.id')
+  hyprctl monitors -j | jq -r --arg ws "$active_workspace" "${JQ_MONITOR_GEO} .[] | select(.activeWorkspace.id == (\$ws | tonumber)) | format_geo"
+  hyprctl clients -j | jq -r --arg ws "$active_workspace" '.[] | select(.workspace.id == ($ws | tonumber)) | "\(.at[0]),\(.at[1]) \(.size[0])x\(.size[1])"'
+}
+
+# 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
+
+# Select based on mode
+case "$MODE" in
+region)
+  hyprpicker -r -z >/dev/null 2>&1 &
+  PID=$!
+  sleep .1
+  SELECTION=$(slurp 2>/dev/null)
+  ;;
+windows)
+  hyprpicker -r -z >/dev/null 2>&1 &
+  PID=$!
+  sleep .1
+  SELECTION=$(get_rectangles | slurp -r 2>/dev/null)
+  ;;
+fullscreen)
+  SELECTION=$(hyprctl monitors -j | jq -r "${JQ_MONITOR_GEO} .[] | select(.focused == true) | format_geo")
+  ;;
+smart | *)
+  RECTS=$(get_rectangles)
+  hyprpicker -r -z >/dev/null 2>&1 &
+  PID=$!
+  sleep .1
+  SELECTION=$(echo "$RECTS" | slurp 2>/dev/null)
+
+  # If the selection area is L * W < 20, we'll assume you were trying to select whichever
+  # window or output it was inside of to prevent accidental 2px snapshots
+  if [[ $SELECTION =~ ^([0-9]+),([0-9]+)[[:space:]]([0-9]+)x([0-9]+)$ ]]; then
+    if ((${BASH_REMATCH[3]} * ${BASH_REMATCH[4]} < 20)); then
+      click_x="${BASH_REMATCH[1]}"
+      click_y="${BASH_REMATCH[2]}"
+
+      while IFS= read -r rect; do
+        if [[ $rect =~ ^([0-9]+),([0-9]+)[[:space:]]([0-9]+)x([0-9]+) ]]; then
+          rect_x="${BASH_REMATCH[1]}"
+          rect_y="${BASH_REMATCH[2]}"
+          rect_width="${BASH_REMATCH[3]}"
+          rect_height="${BASH_REMATCH[4]}"
+
+          if ((click_x >= rect_x && click_x < rect_x + rect_width && click_y >= rect_y && click_y < rect_y + rect_height)); then
+            SELECTION="${rect_x},${rect_y} ${rect_width}x${rect_height}"
+            break
+          fi
+        fi
+      done <<<"$RECTS"
+    fi
+  fi
+  ;;
+esac
+
+[[ -z $SELECTION ]] && exit 0
+
+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"
+
+  (
+    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

bin/omarchy-channel-set

@@ -1,27 +1,19 @@
 #!/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|edge|dev]"
+  echo "Usage: omarchy-channel-set [stable|rc|edge|dev]"
   exit 1
 else
   channel="$1"
 fi
 
 case "$channel" in
-"stable") omarchy-branch-set "master" && omarchy-refresh-pacman "stable" && sudo pacman -Suu --noconfirm ;;
+"stable") omarchy-branch-set "master" && omarchy-refresh-pacman "stable" ;;
+"rc") omarchy-branch-set "rc" && omarchy-refresh-pacman "rc" ;;
 "edge") omarchy-branch-set "master" && omarchy-refresh-pacman "edge" ;;
 "dev") omarchy-branch-set "dev" && omarchy-refresh-pacman "edge" ;;
 *) echo "Unknown channel: $channel"; exit 1; ;;

bin/omarchy-cmd-audio-switch

@@ -1,58 +0,0 @@
-#!/bin/bash
-
-# Switch between audio outputs while preserving the mute status. By default mapped to Super + Mute.
-
-focused_monitor="$(hyprctl monitors -j | jq -r '.[] | select(.focused == true).name')"
-
-sinks=$(pactl -f json list sinks | jq '[.[] | select((.ports | length == 0) or ([.ports[]? | .availability != "not available"] | any))]')
-sinks_count=$(echo "$sinks" | jq '. | length')
-
-if [ "$sinks_count" -eq 0 ]; then
-  swayosd-client \
-    --monitor "$focused_monitor" \
-    --custom-message "No audio devices found"
-  exit 1
-fi
-
-current_sink_name=$(pactl get-default-sink)
-current_sink_index=$(echo "$sinks" | jq -r --arg name "$current_sink_name" 'map(.name) | index($name)')
-
-if [ "$current_sink_index" != "null" ]; then
-  next_sink_index=$(((current_sink_index + 1) % sinks_count))
-else
-  next_sink_index=0
-fi
-
-next_sink=$(echo "$sinks" | jq -r ".[$next_sink_index]")
-next_sink_name=$(echo "$next_sink" | jq -r '.name')
-
-next_sink_description=$(echo "$next_sink" | jq -r '.description')
-if [ "$next_sink_description" = "(null)" ] || [ "$next_sink_description" = "null" ] || [ -z "$next_sink_description" ]; then
-  sink_id=$(echo "$next_sink" | jq -r '.properties."object.id"')
-  next_sink_description=$(wpctl status | grep -E "\s+\*?\s+${sink_id}\." | sed -E 's/^.*[0-9]+\.\s+//' | sed -E 's/\s+\[.*$//')
-fi
-
-next_sink_volume=$(echo "$next_sink" | jq -r \
-  '.volume | to_entries[0].value.value_percent | sub("%"; "")')
-next_sink_is_muted=$(echo "$next_sink" | jq -r '.mute')
-
-if [ "$next_sink_is_muted" = "true" ] || [ "$next_sink_volume" -eq 0 ]; then
-  icon_state="muted"
-elif [ "$next_sink_volume" -le 33 ]; then
-  icon_state="low"
-elif [ "$next_sink_volume" -le 66 ]; then
-  icon_state="medium"
-else
-  icon_state="high"
-fi
-
-next_sink_volume_icon="sink-volume-${icon_state}-symbolic"
-
-if [ "$next_sink_name" != "$current_sink_name" ]; then
-  pactl set-default-sink "$next_sink_name"
-fi
-
-swayosd-client \
-  --monitor "$focused_monitor" \
-  --custom-message "$next_sink_description" \
-  --custom-icon "$next_sink_volume_icon"

bin/omarchy-cmd-brightness

@@ -1,21 +0,0 @@
-#!/bin/bash
-
-# Adjust brightness on the most likely display device.
-# Usage: omarchy-cmd-brightness <step>
-
-step="${1:-+5%}"
-
-# Start with the first possible output, then refine to the most likely given an order heuristic.
-device="$(ls -1 /sys/class/backlight 2>/dev/null | head -n1)"
-for candidate in amdgpu_bl* intel_backlight acpi_video*; do
-  if [[ -e "/sys/class/backlight/$candidate" ]]; then
-    device="$candidate"
-    break
-  fi
-done
-
-# Set the actual brightness of the display device.
-brightnessctl -d "$device" set "$step" >/dev/null
-
-# Use SwayOSD to display the new brightness setting.
-omarchy-swayosd-brightness "$(brightnessctl -d "$device" -m | cut -d',' -f4 | tr -d '%')"

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-screenrecord

@@ -1,123 +0,0 @@
-#!/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.
-
-[[ -f ~/.config/user-dirs.dirs ]] && source ~/.config/user-dirs.dirs
-OUTPUT_DIR="${OMARCHY_SCREENRECORD_DIR:-${XDG_VIDEOS_DIR:-$HOME/Videos}}"
-
-if [[ ! -d "$OUTPUT_DIR" ]]; then
-  notify-send "Screen recording directory does not exist: $OUTPUT_DIR" -u critical -t 3000
-  exit 1
-fi
-
-DESKTOP_AUDIO="false"
-MICROPHONE_AUDIO="false"
-WEBCAM="false"
-STOP_RECORDING="false"
-
-for arg in "$@"; do
-  case "$arg" in
-    --with-desktop-audio) DESKTOP_AUDIO="true" ;;
-    --with-microphone-audio) MICROPHONE_AUDIO="true" ;;
-    --with-webcam) WEBCAM="true" ;;
-    --stop-recording) STOP_RECORDING="true"
-  esac
-done
-
-cleanup_webcam() {
-  pkill -f "WebcamOverlay" 2>/dev/null
-}
-
-start_webcam_overlay() {
-  cleanup_webcam
-
-  # Get monitor scale
-  local scale=$(hyprctl monitors -j | jq -r '.[] | select(.focused == true) | .scale')
-
-  # Target width (base 360px, scaled to monitor)
-  local target_width=$(awk "BEGIN {printf \"%.0f\", 360 * $scale}")
-
-  # Try preferred 16:9 resolutions in order, use first available
-  local preferred_resolutions=("640x360" "1280x720" "1920x1080")
-  local video_size_arg=""
-  local available_formats=$(v4l2-ctl --list-formats-ext -d /dev/video0 2>/dev/null)
-
-  for resolution in "${preferred_resolutions[@]}"; do
-    if echo "$available_formats" | grep -q "$resolution"; then
-      video_size_arg="-video_size $resolution"
-      break
-    fi
-  done
-
-  ffplay -f v4l2 $video_size_arg -framerate 30 /dev/video0 \
-    -vf "scale=${target_width}:-1" \
-    -window_title "WebcamOverlay" \
-    -noborder \
-    -fflags nobuffer -flags low_delay \
-    -probesize 32 -analyzeduration 0 \
-    -loglevel quiet &
-  sleep 1
-}
-
-start_screenrecording() {
-  local filename="$OUTPUT_DIR/screenrecording-$(date +'%Y-%m-%d_%H-%M-%S').mp4"
-  local audio_devices=""
-  local audio_args=""
-
-  [[ "$DESKTOP_AUDIO" == "true" ]] && audio_devices+="default_output"
-
-  if [[ "$MICROPHONE_AUDIO" == "true" ]]; then
-    # Merge audio tracks into one - separate tracks only play one at a time in most players
-    [[ -n "$audio_devices" ]] && audio_devices+="|"
-    audio_devices+="default_input"
-  fi
-
-  [[ -n "$audio_devices" ]] && audio_args+="-a $audio_devices"
-
-  gpu-screen-recorder -w portal -f 60 -fallback-cpu-encoding yes -o "$filename" $audio_args -ac aac &
-  toggle_screenrecording_indicator
-}
-
-stop_screenrecording() {
-  pkill -SIGINT -f "^gpu-screen-recorder"  # SIGINT required to save video properly
-
-  # Wait a maximum of 5 seconds to finish before hard killing
-  local count=0
-  while pgrep -f "^gpu-screen-recorder" >/dev/null && [ $count -lt 50 ]; do
-    sleep 0.1
-    count=$((count + 1))
-  done
-
-  if pgrep -f "^gpu-screen-recorder" >/dev/null; then
-    pkill -9 -f "^gpu-screen-recorder"
-    cleanup_webcam
-    notify-send "Screen recording error" "Recording process had to be force-killed. Video may be corrupted." -u critical -t 5000
-  else
-    cleanup_webcam
-    notify-send "Screen recording saved to $OUTPUT_DIR" -t 2000
-  fi
-  toggle_screenrecording_indicator
-}
-
-toggle_screenrecording_indicator() {
-  pkill -RTMIN+8 waybar
-}
-
-screenrecording_active() {
-  pgrep -f "^gpu-screen-recorder" >/dev/null || pgrep -f "WebcamOverlay" >/dev/null
-}
-
-if screenrecording_active; then
-  if pgrep -f "WebcamOverlay" >/dev/null && ! pgrep -f "^gpu-screen-recorder" >/dev/null; then
-    cleanup_webcam
-  else
-    stop_screenrecording
-  fi
-elif [[ "$STOP_RECORDING" == "false" ]]; then
-  [[ "$WEBCAM" == "true" ]] && start_webcam_overlay
-
-  start_screenrecording || cleanup_webcam
-else
-  exit 1
-fi

bin/omarchy-cmd-screenshot

@@ -1,86 +0,0 @@
-#!/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.
-
-[[ -f ~/.config/user-dirs.dirs ]] && source ~/.config/user-dirs.dirs
-OUTPUT_DIR="${OMARCHY_SCREENSHOT_DIR:-${XDG_PICTURES_DIR:-$HOME/Pictures}}"
-
-if [[ ! -d "$OUTPUT_DIR" ]]; then
-  notify-send "Screenshot directory does not exist: $OUTPUT_DIR" -u critical -t 3000
-  exit 1
-fi
-
-pkill slurp && exit 0
-
-MODE="${1:-smart}"
-PROCESSING="${2:-slurp}"
-
-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])"'
-}
-
-# Select based on mode
-case "$MODE" in
-  region)
-    wayfreeze & PID=$!
-    sleep .1
-    SELECTION=$(slurp 2>/dev/null)
-    kill $PID 2>/dev/null
-    ;;
-  windows)
-    wayfreeze & PID=$!
-    sleep .1
-    SELECTION=$(get_rectangles | slurp -r 2>/dev/null)
-    kill $PID 2>/dev/null
-    ;;
-  fullscreen)
-    SELECTION=$(hyprctl monitors -j | jq -r '.[] | select(.focused == true) | "\(.x),\(.y) \((.width / .scale) | floor)x\((.height / .scale) | floor)"')
-    ;;
-  smart|*)
-    RECTS=$(get_rectangles)
-    wayfreeze & PID=$!
-    sleep .1
-    SELECTION=$(echo "$RECTS" | slurp 2>/dev/null)
-    kill $PID 2>/dev/null
-
-    # If the selction area is L * W < 20, we'll assume you were trying to select whichever
-    # window or output it was inside of to prevent accidental 2px snapshots
-    if [[ "$SELECTION" =~ ^([0-9]+),([0-9]+)[[:space:]]([0-9]+)x([0-9]+)$ ]]; then
-      if (( ${BASH_REMATCH[3]} * ${BASH_REMATCH[4]} < 20 )); then
-        click_x="${BASH_REMATCH[1]}"
-        click_y="${BASH_REMATCH[2]}"
-
-        while IFS= read -r rect; do
-          if [[ "$rect" =~ ^([0-9]+),([0-9]+)[[:space:]]([0-9]+)x([0-9]+) ]]; then
-            rect_x="${BASH_REMATCH[1]}"
-            rect_y="${BASH_REMATCH[2]}"
-            rect_width="${BASH_REMATCH[3]}"
-            rect_height="${BASH_REMATCH[4]}"
-
-            if (( click_x >= rect_x && click_x < rect_x+rect_width && click_y >= rect_y && click_y < rect_y+rect_height )); then
-              SELECTION="${rect_x},${rect_y} ${rect_width}x${rect_height}"
-              break
-            fi
-          fi
-        done <<< "$RECTS"
-      fi
-    fi
-    ;;
-esac
-
-[ -z "$SELECTION" ] && exit 0
-
-if [[ $PROCESSING == "slurp" ]]; then
-grim -g "$SELECTION" - |
-  satty --filename - \
-    --output-filename "$OUTPUT_DIR/screenshot-$(date +'%Y-%m-%d_%H-%M-%S').png" \
-    --early-exit \
-    --actions-on-enter save-to-clipboard \
-    --save-after-copy \
-    --copy-command 'wl-copy'
-else
-  grim -g "$SELECTION" - | wl-copy
-fi

bin/omarchy-cmd-terminal-cwd

@@ -1,9 +1,7 @@
 #!/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
 
-# 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

@@ -0,0 +1,58 @@
+#!/bin/bash
+
+# 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
+  exit 1
+fi
+
+if ! efibootmgr &>/dev/null; then
+  echo "Error: efibootmgr is not available or not functional" >&2
+  exit 1
+fi
+
+if cat /sys/class/dmi/id/bios_vendor 2>/dev/null | grep -qi "American Megatrends"; then
+  echo "Error: American Megatrends firmware may not safely support custom EFI entries" >&2
+  exit 1
+fi
+
+if cat /sys/class/dmi/id/bios_vendor 2>/dev/null | grep -qi "Apple"; then
+  echo "Error: Apple firmware uses its own boot manager" >&2
+  exit 1
+fi
+
+existing_entry=$(efibootmgr | grep -E "^Boot[0-9A-Fa-f]+\*? Omarchy([[:space:]]|$)" | head -1)
+
+if [[ -n $existing_entry ]]; then
+  boot_num=$(echo "$existing_entry" | sed -n 's/^Boot\([0-9A-Fa-f]\+\).*/\1/p')
+
+  if gum confirm "Disable direct boot (remove Omarchy EFI entry)?"; then
+    echo "Removing EFI boot entry $boot_num"
+    sudo efibootmgr --bootnum "$boot_num" --delete-bootnum >/dev/null
+  fi
+
+  exit 0
+else
+  uki_file=$(find /boot/EFI/Linux/ -name "omarchy*.efi" -printf "%f\n" 2>/dev/null | head -1)
+
+  if [[ -z $uki_file ]]; then
+    echo "Error: No Omarchy UKI found in /boot/EFI/Linux/" >&2
+    exit 1
+  fi
+
+  boot_source=$(findmnt -n -o SOURCE /boot)
+  disk=$(echo "$boot_source" | sed 's/p\?[0-9]*$//')
+  part=$(echo "$boot_source" | grep -o 'p\?[0-9]*$' | sed 's/^p//')
+
+  if gum confirm "Setup direct boot (so snapshot booting must be done via bios)?"; then
+    echo "Creating EFI boot entry for $uki_file"
+
+    sudo efibootmgr --create \
+      --disk "$disk" \
+      --part "$part" \
+      --label "Omarchy" \
+      --loader "\\EFI\\Linux\\$uki_file"
+  fi
+fi

bin/omarchy-debug

@@ -1,11 +1,14 @@
 #!/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
 
-while [[ $# -gt 0 ]]; do
+while (( $# > 0 )); do
   case "$1" in
     --no-sudo)
       NO_SUDO=true
@@ -25,7 +28,7 @@ done
 
 LOG_FILE="/tmp/omarchy-debug.log"
 
-if [ "$NO_SUDO" = true ]; then
+if [[ $NO_SUDO = "true" ]]; then
   DMESG_OUTPUT="(skipped - --no-sudo flag used)"
 else
   DMESG_OUTPUT="$(sudo dmesg)"
@@ -47,7 +50,7 @@ DMESG
 $DMESG_OUTPUT
 
 =========================================
-JOURNALCTL (CURRENT BOOT, ERRORS ONLY)
+JOURNALCTL (CURRENT BOOT, WARNINGS+ERRORS)
 =========================================
 $(journalctl -b -p 4..1)
 
@@ -57,7 +60,7 @@ INSTALLED PACKAGES
 $({ expac -S '%n %v (%r)' $(pacman -Qqe) 2>/dev/null; comm -13 <(pacman -Sql | sort) <(pacman -Qqe | sort) | xargs -r expac -Q '%n %v (AUR)'; } | sort)
 EOF
 
-if [ "$PRINT_ONLY" = true ]; then
+if [[ $PRINT_ONLY = "true" ]]; then
   cat "$LOG_FILE"
   exit 0
 fi
@@ -73,7 +76,7 @@ case "$ACTION" in
   "Upload log")
     echo "Uploading debug log to 0x0.st..."
     URL=$(curl -sF "file=@$LOG_FILE" -Fexpires=24 https://0x0.st)
-    if [ $? -eq 0 ] && [ -n "$URL" ]; then
+    if (( $? == 0 )) && [[ -n $URL ]]; then
       echo "✓ Log uploaded successfully!"
       echo "Share this URL:"
       echo ""

bin/omarchy-dev-add-migration

@@ -1,13 +1,12 @@
 #!/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"
 touch $migration_file
 
-if [[ "$1" != "--no-edit" ]]; then
+if [[ $1 != "--no-edit" ]]; then
   nvim $migration_file
 fi
 

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,86 @@
+#!/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."}
+    ]
+  }'
+}
+
+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
+
+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
+
+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]"
@@ -11,7 +12,7 @@ fi
 
 # Find the root drive in case we are looking at partitions
 root_drive=$(lsblk -no PKNAME "$drive" 2>/dev/null | tail -n1)
-if [[ -n "$root_drive" ]]; then
+if [[ -n $root_drive ]]; then
   root_drive="/dev/$root_drive"
 else
   root_drive="$drive"
@@ -19,11 +20,31 @@ fi
 
 # Get basic disk information
 size=$(lsblk -dno SIZE "$drive" 2>/dev/null)
-model=$(lsblk -dno MODEL "$root_drive" 2>/dev/null)
+vendor=$(lsblk -dno VENDOR "$root_drive" 2>/dev/null | sed 's/ *$//')
+model=$(lsblk -dno MODEL "$root_drive" 2>/dev/null | sed 's/ *$//')
+
+# Combine vendor and model, avoiding duplication
+label=""
+if [[ -n $vendor && -n $model ]]; then
+  if [[ $model == *$vendor* ]]; then
+    label="$model"
+  else
+    label="$vendor $model"
+  fi
+elif [[ -n $model ]]; then
+  label="$model"
+elif [[ -n $vendor ]]; then
+  label="$vendor"
+fi
 
 # Format display string
 display="$drive"
-[[ -n "$size" ]] && display="$display ($size)"
-[[ -n "$model" ]] && display="$display - $model"
+[[ -n $size ]] && display="$display ($size)"
+[[ -n $label ]] && display="$display - $label"
+
+# Append compact partition summary
+part_summary=$(lsblk -nro TYPE,NAME,FSTYPE,MOUNTPOINT "$root_drive" 2>/dev/null | \
+  awk '$1=="part" { printf "%s%s%s", s, ($3==""?"unknown":$3), ($4==""?"":"("$4")"); s=", " }')
+[[ -n $part_summary ]] && display+=" [$part_summary]"
 
 echo "$display"

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-set-password.
 
 if (($# == 0)); then
   drives=$(lsblk -dpno NAME | grep -E '/dev/(sd|hd|vd|nvme|mmcblk|xv)')
@@ -10,7 +10,7 @@ fi
 
 drives_with_info=""
 while IFS= read -r drive; do
-  [[ -n "$drive" ]] || continue
+  [[ -n $drive ]] || continue
   drives_with_info+="$(omarchy-drive-info "$drive")"$'\n'
 done <<<"$drives"
 

bin/omarchy-drive-set-password

@@ -1,11 +1,12 @@
 #!/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)
 
 if [[ -n $encrypted_drives ]]; then
-  if [[ $(wc -l <<<"$encrypted_drives") -eq 1 ]]; then
+  if (( $(wc -l <<<"$encrypted_drives") == 1 )); then
     drive_to_change="$encrypted_drives"
   else
     drive_to_change="$(omarchy-drive-select "$encrypted_drives")"

bin/omarchy-first-run

@@ -1,15 +1,17 @@
 #!/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
 
 FIRST_RUN_MODE=~/.local/state/omarchy/first-run.mode
 
-if [[ -f "$FIRST_RUN_MODE" ]]; then
+if [[ -f $FIRST_RUN_MODE ]]; then
   rm -f "$FIRST_RUN_MODE"
 
   bash "$OMARCHY_PATH/install/first-run/battery-monitor.sh"
+  bash "$OMARCHY_PATH/install/first-run/recover-internal-monitor.sh"
   bash "$OMARCHY_PATH/install/first-run/cleanup-reboot-sudoers.sh"
   bash "$OMARCHY_PATH/install/first-run/firewall.sh"
   bash "$OMARCHY_PATH/install/first-run/dns-resolver.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,11 +1,12 @@
 #!/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"
 
-if [[ -n "$font_name" ]]; then
+if [[ -n $font_name ]]; then
   if fc-list | grep -iq "$font_name"; then
     if [[ -f ~/.config/alacritty/alacritty.toml ]]; then
       sed -i "s/family = \".*\"/family = \"$font_name\"/g" ~/.config/alacritty/alacritty.toml
@@ -33,7 +34,7 @@ if [[ -n "$font_name" ]]; then
     omarchy-restart-swayosd
 
     if pgrep -x ghostty; then
-      notify-send "    You must restart Ghostty to see font change"
+      notify-send -u low "    You must restart Ghostty to see font change"
     fi
 
     omarchy-hook font-set "$font_name"

bin/omarchy-haptic-touchpad

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+
+# omarchy:summary=Run the Synaptics touchpad haptic feedback daemon
+
+"""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
@@ -11,7 +12,7 @@ SWAPSIZE=$(( 1024 * ${SWAPSIZE_KB:-0} ))
 
 HIBERNATION_IMAGE_SIZE=$(cat /sys/power/image_size)
 
-if [[ "$SWAPSIZE" -gt "$HIBERNATION_IMAGE_SIZE" ]] && [[ -f /etc/mkinitcpio.conf.d/omarchy_resume.conf ]]; then
+if (( SWAPSIZE > HIBERNATION_IMAGE_SIZE )) && [[ -f /etc/mkinitcpio.conf.d/omarchy_resume.conf ]]; then
   exit 0
 else
   exit 1

bin/omarchy-hibernation-remove

@@ -1,12 +1,12 @@
 #!/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"
 
 # Check if hibernation is configured
-if [ ! -f "$MKINITCPIO_CONF" ] || ! grep -q "^HOOKS+=(resume)$" "$MKINITCPIO_CONF"; then
+if [[ ! -f $MKINITCPIO_CONF ]] || ! grep -q "^HOOKS+=(resume)$" "$MKINITCPIO_CONF"; then
   echo "Hibernation is not set up"
   exit 0
 fi
@@ -25,7 +25,7 @@ if swapon --show | grep -q "$SWAP_FILE"; then
 fi
 
 # Remove swapfile
-if [ -f "$SWAP_FILE" ]; then
+if [[ -f $SWAP_FILE ]]; then
   echo "Removing swapfile"
   sudo rm "$SWAP_FILE"
 fi

bin/omarchy-hibernation-setup

@@ -1,29 +1,47 @@
 #!/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
 
 if [[ ! -f /sys/power/image_size ]]; then
-  echo -e "\033[31mError: Hibernation is not supported on your system\033[0m" >&2
-  exit 1
+  echo -e "Hibernation is not supported on your system" >&2
+  exit 0
 fi
 
+if ! command -v limine-mkinitcpio &>/dev/null; then
+  echo "Skipping hibernation setup (requires Limine bootloader)"
+  exit 0
+fi
 
 MKINITCPIO_CONF="/etc/mkinitcpio.conf.d/omarchy_resume.conf"
+SWAP_FILE="/swap/swapfile"
+RESUME_DROP_IN="/etc/limine-entry-tool.d/resume.conf"
 
 # Check if hibernation is already configured
-if [ -f "$MKINITCPIO_CONF" ] && grep -q "^HOOKS+=(resume)$" "$MKINITCPIO_CONF"; then
+if [[ -f $MKINITCPIO_CONF ]] && grep -q "^HOOKS+=(resume)$" "$MKINITCPIO_CONF"; then
+  # Fix empty resume_offset if btrfs map-swapfile failed during initial setup
+  if [[ -f $RESUME_DROP_IN ]] && grep -q 'resume_offset="$' "$RESUME_DROP_IN" && [[ -f $SWAP_FILE ]]; then
+    RESUME_OFFSET=$(sudo btrfs inspect-internal map-swapfile -r "$SWAP_FILE" 2>/dev/null)
+    if [[ -n $RESUME_OFFSET ]]; then
+      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
+    fi
+  fi
   echo "Hibernation is already set up"
   exit 0
 fi
 
-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
+if [[ $1 != "--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
+  fi
 fi
 
 SWAP_SUBVOLUME="/swap"
-SWAP_FILE="$SWAP_SUBVOLUME/swapfile"
 
 # Create btrfs subvolume for swap
 if ! sudo btrfs subvolume show "$SWAP_SUBVOLUME" &>/dev/null; then
@@ -57,14 +75,43 @@ sudo mkdir -p /etc/mkinitcpio.conf.d
 echo "Adding resume hook to $MKINITCPIO_CONF"
 echo "HOOKS+=(resume)" | sudo tee "$MKINITCPIO_CONF" >/dev/null
 
-# Configure suspend-then-hibernate
-echo "Configuring suspend-then-hibernate"
-sudo mkdir -p /etc/systemd/logind.conf.d /etc/systemd/sleep.conf.d
-sudo cp "$OMARCHY_PATH/default/systemd/lid.conf" /etc/systemd/logind.conf.d/
-sudo cp "$OMARCHY_PATH/default/systemd/hibernate.conf" /etc/systemd/sleep.conf.d/
+# Ensure keyboard backlight doesn't prevent sleep
+sudo cp -p "$OMARCHY_PATH/default/systemd/system-sleep/keyboard-backlight" /usr/lib/systemd/system-sleep/
 
-# Regenerate initramfs
+# Add resume= kernel parameters so the initramfs resume hook knows where to find the
+# hibernation image. Without these, resume happens late (after GPU drivers load) and fails.
+if [[ ! -f $RESUME_DROP_IN ]]; then
+  echo "Adding resume kernel parameters"
+  sudo swapon -p 0 "$SWAP_FILE" 2>/dev/null
+  RESUME_DEVICE=$(findmnt -no SOURCE -T "$SWAP_FILE" | sed 's/\[.*\]//')
+  RESUME_OFFSET=$(sudo btrfs inspect-internal map-swapfile -r "$SWAP_FILE")
+  if [[ -n $RESUME_OFFSET ]]; then
+    sudo mkdir -p /etc/limine-entry-tool.d
+    echo "KERNEL_CMDLINE[default]+=\" resume=$RESUME_DEVICE resume_offset=$RESUME_OFFSET\"" | sudo tee "$RESUME_DROP_IN" >/dev/null
+    sudo tee -a /etc/default/limine < "$RESUME_DROP_IN" >/dev/null
+  else
+    echo "Warning: Could not determine resume offset for $SWAP_FILE" >&2
+  fi
+fi
+
+# Use ACPI alarm for RTC wakeup on s2idle systems (needed for suspend-then-hibernate)
+if grep -q "\[s2idle\]" /sys/power/mem_sleep 2>/dev/null; then
+  LIMINE_DROP_IN="/etc/limine-entry-tool.d/rtc-alarm.conf"
+  if [[ ! -f $LIMINE_DROP_IN ]]; then
+    echo "Enabling ACPI RTC alarm for s2idle suspend"
+    sudo mkdir -p /etc/limine-entry-tool.d
+    echo 'KERNEL_CMDLINE[default]+=" rtc_cmos.use_acpi_alarm=1"' | sudo tee "$LIMINE_DROP_IN" >/dev/null
+    sudo tee -a /etc/default/limine < "$LIMINE_DROP_IN" >/dev/null
+  fi
+fi
+
+# Regenerate initramfs and boot entry
 echo "Regenerating initramfs..."
 sudo limine-mkinitcpio
+sudo limine-update
 
-echo "Hibernation enabled"
+echo
+
+if [[ $1 != "--force" ]] && gum confirm "Reboot to enable hibernation?"; then
+  omarchy-system-reboot
+fi

bin/omarchy-hook

@@ -1,10 +1,11 @@
 #!/bin/bash
 
-# Run a named hook, like post-update (available in ~/.config/omarchy/hooks/post-update).
+# omarchy:summary=Run a named hook, like post-update (available in ~/.config/omarchy/hooks/post-update).
+# omarchy:args=[name] [args...]
 
 set -e
 
-if [[ $# -lt 1 ]]; then
+if (( $# < 1 )); then
   echo "Usage: omarchy-hook [name] [args...]"
   exit 1
 fi

bin/omarchy-hw-asus-expertbook-b9406

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+# 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

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+# 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-dell-xps-oled

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+# omarchy:summary=Match Dell XPS systems with LG OLED panel on Intel Panther Lake (Xe3) GPU.
+
+omarchy-hw-match "XPS" \
+  && omarchy-hw-intel-ptl \
+  && test "$(od -An -tx1 -j8 -N2 /sys/class/drm/card*-eDP-*/edid 2>/dev/null | tr -d ' \n')" = "30e4"

bin/omarchy-hw-external-monitors

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+# omarchy:summary=Returns true when an external monitor is physically connected.
+
+for status in /sys/class/drm/card*-*/status; do
+  [[ "$status" == *-eDP-*/status ]] && continue
+  [[ "$(<"$status")" == "connected" ]] && exit 0
+done
+exit 1

bin/omarchy-hw-framework16

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+# 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

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+# 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
+  (($(lspci | grep -cE 'VGA|3D|Display') >= 2))
+fi

bin/omarchy-hw-intel

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+# 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

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+# 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

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+# 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-recover-internal-monitor

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+# 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"
+
+if [[ -f $TOGGLE ]] && ! omarchy-hw-external-monitors; then
+  rm -f "$TOGGLE"
+fi

bin/omarchy-hw-surface

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+# 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

@@ -0,0 +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

@@ -0,0 +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

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+# 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-active-window-transparency-toggle

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

bin/omarchy-hyprland-monitor-focused

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

bin/omarchy-hyprland-monitor-internal

@@ -0,0 +1,46 @@
+#!/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"
+
+# Get internal monitor name dynamically
+INTERNAL=$(hyprctl monitors -j | jq -r '.[] | select(.name | contains("eDP")).name' | head -n 1)
+
+enable() {
+  if omarchy-hyprland-toggle-enabled "$TOGGLE"; then
+    omarchy-hyprland-toggle --disabled-notification "󰍹    Laptop display enabled" "$TOGGLE"
+  fi
+}
+
+disable() {
+  if ! omarchy-hw-external-monitors; then
+    notify-send -u low "󰍹    Can't disable the only active display"
+    exit 1
+  fi
+  if omarchy-hyprland-toggle-disabled "$TOGGLE" && omarchy-hyprland-toggle-disabled "$MIRROR_TOGGLE"; then
+    echo "monitor=$INTERNAL,disable" >"$TOGGLE_FLAG"
+    notify-send -u low "󰍹    Laptop display disabled"
+    hyprctl reload
+  fi
+}
+
+recover() {
+  if ! omarchy-hw-external-monitors && omarchy-hyprland-toggle-enabled "$TOGGLE"; then
+    omarchy-hyprland-toggle "$TOGGLE"
+  fi
+}
+
+case "$1" in
+  on) enable ;;
+  off) disable ;;
+  toggle) if omarchy-hyprland-toggle-enabled "$TOGGLE"; then enable; else disable; fi ;;
+  recover) recover ;;
+  *)
+    echo "Usage: $(basename "$0") {on|off|toggle|recover}" >&2
+    exit 1
+    ;;
+esac

bin/omarchy-hyprland-monitor-internal-mirror

@@ -0,0 +1,58 @@
+#!/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"
+
+# Get names dynamically
+INTERNAL=$(hyprctl monitors -j | jq -r '.[] | select(.name | contains("eDP")).name' | head -n 1)
+# Get the first available external monitor
+EXTERNAL=$(hyprctl monitors -j | jq -r '.[] | select(.name | contains("eDP") | not).name' | head -n 1)
+
+enable() {
+  if [[ -z "$EXTERNAL" ]]; then
+    notify-send -u low "󰍹    No external monitors found for mirror"
+    exit 1
+  fi
+
+  if [[ -z "$INTERNAL" ]]; then
+    notify-send -u low "󰍹    No laptop monitor found to mirror"
+    exit 1
+  fi
+
+  if omarchy-hyprland-toggle-enabled "$DISABLE_TOGGLE"; then
+    omarchy-hyprland-toggle "$DISABLE_TOGGLE"
+  fi
+
+  if omarchy-hyprland-toggle-disabled "$TOGGLE"; then
+    echo "monitor=$EXTERNAL, preferred, auto, 1, mirror, $INTERNAL" > "$TOGGLE_FLAG"
+    notify-send -u low "󰍹    Mirroring enabled ($EXTERNAL)"
+    hyprctl reload
+  fi
+}
+
+disable() {
+  if omarchy-hyprland-toggle-enabled "$TOGGLE"; then
+    omarchy-hyprland-toggle --disabled-notification "󰍹    Extended mode restored" "$TOGGLE"
+  fi
+}
+
+recover() {
+  if ! omarchy-hw-external-monitors && omarchy-hyprland-toggle-enabled "$TOGGLE"; then
+    omarchy-hyprland-toggle "$TOGGLE"
+  fi
+}
+
+case "$1" in
+  on) enable ;;
+  off) disable ;;
+  toggle) if omarchy-hyprland-toggle-enabled "$TOGGLE"; then disable; else enable; fi ;;
+  recover) recover ;;
+  *)
+    echo "Usage: $(basename "$0") {on|off|toggle|recover}" >&2
+    exit 1
+    ;;
+esac

bin/omarchy-hyprland-monitor-scaling-cycle

@@ -0,0 +1,36 @@
+#!/bin/bash
+
+# omarchy:summary=Cycle scaling for the focused Hyprland monitor
+
+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')
+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)
+
+# 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)
+CURRENT_IDX=$(awk -v s="$CURRENT_SCALE" -v list="${SCALES[*]}" 'BEGIN {
+  n = split(list, arr, " ")
+  best = 0; best_diff = 1e9
+  for (i = 1; i <= n; i++) {
+    d = s - arr[i]; if (d < 0) d = -d
+    if (d < best_diff) { best_diff = d; best = i - 1 }
+  }
+  print best
+}')
+
+if [[ "$1" == "--reverse" ]]; then
+  NEW_IDX=$(( (CURRENT_IDX - 1 + ${#SCALES[@]}) % ${#SCALES[@]} ))
+else
+  NEW_IDX=$(( (CURRENT_IDX + 1) % ${#SCALES[@]} ))
+fi
+
+NEW_SCALE=${SCALES[$NEW_IDX]}
+
+hyprctl keyword monitor "$ACTIVE_MONITOR,${WIDTH}x${HEIGHT}@${REFRESH_RATE},auto,$NEW_SCALE"
+notify-send -u low "󰍹    Display scaling set to ${NEW_SCALE}x"

bin/omarchy-hyprland-monitor-watch

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+# 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"
+
+socat -U - "UNIX-CONNECT:$SOCKET" | while read -r event; do
+  case "$event" in
+    monitorremoved\>\>*|monitorremovedv2\>\>*)
+      omarchy-hyprland-monitor-internal recover
+      omarchy-hyprland-monitor-internal-mirror recover
+      ;;
+  esac
+done

bin/omarchy-hyprland-toggle

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+# 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=""
+
+while [[ $# -gt 1 ]]; do
+  case $1 in
+    --enabled-notification) ENABLED_NOTIFICATION="$2"; shift 2 ;;
+    --disabled-notification) DISABLED_NOTIFICATION="$2"; shift 2 ;;
+    *) break ;;
+  esac
+done
+
+FLAG_NAME="$1"
+FLAG="$HOME/.local/state/omarchy/toggles/hypr/$FLAG_NAME.conf"
+FLAG_SOURCE="$OMARCHY_PATH/default/hypr/toggles/$FLAG_NAME.conf"
+
+if [[ -f $FLAG ]]; then
+  rm $FLAG
+  [[ -n $DISABLED_NOTIFICATION ]] && notify-send -u low "$DISABLED_NOTIFICATION"
+elif [[ -f $FLAG_SOURCE ]]; then
+  cp $FLAG_SOURCE $FLAG
+  [[ -n $ENABLED_NOTIFICATION ]] && notify-send -u low "$ENABLED_NOTIFICATION"
+else
+  echo "Flag not found: $FLAG_NAME"
+  exit 1
+fi
+
+hyprctl reload

bin/omarchy-hyprland-toggle-disabled

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+# 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

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+# 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

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+# 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

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

bin/omarchy-hyprland-workspace-layout-toggle

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+# 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')
+
+case "$CURRENT_LAYOUT" in
+  dwindle) NEW_LAYOUT=scrolling ;;
+  *) NEW_LAYOUT=dwindle ;;
+esac
+
+hyprctl keyword workspace $ACTIVE_WORKSPACE, layout:$NEW_LAYOUT
+notify-send -u low "󱂬    Workspace layout set to $NEW_LAYOUT"

bin/omarchy-hyprland-workspace-toggle-gaps

@@ -1,12 +0,0 @@
-#!/bin/bash
-
-# Toggles the window gaps on the active workspace between no gaps and the default 10/5/2.
-
-workspace_id=$(hyprctl activeworkspace -j | jq -r .id)
-gaps=$(hyprctl workspacerules -j | jq -r ".[] | select(.workspaceString==\"$workspace_id\") | .gapsOut[0] // 0")
-
-if [[ $gaps == "0" ]]; then
-  hyprctl keyword "workspace $workspace_id, gapsout:10, gapsin:5, bordersize:2"
-else \
-  hyprctl keyword "workspace $workspace_id, gapsout:0, gapsin:0, bordersize:0"
-fi

bin/omarchy-install-chromium-google-account

@@ -1,7 +1,6 @@
 #!/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
   CONF=~/.config/chromium-flags.conf

bin/omarchy-install-dev-env

@@ -1,17 +1,21 @@
 #!/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|go|laravel|symfony|php|python|elixir|phoenix|rust|java|ocaml|dotnet|clojure>" >&2
+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
   exit 1
 fi
 
 install_php() {
-  sudo pacman -S php composer php-sqlite xdebug --noconfirm
+  omarchy-pkg-add php composer php-sqlite xdebug
 
   # Install Path for Composer
-  if [[ ":$PATH:" != *":$HOME/.config/composer/vendor/bin:"* ]]; then
+  if [[ :$PATH: != *:$HOME/.config/composer/vendor/bin:* ]]; then
     echo 'export PATH="$HOME/.config/composer/vendor/bin:$PATH"' >>"$HOME/.bashrc"
     source "$HOME/.bashrc"
     echo "Added Composer global bin directory to PATH."
@@ -50,9 +54,10 @@ case "$1" in
 ruby)
   echo -e "Installing Ruby on Rails...\n"
   omarchy-pkg-add libyaml
-  mise use --global ruby@latest
+  mise settings add ruby.compile false
   mise settings add idiomatic_version_file_enable_tools ruby
-  echo "gem: --no-document" > ~/.gemrc
+  mise use --global ruby@latest
+  echo "gem: --no-document" >~/.gemrc
   mise x ruby -- gem install rails --no-document
   echo -e "\nYou can now run: rails new myproject"
   ;;
@@ -141,4 +146,10 @@ clojure)
   omarchy-pkg-add rlwrap
   mise use --global clojure@latest
   ;;
+scala)
+  echo -e "Installing Scala...\n"
+  mise use --global java@latest
+  mise use --global scala@latest
+  mise use --global scala-cli@latest
+  ;;
 esac

bin/omarchy-install-docker-dbs

@@ -1,17 +1,17 @@
 #!/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")
 
-if [[ "$#" -eq 0 ]]; then
+if (( $# == 0 )); then
   choices=$(printf "%s\n" "${options[@]}" | gum choose --header "Select database (return to install, esc to cancel)") || main_menu
 else
   choices="$@"
 fi
 
-if [[ -n "$choices" ]]; then
+if [[ -n $choices ]]; then
   for db in $choices; do
     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 ;;

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-geforce-now

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+# omarchy:summary=Install and launch Geforce Now.
+
+set -e
+
+omarchy-pkg-add flatpak
+cd /tmp
+
+# Download and run GeForce NOW
+curl -LO https://international.download.nvidia.com/GFNLinux/GeForceNOWSetup.bin
+chmod +x GeForceNOWSetup.bin
+./GeForceNOWSetup.bin
+
+# Ensure a separate browser process not started by GFN is available.
+# If not, it seems like GFN has a tendency to hang on login.
+setsid omarchy-launch-browser

bin/omarchy-install-nordvpn

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+# omarchy:summary=Install the NordVPN service with optional GUI.
+# omarchy:requires-sudo=true
+
+echo "Installing NordVPN..."
+omarchy-pkg-aur-add nordvpn-bin
+
+echo "Enabling NordVPN daemon..."
+sudo systemctl enable --now nordvpnd
+
+echo "Adding user to nordvpn group..."
+sudo usermod -aG nordvpn "$USER"
+
+echo -e "\nNordVPN installed! After reboot, run 'nordvpn login' to authenticate."
+
+echo
+gum confirm "Reboot now to make NordVPN usable?" && omarchy-system-reboot

bin/omarchy-install-once

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+# omarchy:summary=Install the ONCE service, enable its background service, and launch the TUI.
+# omarchy:requires-sudo=true
+
+echo "Installing ONCE..."
+omarchy-pkg-add once-bin
+
+echo "Enabling ONCE background service..."
+sudo systemctl enable --now once-background.service
+
+echo -e "\nLaunching ONCE..."
+once

bin/omarchy-install-steam

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Install and launch Steam after first letting the user pick the correct grahics card drivers.
+# omarchy:summary=Install Steam and graphics drivers selected for this system
+# omarchy:requires-sudo=true
 
 set -e
 

bin/omarchy-install-tailscale

@@ -1,15 +1,13 @@
 #!/bin/bash
 
-# Install the Tailscale mesh VPN service, the tsui TUI management app, and a web app for the Tailscale Admin Console.
+# omarchy:summary=Install the Tailscale mesh VPN service and a web app for the Tailscale Admin Console.
+# omarchy:requires-sudo=true
 
-curl -fsSL https://tailscale.com/install.sh | sh
-curl -fsSL https://neuralink.com/tsui/install.sh | bash
+echo -e "\nInstalling Tailscale..."
+omarchy-pkg-add tailscale
 
 echo -e "\nStarting Tailscale..."
+sudo systemctl enable --now tailscaled.service
 sudo tailscale up --accept-routes
 
-echo -e "\nAdd tsui to sudoers..."
-echo "$USER ALL=(ALL) NOPASSWD: $(which tsui)" | sudo tee /etc/sudoers.d/tsui
-
-omarchy-tui-install "Tailscale" "sudo tsui" float https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/tailscale-light.png
-omarchy-webapp-install "Tailscale Admin Console" "https://login.tailscale.com/admin/machines" https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/tailscale-light.png
+omarchy-webapp-install "Tailscale" "https://login.tailscale.com/admin/machines" https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/tailscale-light.png

bin/omarchy-install-terminal

@@ -1,6 +1,8 @@
 #!/bin/bash
 
-# Install one of the approved terminals and set it as the default for Omarchy (Super + Return etc).
+# omarchy:summary=Install one of the approved terminals and set it as the default for Omarchy (Super + Return etc).
+# omarchy:args=<alacritty|ghostty|kitty>
+# omarchy:requires-sudo=true
 
 if (($# == 0)); then
   echo "Usage: omarchy-install-terminal [alacritty|ghostty|kitty]"
@@ -25,33 +27,11 @@ if omarchy-pkg-add $package; then
   # Copy custom desktop entry for alacritty with X-TerminalArg* keys
   if [[ $package == "alacritty" ]]; then
     mkdir -p ~/.local/share/applications
-    cat > ~/.local/share/applications/Alacritty.desktop << EOF
-[Desktop Entry]
-Type=Application
-TryExec=alacritty
-Exec=alacritty
-Icon=Alacritty
-Terminal=false
-Categories=System;TerminalEmulator;
-Name=Alacritty
-GenericName=Terminal
-Comment=A fast, cross-platform, OpenGL terminal emulator
-StartupNotify=true
-StartupWMClass=Alacritty
-Actions=New;
-X-TerminalArgExec=-e
-X-TerminalArgAppId=--class=
-X-TerminalArgTitle=--title=
-X-TerminalArgDir=--working-directory=
-
-[Desktop Action New]
-Name=New Terminal
-Exec=alacritty
-EOF
+    cp $OMARCHY_PATH/applications/Alacritty.desktop ~/.local/share/applications/
   fi
 
   # Update xdg-terminals.list to prioritize the proper terminal
-  cat > ~/.config/xdg-terminals.list << EOF
+  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

bin/omarchy-install-vscode

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Install VSCode and configure it to use the gnome-libsecret password store, not to update automatically, and to use the current Omarchy theme.
+# omarchy:summary=Install VS Code and configure Omarchy defaults for secrets, updates, and theme
 
 echo "Installing VSCode..."
 omarchy-pkg-add visual-studio-code-bin

bin/omarchy-install-xbox-controllers

@@ -1,12 +1,13 @@
 #!/bin/bash
 
-# Install support for using Xbox controllers with Steam/RetroArch/etc.
+# omarchy:summary=Install support for using Xbox controllers with Steam/RetroArch/etc.
+# omarchy:requires-sudo=true
 
 set -e
 
 # Install xpadneo to ensure controllers work out of the box
-sudo pacman -S --noconfirm --needed linux-headers
-yay -S --noconfirm xpadneo-dkms
+omarchy-pkg-add linux-headers
+omarchy-pkg-aur-add xpadneo-dkms
 
 # Prevent xpad/xpadneo driver conflict
 echo blacklist xpad | sudo tee /etc/modprobe.d/blacklist-xpad.conf >/dev/null

bin/omarchy-launch-about

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-# Launch the fastfetch TUI that gives information about the current system.
+# omarchy:summary=Launch the fastfetch TUI that gives information about the current system.
 
 exec omarchy-launch-or-focus-tui "bash -c 'fastfetch; read -n 1 -s'"

bin/omarchy-launch-audio

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-# Launch the Omarchy audio controls TUI (provided by wiremix).
+# omarchy:summary=Launch the Omarchy audio controls TUI (provided by wiremix).
 
 omarchy-launch-or-focus-tui wiremix

bin/omarchy-launch-bluetooth

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Launch the Omarchy bluetooth controls TUI (provided by bluetui).
-# Also attempts to unblock bluetooth service if rfkill had blocked it.
+# omarchy:summary=Launch the Omarchy bluetooth controls TUI (provided by bluetui).
 
 rfkill unblock bluetooth
 exec omarchy-launch-or-focus-tui bluetui

bin/omarchy-launch-browser

@@ -1,12 +1,12 @@
 #!/bin/bash
 
-# Launch the default browser as determined by xdg-settings.
-# Automatically converts --private into the correct flag for the given browser.
+# omarchy:summary=Launch the default browser as determined by xdg-settings.
+# omarchy:args=[url]
 
 default_browser=$(xdg-settings get default-web-browser)
 browser_exec=$(sed -n 's/^Exec=\([^ ]*\).*/\1/p' {~/.local,~/.nix-profile,/usr}/share/applications/$default_browser 2>/dev/null | head -1)
 
-if [[ $browser_exec =~ (firefox|zen|librewolf|mullvad) ]]; then
+if $browser_exec --help | grep -q MOZ_LOG; then
   private_flag="--private-window"
 elif [[ $browser_exec =~ edge ]]; then
   private_flag="--inprivate"

bin/omarchy-launch-editor

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Launch the default editor as determined by $EDITOR (set via ~/.config/uwsm/default) (or nvim if missing).
-# Starts suitable editors in a terminal window and otherwise as a regular application.
+# omarchy:summary=Launch the default editor as determined by $EDITOR (set via ~/.config/uwsm/default) (or nvim if missing).
+# omarchy:args=<path>
 
 omarchy-cmd-present "$EDITOR" || EDITOR=nvim
 

bin/omarchy-launch-floating-terminal-with-presentation

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Launch a floating terminal with the Omarchy logo presentation, then execute the command passed in, and finally end with the omarchy-show-done presentation.
-# Used by actions such as Update System.
+# omarchy:summary=Launch a floating terminal with the Omarchy presentation wrapper
+# omarchy:args=<command>
 
 cmd="$*"
-exec setsid uwsm-app -- xdg-terminal-exec --app-id=org.omarchy.terminal --title=Omarchy -e bash -c "omarchy-show-logo; $cmd; if [ \$? -ne 130 ]; then omarchy-show-done; fi"
+exec setsid uwsm-app -- xdg-terminal-exec --app-id=org.omarchy.terminal --title=Omarchy -e bash -c "omarchy-show-logo; $cmd; if (( \$? != 130 )); then omarchy-show-done; fi"

bin/omarchy-launch-or-focus

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Launch or focus on a given command identified by the passed in window-pattern.
-# Use by some default bindings, like the one for Spotify, to ensure there is only one instance of the application open.
+# omarchy:summary=Launch an app or focus an existing window matching a pattern
+# omarchy:args=<window-pattern> <launch-command>
 
 if (($# == 0)); then
   echo "Usage: omarchy-launch-or-focus [window-pattern] [launch-command]"

bin/omarchy-launch-or-focus-tui

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Launch or focus on a given TUI identified by the passed in as the command.
-# Use by commands like omarchy-launch-wifi to ensure there is only one wifi configuration screen open.
+# omarchy:summary=Launch a TUI or focus an existing terminal window for it
+# omarchy:args=<command> [args...]
 
 APP_ID="org.omarchy.$(basename "$1")"
 LAUNCH_COMMAND="omarchy-launch-tui $@"

bin/omarchy-launch-or-focus-webapp

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Launch or focus on a given web app identified by the window-pattern.
-# Use by some default bindings, like the one for WhatsApp, to ensure there is only one instance of the application open.
+# omarchy:summary=Launch or focus on a given web app identified by the window-pattern.
+# omarchy:args=<window-pattern> <url-and-flags...>
 
 if (($# == 0)); then
   echo "Usage: omarchy-launch-or-focus-webapp [window-pattern] [url-and-flags...]"

bin/omarchy-launch-screensaver

@@ -1,8 +1,7 @@
 #!/bin/bash
 
-# Launch the Omarchy screensaver in the default terminal on the system with the correct font configuration.
+# omarchy:summary=Launch the Omarchy screensaver in the default terminal on the system with the correct font configuration.
 
-# Exit early if we don't have the tte show
 if ! command -v tte &>/dev/null; then
   exit 1
 fi
@@ -11,14 +10,14 @@ fi
 pgrep -f org.omarchy.screensaver && exit 0
 
 # Allow screensaver to be turned off but also force started
-if [[ -f ~/.local/state/omarchy/toggles/screensaver-off ]] && [[ $1 != "force" ]]; then
+if omarchy-toggle-enabled screensaver-off && [[ $1 != "force" ]]; then
   exit 1
 fi
 
 # Silently quit Walker on overlay
 walker -q
 
-focused=$(hyprctl monitors -j | jq -r '.[] | select(.focused == true).name')
+focused=$(omarchy-hyprland-monitor-focused)
 terminal=$(xdg-terminal-exec --print-id)
 
 for m in $(hyprctl monitors -j | jq -r '.[] | .name'); do
@@ -29,24 +28,24 @@ for m in $(hyprctl monitors -j | jq -r '.[] | .name'); do
     hyprctl dispatch exec -- \
       alacritty --class=org.omarchy.screensaver \
       --config-file ~/.local/share/omarchy/default/alacritty/screensaver.toml \
-      -e omarchy-cmd-screensaver
+      -e omarchy-screensaver
     ;;
   *ghostty*)
     hyprctl dispatch exec -- \
       ghostty --class=org.omarchy.screensaver \
       --config-file=~/.local/share/omarchy/default/ghostty/screensaver \
       --font-size=18 \
-      -e omarchy-cmd-screensaver
+      -e omarchy-screensaver
     ;;
   *kitty*)
     hyprctl dispatch exec -- \
       kitty --class=org.omarchy.screensaver \
       --override font_size=18 \
       --override window_padding_width=0 \
-      -e omarchy-cmd-screensaver
+      -e omarchy-screensaver
     ;;
   *)
-    notify-send "✋  Screensaver only runs in Alacritty, Ghostty, or Kitty"
+    notify-send -u low "✋  Screensaver only runs in Alacritty, Ghostty, or Kitty"
     ;;
   esac
 done