docs(agent): backlog revision — fill the workstation gaps

Checked guesses against the tree before adding (GC/auto-optimise/boot
limit and all 21 theme previews already ship — not added). New items,
all confirmed absent:

- NOW#2 CI checks-on-push, promoted because agents push main directly
- NOW#3 memory-pressure protection (systemd-oomd/earlyoom; nothing
  guards the session from OOM today and the release bump died to one)
- NEXT#8 PDF/image viewers + xdg-mime defaults (template ships only mpv)
- NEXT#9 update diff (nvd) + menu-driven rollback
- NEXT#10 nomarchy-doctor health check
- NEXT#11 state-file validation + friendly eval errors
- NEXT#12 screen recording in Capture (+ stop via Waybar indicator)
- NEXT#13 niceties: idle-inhibit toggle, low-battery notify, hyprpicker
- LATER: OCR screenshot-to-text
- Decisions: zram-vs-hibernation, default browser for mime defaults
- docs item now includes a recovery runbook

Verified: V0 — docs-only.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

agent/BACKLOG.md

@@ -32,7 +32,35 @@ never commits unrelated dirty files; graceful when the repo has no user
 git identity. **Verify:** V1 + a round-trip on the theme-sync CLI in a
 sandbox repo; V2 if wired into a check.
 
-### 2. btrfs-assistant segfault — attempt the nixpkgs override fix
+### 2. CI: run the check suite on every push (Forgejo Actions)
+First slice of ROADMAP § Automated upstream lock bumps, promoted to NOW
+because agents now push to `main` autonomously — an always-on net under
+that is the single highest-stability lever available. A workflow that
+runs `nix flake check` + the `checks.*` VM suite + a
+`system.build.toplevel` build on push to `main`. **Why:** pillar 1;
+today nothing re-verifies a push. **Done when:** the workflow exists,
+is documented (docs/TESTING.md), and a red run is visible/notifiable;
+the runner requirements (Linux + KVM for the VM checks, or a documented
+no-KVM subset) are written down. **Verify:** V1 locally (the same
+commands the workflow runs) + a real green run on the Forgejo instance
+— if runner infra doesn't exist yet, deliver the workflow + a `[human]`
+note on registering a runner. **Verify the runner half is possible
+before promising it.**
+
+### 3. Memory-pressure protection (no more frozen desktops)
+New. A workstation that compiles from source *will* hit memory
+exhaustion (the discarded release bump died to a Hyprland OOM; a big
+`nix build` can freeze the session today — nothing mitigates OOM).
+Ship a default-on userspace OOM killer: pick `systemd-oomd`
+(`systemd.oomd` + the NixOS enables for user slices) or `earlyoom` —
+write the choice + rationale into the commit; consider protecting the
+session (Hyprland/greetd) and sacrificing `nix-daemon` build slices
+first. **Why:** "rock-stable" means the UI never locks up. **Done
+when:** on by default (`lib.mkDefault`), overridable natively; the
+choice documented in README's "beyond the surface" note. **Verify:**
+V2 — a VM check that memory pressure kills the hog, not the session.
+
+### 4. btrfs-assistant segfault — attempt the nixpkgs override fix
 ROADMAP § Snapshot browse/restore. btrfs-assistant 2.2 crashes in
 `libbtrfsutil.so.1.4.0` (ABI mismatch, confirmed not a VM artifact); the
 `nomarchy-snapshots` fzf fallback ships. Try an override aligning its
@@ -42,7 +70,7 @@ launches in the VM test, or the attempt is written up as infeasible
 (then re-check on each lock bump). **Verify:** V2 — extend the snapper
 VM check to launch the binary.
 
-### 3. Keyboard layouts — cycle bind + summer-bar parity
+### 5. Keyboard layouts — cycle bind + summer-bar parity
 ROADMAP § Keyboard layouts, remaining bullets: (a) a multi-layout cycle
 bind (`hyprctl switchxkblayout` current-device, or xkb `grp:` option)
 when >1 session layout, in the cheatsheet; (b) add `hyprland/language`
@@ -51,16 +79,18 @@ generated bar has it, the static ones don't; gating doesn't translate,
 decide the static behavior and note it). **Verify:** V1 + `jq` the
 rendered configs; V3 queue the on-hardware cycle check.
 
-### 4. Full docs review & restructure
+### 6. Full docs review & restructure
 ROADMAP § Full docs review. The roadmap/backlog split is done (this
 file); remaining: reconcile every README option table against the live
 `nomarchy.*` surface; drift pass over docs/OVERRIDES.md, docs/TESTING.md,
 templates/downstream/README.md; read the install/first-run story end to
