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/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";