From 6ee243cc3740563bf8a19dd249db2a9304eedd43 Mon Sep 17 00:00:00 2001
From: David Heinemeier Hansson <david@hey.com>
Date: Fri, 7 Aug 2026 14:36:42 +0200
Subject: [PATCH] Split the end-user omarchy skill into topic guides (#6602)

* Split the end-user omarchy skill into topic guides

Move default/omarchy-skill to default/agents/skills/omarchy and break the
monolithic SKILL.md into on-demand topic files for Hyprland config, shell
plugins, theming, and hooks. Update the skill symlink wiring, relink
existing installs through a migration, and correct claims that had drifted
from the implementation: plugin hot-reload, terminal reload, menu
customization, refresh scopes, theme overlays, background locations, hook
timing, and the packaged (not git-managed) system directory.

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

* Add capture and contributing guides to the omarchy skill

Cover screenshots, screen recording, OCR text capture, and LocalSend or
Taildrop sharing, plus how to route bug reports, suggestions, and support
questions upstream with diagnostics and captures of the problem attached.

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

* Scope Hyprland reload guidance to the Lua config files

hyprsunset.conf and xdph.conf are read by separate processes, so hyprctl
neither applies nor validates them. Document restarting hyprsunset after
editing its config, including in the night light example.

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

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 AGENTS.md                                     |   2 +-
 bin/omarchy-finalize-user                     |   8 +-
 bin/omarchy-upgrade-to-quattro                |  10 +-
 .../skills/omarchy}/SKILL.md                  | 202 ++++--------------
 default/agents/skills/omarchy/capture.md      |  60 ++++++
 default/agents/skills/omarchy/contributing.md |  65 ++++++
 default/agents/skills/omarchy/hooks.md        |  28 +++
 default/agents/skills/omarchy/hyprland.md     |  78 +++++++
 default/agents/skills/omarchy/plugins.md      |  52 +++++
 default/agents/skills/omarchy/theming.md      |  56 +++++
 docs/file-layout.md                           |   2 +-
 migrations/1786098807.sh                      |   7 +
 12 files changed, 393 insertions(+), 177 deletions(-)
 rename default/{omarchy-skill => agents/skills/omarchy}/SKILL.md (59%)
 create mode 100644 default/agents/skills/omarchy/capture.md
 create mode 100644 default/agents/skills/omarchy/contributing.md
 create mode 100644 default/agents/skills/omarchy/hooks.md
 create mode 100644 default/agents/skills/omarchy/hyprland.md
 create mode 100644 default/agents/skills/omarchy/plugins.md
 create mode 100644 default/agents/skills/omarchy/theming.md
 create mode 100644 migrations/1786098807.sh

diff --git a/AGENTS.md b/AGENTS.md
index 6cfad12d..9bb571df 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -52,7 +52,7 @@ guidance does not drift from the router.
 
 # Privileged Commands
 
-- Follow the "Privilege Escalation" section of `default/omarchy-skill/SKILL.md`. It draws the
+- 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.
 
diff --git a/bin/omarchy-finalize-user b/bin/omarchy-finalize-user
index 41d7a9ae..81db68d4 100755
--- a/bin/omarchy-finalize-user
+++ b/bin/omarchy-finalize-user
@@ -83,10 +83,10 @@ fi
 # Dev-aware skill symlinks. Cannot live in /etc/skel because OMARCHY_PATH may
 # point at a dev checkout (omarchy dev link) where the target differs.
 mkdir -p ~/.agents/skills ~/.claude/skills ~/.codex/skills ~/.pi/agent/skills
-ln -sfn "$OMARCHY_PATH/default/omarchy-skill" ~/.agents/skills/omarchy
-ln -sfn "$OMARCHY_PATH/default/omarchy-skill" ~/.claude/skills/omarchy
-ln -sfn "$OMARCHY_PATH/default/omarchy-skill" ~/.codex/skills/omarchy
-ln -sfn "$OMARCHY_PATH/default/omarchy-skill" ~/.pi/agent/skills/omarchy
+ln -sfn "$OMARCHY_PATH/default/agents/skills/omarchy" ~/.agents/skills/omarchy
+ln -sfn "$OMARCHY_PATH/default/agents/skills/omarchy" ~/.claude/skills/omarchy
+ln -sfn "$OMARCHY_PATH/default/agents/skills/omarchy" ~/.codex/skills/omarchy
+ln -sfn "$OMARCHY_PATH/default/agents/skills/omarchy" ~/.pi/agent/skills/omarchy
 
 mkdir -p ~/Downloads ~/Pictures ~/Videos ~/.config/gtk-3.0
 xdg-user-dirs-update --set TEMPLATES "$HOME"
