diff --git a/README.md b/README.md
index 3cf8017..ccec32d 100644
--- a/README.md
+++ b/README.md
@@ -49,3 +49,14 @@ Set in shell:
 ```bash
 export KANAGAWA_THEME="wave"  # or "dragon"
 ```
+
+## Omarchy install
+
+For a full Arch + Hyprland desktop built on [Omarchy](https://omarchy.org) with
+these dotfiles, Brave Origin Beta, and WezTerm pre-wired, see
+[`omarchy/README.md`](omarchy/README.md). Quick start on a fresh Arch system:
+
+```bash
+git clone https://github.com/brianpooe/dotfiles.git ~/dotfiles
+~/dotfiles/omarchy/install.sh
+```
diff --git a/omarchy/README.md b/omarchy/README.md
index 3f4ea66..8611dc5 100644
--- a/omarchy/README.md
+++ b/omarchy/README.md
@@ -6,23 +6,71 @@ fork Omarchy — it patches the package list before Omarchy's own installer runs
 then layers customizations on top using Omarchy's documented extension points, so
 it survives `omarchy-update`.
 
-## Usage
+## Environment required
 
-On a fresh Arch Linux system:
+This is a **full system installer**, not a sandbox-safe script. Run it only on a
+machine you intend to set up as an Omarchy workstation.
+
+- **OS:** a fresh **Arch Linux** install (x86_64). The script aborts if
+  `/etc/arch-release` is absent. Arch derivatives (EndeavourOS, CachyOS) are
+  untested.
+- **State:** ideally a clean Arch base — Omarchy's installer reconfigures
+  bootloader, login (SDDM/Limine), services, and the graphics stack. Existing
+  configs at the symlink targets are backed up to `*.pre-omarchy.<timestamp>`,
+  not deleted.
+- **Privileges:** a regular user with **`sudo`** rights (do **not** run as root).
+  The installer will prompt for `sudo` and change your login shell to `zsh`.
+- **Network:** outbound HTTPS to GitHub, the Arch/AUR mirrors, the Omarchy
+  mirror, and `brave.com` (Brave Origin Beta). A working `pacman` mirrorlist.
+- **Required commands:** `git` and `sudo` (preflight checks these). `curl` is
+  used for the optional `nvm` install; everything else is installed by Omarchy.
+- **Hardware:** designed around a single **3440×1440 @ 120Hz** ultrawide (see
+  `files/hypr-monitors.lua`); adjust that file for other displays.
+- **Time/space:** expect a long run (full desktop + AUR builds) and several GB of
+  downloads.
+
+> Heads-up: there is no unattended/dry-run mode. Omarchy's own installer is
+> interactive in places. Don't run this on a daily-driver you can't reimage.
+
+## Installation
+
+On a fresh Arch Linux system, as your normal (non-root) user:
 
 ```bash
-git clone <repo-url> ~/dotfiles
+# 1. Clone these dotfiles
+git clone https://github.com/brianpooe/dotfiles.git ~/dotfiles
+
+# 2. Run the installer (clones Omarchy, installs it, applies the layer)
 ~/dotfiles/omarchy/install.sh
+
+# 3. Reboot (or log out and back in) to start the zsh + Hyprland session
 ```
 
-Re-apply just the customization layer after an `omarchy-update` (does not touch
-the Omarchy core install):
+Re-apply just the customization layer after an `omarchy-update` — this skips the
+Omarchy core install and only re-applies removals/swaps/symlinks/overrides:
 
 ```bash
 ~/dotfiles/omarchy/install.sh --layer-only
+~/dotfiles/omarchy/install.sh --help   # show usage
 ```
 
-Then log out and back in (or reboot) to start the zsh + Hyprland session.
+### Configuration (environment variables)
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `OMARCHY_REPO` | `basecamp/omarchy` | Omarchy source repo (`owner/name`) |
+| `OMARCHY_REF` | `master` | Omarchy branch/tag to install |
+| `OMARCHY_PATH` | `~/.local/share/omarchy` | Where Omarchy is cloned |
+| `DOTFILES_DIR` | repo root (auto-detected) | Source dir for symlinks |
+| `DEFAULT_FONT` | `JetBrainsMono Nerd Font` | System monospace font |
+| `NVM_VERSION` | `v0.40.1` | Pinned nvm release |
+
+Example — install a specific Omarchy tag with a different font:
+
+```bash
+OMARCHY_REF=v3.0.0 DEFAULT_FONT="CaskaydiaMono Nerd Font" \
+  ~/dotfiles/omarchy/install.sh
+```
 
 ## What it does