feat(agent): autonomous-loop infrastructure + roadmap rework

A git-tracked agent/ directory so AI agents can iterate on the distro
unattended (runner-agnostic: /loop, headless claude -p, or a fresh
manual session — all state lives in the checkout, per the distro's own
philosophy):

- LOOP.md — the iteration protocol: orient → pick one BACKLOG task →
  verify up the V0–V3 ladder → commit+push main → record. Safety rails
  (v1 untouchable, no force-push, no surprise lock bumps) and
  stop-and-escalate conditions.
- BACKLOG.md — the forward half of docs/ROADMAP.md reworked into a
  prioritized queue (5 NOW / 6 NEXT / LATER / PROPOSED / Decisions);
  ROADMAP.md stays the design/decision record + shipped log.
- GOALS.md — the four pillars (stable > reproducible/zero-hidden-state >
  effortless config > beautiful), quality bars, non-goals.
- CONVENTIONS.md — coding/design rules (in-flake state, menu placement,
  Waybar whole-swap parity, toggle-vs-package, no formatter).
- MEMORY.md — curated hard-won lessons (VM recipes, btrfs-assistant
  segfault watch, rofi/WirePlumber/hyprlock gotchas).
- HARDWARE-QUEUE.md — every pending V3 on-hardware check collected from
  the ROADMAP, with exact steps, split by machine.
- JOURNAL.md — append-only iteration log, seeded with this bootstrap.

Plus a root CLAUDE.md entry point and README/ROADMAP pointers.

Verified: V0 — docs-only; nix flake check --no-build green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

agent/MEMORY.md

@@ -0,0 +1,60 @@
+# 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
+- 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 2.2 segfaults on launch** (nixpkgs 26.05,
+  `libbtrfsutil.so.1.4.0` ABI mismatch; crashes on hardware too, not a VM
+  artifact). `nomarchy-snapshots` fzf flow is the shipped fallback;
+  re-check on every lock bump (§ Snapshot browse/restore; BACKLOG NOW#2).
+- **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).