Merge quattro into USB authorization branch

2026-09-21 08:23:51 -06:00
commit 27bbbb2fe9
@@ -2,3 +2,5 @@
 # Python bytecode (orchestrator)
 __pycache__/
 *.pyc
+
+.claude/
@@ -13,6 +13,7 @@ commands and reusable setup leaves:
 - use `$OMARCHY_INSTALL` and `$OMARCHY_PATH` instead of hard-coded Omarchy paths.
 - keep root-scoped hardware setup under `install/hardware/` and orchestrate it through `install/hardware/all.sh`.
 - keep every per-user setup leaf under `install/user/` (including `install/user/hardware/` and `install/user/first-run/`) so it is clear what must run for each user.
+- The base install supplies matching kernel headers before hardware setup. DKMS installers should install their driver packages and assume the headers exist.
 - prefer helper commands for package and command checks where available.

 Raw `command -v`, `pacman`, and `pacman-key` are acceptable in package-helper
@@ -15,10 +15,7 @@ Take a full-screen screenshot without opening the editor:
 omarchy capture screenshot fullscreen save
 ```

-The command prints the saved path and writes to the configured Pictures
-directory. Use `omarchy screenshot` for the interactive smart-region flow.
-Capture reference and candidate states as separate images when changing a
-layer-shell surface or layout, then compare both.
+The command writes to Omasnap's configured screenshot directory. Use `omarchy screenshot` for the interactive capture flow, which copies the capture and shows a timed preview. Use `omarchy screenshot --editor=overlay` to test annotation before output. Capture reference and candidate states as separate images when changing a layer-shell surface or layout, then compare both.

 Record a short full-screen video for animation, transition, timing, capture, or
 screen-recording changes:
@@ -15,8 +15,9 @@
 # start.
 #
 # Env: OMARCHY_SCREENRECORD_DEBUG=true appends gpu-screen-recorder's stderr (and
-# the picker target it was launched with) to /tmp/omarchy-screenrecord.log so
-# users can attach a log when reporting capture failures.
+# the picker target it was launched with) to
+# $XDG_RUNTIME_DIR/omarchy-screenrecord.log so users can attach a log when
+# reporting capture failures.

 [[ -f ~/.config/user-dirs.dirs ]] && source ~/.config/user-dirs.dirs
 OUTPUT_DIR="${OMARCHY_SCREENRECORD_DIR:-${XDG_VIDEOS_DIR:-$HOME/Videos}}"
@@ -34,9 +35,18 @@ WEBCAM_SIZE="medium"
 RESOLUTION=""
 FULLSCREEN="false"
 STOP_RECORDING="false"
-RECORDING_FILE="/tmp/omarchy-screenrecord-filename"
-REGION_FILE="${XDG_RUNTIME_DIR:-/tmp}/omarchy-screenrecord-region"
-LOG_FILE=$([[ ${OMARCHY_SCREENRECORD_DEBUG:-false} == "true" ]] && echo "/tmp/omarchy-screenrecord.log" || echo "/dev/null")
+# Both of these live in the per-user runtime directory, which is 0700. What
+# RECORDING_FILE holds is read back on stop and used as a path -- ffmpeg writes
+# beside it, `mv` replaces it, and `rm -f` deletes its preview -- so a name in
+# world-writable /tmp is a name any other local account can create first and
+# then point wherever it likes. The debug log carries the recorder's stderr and
+# the picked geometry, which is nobody else's business either. Fall back to
+# the state directory when there is no session runtime dir -- :-/tmp would put
+# both files back at the fixed names this comment describes.
+RUNTIME_DIR="${XDG_RUNTIME_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/omarchy}"
+RECORDING_FILE="$RUNTIME_DIR/omarchy-screenrecord-filename"
+REGION_FILE="$RUNTIME_DIR/omarchy-screenrecord-region"
+LOG_FILE=$([[ ${OMARCHY_SCREENRECORD_DEBUG:-false} == "true" ]] && echo "$RUNTIME_DIR/omarchy-screenrecord.log" || echo "/dev/null")

 for arg in "$@"; do
  case "$arg" in
@@ -144,6 +154,11 @@ select_capture_target() {
 }

 start_screenrecording() {
+  mkdir -p "$RUNTIME_DIR" || return 1
+  # XDG_STATE_HOME may be outside a private home; protect existing fallbacks too.
+  if [[ -z ${XDG_RUNTIME_DIR:-} ]]; then
+    chmod 700 "$RUNTIME_DIR" || return 1
+  fi
  local capture_args=()
  local target

@@ -2,81 +2,22 @@

 # omarchy:summary=Take a screenshot
 # omarchy:group=capture
-# omarchy:args=[smart|region|windows|fullscreen] [slurp|copy|save] [--editor=<name>]
+# omarchy:args=[smart|region|windows|fullscreen|scroll] [copy|save]
 # 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"
-  omarchy-notification-send "Created screenshot directory: $OUTPUT_DIR" -t 2000
+if [[ -n ${OMARCHY_SCREENSHOT_DIR:-} && -z ${OMASNAP_SCREENSHOT_DIR:-} ]]; then
+  export OMASNAP_SCREENSHOT_DIR="$OMARCHY_SCREENSHOT_DIR"
 fi

-pkill slurp && exit 0
-
-SCREENSHOT_EDITOR="${OMARCHY_SCREENSHOT_EDITOR:-tensaku-edit}"
-
-# Parse --editor flag from any position
-ARGS=()
+omasnap_args=()
 for arg in "$@"; do
-  if [[ $arg == --editor=* ]]; then
-    SCREENSHOT_EDITOR="${arg#--editor=}"
-  else
-    ARGS+=("$arg")
-  fi
+  case "$arg" in
+    copy) omasnap_args+=(--copy) ;;
+    save) omasnap_args+=(--save) ;;
+    slurp) ;;
+    *) omasnap_args+=("$arg") ;;
+  esac
 done
-set -- "${ARGS[@]}"

-MODE="${1:-smart}"
-PROCESSING="${2:-slurp}"
-
-# The picker leaves the screen freeze running (PID on its first output line)
-# so grim captures the frozen overlay rather than live content shifting
-# during teardown.
-#
-# Software-composited cursors (Hyprland's fallback on GPUs without working
-# hardware cursors) are baked into the frames grim captures, so force
-# hardware cursors until after grim runs and restore the setting on exit.
-NO_HW_CURSORS=$(hyprctl getoption cursor:no_hardware_cursors -j | jq '.int')
-
-set_no_hw_cursors() {
-  hyprctl eval "hl.config({ cursor = { no_hardware_cursors = $1 } })" &>/dev/null ||
-    hyprctl keyword cursor:no_hardware_cursors "$1" &>/dev/null
-}
-
-cleanup() {
-  [[ -n $FREEZE_PID ]] && kill $FREEZE_PID 2>/dev/null
-  set_no_hw_cursors "$NO_HW_CURSORS"
-}
-trap cleanup EXIT
-
-set_no_hw_cursors 0
-{ read -r FREEZE_PID; read -r SELECTION; } < <(omarchy-capture-region "$MODE" --keep-freeze)
-
-[[ -z $SELECTION ]] && exit 0
-
-FILENAME="screenshot-$(date +'%Y-%m-%d_%H-%M-%S').png"
-FILEPATH="$OUTPUT_DIR/$FILENAME"
-
-case "$PROCESSING" in
-  slurp)
-    grim -g "$SELECTION" "$FILEPATH" || exit 1
-    echo "$FILEPATH"
-    wl-copy --type image/png <"$FILEPATH"
-
-    # Best-effort: the screenshot is already saved and on the clipboard, so a
-    # notification outage must not report the capture itself as failed.
-    omarchy-notification-send "Screenshot saved to clipboard and file" "Edit with Super + Alt + , (or click this)" \
-      --image "$FILEPATH" \
-      --exec "$SCREENSHOT_EDITOR" "$FILEPATH" || true
-    ;;
-  copy)
-    grim -g "$SELECTION" - | wl-copy --type image/png
-    ;;
-  save)
-    grim -g "$SELECTION" "$FILEPATH" || exit 1
-    echo "$FILEPATH"
-    ;;
-esac
+exec omasnap "${omasnap_args[@]}"
@@ -8,7 +8,10 @@
 set -euo pipefail

 readonly MARGIN=40
-readonly REGION_FILE="${XDG_RUNTIME_DIR:-/tmp}/omarchy-screenrecord-region"
+# Has to resolve to whatever omarchy-capture-screenrecording writes, fallback
+# included, or a recording without a session runtime dir anchors the camera to
+# the whole monitor instead of the region it recorded.
+readonly REGION_FILE="${XDG_RUNTIME_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/omarchy}/omarchy-screenrecord-region"

 usage() {
  echo "Usage: omarchy-capture-webcam-resize <smaller|larger|reset|small|medium|large>" >&2
@@ -30,7 +30,7 @@ open_image() {
  local path="$1"

  [[ -r $path ]] || exit 1
-  exec tensaku-edit "$path"
+  exec omasnap "$path"
 }

 open_text() {
@@ -86,6 +86,10 @@ if ! agent_install; then
  exit 1
 fi

+if [[ $agent == "claude" ]]; then
+  omarchy-install-chromium-claude 2>/dev/null || true
+fi
+
 mkdir -p "$(dirname "$agent_file")"
 printf '%s\n' "$agent" >"$agent_file"

@@ -11,6 +11,18 @@ if (( $# < 1 )); then
 fi

 HOOK=$1
+
+# Hook names are fixed labels chosen by Omarchy code (post-update, theme-set,
+# font-set). The name becomes a filename under the hooks directory. A slash
+# would turn it into directory levels, and a bare `.` or `..` would point bash
+# at the directory itself or its parent. Refuse those rather than follow them.
+# Dots inside a name (a..b) are fine; once slashes are out, only the whole
+# name being `.` or `..` can leave the directory.
+if [[ -z $HOOK || $HOOK == */* || $HOOK == "." || $HOOK == ".." ]]; then
+  echo "Invalid hook name: $HOOK" >&2
+  exit 2
+fi
+
 HOOK_PATH="$HOME/.config/omarchy/hooks/$1"
 HOOK_DIR="$HOOK_PATH.d"
 shift
@@ -15,6 +15,17 @@ fi

 HOOK_TYPE=$1
 HOOK_FILE=$2
+
+# Hook types are the same labels omarchy-hook runs (post-update, theme-set).
+# The type becomes a directory under the hooks directory. A slash would turn
+# it into directory levels. A bare `.` or `..` is a name the runner already
+# refuses, so installing under it would write a hook nothing can run. Refuse
+# those rather than mkdir/cp into them. Dots inside a name (a..b) are fine.
+if [[ -z $HOOK_TYPE || $HOOK_TYPE == */* || $HOOK_TYPE == "." || $HOOK_TYPE == ".." ]]; then
+  echo "Invalid hook name: $HOOK_TYPE" >&2
+  exit 2
+fi
+
 HOOK_DIR="$HOME/.config/omarchy/hooks/$HOOK_TYPE.d"
 HOOK_NAME=$(basename "$HOOK_FILE")
 HOOK_PATH="$HOOK_DIR/$HOOK_NAME"
@@ -0,0 +1,43 @@
+#!/bin/bash
+
+# omarchy:summary=Install the Claude extension for Chromium-based browsers
+# omarchy:requires-sudo=true
+
+set -euo pipefail
+
+if (( EUID == 0 )); then
+  export PATH=/usr/bin:/bin
+fi
+
+EXTENSION_ID="fcoeoabgfenejglbffodgkkbkcdhcgfn"
+EXTENSION_JSON='{ "external_update_url": "https://clients2.google.com/service/update2/crx" }'
+PACKAGED_PATH=/usr/bin/omarchy-install-chromium-claude
+
+# Brave and Brave Origin share Chromium's external extension directory.
+# Seed all supported browsers, including those installed after choosing Claude.
+EXTENSION_DIRS=(
+  /usr/share/chromium/extensions
+  /usr/share/google-chrome/extensions
+  /usr/share/microsoft-edge/extensions
+)
+
+installed=true
+for dir in "${EXTENSION_DIRS[@]}"; do
+  if [[ ! -f $dir/$EXTENSION_ID.json ]] || [[ $(cat "$dir/$EXTENSION_ID.json") != "$EXTENSION_JSON" ]]; then
+    installed=false
+  fi
+done
+
+if [[ $installed == "true" ]]; then
+  exit 0
+fi
+
+if (( EUID == 0 )); then
+  for dir in "${EXTENSION_DIRS[@]}"; do
+    printf '%s\n' "$EXTENSION_JSON" | install -D -m 0644 /dev/stdin "$dir/$EXTENSION_ID.json"
+  done
+elif [[ -t 0 ]]; then
+  exec sudo "$PACKAGED_PATH"
+else
+  exec pkexec "$PACKAGED_PATH"
+fi
@@ -12,37 +12,10 @@ if [[ -z $1 ]]; then
 fi

 install_php() {
-  omarchy-pkg-add php composer php-sqlite xdebug
+  mise tool-alias set php github:nunomaduro/static-php-builds
+  mise use --global php@latest

-  # Install Path for Composer
-  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."
-  else
-    echo "Composer global bin directory already in PATH."
-  fi
-
-  # Enable some extensions
-  local php_ini_path="/etc/php/php.ini"
-  local extensions_to_enable=(
-    "bcmath"
-    "intl"
-    "iconv"
-    "openssl"
-    "pdo_sqlite"
-    "pdo_mysql"
-  )
-
-  # Enable Xdebug
-  sudo sed -i \
-    -e 's/^;zend_extension=xdebug.so/zend_extension=xdebug.so/' \
-    -e 's/^;xdebug.mode=debug/xdebug.mode=debug/' \
-    /etc/php/conf.d/xdebug.ini
-
-  for ext in "${extensions_to_enable[@]}"; do
-    sudo sed -i "s/^;extension=${ext}/extension=${ext}/" "$php_ini_path"
-  done
+  mise x php -- composer global config bin-dir "$HOME/.local/bin"
 }

 install_node() {
@@ -84,7 +57,7 @@ laravel)
  echo -e "Installing PHP and Laravel...\n"
  install_php
  install_node
-  composer global require laravel/installer
+  mise x php -- composer global require laravel/installer
  echo -e "\nYou can now run: laravel new myproject"
  ;;
 symfony)
@@ -10,7 +10,7 @@ set -e
 echo "Installing Xbox controller Bluetooth support..."

 # Install xpadneo to ensure controllers work out of the box
-omarchy-pkg-add linux-headers xpadneo-dkms
+omarchy-pkg-add xpadneo-dkms

 # Prevent xpad/xpadneo driver conflict
 echo blacklist xpad | sudo tee /etc/modprobe.d/blacklist-xpad.conf >/dev/null
@@ -28,7 +28,7 @@ echo "Installing 1Password extension for Chromium..."
 install_chromium_extension

 echo "Opening 1Password..."
-uwsm-app -- 1password >/dev/null 2>&1 &
+setsid uwsm-app -- 1password >/dev/null 2>&1 &

 echo ""
 echo "1Password has been installed. Restart Chromium to load the browser extension."
@@ -22,7 +22,9 @@ if [[ -z $interface ]]; then
  # menu's visibility gate describe. Fall back to the first connected Wi-Fi
  # device. nmcli localizes state names, so pin the locale, and the prefix
  # match accepts states like "connected (externally)".
-  route_device=$(ip route get 1.1.1.1 2>/dev/null | awk '{ for (i = 1; i <= NF; i++) if ($i == "dev") { print $(i + 1); exit } }')
+  if ! route_device=$(ip route get 1.1.1.1 2>/dev/null | awk '{ for (i = 1; i <= NF; i++) if ($i == "dev") { print $(i + 1); exit } }'); then
+    route_device=""
+  fi
  if [[ -n $route_device && -d /sys/class/net/$route_device/wireless ]]; then
    interface=$route_device
  else
@@ -10,6 +10,11 @@ if [[ -z $1 ]]; then
 fi

 remove_php() {
+  mise uninstall php --all
+  mise rm -g php
+  mise tool-alias unset php
+
+  # PHP from before it moved to mise
  omarchy-pkg-drop php composer php-sqlite xdebug
 }

@@ -46,7 +51,9 @@ php)
  ;;
 laravel)
  echo -e "Removing Laravel...\n"
-  composer global remove laravel/installer 2>/dev/null || true
+  mise x php -- composer global remove laravel/installer 2>/dev/null || true
+
+  rm -f "$HOME/.local/bin/laravel" "$HOME/.config/composer/vendor/bin/laravel"
  ;;
 symfony)
  echo -e "Removing Symfony CLI...\n"
@@ -21,6 +21,19 @@ if [[ -z $STATE_NAME ]]; then
 fi

 case "$COMMAND" in
-set) touch "$STATE_DIR/$STATE_NAME" ;;
+set)
+  # State names are fixed labels (reboot-required, restart-*-required). The
+  # name becomes a filename under the state directory. A slash would turn it
+  # into directory levels, and a bare `.` or `..` would touch the directory
+  # itself or its parent. Refuse those. Dots inside a name (a..b) are fine;
+  # once slashes are out, only the whole name being `.` or `..` can leave the
+  # directory. clear needs no such guard: find -name matches basenames only,
+  # so a pattern can never walk out of the directory.
+  if [[ $STATE_NAME == */* || $STATE_NAME == "." || $STATE_NAME == ".." ]]; then
+    echo "Invalid state name: $STATE_NAME" >&2
+    exit 2
+  fi
+  touch "$STATE_DIR/$STATE_NAME"
+  ;;
 clear) find "$STATE_DIR" -maxdepth 1 -type f -name "$STATE_NAME" -delete ;;
 esac
@@ -297,19 +297,34 @@ rebuild_next_boot() {
  umount "$next$esp_mount"
 }

+# Both the staged system and the retained baseline must lose the old hashes.
+scrub_factory_accounts() {
+  local root="$1" user users
+
+  users=$(awk -F: '$3 >= 1000 && $3 < 60000 { print $1 }' "$root/etc/passwd") || return 1
+  for user in $users; do
+    userdel --root "$root" "$user" 2>>"$LOG_FILE" || return 1
+    rm -rf "${root:?}/home/$user" || return 1
+  done
+
+  # passwd --lock preserves the hash. Replace it, then remove the backups
+  # that userdel and usermod leave behind.
+  usermod --root "$root" --password '!' root >>"$LOG_FILE" 2>&1 || return 1
+  rm -f "$root/etc/"{shadow-,gshadow-,passwd-,group-,subuid-,subgid-}
+}
+
 # Remove the seller's account material and machine identity from the retained
 # @factory baseline so it can neither be mounted for recovery nor restore the
 # seller's account on a future reset. Idempotent (a scrubbed baseline has no
 # uid>=1000 accounts left to remove).
 sanitize_factory_baseline() {
-  local factory="$1" user
+  local factory="$1"
  btrfs property set -ts "$factory" ro false

-  for user in $(awk -F: '$3 >= 1000 && $3 < 60000 { print $1 }' "$factory/etc/passwd"); do
-    userdel --root "$factory" "$user" 2>>"$LOG_FILE" || true
-    rm -rf "${factory:?}/home/$user"
-  done
-  passwd --root "$factory" --lock root >>"$LOG_FILE" 2>&1 || true
+  if ! scrub_factory_accounts "$factory"; then
+    btrfs property set -ts "$factory" ro true
+    fail "could not remove account credentials from the factory baseline (see $LOG_FILE)"
+  fi
  rm -f "$factory"/etc/ssh/ssh_host_*
  rm -f "$factory"/etc/NetworkManager/system-connections/*
  rm -rf "$factory"/var/lib/NetworkManager/* "$factory/var/lib/tailscale" "$factory/var/lib/iwd"
@@ -345,17 +360,13 @@ stage_full_reset() {
  rm -rf "$next"/var/lib/NetworkManager/* "$next/var/lib/tailscale" "$next/var/lib/iwd"
  rm -f "$next/var/lib/sddm/state.conf" "$next/etc/sddm.conf.d/autologin.conf"

-  # A factory snapshot from a normal (normal) install contains the original
+  # A factory snapshot from a normal install contains the original
  # user account; first-boot setup must start from none. A leftover account
  # would keep its password hash and group memberships (including wheel), so
  # failure here has to abort the reset, not be shrugged off.
-  local user
-  for user in $(awk -F: '$3 >= 1000 && $3 < 60000 { print $1 }' "$next/etc/passwd"); do
-    log "Removing user $user from the factory system"
-    userdel --root "$next" "$user" 2>>"$LOG_FILE" ||
-      fail "could not remove user $user from the factory system (see $LOG_FILE)"
-  done
-  passwd --root "$next" --lock root >>"$LOG_FILE" 2>&1 || true
+  log "Removing account credentials from the factory system"
+  scrub_factory_accounts "$next" ||
+    fail "could not remove account credentials from the factory system (see $LOG_FILE)"

  # @factory itself survives the wipe as the baseline for future resets. If it
  # came from a normal install it still holds the seller's account and
@@ -1,6 +1,7 @@
 #!/bin/bash

 # omarchy:summary=Update Omarchy and system packages
+# omarchy:alias=omarchy up
 # omarchy:args=[-y]
 # omarchy:examples=omarchy update | omarchy update -y
 # omarchy:requires-sudo=true
@@ -3,6 +3,11 @@
 # omarchy:summary=Ensure the Omarchy and Arch keyring packages are installed and populated
 # omarchy:requires-sudo=true

+# omarchy-update runs this under set -e as a trusted pre-step, so a failed recv
+# or a broken keyring has to stop this script here, not surface later as
+# signature errors in the middle of the main transaction.
+set -euo pipefail
+
 if omarchy-pkg-missing omarchy-keyring || ! sudo pacman-key --list-keys 40DFB630FF42BCFFB047046CF0134EE680CAC571 &>/dev/null; then
  sudo pacman-key --recv-keys 40DFB630FF42BCFFB047046CF0134EE680CAC571 --keyserver keys.openpgp.org
  sudo pacman-key --lsign-key 40DFB630FF42BCFFB047046CF0134EE680CAC571
@@ -19,4 +24,8 @@ fi
 # Always reinstall, as the keyring can be updated without a package version bump.
 echo -e "\e[32m\nUpdate Arch signing keys\e[0m"
 sudo pacman -Sy --noconfirm archlinux-keyring >/dev/null 2> >(grep -vE '^warning: archlinux-keyring-[^ ]+ is up to date -- reinstalling$' >&2)
+
+# Say "correct" only once the key verifiably is: before the failure checks
+# above, a failed recv or reinstall still ended here with exit 0.
+sudo pacman-key --list-keys 40DFB630FF42BCFFB047046CF0134EE680CAC571 >/dev/null
 echo "Keys are correct"
@@ -1457,8 +1457,31 @@ To stop: omarchy-windows-vm stop"
  fi
  # If scale is less than 130%, don't set any scale (use default 100)

-  # Connect with RDP in fullscreen (auto-detects resolution)
-  xfreerdp3 /u:"$WIN_USER" /p:"$WIN_PASS" /v:127.0.0.1:3389 -grab-keyboard /sound /microphone /clipboard /cert:ignore /title:"Windows VM - Omarchy" /dynamic-resolution /gfx:AVC444 /floatbar:sticky:off,default:visible,show:fullscreen $RDP_SCALE
+  RDP_ARGS=(
+    "/u:$WIN_USER"
+    "/p:$WIN_PASS"
+    /v:127.0.0.1:3389
+    -grab-keyboard
+    /sound
+    /microphone
+    /clipboard
+    /cert:ignore
+    "/title:Windows VM - Omarchy"
+    /dynamic-resolution
+    /gfx:AVC444
+    /floatbar:sticky:off,default:visible,show:fullscreen
+  )
+  if [[ -n $RDP_SCALE ]]; then
+    RDP_ARGS+=("$RDP_SCALE")
+  fi
+
+  # Connect with RDP in fullscreen (auto-detects resolution). The arguments go
+  # in over stdin rather than on the command line: /proc/<pid>/cmdline is
+  # world-readable, so passing the VM password as /p:"$WIN_PASS" would show it
+  # to every other user on the machine for as long as the session is open.
+  # /args-from must stay the only argument here — FreeRDP rejects it outright
+  # when it is combined with any other, so new flags belong in RDP_ARGS above.
+  printf '%s\n' "${RDP_ARGS[@]}" | xfreerdp3 /args-from:stdin

  # After RDP closes, stop the container unless --keep-alive was specified
  if [[ $KEEP_ALIVE = "false" ]]; then
@@ -12,5 +12,5 @@
 # Rotate the currently open image by 90 degrees
 <Ctrl+r> = exec mogrify -rotate 90 "$imv_current_file"

-# Edit the current image in Tensaku and quit the viewer
-<Ctrl+e> = exec tensaku-edit "$imv_current_file" & ; quit
+# Edit the current image in Omasnap and quit the viewer
+<Ctrl+e> = exec omasnap "$imv_current_file" & ; quit
@@ -21,6 +21,9 @@
        {
          "id": "omarchy.indicators"
        },
+        {
+          "id": "omacom.elsewhen"
+        },
        {
          "id": "omarchy.clock",
          "format": "dddd HH:mm",
@@ -10,12 +10,11 @@ omarchy screenshot                            # Interactive smart-region flow
 omarchy capture screenshot region             # Select a region
 omarchy capture screenshot windows            # Pick a window
 omarchy capture screenshot fullscreen save    # Full screen, straight to disk (no editor)
+omarchy capture screenshot scroll             # Capture and stitch a scrolling region
+omarchy screenshot --editor=overlay           # Opt into annotation before output
 ```

