Nomarchy/agent/BACKLOG.md

# Backlog — the prioritized task queue

The forward-looking half of the old docs/ROADMAP.md, reworked as a queue
agents can execute. Detailed design notes and decision records stay in
`docs/ROADMAP.md` (referenced as "ROADMAP § <item>"); this file is *what's
next, in what order*.

**Rules:**
- Agents take the topmost actionable item (see LOOP.md). Finished items
  are **deleted** here — the journal + git log are the record; durable
  design notes get a ✓-entry in docs/ROADMAP.md if worth keeping.
- Item numbers are **stable IDs** — never renumbered or reused. A gap in
  the sequence means shipped (or dropped) work; new items take the next
  free number regardless of tier.
- Tags: `[blocked:hw]` needs real hardware (see HARDWARE-QUEUE.md) ·
  `[human]` needs Bernardo · `[stuck]` two failed attempts, needs help ·
  `[big]` must be split before starting.
- Agents may append to **PROPOSED** and **Decisions** freely; only
  Bernardo moves items *out* of PROPOSED into the tiers.

---

## NOW

*Items 21–26: real-hardware QA findings from the Latitude 5410
(Bernardo, 2026-07-04) — bugs found on metal outrank the queue.*

### 26. SUPER+? cheatsheet bind never fires on hardware
Reported (Latitude sweep #2): SUPER+? does nothing — the ? reaches the
focused terminal. Cause: keybinds.nix binds `$mod, question`, but
typing ? holds Shift, so Hyprland sees mods SUPER+SHIFT with keysym
`question` and its exact-modmask match skips a bind declaring SUPER
only (the "question already implies Shift" comment doesn't hold on
real input; headless V1/V2 never pressed the key). Fix: `$mod SHIFT,
question` (user-facing label stays SUPER+?); while there, audit the
bind list for other shifted keysyms (none today — letters carry
explicit SHIFT mods). Confirmed bind-only: `nomarchy-menu keybinds`
from a terminal opens the cheatsheet fine (Latitude, 2026-07-04).
**Verify:** V1 (rendered bind string in the HM generation); V3 retest
on the Latitude.

### 25. swaync text unreadable on summer-day (light-theme contrast)
Reported: on summer-day, notification/control-centre text is invisible
(contrast). Root cause (traced 2026-07-04): swaync.nix renders `.body`
as `@subtext` on `alpha(@base, 0.95)` — but in summer-day (and
flexoki-light) `subtext` *equals/≈ base* because those palettes use
`surface` as a dark contrast surface and `subtext` as text-*on*-surface,
not "dimmer text" (catppuccin-latte-style). summer-day also has
`surface == text` (#5c6a72), so `.widget-title > button`
(@surface bg, @text fg) is self-colored too. Fix direction: swaync.nix
should pair roles that contrast by construction — `muted` (dim-text
role in every palette) for body text on @base, and button fg that
contrasts @surface (`subtext` is arguably the *right* role there) —
or normalize the palette semantics across the light themes; audit the
other `@subtext`/`@surface` consumers (waybar css, rofi) for the same
mispairing before choosing. **Verify:** V1 + a contrast assert over all
themes (text≠bg for each swaync pairing); V2 themed-VM screenshot with
a `notify-send`; V3 re-check on the Latitude.

### 22. Network menu shows nameless/weird entries
Reported: `networkmanager_dmenu` lists entries with no names (likely
hidden-SSID APs rendered as blank rows, possibly other adapters/
duplicate BSSIDs). Investigate its config.ini surface for filtering,
or patch the list source; blank rows in a themed picker read as
breakage. **Verify:** V1 (config renders) — behavior needs Wi-Fi
hardware → V3 on the Latitude.

### 24. "Back" audit — every list menu ends in ↩ Back
Reported: some submenu items/tools still lack a Back option. The "Back
everywhere" pass covered the hand-rolled dmenu lists at the time; audit
what's been added since (VPN, Display, power-profile, printers…) and
the external/plugin modules (networkmanager_dmenu, rofi-pulse-select,
rofi-calc/emoji modi) — hand-rolled lists get the shared `back` helper;
external modi that can't take an injected row get documented as such
(and Esc always works). **Verify:** V1 + a grep-the-generated-script
audit listing which menus have/lack Back; V3 spot-check.

### 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; 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).

## NEXT

### 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.

### 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) in the
  GENERATED bar — summer-night already has one (reverse parity gap
  found 2026-07-04); add to summer-day too + 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 (the
checks-on-push workflow shipped; see item 20 for the runner status):
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. Note the current
runner is eval-only (no KVM) — a green bump run guards eval, not the VM
suite, until item 20's stretch runner exists.

### 20. KVM runner → VM suite in CI `[human]`
The remaining stretch of the CI item — checks-on-push is live and
**green** (run #58; runner = gitea/act_runner docker, eval tier).
Register a second runner on a host with `/dev/kvm` + nix (host-mode
label `nix-kvm`), then an agent uncomments the workflow's `vm-checks`
job: the `checks.*` VM suite + real toplevel/HM builds on every push
(also upgrades item 14's bump gate from eval-only to the full suite).

### 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.

### 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).

### 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.

### 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. Note: items 9–11
(rollback menu, doctor, validation) are natural panels of it — design
them as composable commands, not dead ends.

### 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.

## LATER

- **Wallpapers artifact split** (ROADMAP § Faster switches — decided,
  deferred): pinned `Nomarchy-wallpapers` input so a state write stops
  re-copying 86 MB. Follow-on: pre-built theme variants if switches are
  still slow after.
- **Installer round 2** (ROADMAP § Installer): multi-disk BTRFS RAID,
  impermanence, BIOS/legacy boot.
- **Boot-from-snapshot**: a systemd-boot equivalent of grub-btrfs.
- **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 (NOW#3 should
  also soften that blocker class).

## PROPOSED (agent suggestions — await human triage)

*Agents: append here with a one-paragraph pitch (what/why/cost). Do not
implement. Bernardo moves accepted items into a tier.*

- **Menu parity for downstream-flake options** (raised by Bernardo,
  2026-07-04, from the hardware sweep): anything the docs or the
  hardware queue ask a user to *hand-edit into the downstream flake*
  (`keyboard.layout` multi-layout, `power.batteryChargeLimit`,
  `updates.enable`, `services.printing`, …) should have a menu toggle
  instead — the in-flake-state philosophy already gives the menu a
  write-into-the-flake path, and night-light / auto-timezone /
  auto-commit prove the pattern (incl. rebuild-on-first-enable).
  Pitch: (a) an audit listing every user-facing `nomarchy.*` option vs
  its menu surface; (b) menu writers for the gaps, respecting the
  toggle-vs-package discipline (bare template packages stay hand-edits)
  and menu-placement convention (right submenu, root stays short).
  Values beyond booleans (layout lists, charge thresholds) need a small
  input UI per option. Cost: audit is one iteration; the writers a few
  more, sliceable per option.

- **Portal/Flatpak camera picker still lists the internal IR sensor**
  (ROADMAP § Webcam follow-up). The shipped IR-hide is a *WirePlumber
  v4l2* rule, but Flatpak/portal apps consume cameras via the
  **libcamera** path, where both sensors remain visible — a Flatpak
  Zoom user can still pick the black IR "camera". Options, roughly
  ascending cost: (a) do nothing — document it (portal camera support
  is still rare in practice); (b) a WirePlumber *libcamera* monitor
  rule disabling GREY-only nodes — needs verifying that libcamera
  monitor rules can match early enough (the v4l2 investigation found
  only `device.api` binds pre-rule, which is why surgical scoping
  failed before — same wall likely applies); (c) a libcamera
  configuration/udev quirk hiding the IR sensor at the libcamera layer
  itself. Cost: (b)/(c) need a T14s-style RGB+IR machine to verify →
  pairs with a hardware-queue session. Recommend (a) now, (b)
  investigated when the T14s is next available.

## Decisions `[human]`

Open calls only Bernardo can make; agents add options/evidence but never
decide.

- **Formatter adoption:** repo deliberately has none; `nixfmt-rfc-style`
  would flatten the aligned hand-formatting of ~33 files. Adopt or
  declare never?
- **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?