13 files changed, 131 insertions, 1 deletions
diff --git a/modules/hugo-config.el b/modules/hugo-config.el
index 1feaa452..94be9dd5 100644
--- a/modules/hugo-config.el
+++ b/modules/hugo-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: none; blog publishing is a command-loaded deferral candidate
+;;   for Phase 4.
+;; Top-level side effects: package configuration via use-package.
+;; Runtime requires: user-constants, host-environment.
+;; Direct test load: yes.
+;;
 ;; Integrates ox-hugo for publishing Org files to a Hugo website.
 ;;
 ;; One-file-per-post workflow:
diff --git a/modules/org-agenda-config.el b/modules/org-agenda-config.el
index 231eff8a..3fa09708 100644
--- a/modules/org-agenda-config.el
+++ b/modules/org-agenda-config.el
@@ -3,6 +3,16 @@
 ;;
 ;;; Commentary:
 ;;
+;; Layer: 3 (Domain Workflow).
+;; Category: D/S.
+;; Load shape: eager.
+;; Eager reason: daily agenda workflow; the user expects agenda available at the
+;;   first session.
+;; Top-level side effects: one add-hook and an idle timer that builds the agenda
+;;   file cache 10s after startup (guarded; spec tracks the cache lifecycle).
+;; Runtime requires: user-constants, system-lib, cj-cache-lib.
+;; Direct test load: yes.
+;;
 ;; Performance:
 ;; - Caches agenda file list to avoid scanning projects directory on every view
 ;; - Cache builds asynchronously 10 seconds after Emacs startup (non-blocking)
diff --git a/modules/org-babel-config.el b/modules/org-babel-config.el
index b3a3036a..821403a0 100644
--- a/modules/org-babel-config.el
+++ b/modules/org-babel-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: none necessary; Babel language setup belongs after Org loads
+;;   (after-load deferral candidate).
+;; Top-level side effects: one global key, package configuration via use-package.
+;; Runtime requires: none (configures packages via use-package).
+;; Direct test load: yes.
+;;
 ;; All Org-Babel and Org-Tempo Packages, Settings, and Languages.
 
 ;;; Code:
diff --git a/modules/org-capture-config.el b/modules/org-capture-config.el
index 39cafe03..43b42b5e 100644
--- a/modules/org-capture-config.el
+++ b/modules/org-capture-config.el
@@ -2,6 +2,17 @@
 ;; author: Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
+;;
+;; Layer: 3 (Domain Workflow).
+;; Category: D/P.
+;; Load shape: eager.
+;; Eager reason: capture is a daily hot path; org-protocol capture handlers must
+;;   be registered for external capture to work.
+;; Top-level side effects: capture templates and org-protocol handlers via
+;;   use-package.
+;; Runtime requires: none (configures packages via use-package).
+;; Direct test load: yes.
+;;
 ;; Customizations related to org-capture and org-refile.
 ;; Includes capture templates for tasks, links, PDFs, EPUBs, emails, and drill questions.
 
diff --git a/modules/org-config.el b/modules/org-config.el
index a2615b0c..8ebfdbdb 100644
--- a/modules/org-config.el
+++ b/modules/org-config.el
@@ -1,7 +1,16 @@
 ;;; org-config --- Settings and Enhancements to Org Mode -*- lexical-binding: t; coding: utf-8; -*-
 ;; author Craig Jennings <c@cjennings.net>
 ;;; Commentary:
-
+;;
+;; Layer: 3 (Domain Workflow).
+;; Category: C/D/P.
+;; Load shape: eager.
+;; Eager reason: core Org behavior and org-protocol setup; a daily-driver hot path.
+;; Top-level side effects: org-protocol setup, a cj/custom-keymap binding,
+;;   package configuration via use-package.
+;; Runtime requires: keybindings.
+;; Direct test load: yes (requires keybindings explicitly).
+;;
 ;; note: org-archive-location is set in the :config section after org loads
 
 ;;; Code:
diff --git a/modules/org-contacts-config.el b/modules/org-contacts-config.el
index ff14629b..bd39b6e8 100644
--- a/modules/org-contacts-config.el
+++ b/modules/org-contacts-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: none necessary; belongs after Org/mail load (after-load
+;;   deferral candidate).
+;; Top-level side effects: one global key, package configuration via use-package.
+;; Runtime requires: user-constants.
+;; Direct test load: yes.
+;;
 ;; Configuration for org-contacts, providing contact management within org-mode.
 ;; Integrates with mu4e for email address completion and org-roam for linking
 ;; contacts to projects and notes.
diff --git a/modules/org-drill-config.el b/modules/org-drill-config.el
index c3852ed1..b695619c 100644
--- a/modules/org-drill-config.el
+++ b/modules/org-drill-config.el
@@ -2,6 +2,15 @@
 ;; author: Craig Jennings <c@cjennings.net>
 ;;; Commentary:
 ;;
+;; Layer: 4 (Optional).
+;; Category: O/D/P.
+;; Load shape: eager.
+;; Eager reason: none; optional flashcard workflow, a command-loaded deferral
+;;   candidate for Phase 4.
+;; Top-level side effects: defines a drill keymap, registers it under cj/custom-keymap.
+;; Runtime requires: user-constants, keybindings.
+;; Direct test load: yes (requires keybindings explicitly).
+;;
 ;; Notes: Org-Drill
 ;; `C-; D s' picks a flashcard file from `drill-dir' and starts a session;
 ;; `C-u C-; D s' lets you pick the directory first.  `C-; D f' drills
