Quattro

.gitignore

@@ -0,0 +1,4 @@
+
+# Python bytecode (orchestrator)
+__pycache__/
+*.pyc

.luarc.json

@@ -0,0 +1,11 @@
+{
+  "workspace": {
+    "library": [
+      "/usr/share/hypr/stubs"
+    ],
+    "checkThirdParty": false
+  },
+  "diagnostics": {
+    "globals": ["hl"]
+  }
+}

AGENTS.md

@@ -1,3 +1,15 @@
+# Task Guides
+
+Deeper instructions for specific kinds of work live in `agents/skills/`. Read the
+matching guide before starting:
+
+- [`agents/skills/command-metadata.md`](agents/skills/command-metadata.md) - adding or changing commands in `bin/`
+- [`agents/skills/install-scripts.md`](agents/skills/install-scripts.md) - working under `install/` or on system/user setup commands
+- [`agents/skills/shell-dev.md`](agents/skills/shell-dev.md) - editing the Quickshell desktop under `shell/`
+- [`agents/skills/acceptance-tests.md`](agents/skills/acceptance-tests.md) - writing or running graphical acceptance tests under `test/acceptance.d/`
+- [`agents/skills/visual-verification.md`](agents/skills/visual-verification.md) - verifying any change with a visual effect in the running UI
+- [`docs/migrations.md`](docs/migrations.md) - creating or changing migrations under `migrations/`
+
 # Style
 
 - Two spaces for indentation, no tabs
@@ -12,7 +24,9 @@
 
 All commands start with `omarchy-`. Prefixes indicate purpose.
 
-The authoritative command group list lives in `bin/omarchy` in `GROUP_DESCRIPTIONS`. Keep `GROUP_DESCRIPTIONS` updated when adding a new command prefix.
+The authoritative list of user-facing command groups lives in `bin/omarchy` in `GROUP_DESCRIPTIONS`. Keep `GROUP_DESCRIPTIONS` updated when adding a new command prefix users are meant to browse to.
+
+A group whose commands are all `# omarchy:hidden=true` gets no entry. That table drives the top-level group listing on its own, so an entry there advertises the group even when every command in it is hidden. `apply-` and `provision-` are deliberately absent for that reason; both still route, and `omarchy <group>` still prints a group header without one.
 
 Common prefixes include:
 
@@ -29,103 +43,77 @@ Common prefixes include:
 - `theme-` - theme management
 - `update-` - update components
 
-Other current prefixes include:
-
-- `ac-`, `audio-`, `battery-`, `branch-`, `brightness-`, `channel-`, `config-`, `debug-`, `dev-`, `drive-`, `first-`, `font-`, `haptic-`, `hibernation-`, `hook-`, `hyprland-`, `menu-`, `migrate-`, `notification-`, `npx-`, `plymouth-`, `powerprofiles-`, `reinstall-`, `remove-`, `screensaver-`, `show-`, `snapshot-`, `state-`, `sudo-`, `swayosd-`, `system-`, `transcode-`, `tui-`, `tz-`, `upload-`, `version-`, `voxtype-`, `webapp-`, `wifi-`, `windows-`
-
-# Command Metadata
-
-Commands in `bin/` can declare CLI metadata in comments near the top of the file. `bin/omarchy` scans the first 80 lines, and tests expect command metadata to remain valid.
+Do not maintain a second exhaustive prefix list here. Consult
+`GROUP_DESCRIPTIONS` when selecting or checking a command group so this
+guidance does not drift from the router.
 
-Supported metadata keys:
+# Runtime Environment
 
