From 41a40ccc78b60c9698a0e45dc358f0e4b5ffd5a3 Mon Sep 17 00:00:00 2001
From: Tobi Lutke <tobi@shopify.com>
Date: Fri, 28 Aug 2026 20:03:19 -0500
Subject: [PATCH 01/27] Show captive portal status and sign-in action in
 network panel

---
 shell/plugins/panels/network/Model.js         |  24 ++-
 shell/plugins/panels/network/Panel.qml        | 141 +++++++++++++--
 .../mocks/NetworkMock.qml                     |  31 ++++
 .../network-captive-portal/mocks/qmldir       |   1 +
 .../fixtures/network-captive-portal/shell.qml | 161 ++++++++++++++++++
 test/shell.d/network-captive-portal-test.sh   |  95 +++++++++++
 6 files changed, 438 insertions(+), 15 deletions(-)
 create mode 100644 test/shell.d/fixtures/network-captive-portal/mocks/NetworkMock.qml
 create mode 100644 test/shell.d/fixtures/network-captive-portal/mocks/qmldir
 create mode 100644 test/shell.d/fixtures/network-captive-portal/shell.qml
 create mode 100755 test/shell.d/network-captive-portal-test.sh

diff --git a/shell/plugins/panels/network/Model.js b/shell/plugins/panels/network/Model.js
index b4c84c68..5ed2c0d6 100644
--- a/shell/plugins/panels/network/Model.js
+++ b/shell/plugins/panels/network/Model.js
@@ -14,9 +14,25 @@ function wifiIconFor(strength) {
   return icons[index]
 }
 
-function connectionIcon(kind, signalStrength) {
-  if (kind === "wifi") return wifiIconFor(signalStrength)
-  if (kind === "ethernet") return "󰈀"
+// A known plain-HTTP endpoint lets the network redirect the browser to its
+// login page. Never execute or automatically open an untrusted Location header.
+var captivePortalUrl = "http://ping.archlinux.org/nm-check.txt"
+
+function connectivityState(kind, connectivity, states, checksEnabled) {
+  if (kind === "disconnected") return "none"
+  // Ignore stale cached results when the operator has disabled probing.
+  if (!checksEnabled) return "unknown"
+  if (connectivity === states.Portal) return "portal"
+  if (connectivity === states.Limited) return "limited"
+  if (connectivity === states.Full) return "full"
+  if (connectivity === states.None) return "none"
+  return "unknown"
+}
+
+function connectionIcon(kind, signalStrength, connectivity) {
+  var restricted = connectivity === "portal" || connectivity === "limited"
+  if (kind === "wifi") return restricted ? "󰤩" : wifiIconFor(signalStrength)
+  if (kind === "ethernet") return restricted ? "󰈂" : "󰈀"
   return "󰤮"
 }
 
@@ -352,6 +368,8 @@ if (typeof module !== "undefined") {
     parseNetworkStatus: parseNetworkStatus,
     wifiIconFor: wifiIconFor,
     connectionIcon: connectionIcon,
+    connectivityState: connectivityState,
+    captivePortalUrl: captivePortalUrl,
     formatHeaderSpeed: formatHeaderSpeed,
     formatHeaderFreq: formatHeaderFreq,
     headerDetail: headerDetail,
diff --git a/shell/plugins/panels/network/Panel.qml b/shell/plugins/panels/network/Panel.qml
index d1e41149..97729dcc 100644
--- a/shell/plugins/panels/network/Panel.qml
+++ b/shell/plugins/panels/network/Panel.qml
@@ -119,9 +119,9 @@ Panel {
   property bool cursorActive: false
 
   // Keyboard focus zone for the panel. j/k crosses row boundaries:
-  // header actions ⇄ band ⇄ DNS row ⇄ Wi-Fi networks. h/l move
+  // header actions ⇄ portal ⇄ band ⇄ DNS row ⇄ Wi-Fi networks. h/l move
   // within header actions, band pills, or DNS providers.
-  property string focusSection: "dns"  // "header" | "band" | "dns" | "wifi"
+  property string focusSection: "dns"  // "header" | "portal" | "band" | "dns" | "wifi"
   property int headerIndex: 0
   readonly property bool canDisconnect: !!connectedWifiNetwork
   readonly property bool headerHasDisconnect: false
@@ -220,6 +220,8 @@ Panel {
     // network target; both cards are their own plugins now.
     function showQr() { root.summonWifiQr(true) }
     function speedTest() { root.summonSpeedTest() }
+    function openCaptivePortal() { root.openCaptivePortal() }
+    function checkConnectivity() { root.checkConnectivity() }
   }
 
   function activateHeader() {
@@ -322,11 +324,11 @@ Panel {
       refresh(true)
       selectedIndex = wifiNetworks.length > 0 ? 0 : -1
       wifiActionFocused = false
-      focusSection = wifiNetworks.length > 0 ? "wifi" : "dns"
+      focusSection = hasCaptivePortal ? "portal" : (wifiNetworks.length > 0 ? "wifi" : "dns")
       var idx = dnsProviders.indexOf(dnsProvider)
       dnsIndex = idx >= 0 ? idx : 0
       syncBandIndex()
-      cursorActive = false
+      cursorActive = hasCaptivePortal
     } else {
       // Drop a restart armed by this open: without it a close/reopen inside
       // the 100ms window reuses the running timer and re-enables the scanner
@@ -450,7 +452,59 @@ Panel {
     Quickshell.execDetached(["bash", "-c", "printf %s " + Util.shellQuote(value) + " | wl-copy"])
   }
 
-  readonly property string icon: Model.connectionIcon(kind, signalStrength)
+  // NetworkManager performs the HTTP probe (including unexpected page bodies,
+  // not just redirects). Consume its native notifications rather than running
+  // a second curl loop or mistaking an ordinary timeout for a captive portal.
+  readonly property bool connectivityChecksEnabled: networkManagerAvailable
+    && Networking.canCheckConnectivity && Networking.connectivityCheckEnabled
+  readonly property string connectivity: Model.connectivityState(kind, Networking.connectivity, {
+    Portal: NetworkConnectivity.Portal, Limited: NetworkConnectivity.Limited,
+    Full: NetworkConnectivity.Full, None: NetworkConnectivity.None
+  }, connectivityChecksEnabled)
+  readonly property bool hasCaptivePortal: connectivity === "portal"
+  readonly property bool restricted: hasCaptivePortal || connectivity === "limited"
+  readonly property string icon: Model.connectionIcon(kind, signalStrength, connectivity)
+  readonly property string connectionKey: kind === "wifi" && wifiDevice && connectedWifiNetwork
+    ? kind + ":" + wifiDevice.name + ":" + connectedWifiNetwork.name
+    : (kind === "ethernet" && wiredDevice ? kind + ":" + wiredDevice.name : "")
+
+  onConnectionKeyChanged: Qt.callLater(checkConnectivity)
+  onConnectivityChecksEnabledChanged: Qt.callLater(checkConnectivity)
+  onHasCaptivePortalChanged: {
+    if (hasCaptivePortal && opened && passwordSsid === "") {
+      focusSection = "portal"
+      cursorActive = true
+    } else if (!hasCaptivePortal && focusSection === "portal") {
+      focusSection = headerActionCount > 0 ? "header" : "dns"
+      headerIndex = 0
+    }
+  }
+  onRestrictedChanged: {
+    connectionPhraseSwap.stop()
+    heroMeta.opacity = 1.0
+  }
+
+  function checkConnectivity() {
+    if (connectivityChecksEnabled && kind !== "disconnected") Networking.checkConnectivity()
+  }
+
+  function openCaptivePortal() {
+    if (!hasCaptivePortal) return
+    // Explicit user action only. argv (not a shell string), and a fixed HTTP
+    // URL: let the browser handle the redirect without trusting portal input.
+    Quickshell.execDetached(["omarchy-launch-browser", Model.captivePortalUrl])
+    close()
+  }
+
+  // Keep checking while login is needed, even with the panel closed in favour
+  // of the browser. Normal connected operation relies on NM's own schedule.
+  Timer {
+    id: connectivityPoll
+    interval: 10000
+    repeat: true
+    running: root.restricted && root.connectivityChecksEnabled
+    onTriggered: root.checkConnectivity()
+  }
 
   // The share card is its own panel plugin (omarchy.wifiqr) so a replacement
   // design can take it over; summon() routes to whichever implementation is
@@ -469,6 +523,7 @@ Panel {
   }
 
   function refresh(scanWifi) {
+    checkConnectivity()
     if (scanWifi === undefined) scanWifi = false
     if (!detailsProc.running) detailsProc.running = true
     if (!dnsProc.running) {
@@ -901,7 +956,7 @@ Panel {
   Timer {
     id: connectionPhraseTimer
     interval: 2800
-    running: root.opened && (root.info.type === "ethernet" || (root.info.type === "wifi" && root.canDisconnect))
+    running: root.opened && !root.restricted && (root.info.type === "ethernet" || (root.info.type === "wifi" && root.canDisconnect))
     repeat: true
     onTriggered: connectionPhraseSwap.restart()
   }
@@ -958,6 +1013,9 @@ Panel {
     anchors.fill: parent
     bar: root.bar
     text: root.icon
+    active: root.restricted
+    tooltipText: root.hasCaptivePortal ? "Sign in to this network"
+      : (root.restricted ? "Limited internet access" : "")
 
     onPressed: function(b) {
       if (root.opened) root.close()
@@ -1001,23 +1059,34 @@ Panel {
           if (dy >= 0) return
         }
         if (dy !== 0) {
-          // Vertical order is header ⇄ band ⇄ DNS ⇄ wifi, with the band section
-          // dropping out of the chain entirely when it isn't on screen.
+          // Hidden sections drop out of the keyboard chain entirely.
           if (root.focusSection === "header") {
             if (dy > 0) {
-              if (root.canSelectBand) {
+              if (root.hasCaptivePortal) {
+                root.focusSection = "portal"
+              } else if (root.canSelectBand) {
                 root.focusSection = "band"
                 root.bandAutoFocused = true
               } else {
                 root.focusSection = "dns"
               }
             }
+          } else if (root.focusSection === "portal") {
+            if (dy < 0 && root.headerActionCount > 0) {
+              root.focusSection = "header"
+              root.headerIndex = 0
+            } else if (dy > 0) {
+              root.focusSection = root.canSelectBand ? "band" : "dns"
+              root.bandAutoFocused = true
+            }
           } else if (root.focusSection === "band") {
             // Automatic on the header line, then the pills -- which collapse
             // away under Automatic, leaving a single row to walk.
             if (dy < 0) {
               if (!root.bandAutoFocused) {
                 root.bandAutoFocused = true
+              } else if (root.hasCaptivePortal) {
+                root.focusSection = "portal"
               } else if (root.headerActionCount > 0) {
                 root.focusSection = "header"
                 root.headerIndex = 0
@@ -1035,6 +1104,8 @@ Panel {
               if (root.canSelectBand) {
                 root.focusSection = "band"
                 root.bandAutoFocused = !root.bandPillsVisible
+              } else if (root.hasCaptivePortal) {
+                root.focusSection = "portal"
               } else if (root.headerActionCount > 0) {
                 root.focusSection = "header"
                 root.headerIndex = 0
@@ -1063,6 +1134,7 @@ Panel {
       onActivateRequested: {
         if (root.cursorActive) {
           if (root.focusSection === "header") root.activateHeader()
+          else if (root.focusSection === "portal") root.openCaptivePortal()
           else if (root.focusSection === "band") root.activateBand()
           else if (root.focusSection === "dns") root.activateDns()
           else root.activateSelected()
@@ -1092,7 +1164,7 @@ Panel {
           id: heroIcon
           textFormat: Text.PlainText
           text: root.icon
-          color: root.bar.foreground
+          color: root.restricted ? root.bar.urgent : root.bar.foreground
           font.family: root.bar.fontFamily
           font.pixelSize: Style.font.display
           opacity: root.networkManagerAvailable ? 1.0 : 0.5
@@ -1175,6 +1247,9 @@ Panel {
             width: parent.width
 
             readonly property string title: {
+              // The HTTP restriction does not undo association. Show the live
+              // SSID even before route/details polling has returned anything.
+              if (root.kind === "wifi" && root.connectedWifiNetwork) return root.connectedWifiNetwork.name || "Wi-Fi"
               if (root.info.type === "wifi") return root.info.ssid || "Wi-Fi"
               if (root.info.type === "ethernet") return "Ethernet"
               return root.info.iface || (root.kind === "disconnected" ? "Disconnected" : "No connection")
@@ -1194,6 +1269,8 @@ Panel {
             textFormat: Text.PlainText
             width: parent.width
             text: {
+              if (root.hasCaptivePortal) return "SIGN-IN REQUIRED"
+              if (root.restricted) return "LIMITED INTERNET ACCESS"
               if (root.info.type === "wifi") {
                 if (root.canDisconnect) return root.connectionPhrase.toUpperCase()
                 if (root.kind === "disconnected") return "NOT CONNECTED"
@@ -1204,7 +1281,7 @@ Panel {
               return ""
             }
             visible: text !== ""
-            color: Qt.darker(root.bar.foreground, 1.4)
+            color: root.restricted ? root.bar.urgent : Qt.darker(root.bar.foreground, 1.4)
             font.family: root.bar.fontFamily
             font.pixelSize: Style.font.caption
             font.bold: true
@@ -1215,6 +1292,43 @@ Panel {
 
       }
 
+      Column {
+        visible: root.hasCaptivePortal
+        width: parent.width
+        spacing: Style.space(6)
+
+        Button {
+          id: portalAction
+          width: parent.width
+          text: "Open Captive Portal"
+          iconText: "󰏌"
+          foreground: root.bar.urgent
+          accent: root.bar.urgent
+          fontFamily: root.bar.fontFamily
+          verticalPadding: Style.space(10)
+          bordered: true
+          active: true
+          hasCursor: root.cursorActive && root.focusSection === "portal"
+          onHovered: function(on) {
+            if (!on) return
+            root.cursorActive = true
+            root.focusSection = "portal"
+          }
+          onClicked: root.openCaptivePortal()
+        }
+
+        Text {
+          width: parent.width
+          text: "Sign in or accept this network’s terms to access the internet."
+          textFormat: Text.PlainText
+          wrapMode: Text.WordWrap
+          color: root.bar.foreground
+          opacity: 0.7
+          font.family: root.bar.fontFamily
+          font.pixelSize: Style.font.bodySmall
+        }
+      }
+
       // Connection details: transfer metrics first, then IP/Gateway.
       Column {
         visible: !!root.info.iface
@@ -1654,6 +1768,7 @@ Panel {
       if (isBusy && root.actionKind === "disconnect") return "Disconnecting…"
       if (isBusy && root.actionKind === "forget") return "Forgetting…"
       if (isFailed) return root.failureReason || "Failed"
+      if (isConnected && root.kind === "wifi" && root.hasCaptivePortal) return "Sign-in required"
       if (isConnected) return "Connected"
       return ""
     }
@@ -1661,6 +1776,7 @@ Panel {
     readonly property color statusColor: {
       if (isFailed) return root.bar.urgent
       if (isBusy) return root.bar.foreground
+      if (isConnected && root.kind === "wifi" && root.hasCaptivePortal) return root.bar.urgent
       if (isConnected) return root.bar.foreground
       return Qt.darker(root.bar.foreground, 1.5)
     }
@@ -1715,7 +1831,8 @@ Panel {
       Text {
         id: networkIcon
         textFormat: Text.PlainText
-        text: row.net ? root.wifiIconFor(row.net.signal) : ""
+        text: row.net ? Model.connectionIcon("wifi", row.net.signal,
+          row.isConnected && root.kind === "wifi" ? root.connectivity : "") : ""
         color: row.statusColor
         font.family: root.bar.fontFamily
         font.pixelSize: Style.font.title
diff --git a/test/shell.d/fixtures/network-captive-portal/mocks/NetworkMock.qml b/test/shell.d/fixtures/network-captive-portal/mocks/NetworkMock.qml
new file mode 100644
index 00000000..b41c6513
--- /dev/null
+++ b/test/shell.d/fixtures/network-captive-portal/mocks/NetworkMock.qml
@@ -0,0 +1,31 @@
+pragma Singleton
+import QtQuick
+import Quickshell.Networking
+
+QtObject {
+  property int backend: NetworkBackendType.NetworkManager
+  property bool wifiEnabled: true
+  property bool canCheckConnectivity: true
+  property bool connectivityCheckEnabled: true
+  property int connectivity: NetworkConnectivity.Full
+  property int checks: 0
+  function checkConnectivity() { checks++ }
+
+  property var devices: ({ values: [wifi] })
+  property QtObject wifi: QtObject {
+    property int type: DeviceType.Wifi
+    property string name: "test-wifi"
+    property bool connected: true
+    property bool scannerEnabled: false
+    property var networks: ({ values: [network] })
+  }
+  property QtObject network: QtObject {
+    property string name: "Guest Wi-Fi"
+    property bool connected: true
+    property bool known: true
+    property bool stateChanging: false
+    property real signalStrength: 0.8
+    property int security: WifiSecurityType.Open
+    signal connectionFailed(int reason)
+  }
+}
diff --git a/test/shell.d/fixtures/network-captive-portal/mocks/qmldir b/test/shell.d/fixtures/network-captive-portal/mocks/qmldir
new file mode 100644
index 00000000..03b0cb27
--- /dev/null
+++ b/test/shell.d/fixtures/network-captive-portal/mocks/qmldir
@@ -0,0 +1 @@
+singleton NetworkMock 1.0 NetworkMock.qml
diff --git a/test/shell.d/fixtures/network-captive-portal/shell.qml b/test/shell.d/fixtures/network-captive-portal/shell.qml
new file mode 100644
index 00000000..24c361bc
--- /dev/null
+++ b/test/shell.d/fixtures/network-captive-portal/shell.qml
@@ -0,0 +1,161 @@
+import QtQuick
+import Quickshell
+import Quickshell.Networking
+import qs.Commons
+import "mocks"
+import "network" as Network
+
+ShellRoot {
+  id: test
+  property bool failed: false
+  function check(ok, message) {
+    if (!ok) {
+      failed = true
+      console.log("RESULT fail " + message)
+    }
+  }
+
+  // Not visible in the normal test run. The optional preview maps the real
+  // KeyboardPanel for a screenshot, without ever altering the host network.
+  Item {
+    Network.Panel {
+      id: panel
+      bar: QtObject {
+        property color foreground: Color.foreground
+        property color barForeground: Color.foreground
+        property color urgent: Color.urgent
+        property string fontFamily: Style.font.family
+        property string position: "top"
+        property int barSize: 24
+        property bool vertical: false
+        property bool foregroundAnimationEnabled: false
+        property var activePopout: null
+        function requestPopout(owner) { activePopout = owner }
+        function releasePopout(owner) { activePopout = null }
+        function registerClickTarget(target) {}
+        function unregisterClickTarget(target) {}
+        function hideTooltip(target) {}
+        function showTooltip(target, text) {}
+      }
+    }
+  }
+
+  Timer {
+    interval: 250
+    running: true
+    onTriggered: {
+      test.check(panel.kind === "wifi", "connected Wi-Fi fixture")
+      test.check(panel.connectivity === "full", "normal connectivity")
+      test.check(!panel.testButton.visible && !panel.testBarButton.active, "no false portal banner")
+      test.check(!panel.testPoll.running, "normal connectivity adds no polling")
+      test.check(NetworkMock.checks > 0, "checks at connection/startup")
+      var before = NetworkMock.checks
+      panel.checkConnectivity()
+      test.check(NetworkMock.checks === before + 1, "manual check delegates to NM")
+      NetworkMock.connectivity = NetworkConnectivity.Portal
+      Qt.callLater(portalChecks)
+    }
+  }
+
+  function portalChecks() {
+    check(panel.hasCaptivePortal && panel.restricted, "native portal activates restricted mode")
+    check(panel.testButton.visible, "portal button visible")
+    check(panel.testButton.text === "Open Captive Portal", "prominent action label")
+    check(panel.icon === "󰤩" && panel.testBarButton.active, "blocked bar icon and warning color")
+    check(panel.testMeta.text === "SIGN-IN REQUIRED", "status replaces cheerful connection phrase")
+    check(panel.testTitle.text === "Guest Wi-Fi", "connected SSID survives missing route details")
+    check(panel.testPoll.running && panel.testPoll.interval === 10000, "restricted recheck runs while closed")
+    var before = NetworkMock.checks
+    panel.testPoll.triggered()
+    check(NetworkMock.checks === before + 1, "background timer rechecks through NM")
+    panel.testKeys.textKey("r")
+    check(NetworkMock.checks === before + 2, "r requests fresh connectivity")
+    // Exercise the existing cursor model, not a separate test-only action.
+    panel.cursorActive = true
+    panel.focusSection = "header"
+    panel.testKeys.moveRequested(0, 1)
+    check(panel.focusSection === "portal", "down from header reaches portal")
+    panel.testKeys.moveRequested(0, 1)
+    check(panel.focusSection === "dns", "down from portal skips absent band")
+    panel.testKeys.moveRequested(0, -1)
+    check(panel.focusSection === "portal", "up from DNS reaches portal")
+    panel.bandAvailable = ["2.4", "5"]
+    panel.testKeys.moveRequested(0, 1)
+    check(panel.focusSection === "band", "down from portal reaches available band")
+    panel.testKeys.moveRequested(0, -1)
+    check(panel.focusSection === "portal", "up from band reaches portal")
+    panel.testKeys.activateRequested()
+    NetworkMock.connectivity = NetworkConnectivity.Full
+    Qt.callLater(recoveryChecks)
+  }
+
+  function recoveryChecks() {
+    check(!panel.hasCaptivePortal && !panel.restricted, "login recovery clears restriction")
+    check(!panel.testPoll.running, "recovery stops extra checks")
+    check(!panel.testButton.visible && !panel.testBarButton.active, "recovery hides button and warning color")
+    check(panel.focusSection === "header", "disappearing button leaves valid cursor")
+    check(panel.icon !== "󰤩", "signal icon returns")
+    // No browser launch when the portal is gone (runner asserts one launch).
+    panel.openCaptivePortal()
+    NetworkMock.connectivity = NetworkConnectivity.Limited
+    Qt.callLater(limitedChecks)
+  }
+
+  function limitedChecks() {
+    check(panel.restricted && !panel.hasCaptivePortal, "outage is not mislabelled as a portal")
+    check(!panel.testButton.visible && panel.testMeta.text === "LIMITED INTERNET ACCESS", "limited state has no login button")
+    NetworkMock.connectivity = NetworkConnectivity.Portal
+    NetworkMock.connectivityCheckEnabled = false
+    Qt.callLater(disabledChecks)
+  }
+
+  function disabledChecks() {
+    check(!panel.hasCaptivePortal && panel.connectivity === "unknown", "disabled checks ignore cached portal")
+    check(!panel.testPoll.running, "disabled checks stop polling")
+    var before = NetworkMock.checks
+    panel.checkConnectivity()
+    check(NetworkMock.checks === before, "does not enable or invoke disabled checks")
+    NetworkMock.connectivityCheckEnabled = true
+    NetworkMock.network.connected = false
+    NetworkMock.wifi.connected = false
+    Qt.callLater(disconnectedChecks)
+  }
+
+  function disconnectedChecks() {
+    check(panel.kind === "disconnected" && !panel.hasCaptivePortal, "disconnect clears stale portal")
+    check(!panel.testButton.visible && panel.icon === "󰤮", "disconnected icon not portal icon")
+    if (failed) { Qt.quit(); return }
+    console.log("RESULT pass")
+    var preview = Quickshell.env("NETWORK_TEST_PREVIEW")
+    if (preview === "portal" || preview === "full") {
+      NetworkMock.network.connected = true
+      NetworkMock.wifi.connected = true
+      NetworkMock.connectivity = preview === "portal" ? NetworkConnectivity.Portal : NetworkConnectivity.Full
+      panel.open()
+      previewCapture.start()
+      previewDone.start()
+    } else {
+      // Give the detached, stubbed browser command time to append its argv.
+      done.start()
+    }
+  }
+
+  // Optional fresh, panel-only captures. Rendering the card itself excludes
+  // the host desktop, and the network details above come only from fixtures.
+  // NETWORK_TEST_PREVIEW=portal (or full), NETWORK_TEST_SCREENSHOT=/tmp/new.png
+  Timer {
+    id: previewCapture
+    interval: 750
+    onTriggered: {
+      var path = Quickshell.env("NETWORK_TEST_SCREENSHOT")
+      if (!path) return
+      var card = panel.testKeys.parent.parent
+      card.grabToImage(function(result) {
+        test.check(result.saveToFile(path), "save fresh preview screenshot")
+        Qt.quit()
+      })
+    }
+  }
+  Timer { id: done; interval: 300; onTriggered: Qt.quit() }
+  Timer { id: previewDone; interval: 15000; onTriggered: Qt.quit() }
+}
diff --git a/test/shell.d/network-captive-portal-test.sh b/test/shell.d/network-captive-portal-test.sh
new file mode 100755
index 00000000..0802eeb7
--- /dev/null
+++ b/test/shell.d/network-captive-portal-test.sh
@@ -0,0 +1,95 @@
+#!/bin/bash
+
+set -euo pipefail
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+run_node_test <<'JS'
+const network = requireFromRoot('shell/plugins/panels/network/Model.js')
+const states = { Unknown: 0, None: 1, Portal: 2, Limited: 3, Full: 4 }
+
+for (const kind of ['wifi', 'ethernet']) {
+  for (const [native, expected] of [
+    ['Unknown', 'unknown'], ['None', 'none'], ['Portal', 'portal'],
+    ['Limited', 'limited'], ['Full', 'full']
+  ]) {
+    assertEqual(network.connectivityState(kind, states[native], states, true), expected,
+      `${kind} maps native ${native} connectivity without confusing an outage with a portal`)
+  }
+  assertEqual(network.connectivityState(kind, 99, states, true), 'unknown', `${kind} handles unknown connectivity`)
+  for (const native of Object.values(states)) {
+    assertEqual(network.connectivityState(kind, native, states, false), 'unknown', `${kind} ignores stale results with probing disabled (${native})`)
+  }
+}
+for (const native of Object.values(states)) {
+  assertEqual(network.connectivityState('disconnected', native, states, true), 'none', `disconnect clears stale connectivity (${native})`)
+}
+for (const state of ['portal', 'limited']) {
+  assertEqual(network.connectionIcon('wifi', 80, state), '󰤩', `${state} uses a blocked Wi-Fi icon`)
+  assertEqual(network.connectionIcon('ethernet', 80, state), '󰈂', `${state} uses a blocked Ethernet icon`)
+  assertEqual(network.connectionIcon('disconnected', 80, state), '󰤮', `${state} does not override the disconnected icon`)
+}
+for (const state of ['full', 'unknown', 'none', undefined]) {
+  for (const signal of [-1, 0, 20, 40, 60, 80, 100]) {
+    assertEqual(network.connectionIcon('wifi', signal, state), network.wifiIconFor(signal), `${state} preserves Wi-Fi strength ${signal}`)
+  }
+  assertEqual(network.connectionIcon('ethernet', -1, state), '󰈀', `${state} preserves the Ethernet icon`)
+}
+const url = new URL(network.captivePortalUrl)
+assertEqual(url.protocol, 'http:', 'browser entry point uses plain HTTP so a portal can intercept it')
+assertEqual(url.hostname, 'ping.archlinux.org', 'browser entry point is fixed rather than portal-supplied')
+assertEqual(url.username + url.password, '', 'browser entry point contains no credentials')
+JS
+
+require_compositor "network captive-portal runtime test"
+require_command quickshell
+
+stage=$(mktemp -d)
+trap 'rm -rf -- "$stage"' EXIT
+fixture="$SHELL_TEST_DIR/fixtures/network-captive-portal"
+mkdir -p "$stage/network" "$stage/bin" "$stage/home"
+ln -s "$ROOT/shell/Ui" "$stage/Ui"
+ln -s "$ROOT/shell/Commons" "$stage/Commons"
+cp -r "$fixture/mocks" "$stage/mocks"
+cp "$fixture/shell.qml" "$stage/shell.qml"
+cp "$ROOT/shell/plugins/panels/network/Model.js" "$stage/network/Model.js"
+node - "$ROOT" "$stage" <<'JS'
+const fs = require('fs')
+const [root, stage] = process.argv.slice(2)
+let source = fs.readFileSync(`${root}/shell/plugins/panels/network/Panel.qml`, 'utf8')
+// Keep installed enum values and actual UI bindings. Only replace the singleton
+// and expose private IDs in the disposable copy, never in production code.
+source = source.replace('import Quickshell.Networking', 'import Quickshell.Networking\nimport "../mocks"')
+source = source.replace(/\bNetworking\./g, 'NetworkMock.')
+source = source.replace('  id: root', `  id: root
+  property alias testButton: portalAction
+  property alias testKeys: keyCatcher
+  property alias testMeta: heroMeta
+  property alias testTitle: heroSsid
+  property alias testPoll: connectivityPoll
+  property alias testBarButton: button`)
+fs.writeFileSync(`${stage}/network/Panel.qml`, source)
+JS
+printf '#!/bin/bash\nexit 0\n' > "$stage/bin/noop"
+chmod +x "$stage/bin/noop"
+for command in omarchy-dns omarchy-network-band; do
+  ln -s noop "$stage/bin/$command"
+done
+# Preview uses only synthetic details, never the host's SSID or addresses.
+# Normal assertions keep the details empty to exercise missing-route handling.
+printf '#!/bin/bash\nif [[ -n ${NETWORK_TEST_PREVIEW:-} ]]; then\n  printf "type\\twifi\\niface\\ttest-wifi\\nssid\\tGuest Wi-Fi\\nip\\t192.0.2.10\\ngateway\\t192.0.2.1\\n"\nfi\n' > "$stage/bin/omarchy-network-status"
+chmod +x "$stage/bin/omarchy-network-status"
+printf '#!/bin/bash\nprintf "%%s\\n" "$@" >> "$NETWORK_TEST_BROWSER_LOG"\n' > "$stage/bin/omarchy-launch-browser"
+chmod +x "$stage/bin/omarchy-launch-browser"
+
+# All networking and external actions are mocked; the real connection and
+# browser are never touched, and the fixture writes only to its scratch HOME.
+output=$(HOME="$stage/home" OMARCHY_PATH="$ROOT" PATH="$stage/bin:$PATH" \
+  NETWORK_TEST_BROWSER_LOG="$stage/browser.log" \
+  timeout 30 quickshell -p "$stage" --no-color 2>&1) || fail "network portal fixture exits cleanly" "$output"
+[[ $output == *"RESULT pass"* ]] || fail "network portal runtime assertions pass" "$output"
+if rg -q 'RESULT fail|ReferenceError|TypeError|Error:|Unable to assign|Binding loop' <<< "$output"; then
+  fail "network portal fixture has no QML errors" "$output"
+fi
+[[ -f $stage/browser.log ]] || fail "portal action launches the browser"
+[[ $(<"$stage/browser.log") == "http://ping.archlinux.org/nm-check.txt" ]] || fail "portal opens exactly one fixed HTTP URL"
+pass "network portal, recovery, disabled checks, outage, disconnect, keyboard navigation, and browser argv work in QML"

From f08840d6cc98b81b78290d8e6ff61567b4b21079 Mon Sep 17 00:00:00 2001
From: Spencer Bull <spencer@omarchy.org>
Date: Tue, 1 Sep 2026 14:25:37 -0500
Subject: [PATCH 02/27] Probe Hermes readiness by the flags omarchy-agent
 passes

Hermes v0.20 removed chat's --oneshot flag, which hermes_prompt_ready
used as its capability marker. A fully bootstrapped Hermes Desktop
install then read as not ready: --check failed forever, the default
agent flow looped back into the installer, and --now dead-ended with
"Launch Hermes Desktop once to finish installing it" on a machine
where it already had.

Probe for --tui and --query instead: the flags omarchy-agent actually
passes to seed an interactive session, rather than one that merely
shipped alongside them.
---
 bin/omarchy-install-hermes-cli  |  9 ++++++---
 test/shell.d/hermes-cli-test.sh | 18 ++++++++++++++++--
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/bin/omarchy-install-hermes-cli b/bin/omarchy-install-hermes-cli
index 5b6a3598..150364c0 100755
--- a/bin/omarchy-install-hermes-cli
+++ b/bin/omarchy-install-hermes-cli
@@ -88,13 +88,16 @@ hermes_runs() {
     timeout 15 "$HOME/.local/bin/hermes" --version >/dev/null 2>&1
 }
 
-# The chat subcommand's --oneshot opt-out arrived with native interactive -q,
-# so its presence is a stable capability check without relying on a version.
+# Probed for the flags omarchy-agent actually passes -- --query to seed the
+# session and --tui to keep it interactive -- rather than a flag that merely
+# shipped alongside them: the previous marker, --oneshot, was dropped in Hermes
+# v0.20 and left working installs stranded as "not ready".
 hermes_prompt_ready() {
   local help
   hermes_runs &&
     help=$(timeout 15 "$HOME/.local/bin/hermes" chat --help 2>/dev/null) &&
-    grep -qF -- '--oneshot' <<<"$help"
+    grep -qF -- '--tui' <<<"$help" &&
+    grep -qF -- '--query' <<<"$help"
 }
 
 # --owns answers whether the wrapper on PATH is the one this command wrote, so
diff --git a/test/shell.d/hermes-cli-test.sh b/test/shell.d/hermes-cli-test.sh
index 83b516e9..2144a795 100755
--- a/test/shell.d/hermes-cli-test.sh
+++ b/test/shell.d/hermes-cli-test.sh
@@ -98,7 +98,7 @@ mkdir -p "$test_home/.hermes/hermes-agent/venv/bin"
 cat >"$test_home/.hermes/hermes-agent/venv/bin/hermes" <<'SH'
 #!/bin/bash
 if [[ ${1:-} == "chat" && ${2:-} == "--help" ]]; then
-  [[ ${OMARCHY_TEST_HERMES_CAPABLE:-1} == 1 ]] && echo "--oneshot"
+  [[ ${OMARCHY_TEST_HERMES_CAPABLE:-1} == 1 ]] && echo "[-q QUERY, --query QUERY] [--tui]"
 else
   echo "hermes-agent 0.0.0-test"
 fi
@@ -388,7 +388,7 @@ run_ready_check && fail "--check rejects the app's wrapper when its runtime is g
 cat >"$ready_home/.hermes/hermes-agent/venv/bin/hermes" <<'SH'
 #!/bin/bash
 if [[ ${1:-} == "chat" && ${2:-} == "--help" ]]; then
-  echo "--oneshot"
+  echo "[-q QUERY, --query QUERY] [--tui]"
 else
   echo "hermes-agent 0.0.0-test"
 fi
@@ -396,3 +396,17 @@ SH
 chmod +x "$ready_home/.hermes/hermes-agent/venv/bin/hermes"
 run_ready_check || fail "--check accepts the app's wrapper once it runs"
 pass "readiness runs the app's command rather than trusting its marker"
+
+# A release whose help lists only the retired --oneshot marker cannot run the
+# seeded --tui --query session omarchy-agent starts, so it is not ready.
+cat >"$ready_home/.hermes/hermes-agent/venv/bin/hermes" <<'SH'
+#!/bin/bash
+if [[ ${1:-} == "chat" && ${2:-} == "--help" ]]; then
+  echo "--oneshot"
+else
+  echo "hermes-agent 0.0.0-test"
+fi
+SH
+chmod +x "$ready_home/.hermes/hermes-agent/venv/bin/hermes"
+run_ready_check && fail "--check accepts a release without the flags omarchy-agent passes"
+pass "a release listing only --oneshot is not prompt-ready"

From f7078b9136e5241b2080a41575c85502e2b7c7b0 Mon Sep 17 00:00:00 2001
From: Spencer Bull <spencer@omarchy.org>
Date: Tue, 1 Sep 2026 15:53:52 -0500
Subject: [PATCH 03/27] Match Hermes flag probe at a boundary, cover the mise
 path

Review follow-up on the readiness probe. The two greps were fixed-string
substring matches, so a future release listing only --tui-theme or
--query-log while dropping the bare --tui/--query omarchy-agent passes
would read as ready -- the same false verdict inverted. Anchor both to a
flag boundary.

Add a regression case pinning that a substring-only help is rejected,
and one exercising --check through a mise-installed hermes in both
capability directions: the desktop and foreign cases only covered their
own wrappers, and the mise path is what a machine without the app runs.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 bin/omarchy-install-hermes-cli  |  9 ++++--
 test/shell.d/hermes-cli-test.sh | 52 +++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+), 2 deletions(-)

diff --git a/bin/omarchy-install-hermes-cli b/bin/omarchy-install-hermes-cli
index 150364c0..bdd0daab 100755
--- a/bin/omarchy-install-hermes-cli
+++ b/bin/omarchy-install-hermes-cli
@@ -92,12 +92,17 @@ hermes_runs() {
 # session and --tui to keep it interactive -- rather than a flag that merely
 # shipped alongside them: the previous marker, --oneshot, was dropped in Hermes
 # v0.20 and left working installs stranded as "not ready".
+#
+# Matched at a flag boundary, not as a substring: a bare grep for --tui also
+# accepts a release that lists only --tui-theme while having dropped --tui
+# itself, which would call an install ready that omarchy-agent cannot drive --
+# the same false verdict this check exists to prevent, merely inverted.
 hermes_prompt_ready() {
   local help
   hermes_runs &&
     help=$(timeout 15 "$HOME/.local/bin/hermes" chat --help 2>/dev/null) &&
-    grep -qF -- '--tui' <<<"$help" &&
-    grep -qF -- '--query' <<<"$help"
+    grep -qE -- '--tui([^[:alnum:]-]|$)' <<<"$help" &&
+    grep -qE -- '--query([^[:alnum:]-]|$)' <<<"$help"
 }
 
 # --owns answers whether the wrapper on PATH is the one this command wrote, so
diff --git a/test/shell.d/hermes-cli-test.sh b/test/shell.d/hermes-cli-test.sh
index 2144a795..fa5c1db9 100755
--- a/test/shell.d/hermes-cli-test.sh
+++ b/test/shell.d/hermes-cli-test.sh
@@ -23,6 +23,11 @@ cat >"$mock_bin/omarchy-cmd-missing" <<'SH'
 SH
 
 # `mise where` must fail so the installer sees no Hermes behind the stub.
+#
+# With OMARCHY_TEST_MISE_X_HERMES=1, `mise x -- hermes ...` emulates the Hermes
+# the Omarchy stub runs, so the readiness probe can be exercised through a
+# mise-installed hermes and not only the foreign and desktop wrappers. Off by
+# default, so `mise x` stays silent for every test that does not opt in.
 cat >"$mock_bin/mise" <<'SH'
 #!/bin/bash
 printf '%s\0' "$@" >>"$OMARCHY_TEST_MISE_LOG"
@@ -30,6 +35,18 @@ if [[ $1 == "where" && ${OMARCHY_TEST_MISE_WHERE_OK:-0} == 1 ]]; then
   printf '%s\n' "$OMARCHY_TEST_MISE_ROOT"
   exit 0
 fi
+if [[ $1 == "x" && ${OMARCHY_TEST_MISE_X_HERMES:-0} == 1 ]]; then
+  # Args are `x <tool> -- hermes <hermes-args...>`; skip to what follows hermes.
+  shift
+  while (( $# )) && [[ $1 != "--" ]]; do shift; done
+  shift 2
+  if [[ ${1:-} == "chat" && ${2:-} == "--help" ]]; then
+    [[ ${OMARCHY_TEST_HERMES_CAPABLE:-1} == 1 ]] && echo "[-q QUERY, --query QUERY] [--tui]"
+  else
+    echo "hermes-agent 0.0.0-test"
+  fi
+  exit 0
+fi
 [[ $1 != "where" ]]
 SH
 
@@ -237,6 +254,26 @@ tr '\0' '\n' <"$mise_log" | grep -q '^rm$' || fail "an older owned Hermes enviro
 tr '\0' '\n' <"$mise_log" | grep -q '^uninstall$' || fail "an older owned Hermes environment is uninstalled"
 pass "reinstalling replaces an older owned Hermes environment"
 
+# The mise-installed path is what a machine without the desktop app runs, and
+# --check gates the default agent there too. The stub is present and its mise
+# environment resolves, so readiness turns on the hermes mise runs -- exercised
+# here in both directions, since the desktop and foreign cases cover only their
+# own wrappers.
+run_mise_check() {
+  OMARCHY_TEST_DESKTOP_INSTALLED=0 \
+    OMARCHY_TEST_MISE_WHERE_OK=1 \
+    OMARCHY_TEST_MISE_ROOT="$test_tmp/mise" \
+    OMARCHY_TEST_MISE_LOG="$mise_log" \
+    OMARCHY_TEST_MISE_X_HERMES=1 \
+    OMARCHY_TEST_HERMES_CAPABLE="$1" \
+    HOME="$test_home" \
+    PATH="$mock_bin:$PATH" \
+    bash "$ROOT/bin/omarchy-install-hermes-cli" --check >/dev/null 2>&1
+}
+run_mise_check 1 || fail "--check accepts a mise-installed hermes that runs the seeded session"
+run_mise_check 0 && fail "--check rejects a mise-installed hermes without the flags omarchy-agent passes"
+pass "--check follows the mise-installed hermes it would actually run"
+
 rm -f "$test_home/.local/bin/hermes"
 : >"$mise_log"
 OMARCHY_TEST_MISE_WHERE_OK=1 run_installer 0 &&
@@ -410,3 +447,18 @@ SH
 chmod +x "$ready_home/.hermes/hermes-agent/venv/bin/hermes"
 run_ready_check && fail "--check accepts a release without the flags omarchy-agent passes"
 pass "a release listing only --oneshot is not prompt-ready"
+
+# A release that lists --tui-theme and --query-log but has dropped the bare
+# --tui/--query omarchy-agent passes must not read as ready on the substring
+# alone. The probe matches at a flag boundary for exactly this case.
+cat >"$ready_home/.hermes/hermes-agent/venv/bin/hermes" <<'SH'
+#!/bin/bash
+if [[ ${1:-} == "chat" && ${2:-} == "--help" ]]; then
+  echo "[--tui-theme THEME] [--query-log FILE]"
+else
+  echo "hermes-agent 0.0.0-test"
+fi
+SH
+chmod +x "$ready_home/.hermes/hermes-agent/venv/bin/hermes"
+run_ready_check && fail "--check accepts a release whose flags only contain --tui/--query as a substring"
+pass "a flag that merely contains --tui or --query is not prompt-ready"

From 36d52254a7962e468ce75d637afc7bedeb090cb1 Mon Sep 17 00:00:00 2001
From: Spencer Bull <spencer@omarchy.org>
Date: Tue, 1 Sep 2026 22:51:03 -0500
Subject: [PATCH 04/27] Tear down the mise Hermes CLI on Remove Hermes

Remove Hermes dropped the desktop package and its ~/.hermes runtime but
never touched the mise CLI, on the assumption the install-time handoff
had already removed it. A CLI the app never superseded -- an interrupted
install, or the terminal CLI from before the app existed -- was left
stranded on PATH after uninstall.

Add a --remove mode to omarchy-install-hermes-cli that performs the same
teardown the desktop takeover already does (mise rm -g + mise uninstall,
and the marked stub), and call it from omarchy-remove-ai-hermes. The tool
spec and ownership marker stay defined in one place, so the takeover and
teardown paths cannot drift. Scoped to what Omarchy owns: a Hermes the
user installed themselves is left alone.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 bin/omarchy-install-hermes-cli     | 21 +++++++++++++++-
 bin/omarchy-remove-ai-hermes       |  7 ++++++
 test/shell.d/hermes-cli-test.sh    | 39 ++++++++++++++++++++++++++++++
 test/shell.d/hermes-remove-test.sh | 19 ++++++++++++++-
 4 files changed, 84 insertions(+), 2 deletions(-)

diff --git a/bin/omarchy-install-hermes-cli b/bin/omarchy-install-hermes-cli
index bdd0daab..7ae9410a 100755
--- a/bin/omarchy-install-hermes-cli
+++ b/bin/omarchy-install-hermes-cli
@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # omarchy:summary=Install the Hermes CLI as a mise-backed wrapper in ~/.local/bin
-# omarchy:args=[--check|--now|--owns]
+# 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
@@ -112,6 +112,25 @@ 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 installs and the stub it marks -- 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. Scoped to what is ours:
+# the tool spec is this installer's, and the stub goes only when it carries the
+# marker, so a Hermes the user installed themselves is untouched. Idempotent --
+# nothing installed means nothing to do -- and it is the same teardown the
+# desktop takeover above performs, kept in one place so the two cannot drift.
+if [[ $mode == "--remove" ]]; then
+  mise rm -g "$tool" >/dev/null 2>&1 || true
+  mise uninstall --all "$tool" >/dev/null 2>&1 || true
+
+  if ours; then
+    rm -f "$HOME/.local/bin/hermes"
+  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
diff --git a/bin/omarchy-remove-ai-hermes b/bin/omarchy-remove-ai-hermes
index f67b1d6d..f332dc4b 100755
--- a/bin/omarchy-remove-ai-hermes
+++ b/bin/omarchy-remove-ai-hermes
@@ -8,6 +8,13 @@ set -euo pipefail
 
 omarchy-pkg-drop hermes-desktop
 
+# 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.
+omarchy-install-hermes-cli --remove
+
 # 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
diff --git a/test/shell.d/hermes-cli-test.sh b/test/shell.d/hermes-cli-test.sh
index fa5c1db9..a70589ef 100755
--- a/test/shell.d/hermes-cli-test.sh
+++ b/test/shell.d/hermes-cli-test.sh
@@ -402,6 +402,45 @@ marker_copies=$(grep -rl "Written by omarchy-install-hermes-cli" \
   fail "only omarchy-install-hermes-cli spells out the ownership marker"
 pass "the ownership marker is written down once"
 
+# --remove tears down a Hermes CLI this installer owns, so Remove Hermes can
+# clear one the desktop app never superseded. It turns on the same ownership as
+# the rest of the file, so its cases mirror that split.
+remove_home="$test_tmp/remove-home"
+mkdir -p "$remove_home/.local/bin"
+
+run_remove() {
+  OMARCHY_TEST_DESKTOP_INSTALLED=0 \
+    OMARCHY_TEST_MISE_WHERE_OK="${OMARCHY_TEST_MISE_WHERE_OK:-0}" \
+    OMARCHY_TEST_MISE_ROOT="$test_tmp/mise" \
+    OMARCHY_TEST_MISE_LOG="$mise_log" \
+    HOME="$remove_home" \
+    PATH="$mock_bin:$PATH" \
+    bash "$ROOT/bin/omarchy-install-hermes-cli" --remove
+}
+
+rm -f "$remove_home/.local/bin/hermes"
+: >"$mise_log"
+run_remove || fail "--remove succeeds when there is nothing to remove"
+pass "--remove is idempotent when no Hermes CLI is present"
+
+printf '%s\n' "#!/bin/bash" "$stub_marker" >"$remove_home/.local/bin/hermes"
+chmod +x "$remove_home/.local/bin/hermes"
+: >"$mise_log"
+OMARCHY_TEST_MISE_WHERE_OK=1 run_remove || fail "--remove succeeds tearing down an owned CLI"
+tr '\0' '\n' <"$mise_log" | grep -q '^rm$' || fail "--remove drops the mise tool from config"
+tr '\0' '\n' <"$mise_log" | grep -q '^uninstall$' || fail "--remove uninstalls the mise tool"
+[[ ! -e $remove_home/.local/bin/hermes ]] || fail "--remove takes the stub it owns"
+pass "--remove tears down the mise CLI and the stub this installer owns"
+
+foreign_remove_body="#!/bin/bash
+exec /usr/local/bin/my-own-hermes \"\$@\""
+printf '%s\n' "$foreign_remove_body" >"$remove_home/.local/bin/hermes"
+chmod +x "$remove_home/.local/bin/hermes"
+run_remove || fail "--remove succeeds with a foreign hermes present"
+[[ -f $remove_home/.local/bin/hermes && $(cat "$remove_home/.local/bin/hermes") == "$foreign_remove_body" ]] ||
+  fail "--remove leaves a hermes it does not own untouched"
+pass "--remove leaves a Hermes the user installed themselves"
+
 # The app's marker says its install once landed, not that it is still there. A
 # wrapper whose runtime has since gone answers for nothing, so readiness runs
 # the command, exactly as it does for a hermes the user installed themselves.
diff --git a/test/shell.d/hermes-remove-test.sh b/test/shell.d/hermes-remove-test.sh
index bc80859f..c590f0d3 100755
--- a/test/shell.d/hermes-remove-test.sh
+++ b/test/shell.d/hermes-remove-test.sh
@@ -15,6 +15,14 @@ cat >"$mock_bin/omarchy-pkg-drop" <<'SH'
 #!/bin/bash
 printf '%s\0' "$@" >>"$OMARCHY_TEST_DROP_LOG"
 SH
+
+# The CLI teardown is the installer's own, exercised in hermes-cli-test.sh; here
+# it is mocked to a logger so this test stays about what Remove Hermes does with
+# ~/.hermes, and to keep real mise out of a run with HOME pointed at a fixture.
+cat >"$mock_bin/omarchy-install-hermes-cli" <<'SH'
+#!/bin/bash
+printf '%s\0' "$@" >>"$OMARCHY_TEST_INSTALLER_LOG"
+SH
 chmod +x "$mock_bin"/*
 
 seed_install() {
@@ -35,7 +43,10 @@ seed_install() {
 }
 
 remove() {
-  OMARCHY_TEST_DROP_LOG="$test_tmp/drop-log" HOME="$test_home" PATH="$mock_bin:$PATH" \
+  : >"$test_tmp/installer-log"
+  OMARCHY_TEST_DROP_LOG="$test_tmp/drop-log" \
+    OMARCHY_TEST_INSTALLER_LOG="$test_tmp/installer-log" \
+    HOME="$test_home" PATH="$mock_bin:$PATH" \
     bash "$ROOT/bin/omarchy-remove-ai-hermes" >/dev/null 2>&1
 }
 
@@ -67,6 +78,12 @@ pass "removal keeps what belongs to the user"
 [[ ! -e $test_home/.local/bin/hermes ]] || fail "the app's own hermes command is removed"
 pass "removal takes the command the app installed"
 
+# Removal also asks the installer to tear down a mise CLI the app superseded, so
+# a copy left from before the app took over does not linger once Hermes is gone.
+tr '\0' '\n' <"$test_tmp/installer-log" | grep -qx -- '--remove' ||
+  fail "removal asks the installer to tear down its own CLI"
+pass "removal tears down the mise CLI through the installer"
+
 # A hermes command the app did not write survives even when the app did install
 # a runtime of its own.
 seed_install

From c462aad9eec6b1cff29027cb88fe2ec628402734 Mon Sep 17 00:00:00 2001
From: Spencer Bull <spencer@omarchy.org>
Date: Tue, 1 Sep 2026 23:32:35 -0500
Subject: [PATCH 05/27] Prove ownership before --remove touches mise

The teardown removed the Omarchy tool spec from mise unconditionally,
so removing Hermes Desktop could destroy a mise environment the user
had built against the same spec while sparing their wrapper -- the very
command the removal claims to preserve, broken behind its back. The
whole teardown now turns on the marked stub, as replacement already
does; the desktop takeover keeps its own bargain, where a second Hermes
goes whoever built it and the app still provides the command after.

Also close the probe over underscores -- _ continues a flag name just
as - does, so --tui_mode no longer answers for --tui -- and pin the
gaps review found in the tests: each flag must match on its own (either
grep could be deleted before without a failure), a foreign wrapper's
mise environment must survive --remove, and Remove Hermes must tear
down the CLI in the interrupted-install case, not only after the app's
runtime landed.

Findings from an independent codex review at xhigh, each verified
against the source and proven by mutation before landing.

Co-Authored-By: Codex <noreply@openai.com>
Co-Authored-By: Claude <noreply@anthropic.com>
---
 bin/omarchy-install-hermes-cli     | 24 +++++++++--------
 test/shell.d/hermes-cli-test.sh    | 42 +++++++++++++++++++++++++++++-
 test/shell.d/hermes-remove-test.sh |  4 +++
 3 files changed, 58 insertions(+), 12 deletions(-)

diff --git a/bin/omarchy-install-hermes-cli b/bin/omarchy-install-hermes-cli
index 7ae9410a..4a6923a3 100755
--- a/bin/omarchy-install-hermes-cli
+++ b/bin/omarchy-install-hermes-cli
@@ -101,8 +101,8 @@ hermes_prompt_ready() {
   local help
   hermes_runs &&
     help=$(timeout 15 "$HOME/.local/bin/hermes" chat --help 2>/dev/null) &&
-    grep -qE -- '--tui([^[:alnum:]-]|$)' <<<"$help" &&
-    grep -qE -- '--query([^[:alnum:]-]|$)' <<<"$help"
+    grep -qE -- '--tui([^[:alnum:]_-]|$)' <<<"$help" &&
+    grep -qE -- '--query([^[:alnum:]_-]|$)' <<<"$help"
 }
 
 # --owns answers whether the wrapper on PATH is the one this command wrote, so
@@ -113,18 +113,20 @@ if [[ $mode == "--owns" ]]; then
 fi
 
 # --remove tears down a Hermes CLI this installer put in place -- the mise tool
-# it installs and the stub it marks -- so Remove Hermes clears a CLI the app
+# 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. Scoped to what is ours:
-# the tool spec is this installer's, and the stub goes only when it carries the
-# marker, so a Hermes the user installed themselves is untouched. Idempotent --
-# nothing installed means nothing to do -- and it is the same teardown the
-# desktop takeover above performs, kept in one place so the two cannot drift.
+# 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
-  mise rm -g "$tool" >/dev/null 2>&1 || true
-  mise uninstall --all "$tool" >/dev/null 2>&1 || true
-
   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"
   fi
 
diff --git a/test/shell.d/hermes-cli-test.sh b/test/shell.d/hermes-cli-test.sh
index a70589ef..69a52f61 100755
--- a/test/shell.d/hermes-cli-test.sh
+++ b/test/shell.d/hermes-cli-test.sh
@@ -421,6 +421,10 @@ run_remove() {
 rm -f "$remove_home/.local/bin/hermes"
 : >"$mise_log"
 run_remove || fail "--remove succeeds when there is nothing to remove"
+# No stub means no proof the mise environment -- if one even exists -- is
+# Omarchy's, so nothing may reach mise at all.
+tr '\0' '\n' <"$mise_log" | grep -Eq '^(rm|uninstall)$' &&
+  fail "--remove leaves mise alone when nothing proves ownership"
 pass "--remove is idempotent when no Hermes CLI is present"
 
 printf '%s\n' "#!/bin/bash" "$stub_marker" >"$remove_home/.local/bin/hermes"
@@ -436,9 +440,14 @@ foreign_remove_body="#!/bin/bash
 exec /usr/local/bin/my-own-hermes \"\$@\""
 printf '%s\n' "$foreign_remove_body" >"$remove_home/.local/bin/hermes"
 chmod +x "$remove_home/.local/bin/hermes"
-run_remove || fail "--remove succeeds with a foreign hermes present"
+: >"$mise_log"
+OMARCHY_TEST_MISE_WHERE_OK=1 run_remove || fail "--remove succeeds with a foreign hermes present"
 [[ -f $remove_home/.local/bin/hermes && $(cat "$remove_home/.local/bin/hermes") == "$foreign_remove_body" ]] ||
   fail "--remove leaves a hermes it does not own untouched"
+# The wrapper may front a mise environment the user built against the very same
+# spec; without the marker there is no telling, so the environment stays too.
+tr '\0' '\n' <"$mise_log" | grep -Eq '^(rm|uninstall)$' &&
+  fail "--remove never removes a mise environment it cannot prove is Omarchy's"
 pass "--remove leaves a Hermes the user installed themselves"
 
 # The app's marker says its install once landed, not that it is still there. A
@@ -501,3 +510,34 @@ SH
 chmod +x "$ready_home/.hermes/hermes-agent/venv/bin/hermes"
 run_ready_check && fail "--check accepts a release whose flags only contain --tui/--query as a substring"
 pass "a flag that merely contains --tui or --query is not prompt-ready"
+
+# Each flag answers for itself: a release that kept --tui but dropped --query,
+# or the reverse, cannot run the seeded session either, so neither grep may
+# ride on the other's match.
+for kept in '--tui' '-q QUERY, --query QUERY'; do
+  cat >"$ready_home/.hermes/hermes-agent/venv/bin/hermes" <<SH
+#!/bin/bash
+if [[ \${1:-} == "chat" && \${2:-} == "--help" ]]; then
+  echo "[$kept]"
+else
+  echo "hermes-agent 0.0.0-test"
+fi
+SH
+  chmod +x "$ready_home/.hermes/hermes-agent/venv/bin/hermes"
+  run_ready_check && fail "--check accepts a release listing only $kept"
+done
+pass "either flag alone is not prompt-ready"
+
+# An underscore continues a flag name just as a dash does: --tui_mode is not
+# --tui.
+cat >"$ready_home/.hermes/hermes-agent/venv/bin/hermes" <<'SH'
+#!/bin/bash
+if [[ ${1:-} == "chat" && ${2:-} == "--help" ]]; then
+  echo "[--tui_mode MODE] [--query_log FILE]"
+else
+  echo "hermes-agent 0.0.0-test"
+fi
+SH
+chmod +x "$ready_home/.hermes/hermes-agent/venv/bin/hermes"
+run_ready_check && fail "--check accepts flags that extend --tui/--query with an underscore"
+pass "an underscore continuation is not the bare flag"
diff --git a/test/shell.d/hermes-remove-test.sh b/test/shell.d/hermes-remove-test.sh
index c590f0d3..6045c9a1 100755
--- a/test/shell.d/hermes-remove-test.sh
+++ b/test/shell.d/hermes-remove-test.sh
@@ -104,6 +104,10 @@ printf 'my local edit\n' >"$test_home/.hermes/hermes-agent/PATCH"
 printf '%s\n' "#!/bin/bash" "exec $test_home/.hermes/hermes-agent/venv/bin/hermes \"\$@\"" \
   >"$test_home/.local/bin/hermes"
 remove || fail "remove succeeds when the app never finished installing Hermes"
+# The stranded pre-desktop CLI is exactly the interrupted-install case, so the
+# teardown must be asked for here too, not only when the app's runtime landed.
+tr '\0' '\n' <"$test_tmp/installer-log" | grep -qx -- '--remove' ||
+  fail "removal tears down the CLI even when the app never finished installing"
 [[ -d $test_home/.hermes/hermes-agent ]] ||
   fail "a Hermes runtime the app never installed survives removal"
 [[ -f $test_home/.hermes/hermes-agent/PATCH ]] ||

From 46cfc4ada5d9efe849d0f789178e492d98801011 Mon Sep 17 00:00:00 2001
From: Spencer Bull <spencer@omarchy.org>
Date: Wed, 2 Sep 2026 01:01:13 -0500
Subject: [PATCH 06/27] Judge the CLI teardown by what is left, and match flags
 as definitions

Two review follow-ups. The probe counted any mention of --tui/--query in
the help as support -- Hermes already writes "With --tui:" into --dev's
description, so a release that dropped the option while keeping the
prose would still read as ready. A flag now counts only when followed by
a shape argparse prints after a definition: the usage bracket, the gap
before same-line help text, an uppercase metavar, or the line end. Not
probed by parsing a real invocation on purpose -- a release that ignores
unknown arguments would turn the probe into a live session.

And the teardown trusted its commands: a stub rm that failed aborted
Remove Hermes under set -e before any ~/.hermes handling, while mise
failures vanished into || true. --remove now attempts every step, then
judges by what is left -- the marked stub still present, or mise still
resolving the tool -- and Remove Hermes tolerates the failure until the
runtime is handled, then carries it in its exit code.

Findings from the same codex review at xhigh, verified and proven by
mutation before landing.

Co-Authored-By: Codex <noreply@openai.com>
Co-Authored-By: Claude <noreply@anthropic.com>
---
 bin/omarchy-install-hermes-cli     | 32 ++++++++++++++++++++-------
 bin/omarchy-remove-ai-hermes       | 11 +++++++++-
 test/shell.d/hermes-cli-test.sh    | 35 +++++++++++++++++++++++++++++-
 test/shell.d/hermes-remove-test.sh | 13 +++++++++++
 4 files changed, 81 insertions(+), 10 deletions(-)

diff --git a/bin/omarchy-install-hermes-cli b/bin/omarchy-install-hermes-cli
index 4a6923a3..35405269 100755
--- a/bin/omarchy-install-hermes-cli
+++ b/bin/omarchy-install-hermes-cli
@@ -88,21 +88,27 @@ hermes_runs() {
     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 flag that merely
 # shipped alongside them: the previous marker, --oneshot, was dropped in Hermes
 # v0.20 and left working installs stranded as "not ready".
-#
-# Matched at a flag boundary, not as a substring: a bare grep for --tui also
-# accepts a release that lists only --tui-theme while having dropped --tui
-# itself, which would call an install ready that omarchy-agent cannot drive --
-# the same false verdict this check exists to prevent, merely inverted.
 hermes_prompt_ready() {
   local help
   hermes_runs &&
     help=$(timeout 15 "$HOME/.local/bin/hermes" chat --help 2>/dev/null) &&
-    grep -qE -- '--tui([^[:alnum:]_-]|$)' <<<"$help" &&
-    grep -qE -- '--query([^[:alnum:]_-]|$)' <<<"$help"
+    help_defines_flag '--tui' "$help" &&
+    help_defines_flag '--query' "$help"
 }
 
 # --owns answers whether the wrapper on PATH is the one this command wrote, so
@@ -127,7 +133,17 @@ 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"
+    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.
+    if ours || mise where "$tool" >/dev/null 2>&1; then
+      echo "Could not remove the Hermes CLI Omarchy installed." >&2
+      echo "Remove ~/.local/bin/hermes and the mise tool '$tool', then run omarchy-install-hermes-cli --remove again." >&2
+      exit 1
+    fi
   fi
 
   exit 0
diff --git a/bin/omarchy-remove-ai-hermes b/bin/omarchy-remove-ai-hermes
index f332dc4b..1145fbd1 100755
--- a/bin/omarchy-remove-ai-hermes
+++ b/bin/omarchy-remove-ai-hermes
@@ -13,7 +13,10 @@ omarchy-pkg-drop hermes-desktop
 # 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.
-omarchy-install-hermes-cli --remove
+# 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
+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
@@ -64,3 +67,9 @@ else
   echo "Hermes Desktop has been removed."
   echo "It never finished installing its own Hermes, so nothing in ~/.hermes was touched."
 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
diff --git a/test/shell.d/hermes-cli-test.sh b/test/shell.d/hermes-cli-test.sh
index 69a52f61..24f8e8bc 100755
--- a/test/shell.d/hermes-cli-test.sh
+++ b/test/shell.d/hermes-cli-test.sh
@@ -430,12 +430,19 @@ pass "--remove is idempotent when no Hermes CLI is present"
 printf '%s\n' "#!/bin/bash" "$stub_marker" >"$remove_home/.local/bin/hermes"
 chmod +x "$remove_home/.local/bin/hermes"
 : >"$mise_log"
-OMARCHY_TEST_MISE_WHERE_OK=1 run_remove || fail "--remove succeeds tearing down an owned CLI"
+run_remove || fail "--remove succeeds tearing down an owned CLI"
 tr '\0' '\n' <"$mise_log" | grep -q '^rm$' || fail "--remove drops the mise tool from config"
 tr '\0' '\n' <"$mise_log" | grep -q '^uninstall$' || fail "--remove uninstalls the mise tool"
 [[ ! -e $remove_home/.local/bin/hermes ]] || fail "--remove takes the stub it owns"
 pass "--remove tears down the mise CLI and the stub this installer owns"
 
+# When mise still resolves the tool after the teardown, the environment
+# survived whatever uninstall claimed, and --remove has to say so.
+printf '%s\n' "#!/bin/bash" "$stub_marker" >"$remove_home/.local/bin/hermes"
+chmod +x "$remove_home/.local/bin/hermes"
+OMARCHY_TEST_MISE_WHERE_OK=1 run_remove && fail "--remove claims success while mise still resolves the tool"
+pass "--remove fails when the mise environment survives the teardown"
+
 foreign_remove_body="#!/bin/bash
 exec /usr/local/bin/my-own-hermes \"\$@\""
 printf '%s\n' "$foreign_remove_body" >"$remove_home/.local/bin/hermes"
@@ -450,6 +457,16 @@ tr '\0' '\n' <"$mise_log" | grep -Eq '^(rm|uninstall)$' &&
   fail "--remove never removes a mise environment it cannot prove is Omarchy's"
 pass "--remove leaves a Hermes the user installed themselves"
 
+# Judged by what is left, not by what rm claimed: a stub that survives the
+# teardown is a CLI still installed, and --remove has to say so.
+printf '%s\n' "#!/bin/bash" "$stub_marker" >"$remove_home/.local/bin/hermes"
+chmod +x "$remove_home/.local/bin/hermes"
+chmod 555 "$remove_home/.local/bin"
+run_remove && fail "--remove claims success while the stub survives"
+chmod 755 "$remove_home/.local/bin"
+rm -f "$remove_home/.local/bin/hermes"
+pass "--remove fails when the stub cannot be removed"
+
 # The app's marker says its install once landed, not that it is still there. A
 # wrapper whose runtime has since gone answers for nothing, so readiness runs
 # the command, exactly as it does for a hermes the user installed themselves.
@@ -541,3 +558,19 @@ SH
 chmod +x "$ready_home/.hermes/hermes-agent/venv/bin/hermes"
 run_ready_check && fail "--check accepts flags that extend --tui/--query with an underscore"
 pass "an underscore continuation is not the bare flag"
+
+# A flag mentioned in another option's help text is not that option. Hermes
+# already writes "With --tui:" into --dev's description, so prose has to stay
+# prose even when both names appear in it.
+cat >"$ready_home/.hermes/hermes-agent/venv/bin/hermes" <<'SH'
+#!/bin/bash
+if [[ ${1:-} == "chat" && ${2:-} == "--help" ]]; then
+  echo "  --dev                 With --tui: run sources via tsx"
+  echo "  --log FILE            Where --query output lands"
+else
+  echo "hermes-agent 0.0.0-test"
+fi
+SH
+chmod +x "$ready_home/.hermes/hermes-agent/venv/bin/hermes"
+run_ready_check && fail "--check accepts flags that appear only in option descriptions"
+pass "a flag mentioned in prose is not a defined option"
diff --git a/test/shell.d/hermes-remove-test.sh b/test/shell.d/hermes-remove-test.sh
index 6045c9a1..d3389087 100755
--- a/test/shell.d/hermes-remove-test.sh
+++ b/test/shell.d/hermes-remove-test.sh
@@ -22,6 +22,7 @@ SH
 cat >"$mock_bin/omarchy-install-hermes-cli" <<'SH'
 #!/bin/bash
 printf '%s\0' "$@" >>"$OMARCHY_TEST_INSTALLER_LOG"
+exit "${OMARCHY_TEST_INSTALLER_STATUS:-0}"
 SH
 chmod +x "$mock_bin"/*
 
@@ -46,6 +47,7 @@ remove() {
   : >"$test_tmp/installer-log"
   OMARCHY_TEST_DROP_LOG="$test_tmp/drop-log" \
     OMARCHY_TEST_INSTALLER_LOG="$test_tmp/installer-log" \
+    OMARCHY_TEST_INSTALLER_STATUS="${OMARCHY_TEST_INSTALLER_STATUS:-0}" \
     HOME="$test_home" PATH="$mock_bin:$PATH" \
     bash "$ROOT/bin/omarchy-remove-ai-hermes" >/dev/null 2>&1
 }
@@ -131,3 +133,14 @@ remove || fail "remove succeeds with a wrapper pointing at a sibling directory"
 [[ -f $test_home/.local/bin/hermes && $(cat "$test_home/.local/bin/hermes") == "$sibling_body" ]] ||
   fail "a wrapper pointing at ~/xhermes is not mistaken for one pointing into ~/.hermes"
 pass "removal matches the runtime path as a plain string"
+
+# A CLI teardown that fails must not stop the runtime handling, and must not be
+# papered over either: the data work still happens, and the failure reaches the
+# caller's exit code.
+seed_install
+printf '%s\n' "#!/bin/bash" "exec $test_home/.hermes/hermes-agent/venv/bin/hermes \"\$@\"" \
+  >"$test_home/.local/bin/hermes"
+OMARCHY_TEST_INSTALLER_STATUS=1 remove && fail "a failed CLI teardown surfaces in the exit code"
+[[ ! -d $test_home/.hermes/hermes-agent ]] ||
+  fail "a failed CLI teardown does not stop the runtime removal"
+pass "a failed CLI teardown is reported after the runtime is handled"

From d3d23fdddef846ebb98b52122a6ece66211c0daf Mon Sep 17 00:00:00 2001
From: Brian Armstrong <barmstrong@gmail.com>
Date: Wed, 2 Sep 2026 03:33:44 -0700
Subject: [PATCH 07/27] Honor keepLoaded for services during plugin hot-reload
 (#9485)

* Honor keepLoaded for services during plugin hot-reload

Plugin reload destroyed every service, including omarchy.lock, which drops the ext-session-lock client while Hyprland still holds the lock and surfaces the crashed-lockscreen fallback.

* Prove keepLoaded service survival with a fixture service

A fresh lock service also reports an empty lastEventAt, so comparing it
across the rescan passed whether or not the instance survived. A fixture
keepLoaded service whose in-memory marker is set before the rescan and
read back after can only pass when the same instance is still mounted.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Drop kept services whose plugin no longer declares a service

The _syncServices cleanup only asked whether the plugin was still
installed and enabled, so a kept service whose plugin dropped its
service kind or entry point kept running as a zombie until shell
restart. Apply the same eligibility checks used at creation, and hand
kept instances the refreshed manifest after a rescan.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Cover omarchy.media in keepLoaded expectations; note kept services reload on restart

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: David Heinemeier Hansson <david@hey.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 docs/omarchy-shell.md              |  4 +-
 shell/README.md                    |  8 +++-
 shell/plugins/README.md            |  3 ++
 shell/shell.qml                    | 31 +++++++++++--
 test/shell.d/plugins-test.sh       | 13 ++++++
 test/shell.d/runtime-smoke-test.sh | 72 ++++++++++++++++++++++++++++++
 6 files changed, 122 insertions(+), 9 deletions(-)

diff --git a/docs/omarchy-shell.md b/docs/omarchy-shell.md
index a7c1b389..3142d991 100644
--- a/docs/omarchy-shell.md
+++ b/docs/omarchy-shell.md
@@ -37,9 +37,7 @@ wait).
 
 Only one full bar option is active at a time. The built-in `omarchy.bar` is
 used when `bar.id` is omitted or when a selected third-party bar cannot load.
-Panels, overlays, and menus are loaded when summoned. Plugins can set the
-top-level manifest key `keepLoaded: true` to survive between summons.
-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
diff --git a/shell/README.md b/shell/README.md
index e72d02ce..16162b79 100644
--- a/shell/README.md
+++ b/shell/README.md
@@ -86,8 +86,12 @@ 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.
 
 The full schema lives in `services/PluginRegistry.qml`.
 
diff --git a/shell/plugins/README.md b/shell/plugins/README.md
index d4252515..66cb74e1 100644
--- a/shell/plugins/README.md
+++ b/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
 
diff --git a/shell/shell.qml b/shell/shell.qml
index 71a9834f..7e1cf75d 100644
--- a/shell/shell.qml
+++ b/shell/shell.qml
@@ -329,14 +329,23 @@ ShellRoot {
       if (!Array.isArray(m.kinds) || m.kinds.indexOf("service") === -1) continue
       if (!m.entryPoints || !m.entryPoints.service) continue
       if (!pluginRegistry.isEnabled(id)) continue
-      if (_services[id]) continue
+      if (_services[id]) {
+        // A kept instance outlives the rescan; hand it the fresh manifest.
+        var kept = _services[id]
+        if (kept && "manifest" in kept) kept.manifest = m
+        continue
+      }
       ensureService(id)
     }
-    // Drop services for plugins that have been disabled or removed.
+    // Drop services for plugins that have been disabled or removed, or that
+    // no longer declare a service entry point.
     for (var existingId in _services) {
       var stillThere = plugins[existingId]
+      var stillService = stillThere && Array.isArray(stillThere.kinds)
+        && stillThere.kinds.indexOf("service") !== -1
+        && stillThere.entryPoints && stillThere.entryPoints.service
       var stillEnabled = stillThere && pluginRegistry.isEnabled(existingId)
-      if (stillThere && stillEnabled) continue
+      if (stillService && stillEnabled) continue
       var inst = _services[existingId]
       if (inst && typeof inst.destroy === "function") inst.destroy()
       var next = ({})
@@ -345,12 +354,26 @@ ShellRoot {
     }
   }
 
+  function serviceKeepLoaded(pluginId) {
+    var plugins = pluginRegistry && pluginRegistry.installedPlugins
+    var manifest = plugins ? plugins[pluginId] : null
+    return !!(manifest && manifest.keepLoaded === true)
+  }
+
+  // keepLoaded services (lock, idle, polkit) must survive plugin hot-reload.
+  // Destroying omarchy.lock drops the ext-session-lock client while Hyprland
+  // still holds the lock, which surfaces the crashed-lockscreen fallback.
   function unloadPluginServices() {
+    var next = ({})
     for (var existingId in _services) {
+      if (serviceKeepLoaded(existingId)) {
+        next[existingId] = _services[existingId]
+        continue
+      }
       var inst = _services[existingId]
       if (inst && typeof inst.destroy === "function") inst.destroy()
     }
-    _services = ({})
+    _services = next
   }
 
   Connections {
diff --git a/test/shell.d/plugins-test.sh b/test/shell.d/plugins-test.sh
index 141b4323..5d634dc9 100644
--- a/test/shell.d/plugins-test.sh
+++ b/test/shell.d/plugins-test.sh
@@ -197,5 +197,18 @@ for (const [id, section] of Object.entries({
 }
 check(byId['omarchy.media']?.barWidget?.defaultSection === undefined, 'omarchy.media must use the center fallback')
 
+for (const id of ['omarchy.lock', 'omarchy.idle', 'omarchy.polkit', 'omarchy.notifications', 'omarchy.media']) {
+  check(byId[id]?.keepLoaded === true, `${id} must stay loaded across plugin reloads`)
+}
+
+const shellSource = fs.readFileSync(path.join(root, 'shell/shell.qml'), 'utf8')
+const unloadMatch = shellSource.match(/function unloadPluginServices\(\) \{[\s\S]*?\n  \}/)
+check(!!unloadMatch, 'unloadPluginServices is defined')
+check(!!unloadMatch && /serviceKeepLoaded/.test(unloadMatch[0]), 'unloadPluginServices honors keepLoaded')
+check(
+  /function _syncServices\(\) \{[\s\S]*Drop services for plugins that have been disabled/.test(shellSource),
+  '_syncServices still drops disabled or removed services'
+)
+
 assert(errors.length === 0, 'plugin manifests match shell registry contract', errors.join('\n'))
 JS
diff --git a/test/shell.d/runtime-smoke-test.sh b/test/shell.d/runtime-smoke-test.sh
index f9e52bfd..1b0e5fe9 100755
--- a/test/shell.d/runtime-smoke-test.sh
+++ b/test/shell.d/runtime-smoke-test.sh
@@ -74,6 +74,44 @@ Item {
 }
 QML
 
+# A keepLoaded service must keep its instance (and in-memory state) across a
+# plugin rescan. The marker below can only survive if the object does.
+keep_service_id="acme.keep-service"
+keep_service_dir="$test_home/.config/omarchy/plugins/$keep_service_id"
+mkdir -p "$keep_service_dir"
+cat >"$keep_service_dir/manifest.json" <<JSON
+{
+  "schemaVersion": 1,
+  "id": "$keep_service_id",
+  "name": "Keep Service",
+  "version": "1.0.0",
+  "kinds": ["service"],
+  "keepLoaded": true,
+  "entryPoints": {"service": "Service.qml"}
+}
+JSON
+cat >"$keep_service_dir/Service.qml" <<'QML'
+import QtQuick
+import Quickshell.Io
+
+Item {
+  property string marker: ""
+
+  IpcHandler {
+    target: "acme-keep"
+
+    function set(value: string): string {
+      marker = value
+      return "ok"
+    }
+
+    function get(): string {
+      return marker
+    }
+  }
+}
+QML
+
 cat >"$stub_bin/omarchy-update-available" <<'SH'
 #!/bin/bash
 echo "Omarchy update available (test)"
@@ -188,6 +226,15 @@ pass "shell IPC summon and hide contract works"
 jq -e '.hasPlayer | type == "boolean"' <<<"$(shell_ipc media status)" >/dev/null || fail_with_log "media IPC returns status JSON"
 jq -e '.enabled | type == "boolean"' <<<"$(shell_ipc idle status)" >/dev/null || fail_with_log "idle IPC returns status JSON"
 jq -e '.locked | type == "boolean"' <<<"$(shell_ipc lock status)" >/dev/null || fail_with_log "lock IPC returns status JSON"
+[[ $(shell_ipc shell setPluginEnabled "$keep_service_id" true) == "ok" ]] ||
+  fail_with_log "keepLoaded fixture service could not be enabled"
+keep_marker_set=""
+for _ in {1..80}; do
+  keep_marker_set=$(shell_ipc acme-keep set "survived" 2>/dev/null || true)
+  [[ $keep_marker_set == "ok" ]] && break
+  sleep 0.1
+done
+[[ $keep_marker_set == "ok" ]] || fail_with_log "keepLoaded fixture service IPC responds"
 [[ $(shell_ipc image-selector ping) == "ok" ]] || fail_with_log "image selector IPC responds"
 [[ $(shell_ipc osd ping) == "ok" ]] || fail_with_log "OSD IPC responds"
 [[ $(shell_ipc osd show '{"message":"Runtime smoke","duration":0}') == "ok" ]] || fail_with_log "OSD IPC opens"
@@ -215,6 +262,31 @@ shell_ipc_quiet image-selector cancel "$selector_done_file" >/dev/null
 rm -f "$selector_selection_file" "$selector_done_file"
 pass "image selector IPC survives plugin rescan"
 
+lock_status_after=$(shell_ipc lock status)
+jq -e '.locked | type == "boolean"' <<<"$lock_status_after" >/dev/null || fail_with_log "lock IPC survives plugin rescan"
+lock_event_after=$(jq -r '.lastEvent // empty' <<<"$lock_status_after")
+[[ $lock_event_after != lock-stranded* ]] ||
+  fail_with_log "plugin rescan does not strand the session lock ($lock_event_after)"
+# A recreated instance would answer with a fresh, empty marker.
+[[ $(shell_ipc acme-keep get) == "survived" ]] ||
+  fail_with_log "plugin rescan keeps the keepLoaded service instance mounted"
+pass "keepLoaded service instance survives plugin rescan"
+
+# Dropping the service entry point from the manifest must drop the kept
+# instance instead of leaving a zombie behind.
+jq 'del(.keepLoaded) | .kinds = ["overlay"] | .entryPoints = {"overlay": "Service.qml"}' \
+  "$keep_service_dir/manifest.json" >"$keep_service_dir/manifest.json.tmp"
+mv "$keep_service_dir/manifest.json.tmp" "$keep_service_dir/manifest.json"
+keep_gone=""
+for _ in {1..80}; do
+  keep_gone=$(shell_ipc acme-keep get 2>/dev/null || true)
+  [[ $keep_gone != "survived" ]] && break
+  sleep 0.1
+done
+[[ $keep_gone != "survived" ]] ||
+  fail_with_log "kept service is dropped when its plugin stops declaring a service"
+pass "kept service is dropped when its plugin stops declaring a service"
+
 shell_ipc_quiet omarchy.system-update refresh >/dev/null 2>&1 || true
 sleep 0.8
 

From 21470fd1eacd8c41d26ab018923a732ae0e61528 Mon Sep 17 00:00:00 2001
From: Spencer Bull <spencer@omarchy.org>
Date: Wed, 2 Sep 2026 09:40:44 -0500
Subject: [PATCH 08/27] Say how to finish a failed teardown, and record the
 probe's real history

A failed --remove told the user to run it again, but that advice could
never work: rm -f has usually taken the marked stub by the time the
failure is judged, and a rerun that finds nothing it owns succeeds
without touching the mise environment it was asked to finish removing.
Spell out the three commands that complete the job by hand instead.

Also correct the story the probe comment told: chat never lost
--oneshot in v0.20 -- no released Hermes defined it there. It lived at
the top level until v0.21 added chat's own, so the old probe was keyed
to a flag no release ever carried under chat, and every install read
as not ready. Recorded straight so a future hermes-desktop bump to
v0.21+, which would make the old probe pass on the desktop path alone,
cannot read as the fix.

Findings from omarchybot's review (Opus 5, with Codex at xhigh).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
---
 bin/omarchy-install-hermes-cli  | 16 +++++++++++-----
 test/shell.d/hermes-cli-test.sh |  4 ++--
 2 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/bin/omarchy-install-hermes-cli b/bin/omarchy-install-hermes-cli
index 35405269..4f4b99d7 100755
--- a/bin/omarchy-install-hermes-cli
+++ b/bin/omarchy-install-hermes-cli
@@ -100,9 +100,10 @@ help_defines_flag() {
 }
 
 # Probed for the flags omarchy-agent actually passes -- --query to seed the
-# session and --tui to keep it interactive -- rather than a flag that merely
-# shipped alongside them: the previous marker, --oneshot, was dropped in Hermes
-# v0.20 and left working installs stranded as "not ready".
+# 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 &&
@@ -139,9 +140,14 @@ if [[ $mode == "--remove" ]]; then
     # 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." >&2
-      echo "Remove ~/.local/bin/hermes and the mise tool '$tool', then run omarchy-install-hermes-cli --remove again." >&2
+      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
diff --git a/test/shell.d/hermes-cli-test.sh b/test/shell.d/hermes-cli-test.sh
index 24f8e8bc..1cf033ab 100755
--- a/test/shell.d/hermes-cli-test.sh
+++ b/test/shell.d/hermes-cli-test.sh
@@ -499,8 +499,8 @@ chmod +x "$ready_home/.hermes/hermes-agent/venv/bin/hermes"
 run_ready_check || fail "--check accepts the app's wrapper once it runs"
 pass "readiness runs the app's command rather than trusting its marker"
 
-# A release whose help lists only the retired --oneshot marker cannot run the
-# seeded --tui --query session omarchy-agent starts, so it is not ready.
+# A release whose help lists only the old probe's --oneshot marker cannot run
+# the seeded --tui --query session omarchy-agent starts, so it is not ready.
 cat >"$ready_home/.hermes/hermes-agent/venv/bin/hermes" <<'SH'
 #!/bin/bash
 if [[ ${1:-} == "chat" && ${2:-} == "--help" ]]; then

From 493067741e081c3b09082da6bfd51e99ec24ef00 Mon Sep 17 00:00:00 2001
From: David Heinemeier Hansson <david@hey.com>
Date: Fri, 4 Sep 2026 17:59:32 +0200
Subject: [PATCH 09/27] Give foot its own touchpad scroll factor (#9793)

foot only applies scrollback.multiplier to discrete wheel clicks, so
precise touchpad scrolling ignores it and crawls at the group's 1.5
factor. Split foot out at 2.0 to match how the other terminals feel.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 config/hypr/input.lua  | 3 ++-
 default/hypr/input.lua | 4 +++-
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/config/hypr/input.lua b/config/hypr/input.lua
index d20be92a..d06e05c7 100644
--- a/config/hypr/input.lua
+++ 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.
diff --git a/default/hypr/input.lua b/default/hypr/input.lua
index bdcd384f..a87ad994 100644
--- a/default/hypr/input.lua
+++ b/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 })

From 70047956fac8bdfe36aabb9dea82b4eee50e1b2c Mon Sep 17 00:00:00 2001
From: Mehmet Ince <mehmet@mehmetince.net>
Date: Fri, 4 Sep 2026 19:19:18 +0100
Subject: [PATCH 10/27] Harden lock authentication command lookup

Keep the target user's local bin on user-scoped upgrade paths while giving privileged lock and firewall helpers only root-owned search directories. Pin the lock helper's root PATH and fprintd-list executable, with regression coverage for each defense independently.

Reported-by: Rooke Poole <rookpool97@gmail.com>
---
 bin/omarchy-apply-lock                  |   9 +-
 bin/omarchy-upgrade-to-quattro          |   9 +-
 test/shell.d/apply-lock-test.sh         | 206 ++++++++++++++++++++++++
 test/shell.d/upgrade-to-quattro-test.sh |  46 +++++-
 4 files changed, 262 insertions(+), 8 deletions(-)
 create mode 100644 test/shell.d/apply-lock-test.sh

diff --git a/bin/omarchy-apply-lock b/bin/omarchy-apply-lock
index 9b97c0db..5bb261cb 100755
--- a/bin/omarchy-apply-lock
+++ b/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
diff --git a/bin/omarchy-upgrade-to-quattro b/bin/omarchy-upgrade-to-quattro
index 2e9bd759..a4caa7fe 100755
--- a/bin/omarchy-upgrade-to-quattro
+++ b/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."
 }
diff --git a/test/shell.d/apply-lock-test.sh b/test/shell.d/apply-lock-test.sh
new file mode 100644
index 00000000..5e7170cf
--- /dev/null
+++ b/test/shell.d/apply-lock-test.sh
@@ -0,0 +1,206 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+apply_lock="$ROOT/bin/omarchy-apply-lock"
+
+root_path_guard=$(awk '
+  /^if \(\( EUID == 0 \)\); then$/ { inside = 1 }
+  inside { print }
+  inside && /^fi$/ { exit }
+' "$apply_lock")
+grep -Fx '  export PATH=/usr/share/omarchy/bin:/usr/local/bin:/usr/bin:/bin' <<<"$root_path_guard" >/dev/null ||
+  fail "the root lock helper replaces its inherited command path"
+if grep -E '(\.local/bin|target_user|target_home)' <<<"$root_path_guard" >/dev/null; then
+  fail "the root lock helper does not retain a user-controlled command directory"
+fi
+pass "the root lock helper uses only trusted command directories"
+
+grep -F '[[ -x /usr/bin/fprintd-list ]]' "$apply_lock" >/dev/null ||
+  fail "the lock helper checks the trusted fprintd-list executable"
+grep -F '/usr/bin/fprintd-list "$target_user"' "$apply_lock" >/dev/null ||
+  fail "the lock helper invokes fprintd-list by its trusted absolute path"
+if grep -F 'omarchy-cmd-present fprintd-list' "$apply_lock" >/dev/null ||
+  grep -E '(^|[[:space:];&|])fprintd-list([[:space:]]|$)' "$apply_lock" >/dev/null ||
+  grep -E 'command[[:space:]]+-v[[:space:]]+fprintd-list' "$apply_lock" >/dev/null; then
+  fail "the lock helper does not resolve fprintd-list through PATH"
+fi
+pass "the lock helper pins fprintd-list to its packaged system path"
+
+# Exercise the helper as real root when the suite already has it, or as root in
+# an unprivileged user namespace otherwise. A hardened kernel can disable user
+# namespaces, so preserve the static coverage above and skip only this probe.
+root_runner=()
+root_runtime_available=1
+if (( EUID != 0 )); then
+  if command -v unshare >/dev/null && unshare --user --map-root-user true 2>/dev/null; then
+    root_runner=(unshare --user --map-root-user)
+  else
+    root_runtime_available=0
+  fi
+fi
+
+if (( ! root_runtime_available )); then
+  pass "no unprivileged user namespace; skipping the root lock-helper lookup matrix"
+  exit 0
+fi
+
+# Retarget the two PAM files, the trusted fprintd-list binary, and the final
+# shell status query in copies under this scratch directory. The production
+# files and service stay untouched even when this suite itself runs as root.
+test_tmp=$(mktemp -d)
+trap 'rm -rf "$test_tmp"' EXIT
+
+poison_bin="$test_tmp/poison-bin"
+trusted_root_bin="$test_tmp/trusted-root-bin"
+trusted_fprintd="$test_tmp/trusted-fprintd-list"
+password_pam="$test_tmp/omarchy-lock-password"
+fingerprint_pam="$test_tmp/omarchy-lock-fingerprint"
+attack_marker="$test_tmp/user-fprintd-list-ran"
+trusted_uid="$test_tmp/trusted-fprintd-list.uid"
+trusted_args="$test_tmp/trusted-fprintd-list.args"
+attack_args="$test_tmp/user-fprintd-list.args"
+patched_helper="$test_tmp/omarchy-apply-lock-patched"
+absolute_only_helper="$test_tmp/omarchy-apply-lock-absolute-only"
+root_path_only_helper="$test_tmp/omarchy-apply-lock-root-path-only"
+unprotected_helper="$test_tmp/omarchy-apply-lock-unprotected"
+target_user=omarchy-regression-user
+mkdir -p "$poison_bin" "$trusted_root_bin"
+
+# The runtime copy pins to this isolated root path. It contains every bare
+# command the exercised helper needs, but deliberately no fprintd-list.
+for helper in grep rm tee; do
+  ln -s "/usr/bin/$helper" "$trusted_root_bin/$helper"
+done
+
+export TEST_ATTACK_ARGS="$attack_args"
+export TEST_ATTACK_MARKER="$attack_marker"
+export TEST_TRUSTED_ARGS="$trusted_args"
+export TEST_TRUSTED_UID="$trusted_uid"
+
+cat >"$trusted_fprintd" <<'EOF'
+#!/bin/bash
+
+printf '%s\n' "$EUID" >"$TEST_TRUSTED_UID"
+printf '%s\n' "$*" >"$TEST_TRUSTED_ARGS"
+echo "Fingerprints are enrolled"
+EOF
+
+cat >"$poison_bin/fprintd-list" <<'EOF'
+#!/bin/bash
+
+printf '%s\n' "$EUID" >"$TEST_ATTACK_MARKER"
+printf '%s\n' "$*" >"$TEST_ATTACK_ARGS"
+echo "Fingerprints are enrolled"
+EOF
+
+chmod +x "$trusted_fprintd" "$poison_bin/fprintd-list"
+
+prepare_helper() {
+  local destination="$1" keep_root_path="$2" use_absolute_fprintd="$3"
+
+  awk \
+    -v password_pam="$password_pam" \
+    -v fingerprint_pam="$fingerprint_pam" \
+    -v trusted_root_bin="$trusted_root_bin" \
+    -v trusted_fprintd="$trusted_fprintd" \
+    -v keep_root_path="$keep_root_path" \
+    -v use_absolute_fprintd="$use_absolute_fprintd" '
+    {
+      line = $0
+      gsub("/etc/pam\\.d/omarchy-lock-password", "\"" password_pam "\"", line)
+      gsub("/etc/pam\\.d/omarchy-lock-fingerprint", "\"" fingerprint_pam "\"", line)
+
+      if (line == "if (( EUID == 0 )); then" && keep_root_path == 0) {
+        print "if (( 0 )); then"
+        next
+      }
+      if (line == "  export PATH=/usr/share/omarchy/bin:/usr/local/bin:/usr/bin:/bin") {
+        print "  export PATH=\"" trusted_root_bin "\""
+        next
+      }
+      if (line == "if [[ -x /usr/bin/fprintd-list ]] &&") {
+        if (use_absolute_fprintd == 1) {
+          print "if [[ -x \"" trusted_fprintd "\" ]] &&"
+        } else {
+          print "if command -v fprintd-list >/dev/null 2>&1 &&"
+        }
+        next
+      }
+      if (line == "  /usr/bin/fprintd-list \"$target_user\" 2>/dev/null | grep -qi finger; then") {
+        if (use_absolute_fprintd == 1) {
+          print "  \"" trusted_fprintd "\" \"$target_user\" 2>/dev/null | grep -qi finger; then"
+        } else {
+          print "  fprintd-list \"$target_user\" 2>/dev/null | grep -qi finger; then"
+        }
+        next
+      }
+      if (line == "if omarchy-shell lock status >/dev/null 2>&1; then") {
+        print "if false; then"
+        next
+      }
+
+      print line
+    }
+  ' "$apply_lock" >"$destination"
+  chmod +x "$destination"
+}
+
+prepare_helper "$patched_helper" 1 1
+prepare_helper "$absolute_only_helper" 0 1
+prepare_helper "$root_path_only_helper" 1 0
+prepare_helper "$unprotected_helper" 0 0
+
+for helper in "$patched_helper" "$absolute_only_helper" "$root_path_only_helper" "$unprotected_helper"; do
+  if grep -F '/etc/pam.d/' "$helper" >/dev/null ||
+    grep -F '/usr/bin/fprintd-list' "$helper" >/dev/null ||
+    grep -F 'omarchy-shell lock status' "$helper" >/dev/null; then
+    fail "the isolated root fixture redirects every live-system lock-helper target"
+  fi
+done
+
+reset_runtime_files() {
+  rm -f "$password_pam" "$fingerprint_pam" "$trusted_uid" "$trusted_args" "$attack_marker" "$attack_args"
+}
+
+run_as_root() {
+  local helper="$1" description="$2" output
+
+  if ! output=$(PATH="$poison_bin:/usr/bin:/bin" OMARCHY_INSTALL_USER="$target_user" \
+    "${root_runner[@]}" /bin/bash "$helper" 2>&1); then
+    fail "$description" "$output"
+  fi
+}
+
+reset_runtime_files
+run_as_root "$patched_helper" "the fully hardened lock helper runs in an isolated root context"
+[[ ! -e $attack_marker ]] || fail "the hardened root lock helper executes the user-planted fprintd-list"
+grep -Fx '0' "$trusted_uid" >/dev/null || fail "the trusted fprintd-list probe runs with EUID 0"
+grep -Fx "$target_user" "$trusted_args" >/dev/null || fail "the trusted fprintd-list probe receives the target user"
+[[ -s $password_pam && -s $fingerprint_pam ]] ||
+  fail "the isolated root lock-helper run writes both scratch PAM fixtures"
+pass "the hardened root lock helper uses the trusted fingerprint probe"
+
+reset_runtime_files
+run_as_root "$absolute_only_helper" "the absolute-path-only lock helper runs in an isolated root context"
+[[ ! -e $attack_marker ]] || fail "an absolute fprintd-list path permits the user-planted command"
+grep -Fx '0' "$trusted_uid" >/dev/null || fail "the absolute-path defense runs the trusted probe as root"
+pass "the absolute fprintd-list path independently blocks the user-planted command"
+
+reset_runtime_files
+run_as_root "$root_path_only_helper" "the root-PATH-only lock helper runs in an isolated root context"
+[[ ! -e $attack_marker ]] || fail "the trusted root path permits the user-planted fprintd-list"
+pass "the trusted root path independently blocks the user-planted command"
+
+# Mutation control: removing both protections must execute the planted command
+# as UID 0, proving the matrix detects the original privilege-boundary failure.
+reset_runtime_files
+run_as_root "$unprotected_helper" "the unprotected mutation runs in an isolated root context"
+grep -Fx '0' "$attack_marker" >/dev/null ||
+  fail "the root lock-helper fixture detects a PATH-resolved fprintd-list regression"
+grep -Fx "$target_user" "$attack_args" >/dev/null ||
+  fail "the planted fprintd-list receives the target user"
+[[ -s $fingerprint_pam ]] || fail "the planted fprintd-list controls the fingerprint PAM branch"
+pass "the root lock-helper matrix rejects the vulnerable PATH lookup"
diff --git a/test/shell.d/upgrade-to-quattro-test.sh b/test/shell.d/upgrade-to-quattro-test.sh
index 0648409d..d357f513 100644
--- a/test/shell.d/upgrade-to-quattro-test.sh
+++ b/test/shell.d/upgrade-to-quattro-test.sh
@@ -6,6 +6,10 @@ source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
 
 upgrade_to_quattro="$ROOT/bin/omarchy-upgrade-to-quattro"
 
+function_body() {
+  awk -v name="$1" '$0 == name "() {" { inside = 1; next } inside && $0 == "}" { exit } inside' "$upgrade_to_quattro"
+}
+
 snapshot_line=$(grep -n '^create_pre_upgrade_snapshot$' "$upgrade_to_quattro" | cut -d: -f1)
 pacman_line=$(grep -n '^configure_pacman_channel$' "$upgrade_to_quattro" | cut -d: -f1)
 [[ -n $snapshot_line && -n $pacman_line ]] || fail "upgrade snapshot and first mutation calls exist"
@@ -73,6 +77,44 @@ grep -F 'OMARCHY_INSTALL_USER="$target_user"' "$upgrade_to_quattro" >/dev/null
 grep -F '"$apply_lock"' "$upgrade_to_quattro" >/dev/null
 pass "Omarchy 4 upgrade configures lock screen authentication for the target user"
 
+root_path_count=$(awk '/^root_path=/{ count++ } END { print count + 0 }' "$upgrade_to_quattro")
+(( root_path_count == 1 )) || fail "Omarchy 4 upgrade defines exactly one root command path"
+grep -Fx 'root_path=/usr/share/omarchy/bin:/usr/local/bin:/usr/bin:/bin' "$upgrade_to_quattro" >/dev/null ||
+  fail "Omarchy 4 upgrade limits root command lookup to trusted system directories"
+if grep -E '^root_path=.*(target_home|\.local/bin)' "$upgrade_to_quattro" >/dev/null; then
+  fail "Omarchy 4 upgrade does not put the target user's bin directory on the root command path"
+fi
+grep -Fx 'package_path="$root_path:$target_home/.local/bin"' "$upgrade_to_quattro" >/dev/null ||
+  fail "Omarchy 4 upgrade retains the target user's bin directory for user commands"
+
+lock_authentication_body=$(function_body configure_lock_authentication)
+lock_path_assignment_count=$(awk '{ count += gsub(/(^|[[:space:]])PATH=/, "") } END { print count + 0 }' <<<"$lock_authentication_body")
+(( lock_path_assignment_count == 1 )) ||
+  fail "Omarchy 4 upgrade gives the privileged lock helper exactly one command path"
+grep -Fx '    PATH="$root_path" \' <<<"$lock_authentication_body" >/dev/null ||
+  fail "Omarchy 4 upgrade gives the privileged lock helper the trusted root path"
+if grep -E '(package_path|target_home|\.local/bin)' <<<"$lock_authentication_body" >/dev/null; then
+  fail "Omarchy 4 upgrade does not give the privileged lock helper the target user's path"
+fi
+
+firewall_body=$(function_body apply_firewall_defaults)
+firewall_path_assignment_count=$(awk '{ count += gsub(/(^|[[:space:]])PATH=/, "") } END { print count + 0 }' <<<"$firewall_body")
+(( firewall_path_assignment_count == 1 )) ||
+  fail "Omarchy 4 upgrade gives the privileged firewall helper exactly one command path"
+grep -Fx '  as_root env OMARCHY_PATH=/usr/share/omarchy PATH="$root_path" \' <<<"$firewall_body" >/dev/null ||
+  fail "Omarchy 4 upgrade gives the privileged firewall helper the trusted root path"
+if grep -E '(package_path|target_home|\.local/bin)' <<<"$firewall_body" >/dev/null; then
+  fail "Omarchy 4 upgrade does not give the privileged firewall helper the target user's path"
+fi
+
+user_omarchy_body=$(function_body run_as_user_omarchy)
+grep -F 'PATH="$package_path"' <<<"$user_omarchy_body" >/dev/null ||
+  fail "Omarchy 4 upgrade retains the package and user path for target-user commands"
+if grep -F 'PATH="$root_path"' <<<"$user_omarchy_body" >/dev/null; then
+  fail "Omarchy 4 upgrade does not narrow target-user commands to the root-only path"
+fi
+pass "Omarchy 4 upgrade separates privileged and target-user command paths"
+
 grep -F 'install/helpers/browser-policy.sh' "$upgrade_to_quattro" >/dev/null ||
   fail "Omarchy 4 upgrade uses the shared browser-policy helper"
 grep -F 'as_root test -f "$browser_policy_helper"' "$upgrade_to_quattro" >/dev/null ||
@@ -100,10 +142,6 @@ pass "Omarchy 4 upgrade retires systemd-networkd for NetworkManager"
 # Booting with both managers enabled leaves them fighting over the Wi-Fi
 # adapter, so enabling NetworkManager and disabling iwd cannot be separated by
 # any step that might abort in between.
-function_body() {
-  awk -v name="$1" '$0 == name "() {" { inside = 1; next } inside && $0 == "}" { exit } inside' "$upgrade_to_quattro"
-}
-
 migrations_body=$(function_body run_post_upgrade_migrations)
 grep -F 'fail "Omarchy migrations did not complete.' <<<"$migrations_body" >/dev/null ||
   fail "Omarchy 4 upgrade fails when a migration cannot complete"

From 8f155493805cab5e2c520b83c86b6a1aba6ebe7b Mon Sep 17 00:00:00 2001
From: Spencer Bull <spencer@omarchy.org>
Date: Fri, 4 Sep 2026 21:50:41 -0500
Subject: [PATCH 11/27] Ask, default no, before Remove Hermes deletes the
 user's data

---
 bin/omarchy-remove-ai-hermes       | 36 +++++++++++++----
 manual/17-ai.md                    |  2 +-
 test/shell.d/hermes-remove-test.sh | 65 +++++++++++++++++++++++++++++-
 3 files changed, 94 insertions(+), 9 deletions(-)

diff --git a/bin/omarchy-remove-ai-hermes b/bin/omarchy-remove-ai-hermes
index 1145fbd1..924cafab 100755
--- a/bin/omarchy-remove-ai-hermes
+++ b/bin/omarchy-remove-ai-hermes
@@ -25,11 +25,8 @@ omarchy-install-hermes-cli --remove || cli_removed=false
 # has whatever was there before, and none of it is ours to delete.
 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. Not ~/.config/Hermes, which holds the gateway connections
-  # and their encrypted tokens, the active profile and the update settings. Not
-  # the rest of ~/.hermes either: the chats, memories and the skills Hermes
-  # wrote for itself are the user's, they are small, and finding them still
-  # there after a reinstall is the better surprise.
+  # 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" \
@@ -58,10 +55,35 @@ if [[ -f $HOME/.hermes/hermes-agent/.hermes-bootstrap-complete ]]; then
     fi
   done
 
+  # What is left 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, default no. Only here, behind the bootstrap marker: without
+  # it ~/.hermes is an install the app never owned, and offering to delete it
+  # would put the user's own Hermes on the chopping block. Without a terminal
+  # to ask in, keeping it is the answer.
+  data_removed=false
+  if [[ -t 0 ]] && command -v gum >/dev/null; then
+    # du answers non-zero when either directory is missing (the app makes
+    # ~/.config/Hermes, but nothing says it is still there), 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 your Hermes data ($size: chats, memories, skills, connections and tokens)?"; then
+      rm -rf "$HOME/.hermes" "$HOME/.config/Hermes"
+      data_removed=true
+    fi
+  fi
+
   echo ""
   echo "Hermes Desktop has been removed."
-  echo "Your chats, memories, and skills are still in ~/.hermes,"
-  echo "and your connections and settings in ~/.config/Hermes."
+  if [[ $data_removed == true ]]; then
+    echo "Its chats, memories, and settings in ~/.hermes and ~/.config/Hermes are gone too."
+  else
+    echo "Your chats, memories, and skills are still in ~/.hermes,"
+    echo "and your connections and settings in ~/.config/Hermes."
+  fi
 else
   echo ""
   echo "Hermes Desktop has been removed."
diff --git a/manual/17-ai.md b/manual/17-ai.md
index 78b51430..7a9e7c49 100644
--- a/manual/17-ai.md
+++ b/manual/17-ai.md
@@ -46,7 +46,7 @@ Crashes can also be silenced one program at a time, which is what the diagnosis
 
 The _Install > AI_ menu also carries a few graphical AI apps: the ChatGPT desktop app, Grok Bot for chatting with xAI's models, and Hermes Desktop.
 
-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. Removing the app under _Remove > AI_ takes that runtime with it, and keeps your chats, memories, and the skills Hermes wrote for itself.
+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. 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.
 
 ### Local LLMs
 
diff --git a/test/shell.d/hermes-remove-test.sh b/test/shell.d/hermes-remove-test.sh
index d3389087..88554894 100755
--- a/test/shell.d/hermes-remove-test.sh
+++ b/test/shell.d/hermes-remove-test.sh
@@ -24,6 +24,16 @@ cat >"$mock_bin/omarchy-install-hermes-cli" <<'SH'
 printf '%s\0' "$@" >>"$OMARCHY_TEST_INSTALLER_LOG"
 exit "${OMARCHY_TEST_INSTALLER_STATUS:-0}"
 SH
+
+# The remover asks through gum whether the user's data should go too. The stub
+# answers "no" unless a test says otherwise, and logs every call: a real gum
+# would hang a test run, and one that answered "yes" on its own would be the
+# very data loss the default-no exists to prevent.
+cat >"$mock_bin/gum" <<'SH'
+#!/bin/bash
+printf '%s\0' "$@" >>"$OMARCHY_TEST_GUM_LOG"
+exit "${OMARCHY_TEST_GUM_STATUS:-1}"
+SH
 chmod +x "$mock_bin"/*
 
 seed_install() {
@@ -43,13 +53,30 @@ seed_install() {
   touch "$test_home/.hermes/hermes-agent/.hermes-bootstrap-complete"
 }
 
+# </dev/null pins stdin off a terminal, so these runs exercise the
+# non-interactive path no matter where the suite itself is running.
 remove() {
   : >"$test_tmp/installer-log"
+  : >"$test_tmp/gum-log"
   OMARCHY_TEST_DROP_LOG="$test_tmp/drop-log" \
     OMARCHY_TEST_INSTALLER_LOG="$test_tmp/installer-log" \
     OMARCHY_TEST_INSTALLER_STATUS="${OMARCHY_TEST_INSTALLER_STATUS:-0}" \
+    OMARCHY_TEST_GUM_LOG="$test_tmp/gum-log" \
     HOME="$test_home" PATH="$mock_bin:$PATH" \
-    bash "$ROOT/bin/omarchy-remove-ai-hermes" >/dev/null 2>&1
+    bash "$ROOT/bin/omarchy-remove-ai-hermes" </dev/null >/dev/null 2>&1
+}
+
+# script(1) puts the remover on a pty, which is the only way -t 0 answers true
+# without a person at a real one; the stubbed gum then supplies the answer.
+remove_tty() {
+  : >"$test_tmp/installer-log"
+  : >"$test_tmp/gum-log"
+  OMARCHY_TEST_DROP_LOG="$test_tmp/drop-log" \
+    OMARCHY_TEST_INSTALLER_LOG="$test_tmp/installer-log" \
+    OMARCHY_TEST_GUM_LOG="$test_tmp/gum-log" \
+    OMARCHY_TEST_GUM_STATUS="${OMARCHY_TEST_GUM_STATUS:-1}" \
+    HOME="$test_home" PATH="$mock_bin:$PATH" \
+    script -qec "bash '$ROOT/bin/omarchy-remove-ai-hermes'" /dev/null >/dev/null 2>&1
 }
 
 # The app brings its own uv and its own node; both are runtime, not data.
@@ -77,6 +104,12 @@ pass "removal clears only the managed Node links it stranded"
 [[ -f $test_home/.hermes/SOUL.md ]] || fail "SOUL.md survives removal"
 pass "removal keeps what belongs to the user"
 
+# Without a terminal there is nobody to ask, so gum must not even be reached:
+# a gum that answered "yes" on its own would be a data loss.
+[[ ! -s $test_tmp/gum-log ]] ||
+  fail "removal does not ask about the user's data without a terminal"
+pass "removal keeps the user's data unasked when there is no terminal"
+
 [[ ! -e $test_home/.local/bin/hermes ]] || fail "the app's own hermes command is removed"
 pass "removal takes the command the app installed"
 
@@ -134,6 +167,36 @@ remove || fail "remove succeeds with a wrapper pointing at a sibling directory"
   fail "a wrapper pointing at ~/xhermes is not mistaken for one pointing into ~/.hermes"
 pass "removal matches the runtime path as a plain string"
 
+# On a terminal the user is asked, default no: declining leaves every piece of
+# data where it was.
+seed_install
+remove_tty || fail "remove succeeds when the data question is declined"
+tr '\0' '\n' <"$test_tmp/gum-log" | grep -qx 'confirm' ||
+  fail "removal asks about the user's data on a terminal"
+[[ -f $test_home/.hermes/sessions/one.json && -d $test_home/.config/Hermes ]] ||
+  fail "declining the question keeps the user's data"
+pass "removal asks on a terminal and declining keeps the data"
+
+# An explicit yes is the one path that takes the data too.
+seed_install
+OMARCHY_TEST_GUM_STATUS=0 remove_tty || fail "remove succeeds when the data goes too"
+[[ ! -e $test_home/.hermes && ! -e $test_home/.config/Hermes ]] ||
+  fail "a yes deletes ~/.hermes and ~/.config/Hermes"
+pass "removal deletes the user's data only on an explicit yes"
+
+# Without the bootstrap marker ~/.hermes is an install the app never owned, so
+# it must not even be offered for deletion -- not to a terminal, not to a user
+# who would say yes.
+seed_install
+rm -f "$test_home/.hermes/hermes-agent/.hermes-bootstrap-complete"
+OMARCHY_TEST_GUM_STATUS=0 remove_tty ||
+  fail "remove succeeds when the app never installed Hermes"
+[[ ! -s $test_tmp/gum-log ]] ||
+  fail "a Hermes the app never installed is not offered for deletion"
+[[ -d $test_home/.hermes/hermes-agent && -d $test_home/.config/Hermes ]] ||
+  fail "a Hermes the app never installed survives a would-be yes"
+pass "removal never offers a Hermes the app did not install"
+
 # A CLI teardown that fails must not stop the runtime handling, and must not be
 # papered over either: the data work still happens, and the failure reaches the
 # caller's exit code.

From e8e92c5092c9bbbf3d7fc5240f8551fd1eeaced9 Mon Sep 17 00:00:00 2001
From: David Heinemeier Hansson <david@hey.com>
Date: Sat, 5 Sep 2026 10:17:35 +0200
Subject: [PATCH 12/27] Register the Chromium native messaging hosts for Brave
 Origin (#10292)

Brave Origin keeps its profile under ~/.config/BraveSoftware/Brave-Origin
rather than Brave-Browser, so the Copy URL and Download Video installers
never wrote their host manifests there. The extensions loaded but the
shortcuts did nothing. Add the Origin profile roots and rerun both
installers through a migration.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/omarchy-install-chromium-copy-url  | 3 +++
 bin/omarchy-install-chromium-ytdlp     | 3 +++
 migrations/1788595060.sh               | 4 ++++
 test/shell.d/chromium-copy-url-test.sh | 4 ++++
 test/shell.d/chromium-ytdlp-test.sh    | 4 ++++
 5 files changed, 18 insertions(+)
 create mode 100644 migrations/1788595060.sh

diff --git a/bin/omarchy-install-chromium-copy-url b/bin/omarchy-install-chromium-copy-url
index 4f6dae02..0ee586d6 100755
--- a/bin/omarchy-install-chromium-copy-url
+++ b/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"
 )
diff --git a/bin/omarchy-install-chromium-ytdlp b/bin/omarchy-install-chromium-ytdlp
index c700578c..63ba46d5 100755
--- a/bin/omarchy-install-chromium-ytdlp
+++ b/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"
 )
diff --git a/migrations/1788595060.sh b/migrations/1788595060.sh
new file mode 100644
index 00000000..750da2dc
--- /dev/null
+++ b/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
diff --git a/test/shell.d/chromium-copy-url-test.sh b/test/shell.d/chromium-copy-url-test.sh
index 6dad096f..daed1a3d 100644
--- a/test/shell.d/chromium-copy-url-test.sh
+++ b/test/shell.d/chromium-copy-url-test.sh
@@ -71,6 +71,10 @@ jq -e --arg path "$ROOT/bin/omarchy-chromium-copy-url-host" '
 ' "$native_manifest" >/dev/null || fail "copy-url native host manifest uses Omarchy host path and extension id"
 pass "copy-url native host installer registers the stable extension id"
 
+[[ -f $test_home/.config/BraveSoftware/Brave-Origin/NativeMessagingHosts/com.omarchy.copy_url.json ]] ||
+  fail "copy-url native host installer covers Brave Origin"
+pass "copy-url native host installer covers Brave Origin"
+
 # Chromium ships in the base packages, so fresh installs do not go through
 # omarchy-install-browser, and they mark every migration as already applied.
 # The user install still has to register the host itself.
diff --git a/test/shell.d/chromium-ytdlp-test.sh b/test/shell.d/chromium-ytdlp-test.sh
index 6cd571c4..a2872699 100755
--- a/test/shell.d/chromium-ytdlp-test.sh
+++ b/test/shell.d/chromium-ytdlp-test.sh
@@ -33,6 +33,10 @@ jq -e --arg path "$ROOT/bin/omarchy-chromium-ytdlp-host" '
 ' "$manifest_path" >/dev/null
 pass "yt-dlp native host manifest uses Omarchy host path and extension id"
 
+[[ -f $test_home/.config/BraveSoftware/Brave-Origin/NativeMessagingHosts/com.omarchy.ytdlp.json ]] ||
+  fail "yt-dlp native host installer covers Brave Origin"
+pass "yt-dlp native host installer covers Brave Origin"
+
 parse_result=$(bash -c '
   OMARCHY_PATH="$3"
   source "$1"

From 110cb8f5b4aba7021c17ebade1850cba221d9da6 Mon Sep 17 00:00:00 2001
From: David Heinemeier Hansson <david@hey.com>
Date: Sat, 5 Sep 2026 16:16:23 +0200
Subject: [PATCH 13/27] Add original vi as a standard terminal editor (#10307)

* Add vi as a standard terminal editor

* Use the original vi package
---
 install/omarchy-base.packages  | 1 +
 manual/18-development-tools.md | 2 ++
 migrations/1788596255.sh       | 3 +++
 3 files changed, 6 insertions(+)
 create mode 100644 migrations/1788596255.sh

diff --git a/install/omarchy-base.packages b/install/omarchy-base.packages
index c5013ba6..03af6299 100644
--- a/install/omarchy-base.packages
+++ b/install/omarchy-base.packages
@@ -133,6 +133,7 @@ ufw-docker
 unzip
 usage
 uwsm
+vi
 whois
 wireless-regdb
 wireplumber
diff --git a/manual/18-development-tools.md b/manual/18-development-tools.md
index 59ae9198..f49125d9 100644
--- a/manual/18-development-tools.md
+++ b/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`.
diff --git a/migrations/1788596255.sh b/migrations/1788596255.sh
new file mode 100644
index 00000000..e4c7b0c4
--- /dev/null
+++ b/migrations/1788596255.sh
@@ -0,0 +1,3 @@
+echo "Add vi as a standard terminal editor"
+
+omarchy-pkg-add vi

From 534567398806f36bebcb77c614e6bb8ad2828a5e Mon Sep 17 00:00:00 2001
From: Spencer Bull <spencer@omarchy.org>
Date: Fri, 4 Sep 2026 16:40:12 -0500
Subject: [PATCH 14/27] Add OpenClaw to Install > AI as a web app on its own
 gateway

OpenClaw's desktop experience on Linux is its Control UI, served by the
gateway the openclaw package runs, so the Install > AI entry installs
the package and a web app launcher that routes through the new
omarchy-launch-openclaw: first launch hands off to OpenClaw's own
onboarding wizard, later launches start the gateway when needed and open
the dashboard's single-use browser handoff URL as an app window.
Remove > AI tears the gateway service down through OpenClaw's own
gateway uninstall (falling back to systemctl by hand), aborts rather
than dropping the package under a gateway that will not stop, and keeps
the user's agent in ~/.openclaw.

OpenClaw also joins Setup > Defaults > Agent through the same
agent_installer seam Hermes carries: its CLI is the pacman package
rather than a mise tool, so omarchy-install-openclaw-cli answers
--check/--now with pacman, and omarchy-agent runs `openclaw chat`,
seeding prompts through --message.

The menu mark is a new U+E90C glyph traced from the package's lobster
favicon; E90B stays free for the Perplexity mark still in flight on its
own branch.
The launcher recovers the gateway through `openclaw gateway install --force`
(unit not enabled: missing, or an install that died after writing it) or
`openclaw gateway start` (enabled but stopped), never `openclaw dashboard
--yes`: as of OpenClaw 2026.9.1 that defers to "the owning supervisor" in
both cases, and once the gateway is up it copies a one-time browser pairing
URL into the clipboard. The dashboard probe is bounded so an app-grid launch
cannot hang without a terminal to interrupt it. Removal treats only
systemd's own "inactive"/"failed" as a stopped gateway, so an unreachable
user manager aborts instead of dropping the package under a live process.
All of it verified against a real 2026.9.1 install.
Removal also takes down the node-host unit if OpenClaw ever installed one, and
asks (default no, only on a terminal) whether ~/.openclaw should go too, with
its size: the chats and credentials live there next to hundreds of megabytes
of plugin runtimes and cache OpenClaw downloads for itself.
Onboarding goes through omarchy-openclaw-onboard rather than bare `openclaw
onboard`: as of 2026.9.1 the bare command is the guided flow, which ends by
running a foreground gateway and handing off to a browser tab without
returning, so the install script never reached the app launch and no service
was installed. The helper runs the classic wizard (--flow quickstart
--install-daemon --skip-ui) as a background job that keeps the terminal as its
stdin, so its prompts render and take input as upstream draws them, and stops
it once the gateway answers: upstream leaves the wizard running after its
outro (only the TUI branch exits, and the model sign-in holds a socket open).
Every quickstart prompt precedes the service install, so that point is safe.
A gateway that never comes up after this run applies setup ends the wait as a
failure instead
of hanging, an already-running OpenClaw is left alone rather than mistaken for
this run's success, a gateway answering on the port is only this run's once its
process is the unit's own MainPID (an orphan from an
earlier run) is not mistaken for the service this run installs, and a signal at
the helper takes the wizard down with it.
---
 bin/omarchy                           |   1 +
 bin/omarchy-agent                     |   9 +
 bin/omarchy-default-agent             |   8 +-
 bin/omarchy-install-ai-openclaw       |  35 ++++
 bin/omarchy-install-openclaw-cli      |  29 +++
 bin/omarchy-launch-openclaw           |  91 ++++++++
 bin/omarchy-openclaw-onboard          | 130 ++++++++++++
 bin/omarchy-remove-ai-openclaw        |  78 +++++++
 default/fonts/omarchy/README.md       |   1 +
 default/fonts/omarchy/omarchy.ttf     | Bin 5052 -> 5284 bytes
 default/omarchy/omarchy-menu.jsonc    |   3 +
 manual/17-ai.md                       |   4 +-
 test/shell.d/default-agent-test.sh    |  65 ++++++
 test/shell.d/launch-openclaw-test.sh  | 189 +++++++++++++++++
 test/shell.d/menu-test.sh             |   5 +-
 test/shell.d/openclaw-onboard-test.sh | 288 ++++++++++++++++++++++++++
 test/shell.d/remove-ai-test.sh        | 158 ++++++++++++++
 17 files changed, 1088 insertions(+), 6 deletions(-)
 create mode 100755 bin/omarchy-install-ai-openclaw
 create mode 100755 bin/omarchy-install-openclaw-cli
 create mode 100755 bin/omarchy-launch-openclaw
 create mode 100755 bin/omarchy-openclaw-onboard
 create mode 100755 bin/omarchy-remove-ai-openclaw
 create mode 100755 test/shell.d/launch-openclaw-test.sh
 create mode 100755 test/shell.d/openclaw-onboard-test.sh

diff --git a/bin/omarchy b/bin/omarchy
index 4219109b..2bace6df 100755
--- a/bin/omarchy
+++ b/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"
diff --git a/bin/omarchy-agent b/bin/omarchy-agent
index bc65ab9a..0aa0273b 100755
--- a/bin/omarchy-agent
+++ b/bin/omarchy-agent
@@ -82,6 +82,15 @@ 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")
diff --git a/bin/omarchy-default-agent b/bin/omarchy-default-agent
index 9d575514..f832b22d 100755
--- a/bin/omarchy-default-agent
+++ b/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|hermes|copilot|crush]
+# omarchy:args=[pi|omp|opencode|ori|claude|codex|grok|openclaw|agy|hermes|copilot|crush]
 # omarchy:examples=omarchy default agent | omarchy default agent codex | omarchy default agent claude
 
 installing=false
@@ -32,11 +32,12 @@ 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" ;;
 *)
-  echo "Usage: omarchy-default-agent <pi|omp|opencode|ori|claude|codex|grok|agy|hermes|copilot|crush>"
+  echo "Usage: omarchy-default-agent <pi|omp|opencode|ori|claude|codex|grok|openclaw|agy|hermes|copilot|crush>"
   exit 1
   ;;
 esac
@@ -45,7 +46,8 @@ agent_package=${agent_package:-$agent}
 
 # 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.
+# 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
diff --git a/bin/omarchy-install-ai-openclaw b/bin/omarchy-install-ai-openclaw
new file mode 100755
index 00000000..cb79a9ad
--- /dev/null
+++ b/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."
diff --git a/bin/omarchy-install-openclaw-cli b/bin/omarchy-install-openclaw-cli
new file mode 100755
index 00000000..18e12317
--- /dev/null
+++ b/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
diff --git a/bin/omarchy-launch-openclaw b/bin/omarchy-launch-openclaw
new file mode 100755
index 00000000..13ab6c24
--- /dev/null
+++ b/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"
diff --git a/bin/omarchy-openclaw-onboard b/bin/omarchy-openclaw-onboard
new file mode 100755
index 00000000..5bac15bd
--- /dev/null
+++ b/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"
diff --git a/bin/omarchy-remove-ai-openclaw b/bin/omarchy-remove-ai-openclaw
new file mode 100755
index 00000000..47658a20
--- /dev/null
+++ b/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 ]] && command -v gum >/dev/null; 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
diff --git a/default/fonts/omarchy/README.md b/default/fonts/omarchy/README.md
index 03b8a909..a4ab6935 100644
--- a/default/fonts/omarchy/README.md
+++ b/default/fonts/omarchy/README.md
@@ -13,6 +13,7 @@ The private-use glyphs in `omarchy.ttf` are:
 - `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+E90C` — OpenClaw, traced from the lobster mascot the openclaw package ships as `dist/control-ui/favicon.svg`, since upstream publishes no monochrome SVG; `E90B` is left for the Perplexity mark already in flight on another branch
 
 The agent marks are monochrome so the menu can render them using the active
 theme's foreground and selection colors.
diff --git a/default/fonts/omarchy/omarchy.ttf b/default/fonts/omarchy/omarchy.ttf
index 1ddeb85ce255a899a563eb985e070a6f63f47258..fb9d22a74a6638b60b4f3a701a081a36169fe3db 100644
GIT binary patch
delta 722
zcmZ8dL1+_E5S{-w*`#UOY_iEl)+jdVu4xQanl@Q#TT48M>A_-ycqr0s8jZMVg0{82
zv=uLcpw(Y$(Su4osswWJ5Y)RUh#ow6kRH?=1d$#J#jLZzg2?b@-h1<BKL6JaKIvMK
zmi!t37^lV#_ndiu@&o{}^hB<xmuu<kS=1i^X!wG$a9;lP`6qy_6QHe9$m>(x&--uT
z*%~5QK*LFFt;n|!orU7eyvs$;;`}=50i%@D{X4=v0B##~tf<eIiApMv0I~;-1Jimj
z|MuJ0RRAwuNZyo7S7u&pzWfd#KEnPQ5X>Zzuuoiyv1K8^z1ps`bs^<&H9LNm@$O|^
zWRiUllqI+iMHp_zQ_KcbU<}9Y2o4cP*buADQ6M37t@UxNuBLB;0#*qGba>Dqhq?$Q
zxC{$*sJrTJ)5QM&KCygr!xT5nhvu5eFm4A)&>3_9VUKCh<HjL?8_f*hVx4pvcL7)c
zvARNA2otD{b$I30W!t8G(q7>&@}H_}9A{?_oLkgGt9M)8an)SgYeElE=J7~uz>}g!
zDVy{BUb5peZ*tGLS=a|r{MutMf}a*{rvd+d8Vn@*j!04p%MjPs+f9ke^Fc{Urjlw$
zc$cY4Z!*y%1^j#@tfv0q6tauim^wTf8wo^wBeBt8HI`j$T+@c!K2g&|L8j;WL$Y9T
zpL?hQvM9<HzU&fib}&DuX~uZEJ(J;yBa>-Qj~kjcmmh5Gh@rHiIO0k)5{W8thoYoI
onopK}){eimI_3RAh@YJnRZ7~}ym-9TSt{qJbB2Bu;7-l>1M@+n#{d8T

delta 516
zcmZ9HPe>GD7{;G>X4YBP&Dmv^JQx|Qn=33S4U~rtL4gQGkkBd6VcpupjJwnpyC6sx
z5eh24{zG_By5vEas|a=r>5m65o;;Z4pG$%uflSYAo|=#6d*0vky&vy4bG?f_&rVKa
z5rB7NxbOU})uBN^^5oH??^buz+Xi_W(Aw{MjXO7&%$I=v21u@#OYYdYspKJ$s<Hn<
znL%8P40)d1UG{7B0t}1%oqWx!6y5gT)C`b5Mb7(fy(&3bKo8Pa8Jrn+{nD48TQAr!
z#-S_K%Kh5z#P5fI-OuyKY9QmO0Vz(#NIF%Z4C)DlJ0#9DstWW(GdD0w&mhIbfQur^
z@KM1%G`6vw2t%I!pGp{pvs^Rbt59)0?U0W6zX|N-r*3O)R<c=6G<Tp?)wS_pUo&Mk
zXT$`myY)afO*80BeAP7|_;q4g^lUb(K3dmx$8ppj>nO)3^S(IF`=bv-Bi5w@v_-!I
zY<~OvAo8u(E5pw>F1FYa7)tc6JR2@k?<oJcjyTf%v3v9db*Oh)kBlF&QY>ikn}ck1
US~`QZ^qz>VKG|p0j(tV&7h2tStpET3

diff --git a/default/omarchy/omarchy-menu.jsonc b/default/omarchy/omarchy-menu.jsonc
index 30ee45fc..a82254c6 100644
--- a/default/omarchy/omarchy-menu.jsonc
+++ b/default/omarchy/omarchy-menu.jsonc
@@ -143,6 +143,7 @@
   "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.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"},
@@ -243,6 +244,7 @@
   "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.openclaw": {"icon":"","iconFont":"omarchy","label":"OpenClaw","disabled":"omarchy-pkg-present openclaw","action":"omarchy-launch-floating-terminal-with-presentation omarchy-install-ai-openclaw"},
   "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.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"},
@@ -308,6 +310,7 @@
   "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.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"},
diff --git a/manual/17-ai.md b/manual/17-ai.md
index 78b51430..f94c3546 100644
--- a/manual/17-ai.md
+++ b/manual/17-ai.md
@@ -44,10 +44,12 @@ Crashes can also be silenced one program at a time, which is what the diagnosis
 
 ### Desktop apps
 
-The _Install > AI_ menu also carries a few graphical AI apps: the ChatGPT desktop app, Grok Bot for chatting with xAI's models, and Hermes Desktop.
+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, and OpenClaw.
 
 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. Removing the app under _Remove > AI_ takes that runtime with it, and keeps your chats, memories, and the skills Hermes wrote for itself.
 
+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
 
 Omarchy recommends two ways of running local LLM models: LM Studio and Ollama. LM Studio provides a GUI interface for finding open-weight models, installing them, and running them. It's a great way to get going easily. Ollama offers a CLI for doing so similarly. But if you're new to local models, I'd start with LM Studio. You can install either under _Install > AI_ in the Omarchy Menu.
diff --git a/test/shell.d/default-agent-test.sh b/test/shell.d/default-agent-test.sh
index f421fabb..6a2f15b2 100644
--- a/test/shell.d/default-agent-test.sh
+++ b/test/shell.d/default-agent-test.sh
@@ -542,3 +542,68 @@ fi
 grep -F "missing is not installed" "$test_tmp/missing-output" >/dev/null ||
   fail "agent launcher explains when the default command is missing"
 pass "agent launcher reports a missing default command"
+
+# OpenClaw comes from its pacman package, not mise: choosing it must route
+# through omarchy-install-openclaw-cli and never touch a mise environment.
+cat >"$mock_bin/omarchy-pkg-present" <<'SH'
+#!/bin/bash
+[[ $1 == openclaw && ${OMARCHY_TEST_OPENCLAW_INSTALLED:-false} == "true" ]]
+SH
+cat >"$mock_bin/omarchy-pkg-add" <<'SH'
+#!/bin/bash
+printf '%s\n' "pkg-add $*" >>"$OMARCHY_TEST_STUB_LOG"
+SH
+cat >"$mock_bin/omarchy-launch-openclaw" <<'SH'
+#!/bin/bash
+printf '%s\0' omarchy-launch-openclaw "$@" >"$OMARCHY_TEST_AGENT_INLINE_LOG"
+SH
+cat >"$mock_bin/openclaw" <<'SH'
+#!/bin/bash
+exit 0
+SH
+chmod +x "$mock_bin/omarchy-pkg-present" "$mock_bin/omarchy-pkg-add" \
+  "$mock_bin/omarchy-launch-openclaw" "$mock_bin/openclaw"
+
+: >"$launch_log"
+: >"$terminal_log"
+: >"$mise_history"
+OMARCHY_TEST_OPENCLAW_INSTALLED=true omarchy-default-agent openclaw
+read -r chosen <"$agent_file"
+[[ $chosen == openclaw ]] || fail "choosing OpenClaw records it as the default agent"
+mapfile -d '' -t launch_args <"$launch_log"
+[[ ${launch_args[*]} == "--app-id=org.omarchy.agent omarchy-launch-openclaw --tui" ]] ||
+  fail "choosing OpenClaw launches its terminal UI"
+[[ ! -s $terminal_log ]] || fail "an installed OpenClaw needs no install terminal"
+! grep -q 'use -g openclaw' "$mise_history" || fail "OpenClaw never installs through mise"
+pass "choosing OpenClaw uses the package and launches its terminal UI"
+
+: >"$terminal_log"
+OMARCHY_TEST_OPENCLAW_INSTALLED=false omarchy-default-agent openclaw
+mapfile -d '' -t terminal_args <"$terminal_log"
+[[ ${terminal_args[*]} == "omarchy-default-agent --install openclaw" ]] ||
+  fail "a missing OpenClaw routes through the install terminal"
+pass "a missing OpenClaw routes through the install terminal"
+
+: >"$stub_log"
+: >"$inline_log"
+OMARCHY_TEST_OPENCLAW_INSTALLED=false omarchy-default-agent --install openclaw >/dev/null
+grep -Fx "pkg-add openclaw" "$stub_log" >/dev/null ||
+  fail "installing OpenClaw as default agent adds its package"
+mapfile -d '' -t inline_args <"$inline_log"
+[[ ${inline_args[*]} == "omarchy-launch-openclaw --tui" ]] ||
+  fail "installing OpenClaw as default agent hands over to its terminal UI"
+pass "installing OpenClaw as default agent adds its package"
+
+: >"$launch_log"
+omarchy agent prompt "Review this project"
+mapfile -d '' -t launch_args <"$launch_log"
+# Element-wise: the prompt must travel as one argv entry, which a space-joined
+# comparison could not tell apart from a prompt split into words.
+[[ ${#launch_args[@]} == 5 &&
+  ${launch_args[0]} == "--app-id=org.omarchy.agent" &&
+  ${launch_args[1]} == "omarchy-launch-openclaw" &&
+  ${launch_args[2]} == "--tui" &&
+  ${launch_args[3]} == "--message" &&
+  ${launch_args[4]} == "Review this project" ]] ||
+  fail "OpenClaw receives prompts through --message" "argv: ${launch_args[*]}"
+pass "OpenClaw receives prompts through --message"
diff --git a/test/shell.d/launch-openclaw-test.sh b/test/shell.d/launch-openclaw-test.sh
new file mode 100755
index 00000000..4c443e07
--- /dev/null
+++ b/test/shell.d/launch-openclaw-test.sh
@@ -0,0 +1,189 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+tmp_dir="$(mktemp -d)"
+trap 'rm -rf "$tmp_dir"' EXIT
+
+mkdir -p "$tmp_dir/bin" "$tmp_dir/home"
+export TEST_LOG="$tmp_dir/log"
+export PATH="$tmp_dir/bin:$PATH"
+export HOME="$tmp_dir/home"
+
+for stub in omarchy-launch-webapp omarchy-launch-floating-terminal-with-presentation omarchy-openclaw-onboard; do
+  cat >"$tmp_dir/bin/$stub" <<SCRIPT
+#!/bin/bash
+printf '$stub:%s\n' "\$*" >>"\$TEST_LOG"
+SCRIPT
+  chmod +x "$tmp_dir/bin/$stub"
+done
+
+# The retry loop sleeps between polls; a no-op keeps the suite fast.
+printf '#!/bin/bash\n' >"$tmp_dir/bin/sleep"
+chmod +x "$tmp_dir/bin/sleep"
+
+# The launcher asks systemd whether the gateway unit is enabled; a flag file
+# stands in for the user manager.
+cat >"$tmp_dir/bin/systemctl" <<SCRIPT
+#!/bin/bash
+printf 'systemctl:%s\\n' "\$*" >>"\$TEST_LOG"
+[[ \$* == *is-enabled* ]] && [[ -f $tmp_dir/gateway-enabled ]]
+SCRIPT
+chmod +x "$tmp_dir/bin/systemctl"
+
+# A machine that never onboarded gets the wizard, not a dashboard probe.
+"$ROOT/bin/omarchy-launch-openclaw"
+
+# Through omarchy-openclaw-onboard, never bare `openclaw onboard`, which as of
+# 2026.9.1 ends in a browser tab with a foreground gateway and never returns.
+grep -q '^omarchy-launch-floating-terminal-with-presentation:omarchy-openclaw-onboard && \[\[ -f \$HOME/.openclaw/openclaw.json \]\] && omarchy-launch-openclaw$' "$TEST_LOG" ||
+  fail "OpenClaw launch hands a never-onboarded machine to the wizard" "$(grep floating "$TEST_LOG")"
+! grep -q '^omarchy-launch-webapp:' "$TEST_LOG" ||
+  fail "OpenClaw launch hands a never-onboarded machine to the wizard" "webapp opened anyway"
+pass "OpenClaw launch hands a never-onboarded machine to the wizard"
+
+mkdir -p "$HOME/.openclaw"
+touch "$HOME/.openclaw/openclaw.json"
+
+# A running gateway answers the first probe; its handoff URL opens as the app.
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+[[ $* == *--json* ]] &&
+  echo '{"ok":true,"url":"http://127.0.0.1:18789/?token=shared","browserUrl":"http://127.0.0.1:18789/#handoff"}'
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+"$ROOT/bin/omarchy-launch-openclaw"
+
+grep -q '^omarchy-launch-webapp:http://127.0.0.1:18789/#handoff$' "$TEST_LOG" ||
+  fail "OpenClaw launch opens the running gateway's handoff URL"
+pass "OpenClaw launch opens the running gateway's handoff URL"
+
+# A machine whose gateway unit was never enabled (never installed, or an
+# install that died after writing the unit) gets `gateway install --force`,
+# then is polled until the dashboard answers. Never `dashboard --yes`: since
+# 2026.9.1 that neither installs nor starts anything and, once the gateway is
+# up, pushes a one-time pairing URL into the clipboard.
+cat >"$tmp_dir/bin/openclaw" <<SCRIPT
+#!/bin/bash
+printf 'openclaw:%s\\n' "\$*" >>"\$TEST_LOG"
+if [[ \$* == *--json* ]]; then
+  [[ -f $tmp_dir/gateway-up ]] || { echo '{"ok":false,"reason":"Gateway is not running."}'; exit 1; }
+  echo '{"ok":true,"browserUrl":"http://127.0.0.1:18789/#cold-start"}'
+elif [[ \$1 == gateway ]]; then
+  touch "$tmp_dir/gateway-up"
+fi
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+rm -f "$tmp_dir/gateway-up" "$tmp_dir/gateway-enabled"
+mkdir -p "$HOME/.config/systemd/user"
+touch "$HOME/.config/systemd/user/openclaw-gateway.service"
+: >"$TEST_LOG"
+"$ROOT/bin/omarchy-launch-openclaw"
+
+grep -q '^openclaw:gateway install --force$' "$TEST_LOG" ||
+  fail "OpenClaw launch installs a never-enabled gateway before opening the app"
+! grep -q '^openclaw:gateway start$' "$TEST_LOG" ||
+  fail "OpenClaw launch installs a never-enabled gateway before opening the app" "started the half-installed unit instead"
+grep -q '^omarchy-launch-webapp:http://127.0.0.1:18789/#cold-start$' "$TEST_LOG" ||
+  fail "OpenClaw launch installs a never-enabled gateway before opening the app" "webapp never opened"
+pass "OpenClaw launch installs a never-enabled gateway before opening the app"
+
+# An enabled but stopped unit is started, not reinstalled.
+touch "$tmp_dir/gateway-enabled"
+rm -f "$tmp_dir/gateway-up"
+: >"$TEST_LOG"
+"$ROOT/bin/omarchy-launch-openclaw"
+
+grep -q '^openclaw:gateway start$' "$TEST_LOG" ||
+  fail "OpenClaw launch starts a stopped gateway before opening the app"
+! grep -q '^openclaw:gateway install' "$TEST_LOG" ||
+  fail "OpenClaw launch starts a stopped gateway before opening the app" "reinstalled the unit"
+! grep -q -- '--yes' "$TEST_LOG" ||
+  fail "OpenClaw launch starts a stopped gateway before opening the app" "fell back to dashboard --yes"
+grep -q '^omarchy-launch-webapp:http://127.0.0.1:18789/#cold-start$' "$TEST_LOG" ||
+  fail "OpenClaw launch starts a stopped gateway before opening the app" "webapp never opened"
+pass "OpenClaw launch starts a stopped gateway before opening the app"
+rm -f "$tmp_dir/gateway-enabled"
+
+# A dashboard probe that hangs is cut off, so the launch still fails cleanly
+# instead of sitting forever behind an app-grid icon with no terminal.
+cat >"$tmp_dir/bin/timeout" <<SCRIPT
+#!/bin/bash
+printf 'timeout:%s\\n' "\$1" >>"\$TEST_LOG"
+exit 124
+SCRIPT
+chmod +x "$tmp_dir/bin/timeout"
+: >"$TEST_LOG"
+rc=0
+"$ROOT/bin/omarchy-launch-openclaw" >/dev/null 2>&1 || rc=$?
+[[ $rc != 0 ]] || fail "OpenClaw launch bounds a hanging dashboard probe"
+grep -q '^timeout:10$' "$TEST_LOG" || fail "OpenClaw launch bounds a hanging dashboard probe" "probe ran without a timeout"
+pass "OpenClaw launch bounds a hanging dashboard probe"
+rm -f "$tmp_dir/bin/timeout"
+
+# A gateway that never answers fails the launch instead of opening a dead page.
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+[[ $* == *--json* ]] && exit 1
+exit 0
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+webapp_calls_before=$(grep -c '^omarchy-launch-webapp:' "$TEST_LOG" || true)
+rc=0
+"$ROOT/bin/omarchy-launch-openclaw" >/dev/null 2>&1 || rc=$?
+webapp_calls_after=$(grep -c '^omarchy-launch-webapp:' "$TEST_LOG" || true)
+
+[[ $rc != 0 ]] || fail "OpenClaw launch fails cleanly when the gateway never comes up"
+[[ $webapp_calls_before == "$webapp_calls_after" ]] ||
+  fail "OpenClaw launch fails cleanly when the gateway never comes up" "webapp opened anyway"
+pass "OpenClaw launch fails cleanly when the gateway never comes up"
+
+# --tui runs onboarding in the terminal it is already in, then attaches to the
+# gateway with `openclaw tui` -- never the embedded chat, which the running
+# gateway's state-directory lock would refuse.
+rm -f "$HOME/.openclaw/openclaw.json"
+cat >"$tmp_dir/bin/omarchy-openclaw-onboard" <<SCRIPT
+#!/bin/bash
+printf 'omarchy-openclaw-onboard:%s\n' "\$*" >>"\$TEST_LOG"
+mkdir -p "\$HOME/.openclaw" && touch "\$HOME/.openclaw/openclaw.json"
+SCRIPT
+chmod +x "$tmp_dir/bin/omarchy-openclaw-onboard"
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+[[ $* == *--json* ]] && echo '{"ok":true,"browserUrl":"http://127.0.0.1:18789/#tui"}'
+exit 0
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+floating_calls_before=$(grep -c '^omarchy-launch-floating-terminal-with-presentation:' "$TEST_LOG" || true)
+"$ROOT/bin/omarchy-launch-openclaw" --tui
+
+grep -q '^omarchy-openclaw-onboard:$' "$TEST_LOG" ||
+  fail "--tui onboards in the current terminal" "$(grep 'onboard' "$TEST_LOG")"
+floating_calls_after=$(grep -c '^omarchy-launch-floating-terminal-with-presentation:' "$TEST_LOG" || true)
+[[ $floating_calls_before == "$floating_calls_after" ]] ||
+  fail "--tui onboards in the current terminal" "spawned a floating terminal"
+grep -q '^openclaw:tui$' "$TEST_LOG" || fail "--tui attaches to the gateway"
+pass "--tui onboards in place and attaches to the gateway"
+
+# The stub also logs argv one entry per line, so a prompt split into words
+# would show up as extra lines rather than pass a space-joined comparison.
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+[[ $1 == tui ]] && printf 'argv:[%s]\n' "$@" >>"$TEST_LOG"
+[[ $* == *--json* ]] && echo '{"ok":true,"browserUrl":"http://127.0.0.1:18789/#tui"}'
+exit 0
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+: >"$TEST_LOG"
+"$ROOT/bin/omarchy-launch-openclaw" --tui --message "Review this project"
+[[ $(grep -c '^argv:' "$TEST_LOG") == 3 ]] && grep -q '^argv:\[Review this project\]$' "$TEST_LOG" ||
+  fail "--tui seeds the session through --message" "$(grep '^argv:' "$TEST_LOG" | tr '\n' ' ')"
+! grep -q '^omarchy-launch-webapp:' "$TEST_LOG" ||
+  fail "--tui seeds the session through --message" "webapp opened instead"
+pass "--tui seeds the session through --message"
diff --git a/test/shell.d/menu-test.sh b/test/shell.d/menu-test.sh
index eb5b3122..3907a8e2 100644
--- a/test/shell.d/menu-test.sh
+++ b/test/shell.d/menu-test.sh
@@ -225,6 +225,7 @@ const expectedAgents = {
   codex: { icon: '\ue905', iconFont: 'omarchy', label: 'Codex' },
   grok: { icon: '\ue904', iconFont: 'omarchy', label: 'Grok' },
   hermes: { icon: '\ue90a', iconFont: 'omarchy', label: 'Hermes' },
+  openclaw: { icon: '\ue90c', iconFont: 'omarchy', label: 'OpenClaw' },
   copilot: { icon: '', label: 'Copilot' },
   crush: { icon: '󰋑', label: 'Crush' },
 }
@@ -245,7 +246,7 @@ assertDeepEqual(
   defaultItems
     .filter(item => item.parent === 'setup.default.agent')
     .map(item => item.label),
-  ['Antigravity', 'Claude', 'Codex', 'Copilot', 'Crush', 'Grok', 'Hermes', 'omp', 'OpenCode', 'Ori', 'Pi'],
+  ['Antigravity', 'Claude', 'Codex', 'Copilot', 'Crush', 'Grok', 'Hermes', 'omp', 'OpenClaw', 'OpenCode', 'Ori', 'Pi'],
   'menu sorts coding agents alphabetically'
 )
 const expectedDefaults = {
@@ -637,5 +638,5 @@ assert(
 JS
 
 font_charset=$(fc-query --format='%{charset}' "$ROOT/default/fonts/omarchy/omarchy.ttf")
-[[ $font_charset == *"e900-e90a"* ]] || fail "Omarchy icon font includes every custom menu glyph"
+[[ $font_charset == *"e900-e90a"* && $font_charset == *"e90c"* ]] || fail "Omarchy icon font includes every custom menu glyph"
 pass "Omarchy icon font includes the official agent marks"
diff --git a/test/shell.d/openclaw-onboard-test.sh b/test/shell.d/openclaw-onboard-test.sh
new file mode 100755
index 00000000..852e3e3d
--- /dev/null
+++ b/test/shell.d/openclaw-onboard-test.sh
@@ -0,0 +1,288 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+tmp_dir="$(mktemp -d)"
+trap 'rm -rf "$tmp_dir"' EXIT
+
+mkdir -p "$tmp_dir/bin" "$tmp_dir/home"
+export TEST_LOG="$tmp_dir/log"
+export PATH="$tmp_dir/bin:$PATH"
+export HOME="$tmp_dir/home"
+export OMARCHY_OPENCLAW_ONBOARD_SETTLE_SECONDS=0
+unit="$HOME/.config/systemd/user/openclaw-gateway.service"
+export unit
+
+# systemd and ss stand in for themselves. Once the wizard has written the unit
+# it is running as pid 4242, and that same process holds the gateway port
+# unless a test plants a different listener (an orphan) in $listener_file.
+listener_file="$tmp_dir/listener"
+export listener_file
+cat >"$tmp_dir/bin/systemctl" <<'SCRIPT'
+#!/bin/bash
+printf 'systemctl:%s\n' "$*" >>"$TEST_LOG"
+if [[ $* == *MainPID* ]]; then
+  [[ -f $unit ]] && echo 4242 || echo 0
+  exit 0
+fi
+[[ $* == *is-active* ]] && [[ -f $unit ]]
+SCRIPT
+chmod +x "$tmp_dir/bin/systemctl"
+cat >"$tmp_dir/bin/ss" <<'SCRIPT'
+#!/bin/bash
+pid=
+[[ -f $listener_file ]] && pid=$(cat "$listener_file")
+[[ -z $pid && -f $unit ]] && pid=4242
+[[ -n $pid ]] && echo "LISTEN 0 511 127.0.0.1:18789 0.0.0.0:* users:((\"node\",pid=$pid,fd=3))"
+exit 0
+SCRIPT
+chmod +x "$tmp_dir/bin/ss"
+export OMARCHY_OPENCLAW_ONBOARD_GATEWAY_TIMEOUT=1
+
+# A wizard that configures OpenClaw, prints its outro, and then lingers forever
+# on an open handle: the 2026.9.1 --skip-ui behaviour. It "installs the
+# gateway" by writing the config a moment in, so the gateway only starts
+# answering partway through, never at once.
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+case $1 in
+onboard)
+  ( sleep 1; mkdir -p "$HOME/.openclaw" "${unit%/*}"; touch "$HOME/.openclaw/openclaw.json" "$unit" ) &
+  trap 'echo terminated >>"$TEST_LOG"; exit 143' TERM
+  while :; do sleep 0.2; done
+  ;;
+dashboard)
+  [[ -f $HOME/.openclaw/openclaw.json ]] && echo '{"ok":true,"port":18789}' || { echo '{"ok":false}'; exit 1; }
+  ;;
+esac
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+
+start=$SECONDS
+rc=0
+"$ROOT/bin/omarchy-openclaw-onboard" </dev/null >/dev/null 2>&1 || rc=$?
+elapsed=$((SECONDS - start))
+
+grep -q '^openclaw:onboard --flow quickstart --install-daemon --skip-ui$' "$TEST_LOG" ||
+  fail "onboarding runs the classic quickstart wizard with the service install" "$(grep '^openclaw:onboard' "$TEST_LOG" || true)"
+pass "onboarding runs the classic quickstart wizard with the service install"
+
+[[ $rc == 0 ]] || fail "a wizard that lingers after the gateway is up is stopped and counts as success" "rc=$rc"
+grep -q '^terminated$' "$TEST_LOG" ||
+  fail "a wizard that lingers after the gateway is up is stopped and counts as success" "wizard was never signalled"
+(( elapsed < 30 )) || fail "a wizard that lingers after the gateway is up is stopped and counts as success" "took ${elapsed}s"
+pass "a wizard that lingers after the gateway is up is stopped and counts as success"
+
+# The wizard only starts being stopped once the gateway actually answers: a
+# stub that never writes the config is left alone and must be ended by its own
+# exit, not the watcher.
+: >"$TEST_LOG"
+rm -rf "$HOME/.openclaw" "$unit" "$listener_file"
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+[[ $1 == onboard ]] && { echo "Skipped for now."; exit 3; }
+echo '{"ok":false}'; exit 1
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+rc=0
+"$ROOT/bin/omarchy-openclaw-onboard" </dev/null >/dev/null 2>&1 || rc=$?
+[[ $rc == 3 ]] || fail "an abandoned wizard passes its exit code through" "rc=$rc"
+[[ ! -f $HOME/.openclaw/openclaw.json ]] || fail "an abandoned wizard passes its exit code through" "config appeared"
+! grep -q '^terminated$' "$TEST_LOG" || fail "an abandoned wizard passes its exit code through" "watcher signalled it anyway"
+pass "an abandoned wizard passes its exit code through"
+
+# A wizard that finishes and exits on its own is simply waited for.
+: >"$TEST_LOG"
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+[[ $1 == onboard ]] && { mkdir -p "$HOME/.openclaw"; touch "$HOME/.openclaw/openclaw.json"; exit 0; }
+echo '{"ok":true,"port":18789}'
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+rc=0
+"$ROOT/bin/omarchy-openclaw-onboard" </dev/null >/dev/null 2>&1 || rc=$?
+[[ $rc == 0 ]] || fail "a wizard that exits cleanly is waited for" "rc=$rc"
+pass "a wizard that exits cleanly is waited for"
+
+# Input reaches the wizard: it runs in the foreground, not backgrounded (which
+# would stop it on SIGTTIN the moment it read stdin).
+: >"$TEST_LOG"
+rm -rf "$HOME/.openclaw" "$unit" "$listener_file"
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+case $1 in
+onboard)
+  read -r answer
+  printf 'answer:%s\n' "$answer" >>"$TEST_LOG"
+  mkdir -p "$HOME/.openclaw"; touch "$HOME/.openclaw/openclaw.json"
+  exit 0
+  ;;
+dashboard) echo '{"ok":true,"port":18789}' ;;
+esac
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+printf 'gpt-5\n' | "$ROOT/bin/omarchy-openclaw-onboard" >/dev/null 2>&1
+grep -q '^answer:gpt-5$' "$TEST_LOG" ||
+  fail "the wizard reads terminal input" "$(grep '^answer' "$TEST_LOG" || echo 'no input reached it')"
+pass "the wizard reads terminal input"
+
+# An already-configured machine whose gateway answers is not onboarded again:
+# the wizard's repair pass would otherwise be stopped mid-prompt the moment
+# the watcher saw the pre-existing gateway.
+: >"$TEST_LOG"
+mkdir -p "$HOME/.openclaw" && touch "$HOME/.openclaw/openclaw.json"
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+[[ $1 == onboard ]] && { echo wizard-ran >>"$TEST_LOG"; exit 0; }
+echo '{"ok":true,"port":18789}'
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+rc=0
+"$ROOT/bin/omarchy-openclaw-onboard" </dev/null >/dev/null 2>&1 || rc=$?
+[[ $rc == 0 ]] || fail "an already-running OpenClaw is left alone" "rc=$rc"
+! grep -q '^wizard-ran$' "$TEST_LOG" || fail "an already-running OpenClaw is left alone" "wizard ran anyway"
+pass "an already-running OpenClaw is left alone"
+
+# Setup applied but the gateway never answers: the wizard would linger
+# forever, so it is stopped after the deadline and that is reported as failure.
+: >"$TEST_LOG"
+rm -rf "$HOME/.openclaw" "$unit" "$listener_file"
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+case $1 in
+onboard)
+  mkdir -p "$HOME/.openclaw"; touch "$HOME/.openclaw/openclaw.json"
+  trap 'echo terminated >>"$TEST_LOG"; exit 143' TERM
+  while :; do sleep 0.2; done
+  ;;
+dashboard) echo '{"ok":false}'; exit 1 ;;
+esac
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+start=$SECONDS
+rc=0
+err=$("$ROOT/bin/omarchy-openclaw-onboard" </dev/null 2>&1 >/dev/null) || rc=$?
+elapsed=$((SECONDS - start))
+[[ $rc == 1 ]] || fail "a gateway that never comes up ends the wait with a failure" "rc=$rc"
+grep -q '^terminated$' "$TEST_LOG" || fail "a gateway that never comes up ends the wait with a failure" "wizard left running"
+[[ $err == *"gateway status"* ]] || fail "a gateway that never comes up ends the wait with a failure" "no diagnostic: $err"
+(( elapsed < 30 )) || fail "a gateway that never comes up ends the wait with a failure" "took ${elapsed}s"
+pass "a gateway that never comes up ends the wait with a failure"
+
+# A signal at this script alone takes the wizard down with it.
+: >"$TEST_LOG"
+rm -rf "$HOME/.openclaw" "$unit" "$listener_file"
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+case $1 in
+onboard) trap 'echo terminated >>"$TEST_LOG"; exit 143' TERM; while :; do sleep 0.2; done ;;
+dashboard) echo '{"ok":false}'; exit 1 ;;
+esac
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+"$ROOT/bin/omarchy-openclaw-onboard" </dev/null >/dev/null 2>&1 &
+wrapper=$!
+sleep 1
+kill -TERM "$wrapper"
+wait "$wrapper" 2>/dev/null || true
+sleep 1
+grep -q '^terminated$' "$TEST_LOG" || fail "stopping the wrapper stops the wizard" "wizard survived"
+! pgrep -f "$tmp_dir/bin/openclaw onboard" >/dev/null || fail "stopping the wrapper stops the wizard" "wizard process still alive"
+pass "stopping the wrapper stops the wizard"
+
+# A config left by an earlier, incomplete setup does not start the gateway
+# deadline: only this run applying setup does. The wizard here takes longer
+# than the deadline at its prompts, never touches the old config, and must be
+# left to finish on its own.
+: >"$TEST_LOG"
+mkdir -p "$HOME/.openclaw" && touch "$HOME/.openclaw/openclaw.json"
+sleep 1
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+case $1 in
+onboard) trap 'echo terminated >>"$TEST_LOG"; exit 143' TERM; sleep 4; echo finished >>"$TEST_LOG"; exit 0 ;;
+dashboard) echo '{"ok":false}'; exit 1 ;;
+esac
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+rc=0
+"$ROOT/bin/omarchy-openclaw-onboard" </dev/null >/dev/null 2>&1 || rc=$?
+[[ $rc == 0 ]] || fail "a stale config does not start the gateway deadline" "rc=$rc"
+grep -q '^finished$' "$TEST_LOG" || fail "a stale config does not start the gateway deadline" "wizard was cut short"
+! grep -q '^terminated$' "$TEST_LOG" || fail "a stale config does not start the gateway deadline" "wizard was signalled"
+pass "a stale config does not start the gateway deadline"
+
+# ...while the same stale config being rewritten by this run does arm it.
+: >"$TEST_LOG"
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+case $1 in
+onboard) touch "$HOME/.openclaw/openclaw.json"; trap 'echo terminated >>"$TEST_LOG"; exit 143' TERM; while :; do sleep 0.2; done ;;
+dashboard) echo '{"ok":false}'; exit 1 ;;
+esac
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+rc=0
+"$ROOT/bin/omarchy-openclaw-onboard" </dev/null >/dev/null 2>&1 || rc=$?
+[[ $rc == 1 ]] || fail "a config rewritten by this run arms the gateway deadline" "rc=$rc"
+grep -q '^terminated$' "$TEST_LOG" || fail "a config rewritten by this run arms the gateway deadline" "wizard left running"
+pass "a config rewritten by this run arms the gateway deadline"
+
+# A gateway that answers while no config exists is not this run's: with no
+# config `openclaw dashboard --json` still probes the default port, so a
+# process left behind by something else (an earlier guided onboarding's
+# foreground gateway) would otherwise end a wizard still at its first prompt.
+: >"$TEST_LOG"
+rm -rf "$HOME/.openclaw" "$unit" "$listener_file"
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+case $1 in
+onboard) trap 'echo terminated >>"$TEST_LOG"; exit 143' TERM; sleep 4; echo finished >>"$TEST_LOG"; exit 0 ;;
+dashboard) echo '{"ok":true,"port":18789}' ;;
+esac
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+rc=0
+"$ROOT/bin/omarchy-openclaw-onboard" </dev/null >/dev/null 2>&1 || rc=$?
+[[ $rc == 0 ]] || fail "an orphaned gateway answering with no config does not end the wizard" "rc=$rc"
+grep -q '^finished$' "$TEST_LOG" || fail "an orphaned gateway answering with no config does not end the wizard" "wizard was cut short"
+! grep -q '^terminated$' "$TEST_LOG" || fail "an orphaned gateway answering with no config does not end the wizard" "wizard was signalled"
+pass "an orphaned gateway answering with no config does not end the wizard"
+
+# And after setup, an orphan still bound to the port is not success even
+# while the unit reports active: Type=simple counts it active from the fork,
+# before it has discovered the port is taken. The port's owner has to be the
+# unit's own main process. Here it never is, so the deadline ends the wait as
+# a failure rather than opening the app on the orphan.
+: >"$TEST_LOG"
+rm -rf "$HOME/.openclaw" "$unit" "$listener_file"
+echo 999 >"$listener_file"
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+case $1 in
+onboard) mkdir -p "$HOME/.openclaw" "${unit%/*}"; touch "$HOME/.openclaw/openclaw.json" "$unit"; trap 'echo terminated >>"$TEST_LOG"; exit 143' TERM; while :; do sleep 0.2; done ;;
+dashboard) echo '{"ok":true,"port":18789}' ;;
+esac
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+rc=0
+"$ROOT/bin/omarchy-openclaw-onboard" </dev/null >/dev/null 2>&1 || rc=$?
+[[ $rc == 1 ]] || fail "an orphan holding the port is not mistaken for the active unit" "rc=$rc"
+grep -q '^terminated$' "$TEST_LOG" || fail "an orphan holding the port is not mistaken for the active unit" "wizard left running"
+grep -q '^systemctl:--user show -p MainPID --value openclaw-gateway.service$' "$TEST_LOG" ||
+  fail "an orphan holding the port is not mistaken for the active unit" "unit ownership never checked"
+pass "an orphan holding the port is not mistaken for the active unit"
+rm -f "$listener_file"
diff --git a/test/shell.d/remove-ai-test.sh b/test/shell.d/remove-ai-test.sh
index 8c7cb153..a10bc3b6 100644
--- a/test/shell.d/remove-ai-test.sh
+++ b/test/shell.d/remove-ai-test.sh
@@ -93,3 +93,161 @@ ollama_row=$(grep '^  "remove.ai.ollama":' "$ROOT/default/omarchy/omarchy-menu.j
 [[ $ollama_row == *'"when":"omarchy-pkg-present ollama"'* ]] ||
   fail "Ollama removal is offered only where the package is installed" "$ollama_row"
 pass "Ollama removal is offered only where the package is installed"
+
+# OpenClaw's gateway unit and web app launcher are the app's own; the agent
+# state in ~/.openclaw is the user's. systemctl and openclaw are stubbed so the
+# sandbox never reaches the real user manager or a real gateway.
+cat >"$tmp_dir/bin/systemctl" <<'SCRIPT'
+#!/bin/bash
+printf 'systemctl:%s\n' "$*" >>"$TEST_LOG"
+SCRIPT
+chmod +x "$tmp_dir/bin/systemctl"
+
+# Default openclaw stub: the packaged CLI predates `gateway uninstall`, so the
+# remover has to fall back to its manual systemd path.
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+exit 1
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+
+fresh_openclaw_home() {
+  fresh_home
+  mkdir -p "$HOME/.config/systemd/user/default.target.wants" "$HOME/.openclaw" \
+    "$HOME/.local/share/applications" "$HOME/.local/share/icons/hicolor/256x256/apps"
+  touch "$HOME/.config/systemd/user/openclaw-gateway.service" \
+    "$HOME/.config/systemd/user/openclaw-gateway.service.bak" \
+    "$HOME/.config/systemd/user/openclaw-node.service" \
+    "$HOME/.openclaw/openclaw.json" \
+    "$HOME/.local/share/applications/OpenClaw.desktop" \
+    "$HOME/.local/share/icons/hicolor/256x256/apps/openclaw.png"
+  ln -s ../openclaw-gateway.service \
+    "$HOME/.config/systemd/user/default.target.wants/openclaw-gateway.service"
+  ln -s ../openclaw-node.service \
+    "$HOME/.config/systemd/user/default.target.wants/openclaw-node.service"
+}
+
+# gum would ask about ~/.openclaw; the tests never run on a terminal, so it
+# must not even be reached. Logging it proves that.
+cat >"$tmp_dir/bin/gum" <<'SCRIPT'
+#!/bin/bash
+printf 'gum:%s\n' "$*" >>"$TEST_LOG"
+exit 0
+SCRIPT
+chmod +x "$tmp_dir/bin/gum"
+
+fresh_openclaw_home
+"$ROOT/bin/omarchy-remove-ai-openclaw" >/dev/null
+
+for gone in .config/systemd/user/openclaw-gateway.service \
+  .config/systemd/user/openclaw-gateway.service.bak \
+  .config/systemd/user/default.target.wants/openclaw-gateway.service \
+  .config/systemd/user/openclaw-node.service \
+  .config/systemd/user/default.target.wants/openclaw-node.service \
+  .local/share/applications/OpenClaw.desktop \
+  .local/share/icons/hicolor/256x256/apps/openclaw.png; do
+  [[ ! -e $HOME/$gone && ! -L $HOME/$gone ]] || fail "OpenClaw removal deletes the service and launcher it installed" "$gone"
+done
+pass "OpenClaw removal deletes the service and launcher it installed"
+
+grep -q '^systemctl:--user disable --now openclaw-gateway.service$' "$TEST_LOG" ||
+  fail "OpenClaw removal stops the gateway service"
+grep -q '^systemctl:--user disable --now openclaw-node.service$' "$TEST_LOG" ||
+  fail "OpenClaw removal stops the gateway service" "node host service left running"
+for unit in openclaw-gateway.service openclaw-node.service; do
+  grep -q "^systemctl:--user reset-failed $unit\$" "$TEST_LOG" ||
+    fail "OpenClaw removal stops the gateway service" "$unit left in systemd's failed list"
+done
+pass "OpenClaw removal stops the gateway service"
+
+# Without a terminal there is nobody to ask, so the state stays and gum is
+# never invoked (a gum that answered "yes" on its own would be a data loss).
+[[ -f $HOME/.openclaw/openclaw.json ]] || fail "OpenClaw removal keeps the user's agent state"
+! grep -q '^gum:' "$TEST_LOG" ||
+  fail "OpenClaw removal keeps the user's agent state" "asked about ~/.openclaw without a terminal"
+pass "OpenClaw removal keeps the user's agent state"
+
+# A CLI that knows `gateway uninstall` owns the teardown; the manual systemd
+# fallback must not run.
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+rm -f "$HOME/.config/systemd/user/openclaw-$1.service" \
+  "$HOME/.config/systemd/user/default.target.wants/openclaw-$1.service"
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+
+: >"$TEST_LOG"
+fresh_openclaw_home
+"$ROOT/bin/omarchy-remove-ai-openclaw" >/dev/null
+
+grep -q '^openclaw:gateway uninstall$' "$TEST_LOG" ||
+  fail "OpenClaw removal prefers upstream's own gateway teardown"
+grep -q '^openclaw:node uninstall$' "$TEST_LOG" ||
+  fail "OpenClaw removal prefers upstream's own gateway teardown" "node host not handed to upstream"
+! grep -q '^systemctl:--user disable' "$TEST_LOG" ||
+  fail "OpenClaw removal prefers upstream's own gateway teardown" "manual disable ran too"
+pass "OpenClaw removal prefers upstream's own gateway teardown"
+
+# Without the unit file there is nothing of ours registered, so systemd stays untouched.
+systemctl_calls_before=$(grep -c '^systemctl:' "$TEST_LOG" || true)
+fresh_home
+"$ROOT/bin/omarchy-remove-ai-openclaw" >/dev/null
+systemctl_calls_after=$(grep -c '^systemctl:' "$TEST_LOG" || true)
+
+[[ $systemctl_calls_before == "$systemctl_calls_after" ]] ||
+  fail "OpenClaw removal leaves systemd alone when onboarding never ran"
+pass "OpenClaw removal leaves systemd alone when onboarding never ran"
+
+# A gateway that will not stop aborts the removal before the package drop:
+# pacman would otherwise strand the live process on deleted code.
+cat >"$tmp_dir/bin/openclaw" <<'SCRIPT'
+#!/bin/bash
+printf 'openclaw:%s\n' "$*" >>"$TEST_LOG"
+exit 1
+SCRIPT
+chmod +x "$tmp_dir/bin/openclaw"
+cat >"$tmp_dir/bin/systemctl" <<'SCRIPT'
+#!/bin/bash
+printf 'systemctl:%s\n' "$*" >>"$TEST_LOG"
+[[ $2 == disable ]] && exit 1
+[[ $2 == is-active ]] && exit 0
+exit 0
+SCRIPT
+chmod +x "$tmp_dir/bin/systemctl"
+
+drop_calls_before=$(grep -c '^drop:openclaw$' "$TEST_LOG" || true)
+fresh_openclaw_home
+rc=0
+"$ROOT/bin/omarchy-remove-ai-openclaw" >/dev/null 2>&1 || rc=$?
+drop_calls_after=$(grep -c '^drop:openclaw$' "$TEST_LOG" || true)
+
+[[ $rc != 0 ]] || fail "OpenClaw removal aborts when the gateway cannot be stopped"
+[[ -f $HOME/.config/systemd/user/openclaw-gateway.service ]] ||
+  fail "OpenClaw removal aborts when the gateway cannot be stopped" "unit file deleted"
+[[ $drop_calls_before == "$drop_calls_after" ]] ||
+  fail "OpenClaw removal aborts when the gateway cannot be stopped" "package dropped anyway"
+pass "OpenClaw removal aborts when the gateway cannot be stopped"
+
+# An unreachable user manager is not a stopped gateway: every probe failing
+# with no answer must still abort, not read as "confirmed inactive".
+cat >"$tmp_dir/bin/systemctl" <<'SCRIPT'
+#!/bin/bash
+printf 'systemctl:%s\n' "$*" >>"$TEST_LOG"
+echo "Failed to connect to user scope bus" >&2
+exit 1
+SCRIPT
+chmod +x "$tmp_dir/bin/systemctl"
+
+: >"$TEST_LOG"
+fresh_openclaw_home
+rc=0
+"$ROOT/bin/omarchy-remove-ai-openclaw" >/dev/null 2>&1 || rc=$?
+
+[[ $rc != 0 ]] || fail "OpenClaw removal aborts when systemd cannot be reached"
+[[ -f $HOME/.config/systemd/user/openclaw-gateway.service ]] ||
+  fail "OpenClaw removal aborts when systemd cannot be reached" "unit file deleted"
+! grep -q '^drop:openclaw$' "$TEST_LOG" ||
+  fail "OpenClaw removal aborts when systemd cannot be reached" "package dropped anyway"
+pass "OpenClaw removal aborts when systemd cannot be reached"

From fa60a8b9bffc2a48707e6e323edd7155914b8852 Mon Sep 17 00:00:00 2001
From: Spencer Bull <spencerbull2554@gmail.com>
Date: Tue, 1 Sep 2026 09:26:38 -0500
Subject: [PATCH 15/27] Add the Perplexity desktop app to Install > AI

Follows the T3 Code / Grok Bot flow: the Install > AI entry runs
omarchy-install-and-launch, so picking it installs the perplexity
package on demand and launches the app when the install finishes.
Remove > AI drops the package along with the app's own config, flags
file, and rpc-server runtime cache, keeping the perplexity-* caches
that belong to Perplexity's other products. Like the Hermes remover,
it sets -u so an unset HOME is a refusal rather than rm -rf paths
rooted at /.

The menu mark is a new U+E90B glyph in the Omarchy icon font, so it
reaches desktops through the next omarchy-settings release.

Co-Authored-By: Fable 5 <noreply@anthropic.com>
Co-Authored-By: Codex XHigh <noreply@openai.com>
---
 bin/omarchy-remove-ai-perplexity   |  21 +++++++++++++++++++++
 default/fonts/omarchy/README.md    |   3 ++-
 default/fonts/omarchy/omarchy.ttf  | Bin 5284 -> 5492 bytes
 default/omarchy/omarchy-menu.jsonc |   2 ++
 manual/17-ai.md                    |   2 +-
 test/shell.d/menu-test.sh          |   2 +-
 test/shell.d/remove-ai-test.sh     |  25 +++++++++++++++++++++++++
 7 files changed, 52 insertions(+), 3 deletions(-)
 create mode 100755 bin/omarchy-remove-ai-perplexity

diff --git a/bin/omarchy-remove-ai-perplexity b/bin/omarchy-remove-ai-perplexity
new file mode 100755
index 00000000..c2388738
--- /dev/null
+++ b/bin/omarchy-remove-ai-perplexity
@@ -0,0 +1,21 @@
+#!/bin/bash
+
+# omarchy:summary=Remove the Perplexity desktop app along with its configuration and 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
+
+# Of the perplexity-* dirs under ~/.cache, only the rpc-server runtime is the
+# desktop app's own download; the rest belong to Perplexity products that
+# outlive the desktop app.
+rm -rf \
+  "$HOME/.config/Perplexity" \
+  "$HOME/.cache/Perplexity" \
+  "$HOME/.cache/perplexity-rpc-server"
+rm -f "$HOME/.config/perplexity-flags.conf"
+
+echo ""
+echo "Perplexity has been removed."
diff --git a/default/fonts/omarchy/README.md b/default/fonts/omarchy/README.md
index a4ab6935..e538684d 100644
--- a/default/fonts/omarchy/README.md
+++ b/default/fonts/omarchy/README.md
@@ -13,7 +13,8 @@ The private-use glyphs in `omarchy.ttf` are:
 - `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+E90C` — OpenClaw, traced from the lobster mascot the openclaw package ships as `dist/control-ui/favicon.svg`, since upstream publishes no monochrome SVG; `E90B` is left for the Perplexity mark already in flight on another branch
+- `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
 
 The agent marks are monochrome so the menu can render them using the active
 theme's foreground and selection colors.
diff --git a/default/fonts/omarchy/omarchy.ttf b/default/fonts/omarchy/omarchy.ttf
index fb9d22a74a6638b60b4f3a701a081a36169fe3db..7a26ed1deacde7f421ccbd80fec05fde1ec369f2 100644
GIT binary patch
delta 610
zcmXYtPiPZC6vn@|n>2qd-6oqf6l+5gQftuSnp!+XJg8Odp`{luu4y#Fu32gh2^8uf
z2Ty8Q@gRbS2vQIU1gcUG#ft?I{DZVu@F0sJ)m&^3qPX!TbROTl`F%6InR$;7?vCCK
zE#egbZEE_+(b*4YPXjc<d?~A|#;4Wf9P=$e7{98OuUyXGd;^GUK<}A+PMtga?8I%L
z-_7U8^K7`u5n|3T$MbrzbPSHK%v=LAS|O_j|AtqYUofY1wPa9|YDl8rVq^Has^{J{
zzTX1^4!-oQQMgg8zWjF)2)^h2syPwV%n8b#b25pY5-dK6hajFoW9)WTDbC)m?|{L1
z0DbJZp(2YsbQCa;auZE&(`OC~k%+J9Z@1f3jz{hLZIk0pn8NO`$Gjj6N`Rkh0Q|1*
z@R=o{;PC-X7J_w4kg1+<)b=g9uz-wM;r0X&LIgvI@#pxJ6q6HjEbUCkBt>$j6*(a(
zQ6=qEl4AOJR7yxLSxzLSa3C6%6|th(cFMLjjf4~p%-YY_?Y@<jLzcZor#9%z#)f8Z
zStm*P)%ezE?NEh0t;TlC{u5tbeqv+NvOjvMXEVFByJ_#N(GP2~+Z0li{S9|wX??0k
z?)<}Hl6YW@+m~TIVCj474tMl)FKe7@tZCMQ`CA-yyW-u7vN=S9_0Q5zBH4T$7!jz~
T+zy=gdyU+@q2)@~ie>x<=@_4a

delta 412
zcmZ9GKS%;m9LK-!-I;MI)p=Qzkc35w6l6q1L$pK?I2h6BW!6D=os@%44lPYlJgI1E
zXp9nWX)vKV8iK~AhRSFNa|jyjr(-<6zu)_Qet+JpM=rvL{(?3Qz>FuxCsrO87Xa4u
z$&{sM%JX~6<evaOv}xuy`fJZ$fE)t6B_pk`k6q0iP;Z$uWe{j*atGb(q>y1{bBe-O
zY5tV_tZAoo?YHX$kbcNVEIpTDBdmlNSRaAlwr-^#-d>A9H$BMiGxl!w=B4ru_|B<*
z3`UW~Vy@&?L}+T<t+a?HKGXpbW@{X>xZ{Hb8JNQvEQ-x@NitDFf~H+0i4-MK8;Y$B
zU;(1d?NQ1~i_0)5`_V<D4LVZfE!fyWzKW_+^)wn(|IZn5@y#^J4Mu<I?etI+u-}S+
mA||=*TyvF)AeY6hI_y*=$LqL!pNwgurj3d~&k_fY%H|(ssa*B|

diff --git a/default/omarchy/omarchy-menu.jsonc b/default/omarchy/omarchy-menu.jsonc
index a82254c6..d824319e 100644
--- a/default/omarchy/omarchy-menu.jsonc
+++ b/default/omarchy/omarchy-menu.jsonc
@@ -245,6 +245,7 @@
   "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.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-install-and-launch 'T3 Code' t3code-bin t3code"},
   "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"},
@@ -311,6 +312,7 @@
   "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"},
diff --git a/manual/17-ai.md b/manual/17-ai.md
index f94c3546..8a9c5852 100644
--- a/manual/17-ai.md
+++ b/manual/17-ai.md
@@ -44,7 +44,7 @@ Crashes can also be silenced one program at a time, which is what the diagnosis
 
 ### Desktop apps
 
-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, and OpenClaw.
+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. Removing the app under _Remove > AI_ takes that runtime with it, and keeps your chats, memories, and the skills Hermes wrote for itself.
 
diff --git a/test/shell.d/menu-test.sh b/test/shell.d/menu-test.sh
index 3907a8e2..c65ec000 100644
--- a/test/shell.d/menu-test.sh
+++ b/test/shell.d/menu-test.sh
@@ -638,5 +638,5 @@ assert(
 JS
 
 font_charset=$(fc-query --format='%{charset}' "$ROOT/default/fonts/omarchy/omarchy.ttf")
-[[ $font_charset == *"e900-e90a"* && $font_charset == *"e90c"* ]] || fail "Omarchy icon font includes every custom menu glyph"
+[[ $font_charset == *"e900-e90c"* ]] || fail "Omarchy icon font includes every custom menu glyph"
 pass "Omarchy icon font includes the official agent marks"
diff --git a/test/shell.d/remove-ai-test.sh b/test/shell.d/remove-ai-test.sh
index a10bc3b6..99558353 100644
--- a/test/shell.d/remove-ai-test.sh
+++ b/test/shell.d/remove-ai-test.sh
@@ -75,6 +75,31 @@ for kept in .grok .claude.json .npm .local/share/opencode; do
 done
 pass "T3 Code removal keeps the agent state it bootstrapped"
 
+# Perplexity's other products (the CLI, Comet) share the perplexity-* cache
+# prefix; only the rpc-server runtime is the desktop app's own.
+fresh_home
+mkdir -p "$HOME/.config/Perplexity" "$HOME/.cache/Perplexity" "$HOME/.cache/perplexity-rpc-server" "$HOME/.cache/perplexity-personal-computer-poc"
+touch "$HOME/.config/perplexity-flags.conf"
+"$ROOT/bin/omarchy-remove-ai-perplexity" >/dev/null
+
+for gone in .config/Perplexity .cache/Perplexity .cache/perplexity-rpc-server .config/perplexity-flags.conf; do
+  [[ ! -e $HOME/$gone ]] || fail "Perplexity removal deletes the desktop app's own data" "$gone"
+done
+pass "Perplexity removal deletes the desktop app's own data"
+
+[[ -d $HOME/.cache/perplexity-personal-computer-poc ]] || fail "Perplexity removal keeps other Perplexity products' caches"
+pass "Perplexity removal keeps other Perplexity products' caches"
+
+grep -qx 'drop:perplexity' "$TEST_LOG" || fail "Perplexity removal drops the perplexity package"
+pass "Perplexity removal drops the perplexity package"
+
+# Without HOME the rm -rf paths would degrade to /-rooted ones; -u makes that a
+# refusal instead.
+if env -u HOME "$ROOT/bin/omarchy-remove-ai-perplexity" >/dev/null 2>&1; then
+  fail "Perplexity removal refuses to run without HOME"
+fi
+pass "Perplexity removal refuses to run without HOME"
+
 # ~/.grok belongs to the Grok CLI that omarchy-default-agent installs.
 fresh_home
 mkdir -p "$HOME/.config/Grok Bot" "$HOME/.grokbot" "$HOME/.grok"

From 36e56f4fb463547dd877849bd3bd951410c442e9 Mon Sep 17 00:00:00 2001
From: David Heinemeier Hansson <david@hey.com>
Date: Sat, 5 Sep 2026 20:05:04 +0200
Subject: [PATCH 16/27] Drop tests for shipped one-shot migrations (#10318)

Keep the migrations themselves for late-updaters. Drop the tests that only
exercised frozen file rewrites from 4.0.0, and keep live invariants,
privileged repairs, and the migrator.
---
 agents/skills/migrations.md                   |   2 +
 docs/testing.md                               |   7 +-
 test/cli                                      |  95 ----------
 test/shell.d/agents-default-migration-test.sh | 113 ------------
 test/shell.d/bluetooth-migration-test.sh      | 109 ------------
 test/shell.d/config-test.sh                   |  45 +----
 test/shell.d/limine-cmdline-migration-test.sh | 111 ------------
 test/shell.d/limine-defaults-test.sh          |  11 ++
 .../network-manager-transition-test.sh        |   8 -
 test/shell.d/nvidia-kms-migration-test.sh     | 131 --------------
 .../sleep-lock-environment-migration-test.sh  | 162 ------------------
 test/shell.d/systemd-test.sh                  |  16 +-
 .../terminal-keybinding-migration-test.sh     |  59 -------
 test/shell.d/zram-migration-test.sh           | 104 -----------
 14 files changed, 26 insertions(+), 947 deletions(-)
 delete mode 100755 test/shell.d/agents-default-migration-test.sh
 delete mode 100644 test/shell.d/bluetooth-migration-test.sh
 delete mode 100644 test/shell.d/limine-cmdline-migration-test.sh
 create mode 100644 test/shell.d/limine-defaults-test.sh
 delete mode 100755 test/shell.d/nvidia-kms-migration-test.sh
 delete mode 100755 test/shell.d/sleep-lock-environment-migration-test.sh
 delete mode 100644 test/shell.d/terminal-keybinding-migration-test.sh
 delete mode 100644 test/shell.d/zram-migration-test.sh

diff --git a/agents/skills/migrations.md b/agents/skills/migrations.md
index b8152b43..5ed1d489 100644
--- a/agents/skills/migrations.md
+++ b/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.
diff --git a/docs/testing.md b/docs/testing.md
index 3928ed2b..bcd3b4af 100644
--- a/docs/testing.md
+++ b/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.
diff --git a/test/cli b/test/cli
index 80b981d5..1643d2db 100755
--- a/test/cli
+++ b/test/cli
@@ -519,101 +519,6 @@ expected_background="$THEME_TMPDIR/.local/state/omarchy/current/theme/background
 [[ ! -e $THEME_TMPDIR/.config/omarchy/current ]] || fail "headless theme set avoids config current state"
 pass "headless theme set creates current background symlink"
 
-make_tmpdir MIGRATION_TMPDIR
-mkdir -p \
-  "$MIGRATION_TMPDIR/.config/omarchy/current/theme" \
-  "$MIGRATION_TMPDIR/.config/alacritty" \
-  "$MIGRATION_TMPDIR/.config/hypr" \
-  "$MIGRATION_TMPDIR/.config/hyprland-preview-share-picker" \
-  "$MIGRATION_TMPDIR/.config/btop/themes"
-printf 'tokyo-night\n' >"$MIGRATION_TMPDIR/.config/omarchy/current/theme.name"
-printf 'x\n' >"$MIGRATION_TMPDIR/.config/omarchy/current/theme/colors.toml"
-printf 'general.import = [ "~/.config/omarchy/current/theme/alacritty.toml" ]\n' >"$MIGRATION_TMPDIR/.config/alacritty/alacritty.toml"
-printf 'stylesheets: ["../omarchy/current/theme/hyprland-preview-share-picker.css"]\n' >"$MIGRATION_TMPDIR/.config/hyprland-preview-share-picker/config.yaml"
-cat >"$MIGRATION_TMPDIR/.config/hypr/hyprland.lua" <<'LUA'
-package.path = os.getenv("HOME")
-  .. "/.config/?.lua;"
-  .. (os.getenv("OMARCHY_PATH") or "/usr/share/omarchy")
-  .. "/?.lua;"
-  .. package.path
-LUA
-ln -s "$MIGRATION_TMPDIR/.config/omarchy/current/theme/btop.theme" "$MIGRATION_TMPDIR/.config/btop/themes/current.theme"
-HOME="$MIGRATION_TMPDIR" bash -euo pipefail "$ROOT/migrations/1781043107.sh" >/dev/null
-[[ -f $MIGRATION_TMPDIR/.local/state/omarchy/current/theme.name ]] || fail "current theme migration moves theme name"
-[[ ! -e $MIGRATION_TMPDIR/.config/omarchy/current ]] || fail "current theme migration removes legacy config state"
-grep -Fq '~/.local/state/omarchy/current/theme/alacritty.toml' "$MIGRATION_TMPDIR/.config/alacritty/alacritty.toml" || fail "current theme migration updates alacritty import"
-grep -Fq '../../.local/state/omarchy/current/theme/hyprland-preview-share-picker.css' "$MIGRATION_TMPDIR/.config/hyprland-preview-share-picker/config.yaml" || fail "current theme migration updates relative stylesheet"
-grep -Fq '/.local/state/?.lua;' "$MIGRATION_TMPDIR/.config/hypr/hyprland.lua" || fail "current theme migration keeps Hyprland theme modules discoverable"
-[[ $(readlink "$MIGRATION_TMPDIR/.config/btop/themes/current.theme") == "$MIGRATION_TMPDIR/.local/state/omarchy/current/theme/btop.theme" ]] || fail "current theme migration updates btop symlink"
-pass "current theme migration moves state and rewrites shipped references"
-
-make_tmpdir NVIM_MIGRATION_TMPDIR
-nvim_theme_link="$NVIM_MIGRATION_TMPDIR/.config/nvim/lua/plugins/theme.lua"
-nvim_expected_target="../../../../.local/state/omarchy/current/theme/neovim.lua"
-nvim_expected_resolved_target="$NVIM_MIGRATION_TMPDIR/.local/state/omarchy/current/theme/neovim.lua"
-mkdir -p \
-  "$(dirname "$nvim_theme_link")" \
-  "$NVIM_MIGRATION_TMPDIR/.config/omarchy/current/theme" \
-  "$NVIM_MIGRATION_TMPDIR/.local/state/omarchy/current/theme"
-touch "$NVIM_MIGRATION_TMPDIR/.local/state/omarchy/current/theme/neovim.lua"
-for nvim_legacy_target in \
-  "../../../omarchy/current/theme/neovim.lua" \
-  "$NVIM_MIGRATION_TMPDIR/.config/omarchy/current/theme/neovim.lua"; do
-  ln -sfn "$nvim_legacy_target" "$nvim_theme_link"
-  HOME="$NVIM_MIGRATION_TMPDIR" bash -euo pipefail "$ROOT/migrations/1781158082.sh" >/dev/null
-  nvim_actual_target=$(readlink "$nvim_theme_link")
-  nvim_resolved_target=$(readlink -f "$nvim_theme_link")
-  [[ $nvim_actual_target == $nvim_expected_target ]] || fail "nvim theme migration updates theme symlink"
-  [[ $nvim_resolved_target == $nvim_expected_resolved_target ]] || fail "nvim theme migration points to current theme"
-done
-pass "nvim theme migration relinks current theme"
-
-for nvim_legacy_target in \
-  "../../../omarchy/current/theme/neovim.lua" \
-  "../../../../.config/omarchy/current/theme/neovim.lua" \
-  "~/.config/omarchy/current/theme/neovim.lua" \
-  "$NVIM_MIGRATION_TMPDIR/.config/omarchy/current/theme/neovim.lua"; do
-  ln -sfn "$nvim_legacy_target" "$nvim_theme_link"
-  HOME="$NVIM_MIGRATION_TMPDIR" bash -euo pipefail "$ROOT/migrations/1785002349.sh" >/dev/null
-  nvim_actual_target=$(readlink "$nvim_theme_link")
-  nvim_resolved_target=$(readlink -f "$nvim_theme_link")
-  [[ $nvim_actual_target == $nvim_expected_target ]] || fail "nvim theme repair migration updates $nvim_legacy_target"
-  [[ $nvim_resolved_target == $nvim_expected_resolved_target ]] || fail "nvim theme repair migration points to current theme"
-done
-
-HOME="$NVIM_MIGRATION_TMPDIR" bash -euo pipefail "$ROOT/migrations/1785002349.sh" >/dev/null
-[[ $(readlink "$nvim_theme_link") == $nvim_expected_target ]] || fail "nvim theme repair migration is idempotent"
-
-touch "$NVIM_MIGRATION_TMPDIR/custom-theme.lua"
-ln -sfn "../../../../custom-theme.lua" "$nvim_theme_link"
-HOME="$NVIM_MIGRATION_TMPDIR" bash -euo pipefail "$ROOT/migrations/1785002349.sh" >/dev/null
-[[ $(readlink "$nvim_theme_link") == "../../../../custom-theme.lua" ]] || fail "nvim theme repair migration leaves custom symlinks alone"
-pass "nvim theme repair migration relinks every legacy spelling"
-
-make_tmpdir HYPR_MIGRATION_TMPDIR
-mkdir -p "$HYPR_MIGRATION_TMPDIR/.config/hypr"
-cat >"$HYPR_MIGRATION_TMPDIR/.config/hypr/hyprland.lua" <<'LUA'
--- Learn how to configure Hyprland: https://wiki.hypr.land/Configuring/Start/
-
--- Load user modules from ~/.config and Omarchy defaults from $OMARCHY_PATH.
-package.path = os.getenv("HOME")
-  .. "/.config/?.lua;"
-  .. (os.getenv("OMARCHY_PATH") or (os.getenv("HOME") .. "/.local/share/omarchy"))
-  .. "/?.lua;"
-  .. package.path
-
--- All Omarchy default setups
-require("default.hypr.omarchy")
-
--- Add any other personal Hyprland configuration below.
-o.window("Example", { workspace = "1" })
-LUA
-HOME="$HYPR_MIGRATION_TMPDIR" bash -euo pipefail "$ROOT/migrations/1781063758.sh" >/dev/null
-grep -Fq 'dofile((os.getenv("OMARCHY_PATH") or "/usr/share/omarchy") .. "/default/hypr/bootstrap.lua")' "$HYPR_MIGRATION_TMPDIR/.config/hypr/hyprland.lua" || fail "hyprland bootstrap migration adds bootstrap"
-! grep -Fq 'package.path = os.getenv("HOME")' "$HYPR_MIGRATION_TMPDIR/.config/hypr/hyprland.lua" || fail "hyprland bootstrap migration removes legacy path block"
-grep -Fq 'o.window("Example", { workspace = "1" })' "$HYPR_MIGRATION_TMPDIR/.config/hypr/hyprland.lua" || fail "hyprland bootstrap migration preserves custom config"
-pass "hyprland bootstrap migration updates stale user entrypoint"
-
 cp "$NEXT_THEME/colors.toml" "$CURRENT_THEME/colors.toml"
 cp "$NEXT_THEME/vscode-theme.json" "$CURRENT_THEME/vscode-theme.json"
 
diff --git a/test/shell.d/agents-default-migration-test.sh b/test/shell.d/agents-default-migration-test.sh
deleted file mode 100755
index 319893a6..00000000
--- a/test/shell.d/agents-default-migration-test.sh
+++ /dev/null
@@ -1,113 +0,0 @@
-#!/bin/bash
-
-set -euo pipefail
-
-source "$(dirname "$0")/base-test.sh"
-
-require_command jq
-
-migration="$ROOT/migrations/1785344985.sh"
-test_dir=$(mktemp -d)
-trap 'rm -rf "$test_dir"' EXIT
-
-mkdir -p "$test_dir/bin"
-
-cat >"$test_dir/bin/omarchy-restart-shell" <<'STUB'
-#!/bin/bash
-
-echo restart >>"$SHELL_RESTARTS"
-STUB
-
-chmod +x "$test_dir/bin/"*
-
-export SHELL_RESTARTS="$test_dir/shell-restarts"
-
-home="$test_dir/home"
-config="$home/.config/omarchy/shell.json"
-
-run_migration() {
-  : >"$SHELL_RESTARTS"
-  HOME="$home" PATH="$test_dir/bin:$PATH" bash -euo pipefail "$migration" >/dev/null
-}
-
-# The shipped default minus the widget is what every machine installed before
-# this migration has on disk.
-write_config() {
-  rm -rf "$home"
-  mkdir -p "$home/.config/omarchy"
-  jq "${1:-.}" "$ROOT/config/omarchy/shell.json" >"$config"
-}
-
-without_widget='del(.bar.layout[][] | select((if type == "object" then .id else . end) == "omarchy.agents"))'
-
-ids() {
-  jq -c --arg section "$1" '[.bar.layout[$section][]? | if type == "object" then .id else . end]' "$config"
-}
-
-# ------------------------------------------------------------------ shipped default
-
-jq -e '[.bar.layout.right[].id] | index("omarchy.agents")' "$ROOT/config/omarchy/shell.json" >/dev/null ||
-  fail "shipped config puts the agents widget in the bar"
-pass "shipped config puts the agents widget in the bar"
-
-# ------------------------------------------------------------------ placement
-
-write_config "$without_widget"
-run_migration
-
-[[ $(ids right) == '["omarchy.tray","omarchy.agents","omarchy.bluetooth","omarchy.network","omarchy.audio","omarchy.monitor","omarchy.power"]' ]] ||
-  fail "migration inserts the agents widget after the tray" "$(ids right)"
-pass "migration inserts the agents widget after the tray"
-
-(($(wc -l <"$SHELL_RESTARTS") == 0)) || fail "migration leaves the shell restart to omarchy update"
-pass "migration leaves the shell restart to omarchy update"
-
-before=$(sha256sum "$config")
-run_migration
-[[ $before == $(sha256sum "$config") ]] || fail "migration is idempotent" "$(ids right)"
-pass "migration is idempotent"
-
-# ------------------------------------------------------------------ curated bars
-
-# A user who already placed the widget keeps it exactly where they put it, in
-# whichever section, and never gets a second copy.
-write_config "$without_widget | .bar.layout.center += [{ id: \"omarchy.agents\" }]"
-run_migration
-
-[[ $(ids center) == *'"omarchy.agents"'* ]] || fail "migration leaves a user-placed widget alone" "$(ids center)"
-[[ $(ids right) != *'"omarchy.agents"'* ]] || fail "migration does not add a second copy" "$(ids right)"
-pass "migration respects a widget the user already placed"
-
-# Layouts written before entries grew options are bare id strings.
-write_config "$without_widget | .bar.layout.right = [\"omarchy.tray\", \"omarchy.agents\", \"omarchy.power\"]"
-run_migration
-
-[[ $(ids right) == '["omarchy.tray","omarchy.agents","omarchy.power"]' ]] ||
-  fail "migration reads string-form entries" "$(ids right)"
-pass "migration reads string-form entries"
-
-# A tray dropped from the right section must not strand the widget or drop it.
-write_config "$without_widget | del(.bar.layout.right[] | select(.id == \"omarchy.tray\"))"
-run_migration
-
-[[ $(ids right) == '["omarchy.agents",'* ]] || fail "migration places the widget without a tray" "$(ids right)"
-pass "migration places the widget without a tray"
-
-# ------------------------------------------------------------------ everything else
-
-write_config "$without_widget"
-cp "$config" "$test_dir/before.json"
-run_migration
-
-diff <(jq -S 'del(.bar.layout.right)' "$test_dir/before.json") <(jq -S 'del(.bar.layout.right)' "$config") >/dev/null ||
-  fail "migration touches nothing but the right section" "$(diff <(jq -S . "$test_dir/before.json") <(jq -S . "$config"))"
-pass "migration touches nothing but the right section"
-
-# A config the migration cannot parse is left alone rather than truncated.
-rm -rf "$home"
-mkdir -p "$home/.config/omarchy"
-printf '{ not json' >"$config"
-run_migration
-
-[[ $(cat "$config") == '{ not json' ]] || fail "migration leaves an unparsable config untouched" "$(cat "$config")"
-pass "migration leaves an unparsable config untouched"
diff --git a/test/shell.d/bluetooth-migration-test.sh b/test/shell.d/bluetooth-migration-test.sh
deleted file mode 100644
index 95d5b116..00000000
--- a/test/shell.d/bluetooth-migration-test.sh
+++ /dev/null
@@ -1,109 +0,0 @@
-#!/bin/bash
-
-set -euo pipefail
-
-source "$(dirname "$0")/base-test.sh"
-
-migration="$ROOT/migrations/1786380259.sh"
-test_dir=$(mktemp -d)
-trap 'rm -rf "$test_dir"' EXIT
-
-mkdir -p "$test_dir/bin"
-
-# sudo runs the real command, so sed acts on the redirected main.conf below and
-# the elevated power calls land in the stub beside it.
-cat >"$test_dir/bin/sudo" <<'STUB'
-#!/bin/bash
-
-printf 'sudo %s\n' "$*" >>"$CALLS"
-exec "$@"
-STUB
-
-cat >"$test_dir/bin/omarchy-bluetooth-power" <<'STUB'
-#!/bin/bash
-
-printf 'omarchy-bluetooth-power %s\n' "$*" >>"$CALLS"
-[[ $1 == "is-on" ]] || exit 0
-[[ ${POWERED:-} == "yes" ]]
-STUB
-
-chmod +x "$test_dir/bin/"*
-
-export CALLS="$test_dir/calls"
-
-marker="$test_dir/marker"
-main_conf="$test_dir/main.conf"
-
-reset_machine() {
-  rm -f "$marker"
-  printf '[Policy]\nAutoEnable=false\n' >"$main_conf"
-}
-
-run_migration() {
-  : >"$CALLS"
-
-  OMARCHY_BLUETOOTH_MIGRATION_MARKER="$marker" \
-    OMARCHY_BLUETOOTH_MAIN_CONF="$main_conf" \
-    PATH="$test_dir/bin:$PATH" \
-    bash -euo pipefail "$migration" >/dev/null
-}
-
-# An adapter that is powered right now is one the user turned on, so it stays on.
-reset_machine
-POWERED=yes run_migration
-
-grep -qx 'omarchy-bluetooth-power on' "$CALLS" ||
-  fail "migration keeps a powered adapter on" "$(cat "$CALLS")"
-pass "migration keeps a powered adapter on"
-
-grep -qx '#AutoEnable=true' "$main_conf" ||
-  fail "migration puts AutoEnable back to its default" "$(cat "$main_conf")"
-pass "migration puts AutoEnable back to its default"
-
-[[ -e $marker ]] || fail "migration records the machine as done"
-pass "migration records the machine as done"
-
-# Anything else is a machine that has been booting with Bluetooth off, and the
-# block is what carries that over now AutoEnable no longer holds the adapter down.
-reset_machine
-POWERED=no run_migration
-
-grep -qx 'omarchy-bluetooth-power off' "$CALLS" ||
-  fail "migration carries an unpowered adapter over to the block" "$(cat "$CALLS")"
-pass "migration carries an unpowered adapter over to the block"
-
-# No daemon to ask reads the same way: off is what the machine has been doing.
-reset_machine
-run_migration
-
-grep -qx 'omarchy-bluetooth-power off' "$CALLS" ||
-  fail "migration blocks when no adapter can be read" "$(cat "$CALLS")"
-pass "migration blocks when no adapter can be read"
-
-# /dev/rfkill is only writable unelevated from an active graphical seat, so an
-# update run over SSH would abort here and abort again on every retry.
-grep -qx 'sudo omarchy-bluetooth-power off' "$CALLS" ||
-  fail "migration changes the radio through sudo" "$(cat "$CALLS")"
-pass "migration changes the radio through sudo"
-
-# A second account must not undo an administrator's later choice, since migration
-# completion is recorded per user.
-printf '[Policy]\nAutoEnable=false\n' >"$main_conf"
-POWERED=yes run_migration
-
-grep -qx 'AutoEnable=false' "$main_conf" ||
-  fail "migration leaves a later opt-out alone" "$(cat "$main_conf")"
-pass "migration leaves a later opt-out alone"
-
-[[ ! -s $CALLS ]] ||
-  fail "migration touches no radio state on a second run" "$(cat "$CALLS")"
-pass "migration touches no radio state on a second run"
-
-# Only the exact line Omarchy wrote is reverted, so a hand-edited opt-out stands.
-reset_machine
-printf '[Policy]\nAutoEnable = false\n' >"$main_conf"
-POWERED=yes run_migration
-
-grep -qx 'AutoEnable = false' "$main_conf" ||
-  fail "migration keeps a hand-edited AutoEnable" "$(cat "$main_conf")"
-pass "migration keeps a hand-edited AutoEnable"
diff --git a/test/shell.d/config-test.sh b/test/shell.d/config-test.sh
index 3add6e30..320ee0c8 100755
--- a/test/shell.d/config-test.sh
+++ b/test/shell.d/config-test.sh
@@ -38,6 +38,15 @@ jq -e '
 ' "$ROOT/config/omarchy/shell.json" >/dev/null
 pass "default clock date format has no leading zero"
 
+jq -e '
+  def ids: map(.id // .);
+  (.bar.layout.right | ids) as $ids |
+  ($ids | index("omarchy.tray")) as $tray |
+  ($ids | index("omarchy.agents")) as $agents |
+  $tray != null and $agents == $tray + 1
+' "$ROOT/config/omarchy/shell.json" >/dev/null
+pass "default right layout keeps agents next to the tray"
+
 ROOT="$ROOT" python3 <<'PY'
 import json
 import os
@@ -418,39 +427,3 @@ if grep -RIl 'upgrade-to-quattro\|Omarchy 4\.0 is upgraded' "$ROOT/migrations" >
   fail "4.0 upgrade is not modeled as a migration"
 fi
 pass "4.0 upgrade is handled outside the migration runner"
-
-clock_migration=$(grep -rl 'Remove leading zero from bar clock date' "$ROOT/migrations" | head -n 1 || true)
-[[ -n $clock_migration ]] || fail "clock date format user migration exists"
-
-cat >"$TMPDIR/home/.config/omarchy/shell.json" <<'JSON'
-{
-  "version": 1,
-  "bar": {
-    "layout": {
-      "left": [],
-      "center": [
-        { "id": "omarchy.clock", "formatAlt": "dd MMMM 'W'ww yyyy" },
-        { "id": "omarchy.weather" }
-      ],
-      "right": [
-        { "id": "local.clock", "formatAlt": "dd MMMM 'W'ww yyyy" }
-      ]
-    }
-  },
-  "plugins": []
-}
-JSON
-
-HOME="$TMPDIR/home" OMARCHY_PATH="$ROOT" bash "$clock_migration"
-
-jq -e '
-  .bar.layout.center[0].formatAlt == "d MMMM \u0027W\u0027ww yyyy" and
-  .bar.layout.right[0].formatAlt == "dd MMMM \u0027W\u0027ww yyyy"
-' "$TMPDIR/home/.config/omarchy/shell.json" >/dev/null
-pass "clock date format migration removes leading zero from clock"
-
-before=$(sha256sum "$TMPDIR/home/.config/omarchy/shell.json" | awk '{print $1}')
-HOME="$TMPDIR/home" OMARCHY_PATH="$ROOT" bash "$clock_migration"
-after=$(sha256sum "$TMPDIR/home/.config/omarchy/shell.json" | awk '{print $1}')
-[[ $before == "$after" ]] || fail "clock date format migration is idempotent"
-pass "clock date format migration is idempotent"
diff --git a/test/shell.d/limine-cmdline-migration-test.sh b/test/shell.d/limine-cmdline-migration-test.sh
deleted file mode 100644
index 404dc7ce..00000000
--- a/test/shell.d/limine-cmdline-migration-test.sh
+++ /dev/null
@@ -1,111 +0,0 @@
-#!/bin/bash
-
-set -euo pipefail
-
-source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
-
-migration="$ROOT/migrations/1786482992.sh"
-packaged_defaults="$ROOT/etc/limine-entry-tool.d/omarchy-defaults.conf"
-
-grep -Fq 'KERNEL_CMDLINE[default]+=" initramfs_async=0"' "$packaged_defaults" ||
-  fail "the packaged Limine defaults still unpack the initramfs synchronously"
-pass "packaged Limine defaults keep Plymouth alive at the LUKS prompt"
-
-test_tmp=$(mktemp -d)
-trap 'rm -rf "$test_tmp"' EXIT
-
-stub_bin="$test_tmp/bin"
-calls="$test_tmp/calls.log"
-mkdir -p "$stub_bin"
-: >"$calls"
-
-cat >"$stub_bin/omarchy-cmd-present" <<'SH'
-#!/bin/bash
-
-(( ${LIMINE_MKINITCPIO_INSTALLED:-1} == 1 ))
-SH
-
-cat >"$stub_bin/sudo" <<'SH'
-#!/bin/bash
-
-printf 'sudo' >>"$TEST_LOG"
-printf '\t%s' "$@" >>"$TEST_LOG"
-printf '\n' >>"$TEST_LOG"
-"$@"
-SH
-
-cat >"$stub_bin/limine-mkinitcpio" <<'SH'
-#!/bin/bash
-
-echo 'limine-mkinitcpio' >>"$TEST_LOG"
-SH
-
-chmod +x "$stub_bin"/*
-
-defaults_conf="$test_tmp/omarchy-defaults.conf"
-running_cmdline="$test_tmp/cmdline"
-rebuild_marker="$test_tmp/rebuild-complete"
-
-cp "$packaged_defaults" "$defaults_conf"
-
-# A boot image baked before quattro's defaults landed: the pre-quattro command
-# line plus the machine's own root parameters, and none of the new ones.
-stale_cmdline='quiet splash cryptdevice=PARTUUID=fake:root root=/dev/mapper/root rw'
-
-# Everything the packaged defaults ask for, as a rebuilt image would carry it.
-configured=$(sed -n 's/^KERNEL_CMDLINE\[default\]+="\(.*\)"[[:space:]]*$/\1/p' "$defaults_conf" | tr '\n' ' ')
-current_cmdline="cryptdevice=PARTUUID=fake:root root=/dev/mapper/root rw $configured"
-
-run_migration() {
-  PATH="$stub_bin:$PATH" \
-    TEST_LOG="$calls" \
-    OMARCHY_LIMINE_DEFAULTS_CONF="$defaults_conf" \
-    OMARCHY_RUNNING_CMDLINE="$running_cmdline" \
-    OMARCHY_LIMINE_REBUILD_MARKER="$rebuild_marker" \
-    bash -euo pipefail "$migration" >/dev/null
-}
-
-echo "$stale_cmdline" >"$running_cmdline"
-run_migration
-
-grep -Fxq 'limine-mkinitcpio' "$calls" ||
-  fail "a boot image older than the Limine defaults is rebuilt"
-[[ -f $rebuild_marker ]] || fail "the rebuild records the machine-wide repair"
-pass "migration rebuilds a boot image that predates the Limine defaults"
-
-: >"$calls"
-run_migration
-
-[[ ! -s $calls ]] || fail "a recorded rebuild is not repeated" "$(cat "$calls")"
-pass "migration is machine-idempotent before reboot"
-
-rm -f "$rebuild_marker"
-: >"$calls"
-run_migration
-
-grep -Fxq 'limine-mkinitcpio' "$calls" ||
-  fail "an interrupted rebuild is retried"
-[[ -f $rebuild_marker ]] || fail "a retried rebuild records completion"
-pass "migration retries an interrupted rebuild"
-
-echo "$current_cmdline" >"$running_cmdline"
-rm -f "$rebuild_marker"
-: >"$calls"
-run_migration
-
-[[ ! -s $calls ]] || fail "a boot image matching the defaults is left alone" "$(cat "$calls")"
-[[ ! -e $rebuild_marker ]] || fail "an untouched machine is not marked as repaired"
-pass "migration skips a boot image that already carries the defaults"
-
-echo "$stale_cmdline" >"$running_cmdline"
-: >"$calls"
-LIMINE_MKINITCPIO_INSTALLED=0 run_migration
-
-[[ ! -s $calls ]] || fail "installs without limine-mkinitcpio are skipped" "$(cat "$calls")"
-
-mv "$defaults_conf" "$defaults_conf.away"
-run_migration
-mv "$defaults_conf.away" "$defaults_conf"
-
-[[ ! -s $calls ]] || fail "installs without the Limine defaults are skipped" "$(cat "$calls")"
-pass "migration skips installs it does not apply to"
diff --git a/test/shell.d/limine-defaults-test.sh b/test/shell.d/limine-defaults-test.sh
new file mode 100644
index 00000000..e4c420ff
--- /dev/null
+++ b/test/shell.d/limine-defaults-test.sh
@@ -0,0 +1,11 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+packaged_defaults="$ROOT/etc/limine-entry-tool.d/omarchy-defaults.conf"
+
+grep -Fq 'KERNEL_CMDLINE[default]+=" initramfs_async=0"' "$packaged_defaults" ||
+  fail "the packaged Limine defaults still unpack the initramfs synchronously"
+pass "packaged Limine defaults keep Plymouth alive at the LUKS prompt"
diff --git a/test/shell.d/network-manager-transition-test.sh b/test/shell.d/network-manager-transition-test.sh
index 44154a64..f8769f0c 100644
--- a/test/shell.d/network-manager-transition-test.sh
+++ b/test/shell.d/network-manager-transition-test.sh
@@ -6,7 +6,6 @@ source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
 
 dns="$ROOT/bin/omarchy-dns"
 hardware_network="$ROOT/install/hardware/network.sh"
-migration="$ROOT/migrations/1782002156.sh"
 
 ! grep -F 'systemd-networkd' "$dns" >/dev/null || fail "omarchy-dns no longer restarts systemd-networkd"
 grep -F 'NetworkManager/conf.d/20-omarchy-dns.conf' "$dns" >/dev/null
@@ -26,10 +25,3 @@ grep -F 'systemd-networkd.socket' "$hardware_network" >/dev/null
 grep -F '20-wlan.network' "$hardware_network" >/dev/null
 grep -F 'omarchy-networkd-retired' "$hardware_network" >/dev/null
 pass "hardware setup retires archinstall networkd state"
-
-grep -F 'OMARCHY_UPGRADE_TO_QUATTRO_LIVE' "$migration" >/dev/null
-grep -F 'systemctl disable --now "$unit"' "$migration" >/dev/null
-grep -F 'systemctl stop systemd-networkd.service' "$migration" >/dev/null
-grep -F 'NetworkManager.service' "$migration" >/dev/null
-grep -F '20-wlan.network' "$migration" >/dev/null
-pass "migration repairs upgraded systems with networkd still active"
diff --git a/test/shell.d/nvidia-kms-migration-test.sh b/test/shell.d/nvidia-kms-migration-test.sh
deleted file mode 100755
index 998487ad..00000000
--- a/test/shell.d/nvidia-kms-migration-test.sh
+++ /dev/null
@@ -1,131 +0,0 @@
-#!/bin/bash
-
-set -euo pipefail
-
-source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
-
-migration="$ROOT/migrations/1786605598.sh"
-packaged_hooks="$ROOT/etc/mkinitcpio.conf.d/omarchy_hooks.conf"
-
-test_tmp=$(mktemp -d)
-trap 'rm -rf "$test_tmp"' EXIT
-
-stub_bin="$test_tmp/bin"
-calls="$test_tmp/calls.log"
-mkdir -p "$stub_bin"
-: >"$calls"
-
-cat >"$stub_bin/omarchy-cmd-present" <<'SH'
-#!/bin/bash
-
-(( ${LIMINE_MKINITCPIO_INSTALLED:-1} == 1 ))
-SH
-
-cat >"$stub_bin/sudo" <<'SH'
-#!/bin/bash
-
-printf 'sudo' >>"$TEST_LOG"
-printf '\t%s' "$@" >>"$TEST_LOG"
-printf '\n' >>"$TEST_LOG"
-"$@"
-SH
-
-cat >"$stub_bin/limine-mkinitcpio" <<'SH'
-#!/bin/bash
-
-echo 'limine-mkinitcpio' >>"$TEST_LOG"
-SH
-
-chmod +x "$stub_bin"/*
-
-hooks_conf="$test_tmp/omarchy_hooks.conf"
-nvidia_conf="$test_tmp/nvidia.conf"
-rebuild_marker="$test_tmp/rebuild-complete"
-
-cp "$packaged_hooks" "$hooks_conf"
-echo 'MODULES+=(nvidia nvidia_modeset nvidia_uvm nvidia_drm)' >"$nvidia_conf"
-
-# Each argument is a PCI device as "vendor:class", in sysfs's own format.
-write_pci_devices() {
-  rm -rf "$test_tmp/devices"
-  mkdir -p "$test_tmp/devices"
-
-  local index=0
-  local spec
-  for spec in "$@"; do
-    local slot
-    slot=$(printf '0000:%02x:00.0' "$index")
-    mkdir -p "$test_tmp/devices/$slot"
-    printf '%s\n' "${spec%%:*}" >"$test_tmp/devices/$slot/vendor"
-    printf '%s\n' "${spec##*:}" >"$test_tmp/devices/$slot/class"
-    index=$((index + 1))
-  done
-}
-
-run_migration() {
-  PATH="$stub_bin:$PATH" \
-    TEST_LOG="$calls" \
-    OMARCHY_MKINITCPIO_HOOKS_CONF="$hooks_conf" \
-    OMARCHY_MKINITCPIO_NVIDIA_CONF="$nvidia_conf" \
-    OMARCHY_KMS_REBUILD_MARKER="$rebuild_marker" \
-    OMARCHY_PCI_DEVICES_PATH="$test_tmp/devices" \
-    bash -euo pipefail "$migration" >/dev/null
-}
-
-# NVIDIA-only machine with the proprietary driver: the packaged conditional
-# drops kms, so the stale initramfs must be rebuilt once.
-write_pci_devices 0x10de:0x030000
-run_migration
-
-grep -Fxq 'limine-mkinitcpio' "$calls" ||
-  fail "an NVIDIA-only machine rebuilds its initramfs"
-[[ -f $rebuild_marker ]] || fail "the rebuild records the machine-wide repair"
-pass "migration rebuilds the initramfs on an NVIDIA-only machine"
-
-: >"$calls"
-run_migration
-
-[[ ! -s $calls ]] || fail "a recorded rebuild is not repeated" "$(cat "$calls")"
-pass "migration is machine-idempotent across users"
-
-rm -f "$rebuild_marker"
-: >"$calls"
-run_migration
-
-grep -Fxq 'limine-mkinitcpio' "$calls" ||
-  fail "an interrupted rebuild is retried"
-pass "migration retries an interrupted rebuild"
-
-# Hybrid machine: the conditional keeps kms, so the initramfs already matches.
-write_pci_devices 0x1002:0x030000 0x10de:0x030200
-rm -f "$rebuild_marker"
-: >"$calls"
-run_migration
-
-[[ ! -s $calls ]] || fail "a hybrid machine is left alone" "$(cat "$calls")"
-[[ ! -e $rebuild_marker ]] || fail "an untouched machine is not marked as repaired"
-pass "migration skips a hybrid machine that keeps kms"
-
-# A user-edited hooks conf predating the conditional (the packaged update sits
-# in a .pacnew) still carries kms unconditionally: nothing to rebuild for.
-write_pci_devices 0x10de:0x030000
-echo 'HOOKS=(base udev autodetect modconf kms block filesystems fsck)' >"$hooks_conf"
-: >"$calls"
-run_migration
-
-[[ ! -s $calls ]] || fail "a user-edited hooks conf is left alone" "$(cat "$calls")"
-pass "migration skips a hooks conf without the conditional"
-
-cp "$packaged_hooks" "$hooks_conf"
-
-: >"$calls"
-LIMINE_MKINITCPIO_INSTALLED=0 run_migration
-
-[[ ! -s $calls ]] || fail "installs without limine-mkinitcpio are skipped" "$(cat "$calls")"
-
-mv "$nvidia_conf" "$nvidia_conf.away"
-run_migration
-mv "$nvidia_conf.away" "$nvidia_conf"
-
-[[ ! -s $calls ]] || fail "machines without the proprietary NVIDIA driver are skipped" "$(cat "$calls")"
-pass "migration skips installs it does not apply to"
diff --git a/test/shell.d/sleep-lock-environment-migration-test.sh b/test/shell.d/sleep-lock-environment-migration-test.sh
deleted file mode 100755
index e778c1c0..00000000
--- a/test/shell.d/sleep-lock-environment-migration-test.sh
+++ /dev/null
@@ -1,162 +0,0 @@
-#!/bin/bash
-
-set -euo pipefail
-
-source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
-
-test_tmp=$(mktemp -d)
-trap 'rm -rf "$test_tmp"' EXIT
-
-stub_bin="$test_tmp/bin"
-mkdir -p "$stub_bin"
-
-cat >"$stub_bin/systemctl" <<'STUB'
-#!/bin/bash
-
-printf '%s\n' "$*" >>"$SYSTEMCTL_CALLS"
-
-case "$*" in
-  '--user show-environment')
-    [[ ${MANAGER_AVAILABLE:-true} == "true" ]]
-    ;;
-  '--user daemon-reload')
-    if [[ ${FAIL_SYSTEMCTL_ACTION:-} == "daemon-reload" ]]; then
-      echo "reload failed" >&2
-      exit 1
-    fi
-    ;;
-  '--user show --property=ActiveState --value graphical-session.target')
-    if [[ ${FAIL_SYSTEMCTL_ACTION:-} == "show-graphical" ]]; then
-      echo "state lookup failed" >&2
-      exit 1
-    fi
-    printf '%s\n' "${GRAPHICAL_STATE:-inactive}"
-    ;;
-  '--user show --property=ActiveState --value omarchy-sleep-lock.service')
-    printf '%s\n' "${SLEEP_LOCK_STATE:-inactive}"
-    ;;
-  '--user restart omarchy-sleep-lock.service')
-    if [[ ${FAIL_SYSTEMCTL_ACTION:-} == "restart" ]]; then
-      echo "restart failed" >&2
-      exit 1
-    fi
-    ;;
-  '--user stop omarchy-sleep-lock.service')
-    if [[ ${FAIL_SYSTEMCTL_ACTION:-} == "stop" ]]; then
-      echo "stop failed" >&2
-      exit 1
-    fi
-    ;;
-  '--user reset-failed omarchy-sleep-lock.service') ;;
-  *) exit 1 ;;
-esac
-STUB
-chmod +x "$stub_bin/systemctl"
-
-migration="$ROOT/migrations/1785608166.sh"
-
-run_migration() {
-  local home="$1" calls="$2"
-  shift 2
-
-  mkdir -p "$home/run"
-  HOME="$home" XDG_CONFIG_HOME="$home/.config" XDG_RUNTIME_DIR="$home/run" \
-    SYSTEMCTL_CALLS="$calls" PATH="$stub_bin:$PATH" \
-    "$@" bash -euo pipefail "$migration"
-}
-
-active_home="$test_tmp/active-home"
-active_calls="$test_tmp/active-calls"
-mkdir -p "$active_home/.config/systemd/user"
-printf '%s\n' '[Service]' 'ExecStart=/usr/bin/omarchy-system-sleep-monitor' \
-  >"$active_home/.config/systemd/user/omarchy-sleep-lock.service"
-
-run_migration "$active_home" "$active_calls" \
-  env GRAPHICAL_STATE=active SLEEP_LOCK_STATE=active >/dev/null
-
-dropin="$active_home/.config/systemd/user/omarchy-sleep-lock.service.d/90-omarchy-session-environment.conf"
-grep -Fx 'After=dbus.socket wayland-session-waitenv.service' "$dropin" >/dev/null ||
-  fail "sleep lock migration orders a retained unit after the session environment import"
-grep -Fx 'PartOf=graphical-session.target' "$dropin" >/dev/null ||
-  fail "sleep lock migration ties a retained unit to the graphical session lifecycle"
-grep -Fx 'ConditionEnvironment=OMARCHY_PATH' "$dropin" >/dev/null ||
-  fail "sleep lock migration gates a retained unit on the Omarchy path"
-grep -Fx 'ConditionEnvironment=WAYLAND_DISPLAY' "$dropin" >/dev/null ||
-  fail "sleep lock migration gates a retained unit on the Wayland display"
-pass "sleep lock migration repairs retained full-unit overrides with a drop-in"
-
-grep -Fx -- '--user daemon-reload' "$active_calls" >/dev/null ||
-  fail "sleep lock migration reloads the live user manager"
-grep -Fx -- '--user reset-failed omarchy-sleep-lock.service' "$active_calls" >/dev/null ||
-  fail "sleep lock migration cannot recover a start-limited monitor"
-grep -Fx -- '--user restart omarchy-sleep-lock.service' "$active_calls" >/dev/null ||
-  fail "sleep lock migration leaves an active monitor with its inherited environment"
-grep -Fx -- '--user stop omarchy-sleep-lock.service' "$active_calls" >/dev/null &&
-  fail "sleep lock migration stops the monitor inside an active graphical session"
-pass "sleep lock migration replaces the monitor inside an active graphical session"
-
-inactive_home="$test_tmp/inactive-home"
-inactive_calls="$test_tmp/inactive-calls"
-mkdir -p "$inactive_home"
-
-run_migration "$inactive_home" "$inactive_calls" \
-  env GRAPHICAL_STATE=inactive >/dev/null
-
-grep -Fx -- '--user stop omarchy-sleep-lock.service' "$inactive_calls" >/dev/null ||
-  fail "sleep lock migration leaves a stale monitor running after logout"
-grep -Fx -- '--user restart omarchy-sleep-lock.service' "$inactive_calls" >/dev/null &&
-  fail "sleep lock migration starts the monitor outside a graphical session"
-pass "sleep lock migration stops a monitor left behind after logout"
-
-failed_calls="$test_tmp/failed-calls"
-if run_migration "$test_tmp/failed-home" "$failed_calls" \
-  env GRAPHICAL_STATE=active SLEEP_LOCK_STATE=active FAIL_SYSTEMCTL_ACTION=restart \
-  >"$test_tmp/failed-output" 2>&1; then
-  fail "sleep lock migration marks a failed active-session repair complete"
-fi
-grep -F 'will be retried by omarchy-migrate' "$test_tmp/failed-output" >/dev/null ||
-  fail "sleep lock migration does not explain that a failed repair remains pending"
-pass "sleep lock migration keeps an active-session repair failure retryable"
-
-reload_failed_calls="$test_tmp/reload-failed-calls"
-if run_migration "$test_tmp/reload-failed-home" "$reload_failed_calls" \
-  env FAIL_SYSTEMCTL_ACTION=daemon-reload >"$test_tmp/reload-failed-output" 2>&1; then
-  fail "sleep lock migration ignores a failed user-manager reload"
-fi
-grep -F 'Could not reload the user service manager' "$test_tmp/reload-failed-output" >/dev/null ||
-  fail "sleep lock migration does not report a failed user-manager reload"
-pass "sleep lock migration keeps a failed user-manager reload retryable"
-
-stop_failed_calls="$test_tmp/stop-failed-calls"
-if run_migration "$test_tmp/stop-failed-home" "$stop_failed_calls" \
-  env GRAPHICAL_STATE=inactive FAIL_SYSTEMCTL_ACTION=stop \
-  >"$test_tmp/stop-failed-output" 2>&1; then
-  fail "sleep lock migration ignores a stale monitor that could not be stopped"
-fi
-grep -F 'Could not stop stale omarchy-sleep-lock.service' "$test_tmp/stop-failed-output" >/dev/null ||
-  fail "sleep lock migration does not report a stale monitor stop failure"
-pass "sleep lock migration keeps a stale-monitor stop failure retryable"
-
-state_failed_calls="$test_tmp/state-failed-calls"
-if run_migration "$test_tmp/state-failed-home" "$state_failed_calls" \
-  env FAIL_SYSTEMCTL_ACTION=show-graphical >"$test_tmp/state-failed-output" 2>&1; then
-  fail "sleep lock migration ignores a failed session-state inspection"
-fi
-grep -F 'Could not inspect graphical-session.target' "$test_tmp/state-failed-output" >/dev/null ||
-  fail "sleep lock migration does not report a failed session-state inspection"
-pass "sleep lock migration keeps an indeterminate session repair retryable"
-
-deferred_home="$test_tmp/deferred-home"
-deferred_calls="$test_tmp/deferred-calls"
-mkdir -p "$deferred_home/.config/systemd/user"
-touch "$deferred_home/.config/systemd/user/omarchy-sleep-lock.service"
-
-run_migration "$deferred_home" "$deferred_calls" \
-  env MANAGER_AVAILABLE=false >/dev/null
-
-[[ -f $deferred_home/.config/systemd/user/omarchy-sleep-lock.service.d/90-omarchy-session-environment.conf ]] ||
-  fail "sleep lock migration does not persist the repair without a live user manager"
-deferred_call_count=$(wc -l <"$deferred_calls")
-(( deferred_call_count == 1 )) ||
-  fail "sleep lock migration tries to mutate a user manager that is not running"
-pass "sleep lock migration defers safely when no user manager is running"
diff --git a/test/shell.d/systemd-test.sh b/test/shell.d/systemd-test.sh
index 7d4f67c7..ce7b79b7 100755
--- a/test/shell.d/systemd-test.sh
+++ b/test/shell.d/systemd-test.sh
@@ -71,14 +71,6 @@ grep -Fx 'WantedBy=graphical-session.target' "$fcitx_service" >/dev/null ||
 grep -Fx 'ConditionEnvironment=WAYLAND_DISPLAY' "$fcitx_service" >/dev/null ||
   fail "an update over SSH has a live user manager and no display; starting fcitx5 there wedges the unit active-but-blind, and Wants= will not replace it at graphical login"
 
-fcitx_migration="$ROOT/migrations/1785167800.sh"
-grep -F 'is-active --quiet graphical-session.target' "$fcitx_migration" >/dev/null ||
-  fail "migration kills fcitx5 and starts the unit outside a graphical session"
-grep -F 'systemctl --user enable omarchy-fcitx5.service' "$fcitx_migration" >/dev/null ||
-  fail "migration must enable without --now; --now starts the unit before the session-gate check"
-grep -F 'Could not start omarchy-fcitx5.service' "$fcitx_migration" >/dev/null ||
-  fail "migration pkills a working fcitx5, so a failed handover must be reported instead of marked complete"
-
 grep -F 'pkill -x fcitx5' "$ROOT/bin/omarchy-restart-xcompose" >/dev/null ||
   fail "restart-xcompose cannot reload a fcitx5 running outside the unit, so it silently keeps serving the old table"
 
@@ -111,10 +103,4 @@ pass "systemd-oomd acts on sustained memory stall"
 
 grep -Fx 'systemctl enable systemd-oomd.service' "$ROOT/install/config/enable-services.sh" >/dev/null ||
   fail "new installs ship the oomd drop-ins with the daemon that reads them disabled"
-
-oomd_migration=$(grep -rl 'systemd-oomd.service' "$ROOT/migrations" | head -n 1 || true)
-[[ -n $oomd_migration ]] ||
-  fail "existing installs never enable systemd-oomd; enable-services.sh only runs at install time"
-grep -F 'systemctl --user daemon-reload' "$oomd_migration" >/dev/null ||
-  fail "migration leaves the user manager unaware of app.slice candidacy until the next login"
-pass "existing installs enable systemd-oomd and report app.slice without a relogin"
+pass "new installs enable systemd-oomd"
diff --git a/test/shell.d/terminal-keybinding-migration-test.sh b/test/shell.d/terminal-keybinding-migration-test.sh
deleted file mode 100644
index 04a4c373..00000000
--- a/test/shell.d/terminal-keybinding-migration-test.sh
+++ /dev/null
@@ -1,59 +0,0 @@
-#!/bin/bash
-
-source "$(dirname "${BASH_SOURCE[0]}")/base-test.sh"
-
-migration=$(grep -rl 'Make Shift+Enter distinguishable for terminals and Codex' "$ROOT/migrations" | head -n 1 || true)
-[[ -n $migration ]] || fail "terminal Shift+Enter migration exists"
-
-TMPDIR=$(mktemp -d)
-trap 'rm -rf "$TMPDIR"' EXIT
-
-test_home="$TMPDIR/home"
-mkdir -p \
-  "$test_home/.config/alacritty" \
-  "$test_home/.config/foot" \
-  "$test_home/.config/ghostty" \
-  "$test_home/.config/kitty"
-
-cp "$ROOT/config/alacritty/alacritty.toml" "$test_home/.config/alacritty/alacritty.toml"
-sed -i 's/\\u001B\[13;2u/\\u001B\\r/' "$test_home/.config/alacritty/alacritty.toml"
-
-cp "$ROOT/config/kitty/kitty.conf" "$test_home/.config/kitty/kitty.conf"
-sed -i '/shift+enter/d' "$test_home/.config/kitty/kitty.conf"
-
-cp "$ROOT/config/ghostty/config" "$test_home/.config/ghostty/config"
-sed -i '/shift+enter/d' "$test_home/.config/ghostty/config"
-
-cp "$ROOT/config/foot/foot.ini" "$test_home/.config/foot/foot.ini"
-sed -i '/text-bindings/,$d' "$test_home/.config/foot/foot.ini"
-
-HOME="$test_home" bash "$migration" >/dev/null
-
-grep -qxF '{ key = "Return", mods = "Shift", chars = "\u001B[13;2u" },' "$test_home/.config/alacritty/alacritty.toml" ||
-  fail "migration updates Alacritty Shift+Return to CSI-u"
-pass "migration updates Alacritty Shift+Return to CSI-u"
-
-grep -qxF 'map shift+enter send_text all \e[13;2u' "$test_home/.config/kitty/kitty.conf" ||
-  fail "migration adds Kitty Shift+Enter CSI-u binding"
-grep -qxF 'map alt+shift+enter send_text all \e[13;4u' "$test_home/.config/kitty/kitty.conf" ||
-  fail "migration adds Kitty Alt+Shift+Enter CSI-u binding"
-pass "migration adds Kitty CSI-u bindings"
-
-grep -qxF 'keybind = shift+enter=csi:13;2u' "$test_home/.config/ghostty/config" ||
-  fail "migration adds Ghostty Shift+Enter CSI-u binding"
-grep -qxF 'keybind = alt+shift+enter=csi:13;4u' "$test_home/.config/ghostty/config" ||
-  fail "migration adds Ghostty Alt+Shift+Enter CSI-u binding"
-pass "migration adds Ghostty CSI-u bindings"
-
-grep -qxF '\x1b[13;2u=Shift+Return' "$test_home/.config/foot/foot.ini" ||
-  fail "migration adds Foot Shift+Return CSI-u binding"
-grep -qxF '\x1b[13;4u=Mod1+Shift+Return' "$test_home/.config/foot/foot.ini" ||
-  fail "migration adds Foot Alt+Shift+Return CSI-u binding"
-pass "migration adds Foot CSI-u bindings"
-
-before=$(find "$test_home/.config" -type f -print0 | sort -z | xargs -0 sha256sum)
-HOME="$test_home" bash "$migration" >/dev/null
-after=$(find "$test_home/.config" -type f -print0 | sort -z | xargs -0 sha256sum)
-
-[[ $before == "$after" ]] || fail "terminal Shift+Enter migration is idempotent"
-pass "terminal Shift+Enter migration is idempotent"
diff --git a/test/shell.d/zram-migration-test.sh b/test/shell.d/zram-migration-test.sh
deleted file mode 100644
index cf54c30f..00000000
--- a/test/shell.d/zram-migration-test.sh
+++ /dev/null
@@ -1,104 +0,0 @@
-#!/bin/bash
-
-source "$(dirname "${BASH_SOURCE[0]}")/base-test.sh"
-
-migration=$(grep -rl 'Move zram tuning to a vendor drop-in' "$ROOT/migrations" | head -n 1 || true)
-[[ -n $migration ]] || fail "zram drop-in migration exists"
-
-TMPDIR=$(mktemp -d)
-trap 'rm -rf "$TMPDIR"' EXIT
-
-# The migration shells out to pacman (ownership check) and sudo (removal).
-# Stub both so the test never touches the real system, and let each case pick
-# what `pacman -Qo` reports through PACMAN_OWNS.
-stub_bin="$TMPDIR/bin"
-mkdir -p "$stub_bin"
-
-cat >"$stub_bin/pacman" <<'STUB'
-#!/bin/bash
-[[ ${PACMAN_OWNS:-0} == 1 ]]
-STUB
-
-cat >"$stub_bin/sudo" <<'STUB'
-#!/bin/bash
-exec "$@"
-STUB
-
-chmod +x "$stub_bin/pacman" "$stub_bin/sudo"
-
-# The migration removes the /etc copy only once the drop-in that replaces it is
-# installed. Point that at a fixture so the result does not depend on whether
-# the machine running the tests happens to carry the real one.
-dropin="$TMPDIR/90-omarchy.conf"
-: >"$dropin"
-
-# omarchy-migrate runs each migration with `bash -euo pipefail` and stops the
-# whole chain on a non-zero exit, so match that invocation exactly.
-run_migration() {
-  local conf="$1"
-  PATH="$stub_bin:$PATH" OMARCHY_ZRAM_CONF="$conf" OMARCHY_ZRAM_DROPIN="$dropin" \
-    bash -euo pipefail "$migration" >/dev/null ||
-    fail "migration exits clean for $(basename "$conf")"
-}
-
-# archinstall's own output: a [zram0] section with nothing but the algorithm.
-conf="$TMPDIR/archinstall.conf"
-printf '[zram0]\ncompression-algorithm = zstd\n' >"$conf"
-run_migration "$conf"
-[[ -f $conf ]] && fail "migration removes archinstall's generated config"
-pass "migration removes archinstall's generated config"
-
-# Same shape, different algorithm, plus comments and blank lines.
-conf="$TMPDIR/commented.conf"
-printf '# written by archinstall\n\n[zram0]\ncompression-algorithm = lz4\n\n' >"$conf"
-run_migration "$conf"
-[[ -f $conf ]] && fail "migration ignores comments and a non-zstd algorithm"
-pass "migration ignores comments and a non-zstd algorithm"
-
-# A config that sets nothing decides nothing, and must not take the migration
-# chain down with it.
-conf="$TMPDIR/comments-only.conf"
-printf '# nothing to see here\n\n' >"$conf"
-run_migration "$conf"
-[[ -f $conf ]] && fail "migration removes a config that sets nothing"
-pass "migration removes a config that sets nothing"
-
-conf="$TMPDIR/empty.conf"
-: >"$conf"
-run_migration "$conf"
-[[ -f $conf ]] && fail "migration removes an empty config"
-pass "migration removes an empty config"
-
-# A local override must survive.
-conf="$TMPDIR/local.conf"
-printf '[zram0]\ncompression-algorithm = zstd\nzram-size = ram / 4\n' >"$conf"
-run_migration "$conf"
-[[ -f $conf ]] || fail "migration keeps a locally edited config"
-pass "migration keeps a locally edited config"
-
-# Package-owned copies go away with their package; the migration must not touch
-# them.
-conf="$TMPDIR/owned.conf"
-printf '[zram0]\ncompression-algorithm = zstd\n' >"$conf"
-PATH="$stub_bin:$PATH" PACMAN_OWNS=1 OMARCHY_ZRAM_CONF="$conf" OMARCHY_ZRAM_DROPIN="$dropin" \
-  bash -euo pipefail "$migration" >/dev/null ||
-  fail "migration exits clean for a package-owned config"
-[[ -f $conf ]] || fail "migration keeps a package-owned config"
-pass "migration keeps a package-owned config"
-
-# Nothing to do, and running twice must stay clean.
-conf="$TMPDIR/absent.conf"
-run_migration "$conf"
-run_migration "$conf"
-pass "migration no-ops when the config is already gone"
-
-# Without the drop-in installed, the /etc copy is the only thing configuring
-# zram at all. Removing it would leave the machine with no zram device, so the
-# migration has to leave it alone and stay clean doing it.
-conf="$TMPDIR/no-dropin.conf"
-printf '[zram0]\ncompression-algorithm = zstd\n' >"$conf"
-PATH="$stub_bin:$PATH" OMARCHY_ZRAM_CONF="$conf" OMARCHY_ZRAM_DROPIN="$TMPDIR/absent-dropin.conf" \
-  bash -euo pipefail "$migration" >/dev/null ||
-  fail "migration exits clean when the drop-in is missing"
-[[ -f $conf ]] || fail "migration keeps the config when the drop-in is missing"
-pass "migration keeps the config until the drop-in is installed"

From eea678b480c31b93c93593fa6733eaddb8bb1f23 Mon Sep 17 00:00:00 2001
From: Spencer Bull <spencer@omarchy.org>
Date: Sat, 5 Sep 2026 08:59:46 -0500
Subject: [PATCH 17/27] Ask, default no, before Remove Perplexity deletes the
 user's data

Perplexity 26.9.1 keeps the secret vault and device identity in
~/.local/state/perplexity and its runtime downloads in
~/.local/share/perplexity-rpc-server; the remover knew neither path, so
it deleted the logins unconditionally while leaving the credentials
behind. Now the runtime and Electron caches always go, and the logins,
vault, and launcher flags go only on an explicit yes at a terminal,
default no, the same choice Remove OpenClaw puts in front of the user.
The prompt needs stderr on the terminal too: gum draws it there, so a
redirected stderr means keeping the data, not blocking on a question
nobody can see.

Co-Authored-By: Codex XHigh <noreply@openai.com>
Co-Authored-By: Sonnet 5 <noreply@anthropic.com>
---
 bin/omarchy-remove-ai-perplexity | 42 +++++++++++---
 test/shell.d/remove-ai-test.sh   | 97 ++++++++++++++++++++++++++++----
 2 files changed, 120 insertions(+), 19 deletions(-)

diff --git a/bin/omarchy-remove-ai-perplexity b/bin/omarchy-remove-ai-perplexity
index c2388738..93859484 100755
--- a/bin/omarchy-remove-ai-perplexity
+++ b/bin/omarchy-remove-ai-perplexity
@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# omarchy:summary=Remove the Perplexity desktop app along with its configuration and caches.
+# 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 /.
@@ -8,14 +8,42 @@ set -euo pipefail
 
 omarchy-pkg-drop perplexity
 
-# Of the perplexity-* dirs under ~/.cache, only the rpc-server runtime is the
-# desktop app's own download; the rest belong to Perplexity products that
-# outlive the desktop app.
+# 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/.config/Perplexity" \
   "$HOME/.cache/Perplexity" \
-  "$HOME/.cache/perplexity-rpc-server"
-rm -f "$HOME/.config/perplexity-flags.conf"
+  "$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
diff --git a/test/shell.d/remove-ai-test.sh b/test/shell.d/remove-ai-test.sh
index 99558353..9d518318 100644
--- a/test/shell.d/remove-ai-test.sh
+++ b/test/shell.d/remove-ai-test.sh
@@ -15,6 +15,22 @@ printf 'drop:%s\n' "$*" >>"$TEST_LOG"
 SCRIPT
 chmod +x "$tmp_dir/bin/omarchy-pkg-drop"
 
+# omarchy-remove-ai-perplexity asks through gum whether the user's data goes
+# too. The stub answers "no" unless a test says otherwise and logs the call: a
+# real gum would hang the run, and one that answered "yes" on its own would be
+# the data loss the default-no exists to prevent. It logs to its own file
+# because the OpenClaw section below greps TEST_LOG to prove gum was never
+# reached, and the pty runs here call it on purpose.
+cat >"$tmp_dir/bin/gum" <<'SCRIPT'
+#!/bin/bash
+printf 'gum:%s\n' "$*" >>"$TEST_GUM_LOG"
+exit "${TEST_GUM_STATUS:-1}"
+SCRIPT
+chmod +x "$tmp_dir/bin/gum"
+
+export TEST_GUM_LOG="$tmp_dir/gum-log"
+touch "$TEST_GUM_LOG"
+
 export TEST_LOG="$tmp_dir/log"
 export PATH="$tmp_dir/bin:$PATH"
 
@@ -75,27 +91,84 @@ for kept in .grok .claude.json .npm .local/share/opencode; do
 done
 pass "T3 Code removal keeps the agent state it bootstrapped"
 
-# Perplexity's other products (the CLI, Comet) share the perplexity-* cache
-# prefix; only the rpc-server runtime is the desktop app's own.
-fresh_home
-mkdir -p "$HOME/.config/Perplexity" "$HOME/.cache/Perplexity" "$HOME/.cache/perplexity-rpc-server" "$HOME/.cache/perplexity-personal-computer-poc"
-touch "$HOME/.config/perplexity-flags.conf"
-"$ROOT/bin/omarchy-remove-ai-perplexity" >/dev/null
+# Perplexity's other products (the CLI, Comet) share the perplexity-* prefix;
+# the desktop app owns only its rpc-server runtime and Electron caches. The
+# logins, vault, and flags are the user's and only go when a terminal said so.
+seed_perplexity() {
+  fresh_home
+  mkdir -p "$HOME/.config/Perplexity" "$HOME/.cache/Perplexity" \
+    "$HOME/.cache/perplexity-rpc-server" "$HOME/.local/share/perplexity-rpc-server" \
+    "$HOME/.local/state/perplexity" "$HOME/.cache/perplexity-personal-computer-poc"
+  touch "$HOME/.config/perplexity-flags.conf"
+}
 
-for gone in .config/Perplexity .cache/Perplexity .cache/perplexity-rpc-server .config/perplexity-flags.conf; do
-  [[ ! -e $HOME/$gone ]] || fail "Perplexity removal deletes the desktop app's own data" "$gone"
+# </dev/null pins stdin off a terminal, so this run exercises the
+# non-interactive path no matter where the suite itself is running.
+seed_perplexity
+"$ROOT/bin/omarchy-remove-ai-perplexity" </dev/null >/dev/null
+
+for gone in .cache/Perplexity .cache/perplexity-rpc-server .local/share/perplexity-rpc-server; do
+  [[ ! -e $HOME/$gone ]] || fail "Perplexity removal deletes the app's runtime and caches" "$gone"
 done
-pass "Perplexity removal deletes the desktop app's own data"
+pass "Perplexity removal deletes the app's runtime and caches"
 
-[[ -d $HOME/.cache/perplexity-personal-computer-poc ]] || fail "Perplexity removal keeps other Perplexity products' caches"
-pass "Perplexity removal keeps other Perplexity products' caches"
+for kept in .config/Perplexity .local/state/perplexity .config/perplexity-flags.conf .cache/perplexity-personal-computer-poc; do
+  [[ -e $HOME/$kept ]] || fail "Perplexity removal keeps the user's data and other products' caches" "$kept"
+done
+pass "Perplexity removal keeps the user's data and other products' caches"
 
 grep -qx 'drop:perplexity' "$TEST_LOG" || fail "Perplexity removal drops the perplexity package"
 pass "Perplexity removal drops the perplexity package"
 
+# Without a terminal there is nobody to ask, so gum must not even be reached:
+# one that answered "yes" on its own would be a data loss.
+! grep -q '^gum:' "$TEST_GUM_LOG" || fail "Perplexity removal keeps the user's data unasked when there is no terminal"
+pass "Perplexity removal keeps the user's data unasked when there is no terminal"
+
+# script(1) puts the remover on a pty, the only way -t 0 answers true in a
+# test; the stubbed gum then supplies the answer.
+seed_perplexity
+script -qec "'$ROOT/bin/omarchy-remove-ai-perplexity'" /dev/null >/dev/null 2>&1
+
+[[ -d $HOME/.config/Perplexity && -d $HOME/.local/state/perplexity && -f $HOME/.config/perplexity-flags.conf ]] ||
+  fail "Perplexity removal keeps the user's data when the answer is no"
+pass "Perplexity removal keeps the user's data when the answer is no"
+
+# The stub answers "no" on its own, so only the logged arguments prove the
+# real gum would not default to yes on a bare Enter.
+grep -q '^gum:confirm --default=false ' "$TEST_GUM_LOG" ||
+  fail "Perplexity removal asks with the destructive answer defaulted off"
+pass "Perplexity removal asks with the destructive answer defaulted off"
+
+# A partial install has no user data to measure; du failing must not abort
+# the removal between the package and the prompt.
+seed_perplexity
+rm -rf "$HOME/.config/Perplexity" "$HOME/.local/state/perplexity"
+script -qec "'$ROOT/bin/omarchy-remove-ai-perplexity'" /dev/null >/dev/null 2>&1 ||
+  fail "Perplexity removal survives user-data directories that are already gone"
+pass "Perplexity removal survives user-data directories that are already gone"
+
+# gum draws its prompt on stderr; with stderr redirected the question would be
+# invisible, so the remover must keep the data instead of blocking on it.
+seed_perplexity
+gum_calls_before=$(wc -l <"$TEST_GUM_LOG")
+script -qec "'$ROOT/bin/omarchy-remove-ai-perplexity' 2>/dev/null" /dev/null >/dev/null 2>&1 ||
+  fail "Perplexity removal completes when stderr is not a terminal"
+[[ -d $HOME/.config/Perplexity ]] && (( $(wc -l <"$TEST_GUM_LOG") == gum_calls_before )) ||
+  fail "Perplexity removal keeps the user's data unasked when stderr is not a terminal"
+pass "Perplexity removal keeps the user's data unasked when stderr is not a terminal"
+
+seed_perplexity
+TEST_GUM_STATUS=0 script -qec "'$ROOT/bin/omarchy-remove-ai-perplexity'" /dev/null >/dev/null 2>&1
+
+for gone in .config/Perplexity .local/state/perplexity .config/perplexity-flags.conf; do
+  [[ ! -e $HOME/$gone ]] || fail "Perplexity removal deletes the user's data on an explicit yes" "$gone"
+done
+pass "Perplexity removal deletes the user's data on an explicit yes"
+
 # Without HOME the rm -rf paths would degrade to /-rooted ones; -u makes that a
 # refusal instead.
-if env -u HOME "$ROOT/bin/omarchy-remove-ai-perplexity" >/dev/null 2>&1; then
+if env -u HOME "$ROOT/bin/omarchy-remove-ai-perplexity" </dev/null >/dev/null 2>&1; then
   fail "Perplexity removal refuses to run without HOME"
 fi
 pass "Perplexity removal refuses to run without HOME"

From a1095af075e8f1f304abf16e75a9784067b8d5f7 Mon Sep 17 00:00:00 2001
From: Spencer Bull <spencer@omarchy.org>
Date: Sat, 5 Sep 2026 18:30:49 -0500
Subject: [PATCH 18/27] Ask about the user's data whenever it exists, not only
 behind the bootstrap marker

---
 bin/omarchy-remove-ai-hermes       | 63 +++++++++++++++---------------
 test/shell.d/hermes-remove-test.sh | 27 ++++++++-----
 2 files changed, 49 insertions(+), 41 deletions(-)

diff --git a/bin/omarchy-remove-ai-hermes b/bin/omarchy-remove-ai-hermes
index 924cafab..2465e46c 100755
--- a/bin/omarchy-remove-ai-hermes
+++ b/bin/omarchy-remove-ai-hermes
@@ -22,7 +22,7 @@ omarchy-install-hermes-cli --remove || cli_removed=false
 # 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.
+# 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
@@ -55,39 +55,38 @@ if [[ -f $HOME/.hermes/hermes-agent/.hermes-bootstrap-complete ]]; then
     fi
   done
 
-  # What is left 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, default no. Only here, behind the bootstrap marker: without
-  # it ~/.hermes is an install the app never owned, and offering to delete it
-  # would put the user's own Hermes on the chopping block. Without a terminal
-  # to ask in, keeping it is the answer.
-  data_removed=false
-  if [[ -t 0 ]] && command -v gum >/dev/null; then
-    # du answers non-zero when either directory is missing (the app makes
-    # ~/.config/Hermes, but nothing says it is still there), 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 your Hermes data ($size: chats, memories, skills, connections and tokens)?"; then
-      rm -rf "$HOME/.hermes" "$HOME/.config/Hermes"
-      data_removed=true
-    fi
-  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."
-  else
-    echo "Your chats, memories, and skills are still in ~/.hermes,"
-    echo "and your connections and settings in ~/.config/Hermes."
+# 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 ]] && command -v gum >/dev/null; 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
+    rm -rf "$HOME/.hermes" "$HOME/.config/Hermes"
+    data_removed=true
   fi
-else
-  echo ""
-  echo "Hermes Desktop has been removed."
-  echo "It never finished installing its own Hermes, so nothing in ~/.hermes was touched."
+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
diff --git a/test/shell.d/hermes-remove-test.sh b/test/shell.d/hermes-remove-test.sh
index 88554894..b3ef6862 100755
--- a/test/shell.d/hermes-remove-test.sh
+++ b/test/shell.d/hermes-remove-test.sh
@@ -184,18 +184,27 @@ OMARCHY_TEST_GUM_STATUS=0 remove_tty || fail "remove succeeds when the data goes
   fail "a yes deletes ~/.hermes and ~/.config/Hermes"
 pass "removal deletes the user's data only on an explicit yes"
 
-# Without the bootstrap marker ~/.hermes is an install the app never owned, so
-# it must not even be offered for deletion -- not to a terminal, not to a user
-# who would say yes.
+# Without the bootstrap marker the runtime is not the app's to take unasked,
+# but the data question is still the user's to answer: declining keeps the
+# whole tree -- runtime included -- untouched.
+seed_install
+rm -f "$test_home/.hermes/hermes-agent/.hermes-bootstrap-complete"
+remove_tty || fail "remove succeeds when the app never installed Hermes"
+tr '\0' '\n' <"$test_tmp/gum-log" | grep -qx 'confirm' ||
+  fail "removal still asks about the data without the bootstrap marker"
+[[ -d $test_home/.hermes/hermes-agent && -d $test_home/.config/Hermes ]] ||
+  fail "declining keeps a Hermes the app never installed"
+pass "removal asks without the marker and declining keeps everything"
+
+# The prompt names ~/.hermes itself, so a yes takes the whole tree there too,
+# unowned runtime and all -- that is what was asked and answered.
 seed_install
 rm -f "$test_home/.hermes/hermes-agent/.hermes-bootstrap-complete"
 OMARCHY_TEST_GUM_STATUS=0 remove_tty ||
-  fail "remove succeeds when the app never installed Hermes"
-[[ ! -s $test_tmp/gum-log ]] ||
-  fail "a Hermes the app never installed is not offered for deletion"
-[[ -d $test_home/.hermes/hermes-agent && -d $test_home/.config/Hermes ]] ||
-  fail "a Hermes the app never installed survives a would-be yes"
-pass "removal never offers a Hermes the app did not install"
+  fail "remove succeeds when the data goes too without the marker"
+[[ ! -e $test_home/.hermes && ! -e $test_home/.config/Hermes ]] ||
+  fail "a yes takes ~/.hermes whole when the marker never appeared"
+pass "removal honors a yes on the named paths without the marker"
 
 # A CLI teardown that fails must not stop the runtime handling, and must not be
 # papered over either: the data work still happens, and the failure reaches the

From 6baae0f55667a32cf028bf22bf9139a0a94e1c1e Mon Sep 17 00:00:00 2001
From: Spencer Bull <spencer@omarchy.org>
Date: Sat, 5 Sep 2026 17:06:37 -0500
Subject: [PATCH 19/27] Make Hermes follow the Omarchy theme as a skin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Hermes Desktop installed under Install > AI kept its own palette while every other agent app retinted with the theme. Hermes' skin is its one theme unit for the desktop app, the TUI and the CLI, and its gateway watches the active skin file and broadcasts changes to every surface, so Omarchy publishes a skin named omarchy from a template on every theme switch and nothing Omarchy-specific goes upstream.

Activation goes through hermes config set, which writes the active profile's config and touches the skin so a running gateway repaints at once, and it only replaces Hermes' default skin so a choice made in Hermes stays. A theme switch runs that activation too when the desktop package is present and Hermes is still on its default, so a hand-over the installer missed is finished by the next switch; once the config names the skin a switch never starts Hermes. The desktop adopts a skin from a change broadcast rather than from the config it finds at connect time, and its first launch builds the runtime over minutes, so the installer starts --wait as a transient user unit that outlives the install terminal, activates once the runtime marker appears, republishes after the gateway is up, and reports to the journal. A migration hands the skin to existing Hermes Desktop installs through --activate, which also renders the skin for a theme applied before the template existed.

The generated file is validated before it is published, because Hermes parses it as YAML: only the name, a plain description and #rrggbb colours pass, so an unresolved palette key or a cloned theme's own hermes.yaml leaves the previous skin in place.

🤖 Generated by Fable 5.1 in Claude Code. Reviewed by Fable 5.1 code-review at high.
---
 bin/omarchy-install-ai-hermes              |  11 +
 bin/omarchy-theme-set                      |   1 +
 bin/omarchy-theme-set-hermes               | 199 +++++++++++++++
 default/themed/hermes.yaml.tpl             |  47 ++++
 manual/17-ai.md                            |   4 +-
 migrations/1788619462.sh                   |  12 +
 test/shell.d/hermes-skin-migration-test.sh |  57 +++++
 test/shell.d/hermes-theme-test.sh          | 267 +++++++++++++++++++++
 test/shell.d/theme-staging-test.sh         |   2 +-
 9 files changed, 597 insertions(+), 3 deletions(-)
 create mode 100755 bin/omarchy-theme-set-hermes
 create mode 100644 default/themed/hermes.yaml.tpl
 create mode 100644 migrations/1788619462.sh
 create mode 100644 test/shell.d/hermes-skin-migration-test.sh
 create mode 100644 test/shell.d/hermes-theme-test.sh

diff --git a/bin/omarchy-install-ai-hermes b/bin/omarchy-install-ai-hermes
index 3f6abafe..55a3a271 100755
--- a/bin/omarchy-install-ai-hermes
+++ b/bin/omarchy-install-ai-hermes
@@ -21,6 +21,17 @@ omarchy-install-hermes-cli || true
 echo "Opening Hermes Desktop..."
 setsid uwsm-app -- /usr/bin/hermes-desktop >/dev/null 2>&1 &
 
+# The app builds its runtime on first launch, which takes minutes, and only a
+# running Hermes can be told which skin to show. So the theme is handed over
+# after the launch above, by a helper that waits for that runtime and then
+# names the Omarchy skin through Hermes itself; the running app repaints. Only
+# Hermes' own default is replaced, so a skin chosen in Hermes is never undone.
+# It runs as its own unit, so this terminal closing cannot take it along and
+# what it did is in the journal: journalctl --user -u omarchy-hermes-theme
+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."
 echo "Its first launch installs the Hermes runtime, which takes a few minutes."
diff --git a/bin/omarchy-theme-set b/bin/omarchy-theme-set
index b0c1cda4..b6733803 100755
--- a/bin/omarchy-theme-set
+++ b/bin/omarchy-theme-set
@@ -326,6 +326,7 @@ post_theme_commands=(
   omarchy-theme-set-gnome
   omarchy-theme-set-pi
   omarchy-theme-set-claude
+  omarchy-theme-set-hermes
   omarchy-theme-set-browser
   omarchy-theme-set-vscode
   omarchy-theme-set-obsidian
diff --git a/bin/omarchy-theme-set-hermes b/bin/omarchy-theme-set-hermes
new file mode 100755
index 00000000..a4663738
--- /dev/null
+++ b/bin/omarchy-theme-set-hermes
@@ -0,0 +1,199 @@
+#!/bin/bash
+
+# omarchy:summary=Sync the generated Omarchy theme to Hermes as a skin
+# omarchy:args=[--activate] [--wait]
+# omarchy:hidden=true
+
+# Hermes has one theme unit for all of its surfaces, the skin: a YAML file in
+# ~/.hermes/skins/ that the desktop app, the TUI and the CLI each turn into
+# their own palette. The active one is named by display.skin in Hermes' config,
+# and the gateway watches that file's mtime, so a rewrite of the active skin
+# repaints every connected surface within a second -- no Omarchy code in
+# Hermes, and nothing here that Hermes did not already offer any other system.
+#
+# Every run publishes the skin file, and for the desktop app Omarchy installed
+# names it in the config through Hermes' own config writer if Hermes is still
+# on its default skin, so a theme switch also picks up an install whose
+# hand-over was missed. --activate is the deliberate form, for the installer
+# and the migration: it renders a skin the current theme does not have yet and
+# says why nothing happened when it cannot finish. --wait holds the whole thing
+# until the desktop app has finished building the runtime its first launch
+# provisions.
+
+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"
+# The filename is the skin name Hermes shows and display.skin refers to, and it
+# stays put while the colors change underneath on every theme switch.
+HERMES_SKIN_NAME="omarchy"
+# The app writes this when the runtime it provisions has landed; the CLI
+# installer's readiness probe passes only once it has.
+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
+
+# Only the deliberate form explains itself: the theme switch runs this beside
+# a dozen other hooks, where a note about Hermes on every switch is noise.
+note() {
+  if (( HERMES_ACTIVATE == 1 )); then
+    echo "$*" >&2
+  fi
+}
+
+# The skin is generated with the rest of the theme, so a theme applied before
+# the template existed has none yet. Asked to activate, re-stage the current
+# theme to render it; a theme switch simply has nothing to publish.
+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 desktop app builds its runtime on first launch, which takes minutes and
+# may be abandoned. Poll for the marker rather than the readiness probe, which
+# starts Hermes to answer, and give up quietly on a launch that never came.
+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
+
+# Only follow a Hermes that has been set up. Its config is what Hermes writes
+# when it has; ~/.hermes itself proves nothing, because provisioning creates it
+# on every machine to hold the Omarchy skill.
+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 the strings to every surface, so the
+# generated file is held to the shape the template promises before it is
+# published: the name Hermes loads it by, a plain description, and colors that
+# are all #rrggbb. A theme missing a palette key leaves its placeholder
+# unresolved, and a theme cloned from a git repo may ship its own hermes.yaml;
+# neither gets to write anything else into a file another program reads. The
+# previous skin stays in place instead.
+skin_is_well_formed() {
+  local skin="$1"
+
+  grep -qx "name: $HERMES_SKIN_NAME" "$skin" &&
+    grep -qx 'colors:' "$skin" &&
+    ! grep -qvE "^(#.*|[[:space:]]*|name: $HERMES_SKIN_NAME|description: [A-Za-z0-9 ,.()-]*|colors:|  [a-z_]+: \"#[0-9a-fA-F]{6}\")$" "$skin"
+}
+
+if ! skin_is_well_formed "$HERMES_SOURCE_PATH"; then
+  echo "Skipping Hermes skin: $(basename "$HERMES_SOURCE_PATH") is not a plain color palette." >&2
+  exit 0
+fi
+
+# The gateway watches the skin file's mtime and reads it whole on change, so
+# the write has to be atomic: a half-written file would read as no skin at all.
+publish_skin() {
+  local skins_dir="$1"
+  local tmp
+
+  mkdir -p "$skins_dir"
+  tmp=$(mktemp "$skins_dir/$HERMES_SKIN_NAME.yaml.XXXXXX")
+  cp "$HERMES_SOURCE_PATH" "$tmp"
+  mv "$tmp" "$skins_dir/$HERMES_SKIN_NAME.yaml"
+}
+
+publish_skin "$HERMES_HOME/skins"
+
+# A Hermes profile is a home of its own, with its own skins and config, and the
+# gateway watches whichever profile is active. Existing profiles get the skin
+# too; none are created here.
+for profile in "$HERMES_HOME"/profiles/*/; do
+  [[ -d $profile ]] || continue
+  publish_skin "${profile%/}/skins"
+done
+
+# A theme switch finishes the hand-over only for the app Omarchy installed
+# under Install > AI; a Hermes set up some other way keeps whatever skin it
+# has unless --activate asks for it by name. Hermes writes the active skin
+# under display: at that indent, and once it names ours a theme switch is done
+# here without starting Hermes; anything else is for Hermes itself to answer
+# below, so the grep is only ever a shortcut.
+if (( HERMES_ACTIVATE == 0 )); then
+  omarchy-pkg-present hermes-desktop || exit 0
+  grep -qx "  skin: $HERMES_SKIN_NAME" "$HERMES_CONFIG_PATH" && exit 0
+fi
+
+# Naming the skin in the config is Hermes' own job: `hermes config set` is what
+# `hermes skin use` runs, it writes the active profile's config, and it touches
+# the skin file so a running gateway broadcasts the change and every surface
+# repaints at once. Asked through the installer's readiness probe rather than by
+# running whatever `hermes` is on PATH, because Omarchy's cold stub installs
+# Hermes when run, and that takes minutes.
+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
+
+# A skin the user picked in Hermes stays theirs. Only Hermes' own default is
+# replaced, so a reinstall, a migration or a theme switch never undoes a choice.
+current_skin=$(hermes config get display.skin 2>/dev/null || true)
+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 config set display.skin "$HERMES_SKIN_NAME" >/dev/null
+note "Hermes is on the Omarchy skin."
+
+# The desktop app adopts a skin from a change broadcast, not from the config it
+# finds at connect time, and the gateway seeds its change watcher when it starts.
+# A first launch brings the gateway up moments after the marker, so a config
+# written in that gap goes unannounced; republishing once the gateway is surely
+# up moves the file's mtime again, and that broadcast the desktop does apply.
+if (( HERMES_WAIT == 1 )); then
+  sleep 60
+  publish_skin "$HERMES_HOME/skins"
+fi
diff --git a/default/themed/hermes.yaml.tpl b/default/themed/hermes.yaml.tpl
new file mode 100644
index 00000000..2e39710e
--- /dev/null
+++ b/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 }}"
diff --git a/manual/17-ai.md b/manual/17-ai.md
index 9987cb5b..90d3a10e 100644
--- a/manual/17-ai.md
+++ b/manual/17-ai.md
@@ -26,7 +26,7 @@ Pick your default agent with `omarchy default agent <name>` or under _Setup > De
 
 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
 
@@ -46,7 +46,7 @@ Crashes can also be silenced one program at a time, which is what the diagnosis
 
 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. 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.
+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.
 
diff --git a/migrations/1788619462.sh b/migrations/1788619462.sh
new file mode 100644
index 00000000..56f6c39a
--- /dev/null
+++ b/migrations/1788619462.sh
@@ -0,0 +1,12 @@
+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
+
+# Renders the skin for a theme applied before the template existed, publishes
+# it, and names it in Hermes' config the same way a fresh install does: through
+# Hermes itself, and only when Hermes is still on its default skin, so a skin
+# the user chose stays. A Hermes that is not ready is told and skipped; a Hermes
+# that refuses the write is cosmetic and must not hold up later migrations.
+omarchy-theme-set-hermes --activate || true
diff --git a/test/shell.d/hermes-skin-migration-test.sh b/test/shell.d/hermes-skin-migration-test.sh
new file mode 100644
index 00000000..9e27bf96
--- /dev/null
+++ b/test/shell.d/hermes-skin-migration-test.sh
@@ -0,0 +1,57 @@
+#!/bin/bash
+
+set -euo pipefail
+
+# The migration hands an existing Hermes Desktop install the Omarchy skin. It
+# is exercised here with the package probe and the skin hook stubbed, so a
+# migration that reached a Hermes Omarchy did not install, or that let a
+# Hermes refusing the write hold up later migrations, shows up in what it ran.
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+migration="$ROOT/migrations/1788619462.sh"
+[[ -f $migration ]] || fail "Hermes skin migration exists"
+[[ $(stat -c %a "$migration") == "644" ]] || fail "migration is a plain 0644 file"
+
+test_tmp=$(mktemp -d)
+trap 'rm -rf "$test_tmp"' EXIT
+
+mock_bin="$test_tmp/bin"
+calls="$test_tmp/calls"
+mkdir -p "$mock_bin"
+
+cat >"$mock_bin/omarchy-pkg-present" <<'SH'
+#!/bin/bash
+[[ ${OMARCHY_TEST_DESKTOP_INSTALLED:-0} == 1 ]]
+SH
+
+cat >"$mock_bin/omarchy-theme-set-hermes" <<'SH'
+#!/bin/bash
+echo "omarchy-theme-set-hermes $*" >>"$OMARCHY_TEST_CALLS"
+[[ ${OMARCHY_TEST_HOOK_FAILS:-0} == 0 ]]
+SH
+
+chmod +x "$mock_bin"/*
+
+run_migration() {
+  : >"$calls"
+  OMARCHY_TEST_DESKTOP_INSTALLED="${OMARCHY_TEST_DESKTOP_INSTALLED:-1}" \
+    OMARCHY_TEST_HOOK_FAILS="${OMARCHY_TEST_HOOK_FAILS:-0}" \
+    OMARCHY_TEST_CALLS="$calls" \
+    PATH="$mock_bin:$PATH" \
+    HOME="$test_tmp/home" \
+    OMARCHY_PATH="$ROOT" \
+    bash -euo pipefail "$migration" >/dev/null
+}
+
+OMARCHY_TEST_DESKTOP_INSTALLED=0 run_migration || fail "migration exits clean without Hermes Desktop"
+[[ ! -s $calls ]] || fail "a machine without Hermes Desktop is left alone" "$(cat "$calls")"
+pass "migration only applies where Omarchy installed Hermes Desktop"
+
+run_migration || fail "migration exits clean with Hermes Desktop installed"
+[[ $(cat "$calls") == "omarchy-theme-set-hermes --activate" ]] ||
+  fail "the skin is rendered, published and activated through the hook's deliberate form" "$(cat "$calls")"
+pass "migration hands the skin over through the hook"
+
+OMARCHY_TEST_HOOK_FAILS=1 run_migration || fail "a skin the hook cannot hand over does not hold up later migrations"
+pass "migration tolerates a skin the hook could not activate"
diff --git a/test/shell.d/hermes-theme-test.sh b/test/shell.d/hermes-theme-test.sh
new file mode 100644
index 00000000..6a68cb70
--- /dev/null
+++ b/test/shell.d/hermes-theme-test.sh
@@ -0,0 +1,267 @@
+#!/bin/bash
+
+set -euo pipefail
+
+# omarchy-theme-set-hermes writes a file another program parses and asks that
+# program to switch to it while it is still on its default. Both are exercised
+# here against a throwaway HOME with the Hermes readiness probe, the hermes
+# command and the theme refresh stubbed, so a skin that stopped being
+# validated, a write into a Hermes that was never set up, or an activation
+# that trampled a chosen skin shows up in what landed on disk and what was run.
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+test_tmp=$(mktemp -d)
+trap 'rm -rf "$test_tmp"' EXIT
+
+mock_bin="$test_tmp/bin"
+mkdir -p "$mock_bin"
+
+cat >"$mock_bin/omarchy-install-hermes-cli" <<'SH'
+#!/bin/bash
+echo "check" >>"$OMARCHY_TEST_HERMES_CALLS"
+[[ $1 == "--check" && ${OMARCHY_TEST_HERMES_READY:-0} == "1" ]]
+SH
+
+# A theme switch finishes the hand-over only for the desktop app Omarchy
+# installed; --activate is asked for by name and does not look.
+cat >"$mock_bin/omarchy-pkg-present" <<'SH'
+#!/bin/bash
+[[ $1 == "hermes-desktop" && ${OMARCHY_TEST_DESKTOP_INSTALLED:-1} == "1" ]]
+SH
+
+cat >"$mock_bin/hermes" <<'SH'
+#!/bin/bash
+printf '%s\n' "$*" >>"$OMARCHY_TEST_HERMES_CALLS"
+if [[ $1 == "config" && $2 == "get" ]]; then
+  printf '%s\n' "${OMARCHY_TEST_HERMES_SKIN:-default}"
+fi
+SH
+
+# A refresh re-stages the current theme, which is where the skin gets rendered.
+cat >"$mock_bin/omarchy-theme-refresh" <<'SH'
+#!/bin/bash
+echo "refresh" >>"$OMARCHY_TEST_HERMES_CALLS"
+printf 'name: omarchy\ndescription: Omarchy system theme\ncolors:\n  background: "#1a1b26"\n' \
+  >"$HOME/.local/state/omarchy/current/theme/hermes.yaml"
+SH
+
+# --wait sleeps between its polls and once more after activating; the stub
+# records the delays it was asked for and returns at once.
+cat >"$mock_bin/sleep" <<'SH'
+#!/bin/bash
+printf 'sleep %s\n' "$1" >>"$OMARCHY_TEST_HERMES_CALLS"
+SH
+
+chmod +x "$mock_bin"/*
+
+good_skin='name: omarchy
+description: Omarchy system theme
+colors:
+  background: "#1a1b26"
+  ui_text: "#a9b1d6"
+  ui_accent: "#7aa2f7"'
+
+test_home="$test_tmp/home"
+hermes_home="$test_home/.hermes"
+skin="$hermes_home/skins/omarchy.yaml"
+hermes_calls="$test_tmp/hermes-calls"
+
+# Each case gets a fresh HOME so no file survives from the one before. The
+# Hermes home is created the way provisioning does on every machine; only
+# --set-up adds the config that says Hermes itself has run, on its default
+# skin unless --on names another.
+reset_home() {
+  local source="$good_skin"
+
+  rm -rf "$test_home"
+  mkdir -p "$test_home/.local/state/omarchy/current/theme" "$hermes_home/skills"
+  : >"$hermes_calls"
+
+  while (( $# > 0 )); do
+    case "$1" in
+      --set-up) printf 'display:\n  skin: default\n' >"$hermes_home/config.yaml" ;;
+      --on) printf 'display:\n  skin: %s\n' "$2" >"$hermes_home/config.yaml"; shift ;;
+      *) source="$1" ;;
+    esac
+    shift
+  done
+
+  printf '%s\n' "$source" >"$test_home/.local/state/omarchy/current/theme/hermes.yaml"
+}
+
+run_hook() {
+  OMARCHY_TEST_HERMES_READY="${OMARCHY_TEST_HERMES_READY:-0}" \
+    OMARCHY_TEST_HERMES_SKIN="${OMARCHY_TEST_HERMES_SKIN:-default}" \
+    OMARCHY_TEST_HERMES_CALLS="$hermes_calls" \
+    OMARCHY_TEST_DESKTOP_INSTALLED="${OMARCHY_TEST_DESKTOP_INSTALLED:-1}" \
+    PATH="$mock_bin:$PATH" \
+    HOME="$test_home" \
+    HERMES_HOME='' \
+    "$ROOT/bin/omarchy-theme-set-hermes" "$@"
+}
+
+# -- publishing ---------------------------------------------------------------
+
+reset_home
+run_hook
+[[ ! -e $hermes_home/skins ]] || fail "a Hermes home that only holds the Omarchy skill gets no skin"
+[[ ! -s $hermes_calls ]] || fail "nothing is run for a Hermes that never ran" "$(cat "$hermes_calls")"
+pass "a theme switch leaves a machine that never ran Hermes alone"
+
+reset_home --set-up
+mkdir -p "$hermes_home/profiles/work"
+run_hook 2>"$test_tmp/stderr"
+diff -q "$test_home/.local/state/omarchy/current/theme/hermes.yaml" "$skin" >/dev/null ||
+  fail "the generated skin is published to ~/.hermes/skins/omarchy.yaml"
+diff -q "$skin" "$hermes_home/profiles/work/skins/omarchy.yaml" >/dev/null ||
+  fail "an existing Hermes profile gets the skin too"
+[[ $(ls "$hermes_home/skins") == "omarchy.yaml" ]] || fail "no temporary file is left beside the skin"
+[[ $(cat "$hermes_calls") == "check" ]] || fail "a Hermes that is not ready is asked nothing more" "$(cat "$hermes_calls")"
+[[ ! -s $test_tmp/stderr ]] || fail "a theme switch says nothing about Hermes" "$(cat "$test_tmp/stderr")"
+pass "the skin is published to the Hermes home and every profile"
+
+reset_home --set-up 'name: omarchy
+description: Omarchy system theme
+colors:
+  background: "{{ background }}"'
+mkdir -p "$hermes_home/skins"
+printf 'name: omarchy\ncolors:\n  background: "#000000"\n' >"$skin"
+run_hook 2>"$test_tmp/stderr"
+grep -q '#000000' "$skin" || fail "an unresolved placeholder keeps the previous skin in place"
+grep -q 'not a plain color palette' "$test_tmp/stderr" || fail "an unresolved placeholder is reported"
+pass "a skin with unresolved colors is not published"
+
+for bad in \
+  $'name: omarchy\ndescription: Omarchy system theme\ncolors:\n  background: "#1a1b26"\nbanner_logo: "[link=file:///etc/passwd]x[/link]"' \
+  $'name: omarchy\ndescription: Omarchy system theme\ncolors:\n  background: "#1a1b26\\"\\n  ui_text: \\"#ffffff"' \
+  $'name: nord\ndescription: Nord\ncolors:\n  background: "#2e3440"' \
+  $'description: Omarchy system theme\ncolors:\n  background: "#1a1b26"' \
+  $'name: omarchy\ndescription: Nord: arctic palette\ncolors:\n  background: "#2e3440"'; do
+  reset_home --set-up "$bad"
+  run_hook 2>/dev/null
+  [[ ! -e $skin ]] || fail "a skin that is not exactly a named palette of hex colors is not published" "$bad"
+done
+pass "a skin is held to the shape Hermes loads"
+
+# -- a theme switch finishes a missed hand-over ---------------------------------
+
+reset_home --set-up
+OMARCHY_TEST_HERMES_READY=1 run_hook 2>"$test_tmp/stderr"
+[[ $(cat "$hermes_calls") == $'check\nconfig get display.skin\nconfig set display.skin omarchy' ]] ||
+  fail "a ready Hermes still on its default is switched by a theme switch" "$(cat "$hermes_calls")"
+[[ ! -s $test_tmp/stderr ]] || fail "a theme switch activates quietly" "$(cat "$test_tmp/stderr")"
+pass "a theme switch activates the skin on a Hermes still on its default"
+
+reset_home --on omarchy
+OMARCHY_TEST_HERMES_READY=1 run_hook
+[[ -f $skin ]] || fail "the skin is published when it is already active"
+[[ ! -s $hermes_calls ]] || fail "a Hermes already on the skin is not started" "$(cat "$hermes_calls")"
+pass "a theme switch does not start a Hermes already on the skin"
+
+reset_home --set-up
+OMARCHY_TEST_HERMES_READY=1 OMARCHY_TEST_DESKTOP_INSTALLED=0 run_hook
+[[ -f $skin ]] || fail "a Hermes installed some other way still gets the skin published"
+[[ ! -s $hermes_calls ]] || fail "a theme switch does not touch a Hermes Omarchy did not install as the app" "$(cat "$hermes_calls")"
+pass "a theme switch activates only for the desktop app Omarchy installed"
+
+reset_home --set-up
+OMARCHY_TEST_HERMES_READY=1 OMARCHY_TEST_DESKTOP_INSTALLED=0 run_hook --activate 2>/dev/null
+grep -Fxq 'config set display.skin omarchy' "$hermes_calls" ||
+  fail "--activate switches whichever Hermes it is asked about" "$(cat "$hermes_calls")"
+pass "--activate does not ask which Hermes it is"
+
+reset_home --on ares
+OMARCHY_TEST_HERMES_READY=1 OMARCHY_TEST_HERMES_SKIN=ares run_hook 2>"$test_tmp/stderr"
+! grep -q 'config set' "$hermes_calls" || fail "a theme switch never replaces a chosen skin" "$(cat "$hermes_calls")"
+[[ ! -s $test_tmp/stderr ]] || fail "a chosen skin is left without comment on a theme switch" "$(cat "$test_tmp/stderr")"
+pass "a theme switch leaves a skin the user chose in Hermes"
+
+# -- activation ---------------------------------------------------------------
+
+reset_home
+run_hook --activate 2>"$test_tmp/stderr"
+[[ ! -e $hermes_home/skins && ! -e $hermes_home/config.yaml ]] ||
+  fail "--activate writes nothing into a Hermes that has never run"
+grep -q 'not set up yet' "$test_tmp/stderr" || fail "--activate says why nothing happened"
+pass "--activate waits for Hermes to have been set up"
+
+reset_home --set-up
+run_hook --activate 2>"$test_tmp/stderr"
+[[ -f $skin ]] || fail "--activate publishes the skin when Hermes is not ready"
+[[ $(cat "$hermes_calls") == "check" ]] || fail "a Hermes that is not ready is not run" "$(cat "$hermes_calls")"
+grep -q 'hermes config set display.skin omarchy' "$test_tmp/stderr" || fail "an unready Hermes gets the command that finishes the job"
+pass "--activate publishes but does not run a Hermes that is not ready"
+
+reset_home --set-up
+OMARCHY_TEST_HERMES_READY=1 run_hook --activate 2>"$test_tmp/stderr"
+[[ $(cat "$hermes_calls") == $'check\nconfig get display.skin\nconfig set display.skin omarchy' ]] ||
+  fail "a ready Hermes is asked for its skin and then to switch" "$(cat "$hermes_calls")"
+grep -q 'on the Omarchy skin' "$test_tmp/stderr" || fail "--activate reports success"
+pass "--activate goes through hermes config set when Hermes runs"
+
+reset_home --on omarchy
+OMARCHY_TEST_HERMES_READY=1 OMARCHY_TEST_HERMES_SKIN=omarchy run_hook --activate 2>/dev/null
+grep -Fxq 'config set display.skin omarchy' "$hermes_calls" ||
+  fail "--activate goes through Hermes even when the config already names the skin" "$(cat "$hermes_calls")"
+pass "--activate always asks Hermes to switch"
+
+for chosen in omarchy ""; do
+  reset_home --set-up
+  OMARCHY_TEST_HERMES_READY=1 OMARCHY_TEST_HERMES_SKIN="$chosen" run_hook --activate 2>/dev/null
+  grep -Fxq 'config set display.skin omarchy' "$hermes_calls" ||
+    fail "the default and the omarchy skin are both replaced" "skin='$chosen': $(cat "$hermes_calls")"
+done
+pass "--activate replaces Hermes' default skin"
+
+reset_home --set-up
+OMARCHY_TEST_HERMES_READY=1 OMARCHY_TEST_HERMES_SKIN=ares run_hook --activate 2>"$test_tmp/stderr"
+[[ -f $skin ]] || fail "a chosen skin still gets the Omarchy skin published beside it"
+! grep -q 'config set' "$hermes_calls" || fail "a skin the user chose is not replaced" "$(cat "$hermes_calls")"
+grep -q "'ares' skin" "$test_tmp/stderr" || fail "leaving a chosen skin is reported"
+pass "--activate leaves a skin the user chose in Hermes"
+
+# -- a skin the current theme has not rendered yet -------------------------------
+
+reset_home --set-up
+rm "$test_home/.local/state/omarchy/current/theme/hermes.yaml"
+run_hook
+[[ ! -e $hermes_home/skins && ! -s $hermes_calls ]] ||
+  fail "a theme switch without a rendered skin publishes nothing" "$(cat "$hermes_calls")"
+pass "a theme switch has nothing to do without a rendered skin"
+
+reset_home --set-up
+rm "$test_home/.local/state/omarchy/current/theme/hermes.yaml"
+if run_hook --activate 2>"$test_tmp/stderr"; then
+  fail "--activate fails when no theme has been selected"
+fi
+grep -q 'Select an Omarchy theme' "$test_tmp/stderr" || fail "a missing theme is reported"
+pass "--activate fails without a current theme to render the skin from"
+
+reset_home --set-up
+rm "$test_home/.local/state/omarchy/current/theme/hermes.yaml"
+echo tokyo-night >"$test_home/.local/state/omarchy/current/theme.name"
+OMARCHY_TEST_HERMES_READY=1 run_hook --activate 2>/dev/null
+[[ $(head -1 "$hermes_calls") == "refresh" ]] || fail "a theme applied before the template existed is re-staged" "$(cat "$hermes_calls")"
+[[ -f $skin ]] || fail "the freshly rendered skin is published"
+grep -Fxq 'config set display.skin omarchy' "$hermes_calls" || fail "the freshly rendered skin is activated" "$(cat "$hermes_calls")"
+pass "--activate renders the skin for a theme that predates it"
+
+# -- waiting for the desktop app's first launch ----------------------------------
+
+reset_home --set-up
+mkdir -p "$hermes_home/hermes-agent"
+touch "$hermes_home/hermes-agent/.hermes-bootstrap-complete"
+OMARCHY_TEST_HERMES_READY=1 run_hook --wait 2>/dev/null
+[[ $(cat "$hermes_calls") == $'check\nconfig get display.skin\nconfig set display.skin omarchy\nsleep 60' ]] ||
+  fail "--wait activates as soon as the runtime marker is there, then republishes after the gateway is up" "$(cat "$hermes_calls")"
+[[ -f $skin ]] || fail "--wait publishes the skin"
+pass "--wait activates once the desktop app has built its runtime"
+
+reset_home
+OMARCHY_TEST_HERMES_READY=1 run_hook --wait 2>"$test_tmp/stderr"
+[[ $(head -1 "$hermes_calls") == "sleep 10" && ! -e $hermes_home/skins ]] ||
+  fail "--wait polls for the runtime instead of running Hermes" "$(head -3 "$hermes_calls")"
+[[ $(grep -c 'sleep 10' "$hermes_calls") == 180 ]] || fail "--wait gives up after 30 minutes" "$(grep -c 'sleep 10' "$hermes_calls")"
+grep -q 'did not finish setting up' "$test_tmp/stderr" || fail "giving up is reported"
+pass "--wait polls until the desktop app has built its runtime and gives up in time"
diff --git a/test/shell.d/theme-staging-test.sh b/test/shell.d/theme-staging-test.sh
index cc749a9e..9ec3b0f9 100755
--- a/test/shell.d/theme-staging-test.sh
+++ b/test/shell.d/theme-staging-test.sh
@@ -207,7 +207,7 @@ pass "a theme name cannot climb out of the theme directories"
 # generates. Every generated theme file is either denied to an installed theme or
 # recorded here as carrying colour, so a new template fails until it is placed.
 denied=(alacritty.toml foot.ini ghostty.conf kitty.conf gum_env.lua hyprland.lua neovim.lua vscode.json)
-colour_only=(btop.theme chromium.theme claude.json helix.toml hyprland-preview-share-picker.css keyboard.rgb obsidian.css pi.json shell.toml vscode-theme.json)
+colour_only=(btop.theme chromium.theme claude.json helix.toml hermes.yaml hyprland-preview-share-picker.css keyboard.rgb obsidian.css pi.json shell.toml vscode-theme.json)
 
 for tpl in "$ROOT"/default/themed/*.tpl; do
   generated=$(basename "$tpl" .tpl)

From 8569d1cadc7106b90ca71fbbe673212f682859be Mon Sep 17 00:00:00 2001
From: Spencer Bull <spencer@omarchy.org>
Date: Sat, 5 Sep 2026 23:02:26 -0500
Subject: [PATCH 20/27] Harden the Hermes skin hand-over

Hermes' YAML reader breaks lines on carriage return, NEL and the Unicode line and paragraph separators, and stops at NUL, none of which grep treats as a line end, so a comment line carrying one could put a root-level key such as banner_logo past the validator and into Rich markup on Hermes' terminal surfaces. The lines grep accepted also did not add up to the YAML Hermes needs: a colour before colors:, a second colors:, or a key over YAML's simple-key limit all passed and loaded as no palette at all, which Hermes shows as its default. The validator now counts every byte outside printable ASCII first, then walks the file in order: the name, at most one plain description, colors:, and only #rrggbb colour lines after it.

omarchy-theme-set releases its lock before the hooks run, so the rendered skin can change under this one between the check and the copy. The check is made on a private copy and that copy is what gets published, both on the first pass and on the republish a minute after activation, which used to copy whatever the theme had become by then, unchecked.

A theme switch reads the config of the profile named in active_profile, which is the one Hermes reads, and a profile exists to Hermes once its directory does, with or without a config; it ends early only for a config plainly naming another skin, since only the default is ever replaced, and leaves anything Hermes might read as the default for Hermes to answer. Hermes is run by the path the readiness probe vets, ~/.local/bin/hermes, bounded the way the probe bounds it; an answer that did not come is not taken for the default, and a write Hermes refuses is reported rather than failed, being cosmetic.

A profile that cannot take the skin no longer costs the others or the activation; a directory at the skin's path is an error rather than a place mv puts the temp file; a temp file the copy could not fill is removed. Remove stops the unit the installer left waiting, so a removal within the waiter's half hour does not hand the theme to a Hermes installed some other way or recreate the skin under a home the user asked to delete. The migration no longer swallows the hook's exit: what is not ready or refused is reported and done with inside the hook, so only Omarchy's own failures return, and those keep the migration pending as the guide requires.

Comments are cut to what the code cannot say; the reasoning is here.

Co-Authored-By: Codex XHigh <noreply@openai.com>
---
 bin/omarchy-install-ai-hermes              |   9 +-
 bin/omarchy-remove-ai-hermes               |   3 +
 bin/omarchy-theme-set-hermes               | 190 ++++++++++++---------
 migrations/1788619462.sh                   |   9 +-
 test/shell.d/hermes-remove-test.sh         |  13 ++
 test/shell.d/hermes-skin-migration-test.sh |  12 +-
 test/shell.d/hermes-theme-test.sh          | 146 +++++++++++++++-
 7 files changed, 280 insertions(+), 102 deletions(-)

diff --git a/bin/omarchy-install-ai-hermes b/bin/omarchy-install-ai-hermes
index 55a3a271..fb1411c0 100755
--- a/bin/omarchy-install-ai-hermes
+++ b/bin/omarchy-install-ai-hermes
@@ -21,13 +21,8 @@ omarchy-install-hermes-cli || true
 echo "Opening Hermes Desktop..."
 setsid uwsm-app -- /usr/bin/hermes-desktop >/dev/null 2>&1 &
 
-# The app builds its runtime on first launch, which takes minutes, and only a
-# running Hermes can be told which skin to show. So the theme is handed over
-# after the launch above, by a helper that waits for that runtime and then
-# names the Omarchy skin through Hermes itself; the running app repaints. Only
-# Hermes' own default is replaced, so a skin chosen in Hermes is never undone.
-# It runs as its own unit, so this terminal closing cannot take it along and
-# what it did is in the journal: journalctl --user -u omarchy-hermes-theme
+# Only a running Hermes can be told which skin to show, and the first launch
+# takes minutes; 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
diff --git a/bin/omarchy-remove-ai-hermes b/bin/omarchy-remove-ai-hermes
index 2465e46c..f6b9f292 100755
--- a/bin/omarchy-remove-ai-hermes
+++ b/bin/omarchy-remove-ai-hermes
@@ -8,6 +8,9 @@ set -euo pipefail
 
 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
diff --git a/bin/omarchy-theme-set-hermes b/bin/omarchy-theme-set-hermes
index a4663738..c73b24c7 100755
--- a/bin/omarchy-theme-set-hermes
+++ b/bin/omarchy-theme-set-hermes
@@ -4,21 +4,8 @@
 # omarchy:args=[--activate] [--wait]
 # omarchy:hidden=true
 
-# Hermes has one theme unit for all of its surfaces, the skin: a YAML file in
-# ~/.hermes/skins/ that the desktop app, the TUI and the CLI each turn into
-# their own palette. The active one is named by display.skin in Hermes' config,
-# and the gateway watches that file's mtime, so a rewrite of the active skin
-# repaints every connected surface within a second -- no Omarchy code in
-# Hermes, and nothing here that Hermes did not already offer any other system.
-#
-# Every run publishes the skin file, and for the desktop app Omarchy installed
-# names it in the config through Hermes' own config writer if Hermes is still
-# on its default skin, so a theme switch also picks up an install whose
-# hand-over was missed. --activate is the deliberate form, for the installer
-# and the migration: it renders a skin the current theme does not have yet and
-# says why nothing happened when it cannot finish. --wait holds the whole thing
-# until the desktop app has finished building the runtime its first launch
-# provisions.
+# 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
 
@@ -26,11 +13,10 @@ 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"
-# The filename is the skin name Hermes shows and display.skin refers to, and it
-# stays put while the colors change underneath on every theme switch.
 HERMES_SKIN_NAME="omarchy"
-# The app writes this when the runtime it provisions has landed; the CLI
-# installer's readiness probe passes only once it has.
+# 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
@@ -60,17 +46,14 @@ for arg in "$@"; do
   esac
 done
 
-# Only the deliberate form explains itself: the theme switch runs this beside
-# a dozen other hooks, where a note about Hermes on every switch is noise.
+# A theme switch runs this beside a dozen other hooks; only --activate explains.
 note() {
   if (( HERMES_ACTIVATE == 1 )); then
     echo "$*" >&2
   fi
 }
 
-# The skin is generated with the rest of the theme, so a theme applied before
-# the template existed has none yet. Asked to activate, re-stage the current
-# theme to render it; a theme switch simply has nothing to publish.
+# A theme applied before the template existed has no skin rendered yet.
 if [[ ! -f $HERMES_SOURCE_PATH ]]; then
   (( HERMES_ACTIVATE == 1 )) || exit 0
 
@@ -88,9 +71,8 @@ if [[ ! -f $HERMES_SOURCE_PATH ]]; then
   fi
 fi
 
-# The desktop app builds its runtime on first launch, which takes minutes and
-# may be abandoned. Poll for the marker rather than the readiness probe, which
-# starts Hermes to answer, and give up quietly on a launch that never came.
+# 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
@@ -104,96 +86,148 @@ if (( HERMES_WAIT == 1 )); then
   done
 fi
 
-# Only follow a Hermes that has been set up. Its config is what Hermes writes
-# when it has; ~/.hermes itself proves nothing, because provisioning creates it
-# on every machine to hold the Omarchy skill.
+# 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 the strings to every surface, so the
-# generated file is held to the shape the template promises before it is
-# published: the name Hermes loads it by, a plain description, and colors that
-# are all #rrggbb. A theme missing a palette key leaves its placeholder
-# unresolved, and a theme cloned from a git repo may ship its own hermes.yaml;
-# neither gets to write anything else into a file another program reads. The
-# previous skin stays in place instead.
+# 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"
 
-  grep -qx "name: $HERMES_SKIN_NAME" "$skin" &&
-    grep -qx 'colors:' "$skin" &&
-    ! grep -qvE "^(#.*|[[:space:]]*|name: $HERMES_SKIN_NAME|description: [A-Za-z0-9 ,.()-]*|colors:|  [a-z_]+: \"#[0-9a-fA-F]{6}\")$" "$skin"
+  [[ -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"
 }
 
-if ! skin_is_well_formed "$HERMES_SOURCE_PATH"; then
+# 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 watches the skin file's mtime and reads it whole on change, so
-# the write has to be atomic: a half-written file would read as no skin at all.
+# 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"
-  tmp=$(mktemp "$skins_dir/$HERMES_SKIN_NAME.yaml.XXXXXX")
-  cp "$HERMES_SOURCE_PATH" "$tmp"
-  mv "$tmp" "$skins_dir/$HERMES_SKIN_NAME.yaml"
+  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
 }
 
-publish_skin "$HERMES_HOME/skins"
+# 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
 
-# A Hermes profile is a home of its own, with its own skins and config, and the
-# gateway watches whichever profile is active. Existing profiles get the skin
-# too; none are created here.
-for profile in "$HERMES_HOME"/profiles/*/; do
-  [[ -d $profile ]] || continue
-  publish_skin "${profile%/}/skins"
-done
+  publish_skin "$HERMES_HOME/skins" || {
+    echo "Could not publish the Hermes skin to $HERMES_HOME/skins." >&2
+    return 1
+  }
 
-# A theme switch finishes the hand-over only for the app Omarchy installed
-# under Install > AI; a Hermes set up some other way keeps whatever skin it
-# has unless --activate asks for it by name. Hermes writes the active skin
-# under display: at that indent, and once it names ours a theme switch is done
-# here without starting Hermes; anything else is for Hermes itself to answer
-# below, so the grep is only ever a shortcut.
+  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
-  grep -qx "  skin: $HERMES_SKIN_NAME" "$HERMES_CONFIG_PATH" && 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
 
-# Naming the skin in the config is Hermes' own job: `hermes config set` is what
-# `hermes skin use` runs, it writes the active profile's config, and it touches
-# the skin file so a running gateway broadcasts the change and every surface
-# repaints at once. Asked through the installer's readiness probe rather than by
-# running whatever `hermes` is on PATH, because Omarchy's cold stub installs
-# Hermes when run, and that takes minutes.
+# 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
 
-# A skin the user picked in Hermes stays theirs. Only Hermes' own default is
-# replaced, so a reinstall, a migration or a theme switch never undoes a choice.
-current_skin=$(hermes config get display.skin 2>/dev/null || true)
+# 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 config set display.skin "$HERMES_SKIN_NAME" >/dev/null
+# 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 app adopts a skin from a change broadcast, not from the config it
-# finds at connect time, and the gateway seeds its change watcher when it starts.
-# A first launch brings the gateway up moments after the marker, so a config
-# written in that gap goes unannounced; republishing once the gateway is surely
-# up moves the file's mtime again, and that broadcast the desktop does apply.
+# 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
-  publish_skin "$HERMES_HOME/skins"
+
+  if take_snapshot; then
+    publish_skin_everywhere
+  fi
 fi
diff --git a/migrations/1788619462.sh b/migrations/1788619462.sh
index 56f6c39a..0b491679 100644
--- a/migrations/1788619462.sh
+++ b/migrations/1788619462.sh
@@ -4,9 +4,6 @@ echo "Hand Hermes Desktop the Omarchy theme as a skin"
 # A Hermes the user set up some other way keeps whatever skin they chose.
 omarchy-pkg-present hermes-desktop || exit 0
 
-# Renders the skin for a theme applied before the template existed, publishes
-# it, and names it in Hermes' config the same way a fresh install does: through
-# Hermes itself, and only when Hermes is still on its default skin, so a skin
-# the user chose stays. A Hermes that is not ready is told and skipped; a Hermes
-# that refuses the write is cosmetic and must not hold up later migrations.
-omarchy-theme-set-hermes --activate || true
+# 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
diff --git a/test/shell.d/hermes-remove-test.sh b/test/shell.d/hermes-remove-test.sh
index b3ef6862..0a06f03a 100755
--- a/test/shell.d/hermes-remove-test.sh
+++ b/test/shell.d/hermes-remove-test.sh
@@ -34,6 +34,11 @@ cat >"$mock_bin/gum" <<'SH'
 printf '%s\0' "$@" >>"$OMARCHY_TEST_GUM_LOG"
 exit "${OMARCHY_TEST_GUM_STATUS:-1}"
 SH
+cat >"$mock_bin/systemctl" <<'SH'
+#!/bin/bash
+echo "systemctl $*" >>"$OMARCHY_TEST_SYSTEMCTL_LOG"
+SH
+
 chmod +x "$mock_bin"/*
 
 seed_install() {
@@ -58,9 +63,11 @@ seed_install() {
 remove() {
   : >"$test_tmp/installer-log"
   : >"$test_tmp/gum-log"
+  : >"$test_tmp/systemctl-log"
   OMARCHY_TEST_DROP_LOG="$test_tmp/drop-log" \
     OMARCHY_TEST_INSTALLER_LOG="$test_tmp/installer-log" \
     OMARCHY_TEST_INSTALLER_STATUS="${OMARCHY_TEST_INSTALLER_STATUS:-0}" \
+    OMARCHY_TEST_SYSTEMCTL_LOG="$test_tmp/systemctl-log" \
     OMARCHY_TEST_GUM_LOG="$test_tmp/gum-log" \
     HOME="$test_home" PATH="$mock_bin:$PATH" \
     bash "$ROOT/bin/omarchy-remove-ai-hermes" </dev/null >/dev/null 2>&1
@@ -71,8 +78,10 @@ remove() {
 remove_tty() {
   : >"$test_tmp/installer-log"
   : >"$test_tmp/gum-log"
+  : >"$test_tmp/systemctl-log"
   OMARCHY_TEST_DROP_LOG="$test_tmp/drop-log" \
     OMARCHY_TEST_INSTALLER_LOG="$test_tmp/installer-log" \
+    OMARCHY_TEST_SYSTEMCTL_LOG="$test_tmp/systemctl-log" \
     OMARCHY_TEST_GUM_LOG="$test_tmp/gum-log" \
     OMARCHY_TEST_GUM_STATUS="${OMARCHY_TEST_GUM_STATUS:-1}" \
     HOME="$test_home" PATH="$mock_bin:$PATH" \
@@ -89,6 +98,10 @@ remove || fail "remove succeeds"
 [[ ! -d $test_home/.hermes/node ]] || fail "the node the app installed is removed"
 pass "removal takes the whole runtime the app installed"
 
+grep -Fxq 'systemctl --user stop omarchy-hermes-theme.service' "$test_tmp/systemctl-log" ||
+  fail "the unit the installer left waiting to hand over the theme is stopped" "$(cat "$test_tmp/systemctl-log")"
+pass "removal stops the installer's theme hand-over"
+
 [[ -d $test_home/.config/Hermes ]] ||
   fail "gateway connections, tokens and settings survive removal"
 pass "removal keeps the app's connections and settings"
diff --git a/test/shell.d/hermes-skin-migration-test.sh b/test/shell.d/hermes-skin-migration-test.sh
index 9e27bf96..3fef5303 100644
--- a/test/shell.d/hermes-skin-migration-test.sh
+++ b/test/shell.d/hermes-skin-migration-test.sh
@@ -4,8 +4,8 @@ set -euo pipefail
 
 # The migration hands an existing Hermes Desktop install the Omarchy skin. It
 # is exercised here with the package probe and the skin hook stubbed, so a
-# migration that reached a Hermes Omarchy did not install, or that let a
-# Hermes refusing the write hold up later migrations, shows up in what it ran.
+# migration that reached a Hermes Omarchy did not install, or that marked a
+# failed hand-over done, shows up in what it ran.
 
 source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
 
@@ -22,7 +22,7 @@ mkdir -p "$mock_bin"
 
 cat >"$mock_bin/omarchy-pkg-present" <<'SH'
 #!/bin/bash
-[[ ${OMARCHY_TEST_DESKTOP_INSTALLED:-0} == 1 ]]
+[[ $1 == "hermes-desktop" && ${OMARCHY_TEST_DESKTOP_INSTALLED:-0} == 1 ]]
 SH
 
 cat >"$mock_bin/omarchy-theme-set-hermes" <<'SH'
@@ -53,5 +53,7 @@ run_migration || fail "migration exits clean with Hermes Desktop installed"
   fail "the skin is rendered, published and activated through the hook's deliberate form" "$(cat "$calls")"
 pass "migration hands the skin over through the hook"
 
-OMARCHY_TEST_HOOK_FAILS=1 run_migration || fail "a skin the hook cannot hand over does not hold up later migrations"
-pass "migration tolerates a skin the hook could not activate"
+if OMARCHY_TEST_HOOK_FAILS=1 run_migration; then
+  fail "a hand-over that failed on Omarchy's side stays pending"
+fi
+pass "migration stays pending when the hand-over fails"
diff --git a/test/shell.d/hermes-theme-test.sh b/test/shell.d/hermes-theme-test.sh
index 6a68cb70..631ffe70 100644
--- a/test/shell.d/hermes-theme-test.sh
+++ b/test/shell.d/hermes-theme-test.sh
@@ -30,11 +30,23 @@ cat >"$mock_bin/omarchy-pkg-present" <<'SH'
 [[ $1 == "hermes-desktop" && ${OMARCHY_TEST_DESKTOP_INSTALLED:-1} == "1" ]]
 SH
 
+# The hook runs the hermes the probe vets, ~/.local/bin/hermes, not one on PATH;
+# reset_home installs this stub there and a decoy on PATH that must never run.
 cat >"$mock_bin/hermes" <<'SH'
 #!/bin/bash
+echo "PATH hermes ran: $*" >>"$OMARCHY_TEST_HERMES_CALLS"
+exit 1
+SH
+
+cat >"$mock_bin/hermes-stub" <<'SH'
+#!/bin/bash
 printf '%s\n' "$*" >>"$OMARCHY_TEST_HERMES_CALLS"
 if [[ $1 == "config" && $2 == "get" ]]; then
-  printf '%s\n' "${OMARCHY_TEST_HERMES_SKIN:-default}"
+  [[ ${OMARCHY_TEST_HERMES_GET_FAILS:-0} == 0 ]] || exit 1
+  printf '%s\n' "${OMARCHY_TEST_HERMES_SKIN-default}"
+fi
+if [[ $1 == "config" && $2 == "set" ]]; then
+  [[ ${OMARCHY_TEST_HERMES_SET_FAILS:-0} == 0 ]] || exit 1
 fi
 SH
 
@@ -51,6 +63,12 @@ SH
 cat >"$mock_bin/sleep" <<'SH'
 #!/bin/bash
 printf 'sleep %s\n' "$1" >>"$OMARCHY_TEST_HERMES_CALLS"
+if [[ $1 == 60 && -n ${OMARCHY_TEST_SWAP_SOURCE:-} ]]; then
+  printf '%s\n' "$OMARCHY_TEST_SWAP_SOURCE" >"$HOME/.local/state/omarchy/current/theme/hermes.yaml"
+fi
+if [[ $1 == 60 && ${OMARCHY_TEST_DROP_SKINS:-0} == 1 ]]; then
+  rm -f "$HOME/.hermes/skins/omarchy.yaml" "$HOME"/.hermes/profiles/*/skins/omarchy.yaml
+fi
 SH
 
 chmod +x "$mock_bin"/*
@@ -75,7 +93,8 @@ reset_home() {
   local source="$good_skin"
 
   rm -rf "$test_home"
-  mkdir -p "$test_home/.local/state/omarchy/current/theme" "$hermes_home/skills"
+  mkdir -p "$test_home/.local/state/omarchy/current/theme" "$test_home/.local/bin" "$hermes_home/skills"
+  cp "$mock_bin/hermes-stub" "$test_home/.local/bin/hermes"
   : >"$hermes_calls"
 
   while (( $# > 0 )); do
@@ -92,9 +111,13 @@ reset_home() {
 
 run_hook() {
   OMARCHY_TEST_HERMES_READY="${OMARCHY_TEST_HERMES_READY:-0}" \
-    OMARCHY_TEST_HERMES_SKIN="${OMARCHY_TEST_HERMES_SKIN:-default}" \
+    OMARCHY_TEST_HERMES_SKIN="${OMARCHY_TEST_HERMES_SKIN-default}" \
+    OMARCHY_TEST_HERMES_GET_FAILS="${OMARCHY_TEST_HERMES_GET_FAILS:-0}" \
+    OMARCHY_TEST_HERMES_SET_FAILS="${OMARCHY_TEST_HERMES_SET_FAILS:-0}" \
     OMARCHY_TEST_HERMES_CALLS="$hermes_calls" \
     OMARCHY_TEST_DESKTOP_INSTALLED="${OMARCHY_TEST_DESKTOP_INSTALLED:-1}" \
+    OMARCHY_TEST_SWAP_SOURCE="${OMARCHY_TEST_SWAP_SOURCE:-}" \
+    OMARCHY_TEST_DROP_SKINS="${OMARCHY_TEST_DROP_SKINS:-0}" \
     PATH="$mock_bin:$PATH" \
     HOME="$test_home" \
     HERMES_HOME='' \
@@ -132,17 +155,48 @@ grep -q '#000000' "$skin" || fail "an unresolved placeholder keeps the previous
 grep -q 'not a plain color palette' "$test_tmp/stderr" || fail "an unresolved placeholder is reported"
 pass "a skin with unresolved colors is not published"
 
+# mv would otherwise move the temp file inside a directory at the skin's path,
+# leaving Hermes a directory to read and the temp file behind.
+reset_home --set-up
+mkdir -p "$skin"
+if run_hook 2>/dev/null; then
+  fail "a directory at the skin's path is an error, not a place to put the skin"
+fi
+[[ -z $(ls -A "$skin") && $(ls "$hermes_home/skins") == "omarchy.yaml" ]] ||
+  fail "nothing is left inside or beside a directory at the skin's path" "$(ls -R "$hermes_home/skins")"
+pass "a directory at the skin's path is refused cleanly"
+
 for bad in \
   $'name: omarchy\ndescription: Omarchy system theme\ncolors:\n  background: "#1a1b26"\nbanner_logo: "[link=file:///etc/passwd]x[/link]"' \
   $'name: omarchy\ndescription: Omarchy system theme\ncolors:\n  background: "#1a1b26\\"\\n  ui_text: \\"#ffffff"' \
   $'name: nord\ndescription: Nord\ncolors:\n  background: "#2e3440"' \
   $'description: Omarchy system theme\ncolors:\n  background: "#1a1b26"' \
-  $'name: omarchy\ndescription: Nord: arctic palette\ncolors:\n  background: "#2e3440"'; do
+  $'name: omarchy\ndescription: Nord: arctic palette\ncolors:\n  background: "#2e3440"' \
+  $'name: omarchy\ncolors:\n  background: "#1a1b26"\n#\rbanner_logo: "[link=file:///etc/passwd]x[/link]"' \
+  $'name: omarchy\ncolors:\n  background: "#1a1b26"\n#\xe2\x80\xa8banner_logo: "evil"' \
+  $'name: omarchy\ncolors:\n  background: "#1a1b26"\n#\xc2\x85banner_logo: "evil"' \
+  $'name: omarchy\n  background: "#1a1b26"\ncolors:' \
+  $'name: omarchy\ncolors:\n  background: "#1a1b26"\ncolors:' \
+  $'colors:\n  background: "#1a1b26"\nname: omarchy' \
+  $'name: omarchy\ncolors:'; do
   reset_home --set-up "$bad"
   run_hook 2>/dev/null
   [[ ! -e $skin ]] || fail "a skin that is not exactly a named palette of hex colors is not published" "$bad"
 done
-pass "a skin is held to the shape Hermes loads"
+pass "a skin is held to the shape Hermes loads, on the lines Hermes' YAML reader sees"
+
+# A NUL cannot travel through a shell string, so it is written straight to the
+# source; grep reads past one where YAML stops.
+reset_home --set-up
+printf 'name: omarchy\ncolors:\n  background: "#1a1b26"\0\n' >"$test_home/.local/state/omarchy/current/theme/hermes.yaml"
+run_hook 2>/dev/null
+[[ ! -e $skin ]] || fail "a NUL byte in the skin is rejected"
+pass "a skin carrying a NUL byte is not published"
+
+reset_home --set-up $'# rendered by Omarchy\nname: omarchy\n\ndescription: Omarchy system theme\ncolors:\n  background: "#1a1b26"\n'
+run_hook 2>/dev/null
+[[ -f $skin ]] || fail "comments and blank lines are allowed around the palette"
+pass "a well-formed skin with comments and blank lines is published"
 
 # -- a theme switch finishes a missed hand-over ---------------------------------
 
@@ -173,10 +227,61 @@ pass "--activate does not ask which Hermes it is"
 
 reset_home --on ares
 OMARCHY_TEST_HERMES_READY=1 OMARCHY_TEST_HERMES_SKIN=ares run_hook 2>"$test_tmp/stderr"
-! grep -q 'config set' "$hermes_calls" || fail "a theme switch never replaces a chosen skin" "$(cat "$hermes_calls")"
+[[ -f $skin ]] || fail "a chosen skin still gets the Omarchy skin published beside it"
+[[ ! -s $hermes_calls ]] || fail "a theme switch does not start a Hermes whose config names a chosen skin" "$(cat "$hermes_calls")"
 [[ ! -s $test_tmp/stderr ]] || fail "a chosen skin is left without comment on a theme switch" "$(cat "$test_tmp/stderr")"
 pass "a theme switch leaves a skin the user chose in Hermes"
 
+# Hermes reads the config of the profile named in active_profile, so that is
+# the config that says whether there is anything left to do.
+reset_home --on omarchy
+mkdir -p "$hermes_home/profiles/work"
+printf 'display:\n  skin: default\n' >"$hermes_home/profiles/work/config.yaml"
+echo work >"$hermes_home/active_profile"
+OMARCHY_TEST_HERMES_READY=1 run_hook
+grep -Fxq 'config set display.skin omarchy' "$hermes_calls" ||
+  fail "an active profile still on its default is switched even when the root config names the skin" "$(cat "$hermes_calls")"
+pass "a theme switch follows the active Hermes profile"
+
+reset_home --set-up
+mkdir -p "$hermes_home/profiles/work"
+printf 'display:\n  skin: ares\n' >"$hermes_home/profiles/work/config.yaml"
+echo work >"$hermes_home/active_profile"
+OMARCHY_TEST_HERMES_READY=1 run_hook
+[[ ! -s $hermes_calls ]] || fail "a skin chosen in the active profile is not replaced" "$(cat "$hermes_calls")"
+pass "a theme switch leaves a skin chosen in the active Hermes profile"
+
+# Hermes selects a profile once its directory exists; without a config of its
+# own it is on the default skin whatever the root config says.
+reset_home --on omarchy
+mkdir -p "$hermes_home/profiles/work"
+echo Work >"$hermes_home/active_profile"
+OMARCHY_TEST_HERMES_READY=1 run_hook
+grep -Fxq 'config set display.skin omarchy' "$hermes_calls" ||
+  fail "an active profile without a config of its own is on the default and gets switched" "$(cat "$hermes_calls")"
+pass "a theme switch follows an active profile that has no config yet"
+
+# Only a plainly named skin ends a switch early; anything Hermes might read as
+# its default is left for Hermes to answer.
+for line in 'skin: "default"' 'skin: default # chosen long ago' 'skin: null' 'skin: false'; do
+  reset_home --set-up
+  printf 'display:\n  %s\n' "$line" >"$hermes_home/config.yaml"
+  OMARCHY_TEST_HERMES_READY=1 run_hook
+  grep -Fxq 'config set display.skin omarchy' "$hermes_calls" ||
+    fail "a config line Hermes reads as the default still gets the skin activated" "$line: $(cat "$hermes_calls")"
+done
+pass "a theme switch asks Hermes about any skin line that is not a plain name"
+
+reset_home --set-up
+mkdir -p "$hermes_home/profiles/broken"
+: >"$hermes_home/profiles/broken/skins"
+OMARCHY_TEST_HERMES_READY=1 run_hook 2>"$test_tmp/stderr" || fail "a profile that cannot take the skin does not fail the hook"
+[[ ! -s $test_tmp/stderr ]] || fail "a theme switch stays quiet about a profile it could not reach" "$(cat "$test_tmp/stderr")"
+[[ -f $skin ]] || fail "the Hermes home still gets the skin beside a broken profile"
+grep -Fxq 'config set display.skin omarchy' "$hermes_calls" ||
+  fail "activation still happens beside a broken profile" "$(cat "$hermes_calls")"
+pass "a profile that cannot take the skin costs nobody else"
+
 # -- activation ---------------------------------------------------------------
 
 reset_home
@@ -221,6 +326,20 @@ OMARCHY_TEST_HERMES_READY=1 OMARCHY_TEST_HERMES_SKIN=ares run_hook --activate 2>
 grep -q "'ares' skin" "$test_tmp/stderr" || fail "leaving a chosen skin is reported"
 pass "--activate leaves a skin the user chose in Hermes"
 
+reset_home --set-up
+OMARCHY_TEST_HERMES_READY=1 OMARCHY_TEST_HERMES_GET_FAILS=1 run_hook --activate 2>"$test_tmp/stderr" || fail "a Hermes that does not answer is not an error"
+! grep -q 'config set' "$hermes_calls" || fail "no answer from Hermes is not taken for the default" "$(cat "$hermes_calls")"
+grep -q 'did not say' "$test_tmp/stderr" || fail "an unanswered question is reported"
+pass "--activate does not switch a Hermes that did not say which skin it is on"
+
+reset_home --set-up
+mkdir -p "$hermes_home/hermes-agent"
+touch "$hermes_home/hermes-agent/.hermes-bootstrap-complete"
+OMARCHY_TEST_HERMES_READY=1 OMARCHY_TEST_HERMES_SET_FAILS=1 run_hook --wait 2>"$test_tmp/stderr" || fail "a Hermes that refuses the write is not an error"
+grep -q 'refused' "$test_tmp/stderr" || fail "a refused write is reported"
+! grep -q 'sleep 60' "$hermes_calls" || fail "nothing is announced for a write that did not happen" "$(cat "$hermes_calls")"
+pass "--activate reports a Hermes that refused the skin and moves on"
+
 # -- a skin the current theme has not rendered yet -------------------------------
 
 reset_home --set-up
@@ -258,6 +377,21 @@ OMARCHY_TEST_HERMES_READY=1 run_hook --wait 2>/dev/null
 [[ -f $skin ]] || fail "--wait publishes the skin"
 pass "--wait activates once the desktop app has built its runtime"
 
+reset_home --set-up
+mkdir -p "$hermes_home/hermes-agent" "$hermes_home/profiles/work"
+touch "$hermes_home/hermes-agent/.hermes-bootstrap-complete"
+OMARCHY_TEST_HERMES_READY=1 OMARCHY_TEST_SWAP_SOURCE=$'name: omarchy\ncolors:\n  background: "#1a1b26"\nbanner_logo: "evil"' run_hook --wait 2>/dev/null
+! grep -q 'banner_logo' "$skin" || fail "the republish after the gateway is up does not publish a theme that changed underneath into something rejected"
+pass "--wait checks the skin again before republishing it"
+
+reset_home --set-up
+mkdir -p "$hermes_home/hermes-agent" "$hermes_home/profiles/work"
+touch "$hermes_home/hermes-agent/.hermes-bootstrap-complete"
+OMARCHY_TEST_HERMES_READY=1 OMARCHY_TEST_DROP_SKINS=1 run_hook --wait 2>/dev/null
+[[ -f $skin && -f $hermes_home/profiles/work/skins/omarchy.yaml ]] ||
+  fail "the republish after the gateway is up writes the skin to the Hermes home and every profile again" "$(ls -R "$hermes_home")"
+pass "--wait republishes the skin everywhere once the gateway is up"
+
 reset_home
 OMARCHY_TEST_HERMES_READY=1 run_hook --wait 2>"$test_tmp/stderr"
 [[ $(head -1 "$hermes_calls") == "sleep 10" && ! -e $hermes_home/skins ]] ||

From adcc96a78226735d6fddf5196fb3f71e8c49d584 Mon Sep 17 00:00:00 2001
From: powderluv <powderluv@users.noreply.github.com>
Date: Sun, 6 Sep 2026 02:58:30 -0700
Subject: [PATCH 21/27] Install libfprint-git for every fingerprint reader
 (#10442)

* Use updated libfprint-git for fingerprint setup on edge

* Pick the fingerprint driver from the reader, not the release channel

The channel gate blocked every edge and dev user until the newer
libfprint-git pin is published, misrouted dev checkouts on the stable
mirror, and left the stock-libfprint migration reverting the driver on
accounts without its marker. Key both the setup and the migration on
omarchy-hw-fingerprint-git, a USB ID table of readers stock libfprint
cannot drive, so the git snapshot only goes where it is needed on any
channel. Qualify the package with the omarchy repo, and skip pacman
entirely when the packages are already current so a rerun cannot become
a partial upgrade.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* Install libfprint-git for every fingerprint reader

Stock libfprint lags upstream on new readers, and gating the git
snapshot per reader or per channel only added machinery to keep in sync
with the package repo. Install libfprint-git unconditionally instead:
the omarchy-pkgs pin is the single place a new reader gets enabled. The
migration that swapped it back to stock goes away with the policy it
enforced; late updaters keep the driver they have and pick up the new
pin as a normal package upgrade.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: powderluv <powderluv@powderluv.org>
Co-authored-by: David Heinemeier Hansson <david@hey.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/omarchy-setup-security-fingerprint        | 17 ++--
 migrations/1785090473.sh                      | 21 ++---
 .../fingerprint-driver-migration-test.sh      | 60 ++++++++++++
 test/shell.d/fingerprint-package-test.sh      | 93 +++++++++++++++++++
 4 files changed, 166 insertions(+), 25 deletions(-)
 create mode 100755 test/shell.d/fingerprint-driver-migration-test.sh
 create mode 100755 test/shell.d/fingerprint-package-test.sh

diff --git a/bin/omarchy-setup-security-fingerprint b/bin/omarchy-setup-security-fingerprint
index 383aa376..e46aaed9 100755
--- a/bin/omarchy-setup-security-fingerprint
+++ b/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"
diff --git a/migrations/1785090473.sh b/migrations/1785090473.sh
index 1e64b6ee..ca75cf2c 100644
--- a/migrations/1785090473.sh
+++ b/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
diff --git a/test/shell.d/fingerprint-driver-migration-test.sh b/test/shell.d/fingerprint-driver-migration-test.sh
new file mode 100755
index 00000000..6b3f523c
--- /dev/null
+++ b/test/shell.d/fingerprint-driver-migration-test.sh
@@ -0,0 +1,60 @@
+#!/bin/bash
+#
+# The fingerprint driver migration only repairs a machine an earlier version of
+# it left with fprintd and no libfprint; any installed driver is left alone.
+# The real package helpers run over a stubbed pacman.
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+migration="$ROOT/migrations/1785090473.sh"
+scratch=$(mktemp -d)
+trap 'rm -rf "$scratch"' EXIT
+mkdir -p "$scratch/bin"
+export CALL_LOG="$scratch/calls"
+export PATH="$scratch/bin:$ROOT/bin:$PATH"
+
+cat > "$scratch/bin/sudo" <<'STUB'
+#!/bin/bash
+exec "$@"
+STUB
+# INSTALLED lists the installed package names, one per line; an install adds
+# its packages to INSTALLED_LOG so omarchy-pkg-add's follow-up query sees them.
+cat > "$scratch/bin/pacman" <<'STUB'
+#!/bin/bash
+case "$1" in
+  -Q) grep -qx "$2" <<< "${INSTALLED:-}" || grep -qx "$2" "$INSTALLED_LOG" ;;
+  -S)
+    printf 'pacman %s\n' "$*" >> "$CALL_LOG"
+    for arg in "$@"; do
+      [[ $arg == -* ]] || printf '%s\n' "$arg" >> "$INSTALLED_LOG"
+    done
+    ;;
+  *) printf 'pacman %s\n' "$*" >> "$CALL_LOG" ;;
+esac
+STUB
+chmod +x "$scratch/bin/"*
+export INSTALLED_LOG="$scratch/installed"
+
+run_migration() {
+  : > "$CALL_LOG"
+  : > "$INSTALLED_LOG"
+  bash -euo pipefail "$migration" > /dev/null
+}
+
+INSTALLED='fprintd' run_migration
+grep -qx 'pacman -S --noconfirm --needed libfprint-git' "$CALL_LOG" || fail "fprintd without a library gets libfprint-git"
+pass "fprintd without a library gets libfprint-git"
+
+INSTALLED=$'libfprint-git\nfprintd' run_migration
+[[ ! -s $CALL_LOG ]] || fail "an installed libfprint-git is left alone" "$(<"$CALL_LOG")"
+pass "an installed libfprint-git is left alone"
+
+INSTALLED=$'libfprint\nfprintd' run_migration
+[[ ! -s $CALL_LOG ]] || fail "an installed stock libfprint is left alone" "$(<"$CALL_LOG")"
+pass "an installed stock libfprint is left alone"
+
+INSTALLED='' run_migration
+[[ ! -s $CALL_LOG ]] || fail "a machine without fprintd is left alone" "$(<"$CALL_LOG")"
+pass "a machine without fprintd is left alone"
diff --git a/test/shell.d/fingerprint-package-test.sh b/test/shell.d/fingerprint-package-test.sh
new file mode 100755
index 00000000..70329982
--- /dev/null
+++ b/test/shell.d/fingerprint-package-test.sh
@@ -0,0 +1,93 @@
+#!/bin/bash
+#
+# The fingerprint setup installs libfprint-git in place of stock libfprint. The
+# two conflict, so the swap has to happen inside one --ask 4 transaction, and a
+# rerun with everything installed must not touch pacman at all. The real
+# omarchy-pkg-missing runs; pacman and the privileged calls are stubbed.
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+scratch=$(mktemp -d)
+trap 'rm -rf "$scratch"' EXIT
+mkdir -p "$scratch/bin"
+export CALL_LOG="$scratch/calls"
+export PATH="$scratch/bin:$ROOT/bin:$PATH"
+
+cat > "$scratch/bin/omarchy-hw-fingerprint" <<'STUB'
+#!/bin/bash
+exit "${HARDWARE_STATUS:-0}"
+STUB
+cat > "$scratch/bin/sudo" <<'STUB'
+#!/bin/bash
+case "$1" in
+  pacman | fprintd-enroll) exec "$@" ;;
+  *) echo "Unexpected privileged call: $*" >> "$CALL_LOG"; exit 99 ;;
+esac
+STUB
+# INSTALLED lists the installed package names, one per line.
+cat > "$scratch/bin/pacman" <<'STUB'
+#!/bin/bash
+case "$1" in
+  -Q) grep -qx "$2" <<< "${INSTALLED:-}" ;;
+  -S)
+    printf 'pacman %s\n' "$*" >> "$CALL_LOG"
+    exit "${INSTALL_STATUS:-0}"
+    ;;
+  *) printf 'pacman %s\n' "$*" >> "$CALL_LOG"; exit 99 ;;
+esac
+STUB
+cat > "$scratch/bin/fprintd-enroll" <<'STUB'
+#!/bin/bash
+# Stop before verification/PAM; no host authentication files may be changed.
+echo enroll >> "$CALL_LOG"
+exit 1
+STUB
+cat > "$scratch/bin/fprintd-verify" <<'STUB'
+#!/bin/bash
+echo verify >> "$CALL_LOG"
+exit 1
+STUB
+chmod +x "$scratch/bin/"*
+
+run_setup() {
+  : > "$CALL_LOG"
+  if "$ROOT/bin/omarchy-setup-security-fingerprint" > "$scratch/output" 2>&1; then
+    fail "setup stops on the simulated enrollment or installation failure"
+  fi
+  if grep -q 'Unexpected privileged call' "$CALL_LOG"; then
+    fail "setup does not change PAM after failed enrollment"
+  fi
+}
+
+assert_installs() {
+  grep -qx 'pacman -S --needed --noconfirm --ask 4 libfprint-git fprintd usbutils' "$CALL_LOG" || fail "$1"
+  (( $(grep -c '^pacman ' "$CALL_LOG") == 1 )) || fail "$1: one pacman transaction"
+}
+
+run_setup
+assert_installs "a fresh machine installs libfprint-git, fprintd and usbutils"
+grep -qx enroll "$CALL_LOG" || fail "installation is followed by enrollment"
+pass "a fresh machine installs libfprint-git and reaches enrollment"
+
+INSTALLED=$'libfprint\nfprintd\nusbutils' run_setup
+assert_installs "installed stock libfprint is replaced in the same transaction"
+pass "installed stock libfprint is replaced without a removal step"
+
+INSTALLED=$'libfprint-git\nfprintd\nusbutils' run_setup
+if grep -q '^pacman' "$CALL_LOG"; then
+  fail "a rerun with everything installed does not touch pacman"
+fi
+grep -qx enroll "$CALL_LOG" || fail "a rerun with everything installed reaches enrollment"
+pass "a rerun with everything installed goes straight to enrollment"
+
+INSTALL_STATUS=1 run_setup
+if grep -qx enroll "$CALL_LOG"; then
+  fail "a failed package transaction prevents enrollment"
+fi
+pass "a failed installation stops before enrollment"
+
+HARDWARE_STATUS=1 run_setup
+[[ ! -s $CALL_LOG ]] || fail "missing hardware stops before package operations"
+pass "missing hardware performs no package operations"

From 41b6cc69658d4e3a636bd9356f2b41a9dafcfb22 Mon Sep 17 00:00:00 2001
From: gardensazurescens <gardensazurescens@icloud.com>
Date: Sun, 6 Sep 2026 06:12:07 -0700
Subject: [PATCH 22/27] Add native video wallpaper support (#6792)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Add native video wallpaper support

* Pause video wallpapers while a fullscreen app is focused

* Sample one frame when a video background sets the bar text colour

A video wallpaper made the transparent bar's colour sampling decode the entire file. ImageMagick's video delegate runs ffmpeg with no frame limit, so a twenty-second 1080p background took 11.3s of CPU where one frame takes 0.14s, and it did that on every theme change.

The result was unusable anyway: a multi-frame input emits one value per frame, which the single-value match then rejected, so transparent bars silently fell back to the plain text colour on every video wallpaper. Selecting frame zero fixes the cost and the colour together, and fixes animated GIFs, which had the same bug.

Co-Authored-By: Codex XHigh <noreply@anthropic.com>

* Load wallpaper video lazily, and without an audio output

Three costs the still-image path should never have paid.

BackgroundMedia imported QtMultimedia at file scope and was instantiated on every output, so the module and its audio dependency closure mapped into every shell process whether or not a video was ever shown — measured at +2.72 MiB RSS. Moving the element into its own file behind a Loader that takes a URL defers the whole import: an inactive loader maps none of it, an active one maps all 25 libraries. An inline Component cannot defer that, because the type has to resolve when the file compiles.

Qt's Video convenience type always builds an AudioOutput, and `muted` only aliases that sink's volume, so every monitor decoded an audio stream it would never play and opened an audio client for it. A bare MediaPlayer with no audio output spawns no QFFmpeg::AudioR, QAudioContext or PWDevMon thread, and plays files with no audio track just the same.

The shared image also turned mipmapping on, which the desktop background never had. A full mip chain is about a third more texture memory — 10.6 MiB extra at 4K, per output — for a wallpaper drawn at its own size.

Co-Authored-By: Codex XHigh <noreply@anthropic.com>

* Stop wallpaper playback while the session is locked or screensaved

Playback stopped only for a focused fullscreen window. Locking the session did not stop it, and the lock screen starts a player of its own, so an N-monitor desktop reached 2N decode pipelines the moment it locked — and stayed there, because a display blanked for idle stops being presented but does not stop Qt's FFmpeg engine, which drives its own clock. A laptop locked with the lid shut decoded video until the battery ran out.

The lock and idle services already know both states, so the background service takes the shell reference the loader offers it and reads them. Looking a service up by id needs the registry to be reactive, or a background that loads before the lock service would bind to null and stay there.

Co-Authored-By: Codex XHigh <noreply@anthropic.com>

* Fan out video thumbnails narrower than single-threaded image jobs

The generator fans out one job per core, which was bounded because VIPS_CONCURRENCY=1 made each of them single-threaded. ffmpegthumbnailer leaves FFmpeg's automatic decoder threading on, so a folder of uncached videos put a codec thread pool on every core at once. Queueing video work separately keeps the still-image path at full width and gives the video path a quarter of it.

* Recognize a named video file as a theme preview

The backgrounds fallback beside it already picks videos, so a theme shipping preview.mp4 was the one case that still went unseen.

* Document video backgrounds in the manual

The manual described backgrounds as images only. Worth saying plainly that a video wallpaper costs far more power than a still one and that each monitor decodes its own copy, since neither is visible from the picker.

* Stop the lock screen's own playback once the displays go dark

Pausing the desktop wallpaper on lock only moved the cost. The lock screen builds a player per monitor of its own, so locking an N-monitor session went from N decoders to N rather than to none — and the lock service blanks the displays five seconds later without touching them, which is where a lock spends nearly all of its time. A laptop locked and shut still decoded video into a dark panel.

The service already owns both transitions, so it records whether the displays are dark and the lock view stops playback while they are. The manual said playback stops while the screen is locked, which was the same overstatement; it now says once a locked screen has gone dark.

Co-Authored-By: Codex XHigh <noreply@anthropic.com>

* Keep videos out of the lazy thumbnail path

A lazy row stands in with the media file itself until its thumbnail exists, and the picker draws that with an Image — which shows a picture and shows nothing for a video, with no reload once the real thumbnail lands. So the first open after discovering an uncached video showed a blank tile.

The same branch also spawns one generator per file immediately, before either queue is reached, and the theme switcher always asks for lazy thumbnails. That put the narrower video fan out on the one path that never used it: forty uncached previews meant forty ffmpegthumbnailer processes. Sending videos to the queue instead fixes the blank tile and puts them back under the cap.

Co-Authored-By: Codex XHigh <noreply@anthropic.com>

* Rebuild the theme preview cache after teaching it about video

Preview discovery changed what it recognizes, but its cache keys on theme directory mtimes alone. A theme that already shipped a video preview would keep whatever the old rules cached until something happened to touch the directory. Bumping the version rebuilds it once.

Co-Authored-By: Codex XHigh <noreply@anthropic.com>

* Drop an activeAudioTrack setting that never took effect

Qt's FFmpeg backend ignores setActiveTrack while no source is open, and the literal binding is not reapplied once the media loads and the tracks become known, so the line did nothing. What actually keeps the audio decoder and its client from ever being built is the absent audio output, which a file carrying an audio track confirms on its own: no QFFmpeg::AudioR, QAudioContext or PWDevMon thread appears without it.

Co-Authored-By: Codex XHigh <noreply@anthropic.com>

* Give up the blank state when a display comes back

The lock screen stops its wallpaper while the displays are dark, but it was tracking the blanking it asked for rather than the panels themselves. Opening a docked lid turns the internal panel back on without going through runWake, and so does a resume, which left a visible lock wallpaper frozen on one frame until the next keypress. A frozen wallpaper someone is looking at is worse than the decoding it saves, so a screen change gives the state up.

Co-Authored-By: Codex XHigh <noreply@anthropic.com>

* Time bound the video thumbnail generator

Routing videos through the queue means they are generated before the picker opens rather than behind it, which turned an unreadable or stalled file into a picker that never opens. ffmpegthumbnailer had no bound of its own and the drain waits for every job. A generator that gives up is already handled: the run reports failure, the partial file is removed, and the row drops out of the list.

Co-Authored-By: Codex XHigh <noreply@anthropic.com>

* Pause only the output a fullscreen window covers

The fullscreen test was global, so a game on one monitor stopped the wallpaper on every other one — including the ones still in plain view. That is the failure the lock work was careful to avoid, and it made the manual's claim that playback stops when nothing can see it untrue for the commonest multi-monitor case. A lock or a screensaver does cover every output, so those stay a single decision; fullscreen is now matched against the focused monitor, the way the bar already routes by output.

Co-Authored-By: Codex XHigh <noreply@anthropic.com>

* Kill a video thumbnail generator that ignores the timeout

Plain timeout sends TERM and then waits for a process that may never take it, which leaves the bound it was added for unenforced on exactly the stuck files it was meant to catch.

Co-Authored-By: Codex XHigh <noreply@anthropic.com>

* Pause video wallpapers in battery power-saver

* Fix paused video wallpaper source priming

* Skip snapshots for video background transitions

(cherry picked from commit 6f759538bfa76c2da03634e98ebfc2ebf63ec68e)

* Generate thumbnails for direct-scan videos

(cherry picked from commit 10fcca018a865dca311fb6863e8c8b0057291223)

* Remember a video the thumbnail converter rejected

A permanently unreadable video cost ten seconds of generator time on every
picker open before its row dropped, because nothing recorded the failure.
Both the menu image generator and the direct picker scan now leave a marker
beside the missing thumbnail, keyed like the thumbnail on the file's size
and mtime, so a repaired file starts clean. A timeout is left to retry, as
it may only have been a busy machine.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* Follow the panels' real DPMS state under a locked video wallpaper

The lock screen stopped video playback when it asked for the displays to
blank, and resumed on input, but never checked what the panels did. A blank
that failed left a lit panel on one frozen frame, and a resume that turned
the same outputs back on played nothing until the next keypress.

Quickshell exposes no DPMS signal, so while a video is the locked wallpaper
the lock polls hyprctl and decides per surface from the answer. A wake or
blank request drops the last answer so its optimistic state applies until
the next poll confirms it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* Pause a video wallpaper for the fullscreen window that covers it

The fullscreen check read the globally active window and the focused
monitor, so it only knew about the window that had focus. A fullscreen
window left on one monitor while focus moved to another resumed the
wallpaper decoding behind it, and with fullscreen windows on two outputs
only the focused one paused.

Each output's visible workspace reports whether a fullscreen window covers
it, and Quickshell flips that on the compositor's fullscreen event, so each
panel now decides from its own monitor's active workspace instead.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* Reopen a video wallpaper a theme switch replaced behind its path

Two themes that both ship backgrounds/wallpaper.mp4 leave the current
background at the same path after a switch, so the displayed path never
changed and the running player kept decoding the old file from its open
descriptor. Stills go through the snapshot transition and survive this;
a video switch is instant and did not.

A forced switch onto the path already on show now bumps a reload counter,
and BackgroundMedia rebuilds the video player for it. A cache-busting query
is not an option there, since FFmpeg reads it as part of the filename.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* Keep picker rows uncached while a rejected video is left out

Skipping a video with a failure marker let the picker cache its rows
without it, and cached rows are trusted on the directory's mtime alone.
A file repaired in place never touches that, so the marker's fresh key
was never consulted and the video stayed missing.

The generator now hands the marker back to the row loop, which drops the
row and leaves the rows uncached, so each open re-stats the file and a
repaired one is converted again.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* Hand each background loader only its own kind of file

BackgroundMedia fed one URL to both the still loader and the video player.
On a switch from image to video the Image was handed the video's URL in
the moment before its loader unloaded, so Qt tried to decode the mp4 as a
picture and logged an unsupported format on every such switch; the reverse
handed the player a still to demux.

The still URL is now empty whenever the path is a video and the video URL
empty whenever it is a still, so a switch changes only the loader that
stays.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* Stop a video wallpaper before tearing its player down

Switching from a video to a still destroys the BackgroundVideo item while
its player is mid-read, which FFmpeg reports as a failed open in the shell
journal on every such switch. Stopping the player on destruction lets the
demuxer wind down first, and the switch is quiet.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* Play a video wallpaper's sound track from the first monitor

Video wallpapers were always silent: the player was built without an
audio output, since a muted output still decodes the track and opens an
audio client on every monitor. A video with music should be able to play
it.

The player now builds its AudioOutput only once the media reports a sound
track, so a silent file still opens no audio client, and only the first
screen's panel opts in, so a multi-monitor desktop does not layer copies of
the track. The output is muted while a paused player primes its first
frame, and the lock screen stays silent.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* Keep a departing video player off the still's file

The switch away from a video still logged a cancelled open, and stopping
the player on destruction only hid it: stopping reports the media as
loaded, which the loaded handler answered by playing again. The real cause
was one evaluation pass. Both URLs derived from the `video` flag, which is
itself bound to the path, and QML updates the two in no fixed order, so
the video URL could evaluate against the stale flag and hand the player
the still for a moment. Its destructor then cancelled that open.

Each URL now tests the path directly, the source binding only applies
while the path is a video and restores nothing when it stops, and the
destruction stop goes away with the hazard it introduced.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* Pin the audio wiring in the test and name the output in the manual

The audio assertion passed with the BackgroundMedia forwarding binding
removed, which would have left every wallpaper silent, and did not pin the
silent default or the first-screen selection. It covers all three now.

The manual said the sound track plays "from your first monitor", which
reads as routing to that monitor's audio device. It is the first monitor's
wallpaper that plays, through the default output.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Omabot <omabot@omarchy.org>
Co-authored-by: Codex XHigh <noreply@anthropic.com>
Co-authored-by: z8 <yam@kernelius.com>
Co-authored-by: David Heinemeier Hansson <david@hey.com>
---
 bin/omarchy-bar-text-color                 |   5 +-
 bin/omarchy-menu-images                    |  89 ++++-
 bin/omarchy-theme-bg-next                  |   3 +-
 bin/omarchy-theme-bg-set                   |   8 +-
 bin/omarchy-theme-set                      |  61 +++-
 bin/omarchy-theme-switcher                 |  11 +-
 bin/omarchy-upgrade-to-quattro             |   5 +-
 install/omarchy-base.packages              |   2 +
 manual/39-backgrounds.md                   |   2 +
 migrations/1786609204.sh                   |   3 +
 shell/Commons/Util.qml                     |   4 +
 shell/Ui/BackgroundMedia.qml               |  87 +++++
 shell/Ui/BackgroundVideo.qml               | 122 +++++++
 shell/Ui/qmldir                            |   2 +
 shell/plugins/background/Background.qml    |  65 +++-
 shell/plugins/image-picker/list.sh         |  91 ++++-
 shell/plugins/lock/LockView.qml            |  38 ++-
 shell/plugins/lock/Service.qml             |  70 ++++
 shell/plugins/services/battery/Service.qml |  34 +-
 shell/shell.qml                            |   4 +
 test/shell.d/bar-text-color-test.sh        |  13 +
 test/shell.d/menu-images-test.sh           |   2 +-
 test/shell.d/video-background-test.sh      | 366 +++++++++++++++++++++
 23 files changed, 1009 insertions(+), 78 deletions(-)
 create mode 100644 migrations/1786609204.sh
 create mode 100644 shell/Ui/BackgroundMedia.qml
 create mode 100644 shell/Ui/BackgroundVideo.qml
 create mode 100755 test/shell.d/video-background-test.sh

diff --git a/bin/omarchy-bar-text-color b/bin/omarchy-bar-text-color
index a2ce8cde..35cd0ead 100755
--- a/bin/omarchy-bar-text-color
+++ b/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 \
diff --git a/bin/omarchy-menu-images b/bin/omarchy-menu-images
index 8c316462..8305cb0f 100755
--- a/bin/omarchy-menu-images
+++ b/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
diff --git a/bin/omarchy-theme-bg-next b/bin/omarchy-theme-bg-next
index dfb3d3f0..f9907d7a 100755
--- a/bin/omarchy-theme-bg-next
+++ b/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[@]}
diff --git a/bin/omarchy-theme-bg-set b/bin/omarchy-theme-bg-set
index 45b420df..835321d7 100755
--- a/bin/omarchy-theme-bg-set
+++ b/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
diff --git a/bin/omarchy-theme-set b/bin/omarchy-theme-set
index b6733803..614a8a1b 100755
--- a/bin/omarchy-theme-set
+++ b/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
diff --git a/bin/omarchy-theme-switcher b/bin/omarchy-theme-switcher
index 6d014dd5..49bc127c 100755
--- a/bin/omarchy-theme-switcher
+++ b/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
diff --git a/bin/omarchy-upgrade-to-quattro b/bin/omarchy-upgrade-to-quattro
index 2e9bd759..4dedd961 100755
--- a/bin/omarchy-upgrade-to-quattro
+++ b/bin/omarchy-upgrade-to-quattro
@@ -2078,7 +2078,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
 
diff --git a/install/omarchy-base.packages b/install/omarchy-base.packages
index 03af6299..76e74110 100644
--- a/install/omarchy-base.packages
+++ b/install/omarchy-base.packages
@@ -108,6 +108,8 @@ ttfx
 qemu-user-static-binfmt
 qrencode
 qt6-imageformats
+qt6-multimedia
+qt6-multimedia-ffmpeg
 quickshell
 ripgrep
 ruby
diff --git a/manual/39-backgrounds.md b/manual/39-backgrounds.md
index 6edec391..f2cd51eb 100644
--- a/manual/39-backgrounds.md
+++ b/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.
diff --git a/migrations/1786609204.sh b/migrations/1786609204.sh
new file mode 100644
index 00000000..b7833092
--- /dev/null
+++ b/migrations/1786609204.sh
@@ -0,0 +1,3 @@
+echo "Install native video wallpaper playback dependencies"
+
+omarchy-pkg-add qt6-multimedia qt6-multimedia-ffmpeg
diff --git a/shell/Commons/Util.qml b/shell/Commons/Util.qml
index ca265acd..14af44fe 100644
--- a/shell/Commons/Util.qml
+++ b/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) {
diff --git a/shell/Ui/BackgroundMedia.qml b/shell/Ui/BackgroundMedia.qml
new file mode 100644
index 00000000..b281ae22
--- /dev/null
+++ b/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
+    }
+  }
+}
diff --git a/shell/Ui/BackgroundVideo.qml b/shell/Ui/BackgroundVideo.qml
new file mode 100644
index 00000000..519e8bd9
--- /dev/null
+++ b/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()
+    }
+  }
+}
diff --git a/shell/Ui/qmldir b/shell/Ui/qmldir
index b25bf5ca..63e82639 100644
--- a/shell/Ui/qmldir
+++ b/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
diff --git a/shell/plugins/background/Background.qml b/shell/plugins/background/Background.qml
index 21e1b0a9..dea93a4c 100644
--- a/shell/plugins/background/Background.qml
+++ b/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
diff --git a/shell/plugins/image-picker/list.sh b/shell/plugins/image-picker/list.sh
index a30e4743..0fb74117 100755
--- a/shell/plugins/image-picker/list.sh
+++ b/shell/plugins/image-picker/list.sh
@@ -3,12 +3,18 @@
 image_dirs=${1:-}
 cache_dir=${XDG_CACHE_HOME:-$HOME/.cache}/omarchy/image-selector
 index_file="$cache_dir/index.tsv"
+pending_video_file=$(mktemp)
 
 mkdir -p "$cache_dir"
+trap 'rm -f "$pending_video_file"' EXIT
 
-thumbnail_for() {
+is_video_path() {
+  [[ ${1,,} =~ \.(mp4|m4v|mov|webm|mkv|avi)$ ]]
+}
+
+thumbnail_path_for() {
   local image="$1"
-  local signature hash thumbnail legacy_hash
+  local signature hash
 
   signature=$(stat -Lc '%s:%Y' "$image") || return
   hash=$(awk -F '\t' -v path="$image" -v sig="$signature" '$1 == path && $2 == sig { print $3; exit }' "$index_file" 2>/dev/null)
@@ -17,9 +23,58 @@ thumbnail_for() {
     hash=$(printf '%s\t%s' "$image" "$signature" | md5sum | cut -d ' ' -f 1)
   fi
 
-  thumbnail="$cache_dir/$hash.jpg"
+  printf '%s/%s.jpg' "$cache_dir" "$hash"
+}
 
-  if [[ ! -f $thumbnail ]]; then
+generate_video_thumbnail() {
+  local image="$1"
+  local thumbnail="$2"
+  local lock="$thumbnail.lock"
+  local lock_fd
+  local tmp="$thumbnail.$$.jpg"
+
+  if [[ -d $lock ]] && (( $(date +%s) - $(stat -c '%Y' "$lock" 2>/dev/null || date +%s) > 120 )); then
+    rmdir "$lock" 2>/dev/null
+  fi
+
+  exec {lock_fd}>"$lock" || return
+  flock -w 30 "$lock_fd" || return
+  rm -f "$thumbnail".*.jpg
+
+  [[ -f $thumbnail ]] && return
+
+  if timeout -k 5 10 ffmpegthumbnailer -i "$image" -o "$tmp" -s 1536 -q 8 {lock_fd}>&-; then
+    mv -f "$tmp" "$thumbnail"
+  else
+    status=$?
+    rm -f "$tmp" "$thumbnail"
+    # Remember a rejected video so it costs nothing on the next scan; 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.
+    (( status == 124 || status == 137 )) || : >"$thumbnail.failed"
+    return 1
+  fi
+}
+
+drain_pending_video_thumbnails() {
+  local video_jobs
+
+  [[ -s $pending_video_file ]] || return 0
+
+  video_jobs=$(( $(nproc) / 4 ))
+  (( video_jobs > 0 )) || video_jobs=1
+  export -f generate_video_thumbnail
+  xargs -a "$pending_video_file" -0 -n 2 -P "$video_jobs" \
+    bash -c 'generate_video_thumbnail "$1" "$2"' _ >/dev/null 2>&1 || true
+}
+
+thumbnail_for() {
+  local image="$1"
+  local thumbnail legacy_hash
+
+  thumbnail=$(thumbnail_path_for "$image") || return
+
+  if [[ ! -f $thumbnail ]] && ! is_video_path "$image"; then
     # Older on-demand picker code keyed fallback thumbnails by file content.
     # Keep finding those if a user still has them cached.
     legacy_hash=$(md5sum "$image" 2>/dev/null | cut -d ' ' -f 1)
@@ -28,17 +83,31 @@ thumbnail_for() {
 
   if [[ -f $thumbnail ]]; then
     printf '%s' "$thumbnail"
-  else
+  elif ! is_video_path "$image"; then
     printf '%s' "$image"
   fi
 }
 
-while IFS= read -r dir; do
-  [[ -n $dir && -d $dir ]] || continue
-  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
-done <<<"$image_dirs" | sort -z | while IFS= read -r -d '' image; do
+mapfile -d '' -t images < <(
+  while IFS= read -r dir; do
+    [[ -n $dir && -d $dir ]] || continue
+    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
+  done <<<"$image_dirs" | sort -z
+)
+
+for image in "${images[@]}"; do
+  if is_video_path "$image"; then
+    thumbnail=$(thumbnail_path_for "$image") || continue
+    [[ -f $thumbnail || -f $thumbnail.failed ]] || printf '%s\0%s\0' "$image" "$thumbnail" >>"$pending_video_file"
+  fi
+done
+
+drain_pending_video_thumbnails
+
+for image in "${images[@]}"; do
   thumbnail=$(thumbnail_for "$image")
   [[ -n $thumbnail ]] || continue
   printf '%s\t%s\n' "$image" "$thumbnail"
diff --git a/shell/plugins/lock/LockView.qml b/shell/plugins/lock/LockView.qml
index c2deae0f..e7a430ac 100644
--- a/shell/plugins/lock/LockView.qml
+++ b/shell/plugins/lock/LockView.qml
@@ -14,6 +14,11 @@ Item {
   property int failedAttempts: 0
   property bool inputEnabled: true
   property bool loadBackground: true
+  // A locked session blanks the displays after a few seconds. Nothing is
+  // visible from then until the user wakes it, so a video must not keep
+  // decoding through what is usually the longest part of a lock.
+  property bool displaysBlank: false
+  property bool powerSaverActive: false
   property string passwordText: ""
   property bool syncingPasswordText: false
 
@@ -43,15 +48,6 @@ Item {
   signal clearFailureRequested()
   signal wakeRequested()
 
-  // Cache-busts the lock background by appending `?v=`. Adding a query
-  // string keeps Image's loader happy while forcing it to reload when the
-  // user picks a new background mid-session.
-  function fileUrl(path) {
-    if (!path) return ""
-    var encoded = String(path).split("/").map(encodeURIComponent).join("/")
-    return "file://" + encoded + "?v=" + backgroundVersion
-  }
-
   function forcePasswordFocus() {
     passwordInput.forceActiveFocus()
   }
@@ -90,28 +86,34 @@ Item {
     anchors.fill: parent
     color: Color.background
 
-    Image {
+    BackgroundMedia {
       id: wallpaper
       anchors.fill: parent
-      source: root.loadBackground ? root.fileUrl(root.backgroundPath) : ""
-      fillMode: Image.PreserveAspectCrop
-      asynchronous: true
-      cache: false
-      sourceSize.width: width
-      sourceSize.height: height
+      path: root.loadBackground ? root.backgroundPath : ""
+      version: root.backgroundVersion
+      playbackEnabled: root.loadBackground && !root.displaysBlank && !root.powerSaverActive
     }
 
     MultiEffect {
       anchors.fill: wallpaper
-      source: wallpaper
+      source: wallpaper.video ? null : wallpaper
+      visible: !wallpaper.video
       autoPaddingEnabled: false
-      blurEnabled: root.loadBackground && wallpaper.status === Image.Ready
+      blurEnabled: root.loadBackground && wallpaper.ready
       blur: 1.0
       blurMax: 128
       blurMultiplier: 1.25
       contrast: -0.08
     }
 
+    // Qt's video output cannot be sampled by MultiEffect on every renderer.
+    // Keep video wallpapers visible and darken them slightly for legibility.
+    Rectangle {
+      anchors.fill: wallpaper
+      visible: wallpaper.video
+      color: "#22000000"
+    }
+
     MouseArea {
       anchors.fill: parent
       hoverEnabled: true
diff --git a/shell/plugins/lock/Service.qml b/shell/plugins/lock/Service.qml
index 9ecb1cc0..94d43b68 100644
--- a/shell/plugins/lock/Service.qml
+++ b/shell/plugins/lock/Service.qml
@@ -31,11 +31,21 @@ Item {
   property int backgroundVersion: 0
   property string lastEvent: "init"
   property string lastEventAt: ""
+  property bool displaysBlank: false
+  // displaysBlank tracks what the lock asked for; Hyprland reports what each
+  // panel actually did. While a video is on show the two are reconciled, so a
+  // blank that failed keeps playing and a panel woken behind the lock's back
+  // (a resume that kept the same outputs) resumes instead of freezing.
+  property var monitorDpms: ({})
+  property bool monitorDpmsKnown: false
+  readonly property bool videoBackground: Util.isVideoPath(backgroundPath)
   property bool strandedLock: false
   property bool strandedLockResolved: false
 
   readonly property bool locked: lockRequested || sessionLock.locked || sessionLock.secure
   readonly property bool authenticating: authenticatingPassword || fingerprintAuthenticating
+  readonly property var batteryService: shell && shell.services ? shell.firstPartyServiceFor("omarchy.battery") : null
+  readonly property bool powerSaverActive: batteryService ? batteryService.powerSaverOnBattery : false
 
   function realScreenCount() {
     var screens = Quickshell.screens || []
@@ -165,14 +175,42 @@ Item {
   }
 
   function runWake() {
+    root.displaysBlank = false
+    root.monitorDpmsKnown = false
     if (!wakeProcess.running) wakeProcess.running = true
     if (lockRequested) armBlankTimer()
   }
 
   function runBlank() {
+    root.displaysBlank = true
+    root.monitorDpmsKnown = false
     if (!blankProcess.running) blankProcess.running = true
   }
 
+  function screenBlank(screenName) {
+    var name = String(screenName || "")
+    if (!monitorDpmsKnown || !(name in monitorDpms)) return displaysBlank
+    return !monitorDpms[name]
+  }
+
+  function applyMonitorDpms(text) {
+    var monitors
+    try {
+      monitors = JSON.parse(String(text || ""))
+    } catch (error) {
+      return
+    }
+    if (!Array.isArray(monitors)) return
+
+    var dpms = {}
+    for (var i = 0; i < monitors.length; i++) {
+      var monitor = monitors[i]
+      if (monitor && monitor.name && !monitor.disabled) dpms[String(monitor.name)] = !!monitor.dpmsStatus
+    }
+    monitorDpms = dpms
+    monitorDpmsKnown = true
+  }
+
   function submitPassword(value) {
     var password = String(value || "")
     if (!lockRequested || authenticatingPassword || password.length === 0) return
@@ -276,6 +314,8 @@ Item {
         failedAttempts: root.failedAttempts
         inputEnabled: root.lockRequested
         loadBackground: root.locked
+        displaysBlank: root.screenBlank(lockSurface.screen ? lockSurface.screen.name : "")
+        powerSaverActive: root.powerSaverActive
         passwordText: root.enteredPassword
         onPasswordTextEdited: function(password) { root.enteredPassword = password }
         onSubmitPassword: function(password) { root.submitPassword(password) }
@@ -306,6 +346,7 @@ Item {
       failedAttempts: 0
       inputEnabled: false
       loadBackground: root.previewVisible
+      powerSaverActive: root.powerSaverActive
       passwordText: ""
     }
 
@@ -411,6 +452,31 @@ Item {
     command: ["bash", "-c", "omarchy-brightness-keyboard off; omarchy-brightness-display off"]
   }
 
+  // Quickshell exposes no DPMS signal, so the panel state is polled while a
+  // video is the locked wallpaper. A wake or blank request drops the last
+  // answer, so its optimistic state applies until the next poll confirms it.
+  Process {
+    id: monitorDpmsProcess
+    command: ["hyprctl", "monitors", "-j"]
+    stdout: StdioCollector {
+      onStreamFinished: root.applyMonitorDpms(text)
+    }
+  }
+
+  Timer {
+    id: monitorDpmsTimer
+    interval: 3000
+    repeat: true
+    triggeredOnStart: true
+    running: root.locked && root.videoBackground
+    onTriggered: {
+      if (!monitorDpmsProcess.running) monitorDpmsProcess.running = true
+    }
+    onRunningChanged: {
+      if (!running) root.monitorDpmsKnown = false
+    }
+  }
+
   Timer {
     id: idleBlankTimer
     interval: 5000
@@ -467,6 +533,10 @@ Item {
   Connections {
     target: Quickshell
     function onScreensChanged() {
+      // A panel coming back is a display turning on that runWake did not ask
+      // for, so the blank state has to be given up here or a visible lock
+      // wallpaper stays frozen until the next keypress.
+      root.displaysBlank = false
       root.requestSessionLock()
 
       // A monitor still coming up has no workspace, so cannot answer yet.
diff --git a/shell/plugins/services/battery/Service.qml b/shell/plugins/services/battery/Service.qml
index 37fdf5c7..a1b01cff 100644
--- a/shell/plugins/services/battery/Service.qml
+++ b/shell/plugins/services/battery/Service.qml
@@ -12,6 +12,8 @@ Item {
 
   readonly property int batteryThreshold: 10
   property string pendingPowerSource: ""
+  property string activePowerProfile: ""
+  readonly property bool powerSaverOnBattery: UPower.onBattery && activePowerProfile === "power-saver"
 
   PersistentProperties {
     id: persisted
@@ -53,11 +55,38 @@ Item {
     powerProfileProcess.running = true
   }
 
+  function refreshPowerProfile() {
+    if (!powerProfileReadProcess.running) powerProfileReadProcess.running = true
+  }
+
   Process { id: warningProcess }
 
   Process {
     id: powerProfileProcess
-    onExited: if (root.pendingPowerSource !== "") root.runPendingPowerProfile()
+    onExited: {
+      if (root.pendingPowerSource !== "") root.runPendingPowerProfile()
+      root.refreshPowerProfile()
+    }
+  }
+
+  Process {
+    id: powerProfileReadProcess
+    command: ["powerprofilesctl", "get"]
+    stdout: StdioCollector {
+      waitForEnd: true
+      onStreamFinished: root.activePowerProfile = String(text || "").trim()
+    }
+  }
+
+  Timer {
+    // powerprofilesctl has no portable monitor subcommand; keep profile changes
+    // visible to consumers such as the wallpaper service without requiring the
+    // power panel to be open.
+    interval: 2000
+    running: true
+    repeat: true
+    triggeredOnStart: true
+    onTriggered: root.refreshPowerProfile()
   }
 
   Timer {
@@ -73,6 +102,9 @@ Item {
     function onOnBatteryChanged() {
       root.checkBattery()
       root.applyPowerProfile()
+      root.refreshPowerProfile()
     }
   }
+
+  Component.onCompleted: root.refreshPowerProfile()
 }
diff --git a/shell/shell.qml b/shell/shell.qml
index 7e1cf75d..37a0fe6e 100644
--- a/shell/shell.qml
+++ b/shell/shell.qml
@@ -272,6 +272,10 @@ ShellRoot {
 
   property var _services: ({})
 
+  // Reassigned as each service registers, so a binding that reads this before
+  // looking a service up by id re-evaluates once that service exists.
+  readonly property var services: _services
+
   function serviceFor(pluginId) {
     return _services[String(pluginId)] || null
   }
diff --git a/test/shell.d/bar-text-color-test.sh b/test/shell.d/bar-text-color-test.sh
index b7626c2b..d22a289c 100755
--- a/test/shell.d/bar-text-color-test.sh
+++ b/test/shell.d/bar-text-color-test.sh
@@ -5,6 +5,7 @@ set -euo pipefail
 source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
 
 require_command magick
+require_command ffmpeg
 
 TMPDIR=$(mktemp -d)
 trap 'rm -rf "$TMPDIR"' EXIT
@@ -28,3 +29,15 @@ pass "transparent bar text keeps text color on dark wallpaper"
 result=$(HOME="$TMPDIR" omarchy-bar-text-color top 20 '#ffffff' '#101010' --background "$TMPDIR/missing.png" --screen 100x100)
 [[ $result == "#ffffff" ]] || fail "transparent bar text falls back to text color when sampling fails" "expected #ffffff, got $result"
 pass "transparent bar text falls back to text color when sampling fails"
+
+# A video background must be sampled one frame at a time. Reading the whole file
+# emits a value per frame, which parses as nothing and silently falls back —
+# and decodes the entire wallpaper to find that out.
+light_top_video="$TMPDIR/light-top.mp4"
+ffmpeg -y -f lavfi -i "testsrc=size=640x360:rate=10:duration=2" \
+  -vf "drawbox=x=0:y=0:w=640:h=40:color=0xf5f5f5:t=fill" \
+  -c:v libx264 -preset ultrafast -pix_fmt yuv420p "$light_top_video" -loglevel error
+
+result=$(HOME="$TMPDIR" omarchy-bar-text-color top 40 '#ffffff' '#101010' --background "$light_top_video" --screen 640x360)
+[[ $result == "#101010" ]] || fail "transparent bar text samples one frame of a video wallpaper" "expected #101010, got $result"
+pass "transparent bar text samples one frame of a video wallpaper"
diff --git a/test/shell.d/menu-images-test.sh b/test/shell.d/menu-images-test.sh
index ac20a8ca..179dcb6b 100644
--- a/test/shell.d/menu-images-test.sh
+++ b/test/shell.d/menu-images-test.sh
@@ -69,7 +69,7 @@ PATH="$stub_bin:$PATH" XDG_CACHE_HOME="$cache_home" \
   fail "image menu recovers thumbnails from stranded locks"
 (( $(awk 'END { print NR }' "$cache_dir/$cache_key.rows") == 3 )) ||
   fail "image menu rebuilds every row after cache invalidation"
-[[ $(head -n 1 "$cache_dir/$cache_key.signature") == "v3" ]] ||
+[[ $(head -n 1 "$cache_dir/$cache_key.signature") == "v4" ]] ||
   fail "image menu invalidates stale row caches"
 [[ ! -e $stale_tmp ]] ||
   fail "image menu clears partial thumbnails left by killed generators"
diff --git a/test/shell.d/video-background-test.sh b/test/shell.d/video-background-test.sh
new file mode 100755
index 00000000..1a15dace
--- /dev/null
+++ b/test/shell.d/video-background-test.sh
@@ -0,0 +1,366 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+run_node_test <<'JS'
+const fs = require('fs')
+
+const utilQml = fs.readFileSync(path.join(root, 'shell/Commons/Util.qml'), 'utf8')
+const mediaQml = fs.readFileSync(path.join(root, 'shell/Ui/BackgroundMedia.qml'), 'utf8')
+const videoQml = fs.readFileSync(path.join(root, 'shell/Ui/BackgroundVideo.qml'), 'utf8')
+const backgroundQml = fs.readFileSync(path.join(root, 'shell/plugins/background/Background.qml'), 'utf8')
+const lockQml = fs.readFileSync(path.join(root, 'shell/plugins/lock/LockView.qml'), 'utf8')
+const themeSwitcher = fs.readFileSync(path.join(root, 'bin/omarchy-theme-switcher'), 'utf8')
+const quattroUpgrade = fs.readFileSync(path.join(root, 'bin/omarchy-upgrade-to-quattro'), 'utf8')
+const multimediaMigration = fs.readFileSync(path.join(root, 'migrations/1786609204.sh'), 'utf8')
+const barTextColor = fs.readFileSync(path.join(root, 'bin/omarchy-bar-text-color'), 'utf8')
+const menuImages = fs.readFileSync(path.join(root, 'bin/omarchy-menu-images'), 'utf8')
+const lockView = fs.readFileSync(path.join(root, 'shell/plugins/lock/LockView.qml'), 'utf8')
+const lockService = fs.readFileSync(path.join(root, 'shell/plugins/lock/Service.qml'), 'utf8')
+const batteryService = fs.readFileSync(path.join(root, 'shell/plugins/services/battery/Service.qml'), 'utf8')
+const themeSet = fs.readFileSync(path.join(root, 'bin/omarchy-theme-set'), 'utf8')
+const directImageList = fs.readFileSync(path.join(root, 'shell/plugins/image-picker/list.sh'), 'utf8')
+
+assert(
+  /function isVideoPath\(path\)[\s\S]*\.test\(String\(path \|\| ""\)\)/.test(utilQml) &&
+    !utilQml.includes('split(/[?#]/)'),
+  'shared media helper identifies video paths without truncating valid local names'
+)
+assert(
+  videoQml.includes('loops: MediaPlayer.Infinite') &&
+    videoQml.includes('autoPlay: root.playbackEnabled') &&
+    videoQml.includes('fillMode: VideoOutput.PreserveAspectCrop') &&
+    /imageUrl: path && !Util\.isVideoPath\(path\) \? Util\.fileUrl\(path\) \+ \(version \? "\?v=" \+ version : ""\) : ""/.test(mediaQml) &&
+    /videoUrl: path && Util\.isVideoPath\(path\) \? Util\.fileUrl\(path\) : ""/.test(mediaQml),
+  'background media plays aspect-cropped videos on a loop, and hands each loader only its own kind of file'
+)
+assert(
+  videoQml.includes('MediaPlayer.LoadedMedia') &&
+    videoQml.includes('primePauseTimer') &&
+    videoQml.includes('mediaGeneration') &&
+    videoQml.includes('videoSink') &&
+    videoQml.includes('onVideoFrameChanged') &&
+    videoQml.includes('MediaPlayer.BufferedMedia') &&
+    videoQml.includes('mediaStatus !== MediaPlayer.BufferedMedia') &&
+    videoQml.includes('interval: 1000') &&
+    videoQml.includes('interval: 50') &&
+    videoQml.includes('frameReceived') &&
+    videoQml.includes('output.clearOutput()') &&
+    !videoQml.includes('KeepLastFrame') &&
+    /onPlaybackEnabledChanged:[\s\S]*?if \(playbackEnabled\) player\.play\(\)[\s\S]*?else player\.pause\(\)/.test(videoQml) &&
+    videoQml.includes('primingGeneration') &&
+    videoQml.includes('player.play()') &&
+    videoQml.includes('player.pause()'),
+  'paused video sources are primed to display their first frame'
+)
+assert(
+  !/^\s*import QtMultimedia/m.test(mediaQml) &&
+    mediaQml.includes('source: "BackgroundVideo.qml"'),
+  'the still-image path never imports QtMultimedia, so image-only sessions do not map it'
+)
+assert(
+  !/^\s*Video\s*\{/m.test(videoQml) &&
+    /property bool audioEnabled: false/.test(videoQml) &&
+    /property bool audioEnabled: false/.test(mediaQml) &&
+    /active: root\.audioEnabled && player\.hasAudio/.test(videoQml) &&
+    /audioOutput: audioLoader\.item/.test(videoQml) &&
+    /muted: root\.priming \|\| !root\.playbackEnabled/.test(videoQml) &&
+    /property: "audioEnabled"\s*\n\s*value: root\.audioEnabled/.test(mediaQml) &&
+    /firstScreen: Quickshell\.screens\.length > 0\s*\n\s*&& String\(Quickshell\.screens\[0\]\.name/.test(backgroundQml) &&
+    backgroundQml.includes('audioEnabled: panel.firstScreen') &&
+    !lockQml.includes('audioEnabled'),
+  'a sound track plays from the first monitor only, a silent file builds no audio output, and the lock stays quiet'
+)
+assert(
+  /property: "mediaSource"[\s\S]*?when: videoLoader\.item !== null && Util\.isVideoPath\(root\.path\)\s*\n\s*restoreMode: Binding\.RestoreNone/.test(mediaQml) &&
+    !videoQml.includes('Component.onDestruction'),
+  'a player on its way out keeps its source, so nothing is left loading for its destructor to cancel'
+)
+assert(
+  !mediaQml.includes('mipmap'),
+  'the shared image path leaves mipmapping off, as the desktop background had it'
+)
+assert(
+  /instant \|\| !displayedBackground \|\| isVideo\(path\) \|\| isVideo\(displayedBackground\)[\s\S]*displayedBackground = finalPath/.test(backgroundQml),
+  'video switches bypass the image-only reveal stack and use the durable background path'
+)
+assert(backgroundQml.includes('BackgroundMedia {') && lockQml.includes('BackgroundMedia {'), 'desktop and lock screen share video-capable media rendering')
+assert(
+  lockQml.includes('source: wallpaper.video ? null : wallpaper') &&
+    lockQml.includes('visible: !wallpaper.video') &&
+    lockQml.includes('visible: wallpaper.video'),
+  'lock screen bypasses its image effect for video output'
+)
+assert(
+  /sessionObscured:\s*lockActive \|\| screensaverActive/.test(backgroundQml) &&
+    backgroundQml.includes('playbackEnabled: !root.sessionObscured && !root.powerSaverActive && !panel.fullscreenHere') &&
+    backgroundQml.includes('omarchy.lock') &&
+    backgroundQml.includes('omarchy.idle') &&
+    backgroundQml.includes('omarchy.battery'),
+  'desktop playback stops while covered or on battery power-saver'
+)
+assert(
+  backgroundQml.includes('Hyprland.monitorFor(modelData)') &&
+    /fullscreenHere: visibleWorkspace \? visibleWorkspace\.hasFullscreen : false/.test(backgroundQml) &&
+    !backgroundQml.includes('ToplevelManager.activeToplevel'),
+  'a fullscreen window pauses only the output it covers, wherever focus is'
+)
+assert(
+  /if \(displayedBackground === finalPath\) displayedReloads \+= 1/.test(backgroundQml) &&
+    backgroundQml.includes('reloads: root.displayedReloads') &&
+    /active: root\.path !== "" && root\.video && !root\.reloading/.test(mediaQml) &&
+    /onReloadsChanged: \{[\s\S]*?reloading = true/.test(mediaQml),
+  'a theme switch that keeps the video path still reopens the replaced file'
+)
+assert(
+  barTextColor.includes('magick "$background_path[0]"'),
+  'bar colour sampling reads one frame instead of decoding a whole video'
+)
+assert(
+  menuImages.includes('pending_video_file') && /video_jobs=\$\(\( \$\(nproc\) \/ 4 \)\)/.test(menuImages),
+  'video thumbnails fan out narrower than single-threaded vips jobs'
+)
+assert(
+  themeSwitcher.includes('fast_signature="v2"'),
+  'the theme preview cache rebuilds after preview discovery learned about video'
+)
+assert(
+  /lazy_thumbnails == true && \$cache_only != true \]\] && ! is_video_path/.test(menuImages),
+  'a video never stands in as its own lazy thumbnail, so the fan out cap always applies'
+)
+assert(
+  /thumbnail_command=\(timeout -k \d+ \d+ ffmpegthumbnailer/.test(menuImages),
+  'a stalled video cannot hold the picker shut, because its generator is time bounded'
+)
+assert(
+  directImageList.includes('generate_video_thumbnail') &&
+    /timeout -k \d+ \d+ ffmpegthumbnailer/.test(directImageList) &&
+    /if \[\[ ! -f \$thumbnail \]\] && ! is_video_path/.test(directImageList),
+  'a direct picker scan generates bounded video thumbnails without content-hashing the media'
+)
+assert(
+  themeSet.includes('choose_staged_theme_background') &&
+    themeSet.includes('background_transition_uses_snapshots') &&
+    themeSet.includes('BACKGROUND_TRANSITION_SNAPSHOTS=false') &&
+    /if \[\[ \$BACKGROUND_TRANSITION_SNAPSHOTS == "true" \]\]/.test(themeSet) &&
+    /if \[\[ -z \$CHOSEN_THEME_BACKGROUND \|\| ! -f \$CHOSEN_THEME_BACKGROUND \]\]/.test(themeSet),
+  'theme changes disable both transition snapshots whenever either side is a video'
+)
+assert(
+  /function onScreensChanged\(\) \{[\s\S]*?root\.displaysBlank = false/.test(lockService),
+  'a display coming back gives up the blank state instead of freezing a visible wallpaper'
+)
+assert(
+  lockService.includes('function screenBlank(screenName)') &&
+    lockService.includes('function applyMonitorDpms(text)') &&
+    lockService.includes('command: ["hyprctl", "monitors", "-j"]') &&
+    lockService.includes('running: root.locked && root.videoBackground') &&
+    /displaysBlank: root\.screenBlank\(lockSurface\.screen/.test(lockService) &&
+    /function runWake\(\) \{[\s\S]*?root\.monitorDpmsKnown = false/.test(lockService) &&
+    /function runBlank\(\) \{[\s\S]*?root\.monitorDpmsKnown = false/.test(lockService),
+  'a locked video wallpaper follows what each panel actually did, not only what the lock asked for'
+)
+assert(
+  lockView.includes('playbackEnabled: root.loadBackground && !root.displaysBlank') &&
+    lockView.includes('&& !root.powerSaverActive') &&
+    /displaysBlank: root\.screenBlank\(/.test(lockService) &&
+    /powerSaverActive: root\.powerSaverActive/.test(lockService) &&
+    /function runBlank\(\) \{\s*\n\s*root\.displaysBlank = true/.test(lockService) &&
+    /function runWake\(\) \{\s*\n\s*root\.displaysBlank = false/.test(lockService),
+  'the lock screen stops playback once displays go dark or power-saver is active'
+)
+assert(
+  batteryService.includes('property string activePowerProfile') &&
+    batteryService.includes('UPower.onBattery && activePowerProfile === "power-saver"') &&
+    batteryService.includes('["powerprofilesctl", "get"]') &&
+    batteryService.includes('interval: 2000'),
+  'the battery service tracks the active power-saver profile'
+)
+assert(
+  themeSwitcher.includes("-iname '*.mp4'") &&
+    themeSwitcher.includes('mp4 m4v mov webm mkv avi') &&
+    themeSwitcher.includes('preview.mp4'),
+  'theme switcher previews video-only themes, named preview files included'
+)
+assert(quattroUpgrade.includes("-iname '*.mp4'"), 'Quattro upgrade can seed a video-only theme background')
+assert(
+  multimediaMigration.includes('omarchy-pkg-add qt6-multimedia qt6-multimedia-ffmpeg'),
+  'existing Quattro installations receive video playback dependencies'
+)
+JS
+
+test_tmp=$(mktemp -d)
+trap 'rm -rf "$test_tmp"' EXIT
+mkdir -p "$test_tmp/bin" "$test_tmp/backgrounds" "$test_tmp/generator-cache" "$test_tmp/direct-cache"
+printf 'not a real video\n' >"$test_tmp/backgrounds/sample.mp4"
+
+cat >"$test_tmp/bin/ffmpegthumbnailer" <<'SH'
+#!/bin/bash
+while (( $# > 0 )); do
+  case "$1" in
+    -i) input=$2; shift 2 ;;
+    -o) output=$2; shift 2 ;;
+    *) shift ;;
+  esac
+done
+printf 'thumbnail for %s\n' "$input" >"$output"
+SH
+chmod +x "$test_tmp/bin/ffmpegthumbnailer"
+
+cat >"$test_tmp/bin/md5sum" <<'SH'
+#!/bin/bash
+if (( $# > 0 )); then
+  printf 'unexpected file hash: %s\n' "$*" >>"$MD5_FILE_CALLS"
+fi
+exec /usr/bin/md5sum "$@"
+SH
+chmod +x "$test_tmp/bin/md5sum"
+
+md5_file_calls="$test_tmp/md5-file-calls"
+PATH="$test_tmp/bin:$PATH" XDG_CACHE_HOME="$test_tmp/generator-cache" MD5_FILE_CALLS="$md5_file_calls" \
+  "$ROOT/bin/omarchy-menu-images" --prepare-only "$test_tmp/backgrounds"
+
+generator_thumbnail=$(find "$test_tmp/generator-cache/omarchy/image-selector" -maxdepth 1 -type f -name '*.jpg' -print -quit)
+[[ -s $generator_thumbnail ]] || fail "menu image generator creates a video thumbnail"
+
+generator_row=$(XDG_CACHE_HOME="$test_tmp/generator-cache" "$ROOT/shell/plugins/image-picker/list.sh" "$test_tmp/backgrounds")
+IFS=$'\t' read -r generator_row_path generator_row_thumbnail <<<"$generator_row"
+[[ $generator_row_path == "$test_tmp/backgrounds/sample.mp4" && $generator_row_thumbnail == "$generator_thumbnail" ]] || \
+  fail "direct picker consumes the menu image generator thumbnail" "$generator_row"
+
+row=$(PATH="$test_tmp/bin:$PATH" XDG_CACHE_HOME="$test_tmp/direct-cache" MD5_FILE_CALLS="$md5_file_calls" \
+  "$ROOT/shell/plugins/image-picker/list.sh" "$test_tmp/backgrounds")
+
+IFS=$'\t' read -r row_path row_thumbnail <<<"$row"
+[[ $row_path == "$test_tmp/backgrounds/sample.mp4" && $row_thumbnail == *.jpg && -s $row_thumbnail ]] || \
+  fail "image picker lists videos with their cached thumbnail" "$row"
+[[ ! -s $md5_file_calls ]] || fail "direct video scans avoid hashing the complete media file" "$(<"$md5_file_calls")"
+
+failed_backgrounds="$test_tmp/failed-backgrounds"
+failed_cache="$test_tmp/failed-cache"
+mkdir -p "$failed_backgrounds" "$failed_cache"
+printf 'broken video\n' >"$failed_backgrounds/broken.mp4"
+cat >"$test_tmp/bin/ffmpegthumbnailer" <<'SH'
+#!/bin/bash
+exit 1
+SH
+
+cached_row=$(PATH="$test_tmp/bin:$PATH" XDG_CACHE_HOME="$test_tmp/direct-cache" MD5_FILE_CALLS="$md5_file_calls" \
+  "$ROOT/shell/plugins/image-picker/list.sh" "$test_tmp/backgrounds")
+[[ $cached_row == "$row" ]] || fail "direct picker reuses its cached video thumbnail" "$cached_row"
+
+failed_rows=$(PATH="$test_tmp/bin:$PATH" XDG_CACHE_HOME="$failed_cache" MD5_FILE_CALLS="$md5_file_calls" \
+  "$ROOT/shell/plugins/image-picker/list.sh" "$failed_backgrounds")
+[[ -z $failed_rows ]] || fail "direct picker omits a video whose thumbnail fails" "$failed_rows"
+
+failed_marker=$(find "$failed_cache/omarchy/image-selector" -maxdepth 1 -type f -name '*.failed' -print -quit)
+[[ -n $failed_marker ]] || fail "direct picker remembers a video the converter rejected"
+
+thumbnailer_calls="$test_tmp/thumbnailer-calls"
+cat >"$test_tmp/bin/ffmpegthumbnailer" <<'SH'
+#!/bin/bash
+printf '%s\n' "$*" >>"$THUMBNAILER_CALLS"
+exit 1
+SH
+
+failed_rows=$(PATH="$test_tmp/bin:$PATH" XDG_CACHE_HOME="$failed_cache" THUMBNAILER_CALLS="$thumbnailer_calls" \
+  "$ROOT/shell/plugins/image-picker/list.sh" "$failed_backgrounds")
+[[ -z $failed_rows && ! -e $thumbnailer_calls ]] || fail "direct picker skips a rejected video on the next scan" "$(cat "$thumbnailer_calls" 2>/dev/null)"
+
+generator_failed_cache="$test_tmp/generator-failed-cache"
+PATH="$test_tmp/bin:$PATH" XDG_CACHE_HOME="$generator_failed_cache" THUMBNAILER_CALLS="$thumbnailer_calls" \
+  "$ROOT/bin/omarchy-menu-images" --prepare-only "$failed_backgrounds"
+[[ -s $thumbnailer_calls ]] || fail "menu image generator tries a video it has not seen"
+generator_marker=$(find "$generator_failed_cache/omarchy/image-selector" -maxdepth 1 -type f -name '*.failed' -print -quit)
+[[ -n $generator_marker ]] || fail "menu image generator remembers a video the converter rejected"
+rm -f "$thumbnailer_calls"
+PATH="$test_tmp/bin:$PATH" XDG_CACHE_HOME="$generator_failed_cache" THUMBNAILER_CALLS="$thumbnailer_calls" \
+  "$ROOT/bin/omarchy-menu-images" --prepare-only "$failed_backgrounds"
+[[ ! -e $thumbnailer_calls ]] || fail "menu image generator skips a rejected video on the next open" "$(<"$thumbnailer_calls")"
+
+# A repaired file gets a fresh key, so the old marker no longer applies, and
+# the rows are not cached over its absence, so an in-place repair that leaves
+# the directory's mtime alone is still noticed.
+touch -d '2 minutes' "$failed_backgrounds/broken.mp4"
+PATH="$test_tmp/bin:$PATH" XDG_CACHE_HOME="$generator_failed_cache" THUMBNAILER_CALLS="$thumbnailer_calls" \
+  "$ROOT/bin/omarchy-menu-images" --prepare-only "$failed_backgrounds"
+[[ -s $thumbnailer_calls ]] || fail "menu image generator retries a video that changed since it was rejected"
+
+timeout_backgrounds="$test_tmp/timeout-backgrounds"
+timeout_cache="$test_tmp/timeout-cache"
+mkdir -p "$timeout_backgrounds"
+printf 'slow video\n' >"$timeout_backgrounds/slow.mp4"
+cat >"$test_tmp/bin/ffmpegthumbnailer" <<'SH'
+#!/bin/bash
+exit 124
+SH
+timeout_rows=$(PATH="$test_tmp/bin:$PATH" XDG_CACHE_HOME="$timeout_cache" \
+  "$ROOT/shell/plugins/image-picker/list.sh" "$timeout_backgrounds")
+[[ -z $timeout_rows ]] || fail "direct picker omits a video whose thumbnail timed out" "$timeout_rows"
+timeout_marker=$(find "$timeout_cache/omarchy/image-selector" -maxdepth 1 -type f -name '*.failed' -print -quit)
+[[ -z $timeout_marker ]] || fail "a timed out video is left to retry rather than remembered as failed"
+
+grep -qx 'qt6-multimedia' "$ROOT/install/omarchy-base.packages" || fail "Qt Multimedia runtime is a base package"
+grep -qx 'qt6-multimedia-ffmpeg' "$ROOT/install/omarchy-base.packages" || fail "Qt Multimedia FFmpeg backend is a base package"
+
+pass "menu image generator creates thumbnails consumed by the picker"
+pass "direct picker generates and reuses still thumbnails"
+pass "direct picker omits videos whose thumbnails cannot be generated"
+pass "a rejected video is remembered so it costs nothing on the next open"
+pass "a timed out video is left to retry"
+pass "a locked video wallpaper follows the panels' real DPMS state"
+pass "Qt Multimedia playback dependencies are declared"
+
+source <(awk '
+  /^(is_video_path|snapshot_background_path|background_transition_uses_snapshots|choose_theme_background|choose_staged_theme_background|set_theme_background)\(\) \{/ { copying=1 }
+  copying { print }
+  copying && /^}$/ { copying=0 }
+' "$ROOT/bin/omarchy-theme-set")
+
+transition_home="$test_tmp/transition-home"
+CURRENT_THEME_PATH="$transition_home/.local/state/omarchy/current/theme"
+NEXT_THEME_PATH="$transition_home/.local/state/omarchy/current/next-theme"
+CURRENT_BACKGROUND_LINK="$transition_home/.local/state/omarchy/current/background"
+BACKGROUND_TRANSITION_CACHE="$transition_home/.cache/omarchy/background-transitions"
+THEME_NAME="video-test"
+HOME="$transition_home"
+mkdir -p "$CURRENT_THEME_PATH/backgrounds" "$NEXT_THEME_PATH/backgrounds" "$HOME/.config/omarchy/backgrounds/$THEME_NAME"
+printf 'old image\n' >"$CURRENT_THEME_PATH/backgrounds/old.png"
+printf 'old image staged\n' >"$NEXT_THEME_PATH/backgrounds/old.png"
+printf 'new video\n' >"$NEXT_THEME_PATH/backgrounds/new.mp4"
+ln -s "$CURRENT_THEME_PATH/backgrounds/old.png" "$CURRENT_BACKGROUND_LINK"
+
+choose_staged_theme_background || fail "staged video background is selected before the theme swap"
+expected_staged_background="$CURRENT_THEME_PATH/backgrounds/new.mp4"
+[[ $CHOSEN_THEME_BACKGROUND == $expected_staged_background ]] || \
+  fail "staged background resolves to its durable post-swap path" "$CHOSEN_THEME_BACKGROUND"
+if background_transition_uses_snapshots "$CHOSEN_THEME_BACKGROUND"; then
+  fail "image to video theme transitions skip snapshots"
+fi
+background_transition_uses_snapshots "$CURRENT_THEME_PATH/backgrounds/new.png" || \
+  fail "image to image theme transitions retain snapshots"
+
+rm "$CURRENT_BACKGROUND_LINK"
+printf 'old video\n' >"$CURRENT_THEME_PATH/backgrounds/old.mp4"
+ln -s "$CURRENT_THEME_PATH/backgrounds/old.mp4" "$CURRENT_BACKGROUND_LINK"
+if background_transition_uses_snapshots "$CURRENT_THEME_PATH/backgrounds/new.png"; then
+  fail "video to image theme transitions skip snapshots"
+fi
+
+video_snapshot=$(snapshot_background_path "$CURRENT_THEME_PATH/backgrounds/old.mp4" "video")
+[[ -z $video_snapshot && ! -e $BACKGROUND_TRANSITION_CACHE ]] || fail "video files are never snapshotted"
+
+CHOSEN_THEME_BACKGROUND="$transition_home/disappeared.mp4"
+BACKGROUND_TRANSITION_SNAPSHOTS=false
+OLD_BACKGROUND_SNAPSHOT=""
+colors_payload=""
+shell_payload=""
+shell_ipc() { :; }
+set_theme_background
+[[ -f $CHOSEN_THEME_BACKGROUND && $(readlink "$CURRENT_BACKGROUND_LINK") == "$CHOSEN_THEME_BACKGROUND" ]] || \
+  fail "theme changes recover when a preselected background disappears" "$CHOSEN_THEME_BACKGROUND"
+
+pass "theme transitions skip snapshots whenever either side is a video"
+pass "theme changes recover from a missing preselected background"

From a62e34ea8e04f0aadb68e9ab6136b7fd475ad06d Mon Sep 17 00:00:00 2001
From: David Heinemeier Hansson <david@hey.com>
Date: Sun, 6 Sep 2026 17:07:40 +0200
Subject: [PATCH 23/27] Add Cursor CLI as a coding agent choice (#10465)

* Add Cursor CLI as a coding agent choice

* Launch Cursor CLI through its agent subcommand with --trust

Cursor CLI still dispatches a one-word prompt that names one of its
subcommands (update, login, help) even after a bare --, so name the agent
subcommand outright and pass the prompt behind -- there, where it also
keeps a prompt starting with a dash from being read as an option. --yolo
only auto-allows commands; the workspace trust dialog is skipped only by
--trust, and a launcher that must not stop to ask needs both.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* Leave an official Cursor CLI install alone

Cursor's own installer symlinks ~/.local/bin/cursor-agent, the same path the
mise wrapper takes. The migration now installs the wrapper only when no
cursor-agent command exists, and Remove Preinstalls deletes the path only
when it holds the wrapper omarchy-mise-install wrote, the way the Hermes
wrapper is handled. Selecting the agent treats an executable at that path
other than the wrapper as the user's own install and skips mise, since the
mise shims precede ~/.local/bin on PATH and a mise copy would only shadow
it. The wrapper resolves through mise's registry, which lists cursor-agent
from 2026.8.15 on.

The tests write a real cursor-agent stub before Remove Preinstalls runs,
cover the preinstall opt-out for the new migration, and check that a
symlinked official install survives removal and selection alike while a
dead file at the same path still installs.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* Give Cursor its brand mark and one name in the menu

Add Cursor's mark to the Omarchy icon font as U+E90D and point the agent
entry and both editor entries at it, so one brand is drawn one way across
the menu. Label the agent entry "Cursor CLI", the name the command and the
manual already use, and spell it the same in the migration and the tests.
Append the manual row after the others at the standard width.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* Keep an official Cursor CLI install through a user re-provision

User setup writes every mise wrapper unconditionally, which is fine on a
fresh install but replaces the symlink Cursor's own installer leaves at the
same path when omarchy-provision-user runs again with --force. Guard that
one line the way the migration does.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: John Cavanaugh <59479+cavanaug@users.noreply.github.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/omarchy-agent                  |   8 ++++
 bin/omarchy-default-agent          |  16 +++++--
 bin/omarchy-remove-preinstalls     |   7 +++
 default/fonts/omarchy/README.md    |   1 +
 default/fonts/omarchy/omarchy.ttf  | Bin 5492 -> 5648 bytes
 default/omarchy/omarchy-menu.jsonc |   5 ++-
 install/user/mise.sh               |   2 +
 manual/17-ai.md                    |   1 +
 migrations/1788577553.sh           |   8 ++++
 test/shell.d/default-agent-test.sh |  67 ++++++++++++++++++++++++++++-
 test/shell.d/menu-test.sh          |   5 ++-
 11 files changed, 110 insertions(+), 10 deletions(-)
 create mode 100644 migrations/1788577553.sh

diff --git a/bin/omarchy-agent b/bin/omarchy-agent
index 0aa0273b..3705eefa 100755
--- a/bin/omarchy-agent
+++ b/bin/omarchy-agent
@@ -95,6 +95,14 @@ 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")
diff --git a/bin/omarchy-default-agent b/bin/omarchy-default-agent
index f832b22d..e79100e7 100755
--- a/bin/omarchy-default-agent
+++ b/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|openclaw|agy|hermes|copilot|crush]
+# omarchy:args=[pi|omp|opencode|ori|claude|codex|grok|openclaw|agy|hermes|copilot|crush|cursor-agent]
 # omarchy:examples=omarchy default agent | omarchy default agent codex | omarchy default agent claude
 
 installing=false
@@ -36,8 +36,9 @@ openclaw) agent="openclaw"; name="OpenClaw"; agent_installer="omarchy-install-op
 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" ;;
+cursor | cursor-agent) agent="cursor-agent"; name="Cursor CLI" ;;
 *)
-  echo "Usage: omarchy-default-agent <pi|omp|opencode|ori|claude|codex|grok|openclaw|agy|hermes|copilot|crush>"
+  echo "Usage: omarchy-default-agent <pi|omp|opencode|ori|claude|codex|grok|openclaw|agy|hermes|copilot|crush|cursor-agent>"
   exit 1
   ;;
 esac
@@ -56,8 +57,15 @@ if [[ -n ${agent_installer:-} ]]; then
   agent_present() { "$agent_installer" --check; }
   agent_install() { "$agent_installer" --now; }
 else
-  agent_present() { mise where "$agent_package" &>/dev/null; }
-  agent_install() { mise use -g "$agent_package"; }
+  # 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
diff --git a/bin/omarchy-remove-preinstalls b/bin/omarchy-remove-preinstalls
index 3dca7b22..5da7a4e6 100755
--- a/bin/omarchy-remove-preinstalls
+++ b/bin/omarchy-remove-preinstalls
@@ -17,6 +17,13 @@ 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
+
   # 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
diff --git a/default/fonts/omarchy/README.md b/default/fonts/omarchy/README.md
index e538684d..cb633829 100644
--- a/default/fonts/omarchy/README.md
+++ b/default/fonts/omarchy/README.md
@@ -15,6 +15,7 @@ The private-use glyphs in `omarchy.ttf` are:
 - `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.
diff --git a/default/fonts/omarchy/omarchy.ttf b/default/fonts/omarchy/omarchy.ttf
index 7a26ed1deacde7f421ccbd80fec05fde1ec369f2..8d6df78333fe9f3b2d4801516266015b094b6d03 100644
GIT binary patch
delta 529
zcmZ9IO=uHA6vzK>_AA-u!`*FmK?<#C8!53AT2j%gLa7Hq6oZ1eq>TX^6Vgi3Q*P2;
zv@#-61jW`{QK1(>4+iYPFLLqjP1)i>iYLKc-$uO1Ff;$(|GjzdF+a!G3+t1er`N61
z0IdRI?%Lu?<=pq)FF^SWWZqO4{P~GzCvF4wJpjcj8wpZ9=8w!rs<q|zacCEqe=wI8
z>t%oFviAybW|=2ye!D?O=>>C}dE|y)Tln<tE7x)!aL*5o`citiQED9na`T+9efRa3
z&K8Iz=oFN`D)4Qxu>}=zm4i6YcYKslMGbW{u@WFKgMlCwq@##){*TeWShUIOQFK3&
zyzY49CA_3(c!|F~`6c8#;bc>>!sGr4q~x@?l?l>7ypiMK^v$jyIU=;3t}>hH2()lg
zSyOglVVF}q&GjtZ(DeN1Sl%kmjH>M9EO&;A`LV-?1RSbliL&8_<AfWrqDuH&qw@ob
zPL~u#HGZE_cFkVW4zE~d&x{p4v6H<${jHG>+X+pS3|;R}O;b~9(0TY?4%%mRHy&A)
uT`??I?MYPyTJoh`FpaD1$N%c??AeAOSMCpv3(Cr&+(kn#-)t_`n|}Z<8h+LQ

delta 329
zcmbQB^F?cdLH*_3>M0Bij2#RNOlIjhm1#*C4aXT6m=7>8@OfmUCZ_1Ev+84D5aM89
zU@*%73UDy8hynQyK)y;wZb^j+1Is-iA7}<cNKSroqR4OY-9Y{hAYUgpv7&%copA$@
z{{+Za$V<#kJ^TFG6b1%i7NDJ{3-XJ3OBV0^8_mEVasjAd@x(p%ZRapB0+|eq1`Nz#
zmJX2S0t(DwU|}c#(h>{;KoJgxM22LB42E2We1;;1%9ji;xn6R=<e7YnQA*<f|No1D
zaQ^>k|0e@szc`~fhd8G=`(yzoX?`A%;S4}0fC2Yp8>TiUMz+ltnOGP%Ut#v-;|AHz
uXlyL|oI`c;0wI4!(a9f#LMD3%>#%{HBf7axn4JkI+9s+sd6Q^3BLe^oJyXm8

diff --git a/default/omarchy/omarchy-menu.jsonc b/default/omarchy/omarchy-menu.jsonc
index d824319e..a81b4baa 100644
--- a/default/omarchy/omarchy-menu.jsonc
+++ b/default/omarchy/omarchy-menu.jsonc
@@ -140,6 +140,7 @@
   "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.omp": {"icon":"","iconFont":"omarchy","label":"omp","checked":"[[ \"$(omarchy-default-agent)\" == \"omp\" ]]","action":"omarchy-default-agent omp"},
@@ -163,7 +164,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"},
@@ -228,7 +229,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"},
diff --git a/install/user/mise.sh b/install/user/mise.sh
index 4baeffce..ea118b54 100644
--- a/install/user/mise.sh
+++ b/install/user/mise.sh
@@ -9,6 +9,8 @@ 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
diff --git a/manual/17-ai.md b/manual/17-ai.md
index 90d3a10e..156c0912 100644
--- a/manual/17-ai.md
+++ b/manual/17-ai.md
@@ -15,6 +15,7 @@ Omarchy treats AI coding agents as first-class citizens, but it doesn't pick a f
 | `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  |
+| `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.
 
diff --git a/migrations/1788577553.sh b/migrations/1788577553.sh
new file mode 100644
index 00000000..cc1a54ad
--- /dev/null
+++ b/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
diff --git a/test/shell.d/default-agent-test.sh b/test/shell.d/default-agent-test.sh
index 6a2f15b2..26fdad38 100644
--- a/test/shell.d/default-agent-test.sh
+++ b/test/shell.d/default-agent-test.sh
@@ -98,6 +98,7 @@ omp_package="github:can1357/oh-my-pi"
 crush_package="crush"
 agy_package="antigravity-cli"
 ori_package="github:OpenRouterLabs/ori-releases"
+cursor_agent_package="cursor-agent"
 
 assert_lazy_stub() {
   local package=$1
@@ -116,16 +117,23 @@ assert_lazy_stub "$grok_package" grok
 assert_lazy_stub "$omp_package" omp
 assert_lazy_stub "$crush_package" crush
 assert_lazy_stub "$ori_package" ori
+assert_lazy_stub "$cursor_agent_package" cursor-agent
 pass "custom agent lazy stubs preserve their mise packages"
 
-source "$ROOT/install/user/mise.sh"
+OMARCHY_TEST_MISSING_COMMAND=cursor-agent source "$ROOT/install/user/mise.sh"
 grep -Fx "$agy_package agy" "$stub_log" >/dev/null || fail "user setup creates the Antigravity lazy stub"
 grep -Fx "$grok_package grok" "$stub_log" >/dev/null || fail "user setup creates the Grok lazy stub"
+grep -Fx "$cursor_agent_package" "$stub_log" >/dev/null || fail "user setup creates the Cursor CLI lazy stub"
 grep -Fx "$omp_package omp" "$stub_log" >/dev/null || fail "user setup creates the Oh My Pi lazy stub"
 grep -Fx "$crush_package" "$stub_log" >/dev/null || fail "user setup creates the Crush lazy stub"
 grep -Fx "$ori_package ori" "$stub_log" >/dev/null || fail "user setup creates the Ori lazy stub"
 pass "user setup creates the custom agent lazy stubs"
 
+: >"$stub_log"
+source "$ROOT/install/user/mise.sh"
+grep -Fx "$cursor_agent_package" "$stub_log" >/dev/null && fail "user setup replaces an existing cursor-agent command"
+pass "user setup keeps an existing Cursor CLI install"
+
 : >"$stub_log"
 source "$ROOT/migrations/1785617047.sh" >/dev/null
 grep -Fx "$omp_package omp" "$stub_log" >/dev/null || fail "Oh My Pi migration creates a working lazy stub"
@@ -134,6 +142,17 @@ grep -Fx "$omp_package omp" "$stub_log" >/dev/null || fail "Oh My Pi migration c
 source "$ROOT/migrations/1787342993.sh" >/dev/null
 grep -Fx "$ori_package ori" "$stub_log" >/dev/null || fail "Ori migration creates a working lazy stub"
 
+: >"$stub_log"
+export OMARCHY_TEST_MISSING_COMMAND=cursor-agent
+source "$ROOT/migrations/1788577553.sh" >/dev/null
+unset OMARCHY_TEST_MISSING_COMMAND
+grep -Fx "$cursor_agent_package" "$stub_log" >/dev/null || fail "Cursor CLI migration creates a working lazy stub"
+
+: >"$stub_log"
+source "$ROOT/migrations/1788577553.sh" >/dev/null
+[[ ! -s $stub_log ]] || fail "Cursor CLI migration reinstalls an existing cursor-agent command"
+pass "Cursor CLI migration preserves an existing Cursor CLI install"
+
 : >"$stub_log"
 source "$ROOT/migrations/1785846769.sh" >/dev/null
 grep -Fx "$omp_package omp" "$stub_log" >/dev/null || fail "agent migration repairs the Oh My Pi lazy stub"
@@ -216,6 +235,7 @@ touch "$test_home/.local/state/omarchy/preinstalls-removed"
 source "$ROOT/migrations/1785617047.sh" >/dev/null
 source "$ROOT/migrations/1785846769.sh" >/dev/null
 source "$ROOT/migrations/1787342993.sh" >/dev/null
+OMARCHY_TEST_MISSING_COMMAND=cursor-agent source "$ROOT/migrations/1788577553.sh" >/dev/null
 [[ ! -s $stub_log ]] || fail "agent migrations respect the preinstall opt-out"
 [[ ! -e $test_home/.local/bin/omp ]] || fail "agent migration removes the obsolete Oh My Pi wrapper after opt-out"
 
@@ -242,11 +262,20 @@ pass "agent migrations install working wrappers without overriding the preinstal
 
 touch "$test_home/.local/bin/agy" "$test_home/.local/bin/ori"
 omarchy-remove-preinstalls >/dev/null
-for command in agy omp ori grok crush; do
+for command in agy omp ori grok crush cursor-agent; do
   [[ ! -e $test_home/.local/bin/$command ]] || fail "Remove Preinstalls deletes the $command lazy stub"
 done
 pass "Remove Preinstalls deletes every optional agent lazy stub"
 
+# Cursor's installer links the same path, so anything but the mise wrapper is
+# the user's own install.
+touch "$test_home/.local/bin/cursor-agent.official"
+ln -s cursor-agent.official "$test_home/.local/bin/cursor-agent"
+omarchy-remove-preinstalls >/dev/null
+[[ -L $test_home/.local/bin/cursor-agent ]] || fail "Remove Preinstalls keeps an official Cursor CLI install"
+rm -f "$test_home/.local/bin/cursor-agent" "$test_home/.local/bin/cursor-agent.official"
+pass "Remove Preinstalls keeps an official Cursor CLI install"
+
 [[ -z $(omarchy-default-agent) ]] || fail "default agent is unset until one is chosen"
 pass "default agent is unset until one is chosen"
 
@@ -307,6 +336,8 @@ declare -A expected_agents=(
   [gemini-cli]="agy"
   [copilot]="copilot"
   [github-copilot]="copilot"
+  [cursor]="cursor-agent"
+  [cursor-agent]="cursor-agent"
 )
 
 declare -A expected_packages=(
@@ -320,6 +351,7 @@ declare -A expected_packages=(
   [grok]="$grok_package"
   [agy]="$agy_package"
   [copilot]="copilot"
+  [cursor-agent]="$cursor_agent_package"
 )
 
 for selection in "${!expected_agents[@]}"; do
@@ -380,6 +412,35 @@ mapfile -d '' -t agent_open_args <"$agent_open_log"
   fail "installed agent opens in a new terminal after selection"
 pass "installed agents select and open without notifications"
 
+# Cursor's installer links the wrapper's path, and the mise shims precede
+# ~/.local/bin, so a mise copy would shadow the user's own install.
+touch "$test_home/.local/bin/cursor-agent.official"
+chmod +x "$test_home/.local/bin/cursor-agent.official"
+ln -s cursor-agent.official "$test_home/.local/bin/cursor-agent"
+: >"$terminal_log"
+: >"$mise_log"
+: >"$agent_open_log"
+omarchy-default-agent cursor-agent
+[[ ! -s $terminal_log ]] || fail "an official Cursor CLI install needs no install terminal"
+[[ ! -s $mise_log ]] || fail "an official Cursor CLI install is left to itself by mise"
+[[ $(<"$agent_file") == "cursor-agent" ]] || fail "an official Cursor CLI install becomes the default"
+mapfile -d '' -t agent_open_args <"$agent_open_log"
+[[ ${#agent_open_args[@]} == 1 && ${agent_open_args[0]} == "omarchy-agent" ]] ||
+  fail "an official Cursor CLI install opens after selection"
+rm -f "$test_home/.local/bin/cursor-agent" "$test_home/.local/bin/cursor-agent.official"
+printf '%s\n' copilot >"$agent_file"
+pass "selecting an official Cursor CLI install skips mise"
+
+# A file nothing can run is not an install; the wrapper is still wanted.
+touch "$test_home/.local/bin/cursor-agent"
+: >"$terminal_log"
+omarchy-default-agent cursor-agent
+mapfile -d '' -t terminal_args <"$terminal_log"
+[[ ${terminal_args[*]} == "omarchy-default-agent --install cursor-agent" ]] ||
+  fail "a dead file at the wrapper's path still installs Cursor CLI"
+rm -f "$test_home/.local/bin/cursor-agent"
+pass "a dead file at the wrapper's path does not pass for an install"
+
 : >"$agent_open_log"
 if omarchy-default-agent unsupported >"$test_tmp/invalid-output" 2>&1; then
   fail "default agent rejects unsupported providers"
@@ -464,6 +525,7 @@ assert_launch claude claude --permission-mode auto -- "Review this project"
 assert_launch codex codex --approve-for-me -- "Review this project"
 assert_launch crush crush run "Review this project"
 assert_launch grok grok --permission-mode bypassPermissions -- "Review this project"
+assert_launch cursor-agent cursor-agent --yolo --trust agent -- "Review this project"
 assert_launch hermes env -u HERMES_SESSION_SOURCE hermes chat --yolo --tui "--query=Review this project"
 assert_launch agy agy --dangerously-skip-permissions --prompt-interactive "Review this project"
 assert_launch copilot copilot --allow-all --interactive "Review this project"
@@ -484,6 +546,7 @@ assert_bypass claude claude --permission-mode auto
 assert_bypass codex codex --approve-for-me
 assert_bypass crush crush --yolo
 assert_bypass grok grok --permission-mode bypassPermissions
+assert_bypass cursor-agent cursor-agent --yolo --trust
 assert_bypass hermes hermes --yolo
 assert_bypass agy agy --dangerously-skip-permissions
 assert_bypass copilot copilot --allow-all
diff --git a/test/shell.d/menu-test.sh b/test/shell.d/menu-test.sh
index c65ec000..1365c3bf 100644
--- a/test/shell.d/menu-test.sh
+++ b/test/shell.d/menu-test.sh
@@ -228,6 +228,7 @@ const expectedAgents = {
   openclaw: { icon: '\ue90c', iconFont: 'omarchy', label: 'OpenClaw' },
   copilot: { icon: '', label: 'Copilot' },
   crush: { icon: '󰋑', label: 'Crush' },
+  'cursor-agent': { icon: '\ue90d', iconFont: 'omarchy', label: 'Cursor CLI' },
 }
 assert(
   Object.entries(expectedAgents).every(([agent, expected]) => {
@@ -246,7 +247,7 @@ assertDeepEqual(
   defaultItems
     .filter(item => item.parent === 'setup.default.agent')
     .map(item => item.label),
-  ['Antigravity', 'Claude', 'Codex', 'Copilot', 'Crush', 'Grok', 'Hermes', 'omp', 'OpenClaw', 'OpenCode', 'Ori', 'Pi'],
+  ['Antigravity', 'Claude', 'Codex', 'Copilot', 'Crush', 'Cursor CLI', 'Grok', 'Hermes', 'omp', 'OpenClaw', 'OpenCode', 'Ori', 'Pi'],
   'menu sorts coding agents alphabetically'
 )
 const expectedDefaults = {
@@ -638,5 +639,5 @@ assert(
 JS
 
 font_charset=$(fc-query --format='%{charset}' "$ROOT/default/fonts/omarchy/omarchy.ttf")
-[[ $font_charset == *"e900-e90c"* ]] || fail "Omarchy icon font includes every custom menu glyph"
+[[ $font_charset == *"e900-e90d"* ]] || fail "Omarchy icon font includes every custom menu glyph"
 pass "Omarchy icon font includes the official agent marks"

From a9eaf7978e33a6832630c51f1bb87f97dbf5fe36 Mon Sep 17 00:00:00 2001
From: steelcityappliance <steelcityappliancerepairllc@gmail.com>
Date: Sun, 6 Sep 2026 14:29:36 -0500
Subject: [PATCH 24/27] Point the shipped agent skills at omacom/omarchy
 (#10532)

The repository moved from basecamp/omarchy to omacom/omarchy, but the skills
Omarchy installs into ~/.claude/skills, ~/.codex/skills and ~/.agents/skills
still name the old owner. Most gh calls follow the rename, so nothing looks
wrong in normal use. Search does not: `gh issue list --repo basecamp/omarchy
--search ...` exits 0 with no output, and the raw search API answers
"Validation Failed". An agent following contributing.md or reporting.md runs
its duplicate check before filing, sees zero matches, and files a duplicate.

Replace the owner in contributing.md, reporting.md and the issue-template
contact link, which is the same stale name on the contributor path. The git
clone and release URLs in bin/ and manual/ are left alone: GitHub redirects
those, and channel-test.sh asserts the exact clone URL, so changing them is a
separate change.

Fixes #10118

Written by Claude Fable 5.1 via Claude Code, reviewed by Marc Morriss

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/ISSUE_TEMPLATE/config.yml                 |  2 +-
 default/agents/skills/diagnose-crash/reporting.md | 10 +++++-----
 default/agents/skills/omarchy/contributing.md     |  8 ++++----
 3 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 2e9a3140..d353097d 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.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
diff --git a/default/agents/skills/diagnose-crash/reporting.md b/default/agents/skills/diagnose-crash/reporting.md
index 154f1a25..15bd08bc 100644
--- a/default/agents/skills/diagnose-crash/reporting.md
+++ b/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
diff --git a/default/agents/skills/omarchy/contributing.md b/default/agents/skills/omarchy/contributing.md
index 117a9901..b5fd0533 100644
--- a/default/agents/skills/omarchy/contributing.md
+++ b/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
 ```
 

From 1d466c4003ea5be406f9ab0de138c726f4565572 Mon Sep 17 00:00:00 2001
From: Ryan Hughes <ryan@heyoodle.com>
Date: Sun, 6 Sep 2026 16:01:50 -0400
Subject: [PATCH 25/27] Add o.rebind for replacing Hyprland keybindings

---
 config/hypr/bindings.lua                      | 11 +++++-----
 default/agents/skills/omarchy/SKILL.md        |  2 +-
 default/agents/skills/omarchy/hyprland.md     | 10 ++++-----
 default/hypr/helpers.lua                      |  5 +++++
 manual/31-dotfiles.md                         |  7 ++++---
 .../hyprland-binding-conflicts-test.sh        | 21 +++++++++++++++++++
 6 files changed, 40 insertions(+), 16 deletions(-)

diff --git a/config/hypr/bindings.lua b/config/hypr/bindings.lua
index 98d3ecbe..6da7b938 100644
--- a/config/hypr/bindings.lua
+++ b/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")
diff --git a/default/agents/skills/omarchy/SKILL.md b/default/agents/skills/omarchy/SKILL.md
index aed1e38c..4ce34bb0 100644
--- a/default/agents/skills/omarchy/SKILL.md
+++ b/default/agents/skills/omarchy/SKILL.md
@@ -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`)
diff --git a/default/agents/skills/omarchy/hyprland.md b/default/agents/skills/omarchy/hyprland.md
index 961ff388..fd518ad3 100644
--- a/default/agents/skills/omarchy/hyprland.md
+++ b/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
 
diff --git a/default/hypr/helpers.lua b/default/hypr/helpers.lua
index b1eb48fa..04964703 100644
--- a/default/hypr/helpers.lua
+++ b/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
diff --git a/manual/31-dotfiles.md b/manual/31-dotfiles.md
index 11e0d762..ec148b44 100644
--- a/manual/31-dotfiles.md
+++ b/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!
 
diff --git a/test/shell.d/hyprland-binding-conflicts-test.sh b/test/shell.d/hyprland-binding-conflicts-test.sh
index c34d4bfd..d0eb9e0e 100755
--- a/test/shell.d/hyprland-binding-conflicts-test.sh
+++ b/test/shell.d/hyprland-binding-conflicts-test.sh
@@ -40,6 +40,13 @@ hl = setmetatable({
       release = opts.release == true,
     })
   end,
+  unbind = function(keys)
+    for index = #bindings, 1, -1 do
+      if bindings[index].keys == keys then
+        table.remove(bindings, index)
+      end
+    end
+  end,
   config = function() end,
   env = function() end,
   monitor = function() end,
@@ -188,3 +195,17 @@ probe=$(PATH="$stub_bin:$PATH" list_bindings "$home" \
 grep -Fqx "ALT+SHIFT+SUPER+RIGHT" <<<"$probe" ||
   fail "the conflict check ignores modifier order"
 pass "the conflict check catches collisions across keycodes and modifier order"
+
+rebound=$(PATH="$stub_bin:$PATH" list_bindings "$home" \
+  'o.rebind("SUPER + SHIFT + F", "Flea", { launch = "flea" })' | \
+  awk -F'\t' '$1 == "SHIFT+SUPER+F"')
+[[ $rebound == $'SHIFT+SUPER+F\tSUPER + SHIFT + F\tFlea' ]] ||
+  fail "rebinding replaces the default file manager without stacking actions" "$rebound"
+pass "rebinding replaces the default file manager without stacking actions"
+
+rebound=$(PATH="$stub_bin:$PATH" list_bindings "$home" \
+  'o.rebind("F9", "Dictation on release", "voxtype record toggle", { release = true })' | \
+  awk -F'\t' '$2 == "F9"')
+[[ $rebound == $'F9 (release)\tF9\tDictation on release' ]] ||
+  fail "rebinding replaces all bindings for a key and preserves binding options" "$rebound"
+pass "rebinding replaces all bindings for a key and preserves binding options"

From 0d223fe820dc5aa337e1aa11820f146edefc2856 Mon Sep 17 00:00:00 2001
From: JP <jp305@pm.me>
Date: Sun, 6 Sep 2026 16:29:16 -0400
Subject: [PATCH 26/27] Add Muse Code as a default coding agent (#9915)

* Add Muse Code as a default coding agent

Meta ships Muse Code only as a binary, so it installs from the AUR
(muse-code-bin) instead of mise, and a fresh install runs the muse login
browser flow in the install terminal before the agent opens.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0148qKzr366p2Ubu2igCLvPg

* Refine Muse Code menu and prompt forwarding

* Install Muse Code from OPR

* Install Muse Code through mise's HTTP backend

* Preinstall the Muse mise stub

* Use the shared Muse installation flow

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: David Heinemeier Hansson <david@hey.com>
---
 bin/omarchy-agent                  |   5 ++
 bin/omarchy-default-agent          |   9 +-
 bin/omarchy-remove-preinstalls     |   6 ++
 default/omarchy/omarchy-menu.jsonc |   1 +
 install/user/mise.sh               |   3 +
 manual/17-ai.md                    |   3 +
 migrations/1788724825.sh           |   5 ++
 test/shell.d/default-agent-test.sh | 135 ++++++++++++++++++++++++++++-
 test/shell.d/menu-test.sh          |   6 +-
 9 files changed, 167 insertions(+), 6 deletions(-)
 create mode 100644 migrations/1788724825.sh

diff --git a/bin/omarchy-agent b/bin/omarchy-agent
index 3705eefa..e35bcf04 100755
--- a/bin/omarchy-agent
+++ b/bin/omarchy-agent
@@ -110,6 +110,11 @@ hermes)
     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")
diff --git a/bin/omarchy-default-agent b/bin/omarchy-default-agent
index e79100e7..af93d863 100755
--- a/bin/omarchy-default-agent
+++ b/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|openclaw|agy|hermes|copilot|crush|cursor-agent]
+# 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
@@ -36,9 +36,14 @@ openclaw) agent="openclaw"; name="OpenClaw"; agent_installer="omarchy-install-op
 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|openclaw|agy|hermes|copilot|crush|cursor-agent>"
+  echo "Usage: omarchy-default-agent <pi|omp|opencode|ori|claude|codex|grok|openclaw|agy|hermes|copilot|crush|cursor-agent|muse>"
   exit 1
   ;;
 esac
diff --git a/bin/omarchy-remove-preinstalls b/bin/omarchy-remove-preinstalls
index 5da7a4e6..bfb8fe34 100755
--- a/bin/omarchy-remove-preinstalls
+++ b/bin/omarchy-remove-preinstalls
@@ -24,6 +24,12 @@ if gum confirm "Are you sure you want to remove all preinstalled web apps, TUI w
     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
diff --git a/default/omarchy/omarchy-menu.jsonc b/default/omarchy/omarchy-menu.jsonc
index a81b4baa..0e590652 100644
--- a/default/omarchy/omarchy-menu.jsonc
+++ b/default/omarchy/omarchy-menu.jsonc
@@ -143,6 +143,7 @@
   "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"},
diff --git a/install/user/mise.sh b/install/user/mise.sh
index ea118b54..b5c7884b 100644
--- a/install/user/mise.sh
+++ b/install/user/mise.sh
@@ -21,3 +21,6 @@ omarchy-mise-install github:OpenRouterLabs/ori-releases ori
 # 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
diff --git a/manual/17-ai.md b/manual/17-ai.md
index 156c0912..8911b974 100644
--- a/manual/17-ai.md
+++ b/manual/17-ai.md
@@ -15,6 +15,7 @@ Omarchy treats AI coding agents as first-class citizens, but it doesn't pick a f
 | `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.
@@ -25,6 +26,8 @@ To wrap an additional CLI the same way, run `omarchy-mise-install <package> [com
 
 Pick your default agent with `omarchy default agent <name>` or under _Setup > Defaults > Agent_ in the Omarchy Menu (`Super + Space`). If the agent isn't installed yet, picking it installs it first. A fresh Omarchy will invite you to make this choice with a one-time notification.
 
+[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, OpenCode, and Hermes (once Hermes Desktop is installed) all follow along when you switch the Omarchy theme.
diff --git a/migrations/1788724825.sh b/migrations/1788724825.sh
new file mode 100644
index 00000000..cc76dc0f
--- /dev/null
+++ b/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
diff --git a/test/shell.d/default-agent-test.sh b/test/shell.d/default-agent-test.sh
index 26fdad38..ea65b973 100644
--- a/test/shell.d/default-agent-test.sh
+++ b/test/shell.d/default-agent-test.sh
@@ -19,6 +19,7 @@ mise_history="$test_tmp/mise-history"
 stub_log="$test_tmp/stubs"
 terminal_log="$test_tmp/terminal"
 menu_log="$test_tmp/menu"
+muse_login_log="$test_tmp/muse-login"
 mkdir -p "$mock_bin" "$test_home"
 
 cat >"$mock_bin/omarchy-notification-send" <<'SH'
@@ -69,6 +70,22 @@ cat >"$mock_bin/omarchy-menu" <<'SH'
 printf '%s\0' "$@" >"$OMARCHY_TEST_AGENT_MENU_LOG"
 SH
 
+cat >"$mock_bin/omarchy-pkg-add" <<'SH'
+#!/bin/bash
+echo "Muse must install through mise" >&2
+exit 1
+SH
+ln -s omarchy-pkg-add "$mock_bin/omarchy-pkg-aur-add"
+
+cat >"$mock_bin/muse" <<'SH'
+#!/bin/bash
+if [[ ${1:-} == "login" ]]; then
+  printf 'muse %s\n' "$*" >>"$OMARCHY_TEST_MUSE_LOGIN_LOG"
+else
+  printf '%s\0' muse "$@" >"$OMARCHY_TEST_AGENT_INLINE_LOG"
+fi
+SH
+
 cat >"$mock_bin/omarchy-test-noop" <<'SH'
 #!/bin/bash
 exit 0
@@ -91,6 +108,7 @@ export OMARCHY_TEST_MISE_HISTORY="$mise_history"
 export OMARCHY_TEST_STUB_LOG="$stub_log"
 export OMARCHY_TEST_AGENT_TERMINAL_LOG="$terminal_log"
 export OMARCHY_TEST_AGENT_MENU_LOG="$menu_log"
+export OMARCHY_TEST_MUSE_LOGIN_LOG="$muse_login_log"
 export OMARCHY_PATH="$ROOT"
 
 grok_package="npm:@xai-official/grok"
@@ -99,6 +117,7 @@ crush_package="crush"
 agy_package="antigravity-cli"
 ori_package="github:OpenRouterLabs/ori-releases"
 cursor_agent_package="cursor-agent"
+muse_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]"
 
 assert_lazy_stub() {
   local package=$1
@@ -118,6 +137,7 @@ assert_lazy_stub "$omp_package" omp
 assert_lazy_stub "$crush_package" crush
 assert_lazy_stub "$ori_package" ori
 assert_lazy_stub "$cursor_agent_package" cursor-agent
+assert_lazy_stub "$muse_package" muse
 pass "custom agent lazy stubs preserve their mise packages"
 
 OMARCHY_TEST_MISSING_COMMAND=cursor-agent source "$ROOT/install/user/mise.sh"
@@ -127,12 +147,29 @@ grep -Fx "$cursor_agent_package" "$stub_log" >/dev/null || fail "user setup crea
 grep -Fx "$omp_package omp" "$stub_log" >/dev/null || fail "user setup creates the Oh My Pi lazy stub"
 grep -Fx "$crush_package" "$stub_log" >/dev/null || fail "user setup creates the Crush lazy stub"
 grep -Fx "$ori_package ori" "$stub_log" >/dev/null || fail "user setup creates the Ori lazy stub"
+OMARCHY_TEST_MISSING_COMMAND=muse source "$ROOT/install/user/mise.sh"
+grep -Fx "$muse_package muse" "$stub_log" >/dev/null || fail "user setup creates the Muse lazy stub"
 pass "user setup creates the custom agent lazy stubs"
 
 : >"$stub_log"
 source "$ROOT/install/user/mise.sh"
 grep -Fx "$cursor_agent_package" "$stub_log" >/dev/null && fail "user setup replaces an existing cursor-agent command"
 pass "user setup keeps an existing Cursor CLI install"
+grep -Fx "$muse_package muse" "$stub_log" >/dev/null && fail "user setup replaces an existing Muse command"
+
+: >"$stub_log"
+OMARCHY_TEST_MISSING_COMMAND=muse source "$ROOT/migrations/1788724825.sh" >/dev/null
+grep -Fx "$muse_package muse" "$stub_log" >/dev/null || fail "Muse migration creates its lazy stub"
+: >"$stub_log"
+source "$ROOT/migrations/1788724825.sh" >/dev/null
+[[ ! -s $stub_log ]] || fail "Muse migration replaces an existing command"
+mkdir -p "$test_home/.local/state/omarchy"
+touch "$test_home/.local/state/omarchy/preinstalls-removed"
+OMARCHY_TEST_MISSING_COMMAND=muse source "$ROOT/migrations/1788724825.sh" >/dev/null
+[[ ! -s $stub_log ]] || fail "Muse migration ignores the preinstall opt-out"
+rm "$test_home/.local/state/omarchy/preinstalls-removed"
+pass "Muse migration preserves existing installs and the preinstall opt-out"
+
 
 : >"$stub_log"
 source "$ROOT/migrations/1785617047.sh" >/dev/null
@@ -260,9 +297,10 @@ rm "$test_home/.local/state/omarchy/preinstalls-removed"
 rm -f "$agent_file"
 pass "agent migrations install working wrappers without overriding the preinstall opt-out"
 
+"$ROOT/bin/omarchy-mise-install" "$muse_package" muse
 touch "$test_home/.local/bin/agy" "$test_home/.local/bin/ori"
 omarchy-remove-preinstalls >/dev/null
-for command in agy omp ori grok crush cursor-agent; do
+for command in agy omp ori grok crush cursor-agent muse; do
   [[ ! -e $test_home/.local/bin/$command ]] || fail "Remove Preinstalls deletes the $command lazy stub"
 done
 pass "Remove Preinstalls deletes every optional agent lazy stub"
@@ -275,6 +313,13 @@ omarchy-remove-preinstalls >/dev/null
 [[ -L $test_home/.local/bin/cursor-agent ]] || fail "Remove Preinstalls keeps an official Cursor CLI install"
 rm -f "$test_home/.local/bin/cursor-agent" "$test_home/.local/bin/cursor-agent.official"
 pass "Remove Preinstalls keeps an official Cursor CLI install"
+printf '#!/bin/bash\necho user-muse\n' >"$test_home/.local/bin/muse"
+chmod +x "$test_home/.local/bin/muse"
+omarchy-remove-preinstalls >/dev/null
+[[ $("$test_home/.local/bin/muse") == "user-muse" ]] || fail "Remove Preinstalls deletes a user-managed Muse"
+rm "$test_home/.local/bin/muse"
+pass "Remove Preinstalls keeps a user-managed Muse install"
+
 
 [[ -z $(omarchy-default-agent) ]] || fail "default agent is unset until one is chosen"
 pass "default agent is unset until one is chosen"
@@ -338,6 +383,9 @@ declare -A expected_agents=(
   [github-copilot]="copilot"
   [cursor]="cursor-agent"
   [cursor-agent]="cursor-agent"
+  [muse]="muse"
+  [muse-code]="muse"
+  [musecode]="muse"
 )
 
 declare -A expected_packages=(
@@ -352,6 +400,7 @@ declare -A expected_packages=(
   [agy]="$agy_package"
   [copilot]="copilot"
   [cursor-agent]="$cursor_agent_package"
+  [muse]="$muse_package"
 )
 
 for selection in "${!expected_agents[@]}"; do
@@ -361,8 +410,12 @@ for selection in "${!expected_agents[@]}"; do
   [[ $(omarchy-default-agent) == $expected ]] || fail "default agent canonicalizes $selection"
 
   mapfile -d '' -t mise_args <"$mise_log"
-  [[ ${mise_args[0]} == "use" && ${mise_args[1]} == "-g" && ${mise_args[2]} == ${expected_packages[$expected]} ]] ||
+  [[ ${mise_args[0]} == "use" && ${mise_args[1]} == "-g" ]] ||
     fail "default agent installs $selection globally through mise"
+  case ${mise_args[2]} in
+    "${expected_packages[$expected]}") ;;
+    *) fail "default agent preserves $selection backend options" ;;
+  esac
 
   mapfile -d '' -t agent_open_args <"$agent_open_log"
   [[ ${#agent_open_args[@]} == 1 && ${agent_open_args[0]} == "omarchy-agent" ]] ||
@@ -475,6 +528,76 @@ grep -F "Could not set Codex as the default coding agent" "$test_tmp/setup-failu
 [[ ! -s $agent_open_log ]] || fail "failed activation does not open an agent"
 pass "default agent reports mise failures without notifications"
 
+# Muse follows the shared mise installation and launch path.
+: >"$notification_history"
+: >"$agent_open_log"
+: >"$terminal_log"
+omarchy-default-agent muse
+mapfile -d '' -t terminal_args <"$terminal_log"
+[[ ${terminal_args[0]} == "omarchy-default-agent" && ${terminal_args[1]} == "--install" && ${terminal_args[2]} == "muse" ]] ||
+  fail "missing Muse installation opens in a terminal"
+[[ ! -s $notification_history ]] || fail "missing Muse installation skips notifications"
+[[ ! -s $agent_open_log ]] || fail "missing Muse installation waits to open the agent"
+[[ $(omarchy-default-agent) == "copilot" ]] || fail "missing Muse installation waits to change the selection"
+
+if OMARCHY_TEST_MISE_FAIL=true omarchy-default-agent --install muse >"$test_tmp/muse-install-failure-output" 2>&1; then
+  fail "missing Muse rejects a failed mise installation"
+fi
+[[ $(omarchy-default-agent) == "copilot" ]] || fail "failed Muse installation preserves the current default"
+[[ ! -s $muse_login_log && ! -s $agent_open_log ]] || fail "failed Muse installation skips login and launch"
+grep -F "Could not install Muse Code with mise" "$test_tmp/muse-install-failure-output" >/dev/null ||
+  fail "failed Muse installation identifies mise"
+pass "failed Muse mise installation preserves the selection and skips login"
+
+: >"$mise_history"
+: >"$stub_log"
+omarchy-default-agent --install muse >"$test_tmp/muse-install-output"
+grep -Fx "use -g $muse_package" "$mise_history" >/dev/null || fail "visible Muse installation uses the HTTP backend"
+[[ ! -s $stub_log ]] || fail "Muse selection recreates its preinstalled wrapper"
+[[ ! -s $muse_login_log ]] || fail "Muse selection runs a separate login flow"
+[[ $(omarchy-default-agent) == "muse" ]] || fail "visible Muse installation changes the selection"
+mapfile -d '' -t agent_open_args <"$agent_open_log"
+[[ ${#agent_open_args[@]} == 2 && ${agent_open_args[0]} == "omarchy-agent" && ${agent_open_args[1]} == "--inline" ]] ||
+  fail "newly installed Muse opens in the installation terminal"
+pass "Muse installs visibly through mise and opens directly"
+
+: >"$terminal_log"
+: >"$muse_login_log"
+: >"$agent_open_log"
+OMARCHY_TEST_AGENT_INSTALLED=true omarchy-default-agent muse-code
+[[ ! -s $terminal_log ]] || fail "installed Muse selection skips the terminal"
+[[ ! -s $muse_login_log ]] || fail "installed Muse selection skips the login"
+[[ $(omarchy-default-agent) == "muse" ]] || fail "default agent canonicalizes muse-code"
+mapfile -d '' -t agent_open_args <"$agent_open_log"
+[[ ${#agent_open_args[@]} == 1 && ${agent_open_args[0]} == "omarchy-agent" ]] ||
+  fail "installed Muse opens in a new terminal after selection"
+pass "installed Muse selects and opens directly"
+
+OMARCHY_TEST_AGENT_INSTALLED=true omarchy-default-agent pi
+: >"$agent_open_log"
+if OMARCHY_TEST_AGENT_INSTALLED=true OMARCHY_TEST_MISE_FAIL=true omarchy-default-agent musecode >"$test_tmp/muse-failure-output" 2>&1; then
+  fail "default agent rejects a failed Muse activation"
+fi
+[[ $(omarchy-default-agent) == "pi" ]] || fail "failed Muse activation preserves the current default agent"
+grep -F "Could not set Muse Code as the default coding agent" "$test_tmp/muse-failure-output" >/dev/null ||
+  fail "default agent reports a failed Muse activation"
+[[ ! -s $agent_open_log ]] || fail "failed Muse activation does not open an agent"
+pass "default agent reports Muse mise failures without changing the selection"
+
+# A manually installed launcher belongs to the user; selecting it must not
+# install a second copy or replace it with the Omarchy wrapper.
+printf '#!/bin/bash\necho user-muse\n' >"$test_home/.local/bin/muse"
+chmod +x "$test_home/.local/bin/muse"
+: >"$mise_history"
+: >"$stub_log"
+: >"$terminal_log"
+omarchy-default-agent muse
+[[ $(omarchy-default-agent) == "muse" ]] || fail "a user-installed Muse can be selected"
+[[ ! -s $mise_history && ! -s $stub_log && ! -s $terminal_log ]] || fail "a user-installed Muse skips installation and wrapper creation"
+[[ $("$test_home/.local/bin/muse") == "user-muse" ]] || fail "a user-installed Muse is preserved"
+rm "$test_home/.local/bin/muse"
+pass "selecting a user-installed Muse preserves its launcher"
+
 rm "$mock_bin/omarchy-agent"
 hash -r
 
@@ -523,6 +646,7 @@ assert_launch opencode opencode --auto --prompt "Review this project"
 assert_launch ori ori code --interactive --prompt "Review this project"
 assert_launch claude claude --permission-mode auto -- "Review this project"
 assert_launch codex codex --approve-for-me -- "Review this project"
+assert_launch muse muse --approval-mode never -- "Review this project"
 assert_launch crush crush run "Review this project"
 assert_launch grok grok --permission-mode bypassPermissions -- "Review this project"
 assert_launch cursor-agent cursor-agent --yolo --trust agent -- "Review this project"
@@ -531,6 +655,12 @@ assert_launch agy agy --dangerously-skip-permissions --prompt-interactive "Revie
 assert_launch copilot copilot --allow-all --interactive "Review this project"
 pass "agent launcher adapts initial prompts for every supported agent"
 
+literal_muse_prompt=$'--disable-sandbox !Crash {$(touch must-not-run)}\ntrailing\\ '
+printf '%s\n' "muse" >"$agent_file"
+omarchy-agent-prompt "$literal_muse_prompt"
+assert_launched muse "separates prompt text from options" muse --approval-mode never -- "$literal_muse_prompt"
+pass "Muse receives option-like prompts as one literal argument"
+
 literal_hermes_prompt=$' --help !Crash /quit {$(touch must-not-run)}\ntrailing\\ '
 printf '%s\n' "hermes" >"$agent_file"
 omarchy-agent-prompt "$literal_hermes_prompt"
@@ -544,6 +674,7 @@ assert_bypass opencode opencode --auto
 assert_bypass ori ori code
 assert_bypass claude claude --permission-mode auto
 assert_bypass codex codex --approve-for-me
+assert_bypass muse muse --approval-mode never
 assert_bypass crush crush --yolo
 assert_bypass grok grok --permission-mode bypassPermissions
 assert_bypass cursor-agent cursor-agent --yolo --trust
diff --git a/test/shell.d/menu-test.sh b/test/shell.d/menu-test.sh
index 1365c3bf..b227bb10 100644
--- a/test/shell.d/menu-test.sh
+++ b/test/shell.d/menu-test.sh
@@ -228,7 +228,9 @@ const expectedAgents = {
   openclaw: { icon: '\ue90c', iconFont: 'omarchy', label: 'OpenClaw' },
   copilot: { icon: '', label: 'Copilot' },
   crush: { icon: '󰋑', label: 'Crush' },
+  muse: { icon: '󰛤', label: 'Muse Code' },
   'cursor-agent': { icon: '\ue90d', iconFont: 'omarchy', label: 'Cursor CLI' },
+
 }
 assert(
   Object.entries(expectedAgents).every(([agent, expected]) => {
@@ -241,13 +243,13 @@ assert(
       && !entry.when
       && entry.checked.includes(`== \"${agent}\"`)
   }),
-  'menu exposes every mise-installable coding agent with its own glyph under Defaults > Agent'
+  'menu exposes every supported coding agent with its own glyph under Defaults > Agent'
 )
 assertDeepEqual(
   defaultItems
     .filter(item => item.parent === 'setup.default.agent')
     .map(item => item.label),
-  ['Antigravity', 'Claude', 'Codex', 'Copilot', 'Crush', 'Cursor CLI', 'Grok', 'Hermes', 'omp', 'OpenClaw', 'OpenCode', 'Ori', 'Pi'],
+  ['Antigravity', 'Claude', 'Codex', 'Copilot', 'Crush', 'Cursor CLI', 'Grok', 'Hermes', 'Muse Code', 'omp', 'OpenClaw', 'OpenCode', 'Ori', 'Pi'],
   'menu sorts coding agents alphabetically'
 )
 const expectedDefaults = {

From 97a86af116b71ffd6b6dd0afc27cdefce5cacee2 Mon Sep 17 00:00:00 2001
From: David Heinemeier Hansson <david@hey.com>
Date: Sat, 29 Aug 2026 21:56:17 +0200
Subject: [PATCH 27/27] Nix ideas

---
 plans/nix.md | 150 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 150 insertions(+)
 create mode 100644 plans/nix.md

diff --git a/plans/nix.md b/plans/nix.md
new file mode 100644
index 00000000..b1a8ce31
--- /dev/null
+++ b/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?