style: align comments with the project conventions

Apply a codebase-wide comment audit against the comment conventions:
split banned semicolons and multi-sentence lines into one sentence per
line, cut cross-file and history narration, trim file-top headers to a
single purpose line, and drop verbosity that did not earn its place.
Prose docs (CLAUDE.md, install.md) get the same one-sentence-per-line
and no-semicolon treatment.

modules/agents/claude-code/claude-code.nix

@@ -5,8 +5,8 @@
   ...
 }:
 # 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.
+# the package and manages ~/.claude.
+# Login credentials are left unmanaged so they survive rebuilds.
 let
   cfg = config.modules.agents.claude-code;
   user = config.user.name;
@@ -22,10 +22,8 @@ in
     cached credential while it lasts. Suitable for a single-user machine'';
 
   config = lib.mkIf cfg.enable {
-    # Keying sudo's credential cache per user rather than per terminal lets one
-    # authentication cover commands issued by processes holding no terminal of
-    # their own. Any process running as this user can spend that credential
-    # until it lapses, so this suits a single-user machine.
+    # Key the credential cache per user rather than per terminal, so one
+    # authentication covers the agent's terminal-less commands.
     security.sudo.extraConfig = ''
       Defaults timestamp_type=global
       Defaults timestamp_timeout=60
@@ -38,7 +36,7 @@ in
       programs.claude-code = {
         enable = true;
 
-        # Global agent instructions, rendered to ~/.claude/CLAUDE.md.
+        # The global agent-instructions file.
         context = ./CLAUDE.md;
 
         # One directory per skill, symlinked under ~/.claude/skills.

modules/agents/claude-code/hooks/agent-sudo-guard.sh

@@ -1,10 +1,10 @@
 #!/bin/sh
-# agent-sudo-guard.sh — refuse a privileged command while sudo's credential
-# cache is cold, naming the command that warms it.
+# Refuse a privileged command while sudo's credential cache is cold, naming the
+# command that warms it.
 #
 # Commands arrive here from subprocesses holding no terminal, so an uncached
-# sudo fails with a bare non-zero exit and no output, reading as an unexplained
-# stall. The probe below reads a cache keyed per user rather than per terminal,
+# sudo fails with a bare non-zero exit and no output, reading as an unexplained stall.
+# The probe below reads a cache keyed per user rather than per terminal,
 # so an authentication made in the operator's own terminal counts.
 
 input=$(cat)

modules/agents/skills.nix

@@ -1,13 +1,6 @@
 { config, inputs, ... }:
-# Global agent skills from the skills flake, placed under the agent harness's
-# skills directory so they are active in every project. The flake's home-manager
-# module self-gates on the harness being enabled and installs nothing for an
-# empty selection, so a host without one carries no skills either way.
-#
-# Unlike every other module, this one declares no `enable` flag and wires
-# unconditionally, by design.
-# The flake's self-gating above already makes it inert where the harness is
-# absent, so a gate would guard nothing.
+# Global agent skills, placed under the skills directory so they are active in
+# every project.
 let
   user = config.user.name;
 

modules/agents/tools/gitea-axi.nix

@@ -5,8 +5,6 @@
   ...
 }:
 # gitea-axi for the primary user, installed through its own home-manager module.
-# That module also declares the Claude Code context when that harness is
-# enabled on the host; enabling this alone installs the CLI and nothing else.
 let
   cfg = config.modules.agents.tools.gitea-axi;
   user = config.user.name;

modules/desktop/firefox.nix

@@ -35,8 +35,7 @@ in
             Snippets = false;
           };
 
