Omarchy 4 prep: Quickshell shell migration, menu selector compatibility, resume monitor, QML lint workflow

.benchmarks/README.md

@@ -1,6 +1,6 @@
 # System Tests and Benchmarks
 
-Minimal system-wide benchmarks and diagnostics (not Waybar-specific).
+Minimal system-wide benchmarks and diagnostics.
 
 - `.benchmarks/system-quick-bench.sh` — short CPU/memory/network benchmark snapshot.
 - `.tests/system-resource-leak-test.sh` — short leak and growth check over time.

.github/workflows/quickshell-lint.yml

@@ -0,0 +1,70 @@
+name: Lint Quickshell
+
+on:
+  push:
+    branches:
+      - distro/arch-omarchy
+    paths:
+      - '**/*.qml'
+      - '.github/workflows/quickshell-lint.yml'
+  pull_request:
+    paths:
+      - '**/*.qml'
+      - '.github/workflows/quickshell-lint.yml'
+
+permissions:
+  contents: read
+
+env:
+  # Version of the Arch `quickshell` package this lint runs against. The
+  # Omarchy shell runs on Arch's quickshell (which pulls qt6-declarative, i.e.
+  # qmllint), so this tracks the Arch package - not Qt and not upstream tags.
+  # Renovate keeps it in sync via the repology datasource (see the
+  # customManagers entry in renovate.json); the version check below fails if
+  # the container's quickshell has drifted from this pin, which is the signal
+  # to merge the Renovate bump.
+  QUICKSHELL_VERSION: "0.3.0"
+
+jobs:
+  qmllint:
+    runs-on: ubuntu-latest
+    container: archlinux:latest
+    steps:
+      - name: Install quickshell and qmllint
+        run: |
+          # Refresh the keyring first (the base image's can lag and break
+          # signature checks), then install quickshell (pulls qt6-declarative =
+          # qmllint) and git (needed by actions/checkout in this container).
+          pacman -Sy --noconfirm --needed archlinux-keyring
+          pacman -Su --noconfirm --needed quickshell qt6-declarative git
+
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: Trust the checkout (container git ownership)
+        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+      - name: Verify quickshell matches the pinned version
+        run: |
+          installed="$(pacman -Q quickshell | awk '{print $2}' | cut -d- -f1)"
+          echo "Installed quickshell: $installed (pinned QUICKSHELL_VERSION: $QUICKSHELL_VERSION)"
+          if [ "$installed" != "$QUICKSHELL_VERSION" ]; then
+            echo "::error::Arch quickshell is $installed but QUICKSHELL_VERSION is pinned to $QUICKSHELL_VERSION. Merge the Renovate bump so the pin matches the package being linted against." >&2
+            exit 1
+          fi
+
+      - name: Lint QML
+        run: |
+          export PATH="/usr/lib/qt6/bin:$PATH"
+          mapfile -t qml_files < <(git ls-files '*.qml')
+          if [ "${#qml_files[@]}" -eq 0 ]; then
+            echo 'No QML files found.'
+            exit 0
+          fi
+          printf 'Linting %s QML file(s) with %s:\n' "${#qml_files[@]}" "$(qmllint --version)"
+          printf '  %s\n' "${qml_files[@]}"
+          # quickshell installs its QML modules under /usr/lib/qt6/qml, so `-I`
+          # lets qmllint resolve `Quickshell.*`. The Omarchy shell's own `qs.*`
+          # modules ship in the (unpackaged) shell source, so the import
+          # category stays disabled; qmllint still fails on real syntax errors.
+          qmllint -I /usr/lib/qt6/qml --import disable --unqualified disable "${qml_files[@]}"