diff --git a/bin/omarchy-upgrade-to-quattro b/bin/omarchy-upgrade-to-quattro
index 00083d33..97aea8e2 100755
--- a/bin/omarchy-upgrade-to-quattro
+++ b/bin/omarchy-upgrade-to-quattro
@@ -1877,11 +1877,11 @@ repair_sleep_lock_unit_override
 install_bash_startup
 
 mkdir -p "$HOME/.agents/skills" "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.pi/agent/skills"
-if [[ -d $root/default/omarchy-skill ]]; then
-  ln -sfn "$root/default/omarchy-skill" "$HOME/.agents/skills/omarchy"
-  ln -sfn "$root/default/omarchy-skill" "$HOME/.claude/skills/omarchy"
-  ln -sfn "$root/default/omarchy-skill" "$HOME/.codex/skills/omarchy"
-  ln -sfn "$root/default/omarchy-skill" "$HOME/.pi/agent/skills/omarchy"
+if [[ -d $root/default/agents/skills/omarchy ]]; then
+  ln -sfn "$root/default/agents/skills/omarchy" "$HOME/.agents/skills/omarchy"
+  ln -sfn "$root/default/agents/skills/omarchy" "$HOME/.claude/skills/omarchy"
+  ln -sfn "$root/default/agents/skills/omarchy" "$HOME/.codex/skills/omarchy"
+  ln -sfn "$root/default/agents/skills/omarchy" "$HOME/.pi/agent/skills/omarchy"
 fi
 
 mkdir -p "$HOME/.local/state/omarchy/toggles/hypr"
diff --git a/default/omarchy-skill/SKILL.md b/default/agents/skills/omarchy/SKILL.md
similarity index 59%
rename from default/omarchy-skill/SKILL.md
rename to default/agents/skills/omarchy/SKILL.md
index 8cb227ae..1b00974a 100644
--- a/default/omarchy-skill/SKILL.md
+++ b/default/agents/skills/omarchy/SKILL.md
@@ -36,20 +36,30 @@ It is not for contributing to Omarchy source code.
 
 **Do NOT use this skill for Omarchy development tasks** (editing the Omarchy source tree, creating migrations, or running `omarchy dev ...` workflows).
 
+## Topic Guides
+
+Deeper instructions for common areas live next to this file. Read the
+matching guide before starting:
+
+- [`hyprland.md`](hyprland.md) - keybindings, monitors, window rules, and other Hyprland config
+- [`plugins.md`](plugins.md) - the Omarchy shell: bar layout, widgets, plugins, idle behavior
+- [`theming.md`](theming.md) - themes, backgrounds, and fonts
+- [`hooks.md`](hooks.md) - automation hooks that run on system events
+- [`capture.md`](capture.md) - screenshots, screen recordings, OCR text capture, and file sharing
+- [`contributing.md`](contributing.md) - reporting Omarchy bugs and submitting fixes upstream
+
 ## Critical Safety Rules
 
-When invoking a privileged command directly, use `pkexec` instead of `sudo` so Omarchy can show a graphical authorization prompt with command context. Do not wrap commands that already manage privilege elevation themselves.
+For 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.
 
 **For end-user customization tasks, NEVER modify anything in `/usr/share/omarchy/`** - but READING is safe and encouraged.
 
-This directory contains Omarchy's source files managed by git. Any changes will be:
-- Lost on next `omarchy update`
-- Cause conflicts with upstream
-- Break the system's update mechanism
+This directory is owned by the omarchy package. Any local changes will be
+overwritten on the next `omarchy update`.
 
 ```
 /usr/share/omarchy/     # READ-ONLY - NEVER EDIT (reading is OK)
-├── bin/                    # Source scripts (symlinked to PATH)
+├── bin/                    # Command source (packaged binaries are on PATH)
 ├── config/                 # Default config templates
 ├── themes/                 # Stock themes
 ├── default/                # System defaults
@@ -66,7 +76,7 @@ This directory contains Omarchy's source files managed by git. Any changes will
 
 **Always use these safe locations instead:**
 - `~/.config/` - User configuration (safe to edit)
-- `~/.config/omarchy/themes/<custom-name>/` - Custom themes (must be real directories)
+- `~/.config/omarchy/themes/<custom-name>/` - Custom themes
 - `~/.config/omarchy/hooks/` - Custom automation hooks
 
 If the request is to develop Omarchy itself, this skill is out of scope. Follow repository development instructions instead of this skill.
@@ -92,7 +102,7 @@ Omarchy is built on:
 | **Arch Linux** | Base OS | `/etc/`, `~/.config/` |
 | **Hyprland** | Wayland compositor/WM | `~/.config/hypr/` |
 | **Omarchy shell** | Status bar + notifications (Quickshell) | `~/.config/omarchy/shell.json` |
-| **Launcher** | Quickshell launcher | `~/.config/omarchy/shell.json` |
+| **Launcher/menus** | Quickshell menu | `~/.config/omarchy/extensions/omarchy-menu.jsonc` |
 | **Alacritty/Foot/Kitty/Ghostty** | Terminals | `~/.config/<terminal>/` |
 | **Omarchy OSD** | On-screen display | Quickshell plugin |
 
@@ -101,7 +111,7 @@ Omarchy is built on:
 Omarchy ships a single `omarchy` CLI that dispatches to all `omarchy-*` binaries via `omarchy <group> <action>`. 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.
 
 ```bash
