docs(load-graph): seed module inventory and annotate foundation headers

I started the init.el load-graph classification with the foundation batch. I added docs/design/module-inventory.org as the living per-module inventory and annotated the seven foundation modules (system-lib, user-constants, host-environment, system-defaults, keyboard-compat, keybindings, config-utilities) with the load-graph header contract: layer, category, load shape, eager reason, top-level side effects, runtime requires, and direct-test-load safety.

I changed no load order, so init.el keeps its current eager order. The inventory records one hidden dependency for Phase 2: system-defaults uses host-environment and user-constants symbols at load while declaring them eval-when-compile, so the compiled module cannot load standalone.

8 files changed, 258 insertions, 2 deletions

diff --git a/docs/design/module-inventory.org b/docs/design/module-inventory.org
new file mode 100644
index 00000000..b1e2841e
--- /dev/null
+++ b/docs/design/module-inventory.org
@@ -0,0 +1,180 @@
+#+TITLE: Module Inventory — init.el Load Graph
+#+AUTHOR: Craig Jennings
+#+DATE: 2026-05-24
+
+* Purpose
+
+Living per-module inventory for the [[file:init-load-graph.org][init.el load-graph refactor]]. The
+spec's module-category table is the seed; this file is the per-module truth as
+each module is inspected and classified. A module moves from [[*Pending
+classification][Pending classification]] into [[*Classified modules][Classified
+modules]] once its source has been read and its load-graph header written.
+
+Phase 1 exit criterion: every module required by =init.el= (102 total) is
+represented here with a category and target load shape, every eager survivor
+has a documented reason, and top-level timer/process/network side effects are
+identified. Classification proceeds in batches; the header-validation test
+=tests/test-init-module-headers.el= enforces the contract on each classified
+module.
+
+This inventory is independent from the helper inventory owned by
+=utility-consolidation.org=.
+
+* Status
+
+- Phase 1 (Inventory and Contracts), in progress.
+- Batch 1 (Foundation, Layer 1): classified. 7 of 102 modules.
+- No load-order changes have been made; =init.el= keeps its current eager order.
+
+* Legend
+
+Category key (a module may carry two, e.g. =F/S=):
+
+- =F= foundation or shared library/config
+- =C= core eager UX
+- =P= package configuration (usually hook/command/package loaded)
+- =D= domain workflow with a possible eager reason
+- =S= startup side-effect / timer / process owner
+- =O= optional, entertainment, experimental, rarely used
+- =L= pure-ish library / command helpers, easy to load directly
+
+Load shape: =eager= | =hook= | =mode= | =command= | =after-load=.
+
+Direct test load: =yes= | =conditional= | =no= — can the module be loaded
+directly in batch without first loading the rest of init?
+
+* Classified modules
+
+** Batch 1 — Foundation (Layer 1)
+
+| Module | Layer | Cat | Current | Target | Runtime requires | Top-level side effects | Direct load |
+|--------+-------+-----+---------+--------+------------------+------------------------+-------------|
+| =system-lib= | 1 | F/L | eager | eager | none (auth-source on demand) | none | yes |
+| =user-constants= | 1 | F | eager | eager | none | file writes: creates configured dirs/files at load | conditional |
+| =host-environment= | 1 | F/L | eager | eager | none (battery on demand) | none | yes |
+| =system-defaults= | 1 | F/S | eager | eager | autorevert, server, bookmark, host-environment, user-constants | global setq, display-warning advice, display-buffer-alist entry, one key remap | conditional |
+| =keyboard-compat= | 1 | F/S | eager | eager | host-environment | adds emacs-startup-hook | yes |
+| =keybindings= | 1 | F/C | eager | eager | user-constants, which-key, free-keys | defines cj/custom-keymap + cj/jump-map, binds global keys, which-key labels | conditional |
+| =config-utilities= | 1 | C/O | eager | eager | cl-lib, cl-generic, eieio, find-lisp, profiler | defines cj/debug-config-keymap, binds C-c d | yes |
+
+Every Batch 1 module stays eager: each satisfies a spec eager-reason condition
+(shared helpers, path constants, core Emacs behavior, or the global keymap
+owner). Reasons are recorded in each module's load-graph header.
+
+* Hidden dependencies found
+
+Discoveries that belong to Phase 2 (make dependencies explicit). Recorded here,
+not fixed here.
+
+- =system-defaults= reads =env-bsd-p= (host-environment) and =user-home-dir=
+  (user-constants) at *load* time, but declares both only via
+  =eval-when-compile=. The compiled module therefore cannot load standalone —
+  it works at startup only because =init.el= requires host-environment and
+  user-constants earlier. Phase 2 fix: promote the two =eval-when-compile=
+  requires to plain runtime =require=. (Test
+  =test-system-defaults-functions.el= was updated to require host-environment
+  so the unit loads in isolation; the production fix is still pending.)
+
+* Pending classification
+
+The remaining 95 modules required by =init.el=, awaiting per-module inspection.
+Each batch reads these against their source and moves them into [[*Classified
+modules][Classified modules]] with a load-graph header. Suggested batch order
+follows the spec: text/editing command modules, then UI, then programming, then
+Org, then optional integrations.
+
+- [ ] ai-config
+- [ ] ai-vterm
+- [ ] auth-config
+- [ ] browser-config
+- [ ] calendar-sync
+- [ ] calibredb-epub-config
+- [ ] chrono-tools
+- [ ] coverage-core
+- [ ] coverage-elisp
+- [ ] custom-buffer-file
+- [ ] custom-case
+- [ ] custom-comments
+- [ ] custom-datetime
+- [ ] custom-line-paragraph
+- [ ] custom-misc
+- [ ] custom-ordering
+- [ ] custom-text-enclose
+- [ ] custom-whitespace
+- [ ] dashboard-config
+- [ ] dev-fkeys
+- [ ] diff-config
+- [ ] dirvish-config
+- [ ] dwim-shell-config
+- [ ] elfeed-config
+- [ ] erc-config
+- [ ] eshell-config
+- [ ] eww-config
+- [ ] external-open
+- [ ] flycheck-config
+- [ ] flyspell-and-abbrev
+- [ ] font-config
+- [ ] games-config
+- [ ] gloss-config
+- [ ] help-config
+- [ ] help-utils
+- [ ] httpd-config
+- [ ] hugo-config
+- [ ] jumper
+- [ ] keyboard-macros
+- [ ] latex-config
+- [ ] linear-config
+- [ ] local-repository
+- [ ] lorem-optimum
+- [ ] mail-config
+- [ ] markdown-config
+- [ ] media-utils
+- [ ] modeline-config
+- [ ] mousetrap-mode
+- [ ] music-config
+- [ ] nerd-icons-config
+- [ ] org-agenda-config
+- [ ] org-babel-config
+- [ ] org-capture-config
+- [ ] org-config
+- [ ] org-contacts-config
+- [ ] org-drill-config
+- [ ] org-export-config
+- [ ] org-noter-config
+- [ ] org-refile-config
+- [ ] org-reveal-config
+- [ ] org-roam-config
+- [ ] org-webclipper
+- [ ] pdf-config
+- [ ] popper-config
+- [ ] prog-c
+- [ ] prog-general
+- [ ] prog-go
+- [ ] prog-json
+- [ ] prog-lisp
+- [ ] prog-python
+- [ ] prog-shell
+- [ ] prog-training
+- [ ] prog-webdev
+- [ ] prog-yaml
+- [ ] quick-video-capture
+- [ ] reconcile-open-repos
+- [ ] restclient-config
+- [ ] selection-framework
+- [ ] slack-config
+- [ ] system-commands
+- [ ] system-utils
+- [ ] telega-config
+- [ ] test-runner
+- [ ] text-config
+- [ ] tramp-config
+- [ ] transcription-config
+- [ ] ui-config
+- [ ] ui-navigation
+- [ ] ui-theme
+- [ ] undead-buffers
+- [ ] vc-config
+- [ ] video-audio-recording
+- [ ] vterm-config
+- [ ] weather-config
+- [ ] wrap-up
diff --git a/modules/config-utilities.el b/modules/config-utilities.el
index 4ed086d1..b3eec5d3 100644
--- a/modules/config-utilities.el
+++ b/modules/config-utilities.el
@@ -2,6 +2,15 @@
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
+;;
+;; Layer: 1 (Foundation).
+;; Category: C/O.
+;; Load shape: eager.
+;; Eager reason: the C-c d debug keymap is kept available during config work.
+;; Top-level side effects: defines `cj/debug-config-keymap', binds it to C-c d.
+;; Runtime requires: cl-lib, cl-generic, eieio, find-lisp, profiler.
+;; Direct test load: yes (defines a keymap and helpers; batch-safe).
+;;
 ;; Development and debugging utilities for Emacs configuration maintenance.
 ;;
 ;;; Code:
diff --git a/modules/host-environment.el b/modules/host-environment.el
index e9887766..0afb39cb 100644
--- a/modules/host-environment.el
+++ b/modules/host-environment.el
@@ -2,6 +2,17 @@
 ;; author Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
+;;
+;; Layer: 1 (Foundation).
+;; Category: F/L.
+;; Load shape: eager.
+;; Eager reason: host predicates (laptop-p, battery presence) used by other
+;;   foundation/UI modules deciding behavior at startup.
+;; Top-level side effects: none.
+;; Runtime requires: none (battery loaded on demand; declared via
+;;   `declare-function').
+;; Direct test load: yes (pure predicates; batch-safe).
+;;
 ;; Convenience functions to report about the host environment
 ;;
 ;;; Code:
diff --git a/modules/keybindings.el b/modules/keybindings.el
index 462fde24..6e8adeac 100644
--- a/modules/keybindings.el
+++ b/modules/keybindings.el
@@ -3,6 +3,17 @@
 ;;
 ;;; Commentary:
 ;;
+;; Layer: 1 (Foundation).
+;; Category: F/C.
+;; Load shape: eager.
+;; Eager reason: owns `cj/custom-keymap' and the global C-; prefix that feature
+;;   modules register into; must exist before they load.
+;; Top-level side effects: defines `cj/custom-keymap'/`cj/jump-map', binds
+;;   global keys (C-;, C-z, and others), registers which-key labels after-load.
+;; Runtime requires: user-constants (currently eval-when-compile only),
+;;   which-key, free-keys.
+;; Direct test load: conditional (binds global keys; needs user-constants).
+;;
 ;; Global keybinding configuration and custom keymap framework.
 ;;
 ;; Main features include:
diff --git a/modules/keyboard-compat.el b/modules/keyboard-compat.el
index 22263e9c..914a343a 100644
--- a/modules/keyboard-compat.el
+++ b/modules/keyboard-compat.el
@@ -2,7 +2,17 @@
 ;; author: Craig Jennings <c@cjennings.net>
 
 ;;; Commentary:
-
+;;
+;; Layer: 1 (Foundation).
+;; Category: F/S.
+;; Load shape: eager.
+;; Eager reason: normalizes terminal/GUI key input so the first session's
+;;   keybindings resolve consistently.
+;; Top-level side effects: adds `cj/keyboard-compat-terminal-setup' to
+;;   `emacs-startup-hook'.
+;; Runtime requires: host-environment.
+;; Direct test load: yes (registers a startup hook; batch-safe).
+;;
 ;; This module fixes keyboard input differences between terminal and GUI Emacs.
 ;;
 ;; THE PROBLEM: Meta+Shift keybindings behave differently in terminal vs GUI
diff --git a/modules/system-defaults.el b/modules/system-defaults.el
index d0b9f835..33d93bbc 100644
--- a/modules/system-defaults.el
+++ b/modules/system-defaults.el
@@ -2,6 +2,21 @@
 ;; author: Craig Jennings <c@cjennings.net>
 ;;
 ;;; Commentary:
+;;
+;; Layer: 1 (Foundation).
+;; Category: F/S.
+;; Load shape: eager.
+;; Eager reason: establishes core Emacs behavior (encoding, clipboard,
+;;   scrolling, kill/quit defaults) the first interactive session relies on.
+;; Top-level side effects: mutates global defaults (many `setq'), advises
+;;   `display-warning', adds a `display-buffer-alist' entry, remaps one global
+;;   key.
+;; Runtime requires: autorevert, server, bookmark; host-environment
+;;   (`env-bsd-p') and user-constants (`user-home-dir') are read at load but
+;;   currently only required via eval-when-compile — Phase 2 to make explicit.
+;; Direct test load: conditional (host-environment and user-constants must load
+;;   first; the compiled module cannot resolve them standalone yet).
+;;
 ;; Loads during init to set sane defaults: UTF-8 everywhere, quiet prompts, synced clipboards,
 ;; and hands-off async shell buffers. Nothing to call—just launch Emacs and the environment is ready.
 ;; Native compilation is tuned for performance and its warnings get logged to comp-warnings.log.
diff --git a/modules/system-lib.el b/modules/system-lib.el
index 80175958..333c15ee 100644
--- a/modules/system-lib.el
+++ b/modules/system-lib.el
@@ -1,6 +1,16 @@
 ;;; system-lib.el --- System utility library functions -*- lexical-binding: t; -*-
 ;;
 ;;; Commentary:
+;;
+;; Layer: 1 (Foundation).
+;; Category: F/L.
+;; Load shape: eager.
+;; Eager reason: low-level helpers (executable lookup, process output, silent
+;;   logging) used by many eager modules during startup.
+;; Top-level side effects: none.
+;; Runtime requires: none (auth-source loaded on demand inside the helper).
+;; Direct test load: yes (pure helpers; batch-safe).
+;;
 ;; This module provides low-level system utility functions for checking
 ;; the availability of external programs and system capabilities.
 ;;
diff --git a/modules/user-constants.el b/modules/user-constants.el
index 2cc4a50c..293bc806 100644
--- a/modules/user-constants.el
+++ b/modules/user-constants.el
@@ -1,7 +1,17 @@
 ;;; user-constants.el --- User Constants -*- lexical-binding: t; coding: utf-8; -*-
 ;; author: Craig Jennings <c@cjennings.net>
 ;;; Commentary:
-
+;;
+;; Layer: 1 (Foundation).
+;; Category: F.
+;; Load shape: eager.
+;; Eager reason: defines the path constants referenced across the config and
+;;   creates the required directories/files before other modules load.
+;; Top-level side effects: file writes — creates configured directories and
+;;   stub files via `cj/initialize-user-directories-and-files' at load.
+;; Runtime requires: none.
+;; Direct test load: conditional (touches the filesystem on load).
+;;
 ;; This module defines important file and directory paths used throughout the
 ;; Emacs configuration, and ensures they exist during startup.
 ;;