.opencode/skills/omarchy-shell-quickshell/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: omarchy-shell-quickshell
+description: Customise and reload the Omarchy shell (omarchy-shell) - the Quickshell process behind the bar, notifications, OSD, launcher, and settings - in this dotfiles repo. Use when working with the Omarchy shell or Quickshell: editing omarchy/.config/omarchy/plugins/, the shell.json generator dot/src/lib/omarchyShellConfig.ts, shell.json, BarWidget/WidgetButton or other Quickshell QML, running omarchy plugin or omarchy restart shell, referencing upstream Quickshell, or when a shell or bar change is not showing up.
+---
+
+# Omarchy Shell (Quickshell)
+
+## Background / upstream
+
+- The Omarchy shell is a single long-running **Quickshell** process (`omarchy-shell`) that hosts the top bar, notification daemon, on-screen display, launcher, and settings panel. Restarting "the shell" restarts all of them together.
+- **Quickshell** is the upstream framework: a QML/Qt6 toolkit for Wayland desktop shells (layer-shell surfaces via `WlrLayershell`, an IPC bus, and live QML reload). Upstream is self-hosted Forgejo at `git.outfoxxed.me/quickshell/quickshell`; the opencode `quickshell` reference clones the official GitHub mirror `quickshell-mirror/quickshell`. Use it for QML types, layer-shell, `IpcHandler`, reloadable config, and the `qs` CLI.
+- Omarchy's shell source lives in `~/.local/share/omarchy/shell/` - **READ-ONLY** (reading is useful: base classes `BarWidget`/`WidgetButton` in `shell/Ui/`, the bar host in `shell/plugins/bar/Bar.qml`). Edits are lost on `omarchy update`.
+
+## Source of truth (never edit live)
+
+- Custom shell content ships as **user plugins**. Edit the stow source `omarchy/.config/omarchy/plugins/<id>/` (stows to `~/.config/omarchy/plugins/<id>/`).
+- `~/.config/omarchy/shell.json` is **generated, not hand-edited**. It is rendered by `dot` from `dot/src/lib/omarchyShellConfig.ts` (`mergeOmarchyShellConfig`), starting from Omarchy's default and inserting personal modules. Edit the generator, rebuild `dot`, then `dot stow` regenerates the file. The live file is mode `0600` and tracked by neither dotfiles repo.
+
+## Plugin layout
+
+A plugin is a folder with `manifest.json` + entry-point QML:
+
+- `manifest.json`: `schemaVersion: 1`, `id: "timmo.<name>"`, `kinds` (e.g. `["bar-widget"]`), `entryPoints` mapping each kind to a QML file, and a per-kind config block (for a bar widget: `barWidget` with `displayName`, `category`, `allowMultiple`).
+- Entry QML: a bar widget extends `BarWidget` (`import qs.Commons`, `import qs.Ui`), sets `moduleName` to the plugin id, reads per-instance `shell.json` settings via `setting(name, fallback)`, and uses `WidgetButton` for clickable text cells.
+
+Stow gotcha: `~/.config/omarchy/plugins/` is a **real directory with per-plugin symlinks**. A brand-new plugin needs `dot stow` to create its symlink before the shell sees it. Editing an existing plugin's files is already live (symlink -> dotfiles source).
+
+## Reload matrix (run after a change)
+
+| Change | Action |
+| --- | --- |
+| `shell.json` layout/settings, existing modules only | Hot-reloads on save - nothing to run |
+| New plugin added | `omarchy plugin rescan`, then the hot-reload picks it up |
+| Plugin / shell QML code edited | `omarchy restart shell` (full restart) |
+
+`omarchy restart shell` (= `omarchy-restart-shell`: `pkill -x quickshell` + detached `setsid` relaunch) is the **only** reliable way to load new or changed QML. `omarchy plugin rescan` and `omarchy-shell shell reloadConfig` do **not** reload cached QML.
+
+## The XCB trap (critical)
+
+`omarchy-restart-shell` inherits the caller's environment. If `QT_QPA_PLATFORM=xcb`, Quickshell starts under XWayland, `WlrLayershell` cannot attach, and the shell renders as a **floating window** instead of bar/overlay surfaces (no error).
+
+- Interactive shells in this repo set `QT_QPA_PLATFORM="wayland;xcb"` (`zsh/.zshrc`) so a direct `omarchy restart shell` works. A plain `xcb` reintroduces the floating-window bug.
+- From any non-interactive context (SSH, `systemd`, `cron`, an agent shell) force Wayland and make sure the session is reachable:
+
+```bash
+QT_QPA_PLATFORM=wayland omarchy restart shell   # needs WAYLAND_DISPLAY + XDG_RUNTIME_DIR
+```
+
+- `dot update` bakes this in: it reloads the shell **only when the generated `shell.json` changed**, forcing `QT_QPA_PLATFORM=wayland` on the restart (`reloadOmarchyShell` in `dot/src/commands/Update.ts`). Standalone `dot stow` does not reload.
+
+## Lint (required after every final QML change)
+
+After every final QML edit, lint the files you touched with the **Qt6** `qmllint`. On Arch the Qt6 binary is `/usr/lib/qt6/bin/qmllint` - the bare `/usr/bin/qmllint` may be an older Qt5 build that rejects these flags. `-I /usr/lib/qt6/qml` lets it resolve the installed `Quickshell.*` modules:
+
+```bash
+/usr/lib/qt6/bin/qmllint -I /usr/lib/qt6/qml --import disable --unqualified disable <file>.qml
+```
+
+The shell's own `qs.*` modules ship in the (unpackaged) shell source, so the `import`/`unqualified` categories stay disabled as noise; `qmllint` still fails (non-zero) on real syntax errors, which is what the gate catches. This mirrors `.github/workflows/quickshell-lint.yml`, which lints inside an Arch container against the `quickshell` package pinned by `QUICKSHELL_VERSION` (kept in sync with the Arch package by Renovate via repology, and asserted to match). Lint must pass locally before a QML change is considered done.
+
+## Verify
+
+- `omarchy plugin list` - is the plugin registered and enabled?
+- `omarchy-shell shell debugBarGeometry` - per-module `x`/`width`/`visible`; confirm a widget renders or collapses.
+- `omarchy plugin validate <folder>` rejects symlinked plugin folders - **expected** for stowed plugins, not a real error.
+- `grim -g "0,0 360x32" out.png` - visual check of the bar's left edge; after a restart confirm `hyprctl layers | grep omarchy-bar`.
+- After editing the generator: `cd dot && bunx tsc --noEmit && bun run format && bun run build`.

