From cad351ec00c3f78cfb6e203d87c7309a620e485c Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sun, 24 May 2026 16:57:56 -0500
Subject: docs(load-graph): classify domain, integration, and optional modules
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Eighth classification batch: 17 domain/integration/optional modules — ai-config, ai-vterm, browser-config, calendar-sync, calibredb-epub-config, chrono-tools, dirvish-config, dwim-shell-config, erc-config, eshell-config, eww-config, flyspell-and-abbrev, games-config, gloss-config, httpd-config, jumper, latex-config. I annotated each header, added a Batch 8 table to the inventory, and extended the validation allowlist. 82 of 102 modules are now classified.

Almost all are eager only by init order and become command/hook/mode-loaded. calendar-sync stays eager when its .local.el is present. One new hidden dependency: calendar-sync guards its C-; g registration with a boundp shim and doesn't require keybindings, so the binding drops standalone.

I deferred elfeed-config rather than annotate it. Its header edit triggers byte-compilation, and the existing tests only pass when the module loads as interpreted source — the compiled cj/elfeed-process-entries inlines an elfeed struct accessor the stubs can't intercept, and the batch test environment has no elfeed package to build real structs. It needs its tests rewritten first, recorded in the inventory and a new todo task.

Also made the header allowlist scoping test durable: it used games-config (now classified) as its unclassified example; switched to a sentinel name plus a duplicate-entry guard.
---
 modules/ai-config.el             | 10 ++++++++++
 modules/ai-vterm.el              | 12 +++++++++++-
 modules/browser-config.el        | 10 ++++++++++
 modules/calendar-sync.el         | 16 +++++++++++++++-
 modules/calibredb-epub-config.el | 11 ++++++++++-
 modules/chrono-tools.el          |  9 +++++++++
 modules/dirvish-config.el        | 11 ++++++++++-
 modules/dwim-shell-config.el     |  9 +++++++++
 modules/erc-config.el            | 10 ++++++++++
 modules/eshell-config.el         | 10 +++++++++-
 modules/eww-config.el            |  8 ++++++++
 modules/flyspell-and-abbrev.el   | 10 +++++++++-
 modules/games-config.el          |  8 ++++++++
 modules/gloss-config.el          |  9 +++++++++
 modules/httpd-config.el          | 10 +++++++++-
 modules/jumper.el                | 10 +++++++++-
 modules/latex-config.el          |  8 ++++++++
 17 files changed, 163 insertions(+), 8 deletions(-)

(limited to 'modules')

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.
-- 
cgit v1.2.3