diff --git a/modules/org-export-config.el b/modules/org-export-config.el
index 0cf0af15..493316f9 100644
--- a/modules/org-export-config.el
+++ b/modules/org-export-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: none; export backends/processes are a command-loaded deferral
+;;   candidate for Phase 4.
+;; Top-level side effects: package configuration via use-package.
+;; Runtime requires: system-lib.
+;; Direct test load: yes.
+;;
 ;; This module configures Org mode's export capabilities, providing multiple
 ;; backend options for converting Org documents to various formats.
 ;;
diff --git a/modules/org-noter-config.el b/modules/org-noter-config.el
index ca8432a2..6504550f 100644
--- a/modules/org-noter-config.el
+++ b/modules/org-noter-config.el
@@ -2,6 +2,16 @@
 
 ;;; Commentary:
 ;;
+;; Layer: 4 (Optional).
+;; Category: O/D/P.
+;; Load shape: eager.
+;; Eager reason: none; PDF/EPUB note-taking is a command-loaded deferral
+;;   candidate for Phase 4.
+;; Top-level side effects: one add-hook, defines a keymap, registers under
+;;   cj/custom-keymap.
+;; Runtime requires: cl-lib, user-constants, keybindings.
+;; Direct test load: yes (requires keybindings explicitly).
+;;
 ;; Org-noter configuration for taking notes on PDF and EPUB documents.
 ;;
 ;; Workflow:
diff --git a/modules/org-refile-config.el b/modules/org-refile-config.el
index 3c3cc7da..a6b7ac3a 100644
--- a/modules/org-refile-config.el
+++ b/modules/org-refile-config.el
@@ -1,6 +1,17 @@
 ;;; org-refile-config.el --- Org Refile Customizations -*- lexical-binding: t; coding: utf-8; -*-
 ;; author: Craig Jennings <c@cjennings.net>
 ;;; Commentary:
+;;
+;; Layer: 3 (Domain Workflow).
+;; Category: D/S.
+;; Load shape: eager.
+;; Eager reason: daily refile workflow; the user expects refile targets ready at
+;;   the first session.
+;; Top-level side effects: an idle timer that builds the refile-target cache
+;;   (guarded; spec tracks the cache lifecycle).
+;; Runtime requires: system-lib, cj-cache-lib.
+;; Direct test load: yes.
+;;
 ;; Configuration and custom functions for org-mode refiling.
 ;;
 ;; Performance:
diff --git a/modules/org-reveal-config.el b/modules/org-reveal-config.el
index 89d5480e..bc002276 100644
--- a/modules/org-reveal-config.el
+++ b/modules/org-reveal-config.el
@@ -2,6 +2,16 @@
 ;; author: Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
+;;
+;; Layer: 4 (Optional).
+;; Category: O/D/P.
+;; Load shape: eager.
+;; Eager reason: none; presentation export is a command-loaded deferral
+;;   candidate for Phase 4.
+;; Top-level side effects: package configuration via use-package.
+;; Runtime requires: none (configures packages via use-package).
+;; Direct test load: yes.
+;;
 ;; Integrates ox-reveal for creating reveal.js presentations from Org files.
 ;;
 ;; Fully offline workflow using a local reveal.js clone (managed by
diff --git a/modules/org-roam-config.el b/modules/org-roam-config.el
index c6e8977f..fdd9e1fc 100644
--- a/modules/org-roam-config.el
+++ b/modules/org-roam-config.el
@@ -1,6 +1,17 @@
 ;;; org-roam-config.el --- Org-Roam Config -*- lexical-binding: t; coding: utf-8; -*-
 ;; author: Craig Jennings <c@cjennings.net>
 ;;; Commentary:
+;;
+;; Layer: 3 (Domain Workflow).
+;; Category: D/P/S.
+;; Load shape: eager.
+;; Eager reason: daily knowledge-management workflow; capture/finalize hooks and
+;;   the roam database.
+;; Top-level side effects: one global key, org-roam database setup, package
+;;   configuration via use-package.
+;; Runtime requires: user-constants.
+;; Direct test load: yes.
+;;
 ;; Configuration and utilities for org-roam knowledge management.
 ;;
 ;; Key features:
diff --git a/modules/org-webclipper.el b/modules/org-webclipper.el
index 2a6d7164..9c2f1061 100644
--- a/modules/org-webclipper.el
+++ b/modules/org-webclipper.el
@@ -2,6 +2,15 @@
 
 ;;; Commentary:
 ;;
+;; Layer: 4 (Optional).
+;; Category: O/D/P.
+;; Load shape: eager.
+;; Eager reason: none; web clipping runs via org-protocol/command, a Phase 4
+;;   protocol/command-loaded deferral candidate.
+;; Top-level side effects: org-protocol handler registration via use-package.
+;; Runtime requires: none (configures packages via use-package).
+;; Direct test load: yes.
+;;
 ;; This package provides a seamless "fire-and-forget" workflow for clipping
 ;; web pages from the browser directly into an Org file using org-protocol
 ;; and org-web-tools.