style: 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.

flake.nix

@@ -1,11 +1,11 @@
 {
-  description = "Alexion's NixOS configuration — one flake for every Host";
+  description = "Alexion's NixOS configuration — one flake for every host";
 
   inputs = {
-    # Base channel: nixos-unstable (rolling, but gated by the NixOS test suite).
+    # Base channel.
     nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
 
-    # Fresher-than-base packages, reachable per-package as `unstable.<name>`.
+    # Fresher packages, reachable per-package as `unstable.<name>`.
     nixpkgs-unstable.url = "github:nixos/nixpkgs/nixpkgs-unstable";
 
     # Latest stable release, reachable per-package as `stable.<name>`.
@@ -16,22 +16,20 @@
       inputs.nixpkgs.follows = "nixpkgs";
     };
 
-    # Neovim configured declaratively in Nix. Must follow our nixpkgs so its
+    # Follows our nixpkgs so its plugins build against the same package set.
-    # plugins build against the same package set.
     nixvim = {
       url = "github:nix-community/nixvim";
       inputs.nixpkgs.follows = "nixpkgs";
     };
 
-    # Declarative disk partitioning. Each Host declares its own layout; a Host
+    # Declarative disk partitioning; each host declares its own layout.
-    # that preserves an existing pool simply declares none.
     disko = {
       url = "github:nix-community/disko";
       inputs.nixpkgs.follows = "nixpkgs";
     };
 
-    # CachyOS kernel + binary cache. Deliberately NOT following our nixpkgs, so the
+    # CachyOS kernel and binary cache. Pins its own nixpkgs so its cache stays
-    # chaotic cache stays usable and the kernel is fetched rather than compiled.
+    # usable and the kernel is fetched from it.
     chaotic.url = "github:chaotic-cx/nyx/nyxpkgs-unstable";
   };
 
