docs: condense comments across the repo

Comments had drifted into multi-paragraph narrative (git commit
lineage, debugging stories, restated code) in several hot spots
(scripts/deploy, hermes-agent.nix, flake.nix, gitea.nix, headscale.nix).
Trim every comment to its load-bearing "why" — gotchas, safety
warnings, and non-obvious rationale survive verbatim in substance,
just tightened to 1-2 sentences; historical narrative and anything
already covered in CLAUDE.md is cut. No code/logic changed.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UJqEmY1y3AYX3JoX4Y6b21

hosts/terra/home/hyprland.nix

@@ -1,32 +1,16 @@
 { lib, pkgs, config, inputs, ... }:
 
-# Hyprland config migrated from github.com/darman96/hyprland-dotfiles (the
-# hyprlang `hypr/*.conf` files) into the home-manager lua-style `settings`
-# (configType defaults to "lua" on stateVersion 26.05). Each top-level
-# `settings` attr becomes an `hl.<name>(...)` call in ~/.config/hypr/hyprland.lua;
-# `_args` lists become multi-arg calls, `_var` locals become `local x = ...`, and
-# `lib.generators.mkLuaInline` values render as raw Lua expressions.
+# Hyprland config migrated from github.com/darman96/hyprland-dotfiles into
+# home-manager's lua-style `settings` (each attr becomes an `hl.<name>(...)`
+# call in hyprland.lua). Imported by home.nix; system-level enable lives in
+# ../../services/desktop/desktop-hyprland.nix.
 #
-# Imported by home.nix. System-level Hyprland enable (session entry, portals)
-# lives in ../../services/desktop/desktop-hyprland.nix; this manages the user's
-# own hyprland.lua.
-#
-# Deliberately NOT migrated:
-#   - hyprbars.conf: config for the third-party `hyprbevelbars` plugin, which
-#     isn't packaged in nixpkgs. Load it via
-#     `wayland.windowManager.hyprland.plugins` and re-add its config once
-#     available. (hyprredsquare.conf's plugin was renamed hypr-chrome and
-#     rewritten since - it's wired in below via the `hypr-chrome` flake
-#     input instead, with its own `plugin.hyprchrome` config.)
-#   - hyprqt6engine.conf + `QT_QPA_PLATFORMTHEME=hyprqt6engine`: terra themes Qt
-#     through qtct/Dracula in home.nix, so that env var is left off to avoid a conflict.
-#   - hyprlock.conf: a separate program (use `programs.hyprlock` if wanted).
-#   - the duplicate pamixer/amixer + `.wob` volume binds: kept only the clean
-#     pipewire `wpctl`/`playerctl` set (no wob overlay is configured here).
-#   - `XDG_MENU_PREFIX=arch-` and `VCPKG_ROOT`: Arch-/user-specific.
-# Many binds reference apps/scripts not packaged on terra yet (vivaldi-stable,
-# dolphin, vicinae, grimblast, waypaper, discord, gitkraken, qbz,
-# ~/.config/scripts/start-communications.sh); add them separately.
+# Not migrated: hyprbars (unpackaged plugin; its successor hypr-chrome is
+# wired in below instead), hyprqt6engine (conflicts with home.nix's qtct/
+# Dracula Qt theming), hyprlock (use programs.hyprlock), the old wob volume
+# overlay (kept only wpctl/playerctl), and Arch-specific env vars. Several
+# binds reference apps not yet packaged here (vivaldi-stable, dolphin,
+# vicinae, grimblast, waypaper, discord, gitkraken, qbz).
 
 let
   lua = lib.generators.mkLuaInline;
@@ -37,11 +21,9 @@ let
   cursorName = config.home.pointerCursor.name;
   cursorSize = toString config.home.pointerCursor.size;
 
-  # Wallpaper images aren't checked into this repo (binary blobs) — pulled
-  # from the existing Wallhaven library on /mnt/hdd_01 instead. Picked once
-  # here rather than at runtime, since hyprpaper has no built-in "random"
-  # mode; re-pick and rebuild (or swap in real per-monitor selection) when
-  # this stops being a placeholder.
+  # Wallpapers aren't checked into this repo (binaries) — pulled from the
+  # Wallhaven library on /mnt/hdd_01. Picked once here since hyprpaper has
+  # no built-in "random" mode.
   # wallpaper = "/mnt/hdd_01/data/Pictures/Wallhaven/wallhaven-ym81rl.png";
   wallpaper = "/mnt/hdd_01/data/Pictures/Wallhaven/wallhaven-mlwz78.png";
 
@@ -317,11 +299,8 @@ in
           "hyprland.start"
           (lua ''
             function()
-              -- No polkit agent is started here: quickshell registers one
-              -- itself (HyprChrome/Widgets/Polkit), and a session admits only
-              -- one. The hyprpolkitagent line this replaces had been dead for
-              -- a while anyway — the unit was never installed, so the start
-              -- failed silently and the session ran with no agent at all.
+              -- No polkit agent started here: quickshell registers its own
+              -- (HyprChrome/Widgets/Polkit), and a session admits only one.
               hl.exec_cmd("cosmic-settings-daemon")
               hl.exec_cmd("quickshell")
               hl.exec_cmd("alacritty", { workspace = "special:terminal silent" })

hosts/terra/home/theme.nix

@@ -23,14 +23,11 @@ in
     };
   };
 
-  # The cursor theme. XCURSOR_THEME alone is not enough for Steam: the client
-  # UI (steamwebhelper) runs inside a pressure-vessel container that rebuilds
-  # /etc, so the /etc/profiles/per-user/darman/share/icons entry of
-  # XCURSOR_PATH does not exist in there and libXcursor finds no theme by
-  # that name — it falls back to the built-in core X11 cursor. $HOME and
-  # /nix are bind-mounted into the container, so the ~/.icons symlink that
-  # `dotIcons` (on by default) drops does resolve. Same class of problem as
-  # the ~/.themes/~/.icons flatpak workaround above.
+  # XCURSOR_THEME alone isn't enough for Steam: steamwebhelper runs inside a
+  # pressure-vessel container with its own /etc, so XCURSOR_PATH doesn't
+  # resolve there and it falls back to the core X11 cursor. $HOME and /nix are
+  # bind-mounted in though, so the ~/.icons symlink `dotIcons` drops still
+  # resolves — same fix as the flatpak workaround below.
   home.pointerCursor = {
     name = "Bibata-Modern-Classic";
     package = pkgs.bibata-cursors;
@@ -39,11 +36,9 @@ in
     hyprcursor.enable = true;
   };
 
-  # Flatpak apps are sandboxed and can't see XDG_DATA_DIRS/nix-store theme
-  # paths, so the portal-reported GTK theme / icon theme names resolve to
-  # nothing inside the sandbox and they fall back to Adwaita. Flatpak
-  # auto-exposes ~/.themes and ~/.icons read-only to every sandboxed app
-  # specifically for this case.
+  # Flatpak apps can't see XDG_DATA_DIRS/nix-store theme paths, so the
+  # portal-reported theme names resolve to nothing and fall back to Adwaita;
+  # Flatpak auto-exposes ~/.themes and ~/.icons read-only as the workaround.
   home.file.".themes/Dracula".source =
     "${pkgs.dracula-theme}/share/themes/Dracula";
   home.file.".icons/${iconTheme}".source = iconThemeFolder;