# 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
- CI (`.gitea/workflows/check.yml`) is **eval-tier only**: the act_runner
  is a docker container (no systemd, no /dev/kvm). Container gotchas are
  documented 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) — learned over the legacy repo's 57 runs; read
  them before touching the workflow.
- 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
  uevent, `InvocationID` change proves the restart).
- 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/Ghostty need guest GL (`virtio-vga-gl`, `gl=on`) in
  interactive QEMU or the session won't start; black screen ≈ missing GL
  (docs/TESTING.md § gotchas).
- 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).

## Gotchas (cost a debugging session once)
- 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: `sys-update` (lock) before
  `home-update`, or desktop changes are silently skipped against the old
  lock (README § 3).
- grub `loadfont`s every `.pf2` in a theme dir — reuse a bundled DejaVu
  rather than shipping fonts (§ Distro branding).