feat: Rewrote neomutt keybindings, updated comments

- Rewriting the neomutt keybindings by hand
- Updated comments to be simpler

103 files changed, 627 insertions, 561 deletions

diff --git a/modules/communication/default.nix b/modules/communication/default.nix
index 4dc805b..70afc8d 100644
--- a/modules/communication/default.nix
+++ b/modules/communication/default.nix
@@ -1,4 +1,4 @@
-# Communication - Email client modules
+# Email client modules
 { ... }:
 {
   imports = [
diff --git a/modules/communication/neomutt/account/default.nix b/modules/communication/neomutt/account/default.nix
index e6e60d2..f0b1cb1 100644
--- a/modules/communication/neomutt/account/default.nix
+++ b/modules/communication/neomutt/account/default.nix
@@ -1,4 +1,4 @@
-# Account - Converts neomutt account options into home-manager email config
+# Converts neomutt account options into home-manager email config
 { config, lib, ... }:
 {
   options.communication.neomutt.accounts = lib.mkOption {
diff --git a/modules/communication/neomutt/account/flavors/gmail.nix b/modules/communication/neomutt/account/flavors/gmail.nix
index 28ec979..ba39c58 100644
--- a/modules/communication/neomutt/account/flavors/gmail.nix
+++ b/modules/communication/neomutt/account/flavors/gmail.nix
@@ -1,4 +1,4 @@
-# Gmail - Gmail-specific defaults for folder names, mbsync patterns, and mailboxes
+# Gmail-specific defaults for folder names, mbsync patterns, and mailboxes
 {
   config,
   lib,
diff --git a/modules/communication/neomutt/account/options.nix b/modules/communication/neomutt/account/options.nix
index 3dd6c9f..45e6744 100644
--- a/modules/communication/neomutt/account/options.nix
+++ b/modules/communication/neomutt/account/options.nix
@@ -1,4 +1,4 @@
-# Options - Email account option definitions (realName, address, folders, gpg, etc.)
+# Email account option definitions
 { lib, ... }:
 {
   options = {
diff --git a/modules/communication/neomutt/assertions.nix b/modules/communication/neomutt/assertions.nix
index 5fad5c9..aa28502 100644
--- a/modules/communication/neomutt/assertions.nix
+++ b/modules/communication/neomutt/assertions.nix
@@ -1,4 +1,4 @@
-# Assertions - Validates neomutt dependencies (less, bat, kitty, chawan) are enabled
+# Validates neomutt dependencies are enabled
 { config, ... }:
 {
   assertions = [
diff --git a/modules/communication/neomutt/default.nix b/modules/communication/neomutt/default.nix
index 1512465..6d882e1 100644
--- a/modules/communication/neomutt/default.nix
+++ b/modules/communication/neomutt/default.nix
@@ -1,4 +1,4 @@
-# Neomutt - Email suite entry point (neomutt + mbsync + notmuch)
+# Email suite entry point
 {
   config,
   lib,
diff --git a/modules/communication/neomutt/keybindings.nix b/modules/communication/neomutt/keybindings.nix
index 59712fa..e9a3490 100644
--- a/modules/communication/neomutt/keybindings.nix
+++ b/modules/communication/neomutt/keybindings.nix
@@ -1,359 +1,485 @@
-# Keybindings - Vim-style keyboard shortcuts for neomutt
-#
-# Covers the core menus: generic (fallback), index, pager, sidebar,
-# attach, browser, compose. Menus like pgp/smime/mix/postpone/alias/query
-# are intentionally left mostly on defaults - they're rarely touched and
-# not worth risking an incorrect binding for. Press `?` inside neomutt
-# in any menu to see the live, authoritative list of bound functions.
 { config, lib, ... }:
+
 {
-  config.programs.neomutt.binds = lib.mkIf config.communication.neomutt.enable [
-    # --- sidebar navigation (vim: Ctrl-k=up, Ctrl-j=down) ---
-    {
-      map = [
-        "index"
-        "pager"
-      ];
-      key = "\\Ck";
-      action = "sidebar-prev";
-    }
-    {
-      map = [
-        "index"
-        "pager"
-      ];
-      key = "\\Cj";
-      action = "sidebar-next";
-    }
-    {
-      # jump into the highlighted mailbox
-      map = [
-        "index"
-        "pager"
-      ];
-      key = "\\Co";
-      action = "sidebar-open";
-    }
-    {
-      map = [
-        "index"
-        "pager"
-      ];
-      key = "\\Cp";
-      action = "sidebar-prev-new";
-    }
-    {
-      map = [
-        "index"
-        "pager"
-      ];
-      key = "\\Cn";
-      action = "sidebar-next-new";
-    }
-    {
-      # show/hide the sidebar column entirely
-      map = [
-        "index"
-        "pager"
-      ];
-      key = "B";
-      action = "sidebar-toggle-visible";
-    }
+  config.programs.neomutt.binds = lib.mkIf config.communication.neomutt.enable (
+    lib.mkMerge [
+      # Force noop bindings to the top of neomuttrc
+      (lib.mkBefore [
+        {
+          map = [
+            "generic"
+            "index"
+            "pager"
+            "browser"
+            "attach"
+            "compose"
+          ];
+          key = "z";
+          action = "noop";
+        }
+        {
+          map = [
+            "generic"
+            "index"
+            "pager"
+            "browser"
+            "attach"
+            "compose"
+          ];
+          key = "d";
+          action = "noop";
+        }
+        {
+          map = [
+            "generic"
+            "index"
+            "pager"
+            "browser"
+            "attach"
+            "compose"
+          ];
+          key = "g";
+          action = "noop";
+        }
+      ])
 
-    # --- basic entry navigation (generic = fallback for every list-style menu) ---
-    {
-      map = [ "generic" ];
-      key = "j";
-      action = "next-entry";
-    }
-    {
-      map = [ "generic" ];
-      key = "k";
-      action = "previous-entry";
-    }
-    {
-      map = [ "generic" ];
-      key = "gg";
-      action = "first-entry";
-    }
-    {
-      map = [
-        "index"
-        "generic"
-      ];
-      key = "G";
-      action = "last-entry";
-    }
+      # Other bindings
+      [
+        # Sidebar navigation
+        {
+          map = [
+            "index"
+            "pager"
+          ];
+          key = "\\Ck";
+          action = "sidebar-prev";
+        }
+        {
+          map = [
+            "index"
+            "pager"
+          ];
+          key = "\\Cj";
+          action = "sidebar-next";
+        }
+        {
+          map = [
+            "index"
+            "pager"
+          ];
+          key = "\\Co";
+          action = "sidebar-open";
+        }
+        {
+          map = [
+            "index"
+            "pager"
+          ];
+          key = "\\Cn";
+          action = "sidebar-toggle-visible";
+        }
 
-    # --- scroll-to-position, straight from vim (zt/zz/zb) ---
-    {
-      map = [ "generic" ];
-      key = "zt";
-      action = "current-top";
-    }
-    {
-      map = [ "generic" ];
-      key = "zz";
-      action = "current-middle";
-    }
-    {
-      map = [ "generic" ];
-      key = "zb";
-      action = "current-bottom";
-    }
+        # Basic movement
+        {
+          map = [ "generic" ];
+          key = "j";
+          action = "next-entry";
+        }
+        {
+          map = [ "generic" ];
+          key = "k";
+          action = "previous-entry";
+        }
+        {
+          map = [ "generic" ];
+          key = "gg";
+          action = "first-entry";
+        }
+        {
+          map = [
+            "index"
+            "generic"
+          ];
+          key = "G";
+          action = "last-entry";
+        }
+        {
+          map = [ "pager" ];
+          key = "h";
+          action = "exit";
+        }
+        {
+          map = [ "pager" ];
+          key = "l";
+          action = "view-attachments";
+        }
+        {
+          map = [ "index" ];
+          key = "l";
+          action = "display-message";
+        }
 
-    # --- pager scrolling ---
-    {
-      map = [ "pager" ];
-      key = "j";
-      action = "next-line";
-    }
-    {
-      map = [ "pager" ];
-      key = "k";
-      action = "previous-line";
-    }
-    {
-      map = [ "pager" ];
-      key = "gg";
-      action = "top";
-    }
-    {
-      map = [ "pager" ];
-      key = "G";
-      action = "bottom";
-    }
-    {
-      map = [
-        "generic"
-        "index"
-        "pager"
-      ];
-      key = "\\Cd";
-      action = "half-down";
-    }
-    {
-      map = [
-        "generic"
-        "index"
-        "pager"
-      ];
-      key = "\\Cu";
-      action = "half-up";
-    }
-    {
-      map = [
-        "generic"
-        "index"
-        "pager"
-      ];
-      key = "\\Cf";
-      action = "next-page";
-    }
-    {
-      # NOTE: Ctrl-B is deliberately left unbound in the pager map here -
-      # macros.nix claims it there for the chawan browser-view macro.
-      map = [ "index" ];
-      key = "\\Cb";
-      action = "previous-page";
-    }
+        # Scrolling
+        {
+          map = [ "generic" ];
+          key = "zt";
+          action = "current-top";
+        }
+        {
+          map = [ "generic" ];
+          key = "zz";
+          action = "current-middle";
+        }
+        {
+          map = [ "generic" ];
+          key = "zb";
+          action = "current-bottom";
+        }
+        {
+          map = [ "pager" ];
+          key = "j";
+          action = "next-line";
+        }
+        {
+          map = [ "pager" ];
+          key = "k";
+          action = "previous-line";
+        }
+        {
+          map = [ "pager" ];
+          key = "gg";
+          action = "top";
+        }
+        {
+          map = [ "pager" ];
+          key = "G";
+          action = "bottom";
+        }
+        {
+          map = [
+            "generic"
+            "index"
+            "pager"
+          ];
+          key = "\\Cd";
+          action = "half-down";
+        }
+        {
+          map = [
+            "generic"
+            "index"
+            "pager"
+          ];
+          key = "\\Cu";
+          action = "half-up";
+        }
+        {
+          map = [
+            "generic"
+            "index"
+            "pager"
+          ];
+          key = "\\Cf";
+          action = "next-page";
+        }
+        {
+          map = [ "index" ];
+          key = "\\Cb";
+          action = "previous-page";
+        }
 
-    # --- h/l as "back / go into", vim left/right ---
-    {
-      map = [ "pager" ];
-      key = "h";
-      action = "exit";
-    }
-    {
-      map = [ "pager" ];
-      key = "l";
-      action = "view-attachments";
-    }
-    {
-      map = [ "index" ];
-      key = "l";
-      action = "display-message";
-    }
+        # Searching and limiting
+        {
+          map = [
+            "generic"
+            "index"
+            "pager"
+          ];
+          key = "/";
+          action = "search";
+        }
+        {
+          map = [
+            "generic"
+            "index"
+            "pager"
+          ];
+          key = "?";
+          action = "search-reverse";
+        }
+        {
+          map = [
+            "generic"
+            "index"
+            "pager"
+          ];
+          key = "n";
+          action = "search-next";
+        }
+        {
+          map = [
+            "generic"
+            "index"
+            "pager"
+          ];
+          key = "N";
+          action = "search-opposite";
+        }
+        {
+          map = [ "index" ];
+          key = "gf";
+          action = "limit";
+        }
 
-    # --- search (mostly default already, restated for a complete reference) ---
-    {
-      map = [
-        "generic"
-        "index"
-        "pager"
-      ];
-      key = "/";
-      action = "search";
-    }
-    {
-      map = [
-        "generic"
-        "index"
-        "pager"
-      ];
-      key = "?";
-      action = "search-reverse";
-    }
-    {
-      map = [
-        "generic"
-        "index"
-        "pager"
-      ];
-      key = "n";
-      action = "search-next";
-    }
-    {
-      map = [
-        "generic"
-        "index"
-        "pager"
-      ];
-      key = "N";
-      action = "search-opposite";
-    }
+        # Message states and threads
+        {
+          map = [ "index" ];
+          key = "]";
+          action = "next-unread";
+        }
+        {
+          map = [ "index" ];
+          key = "[";
+          action = "previous-unread";
+        }
+        {
+          map = [ "index" ];
+          key = "}";
+          action = "next-new";
+        }
+        {
+          map = [ "index" ];
+          key = "{";
+          action = "previous-new";
+        }
+        {
+          map = [ "index" ];
+          key = "za";
+          action = "collapse-thread";
+        }
+        {
+          map = [ "index" ];
+          key = "zA";
+          action = "collapse-all";
+        }
 
-    # --- delete / undelete, vim dd ---
-    {
-      map = [
-        "index"
-        "pager"
-      ];
-      key = "dd";
-      action = "delete-message";
-    }
-    {
-      map = [ "index" ];
-      key = "dT";
-      action = "delete-thread";
-    }
-    {
-      map = [ "index" ];
-      key = "u";
-      action = "undelete-message";
-    }
-    {
-      map = [ "index" ];
-      key = "U";
-      action = "undelete-thread";
-    }
-    {
-      map = [ "attach" ];
-      key = "dd";
-      action = "delete-entry";
-    }
-    {
-      map = [ "attach" ];
-      key = "u";
-      action = "undelete-entry";
-    }
+        # Core email actions
+        {
+          map = [
+            "index"
+            "pager"
+          ];
+          key = "m";
+          action = "mail";
+        }
+        {
+          map = [
+            "index"
+            "pager"
+          ];
+          key = "r";
+          action = "reply";
+        }
+        {
+          map = [
+            "index"
+            "pager"
+          ];
+          key = "R";
+          action = "group-reply";
+        }
+        {
+          map = [
+            "index"
+            "pager"
+          ];
+          key = "f";
+          action = "forward-message";
+        }
+        {
+          map = [
+            "index"
+            "pager"
+          ];
+          key = "c";
+          action = "change-folder";
+        }
+        {
+          map = [
+            "index"
+            "pager"
+          ];
+          key = "s";
+          action = "save-message";
+        }
+        {
+          map = [
+            "index"
+            "pager"
+          ];
+          key = "y";
+          action = "copy-message";
+        }
+        {
+          map = [ "index" ];
+          key = "t";
+          action = "tag-entry";
+        }
+        {
+          map = [ "pager" ];
+          key = "t";
+          action = "tag-message";
+        }
+        {
+          map = [ "index" ];
+          key = "T";
+          action = "tag-thread";
+        }
+        {
+          map = [
+            "index"
+            "pager"
+          ];
+          key = "gh";
+          action = "display-toggle-weed";
+        }
 
-    # --- limit / filter the index, gf = filter, gF = clear filter ---
-    {
-      # prompts for a limit pattern; macros.nix binds gF to clear it
-      map = [ "index" ];
-      key = "gf";
-      action = "limit";
-    }
+        # Deletion and undeletion
+        {
+          map = [
+            "index"
+            "pager"
+          ];
+          key = "dd";
+          action = "delete-message";
+        }
+        {
+          map = [ "index" ];
+          key = "dT";
+          action = "delete-thread";
+        }
+        {
+          map = [
+            "index"
+            "pager"
+          ];
+          key = "u";
+          action = "undelete-message";
+        }
+        {
+          map = [ "index" ];
+          key = "U";
+          action = "undelete-thread";
+        }
+        {
+          map = [ "attach" ];
+          key = "dd";
+          action = "delete-entry";
+        }
+        {
+          map = [ "attach" ];
+          key = "u";
+          action = "undelete-entry";
+        }
 
-    # --- unread / new / flagged navigation ---
-    {
-      map = [ "index" ];
-      key = "]";
-      action = "next-unread";
-    }
-    {
-      map = [ "index" ];
-      key = "[";
-      action = "previous-unread";
-    }
-    {
-      map = [ "index" ];
-      key = "}";
-      action = "next-new";
-    }
-    {
-      map = [ "index" ];
-      key = "{";
-      action = "previous-new";
-    }
-    {
-      map = [ "index" ];
-      key = "gn";
-      action = "next-flagged";
-    }
-    {
-      map = [ "index" ];
-      key = "gp";
-      action = "previous-flagged";
-    }
+        # Menu specific
+        {
+          map = [ "attach" ];
+          key = "l";
+          action = "view-attach";
+        }
+        {
+          map = [ "attach" ];
+          key = "s";
+          action = "save-entry";
+        }
+        {
+          map = [ "attach" ];
+          key = "p";
+          action = "print-entry";
+        }
 
-    # --- attach menu ---
-    {
-      map = [ "attach" ];
-      key = "l";
-      action = "view-attach";
-    }
-    {
-      map = [ "attach" ];
-      key = "s";
-      action = "save-entry";
-    }
-    {
-      map = [ "attach" ];
-      key = "p";
-      action = "print-entry";
-    }
+        {
+          map = [ "browser" ];
+          key = "j";
+          action = "next-entry";
+        }
+        {
+          map = [ "browser" ];
+          key = "k";
+          action = "previous-entry";
+        }
+        {
+          map = [ "browser" ];
+          key = "gg";
+          action = "first-entry";
+        }
+        {
+          map = [ "browser" ];
+          key = "G";
+          action = "last-entry";
+        }
+        {
+          map = [ "browser" ];
+          key = "l";
+          action = "select-entry";
+        }
+        {
+          map = [ "browser" ];
+          key = "\\Cd";
+          action = "half-down";
+        }
+        {
+          map = [ "browser" ];
+          key = "\\Cu";
+          action = "half-up";
+        }
 
-    # --- browser (folder / file picker) ---
-    {
-      map = [ "browser" ];
-      key = "j";
-      action = "next-entry";
-    }
-    {
-      map = [ "browser" ];
-      key = "k";
-      action = "previous-entry";
-    }
-    {
-      map = [ "browser" ];
-      key = "gg";
-      action = "first-entry";
-    }
-    {
-      map = [ "browser" ];
-      key = "G";
-      action = "last-entry";
-    }
-    {
-      # neomutt has no dedicated "go up a directory" function - the ".."
-      # row is a normal entry, so l/Enter on it goes up just fine
-      map = [ "browser" ];
-      key = "l";
-      action = "select-entry";
-    }
-    {
-      map = [ "browser" ];
-      key = "\\Cd";
-      action = "half-down";
-    }
-    {
-      map = [ "browser" ];
-      key = "\\Cu";
-      action = "half-up";
-    }
+        {
+          map = [ "compose" ];
+          key = "j";
+          action = "next-entry";
+        }
+        {
+          map = [ "compose" ];
+          key = "k";
+          action = "previous-entry";
+        }
+        {
+          map = [ "compose" ];
+          key = "y";
+          action = "send-message";
+        }
+        {
+          map = [ "compose" ];
+          key = "a";
+          action = "attach-file";
+        }
+        {
+          map = [ "compose" ];
+          key = "e";
+          action = "edit-message";
+        }
+        {
+          map = [ "compose" ];
+          key = "p";
+          action = "postpone-message";
+        }
 
-    # --- compose menu ---
-    {
-      map = [ "compose" ];
-      key = "j";
-      action = "next-entry";
-    }
-    {
-      map = [ "compose" ];
-      key = "k";
-      action = "previous-entry";
-    }
-  ];
+        # Global exit
+        {
+          map = [
+            "generic"
+            "index"
+            "pager"
+            "browser"
+            "attach"
+            "compose"
+          ];
+          key = "q";
+          action = "exit";
+        }
+      ]
+    ]
+  );
 }
diff --git a/modules/communication/neomutt/macros.nix b/modules/communication/neomutt/macros.nix
index 4a1fd5d..9ad3593 100644
--- a/modules/communication/neomutt/macros.nix
+++ b/modules/communication/neomutt/macros.nix
@@ -1,10 +1,9 @@
-# Macros - neomutt macros for sync, URL extraction, flag legend, and quit
+# neomutt macros for sync, URL extraction, flag legend, and quit
 { config, lib, ... }:
 {
   config.programs.neomutt.macros = lib.mkIf config.communication.neomutt.enable [
     {
-      # sync the mailbox and run the external sync script, silencing the
-      # "press any key" prompt around it. Vim mnemonic: g-prefixed, "go sync".
+      # Sync the mailbox and run the external sync script
       map = [
         "index"
         "pager"
@@ -13,9 +12,7 @@
       action = "<enter-command>set my_wait_key=$wait_key wait_key=no<enter><sync-mailbox><shell-escape>${lib.getExe config.scripts.neomutt-sync.package}<enter><sync-mailbox><enter-command>set wait_key=$my_wait_key<enter>";
     }
     {
-      # extract every URL from the message via urlscan into a picker menu,
-      # then follow the selected one. Vim mnemonic: gx, same as vim-plugins
-      # that open the link/file under the cursor.
+      # Extract every URL from the message via urlscan into a picker menu
       map = [
         "index"
         "pager"
@@ -24,42 +21,31 @@
       action = "<pipe-message>urlscan<enter>";
     }
     {
-      # open the message body in interactive chawan -- real vim-style
-      # cursor navigation (hjkl, Tab/Shift-Tab between links, Enter to
-      # follow, B back, q to return to neomutt). Replaces the old
-      # urlscan-based link picker.
-      # Kept on Ctrl-B since that's common muscle-memory for "open this in
-      # a browser-like view" - previous-page is intentionally NOT bound to
-      # Ctrl-B in the pager (see binds.nix) so this doesn't get shadowed.
+      # Open the message body in interactive chawan with vim-style navigation
       map = [ "pager" ];
       key = "\\Cb";
       action = "<enter-command>set my_pipe_decode=$pipe_decode pipe_decode=yes<enter><pipe-message>${lib.getExe config.web.chawan.package} -o \"title='neomutt'\"<enter><enter-command>set pipe_decode=$my_pipe_decode<enter>";
     }
     {
-      # on a specific attachment (not just the top-level
-      # message): pipe-entry sends the selected attachment instead.
-      # Same gx mnemonic as the index/pager macro above.
+      # Pipe the selected attachment instead of the whole message
       map = [ "attach" ];
       key = "gx";
       action = "<pipe-entry>${lib.getExe config.web.chawan.package} -o \"title='neomutt'\" <enter>";
     }
     {
-      # clear the current limit/filter and show every message again,
-      # the counterpart to gf (interactive limit prompt) in binds.nix
+      # Clear the current limit and show every message again
       map = [ "index" ];
       key = "gF";
       action = "<limit>all<enter>";
     }
     {
-      # save and quit, vim-style (sync mailbox, then quit) - same ZZ
-      # you'd type in vim to write and exit
+      # Save the mailbox and quit
       map = [ "index" ];
       key = "ZZ";
       action = "<sync-mailbox><quit>";
     }
     {
-      # quit without saving, vim-style counterpart to ZZ - same ZQ
-      # you'd type in vim to discard and exit
+      # Quit without saving
       map = [ "index" ];
       key = "ZQ";
       action = "<exit>";
diff --git a/modules/communication/neomutt/neomutt.nix b/modules/communication/neomutt/neomutt.nix
index 997c948..e25d0b3 100644
--- a/modules/communication/neomutt/neomutt.nix
+++ b/modules/communication/neomutt/neomutt.nix
@@ -1,4 +1,4 @@
-# neomutt - Terminal email client
+# Terminal email client
 {
   config,
   lib,
@@ -44,7 +44,7 @@
       };
       sidebar.enable = true;
       sort = "reverse-threads";
-      vimKeys = true;
+      vimKeys = false;
       unmailboxes = true;
       checkStatsInterval = 20;
       extraConfig = builtins.readFile ./.neomuttrc;
diff --git a/modules/communication/neomutt/sync/default.nix b/modules/communication/neomutt/sync/default.nix
index 2fcaa18..629a655 100644
--- a/modules/communication/neomutt/sync/default.nix
+++ b/modules/communication/neomutt/sync/default.nix
@@ -1,4 +1,4 @@
-# Sync - Mail synchronization modules (mbsync, notmuch)
+# Mail synchronization modules
 { ... }:
 {
   imports = [
diff --git a/modules/communication/neomutt/sync/mbsync.nix b/modules/communication/neomutt/sync/mbsync.nix
index 7642099..28b7b2c 100644
--- a/modules/communication/neomutt/sync/mbsync.nix
+++ b/modules/communication/neomutt/sync/mbsync.nix
@@ -1,4 +1,4 @@
-# Mbsync - Mailbox synchronization (isync/mbsync)
+# Mailbox synchronization
 { config, lib, ... }:
 {
   config = lib.mkIf config.communication.neomutt.enable {
diff --git a/modules/communication/neomutt/sync/notmuch.nix b/modules/communication/neomutt/sync/notmuch.nix
index 277b232..6f806fb 100644
--- a/modules/communication/neomutt/sync/notmuch.nix
+++ b/modules/communication/neomutt/sync/notmuch.nix
@@ -1,4 +1,4 @@
-# Notmuch - Mail indexer for fast email search
+# Mail indexer for fast email search
 { config, lib, ... }:
 {
   config = lib.mkIf config.communication.neomutt.enable {
diff --git a/modules/default.nix b/modules/default.nix
index eb06ff1..f537af4 100644
--- a/modules/default.nix
+++ b/modules/default.nix
@@ -1,4 +1,4 @@
-# Modules - Top-level module aggregator importing all submodules
+# Top-level module aggregator importing all submodules
 { config, ... }:
 {
   imports = [
diff --git a/modules/desktop/darkman/default.nix b/modules/desktop/darkman/default.nix
index 9dc7ef9..a7bf598 100644
--- a/modules/desktop/darkman/default.nix
+++ b/modules/desktop/darkman/default.nix
@@ -1,4 +1,4 @@
-# Darkman - Automatic dark/light mode switching based on time of day
+# Automatic dark and light mode switching based on time of day
 {
   config,
   lib,
diff --git a/modules/desktop/default.nix b/modules/desktop/default.nix
index 15ad896..6521927 100644
--- a/modules/desktop/default.nix
+++ b/modules/desktop/default.nix
@@ -1,4 +1,4 @@
-# Desktop - Desktop environment configuration (Hyprland, darkman, waybar)
+# Desktop environment configuration
 {
   lib,
   config,
diff --git a/modules/desktop/rofi/theme.mustache.rasi b/modules/desktop/rofi/theme.mustache.rasi
index 9d161ec..b2005c1 100644
--- a/modules/desktop/rofi/theme.mustache.rasi
+++ b/modules/desktop/rofi/theme.mustache.rasi
@@ -1,23 +1,5 @@
-/**
- * Rofi Theme — Base16 "OneDark Dark" (olimorris)
- * Mustache template: render with a base16 color map to produce a .rasi file
- *
- * base00 - default background
- * base01 - lighter background (status bar, line numbers)
- * base02 - selection background
- * base03 - comments, invisibles
- * base04 - dark foreground (status bar)
- * base05 - default foreground
- * base06 - light foreground
- * base07 - lightest foreground
- * base08 - red      (errors, urgent)
- * base09 - orange    (numbers)
- * base0A - yellow    (search matches)
- * base0B - green     (strings)
- * base0C - cyan      (support, regex)
- * base0D - blue      (functions, active/selected)
- * base0E - purple/magenta (keywords)
- * base0F - brown     (deprecated)
+/*
+ * Rofi theme based on the Base16 OneDark Dark theme, rendered from a mustache template
  */
 
 * {
diff --git a/modules/desktop/waybar/style.mustache.css b/modules/desktop/waybar/style.mustache.css
index ddeaa88..a5f458e 100644
--- a/modules/desktop/waybar/style.mustache.css
+++ b/modules/desktop/waybar/style.mustache.css
@@ -1,23 +1,5 @@
 /*
- * Waybar Style — Base16 "OneDark Dark" (olimorris)
- * Mustache template: render with a base16 color map to produce a .css file
- *
- * base00 - default background
- * base01 - lighter background (status bar, line numbers)
- * base02 - selection background
- * base03 - comments, invisibles
- * base04 - dark foreground (status bar)
- * base05 - default foreground
- * base06 - light foreground
- * base07 - lightest foreground
- * base08 - red      (errors, urgent)
- * base09 - orange    (numbers)
- * base0A - yellow    (search matches)
- * base0B - green     (strings)
- * base0C - cyan      (support, regex)
- * base0D - blue      (functions, active/selected)
- * base0E - purple/magenta (keywords)
- * base0F - brown     (deprecated)
+ * Waybar style based on the Base16 OneDark Dark theme, rendered from a mustache template
  */
 
 * {
diff --git a/modules/desktop/xdg/default.nix b/modules/desktop/xdg/default.nix
index 400d91d..d0a8358 100644
--- a/modules/desktop/xdg/default.nix
+++ b/modules/desktop/xdg/default.nix
@@ -1,4 +1,4 @@
-# xdg - XDG Desktop Portal configuration
+# XDG Desktop Portal configuration
 {
   config,
   lib,
diff --git a/modules/development/bruno/default.nix b/modules/development/bruno/default.nix
index e43e329..8684264 100644
--- a/modules/development/bruno/default.nix
+++ b/modules/development/bruno/default.nix
@@ -1,4 +1,4 @@
-# Bruno - Open-source API client for testing HTTP endpoints
+# Open-source API client for testing HTTP endpoints
 {
   config,
   lib,
diff --git a/modules/development/default.nix b/modules/development/default.nix
index 6ae109e..1441fe2 100644
--- a/modules/development/default.nix
+++ b/modules/development/default.nix
@@ -1,4 +1,4 @@
-# Development - Development tools module (bruno, delta, git, lazygit, nixvim, opencode, qemu, vscodium)
+# Development tools module
 { ... }:
 
 {
diff --git a/modules/development/delta/default.nix b/modules/development/delta/default.nix
index bbfe9dd..b35e5a6 100644
--- a/modules/development/delta/default.nix
+++ b/modules/development/delta/default.nix
@@ -1,4 +1,4 @@
-# Delta - A syntax-highlighting pager for git, diff, and grep output
+# A syntax-highlighting pager for git, diff, and grep output
 {
   config,
   lib,
diff --git a/modules/development/git/assertions.nix b/modules/development/git/assertions.nix
index c18c847..02acd92 100644
--- a/modules/development/git/assertions.nix
+++ b/modules/development/git/assertions.nix
@@ -1,4 +1,4 @@
-# Assertions - Validates SSH is enabled when git.useSSH is set
+# Validates SSH is enabled when git.useSSH is set
 { config, ... }:
 {
   assertions = [
diff --git a/modules/development/git/default.nix b/modules/development/git/default.nix
index 5937c2f..9a937f5 100644
--- a/modules/development/git/default.nix
+++ b/modules/development/git/default.nix
@@ -1,4 +1,4 @@
-# Git - Distributed version control system
+# Distributed version control system
 {
   config,
   lib,
diff --git a/modules/development/lazygit/assertions.nix b/modules/development/lazygit/assertions.nix
index b79cfb4..2539af6 100644
--- a/modules/development/lazygit/assertions.nix
+++ b/modules/development/lazygit/assertions.nix
@@ -1,4 +1,4 @@
-# Assertions - LazyGit only makes sense when Git is enabled
+# LazyGit only makes sense when Git is enabled
 { config, ... }:
 {
   assertions = [
diff --git a/modules/development/lazygit/default.nix b/modules/development/lazygit/default.nix
index b75ebeb..b490f4f 100644
--- a/modules/development/lazygit/default.nix
+++ b/modules/development/lazygit/default.nix
@@ -1,4 +1,4 @@
-# Lazygit - A simple terminal UI for git commands
+# A simple terminal UI for git commands
 { config, lib, ... }:
 {
   imports = [
diff --git a/modules/development/nixvim/colorscheme.nix b/modules/development/nixvim/colorscheme.nix
index 00345cf..1569cb5 100644
--- a/modules/development/nixvim/colorscheme.nix
+++ b/modules/development/nixvim/colorscheme.nix
@@ -1,4 +1,4 @@
-# Colorscheme - Base16 theme configuration for nixvim
+# Base16 theme configuration for nixvim
 { config, lib, ... }:
 {
   config.programs.nixvim.colorschemes.base16 = lib.mkIf config.development.nixvim.enable {
diff --git a/modules/development/nixvim/default.nix b/modules/development/nixvim/default.nix
index c212560..17705fa 100644
--- a/modules/development/nixvim/default.nix
+++ b/modules/development/nixvim/default.nix
@@ -1,4 +1,4 @@
-# Nixvim - Neovim configured through Nix (home-manager integration)
+# Neovim configured through Nix
 { config, lib, ... }:
 {
   imports = [
diff --git a/modules/development/nixvim/keymaps.nix b/modules/development/nixvim/keymaps.nix
index 88fa841..95e1f24 100644
--- a/modules/development/nixvim/keymaps.nix
+++ b/modules/development/nixvim/keymaps.nix
@@ -1,4 +1,4 @@
-# Keymaps - Keyboard shortcut configuration for nixvim
+# Keyboard shortcut configuration for nixvim
 { config, lib, ... }:
 {
   config.programs.nixvim.keymaps = lib.mkIf config.development.nixvim.enable [
diff --git a/modules/development/nixvim/plugins/cmp.nix b/modules/development/nixvim/plugins/cmp.nix
index 4affdd4..b2347ba 100644
--- a/modules/development/nixvim/plugins/cmp.nix
+++ b/modules/development/nixvim/plugins/cmp.nix
@@ -1,4 +1,4 @@
-# Cmp - Completion plugin (nvim-cmp) for auto-completion
+# Completion plugin for auto-completion
 { config, lib, ... }:
 {
   config.programs.nixvim.plugins.cmp = lib.mkIf config.development.nixvim.enable {
diff --git a/modules/development/nixvim/plugins/comment.nix b/modules/development/nixvim/plugins/comment.nix
index 8170ea4..10bed84 100644
--- a/modules/development/nixvim/plugins/comment.nix
+++ b/modules/development/nixvim/plugins/comment.nix
@@ -1,4 +1,4 @@
-# Comment - Comment toggling plugin (comment.nvim)
+# Comment toggling plugin
 { config, lib, ... }:
 {
   config.programs.nixvim.plugins.comment = lib.mkIf config.development.nixvim.enable {
diff --git a/modules/development/nixvim/plugins/default.nix b/modules/development/nixvim/plugins/default.nix
index f11a2d5..c7ebea4 100644
--- a/modules/development/nixvim/plugins/default.nix
+++ b/modules/development/nixvim/plugins/default.nix
@@ -1,4 +1,4 @@
-# Plugins - Collection of nixvim plugin configurations
+# Collection of nixvim plugin configurations
 { ... }:
 {
   imports = [
diff --git a/modules/development/nixvim/plugins/gitsigns.nix b/modules/development/nixvim/plugins/gitsigns.nix
index a35a5d8..38ad85f 100644
--- a/modules/development/nixvim/plugins/gitsigns.nix
+++ b/modules/development/nixvim/plugins/gitsigns.nix
@@ -1,4 +1,4 @@
-# Gitsigns - Git status in the sign column (gitsigns.nvim)
+# Git status in the sign column
 { config, lib, ... }:
 {
   config.programs.nixvim.plugins.gitsigns = lib.mkIf config.development.nixvim.enable {
diff --git a/modules/development/nixvim/plugins/indent-blankline.nix b/modules/development/nixvim/plugins/indent-blankline.nix
index a07b361..6890dbf 100644
--- a/modules/development/nixvim/plugins/indent-blankline.nix
+++ b/modules/development/nixvim/plugins/indent-blankline.nix
@@ -1,4 +1,4 @@
-# Indent-blankline - Visual indentation guides (indent-blankline.nvim)
+# Visual indentation guides
 { config, lib, ... }:
 {
   config.programs.nixvim.plugins.indent-blankline = lib.mkIf config.development.nixvim.enable {
diff --git a/modules/development/nixvim/plugins/lsp.nix b/modules/development/nixvim/plugins/lsp.nix
index 46bd897..0a92f86 100644
--- a/modules/development/nixvim/plugins/lsp.nix
+++ b/modules/development/nixvim/plugins/lsp.nix
@@ -1,4 +1,4 @@
-# LSP - Language Server Protocol configuration (nvim-lspconfig)
+# Language Server Protocol configuration
 { config, lib, ... }:
 {
   config.programs.nixvim.plugins.lsp = lib.mkIf config.development.nixvim.enable {
@@ -15,7 +15,7 @@
     };
 
     servers = {
-      # -- System & Configuration --
+      # System and configuration
       nixd = {
         enable = true;
         package = null;
@@ -23,7 +23,7 @@
       bashls = {
         enable = true;
         package = null;
-      }; # Bash/Shell
+      }; # Bash shell
       taplo = {
         enable = true;
         package = null;
@@ -41,7 +41,7 @@
         package = null;
       }; # Markdown
 
-      # -- Web Development (HTML/CSS/JS/TS) --
+      # Web development
       html = {
         enable = true;
         package = null;
@@ -49,17 +49,17 @@
       cssls = {
         enable = true;
         package = null;
-      }; # CSS/SCSS/LESS
+      }; # CSS, SCSS and LESS
       tailwindcss = {
         enable = true;
         package = null;
       }; # Tailwind CSS
       vtsls = {
-        # JS/TS (Modern fast wrapper for tsserver)
+        # JS and TS fast wrapper for tsserver
         enable = true;
         package = null;
         settings = {
-          # Optional but recommended: stops huge generic types from taking over your screen
+          # Limits huge generic type hints
           vtsls.experimental.maxInlayHintLength = 30;
 
           # TypeScript type inferences
@@ -72,7 +72,7 @@
             enumMemberValues.enabled = true;
           };
 
-          # JavaScript type inferences (via JSDoc)
+          # JavaScript type inferences
           javascript.inlayHints = {
             parameterNames.enabled = "all";
             parameterTypes.enabled = true;
@@ -86,9 +86,9 @@
       eslint = {
         enable = true;
         package = null;
-      }; # ESLint diagnostics/formatting
+      }; # ESLint diagnostics and formatting
 
-      # -- Web Frameworks --
+      # Web frameworks
       volar = {
         # Vue
         enable = true;
@@ -104,26 +104,26 @@
         package = null;
       }; # Astro
 
-      # -- Scripting & High-Level Languages --
+      # Scripting and high-level languages
       basedpyright = {
-        # Python (Modern, faster fork of Pyright)
+        # Python, modern faster fork of Pyright
         enable = true;
         package = null;
         settings.basedpyright.analysis.inlayHints = {
           variableTypes = true;
           callArgumentNames = true;
           functionReturnTypes = true;
-          genericTypes = false; # can get noisy, opt-in
+          genericTypes = false; # Opt in since these can get noisy
         };
       };
       ruff = {
         enable = true;
         package = null;
-      }; # Python (Ultra-fast linter/formatter)
+      }; # Python linter and formatter
       ruby_lsp = {
         enable = true;
         package = null;
-      }; # Ruby (Shopify's modern standard)
+      }; # Ruby
       lua_ls = {
         # Lua
         enable = true;
@@ -145,13 +145,13 @@
         package = null;
       }; # Elixir
 
-      # -- Systems, Compiled, & Enterprise --
+      # Systems, compiled and enterprise
       clangd = {
         enable = true;
         package = null;
-      }; # C/C++ (inlay hints on by default)
+      }; # C and C++ with inlay hints on by default
       rust_analyzer = {
-        # Rust (inlay hints on by default)
+        # Rust with inlay hints on by default
         enable = true;
         package = null;
         installCargo = false;
@@ -174,7 +174,7 @@
       zls = {
         enable = true;
         package = null;
-      }; # Zig (inlay hints on by default)
+      }; # Zig with inlay hints on by default
       jdtls = {
         # Java
         enable = true;
@@ -188,7 +188,7 @@
       csharp_ls = {
         enable = true;
         package = null;
-      }; # C# (.NET) — no inlay hint support
+      }; # C# without inlay hint support
       hls = {
         # Haskell
         enable = true;
@@ -201,7 +201,7 @@
         package = null;
       }; # OCaml
 
-      # -- Infrastructure & DevOps --
+      # Infrastructure and DevOps
       dockerls = {
         enable = true;
         package = null;
@@ -213,9 +213,9 @@
       terraformls = {
         enable = true;
         package = null;
-      }; # Terraform/HCL
+      }; # Terraform and HCL
 
-      # -- Data & APIs --
+      # Data and APIs
       sqlls = {
         enable = true;
         package = null;
diff --git a/modules/development/nixvim/plugins/lualine.nix b/modules/development/nixvim/plugins/lualine.nix
index ab46499..560a055 100644
--- a/modules/development/nixvim/plugins/lualine.nix
+++ b/modules/development/nixvim/plugins/lualine.nix
@@ -1,4 +1,4 @@
-# Lualine - Statusline configuration (lualine.nvim)
+# Statusline configuration
 { config, lib, ... }:
 {
   config.programs.nixvim.plugins.lualine = lib.mkIf config.development.nixvim.enable {
diff --git a/modules/development/nixvim/plugins/luasnip.nix b/modules/development/nixvim/plugins/luasnip.nix
index e704435..cab0f62 100644
--- a/modules/development/nixvim/plugins/luasnip.nix
+++ b/modules/development/nixvim/plugins/luasnip.nix
@@ -1,4 +1,4 @@
-# Luasnip - Snippet engine for Neovim (Lua-based)
+# Snippet engine for Neovim
 { config, lib, ... }:
 {
   config.programs.nixvim.plugins.luasnip = lib.mkIf config.development.nixvim.enable {
diff --git a/modules/development/nixvim/plugins/noice.nix b/modules/development/nixvim/plugins/noice.nix
index 622f8d5..8f2ea0d 100644
--- a/modules/development/nixvim/plugins/noice.nix
+++ b/modules/development/nixvim/plugins/noice.nix
@@ -1,4 +1,4 @@
-# Noice - Modern UI for Neovim (cmdline, popupmenu, messages)
+# Modern UI for Neovim
 { config, lib, ... }:
 {
   config.programs.nixvim.plugins.noice = lib.mkIf config.development.nixvim.enable {
diff --git a/modules/development/nixvim/plugins/nvim-tree.nix b/modules/development/nixvim/plugins/nvim-tree.nix
index c3b104d..2f35e3c 100644
--- a/modules/development/nixvim/plugins/nvim-tree.nix
+++ b/modules/development/nixvim/plugins/nvim-tree.nix
@@ -1,4 +1,4 @@
-# Nvim-tree - File explorer sidebar (nvim-tree.lua)
+# File explorer sidebar
 { config, lib, ... }:
 {
   config.programs.nixvim.plugins.nvim-tree = lib.mkIf config.development.nixvim.enable {
diff --git a/modules/development/nixvim/plugins/telescope.nix b/modules/development/nixvim/plugins/telescope.nix
index dc873fd..8f06ec9 100644
--- a/modules/development/nixvim/plugins/telescope.nix
+++ b/modules/development/nixvim/plugins/telescope.nix
@@ -1,11 +1,11 @@
-# Telescope - Fuzzy finder
+# Fuzzy finder
 { config, lib, ... }:
 {
   config.programs.nixvim.plugins.telescope = lib.mkIf config.development.nixvim.enable {
     enable = true;
     extensions = {
-      fzf-native.enable = true; # faster fuzzy sorting
-      ui-select.enable = true; # use telescope for vim.ui.select (code actions etc.)
+      fzf-native.enable = true; # Faster fuzzy sorting
+      ui-select.enable = true; # Uses telescope for vim.ui.select
     };
     settings = {
       defaults = {
diff --git a/modules/development/nixvim/plugins/treesitter.nix b/modules/development/nixvim/plugins/treesitter.nix
index d462792..6150ad2 100644
--- a/modules/development/nixvim/plugins/treesitter.nix
+++ b/modules/development/nixvim/plugins/treesitter.nix
@@ -1,4 +1,4 @@
-# Treesitter - Syntax highlighting and parsing (nvim-treesitter)
+# Syntax highlighting and parsing
 { config, lib, ... }:
 {
   config.programs.nixvim.plugins.treesitter = lib.mkIf config.development.nixvim.enable {
diff --git a/modules/development/nixvim/plugins/web-devicons.nix b/modules/development/nixvim/plugins/web-devicons.nix
index d222df4..61ca5e9 100644
--- a/modules/development/nixvim/plugins/web-devicons.nix
+++ b/modules/development/nixvim/plugins/web-devicons.nix
@@ -1,4 +1,4 @@
-# Web-devicons - File icons for various file types (nvim-web-devicons)
+# File icons for various file types
 { config, lib, ... }:
 {
   config.programs.nixvim.plugins.web-devicons = lib.mkIf config.development.nixvim.enable {
diff --git a/modules/development/nixvim/plugins/which-key.nix b/modules/development/nixvim/plugins/which-key.nix
index ea55615..81ecd14 100644
--- a/modules/development/nixvim/plugins/which-key.nix
+++ b/modules/development/nixvim/plugins/which-key.nix
@@ -1,4 +1,4 @@
-# Which-key - Popup for keybindings (which-key.nvim)
+# Popup for keybindings
 { config, lib, ... }:
 {
   config.programs.nixvim.plugins.which-key = lib.mkIf config.development.nixvim.enable {
diff --git a/modules/development/opencode/default.nix b/modules/development/opencode/default.nix
index c41918a..3cbc05e 100644
--- a/modules/development/opencode/default.nix
+++ b/modules/development/opencode/default.nix
@@ -1,4 +1,4 @@
-# Opencode - AI-powered coding assistant (opencode.ai)
+# AI-powered coding assistant
 {
   config,
   lib,
diff --git a/modules/development/qemu/default.nix b/modules/development/qemu/default.nix
index 750ff4b..c426e75 100644
--- a/modules/development/qemu/default.nix
+++ b/modules/development/qemu/default.nix
@@ -1,4 +1,4 @@
-# QEMU - generic and open source machine & userspace emulator and virtualizer.
+# generic and open source machine and userspace emulator and virtualizer
 {
   config,
   lib,
diff --git a/modules/development/vscodium/default.nix b/modules/development/vscodium/default.nix
index 28e5857..b365768 100644
--- a/modules/development/vscodium/default.nix
+++ b/modules/development/vscodium/default.nix
@@ -1,4 +1,4 @@
-# VSCodium - Visual Studio Code fork
+# Visual Studio Code fork
 {
   config,
   lib,
diff --git a/modules/file-management/default.nix b/modules/file-management/default.nix
index 304097a..349e708 100644
--- a/modules/file-management/default.nix
+++ b/modules/file-management/default.nix
@@ -1,4 +1,4 @@
-# File Management - File manager and utility modules (yazi, lsd, ouch)
+# File manager and utility modules
 { ... }:
 {
   imports = [
diff --git a/modules/file-management/lsd/default.nix b/modules/file-management/lsd/default.nix
index b082989..995fd29 100644
--- a/modules/file-management/lsd/default.nix
+++ b/modules/file-management/lsd/default.nix
@@ -1,4 +1,4 @@
-# LSD - Ls alternative with icons and colors (Rust-based)
+# Ls alternative with icons and colors
 { config, lib, ... }:
 {
   options.file-management.lsd = {
diff --git a/modules/file-management/ouch/default.nix b/modules/file-management/ouch/default.nix
index 01a865a..c8986fe 100644
--- a/modules/file-management/ouch/default.nix
+++ b/modules/file-management/ouch/default.nix
@@ -1,4 +1,4 @@
-# Ouch! - CLI tool for compressing and decompressing various formats.
+# CLI tool for compressing and decompressing various formats
 {
   pkgs,
   lib,
diff --git a/modules/file-management/yazi/assertions.nix b/modules/file-management/yazi/assertions.nix
index b100fca..599b8b5 100644
--- a/modules/file-management/yazi/assertions.nix
+++ b/modules/file-management/yazi/assertions.nix
@@ -1,4 +1,4 @@
-# Assertions - Validates kitty is enabled for yazi desktop entry
+# Validates kitty is enabled for yazi desktop entry
 { config, ... }:
 {
   assertions = [
diff --git a/modules/file-management/yazi/default.nix b/modules/file-management/yazi/default.nix
index f9bd98a..2692240 100644
--- a/modules/file-management/yazi/default.nix
+++ b/modules/file-management/yazi/default.nix
@@ -1,4 +1,4 @@
-# yazi - Terminal file manager with native previews
+# Terminal file manager with native previews
 { config, lib, ... }:
 {
   imports = [
diff --git a/modules/fonts/default.nix b/modules/fonts/default.nix
index 2d13d52..7f71c2e 100644
--- a/modules/fonts/default.nix
+++ b/modules/fonts/default.nix
@@ -1,4 +1,4 @@
-# Fonts - Font configuration (Fira Code Nerd Font)
+# Font configuration
 {
   lib,
   config,
diff --git a/modules/gaming/default.nix b/modules/gaming/default.nix
index 463c138..d2b2d5f 100644
--- a/modules/gaming/default.nix
+++ b/modules/gaming/default.nix
@@ -1,4 +1,4 @@
-# Gaming - Collection of game launchers and gaming utilities
+# Collection of game launchers and gaming utilities
 { ... }:
 {
   imports = [
diff --git a/modules/gaming/heroic/default.nix b/modules/gaming/heroic/default.nix
index 591e60b..c1fb1de 100644
--- a/modules/gaming/heroic/default.nix
+++ b/modules/gaming/heroic/default.nix
@@ -1,4 +1,4 @@
-# Heroic Games Launcher - Epic/GOG/Amazon game launcher
+# Epic, GOG and Amazon game launcher
 {
   config,
   pkgs,
diff --git a/modules/gaming/steam/default.nix b/modules/gaming/steam/default.nix
index ba3cf0f..5662656 100644
--- a/modules/gaming/steam/default.nix
+++ b/modules/gaming/steam/default.nix
@@ -1,4 +1,4 @@
-# Steam - game store
+# Game store
 {
   config,
   pkgs,
diff --git a/modules/media/default.nix b/modules/media/default.nix
index b7c744f..74cc62d 100644
--- a/modules/media/default.nix
+++ b/modules/media/default.nix
@@ -1,4 +1,4 @@
-# Media - Multimedia tools (swayimg, grim, pamixer, playerctl, slurp, vlc, wf-recorder)
+# Multimedia tools
 { ... }:
 {
   imports = [
diff --git a/modules/media/grim/default.nix b/modules/media/grim/default.nix
index b8d3645..5a0536c 100644
--- a/modules/media/grim/default.nix
+++ b/modules/media/grim/default.nix
@@ -1,4 +1,4 @@
-# Grim - Screenshot utility for wlroots Wayland compositors
+# Screenshot utility for wlroots Wayland compositors
 {
   config,
   lib,
diff --git a/modules/media/pamixer/default.nix b/modules/media/pamixer/default.nix
index 9f47c68..9934648 100644
--- a/modules/media/pamixer/default.nix
+++ b/modules/media/pamixer/default.nix
@@ -1,4 +1,4 @@
-# Pamixer - PulseAudio command-line mixer (volume control)
+# PulseAudio command-line mixer
 {
   config,
   lib,
diff --git a/modules/media/playerctl/default.nix b/modules/media/playerctl/default.nix
index 53ac353..3c15f11 100644
--- a/modules/media/playerctl/default.nix
+++ b/modules/media/playerctl/default.nix
@@ -1,4 +1,4 @@
-# Playerctl - CLI for controlling media players (Spotify, MPRIS, etc.)
+# CLI for controlling media players
 {
   config,
   lib,
diff --git a/modules/media/slurp/default.nix b/modules/media/slurp/default.nix
index 6288e14..39a8a12 100644
--- a/modules/media/slurp/default.nix
+++ b/modules/media/slurp/default.nix
@@ -1,4 +1,4 @@
-# Slurp - Region selector for wlroots Wayland compositors (used by grim)
+# Region selector for wlroots Wayland compositors
 {
   config,
   lib,
diff --git a/modules/media/vlc/default.nix b/modules/media/vlc/default.nix
index 7caf93c..0d32e3b 100644
--- a/modules/media/vlc/default.nix
+++ b/modules/media/vlc/default.nix
@@ -1,4 +1,4 @@
-# VLC - Versatile multimedia player for audio/video playback
+# Versatile multimedia player for audio and video playback
 {
   config,
   lib,
diff --git a/modules/media/wf-recorder/default.nix b/modules/media/wf-recorder/default.nix
index 60e6f4c..6f19a38 100644
--- a/modules/media/wf-recorder/default.nix
+++ b/modules/media/wf-recorder/default.nix
@@ -1,4 +1,4 @@
-# Wf-recorder - Screen recording utility for wlroots Wayland compositors
+# Screen recording utility for wlroots Wayland compositors
 {
   config,
   pkgs,
diff --git a/modules/networking/bluetui/assertions.nix b/modules/networking/bluetui/assertions.nix
index 6d0924f..e764a9c 100644
--- a/modules/networking/bluetui/assertions.nix
+++ b/modules/networking/bluetui/assertions.nix
@@ -1,4 +1,4 @@
-# Assertions - Validates kitty is enabled for bluetui desktop entry
+# Validates kitty is enabled for bluetui desktop entry
 { config, ... }:
 {
   assertions = [
diff --git a/modules/networking/bluetui/default.nix b/modules/networking/bluetui/default.nix
index fc8971e..81cf11d 100644
--- a/modules/networking/bluetui/default.nix
+++ b/modules/networking/bluetui/default.nix
@@ -1,4 +1,4 @@
-# Bluetui - Bluetooth TUI client
+# Bluetooth TUI client
 {
   config,
   lib,
diff --git a/modules/networking/default.nix b/modules/networking/default.nix
index ffafea2..0b8650c 100644
--- a/modules/networking/default.nix
+++ b/modules/networking/default.nix
@@ -1,4 +1,4 @@
-# Networking - Network utility modules (bluetui, impala)
+# Network utility modules
 { ... }:
 {
   imports = [
diff --git a/modules/networking/impala/assertions.nix b/modules/networking/impala/assertions.nix
index 57cb04f..0ddeb8e 100644
--- a/modules/networking/impala/assertions.nix
+++ b/modules/networking/impala/assertions.nix
@@ -1,4 +1,4 @@
-# Assertions - Validates kitty is enabled for impala desktop entry
+# Validates kitty is enabled for impala desktop entry
 { config, ... }:
 {
   assertions = [
diff --git a/modules/networking/impala/default.nix b/modules/networking/impala/default.nix
index 66c992e..723a879 100644
--- a/modules/networking/impala/default.nix
+++ b/modules/networking/impala/default.nix
@@ -1,4 +1,4 @@
-# Impala - TUI for managing wifi on Linux
+# TUI for managing wifi on Linux
 {
   config,
   lib,
diff --git a/modules/networking/usque/default.nix b/modules/networking/usque/default.nix
index c5ef315..b8c25ee 100644
--- a/modules/networking/usque/default.nix
+++ b/modules/networking/usque/default.nix
@@ -1,4 +1,4 @@
-# Usque - Open-source reimplementation of the Cloudflare WARP client's MASQUE protocol
+# Open-source reimplementation of the Cloudflare WARP client's MASQUE protocol
 {
   config,
   pkgs,
diff --git a/modules/office/default.nix b/modules/office/default.nix
index c101580..8628151 100644
--- a/modules/office/default.nix
+++ b/modules/office/default.nix
@@ -1,4 +1,4 @@
-# Office - Document viewer modules (zathura)
+# Document viewer modules
 { ... }:
 {
   imports = [
diff --git a/modules/office/zathura/default.nix b/modules/office/zathura/default.nix
index 3aece2b..db742ec 100644
--- a/modules/office/zathura/default.nix
+++ b/modules/office/zathura/default.nix
@@ -1,4 +1,4 @@
-# Zathura - Minimalistic document viewer (PDF, DJVU, etc.)
+# Minimalistic document viewer
 {
   config,
   lib,
diff --git a/modules/scripts/gopass-ssh-load/script.sh b/modules/scripts/gopass-ssh-load/script.sh
index 43c83b0..be7d9d1 100644
--- a/modules/scripts/gopass-ssh-load/script.sh
+++ b/modules/scripts/gopass-ssh-load/script.sh
@@ -16,8 +16,7 @@ if ssh-add -l 2>/dev/null | grep -qE "(ED25519|RSA|ECDSA)"; then
   exit 0
 fi
 
-# GOPASS_SSH_KEYS: space-separated list of gopass entry names under ssh/
-# e.g. GOPASS_SSH_KEYS="github gitlab work-server"
+# GOPASS_SSH_KEYS holds a space-separated list of gopass entry names under ssh
 if [ -z "${GOPASS_SSH_KEYS:-}" ]; then
   echo "Error: GOPASS_SSH_KEYS is not set. Example: GOPASS_SSH_KEYS=\"github gitlab\"" >&2
   exit 1
diff --git a/modules/scripts/gpg-backup/script.sh b/modules/scripts/gpg-backup/script.sh
index 0d74d1c..c8e7363 100644
--- a/modules/scripts/gpg-backup/script.sh
+++ b/modules/scripts/gpg-backup/script.sh
@@ -126,7 +126,7 @@ do_import() {
   echo "  Run 'gpg --list-secret-keys' to confirm."
 }
 
-# --- main ---
+# Main
 
 if [[ $# -ne 2 ]]; then
   usage
diff --git a/modules/scripts/neomutt-sync/script.sh b/modules/scripts/neomutt-sync/script.sh
index b2db42a..02e03e7 100644
--- a/modules/scripts/neomutt-sync/script.sh
+++ b/modules/scripts/neomutt-sync/script.sh
@@ -26,9 +26,9 @@ button_key_inactive_color = (YELLOW,BLACK,OFF)
 button_label_inactive_color = (YELLOW,BLACK,OFF)
 EOF
 
-# 2. Run the sync and indexing progress bar
+# Run the sync and indexing progress bar
 (
-  # --- PHASE 1: mbsync ---
+  # mbsync phase
   script -q -e -c "mbsync -a" /dev/null | awk -v RS='\r' '
   {
     c_str = ""
@@ -47,15 +47,15 @@ EOF
     fflush()
   }'
 
-  # --- PHASE 2: notmuch ---
+  # notmuch phase
   printf "XXX\n100\nIndexing new mail with notmuch...\nXXX\n"
   notmuch new > "$NOTMUCH_LOG" 2>&1
 ) | dialog --title "$TITLE" --gauge "Initializing..." 8 80 0
 
-# 3. Format the captured notmuch output into a single clean line
+# Format the captured notmuch output into a single clean line
 CLEAN_OUT=$(tr '\n' ' ' < "$NOTMUCH_LOG" | sed 's/  */ /g')
 
-# 4. Display final results and wait for user input (Enter/Esc) to dismiss
+# Display final results and wait for user input
 dialog --title "$TITLE" --msgbox "Done!\n$CLEAN_OUT" 8 80
 
 clear
diff --git a/modules/scripts/screen-recording/script.sh b/modules/scripts/screen-recording/script.sh
index c2dafbe..dad0483 100644
--- a/modules/scripts/screen-recording/script.sh
+++ b/modules/scripts/screen-recording/script.sh
@@ -7,7 +7,7 @@ YELLOW='\033[1;33m'
 RED='\033[0;31m'
 NC='\033[0m'
 
-# --- 1. ARGUMENT PARSING ---
+# Argument parsing
 SELECT_MODE=false
 while [[ "$#" -gt 0 ]]; do
 	case $1 in
@@ -16,7 +16,7 @@ while [[ "$#" -gt 0 ]]; do
 	shift
 done
 
-# --- 2. GEOMETRY SELECTION ---
+# Geometry selection
 GEOMETRY=""
 
 if [ "$SELECT_MODE" = true ]; then
@@ -34,7 +34,7 @@ if [ "$SELECT_MODE" = true ]; then
 	fi
 fi
 
-# --- 3. START RECORDING ---
+# Start recording
 FILENAME="$OUT_DIR/recording-$(date +%Y%m%d-%H%M%S).mp4"
 
 echo -e "${GREEN}Recording started!${NC}"
diff --git a/modules/scripts/yazi-file-chooser/script.sh b/modules/scripts/yazi-file-chooser/script.sh
index e02c742..5e4b229 100644
--- a/modules/scripts/yazi-file-chooser/script.sh
+++ b/modules/scripts/yazi-file-chooser/script.sh
@@ -1,8 +1,8 @@
-# $1 = multiple selection (1/0)
-# $2 = directory select mode (1/0)
-# $3 = save file mode (1/0)
-# $4 = initial directory path
-# $5 = output path file (where portal expects selected paths)
+# $1 toggles multiple selection
+# $2 toggles directory select mode
+# $3 toggles save file mode
+# $4 is the initial directory path
+# $5 is the output path file
 
 # multiple="$1"
 directory="$2"
@@ -12,9 +12,9 @@ out="$5"
 
 # Pick directory vs single/multiple file
 if [ "$directory" = "1" ]; then
-    # --cwd-file outputs the final working directory path when exiting
+    # Outputs the final working directory path on exit
     exec yazi "$path" --cwd-file="$out"
 else
-    # --chooser-file writes all selected file path(s) to $out on exit
+    # Writes all selected file paths to the output file on exit
     exec yazi "$path" --chooser-file="$out"
 fi
diff --git a/modules/security/default.nix b/modules/security/default.nix
index 40bb6fc..e96920a 100644
--- a/modules/security/default.nix
+++ b/modules/security/default.nix
@@ -1,4 +1,4 @@
-# Security - Security tools (gopass, gpg, ssh)
+# Security tools
 { ... }:
 
 {
diff --git a/modules/security/gopass/default.nix b/modules/security/gopass/default.nix
index c4910cb..d154226 100644
--- a/modules/security/gopass/default.nix
+++ b/modules/security/gopass/default.nix
@@ -1,4 +1,4 @@
-# gopass - Standard Unix password manager (Go implementation)
+# Standard Unix password manager
 {
   config,
   lib,
diff --git a/modules/security/gpg/default.nix b/modules/security/gpg/default.nix
index 88c57d1..472270b 100644
--- a/modules/security/gpg/default.nix
+++ b/modules/security/gpg/default.nix
@@ -1,4 +1,4 @@
-# gpg - GNU Privacy Guard
+# GNU Privacy Guard
 {
   config,
   lib,
diff --git a/modules/security/ssh/default.nix b/modules/security/ssh/default.nix
index 9b89deb..97b5808 100644
--- a/modules/security/ssh/default.nix
+++ b/modules/security/ssh/default.nix
@@ -1,4 +1,4 @@
-# OpenSSH - Secure shell (SSH) client for encrypted remote connections
+# Secure shell client for encrypted remote connections
 {
   config,
   lib,
diff --git a/modules/security/ssh/git.nix b/modules/security/ssh/git.nix
index 23b52ab..146bfb9 100644
--- a/modules/security/ssh/git.nix
+++ b/modules/security/ssh/git.nix
@@ -1,4 +1,4 @@
-# Git - SSH host configurations for git platforms (github, gitlab, bitbucket, codeberg, sr.ht)
+# SSH host configurations for git platforms
 { config, lib, ... }:
 let
   hosts = [
diff --git a/modules/system/bottom/default.nix b/modules/system/bottom/default.nix
index fc72ec3..b037c56 100644
--- a/modules/system/bottom/default.nix
+++ b/modules/system/bottom/default.nix
@@ -1,4 +1,4 @@
-# Bottom - Cross-platform graphical process/system monitor (Rust-based)
+# Cross-platform graphical process and system monitor
 {
   config,
   lib,
diff --git a/modules/system/brightnessctl/default.nix b/modules/system/brightnessctl/default.nix
index c686eaf..e8fafb7 100644
--- a/modules/system/brightnessctl/default.nix
+++ b/modules/system/brightnessctl/default.nix
@@ -1,4 +1,4 @@
-# brightnessctl - Backlight brightness control tool
+# Backlight brightness control tool
 {
   config,
   lib,
diff --git a/modules/system/default.nix b/modules/system/default.nix
index afd3c12..591cd10 100644
--- a/modules/system/default.nix
+++ b/modules/system/default.nix
@@ -1,4 +1,4 @@
-# System - System monitoring tools (bottom, brightnessctl, htop, nvtop, systemctl-tui)
+# System monitoring tools
 { ... }:
 {
   imports = [
diff --git a/modules/system/htop/default.nix b/modules/system/htop/default.nix
index 1de9032..02fea6e 100644
--- a/modules/system/htop/default.nix
+++ b/modules/system/htop/default.nix
@@ -1,4 +1,4 @@
-# Htop - Interactive process viewer (using htop-vim version)
+# Interactive process viewer
 {
   pkgs,
   lib,
diff --git a/modules/system/nvtop/default.nix b/modules/system/nvtop/default.nix
index 54b4e44..2fc8e84 100644
--- a/modules/system/nvtop/default.nix
+++ b/modules/system/nvtop/default.nix
@@ -1,4 +1,4 @@
-# Nvtop - GPU process monitor (NVIDIA/AMD/Intel GPUs)
+# GPU process monitor
 {
   config,
   pkgs,
diff --git a/modules/system/systemctl-tui/default.nix b/modules/system/systemctl-tui/default.nix
index e7ccaa9..b6196d7 100644
--- a/modules/system/systemctl-tui/default.nix
+++ b/modules/system/systemctl-tui/default.nix
@@ -1,4 +1,4 @@
-# systemctl-tui - TUI for systemctl (systemd service management)
+# TUI for systemctl
 {
   config,
   pkgs,
diff --git a/modules/terminal/bash/default.nix b/modules/terminal/bash/default.nix
index dec9a11..20a0067 100644
--- a/modules/terminal/bash/default.nix
+++ b/modules/terminal/bash/default.nix
@@ -1,4 +1,4 @@
-# Bash - GNU Bourne Again SHell
+# GNU Bourne Again SHell
 { lib, ... }:
 {
   options.terminal.bash = {
diff --git a/modules/terminal/bat/default.nix b/modules/terminal/bat/default.nix
index 2344c15..a35bcbe 100644
--- a/modules/terminal/bat/default.nix
+++ b/modules/terminal/bat/default.nix
@@ -1,4 +1,4 @@
-# bat - a cat clone with wings
+# A cat clone with wings
 {
   config,
   lib,
diff --git a/modules/terminal/default.nix b/modules/terminal/default.nix
index 80992e1..55b6e1f 100644
--- a/modules/terminal/default.nix
+++ b/modules/terminal/default.nix
@@ -1,4 +1,4 @@
-# Terminal - Terminal emulator and shell modules (bash, bat, fzf, kitty, less, starship, tmux, zsh)
+# Terminal emulator and shell modules
 { ... }:
 
 {
diff --git a/modules/terminal/fzf/assertions.nix b/modules/terminal/fzf/assertions.nix
index 2c0bec9..9fb24b9 100644
--- a/modules/terminal/fzf/assertions.nix
+++ b/modules/terminal/fzf/assertions.nix
@@ -1,4 +1,4 @@
-# Assertions - Validates zsh or bash is enabled when fzf is enabled
+# Validates zsh or bash is enabled when fzf is enabled
 { config, ... }:
 {
   assertions = [
diff --git a/modules/terminal/fzf/default.nix b/modules/terminal/fzf/default.nix
index 5842db4..c59e039 100644
--- a/modules/terminal/fzf/default.nix
+++ b/modules/terminal/fzf/default.nix
@@ -1,4 +1,4 @@
-# FZF - Fuzzy finder, CLI fuzzy search tool
+# Fuzzy finder, CLI fuzzy search tool
 {
   config,
   lib,
diff --git a/modules/terminal/kitty/default.nix b/modules/terminal/kitty/default.nix
index f4d81ba..d40a9b6 100644
--- a/modules/terminal/kitty/default.nix
+++ b/modules/terminal/kitty/default.nix
@@ -1,4 +1,4 @@
-# Kitty - GPU-accelerated terminal emulator
+# GPU-accelerated terminal emulator
 {
   config,
   lib,
diff --git a/modules/terminal/less/default.nix b/modules/terminal/less/default.nix
index f68875c..66ddce9 100644
--- a/modules/terminal/less/default.nix
+++ b/modules/terminal/less/default.nix
@@ -1,4 +1,4 @@
-# less - terminal pager
+# Terminal pager
 { config, lib, ... }:
 {
   options.terminal.less = {
diff --git a/modules/terminal/starship/default.nix b/modules/terminal/starship/default.nix
index 86e8527..6aa83d6 100644
--- a/modules/terminal/starship/default.nix
+++ b/modules/terminal/starship/default.nix
@@ -1,4 +1,4 @@
-# Starship - Minimal, blazing-fast shell prompt
+# Minimal, blazing-fast shell prompt
 { config, lib, ... }:
 {
   options.terminal.starship = {
diff --git a/modules/terminal/tmux/default.nix b/modules/terminal/tmux/default.nix
index 2e8d57d..c9ea17b 100644
--- a/modules/terminal/tmux/default.nix
+++ b/modules/terminal/tmux/default.nix
@@ -1,4 +1,4 @@
-# Tmux - Terminal multiplexer (window/pane management)
+# Terminal multiplexer
 {
   config,
   lib,
diff --git a/modules/terminal/zsh/default.nix b/modules/terminal/zsh/default.nix
index d04ebb7..9848fb8 100644
--- a/modules/terminal/zsh/default.nix
+++ b/modules/terminal/zsh/default.nix
@@ -1,4 +1,4 @@
-# Zsh - Z shell, extended bash with additional features and plugins
+# Z shell, extended bash with additional features and plugins
 {
   config,
   lib,
diff --git a/modules/terminal/zsh/nix-aliases.sh b/modules/terminal/zsh/nix-aliases.sh
index 0bcfbe5..1c07d3a 100644
--- a/modules/terminal/zsh/nix-aliases.sh
+++ b/modules/terminal/zsh/nix-aliases.sh
@@ -1,4 +1,4 @@
-# Nix aliases - Wrappers for nix-shell and nix develop that auto-start $SHELL
+# Wrappers for nix-shell and nix develop that auto-start $SHELL
 nix-shell() {
   for arg in "$@"; do
     if [[ "$arg" == "--run" || "$arg" == "--command" ]]; then
diff --git a/modules/web/aria2/default.nix b/modules/web/aria2/default.nix
index 77b25bb..800f178 100644
--- a/modules/web/aria2/default.nix
+++ b/modules/web/aria2/default.nix
@@ -1,4 +1,4 @@
-# Aria2 - command line download manager
+# Command line download manager
 {
   lib,
   config,
diff --git a/modules/web/chawan/assertions.nix b/modules/web/chawan/assertions.nix
index 2ab30a0..93b5fab 100644
--- a/modules/web/chawan/assertions.nix
+++ b/modules/web/chawan/assertions.nix
@@ -1,4 +1,4 @@
-# Assertions - Validates kitty is enabled for chawan desktop entry
+# Validates kitty is enabled for chawan desktop entry
 { config, ... }:
 {
   assertions = [
diff --git a/modules/web/chawan/default.nix b/modules/web/chawan/default.nix
index 7d1398e..b71d902 100644
--- a/modules/web/chawan/default.nix
+++ b/modules/web/chawan/default.nix
@@ -1,4 +1,4 @@
-# Chawan - Text-based web browser and pager
+# Text-based web browser and pager
 {
   config,
   lib,
diff --git a/modules/web/chromium/browserpass.nix b/modules/web/chromium/browserpass.nix
index f09945d..6bef374 100644
--- a/modules/web/chromium/browserpass.nix
+++ b/modules/web/chromium/browserpass.nix
@@ -5,7 +5,7 @@
   ...
 }:
 let
-  # Extension ID computed from the pinned "extensionKey" in
+  # Extension ID computed from the pinned extensionKey
   patchedHost =
     pkgs.runCommand "com.github.browserpass.native.json"
       {
diff --git a/modules/web/chromium/extensions/default.nix b/modules/web/chromium/extensions/default.nix
index 6128d2b..a079a78 100644
--- a/modules/web/chromium/extensions/default.nix
+++ b/modules/web/chromium/extensions/default.nix
@@ -51,8 +51,7 @@ in
     '';
   };
 
-  # readOnly options get their actual value assigned here, in this same
-  # module's config — this is the one place allowed to set it.
+  # Readonly options get their actual value assigned here in this module
   config.web.chromium.extensions = {
     aria2Explorer = mkExtension ./aria2-explorer.nix;
     browserpass = mkExtension ./browserpass.nix;
diff --git a/modules/web/chromium/extensions/lib.nix b/modules/web/chromium/extensions/lib.nix
index d319a5c..79007bd 100644
--- a/modules/web/chromium/extensions/lib.nix
+++ b/modules/web/chromium/extensions/lib.nix
@@ -5,9 +5,7 @@
   checkForUpdates ? true,
 }:
 rec {
-  # --- Hit the GitHub releases API and return the latest tag name. ---
-  # Impure: requires --impure since there's no fixed output hash for the API
-  # response itself. Optionally uses $GITHUB_TOKEN to dodge rate limits.
+  # Fetch the latest release tag from the GitHub releases API
   fetchLatestGithubReleaseTag =
     { owner, repo }:
     let
@@ -19,9 +17,7 @@ rec {
     in
     json.tag_name;
 
-  # --- Compare pinned version against upstream latest, abort with instructions if stale. ---
-  # Returns `version` unchanged on success so it can be threaded into the
-  # derivation below and force this check to actually run.
+  # Abort if the pinned version is older than the latest upstream release
   checkExtensionVersion =
     {
       pname,
@@ -61,11 +57,7 @@ rec {
       else
         version;
 
-  # --- Download + unpack a zip *or* crx into a plain unpacked-extension dir. ---
-  # A CRX3 file is just: "Cr24" magic (4B) + version (4B) + header length N (4B)
-  # + N bytes of protobuf header + a normal zip payload. We slice off the
-  # header when isCrx = true, then unzip exactly like any other release zip —
-  # so every extension, crx or not, goes through one identical pipeline.
+  # Download and unpack a zip or crx file into an unpacked extension directory
   fetchUnpackedExtension =
     {
       pname,
@@ -73,7 +65,7 @@ rec {
       url,
       hash,
       isCrx ? false,
-      extensionKey ? null, # NEW: Accept an optional public key
+      extensionKey ? null, # Accept an optional public key
     }:
     pkgs.stdenv.mkDerivation {
       inherit pname version;
@@ -81,7 +73,7 @@ rec {
 
       nativeBuildInputs = [
         config.file-management.ouch.package
-        pkgs.jq # NEW: Required for safely editing manifest.json
+        pkgs.jq # Required for safely editing manifest.json
       ];
       dontUnpack = true;
 
@@ -90,14 +82,14 @@ rec {
         mkdir -p $out
 
         if [ "${lib.boolToString isCrx}" = "true" ]; then
-          # Verify "Cr24" magic header
+          # Verify the Cr24 magic header
           magic=$(head -c 4 "$src")
           if [ "$magic" != "Cr24" ]; then
             echo "Error: $src is not a valid CRX file" >&2
             exit 1
           fi
 
-          # Extract header length (bytes 8-11, little-endian)
+          # Extract header length in bytes 8 to 11
           bytes=$(od -An -j8 -N4 -tu1 "$src")
           read b1 b2 b3 b4 <<< $bytes
           hlen=$(( b1 + (b2 << 8) + (b3 << 16) + (b4 << 24) ))
@@ -109,7 +101,7 @@ rec {
           ouch decompress $src --dir $out
         fi
 
-        # Flatten a single wrapping folder (common in GitHub release zips)
+        # Flatten a single wrapping folder
         if [ "$(ls -1 $out | wc -l)" -eq 1 ] && [ -d "$out"/* ]; then
           shopt -s dotglob
           mv "$out"/*/* "$out"/ 2>/dev/null || true
@@ -117,7 +109,7 @@ rec {
           shopt -u dotglob
         fi
 
-        # NEW: Inject the public key into manifest.json if provided
+        # Inject the public key into manifest.json if provided
         ${lib.optionalString (extensionKey != null) ''
           if [ -f "$out/manifest.json" ]; then
             echo "Injecting extension key into manifest.json to lock the extension ID..."
@@ -132,7 +124,7 @@ rec {
       '';
 
       installPhase = "true";
-    }; # --- Package a local directory as an unpacked extension derivation. ---
+    }; # Package a local directory as an unpacked extension
 
   mkLocalExtension =
     {
diff --git a/modules/web/default.nix b/modules/web/default.nix
index 7357df9..4e07536 100644
--- a/modules/web/default.nix
+++ b/modules/web/default.nix
@@ -1,4 +1,4 @@
-# Web - Web browser and downloader modules (aria2, brave, chawan)
+# Web browser and downloader modules
 { ... }:
 {
   imports = [