10 files changed, 55 insertions, 220 deletions
diff --git a/modules/auth-config.el b/modules/auth-config.el
index 62d773057..c2df244b5 100644
--- a/modules/auth-config.el
+++ b/modules/auth-config.el
@@ -1,4 +1,4 @@
-;; auth-config.el --- Configuration for Authentication Utilities -*- lexical-binding: t; coding: utf-8; -*-
+;;; auth-config.el --- Authentication and GPG integration -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
@@ -6,29 +6,16 @@
 ;; Layer: 1 (Foundation).
 ;; Category: F/D.
 ;; Load shape: eager.
-;; Eager reason: auth-source and GPG/epa setup that other modules rely on for
-;;   credentials early in the session.
-;; Top-level side effects: auth-source/epa configuration via use-package and setq.
+;; Eager reason: credentials and GPG setup are needed by other modules early.
+;; Top-level side effects: auth-source/epa setup and oauth2-auto cache advice.
 ;; Runtime requires: system-lib, user-constants.
-;; Direct test load: yes (configuration only).
+;; Direct test load: yes.
 ;;
-;; Configuration for Emacs authentication and GPG integration:
-
-;; • auth-source
-;;   – Forces use of your default authinfo file
-;;   – Disable external GPG agent in favor of Emacs's own prompt
-;;   – Keeps auth-source debug logging disabled by default
-
-;; • Easy PG Assistant (epa)
-;;   – Force using the 'gpg2' executable for encryption/decryption operations
-
-;; • oauth2-auto cache fix (via advice)
-;;   – oauth2-auto version 20250624.1919 has caching bug on line 206
-;;   – Function oauth2-auto--plstore-read has `or nil` disabling cache
-;;   – This caused GPG passphrase prompts every ~15 minutes during gcal-sync
-;;   – Fix: Advice to enable hash-table cache without modifying package
-;;   – Works across package updates
-;;   – Fixed 2025-11-11
+;; Central auth-source, GPG, and credential-debug setup. Auth lookups use the
+;; configured authinfo file; passphrase caching is left to gpg-agent.
+;;
+;; Advises oauth2-auto's plstore reader to restore in-memory caching and avoid
+;; repeated GPG prompts during calendar/mail refreshes.
 
 ;;; Code:
 
diff --git a/modules/custom-datetime.el b/modules/custom-datetime.el
index 6bca494d8..0528688c2 100644
--- a/modules/custom-datetime.el
+++ b/modules/custom-datetime.el
@@ -1,4 +1,4 @@
-;;; custom-datetime.el ---  -*- coding: utf-8; lexical-binding: t; -*-
+;;; custom-datetime.el --- Insert formatted date and time strings -*- coding: utf-8; lexical-binding: t; -*-
 
 ;;; Commentary:
 ;;
@@ -12,32 +12,8 @@
 ;; Runtime requires: keybindings.
 ;; Direct test load: yes (requires keybindings explicitly).
 ;;
-;; Utilities for inserting date/time stamps in multiple formats.
-;;
-;; Interactive commands:
-;; - cj/insert-readable-date-time
-;; - cj/insert-sortable-date-time
-;; - cj/insert-sortable-time
-;; - cj/insert-readable-time
-;; - cj/insert-sortable-date
-;; - cj/insert-readable-date
-;;
-;; Each command is generated by `cj/--define-datetime-inserter' from a
-;; corresponding format variable:
-;;   readable-date-time-format, sortable-date-time-format,
-;;   sortable-time-format, readable-time-format,
-;;   sortable-date-format, readable-date-format.
-;; Customize these (see `format-time-string') to change output.
-;; Some defaults include a trailing space for convenient typing.
-;;
-;; Key bindings:
-;; A prefix map `cj/datetime-map' is installed on "d" under `cj/custom-keymap':
-;;   r → readable date+time
-;;   s → sortable date+time
-;;   t → sortable time
-;;   T → readable time
-;;   d → sortable date
-;;   D → readable date
+;; Date/time insertion commands under C-; d. Each command is generated from a
+;; customizable format variable and inserts format-time-string output at point.
 ;;
 ;;; Code:
 