AGENTS.md

@@ -49,14 +49,16 @@ Keep shared cross-project agent behaviour in the global `~/.config/opencode/AGEN
 
 - For Effect-TS code (`effect`, `@effect/platform`, `Context.Tag`, `Layer`, `Effect.gen`), apply the `effect` skill.
 - For OpenTUI code (`@opentui/core`, renderables, keyboard handling, suspend/resume), apply the `opentui` skill.
+- For Omarchy shell work — the Omarchy shell process (omarchy-shell), built on the upstream Quickshell framework (bar widgets/plugins under `omarchy/.config/omarchy/plugins/`, the `shell.json` generator `dot/src/lib/omarchyShellConfig.ts`, reloading the running shell, or upstream Quickshell itself), apply the `omarchy-shell-quickshell` skill.
 
 ## Omarchy Host Overrides
 
-- Hyprland config is a stowed dotfiles package (`hypr/.config/hypr/`, conf-only), not a tracked Omarchy repo.
-- `waybar`, `ghostty`, and `uwsm` are single-branch Omarchy repos expected on `main`.
+- Hyprland config is a stowed dotfiles package (`hypr/.config/hypr/`), not a tracked Omarchy repo.
+- `ghostty` and `uwsm` are single-branch Omarchy repos expected on `main`.
 - `bootstrap` is expected on `distro/omarchy`.
 - Hypr host-specific overrides live under `~/.config/hypr/hosts/$OMARCHY_HOST`, selected by the runtime `~/.config/hypr/host` symlink.
 - `dot stow` lays down the Hypr package with `--no-folding` and creates/repairs `~/.config/hypr/host`; `dot doctor` checks the host link and flags any leftover legacy `omarchy-hypr` clone.
+- The Hypr package alone is stowed non-destructively: `dot stow` and `dot install` skip the usual unstow-then-restow for `hypr` so its symlinks (notably `hyprland.lua`) never vanish mid-stow, then reload Hyprland afterwards. This stops Hyprland's live-config autoreload from catching a missing config and dropping into emergency mode. Keep this behaviour if you touch the stow loop in `dot/src/commands/{Stow,Install}.ts`.
 - A machine still on the retired `~/.config/hypr` `omarchy-hypr` clone halts `dot update` until the clone is backed up and re-stowed.
 - If this host override layout changes, update the docs site (`docs/src/content/docs/`), `README.md`, `AGENTS.md`, and skill documentation together so repo instructions stay consistent.
 
@@ -75,6 +77,7 @@ Keep shared cross-project agent behaviour in the global `~/.config/opencode/AGEN
 - Keep command and flag metadata in `dot/src/cli/spec.ts`; help and completion generation consume that registry.
 - When changing `dot` commands, subcommands, aliases, or flags, run `dot completions` for each supported shell after rebuilding so the stowed completion files stay in sync.
 - The `docs/` command reference (`docs/src/content/docs/dot/commands.md`) is generated from `dot/src/cli/spec.ts`. After changing commands, regenerate it with `mise run gen:cli` in `docs/` (alongside shell completions) and commit the result.
