docs(agent): #76 hibernation design calls settled

Bernardo's three design calls on the hibernation half of #76:
- swap sizing = exactly RAM (installer default, no change)
- migration for existing machines = docs runbook (MIGRATION.md), not a tool
- no-swap Hibernate = keep menu row, notify on failure

Recon confirmed new installs are already hibernation-ready (installer +
patch-template resume wiring + Power-menu Hibernate row). Folded decisions
into BACKLOG #76; re-sliced remainder to MIGRATION.md runbook + notify-on-
failure menu; recorded in Decisions.

Verification: V0 (docs-only) nix flake check --no-build green.

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

agent/BACKLOG.md

@@ -51,18 +51,31 @@ the encrypted volume** (subvolume, not a separate cleartext partition).
 Installer path already sketches this (`@swap` + resume_offset patch in
 `nomarchy-install` / `patch-template.py`) when `swapSize` ≥ RAM-ish.
 
-**Scope (split before/while implementing — do not land as one mega-PR):**
+**✓ Design settled (Bernardo 2026-07-10):**
+- **Swap sizing** — keep **exactly RAM** (rounded up to whole GiB), as the
+  installer already does. Hibernate image ≤ RAM; zram (priority 100) takes
+  day-to-day paging so the file stays reserved for the image. No change.
+- **`swapSize=0`** — stays a no-swap / no-resume opt-out (already handled by
+  installer + patch-template: no `@swap`, no `swapDevices`/resume wiring).
+- **Migration (existing machines)** — **docs runbook in `docs/MIGRATION.md`**,
+  not a tool: create `@swap` subvol + swapfile, `map-swapfile -r` offset,
+  add `swapDevices`/`boot.resumeDevice`/`resume_offset` to `system.nix`.
+- **No-swap Hibernate UX** — **keep the Power-menu Hibernate row**; when
+  hibernate fails (no swap), show a desktop **notification** explaining no
+  swap is configured (rather than hiding the row or a silent no-op).
 
-1. **Design** — default `swapSize` (= RAM? round up?), LUKS+systemd-initrd
-   resume (already used), what when install chose `swapSize=0`, migration
-   for existing machines. (zram priority-vs-disk already settled + shipped.)
-2. **Module** — NixOS: ensure hibernation knobs are coherent when swapfile
-   exists (resume device/offset); Power menu Hibernate already present —
-   must work when swap is configured. (zram already default-on in oom.nix.)
-3. **Installer** — default new installs to hibernation-ready `@swap`
-   swapfile (encrypted with root); keep `0` = no swap opt-out; document
-   migration.
-4. **Verify (required)**
+**Already shipped for NEW installs** (verify, don't rebuild): installer
+defaults `NOMARCHY_SWAP_GB=RAM` → hibernation-ready `@swap` swapfile encrypted
+with root; `patch-template.py` writes `swapDevices` + `boot.resumeDevice` +
+`resume_offset`; Power menu has a Hibernate row; hibernate+LUKS+hyprlock
+interplay handled in `modules/nixos/default.nix` / `modules/home/idle.nix`.
+
+**Remaining slices:**
+
+1. **Docs** — `docs/MIGRATION.md` hibernation-enable runbook (V0).
+2. **Menu** — Hibernate row: notify-on-failure when no swap configured
+   (behavioral, V1/V2). Keep the row unconditional.
+3. **Verify (required)**
    - **V0:** eval / option / disko contracts.
    - **V2 (mandatory, agent):** exercise hibernation in the **VM harness**
      (`runNixOSTest` or install-test style) — encrypted root + BTRFS
@@ -199,7 +212,9 @@ decide. **Resolved** entries stay for history; agents treat them as closed.
   Implementation is a future/NEXT item when designed (installer +
   resume device + encrypted-root story).
 
-### Still open (design detail under #76)
+### Resolved (2026-07-10, #76 design)
 
-- **Swap sizing / LUKS resume** — implement under NEXT #76 (disk ≥ RAM +
-  zram on is the product default; exact installer numbers TBD in design).
+- **Swap sizing** — **exactly RAM** (installer default, unchanged). Hibernate
+  image ≤ RAM; zram takes day-to-day paging. **`swapSize=0`** stays no-swap.
+- **Migration** — **docs runbook** (`docs/MIGRATION.md`), not a tool.
+- **No-swap Hibernate** — keep the menu row; **notify on failure**.