-The first argument picks the mode (`smart|region|windows|fullscreen`), the
-second what happens with it (`slurp|copy|save`). `save` skips the annotation
-editor and prints the saved path. Screenshots land in the configured Pictures
-directory (override with `OMARCHY_SCREENSHOT_DIR`).
+The first argument picks the Omasnap mode (`smart|region|windows|fullscreen|scroll`). By default, a capture copies to the clipboard and shows a preview for 10 seconds. Use the preview's Edit action to annotate, or pass `--editor=overlay` or `--editor=window` to edit before output. A second argument of `copy` or `save` skips the preview and sends the screenshot straight to that destination. Saved screenshots land in `~/Pictures/Screenshots` by default (override with `OMASNAP_SCREENSHOT_DIR`; the legacy `OMARCHY_SCREENSHOT_DIR` is also honored by the Omarchy command).

 ## Screen Recording

@@ -33,7 +32,7 @@ Recordings land in the configured Videos directory (override with
 `omarchy capture webcam resize <smaller|larger|reset|small|medium|large>`.

 If recording fails to start, rerun with `OMARCHY_SCREENRECORD_DEBUG=true` to
-collect a log at `/tmp/omarchy-screenrecord.log` worth attaching to a bug
+collect a log at `$XDG_RUNTIME_DIR/omarchy-screenrecord.log` (or `${XDG_STATE_HOME:-$HOME/.local/state}/omarchy/omarchy-screenrecord.log` without a session runtime directory) worth attaching to a bug
 report.

 ## Text Capture (OCR)
@@ -38,7 +38,7 @@ drag-and-drop in the web form, so save the capture and hand the user the file
 path to attach (`gh` cannot upload media).

 For screen-recording failures specifically, rerun with
-`OMARCHY_SCREENRECORD_DEBUG=true` and attach `/tmp/omarchy-screenrecord.log`.
+`OMARCHY_SCREENRECORD_DEBUG=true` and attach `$XDG_RUNTIME_DIR/omarchy-screenrecord.log` (or `${XDG_STATE_HOME:-$HOME/.local/state}/omarchy/omarchy-screenrecord.log` without a session runtime directory).

 File the issue with `gh` when available:

@@ -1,2 +1,5 @@
-- Remove the 1px border around the slurp region selection used by screenshots.
+-- Remove the 1px border around the slurp region selection used by recordings, OCR, and QR capture.
 hl.layer_rule({ match = { namespace = "selection" }, no_anim = true, animation = "none" })
+
+-- Keep the Omasnap overlay immediate and out of screen shares.
+hl.layer_rule({ match = { namespace = "^omasnap$" }, no_anim = true, animation = "none", no_screen_share = true })
@@ -27,8 +27,6 @@ o.window("org.omarchy.about", { float = true })
 o.window("org.omarchy.about", { center = true })
 o.window("org.omarchy.about", { size = { 920, 480 } })

-o.window("dev.tensaku.Tensaku", { float = true })
-o.window("dev.tensaku.Tensaku", { center = true })
 o.window("omacalc", { float = true })

 -- Fullscreen screensaver.
@@ -279,8 +279,8 @@
  "install.development.javascript.node": {"icon":"","label":"Node.js","disabled":"[[ -d $HOME/.local/share/mise/installs/node ]]","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-install-dev-env node'"},
  "install.development.javascript.bun": {"icon":"","label":"Bun","disabled":"[[ -d $HOME/.local/share/mise/installs/bun ]]","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-install-dev-env bun'"},
  "install.development.javascript.deno": {"icon":"","label":"Deno","disabled":"[[ -d $HOME/.local/share/mise/installs/deno ]]","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-install-dev-env deno'"},
-  "install.development.php.php": {"icon":"","label":"PHP","disabled":"omarchy-pkg-present php","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-install-dev-env php'"},
-  "install.development.php.laravel": {"icon":"","label":"Laravel","disabled":"[[ -x $HOME/.config/composer/vendor/bin/laravel ]]","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-install-dev-env laravel'"},
+  "install.development.php.php": {"icon":"","label":"PHP","disabled":"[[ -d $HOME/.local/share/mise/installs/php ]]","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-install-dev-env php'"},
+  "install.development.php.laravel": {"icon":"","label":"Laravel","disabled":"[[ -x $HOME/.local/bin/laravel ]]","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-install-dev-env laravel'"},
  "install.development.php.symfony": {"icon":"","label":"Symfony","disabled":"omarchy-pkg-present symfony-cli","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-install-dev-env symfony'"},
  "install.development.elixir.elixir": {"icon":"","label":"Elixir","disabled":"[[ -d $HOME/.local/share/mise/installs/elixir ]]","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-install-dev-env elixir'"},
  "install.development.elixir.phoenix": {"icon":"","label":"Phoenix","disabled":"compgen -G \"$HOME/.mix/archives/phx_new*\"","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-install-dev-env phoenix'"},
@@ -347,8 +347,8 @@
  "remove.development.javascript.node": {"icon":"","label":"Node.js","when":"[[ -d $HOME/.local/share/mise/installs/node ]]","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-remove-dev-env node'"},
  "remove.development.javascript.bun": {"icon":"","label":"Bun","when":"[[ -d $HOME/.local/share/mise/installs/bun ]]","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-remove-dev-env bun'"},
  "remove.development.javascript.deno": {"icon":"","label":"Deno","when":"[[ -d $HOME/.local/share/mise/installs/deno ]]","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-remove-dev-env deno'"},
-  "remove.development.php.php": {"icon":"","label":"PHP","when":"omarchy-pkg-present php","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-remove-dev-env php'"},
-  "remove.development.php.laravel": {"icon":"","label":"Laravel","when":"[[ -x $HOME/.config/composer/vendor/bin/laravel ]]","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-remove-dev-env laravel'"},
+  "remove.development.php.php": {"icon":"","label":"PHP","when":"[[ -d $HOME/.local/share/mise/installs/php ]] || omarchy-pkg-present php","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-remove-dev-env php'"},
+  "remove.development.php.laravel": {"icon":"","label":"Laravel","when":"[[ -x $HOME/.local/bin/laravel || -x $HOME/.config/composer/vendor/bin/laravel ]]","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-remove-dev-env laravel'"},
  "remove.development.php.symfony": {"icon":"","label":"Symfony","when":"omarchy-pkg-present symfony-cli","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-remove-dev-env symfony'"},
  "remove.development.elixir.elixir": {"icon":"","label":"Elixir","when":"[[ -d $HOME/.local/share/mise/installs/elixir ]]","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-remove-dev-env elixir'"},
  "remove.development.elixir.phoenix": {"icon":"","label":"Phoenix","when":"[[ -d $HOME/.local/share/mise/installs/elixir ]]","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-remove-dev-env phoenix'"},
@@ -10,8 +10,8 @@ export TERMINAL=xdg-terminal-exec
 # Used by terminal programs to open files with the selected Omarchy default editor
 export EDITOR="omarchy-launch-editor --inline"

-# Use a custom directory for screenshots (remember to make the directory!)
-# export OMARCHY_SCREENSHOT_DIR="$HOME/Pictures/Screenshots"
+# Use a custom directory for screenshots
+# export OMASNAP_SCREENSHOT_DIR="$HOME/Pictures/Screenshots"

 # Use a custom directory for screenrecordings (remember to make the directory!)
 # export OMARCHY_SCREENRECORD_DIR="$HOME/Videos/Screencasts"
@@ -116,7 +116,6 @@ default/**                     ──►  omarchy-settings    /usr/share/omarchy
  ├─ hypr/toggles/*.lua (flags,
  │    single-window-aspect-ratio, window-no-gaps)      /etc/skel/.local/state/omarchy/toggles/hypr/
  ├─ nautilus-python/extensions/*.py                    /etc/skel/.local/share/nautilus-python/extensions/
-  ├─ tensaku/state.toml                                 /etc/skel/.local/state/tensaku/state.toml
  ├─ uwsm/env.d/10-omarchy                              /usr/share/uwsm/env.d/
  ├─ environment.d/*.conf                               /usr/lib/environment.d/
  ├─ fontconfig/conf.avail/50-omarchy.conf              /usr/share/fontconfig/conf.avail/
@@ -20,7 +20,17 @@ wait).
  "author": "You",
  "description": "A clock that does cool things",
  "kinds": ["bar-widget"],
-  "entryPoints": { "barWidget": "Widget.qml" }
+  "entryPoints": { "barWidget": "Widget.qml" },
+  "barWidget": {
+    "displayName": "Cool clock",
+    "category": "Time",
+    "allowMultiple": false,
+    "defaultSection": "left",
+    "defaults": { "format": "HH:mm" },
+    "schema": [
+      { "key": "format", "type": "string", "label": "Format" }
+    ]
+  }
 }
 ```

@@ -37,7 +47,7 @@ wait).

 Only one full bar option is active at a time. The built-in `omarchy.bar` is
 used when `bar.id` is omitted or when a selected third-party bar cannot load.
-Panels, overlays, and menus are loaded when summoned. Plugins can set the top-level manifest key `keepLoaded: true` to survive between summons, and to keep a service mounted across plugin hot-reload (so `omarchy.lock` is not destroyed while Hyprland still holds the session lock). First-party services are loaded at startup.
+Panels, overlays, and menus are loaded when summoned. Plugins can set the top-level manifest key `keepLoaded: true` to survive between summons, and to keep a service mounted across plugin hot-reload (so `omarchy.lock` is not destroyed while Hyprland still holds the session lock). The kept service instance is not replaced, so changes to its code take effect on a shell restart. First-party services are loaded at startup.

 Entry points are QML `Item`s. Panel, overlay, and menu entry points expose `open(payloadJson)` and `close()` for summon/hide; on load the host injects `omarchyPath`, `shell`, `manifest`, and the registries (`pluginRegistry` / `barWidgetRegistry`) as properties. Built-in plugins receive the trusted host objects. Third-party plugins receive capability-scoped facades instead: ordinary plugins may look up and control only their own service and lifecycle, built-in clones retain narrow source-specific configuration and UI compatibility, menu plugins receive an application-library facade, and plugins can read detached scalar bar state. A full-bar plugin additionally receives detached bar configuration and widget-catalog snapshots, narrow proxies for the non-authentication services used by built-in bar widgets, and lifecycle control over configured non-authentication UI plugins. Authentication capabilities are stamped from trusted first-party manifests, authentication services are kept out of the host's public service map and QML object tree, and third-party registry/configuration snapshots can be changed only locally without mutating host state. The facades are API boundaries, not same-process QML sandboxes: a visual widget shares the host bar's scene and can walk its parent hierarchy to ordinary host objects. Sensitive state must not rely on the facade alone for isolation.

@@ -88,6 +98,10 @@ bar from the CLI — `use | reset | defaults | position | transparent | put |
 move | set`, with placement flags such as `--section` and `--index`.
 The lower-level IPC methods remain available through `omarchy-shell shell ...`.

+## Elsewhen
+
+Elsewhen (`omacom.elsewhen`) ships in the `elsewhen` package at `/usr/share/omarchy/shell/plugins/omacom.elsewhen`, where the shell discovers it automatically. New installs place it immediately before the clock; the migration uses `omarchy bar put omacom.elsewhen --before omarchy.clock`, which preserves an existing placement and uses Elsewhen's normal right-side placement if the clock is absent. Existing plugin directories and symlinks are left intact. The normal update flow restarts the shell after migrations; the migration does not interrupt plugin loading with an immediate restart.
+
 ## IPC

 The shell exposes a `shell` target (the host also registers
@@ -52,6 +52,7 @@ directory or an installed Omarchy.
 Assertions are TAP-flavored and blunt:

 - `pass "description"` prints `ok - description`.
+- `skip "description"` prints `ok - description # SKIP`. Include why the check could not run. Like `pass`, it returns normally; use `exit 0` afterwards only when the rest of the file cannot run either.
 - `fail "description" [detail]` prints the optional detail and
  `not ok - description` to stderr, then **exits the file**. There is no
  counting or continuing within a file: the first failed assertion ends it,
@@ -59,19 +60,13 @@ Assertions are TAP-flavored and blunt:
  already invalidated.
 - `require_command <cmd>` fails the file when a needed tool is absent.

-The runner compensates for that early exit: `./test/shell` continues past a
-failing file and summarizes the failures at the end. Aborting the whole run at
-the first bad file once let a single packaging failure mask 114 of 134 files.
-Failure granularity is therefore per file inside a run, per assertion inside a
-file.
+The runner compensates for that early exit: `./test/shell` continues past a failing file and summarizes the failures at the end. Aborting the whole run at the first bad file once let a single packaging failure mask 114 of 134 files. Failure granularity is therefore per file inside a run, per assertion inside a file.
+
+The runner also lists files with skipped checks, including files that ran some checks or later failed. Skips do not fail a run. When no files fail, a run with skips is reported as completed without failures rather than having passed every check.

 ## Compositor-dependent tests

-Some tests launch Quickshell or query Hyprland, but the suite must stay green
-on headless machines. `require_compositor "description"` handles this: when no
-compositor answers it prints `ok - no Wayland compositor; skipping ...` and
-exits 0 — a skip is a passing test — and otherwise returns so the file
-proceeds.
+Some tests launch Quickshell or query Hyprland, but the suite must stay green on headless machines. `require_compositor "description"` handles this: when no compositor answers it calls `skip` with the reason and exits 0, and otherwise returns so the file proceeds. The skip marker lets the runner distinguish unavailable runtime coverage from checks that passed.

 The probe is more than an environment check, because `WAYLAND_DISPLAY` only
 proves the variable was inherited. Sandboxes pass the environment through
@@ -119,6 +114,7 @@ only a live session can prove.

 ## Conventions worth copying

+- **Redirect background output.** Send background fixtures' stdout to a log or `/dev/null` and clean up the processes on exit. An inherited output pipe can hold the runner open after the test exits.
 - **Stub the world, run the real code.** Tests build a scratch `bin/` of stub
  executables (`sudo`, `tmux`, `gsettings`, helper commands) that log their
  arguments to a file, prepend it to `PATH`, and then run the real script
@@ -1,6 +1,12 @@
 # Solve common flakiness with SSH (MTU discovery on flaky links).
 net.ipv4.tcp_mtu_probing=1

+# BBR estimates bottleneck bandwidth and minimum RTT and paces to them, where
+# cubic keeps pushing until packets drop. That cuts queueing latency
+# (bufferbloat) on fast links. fq is the qdisc BBR is built to pace through.
+net.core.default_qdisc=fq
+net.ipv4.tcp_congestion_control=bbr
+
 # Tune reclaim for swap on zram, which is orders of magnitude faster than the
 # disk swapfile these defaults assume.

@@ -6,5 +6,5 @@ pci_info=$(lspci -nn)

 if (echo "$pci_info" | grep -q "14e4:43a0" || echo "$pci_info" | grep -q "14e4:4331"); then
  echo "BCM4360 / BCM4331 detected"
-  omarchy-pkg-add broadcom-wl-dkms linux-headers
+  omarchy-pkg-add broadcom-wl-dkms
 fi
@@ -4,8 +4,7 @@
 # v4l2-relayd re-exposes it at 1280x720 under the same name.

 if omarchy-hw-elgato-camlink-4k; then
-  mapfile -t kernel_headers < <(pacman -Qqs '^linux(-zen|-lts|-hardened|-t2|-ptl|-omarchy(-bore|-ptl-novrr-mm)?)?$' | sed 's/$/-headers/')
-  omarchy-pkg-add "${kernel_headers[@]}" v4l2loopback-dkms v4l2loopback-utils v4l2-relayd
+  omarchy-pkg-add v4l2loopback-dkms v4l2loopback-utils v4l2-relayd

  sudo install -Dm644 "$OMARCHY_PATH/default/udev/elgato-camlink-4k.rules" /etc/udev/rules.d/71-elgato-camlink-4k.rules
  sudo install -Dm644 "$OMARCHY_PATH/default/v4l2-relayd/camlink.conf" /etc/v4l2-relayd.d/camlink.conf
@@ -1,7 +1,7 @@
 # Install Tuxedo drivers for keyboard backlighting on Tuxedo laptops and
 # compatible devices like the Slimbook Executive (Clevo/Tuxedo chassis).
 if cat /sys/class/dmi/id/sys_vendor 2>/dev/null | grep -qi "TUXEDO\|Slimbook"; then
-  omarchy-pkg-add linux-headers tuxedo-drivers-nocompatcheck-dkms
+  omarchy-pkg-add tuxedo-drivers-nocompatcheck-dkms

  # Blacklist the legacy clevo_xsm_wmi module which conflicts with the tuxedo-drivers
  # clevo_wmi module. When clevo_xsm_wmi loads first, it grabs the Clevo WMI GUIDs,
@@ -1,4 +1,4 @@
 # Install drivers for Motorcomm YT6801 ethernet adapter used by the Slimbook Executive
 if lspci | grep -i "YT6801\|Motorcomm.*Ethernet"; then
-  omarchy-pkg-add linux-headers yt6801-dkms
+  omarchy-pkg-add yt6801-dkms
 fi
@@ -1,8 +1,4 @@
 if lspci | grep -qi 'nvidia'; then
-  # Check which kernel is installed and set appropriate headers package
-  KERNEL_PACKAGE=$(pacman -Qqs '^linux(-zen|-lts|-hardened|-t2|-ptl|-omarchy(-bore|-ptl-novrr-mm)?)?$' | head -1 || true)
-  [[ -n $KERNEL_PACKAGE ]] && omarchy-pkg-add "$KERNEL_PACKAGE-headers"
-
  if omarchy-hw-nvidia-gsp; then
    PACKAGES=(nvidia-open-dkms nvidia-utils lib32-nvidia-utils libva-nvidia-driver)
  elif omarchy-hw-nvidia-without-gsp; then
@@ -26,6 +26,7 @@ docker-compose
 dosfstools
 dotnet-runtime
 dua-cli
+elsewhen
 evince
 exfatprogs
 expac
@@ -95,6 +96,10 @@ omacalc
 omacut
 omawrite
 omarchy-nvim
+omasnap
+# OWE owns desktop video backgrounds and feeds the lock screen its frames.
+owe
+owe-lockfeed
 pacman-contrib
 pamixer
 pinta
@@ -108,12 +113,9 @@ ttfx
 qemu-user-static-binfmt
 qrencode
 qt6-imageformats
-qt6-multimedia
-qt6-multimedia-ffmpeg
 quickshell
 ripgrep
 ruby
-tensaku
 sddm
 slurp
 socat
@@ -20,9 +20,7 @@ libva-nvidia-driver
 limine
 limine-mkinitcpio-hook
 limine-snapper-sync
-linux
 linux-firmware
-linux-headers
 linux-omarchy
 linux-omarchy-headers
 macbook12-spi-driver-dkms
@@ -14,9 +14,12 @@ set -euo pipefail
 systemctl --user daemon-reload
 systemctl --user enable --now \
  bt-agent.service \
+  owed.service \
  omarchy-recover-internal-monitor.service \
  omarchy-sleep-lock.service \
  omarchy-migrate-notify.service \
  omarchy-fcitx5.service \
  omarchy-crash-watch.service \
  omarchy-usb-authorization.service
+
+omarchy-hook-install theme-set /usr/share/owe/10-owe-sync
@@ -2,13 +2,6 @@
 mkdir -p "$HOME/Work"
 mkdir -p "$HOME/Work/tries"

-cat >"$HOME/Work/.mise.toml" <<'EOF'
-[env]
-_.path = "{{ cwd }}/bin"
-EOF
-
-mise trust ~/Work/.mise.toml
-
 # Offline installs unpack the Node tarball bundled by the ISO: from
 # /opt/packages in the ISO chroot, or from the copy staged in provisioning state when
 # omarchy-provision-owner finalizes the user at first boot.
@@ -37,6 +30,11 @@ if [[ -n $NODE_PACKAGE_DIR ]]; then
    mkdir -p "$NODE_INSTALL_DIR"
    tar -xzf "$NODE_TARBALL" --strip-components=1 -C "$NODE_INSTALL_DIR"
    mise use -g node@"$NODE_VERSION"
+
+    # That pinned the exact bundled version, which would exempt Node from
+    # mise up forever. Loosen it to latest, like an online install gets:
+    # mise resolves latest to the installed version while offline.
+    mise config set tools.node latest --file "$HOME/.config/mise/config.toml"
  fi
 else
  mise use -g node@latest
@@ -13,13 +13,15 @@ Everything you can grab off the screen hangs off the Print Screen key. One key o

 ## Screenshots

-Hit `Print Screen` and the screen freezes so nothing shifts under you while you aim. Drag a box for a freeform region, or just click once and the shot snaps to whatever rectangle you clicked in — a window if you landed on one, the whole monitor if you landed on the bar or in a gap. Changed your mind? Hit `Print Screen` again to dismiss the picker.
+Hit `Print Screen` and Omasnap captures the focused monitor before its overlay appears, so nothing shifts under you while you aim. Drag a freeform region, click a window to capture it, or click open space to capture the whole monitor. Press `S` before drawing to capture a scrolling region. Changed your mind? Hit `Print Screen` again to dismiss Omasnap.

-The result goes two places at once: a PNG in your pictures directory, and the clipboard, so you can paste it straight into a chat window with `Super + V`. A notification pops up with a thumbnail. Click it (or hit `Super + Alt + ,` to invoke the last notification) and the shot opens in Tensaku, the annotation editor, where you can draw arrows and boxes on it before you send it.
+After you select an area, Omasnap copies the capture to the clipboard and shows a preview for 10 seconds. Use the preview's pin button or `Ctrl + P` to keep it on screen, or choose Edit to annotate it.

-Files land in `~/Pictures` by default, named `screenshot-2026-08-13_14-22-05.png`. If you'd rather keep them in their own folder, set `OMARCHY_SCREENSHOT_DIR` — see [the FAQ](46-faq.md) for where to put session environment variables. Omarchy creates the directory for you if it isn't there. You can swap the editor too with `OMARCHY_SCREENSHOT_EDITOR`.
+The annotation editor can draw arrows, lines, shapes, highlights, numbered markers, text, and secure redactions; crop or cut out part of the image; OCR its text; and add a backdrop. In the editor, press `Enter` to copy and save the finished PNG, `Ctrl + C` to copy it without saving, or `Ctrl + S` to save it without copying.

-From the terminal, `omarchy screenshot` takes the same shot, and you can be explicit about it: `omarchy capture screenshot region` for freeform only, `windows` to snap to window and monitor rectangles, or `fullscreen` to skip the picker entirely and grab the focused monitor. A second argument of `copy` puts the shot only on the clipboard, and `save` only on disk.
+Saved screenshots land in `~/Pictures/Screenshots` by default, with a name such as `screenshot-2026-08-13_14-22-05-firefox.png`. Set `OMASNAP_SCREENSHOT_DIR` to use another directory — see [the FAQ](46-faq.md) for where to put session environment variables. Omasnap creates the directory when it saves the first shot.
+
+From the terminal, `omarchy screenshot` opens the same overlay, and you can choose its starting mode: `omarchy capture screenshot region`, `windows`, `fullscreen`, or `scroll`. A second argument of `copy` or `save` skips the preview and sends the shot straight to that destination. To edit before output, use `omarchy screenshot --editor=overlay` for a fullscreen editor or `omarchy screenshot --editor=window` for a separate window.

 ### Driving the picker from the keyboard

@@ -27,16 +29,18 @@ While the selection is up, you don't have to use the mouse at all:

 | Key | Function |
 | --- | -------- |
+| `S` | Toggle scrolling-region mode |
+| `Super + Arrow keys` | Move among windows in Window mode |
 | `Return` | Capture the highlighted window |
-| `Ctrl + Return` | Capture the whole screen |
-| `Tab` / `Ctrl + Tab` | Highlight the next / previous window |
-| Arrow keys | Highlight the window in that direction |
+| `Ctrl + A` | Capture the full focused monitor |
+| `R` | Restore the last region drawn in this session |
+| `Esc` | Dismiss Omasnap |

-The arrows and Tab move the cursor to the window they pick, so the highlight follows along and you can see what you're about to capture. These bindings only exist while a selection is on screen, so they can't collide with anything in your own config.
+These bindings only exist while Omasnap is open, so they can't collide with anything in your own config.

 ## Screen recording

-`Alt + Print Screen` opens _Trigger > Capture > Screenrecord_, which asks what you want on the soundtrack: no audio, desktop audio, desktop plus microphone, or desktop plus microphone plus webcam. That last one only shows up if you actually have a camera plugged in. Pick one and you get the same picker as a screenshot: drag a region, or click a window or monitor.
+`Alt + Print Screen` opens _Trigger > Capture > Screenrecord_, which asks what you want on the soundtrack: no audio, desktop audio, desktop plus microphone, or desktop plus microphone plus webcam. That last one only shows up if you actually have a camera plugged in. Pick one and Omarchy's recording picker lets you drag a region or click a window or monitor.

 Recording runs on gpu-screen-recorder, which encodes on the GPU at 60fps and falls back to the CPU if it has to. The result is an MP4 in `~/Videos`, named `screenrecording-2026-08-13_14-22-05.mp4`. Set `OMARCHY_SCREENRECORD_DIR` to change that — but note that unlike the screenshot directory, this one has to exist already, or the recording refuses to start.

@@ -50,7 +50,7 @@ Capture commands — Screenshots and screen recording:
  omarchy capture qr                                                                                                                                                                                                       Decode a QR code from a screenshot region
  omarchy capture screenrecording [--fullscreen] [--with-desktop-audio] [--with-microphone-audio] [--with-webcam] [--webcam-device=<device>] [--webcam-size=<small|medium|large>] [--resolution=<size>] [--stop-recording]  Start or stop screen recording
  omarchy capture screenrecording with webcam                                                                                                                                                                              Pick a webcam and start a screen recording with it
-  omarchy capture screenshot [smart|region|windows|fullscreen] [slurp|copy|save] [--editor=<name>]                                                                                                                         Take a screenshot
+  omarchy capture screenshot [smart|region|windows|fullscreen|scroll] [copy|save]                                                                                                                                          Take a screenshot
  omarchy capture text                                                                                                                                                                                                     Extract text from a screenshot region with OCR
  omarchy capture webcam resize <smaller|larger|reset|small|medium|large>                                                                                                                                                  Resize the active webcam recording overlay
 ```
@@ -26,6 +26,8 @@ To wrap an additional CLI the same way, run `omarchy-mise-install <package> [com

 Pick your default agent with `omarchy default agent <name>` or under _Setup > Defaults > Agent_ in the Omarchy Menu (`Super + Space`). If the agent isn't installed yet, picking it installs it first. A fresh Omarchy will invite you to make this choice with a one-time notification.

+Choosing Claude also attempts to set up its browser extension for Chromium, Chrome, Brave, Brave Origin, and Edge. The extension setup applies to all users and may ask for your system password; cancelling or a failed extension install still selects and launches Claude. Restart your browser, enable the extension if prompted, and sign in to Claude to finish connecting it. Run `/chrome` in Claude to check the connection. Firefox and Zen do not support this extension. If Claude was already your default before this setup was added, select it again to install the extension.
+
 [Muse Code](https://dev.meta.ai) — Meta's `muse` — uses a preinstalled mise stub like the other agents. Picking it as the default installs Meta's official launcher through mise's HTTP backend. The launcher verifies and updates the native binary for your machine.

 Once you've chosen, `Super + Shift + Ctrl + A` launches the default agent in a dedicated terminal window (or brings up the picker if you haven't chosen yet). You can also launch it straight into a task with `omarchy agent prompt "Review this project"`. Agents launched this way run unattended in their respective don't-stop-to-ask modes, so be ready for them to actually do things! And since agents refuse to remember trust for your home directory, launches from `$HOME` start in `~/Work` instead.
@@ -57,3 +57,5 @@ The full manual can be found via `man yt-dlp`.
 ## try

 [try](https://github.com/tobi/try) makes it easy to manage programming experiments with date-stamped directories. All experiments live in `~/Work/tries` and you can access them via `try`.
+
+Omarchy does not add a project's `bin/` directory to `PATH` automatically. Run trusted project-local tools with an explicit relative path, such as `bin/rails` or `./bin/dev`.
@@ -95,7 +95,7 @@ omarchy plugin validate ./my-plugin

 That runs the same checks the shell does at load time: the schema version, the required fields, an id that isn't reserved, entry points that are safe relative paths and actually exist, an entry point for every kind you claimed, and no symlinks anywhere inside the folder.

-For the full picture, the source is the documentation: `shell/README.md` in the Omarchy repo covers the manifest schema, the shell's IPC contract, and the exact shape of `shell.json`, and `shell/plugins/README.md` lists every first-party plugin with its id, kinds, and entry points.
+For plugin development, see the [shell reference](https://github.com/omacom/omarchy/blob/quattro/docs/omarchy-shell.md) and [first-party plugin catalog](https://github.com/omacom/omarchy/blob/quattro/shell/plugins/README.md).

 ## Sharing yours with the world

@@ -4,6 +4,8 @@ Every theme ships with its own set of backgrounds, and you can add extras of you

 You can do this most easily by going to _Install > Style > Background_ in the Omarchy Menu. That'll bring up the folder where the backgrounds for that theme is stored. Hit `Super + Shift + F` to start another file manager, find your background, copy it over.  Now it'll be included in the choices of backgrounds you can select between using `Super + Ctrl + Space`.

-Backgrounds can be videos as well as stills. Drop an `mp4`, `m4v`, `mov`, `webm`, `mkv`, or `avi` file in the same folder and it appears alongside the images, playing on a loop. Only your first monitor's wallpaper plays a video's sound track, through the default audio output at the system volume, and the lock screen stays silent. Playback stops on its own whenever nothing can see it — while a fullscreen window covers that monitor, while the screensaver is up, and once a locked screen has gone dark — but a video wallpaper still costs far more power than a still one, and each monitor decodes its own copy.
+Backgrounds can be videos as well as stills. Drop an `mp4`, `m4v`, `mov`, `webm`, `mkv`, or `avi` file in the same folder and it appears alongside the images. Videos are played by the OWE wallpaper engine. It decodes the video once for all monitors and plays its sound through the default audio output, and it stops playback whenever nothing can see it. The lock screen draws the same decode, muted, through OWE. A video wallpaper still costs far more power than a still one.

 You can find a huge collection of cool curated backgrounds on https://github.com/dharmx/walls.
+
+Video backgrounds keep a cached still on the lock screen while playback is paused or unavailable. Animated GIFs play on the desktop and show a still frame on the lock screen.
@@ -54,15 +54,15 @@ Automatic discovery, where printers on the network appear without being added, i

 ### How do I change where screenshots or screenrecordings are saved?

-If you want screenshots to be saved to `~/Pictures/Screenshots` instead of just `~/Pictures`, you can add this to a file under `~/.config/uwsm/env.d/` (like `~/.config/uwsm/env.d/capture`):
+Saved screenshots go to `~/Pictures/Screenshots` by default. To use another directory, add this to a file under `~/.config/uwsm/env.d/` (like `~/.config/uwsm/env.d/capture`):

 ```
-export OMARCHY_SCREENSHOT_DIR="$HOME/Pictures/Screenshots"
+export OMASNAP_SCREENSHOT_DIR="$HOME/Pictures/Captures"
 ```

 You can do the same for screenrecordings using `OMARCHY_SCREENRECORD_DIR`.

-Just remember to create the directory you want to save to and restart Omarchy for this to take effect.
+Omasnap creates its screenshot directory automatically. Create the screenrecording directory yourself, then restart Omarchy for either environment change to take effect.

 ### How do I get the speakers + webcam working on my Apple Studio Display?

@@ -1,3 +1 @@
-echo "Install native video wallpaper playback dependencies"
-
-omarchy-pkg-add qt6-multimedia qt6-multimedia-ffmpeg
+echo "Native video dependencies are superseded by the OWE migration"
@@ -0,0 +1,18 @@
+echo "Replace Satty and Tensaku with Omasnap"
+
+omarchy-pkg-add omasnap
+
+# The old source installer left a NoDisplay entry that overrides the packaged launcher.
+rm -f "$HOME/.local/share/applications/omasnap.desktop"
+
+imv_config="$HOME/.config/imv/config"
+if [[ -f $imv_config ]]; then
+  sed -i --follow-symlinks \
+    -e 's/^# Edit the current image in Tensaku and quit the viewer$/# Edit the current image in Omasnap and quit the viewer/' \
+    -e 's/^# Edit the current image in Satty and quit the viewer$/# Edit the current image in Omasnap and quit the viewer/' \
+    -e 's|^<Ctrl+e> = exec tensaku-edit "$imv_current_file" & ; quit$|<Ctrl+e> = exec omasnap "$imv_current_file" \& ; quit|' \
+    -e 's|^<Ctrl+e> = exec satty --filename "$imv_current_file" & ; quit$|<Ctrl+e> = exec omasnap "$imv_current_file" \& ; quit|' \
+    "$imv_config"
+fi
+
+omarchy-pkg-drop satty tensaku
@@ -0,0 +1,99 @@
+echo "Remove automatic project bin directories from PATH"
+
+work_dir="$HOME/Work"
+mise_config="$work_dir/.mise.toml"
+# install/user/mise-work.sh as shipped in Omarchy 4.0.3.
+stock_sha="bd04f191d63bbde86920f44f76f0989fad980afc84e268e8474c201ec7149245"
+cwd_bin='\{\{[[:space:]]*cwd[[:space:]]*\}\}/bin'
+unsafe_path="^[[:space:]]*_[.]path[[:space:]]*=[[:space:]]*(\"$cwd_bin\"|'$cwd_bin')[[:space:]]*(#.*)?$"
+env_section='^[[:space:]]*\[[[:space:]]*env[[:space:]]*\][[:space:]]*(#.*)?$'
+any_section='^[[:space:]]*\[\[?.*\]\]?[[:space:]]*(#.*)?$'
+
+remove_empty_work_dir=false
+if [[ ! -e $work_dir ]]; then
+  mkdir -p "$work_dir"
+  remove_empty_work_dir=true
+fi
+
+was_ignored=false
+if [[ -d $work_dir ]]; then
+  mise_state_dir=${MISE_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/mise}
+  ignored_configs_dir="$mise_state_dir/ignored-configs"
+  work_target=$(readlink -m "$work_dir")
+  config_path_target="$work_target/.mise.toml"
+  config_target=$(readlink -m "$mise_config")
+
+  if [[ -d $ignored_configs_dir ]]; then
+    for ignored_entry in "$ignored_configs_dir"/*; do
+      [[ -L $ignored_entry ]] || continue
+      ignored_target=$(readlink "$ignored_entry")
+      if [[ $ignored_target == $work_target || $ignored_target == $config_path_target || $ignored_target == $config_target ]]; then
+        was_ignored=true
+        break
+      fi
+    done
+  fi
+
+  if [[ $was_ignored == "false" ]]; then
+    # Normal Mise trust is recorded against the config-root directory, while
+    # paranoid trust is recorded against the file and its contents. Stage an
+    # empty, inert config when the legacy file is gone so either trust mode can
+    # resolve and revoke the original grant.
+    remove_empty_mise_config=false
+    if [[ ! -e $mise_config && ! -L $mise_config ]]; then
+      if (set -o noclobber; : >"$mise_config") 2>/dev/null; then
+        remove_empty_mise_config=true
+      fi
+    fi
+
+    untrust_target="$work_dir"
+    if [[ -f $mise_config ]]; then
+      untrust_target="$mise_config"
+    fi
+
+    if mise trust --untrust "$untrust_target"; then
+      :
+    else
+      if [[ $remove_empty_mise_config == "true" ]]; then
+        rm -f -- "$mise_config"
+      fi
+      exit 1
+    fi
+
+    if [[ $remove_empty_mise_config == "true" ]]; then
+      rm -f -- "$mise_config"
+    fi
+  fi
+fi
+
+if [[ -f $mise_config ]]; then
+  if [[ ! -L $mise_config && $(sha256sum "$mise_config" | cut -d ' ' -f 1) == $stock_sha ]]; then
+    rm -f -- "$mise_config"
+  else
+    unsafe_env_paths=$(sed -n -E "\\%$env_section%,\\%$any_section% { \\%$unsafe_path%p; }" "$mise_config")
+    if [[ -n $unsafe_env_paths ]]; then
+      backup=$(mktemp "$mise_config.bak.XXXXXX")
+      cp -p -- "$mise_config" "$backup"
+      sed --follow-symlinks -i -E "\\%$env_section%,\\%$any_section% { \\%$unsafe_path%d; }" "$mise_config"
+
+      printf '\n%s\n' \
+        "Automatic project bin directories were removed from your Mise PATH." \
+        "Your other Mise settings were preserved."
+      printf '\nBackup saved to:\n  %s\n' "$backup"
+    fi
+  fi
+fi
+
+if [[ -f $mise_config ]]; then
+  if [[ $was_ignored == "true" ]]; then
+    printf '\n%s\n' "This custom config remains ignored by Mise."
+  else
+    printf '\n%s\n  %s\n' \
+      "Mise trust for this custom config was revoked. Review it before trusting it again:" \
+      "mise trust $mise_config"
+  fi
+fi
+
+if [[ $remove_empty_work_dir == "true" ]]; then
+  rmdir "$work_dir" 2>/dev/null || true
+fi
@@ -0,0 +1,11 @@
+echo "Switch TCP congestion control to BBR with fq pacing"
+
+# Boot applies the shipped file regardless; this only makes new connections
+# use BBR now. Setting the sysctls autoloads tcp_bbr and sch_fq. Qdiscs
+# already attached to interfaces stay until they are recreated, normally at
+# reboot.
+if [[ $(sysctl -n net.ipv4.tcp_congestion_control) == "bbr" && $(sysctl -n net.core.default_qdisc) == "fq" ]]; then
+  exit 0
+fi
+
+sudo sysctl -p /etc/sysctl.d/99-omarchy-sysctl.conf >/dev/null || omarchy-state set reboot-required
@@ -0,0 +1,10 @@
+echo "Install missing headers for the Omarchy or T2 kernel"
+
+# Fresh ISO installs mark earlier migrations complete, so the kernel migration
+# cannot repair headers omitted by those installers. Package installation is
+# idempotent when another user has already applied this repair.
+for kernel in linux-omarchy linux-t2; do
+  if omarchy-pkg-present "$kernel"; then
+    omarchy-pkg-add "$kernel-headers"
+  fi
+done
@@ -0,0 +1,14 @@
+echo "Install Elsewhen, the world clock plugin"
+
+omarchy-pkg-add elsewhen
+
+# Dev checkouts do not contain plugins installed by system packages.
+packaged_plugin="/usr/share/omarchy/shell/plugins/omacom.elsewhen"
+user_plugin="$HOME/.config/omarchy/plugins/omacom.elsewhen"
+if [[ ! $OMARCHY_PATH -ef /usr/share/omarchy && -d $packaged_plugin && ! -e $user_plugin && ! -L $user_plugin ]]; then
+  mkdir -p "${user_plugin%/*}"
+  ln -s "$packaged_plugin" "$user_plugin"
+fi
+
+omarchy-shell shell rescanPlugins
+omarchy-bar put omacom.elsewhen --before omarchy.clock
@@ -0,0 +1,17 @@
+echo "Enable OWE desktop video backgrounds and lock feed"
+
+omarchy-pkg-add owe owe-lockfeed
+omarchy-hook-install theme-set /usr/share/owe/10-owe-sync
+
+systemctl --user daemon-reload >/dev/null 2>&1 || true
+if ! systemctl --user enable owed.service; then
+  wants_dir="$HOME/.config/systemd/user/graphical-session.target.wants"
+  mkdir -p "$wants_dir"
+  ln -sfn /usr/lib/systemd/user/owed.service "$wants_dir/owed.service"
+fi
+
+# A TTY update enables the next graphical login without starting a renderer
+# against a missing Wayland session. A failed live start leaves this pending.
+if [[ ${OMARCHY_UPGRADE_TO_QUATTRO_LIVE:-0} != 1 ]] && systemctl --user is-active --quiet graphical-session.target; then
+  systemctl --user start owed.service
+fi
@@ -61,7 +61,7 @@ QtObject {
  // Run an argv vector without a shell interpreting it: the constant `exec "$@"`
  // means the args only ever land in positional parameters, which bash expands
  // without re-tokenizing — so untrusted data ($(id), a filename) stays literal.
-  // The login shell (-l) keeps the PATH/session env GUI targets (tensaku, mpv,
+  // The login shell (-l) keeps the PATH/session env GUI targets (omasnap, mpv,
  // xdg-open) need. Prefer this over execDetached for anything built from input.
  function execArgv(argv) {
    Quickshell.execDetached(["bash", "-lc", 'exec "$@"', "bash"].concat(argv))
@@ -1,302 +1,9 @@
 # Omarchy shell

-`omarchy-shell` is a single long-running [Quickshell](https://quickshell.org/)
-instance that hosts the Omarchy desktop. Hyprland autostart launches one shell
-per graphical session; everything else — the bar, background switcher, panels,
-and overlays — runs **inside** the shell as a plugin.
+The Omarchy desktop runs in one long-lived Quickshell process. Its bar, panels, overlays, menus, and services are plugins hosted by `shell.qml`.

-Hosting everything inside one shell means:
-
- shared services and singletons live once, not once per process
- summoning a panel is an IPC call into a process that is already running,
-  not a fresh `quickshell -p ...` cold start
- third-party plugins can be loaded from disk without changing any source
-  code in Omarchy itself
-
-The runtime layout:
-
-```
-shell/
-  shell.qml              entry point (ShellRoot)
-  services/
-    PluginRegistry.qml   discovers, validates plugins, looks up enabled state in shell.json
-    BarWidgetRegistry.qml unified registry for bar widgets (1p + 3p)
-  plugins/
-    bar/                 first-party plugins (see plugins/README.md)
-    image-picker/
-    menu/
-    notifications/
-    panels/
-      audio/
-      bluetooth/
-      monitor/
-      network/
-      power/
-      weather/
-    agents/
-    services/
-      battery/
-      idle/
-    osd/
-    polkit/
-```
-
-The plugin discovery path is documented in [plugins/README.md](plugins/README.md).
-
-## Plugin manifest
-
-Every plugin ships a `manifest.json` describing what it is and how the
-shell should load it. Minimal example:
-
-```json
-{
-  "schemaVersion": 1,
-  "id": "my.org.cool-clock",
-  "name": "Cool clock",
-  "version": "1.0.0",
-  "author": "You",
-  "description": "A clock that does cool things",
-  "kinds": ["bar-widget"],
-  "entryPoints": { "barWidget": "Widget.qml" },
-  "barWidget": {
-    "displayName": "Cool clock",
-    "category": "Time",
-    "allowMultiple": false,
-    "defaultSection": "left",
-    "defaults": { "format": "HH:mm" },
-    "schema": [
-      { "key": "format", "type": "string", "label": "Format" }
-    ]
-  }
-}
-```
-
-Supported `kinds`:
-
-| Kind         | What it is                                                   |
-|--------------|--------------------------------------------------------------|
-| `bar-widget` | A component that the active bar can drop into a section      |
-| `panel`      | A persistent or summoned floating window (e.g. OSD)          |
-| `overlay`    | A fullscreen overlay (e.g. background switcher)              |
-| `menu`       | A summoned menu surface                                      |
-| `service`    | A headless singleton, no UI                                  |
-| `bar`        | A full bar option that can replace the built-in `omarchy.bar` |
-
-Only one `bar` plugin is active at a time. Missing or invalid selections fall
-back to the built-in `omarchy.bar`, so users always have a safe path home.
-Panels, overlays, and menus are loaded when summoned. Plugins that need
-to outlive a single summon can set `keepLoaded: true` (e.g. the image
-picker keeps its overlay window mounted between summons). The same flag
-keeps a service mounted across plugin hot-reload, so tearing down a
-changed bar widget cannot destroy `omarchy.lock` while Hyprland still
-holds the session lock. The kept instance is not replaced, so code
-changes to a `keepLoaded` service itself only take effect on a shell
-restart. First-party services are loaded at startup.
-
-Entry points may declare `omarchyPath`, `shell`, `manifest`, `pluginRegistry`, and `barWidgetRegistry` properties for host injection. Built-in plugins receive the trusted host objects. Third-party plugins receive capability-scoped facades: ordinary plugins can look up and control only their own service and lifecycle, built-in clones retain narrow source-specific configuration and UI compatibility, menu plugins receive an application-library facade, and plugins can read detached scalar bar state. A full-bar plugin additionally receives detached bar configuration and widget-catalog snapshots, narrow proxies for the non-authentication services used by built-in bar widgets, and lifecycle control over configured non-authentication UI plugins. Authentication capabilities are stamped from trusted first-party manifests, authentication services are retained outside the host's public service map and QML object tree, and changing a third-party registry or configuration snapshot cannot mutate host state. Facades do not isolate visual widgets from the parent hierarchy of the shared QML scene, so sensitive state must remain outside that reachable graph.
-
-Widgets rendered by a third-party replacement bar receive a service-less entry facade with target-scoped lifecycle and settings operations. Their live service objects are available only when the trusted built-in bar hosts them; otherwise the replacement bar could request and retain any configured widget's service.
-
-The full schema lives in `services/PluginRegistry.qml`.
-
-## Installing a third-party plugin
-
-A plugin is a **git repo** with a `manifest.json` at its root. Adding one
-clones it straight into `~/.config/omarchy/plugins/<id>/` (named by the
-manifest id); updating is a fast-forward pull of that checkout.
-
-```bash
-omarchy plugin add https://github.com/acme/omarchy-weather.git
-omarchy plugin update acme.weather       # fetches, shows a diff, fast-forwards
-omarchy plugin update                    # updates every git-managed plugin
-omarchy plugin remove acme.weather
-```
-
-> ⚠️ **Plugins run as unsandboxed code inside `omarchy-shell`.** Adding warns you before cloning, plugins land disabled so you can review the code before enabling, and updates show a diff of the changes before touching anything. The scoped QML interfaces remove direct authentication-service and generic replacement-bar service lookups, but visual plugins still share and can traverse the ordinary host scene. Only add repos whose code you are willing to run.
-
-Each command is **interactive** when run bare in a terminal (gum pickers,
-confirmation, a diff to review) and fully **non-interactive** when given
-arguments. Pass `--yes` to skip every prompt — this is the path for scripts and
-AI agents:
-
-```bash
-omarchy plugin add https://github.com/acme/omarchy-weather.git --enable --yes
-omarchy plugin update --yes
-```
-
-The installer never runs plugin code, install hooks, or sudo — it only clones
-files, validates the manifest, and toggles enabled state over shell IPC. Since
-an installed plugin is a plain git checkout, anything beyond add/update
-(pinning a ref, switching branches) is ordinary git in the plugin directory.
-
-### Installing by hand
-
-You can still drop a plugin in without git:
-
-1. Put it in `~/.config/omarchy/plugins/<plugin-id>/` with a `manifest.json`
-   plus the QML referenced from its `entryPoints`.
-2. `omarchy-shell shell rescanPlugins`.
-3. `omarchy plugin enable <id>`. Bar widgets start in
-   `barWidget.defaultSection`, or in the center when it is omitted, and can be
-   moved with `omarchy bar move`; a full bar replaces the one in use.
-
-The lower-level IPC equivalents remain available via `omarchy-shell shell rescanPlugins`,
-`omarchy-shell shell enablePlugin <id> '{}'`, and `omarchy-shell shell listPlugins`.
-The `omarchy plugin` commands wrap those calls. `omarchy bar move` and
-`omarchy bar set` edit the persisted widget layout in `shell.json`.
-
-To hack on a built-in plugin safely, clone it into user config instead of
-editing the built-in source. The complete plugin directory is copied, including
-every declared kind and local dependency. A built-in id such as
-`omarchy.clock` becomes `<username>.clock` (e.g. `dhh.clock`), with `My Clock`
-as its display name. The username prefix keeps shared clones from colliding
-with each other or with other plugin authors.
-
-```bash
-omarchy plugin clone omarchy.clock
-```
-
-Cloning switches from the built-in to the new personal plugin, preserving an
-existing bar widget's position and settings. Setup > Plugins > Clone provides
-the interactive picker, then opens the new `<username>.*` directory in `$EDITOR`.
-Existing shortcuts and shell IPC calls made to the built-in id are routed to
-the enabled clone, so cloning does not require changing its callers. Removing
-an active clone switches back to its built-in source.
-Saving a file anywhere under `~/.config/omarchy/plugins/` reloads plugin code
-automatically; `omarchy-shell shell rescanPlugins` remains available to force a reload.
-
-First-party plugins under `shell/plugins/` are discovered the same way and load
-by default. Disabling a non-widget records it in `disabledPlugins[]`; disabling
-a widget removes it from the bar layout while leaving its component available
-to add again. A full bar has no off state and is replaced by enabling another.
-
-## IPC contract
-
-The shell exposes a single `shell` IPC target plus whatever extra targets
-individual plugins register (e.g. the bar's `bar` target for refresh
-hooks, the image picker's `image-selector` target). `omarchy-menu` uses the
-shell target to summon the first-party `omarchy.menu` plugin instead of
-running a separate Quickshell instance.
-
-| Method                                   | Returns | Effect                                                |
-|------------------------------------------|---------|-------------------------------------------------------|
-| `ping`                                   | `ok`    | health check                                          |
-| `summon <id> <payloadJson>`              | `ok` / `unknown` | load + open a panel/overlay plugin           |
-| `hide <id>`                              | —       | close a previously-summoned plugin                    |
-| `toggle <id> <payloadJson>`              | —       | summon if closed, hide if open                        |
-| `call <id> <method> <arg>`               | string  | call a method on an already-loaded plugin             |
-| `rescanPlugins`                          | —       | re-walk plugin dirs and hot-reload plugin code        |
-| `reloadConfig`                           | `ok`    | reload `~/.config/omarchy/shell.json`                 |
-| `setPluginEnabled <id> <enabled>`        | `ok` / `unknown` | flip the persisted enabled bit (see note)    |
-| `listPlugins`                            | JSON    | every discovered plugin, sorted by name               |
-
-Direct invocation:
-
-```
-quickshell ipc -p $OMARCHY_PATH/shell call shell ping
-```
-
-Hyprland autostart launches the shell directly with `quickshell -p
-$OMARCHY_PATH/shell`. Use `omarchy-restart-shell` to stop every running
-instance of that config and launch one fresh shell process.
-
-A convenience wrapper, [`omarchy-shell`](../bin/omarchy-shell), forwards IPC
-calls to the running shell. It does not start the shell.
-
-```
-omarchy-shell shell ping
-omarchy-shell shell toggle omarchy.menu '{"menu":"root"}'
-omarchy-shell shell listPlugins
-omarchy-shell shell rescanPlugins
-```
-
-**Note on `setPluginEnabled`:** the `enabled` argument is a string. Only the
-literal `"true"` enables the plugin; every other value (including `"True"`,
-`"1"`, `"yes"`, or omitted) disables it. This keeps the IPC surface
-type-stable across QML's `string`-only IPC arguments.
-
-## Persisted state
-
-There is one user config file. Everything that distinguishes your
-customization from the shipped defaults lives in it.
-
-| Path                              | Owner          | Purpose                                                |
-|-----------------------------------|----------------|--------------------------------------------------------|
-| `~/.config/omarchy/shell.json`    | the shell      | full layout + per-entry settings + enabled plugin list |
-| `~/.config/omarchy/plugins/<id>/` | user           | drop-in third-party plugin source files                |
-
-The `config/omarchy/shell.json` default config describes the
-fresh-install state. When the user has no `shell.json`, the shell uses
-the defaults verbatim. Once the user customizes anything, `shell.json`
-becomes the authoritative file — we do **not** deep-merge defaults back in.
-
-### shell.json shape
-
-```json
-{
-  "version": 1,
-  "idle": {
-    "screensaver": 150,
-    "lock": 300
-  },
-  "bar": {
-    "id": "omarchy.bar",
-    "position": "top",
-    "transparent": false,
-    "centerAnchor": "omarchy.clock",
-    "layout": {
-      "left":   [ { "id": "omarchy.menu" }, { "id": "omarchy.workspaces" } ],
-      "center": [ { "id": "omarchy.clock", "format": "HH:mm" } ],
-      "right": [
-        { "id": "omarchy.audio" }
-      ]
-    }
-  },
-  "plugins": []
-}
-```
-
-### Storage rules
-
-1. **The active bar option is `bar.id`.** Omit it or set it to `omarchy.bar`
-   to use the built-in bar. Set it to another plugin id whose manifest declares
-   `kind: "bar"` to replace the full bar.
-2. **Every plugin instance is one entry.** Either in `bar.layout.<section>`
-   for bar widgets, or in `plugins[]` for panels, overlays, services,
-   menus, and anything else non-bar.
-3. **Settings are inline on the entry.** No `config:` sub-object, no
-   separate per-plugin settings file, no merge layers. The fields on each
-   entry are the values the plugin sees.
-4. **Built-in widget ids are namespaced.** Use ids such as `omarchy.clock`,
-   `omarchy.audio`, and `omarchy.network`. The migration rewrites older ids
-   like `Clock` and `AudioPanel` forward.
-5. **Third-party enabled ⇔ present.** A third-party plugin is enabled iff
-   its id appears somewhere in shell.json. For full bar options, that means
-   `bar.id`; for bar widgets, plugin enable/disable adds/removes layout entries;
-   other plugin kinds are enabled the same way. First-party non-bar plugins
-   are enabled unless listed in `disabledPlugins[]`.
-6. **Multiple instances** are allowed when a manifest sets
-   `allowMultiple: true`. Each instance is independent — e.g. two clock
-   widgets in different timezones are just two `{"id":"omarchy.clock", "timezone": ...}`
-   entries with their own values.
-7. **Idle timings are top-level.** `idle.screensaver` and `idle.lock`
-   are seconds since user idle began, so the default lock fires at 300s
-   even if the 150s screensaver starts first.
-8. **`version: 1` is required** at the top level. The shell will fall back
-   to defaults rather than load an unknown version.
-
-## Implementation history
-
-Built up in phases on this branch:
-
- Phase 1 — `omarchy-shell phase 1: host the existing bar in a single shell`
- Phase 2 — `omarchy-shell phase 2: plugin registry and bar widget registry`
- Phase 3 — `omarchy-shell phase 3: fold bar-settings into the shell as a panel plugin`
- Phase 4 — `omarchy-shell phase 4: absorb background-switcher as a plugin`
- Phase 5 — `omarchy-shell phase 5: docs, cleanup, and migration crumbs`
- Phase 6 — `omarchy-shell phase 6: reviewer cleanup (path traversal, collision, races)`
- Phase 7 — `omarchy-shell phase 7: replace socket with IpcHandler, rename to image-picker`
- Phase 8a — `omarchy-shell phase 8a: unified shell.json with inline plugin settings`
-
-Shared services and Pipewire/UPower/Hyprland consolidation are explicitly
-out of scope here and deferred to a follow-up after a review pass.
+- [Shell reference](../docs/omarchy-shell.md) — plugin manifests, IPC, configuration, and shared UI contracts.
+- [Plugin user guide](../manual/32-shell-plugins.md) — install, configure, and clone plugins.
+- [First-party plugins](plugins/README.md) — bundled plugin IDs, kinds, and entry points.
+- [Shell development guide](../agents/skills/shell-dev.md) — conventions for changing the desktop.
+- [Theming reference](../docs/theming.md) — theme tokens, templates, and generated configuration.
@@ -1,29 +1,19 @@
 import QtQuick
 import qs.Commons

+// The shell draws stills only. OWE owns video backgrounds on the desktop, and
+// it feeds the lock screen through its own socket.
 Item {
  id: root

  property string path: ""
  property int version: 0
-  property bool playbackEnabled: true
-  property bool audioEnabled: false
-  // Bumped when the file behind an unchanged path may have been replaced.
-  // Images cache-bust through version; a video is rebuilt, since FFmpeg
-  // would read a query as part of the filename.
-  property int reloads: 0
-  property bool reloading: false
-  readonly property var current: video ? videoLoader.item : imageLoader.item
+  readonly property var current: imageLoader.item
  readonly property bool ready: current ? current.ready : false
  readonly property bool video: Util.isVideoPath(path)
-  // Cache-bust images selected in a running lock session. FFmpeg treats the
-  // query as part of a local filename, so videos must keep their plain URL.
-  // Each URL is empty for the other kind, so a switch never hands the still
-  // loader a video, or the player a still, in the moment before it unloads.
-  // Both test the path directly: going through `video` lets a URL evaluate
-  // against the stale flag and leak the wrong file for one pass.
-  readonly property url imageUrl: path && !Util.isVideoPath(path) ? Util.fileUrl(path) + (version ? "?v=" + version : "") : ""
-  readonly property url videoUrl: path && Util.isVideoPath(path) ? Util.fileUrl(path) : ""
+  // Cache-bust images selected in a running lock session, so a theme switch
+  // that replaces the file behind an unchanged path shows the new pixels.
+  readonly property url imageUrl: path && !video ? Util.fileUrl(path) + (version ? "?v=" + version : "") : ""

  Loader {
    id: imageLoader
@@ -32,45 +22,6 @@ Item {
    sourceComponent: imageComponent
  }

-  // Loaded by URL rather than from a Component here, so QtMultimedia and its
-  // audio dependency closure never map into a session that only shows images.
-  Loader {
-    id: videoLoader
-    anchors.fill: parent
-    active: root.path !== "" && root.video && !root.reloading
-    source: "BackgroundVideo.qml"
-  }
-
-  onReloadsChanged: {
-    if (!video) return
-    reloading = true
-    Qt.callLater(function() { root.reloading = false })
-  }
-
-  // A player on its way out keeps its source: pushing an empty one starts a
-  // load of nothing that its destructor then cancels, which FFmpeg logs.
-  Binding {
-    target: videoLoader.item
-    property: "mediaSource"
-    value: root.videoUrl
-    when: videoLoader.item !== null && Util.isVideoPath(root.path)
-    restoreMode: Binding.RestoreNone
-  }
-
-  Binding {
-    target: videoLoader.item
-    property: "playbackEnabled"
-    value: root.playbackEnabled
-    when: videoLoader.item !== null
-  }
-
-  Binding {
-    target: videoLoader.item
-    property: "audioEnabled"
-    value: root.audioEnabled
-    when: videoLoader.item !== null
-  }
-
  Component {
    id: imageComponent

@@ -1,122 +0,0 @@
-import QtQuick
-import QtMultimedia
-
-// Deliberately a bare MediaPlayer and VideoOutput rather than the Video
-// convenience type: Video always builds an AudioOutput, and a muted sink still
-// decodes the audio stream and opens an audio client on every output.
-Item {
-  id: root
-
-  property url mediaSource: ""
-  property bool playbackEnabled: true
-  property bool audioEnabled: false
-  property int mediaGeneration: 0
-  property bool priming: false
-  property int primingGeneration: -1
-  property bool frameReceived: false
-  readonly property bool ready: player.hasVideo
-
-  onMediaSourceChanged: {
-    mediaGeneration += 1
-    priming = false
-    primingGeneration = -1
-    frameReceived = false
-    primePauseTimer.stop()
-    framePauseTimer.stop()
-    output.clearOutput()
-  }
-
-  onPlaybackEnabledChanged: {
-    priming = false
-    frameReceived = false
-    primePauseTimer.stop()
-    framePauseTimer.stop()
-    if (playbackEnabled) player.play()
-    else player.pause()
-  }
-
-  function pauseAfterPrimedFrame() {
-    if (!priming
-        || root.playbackEnabled
-        || primingGeneration !== root.mediaGeneration) return
-
-    priming = false
-    primePauseTimer.stop()
-    framePauseTimer.stop()
-    player.pause()
-  }
-
-  // A paused MediaPlayer can load a source without presenting its first frame.
-  // Prime it until VideoOutput receives a frame, with a timeout so a stalled
-  // decoder cannot keep running indefinitely on battery.
-  Timer {
-    id: primePauseTimer
-    interval: 1000
-    repeat: false
-
-    onTriggered: root.pauseAfterPrimedFrame()
-  }
-
-  // Receiving a frame means the decoder has produced it, but the scene graph
-  // may not have committed it yet. Give VideoOutput a render cycle before
-  // pausing so the first frame is not lost on a source switch.
-  Timer {
-    id: framePauseTimer
-    interval: 50
-    repeat: false
-
-    onTriggered: root.pauseAfterPrimedFrame()
-  }
-
-  VideoOutput {
-    id: output
-    anchors.fill: parent
-    fillMode: VideoOutput.PreserveAspectCrop
-  }
-
-  // Sound is opted into per output: with a player per monitor, every output
-  // playing the track would layer copies of it. The sink is only built once
-  // the media reports a sound track, so a silent file never opens an audio
-  // client or its threads. Priming a paused player must not be heard.
-  Loader {
-    id: audioLoader
-    active: root.audioEnabled && player.hasAudio
-    sourceComponent: AudioOutput {
-      muted: root.priming || !root.playbackEnabled
-    }
-  }
-
-  MediaPlayer {
-    id: player
-    source: root.mediaSource
-    videoOutput: output
-    audioOutput: audioLoader.item
-    loops: MediaPlayer.Infinite
-    autoPlay: root.playbackEnabled
-    onMediaStatusChanged: {
-      if (mediaStatus !== MediaPlayer.LoadedMedia) return
-
-      if (!root.playbackEnabled) {
-        root.priming = true
-        root.primingGeneration = root.mediaGeneration
-        root.frameReceived = false
-        primePauseTimer.restart()
-      }
-      player.play()
-    }
-  }
-
-  Connections {
-    target: output.videoSink
-    function onVideoFrameChanged() {
-      if (player.mediaStatus !== MediaPlayer.BufferedMedia) return
-      if (!root.priming
-          || root.playbackEnabled
-          || root.primingGeneration !== root.mediaGeneration
-          || root.frameReceived) return
-
-      root.frameReceived = true
-      framePauseTimer.restart()
-    }
-  }
-}
@@ -4,7 +4,6 @@ BarIndicator 1.0 BarIndicator.qml
 BarIconButton 1.0 BarIconButton.qml
 BarWidget 1.0 BarWidget.qml
 BackgroundMedia 1.0 BackgroundMedia.qml
-BackgroundVideo 1.0 BackgroundVideo.qml
 BorderOverlay 1.0 BorderOverlay.qml
 BorderSurface 1.0 BorderSurface.qml
 Button 1.0 Button.qml
@@ -1,5 +1,4 @@
 import Quickshell
-import Quickshell.Hyprland
 import Quickshell.Io
 import Quickshell.Wayland
 import QtQuick
@@ -17,7 +16,6 @@ Item {

  property string currentBackground: ""
  property string displayedBackground: ""
-  property int displayedReloads: 0
  property string incomingBackground: ""
  property string oldBackground: ""
  property bool finishingTransition: false
@@ -28,23 +26,6 @@ Item {
  property string pendingShellRaw: ""
  property real revealProgress: 1

-  // Injected by the first-party service loader; used to reach the lock and idle
-  // services so playback can stop whenever nothing can see the wallpaper.
-  property var shell: null
-
-  // Stop a video wallpaper's decoding whenever it is covered. Qt's FFmpeg
-  // engine drives its own clock, so an unseen player keeps decoding until it
-  // is told not to — a locked laptop would otherwise decode until it died.
-  readonly property var lockService: shell && shell.services ? shell.firstPartyServiceFor("omarchy.lock") : null
-  readonly property var idleService: shell && shell.services ? shell.firstPartyServiceFor("omarchy.idle") : null
-  readonly property var batteryService: shell && shell.services ? shell.firstPartyServiceFor("omarchy.battery") : null
-  readonly property bool lockActive: lockService ? lockService.locked : false
-  readonly property bool screensaverActive: idleService ? idleService.screensaverWindowCount > 0 : false
-  readonly property bool powerSaverActive: batteryService ? batteryService.powerSaverOnBattery : false
-  // A lock or a screensaver covers every output, so it is decided once here.
-  // Fullscreen is decided per output below, because it only covers its own.
-  readonly property bool sessionObscured: lockActive || screensaverActive
-
  function isVideo(path) {
    return Util.isVideoPath(path)
  }
@@ -78,9 +59,6 @@ Item {
    if (instant || !displayedBackground || isVideo(path) || isVideo(displayedBackground)) {
      oldBackground = ""
      incomingBackground = ""
-      // A theme switch can replace the file behind an unchanged path, which
-      // an unchanged property would never pick up.
-      if (displayedBackground === finalPath) displayedReloads += 1
      displayedBackground = finalPath
      revealProgress = 1
      return
@@ -225,23 +203,9 @@ Item {
      // Keep render updates enabled. The background layer has been observed to
      // lose its committed buffer while parked with updatesEnabled=false,
      // leaving a black desktop until omarchy-shell is restarted. A still
-      // wallpaper costs nothing to keep enabled, and a video one is throttled
-      // by pausing playback rather than by parking the layer.
+      // wallpaper costs nothing to keep enabled. OWE manages video layers.
      updatesEnabled: true

-      // Pausing every wallpaper for one fullscreen window would freeze the one
-      // still on show next to it, which costs a viewer more than it saves. The
-      // workspace on show here knows whether a fullscreen window covers it,
-      // wherever focus happens to be.
-      readonly property var hyprlandMonitor: Hyprland.monitorFor(modelData)
-      readonly property var visibleWorkspace: hyprlandMonitor ? hyprlandMonitor.activeWorkspace : null
-      readonly property bool fullscreenHere: visibleWorkspace ? visibleWorkspace.hasFullscreen : false
-
-      // A sound track plays from one output only, or every monitor would
-      // layer its own copy of it.
-      readonly property bool firstScreen: Quickshell.screens.length > 0
-        && String(Quickshell.screens[0].name || "") === String(modelData.name || "")
-
      property bool maskReady: false

      function maybeStartReveal() {
@@ -259,13 +223,12 @@ Item {
      WlrLayershell.keyboardFocus: WlrKeyboardFocus.None
      exclusionMode: ExclusionMode.Ignore

+      // OWE owns video backgrounds. This layer draws stills, and stays empty
+      // behind a video so OWE's own layer shows through.
      BackgroundMedia {
        id: base
        anchors.fill: parent
        path: root.displayedBackground
-        reloads: root.displayedReloads
-        playbackEnabled: !root.sessionObscured && !root.powerSaverActive && !panel.fullscreenHere
-        audioEnabled: panel.firstScreen
        onReadyChanged: {
          if (ready && root.finishingTransition) {
            root.incomingBackground = ""
@@ -14,7 +14,7 @@ the shell for its whole session.

 ## Customizing

-The bar config lives under the `bar:` key of [`~/.config/omarchy/shell.json`](../../README.md#shelljson-shape). Out of the box the shell uses [`config/omarchy/shell.json`](../../../config/omarchy/shell.json). Once you customize anything via the bar gestures, `omarchy bar ...`, or by editing shell.json directly, your file is canonical — there is no deep-merge.
+The bar config lives under the `bar:` key of [`~/.config/omarchy/shell.json`](../../../docs/omarchy-shell.md#shelljson). Out of the box the shell uses [`config/omarchy/shell.json`](../../../config/omarchy/shell.json). Once you customize anything via the bar gestures, `omarchy bar ...`, or by editing shell.json directly, your file is canonical — there is no deep-merge.

 The bar is configured directly on the bar itself: drag empty bar space (or click-and-hold) to move the bar to another screen edge, double-left-click empty center-bar space to toggle transparency, and drag widgets to reorder them. The `omarchy bar position`, `omarchy bar transparent`, `omarchy bar move`, and `omarchy bar set` commands do the same from scripts. Enable or disable widgets with `omarchy plugin enable` and `omarchy plugin disable` (widget ids come from `omarchy plugin list`).

@@ -172,9 +172,4 @@ richer popup plugins live in feature directories such as `../panels/audio/`,
 `manifest.json`. Bar layout ids are namespaced, e.g. `omarchy.audio`,
 `omarchy.network`, and `omarchy.clock`.

-Third-party widgets ship as separate plugins under
-`~/.config/omarchy/plugins/<plugin-id>/` with their own `manifest.json`
-declaring `kinds: ["bar-widget"]` and a `barWidget` entry point. See
-[../../README.md](../../README.md) for the manifest schema. Rescan, enable,
-and place third-party plugins with `omarchy-shell shell rescanPlugins`,
-`omarchy plugin enable`, and `omarchy bar move`.
+Third-party widgets ship as separate plugins under `~/.config/omarchy/plugins/<plugin-id>/` with their own `manifest.json` declaring `kinds: ["bar-widget"]` and a `barWidget` entry point. See the [shell reference](../../../docs/omarchy-shell.md#plugin-manifest) for the manifest schema. Rescan, enable, and place third-party plugins with `omarchy-shell shell rescanPlugins`, `omarchy plugin enable`, and `omarchy bar move`.
@@ -0,0 +1,7 @@
+import QtQuick
+import Owe.LockFeed
+
+// Loaded through a Loader from LockView, so a system without the module shows
+// no lock video instead of losing the whole lock screen.
+LockFeed {
+}
@@ -7,6 +7,7 @@ Item {
  id: root

  property string backgroundPath: ""
+  property string videoPosterPath: ""
  property int backgroundVersion: 0
  property bool fingerprintConfigured: false
  property bool authenticatingPassword: false
@@ -43,6 +44,9 @@ Item {
    ? Border.surfaceSpec("lock", "border-error", Color.lock.borderError, root.outlineThickness, "border-alpha")
    : Border.surfaceSpec("lock", "border-active", Color.lock.borderActive, root.outlineThickness, "border-alpha")

+  readonly property bool video: Util.isVideoPath(root.backgroundPath)
+  readonly property bool feedActive: root.video && root.loadBackground && !root.displaysBlank && !root.powerSaverActive
+
  signal submitPassword(string password)
  signal passwordTextEdited(string password)
  signal clearFailureRequested()
@@ -88,16 +92,15 @@ Item {

    BackgroundMedia {
      id: wallpaper
+      objectName: "lockWallpaper"
      anchors.fill: parent
-      path: root.loadBackground ? root.backgroundPath : ""
+      path: root.loadBackground ? (root.video ? root.videoPosterPath : root.backgroundPath) : ""
      version: root.backgroundVersion
-      playbackEnabled: root.loadBackground && !root.displaysBlank && !root.powerSaverActive
    }

    MultiEffect {
      anchors.fill: wallpaper
-      source: wallpaper.video ? null : wallpaper
-      visible: !wallpaper.video
+      source: wallpaper
      autoPaddingEnabled: false
      blurEnabled: root.loadBackground && wallpaper.ready
      blur: 1.0
@@ -106,11 +109,22 @@ Item {
      contrast: -0.08
    }

-    // Qt's video output cannot be sampled by MultiEffect on every renderer.
+    // The cached poster stays behind the feed when policy pauses playback,
+    // the module is unavailable, or a new connection has not received a frame.
+    Loader {
+      id: feedLoader
+      objectName: "lockFeedLoader"
+      anchors.fill: parent
+      active: root.feedActive
+      source: "LockFeedSurface.qml"
+      visible: status === Loader.Ready
+    }
+
+    // The feed item cannot be sampled by MultiEffect on every renderer.
    // Keep video wallpapers visible and darken them slightly for legibility.
    Rectangle {
-      anchors.fill: wallpaper
-      visible: wallpaper.video
+      anchors.fill: feedLoader
+      visible: root.video
      color: "#22000000"
    }

@@ -28,6 +28,7 @@ Item {
  property string failureMessage: ""
  property int failedAttempts: 0
  property string backgroundPath: ""
+  property string videoPosterPath: ""
  property int backgroundVersion: 0
  property string lastEvent: "init"
  property string lastEventAt: ""
@@ -113,6 +114,16 @@ Item {
    if (!readlinkProc.running) readlinkProc.running = true
  }

+  function refreshPoster() {
+    if (!root.videoBackground) {
+      root.videoPosterPath = ""
+      return
+    }
+    if (posterProc.running) return
+    posterProc.sourcePath = root.backgroundPath
+    posterProc.running = true
+  }
+
  function refreshFingerprintStatus() {
    if (!fingerprintCheckProc.running) fingerprintCheckProc.running = true
  }
@@ -307,6 +318,7 @@ Item {
        id: lockView
        anchors.fill: parent
        backgroundPath: root.backgroundPath
+        videoPosterPath: root.videoPosterPath
        backgroundVersion: root.backgroundVersion
        fingerprintConfigured: root.fingerprintConfigured
        authenticatingPassword: root.authenticatingPassword
@@ -339,6 +351,7 @@ Item {
    LockView {
      anchors.fill: parent
      backgroundPath: root.backgroundPath
+      videoPosterPath: root.videoPosterPath
      backgroundVersion: root.backgroundVersion
      fingerprintConfigured: root.fingerprintConfigured
      authenticatingPassword: false
@@ -409,9 +422,25 @@ Item {
      onStreamFinished: {
        var next = String(text || "").trim()
        if (next !== root.backgroundPath) {
+          root.videoPosterPath = ""
          root.backgroundPath = next
          root.backgroundVersion += 1
        }
+        root.refreshPoster()
+      }
+    }
+  }
+
+  Process {
+    id: posterProc
+    property string sourcePath: ""
+    command: ["bash", Quickshell.env("OMARCHY_PATH") + "/shell/plugins/lock/poster.sh", sourcePath]
+    stdout: StdioCollector { id: posterOutput; waitForEnd: true }
+    onExited: function(exitCode) {
+      if (sourcePath !== root.backgroundPath) {
+        root.refreshPoster()
+      } else {
+        root.videoPosterPath = exitCode === 0 ? String(posterOutput.text || "").trim() : ""
      }
    }
  }
@@ -0,0 +1,24 @@
+#!/bin/bash
+
+# One cached frame shared by all lock outputs, including when OWE is paused.
+set -euo pipefail
+
+source_path=$1
+cache_dir="${XDG_CACHE_HOME:-$HOME/.cache}/omarchy/lock-poster"
+signature=$(stat -Lc '%s:%y:%z' "$source_path")
+key=$(printf '%s\n%s' "$source_path" "$signature" | sha256sum | cut -d ' ' -f 1)
+poster="$cache_dir/poster-$key.jpg"
+mkdir -p "$cache_dir"
+exec {lock_fd}>"$cache_dir/.lock"
+flock -w 10 "$lock_fd"
+
+if [[ ! -s $poster ]]; then
+  temporary=$(mktemp "$cache_dir/.poster-XXXXXX.jpg")
+  trap 'rm -f "$temporary"' EXIT
+  timeout -k 1 5 ffmpegthumbnailer -i "$source_path" -o "$temporary" -s 1920 -q 8 {lock_fd}>&-
+  [[ -s $temporary ]]
+  mv -f "$temporary" "$poster"
+  find "$cache_dir" -maxdepth 1 -type f -name 'poster-*.jpg' ! -name "poster-$key.jpg" -delete
+fi
+
+printf '%s\n' "$poster"
@@ -24,6 +24,20 @@ verify_core_packages() {
  pass "all Omarchy core packages are installed (${#missing[@]} missing)"
 }

+verify_kernel_headers() {
+  local kernel=linux-omarchy
+  local release
+  release=$(uname -r)
+  omarchy-pkg-present linux-t2 && kernel=linux-t2
+
+  [[ $(cat "/usr/lib/modules/$release/pkgbase") == "$kernel" ]] ||
+    fail "the installed system boots the supported kernel" "$release is not $kernel"
+  omarchy-pkg-present "$kernel-headers" || fail "kernel headers are installed" "$kernel-headers is missing"
+  [[ $(cat "/usr/lib/modules/$release/build/include/config/kernel.release") == "$release" ]] ||
+    fail "headers match the running kernel" "$release has missing or mismatched headers"
+  pass "the running $kernel kernel has matching headers ($release)"
+}
+
 verify_defaults() {
  [[ $(omarchy-default-browser) == "chromium" ]] || fail "Chromium is the default browser"
  pass "Chromium is the default browser"
@@ -112,7 +126,7 @@ verify_user_setup() {
  pass "Omarchy user state and shell configuration exist"
 }

-for check in verify_core_packages verify_defaults verify_services verify_runtime_tools verify_user_setup; do
+for check in verify_core_packages verify_kernel_headers verify_defaults verify_services verify_runtime_tools verify_user_setup; do
  if ! ("$check"); then
    status=1
  fi
@@ -21,16 +21,31 @@ fi
 # Keep going after a failing file. A test file exits at its first failed
 # assertion, so aborting the run there too would hide every file after it --
 # one packaging failure was masking 114 of 134 files.
+output=$(mktemp)
+trap 'rm -f "$output"' EXIT
 failed=()
+skipped=()
 for test in "${tests[@]}"; do
  printf '==> %s\n' "${test#$ROOT/}"
-  bash "$test" || failed+=("${test#$ROOT/}")
+  bash "$test" | tee "$output" || failed+=("${test#$ROOT/}")
+  if grep -q '^ok - .* # SKIP$' "$output"; then
+    skipped+=("${test#$ROOT/}")
+  fi
 done

+if (( ${#skipped[@]} > 0 )); then
+  printf '\nSkipped checks in %d of %d test files:\n' "${#skipped[@]}" "${#tests[@]}"
+  printf '  %s\n' "${skipped[@]}"
+fi
+
 if (( ${#failed[@]} > 0 )); then
  printf '\n%d of %d test files failed:\n' "${#failed[@]}" "${#tests[@]}" >&2
  printf '  %s\n' "${failed[@]}" >&2
  exit 1
 fi

-printf '\nAll %d test files passed.\n' "${#tests[@]}"
+if (( ${#skipped[@]} == 0 )); then
+  printf '\nAll %d test files passed.\n' "${#tests[@]}"
+else
+  printf '\n%d test files completed without failures; %d had skipped checks.\n' "${#tests[@]}" "${#skipped[@]}"
+fi
@@ -43,7 +43,7 @@ if (( EUID != 0 )); then
 fi

 if (( ! root_runtime_available )); then
-  pass "no unprivileged user namespace; skipping the root lock-helper lookup matrix"
+  skip "no unprivileged user namespace; skipping the root lock-helper lookup matrix"
  exit 0
 fi

@@ -7,7 +7,7 @@ source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
 require_compositor "bar icon geometry test"

 if ! command -v quickshell >/dev/null 2>&1; then
-  pass "quickshell not installed; skipping bar icon geometry test"
+  skip "quickshell not installed; skipping bar icon geometry test"
  exit 0
 fi

@@ -21,7 +21,7 @@ trap cleanup EXIT
 require_compositor "bar widget contract test"

 if ! command -v quickshell >/dev/null 2>&1; then
-  pass "quickshell not installed; skipping bar widget contract test"
+  skip "quickshell not installed; skipping bar widget contract test"
  exit 0
 fi

@@ -14,6 +14,10 @@ pass() {
  printf 'ok - %s\n' "$1"
 }

+skip() {
+  printf 'ok - %s # SKIP\n' "$1"
+}
+
 fail() {
  local description="$1"
  local detail="${2:-}"
@@ -72,7 +76,7 @@ require_compositor() {
    return 0
  fi

-  pass "no Wayland compositor; skipping $description"
+  skip "no Wayland compositor; skipping $description"
  exit 0
 }

@@ -123,7 +123,7 @@ if [[ -n $real_hiddev ]]; then
    fail "wrapper did not trust a valid cached hiddev node: $real_hiddev"
  pass "wrapper trusts a cached hiddev character device without re-detecting"
 else
-  pass "no /dev/hiddev* character device present; skipping the valid-cache case"
+  skip "no /dev/hiddev* character device present; skipping the valid-cache case"
 fi

 # --- With no XDG_RUNTIME_DIR, the predictable /tmp cache is not consulted ------
@@ -148,5 +148,5 @@ if mkfifo "$tmp_cache" 2>/dev/null; then
      "it blocked reading the FIFO decoy at $tmp_cache"
  pass "wrapper ignores the /tmp cache path when XDG_RUNTIME_DIR is unset"
 else
-  pass "$tmp_cache already present or not safely creatable; skipping the /tmp-fallback case"
+  skip "$tmp_cache already present or not safely creatable; skipping the /tmp-fallback case"
 fi
@@ -46,7 +46,7 @@ mode=$(stat -c '%a' "$write_dir/color.json")
 pass "theme colour writes a 0644 color.json"

 if (( EUID == 0 )); then
-  pass "running as root; skipping the mktemp-failure check"
+  skip "running as root; skipping the mktemp-failure check"
 else
  chmod u+w "$write_dir"
  export TMPDIR=$test_tmp/missing-tmp
@@ -82,7 +82,7 @@ SH
 chmod +x "$stub_bin/sudo"

 if ((EUID == 0)); then
-  pass "running as root; skipping the elevation checks, which would rewrite this machine's browser policy"
+  skip "running as root; skipping the elevation checks, which would rewrite this machine's browser policy"
 else
  elevation_for() {
    : >"$test_tmp/elevation"
@@ -20,7 +20,7 @@ JS
 require_compositor "Button hover geometry runtime test"

 if ! command -v quickshell >/dev/null 2>&1; then
-  pass "quickshell not installed; skipping Button hover geometry runtime test"
+  skip "quickshell not installed; skipping Button hover geometry runtime test"
  exit 0
 fi

@@ -0,0 +1,50 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+# Exercise the privileged installer without writing to the host's /usr/share.
+if ! command -v bwrap >/dev/null || ! bwrap --ro-bind / / --unshare-user --uid 0 --gid 0 true 2>/dev/null; then
+  skip "user namespaces unavailable; skipping isolated Claude extension installation"
+  exit 0
+fi
+
+test_tmp=$(mktemp -d)
+trap 'rm -rf "$test_tmp"' EXIT
+mkdir -p "$test_tmp/share" "$test_tmp/bin"
+installer="$ROOT/bin/omarchy-install-chromium-claude"
+extension_id=fcoeoabgfenejglbffodgkkbkcdhcgfn
+sandbox=(bwrap --ro-bind / / --bind "$test_tmp" "$test_tmp" --dev /dev --proc /proc --unshare-user)
+
+"${sandbox[@]}" --uid 0 --gid 0 --bind "$test_tmp/share" /usr/share bash "$installer"
+for browser in chromium google-chrome microsoft-edge; do
+  file="$test_tmp/share/$browser/extensions/$extension_id.json"
+  jq -e '.external_update_url == "https://clients2.google.com/service/update2/crx"' "$file" >/dev/null ||
+    fail "$browser registers the official Claude Web Store extension"
+  [[ $(stat -c '%a' "$file") == "644" ]] || fail "$browser extension registration is readable"
+done
+pass "Claude extension installer registers all supported browser families"
+
+cat >"$test_tmp/bin/pkexec" <<'SH'
+#!/bin/bash
+printf '%s\n' "$@" >"$AUTH_LOG"
+exit 42
+SH
+chmod +x "$test_tmp/bin/pkexec"
+export AUTH_LOG="$test_tmp/auth-log"
+export PATH="$test_tmp/bin:$PATH"
+
+# A read-only /usr/share and a failing auth stub prove that a repeated run
+# neither rewrites the files nor requests authentication.
+"${sandbox[@]}" --uid 1000 --gid 1000 --ro-bind "$test_tmp/share" /usr/share bash "$installer" </dev/null
+[[ ! -e $AUTH_LOG ]] || fail "configured Claude extensions need no authentication"
+pass "configured Claude extensions need neither writes nor authentication"
+
+rm "$test_tmp/share/google-chrome/extensions/$extension_id.json"
+status=0
+"${sandbox[@]}" --uid 1000 --gid 1000 --ro-bind "$test_tmp/share" /usr/share bash "$installer" </dev/null || status=$?
+[[ $status == 42 ]] || fail "Claude extension installer propagates authentication failure"
+[[ $(cat "$AUTH_LOG") == "/usr/bin/omarchy-install-chromium-claude" ]] ||
+  fail "menu installation elevates only the packaged installer"
+pass "missing registration uses pkexec and propagates authentication failure"
@@ -277,12 +277,12 @@ printf '%s\n' "$1" >"$EDITOR_PATH_OUT"
 cat "$1" >"$EDITOR_TEXT_OUT"
 SH

-cat >"$TMPDIR/bin/tensaku-edit" <<'SH'
+cat >"$TMPDIR/bin/omasnap" <<'SH'
 #!/bin/bash
-printf '%s\n' "$*" >"$TENSAKU_OUT"
+printf '%s\n' "$*" >"$OMASNAP_OUT"
 SH

-chmod +x "$TMPDIR/bin/wl-copy" "$TMPDIR/bin/wl-paste" "$TMPDIR/bin/wtype" "$TMPDIR/bin/omarchy-launch-browser" "$TMPDIR/bin/omarchy-launch-editor" "$TMPDIR/bin/tensaku-edit"
+chmod +x "$TMPDIR/bin/wl-copy" "$TMPDIR/bin/wl-paste" "$TMPDIR/bin/wtype" "$TMPDIR/bin/omarchy-launch-browser" "$TMPDIR/bin/omarchy-launch-editor" "$TMPDIR/bin/omasnap"

 capture_output=$(XDG_RUNTIME_DIR="$TMPDIR" XDG_STATE_HOME="$TMPDIR/state" PATH="$TMPDIR/bin:$PATH" "$ROOT/shell/plugins/clipboard/capture.sh")
 [[ $capture_output == '{"type":"text","text":"terminal copy"}' ]] || fail "clipboard capture records normal text events"
@@ -513,8 +513,8 @@ pass "clipboard open helper opens text entries in editor"
 [[ $(<"$TMPDIR/editor-path") == "$TMPDIR"/state/omarchy/clipboard-open/clipboard.*.txt ]] || fail "clipboard open helper writes text entries to a temporary file"
 pass "clipboard open helper writes text entries to a temporary file"

-TENSAKU_OUT="$TMPDIR/tensaku" HOME="$TMPDIR/home" PATH="$TMPDIR/bin:$PATH" \
+OMASNAP_OUT="$TMPDIR/omasnap" HOME="$TMPDIR/home" PATH="$TMPDIR/bin:$PATH" \
  "$ROOT/bin/omarchy-clipboard-open" --history-index 2

-[[ $(<"$TMPDIR/tensaku") == "$TMPDIR/image.png" ]] || fail "clipboard open helper opens image entries in Tensaku"
-pass "clipboard open helper opens image entries in Tensaku"
+[[ $(<"$TMPDIR/omasnap") == "$TMPDIR/image.png" ]] || fail "clipboard open helper opens image entries in Omasnap"
+pass "clipboard open helper opens image entries in Omasnap"
@@ -62,7 +62,7 @@ run_guard() {
  ' bash "$SHELL_TEST_DIR" 2>&1 || printf 'guard exited %s\n' "$?"
 }

-skipped="ok - no Wayland compositor; skipping sample runtime test"
+skipped="ok - no Wayland compositor; skipping sample runtime test # SKIP"

 output=$(run_guard -u WAYLAND_DISPLAY XDG_RUNTIME_DIR="$runtime_dir")
 [[ $output == "$skipped" ]] || fail "guard skips without a display" "$output"
@@ -76,7 +76,7 @@ pass "guard skips when the socket is unreachable"

 # Everything below needs a socket to stand in for a live or abandoned compositor.
 if (( ! socket_bound )); then
-  pass "cannot bind a Unix socket here; skipping the cases that need one"
+  skip "cannot bind a Unix socket here; skipping the cases that need one"
  exit 0
 fi

@@ -33,6 +33,15 @@ jq -e '
 ' "$ROOT/config/omarchy/shell.json" >/dev/null
 pass "default center anchor exists in center layout"

+jq -e '
+  def ids: map(.id // .);
+  (.bar.layout.center | ids) as $ids |
+  ($ids | index("omacom.elsewhen")) as $elsewhen |
+  ($ids | index("omarchy.clock")) as $clock |
+  $elsewhen != null and $clock == $elsewhen + 1
+' "$ROOT/config/omarchy/shell.json" >/dev/null
+pass "default center layout puts elsewhen immediately before the clock"
+
 jq -e '
  any(.bar.layout.center[]; (.id // .) == "omarchy.clock" and (.formatAlt // "") == "d MMMM \u0027W\u0027ww yyyy")
 ' "$ROOT/config/omarchy/shell.json" >/dev/null
@@ -1,238 +0,0 @@
-#!/bin/bash
-
-set -euo pipefail
-
-source "$(dirname "${BASH_SOURCE[0]}")/base-test.sh"
-
-require_command jq
-require_command python3
-
-migration="$ROOT/migrations/1786643346.sh"
-test_dir=$(mktemp -d)
-trap 'rm -rf "$test_dir"' EXIT
-
-home="$test_dir/home"
-profile_root="$home/.config/chromium"
-preferences="$profile_root/Default/Preferences"
-mkdir -p "$(dirname "$preferences")"
-
-# Any id Chromium once derived from the extension's keyless load path; the
-# repair keys off the registered command name, not the id.
-ghost_id="ikkebdkaanlebnifjnbeiaklodhbjcci"
-pinned_id="bgpiichlckmfanooecilcjemknkcpngb"
-
-write_stale_preferences() {
-  jq -n --arg ghost "$ghost_id" --arg pinned "$pinned_id" '{extensions: {commands: {"linux:Alt+Shift+L": {command_name: "copy-url", extension: $ghost, global: false}}, settings: {($ghost): {commands: {"copy-url": {suggested_key: "Alt+Shift+L", was_assigned: true}}}, ($pinned): {commands: {"copy-url": {suggested_key: "Alt+Shift+L"}}}}}}' >"$preferences"
-}
-
-stub_bin="$test_dir/bin"
-mkdir -p "$stub_bin"
-
-cat >"$stub_bin/python3" <<'STUB'
-#!/bin/bash
-exit 127
-STUB
-chmod +x "$stub_bin/python3"
-
-# Test stubs must delegate to the system interpreter, not a user shim that can
-# route python3 back through the stubs and recurse.
-REAL_PYTHON=$(PATH="$stub_bin:$PATH" command -p -v python3)
-[[ $REAL_PYTHON != "$stub_bin/python3" ]] || fail "real Python resolution bypasses user shims"
-export REAL_PYTHON
-rm -f "$stub_bin/python3"
-
-run_migration() {
-  HOME="$home" PATH="$stub_bin:$PATH" bash -euo pipefail "$migration" >/dev/null 2>&1
-}
-
-# A running Chromium-family browser marks its profile root with a SingletonLock
-# symlink to <hostname>-<pid>, a target that never exists on disk. That lock —
-# not the mere presence of a browser process — is what the migration waits on.
-open_browser() {
-  mkdir -p "$profile_root"
-  ln -sfn "test-host-1234" "$profile_root/SingletonLock"
-}
-close_browser() {
-  rm -f "$profile_root/SingletonLock"
-}
-
-# The affected profile being open prompts for the windows to be closed;
-# declining (or having no terminal to ask in) defers the repair so a
-# rewrite-on-exit cannot revert it.
-printf '#!/bin/bash\nexit 1\n' >"$stub_bin/gum"
-chmod +x "$stub_bin/gum"
-write_stale_preferences
-open_browser
-
-before_hash=$(sha256sum "$preferences" | cut -d' ' -f1)
-
-run_migration && fail "migration defers while the affected profile is open"
-[[ $(sha256sum "$preferences" | cut -d' ' -f1) == "$before_hash" ]] ||
-  fail "migration leaves preferences alone while the affected profile is open"
-pass "migration defers the repair while the affected profile is open"
-
-# gum paints its prompt on stderr, so that stream has to stay attached:
-# suppressing it leaves gum reading keys behind an unpainted screen, which
-# reads as a hung update.
-cat >"$stub_bin/gum" <<'STUB'
-#!/bin/bash
-echo "gum-prompt-painted" >&2
-exit 1
-STUB
-prompt_stderr="$test_dir/prompt-stderr"
-HOME="$home" PATH="$stub_bin:$PATH" bash -euo pipefail "$migration" >/dev/null 2>"$prompt_stderr" &&
-  fail "migration defers when the browser prompt is declined"
-grep -q "gum-prompt-painted" "$prompt_stderr" || fail "migration keeps the browser prompt visible"
-pass "migration keeps the browser prompt visible"
-
-# A browser holding a different profile root cannot revert this repair, so it
-# must not hold the update: the repair goes through without ever reaching the
-# prompt, which the still-declining gum stub would otherwise fail.
-close_browser
-mkdir -p "$home/.config/google-chrome"
-ln -sfn "test-host-1234" "$home/.config/google-chrome/SingletonLock"
-write_stale_preferences
-run_migration || fail "migration repairs while a different profile root is open"
-jq -e --arg pinned "$pinned_id" '.extensions.commands["linux:Alt+Shift+L"].extension == $pinned' "$preferences" >/dev/null ||
-  fail "migration repairs the shortcut while a different profile root is open"
-pass "migration ignores a browser on a different profile root"
-rm -f "$home/.config/google-chrome/SingletonLock" "$preferences.omarchy-copy-url-repair.bak"
-
-# Closing the affected profile and confirming the prompt lets the repair
-# proceed.
-write_stale_preferences
-open_browser
-cat >"$stub_bin/gum" <<'STUB'
-#!/bin/bash
-"$CLOSE_BROWSER"
-touch "${GUM_CALLED:?}"
-exit 0
-STUB
-cat >"$stub_bin/close-browser" <<'STUB'
-#!/bin/bash
-rm -f "$HOME/.config/chromium/SingletonLock"
-STUB
-chmod +x "$stub_bin/gum" "$stub_bin/close-browser"
-GUM_CALLED="$test_dir/gum-called" CLOSE_BROWSER="$stub_bin/close-browser" \
-  HOME="$home" PATH="$stub_bin:$PATH" bash -euo pipefail "$migration" >/dev/null 2>&1 ||
-  fail "migration proceeds once the profile is closed and the prompt confirmed"
-[[ -e $test_dir/gum-called ]] || fail "migration asks before repairing under a running browser"
-jq -e --arg pinned "$pinned_id" '.extensions.commands["linux:Alt+Shift+L"].extension == $pinned' "$preferences" >/dev/null ||
-  fail "migration repairs after the browser prompt is confirmed"
-pass "migration asks to close the browser and repairs on confirmation"
-rm -f "$preferences.omarchy-copy-url-repair.bak"
-
-# With the affected profile closed the ghost registration moves to the pinned id.
-printf '#!/bin/bash\nexit 1\n' >"$stub_bin/gum"
-close_browser
-write_stale_preferences
-run_migration || fail "migration repairs the shortcut when no browser is running"
-
-jq -e --arg ghost "$ghost_id" --arg pinned "$pinned_id" '
-  .extensions.commands["linux:Alt+Shift+L"].extension == $pinned and
-  (.extensions.settings | has($ghost) | not) and
-  .extensions.settings[$pinned].commands["copy-url"].was_assigned == true
-' "$preferences" >/dev/null || fail "migration rebinds the Copy URL shortcut to the pinned extension id"
-[[ -f $preferences.omarchy-copy-url-repair.bak ]] ||
-  fail "migration backs up preferences before the repair"
-pass "migration rebinds the Copy URL shortcut to the pinned extension id"
-
-# A repaired profile has no ghost registration left, so nothing is pending —
-# even while that same profile is open.
-rm "$preferences.omarchy-copy-url-repair.bak"
-repaired_hash=$(sha256sum "$preferences" | cut -d' ' -f1)
-open_browser
-run_migration || fail "migration reruns cleanly after the repair"
-[[ $(sha256sum "$preferences" | cut -d' ' -f1) == "$repaired_hash" && ! -e $preferences.omarchy-copy-url-repair.bak ]] ||
-  fail "migration is idempotent after the repair"
-pass "migration is idempotent after the repair"
-close_browser
-
-# A remapped shortcut keeps the user's chosen key while moving to the pinned id.
-jq -n --arg ghost "$ghost_id" '{extensions: {commands: {"linux:Ctrl+Alt+P": {command_name: "copy-url", extension: $ghost, global: false}}, settings: {}}}' >"$preferences"
-run_migration || fail "migration repairs remapped shortcuts"
-jq -e --arg pinned "$pinned_id" '.extensions.commands["linux:Ctrl+Alt+P"].extension == $pinned' "$preferences" >/dev/null ||
-  fail "migration keeps the remapped key while rebinding to the pinned id"
-pass "migration keeps remapped shortcut keys"
-
-# When the pinned extension already holds a copy-url binding (the user fixed
-# it by hand), the ghost is dropped rather than doubled into a second binding.
-jq -n --arg ghost "$ghost_id" --arg pinned "$pinned_id" '{extensions: {commands: {"linux:Ctrl+Alt+P": {command_name: "copy-url", extension: $pinned, global: false}, "linux:Alt+Shift+L": {command_name: "copy-url", extension: $ghost, global: false}}, settings: {}}}' >"$preferences"
-run_migration || fail "migration cleans ghosts alongside a manual repair"
-jq -e --arg pinned "$pinned_id" '
-  (.extensions.commands | has("linux:Alt+Shift+L") | not) and
-  .extensions.commands["linux:Ctrl+Alt+P"].extension == $pinned
-' "$preferences" >/dev/null || fail "migration drops the ghost instead of double-binding the pinned extension"
-pass "migration never double-binds the pinned extension"
-
-# A browser starting mid-repair may write stale Preferences back on exit, so
-# the migration must stay pending for a later browser-free run to verify. A
-# stub hands the repair call through and opens the profile right after it.
-write_stale_preferences
-close_browser
-rm -f "$preferences.omarchy-copy-url-repair.bak"
-cat >"$stub_bin/python3" <<'STUB'
-#!/bin/bash
-# Called as `python3 -c <script> <preferences> <pinned_id> <check|repair>`, and
-# the check calls report a surviving ghost through their exit status.
-"${REAL_PYTHON}" "$@"
-status=$?
-[[ ${5:-} == "repair" ]] && ln -sfn "test-host-1234" "$HOME/.config/chromium/SingletonLock"
-exit $status
-STUB
-chmod +x "$stub_bin/python3"
-if HOME="$home" PATH="$stub_bin:$PATH" bash -euo pipefail "$migration" >/dev/null 2>&1; then
-  fail "migration stays pending when a browser starts mid-repair"
-fi
-jq -e --arg pinned "$pinned_id" '.extensions.commands["linux:Alt+Shift+L"].extension == $pinned' "$preferences" >/dev/null ||
-  fail "migration still repairs preferences before deferring on a late browser"
-pass "migration stays pending when a browser starts mid-repair"
-rm -f "$stub_bin/python3" "$preferences.omarchy-copy-url-repair.bak"
-close_browser
-
-# A browser that started and exited mid-repair restores stale Preferences
-# before the final profile check; the post-repair file verification catches it.
-write_stale_preferences
-cp "$preferences" "$test_dir/stale-preferences"
-cat >"$stub_bin/python3" <<'STUB'
-#!/bin/bash
-"${REAL_PYTHON}" "$@"
-status=$?
-[[ ${5:-} == "repair" ]] && cp "${STALE_PREFERENCES:?}" "${REPAIRED_PREFERENCES:?}"
-exit $status
-STUB
-chmod +x "$stub_bin/python3"
-if HOME="$home" PATH="$stub_bin:$PATH" STALE_PREFERENCES="$test_dir/stale-preferences" \
-  REPAIRED_PREFERENCES="$preferences" bash -euo pipefail "$migration" >/dev/null 2>&1; then
-  fail "migration stays pending when a briefly-lived browser undoes the repair"
-fi
-pass "migration stays pending when a briefly-lived browser undoes the repair"
-rm -f "$stub_bin/python3"
-close_browser
-write_stale_preferences
-run_migration || fail "migration recovers after a reverted repair"
-rm -f "$preferences.omarchy-copy-url-repair.bak"
-
-# A repair attempted while the affected profile was open leaves its backup
-# behind. A rerun that sees a clean disk while that profile still runs must
-# stay pending — the browser can restore the ghost on exit — and only a
-# browser-free rerun verifies the repair and completes.
-write_stale_preferences
-run_migration || fail "repair run before the verification scenario"
-[[ -f $preferences.omarchy-copy-url-repair.bak ]] || fail "verification scenario has a repair backup"
-open_browser
-run_migration && fail "migration must not complete an unverified repair while a browser runs"
-pass "migration keeps an unverified repair pending while a browser runs"
-close_browser
-run_migration || fail "migration completes once the repair is verified with browsers closed"
-pass "migration verifies an attempted repair on a browser-free rerun"
-rm -f "$preferences.omarchy-copy-url-repair.bak"
-
-# An installed third-party extension with a command that happens to be named
-# copy-url keeps its own registration.
-jq -n '{extensions: {commands: {"linux:Alt+Shift+L": {command_name: "copy-url", extension: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", global: false}}, settings: {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa: {path: "/home/user/.config/some-extension", commands: {}}}}}' >"$preferences"
-untouched_hash=$(sha256sum "$preferences" | cut -d' ' -f1)
-run_migration || fail "migration leaves installed third-party extensions alone"
-[[ $(sha256sum "$preferences" | cut -d' ' -f1) == "$untouched_hash" ]] ||
-  fail "migration does not steal a third-party copy-url command registration"
-pass "migration leaves installed third-party extensions alone"
@@ -22,6 +22,15 @@ menu_log="$test_tmp/menu"
 muse_login_log="$test_tmp/muse-login"
 mkdir -p "$mock_bin" "$test_home"

+cat >"$mock_bin/omarchy-install-chromium-claude" <<'SH'
+#!/bin/bash
+echo claude-extension >>"$OMARCHY_TEST_STUB_LOG"
+if [[ ${OMARCHY_TEST_EXTENSION_FAIL:-false} == "true" ]]; then
+  echo "Extension installation failed" >&2
+  exit 1
+fi
+SH
+
 cat >"$mock_bin/omarchy-notification-send" <<'SH'
 #!/bin/bash
 printf '%s\0' "$@" >>"$OMARCHY_TEST_NOTIFICATION_HISTORY"
@@ -406,9 +415,16 @@ declare -A expected_packages=(
 for selection in "${!expected_agents[@]}"; do
  expected=${expected_agents[$selection]}
  : >"$agent_open_log"
+  : >"$stub_log"
  OMARCHY_TEST_AGENT_INSTALLED=true omarchy-default-agent "$selection"
  [[ $(omarchy-default-agent) == $expected ]] || fail "default agent canonicalizes $selection"

+  if [[ $expected == "claude" ]]; then
+    grep -qx claude-extension "$stub_log" || fail "Claude selection installs the browser extension"
+  else
+    [[ ! -s $stub_log ]] || fail "other agents do not install the Claude extension"
+  fi
+
  mapfile -d '' -t mise_args <"$mise_log"
  [[ ${mise_args[0]} == "use" && ${mise_args[1]} == "-g" ]] ||
    fail "default agent installs $selection globally through mise"
@@ -426,6 +442,14 @@ pass "default agent selects and opens every supported provider and alias"
  fail "default agent stores its selection in Omarchy user config"
 pass "default agent stores its selection in Omarchy user config"

+OMARCHY_TEST_AGENT_INSTALLED=true omarchy-default-agent pi
+: >"$agent_open_log"
+OMARCHY_TEST_AGENT_INSTALLED=true OMARCHY_TEST_EXTENSION_FAIL=true omarchy-default-agent claude >"$test_tmp/extension-failure" 2>&1
+[[ $(omarchy-default-agent) == "claude" ]] || fail "extension installation failure still selects Claude"
+mapfile -d '' -t agent_open_args <"$agent_open_log"
+[[ ${agent_open_args[*]} == "omarchy-agent" ]] || fail "extension installation failure still launches Claude"
+[[ ! -s $test_tmp/extension-failure ]] || fail "extension installation failure is silent"
+pass "extension installation failure silently continues selecting and launching Claude"
 OMARCHY_TEST_AGENT_INSTALLED=true omarchy-default-agent pi
 : >"$notification_history"
 : >"$agent_open_log"
@@ -81,13 +81,13 @@ SH
  rm -rf "$poison_dir"
  pass "root omarchy-dns resolves system helpers from a trusted PATH, not the invocation PATH"
 else
-  pass "no unprivileged user namespace; skipping the root trusted-PATH probe"
+  skip "no unprivileged user namespace; skipping the root trusted-PATH probe"
 fi

 # require_root returns immediately for root, so the stubs below would not stand
 # between the script and the host's real NetworkManager and resolved config.
 if (( EUID == 0 )); then
-  pass "running as root; skipping the elevation checks, which would rewrite this machine's DNS"
+  skip "running as root; skipping the elevation checks, which would rewrite this machine's DNS"
  exit 0
 fi

@@ -0,0 +1,89 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+require_command jq
+
+test_dir=$(mktemp -d)
+trap 'rm -rf "$test_dir"' EXIT
+mkdir -p "$test_dir/bin" "$test_dir/home"
+export CALL_LOG="$test_dir/calls"
+
+cat >"$test_dir/bin/omarchy-pkg-add" <<'SH'
+#!/bin/bash
+printf 'package %s\n' "$*" >>"$CALL_LOG"
+exit "${PACKAGE_STATUS:-0}"
+SH
+cat >"$test_dir/bin/omarchy-shell" <<'SH'
+#!/bin/bash
+printf '%s\n' "$*" >>"$CALL_LOG"
+[[ $2 != "rescanPlugins" ]] || exit "${SCAN_STATUS:-0}"
+printf '%s\n' "${TEST_PUT_RESULT:-ok}"
+SH
+cat >"$test_dir/bin/omarchy-restart-shell" <<'SH'
+#!/bin/bash
+echo 'migration must leave the restart to omarchy update' >&2
+exit 1
+SH
+chmod +x "$test_dir/bin/"*
+
+mkdir -p "$test_dir/packaged/shell/plugins/omacom.elsewhen"
+sed "s|/usr/share/omarchy|$test_dir/packaged|g" "$ROOT/migrations/1789581661.sh" >"$test_dir/migration.sh"
+
+plugin="$test_dir/home/.config/omarchy/plugins/omacom.elsewhen"
+run_migration() {
+  : >"$CALL_LOG"
+  HOME="$test_dir/home" OMARCHY_PATH="${1:-$test_dir/packaged}" PATH="$test_dir/bin:$ROOT/bin:$PATH" \
+    bash -euo pipefail "$test_dir/migration.sh" >"$test_dir/output" 2>&1
+}
+
+if PACKAGE_STATUS=1 run_migration; then
+  fail "package failure stops the migration"
+fi
+[[ ! -e $plugin && ! -L $plugin && $(cat "$CALL_LOG") == "package elsewhen" ]] ||
+  fail "package failure leaves the plugin and shell untouched"
+pass "package failure stops before changing the shell"
+
+run_migration
+[[ ! -e $plugin && ! -L $plugin ]] || fail "migration does not create a user plugin link"
+[[ ! -e $ROOT/config/omarchy/plugins/omacom.elsewhen && ! -L $ROOT/config/omarchy/plugins/omacom.elsewhen ]] || fail "fresh installs do not ship a user plugin link"
+pass "migration and fresh installs rely on the packaged plugin directory"
+
+expected=$'package elsewhen\nshell rescanPlugins\nshell putBarWidget omacom.elsewhen {"before":"omarchy.clock"}'
+[[ $(cat "$CALL_LOG") == "$expected" ]] || fail "install, scan and placement run in order" "$(cat "$CALL_LOG")"
+pass "real bar helper enables and places before the clock without restarting during reload"
+
+run_migration
+[[ $(cat "$CALL_LOG") == "$expected" ]] || fail "migration can be rerun"
+[[ ! -e $plugin && ! -L $plugin ]] || fail "rerunning the migration does not create a user plugin link"
+pass "migration can be rerun without a user plugin link"
+
+run_migration "$ROOT"
+[[ $(readlink "$plugin") == "$test_dir/packaged/shell/plugins/omacom.elsewhen" ]] || fail "dev checkout links the packaged plugin"
+pass "dev checkout discovers Elsewhen through a user plugin link"
+run_migration "$ROOT"
+[[ $(readlink "$plugin") == "$test_dir/packaged/shell/plugins/omacom.elsewhen" ]] || fail "dev link survives a rerun"
+pass "dev link is idempotent"
+rm "$plugin"
+
+mkdir -p "$plugin"
+printf 'local work\n' >"$plugin/notes"
+run_migration "$ROOT"
+[[ ! -L $plugin && $(cat "$plugin/notes") == "local work" ]] || fail "existing checkout is preserved"
+pass "existing checkout and local files are preserved"
+
+rm "$plugin/notes"
+rmdir "$plugin"
+ln -s "$test_dir/custom-plugin" "$plugin"
+run_migration "$ROOT"
+[[ $(readlink "$plugin") == "$test_dir/custom-plugin" ]] || fail "existing symlink is preserved"
+pass "existing symlink is preserved, including a missing target"
+
+for failure in 'SCAN_STATUS=1' 'TEST_PUT_RESULT=unknown'; do
+  if env "$failure" HOME="$test_dir/home" OMARCHY_PATH="$ROOT" PATH="$test_dir/bin:$ROOT/bin:$PATH" \
+    bash -euo pipefail "$test_dir/migration.sh" >"$test_dir/output" 2>&1; then
+    fail "$failure must leave the migration pending"
+  fi
+  pass "$failure leaves the migration pending"
+done
@@ -0,0 +1,148 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+if (( EUID != 0 )); then
+  if unshare --user --map-root-user true 2>/dev/null; then
+    exec unshare --user --map-root-user bash "$0"
+  fi
+  skip "no unprivileged user namespace; skipping factory account cleanup"
+  exit 0
+fi
+
+test_tmp=$(mktemp -d)
+trap 'rm -rf "$test_tmp"' EXIT
+
+# Load the production functions without self-elevation or the reset entrypoint.
+awk '
+  /^[a-z_]+\(\) \{/ { copying = 1 }
+  copying { print }
+  /^}/ { copying = 0 }
+' "$ROOT/bin/omarchy-system-factory-reset" >"$test_tmp/functions"
+
+cat >"$test_tmp/reset" <<'SH'
+#!/bin/bash
+set -euo pipefail
+source "$1/functions"
+TOP_MNT="$2"
+NEXT_NAME=@omarchy-reset-next
+PROVISIONING_DIR=/var/lib/omarchy/provisioning
+LOG_FILE="$TOP_MNT/reset.log"
+
+log() { printf '%s\n' "$1" >>"$LOG_FILE"; }
+fail() { log "$1"; exit 1; }
+
+# Account tools are real. Only snapshots, boot rebuilding, and system services
+# are replaced: all writes stay inside this test's disposable directory.
+btrfs() {
+  if [[ $1 == "subvolume" && $2 == "snapshot" ]]; then
+    mkdir -p "$4"
+    cp -a "$3/." "$4/"
+  elif [[ $1 == "property" ]]; then
+    printf '%s\n' "$6" >"$4/read-only"
+  else
+    return 1
+  fi
+}
+systemd-id128() { printf '%032d\n' 1; }
+install_provisioning_units() { :; }
+encrypted_install() { return 1; }
+rebuild_next_boot() { touch "$TOP_MNT/rebuilt"; }
+sync() { :; }
+
+userdel() {
+  [[ ${FAIL_COMMAND:-} == "userdel" && $2 == "$FAIL_ROOT" ]] && return 42
+  command userdel "$@"
+}
+usermod() {
+  [[ ${FAIL_COMMAND:-} == "usermod" && $2 == "$FAIL_ROOT" ]] && return 42
+  command usermod "$@"
+}
+rm() {
+  [[ ${FAIL_COMMAND:-} == "rm" && $* == *"$FAIL_ROOT/etc/shadow-"* ]] && return 42
+  command rm "$@"
+}
+
+stage_full_reset
+SH
+
+make_fixture() {
+  local top="$1" root_hash="${2:-original-root-hash}"
+  local factory="$top/@factory"
+  mkdir -p "$top/@" "$factory/etc" "$factory/home/seller" \
+    "$factory/usr/bin" "$factory/usr/share/omarchy/install/provisioning" \
+    "$factory/var/lib/omarchy/provisioning/packages"
+  touch "$top/@/old-system" "$factory/home/seller/private-file" \
+    "$factory/usr/share/omarchy/install/provisioning/omarchy-provision-owner.service" \
+    "$factory/var/lib/omarchy/provisioning/packages/node-v0.tar.gz"
+  printf '#!/bin/bash\n' >"$factory/usr/bin/omarchy-provision-owner"
+  chmod +x "$factory/usr/bin/omarchy-provision-owner"
+  printf 'true\n' >"$factory/read-only"
+  cat >"$factory/etc/passwd" <<'EOF'
+root:x:0:0:root:/root:/bin/bash
+daemon:x:1:1:daemon:/:/usr/bin/nologin
+seller:x:1000:1000:Seller:/home/seller:/bin/bash
+EOF
+  printf 'root:%s:20000:0:99999:7:::\ndaemon:*:20000:0:99999:7:::\nseller:original-user-hash:20000:0:99999:7:::\n' \
+    "$root_hash" >"$factory/etc/shadow"
+  printf 'root:x:0:\ndaemon:x:1:\nseller:x:1000:\nwheel:x:998:seller\n' >"$factory/etc/group"
+  printf 'root:!::\ndaemon:!::\nseller:!::\nwheel:!::seller\n' >"$factory/etc/gshadow"
+  printf 'USERGROUPS_ENAB yes\n' >"$factory/etc/login.defs"
+  printf 'seller:100000:65536\n' >"$factory/etc/subuid"
+  printf 'seller:100000:65536\n' >"$factory/etc/subgid"
+  chmod 600 "$factory/etc/"{shadow,gshadow}
+  for file in passwd shadow group gshadow subuid subgid; do
+    cp "$factory/etc/$file" "$factory/etc/$file-"
+  done
+}
+
+assert_scrubbed() {
+  local root="$1" file
+  [[ $(awk -F: '$1 == "root" { print $2 }' "$root/etc/shadow") == "!" ]] ||
+    fail "reset erases the root hash while keeping the account locked"
+  ! grep -q 'original-.*-hash\|seller' "$root/etc/"{passwd,shadow,group,gshadow} ||
+    fail "reset removes seller account credentials and group membership"
+  [[ ! -e $root/home/seller ]] || fail "reset removes the seller's baseline home"
+  grep -q '^daemon:\*:' "$root/etc/shadow" || fail "reset preserves service accounts"
+  [[ $(stat -c '%a' "$root/etc/shadow") == "600" ]] || fail "shadow stays private"
+  for file in passwd shadow group gshadow subuid subgid; do
+    [[ ! -e $root/etc/$file- ]] || fail "reset removes the $file backup"
+  done
+}
+
+for scenario in normal locked; do
+  top="$test_tmp/$scenario"
+  if [[ $scenario == "locked" ]]; then
+    make_fixture "$top" '!'
+  else
+    make_fixture "$top"
+  fi
+  bash "$test_tmp/reset" "$test_tmp" "$top" || fail "$scenario reset stages successfully"
+  assert_scrubbed "$top/@factory"
+  assert_scrubbed "$top/@"
+  [[ $(cat "$top/@factory/read-only") == "true" ]] || fail "baseline returns to read-only"
+  [[ -f $top/@/var/lib/omarchy/provisioning/pending && -f $top/rebuilt ]] ||
+    fail "reset reaches provisioning after cleanup"
+
+  bash "$test_tmp/reset" "$test_tmp" "$top" || fail "$scenario reset can be repeated"
+  assert_scrubbed "$top/@factory"
+  assert_scrubbed "$top/@"
+  pass "$scenario reset scrubs both roots, preserves service accounts, and can be repeated"
+done
+
+for target in @omarchy-reset-next @factory; do
+  for command in userdel usermod rm; do
+    top="$test_tmp/fail-$target-$command"
+    make_fixture "$top"
+    if FAIL_COMMAND="$command" FAIL_ROOT="$top/$target" bash "$test_tmp/reset" "$test_tmp" "$top"; then
+      fail "reset accepted failed $command in $target"
+    fi
+    [[ -f $top/@/old-system && ! -e $top/rebuilt ]] ||
+      fail "failed cleanup must not activate or rebuild the reset system"
+    [[ $(cat "$top/@factory/read-only") == "true" ]] ||
+      fail "failed cleanup must leave the baseline read-only"
+    pass "failed $command in $target aborts reset before activation"
+  done
+done
@@ -4,7 +4,7 @@ source "$(dirname "$0")/base-test.sh"

 # The hook guards on the real /etc/pam.d path, which can't be mocked via PATH.
 if [[ -f /etc/pam.d/omarchy-lock-fingerprint ]]; then
-  pass "fingerprint invitation test skipped: host already has fingerprint auth configured"
+  skip "fingerprint invitation test skipped: host already has fingerprint auth configured"
  exit 0
 fi

@@ -0,0 +1,69 @@
+import QtQuick
+import Quickshell
+
+ShellRoot {
+  id: root
+  property var view
+  property var wallpaper
+  property var feed
+  property int step: 0
+
+  Item { id: host; width: 1000; height: 700 }
+
+  function findItem(item, name) {
+    if (item.objectName === name) return item
+    for (var i = 0; i < item.children.length; i++) {
+      var found = findItem(item.children[i], name)
+      if (found) return found
+    }
+    return null
+  }
+
+  function check(condition, message) {
+    if (!condition) throw new Error(message)
+  }
+
+  Timer {
+    interval: 150
+    repeat: true
+    running: true
+    onTriggered: {
+      try {
+        if (root.step === 0) {
+          var component = Qt.createComponent("file://" + Quickshell.env("OMARCHY_PATH") + "/shell/plugins/lock/LockView.qml")
+          check(component.status === Component.Ready, component.errorString())
+          root.view = component.createObject(host, {width: 1000, height: 700, backgroundPath: "/still.png", loadBackground: false})
+          check(root.view !== null, component.errorString())
+          root.wallpaper = findItem(root.view, "lockWallpaper")
+          root.feed = findItem(root.view, "lockFeedLoader")
+          check(root.wallpaper.path === "", "hidden still must not decode")
+          root.view.backgroundPath = "/video.mp4"
+          root.view.videoPosterPath = "/poster.jpg"
+        } else if (root.step === 1) {
+          check(!root.feed.active && root.feed.item === null, "hidden video must not load a feed client")
+          root.view.loadBackground = true
+          root.view.powerSaverActive = true
+        } else if (root.step === 2) {
+          check(root.wallpaper.path === "/poster.jpg", "power saver keeps the video poster")
+          check(!root.feed.active, "power saver must not connect to the feed")
+          root.view.powerSaverActive = false
+        } else if (root.step === 3) {
+          check(root.feed.active, "visible video enables the isolated feed loader")
+          check(root.wallpaper.path === "/poster.jpg", "poster stays beneath the feed before its first frame")
+          root.view.displaysBlank = true
+        } else if (root.step === 4) {
+          check(!root.feed.active && root.feed.item === null, "blanking releases the feed client")
+          root.view.loadBackground = false
+        } else {
+          check(root.wallpaper.path === "", "unlock releases the poster image")
+          console.log("OWE_LOCK_TEST_PASS")
+          Qt.quit()
+        }
+        root.step++
+      } catch (error) {
+        console.error("OWE_LOCK_TEST_FAIL: " + error)
+        Qt.quit()
+      }
+    }
+  }
+}
@@ -0,0 +1,158 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(dirname "${BASH_SOURCE[0]}")/base-test.sh"
+
+work_dir=$(mktemp -d)
+trap 'rm -rf "$work_dir"' EXIT
+
+fake_home="$work_dir/home"
+mkdir -p "$fake_home/.config/omarchy/hooks" "$fake_home/.local/state/omarchy"
+
+# --- omarchy-hook --------------------------------------------------------------
+
+# A hook name is a label, not a path. One carrying a slash, or one that is a
+# bare `.` or `..`, would run a script from outside the hooks directory.
+
+cat >"$fake_home/.config/omarchy/hooks/test-hook" <<'SH'
+touch "$HOME/hook-ran"
+SH
+
+HOME="$fake_home" "$ROOT/bin/omarchy-hook" test-hook
+[[ -f $fake_home/hook-ran ]] ||
+  fail "omarchy hook runs a named hook from the hooks directory"
+pass "omarchy hook runs a named hook from the hooks directory"
+
+# Dots inside a name are not a path. a..b stays inside the hooks directory.
+cat >"$fake_home/.config/omarchy/hooks/a..b" <<'SH'
+touch "$HOME/dotted-hook-ran"
+SH
+
+HOME="$fake_home" "$ROOT/bin/omarchy-hook" a..b
+[[ -f $fake_home/dotted-hook-ran ]] ||
+  fail "omarchy hook accepts a hook name with dots in the middle"
+pass "omarchy hook accepts a hook name with dots in the middle"
+
+for name in . ..; do
+  status=0
+  HOME="$fake_home" "$ROOT/bin/omarchy-hook" "$name" >/dev/null 2>&1 || status=$?
+  (( status == 2 )) ||
+    fail "omarchy hook refuses a hook name of $name" "exit: $status"
+  pass "omarchy hook refuses a hook name of $name"
+done
+
+# This file sits where a name of ../../evil would resolve: hooks/../.. is
+# ~/.config.
+cat >"$fake_home/.config/evil" <<'SH'
+touch "$HOME/escape-ran"
+SH
+chmod +x "$fake_home/.config/evil"
+
+status=0
+HOME="$fake_home" "$ROOT/bin/omarchy-hook" "../../evil" >/dev/null 2>&1 || status=$?
+(( status == 2 )) ||
+  fail "omarchy hook refuses a hook name with a dot-dot" "exit: $status"
+[[ ! -e $fake_home/escape-ran ]] ||
+  fail "omarchy hook runs nothing when it refuses the name"
+pass "omarchy hook refuses a hook name with a dot-dot"
+
+status=0
+HOME="$fake_home" "$ROOT/bin/omarchy-hook" "sub/dir" >/dev/null 2>&1 || status=$?
+(( status == 2 )) ||
+  fail "omarchy hook refuses a hook name with a slash" "exit: $status"
+pass "omarchy hook refuses a hook name with a slash"
+
+# --- omarchy-hook-install ------------------------------------------------------
+
+# The installer joins the type into ~/.config/omarchy/hooks/<type>.d before
+# mkdir/cp. The runner already refuses a slashed type; install must too, or a
+# name the runner will not run still lands on disk.
+
+source_hook="$work_dir/source-hook"
+cat >"$source_hook" <<'SH'
+#!/bin/bash
+true
+SH
+
+HOME="$fake_home" "$ROOT/bin/omarchy-hook-install" post-update "$source_hook" >/dev/null
+[[ -f $fake_home/.config/omarchy/hooks/post-update.d/source-hook ]] ||
+  fail "omarchy hook install still installs a named hook"
+pass "omarchy hook install still installs a named hook"
+
+HOME="$fake_home" "$ROOT/bin/omarchy-hook-install" a..b "$source_hook" >/dev/null
+[[ -f $fake_home/.config/omarchy/hooks/a..b.d/source-hook ]] ||
+  fail "omarchy hook install accepts a hook name with dots in the middle"
+pass "omarchy hook install accepts a hook name with dots in the middle"
+
+for name in . ..; do
+  status=0
+  HOME="$fake_home" "$ROOT/bin/omarchy-hook-install" "$name" "$source_hook" >/dev/null 2>&1 || status=$?
+  (( status == 2 )) ||
+    fail "omarchy hook install refuses a hook name of $name" "exit: $status"
+  [[ ! -e $fake_home/.config/omarchy/hooks/${name}.d ]] ||
+    fail "omarchy hook install creates no directory for a hook name of $name"
+  pass "omarchy hook install refuses a hook name of $name"
+done
+
+# hooks/../../evil.d is ~/.config/evil.d. The guard must fire before mkdir.
+status=0
+HOME="$fake_home" "$ROOT/bin/omarchy-hook-install" "../../evil" "$source_hook" >/dev/null 2>&1 || status=$?
+(( status == 2 )) ||
+  fail "omarchy hook install refuses a hook name with a dot-dot" "exit: $status"
+[[ ! -e $fake_home/.config/evil.d ]] ||
+  fail "omarchy hook install creates nothing outside the hooks directory"
+pass "omarchy hook install refuses a hook name with a dot-dot"
+
+status=0
+HOME="$fake_home" "$ROOT/bin/omarchy-hook-install" "sub/dir" "$source_hook" >/dev/null 2>&1 || status=$?
+(( status == 2 )) ||
+  fail "omarchy hook install refuses a hook name with a slash" "exit: $status"
+[[ ! -e $fake_home/.config/omarchy/hooks/sub ]] ||
+  fail "omarchy hook install creates no nested directory from a slashed name"
+pass "omarchy hook install refuses a hook name with a slash"
+
+# --- omarchy-state -------------------------------------------------------------
+
+state_dir="$fake_home/.local/state/omarchy"
+
+HOME="$fake_home" "$ROOT/bin/omarchy-state" set reboot-required
+[[ -f $state_dir/reboot-required ]] ||
+  fail "omarchy state set still creates a plain state file"
+pass "omarchy state set still creates a plain state file"
+
+HOME="$fake_home" "$ROOT/bin/omarchy-state" set v1..2
+[[ -f $state_dir/v1..2 ]] ||
+  fail "omarchy state set accepts a state name with dots in the middle"
+pass "omarchy state set accepts a state name with dots in the middle"
+
+for name in . ..; do
+  status=0
+  HOME="$fake_home" "$ROOT/bin/omarchy-state" set "$name" >/dev/null 2>&1 || status=$?
+  (( status == 2 )) ||
+    fail "omarchy state set refuses a state name of $name" "exit: $status"
+  pass "omarchy state set refuses a state name of $name"
+done
+
+# state/../.. is ~/.local. The guard must fire before touch gets there.
+status=0
+HOME="$fake_home" "$ROOT/bin/omarchy-state" set "../../escape" >/dev/null 2>&1 || status=$?
+(( status == 2 )) ||
+  fail "omarchy state set refuses a state name with a dot-dot" "exit: $status"
+[[ ! -e $fake_home/.local/escape ]] ||
+  fail "omarchy state set creates nothing outside the state directory"
+pass "omarchy state set refuses a state name with a dot-dot"
+
+status=0
+HOME="$fake_home" "$ROOT/bin/omarchy-state" set "sub/dir" >/dev/null 2>&1 || status=$?
+(( status == 2 )) ||
+  fail "omarchy state set refuses a state name with a slash" "exit: $status"
+pass "omarchy state set refuses a state name with a slash"
+
+# clear takes patterns by design ("state-name-or-pattern") and matches
+# basenames through find -name, so it can never walk out of the directory.
+touch "$state_dir/restart-a-required" "$state_dir/restart-b-required" "$state_dir/keep-me"
+HOME="$fake_home" "$ROOT/bin/omarchy-state" clear "restart-*-required"
+[[ ! -e $state_dir/restart-a-required && ! -e $state_dir/restart-b-required && -f $state_dir/keep-me ]] ||
+  fail "omarchy state clear still clears matching patterns only"
+pass "omarchy state clear still clears matching patterns only"
@@ -21,7 +21,7 @@ trap cleanup EXIT
 require_compositor "QML contract test"

 if ! command -v quickshell >/dev/null 2>&1; then
-  pass "quickshell not installed; skipping QML contract test"
+  skip "quickshell not installed; skipping QML contract test"
  exit 0
 fi

@@ -0,0 +1,58 @@
+#!/bin/bash
+
+set -euo pipefail
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+tmp_dir=$(mktemp -d)
+trap 'rm -rf "$tmp_dir"' EXIT
+mkdir -p "$tmp_dir/bin"
+export INSTALLED_PACKAGES="$tmp_dir/installed" CALL_LOG="$tmp_dir/calls"
+export PATH="$tmp_dir/bin:$ROOT/bin:$PATH"
+
+# Keep the real package helpers, but contain every pacman transaction here.
+cat > "$tmp_dir/bin/pacman" <<'SH'
+#!/bin/bash
+case "$1" in
+  -Q) grep -Fxq -- "$2" "$INSTALLED_PACKAGES" ;;
+  -S)
+    [[ ${FAIL_INSTALL:-0} == 0 ]] || exit 1
+    shift 3 # -S --noconfirm --needed
+    printf '%s\n' "$@" >> "$INSTALLED_PACKAGES"
+    printf '%s\n' "$@" >> "$CALL_LOG"
+    ;;
+  *) exit 1 ;;
+esac
+SH
+cat > "$tmp_dir/bin/sudo" <<'SH'
+#!/bin/bash
+[[ $1 == "pacman" ]] || exit 1
+"$@"
+SH
+chmod +x "$tmp_dir/bin/"*
+
+migration="$ROOT/migrations/1789444024.sh"
+for kernels in linux-omarchy linux-t2 'linux-omarchy linux-t2'; do
+  read -ra installed <<< "$kernels"
+  printf '%s\n' linux linux-headers "${installed[@]}" > "$INSTALLED_PACKAGES"
+  : > "$CALL_LOG"
+  bash -euo pipefail "$migration" >/dev/null
+  for kernel in "${installed[@]}"; do
+    grep -Fxq "$kernel-headers" "$INSTALLED_PACKAGES" || fail "$kernel gets its headers"
+  done
+  : > "$CALL_LOG"
+  bash -euo pipefail "$migration" >/dev/null
+  [[ ! -s $CALL_LOG ]] || fail "header repair is idempotent"
+  pass "missing headers are repaired once for $kernels"
+done
+
+printf '%s\n' linux linux-aarch64 > "$INSTALLED_PACKAGES"
+: > "$CALL_LOG"
+bash -euo pipefail "$migration" >/dev/null
+[[ ! -s $CALL_LOG ]] || fail "header repair skips unrelated kernels"
+pass "header repair skips unrelated kernels"
+
+echo linux-omarchy > "$INSTALLED_PACKAGES"
+if FAIL_INSTALL=1 bash -euo pipefail "$migration" >/dev/null; then
+  fail "a failed header installation must leave the migration pending"
+fi
+pass "header installation failure is propagated"
@@ -150,5 +150,5 @@ pass "font controls create missing Kitty overrides without restoring the theme i
 if "$ROOT/bin/omarchy-cmd-present" kitty; then
  kitty +runpy "$(cat "$ROOT/test/shell.d/fixtures/kitty/check-config.py")"
 else
-  pass "Kitty not installed; skipping native config parser checks"
+  skip "Kitty not installed; skipping native config parser checks"
 fi
@@ -4,6 +4,9 @@ set -euo pipefail

 source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"

+# Start with color enabled; the no-color scenarios opt in below.
+unset NO_COLOR
+
 tmp_dir="$(mktemp -d)"
 trap 'rm -rf "$tmp_dir"' EXIT

@@ -32,15 +32,6 @@ check(command == ["/usr/bin/updatedb", *options],
      "locate service runs updatedb directly with fixed Btrfs options")
 check("ConditionACPower=true" in (root / "etc/systemd/system/plocate-updatedb.service.d/ac-only.conf").read_text(),
      "scheduled locate indexing keeps its AC-power condition")
-check(not (root / "install/config/locate.sh").exists() and not (root / "migrations/1784809451.sh").exists(),
-      "the retired locate configuration helper and migration are absent")
-for directory in ("bin", "install", "migrations"):
-  for path in (root / directory).rglob("*"):
-    if path.is_file():
-      content = path.read_text()
-      if "OMARCHY_UPDATEDB_CONF_PATH" in content or "config/locate.sh" in content:
-        raise SystemExit("not ok - retired locate configuration path remains in " + str(path))
-check(True, "runtime and installation no longer reference the configuration rewrite")

 with tempfile.TemporaryDirectory(prefix="omarchy-locate-") as scratch:
  scratch = Path(scratch)
@@ -21,7 +21,7 @@ trap cleanup EXIT
 require_compositor "lock fingerprint indicator test"

 if ! command -v quickshell >/dev/null 2>&1; then
-  pass "quickshell not installed; skipping lock fingerprint indicator test"
+  skip "quickshell not installed; skipping lock fingerprint indicator test"
  exit 0
 fi

@@ -21,7 +21,7 @@ trap cleanup EXIT
 require_compositor "lock password overflow test"

 if ! command -v quickshell >/dev/null 2>&1; then
-  pass "quickshell not installed; skipping lock password overflow test"
+  skip "quickshell not installed; skipping lock password overflow test"
  exit 0
 fi

@@ -21,7 +21,7 @@ trap cleanup EXIT
 require_compositor "manifest entrypoint load test"

 if ! command -v quickshell >/dev/null 2>&1; then
-  pass "quickshell not installed; skipping manifest entrypoint load test"
+  skip "quickshell not installed; skipping manifest entrypoint load test"
  exit 0
 fi

@@ -0,0 +1,270 @@
+#!/bin/bash
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/base-test.sh"
+
+require_command mise
+
+test_dir=$(mktemp -d)
+trap 'rm -rf "$test_dir"' EXIT
+migration="$ROOT/migrations/1789095456.sh"
+
+run_migration() {
+  local test_home="$1"
+
+  env -i \
+    HOME="$test_home" \
+    XDG_CACHE_HOME="$test_home/.cache" \
+    XDG_CONFIG_HOME="$test_home/.config" \
+    XDG_DATA_HOME="$test_home/.local/share" \
+    XDG_STATE_HOME="$test_home/.local/state" \
+    MISE_PARANOID="${OMARCHY_TEST_MISE_PARANOID:-false}" \
+    PATH=/usr/bin \
+    bash -euo pipefail "$migration"
+}
+
+run_mise() {
+  local test_home="$1"
+  shift
+
+  env -i \
+    HOME="$test_home" \
+    XDG_CACHE_HOME="$test_home/.cache" \
+    XDG_CONFIG_HOME="$test_home/.config" \
+    XDG_DATA_HOME="$test_home/.local/share" \
+    XDG_STATE_HOME="$test_home/.local/state" \
+    MISE_PARANOID="${OMARCHY_TEST_MISE_PARANOID:-false}" \
+    PATH=/usr/bin \
+    mise "$@"
+}
+
+mise_environment() {
+  local test_home="$1"
+  local project="$2"
+
+  (
+    cd "$project"
+    run_mise "$test_home" env -s bash
+  )
+}
+
+mise_path_active() {
+  local test_home="$1"
+  local project="$2"
+  local output
+
+  if ! output=$(mise_environment "$test_home" "$project" 2>/dev/null); then
+    return 1
+  fi
+
+  grep -F "$project/bin" <<<"$output" >/dev/null
+}
+
+assert_unsafe_variant_removed() {
+  local variant="$1"
+  local assignment="$2"
+  local variant_home="$test_dir/$variant-home"
+  local variant_config="$variant_home/Work/.mise.toml"
+  local variant_project="$variant_home/Work/tries/untrusted-repository"
+
+  mkdir -p "$variant_project/bin"
+  printf '[env]\n%s\n' "$assignment" >"$variant_config"
+  run_mise "$variant_home" trust "$variant_config" >/dev/null
+
+  mise_path_active "$variant_home" "$variant_project" || fail "$variant legacy config prepends the repository bin directory"
+
+  run_migration "$variant_home" >/dev/null
+  if mise_path_active "$variant_home" "$variant_project"; then
+    fail "$variant repository bin directory remains in PATH after migration"
+  fi
+}
+
+install_home="$test_dir/install-home"
+install_log="$test_dir/install-mise.log"
+mkdir -p "$install_home" "$test_dir/bin"
+cat >"$test_dir/bin/mise" <<'SH'
+#!/bin/bash
+printf '%s\n' "$*" >>"$MISE_TEST_LOG"
+SH
+chmod +x "$test_dir/bin/mise"
+
+env \
+  HOME="$install_home" \
+  MISE_TEST_LOG="$install_log" \
+  OMARCHY_SETUP_CONTEXT=runtime \
+  PATH="$test_dir/bin:/usr/bin" \
+  bash -euo pipefail -c 'source "$1"' bash "$ROOT/install/user/mise-work.sh"
+
+[[ -d $install_home/Work/tries ]] || fail "installer creates the work and tries directories"
+[[ ! -e $install_home/Work/.mise.toml ]] || fail "installer does not create a trusted Work Mise config"
+[[ $(<"$install_log") == "use -g node@latest" ]] || fail "installer only invokes Mise for the global Node setup"
+pass "new installs do not add project bin directories to PATH"
+
+stock_home="$test_dir/stock-home"
+stock_config="$stock_home/Work/.mise.toml"
+stock_project="$stock_home/Work/tries/untrusted-repository"
+mkdir -p "$stock_project/bin"
+cat >"$stock_config" <<'TOML'
+[env]
+_.path = "{{ cwd }}/bin"
+TOML
+run_mise "$stock_home" trust "$stock_config" >/dev/null
+
+mise_path_active "$stock_home" "$stock_project" || fail "legacy config prepends the repository bin directory"
+
+run_migration "$stock_home" >/dev/null
+[[ ! -e $stock_config ]] || fail "migration removes the stock Work Mise config"
+cat >"$stock_config" <<'TOML'
+[env]
+_.path = "{{ cwd }}/bin"
+TOML
+if mise_path_active "$stock_home" "$stock_project"; then
+  fail "recreated Work config remains trusted after migration"
+fi
+run_migration "$stock_home" >/dev/null
+[[ ! -e $stock_config ]] || fail "stock migration is idempotent"
+pass "migration removes the repository bin directory and revokes the Work trust root"
+
+assert_unsafe_variant_removed inline-comment '_.path = "{{ cwd }}/bin" # Omarchy default'
+assert_unsafe_variant_removed single-quoted "_.path = '{{ cwd }}/bin'"
+pass "migration removes annotated and single-quoted project bin paths"
+
+custom_home="$test_dir/custom-home"
+custom_config="$custom_home/Work/.mise.toml"
+mkdir -p "$(dirname "$custom_config")"
+cat >"$custom_config" <<'TOML'
+[env]
+KEEP = "yes"
+  _.path   =   "{{ cwd }}/bin"
+# _.path = "{{ cwd }}/bin"
+
+[tools]
+ruby = "latest"
+
+[other]
+_.path = "{{ cwd }}/bin"
+TOML
+cp "$custom_config" "$test_dir/custom-original"
+cat >"$test_dir/custom-expected" <<'TOML'
+[env]
+KEEP = "yes"
+# _.path = "{{ cwd }}/bin"
+
+[tools]
+ruby = "latest"
+
+[other]
+_.path = "{{ cwd }}/bin"
+TOML
+chmod 600 "$custom_config"
+run_mise "$custom_home" trust "$custom_config" >/dev/null
+
+custom_output=$(run_migration "$custom_home")
+cmp -s "$test_dir/custom-expected" "$custom_config" || fail "migration preserves unrelated custom Mise settings"
+[[ $(stat -c %a "$custom_config") == "600" ]] || fail "migration preserves custom config permissions"
+grep -F "mise trust $custom_config" <<<"$custom_output" >/dev/null || fail "migration explains how to review and re-trust a custom config"
+custom_backups=("$custom_config".bak.*)
+[[ -f ${custom_backups[0]} ]] || fail "migration backs up a customized Mise config"
+(( ${#custom_backups[@]} == 1 )) || fail "migration creates one custom config backup"
+cmp -s "$test_dir/custom-original" "${custom_backups[0]}" || fail "custom config backup preserves the original"
+
+run_migration "$custom_home" >/dev/null
+custom_backups=("$custom_config".bak.*)
+(( ${#custom_backups[@]} == 1 )) || fail "custom migration does not create another backup on rerun"
+cmp -s "$test_dir/custom-expected" "$custom_config" || fail "custom migration is idempotent"
+pass "custom Mise settings, permissions, and original backup survive the repair"
+
+unrelated_home="$test_dir/unrelated-home"
+unrelated_config="$unrelated_home/Work/.mise.toml"
+unrelated_project="$unrelated_home/Work/tries/untrusted-repository"
+mkdir -p "$unrelated_project/bin"
+printf '[env]\nKEEP = "yes"\n' >"$unrelated_config"
+cp "$unrelated_config" "$test_dir/unrelated-original"
+run_mise "$unrelated_home" trust "$unrelated_config" >/dev/null
+run_migration "$unrelated_home" >/dev/null
+cmp -s "$test_dir/unrelated-original" "$unrelated_config" || fail "unrelated Mise config remains unchanged"
+unrelated_backups=("$unrelated_config".bak.*)
+[[ ! -e ${unrelated_backups[0]} ]] || fail "unchanged Mise config is not backed up"
+printf '[env]\n_.path = "{{ cwd }}/bin"\n' >"$unrelated_config"
+if mise_path_active "$unrelated_home" "$unrelated_project"; then
+  fail "safe Work config retains its old trust grant"
+fi
+
+absent_home="$test_dir/absent-home"
+absent_config="$absent_home/Work/.mise.toml"
+absent_project="$absent_home/Work/tries/untrusted-repository"
+mkdir -p "$(dirname "$absent_config")"
+printf '[env]\n_.path = "{{ cwd }}/bin"\n' >"$absent_config"
+run_mise "$absent_home" trust "$absent_config" >/dev/null
+rm "$absent_config"
+rmdir "$absent_home/Work"
+run_migration "$absent_home" >/dev/null
+[[ ! -e $absent_home/Work ]] || fail "migration does not retain a temporary Work directory"
+mkdir -p "$absent_project/bin"
+printf '[env]\n_.path = "{{ cwd }}/bin"\n' >"$absent_config"
+if mise_path_active "$absent_home" "$absent_project"; then
+  fail "deleted Work directory retains its stale trust grant"
+fi
+pass "migration leaves unrelated configs alone and revokes dangling Work trust"
+
+paranoid_home="$test_dir/paranoid-home"
+paranoid_work="$paranoid_home/Work"
+paranoid_config="$paranoid_work/.mise.toml"
+paranoid_project="$paranoid_work/tries/untrusted-repository"
+mkdir -p "$paranoid_project/bin"
+printf '[env]\n_.path = "{{ cwd }}/bin"\n' >"$paranoid_config"
+OMARCHY_TEST_MISE_PARANOID=true run_mise "$paranoid_home" trust "$paranoid_config" >/dev/null
+OMARCHY_TEST_MISE_PARANOID=true mise_path_active "$paranoid_home" "$paranoid_project" || fail "paranoid legacy config prepends the repository bin directory"
+rm -r "$paranoid_work"
+
+OMARCHY_TEST_MISE_PARANOID=true run_migration "$paranoid_home" >/dev/null
+[[ ! -e $paranoid_work ]] || fail "paranoid migration removes its temporary Work directory"
+mkdir -p "$paranoid_project/bin"
+printf '[env]\n_.path = "{{ cwd }}/bin"\n' >"$paranoid_config"
+if OMARCHY_TEST_MISE_PARANOID=true mise_path_active "$paranoid_home" "$paranoid_project"; then
+  fail "paranoid migration retains content-bound trust for the deleted legacy config"
+fi
+pass "migration revokes stale content-bound trust in Mise paranoid mode"
+
+ignored_home="$test_dir/ignored-home"
+ignored_config="$ignored_home/Work/.mise.toml"
+ignored_project="$ignored_home/Work/tries/untrusted-repository"
+mkdir -p "$ignored_project/bin"
+cat >"$ignored_config" <<'TOML'
+[env]
+_.path = "{{ cwd }}/bin"
+KEEP = "yes"
+TOML
+run_mise "$ignored_home" trust "$ignored_config" >/dev/null
+run_mise "$ignored_home" trust --ignore "$ignored_config" >/dev/null
+
+ignored_output=$(run_migration "$ignored_home")
+grep -F '{{ cwd }}/bin' "$ignored_config" >/dev/null && fail "ignored config retains the unsafe path"
+grep -Fx 'KEEP = "yes"' "$ignored_config" >/dev/null || fail "ignored config keeps unrelated settings"
+ignored_entries=("$ignored_home/.local/state/mise/ignored-configs/"*)
+[[ -L ${ignored_entries[0]} ]] || fail "migration preserves the explicit Mise ignore marker"
+(( ${#ignored_entries[@]} == 1 )) || fail "migration preserves exactly one Mise ignore marker"
+ignored_target=$(readlink "${ignored_entries[0]}")
+[[ $ignored_target == $ignored_home/Work || $ignored_target == $ignored_config ]] || fail "preserved Mise ignore marker still targets the Work config"
+grep -F "remains ignored by Mise" <<<"$ignored_output" >/dev/null || fail "migration reports that the custom config remains ignored"
+if mise_path_active "$ignored_home" "$ignored_project"; then
+  fail "ignored config becomes active after migration"
+fi
+pass "migration preserves an explicit decision to ignore the Work config"
+
+symlink_home="$test_dir/symlink-home"
+symlink_config="$symlink_home/Work/.mise.toml"
+symlink_target="$test_dir/dotfiles-mise.toml"
+mkdir -p "$(dirname "$symlink_config")"
+cat >"$symlink_target" <<'TOML'
+[env]
+_.path = "{{ cwd }}/bin"
+KEEP = "yes"
+TOML
+ln -s "$symlink_target" "$symlink_config"
+
+run_migration "$symlink_home" >/dev/null
+[[ -L $symlink_config ]] || fail "migration preserves a dotfile symlink"
+grep -F '{{ cwd }}/bin' "$symlink_target" >/dev/null && fail "symlink target retains the unsafe path"
+grep -Fx 'KEEP = "yes"' "$symlink_target" >/dev/null || fail "symlink target keeps unrelated settings"
+pass "custom dotfile symlinks survive the repair"
@@ -7,6 +7,14 @@ source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
 tmp=$(mktemp -d)
 trap 'rm -rf "$tmp"' EXIT
 mkdir -p "$tmp/bin"
+export QR_ROUTE_EXIT=0
+
+# Loopback is never wireless, so exercise the connected-Wi-Fi fallback.
+cat >"$tmp/bin/ip" <<'EOF'
+#!/bin/bash
+[[ $QR_ROUTE_EXIT == "0" ]] || exit "$QR_ROUTE_EXIT"
+printf '1.1.1.1 dev lo\n'
+EOF

 cat >"$tmp/bin/nmcli" <<'EOF'
 #!/bin/bash
@@ -28,13 +36,13 @@ payload=$(</dev/stdin)
 printf '%s' "$payload" >"$QR_PAYLOAD_FILE"
 printf '##    \n  ##  \n    ##\n'
 EOF
-chmod +x "$tmp/bin/nmcli" "$tmp/bin/qrencode"
+chmod +x "$tmp/bin/ip" "$tmp/bin/nmcli" "$tmp/bin/qrencode"

 run_success_case() {
  local description=$1 fields=$2 expected_payload=$3
  shift 3
  local output meta matrix payload arg with_meta=false
-  local expected_matrix expected_security expected_ssid expected_iface="*"
+  local expected_matrix expected_security expected_ssid expected_iface="wlan0"

  for arg in "$@"; do
    [[ $arg == "--meta" ]] && with_meta=true || expected_iface=$arg
@@ -49,9 +57,8 @@ run_success_case() {
    meta=$(head -n1 <<<"$output")
    matrix=$(tail -n +2 <<<"$output")

-    # The meta line leads with the shared interface, security, and SSID. With
-    # no interface argument the helper detects one from the live host, so that
-    # field is only pinned when the case pinned it.
+    # The metadata reports the requested interface, or the connected Wi-Fi
+    # interface supplied by the nmcli stub when no interface was requested.
    expected_security=${expected_payload#WIFI:T:}
    expected_security=${expected_security%%;*}
    expected_ssid=$(head -n1 <<<"$fields")
@@ -88,6 +95,12 @@ run_success_case \
  'WIFI:T:WPA;S:Cafe Detected;P:secret;;' \
  --meta

+QR_ROUTE_EXIT=2 run_success_case \
+  "network QR helper detects Wi-Fi when route lookup fails" \
+  $'Cafe No Route\nwpa-psk\nsecret\nno\n' \
+  'WIFI:T:WPA;S:Cafe No Route;P:secret;;' \
+  --meta
+
 run_success_case \
  "network QR helper supports open networks" \
  $'Cafe Open\nnone\n\nno\n' \
@@ -140,7 +140,6 @@ export OMARCHY_PTL_REBUILD_MARKER="$scratch/state/1789095456"
 export OMARCHY_MIGRATION_STATE="$scratch/user-markers"
 touch "$OMARCHY_PTL_REBUILD_MARKER" "$OMARCHY_MIGRATION_STATE/1789095456.sh"
 cp "$migration" "$scratch/omarchy/migrations/"
-[[ ! -e $ROOT/migrations/1789095456.sh ]] || fail "the superseded migration must not install the PTL variant first"
 pending=$(OMARCHY_PATH="$scratch/omarchy" "$ROOT/bin/omarchy-migrate" --pending)
 [[ $pending == "1789325478.sh" ]] || fail "the renamed migration is pending after completing the old migration"
 OMARCHY_PATH="$scratch/omarchy" "$ROOT/bin/omarchy-migrate" > "$scratch/output" 2>&1