feat:which-key: Add descriptive labels for custom keymaps

Enhance which-key integration by providing detailed descriptions for
new key bindings across multiple modules. This improves the
usability of custom keymaps by clarifying the purpose of each
keybinding, making it easier for users to navigate and understand
different menus and options available within the configuration.

This update ensures that all custom keymaps now display a
descriptive label in the which-key popup to explain their
functionality, aiding users in identifying keymap purposes promptly.

34 files changed, 322 insertions, 30 deletions

diff --git a/modules/ai-config.el b/modules/ai-config.el
index 004750b6..3b89faca 100644
--- a/modules/ai-config.el
+++ b/modules/ai-config.el
@@ -415,5 +415,22 @@ Works for any buffer, whether it's visiting a file or not."
   "x" #'cj/gptel-clear-buffer)        ;; clears the assistant buffer
 (keymap-set cj/custom-keymap "a" cj/ai-keymap)
 
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements
+    "C-; a" "AI assistant menu"
+    "C-; a B" "switch backend"
+    "C-; a M" "gptel menu"
+    "C-; a d" "delete conversation"
+    "C-; a ." "add buffer"
+    "C-; a f" "add file"
+    "C-; a l" "load conversation"
+    "C-; a m" "change model"
+    "C-; a p" "change prompt"
+    "C-; a &" "rewrite region"
+    "C-; a r" "clear context"
+    "C-; a s" "save conversation"
+    "C-; a t" "toggle window"
+    "C-; a x" "clear buffer"))
+
 (provide 'ai-config)
 ;;; ai-config.el ends here.
diff --git a/modules/config-utilities.el b/modules/config-utilities.el
index ea92f19a..32018371 100644
--- a/modules/config-utilities.el
+++ b/modules/config-utilities.el
@@ -17,12 +17,27 @@
 (keymap-global-set "C-c d" cj/debug-config-keymap)
 
 (with-eval-after-load 'which-key
-  (which-key-add-key-based-replacements "C-c d" "config debugging utils"))
+  (which-key-add-key-based-replacements
+    "C-c d" "config debugging utils"
+    "C-c d p" "profiler menu"
+    "C-c d p s" "start profiler"
+    "C-c d p h" "stop profiler"
+    "C-c d p r" "profiler report"
+    "C-c d t" "toggle debug-on-error"
+    "C-c d b" "benchmark method"
+    "C-c d c" "compilation menu"
+    "C-c d c h" "compile home"
+    "C-c d c d" "delete compiled"
+    "C-c d c ." "compile buffer"
+    "C-c d i" "info menu"
+    "C-c d i b" "info build"
+    "C-c d i p" "info packages"
+    "C-c d i f" "info features"
+    "C-c d r" "reload init"
+    "C-c d a" "reset auth cache"))
 
 ;;; --------------------------------- Profiling ---------------------------------
 
