fix(editor): improve external editor (Ctrl-X) UX

docs/reference/configuration.md

@@ -95,8 +95,37 @@ their corresponding top-level category object in your `settings.json` file.
 #### `general`
 
 - **`general.preferredEditor`** (string):
-  - **Description:** The preferred editor to open files in.
+  - **Description:** The preferred editor to open files in when using the
+    external editor feature (Ctrl-X).
   - **Default:** `undefined`
+  - **Accepted values:**
+
+    | Identifier    | Editor                                         | Platform |
+    | ------------- | ---------------------------------------------- | -------- |
+    | `vscode`      | Visual Studio Code                             | All      |
+    | `vscodium`    | VSCodium                                       | All      |
+    | `cursor`      | Cursor                                         | All      |
+    | `windsurf`    | Windsurf                                       | All      |
+    | `zed`         | Zed                                            | All      |
+    | `antigravity` | Antigravity                                    | All      |
+    | `sublimetext` | Sublime Text                                   | All      |
+    | `lapce`       | Lapce                                          | All      |
+    | `nova`        | Nova                                           | macOS    |
+    | `bbedit`      | BBEdit                                         | macOS    |
+    | `vim`         | Vim                                            | All      |
+    | `neovim`      | Neovim                                         | All      |
+    | `emacs`       | Emacs                                          | All      |
+    | `emacsclient` | Emacs Client (requires a running Emacs daemon) | All      |
+    | `hx`          | Helix                                          | All      |
+    | `micro`       | Micro                                          | All      |
+
+  - **`$VISUAL` / `$EDITOR` fallback:** If `preferredEditor` is not set, the CLI
+    falls back to the `$VISUAL` environment variable, then `$EDITOR`, and
+    finally `vi` (Unix) or `notepad` (Windows). This lets you use any editor not
+    in the list above — including editors with custom arguments like
+    `emacsclient -nw` — by setting the environment variable directly.
+  - **Note:** Setting an unrecognized identifier produces a clear error at
+    runtime. To configure your editor interactively, use the `/editor` command.
 
 - **`general.vimMode`** (boolean):
   - **Description:** Enable Vim keybindings

packages/cli/src/ui/components/EditorSettingsDialog.tsx

@@ -24,7 +24,6 @@ import {
   EDITOR_DISPLAY_NAMES,
 } from '@google/gemini-cli-core';
 import { useKeypress } from '../hooks/useKeypress.js';
-import { coreEvents } from '@google/gemini-cli-core';
 
 interface EditorDialogProps {
   onSelect: (
@@ -72,10 +71,6 @@ export function EditorSettingsDialog({
       )
     : 0;
   if (editorIndex === -1) {
-    coreEvents.emitFeedback(
-      'error',
-      `Editor is not supported: ${currentPreference}`,
-    );
     editorIndex = 0;
   }
 
@@ -161,6 +156,7 @@ export function EditorSettingsDialog({
           onSelect={handleEditorSelect}
           isFocused={focusedSection === 'editor'}
           key={selectedScope}
+          maxItemsToShow={editorItems.length}
         />
 
         <Box marginTop={1} flexDirection="column">

packages/cli/src/ui/components/shared/text-buffer.ts

@@ -13,6 +13,7 @@ import { LRUCache } from 'mnemonist';
 import {
   coreEvents,
   debugLogger,
+  getErrorMessage,
   unescapePath,
   type EditorType,
 } from '@google/gemini-cli-core';
@@ -3117,11 +3118,7 @@ export function useTextBuffer({
 
       dispatch({ type: 'set_text', payload: newText, pushToUndo: false });
     } catch (err) {
-      coreEvents.emitFeedback(
-        'error',
-        '[useTextBuffer] external editor error',
-        err,
-      );
+      coreEvents.emitFeedback('error', getErrorMessage(err), err);
     } finally {
       try {
         fs.unlinkSync(filePath);