chore(agent): sync-sweep rule on task completion + apply it; zram user docs
All checks were successful
Check / eval (push) Successful in 4m45s

New standing rule (LOOP.md §5 step 4, echoed in AGENTS.md): when a task
ships, grep its number/feature name across agent/ and docs/ and update
or delete every cross-reference it made stale, in the same commit —
including pruning checked-off [x] HARDWARE-QUEUE entries whose outcome
is recorded (journal/ROADMAP; git history is the archive).

First application: BACKLOG PROPOSED groomed (the auto time-of-day theme
pitch was stale — shipped as #79; shipped/promoted placeholder lines
removed; v1.0 pointer rewritten; FUTURE promoted-stub dropped);
HARDWARE-QUEUE pruned of 29 checked entries (363→253 lines) with
dangling references reworded and the prune rule documented in its
header.

Also closes the zram user-doc gap: README §3 now documents the zram
default (zstd/50%/prio 100), hibernation working out of the box on new
installs, and the MIGRATION.md runbook for existing machines.

Verification: V0 (docs/meta only).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Bernardo Magri
2026-07-11 09:20:54 +01:00
parent 5ef66c242e
commit 4c656b1e73
6 changed files with 49 additions and 176 deletions

View File

@@ -36,6 +36,10 @@ git-tracked in `agent/`.
- **Conventions** (`agent/CONVENTIONS.md`): in-flake state, menu
placement, Waybar parity with whole-swaps, toggle-vs-package discipline,
template as SoT for opt-in comments (`templates/downstream`).
- **Sync sweep on completion** (`agent/LOOP.md` §5): when a task ships,
update or delete every cross-reference it made stale — BACKLOG
pitches/pointers, HARDWARE-QUEUE entries, docs — in the same commit.
No stale items, no unsynced information.
- **Git:** direct commits on `main`, pushed; **`v1` is human-only** —
never touch it. Never `nix flake update` unless the task is a lock bump.
No formatter — match aligned hand-formatting.

View File

@@ -330,6 +330,14 @@ the offending process (with a desktop notification) instead of freezing
the desktop — process-level on purpose, since a Hyprland session is one
cgroup and systemd-oomd would kill all of it (oomd is disabled
accordingly). Opt out with `services.earlyoom.enable = false;`.
**`zramSwap`** is also on by default (zstd, 50% of RAM, priority 100):
day-to-day memory pressure pages into compressed RAM instead of the
disk, keeping the disk swapfile free for **hibernation** — the installer
creates a RAM-sized encrypted swapfile and wires `resume`, so
Power Hibernate works out of the box (swap size 0 at install = no
swap). Opt out with `zramSwap.enable = false;`; to add hibernation to a
machine installed before it existed, follow
**[docs/MIGRATION.md](docs/MIGRATION.md)** § Enabling hibernation.
## 4. How theming works

View File

