feat: add debug infrastructure for config modules

This commit establishes a pattern for organizing debug code in separate
files that can be enabled/disabled via a central toggle.

## Changes

**1. Added debug toggle to user-constants.el**

New variable `cj/debug-modules` controls which modules load debug functions:
- Set to nil (default): No debug functions loaded
- Set to list of symbols: Load debug for specific modules
  Example: (setq cj/debug-modules '(org-agenda mail))
- Set to t: Load all debug modules
  Example: (setq cj/debug-modules t)

Placed early in user-constants.el so it's available before other modules load.

**2. Created org-agenda-config-debug.el**

New debug file contains:
- `cj/org-agenda-debug-dump-files` - Shows all org-agenda-files with status,
  file sizes, and modification times
- `cj/org-agenda-debug-rebuild-timing` - Measures rebuild performance and
  reports detailed timing statistics
- `cj/log-silently` - Helper function to write to *Messages* without echo

All functions use ;;;###autoload for easy invocation before explicit loading.

**3. Added conditional require to org-agenda-config.el**

Checks `cj/debug-modules` and conditionally loads org-agenda-config-debug.el:
```elisp
(when (or (eq cj/debug-modules t)
          (memq 'org-agenda cj/debug-modules))
  (require 'org-agenda-config-debug ...))
```

## Benefits

**Cleaner separation of concerns:**
- Production code stays in main config files
- Debug code isolated in *-debug.el files
- Easy to enable/disable debugging per module

**Reusable pattern:**
- Can be applied to any config module (mail, chime, etc.)
- Consistent naming: <module>-debug.el
- Consistent namespace: cj/<module>-debug-*

**Zero overhead when disabled:**
- Debug files not loaded unless explicitly enabled
- No performance impact on normal usage

## Usage

To enable org-agenda debug functions:
```elisp
;; In user-constants.el or early-init.el
(setq cj/debug-modules '(org-agenda))
```

Then restart Emacs and run:
- M-x cj/org-agenda-debug-dump-files
- M-x cj/org-agenda-debug-rebuild-timing

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

3 files changed, 92 insertions, 0 deletions

diff --git a/modules/org-agenda-config-debug.el b/modules/org-agenda-config-debug.el
new file mode 100644
index 00000000..aded3b6a
--- /dev/null
+++ b/modules/org-agenda-config-debug.el
@@ -0,0 +1,75 @@
+;;; org-agenda-config-debug.el --- Debug functions for org-agenda-config -*- lexical-binding: t; coding: utf-8; -*-
+;; author: Craig Jennings <c@cjennings.net>
+;;
+;;; Commentary:
+;;
+;; This file contains debug functions for org-agenda-config.el.
+;; It is only loaded when cj/debug-modules includes 'org-agenda or is t.
+;;
+;; Enable with: (setq cj/debug-modules '(org-agenda))
+;;          or: (setq cj/debug-modules t)
+;;
+;; Available debug functions:
+;; - cj/org-agenda-debug-dump-files - Show all org-agenda-files with status
+;; - cj/org-agenda-debug-rebuild-timing - Measure rebuild performance
+;;
+;;; Code:
+
+(require 'user-constants)
+
+;; ---------------------------- Helper Functions -------------------------------
+
+(defun cj/log-silently (format-string &rest args)
+  "Append formatted message to *Messages* buffer without echoing.
+FORMAT-STRING and ARGS are passed to `format'.
+This is a local copy of the pattern from system-utils.el."
+  (let ((inhibit-read-only t))
+    (with-current-buffer (get-buffer-create "*Messages*")
+      (goto-char (point-max))
+      (unless (bolp) (insert "\n"))
+      (insert (apply #'format format-string args))
+      (unless (bolp) (insert "\n")))))
+
+;; ---------------------------- Debug Functions --------------------------------
+
+;;;###autoload
+(defun cj/org-agenda-debug-dump-files ()
+  "Dump all org-agenda-files to *Messages* buffer with status.
+Shows which files exist, which are missing, and their sizes."
+  (interactive)
+  (cj/log-silently "=== Org Agenda Debug: Files ===")
+  (cj/log-silently "Total files: %d" (length org-agenda-files))
+  (cj/log-silently "")
+  (dolist (file org-agenda-files)
+    (if (file-exists-p file)
+        (let ((size (file-attribute-size (file-attributes file)))
+              (mtime (format-time-string "%Y-%m-%d %H:%M:%S"
+                                         (file-attribute-modification-time
+                                          (file-attributes file)))))
+          (cj/log-silently "✓ %s" file)
+          (cj/log-silently "  Size: %d bytes, Modified: %s" size mtime))
+      (cj/log-silently "✗ %s [MISSING]" file)))
+  (cj/log-silently "")
+  (cj/log-silently "=== End Org Agenda Debug ===")
+  (message "Org Agenda: Dumped %d files to *Messages* buffer" (length org-agenda-files)))
+
+;;;###autoload
+(defun cj/org-agenda-debug-rebuild-timing ()
+  "Measure and report timing for rebuilding org-agenda-files.
+Runs cj/build-org-agenda-list and reports detailed timing."
+  (interactive)
+  (cj/log-silently "=== Org Agenda Debug: Rebuild Timing ===")
+  (let ((start-time (current-time)))
+    (cj/build-org-agenda-list)
+    (let ((elapsed (float-time (time-subtract (current-time) start-time))))
+      (cj/log-silently "Rebuild completed in %.3f seconds" elapsed)
+      (cj/log-silently "Files found: %d" (length org-agenda-files))
+      (cj/log-silently "Average time per file: %.4f seconds"
+                       (if (> (length org-agenda-files) 0)
+                           (/ elapsed (float (length org-agenda-files)))
+                         0.0))))
+  (cj/log-silently "=== End Org Agenda Debug ===")
+  (message "Org Agenda: Timing info dumped to *Messages* buffer"))
+
+(provide 'org-agenda-config-debug)
+;;; org-agenda-config-debug.el ends here
diff --git a/modules/org-agenda-config.el b/modules/org-agenda-config.el
index d0042fda..5cb7ed00 100644
--- a/modules/org-agenda-config.el
+++ b/modules/org-agenda-config.el
@@ -32,6 +32,14 @@
 ;;; Code:
 (require 'user-constants)
 
+;; Load debug functions if enabled
+(when (or (eq cj/debug-modules t)
+          (memq 'org-agenda cj/debug-modules))
+  (require 'org-agenda-config-debug
+           (expand-file-name "org-agenda-config-debug.el"
+                             (file-name-directory load-file-name))
+           t))
+
 (use-package org-agenda
   :ensure nil ;; built-in
   :after (org)
diff --git a/modules/user-constants.el b/modules/user-constants.el
index 59129697..bcb34bcc 100644
--- a/modules/user-constants.el
+++ b/modules/user-constants.el
@@ -20,6 +20,15 @@
 ;;
 ;;; Code:
 
+;; -------------------------------- Debug Toggle -------------------------------
+
+(defvar cj/debug-modules nil
+  "List of modules with debug functions enabled.
+Possible values: org-agenda, mail, chime, etc.
+Set to t to enable all debug modules.
+Example: (setq cj/debug-modules '(org-agenda mail))
+         (setq cj/debug-modules t)  ; Enable all")
+
 ;; -------------------------------- Contact Info -------------------------------
 
 (defvar user-whole-name "Craig Jennings"