feat: `switch-context` (#3149)

This PR lets you change the current search context to the one of the
currently selected command, which lets you easily see the surrounding
commands of its session.

It adds the following:
- `switch-context` and `clear-context` actions
- A `has-context` condition
- `CTX:` and `C>` prefixes to show we're in another context

The `switch-context` behavior is as follows:
- The selected command defines the new context
- The filter mode is automatically switched to SESSION
- The search input is cleared, which gives you a full overview of the
other commands executed in the same session
- The command which triggered this mode keeps being selected to get a
clear overview
- The filter mode can be changed to modes such as DIRECTORY, but not to
GLOBAL or SESSION+ as IMO those would be confusing in this mode

This lets you easily navigate between modes and commands the way you
prefer, for instance by switching the context through selected commands
or switching back to the default mode with the same key.

This could certainly still be improved (the docs are missing for
instance), and if you have any feedback I can change the behavior as you
see fit. I can add the docs when you'll approve the new names.

Closes #2784

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

---------

Co-authored-by: Ellie Huxtable <ellie@elliehuxtable.com>

6 files changed, 74 insertions, 17 deletions

diff --git a/docs/docs/configuration/advanced-key-binding.md b/docs/docs/configuration/advanced-key-binding.md
index 1fe9c1e4..7f73b5d6 100644
--- a/docs/docs/configuration/advanced-key-binding.md
+++ b/docs/docs/configuration/advanced-key-binding.md
@@ -206,6 +206,8 @@ Note: `select-next` and `select-previous` respect the `invert` setting. When `in
 | `cycle-filter-mode` | Cycle through filter modes (global, host, session, directory) |
 | `cycle-search-mode` | Cycle through search modes (fuzzy, prefix, fulltext, skim) |
 | `toggle-tab` | Toggle between the search tab and inspector tab |
+| `switch-context` | Switch to the [context](../guide/advanced-usage.md#context-switch) of the currently selected command |
+| `clear-context` | Return to the initial [context](../guide/advanced-usage.md#context-switch) |
 
 The difference between `accept` and `return-selection`: `accept` runs the command immediately when the TUI closes, while `return-selection` places it on your command line for further editing before you press enter. The `enter_accept` setting controls which of these the default `enter` key uses.
 
@@ -251,6 +253,7 @@ Conditions let a single key do different things depending on the current state.
 | `list-at-end` | The selection is at the last entry |
 | `no-results` | The search returned zero results |
 | `has-results` | The search returned at least one result |
+| `has-context` | The context comes from a previously selected command (`switch-context`) |
 
 ### Boolean expressions
 
diff --git a/docs/docs/configuration/config.md b/docs/docs/configuration/config.md
index 49e29a79..31980ed1 100644
--- a/docs/docs/configuration/config.md
+++ b/docs/docs/configuration/config.md
@@ -139,13 +139,14 @@ Default: `global`
 
 The default filter to use when searching
 
-| Mode             | Description                                                  |
-| ---------------- | ------------------------------------------------------------ |
-| global (default) | Search history from all hosts, all sessions, all directories |
-| host             | Search history just from this host                           |
-| session          | Search history just from the current session                 |
-| directory        | Search history just from the current directory (global)      |
-| workspace        | Search history just from the current git repository (>17.0)  |
+| Mode             | Description                                                                          |
+|------------------|--------------------------------------------------------------------------------------|
+| global (default) | Search from the full history                                                         |
+| host             | Search history from this host                                                        |
+| session          | Search history from the current session                                              |
+| directory        | Search history from the current directory                                            |
+| workspace        | Search history from the current git repository                                       |
+| session-preload  | Search from the current session and the global history from before the session start |
 
 Filter modes can still be toggled via ctrl-r
 
diff --git a/docs/docs/configuration/key-binding.md b/docs/docs/configuration/key-binding.md
index f292999f..942a2400 100644
--- a/docs/docs/configuration/key-binding.md
+++ b/docs/docs/configuration/key-binding.md
@@ -202,31 +202,32 @@ $env.config = (
 ## Atuin UI shortcuts
 
 | Shortcut                                  | Action                                                                        |
-| ----------------------------------------- | ----------------------------------------------------------------------------- |
-| enter                                     | Execute selected item                                                        |
+|-------------------------------------------|-------------------------------------------------------------------------------|
+| enter                                     | Execute selected item                                                         |
 | tab                                       | Select item and edit                                                          |
 | ctrl + r                                  | Cycle through filter modes                                                    |
 | ctrl + s                                  | Cycle through search modes                                                    |
 | alt + 1 to alt + 9                        | Select item by the number located near it                                     |
 | ctrl + c / ctrl + d / ctrl + g / esc      | Return original                                                               |
 | ctrl + y                                  | Copy selected item to clipboard                                               |
-| ctrl + ← / alt + b                       | Move the cursor to the previous word                                          |
-| ctrl + → / alt + f                       | Move the cursor to the next word                                              |
-| ctrl + b / ←                  | Move the cursor to the left                                                   |
-| ctrl + f / →                  | Move the cursor to the right                                                  |
+| ctrl + ← / alt + b                        | Move the cursor to the previous word                                          |
+| ctrl + → / alt + f                        | Move the cursor to the next word                                              |
+| ctrl + b / ←                              | Move the cursor to the left                                                   |
+| ctrl + f / →                              | Move the cursor to the right                                                  |
 | ctrl + a / home                           | Move the cursor to the start of the line                                      |
 | ctrl + e / end                            | Move the cursor to the end of the line                                        |
 | ctrl + backspace / ctrl + alt + backspace | Remove the previous word / remove the word just before the cursor             |
 | ctrl + delete / ctrl + alt + delete       | Remove the next word or the word just after the cursor                        |
 | ctrl + w                                  | Remove the word before the cursor even if it spans across the word boundaries |
 | ctrl + u                                  | Clear the current line                                                        |
-| ctrl + n / ctrl + j / ↑                  | Select the next item on the list                                              |
-| ctrl + p / ctrl + k / ↓                  | Select the previous item on the list                                          |
+| ctrl + n / ctrl + j / ↑                   | Select the next item on the list                                              |
+| ctrl + p / ctrl + k / ↓                   | Select the previous item on the list                                          |
 | ctrl + o                                  | Open the [inspector](#inspector)                                              |
 | page down                                 | Scroll search results one page down                                           |
 | page up                                   | Scroll search results one page up                                             |
-| ↓ (with no entry selected)               | Return original or return query depending on [settings](config.md#exit_mode)                         |
-| ↓                                        | Select the next item on the list                                              |
+| ↓ (with no entry selected)                | Return original or return query depending on [settings](config.md#exit_mode)  |
+| ↓                                         | Select the next item on the list                                              |
+| ctrl + a, c                               | Switch to the context of the currently selected command / return to default   |
 
 
 ### Vim mode
diff --git a/docs/docs/guide/advanced-usage.md b/docs/docs/guide/advanced-usage.md
new file mode 100644
index 00000000..0d5a1359
--- /dev/null
+++ b/docs/docs/guide/advanced-usage.md
@@ -0,0 +1,49 @@
+# Advanced Usage
+
+Atuin offers you several options to help navigate through the results.
+
+## Filter mode
+
+The command history can be filtered in different ways, letting you narrow the search scope.
+
+You can cycle through the different modes by pressing **ctrl-r**.
+
+The available modes are:
+
+| Mode             | Description                                                                          |
+|------------------|--------------------------------------------------------------------------------------|
+| global (default) | Search from the full history                                                         |
+| host             | Search history from this host                                                        |
+| session          | Search history from the current session                                              |
+| directory        | Search history from the current directory                                            |
+| workspace        | Search history from the current git repository                                       |
+| session-preload  | Search from the current session and the global history from before the session start |
+
+See the [`filter_mode` config reference](../configuration/config.md#filter_mode) for more details.
+
+## Search mode
+
+Atuin offers different modes to interpret your search query.
+
+You can cycle through the different modes by pressing **ctrl-s**.
+
+The available modes are:
+
+| Mode            | Description                                                                                                    |
+|-----------------|----------------------------------------------------------------------------------------------------------------|
+| fuzzy (default) | Search for commands in a fuzzy way, similar to the [fzf syntax](https://github.com/junegunn/fzf#search-syntax) |
+| prefix          | Commands that start with your query                                                                            |
+| fulltext        | Commands that contain your query as a substring                                                                |
+| skim            | Search for commands using the [skim syntax](https://github.com/lotabout/skim#search-syntax)                    |
+
+See the [`search_mode` config reference](../configuration/config.md#search_mode) for more details.
+
+## Context switch
+
+Atuin uses the current context (host, session, directory) to filter the history when you use a filter mode other than *global*.
+
+You can switch this context to the one of the currently selected command by pressing **ctrl-a** then **c**.
+
+This will set the filter mode to *session* and clear the search query, which will show you all the commands executed in the same shell session.
+
+Pressing this key combination again will return to the initial context. You can customize this behavior by setting [custom key bindings](../configuration/advanced-key-binding.md) to the `switch-context` and `clear-context` commands. `switch-context` can be called several times to navigate through multiple command contexts, while `clear-context` will always return to the initial context.
diff --git a/docs/docs/guide/basic-usage.md b/docs/docs/guide/basic-usage.md
index 0b40a0aa..f6df1c94 100644
--- a/docs/docs/guide/basic-usage.md
+++ b/docs/docs/guide/basic-usage.md
@@ -26,6 +26,8 @@ While searching in the TUI, you can adjust the "filter mode" by repeatedly press
 3. The current directory only
 4. The current shell session only
 
+See the [advanced usage](advanced-usage.md) page for more options.
+
 ## Common config adjustment
 
 For a full set of config values, please see the [config reference page](../configuration/config.md).
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 1cbbf30d..4ca51c60 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -63,6 +63,7 @@ nav:
       - Setting up sync: guide/sync.md
       - Import existing history: guide/import.md
       - Basic usage: guide/basic-usage.md
+      - Advanced usage: guide/advanced-usage.md
       - Deleting history: guide/delete-history.md
       - Syncing dotfiles: guide/dotfiles.md
       - Theming: guide/theming.md