Merge remote-tracking branch 'refs/remotes/portfolio/quattro' into codex/portfolio-9457-20260907

.github/ISSUE_TEMPLATE/config.yml

@@ -1,7 +1,7 @@
 blank_issues_enabled: false
 contact_links:
   - name: Suggestion
-    url: https://github.com/basecamp/omarchy/discussions/categories/suggestions
+    url: https://github.com/omacom/omarchy/discussions/categories/suggestions
     about: Suggest a new feature, change to existing feature, or other ideas in Discussions.
   - name: Support
     url: https://omarchy.org/discord

README.md

@@ -1,6 +1,6 @@
 # Omarchy
 
-Omarchy is a beautiful, modern & opinionated Linux distribution by DHH.
+Omarchy is a beautiful, fun & agentic Linux distribution by DHH.
 
 Read more at [omarchy.org](https://omarchy.org).
 

agents/skills/migrations.md

@@ -163,6 +163,8 @@ rm ~/.local/state/omarchy/migrations/<migration>.sh
 omarchy-migrate
 ```
 
+Keep a dedicated test while the migration is still being written or bugfixed, if it calls an Omarchy helper whose interface can still change, or if it is a security-sensitive privileged repair (FIDO2, leftover installer artifacts, udev, sshd). Once a one-shot rewrite has shipped in a tagged release and is frozen, drop the test even when that rewrite used sudo, pacman, or limine-mkinitcpio. Keep the migration itself for late-updaters. Tests of `omarchy-migrate`, the login notifier, and `omarchy-upgrade-to-quattro` stay.
+
 Omarchy 4.0 is upgraded through `bin/omarchy-upgrade-to-quattro`, 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.

agents/skills/shell-dev.md

@@ -20,9 +20,7 @@ Run `omarchy-restart-shell` after making changes to QML files.
   [`docs/omarchy-shell.md`](../../docs/omarchy-shell.md) and
   `shell/services/PluginRegistry.qml` for the current contract; fields such as
   `activation` are optional.
-- Entry-point QML files are `Item`s (not `ShellRoot`), and accept the
-  shell-injected properties `omarchyPath`, `shell`, `manifest`, and
-  `pluginRegistry` / `barWidgetRegistry` as appropriate.
+- Entry-point QML files are `Item`s (not `ShellRoot`), and accept the shell-injected properties `omarchyPath`, `shell`, `manifest`, and `pluginRegistry` / `barWidgetRegistry` as appropriate. First-party plugins receive the host objects. Third-party plugins receive capability-scoped facades: ordinary plugins may look up and control only their own service and lifecycle, built-in clones retain narrow source-specific configuration and UI compatibility, menu plugins receive an application-library facade, and plugins can read detached scalar bar state; full-bar plugins additionally receive detached bar configuration and widget-catalog snapshots, narrow proxies for the non-authentication services used by built-in bar widgets, and lifecycle control over configured non-authentication UI plugins. Authentication capabilities must be stamped from trusted first-party manifests, and third-party registry views and bar configuration must be detached snapshots rather than shared objects. These facades reduce accidental authority but are not a same-process QML sandbox: a visual bar widget can walk its parent hierarchy to ordinary host objects. Authentication services must therefore remain outside both `ShellRoot._services` and the host QObject tree. Do not expose authentication services through new third-party-facing properties.
 - Panel / overlay / menu plugins must expose `open(payloadJson)` and
   `close()` lifecycle methods for `shell summon` and `shell hide`.
 

bin/omarchy

@@ -65,6 +65,7 @@ GROUP_DESCRIPTIONS[monitor]="Monitor status helpers"
 GROUP_DESCRIPTIONS[network]="Network status helpers"
 GROUP_DESCRIPTIONS[notification]="Notification helpers"
 GROUP_DESCRIPTIONS[mise]="Mise tool wrappers"
+GROUP_DESCRIPTIONS[openclaw]="OpenClaw agent platform setup"
 GROUP_DESCRIPTIONS[osd]="On-screen display status helpers"
 GROUP_DESCRIPTIONS[pkg]="Package management helpers"
 GROUP_DESCRIPTIONS[plugin]="Omarchy shell plugin and bar widget management"

bin/omarchy-agent

@@ -82,10 +82,39 @@ grok)
   command=(grok --permission-mode bypassPermissions)
   [[ -n ${prompt:-} ]] && command+=(-- "$prompt")
   ;;
+openclaw)
+  # The launcher owns onboarding and the gateway dance: OpenClaw's terminal UI
+  # must attach to the running gateway (the embedded `openclaw chat` refuses to
+  # start while the gateway owns the state directory). It has no permission
+  # prompts to skip, and --message seeds the session while keeping it
+  # interactive.
+  command=(omarchy-launch-openclaw --tui)
+  [[ -n ${prompt:-} ]] && command+=(--message "$prompt")
+  ;;
 codex)
   command=(codex --approve-for-me)
   [[ -n ${prompt:-} ]] && command+=(-- "$prompt")
   ;;
+cursor-agent)
+  # --yolo covers commands only; the workspace trust dialog has its own flag.
+  # A one-word prompt naming a subcommand (update, login, help) still runs that
+  # subcommand after a bare --, so the agent subcommand is named outright, and
+  # -- after it keeps a prompt starting with a dash from being read as an option.
+  command=(cursor-agent --yolo --trust)
+  [[ -n ${prompt:-} ]] && command+=(agent -- "$prompt")
+  ;;
+hermes)
+  if [[ -n ${prompt:-} ]]; then
+    command=(env -u HERMES_SESSION_SOURCE hermes chat --yolo --tui "--query=$prompt")
+  else
+    command=(hermes --yolo)
+  fi
+  ;;
+muse)
+  # --approval-mode never skips the tool prompts but keeps Muse's own sandbox.
+  command=(muse --approval-mode never)
+  [[ -n ${prompt:-} ]] && command+=(-- "$prompt")
+  ;;
 omp)
   command=(omp --auto-approve)
   [[ -n ${prompt:-} ]] && command+=(-- "$prompt")

bin/omarchy-apply-lock

@@ -6,6 +6,12 @@
 
 set -e
 
+# Install and upgrade callers can start this helper as root. Ignore their PATH
+# so optional commands never fall through to a user-writable directory.
+if (( EUID == 0 )); then
+  export PATH=/usr/share/omarchy/bin:/usr/local/bin:/usr/bin:/bin
+fi
+
 target_user=${OMARCHY_INSTALL_USER:-${SUDO_USER:-}}
 if [[ -z $target_user && -n ${PKEXEC_UID:-} ]]; then
   target_user=$(getent passwd "$PKEXEC_UID" | cut -d: -f1)
@@ -34,7 +40,8 @@ auth       required                    pam_faillock.so authsucc
 account    include                     system-local-login
 EOF
 
-if omarchy-cmd-present fprintd-list && fprintd-list "$target_user" 2>/dev/null | grep -qi finger; then
+if [[ -x /usr/bin/fprintd-list ]] &&
+  /usr/bin/fprintd-list "$target_user" 2>/dev/null | grep -qi finger; then
   echo "Configuring lock screen fingerprint authentication..."
   as_root tee /etc/pam.d/omarchy-lock-fingerprint >/dev/null <<'EOF'
 #%PAM-1.0

bin/omarchy-bar-text-color

@@ -109,7 +109,10 @@ right)
   ;;
 esac
 
-pixel=$(magick "$background_path" -auto-orient \
+# Sample the first frame only. Without the selector a video background makes
+# ImageMagick decode the whole file and emit one value per frame, and the match
+# below then fails into the fallback colour.
+pixel=$(magick "$background_path[0]" -auto-orient \
   -resize "${screen_width}x${screen_height}^" \
   -gravity center -extent "${screen_width}x${screen_height}" \
   -gravity NorthWest -crop "$crop" +repage \

bin/omarchy-default-agent

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # omarchy:summary=Set and launch the default coding agent
-# omarchy:args=[pi|omp|opencode|ori|claude|codex|grok|agy|copilot|crush]
+# omarchy:args=[pi|omp|opencode|ori|claude|codex|grok|openclaw|agy|hermes|copilot|crush|cursor-agent|muse]
 # omarchy:examples=omarchy default agent | omarchy default agent codex | omarchy default agent claude
 
 installing=false
@@ -32,21 +32,52 @@ claude | claude-code) agent="claude"; name="Claude Code" ;;
 codex) agent="codex"; name="Codex" ;;
 crush) agent="crush"; name="Crush" ;;
 grok) agent="grok"; name="Grok"; agent_package="npm:@xai-official/grok" ;;
+openclaw) agent="openclaw"; name="OpenClaw"; agent_installer="omarchy-install-openclaw-cli" ;;
 agy | antigravity | antigravity-cli | gemini | gemini-cli) agent="agy"; name="Antigravity"; agent_package="antigravity-cli" ;;
+hermes) agent="hermes"; name="Hermes"; agent_installer="omarchy-install-hermes-cli" ;;
 copilot | github-copilot) agent="copilot"; name="GitHub Copilot" ;;
+muse | muse-code | musecode)
+  agent="muse"; name="Muse Code"
+  # Meta's launcher verifies and updates the native binary for this platform.
+  agent_package="http:muse[url=https://api.meta.ai/muse-launcher.sh,bin=muse,version_list_url=https://api.meta.ai/muse-code/channels/muse-stable,version_json_path=.version]"
+  ;;
+cursor | cursor-agent) agent="cursor-agent"; name="Cursor CLI" ;;
 *)
-  echo "Usage: omarchy-default-agent <pi|omp|opencode|ori|claude|codex|grok|agy|copilot|crush>"
+  echo "Usage: omarchy-default-agent <pi|omp|opencode|ori|claude|codex|grok|openclaw|agy|hermes|copilot|crush|cursor-agent|muse>"
   exit 1
   ;;
 esac
 
 agent_package=${agent_package:-$agent}
 
-if [[ $installing == "false" ]] && ! mise where "$agent_package" &>/dev/null; then
+# Hermes reaches mise through its own installer rather than straight from
+# here: it needs its interpreter pinned, and a bare `mise use` has nowhere to
+# say so. See omarchy-install-hermes-cli. OpenClaw comes from its pacman
+# package the same way; see omarchy-install-openclaw-cli.
+if [[ -n ${agent_installer:-} ]]; then
+  # Not omarchy-cmd-present: the stub is on PATH from first boot and says
+  # nothing about whether Hermes is installed behind it. Treating a cold stub
+  # as installed skips the floating terminal and runs the minute-long install
+  # inside the menu action instead.
+  agent_present() { "$agent_installer" --check; }
+  agent_install() { "$agent_installer" --now; }
+else
+  # Anything at the wrapper's path other than the wrapper is the user's own
+  # install, such as the symlink Cursor's installer leaves. A mise copy would
+  # only shadow it, since the mise shims precede ~/.local/bin on PATH.
+  user_install() {
+    [[ -x $HOME/.local/bin/$agent ]] &&
+      { [[ -L $HOME/.local/bin/$agent ]] || ! grep -q '^mise use -g' "$HOME/.local/bin/$agent"; }
+  }
+  agent_present() { user_install || mise where "$agent_package" &>/dev/null; }
+  agent_install() { user_install || mise use -g "$agent_package"; }
+fi
+
+if [[ $installing == "false" ]] && ! agent_present; then
   exec omarchy-launch-floating-terminal-with-presentation omarchy-default-agent --install "$agent"
 fi
 
-if ! mise use -g "$agent_package"; then
+if ! agent_install; then
   if [[ $installing == "true" ]]; then
     echo "Could not install $name with mise" >&2
   else

bin/omarchy-display-text-size

@@ -129,7 +129,8 @@ term_pt_for() {
     'BEGIN { printf "%d", int(s * p / b + 0.5) }'
 }
 
-# Set the font point size in every terminal config that exists. Family is left
+# Set the font point size in terminal configs, creating Kitty overrides when
+# it inherits its size from the system config. Family is left
 # untouched — that is omarchy-font-set's job. Live-reload signals mirror
 # omarchy-font-set; foot has no reload signal, so running instances are nudged.
 set_terminal_size() {
@@ -139,8 +140,13 @@ set_terminal_size() {
     sed -i -E "s/^size[[:space:]]*=.*/size = $pt/" ~/.config/alacritty/alacritty.toml
   fi
 
-  if [[ -f ~/.config/kitty/kitty.conf ]]; then
-    sed -i -E "s/^font_size[[:space:]]+.*/font_size $pt.0/" ~/.config/kitty/kitty.conf
+  if [[ -f ~/.config/kitty/kitty.conf ]] || omarchy-cmd-present kitty; then
+    mkdir -p ~/.config/kitty
+    if grep -qE '^[[:space:]]*font_size[[:space:]]+' ~/.config/kitty/kitty.conf 2>/dev/null; then
+      sed --follow-symlinks -i -E "s/^[[:space:]]*font_size[[:space:]]+.*/font_size $pt.0/" ~/.config/kitty/kitty.conf
+    else
+      printf '\nfont_size %s.0\n' "$pt" >>~/.config/kitty/kitty.conf
+    fi
     pkill -USR1 kitty 2>/dev/null || true
   fi
 
@@ -177,9 +183,13 @@ term_current_pt() {
   elif [[ -f ~/.config/alacritty/alacritty.toml ]]; then
     grep -oP '^size[[:space:]]*=[[:space:]]*\K[0-9.]+' ~/.config/alacritty/alacritty.toml | head -1
   elif [[ -f ~/.config/kitty/kitty.conf ]]; then
-    grep -oP '^font_size[[:space:]]+\K[0-9.]+' ~/.config/kitty/kitty.conf | head -1
+    local pt
+    pt=$(grep -oP '^[[:space:]]*font_size[[:space:]]+\K[0-9.]+' ~/.config/kitty/kitty.conf | tail -1)
+    echo "${pt:-$TERM_DEFAULT_PT}"
   elif [[ -f ~/.config/foot/foot.ini ]]; then
     grep -oP ':size=\K[0-9.]+' ~/.config/foot/foot.ini | head -1
+  elif omarchy-cmd-present kitty; then
+    echo "$TERM_DEFAULT_PT"
   fi
 }
 

bin/omarchy-font-set

@@ -30,8 +30,14 @@ if [[ -f ~/.config/alacritty/alacritty.toml ]]; then
   sed -i "s/family = \".*\"/family = \"$font_name\"/g" ~/.config/alacritty/alacritty.toml
 fi
 
-if [[ -f ~/.config/kitty/kitty.conf ]]; then
-  sed -i "s/^font_family .*/font_family $font_name/g" ~/.config/kitty/kitty.conf
+if [[ -f ~/.config/kitty/kitty.conf ]] || omarchy-cmd-present kitty; then
+  mkdir -p ~/.config/kitty
+  if grep -qE '^[[:space:]]*font_family[[:space:]]+' ~/.config/kitty/kitty.conf 2>/dev/null; then
+    kitty_font_name=$(printf '%s' "$font_name" | sed 's/[\\&/]/\\&/g')
+    sed --follow-symlinks -i -E "s/^[[:space:]]*font_family[[:space:]]+.*/font_family $kitty_font_name/" ~/.config/kitty/kitty.conf
+  else
+    printf '\nfont_family %s\n' "$font_name" >>~/.config/kitty/kitty.conf
+  fi
   pkill -USR1 kitty
 fi
 

bin/omarchy-hibernation-setup

@@ -30,6 +30,35 @@ MKINITCPIO_CONF="/etc/mkinitcpio.conf.d/omarchy_resume.conf"
 SWAP_FILE="/swap/swapfile"
 RESUME_DROP_IN="/etc/limine-entry-tool.d/resume.conf"
 
+install_root_file() {
+  local source="$1"
+  local destination="$2"
+  local mode="$3"
+  local stage
+
+  stage=$(sudo /usr/bin/mktemp -- "${destination%/*}/.${destination##*/}.omarchy.XXXXXX") || return 1
+  safe_stage_path "$stage" "$destination" || return 1
+
+  if sudo /usr/bin/install -m "$mode" -o root -g root -T "$source" "$stage" &&
+    sudo /usr/bin/mv -Tf -- "$stage" "$destination"; then
+    return 0
+  else
+    safe_stage_path "$stage" "$destination" && sudo /usr/bin/rm -f -- "$stage"
+    return 1
+  fi
+}
+
+safe_stage_path() {
+  local stage="$1"
+  local destination="$2"
+  local prefix suffix
+
+  prefix="${destination%/*}/.${destination##*/}.omarchy."
+  [[ $stage == "$prefix"* ]] || return 1
+  suffix=${stage#"$prefix"}
+  [[ $suffix =~ ^[[:alnum:]]{6}$ ]]
+}
+
 # Check if hibernation is already configured
 if [[ -f $MKINITCPIO_CONF ]] && grep -q "^HOOKS+=(resume)$" "$MKINITCPIO_CONF"; then
   # Fix empty resume_offset if btrfs map-swapfile failed during initial setup
@@ -83,14 +112,20 @@ if ! swapon --show | grep -q "$SWAP_FILE"; then
   sudo swapon -p 0 "$SWAP_FILE"
 fi
 
+# Ensure keyboard backlight doesn't prevent sleep
+# Install this before writing the resume marker so a failed install remains
+# retryable through the normal setup command.
+if ! install_root_file "$OMARCHY_PATH/default/systemd/system-sleep/keyboard-backlight" \
+  /usr/lib/systemd/system-sleep/keyboard-backlight 0755; then
+  echo "Could not install the keyboard-backlight system-sleep hook" >&2
+  exit 1
+fi
+
 # Add resume hook to mkinitcpio
 sudo mkdir -p /etc/mkinitcpio.conf.d
 echo "Adding resume hook to $MKINITCPIO_CONF"
 echo "HOOKS+=(resume)" | sudo tee "$MKINITCPIO_CONF" >/dev/null
 
-# Ensure keyboard backlight doesn't prevent sleep
-sudo cp -p "$OMARCHY_PATH/default/systemd/system-sleep/keyboard-backlight" /usr/lib/systemd/system-sleep/
-
 # Add resume= kernel parameters so the initramfs resume hook knows where to find the
 # hibernation image. Without these, resume happens late (after GPU drivers load) and fails.
 if [[ ! -f $RESUME_DROP_IN ]]; then

bin/omarchy-install-ai-hermes

@@ -0,0 +1,159 @@
+#!/bin/bash
+
+# omarchy:summary=Install the Hermes desktop app
+# omarchy:requires-sudo=true
+
+set -e
+
+if (( EUID == 0 )); then
+  echo "Run this command as your desktop user, without sudo." >&2
+  exit 1
+fi
+
+echo "Installing Hermes Desktop..."
+omarchy-pkg-add hermes-desktop
+
+if [[ ! -r /usr/share/hermes-desktop/install.sh || ! -r /usr/share/hermes-desktop/runtime.patch ]] ||
+  ! release_commit=$(jq -er 'select(.branch == "main") | .commit | select(test("^[0-9a-f]{40}$"))' /opt/hermes-desktop/resources/install-stamp.json 2>/dev/null); then
+  echo "The installed Hermes package cannot prepare in-app updates. Run 'omarchy update', then try again." >&2
+  exit 1
+fi
+
+# If Hermes was already installed for the terminal, the app supersedes it: one
+# machine, one Hermes. This drops that copy so the terminal, the default agent
+# and the app all end up on the app's installation.
+omarchy-install-hermes-cli || true
+
+# Keep the runtime at the root even when invoked from a Hermes profile.
+HERMES_HOME=$(realpath -ms -- "${HERMES_HOME:-$HOME/.hermes}")
+home_parent=$(dirname -- "$HERMES_HOME")
+if [[ ${home_parent##*/} == [Pp][Rr][Oo][Ff][Ii][Ll][Ee][Ss] ]]; then
+  HERMES_HOME=$(dirname -- "$home_parent")
+fi
+export HERMES_HOME
+
+runtime="$HERMES_HOME/hermes-agent"
+native_app="$runtime/apps/desktop/release/linux-unpacked"
+
+runtime_ready() {
+  [[ -f $runtime/.hermes-bootstrap-complete && -f $runtime/venv/bin/hermes && -x $runtime/venv/bin/hermes && -f $runtime/venv/bin/python && -x $runtime/venv/bin/python ]] &&
+    timeout 15 "$runtime/venv/bin/hermes" --version >/dev/null 2>&1
+}
+
+check_main() {
+  local main_commit
+  main_commit=$(git -C "$runtime" rev-parse --verify refs/heads/main 2>/dev/null || true)
+  if [[ -n $main_commit && $main_commit != "$release_commit" && $main_commit != "$(git -C "$runtime" rev-parse --verify refs/remotes/origin/main 2>/dev/null)" ]]; then
+    echo "Hermes main has local commits. Keep that work and prepare the desktop with 'hermes desktop --build-only'." >&2
+    return 1
+  fi
+}
+
+if ! runtime_ready; then
+  # The upstream installer can reset an existing checkout. Do not pin a newer
+  # or modified runtime back to the package release while repairing setup.
+  if [[ -e $runtime || -L $runtime ]]; then
+    if [[ $(git -C "$runtime" rev-parse HEAD 2>/dev/null) != "$release_commit" ]] ||
+      [[ -n $(git -C "$runtime" status --porcelain --untracked-files=all) ]]; then
+      echo "Hermes setup is incomplete at $runtime. Repair that installation before trying again; existing files have been kept." >&2
+      exit 1
+    fi
+    check_main
+  fi
+
+  # Upstream replaces these commands, including foreign files and symlinks.
+  # Keep their original bytes/links before handing the names to the desktop.
+  command_backup=""
+  for command in hermes hermes-agent hermes-acp; do
+    command_path="$HOME/.local/bin/$command"
+    if [[ -e $command_path || -L $command_path ]]; then
+      if [[ ! -f $command_path && ! -L $command_path ]]; then
+        echo "Cannot replace $command_path: move it aside before installing Hermes Desktop." >&2
+        exit 1
+      fi
+      if [[ -z $command_backup ]]; then
+        command_backup=$(mktemp -d "$HOME/.local/bin/.hermes-before-desktop.XXXXXX")
+        echo "Saving existing Hermes commands in $command_backup"
+      fi
+      cp -a -- "$command_path" "$command_backup/"
+    fi
+  done
+
+  echo "Setting up the Hermes runtime..."
+  bash /usr/share/hermes-desktop/install.sh --skip-setup --branch main --commit "$release_commit" --force-commit --dir "$runtime" --hermes-home "$HERMES_HOME"
+  if ! runtime_ready; then
+    echo "Hermes runtime setup did not complete. Re-run this command after resolving the installer error." >&2
+    exit 1
+  fi
+fi
+
+runtime_commit=$(git -C "$runtime" rev-parse HEAD)
+if [[ $runtime_commit == "$release_commit" ]]; then
+  # The updater switches to main before checking for changes. Start main at
+  # the packaged release, with enough history for its first fast-forward.
+  check_main
+  if [[ $(git -C "$runtime" rev-parse --is-shallow-repository) == "true" ]]; then
+    git -C "$runtime" fetch --unshallow origin main
+  fi
+  git -C "$runtime" switch -C main "$release_commit"
+
+  if git -C "$runtime" apply --check /usr/share/hermes-desktop/runtime.patch >/dev/null 2>&1; then
+    git -C "$runtime" apply /usr/share/hermes-desktop/runtime.patch
+  elif ! git -C "$runtime" apply --reverse --check /usr/share/hermes-desktop/runtime.patch >/dev/null 2>&1; then
+    echo "The Hermes Linux runtime patch conflicts with local changes. Existing files have been kept." >&2
+    exit 1
+  fi
+fi
+
+if [[ -e $native_app || -L $native_app ]]; then
+  if [[ ! -f $native_app/Hermes || ! -x $native_app/Hermes || ! -f $native_app/resources/app.asar || ! -f $native_app/resources/install-stamp.json ]]; then
+    echo "The Hermes desktop app at $native_app is incomplete. Repair it with 'hermes desktop --build-only' before trying again." >&2
+    exit 1
+  fi
+else
+  if [[ $runtime_commit != "$release_commit" ]]; then
+    echo "The Hermes runtime has moved beyond the packaged desktop release. Run 'hermes desktop --build-only', then try again." >&2
+    exit 1
+  fi
+  desktop_changes=$(git -C "$runtime" status --porcelain --untracked-files=all -- apps/desktop package.json package-lock.json)
+  if [[ -n $desktop_changes ]]; then
+    echo "Hermes desktop sources have local changes. Run 'hermes desktop --build-only', then try again; existing files have been kept." >&2
+    exit 1
+  fi
+
+  mkdir -p -- "${native_app%/*}"
+  staging=$(mktemp -d "${native_app%/*}/.linux-unpacked.XXXXXX")
+  trap 'rm -rf -- "$staging"' EXIT
+  cp -a /opt/hermes-desktop/. "$staging/"
+  chmod 0755 "$staging/chrome-sandbox"
+  mv -T --no-clobber -- "$staging" "$native_app"
+  if [[ -e $staging ]]; then
+    echo "A Hermes desktop app appeared during setup. It has been kept; please try again." >&2
+    exit 1
+  fi
+  trap - EXIT
+
+  # Record this matching prebuilt app using the CLI's own content hash, so
+  # subsequent menu launches do not rebuild an app that is already current.
+  env -u PYTHONPATH -u PYTHONHOME "$runtime/venv/bin/python" - "$runtime" <<'PY'
+import sys
+from pathlib import Path
+
+sys.path.insert(0, sys.argv[1])
+from hermes_cli.main import _write_desktop_build_stamp
+
+_write_desktop_build_stamp(Path(sys.argv[1]), source_mode=False)
+PY
+fi
+
+echo "Opening Hermes Desktop..."
+setsid uwsm-app -- /usr/bin/hermes-desktop >/dev/null 2>&1 &
+
+# Only a running Hermes can be told which skin to show; a unit outlives this
+# terminal and reports to the journal.
+echo "Matching Hermes to the current theme once it is set up..."
+systemctl --user stop omarchy-hermes-theme.service 2>/dev/null || true
+systemd-run --user --quiet --collect --unit=omarchy-hermes-theme omarchy-theme-set-hermes --wait
+
+echo ""
+echo "Hermes Desktop has been installed."

bin/omarchy-install-ai-openclaw

@@ -0,0 +1,35 @@
+#!/bin/bash
+
+# omarchy:summary=Install the OpenClaw agent platform and its Control UI web app
+# omarchy:requires-sudo=true
+
+set -e
+
+echo "Installing OpenClaw..."
+omarchy-pkg-add openclaw
+
+# The desktop app is OpenClaw's Control UI: a web app served by its own
+# gateway. The launcher entry goes through omarchy-launch-openclaw, which
+# onboards or starts that gateway before opening the window. The icon ships
+# inside the package, so nothing is fetched here.
+echo "Installing the OpenClaw web app..."
+omarchy-webapp-install OpenClaw "http://127.0.0.1:18789" \
+  /usr/lib/node_modules/openclaw/dist/control-ui/apple-touch-icon.png \
+  omarchy-launch-openclaw
+
+# A first install runs onboarding right here: launching the app instead would
+# open a second floating terminal for the wizard, identical to this one.
+# omarchy-openclaw-onboard runs the wizard the way this flow needs (terminal
+# prompts, gateway as a user service, and it actually returns). A machine
+# that is already onboarded goes straight to the app.
+if [[ -f $HOME/.openclaw/openclaw.json ]]; then
+  echo "Opening OpenClaw..."
+  setsid uwsm-app -- gtk-launch OpenClaw >/dev/null 2>&1 &
+elif omarchy-openclaw-onboard && [[ -f $HOME/.openclaw/openclaw.json ]]; then
+  echo "Opening OpenClaw..."
+  setsid uwsm-app -- gtk-launch OpenClaw >/dev/null 2>&1 &
+fi
+
+echo ""
+echo "OpenClaw has been installed."
+echo "If you skipped onboarding, launching OpenClaw from the app grid resumes it."

bin/omarchy-install-ai-t3-code

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+# omarchy:summary=Install T3 Code and point it at the Omarchy palette
+# omarchy:requires-sudo=true
+
+set -e
+
+T3CODE_HOME="${T3CODE_HOME:-$HOME/.t3}"
+T3CODE_STATE_DIR="$T3CODE_HOME/userdata"
+
+echo "Installing T3 Code..."
+omarchy-pkg-add t3code-bin
+
+echo "Matching T3 Code to the current theme..."
+mkdir -p "$T3CODE_STATE_DIR"
+
+# An updated user's current theme may have been staged before this template existed.
+if [[ ! -f $HOME/.local/state/omarchy/current/theme/t3code.json ]]; then
+  omarchy-theme-refresh
+fi
+
+omarchy-theme-set-t3code
+
+# The packaged CLI selects the published palette before the app's first launch.
+t3 theme set omarchy --base-dir "$T3CODE_HOME"
+
+echo "Opening T3 Code..."
+setsid uwsm-app -- gtk-launch t3code >/dev/null 2>&1 &
+
+echo ""
+echo "T3 Code has been installed."

bin/omarchy-install-chromium-copy-url

@@ -16,6 +16,9 @@ browser_dirs=(
   "$HOME/.config/BraveSoftware/Brave-Browser"
   "$HOME/.config/BraveSoftware/Brave-Browser-Beta"
   "$HOME/.config/BraveSoftware/Brave-Browser-Nightly"
+  "$HOME/.config/BraveSoftware/Brave-Origin"
+  "$HOME/.config/BraveSoftware/Brave-Origin-Beta"
+  "$HOME/.config/BraveSoftware/Brave-Origin-Nightly"
   "$HOME/.config/microsoft-edge"
   "$HOME/.config/microsoft-edge-dev"
 )

bin/omarchy-install-chromium-ytdlp

@@ -17,6 +17,9 @@ browser_dirs=(
   "$HOME/.config/BraveSoftware/Brave-Browser"
   "$HOME/.config/BraveSoftware/Brave-Browser-Beta"
   "$HOME/.config/BraveSoftware/Brave-Browser-Nightly"
+  "$HOME/.config/BraveSoftware/Brave-Origin"
+  "$HOME/.config/BraveSoftware/Brave-Origin-Beta"
+  "$HOME/.config/BraveSoftware/Brave-Origin-Nightly"
   "$HOME/.config/microsoft-edge"
   "$HOME/.config/microsoft-edge-dev"
 )

bin/omarchy-install-hermes-cli

@@ -0,0 +1,280 @@
+#!/bin/bash
+
+# omarchy:summary=Install the Hermes CLI as a mise-backed wrapper in ~/.local/bin
+# omarchy:args=[--check|--now|--owns|--remove]
+# omarchy:examples=omarchy install hermes cli | omarchy install hermes cli --now
+
+# Hermes pins every one of its dependencies exactly and declares
+# Requires-Python >=3.11,<3.14, so it can neither be built against Arch's
+# Python nor share the python-* packages. mise builds it a private environment
+# instead.
+#
+# It gets its own installer rather than a line in omarchy-mise-install because
+# of the interpreter pin. Given no compatible interpreter to hand, uv builds
+# the venv against the system Python in violation of Hermes' own bound,
+# reports success, and leaves the breakage to surface later inside a
+# dependency -- and omarchy-mise-install writes a fixed stub with nowhere to
+# say otherwise.
+#
+# There is only ever one Hermes on a machine. hermes-desktop cannot run against
+# this one -- it needs a runtime built from its own commit, and the version gap
+# fails its readiness probe -- so it installs its own under ~/.hermes and puts
+# that on PATH. When the package is present it therefore owns Hermes outright:
+# this installer stands aside and removes its own copy, so the terminal, the
+# default agent and the app are all the same installation.
+
+set -euo pipefail
+
+mode=${1:-}
+
+tool='pipx:hermes-agent[extras=all]'
+python='3.13'
+
+# The line that identifies the stub as this installer's; matched whole, so a
+# wrapper that merely mentions the command is not mistaken for ours.
+marker='# Written by omarchy-install-hermes-cli.'
+
+# The package, not the runtime directory: it is installed before the app has
+# ever run, and that is exactly when we must not start building a second copy.
+desktop_owns_hermes() {
+  omarchy-pkg-present hermes-desktop
+}
+
+# The venv appears at the python-deps stage, several stages before the one that
+# installs the command, so its presence says nothing about being usable. The
+# marker is written last, and the command is what the agent actually runs.
+desktop_hermes_ready() {
+  [[ -f $HOME/.hermes/hermes-agent/.hermes-bootstrap-complete ]] || return 1
+
+  # An executable of that name proves nothing about whose it is; the app's own
+  # points into ~/.hermes, and anything else is not the install we are asking
+  # about. Matched as a plain string, because the path carries a dot and an
+  # unanchored pattern would also claim a wrapper pointing at ~/xhermes.
+  [[ -f $HOME/.local/bin/hermes ]] || return 1
+  grep -qF "$HOME/.hermes" "$HOME/.local/bin/hermes" || return 1
+
+  # And a marker left behind by an install whose venv has since gone answers
+  # for nothing, so the command has to run, exactly as a foreign one must.
+  hermes_prompt_ready
+}
+
+# Whether Hermes is really installed, not merely whether the stub exists. A
+# stub on its own is cold: running it installs Hermes, which takes minutes.
+installed() {
+  [[ -d "$(mise where "$tool" 2>/dev/null)/hermes-agent/lib/python$python" ]]
+}
+
+# The stub is the only thing this installer owns. Anything else at that path
+# -- Hermes' official installer, a hand-rolled wrapper, even a dangling link
+# -- was put there by the user and is never deleted or overwritten here.
+# Symlinks count as foreign even when they resolve to a marked file: the stub
+# is written as a regular file, so a link is someone else's arrangement.
+ours() {
+  [[ -f $HOME/.local/bin/hermes && ! -L $HOME/.local/bin/hermes ]] &&
+    grep -qxF "$marker" "$HOME/.local/bin/hermes"
+}
+
+foreign_hermes() {
+  [[ -e $HOME/.local/bin/hermes || -L $HOME/.local/bin/hermes ]] && ! ours
+}
+
+# A hermes at that path is usable when it is a command that runs: a regular
+# executable whose --version answers. The executable bit alone proves little -- a directory
+# passes -x on search permission, and a wrapper whose interpreter or target is
+# gone passes it too. The desktop app applies the same probe with the same 15
+# second budget, so what passes here is what it will use.
+hermes_runs() {
+  [[ -f $HOME/.local/bin/hermes && -x $HOME/.local/bin/hermes ]] &&
+    timeout 15 "$HOME/.local/bin/hermes" --version >/dev/null 2>&1
+}
+
+# A flag counts only when the help defines it, not whenever it is mentioned:
+# what follows must be a shape argparse prints after a definition -- the usage
+# line's closing bracket, the gap before same-line help text, an uppercase
+# metavar, or the end of the line. Prose like "With --tui: run ..." stays
+# prose, and --tui-theme or --tui_mode never answers for --tui. Not probed by
+# parsing an actual invocation on purpose: a release that ignores unknown
+# arguments would turn the probe into a live session.
+help_defines_flag() {
+  grep -qE -- "$1(]|[[:space:]][[:upper:]]|[[:space:]]{2}|$)" <<<"$2"
+}
+
+# Probed for the flags omarchy-agent actually passes -- --query to seed the
+# session and --tui to keep it interactive -- rather than a marker standing in
+# for them: the old probe keyed on chat carrying --oneshot, which no released
+# Hermes did (it lived at the top level until v0.21 added chat's own), so
+# every release read as "not ready".
+hermes_prompt_ready() {
+  local help
+  hermes_runs &&
+    help=$(timeout 15 "$HOME/.local/bin/hermes" chat --help 2>/dev/null) &&
+    help_defines_flag '--tui' "$help" &&
+    help_defines_flag '--query' "$help"
+}
+
+# --owns answers whether the wrapper on PATH is the one this command wrote, so
+# the migration and Remove Preinstalls do not each carry their own copy of the
+# marker and drift from it.
+if [[ $mode == "--owns" ]]; then
+  if ours; then exit 0; else exit 1; fi
+fi
+
+# --remove tears down a Hermes CLI this installer put in place -- the mise tool
+# it installed and the stub it marked -- so Remove Hermes clears a CLI the app
+# never superseded (an interrupted install, or the terminal CLI from before the
+# app existed) rather than leaving it stranded on PATH. The whole teardown
+# turns on the marked stub, exactly as replacement does further down: without
+# it nothing proves the mise environment is Omarchy's rather than one the user
+# built against the same spec, and a user's stays theirs. The desktop takeover
+# removes the environment without asking, but that is its own bargain -- a
+# second Hermes has to go whoever built it, and the app still provides the
+# command afterwards; here nothing would. Idempotent: nothing owned, nothing
+# to do.
+if [[ $mode == "--remove" ]]; then
+  if ours; then
+    mise rm -g "$tool" >/dev/null 2>&1 || true
+    mise uninstall --all "$tool" >/dev/null 2>&1 || true
+    rm -f "$HOME/.local/bin/hermes" 2>/dev/null || true
+
+    # Every step is attempted before any is judged, and judged by what is left
+    # rather than by what the commands claimed: the marked stub still answering
+    # hermes, or mise still resolving the tool, is a CLI still installed no
+    # matter how the removal exited.
+    # Not "run --remove again": once the stub is gone nothing marks the mise
+    # environment as ours, so a rerun would find nothing it owns and succeed
+    # without touching what was left. Only the full commands finish the job.
+    if ours || mise where "$tool" >/dev/null 2>&1; then
+      echo "Could not remove the Hermes CLI Omarchy installed. Finish by hand:" >&2
+      echo "  rm -f ~/.local/bin/hermes" >&2
+      echo "  mise rm -g '$tool'" >&2
+      echo "  mise uninstall --all '$tool'" >&2
+      exit 1
+    fi
+  fi
+
+  exit 0
+fi
+
+# --check lets callers tell a cold stub from a working one before they commit
+# to a path that assumes Hermes is ready.
+if [[ $mode == "--check" ]]; then
+  if desktop_owns_hermes; then
+    if desktop_hermes_ready; then exit 0; else exit 1; fi
+  fi
+  # A foreign command is ready only when it also supports prompted sessions;
+  # since it is not ours to replace, nothing this installer does will update it.
+  if foreign_hermes; then
+    if hermes_prompt_ready; then exit 0; else exit 1; fi
+  fi
+  if installed && hermes_prompt_ready; then exit 0; else exit 1; fi
+fi
+
+# Hand Hermes over to the app rather than keeping a second copy beside it.
+if desktop_owns_hermes; then
+  # Not gated on that copy being healthy: `mise up` can rebuild it against the
+  # wrong interpreter and a half-finished install answers to neither test, and
+  # either way it is still a second Hermes. Removing nothing is harmless.
+  if mise where "$tool" >/dev/null 2>&1; then
+    echo "Hermes Desktop provides Hermes; removing the separate CLI install..." >&2
+  fi
+
+  mise rm -g "$tool" >/dev/null 2>&1 || true
+  mise uninstall --all "$tool" >/dev/null 2>&1 || true
+
+  # Our own stub has to go with it. Left in place it still answers `hermes`
+  # until the app's bootstrap overwrites it, and answering means building the
+  # second Hermes this whole arrangement exists to avoid.
+  if ours; then
+    rm -f "$HOME/.local/bin/hermes"
+  fi
+
+  if desktop_hermes_ready; then
+    exit 0
+  fi
+
+  echo "Hermes Desktop is installed but has not set Hermes up yet." >&2
+  echo "Launch Hermes Desktop once to finish installing it." >&2
+  exit 1
+fi
+
+# The user already has a hermes of their own. Leave it be: a working one is
+# what the default agent will run, and a broken one is theirs to fix.
+if foreign_hermes; then
+  if hermes_prompt_ready; then
+    exit 0
+  fi
+
+  if hermes_runs; then
+    echo "~/.local/bin/hermes does not support the interactive seeded sessions Omarchy needs." >&2
+    echo "Update it to a Hermes Agent release with interactive chat queries, then run omarchy-install-hermes-cli again." >&2
+    exit 1
+  fi
+
+  echo "~/.local/bin/hermes exists but is not runnable, and it was not installed by Omarchy." >&2
+  echo "Fix or remove it, then run omarchy-install-hermes-cli again." >&2
+  exit 1
+fi
+
+# Only the marked wrapper proves the matching mise environment is ours to replace.
+if installed && ! hermes_prompt_ready; then
+  if ours; then
+    echo "Updating Hermes for prompted sessions..." >&2
+    mise rm -g "$tool" >/dev/null 2>&1 || true
+    mise uninstall --all "$tool" >/dev/null 2>&1 || true
+  else
+    echo "A Hermes mise environment exists without an Omarchy-owned wrapper." >&2
+    echo "Update or remove it explicitly, then run omarchy-install-hermes-cli again." >&2
+    exit 1
+  fi
+fi
+
+mkdir -p "$HOME/.local/bin"
+rm -f "$HOME/.local/bin/hermes"
+
+cat >"$HOME/.local/bin/hermes" <<EOF
+#!/bin/bash
+
+$marker
+
+export UV_PYTHON="$python"
+
+# Exported rather than set on the install line alone, so the version resolved
+# to run agrees with the one just installed. Hermes ships several times a week
+# and mise's cooldown would otherwise hold a new release back for days.
+export MISE_MINIMUM_RELEASE_AGE=0
+
+# mise up -- which omarchy update runs -- reinstalls without that pin, so this
+# asks which interpreter is actually there rather than whether anything is.
+if ! [[ -d "\$(mise where '$tool' 2>/dev/null)/hermes-agent/lib/python$python" ]]; then
+  echo "Installing Hermes on Python $python (this takes a minute)..." >&2
+
+  # mise's pipx backend shells out to uv, which a stock Omarchy does not have.
+  # It is fetched here rather than when this stub was written, so setting up a
+  # machine that never runs Hermes costs nothing.
+  if omarchy-cmd-missing uv && ! mise where uv >/dev/null 2>&1; then
+    mise use -g --quiet uv@latest || exit 1
+  fi
+
+  mise use -g --quiet --force '$tool' || exit 1
+fi
+
+# The pin belongs to building Hermes, not to everything Hermes then runs.
+# Exported it would reach the agent and every command it shells out to, so a
+# uv in the user's own project would resolve 3.13 there too -- uv only warns
+# when that contradicts the project's requires-python, and builds it anyway.
+exec env -u UV_PYTHON mise x '$tool' -- hermes "\$@"
+EOF
+
+chmod +x "$HOME/.local/bin/hermes"
+
+# The desktop app resolves a hermes on PATH by running `hermes --version` with
+# a 15 second budget, then falls back to cloning its own copy when that times
+# out. A first-run mise install does not fit in 15 seconds, so anything that
+# hands Hermes to the GUI has to install it here rather than leave it stubbed.
+if [[ $mode == "--now" ]]; then
+  "$HOME/.local/bin/hermes" --version
+  if ! hermes_prompt_ready; then
+    echo "Hermes installed without the interactive seeded sessions Omarchy needs." >&2
+    exit 1
+  fi
+fi

bin/omarchy-install-openclaw-cli

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+# omarchy:summary=Ensure the OpenClaw CLI is installed for the default agent
+# omarchy:args=[--check|--now]
+# omarchy:requires-sudo=true
+
+# OpenClaw is not a mise tool: the openclaw pacman package is the one OpenClaw
+# installation on the machine — the CLI, the gateway, and the Install > AI web
+# app all share it, and the fast ring keeps it current. The default-agent flow
+# talks to that package through the same --check/--now contract mise-backed
+# agents get from mise itself.
+
+set -euo pipefail
+
+case "${1:---now}" in
+--check)
+  omarchy-pkg-present openclaw
+  ;;
+--now)
+  if ! omarchy-pkg-present openclaw; then
+    echo "Installing OpenClaw..."
+    omarchy-pkg-add openclaw
+  fi
+  ;;
+*)
+  echo "Usage: omarchy-install-openclaw-cli [--check|--now]" >&2
+  exit 1
+  ;;
+esac

bin/omarchy-launch-1password

@@ -4,8 +4,11 @@
 
 set -e
 
+# 1Password reads the display scale itself, the way Electron apps do, and comes
+# up oversized next to every other window on a scaled monitor. The packaged
+# .desktop pins it too; this covers the hotkey, which runs the binary directly.
 if omarchy-cmd-present 1password; then
-  exec setsid uwsm-app -- 1password
+  exec setsid uwsm-app -- 1password --force-device-scale-factor=1
 else
   exec omarchy-launch-floating-terminal-with-presentation omarchy-install-service-1password
 fi

bin/omarchy-launch-openclaw

@@ -0,0 +1,91 @@
+#!/bin/bash
+
+# omarchy:summary=Open the OpenClaw Control UI (or its terminal UI with --tui), onboarding or starting the gateway first when needed.
+# omarchy:args=[--tui [--message <text>]]
+
+set -euo pipefail
+
+tui=false
+message=()
+if [[ ${1:-} == "--tui" ]]; then
+  tui=true
+  shift
+  if [[ ${1:-} == "--message" ]]; then
+    message=(--message "${2:?--message needs a value}")
+    shift 2
+  fi
+fi
+
+# Onboarding is OpenClaw's own interactive wizard, run through
+# omarchy-openclaw-onboard so it stays in the terminal, installs the gateway
+# as a user service, and returns (see that script for why bare `openclaw
+# onboard` does none of those as of 2026.9.1). The config check gates what
+# follows because the wizard's "Skip for now" also exits 0: only inference
+# that passed writes the config, and skipping must not loop back into the
+# wizard.
+if [[ ! -f $HOME/.openclaw/openclaw.json ]]; then
+  if [[ $tui == "true" ]]; then
+    # Already in a terminal, so the wizard runs right here.
+    omarchy-openclaw-onboard
+    [[ -f $HOME/.openclaw/openclaw.json ]] || exit 1
+  else
+    # The wizard needs a real terminal, and chaining the relaunch means
+    # finishing it lands the user in the app. Single quotes so $HOME expands
+    # in the spawned terminal.
+    # shellcheck disable=SC2016
+    exec omarchy-launch-floating-terminal-with-presentation \
+      'omarchy-openclaw-onboard && [[ -f $HOME/.openclaw/openclaw.json ]] && omarchy-launch-openclaw'
+  fi
+fi
+
+dashboard_url() {
+  # browserUrl carries a single-use browser handoff; url is the shared-auth
+  # fallback for gateways predating the handoff flow. The timeout keeps a
+  # wedged CLI from hanging an app-grid launch that has no terminal to ^C.
+  timeout 10 openclaw dashboard --json 2>/dev/null | jq -re '.browserUrl // .url // empty'
+}
+
+# --json never starts the gateway, so an empty answer means it is not running.
+# Recovery goes through the gateway's own service commands. `dashboard --yes`
+# used to be the start/install-without-prompting path, but as of 2026.9.1 it
+# defers to "the owning supervisor" for both a missing and a stopped unit,
+# and once the gateway is up it copies a one-time pairing URL into the
+# clipboard, which nothing here needs. Enablement, not the unit file, decides:
+# a unit that was written but never enabled (an install that died halfway)
+# would otherwise be "started" once and stay off at every following login,
+# where --force rewrites and enables it.
+if ! url=$(dashboard_url); then
+  if systemctl --user is-enabled --quiet openclaw-gateway.service 2>/dev/null; then
+    timeout 60 openclaw gateway start >&2 || true
+  else
+    timeout 120 openclaw gateway install --force >&2 || true
+  fi
+
+  # A first-ever service install (unit write, daemon-reload, first boot)
+  # takes materially longer than starting an installed unit, so the budget
+  # is sized for the slow case.
+  for _ in {1..30}; do
+    url=$(dashboard_url) && break
+    sleep 1
+  done
+fi
+
+if [[ -z ${url:-} ]]; then
+  echo "OpenClaw's gateway did not come up. Check it with: openclaw gateway status" >&2
+  echo "If onboarding never finished, rerun it with: omarchy-openclaw-onboard" >&2
+  exit 1
+fi
+
+if [[ $tui == "true" ]]; then
+  # Attach to the gateway rather than `openclaw chat`: chat is the embedded
+  # local runtime, which refuses to start while the gateway owns ~/.openclaw's
+  # state directory -- and on any machine set up through Install > AI, the
+  # gateway service is running whenever the desktop session is.
+  exec openclaw tui "${message[@]}"
+fi
+
+# The handoff URL rides in the browser's argv, which uwsm's app daemon echoes
+# into the user journal. Accepted: the token is single-use with a ten-minute
+# expiry against a loopback-only gateway, and journal access already implies
+# access to ~/.openclaw itself.
+exec omarchy-launch-webapp "$url"

bin/omarchy-menu-images

@@ -75,8 +75,9 @@ fi
 selection_file=$(mktemp)
 done_file=$(mktemp)
 pending_file=$(mktemp)
+pending_video_file=$(mktemp)
 rm -f "$done_file"
-trap 'rm -f "$selection_file" "$done_file" "$pending_file"' EXIT
+trap 'rm -f "$selection_file" "$done_file" "$pending_file" "$pending_video_file"' EXIT
 
 image_dirs_env=""
 for dir in "${image_dirs[@]}"; do
@@ -111,8 +112,8 @@ cache_key=$(printf '%s' "$image_dirs_env" | md5sum | cut -d ' ' -f 1)
 rows_cache_file="$cache_dir/$cache_key.rows"
 rows_signature_file="$cache_dir/$cache_key.signature"
 rows_fast_signature_file="$cache_dir/$cache_key.fast-signature"
-rows_signature="v3"$'\n'
-rows_fast_signature="v2"$'\n'
+rows_signature="v4"$'\n'
+rows_fast_signature="v3"$'\n'
 rows_cacheable=true
 rows_cache_hit=false
 image_files=()
@@ -133,17 +134,25 @@ else
         image_files+=("$image")
         image_signature=$(stat -Lc '%s:%Y' "$image") || continue
         rows_signature+="$image:$image_signature"$'\n'
-      done < <(find -L "$dir" -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)
+      done < <(find -L "$dir" -maxdepth 1 -type f \
+        \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' -o -iname '*.gif' -o -iname '*.bmp' -o -iname '*.webp' \
+           -o -iname '*.mp4' -o -iname '*.m4v' -o -iname '*.mov' -o -iname '*.webm' -o -iname '*.mkv' -o -iname '*.avi' \) \
+        -print0 2>/dev/null | sort -z)
     fi
   done
 fi
 
+is_video_path() {
+  [[ ${1,,} =~ \.(mp4|m4v|mov|webm|mkv|avi)$ ]]
+}
+
 generate_thumbnail() {
   local image="$1"
   local thumbnail="$2"
   local lock="$thumbnail.lock"
   local lock_fd
   local tmp="$thumbnail.$$.jpg"
+  local thumbnail_command
 
   # Older releases used directories as locks, which could survive a killed
   # generator and block this thumbnail forever. Only reap aged ones, so a
@@ -161,13 +170,29 @@ generate_thumbnail() {
 
   [[ -f $thumbnail ]] && return
 
-  # Callers fan out one generator per image, so keep each vips single-threaded.
-  # Close the lock fd for vips: an orphaned or hung vips must not keep holding
-  # the lock after this shell is killed.
-  if VIPS_CONCURRENCY=1 vipsthumbnail "$image" --size 1536x864 --smartcrop=centre --path "$tmp[Q=82,strip]" {lock_fd}>&-; then
+  # Callers fan out one generator per file, so keep each image conversion
+  # single-threaded. ffmpegthumbnailer provides a still preview for videos.
+  if is_video_path "$image"; then
+    # Videos are generated before the picker opens, so one unreadable or
+    # stalled file must not hold it shut. A failed run drops the row.
+    thumbnail_command=(timeout -k 5 10 ffmpegthumbnailer -i "$image" -o "$tmp" -s 1536 -q 8)
+  else
+    thumbnail_command=(env VIPS_CONCURRENCY=1 vipsthumbnail "$image" --size 1536x864 --smartcrop=centre --path "$tmp[Q=82,strip]")
+  fi
+
+  # Close the lock fd for the converter: an orphaned or hung child must not
+  # keep holding the lock after this shell is killed.
+  if "${thumbnail_command[@]}" {lock_fd}>&-; then
     mv -f "$tmp" "$thumbnail"
   else
+    status=$?
     rm -f "$tmp" "$thumbnail"
+    # Remember a video the converter rejected, so it costs nothing on the next
+    # open. The key covers size and mtime, so a repaired file starts clean. A
+    # timeout is left to retry: the machine may only have been busy.
+    if is_video_path "$image" && (( status != 124 && status != 137 )); then
+      : >"$thumbnail.failed"
+    fi
   fi
 }
 
@@ -186,7 +211,17 @@ thumbnail_for() {
   thumbnail="$cache_dir/$hash.jpg"
 
   if [[ ! -f $thumbnail ]]; then
-    if [[ $lazy_thumbnails == true && $cache_only != true ]]; then
+    # A video that already failed to convert has no row to offer. Hand the
+    # marker back so the caller can keep the rows uncached over its absence.
+    if is_video_path "$image" && [[ -f $thumbnail.failed ]]; then
+      printf '%s' "$thumbnail.failed"
+      return
+    fi
+
+    # A lazy row stands in with the media file itself, which the picker draws
+    # with an Image -- fine for a picture, blank for a video. Videos take the
+    # queue instead, which also keeps them under its narrower fan out.
+    if [[ $lazy_thumbnails == true && $cache_only != true ]] && ! is_video_path "$image"; then
       rows_cacheable=false
 
       if [[ $prepare_only != true ]]; then
@@ -197,19 +232,35 @@ thumbnail_for() {
       return
     fi
 
-    printf '%s\0%s\0' "$image" "$thumbnail" >>"$pending_file"
+    if is_video_path "$image"; then
+      printf '%s\0%s\0' "$image" "$thumbnail" >>"$pending_video_file"
+    else
+      printf '%s\0%s\0' "$image" "$thumbnail" >>"$pending_file"
+    fi
   fi
 
   printf '%s' "$thumbnail"
 }
 
-# Generate every queued thumbnail at once; each vips run is single-threaded.
+# Each vips run is single-threaded, so still images can fill every core.
+# ffmpegthumbnailer leaves FFmpeg's automatic threading on, so a full-width fan
+# out of those would put a codec thread pool on every core at once.
 drain_pending_thumbnails() {
-  [[ -s $pending_file ]] || return 0
+  local video_jobs
 
-  export -f generate_thumbnail
-  xargs -a "$pending_file" -0 -n 2 -P "$(nproc)" \
-    bash -c 'generate_thumbnail "$1" "$2"' _ >/dev/null 2>&1 || true
+  export -f generate_thumbnail is_video_path
+
+  if [[ -s $pending_file ]]; then
+    xargs -a "$pending_file" -0 -n 2 -P "$(nproc)" \
+      bash -c 'generate_thumbnail "$1" "$2"' _ >/dev/null 2>&1 || true
+  fi
+
+  if [[ -s $pending_video_file ]]; then
+    video_jobs=$(( $(nproc) / 4 ))
+    (( video_jobs > 0 )) || video_jobs=1
+    xargs -a "$pending_video_file" -0 -n 2 -P "$video_jobs" \
+      bash -c 'generate_thumbnail "$1" "$2"' _ >/dev/null 2>&1 || true
+  fi
 }
 
 if [[ $rows_cache_hit != true && -f $rows_cache_file && -f $rows_signature_file ]] && cmp -s "$rows_signature_file" <(printf '%s' "$rows_signature"); then
@@ -219,6 +270,12 @@ elif [[ $rows_cache_hit != true ]]; then
   for image in "${image_files[@]}"; do
     thumbnail=$(thumbnail_for "$image")
     [[ -n $thumbnail ]] || continue
+    # Cached rows are trusted on the directory's mtime alone, which a file
+    # repaired in place never changes. Leave them uncached instead.
+    if [[ $thumbnail == *.failed ]]; then
+      rows_cacheable=false
+      continue
+    fi
     if [[ $lazy_thumbnails == true && $cache_only != true && $thumbnail == $image ]]; then
       rows_cacheable=false
     fi
@@ -232,7 +289,7 @@ elif [[ $rows_cache_hit != true ]]; then
 
   drain_pending_thumbnails
 
-  if [[ -s $pending_file ]]; then
+  if [[ -s $pending_file || -s $pending_video_file ]]; then
     pruned=""
     while IFS=$'\t' read -r row_image row_thumbnail; do
       if [[ ! -e $row_thumbnail ]]; then

bin/omarchy-mise-install

@@ -12,8 +12,38 @@ package=$1
 command=${2:-$1}
 bin=${3:-$command}
 
+# The command name becomes a file name under ~/.local/bin, so a slash in it
+# writes the wrapper somewhere else and the rm below deletes somewhere else. A
+# leading dot hides it or walks up, and a leading dash makes a name that reads
+# as an option to whatever picks it up. Checked before anything is removed or
+# written, and kept to those shapes so package names like npm:playwright still
+# stand in for the command name.
+case "$command" in
+  */* | .* | -* | *[[:cntrl:]]*)
+    echo "omarchy-mise-install: '$command' is not usable as a command name" >&2
+    exit 1
+    ;;
+esac
+
 mkdir -p "$HOME/.local/bin"
 
+# The heredoc below is unquoted, so whatever these hold is written into the
+# wrapper as shell source. Quote them the way omarchy-install-and-launch does, so
+# a package name carrying shell characters stays one argument instead of running.
+printf -v package_arg '%q' "$package"
+printf -v bin_arg '%q' "$bin"
+
+# Keep values that are inert inside double quotes in the form existing migrations
+# recognize, including mise backend options that %q would unnecessarily escape.
+case "$package" in
+  *'$'* | *'`'* | *'"'* | *'\'* | *'!'* | *[[:cntrl:]]*) ;;
+  *) package_arg="\"$package\"" ;;
+esac
+case "$bin" in
+  *'$'* | *'`'* | *'"'* | *'\'* | *'!'* | *[[:cntrl:]]*) ;;
+  *) bin_arg="\"$bin\"" ;;
+esac
+
 # These tools install and upgrade on first run, so mise's release cooldown would
 # hold a new version back for days after it ships. Exported rather than set on
 # the install line alone, so resolving the version to execute agrees with the
@@ -22,8 +52,8 @@ rm -f "$HOME/.local/bin/$command"
 cat >"$HOME/.local/bin/$command" <<EOF
 #!/bin/bash
 export MISE_MINIMUM_RELEASE_AGE=0
-mise use -g --quiet "$package" || exit 1
-exec mise x "$package" -- "$bin" "\$@"
+mise use -g --quiet $package_arg || exit 1
+exec mise x $package_arg -- $bin_arg "\$@"
 EOF
 
 chmod +x "$HOME/.local/bin/$command"

bin/omarchy-openclaw-onboard

@@ -0,0 +1,130 @@
+#!/bin/bash
+
+# omarchy:summary=Run OpenClaw's setup wizard the way Omarchy needs it: in the terminal, installing the gateway as a user service, and returning when it is done.
+
+# Not bare `openclaw onboard`: as of 2026.9.1 that is the guided flow, which
+# ends by running a foreground gateway and handing off to a browser tab, and
+# never returns. --install-daemon keeps it to the classic wizard (minimal
+# prompts with --flow quickstart) that installs the gateway service, and
+# --skip-ui drops its closing Control UI/TUI prompt since whoever called this
+# opens one next.
+#
+# That classic wizard has one wrinkle: with --skip-ui it prints "Onboarding
+# complete" and then never exits. Upstream only calls exit(0) when it launched
+# the TUI, and the model sign-in leaves an open socket that keeps the process
+# alive otherwise. So this script watches for the gateway to answer and then
+# stops the wizard. That is safe because every prompt in the quickstart flow
+# runs before the gateway service is installed and reachable: by the time the
+# dashboard answers, only the closing notes are left.
+
+set -uo pipefail
+
+wizard=(openclaw onboard --flow quickstart --install-daemon --skip-ui)
+config=$HOME/.openclaw/openclaw.json
+settle_seconds=${OMARCHY_OPENCLAW_ONBOARD_SETTLE_SECONDS:-3}
+# Counted from the moment the config exists, i.e. once the wizard has applied
+# setup; the prompts before that take as long as the user takes.
+gateway_timeout=${OMARCHY_OPENCLAW_ONBOARD_GATEWAY_TIMEOUT:-180}
+
+gateway_answers() {
+  timeout 10 openclaw dashboard --json 2>/dev/null | jq -e '.ok == true' >/dev/null 2>&1
+}
+
+# A gateway already answering means OpenClaw is set up, and this run must not
+# read its own success off state that predates it: the wizard's repair pass
+# would be stopped mid-prompt the moment the watcher looked. Nothing to do.
+if [[ -f $config ]] && gateway_answers; then
+  echo "OpenClaw is already set up and its gateway is running." >&2
+  echo "To change providers or settings, run: openclaw onboard --classic" >&2
+  exit 0
+fi
+
+# Marks when this run began, so a config left behind by an earlier, incomplete
+# setup is not mistaken for this run having applied its own: the gateway
+# deadline below must not start ticking while the user is still at prompts.
+started=$(mktemp)
+trap 'rm -f "$started"' EXIT
+
+# Backgrounded so this script can watch it, but with the terminal kept as its
+# stdin (bash would otherwise hand a background job /dev/null). Job control is
+# off in a script, so it stays in the terminal's foreground process group and
+# reads from it freely. Ctrl-C does not reach it directly, though: bash starts
+# async children with SIGINT ignored when job control is off, so the INT trap
+# below is what turns Ctrl-C into the wizard's exit.
+"${wizard[@]}" <&0 &
+wizard_pid=$!
+
+stop_wizard() {
+  kill -TERM "$wizard_pid" 2>/dev/null || true
+}
+# Any signal at this script, whether Ctrl-C from the terminal or a kill aimed
+# at its pid alone, takes the wizard down with it rather than leaving it
+# running unwatched.
+trap 'stop_wizard' INT TERM HUP
+
+# Whether this run has applied setup: the config exists and is not older than
+# the run itself.
+config_applied() {
+  [[ -f $config && ! $started -nt $config ]]
+}
+
+# Whether this run's gateway is up: setup applied, and the process answering
+# on the gateway's port is the main process of the service the wizard
+# installs. Not the dashboard alone: with no config on disk `openclaw
+# dashboard --json` still probes the default loopback port, so a gateway left
+# behind by something else (an earlier guided onboarding's foreground
+# gateway, say) would read as this run's success while the user is still at
+# the first prompt. And not the unit being active either: its Type=simple
+# counts it active from the fork, before it has found the port taken by such
+# an orphan, and the app would then open on the orphan rather than the
+# service this run installed.
+gateway_ready() {
+  config_applied || return 1
+  local json port listener main_pid
+  json=$(timeout 10 openclaw dashboard --json 2>/dev/null) || return 1
+  jq -e '.ok == true' <<<"$json" >/dev/null 2>&1 || return 1
+  port=$(jq -r '.port // empty' <<<"$json" 2>/dev/null)
+  [[ -n $port ]] || return 1
+  listener=$(ss -ltnpH "sport = :$port" 2>/dev/null | sed -n 's/.*pid=\([0-9]*\).*/\1/p' | head -1)
+  main_pid=$(systemctl --user show -p MainPID --value openclaw-gateway.service 2>/dev/null)
+  [[ -n $listener && -n $main_pid && $main_pid != 0 && $listener == "$main_pid" ]]
+}
+
+stopped=false
+timed_out=false
+config_seen_at=
+while kill -0 "$wizard_pid" 2>/dev/null; do
+  sleep 2
+  if gateway_ready; then
+    # Let the outro finish printing, then end the process the wizard leaves
+    # running.
+    sleep "$settle_seconds"
+    stop_wizard
+    stopped=true
+    break
+  fi
+  config_applied || continue
+  : "${config_seen_at:=$SECONDS}"
+  if (( SECONDS - config_seen_at >= gateway_timeout )); then
+    # Setup was applied but the service never came up (port taken, unit
+    # failing, ...): the wizard would sit in its never-exiting state forever,
+    # and so would whoever is waiting on this script.
+    stop_wizard
+    timed_out=true
+    break
+  fi
+done
+
+wait "$wizard_pid"
+rc=$?
+
+if [[ $timed_out == true ]]; then
+  echo "OpenClaw's gateway did not come up within ${gateway_timeout}s of setup finishing." >&2
+  echo "Check it with: openclaw gateway status" >&2
+  exit 1
+fi
+# A wizard stopped here after the gateway came up did its job. One that
+# exited on its own, including a user who chose "Skip for now" (no config,
+# non-zero), keeps its own exit code.
+[[ $stopped == true ]] && rc=0
+exit "$rc"

bin/omarchy-pkg-aur-install

@@ -24,6 +24,6 @@ if [[ -n $pkg_names ]]; then
   source omarchy-sudo-keepalive
 
   echo "$pkg_names" | sed 's/^/aur\//' | tr '\n' ' ' | xargs yay -S --noconfirm
-  sudo updatedb
+  sudo updatedb --prune-bind-mounts=no --add-prunepaths=/.snapshots
   omarchy-show-done
 fi

bin/omarchy-provision-owner

@@ -449,7 +449,7 @@ greeter_screen() {
     rows=$(stty size 2>/dev/null </dev/tty | awk '{print $1}')
     [[ $rows =~ ^[0-9]+$ ]] || rows=${LINES:-24}
 
-    tagline="Beautiful, Modern & Opinionated Linux by DHH"
+    tagline="Beautiful, Fun & Agentic Linux by DHH"
     hint="Press Return to Start Setup"
 
     printf '%s%s' "$HIDE_CURSOR" "$CLEAR"

bin/omarchy-provision-user

@@ -84,7 +84,7 @@ 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.
 # Loops every skill directory, so shipping a new one needs no edit here.
-mkdir -p ~/.agents/skills ~/.claude/skills ~/.codex/skills ~/.pi/agent/skills ~/.gemini/config/skills
+mkdir -p ~/.agents/skills ~/.claude/skills ~/.codex/skills ~/.pi/agent/skills ~/.gemini/config/skills ~/.hermes/skills
 for skill in "$OMARCHY_PATH"/default/agents/skills/*/; do
   skill=${skill%/}
   name=${skill##*/}
@@ -93,6 +93,14 @@ for skill in "$OMARCHY_PATH"/default/agents/skills/*/; do
   ln -sfn "$skill" ~/.codex/skills/"$name"
   ln -sfn "$skill" ~/.pi/agent/skills/"$name"
   ln -sfn "$skill" ~/.gemini/config/skills/"$name"
+  ln -sfn "$skill" ~/.hermes/skills/"$name"
+  if [[ -d ~/.hermes/profiles ]]; then
+    for profile in ~/.hermes/profiles/*/; do
+      [[ -d $profile ]] || continue
+      mkdir -p "$profile/skills"
+      ln -sfn "$skill" "$profile/skills/$name"
+    done
+  fi
 done
 
 mkdir -p ~/Downloads ~/Pictures ~/Videos ~/.config/gtk-3.0

bin/omarchy-remove-ai-hermes

@@ -0,0 +1,147 @@
+#!/bin/bash
+
+# omarchy:summary=Remove the Hermes desktop app along with the Hermes runtime it installed.
+# omarchy:requires-sudo=true
+
+# -u so an unset HOME is an error rather than a set of rm -rf paths rooted at /.
+set -euo pipefail
+
+ensure_hermes_stopped() {
+  python3 - "$HOME" <<'PY'
+import os
+from pathlib import Path
+import sys
+
+home = Path(sys.argv[1])
+roots = [str((home / relative).resolve()) for relative in ('.hermes', '.config/Hermes')]
+roots.append('/opt/hermes-desktop')
+
+def belongs_to_hermes(target):
+    target = target.removesuffix(' (deleted)')
+    return any(target == root or target.startswith(root + '/') for root in roots)
+
+holders = []
+for process in Path('/proc').iterdir():
+    if not process.name.isdigit() or int(process.name) == os.getpid():
+        continue
+    try:
+        if process.stat().st_uid != os.getuid():
+            continue
+        targets = [os.fsdecode(arg) for arg in (process / 'cmdline').read_bytes().split(b'\0')]
+        entries = [process / 'exe', process / 'cwd']
+        try:
+            entries.extend((process / 'fd').iterdir())
+        except PermissionError:
+            pass
+        for entry in entries:
+            try:
+                targets.append(os.readlink(entry))
+            except OSError:
+                pass
+        if any(belongs_to_hermes(target) for target in targets):
+            holders.append(process.name)
+    except (FileNotFoundError, ProcessLookupError, PermissionError):
+        continue
+
+if holders:
+    print('Close Hermes and processes using its files before removing it (PIDs: '
+          + ', '.join(holders) + '). Then try again.', file=sys.stderr)
+    sys.exit(1)
+PY
+}
+
+# Removing an open SQLite WAL leaves a live writer on a deleted generation.
+ensure_hermes_stopped
+omarchy-pkg-drop hermes-desktop
+
+# The installer leaves a unit waiting to hand the app the Omarchy theme.
+systemctl --user stop omarchy-hermes-theme.service 2>/dev/null || true
+
+# The mise CLI is the app's predecessor, not the app itself: Hermes Desktop takes
+# it over on install and runs its own runtime instead, so a copy still here is one
+# the app never superseded -- an interrupted install, or the terminal CLI from
+# before the app existed. Remove Hermes clears that too, scoped by the installer
+# to what Omarchy owns so a hermes the user set up themselves is left alone.
+# Tolerated here rather than fatal, so the ~/.hermes handling below still runs;
+# the failure is answered for at the end instead of being swallowed.
+cli_removed=true
+ensure_hermes_stopped
+omarchy-install-hermes-cli --remove || cli_removed=false
+
+# The app writes this when the runtime it provisions under ~/.hermes has landed,
+# and it is the only thing that tells that runtime apart from one the user
+# installed themselves -- the paths are the same either way. Without it the app
+# never got that far: a machine where it was installed but never launched still
+# has whatever was there before, and none of it is ours to delete unasked.
+if [[ -f $HOME/.hermes/hermes-agent/.hermes-bootstrap-complete ]]; then
+  # The checkout and venv, its own uv, its own node. None of it is any use once
+  # the app is gone, so it goes without asking; what the user made with the app
+  # is a different question, answered below.
+  rm -rf \
+    "$HOME/.hermes/hermes-agent" \
+    "$HOME/.hermes/bootstrap-cache" \
+    "$HOME/.hermes/bin" \
+    "$HOME/.hermes/node"
+
+  # Only the wrappers pointing into ~/.hermes, matched as a plain string: the
+  # path carries a dot, so an unanchored pattern would also claim a wrapper
+  # pointing at a sibling like ~/xhermes.
+  for command in hermes hermes-agent hermes-acp; do
+    wrapper="$HOME/.local/bin/$command"
+
+    if [[ -f $wrapper && ! -L $wrapper ]] && grep -qF "$HOME/.hermes" "$wrapper"; then
+      rm -f "$wrapper"
+    fi
+  done
+
+  # When Hermes brought its own Node it symlinked these next to its own commands,
+  # and they point at what we just deleted. Only the links into ~/.hermes: a
+  # system Node, or someone else's, lives somewhere else entirely.
+  for command in node npm npx; do
+    link="$HOME/.local/bin/$command"
+
+    if [[ -L $link && $(readlink "$link") == "$HOME/.hermes"/* ]]; then
+      rm -f "$link"
+    fi
+  done
+
+fi
+
+# What survives to here is the user's: the chats, memories and skills in
+# ~/.hermes, the connections and their encrypted tokens in ~/.config/Hermes.
+# Keeping them stays the default -- they are small, and finding them intact
+# after a reinstall is the better surprise -- but a removal meant to be
+# complete should not leave credentials behind either, so the choice is put in
+# front of the user with the size, default no. Asked whenever the directories
+# exist, marker or no marker: on a machine where the marker never appeared the
+# data came from the terminal CLI or an install the app never finished, and it
+# is still what removal is asked to clean up. Naming the paths keeps the
+# question honest there too -- ~/.hermes may still carry a runtime the app
+# never owned, a yes takes that with it, and saying so is the prompt's job.
+# Without a terminal to ask in, keeping everything is the answer.
+data_removed=false
+if [[ -d $HOME/.hermes || -d $HOME/.config/Hermes ]] && [[ -t 0 ]] && omarchy-cmd-present gum; then
+  # du answers non-zero when either directory is missing, and pipefail would
+  # turn that into an aborted removal; the size is worth no such thing.
+  size=$(du -shc "$HOME/.hermes" "$HOME/.config/Hermes" 2>/dev/null | tail -1 | cut -f1 || true)
+  if gum confirm --default=false "Also delete ~/.hermes and ~/.config/Hermes ($size: chats, memories, skills, connections and tokens)?"; then
+    ensure_hermes_stopped
+    rm -rf "$HOME/.hermes" "$HOME/.config/Hermes"
+    data_removed=true
+  fi
+fi
+
+echo ""
+echo "Hermes Desktop has been removed."
+if [[ $data_removed == true ]]; then
+  echo "Its chats, memories, and settings in ~/.hermes and ~/.config/Hermes are gone too."
+elif [[ -d $HOME/.hermes || -d $HOME/.config/Hermes ]]; then
+  echo "Your chats, memories, and skills are still in ~/.hermes,"
+  echo "and your connections and settings in ~/.config/Hermes."
+fi
+
+# The messages above still hold -- the app and its runtime are gone -- but a CLI
+# teardown that failed already said so on stderr, and that stands.
+if [[ $cli_removed == "false" ]]; then
+  exit 1
+fi

bin/omarchy-remove-ai-openclaw

@@ -0,0 +1,78 @@
+#!/bin/bash
+
+# omarchy:summary=Remove the OpenClaw agent platform along with its gateway service and web app.
+# omarchy:requires-sudo=true
+
+# -u so an unset HOME is an error rather than a set of rm -rf paths rooted at /.
+set -euo pipefail
+
+unit_dir="$HOME/.config/systemd/user"
+
+# Only systemd's own word counts as "stopped": a non-zero exit from is-active
+# also covers an unreachable user manager, which says nothing about whether
+# the process is alive.
+unit_stopped() {
+  local state
+  state=$(systemctl --user is-active "$1" 2>/dev/null) || true
+  [[ $state == inactive || $state == failed ]]
+}
+
+# The user services OpenClaw installs for itself: the gateway through
+# onboarding, and the node host if the user ever paired this machine to
+# another gateway. OpenClaw writes them to $HOME/.config regardless of
+# XDG_CONFIG_HOME, so look exactly there; no unit means nothing registered.
+# Upstream's own teardown knows every piece its install wrote (unit file, the
+# default.target.wants enablement symlink, the reload), so prefer it while the
+# binary is still installed and fall back to doing the same by hand. A service
+# that will not stop aborts the removal: dropping the package would strand the
+# live process on deleted code with no way to restart it cleanly.
+for unit_file in "$unit_dir"/openclaw-gateway.service "$unit_dir"/openclaw-node.service; do
+  [[ -f $unit_file ]] || continue
+  unit=${unit_file##*/}
+  role=${unit#openclaw-}
+  role=${role%.service}
+  if openclaw "$role" uninstall >/dev/null 2>&1 ||
+    systemctl --user disable --now "$unit" 2>/dev/null ||
+    unit_stopped "$unit"; then
+    # .bak is what `gateway install --force` leaves behind when it rewrites a
+    # unit, so it goes with the unit.
+    rm -f "$unit_file" "$unit_file.bak" "$unit_dir/default.target.wants/$unit"
+    systemctl --user daemon-reload 2>/dev/null || true
+    # A unit that had been failing stays listed as "not-found failed" after
+    # its file is gone until its failed state is reset.
+    systemctl --user reset-failed "$unit" 2>/dev/null || true
+  else
+    echo "Could not stop $unit; OpenClaw was not removed." >&2
+    exit 1
+  fi
+done
+
+omarchy-pkg-drop openclaw
+
+# The web app launcher and icon omarchy-install-ai-openclaw created.
+rm -f "$HOME/.local/share/applications/OpenClaw.desktop"
+rm -f "$HOME/.local/share/icons/hicolor/256x256/apps/openclaw.png"
+gtk-update-icon-cache "$HOME/.local/share/icons/hicolor" &>/dev/null || true
+
+# ~/.openclaw stays unless asked: the chats, memories, and credentials in
+# there are the user's agent, and finding them intact after a reinstall is the
+# better surprise. But it also holds the plugin runtimes and caches OpenClaw
+# downloads for itself, easily hundreds of megabytes, so the choice is put in
+# front of the user with the size rather than left silent. Without a terminal
+# to ask in, keeping it is the answer.
+state_removed=false
+if [[ -d $HOME/.openclaw && -t 0 ]] && omarchy-cmd-present gum; then
+  size=$(du -sh "$HOME/.openclaw" 2>/dev/null | cut -f1)
+  if gum confirm --default=false "Also delete ~/.openclaw ($size: chats, memories, credentials, and downloaded plugins)?"; then
+    rm -rf "$HOME/.openclaw"
+    state_removed=true
+  fi
+fi
+
+echo ""
+echo "OpenClaw has been removed."
+if [[ $state_removed == true ]]; then
+  echo "Its chats, memories, and settings in ~/.openclaw are gone too."
+elif [[ -d $HOME/.openclaw ]]; then
+  echo "Your agent's chats, memories, and settings are still in ~/.openclaw."
+fi

bin/omarchy-remove-ai-perplexity

@@ -0,0 +1,49 @@
+#!/bin/bash
+
+# omarchy:summary=Remove the Perplexity desktop app along with its runtime caches.
+# omarchy:requires-sudo=true
+
+# -u so an unset HOME is an error rather than a set of rm -rf paths rooted at /.
+set -euo pipefail
+
+omarchy-pkg-drop perplexity
+
+# The runtime the app downloads for itself: llama.cpp builds and local models
+# under ~/.local/share, the older download location under ~/.cache. Of the
+# perplexity-* dirs these are the only ones the desktop app owns; the rest
+# belong to Perplexity products that outlive it.
+rm -rf \
+  "$HOME/.cache/Perplexity" \
+  "$HOME/.cache/perplexity-rpc-server" \
+  "$HOME/.local/share/perplexity-rpc-server"
+
+# What is left is the user's: the logins and session in ~/.config/Perplexity,
+# the secret vault and device identity in ~/.local/state/perplexity, and the
+# launcher flags. Keeping them stays the default -- they are small, and being
+# signed in after a reinstall is the better surprise -- but a removal meant to
+# be complete should not leave credentials behind either, so the choice is put
+# in front of the user, default no. Without a terminal to ask in, keeping it
+# is the answer -- and gum draws the prompt on stderr, so a redirected stderr
+# would block on a question nobody can see.
+data_removed=false
+if [[ -t 0 && -t 2 ]]; then
+  # du answers non-zero when a directory is missing, and pipefail would turn
+  # that into an aborted removal; the size is worth no such thing.
+  size=$(du -shc "$HOME/.config/Perplexity" "$HOME/.local/state/perplexity" 2>/dev/null | tail -1 | cut -f1 || true)
+  if gum confirm --default=false "Also delete your Perplexity data ($size: logins, settings, secret vault and device identity)?"; then
+    rm -rf \
+      "$HOME/.config/Perplexity" \
+      "$HOME/.local/state/perplexity"
+    rm -f "$HOME/.config/perplexity-flags.conf"
+    data_removed=true
+  fi
+fi
+
+echo ""
+echo "Perplexity has been removed."
+if [[ $data_removed == "true" ]]; then
+  echo "Its logins, settings, secret vault, and device identity are gone too."
+else
+  echo "Nothing of yours was touched: not the logins in ~/.config/Perplexity,"
+  echo "nor the secret vault and device identity in ~/.local/state/perplexity."
+fi

bin/omarchy-remove-preinstalls

@@ -17,6 +17,27 @@ if gum confirm "Are you sure you want to remove all preinstalled web apps, TUI w
        ~/.local/bin/gh ~/.local/bin/opencode ~/.local/bin/playwright ~/.local/bin/playwright-cli ~/.local/bin/pi \
        ~/.local/bin/omp ~/.local/bin/ori ~/.local/bin/grok ~/.local/bin/crush ~/.local/bin/ghui ~/.local/bin/hunk
 
+  # Cursor's own installer links ~/.local/bin/cursor-agent as well, so only
+  # the mise wrapper omarchy-mise-install wrote is a preinstall.
+  if [[ -f ~/.local/bin/cursor-agent && ! -L ~/.local/bin/cursor-agent ]] &&
+    grep -Eq '^mise use -g .*"cursor-agent"' ~/.local/bin/cursor-agent; then
+    rm -f ~/.local/bin/cursor-agent
+  fi
+
+  # Preserve a user-managed Muse launcher at the same path.
+  if [[ -f ~/.local/bin/muse && ! -L ~/.local/bin/muse ]] &&
+    grep -Eq '^mise use -g .*"http:muse\[' ~/.local/bin/muse; then
+    rm -f ~/.local/bin/muse
+  fi
+
+  # Only the wrapper omarchy-install-hermes-cli wrote is a preinstall. Hermes
+  # Desktop's command, an official install, or anything else at that path is
+  # the user's, so it is the installer that decides whether the wrapper is its
+  # own, rather than a copy of its marker kept here.
+  if omarchy-install-hermes-cli --owns; then
+    rm -f ~/.local/bin/hermes
+  fi
+
   omarchy-pkg-drop \
     aether \
     cliamp \

bin/omarchy-setup-security-fingerprint

@@ -74,18 +74,15 @@ if ! omarchy-hw-fingerprint; then
   exit 1
 fi
 
-# Install required packages
-echo "Installing required packages..."
-
-# libfprint-git provides+conflicts libfprint; pacman -S --noconfirm
-# defaults the conflict prompt to N and aborts. Pre-remove it (deps-only,
-# so an installed fprintd stays put) so stock libfprint installs cleanly.
-if pacman -Q libfprint-git &>/dev/null; then
-  sudo pacman -Rdd --noconfirm libfprint-git
+# libfprint-git tracks upstream ahead of the Arch release, so a new reader only
+# needs a pin bump in omarchy-pkgs. It conflicts with stock libfprint, and
+# --noconfirm answers that prompt with N; --ask 4 accepts the replacement in
+# one transaction, so a failed install leaves the existing driver in place.
+if omarchy-pkg-missing libfprint-git fprintd usbutils; then
+  echo "Installing required packages..."
+  sudo pacman -S --needed --noconfirm --ask 4 libfprint-git fprintd usbutils
 fi
 
-omarchy-pkg-add libfprint fprintd usbutils
-
 # Enroll first fingerprint
 echo -e "\e[32m\nLet's setup your right index finger as the first fingerprint.\e[0m"
 echo -e "Keep moving the finger around on sensor until the process completes.\n"

bin/omarchy-theme-bg-next

@@ -10,7 +10,8 @@ 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 \
-    \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' -o -iname '*.gif' -o -iname '*.bmp' -o -iname '*.webp' \) \
+    \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' -o -iname '*.gif' -o -iname '*.bmp' -o -iname '*.webp' \
+       -o -iname '*.mp4' -o -iname '*.m4v' -o -iname '*.mov' -o -iname '*.webm' -o -iname '*.mkv' -o -iname '*.avi' \) \
     -print0 2>/dev/null | sort -z
 )
 TOTAL=${#BACKGROUNDS[@]}

bin/omarchy-theme-bg-set

@@ -1,11 +1,11 @@
 #!/bin/bash
 
-# omarchy:summary=Set the current background image
-# omarchy:args=<path-to-image>
+# omarchy:summary=Set the current background image or video
+# omarchy:args=<path-to-media>
 # omarchy:examples=omarchy theme bg set ~/Pictures/background.png
 
 if [[ -z $1 ]]; then
-  echo "Usage: omarchy-theme-bg-set <path-to-image>" >&2
+  echo "Usage: omarchy-theme-bg-set <path-to-media>" >&2
   exit 1
 fi
 
@@ -17,7 +17,7 @@ if [[ ! -f $BACKGROUND ]]; then
   exit 1
 fi
 
-# Create symlink to the new background
+# Create symlink to the new background media
 ln -nsf "$BACKGROUND" "$CURRENT_BACKGROUND_LINK"
 
 # Update the live shell background immediately when it is running. The

bin/omarchy-theme-set

@@ -48,12 +48,17 @@ shell_ipc() {
   timeout 2 omarchy-shell "$@" >/dev/null 2>&1
 }
 
+is_video_path() {
+  [[ ${1,,} =~ \.(mp4|m4v|mov|webm|mkv|avi)$ ]]
+}
+
 snapshot_background_path() {
   local background="$1"
   local name="$2"
   local snapshot extension
 
   [[ -f $background ]] || return
+  is_video_path "$background" && return
 
   mkdir -p "$BACKGROUND_TRANSITION_CACHE"
   extension=${background##*.}
@@ -69,20 +74,35 @@ snapshot_current_background() {
   snapshot_background_path "$current_background" "previous"
 }
 
+background_transition_uses_snapshots() {
+  local next_background="$1"
+  local current_background
+
+  current_background=$(readlink -f "$CURRENT_BACKGROUND_LINK" 2>/dev/null || true)
+  ! is_video_path "$current_background" && ! is_video_path "$next_background"
+}
+
 choose_theme_background() {
+  local theme_path="${1:-$CURRENT_THEME_PATH}"
+  local current_theme_backgrounds="$CURRENT_THEME_PATH/backgrounds"
   local backgrounds=()
   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' \) \
+    find -L "$HOME/.config/omarchy/backgrounds/$THEME_NAME/" "$theme_path/backgrounds/" -maxdepth 1 -type f \
+      \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' -o -iname '*.gif' -o -iname '*.bmp' -o -iname '*.webp' \
+         -o -iname '*.mp4' -o -iname '*.m4v' -o -iname '*.mov' -o -iname '*.webm' -o -iname '*.mkv' -o -iname '*.avi' \) \
       -print0 2>/dev/null | sort -z
   )
 
   (( ${#backgrounds[@]} > 0 )) || return 1
 
   current_background=$(readlink "$CURRENT_BACKGROUND_LINK" 2>/dev/null || true)
+  if [[ $theme_path != $CURRENT_THEME_PATH && ${current_background%/*} == $current_theme_backgrounds ]]; then
+    current_background="$theme_path/backgrounds/${current_background##*/}"
+  fi
+
   index=-1
   for i in "${!backgrounds[@]}"; do
     if [[ ${backgrounds[$i]} == $current_background ]]; then
@@ -99,6 +119,16 @@ choose_theme_background() {
   fi
 }
 
+choose_staged_theme_background() {
+  local next_theme_backgrounds="$NEXT_THEME_PATH/backgrounds"
+
+  choose_theme_background "$NEXT_THEME_PATH" || return 1
+
+  if [[ ${CHOSEN_THEME_BACKGROUND%/*} == $next_theme_backgrounds ]]; then
+    CHOSEN_THEME_BACKGROUND="$CURRENT_THEME_PATH/backgrounds/${CHOSEN_THEME_BACKGROUND##*/}"
+  fi
+}
+
 set_theme_background_link() {
   choose_theme_background || return 1
   ln -nsf "$CHOSEN_THEME_BACKGROUND" "$CURRENT_BACKGROUND_LINK"
@@ -107,14 +137,19 @@ set_theme_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
+  if [[ -z $CHOSEN_THEME_BACKGROUND || ! -f $CHOSEN_THEME_BACKGROUND ]]; then
+    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
   fi
 
   new_background="$CHOSEN_THEME_BACKGROUND"
-  new_background_snapshot=$(snapshot_background_path "$new_background" "next")
+  new_background_snapshot=""
+  if [[ $BACKGROUND_TRANSITION_SNAPSHOTS == "true" ]]; then
+    new_background_snapshot=$(snapshot_background_path "$new_background" "next")
+  fi
 
   if [[ -f $OLD_BACKGROUND_SNAPSHOT && -f $new_background_snapshot ]]; then
     shell_ipc background themeTransition "$OLD_BACKGROUND_SNAPSHOT" "$new_background_snapshot" "$new_background" "$colors_payload" "$shell_payload" || \
@@ -283,9 +318,19 @@ fi
 # Generate dynamic configs
 omarchy-theme-set-templates
 
+CHOSEN_THEME_BACKGROUND=""
 OLD_BACKGROUND_SNAPSHOT=""
+BACKGROUND_TRANSITION_SNAPSHOTS=true
 if [[ $THEME_HEADLESS != "1" && $OMARCHY_THEME_SKIP_BACKGROUND != "1" ]]; then
-  OLD_BACKGROUND_SNAPSHOT=$(snapshot_current_background)
+  # Resolve the staged choice while the old theme still exists. Video changes
+  # switch directly to the durable path in QML, so neither side needs a copy.
+  if choose_staged_theme_background; then
+    if background_transition_uses_snapshots "$CHOSEN_THEME_BACKGROUND"; then
+      OLD_BACKGROUND_SNAPSHOT=$(snapshot_current_background)
+    else
+      BACKGROUND_TRANSITION_SNAPSHOTS=false
+    fi
+  fi
 fi
 
 # Swap next theme in as current
@@ -326,6 +371,8 @@ post_theme_commands=(
   omarchy-theme-set-gnome
   omarchy-theme-set-pi
   omarchy-theme-set-claude
+  omarchy-theme-set-hermes
+  omarchy-theme-set-t3code
   omarchy-theme-set-browser
   omarchy-theme-set-vscode
   omarchy-theme-set-obsidian

bin/omarchy-theme-set-hermes

@@ -0,0 +1,233 @@
+#!/bin/bash
+
+# omarchy:summary=Sync the generated Omarchy theme to Hermes as a skin
+# omarchy:args=[--activate] [--wait]
+# omarchy:hidden=true
+
+# A skin is Hermes' one theme unit for the desktop app, the TUI and the CLI;
+# its gateway watches the active skin file and repaints every surface on change.
+
+set -euo pipefail
+
+HERMES_SOURCE_PATH="$HOME/.local/state/omarchy/current/theme/hermes.yaml"
+HERMES_THEME_NAME_PATH="$HOME/.local/state/omarchy/current/theme.name"
+HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
+HERMES_CONFIG_PATH="$HERMES_HOME/config.yaml"
+HERMES_SKIN_NAME="omarchy"
+# The command the readiness probe vets, rather than whichever hermes is on PATH.
+HERMES_COMMAND="$HOME/.local/bin/hermes"
+# Written by the desktop app once the runtime its first launch provisions is in.
+HERMES_BOOTSTRAP_MARKER="$HERMES_HOME/hermes-agent/.hermes-bootstrap-complete"
+HERMES_ACTIVATE=0
+HERMES_WAIT=0
+HERMES_WAIT_LIMIT=$((30 * 60))
+
+usage() {
+  echo "Usage: omarchy-theme-set-hermes [--activate] [--wait]"
+}
+
+for arg in "$@"; do
+  case "$arg" in
+    --activate)
+      HERMES_ACTIVATE=1
+      ;;
+    --wait)
+      HERMES_ACTIVATE=1
+      HERMES_WAIT=1
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    *)
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+# A theme switch runs this beside a dozen other hooks; only --activate explains.
+note() {
+  if (( HERMES_ACTIVATE == 1 )); then
+    echo "$*" >&2
+  fi
+}
+
+# A theme applied before the template existed has no skin rendered yet.
+if [[ ! -f $HERMES_SOURCE_PATH ]]; then
+  (( HERMES_ACTIVATE == 1 )) || exit 0
+
+  if [[ ! -s $HERMES_THEME_NAME_PATH ]]; then
+    echo "Hermes skin source missing: $HERMES_SOURCE_PATH" >&2
+    echo "Select an Omarchy theme first." >&2
+    exit 1
+  fi
+
+  omarchy-theme-refresh
+
+  if [[ ! -f $HERMES_SOURCE_PATH ]]; then
+    echo "Hermes skin source missing after refreshing the theme: $HERMES_SOURCE_PATH" >&2
+    exit 1
+  fi
+fi
+
+# The first launch takes minutes and may be abandoned; the readiness probe
+# would start Hermes to answer, so poll for the marker instead.
+if (( HERMES_WAIT == 1 )); then
+  waited=0
+  until [[ -f $HERMES_BOOTSTRAP_MARKER && -f $HERMES_CONFIG_PATH ]]; do
+    if (( waited >= HERMES_WAIT_LIMIT )); then
+      echo "Hermes did not finish setting up within $((HERMES_WAIT_LIMIT / 60)) minutes; run omarchy-theme-set-hermes --activate once it has." >&2
+      exit 0
+    fi
+
+    sleep 10
+    waited=$((waited + 10))
+  done
+fi
+
+# Provisioning creates ~/.hermes on every machine for the Omarchy skill; the
+# config is what Hermes writes once it has actually run.
+if [[ ! -f $HERMES_CONFIG_PATH ]]; then
+  note "Hermes is not set up yet; launch it once, then run omarchy-theme-set-hermes --activate."
+  exit 0
+fi
+
+# Hermes parses the skin as YAML and hands its strings to every surface, so only
+# the name, a plain description and #rrggbb colours may reach it, in the order
+# YAML needs them. YAML breaks lines on bytes grep does not, so the bytes are
+# counted first, NUL included.
+skin_is_well_formed() {
+  local skin="$1"
+
+  [[ -f $skin ]] &&
+    (( $(LC_ALL=C tr -d ' -~\n' <"$skin" | wc -c) == 0 )) &&
+    awk -v name="name: $HERMES_SKIN_NAME" '
+      bad { next }
+      /^#/ || /^[[:space:]]*$/ { next }
+      !seen_name { if ($0 == name) seen_name = 1; else bad = 1; next }
+      !seen_colors {
+        if ($0 == "colors:") seen_colors = 1
+        else if (!seen_description && $0 ~ /^description: [A-Za-z0-9 ,.()-]{0,200}$/) seen_description = 1
+        else bad = 1
+        next
+      }
+      /^  [a-z_]{1,64}: "#[0-9a-fA-F]{6}"$/ { colors++; next }
+      { bad = 1 }
+      END { exit (bad || !seen_colors || colors == 0) }
+    ' "$skin"
+}
+
+# The check has to cover the bytes that get published, and the theme can change
+# underneath between the two, so a private copy is taken and that is checked.
+snapshot_dir=$(mktemp -d)
+trap 'rm -rf "$snapshot_dir"' EXIT
+HERMES_SNAPSHOT="$snapshot_dir/$HERMES_SKIN_NAME.yaml"
+
+take_snapshot() {
+  cp "$HERMES_SOURCE_PATH" "$HERMES_SNAPSHOT" 2>/dev/null && skin_is_well_formed "$HERMES_SNAPSHOT"
+}
+
+if ! take_snapshot; then
+  echo "Skipping Hermes skin: $(basename "$HERMES_SOURCE_PATH") is not a plain color palette." >&2
+  exit 0
+fi
+
+# The gateway reads the file whole on an mtime change, so the write is atomic;
+# -T so a directory at the skin's path is an error rather than a destination.
+publish_skin() {
+  local skins_dir="$1"
+  local tmp
+
+  mkdir -p "$skins_dir" 2>/dev/null || return 1
+  tmp=$(mktemp "$skins_dir/$HERMES_SKIN_NAME.yaml.XXXXXX" 2>/dev/null) || return 1
+  if ! cp "$HERMES_SNAPSHOT" "$tmp" 2>/dev/null || ! mv -T "$tmp" "$skins_dir/$HERMES_SKIN_NAME.yaml" 2>/dev/null; then
+    rm -f "$tmp"
+    return 1
+  fi
+}
+
+# A profile is a Hermes home of its own; existing ones get the skin, none are
+# made, and one that cannot take it does not cost the others.
+publish_skin_everywhere() {
+  local profile
+
+  publish_skin "$HERMES_HOME/skins" || {
+    echo "Could not publish the Hermes skin to $HERMES_HOME/skins." >&2
+    return 1
+  }
+
+  for profile in "$HERMES_HOME"/profiles/*/; do
+    [[ -d $profile ]] || continue
+    publish_skin "${profile%/}/skins" || note "Could not publish the skin to the Hermes profile $(basename "$profile")."
+  done
+}
+
+publish_skin_everywhere
+
+# Hermes reads the config of the profile named in active_profile; the profile
+# exists once its directory does, with or without a config of its own.
+active_config_path() {
+  local profile
+
+  profile=$(cat "$HERMES_HOME/active_profile" 2>/dev/null || true)
+  profile=${profile,,}
+
+  if [[ -n $profile && $profile != "default" && -d $HERMES_HOME/profiles/$profile ]]; then
+    echo "$HERMES_HOME/profiles/$profile/config.yaml"
+  else
+    echo "$HERMES_CONFIG_PATH"
+  fi
+}
+
+# A theme switch finishes the hand-over only for the app Omarchy installed, and
+# only Hermes' default is ever replaced, so a config plainly naming another skin
+# ends it here without starting Hermes. Anything less plain is for Hermes to read.
+if (( HERMES_ACTIVATE == 0 )); then
+  omarchy-pkg-present hermes-desktop || exit 0
+
+  skin_line=$(grep -m1 -x '  skin: .*' "$(active_config_path)" 2>/dev/null || true)
+  case "${skin_line#  skin: }" in
+    "" | default | null | true | false | *[!A-Za-z0-9_-]*) ;;
+    *) exit 0 ;;
+  esac
+fi
+
+# Omarchy's cold stub installs Hermes when run, so ask the probe before running it.
+if ! omarchy-install-hermes-cli --check 2>/dev/null; then
+  note "Hermes is not ready, so the Omarchy skin is published but not active."
+  note "Once Hermes runs, activate it with: hermes config set display.skin $HERMES_SKIN_NAME"
+  exit 0
+fi
+
+# Only Hermes' own default is replaced, so a skin chosen in Hermes stays; an
+# answer that did not come is not a default.
+if ! current_skin=$(timeout 15 "$HERMES_COMMAND" config get display.skin 2>/dev/null); then
+  note "Hermes did not say which skin it is on, so the Omarchy skin is published but not active."
+  exit 0
+fi
+
+if [[ -n $current_skin && $current_skin != "default" && $current_skin != "$HERMES_SKIN_NAME" ]]; then
+  note "Hermes is set to the '$current_skin' skin; leaving it. Switch with: hermes config set display.skin $HERMES_SKIN_NAME"
+  exit 0
+fi
+
+# Hermes' own writer: it updates the active profile's config and touches the
+# skin file so a running gateway broadcasts the change. A refusal is cosmetic.
+if ! timeout 30 "$HERMES_COMMAND" config set display.skin "$HERMES_SKIN_NAME" >/dev/null 2>&1; then
+  note "Hermes refused to switch skins, so the Omarchy skin is published but not active."
+  exit 0
+fi
+
+note "Hermes is on the Omarchy skin."
+
+# The desktop applies a skin only from a broadcast, and a config written before
+# the gateway seeded its watcher goes unannounced; a later write is announced.
+# The theme may have changed underneath in the meantime, so it is checked again.
+if (( HERMES_WAIT == 1 )); then
+  sleep 60
+
+  if take_snapshot; then
+    publish_skin_everywhere
+  fi
+fi

bin/omarchy-theme-set-t3code

@@ -0,0 +1,34 @@
+#!/bin/bash
+
+# omarchy:summary=Sync the generated Omarchy theme to T3 Code
+# omarchy:hidden=true
+
+set -euo pipefail
+
+T3CODE_SOURCE_PATH="$HOME/.local/state/omarchy/current/theme/t3code.json"
+T3CODE_HOME="${T3CODE_HOME:-$HOME/.t3}"
+T3CODE_STATE_DIR="$T3CODE_HOME/userdata"
+# The filename is the theme id T3 Code shows and `t3 theme set` accepts, and
+# it stays stable while the colors change underneath on every theme switch.
+T3CODE_THEME_PATH="$T3CODE_STATE_DIR/themes/omarchy.json"
+
+[[ -f $T3CODE_SOURCE_PATH ]] || exit 0
+
+# A theme without an accent or a background leaves its placeholder unresolved.
+# Publishing that would only make T3 Code reject the file, so skip instead and
+# leave the previous palette in place.
+if grep -q '{{' "$T3CODE_SOURCE_PATH"; then
+  echo "Skipping T3 Code theme: $(basename "$T3CODE_SOURCE_PATH") has unresolved colors." >&2
+  exit 0
+fi
+
+# Only follow an install that already exists. Creating the directory here would
+# leave a stray T3 Code state dir on machines that do not run it.
+[[ -d $T3CODE_STATE_DIR ]] || exit 0
+
+# T3 Code watches this file and retints every connected client on change, so
+# the write has to be atomic: a half-written file would read as invalid.
+mkdir -p "$(dirname "$T3CODE_THEME_PATH")"
+tmp=$(mktemp "$T3CODE_THEME_PATH.XXXXXX")
+cp "$T3CODE_SOURCE_PATH" "$tmp"
+mv "$tmp" "$T3CODE_THEME_PATH"

bin/omarchy-theme-switcher

@@ -22,7 +22,7 @@ find_preview() {
   local theme_path="$1"
   local preview preview_name
 
-  for preview_name in preview.png preview.jpg preview.jpeg preview.webp preview.gif preview.bmp; do
+  for preview_name in preview.png preview.jpg preview.jpeg preview.webp preview.gif preview.bmp preview.mp4 preview.m4v preview.mov preview.webm preview.mkv preview.avi; do
     preview=$(find -L "$theme_path" -maxdepth 1 -type f -iname "$preview_name" -print -quit 2>/dev/null)
 
     if [[ -n $preview ]]; then
@@ -32,7 +32,10 @@ find_preview() {
   done
 
   if [[ -d $theme_path/backgrounds ]]; then
-    find -L "$theme_path/backgrounds" -maxdepth 1 -type f \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' -o -iname '*.gif' -o -iname '*.bmp' -o -iname '*.webp' \) -print 2>/dev/null | sort | head -n 1
+    find -L "$theme_path/backgrounds" -maxdepth 1 -type f \
+      \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' -o -iname '*.gif' -o -iname '*.bmp' -o -iname '*.webp' \
+         -o -iname '*.mp4' -o -iname '*.m4v' -o -iname '*.mov' -o -iname '*.webm' -o -iname '*.mkv' -o -iname '*.avi' \) \
+      -print 2>/dev/null | sort | head -n 1
   fi
 }
 
@@ -48,7 +51,7 @@ add_theme_preview() {
   ln -s "$preview" "$preview_dir/$theme_name.$extension"
 }
 
-fast_signature="v1"$'\n'
+fast_signature="v2"$'\n'
 for theme_dir in "$USER_THEMES_PATH" "$OMARCHY_THEMES_PATH"; do
   if [[ -d $theme_dir ]]; then
     fast_signature+="$theme_dir:$(stat -Lc '%Y' "$theme_dir")"$'\n'
@@ -104,7 +107,7 @@ fi
 
 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
+for extension in png jpg jpeg webp gif bmp mp4 m4v mov webm mkv avi; do
   if [[ -e $preview_dir/$current_theme.$extension ]]; then
     selected_preview="$preview_dir/$current_theme.$extension"
     break

bin/omarchy-toggle-fullscreen-desktop

@@ -0,0 +1,27 @@
+#!/bin/bash
+
+# omarchy:summary=Toggle a full screen desktop: hide the top bar and remove the window gaps together
+# omarchy:args=[toggle|on|off]
+# omarchy:examples=omarchy toggle fullscreen desktop | omarchy toggle fullscreen desktop off | omarchy toggle fullscreen desktop on
+
+ACTION="${1:-toggle}"
+
+case $ACTION in
+  toggle|"")
+    # Only leave full screen when both halves are already in it, so a lone bar
+    # or a lone gap toggle is pulled into line rather than flipped away.
+    if omarchy-toggle-enabled bar-off && omarchy-hyprland-toggle-enabled window-no-gaps; then
+      ACTION="off"
+    else
+      ACTION="on"
+    fi
+    ;;
+  on|off) ;;
+  *)
+    echo "Usage: omarchy-toggle-fullscreen-desktop [toggle|on|off]" >&2
+    exit 1
+    ;;
+esac
+
+omarchy-toggle-bar "$ACTION"
+omarchy-hyprland-toggle window-no-gaps "$ACTION"

bin/omarchy-toggle-hybrid-gpu

@@ -3,6 +3,35 @@
 # omarchy:summary=Toggle dedicated vs integrated GPU mode via supergfxd (for hybrid gpu laptops, like Asus G14).
 # omarchy:requires-sudo=true
 
+install_root_file() {
+  local source="$1"
+  local destination="$2"
+  local mode="$3"
+  local stage
+
+  stage=$(sudo /usr/bin/mktemp -- "${destination%/*}/.${destination##*/}.omarchy.XXXXXX") || return 1
+  safe_stage_path "$stage" "$destination" || return 1
+
+  if sudo /usr/bin/install -m "$mode" -o root -g root -T "$source" "$stage" &&
+    sudo /usr/bin/mv -Tf -- "$stage" "$destination"; then
+    return 0
+  else
+    safe_stage_path "$stage" "$destination" && sudo /usr/bin/rm -f -- "$stage"
+    return 1
+  fi
+}
+
+safe_stage_path() {
+  local stage="$1"
+  local destination="$2"
+  local prefix suffix
+
+  prefix="${destination%/*}/.${destination##*/}.omarchy."
+  [[ $stage == "$prefix"* ]] || return 1
+  suffix=${stage#"$prefix"}
+  [[ $suffix =~ ^[[:alnum:]]{6}$ ]]
+}
+
 if omarchy-cmd-missing supergfxctl; then
   omarchy-pkg-add supergfxctl
 
@@ -54,18 +83,31 @@ case "$gpu_mode" in
   ;;
 "Hybrid")
   if gum confirm "Use only integrated GPU and reboot?"; then
-    # Switch to integrated mode and ensure vfio is enabled (needed for sleep/wake trick)
-    sudo sed -i "s/\"mode\": \".*\"/\"mode\": \"Integrated\"/" /etc/supergfxd.conf
-    sudo sed -i 's/"vfio_enable": false/"vfio_enable": true/' /etc/supergfxd.conf
-
-    # Force igpu mode after system sleep (or dgpu could get activated)
-    sudo mkdir -p /usr/lib/systemd/system-sleep
-    sudo cp -p "$OMARCHY_PATH/default/systemd/system-sleep/force-igpu" /usr/lib/systemd/system-sleep/
-
     # Delay supergfxd startup to avoid race condition with display manager
     # that can cause system freeze when booting in Integrated mode
     sudo mkdir -p /etc/systemd/system/supergfxd.service.d
-    sudo cp -p "$OMARCHY_PATH/default/systemd/system/supergfxd.service.d/delay-start.conf" /etc/systemd/system/supergfxd.service.d/
+    if ! install_root_file "$OMARCHY_PATH/default/systemd/system/supergfxd.service.d/delay-start.conf" \
+      /etc/systemd/system/supergfxd.service.d/delay-start.conf 0644; then
+      echo "Could not install the supergfxd startup-delay override" >&2
+      exit 1
+    fi
+
+    # Publish the self-guarding sleep hook before enabling Integrated mode. It
+    # remains inert while the config says Hybrid, so any failed step is safe to
+    # retry without leaving the GPU config partially switched.
+    sudo mkdir -p /usr/lib/systemd/system-sleep
+    if ! install_root_file "$OMARCHY_PATH/default/systemd/system-sleep/force-igpu" \
+      /usr/lib/systemd/system-sleep/force-igpu 0755; then
+      echo "Could not install the force-igpu system-sleep hook" >&2
+      exit 1
+    fi
+
+    # Switch both settings in one atomic config rewrite only after every
+    # supporting file has been installed successfully.
+    sudo sed -i \
+      -e 's/"mode": ".*"/"mode": "Integrated"/' \
+      -e 's/"vfio_enable": false/"vfio_enable": true/' \
+      /etc/supergfxd.conf
 
     omarchy-system-reboot
   fi

bin/omarchy-upgrade-to-quattro

@@ -175,7 +175,10 @@ target_home=$(getent passwd "$target_user" | cut -d: -f6)
 [[ -n $target_home && -d $target_home ]] || fail "Home directory for '$target_user' was not found."
 target_uid=$(id -u "$target_user")
 target_runtime_dir="/run/user/$target_uid"
-package_path="/usr/share/omarchy/bin:/usr/local/bin:/usr/bin:/bin:$target_home/.local/bin"
+# User-local commands are needed only after dropping to the target user. Never
+# expose their search path to commands run through as_root.
+root_path=/usr/share/omarchy/bin:/usr/local/bin:/usr/bin:/bin
+package_path="$root_path:$target_home/.local/bin"
 
 as_root() {
   if (( EUID == 0 )); then
@@ -661,7 +664,7 @@ configure_lock_authentication() {
   as_root env \
     OMARCHY_INSTALL_USER="$target_user" \
     OMARCHY_PATH=/usr/share/omarchy \
-    PATH="$package_path" \
+    PATH="$root_path" \
     "$apply_lock"
 }
 
@@ -1287,7 +1290,7 @@ apply_firewall_defaults() {
   fi
 
   log "Applying Omarchy firewall defaults"
-  as_root env OMARCHY_PATH=/usr/share/omarchy PATH="$package_path" \
+  as_root env OMARCHY_PATH=/usr/share/omarchy PATH="$root_path" \
     bash -euo pipefail "$firewall_script" ||
     warn "Could not apply firewall defaults; run 'sudo bash $firewall_script' after reboot."
 }
@@ -2078,7 +2081,10 @@ for file in \
 done
 ln -snf "$HOME/.local/state/omarchy/current/theme/btop.theme" "$HOME/.config/btop/themes/current.theme"
 if [[ ! -e $HOME/.local/state/omarchy/current/background && -d $HOME/.local/state/omarchy/current/theme/backgrounds ]]; then
-  background=$(find "$HOME/.local/state/omarchy/current/theme/backgrounds" -maxdepth 1 -type f \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' -o -iname '*.webp' \) | sort | head -n1)
+  background=$(find "$HOME/.local/state/omarchy/current/theme/backgrounds" -maxdepth 1 -type f \
+    \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' -o -iname '*.webp' \
+       -o -iname '*.mp4' -o -iname '*.m4v' -o -iname '*.mov' -o -iname '*.webm' -o -iname '*.mkv' -o -iname '*.avi' \) \
+    | sort | head -n1)
   [[ -n ${background:-} ]] && ln -snf "$background" "$HOME/.local/state/omarchy/current/background"
 fi
 

config/hypr/bindings.lua

@@ -1,5 +1,5 @@
--- Keep only your personal keybinding overrides here. Add new bindings or
--- unbind defaults before replacing them.
+-- Keep only your personal keybinding overrides here. Add new bindings with
+-- o.bind or replace defaults with o.rebind.
 
 -- See current bindings and descriptions:
 --   omarchy menu keybindings --print
@@ -15,10 +15,9 @@
 -- Add a new binding.
 -- o.bind("SUPER + SHIFT + R", "SSH", "alacritty -e ssh your-server")
 
--- Change an existing binding by unbinding it first, then binding the key again.
--- This example changes SUPER+SPACE from the launcher to the Omarchy root menu.
--- hl.unbind("SUPER + SPACE")
--- o.bind("SUPER + SPACE", "Omarchy menu", "omarchy-menu toggle root")
+-- Change an existing binding. o.rebind takes the same arguments as o.bind.
+-- This example replaces the default file manager with Flea.
+-- o.rebind("SUPER + SHIFT + F", "File manager", { launch = "flea" })
 
 -- Disable a default binding without replacing it.
 -- hl.unbind("SUPER + SHIFT + B")

config/hypr/input.lua

@@ -45,7 +45,8 @@
 -- })
 
 -- App-specific touchpad scroll speeds.
--- o.window("(Alacritty|kitty|foot)", { scroll_touchpad = 1.5 })
+-- o.window("(Alacritty|kitty)", { scroll_touchpad = 1.5 })
+-- o.window("foot", { scroll_touchpad = 2.0 })
 -- o.window("com.mitchellh.ghostty", { scroll_touchpad = 0.2 })
 
 -- Enable touchpad gestures for changing workspaces.

config/kitty/kitty.conf

@@ -1,35 +1,21 @@
+# Remove the include below to disconnect Kitty from Omarchy's theming system.
 include ~/.local/state/omarchy/current/theme/kitty.conf
 
+# Settings below override Omarchy's defaults in /etc/xdg/kitty/kitty.conf.
+# Learn more: https://sw.kovidgoyal.net/kitty/conf/
+
 # Font
-font_family JetBrainsMono Nerd Font
-bold_italic_font auto
-font_size        9.0
+# font_family JetBrainsMono Nerd Font
+# font_size 12
 
-# Window
-window_padding_width 14
-hide_window_decorations yes
-confirm_os_window_close 0
+# Window padding
+# window_padding_width 14
 
-# Keybindings
-map ctrl+insert copy_to_clipboard
-map shift+insert paste_from_clipboard
-# Send Shift+Enter as CSI-u so TUIs can distinguish it from Enter.
-map shift+enter send_text all \e[13;2u
-# Kitty legacy encoding sends Alt+Shift+Enter the same as Alt+Enter; send CSI-u so tmux can match M-S-Enter.
-map alt+shift+enter send_text all \e[13;4u
+# Unmap a shortcut, passing it through to the terminal application
+# map ctrl+insert
 
-# Allow remote access
-allow_remote_control yes
-listen_on unix:${XDG_RUNTIME_DIR}/omarchy-kitty-{kitty_pid}
+# Set or replace a shortcut
+# map ctrl+shift+c copy_to_clipboard
 
-# Aesthetics
-cursor_shape block
-cursor_blink_interval 0
-shell_integration no-cursor
-enable_audio_bell no
-
-# Minimal Tab bar styling
-tab_bar_edge                bottom
-tab_bar_style               powerline
-tab_powerline_style         slanted
-tab_title_template          {title}{' :{}:'.format(num_windows) if num_windows > 1 else ''}
+# Remove all inherited shortcuts, including Kitty's built-in shortcuts
+# clear_all_shortcuts yes

default/agents/skills/diagnose-crash/reporting.md

@@ -40,8 +40,8 @@ useful; filing there yourself is not part of this.
 A duplicate issue costs a maintainer more time than no report at all.
 
 ```bash
-gh search issues --repo basecamp/omarchy "<program> crash"
-gh issue list --repo basecamp/omarchy --state all --search "<signal> <program>"
+gh search issues --repo omacom/omarchy "<program> crash"
+gh issue list --repo omacom/omarchy --state all --search "<signal> <program>"
 ```
 
 Search on the crashing program, the signal, and distinctive symbols from the
@@ -59,7 +59,7 @@ more than another duplicate.
 If a plausible match comes back, read it properly first:
 
 ```bash
-gh issue view <number> --repo basecamp/omarchy --comments
+gh issue view <number> --repo omacom/omarchy --comments
 ```
 
 Confirm it is genuinely the same failure. The same program crashing is not the
@@ -74,7 +74,7 @@ A comment that only says the bug happens to you too is noise. If that is all you
 have, tell the user so and file nothing.
 
 ```bash
-gh issue comment <number> --repo basecamp/omarchy --body "..."
+gh issue comment <number> --repo omacom/omarchy --body "..."
 ```
 
 ## Filing a new issue
@@ -82,7 +82,7 @@ gh issue comment <number> --repo basecamp/omarchy --body "..."
 Only when the search turns up nothing that matches:
 
 ```bash
-gh issue create --repo basecamp/omarchy --title "..." --body "..."
+gh issue create --repo omacom/omarchy --title "..." --body "..."
 ```
 
 Include what happened, what was expected, steps to reproduce, system details from

default/agents/skills/omarchy/SKILL.md

@@ -13,7 +13,7 @@ description: >
 
 # Omarchy Skill
 
-Manage [Omarchy](https://omarchy.org/) Linux systems - a beautiful, modern, opinionated Arch Linux distribution with Hyprland.
+Manage [Omarchy](https://omarchy.org/) Linux systems - a beautiful, fun, agentic Arch Linux distribution with Hyprland.
 
 This skill is for end-user customization on installed systems.
 It is not for contributing to Omarchy source code.
@@ -278,7 +278,7 @@ This skill intentionally does not cover Omarchy source development. Do not use t
 ## Example Requests
 
 - "Change my theme to catppuccin" -> `omarchy theme set catppuccin`
-- "Add a keybinding for Super+E to open file manager" -> Check existing bindings first, call `hl.unbind` if needed, then `o.bind` in `~/.config/hypr/bindings.lua`
+- "Add a keybinding for Super+E to open file manager" -> Check existing bindings first, then use `o.rebind` to replace one or `o.bind` to add one in `~/.config/hypr/bindings.lua`
 - "Configure my external monitor" -> Edit `~/.config/hypr/monitors.lua`
 - "Make the window gaps smaller" -> Edit `~/.config/hypr/looknfeel.lua`
 - "Turn on night light" -> `omarchy toggle nightlight` (for time-based schedules, edit `~/.config/hypr/hyprsunset.conf` profiles, then `omarchy restart hyprsunset`)

default/agents/skills/omarchy/contributing.md

@@ -3,13 +3,13 @@
 Read this when the user wants to report an Omarchy bug, suggest a feature, or
 contribute a fix upstream.
 
-Omarchy lives at https://github.com/basecamp/omarchy. Route requests to the
+Omarchy lives at https://github.com/omacom/omarchy. Route requests to the
 right place:
 
 - **Verified bugs** -> GitHub issues. Issues are for validated bugs only, not
   support requests.
 - **Feature ideas and suggestions** ->
-  https://github.com/basecamp/omarchy/discussions/categories/suggestions
+  https://github.com/omacom/omarchy/discussions/categories/suggestions
 - **Support and "is this a bug?" questions** -> the Discord community at
   https://omarchy.org/discord. Start here when the problem isn't clearly a bug
   in Omarchy itself.
@@ -43,7 +43,7 @@ For screen-recording failures specifically, rerun with
 File the issue with `gh` when available:
 
 ```bash
-gh issue create --repo basecamp/omarchy --title "..." --body "..."
+gh issue create --repo omacom/omarchy --title "..." --body "..."
 ```
 
 Include: what happened, what was expected, steps to reproduce, system details,
@@ -54,7 +54,7 @@ the debug log URL (or attached log), and the capture.
 Never develop against `/usr/share/omarchy`. Clone a working copy instead:
 
 ```bash
-gh repo fork basecamp/omarchy --clone
+gh repo fork omacom/omarchy --clone
 cd omarchy
 ```
 

default/agents/skills/omarchy/hyprland.md

@@ -43,18 +43,16 @@ View current bindings: `omarchy menu keybindings --print`
 **IMPORTANT: When re-binding an existing key:**
 
 1. First check existing bindings: `omarchy menu keybindings --print`
-2. If the key is already bound, you MUST call `hl.unbind(...)` BEFORE the new `o.bind(...)`
+2. If the key is already bound, use `o.rebind(...)` to remove the existing binding and add its replacement. It takes the same arguments as `o.bind(...)`.
 3. Inform the user what the key was previously bound to
 
 Example - rebinding SUPER+F (which is bound to fullscreen by default):
 ```lua
--- Unbind existing SUPER+F (was: fullscreen)
-hl.unbind("SUPER + F")
--- New binding for file manager
-o.bind("SUPER + F", "File manager", { launch = "nautilus" })
+-- Replace SUPER+F (was: fullscreen) with the file manager.
+o.rebind("SUPER + F", "File manager", { launch = "nautilus" })
 ```
 
-Always tell the user: "Note: SUPER+F was previously bound to fullscreen. I've added an unbind to override it."
+Tell the user which action was replaced. Use `hl.unbind(...)` to remove a binding without replacing it.
 
 ## Display/Monitors
 

default/fonts/omarchy/README.md

@@ -12,6 +12,10 @@ The private-use glyphs in `omarchy.ttf` are:
 - `U+E907` — Ollama, from <https://simpleicons.org/icons/ollama.svg>
 - `U+E908` — T3 Code, traced from the app icon in <https://aur.archlinux.org/cgit/aur.git/plain/t3code-icon.png?h=t3code-bin>, since upstream publishes no monochrome SVG
 - `U+E909` — Ori, from <https://openrouter.ai/brand/v2/openrouter-glyph-dark.svg>, OpenRouter's own mark: Ori ships no separate logo and its product page uses this one
+- `U+E90A` — Hermes, Font Awesome's staff-snake (CC BY 4.0) from <https://fontawesome.com/icons/staff-snake>, the mark Hermes serves as its favicon: their app icon is a portrait that reads as a smudge at menu size
+- `U+E90B` — Perplexity, from <https://simpleicons.org/icons/perplexity.svg>
+- `U+E90C` — OpenClaw, traced from the lobster mascot the openclaw package ships as `dist/control-ui/favicon.svg`, since upstream publishes no monochrome SVG
+- `U+E90D` — Cursor, from <https://simpleicons.org/icons/cursor.svg>
 
 The agent marks are monochrome so the menu can render them using the active
 theme's foreground and selection colors.

default/hypr/apps/hermes.lua

@@ -0,0 +1,7 @@
+-- Hermes Desktop's frameless HUD manages its own geometry.
+o.window({ class = "^Hermes$", title = "^Hermes HUD$" }, {
+  tag = "-default-opacity",
+  float = true,
+  border_size = 0,
+  opacity = "1 1",
+})

default/hypr/bindings/utilities.lua

@@ -19,6 +19,7 @@ o.bind("SUPER + SHIFT + CTRL + SPACE", "Theme menu", "omarchy-menu toggle theme"
 o.bind("SUPER + BACKSPACE", "Toggle window transparency", "omarchy-hyprland-window-transparency-toggle")
 o.bind("SUPER + SHIFT + BACKSPACE", "Toggle window gaps", "omarchy-hyprland-window-gaps-toggle")
 o.bind("SUPER + CTRL + BACKSPACE", "Toggle single-window square aspect", "omarchy-hyprland-window-single-square-aspect-toggle")
+o.bind_toggle("SUPER + CTRL + ALT + F", "Toggle full screen desktop", "fullscreen-desktop")
 
 -- xkbcommon names the comma keysym "comma"; the upper-case "COMMA" does not match.
 o.bind("SUPER + comma", "Dismiss last notification", "omarchy-shell notifications dismissOne")

default/hypr/helpers.lua

@@ -105,6 +105,11 @@ function o.bind(keys, description, dispatcher, options)
   hl.bind(keys, dispatcher, opts)
 end
 
+function o.rebind(keys, description, dispatcher, options)
+  hl.unbind(keys)
+  o.bind(keys, description, dispatcher, options)
+end
+
 function o.launch(command)
   return "uwsm-app -- " .. command
 end

default/hypr/input.lua

@@ -75,5 +75,7 @@ hl.config({
 })
 
 -- Scroll nicely in the terminal.
-o.window("(Alacritty|kitty|foot)", { scroll_touchpad = 1.5 })
+o.window("(Alacritty|kitty)", { scroll_touchpad = 1.5 })
+-- foot only applies its scrollback multiplier to wheel clicks, not precise touchpad scrolling.
+o.window("foot", { scroll_touchpad = 2.0 })
 o.window("com.mitchellh.ghostty", { scroll_touchpad = 0.2 })

default/omarchy/launcher.hides

@@ -12,6 +12,7 @@ fcitx5-configtool
 fcitx5-wayland-launcher
 foot-server
 footclient
+hermes
 java-java-openjdk
 jconsole-java-openjdk
 jshell-java-openjdk

default/omarchy/omarchy-menu.jsonc

@@ -140,8 +140,12 @@
   "setup.default.agent.codex": {"icon":"","iconFont":"omarchy","label":"Codex","checked":"[[ \"$(omarchy-default-agent)\" == \"codex\" ]]","action":"omarchy-default-agent codex"},
   "setup.default.agent.copilot": {"icon":"","label":"Copilot","checked":"[[ \"$(omarchy-default-agent)\" == \"copilot\" ]]","action":"omarchy-default-agent copilot"},
   "setup.default.agent.crush": {"icon":"󰋑","label":"Crush","checked":"[[ \"$(omarchy-default-agent)\" == \"crush\" ]]","action":"omarchy-default-agent crush"},
+  "setup.default.agent.cursor-agent": {"icon":"","iconFont":"omarchy","label":"Cursor CLI","checked":"[[ \"$(omarchy-default-agent)\" == \"cursor-agent\" ]]","action":"omarchy-default-agent cursor-agent"},
   "setup.default.agent.grok": {"icon":"","iconFont":"omarchy","label":"Grok","checked":"[[ \"$(omarchy-default-agent)\" == \"grok\" ]]","action":"omarchy-default-agent grok"},
+  "setup.default.agent.hermes": {"icon":"","iconFont":"omarchy","label":"Hermes","checked":"[[ \"$(omarchy-default-agent)\" == \"hermes\" ]]","action":"omarchy-default-agent hermes"},
+  "setup.default.agent.muse": {"icon":"󰛤","label":"Muse Code","checked":"[[ \"$(omarchy-default-agent)\" == \"muse\" ]]","action":"omarchy-default-agent muse"},
   "setup.default.agent.omp": {"icon":"","iconFont":"omarchy","label":"omp","checked":"[[ \"$(omarchy-default-agent)\" == \"omp\" ]]","action":"omarchy-default-agent omp"},
+  "setup.default.agent.openclaw": {"icon":"","iconFont":"omarchy","label":"OpenClaw","checked":"[[ \"$(omarchy-default-agent)\" == \"openclaw\" ]]","action":"omarchy-default-agent openclaw"},
   "setup.default.agent.opencode": {"icon":"","iconFont":"omarchy","label":"OpenCode","checked":"[[ \"$(omarchy-default-agent)\" == \"opencode\" ]]","action":"omarchy-default-agent opencode"},
   "setup.default.agent.ori": {"icon":"","iconFont":"omarchy","label":"Ori","checked":"[[ \"$(omarchy-default-agent)\" == \"ori\" ]]","action":"omarchy-default-agent ori"},
   "setup.default.agent.pi": {"icon":"","iconFont":"omarchy","label":"Pi","checked":"[[ \"$(omarchy-default-agent)\" == \"pi\" ]]","action":"omarchy-default-agent pi"},
@@ -161,7 +165,7 @@
   "setup.default.editor": {"icon":"","label":"Editor","title":"Default Editor"},
   "setup.default.editor.neovim": {"icon":"","label":"Neovim","checked":"[[ \"$(omarchy-default-editor)\" == \"nvim\" ]]","action":"omarchy-default-editor nvim"},
   "setup.default.editor.vscode": {"icon":"","label":"VSCode","checked":"[[ \"$(omarchy-default-editor)\" == \"code\" ]]","action":"omarchy-default-editor code"},
-  "setup.default.editor.cursor": {"icon":"","label":"Cursor","checked":"[[ \"$(omarchy-default-editor)\" == \"cursor\" ]]","action":"omarchy-default-editor cursor"},
+  "setup.default.editor.cursor": {"icon":"","iconFont":"omarchy","label":"Cursor","checked":"[[ \"$(omarchy-default-editor)\" == \"cursor\" ]]","action":"omarchy-default-editor cursor"},
   "setup.default.editor.zed": {"icon":"","label":"Zed","checked":"[[ \"$(omarchy-default-editor)\" == \"zeditor\" ]]","action":"omarchy-default-editor zed"},
   "setup.default.editor.sublime": {"icon":"","label":"Sublime Text","checked":"[[ \"$(omarchy-default-editor)\" == \"sublime_text\" ]]","action":"omarchy-default-editor sublime_text"},
   "setup.default.editor.helix": {"icon":"","label":"Helix","checked":"[[ \"$(omarchy-default-editor)\" == \"helix\" ]]","action":"omarchy-default-editor helix"},
@@ -226,7 +230,7 @@
   "install.service.bitwarden": {"icon":"󰟵","label":"Bitwarden","disabled":"omarchy-pkg-present bitwarden","action":"omarchy-install-and-launch Bitwarden 'bitwarden bitwarden-cli' bitwarden"},
   "install.service.chromium-account": {"icon":"","label":"Chromium Account","when":"[[ -f ~/.config/chromium-flags.conf ]]","disabled":"grep -q oauth2-client-id ~/.config/chromium-flags.conf","action":"omarchy-launch-floating-terminal-with-presentation omarchy-install-chromium-google-account"},
   "install.editor.vscode": {"icon":"","label":"VSCode","disabled":"omarchy-pkg-present visual-studio-code-bin","action":"omarchy-launch-floating-terminal-with-presentation omarchy-install-editor-vscode"},
-  "install.editor.cursor": {"icon":"","label":"Cursor","disabled":"omarchy-pkg-present cursor-bin","action":"omarchy-install-and-launch Cursor cursor-bin cursor"},
+  "install.editor.cursor": {"icon":"","iconFont":"omarchy","label":"Cursor","disabled":"omarchy-pkg-present cursor-bin","action":"omarchy-install-and-launch Cursor cursor-bin cursor"},
   "install.editor.zed": {"icon":"","label":"Zed","disabled":"omarchy-pkg-present zed","action":"omarchy-launch-floating-terminal-with-presentation omarchy-install-editor-zed"},
   "install.editor.sublime": {"icon":"","label":"Sublime Text","disabled":"omarchy-pkg-present sublime-text-4","action":"omarchy-install-and-launch 'Sublime Text' sublime-text-4 sublime_text"},
   "install.editor.helix": {"icon":"","label":"Helix","disabled":"omarchy-pkg-present helix","action":"omarchy-launch-floating-terminal-with-presentation omarchy-install-editor-helix"},
@@ -239,9 +243,12 @@
   "install.ai.chatgpt": {"icon":"","iconFont":"omarchy","label":"ChatGPT Desktop","disabled":"omarchy-pkg-present openai-codex-desktop","action":"omarchy-launch-floating-terminal-with-presentation omarchy-install-ai-chatgpt"},
   "install.ai.dictation": {"icon":"","label":"Dictation","disabled":"omarchy-pkg-present voxtype-bin","action":"omarchy-launch-floating-terminal-with-presentation omarchy-voxtype-install"},
   "install.ai.grok-bot": {"icon":"","iconFont":"omarchy","label":"Grok Bot","disabled":"omarchy-pkg-present grok-bot","action":"omarchy-install-and-launch 'Grok Bot' grok-bot grok-bot"},
+  "install.ai.hermes": {"icon":"","iconFont":"omarchy","label":"Hermes Desktop","disabled":"omarchy-pkg-present hermes-desktop","action":"omarchy-launch-floating-terminal-with-presentation omarchy-install-ai-hermes"},
   "install.ai.lm-studio": {"icon":"","iconFont":"omarchy","label":"LM Studio","disabled":"omarchy-pkg-present lmstudio-bin","action":"omarchy-install-app 'LM Studio' lmstudio-bin"},
   "install.ai.ollama": {"icon":"","iconFont":"omarchy","label":"Ollama","disabled":"omarchy-cmd-present ollama","action":"if omarchy-cmd-present nvidia-smi; then ollama_pkg=ollama-cuda; elif omarchy-cmd-present rocminfo; then ollama_pkg=ollama-rocm; else ollama_pkg=ollama; fi; omarchy-install-app Ollama \"$ollama_pkg\""},
-  "install.ai.t3-code": {"icon":"","iconFont":"omarchy","label":"T3 Code","disabled":"omarchy-pkg-present t3code-bin","action":"omarchy-install-and-launch 'T3 Code' t3code-bin t3code"},
+  "install.ai.openclaw": {"icon":"","iconFont":"omarchy","label":"OpenClaw","disabled":"omarchy-pkg-present openclaw","action":"omarchy-launch-floating-terminal-with-presentation omarchy-install-ai-openclaw"},
+  "install.ai.perplexity": {"icon":"","iconFont":"omarchy","label":"Perplexity","disabled":"omarchy-pkg-present perplexity","action":"omarchy-install-and-launch Perplexity perplexity perplexity"},
+  "install.ai.t3-code": {"icon":"","iconFont":"omarchy","label":"T3 Code","disabled":"omarchy-pkg-present t3code-bin","action":"omarchy-launch-floating-terminal-with-presentation omarchy-install-ai-t3-code"},
   "install.gaming.steam": {"icon":"","label":"Steam","disabled":"omarchy-pkg-present steam","action":"omarchy-launch-floating-terminal-with-presentation omarchy-install-gaming-steam"},
   "install.gaming.retroarch": {"icon":"󰯉","label":"RetroArch","disabled":"omarchy-pkg-present retroarch","action":"omarchy-launch-floating-terminal-with-presentation omarchy-install-gaming-retroarch"},
   "install.gaming.minecraft": {"icon":"󰍳","label":"Minecraft","disabled":"omarchy-pkg-present minecraft-launcher","action":"omarchy-install-and-launch Minecraft minecraft-launcher minecraft-launcher"},
@@ -292,6 +299,7 @@
   "remove.security.fido2": {"icon":"","label":"Fido2","when":"omarchy-pkg-present pam-u2f","action":"omarchy-launch-floating-terminal-with-presentation omarchy-remove-security-fido2"},
   "remove.security.sshd": {"icon":"󰣀","label":"SSHD","when":"systemctl is-enabled --quiet sshd","action":"omarchy-launch-floating-terminal-with-presentation omarchy-remove-security-sshd"},
   "remove.security.sudoless-docker": {"icon":"󰡨","label":"Sudoless Docker","when":"! omarchy-sudo-docker --configured","action":"omarchy-launch-floating-terminal-with-presentation omarchy-remove-security-sudoless-docker"},
+  "remove.ai.hermes": {"icon":"","iconFont":"omarchy","label":"Hermes Desktop","when":"omarchy-pkg-present hermes-desktop","action":"omarchy-launch-floating-terminal-with-presentation omarchy-remove-ai-hermes"},
   "remove.browser.chrome": {"icon":"","label":"Chrome","when":"omarchy-pkg-present google-chrome","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-remove-browser chrome'"},
   "remove.browser.edge": {"icon":"󰇩","label":"Edge","when":"omarchy-pkg-present microsoft-edge-stable-bin","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-remove-browser edge'"},
   "remove.browser.brave": {"icon":"","label":"Brave","when":"omarchy-pkg-present brave-bin","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-remove-browser brave'"},
@@ -305,6 +313,8 @@
   "remove.ai.grok-bot": {"icon":"","iconFont":"omarchy","label":"Grok Bot","when":"omarchy-pkg-present grok-bot","action":"omarchy-launch-floating-terminal-with-presentation omarchy-remove-ai-grok-bot"},
   "remove.ai.lm-studio": {"icon":"","iconFont":"omarchy","label":"LM Studio","when":"omarchy-pkg-present lmstudio-bin","action":"omarchy-launch-floating-terminal-with-presentation omarchy-remove-ai-lm-studio"},
   "remove.ai.ollama": {"icon":"","iconFont":"omarchy","label":"Ollama","when":"omarchy-pkg-present ollama","action":"omarchy-launch-floating-terminal-with-presentation omarchy-remove-ai-ollama"},
+  "remove.ai.openclaw": {"icon":"","iconFont":"omarchy","label":"OpenClaw","when":"omarchy-pkg-present openclaw","action":"omarchy-launch-floating-terminal-with-presentation omarchy-remove-ai-openclaw"},
+  "remove.ai.perplexity": {"icon":"","iconFont":"omarchy","label":"Perplexity","when":"omarchy-pkg-present perplexity","action":"omarchy-launch-floating-terminal-with-presentation omarchy-remove-ai-perplexity"},
   "remove.ai.t3-code": {"icon":"","iconFont":"omarchy","label":"T3 Code","when":"omarchy-pkg-present t3code-bin","action":"omarchy-launch-floating-terminal-with-presentation omarchy-remove-ai-t3-code"},
   "remove.gaming.steam": {"icon":"","label":"Steam","when":"omarchy-pkg-present steam","action":"omarchy-launch-floating-terminal-with-presentation omarchy-remove-gaming-steam"},
   "remove.gaming.retroarch": {"icon":"","label":"RetroArch","when":"omarchy-pkg-present retroarch","action":"omarchy-launch-floating-terminal-with-presentation omarchy-remove-gaming-retroarch"},

default/systemd/system-sleep/force-igpu

@@ -1,29 +1,65 @@
 #!/bin/bash
 
+set -e
+
 # Use the Vfio to Integrated trick to turn off NVIDIA dgpu when in integrated mode
 # without needing to restart the computer. This is needed because computers like the Asus G14
 # will wake after suspend in Hybrid mode, even if the system was in Integrated mode before
 # suspending.
 
+restore_marker=/run/omarchy-force-igpu-integrated
+sleep_action=${SYSTEMD_SLEEP_ACTION:-$2}
+[[ -x /usr/bin/supergfxctl ]] || exit 0
+
+switch_mode() {
+  local expected="$1" current
+
+  if ! /usr/bin/timeout --kill-after=1s 3s /usr/bin/supergfxctl -m "$expected"; then
+    echo "Could not request the GPU transition to $expected mode" >&2
+    return 1
+  fi
+  for _ in {1..10}; do
+    if current=$(/usr/bin/timeout --kill-after=1s 2s /usr/bin/supergfxctl -g 2>/dev/null) &&
+      [[ $current == "$expected" ]]; then
+      return 0
+    fi
+    sleep 1
+  done
+
+  echo "Could not confirm the GPU transition to $expected mode" >&2
+  return 1
+}
+
 case "$1" in
   pre)
+    # Remember the mode this sleep cycle started in. supergfxctl persists the
+    # temporary hibernate switch to Vfio, so post must not consult that mutable
+    # value when deciding whether to restore Integrated mode.
+    if [[ -L $restore_marker ]]; then
+      exit 1
+    elif [[ ! -f $restore_marker ]]; then
+      /usr/bin/grep -Eq '"mode"[[:space:]]*:[[:space:]]*"Integrated"' /etc/supergfxd.conf 2>/dev/null || exit 0
+      /usr/bin/install -m 0600 -o root -g root -T /dev/null "$restore_marker"
+    fi
+
     # Before hibernating, switch to Vfio so the nvidia driver is detached from the dGPU.
     # Without this, hibernate resume fails because the nvidia driver can't freeze a
     # powered-off dGPU (returns -EIO), which aborts the entire resume.
-    if [[ $2 == "hibernate" ]]; then
-      /usr/bin/supergfxctl -m Vfio
-      sleep 1
+    if [[ $sleep_action == "hibernate" ]]; then
+      switch_mode Vfio
     fi
     ;;
   post)
+    [[ -f $restore_marker && ! -L $restore_marker ]] || exit 0
+
     # small delay so the device is fully re-enumerated
     sleep 4
 
     # force-bind dGPU to vfio (fully detached from nvidia)
-    /usr/bin/supergfxctl -m Vfio
-    sleep 1
+    switch_mode Vfio
 
     # then go back to Integrated, which powers it off again
-    /usr/bin/supergfxctl -m Integrated
+    switch_mode Integrated
+    /usr/bin/rm -f -- "$restore_marker"
     ;;
 esac

default/systemd/system-sleep/keyboard-backlight

@@ -3,7 +3,9 @@
 # Turn off keyboard backlight before hibernate to prevent hang on power-off.
 # The ASUS keyboard controller can block S4 shutdown if LEDs are active.
 
-if [[ $1 == "pre" && $2 == "hibernate" ]]; then
+sleep_action=${SYSTEMD_SLEEP_ACTION:-$2}
+
+if [[ $1 == "pre" && $sleep_action == "hibernate" ]]; then
   device=""
   for candidate in /sys/class/leds/*kbd_backlight*; do
     if [[ -e "$candidate" ]]; then

default/systemd/system/plocate-updatedb.service.d/10-omarchy.conf

@@ -0,0 +1,3 @@
+[Service]
+ExecStart=
+ExecStart=/usr/bin/updatedb --prune-bind-mounts=no --add-prunepaths=/.snapshots

default/themed/hermes.yaml.tpl

@@ -0,0 +1,47 @@
+name: omarchy
+description: Omarchy system theme
+colors:
+  background: "{{ background }}"
+  ui_text: "{{ foreground }}"
+  ui_primary: "{{ accent }}"
+  ui_accent: "{{ accent }}"
+  ui_border: "{{ muted }}"
+  ui_label: "{{ accent }}"
+  ui_ok: "{{ green }}"
+  ui_warn: "{{ yellow }}"
+  ui_error: "{{ red }}"
+  ui_tool: "{{ cyan }}"
+  ui_thinking: "{{ dark_foreground }}"
+  banner_border: "{{ muted }}"
+  banner_title: "{{ accent }}"
+  banner_accent: "{{ accent }}"
+  banner_dim: "{{ dark_foreground }}"
+  banner_text: "{{ foreground }}"
+  prompt: "{{ bright_foreground }}"
+  input_rule: "{{ muted }}"
+  response_border: "{{ accent }}"
+  shell_dollar: "{{ blue }}"
+  selection_bg: "{{ selection }}"
+  session_label: "{{ accent }}"
+  session_border: "{{ muted }}"
+  status_bar_bg: "{{ dark_background }}"
+  status_bar_text: "{{ foreground }}"
+  status_bar_strong: "{{ accent }}"
+  status_bar_dim: "{{ dark_foreground }}"
+  status_bar_good: "{{ green }}"
+  status_bar_warn: "{{ yellow }}"
+  status_bar_bad: "{{ red }}"
+  status_bar_critical: "{{ bright_red }}"
+  voice_status_bg: "{{ dark_background }}"
+  completion_menu_bg: "{{ lighter_background }}"
+  completion_menu_current_bg: "{{ selection }}"
+  completion_menu_meta_bg: "{{ lighter_background }}"
+  completion_menu_meta_current_bg: "{{ selection }}"
+  diff_added: "{{ mix background green 15% }}"
+  diff_removed: "{{ mix background red 15% }}"
+  diff_added_word: "{{ green }}"
+  diff_removed_word: "{{ red }}"
+  syntax_string: "{{ green }}"
+  syntax_number: "{{ yellow }}"
+  syntax_keyword: "{{ magenta }}"
+  syntax_comment: "{{ muted }}"

default/themed/t3code.json.tpl

@@ -0,0 +1,36 @@
+{
+  "name": "Omarchy",
+  "appearance": "{{ mode }}",
+  "canvas": "{{ background }}",
+  "accent": "{{ accent }}",
+  "colors": {
+    "chrome": "{{ background }}",
+    "toolbar": "{{ background }}",
+    "toolbarForeground": "{{ foreground }}",
+    "toolbarBorder": "{{ muted }}",
+
+    "text": "{{ foreground }}",
+    "border": "{{ muted }}",
+    "focus": "{{ accent }}",
+
+    "sidebar": "{{ dark_background }}",
+    "sidebarForeground": "{{ foreground }}",
+    "sidebarBorder": "{{ muted }}",
+    "sidebarRowHover": "{{ mix dark_background foreground 6% }}",
+    "sidebarRowActive": "{{ mix dark_background accent 18% }}",
+    "sidebarRowSelected": "{{ selection }}",
+
+    "error": "{{ mix red foreground 35% }}",
+    "warning": "{{ mix yellow foreground 35% }}",
+
+    "codeBackground": "{{ dark_background }}",
+    "codeForeground": "{{ foreground }}",
+
+    "terminalBackground": "{{ background }}",
+    "terminalForeground": "{{ foreground }}",
+    "terminalCursor": "{{ bright_foreground }}",
+    "terminalSelection": "{{ selection }}",
+    "terminalScrollbar": "{{ muted }}",
+    "terminalScrollbarHover": "{{ dark_foreground }}"
+  }
+}

docs/file-layout.md

@@ -84,6 +84,7 @@ version                        ──►  omarchy             /usr/share/omarchy
 config/**                      ──►  omarchy-settings    /etc/skel/.config/**         (seeds new users)
                                                         /usr/share/omarchy/config/** (resync source)
 etc/fastfetch/config.jsonc     ──►  omarchy-settings    /etc/fastfetch/config.jsonc
+etc/xdg/kitty/kitty.conf       ──►  omarchy-settings    /etc/xdg/kitty/kitty.conf
 
 applications/*.desktop         ──►  omarchy-settings    /etc/skel/.local/share/applications/
                                                         /usr/share/omarchy/applications/
@@ -124,8 +125,7 @@ default/**                     ──►  omarchy-settings    /usr/share/omarchy
   ├─ applications/mimeapps.list                         /usr/share/applications/mimeapps.list
   ├─ systemd/user/*.service                             /usr/lib/systemd/user/
   ├─ systemd/user/app.slice.d/10-oomd.conf              /usr/lib/systemd/user/app.slice.d/
-  ├─ systemd/system-sleep/{force-igpu,
-  │    keyboard-backlight,unmount-fuse}                 /usr/lib/systemd/system-sleep/
+  ├─ systemd/system-sleep/unmount-fuse                  /usr/lib/systemd/system-sleep/
   ├─ systemd/zram-generator.conf.d/90-omarchy.conf      /usr/lib/systemd/zram-generator.conf.d/
   ├─ fonts/omarchy/omarchy.ttf                          /usr/share/fonts/omarchy/
   ├─ sddm/omarchy/                                      /usr/share/sddm/themes/omarchy/
@@ -139,6 +139,8 @@ logo.{txt,svg}, icon.{txt,png}  ──► omarchy-settings    /usr/share/omarchy
                                                         /etc/skel/.config/omarchy/branding/{about,screensaver}.txt
 ```
 
+The hardware-conditional `force-igpu` and `keyboard-backlight` sources also live under `default/systemd/system-sleep/`, but their setup commands publish root-owned copies only on machines that need them; they are not installed by `omarchy-settings`.
+
 ### Why `etc-overrides/` exists
 
 Some files under `/etc/` (`.bashrc` in `/etc/skel`, `nsswitch.conf`,
@@ -152,6 +154,14 @@ without a file conflict. Instead their sources (under `etc/` in the repo;
 Tradeoff: user edits to those files get clobbered on every `omarchy-settings`
 upgrade. This is documented in the PKGBUILD.
 
+## Locate indexing
+
+`default/systemd/system/plocate-updatedb.service.d/10-omarchy.conf` ships through `omarchy-settings` to `/usr/lib/systemd/system/plocate-updatedb.service.d/10-omarchy.conf`. It replaces the existing service's `ExecStart` with `updatedb --prune-bind-mounts=no --add-prunepaths=/.snapshots`, keeping Btrfs subvolume mounts searchable and excluding Snapper snapshots. The upstream service retains its timer, resource limits, and sandbox; Omarchy's existing AC-power condition still applies.
+
+`/etc/updatedb.conf` remains owned by plocate and is never rewritten by Omarchy. The command-line options override bind-mount pruning and add to the administrator's existing path exclusions. Installer and AUR package refreshes pass the same options directly because installation may run without systemd and an explicitly requested refresh should work on battery.
+
+Arch's systemd package hook reloads units when the vendor drop-in is installed or upgraded. The settings package containing the drop-in must ship alongside the runtime package that removes the old configuration helper and migration. Pacman removes those retired files; no new state migration is needed. A running indexer finishes with its original options, and subsequent service starts use the drop-in. For an immediate local test after installing the packages, restart `plocate-updatedb.service` while connected to AC power.
+
 ## Env bootstrap (`default/bash/env-bootstrap`)
 
 Single source of truth for `OMARCHY_PATH` and dev-link-aware `PATH`. It:
@@ -198,11 +208,7 @@ Runs once per user. It does **not** copy `~/.config/**`, `~/.bashrc`,
 `flags.lua`, or the nautilus extensions — `/etc/skel` already seeded those.
 It only does the things `/etc/skel` can't:
 
-- Skill symlinks `~/.{agents,claude,codex,pi/agent}/skills/<name>` →
-  `$OMARCHY_PATH/default/agents/skills/<name>`, looping over every skill
-  directory there (currently `omarchy` and `diagnose-crash`) so new skills
-  need no edit. Symlinks (not copies) so `omarchy dev link` against a dev
-  checkout repoints them correctly.
+- Skill symlinks into `~/.agents/skills/<name>`, `~/.claude/skills/<name>`, `~/.codex/skills/<name>`, `~/.pi/agent/skills/<name>`, `~/.gemini/config/skills/<name>` (Antigravity), `~/.hermes/skills/<name>`, and each existing `~/.hermes/profiles/*/skills/<name>` → `$OMARCHY_PATH/default/agents/skills/<name>`, looping over every skill directory there (currently `omarchy` and `diagnose-crash`) so new skills need no edit. Symlinks (not copies) so `omarchy dev link` against a dev checkout repoints them correctly. Hermes profile dirs are only linked when they already exist — provision does not create Hermes profiles.
 - `xdg-user-dirs-update` (Templates/Public/Desktop folded back into `$HOME`)
   and `~/.config/gtk-3.0/bookmarks` (needs `$HOME` expansion).
 - Hyprland's package-owned default input reads `XKBLAYOUT` / `XKBVARIANT`
@@ -355,3 +361,9 @@ return to the packaged default.
 | New stock theme | `themes/<name>/` (+ matching templates under `default/themed/` if they need theme colors) |
 | User-installed theme | `~/.config/omarchy/themes/<name>/` |
 | Generated current theme/background state | `~/.local/state/omarchy/current/` |
+
+## Kitty defaults and user overrides
+
+Kitty loads `/etc/xdg/kitty/kitty.conf` before `~/.config/kitty/kitty.conf`. The `omarchy-settings` package owns the system file; the user template contains only the active theme include and commented examples for personal overrides. Keeping the theme include in the user file lets users remove it without changing the packaged defaults. Individual inherited keybindings can be unmapped with an empty `map <shortcut>` directive, or all inherited bindings can be cleared with `clear_all_shortcuts yes`.
+
+The system default uses `allow_remote_control socket-only` so Omarchy can query the active terminal directory over its Unix socket while Kitty rejects remote-control requests arriving through terminal output. Changing this setting requires restarting Kitty. The migration refreshes the exact previous stock config with a backup; customized configs retain their settings and ordering, with only explicit unrestricted `yes`, `y`, or `true` remote-control settings commented out.

docs/omarchy-shell.md

@@ -37,14 +37,11 @@ wait).
 
 Only one full bar option is active at a time. The built-in `omarchy.bar` is
 used when `bar.id` is omitted or when a selected third-party bar cannot load.
-Panels, overlays, and menus are loaded when summoned. Plugins can set the
-top-level manifest key `keepLoaded: true` to survive between summons.
-First-party services are loaded at startup.
+Panels, overlays, and menus are loaded when summoned. Plugins can set the top-level manifest key `keepLoaded: true` to survive between summons, and to keep a service mounted across plugin hot-reload (so `omarchy.lock` is not destroyed while Hyprland still holds the session lock). First-party services are loaded at startup.
 
-Entry points are QML `Item`s. Panel, overlay, and menu entry points expose
-`open(payloadJson)` and `close()` for summon/hide; on load the host injects
-`omarchyPath`, `shell`, `manifest`, and the registries (`pluginRegistry` /
-`barWidgetRegistry`) as properties.
+Entry points are QML `Item`s. Panel, overlay, and menu entry points expose `open(payloadJson)` and `close()` for summon/hide; on load the host injects `omarchyPath`, `shell`, `manifest`, and the registries (`pluginRegistry` / `barWidgetRegistry`) as properties. Built-in plugins receive the trusted host objects. Third-party plugins receive capability-scoped facades instead: ordinary plugins may look up and control only their own service and lifecycle, built-in clones retain narrow source-specific configuration and UI compatibility, menu plugins receive an application-library facade, and plugins can read detached scalar bar state. A full-bar plugin additionally receives detached bar configuration and widget-catalog snapshots, narrow proxies for the non-authentication services used by built-in bar widgets, and lifecycle control over configured non-authentication UI plugins. Authentication capabilities are stamped from trusted first-party manifests, authentication services are kept out of the host's public service map and QML object tree, and third-party registry/configuration snapshots can be changed only locally without mutating host state. The facades are API boundaries, not same-process QML sandboxes: a visual widget shares the host bar's scene and can walk its parent hierarchy to ordinary host objects. Sensitive state must not rely on the facade alone for isolation.
+
+A third-party replacement bar can render registered widget components, but widgets it hosts receive a service-less entry facade. Allowing the bar to manufacture an own-service facade for an arbitrary widget would also let it retrieve that plugin's live service object. Service-backed third-party widgets therefore retain their full integration only under the trusted built-in bar; a replacement bar may still provide their target-scoped lifecycle and settings operations.
 
 Full schema: [`shell/services/PluginRegistry.qml`](../shell/services/PluginRegistry.qml).
 
@@ -81,12 +78,7 @@ one replaces the active bar, and it is therefore never offered under Disable.
 Bar widgets may set `barWidget.defaultSection` to `left`, `center`, or `right`;
 widgets that omit it default to `center`.
 
-Plugins run as **unsandboxed code** inside `omarchy-shell`. Adding warns you
-before cloning, plugins land disabled so you can review the code before
-`omarchy plugin enable`, and updates show a diff before touching anything.
-Commands confirm in a terminal even when given arguments; without one they
-refuse rather than guess. Add `--yes` to skip every prompt (the path for
-scripts and agents).
+Plugins run as **unsandboxed code** inside `omarchy-shell`. Adding warns you before cloning, plugins land disabled so you can review the code before `omarchy plugin enable`, and updates show a diff before touching anything. Commands confirm in a terminal even when given arguments; without one they refuse rather than guess. Add `--yes` to skip every prompt (the path for scripts and agents). The scoped interfaces remove direct access to authentication services and avoid handing generic cross-plugin service factories to replacement bars, but visual plugins can still traverse ordinary objects in their shared QML scene. Plugin code also has the same user-level file and process access as the shell.
 
 You can still install by hand: drop a plugin into
 `~/.config/omarchy/plugins/<id>/`, run `omarchy-shell shell rescanPlugins`, then

docs/testing.md

@@ -20,11 +20,10 @@ the end and exits non-zero.
   the theme pipeline: template rendering (`omarchy-theme-set-templates`,
   `omarchy-theme-color`, `omarchy-theme-osc`), the theme sync commands
   (tmux, GNOME, VS Code, Pi, Claude) run against stub binaries and a fake
-  `$HOME`, and the theme-state migrations.
+  `$HOME`.
 - **`./test/shell`** — runs every `test/shell.d/*-test.sh` (except
   `base-test.sh` itself). Each file is an independent suite covering one area:
-  a shell plugin, a `bin/` command, a config invariant, a migration. This is
-  where new tests go.
+  a shell plugin, a `bin/` command, a config invariant, or a still-live migration. This is where new tests go.
 - **Acceptance** — everything that needs a real desktop doing real things.
   Deliberately excluded from `./test/all`; it runs in a VM, not the
   development session.
@@ -132,7 +131,7 @@ only a live session can prove.
   fake `$HOME`, runs `bash -euo pipefail "$ROOT/migrations/<ts>.sh"`, and
   asserts the resulting state — including running it twice to prove
   idempotence, and once against non-legacy state to prove it leaves user
-  customization alone.
+  customization alone. Keep that test while the migration is still being written or bugfixed, if it calls an Omarchy helper whose interface can still change, or if it is a security-sensitive privileged repair. Once a one-shot rewrite has shipped in a tagged release and is frozen, drop the test even when that rewrite used sudo, pacman, or limine-mkinitcpio. Keep the migration itself for late-updaters. Tests of `omarchy-migrate`, the login notifier, and `omarchy-upgrade-to-quattro` stay.
 - **Assert the invariant, not the snapshot.** Config tests pin the property a
   test is named for (this widget stays adjacent to that one) rather than whole
   structures, so unrelated churn does not fail them.

etc/xdg/kitty/kitty.conf

@@ -0,0 +1,35 @@
+# Omarchy defaults. Put personal overrides in ~/.config/kitty/kitty.conf.
+
+# Font
+font_family JetBrainsMono Nerd Font
+bold_italic_font auto
+font_size        9.0
+
+# Window
+window_padding_width 14
+hide_window_decorations yes
+confirm_os_window_close 0
+
+# Keybindings
+map ctrl+insert copy_to_clipboard
+map shift+insert paste_from_clipboard
+# Send Shift+Enter as CSI-u so TUIs can distinguish it from Enter.
+map shift+enter send_text all \e[13;2u
+# Kitty legacy encoding sends Alt+Shift+Enter the same as Alt+Enter; send CSI-u so tmux can match M-S-Enter.
+map alt+shift+enter send_text all \e[13;4u
+
+# Allow local cwd lookup, but reject remote control through terminal output.
+allow_remote_control socket-only
+listen_on unix:${XDG_RUNTIME_DIR}/omarchy-kitty-{kitty_pid}
+
+# Aesthetics
+cursor_shape block
+cursor_blink_interval 0
+shell_integration no-cursor
+enable_audio_bell no
+
+# Minimal Tab bar styling
+tab_bar_edge                bottom
+tab_bar_style               powerline
+tab_powerline_style         slanted
+tab_title_template          {title}{' :{}:'.format(num_windows) if num_windows > 1 else ''}

install/config/all.sh

@@ -7,6 +7,5 @@ run_logged "$OMARCHY_INSTALL/config/ssh-command-path.sh"
 run_logged "$OMARCHY_INSTALL/config/ssh-keepalive.sh"
 run_logged "$OMARCHY_INSTALL/config/docker.sh"
 run_logged "$OMARCHY_INSTALL/config/snapper.sh"
-run_logged "$OMARCHY_INSTALL/config/locate.sh"
 run_logged "$OMARCHY_INSTALL/config/enable-services.sh"
 run_logged "$OMARCHY_INSTALL/config/firewall.sh"

install/config/locate.sh

@@ -1,32 +0,0 @@
-UPDATEDB_CONF_PATH="${OMARCHY_UPDATEDB_CONF_PATH:-/etc/updatedb.conf}"
-
-echo "Configuring locate to skip Btrfs snapshots and index Btrfs subvolumes"
-
-[[ -f $UPDATEDB_CONF_PATH ]] || exit 0
-
-# updatedb refuses to run at all on a config that defines a variable twice, so
-# every setting here is rewritten where it already stands and only appended
-# when the file has no line for it.
-
-# Btrfs subvolume mounts (like /home) look like bind mounts, so pruning
-# bind mounts leaves them out of the index entirely.
-if grep -qE '^[[:space:]]*PRUNE_BIND_MOUNTS[[:space:]]*=' "$UPDATEDB_CONF_PATH"; then
-  sed -i -E 's|^[[:space:]]*PRUNE_BIND_MOUNTS[[:space:]]*=.*|PRUNE_BIND_MOUNTS = "no"|' "$UPDATEDB_CONF_PATH"
-else
-  printf '%s\n' 'PRUNE_BIND_MOUNTS = "no"' >>"$UPDATEDB_CONF_PATH"
-fi
-
-# Snapper snapshots are nested subvolumes reached by plain directory
-# traversal, so without this updatedb indexes the system once per snapshot.
-if grep -qE '^[[:space:]]*PRUNEPATHS[[:space:]]*=' "$UPDATEDB_CONF_PATH"; then
-  # updatedb only accepts quoted values and allows a comment after them. Read
-  # back what the machine already prunes and write the whole setting out again
-  # rather than splicing into a line of unknown shape.
-  pruned=$(sed -nE 's|^[[:space:]]*PRUNEPATHS[[:space:]]*=[[:space:]]*"([^"]*)".*|\1|p' "$UPDATEDB_CONF_PATH" | tail -n 1)
-
-  if [[ " $pruned " != *" /.snapshots "* ]]; then
-    sed -i -E "s|^[[:space:]]*PRUNEPATHS[[:space:]]*=.*|PRUNEPATHS = \"/.snapshots${pruned:+ $pruned}\"|" "$UPDATEDB_CONF_PATH"
-  fi
-else
-  printf '%s\n' 'PRUNEPATHS = "/.snapshots"' >>"$UPDATEDB_CONF_PATH"
-fi

install/omarchy-base.packages

@@ -108,6 +108,8 @@ ttfx
 qemu-user-static-binfmt
 qrencode
 qt6-imageformats
+qt6-multimedia
+qt6-multimedia-ffmpeg
 quickshell
 ripgrep
 ruby
@@ -133,6 +135,7 @@ ufw-docker
 unzip
 usage
 uwsm
+vi
 whois
 wireless-regdb
 wireplumber

install/post-install/localdb.sh

@@ -1,2 +1,3 @@
 # Update localdb so locate can find the installed system files immediately.
-updatedb
+# Match the scheduled service while installation runs without a system manager.
+updatedb --prune-bind-mounts=no --add-prunepaths=/.snapshots

install/user/mise.sh

@@ -1,3 +1,7 @@
+# Upgrades must not delete the version a running process is executing from:
+# mise up would prune the old install dir out from under a live session.
+mise settings set upgrade.auto_prune false
+
 omarchy-mise-install codex
 omarchy-mise-install claude
 omarchy-mise-install crush
@@ -9,7 +13,18 @@ omarchy-mise-install npm:playwright playwright
 omarchy-mise-install pi
 omarchy-mise-install github:can1357/oh-my-pi omp
 omarchy-mise-install npm:@xai-official/grok grok
+# Cursor's own installer links the same path, so a re-provision keeps it.
+omarchy-cmd-missing cursor-agent && omarchy-mise-install cursor-agent
 omarchy-mise-install npm:@kitlangton/ghui ghui
 omarchy-mise-install aqua:modem-dev/hunk hunk
 omarchy-mise-install github:basecamp/hey-cli hey
 omarchy-mise-install github:OpenRouterLabs/ori-releases ori
+# Every line above writes a stub and cannot fail. This one can: it exits
+# non-zero when Hermes Desktop owns Hermes but has not finished setting it up,
+# and this leaf is sourced under `bash -eE`, so that would abort the rest of
+# omarchy-provision-user -- the default browser, the mailto handler and the
+# finalize-user marker all come after it.
+omarchy-install-hermes-cli || true
+if omarchy-cmd-missing muse; then
+  omarchy-mise-install "http:muse[url=https://api.meta.ai/muse-launcher.sh,bin=muse,version_list_url=https://api.meta.ai/muse-code/channels/muse-stable,version_json_path=.version]" muse
+fi

manual/07-hotkeys.md

@@ -192,6 +192,7 @@ All style options are also accessible under _Style_ in the Omarchy menu (`Super
 | `Shift + Mute` | Switch to next audio output |
 | `Shift + Play` | Switch to next media source |
 | `Super + Shift + Backspace` | Toggle window gaps |
+| `Super + Ctrl + Alt + F` | Toggle full screen desktop (top bar + window gaps) |
 
 ## Reminders
 

manual/17-ai.md

@@ -14,6 +14,9 @@ Omarchy treats AI coding agents as first-class citizens, but it doesn't pick a f
 | `pi`       | [Mario Zechner's Pi](https://github.com/badlogic/pi-mono)        |
 | `omp`      | [Oh My Pi](https://github.com/can1357/oh-my-pi)                  |
 | `ori`      | [Ori](https://openrouter.ai/docs/guides/ori/harness), OpenRouter's harness |
+| `hermes`   | [Hermes](https://hermes-agent.nousresearch.com/), Nous Research's agent  |
+| `muse`     | [Muse Code](https://dev.meta.ai), Meta's coding agent           |
+| `cursor-agent` | [Cursor CLI](https://cursor.com/cli)                         |
 
 `ori` is the odd one out: it runs the other harnesses against OpenRouter's whole model catalog, so `ori claude`, `ori codex`, or `ori opencode` start those agents on whichever model you point them at, and `ori code` is Ori's own agent.
 
@@ -23,9 +26,11 @@ To wrap an additional CLI the same way, run `omarchy-mise-install <package> [com
 
 Pick your default agent with `omarchy default agent <name>` or under _Setup > Defaults > Agent_ in the Omarchy Menu (`Super + Space`). If the agent isn't installed yet, picking it installs it first. A fresh Omarchy will invite you to make this choice with a one-time notification.
 
+[Muse Code](https://dev.meta.ai) — Meta's `muse` — uses a preinstalled mise stub like the other agents. Picking it as the default installs Meta's official launcher through mise's HTTP backend. The launcher verifies and updates the native binary for your machine.
+
 Once you've chosen, `Super + Shift + Ctrl + A` launches the default agent in a dedicated terminal window (or brings up the picker if you haven't chosen yet). You can also launch it straight into a task with `omarchy agent prompt "Review this project"`. Agents launched this way run unattended in their respective don't-stop-to-ask modes, so be ready for them to actually do things! And since agents refuse to remember trust for your home directory, launches from `$HOME` start in `~/Work` instead.
 
-There are terminal shortcuts too: `a` runs the default agent inline in the current terminal, while `c`, `cx`, and `cy` start OpenCode, Claude Code, and Codex directly (again in their auto-approving modes). Theme changes sync to the agents as well: Claude Code, Pi, and OpenCode all follow along when you switch the Omarchy theme.
+There are terminal shortcuts too: `a` runs the default agent inline in the current terminal, while `c`, `cx`, and `cy` start OpenCode, Claude Code, and Codex directly (again in their auto-approving modes). Theme changes sync to the agents as well: Claude Code, Pi, OpenCode, and Hermes (once Hermes Desktop is installed) all follow along when you switch the Omarchy theme.
 
 ### The agents panel
 
@@ -43,7 +48,11 @@ Crashes can also be silenced one program at a time, which is what the diagnosis
 
 ### Desktop apps
 
-The _Install > AI_ menu also carries a couple of graphical AI apps: the ChatGPT desktop app, and Grok Bot for chatting with xAI's models.
+The _Install > AI_ menu also carries a few graphical AI apps: the ChatGPT desktop app, Grok Bot for chatting with xAI's models, Hermes Desktop, OpenClaw, and the Perplexity desktop app.
+
+Hermes Desktop is the one to know about, because there is only ever one Hermes on a machine. The app only runs against a runtime built from its own commit, so it installs one of its own under `~/.hermes` on first launch, which takes a few minutes and shows its own progress. From then on that is the Hermes the terminal `hermes` command and the default agent use too, whichever order you installed them in. Installing it also hands Hermes the Omarchy theme as a skin named `omarchy`, which every Hermes surface follows as you switch themes; pick another under Hermes' Appearance settings or with `/skin` if you'd rather it didn't, and Omarchy leaves that choice alone. Removing the app under _Remove > AI_ takes that runtime with it, and keeps your chats, memories, and the skills Hermes wrote for itself unless you tell it otherwise: it asks, defaulting to no, whether that data and your connection settings should go too.
+
+OpenClaw's desktop experience is its Control UI, which opens as a web app backed by its own local gateway. OpenClaw updates arrive through Omarchy's package updates, so skip the Control UI's own "Update Gateway" button: it would try to write into the package-managed install and fail. Removing OpenClaw under _Remove > AI_ takes the gateway service and the app with it and then asks whether `~/.openclaw` should go too, since that holds your chats and credentials alongside the plugin runtimes OpenClaw downloads for itself; the default keeps it.
 
 ### Local LLMs
 
@@ -51,6 +60,6 @@ Omarchy recommends two ways of running local LLM models: LM Studio and Ollama. L
 
 ### The Omarchy Skill
 
-Agent skills help AI use specific tools in a specific way, and Omarchy ships with a default skill for tailoring the system. Like tweaking your Hyprland config, adjusting the bar, or even creating a new theme from scratch. It's symlinked into the skill directories for Claude Code (`~/.claude/skills`), Codex (`~/.codex/skills`), Pi (`~/.pi/agent/skills`), Antigravity (`~/.gemini/config/skills`), and the generic `~/.agents/skills` location, so most harnesses pick it up automatically.
+Agent skills help AI use specific tools in a specific way, and Omarchy ships with a default skill for tailoring the system. Like tweaking your Hyprland config, adjusting the bar, or even creating a new theme from scratch. It's symlinked into the skill directories for Claude Code (`~/.claude/skills`), Codex (`~/.codex/skills`), Pi (`~/.pi/agent/skills`), Antigravity (`~/.gemini/config/skills`), Hermes (`~/.hermes/skills` and each `~/.hermes/profiles/*/skills`), and the generic `~/.agents/skills` location, so most harnesses pick it up automatically.
 
 But you should treat this skill as experimental. Different models will use it to different effect. It's best to run in plan mode first, so you have an idea of what the agent would like to change. And then be ready to rollback changes or even invoking `omarchy reinstall configs`, if the agent makes a mess of everything.

manual/18-development-tools.md

@@ -4,6 +4,8 @@
 
 Omarchy ships with [Neovim](https://neovim.io/) by default, but if you'd like something a bit more mainstream and familiar, you can run the Omarchy Menu (`Super + Space`) and see the options under _Install > Editor_. We have VSCode, Cursor, Zed, Sublime Text, Helix, Vim, and Emacs listed there. If you don't find what you're looking for, checkout _Install > Package_, and see if it isn't in an Arch package (and if not, try _Install > AUR_ to check the AUR).
 
+The original `vi` editor is also available out of the box. Run `vi filename` to edit a file in the terminal.
+
 Theme matching is offered for `VSCode`, `Cursor`, `VSCodium`, and `Helix`.
 
 You can set the system-wide default editor under `Setup > Defaults > Editor`.

manual/31-dotfiles.md

@@ -66,10 +66,11 @@ Look, this is your computer. You can do whatever you want with it, but I would a
 
 You can change just about everything that way, like the default keybindings. Just edit `~/.config/hypr/bindings.lua` to, say, replace [Obsidian](https://obsidian.md/) with [Joplin](https://joplinapp.org/) (install with `omarchy-pkg-add joplin-bin`):
 
+```lua
+o.rebind("SUPER + SHIFT + O", "Joplin", "joplin-desktop")
 ```
-hl.unbind("SUPER + SHIFT + O")
-o.bind("SUPER + SHIFT + O", "Joplin", "joplin-desktop")
-```
+
+`o.rebind` removes the existing binding before adding its replacement. It takes the same arguments as `o.bind`, including launch helpers and binding options. Use `o.bind` to add a binding, or `hl.unbind` to remove one without replacing it.
 
 If you insist on hacking on the internal Omarchy files, switch to the dev channel via _Update > Channel > Dev_. That links Omarchy to a git checkout of the source code in `~/omarchy`, which you're free to change to your heart's content. Ain't nobody here to tell you what to do!
 

manual/32-shell-plugins.md

@@ -4,7 +4,7 @@ The Omarchy desktop runs as a single long-lived Quickshell process called `omarc
 
 That's not just an implementation detail. It means you can turn pieces of the desktop off, swap them out, or write your own without touching a line of Omarchy's source.
 
-The first-party plugins ship with Omarchy and live in `$OMARCHY_PATH/shell/plugins/`. Anything you add yourself — your own experiments, or something you found on GitHub — lives in `~/.config/omarchy/plugins/`. Both are discovered the same way at startup; the only difference is where they sit on disk.
+The first-party plugins ship with Omarchy and live in `$OMARCHY_PATH/shell/plugins/`. Anything you add yourself — your own experiments, or something you found on GitHub — lives in `~/.config/omarchy/plugins/`. Both are discovered the same way at startup, but built-ins receive trusted shell interfaces while third-party plugins receive a limited interface scoped to their own service and lifecycle. Clones of built-ins keep only the source-specific configuration and UI calls needed for the original behavior.
 
 ## Seeing what you have
 
@@ -37,7 +37,9 @@ A third-party plugin is just a git repo with a `manifest.json` at its root.
 omarchy plugin add https://github.com/acme/omarchy-weather.git --enable
 ```
 
-Before it does anything, it tells you plainly that plugins run as arbitrary, unsandboxed code inside your long-lived shell process, shows you the URL, and asks you to confirm. Take that seriously. A plugin isn't a config file — it's code that runs for as long as your session does, with everything your user account can reach. Only add repos you're willing to run, and read them before you enable them.
+Before it does anything, it tells you plainly that plugins run as arbitrary, unsandboxed code inside your long-lived shell process, shows you the URL, and asks you to confirm. Take that seriously. The third-party plugin interface does not directly expose authentication services, and a replacement bar receives only limited capabilities for configured non-authentication UI. Visual plugins still share the shell's QML scene and can walk ordinary parent objects, while all plugin code runs with everything your user account can reach. Authentication state is protected separately by keeping those services outside the reachable host object graph. Only add repos you're willing to run, and read them before you enable them.
+
+A replacement bar can render installed widgets, but service-backed third-party widgets may have reduced functionality there because the bar is not allowed to request another plugin's live service object. Switch back to the built-in `omarchy.bar` if such a widget needs its companion service.
 
 Then it clones the repo into a staging directory, validates the manifest, refuses the install if another plugin already claims that id, and moves it into `~/.config/omarchy/plugins/<id>/`. Without `--enable` it asks whether you want it on now, and you can say no and go read the code first. It never runs anything from the plugin, never executes an install hook, and never asks for sudo — it clones files, checks the manifest, and flips a bit over IPC.
 

manual/39-backgrounds.md

@@ -4,4 +4,6 @@ Every theme ships with its own set of backgrounds, and you can add extras of you
 
 You can do this most easily by going to _Install > Style > Background_ in the Omarchy Menu. That'll bring up the folder where the backgrounds for that theme is stored. Hit `Super + Shift + F` to start another file manager, find your background, copy it over.  Now it'll be included in the choices of backgrounds you can select between using `Super + Ctrl + Space`.
 
+Backgrounds can be videos as well as stills. Drop an `mp4`, `m4v`, `mov`, `webm`, `mkv`, or `avi` file in the same folder and it appears alongside the images, playing on a loop. Only your first monitor's wallpaper plays a video's sound track, through the default audio output at the system volume, and the lock screen stays silent. Playback stops on its own whenever nothing can see it — while a fullscreen window covers that monitor, while the screensaver is up, and once a locked screen has gone dark — but a video wallpaper still costs far more power than a still one, and each monitor decodes its own copy.
+
 You can find a huge collection of cool curated backgrounds on https://github.com/dharmx/walls.

migrations/1784809451.sh

@@ -1,30 +0,0 @@
-echo "Configure locate to skip Btrfs snapshots and index Btrfs subvolumes"
-
-OMARCHY_PATH="${OMARCHY_PATH:-/usr/share/omarchy}"
-locate_config_script="$OMARCHY_PATH/install/config/locate.sh"
-UPDATEDB_CONF_PATH="${OMARCHY_UPDATEDB_CONF_PATH:-/etc/updatedb.conf}"
-
-as_root() {
-  if (( EUID == 0 )); then
-    "$@"
-  else
-    sudo "$@"
-  fi
-}
-
-[[ -f $UPDATEDB_CONF_PATH ]] || exit 0
-[[ -f $locate_config_script ]] || exit 0
-
-if grep -q '^PRUNE_BIND_MOUNTS = "no"' "$UPDATEDB_CONF_PATH" &&
-  grep -E '^PRUNEPATHS' "$UPDATEDB_CONF_PATH" | grep -E '(^|[[:space:]"])/\.snapshots([[:space:]"]|$)' >/dev/null; then
-  exit 0
-fi
-
-as_root env OMARCHY_UPDATEDB_CONF_PATH="$UPDATEDB_CONF_PATH" bash -euo pipefail "$locate_config_script"
-
-# Rebuild the index with the new exclusions; pruning /.snapshots turns
-# multi-hour runs on snapshot-heavy systems back into one-minute runs. Restart
-# rather than start: the machines this targets are the ones with an updatedb
-# already grinding through every snapshot, and a run that started before the
-# rewrite keeps using the config it read at startup.
-as_root systemctl restart --no-block plocate-updatedb.service >/dev/null 2>&1 || true

migrations/1785090473.sh

@@ -1,17 +1,8 @@
-echo "Switch fingerprint support back to stock libfprint"
+echo "Repair fingerprint support left without a libfprint"
 
-# libfprint-git existed to carry the focaltech_moc driver and the FocalTech
-# FT9349 device ID (2808:a97a) before any release shipped them. libfprint
-# 1.94.100 has both, so fingerprint setups go back to the stock Arch package.
-
-# The remove/install pair below isn't one transaction: if the install failed
-# on a previous run, libfprint-git is already gone but fprintd is left with
-# no libfprint — the elif finishes the job on rerun.
-if pacman -Q libfprint-git &>/dev/null; then
-  # Deps-only removal keeps fprintd installed while its libfprint
-  # dependency is swapped out underneath it.
-  sudo pacman -Rdd --noconfirm libfprint-git
-  omarchy-pkg-add libfprint
-elif pacman -Q fprintd &>/dev/null && ! pacman -Q libfprint &>/dev/null; then
-  omarchy-pkg-add libfprint
+# An earlier version of this migration swapped libfprint-git for stock
+# libfprint in two steps. A run that failed between them left fprintd with
+# no library; finish with the driver the fingerprint setup installs now.
+if omarchy-pkg-present fprintd && omarchy-pkg-missing libfprint && omarchy-pkg-missing libfprint-git; then
+  omarchy-pkg-add libfprint-git
 fi

migrations/1786609204.sh

@@ -0,0 +1,3 @@
+echo "Install native video wallpaper playback dependencies"
+
+omarchy-pkg-add qt6-multimedia qt6-multimedia-ffmpeg

migrations/1787215483.sh

@@ -0,0 +1,3 @@
+echo "Stop mise upgrades from pruning versions still in use"
+
+mise settings set upgrade.auto_prune false

migrations/1787760281.sh

@@ -0,0 +1,25 @@
+echo "Install the Hermes CLI wrapper for existing installs"
+
+# Users who removed the preinstalls opted out of the mise wrappers, and Hermes
+# is one of them.
+[[ -f $HOME/.local/state/omarchy/preinstalls-removed ]] && exit 0
+
+# Hermes Desktop provides its own Hermes. The installer stands aside for it,
+# removing the mise copy and the Omarchy wrapper an earlier install may have
+# left beside the app. It also reports when the app has not finished setting
+# Hermes up, which is the app's to finish, not this migration's to fail on.
+if omarchy-pkg-present hermes-desktop; then
+  omarchy-install-hermes-cli || true
+  exit 0
+fi
+
+# Anything already answering to hermes that this installer did not write --
+# an official install, a hand-rolled wrapper, even a dangling link -- belongs to
+# the user and stays exactly as it is. The installer is asked rather than
+# matched against here, so there is one answer to who owns that wrapper.
+wrapper="$HOME/.local/bin/hermes"
+if [[ -e $wrapper || -L $wrapper ]] && ! omarchy-install-hermes-cli --owns; then
+  exit 0
+fi
+
+omarchy-install-hermes-cli

migrations/1787843905.sh

@@ -0,0 +1,22 @@
+echo "Link Omarchy agent skills into Hermes skill directories"
+
+OMARCHY_PATH="${OMARCHY_PATH:-/usr/share/omarchy}"
+skills_source="$OMARCHY_PATH/default/agents/skills"
+
+[[ -d $skills_source ]] || exit 0
+
+mkdir -p "$HOME/.hermes/skills"
+
+for skill in "$skills_source"/*/; do
+  [[ -d $skill ]] || continue
+  name=${skill%/}
+  name=${name##*/}
+  ln -sfn "$skills_source/$name" "$HOME/.hermes/skills/$name"
+  if [[ -d $HOME/.hermes/profiles ]]; then
+    for profile in "$HOME"/.hermes/profiles/*/; do
+      [[ -d $profile ]] || continue
+      mkdir -p "$profile/skills"
+      ln -sfn "$skills_source/$name" "$profile/skills/$name"
+    done
+  fi
+done

migrations/1788577553.sh

@@ -0,0 +1,8 @@
+echo "Install Cursor CLI via mise wrapper"
+
+# Cursor's own installer links ~/.local/bin/cursor-agent, so an existing
+# command is the user's and stays. The wrapper resolves cursor-agent through
+# mise's registry, which lists it from 2026.8.15 on.
+if omarchy-cmd-missing cursor-agent && [[ ! -f $HOME/.local/state/omarchy/preinstalls-removed ]]; then
+  omarchy-mise-install cursor-agent
+fi

migrations/1788595060.sh

@@ -0,0 +1,4 @@
+echo "Register the Chromium extension native messaging hosts for Brave Origin"
+
+omarchy-install-chromium-copy-url
+omarchy-install-chromium-ytdlp

migrations/1788596255.sh

@@ -0,0 +1,3 @@
+echo "Add vi as a standard terminal editor"
+
+omarchy-pkg-add vi

migrations/1788619462.sh

@@ -0,0 +1,9 @@
+echo "Hand Hermes Desktop the Omarchy theme as a skin"
+
+# Only the app Omarchy installed under Install > AI follows the theme by itself.
+# A Hermes the user set up some other way keeps whatever skin they chose.
+omarchy-pkg-present hermes-desktop || exit 0
+
+# The same hand-over a fresh install does. A Hermes that is not ready or refuses
+# the write is reported and done with there; only Omarchy's own failures return.
+omarchy-theme-set-hermes --activate

migrations/1788662350.sh

@@ -0,0 +1,303 @@
+echo "Repair user-owned system-sleep hooks and hybrid GPU service configuration"
+
+system_sleep_dir=/usr/lib/systemd/system-sleep
+supergfxd_drop_in=/etc/systemd/system/supergfxd.service.d/delay-start.conf
+quarantine_root=/var/lib/omarchy/migrations/1788662350-system-sleep
+reload_needed_marker=/var/lib/omarchy/migrations/1788662350-systemd-reload-needed
+keyboard_source="$OMARCHY_PATH/default/systemd/system-sleep/keyboard-backlight"
+force_igpu_source="$OMARCHY_PATH/default/systemd/system-sleep/force-igpu"
+supergfxd_source="$OMARCHY_PATH/default/systemd/system/supergfxd.service.d/delay-start.conf"
+legacy_keyboard_sha256=f313a81e47401f0d38b8602e5997f52c5286d5e97f74027564ddd515b3d16511
+legacy_force_igpu_sha256=d604e7c4903829563e45fc52188fc5602c3f1bc66e247f0a2cc0a974ed6e57db
+
+as_root() {
+  if (( EUID == 0 )); then
+    "$@"
+  else
+    sudo "$@"
+  fi
+}
+
+path_is_root_controlled() {
+  local path="$1"
+  local current=/ component candidate file_mode link metadata part status uid gid mode
+  local missing_depth=0 symlink_count=0
+  local -a pending resolved link_components
+
+  [[ $path == /* ]] || return 1
+  IFS=/ read -r -a pending <<<"$path"
+  # A non-root group is harmless when neither it nor everyone else can write.
+  # Resolve symlinks component by component so an indirect link cannot hide an
+  # intermediate directory controlled by an unprivileged user.
+  metadata=$(path_metadata /) || return 1
+  read -r file_mode uid gid mode <<<"$metadata"
+  (( uid == 0 && (8#$mode & 8#022) == 0 )) || return 1
+
+  while ((${#pending[@]})); do
+    component=${pending[0]}
+    pending=("${pending[@]:1}")
+    [[ -n $component ]] || continue
+    [[ $component == "." ]] && continue
+
+    if [[ $component == ".." ]]; then
+      if ((${#resolved[@]})); then
+        unset 'resolved[-1]'
+      fi
+
+      current=/
+      for part in "${resolved[@]}"; do
+        if [[ $current == "/" ]]; then
+          current="/$part"
+        else
+          current="$current/$part"
+        fi
+      done
+      if (( missing_depth > 0 && ${#resolved[@]} < missing_depth )); then
+        missing_depth=0
+      fi
+      continue
+    fi
+
+    if [[ $current == "/" ]]; then
+      candidate="/$component"
+    else
+      candidate="$current/$component"
+    fi
+
+    if (( missing_depth > 0 )); then
+      # The first missing component makes descendants inactive today, but keep
+      # consuming the lexical suffix. A later .. can escape back into an
+      # existing user-controlled path that would become active if an
+      # administrator creates the missing directory.
+      resolved+=("$component")
+      current=$candidate
+      continue
+    elif metadata=$(path_metadata "$candidate"); then
+      read -r file_mode uid gid mode <<<"$metadata"
+    else
+      status=$?
+      if (( status == 2 )); then
+        resolved+=("$component")
+        current=$candidate
+        missing_depth=${#resolved[@]}
+        continue
+      else
+        return 1
+      fi
+    fi
+    if (( (16#$file_mode & 16#f000) == 16#a000 )); then
+      ((++symlink_count <= 40)) || return 1
+      link=$(readlink_with_privilege "$candidate") || return 1
+      IFS=/ read -r -a link_components <<<"$link"
+      pending=("${link_components[@]}" "${pending[@]}")
+      if [[ $link == /* ]]; then
+        resolved=()
+        current=/
+      fi
+      continue
+    fi
+
+    (( uid == 0 && (8#$mode & 8#022) == 0 )) || return 1
+    resolved+=("$component")
+    current=$candidate
+  done
+}
+
+path_metadata() {
+  local path="$1"
+  local metadata parent
+
+  if /usr/bin/stat -c '%f %u %g %a' -- "$path" 2>/dev/null; then
+    return 0
+  elif [[ ! -e $path && ! -L $path ]]; then
+    parent=${path%/*}
+    [[ -n $parent ]] || parent=/
+    # Avoid asking for sudo for ordinary ENOENT. If the parent is searchable,
+    # the absence is conclusive; an inaccessible root-only chain still needs a
+    # privileged metadata check so safe administrator symlinks are preserved.
+    [[ -x $parent ]] && return 2
+    if metadata=$(as_root /usr/bin/stat -c '%f %u %g %a' -- "$path" 2>/dev/null); then
+      printf '%s\n' "$metadata"
+      return 0
+    elif as_root /usr/bin/test -x "$parent"; then
+      # The privileged probe could search the protected parent, so stat's
+      # failure identifies a target that does not exist yet.
+      return 2
+    else
+      return 1
+    fi
+  else
+    as_root /usr/bin/stat -c '%f %u %g %a' -- "$path"
+  fi
+}
+
+readlink_with_privilege() {
+  local path="$1"
+
+  if /usr/bin/readlink -- "$path" 2>/dev/null; then
+    return 0
+  else
+    as_root /usr/bin/readlink -- "$path"
+  fi
+}
+
+privileged_entry_is_safe() {
+  local path="$1"
+
+  path_is_root_controlled "$path"
+}
+
+file_matches_source() {
+  local source="$1"
+  local destination="$2"
+
+  [[ -f $destination && ! -L $destination ]] || return 1
+
+  if [[ -r $destination ]]; then
+    /usr/bin/cmp -s -- "$source" "$destination"
+  else
+    as_root /usr/bin/cmp -s -- "$source" "$destination"
+  fi
+}
+
+file_matches_sha256() {
+  local destination="$1"
+  local expected="$2"
+  local digest
+
+  [[ -f $destination && ! -L $destination ]] || return 1
+  if [[ -r $destination ]]; then
+    digest=$(/usr/bin/sha256sum -- "$destination") || return 1
+  else
+    digest=$(as_root /usr/bin/sha256sum -- "$destination") || return 1
+  fi
+  [[ ${digest%% *} == "$expected" ]]
+}
+
+safe_stage_path() {
+  local stage="$1"
+  local destination="$2"
+  local prefix suffix
+
+  prefix="${destination%/*}/.${destination##*/}.omarchy."
+  [[ $stage == "$prefix"* ]] || return 1
+  suffix=${stage#"$prefix"}
+  [[ $suffix =~ ^[[:alnum:]]{6}$ ]]
+}
+
+install_root_file() {
+  local source="$1"
+  local destination="$2"
+  local mode="$3"
+  local stage
+
+  stage=$(as_root /usr/bin/mktemp -- "${destination%/*}/.${destination##*/}.omarchy.XXXXXX") || return 1
+  safe_stage_path "$stage" "$destination" || return 1
+
+  if as_root /usr/bin/install -m "$mode" -o root -g root -T "$source" "$stage" &&
+    as_root /usr/bin/mv -Tf -- "$stage" "$destination"; then
+    return 0
+  else
+    safe_stage_path "$stage" "$destination" && as_root /usr/bin/rm -f -- "$stage"
+    return 1
+  fi
+}
+
+preserve_unsafe_customization() {
+  local path="$1"
+  local label="$2"
+  local backup_dir backup
+
+  if ! as_root /usr/bin/install -d -m 0700 -o root -g root "$quarantine_root"; then
+    echo "Could not create the root-only system-sleep quarantine at $quarantine_root" >&2
+    return 1
+  fi
+  if ! backup_dir=$(as_root /usr/bin/mktemp -d -- "$quarantine_root/${label}.XXXXXX"); then
+    echo "Could not reserve a quarantine path for $path" >&2
+    return 1
+  fi
+  backup="$backup_dir/original"
+
+  if as_root /usr/bin/cp -a --no-dereference -T -- "$path" "$backup"; then
+    printf '%s\n' "$backup"
+  else
+    as_root /usr/bin/rm -rf -- "$backup_dir"
+    echo "Could not preserve unsafe custom content from $path before repairing it" >&2
+    return 1
+  fi
+}
+
+repair_unsafe_privileged_entry() {
+  local source="$1"
+  local destination="$2"
+  local mode="$3"
+  local label="$4"
+  local legacy_sha256="${5:-}"
+  local backup current_mode
+
+  [[ -e $destination || -L $destination ]] || return 0
+  [[ -f $destination || -L $destination ]] || return 0
+
+  if file_matches_source "$source" "$destination"; then
+    current_mode=$(/usr/bin/stat -c '%a' -- "$destination" 2>/dev/null) ||
+      current_mode=$(as_root /usr/bin/stat -c '%a' -- "$destination") || return 1
+    if privileged_entry_is_safe "$destination" && [[ $current_mode == "${mode#0}" ]]; then
+      return 0
+    fi
+  elif [[ -n $legacy_sha256 ]] && file_matches_sha256 "$destination" "$legacy_sha256"; then
+    :
+  else
+    privileged_entry_is_safe "$destination" && return 0
+    backup=$(preserve_unsafe_customization "$destination" "$label") || return 1
+  fi
+
+  if install_root_file "$source" "$destination" "$mode"; then
+    if [[ -n ${backup:-} ]]; then
+      echo "Preserved unsafe custom content from $destination at $backup for administrator review" >&2
+    fi
+  else
+    if [[ -n ${backup:-} ]]; then
+      echo "Preserved unsafe custom content from $destination at $backup, but could not repair the active path" >&2
+    fi
+    return 1
+  fi
+}
+
+# Replace rather than chown an unsafe destination: its current owner may have
+# already changed the contents or kept a writable file descriptor open. The
+# root-owned staging inode makes the final rename an atomic trust transition.
+repair_unsafe_privileged_entry "$keyboard_source" \
+  "$system_sleep_dir/keyboard-backlight" 0755 keyboard-backlight "$legacy_keyboard_sha256"
+
+force_igpu="$system_sleep_dir/force-igpu"
+repair_unsafe_privileged_entry "$force_igpu_source" "$force_igpu" 0755 force-igpu "$legacy_force_igpu_sha256"
+
+systemd_reload_needed=false
+if [[ -e $reload_needed_marker || -L $reload_needed_marker ]]; then
+  systemd_reload_needed=true
+fi
+
+if [[ -e $supergfxd_drop_in || -L $supergfxd_drop_in ]]; then
+  if ! privileged_entry_is_safe "$supergfxd_drop_in"; then
+    # Replacing the drop-in and reloading systemd are one repair. Record the
+    # second half before changing the file so failure or interruption cannot
+    # be forgotten when a retry sees only the trusted replacement on disk.
+    if ! as_root /usr/bin/install -Dm0644 -o root -g root /dev/null "$reload_needed_marker"; then
+      echo "Could not persist the pending systemd reload for the repaired supergfxd configuration" >&2
+      exit 1
+    fi
+    systemd_reload_needed=true
+    repair_unsafe_privileged_entry "$supergfxd_source" "$supergfxd_drop_in" 0644 delay-start.conf
+  fi
+fi
+
+if $systemd_reload_needed; then
+  if ! as_root /usr/bin/systemctl daemon-reload; then
+    echo "Could not reload systemd after repairing the supergfxd configuration; the migration will retry" >&2
+    exit 1
+  fi
+  if ! as_root /usr/bin/rm -f -- "$reload_needed_marker"; then
+    echo "Could not clear the pending systemd reload marker; the migration will retry" >&2
+    exit 1
+  fi
+fi

migrations/1788724825.sh

@@ -0,0 +1,5 @@
+echo "Install Muse Code via mise wrapper"
+
+if omarchy-cmd-missing muse && [[ ! -f $HOME/.local/state/omarchy/preinstalls-removed ]]; then
+  omarchy-mise-install "http:muse[url=https://api.meta.ai/muse-launcher.sh,bin=muse,version_list_url=https://api.meta.ai/muse-code/channels/muse-stable,version_json_path=.version]" muse
+fi

migrations/1788745941.sh

@@ -0,0 +1,33 @@
+echo "Update Kitty configuration"
+
+kitty_config="$HOME/.config/kitty/kitty.conf"
+# config/kitty/kitty.conf as shipped after 008f3a22 (Kitty cwd lookup).
+stock_sha="856cd466bf568d091cb775c5b90d1852178090a419f492fde02a4eaef6407bf9"
+unrestricted='^[[:space:]]*allow_remote_control[[:space:]]+(yes|y|true)[[:space:]]*$'
+
+if [[ -f $kitty_config ]]; then
+  changed=false
+
+  if [[ $(sha256sum "$kitty_config" | cut -d ' ' -f 1) == $stock_sha ]]; then
+    omarchy-refresh-config kitty/kitty.conf
+    changed=true
+  elif grep -qE "$unrestricted" "$kitty_config"; then
+    # Preserve customizations and ordering. An otherwise stock line can be an
+    # intentional override of an earlier include or mapping.
+    backup=$(mktemp "$kitty_config.bak.XXXXXX")
+    cp -p "$kitty_config" "$backup"
+    sed --follow-symlinks -i -E "s/$unrestricted/# &/" "$kitty_config"
+    printf '\n%s\n' \
+      "Unrestricted remote control disabled." \
+      "Your other Kitty settings were preserved."
+    printf '\nBackup saved to:\n  %s\n' "$backup"
+    changed=true
+  fi
+
+  if [[ $changed == "true" ]]; then
+    # Kitty reads allow_remote_control at startup; config reload is insufficient.
+    gum style --border rounded --border-foreground 3 --padding "1 2" --margin "1 0" \
+      "Restart Kitty" "" \
+      "Close and reopen all Kitty windows to apply this change."
+  fi
+fi

plans/nix.md

@@ -0,0 +1,150 @@
+# Plan: Nix — replace Arch with a sovereign Nix foundation
+
+Revision 2. Rev 2 incorporates adversarial review by codex (xhigh): atomicity restated as atomic selection rather than transactional activation, staged switches for major updates, password hashes kept out of the store, a legal-redistribution gate for unfree packages, precise sovereignty boundaries (mise, fwupd, Steam, Cloudflare), a signed release manifest with anti-rollback, source-rebuild proof in the continuity gate, garbage-collection policy, and a substantially hardened migration: supported-layout gating, live-probed hardware config, an explicit boot transaction with user blessing, state-divergence policy for the shared home, and two-stage rollback.
+
+## Problem
+
+Omarchy spends a remarkable amount of its code protecting users from its own package manager. The scars are all pacman-shaped:
+
+- `omarchy-update-system-pkgs-when-conflicted` is ~150 lines of quarantine choreography — stash unowned conflicting files under `/var/lib/omarchy/replaced`, retry, restore what the upgrade didn't claim — because pacman refuses to own file conflicts.
+- The `etc-overrides/` mechanism (`docs/file-layout.md`) exists solely because pacman won't let two packages touch the same `/etc` file, so we ship copies to `/usr/share/omarchy/etc-overrides/` and `cp -f` them into place from scriptlets.
+- An ALPM hook (`00-omarchy-update-guard.hook`) aborts direct `pacman -Syu` because updates that bypass `omarchy update` skip the coordination around them — snapshots, migrations, hooks, restart checks; we built a guard to keep users away from the distribution's own tooling.
+- The keyring dance in `omarchy-update-keyring` bootstraps trust through `keys.openpgp.org`, and `etc/gnupg/dirmngr.conf` lists five more external keyservers — our signature chain roots outside our infrastructure.
+- Updates are not atomic, so we bolted atomicity on: snapper snapshots plus `limine-snapper-sync` approximate what the package manager can't promise, and `docs/update-process.md` still lists pacnew/pacsave handling as an open wound.
+- `omarchy-upgrade-to-quattro` is 2,389 lines. That is what it costs to move a fleet of mutable, individually-drifted Arch installs through one package-layout transition.
+
+And sovereignty is only half-won. We already run the hosting — `mirror.omarchy.org` serves core/extra/multilib, `pkgs.omarchy.org` serves the `[omarchy]` repo, stable deliberately trails upstream Arch by a month (`manual/30-updates.md`) — but we don't own the substance. Arch decides what a "system upgrade" contains and when soname bumps land; we inherit every decision a day later and can only delay it. The AUR path (`omarchy-pkg-aur-*`, the Install menu) executes unsigned build scripts fetched live from `aur.archlinux.org`. T2 Macs add a GitHub-hosted third-party repo with `SigLevel = Never` (`install/hardware/pacman.sh`). And because every install mutates independently, no two Omarchy machines run the same bytes — "we tested this update" is a statement about our machine, not yours.
+
+Nix fixes the category, not the symptoms. A NixOS system is a closure: one immutable tree of store paths containing every package, config file, and service definition, built once, signed once, and selected atomically — the running system is a symlink flip to a complete generation, and the old one stays bootable. Rollback is booting the previous generation; file conflicts and pacnew files are structurally impossible; and every machine's packages are the byte-identical store paths we built and tested (the thin top-level closure that composes them — hostname, disk UUIDs, the user's package manifest — is assembled per machine; the payload is not). To be precise about what is and isn't atomic: *selecting* a generation is atomic, *activating* one is a sequence — services stop, activation scripts run, services start — and a step in that sequence can fail. The design below stages risky switches across a reboot for exactly that reason. The catch is that the Nix ecosystem assumes nixos.org: `cache.nixos.org` as substituter, nixpkgs from GitHub, channels from `channels.nixos.org`, an install script piped from their web server. This plan takes the technology and none of the hosting.
+
+## Shape
+
+- Omarchy becomes a NixOS-based system whose entire supply chain runs on omarchy.org infrastructure: a pinned nixpkgs fork on our git hosting, closures built on our build farm, binaries served from our signed cache. A user's machine never contacts nixos.org, cache.nixos.org, or GitHub for OS concerns — the same posture `pkgs.omarchy.org` and the mirrors have today, extended until it covers everything.
+- Users don't learn Nix. The `omarchy` CLI keeps its verbs (`omarchy-pkg-add`, `omarchy update`, `omarchy-channel-set`), `~/.config` stays your mutable files, themes and the refresh pattern are untouched. Nix is plumbing, exactly as pacman was plumbing — it just leaks less.
+- An update is: fetch prebuilt, signed store paths from our cache, compose the new generation, activate it — across a reboot when the jump is big — and keep the old generation bootable. What we ship is what we tested, store path for store path.
+
+## Sovereignty, precisely
+
+"Sovereign" means two different things at two different times, and the plan should be honest about which is which:
+
+- **Runtime sovereignty (absolute, for OS delivery)**: an installed machine resolves every OS need — binaries, sources, expressions, signatures, update metadata — against omarchy.org hosts only. No fallback substituters, no keyservers, no GitHub fetches, no upstream flake registry. If nixos.org vanished tomorrow, no user would notice.
+- **Build-time sovereignty (continuity)**: our infrastructure ingests from upstream nixpkgs at development time, then archives everything — the nixpkgs tree in our git mirror, every source tarball in our archive, every build product *and its build closure* (sources, patches, derivations, the compilers that made it) in our cache. If upstream vanished, we could keep building, patching, and releasing from what we hold, indefinitely. What we do not claim: re-deriving the world from a bootstrap seed. Nixpkgs' standard binary bootstrap tarballs are part of what we mirror and trust; full source-bootstrap purity is out of scope.
+
+The boundary is OS delivery, and the plan names what sits outside it rather than letting "absolute" quietly overclaim. `mise`-managed tools pull from GitHub and language registries; fwupd firmware comes from LVFS; Steam downloads Valve's content; browsers update their own components. Those are application-content channels the user chose, not OS delivery, and they keep working — but each gets an explicit decision (mirror it, repoint it, or declare it outside the promise) instead of an assumption. The dev channel's GitHub clone in `omarchy-channel-set` repoints to our git hosting. And Cloudflare stays as the DDoS shield and CDN (`manual/48-security.md`), but the cache origin is storage we control, with a documented path to serve it from elsewhere — a CDN in front of sovereign infrastructure, never the only copy of it.
+
+The release gate makes this testable, in two parts. Delivery: a release is publishable only if a clean machine, with outbound network restricted to omarchy.org, can install the ISO, update, and install every curated extra. Continuity: from an empty store, with binary substitution disabled and only our source archive reachable, the release closure must rebuild — proving we archived the build inputs, not just the outputs. Sovereignty becomes a CI assertion instead of an aspiration.
+
+## Rejected approaches
+
+- **Nix on top of Arch** (Nix as a secondary package manager, Arch stays the base): two package managers, two update pipelines, two failure modes, and the worst properties of both — pacman still owns the system, so none of the atomicity or reproducibility arrives where it matters. The halfway house costs most of the migration and delivers little of the payoff.
+- **Guix**: the same functional model with a nicer language, but its FSDG-purist stance on proprietary firmware, microcode, and NVIDIA drivers means fighting the distribution on exactly the hardware enablement (`install/hardware/` is 51 leaves deep) that Omarchy considers table stakes. Nonguix exists; building a product on an unofficial channel the project disowns is not a foundation.
+- **cache.nixos.org as fallback substituter**: the tempting hedge — use our cache first, theirs when we miss. It silently converts every gap in our build coverage into an external runtime dependency, which is precisely the failure mode this plan exists to eliminate. Misses should fail loudly and get fixed in our farm, not papered over by someone else's CDN.
+- **Hydra for the build farm**: the canonical Nix CI is a sprawling Perl application that is its own operational project. Our release matrix is a known, finite list of targets; plain `nix build` over that list in ordinary CI, followed by `nix copy` to the cache, does the job with tooling we already understand.
+- **A live binary-cache daemon** (Attic, Harmonia): a Nix binary cache is narinfo and nar files — static content. Object storage behind Cloudflare is the same shape as the pacman repo we serve today, has no attack surface, and scales for free. A daemon earns its keep only if we later want deduplicating storage across many releases; start dumb.
+- **home-manager for user configs**: it would make `~/.config` a farm of read-only symlinks into the store, which is the opposite of Omarchy's "your files" philosophy (`plans/dots.md` exists because those files are yours to edit). The declarative boundary stops at the system layer; the user layer stays mutable plain files.
+- **Image-based atomicity instead** (ostree/Silverblue-style, or A/B partitions): atomic, but at image granularity — you get our image or you get nothing, and local package additions become a bolted-on overlay mechanism. Nix gives the same atomicity at package granularity, so `omarchy-pkg-add` keeps meaning something.
+- **Staying on Arch and hardening further**: the baseline. Every mitigation above can be polished, but they remain mitigations for structural properties — mutability, non-atomicity, conflict-prone file ownership — that pacman cannot shed. We would be signing up to maintain the workaround museum forever.
+
+## Design
+
+### Supply chain
+
+- **nixpkgs fork**: a mirror of nixpkgs on our git hosting, plus an `omarchy` branch carrying our patches (the successor to `omarchy-pkgs`' PKGBUILD patches). Each release pins an exact revision. Flake inputs reference our tarball endpoint (`https://mirror.omarchy.org/src/nixpkgs-<rev>.tar.gz`) with the lockfile's `narHash` pinning content, so even the expression source is fetched from us and integrity-checked.
+- **Source archive**: builders fetch upstream sources once, at ingestion; every fixed-output derivation's output is then held in our cache and our source mirror. `hashedMirrors` pointed at omarchy.org covers `fetchurl`, but it is a hint, not a boundary — `fetchgit`, flake fetchers, and language-ecosystem fetchers each need their own mirroring, and a cache miss makes Nix try a local build whose fetcher will happily call GitHub. So the boundary is enforced where it can't be forgotten: builder and client network policy allows omarchy.org only, and a miss *fails loudly* — a hole in our archive is a bug to fix in the farm, never a silent fallback to upstream. Rebuilds never need the original upstream URL to still exist.
+- **The omarchy flake**: lives where `omarchy-pkgs` lives today — same repo split as now (this repo is the runtime; the packaging repo owns pins, the overlay of packages nixpkgs lacks, and the NixOS modules; `omarchy-iso` owns the installer). The T2 Mac kernel and the `linux-ptl` kernel move from third-party repos and AUR-adjacent sources into our overlay, built and signed on our farm — which closes today's `SigLevel = Never` hole outright.
+
+### Binary cache and trust
+
+- `cache.omarchy.org`: narinfo + nar objects on object storage behind Cloudflare, populated by `nix copy` from the farm, signed with an Omarchy ed25519 cache key. Released objects are write-once (object-locked): a nondeterministic rebuild must never silently replace a narinfo the fleet already trusts.
+- Cache signatures authenticate store paths; they do not say "this is the current stable release." That job belongs to a **release manifest**: a small document per channel naming the release version, the exact top-level closure hashes per hardware variant, and an expiry — signed offline with a release key that is *separate* from the cache key, monotonically versioned so a compromised CDN cannot replay last month's release, and re-signed on a cadence so a frozen mirror goes stale loudly. `omarchy-update-available` and the update flow trust the manifest first, paths second. Key hygiene — build key, cache key, release key, rotation, and revocation — is a Phase 0 deliverable with a rehearsed compromise-recovery runbook, not an appendix.
+- Client `nix.conf` (owned by our NixOS module, not user-editable state): `substituters = https://cache.omarchy.org` — nothing else, replacing the default cache.nixos.org entirely; `trusted-public-keys` lists only our key; the flake registry is pinned to our own registry file so bare flake references cannot reach GitHub.
+- Trust roots: the cache and release public keys ship inside the ISO and the installed closure. `keys.openpgp.org`, `archlinux-keyring`, `omarchy-update-keyring`, and the five keyservers in `etc/gnupg/dirmngr.conf` all leave the OS trust path (gnupg remains for the user's own purposes).
+
+### Build farm
+
+Our own builders run `nix build` over the release matrix: the base system closure per hardware variant (NVIDIA open/legacy, T2, `linux-ptl`, plain), every optional package behind the Install menu and `omarchy-install-*`, and the ISO. A release job then verifies the gate: every store path in every target closure must be substitutable from `cache.omarchy.org` before the release tag is signed. Nothing a user can reach through blessed UI may miss the cache.
+
+One gate is legal, not technical: nixpkgs distinguishes redistributable-unfree from unfree-you-may-not-redistribute, and serving a package from our cache *is* redistribution. NVIDIA userspace drivers (nixpkgs patches them), VS Code, Chrome, vendor firmware, and printer blobs each need a per-package answer in Phase 0: confirmed redistribution rights, a redistributable substitute (VSCodium-shaped choices), or a blessed vendor-fetch exception — which is a named, per-package hole in the runtime-sovereignty claim, recorded as such rather than discovered later. No package enters the curated set without landing in one of those three buckets.
+
+### The system layer
+
+- Everything under `install/config/`, `install/hardware/`, and the `etc/` tree becomes NixOS module code: `services.displayManager.sddm`, `boot.plymouth`, snapper, docker, cups hardening, the sysctl/sudoers/tmpfiles drop-ins, the NVIDIA modprobe and initrd logic that today lives as conditional bash inside `etc/mkinitcpio.conf.d/omarchy_hooks.conf`. `omarchy-apply-system` and `omarchy-apply-hardware` become module imports plus hardware-variant selection instead of sourced shell leaves — and the entire `etc-overrides/` mechanism is deleted, because composing `/etc` from multiple sources is what the module system is.
+- **Bootloader**: limine stays — NixOS ships a `boot.loader.limine` module — but its job changes: boot entries are system generations, not snapper snapshots, so `limine-snapper-sync` and `limine-mkinitcpio` retire. The UKI and fallback-entry behavior configured in `etc/limine-entry-tool.d/` and the direct-boot path (`omarchy-setup-direct-boot`) must be reproduced deliberately — upstream's limine/UKI story is still settling — and boot security is its own workstream: Secure Boot stays explicitly unsupported (as `manual/02-getting-started.md` says today) unless that workstream designs key enrollment, measurement, and recovery properly; it does not sneak in as a module default.
+- **Per-machine composition, budgeted**: the cache delivers every package prebuilt, but each machine still evaluates and assembles its thin top-level closure — `/etc`, initrd, activation scripts — locally on every switch. That cost is real on low-end hardware and gets a measured budget (time and memory, on the weakest supported machines) in the acceptance suite, not an assumption that "everything substitutes, so it's fast."
+- **A supported customization layer**: `/etc` becoming module-owned cannot mean "hope nobody needed to change it." Mounts, sudo rules, kernel parameters, and service tweaks are system concerns with no home-directory equivalent, so the machine gets a blessed local-override file the modules import — real Nix options, documented, surviving updates — and every managed `/etc` file has a named owner. Coordination that today hides behind the pacman guard (migrations, hooks, restart markers) moves into activation-time logic keyed by release version, so even a user running `nixos-rebuild` directly cannot skip it: `omarchy update` stays the pleasant path, but correctness no longer depends on being the only path.
+- **Store hygiene**: closures don't orphan, but unreferenced store paths accumulate and old generations are what rollback is made of — so garbage collection is policy, not an afterthought: automatic GC with a generation-retention window, a cap on boot-menu generations, and a free-space floor, sized so the store's steady state on a user disk compares honestly with today's pruned pacman cache.
+- **Filesystem**: btrfs stays for `/home` (snapper's remaining job: user-file snapshots, until `plans/backup.md` and `plans/dots.md` cover that ground) and for `omarchy-system-factory-reset`'s subvolume mechanics — though the reset workflow itself (the `@factory` baseline, UKI rebuild, LUKS re-key) must be ported, and the restore guarantee narrows honestly: booting an old generation restores the OS, not mutable `/var` state the old root snapshots used to carry. `omarchy-snapshot restore` for the OS becomes "boot the previous generation."
+
+### The user layer stays mutable
+
+Non-negotiable: `~/.config` remains plain files the user owns and edits. `/etc/skel` seeding, `omarchy-refresh-config`, themes, and the entire `default/` → `~/.config` pipeline work unchanged. The declarative world ends at the system/user boundary; crossing it (home-manager) is rejected above. This is the line that keeps Omarchy feeling like Omarchy rather than like NixOS.
+
+### Package UX
+
+- The machine grows a package manifest — a plain text list in the spirit of `install/omarchy-base.packages`, owned by the machine, listing what this user added. `omarchy-pkg-add <name>` resolves the name (an alias table maps established Arch names to nixpkgs attributes, so muscle memory and the menu's package names keep working), appends to the manifest, and rebuilds against our cache — prebuilt, so "rebuild" means download, a local re-evaluation, and a switch: never a compile, and held to the per-machine composition budget above rather than assumed fast. `omarchy-pkg-drop` removes and rebuilds. `pkg-present`/`pkg-missing` query the running closure.
+- The Quickshell menu's guard prelude (`shell/plugins/menu/MenuModel.js` snapshots `pacman -Qq` plus a Provides parse because forking per guard "spends over a second") gets simpler and faster: one listing of the current closure's package set, computed at activation time and cached, replaces the pacman queries.
+- **The AUR is gone, replaced by the curated extras set**: everything the Install menu offers today (Chrome, Brave, Zen, VS Code, Steam and the lib32 Vulkan stack via nixpkgs' 32-bit support, and friends) comes from nixpkgs or our overlay, built and signed on our farm — the first time Omarchy's optional software carries the same signature chain as its core. Arbitrary AUR browsing (`omarchy-pkg-aur-install`) has no sovereign equivalent and is not replaced. The escape hatch for power users — adding their own flakes or substituters — is real Nix, documented as leaving the supported, sovereign envelope, and never wired into blessed UI.
+
+### Updates, channels, migrations
+
+- `omarchy-update` keeps its skeleton — transcript, lock, free-space check, confirm, stay-awake, migrations, hooks, `omarchy-update-restart` — and swaps its heart: the pacman transaction becomes "download the release closure from the cache, then switch." Failure before activation leaves the running system untouched, and the failed download costs nothing. Activation itself is the sequence that can still hurt — services stop, scripts run, services start — so routine updates switch live, while kernel and other big jumps stage as the *next boot's* generation and activate through the reboot `omarchy-update-restart` already prompts for. `omarchy-update-analyze-logs` survives with a shorter beat: activation and service-restart failures still deserve forensics; package transactions no longer do. And rolling back a generation rolls back the OS, not `/var` — a service that migrated its database forward needs its own story, which is what snapshots-before-update remain for.
+- Deleted outright, with the failure modes they existed for: `omarchy-update-keyring`, `omarchy-update-pkg-prune`, `omarchy-update-system-pkgs-when-conflicted`, `omarchy-update-pacman-guard` and the ALPM hooks, `omarchy-update-orphan-pkgs` (replaced by the GC policy above), `omarchy-update-aur-pkgs`, and the pacnew concern. The guard's job — "don't update behind Omarchy's back" — is covered by the activation-time coordination described above, which runs no matter who triggers the switch.
+- **Channels**: `stable`/`rc`/`edge` become branches of the omarchy flake with their own nixpkgs pins and their own cache prefixes, mirroring today's three pacman.conf templates. `omarchy-channel-set` flips the flake reference and switches. `dev` keeps its meaning: a local checkout via `omarchy-dev-link`, with `omarchy update` fast-forwarding it as now.
+- **Version**: real at last. `omarchy-version` reports the release tag of the running closure instead of deriving it from `pacman -Q`; `omarchy-update-available` compares that against a small release-manifest JSON on the cache host instead of running `checkupdates`.
+- **Migrations** (`migrations/`, 94 files) shrink to their legitimate residue: user-space state under `$HOME`. The 14 that touch pacman/limine/mkinitcpio have no successors — system-state transitions become module code that is simply part of the next closure. The per-user marker mechanism and `omarchy-migrate-notify` survive for what remains.
+
+### ISO and installer
+
+`omarchy-iso` rebuilds around a NixOS ISO carrying the full release closure in its store. Offline installation becomes `nix copy` from the ISO's store to the target plus writing the hardware module selection and the machine manifest — structurally the same "offline mirror" trick the ISO does today with pacman packages, minus the post-install `pacman.conf` restore dance (`install/post-install/pacman.sh`). The ISO signature chain (`iso.omarchy.org`, `.sig`) is unchanged.
+
+## Migrating from Quattro to Cinque
+
+`omarchy-upgrade-to-quattro`'s 2,389 lines are the cautionary tale for what in-place transitions cost — and that one didn't change the package manager. But Quattro's standard disk layout is the opportunity: root on a btrfs subvolume (`@`) with `/home` on its own (`@home`), inside one LUKS container, under a bootloader that already knows how to offer multiple roots. That layout lets Cinque move in *beside* Quattro instead of on top of it.
+
+### The parallel-root migration
+
+`omarchy-upgrade-to-cinque` ships as an ordinary Quattro package update, the same delivery path the v3→v4 upgrader used. It never runs unprompted — migration is an explicit user action, announced through the usual channels, never something `omarchy update` springs on anyone.
+
+1. **Preflight, running system untouched**: the migrator supports the standard layout — btrfs root on `@`, `/home` on `@home`, one LUKS container, limine — and *refuses* everything else (LVM, RAID, exotic mount graphs, hand-built boot chains) toward the reinstall path; `omarchy-system-factory-reset` already gates on the same layout for the same reason, and for boot and storage, "I don't recognize this" is a blocker, not a warning. Then: a hardware gate — the machine's variant (NVIDIA generation, T2, `linux-ptl`) must have a built Cinque closure in the cache, or the migrator refuses with "not yet" rather than "hope so"; a space gate computed from the actual NAR sizes the cache reports plus the retained Quattro root, btrfs metadata headroom, and ESP room for both systems' boot artifacts (the fixed 10 GiB check in `omarchy-update-requires-free-space` is not an estimator); hibernation detection — a suspended image or the swap-subvolume setup from `omarchy-hibernation-setup` is invalidated and its resume configuration carried or rebuilt, because resuming one OS's hibernation image from the other corrupts the filesystem; and the inventory that feeds the *won't-survive report* (see below), which the user reads before consenting.
+2. **Fetch**: the release closure downloads from `cache.omarchy.org` into a fresh `@cinque` subvolume's `/nix` store — resumable, verifiable against signatures, and entirely inert while Quattro keeps running. The sovereignty gate applies here too: the whole migration touches only omarchy.org hosts.
+3. **Carry state**: the partition table, LUKS container, and `@home` are untouched — Cinque mounts the same `/home`. The machine's module configuration is generated from the *live* system — current mounts, `fstab`, `crypttab`, `lsblk`, `/proc/cmdline` — not from a replay of historical hardware detection, and the generated initrd is validated before anything is asked to boot from it. Accounts carry as the full database, not a hash import: `/etc/passwd`, `/etc/shadow`, groups, and NixOS's ID-stability state move as root-only files with `users.mutableUsers` on — password hashes must never be interpolated into the world-readable store. `machine-id`, SSH host keys, and NetworkManager connections come along; `/var/lib` payloads that are data rather than OS (docker volumes chief among them) are copied with their services stopped — a reflink copy of a live database is cheap and worthless.
+4. **First boot, Quattro still the default**: the migrator adds a Cinque boot entry inside a deliberate boot transaction — the ESP contents and firmware boot variables are inventoried and backed up first, foreign entries (Windows, other distros, the fallback loader) are preserved, and machines using `omarchy-setup-direct-boot`'s NVRAM path get that path handled explicitly. The user boots Cinque by choosing it; limine has no proven boot-once/boot-counting mechanism today, so *blessing is a human act*: first-boot verification (graphical session reached, network up, closure healthy) presents its results and asks before Cinque becomes the default. A failed boot needs no cleverness — the default was still Quattro, and a diagnostic bundle waits for `omarchy-upload-log`.
+5. **Rollback window, then reclaim**: at cutover the migrator snapshots `@home` — the two systems share a live home from here on, and applications will migrate profiles and state forward in formats the old side may not read, so a real return to Quattro needs that anchor to offer. `omarchy-upgrade-to-cinque --rollback` is two-stage by construction: it makes Quattro the default and reboots into it; only then, from the running Quattro, does it offer to restore the home snapshot (with post-cutover writes preserved alongside, never silently discarded) and remove `@cinque` — a system never deletes the root it is running on. In the other direction, `--reclaim` (or the update pipeline, after enough clean boots — open question) deletes the Quattro root and returns the space.
+
+Rollback is a reboot plus a decision about state, and the plan says so — the OS comes back untouched by menu choice; the shared home's forward drift is what the cutover snapshot exists to answer. That is still a property no in-place mechanism can offer, and it is what makes offering the migration to a fleet responsible rather than reckless.
+
+One wrinkle owned explicitly: during the window, exactly one side owns the bootloader — Cinque, from the moment its entry is blessed. The Quattro root is kept bootable but frozen — the migrator's only writes into it are disabling `limine-snapper-sync` and the update timers, because two operating systems regenerating one boot configuration is how both stop booting. Booting Quattro during the window is for rescue and rollback, not for continued dual life; the way back to a *living* Quattro is `--rollback`, which returns bootloader ownership along with the default.
+
+### The won't-survive report
+
+Some of what a Quattro machine accumulated has no Cinque equivalent, and the preflight says so per-machine, before anything changes:
+
+- **Packages the user added**: the delta of `pacman -Qqe` against the Quattro release baseline (the raw list would drown the signal in the base system), run through the alias table into the manifest; AUR packages without an overlay equivalent (`pacman -Qem` minus the curated set) are listed by name with the escape-hatch documentation linked. Not a blocker — the user decides.
+- **Custom pacman repos**: both the `pre-refresh-pacman.d` hook layer and repos hand-added to `pacman.conf`, named as unsupported since the mechanism itself retires.
+- **System-level drift**: `pacman -Qii` backup-file diffs are the start, not the whole story — the scan also covers unowned files in `/etc` (`omarchy-update-system-pkgs-when-conflicted`'s quarantine logic proves we can tell), package-file divergence via `pacman -Qkk`, locally enabled or masked systemd units and drop-ins, DKMS modules, printer configuration, and firewall rules. Everything found is listed so the user can carry the *intent* forward — into `~/.config`, an Omarchy setting, or Cinque's local-override module — instead of silently losing edits. Drift in boot or storage configuration is a blocker, per the preflight.
+
+Per-user state needs no migration at all: migration markers, themes, and everything else under `/home` ride along on `@home`. Dev-link users get their checkout fast-forwarded onto the Cinque branch by the migrator rather than a package swap.
+
+### Rejected migration paths
+
+- **`NIXOS_LUSTRATE` in place**: the historical takeover mechanism mutates the only root the machine has — a failure mid-lustrate is an unbootable machine and a restore from backup — and upstream is deprecating it (it doesn't work with the now-default systemd initrd, and NixOS's own guidance points at install-to-another-root instead, which is exactly what the parallel subvolume is). The parallel root delivers everything lustrate promised, plus a rollback that is just a boot-menu choice. Machines without room for two roots get "free up space first," not a reason to lose the rollback.
+- **Reinstall as the only path**: always supported, documented, and cheap once `plans/backup.md` and `plans/dots.md` land (which this plan therefore treats as prerequisites, not nice-to-haves) — but a migration path only matters if the fleet actually takes it, and "back up, reflash, restore" is where fleets quietly decide to stay behind. Reinstall is the fallback, not the offer.
+- **Automatic migration through `omarchy update`**: never. Changing a user's operating system's foundation is a decision, not an update.
+
+## Rollout
+
+- **Phase 0 — infrastructure, zero user impact**: nixpkgs mirror and tarball endpoint, source archive, `cache.omarchy.org`, the key hierarchy (build/cache/release, offline signing workflow, compromise runbook), the signed release-manifest format, the legal-redistribution inventory for the curated set, the build farm, and a CI job that builds the current desktop's equivalent closure and proves both halves of the sovereignty gate (delivery with outbound network restricted to omarchy.org; rebuild from the source archive with substitution disabled).
+- **Phase 1 — system parity** (packaging repo, with changes here): NixOS modules covering every `install/config/`, `install/hardware/`, and `etc/` entry; the flake with per-channel pins; boots and passes the graphical acceptance suite in the VM (`agents/skills/acceptance-tests.md`).
+- **Phase 2 — CLI port** (this repo): `pkg-*`, `update-*`, `channel-*`, `version-*`, snapshot/restore semantics, menu guards; delete the pacman-only organs; port the 18 pacman/yay-mocking test files in `test/shell.d/` to the new seams.
+- **Phase 3 — ISO and installer** (`omarchy-iso`): the offline NixOS ISO, installer flow, hardware detection wiring into module selection.
+- **Phase 4 — release and overlap**: ship as the next major; maintain the Quattro channels in parallel through the overlap window; deliver `omarchy-upgrade-to-cinque` as a Quattro package update, with the reinstall-with-restore path documented as the fallback.
+- **Docs and tests**: `docs/update-process.md` rewritten around the switch model; a new `docs/` reference for the sovereignty gate and cache/mirror topology; manual chapters for updating, rollback-by-generation, and the extras set; shell tests for manifest editing, alias resolution, channel flips, and guard-free update flow; switch-time and evaluation budgets measured on the weakest supported hardware in the acceptance suite; the release-gate CI assertion is itself the sovereignty test.
+
+## Open questions
+
+1. **Which Nix**: upstream CppNix is the safe default; Lix is an argument about governance and pace we don't strictly need to have while we're rehosting everything anyway. Whichever we pick, users get it from our ISO and our cache — never from an install script on someone else's domain.
+2. **Flakes or stable evaluation**: flakes are the ecosystem's lingua franca but formally still experimental upstream. Since we pin our own Nix, we can adopt flakes and own the flag — or use plain evaluation with explicit pins and lose some tooling. Leaning flakes; deserves a deliberate decision.
+3. **How far the curated extras set reaches**: nixpkgs holds ~100k packages; we will build and cache hundreds, not all of it. What is the story when a user wants a package outside the set — a request pipeline into the overlay, the documented unsupported escape hatch, or both?
+4. **Reclaim policy** for the migration's rollback window: does the retained Quattro root get deleted only by explicit `--reclaim`, or automatically after N clean Cinque boots — and how long is a responsible default window on space-constrained disks?
+5. **Btrfs by default, still**: with system rollback moved to generations, btrfs earns its place only through `/home` snapshots and factory reset. Keep it, or simplify the default filesystem story?
+6. **Naming and posture**: "powered by Nix" is a fact; "a NixOS derivative" is a relationship with trademark and community expectations attached. How loudly do we say which — and does sovereign rehosting change what we ought to call it?

shell/Commons/Util.qml

@@ -44,6 +44,10 @@ QtObject {
     return "file://" + String(path).split("/").map(encodeURIComponent).join("/")
   }
 
+  function isVideoPath(path) {
+    return /\.(mp4|m4v|mov|webm|mkv|avi)$/i.test(String(path || ""))
+  }
+
   // Single-quote a string for bash. The replace handles embedded single
   // quotes by closing, escaping, and re-opening the literal.
   function shellQuote(value) {

shell/README.md

@@ -86,8 +86,16 @@ Only one `bar` plugin is active at a time. Missing or invalid selections fall
 back to the built-in `omarchy.bar`, so users always have a safe path home.
 Panels, overlays, and menus are loaded when summoned. Plugins that need
 to outlive a single summon can set `keepLoaded: true` (e.g. the image
-picker keeps its overlay window mounted between summons). First-party
-services are loaded at startup.
+picker keeps its overlay window mounted between summons). The same flag
+keeps a service mounted across plugin hot-reload, so tearing down a
+changed bar widget cannot destroy `omarchy.lock` while Hyprland still
+holds the session lock. The kept instance is not replaced, so code
+changes to a `keepLoaded` service itself only take effect on a shell
+restart. First-party services are loaded at startup.
+
+Entry points may declare `omarchyPath`, `shell`, `manifest`, `pluginRegistry`, and `barWidgetRegistry` properties for host injection. Built-in plugins receive the trusted host objects. Third-party plugins receive capability-scoped facades: ordinary plugins can look up and control only their own service and lifecycle, built-in clones retain narrow source-specific configuration and UI compatibility, menu plugins receive an application-library facade, and plugins can read detached scalar bar state. A full-bar plugin additionally receives detached bar configuration and widget-catalog snapshots, narrow proxies for the non-authentication services used by built-in bar widgets, and lifecycle control over configured non-authentication UI plugins. Authentication capabilities are stamped from trusted first-party manifests, authentication services are retained outside the host's public service map and QML object tree, and changing a third-party registry or configuration snapshot cannot mutate host state. Facades do not isolate visual widgets from the parent hierarchy of the shared QML scene, so sensitive state must remain outside that reachable graph.
+
+Widgets rendered by a third-party replacement bar receive a service-less entry facade with target-scoped lifecycle and settings operations. Their live service objects are available only when the trusted built-in bar hosts them; otherwise the replacement bar could request and retain any configured widget's service.
 
 The full schema lives in `services/PluginRegistry.qml`.
 
@@ -104,10 +112,7 @@ omarchy plugin update                    # updates every git-managed plugin
 omarchy plugin remove acme.weather
 ```
 
-> ⚠️ **Plugins run as unsandboxed code inside `omarchy-shell`.** Adding warns
-> you before cloning, plugins land disabled so you can review the code before
-> enabling, and updates show a diff of the changes before touching anything.
-> Only add repos whose code you are willing to run.
+> ⚠️ **Plugins run as unsandboxed code inside `omarchy-shell`.** Adding warns you before cloning, plugins land disabled so you can review the code before enabling, and updates show a diff of the changes before touching anything. The scoped QML interfaces remove direct authentication-service and generic replacement-bar service lookups, but visual plugins still share and can traverse the ordinary host scene. Only add repos whose code you are willing to run.
 
 Each command is **interactive** when run bare in a terminal (gum pickers,
 confirmation, a diff to review) and fully **non-interactive** when given

shell/Ui/BackgroundMedia.qml

@@ -0,0 +1,87 @@
+import QtQuick
+import qs.Commons
+
+Item {
+  id: root
+
+  property string path: ""
+  property int version: 0
+  property bool playbackEnabled: true
+  property bool audioEnabled: false
+  // Bumped when the file behind an unchanged path may have been replaced.
+  // Images cache-bust through version; a video is rebuilt, since FFmpeg
+  // would read a query as part of the filename.
+  property int reloads: 0
+  property bool reloading: false
+  readonly property var current: video ? videoLoader.item : imageLoader.item
+  readonly property bool ready: current ? current.ready : false
+  readonly property bool video: Util.isVideoPath(path)
+  // Cache-bust images selected in a running lock session. FFmpeg treats the
+  // query as part of a local filename, so videos must keep their plain URL.
+  // Each URL is empty for the other kind, so a switch never hands the still
+  // loader a video, or the player a still, in the moment before it unloads.
+  // Both test the path directly: going through `video` lets a URL evaluate
+  // against the stale flag and leak the wrong file for one pass.
+  readonly property url imageUrl: path && !Util.isVideoPath(path) ? Util.fileUrl(path) + (version ? "?v=" + version : "") : ""
+  readonly property url videoUrl: path && Util.isVideoPath(path) ? Util.fileUrl(path) : ""
+
+  Loader {
+    id: imageLoader
+    anchors.fill: parent
+    active: root.path !== "" && !root.video
+    sourceComponent: imageComponent
+  }
+
+  // Loaded by URL rather than from a Component here, so QtMultimedia and its
+  // audio dependency closure never map into a session that only shows images.
+  Loader {
+    id: videoLoader
+    anchors.fill: parent
+    active: root.path !== "" && root.video && !root.reloading
+    source: "BackgroundVideo.qml"
+  }
+
+  onReloadsChanged: {
+    if (!video) return
+    reloading = true
+    Qt.callLater(function() { root.reloading = false })
+  }
+
+  // A player on its way out keeps its source: pushing an empty one starts a
+  // load of nothing that its destructor then cancels, which FFmpeg logs.
+  Binding {
+    target: videoLoader.item
+    property: "mediaSource"
+    value: root.videoUrl
+    when: videoLoader.item !== null && Util.isVideoPath(root.path)
+    restoreMode: Binding.RestoreNone
+  }
+
+  Binding {
+    target: videoLoader.item
+    property: "playbackEnabled"
+    value: root.playbackEnabled
+    when: videoLoader.item !== null
+  }
+
+  Binding {
+    target: videoLoader.item
+    property: "audioEnabled"
+    value: root.audioEnabled
+    when: videoLoader.item !== null
+  }
+
+  Component {
+    id: imageComponent
+
+    Image {
+      readonly property bool ready: status === Image.Ready
+      source: root.imageUrl
+      fillMode: Image.PreserveAspectCrop
+      asynchronous: true
+      cache: root.version === 0
+      sourceSize.width: root.version > 0 ? width : 0
+      sourceSize.height: root.version > 0 ? height : 0
+    }
+  }
+}

shell/Ui/BackgroundVideo.qml

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

shell/Ui/PluginBarApi.qml

@@ -0,0 +1,87 @@
+import QtQuick
+
+// Bar surface exposed to an installed third-party widget. Scalar presentation
+// state is mirrored by Bar.qml and operations are delegated through scoped
+// callbacks. The facade avoids direct host-Bar injection; it cannot isolate a
+// visual child from the parent hierarchy of the QML scene that renders it.
+QtObject {
+  id: api
+
+  required property string pluginId
+  required property string moduleName
+  property var shell: null
+
+  property color foreground: "transparent"
+  property color barForeground: "transparent"
+  property color background: "transparent"
+  property color urgent: "transparent"
+  property string fontFamily: ""
+  property string position: "top"
+  property bool vertical: false
+  property int barSize: 0
+  property bool transparent: false
+  property bool foregroundAnimationEnabled: true
+  property bool centerSectionRevealHeld: false
+  property bool _centerHoverRevealSuppressed: false
+  readonly property bool centerHoverRevealSuppressed: _centerHoverRevealSuppressed
+  property var activePopout: null
+  property var clickTargets: []
+  property var layoutConfig: ({})
+  readonly property var foreignPopoutMarker: ({ foreign: true })
+
+  property var _showTooltip: null
+  property var _hideTooltip: null
+  property var _registerClickTarget: null
+  property var _unregisterClickTarget: null
+  property var _requestPopout: null
+  property var _releasePopout: null
+  property var _switchPanelFrom: null
+  property var _targetBelongsToWindow: null
+  property var _moduleWidgets: null
+  property var _run: null
+  property var _setCenterHoverRevealSuppressed: null
+
+  function setCenterHoverRevealSuppressed(value) {
+    if (_setCenterHoverRevealSuppressed) _setCenterHoverRevealSuppressed(!!value)
+  }
+
+  function showTooltip(target, text) {
+    if (_showTooltip) _showTooltip(target, String(text || ""))
+  }
+
+  function hideTooltip(target) {
+    if (_hideTooltip) _hideTooltip(target)
+  }
+
+  function registerClickTarget(target) {
+    if (_registerClickTarget) _registerClickTarget(target)
+  }
+
+  function unregisterClickTarget(target) {
+    if (_unregisterClickTarget) _unregisterClickTarget(target)
+  }
+
+  function requestPopout(owner) {
+    if (_requestPopout) _requestPopout(owner)
+  }
+
+  function releasePopout(owner) {
+    if (_releasePopout) _releasePopout(owner)
+  }
+
+  function switchPanelFrom(owner, direction) {
+    return _switchPanelFrom ? _switchPanelFrom(owner, direction) : false
+  }
+
+  function targetBelongsToWindow(target, window) {
+    return _targetBelongsToWindow ? _targetBelongsToWindow(target, window) : false
+  }
+
+  function moduleWidgets(id) {
+    return _moduleWidgets ? _moduleWidgets(String(id || "")) : []
+  }
+
+  function run(command) {
+    if (_run) _run(String(command || ""))
+  }
+}

shell/Ui/qmldir

@@ -3,6 +3,8 @@ module qs.Ui
 BarIndicator 1.0 BarIndicator.qml
 BarIconButton 1.0 BarIconButton.qml
 BarWidget 1.0 BarWidget.qml
+BackgroundMedia 1.0 BackgroundMedia.qml
+BackgroundVideo 1.0 BackgroundVideo.qml
 BorderOverlay 1.0 BorderOverlay.qml
 BorderSurface 1.0 BorderSurface.qml
 Button 1.0 Button.qml
@@ -23,6 +25,7 @@ PanelSectionHeader 1.0 PanelSectionHeader.qml
 PanelSeparator 1.0 PanelSeparator.qml
 PanelSlider 1.0 PanelSlider.qml
 PanelToolTip 1.0 PanelToolTip.qml
+PluginBarApi 1.0 PluginBarApi.qml
 PointerMoveGate 1.0 PointerMoveGate.qml
 ScreenMoveRemap 1.0 ScreenMoveRemap.qml
 PopupCard 1.0 PopupCard.qml

shell/plugins/README.md

@@ -83,6 +83,9 @@ separate PAM services: `omarchy-lock-password` for password auth and,
 only when fingerprints are enrolled, `omarchy-lock-fingerprint` for
 fingerprint auth. It mirrors the previous lock screen field dimensions,
 colors, blurred wallpaper, placeholder, and Hyprland-driven corners.
+The plugin sets `keepLoaded: true` so a plugin hot-reload (for example
+an installed bar widget changing on disk) does not destroy the lock
+client while Hyprland still holds the session lock.
 
 ## Polkit agent
 

shell/plugins/background/Background.qml

@@ -1,4 +1,5 @@
 import Quickshell
+import Quickshell.Hyprland
 import Quickshell.Io
 import Quickshell.Wayland
 import QtQuick
@@ -16,6 +17,7 @@ Item {
 
   property string currentBackground: ""
   property string displayedBackground: ""
+  property int displayedReloads: 0
   property string incomingBackground: ""
   property string oldBackground: ""
   property bool finishingTransition: false
@@ -26,6 +28,27 @@ Item {
   property string pendingShellRaw: ""
   property real revealProgress: 1
 
+  // Injected by the first-party service loader; used to reach the lock and idle
+  // services so playback can stop whenever nothing can see the wallpaper.
+  property var shell: null
+
+  // Stop a video wallpaper's decoding whenever it is covered. Qt's FFmpeg
+  // engine drives its own clock, so an unseen player keeps decoding until it
+  // is told not to — a locked laptop would otherwise decode until it died.
+  readonly property var lockService: shell && shell.services ? shell.firstPartyServiceFor("omarchy.lock") : null
+  readonly property var idleService: shell && shell.services ? shell.firstPartyServiceFor("omarchy.idle") : null
+  readonly property var batteryService: shell && shell.services ? shell.firstPartyServiceFor("omarchy.battery") : null
+  readonly property bool lockActive: lockService ? lockService.locked : false
+  readonly property bool screensaverActive: idleService ? idleService.screensaverWindowCount > 0 : false
+  readonly property bool powerSaverActive: batteryService ? batteryService.powerSaverOnBattery : false
+  // A lock or a screensaver covers every output, so it is decided once here.
+  // Fullscreen is decided per output below, because it only covers its own.
+  readonly property bool sessionObscured: lockActive || screensaverActive
+
+  function isVideo(path) {
+    return Util.isVideoPath(path)
+  }
+
   function imageUrl(path) {
     return Util.fileUrl(path)
   }
@@ -50,10 +73,15 @@ Item {
     revealAnimation.stop()
     finishingTransition = false
 
-    if (instant || !displayedBackground) {
+    // Video frames are not fed through the image-only reveal stack. Switching
+    // instantly also avoids decoding two full videos during a transition.
+    if (instant || !displayedBackground || isVideo(path) || isVideo(displayedBackground)) {
       oldBackground = ""
       incomingBackground = ""
-      displayedBackground = path
+      // A theme switch can replace the file behind an unchanged path, which
+      // an unchanged property would never pick up.
+      if (displayedBackground === finalPath) displayedReloads += 1
+      displayedBackground = finalPath
       revealProgress = 1
       return
     }
@@ -196,11 +224,24 @@ Item {
       color: "transparent"
       // Keep render updates enabled. The background layer has been observed to
       // lose its committed buffer while parked with updatesEnabled=false,
-      // leaving a black desktop until omarchy-shell is restarted. The wallpaper
-      // itself is static, so this favors correctness over a small render-loop
-      // optimization.
+      // leaving a black desktop until omarchy-shell is restarted. A still
+      // wallpaper costs nothing to keep enabled, and a video one is throttled
+      // by pausing playback rather than by parking the layer.
       updatesEnabled: true
 
+      // Pausing every wallpaper for one fullscreen window would freeze the one
+      // still on show next to it, which costs a viewer more than it saves. The
+      // workspace on show here knows whether a fullscreen window covers it,
+      // wherever focus happens to be.
+      readonly property var hyprlandMonitor: Hyprland.monitorFor(modelData)
+      readonly property var visibleWorkspace: hyprlandMonitor ? hyprlandMonitor.activeWorkspace : null
+      readonly property bool fullscreenHere: visibleWorkspace ? visibleWorkspace.hasFullscreen : false
+
+      // A sound track plays from one output only, or every monitor would
+      // layer its own copy of it.
+      readonly property bool firstScreen: Quickshell.screens.length > 0
+        && String(Quickshell.screens[0].name || "") === String(modelData.name || "")
+
       property bool maskReady: false
 
       function maybeStartReveal() {
@@ -218,15 +259,15 @@ Item {
       WlrLayershell.keyboardFocus: WlrKeyboardFocus.None
       exclusionMode: ExclusionMode.Ignore
 
-      Image {
+      BackgroundMedia {
         id: base
         anchors.fill: parent
-        source: root.imageUrl(root.displayedBackground)
-        fillMode: Image.PreserveAspectCrop
-        asynchronous: true
-        cache: true
-        onStatusChanged: {
-          if (status === Image.Ready && root.finishingTransition) {
+        path: root.displayedBackground
+        reloads: root.displayedReloads
+        playbackEnabled: !root.sessionObscured && !root.powerSaverActive && !panel.fullscreenHere
+        audioEnabled: panel.firstScreen
+        onReadyChanged: {
+          if (ready && root.finishingTransition) {
             root.incomingBackground = ""
             root.oldBackground = ""
             root.finishingTransition = false

shell/plugins/bar/Bar.qml

@@ -12,20 +12,29 @@ Item {
   id: root
 
   // The omarchy-shell host injects omarchyPath from OMARCHY_PATH.
-  required property string omarchyPath
+  property string omarchyPath: Quickshell.env("OMARCHY_PATH")
   // Injected by the host shell so bar slots can resolve enabled widgets.
-  required property var barWidgetRegistry
+  property var barWidgetRegistry: fallbackBarWidgetRegistry
+  // Read-only registry view for third-party full bars; the built-in bar does
+  // not otherwise need it, but declaring it keeps clone construction atomic.
+  property var pluginRegistry: null
   // Injected by the host shell every time shell.json is reloaded. Holds the
   // `bar:` subtree: position, centerAnchor, layout. The host owns file IO;
   // the bar just renders whatever it's handed. The bar font follows the
   // OS-level fontconfig monospace binding — it is not stored in shell.json.
-  required property var barConfig
+  property var barConfig: ({})
   // Injected by the host shell. Used for shell-wide actions such as opening
   // settings and persisting inline widget state.
   property var shell: null
   // Manifest for the active bar option. Present for custom bars and useful for
   // diagnostics; the built-in bar does not otherwise need it.
   property var manifest: null
+  QtObject {
+    id: fallbackBarWidgetRegistry
+    property var widgets: ({})
+    property int revision: 0
+    function metadataFor(id) { return null }
+  }
   // Mirrors the on-disk `bar-off` flag so the user can hide the bar without
   // killing the entire shell. Hidden panels stay mapped but park off-screen
   // without an exclusion zone; updated by the FileView watcher further down.
@@ -100,6 +109,223 @@ Item {
   property var barMoveScreen: null
   property var clickTargets: []
   property var moduleSlots: []
+  property var pluginBarApis: ({})
+  property var pluginObjectOwners: []
+
+  Component {
+    id: pluginBarApiComponent
+    PluginBarApi { }
+  }
+
+  function publicLayoutConfig() {
+    return JSON.parse(JSON.stringify(root.layoutConfig || {}))
+  }
+
+  function bindPluginBarApi(api) {
+    if (!api) return
+    api.foreground = Qt.binding(function() { return root.foreground })
+    api.barForeground = Qt.binding(function() { return root.barForeground })
+    api.background = Qt.binding(function() { return root.background })
+    api.urgent = Qt.binding(function() { return root.urgent })
+    api.fontFamily = Qt.binding(function() { return root.fontFamily })
+    api.position = Qt.binding(function() { return root.position })
+    api.vertical = Qt.binding(function() { return root.vertical })
+    api.barSize = Qt.binding(function() { return root.barSize })
+    api.transparent = Qt.binding(function() { return root.transparent })
+    api.foregroundAnimationEnabled = Qt.binding(function() { return root.foregroundAnimationEnabled })
+    api.centerSectionRevealHeld = Qt.binding(function() { return root.centerSectionRevealHeld })
+    api._centerHoverRevealSuppressed = Qt.binding(function() { return root.centerHoverRevealSuppressed })
+    root.syncPluginBarApiObjects(api)
+  }
+
+  function syncPluginBarApiObjects(api) {
+    if (!api) return
+    api.activePopout = root.pluginOwnsBarObject(api.pluginId, root.activePopout)
+      ? root.activePopout : (root.activePopout ? api.foreignPopoutMarker : null)
+    api.clickTargets = root.pluginClickTargets(api.pluginId)
+    api.layoutConfig = root.publicLayoutConfig()
+  }
+
+  function pluginObjectRecord(target) {
+    for (var i = 0; i < pluginObjectOwners.length; i++) {
+      var record = pluginObjectOwners[i]
+      if (record && record.target === target) return record
+    }
+    return null
+  }
+
+  function markPluginObject(pluginId, target, role) {
+    var key = String(pluginId || "")
+    if (!key || !target) return false
+    var record = root.pluginObjectRecord(target)
+    if (record && record.pluginId !== key) return false
+    var next = []
+    for (var i = 0; i < pluginObjectOwners.length; i++) {
+      var existing = pluginObjectOwners[i]
+      if (!existing || existing.target !== target) next.push(existing)
+    }
+    var updated = record || { target: target, pluginId: key, clickTarget: false, popout: false }
+    updated[role] = true
+    next.push(updated)
+    pluginObjectOwners = next
+    return true
+  }
+
+  function unmarkPluginObject(pluginId, target, role) {
+    var key = String(pluginId || "")
+    var next = []
+    for (var i = 0; i < pluginObjectOwners.length; i++) {
+      var record = pluginObjectOwners[i]
+      if (!record || record.target !== target || record.pluginId !== key) {
+        next.push(record)
+        continue
+      }
+      record[role] = false
+      if (record.clickTarget || record.popout) next.push(record)
+    }
+    pluginObjectOwners = next
+  }
+
+  function pluginOwnsBarObject(pluginId, target) {
+    var record = target ? root.pluginObjectRecord(target) : null
+    return !!record && record.pluginId === String(pluginId || "")
+  }
+
+  function pluginClickTargets(pluginId) {
+    var out = []
+    for (var i = 0; i < root.clickTargets.length; i++) {
+      var target = root.clickTargets[i]
+      if (root.pluginOwnsBarObject(pluginId, target)) out.push(target)
+    }
+    return out
+  }
+
+  function syncAllPluginBarApiObjects() {
+    for (var id in pluginBarApis) root.syncPluginBarApiObjects(pluginBarApis[id])
+  }
+
+  function registerPluginClickTarget(pluginId, target) {
+    if (!root.markPluginObject(pluginId, target, "clickTarget")) return
+    root.registerClickTarget(target)
+  }
+
+  function unregisterPluginClickTarget(pluginId, target) {
+    if (!root.pluginOwnsBarObject(pluginId, target)) return
+    root.unregisterClickTarget(target)
+    root.unmarkPluginObject(pluginId, target, "clickTarget")
+  }
+
+  function requestPluginPopout(pluginId, owner) {
+    if (!root.markPluginObject(pluginId, owner, "popout")) return
+    root.requestPopout(owner)
+  }
+
+  function releasePluginPopout(pluginId, owner) {
+    if (!root.pluginOwnsBarObject(pluginId, owner)) return
+    root.releasePopout(owner)
+    root.unmarkPluginObject(pluginId, owner, "popout")
+  }
+
+  function pluginBarApiFor(pluginId, moduleName, registered) {
+    var key = String(pluginId || "")
+    if (!key) return null
+
+    var pluginShell = null
+    if (registered && root.shell && typeof root.shell.pluginShellForId === "function") {
+      // Only the trusted built-in bar receives ShellRoot and can request a
+      // service-capable facade for the widget it is instantiating.
+      pluginShell = root.shell.pluginShellForId(moduleName)
+    } else if (root.shell && typeof root.shell.pluginShellForBarEntry === "function") {
+      // Replacement bars receive a service-less entry facade. Giving an
+      // untrusted bar a generic facade factory would let it retrieve another
+      // third-party plugin's live service object.
+      pluginShell = root.shell.pluginShellForBarEntry(key, moduleName)
+    }
+
+    if (pluginBarApis[key]) {
+      pluginBarApis[key].shell = pluginShell
+      return pluginBarApis[key]
+    }
+
+    var api = pluginBarApiComponent.createObject(null, {
+      pluginId: key,
+      moduleName: String(moduleName || ""),
+      shell: pluginShell,
+      _showTooltip: function(target, text) { root.showTooltip(target, text) },
+      _hideTooltip: function(target) { root.hideTooltip(target) },
+      _registerClickTarget: function(target) { root.registerPluginClickTarget(key, target) },
+      _unregisterClickTarget: function(target) { root.unregisterPluginClickTarget(key, target) },
+      _requestPopout: function(owner) { root.requestPluginPopout(key, owner) },
+      _releasePopout: function(owner) { root.releasePluginPopout(key, owner) },
+      _switchPanelFrom: function(owner, direction) { return root.switchPanelFrom(owner, direction) },
+      _targetBelongsToWindow: function(target, window) { return root.targetBelongsToWindow(target, window) },
+      _moduleWidgets: function(requestedId) {
+        return String(requestedId || "") === String(moduleName || "")
+          ? root.moduleWidgets(moduleName) : []
+      },
+      _run: function(command) { root.run(command) },
+      _setCenterHoverRevealSuppressed: function(value) {
+        root.centerHoverRevealSuppressed = !!value
+      }
+    })
+    if (!api) return null
+    root.bindPluginBarApi(api)
+
+    var next = ({})
+    for (var id in pluginBarApis) next[id] = pluginBarApis[id]
+    next[key] = api
+    pluginBarApis = next
+    return api
+  }
+
+  function pluginBarApiUsed(pluginId) {
+    for (var i = 0; i < moduleSlots.length; i++) {
+      var slot = moduleSlots[i]
+      if (slot && slot.pluginApiId === pluginId) return true
+    }
+    return false
+  }
+
+  function releasePluginObjects(pluginId) {
+    var owned = pluginObjectOwners.slice()
+    for (var i = 0; i < owned.length; i++) {
+      var record = owned[i]
+      if (!record || record.pluginId !== pluginId) continue
+      if (record.clickTarget) root.unregisterClickTarget(record.target)
+      if (record.popout && root.activePopout === record.target) root.releasePopout(record.target)
+    }
+    pluginObjectOwners = pluginObjectOwners.filter(function(record) {
+      return record && record.pluginId !== pluginId
+    })
+  }
+
+  function prunePluginBarApis() {
+    var next = ({})
+    for (var id in pluginBarApis) {
+      var api = pluginBarApis[id]
+      if (root.pluginBarApiUsed(id)) {
+        next[id] = api
+        continue
+      }
+      root.releasePluginObjects(id)
+      if (api && typeof api.destroy === "function") api.destroy()
+    }
+    pluginBarApis = next
+  }
+
+  onActivePopoutChanged: syncAllPluginBarApiObjects()
+  onClickTargetsChanged: syncAllPluginBarApiObjects()
+  onLayoutConfigChanged: syncAllPluginBarApiObjects()
+  onModuleSlotsChanged: Qt.callLater(prunePluginBarApis)
+
+  Component.onDestruction: {
+    for (var id in pluginBarApis) {
+      root.releasePluginObjects(id)
+      if (pluginBarApis[id] && typeof pluginBarApis[id].destroy === "function")
+        pluginBarApis[id].destroy()
+    }
+    pluginBarApis = ({})
+  }
 
   function registerClickTarget(target) {
     if (!target || clickTargets.indexOf(target) !== -1) return
@@ -599,6 +825,10 @@ Item {
     if (barHoverCount === 0) centerSectionRevealTimer.restart()
   }
 
+  function setCenterHoverRevealSuppressed(value) {
+    centerHoverRevealSuppressed = !!value
+  }
+
   Timer {
     id: centerSectionRevealTimer
     interval: 120
@@ -1548,6 +1778,9 @@ Item {
     readonly property string moduleName: root.entryId(entry)
     readonly property var moduleSettings: root.entrySettings(entry)
     readonly property string customType: root.customModuleType(entry)
+    readonly property var registryMetadata: root.barWidgetRegistry.metadataFor(root.canonicalWidgetId(moduleName))
+    readonly property bool firstParty: registryMetadata && registryMetadata.firstParty === true
+    readonly property string pluginApiId: registered ? root.canonicalWidgetId(moduleName) : "bar-entry:" + moduleName
     // Re-evaluate when the registry mutates (Component reference changes,
     // plugin enabled/disabled, etc.). Reading the `widgets` property creates
     // the binding dependency — the wrapped function call alone wouldn't.
@@ -1766,7 +1999,8 @@ Item {
     function injectProps() {
       var target = activeItem
       if (!target) return
-      if ("bar" in target) target.bar = root
+      if ("bar" in target) target.bar = firstParty
+        ? root : root.pluginBarApiFor(pluginApiId, moduleName, registered)
       if ("moduleName" in target) target.moduleName = moduleName
       if ("settings" in target) target.settings = moduleSettings
     }

shell/plugins/bar/widgets/KeyboardLayout.qml

@@ -27,6 +27,11 @@ BarWidget {
   // the widget ships on the bar and stays out of the way until there are two.
   // An older Hyprland that doesn't report the list keeps showing the label.
   property bool multipleLayouts: true
+  // Where the reading sits in the layout list, how long that list is, and every
+  // keyboard sharing it. A switch moves that set together, so it needs all three.
+  property int layoutIndex: 0
+  property int layoutCount: 0
+  property var syncNames: []
   // Short language code per layout description ("English (US)": "en"), read from
   // xkb's own table rather than maintained by hand.
   property var layoutBriefs: ({})
@@ -63,17 +68,31 @@ BarWidget {
   }
 
   // switchxkblayout is a hyprctl command rather than a dispatcher, so it has to
-  // be run rather than sent over the dispatch socket. It switches the keyboard
-  // the last reading spoke for, so a click always advances the device the label
-  // is describing. Switching the seat together would reach the typed keyboard
-  // without having to name it, but it would also carry the buttons along, and
-  // the whole read depends on those staying where they started: once a button
-  // has been advanced too, a toggle that wraps the keyboard back to the first
-  // layout leaves the button reading as the furthest along, and the label
-  // follows the button.
+  // be run rather than sent over the dispatch socket.
+  //
+  // Move every keyboard holding the same layout list, rather than the single one
+  // the last reading spoke for. Naming one device puts the whole switch behind
+  // UNTYPED_KEYBOARDS recognising every non-keyboard by name, and that list
+  // cannot keep up with what a seat carries: vendor hotkey blocks
+  // (intel-hid-events, dell-wmi-hotkeys), HID consumer controls, and Bluetooth
+  // AVRCP endpoints from a pair of headphones all arrive holding the seat's
+  // layout list, and they sort ahead of the keyboard being typed on. The click
+  // then advances a device nobody types on; that device is now the furthest
+  // along, so it wins the next reading too, and the label describes it while the
+  // real keyboard never moved.
+  //
+  // An absolute index rather than "next", because "next" advances each device
+  // from wherever it already sits: a seat that has drifted apart stays drifted
+  // and merely inverts. One index converges them in a single click, and a seat
+  // in lockstep is what leaves the reading nothing to disagree about afterwards.
+  //
+  // Keyboards given their own kb_layout hold a different list and are left out:
+  // an index into this list would not mean the same layout to them.
   function cycleLayout() {
-    if (!root.keyboardName || !root.bar) return
-    root.bar.run("hyprctl switchxkblayout " + Util.shellQuote(root.keyboardName) + " next")
+    if (!root.bar || root.layoutCount < 2 || root.syncNames.length === 0) return
+    const next = (root.layoutIndex + 1) % root.layoutCount
+    root.bar.run(root.syncNames.map(name =>
+      "hyprctl switchxkblayout " + Util.shellQuote(name) + " " + next).join("; "))
     refreshTimer.restart()
   }
 
@@ -149,6 +168,14 @@ BarWidget {
         root.keyboardCount = typed.length
         root.keyboardName = String(kb.name || "")
         root.multipleLayouts = kb.layout === undefined || String(kb.layout).indexOf(",") !== -1
+        root.layoutIndex = kb.active_layout_index || 0
+        root.layoutCount = kb.layout === undefined ? 0 : String(kb.layout).split(",").length
+        // Buttons and virtual keyboards are included on purpose: they hold the
+        // same list, and leaving them behind is what lets a reading drift onto
+        // one of them later.
+        root.syncNames = listed.filter(k => String(k.layout) === String(kb.layout))
+                               .map(k => String(k.name || ""))
+                               .filter(name => name !== "")
         root.layoutFull = kb.active_keymap
       }
     }