diff --git a/README.md b/README.md
index 150af3d..42bbf8b 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,7 @@ My current setup is built around these core components:
 ### Directory Structure
 
 - **`hypr/`**: Hyprland configurations (keybindings, window rules, animations, monitor layout, lid-close display handling, and autostart). See [`hypr/keybinds.md`](hypr/keybinds.md) for custom keybindings.
-- **`omarchy/`**: Omarchy 4 configuration — `shell.json` (bar layout and idle/lock timings), `extensions/` (entries added to the Omarchy menu), `hooks/` (event hooks such as retinting AGS on theme change), and `themed/` (extra theme templates).
+- **`omarchy/`**: Omarchy 4 configuration — `shell.json` (bar layout, custom bar modules, and idle/lock timings), `extensions/` (entries added to the Omarchy menu), `hooks/` (event hooks such as retinting AGS on theme change), and `themed/` (extra theme templates). See [`omarchy/README.md`](omarchy/README.md) for the bar layout.
 - **`ags/`**: Custom desktop widgets built with TypeScript and GTK — media player, notification hub, quick settings, system monitor, wallpaper picker, and theme picker.
 - **`scripts/`**: Global utility scripts seamlessly exposed as commands by the installer. See [`commands.md`](commands.md).
 - **`wallpapers/`**: A collection of local custom wallpapers for dynamic theming. See [`wallpaper-gallery/`](wallpaper-gallery/index.md) for the full gallery (split alphabetically across multiple pages).
diff --git a/omarchy/README.md b/omarchy/README.md
new file mode 100644
index 0000000..f161346
--- /dev/null
+++ b/omarchy/README.md
@@ -0,0 +1,62 @@
+# Omarchy config
+
+Omarchy 4 replaced waybar with the Quickshell bar built into `omarchy-shell`.
+`shell.json` is the whole bar config; it hot-reloads on save, and
+`install.sh` deploys it to `~/.config/omarchy/shell.json`.
+
+## Bar layout
+
+Ported from the old `waybar/config.jsonc`, section for section:
+
+| Old waybar module | shell.json widget |
+| --- | --- |
+| `custom/omarchy` | `omarchy.menu` |
+| `hyprland/workspaces` | `omarchy.workspaces` |
+| `clock` | `omarchy.clock` |
+| `custom/update` | `omarchy.system-update` |
+| `custom/voxtype` | `omarchy.indicators` -> `Dictation` |
+| `custom/screenrecording-indicator` | `omarchy.indicators` -> `ScreenRecording` |
+| `custom/idle-indicator` | `omarchy.indicators` -> `StayAwake` |
+| `custom/notification-silencing-indicator` | `omarchy.indicators` -> `Dnd` |
+| `group/tray-expander` | `omarchy.tray` |
+| `bluetooth` | `omarchy.bluetooth` |
+| `network` | `omarchy.network` |
+| `pulseaudio` | `omarchy.audio` |
+| `battery` | `omarchy.power` |
+| `cpu` | `blob.cpu` (custom module) |
+| `custom/notification` | `blob.notifications` (custom module) |
+
+Drop the `items` list from `omarchy.indicators` to show all six indicators
+(adds `NightLight` and `Reminder`).
+
+## Custom modules
+
+The bar accepts arbitrary ids with `type: "command"`, which is how the two
+AGS entry points survive the move off waybar:
+
+- `blob.cpu` - left opens btop, middle opens alacritty, right toggles the AGS
+  system monitor
+- `blob.notifications` - left toggles the AGS notification center, right
+  toggles notification silencing
+
+A command module with no `exec` key is a static icon; add `exec` and
+`interval` for one that refreshes its own text.
+
+## Editing
+
+Dragging widgets in the bar rewrites `~/.config/omarchy/shell.json` directly.
+That makes the live file diverge from this one, so after rearranging by hand,
+copy it back:
+
+```bash
+cp ~/.config/omarchy/shell.json omarchy/shell.json
+```
+
+Run `./install.sh --check` to see whether the two have drifted.
+
+## Not portable from waybar
+
+- Bar height: fixed by the shell's style (26px horizontal, 28px vertical).
+- Per-widget click actions on first-party widgets: `omarchy.clock`,
+  `omarchy.network`, and `omarchy.bluetooth` own their popups, so the old
+  right-click-into-AGS bindings only exist on the custom modules above.
diff --git a/omarchy/shell.json b/omarchy/shell.json
index 74ead5d..0ec7697 100644
--- a/omarchy/shell.json
+++ b/omarchy/shell.json
@@ -18,32 +18,29 @@
         }
       ],
       "center": [
-        {
-          "id": "omarchy.indicators"
-        },
         {
           "id": "omarchy.clock",
-          "format": "dddd HH:mm",
+          "format": "dddd d MMMM HH:mm",
           "formatAlt": "d MMMM 'W'ww yyyy",
-          "verticalFormat": "HH\n\u2014\nmm"
-        },
-        {
-          "id": "omarchy.keyboard-layout"
-        },
-        {
-          "id": "omarchy.weather"
+          "verticalFormat": "HH\n—\nmm"
         },
         {
           "id": "omarchy.system-update"
+        },
+        {
+          "id": "omarchy.indicators",
+          "items": [
+            "Dictation",
+            "ScreenRecording",
+            "StayAwake",
+            "Dnd"
+          ]
         }
       ],
       "right": [
         {
           "id": "omarchy.tray"
         },
-        {
-          "id": "omarchy.agents"
-        },
         {
           "id": "omarchy.bluetooth"
         },
@@ -54,10 +51,24 @@
           "id": "omarchy.audio"
         },
         {
-          "id": "omarchy.monitor"
+          "id": "blob.cpu",
+          "type": "command",
+          "text": "󰍛",
+          "tooltip": "System monitor",
+          "onClick": "omarchy-launch-or-focus-tui btop",
+          "onMiddleClick": "alacritty",
+          "onRightClick": "ags toggle sys-monitor"
         },
         {
           "id": "omarchy.power"
+        },
+        {
+          "id": "blob.notifications",
+          "type": "command",
+          "text": "",
+          "tooltip": "Notifications",
+          "onClick": "ags toggle notification-center",
+          "onRightClick": "omarchy-toggle-notification-silencing"
         }
       ]
     }