Nomarchy/agent/MEMORY.md

Memory — durable lessons, learned the hard way

Curated, not append-only: one line per fact, newest at the top of its section; delete entries that stop being true. Details usually live in a docs/ROADMAP.md decision record — pointer given as (§ item). Add a fact here the moment a debugging session teaches you something a future iteration would otherwise rediscover.

Testing & VM recipes

• Doctor float V2: THEME=<slug> nix build --impure -f tools/doctor-float.nix — softGL Hyprland, nomarchy-menu doctor, asserts class=com.nomarchy.doctor + floating + centered midpoints + screenshots (Kitty --class=…). SoftGL may still struggle with a GPU terminal; size can ignore percent windowrules if client geometry wins.
• theme-shot softGL may not start Kitty — btop.png is best-effort (usually identical to desktop). Guest asserts on ~/.config/btop/themes/nomarchy.theme prove baking; the TUI look is hardware/GL tier (HARDWARE-QUEUE).
• Waybar custom/doctor tripwire: status helper must invoke nomarchy-doctor by absolute store path (waybar's env can miss system PATH → command -v … || exit 0 self-hides forever); empty "text" also self-hides; strip ANSI before packing the tooltip; use signal 10 + format = "{}". theme-shot asserts class:bad + glyph and pokes RTMIN+10 before the desktop shot.
• tuigreet dies silently under runNixOSTest (even bare, no theme flag: greetd sits as "(greetd)" with no child, nothing in the journal — its stderr goes to the VT) — nixpkgs' own greetd test uses agreety instead. Greeter rendering is interactive-ISO/hardware tier; don't burn another session on a checks.greeter VM test.
• In VM tests pgrep -f PATTERN can match the test backdoor's own bash -c wrapper (the pattern is in its cmdline) — use pgrep -x or a [t]uigreet-style bracket pattern.
• Don't default a "timer/session" feature to V3 — most of it is VM-testable. A scheduled/session behaviour usually decomposes into a generic step already covered elsewhere (e.g. home-manager switch, exercised by every theme apply) and a specific decision (which theme, when). Stub the generic step (NOMARCHY_REBUILD=<marker> for theme-sync) and simulate time by moving the VM clock (date -s, timedatectl set-ntp false, time.timeZone = "UTC"), then assert the decision + state change headlessly. checks.auto-theme does exactly this for #79's sunset/sunrise. Only the literal timer-fires-on-OnCalendar is truly on-hardware, and systemd-analyze calendar validates that schedule. (I first mis-framed #79 as V3 — it's V2.)
• writeShellScriptBin scripts run set -euo pipefail (nomarchy-doctor, the menu, lifecycle CLIs). So a no-match grep inside $(…) (grep exits 1 → command-sub fails → abort) and a standalone cond && action (false cond → abort) both kill the script mid-run — the tell is output that stops before the final/verdict line with no error. Guard: … | grep … || true inside $(), cmd 2>/dev/null || echo 0 for captures, and if instead of && action. (#77 doctor hibernate section; caught by the checks.doctor VM test on first run.)
• A checks.* fixture CANNOT be a writeText/toFile state file read at eval time ("path … is not valid" — flake check's eval store won't realise it): extract the logic into a pure importable file and unit-test THAT (monitor-rules.nix / checks.display-profiles is the pattern).
• Hibernation reference (Latitude / Newton, BACKLOG #76): LUKS whole root BTRFS; @swap → /swap; file /swap/swapfile; boot.resumeDevice = LUKS root UUID; resume_offset from btrfs inspect-internal map-swapfile -r. Swap is encrypted with root (not a cleartext partition). No zram on that box yet — zram is additive for live pressure only. Installer already creates this when swapSize>0.
• CI (.gitea/workflows/check.yml) is eval-tier only (standing decision 2026-07-10): act_runner docker-compose on the Gitea VPS; no KVM there. Full VM suite is BACKLOG FUTURE #20, not NEXT — needs a separate nix+/dev/kvm runner. Container gotchas are in the workflow header (single-user Nix + nixbld users, sandbox=false for Stylix IFD, Nix pinned 2.31.5 vs lazy-trees, no JS actions past node20).
• The Gitea instance is 1.25.4 — on: schedule workflows are supported; bump.yml assumes the Actions token can push to main (standard Gitea behaviour, but unconfirmed until the first run lands).
• The git server is Gitea (gitea/act_runner via docker-compose), NOT Forgejo — workflows are read from .gitea/workflows/ (or .github/), never .forgejo/workflows/ (a whole push cycle was lost to that).
• Reusable headless VM harness: checks.* via runNixOSTest — existing examples to crib from: distro-id (boots + switch-to-configuration dry-activate), hardware-toggles (kernel cmdline/PAM assertions), battery-charge-limit (fake Mains adapter via test_power, real udev event burst while the oneshot is active; clean inactive result plus an InvocationID change proves coalesced AC re-apply). AC udev hooks for a settling oneshot must use start, never restart: USB-C docks emit event bursts and restarts SIGTERM the in-flight pass into start-limit-hit.
• Themed-desktop screenshots work headlessly: software-GL Hyprland (LIBGL_ALWAYS_SOFTWARE on virtio-gpu) + machine.screenshot() QMP dump — prototyped 2026-06-19, kept as the fallback for theme previews (§ Visual theme picker).
• Hyprland needs guest GL (virtio-vga-gl, gl=on) in interactive QEMU or the session won't start; black screen ≈ missing GL (docs/TESTING.md § gotchas). Kitty is the sole terminal (no Ghostty).
• No KVM = slow, not broken; don't read slowness as failure.

Known-broken / watchlist

• btrfs-assistant "segfault" was unprivileged-only (re-diagnosed 2026-07-04): libbtrfsutil's unprivileged subvolume iteration crashes on btrfs-progs 6.17.1 (upstream-fixed after); as root it works, and the pkexec launcher runs it as root. The real distro bug was no polkit agent in the session (every pkexec failed silently) — hyprpolkitagent now ships (hyprland.nix exec-once). checks.snapshot-gui guards the root path. Lesson: before "app X is broken", check WHO it runs as — and whether polkit prompts can render at all (§ Snapshot browse/restore).
• NixOS release bump is a trap: the discarded attempt (branch deleted 2026-06-22) hit a Hyprland OOM blocker; a redo is a deliberate v2, never part of routine lock bumps.
• theme-state.json is git-tracked inside an 86 MB flake tree, so every state write re-copies the source before eval — the wallpapers-artifact split (BACKLOG LATER) is the decided fix (§ Faster switches).
• Friendly theme-state load (modules/theme-state-read.nix, #66): builtins.tryEval does not catch readFile/fromJSON failures — gate with pathExists + empty/non-object checks before fromJSON. Subtle JSON syntax errors still surface from nlohmann (line/col); field schema stays in theme.nix. mkFlake must builtins.seq the check onto the whole return set or lazy attr access skips it.

Design invariants

• Dock transitions are ordered safety operations (#100): dock in one hyprctl --batch (external on → every internal workspace moved → focus external → internal off); undock enables internal before moving anything. The Hyprland watcher, not a shell-pipeline subshell, owns a low-level handle-lid-switch inhibitor until the lid is physically open; startup cleans a validated stale process group. HDMI availability may appear only as change:sink, so fresh monitoradded is the intent boundary for the settled PipeWire/WirePlumber reprobe + sink pick; generic audio changes must not override a manual in-dock speaker choice.
• Waybar status is never color-only (item 28 sweep, iteration #69): every status module must distinguish its states by SHAPE (glyph) or presence (self-hide), never color alone — good/warn/bad collapse under color-blindness. When adding a state, give it a distinct glyph or gate the module on it; a new class that only recolors an existing glyph is a regression. Suppressed notification states (DND and app-inhibited) all use the bell-off glyph + @muted.
• Identity themes are not traffic lights (#69): white, vantablack, lumon, hackerman, matte-black, miasma — monochrome / mono-hue / earthy status by design. audit-theme-design.py tags their hue/CVD/ANSI-family findings [identity]; do not "fix" them into R/Y/G.
• Import hierarchy ≠ ANSI (#70): import-palettes.py must not set surface==overlay when color0==color8; light color0 is often ANSI black (not a chip). Roles are first-class — never bulk-reimport shipped JSON without a hierarchy pass.

Gotchas (cost a debugging session once)

• Installer HM pre-activate needs XDG_RUNTIME_DIR (+ session bus) (#123): runuser … activate inside nixos-enter has no user session. Without mkdir -p /run/user/$UID owned by the install user and XDG_RUNTIME_DIR (prefer dbus-run-session -- activate), dconf dies with Permission denied and the bake aborts mid-way — first boot looks unthemed / missing nm-applet even though the system installed.
• ISO filename is image.baseName (#125): volumeID alone does not rename result/iso/…; force image.baseName to nomarchy-… or the artifact stays nixos-live-….iso.
• Install flake ref must match the ISO branch (#124): while v1 lags main, seed ?ref=main (and compose-lock original) from main-built ISOs; NOMARCHY_FLAKE_URL must actually rewrite inputs.nomarchy.url (was set but unused until #124).
• Gum filter returns unmatched typed text by default; catalog-only pickers require --strict plus an independent exact-membership validation boundary.
• Waybar layer: top renders above even real-fullscreen windows — the bar draws over a fullscreen video. layer: bottom lets the fullscreen surface cover it while the exclusive zone still reserves the bar's space in normal tiling (trade-off: floating windows can now overlap the bar strip). Set in both waybar.nix and every whole-swap jsonc (item 30).
• Hyprland binds match the exact modmask: a shifted keysym (question) needs SHIFT in mods or the bind never fires — the keypress falls through to the focused window (§ item 26; caught on hardware, invisible to eval-tier tests).
• Never kill a Wayland session-lock client (hyprlock): its crash failsafe drops to a tty instead of unlocking (§ Hibernate double-unlock).
• rofi element-icon size is one value = a square cell; WxH silently collapses and non-square icons letterbox — pre-crop images square at build (§ Visual theme picker).
• WirePlumber 0.5 monitor rules can only early-match device.api; device.product.name etc. bind after the rule runs — surgical libcamera scoping is impossible (§ Webcam).
• hyprctl switchxkblayout is a global layout flip; per-device isolation needs device[<name>]:kb_layout keywords (§ Keyboard layouts).
• Waybar's clock captures the timezone at construction — a zone change needs SIGUSR2 (watcher in timezone.nix) (§ Automatic timezone).
• Waybar persistent_workspaces (underscore) is dead syntax silently ignored; the hyphen form is honoured and renders phantom workspaces (§ Waybar shows non-existent workspaces).
• GTK4/libadwaita/Qt6 read light/dark from the portal's org.freedesktop.appearance color-scheme (dconf), not Stylix polarity (§ GTK/Qt ignore the theme's mode).
• Update order matters downstream: nomarchy-pull (lock) then nomarchy-rebuild then nomarchy-home, or desktop changes are silently skipped against the old lock (README § 3).
• Hyprland 0.55 renames stayfocused → stay_focused (and similar underscore effects); stayfocused 1 is invalid field type at parse (§ polkit workspace rules, 2026-07-10 hardware).
• Never gate a safety listener behind the optional feature it also serves: the display menu existed with no profiles while its blackout rescue did not. Rofi defaults to mouse-pointer output (monitor=-5), which is stale in clamshell mode; use focused output (-1) for keyboard-launched UI.
• Hyprland 0.53 rewrote window rules: windowrulev2 is a hard error and the old rule-first float, class:^…$ no longer parses — both surface a red config-error banner on the default desktop. Hyprlang legacy form is now <effect> <value>, match:<prop> ^…$ (e.g. float 1, match:class ^…$); effects carry a value, matchers take match: (§ windowrule migration).
• grub loadfonts every .pf2 in a theme dir — reuse a bundled DejaVu rather than shipping fonts (§ Distro branding).
• Agent instructions live vendor-neutrally in agent/ (VERIFICATION, DELEGATION, THEME-DESIGN; entry AGENTS.md) — .claude/ is a thin adapter (permissions + subagent defs only; skills were removed 2026-07-11). Never git add -A blindly: check git status --short for genuine strangers first (settings.local.json, harness-dropped files) and commit with explicit pathspecs (§ loop hygiene).