diff --git a/docs/config.md b/docs/config.md
index dcef03396e..47be7f1ca2 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -95,7 +95,9 @@ Actions accept a single key or multiple keys:
 Some defaults intentionally include multiple variants for one logical shortcut
 because terminal modifier reporting can differ by platform/emulator. For
 example, `?` may arrive as plain `?` or `shift-?`, and control chords may
-arrive with or without `SHIFT`.
+arrive with or without `SHIFT`. Shifted letter bindings are also matched
+compatibly when terminals report uppercase letters without explicit `SHIFT`
+(for example, `shift-i` matching `I`).
 
 Aliases like `escape`, `pageup`, and `pgdn` are normalized.
 
diff --git a/docs/default-keymap.toml b/docs/default-keymap.toml
index c2453b2ec5..cf9a2b3a9f 100644
--- a/docs/default-keymap.toml
+++ b/docs/default-keymap.toml
@@ -73,6 +73,8 @@ yank = ["ctrl-y"]
 
 [tui.keymap.vim_normal]
 # Vim normal-mode actions for modal editing.
+# Shifted letter bindings also match uppercase event forms reported without
+# explicit SHIFT by some terminals.
 enter_insert = "i"
 append_after_cursor = "a"
 append_line_end = "shift-a"
diff --git a/docs/keymap-action-matrix.md b/docs/keymap-action-matrix.md
index dada5155e9..b399bf135e 100644
--- a/docs/keymap-action-matrix.md
+++ b/docs/keymap-action-matrix.md
@@ -24,6 +24,9 @@ For runtime behavior, safety invariants, and testing guidance, see
   - `composer.toggle_shortcuts`: `?` and `shift-?`
   - `approval.open_fullscreen`: `ctrl-a` and `ctrl-shift-a`
   - `onboarding.toggle_animation`: `ctrl-.` and `ctrl-shift-.`
+- Shifted letter bindings are also matched compatibly across terminal variants
+  when reported as uppercase letters without explicit `SHIFT` (for example
+  `shift-i` matching `I`, `shift-a` matching `A`, and `shift-o` matching `O`).
 - Keep these paired defaults unless/until key-event normalization is made
   platform-consistent at a lower layer.