{"owner":"basecamp","repo":"omarchy","hasSkills":true,"totalSkillsCount":70,"totalTokensCount":34499,"categories":["root-instruction","subagent-persona","anthropic-skill","plugin-manifest"],"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","agents/skills/acceptance-tests.md","agents/skills/migrations.md","agents/skills/mise-tools.md","agents/skills/shell-dev.md","agents/skills/install-scripts.md","agents/skills/command-metadata.md","agents/skills/icon-font.md","default/agents/skills/omarchy-app/SKILL.md","default/agents/skills/diagnose-crash/SKILL.md","default/agents/skills/omarchy/SKILL.md","agents/skills/visual-verification.md","shell/plugins/README.md","shell/plugins/agents/README.md","shell/plugins/agents/manifest.json","shell/plugins/background/manifest.json","shell/plugins/bar/README.md","shell/plugins/bar/manifest.json","shell/plugins/clipboard/manifest.json","shell/plugins/dev-gallery/manifest.json","shell/plugins/dock/manifest.json","shell/plugins/emojis/emojis.json","shell/plugins/emojis/manifest.json","shell/plugins/image-picker/manifest.json","shell/plugins/lock/manifest.json","shell/plugins/menu/manifest.json","shell/plugins/notifications/manifest.json","shell/plugins/osd/manifest.json","shell/plugins/polkit/manifest.json","shell/plugins/reminders/manifest.json","default/agents/skills/diagnose-crash/reporting.md","default/agents/skills/omarchy-app/templates.md","default/agents/skills/omarchy/capture.md","default/agents/skills/omarchy/contributing.md","default/agents/skills/omarchy/hooks.md","default/agents/skills/omarchy/hyprland.md","default/agents/skills/omarchy/plugins.md","default/agents/skills/omarchy/theming.md","default/chromium/extensions/copy-url/manifest.json","default/chromium/extensions/whatsapp-slim/manifest.json","default/chromium/extensions/yt-dlp/manifest.json","shell/plugins/bar/widgets/ActiveWindow.manifest.json","shell/plugins/bar/widgets/Indicators.manifest.json","shell/plugins/bar/widgets/KeyboardLayout.manifest.json","shell/plugins/bar/widgets/Microphone.manifest.json","shell/plugins/bar/widgets/Spacer.manifest.json","shell/plugins/bar/widgets/SystemUpdate.manifest.json","shell/plugins/bar/widgets/Tray.manifest.json","shell/plugins/bar/widgets/Workspaces.manifest.json","shell/plugins/panels/audio/manifest.json","shell/plugins/panels/bluetooth/manifest.json","shell/plugins/panels/clock/manifest.json","shell/plugins/panels/disk-speedtest/manifest.json","shell/plugins/panels/dropbox/manifest.json","shell/plugins/panels/elsewhen/cities.json","shell/plugins/panels/elsewhen/manifest.json","shell/plugins/panels/elsewhen/world.json","shell/plugins/panels/monitor/manifest.json","shell/plugins/panels/network/manifest.json","shell/plugins/panels/power/manifest.json","shell/plugins/panels/speedtest/manifest.json","shell/plugins/panels/tailscale/README.md","shell/plugins/panels/tailscale/manifest.json","shell/plugins/panels/weather/manifest.json","shell/plugins/panels/wifiqr/manifest.json","shell/plugins/services/battery/manifest.json","shell/plugins/services/idle/manifest.json","shell/plugins/services/media/manifest.json","shell/plugins/services/nightlight/manifest.json","shell/plugins/services/remote-session/manifest.json"],"skills":{"AGENTS.md":"# Task Guides\n\nDeeper instructions for specific kinds of work live in `agents/skills/`. Read the\nmatching guide before starting:\n\n- [`agents/skills/command-metadata.md`](agents/skills/command-metadata.md) - adding or changing commands in `bin/`\n- [`agents/skills/install-scripts.md`](agents/skills/install-scripts.md) - working under `install/` or on system/user setup commands\n- [`agents/skills/mise-tools.md`](agents/skills/mise-tools.md) - adding or changing mise-managed tools\n- [`agents/skills/shell-dev.md`](agents/skills/shell-dev.md) - editing the Quickshell desktop under `shell/`\n- [`agents/skills/icon-font.md`](agents/skills/icon-font.md) - adding branded glyphs to `default/fonts/omarchy/omarchy.ttf`\n- [`agents/skills/acceptance-tests.md`](agents/skills/acceptance-tests.md) - writing or running graphical acceptance tests under `test/acceptance.d/`\n- [`agents/skills/visual-verification.md`](agents/skills/visual-verification.md) - verifying any change with a visual effect in the running UI\n- [`agents/skills/migrations.md`](agents/skills/migrations.md) - creating or changing migrations under `migrations/`\n\n# Documentation Layout\n\nThree documentation trees, split by genre and audience:\n\n- `agents/skills/` - task procedure (\"do this when doing X\"), for anyone working on the codebase\n- `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\n- `manual/` - end-user documentation for using Omarchy, published; never codebase internals\n\n# Style\n\n- 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\n- Two spaces for indentation, no tabs\n- Use bash 5 conditionals: use `[[ ]]` for string/file tests and `(( ))` for numeric tests\n- In `[[ ]]`, don't quote variables, but do quote string literals when comparing values (e.g., `[[ $branch == \"dev\" ]]`)\n- Prefer `(( ))` over numeric operators inside `[[ ]]` (e.g., `(( count < 50 ))`, not `[[ $count -lt 50 ]]`)\n- 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\n- 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`)\n- Shebangs must use `#!/bin/bash` consistently (never `#!/usr/bin/env bash`). A security-sensitive entrypoint may use the exact `#!/bin/bash -p` form only when it must suppress `BASH_ENV` and exported-function startup injection before its first command; that exception must be explained at the boundary and covered by a regression that rejects an ordinary Bash launch with a decoy `-p` argument.\n- Scripts under `install/` and `migrations/` may be sourced and intentionally omit shebangs\n\n# Command Naming\n\nAll commands start with `omarchy-`. Prefixes indicate purpose.\n\nThe 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.\n\nA 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 ` still prints a group header without one.\n\nCommon prefixes include:\n\n- `cmd-` - check if commands exist, misc utility commands\n- `capture-` - screenshots, screen recordings, and other capture tools\n- `pkg-` - package management helpers\n- `hw-` - hardware detection (return exit codes for use in conditionals)\n- `refresh-` - copy default config to user's `~/.config/`\n- `restart-` - restart a component\n- `launch-` - open applications\n- `install-` - install optional software\n- `setup-` - interactive setup wizards\n- `toggle-` - toggle features on/off\n- `theme-` - theme management\n- `update-` - update components\n\nDo not maintain a second exhaustive prefix list here. Consult\n`GROUP_DESCRIPTIONS` when selecting or checking a command group so this\nguidance does not drift from the router.\n\n# Runtime Environment\n\n- `$OMARCHY_PATH` is set at the top level by the uwsm session environment and is always available to Omarchy runtime code.\n- 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.\n\n# Platforms\n\nOmarchy runs on x86 and aarch64 (ARM). A platform name is the CPU architecture, then a hardware family only when that family needs handling of its own:\n\n- `x86` - every x86_64 machine\n- `aarch64` - every ARM machine without a family of its own (Raspberry Pis and ARM VMs today)\n- `aarch64-apple` - Apple Silicon Macs\n- `aarch64-qualcomm` - Snapdragon laptops\n- `aarch64-n1x` - NVIDIA N1x laptops\n- `aarch64-gb10` - NVIDIA GB10 desktops (DGX Spark, ASUS Ascent GX10)\n\nA new family is named `aarch64-` (e.g. `aarch64-qualcomm`, `aarch64-n1x`) and is added only once it needs code of its own, so `aarch64*` always means ARM. `omarchy-hw-platform` prints the most specific name. Use these exact names wherever a platform is named: package lists, pacman template directories, image manifests, dispatch registration, tests and docs. Never introduce `generic`, `arm64`, `apple-silicon` or other spellings; the old `apple-silicon`, `generic-aarch64` and `generic` are read only for compatibility with older image builders.\n\nAsk a helper; don't read `uname -m` or the device tree in feature code:\n\n- `omarchy-hw-x86` / `omarchy-hw-aarch64` - the CPU architecture. Use them for binary and ABI availability: a package with no aarch64 build, an x86 guest VM, multilib.\n- `omarchy-hw-aarch64-apple`, `omarchy-hw-aarch64-qualcomm`, `omarchy-hw-aarch64-n1x`, `omarchy-hw-aarch64-gb10` (one per family) - built on `omarchy-hw-platform`, image-build aware. Use them for hardware behaviour that the whole family shares; a single model's quirks stay behind `omarchy-hw-match` on its DMI name, or behind `omarchy-hw-match-device-tree` on its device-tree compatible string where models share a DMI name. `omarchy-hw-apple-silicon` and `omarchy-hw-n1x` are hidden aliases kept for the omarchy-mac packages and older N1x images; don't use them in new code.\n\nWhere platform code lives:\n\n- Packages: `install/omarchy-base.packages` for everyone, `install/omarchy-aarch64.packages` for every ARM machine, `install/omarchy-.packages` for one family, and base packages with no aarch64 build in `install/omarchy-x86_64-only.packages`. `omarchy-pkg-defaults` composes them.\n- Pacman templates: `default/pacman/` for x86, `default/pacman//` for each ARM platform.\n- Hardware setup: `install/hardware//`, gated by a predicate. `install/hardware/apple/` holds Intel Mac quirks; Apple Silicon's own setup ships in the omarchy-mac packages.\n- Boot chains Omarchy can't drive generically: a platform package behind `omarchy-lifecycle-dispatch` ([`docs/lifecycle-dispatch.md`](docs/lifecycle-dispatch.md)). Platforms that boot Limine with UKIs like x86 keep the generic path.\n\nThe experience should be the same on every platform. When a package or feature is missing or broken on one, the default is to get it fixed upstream (an aarch64 build, a bug report, a patch to the maintainer) and leave the gap visible meanwhile, not to paper over it. When asked for a platform workaround, say so and propose the upstream fix first. Hiding a menu entry or skipping a package is fine only for things that can't exist there (an x86 guest VM, an x86-only proprietary binary). Alternative packages and platform-only replacements are a last resort, used only when upstream can't or won't fix it, with the reason written next to the code.\n\n# Privileged Commands\n\n- Follow the \"Privilege Escalation\" section of `default/agents/skills/omarchy/SKILL.md`. It draws the\n `sudo`/`pkexec` line by whether the caller has a terminal to enter a password in, and the repo's\n own scripts follow it.\n\n# Git\n\n- Commits should be atomic: include only one coherent change or fix, and do not mix unrelated work.\n- Commit messages should be succinct and describe the change being made.\n\n# Helper Commands\n\nUse these instead of raw shell commands:\n\n- `omarchy-cmd-missing` / `omarchy-cmd-present` - check for commands\n- `omarchy-pkg-missing` / `omarchy-pkg-present` - check for packages (don't use these if you can just use `omarchy-pkg-add`/`omarchy-pkg-drop`)\n- `omarchy-pkg-add` - install packages from the configured pacman repos, Omarchy's included; use `omarchy-pkg-aur-add` for AUR packages\n- `omarchy-pkg-drop` - remove packages; use this instead of raw `pacman -R*`\n- `omarchy-notification-send` - send desktop notifications; do not call `notify-send` directly\n- `omarchy-hw-asus-rog` - detect ASUS ROG hardware (and similar `hw-*` commands)\n\nCommands 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.\n\nExceptions 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.\n\n# Background Work\n\n- Long-running code (the shell, daemons, watchers) reacts to events instead of polling with a timer. Polling is the last resort, for state with no change signal; [`agents/skills/shell-dev.md`](agents/skills/shell-dev.md) lists the event sources and the push-refresh pattern.\n- `test/shell.d/shell-idle-spawn-test.sh` fails when an idle shell starts any process, and other tests hold the router, menu guards and theme switch to budgets; see \"Performance guards\" in [`docs/testing.md`](docs/testing.md).\n\n# Menu\n\n- The menu definition lives in `default/omarchy/omarchy-menu.jsonc`;\n [`docs/menu.md`](docs/menu.md) covers the schema, guards, and providers.\n- Do not add `aliases` to new menu entries. Aliases are reserved for\n established alternate names users already type, kept for compatibility.\n\n# Config Structure\n\n- `config/` - default configs copied to `~/.config/`\n- `default/themed/*.tpl` - templates with `{{ variable }}` placeholders for theme colors\n- `themes/*/colors.toml` - theme color definitions (accent, background, foreground, red/green/yellow/blue/magenta/cyan and bright_* variants)\n\n# Tests\n\nRun focused automated tests for the area you changed;\n[`docs/testing.md`](docs/testing.md) covers how the suites are shaped. Current\ntest entry points:\n\n- `./test/all` - aggregate runner for CLI and shell tests; it intentionally does not run graphical acceptance tests\n- `./test/cli` - CLI routing, command metadata, theme helpers, and safe dispatch coverage\n- `./test/shell` - all Omarchy shell tests under `test/shell.d/`\n\nHow to run them without wasting runs:\n\n- Run the files for what you changed directly: `bash test/shell.d/-test.sh`. A change inside one plugin or command runs that area's files (and `i18n-test.sh` when catalog strings changed), not `./test/shell`.\n- Run `./test/shell` or `./test/all` only when the change reaches shared code (`shell/Commons/`, `base-test.sh`, the runners, a widely used `bin/` helper), and then once, at the end.\n- Always write the whole output to a log file and read it from there: `bash test/shell.d/-test.sh >/tmp/.log 2>&1`. Never pipe a test run straight through `grep`, `head` or `tail`: what they drop is gone, and getting it back costs a whole run. `./test/shell` keeps every file's log and prints the directory at the end; read a failure from its log.\n- Run a test again only after changing something it covers. Never rerun to see output, to confirm a pass, or in the hope that a failure goes away.\n- For a failure in a file you did not touch, run that one file once on the base branch (in a worktree, or with `git stash`). If it fails there too, it was already broken: report it and leave it out of this change.\n- Tests that use the live session (`require_compositor`, `shell-idle-spawn-test.sh`) read the real desktop, so the user working at it can fail them. One that fails in a full run and passes alone is session noise: say so; do not loop on it.\n\nWhen to add a test. A test earns its place only by catching a regression nothing else would; every one costs a maintainer to read and everyone a slower suite. Before writing one, name the breakage it would catch. If the answer is \"someone edits the line I just added\", don't write it.\n\n- No test for a small declarative change: a menu row, a config value, a package-list entry, a string, a rename. Those need no test of their own, and certainly not a new file.\n- Don't restate the implementation: grepping the source or config for the string you just added, asserting a value equals itself, or re-reading the file you edited to confirm the edit is there.\n- A test must fail without your change. Revert the fix, or reason it through, and check that the test goes red for the reason the change exists. One that stays green guards nothing.\n- Don't test your own stub. If a fake binary or fixture the test writes provides the behaviour under test, nothing real is tested.\n- No change-detectors: snapshots of large output, file lists, or exact counts that break whenever someone adds an unrelated entry.\n- Extend the area's existing test file (`git grep` the command or function under `test/`) rather than adding a new `*-test.sh`, and follow its style.\n- Keep tests in proportion to the change. A few lines of change rarely justify more than a few lines of test, and usually none.\n- Do test real logic: parsing, routing, a migration's idempotence and no-op paths, a guard on hardware without the feature, the edge case a fix handles. A bug fix with logic in it gets the one test that fails on the base branch and passes with the fix.\n\nNew 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.\n\nThe graphical acceptance suite runs in a disposable VM, not in the active\ndevelopment session; see [`agents/skills/acceptance-tests.md`](agents/skills/acceptance-tests.md).\n\nVisual changes must be verified in the running UI in addition to automated\ntests; follow [`agents/skills/visual-verification.md`](agents/skills/visual-verification.md).\n\n# Refresh Pattern\n\nTo copy a default config to user config with automatic backup:\n\n```bash\nomarchy-refresh-config hypr/hyprland.lua\n```\n\nThis copies `$OMARCHY_PATH/config/hypr/hyprland.lua` to `~/.config/hypr/hyprland.lua`. The argument\nis interpolated into both paths and only checked with `[[ -e ]]`, so pass a plain relative path: a\nname containing `..` resolves and copies, landing outside `~/.config` rather than being rejected.\n","agents/skills/acceptance-tests.md":"# Acceptance Tests\n\nRead this before writing or running the graphical acceptance suite under\n`test/acceptance.d/`.\n\nThe graphical acceptance suite lives in `test/acceptance` with test files under\n`test/acceptance.d/*-test.sh`. It exercises a real installed Omarchy desktop,\nincluding session health, shell surfaces, panels, keyboard navigation,\nrepresentative applications, and system setup. Source\n`test/acceptance.d/base-test.sh` for the shared helpers.\n\nRun acceptance tests in a disposable VM through the sibling `omarchy-iso`\nrepository, not in the active development session. The suite opens and closes\napplications and temporarily changes desktop configuration.\n\nFor acceptance-test-only changes, reuse an installed base and sync the suite:\n\n```bash\ncd ../omarchy-iso\n./bin/omarchy-iso-test release/.iso --reuse-base --sync-omarchy ../omarchy --no-preview\n```\n\nUse `--sync-all ../omarchy` instead of `--sync-omarchy ../omarchy` when the\nacceptance run must exercise local `bin/`, `config/`, or `shell/` source too.\nChanges to package manifests, installation, finalization, or shipped defaults\nrequire a fresh ISO built from the local checkouts and a run without\n`--reuse-base`:\n\n```bash\ncd ../omarchy-iso\n./bin/omarchy-iso-make --no-boot-offer --local-source ../omarchy ../omarchy-pkgs\n./bin/omarchy-iso-test release/.iso --no-preview\n```\n\nKeep unrelated acceptance workflows in separate test files. The runner records\na failed file and continues with the remaining files, which preserves as much\ndiagnostic coverage as possible. Restore modified user state with traps, close\nanything the test opens, and capture every visually distinct state (including\nentered input where relevant) as `success-.png`; failure helpers capture\n`failure-.png`. The ISO harness collects the screenshots and logs under\nits timestamped `test-runs/` directory and opens the screenshots after the run\nunless `--no-preview` is passed.\n\nThe ISO harness exercises compositor-level shortcuts with QMP virtual keyboard\ninput. In-guest `wtype` is suitable for typing into focused controls, but it\ndoes not reliably prove that a global Hyprland keybinding works.\n","agents/skills/migrations.md":"# Omarchy migrations\n\nRead this before creating or changing migrations under `migrations/`.\n\nOmarchy migrations are one-time repair scripts for existing installs. They are\nused when a package update needs to change state that pacman cannot safely own by\nitself.\n\n## Migration model\n\nMigrations live in:\n\n```text\nmigrations/*.sh\n```\n\nThey run as the current Omarchy user through `omarchy-migrate`, normally during\n`omarchy update`. A migration may touch user/session state (`~/.config`,\n`~/.local`, user systemd, browser/editor prefs, DBus/session state), and may also\nperform machine-wide repairs when needed.\n\nCompletion state is per-user:\n\n```text\n~/.local/state/omarchy/migrations/\n```\n\nThat means every user gets a chance to run every migration. Migrations run as the\nuser; privileged operations should invoke the appropriate helper or privilege\nprompt themselves. Migrations must be idempotent: if one user already applied a\nmachine-wide repair, the same migration running for another user should detect\nthat and no-op.\n\n## When migrations run\n\n### During `omarchy update`\n\n`omarchy update` is the normal update path. It runs package updates, then:\n\n```bash\nomarchy-migrate\nomarchy-hook post-update\n```\n\n`omarchy-migrate` waits for any active pacman transaction to finish, then runs\nall pending migrations for the current user in the visible update terminal.\n\n### At login\n\nEvery graphical login starts `omarchy-migrate-notify.service` after\n`graphical-session.target`. The notifier checks:\n\n```bash\nomarchy-migrate --pending\n```\n\nIt stays silent while `omarchy update` holds its lock, since that update applies\nthe pending migrations itself.\n\nIf that user has pending migrations, it shows a notification that opens a\nterminal for:\n\n```bash\nomarchy-migrate\n```\n\nThe notifier never runs migrations silently in the background.\n\nThis is what covers users who did not run the update themselves: someone who\nbypassed the pacman guard with `sudo env OMARCHY_ALLOW_DIRECT_PACMAN=1 pacman\n-Syu`, and any second user on the machine, whose migration markers are per-user\nand therefore still missing after another user updated.\n\nLogin is the only trigger on purpose. Watching the packaged migration directory\nalso fires during a normal `omarchy update`, which prompts for migrations that\n`omarchy-migrate` is about to run in the visible update terminal.\n\n### Manually\n\nUsers can safely run:\n\n```bash\nomarchy-migrate\n```\n\nat any time. Already-completed migrations are skipped.\n\n## Inspecting pending migrations\n\nUse:\n\n```bash\nomarchy-migrate --pending\n```\n\nExit behavior:\n\n- `0` — one or more migrations are pending\n- non-zero — no migrations are pending\n\nOutput is one pending migration per line:\n\n```text\n1781158082.sh\n```\n\n## Creating a migration\n\nUse the helper:\n\n```bash\nomarchy-dev-add-migration --no-edit\n```\n\nThis creates:\n\n```text\nmigrations/.sh\n```\n\nNew migration format:\n\n- File permissions must be `0644` (`-rw-r--r--`). Migration runners execute them\n with `bash -euo pipefail`, not through executable bits.\n- No shebang line.\n- Start with an `echo` describing what the migration does.\n- Use `$OMARCHY_PATH` to reference the Omarchy directory.\n- Be idempotent. Check existing state before changing it.\n- Migrations are strictly ordered and synchronous. A migration that cannot finish must exit non-zero, remain pending, and stop the queue; never mark later migrations complete against state an earlier migration has not established.\n- Use helper commands such as `omarchy-cmd-present`, `omarchy-cmd-missing`,\n `omarchy-pkg-add`, `omarchy-pkg-drop`, `omarchy-pkg-present`, and\n `omarchy-pkg-missing` when appropriate.\n- Never restart the Omarchy shell. `omarchy update` restarts it unconditionally\n after migrations run, and the login-time shell already runs current code and\n hot-reloads `shell.json` edits.\n- Raw `pacman`, `command -v`, and direct config edits are acceptable when\n needed for one-off repair work.\n\nExample:\n\n```bash\necho \"Relink Neovim theme to Omarchy current state\"\n\ntheme_link=\"$HOME/.config/nvim/lua/plugins/theme.lua\"\ncurrent_relative_target=\"../../../../.local/state/omarchy/current/theme/neovim.lua\"\n\n[[ -L $theme_link ]] || exit 0\nln -sfn \"$current_relative_target\" \"$theme_link\"\n```\n\n## Testing migrations\n\nRun a migration against a temporary home when possible:\n\n```bash\nHOME=$(mktemp -d) bash -euo pipefail migrations/.sh\n```\n\nTo rerun a migration locally, remove its marker and run the migrator:\n\n```bash\nrm ~/.local/state/omarchy/migrations/.sh\nomarchy-migrate\n```\n\nKeep 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.\n\nOmarchy 4.0 is upgraded through `bin/omarchy-upgrade-to-quattro`, not through the\nnormal migration runner. Do not add compatibility migrations for old installer\nlayouts; put pre-4 package-layout transition work in the upgrade command instead.\n\nClearing a privileged file that a retired installer left on disk is the exception, and belongs in a migration whether or not that installer was part of a package layout transition. The upgrade command only runs on a machine still making the 3 to 4 crossing, so anything put there never reaches an install that crossed already, and it never runs at all for an installer that was retired on its own — while the file the installer wrote is still sitting on those machines. The upgrade command finishes by running `omarchy-migrate` (`run_post_upgrade_migrations`), so one migration reaches every population; a copy in the upgrade command would only be a second copy of the same predicate to keep correct. Such a migration must name the defect it clears and match what the old installer actually produced before deleting it. Leave safe administrator-authored files alone; if one still contains the vulnerable privileged action, preserve it under an inactive name rather than discarding custom content or leaving the action executable. A user config that depends on the same retired compatibility path may be repaired in that migration when doing so eliminates an overlapping migration, but only by matching and replacing the exact legacy path while preserving the rest of the file.\n","agents/skills/mise-tools.md":"# mise-managed tools\n\nRead this before adding or changing a mise-managed tool. Default tools belong in `etc/mise/conf.d/omarchy-tools.toml`, which the settings package installs; `install/user/mise.sh` creates their native mise shims during user setup.\n\n## Leave the user's config alone\n\nOmarchy does not write `~/.config/mise/config.toml`; it is the user's, for overriding what Omarchy ships. Settings go in `etc/mise/conf.d/omarchy.toml`, which still loads after a user opts out of the default tools, and tools in `omarchy-tools.toml`. A command that installs a default tool runs `mise install ` when `omarchy-mise-default-tools declares `, and `mise use -g` only for a user who opted out. `mise use -g` on a declared tool would copy the declaration's options, `lazy = true` included, into the user's config.\n\n## Declare a default tool\n\nUse a registry shorthand and set `lazy = true` so the first command invocation installs the tool. Follow the existing defaults' release policy: `minimum_release_age = \"0s\"` makes new releases eligible immediately.\n\n```toml\n[tools]\ncodex = { version = \"latest\", lazy = true, minimum_release_age = \"0s\" }\n```\n\nLazy defaults need mise 2026.10.11 or newer. Older releases install every lazy tool nobody has run yet. Before 2026.10.11, a bare `mise upgrade`, which `omarchy update` and `mup` run, does it. In 2026.10.7 and 2026.10.8, the `auto_update` check a shell prompt starts did it too.\n\nAgent CLIs also set `auto_update = \"4h\"`, so mise upgrades them before they run (at most once every four hours) instead of leaving them on whatever version was installed first. Leave it off for tools that mise itself calls, such as `gh`, which is mise's GitHub credential helper.\n\n```toml\n[tools]\ncodex = { version = \"latest\", lazy = true, auto_update = \"4h\", minimum_release_age = \"0s\" }\n```\n\nDo not add handwritten wrappers for ordinary tools. Hermes keeps its custom installer because it needs Python 3.13 and must defer to Hermes Desktop when that app owns the command.\n\n## Choose the registry name\n\nBefore adding a GitHub- or Aqua-backed tool, run `mise registry ` and inspect the result. The tool name and command may differ: `hey-cli` provides `hey`, for example.\n\nUse the registry shorthand instead of an explicit `github:` or `aqua:` backend. Shorthands let mise use for cached version and public GitHub release metadata, reducing GitHub API requests during installation and updates.\n\nIf a GitHub- or Aqua-backed tool has no registry entry, request one upstream with the repository or package URL and the required command name. Wait for that entry before adding the tool to Omarchy; do not substitute an explicit `github:` or `aqua:` declaration.\n\n## Handle backend exceptions\n\nOther explicit backends, such as `pipx:`, may be used when their behavior or options are required. Check that a shorthand refers to the intended tool: `cf` names Cloud Foundry in mise's registry, so Omarchy uses `npm:cf` for the Cloudflare CLI.\n\nWhen an explicit backend has no registry binary metadata, declare the commands mise should create lazy shims for:\n\n```toml\n[tools]\n\"npm:cf\" = { version = \"latest\", lazy = true, lazy_bins = [\"cf\"], minimum_release_age = \"0s\" }\n```\n\nAfter changing declarations, verify that `mise reshim --system` creates the expected commands in an isolated test environment. Test first-use installation as well as an already-installed tool; a declaration alone does not prove its shim works.\n","agents/skills/shell-dev.md":"# Omarchy Shell Development\n\nRead this before editing the Quickshell desktop under `shell/`.\n\nThe Quickshell desktop runs as a single long-running process out of\n`shell/`. Hyprland autostart launches it directly with `quickshell -n -p`;\ndo not start additional standalone Quickshell instances for individual\ncomponents.\n\nRun `omarchy-restart-shell` after making changes to QML files.\n\n## Plugin contract\n\n- First-party plugins live directly under `shell/plugins/` or one category\n level deeper, such as `shell/plugins/panels/weather/`. First-party bar-only\n widgets may use adjacent `*.manifest.json` files. Third-party plugins live\n at `~/.config/omarchy/plugins//` with a `manifest.json` at the root.\n- Every plugin manifest declares `schemaVersion`, `id`, `name`, `version`,\n `kinds`, and `entryPoints`. See\n [`docs/omarchy-shell.md`](../../docs/omarchy-shell.md) and\n `shell/services/PluginRegistry.qml` for the current contract; fields such as\n `activation` are optional.\n- Entry-point QML files are `Item`s (not `ShellRoot`), and accept the shell-injected properties `omarchyPath`, `shell`, `manifest`, and `pluginRegistry` / `barWidgetRegistry` as appropriate. First-party plugins receive the host objects. Third-party plugins receive capability-scoped facades: ordinary plugins may look up and control only their own service and lifecycle, built-in clones retain narrow source-specific configuration and UI compatibility, menu plugins receive an application-library facade, and plugins can read detached scalar bar state; full-bar plugins additionally receive detached bar configuration and widget-catalog snapshots, narrow proxies for the non-authentication services used by built-in bar widgets, and lifecycle control over configured non-authentication UI plugins. Authentication capabilities must be stamped from trusted first-party manifests, and third-party registry views and bar configuration must be detached snapshots rather than shared objects. These facades reduce accidental authority but are not a same-process QML sandbox: a visual bar widget can walk its parent hierarchy to ordinary host objects. Authentication services must therefore remain outside both `ShellRoot._services` and the host QObject tree. Do not expose authentication services through new third-party-facing properties.\n- Panel / overlay / menu plugins must expose `open(payloadJson)` and\n `close()` lifecycle methods for `shell summon` and `shell hide`.\n- A panel built on `KeyboardPanel` passes its card as `content: PanelKeyCatcher { … }` rather than as children, so the tree is built the first time the panel opens instead of at startup on every monitor, and kept from then on. Ids inside the content are invisible to the rest of the file: expose the ones root-level code needs with `property alias` on the content root, read them through `panel.loadedContent` (null until the first open), and keep anything that must run while the panel is closed (timers, data, IPC) outside the content.\n\n## IPC\n\n- `bin/omarchy-shell` is the canonical IPC entry point. It forwards to\n the running shell and does not start it. Prefer it over re-implementing\n direct Quickshell socket calls in every CLI.\n- The `shell` IPC target exposes lifecycle and configuration methods including\n `ping`, `summon`, `hide`, `toggle`, `call`, `rescanPlugins`, `reloadConfig`,\n `setPluginEnabled`, and `listPlugins`. `shell.qml` also registers\n `image-selector`, which drives the `omarchy.image-picker` panel.\n- Individual plugins register their own IPC targets, named for the plugin rather\n than for where they appear: the background switcher registers `background`, and\n bar widgets register one target each — `omarchy.indicators`,\n `omarchy.system-update`, `omarchy.clock`. There is no `bar` target.\n\n## Keeping state current without polling\n\nThe shell runs all day on battery, and a widget is built once per monitor, so a `Timer` that starts a `Process` costs that process times the number of monitors, every tick, forever. Don't poll for state that only changes through known events. Pick the first of these that fits:\n\n- A native Quickshell service that signals on change: `UPower` and `PowerProfiles` (`Quickshell.Services.UPower`), `Hyprland` and each workspace's `lastIpcObject`, `Pipewire`, `Mpris`, `SystemTray`, `Notifications`.\n- An event stream the shell already runs, such as the Hyprland IPC events or the long-running `pactl subscribe` in `Commons/UntypedInput.qml`. Extend it rather than starting a second one.\n- A file watch: `FileView` with `watchChanges`, or the directory watch in `plugins/bar/Bar.qml`, when the state lives in a file the user can read.\n- A push from the command that changes the state. If only Omarchy commands change it, have them call `omarchy-shell -q refresh` after the change, the way `omarchy-reminder` and `omarchy-sudo-passwordless` do. When the change happens later, without a command running (an expiry, say), schedule the refresh with a transient `systemd-run --user --on-active=…` timer. A root-owned timer cannot reach the user's shell.\n\nPolling is the last resort, kept for state with no change signal at all (a remote API, say). Then gate the timer on the panel being open where you can, pick the longest interval the UI can tolerate, and put the poll in one shared service rather than in a per-monitor widget. Never poll a privileged probe: every `sudo -n` can write to the auth log.\n\n## Editing widget files with glyphs\n\nWidget files in `shell/plugins/bar/widgets/` contain Nerd Font glyphs as raw\nunicode characters. Agent file-editing tools can strip multi-byte codepoints\nin some positions — do **not** rewrite widget files wholesale through those\ntools. For glyph fixes, make a targeted edit with the surrounding context, or\nuse a Python script that inserts codepoints via `chr(0xXXXXX)`.\n\n## Palette references\n\nImport `qs.Commons as Commons` and use `Commons.Color` for the palette singleton, including `Connections.target`. Qt 6.12 introduces a `Color` type in `QtQuick` that shadows unqualified palette references. This applies to first-party components and third-party plugin QML alike. Keep the unqualified `qs.Commons` import when the file also uses `Style`, `Util`, or `Border`.\n","agents/skills/install-scripts.md":"# Install Scripts\n\nRead this before working under `install/` or on the system/user setup commands.\n\nThe ISO owns installation orchestration. This repo ships target-side setup\ncommands and reusable setup leaves:\n\n- `bin/omarchy-apply-system` runs root-owned system setup during ISO finalization.\n- `bin/omarchy-apply-hardware` runs idempotent hardware-specific setup and is called by `omarchy-apply-system`.\n- `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`.\n- leaf scripts under `install/` are sourced by `run_logged $OMARCHY_INSTALL/path/to/script.sh` and intentionally do not have shebangs.\n- avoid `exit` in sourced setup scripts unless intentionally aborting setup.\n- use `$OMARCHY_INSTALL` and `$OMARCHY_PATH` instead of hard-coded Omarchy paths.\n- keep root-scoped hardware setup under `install/hardware/` and orchestrate it through `install/hardware/all.sh`.\n- in an image build every `run_logged` leaf in `install/hardware/all.sh` is queued and runs on the machine's first boot instead (`bin/omarchy-provision-hardware`, see `docs/file-layout.md`), possibly offline, using packages already in the image, and before any user exists; keep those leaves idempotent and put nothing but `run_logged` lines in `all.sh`.\n- gate platform-specific setup on a predicate built on `omarchy-hw-platform` (`omarchy-hw-aarch64-apple`), not on `uname -m`; architecture checks (`omarchy-hw-x86`, `omarchy-hw-aarch64`) are only for ABI, binary availability or a repository's `$arch`. Platform names and where platform code lives are in the Platforms section of `AGENTS.md`.\n- 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.\n- The base install supplies matching kernel headers before hardware setup. DKMS installers should install their driver packages and assume the headers exist.\n- prefer helper commands for package and command checks where available.\n\nRaw `command -v`, `pacman`, and `pacman-key` are acceptable in package-helper\ncontexts where direct package-manager behavior is the point of the script.\n","agents/skills/command-metadata.md":"# Command Metadata\n\nRead this before adding or changing commands in `bin/`.\n\nCommands in `bin/` can declare CLI metadata in comments near the top of the\nfile. `bin/omarchy` scans the first 80 lines, and tests expect command metadata\nto remain valid.\n\nSupported metadata keys:\n\n- `# omarchy:group=...` - override the command group inferred from the filename\n- `# omarchy:name=...` - override the command name inferred from the filename\n- `# omarchy:summary=...` - short help text\n- `# omarchy:args=...` - usage arguments\n- `# omarchy:examples=...` - examples separated with ` | `\n- `# omarchy:alias=...` / `# omarchy:aliases=...` - alternate routes\n- `# omarchy:hidden=true` - hide from default command listings\n- `# omarchy:requires-sudo=true` - mark commands that require sudo\n\nOnly use `omarchy:examples` where there are args that need explaining.\n\nPrefer explicit metadata for user-facing commands. Keep routes consistent with\nthe filename unless there is a deliberate alias or compatibility route.\n\nExample:\n\n```bash\n# omarchy:summary=Take a screenshot\n# omarchy:args=[smart|region|windows|fullscreen] [slurp|copy]\n# omarchy:examples=omarchy screenshot | omarchy capture screenshot region\n```\n","agents/skills/icon-font.md":"# Omarchy Icon Font\n\nRead this before adding a branded glyph to `default/fonts/omarchy/omarchy.ttf`.\n\nThe Omarchy icon font is a small private-use font carrying the marks Nerd\nFonts does not have: the Omarchy logo and the agent and app brand marks. The\nmenu draws one by naming the font on an entry:\n\n```jsonc\n\"setup.default.agent.grok\": {\"icon\":\"\",\"iconFont\":\"omarchy\",\"label\":\"Grok\", ...}\n```\n\nWithout `iconFont`, an entry's `icon` is drawn in the menu font, so reach for\nthis font only when a Nerd Font glyph would misrepresent the thing. A generic\nrobot for four different AI apps is the case that justifies a real mark; a\nfolder or a microphone is not.\n\n`default/fonts/omarchy/README.md` lists every glyph with the URL its artwork\ncame from. Keep that list accurate — it is the only record of provenance.\n\n## Adding a glyph\n\n`omarchy dev font` does the work:\n\n```bash\nomarchy dev font list\nomarchy dev font add ollama https://simpleicons.org/icons/ollama.svg\n```\n\n`add` fetches the SVG, scales it into the same 64..960 box the existing marks\nuse so it lands at their optical size, appends it at the next free private-use\ncodepoint, and adds a line to the font README. It prints the codepoint and the\nglyph itself.\n\nThe source must be a **monochrome SVG with a single ``**, because the\nmenu recolors the glyph with the active theme's foreground and selection\ncolors. Brand icon sets such as publish exactly that\nshape. App favicons usually do not: they are multi-color, carry a container\ntile, or split across several paths. Prefer the official mark when it is\npublished as flat monochrome art, and fall back to an icon set's redraw when it\nis not.\n\nTwo-tone marks are a trap. Every path becomes solid foreground, so a logo whose\nmeaning depends on lighter and darker halves turns into an unreadable blob.\nPick a source whose silhouette alone reads.\n\n## After adding\n\nThe command prints these, and all of them matter:\n\n- Point the menu entry at the new codepoint with `\"iconFont\":\"omarchy\"`.\n- Bump the charset range asserted in `test/shell.d/menu-test.sh`; that test\n pins the font's coverage and fails until it matches.\n- Check the README line the command added, and give it a proper display name\n with `--label` if the glyph name is not the brand's name.\n\nThe font is package-owned: `omarchy-settings` installs it to\n`/usr/share/fonts/omarchy/omarchy.ttf`, so a new glyph reaches the desktop\nthrough a settings release, not through `omarchy update`. Between the merge and\nthat release, a pulled checkout renders the new entry with no icon.\n\n## Verifying\n\nRender the whole font and look at it, which catches inverted contours and\nfilled counters that a glyph list cannot show:\n\n```bash\npython3 -c \"open('/tmp/row.txt','w').write(' '.join(chr(c) for c in range(0xE900, 0xE910)))\"\nmagick -background white -fill black -font default/fonts/omarchy/omarchy.ttf \\\n -pointsize 110 label:@/tmp/row.txt /tmp/font-row.png\n```\n\nThen confirm it in the running menu per [`visual-verification.md`](visual-verification.md). Avoid leaving two fonts with the `omarchy` family registered: Qt can use an old copy in `~/.local/share/fonts` even when `fc-match omarchy` reports the packaged font. For a preview, either replace the packaged file in the disposable VM or temporarily exclude it with a `` rule in `~/.config/fontconfig/conf.d/` before loading the candidate.\n\nRefresh the font cache and restart the shell afterwards — Qt reads the font database at startup, so `omarchy menu refresh` alone will not pick up a changed font. Remove temporary fonts and rules after verification.\n","default/agents/skills/omarchy-app/SKILL.md":"---\nname: omarchy-app\ndescription: >\n Build a new desktop app for Omarchy the way Omarchy's own apps are built\n (Hype, Monologue, Omacut): C++ and Qt Quick, compiled with qmake6 and make\n into a single binary, following the Omarchy theme live, and installed as an\n Arch package so it shows up in the app launcher. Use when asked to make,\n build, or scaffold an app, tool, utility, or GUI program for the desktop.\n Triggers: new app, make me an app, desktop app, GUI, Qt, QML, Qt Quick, C++\n app, qmake, app launcher entry, PKGBUILD for my app.\n---\n\n# Building an Omarchy App\n\nOmarchy's own apps are dead simple on purpose: one window, one job, driven\nfrom the keyboard, following the desktop theme, and installed like any other\npackage. Build new ones the same way. `templates.md` has the starter files;\nthe published apps are the reference for anything bigger:\n\n- Omacut, a video trimmer: https://github.com/omacom-io/omacut\n- Monologue, a webcam recorder: https://github.com/omacom/monologue\n- Hype, Markdown presentations: https://github.com/omacom/hype\n- Signed, PDF signing: https://github.com/omacom/signed\n\n## Before writing code\n\nAsk what the app should do if it isn't clear, and settle the one job it does.\nPick a short lowercase name (`tally`, `pomo`); it is the binary, the package,\nthe `.desktop` file, the icon, and the Wayland app id all at once. Create the\nproject in `~/Work/` unless the user says otherwise, and `git init` it.\n\nEverything an app needs is part of Omarchy: `qmake6`, `make`, a C++\ncompiler, Qt's base, declarative, multimedia, SVG, and Wayland modules, and\n`ffmpeg`. If `qmake6` is missing, install the set with `omarchy-pkg-add\nbase-devel qt6-base qt6-declarative qt6-multimedia qt6-svg qt6-wayland ffmpeg`.\n\n## Shape\n\n```text\n.pro qmake project: Qt modules, sources, resources\nbin/build qmake6 + make into build/\nbin/test builds and runs the Qt Test binary offscreen\nbin/install makepkg -fsi, so the app lands in the launcher\nsrc/main.cpp app setup; hands C++ objects to QML\nsrc/backend.{h,cpp} the app's state and work, as a QObject\nsrc/theme.{h,cpp} follows the Omarchy accent and Hyprland's rounding\nsrc/Main.qml the window: layout, keys, nothing else\nsrc/resources.qrc compiles the QML into the binary\ntests/_tests.{pro,cpp}\npkgbuild/PKGBUILD pkgbuild/.desktop pkgbuild/.svg\nREADME.md LICENSE .gitignore\n```\n\n`src/` stays flat. No CMake, no build directories checked in, no generated\nfiles committed.\n\n## How the pieces split\n\n- **C++ owns the logic**: state, files, processes, anything that can fail.\n Expose it as a `QObject` with `Q_PROPERTY … NOTIFY` for state and\n `Q_INVOKABLE` for actions, handed to QML with\n `engine.rootContext()->setContextProperty(\"backend\", &backend)`.\n- **QML owns layout and interaction**: an `ApplicationWindow` in `Main.qml`,\n a few components beside it, and every key binding as a `Shortcut` with\n `context: Qt.ApplicationShortcut`.\n- Use `QGuiApplication`, not `QApplication`. Call\n `app.setDesktopFileName(\"\")` so the compositor and launcher match the\n window to its `.desktop` file and icon.\n- Use the Material style with `Material.theme: Material.Dark` and the theme\n accent as `Material.accent`, on a dark window color.\n- Heavy media work goes through the `ffmpeg`/`ffprobe` command-line tools via\n `QProcess`, not by linking libav.\n- Open and save dialogs go through xdg-desktop-portal over D-Bus\n (`org.freedesktop.portal.FileChooser`), never `QFileDialog`. Omacut's\n `src/portalfilepicker.{h,cpp}` behind an abstract `src/filepicker.h` is the\n pattern to copy, with its attribution, and lets tests inject a fake picker.\n\n## Omarchy conventions\n\n- **Follow the theme live.** Read `accent` from\n `~/.local/state/omarchy/current/theme/colors.toml` and watch it; a theme\n switch replaces files and symlinks, so re-arm the watcher on every change.\n Fall back to `#FFD60A` when Omarchy isn't there. `templates.md` has the\n `Theme` class. Never change Omarchy's config.\n- **Speak the user's language.** Omarchy runs in 50 languages, and the app\n follows the one picked under Setup > Language, live, like the theme. Write\n every visible string as `qsTr(\"Save\")` in QML or `tr(\"Save\")` in C++, with\n `%1` placeholders filled by `.arg()` rather than sentences glued together,\n and a counted string as `qsTr(\"%n clips\", \"\", count)` so each language gets\n its own plural forms. Ship translations as `src/i18n/.json` (English\n text to translation) compiled into the binary. The `Translator` in\n `templates.md` reads `~/.config/omarchy/language`, falls back from `pt-BR`\n to `pt` to English per string, and sets the default `QLocale` and layout\n direction from Omarchy's registry: write numbers and dates through\n `Qt.locale()` (`value.toLocaleString(Qt.locale(), 'f', 1)`) so they take\n the language's separators and digits, and keep the window's content under\n the template's mirrored root so Arabic, Hebrew, Persian, and Urdu read\n right to left. A binding that formats a date or number should read\n `translator.language` so it re-renders on a switch. Translate the\n `.desktop` file's `Name` and `Comment` too (`Name[da]=…`). Keep brand\n names, units, and keyboard keys as they are.\n- **Corners match the windows.** Hyprland's `decoration:rounding` is 0 on\n Omarchy's default, so corners are sharp unless the theme or the user rounds\n windows. The template `Theme` asks `hyprctl` for the effective value and\n exposes it as `theme.radius`; use it for every panel, dialog, and button,\n set `Material.roundedScale: theme.radius` on the window and on Material\n controls in other files, and cap small elements with\n `Math.min(4, theme.radius)`. Only true circles keep a fixed radius.\n- **Place things where the pointer is.** Anything the user inserts lands\n under the mouse when it's over the content (a `HoverHandler` tracks it),\n and in the middle of what's visible otherwise. Never at a fixed corner.\n- **Keyboard first.** `?` shows every shortcut in an overlay, `Q` quits (and\n asks first when there's unsaved or unexported work), Space is the main\n action, Ctrl+Z / Ctrl+Shift+Z undo and redo. The README lists the shortcuts\n in a table.\n- **Careful with data.** Never modify the user's originals. Save atomically\n (write beside the target, then rename). Ask before discarding work.\n- **Say what's wrong.** A missing tool, device, or permission is reported in\n the window, never worked around by quietly doing less.\n- **Agents can drive it.** If the app makes or changes files, give it\n commands that need no display, as Hype does (`hype check`, `hype render`,\n `hype export`): each takes `--json`, exits 0 or 1 with errors on stderr, and\n ` skill install` installs a short agent skill bundled in the binary.\n Set `QT_QPA_PLATFORM=offscreen` before `QGuiApplication` for those commands,\n and keep the GUI behind ` open`. Hype's `src/cli.cpp` is the pattern.\n- Comments explain why, in full sentences. Commit messages are short and\n imperative (\"Trim from the keyboard\").\n\n## Loop\n\n1. `bin/build`, then run `build/` to try it. Pass a file argument if\n the app opens files, so it's quick to test.\n2. `bin/test` after each change to the backend. Tests compile `../src/*.cpp`\n straight in, run offscreen, and pass temp directories to anything that\n reads the disk (the `Theme` takes the theme directory as an argument).\n3. Look at it. Take a screenshot with `omarchy capture screenshot fullscreen\n save` and check the window against the theme before calling it done.\n Switch the language once (`omarchy language da`) and look again: longer\n words must not clip, and nothing should still be in English.\n4. Drive the real QML offscreen when a change is about interaction. A small\n harness in the scratchpad that loads `qrc:/Main.qml` with\n `QT_QPA_PLATFORM=offscreen`, sends mouse and key events, and saves\n `window->grabWindow()` shows what the user would see without touching\n their desktop. Set `QT_FORCE_STDERR_LOGGING=1`, or QML warnings go to the\n journal instead of the terminal.\n5. `bin/install` builds the package with `makepkg -fsi`, which installs the\n binary, the `.desktop` entry, and the icon. The app then appears in the\n Omarchy app launcher (`Super + Space`). Run it again after every change\n the user should see there.\n\n## Qt Quick traps\n\n- Don't name a component file after a Qt Quick type: `ItemView.qml` fails\n with \"abstract base class\". Prefix it with what it shows (`PlacedItem.qml`).\n- A `MouseArea` inside a `ListView` or `Flickable` loses its drag after a few\n pixels unless it sets `preventStealing: true`.\n- `ListView` pins delegates to `x: 0`. To center content, make the delegate a\n full-width `Item` and center the content inside it.\n- Every file that sets a `Material.*` attached property must import\n `QtQuick.Controls.Material`, or the file fails to load.\n- A Material `TextField` floats its `placeholderText` as the label. Don't add\n a separate label above it, or the two overlap.\n- `font.pixelSize` is an int. Standard keys go in `sequences:\n [StandardKey.Undo]`, not `sequence:`.\n- Text that must look the same on screen and in an exported file is measured\n and painted by one C++ function, used by a `QQuickPaintedItem` on screen and\n by the exporter, rather than laid out twice.\n\n## README and release\n\n- The README opens with a screenshot of the app doing its job. Grab it from\n the offscreen harness, with the default accent so it doesn't depend on the\n current theme, and with made-up content: never the user's name, signature,\n files, or other personal data.\n- To ship: tag `v` and make a GitHub release, then add the package to\n `omacom/omarchy-pkgs` under `pkgbuilds//` building from the release\n tarball, with `.omarchy/package.json` set to `\"source\": \"local\"`,\n `\"auto_merge\": true`, and an `upstream.watch` on the GitHub repo so later\n releases sync on their own. Only once that package is published can\n Omarchy install it: `install/omarchy-base.packages`, the preinstall\n scripts, and a migration for existing machines.\n","default/agents/skills/diagnose-crash/SKILL.md":"---\nname: diagnose-crash\ndescription: >\n Diagnose why a program crashed on this machine, from a systemd-coredump core dump.\n Use when a process has segfaulted, aborted, or otherwise dumped core, when asked\n why an application crashed or disappeared, or when a \"Process crashed:\" desktop\n notification is acted on. Triggers: crash, segfault, SIGSEGV, SIGABRT, core dump,\n coredumpctl, \"why did X crash\", \"X keeps crashing\", backtrace symbolization.\n Covers reporting a confirmed Omarchy bug upstream — see reporting.md.\n---\n\n# Diagnosing a Crash\n\nWork from evidence. The goal is an honest account of what happened, not a\nplausible-sounding story.\n\n## Establish the facts\n\n`coredumpctl info ` is the starting point. Beyond the backtrace, note the\n**command line** the process was started with — it usually reveals what the\nprogram was working on when it died, which is often the whole answer.\n\n`coredumpctl list` shows whether this crash is a one-off or a pattern. Repeated\ncrashes of the same program, or several programs dying together, point somewhere\ndifferent than a single failure does.\n\n## Rule out the boring causes first\n\nCheck resource exhaustion before blaming the program: `free -h`, and the journal\nfor OOM kills. A process killed by the OOM killer is not a bug in that process.\n\n## Correlate against the timeline\n\nThe crash timestamp is the most underused piece of evidence. Compare it against:\n\n- **Filesystem mtimes.** A directory or file whose mtime lands on the same second\n as the crash strongly suggests what triggered it.\n- **The journal** around that moment, for related warnings from the same or\n neighbouring processes.\n- **Recent package updates.** A crash that starts right after an update points at\n the update.\n\n## Read the whole core, not just frame 0\n\nThread stacks other than the crashing one show what work was **in flight** —\nthumbnailers, image loaders, IPC readers, GPU queues. That context often explains\nthe trigger even when the crashing frame itself cannot be symbolized.\n\nNote any third-party code in the address space: file-manager or browser\nextensions, plugins, out-of-tree drivers. In-process third-party code is a common\ncrash source and worth flagging — but do not pin blame on it without evidence\nthat it is actually implicated.\n\n## Symbolize when you can\n\nThis is Arch, which runs a public debuginfod server:\n\n```bash\ncore=$(mktemp -t crash-XXXXXX.core)\ntrap 'rm -f \"$core\"' EXIT\ncoredumpctl dump --output=\"$core\"\nDEBUGINFOD_URLS=\"https://debuginfod.archlinux.org\" \\\n gdb -q \"$core\" \\\n -batch -ex 'set debuginfod enabled on' -ex 'bt'\n```\n\nA core is a verbatim copy of the process's memory and can hold passwords, tokens,\nand private documents. Write it to a fresh `mktemp` path rather than a predictable\nshared one, and delete it when you are done — never leave it lying in `/tmp`.\n\nMany packages publish no debug symbols. When frames stay unresolved, say so —\nnever invent function names to fill the gap. An unsymbolized stack still has\nshape: which library each frame belongs to, and whether the crash came from a\nsignal handler, a main loop, or a worker thread.\n\n## Report\n\n1. What crashed, and what it was doing at the time.\n2. The most likely mechanism — separating clearly what the evidence **proves**\n from what you are **inferring**.\n3. Whether any user data was lost, and where it can be recovered from. Check the\n trash before concluding anything is gone.\n4. Whether it is likely to recur, and what would avoid or fix it.\n\nBe straight about the limits of the evidence. If the cause is genuinely\nambiguous, say so rather than assembling confidence out of guesswork.\n\n**Leave the system as you found it.** Diagnosis reads; it does not fix, tidy, or\nreconfigure. The one thing to clean up is your own: delete the core you extracted\nabove, which is a copy of the crashed process's memory. The single change a\ndiagnosis may make is the mute below, and only when the user asks for it.\n\n## Offer to stop the notifications for this program\n\nA crash you have explained often keeps happening anyway. Finish by offering to\nsilence notifications for **that one program**, and never run it unprompted. Say\nhow to lift it in the same breath, so it is not a one-way door.\n\n```bash\nomarchy-crash-mute '' # silence it\nomarchy-crash-mute '' off # let it speak again\nomarchy-crash-mute # list what is muted\n```\n\nPass the `binary:` path from the crash facts, or the `process:` name where no\nbinary was recorded; the command reduces either to the name the watcher keys on.\nA diagnosis run by hand from `omarchy agent crash ` has neither, so take\nthem from `coredumpctl info`. Prefer the binary: a process name is truncated to\n15 characters and a basename is not, so muting the truncated form matches\nnothing, forever, while looking like it worked.\n\nQuote it. The name is whatever the crashed program's author called a file, and a\nsingle quote inside one closes yours and runs the rest as your shell.\n\nThe key is a bare name, so anything run through an interpreter is keyed as the\ninterpreter: muting `python3.13` silences every Python program on the machine.\nSay so rather than quietly doing it.\n\nNone of this fixes anything, and a mute offered in place of a fix that was within\nreach is the wrong answer. For every program rather than one, the switch is\n_Trigger > Toggle > Crash Capture_.\n\n## If it is an Omarchy bug\n\nMost application crashes are upstream bugs in those applications, not Omarchy's\ndoing. In the minority of cases where the cause really does sit within Omarchy's\nsphere of control, read [`reporting.md`](reporting.md) before offering to file\nanything.\n","default/agents/skills/omarchy/SKILL.md":"---\nname: omarchy\ndescription: >\n REQUIRED for end-user customization of Linux desktop, window manager, or system config.\n Use when editing ANY file in ~/.config/, ~/.config/hypr/, ~/.config/omarchy/,\n ~/.config/alacritty/, ~/.config/foot/, ~/.config/kitty/, or ~/.config/ghostty/.\n Triggers: Hyprland, window rules, window behavior, animations, keybindings, monitors, gaps, borders,\n blur, opacity, omarchy-shell, bar, widgets, terminal config, themes, fonts, background,\n night light, idle, lock screen, screenshots, screen recording, reminders, layer rules, workspace\n settings, display config, appearance changes, and user-facing omarchy commands. Excludes Omarchy\n source development through `omarchy dev link` workflows.\n---\n\n# Omarchy Skill\n\nManage [Omarchy](https://omarchy.org/) Linux systems - a beautiful, fun, agentic Arch Linux distribution with Hyprland.\n\nThis skill is for end-user customization on installed systems.\nIt is not for contributing to Omarchy source code.\n\n## Topic Guides\n\nDeeper instructions for common areas live next to this file. Read the\nmatching guide before starting:\n\n- [`hyprland.md`](hyprland.md) - keybindings, monitors, window rules, and other Hyprland config\n- [`plugins.md`](plugins.md) - the Omarchy shell: bar layout, widgets, plugins, idle behavior\n- [`theming.md`](theming.md) - themes, backgrounds, and fonts\n- [`hooks.md`](hooks.md) - automation hooks that run on system events\n- [`capture.md`](capture.md) - screenshots, screen recordings, OCR text capture, and file sharing\n- [`contributing.md`](contributing.md) - reporting Omarchy bugs and submitting fixes upstream\n\n## Critical Safety Rules\n\nFor privileged commands, follow the Privilege Escalation rules below: `sudo` when a terminal is available for the password prompt, `pkexec` when it is not. Do not wrap commands that already manage privilege elevation themselves.\n\n**For end-user customization tasks, NEVER modify anything in `/usr/share/omarchy/`** - but READING is safe and encouraged.\n\nThis directory is owned by the omarchy package. Any local changes will be\noverwritten on the next `omarchy update`.\n\n```\n/usr/share/omarchy/ # READ-ONLY - NEVER EDIT (reading is OK)\n├── bin/ # Command source (packaged binaries are on PATH)\n├── config/ # Default config templates\n├── themes/ # Stock themes\n├── default/ # System defaults\n├── shell/ # Omarchy shell source and defaults\n├── migrations/ # Update migrations\n└── install/ # Installation scripts\n```\n\n**Reading `/usr/share/omarchy/` is SAFE and useful** - do it freely to:\n- Understand how omarchy commands work: `omarchy theme set --help` or `cat $(which omarchy-theme-set)`\n- See default configs before customizing: `cat \"$OMARCHY_PATH/config/omarchy/shell.json\"`\n- Check stock theme files to copy for customization\n- Reference default hyprland settings: `cat /usr/share/omarchy/default/hypr/*`\n\n**Always use these safe locations instead:**\n- `~/.config/` - User configuration (safe to edit)\n- `~/.config/omarchy/themes//` - Custom themes\n- `~/.config/omarchy/hooks/` - Custom automation hooks\n\nIf the request is to develop Omarchy itself, this skill is out of scope. Follow repository development instructions instead of this skill.\n\n## Privilege Escalation\n\nFor an interactive script or command run in a visible terminal, use `sudo` for\nprivileged work. Omarchy may grant passwordless `sudo` access to particular\ncommands, and the terminal is the appropriate place to request a password\nwhen one is needed.\n\nUse `pkexec` only when the caller cannot interact with a terminal or cannot\nenter a password there, such as a command launched by an agent or a graphical\nbackground process. Do not replace `sudo` with `pkexec` merely because a\ncommand changes system state.\n\n## System Architecture\n\nOmarchy is built on:\n\n| Component | Purpose | Config Location |\n|-----------|---------|-----------------|\n| **Arch Linux** | Base OS | `/etc/`, `~/.config/` |\n| **Hyprland** | Wayland compositor/WM | `~/.config/hypr/` |\n| **Omarchy shell** | Status bar + notifications (Quickshell) | `~/.config/omarchy/shell.json` |\n| **Launcher/menus** | Quickshell menu | `~/.config/omarchy/extensions/omarchy-menu.jsonc` |\n| **Alacritty/Foot/Kitty/Ghostty** | Terminals | `~/.config//` |\n| **Omarchy OSD** | On-screen display | Quickshell plugin |\n\n## Command Discovery\n\nOmarchy ships a single `omarchy` CLI that dispatches to all `omarchy-*` binaries via `omarchy `. Always prefer this form — it is self-documenting and stable. The underlying `omarchy-*` binaries still exist on `PATH` and remain safe to read for source.\n\n```bash\n# List every documented command and its summary (--all includes hidden commands)\nomarchy commands\n\n# Show the commands inside a group\nomarchy theme --help\nomarchy refresh --help\nomarchy restart --help\n\n# Show help for a specific command (does not execute it)\nomarchy theme set --help\n\n# Machine-readable listing (binary, route, summary, args, aliases)\nomarchy commands --json\n\n# Read a command's source to understand it\ncat $(which omarchy-theme-set)\n```\n\n### Command Groups\n\nRun `omarchy --help` for the full list. The most common groups:\n\n| Group | Purpose | Example |\n|-------|---------|---------|\n| `omarchy refresh` | Reset config to defaults (backs up first) | `omarchy refresh shell` |\n| `omarchy restart` | Restart a service/app | `omarchy restart shell` |\n| `omarchy toggle` | Toggle feature on/off | `omarchy toggle nightlight` |\n| `omarchy theme` | Theme management | `omarchy theme set ` |\n| `omarchy bar` | Bar layout and widgets | `omarchy bar move omarchy.clock --section right` |\n| `omarchy plugin` | Manage/clone shell plugins | `omarchy plugin clone omarchy.clock` |\n| `omarchy hook` | Install automation hooks | `omarchy hook install theme-set