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 004750b6f..3b89facad 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 ea92f19ab..32018371d 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 4fd9ac059..59250ddb0 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 b4e51b2cf..0d83d31b1 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 c195ebc22..5b06d81a9 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 e0224a327..08f974fde 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 7f0baef94..32f9aaa1d 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 2af9c2444..be1f26bb7 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 abc9995ad..7d906e75a 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 ccacdd2dc..e93e6deab 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 df93459a5..d5f8d80cd 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 382b22508..45c2a778c 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 1c189fa37..e7efb33f0 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 41d842fbc..8c4db8104 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 d7f1ad398..ea19f08fc 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 379fc7b2c..d12a17941 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 eea09da6f..ddd4497ff 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 1f8867efd..1eff621cf 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 c65e5342d..402c2589b 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 fa9ee6dd1..76c08c792 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 90feb7eba..902fbd9c4 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 c86ac6a34..7b4364243 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 0249973f1..753b1092e 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 df4e18f1b..adb99db42 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 f18760c75..08047e3a1 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 ed0831b8b..f3e1b7e04 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 070987438..f78b68da3 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 f6ebfe095..669922ef4 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 66ca1cbd1..0bc71f64e 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 6e51c32cf..eef207185 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 730e36a30..29db9e0b4 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 3b116cc1b..a936e890d 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 fa4c29267..73f782f60 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 80b3295d2..db94cdb10 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 ---------------------------