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