diff --git a/docs/terminal-shortcuts.md b/docs/terminal-shortcuts.md
index c8fd6a93..ce632772 100644
--- a/docs/terminal-shortcuts.md
+++ b/docs/terminal-shortcuts.md
@@ -1,6 +1,6 @@
 # Terminal Shortcuts
 
-This document is **generated from** `src/renderer/src/components/terminal-pane/terminal-shortcut-table.ts` and is enforced by `terminal-shortcut-table.docs.test.ts`. If the table changes, this file must be regenerated (run the parity test and paste in the expected output).
+This document is **generated from** `src/renderer/src/components/terminal-pane/terminal-shortcut-table.ts` and is enforced by `terminal-shortcut-table.docs.test.ts`. If the table changes, this file must be regenerated: run the parity test in `terminal-shortcut-table.docs.test.ts`, then replace the rows inside the `BEGIN:MAC`/`END:MAC` and `BEGIN:NONMAC`/`END:NONMAC` HTML-comment markers below with the `expected` value from the assertion diff.
 
 Notation:
 - `Mod` = Cmd on macOS, Ctrl on Windows/Linux
@@ -58,6 +58,8 @@ Shortcuts that depend on the Mac "Option as Alt" setting (Option+letter composin
 
 ## Reserved shell chords (never intercepted)
 
+(This section is editorial and is not enforced by the parity test — it describes chords intentionally left out of the table.)
+
 These fall through to xterm.js and the shell regardless of platform:
 
 - `Ctrl+C` — SIGINT
diff --git a/src/renderer/src/components/terminal-pane/terminal-shortcut-table.docs.test.ts b/src/renderer/src/components/terminal-pane/terminal-shortcut-table.docs.test.ts
index 77e68d85..e71f4753 100644
--- a/src/renderer/src/components/terminal-pane/terminal-shortcut-table.docs.test.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-shortcut-table.docs.test.ts
@@ -53,7 +53,9 @@ function formatKeyLabel(entry: ShortcutEntry): string {
     }
     return first
   }
-  return '?'
+  // Surface malformed entries at the parity test rather than corrupting the
+  // generated doc with a '?' placeholder that would silently pass review.
+  throw new Error(`ShortcutEntry '${entry.id}' has no key, keyLower, or code`)
 }
 
 function formatChord(entry: ShortcutEntry): string {
@@ -126,4 +128,23 @@ describe('terminal-shortcuts.md parity with TERMINAL_SHORTCUTS', () => {
     const actual = extractSection(doc, 'NONMAC')
     expect(actual).toEqual(expected)
   })
+
+  it('every entry applies to at least one platform', () => {
+    // An entry with mac=false && nonMac=false is dead code — it can never fire.
+    for (const e of TERMINAL_SHORTCUTS) {
+      expect(e.mac || e.nonMac, `ShortcutEntry '${e.id}' fires on no platform`).toBe(true)
+    }
+  })
+
+  it('formatKeyLabel throws on an entry with no key, keyLower, or code', () => {
+    const malformed: ShortcutEntry = {
+      id: 'malformed-test',
+      description: 'test',
+      mac: true,
+      nonMac: true,
+      match: { modifiers: [] },
+      action: { type: 'toggleSearch' }
+    }
+    expect(() => formatKeyLabel(malformed)).toThrow(/malformed-test/)
+  })
 })
diff --git a/tests/e2e/terminal-shortcuts.spec.ts b/tests/e2e/terminal-shortcuts.spec.ts
index 3fb79625..251c64df 100644
--- a/tests/e2e/terminal-shortcuts.spec.ts
+++ b/tests/e2e/terminal-shortcuts.spec.ts
@@ -189,8 +189,11 @@ test.describe('Terminal Shortcuts', () => {
     // Why: must run before Cmd+K clears the buffer; selectAll + Mod+Shift+C
     // must route through the shortcut policy and write the selection through
     // the clipboard:writeText IPC (which the spy captured).
-    await selectAllActiveTerminal(orcaPage)
+    // Why: focus must happen BEFORE selectAll — focusing the xterm helper
+    // textarea after a programmatic selection can collapse the selection in
+    // some xterm configurations, so we focus first and then select.
     await focusActiveTerminal(orcaPage)
+    await selectAllActiveTerminal(orcaPage)
     await orcaPage.keyboard.press(`${mod}+Shift+c`)
     await expect
       .poll(async () => (await getClipboardWrites(electronApp)).some((t) => t.includes(marker)), {