-- `# omarchy:summary=...` - short help text
-- `# omarchy:group=...` - command group when it differs from the filename-derived prefix
-- `# omarchy:name=...` - command name within the group
-- `# omarchy:args=...` - usage arguments
-- `# omarchy:examples=...` - examples separated with ` | `
-- `# omarchy:alias=...` / `# omarchy:aliases=...` - alternate routes
-- `# omarchy:hidden=true` - hide from default command listings
-- `# omarchy:requires-sudo=true` - mark commands that require sudo
+- `$OMARCHY_PATH` is set at the top level by the uwsm session environment and is always available to Omarchy runtime code.
+- Commands in `bin/` and Quickshell QML should rely on `$OMARCHY_PATH` / `Quickshell.env("OMARCHY_PATH")`; do not derive fallback paths from `HOME`, `Quickshell.shellDir`, or re-export/default `OMARCHY_PATH` manually.
 
-Prefer explicit metadata for user-facing commands. Keep routes consistent with the filename unless there is a deliberate alias or compatibility route.
+# Privileged Commands
 
-Example:
+- Follow the "Privilege Escalation" section of `default/agents/skills/omarchy/SKILL.md`. It draws the
+  `sudo`/`pkexec` line by whether the caller has a terminal to enter a password in, and the repo's
+  own scripts follow it.
 
-```bash
-# omarchy:summary=Take a screenshot
-# omarchy:group=capture
-# omarchy:args=[smart|region|windows|fullscreen] [slurp|copy]
-# omarchy:examples=omarchy screenshot | omarchy capture screenshot region
-# omarchy:aliases=omarchy screenshot
-```
-
-# Install Scripts
-
-Install entry points (`install.sh`, `boot.sh`) use `#!/bin/bash`. Many scripts under `install/` are sourced via `run_logged` and intentionally do not have shebangs.
+# Git
 
-Install stage files follow this pattern:
-
-- `install/*/all.sh` lists scripts in execution order
-- leaf scripts are sourced by `run_logged $OMARCHY_INSTALL/path/to/script.sh`
-- avoid `exit` in sourced install scripts unless intentionally aborting the install
-- use `$OMARCHY_INSTALL` and `$OMARCHY_PATH` instead of hard-coded Omarchy paths
-- keep hardware-specific logic under `install/config/hardware/`
-- prefer helper commands for package and command checks where available
-
-Raw `command -v`, `pacman`, and `pacman-key` are acceptable in bootstrap/preflight/package-helper contexts where the helper commands may not be available yet or where direct package-manager behavior is the point of the script.
+- Commits should be atomic: include only one coherent change or fix, and do not mix unrelated work.
+- Commit messages should be succinct and describe the change being made.
 
 # Helper Commands
 
 Use these instead of raw shell commands:
 
 - `omarchy-cmd-missing` / `omarchy-cmd-present` - check for commands
