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>

hosts/argon/niri.nix

@@ -1,4 +1,5 @@
 # argon: desktop with two 1440p monitors side by side
+
 {
   wayland.windowManager.niri.settings = {
     input = {

hosts/default/configuration.nix

@@ -1,4 +1,4 @@
-# 0x29a nixos conifg
+# 0x29a nixos config
 
 { pkgs, ... }:
 

hosts/neon/niri.nix

@@ -1,17 +1,7 @@
-# neon: laptop, built-in display is auto-configured by niri
+# neon: laptop, the built-in display is auto-configured by niri
+
 { lib, ... }:
 
-let
-  brightness = step: {
-    _props.allow-when-locked = true;
-    spawn = [
-      "brightnessctl"
-      "--class=backlight"
-      "set"
-      step
-    ];
-  };
-in
 {
   wayland.windowManager.niri.settings = {
     input.touchpad = {
@@ -26,9 +16,9 @@ in
       "Ctrl+Print".screenshot-screen = { };
       "Mod+Shift+P".power-off-monitors = { };
 
-      # finer brightness steps; mkForce, since spawn lists would otherwise be concatenated
-      "XF86MonBrightnessUp" = lib.mkForce (brightness "+1%");
-      "XF86MonBrightnessDown" = lib.mkForce (brightness "1%-");
+      # finer brightness steps
+      "XF86MonBrightnessUp".spawn-sh = lib.mkForce "brightnessctl --class=backlight set +1%";
+      "XF86MonBrightnessDown".spawn-sh = lib.mkForce "brightnessctl --class=backlight set 1%-";
     };
   };
 }

modules/home-manager/git.nix

@@ -1,3 +1,7 @@
+# Commits are signed with each machine's ~/.ssh/id_ed25519 through the ssh
+# agent. gitea verifies them against the account keys; allowed_signers gives
+# the local git the same trust, so `git log --show-signature` resolves too.
+
 {
   config,
   lib,
@@ -7,18 +11,12 @@
 
 let
   email = "aaron@0x29a.ch";
-
-  # public half of every machine's ~/.ssh/id_ed25519, each one verified as a
-  # signing key in gitea. the key a host signs with is picked up from the key
-  # file itself, this list only tells the local git which machines to trust
   signingKeys = [
     "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHRhwzo1oxaT3fEySSmILKNnu9v30cfjx5G7FKpmfqeX aaron@argon"
     "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGDkhvvTUcBSQdtXjX+Mw2Bp8HHhtiBm8aJi4ZxiBgZR aaron@neon"
   ];
 in
 {
-  # gitea verifies signatures against the account keys, this teaches the local
-  # git the same trust so `git log --show-signature` resolves as well
   xdg.configFile."git/allowed_signers".text = lib.concatMapStrings (
     key: "${email} ${key}\n"
   ) signingKeys;
@@ -26,9 +24,7 @@ in
   programs.git = {
     enable = true;
     settings = {
-      push = {
-        autoSetupRemote = true;
-      };
+      push.autoSetupRemote = true;
       user = {
         name = "aaron";
         inherit email;
@@ -37,8 +33,7 @@ in
     };
     signing = {
       format = "ssh";
-      # point at the *public* key so ssh-keygen signs through the ssh agent
-      # instead of reading the passphrase protected private key from disk
+      # the public key makes ssh-keygen sign through the agent
       key = "${config.home.homeDirectory}/.ssh/id_ed25519.pub";
       signer = "${pkgs.openssh}/bin/ssh-keygen";
       signByDefault = true;

modules/home-manager/niri.nix

@@ -1,7 +1,11 @@
+# Only renders ~/.config/niri/config.kdl; niri itself, its session and portals
+# come from modules/nixos/niri.nix. Outputs and input devices that differ
+# per machine live in hosts/<host>/niri.nix.
+
 { lib, osConfig, ... }:
 
 let
-  # Mod+1..9 focus a workspace, Mod+Ctrl+1..9 move the column there.
+  # Mod+1..9 focus a workspace, Mod+Ctrl+1..9 move the column there
   workspaceBinds = lib.mergeAttrsList (
     map (n: {
       "Mod+${toString n}".focus-workspace = n;
@@ -9,24 +13,18 @@ let
     }) (lib.range 1 9)
   );
 
-  # Shorthand for binds that only run spawn-sh while allowed on the lock screen.
+  # shell command that also works on the lock screen
   lockedSh = cmd: {
     _props.allow-when-locked = true;
     spawn-sh = cmd;
   };
 in
 {
-  # Niri config, rendered to ~/.config/niri/config.kdl by home-manager's built-in
-  # wayland.windowManager.niri module. The compositor itself, its session, systemd
-  # units and portals are provided by the NixOS module (modules/nixos/niri.nix), so
-  # this module only writes the config. Host-specific outputs and input devices
-  # live in hosts/<host>/niri.nix.
-
   wayland.windowManager.niri = {
-    # only on hosts that run niri (see modules/nixos/niri.nix)
+    # only on hosts that run niri
     enable = osConfig.programs.niri.enable;
 
-    # Use the system's niri so the config is validated against the running version.
+    # validate the config against the installed niri
     package = osConfig.programs.niri.package;
     systemd.enable = false;
     portalPackage = null;
@@ -125,21 +123,11 @@ in
         };
         "Mod+D" = {
           _props.hotkey-overlay-title = "Run an Application";
-          spawn = [
-            "noctalia"
-            "msg"
-            "panel-toggle"
-            "launcher"
-          ];
+          spawn-sh = "noctalia msg panel-toggle launcher";
         };
         "Super+Alt+L" = {
           _props.hotkey-overlay-title = "Lock the Screen";
-          spawn = [
-            "noctalia"
-            "msg"
-            "session"
-            "lock"
-          ];
+          spawn-sh = "noctalia msg session lock";
         };
 
         # media keys (PipeWire / WirePlumber)
@@ -151,24 +139,8 @@ in
         "XF86AudioStop" = lockedSh "playerctl stop";
         "XF86AudioPrev" = lockedSh "playerctl previous";
         "XF86AudioNext" = lockedSh "playerctl next";
-        "XF86MonBrightnessUp" = {
-          _props.allow-when-locked = true;
-          spawn = [
-            "brightnessctl"
-            "--class=backlight"
-            "set"
-            "+10%"
-          ];
-        };
-        "XF86MonBrightnessDown" = {
-          _props.allow-when-locked = true;
-          spawn = [
-            "brightnessctl"
-            "--class=backlight"
-            "set"
-            "10%-"
-          ];
-        };
+        "XF86MonBrightnessUp" = lockedSh "brightnessctl --class=backlight set +10%";
+        "XF86MonBrightnessDown" = lockedSh "brightnessctl --class=backlight set 10%-";
 
         "Mod+O" = {
           _props.repeat = false;

modules/home-manager/shell.nix

@@ -1,25 +1,26 @@
+# zsh with oh-my-zsh: agnoster where glyphs render, gentoo on the console.
+# Deep paths are shortened to `…/last/two` so the prompt stays on one line:
+# `%(4~|…/%2~|%~)` shows the last two components from four levels down.
+
 { lib, ... }:
 
 {
-  # configure z-shell to use omz with some plugins
   programs.zsh = {
     enable = true;
     autosuggestion.enable = true;
     syntaxHighlighting.enable = true;
     oh-my-zsh = {
       enable = true;
-      # add git and agents as plugins
       plugins = [
         "git"
         "ssh-agent"
         "gpg-agent"
       ];
-      # everything here lands before `source $ZSH/oh-my-zsh.sh`
+      # runs before oh-my-zsh is sourced
       extraConfig = ''
-        # make omz faster on large repositories
+        # faster git status on large repositories
         DISABLE_UNTRACKED_FILES_DIRTY=true
 
-        # only display a fancy theme when glyphs are rendered
         if [[ "$TERM" == "linux" || "$TERM" == "screen" ]]; then
           ZSH_THEME="gentoo"
         else
@@ -28,37 +29,20 @@
       '';
     };
 
-    # Unlike oh-my-zsh.extraConfig above, this lands *after*
-    # `source $ZSH/oh-my-zsh.sh`, which is where the theme's prompt functions
-    # come into existence.
+    # runs after oh-my-zsh, once the theme's prompt exists
     initContent = lib.mkAfter ''
-      # Keep the prompt on one line in deeply nested trees.
-      #
-      # Both themes render the working directory as `%~`, the full path with
-      # $HOME collapsed to `~`. Somewhere like
-      # ~/git/bfh/cas-pml-sem/documents/bericht that is 39 columns on its own,
-      # and together with user@host and a long branch name the line wraps.
-      #
-      # `%(4~|…/%2~|%~)` is a prompt ternary: at four or more components show
-      # an ellipsis and the last two, otherwise show the path whole. Short
-      # paths like ~/git/nixconfig are left alone.
       if [[ "$ZSH_THEME" == "agnoster" ]]; then
-        # agnoster calls prompt_dir on every render, so redefining it is
-        # enough. AGNOSTER_DIR_* keep the segment's own colours.
+        # agnoster renders prompt_dir on every prompt, so override it
         prompt_dir() {
           prompt_segment "$AGNOSTER_DIR_BG" "$AGNOSTER_DIR_FG" '%(4~|…/%2~|%~)'
         }
       else
-        # gentoo builds PROMPT once at load time, so patch the string. Its
-        # `%~` is the non-root branch of `%(!.%1~.%~)`, and it is the first
-        # literal `%~` in there, so the root branch is untouched. ASCII `...`
-        # because this branch is the Linux console, whose font may lack U+2026.
+        # gentoo builds PROMPT once; ascii dots, the console font lacks …
         PROMPT="''${PROMPT/\%~/%(4~|.../%2~|%~)}"
       fi
     '';
   };
 
-  # set important env vars
   home.sessionVariables = {
     EDITOR = "vim";
     NH_FLAKE = "/home/aaron/git/nixconfig";

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 "

modules/nixos/appimage.nix

@@ -1,17 +1,10 @@
+# Running an AppImage directly fails on NixOS: its runtime dlopens
+# libfuse.so.2, which nix-ld doesn't cover. appimage-run unpacks the image
+# into an FHS sandbox instead. Used for the BitBox02 wallet from bitbox.swiss.
+
 {
-  # AppImages ship a squashfs payload that the bundled runtime mounts through
-  # libfuse.so.2 at startup. nix-ld resolves the ELF interpreter but not that
-  # dlopen, so running one directly dies with "dlopen(): error loading
-  # libfuse.so.2". appimage-run sidesteps the mount entirely: it unpacks the
-  # image and runs the payload inside an FHS sandbox, which the bundled Qt and
-  # electron style binaries need anyway.
-  #
-  # Used for the BitBox02 wallet AppImage, downloaded fresh from
-  # https://bitbox.swiss/download/ rather than installed from nixpkgs.
   programs.appimage = {
     enable = true;
-    # register AppImages with binfmt_misc so ./Something.AppImage runs as-is,
-    # no appimage-run prefix to remember.
-    binfmt = true;
+    binfmt = true; # ./Something.AppImage runs without the appimage-run prefix
   };
 }

modules/nixos/astro.nix

@@ -1,37 +1,23 @@
+# Stellarium for target finding, Siril for stacking.
+#
+# Siril's python plugins run in a venv of foreign manylinux wheels (numpy,
+# PyQt6, ...), dlopened by nixpkgs python, so nix-ld doesn't help. The wrapper
+# puts their libs on LD_LIBRARY_PATH, a python on PATH to bootstrap the venv,
+# and adwaita-qt6 on QT_PLUGIN_PATH so the dark style override resolves.
+# The python comes from /etc/siril/bin, a stable symlink: a /nix/store path
+# would leave the venv dangling after the next python bump and gc.
+#
+# StarNet++ has no package: unzip the v2 ORT cli build from starnetastro.com
+# to ~/.local/share/siril/starnet/ and point Siril's preferences at ./starnet2.
+# It runs through nix-ld and finds its own libs in the bundled ./lib.
+
 { lib, pkgs, ... }:
 
 let
-  # Siril's Python plugins (sirilpy) run in a venv that pip-installs foreign
-  # manylinux wheels (numpy, GraXpert deps, ...). Those .so files need
-  # libstdc++ at runtime. nix-ld does NOT cover this: it only handles the
-  # initial exec of a foreign binary, but here a *native* nixpkgs python
-  # dlopen()s the foreign wheel. So we put the libs on LD_LIBRARY_PATH, which
-  # the python subprocess inherits from the Siril process.
   sirilWithPlugins = pkgs.symlinkJoin {
     name = "siril-with-plugins";
     paths = [ pkgs.siril ];
     nativeBuildInputs = [ pkgs.makeWrapper ];
-    # Siril bootstraps its sirilpy venv at first run by locating a `python3`
-    # on PATH. nixpkgs only *propagates* python3 from the siril derivation (it
-    # isn't on the runtime PATH), so without the --prefix PATH below the GUI
-    # fails with "Python not found in system PATH" and never creates
-    # ~/.local/share/siril/venv.
-    #
-    # We deliberately do NOT put ${pkgs.python3}/bin on PATH directly: `venv`
-    # symlinks bin/python3 to whatever sys.executable was, so the venv would
-    # hard-link a /nix/store hash that gets garbage-collected after the next
-    # python bump, leaving a dangling symlink ("Error finding venv python
-    # path, unable to spawn python"). Instead we go through the stable
-    # /etc/siril/bin/python3 symlink (see environment.etc below), which NixOS
-    # re-points at the current python on every rebuild.
-    #
-    # The VeraLux PyQt6 wheel ships only the built-in Windows/Fusion styles, so
-    # the global QT_STYLE_OVERRIDE=adwaita-dark (inherited from the session) is
-    # rejected ("invalid style override") and windows fall back to a light
-    # theme. We expose nixpkgs adwaita-qt6's style plugin on QT_PLUGIN_PATH so
-    # the override resolves. This works because nixpkgs qt6 and the bundled Qt
-    # share a major.minor (6.11); if they ever drift the plugin is simply
-    # ignored again (harmless warning + Fusion fallback, no loss of function).
     postBuild = ''
       wrapProgram $out/bin/siril \
         --prefix PATH : /etc/siril/bin \
@@ -40,21 +26,19 @@ let
           lib.makeLibraryPath (
             with pkgs;
             [
-              stdenv.cc.cc.lib # libstdc++ / libgcc_s / libgomp  (numpy etc.)
+              stdenv.cc.cc.lib # libstdc++, libgcc_s, libgomp (numpy)
               zlib
-              zstd # libzstd.so.1                     (PyQt6)
-              libGL # libGL.so.1                       (PyQt6)
-              # PyQt6 (VeraLux) — Qt bundles xcb support so it needs these even
-              # on Wayland; libxkbcommon is the keymap lib used by Wayland too.
+              zstd # PyQt6
+              libGL # PyQt6
+              # Qt needs these even on wayland
               glib
               fontconfig
               freetype
               dbus
               libxkbcommon
-              # Qt platform plugins: the wayland plugin (libqwayland.so) needs the
-              # wayland client libs; the xcb fallback needs libxcb-cursor.so.0.
-              wayland # libwayland-client/cursor/egl       (wayland plugin)
-              libxcb-cursor # libxcb-cursor.so.0                 (xcb plugin)
+              # Qt platform plugins: wayland, and the xcb fallback
+              wayland
+              libxcb-cursor
               libx11
               libxcb
               libxcb-util
@@ -69,27 +53,20 @@ let
   };
 in
 {
-  # install stellarium for target finding and siril for stacking
-  environment.systemPackages = with pkgs; [
-    stellarium
+  environment.systemPackages = [
+    pkgs.stellarium
     sirilWithPlugins
   ];
 
-  # Stable, GC-safe interpreter path for Siril's venv (see sirilWithPlugins).
-  # Same python as siril itself propagates, so sirilpy's ABI matches.
+  # same python siril propagates, so sirilpy's abi matches
   environment.etc."siril/bin/python3".source = "${pkgs.python3}/bin/python3";
 
-  # StarNet++ has no nixpkgs package. Download the StarNet v2 ORT CLI build
-  # (starnet2_linux_*_ORT_x64_cli) from https://www.starnetastro.com/download/
-  # and unzip it to ~/.local/share/siril/starnet/. Then in Siril set
-  #   Preferences -> Miscellaneous -> StarNet executable
-  # to the extracted ./starnet2 binary.
-  #
-  # The binary is a generic dynamically-linked ELF, so NixOS needs nix-ld to
-  # run it. Its own opencv/onnxruntime libs are found via the bundled ./lib.
-  programs.nix-ld.enable = true;
-  programs.nix-ld.libraries = with pkgs; [
-    stdenv.cc.cc.lib # libstdc++ / libgcc_s
-    zlib
-  ];
+  # for StarNet++
+  programs.nix-ld = {
+    enable = true;
+    libraries = with pkgs; [
+      stdenv.cc.cc.lib
+      zlib
+    ];
+  };
 }

modules/nixos/protonvpn.nix

@@ -1,13 +1,8 @@
 { pkgs, ... }:
 
 {
-  # protonvpn uses wireguard tunnels, which break strict reverse path filtering
-  # because packets arrive on the tunnel interface but may be routed back differently.
-  # "loose" checks that the source is routable through *any* interface (not necessarily
-  # the same one), which is sufficient for wireguard while still preventing IP spoofing.
+  # wireguard replies may leave on another interface, so strict rpfilter drops them
   networking.firewall.checkReversePath = "loose";
 
-  environment.systemPackages = with pkgs; [
-    proton-vpn
-  ];
+  environment.systemPackages = [ pkgs.proton-vpn ];
 }