basecamp · dhh · Aug 7, 2026 · Aug 7, 2026 · Aug 7, 2026 · Aug 7, 2026
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,4 @@
+
+# Python bytecode (orchestrator)
+__pycache__/
+*.pyc
diff --git a/.luarc.json b/.luarc.json
@@ -0,0 +1,11 @@
+{
+  "workspace": {
+    "library": [
+      "/usr/share/hypr/stubs"
+    ],
+    "checkThirdParty": false
+  },
+  "diagnostics": {
+    "globals": ["hl"]
+  }
+}
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,9 +1,32 @@
+# 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/icon-font.md`](agents/skills/icon-font.md) - adding branded glyphs to `default/fonts/omarchy/omarchy.ttf`
+- [`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
+- [`agents/skills/migrations.md`](agents/skills/migrations.md) - creating or changing migrations under `migrations/`
+
+# Documentation Layout
+
+Three documentation trees, split by genre and audience:
+
+- `agents/skills/` - task procedure ("do this when doing X"), for anyone working on the codebase
+- `docs/` - reference on how the system is shaped (file layout, update pipeline, theming, shell architecture), for anyone working on the codebase; skills link here for depth
+- `manual/` - end-user documentation for using Omarchy, published; never codebase internals
+
 # Style
 
+- In markdown documents (`plans/`, `docs/`, `manual/`), write full lines — no hard wrapping at 80 columns; break only at structural boundaries like headings and list items
 - Two spaces for indentation, no tabs
 - Use bash 5 conditionals: use `[[ ]]` for string/file tests and `(( ))` for numeric tests
 - In `[[ ]]`, don't quote variables, but do quote string literals when comparing values (e.g., `[[ $branch == "dev" ]]`)
 - Prefer `(( ))` over numeric operators inside `[[ ]]` (e.g., `(( count < 50 ))`, not `[[ $count -lt 50 ]]`)
+- Prefer a full `if`/`else` conditional for simple two-path control flow; don't rely on `exec` or `exit` in one branch to make following statements unreachable
 - For strings/paths with spaces, quote them instead of escaping spaces with `\ ` (e.g., `"$APP_DIR/Disk Usage.desktop"`, not `$APP_DIR/Disk\ Usage.desktop`)
 - Shebangs must use `#!/bin/bash` consistently (never `#!/usr/bin/env bash`)
 - Scripts under `install/` and `migrations/` may be sourced and intentionally omit shebangs
@@ -12,7 +35,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 +54,80 @@ 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-`
+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.
 
-# 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.
-
-Supported metadata keys:
-
-- `# 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
-
-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:group=capture
-# omarchy:args=[smart|region|windows|fullscreen] [slurp|copy]
-# omarchy:examples=omarchy screenshot | omarchy capture screenshot region
-# omarchy:aliases=omarchy screenshot
-```
+# Runtime Environment
 
-# Install Scripts
+- `$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.
 
-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.
+# Privileged Commands
 
-Install stage files follow this pattern:
+- 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.
 
-- `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
+# Git
 
-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.
+
+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.
+
+# Menu
+
+- The menu definition lives in `default/omarchy/omarchy-menu.jsonc`;
+  [`docs/menu.md`](docs/menu.md) covers the schema, guards, and providers.
+- Do not add `aliases` to new menu entries. Aliases are reserved for
+  established alternate names users already type, kept for compatibility.
 
 # Config Structure
 
 - `config/` - default configs copied to `~/.config/`
 - `default/themed/*.tpl` - templates with `{{ variable }}` placeholders for theme colors
-- `themes/*/colors.toml` - theme color definitions (accent, background, foreground, color0-15)
+- `themes/*/colors.toml` - theme color definitions (accent, background, foreground, red/green/yellow/blue/magenta/cyan and bright_* variants)
 
-# Visual Changes
+# Tests
 
-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.
+Run focused automated tests for the area you changed;
+[`docs/testing.md`](docs/testing.md) covers how the suites are shaped. Current
+test entry points:
 
-# Refresh Pattern
+- `./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/`
 
-To copy a default config to user config with automatic backup:
+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.
 
-```bash
-omarchy-refresh-config hypr/hyprlock.conf
-```
+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).
 
-This copies `~/.local/share/omarchy/config/hypr/hyprlock.conf` to `~/.config/hypr/hyprlock.conf`.
+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).
 
-# Migrations
-
-To create a new migration, run `omarchy-dev-add-migration --no-edit`. This creates a migration file named after the unix timestamp of the last commit.
-
-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`
-
-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.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/README.md b/README.md
@@ -4,6 +4,77 @@ Omarchy is a beautiful, modern & opinionated Linux distribution by DHH.
 
 Read more at [omarchy.org](https://omarchy.org).
 
+## The Omarchy Manual
+
+The manual lives in [`manual/`](manual/), which is its authoritative source. It's
+mirrored to [learn.omacom.io](https://learn.omacom.io/2/the-omarchy-manual), where
+its screenshots are also hosted.
+
+- [Welcome to Omarchy!](manual/01-welcome-to-omarchy.md)
+
+**The Basics**
+
+- [Getting Started](manual/02-getting-started.md)
+- [Coming From Mac or Windows](manual/03-coming-from-mac-or-windows.md)
+- [Navigation](manual/04-navigation.md)
+- [The top bar](manual/05-the-top-bar.md)
+- [Themes](manual/06-themes.md)
+- [Hotkeys](manual/07-hotkeys.md)
+- [Unified Clipboard & History](manual/08-unified-clipboard-history.md)
+- [Reminders](manual/09-reminders.md)
+- [Notices](manual/10-notices.md)
+- [Text Extraction & Dictation](manual/11-text-extraction-dictation.md)
+- [Screenshots & Recording](manual/12-screenshots-recording.md)
+- [Toggles, idle & screensaver](manual/13-toggles-idle-screensaver.md)
+- [Omarchy CLI](manual/14-omarchy-cli.md)
+
+**The Applications**
+
+- [Terminal](manual/15-terminal.md)
+- [Neovim](manual/16-neovim.md)
+- [AI](manual/17-ai.md)
+- [Development Tools](manual/18-development-tools.md)
+- [Shell Tools](manual/19-shell-tools.md)
+- [Shell Functions](manual/20-shell-functions.md)
+- [TUIs](manual/21-tuis.md)
+- [GUIs](manual/22-guis.md)
+- [Browsers](manual/23-browsers.md)
+- [Commercial apps/services](manual/24-commercial-apps-services.md)
+- [Web Apps](manual/25-web-apps.md)
+- [Gaming](manual/26-gaming.md)
+- [Filling out PDFs](manual/27-filling-out-pdfs.md)
+- [Windows VM](manual/28-windows-vm.md)
+- [Other Packages](manual/29-other-packages.md)
+
+**Configuration**
+
+- [Updates](manual/30-updates.md)
+- [Dotfiles](manual/31-dotfiles.md)
+- [Shell plugins](manual/32-shell-plugins.md)
+- [Monitors](manual/33-monitors.md)
+- [Keyboard, Mouse, Trackpad](manual/34-keyboard-mouse-trackpad.md)
+- [Networking](manual/35-networking.md)
+- [System sleep](manual/36-system-sleep.md)
+- [Hardware authentication](manual/37-hardware-authentication.md)
+- [Fonts](manual/38-fonts.md)
+- [Backgrounds](manual/39-backgrounds.md)
+- [Prompt](manual/40-prompt.md)
+- [Branding](manual/41-branding.md)
+- [Common tweaks](manual/42-common-tweaks.md)
+- [Extra themes](manual/43-extra-themes.md)
+- [Making your own theme](manual/44-making-your-own-theme.md)
+
+**The Rest**
+
+- [Mac support](manual/45-mac-support.md)
+- [Troubleshooting](manual/46-troubleshooting.md)
+- [FAQ](manual/47-faq.md)
+- [System snapshots](manual/48-system-snapshots.md)
+- [Security](manual/49-security.md)
+- [Omarchy on...](manual/50-omarchy-on.md)
+- [Dual Boot Install](manual/51-dual-boot-install.md)
+- [Unattended Installs](manual/52-unattended-installs.md)
+
 ## License
 
 Omarchy is released under the [MIT License](https://opensource.org/licenses/MIT).
diff --git a/agents/skills/acceptance-tests.md b/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.
diff --git a/agents/skills/command-metadata.md b/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
+```