-end. Site-vs-markdown is a Decision (below). **Verify:** V0 + a
-mechanical option-surface diff (eval the options, compare to the
-tables — consider making that a permanent check).
+end; add a short **recovery runbook** (desktop won't start → boot an
+older generation / `nomarchy-snapshots` / greetd journal — the pieces
+exist, the story isn't written). Site-vs-markdown is a Decision (below).
+**Verify:** V0 + a mechanical option-surface diff (eval the options,
+compare to the tables — consider making that a permanent check).
 
-### 5. Webcam follow-ups (small)
+### 7. Webcam follow-ups (small)
 ROADMAP § Webcam: ship `v4l-utils` + `cameractrls` (commented app-suite
 entries or alongside the camera toggle — respect the option-surface
 rule) for genuine-tuning cases; write up the portal/Flatpak
@@ -69,37 +99,101 @@ with options. **Verify:** V1.
 
 ## NEXT
 
-### 6. Automated upstream lock bumps (maintainer CI) `[big]`
-ROADMAP § Automated upstream lock bumps — design decided: weekly
-scheduled job (Forgejo Actions) runs `nix flake update` (within pinned
-release branches) → `nix flake check` + the `checks.*` suite + toplevel
-build → lands on `main` on green; `v1` promotion stays human. Repo has
-no CI today, so slice: (a) a workflow that just runs checks on push,
-(b) the scheduled bump job, (c) the fast-lane note for security bumps.
+### 8. Complete-workstation viewers + default applications
+New. The template ships mpv but **no PDF viewer and no image viewer**,
+and nothing sets xdg-mime defaults — so "open a PDF/photo" falls to
+whatever GTK guesses (GIMP for images). Two halves: (a) add a themed,
+lightweight PDF viewer + image viewer to the template's active
+`home.packages` (candidates: zathura or GNOME Papers; imv or loupe —
+prefer what Stylix themes well); (b) a mime-defaults module setting
+`xdg.mimeApps` associations (browser/PDF/image/video/text, `mkDefault`)
+— real config, so unlike bare packages this *is* module territory, but
+it must degrade gracefully when the user deletes a package from the
+suite. **Verify:** V1 + assert the rendered mimeapps.list; V3 queue an
+open-a-file smoke.
 
-### 7. Display profiles — docked/undocked switching
+### 9. Update & rollback UX
+New; extends the update-awareness story to the other half: what changed,
+and how do I get back. (a) `sys-update` prints a human diff of what the
+update changed (`nvd diff` between system generations, or `nix store
+diff-closures`); (b) a **System → Rollback** menu flow: desktop = pick a
+recent `home-manager generations` entry and activate it (the theme
+history is already generations); system = point at the boot-menu
+generation flow + `nomarchy-snapshots` rather than reimplementing it —
+destructive steps keep the typed-`yes` gate. **Why:** informative +
+rock-stable means undo is one menu away, not a Nix lesson. **Verify:**
+V1; V2 for the generation-activate path in a VM.
+
+### 10. `nomarchy-doctor` — one-shot health check
+New. A single command (+ System-menu entry) that checks the things that
+actually break user machines and prints a themed pass/fail sheet:
+failed systemd units (system + user), disk space (/, /boot, the nix
+store), state-file parses + is git-tracked, downstream flake dirty/
+diverged, last rebuild generation age, snapper timeline running (when
+enabled). Read-only, no auto-fixing; each failure prints the one command
+that fixes it. Optionally later: a self-gating Waybar warning fed by the
+same script. **Verify:** V2 — a VM check with an induced failure.
+
+### 11. State-file validation & friendly errors
+New; "the user never has to master Nix" must include *error messages*.
+A hand-edited theme-state.json (trailing comma, wrong type, unknown
+theme slug) today surfaces as a raw Nix eval stack. Add (a) `nomarchy-
+theme-sync validate` + validate-before-write on every set/apply; (b) an
+eval-time schema assertion in `theme.nix` whose message says the field,
+the problem, and the fix in plain language. **Verify:** V1 + a corpus of
+broken-state fixtures round-tripped through validate; V2 if cheap.
+
+### 12. Screen recording in the Capture submenu
+New; screenshots ship, recording doesn't — a standard workstation need.
+Extend `nomarchy-menu capture`: record region/full → `wl-screenrec`
+(fallback `wf-recorder`), saved next to Screenshots, with a self-gating
+Waybar recording indicator that stops the recording on click (the only
+sane "stop" surface). Optional audio toggle. Parity rule applies.
+**Verify:** V1 + `bash -n`; V2 headless if the software-GL recipe
+supports it, else V3 queue.
+
+### 13. Small niceties batch (one slice per iteration)
+Each is a small, self-contained polish item in the existing patterns:
+- **Idle-inhibit (caffeine) toggle:** Waybar `idle_inhibitor` module
+  (blocks hypridle lock/suspend during video/presentations) + summer
+  whole-swap parity + cheatsheet mention.
+- **Low-battery notifications:** the bar colors at 25/10% but nothing
+  *notifies*; gate on `power.laptop` (poweralertd, or a small upower
+  watcher consistent with how the bar reads state).
+- **Color picker:** `hyprpicker` → clipboard as a Tools › entry +
+  `SUPER+CTRL` bind; pairs naturally with theme work.
+
+### 14. Automated upstream lock bumps (maintainer CI, slices b+c) `[big]`
+ROADMAP § Automated upstream lock bumps — the scheduled half, after
+NOW#2 lands: weekly job runs `nix flake update` (within pinned release
+branches) → full check suite → lands on `main` on green; `v1` promotion
+stays human. Plus the fast-lane note for security bumps.
+
+### 15. Display profiles — docked/undocked switching
 ROADMAP § Display / monitor management, remaining: true profile
 switching of the *same* outputs (multi-layout toggles, beyond
 per-output hotplug rules), optionally workspace-to-monitor binding.
 Design first (state-file shape, menu surface) — write the plan into
 this entry before coding.
 
