@@ -6,14 +6,16 @@ Decision record for application key bindings on `@opentui/core` 0.6.6. The engin
 
 **Adopt** `@opentui/keymap` for application commands. Do not move widget-local editing, the scroll lease, or the kill ring into it.
 
-`createDefaultOpenTuiKeymap(renderer)` installs the default parser, the event matcher, and the enabled and metadata fields. The shell registers one layer: `commands` (`name`, `run`) and `bindings` (`key`, `cmd`). Each `run` calls the existing handler in `src/tui/shell/keys.ts`. The help overlay reads those rows from the same catalog as the registration (`keymapShortcuts()` plus `promptLocalShortcuts()`).
+`createDefaultOpenTuiKeymap(renderer)` installs the default parser, the event matcher, and the enabled and metadata fields. The shell registers one layer. Each command `run` calls one existing function. There is no parallel key switch. Help lines are the keymap's registered `desc` values plus the widget-default rows.
+
+Textarea defaults are not registered again. `renderables/Textarea.d.ts` `TextareaAction` and the shipped `defaultTextareaKeyBindings` already cover cursor motion, word motion, Ctrl+D, Ctrl+K/U/W, and Alt+D. `PROMPT_KEY_BINDINGS` already maps Enter to submit and Ctrl+Enter / Ctrl+J / Shift+Enter to newline. The kill ring only diffs those deletes and yanks.
 
 ## What stays a command body
 
 Widget `keyBindings` cannot express policy that spans the shell:
 
-- **Scroll lease.** One surface holds the lease. The wheel must not move the transcript while a modal is open. Arrow keys never scroll the transcript.
-- **Kill ring.** Ctrl+K/U/W and Alt+D kill, Ctrl+Y yanks, Alt+Y yank-pops. Those stay Textarea-local in `prompt-kill-ring.ts`. The keymap does not bind them.
+- **Scroll lease.** One surface holds the lease. The wheel must not move the transcript while a modal is open. Arrow keys never scroll the transcript. `ScrollBoxRenderable.handleKeyPress` forwards arrows to `ScrollBarRenderable`, which scrolls on up/down. That focused arrow-scroll is not adopted.
+- **Kill ring.** Textarea delete actions discard the text (`delete-to-line-end`, `delete-to-line-start`, `delete-word-backward`, `delete-word-forward` in `Textarea.d.ts`). `prompt-kill-ring.ts` stays for the diff and for yank / yank-pop. The keymap does not bind those chords.
 - **Ctrl+C.** Pause, stop sub-agents, and quit stay `handleCtrlC`. The keymap command calls that handler; it does not reimplement the arming window. A decision gate still declines before the arming handler runs.
 
 Paste, overlay accept, and prompt newline chords stay where they were. Enter, Up, and Down stay in `keys.ts` because the same chord sends, steers, recalls history, or moves the caret. Ctrl+X is the held-item drop and is a keymap command.
 
@@ -17,7 +17,7 @@ import { describe, expect, test } from "bun:test";
 import { defined } from "../../testkit/defined.js";
 import { isPaused } from "./delivery-queue.js";
 import { PROMPT_KEY_BINDINGS } from "./prompt-input.js";
-import { SHELL_SHORTCUTS } from "./keybindings.js";
+import { shellShortcuts } from "./keybindings.js";
 import { createHarness, type Harness } from "./harness.js";
 import { mountRunnerHost } from "./runner/host.js";
 import { openCommandSurface } from "./command-surfaces.js";
@@ -733,7 +733,7 @@ function recordSubmits(
 }
 
 function rowsIn(group: Group): readonly { keys: string; probe: Probe }[] {
-  return SHELL_SHORTCUTS.flatMap((row) => {
+  return shellShortcuts().flatMap((row) => {
     const entry = PROBES[row.keys];
     return entry !== undefined && entry.group === group
       ? [{ keys: row.keys, probe: entry.probe }]
@@ -760,14 +760,14 @@ async function runGroup(group: Group): Promise<void> {
 
 describe("every catalog row is driven against real behavior", () => {
   test("no row is left without a probe", () => {
-    const missing = SHELL_SHORTCUTS.filter(
-      (row) => PROBES[row.keys] === undefined,
-    ).map((row) => row.keys);
+    const missing = shellShortcuts()
+      .filter((row) => PROBES[row.keys] === undefined)
+      .map((row) => row.keys);
     expect(missing).toEqual([]);
   });
 
   test("no probe describes a chord the catalog no longer lists", () => {
-    const listed = new Set(SHELL_SHORTCUTS.map((row) => row.keys));
+    const listed = new Set(shellShortcuts().map((row) => row.keys));
     expect(Object.keys(PROBES).filter((keys) => !listed.has(keys))).toEqual([]);
   });
 
 
@@ -1,109 +1,27 @@
 /**
- * OpenTUI shell keybinding catalog (pure data) — the help overlay's source
- * of truth. Rows with `command` are application chords registered on
- * `@opentui/keymap`. Rows without one stay prompt-local: textarea defaults,
- * the kill ring, or a chord whose meaning depends on context keys.ts still
- * owns. `keybindings.test.ts` drives every row through a live shell.
+ * Help rows. Application lines come from the live `@opentui/keymap`
+ * registration (`bindAppHelp`). Widget-default rows are the Textarea chords
+ * `defaultTextareaKeyBindings` / `PROMPT_KEY_BINDINGS` already perform, plus
+ * the kill-ring yank chords the textarea does not implement.
+ * There is no second copy of the application chord table here.
  */
 
 export interface ShellShortcut {
   readonly keys: string;
   readonly description: string;
-  /** `@opentui/keymap` command name. Absent for prompt-local chords. */
-  readonly command?: string;
-  /** Binding strings for `command`. Absent for prompt-local chords. */
-  readonly bindings?: readonly string[];
 }
 
-export const SHELL_SHORTCUTS: readonly ShellShortcut[] = [
+/**
+ * Prompt-local rows. Cursor, delete, word motion, and newline/submit are
+ * Textarea defaults (`renderables/Textarea.d.ts` `TextareaAction`). Yank is
+ * not a Textarea action; it stays listed because the kill ring records it.
+ */
+export const WIDGET_DEFAULT_SHORTCUTS: readonly ShellShortcut[] = [
   {
     keys: "Enter",
     description:
       "soft-steer at the next tool boundary while busy (held above the prompt); send straight through when idle",
   },
-  {
-    keys: "Alt+Enter",
-    description:
-      "queue a follow-up delivered only when the run goes idle; does nothing unless a run is busy",
-    command: "shell.queue",
-    bindings: ["alt+return"],
-  },
-  {
-    keys: "Up / Down / Enter / Ctrl+X",
-    description:
-      "on held items above the prompt: select, send now, drop (Esc backs out)",
-    // Up, Down, and Enter also move the caret, recall history, or send.
-    // Only Ctrl+X is unambiguous; the others stay in keys.ts.
-    command: "shell.held.drop",
-    bindings: ["ctrl+x"],
-  },
-  {
-    keys: "Ctrl+C",
-    description:
-      "pause a busy run and hold the queue, or clear the prompt and attachments when idle; Ctrl+C again to exit — with live sub-agents, a 2nd press stops them, a 3rd quits",
-    command: "shell.interrupt",
-    bindings: ["ctrl+c"],
-  },
-  {
-    keys: "Ctrl+G",
-    description:
-      "pop the most recently queued or steered message back into the prompt for editing",
-    command: "shell.cancel",
-    bindings: ["ctrl+g"],
-  },
-  {
-    keys: "Alt+C",
-    description:
-      "copy mode: pick a message, tool output, or diff; press again to close it",
-    command: "shell.copy",
-    bindings: ["alt+c"],
-  },
-  {
-    keys: "Alt+M",
-    description:
-      "toggle DEC mouse capture (on by default: wheel scroll, click-to-expand, drag-to-copy); off restores native terminal drag-select",
-    command: "shell.mouse",
-    bindings: ["alt+m"],
-  },
-  {
-    keys: "Alt+E",
-    description:
-      "expand or collapse every collapsible row (tool call, diff, skill, reasoning)",
-    command: "shell.expand",
-    bindings: ["alt+e"],
-  },
-  {
-    keys: "Alt+T",
-    description:
-      "show or hide the task list above the prompt (hidden by default)",
-    command: "shell.tasks",
-    bindings: ["alt+t"],
-  },
-  {
-    keys: "Alt+O",
-    description:
-      "observe a live subagent session; a system row says so when there is none",
-    command: "shell.observe",
-    bindings: ["alt+o"],
-  },
-  {
-    keys: "Tab",
-    description: "move focus between the prompt and the transcript",
-    command: "shell.focus",
-    bindings: ["tab"],
-  },
-  {
-    keys: "Shift+Tab",
-    description: "cycle reasoning effort for the current model",
-    command: "shell.effort",
-    bindings: ["shift+tab"],
-  },
-  {
-    keys: "Esc",
-    description: "close the open overlay, or leave subagent observe",
-    command: "shell.dismiss",
-    bindings: ["escape"],
-  },
   {
     keys: "Ctrl+B / Ctrl+F",
     description: "move the cursor back / forward one character",
@@ -156,36 +74,39 @@ export const SHELL_SHORTCUTS: readonly ShellShortcut[] = [
     description:
       "insert a newline instead of sending (Shift+Enter also works on terminals that report the modifier)",
   },
-] as const;
+];
 
-/** Application chords the keymap registers. */
-export function keymapShortcuts(): readonly ShellShortcut[] {
-  return SHELL_SHORTCUTS.filter((row) => row.command !== undefined);
+let appRows: readonly ShellShortcut[] = [];
+let readAppHelp: () => readonly string[] = () =>
+  appRows.map((row) => `${row.keys} — ${row.description}`);
+
+/** Called when the keymap module loads, and again from the live keymap. */
+export function setAppShortcutRows(rows: readonly ShellShortcut[]): void {
+  appRows = rows;
 }
 
-/**
- * Prompt-local rows: textarea defaults, the kill ring, paste, and chords
- * whose meaning depends on context the keymap does not own.
- */
-export function promptLocalShortcuts(): readonly ShellShortcut[] {
-  return SHELL_SHORTCUTS.filter((row) => row.command === undefined);
+export function bindAppHelp(read: () => readonly string[]): () => void {
+  const previous = readAppHelp;
+  readAppHelp = read;
+  return () => {
+    readAppHelp = previous;
+  };
+}
+
+/** Catalog the live tests drive. Application rows are whatever the keymap registered. */
+export function shellShortcuts(): readonly ShellShortcut[] {
+  return [...appRows, ...WIDGET_DEFAULT_SHORTCUTS];
 }
 
 function formatShortcut(row: ShellShortcut): string {
   return `${row.keys} — ${row.description}`;
 }
 
-/**
- * Help rows from the keymap catalog plus prompt-local rows, in catalog
- * order, so the overlay cannot drift from either list.
- */
+/** Keymap command lines, then widget-default rows. */
 export function helpItems(): readonly string[] {
-  const owned = new Set<string>([
-    ...keymapShortcuts().map((row) => row.keys),
-    ...promptLocalShortcuts().map((row) => row.keys),
-  ]);
   return [
-    ...SHELL_SHORTCUTS.filter((row) => owned.has(row.keys)).map(formatShortcut),
+    ...readAppHelp(),
+    ...WIDGET_DEFAULT_SHORTCUTS.map(formatShortcut),
     "Close help",
   ];
 }
@@ -632,14 +632,17 @@ export function createAppShell(
   if (onObserveRequestOpt) {
     setPaletteOnObserveRequest(shell, onObserveRequestOpt);
   }
-  const { onKey, onPaste, keymap } = createShellKeyHandlers(shell, {
+  const { onKey, onPaste } = createShellKeyHandlers(shell, {
     isDisposed: () => disposed,
   });
   if (wireKeys) {
-    renderer.keyInput.on("keypress", onKey);
+    detachKeymap = attachShellKeymap(renderer as CliRenderer, shell);
+    // onKey runs before the keymap listener (prepended above) so paste-burst
+    // bookkeeping and the kill-ring break happen, then the keymap may
+    // stopPropagation. Textarea defaults run last.
+    renderer.keyInput.prependListener("keypress", onKey);
     renderer.keyInput.on("paste", onPaste);
     prompt.onSubmit = onEnter;
-    detachKeymap = attachShellKeymap(renderer as CliRenderer, keymap);
   }
 
   applyLayout(shell, layout);
 
@@ -1,25 +1,27 @@
 /**
- * Application chords on `@opentui/keymap`. The package looks the chord up;
- * `ShellKeymapDispatch` in keys.ts is the command body. Prompt kill, newline,
- * and contextual Enter / Up / Down stay out of this layer.
+ * Registers `APP_CHORDS` on `@opentui/keymap`. Lookup belongs to the package.
+ * There is no second switch from key name to handler.
  */
 import type { CliRenderer, KeyEvent, Renderable } from "@opentui/core";
 import type { Keymap } from "@opentui/keymap";
 import { createDefaultOpenTuiKeymap } from "@opentui/keymap/opentui";
 
-import { keymapShortcuts } from "../keybindings.js";
-import type { ShellKeymapDispatch } from "./keys.js";
+import { bindAppHelp, setAppShortcutRows } from "../keybindings.js";
+import type { AppShell } from "./internals.js";
+import { APP_CHORDS, appHelpLines, shellIsLive } from "./shell-chords.js";
+
+setAppShortcutRows(
+  APP_CHORDS.map((row) => ({
+    keys: row.keys,
+    description: row.description,
+  })),
+);
+bindAppHelp(appHelpLines);
 
 type ShellKeymap = Keymap<Renderable, KeyEvent>;
 
 const keymaps = new WeakMap<CliRenderer, ShellKeymap>();
 
-/**
- * Terminals that cannot report Shift+Tab send `backtab`. It is not a named
- * key in the default parser, so a string binding would become a letter sequence.
- */
-const EFFORT_BACKTAB = { name: "backtab" } as const;
-
 function keymapFor(renderer: CliRenderer): ShellKeymap {
   const existing = keymaps.get(renderer);
   if (existing !== undefined) return existing;
@@ -28,69 +30,44 @@ function keymapFor(renderer: CliRenderer): ShellKeymap {
   return created;
 }
 
-function runCommand(
-  command: string,
-  dispatch: ShellKeymapDispatch,
-  key: KeyEvent,
-): boolean {
-  switch (command) {
-    case "shell.dismiss":
-      return dispatch.escape(key);
-    case "shell.interrupt":
-      return dispatch.ctrlC(key);
-    case "shell.copy":
-      return dispatch.copy(key);
-    case "shell.mouse":
-      return dispatch.mouse(key);
-    case "shell.expand":
-      return dispatch.expand(key);
-    case "shell.tasks":
-      return dispatch.tasks(key);
-    case "shell.observe":
-      return dispatch.observe(key);
-    case "shell.focus":
-      return dispatch.focus(key);
-    case "shell.effort":
-      return dispatch.effort(key);
-    case "shell.cancel":
-      return dispatch.cancel(key);
-    case "shell.queue":
-      return dispatch.queue(key);
-    case "shell.held.drop":
-      return dispatch.heldDrop(key);
-    default:
-      return false;
-  }
+function helpFromKeymap(keymap: ShellKeymap): readonly string[] {
+  return keymap.getCommands({ visibility: "registered" }).flatMap((command) => {
+    const desc = command.desc;
+    return typeof desc === "string" && desc.length > 0 ? [desc] : [];
+  });
 }
 
-/** Register the shell's application layer. Dispose unregisters that layer. */
+/** Register the shell's application layer. Dispose drops that layer. */
 export function attachShellKeymap(
   renderer: CliRenderer,
-  dispatch: ShellKeymapDispatch,
+  shell: AppShell,
 ): () => void {
   const keymap = keymapFor(renderer);
-  const rows = keymapShortcuts();
-  return keymap.registerLayer({
-    commands: rows.map((row) => ({
-      name: row.command ?? "",
-      desc: row.description,
-      run(ctx: { event: KeyEvent }): boolean {
-        const command = row.command;
-        if (command === undefined) return false;
-        return runCommand(command, dispatch, ctx.event);
+  const disposeLayer = keymap.registerLayer({
+    commands: APP_CHORDS.map((chord) => ({
+      name: chord.name,
+      desc: `${chord.keys} — ${chord.description}`,
+      enabled: () => shellIsLive(shell) && (chord.active?.(shell) ?? true),
+      run: (ctx: { event: KeyEvent }): boolean => {
+        // onKey already claimed this chord (slash Tab, overlay Enter, yank).
+        if (ctx.event.defaultPrevented) return false;
+        const handled = chord.run(shell);
+        if (handled && chord.preventDefault === false)
+          ctx.event.preventDefault();
+        return handled;
       },
     })),
-    bindings: [
-      ...rows.flatMap((row) =>
-        (row.bindings ?? []).map((key) => ({
-          key,
-          cmd: row.command ?? "",
-          // Esc must not stopPropagation. The engine pairs that with
-          // preventDefault, and the list modal's own listener still has to run.
-          ...(row.command === "shell.dismiss" ? { preventDefault: false } : {}),
-        })),
-      ),
-      { key: EFFORT_BACKTAB, cmd: "shell.effort" },
-    ],
+    bindings: APP_CHORDS.flatMap((chord) =>
+      chord.bindings.map((key) => ({
+        key,
+        cmd: chord.name,
+        ...(chord.preventDefault === false ? { preventDefault: false } : {}),
+      })),
+    ),
   });
+  const disposeHelp = bindAppHelp(() => helpFromKeymap(keymap));
+  return () => {
+    disposeHelp();
+    disposeLayer();
+  };
 }