diff --git a/modules/custom-line-paragraph.el b/modules/custom-line-paragraph.el
index 2cbcecc16..dd2999c4e 100644
--- a/modules/custom-line-paragraph.el
+++ b/modules/custom-line-paragraph.el
@@ -1,4 +1,4 @@
-;;; custom-line-paragraph.el ---  -*- coding: utf-8; lexical-binding: t; -*-
+;;; custom-line-paragraph.el --- Line and paragraph editing commands -*- coding: utf-8; lexical-binding: t; -*-
 ;; Author: Craig Jennings <c@cjennings.net>
 ;;
 ;;; Commentary:
@@ -14,16 +14,9 @@
 ;; Runtime requires: keybindings (expand-region on demand via declare-function).
 ;; Direct test load: yes (requires keybindings explicitly).
 ;;
-;; This module provides the following line and paragraph manipulation utilities:
-;;
-;; - joining lines in a region or the current line with the previous one
-;; - joining separate lines into a single paragraph
-;; - duplicating lines or regions (optional commenting)
-;; - removing duplicate lines
-;; - removing lines containing specific text
-;; - underlining text with a custom character
-;;
-;; Bound to keymap prefix  C-; l
+;; Line and paragraph transforms under C-; l: join, duplicate, delete matching
+;; lines, remove duplicates, and underline text. Commands operate on the active
+;; region when present and otherwise on the current line or paragraph.
 ;;
 ;;; Code:
 
diff --git a/modules/custom-ordering.el b/modules/custom-ordering.el
index 0a499a35a..4dc5bff84 100644
--- a/modules/custom-ordering.el
+++ b/modules/custom-ordering.el
@@ -1,4 +1,4 @@
-;;; custom-ordering.el ---  -*- coding: utf-8; lexical-binding: t; -*-
+;;; custom-ordering.el --- Region sorting and list-format transforms -*- coding: utf-8; lexical-binding: t; -*-
 
 ;;; Commentary:
 ;;
@@ -13,22 +13,10 @@
 ;;   declare-function).
 ;; Direct test load: yes (requires keybindings explicitly).
 ;;
-;; Text transformation and sorting utilities for reformatting data structures.
+;; Region transforms under C-; o for sorting, reversing, numbering, quote
+;; toggling, and converting between line lists and comma-separated arrays.
+;; Helpers preserve trailing newlines where line-oriented callers expect them.
 ;;
