docs: move explanations into short module headers

Non-obvious context sits in a brief header at the top of a module, everything else uses single-line comments. niri binds use spawn-sh strings, so neon only overrides the command.

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

modules/home-manager/tmux.nix

@@ -1,54 +1,37 @@
+# Nord-style status line built natively, no theme plugin.
+# The powerline separators (U+E0B0..U+E0B3) are written as escapes via
+# fromJSON: literal private-use glyphs get stripped silently on copy/paste.
+# Commas inside #{?...} separate arguments, hence the escaped `#,` below.
+
 let
-  # Powerline separators, U+E0B0..U+E0B3.
-  #
-  # Written as escapes rather than literal glyphs. These are Private Use Area
-  # codepoints: they render only with a patched font, they survive copy/paste
-  # badly, and when they get stripped the loss is invisible, the config still
-  # parses, the status bar just quietly loses its separators. Nix has no \u
-  # escape of its own, but fromJSON does.
   sep = builtins.fromJSON ''
     {
-      "right":     "\ue0b0",
-      "rightThin": "\ue0b1",
-      "left":      "\ue0b2",
-      "leftThin":  "\ue0b3"
+      "right":     "",
+      "rightThin": "",
+      "left":      "",
+      "leftThin":  ""
     }
   '';
 in
 {
   programs.tmux = {
-    # defaults
     enable = true;
     prefix = "C-a";
     keyMode = "vi";
     mouse = true;
-
-    # tmux-256color gives truecolor, italics and undercurl in nvim.
-    terminal = "tmux-256color";
-
-    # Default is 500ms. Causes lag you feel when leaving insert mode in nvim,
-    # because tmux is waiting to see whether Esc starts an escape sequence.
-    escapeTime = 10;
-
-    # nvim autoread / :checktime react to focus.
-    focusEvents = true;
-
-    # History limit.
+    terminal = "tmux-256color"; # truecolor, italics and undercurl in nvim
+    escapeTime = 10; # the 500ms default lags leaving insert mode in nvim
+    focusEvents = true; # nvim autoread
     historyLimit = 50000;
-
-    # Window numbers matching the number row.
-    baseIndex = 1;
+    baseIndex = 1; # window numbers match the number row
 
     extraConfig = ''
-      # Status keys
       set -g status-keys vi
 
-      # Tell tmux the outer terminal can do 24-bit colour (tmux >= 3.2).
+      # outer terminal does 24-bit colour
       set -sa terminal-features ",*:RGB"
 
-      # Shift+Enter / extended keys
-      # These make tmux forward CSI-u sequences unconditionally.
-      # Needs tmux >= 3.5 for the format option,
+      # forward Shift+Enter and other extended keys as CSI-u (tmux >= 3.5)
       set -s extended-keys always
       set -s extended-keys-format csi-u
       set -as terminal-features '*:extkeys'
@@ -88,27 +71,18 @@ in
       bind -r K resize-pane -U 5
       bind -r L resize-pane -R 5
 
-      # Wayland clipboard integration
-      # Copy selection to both clipboard (Ctrl+V / Shift+Insert) and primary (middle-click)
+      # copy to both the clipboard and primary selection
       bind -T copy-mode-vi v send-keys -X begin-selection
       bind -T copy-mode-vi C-v send-keys -X rectangle-toggle
       bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "wl-copy && wl-copy --primary"
       bind -T copy-mode-vi Enter send-keys -X copy-pipe-and-cancel "wl-copy && wl-copy --primary"
       bind -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "wl-copy && wl-copy --primary"
-      # Uncomment if you want yanks to also travel over SSH via OSC52.
-      # Locally redundant with wl-copy above.
-      #set -g set-clipboard on
 
       # Kill commands
       bind q confirm-before -p "kill window #W? (y/n)" kill-window
       bind Q confirm-before -p "kill session #S? (y/n)" kill-session
 
       # Bars
-      # This is the nord-tmux status line. #{prefix_highlight} came from that
-      # theme's tmux-prefix-highlight integration -- a plugin you never loaded,
-      # so the token expanded to nothing. tmux can do it natively. Commas inside
-      # #{?...} are argument separators and have to be escaped as #, hence the
-      # look of the style spec.
       set -g status-left-length 24
       set -g status-left "#[fg=black,bg=blue,bold] #{=20:session_name} #[fg=blue,bg=black,nobold,noitalics,nounderscore]${sep.right}"
       set -g status-right "#{?client_prefix,#[fg=black#,bg=yellow#,bold] ^A ,}#[fg=brightblack,bg=black,nobold,noitalics,nounderscore]${sep.left}#[fg=white,bg=brightblack] %Y-%m-%d #[fg=white,bg=brightblack,nobold,noitalics,nounderscore]${sep.leftThin}#[fg=white,bg=brightblack] %H:%M #[fg=cyan,bg=brightblack,nobold,noitalics,nounderscore]${sep.left}#[fg=black,bg=cyan,bold] #H "