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/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
+    ];
+  };
 }