@@ -42,13 +40,13 @@
       my = import ./lib { inherit lib inputs self; };
     in
     {
-      # The trimmed helper lib: the Auto-loader, the host-builder, the script-from-file helper.
+      # Helper functions for discovering and building hosts.
       lib = my;
 
-      # Every Host under hosts/ is auto-discovered and built.
+      # Every host under hosts/ is discovered and built.
       nixosConfigurations = my.mkHosts (self + "/hosts");
 
-      # `nix flake check` builds each Host's toplevel — the primary test seam.
+      # `nix flake check` builds each host's toplevel.
       checks.x86_64-linux = lib.mapAttrs (
         _name: host: host.config.system.build.toplevel
       ) self.nixosConfigurations;

hosts/neogaia/default.nix

@@ -1,8 +1,6 @@
 { pkgs, ... }:
 # neogaia — Dell XPS 13 9380 laptop.
-#
+# Disk layout is in ./disk.nix; `fileSystems` are derived from it, none declared here.
-# The disk layout lives in ./disk.nix (disko); the resulting `fileSystems` are
-# derived from it, so none are declared by hand here.
 {
   imports = [
     ./hardware-configuration.nix
@@ -11,44 +9,34 @@
 
   system.stateVersion = "26.05";
 
-  # systemd-boot on the EFI system partition disko creates. The initrd prompts
+  # systemd-boot on the EFI system partition.
-  # for the LUKS passphrase (disko wires up boot.initrd.luks.devices), so a
-  # normal boot unlocks the encrypted root.
   boot.loader.systemd-boot.enable = true;
   boot.loader.efi.canTouchEfiVariables = true;
 
-  # neogaia runs the CachyOS kernel, selected per-Host via boot.kernelPackages.
   boot.kernelPackages = pkgs.linuxPackages_cachyos;
 
-  # Intel CPU microcode updates for the XPS 13's Core i7-8565U.
   hardware.cpu.intel.updateMicrocode = true;
 
-  # Redistributable firmware — carries the ath10k blobs the QCA6174 wifi needs.
+  # Redistributable firmware for the QCA6174 wifi (ath10k blobs).
   hardware.enableRedistributableFirmware = true;
 
-  # Swap is RAM-backed zram rather than an on-disk partition.
+  # RAM-backed swap; no on-disk swap partition.
   zramSwap.enable = true;
 
-  # NetworkManager drives the wifi so it can be joined from the console.
+  # So wifi can be joined from the console.
   networking.networkmanager.enable = true;
 
-  # An SSH daemon so the rest of the setup can be driven over the network.
+  # So setup can be driven over the network.
   services.openssh.enable = true;
 
   # fish as the login shell.
   modules.fish.enable = true;
   modules.fish.defaultShell = true;
 
-  # tmux as the terminal multiplexer.
   modules.tmux.enable = true;
-
-  # Neovim, configured declaratively via nixvim.
   modules.nvim.enable = true;
-
-  # Claude Code, Anthropic's CLI, installed via home-manager.
   modules.claude-code.enable = true;
 
-  # Locale preferences for the base system.
   time.timeZone = "America/New_York";
   i18n.defaultLocale = "en_GB.UTF-8";
   console.keyMap = "us";

hosts/neogaia/disk.nix

@@ -1,13 +1,7 @@
 { ... }:
-# neogaia's disk layout, declared with disko and interpreted by the disko module
+# neogaia's disk layout for disko: one NVMe disk, GPT, with an EFI system
-# the host-builder wires in. This is a per-Host concern: another Host declares a
+# partition and a LUKS container holding btrfs subvolumes. No swap partition;
-# different `disko.devices` (or none, preserving an existing pool by importing it).
+# swap is zram. disko derives `fileSystems` and `boot.initrd.luks.devices` from this.
-#
-# One NVMe disk, GPT: an EFI system partition for systemd-boot, and a LUKS
-# container holding a btrfs filesystem with subvolumes. Swap is zram (RAM-backed),
-# so there is deliberately no on-disk swap partition. disko derives the matching
-# `fileSystems.*` and `boot.initrd.luks.devices.*` from this, so a normal boot
-# prompts for the passphrase in the initrd and unlocks the encrypted root.
 {
   disko.devices.disk.main = {
     type = "disk";

hosts/neogaia/hardware-configuration.nix

@@ -1,6 +1,5 @@
 { lib, modulesPath, ... }:
-# Placeholder hardware profile for the XPS 13: the host platform and the initrd
+# Placeholder: regenerate with nixos-generate-config on the target machine.
-# modules the machine needs to evaluate and boot.
 {
   imports = [ (modulesPath + "/installer/scan/not-detected.nix") ];
 

lib/default.nix

@@ -13,10 +13,8 @@ let
     mapAttrsToList
     ;
 
-  # --- Auto-loader ---------------------------------------------------------
+  # Recursively collect every `.nix` file under `dir` as a flat list, for a
-  # Recursively collect every `.nix` file under `dir`, returned as a flat list
+  # module's `imports`.
-  # of paths suitable for a module `imports`: a directory recurses, a `.nix`
-  # file is taken, anything else is skipped.
   collectNixFiles =
     dir:
     flatten (
@@ -34,10 +32,9 @@ let
       ) (builtins.readDir dir)
     );
 
-  # --- Host-builder --------------------------------------------------------
+  # Build one host: every module is imported unconditionally (inert until its
-  # Build one Host: every Module is imported unconditionally (inert until its
+  # `enable` flag is set), alongside home-manager, chaotic, the shared base, and
-  # `enable` flag is set), alongside home-manager, chaotic, the shared base,
+  # the host's own directory.
-  # and the Host's own directory.
   mkHost =
     {
       hostName,
@@ -61,7 +58,7 @@ let
         ];
     };
 
-  # Discover every Host (a subdirectory of `hostsDir`) and build each one.
+  # Discover every host (a subdirectory of `hostsDir`) and build each one.
   mkHosts =
     hostsDir:
     let

modules/claude-code/claude-code.nix

@@ -3,19 +3,14 @@
   lib,
   ...
 }:
-# Claude Code — Anthropic's CLI — for the primary user, configured declaratively
+# Claude Code for the primary user, configured through home-manager, which ships
-# through home-manager. home-manager ships the package and manages ~/.claude:
+# the package and manages ~/.claude. Login credentials are left unmanaged so they
-# the global agent instructions (./CLAUDE.md), the skills tree (./skills), the
+# survive rebuilds.
-# 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.
 let
   cfg = config.modules.claude-code;
   user = config.user.name;
 
-  # Rings the terminal bell so tmux flags the background pane; wired to both the
+  # Rings the terminal bell so tmux flags the background pane.
-  # end of a turn and attention notifications below.
   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
+      # One directory per skill, symlinked under ~/.claude/skills.
-      # ~/.claude/skills.
       skills = ./skills;
 
-      # Installed executable at ~/.claude/hooks/attention-bell.sh, where the
+      # Installed at ~/.claude/hooks/attention-bell.sh, referenced by the settings below.
-      # settings hooks reference it.
       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
+# Reference example for the module shape: imported unconditionally, but inert
-# imported unconditionally but its body stays inert until a Host sets the
+# until a host sets its `enable` flag.
-# `enable` flag, so each Host reads as a checklist of `enable = true` lines.
 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
+# fish for the primary user, configured through home-manager.
-# 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`.
 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
+    # System-level fish registers it in /etc/shells and installs vendor completions.
-    # 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
+        eza # backs the ls/la/ll aliases
-        bat # syntax-highlighting cat/pager; backs the manpager below
+        bat # backs the manpager
-        fastfetch # system-info banner printed as the shell greeting
+        fastfetch # the shell greeting
-        wget # non-interactive HTTP downloader; backs the wget abbreviation
+        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
+        # Rendered by home-manager into ~/.config/fish/config.fish.
-        # ~/.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,
+# Neovim for the primary user, configured declaratively through nixvim. The
-# keymaps, and plugin settings are typed Nix; the imperative remainder (the
+# imperative remainder (colorscheme, Neogit blame autocmd) lives in ./config.lua.
-# 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.
 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
+        # gbprod/nord.nvim (nixvim's colorschemes.nord is a different plugin);
-        # up in ./config.lua.
+        # 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
+# tmux for the primary user, configured through home-manager. Settings without a
-# settings home-manager exposes as options are set here; every setting it has
+# home-manager option are read from ./extra.conf.
-# no option for is read verbatim from ./extra.conf. No tmux plugin manager is
-# used.
 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.
+      baseIndex = 1;
-      clock24 = true; # 24-hour clock in the clock-mode overlay.
+      clock24 = true;
       escapeTime = 10; # short Esc delay so exiting insert mode in nvim isn't laggy.
       historyLimit = 10000;
       terminal = "tmux-256color";

system/default.nix

@@ -5,13 +5,12 @@
   inputs,
   ...
 }:
-# The Skeleton's shared base config: the pieces every Host carries regardless of
+# Shared base config carried by every host.
-# which Modules it enables — overlays, the `user`, flakes, and home-manager.
 let
   inherit (lib) mkOption types;
   user = config.user;
 
-  # Instantiate an extra nixpkgs source for the same platform as the base pkgs.
+  # Args to instantiate an extra nixpkgs source on the base platform.
   pinArgs = prev: {
     inherit (prev.stdenv.hostPlatform) system;
     config.allowUnfree = true;
@@ -23,7 +22,7 @@ in
       type = types.str;
       default = "alexion";
       description = ''
-        The primary interactive user this Host is built for. Drives both the
+        The primary interactive user this host is built for. Drives both the
         system account and the home-manager user in lockstep.
       '';
     };
@@ -35,9 +34,8 @@ in
   };
 
   config = {
-    # Base is nixos-unstable; reach a package fresher with `unstable.<name>` or
+    # Reach fresher packages with `unstable.<name>` or pin with `stable.<name>`.
-    # pin it rock-solid with `stable.<name>`. chaotic's overlay is added by its
+    # chaotic's overlay is added by its own module, not here.
-    # own NixOS module, imported by the host-builder.
     nixpkgs.overlays = [
       (_final: prev: {
         unstable = import inputs.nixpkgs-unstable (pinArgs prev);
@@ -46,22 +44,21 @@ in
     ];
     nixpkgs.config.allowUnfree = true;
 
-    # Flakes + a baseline so `nixos-rebuild switch` works from the console.
+    # Flakes, so `nixos-rebuild switch` works from the console.
     nix.settings.experimental-features = [
       "nix-command"
       "flakes"
     ];
 
-    # The chaotic binary cache, so the CachyOS kernel is substituted rather than
+    # chaotic's binary cache, so the CachyOS kernel is fetched rather than
-    # compiled. Appended with the `extra-` options so cache.nixos.org and any
+    # compiled. The `extra-` prefix keeps cache.nixos.org alongside it.
-    # other substituter are kept alongside it.
     nix.settings.extra-substituters = [ "https://nyx-cache.chaotic.cx/" ];
     nix.settings.extra-trusted-public-keys = [
       "nyx-cache.chaotic.cx:dJxTrgMC3V3cFfyIiBQDQorG6k1LsqurH/srpMSq7qk="
     ];
     environment.systemPackages = [ pkgs.git ];
 
-    # Primary user, in wheel. No password is set here.
+    # Primary user, in the wheel group. No password set here.
     users.users.${user.name} = {
       isNormalUser = true;
       description = user.description;
@@ -69,8 +66,8 @@ in
     };
 
     # home-manager as a NixOS module: one `nixos-rebuild switch` builds the
-    # system and the user environment atomically, sharing the system's pkgs
+    # system and user environment together, sharing the system's pkgs and
-    # (with our overlays) and installing user packages into the system profile.
+    # installing user packages into the system profile.
     home-manager = {
       useGlobalPkgs = true;
       useUserPackages = true;