Trim verbose comments to concise, self-contained notes

Cut restated "what", domain-glossary framing, cross-file consumption
narration, and against-alternative justification from in-file comments;
keep only non-obvious "why" and load-bearing pointers. Drop the
`generateCompletions` line (a no-op restatement of the upstream default)
and its comment.

modules/claude-code/claude-code.nix

@@ -3,19 +3,14 @@
   lib,
   ...
 }:
-# Claude Code — Anthropic's CLI — for the primary user, configured declaratively
-# through home-manager. home-manager ships the package and manages ~/.claude:
-# the global agent instructions (./CLAUDE.md), the skills tree (./skills), the
-# attention-bell hook (./hooks), and settings.json (the model and the hook
-# wiring). Login credentials are left unmanaged so they survive rebuilds;
-# signing in without a browser, as needed over the console or SSH, is covered in
-# ./authentication.md.
+# Claude Code for the primary user, configured through home-manager, which ships
+# the package and manages ~/.claude. Login credentials are left unmanaged so they
+# survive rebuilds.
 let
   cfg = config.modules.claude-code;
   user = config.user.name;
 
-  # Rings the terminal bell so tmux flags the background pane; wired to both the
-  # end of a turn and attention notifications below.
+  # Rings the terminal bell so tmux flags the background pane.
   bellHook = [
     {
       hooks = [
@@ -37,12 +32,10 @@ in
       # Global agent instructions, rendered to ~/.claude/CLAUDE.md.
       context = ./CLAUDE.md;
 
-      # One directory per skill, each carrying its SKILL.md, symlinked under
-      # ~/.claude/skills.
+      # One directory per skill, symlinked under ~/.claude/skills.
       skills = ./skills;
 
-      # Installed executable at ~/.claude/hooks/attention-bell.sh, where the
-      # settings hooks reference it.
+      # Installed at ~/.claude/hooks/attention-bell.sh, referenced by the settings below.
       hooks."attention-bell.sh" = builtins.readFile ./hooks/attention-bell.sh;
 
       settings = {

modules/example.nix

@@ -1,12 +1,11 @@
 { config, lib, ... }:
-# The Auto-loader reference example. Every real Module copies this shape: it is
-# imported unconditionally but its body stays inert until a Host sets the
-# `enable` flag, so each Host reads as a checklist of `enable = true` lines.
+# Reference example for the module shape: imported unconditionally, but inert
+# until a host sets its `enable` flag.
 let
   cfg = config.modules.example;
 in
 {
-  options.modules.example.enable = lib.mkEnableOption "the Auto-loader reference example Module";
+  options.modules.example.enable = lib.mkEnableOption "the reference example module";
 
   config = lib.mkIf cfg.enable {
     environment.etc."skeleton-example".text = "This Module is enabled.\n";

modules/fish/fish.nix

@@ -4,10 +4,7 @@
   pkgs,
   ...
 }:
-# fish for the primary user, configured natively through home-manager. Wires the
-# done and bang-bang plugins, a fastfetch greeting, a bat-backed manpager, helper
-# functions, the eza aliases, and vi-style command-line editing. Set fish as the
-# default login shell by also turning on `modules.fish.defaultShell`.
+# fish for the primary user, configured through home-manager.
 let
   cfg = config.modules.fish;
   user = config.user.name;
@@ -24,28 +21,21 @@ in
   };
 
   config = lib.mkIf cfg.enable {
-    # System-level fish: registers it in /etc/shells and installs vendor
-    # completions.
+    # System-level fish registers it in /etc/shells and installs vendor completions.
     programs.fish.enable = true;
     users.users.${user}.shell = lib.mkIf cfg.defaultShell pkgs.fish;
 
     home-manager.users.${user} = {
       home.packages = with pkgs; [
-        eza # modern ls with git awareness and icons; backs the ls aliases
-        bat # syntax-highlighting cat/pager; backs the manpager below
-        fastfetch # system-info banner printed as the shell greeting
-        wget # non-interactive HTTP downloader; backs the wget abbreviation
+        eza # backs the ls/la/ll aliases
+        bat # backs the manpager
+        fastfetch # the shell greeting
+        wget # backs the wget abbreviation
       ];
 
       programs.fish = {
         enable = true;
 
-        # Relied-on upstream defaults, pinned so a future change can't silently
-        # alter behaviour.
-        generateCompletions = true;
-
-        # Prefer abbreviations over aliases when other modules wire up fish
-        # shortcuts, matching the abbreviation-first style below.
         preferAbbrs = true;
 
         plugins = [
@@ -94,7 +84,6 @@ in
         };
 
         functions = {
-          # Run fastfetch as the welcome message.
           fish_greeting = "fastfetch";
 
           history = {
@@ -114,8 +103,7 @@ in
           };
         };
 
-        # Read from a real fish file, which home-manager renders into
-        # ~/.config/fish/config.fish.
+        # Rendered by home-manager into ~/.config/fish/config.fish.
         interactiveShellInit = builtins.readFile ./config.fish;
       };
     };

modules/nvim/nvim.nix

@@ -5,12 +5,8 @@
   inputs,
   ...
 }:
-# Neovim for the primary user, configured declaratively through nixvim. Options,
-# keymaps, and plugin settings are typed Nix; the imperative remainder (the
-# colorscheme call and the Neogit blame-toggle autocmd) lives in ./config.lua.
-# Plugins come from nixpkgs — no plugin manager and no runtime cloning — and
-# treesitter grammars are built by Nix, so no compiler is needed at runtime. git
-# backs the git plugins; ripgrep and fd back the picker.
+# Neovim for the primary user, configured declaratively through nixvim. The
+# imperative remainder (colorscheme, Neogit blame autocmd) lives in ./config.lua.
 let
   cfg = config.modules.nvim;
   user = config.user.name;
@@ -32,7 +28,7 @@ in
         ];
 
         globals.mapleader = " ";
-        globals.clipboard = "osc52"; # neovim's built-in OSC 52 provider, no external binary needed
+        globals.clipboard = "osc52"; # built-in OSC 52 provider, no external binary needed
 
         opts = {
           clipboard = "unnamedplus";
@@ -180,8 +176,8 @@ in
           };
         };
 
-        # gbprod/nord.nvim; nixvim's colorschemes.nord is a different plugin. Set
-        # up in ./config.lua.
+        # gbprod/nord.nvim (nixvim's colorschemes.nord is a different plugin);
+        # set up in ./config.lua.
         extraPlugins = [ pkgs.vimPlugins.gbprod-nord ];
 
         extraConfigLua = builtins.readFile ./config.lua;

modules/tmux/tmux.nix

@@ -3,10 +3,8 @@
   lib,
   ...
 }:
-# tmux for the primary user, configured natively through home-manager. The
-# settings home-manager exposes as options are set here; every setting it has
-# no option for is read verbatim from ./extra.conf. No tmux plugin manager is
-# used.
+# tmux for the primary user, configured through home-manager. Settings without a
+# home-manager option are read from ./extra.conf.
 let
   cfg = config.modules.tmux;
   user = config.user.name;
@@ -21,8 +19,8 @@ in
       prefix = "C-Space";
       keyMode = "vi";
       mouse = true;
-      baseIndex = 1; # windows and panes count from 1.
-      clock24 = true; # 24-hour clock in the clock-mode overlay.
+      baseIndex = 1;
+      clock24 = true;
       escapeTime = 10; # short Esc delay so exiting insert mode in nvim isn't laggy.
       historyLimit = 10000;
       terminal = "tmux-256color";