-;; Array/list formatting:
-;; - arrayify/listify - convert lines to comma-separated format (with/without quotes, brackets)
-;; - unarrayify - convert arrays back to separate lines
-;;
-;; Line manipulation:
-;; - toggle-quotes - swap double ↔ single quotes
-;; - reverse-lines - reverse line order
-;; - number-lines - add line numbers with custom format (supports zero-padding)
-;; - alphabetize-region - sort words alphabetically
-;; - comma-separated-text-to-lines - split CSV text into lines
-;;
-;; Convenience functions: listify, arrayify-json, arrayify-python
-;; Bound to keymap prefix C-; o
-
 ;;; Code:
 
 (require 'cl-lib)
diff --git a/modules/custom-text-enclose.el b/modules/custom-text-enclose.el
index 5b1b00a71..4d72347d1 100644
--- a/modules/custom-text-enclose.el
+++ b/modules/custom-text-enclose.el
@@ -1,4 +1,4 @@
-;;; custom-text-enclose.el ---  -*- coding: utf-8; lexical-binding: t; -*-
+;;; custom-text-enclose.el --- Wrap, unwrap, and prefix text ranges -*- coding: utf-8; lexical-binding: t; -*-
 
 ;;; Commentary:
 ;;
@@ -12,23 +12,10 @@
 ;; Runtime requires: keybindings (change-inner on demand via declare-function).
 ;; Direct test load: yes (requires keybindings explicitly).
 ;;
-;; Text enclosure utilities for wrapping and line manipulation.
+;; Text enclosure commands under C-; s. Commands wrap or unwrap the active
+;; region/word at point, and add prefixes, suffixes, indentation, or dedentation
+;; across selected lines.
 ;;
-;; Wrapping functions:
-;; - surround-word-or-region - wrap text with same delimiter on both sides
-;; - wrap-word-or-region - wrap with different opening/closing delimiters
-;; - unwrap-word-or-region - remove surrounding delimiters
-;;
-;; Line manipulation:
-;; - append-to-lines - add suffix to each line
-;; - prepend-to-lines - add prefix to each line
-;; - indent-lines - add leading whitespace (spaces or tabs)
-;; - dedent-lines - remove leading whitespace
-;;
-;; Most functions work on region or entire buffer when no region is active.
-;;
-;; Bound to keymap prefix C-; s
-
 ;;; Code:
 
 (require 'keybindings)  ;; provides cj/custom-keymap
diff --git a/modules/custom-whitespace.el b/modules/custom-whitespace.el
index 0d4d1cc06..cbf3eff12 100644
--- a/modules/custom-whitespace.el
+++ b/modules/custom-whitespace.el
@@ -1,4 +1,4 @@
-;;; custom-whitespace.el ---  -*- coding: utf-8; lexical-binding: t; -*-
+;;; custom-whitespace.el --- Whitespace cleanup commands -*- coding: utf-8; lexical-binding: t; -*-
 
 ;;; Commentary:
 ;;
@@ -12,19 +12,10 @@
 ;; Runtime requires: keybindings.
 ;; Direct test load: yes (requires keybindings explicitly).
 ;;
-;; This module provides whitespace manipulation operations for cleaning and transforming whitespace in text.
-
-;; Functions include:
-
-;; - removing leading and trailing whitespace
-;; - collapsing multiple spaces to single spaces
-;; - deleting blank lines
-;; - converting whitespace to hyphens.
-
-;; All operations work on the current line, active region, or entire buffer depending on context.
-
-;; Bound to keymap prefix C-; w
-
+;; Whitespace cleanup under C-; w: trim line edges, collapse runs of spaces,
+;; delete blank lines, enforce a single blank line, and hyphenate whitespace.
+;; Commands choose region, buffer, or current line based on prefix/mark state.
+;;
 ;;; Code:
 
 (require 'keybindings)  ;; provides cj/custom-keymap
diff --git a/modules/dwim-shell-config.el b/modules/dwim-shell-config.el
index 014194c7b..e8790a489 100644
--- a/modules/dwim-shell-config.el
+++ b/modules/dwim-shell-config.el
@@ -1,99 +1,23 @@
-;; dwim-shell-config.el --- Dired Shell Commands -*- coding: utf-8; lexical-binding: t; -*-
+;;; dwim-shell-config.el --- Dired shell command menu -*- coding: utf-8; lexical-binding: t; -*-
 ;;
 ;;; Commentary:
 ;;
 ;; Layer: 3 (Domain Workflow).
 ;; Category: D/P.
 ;; Load shape: eager.
-;; Eager reason: none; Dired/Dirvish shell commands, a command-loaded deferral
-;;   candidate.
+;; Eager reason: none; Dired/Dirvish shell commands can load by command.
 ;; Top-level side effects: package configuration via use-package.
-;; Runtime requires: cl-lib.
+;; Runtime requires: cl-lib, system-lib.
 ;; Direct test load: yes.
 ;;
-;; This module provides a collection of DWIM (Do What I Mean) shell commands
-;; for common file operations in Dired and other buffers. It leverages the
-;; `dwim-shell-command' package to execute shell commands on marked files
-;; with smart templating and progress tracking.
-;;
-;; Features:
-;; - Audio/Video conversion (mp3, opus, webp, HEVC)
-;; - Image manipulation (resize, flip, format conversion)
-;; - PDF operations (merge, split, password protection, OCR)
-;; - Archive management (zip/unzip)
-;; - Document conversion (epub to org, docx to pdf, pdf to txt)
-;; - Git operations (clone from clipboard)
-;; - External file opening with context awareness
-;;
-;; Workflow:
-;; 1. *Mark files in Dired/Dirvish*
-;;    - Use =m= to mark individual files
-;;    - Use =* .= to mark by extension
-;;    - Use =% m= to mark by regexp
-;;    - Or operate on the file under cursor if nothing is marked
-;;
-;; 2. *Execute a DWIM command*
-;;    - Call the command via =M-x dwim-shell-commands-[command-name]=
-;;    - Or bind frequently used commands to keys
-;;
-;; 3. *Command execution*
-;;    - The command runs asynchronously in the background
-;;    - A =*Async Shell Command*= buffer shows progress
-;;    - Files are processed with smart templating (replacing =<<f>>=, =<<fne>>=, etc.)
-;;
-;; 4. *Results*
-;;    - New files appear in the Dired/Dirvish buffer
-;;    - Buffer auto-refreshes when command completes
-;;    - Errors appear in the async buffer if something fails
-;;
-;; Requirements:
-;; The commands rely on various external utilities that need to be installed:
-;; - ffmpeg: Audio/video conversion
-;; - imagemagick (convert): Image manipulation
-;; - qpdf: PDF operations (requires version 8.x+ for secure password handling)
-;; - tesseract: OCR functionality
-;; - pandoc: Document conversion
-;; - atool: Archive extraction
-;; - rsvg-convert: SVG to PNG conversion
-;; - pdftotext: PDF text extraction
-;; - git: Version control operations
-;; - gpgconf: GPG agent management
-;; - 7z (p7zip): Secure password-protected archives
-;;
-;; On Arch Linux, install the requirements with:
-;; #+begin_src bash
-;; sudo pacman -S --needed ffmpeg imagemagick qpdf tesseract tesseract-data-eng pandoc atool librsvg poppler git gnupg p7zip zip unzip mkvtoolnix-cli mpv ruby
-;; #+end_src
-;;
-;; On MacOS, install the requirements with:
-;; #+begin_src bash
-;; brew install ffmpeg imagemagick qpdf tesseract pandoc atool librsvg poppler gnupg p7zip mkvtoolnix mpv
-;; #+end_src
-;;
-;; Usage:
-;; Commands operate on marked files in Dired or the current file in other modes.
-;; The package automatically replaces standard shell commands with DWIM versions
-;; for a more intuitive experience.
-;;
-;; Security:
-;; Password-protected operations (PDF encryption, archive encryption) use secure
-;; methods to avoid exposing passwords in process lists or command history:
-;; - PDF operations: Use temporary files with restrictive permissions (mode 600)
-;; - Archive operations: Use 7z instead of zip for better password handling
-;; - Temporary password files are automatically cleaned up after use
-;; - Note: Switched from zip to 7z for encryption due to zip's insecure -P flag
-;;
-;; Template Variables:
-;; - <<f>>: Full path to file
-;; - <<fne>>: File name without extension
-;; - <<e>>: File extension
-;; - <<b>>: Base name (file name with extension, no directory)
-;; - <<d>>: Directory path
-;; - <<n>>: Sequential number (for batch renaming)
-;; - <<td>>: Temporary directory
-;; - <<cb>>: Clipboard contents
-;; - <<*>>: All marked files
+;; Configures dwim-shell-command actions for marked Dired/Dirvish files:
+;; media conversion, archive/PDF/document operations, external opening, and a
+;; curated transient menu. Commands use dwim-shell templates for marked files or
+;; the current buffer file.
 ;;
+;; Password-bearing operations avoid command-line secrets by writing temporary
+;; password files with restrictive permissions and deleting them from the process
+;; sentinel after the spawned command exits.
 
 ;;; Code:
 
diff --git a/modules/local-repository.el b/modules/local-repository.el
index 9ce7a1af3..a9df09d38 100644
--- a/modules/local-repository.el
+++ b/modules/local-repository.el
@@ -1,4 +1,4 @@
-;;; local-repository.el --- local repository functionality -*- lexical-binding: t; coding: utf-8; -*-
+;;; local-repository.el --- Local package archive helpers -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
@@ -6,12 +6,15 @@
 ;; Layer: 4 (Optional).
 ;; Category: O/D/P.
 ;; Load shape: eager.
-;; Eager reason: none; local package-mirror workflow, a command-loaded deferral
-;;   candidate.
+;; Eager reason: none; local package mirror commands can autoload.
 ;; Top-level side effects: none.
-;; Runtime requires: elpa-mirror.
+;; Runtime requires: elpa-mirror when updating the mirror.
 ;; Direct test load: yes.
 ;;
+;; Adds the checked-in local package archive to package-archives with high
+;; priority, and provides a command to refresh that archive from installed
+;; packages via elpa-mirror.
+
 ;;; Code:
 
 (require 'elpa-mirror nil t)  ;; optional; cj/update-localrepo-repository fails at call-time if absent
diff --git a/modules/mousetrap-mode.el b/modules/mousetrap-mode.el
index 3817e0081..656d49e2f 100644
--- a/modules/mousetrap-mode.el
+++ b/modules/mousetrap-mode.el
@@ -1,4 +1,4 @@
-;;; mousetrap-mode.el ---  -*- coding: utf-8; lexical-binding: t; -*-
+;;; mousetrap-mode.el --- Profile-based mouse event blocking -*- coding: utf-8; lexical-binding: t; -*-
 ;;
 ;;; Commentary:
 ;;
@@ -11,25 +11,12 @@
 ;; Runtime requires: cl-lib.
 ;; Direct test load: yes.
 ;;
-;; Mouse Trap Mode is a minor mode for Emacs that disables most mouse and
-;; trackpad events to prevent accidental text modifications.  Hitting the
-;; trackpad and finding my text is being inserted in an unintended place is
-;; quite annoying, especially when you're overcaffeinated.
+;; Global minor mode that blocks accidental mouse edits while preserving allowed
+;; interaction categories per major-mode profile: scroll, click, drag, and
+;; multi-click.
 ;;
-;; The mode uses a profile-based architecture to selectively enable/disable
-;; mouse events based on the current major mode.  Profiles define which
-;; event categories are allowed (scrolling, clicks, drags, etc.), and modes
-;; are mapped to profiles.
-;;
-;; The keymap is built dynamically when the mode is toggled, so you can
-;; change profiles or mode mappings and re-enable the mode without reloading
-;; your Emacs configuration.
-;;
-;; Keymaps are buffer-local via `emulation-mode-map-alists', so each buffer
-;; gets the correct profile for its major mode independently.
-;;
-;; Inspired by this blog post from Malabarba
-;; https://endlessparentheses.com/disable-mouse-only-inside-emacs.html
+;; The mode builds buffer-local emulation keymaps from profiles, so changing a
+;; profile or mode mapping takes effect after toggling the mode.
 ;;
 ;;; Code:
 
diff --git a/modules/weather-config.el b/modules/weather-config.el
index d2912fedd..aa43605f4 100644
--- a/modules/weather-config.el
+++ b/modules/weather-config.el
@@ -1,4 +1,4 @@
-;;; weather-config.el ---  -*- lexical-binding: t; coding: utf-8; -*-
+;;; weather-config.el --- wttrin weather display and modeline setup -*- lexical-binding: t; coding: utf-8; -*-
 ;; author: Craig Jennings <c@cjennings.net>
 ;;; Commentary:
 ;;
@@ -11,9 +11,8 @@
 ;; Runtime requires: none (configures packages via use-package).
 ;; Direct test load: yes.
 ;;
-;; Call M-W to open wttrin with your preferred location list immediately.
-;; Adjust the city list by editing `wttrin-default-locations` or answering wttrin prompts when asked.
-;; Forecasts arrive in an Emacs buffer, so you can stay keyboard-only while checking weather.
+;; Configures wttrin for favorite-location forecasts, mode-line weather, and
+;; whereami-backed geolocation. M-S-w opens the weather buffer.
 ;;
 ;;; Code: