Nomarchy/agent/BACKLOG.md

# Backlog — the prioritized task queue

**This is the only executable work list for agents.** Product themes and
v1.0 intent live in [`docs/VISION.md`](../docs/VISION.md); design history
in [`docs/ROADMAP.md`](../docs/ROADMAP.md); map in
[`docs/README.md`](../docs/README.md) and [`agent/README.md`](README.md).

**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 (and/or a note in VISION)
  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 (include
  `VISION § …` or `ROADMAP § …` when relevant); only Bernardo moves items
  *out* of PROPOSED into the tiers.

---

## NOW

*(empty — NEXT's top item is the queue head)*

## NEXT

### 64. MIGRATION.md snapshot layout vs installer
Installer creates disko `@snapshots` → `/.snapshots` and a first-boot
oneshot for nested `/home/.snapshots`. MIGRATION still speaks of
top-level `@home-snapshots` (TuringMachine vocabulary). One paragraph
clarifying installer layout vs migration machines. Cost: docs only; V0.

### 65. Installer soft gap: chown flake dir
`chown -R 1000:100` on the generated flake assumes first-user UID/GID.
Use the real install username’s uid/gid (or `id` after user create).
Cost: small; V0–V1.

### 66. Fail-closed / friendlier theme-state errors in `mkFlake`
Missing or invalid `theme-state.json` should fail early with a pointer
to schema/docs, not a raw `readFile`/`fromJSON` stack. Related:
`settings.displayProfile*` defaults; unknown border role. Cost: medium
lib UX; V0–V1.

### 67. Theme fidelity / hierarchy nits (popular ports)
gruvbox Material vs classic name+btop split; nord inverted subtext/text;
tokyo-night btop warm fg; ethereal surface=base; retro-82 surface
darker than base; ristretto subtext=text + btop bg drift; flexoki-light
bright-black. Cost: small JSON/btop each; V0 contrast + V1.

### 68. #52 residual ANSI
**vantablack** `ansi[8]` still `#fdfdfd` (diverges from `muted #666666`);
**osaka-jade** `ansi[3]` still warn-green `#459451` while `warn` is
`#E5C736`. Treat as fidelity bugs (align with muted/warn). Cost: tiny
JSON; V0 contrast.

### 69. audit-theme-design identity exemptions
Document expected CVD/hue noise for white/vantablack/lumon/hackerman/
matte-black/miasma so audits don’t “fix” identity into traffic lights.
Optional special-case in the report script. Cost: docs or small script; V0.

### 70. Import pipeline hierarchy when ANSI 0==8
`tools/import-palettes.py` maps surface←color0, overlay←color8; when
0==8 (gruvbox, everforest) surface=overlay; light themes get sludge
mantle. Allow role overrides independent of ANSI; don’t re-import
without a hierarchy pass. Cost: tool + convention; V0.

### 71. Portal/Flatpak IR camera — document (a)
Ship the recommended path only: document that the WirePlumber *v4l2*
IR-hide does not cover libcamera/Flatpak pickers (ROADMAP § Webcam).
Leave (b)/(c) engineering for a T14s session. Cost: docs; V0.

### 72. Installer ↔ template SoT — CI parity check
Optional pure check that the install share ships the same template
files as `templates/downstream`. Cost: small tool + flake check; V0.

### 73. Post-install hardware hints residual
#43 shipped Firmware MOTD/tip. Still open: fingerprint + doctor
one-liners (once or until dismissed). Cost: small greeter/MOTD/notify;
V1–V2.

### 74. Unattended-install test matrix
`test-install.sh` always LUKS+swap; add (or document) no-swap and
explicit no-LUKS paths via env flags only. Cost: script + KVM time; V2.

### 75. Installer template SoT — V2 install after ISO rebuild
HM pre-activate now pulls starter packages (larger closure). Run
`test-install.sh` (or equivalent) on a rebuilt live ISO and confirm
first boot still themed. Cost: ISO + KVM; V2.

### 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
that later upgrades the bump gate from eval-only to the full suite.

### 41. Floating-window audit — residual GTK portal class `[blocked:hw]`
(Raised by Bernardo, 2026-07-07 — item 11.) Conservative cut + 2026-07-10
slice shipped: mixer, blueman, system-config-printer, calendar,
**hyprpolkitagent** + **pinentry-qt** (classes from package app-id
strings; softGL capture harness could not materialize dialogs).
**Still open:** GTK file-chooser portal (`xdg-desktop-portal-gtk`) —
class not discoverable headlessly. On hardware: open a portal file
picker, `hyprctl clients`, append float/center rules if needed; confirm
polkit/pinentry/blueman actually float.

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

*Open work only. Shipped exam/A–C items (#47–#63, #14, #52 theme
high-ROI, etc.) live in the journal + ROADMAP — not here.*

### Product / day-2

- **Battery charge-limit — make the toggle instant** `[blocked:hw]`
  Menu/CC write `settings.power.batteryChargeLimit` but need a rebuild.
  Instant path: udev group-writable `charge_control_end_threshold` on
  system batteries + live `echo` alongside state persist. Decide first
  whether a local user may set the charge cap. Cost: medium; hw confirm.

_(Portal/Flatpak IR camera → **#71** docs (a); (b)/(c) still need T14s.)_

_(Post-install hardware hints residual → **#73**.)_

- **Look & Feel submenu** (ROADMAP optional) — night-light, wallpaper
  cycle, blur/gaps with Theme; root stays six entries. Product call.

- **NVIDIA first-class options** `[big]` `[blocked:hw]` — thin
  `nomarchy.hardware.nvidia.*` only with hybrid maintainer + queue.
  Prefer shipped #59 commented guidance until then.

### Installer / template

_(Installer ↔ template SoT CI → **#72**; V2 install → **#75**.)_
_(Installer chown flake dir → **#65**.)_
_(MIGRATION.md snapshot layout → **#64**.)_
_(Unattended-install test matrix → **#74**.)_
_(Friendlier mkFlake theme-state errors → **#66**.)_

### Theme polish

_(#52 residual ANSI → **#68**.)_
_(Fidelity / hierarchy nits → **#67**.)_
_(Import pipeline hierarchy → **#70**.)_
_(audit-theme-design identity exemptions → **#69**.)_

- **summer-day / summer-night pair polish** — waybar CSS vs JSON dual
  SoT; night `subtext`=`muted`=`overlay`; day/night font + battery
  threshold + VPN pill drift. Pick JSON as SoT (or document EF split).
  Cost: CSS/JSON; V3.

- **summer-\* CSS status module states** — missing `.on` / `.available`
  / `.recording` polish vs boreal/generated. Cost: CSS; V3.

- **theme preview recapture nicety** — executive-slate + neon-glass
  previews are bare desktop+bar, not the floating-terminal composition
  of the other 21; optional identity `btop.theme`s. Cost: asset/V3.

- **Identity optional taste retunes** — white / lumon / hackerman /
  matte-black / miasma hierarchy or status L-steps only (no traffic-light
  forced on identity themes). Product call per theme.

### v1.0 pointer

See **VISION**. Remaining PROPOSED: charge-limit instant, Look & Feel,
NVIDIA first-class, summer-* / preview / identity taste polish.


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

- **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. The shipped
  mime defaults (item 8, done) point `text/html`/http(s) at
  `firefox.desktop` as *inert* entries — they activate the moment
  Firefox is installed and are skipped otherwise, so the remaining call
  is only: ship a browser active in the suite, or stay
  browserless-by-default?

- **Default power backend — PPD vs TLP:** (raised by Bernardo 2026-07-08:
  would TLP be more power-efficient, and should it be the default?)
  TLP does get more *idle* battery life, but only from device-level knobs
  PPD deliberately omits — PCIe ASPM, disk/NVMe link PM, USB autosuspend,
  runtime PM — which are the same knobs behind NVMe/USB flakiness that
  pillar 1 (rock-stable, never fight your machine) guards against.
  **Evidence (2026-07-08):** no credible hard-watt benchmarks exist — TLP's
  own maintainer declines to quote any ("measure on your hardware") and says
  PPD's power-saver gives *similar* savings under load; TLP's edge is
  idle-only (linrunner.de/tlp/faq/ppd.html — PPD covers a *subset* of TLP,
  "no settings to reduce consumption when the CPU is idle"). Our sibling
  distro **Omarchy** ran this exact experiment — a "replace Power Profiles
  with TLP for battery" guide — and the author **reverted to PPD** ("more
  headaches and weird issues"); Omarchy shipped PPD auto-switching instead
  (basecamp/omarchy#3907). PPD 3.4.0 now does AC/battery auto-switching,
  closing part of TLP's UX gap. **Cost of TLP-default:** TLP has no live
  D-Bus profile API, so the `powermgmt` menu + Waybar profile indicator +
  low-battery auto power-saver (all `powerprofilesctl`) would need a rework —
  it's not a one-line backend swap. **Agent rec (evidence, not a decision):
  keep PPD default;** chase battery via targeted low-risk tweaks (PCIe ASPM
  policy, battery-side EPP, the charge *start* threshold, PPD auto-switching)
  and keep TLP the documented one-line opt-in it already is
  (`nomarchy.system.power.backend = "tlp"`). Options: (i) status quo +
  targeted tweaks [rec]; (ii) TLP default (reworks the profile UX);
  (iii) nothing.