-(with-eval-after-load 'which-key
-  (which-key-add-key-based-replacements "C-c d p" "profiler menu."))
 (keymap-set cj/debug-config-keymap "p s" #'profiler-start)
 (keymap-set cj/debug-config-keymap "p h" #'profiler-stop)
 (keymap-set cj/debug-config-keymap "p r" #'profiler-report)
@@ -92,8 +107,6 @@ Recompile natively when supported, otherwise fall back to byte compilation."
       (message "Cancelled recompilation of %s" user-emacs-directory))))
 
 (keymap-set cj/debug-config-keymap "c h" 'cj/recompile-emacs-home)
-(with-eval-after-load 'which-key
-  (which-key-add-key-based-replacements "C-c d c" "config compilation options."))
 
 (defun cj/delete-emacs-home-compiled-files ()
   "Delete all compiled files recursively in \='user-emacs-directory\='."
@@ -214,8 +227,6 @@ Recompile natively when supported, otherwise fall back to byte compilation."
     (pop-to-buffer buf)))
 
 (keymap-set cj/debug-config-keymap "i b" 'cj/info-emacs-build)
-(with-eval-after-load 'which-key
-  (which-key-add-key-based-replacements "C-c d i" "info on build/features/packages."))
 
 (defvar cj--loaded-file-paths nil
   "All file paths that are loaded.")
diff --git a/modules/custom-case.el b/modules/custom-case.el
index 4fd9ac05..59250ddb 100644
--- a/modules/custom-case.el
+++ b/modules/custom-case.el
@@ -118,7 +118,11 @@ short prepositions, and all articles are considered minor words."
 (keymap-set cj/custom-keymap "c" cj/case-map)
 
 (with-eval-after-load 'which-key
-  (which-key-add-key-based-replacements "C-; c" "case change menu"))
+  (which-key-add-key-based-replacements
+    "C-; c" "case change menu"
+    "C-; c t" "title case"
+    "C-; c u" "upcase"
+    "C-; c l" "downcase"))
 
 (provide 'custom-case)
 ;;; custom-case.el ends here.
diff --git a/modules/custom-comments.el b/modules/custom-comments.el
index b4e51b2c..0d83d31b 100644
--- a/modules/custom-comments.el
+++ b/modules/custom-comments.el
@@ -619,7 +619,18 @@ Leverages cj/comment-inline-border."
 (keymap-set cj/custom-keymap "C" cj/comment-map)
 
 (with-eval-after-load 'which-key
-  (which-key-add-key-based-replacements "C-; C" "code comment menu"))
+  (which-key-add-key-based-replacements
+    "C-; C" "code comment menu"
+    "C-; C r" "reformat comment"
+    "C-; C d" "delete comments"
+    "C-; C c" "inline border"
+    "C-; C -" "hyphen divider"
+    "C-; C s" "simple divider"
+    "C-; C p" "padded divider"
+    "C-; C b" "box"
+    "C-; C h" "heavy box"
+    "C-; C u" "unicode box"
+    "C-; C n" "block banner"))
 
 (provide 'custom-comments)
 ;;; custom-comments.el ends here.
diff --git a/modules/custom-datetime.el b/modules/custom-datetime.el
index c195ebc2..5b06d81a 100644
--- a/modules/custom-datetime.el
+++ b/modules/custom-datetime.el
@@ -117,7 +117,14 @@ Use `readable-date-format' for formatting."
 (keymap-set cj/custom-keymap "d" cj/datetime-map)
 
 (with-eval-after-load 'which-key
-  (which-key-add-key-based-replacements "C-; d" "date/time insertion menu"))
+  (which-key-add-key-based-replacements
+    "C-; d" "date/time insertion menu"
+    "C-; d r" "readable date-time"
+    "C-; d s" "sortable date-time"
+    "C-; d t" "sortable time"
+    "C-; d T" "readable time"
+    "C-; d d" "sortable date"
+    "C-; d D" "readable date"))
 
 (provide 'custom-datetime)
 ;;; custom-datetime.el ends here.
diff --git a/modules/custom-file-buffer.el b/modules/custom-file-buffer.el
index e0224a32..08f974fd 100644
--- a/modules/custom-file-buffer.el
+++ b/modules/custom-file-buffer.el
@@ -240,7 +240,20 @@ Do not save the deleted text in the kill ring."
 (keymap-set cj/custom-keymap "b" cj/buffer-and-file-map)
 
 (with-eval-after-load 'which-key
-  (which-key-add-key-based-replacements "C-; b" "buffer and file menu"))
+  (which-key-add-key-based-replacements
+    "C-; b" "buffer and file menu"
+    "C-; b m" "move file"
+    "C-; b r" "rename file"
+    "C-; b p" "print to PS"
+    "C-; b d" "delete file"
+    "C-; b c" "copy buffer"
+    "C-; b n" "copy buffer name"
+    "C-; b t" "clear to top"
+    "C-; b b" "clear to bottom"
+    "C-; b x" "erase buffer"
+    "C-; b s" "save as"
+    "C-; b l" "copy file link"
+    "C-; b P" "copy file path"))
 
 
 (provide 'custom-file-buffer)
diff --git a/modules/custom-line-paragraph.el b/modules/custom-line-paragraph.el
index 7f0baef9..32f9aaa1 100644
--- a/modules/custom-line-paragraph.el
+++ b/modules/custom-line-paragraph.el
@@ -139,8 +139,15 @@ If the line is empty or contains only whitespace, abort with a message."
 (keymap-set cj/custom-keymap "l" cj/line-and-paragraph-map)
 
 (with-eval-after-load 'which-key
-  (which-key-add-key-based-replacements "C-; l" "line and paragraph menu")
-  (which-key-add-key-based-replacements "C-; l c" "duplicate and comment"))
+  (which-key-add-key-based-replacements
+    "C-; l" "line and paragraph menu"
+    "C-; l j" "join lines"
+    "C-; l J" "join paragraph"
+    "C-; l d" "duplicate"
+    "C-; l c" "duplicate and comment"
+    "C-; l R" "remove duplicates"
+    "C-; l r" "remove matching"
+    "C-; l u" "underscore line"))
 
 (provide 'custom-line-paragraph)
 ;;; custom-line-paragraph.el ends here.
diff --git a/modules/custom-misc.el b/modules/custom-misc.el
index 2af9c244..be1f26bb 100644
--- a/modules/custom-misc.el
+++ b/modules/custom-misc.el
@@ -152,5 +152,15 @@ to nil."
 (keymap-set cj/custom-keymap "SPC" #'cj/switch-to-previous-buffer)
 (keymap-set cj/custom-keymap "|" #'display-fill-column-indicator-mode)
 
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements
+    "C-; )" "jump to paren"
+    "C-; f" "format buffer"
+    "C-; W" "count words"
+    "C-; /" "fraction glyphs"
+    "C-; A" "align regexp"
+    "C-; SPC" "prev buffer"
+    "C-; |" "fill column"))
+
 (provide 'custom-misc)
 ;;; custom-misc.el ends here
diff --git a/modules/custom-ordering.el b/modules/custom-ordering.el
index abc9995a..7d906e75 100644
--- a/modules/custom-ordering.el
+++ b/modules/custom-ordering.el
@@ -253,7 +253,16 @@ Returns the transformed string without modifying the buffer."
 
 (keymap-set cj/custom-keymap "o" cj/ordering-map)
 (with-eval-after-load 'which-key
-  (which-key-add-key-based-replacements "C-; o" "ordering/sorting menu"))
+  (which-key-add-key-based-replacements
+    "C-; o" "ordering/sorting menu"
+    "C-; o l" "listify"
+    "C-; o j" "JSON array"
+    "C-; o p" "Python list"
+    "C-; o q" "toggle quotes"
+    "C-; o r" "reverse lines"
+    "C-; o n" "number lines"
+    "C-; o A" "alphabetize"
+    "C-; o L" "comma to lines"))
 
 (provide 'custom-ordering)
 ;;; custom-ordering.el ends here.
diff --git a/modules/custom-text-enclose.el b/modules/custom-text-enclose.el
index ccacdd2d..e93e6dea 100644
--- a/modules/custom-text-enclose.el
+++ b/modules/custom-text-enclose.el
@@ -264,11 +264,23 @@ Works on region if active, otherwise entire buffer."
   "a" #'cj/append-to-lines-in-region-or-buffer
   "p" #'cj/prepend-to-lines-in-region-or-buffer
   "i" #'cj/indent-lines-in-region-or-buffer
-  "d" #'cj/dedent-lines-in-region-or-buffer)
+  "d" #'cj/dedent-lines-in-region-or-buffer
+  "I" #'change-inner
+  "O" #'change-outer)
 
 (keymap-set cj/custom-keymap "s" cj/enclose-map)
 (with-eval-after-load 'which-key
-  (which-key-add-key-based-replacements "C-; s" "text enclose menu"))
+  (which-key-add-key-based-replacements
+    "C-; s" "text enclose menu"
+    "C-; s s" "surround text"
+    "C-; s w" "wrap text"
+    "C-; s u" "unwrap text"
+    "C-; s a" "append to lines"
+    "C-; s p" "prepend to lines"
+    "C-; s i" "indent lines"
+    "C-; s d" "dedent lines"
+    "C-; s I" "change inner"
+    "C-; s O" "change outer"))
 
 (provide 'custom-text-enclose)
 ;;; custom-text-enclose.el ends here.
diff --git a/modules/custom-whitespace.el b/modules/custom-whitespace.el
index df93459a..d5f8d80c 100644
--- a/modules/custom-whitespace.el
+++ b/modules/custom-whitespace.el
@@ -217,7 +217,15 @@ Operate on the active region designated by START and END."
 
 (keymap-set cj/custom-keymap "w" cj/whitespace-map)
 (with-eval-after-load 'which-key
-  (which-key-add-key-based-replacements "C-; w" "whitespace menu"))
+  (which-key-add-key-based-replacements
+    "C-; w" "whitespace menu"
+    "C-; w c" "collapse whitespace"
+    "C-; w l" "delete blank lines"
+    "C-; w 1" "single blank line"
+    "C-; w d" "delete all whitespace"
+    "C-; w -" "hyphenate whitespace"
+    "C-; w t" "untabify"
+    "C-; w T" "tabify"))
 
 (provide 'custom-whitespace)
 ;;; custom-whitespace.el ends here.
diff --git a/modules/diff-config.el b/modules/diff-config.el
index 382b2250..45c2a778 100644
--- a/modules/diff-config.el
+++ b/modules/diff-config.el
@@ -48,6 +48,14 @@
   (add-hook 'ediff-mode-hook               #'cj/ediff-hook)
   (add-hook 'ediff-after-quit-hook-internal #'winner-undo))
 
+;; which-key labels
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements
+    "C-c D" "ediff menu"
+    "C-c D f" "ediff files"
+    "C-c D b" "ediff buffers"
+    "C-c D r" "ediff revision"
+    "C-c D D" "ediff directories"))
 
 (provide 'diff-config)
 ;;; diff-config.el ends here
diff --git a/modules/erc-config.el b/modules/erc-config.el
index 1c189fa3..e7efb33f 100644
--- a/modules/erc-config.el
+++ b/modules/erc-config.el
@@ -183,7 +183,14 @@ Auto-adds # prefix if missing.  Offers completion from configured channels."
 
 (keymap-set cj/custom-keymap "E" cj/erc-keymap)
 (with-eval-after-load 'which-key
-  (which-key-add-key-based-replacements "C-; E" "ERC chat menu"))
+  (which-key-add-key-based-replacements
+    "C-; E" "ERC chat menu"
+    "C-; E C" "connect server"
+    "C-; E c" "join channel"
+    "C-; E b" "switch buffer"
+    "C-; E l" "list servers"
+    "C-; E q" "quit channel"
+    "C-; E Q" "quit server"))
 
 ;; Main ERC configuration
 (use-package erc
diff --git a/modules/external-open.el b/modules/external-open.el
index 41d842fb..8c4db810 100644
--- a/modules/external-open.el
+++ b/modules/external-open.el
@@ -111,6 +111,11 @@
 
 (keymap-global-set "C-c x o" #'cj/open-this-file-with)
 
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements
+    "C-c x" "external open menu"
+    "C-c x o" "open file with"))
+
 ;; -------------------- Open Files With Default File Handler -------------------
 
 (defun cj/find-file-auto (orig-fun &rest args)
diff --git a/modules/flycheck-config.el b/modules/flycheck-config.el
index d7f1ad39..ea19f08f 100644
--- a/modules/flycheck-config.el
+++ b/modules/flycheck-config.el
@@ -94,5 +94,8 @@ Runs flycheck-prose-on-demand if in an org-buffer."
     ;; trigger immediate check
     (flycheck-buffer)))
 
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements "C-; ?" "list errors"))
+
 (provide 'flycheck-config)
 ;;; flycheck-config.el ends here
diff --git a/modules/flyspell-and-abbrev.el b/modules/flyspell-and-abbrev.el
index 379fc7b2..d12a1794 100644
--- a/modules/flyspell-and-abbrev.el
+++ b/modules/flyspell-and-abbrev.el
@@ -239,5 +239,11 @@ Press C-' repeatedly to step through misspellings one at a time."
 ;;;###autoload (keymap-set global-map "C-c f" #'cj/flyspell-toggle)
 ;;;###autoload (keymap-set global-map "C-'" #'cj/flyspell-then-abbrev)
 
+;; which-key labels
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements
+    "C-c f" "flyspell toggle"
+    "C-'" "flyspell then abbrev"))
+
 (provide 'flyspell-and-abbrev)
 ;;; flyspell-and-abbrev.el ends here.
diff --git a/modules/font-config.el b/modules/font-config.el
index eea09da6..ddd4497f 100644
--- a/modules/font-config.el
+++ b/modules/font-config.el
@@ -284,5 +284,12 @@ If FRAME is nil, uses the selected frame."
 									   "<~" "<~~" "</" "</>" "~@" "~-" "~>" "~~" "~~>" "%%"))
   (global-ligature-mode t))
 
+;; which-key labels
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements
+    "C-c E" "emojify menu"
+    "C-c E i" "insert emoji"
+    "C-c E l" "list emojis"))
+
 (provide 'font-config)
 ;;; font-config.el ends here
diff --git a/modules/keybindings.el b/modules/keybindings.el
index 1f8867ef..1eff621c 100644
--- a/modules/keybindings.el
+++ b/modules/keybindings.el
@@ -68,12 +68,22 @@ Errors if VAR is unbound, not a non-empty string, or the file does not exist."
 	  ;; Bind it under the prefix map.
 	  (keymap-set cj/jump-map key fn))))
 
-;; Bind the prefix globally (user-reserved prefix).
-(keymap-global-set "C-c j" cj/jump-map)
+;; Bind the prefix to custom keymap
+(keymap-set cj/custom-keymap "j" cj/jump-map)
 
-;; nicer prefix label in which-key
+;; which-key labels
 (with-eval-after-load 'which-key
-  (which-key-add-key-based-replacements "C-c j" "Jump to common files."))
+  (which-key-add-key-based-replacements
+    "C-; j" "jump to files menu"
+    "C-; j r" "jump to reference"
+    "C-; j s" "jump to schedule"
+    "C-; j i" "jump to inbox"
+    "C-; j c" "jump to contacts"
+    "C-; j m" "jump to macros"
+    "C-; j n" "jump to reading notes"
+    "C-; j w" "jump to webclipped"
+    "C-; j g" "jump to gcal"
+    "C-; j I" "jump to emacs init"))
 
 ;; ---------------------------- Keybinding Discovery ---------------------------
 
diff --git a/modules/mail-config.el b/modules/mail-config.el
index c65e5342..402c2589 100644
--- a/modules/mail-config.el
+++ b/modules/mail-config.el
@@ -294,7 +294,10 @@ Prompts user for the action when executing."
 	  "d" #'org-msg-attach-delete)
 	(keymap-set cj/custom-keymap "e" cj/email-map)
 	(with-eval-after-load 'which-key
-	  (which-key-add-key-based-replacements "C-; e" "email menu"))
+	  (which-key-add-key-based-replacements
+        "C-; e" "email menu"
+        "C-; e a" "attach file"
+        "C-; e d" "delete attachment"))
   :bind
   ;; more intuitive keybinding for attachments
   (:map org-msg-edit-mode-map
@@ -342,5 +345,9 @@ Prompts user for the action when executing."
 (advice-add #'mu4e-compose-wide-reply
 			:after (lambda (&rest _) (org-msg-edit-mode)))
 
+;; which-key labels
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements "C-c m" "mu4e email"))
+
 (provide 'mail-config)
 ;;; mail-config.el ends here
diff --git a/modules/mousetrap-mode.el b/modules/mousetrap-mode.el
index fa9ee6dd..76c08c79 100644
--- a/modules/mousetrap-mode.el
+++ b/modules/mousetrap-mode.el
@@ -62,5 +62,8 @@ with or without C-, M-, S- modifiers."
 
 (keymap-global-set "C-c M" #'mouse-trap-mode)
 
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements "C-c M" "mouse trap mode"))
+
 (provide 'mousetrap-mode)
 ;;; mousetrap-mode.el ends here.
diff --git a/modules/music-config.el b/modules/music-config.el
index 90feb7eb..902fbd9c 100644
--- a/modules/music-config.el
+++ b/modules/music-config.el
@@ -366,7 +366,16 @@ Dirs added recursively."
 
 (keymap-set cj/custom-keymap "m" cj/music-map)
 (with-eval-after-load 'which-key
-  (which-key-add-key-based-replacements "C-; m" "music menu"))
+  (which-key-add-key-based-replacements
+    "C-; m" "music menu"
+    "C-; m m" "toggle playlist"
+    "C-; m M" "show playlist"
+    "C-; m a" "add music"
+    "C-; m r" "create radio"
+    "C-; m SPC" "pause"
+    "C-; m s" "stop"
+    "C-; m p" "playlist mode"
+    "C-; m x" "shuffle"))
 
 (use-package emms
   :defer t
diff --git a/modules/org-agenda-config.el b/modules/org-agenda-config.el
index c86ac6a3..7b436424 100644
--- a/modules/org-agenda-config.el
+++ b/modules/org-agenda-config.el
@@ -296,6 +296,9 @@ This allows a line to show in an agenda without being scheduled or a deadline."
   ;; Enable chime-mode automatically
   (chime-mode 1))
 
+;; which-key labels
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements "C-c A" "chime check"))
 
 (provide 'org-agenda-config)
 ;;; org-agenda-config.el ends here
diff --git a/modules/org-config.el b/modules/org-config.el
index 0249973f..753b1092 100644
--- a/modules/org-config.el
+++ b/modules/org-config.el
@@ -16,7 +16,7 @@
   :init
   (defvar-keymap cj/org-table-map
     :doc "org table operations.")
-  (keymap-global-set "C-c t" cj/org-table-map)
+  (keymap-set cj/custom-keymap "T" cj/org-table-map)
   :bind
   ("C-c c" . org-capture)
   ("C-c a" . org-agenda)
@@ -266,5 +266,20 @@ the current buffer's cache. Useful when encountering parsing errors like
           (message "Cleared org-element cache for current buffer"))
       (user-error "Current buffer is not in org-mode"))))
 
+;; which-key labels for org-table-map
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements
+    "C-; T" "org table menu"
+    "C-; T r" "table row"
+    "C-; T r i" "insert row"
+    "C-; T r d" "delete row"
+    "C-; T c" "table column"
+    "C-; T c i" "insert column"
+    "C-; T c d" "delete column"
+    ;; org global bindings
+    "C-c a" "org agenda"
+    "C-c c" "org capture"
+    "C-c l" "org store link"))
+
 (provide 'org-config)
 ;;; org-config.el ends here
diff --git a/modules/org-contacts-config.el b/modules/org-contacts-config.el
index df4e18f1..adb99db4 100644
--- a/modules/org-contacts-config.el
+++ b/modules/org-contacts-config.el
@@ -212,5 +212,14 @@ module provides more sophisticated completion."
 ;; Bind the org-contacts map to the C-c C prefix
 (keymap-global-set "C-c C" cj/org-contacts-map)
 
+;; which-key labels
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements
+    "C-c C" "contacts menu"
+    "C-c C f" "find contact"
+    "C-c C n" "new contact"
+    "C-c C e" "insert email"
+    "C-c C v" "view all contacts"))
+
 (provide 'org-contacts-config)
 ;;; org-contacts-config.el ends here
diff --git a/modules/org-drill-config.el b/modules/org-drill-config.el
index f18760c7..08047e3a 100644
--- a/modules/org-drill-config.el
+++ b/modules/org-drill-config.el
@@ -70,7 +70,13 @@
 
   (keymap-set cj/custom-keymap "D" cj/drill-map)
   (with-eval-after-load 'which-key
-	(which-key-add-key-based-replacements "C-; D" "org-drill menu")))
+	(which-key-add-key-based-replacements
+      "C-; D" "org-drill menu"
+      "C-; D s" "start drill"
+      "C-; D e" "edit drill file"
+      "C-; D c" "capture question"
+      "C-; D r" "refile to drill"
+      "C-; D R" "resume drill")))
 
 (provide 'org-drill-config)
 ;;; org-drill-config.el ends here.
diff --git a/modules/org-gcal-config.el b/modules/org-gcal-config.el
index ed0831b8..f3e1b7e0 100644
--- a/modules/org-gcal-config.el
+++ b/modules/org-gcal-config.el
@@ -10,6 +10,9 @@
 ;; - Automatic removal of cancelled events, but with TODOs added for visibility
 ;; - System timezone configuration via functions in host-environment
 ;; - No notifications on syncing
+;; - Events are managed by Org (changes in org file push back to Google Calendar)
+;;   This is controlled by org-gcal-managed-newly-fetched-mode and
+;;   org-gcal-managed-update-existing-mode set to "org"
 ;; - Initial automatic sync post Emacs startup. No auto resync'ing.
 ;;   (my calendar doesn't change hourly and I want fewer distractions and slowdowns).
 ;;   if you need it: https://github.com/kidd/org-gcal.el?tab=readme-ov-file#sync-automatically-at-regular-times
@@ -42,6 +45,22 @@ Useful when a sync fails and leaves the lock in place, preventing future syncs."
   (setq org-gcal--sync-lock nil)
   (message "org-gcal sync lock cleared"))
 
+(defun cj/org-gcal-convert-all-to-org-managed ()
+  "Convert all org-gcal events in current buffer to Org-managed.
+
+Changes all events with org-gcal-managed property from 'gcal' to 'org',
+enabling bidirectional sync so changes push back to Google Calendar."
+  (interactive)
+  (let ((count 0))
+    (save-excursion
+      (goto-char (point-min))
+      (while (re-search-forward "^:org-gcal-managed: gcal$" nil t)
+        (replace-match ":org-gcal-managed: org")
+        (setq count (1+ count))))
+    (when (> count 0)
+      (save-buffer))
+    (message "Converted %d event(s) to Org-managed" count)))
+
 (use-package org-gcal
   :defer t ;; unless idle timer is set below
   :bind (("C-; g" . org-gcal-sync)
@@ -71,11 +90,20 @@ Useful when a sync fails and leaves the lock in place, preventing future syncs."
   (setq org-gcal-remove-api-cancelled-events t)        ;; auto-remove cancelled events
   (setq  org-gcal-update-cancelled-events-with-todo t) ;; todo cancelled events for visibility
 
+  ;; Enable bidirectional sync - treat events as Org-managed so changes push back
+  (setq org-gcal-managed-newly-fetched-mode "org")     ;; New events from GCal are Org-managed
+  (setq org-gcal-managed-update-existing-mode "org")   ;; Existing events become Org-managed
+
   :config
   ;; Enable plstore passphrase caching after org-gcal loads
   (require 'plstore)
   (setq plstore-cache-passphrase-for-symmetric-encryption t)
 
+  ;; Enable debugging for HTTP requests
+  (require 'request)
+  (setq request-log-level 'debug)
+  (setq request-message-level 'debug)
+
   ;; set org-gcal timezone based on system timezone
   (setq org-gcal-local-timezone (cj/detect-system-timezone))
 
@@ -90,5 +118,11 @@ Useful when a sync fails and leaves the lock in place, preventing future syncs."
 ;;	   (org-gcal-sync)
 ;;	 (error (message "org-gcal: Initial sync failed: %s" err)))))
 
+;; which-key labels
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements
+    "C-; g" "gcal sync"
+    "C-; G" "clear sync lock"))
+
 (provide 'org-gcal-config)
 ;;; org-gcal-config.el ends here
diff --git a/modules/org-roam-config.el b/modules/org-roam-config.el
index 07098743..f78b68da 100644
--- a/modules/org-roam-config.el
+++ b/modules/org-roam-config.el
@@ -85,7 +85,9 @@
   (add-to-list 'org-after-todo-state-change-hook
                (lambda ()
                  (when (and (member org-state org-done-keywords)
-                            (not (member org-last-state org-done-keywords)))
+                            (not (member org-last-state org-done-keywords))
+                            ;; Don't run for gcal.org - it's managed by org-gcal
+                            (not (string= (buffer-file-name) (expand-file-name gcal-file))))
                    (cj/org-roam-copy-todo-to-today)))))
 
 ;; ------------------------- Org Roam Insert Immediate -------------------------
@@ -294,5 +296,19 @@ title."
 	;; Message to user
 	(message "'%s' added as an org-roam node." title)))
 
+;; which-key labels
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements
+    "C-c n" "org-roam menu"
+    "C-c n l" "roam buffer toggle"
+    "C-c n f" "roam find node"
+    "C-c n p" "roam find project"
+    "C-c n r" "roam find recipe"
+    "C-c n t" "roam find topic"
+    "C-c n i" "roam insert node"
+    "C-c n w" "roam find webclip"
+    "C-c n I" "roam insert immediate"
+    "C-c n d" "roam dailies menu"))
+
 (provide 'org-roam-config)
 ;;; org-roam-config.el ends here.
diff --git a/modules/prog-general.el b/modules/prog-general.el
index f6ebfe09..669922ef 100644
--- a/modules/prog-general.el
+++ b/modules/prog-general.el
@@ -400,6 +400,15 @@ If no such file exists there, display a message."
 				   "1.5 sec" nil 'delete-windows-on
 				   (get-buffer-create "*compilation*"))))))
 
+;; which-key labels
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements
+    "C-c s" "snippets menu"
+    "C-c s n" "new snippet"
+    "C-c s e" "edit snippet"
+    "C-c s i" "insert snippet"
+    "C-c p" "projectile menu"
+    "C-c C-s" "symbol overlay"))
 
 (provide 'prog-general)
 ;;; prog-general.el ends here
diff --git a/modules/selection-framework.el b/modules/selection-framework.el
index 66ca1cbd..0bc71f64 100644
--- a/modules/selection-framework.el
+++ b/modules/selection-framework.el
@@ -259,5 +259,9 @@
   :config
   (company-prescient-mode))
 
+;; which-key labels
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements "C-c h" "consult history"))
+
 (provide 'selection-framework)
 ;;; selection-framework.el ends here
diff --git a/modules/system-utils.el b/modules/system-utils.el
index 6e51c32c..eef20718 100644
--- a/modules/system-utils.el
+++ b/modules/system-utils.el
@@ -43,6 +43,9 @@
      (message "Error occurred during evaluation: %s" (error-message-string err)))))
 (keymap-global-set "C-c b" #'cj/eval-buffer-with-confirmation-or-error-message)
 
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements "C-c b" "eval buffer"))
+
 ;;; ---------------------------- Edit A File With Sudo ----------------------------
 
 (use-package sudo-edit
diff --git a/modules/text-config.el b/modules/text-config.el
index 730e36a3..29db9e0b 100644
--- a/modules/text-config.el
+++ b/modules/text-config.el
@@ -46,8 +46,7 @@
 ;; change inner and outer, just like in vim.
 
 (use-package change-inner
-  :bind (("C-c i" . change-inner)
-         ("C-c o" . change-outer)))
+  :commands (change-inner change-outer))
 
 ;; ------------------------------ Delete Selection -----------------------------
 ;; delete the region on character insertion
diff --git a/modules/vc-config.el b/modules/vc-config.el
index 3b116cc1..a936e890 100644
--- a/modules/vc-config.el
+++ b/modules/vc-config.el
@@ -131,7 +131,16 @@
 
 (keymap-set cj/custom-keymap "v" cj/vc-map)
 (with-eval-after-load 'which-key
-  (which-key-add-key-based-replacements "C-; v" "version control menu"))
+  (which-key-add-key-based-replacements
+    "C-; v" "version control menu"
+    "C-; v d" "goto diff hunks"
+    "C-; v c" "create issue"
+    "C-; v f" "forge pull"
+    "C-; v i" "list issues"
+    "C-; v n" "next hunk"
+    "C-; v p" "previous hunk"
+    "C-; v r" "list pull requests"
+    "C-; v t" "git timemachine"))
 
 (provide 'vc-config)
 ;;; vc-config.el ends here.
diff --git a/modules/video-audio-recording.el b/modules/video-audio-recording.el
index fa4c2926..73f782f6 100644
--- a/modules/video-audio-recording.el
+++ b/modules/video-audio-recording.el
@@ -227,5 +227,14 @@ Otherwise use the default location in `audio-recordings-dir'."
 
 (keymap-set cj/custom-keymap "r" cj/record-map)
 
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements
+    "C-; r" "recording menu"
+    "C-; r v" "start video"
+    "C-; r V" "stop video"
+    "C-; r a" "start audio"
+    "C-; r A" "stop audio"
+    "C-; r l" "adjust levels"))
+
 (provide 'video-audio-recording)
 ;;; video-audio-recording.el ends here.
diff --git a/modules/wip.el b/modules/wip.el
index 80b3295d..db94cdb1 100644
--- a/modules/wip.el
+++ b/modules/wip.el
@@ -127,6 +127,8 @@ If CONFIRM is non-nil, mark VAR to always require confirmation."
 
 (keymap-set cj/custom-keymap "!" #'cj/system-command-menu)
 
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements "C-; !" "system commands"))
 
 ;; --------------------------- Org Upcoming Modeline ---------------------------