-          # An ad and content blocker, the operator's password manager, and a
-          # video sponsor-skipper. All three are self-contained web extensions.
+          # An ad blocker, a password manager, and a video sponsor-skipper.
           ExtensionSettings = {
             "uBlock0@raymondhill.net" = forceInstalled "ublock-origin";
             "78272b6fa58f4a1abaac99321d503a20@proton.me" = forceInstalled "proton-pass";
@@ -65,16 +64,15 @@ in
             };
 
           settings = {
-            # Scale the UI and page by a fixed factor. Left at auto (-1),
-            # Firefox reads the panel's 1.5x and inflates its whole chrome on
-            # this display while point-sized apps stay put; a shade under that
-            # brings it into line without dropping to true 1:1, which reads too
-            # small at this DPI.
+            # Scale the UI and page by a fixed factor.
+            # Left at auto (-1), Firefox reads the panel's 1.5x and inflates its
+            # whole chrome while point-sized apps stay put.
+            # A shade under that brings it into line without dropping to true
+            # 1:1, which reads too small at this DPI.
             "layout.css.devPixelsPerPx" = "1.25";
 
-            # Auto-enable the sideloaded Firefox Color add-on that carries the
-            # Nord chrome theme, which Firefox otherwise leaves disabled.
-            # The functional extensions come through policy and are unaffected.
+            # Auto-enable the sideloaded Firefox Color add-on carrying the Nord
+            # chrome theme, which Firefox otherwise leaves disabled.
             "extensions.autoDisableScopes" = 0;
 
             # Sponsored surfaces the policies above do not reach.
@@ -103,9 +101,8 @@ in
         };
       };
 
-      # Nord chrome from the shared Stylix scheme, against the one profile.
-      # colorTheme recolours the toolbar and tabs, which the target does not do
-      # on its own, through the Stylix-managed Firefox Color add-on.
+      # Nord chrome for the one profile, applied through the Stylix-managed
+      # Firefox Color add-on that colorTheme enables.
       stylix.targets.firefox = {
         enable = true;
         profileNames = [ "default" ];

modules/desktop/hyprland/hypridle.nix

@@ -4,8 +4,7 @@
   pkgs,
   ...
 }:
-# Idle management: hypridle locks on idle, powers the displays off, and locks
-# before every suspend, so an unattended session always lands at hyprlock.
+# hypridle: idle-triggered locking and display power management.
 let
   cfg = config.modules.desktop.hyprland.hypridle;
   user = config.user.name;

modules/desktop/hyprland/hyprland.nix

@@ -4,7 +4,7 @@
   pkgs,
   ...
 }:
-# The Hyprland compositor, sourced from nixpkgs.
+# The Hyprland compositor.
 let
   cfg = config.modules.desktop.hyprland;
   user = config.user.name;
@@ -63,12 +63,13 @@ in
         "$mod" = "SUPER";
         "$terminal" = "alacritty";
 
