9 files changed, 89 insertions, 3 deletions
diff --git a/modules/coverage-core.el b/modules/coverage-core.el
index 47e891e6..0a8b2464 100644
--- a/modules/coverage-core.el
+++ b/modules/coverage-core.el
@@ -2,6 +2,15 @@
 ;; author: Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
+;;
+;; Layer: 2 (Core UX).
+;; Category: C/L.
+;; Load shape: eager.
+;; Eager reason: the F7 coverage entry point and the backend registry.
+;; Top-level side effects: one global key (F7).
+;; Runtime requires: seq, subr-x, system-lib.
+;; Direct test load: yes.
+;;
 ;; Language-agnostic core for diff-aware coverage reporting.
 ;;
 ;; Reads an LCOV file, invokes git diff at a selectable scope,
diff --git a/modules/coverage-elisp.el b/modules/coverage-elisp.el
index 048c81dd..0c640c50 100644
--- a/modules/coverage-elisp.el
+++ b/modules/coverage-elisp.el
@@ -2,6 +2,15 @@
 ;; author: Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
+;;
+;; Layer: 2 (Core UX).
+;; Category: C/P.
+;; Load shape: eager.
+;; Eager reason: registers the elisp coverage backend after coverage-core; cheap.
+;; Top-level side effects: backend registration via use-package.
+;; Runtime requires: coverage-core.
+;; Direct test load: yes.
+;;
 ;; Registers the `elisp' coverage backend with `coverage-core'.
 ;;
 ;; Detection: a project root with a Makefile / Eask / Cask plus any
diff --git a/modules/dev-fkeys.el b/modules/dev-fkeys.el
index 3b0a818c..02e8a72e 100644
--- a/modules/dev-fkeys.el
+++ b/modules/dev-fkeys.el
@@ -1,6 +1,18 @@
 ;;; dev-fkeys.el --- Developer F-key dispatchers -*- lexical-binding: t -*-
 
 ;;; Commentary:
+;;
+;; Layer: 2 (Core UX).
+;; Category: C.
+;; Load shape: eager.
+;; Eager reason: the F4/F6 developer command entry points.
+;; Top-level side effects: six global F-key bindings; conditionally registers a
+;;   C-; P binding.
+;; Runtime requires: cl-lib, system-lib. keybindings is needed for the C-; P
+;;   binding but is declared only via eval-when-compile and guarded by `boundp',
+;;   so that binding silently drops standalone. Phase 2 fix.
+;; Direct test load: conditional (C-; P registration skipped without keybindings).
+;;
 ;; Project-aware F-key block for developer workflows:
 ;;
 ;;   F4    completing-read of compile/run candidates filtered by project type
diff --git a/modules/diff-config.el b/modules/diff-config.el
index 45c2a778..75869a73 100644
--- a/modules/diff-config.el
+++ b/modules/diff-config.el
@@ -2,7 +2,16 @@
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
-
+;;
+;; Layer: 2 (Core UX).
+;; Category: C/P.
+;; Load shape: eager.
+;; Eager reason: Ediff and diff UX defaults; eager only by init order, a
+;;   package-load deferral candidate.
+;; Top-level side effects: package configuration via use-package.
+;; Runtime requires: none.
+;; Direct test load: yes.
+;;
 ;; I've configured Ediff for a clean and efficient diff experience.
 
 ;; • Ediff will use a plain control window, horizontal splits, ignore whitespace, and only highlight the current change.
diff --git a/modules/flycheck-config.el b/modules/flycheck-config.el
index f064cb13..8932a3ac 100644
--- a/modules/flycheck-config.el
+++ b/modules/flycheck-config.el
@@ -2,7 +2,18 @@
 ;;  author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
-
+;;
+;; Layer: 2 (Core UX).
+;; Category: C/P.
+;; Load shape: eager.
+;; Eager reason: general linting setup; spec target is hook-loaded, a deferral
+;;   candidate.
+;; Top-level side effects: package configuration via use-package, binds into
+;;   cj/custom-keymap through use-package :map.
+;; Runtime requires: keybindings is needed for the cj/custom-keymap :map binding
+;;   but is not required here; the binding fails standalone. Phase 2 fix.
+;; Direct test load: conditional (needs cj/custom-keymap for the :map binding).
+;;
 ;; This file configures Flycheck for on-demand syntax and grammar checking.
 ;; - Flycheck starts automatically only in sh-mode and emacs-lisp-mode
 
diff --git a/modules/help-config.el b/modules/help-config.el
index cfe67bf0..ce9fd861 100644
--- a/modules/help-config.el
+++ b/modules/help-config.el
@@ -3,6 +3,15 @@
 
 ;;; Commentary:
 ;;
+;; Layer: 2 (Core UX).
+;; Category: C/P.
+;; Load shape: eager.
+;; Eager reason: help/info/man configuration and its keybindings; eager only by
+;;   init order, a deferral candidate.
+;; Top-level side effects: two global keys, package configuration via use-package.
+;; Runtime requires: none.
+;; Direct test load: yes.
+;;
 ;; This module enhances Emacs' built-in help system and documentation features.
 ;; It configures:
 ;;
diff --git a/modules/help-utils.el b/modules/help-utils.el
index 91ac8947..f9f5d142 100644
--- a/modules/help-utils.el
+++ b/modules/help-utils.el
@@ -3,6 +3,15 @@
 ;;
 ;;; Commentary:
 ;;
+;; Layer: 2 (Core UX).
+;; Category: L/D.
+;; Load shape: eager.
+;; Eager reason: documentation-search commands; eager only by init order, a
+;;   deferral candidate (autoload commands) for Phase 4.
+;; Top-level side effects: one global key, package configuration via use-package.
+;; Runtime requires: none.
+;; Direct test load: yes.
+;;
 ;; This module provides various utilities for accessing documentation and help resources
 ;; directly within Emacs.
 ;; DevDocs for programming documentation
diff --git a/modules/test-runner.el b/modules/test-runner.el
index 1c993446..2a6f25e7 100644
--- a/modules/test-runner.el
+++ b/modules/test-runner.el
@@ -2,7 +2,15 @@
 ;; author: Craig Jennings <c@cjennings.net>
 ;;
 ;;; Commentary:
-
+;;
+;; Layer: 2 (Core UX).
+;; Category: C/L.
+;; Load shape: eager.
+;; Eager reason: the test keymap entry point and project-scoped runner state.
+;; Top-level side effects: defines a test keymap, registers it under cj/custom-keymap.
+;; Runtime requires: ert, cl-lib, keybindings.
+;; Direct test load: yes (requires keybindings explicitly).
+;;
 ;; This module provides a powerful ERT test runner with focus/unfocus workflow
 ;; for efficient test-driven development in Emacs Lisp projects.
 ;;
diff --git a/modules/vc-config.el b/modules/vc-config.el
index 45aec73b..8b82b4cc 100644
--- a/modules/vc-config.el
+++ b/modules/vc-config.el
@@ -1,6 +1,16 @@
 ;;; vc-config.el --- Version Control Configuration -*- lexical-binding: t; coding: utf-8; -*-
 ;; author: Craig Jennings <c@cjennings.net>
 ;;; Commentary:
+;;
+;; Layer: 2 (Core UX).
+;; Category: C/P.
+;; Load shape: eager.
+;; Eager reason: the C-x g Magit entry point and the git keymap.
+;; Top-level side effects: defines two keymaps, registers under cj/custom-keymap,
+;;   package configuration via use-package.
+;; Runtime requires: user-constants, keybindings.
+;; Direct test load: yes (requires keybindings explicitly).
+;;
 ;; C-x g is my general entry to Magit's version control via the status page.
 
 ;; Navigating changes in file happens via git gutter