docs(omarchy): #78 Omarchy → Nomarchy migrant one-pager

Add docs/OMARCHY.md for users coming from Omarchy (VISION § F). Leads
with the one real difference — imperative dotfiles vs a declarative flake
built via the menu, with rollback through NixOS generations — then maps
the deltas: install (ISO/nomarchy-install or MIGRATION.md), a familiar
keybindings table, theming (SUPER+T / nomarchy-theme-sync), installing
software (home.packages / nix shell, no AUR), and update+rollback
(nomarchy-pull/-rebuild/-home, boot-menu generations, nomarchy-doctor).
Registered in docs/README.md; VISION § F marked shipped.

The Nomarchy side is grounded in the code: keybindings pulled from
keybinds.nix, and every cited command (7), the nsearch alias, and the
named theme slugs (gruvbox/rose-pine/nord) verified to exist. Omarchy-side
claims kept to known facts (Arch, dotfiles, pacman/AUR).

Verification: V0 (docs-only); commands/slugs/binds checked against the tree.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/OMARCHY.md

@@ -0,0 +1,125 @@
+# Coming from Omarchy
+
+Nomarchy and [Omarchy](https://omarchy.org) are cousins: the same
+Hyprland + Waybar desktop feel, the same opinionated "beautiful out of the
+box," one-command theming, and a keyboard-driven menu. If you liked
+Omarchy, you'll be at home here in minutes.
+
+The one real difference is the **foundation**:
+
+|            | Omarchy | Nomarchy |
+|------------|---------|----------|
+| Base       | Arch Linux | NixOS |
+| Config     | **imperative** dotfiles you edit in `~/.config`, live | **declarative** — built from a flake; changed via the menu or your `home.nix`/`system.nix` |
+| Packages   | `pacman` / `yay` / AUR, anytime | `nixpkgs` — added to your flake (no AUR) |
+| Recovery   | reinstall / restore dotfiles | **every rebuild is a bootable generation** — roll back from the boot menu |
+
+This page maps the day-to-day deltas. Nothing about the *desktop* has to
+be relearned — only *how you change it*.
+
+---
+
+## The one mental shift: declarative, not dotfiles
+
+In Omarchy you open a file under `~/.config`, save it, and the change is
+live. In Nomarchy the whole desktop is **built from your flake**, so you
+change it one of two ways:
+
+1. **The menu** (`SUPER+M`) — the everyday path. It writes the change into
+   your flake's state and rebuilds for you. You never hand-edit a config
+   for theming, night light, wallpaper, keyboard layout, power, etc.
+2. **Your flake** — for anything the menu doesn't cover, edit
+   `home.nix` / `system.nix` (a handful of `nomarchy.*` options and plain
+   Home-Manager/NixOS), then run a rebuild.
+
+The payoff for the extra indirection: **a bad change never bricks you.**
+Every `nomarchy-rebuild` is a new NixOS generation; if one misbehaves,
+reboot and pick the previous entry from the boot menu — your files
+(`/home`) are never touched. See [RECOVERY.md](RECOVERY.md).
+
+> Editing `~/.config/hypr/*` by hand won't stick — Home-Manager owns those
+> files and rewrites them on the next rebuild. Change the source (menu or
+> flake) instead.
+
+---
+
+## Install
+
+| | |
+|---|---|
+| **Omarchy** | Run the bootstrap on a fresh Arch install. |
+| **Nomarchy** | Boot the ISO and run **`nomarchy-install`** (single-disk UEFI, optional LUKS, hibernation-ready swap). |
+| **Already on NixOS?** | Convert in place, no reformat — [MIGRATION.md](MIGRATION.md). |
+
+---
+
+## Keybindings (they'll feel familiar)
+
+The full, always-current list is one keypress away: **`SUPER+?`** opens the
+live cheatsheet — you never have to memorize this table.
+
+| Key | Action |
+|-----|--------|
+| `SUPER+Return` | Terminal |
+| `SUPER+Space` | App launcher |
+| `SUPER+M` | Main menu (theme, network, audio, power, tools…) |
+| `SUPER+T` | Theme picker |
+| `SUPER+SHIFT+T` | Next wallpaper |
+| `SUPER+E` | File manager (yazi) |
+| `SUPER+X` | Power menu (lock / suspend / hibernate / reboot …) |
+| `SUPER+?` | Keybindings cheatsheet |
+| `Print` | Screenshot region → clipboard |
+| `SUPER+CTRL+<key>` | Jump straight to a menu module (clipboard `V`, calc `C`, emoji `E`, capture `S`, …) |
+
+---
+
+## Theming
+
+Both distros reskin everything from one place. In Nomarchy:
+
+- **`SUPER+T`** (or `nomarchy-menu theme`) — pick from 24 presets with live
+  previews; it rebuilds and applies to Hyprland, Waybar, the terminal,
+  btop and GTK/Qt at once.
+- Or from a shell: `nomarchy-theme-sync apply <slug>` (e.g. `gruvbox`,
+  `rose-pine`, `nord`).
+- Tweak gaps / rounding / fonts / opacity / icon pack without leaving the
+  theme system — see [OVERRIDES.md](OVERRIDES.md). One git-tracked JSON
+  (`theme-state.json`) is the single source of truth.
+
+---
+
+## Installing software
+
+There is no AUR. Two paths:
+
+- **Keep it:** add the package to `home.packages` in your flake's
+  `home.nix`, then `nomarchy-home`. It's now declared, reproducible, and
+  part of your rollback history. A curated default app set already ships —
+  you extend the list.
+- **Just this once:** `nix shell nixpkgs#<pkg>` drops you into a shell with
+  it on `PATH`, gone when you exit — the equivalent of a throwaway install.
+
+Search with `nsearch <name>` (`nix search nixpkgs`).
+
+---
+
+## Update & roll back
+
+| | Omarchy | Nomarchy |
+|---|---|---|
+| **Update** | update command | `nomarchy-pull` (bump inputs), then `nomarchy-rebuild` (system) + `nomarchy-home` (desktop) |
+| **Roll back** | restore dotfiles | reboot → pick the previous **generation** in the boot menu (or a snapper snapshot) |
+| **Health check** | — | `nomarchy-doctor` (System › Doctor) — read-only pass/fail sheet, each ✖ shows its fix |
+
+On a failed rebuild, `nomarchy-rebuild` / `nomarchy-home` print the last
+log lines and point you at `nomarchy-doctor` and [RECOVERY.md](RECOVERY.md)
+— you're never left guessing.
+
+---
+
+## What's exactly the same
+
+Hyprland tiling and feel, Waybar, the rofi-driven menu, the blur/rounding
+aesthetic, keyboard-first everything, and strong opinionated defaults. The
+desktop is the part you already know — this page is only about the NixOS
+plumbing underneath.

docs/README.md

@@ -13,6 +13,7 @@ tree for the same facts.
 | [RECOVERY.md](RECOVERY.md) | Users | Broken theme/desktop/boot → undo |
 | [OVERRIDES.md](OVERRIDES.md) | Users | Downstream Nix overrides |
 | [MIGRATION.md](MIGRATION.md) | Users | Existing NixOS → Nomarchy without reinstall |
+| [OMARCHY.md](OMARCHY.md) | Users | Coming from Omarchy — bindings/theme/install/config map |
 
 ## Related (not under `docs/`)
 

docs/VISION.md

@@ -111,7 +111,7 @@ Reference: [HARDWARE.md](HARDWARE.md) §4–§5, §10.
 
 | Idea | Intent | Notes |
 |------|--------|-------|
-| **Omarchy migrant one-pager** | Bindings/theme/install map | `docs/` short guide |
+| **Omarchy migrant one-pager** ✓ | Bindings/theme/install map | ✓ shipped `docs/OMARCHY.md` (#78, 2026-07-10) |
 | **Hardware hall of fame** | Install-tested models; invite DMI PRs | Ties to HARDWARE.md §9 |
 | **60s demo** | Live → install → theme → menu | Outside repo OK |