-# List every documented command and its summary
+# List every documented command and its summary (--all includes hidden commands)
 omarchy commands
 
 # Show the commands inside a group
@@ -142,52 +152,9 @@ Run `omarchy --help` for the full list. The most common groups:
 
 ## Configuration Locations
 
-### Hyprland (Window Manager)
-
-Omarchy configures Hyprland in Lua. User files are loaded after Omarchy's
-defaults, so overrides go here:
-
-```
-~/.config/hypr/
-├── hyprland.lua       # Main config (loads Omarchy defaults, then user files)
-├── bindings.lua       # Keybindings
-├── monitors.lua       # Display configuration
-├── input.lua          # Keyboard/mouse settings
-├── looknfeel.lua      # Appearance (gaps, borders, animations)
-├── autostart.lua      # Startup applications
-└── hyprsunset.conf    # Night light / blue light filter
-```
-
-**Key behaviors:**
-- Hyprland auto-reloads on config save (no restart needed for most changes)
-- Use `hyprctl reload` to force reload
-- After ANY Hyprland config change, validate with `hyprctl reload` followed by `hyprctl configerrors`
-- If `hyprctl configerrors` reports errors, address them and rerun validation until clean or until a real blocker is identified
-- Use `omarchy refresh hyprland` to reset to defaults
-
-### Omarchy shell (Status Bar + Notifications)
-
-The bar, notification daemon, settings panel, and assorted overlays all run
-inside a single long-running Quickshell process (`omarchy-shell`).
-
-```
-~/.config/omarchy/shell.json             # User overrides: bar, plugins, idle
-~/.config/omarchy/plugins/<plugin-id>/   # User-owned shell plugins
-$OMARCHY_PATH/config/omarchy/shell.json  # Canonical defaults
-```
-
-The shell hot-reloads `shell.json` on save — no restart needed for layout
-changes. `idle.screensaver` and `idle.lock` are seconds since user idle began.
-
-To customize a built-in bar widget, never edit `$OMARCHY_PATH/shell/plugins/`.
-Clone it into the user plugin directory instead:
-
-```bash
-omarchy plugin clone omarchy.workspaces
-# Edit ~/.config/omarchy/plugins/<username>.workspaces/; saved changes reload automatically.
-```
-
-**Commands:** `omarchy restart shell`, `omarchy refresh shell`
+Hyprland config lives in `~/.config/hypr/` — see [`hyprland.md`](hyprland.md).
+The Omarchy shell (bar, notifications, plugins, idle) is configured in
+`~/.config/omarchy/shell.json` — see [`plugins.md`](plugins.md).
 
 ### Terminals
 
@@ -212,7 +179,7 @@ omarchy plugin clone omarchy.workspaces
 
 ## Safe Customization Patterns
 
-### Pattern 1: Edit User Config Directly
+### Edit User Config Directly
 
 For simple changes, edit files in `~/.config/`:
 
@@ -227,44 +194,12 @@ cp ~/.config/hypr/bindings.lua ~/.config/hypr/bindings.lua.bak.$(date +%s)
 
 # 4. Apply changes
 # - Hyprland: auto-reloads on save, but MUST validate with `hyprctl reload` and `hyprctl configerrors`
-# - Omarchy shell: shell.json hot-reloads; use `omarchy-shell shell rescanPlugins` for plugin/widget code changes
-# - Launcher: restart with `omarchy restart shell`
-# - Terminals: MUST restart with `omarchy restart terminal`
+# - Omarchy shell: shell.json and user plugin code under ~/.config/omarchy/plugins/ hot-reload on save
+# - Menus/launcher: ~/.config/omarchy/extensions/omarchy-menu.jsonc hot-reloads on save
+# - Terminals: apply with `omarchy restart terminal` (reloads running terminals; foot picks changes up in new windows)
 ```
 
-### Pattern 2: Make a new theme
-
-1. Create a directory under ~/.config/omarchy/themes.
-2. See how an existing theme is done via /usr/share/omarchy/themes/catppuccin.
-3. Download a matching background (or several) from the internet and put them in ~/.config/omarchy/themes/[name-of-new-theme]
-4. When done with the theme, run `omarchy theme set "Name of new theme"`
-
-### Pattern 3: Use Hooks for Automation
-
-Hooks live in `~/.config/omarchy/hooks/<name>.d/` — one directory per event,
-holding any number of independent scripts. Install with
-`omarchy hook install <name> <script>` (copies the script in and makes it
-executable):
-
-```
-~/.config/omarchy/hooks/
-├── battery-low.d/          # Low battery (percentage in $1)
-├── font-set.d/             # After font change (font name in $1)
-├── post-boot.d/            # After the desktop starts
-├── post-update.d/          # After `omarchy update`
-├── pre-refresh-pacman.d/   # Before package sync during update
-└── theme-set.d/            # After theme change (theme slug in $1)
-```
-
-Example hook script:
-```bash
-#!/bin/bash
-THEME_NAME=$1
-echo "Theme changed to: $THEME_NAME"
-# Add custom actions here
-```
-
-### Pattern 4: Reset to Defaults -- ALWAYS SEEK USER CONFIRMATION BEFORE RUNNING
+### Reset to Defaults -- ALWAYS SEEK USER CONFIRMATION BEFORE RUNNING
 
 When customizations go wrong:
 
@@ -276,77 +211,10 @@ omarchy refresh hyprland
 # The refresh command:
 # 1. Backs up current config with timestamp
 # 2. Copies default from $OMARCHY_PATH/config/
-# 3. Restarts the component
+# 3. Restarts the component where the refresh needs it (e.g. `refresh shell`)
 ```
 
