docs: cover prefix mode properly (#3383)

<!-- Thank you for making a PR! Bug fixes are always welcome, but if
you're adding a new feature or changing an existing one, we'd really
appreciate if you open an issue, post on the forum, or drop in on
Discord -->

## Checks
- [ ] I am happy for maintainers to push small adjustments to this PR,
to speed up the review cycle
- [ ] I have checked that there are no existing pull requests for the
same thing

3 files changed, 46 insertions, 1 deletions

diff --git a/docs/docs/configuration/advanced-key-binding.md b/docs/docs/configuration/advanced-key-binding.md
index 21cf35c6..c2edc6c3 100644
--- a/docs/docs/configuration/advanced-key-binding.md
+++ b/docs/docs/configuration/advanced-key-binding.md
@@ -389,6 +389,43 @@ This is equivalent to setting `enter_accept = false`, but expressed directly as
 "delete" = "delete"
 ```
 
+### Custom prefix bindings
+
+Prefix mode is a two-step shortcut: press the prefix key (++ctrl+a++ by default), then a second key. This is useful for actions you don't need on a single key. The default prefix bindings are:
+
+| Key | Action |
+|-----|--------|
+| `d` | Delete the selected entry |
+| `D` | Delete all entries matching the selected command |
+| `a` | Move cursor to start of line |
+| `c` | Clear context (if in a switched context), otherwise switch context |
+
+You can customize these with `[keymap.prefix]`:
+
+```toml
+[keymap.prefix]
+# Add a binding to copy the selected entry
+"y" = "copy"
+
+# Make 'x' delete instead of 'd'
+"x" = "delete"
+"d" = "noop"
+```
+
+To change which key enters prefix mode, set `prefix` under `[keys]`:
+
+```toml
+[keys]
+prefix = "x"  # ctrl-x instead of ctrl-a
+```
+
+Or bind `enter-prefix-mode` directly in your keymap:
+
+```toml
+[keymap.emacs]
+"ctrl-x" = "enter-prefix-mode"
+```
+
 ## Relationship with `[keys]`
 
 The `[keymap]` section is a more powerful replacement for the `[keys]` section. The two are **mutually exclusive**:
diff --git a/docs/docs/configuration/config.md b/docs/docs/configuration/config.md
index 9ef001d0..f453f903 100644
--- a/docs/docs/configuration/config.md
+++ b/docs/docs/configuration/config.md
@@ -700,7 +700,9 @@ Atuin version: > 18.3
 
 Default: `a`
 
-Which key to use as the prefix
+Which key to use as the prefix. Prefix mode is a two-step shortcut system: you press ++ctrl++ and the prefix key to enter prefix mode, then press a second key to trigger an action. For example, with the default prefix `a`, pressing ++ctrl+a++ then ++d++ deletes the selected entry.
+
+See the [key binding page](key-binding.md#prefix-mode) for the full list of default prefix shortcuts, or the [advanced key binding page](advanced-key-binding.md#custom-prefix-bindings) to customize them.
 
 ### `exit_past_line_start`
 
diff --git a/docs/docs/configuration/key-binding.md b/docs/docs/configuration/key-binding.md
index 47f24cd4..c8dc91bc 100644
--- a/docs/docs/configuration/key-binding.md
+++ b/docs/docs/configuration/key-binding.md
@@ -229,8 +229,14 @@ $env.config = (
 | ↓                                         | Select the next item on the list                                              |
 | ctrl + a, d                               | Delete the selected history entry                                            |
 | ctrl + a, D                               | Delete **all** history entries matching the selected command                  |
+| ctrl + a, a                               | Move cursor to the start of the line                                         |
 | ctrl + a, c                               | Switch to the context of the currently selected command / return to default   |
 
+### Prefix mode
+
+The shortcuts above that start with ++ctrl+a++ use **prefix mode** — a two-step key combination. Pressing the prefix key (++ctrl+a++ by default) enters prefix mode, then the next key you press triggers the action. Prefix mode exits automatically after the action runs.
+
+This is useful for less-frequent actions that don't need a dedicated shortcut. The prefix key can be changed with the [`prefix`](config.md#prefix) setting, and the bindings themselves can be customized with [`[keymap.prefix]`](advanced-key-binding.md#custom-prefix-bindings).
 
 ### Vim mode
 If [vim is enabled in the config](config.md#keymap_mode), the following keybindings are enabled: