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
+**Already shipped for NEW installs** (verify, don't rebuild): installer
-   resume (already used), what when install chose `swapSize=0`, migration
+defaults `NOMARCHY_SWAP_GB=RAM` → hibernation-ready `@swap` swapfile encrypted
-   for existing machines. (zram priority-vs-disk already settled + shipped.)
+with root; `patch-template.py` writes `swapDevices` + `boot.resumeDevice` +
-2. **Module** — NixOS: ensure hibernation knobs are coherent when swapfile
+`resume_offset`; Power menu has a Hibernate row; hibernate+LUKS+hyprlock
-   exists (resume device/offset); Power menu Hibernate already present —
+interplay handled in `modules/nixos/default.nix` / `modules/home/idle.nix`.
-   must work when swap is configured. (zram already default-on in oom.nix.)
+
-3. **Installer** — default new installs to hibernation-ready `@swap`
+**Remaining slices:**
-   swapfile (encrypted with root); keep `0` = no swap opt-out; document
+
-   migration.
+1. **Docs** — `docs/MIGRATION.md` hibernation-enable runbook (V0).
-4. **Verify (required)**
+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 +
+- **Swap sizing** — **exactly RAM** (installer default, unchanged). Hibernate
-  zram on is the product default; exact installer numbers TBD in design).
+  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**.

agent/JOURNAL.md

@@ -17,6 +17,21 @@ Template:
 
 ---
 
+## 2026-07-10 — #76 hibernation design calls (no commit yet → this bookkeeping)
+- **Task:** BACKLOG #76 design slice — Bernardo made the open calls.
+- **Did:** Recon showed the hibernation half is **already built for new
+  installs** (installer defaults swap=RAM hibernation-ready `@swap` swapfile;
+  `patch-template.py` writes swapDevices/resumeDevice/resume_offset; Power
+  menu Hibernate row + LUKS/hyprlock handling exist). Settled 3 calls:
+  (1) swap sizing = **exactly RAM** (no change); (2) migration = **docs
+  runbook in MIGRATION.md**, not a tool; (3) no-swap Hibernate = **keep row,
+  notify on failure**. Folded into BACKLOG #76 (design ✓, re-sliced remaining:
+  MIGRATION.md runbook + notify-on-failure menu) and Decisions.
+- **Verified:** **V0** — `nix flake check --no-build` green (docs-only).
+- **Pending:** two remaining slices below; V2 hibernate VM test + V3 laptop.
+- **Next suggestion:** slice 1 — `docs/MIGRATION.md` hibernation-enable runbook
+  (V0), then slice 2 — Hibernate notify-on-failure (V1/V2).
+
 ## 2026-07-10 — #76 zram slice: compressed-RAM swap default
 - **Task:** BACKLOG #76 (`[big]`) — split; took the low-risk zram-default slice.
 - **Did:** `zramSwap` on by default in `modules/nixos/oom.nix` (zstd, 50% RAM,