-## Common Tasks
-
-### Themes
-
-```bash
-omarchy theme list              # Show available themes
-omarchy theme current           # Show current theme
-omarchy theme set <name>        # Apply theme ("Tokyo Night" and "tokyo-night" both work)
-omarchy theme bg next           # Cycle background
-omarchy theme install <url>     # Install from git repo
-```
-
-### Keybindings
-
-Edit `~/.config/hypr/bindings.lua`. Format:
-```lua
-o.bind("SUPER + SHIFT + R", "SSH", "alacritty -e ssh your-server")
-o.bind("SUPER + B", "Browser", { launch = "chromium" })  -- launch wraps with uwsm-app
-```
-
-View current bindings: `omarchy menu keybindings --print`
-
-**IMPORTANT: When re-binding an existing key:**
-
-1. First check existing bindings: `omarchy menu keybindings --print`
-2. If the key is already bound, you MUST call `hl.unbind(...)` BEFORE the new `o.bind(...)`
-3. Inform the user what the key was previously bound to
-
-Example - rebinding SUPER+F (which is bound to fullscreen by default):
-```lua
--- Unbind existing SUPER+F (was: fullscreen)
-hl.unbind("SUPER + F")
--- New binding for file manager
-o.bind("SUPER + F", "File manager", { launch = "nautilus" })
-```
-
-Always tell the user: "Note: SUPER+F was previously bound to fullscreen. I've added an unbind to override it."
-
-### Display/Monitors
-
-Edit `~/.config/hypr/monitors.lua`. Format:
-```lua
-hl.monitor({ output = "eDP-1", mode = "1920x1080@60", position = "0x0", scale = 1 })
-hl.monitor({ output = "HDMI-A-1", mode = "2560x1440@144", position = "1920x0", scale = 1 })
-```
-
-List monitors and supported modes: `hyprctl monitors all`
-
-### Window Rules
-
-**CRITICAL: Hyprland window rules syntax changes frequently between versions.**
-
-Before writing ANY window rules, you MUST fetch the current documentation from the official Hyprland wiki:
-- https://wiki.hypr.land/Configuring/Window-Rules/
-
-DO NOT rely on cached or memorized window rule syntax. The format has changed multiple times and using outdated syntax will cause errors or unexpected behavior.
-
-Window rules go in `~/.config/hypr/hyprland.lua` or a required Lua module. Prefer Omarchy's `o.window(match, rules)` helper — see examples in `$OMARCHY_PATH/default/hypr/windows.lua`.
-
-### Fonts
-
-```bash
-omarchy font list               # Available fonts
-omarchy font current            # Current font
-omarchy font set <name>         # Change font
-```
-
-### System
+## System Commands
 
 ```bash
 omarchy update                  # Full system update
@@ -383,10 +251,10 @@ When user requests system changes:
 
 1. **Is it a stock omarchy command?** Use it directly
 2. **Is it a config edit?** Edit in `~/.config/`, never `/usr/share/omarchy/`
-3. **Is it a theme customization?** Create a NEW custom theme directory
-4. **Is it automation?** Use `omarchy hook install` and the hook `.d` directories
+3. **Is it a theme customization?** Follow [`theming.md`](theming.md); create a NEW custom theme directory
+4. **Is it automation?** Follow [`hooks.md`](hooks.md); use `omarchy hook install` and the hook `.d` directories
 5. **Is it a package install?** Use `omarchy pkg add <pkgs...>` (or `omarchy pkg aur add <pkgs...>` for AUR-only packages)
-6. **Is it built-in shell/plugin code?** Clone it with `omarchy plugin clone`; never edit the packaged copy
+6. **Is it built-in shell/plugin code?** Follow [`plugins.md`](plugins.md); clone it with `omarchy plugin clone`, never edit the packaged copy
 7. **Unsure if command exists?** Run `omarchy commands` (or `omarchy <group> --help` for one group)
 
 ### Reminder Requests
@@ -413,12 +281,14 @@ This skill intentionally does not cover Omarchy source development. Do not use t
 - "Add a keybinding for Super+E to open file manager" -> Check existing bindings first, call `hl.unbind` if needed, then `o.bind` in `~/.config/hypr/bindings.lua`
 - "Configure my external monitor" -> Edit `~/.config/hypr/monitors.lua`
 - "Make the window gaps smaller" -> Edit `~/.config/hypr/looknfeel.lua`
-- "Set up night light to turn on at sunset" -> `omarchy toggle nightlight` or edit `~/.config/hypr/hyprsunset.conf`
+- "Turn on night light" -> `omarchy toggle nightlight` (for time-based schedules, edit `~/.config/hypr/hyprsunset.conf` profiles, then `omarchy restart hyprsunset`)
 - "Set a reminder to pickup jack in 15 minutes" -> `omarchy reminder 15 "Pickup Jack"`
 - "Show my reminders" -> `omarchy reminder show`
 - "Clear all reminders" -> `omarchy reminder clear`
-- "Customize the catppuccin theme colors" -> Create `~/.config/omarchy/themes/catppuccin-custom/` by copying from stock, then edit
+- "Customize the catppuccin theme colors" -> Overlay: put an edited `colors.toml` in `~/.config/omarchy/themes/catppuccin/`, then re-apply the theme (see `theming.md`)
 - "Run a script every time I change themes" -> Install it with `omarchy hook install theme-set <script>`
 - "Change how workspace labels are rendered" -> Clone `omarchy.workspaces`, which switches the bar to `<username>.workspaces`, then edit the clone
 - "Lock after ten minutes" -> Set `idle.lock` to `600` in `~/.config/omarchy/shell.json`
 - "Reset shell/bar to defaults" -> `omarchy refresh shell`
+- "Record my screen" -> `omarchy screenrecord --fullscreen`, then `omarchy screenrecord --stop-recording` (see `capture.md`)
+- "Report this bug to Omarchy" -> Gather diagnostics and a capture of the problem, then file it (see `contributing.md`)
diff --git a/default/agents/skills/omarchy/capture.md b/default/agents/skills/omarchy/capture.md
new file mode 100644
index 00000000..41a52b6c
--- /dev/null
+++ b/default/agents/skills/omarchy/capture.md
@@ -0,0 +1,60 @@
+# Capture and Sharing
+
+Read this before taking screenshots or screen recordings, extracting text from
+the screen, or sharing files with other machines.
+
+## Screenshots
+
+```bash
+omarchy screenshot                            # Interactive smart-region flow
+omarchy capture screenshot region             # Select a region
+omarchy capture screenshot windows            # Pick a window
+omarchy capture screenshot fullscreen save    # Full screen, straight to disk (no editor)
+```
+
+The first argument picks the mode (`smart|region|windows|fullscreen`), the
+second what happens with it (`slurp|copy|save`). `save` skips the annotation
+editor and prints the saved path. Screenshots land in the configured Pictures
+directory (override with `OMARCHY_SCREENSHOT_DIR`).
+
+## Screen Recording
+
+```bash
+omarchy screenrecord --fullscreen             # Start recording the full screen
+# ...exercise whatever you want on film...
+omarchy screenrecord --stop-recording         # Stop; prints the saved path
+```
+
+Optional flags: `--with-desktop-audio`, `--with-microphone-audio`,
+`--with-webcam` (plus `--webcam-device=` and `--webcam-size=`), and
+`--resolution=<size>`. Without `--fullscreen` a region picker opens first.
+Recordings land in the configured Videos directory (override with
+`OMARCHY_SCREENRECORD_DIR`). Resize a live webcam overlay with
+`omarchy capture webcam resize <smaller|larger|reset|small|medium|large>`.
+
+If recording fails to start, rerun with `OMARCHY_SCREENRECORD_DEBUG=true` to
+collect a log at `/tmp/omarchy-screenrecord.log` worth attaching to a bug
+report.
+
+## Text Capture (OCR)
+
+```bash
+omarchy capture text    # Select a region; extracted text goes to the clipboard
+```
+
+## Sharing Files
+
+```bash
+omarchy share clipboard               # Share the clipboard via LocalSend
+omarchy share file <path...>          # Share files with nearby devices
+omarchy share folder <path>           # Share a folder
+
+omarchy tailscale send <machine> <file...>    # Taildrop to a tailnet machine
+omarchy tailscale receive [directory]         # Save incoming Taildrop files
+```
+
+Shrink large captures before sharing them:
+
+```bash
+omarchy transcode <input> [format] [resolution]   # Re-encode pictures/videos for sharing
+```
diff --git a/default/agents/skills/omarchy/contributing.md b/default/agents/skills/omarchy/contributing.md
new file mode 100644
index 00000000..117a9901
--- /dev/null
+++ b/default/agents/skills/omarchy/contributing.md
@@ -0,0 +1,65 @@
+# Reporting Issues and Submitting PRs
+
+Read this when the user wants to report an Omarchy bug, suggest a feature, or
+contribute a fix upstream.
+
+Omarchy lives at https://github.com/basecamp/omarchy. Route requests to the
+right place:
+
+- **Verified bugs** -> GitHub issues. Issues are for validated bugs only, not
+  support requests.
+- **Feature ideas and suggestions** ->
+  https://github.com/basecamp/omarchy/discussions/categories/suggestions
+- **Support and "is this a bug?" questions** -> the Discord community at
+  https://omarchy.org/discord. Start here when the problem isn't clearly a bug
+  in Omarchy itself.
+
+## Filing a Good Bug Report
+
+The bug template asks for system details (CPU, GPU, Omarchy version), a
+description with steps to reproduce, and diagnostics. Gather them:
+
+```bash
+omarchy version
+
+# Generate the diagnostic log (also written to /tmp/omarchy-debug.log)
+omarchy debug --no-sudo --print
+
+# Interactive variant: `omarchy debug` offers to upload the log to
+# logs.omarchy.org (expires after 24h) and prints a shareable URL to
+# include in the issue.
+```
+
+**Capture the problem on screen.** A screenshot or short recording of the bug
+is often worth more than the description — see [`capture.md`](capture.md) for
+`omarchy capture screenshot` and `omarchy screenrecord`. Keep recordings short
+and focused on the misbehavior. GitHub issue attachments are added by
+drag-and-drop in the web form, so save the capture and hand the user the file
+path to attach (`gh` cannot upload media).
+
+For screen-recording failures specifically, rerun with
+`OMARCHY_SCREENRECORD_DEBUG=true` and attach `/tmp/omarchy-screenrecord.log`.
+
+File the issue with `gh` when available:
+
+```bash
+gh issue create --repo basecamp/omarchy --title "..." --body "..."
+```
+
+Include: what happened, what was expected, steps to reproduce, system details,
+the debug log URL (or attached log), and the capture.
+
+## Submitting a PR
+
+Never develop against `/usr/share/omarchy`. Clone a working copy instead:
+
+```bash
+gh repo fork basecamp/omarchy --clone
+cd omarchy
+```
+
+Follow the repository's own `AGENTS.md` for style, testing, and commit
+conventions — it is the authority on contributions. Keep commits atomic, run
+`./test/all` before pushing, and open the PR with `gh pr create`. A PR that
+fixes a visual problem should include before/after captures (again, see
+[`capture.md`](capture.md)).
diff --git a/default/agents/skills/omarchy/hooks.md b/default/agents/skills/omarchy/hooks.md
new file mode 100644
index 00000000..4f8236ac
--- /dev/null
+++ b/default/agents/skills/omarchy/hooks.md
@@ -0,0 +1,28 @@
+# Automation Hooks
+
+Read this before setting up scripts that run on system events (theme changes,
+updates, boot, low battery, etc.).
+
+Hooks live in `~/.config/omarchy/hooks/<name>.d/` — one directory per event,
+holding any number of independent scripts. Install with
+`omarchy hook install <name> <script>` (copies the script in and makes it
+executable). The runner also executes a flat `~/.config/omarchy/hooks/<name>`
+file first, if one exists.
+
+```
+~/.config/omarchy/hooks/
+├── battery-low.d/          # Low battery (percentage in $1)
+├── font-set.d/             # After font change (font name in $1)
+├── post-boot.d/            # After the desktop starts
+├── post-update.d/          # During `omarchy update`, after system packages and migrations
+├── pre-refresh-pacman.d/   # Before `omarchy refresh pacman` re-syncs packages
+└── theme-set.d/            # After theme change (theme slug in $1)
+```
+
+Example hook script:
+```bash
+#!/bin/bash
+THEME_NAME=$1
+echo "Theme changed to: $THEME_NAME"
+# Add custom actions here
+```
diff --git a/default/agents/skills/omarchy/hyprland.md b/default/agents/skills/omarchy/hyprland.md
new file mode 100644
index 00000000..961ff388
--- /dev/null
+++ b/default/agents/skills/omarchy/hyprland.md
@@ -0,0 +1,78 @@
+# Hyprland Configuration
+
+Read this before changing keybindings, monitors, window rules, or any other
+Hyprland (window manager) configuration.
+
+Omarchy configures Hyprland in Lua. User files are loaded after Omarchy's
+defaults, so overrides go here:
+
+```
+~/.config/hypr/
+├── hyprland.lua       # Main config (loads Omarchy defaults, then user files)
+├── bindings.lua       # Keybindings
+├── monitors.lua       # Display configuration
+├── input.lua          # Keyboard/mouse settings
+├── looknfeel.lua      # Appearance (gaps, borders, animations)
+├── autostart.lua      # Startup applications
+├── hyprsunset.conf    # Night light / blue light filter
+└── xdph.conf          # Screen sharing / desktop portal
+```
+
+**Key behaviors (the `.lua` files):**
+- Hyprland auto-reloads on config save (no restart needed for most changes)
+- Use `hyprctl reload` to force reload
+- After ANY Hyprland Lua config change, validate with `hyprctl reload` followed by `hyprctl configerrors`
+- If `hyprctl configerrors` reports errors, address them and rerun validation until clean or until a real blocker is identified
+- Use `omarchy refresh hyprland` to reset the Lua config files to defaults
+
+The two `.conf` files are read by separate processes, so `hyprctl` neither
+applies nor validates them:
+- `hyprsunset.conf` (night light): apply changes with `omarchy restart hyprsunset`; reset with `omarchy refresh hyprsunset`
+- `xdph.conf` (screen-sharing portal): applies when the portal restarts, e.g. on next login
+
+## Keybindings
+
+Edit `~/.config/hypr/bindings.lua`. Format:
+```lua
+o.bind("SUPER + SHIFT + R", "SSH", "alacritty -e ssh your-server")
+o.bind("SUPER + B", "Browser", { launch = "chromium" })  -- launch wraps with uwsm-app
+```
+
+View current bindings: `omarchy menu keybindings --print`
+
+**IMPORTANT: When re-binding an existing key:**
+
+1. First check existing bindings: `omarchy menu keybindings --print`
+2. If the key is already bound, you MUST call `hl.unbind(...)` BEFORE the new `o.bind(...)`
+3. Inform the user what the key was previously bound to
+
+Example - rebinding SUPER+F (which is bound to fullscreen by default):
+```lua
+-- Unbind existing SUPER+F (was: fullscreen)
+hl.unbind("SUPER + F")
+-- New binding for file manager
+o.bind("SUPER + F", "File manager", { launch = "nautilus" })
+```
+
+Always tell the user: "Note: SUPER+F was previously bound to fullscreen. I've added an unbind to override it."
+
+## Display/Monitors
+
+Edit `~/.config/hypr/monitors.lua`. Format:
+```lua
+hl.monitor({ output = "eDP-1", mode = "1920x1080@60", position = "0x0", scale = 1 })
+hl.monitor({ output = "HDMI-A-1", mode = "2560x1440@144", position = "1920x0", scale = 1 })
+```
+
+List monitors and supported modes: `hyprctl monitors all`
+
+## Window Rules
+
+**CRITICAL: Hyprland window rules syntax changes frequently between versions.**
+
+Before writing ANY window rules, you MUST fetch the current documentation from the official Hyprland wiki:
+- https://wiki.hypr.land/Configuring/Basics/Window-Rules/
+
+DO NOT rely on cached or memorized window rule syntax. The format has changed multiple times and using outdated syntax will cause errors or unexpected behavior.
+
+Window rules go in `~/.config/hypr/hyprland.lua` or a required Lua module. Prefer Omarchy's `o.window(match, rules)` helper — see examples in `$OMARCHY_PATH/default/hypr/windows.lua`.
diff --git a/default/agents/skills/omarchy/plugins.md b/default/agents/skills/omarchy/plugins.md
new file mode 100644
index 00000000..6e3ab069
--- /dev/null
+++ b/default/agents/skills/omarchy/plugins.md
@@ -0,0 +1,52 @@
+# Omarchy Shell: Bar, Plugins, and Idle
+
+Read this before changing the status bar, notifications, shell plugins,
+widgets, or idle/lock behavior.
+
+The bar, notification daemon, settings panel, and assorted overlays all run
+inside a single long-running Quickshell process (`omarchy-shell`).
+
+```
+~/.config/omarchy/shell.json             # User overrides: bar, plugins, idle
+~/.config/omarchy/plugins/<plugin-id>/   # User-owned shell plugins
+$OMARCHY_PATH/config/omarchy/shell.json  # Canonical defaults
+```
+
+The shell hot-reloads `shell.json` on save — no restart needed for layout
+changes. `idle.screensaver` and `idle.lock` are seconds since user idle began.
+
+**Commands:** `omarchy restart shell`, `omarchy refresh shell`
+
+## Bar Layout
+
+Use the `omarchy bar` group to move and manage widgets:
+
+```bash
+omarchy bar move omarchy.clock --section right
+```
+
+For layout edits beyond what the commands cover, edit the bar configuration
+in `~/.config/omarchy/shell.json`; it hot-reloads on save.
+
+## Customizing Built-In Plugins and Widgets
+
+To customize a built-in bar widget, never edit `$OMARCHY_PATH/shell/plugins/`.
+Clone it into the user plugin directory instead:
+
+```bash
+omarchy plugin clone omarchy.workspaces
+# Edit ~/.config/omarchy/plugins/<username>.workspaces/; saved changes reload automatically.
+```
+
+Cloning switches the bar to the cloned copy (e.g. `<username>.workspaces`),
+which is yours to edit and survives updates.
+
+Saving a file anywhere under `~/.config/omarchy/plugins/` reloads plugin code
+automatically. If a change somehow fails to apply, force a reload with
+`omarchy-shell shell rescanPlugins`.
+
+## Idle and Lock
+
+Set `idle.screensaver` and `idle.lock` in `~/.config/omarchy/shell.json`,
+in seconds since user idle began. Example: "lock after ten minutes" means
+setting `idle.lock` to `600`.
diff --git a/default/agents/skills/omarchy/theming.md b/default/agents/skills/omarchy/theming.md
new file mode 100644
index 00000000..fcd19ab6
--- /dev/null
+++ b/default/agents/skills/omarchy/theming.md
@@ -0,0 +1,56 @@
+# Themes, Backgrounds, and Fonts
+
+Read this before changing themes, backgrounds, fonts, or theme colors.
+
+## Theme Commands
+
+```bash
+omarchy theme list              # Show available themes
+omarchy theme current           # Show current theme
+omarchy theme set <name>        # Apply theme ("Tokyo Night" and "tokyo-night" both work)
+omarchy theme bg next           # Cycle background
+omarchy theme install <url>     # Install from git repo
+```
+
+## Making a New Theme
+
+1. Create a directory under `~/.config/omarchy/themes`.
+2. See how an existing theme is done via `/usr/share/omarchy/themes/catppuccin`.
+3. Download a matching background (or several) from the internet and put them in `~/.config/omarchy/themes/<name-of-new-theme>/backgrounds/`.
+4. When done with the theme, run `omarchy theme set "Name of new theme"`.
+
+Additional user backgrounds for any theme (stock or custom) go in
+`~/.config/omarchy/backgrounds/<theme-slug>/`.
+
+## Customizing a Stock Theme
+
+Never edit stock themes under `/usr/share/omarchy/themes/` — changes are lost
+on update. Two safe options:
+
+**Overlay (preferred for small tweaks):** create a user theme directory with
+the SAME slug containing only the files you want to change. When the theme is
+applied, the stock theme is copied first and your files win on top:
+
+```bash
+mkdir -p ~/.config/omarchy/themes/catppuccin
+cp /usr/share/omarchy/themes/catppuccin/colors.toml ~/.config/omarchy/themes/catppuccin/
+# Edit the copied colors.toml, then re-apply:
+omarchy theme set catppuccin
+```
+
+**Fork:** copy the whole stock theme under a new name for a fully independent
+variant:
+
+```bash
+cp -r /usr/share/omarchy/themes/catppuccin ~/.config/omarchy/themes/catppuccin-custom
+# Edit ~/.config/omarchy/themes/catppuccin-custom/, then:
+omarchy theme set catppuccin-custom
+```
+
+## Fonts
+
+```bash
+omarchy font list               # Available fonts
+omarchy font current            # Current font
+omarchy font set <name>         # Change font
+```
diff --git a/docs/file-layout.md b/docs/file-layout.md
index 29e8196a..99370089 100644
--- a/docs/file-layout.md
+++ b/docs/file-layout.md
@@ -165,7 +165,7 @@ Runs once per user. It does **not** copy `~/.config/**`, `~/.bashrc`,
 It only does the things `/etc/skel` can't:
 
 - Skill symlinks `~/.{agents,claude,codex,pi/agent}/skills/omarchy` →
-  `$OMARCHY_PATH/default/omarchy-skill`. Symlinks (not copies) so
+  `$OMARCHY_PATH/default/agents/skills/omarchy`. Symlinks (not copies) so
   `omarchy dev link` against a dev checkout repoints them correctly.
 - `xdg-user-dirs-update` (Templates/Public/Desktop folded back into `$HOME`)
   and `~/.config/gtk-3.0/bookmarks` (needs `$HOME` expansion).
diff --git a/migrations/1786098807.sh b/migrations/1786098807.sh
new file mode 100644
index 00000000..6b2c2cc8
--- /dev/null
+++ b/migrations/1786098807.sh
@@ -0,0 +1,7 @@
+echo "Relink agent skill symlinks to default/agents/skills/omarchy"
+
+mkdir -p ~/.agents/skills ~/.claude/skills ~/.codex/skills ~/.pi/agent/skills
+ln -sfn "$OMARCHY_PATH/default/agents/skills/omarchy" ~/.agents/skills/omarchy
+ln -sfn "$OMARCHY_PATH/default/agents/skills/omarchy" ~/.claude/skills/omarchy
+ln -sfn "$OMARCHY_PATH/default/agents/skills/omarchy" ~/.codex/skills/omarchy
+ln -sfn "$OMARCHY_PATH/default/agents/skills/omarchy" ~/.pi/agent/skills/omarchy