+
+| Compatibility |
+
+This shouldn't break any existing flows. This is a general purpose UI element,
+to be extended in a variety of ways. Those customizations will all be opt-in by
+the user, so I'm not expecting any breaking compatibility changes here.
+
+ |
+
+| Accessibility |
+
+The Suggestions UI was designed with the goal of making commandline shell
+suggestions _more_ accessible. As Carlos previously wrote:
+
+> Screen readers struggle with this because the entire menu is redrawn every time, making it harder to understand what exactly is "selected" (as the concept of selection in this instance is a shell-side concept represented by visual manipulation).
+>
+> ...
+>
+> _\[Shell driven suggestions\]_ can then be leveraged by Windows Terminal to create UI elements. Doing so leverages WinUI's accessible design.
+
+This will allow the Terminal to provide more context-relevant information to
+screen readers.
+
+ |
+
+| Sustainability |
+
+No sustainability changes expected.
+
+ |
+
+| Localization |
+
+The localization needs of the Suggestions UI will be effectively the same as the
+needs of the Command Palette.
+
+The Terminal will have no way to localize suggestions that are provided via
+[shell-driven autocompletion]. These are just verbatim strings that the shell
+told us to use. We don't consider this to be something to worry about, however.
+This is no different than the fact that Terminal cannot localize the `Get-Help`
+(or any other) output of PowerShell.
+
+ |
+
+
+
+## Implementation Plan
+
+This is more of an informative outline, rather than a normative one. Many of the
+things from Crawl, Walk, and Run are all already in PRs as of the time of this
+spec's review.
+
+### 🐣 Crawl
+
+* [ ] Fork the Command palette to a new UI element, the `SuggestionsControl`
+* [ ] Enable previewing `sendInput` actions in the Command Palette and `SuggestionsControl`
+* [ ] Enable the `SuggestionsControl` to open top-down (aligned to the bottom of the cursor row) or bottom-up (aligned to the top of the cursor row).
+* [ ] Disable sorting on the `SuggestionsControl` - elements should presumably be pre-sorted by the source.
+* [ ] Expose the recent commands as a accessor on `TermControl`
+* [ ] Add a `suggestions` action which accepts a single option `recentCommands`. These should be fed in MRU order to the `SuggestionsControl`.
+* [ ] Expose the recent directories as an accessor on `TermControl`, and add a `recentDirectories` source.
+
+### 🚶 Walk
+
+* [ ] Add a `tasks` source to `suggestions` which opens the Suggestions UI with
+ a tree of all `sendInput` commands
+* [ ] Enable the `SuggestionsControl` to open with or without a search box
+* [ ] Plumb support for shell-driven completions through the core up to the app
+* [ ] Expose the _current_ commandline from the `TermControl`
+* [ ] Add a `useCommandline` property to `suggestions`, to pre-populate the search with the current commandline.
+* [ ] Persist recent commands / directories accordingly
+
+### 🏃♂️ Run
+
+* [ ] Add a `description` field to `Command`
+* [ ] Add a `TeachingTip` (or similar) to the Suggestions UI to display
+ descriptions (when available)
+* [ ] Use the `ToolTip` property of shell-driven suggestions as the description
+* [ ] Add a boolean `nesting` property which can be used to disable nesting on the `tasks` source.
+* [ ] Add the ability for `nesting` to accept `enabled`/`disabled` as `true`/`false` equivalents
+* [ ] Add the ability for `nesting` to accept `source`, which instead groups all
+ commands to the Suggestions UI by the source of that suggestion.
+
+### 🚀 Sprint
+
+The two "sprint" tasks here are much more ambitious than the other listed
+scenarios, so breaking them down to atomic tasks sees less reasonable. We'd have
+to spend a considerable amount more time figuring out _how_ to do each of these
+first.
+
+For example - extensions. We have yet to fully realize what extensions _are_.
+Determining how extensions will provide suggestions is left as something we'll
+need to do as a part of the Extensions spec.
+
+## Conclusion
+
+Here's a sample json schema for the settings discussed here.
+
+```json
+"OpenSuggestionsAction": {
+ "description": "Arguments corresponding to a Open Suggestions Action",
+ "allOf": [
+ {
+ "$ref": "#/$defs/ShortcutAction"
+ },
+ {
+ "properties": {
+ "action": {
+ "type": "string",
+ "const": "suggestions"
+ },
+ "source": {
+ "$ref": "#/$defs/SuggestionSource",
+ "description": "Which suggestion sources to filter."
+ },
+ "useCommandline": {
+ "default": false,
+ "description": "When set to `true`, the current commandline the user has typed will pre-populate the filter of the Suggestions UI. This requires that the user has enabled shell integration in their shell's config. When set to false, the filter will start empty."
+ },
+ "nesting": {
+ "default": true,
+ "description": "When set to `true`, suggestions will follow the provided nesting structure. For Tasks, these will follow the structure of the Command Palette. When set to `false`, no nesting will be used (and all suggestions will be in the top-level menu.",
+ "$comment": "This setting is a possible follow-up setting, not required for v1. "
+ }
+ }
+ }
+ ]
+},
+"BuiltinSuggestionSource": {
+ "enum": [
+ "commandHistory",
+ "directoryHistory",
+ "tasks",
+ "local",
+ "all"
+ ],
+ "type": "string"
+},
+"SuggestionSource": {
+ "default": "all",
+ "description": "Either a single suggestion source, or an array of sources to concatenate. Built-in sources include `commandHistory`, `directoryHistory`, `tasks`, and `local`. Extensions may provide additional values. The special value `all` indicates all suggestion sources should be included",
+ "$comment": "`tasks` and `local` are sources that would be added by the Tasks feature, as a follow-up"
+ "oneOf": [
+ {
+ "type": [ "string", "null", "BuiltinSuggestionSource" ]
+ },
+ {
+ "type": "array",
+ "items": { "type": "BuiltinSuggestionSource" }
+ },
+ {
+ "type": "array",
+ "items": { "type": "string" }
+ }
+ ]
+},
+```
+
+### Future Considerations
+
+* Another extension idea: `WithFig.FigCompletions`. Imagine an extension that
+ could parse existing [Fig] completion specs, and provide those as suggestions
+ in this way.
+ * This might be a good example of an async suggestion source. The current
+ commandline is used as the starting filter, and the suggestions would be
+ populated by some `fig` process / thread / async operation that returns the
+ suggestions.
+* If the user hasn't enabled shell completion, we could add text to the
+ `commandHistory` or `directoryHistory` menus to inform the user how they could
+ go enable shell integration. We already have a docs page dedicated to this, so
+ we could start by linking to that page. More notes on this in [Automatic shell
+ integration](#Automatic-shell-integration).
+* Maybe there could be a per-profile setting for automatic suggestions after
+ some timeout. Like, as you type, a menu version of the Suggestions UI appears.
+ So you could just start typing `git c`, and it would automatically give you a
+ menu with suggestions, implicitly using the typed command as the "filter".
+ * Maybe we could do this as an `implicit` property on the `suggestions` action
+
+
+#### Description Tooltips
+
+> **Note**: _This is left as a future consideration for the initial draft of
+> this spec. I'd like to flesh out [shell-driven autocompletion] more before
+> committing any plans here._
+
+It would be beneficial for the Suggestions UI to display additional context to
+the user. Consider a extension that provides some commands for the user, like a
+hypothetical "Docker" extension. The extension author might be able to give the
+commands simplified names, but also want to expose a more detailed description
+of the commands to the user.
+
+Or consider the Suggestions UI when invoked by [shell-driven autocompletion].
+The shell might want to provide help text to the user with each of the
+suggestions. This would allow a user to browse through the suggestions that they
+might not know about, and learn how they work before committing to one.
+
+Only the help text for the currently hovered command should be presented to the
+user. To support this kind of UX, we'll add an optional flyout of some sort to
+display with the Suggestions UI. This flyout will only appear if there's more
+information provided to the Terminal.
+
+This might be in the form of a `TeachingTip`, as in this example:
+
+
+
+Actions in the settings could also accept an optional `description` property, to
+specify the string that would be presented in that flyout.
+
+#### Automatic shell integration
+
+A large portion of these features all rely on shell integration being enabled by
+the user. However, this is not a trivial thing for the Terminal to do on behalf
+of the user. Shell integration relies on changes to the user's shell config. If
+the Terminal were to try and configure those itself, we may accidentally destroy
+configuration that the user has already set up. Hence why the Terminal can't
+just have a "Light up all the bells and whistles" toggle in the Settings UI.
+
+This is a non-trivial problem to solve, so it is being left as a future
+consideration, for a later spec. It deserves its own spec to sort out how we
+should expose this to users and safely implement it.
+
+#### Pre-filtering the UI & filter by source
+
+> **Note**: _This is a brainstorm I considered while writing this spec. I would
+> not include it in the v1 of this spec. Rather, I'd like to leave it for
+> where we might go with this UX in the future._
+
+Do want to support different _types_ of nesting? So instead of just the default,
+there could be something like `nesting: "source"`, to create a menu structured
+like:
+
+```
+Suggestions UI
+├─ Recent Commands...
+│ ├─ git checkout main
+│ ├─ git fetch
+│ └─ git pull
+├─ Recent Directories...
+│ ├─ d:\dev
+│ ├─ d:\dev\public
+│ └─ d:\dev\public\terminal
+├─ Saved tasks...
+│ ├─ Git...
+│ │ └─ git commit -m "
+│ │ └─ git log...
+│ └─ bx & runut
+└─ Docker
+ ├─ docker build --platform linux/amd64