From 7c0e339be45adeaae8164bade2a0f99396d131b6 Mon Sep 17 00:00:00 2001
From: l0ng-ai <24760907+l0ng-ai@users.noreply.github.com>
Date: Tue, 15 Sep 2026 23:01:51 +0800
Subject: [PATCH] docs(keymap): terminal shortcuts keep their chord; upgrading
 configs (#868)

A chord added in config wins a tie only against another app-wide action.
Copy, paste, find, clear scrollback and insert newline are bound in the
Terminal context, which is deeper, so they keep their chord while a
terminal is focused. Also tells people upgrading that a shortcut recorded
in Settings up to 26.9.2 was saved as a string. It now adds instead of
replacing, and a list brings back the old meaning.

Claude-Session: https://claude.ai/code/session_01JRqYZ9E153WpSHGS2AW3BM
---
 docs/customization/keybindings.mdx | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/docs/customization/keybindings.mdx b/docs/customization/keybindings.mdx
index 63ad7344..cc699d7c 100644
--- a/docs/customization/keybindings.mdx
+++ b/docs/customization/keybindings.mdx
@@ -56,8 +56,14 @@ An action's value takes one of two shapes:
 | `""` or `[]` | **Unbind** the action |
 
 Recording a shortcut on the Settings page replaces, so it writes the list
-shape. A shortcut you add that another action already uses wins: it is the one
-that runs.
+shape. A shortcut you add that another action already uses is the one that
+runs. The exception is the terminal's own shortcuts: copy, paste, find, clear
+scrollback and insert newline keep theirs while a terminal has focus.
+
+Up to 26.9.2 a string replaced the default, and the Settings page wrote
+strings. So a shortcut you recorded in those versions now works *beside* the
+default it was meant to replace. To drop the default again, record the shortcut again
+or wrap it in a list: `"NewTab": ["cmd-shift-n"]`.
 
 The syntax is modifiers joined by `-`, then the key. Chords are separated by a
 space.