docs: update documentation for popup, fix_typos, and configurable menu

- README: expand hexai-tmux-action bullet with popup mode, all built-in
  hotkeys, configurable menu, and overridable prompts
- configuration.md: update TUI section (split→popup, new popup flags,
  configurable menu example, prompt key-prefix table)
- usage.md: update Hexai Action section with full hotkey table and
  configurable menu mention

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

3 files changed, 62 insertions, 14 deletions

diff --git a/README.md b/README.md
index e71e93b..9da94e1 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,11 @@ It has got improved capabilities for Go code understanding (for example, create
   - File-based storage with JSONL format (git-friendly)
   - Built-in meta-prompts for interactive prompt creation and management
 * TUI AI code-action runner (`hexai-tmux-action`) with Bubble Tea
-  - Includes a "Custom prompt" action (hotkey `p`) that opens your editor (`$HEXAI_EDITOR` or `$EDITOR`) on a temporary Markdown file.
+  - Opens as a tmux popup when invoked from Helix `:pipe`
+  - Built-in actions: Rewrite (`r`), Simplify (`i`), Document (`c`), Go tests (`t`), Fix typos (`f`), Custom prompt (`p`), Skip (`s`)
+  - Fully configurable menu via `[[tmux_action.menu]]` — reorder, remove, rename, rebind hotkeys, embed custom actions directly in main menu
+  - All action prompts overridable via `[prompts.code_action]` in `config.toml`
+  - Custom prompt action opens your editor (`$HEXAI_EDITOR` or `$EDITOR`) on a temporary Markdown file
 * Tmux popup editor (`hexai-tmux-edit`) for composing longer AI agent prompts
   - Opens `$EDITOR` in a tmux popup, pre-filled with the current prompt text
   - Auto-detects Cursor, Amp, Aider (WIP), and other agents
diff --git a/docs/configuration.md b/docs/configuration.md
index 645d2ca..06cc9fc 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -87,17 +87,41 @@ This is mostly useful when Helix runs in a [tmux](https://tmux.github.io/) sessi
 - Helix integration (recommended): bind a key to pipe the current selection to `hexai-tmux-action` and replace it with the output.
   - Example: `C-a = ":pipe hexai-tmux-action"`
 - Default behavior:
-  - Inline TUI when run in a real terminal (TTY).
-  - When invoked via Helix `:pipe`, `hexai-tmux-action` opens a split pane to render the menu and returns the result on stdout for Helix to apply.
-  - If no TTY and no tmux are available, it falls back to echoing the input.
+  - When invoked via Helix `:pipe`, `hexai-tmux-action` opens a tmux popup to render the menu and returns the result on stdout for Helix to apply.
 - Flags:
   - `--infile`  Read input from the given file instead of stdin.
   - `--outfile` Write output to the given file instead of stdout (truncates/creates).
-  - `--tmux-target` tmux target pane/window (advanced).
-  - `--tmux-split v|h` split orientation (default: `v`).
-  - `--tmux-percent N` split size percentage (default: `33`).
+  - `--tmux-target` tmux target pane (advanced).
+  - `--tmux-popup-width` popup width (default: `60%`).
+  - `--tmux-popup-height` popup height (default: `50%`).
   - `--ui-child` internal; used by the parent process when spawning inside tmux.
 
+Configurable menu
+
+By default `hexai-tmux-action` shows all built-in actions. Define `[[tmux_action.menu]]` in `config.toml` to fully replace the menu — reorder, remove, rename, rebind hotkeys, or embed custom actions directly in the main menu instead of the submenu:
+
+```toml
+[[tmux_action.menu]]
+kind   = "rewrite"
+hotkey = "r"
+
+[[tmux_action.menu]]
+kind   = "fix_typos"
+hotkey = "f"
+title  = "Proofread"   # optional title override
+
+[[tmux_action.menu]]
+kind      = "custom"
+custom_id = "extract-function"   # references [[prompts.code_action.custom]]
+hotkey    = "e"
+
+[[tmux_action.menu]]
+kind   = "skip"
+hotkey = "s"
+```
+
+Valid built-in kinds: `rewrite`, `simplify`, `document`, `gotest`, `fix_typos`, `custom_prompt`, `skip`.
+
 Editor integration
 
 - Hexai tries to launch your preferred editor when needed (e.g., TUI “Custom prompt”, CLI with no args).
@@ -110,9 +134,18 @@ See the [tmux integration guide](docs/tmux.md) for details on configuring the st
 
 Code action prompts
 
-- All prompts can be customized under `[prompts.code_action]` in `config.toml`. In addition to `rewrite_*`, `diagnostics_*`, `document_*`, and `go_test_*`, the following templates control the \u201cSimplify and improve\u201d action:
-  - `simplify_system`
-  - `simplify_user` (uses `{{selection}}`)
+All prompts used by `hexai-tmux-action` (and the LSP code actions) can be overridden under `[prompts.code_action]` in `config.toml`. Each action has a `*_system` and a `*_user` template. Specifying a value completely replaces the built-in default; omitting it leaves the default in place.
+
+| Key prefix | Action |
+|---|---|
+| `rewrite_*` | Rewrite selection |
+| `diagnostics_*` | Resolve diagnostics |
+| `document_*` | Document code |
+| `go_test_*` | Generate Go unit test(s) |
+| `simplify_*` | Simplify and improve |
+| `fix_typos_*` | Fix typos and improve grammar and clarity |
+
+User templates support `{{selection}}` (always available) and `{{diagnostics}}` (diagnostics scope). See [config.toml.example](../config.toml.example) for the full defaults.
 
 Hexai Tmux Edit (popup editor)
 
diff --git a/docs/usage.md b/docs/usage.md
index 0429176..096b93a 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -215,12 +215,23 @@ ask done 0
 
 ## Hexai Action (TUI)
 
-`hexai-tmux-action` runs code actions over a selection or diagnostics+selection piped from stdin, or read from a file.
+`hexai-tmux-action` runs code actions over a selection or diagnostics+selection piped from stdin, or read from a file. When invoked from Helix `:pipe`, it opens a tmux popup to display the menu and returns the result on stdout.
+
+- Choose an action with arrow keys, `j/k`, `g/G`, Enter, or single-character hotkeys.
+- Default built-in actions and hotkeys:
+
+| Hotkey | Action |
+|---|---|
+| `r` | Rewrite selection |
+| `i` | Simplify and improve |
+| `c` | Document code |
+| `t` | Generate Go unit test(s) |
+| `f` | Fix typos and improve grammar and clarity |
+| `p` | Custom prompt (opens `$HEXAI_EDITOR` / `$EDITOR` on a temporary `.md` file) |
+| `s` | Skip |
 
-- Choose an action with arrow keys, `j/k`, `g/G`, Enter, or hotkeys `[s] [r] [c] [t]`.
-  - Includes: Rewrite selection, Simplify and improve, Document code, Generate Go unit test(s), Skip.
-  - “Custom prompt” (hotkey `[p]`) opens your editor (`$HEXAI_EDITOR` or `$EDITOR`) on a temporary `.md` file to write a free-form instruction.
 - Output is written to stdout by default, or to a file via `--outfile`.
+- The menu can be fully replaced via `[[tmux_action.menu]]` in `config.toml` — see the [configuration guide](configuration.md) for details.
 
 Input formats