-- `omarchy-pkg-missing` / `omarchy-pkg-present` - check for packages
+- `omarchy-pkg-missing` / `omarchy-pkg-present` - check for packages (don't use these if you can just use `omarchy-pkg-add`/`omarchy-pkg-drop`)
 - `omarchy-pkg-add` - install packages (handles both pacman and AUR)
+- `omarchy-pkg-drop` - remove packages; use this instead of raw `pacman -R*`
+- `omarchy-notification-send` - send desktop notifications; do not call `notify-send` directly
 - `omarchy-hw-asus-rog` - detect ASUS ROG hardware (and similar `hw-*` commands)
 
-Exceptions are allowed for bootstrap, preflight, migration, and package-helper scripts where the helper may not be available yet, where the helper itself is being implemented, or where direct package-manager behavior is required.
+Commands installed by Omarchy's default package set are runtime invariants. Invoke them directly; do not add defensive `omarchy-cmd-present` / `omarchy-cmd-missing` checks around them. Use command-presence helpers only for genuinely optional dependencies or code that can run before the default package set is installed.
 
-# Config Structure
+Exceptions are allowed for migration and package-helper scripts where the helper may not be available yet, where the helper itself is being implemented, or where direct package-manager behavior is required.
 
-- `config/` - default configs copied to `~/.config/`
-- `default/themed/*.tpl` - templates with `{{ variable }}` placeholders for theme colors
-- `themes/*/colors.toml` - theme color definitions (accent, background, foreground, color0-15)
+# Menu
 
-# Visual Changes
+- The menu definition lives in `default/omarchy/omarchy-menu.jsonc`.
+- Do not add `aliases` to new menu entries. Aliases are reserved for
+  established alternate names users already type, kept for compatibility.
 
-When making visual changes, such as Waybar styles or desktop appearance, always take and analyze a screenshot after applying the change to verify the result. Use `omarchy capture screenshot fullscreen save` for fullscreen screenshots.
+# Config Structure
 
-# Refresh Pattern
+- `config/` - default configs copied to `~/.config/`
+- `default/themed/*.tpl` - templates with `{{ variable }}` placeholders for theme colors
+- `themes/*/colors.toml` - theme color definitions (accent, background, foreground, red/green/yellow/blue/magenta/cyan and bright_* variants)
 
-To copy a default config to user config with automatic backup:
+# Tests
 
-```bash
-omarchy-refresh-config hypr/hyprlock.conf
-```
+Run focused automated tests for the area you changed. Current test entry points:
 
-This copies `~/.local/share/omarchy/config/hypr/hyprlock.conf` to `~/.config/hypr/hyprlock.conf`.
+- `./test/all` - aggregate runner for CLI and shell tests; it intentionally does not run graphical acceptance tests
+- `./test/cli` - CLI routing, command metadata, theme helpers, and safe dispatch coverage
+- `./test/shell` - all Omarchy shell tests under `test/shell.d/`
 
-# Migrations
+New Omarchy shell tests should live in `test/shell.d/*-test.sh` so `./test/shell` picks them up automatically. Source `test/shell.d/base-test.sh` for shared root-path discovery, assertions, and Node test helpers.
 
-To create a new migration, run `omarchy-dev-add-migration --no-edit`. This creates a migration file named after the unix timestamp of the last commit.
+The graphical acceptance suite runs in a disposable VM, not in the active
+development session; see [`agents/skills/acceptance-tests.md`](agents/skills/acceptance-tests.md).
 
-New migration format:
-- File permissions must be `0644` (`-rw-r--r--`); migrations are sourced, not executed directly
-- No shebang line
-- Start with an `echo` describing what the migration does
-- Use `$OMARCHY_PATH` to reference the omarchy directory
-- Prefer helper commands such as `omarchy-cmd-present`, `omarchy-cmd-missing`, `omarchy-pkg-present`, and `omarchy-pkg-missing`
+Visual changes must be verified in the running UI in addition to automated
+tests; follow [`agents/skills/visual-verification.md`](agents/skills/visual-verification.md).
 
-Some older migrations predate these rules. Do not copy older migrations that start with shebangs, omit the leading `echo`, or hard-code `~/.local/share/omarchy`.
+# Refresh Pattern
 
-Migrations may use raw `pacman`, `command -v`, or direct config edits when needed for historical compatibility or one-off repair work.
+To copy a default config to user config with automatic backup:
 
-Example:
 ```bash
-echo "Disable fingerprint in hyprlock if fingerprint auth is not configured"
-
-if omarchy-cmd-missing fprintd-list || ! fprintd-list "$USER" 2>/dev/null | grep -q "finger"; then
-  sed -i 's/fingerprint:enabled = .*/fingerprint:enabled = false/' ~/.config/hypr/hyprlock.conf
-fi
+omarchy-refresh-config hypr/hyprland.lua
 ```
+
+This copies `$OMARCHY_PATH/config/hypr/hyprland.lua` to `~/.config/hypr/hyprland.lua`. The argument
+is interpolated into both paths and only checked with `[[ -e ]]`, so pass a plain relative path: a
+name containing `..` resolves and copies, landing outside `~/.config` rather than being rejected.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

agents/skills/acceptance-tests.md

@@ -0,0 +1,46 @@
+# Acceptance Tests
+
+Read this before writing or running the graphical acceptance suite under
+`test/acceptance.d/`.
+
+The graphical acceptance suite lives in `test/acceptance` with test files under
+`test/acceptance.d/*-test.sh`. It exercises a real installed Omarchy desktop,
+including session health, shell surfaces, panels, keyboard navigation,
+representative applications, and system setup. Source
+`test/acceptance.d/base-test.sh` for the shared helpers.
+
+Run acceptance tests in a disposable VM through the sibling `omarchy-iso`
+repository, not in the active development session. The suite opens and closes
+applications and temporarily changes desktop configuration.
+
+For acceptance-test-only changes, reuse an installed base and sync the suite:
+
+```bash
+cd ../omarchy-iso
+./bin/omarchy-iso-test release/<iso>.iso --reuse-base --sync-omarchy ../omarchy --no-preview
+```
+
+Use `--sync-all ../omarchy` instead of `--sync-omarchy ../omarchy` when the
+acceptance run must exercise local `bin/`, `config/`, or `shell/` source too.
+Changes to package manifests, installation, finalization, or shipped defaults
+require a fresh ISO built from the local checkouts and a run without
+`--reuse-base`:
+
+```bash
+cd ../omarchy-iso
+./bin/omarchy-iso-make --no-boot-offer --local-source ../omarchy ../omarchy-pkgs
+./bin/omarchy-iso-test release/<generated-iso>.iso --no-preview
+```
+
+Keep unrelated acceptance workflows in separate test files. The runner records
+a failed file and continues with the remaining files, which preserves as much
+diagnostic coverage as possible. Restore modified user state with traps, close
+anything the test opens, and capture every visually distinct state (including
+entered input where relevant) as `success-<step>.png`; failure helpers capture
+`failure-<step>.png`. The ISO harness collects the screenshots and logs under
+its timestamped `test-runs/` directory and opens the screenshots after the run
+unless `--no-preview` is passed.
+
+The ISO harness exercises compositor-level shortcuts with QMP virtual keyboard
+input. In-guest `wtype` is suitable for typing into focused controls, but it
+does not reliably prove that a global Hyprland keybinding works.

agents/skills/command-metadata.md

@@ -0,0 +1,31 @@
+# Command Metadata
+
+Read this before adding or changing commands in `bin/`.
+
+Commands in `bin/` can declare CLI metadata in comments near the top of the
+file. `bin/omarchy` scans the first 80 lines, and tests expect command metadata
+to remain valid.
+
+Supported metadata keys:
+
+- `# omarchy:group=...` - override the command group inferred from the filename
+- `# omarchy:name=...` - override the command name inferred from the filename
+- `# omarchy:summary=...` - short help text
+- `# omarchy:args=...` - usage arguments
+- `# omarchy:examples=...` - examples separated with ` | `
+- `# omarchy:alias=...` / `# omarchy:aliases=...` - alternate routes
+- `# omarchy:hidden=true` - hide from default command listings
+- `# omarchy:requires-sudo=true` - mark commands that require sudo
+
+Only use `omarchy:examples` where there are args that need explaining.
+
+Prefer explicit metadata for user-facing commands. Keep routes consistent with
+the filename unless there is a deliberate alias or compatibility route.
+
+Example:
+
+```bash
+# omarchy:summary=Take a screenshot
+# omarchy:args=[smart|region|windows|fullscreen] [slurp|copy]
+# omarchy:examples=omarchy screenshot | omarchy capture screenshot region
+```

agents/skills/install-scripts.md

@@ -0,0 +1,19 @@
+# Install Scripts
+
+Read this before working under `install/` or on the system/user setup commands.
+
+The ISO owns installation orchestration. This repo ships target-side setup
+commands and reusable setup leaves:
+
+- `bin/omarchy-apply-system` runs root-owned system setup during ISO finalization.
+- `bin/omarchy-apply-hardware` runs idempotent hardware-specific setup and is called by `omarchy-apply-system`.
+- `bin/omarchy-finalize-user` runs the per-user runtime finalization (skill symlinks, xdg-user-dirs, mime defaults, `install/user/all.sh`). Shipped user defaults are seeded by `/etc/skel` from `omarchy-settings`, not by this command. `bin/omarchy-reinstall-configs` is the explicit destructive resync of those defaults into an existing user's `$HOME`.
+- leaf scripts under `install/` are sourced by `run_logged $OMARCHY_INSTALL/path/to/script.sh` and intentionally do not have shebangs.
+- avoid `exit` in sourced setup scripts unless intentionally aborting setup.
+- use `$OMARCHY_INSTALL` and `$OMARCHY_PATH` instead of hard-coded Omarchy paths.
+- keep root-scoped hardware setup under `install/hardware/` and orchestrate it through `install/hardware/all.sh`.
+- keep every per-user setup leaf under `install/user/` (including `install/user/hardware/` and `install/user/first-run/`) so it is clear what must run for each user.
+- prefer helper commands for package and command checks where available.
+
+Raw `command -v`, `pacman`, and `pacman-key` are acceptable in package-helper
+contexts where direct package-manager behavior is the point of the script.

agents/skills/shell-dev.md

@@ -0,0 +1,49 @@
+# Omarchy Shell Development
+
+Read this before editing the Quickshell desktop under `shell/`.
+
+The Quickshell desktop runs as a single long-running process out of
+`shell/`. Hyprland autostart launches it directly with `quickshell -n -p`;
+do not start additional standalone Quickshell instances for individual
+components.
+
+Run `omarchy-restart-shell` after making changes to QML files.
+
+## Plugin contract
+
+- First-party plugins live directly under `shell/plugins/` or one category
+  level deeper, such as `shell/plugins/panels/weather/`. First-party bar-only
+  widgets may use adjacent `*.manifest.json` files. Third-party plugins live
+  at `~/.config/omarchy/plugins/<id>/` with a `manifest.json` at the root.
+- Every plugin manifest declares `schemaVersion`, `id`, `name`, `version`,
+  `kinds`, and `entryPoints`. See
+  [`docs/omarchy-shell.md`](../../docs/omarchy-shell.md) and
+  `shell/services/PluginRegistry.qml` for the current contract; fields such as
+  `activation` are optional.
+- Entry-point QML files are `Item`s (not `ShellRoot`), and accept the
+  shell-injected properties `omarchyPath`, `shell`, `manifest`, and
+  `pluginRegistry` / `barWidgetRegistry` as appropriate.
+- Panel / overlay / menu plugins must expose `open(payloadJson)` and
+  `close()` lifecycle methods for `shell summon` and `shell hide`.
+
+## IPC
+
+- `bin/omarchy-shell` is the canonical IPC entry point. It forwards to
+  the running shell and does not start it. Prefer it over re-implementing
+  direct Quickshell socket calls in every CLI.
+- The `shell` IPC target exposes lifecycle and configuration methods including
+  `ping`, `summon`, `hide`, `toggle`, `call`, `rescanPlugins`, `reloadConfig`,
+  `setPluginEnabled`, and `listPlugins`. `shell.qml` also registers
+  `image-selector`, which drives the `omarchy.image-picker` panel.
+- Individual plugins register their own IPC targets, named for the plugin rather
+  than for where they appear: the background switcher registers `background`, and
+  bar widgets register one target each — `omarchy.indicators`,
+  `omarchy.system-update`, `omarchy.clock`. There is no `bar` target.
+
+## Editing widget files with glyphs
+
+Widget files in `shell/plugins/bar/widgets/` contain Nerd Font glyphs as raw
+unicode characters. Agent file-editing tools can strip multi-byte codepoints
+in some positions — do **not** rewrite widget files wholesale through those
+tools. For glyph fixes, make a targeted edit with the surrounding context, or
+use a Python script that inserts codepoints via `chr(0xXXXXX)`.