Mega update of shell integration docs and features (#769)

wow boy howdy, a lot of this needed updating

TerminalDocs/TOC.yml

@@ -42,6 +42,8 @@
       href: dynamic-profiles.md
     - name: JSON fragment extensions
       href: json-fragment-extensions.md
+    - name: Shell integration
+      href: tutorials/shell-integration.md
     - name: Cascadia Code
       href: cascadia-code.md
     - name: Terminal Chat
@@ -58,8 +60,6 @@
           href: tutorials/tab-title.md
         - name: Open tab or pane in same directory
           href: tutorials/new-tab-same-directory.md
-        - name: Shell integration
-          href: tutorials/shell-integration.md
         - name: Set the progress bar
           href: tutorials/progress-bar-sequences.md
     - name: Custom Terminal gallery

TerminalDocs/customize-settings/actions.md

@@ -1288,9 +1288,9 @@ Changes the active color scheme.
 { "command": { "action": "setColorScheme", "colorScheme": "Campbell" }, "keys": "" }
 ```
 
-### Experimental add scroll mark
+### Add scroll mark
 
-Adds a scroll mark to the text buffer. If there's a selection, the mark is placed at the selection, otherwise it's placed at the cursor row. This is an experimental feature, and its continued existence is not guaranteed.
+Adds a scroll mark to the text buffer. If there's a selection, the mark is placed at the selection, otherwise it's placed at the cursor row.
 
 **Command name:** `addMark`
 
@@ -1306,9 +1306,12 @@ Adds a scroll mark to the text buffer. If there's a selection, the mark is place
 { "command": { "action": "addMark", "color": "#ff00ff" } }
 ```
 
-### Experimental scroll to mark
+> [!IMPORTANT]
+> This action became stable in v1.21. Before that version, it was only available in [Windows Terminal Preview](https://aka.ms/terminal-preview)
+
+### Scroll to mark
 
-Scrolls to the scroll mark in the given direction. This is an experimental feature, and its continued existence is not guaranteed.
+Scrolls to the scroll mark in the given direction. For more info, see [Scroll marks](../customize-settings/profile-advanced.md#scroll-marks-preview) and [Shell Integration](../tutorials/shell-integration.md).
 
 **Command name:** `scrollToMark`
 
@@ -1324,7 +1327,10 @@ Scrolls to the scroll mark in the given direction. This is an experimental featu
 { "command": { "action": "scrollToMark", "direction": "previous" } }
 ```
 
-### Experimental clear mark
+> [!IMPORTANT]
+> This action became stable in v1.21. Before that version, it was only available in [Windows Terminal Preview](https://aka.ms/terminal-preview)
+
+### Clear mark
 
 Clears scroll mark at the current position, either at a selection if there is one or at the cursor position. This is an experimental feature, and its continued existence is not guaranteed.
 
@@ -1336,7 +1342,10 @@ Clears scroll mark at the current position, either at a selection if there is on
 { "command": { "action": "clearMark" } }
 ```
 
-### Experimental clear all marks
+> [!IMPORTANT]
+> This action became stable in v1.21. Before that version, it was only available in [Windows Terminal Preview](https://aka.ms/terminal-preview)
+
+### Clear all marks
 
 Clears all scroll marks in the text buffer. This is an experimental feature, and its continued existence is not guaranteed.
 
@@ -1348,6 +1357,9 @@ Clears all scroll marks in the text buffer. This is an experimental feature, and
 { "command": { "action": "clearAllMarks" } }
 ```
 
+> [!IMPORTANT]
+> This action became stable in v1.21. Before that version, it was only available in [Windows Terminal Preview](https://aka.ms/terminal-preview)
+
 <br />
 ___
 
@@ -1368,7 +1380,7 @@ This allows the user to open the suggestions menu. The entries in the suggestion
 :::column-end:::
 :::row-end:::
 
-**Command name:** `openSuggestions`
+**Command name:** `showSuggestions`
 
 #### Parameters
 
@@ -1387,9 +1399,9 @@ The following suggestion sources are supported:
 
 These values can be used by themselves as a string parameter value, or combined as an array. For example:
 ```json
-{ "command": { "action": "openSuggestions", "source": ["recentCommands", "tasks"] } },
-{ "command": { "action": "openSuggestions", "source": "all" } },
-{ "command": { "action": "openSuggestions", "source": "recentCommands" } },
+{ "command": { "action": "showSuggestions", "source": ["recentCommands", "tasks"] } },
+{ "command": { "action": "showSuggestions", "source": "all" } },
+{ "command": { "action": "showSuggestions", "source": "recentCommands" } },
 ```
 
 In the above example, the first two commands will open the suggestions menu with both recent commands and tasks. The third command will open the suggestions menu with only recent commands.

TerminalDocs/customize-settings/profile-advanced.md

@@ -151,33 +151,41 @@ ___
 
 ## Scroll marks ([Preview](https://aka.ms/terminal-preview))
 
-The following settings modify how scroll marks behave in Windows Terminal.
+The following settings modify how scroll marks behave in Windows Terminal. For
+more info on marks and shell integration, visit the [Shell integration
+page](../tutorials/shell-integration.md).
 
-### Experimental automatically add scroll marks ([Preview](https://aka.ms/terminal-preview))
+### Automatically add scroll marks
 
-Automatically marks prompts when set to `true`. This is an experimental feature, and its continued existence is not guaranteed.
+When set to `true`, the Terminal will automatically mark the current like as a
+prompt when the user presses <kbd>Enter</kbd>. If the user has shell integration
+enabled, this will treat the current cursor position as a `FTCS;C`, ending the
+current command and starting the output.
 
-**Property name:** `experimental.autoMarkPrompts`
+
+**Property name:** `autoMarkPrompts`
 
 **Necessity:** Optional
 
 **Accepts:** `true`, `false`
 
 > [!IMPORTANT]
-> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+> This feature became stable in v1.21. Before that version, it was only available in [Windows Terminal Preview](https://aka.ms/terminal-preview), and was named `experimental.autoMarkPrompts`.
 
-### Experimental show marks on scrollbar ([Preview](https://aka.ms/terminal-preview))
+### Show marks on scrollbar
 
-Displays marks on the scrollbar when set to `true`. This is an experimental feature, and its continued existence is not guaranteed.
+Displays marks on the scrollbar when set to `true`. When combined with `autoMarkPrompts` or shell integration, this will show the location of the prompts on the scrollbar.
 
-**Property name:** `experimental.showMarksOnScrollbar`
+![Windows Terminal scrollbar marks](../images/scroll-marks.png)
+
+**Property name:** `showMarksOnScrollbar`
 
 **Necessity:** Optional
 
 **Accepts:** `true`, `false`
 
 > [!IMPORTANT]
-> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+> This feature became stable in v1.21. Before that version, it was only available in [Windows Terminal Preview](https://aka.ms/terminal-preview), and was named `experimental.showMarksOnScrollbar`.
 
 ___
 

TerminalDocs/tutorials/shell-integration.md

@@ -8,14 +8,30 @@ ms.topic: tutorial
 #Customer intent: As a developer or IT admin, I want to enable shell integration
 ---
 
-# Tutorial: Enable shell integration in the Windows Terminal
+# Shell Integration
+
+- [Shell Integration](#shell-integration)
+  - [How does this work?](#how-does-this-work)
+  - [How to enable shell integration marks](#how-to-enable-shell-integration-marks)
+    - [PowerShell (`pwsh.exe`)](#powershell-pwshexe)
+    - [Command Prompt](#command-prompt)
+    - [Bash](#bash)
+  - [Shell integration features](#shell-integration-features)
+    - [Open new tabs in the same working directory](#open-new-tabs-in-the-same-working-directory)
+    - [Show marks for each command in the scrollbar](#show-marks-for-each-command-in-the-scrollbar)
+    - [Automatically jump between commands](#automatically-jump-between-commands)
+    - [Select the entire output of a command](#select-the-entire-output-of-a-command)
+    - [Recent command suggestions](#recent-command-suggestions)
+  - [Additional resources](#additional-resources)
+
 
 Starting in Terminal 1.15 Preview, the Windows Terminal has started experimentally supporting some "shell integration" features. These features make the command-line easier to use. In earlier releases, we enabled shell to tell the Terminal what the current working directory is. Now, we've added support for more sequences to allow your shell to semantically describe parts of the terminal output as a "prompt", a "command", or "output". The shell can also tell the terminal whether a command succeeded or failed.
 
 This is a guide to some of the shell integration features we've rolled out as of Terminal v1.18. We're planning on building even more features on top of these in the future, so we'd love to get some additional feedback on how folks using them.
 
 > **Note**:
->  Notably, "marks" are still experimental, and are **only enabled for [Preview](https://aka.ms/terminal-preview) builds of the Terminal**. The settings for these features may change in a future release.
+>  As of Terminal 1.21, marks are now a stable feature. Prior to 1.21, marks were **only enabled for [Preview](https://aka.ms/terminal-preview) builds of the Terminal**.
+> If you're using a version of Terminal before 1.21, the `showMarksOnScrollbar` setting was named `experimental.showMarksOnScrollbar`, and `autoMarkPrompts` was named `experimental.autoMarkPrompts`.
 
 ## How does this work?
 
@@ -41,16 +57,16 @@ Supporting these features requires cooperation between your shell and the Termin
 
 To enable these features in the Terminal, you'll want to add the following to your settings:
 
-```jsonc
+```json
 "profiles":
 {
     "defaults":
     {
-        // Marks in general
-        "experimental.showMarksOnScrollbar": true,
+        // Enable marks on the scrollbar
+        "showMarksOnScrollbar": true,
 
-        // Needed for both pwsh and CMD shell integration
-        "experimental.autoMarkPrompts": true,
+        // Needed for both pwsh, CMD and bash shell integration
+        "autoMarkPrompts": true,
 
         // Add support for a right-click context menu
         // You can also just bind the `showContextMenu` action
@@ -59,15 +75,16 @@ To enable these features in the Terminal, you'll want to add the following to yo
 }
 "actions":
 [
+    // Scroll between prompts
     { "keys": "ctrl+up",   "command": { "action": "scrollToMark", "direction": "previous" }, },
     { "keys": "ctrl+down", "command": { "action": "scrollToMark", "direction": "next" }, },
 
     // Add the ability to select a whole command (or its output)
-    { "keys": "ctrl+shift+w", "command": { "action": "selectOutput", "direction": "prev" }, },
-    { "keys": "ctrl+shift+s", "command": { "action": "selectOutput", "direction": "next" }, },
+    { "command": { "action": "selectOutput", "direction": "prev" }, },
+    { "command": { "action": "selectOutput", "direction": "next" }, },
 
-    { "keys": "ctrl+alt+shift+w", "command": { "action": "selectCommand", "direction": "prev" }, },
-    { "keys": "ctrl+alt+shift+s", "command": { "action": "selectCommand", "direction": "next" }, },
+    { "command": { "action": "selectCommand", "direction": "prev" }, },
+    { "command": { "action": "selectCommand", "direction": "next" }, },
 ]
 ```
 
@@ -81,7 +98,7 @@ We'll need to edit your `prompt` to make sure we tell the Terminal about the CWD
 
 Add the following to your [PowerShell profile](/powershell/module/microsoft.powershell.core/about/about_profiles):
 
-```pwsh
+```powershell
 $Global:__LastHistoryId = -1
 
 function Global:__Terminal-Get-LastExitCode {
@@ -155,10 +172,20 @@ These examples assume your current `PROMPT` is just `$P$G`. You can instead choo
 PROMPT $e]133;D$e\$e]133;A$e\$e]9;9;$P$e\%PROMPT%$e]133;B$e\
 ```
 
+### Bash
+
+You can add the following to the end of your `~/.bashrc` to enable shell integration in bash:
+
+```bash
+PS1="\[\033]133;D;\007\]\[\033]133;A;\007\]$PS1\[\033]133;B;\007\]"
+```
+
+This will wrap your existing `$PS1` with the necessary sequences to enable shell integration.
+
 > **Note**:
 > Don't see your favorite shell here? If you figure it out, feel free to [contribute a solution for your preferred shell!](https://github.com/MicrosoftDocs/terminal/compare)
 
-## Shell integration demos
+## Shell integration features
 
 ### Open new tabs in the same working directory
 ![Open new tabs in the same working directory](../images/duplicate-tab-same-cwd.gif)
@@ -168,9 +195,37 @@ PROMPT $e]133;D$e\$e]133;A$e\$e]9;9;$P$e\%PROMPT%$e]133;B$e\
 
 ### Automatically jump between commands
 
+This uses the `scrollToMark` actions as we have them defined above.
+
 ![Automatically jump between commands](https://user-images.githubusercontent.com/18356694/164290677-ffaafe09-81c4-4181-a4b8-db79a8aed235.gif)
 
 ### Select the entire output of a command
+
+In this gif, we use the `selectOutput` action bound to `ctrl+g` to select the entire output of a command.
 ![Select the entire output of a command](https://user-images.githubusercontent.com/18356694/207696859-a227abe2-ccd4-4b81-8a2c-8a22219cd0dd.gif)
 
+The following uses the `experimental.rightClickContextMenu` setting to enable a right-click context menu in the Terminal. With that and shell integration enabled, you can right-click on a command to select the entire command or its output.
+
 ![Select the command using the right-click context menu](https://user-images.githubusercontent.com/18356694/222840120-7a2493b2-2264-4e94-af2b-17bfacc90353.gif)
+
+
+### Recent command suggestions
+
+With shell integration enabled, the Suggestions UI can be configured to also show your recent commands.
+
+![The suggestions UI showing recent commands in it](../images/recent-command-suggestions.gif)
+
+You can open this menu with the following action:
+
+```json
+{
+    "command": { "action": "showSuggestions", "source": "recentCommands", "useCommandline": true },
+},
+```
+
+(For more info, see the [Suggestions documentation](../customize-settings/actions.md#open-suggestions-menu))
+
+## Additional resources
+* [`autoMarkPrompts`](../customize-settings/profile-advanced.md#automatically-add-scroll-marks)
+* [`showMarksOnScrollbar`](../customize-settings/profile-advanced.md#show-marks-on-scrollbar)
+* [`showSuggestions`](../customize-settings/actions.md#open-suggestions-menu)