-        # Hand the cursor theme to the compositor directly. UWSM launches the
-        # session without the shell profile that carries the pointer-cursor
-        # variables, so without this Hyprland never sees a theme and falls back
-        # to its built-in cursor. Bibata ships XCursor only; the hyprcursor
-        # variables name the same theme, which Hyprland resolves through its
-        # XCursor fallback.
+        # Hand the cursor theme to the compositor directly.
+        # UWSM launches the session without the shell profile that carries the
+        # pointer-cursor variables, so without this Hyprland never sees a theme
+        # and falls back to its built-in cursor.
+        # Bibata ships XCursor only.
+        # The hyprcursor variables name the same theme, which Hyprland resolves
+        # through its XCursor fallback.
         env = lib.optionals (cursor != null) [
           "XCURSOR_THEME,${cursor.name}"
           "XCURSOR_SIZE,${toString cursor.size}"
@@ -81,7 +82,7 @@ in
           # Caps is a second Escape.
           # Shift+Caps still toggles a real CapsLock.
           kb_options = "caps:escape_shifted_capslock";
-          # Snappy: a short delay before repeat begins, then a fast repeat rate.
+          # Snappy key repeat.
           repeat_delay = 250;
           repeat_rate = 45;
           accel_profile = "flat";
@@ -156,8 +157,9 @@ in
         ++ workspaceBinds;
 
         # Volume and brightness keys repeat while held, each raising a popup
-        # through the OSD client. Volume is capped at 100 percent; the client
-        # floors brightness so a full hold cannot black the screen out.
+        # through the OSD client.
+        # Volume is capped at 100 percent.
+        # The client floors brightness so a full hold cannot black the screen out.
         binde = [
           ", XF86AudioRaiseVolume, exec, ${pkgs.swayosd}/bin/swayosd-client --output-volume raise --max-volume 100"
           ", XF86AudioLowerVolume, exec, ${pkgs.swayosd}/bin/swayosd-client --output-volume lower"

modules/desktop/hyprland/hyprlock.nix

@@ -4,13 +4,12 @@
   pkgs,
   ...
 }:
-# The lock screen: hyprlock, a session-lock client whose surface the compositor owns, so it survives a crash of the locker rather than exposing the session.
+# The lock screen: a hyprlock session-lock surface the compositor owns.
 let
   cfg = config.modules.desktop.hyprland.hyprlock;
   user = config.user.name;
 
-  # The hyprlock this module installs, so the keybind and the idle daemon lock
-  # with one package and never split versions.
+  # The hyprlock this module installs, used by the lock keybind below.
   hyprlock = "${config.home-manager.users.${user}.programs.hyprlock.package}/bin/hyprlock";
 in
 {
@@ -30,7 +29,8 @@ in
             disable_loading_bar = true;
           };
 
-          # A centered password field; its colors are the Stylix target's.
+          # A centered password field.
+          # Its colors come from the Stylix hyprlock target.
           input-field = {
             size = "260, 52";
             rounding = 8;

modules/desktop/osd.nix

@@ -16,14 +16,13 @@ in
     environment.systemPackages = [ pkgs.swayosd ];
 
     # The udev rule chgrps each backlight's brightness node to `video` and adds
-    # group write, so the server dims the panel without root. Membership below
-    # grants the running session that access.
+    # group write, so the server dims the panel without root.
+    # Membership below grants the running session that access.
     services.udev.packages = [ pkgs.swayosd ];
     users.users.${user}.extraGroups = [ "video" ];
 
     # The server draws the popups, so it runs for the whole graphical session.
-    # Bound to the target uwsm activates, like the bar, rather than an
-    # exec-once in the compositor config.
+    # It binds to the target uwsm activates.
     home-manager.users.${user}.systemd.user.services.swayosd = {
       Unit = {
         Description = "SwayOSD on-screen display server";

modules/desktop/portals.nix

@@ -10,8 +10,9 @@ in
   config = lib.mkIf cfg.enable {
     # The backend packages arrive with the compositor, so only the routing is set
     # here.
-    # GTK is the default backend, and the three compositor-native requests go to
-    # Hyprland.
+    # Screen sharing, screenshots, and global shortcuts need the compositor's
+    # own backend.
+    # Everything else uses GTK.
     xdg.portal.config.common = {
       default = [ "gtk" ];
       "org.freedesktop.impl.portal.ScreenCast" = [ "hyprland" ];

modules/desktop/screenshot.nix

@@ -15,9 +15,8 @@ let
   wl-copy = "${pkgs.wl-clipboard}/bin/wl-copy";
   xdgUserDir = "${pkgs.xdg-user-dirs}/bin/xdg-user-dir";
 
-  # satty is the annotation step, and its copy action is set to save as well,
-  # so a single keystroke through it lands the shot in both the clipboard and a
-  # file.
+  # satty's copy action also saves, so one keystroke lands the shot in both the
+  # clipboard and a file.
   capture =
     target:
     pkgs.writeShellScript "screenshot-${target}" ''
@@ -46,8 +45,8 @@ in
       ];
 
       # Print with plain/Shift/Ctrl for region/window/full.
-      # Super+L, the spec's chosen key, is already the hjkl focus and movement
-      # bind, so screenshots take the Print key instead.
+      # Super+L is already the hjkl focus and movement bind, so screenshots take
+      # the Print key instead.
       wayland.windowManager.hyprland.settings.bind = [
         ", Print, exec, ${capture "area"}"
         "SHIFT, Print, exec, ${capture "active"}"

modules/desktop/terminal.nix

@@ -4,8 +4,7 @@
   pkgs,
   ...
 }:
-# Alacritty as the desktop terminal, a lightweight GPU renderer that opens
-# fast on the laptop's integrated graphics.
+# Alacritty as the desktop terminal.
 let
   cfg = config.modules.desktop.terminal;
   user = config.user.name;

modules/desktop/userdirs.nix

@@ -9,8 +9,7 @@ in
   options.modules.desktop.userdirs.enable = lib.mkEnableOption "XDG user directories";
 
   config = lib.mkIf cfg.enable {
-    # enable writes ~/.config/user-dirs.dirs from the option defaults, which
-    # xdg-user-dir then reads.
+    # Write ~/.config/user-dirs.dirs from the option defaults.
     home-manager.users.${user}.xdg.userDirs.enable = true;
   };
 }

modules/fish/fish.nix

@@ -84,9 +84,9 @@ in
         };
 
         functions = {
-          # Pick the logo that fits the terminal so the greeting never wraps:
-          # the full logo needs about 118 columns beside the info block, the
-          # compact one about 89, and the info block alone about 71.
+          # Pick the logo that fits the terminal so the greeting never wraps.
+          # The full logo needs about 118 columns beside the info block, the
+          # compact one about 89, the info block alone about 71.
           fish_greeting = ''
             if test "$COLUMNS" -ge 118
                 fastfetch
@@ -97,10 +97,9 @@ in
             end
           '';
 
-          # vi insert mode omits the emacs ctrl-f and ctrl-r bindings, so
-          # restore both.
+          # vi insert mode omits the emacs ctrl-f and ctrl-r bindings, so restore both.
           # ctrl-f accepts an autosuggestion and ctrl-r opens the history pager.
-          # Only insert mode is bound: vi normal mode keeps ctrl-r as redo.
+          # vi normal mode keeps its ctrl-r redo, since only insert mode is bound.
           fish_user_key_bindings = ''
             bind -M insert ctrl-f forward-char
             bind -M insert ctrl-r history-pager

modules/nvim/config.lua

@@ -1,13 +1,12 @@
--- Imperative configuration that has no typed nixvim option: the colorscheme
--- call and two autocmds. Everything expressible as Nix lives in ./nvim.nix.
+-- Imperative configuration that has no typed nixvim option: the colorscheme call and autocmds.
 
--- gbprod/nord.nvim, provided as an extra plugin from nixpkgs.
+-- gbprod/nord.nvim.
 require("nord").setup({
   transparent = true,
 })
 vim.cmd.colorscheme("nord")
 
--- Conceal markdown syntax in markdown buffers (previously an after/ftplugin).
+-- Conceal markdown syntax in markdown buffers.
 -- conceallevel is window-local, so it is set with opt_local when the filetype
 -- is applied to the buffer's window.
 vim.api.nvim_create_autocmd("FileType", {

modules/nvim/nvim.nix

@@ -5,8 +5,7 @@
   inputs,
   ...
 }:
-# Neovim for the primary user, configured declaratively through nixvim. The
-# imperative remainder (colorscheme, Neogit blame autocmd) lives in ./config.lua.
+# Neovim for the primary user, configured declaratively through nixvim.
 let
   cfg = config.modules.nvim;
   user = config.user.name;
@@ -176,8 +175,8 @@ in
           };
         };
 
-        # gbprod/nord.nvim (nixvim's colorschemes.nord is a different plugin);
-        # set up in ./config.lua.
+        # gbprod/nord.nvim, set up in ./config.lua.
+        # nixvim's colorschemes.nord is a different plugin.
         extraPlugins = [ pkgs.vimPlugins.gbprod-nord ];
 
         extraConfigLua = builtins.readFile ./config.lua;

modules/tmux/extra.conf

@@ -6,8 +6,8 @@ bind -T copy-mode-vi v send -X begin-selection
 bind -T copy-mode-vi y send -X copy-selection-and-cancel
 bind -T copy-mode-vi MouseDragEnd1Pane send -X copy-selection-and-cancel
 
-# \ splits the pane side-by-side, - splits it stacked; both open the new pane
-# in the current pane's directory, as does c for a new window.
+# \ splits the pane side-by-side, - splits it stacked.
+# Both open the new pane in the current pane's directory, as does c for a new window.
 unbind %
 unbind '"'
 bind \\ split-window -h -c "#{pane_current_path}"
@@ -27,13 +27,14 @@ bind r source-file ~/.config/tmux/tmux.conf \; display-message "tmux.conf reload
 set -ag terminal-overrides ",*:RGB"
 
 # monitor-bell flags a background window in the status bar when it rings the
-# terminal bell while unfocused. bell-action=none suppresses the actual BEL
-# (no beep or flash); the per-window status highlight is independent of it.
+# terminal bell while unfocused.
+# bell-action=none suppresses the actual BEL (no beep or flash).
+# The per-window status highlight is independent of it.
 setw -g monitor-bell on
 set -g bell-action none
 
 # Minimal status bar: session name plus window list only.
-# Colours are left to Stylix, which themes the status and pane styles.
+# Colours are left to Stylix.
 set -g status-position bottom
 set -g status-left " #S "
 set -g status-left-length 20

modules/tmux/tmux.nix

@@ -3,8 +3,8 @@
   lib,
   ...
 }:
-# tmux for the primary user, configured through home-manager. Settings without a
-# home-manager option are read from ./extra.conf.
+# 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;