@@ -95,9 +95,6 @@ that label is online (Gitea queues forever otherwise).
pass: reformat the tree once, document in CONVENTIONS, optional CI
check. **Not** the queue head — no drive-by reformats until that pass.
### Hibernation + zram
**Promoted → NEXT #76** (2026-07-10).
## PROPOSED (agent suggestions — await human triage)
*Agents: append here with a one-paragraph pitch (what/why/cost). Do not
@@ -108,67 +105,15 @@ high-ROI, etc.) live in the journal + ROADMAP — not here.*
### Product / day-2
_(Doctor hibernate/sleep section → promoted to **NEXT #77** 2026-07-10.)_
_(Battery charge-limit instant → shipped 2026-07-10; V3 PASS Latitude
5310: Custom charge type + live menu + unplug re-apply.)_
_(Portal/Flatpak IR camera → **#71** docs (a); (b)/(c) still need T14s.)_
_(Post-install hardware hints residual → **#73**.)_
_(Look & Feel submenu → already shipped (Theme / wallpaper / night light);
2026-07-10: Reset wallpaper (auto) row; root stays six.)_
- **NVIDIA first-class options** — **deferred past v1** (Bernardo
2026-07-10). Keep #59 commented install guidance; no
`nomarchy.hardware.nvidia.*` until a hybrid maintainer + queue.
### 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
- **Auto time-of-day theme pair** (`VISION § D`) `[big]` — no scheduled
light/dark theme switch exists today (only night-light gamma via hyprsunset
+ wallpaper `bg auto`). Let a user pair two shipped themes (e.g.
summer-day ↔ summer-night) and switch on a schedule/sunset through the
**existing** engine — a systemd timer running `nomarchy-theme-sync apply
<slug>` — staying one theme engine (GOALS: no second pipeline). Split
before starting: (a) state schema for the pair + schedule, (b) the timer/
hook, (c) menu surface. Cost: multi-slice; verify each `apply` still bakes
one clean generation. (Verified 2026-07-10: no time-of-day/auto-theme
scheduler in the tree.)
_(#52 residual ANSI → **#68** ✓.)_
_(Fidelity / hierarchy nits → **#67** ✓.)_
_(Import pipeline hierarchy → **#70** ✓.)_
_(audit-theme-design identity exemptions → **#69** ✓.)_
_(summer-day/night pair polish + status CSS + preview recapture →
shipped 2026-07-10: JSON SoT, status states, theme-shot previews for
executive-slate + neon-glass.)_
_(Identity taste retunes + hand `btop.theme` for white/vantablack/lumon/
hackerman/matte-black/miasma/neon-glass/boreal/executive-slate →
shipped 2026-07-10.)_
### Docs / narrative
_(Omarchy migrant one-pager → shipped 2026-07-10 as **#78**:
`docs/OMARCHY.md` — config-model shift, install, bindings, theming,
packages, update/rollback; verified commands/slugs/binds.)_
### v1.0 pointer
See **VISION**. Shipped: doctor hibernate #77, Omarchy migrant doc #78.
Open PROPOSED: auto time-of-day theme pair (`§D`, big); NVIDIA wrappers
deferred past v1; IR portal (b)/(c) hardware. Browser default = Chromium;
power = PPD.
See **VISION**. Open PROPOSED: NVIDIA wrappers deferred past v1; IR
portal (b)/(c) need T14s hardware (HARDWARE-QUEUE § T14s). Standing
calls: browser default = Chromium; power backend = PPD.
## Decisions `[human]`

View File

@@ -3,27 +3,14 @@
Everything shipped at V1/V2 whose final verification needs real hardware.
Agents **append** (newest at the bottom of a section) with exact steps;
Bernardo runs them and either checks off (`[x]` + date + verdict) or files
the failure as a NOW bug in BACKLOG.md. Machines: the **AMD dev box**
(Ryzen AI laptop: AMD + fingerprint + NPU), the **Latitude 5310/5410**
(Intel QA — 2026-07-10 session on **5310**), the **T14s** (webcam case).
the failure as a NOW bug in BACKLOG.md. Checked-off entries are **pruned**
on the next sync sweep (LOOP.md §5) — outcomes live in the journal/ROADMAP;
git history is the archive. Machines: the **AMD dev box** (Ryzen AI
laptop: AMD + fingerprint + NPU), the **Latitude 5310/5410** (Intel QA),
the **T14s** (webcam case).
## Any machine (dev box is fine)
*2026-07-10 Latitude 5310 session (Bernardo) — ticks below marked PASS from
that run; leftover open items still need a pass.*
- [x] **Unfree CLI default (2026-07-10)** — PASS (Bernardo, Latitude).
- [x] **Waybar icon+percentage spacing (2026-07-10)** — PASS after double-pad
(volume high / keyboard / battery no longer kiss text; unified clock).
- [x] **Calendar on unified clock (2026-07-10)** — PASS (Bernardo).
- [x] **Rofi menu case-insensitive filter (2026-07-10)** — PASS: SUPER+M
`sys` → System; apps/drun already fine.
- [x] **Charge-limit live apply (2026-07-10)** — PASS after Custom type fix
(`45c584d`): menu 60/90/80 writes sysfs; toast; no rebuild needed.
Adaptive was ignoring the cap while reporting end=80.
- [x] **#41 float classes** — PASS polkit float+same-ws (Latitude); portal
rules shipped (`xdg-desktop-portal-gtk`). OpenFile file-picker confirmed
floating on hardware (Bernardo, 2026-07-10) — #41 fully closed.
- [ ] **#55 fingerprint enroll on real reader** — with
`nomarchy.hardware.fingerprint.enable` and a physical reader: System
Fingerprint Enroll a finger; List shows it; Verify succeeds; optional
@@ -34,7 +21,8 @@ that run; leftover open items still need a pass.*
charge-limit oneshot writes the threshold, System Battery limit
and Power profile rows appear, Waybar power-profile module shows,
doctor charge-limit section runs. On `BAT0`-only machines this is
a no-op (already covered by existing charge-limit re-apply item).
a no-op (charge-limit re-apply passed on `BAT0` — Latitude
2026-07-10).
- [ ] **btop theme fidelity (#52 residual)** — softGL theme-shot cannot
open Ghostty, so the hand `btop.theme` assets were only guest-file
asserted (main_bg / inactive_fg keys) + desktop/bar rendered for
@@ -43,9 +31,6 @@ that run; leftover open items still need a pass.*
confirm backgrounds/text match the theme (esp. rose-pine Dawn light
bg `#faf4ed`, vantablack near-black `#0d0d0d`, catppuccin Mocha
`#1E1E2E`). One pass cycling those five is enough.
- [x] **Battery charge limit re-apply on unplug** — PASS (Latitude
2026-07-10): with limit 80, unplug ~3s + plug; sysfs stays 80
(delayed oneshot + Custom type).
- [ ] **SSH_AUTH_SOCK for GUI clients** — after relogin, launch a GUI git
client (or `rofi`-launched terminal-less app) and confirm it reaches
gpg-agent's SSH socket without an interactive shell parent.
@@ -58,17 +43,6 @@ that run; leftover open items still need a pass.*
own bell-off glyph, executive-slate/boreal use 󰂛). The glyph itself
already renders (DND uses it); this only confirms swaync emits the
`inhibited-*` class and the bar routes it.
- [x] **Night-light full cycle** — first menu enable rebuilds + hyprsunset
starts; later toggles are instant (no rebuild); an *off* survives
reboot (ExecCondition); stopping hyprsunset restores gamma.
— 2026-07-04 Bernardo: PASS enable/disable on hardware
(off-survives-reboot + gamma-restore not explicitly checked).
- [x] **Auto-timezone** — enable from the menu; confirm geoclue finds the
zone, `/etc/localtime` updates, and the Waybar clock refreshes
(SIGUSR2 watcher) — also after a manual `timedatectl set-timezone`.
— 2026-07-04 Bernardo: PASS — enabled from the menu, `timedatectl`
shows Europe/London (the manual set-timezone re-trigger wasn't
exercised).
- [ ] **Keyboard layout cycle bind** — with a comma layout (e.g.
`nomarchy.keyboard.layout = "us,de"`), SUPER+SHIFT+K cycles the
focused keyboard's layout, the Waybar `󰌌` indicator follows, and
@@ -76,10 +50,8 @@ that run; leftover open items still need a pass.*
no comma layout was configured, so the bind wasn't rendered (the
gate working as designed, not a failure) — retest after setting a
comma layout + rebuild + relogin. The SUPER+? no-op found en
route IS a real bug → BACKLOG item 26 (fix shipped — see the
dedicated SUPER+? entry below).
- [x] **SUPER+? opens the cheatsheet** (item 32 re-fix) — PASS (Latitude
2026-07-10): SUPER+? opens cheatsheet; row shows `SUPER + ?`.
route was a real bug → BACKLOG item 26 (fix shipped; SUPER+?
cheatsheet PASS on Latitude 2026-07-10).
- [ ] **swaync readable on summer-day** (item 25 fix) — on summer-day
after `home-update`: `notify-send "title" "body text"` shows
readable body text; open the control centre (SUPER+N), hover a
@@ -99,42 +71,15 @@ that run; leftover open items still need a pass.*
(SUPER+? / root menu Keybindings) now ends in ↩ Back and
returns to the root picker; spot a couple of submenus (Display,
VPN Tailscale) still Back correctly after the audit pass.
- [x] **Network menu has no blank rows** (item 22 fix) — PASS (Latitude
2026-07-10 Round 4): Tools Network, no empty separator rows.
Residual hidden-SSID nameless row still possible (not a config bug).
- [ ] **Keyboard hotplug picker (re-verify after in-flake graduation)**
plug an external keyboard post-login, pick a layout in rofi, confirm
it applies per-device only, persists in `settings.keyboard.devices`,
and graduates into a `device{}` block on the next rebuild.
- [x] **Snapshots restore/rollback** — ⚠ PRECONDITION: update to main ≥
a47aa3a and RELOGIN first (the polkit agent starts with the session).
Bernardo's 2026-07-04 Latitude findings 5/6 ("btrfs-assistant still
crashes", "menu snapshots shows nothing") match the PRE-fix behavior
exactly: no agent → pkexec fails silently (= menu does nothing), and
a direct unprivileged run crashes (= the libbtrfsutil bug). If either
still reproduces ON THE FIXED BUILD after relogin, reopen BACKLOG
item 4 as [stuck]. Then: `nomarchy-menu snapshot` now opens
the **btrfs-assistant GUI**: a *themed* polkit prompt must appear
(hyprpolkitagent — first on-hardware outing) and the GUI must open
as root. Also exercise the fzf fallback in a terminal
(`sudo nomarchy-snapshots`): browse/diff, restore a file
(`undochange`), and a root-config rollback behind the typed-`yes`
gate. Bonus check: any other pkexec flow now prompts instead of
silently failing. — 2026-07-04 Bernardo: PASS on the fixed build —
polkit prompt appears, GUI opens as root, fzf fallback works.
Restore/rollback not exercised → residual item below.
- [ ] **Snapshots restore + rollback exercise** (residual from the item
above — the GUI/polkit half passed 2026-07-04): in
- [ ] **Snapshots restore + rollback exercise** (residual — the
GUI/polkit half passed on hardware 2026-07-04, a47aa3a): in
`sudo nomarchy-snapshots`, restore a single file (`undochange`)
and walk a root-config rollback up to (or through) the
typed-`yes` gate.
- [x] **Caffeine toggle (item 13 slice)** — PASS (Latitude 2026-07-10):
bar cup toggles 󰾪↔󰅶; idle hold smoke OK (full 5min lock wait not
re-timed this session).
- [x] **Screen recording (item 12)** — PASS (Latitude 2026-07-10 Round 3):
region/screen record → playable mp4; bar ⏺; click ⏺ stops.
- [x] **Doctor (item 10)** — PASS (Latitude 2026-07-10 Round 4): System
Doctor sheet opens; healthy machine mostly ✔/.
- [ ] **Rollback menu (item 9b)** — after a couple of theme changes,
menu System Rollback: recent desktop generations listed
(newest marked current); picking an older one opens a terminal,
@@ -162,14 +107,6 @@ that run; leftover open items still need a pass.*
- [ ] **Visual theme pass** — live ISO: all six identity themes (bars) +
the four authored rofi `.rasi` (nord/retro-82/lumon/kanagawa) look
right, not just parse.
- [x] **Auto-commit on a real machine** — System Auto-commit toggles on
(row shows state, notification fires); a theme apply from SUPER+T then
shows a `nomarchy: apply theme …` commit in `~/.nomarchy` (`git log`);
unrelated dirty files in the checkout stay uncommitted; toggle off is
itself the last commit. Also: the "Auto timezone (on/off)" row label
now reflects the real state (the `= true` comparison fix).
— 2026-07-04 Bernardo: PASS — theme changes committed and the
toggle self-committed.
- [ ] **Display profiles, slice a (item 15)** — declare two
`nomarchy.displayProfiles` (e.g. docked disables eDP-1 + arranges
the externals; undocked re-enables it), `home-update`, then:
@@ -204,9 +141,6 @@ that run; leftover open items still need a pass.*
(tooltips, fastfetch labels) is visible on summer-day +
flexoki-light, kanagawa floats are lighter than the bg (upstream
sumiInk4). Anything that reads worse than before → reopen 28b.
- [x] **Clock zone tooltip** — PASS (Bernardo, Latitude 2026-07-10):
hover shows date + zone (single chrono block fix `0834038`); calendar
is click-to-calcurse, not in the tooltip.
- [ ] **Doctor bar tripwire (LATER item)** — with everything healthy
the bar shows nothing; `systemctl --user start doomed`-style
induced failure → within ~5 min a red appears (tooltip lists
@@ -246,30 +180,10 @@ that run; leftover open items still need a pass.*
draining. (Crossing logic VM-verified — this checks the real
swaync rendering in a session.)
- [x] **Battery charge-limit toggle** (iteration #55 / menu path) — PASS
(Latitude 2026-07-10): Power + System Battery limit presets write
state + sysfs (Custom type). Gum control-center path not re-checked
(limit moved to rofi).
- [x] **Waybar hides under fullscreen video** (item 30) — PASS (Latitude
2026-07-10): fullscreen video covers bar; exit restores.
- [x] **Battery limit in rofi System** (iteration #64, item 36a) — PASS
(Latitude 2026-07-10): presets apply live; sysfs matches.
- [x] **Config dialogs float** (item 41 residual) — PASS (Latitude
2026-07-10 Round 4): polkit + config dialogs float; portal rule
shipped; OpenFile file-picker confirmed floating on hardware
(Bernardo, 2026-07-10) — #41 fully closed.
- [x] **Right-click volume → floating mixer** (iteration #62, item 35) —
PASS (Latitude 2026-07-10): pwvucontrol floats+centered after
packaging with waybar.
- [x] **Window focus on arrows** (iteration #61) — PASS (Latitude
2026-07-10): SUPER+arrows move focus; SUPER+? shows them.
- [ ] **Audio opens in Amberol** (iteration #60, item 37) — after
`nomarchy-home`: double-click an mp3/flac/ogg (or `xdg-open song.mp3`)
→ it opens in Amberol, not mpv; video files still open in mpv.
(`xdg-mime query default audio/mpeg` → io.bassi.Amberol.desktop.)
- [x] **Capture-to-file keybinds** (iteration #59, item 38) — PASS
(Latitude 2026-07-10): Print / SHIFT+Print / CTRL+Print + Capture
menu; clipboard path toasts after fix.
- [ ] **rofi menu polish** (iteration #58, item 39 + #56/#57 34/40) —
after `nomarchy-home`: (a) menu System Power profile shows a
colored icon per profile (performance/balanced/power-saver), not
@@ -277,13 +191,6 @@ that run; leftover open items still need a pass.*
shows a single arrow, no double; (c) on this single-monitor box,
System Display → pick a resolution → Back returns to System
(not back into the same resolution list).
- [x] **Combined power menu** (iteration #67, item 36b) — PASS (Latitude
2026-07-10 A1/A2): battery + power-profile icons open same Power
menu; profile switch + charge limit work.
- [x] **Calendar on the unified clock click** (iteration #68 + 2026-07-10
bar polish) — PASS (Bernardo, Latitude 2026-07-10): unified clock,
calcurse floats centered.
- [ ] **Screenshot annotation (satty)** (iteration #73) — after `nomarchy-home`:
hit SUPER+SHIFT+Print (or Tools ▸ Capture ▸ Annotate region) → a region
select (slurp) appears, then the `satty` UI opens in fullscreen with the
@@ -333,20 +240,6 @@ that run; leftover open items still need a pass.*
hardware-only.)
## Latitude 5310 / 5410 only
- [x] **Waybar theme-switch resilience** (finding #1 re-test, needs main ≥
the supervisor commit + relogin) — switch themes repeatedly (incl.
summer-day/night whole-swaps): the bar restarts cleanly each time;
if anything kills it, it's back within ~a second. `pgrep -f
nomarchy-waybar` shows the supervisor. — 2026-07-04 Bernardo:
PASS — theme switches clean; pkill respawn so fast the bar never
visibly disappears.
- [x] **Media keys + gestures** (from dccceb4) — volume/brightness keys
drive the OSD; touchpad gestures work. — 2026-07-04 Bernardo:
PASS, volume/brightness keys and touchpad gestures all working.
- [x] **2026-07-10 Latitude 5310 QA batch** — PASS core desktop smoke
(charge Custom type, bar, menus, capture, polkit workspace, lifecycle
CLIs). Not a full v1 promotion gate — residual open items remain
above (themes eyeball, greeter, display profiles, Amberol, satty, …).
- [ ] **v1 QA batch on-hardware pass** (583708d batch was QEMU-verified) —
general smoke before the next `main → v1` promotion (broader than
the 2026-07-10 session; include theme/ISO/greeter leftovers).

View File

@@ -19,6 +19,21 @@ Template:
---
## 2026-07-11 — Sync-sweep rule + grooming + zram user docs (human-requested)
- **Task:** Bernardo: groom stale items and codify the check so they don't
recur; close the zram user-doc gap.
- **Did:** LOOP.md §5 gains step 4 **Sync sweep** (grep item/feature across
agent/+docs/ on ship; prune recorded `[x]` queue entries) + an AGENTS.md
rule line. Applied it: BACKLOG PROPOSED pruned (auto-theme pitch was
stale — shipped as #79; shipped/promoted placeholders removed; v1.0
pointer rewritten; FUTURE promoted-stub dropped). HARDWARE-QUEUE pruned
29 checked `[x]` entries (363→~250 lines), dangling refs reworded,
prune rule in header. README §3 now documents the zram default +
hibernation out-of-the-box + MIGRATION pointer.
- **Verified:** V0 (docs/meta only) — grep sweep for dangling refs clean.
- **Pending:** night-light geo mode next (same session).
- **Next suggestion:** wallpapers artifact split (LATER, decided).
## 2026-07-11 — Vendor-neutral agent docs restructure (human-requested)
- **Task:** Bernardo: de-vendor the agent instructions (multi-model repo),
clean stale files, better docs/agent/.claude structure.

View File

@@ -132,6 +132,14 @@ the reusable recipes).
file's rules).
2. Append a `JOURNAL.md` entry (template in that file).
3. Queue any V3 checks in `HARDWARE-QUEUE.md`.
4. **Sync sweep.** Grep the item's number and feature name across
`agent/` and `docs/` and update or delete every cross-reference the
ship made stale: the PROPOSED pitch that spawned it (and BACKLOG's
v1.0 pointer), HARDWARE-QUEUE entries it supersedes, ROADMAP/README/
docs mentions of the old behavior. While there, prune checked-off
`[x]` HARDWARE-QUEUE entries whose outcome is already recorded
(journal/ROADMAP — git history is the archive). A shipped item must
leave no stale pointer behind; the sweep rides in the same commit.
### 6. Pace (self-paced runners only)
Under `/loop`, continue to the next iteration while tasks remain