+- The Omarchy bar `shell.json` is generated by `dot/src/lib/omarchyShellConfig.ts`; the `dot update` loop reloads the running shell only when the rendered `shell.json` changes and forces `QT_QPA_PLATFORM=wayland` on the restart so the layer-shell bar attaches. Keep this behaviour if you touch `reloadOmarchyShell` in `dot/src/commands/Update.ts` or the shell-config return value. See the `omarchy-shell-quickshell` skill.
 
 ## Documentation Site
 

README.md

@@ -13,8 +13,8 @@ My public [Omarchy](https://omarchy.org) dotfiles, managed with GNU Stow and the
 
 - Stow-based dotfiles rooted at `~/.config/dotfiles`, applied with the `dot` command
 - A single compiled binary at `scripts/.local/bin/dot` (Bun + Effect v4 + OpenTUI) with a TUI dashboard and a full CLI
-- Git/GitHub tooling: diff, log, status, workflow runs, and a notification inbox across managed repos, with Waybar modules
-- Managed Omarchy repos (`bootstrap`, `waybar`, `ghostty`, `uwsm`) and per-host Hyprland overrides
+- Git/GitHub tooling: diff, log, status, workflow runs, and a notification inbox across managed repos, surfaced in the Omarchy Quickshell status bar
+- Managed Omarchy repos (`bootstrap`, `ghostty`, `uwsm`) and per-host Hyprland overrides
 - Optional private overlay from `~/.config/dotfiles-private`
 - Shared OpenCode agents, commands, skills, and plugins, published to [`timmo001/opencode-config`](https://github.com/timmo001/opencode-config)
 

agents/.agents/skills/dotfiles-stow/SKILL.md

@@ -83,11 +83,12 @@ When editing the public dotfiles repo (`~/.config/dotfiles`), treat a docs updat
 
 ## Omarchy Host Override Documentation Rules
 
-- Hyprland config is a stowed dotfiles package (`hypr/.config/hypr/`, conf-only), not a tracked Omarchy repo.
-- `waybar`, `ghostty`, and `uwsm` are single-branch Omarchy repos expected on `main`.
+- Hyprland config is a stowed dotfiles package (`hypr/.config/hypr/`), not a tracked Omarchy repo.
+- `ghostty` and `uwsm` are single-branch Omarchy repos expected on `main`.
 - `bootstrap` is expected on `distro/omarchy`.
 - Hypr host-specific overrides live under `~/.config/hypr/hosts/$OMARCHY_HOST`, selected by the runtime `~/.config/hypr/host` symlink.
 - `dot stow` lays down the Hypr package with `--no-folding` and creates/repairs `~/.config/hypr/host`; `dot doctor` checks it and flags any leftover legacy `omarchy-hypr` clone.
+- The Hypr package alone is stowed non-destructively: `dot stow` and `dot install` skip the usual unstow-then-restow for `hypr` so its symlinks (notably `hyprland.lua`) never vanish mid-stow, then reload Hyprland afterwards, so Hyprland's autoreload never catches a missing config and trips emergency mode.
 - When changing host override layout or guidance, update the relevant `README.md`, `AGENTS.md`, and skill documentation together.
 - Repos that use host-specific overrides should have their own `README.md` and `AGENTS.md` that explicitly state the arrangement and the requirement to keep related documentation in sync when it changes.
 

agents/.agents/skills/safe-process-signals/SKILL.md

@@ -54,7 +54,7 @@ Omarchy's restart helpers use `pkill -x <name>` which matches the process name o
 
 ```bash
 # Best: exact process name (what omarchy-restart-* uses)
-pkill -x "waybar"
+pkill -x "quickshell"
 
 # Acceptable: bracket trick when -f is needed
 pkill -f "[n]ode.*server.js"
@@ -66,7 +66,7 @@ pkill -f "node.*server.js"
 When you need to restart an Omarchy-managed app, prefer the built-in helper:
 
 ```bash
-omarchy restart waybar
+omarchy restart shell
 omarchy restart terminal
 omarchy restart-app <name> [args...]
 ```

docs/astro.config.mjs

@@ -107,6 +107,7 @@ export default defineConfig({
           items: [
             { label: 'Overview', slug: 'omarchy' },
             { label: 'Host Overrides', slug: 'omarchy/host-overrides' },
+            { label: 'Shell (Quickshell)', slug: 'omarchy/shell' },
             { label: 'Controls', slug: 'omarchy/controls' },
           ],
         },

docs/src/content/docs/bar-integrations.mdx

@@ -13,7 +13,7 @@ export const commandCards = [
 
 `--bar-json` is a shared status-bar contract rather than a single command. Tools emit one-line `--bar-json` output (with `text`, `tooltip`, and `class` fields) meant to be polled by a status bar module through its own short-lived cache. Left click opens the relevant TUI; right click refreshes the cache.
 
-The JSON format is bar-agnostic: it works with [Waybar](https://github.com/Alexays/Waybar), [Quickshell](https://quickshell.outfoxxed.me), or any bar that can run a command and parse JSON. My own setup uses Waybar, so the bundled modules and `dot doctor` checks target Waybar, but the commands themselves do not depend on it.
+The JSON format is bar-agnostic: it works with [Quickshell](https://quickshell.outfoxxed.me), [Waybar](https://github.com/Alexays/Waybar), or any bar that can run a command and parse JSON. My own setup uses the Omarchy 4 Quickshell bar, which runs these commands through `timmo.command` widgets, but the commands themselves do not depend on any particular bar. See [Shell (Quickshell)](/omarchy/shell/) for how that bar is configured.
 
 ## dot commands with bar output
 
@@ -37,4 +37,4 @@ Which repos and which activity reach the bar is controlled by the private `dot-g
 
 ## Health checks
 
-`dot doctor` verifies the active status-bar module wiring for `git-workflows` and `git-notifications`, alongside `dot-git.yml` and the absence of legacy `git-workflow-watch` leftovers.
+`dot doctor` verifies `dot-git.yml`, GitHub notification API access, and the absence of legacy `git-workflow-watch` leftovers.

docs/src/content/docs/configuration/private-git.md

@@ -24,4 +24,4 @@ The `notifications.bar.ignore_bot_activity` key controls status-bar bot noise. A
 ## Requirements
 
 - `dot git-notifications` requires `gh` authenticated with a classic token carrying the `notifications` or `repo` scope.
-- `dot doctor` verifies `dot-git.yml`, the active status-bar module wiring, and the absence of legacy `git-workflow-watch` leftovers.
+- `dot doctor` verifies `dot-git.yml` and the absence of legacy `git-workflow-watch` leftovers.

docs/src/content/docs/dot/commands.md

@@ -138,8 +138,8 @@ Origin HEAD          Local origin/HEAD tracks the remote default branch (not sta
 Stow integrity       Dry-run restow to detect drift
 OpenCode location    Canonical paths, legacy remnants
 Git config           Managed include is active
-Workflow runs        Repo list, status bar config, legacy watcher cleanup
-Git notifications    API scope and status bar notification module wiring
+Workflow runs        Repo list and legacy watcher cleanup
+Git notifications    API scope and notification access
 Doctor startup       Startup notification timer
 Daily volume reset   Laptop-only optional timer
 Omarchy repos        Diff repos + worktree branch correctness

docs/src/content/docs/getting-started/install.md

@@ -46,7 +46,7 @@ dot init --host laptop --noninteractive --confirm
 Or run `dot init` in an interactive shell to be prompted.
 
 :::note
-If stock Omarchy directories already exist at `~/.config/waybar`, `~/.config/ghostty`, or `~/.config/uwsm`, `dot init` backs them up with a `.dot-init-backup-*` suffix before cloning the managed repos. Hyprland config is stowed from the `hypr/` package instead.
+If stock Omarchy directories already exist at `~/.config/ghostty` or `~/.config/uwsm`, `dot init` backs them up with a `.dot-init-backup-*` suffix before cloning the managed repos. Hyprland config is stowed from the `hypr/` package instead.
 :::
 
 ## Ongoing workflow