-### 8. Greeter theming from the JSON
+### 16. Greeter theming from the JSON
 ROADMAP § Greeter. tuigreet themed from theme-state.json at system
 rebuild (same model as Plymouth's tint). Scope: tuigreet only (no SDDM).
 
-### 9. Launch-or-focus UX scripts
+### 17. Launch-or-focus UX scripts
 ROADMAP § launch-or-focus. Hyprland dispatch scripts: a bind launches an
 app or focuses its existing window. Curate which apps get binds;
 cheatsheet entries via keybinds.nix.
 
-### 10. "nomarchy" control center + first-boot welcome `[big]`
+### 18. "nomarchy" control center + first-boot welcome `[big]`
 ROADMAP § control center. A single front-end over the common toggles on
 the same `nomarchy-theme-sync` surface, + a first-boot guided
 "pick your theme / essentials" flow. Needs a design pass (TUI vs GUI)
-→ write options into Decisions before implementing.
+→ write options into Decisions before implementing. Note: items 9–11
+(rollback menu, doctor, validation) are natural panels of it — design
+them as composable commands, not dead ends.
 
-### 11. Look & Feel menu category
+### 19. Look & Feel menu category
 ROADMAP § Menu system, remaining: group Theme + night-light (+ wallpaper
 cycle, future appearance toggles) under a Look & Feel submenu once it
 earns ≥3 entries — keep the root at six.
@@ -116,11 +210,14 @@ earns ≥3 entries — keep the root at six.
 - **Night-light geo mode**: lat/long auto sunset/sunrise (means wlsunset).
 - **Per-theme icon overrides** / more icon packs (ROADMAP § Icon themes).
 - **MIPI/IPU software-ISP camera** support (no-UVC machines).
+- **OCR screenshot-to-text**: a Capture › entry (grim region → tesseract
+  → clipboard) — cheap once recording (#12) reshapes the submenu.
 - **Auto-timezone Waybar tooltip** showing the detected zone (optional).
 - **VPN exit-node richer display** (country/city) (optional).
 - **NixOS release bump → v2** `[human]`: deliberate, hand-edited, never
   automated; the previous attempt was discarded (2026-06-22) over a
-  Hyprland OOM blocker — see MEMORY.md before retrying.
+  Hyprland OOM blocker — see MEMORY.md before retrying (NOW#3 should
+  also soften that blocker class).
 
 ## PROPOSED (agent suggestions — await human triage)
 
@@ -140,3 +237,10 @@ decide.
 - **Docs site vs Markdown-in-repo** (from the docs-review item).
 - **Control center form factor:** TUI (gum/ratatui-style) vs GUI vs
   "the rofi menu *is* the control center, just add a first-boot flow".
+- **zram swap:** faster under pressure and pairs with NOW#3, but it
+  interacts with the hibernation-swapfile story (resume device/priority
+  ordering) — adopt, adopt-with-hibernation-guard, or skip?
+- **Default browser:** the template comments Firefox out; item #8's mime
+  defaults need *something* to point `text/html` at — ship a browser
+  active in the suite, or leave browserless-by-default and let mime
+  defaults degrade?

agent/JOURNAL.md

@@ -17,6 +17,23 @@ Template:
 
 ---
 
+## 2026-07-04 — Backlog revision pass (human-requested)
+- **Task:** Bernardo asked for a philosophy-aligned revision of BACKLOG.md
+  ("I'm sure I'm forgetting important items").
+- **Did:** verified guessed gaps against the tree first (GC/optimise/boot
+  limit + all 21 previews already ship — dropped those ideas). Added the
+  confirmed gaps: CI-on-push promoted to NOW#2 (agents push to main now),
+  memory-pressure protection NOW#3 (nothing mitigates OOM; the release
+  bump died to one), viewers+mime defaults #8, update/rollback UX #9,
+  nomarchy-doctor #10, state-file validation #11, screen recording #12,
+  niceties batch #13 (idle-inhibit, low-battery notify, hyprpicker), OCR
+  in LATER; recovery runbook folded into the docs item; zram + default
+  browser added to Decisions.
+- **Verified:** V0 (docs-only).
+- **Pending:** Bernardo to sanity-check the new NOW ordering, esp. CI at
+  #2 and the two new Decisions.
+- **Next suggestion:** unchanged — NOW#1 (opt-in auto-commit).
+
 ## 2026-07-04 — Bootstrap the loop infrastructure (this commit)
 - **Task:** create `agent/` (human-requested): LOOP/GOALS/BACKLOG/
   CONVENTIONS/MEMORY/HARDWARE-QUEUE/JOURNAL, root CLAUDE.md, README +