docs: explain the sys-update -> home-update ordering

home-update rebuilds the desktop against the current flake.lock and never
touches it; only sys-update runs `nix flake update`. So pulling a distro
change that affects the home layer requires sys-update first (updates the
lock), then home-update -- the reverse order rebuilds against stale inputs
and silently skips the new home-side changes (hit while testing the mic
fix). Also note hyprctl reload after a home-side keybind change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -160,6 +160,17 @@ sys-update    # nix flake update + system rebuild (BTRFS snapshot first when ava
 home-update   # home-manager switch (no flake update, no sudo)
 ```
 
+**Order matters when pulling distro updates.** `home-update` does *not*
+touch the lock — it rebuilds the desktop against the **current**
+`flake.lock`. A new Nomarchy revision (new keybinds, theming, modules)
+arrives only when the lock is updated, which `sys-update` does
+(`nix flake update`). So to pull an update that affects the desktop layer:
+run `sys-update` **first** (updates the lock + rebuilds the system), **then**
+`home-update` (re-applies the desktop against the new lock). Doing them in
+the other order rebuilds the desktop against the *old* inputs and silently
+skips the new home-side changes. After a home-side keybind/config change,
+also `hyprctl reload` (or relogin) so the running session re-reads it.
+
 Override anything via the `nomarchy.*` surface or plain NixOS/HM options:
 appearance (gaps/colors/fonts) changes through `nomarchy-theme-sync`,
 behaviour (input/misc/monitor/chrome) is `mkDefault` so a plain `home.nix`

modules/home/hyprland.nix

@@ -8,22 +8,23 @@ let
   c = t.colors;
   inherit (config.nomarchy.lib) rgb rgba;
 
-  # swayosd 0.2.1's `--input-volume mute-toggle` draws the OSD but never
-  # flips the source mute (verified on hardware: wpctl toggles the state,
-  # swayosd's input-mute path is a no-op — unlike its working output-mute
-  # path). Do the real toggle with wpctl, then show an OSD reflecting the
-  # resulting state via swayosd's --custom-icon/--custom-message.
+  # swayosd's `--input-volume mute-toggle` draws the OSD but never flips the
+  # source mute (verified on hardware: wpctl toggles the state, swayosd's
+  # input-mute path is a no-op — unlike its working output-mute path). Do the
+  # real toggle with wpctl, then re-render the same icon + volume-bar OSD the
+  # native input path would, reading the resulting state back from wpctl:
+  # --custom-progress is the mic level (0.0-1.0), --custom-icon the
+  # muted/active glyph. Pure bash builtins for parsing so the script needs no
+  # PATH beyond the two pinned tools.
   micMute = pkgs.writeShellScript "nomarchy-mic-mute" ''
     ${pkgs.wireplumber}/bin/wpctl set-mute @DEFAULT_SOURCE@ toggle
-    if ${pkgs.wireplumber}/bin/wpctl get-volume @DEFAULT_SOURCE@ | grep -q MUTED; then
-      ${pkgs.swayosd}/bin/swayosd-client \
-        --custom-icon microphone-sensitivity-muted-symbolic \
-        --custom-message "Microphone muted"
-    else
-      ${pkgs.swayosd}/bin/swayosd-client \
-        --custom-icon microphone-sensitivity-high-symbolic \
-        --custom-message "Microphone unmuted"
-    fi
+    out=$(${pkgs.wireplumber}/bin/wpctl get-volume @DEFAULT_SOURCE@)
+    set -- $out            # "Volume: 0.85 [MUTED]" -> $2 is the level
+    case "$out" in
+      *MUTED*) icon=microphone-sensitivity-muted-symbolic ;;
+      *)       icon=microphone-sensitivity-high-symbolic ;;
+    esac
+    ${pkgs.swayosd}/bin/swayosd-client --custom-icon "$icon" --custom-progress "$2"
   '';
 
   # SUPER+1..9 / SUPER+SHIFT+1..9 workspace binds, generated.