17 files changed, 163 insertions, 8 deletions
diff --git a/modules/ai-config.el b/modules/ai-config.el
index fad43584..e2a71fed 100644
--- a/modules/ai-config.el
+++ b/modules/ai-config.el
@@ -2,6 +2,16 @@
 ;; author Craig Jennings <c@cjennings.net>
 ;;
 ;;; Commentary:
+;;
+;; Layer: 3 (Domain Workflow).
+;; Category: D/P.
+;; Load shape: eager.
+;; Eager reason: registers the cj/ai-keymap (C-; a); GPTel itself should load on
+;;   command, a Phase 5 deferral candidate.
+;; Top-level side effects: defines cj/ai-keymap, registers it under cj/custom-keymap.
+;; Runtime requires: keybindings, system-lib.
+;; Direct test load: yes (requires keybindings explicitly).
+;;
 ;; Configuration for AI integrations in Emacs, focused on GPTel.
 ;;
 ;; Main Features:
diff --git a/modules/ai-vterm.el b/modules/ai-vterm.el
index 4306db9a..60d0c7f3 100644
--- a/modules/ai-vterm.el
+++ b/modules/ai-vterm.el
@@ -3,7 +3,17 @@
 ;; Author: Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
-
+;;
+;; Layer: 3 (Domain Workflow).
+;; Category: D.
+;; Load shape: eager.
+;; Eager reason: registers four global keys for the AI-agent vterm launcher; a
+;;   command-loaded deferral candidate.
+;; Top-level side effects: four global key bindings.
+;; Runtime requires: cl-lib, seq, cj-window-geometry-lib, cj-window-toggle-lib,
+;;   host-environment.
+;; Direct test load: yes.
+;;
 ;; Picks an AI-agent project (a dir under ~/.emacs.d, ~/code/*, or
 ;; ~/projects/* containing .ai/protocols.org), opens or reuses a vterm
 ;; buffer named "agent [<basename>]", sends the agent's startup
diff --git a/modules/browser-config.el b/modules/browser-config.el
index 52c3b8a6..4a2c5462 100644
--- a/modules/browser-config.el
+++ b/modules/browser-config.el
@@ -2,6 +2,16 @@
 ;; author: Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
+;;
+;; Layer: 3 (Domain Workflow).
+;; Category: D/P.
+;; Load shape: eager.
+;; Eager reason: registers one browser-selection key; a command-loaded deferral
+;;   candidate.
+;; Top-level side effects: one global key binding.
+;; Runtime requires: cl-lib.
+;; Direct test load: yes.
+;;
 ;; This module provides browser selection and configuration for Emacs.
 ;; It automatically discovers available browsers on the system, allows the user
 ;; to choose their preferred browser via completing-read, and persists the choice
diff --git a/modules/calendar-sync.el b/modules/calendar-sync.el
index 4ccb0917..4d1ea219 100644
--- a/modules/calendar-sync.el
+++ b/modules/calendar-sync.el
@@ -4,7 +4,21 @@
 ;; Created: 2025-11-16
 
 ;;; Commentary:
-
+;;
+;; Layer: 3 (Domain Workflow).
+;; Category: D/S.
+;; Load shape: eager only when calendar-sync.local.el configures calendars.
+;; Eager reason: daily-driver workflow; calendars are expected synced at the
+;;   first session. Timers and network fetches are guarded for batch/test loads.
+;; Top-level side effects: defines a calendar keymap and conditionally registers
+;;   it under cj/custom-keymap; timer and network fetches guarded by
+;;   config/noninteractive checks.
+;; Runtime requires: cl-lib, subr-x, system-lib, cj-org-text-lib. keybindings is
+;;   needed for the C-; g binding but only reached through a boundp guard, so the
+;;   binding silently drops standalone. Phase 2 fix.
+;; Direct test load: conditional (C-; g registration skipped without keybindings;
+;;   private config optional).
+;;
 ;; Simple, reliable one-way sync from multiple calendars to Org mode.
 ;; Downloads .ics files from calendar URLs (Google, Proton, etc.) and
 ;; converts to Org format. No OAuth, no API complexity, just file conversion.
diff --git a/modules/calibredb-epub-config.el b/modules/calibredb-epub-config.el
index 45a0b79a..4243e509 100644
--- a/modules/calibredb-epub-config.el
+++ b/modules/calibredb-epub-config.el
@@ -2,7 +2,16 @@
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
-
+;;
+;; Layer: 4 (Optional).
+;; Category: O/D/P.
+;; Load shape: eager.
+;; Eager reason: none; optional ebook workflow, a command-loaded deferral
+;;   candidate for Phase 4.
+;; Top-level side effects: one add-hook, one advice-add, package config.
+;; Runtime requires: user-constants, subr-x.
+;; Direct test load: yes.
+;;
 ;; This module provides a comprehensive ebook management and reading experience
 ;; within Emacs, integrating CalibreDB for library management and Nov for EPUB
 ;; reading.
diff --git a/modules/chrono-tools.el b/modules/chrono-tools.el
index 33f2b11e..9ccba667 100644
--- a/modules/chrono-tools.el
+++ b/modules/chrono-tools.el
@@ -3,6 +3,15 @@
 ;;
 ;;; Commentary:
 ;;
+;; Layer: 3 (Domain Workflow).
+;; Category: D/P.
+;; Load shape: eager.
+;; Eager reason: none; calendar/timer commands, a command-loaded deferral
+;;   candidate.
+;; Top-level side effects: package configuration via use-package.
+;; Runtime requires: user-constants.
+;; Direct test load: yes.
+;;
 ;; This module centralizes configuration for Emacs time-related tools:
 ;;
 ;; – time-zones: interactive world clock with fuzzy search and time shifting
diff --git a/modules/dirvish-config.el b/modules/dirvish-config.el
index 8fe5c7b8..9e50bbc0 100644
--- a/modules/dirvish-config.el
+++ b/modules/dirvish-config.el
@@ -2,7 +2,16 @@
 ;; author: Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
-
+;;
+;; Layer: 3 (Domain Workflow).
+;; Category: D/P.
+;; Load shape: eager.
+;; Eager reason: none; file manager, a command/hook-loaded deferral candidate.
+;; Top-level side effects: three add-hook, package configuration via use-package.
+;; Runtime requires: user-constants, system-utils, host-environment, system-lib,
+;;   external-open-lib.
+;; Direct test load: yes.
+;;
 ;; Enhanced file management via Dirvish (modern dired replacement) with icons,
 ;; previews, and quick access directories (press 'g'). Includes utilities for
 ;; ediff, playlist creation, path copying, and external file manager integration.
diff --git a/modules/dwim-shell-config.el b/modules/dwim-shell-config.el
index 046a7e63..83f1d4a2 100644
--- a/modules/dwim-shell-config.el
+++ b/modules/dwim-shell-config.el
@@ -2,6 +2,15 @@
 ;;
 ;;; Commentary:
 ;;
+;; Layer: 3 (Domain Workflow).
+;; Category: D/P.
+;; Load shape: eager.
+;; Eager reason: none; Dired/Dirvish shell commands, a command-loaded deferral
+;;   candidate.
+;; Top-level side effects: package configuration via use-package.
+;; Runtime requires: cl-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
diff --git a/modules/erc-config.el b/modules/erc-config.el
index 76e7e74e..e63b12eb 100644
--- a/modules/erc-config.el
+++ b/modules/erc-config.el
@@ -3,6 +3,16 @@
 ;;
 ;;; Commentary:
 ;;
+;; Layer: 4 (Optional).
+;; Category: O/D/P.
+;; Load shape: eager.
+;; Eager reason: none; IRC should not be a startup load, a command-loaded
+;;   deferral candidate for Phase 5.
+;; Top-level side effects: defines an ERC keymap, registers it under
+;;   cj/custom-keymap, package configuration via use-package.
+;; Runtime requires: cl-lib, keybindings.
+;; Direct test load: yes (requires keybindings explicitly).
+;;
 ;; Enhanced ERC configuration with multi-server support.
 ;;
 ;; Main keybindings:
diff --git a/modules/eshell-config.el b/modules/eshell-config.el
index 4d180d1c..64bc88c6 100644
--- a/modules/eshell-config.el
+++ b/modules/eshell-config.el
@@ -2,7 +2,15 @@
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
-
+;;
+;; Layer: 3 (Domain Workflow).
+;; Category: D/P.
+;; Load shape: eager.
+;; Eager reason: none; shell/REPL, a command/hook-loaded deferral candidate.
+;; Top-level side effects: one add-hook, one advice-add, package config.
+;; Runtime requires: system-utils.
+;; Direct test load: yes.
+;;
 ;; ESHELL
 ;; - Eshell is useful as a REPL
 ;; - Redirect to the kill ring : ls > /dev/kill
diff --git a/modules/eww-config.el b/modules/eww-config.el
index 16a1f5eb..066fae98 100644
--- a/modules/eww-config.el
+++ b/modules/eww-config.el
@@ -3,6 +3,14 @@
 ;;
 ;;; Commentary:
 ;;
+;; Layer: 3 (Domain Workflow).
+;; Category: D/P.
+;; Load shape: eager.
+;; Eager reason: none; web-browsing helpers, a command-loaded deferral candidate.
+;; Top-level side effects: package configuration via use-package.
+;; Runtime requires: cl-lib.
+;; Direct test load: yes.
+;;
 ;; This module provides a minimal, privacy-focused browsing experience with:
 ;; - Simplified navigation keybindings (< and > for back/forward)
 ;; - Quick URL copying to clipboard
diff --git a/modules/flyspell-and-abbrev.el b/modules/flyspell-and-abbrev.el
index e732ac46..376a9dc5 100644
--- a/modules/flyspell-and-abbrev.el
+++ b/modules/flyspell-and-abbrev.el
@@ -2,7 +2,15 @@
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
-
+;;
+;; Layer: 2 (Core UX).
+;; Category: C/P.
+;; Load shape: eager.
+;; Eager reason: text-mode spelling and abbrev hooks; spec target is hook-loaded.
+;; Top-level side effects: package configuration via use-package (mode hooks).
+;; Runtime requires: cl-lib.
+;; Direct test load: yes.
+;;
 ;; WORKFLOW:
 ;; This module provides intelligent spell checking with automatic abbreviation
 ;; creation to prevent repeated misspellings.
diff --git a/modules/games-config.el b/modules/games-config.el
index e0c512ef..9aa59816 100644
--- a/modules/games-config.el
+++ b/modules/games-config.el
@@ -3,6 +3,14 @@
 ;;
 ;;; Commentary:
 ;;
+;; Layer: 4 (Optional).
+;; Category: O.
+;; Load shape: eager.
+;; Eager reason: none; optional games, a command-loaded deferral candidate.
+;; Top-level side effects: package configuration via use-package.
+;; Runtime requires: none.
+;; Direct test load: yes.
+;;
 ;; Configuration for game packages.
 ;;
 ;; - Malyon for playing interactive fiction and text adventures in Z-machine format
diff --git a/modules/gloss-config.el b/modules/gloss-config.el
index 63b3c8d2..8afe44d4 100644
--- a/modules/gloss-config.el
+++ b/modules/gloss-config.el
@@ -3,6 +3,15 @@
 
 ;;; Commentary:
 ;;
+;; Layer: 4 (Optional).
+;; Category: O/D/P.
+;; Load shape: eager.
+;; Eager reason: none; optional glossary workflow (v1 shakedown), a command-loaded
+;;   deferral candidate.
+;; Top-level side effects: package configuration via use-package.
+;; Runtime requires: none.
+;; Direct test load: yes.
+;;
 ;; gloss — Glossary Lookup with Online-Sourced Selection.
 ;;
 ;; Personal glossary on `C-h g'.  Looks up terms in a single git-tracked
diff --git a/modules/httpd-config.el b/modules/httpd-config.el
index ac1f7a0f..c9039942 100644
--- a/modules/httpd-config.el
+++ b/modules/httpd-config.el
@@ -2,7 +2,15 @@
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
-
+;;
+;; Layer: 4 (Optional).
+;; Category: O/D/P.
+;; Load shape: eager.
+;; Eager reason: none; local web server, a command-loaded deferral candidate.
+;; Top-level side effects: package configuration via use-package.
+;; Runtime requires: none.
+;; Direct test load: yes.
+;;
 ;;; Code:
 
 
diff --git a/modules/jumper.el b/modules/jumper.el
index 67d930aa..8941d508 100644
--- a/modules/jumper.el
+++ b/modules/jumper.el
@@ -7,7 +7,15 @@
 ;; URL: https://github.com/cjennings/jumper
 
 ;;; Commentary:
-
+;;
+;; Layer: 4 (Optional).
+;; Category: O/L.
+;; Load shape: eager.
+;; Eager reason: none; navigation helper, a command-loaded deferral candidate.
+;; Top-level side effects: defines a jumper keymap.
+;; Runtime requires: cl-lib.
+;; Direct test load: yes.
+;;
 ;; Jumper provides a simple way to store and jump between locations
 ;; in your codebase without needing to remember register assignments.
 ;;
diff --git a/modules/latex-config.el b/modules/latex-config.el
index a0af2a1a..8636e2cd 100644
--- a/modules/latex-config.el
+++ b/modules/latex-config.el
@@ -3,6 +3,14 @@
 
 ;;; Commentary:
 ;;
+;; Layer: 3 (Domain Workflow).
+;; Category: D/P.
+;; Load shape: eager.
+;; Eager reason: none; LaTeX/AUCTeX editing, a hook/mode-loaded deferral candidate.
+;; Top-level side effects: package configuration via use-package.
+;; Runtime requires: none.
+;; Direct test load: yes.
+;;
 ;; WORKFLOW:
 ;;
 ;; Opening any tex file will put you into LaTeX mode.