Avoid transient Hyprland binding module errors

Move stock Hyprland bindings into defaults
Fix notification popup placement
2026-08-02 04:37:49 +02:00 · 2026-06-16 01:27:43 -04:00 · 2026-06-16 01:25:04 -04:00 · 2026-06-16 01:25:04 -04:00 · 2026-06-15 11:27:54 -04:00 · 2026-06-14 21:12:42 -04:00
692 changed files with 9581 additions and 5743 deletions
@@ -0,0 +1,4 @@
+
+# Python bytecode (orchestrator)
+__pycache__/
+*.pyc
@@ -74,18 +74,19 @@ Example:

 # Install Scripts

-Install entry points (`install.sh`, `boot.sh`) use `#!/bin/bash`. Many scripts under `install/` are sourced via `run_logged` and intentionally do not have shebangs.
+The ISO owns installation orchestration. This repo ships target-side setup commands and reusable setup leaves:

-Install stage files follow this pattern:
+- `bin/omarchy-setup-system` runs root-owned system setup during ISO finalization.
+- `bin/omarchy-setup-hardware` runs idempotent hardware-specific setup and is called by `omarchy-setup-system`.
+- `bin/omarchy-finalize-user` runs the per-user runtime finalization (skill symlinks, xdg-user-dirs, mime defaults, `install/user/all.sh`). Shipped user defaults are seeded by `/etc/skel` from `omarchy-settings`, not by this command. `bin/omarchy-reinstall-configs` is the explicit destructive resync of those defaults into an existing user's `$HOME`.
+- leaf scripts under `install/` are sourced by `run_logged $OMARCHY_INSTALL/path/to/script.sh` and intentionally do not have shebangs.
+- avoid `exit` in sourced setup scripts unless intentionally aborting setup.
+- 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.
+- prefer helper commands for package and command checks where available.

- `install/*/all.sh` lists scripts in execution order
- leaf scripts are sourced by `run_logged $OMARCHY_INSTALL/path/to/script.sh`
- avoid `exit` in sourced install scripts unless intentionally aborting the install
- use `$OMARCHY_INSTALL` and `$OMARCHY_PATH` instead of hard-coded Omarchy paths
- keep hardware-specific logic under `install/config/hardware/`
- prefer helper commands for package and command checks where available
-
-Raw `command -v`, `pacman`, and `pacman-key` are acceptable in bootstrap/preflight/package-helper contexts where the helper commands may not be available yet or where direct package-manager behavior is the point of the script.
+Raw `command -v`, `pacman`, and `pacman-key` are acceptable in package-helper contexts where direct package-manager behavior is the point of the script.

 # Helper Commands

@@ -98,13 +99,13 @@ Use these instead of raw shell commands:
 - `omarchy-notification-send` - send desktop notifications; do not call `notify-send` directly
 - `omarchy-hw-asus-rog` - detect ASUS ROG hardware (and similar `hw-*` commands)

-Exceptions are allowed for bootstrap, preflight, migration, and package-helper scripts where the helper may not be available yet, where the helper itself is being implemented, or where direct package-manager behavior is required.
+Exceptions are allowed for migration and package-helper scripts where the helper may not be available yet, where the helper itself is being implemented, or where direct package-manager behavior is required.

 # Config Structure

 - `config/` - default configs copied to `~/.config/`
 - `default/themed/*.tpl` - templates with `{{ variable }}` placeholders for theme colors
- `themes/*/colors.toml` - theme color definitions (accent, background, foreground, red/green/yellow/blue/magenta/cyan and bright_* variants)
+- `themes/*/colors.toml` - theme color definitions (accent, bg, fg, red/green/yellow/blue/magenta/cyan and bright_* variants)

 # Tests

@@ -170,19 +171,23 @@ To copy a default config to user config with automatic backup:
 omarchy-refresh-config hypr/hyprlock.conf
 ```

-This copies `~/.local/share/omarchy/config/hypr/hyprlock.conf` to `~/.config/hypr/hyprlock.conf`.
+This copies `/etc/skel/.config/hypr/hyprlock.conf` to `~/.config/hypr/hyprlock.conf`.

 # Migrations

-To create a new migration, run `omarchy-dev-add-migration --no-edit`. This creates a migration file named after the unix timestamp of the last commit.
+Read `docs/migrations.md` before creating or changing migrations.
+
+Migrations are per-user and run through `omarchy-migrate` during `omarchy update` or from the migration notification. Put migrations directly under `migrations/<timestamp>.sh`. Pending state is per-user under `~/.local/state/omarchy/migrations/`, so every user gets a chance to run every migration. Migrations run as the user; privileged work should invoke the appropriate helper or privilege prompt, and no-op when another user already applied it.
+
+To create a new migration, run `omarchy-dev-add-migration --no-edit`.

 New migration format:
- File permissions must be `0644` (`-rw-r--r--`); migrations are sourced, not executed directly
+- File permissions must be `0644` (`-rw-r--r--`); migration runners execute them with `bash -euo pipefail`, not through executable bits
 - No shebang line
 - Start with an `echo` describing what the migration does
 - Use `$OMARCHY_PATH` to reference the omarchy directory
 - Prefer helper commands such as `omarchy-cmd-present`, `omarchy-cmd-missing`, `omarchy-pkg-present`, and `omarchy-pkg-missing`

-Some older migrations predate these rules. Do not copy older migrations that start with shebangs, omit the leading `echo`, or hard-code `~/.local/share/omarchy`.
+Omarchy 4.0 is upgraded through `bin/omarchy-upgrade-to-4`, not through the normal migration runner. Do not add compatibility migrations for old installer layouts; put pre-4 package-layout transition work in the upgrade command instead.

-Migrations may use raw `pacman`, `command -v`, or direct config edits when needed for historical compatibility or one-off repair work.
+Migrations may use raw `pacman`, `command -v`, or direct config edits when needed for one-off repair work.
@@ -0,0 +1,8 @@
+[Desktop Entry]
+Version=1.0
+Name=Basecamp
+Exec=omarchy-launch-webapp https://launchpad.37signals.com
+Terminal=false
+Type=Application
+Icon=basecamp
+StartupNotify=true
@@ -0,0 +1,8 @@
+[Desktop Entry]
+Version=1.0
+Name=ChatGPT
+Exec=omarchy-launch-webapp https://chatgpt.com/
+Terminal=false
+Type=Application
+Icon=chatgpt
+StartupNotify=true
@@ -0,0 +1,8 @@
+[Desktop Entry]
+Version=1.0
+Name=Discord
+Exec=omarchy-launch-webapp https://discord.com/channels/@me
+Terminal=false
+Type=Application
+Icon=omarchy-discord
+StartupNotify=true
@@ -0,0 +1,8 @@
+[Desktop Entry]
+Version=1.0
+Name=Disk Usage
+Exec=xdg-terminal-exec --app-id=TUI.float -e bash -c "dua i /"
+Terminal=false
+Type=Application
+Icon=disk-usage
+StartupNotify=true
@@ -0,0 +1,8 @@
+[Desktop Entry]
+Version=1.0
+Name=Docker
+Exec=xdg-terminal-exec --app-id=TUI.tile -e lazydocker
+Terminal=false
+Type=Application
+Icon=docker
+StartupNotify=true
@@ -0,0 +1,8 @@
+[Desktop Entry]
+Version=1.0
+Name=Figma
+Exec=omarchy-launch-webapp https://figma.com/
+Terminal=false
+Type=Application
+Icon=figma
+StartupNotify=true
@@ -0,0 +1,8 @@
+[Desktop Entry]
+Version=1.0
+Name=Fizzy
+Exec=omarchy-launch-webapp https://app.fizzy.do/
+Terminal=false
+Type=Application
+Icon=fizzy
+StartupNotify=true
@@ -0,0 +1,8 @@
+[Desktop Entry]
+Version=1.0
+Name=GitHub
+Exec=omarchy-launch-webapp https://github.com/
+Terminal=false
+Type=Application
+Icon=github
+StartupNotify=true
@@ -0,0 +1,8 @@
+[Desktop Entry]
+Version=1.0
+Name=Google Contacts
+Exec=omarchy-launch-webapp https://contacts.google.com/
+Terminal=false
+Type=Application
+Icon=google-contacts
+StartupNotify=true
@@ -0,0 +1,8 @@
+[Desktop Entry]
+Version=1.0
+Name=Google Maps
+Exec=omarchy-launch-webapp https://maps.google.com
+Terminal=false
+Type=Application
+Icon=google-maps
+StartupNotify=true
@@ -0,0 +1,8 @@
+[Desktop Entry]
+Version=1.0
+Name=Google Messages
+Exec=omarchy-launch-webapp https://messages.google.com/web/conversations
+Terminal=false
+Type=Application
+Icon=google-messages
+StartupNotify=true
@@ -0,0 +1,8 @@
+[Desktop Entry]
+Version=1.0
+Name=Google Photos
+Exec=omarchy-launch-webapp https://photos.google.com/
+Terminal=false
+Type=Application
+Icon=google-photos
+StartupNotify=true
@@ -0,0 +1,9 @@
+[Desktop Entry]
+Version=1.0
+Name=HEY
+Exec=omarchy-webapp-handler-hey %u
+Terminal=false
+Type=Application
+Icon=hey
+StartupNotify=true
+MimeType=x-scheme-handler/mailto
@@ -0,0 +1,8 @@
+[Desktop Entry]
+Version=1.0
+Name=WhatsApp
+Exec=omarchy-launch-webapp https://web.whatsapp.com/
+Terminal=false
+Type=Application
+Icon=whatsapp
+StartupNotify=true
@@ -0,0 +1,8 @@
+[Desktop Entry]
+Version=1.0
+Name=X
+Exec=omarchy-launch-webapp https://x.com/
+Terminal=false
+Type=Application
+Icon=x
+StartupNotify=true
@@ -0,0 +1,8 @@
+[Desktop Entry]
+Version=1.0
+Name=YouTube
+Exec=omarchy-launch-webapp https://youtube.com/
+Terminal=false
+Type=Application
+Icon=youtube
+StartupNotify=true
@@ -0,0 +1,9 @@
+[Desktop Entry]
+Version=1.0
+Name=Zoom
+Exec=omarchy-webapp-handler-zoom %u
+Terminal=false
+Type=Application
+Icon=zoom
+StartupNotify=true
+MimeType=x-scheme-handler/zoommtg;x-scheme-handler/zoomus
@@ -4,7 +4,7 @@ Name=Battle.net
 GenericName=Game Launcher
 Comment=Blizzard game launcher (umu-launcher + GE-Proton)
 Exec=omarchy-launch-battlenet
-Icon=Battle.net
+Icon=battle-net
 Terminal=false
 Categories=Game;
 StartupNotify=true
@@ -39,6 +39,7 @@ GROUP_DESCRIPTIONS[clipboard]="Clipboard helpers"
 GROUP_DESCRIPTIONS[cmd]="Command and shortcut helpers"
 GROUP_DESCRIPTIONS[config]="System configuration helpers"
 GROUP_DESCRIPTIONS[debug]="Diagnostics and support logs"
+GROUP_DESCRIPTIONS[finalize]="Finalize user setup"
 GROUP_DESCRIPTIONS[default]="Default application selection"
 GROUP_DESCRIPTIONS[dev]="Omarchy development tools"
 GROUP_DESCRIPTIONS[dns]="DNS resolver configuration"
@@ -1,18 +0,0 @@
-#!/bin/bash
-
-# omarchy:summary=Set the branch for Omarchy's git repository.
-# omarchy:args=<master|rc|dev>
-
-if (($# == 0)); then
-  echo "Usage: omarchy-branch-set [master|rc|dev]"
-  exit 1
-else
-  branch="$1"
-fi
-
-if [[ $branch != "master" && $branch != "rc" && $branch != "dev" ]]; then
-  echo "Error: Invalid branch '$branch'. Must be one of: master, rc, dev"
-  exit 1
-fi
-
-git -C $OMARCHY_PATH switch $branch
@@ -16,7 +16,7 @@ fi

 pkill slurp && exit 0

-SCREENSHOT_EDITOR="${OMARCHY_SCREENSHOT_EDITOR:-satty}"
+SCREENSHOT_EDITOR="${OMARCHY_SCREENSHOT_EDITOR:-tensaku-edit}"

 # Parse --editor flag from any position
 ARGS=()
@@ -31,15 +31,7 @@ set -- "${ARGS[@]}"

 open_editor() {
  local filepath="$1"
-  if [[ $SCREENSHOT_EDITOR == "satty" ]]; then
-    satty --filename "$filepath" \
-      --output-filename "$filepath" \
-      --actions-on-enter save-to-clipboard \
-      --save-after-copy \
-      --copy-command 'wl-copy --type image/png'
-  else
-    $SCREENSHOT_EDITOR "$filepath"
-  fi
+  "$SCREENSHOT_EDITOR" "$filepath"
 }

 MODE="${1:-smart}"
@@ -0,0 +1,33 @@
+#!/bin/bash
+
+# omarchy:summary=Print the active Omarchy package channel
+
+set -euo pipefail
+
+conf=${OMARCHY_CONFIG_FILE:-/etc/omarchy.conf}
+omarchy_path=${OMARCHY_PATH:-/usr/share/omarchy}
+
+if [[ -r $conf ]]; then
+  configured_path=$(bash -c 'source "$1"; printf "%s\n" "${OMARCHY_PATH:-}"' bash "$conf" 2>/dev/null || true)
+  [[ -n $configured_path ]] && omarchy_path="$configured_path"
+fi
+
+channel=$(omarchy-version-channel 2>/dev/null | awk '{ print $1 }')
+
+if pacman -Q omarchy-dev omarchy-settings-dev >/dev/null 2>&1; then
+  case "$channel" in
+    rc) echo rc ;;
+    edge)
+      if [[ $omarchy_path == "/usr/share/omarchy" ]]; then
+        echo dev
+      else
+        echo edge
+      fi
+      ;;
+    *) echo unknown ;;
+  esac
+elif pacman -Q omarchy omarchy-settings >/dev/null 2>&1 && [[ $channel == "stable" ]]; then
+  echo stable
+else
+  echo unknown
+fi
@@ -1,22 +1,123 @@
 #!/bin/bash

-# omarchy:summary=Set the Omarchy channel, which dictates what git branch and package repository is used.
-# omarchy:args=<stable|rc|edge|dev>
+# omarchy:summary=Set the Omarchy package channel.
+# omarchy:args=<stable|rc|dev|edge>
 # omarchy:requires-sudo=true

-if (($# == 0)); then
-  echo "Usage: omarchy-channel-set [stable|rc|edge|dev]"
-  exit 1
-else
-  channel="$1"
-fi
+set -euo pipefail
+
+usage() { echo "Usage: omarchy-channel-set [stable|rc|dev|edge]"; }
+fail() { echo "Error: $*" >&2; exit 1; }
+
+confirm_edge() {
+  cat <<'WARNING'
+
+Edge links Omarchy directly to a mutable source checkout.
+
+This disables package-based protections for the Omarchy code path, including
+normal package updates and package-backed snapshot restores. You'll be
+responsible for pulling, fixing, and restoring that checkout yourself.
+
+WARNING
+
+  if omarchy-cmd-present gum; then
+    gum confirm --default=false "Enable Edge anyway?"
+  else
+    local answer=""
+    read -r -p "Enable Edge anyway? [y/N] " answer
+    [[ $answer == "y" || $answer == "Y" || $answer == "yes" || $answer == "YES" ]]
+  fi
+}
+
+choose_edge_checkout() {
+  local default_path="$HOME/Work/omarchy"
+  local path="${OMARCHY_EDGE_PATH:-}"
+
+  if [[ -z $path ]]; then
+    if omarchy-cmd-present gum; then
+      path=$(gum input --value "$default_path" --placeholder "$default_path" --header "Where should Edge checkout live? Existing non-checkout paths will not be overwritten.") || exit 1
+    else
+      read -r -p "Edge checkout path [$default_path]: " path
+    fi
+  fi
+
+  path="${path:-$default_path}"
+  case "$path" in
+    "~") path="$HOME" ;;
+    "~/"*) path="$HOME/${path#~/}" ;;
+    /*) ;;
+    *) path="$PWD/$path" ;;
+  esac
+
+  if [[ -e $path && ! -d $path/.git ]]; then
+    fail "$path already exists and is not a git checkout. Choose an empty path or an existing Omarchy checkout."
+  fi
+
+  if [[ -d $path/.git && ( ! -d $path/bin || ! -d $path/default || ! -d $path/shell ) ]]; then
+    fail "$path is a git checkout, but it does not look like Omarchy."
+  fi
+
+  printf '%s\n' "$path"
+}
+
+sync_edge_checkout() {
+  local checkout="$1"
+
+  if [[ -d $checkout/.git ]]; then
+    echo "Updating Edge checkout at $checkout"
+    git -C "$checkout" fetch origin quattro
+    git -C "$checkout" checkout quattro 2>/dev/null || git -C "$checkout" checkout --track origin/quattro
+    git -C "$checkout" pull --ff-only origin quattro
+  else
+    mkdir -p "$(dirname -- "$checkout")"
+    git clone --branch quattro --single-branch https://github.com/basecamp/omarchy.git "$checkout"
+  fi
+
+  omarchy-dev-link "$checkout"
+}
+
+(( $# > 0 )) || { usage; exit 1; }
+
+edge_checkout=""
+channel="$1"

 case "$channel" in
-"stable") omarchy-branch-set "master" && omarchy-refresh-pacman "stable" ;;
-"rc") omarchy-branch-set "rc" && omarchy-refresh-pacman "rc" ;;
-"edge") omarchy-branch-set "master" && omarchy-refresh-pacman "edge" ;;
-"dev") omarchy-branch-set "dev" && omarchy-refresh-pacman "edge" ;;
-*) echo "Unknown channel: $channel"; exit 1; ;;
+  stable)
+    pacman_channel=stable
+    packages=(omarchy omarchy-settings)
+    ;;
+  rc)
+    pacman_channel=rc
+    packages=(omarchy-dev omarchy-settings-dev)
+    ;;
+  dev)
+    pacman_channel=edge
+    packages=(omarchy-dev omarchy-settings-dev)
+    ;;
+  edge|source)
+    confirm_edge || { echo "Cancelled."; exit 0; }
+    edge_checkout=$(choose_edge_checkout)
+    pacman_channel=edge
+    packages=(omarchy-dev omarchy-settings-dev)
+    ;;
+  *)
+    echo "Unknown channel: $channel" >&2
+    usage >&2
+    exit 1
+    ;;
 esac

+omarchy-refresh-pacman "$pacman_channel"
+# --ask 4 accepts omarchy <-> omarchy-dev replacement prompts without file overwrites.
+sudo env OMARCHY_UPDATE_PACMAN=1 pacman -S --needed --noconfirm --ask 4 "${packages[@]}"
+
+if [[ -z $edge_checkout ]] && omarchy-cmd-present omarchy-dev-unlink; then
+  omarchy-dev-unlink
+  export OMARCHY_PATH=/usr/share/omarchy
+fi
+
 omarchy-update -y
+
+if [[ -n $edge_checkout ]]; then
+  sync_edge_checkout "$edge_checkout"
+fi
@@ -29,7 +29,7 @@ open_image() {
  local path="$1"

  [[ -r $path ]] || exit 1
-  exec satty --filename "$path" --output-filename "$path"
+  exec tensaku-edit "$path"
 }

 open_text() {
@@ -37,7 +37,7 @@ fi
 cat > "$LOG_FILE" <<EOF
 Date: $(date)
 Hostname: $(hostname)
-Omarchy Branch: $(git -C "$OMARCHY_PATH" branch --show-current 2>/dev/null || echo "unknown")
+Omarchy Package: $(pacman -Q omarchy 2>/dev/null || echo "unknown")

 =========================================
 SYSTEM INFORMATION
@@ -75,14 +75,12 @@ ACTION=$(gum choose "${OPTIONS[@]}")
 case "$ACTION" in
  "Upload log")
    echo "Uploading debug log to logs.omarchy.org..."
-    URL=$(curl -sF "file=@$LOG_FILE" -Fexpires=24 https://logs.omarchy.org)
+    URL=$(curl -sf -F "file=@$LOG_FILE" -Fexpires=24 https://logs.omarchy.org/)
    if (( $? == 0 )) && [[ -n $URL ]]; then
      echo "✓ Log uploaded successfully!"
      echo "Share this URL:"
      echo ""
      echo "  $URL"
-      echo ""
-      echo "This link will expire in 24 hours."
    else
      echo "Error: Failed to upload log file"
      exit 1
@@ -5,7 +5,8 @@
 # omarchy:examples=omarchy default terminal ghostty | omarchy default terminal kitty

 if (($# == 0)); then
-  desktop_id=$(grep -vE '^($|#)' ~/.config/xdg-terminals.list 2>/dev/null | head -n 1)
+  desktop_id=$(xdg-terminal-exec --print-id 2>/dev/null || true)
+  desktop_id=${desktop_id%%:*}
  case "$desktop_id" in
  Alacritty.desktop) echo "alacritty" ;;
  foot.desktop) echo "foot" ;;
@@ -1,13 +1,41 @@
 #!/bin/bash

-# omarchy:summary=Creates a new Omarchy migration named after the unix timestamp of the last commit.
+# omarchy:summary=Create a new Omarchy migration in the current source tree.
+# omarchy:args=[--no-edit]

-cd ~/.local/share/omarchy
-migration_file="$HOME/.local/share/omarchy/migrations/$(git log -1 --format=%cd --date=unix).sh"
-touch $migration_file
+set -euo pipefail

-if [[ $1 != "--no-edit" ]]; then
-  nvim $migration_file
+no_edit=0
+
+while (($#)); do
+  case "$1" in
+    --no-edit)
+      no_edit=1
+      shift
+      ;;
+    system|user)
+      echo "omarchy-dev-add-migration: migration scopes are no longer used; creating a regular migration." >&2
+      shift
+      ;;
+    -h|--help)
+      echo "Usage: omarchy-dev-add-migration [--no-edit]"
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      echo "Usage: omarchy-dev-add-migration [--no-edit]" >&2
+      exit 1
+      ;;
+  esac
+done
+
+cd "${OMARCHY_PATH:-$(pwd)}"
+mkdir -p migrations
+migration_file="migrations/$(git log -1 --format=%cd --date=unix).sh"
+touch "$migration_file"
+
+if (( ! no_edit )); then
+  nvim "$migration_file"
 fi

-echo $migration_file
+printf '%s\n' "$PWD/$migration_file"
@@ -0,0 +1,61 @@
+#!/bin/bash
+
+# omarchy:summary=Point Omarchy at a local checkout after reboot
+# omarchy:group=dev
+# omarchy:args=<path-to-checkout>
+# omarchy:examples=omarchy dev link ~/Work/omarchy/omarchy-installer
+
+set -euo pipefail
+
+if (( EUID == 0 )); then
+  echo "Error: run omarchy-dev-link as your user, not under sudo." >&2
+  exit 1
+fi
+
+if (( $# != 1 )) || [[ $1 == "-h" || $1 == "--help" ]]; then
+  cat <<USAGE
+Usage: omarchy dev link <path-to-checkout>
+
+Writes /etc/omarchy.conf so OMARCHY_PATH resolves to <path-to-checkout>
+after reboot. This intentionally does not rewrite the running Hyprland,
+systemd, shell, or app-launcher environment; reboot to make every layer agree.
+
+Affects only \$OMARCHY_PATH-resolved trees: bin/, default/, shell/,
+themes/, applications/, config/. Files installed at fixed system paths
+(/etc/, /usr/lib/systemd/, udev rule bodies, /etc/skel after user
+creation, /usr/share/plymouth) are NOT covered — for those, use
+omarchy-dev-pkg-test to build and install the package from the checkout.
+USAGE
+  exit 0
+fi
+
+omarchy_conf_quote() {
+  local value="$1"
+  value=${value//\\/\\\\}
+  value=${value//\"/\\\"}
+  value=${value//\$/\\\$}
+  value=${value//\`/\\\`}
+  printf '"%s"' "$value"
+}
+
+target=$(realpath -e "$1" 2>/dev/null) || {
+  echo "Error: path does not exist: $1" >&2
+  exit 1
+}
+
+for required in bin default shell; do
+  if [[ ! -d $target/$required ]]; then
+    echo "Warning: $target/$required not found — does this look like an Omarchy source checkout?" >&2
+  fi
+done
+
+{
+  printf 'export OMARCHY_PATH='
+  omarchy_conf_quote "$target"
+  printf '\n'
+} | sudo tee /etc/omarchy.conf >/dev/null
+
+echo "Pointed Omarchy at $target"
+echo
+echo "Reboot to activate the linked checkout in Hyprland, app launchers, and new shells."
+echo "Run 'omarchy dev unlink' and reboot to restore the package install."
@@ -0,0 +1,137 @@
+#!/bin/bash
+
+# omarchy:summary=Build and install an Omarchy package from a local checkout
+# omarchy:group=dev
+# omarchy:args=[package-name] [path-to-checkout]
+# omarchy:examples=omarchy dev pkg-test | omarchy dev pkg-test omarchy-dev ~/Work/omarchy/omarchy-installer
+
+set -euo pipefail
+
+if [[ ${1:-} == "-h" || ${1:-} == "--help" ]]; then
+  cat <<USAGE
+Usage: omarchy dev pkg-test [package-name] [path-to-checkout]
+
+Builds and installs an Omarchy package from a local Omarchy source
+checkout. Use when changes need to land at fixed system paths (/etc/,
+/usr/lib/systemd/, udev rule bodies, plymouth) that omarchy-dev-link
+can't shadow.
+
+Defaults:
+  packages          omarchy-settings-dev omarchy-dev
+  path-to-checkout  ~/Work/omarchy/omarchy-installer
+
+Examples:
+  omarchy dev pkg-test
+  omarchy dev pkg-test omarchy-settings-dev
+  omarchy dev pkg-test omarchy-dev ~/Work/omarchy/omarchy-installer
+
+The pkgver of the built package is tagged 'dev.<short-sha>[.dirty]' so
+'pacman -Q' makes it obvious where the installed version came from.
+
+PKGBUILDs are read from \${OMARCHY_PKGBUILDS_DIR:-~/Work/omarchy/omarchy-pkgs/pkgbuilds}/<package-name>/.
+USAGE
+  exit 0
+fi
+
+remove_pkgver_function() {
+  local pkgbuild="$1"
+  local tmp="$pkgbuild.tmp"
+
+  awk '
+    /^pkgver\(\)[[:space:]]*\{/ {
+      in_pkgver = 1
+      depth = 0
+    }
+    in_pkgver {
+      line = $0
+      opens = gsub(/\{/, "{", line)
+      line = $0
+      closes = gsub(/\}/, "}", line)
+      depth += opens - closes
+      if (depth <= 0) {
+        in_pkgver = 0
+      }
+      next
+    }
+    { print }
+  ' "$pkgbuild" >"$tmp"
+  mv "$tmp" "$pkgbuild"
+}
+
+dev_package_name() {
+  local pkg="$1"
+
+  case "$pkg" in
+    omarchy | omarchy-settings)
+      printf '%s-dev\n' "$pkg"
+      ;;
+    *)
+      printf '%s\n' "$pkg"
+      ;;
+  esac
+}
+
+if (( $# == 0 )); then
+  PKGS=(omarchy-settings-dev omarchy-dev)
+  CHECKOUT="$HOME/Work/omarchy/omarchy-installer"
+  MAKEPKG_ARGS=()
+else
+  PKGS=("$(dev_package_name "$1")")
+  CHECKOUT="${2:-$HOME/Work/omarchy/omarchy-installer}"
+  MAKEPKG_ARGS=("${@:3}")
+fi
+PKGBUILDS_ROOT="${OMARCHY_PKGBUILDS_DIR:-$HOME/Work/omarchy/omarchy-pkgs/pkgbuilds}"
+
+if [[ ! -d "$CHECKOUT" ]]; then
+  echo "Error: checkout not found at $CHECKOUT" >&2
+  exit 1
+fi
+for PKG in "${PKGS[@]}"; do
+  PKGBUILD_DIR="$PKGBUILDS_ROOT/$PKG"
+  if [[ ! -f "$PKGBUILD_DIR/PKGBUILD" ]]; then
+    echo "Error: PKGBUILD not found at $PKGBUILD_DIR/PKGBUILD" >&2
+    echo "       Pass a different package name as arg 1, or set OMARCHY_PKGBUILDS_DIR." >&2
+    exit 1
+  fi
+done
+
+build_dir=$(mktemp -d -t omarchy-dev-pkg-test.XXXXXX)
+trap 'rm -rf "$build_dir"' EXIT
+
+# pkgver=dev.<sha>[.dirty] so pacman -Q makes the source obvious.
+short_sha=$(git -C "$CHECKOUT" rev-parse --short HEAD 2>/dev/null || echo "local")
+dirty=""
+if [[ -d "$CHECKOUT/.git" ]] && [[ -n "$(git -C "$CHECKOUT" status --porcelain)" ]]; then
+  dirty=".dirty"
+fi
+new_pkgver="dev.${short_sha}${dirty}"
+
+for PKG in "${PKGS[@]}"; do
+  PKGBUILD_DIR="$PKGBUILDS_ROOT/$PKG"
+  package_build_dir="$build_dir/$PKG"
+  mkdir -p "$package_build_dir"
+  cp -a "$PKGBUILD_DIR/." "$package_build_dir/"
+
+  remove_pkgver_function "$package_build_dir/PKGBUILD"
+  sed -i "s/^pkgver=.*/pkgver=${new_pkgver}/" "$package_build_dir/PKGBUILD"
+
+  echo "Building $PKG ${new_pkgver} from $CHECKOUT"
+  echo "  build dir: $package_build_dir"
+  echo "  PKGBUILD : $PKGBUILD_DIR/PKGBUILD"
+  echo
+
+  (
+    cd "$package_build_dir"
+    OMARCHY_SRC="$CHECKOUT" makepkg -s --skipchecksums --noconfirm "${MAKEPKG_ARGS[@]}"
+  )
+
+  # Install separately so we can pass --overwrite='*' (makepkg -i can't).
+  # Dev builds frequently conflict with files left behind by previous
+  # script-installed Omarchy versions; the build is the authoritative state.
+  built_pkg=$(ls -t "$package_build_dir"/*.pkg.tar.* 2>/dev/null | grep -v '\.sig$' | head -1)
+  if [[ -z $built_pkg ]]; then
+    echo "Error: no built package found in $package_build_dir" >&2
+    exit 1
+  fi
+  sudo pacman -U --noconfirm --overwrite='*' "$built_pkg"
+done
@@ -0,0 +1,42 @@
+#!/bin/bash
+
+# omarchy:summary=Show the current Omarchy dev-link state
+# omarchy:group=dev
+
+set -euo pipefail
+
+default_target="/usr/share/omarchy"
+configured="$default_target"
+conf_present=0
+linked=0
+
+if [[ -f /etc/omarchy.conf ]]; then
+  conf_present=1
+  configured=$(
+    OMARCHY_PATH=
+    # shellcheck disable=SC1091
+    . /etc/omarchy.conf
+    printf '%s' "${OMARCHY_PATH:-<empty>}"
+  )
+  if [[ $configured != "$default_target" ]]; then
+    linked=1
+  fi
+fi
+
+if (( linked )); then
+  echo "dev-link: configured"
+  echo "  /etc/omarchy.conf -> OMARCHY_PATH=$configured"
+  echo "  status: reboot required before all session layers use this checkout"
+else
+  echo "dev-link: inactive"
+  if (( conf_present )); then
+    echo "  /etc/omarchy.conf -> OMARCHY_PATH=$configured (default guard)"
+  fi
+fi
+
+echo "  current shell:       OMARCHY_PATH=${OMARCHY_PATH:-<unset>}"
+
+if [[ ${OMARCHY_PATH:-$default_target} != "$configured" ]]; then
+  echo
+  echo "Note: the running session does not match /etc/omarchy.conf. Reboot to settle it."
+fi
@@ -0,0 +1,453 @@
+#!/bin/bash
+
+# omarchy:summary=Preview an Omarchy theme palette in the terminal
+# omarchy:args=[theme-name|theme-dir|colors.toml] [--no-color] [--no-osc|--osc]
+# omarchy:examples=omarchy dev theme-preview | omarchy dev theme-preview tokyo-night | omarchy dev theme-preview themes/gruvbox/colors.toml --no-color --no-osc
+
+set -o pipefail
+
+CURRENT_THEME_PATH="$HOME/.local/state/omarchy/current/theme"
+USER_THEMES_PATH="$HOME/.config/omarchy/themes"
+OMARCHY_THEMES_PATH="$OMARCHY_PATH/themes"
+
+COLOR_OUTPUT=1
+APPLY_OSC="auto"
+THEME_REF=""
+declare -A COLORS
+
+usage() {
+  cat <<'USAGE'
+Usage: omarchy-dev-theme-preview [theme-name|theme-dir|colors.toml] [--no-color] [--no-osc]
+
+Preview a theme palette in the terminal. Without an argument, previews the
+current theme from ~/.local/state/omarchy/current/theme/colors.toml.
+
+When stdout is a terminal and color output is enabled, the preview also applies
+that theme's OSC palette to the current terminal only. Use --no-osc to suppress
+that, or --osc to force it even when stdout is not detected as a terminal.
+USAGE
+}
+
+for arg in "$@"; do
+  case "$arg" in
+    --no-color | --plain)
+      COLOR_OUTPUT=0
+      APPLY_OSC="never"
+      ;;
+    --no-osc)
+      APPLY_OSC="never"
+      ;;
+    --osc | --apply-osc | --terminal)
+      APPLY_OSC="always"
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    *)
+      if [[ -n $THEME_REF ]]; then
+        usage >&2
+        exit 1
+      fi
+      THEME_REF="$arg"
+      ;;
+  esac
+done
+
+if [[ -n ${NO_COLOR:-} ]]; then
+  COLOR_OUTPUT=0
+fi
+
+normalize_theme_name() {
+  printf '%s' "$1" | sed -E 's/<[^>]+>//g' | tr '[:upper:]' '[:lower:]' | tr ' ' '-'
+}
+
+resolve_colors_file() {
+  local ref="$1"
+  local theme_name
+
+  if [[ -z $ref ]]; then
+    printf '%s/colors.toml' "$CURRENT_THEME_PATH"
+  elif [[ -f $ref ]]; then
+    printf '%s' "$ref"
+  elif [[ -d $ref && -f $ref/colors.toml ]]; then
+    printf '%s/colors.toml' "$ref"
+  else
+    theme_name=$(normalize_theme_name "$ref")
+    if [[ -f $USER_THEMES_PATH/$theme_name/colors.toml ]]; then
+      printf '%s/colors.toml' "$USER_THEMES_PATH/$theme_name"
+    elif [[ -f $OMARCHY_THEMES_PATH/$theme_name/colors.toml ]]; then
+      printf '%s/colors.toml' "$OMARCHY_THEMES_PATH/$theme_name"
+    else
+      return 1
+    fi
+  fi
+}
+
+clean_toml_value() {
+  local value="$1"
+
+  value="${value#*[\"\']}"
+  value="${value%%[\"\']*}"
+  printf '%s' "$value"
+}
+
+load_colors() {
+  local colors_file="$1"
+  local key value
+
+  while IFS='=' read -r key value; do
+    key="${key//[\"\' ]/}"
+    [[ $key && $key != \#* ]] || continue
+    value=$(clean_toml_value "$value")
+    COLORS[$key]="$value"
+  done <"$colors_file"
+
+  # Legacy semantic names win when present so older themes keep their intended
+  # primary text/background colors even if they also had dimmer fg/bg slots.
+  [[ ${COLORS[background]} ]] && COLORS[bg]="${COLORS[background]}"
+  [[ ${COLORS[foreground]} ]] && COLORS[fg]="${COLORS[foreground]}"
+  [[ ${COLORS[bg]} ]] || COLORS[bg]="${COLORS[color0]}"
+  [[ ${COLORS[fg]} ]] || COLORS[fg]="${COLORS[color7]}"
+  [[ ${COLORS[light_fg]} ]] || COLORS[light_fg]="${COLORS[color7]:-${COLORS[fg]}}"
+  [[ ${COLORS[bright_fg]} ]] || COLORS[bright_fg]="${COLORS[color15]:-${COLORS[fg]}}"
+  [[ ${COLORS[selection_background]} ]] || COLORS[selection_background]="${COLORS[selection]}"
+  [[ ${COLORS[selection_foreground]} ]] || COLORS[selection_foreground]="${COLORS[bright_fg]}"
+
+  if hex_valid "${COLORS[bg]}"; then
+    [[ ${COLORS[dark_bg]} ]] || COLORS[dark_bg]=$(mix_hex "${COLORS[bg]}" "#000000" 1 4)
+    [[ ${COLORS[darker_bg]} ]] || COLORS[darker_bg]=$(mix_hex "${COLORS[bg]}" "#000000" 1 2)
+  fi
+}
+
+hex_parts() {
+  local hex="${1#\#}"
+
+  printf '%d %d %d' "0x${hex:0:2}" "0x${hex:2:2}" "0x${hex:4:2}"
+}
+
+hex_valid() {
+  [[ $1 =~ ^#[0-9A-Fa-f]{6}$ ]]
+}
+
+luma_sum() {
+  local r g b
+
+  read -r r g b < <(hex_parts "$1")
+  printf '%d' $((r * 2126 + g * 7152 + b * 722))
+}
+
+contrast_ratio() {
+  local fg="$1"
+  local bg="$2"
+
+  awk -v fg="${fg#\#}" -v bg="${bg#\#}" '
+    function hex_value(char) { return index("0123456789abcdef", tolower(char)) - 1 }
+    function hex_pair(hex, idx) { return hex_value(substr(hex, idx, 1)) * 16 + hex_value(substr(hex, idx + 1, 1)) }
+    function channel(hex, idx) { return hex_pair(hex, idx) / 255 }
+    function linear(c) { return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ^ 2.4 }
+    function lum(hex) {
+      return 0.2126 * linear(channel(hex, 1)) + 0.7152 * linear(channel(hex, 3)) + 0.0722 * linear(channel(hex, 5))
+    }
+    BEGIN {
+      a = lum(fg)
+      b = lum(bg)
+      if (a < b) { tmp = a; a = b; b = tmp }
+      printf "%.2f", (a + 0.05) / (b + 0.05)
+    }
+  '
+}
+
+ansi_bg() {
+  local r g b
+
+  read -r r g b < <(hex_parts "$1")
+  printf '\033[48;2;%d;%d;%dm' "$r" "$g" "$b"
+}
+
+ansi_fg() {
+  local r g b
+
+  read -r r g b < <(hex_parts "$1")
+  printf '\033[38;2;%d;%d;%dm' "$r" "$g" "$b"
+}
+
+reset_ansi() {
+  printf '\033[0m'
+}
+
+apply_terminal_osc() {
+  case "$APPLY_OSC" in
+    never)
+      return
+      ;;
+    auto)
+      [[ -t 1 ]] && (( COLOR_OUTPUT )) || return
+      ;;
+    always)
+      ;;
+  esac
+
+  if [[ -x $OMARCHY_PATH/bin/omarchy-theme-osc ]]; then
+    "$OMARCHY_PATH/bin/omarchy-theme-osc" "$colors_file" || true
+  else
+    omarchy-theme-osc "$colors_file" || true
+  fi
+}
+
+swatch() {
+  local hex="$1"
+  local width="${2:-18}"
+  local i
+
+  if (( COLOR_OUTPUT )) && hex_valid "$hex"; then
+    ansi_bg "$hex"
+    for (( i = 0; i < width; i++ )); do
+      printf ' '
+    done
+    reset_ansi
+  else
+    for (( i = 0; i < width; i++ )); do
+      printf '#'
+    done
+  fi
+}
+
+print_color_row() {
+  local key="$1"
+  local hex="${COLORS[$key]}"
+
+  [[ -n $hex ]] || return
+  printf '  %-22s %-9s ' "$key" "$hex"
+  swatch "$hex" 20
+  printf '\n'
+}
+
+paint_segment() {
+  local text="$1"
+  local fg="$2"
+  local bg="${3:-${COLORS[bg]}}"
+
+  if (( COLOR_OUTPUT )) && hex_valid "$fg" && hex_valid "$bg"; then
+    ansi_bg "$bg"
+    ansi_fg "$fg"
+    printf '%s' "$text"
+    reset_ansi
+  else
+    printf '%s' "$text"
+  fi
+}
+
+print_group() {
+  local title="$1"
+  shift
+  local key
+
+  printf '\n%s\n' "$title"
+  for key in "$@"; do
+    print_color_row "$key"
+  done
+}
+
+print_selection_sample() {
+  local bg="${COLORS[bg]}"
+  local fg="${COLORS[fg]}"
+  local selection_bg="${COLORS[selection_background]}"
+  local selection_fg="${COLORS[selection_foreground]}"
+
+  [[ -n $bg && -n $fg && -n $selection_bg && -n $selection_fg ]] || return
+
+  printf '\nSelection sample\n  '
+  if (( COLOR_OUTPUT )) && hex_valid "$bg" && hex_valid "$fg" && hex_valid "$selection_bg" && hex_valid "$selection_fg"; then
+    ansi_bg "$bg"
+    ansi_fg "$fg"
+    printf ' This is some '
+    ansi_bg "$selection_bg"
+    ansi_fg "$selection_fg"
+    printf 'selected text'
+    ansi_bg "$bg"
+    ansi_fg "$fg"
+    printf ' in a sentence '
+    reset_ansi
+    printf '\n'
+  else
+    printf 'This is some [selected text] in a sentence\n'
+  fi
+}
+
+print_practical_samples() {
+  printf '\nTerminal/UI samples\n'
+  printf '  '
+  paint_segment ' normal text ' "${COLORS[fg]}"
+  paint_segment ' muted/comment ' "${COLORS[muted]}"
+  paint_segment ' accent/link ' "${COLORS[accent]}"
+  paint_segment ' error ' "${COLORS[red]}"
+  paint_segment ' warning ' "${COLORS[yellow]}"
+  paint_segment ' success ' "${COLORS[green]}"
+  printf '\n  '
+  paint_segment ' $ omarchy theme-preview ' "${COLORS[green]}"
+  paint_segment ' # comment ' "${COLORS[muted]}"
+  paint_segment ' "string" ' "${COLORS[green]}"
+  paint_segment ' function() ' "${COLORS[blue]}"
+  paint_segment ' --flag ' "${COLORS[magenta]}"
+  printf '\n  '
+  paint_segment ' unselected menu row ' "${COLORS[fg]}"
+  printf '\n  '
+  paint_segment ' selected menu row ' "${COLORS[selection_foreground]}" "${COLORS[selection_background]}"
+  printf '\n  '
+  paint_segment ' status/inverse ' "${COLORS[bg]}" "${COLORS[fg]}"
+  paint_segment ' inactive surface ' "${COLORS[fg]}" "${COLORS[lighter_bg]}"
+  paint_segment ' urgent ' "${COLORS[bg]}" "${COLORS[red]}"
+  printf '\n'
+}
+
+print_palette_strip() {
+  local title="$1"
+  shift
+  local key hex
+
+  printf '  %-12s ' "$title"
+  for key in "$@"; do
+    hex="${COLORS[$key]}"
+    if [[ -n $hex ]]; then
+      swatch "$hex" 4
+      printf ' '
+    fi
+  done
+  printf '\n'
+}
+
+print_ansi_palette() {
+  printf '\nANSI palette strips\n'
+  print_palette_strip normal bg red green yellow blue magenta cyan fg
+  print_palette_strip bright muted bright_red bright_green bright_yellow bright_blue bright_magenta bright_cyan bright_fg
+}
+
+mix_hex() {
+  local start="$1"
+  local end="$2"
+  local index="$3"
+  local max_index="$4"
+  local sr sg sb er eg eb r g b
+
+  read -r sr sg sb < <(hex_parts "$start")
+  read -r er eg eb < <(hex_parts "$end")
+
+  if (( max_index == 0 )); then
+    printf '%s' "$start"
+    return
+  fi
+
+  r=$(((sr * (max_index - index) + er * index + max_index / 2) / max_index))
+  g=$(((sg * (max_index - index) + eg * index + max_index / 2) / max_index))
+  b=$(((sb * (max_index - index) + eb * index + max_index / 2) / max_index))
+  printf '#%02x%02x%02x' "$r" "$g" "$b"
+}
+
+print_gradient() {
+  local start_key="$1"
+  local end_key="$2"
+  local start="${COLORS[$start_key]}"
+  local end="${COLORS[$end_key]}"
+  local steps=24
+  local i hex
+
+  [[ -n $start && -n $end ]] || return
+  hex_valid "$start" && hex_valid "$end" || return
+
+  printf '\n%s -> %s gradient\n' "$start_key" "$end_key"
+  printf '  %s ' "$start"
+  for (( i = 0; i < steps; i++ )); do
+    hex=$(mix_hex "$start" "$end" "$i" "$((steps - 1))")
+    if (( COLOR_OUTPUT )); then
+      ansi_bg "$hex"
+      printf '  '
+      reset_ansi
+    else
+      printf '%s ' "$hex"
+    fi
+  done
+  printf ' %s\n' "$end"
+}
+
+print_neutral_ramp() {
+  local mode="$1"
+  local direction sort_flag key hex score entry
+  local -a keys entries sorted
+
+  keys=(darker_bg dark_bg bg lighter_bg selection muted dark_fg fg light_fg bright_fg)
+  if [[ $mode == "light" ]]; then
+    direction="lightest -> darkest"
+    sort_flag="-rn"
+  else
+    direction="darkest -> lightest"
+    sort_flag="-n"
+  fi
+
+  for key in "${keys[@]}"; do
+    hex="${COLORS[$key]}"
+    [[ -n $hex ]] || continue
+    hex_valid "$hex" || continue
+    score=$(luma_sum "$hex")
+    entries+=("$score $key")
+  done
+
+  (( ${#entries[@]} > 0 )) || return
+
+  mapfile -t sorted < <(printf '%s\n' "${entries[@]}" | sort "$sort_flag")
+
+  printf '\nNeutral ramp (%s)\n' "$direction"
+  for entry in "${sorted[@]}"; do
+    key="${entry#* }"
+    print_color_row "$key"
+  done
+}
+
+colors_file=$(resolve_colors_file "$THEME_REF") || {
+  echo "Theme not found: $THEME_REF" >&2
+  exit 1
+}
+
+if [[ ! -f $colors_file ]]; then
+  echo "Missing colors.toml: $colors_file" >&2
+  exit 1
+fi
+
+load_colors "$colors_file"
+
+mode="${COLORS[mode]}"
+if [[ -z $mode && ${COLORS[bg]} =~ ^#[0-9A-Fa-f]{6}$ ]]; then
+  if (( $(luma_sum "${COLORS[bg]}") > 1275000 )); then
+    mode="light"
+  else
+    mode="dark"
+  fi
+fi
+[[ -n $mode ]] || mode="dark"
+
+theme_label="$THEME_REF"
+if [[ -z $theme_label ]]; then
+  if [[ -f $HOME/.local/state/omarchy/current/theme.name ]]; then
+    theme_label=$(<"$HOME/.local/state/omarchy/current/theme.name")
+  else
+    theme_label="current"
+  fi
+fi
+
+apply_terminal_osc
+
+printf 'Theme: %s\n' "$theme_label"
+printf 'File:  %s\n' "$colors_file"
+printf 'Mode:  %s\n' "$mode"
+if [[ ${COLORS[fg]} =~ ^#[0-9A-Fa-f]{6}$ && ${COLORS[bg]} =~ ^#[0-9A-Fa-f]{6}$ ]]; then
+  printf 'fg/bg contrast: %s:1\n' "$(contrast_ratio "${COLORS[fg]}" "${COLORS[bg]}")"
+fi
+
+print_gradient bg bright_fg
+print_neutral_ramp "$mode"
+print_group "Foundation" bg fg accent selection
+print_selection_sample
+print_practical_samples
+print_ansi_palette
+print_group "Normal colors" red yellow orange green cyan blue magenta brown
+print_group "Bright colors" bright_red bright_yellow bright_green bright_cyan bright_blue bright_magenta bright_fg
@@ -0,0 +1,30 @@
+#!/bin/bash
+
+# omarchy:summary=Restore Omarchy to the package install after reboot
+# omarchy:group=dev
+
+set -euo pipefail
+
+if (( EUID == 0 )); then
+  echo "Error: run omarchy-dev-unlink as your user, not under sudo." >&2
+  exit 1
+fi
+
+if [[ ${1:-} == "-h" || ${1:-} == "--help" ]]; then
+  cat <<USAGE
+Usage: omarchy dev unlink
+
+Writes /etc/omarchy.conf so OMARCHY_PATH resolves to /usr/share/omarchy
+after reboot. This intentionally does not rewrite the running Hyprland,
+systemd, shell, or app-launcher environment; reboot to make every layer agree.
+USAGE
+  exit 0
+fi
+
+default_target="/usr/share/omarchy"
+
+printf 'export OMARCHY_PATH="%s"\n' "$default_target" | sudo tee /etc/omarchy.conf >/dev/null
+
+echo "Set /etc/omarchy.conf -> OMARCHY_PATH=$default_target"
+echo
+echo "Reboot to restore the package install in Hyprland, app launchers, and new shells."
@@ -0,0 +1,117 @@
+#!/bin/bash
+
+# omarchy:summary=Finalize Omarchy user setup (runtime tweaks /etc/skel can't do)
+# omarchy:group=finalize
+# omarchy:examples=omarchy finalize user | omarchy finalize user --force
+
+set -euo pipefail
+
+usage() {
+  cat <<USAGE
+Usage: omarchy finalize user [--force] [--first-install]
+
+Runs the per-user setup steps that /etc/skel can't seed:
+dev-aware skill symlinks, xdg-user-dirs + gtk bookmarks (need \$HOME),
+default browser/mailto, and install/user/all.sh.
+
+For shipped configs see /etc/skel (new users) and omarchy-reinstall-configs
+(existing users explicitly resyncing).
+
+--first-install is used by the ISO in the target chroot. It marks shipped
+migrations complete for the freshly-created user.
+
+Idempotency marker: ~/.local/state/omarchy/finalize-user.done
+USAGE
+}
+
+if (( EUID == 0 )); then
+  echo "Error: run omarchy-finalize-user as the user being configured, not as root." >&2
+  exit 1
+fi
+
+force=0
+first_install=0
+while (($#)); do
+  case "$1" in
+    --force)
+      force=1
+      shift
+      ;;
+    --first-install)
+      first_install=1
+      force=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+state_dir="$HOME/.local/state/omarchy"
+marker="$state_dir/finalize-user.done"
+mkdir -p "$state_dir"
+
+if [[ -f $marker && $force -eq 0 ]]; then
+  echo "User finalization already complete (rerun with --force to refresh)."
+  exit 0
+fi
+
+export OMARCHY_PATH="${OMARCHY_PATH:-/usr/share/omarchy}"
+export OMARCHY_INSTALL="${OMARCHY_INSTALL:-$OMARCHY_PATH/install}"
+export OMARCHY_SETUP_CONTEXT="${OMARCHY_SETUP_CONTEXT:-runtime}"
+export PATH="$OMARCHY_PATH/bin:$PATH"
+
+if (( first_install )); then
+  export OMARCHY_SETUP_CONTEXT=iso-chroot
+fi
+
+if [[ -n ${OMARCHY_INSTALL_LOG_FILE:-} && -f $OMARCHY_INSTALL/helpers/logging.sh ]]; then
+  source "$OMARCHY_INSTALL/helpers/logging.sh"
+else
+  run_logged() {
+    local script="$1"
+    bash -eE -c 'source "$1"' bash "$script"
+  }
+fi
+
+# Dev-aware skill symlinks. Cannot live in /etc/skel because OMARCHY_PATH may
+# point at a dev checkout (omarchy dev link) where the target differs.
+mkdir -p ~/.agents/skills ~/.claude/skills ~/.codex/skills ~/.pi/agent/skills
+ln -sfn "$OMARCHY_PATH/default/omarchy-skill" ~/.agents/skills/omarchy
+ln -sfn "$OMARCHY_PATH/default/omarchy-skill" ~/.claude/skills/omarchy
+ln -sfn "$OMARCHY_PATH/default/omarchy-skill" ~/.codex/skills/omarchy
+ln -sfn "$OMARCHY_PATH/default/omarchy-skill" ~/.pi/agent/skills/omarchy
+
+mkdir -p ~/Downloads ~/Pictures ~/Videos ~/.config/gtk-3.0
+xdg-user-dirs-update --set TEMPLATES "$HOME"
+xdg-user-dirs-update --set PUBLICSHARE "$HOME"
+xdg-user-dirs-update --set DESKTOP "$HOME"
+rmdir ~/Templates ~/Public ~/Desktop 2>/dev/null || true
+touch ~/.config/gtk-3.0/bookmarks
+for dir in Downloads Projects Pictures Videos; do
+  bookmark="file://$HOME/$dir $dir"
+  grep -qxF "$bookmark" ~/.config/gtk-3.0/bookmarks || echo "$bookmark" >>~/.config/gtk-3.0/bookmarks
+done
+
+source "$OMARCHY_INSTALL/user/all.sh"
+
+omarchy-refresh-applications
+xdg-settings set default-web-browser chromium.desktop
+xdg-mime default HEY.desktop x-scheme-handler/mailto
+
+if (( first_install )); then
+  mkdir -p "$state_dir/migrations"
+  for migration in "$OMARCHY_PATH"/migrations/*.sh; do
+    [[ -f $migration ]] && touch "$state_dir/migrations/$(basename "$migration")"
+  done
+fi
+
+touch "$marker"
+echo "User finalization complete."
@@ -1,25 +1,135 @@
 #!/bin/bash

-# omarchy:summary=Finish the installation of Omarchy with items that can only be done after logging in.
-# omarchy:requires-sudo=true
+# omarchy:summary=Finish first-login setup for Omarchy.
+# omarchy:args=[--force]

 set -e

-FIRST_RUN_MODE=~/.local/state/omarchy/first-run.mode
+usage() {
+  cat <<USAGE
+Usage: omarchy-first-run [--force]

-if [[ -f $FIRST_RUN_MODE ]]; then
-  rm -f "$FIRST_RUN_MODE"
+Run first-login user setup and notification hooks. By default this only runs
+once per user. Use --force to rerun the full sequence and refresh user setup.
+USAGE
+}

-  bash "$OMARCHY_PATH/install/first-run/recover-internal-monitor.sh"
-  bash "$OMARCHY_PATH/install/first-run/cleanup-reboot-sudoers.sh"
-  bash "$OMARCHY_PATH/install/first-run/firewall.sh"
-  bash "$OMARCHY_PATH/install/first-run/dns-resolver.sh"
-  bash "$OMARCHY_PATH/install/first-run/gnome-theme.sh"
-  bash "$OMARCHY_PATH/install/first-run/gdk-scale.sh"
-  bash "$OMARCHY_PATH/install/first-run/gtk-primary-paste.sh"
-  omarchy-hook-install post-update "$OMARCHY_PATH/install/first-run/install-voxtype.hook"
-  sudo /bin/rm -f /etc/sudoers.d/first-run
+force=0
+finalize_user_args=()
+while (($#)); do
+  case "$1" in
+    --force)
+      force=1
+      finalize_user_args+=(--force)
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done

-  bash "$OMARCHY_PATH/install/first-run/welcome.sh"
-  bash "$OMARCHY_PATH/install/first-run/wifi.sh"
+omarchy-finalize-user "${finalize_user_args[@]}" || true
+
+state_dir=~/.local/state/omarchy
+mkdir -p "$state_dir"
+
+FIRST_RUN_LOG="$state_dir/first-run.log"
+first_run_failed=0
+
+log_first_run() {
+  printf '[%s] %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$*" >>"$FIRST_RUN_LOG"
+}
+
+notification_server_ready() {
+  if command -v gdbus >/dev/null 2>&1; then
+    gdbus call --session \
+      --dest org.freedesktop.Notifications \
+      --object-path /org/freedesktop/Notifications \
+      --method org.freedesktop.Notifications.GetServerInformation >/dev/null 2>&1
+  elif command -v busctl >/dev/null 2>&1; then
+    busctl --user call \
+      org.freedesktop.Notifications \
+      /org/freedesktop/Notifications \
+      org.freedesktop.Notifications \
+      GetServerInformation >/dev/null 2>&1
+  else
+    return 0
+  fi
+}
+
+wait_for_notifications() {
+  command -v omarchy-shell >/dev/null || return 0
+
+  for _ in {1..100}; do
+    if omarchy-shell notifications ping >/dev/null 2>&1 && notification_server_ready; then
+      return 0
+    fi
+    sleep 0.1
+  done
+
+  log_first_run "Timed out waiting for notification service; continuing"
+  return 0
+}
+
+run_first_run_step() {
+  local name="$1"
+  shift
+
+  log_first_run "Starting: $name"
+  if "$@"; then
+    log_first_run "Completed: $name"
+  else
+    local status=$?
+    first_run_failed=1
+    log_first_run "Failed: $name (exit code: $status)"
+  fi
+}
+
+wait_for_notifications
+
+MIGRATION_NOTIFY_WATCH_MARKER="$state_dir/user-migration-notify-watch-enabled"
+if [[ ! -f $MIGRATION_NOTIFY_WATCH_MARKER || $force -eq 1 ]]; then
+  if systemctl --user enable --now omarchy-update-user-notify.path >/dev/null 2>&1; then
+    touch "$MIGRATION_NOTIFY_WATCH_MARKER"
+  fi
+fi
+
+run_first_run_step "notify about pending migrations" omarchy-migrate-notify
+
+USER_MARKER="$state_dir/first-run-user.done"
+if [[ ! -f $USER_MARKER || $force -eq 1 ]]; then
+  run_first_run_step "install Voxtype post-update hook" \
+    omarchy-hook-install post-update "$OMARCHY_PATH/install/user/first-run/install-voxtype.hook"
+
+  run_first_run_step "enable user systemd units" \
+    bash "$OMARCHY_PATH/install/user/first-run/enable-user-units.sh"
+  run_first_run_step "set GNOME theme" \
+    bash "$OMARCHY_PATH/install/user/first-run/gnome-theme.sh"
+  run_first_run_step "set GTK primary paste" \
+    bash "$OMARCHY_PATH/install/user/first-run/gtk-primary-paste.sh"
+
+  wait_for_notifications
+  run_first_run_step "show welcome notification" \
+    bash "$OMARCHY_PATH/install/user/first-run/welcome.sh"
+  # The first-run notification scripts register action callbacks in background
+  # notify-send processes. Give the notification server a tick to ingest the
+  # welcome toast before queueing the Wi-Fi/update toasts.
+  sleep 0.3
+  run_first_run_step "show Wi-Fi/update notifications" \
+    bash "$OMARCHY_PATH/install/user/first-run/wifi.sh"
+
+  if (( first_run_failed == 0 )); then
+    touch "$USER_MARKER"
+  else
+    log_first_run "One or more first-run steps failed; first-run will retry next login"
+  fi
+else
+  echo "First-run already complete (rerun with --force to refresh)."
 fi
@@ -4,50 +4,87 @@
 # omarchy:args=<font-name>
 # omarchy:examples=omarchy font list | omarchy font set "CaskaydiaMono Nerd Font"

-font_name="$1"
+usage() {
+  echo "Usage: omarchy-font-set <font-name>"
+}

-if [[ -n $font_name ]]; then
-  if fc-list | grep -iq "$font_name"; then
-    if [[ -f ~/.config/alacritty/alacritty.toml ]]; then
-      sed -i "s/family = \".*\"/family = \"$font_name\"/g" ~/.config/alacritty/alacritty.toml
-    fi
+font_name="${1:-}"
+omarchy_root="${OMARCHY_PATH:-/usr/share/omarchy}"

-    if [[ -f ~/.config/kitty/kitty.conf ]]; then
-      sed -i "s/^font_family .*/font_family $font_name/g" ~/.config/kitty/kitty.conf
-      pkill -USR1 kitty
-    fi
+case "$font_name" in
+  -h|--help)
+    usage
+    exit 0
+    ;;
+  "")
+    usage >&2
+    exit 1
+    ;;
+esac

-    if [[ -f ~/.config/ghostty/config ]]; then
-      sed -i "s/font-family = \".*\"/font-family = \"$font_name\"/g" ~/.config/ghostty/config
-      pkill -SIGUSR2 ghostty
-    fi
+if ! fc-list | grep -Fqi -- "$font_name"; then
+  echo "Font '$font_name' not found."
+  exit 1
+fi

-    if [[ -f ~/.config/foot/foot.ini ]]; then
-      sed -i "s/^font=.*/font=$font_name:size=9/g" ~/.config/foot/foot.ini
-    fi
+if [[ -f ~/.config/alacritty/alacritty.toml ]]; then
+  sed -i "s/family = \".*\"/family = \"$font_name\"/g" ~/.config/alacritty/alacritty.toml
+fi

-    # fontconfig is the canonical source of truth — the omarchy shell, Qt
-    # apps, and anything else that resolves "monospace" all read from here.
-    xmlstarlet ed -L \
-      -u '//match[@target="pattern"][test/string="monospace"]/edit[@name="family"]/string' \
-      -v "$font_name" \
-      ~/.config/fontconfig/fonts.conf
+if [[ -f ~/.config/kitty/kitty.conf ]]; then
+  sed -i "s/^font_family .*/font_family $font_name/g" ~/.config/kitty/kitty.conf
+  pkill -USR1 kitty
+fi

-    omarchy-restart-shell
+if [[ -f ~/.config/ghostty/config ]]; then
+  sed -i "s/font-family = \".*\"/font-family = \"$font_name\"/g" ~/.config/ghostty/config
+  pkill -SIGUSR2 ghostty
+fi

-    if pgrep -x ghostty; then
-      omarchy-notification-send -g  "You must restart Ghostty to see font change"
-    fi
+if [[ -f ~/.config/foot/foot.ini ]]; then
+  sed -i "s/^font=.*/font=$font_name:size=9/g" ~/.config/foot/foot.ini
+fi

-    if pgrep -x foot; then
-      omarchy-notification-send -g  "You must restart Foot to see font change"
-    fi
-
-    omarchy-hook font-set "$font_name"
-  else
-    echo "Font '$font_name' not found."
+# fontconfig is the canonical source of truth — the omarchy shell, Qt apps,
+# and anything resolving "monospace" all read from here. The shipped default
+# is package-owned; create a user override only when the user changes fonts.
+fontconfig_file="$HOME/.config/fontconfig/fonts.conf"
+if [[ ! -f $fontconfig_file ]]; then
+  fontconfig_default="$omarchy_root/default/fontconfig/conf.avail/50-omarchy.conf"
+  if [[ ! -f $fontconfig_default ]]; then
+    echo "Default fontconfig file not found: $fontconfig_default" >&2
    exit 1
  fi
-else
-  echo "Usage: omarchy-font-set <font-name>"
+  mkdir -p "$(dirname "$fontconfig_file")"
+  cp "$fontconfig_default" "$fontconfig_file"
 fi
+
+# We own the markup in 50-omarchy.conf, so the monospace block is predictable:
+# the <string>FAMILY</string> immediately after <string>monospace</string> is
+# the family we're replacing.
+tmp=$(mktemp)
+if ! awk -v new_font="$font_name" '
+  in_mono && /<string>[^<]*<\/string>/ {
+    sub(/<string>[^<]*<\/string>/, "<string>" new_font "</string>")
+    in_mono = 0
+  }
+  /<string>monospace<\/string>/ { in_mono = 1 }
+  { print }
+' "$fontconfig_file" >"$tmp"; then
+  rm -f "$tmp"
+  echo "Failed to update $fontconfig_file" >&2
+  exit 1
+fi
+mv "$tmp" "$fontconfig_file"
+
+omarchy-restart-shell
+
+if pgrep -x ghostty; then
+  omarchy-notification-send -g  "You must restart Ghostty to see font change"
+fi
+
+if pgrep -x foot; then
+  omarchy-notification-send -g  "You must restart Foot to see font change"
+fi
+
+omarchy-hook font-set "$font_name"
@@ -51,11 +51,7 @@ desktop_name="$game_name"
 desktop_id=$(printf '%s' "$desktop_name" | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]' '-' | sed 's/^-//; s/-$//')
 desktop_dir="$HOME/.local/share/applications"
 desktop_file="$desktop_dir/$desktop_id.desktop"
-icon_dir="$desktop_dir/icons"
-icon_path="$icon_dir/Retro Gaming.png"
-
-mkdir -p "$desktop_dir" "$icon_dir"
-[[ -f $icon_path ]] || cp "$HOME/.local/share/omarchy/applications/icons/Retro Gaming.png" "$icon_path"
+mkdir -p "$desktop_dir"

 cat >"$desktop_file" <<EOF
 [Desktop Entry]
@@ -65,7 +61,7 @@ Comment=Play $game_name with RetroArch
 Exec=retroarch -L "$core_path" "$game_path"
 Terminal=false
 Type=Application
-Icon=$icon_path
+Icon=retro-gaming
 StartupNotify=true
 Categories=Game;Emulator;
 EOF
@@ -38,8 +38,9 @@ if [[ -f $MKINITCPIO_CONF ]] && grep -q "^HOOKS+=(resume)$" "$MKINITCPIO_CONF";
    if [[ -n $RESUME_OFFSET ]]; then
      echo "Fixing empty resume_offset ($RESUME_OFFSET)"
      sudo sed -i "s/resume_offset=\"$/resume_offset=$RESUME_OFFSET\"/" "$RESUME_DROP_IN"
-      sudo sed -i "s/resume_offset=\"$/resume_offset=$RESUME_OFFSET\"/" /etc/default/limine
-      $NO_REBUILD || sudo limine-mkinitcpio
+      if ! $NO_REBUILD; then
+        sudo limine-mkinitcpio
+      fi
    fi
  fi
  echo "Hibernation is already set up"
@@ -100,7 +101,6 @@ if [[ ! -f $RESUME_DROP_IN ]]; then
  if [[ -n $RESUME_OFFSET ]]; then
    sudo mkdir -p /etc/limine-entry-tool.d
    echo "KERNEL_CMDLINE[default]+=\" resume=$RESUME_DEVICE resume_offset=$RESUME_OFFSET\"" | sudo tee "$RESUME_DROP_IN" >/dev/null
-    sudo tee -a /etc/default/limine < "$RESUME_DROP_IN" >/dev/null
  else
    echo "Warning: Could not determine resume offset for $SWAP_FILE" >&2
  fi
@@ -113,7 +113,6 @@ if grep -q "\[s2idle\]" /sys/power/mem_sleep 2>/dev/null; then
    echo "Enabling ACPI RTC alarm for s2idle suspend"
    sudo mkdir -p /etc/limine-entry-tool.d
    echo 'KERNEL_CMDLINE[default]+=" rtc_cmos.use_acpi_alarm=1"' | sudo tee "$LIMINE_DROP_IN" >/dev/null
-    sudo tee -a /etc/default/limine < "$LIMINE_DROP_IN" >/dev/null
  fi
 fi

@@ -0,0 +1,110 @@
+#!/bin/bash
+
+# omarchy:summary=Pause or resume Hyprland config auto-reload around package transactions.
+# omarchy:hidden=true
+
+set -euo pipefail
+
+command="${1:-}"
+case "$command" in
+  pause | resume) ;;
+  *)
+    echo "Usage: omarchy-hyprland-reload-guard pause|resume" >&2
+    exit 1
+    ;;
+esac
+
+run_root="${OMARCHY_HYPRLAND_RELOAD_GUARD_RUN_ROOT:-/run/user}"
+state_dir="${OMARCHY_HYPRLAND_RELOAD_GUARD_STATE_DIR:-/run/omarchy/hyprland-reload-guard}"
+hyprctl_bin="${HYPRCTL:-/usr/bin/hyprctl}"
+
+hyprctl_instance() {
+  local runtime_dir="$1"
+  local signature="$2"
+  shift 2
+
+  XDG_RUNTIME_DIR="$runtime_dir" "$hyprctl_bin" --instance "$signature" "$@"
+}
+
+option_bool() {
+  local runtime_dir="$1"
+  local signature="$2"
+  local option="$3"
+
+  hyprctl_instance "$runtime_dir" "$signature" -j getoption "$option" 2>/dev/null | jq -r '.bool'
+}
+
+instances() {
+  local instance_dir signature hypr_dir runtime_dir uid
+
+  [[ -d $run_root ]] || return 0
+
+  for instance_dir in "$run_root"/*/hypr/*; do
+    [[ -d $instance_dir ]] || continue
+
+    signature="${instance_dir##*/}"
+    hypr_dir="${instance_dir%/*}"
+    runtime_dir="${hypr_dir%/*}"
+    uid="${runtime_dir##*/}"
+
+    [[ $uid =~ ^[0-9]+$ ]] || continue
+
+    printf '%s\t%s\n' "$runtime_dir" "$signature"
+  done
+}
+
+pause_instance() {
+  local runtime_dir="$1"
+  local signature="$2"
+  local disable_autoreload suppress_errors state_file="$state_dir/$signature"
+
+  mkdir -p "$state_dir"
+
+  if [[ ! -f $state_file ]]; then
+    disable_autoreload=$(option_bool "$runtime_dir" "$signature" misc.disable_autoreload) || return 0
+    suppress_errors=$(option_bool "$runtime_dir" "$signature" debug.suppress_errors) || return 0
+    printf '%s\t%s\t%s\n' "$runtime_dir" "$disable_autoreload" "$suppress_errors" >"$state_file"
+  fi
+
+  hyprctl_instance "$runtime_dir" "$signature" eval \
+    'hl.config({ misc = { disable_autoreload = true }, debug = { suppress_errors = true } })' \
+    >/dev/null 2>&1 || true
+}
+
+resume_instance() {
+  local state_file="$1"
+  local signature="${state_file##*/}"
+  local runtime_dir disable_autoreload suppress_errors
+
+  IFS=$'\t' read -r runtime_dir disable_autoreload suppress_errors <"$state_file" || return 0
+
+  if [[ -d $runtime_dir ]]; then
+    hyprctl_instance "$runtime_dir" "$signature" eval \
+      "hl.config({ debug = { suppress_errors = $suppress_errors } })" \
+      >/dev/null 2>&1 || true
+
+    hyprctl_instance "$runtime_dir" "$signature" reload >/dev/null 2>&1 || true
+
+    hyprctl_instance "$runtime_dir" "$signature" eval \
+      "hl.config({ misc = { disable_autoreload = $disable_autoreload }, debug = { suppress_errors = $suppress_errors } })" \
+      >/dev/null 2>&1 || true
+  fi
+
+  rm -f "$state_file"
+}
+
+case "$command" in
+  pause)
+    while IFS=$'\t' read -r runtime_dir signature; do
+      pause_instance "$runtime_dir" "$signature"
+    done < <(instances)
+    ;;
+  resume)
+    [[ -d $state_dir ]] || exit 0
+    for state_file in "$state_dir"/*; do
+      [[ -f $state_file ]] || continue
+      resume_instance "$state_file"
+    done
+    rmdir "$state_dir" 2>/dev/null || true
+    ;;
+esac
@@ -67,7 +67,7 @@ brave-origin)
  setup_policy_directory /etc/brave/policies/managed
  mkdir -p ~/.config
  # FIXME: Use normal chromium flags when Brave Origin wrapper has been fixed
-  echo "--load-extension=~/.local/share/omarchy/default/chromium/extensions/copy-url,~/.local/share/omarchy/default/chromium/extensions/yt-dlp" > ~/.config/brave-origin-beta-flags.conf
+  echo "--load-extension=/usr/share/omarchy/default/chromium/extensions/copy-url,/usr/share/omarchy/default/chromium/extensions/yt-dlp" > ~/.config/brave-origin-beta-flags.conf
  omarchy-install-chromium-ytdlp
  omarchy-theme-set-browser
  announce_browser_installed "Brave Origin"
@@ -8,7 +8,7 @@ omarchy-pkg-add helix
 mkdir -p ~/.config/helix/themes

 # Symlink the rendered Omarchy theme so Helix tracks the active theme
-ln -sf ~/.config/omarchy/current/theme/helix.toml ~/.config/helix/themes/omarchy.toml
+ln -sf "$HOME/.local/state/omarchy/current/theme/helix.toml" ~/.config/helix/themes/omarchy.toml

 # Only seed a config.toml if the user does not already have one
 if [[ ! -f ~/.config/helix/config.toml ]]; then
@@ -18,7 +18,7 @@ EOF
 fi

 # Ensure the symlink target exists for users whose current theme predates this template
-if [[ ! -e ~/.config/omarchy/current/theme/helix.toml ]]; then
+if [[ ! -e $HOME/.local/state/omarchy/current/theme/helix.toml ]]; then
  omarchy-theme-refresh
 fi

@@ -63,12 +63,9 @@ EOF
  launched_installer=1
 fi

-mkdir -p "$HOME/.local/share/applications" "$HOME/.local/share/icons/hicolor/48x48/apps"
-install -m 644 "$HOME/.local/share/omarchy/applications/battlenet.desktop" \
+mkdir -p "$HOME/.local/share/applications"
+install -m 644 "$OMARCHY_PATH/applications/battlenet.desktop" \
  "$HOME/.local/share/applications/battlenet.desktop"
-install -m 644 "$HOME/.local/share/omarchy/applications/icons/Battle.net.png" \
-  "$HOME/.local/share/icons/hicolor/48x48/apps/Battle.net.png"
-gtk-update-icon-cache "$HOME/.local/share/icons/hicolor" &>/dev/null || true
 update-desktop-database "$HOME/.local/share/applications" 2>/dev/null || true

 if (( launched_installer )); then
@@ -13,8 +13,6 @@ SUNSHINE_ADMIN_APP="Sunshine Admin"
 SUNSHINE_ADMIN_URL="https://localhost:47990"
 SUNSHINE_ADMIN_EXEC="omarchy-launch-webapp $SUNSHINE_ADMIN_URL --ignore-certificate-errors"
 SUNSHINE_ICON_SOURCE="/usr/share/sunshine/web/images/logo-sunshine-45.png"
-SUNSHINE_ICON_NAME="Sunshine Admin.png"
-WEBAPP_ICON_DIR="$HOME/.local/share/applications/icons"
 HYPR_AUTOSTART_FILE="$HOME/.config/hypr/autostart.lua"
 HYPR_AUTOSTART_ENTRY='o.launch_on_start("sunshine")'

@@ -59,9 +57,7 @@ open_ufw_ports() {
 }

 install_admin_webapp() {
-  mkdir -p "$WEBAPP_ICON_DIR"
-  cp "$SUNSHINE_ICON_SOURCE" "$WEBAPP_ICON_DIR/$SUNSHINE_ICON_NAME"
-  omarchy-webapp-install "$SUNSHINE_ADMIN_APP" "$SUNSHINE_ADMIN_URL" "$SUNSHINE_ICON_NAME" "$SUNSHINE_ADMIN_EXEC"
+  omarchy-webapp-install "$SUNSHINE_ADMIN_APP" "$SUNSHINE_ADMIN_URL" "$SUNSHINE_ICON_SOURCE" "$SUNSHINE_ADMIN_EXEC"
 }

 enable_hyprland_autostart() {
@@ -32,10 +32,10 @@ for m in $(hyprctl monitors -j | jq -r '.[] | .name'); do

  case $terminal in
  *Alacritty*)
-    hypr_exec "alacritty --class=org.omarchy.screensaver --config-file ~/.local/share/omarchy/default/alacritty/screensaver.toml -e omarchy-screensaver"
+    hypr_exec "alacritty --class=org.omarchy.screensaver --config-file $OMARCHY_PATH/default/alacritty/screensaver.toml -e omarchy-screensaver"
    ;;
  *ghostty*)
-    hypr_exec "ghostty --class=org.omarchy.screensaver --config-file=~/.local/share/omarchy/default/ghostty/screensaver --font-size=18 -e omarchy-screensaver"
+    hypr_exec "ghostty --class=org.omarchy.screensaver --config-file=$OMARCHY_PATH/default/ghostty/screensaver --font-size=18 -e omarchy-screensaver"
    ;;
  *foot*)
    hypr_exec "foot --app-id=org.omarchy.screensaver --config=\"$OMARCHY_PATH/default/foot/screensaver.ini\" -e omarchy-screensaver"
@@ -1,28 +1,97 @@
 #!/bin/bash

-# omarchy:summary=Run all pending migrations to bring the system in line with the installed version.
+# omarchy:summary=Run pending Omarchy migrations.
+# omarchy:args=[--pending]

-STATE_DIR="$HOME/.local/state/omarchy/migrations"
-mkdir -p "$STATE_DIR"
+set -euo pipefail

-# Skipped migrations are tracked separately
-mkdir -p "$STATE_DIR/skipped"
+mode="run"

-# Run any pending migrations
-for file in $OMARCHY_PATH/migrations/*.sh; do
-  filename=$(basename "$file")
+usage() {
+  echo "Usage: omarchy-migrate [--pending]"
+}

-  if [[ ! -f $STATE_DIR/$filename && ! -f $STATE_DIR/skipped/$filename ]]; then
-    echo -e "\e[32m\nRunning migration (${filename%.sh})\e[0m"
-
-    if bash $file; then
-      touch "$STATE_DIR/$filename"
-    else
-      if gum confirm "Migration ${filename%.sh} failed. Skip and continue?"; then
-        touch "$STATE_DIR/skipped/$filename"
-      else
-        exit 1
-      fi
-    fi
-  fi
+while (($#)); do
+  case "$1" in
+    --pending|--check)
+      mode="pending"
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      exit 1
+      ;;
+  esac
 done
+
+OMARCHY_PATH="${OMARCHY_PATH:-/usr/share/omarchy}"
+STATE_DIR="${OMARCHY_MIGRATION_STATE:-$HOME/.local/state/omarchy/migrations}"
+MIGRATIONS_DIR="$OMARCHY_PATH/migrations"
+
+migration_entries() {
+  [[ -d $MIGRATIONS_DIR ]] || return 0
+
+  local file filename
+
+  for file in "$MIGRATIONS_DIR"/*.sh; do
+    [[ -f $file ]] || continue
+    filename=$(basename "$file")
+    printf '%s\t%s\t%s\n' "$filename" "$file" "$STATE_DIR/$filename"
+  done
+}
+
+pending_migrations() {
+  local name file marker
+
+  while IFS=$'\t' read -r name file marker; do
+    [[ -n $name ]] || continue
+    if [[ ! -f $marker ]]; then
+      printf '%s\n' "$name"
+    fi
+  done < <(migration_entries)
+}
+
+if [[ $mode == "pending" ]]; then
+  pending_output=$(pending_migrations)
+  if [[ -n $pending_output ]]; then
+    printf '%s\n' "$pending_output"
+    exit 0
+  else
+    exit 1
+  fi
+fi
+
+wait_for_pacman_transaction() {
+  local lock_file=/var/lib/pacman/db.lck
+
+  [[ -e $lock_file ]] || return 0
+  echo "Waiting for pacman transaction to finish before running Omarchy migrations..."
+
+  for _ in {1..900}; do
+    [[ -e $lock_file ]] || return 0
+    sleep 1
+  done
+
+  echo "Pacman transaction is still running; Omarchy migrations will retry on next login."
+  exit 0
+}
+
+wait_for_pacman_transaction
+
+mkdir -p "$STATE_DIR"
+[[ -d $MIGRATIONS_DIR ]] || exit 0
+
+while IFS=$'\t' read -r name file marker; do
+  [[ -n $name ]] || continue
+
+  if [[ ! -f $marker ]]; then
+    echo -e "\e[32m\nRunning migration (${name%.sh})\e[0m"
+    OMARCHY_PATH="$OMARCHY_PATH" bash -euo pipefail "$file"
+    mkdir -p "$(dirname "$marker")"
+    touch "$marker"
+  fi
+done < <(migration_entries)
@@ -0,0 +1,35 @@
+#!/bin/bash
+
+# omarchy:summary=Notify the user when Omarchy has pending migrations
+
+set -euo pipefail
+
+pending_migrations=$(omarchy-migrate --pending 2>/dev/null) || exit 0
+pending_count=$(printf '%s\n' "$pending_migrations" | sed '/^[[:space:]]*$/d' | wc -l)
+
+if (( pending_count == 1 )); then
+  message="1 new Omarchy migration is available. Click to run it in a terminal."
+else
+  message="$pending_count new Omarchy migrations are available. Click to run them in a terminal."
+fi
+
+notify_command=$(printf 'if [[ -n $(omarchy-notification-send -u critical -g  "Run Omarchy Migrations" %q -a) ]]; then omarchy-launch-floating-terminal-with-presentation omarchy-migrate; fi' "$message")
+
+if command -v systemd-run >/dev/null 2>&1; then
+  unit="omarchy-migrations-notification-$(date +%Y%m%d%H%M%S)"
+  systemd-run --user --scope --unit="$unit" bash -lc "$notify_command" >/dev/null 2>&1 && exit 0
+fi
+
+print_pending_migrations() {
+  echo "Omarchy has pending migrations. Run omarchy-migrate in a terminal to apply them:"
+  while IFS= read -r migration; do
+    [[ -n $migration ]] || continue
+    printf '  %s\n' "$migration"
+  done <<<"$pending_migrations"
+}
+
+if [[ -t 1 ]]; then
+  print_pending_migrations
+else
+  print_pending_migrations >&2
+fi
@@ -37,7 +37,7 @@ print_status() {
    nm=$(nmcli -t -f GENERAL.STATE,GENERAL.CONNECTION dev show "$device" 2>/dev/null)
    state=$(awk -F: '$1 == "GENERAL.STATE" { print $2; exit }' <<<"$nm")
    ssid=$(awk -F: '$1 == "GENERAL.CONNECTION" { print $2; exit }' <<<"$nm")
-    signal=$(nmcli -t -f IN-USE,SIGNAL dev wifi list ifname "$device" 2>/dev/null | awk -F: '$1 == "*" { print $2; exit }')
+    signal=$(nmcli -t -f IN-USE,SIGNAL dev wifi list ifname "$device" --rescan no 2>/dev/null | awk -F: '$1 == "*" { print $2; exit }')
    freq=$(iw dev "$device" link 2>/dev/null | awk '/freq:/ { print $2; exit }')

    if [[ $state != 100* ]]; then
@@ -6,7 +6,11 @@
 # omarchy:requires-sudo=true

 if omarchy-pkg-missing "$@"; then
-  sudo pacman -S --noconfirm --needed "$@" || exit 1
+  if (( EUID == 0 )); then
+    pacman -S --noconfirm --needed "$@" || exit 1
+  else
+    sudo pacman -S --noconfirm --needed "$@" || exit 1
+  fi
 fi

 for pkg in "$@"; do
@@ -2,7 +2,7 @@

 # omarchy:summary=Preview a Plymouth boot screen with custom colors and logo
 # omarchy:args=<background-hex> <text-hex> <path-to-logo.png> <output-path>
-# omarchy:examples=omarchy plymouth preview '#1d2021' '#ebdbb2' ~/.config/omarchy/current/theme/plymouth/logo.png /tmp/plymouth-preview.png
+# omarchy:examples=omarchy plymouth preview '#1d2021' '#ebdbb2' ~/.local/state/omarchy/current/theme/plymouth/logo.png /tmp/plymouth-preview.png

 # Render a Plymouth login-screen preview PNG by compositing the staged omarchy
 # theme assets (recolored with the given text color) onto the background.
@@ -35,7 +35,7 @@ fi
 staging_dir=$(mktemp -d)
 trap 'rm -rf "$staging_dir"' EXIT

-find ~/.local/share/omarchy/default/plymouth -maxdepth 1 -type f -exec cp -t "$staging_dir/" {} +
+find $OMARCHY_PATH/default/plymouth -maxdepth 1 -type f -exec cp -t "$staging_dir/" {} +
 cp "$logo_path" "$staging_dir/logo.png"

 for asset in bullet.png entry.png lock.png; do
@@ -5,7 +5,7 @@

 theme_dir="/usr/share/plymouth/themes/omarchy"

-sudo find ~/.local/share/omarchy/default/plymouth -maxdepth 1 -type f -exec cp -t "$theme_dir/" {} +
+sudo find $OMARCHY_PATH/default/plymouth -maxdepth 1 -type f -exec cp -t "$theme_dir/" {} +
 sudo plymouth-set-default-theme omarchy

 if omarchy-cmd-present limine-mkinitcpio; then
@@ -2,7 +2,7 @@

 # omarchy:summary=Set the Plymouth boot theme colors and logo
 # omarchy:args=<background-hex> <text-hex> <path-to-logo.png>
-# omarchy:examples=omarchy plymouth set '#1d2021' '#ebdbb2' ~/.config/omarchy/current/theme/plymouth/logo.png
+# omarchy:examples=omarchy plymouth set '#1d2021' '#ebdbb2' ~/.local/state/omarchy/current/theme/plymouth/logo.png
 # omarchy:requires-sudo=true

 # Configure the Plymouth boot theme with a custom background color, text color, and logo.
@@ -42,7 +42,7 @@ theme_dir="/usr/share/plymouth/themes/omarchy"
 staging_dir=$(mktemp -d)
 trap 'rm -rf "$staging_dir"' EXIT

-find ~/.local/share/omarchy/default/plymouth -maxdepth 1 -type f -exec cp -t "$staging_dir/" {} +
+find $OMARCHY_PATH/default/plymouth -maxdepth 1 -type f -exec cp -t "$staging_dir/" {} +
 cp "$logo_path" "$staging_dir/logo.png"

 sed -i \
@@ -65,7 +65,7 @@ fi

 # Sync the SDDM login screen with the same colors and logo.
 sddm_dir="/usr/share/sddm/themes/omarchy"
-sddm_template="$HOME/.local/share/omarchy/default/sddm/omarchy/Main.qml"
+sddm_template="$OMARCHY_PATH/default/sddm/omarchy/Main.qml"

 sed \
  -e "s/#1a1b26/#$bg_hex/g" \
@@ -20,7 +20,38 @@ else
  theme_dir="$OMARCHY_PATH/themes/$theme"
 fi

-bg=$(awk -F'"' '/^background/{print $2}' "$theme_dir/colors.toml")
-text=$(awk -F'"' '/^foreground/{print $2}' "$theme_dir/colors.toml")
+theme_color() {
+  local key="$1"
+  local fallback="$2"
+
+  awk -F= -v key="$key" -v fallback="$fallback" '
+    function clean(raw) {
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", raw)
+      if (raw ~ /^"/) {
+        sub(/^"/, "", raw)
+        sub(/".*$/, "", raw)
+      }
+      return raw
+    }
+
+    {
+      field = $1
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", field)
+      if (field == key) {
+        print clean($2)
+        found = 1
+        exit
+      }
+      if (field == fallback) fallback_value = clean($2)
+    }
+
+    END {
+      if (!found && fallback_value != "") print fallback_value
+    }
+  ' "$theme_dir/colors.toml"
+}
+
+bg=$(theme_color background bg)
+text=$(theme_color foreground fg)

 exec omarchy-plymouth-set "$bg" "$text" "$theme_dir/unlock.png"
@@ -1,10 +1,6 @@
 #!/bin/bash

-# omarchy:summary=Ensure all default .desktop, web apps, TUIs, and mise wrappers are installed.
-
-mkdir -p ~/.local/share/icons/hicolor/48x48/apps/
-cp "$OMARCHY_PATH"/applications/icons/*.png ~/.local/share/icons/hicolor/48x48/apps/
-gtk-update-icon-cache ~/.local/share/icons/hicolor &>/dev/null
+# omarchy:summary=Ensure default application launchers and mise wrappers are installed.

 # Copy .desktop declarations
 mkdir -p ~/.local/share/applications
@@ -14,10 +10,8 @@ if omarchy-cmd-present alacritty; then
  cp "$OMARCHY_PATH/default/alacritty/Alacritty.desktop" ~/.local/share/applications/
 fi

-# Refresh the webapps, TUIs, and mise wrappers
-bash "$OMARCHY_PATH/install/packaging/icons.sh"
-bash "$OMARCHY_PATH/install/packaging/webapps.sh"
-bash "$OMARCHY_PATH/install/packaging/tuis.sh"
-bash "$OMARCHY_PATH/install/packaging/mise.sh"
+if [[ -f "$OMARCHY_PATH/install/user/mise.sh" ]]; then
+  bash "$OMARCHY_PATH/install/user/mise.sh"
+fi

 update-desktop-database ~/.local/share/applications
@@ -1,37 +1,37 @@
 #!/bin/bash

-# omarchy:summary=Copies the named config from ~/.local/share/omarchy/config/X/Y/Z -> ~/.config/X/Y/Z.
+# omarchy:summary=Copy a shipped user config from /etc/skel/.config into ~/.config (backs up your version).
 # omarchy:args=<config-path>

-config_file=$1
+config_file=${1:-}

 if [[ -z $config_file ]]; then
  cat <<USAGE
  Usage: $0 [config_file]

-  Must provide a file path from the .config directory to be refreshed.
-  To copy ~/.local/share/omarchy/config/hypr/hyprland.lua to ~/.config/hypr/hyprland.lua
+  Must provide a file path relative to .config to be refreshed.
+  To copy /etc/skel/.config/hypr/hyprland.lua to ~/.config/hypr/hyprland.lua:

    $0 hypr/hyprland.lua
 USAGE
  exit 1
 fi

-# Backup the destination file (with timestamp) to avoid clobbering (Ex: hyprland.lua.bak.1753817951)
 user_config_file="${HOME}/.config/$config_file"
-default_config_file="$OMARCHY_PATH/config/$config_file"
+default_config_file="/etc/skel/.config/$config_file"
 backup_config_file="$user_config_file.bak.$(date +%s)"

+if [[ ! -e $default_config_file ]]; then
+  echo "Not a shipped user config: $config_file" >&2
+  exit 1
+fi
+
 mkdir -p "$(dirname "$user_config_file")"

 if [[ -f $user_config_file ]]; then
-  # Create preliminary backup
-  cp -f "$user_config_file" "$backup_config_file" 2>/dev/null
+  cp -f "$user_config_file" "$backup_config_file"
+  cp -f "$default_config_file" "$user_config_file"

-  # Replace config with new default
-  cp -f "$default_config_file" "$user_config_file" 2>/dev/null
-
-  # Compare and delete/inform accordingly
  if cmp -s "$user_config_file" "$backup_config_file"; then
    rm "$backup_config_file"
  else
@@ -39,6 +39,5 @@ if [[ -f $user_config_file ]]; then
    diff "$user_config_file" "$backup_config_file" || true
  fi
 else
-  # Config file did not exist already
-  cp -f "$default_config_file" "$user_config_file" 2>/dev/null
+  cp -f "$default_config_file" "$user_config_file"
 fi
@@ -1,5 +0,0 @@
-#!/bin/bash
-
-# omarchy:summary=Overwrite the user config for fastfetch with the Omarchy default.
-
-omarchy-refresh-config fastfetch/config.jsonc
@@ -9,5 +9,6 @@ omarchy-refresh-config hypr/input.lua
 omarchy-refresh-config hypr/looknfeel.lua
 omarchy-refresh-config hypr/hyprland.lua
 omarchy-refresh-config hypr/monitors.lua
-bash "$OMARCHY_PATH/install/config/omarchy-toggles.sh"
-bash "$OMARCHY_PATH/install/config/detect-keyboard-layout.sh"
+
+mkdir -p ~/.local/state/omarchy/toggles/hypr
+cp "$OMARCHY_PATH/default/hypr/toggles/flags.lua" ~/.local/state/omarchy/toggles/hypr/
@@ -11,7 +11,7 @@ echo "Resetting limine config"

 sudo mv /boot/limine.conf /boot/limine.conf.bak

-sudo cp ~/.local/share/omarchy/default/limine/limine.conf /boot/limine.conf
+sudo cp $OMARCHY_PATH/default/limine/limine.conf /boot/limine.conf

 sudo limine-update
 sudo limine-snapper-sync
@@ -23,4 +23,4 @@ sudo cp -f "$OMARCHY_PATH/default/pacman/mirrorlist-$channel" /etc/pacman.d/mirr
 omarchy-hook pre-refresh-pacman

 # Reset all package DBs and then update
-sudo pacman -Syyuu --noconfirm
+sudo env OMARCHY_UPDATE_PACMAN=1 pacman -Syyuu --noconfirm
@@ -3,7 +3,7 @@
 # omarchy:summary=Overwrite the user config for the Plymouth drive decryption and boot sequence with the Omarchy default and rebuild it.
 # omarchy:requires-sudo=true

-sudo cp -r ~/.local/share/omarchy/default/plymouth/* /usr/share/plymouth/themes/omarchy/
+sudo cp -r $OMARCHY_PATH/default/plymouth/* /usr/share/plymouth/themes/omarchy/
 sudo plymouth-set-default-theme omarchy

 if command -v limine-mkinitcpio &>/dev/null; then
@@ -5,12 +5,9 @@

 set -e

-# Attempt to reinstall all default Omarchy packages and reset all the default configs.
+echo -e "This will reinstall all default Omarchy packages and reset default configs.\nWarning: user config changes will be overwritten.\n"

-echo -e "This will reinstall all the default Omarchy packages and reset all default configs.\nWarning: All user changes to configs will be lost.\n"
-
-if gum confirm "Are you sure you want to reinstall and lose all config changes?"; then
-  omarchy-reinstall-git
+if gum confirm "Are you sure you want to reinstall and lose config changes?"; then
  omarchy-reinstall-pkgs
  omarchy-reinstall-configs

@@ -1,24 +1,28 @@
 #!/bin/bash

-# omarchy:summary=Reset all Omarchy user configs to the defaults
-# omarchy:requires-sudo=true
+# omarchy:summary=Reset Omarchy user configs and shipped defaults in $HOME (destructive)

-set -e
-
-# Overwrite all user configs with the Omarchy defaults.
+set -euo pipefail

 if (( EUID == 0 )); then
  echo "Error: This script should not be run as root"
  exit 1
 fi

-echo "Resetting all Omarchy configs"
-cp -R ~/.local/share/omarchy/config/* ~/.config/
-cp ~/.local/share/omarchy/default/bashrc ~/.bashrc
-echo '[[ -f ~/.bashrc ]] && . ~/.bashrc' | tee ~/.bash_profile >/dev/null
+echo "Resetting Omarchy user configs to shipped defaults..."

-$(bash $OMARCHY_PATH/install/config/theme.sh)
+# /etc/skel is the same tree useradd -m copies to seed a fresh user's $HOME.
+# Replaying it over an existing user resyncs every package-shipped user
+# default in one pass: .bashrc, .config/**, .local/share/applications,
+# nautilus-python extensions, branding, hypr toggles, and migration markers.
+# Trailing dot copies dotfiles; the shell wouldn't glob them with /etc/skel/*.
+cp -af /etc/skel/. ~/

 omarchy-refresh-limine
 omarchy-refresh-plymouth
-omarchy-nvim-setup
+
+if omarchy-cmd-present omarchy-nvim-refresh; then
+  omarchy-nvim-refresh
+elif omarchy-cmd-present omarchy-nvim-setup; then
+  omarchy-nvim-setup --force
+fi
@@ -1,11 +0,0 @@
-#!/bin/bash
-
-# omarchy:summary=Reinstall the stable Omarchy source directory from git
-
-set -e
-
-# Reinstall the Omarchy configuration directory from the git source.
-
-git clone --depth=1 --branch master "https://github.com/basecamp/omarchy.git" ~/.local/share/omarchy-new >/dev/null
-mv $OMARCHY_PATH ~/.local/share/omarchy-old
-mv ~/.local/share/omarchy-new $OMARCHY_PATH
@@ -11,8 +11,8 @@ set -e
 omarchy-refresh-pacman

 # Downgrade any packages to the stable setup
-sudo pacman -Suu --noconfirm
+sudo env OMARCHY_UPDATE_PACMAN=1 pacman -Suu --noconfirm

 # Ensure all packages are installed
 mapfile -t packages < <(grep -v '^#' "$OMARCHY_PATH/install/omarchy-base.packages" | grep -v '^$')
-sudo pacman -Syu --noconfirm --needed "${packages[@]}"
+sudo env OMARCHY_UPDATE_PACMAN=1 pacman -Syu --noconfirm --needed "${packages[@]}"
@@ -12,9 +12,7 @@ sleep 1

 rm -rf "$PREFIX"
 rm -f "$HOME/.local/share/applications/battlenet.desktop"
-rm -f "$HOME/.local/share/icons/hicolor/48x48/apps/Battle.net.png"
 rm -f "$HOME/.cache/omarchy/Battle.net-Setup.exe"
-gtk-update-icon-cache "$HOME/.local/share/icons/hicolor" &>/dev/null || true
 update-desktop-database "$HOME/.local/share/applications" 2>/dev/null || true

 echo
@@ -8,8 +8,8 @@ if gum confirm "Are you sure you want to remove all preinstalled web apps, TUI w
  omarchy-webapp-remove-all
  omarchy-tui-remove-all

-  [[ -f ~/.config/hypr/bindings.lua ]] && cp ~/.config/hypr/bindings.lua ~/.config/hypr/bindings.lua.bak
-  cp "$OMARCHY_PATH/default/hypr/plain-bindings.lua" ~/.config/hypr/bindings.lua
+  mkdir -p ~/.local/state/omarchy
+  touch ~/.local/state/omarchy/preinstalls-removed
  hyprctl reload

  # Remove mise stubs
@@ -24,7 +24,6 @@ if gum confirm "Are you sure you want to remove all preinstalled web apps, TUI w
    spotify \
    libreoffice-fresh \
    1password \
-    1password-beta \
    1password-cli \
    xournalpp \
    signal-desktop \
@@ -3,13 +3,178 @@
 # omarchy:summary=Restart the Omarchy shell
 # omarchy:examples=omarchy restart shell

-CONFIG_DIR="$OMARCHY_PATH/shell"
+omarchy_root="${OMARCHY_PATH:-/usr/share/omarchy}"
+if [[ ! -f $omarchy_root/shell/shell.qml && -f /usr/share/omarchy/shell/shell.qml ]]; then
+  omarchy_root=/usr/share/omarchy
+fi

-if [[ $(omarchy-shell lock isLocked 2>/dev/null || true) == "true" ]]; then
+CONFIG_DIR="$omarchy_root/shell"
+[[ -f $CONFIG_DIR/shell.qml ]] || { echo "Omarchy shell config not found: $CONFIG_DIR" >&2; exit 1; }
+
+export OMARCHY_PATH="$omarchy_root"
+export PATH="$omarchy_root/bin:/usr/local/bin:/usr/bin:/bin:$PATH"
+
+omarchy_shell_bin=/usr/bin/omarchy-shell
+[[ -x $omarchy_shell_bin ]] || omarchy_shell_bin=omarchy-shell
+
+import_env_from_pid() {
+  local pid=$1 entry key
+
+  [[ -r /proc/$pid/environ ]] || return 1
+
+  while IFS= read -r -d '' entry; do
+    key=${entry%%=*}
+    case $key in
+      DBUS_SESSION_BUS_ADDRESS | DISPLAY | HYPRLAND_INSTANCE_SIGNATURE | LANG | LC_ALL | LC_CTYPE | QT_QPA_PLATFORM | WAYLAND_DISPLAY | XDG_CURRENT_DESKTOP | XDG_RUNTIME_DIR | XDG_SESSION_TYPE)
+        [[ -n ${!key:-} ]] || export "$entry"
+        ;;
+    esac
+  done <"/proc/$pid/environ"
+}
+
+import_graphical_session_env() {
+  local current_user hypr_dir pid wayland_socket x11_socket
+
+  current_user=${USER:-$(id -un)}
+
+  for pid in $(pgrep -xu "$current_user" quickshell 2>/dev/null || true); do
+    import_env_from_pid "$pid" || true
+  done
+
+  for pid in $(pgrep -u "$UID" -f '/omarchy-hyprland-monitor-watch($| )' 2>/dev/null || true); do
+    import_env_from_pid "$pid" || true
+  done
+
+  if [[ -z ${XDG_RUNTIME_DIR:-} && -d /run/user/$UID ]]; then
+    export XDG_RUNTIME_DIR="/run/user/$UID"
+  fi
+
+  if [[ -z ${WAYLAND_DISPLAY:-} && -n ${XDG_RUNTIME_DIR:-} ]]; then
+    for wayland_socket in "$XDG_RUNTIME_DIR"/wayland-*; do
+      [[ -S $wayland_socket ]] || continue
+      export WAYLAND_DISPLAY=${wayland_socket##*/}
+      break
+    done
+  fi
+
+  if [[ -z ${DISPLAY:-} ]]; then
+    for x11_socket in /tmp/.X11-unix/X*; do
+      [[ -S $x11_socket ]] || continue
+      export DISPLAY=:${x11_socket##*X}
+      break
+    done
+  fi
+
+  if [[ -z ${HYPRLAND_INSTANCE_SIGNATURE:-} && -n ${XDG_RUNTIME_DIR:-} && -d $XDG_RUNTIME_DIR/hypr ]]; then
+    hypr_dir=$(find "$XDG_RUNTIME_DIR/hypr" -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\n' 2>/dev/null | sort -n | tail -n 1 | cut -d' ' -f2-)
+    [[ -n $hypr_dir ]] && export HYPRLAND_INSTANCE_SIGNATURE=${hypr_dir##*/}
+  fi
+
+  if [[ -z ${LANG:-} || $LANG == "C" || $LANG == "POSIX" ]]; then
+    if locale -a 2>/dev/null | grep -qxF "C.utf8"; then
+      export LANG="C.utf8"
+    else
+      export LANG="C.UTF-8"
+    fi
+  fi
+
+  if [[ -z ${QT_QPA_PLATFORM:-} ]]; then
+    export QT_QPA_PLATFORM="wayland;xcb"
+  fi
+
+  if [[ -z ${DBUS_SESSION_BUS_ADDRESS:-} && -n ${XDG_RUNTIME_DIR:-} && -S $XDG_RUNTIME_DIR/bus ]]; then
+    export DBUS_SESSION_BUS_ADDRESS="unix:path=$XDG_RUNTIME_DIR/bus"
+  fi
+}
+
+require_graphical_session_env() {
+  local missing=()
+
+  [[ -n ${XDG_RUNTIME_DIR:-} ]] || missing+=(XDG_RUNTIME_DIR)
+  [[ -n ${WAYLAND_DISPLAY:-} || -n ${DISPLAY:-} ]] || missing+=(WAYLAND_DISPLAY)
+
+  if [[ -n ${XDG_RUNTIME_DIR:-} && -d $XDG_RUNTIME_DIR/hypr && -z ${HYPRLAND_INSTANCE_SIGNATURE:-} ]]; then
+    missing+=(HYPRLAND_INSTANCE_SIGNATURE)
+  fi
+
+  if (( ${#missing[@]} > 0 )); then
+    printf 'Refusing to restart Omarchy shell; missing graphical session environment: %s\n' "${missing[*]}" >&2
+    exit 1
+  fi
+}
+
+hyprland_session_locked() {
+  local monitors
+
+  if monitors=$(hyprctl -j monitors 2>/dev/null); then
+    [[ $monitors == *'"LOCK"'* ]] && return 0
+  fi
+
+  monitors=$(hyprctl monitors 2>/dev/null) || return 1
+  [[ $monitors == *"session lock"* ]]
+}
+
+shell_quote() {
+  printf "'"
+  printf "%s" "$1" | sed "s/'/'\\\\''/g"
+  printf "'"
+}
+
+lua_quote() {
+  local value=$1
+  value=${value//\\/\\\\}
+  value=${value//\"/\\\"}
+  value=${value//$'\n'/\\n}
+  printf '"%s"' "$value"
+}
+
+launch_shell() {
+  local launch_command
+
+  launch_command="env OMARCHY_PATH=$(shell_quote "$omarchy_root") PATH=$(shell_quote "$PATH") quickshell -n -p $(shell_quote "$CONFIG_DIR")"
+
+  if [[ -n ${HYPRLAND_INSTANCE_SIGNATURE:-} ]] && omarchy-cmd-present hyprctl; then
+    if hyprctl dispatch "hl.dsp.exec_cmd($(lua_quote "$launch_command"))" >/dev/null 2>&1; then
+      return 0
+    fi
+
+    if hyprctl dispatch exec "$launch_command" >/dev/null 2>&1; then
+      return 0
+    fi
+  fi
+
+  setsid quickshell -n -p "$CONFIG_DIR" >/dev/null 2>&1 &
+}
+
+restore_hyprland_session_lock() {
+  local attempt
+
+  for (( attempt = 0; attempt < 50; attempt++ )); do
+    if "$omarchy_shell_bin" shell ping >/dev/null 2>&1; then
+      "$omarchy_shell_bin" lock lock >/dev/null 2>&1 || true
+      return 0
+    fi
+    sleep 0.1
+  done
+
+  echo "Omarchy shell restarted while Hyprland was session-locked, but lock IPC did not become ready." >&2
+}
+
+import_graphical_session_env
+require_graphical_session_env
+
+hyprland_was_session_locked=0
+hyprland_session_locked && hyprland_was_session_locked=1
+
+if [[ $("$omarchy_shell_bin" lock isLocked 2>/dev/null || true) == "true" ]]; then
  echo "Refusing to restart Omarchy shell while the session is locked." >&2
  exit 1
 fi

 pkill -x quickshell 2>/dev/null || true
 sleep 0.2
-setsid quickshell -n -p "$CONFIG_DIR" >/dev/null 2>&1 &
+launch_shell
+
+if (( hyprland_was_session_locked )); then
+  restore_hyprland_session_lock
+fi
@@ -0,0 +1,61 @@
+#!/bin/bash
+
+# omarchy:summary=Apply Omarchy hardware-specific packages and system configuration
+# omarchy:group=setup
+# omarchy:requires-sudo=true
+# omarchy:examples=omarchy setup hardware --install-user dhh
+
+set -euo pipefail
+
+usage() {
+  cat <<USAGE
+Usage: omarchy setup hardware --install-user USER
+
+Runs idempotent hardware detection/setup for the installed machine. This is
+called by omarchy-setup-system during ISO finalization and can be rerun later
+for diagnostics or after hardware/package updates.
+USAGE
+}
+
+install_user="${OMARCHY_INSTALL_USER:-}"
+while (($#)); do
+  case "$1" in
+    --install-user)
+      install_user="${2:-}"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+if (( EUID != 0 )); then
+  echo "Error: omarchy-setup-hardware must run as root" >&2
+  exit 1
+fi
+
+if [[ -z $install_user || $install_user == "root" ]]; then
+  echo "Error: --install-user must name the target non-root user" >&2
+  exit 1
+fi
+
+if ! getent passwd "$install_user" >/dev/null; then
+  echo "Error: user '$install_user' does not exist" >&2
+  exit 1
+fi
+
+export OMARCHY_INSTALL_USER="$install_user"
+export OMARCHY_PATH="${OMARCHY_PATH:-/usr/share/omarchy}"
+export OMARCHY_INSTALL="${OMARCHY_INSTALL:-$OMARCHY_PATH/install}"
+export OMARCHY_INSTALL_LOG_FILE="${OMARCHY_INSTALL_LOG_FILE:-/var/log/omarchy-install.log}"
+export PATH="$OMARCHY_PATH/bin:$PATH"
+
+source "$OMARCHY_INSTALL/helpers/logging.sh"
+source "$OMARCHY_INSTALL/hardware/all.sh"
@@ -7,7 +7,7 @@

 set -e

-target_user=${SUDO_USER:-}
+target_user=${OMARCHY_INSTALL_USER:-${SUDO_USER:-}}
 if [[ -z $target_user && -n ${PKEXEC_UID:-} ]]; then
  target_user=$(getent passwd "$PKEXEC_UID" | cut -d: -f1)
 fi
@@ -59,4 +59,9 @@ else
 fi


-omarchy-shell lock status >/dev/null 2>&1 && echo "Lock screen authentication configured."
+# omarchy-shell can't reach a running shell during chroot install. The echo
+# is just confirmation, so swallow the failure rather than letting it become
+# the script's exit code.
+if omarchy-shell lock status >/dev/null 2>&1; then
+  echo "Lock screen authentication configured."
+fi
@@ -57,12 +57,12 @@ echo -e "\e[32mSetting up fingerprint scanner for authentication.\n\e[0m"
 # Install required packages
 echo "Installing required packages..."

+installed_libfprint=$(pacman -Qq libfprint 2>/dev/null || true)
+
 # libfprint-git provides+conflicts libfprint; pacman -S --noconfirm
-# defaults the conflict prompt to N and aborts. Pre-remove libfprint
-# with -Rdd so the install goes silent. -Rdd (not omarchy-pkg-drop's
-# -Rns) is required because fprintd requires libfprint; the dep is
-# re-satisfied immediately by libfprint-git's provides=libfprint.
-if omarchy-pkg-present libfprint; then
+# defaults the conflict prompt to N and aborts. Pre-remove the exact
+# libfprint package, but not an installed provider like libfprint-git.
+if [[ $installed_libfprint == "libfprint" ]]; then
  sudo pacman -Rdd --noconfirm libfprint
 fi

@@ -0,0 +1,92 @@
+#!/bin/bash
+
+# omarchy:summary=Apply Omarchy system setup in the installed target
+# omarchy:group=setup
+# omarchy:requires-sudo=true
+# omarchy:examples=omarchy setup system --install-user dhh --first-install
+
+set -euo pipefail
+
+usage() {
+  cat <<USAGE
+Usage: omarchy setup system --install-user USER [--first-install|--upgrade]
+
+Runs root-owned Omarchy system setup. The ISO calls this in the target chroot
+after packages are installed and the target user exists. It also calls
+omarchy-setup-hardware, so hardware setup cannot be accidentally skipped.
+USAGE
+}
+
+install_user="${OMARCHY_INSTALL_USER:-}"
+first_install=0
+upgrade=0
+
+while (($#)); do
+  case "$1" in
+    --install-user)
+      install_user="${2:-}"
+      shift 2
+      ;;
+    --first-install)
+      first_install=1
+      shift
+      ;;
+    --upgrade)
+      upgrade=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+if (( EUID != 0 )); then
+  echo "Error: omarchy-setup-system must run as root" >&2
+  exit 1
+fi
+
+if [[ -z $install_user || $install_user == "root" ]]; then
+  echo "Error: --install-user must name the target non-root user" >&2
+  exit 1
+fi
+
+if ! getent passwd "$install_user" >/dev/null; then
+  echo "Error: user '$install_user' does not exist" >&2
+  exit 1
+fi
+
+export OMARCHY_INSTALL_USER="$install_user"
+export OMARCHY_FIRST_INSTALL="$first_install"
+export OMARCHY_UPGRADE="$upgrade"
+export OMARCHY_PATH="${OMARCHY_PATH:-/usr/share/omarchy}"
+export OMARCHY_INSTALL="${OMARCHY_INSTALL:-$OMARCHY_PATH/install}"
+export OMARCHY_INSTALL_LOG_FILE="${OMARCHY_INSTALL_LOG_FILE:-/var/log/omarchy-install.log}"
+export PATH="$OMARCHY_PATH/bin:$PATH"
+
+source "$OMARCHY_INSTALL/helpers/logging.sh"
+start_install_log
+
+run_logged "$OMARCHY_INSTALL/config/theme-system.sh"
+run_logged "$OMARCHY_INSTALL/config/increase-lockout-limit.sh"
+run_logged "$OMARCHY_INSTALL/config/lockscreen-pam.sh"
+run_logged "$OMARCHY_INSTALL/config/fix-powerprofilesctl-shebang.sh"
+run_logged "$OMARCHY_INSTALL/config/docker.sh"
+run_logged "$OMARCHY_INSTALL/config/enable-services.sh"
+run_logged "$OMARCHY_INSTALL/config/firewall.sh"
+
+omarchy-setup-hardware --install-user "$install_user"
+
+run_logged "$OMARCHY_INSTALL/login/sddm.sh"
+
+run_logged "$OMARCHY_INSTALL/post-install/pacman.sh"
+run_logged "$OMARCHY_INSTALL/post-install/udev.sh"
+run_logged "$OMARCHY_INSTALL/post-install/localdb.sh"
+
+stop_install_log
@@ -75,7 +75,7 @@ valid_hex "$background_color" || fallback
 omarchy-cmd-present magick || fallback

 if [[ -z $background_path ]]; then
-  background_path=$(readlink -f "$HOME/.config/omarchy/current/background" 2>/dev/null || true)
+  background_path=$(readlink -f "$HOME/.local/state/omarchy/current/background" 2>/dev/null || true)
 fi
 [[ -f $background_path ]] || fallback

@@ -4,6 +4,6 @@

 clear
 echo -e "\033[32m"
-cat <~/.local/share/omarchy/logo.txt
+cat <$OMARCHY_PATH/logo.txt
 echo -e "\033[0m"
 echo
@@ -7,11 +7,13 @@
 monitor_command='exec dbus-monitor --system "type='\''signal'\'',sender='\''org.freedesktop.login1'\'',interface='\''org.freedesktop.login1.Manager'\'',member='\''PrepareForSleep'\''"'

 consume_sleep_events() {
-  local line
+  local line sleep_lock
+  sleep_lock=$(command -v omarchy-system-sleep-lock || true)
+  sleep_lock=${sleep_lock:-/usr/bin/omarchy-system-sleep-lock}

  while IFS= read -r line; do
    if [[ $line == *"boolean true"* ]]; then
-      "$OMARCHY_PATH/bin/omarchy-system-sleep-lock"
+      "$sleep_lock"
      exit 0
    fi
  done
@@ -22,9 +24,12 @@ if [[ ${1:-} == "--consume" ]]; then
  exit 0
 fi

+sleep_monitor=$(command -v omarchy-system-sleep-monitor || true)
+sleep_monitor=${sleep_monitor:-/usr/bin/omarchy-system-sleep-monitor}
+
 exec systemd-inhibit \
  --what=sleep \
  --mode=delay \
  --who=Omarchy \
  --why="Lock screen before suspend" \
-  bash -lc "$monitor_command | \"$OMARCHY_PATH/bin/omarchy-system-sleep-monitor\" --consume"
+  bash -lc "$monitor_command | \"$sleep_monitor\" --consume"
@@ -2,9 +2,9 @@

 # omarchy:summary=Cache background switcher thumbnails for the current theme

-theme_name=$(cat "$HOME/.config/omarchy/current/theme.name" 2>/dev/null)
+theme_name=$(cat "$HOME/.local/state/omarchy/current/theme.name" 2>/dev/null)

 omarchy-menu-images \
  --cache-only \
-  "$HOME/.config/omarchy/current/theme/backgrounds" \
+  "$HOME/.local/state/omarchy/current/theme/backgrounds" \
  "$HOME/.config/omarchy/backgrounds/$theme_name"
@@ -3,7 +3,7 @@
 # omarchy:summary=Show current background
 # omarchy:examples=omarchy theme bg current

-BACKGROUND_PATH=$(readlink -f "$HOME/.config/omarchy/current/background" 2>/dev/null)
+BACKGROUND_PATH=$(readlink -f "$HOME/.local/state/omarchy/current/background" 2>/dev/null)

 if [[ -n $BACKGROUND_PATH ]]; then
  basename -- "$BACKGROUND_PATH" | perl -pe 's/\.[^.]+$//; s/^\d+-//; s/-/ /g; s/\b(\w)/\U$1/g'
@@ -2,7 +2,7 @@

 # omarchy:summary=Open the current theme's user background folder

-CURRENT_THEME_NAME=$(cat "$HOME/.config/omarchy/current/theme.name")
+CURRENT_THEME_NAME=$(cat "$HOME/.local/state/omarchy/current/theme.name")
 THEME_USER_BACKGROUNDS="$HOME/.config/omarchy/backgrounds/$CURRENT_THEME_NAME"

 mkdir -p "$THEME_USER_BACKGROUNDS"
@@ -3,10 +3,10 @@
 # omarchy:summary=Cycle to the next background for the current theme
 # omarchy:examples=omarchy theme bg next

-THEME_NAME=$(cat "$HOME/.config/omarchy/current/theme.name" 2>/dev/null)
-THEME_BACKGROUNDS_PATH="$HOME/.config/omarchy/current/theme/backgrounds/"
+THEME_NAME=$(cat "$HOME/.local/state/omarchy/current/theme.name" 2>/dev/null)
+THEME_BACKGROUNDS_PATH="$HOME/.local/state/omarchy/current/theme/backgrounds/"
 USER_BACKGROUNDS_PATH="$HOME/.config/omarchy/backgrounds/$THEME_NAME/"
-CURRENT_BACKGROUND_LINK="$HOME/.config/omarchy/current/background"
+CURRENT_BACKGROUND_LINK="$HOME/.local/state/omarchy/current/background"

 mapfile -d '' -t BACKGROUNDS < <(
  find -L "$USER_BACKGROUNDS_PATH" "$THEME_BACKGROUNDS_PATH" -maxdepth 1 -type f \
@@ -10,7 +10,7 @@ if [[ -z $1 ]]; then
 fi

 BACKGROUND="$(realpath "$1")"
-CURRENT_BACKGROUND_LINK="$HOME/.config/omarchy/current/background"
+CURRENT_BACKGROUND_LINK="$HOME/.local/state/omarchy/current/background"

 if [[ ! -f $BACKGROUND ]]; then
  echo "File does not exist: $BACKGROUND" >&2
@@ -5,10 +5,10 @@
 # omarchy:name=bg-switcher
 # omarchy:aliases=omarchy background

-theme_name=$(cat "$HOME/.config/omarchy/current/theme.name" 2>/dev/null)
-current_background=$(readlink -f "$HOME/.config/omarchy/current/background" 2>/dev/null)
+theme_name=$(cat "$HOME/.local/state/omarchy/current/theme.name" 2>/dev/null)
+current_background=$(readlink -f "$HOME/.local/state/omarchy/current/background" 2>/dev/null)

 omarchy-menu-images \
  --selected "$current_background" \
-  "$HOME/.config/omarchy/current/theme/backgrounds" \
+  "$HOME/.local/state/omarchy/current/theme/backgrounds" \
  "$HOME/.config/omarchy/backgrounds/$theme_name"
@@ -154,13 +154,6 @@ if [[ -z $foreground ]]; then
  foreground=$(extract_color_in_section "colors" "primary.foreground")
 fi

-# Extract cursor color (from [colors.cursor] section)
-cursor=$(extract_color_in_section "colors.cursor" "cursor")
-
-if [[ -z $cursor ]]; then
-  cursor=$(extract_color_in_section "colors" "cursor.cursor")
-fi
-
 # Extract selection colors
 selection_background=$(extract_color_in_section "colors.selection" "background")

@@ -168,29 +161,22 @@ if [[ -z $selection_background ]]; then
  selection_background=$(extract_color_in_section "colors" "selection.background")
 fi

-selection_foreground=$(extract_color_in_section "colors.selection" "text")
-
-if [[ -z $selection_foreground ]]; then
-  selection_foreground=$(extract_color_in_section "colors" "selection.text")
-fi
-
 # Apply defaults
 background=${background:-$color0}
 foreground=${foreground:-$color7}
-cursor=${cursor:-$foreground}
+color0=$background
+color7=$foreground
 selection_background=${selection_background:-$foreground}
-selection_foreground=${selection_foreground:-$background}
 accent=$color4

 mkdir -p "$THEME_SOURCE"

 cat > "$COLORS_OUTPUT" <<EOF
 accent = "$accent"
-cursor = "$cursor"
-foreground = "$foreground"
-background = "$background"
-selection_foreground = "$selection_foreground"
-selection_background = "$selection_background"
+selection = "$selection_background"
+
+bg = "$background"
+fg = "$foreground"

 color0 = "$color0"
 color1 = "$color1"
@@ -3,7 +3,7 @@
 # omarchy:summary=Show current theme
 # omarchy:examples=omarchy theme current

-THEME_NAME_PATH="$HOME/.config/omarchy/current/theme.name"
+THEME_NAME_PATH="$HOME/.local/state/omarchy/current/theme.name"

 if [[ -f $THEME_NAME_PATH ]]; then
  cat $THEME_NAME_PATH | sed -E 's/(^|-)([a-z])/\1\u\2/g; s/-/ /g'
@@ -3,7 +3,7 @@
 # omarchy:summary=Print OSC sequences for an Omarchy color theme
 # omarchy:hidden=true

-theme="${1:-$HOME/.config/omarchy/current/theme/colors.toml}"
+theme="${1:-$HOME/.local/state/omarchy/current/theme/colors.toml}"

 [[ -f $theme ]] || exit 0

@@ -33,6 +33,13 @@ awk -F= '
  }

  END {
+    if (colors["background"] != "") colors["bg"] = colors["background"]
+    if (colors["foreground"] != "") colors["fg"] = colors["foreground"]
+    if (colors["bg"] != "") colors["background"] = colors["bg"]
+    if (colors["fg"] != "") colors["foreground"] = colors["fg"]
+    if (colors["bg"] != "") colors["color0"] = colors["bg"]
+    if (colors["fg"] != "") colors["color7"] = colors["fg"]
+
    alias_color("color0", "bg")
    alias_color("color0", "background")
    alias_color("color1", "red")
@@ -63,6 +70,14 @@ awk -F= '
    alias_color("color14", "cyan")
    alias_color("color15", "bright_fg")
    alias_color("color15", "foreground")
+    alias_color("light_fg", "color7")
+    alias_color("light_fg", "fg")
+    alias_color("bright_fg", "color15")
+    alias_color("bright_fg", "fg")
+    if (colors["bright_fg"] != "") colors["cursor"] = colors["bright_fg"]
+
+    if (colors["selection_background"] == "" && colors["selection"] != "") colors["selection_background"] = colors["selection"]
+    if (colors["selection_foreground"] == "") colors["selection_foreground"] = colors["bright_fg"]

    if (colors["foreground"] != "") printf "\033]10;%s\007", colors["foreground"]
    if (colors["background"] != "") printf "\033]11;%s\007", colors["background"]
@@ -2,7 +2,7 @@

 # omarchy:summary=Refresh the current theme from its templates.

-THEME_NAME_PATH="$HOME/.config/omarchy/current/theme.name"
+THEME_NAME_PATH="$HOME/.local/state/omarchy/current/theme.name"

 if [[ -f $THEME_NAME_PATH ]]; then
  OMARCHY_THEME_SKIP_BACKGROUND=1 omarchy-theme-set "$(cat $THEME_NAME_PATH)"
@@ -19,7 +19,6 @@ else
 fi

 THEMES_DIR="$HOME/.config/omarchy/themes"
-CURRENT_DIR="$HOME/.config/omarchy/current"
 THEME_PATH="$THEMES_DIR/$THEME_NAME"

 # Ensure a theme was set
@@ -9,9 +9,9 @@ if [[ -z $1 ]]; then
  exit 1
 fi

-CURRENT_THEME_PATH="$HOME/.config/omarchy/current/theme"
-NEXT_THEME_PATH="$HOME/.config/omarchy/current/next-theme"
-CURRENT_BACKGROUND_LINK="$HOME/.config/omarchy/current/background"
+CURRENT_THEME_PATH="$HOME/.local/state/omarchy/current/theme"
+NEXT_THEME_PATH="$HOME/.local/state/omarchy/current/next-theme"
+CURRENT_BACKGROUND_LINK="$HOME/.local/state/omarchy/current/background"
 BACKGROUND_TRANSITION_CACHE="$HOME/.cache/omarchy/background-transitions"
 THEME_SET_LOCK="${XDG_RUNTIME_DIR:-/tmp}/omarchy-theme-set.lock"
 USER_THEMES_PATH="$HOME/.config/omarchy/themes"
@@ -56,21 +56,18 @@ snapshot_current_background() {
  snapshot_background_path "$current_background" "previous"
 }

-set_theme_background() {
+choose_theme_background() {
  local backgrounds=()
-  local current_background index new_background next_index new_background_snapshot
+  local current_background index next_index i

+  CHOSEN_THEME_BACKGROUND=""
  mapfile -d '' -t backgrounds < <(
    find -L "$HOME/.config/omarchy/backgrounds/$THEME_NAME/" "$CURRENT_THEME_PATH/backgrounds/" -maxdepth 1 -type f \
      \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' -o -iname '*.gif' -o -iname '*.bmp' -o -iname '*.webp' \) \
      -print0 2>/dev/null | sort -z
  )

-  if (( ${#backgrounds[@]} == 0 )); then
-    omarchy-notification-send "No background was found for theme" -t 2000
-    shell_ipc shell applyTheme "$colors_payload" "$shell_payload" || true
-    return
-  fi
+  (( ${#backgrounds[@]} > 0 )) || return 1

  current_background=$(readlink "$CURRENT_BACKGROUND_LINK" 2>/dev/null || true)
  index=-1
@@ -82,12 +79,28 @@ set_theme_background() {
  done

  if (( index == -1 )); then
-    new_background="${backgrounds[0]}"
+    CHOSEN_THEME_BACKGROUND="${backgrounds[0]}"
  else
    next_index=$(((index + 1) % ${#backgrounds[@]}))
-    new_background="${backgrounds[$next_index]}"
+    CHOSEN_THEME_BACKGROUND="${backgrounds[$next_index]}"
+  fi
+}
+
+set_theme_background_link() {
+  choose_theme_background || return 1
+  ln -nsf "$CHOSEN_THEME_BACKGROUND" "$CURRENT_BACKGROUND_LINK"
+}
+
+set_theme_background() {
+  local new_background new_background_snapshot
+
+  if ! choose_theme_background; then
+    omarchy-notification-send "No background was found for theme" -t 2000
+    shell_ipc shell applyTheme "$colors_payload" "$shell_payload" || true
+    return
  fi

+  new_background="$CHOSEN_THEME_BACKGROUND"
  new_background_snapshot=$(snapshot_background_path "$new_background" "next")

  if [[ -f $OLD_BACKGROUND_SNAPSHOT && -f $new_background_snapshot ]]; then
@@ -110,6 +123,10 @@ set_theme_background() {
 }

 THEME_NAME=$(echo "$1" | sed -E 's/<[^>]+>//g' | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+THEME_HEADLESS=0
+if [[ ${OMARCHY_THEME_HEADLESS:-} == "1" || ${OMARCHY_THEME_OFFLINE:-} == "1" ]]; then
+  THEME_HEADLESS=1
+fi

 if [[ ! -d $OMARCHY_THEMES_PATH/$THEME_NAME ]] && [[ ! -d $USER_THEMES_PATH/$THEME_NAME ]]; then
  echo "Theme '$THEME_NAME' does not exist"
@@ -139,7 +156,7 @@ fi
 omarchy-theme-set-templates

 OLD_BACKGROUND_SNAPSHOT=""
-if [[ $OMARCHY_THEME_SKIP_BACKGROUND != "1" ]]; then
+if [[ $THEME_HEADLESS != "1" && $OMARCHY_THEME_SKIP_BACKGROUND != "1" ]]; then
  OLD_BACKGROUND_SNAPSHOT=$(snapshot_current_background)
 fi

@@ -148,13 +165,18 @@ rm -rf "$CURRENT_THEME_PATH"
 mv "$NEXT_THEME_PATH" "$CURRENT_THEME_PATH"

 # Store theme name for reference
-echo "$THEME_NAME" >"$HOME/.config/omarchy/current/theme.name"
+echo "$THEME_NAME" >"$HOME/.local/state/omarchy/current/theme.name"

 # Make the running shell pick up the new palette immediately while the rest of
 # the theme hooks run.
 colors_payload=$([[ -f $CURRENT_THEME_PATH/colors.toml ]] && base64 -w 0 "$CURRENT_THEME_PATH/colors.toml")
 shell_payload=$([[ -f $CURRENT_THEME_PATH/shell.toml ]] && base64 -w 0 "$CURRENT_THEME_PATH/shell.toml")
-if [[ $OMARCHY_THEME_SKIP_BACKGROUND == "1" ]]; then
+if [[ $THEME_HEADLESS == "1" ]]; then
+  # No shell/session bus exists during ISO chroot finalization, but the first
+  # real login still needs a current background symlink for omarchy-shell to
+  # render.
+  [[ $OMARCHY_THEME_SKIP_BACKGROUND == "1" ]] || set_theme_background_link || true
+elif [[ $OMARCHY_THEME_SKIP_BACKGROUND == "1" ]]; then
  shell_ipc shell applyTheme "$colors_payload" "$shell_payload" || true
 else
  set_theme_background
@@ -181,13 +203,15 @@ post_theme_commands=(
  omarchy-theme-set-keyboard
 )

-run_parallel "${post_theme_commands[@]}"
+if [[ $THEME_HEADLESS != "1" ]]; then
+  run_parallel "${post_theme_commands[@]}"

-# Call hook on theme set
-omarchy-hook theme-set "$THEME_NAME" >/dev/null
+  # Call hook on theme set
+  omarchy-hook theme-set "$THEME_NAME" >/dev/null

-# Warm selector caches after the theme is applied. The shell hot-reloads theme
-# colors/backgrounds, so keep the running instance alive and preload the picker
-# rows/selection to avoid first-open carousel settling after a theme change.
-omarchy-theme-switcher --preload >/dev/null 2>&1
-omarchy-theme-bg-cache >/dev/null 2>&1 &
+  # Warm selector caches after the theme is applied. The shell hot-reloads theme
+  # colors/backgrounds, so keep the running instance alive and preload the picker
+  # rows/selection to avoid first-open carousel settling after a theme change.
+  omarchy-theme-switcher --preload >/dev/null 2>&1
+  omarchy-theme-bg-cache >/dev/null 2>&1 &
+fi
@@ -3,7 +3,7 @@
 # omarchy:summary=Apply the current theme color to Chromium, Chrome, Edge, and Brave
 # omarchy:hidden=true

-CHROMIUM_THEME=~/.config/omarchy/current/theme/chromium.theme
+CHROMIUM_THEME=$HOME/.local/state/omarchy/current/theme/chromium.theme

 if [[ -f $CHROMIUM_THEME ]]; then
  THEME_RGB_COLOR=$(<$CHROMIUM_THEME)
@@ -3,7 +3,7 @@
 # omarchy:summary=Apply current Omarchy theme colors to running Foot terminals
 # omarchy:hidden=true

-colors_toml=~/.config/omarchy/current/theme/colors.toml
+colors_toml=$HOME/.local/state/omarchy/current/theme/colors.toml

 if [[ ! -f $colors_toml ]] || ! pgrep -x foot >/dev/null; then
  exit 0
@@ -3,7 +3,14 @@
 # omarchy:summary=Apply the current theme to GNOME color mode and icon settings
 # omarchy:hidden=true

-THEME_DIR=~/.config/omarchy/current/theme
+# gsettings needs a user DBus session. During ISO installs this command can be
+# reached from arch-chroot while applying the initial Omarchy theme; defer until
+# the user has a real session instead of emitting dconf warnings.
+if [[ -z ${DBUS_SESSION_BUS_ADDRESS:-} ]]; then
+  exit 0
+fi
+
+THEME_DIR=$HOME/.local/state/omarchy/current/theme
 COLORS_FILE="$THEME_DIR/colors.toml"

 # In-tree light themes now declare `mode = "light"` in colors.toml instead of
@@ -43,7 +50,7 @@ else
 fi

 # Change gnome icon theme color
-GNOME_ICONS_THEME=~/.config/omarchy/current/theme/icons.theme
+GNOME_ICONS_THEME=$HOME/.local/state/omarchy/current/theme/icons.theme
 if [[ -f $GNOME_ICONS_THEME ]]; then
  gsettings set org.gnome.desktop.interface icon-theme "$(<$GNOME_ICONS_THEME)"
 else
@@ -3,7 +3,7 @@
 # omarchy:summary=Apply the current theme keyboard color to ASUS ROG keyboards
 # omarchy:hidden=true

-ASUSCTL_THEME=~/.config/omarchy/current/theme/keyboard.rgb
+ASUSCTL_THEME=$HOME/.local/state/omarchy/current/theme/keyboard.rgb

 if omarchy-cmd-present asusctl; then
  asusctl aura effect static -c $(sed 's/^#//' $ASUSCTL_THEME)
@@ -3,7 +3,7 @@
 # omarchy:summary=Apply the current theme keyboard color to Framework Laptop 16 keyboards
 # omarchy:hidden=true

-FRAMEWORK16_THEME=~/.config/omarchy/current/theme/keyboard.rgb
+FRAMEWORK16_THEME=$HOME/.local/state/omarchy/current/theme/keyboard.rgb

 if omarchy-cmd-present qmk_hid && [[ -f $FRAMEWORK16_THEME ]]; then
  hex=$(cat "$FRAMEWORK16_THEME")
@@ -3,7 +3,7 @@
 # omarchy:summary=Sync Omarchy theme to all Obsidian vaults
 # omarchy:hidden=true

-CURRENT_THEME_DIR="$HOME/.config/omarchy/current/theme"
+CURRENT_THEME_DIR="$HOME/.local/state/omarchy/current/theme"

 [[ -f $CURRENT_THEME_DIR/obsidian.css ]] || exit 0

@@ -6,7 +6,7 @@

 set -euo pipefail

-CURRENT_THEME_PATH="$HOME/.config/omarchy/current/theme"
+CURRENT_THEME_PATH="$HOME/.local/state/omarchy/current/theme"
 PI_SOURCE_PATH="$CURRENT_THEME_PATH/pi.json"
 PI_AGENT_DIR="$HOME/.pi/agent"
 PI_THEME_DIR="$PI_AGENT_DIR/themes"
@@ -5,7 +5,7 @@

 TEMPLATES_DIR="$OMARCHY_PATH/default/themed"
 USER_TEMPLATES_DIR="$HOME/.config/omarchy/themed"
-NEXT_THEME_DIR="$HOME/.config/omarchy/current/next-theme"
+NEXT_THEME_DIR="$HOME/.local/state/omarchy/current/next-theme"
 COLORS_FILE="$NEXT_THEME_DIR/colors.toml"

 declare -A THEME_COLORS
@@ -382,8 +382,8 @@ resolve_theme_mode() {

  if [[ -f $NEXT_THEME_DIR/light.mode ]]; then
    THEME_COLORS[mode]="light"
-  elif [[ ${THEME_COLORS[background]} =~ ^#[0-9A-Fa-f]{6}$ ]]; then
-    bg_hex="${THEME_COLORS[background]#\#}"
+  elif [[ ${THEME_COLORS[bg]} =~ ^#[0-9A-Fa-f]{6}$ ]]; then
+    bg_hex="${THEME_COLORS[bg]#\#}"
    lum=$(( $(printf "%d" "0x${bg_hex:0:2}") + $(printf "%d" "0x${bg_hex:2:2}") + $(printf "%d" "0x${bg_hex:4:2}") ))
    (( lum > 382 )) && THEME_COLORS[mode]="light" || THEME_COLORS[mode]="dark"
  else
@@ -407,10 +407,20 @@ if [[ -f $COLORS_FILE ]]; then
    THEME_COLORS[$key]="$value"
  done <"$COLORS_FILE"

-  # Legacy compatibility: map ANSI color0..color15 and raw bg/fg to semantic names
+  # Canonical palette keys are bg/fg. Preserve older themes that still define
+  # background/foreground by treating those semantic values as the source of
+  # truth, then expose the old names as template aliases for user templates.
+  [[ ${THEME_COLORS[background]} ]] && THEME_COLORS[bg]="${THEME_COLORS[background]}"
+  [[ ${THEME_COLORS[foreground]} ]] && THEME_COLORS[fg]="${THEME_COLORS[foreground]}"
+  [[ ${THEME_COLORS[bg]} ]] || THEME_COLORS[bg]="${THEME_COLORS[color0]}"
+  [[ ${THEME_COLORS[fg]} ]] || THEME_COLORS[fg]="${THEME_COLORS[color7]}"
+  [[ ${THEME_COLORS[bg]} ]] && THEME_COLORS[background]="${THEME_COLORS[bg]}"
+  [[ ${THEME_COLORS[fg]} ]] && THEME_COLORS[foreground]="${THEME_COLORS[fg]}"
+  [[ ${THEME_COLORS[bg]} ]] && THEME_COLORS[color0]="${THEME_COLORS[bg]}"
+  [[ ${THEME_COLORS[fg]} ]] && THEME_COLORS[color7]="${THEME_COLORS[fg]}"
+
+  # Legacy compatibility: map ANSI color0..color15 to semantic names.
  declare -A legacy_alias=(
-    [bg]=background
-    [fg]=foreground
    [red]=color1
    [green]=color2
    [yellow]=color3
@@ -430,18 +440,21 @@ if [[ -f $COLORS_FILE ]]; then
  alias_theme_color magenta purple
  alias_theme_color bright_magenta bright_purple

-  [[ ${THEME_COLORS[light_fg]} ]]   || THEME_COLORS[light_fg]="${THEME_COLORS[color7]:-${THEME_COLORS[foreground]}}"
-  [[ ${THEME_COLORS[bright_fg]} ]]  || THEME_COLORS[bright_fg]="${THEME_COLORS[color15]:-${THEME_COLORS[foreground]}}"
-  [[ ${THEME_COLORS[lighter_bg]} ]] || THEME_COLORS[lighter_bg]="${THEME_COLORS[color0]:-${THEME_COLORS[background]}}"
-  [[ ${THEME_COLORS[dark_fg]} ]]    || THEME_COLORS[dark_fg]="${THEME_COLORS[color8]:-${THEME_COLORS[foreground]}}"
+  [[ ${THEME_COLORS[light_fg]} ]]   || THEME_COLORS[light_fg]="${THEME_COLORS[color7]:-${THEME_COLORS[fg]}}"
+  [[ ${THEME_COLORS[bright_fg]} ]]  || THEME_COLORS[bright_fg]="${THEME_COLORS[color15]:-${THEME_COLORS[fg]}}"
+  THEME_COLORS[cursor]="${THEME_COLORS[bright_fg]}"
+  [[ ${THEME_COLORS[lighter_bg]} ]] || THEME_COLORS[lighter_bg]="${THEME_COLORS[color0]:-${THEME_COLORS[bg]}}"
+  [[ ${THEME_COLORS[dark_fg]} ]]    || THEME_COLORS[dark_fg]="${THEME_COLORS[color8]:-${THEME_COLORS[fg]}}"
  [[ ${THEME_COLORS[muted]} ]]      || THEME_COLORS[muted]="${THEME_COLORS[color8]:-${THEME_COLORS[dark_fg]}}"
-  [[ ${THEME_COLORS[selection]} ]]  || THEME_COLORS[selection]="${THEME_COLORS[selection_background]:-${THEME_COLORS[color8]:-${THEME_COLORS[color0]}}}"
-  [[ ${THEME_COLORS[orange]} ]]     || THEME_COLORS[orange]="${THEME_COLORS[yellow]}"
+  [[ ${THEME_COLORS[selection]} ]]            || THEME_COLORS[selection]="${THEME_COLORS[selection_background]:-${THEME_COLORS[color8]:-${THEME_COLORS[color0]:-${THEME_COLORS[bg]}}}}"
+  [[ ${THEME_COLORS[selection_background]} ]] || THEME_COLORS[selection_background]="${THEME_COLORS[selection]}"
+  [[ ${THEME_COLORS[selection_foreground]} ]] || THEME_COLORS[selection_foreground]="${THEME_COLORS[bright_fg]}"
+  [[ ${THEME_COLORS[orange]} ]]               || THEME_COLORS[orange]="${THEME_COLORS[yellow]}"
  [[ ${THEME_COLORS[brown]} ]]      || THEME_COLORS[brown]=$(mix_color "${THEME_COLORS[orange]}" "#000000" 50%)

  # Auto-derive shades from base accents when not defined and not aliased from colorN
-  [[ ${THEME_COLORS[dark_bg]} ]]       || THEME_COLORS[dark_bg]=$(mix_color "${THEME_COLORS[background]}" "#000000" 25%)
-  [[ ${THEME_COLORS[darker_bg]} ]]     || THEME_COLORS[darker_bg]=$(mix_color "${THEME_COLORS[background]}" "#000000" 50%)
+  [[ ${THEME_COLORS[dark_bg]} ]]       || THEME_COLORS[dark_bg]=$(mix_color "${THEME_COLORS[bg]}" "#000000" 25%)
+  [[ ${THEME_COLORS[darker_bg]} ]]     || THEME_COLORS[darker_bg]=$(mix_color "${THEME_COLORS[bg]}" "#000000" 50%)
  [[ ${THEME_COLORS[bright_red]} ]]    || THEME_COLORS[bright_red]=$(mix_color "${THEME_COLORS[red]}" "#ffffff" 20%)
  [[ ${THEME_COLORS[bright_yellow]} ]] || THEME_COLORS[bright_yellow]=$(mix_color "${THEME_COLORS[yellow]}" "#ffffff" 20%)
  [[ ${THEME_COLORS[bright_green]} ]]  || THEME_COLORS[bright_green]=$(mix_color "${THEME_COLORS[green]}" "#ffffff" 20%)
@@ -3,7 +3,7 @@
 # omarchy:summary=Sync current Omarchy theme environment into tmux
 # omarchy:hidden=true

-CURRENT_THEME_PATH="$HOME/.config/omarchy/current/theme"
+CURRENT_THEME_PATH="$HOME/.local/state/omarchy/current/theme"
 GUM_ENV="$CURRENT_THEME_PATH/gum_env.lua"
 COLORS_TOML="$CURRENT_THEME_PATH/colors.toml"

@@ -54,21 +54,31 @@ theme_osc_sequences() {

 theme_color() {
  local key="$1"
+  local fallback="${2:-}"
+
+  awk -F= -v key="$key" -v fallback="$fallback" '
+    function clean(raw) {
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", raw)
+      if (raw ~ /^"/) {
+        sub(/^"/, "", raw)
+        sub(/".*$/, "", raw)
+      }
+      return raw
+    }

-  awk -F= -v key="$key" '
    {
      field = $1
      gsub(/^[[:space:]]+|[[:space:]]+$/, "", field)
      if (field == key) {
-        value = $2
-        gsub(/^[[:space:]]+|[[:space:]]+$/, "", value)
-        if (value ~ /^"/) {
-          sub(/^"/, "", value)
-          sub(/".*$/, "", value)
-        }
-        print value
+        print clean($2)
+        found = 1
        exit
      }
+      if (fallback != "" && field == fallback) fallback_value = clean($2)
+    }
+
+    END {
+      if (!found && fallback_value != "") print fallback_value
    }
  ' "$COLORS_TOML"
 }
@@ -78,8 +88,8 @@ sync_tmux_window_style() {

  [[ -f $COLORS_TOML ]] || return

-  foreground=$(theme_color foreground)
-  background=$(theme_color background)
+  foreground=$(theme_color foreground fg)
+  background=$(theme_color background bg)

  [[ -n $foreground && -n $background ]] || return

@@ -3,8 +3,8 @@
 # omarchy:summary=Sync Omarchy theme to VS Code, VSCodium, and Cursor
 # omarchy:hidden=true

-VS_CODE_THEME_DESCRIPTOR="$HOME/.config/omarchy/current/theme/vscode.json"
-GENERATED_THEME="$HOME/.config/omarchy/current/theme/vscode-theme.json"
+VS_CODE_THEME_DESCRIPTOR="$HOME/.local/state/omarchy/current/theme/vscode.json"
+GENERATED_THEME="$HOME/.local/state/omarchy/current/theme/vscode-theme.json"
 GENERATED_EXTENSION_NAME="omarchy-theme"
 GENERATED_EXTENSION_ID="local.$GENERATED_EXTENSION_NAME"
 GENERATED_EXTENSION_VERSION="1.0.0"
@@ -102,7 +102,7 @@ if [[ ! -f $fast_signature_file ]] || ! cmp -s "$fast_signature_file" <(printf '
  printf '%s' "$fast_signature" >"$fast_signature_file"
 fi

-current_theme=$(cat "$HOME/.config/omarchy/current/theme.name" 2>/dev/null)
+current_theme=$(cat "$HOME/.local/state/omarchy/current/theme.name" 2>/dev/null)
 selected_preview=""
 for extension in png jpg jpeg webp gif bmp; do
  if [[ -e $preview_dir/$current_theme.$extension ]]; then
@@ -1,40 +1,76 @@
 #!/bin/bash

 # omarchy:summary=Create a desktop launcher for a terminal UI app
-# omarchy:args=[name command window-style icon-url]
+# omarchy:args=[name command window-style icon-url-or-name]

 set -e

+ICON_DIR="$HOME/.local/share/icons/hicolor/256x256/apps"
+
+safe_icon_name() {
+  printf '%s\n' "$1" \
+    | tr '[:upper:]' '[:lower:]' \
+    | sed 's/[^[:alnum:]]\+/-/g; s/^-//; s/-$//'
+}
+
+icon_name_from_ref() {
+  local ref="$1"
+  local name
+  name=$(basename "$ref")
+
+  if [[ $name == *.* ]]; then
+    safe_icon_name "${name%.*}"
+  else
+    printf '%s\n' "$name"
+  fi
+}
+
+install_user_icon() {
+  local source="$1"
+  local name="$2"
+  local ext="${source##*.}"
+
+  [[ $ext == "$source" ]] && ext="png"
+  mkdir -p "$ICON_DIR"
+  cp "$source" "$ICON_DIR/$name.$ext"
+  gtk-update-icon-cache "$HOME/.local/share/icons/hicolor" &>/dev/null || true
+  printf '%s\n' "$name"
+}
+
 if (( $# != 4 )); then
  echo -e "\e[32mLet's create a TUI shortcut you can start with the app launcher.\n\e[0m"
  APP_NAME=$(gum input --prompt "Name> " --placeholder "My TUI")
  APP_EXEC=$(gum input --prompt "Launch Command> " --placeholder "lazydocker or bash -c 'dust; read -n 1 -s'")
  WINDOW_STYLE=$(gum choose --header "Window style" float tile)
-  ICON_URL=$(gum input --prompt "Icon URL> " --placeholder "See https://dashboardicons.com (must use PNG or SVG!)")
+  ICON_REF=$(gum input --prompt "Icon URL/name> " --placeholder "See https://dashboardicons.com or enter an installed icon name")
 else
  APP_NAME="$1"
  APP_EXEC="$2"
  WINDOW_STYLE="$3"
-  ICON_URL="$4"
+  ICON_REF="$4"
 fi

-if [[ -z $APP_NAME || -z $APP_EXEC || -z $ICON_URL ]]; then
-  echo "You must set app name, app command, and icon URL!"
+if [[ -z $APP_NAME || -z $APP_EXEC || -z $ICON_REF ]]; then
+  echo "You must set app name, app command, and icon URL/name!"
  exit 1
 fi

-ICON_DIR="$HOME/.local/share/applications/icons"
 DESKTOP_FILE="$HOME/.local/share/applications/$APP_NAME.desktop"
+mkdir -p "$(dirname "$DESKTOP_FILE")"

-if [[ ! $ICON_URL =~ ^https?:// ]] && [[ -f $ICON_URL ]]; then
-  ICON_PATH="$ICON_URL"
-else
-  ICON_PATH="$ICON_DIR/$APP_NAME.png"
+if [[ $ICON_REF =~ ^https?:// ]]; then
+  ICON_VALUE=$(safe_icon_name "$APP_NAME")
  mkdir -p "$ICON_DIR"
-  if ! curl -sL -o "$ICON_PATH" "$ICON_URL"; then
+  if ! curl -sL -o "$ICON_DIR/$ICON_VALUE.png" "$ICON_REF"; then
    echo "Error: Failed to download icon."
    exit 1
  fi
+  gtk-update-icon-cache "$HOME/.local/share/icons/hicolor" &>/dev/null || true
+elif [[ -f $ICON_REF ]]; then
+  ICON_VALUE=$(install_user_icon "$ICON_REF" "$(safe_icon_name "$APP_NAME")")
+else
+  # Bundled Omarchy icons are package-owned under /usr/share/icons/hicolor.
+  ICON_VALUE=$(icon_name_from_ref "$ICON_REF")
 fi

 if [[ $WINDOW_STYLE == "float" ]]; then
@@ -51,7 +87,7 @@ Comment=$APP_NAME
 Exec=xdg-terminal-exec --app-id=$APP_CLASS -e $APP_EXEC
 Terminal=false
 Type=Application
-Icon=$ICON_PATH
+Icon=$ICON_VALUE
 StartupNotify=true
 EOF

--- a/Show More
+++ b/Show More