Improve the VT cursor movement implementation (#3628)

## Summary of the Pull Request

Originally there were 3 different methods for implementing VT cursor movement, and between them they still couldn't handle some of the operations correctly. This PR unifies those operations into a single method that can handle every type of cursor movement, and which fixes some of the issues with the existing implementations. In particular it fixes the `CNL` and `CPL` operations, so they're now correctly constrained by the `DECSTBM` margins.

## References

If this PR is accepted, the method added here should make it trivial to implement the `VPR` and `HPR` commands in issue #3428.

## PR Checklist
* [x] Closes #2926
* [x] CLA signed. If not, go over [here](https://cla.opensource.microsoft.com/microsoft/Terminal) and sign the CLA
* [x] Tests added/passed
* [ ] Requires documentation to be updated
* [ ] I've discussed this with core contributors already. If not checked, I'm ready to accept this work might be rejected in favor of a different grand plan. Issue number where discussion took place: #xxx

## Detailed Description of the Pull Request / Additional comments

The new [`AdaptDispatch::_CursorMovePosition`](d6c4f35cf6/src/terminal/adapter/adaptDispatch.cpp (L169)) method is based on the proposal I made in issue #3428 for the `VPR` and `HPR` comands. It takes three arguments: a row offset (which can be absolute or relative), a column offset (ditto), and a flag specifying whether the position should be constrained by the `DECSTBM` margins.

To make the code more readable, I've implemented the offsets using [a `struct` with some `constexpr` helper functions for the construction](d6c4f35cf6/src/terminal/adapter/adaptDispatch.hpp (L116-L125)). This lets you specify the parameters with expressions like `Offset::Absolute(col)` or `Offset::Forward(distance)` which I think makes the calling code a little easier to understand.

While implementing this new method, I noticed a couple of issues in the existing movement implementations which I thought would be good to fix at the same time.

1. When cursor movement is constrained horizontally, it should be constrained by the buffer width, and not the horizontal viewport boundaries. This is an issue I've previously corrected in other parts of the codebase, and I think the cursor movement was one of the last areas where it was still a problem.

2. A number of the commands had range and overflow checks for their parameters that were either unnecessary (testing for a condition that could never occur) or incorrect (if an operation overflows, the correct behavior is to clamp it, and not just fail). The new implementation handles legitimate overflows correctly, but doesn't check for impossible ranges.

Because of the change of behavior in point 1, I also had to update the implementations of [the `DECSC` and `CPR` commands](9cf7a9b577) to account for the column offset now being relative to the buffer and not the viewport, otherwise those operations would no longer work correctly.

## Validation Steps Performed

Because of the two changes in behavior mentioned above, there were a number of adapter tests that stopped working and needed to be updated. First off there were those that expected the column offset to be relative to the left viewport position and constrained by the viewport width. These now had to be updated to [use the full buffer width](49887a3589) as the allowed horizontal extent.

Then there were all the overflow and out-of-range tests that were testing conditions that could never occur in practice, or where the expected behavior that was tested was actually incorrect. I did spend some time trying to see if there was value in updating these tests somehow, but in the end I decided it was best to just [drop them](6e80d0de19) altogether.

For the `CNL` and `CPL` operations, there didn't appear to be any existing tests, so I added some [new screen buffer tests](d6c4f35cf6) to check that those operations now work correctly, both with and without margins.

(cherry picked from commit 2fec1787a0)

.github/ISSUE_TEMPLATE/Bug_Report.md

@@ -1,7 +1,7 @@
 ---
-name: Bug report 🐛
+name: "Bug report 🐛"
 about: Report errors or unexpected behavior
-title: "Bug Report (IF I DO NOT CHANGE THIS THE ISSUE WILL BE AUTO-CLOSED)"
+title: ''
 labels: ''
 assignees: ''
 

.github/ISSUE_TEMPLATE/Documentation_Issue.md

@@ -1,7 +1,7 @@
 ---
-name: Documentation Issue 📚
+name: "Documentation Issue 📚"
 about: Report issues in our documentation
-title: "Documentation Issue"
+title: ''
 labels: Issue-Docs
 assignees: ''
 

.github/ISSUE_TEMPLATE/Feature_Request.md

@@ -1,34 +1,35 @@
----
-name: Feature Request/Idea 🚀
-about: Suggest a new feature or improvement (this does not mean you have to implement it)
-title: "Feature Request"
-labels: Issue-Feature
-assignees: ''
-
----
-
-<!-- 
-🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨
-
-I ACKNOWLEDGE THE FOLLOWING BEFORE PROCEEDING:
-1. If I delete this entire template and go my own path, the core team may close my issue without further explanation or engagement.
-2. If I list multiple bugs/concerns in this one issue, the core team may close my issue without further explanation or engagement.
-3. If I write an issue that has many duplicates, the core team may close my issue without further explanation or engagement (and without necessarily spending time to find the exact duplicate ID number).
-4. If I leave the title incomplete when filing the issue, the core team may close my issue without further explanation or engagement.
-5. If I file something completely blank in the body, the core team may close my issue without further explanation or engagement.
-
-All good? Then proceed!
--->
-
-# Description of the new feature/enhancement
-
-<!-- 
-A clear and concise description of what the problem is that the new feature would solve.
-Describe why and how a user would use this new functionality (if applicable).
--->
-
-# Proposed technical implementation details (optional)
-
-<!-- 
-A clear and concise description of what you want to happen.
--->
+---
+name: "Feature Request/Idea 🚀"
+about: Suggest a new feature or improvement (this does not mean you have to implement
+  it)
+title: ''
+labels: Issue-Feature
+assignees: ''
+
+---
+
+<!-- 
+🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨
+
+I ACKNOWLEDGE THE FOLLOWING BEFORE PROCEEDING:
+1. If I delete this entire template and go my own path, the core team may close my issue without further explanation or engagement.
+2. If I list multiple bugs/concerns in this one issue, the core team may close my issue without further explanation or engagement.
+3. If I write an issue that has many duplicates, the core team may close my issue without further explanation or engagement (and without necessarily spending time to find the exact duplicate ID number).
+4. If I leave the title incomplete when filing the issue, the core team may close my issue without further explanation or engagement.
+5. If I file something completely blank in the body, the core team may close my issue without further explanation or engagement.
+
+All good? Then proceed!
+-->
+
+# Description of the new feature/enhancement
+
+<!-- 
+A clear and concise description of what the problem is that the new feature would solve.
+Describe why and how a user would use this new functionality (if applicable).
+-->
+
+# Proposed technical implementation details (optional)
+
+<!-- 
+A clear and concise description of what you want to happen.
+-->

.github/ISSUE_TEMPLATE/Guidance_Issue.md

@@ -1,10 +0,0 @@
----
-name: Community Guidance Request ✨
-about: Suggest somewhere the Windows Terminal Team needs to provide community guidance through new documentation or process.
-title: "Guidance"
-labels: Issue-Docs
-assignees: 'bitcrazed'
-
----
-
-<!-- What needs to change? Who is responsible for it? Why is it an open question? -->

.gitignore

@@ -261,6 +261,9 @@ build*.rec
 build*.wrn
 build*.metadata
 
+# MS Build binary logs
+*.binlog
+
 # .razzlerc.cmd file - used by dev environment
 tools/.razzlerc.*
 # .PowershellModules - if one needs a powershell module dependency, one

NOTICE.md

@@ -47,3 +47,33 @@ ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
+
+## telnetpp
+
+**Source**: https://github.com/KazDragon/telnetpp
+
+### License 
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2015-2017 Matthew Chaplain a.k.a KazDragon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

README.md

@@ -1,159 +1,167 @@
-# Welcome\! 
-#### This repository contains the source code for:
+# Welcome to the Windows Terminal, Console and Command-Line repo
 
-  * [Windows Terminal](https://www.microsoft.com/en-us/p/windows-terminal-preview/9n0dx20hk701)
-  * The Windows console host (`conhost.exe`)
-  * Components shared between the two projects
-  * [ColorTool](https://github.com/Microsoft/Terminal/tree/master/src/tools/ColorTool)
-  * [Sample projects](https://github.com/Microsoft/Terminal/tree/master/samples) that show how to consume the Windows Console APIs
-  
-#### Other related repositories include:
-  * [Console API Documentation](https://github.com/MicrosoftDocs/Console-Docs)
+This repository contains the source code for:
 
-## Installation
+* [Windows Terminal](https://www.microsoft.com/en-us/p/windows-terminal-preview/9n0dx20hk701)
+* The Windows console host (`conhost.exe`)
+* Components shared between the two projects
+* [ColorTool](https://github.com/Microsoft/Terminal/tree/master/src/tools/ColorTool)
+* [Sample projects](https://github.com/Microsoft/Terminal/tree/master/samples) that show how to consume the Windows Console APIs
 
-_(Note: in order to run the Windows Terminal, you'll need to be running at least Windows build 18362 or higher.)_
+Related repositories include:
 
-### Microsoft Store
+* [Console API Documentation](https://github.com/MicrosoftDocs/Console-Docs)
+* [Cascadia Code Font](https://github.com/Microsoft/Cascadia-Code)
 
-Download the Microsoft Terminal free from the Microsoft Store and it'll be continuously updated. Or, feel free to side-load [releases](https://github.com/microsoft/terminal/releases) from GitHub, but note they won't auto-update.
+## Installing and running Windows Terminal
 
-<a href='//www.microsoft.com/store/apps/9n0dx20hk701?cid=storebadge&ocid=badge'><img src='https://assets.windowsphone.com/85864462-9c82-451e-9355-a3d5f874397a/English_get-it-from-MS_InvariantCulture_Default.png' alt='English badge' width="284" height="104" style='width: 284px; height: 104px;'/></a>
+> 👉 Note: Windows Terminal requires Windows 10 1903 (build 18362) or later
 
-### Chocolatey (Unofficial)
+### Manually installing builds from this repository
 
-Download and upgrade the Windows Terminal from [Chocolatey](https://chocolatey.org).
+For users who are unable to install Terminal from the Microsoft Store, Terminal builds can be manually downloaded from this repository's [Releases page](https://github.com/microsoft/terminal/releases).
+
+> ⚠ Note: If you install Terminal manually:
+>
+> * Be sure to install the [Desktop Bridge VC++ v14 Redistributable Package](https://www.microsoft.com/en-us/download/details.aspx?id=53175) otherwise Terminal may not install and/or run and may crash at startup
+> * Terminal will not auto-update when new builds are released so you will need to regularly install the latest Terminal release to receive all the latest fixes and improvements!
+
+### Install via Chocolatey (unofficial)
+
+[Chocolatey](https://chocolatey.org) users can download and install the latest Terminal release by installing the `microsoft-windows-terminal` package:
 
-To install Windows Terminal, run the following command from the command line or from PowerShell:
 ```powershell
 choco install microsoft-windows-terminal
 ```
 
-To upgrade Windows Terminal, run the following command from the command line or from PowerShell:
+To upgrade Windows Terminal using Chocolatey, run the following:
+
 ```powershell
 choco upgrade microsoft-windows-terminal
 ```
 
-If you have any issues when installing/upgrading the package please go to the [package page](https://chocolatey.org/packages/microsoft-windows-terminal) and follow the [Chocolatey triage process](https://chocolatey.org/docs/package-triage-process)
+If you have any issues when installing/upgrading the package please go to the [Windows Terminal package page](https://chocolatey.org/packages/microsoft-windows-terminal) and follow the [Chocolatey triage process](https://chocolatey.org/docs/package-triage-process)
 
-### Build Status
+---
+
+## Project Build Status
 
 Project|Build Status
 ---|---
 Terminal|[![Build Status](https://dev.azure.com/ms/Terminal/_apis/build/status/Terminal%20CI?branchName=master)](https://dev.azure.com/ms/Terminal/_build?definitionId=136)
 ColorTool|![](https://microsoft.visualstudio.com/_apis/public/build/definitions/c93e867a-8815-43c1-92c4-e7dd5404f1e1/17023/badge)
 
-# Windows Terminal Project's Timeline
+---
 
-The plan for delivering Windows Terminal v1.0 [is described here](/doc/terminal-v1-timeline.md), and will be updated as the project proceeds.
+## Windows Terminal v1.0 Roadmap
 
-# Terminal & Console Overview
+The plan for delivering Windows Terminal v1.0 [is described here](/doc/terminal-v1-roadmap.md), and will be updated as the project proceeds.
+
+---
+
+## Terminal & Console Overview
 
 Please take a few minutes to review the overview below before diving into the code:
 
-## Windows Terminal
+### Windows Terminal
 
 Windows Terminal is a new, modern, feature-rich, productive terminal application for command-line users. It includes many of the features most frequently requested by the Windows command-line community including support for tabs, rich text, globalization, configurability, theming & styling, and more.
 
-The Terminal will also need to meet our goals and measures to ensure it remains fast, and efficient, and doesn't consume vast amounts of memory or power.
+The Terminal will also need to meet our goals and measures to ensure it remains fast and efficient, and doesn't consume vast amounts of memory or power.
 
-## The Windows console host
+### The Windows Console Host
 
-The Windows console host, `conhost.exe`, is Windows' original command-line user experience. It implements Windows' command-line infrastructure, and is responsible for hosting the Windows Console API, input engine, rendering engine, and user preferences. The console host code in this repository is the actual source from which the `conhost.exe` in Windows itself is built.
+The Windows Console host, `conhost.exe`, is Windows' original command-line user experience. It also hosts Windows' command-line infrastructure and the Windows Console API server, input engine, rendering engine, user preferences, etc. The console host code in this repository is the actual source from which the `conhost.exe` in Windows itself is built.
 
-Console's primary goal is to remain backwards-compatible with existing console subsystem applications.
+Since taking ownership of the Windows command-line in 2014, the team added several new features to the Console, including background transparency, line-based selection, support for [ANSI / Virtual Terminal sequences](https://en.wikipedia.org/wiki/ANSI_escape_code), [24-bit color](https://devblogs.microsoft.com/commandline/24-bit-color-in-the-windows-console/), a [Pseudoconsole ("ConPTY")](https://devblogs.microsoft.com/commandline/windows-command-line-introducing-the-windows-pseudo-console-conpty/), and more.
 
-Since assuming ownership of the Windows command-line in 2014, the team has added several new features to the Console, including window transparency, line-based selection, support for [ANSI / Virtual Terminal sequences](https://en.wikipedia.org/wiki/ANSI_escape_code), [24-bit color](https://devblogs.microsoft.com/commandline/24-bit-color-in-the-windows-console/), a [Pseudoconsole ("ConPTY")](https://devblogs.microsoft.com/commandline/windows-command-line-introducing-the-windows-pseudo-console-conpty/), and more.
-
-However, because the Console's primary goal is to maintain backward compatibility, we've been unable to add many of the features the community has been asking for, and which we've been wanting to add for the last several years--like tabs!
+However, because Windows Console's primary goal is to maintain backward compatibility, we have been unable to add many of the features the community (and the team) have been wanting for the last several years including tabs, unicode text, and emoji.
 
 These limitations led us to create the new Windows Terminal.
 
-## Shared Components
+> You can read more about the evolution of the command-line in general, and the Windows command-line specifically in [this accompanying series of blog posts](https://devblogs.microsoft.com/commandline/windows-command-line-backgrounder/) on the Command-Line team's blog.
 
-While overhauling the Console, we've modernized its codebase considerably. We've cleanly separated logical entities into modules and classes, introduced some key extensibility points, replaced several old, home-grown collections and containers with safer, more efficient [STL containers](https://docs.microsoft.com/en-us/cpp/standard-library/stl-containers?view=vs-2019), and made the code simpler and safer by using Microsoft's [WIL](https://github.com/Microsoft/wil) header library.
+### Shared Components
 
-This overhaul work resulted in the creation of several key components that would be useful for any terminal implementation on Windows, including a new DirectWrite-based text layout and rendering engine, a text buffer capable of storing both UTF-16 and UTF-8, and a VT parser/emitter.
+While overhauling Windows Console, we modernized its codebase considerably, cleanly separating logical entities into modules and classes, introduced some key extensibility points, replaced several old, home-grown collections and containers with safer, more efficient [STL containers](https://docs.microsoft.com/en-us/cpp/standard-library/stl-containers?view=vs-2019), and made the code simpler and safer by using Microsoft's [Windows Implementation Libraries - WIL](https://github.com/Microsoft/wil).
 
-## Building a new terminal
+This overhaul resulted in several of Console's key components being available for re-use in any terminal implementation on Windows. These components include a new DirectWrite-based text layout and rendering engine, a text buffer capable of storing both UTF-16 and UTF-8, a VT parser/emitter, and more.
 
-When we started building the new terminal application, we explored and evaluated several approaches and technology stacks. We ultimately decided that our goals would be best met by sticking with C++ and sharing the aforementioned modernized components, placing them atop the modern Windows application platform and UI framework.
+### Creating the new Windows Terminal
 
-Further, we realized that this would allow us to build the terminal's renderer and input stack as a reusable Windows UI control that others can incorporate into their applications.
+When we started planning the new Windows Terminal application, we explored and evaluated several approaches and technology stacks. We ultimately decided that our goals would be best met by continuing our investment in our C++ codebase, which would allow us to reuse several of the aforementioned modernized components in both the existing Console and the new Terminal. Further, we realized that this would allow us to build much of the Terminal's core itself as a reusable UI control that others can incorporate into their own applications.
 
-# FAQ
+The result of this work is contained within this repo and delivered as the Windows Terminal application you can download from the Microsoft Store, or [directly from this repo's releases](https://github.com/microsoft/terminal/releases).
 
-## Where can I download Windows Terminal?
+---
 
-The latest release of Windows Terminal can be downloaded from [this repo's Releases](https://github.com/microsoft/terminal/releases) page or [from the Microsoft Store](https://www.microsoft.com/en-us/p/windows-terminal-preview/9n0dx20hk701)
+## Resources
 
-## I built and ran the new Terminal, but I just get a blank window app!
+For more information about Windows Terminal, you may find some of these resources useful and interesting:
 
-Make sure you are building for your computer's architecture. If your box has a 64-bit Windows, change your Solution Platform to x64.  
-To check your OS architecture go to Settings -> System -> About (or Win+X -> System) and under `Device specifications` check for the  `System type`.
+* [Command-Line Blog](https://devblogs.microsoft.com/commandline)
+* [Command-Line Backgrounder Blog Series](https://devblogs.microsoft.com/commandline/windows-command-line-backgrounder/)
+* Windows Terminal Launch: [Terminal "Sizzle Video"](https://www.youtube.com/watch?v=8gw0rXPMMPE&list=PLEHMQNlPj-Jzh9DkNpqipDGCZZuOwrQwR&index=2&t=0s)
+* Windows Terminal Launch: [Build 2019 Session](https://www.youtube.com/watch?v=KMudkRcwjCw)
+* Run As Radio: [Show 645 - Windows Terminal with Richard Turner](http://www.runasradio.com/Shows/Show/645)
+* Azure Devops Podcast: [Episode 54 - Kayla Cinnamon and Rich Turner on DevOps on the Windows Terminal](http://azuredevopspodcast.clear-measure.com/kayla-cinnamon-and-rich-turner-on-devops-on-the-windows-terminal-team-episode-54)
+* Microsoft Ignite 2019 Session: [The Modern Windows Command Line: Windows Terminal - BRK3321](https://myignite.techcommunity.microsoft.com/sessions/81329?source=sessions)
 
-## I built and ran the new Terminal, but it looks just like the old console! What gives?
+---
 
-Firstly, make sure you're building & deploying `CascadiaPackage` in Visual Studio, _NOT_ `Host.EXE`. `OpenConsole.exe` is just `conhost.exe`, the same old console you know and love. `opencon.cmd` will launch `openconsole.exe`, and unfortunately, `openterm.cmd` is currently broken.
+## FAQ
 
-Secondly, try pressing <kbd>Ctrl</kbd> + <kbd>T</kbd>. The tabs are hidden when you only have one tab by default. In the future, the UI will be dramatically different, but for now, the defaults are _supposed_ to look like the console defaults.
+### I built and ran the new Terminal, but it looks just like the old console
 
-## I tried running WindowsTerminal.exe and it crashes!
+Cause: You're launching the incorrect solution in Visual Studio.
 
-* Don't try to run it unpackaged. Make sure to build & deploy `CascadiaPackage` from Visual Studio, and run the Windows Terminal (Dev Build) app.
-* Make sure you're on the right version of Windows. You'll need to be on Insider's builds, or wait for the 1903 release, as the Windows Terminal **REQUIRES** features from the latest Windows release.
+Solution: Make sure you're building & deploying the `CascadiaPackage` project in Visual Studio.
 
-# Getting Started
+> ⚠ Note: `OpenConsole.exe` is just a locally-built `conhost.exe`, the classic Windows Console that hosts Windows' command-line infrastructure. OpenConsole is used by Windows Terminal to connect to and communicate with command-line applications (via [ConPty](https://devblogs.microsoft.com/commandline/windows-command-line-introducing-the-windows-pseudo-console-conpty/)).
 
-## Debugging
+---
 
-* To debug in VS, right click on CascadiaPackage (from VS Solution Explorer) and go to properties, in the Debug menu, change "Application process" and "Background task process" to "Native Only".
+## Documentation
+
+All project documentation is located in the `./doc` folder. If you would like to contribute to the documentation, please submit a pull request.
+
+---
 
 ## Contributing
 
 We are excited to work alongside you, our amazing community, to build and enhance Windows Terminal\!
 
-We ask that **before you start work on a feature that you would like to contribute**, please read our [Contributor's Guide](https://github.com/microsoft/terminal/blob/master/doc/contributing.md). We will be happy to work with you to figure out the best approach, provide guidance and mentorship throughout feature development, and help avoid any wasted or duplicate effort.
-
-> 👉 **Remember\!** Your contributions may be incorporated into future versions of Windows\! Because of this, all pull requests will be subject to the same level of scrutiny for quality, coding standards, performance, globalization, accessibility, and compatibility as those of our internal contributors.
-
-> ⚠ **Note**: The Command-Line Team is actively working out of this repository and will be periodically re-structuring the code to make it easier to comprehend, navigate, build, test, and contribute to, so **DO expect significant changes to code layout on a regular basis**.
-
-## Documentation
-
-All documentation is located in the `./doc` folder. If you would like to contribute to the documentation, please submit a pull request.
+***BEFORE you start work on a feature/fix***, please read & follow our [Contributor's Guide](https://github.com/microsoft/terminal/blob/master/contributing.md) to help avoid any wasted or duplicate effort.
 
 ## Communicating with the Team
 
-The easiest way to communicate with the team is via GitHub issues. Please file new issues, feature requests and suggestions, but **DO search for similar open/closed pre-existing issues before you do**.
+The easiest way to communicate with the team is via GitHub issues.
 
-Please help us keep this repository clean, inclusive, and fun\! We will not tolerate any abusive, rude, disrespectful or inappropriate behavior. Read our [Code of Conduct](https://opensource.microsoft.com/codeofconduct/) for more details.
+Please file new issues, feature requests and suggestions, but **DO search for similar open/closed pre-existing issues before creating a new issue.**
 
 If you would like to ask a question that you feel doesn't warrant an issue (yet), please reach out to us via Twitter:
 
-  * Rich Turner, Program Manager: [@richturn\_ms](https://twitter.com/richturn_ms)
+* Kayla Cinnamon, Program Manager: [@cinnamon\_msft](https://twitter.com/cinnamon_msft)
+* Rich Turner, Program Manager: [@richturn\_ms](https://twitter.com/richturn_ms)
+* Dustin Howett, Engineering Lead: [@dhowett](https://twitter.com/DHowett)
+* Michael Niksa, Senior Developer: [@michaelniksa](https://twitter.com/MichaelNiksa)
+* Mike Griese, Developer: [@zadjii](https://twitter.com/zadjii)
+* Carlos Zamora, Developer: [@cazamor_msft](https://twitter.com/cazamor_msft)
+* Leon Liang, Developer: [@leonmsft](https://twitter.com/leonmsft)
 
-  * Dustin Howett, Engineering Lead: [@dhowett](https://twitter.com/DHowett)
-  
-  * Michael Niksa, Senior Developer: [@michaelniksa](https://twitter.com/MichaelNiksa)
+## Developer Guidance
 
-  * Kayla Cinnamon, Program Manager (especially for UX issues): [@cinnamon\_msft](https://twitter.com/cinnamon_msft)
-
-# Developer Guidance
-
-## Build Prerequisites
-
-* You must be running Windows 1903 (build >= 10.0.18362.0) or above in order to run Windows Terminal.
-* You must have the [1903 SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk) (build 10.0.18362.0) installed.
-* You must have at least [VS 2019](https://visualstudio.microsoft.com/downloads/) installed.
-* You must install the following Workloads via the VS Installer. Opening the solution will [prompt you to install missing components automatically](https://devblogs.microsoft.com/setup/configure-visual-studio-across-your-organization-with-vsconfig/).
-  - Desktop Development with C++
-  - Universal Windows Platform Development
-  - **The following Individual Components**
-     - C++ (v142) Universal Windows Platform Tools
-
-* You must also [enable Developer Mode in the Windows Settings app](https://docs.microsoft.com/en-us/windows/uwp/get-started/enable-your-device-for-development) to locally install and run the Terminal app.
+## Prerequisites
 
+* You must be running Windows 1903 (build >= 10.0.18362.0) or later to run Windows Terminal
+* You must [enable Developer Mode in the Windows Settings app](https://docs.microsoft.com/en-us/windows/uwp/get-started/enable-your-device-for-development) to locally install and run Windows Terminal
+* You must have the [Windows 10 1903 SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk) installed
+* You must have at least [VS 2019](https://visualstudio.microsoft.com/downloads/) installed
+* You must install the following Workloads via the VS Installer. Note: Opening the solution in VS 2019 will [prompt you to install missing components automatically](https://devblogs.microsoft.com/setup/configure-visual-studio-across-your-organization-with-vsconfig/):
+  * Desktop Development with C++
+  * Universal Windows Platform Development
+  * **The following Individual Components**
+    * C++ (v142) Universal Windows Platform Tools
 
 ## Building the Code
 
@@ -163,9 +171,9 @@ This repository uses [git submodules](https://git-scm.com/book/en/v2/Git-Tools-S
 git submodule update --init --recursive
 ```
 
-OpenConsole.sln may be built from within Visual Studio or from the command-line using MSBuild. To build from the command line, find your shell below.
+OpenConsole.sln may be built from within Visual Studio or from the command-line using a set of convenience scripts & tools in the **/tools** directory:
 
-### PowerShell
+### Building in PowerShell
 
 ```powershell
 Import-Module .\tools\OpenConsole.psm1
@@ -173,27 +181,35 @@ Set-MsBuildDevEnvironment
 Invoke-OpenConsoleBuild
 ```
 
-### CMD
+### Building in Cmd
 
 ```shell
 .\tools\razzle.cmd
 bcz
 ```
 
-We've provided a set of convenience scripts as well as [README](./tools/README.md) in the **/tools** directory to help automate the process of building and running tests.
+## Running & Debugging
 
-## Coding Guidance
+To debug the Windows Terminal in VS, right click on `CascadiaPackage` (in the Solution Explorer) and go to properties. In the Debug menu, change "Application process" and "Background task process" to "Native Only".
 
-Please review these brief docs below relating to our coding standards etc.
+You should then be able to build & debug the Terminal project by hitting <kbd>F5</kbd>.
 
-> 👉 If you find something missing from these docs, feel free to contribute to any of our documentation files anywhere in the repository (or make some new ones\!)
+> 👉 You will _not_ be able to launch the Terminal directly by running the WindowsTerminal.exe. For more details on why, see [#926](https://github.com/microsoft/terminal/issues/926), [#4043](https://github.com/microsoft/terminal/issues/4043)
+
+### Coding Guidance
+
+Please review these brief docs below about our coding practices.
+
+> 👉 If you find something missing from these docs, feel free to contribute to any of our documentation files anywhere in the repository (or write some new ones!)
 
 This is a work in progress as we learn what we'll need to provide people in order to be effective contributors to our project.
 
-  - [Coding Style](https://github.com/Microsoft/Terminal/blob/master/doc/STYLE.md)
-  - [Code Organization](https://github.com/Microsoft/Terminal/blob/master/doc/ORGANIZATION.md)
-  - [Exceptions in our legacy codebase](https://github.com/Microsoft/Terminal/blob/master/doc/EXCEPTIONS.md)
-  - [Helpful smart pointers and macros for interfacing with Windows in WIL](https://github.com/Microsoft/Terminal/blob/master/doc/WIL.md)
+* [Coding Style](https://github.com/Microsoft/Terminal/blob/master/doc/STYLE.md)
+* [Code Organization](https://github.com/Microsoft/Terminal/blob/master/doc/ORGANIZATION.md)
+* [Exceptions in our legacy codebase](https://github.com/Microsoft/Terminal/blob/master/doc/EXCEPTIONS.md)
+* [Helpful smart pointers and macros for interfacing with Windows in WIL](https://github.com/Microsoft/Terminal/blob/master/doc/WIL.md)
+
+---
 
 # Code of Conduct
 

SECURITY.md

@@ -12,7 +12,7 @@ If you believe you have found a security vulnerability in any Microsoft-owned re
 
 Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report).
 
-If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com).  If possible, encrypt your message with our PGP key; please download it from the the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/en-us/msrc/pgp-key-msrc).
+If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com).  If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/en-us/msrc/pgp-key-msrc).
 
 You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc). 
 

build/config/SignConfig.NuGet.xml

@@ -0,0 +1,5 @@
+<SignConfigXML>
+  <job platform="" configuration="" dest="__INPATHROOT__" jobname="EngFunSimpleSign" approvers="">
+   <file src="__INPATHROOT__\Microsoft.Terminal*.nupkg" signType="NuGet" /> 
+  </job>
+</SignConfigXML>

build/config/SignConfig.WindowsTerminal.xml

@@ -1,5 +1,6 @@
 <SignConfigXML>
   <job platform="" configuration="" certSubject="CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US" jobname="EngFunSimpleSign" approvers="">
    <file src="__INPATHROOT__\Microsoft.WindowsTerminal_8wekyb3d8bbwe.msixbundle" signType="136020001" dest="__OUTPATHROOT__\Microsoft.WindowsTerminal_8wekyb3d8bbwe.msixbundle" /> 
+   <file src="__INPATHROOT__\Microsoft.WindowsTerminalUniversal_8wekyb3d8bbwe.msixbundle" signType="136020001" dest="__OUTPATHROOT__\Microsoft.WindowsTerminalUniversal_8wekyb3d8bbwe.msixbundle" /> 
   </job>
 </SignConfigXML>

build/pipelines/templates/build-console-steps.yml

@@ -42,7 +42,7 @@ steps:
     vsVersion: 16.0
     platform: '$(BuildPlatform)'
     configuration: '$(BuildConfiguration)'
-    msbuildArgs: ${{ parameters.additionalBuildArguments }}
+    msbuildArgs: "${{ parameters.additionalBuildArguments }}"
     clean: true
     maximumCpuCount: true
 
@@ -54,6 +54,14 @@ steps:
       $Package = Get-ChildItem -Recurse -Filter "CascadiaPackage_*.msix"
       .\build\scripts\Test-WindowsTerminalPackage.ps1 -Verbose -Path $Package.FullName
 
+- task: powershell@2
+  displayName: 'Source Index PDBs'
+  inputs:
+    targetType: filePath
+    filePath: build\scripts\Index-Pdbs.ps1
+    arguments: -SearchDir '$(Build.SourcesDirectory)' -SourceRoot '$(Build.SourcesDirectory)' -recursive -Verbose -CommitId $(Build.SourceVersion)
+    errorActionPreference: silentlyContinue
+
 - task: VSTest@2
   displayName: 'Run Unit Tests'
   inputs:

build/rules/GenerateSxsManifestsFromWinmds.targets

@@ -10,7 +10,7 @@
   <Target Name="_ConsoleMapWinmdsToManifestFiles" DependsOnTargets="ResolveAssemblyReferences">
     <ItemGroup>
       <!-- For each non-system .winmd file in References, generate a .manifest in IntDir for it. -->
-      <_ConsoleWinmdManifest Include="@(ReferencePath->'$(IntDir)\%(FileName).manifest')" Condition="'%(ReferencePath.IsSystemReference)' != 'true' and '%(ReferencePath.WinMDFile)' == 'true' and '%(ReferencePath.ReferenceSourceTarget)' == 'ResolveAssemblyReference'">
+      <_ConsoleWinmdManifest Include="@(ReferencePath->'$(IntDir)\%(FileName).manifest')" Condition="'%(ReferencePath.IsSystemReference)' != 'true' and '%(ReferencePath.WinMDFile)' == 'true' and '%(ReferencePath.ReferenceSourceTarget)' == 'ResolveAssemblyReference' and '%(ReferencePath.Implementation)' != ''">
         <WinMDPath>%(ReferencePath.FullPath)</WinMDPath>
         <Implementation>%(ReferencePath.Implementation)</Implementation>
       </_ConsoleWinmdManifest>

build/scripts/Index-Pdbs.ps1

@@ -0,0 +1,85 @@
+[CmdLetBinding()]
+Param(
+    [Parameter(Mandatory=$true, Position=0)][string]$SearchDir,
+    [Parameter(Mandatory=$true, Position=1)][string]$SourceRoot,
+    [Parameter(Mandatory=$true, Position=2)][string]$CommitId,
+    [string]$Organization = "microsoft",
+    [string]$Repo = "terminal",
+    [switch]$recursive
+)
+
+$debuggerPath = (Get-ItemProperty -path "HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows Kits\Installed Roots" -name WindowsDebuggersRoot10).WindowsDebuggersRoot10
+$srcsrvPath = Join-Path $debuggerPath "x64\srcsrv"
+$srctoolExe = Join-Path $srcsrvPath "srctool.exe"
+$pdbstrExe = Join-Path $srcsrvPath "pdbstr.exe"
+
+$fileTable = @{}
+foreach ($gitFile in & git ls-files)
+{
+    $fileTable[$gitFile] = $gitFile
+}
+
+$mappedFiles = New-Object System.Collections.ArrayList
+
+foreach ($file in (Get-ChildItem -r:$recursive "$SearchDir\*.pdb"))
+{
+    Write-Verbose "Found $file"
+
+    $ErrorActionPreference = "Continue" # Azure Pipelines defaults to "Stop", continue past errors in this script.
+    
+    $allFiles = & $srctoolExe -r "$file"
+
+    # If the pdb didn't have enough files then skip it (the srctool output has a blank line even when there's no info
+    # so check for less than 2 lines)
+    if ($allFiles.Length -lt 2)
+    {
+        continue
+    }
+
+    for ($i = 0; $i -lt $allFiles.Length; $i++)
+    {
+        if ($allFiles[$i].StartsWith($SourceRoot, [StringComparison]::OrdinalIgnoreCase))
+        {
+            $relative = $allFiles[$i].Substring($SourceRoot.Length).TrimStart("\")
+            $relative = $relative.Replace("\", "/")
+
+            # Git urls are case-sensitive but the PDB might contain a lowercased version of the file path.
+            # Look up the relative url in the output of "ls-files". If it's not there then it's not something
+            # in git, so don't index it.
+            $relative = $fileTable[$relative]
+            if ($relative)
+            {
+                $mapping = $allFiles[$i] + "*$relative"
+                $mappedFiles.Add($mapping)
+
+                Write-Verbose "Mapped path $($i): $mapping"
+            }
+        }
+    }
+
+    $pdbstrFile = Join-Path "$env:TEMP" "pdbstr.txt"
+
+    Write-Verbose "pdbstr.txt = $pdbstrFile"
+
+    @"
+SRCSRV: ini ------------------------------------------------
+VERSION=2
+VERCTRL=http
+SRCSRV: variables ------------------------------------------
+ORGANIZATION=$Organization
+REPO=$Repo
+COMMITID=$CommitId
+HTTP_ALIAS=https://raw.githubusercontent.com/%ORGANIZATION%/%REPO%/%COMMITID%/
+HTTP_EXTRACT_TARGET=%HTTP_ALIAS%%var2%
+SRCSRVTRG=%HTTP_EXTRACT_TARGET%
+SRC_INDEX=public
+SRCSRV: source files ---------------------------------------
+$($mappedFiles -join "`r`n")
+SRCSRV: end ------------------------------------------------
+"@ | Set-Content $pdbstrFile
+
+    & $pdbstrExe -p:"$file" -w -s:srcsrv -i:$pdbstrFile
+}
+
+# Return with exit 0 to override any weird error code from other tools
+Exit 0

build/scripts/Test-WindowsTerminalPackage.ps1

@@ -75,13 +75,11 @@ Try {
         Throw "Failed to find App.xbf (TerminalApp project) in resources.pri"
     }
 
-    If ($Manifest.Package.Identity.ProcessorArchitecture -Ne "arm64") {
-        ### ARM64 doesn't package cpprest_2_10.
-        If (($null -eq (Get-Item "$AppxPackageRootPath\cpprest_2_10.dll" -EA:Ignore)) -And
-            ($null -eq (Get-Item "$AppxPackageRootPath\cpprest_2_10d.dll" -EA:Ignore))) {
-            Throw "Failed to find cpprest_2_10.dll -- check the WAP packaging project"
-        }
+    If (($null -eq (Get-Item "$AppxPackageRootPath\cpprest142_2_10.dll" -EA:Ignore)) -And
+        ($null -eq (Get-Item "$AppxPackageRootPath\cpprest142_2_10d.dll" -EA:Ignore))) {
+        Throw "Failed to find cpprest142_2_10.dll -- check the WAP packaging project"
     }
+
 } Finally {
     Remove-Item -Recurse -Force $AppxPackageRootPath
 }

contributing.md

@@ -21,6 +21,9 @@ We drive the bot by tagging issues with specific labels which cause the bot engi
 Therefore, if you do file issues, or create PRs, please keep an eye on your GitHub notifications. If you do not respond to requests for information, your issues/PRs may be closed automatically.
 
 ---
+## Reporting Security Issues
+
+**Please do not report security vulnerabilities through public GitHub issues.** Instead, please report them to the Microsoft Security Response Center (MSRC). See [Security.md](../SECURITY.md) for more information.
 
 ## Before you start, file an issue
 

custom.props

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <!-- This file is read by XES, which we use in our Release builds. -->
+  <PropertyGroup Label="Version">
+    <XesUseOneStoreVersioning>true</XesUseOneStoreVersioning>
+    <XesBaseYearForStoreVersion>2019</XesBaseYearForStoreVersion>
+    <VersionMajor>0</VersionMajor>
+    <VersionMinor>8</VersionMinor>
+    <VersionInfoProductName>Windows Terminal</VersionInfoProductName>
+  </PropertyGroup>
+</Project>

doc/ORGANIZATION.md

@@ -24,6 +24,16 @@
 * `/ipch` – not checked in is where intellisense data will be generated if you use Visual Studio 2015
 * `/obj` – not checked in is where objects will be generated by the MSBuild system
 * `/src` – This is the fun one. In the root is common build system data.
+	* `/src/cascadia` - This directory contains all the code specific to the Windows Terminal
+		* `/src/cascadia/TerminalConnection` - This DLL is responsible for the various different ways a terminal instance can communicate with different terminal backends. Examples include the `ConptyConnection` (for communicating with Windows Console processes), or the `AzureCloudShellConnection` for communicating with Azure.
+		* `/src/cascadia/TerminalSettings` - This is the DLL responsible for abstracting the settings for both the TerminalCore and the TerminalControl. This provides consumers of the TerminalControl a common interface for supplying settings to the Terminal.
+		* `/src/cascadia/TerminalCore` - This LIB is responsible for the core implementation of a terminal instance. This defines one important class `Terminal` which is a complete terminal instance, with buffer, colors table, VT parsing, input handling, etc. It does _not_ prescribe any sort of UI implementation - it should be connected to code that can handle rendering its contents, and provide input to it.
+		* `/src/cascadia/TerminalControl` - This DLL provides the UWP-XAML implementation of a `TermControl`, which can be embedded within an application to provide a terminal instance within the application. It contains a DX renderer for drawing text to the screen, and translates input to send to the core Terminal. It also recieves settings to apply to both itself and the core Terminal.
+		* `/src/cascadia/TerminalApp` - This DLL represents the implementation of the Windows Terminal application. This includes parsing settings, hosting tabs & panes with Terminals in them, and displaying other UI elements. This DLL is almost entirely UWP-like code, and shouldn't be doing any Win32-like UI work.
+		* `/src/cascadia/WindowsTerminal` - This EXE provides Win32 hosting for the TerminalApp. It will set up XAML islands, and is responsible for drawing the window, either as a standard window or with content in the titlebar (non-client area).
+		* `/src/cascadia/CasadiaPackage` - This is a project for packaging the Windows Terminal and its dependencies into an .appx/.msix for deploying to the machine.
+		* `/src/cascadia/PublicTerminalCore` - This is a DLL wrapper for the TerminalCore and Renderer, similar to `TermControl`, which exposes some exported functions that so the Terminal can be used from C#.
+		* `/src/cascadia/WpfTerminalControl` - A DLL implementing a WPF version of the Terminal Control.
 	* `/src/host` – The meat of the windows console host. This includes buffer, input, output, windowing, server management, clipboard, and most interactions with the console host window that aren’t stated anywhere else. We’re trying to pull things out that are reusable into other libraries, but it’s a work in progress
 		* `/src/host/lib` – Builds the reusable LIB copy of the host
 		* `/src/host/dll` – Packages LIB into conhostv2.dll to be put into the OS C:\windows\system32\
@@ -42,7 +52,7 @@
 		* `/src/renderer/base` – Base interface layer providing non-engine-specific rendering things like choosing the data from the console buffer, deciding how to lay out or transform that data, then dispatching commands to a specific final display engine
 		* `/src/renderer/gdi` – The GDI implementation of rendering to the screen. Takes commands to “draw a line” or “fill the background” or “select a region” from the base and turns them into GDI calls to the screen. Extracted from original console host code.
 		* `/src/renderer/inc` – Interface definitions for all renderer communication
-	* `/src/terminal` – Virtual terminal support for the console. This is the sequences that are found in-band with other text on STDIN/STDOUT that command the display to do things. This is the *nix way of controlling a console.
+	* `/src/terminal` – Virtual terminal support for the console. This is the sequences that are found in-band with other text on STDIN/STDOUT that command the display to do things. This is the \*nix way of controlling a console.
 		* `/src/terminal/parser` – This contains a state machine and sorting engine for feeding in individual characters from STDOUT or STDIN and decoding them into the appropriate verbs that should be performed
 		* `/src/terminal/adapter` – This converts the verbs from the interface into calls on the console API. It doesn’t actually call through the API (for performance reasons since it lives inside the same binary), but it tries to remain as close to an API call as possible. There are some private extensions to the API for behaviors that didn’t exist before this was written that we’ve not made public. We don’t know if we will yet or force people to use VT to get at them.
 	* `/src/tsf` – Text Services Foundation. This provides IME input services to the console. This was historically used for only Chinese, Japanese, and Korean IMEs specifically on OS installations with those as the primary language. It was in the summer of 2016 unrestricted to be able to be used on any OS installation with any IME (whether or not it will display correctly is a different story). It also was unrestricted to allow things like Pen and Touch input (which are routed via IME messages) to display properly inside the console from the TabTip window (the little popup that helps you insert pen/touch writing/keyboard candidates into an application)
@@ -90,7 +100,7 @@
 * Assorted utilities and stuff
 	* `Misc.cpp` (left for us by previous eras of random console devs)
 	* `Util.cpp` (created in our era)
-* Custom zeroing and non-throwing allocator 
+* Custom zeroing and non-throwing allocator
 	* `Newdelete.cpp`
 * Related to inserting text into the TextInfo buffer
 	* `Output.cpp`

doc/cascadia/SettingsSchema.md

@@ -1,181 +1,197 @@
-# Profiles.json Documentation
-
-## Globals
-Properties listed below affect the entire window, regardless of the profile settings.
-
-| Property | Necessity | Type | Default | Description |
-| -------- | --------- | ---- | ------- | ----------- |
-| `alwaysShowTabs` | _Required_ | Boolean | `true` | When set to `true`, tabs are always displayed. When set to `false` and `showTabsInTitlebar` is set to `false`, tabs only appear after typing <kbd>Ctrl</kbd> + <kbd>T</kbd>. |
-| `copyOnSelect` | Optional | Boolean | `false` | When set to `true`, a selection is immediately copied to your clipboard upon creation. When set to `false`, the selection persists and awaits further action. |
-| `defaultProfile` | _Required_ | String | PowerShell guid | Sets the default profile. Opens by typing <kbd>Ctrl</kbd> + <kbd>T</kbd> or by clicking the '+' icon. The guid of the desired default profile is used as the value. |
-| `initialCols` | _Required_ | Integer | `120` | The number of columns displayed in the window upon first load. |
-| `initialRows` | _Required_ | Integer | `30` | The number of rows displayed in the window upon first load. |
-| `requestedTheme` | _Required_ | String | `system` | Sets the theme of the application. Possible values: `"light"`, `"dark"`, `"system"` |
-| `showTerminalTitleInTitlebar` | _Required_ | Boolean | `true` | When set to `true`, titlebar displays the title of the selected tab. When set to `false`, titlebar displays "Windows Terminal". |
-| `showTabsInTitlebar` | Optional | Boolean | `true` | When set to `true`, the tabs are moved into the titlebar and the titlebar disappears. When set to `false`, the titlebar sits above the tabs. |
-| `wordDelimiters` | Optional | String | <code>&nbsp;&#x2f;&#x5c;&#x28;&#x29;&#x22;&#x27;&#x2d;&#x3a;&#x2c;&#x2e;&#x3b;&#x3c;&#x3e;&#x7e;&#x21;&#x40;&#x23;&#x24;&#x25;&#x5e;&#x26;&#x2a;&#x7c;&#x2b;&#x3d;&#x5b;&#x5d;&#x7b;&#x7d;&#x7e;&#x3f;│</code><br>_(`│` is `U+2502 BOX DRAWINGS LIGHT VERTICAL`)_ | Determines the delimiters used in a double click selection. |
-
-## Profiles
-Properties listed below are specific to each unique profile.
-
-| Property | Necessity | Type | Default | Description |
-| -------- | --------- | ---- | ------- | ----------- |
-| `acrylicOpacity` | _Required_ | Number | `0.5` | When `useAcrylic` is set to `true`, it sets the transparency of the window for the profile. Accepts floating point values from 0-1. |
-| `closeOnExit` | _Required_ | Boolean | `true` | When set to `true`, the selected tab closes when `exit` is typed. When set to `false`, the tab will remain open when `exit` is typed. |
-| `colorScheme` | _Required_ | String | `Campbell` | Name of the terminal color scheme to use. Color schemes are defined under `schemes`. |
-| `commandline` | _Required_ | String | `powershell.exe` | Executable used in the profile. |
-| `cursorColor` | _Required_ | String | `#FFFFFF` | Sets the cursor color for the profile. Uses hex color format: `"#rrggbb"`. |
-| `cursorShape` | _Required_ | String | `bar` | Sets the cursor shape for the profile. Possible values: `"vintage"` ( &#x2583; ), `"bar"` ( &#x2503; ), `"underscore"` ( &#x2581; ), `"filledBox"` ( &#x2588; ), `"emptyBox"` ( &#x25AF; ) |
-| `fontFace` | _Required_ | String | `Consolas` | Name of the font face used in the profile. We will try to fallback to Consolas if this can't be found or is invalid. |
-| `fontSize` | _Required_ | Integer | `12` | Sets the font size. |
-| `guid` | _Required_ | String | | Unique identifier of the profile. Written in registry format: `"{00000000-0000-0000-0000-000000000000}"`. |
-| `hidden` | Optional | Boolean | `false` | If set to true, the profile will not appear in the list of profiles. This can be used to hide default profiles and dynamicially generated profiles, while leaving them in your settings file. |
-| `historySize` | _Required_ | Integer | `9001` | The number of lines above the ones displayed in the window you can scroll back to. |
-| `name` | _Required_ | String | `PowerShell Core` | Name of the profile. Displays in the dropdown menu. <br>Additionally, this value will be used as the "title" to pass to the shell on startup. Some shells (like `bash`) may choose to ignore this initial value, while others (`cmd`, `powershell`) may use this value over the lifetime of the application. This "title" behavior can be overriden by using `tabTitle`. |
-| `padding` | _Required_ | String | `8, 8, 8, 8` | Sets the padding around the text within the window. Can have three different formats: `"#"` sets the same padding for all sides, `"#, #"` sets the same padding for left-right and top-bottom, and `"#, #, #, #"` sets the padding individually for left, top, right, and bottom. |
-| `snapOnInput` | _Required_ | Boolean | `true` | When set to `true`, the window will scroll to the command input line when typing. When set to `false`, the window will not scroll when you start typing. |
-| `startingDirectory` | _Required_ | String | `%USERPROFILE%` | The directory the shell starts in when it is loaded. This path must be formatted as a Windows path.|
-| `useAcrylic` | _Required_ | Boolean | `false` | When set to `true`, the window will have an acrylic background. When set to `false`, the window will have a plain, untextured background. |
-| `background` | Optional | String | | Sets the background color of the profile. Overrides `background` set in color scheme if `colorscheme` is set. Uses hex color format: `"#rrggbb"`. |
-| `backgroundImage` | Optional | String | | Sets the file location of the Image to draw over the window background. |
-| `backgroundImageAlignment` | Optional | String | `center` | Sets how the background image aligns to the boundaries of the window. Possible values: `"center"`, `"left"`, `"top"`, `"right"`, `"bottom"`, `"topLeft"`, `"topRight"`, `"bottomLeft"`, `"bottomRight"` |
-| `backgroundImageOpacity` | Optional | Number | `1.0` | Sets the transparency of the background image. Accepts floating point values from 0-1. |
-| `backgroundImageStretchMode` | Optional | String | `uniformToFill` | Sets how the background image is resized to fill the window. Possible values: `"none"`, `"fill"`, `"uniform"`, `"uniformToFill"` |
-| `colorTable` | Optional | Array[String] | | Array of colors used in the profile if `colorscheme` is not set. Colors use hex color format: `"#rrggbb"`. Ordering is as follows: `[black, red, green, yellow, blue, magenta, cyan, white, bright black, bright red, bright green, bright yellow, bright blue, bright magenta, bright cyan, bright white]` |
-| `cursorHeight` | Optional | Integer | | Sets the percentage height of the cursor starting from the bottom. Only works when `cursorShape` is set to `"vintage"`. Accepts values from 25-100. |
-| `foreground` | Optional | String | | Sets the foreground color of the profile. Overrides `foreground` set in color scheme if `colorscheme` is set. Uses hex color format: `"#rrggbb"`. |
-| `icon` | Optional | String | | Image file location of the icon used in the profile. Displays within the tab and the dropdown menu. See [Background Images and Icons](./SettingsSchema.md#background-images-and-icons) below for help on specifying your own icons |
-| `scrollbarState` | Optional | String | | Defines the visibility of the scrollbar. Possible values: `"visible"`, `"hidden"` |
-| `tabTitle` | Optional | String | | If set, will replace the `name` as the title to pass to the shell on startup. Some shells (like `bash`) may choose to ignore this initial value, while others (`cmd`, `powershell`) may use this value over the lifetime of the application.  |
-
-## Schemes
-Properties listed below are specific to each color scheme. [ColorTool](https://github.com/microsoft/terminal/tree/master/src/tools/ColorTool) is a great tool you can use to create and explore new color schemes. All colors use hex color format.
-
-| Property | Necessity | Type | Description |
-| -------- | ---- | ----------- | ----------- |
-| `name` | _Required_ | String | Name of the color scheme. |
-| `foreground` | _Required_ | String | Sets the foreground color of the color scheme. |
-| `background` | _Required_ | String | Sets the background color of the color scheme. |
-| `black` | _Required_ | String | Sets the color used as ANSI black. |
-| `blue` | _Required_ | String | Sets the color used as ANSI blue. |
-| `brightBlack` | _Required_ | String | Sets the color used as ANSI bright black. |
-| `brightBlue` | _Required_ | String | Sets the color used as ANSI bright blue. |
-| `brightCyan` | _Required_ | String | Sets the color used as ANSI bright cyan. |
-| `brightGreen` | _Required_ | String | Sets the color used as ANSI bright green. |
-| `brightPurple` | _Required_ | String | Sets the color used as ANSI bright purple. |
-| `brightRed` | _Required_ | String | Sets the color used as ANSI bright red. |
-| `brightWhite` | _Required_ | String | Sets the color used as ANSI bright white. |
-| `brightYellow` | _Required_ | String | Sets the color used as ANSI bright yellow. |
-| `cyan` | _Required_ | String | Sets the color used as ANSI cyan. |
-| `green` | _Required_ | String | Sets the color used as ANSI green. |
-| `purple` | _Required_ | String | Sets the color used as ANSI purple. |
-| `red` | _Required_ | String | Sets the color used as ANSI red. |
-| `white` | _Required_ | String | Sets the color used as ANSI white. |
-| `yellow` | _Required_ | String | Sets the color used as ANSI yellow. |
-
-## Keybindings
-Properties listed below are specific to each custom key binding.
-
-| Property | Necessity | Type | Description |
-| -------- | ---- | ----------- | ----------- |
-| `command` | _Required_ | String | The command executed when the associated key bindings are pressed. |
-| `keys` | _Required_ | Array[String] | Defines the key combinations used to call the command. |
-
-### Implemented Keybindings
-
-Bindings listed below are per the implementation in `src/cascadia/TerminalApp/AppKeyBindingsSerialization.cpp`
-
-- copy
-- copyTextWithoutNewlines
-- paste
-- newTab
-- openNewTabDropdown
-- duplicateTab
-- newTabProfile0
-- newTabProfile1
-- newTabProfile2
-- newTabProfile3
-- newTabProfile4
-- newTabProfile5
-- newTabProfile6
-- newTabProfile7
-- newTabProfile8
-- newWindow
-- closeWindow
-- closeTab
-- closePane
-- switchToTab
-- nextTab
-- prevTab
-- increaseFontSize
-- decreaseFontSize
-- scrollUp
-- scrollDown
-- scrollUpPage
-- scrollDownPage
-- switchToTab0
-- switchToTab1
-- switchToTab2
-- switchToTab3
-- switchToTab4
-- switchToTab5
-- switchToTab6
-- switchToTab7
-- switchToTab8
-- openSettings
-- splitHorizontal
-- splitVertical
-- resizePaneLeft
-- resizePaneRight
-- resizePaneUp
-- resizePaneDown
-- moveFocusLeft
-- moveFocusRight
-- moveFocusUp
-- moveFocusDown
-
-## Background Images and Icons
-Some Terminal settings allow you to specify custom background images and icons. It is recommended that custom images and icons are stored in system-provided folders and are referred to using the correct [URI Schemes](https://docs.microsoft.com/en-us/windows/uwp/app-resources/uri-schemes). URI Schemes provide a way to reference files independent of their physical paths (which may change in the future).
-
-The most useful URI schemes to remember when customizing background images and icons are:
-
-| URI Scheme | Corresponding Physical Path | Use / description |
-| --- | --- | ---|
-| `ms-appdata:///Local/` | `%localappdata%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\` | Per-machine files |
-| `ms-appdata:///Roaming/` | `%localappdata%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\RoamingState\` | Common files |
-
-> ⚠ Note: Do not rely on file references using the `ms-appx` URI Scheme (i.e. icons). These files are considered an internal implementation detail and may change name/location or may be omitted in the future.
-
-### Icons
-Terminal displays icons for each of your profiles which Terminal generates for any built-in shells - PowerShell Core, PowerShell, and any installed Linux/WSL distros. Each profile refers to a stock icon via the `ms-appx` URI Scheme.
-
-> ⚠ Note: Do not rely on the files referenced by the `ms-appx` URI Scheme - they are considered an internal implementation detail and may change name/location or may be omitted in the future.
-
-You can refer to you own icons if you wish, e.g.:
-
-```json
-    "icon" : "C:\\Users\\richturn\\OneDrive\\WindowsTerminal\\icon-ubuntu-32.png",
-```
-
-> 👉 Tip: Icons should be sized to 32x32px in an appropriate raster image format (e.g. .PNG, .GIF, or .ICO) to avoid having to scale your icons during runtime (causing a noticeable delay and loss of quality.)
-
-### Custom Background Images
-You can apply a background image to each of your profiles, allowing you to configure/brand/style each of your profiles independently from one another if you wish.
-
-To do so, specify your preferred `backgroundImage`, position it using `backgroundImageAlignment`, set its opacity with `backgroundImageOpacity`, and/or specify how your image fill the available space using `backgroundImageStretchMode`.
-
-For example:
-```json
-    "backgroundImage": "C:\\Users\\richturn\\OneDrive\\WindowsTerminal\\bg-ubuntu-256.png",
-    "backgroundImageAlignment": "bottomRight",
-    "backgroundImageOpacity": 0.1,
-    "backgroundImageStretchMode": "none"
-```
-
-> 👉 Tip: You can easily roam your collection of images and icons across all your machines by storing your icons and images in OneDrive (as shown above).
-
-With these settings, your Terminal's Ubuntu profile would look similar to this:
-
-![Custom icon and background image](../images/custom-icon-and-background-image.jpg)
-
-
+# Profiles.json Documentation
+
+## Globals
+Properties listed below affect the entire window, regardless of the profile settings.
+
+| Property | Necessity | Type | Default | Description |
+| -------- | --------- | ---- | ------- | ----------- |
+| `alwaysShowTabs` | _Required_ | Boolean | `true` | When set to `true`, tabs are always displayed. When set to `false` and `showTabsInTitlebar` is set to `false`, tabs only appear after typing <kbd>Ctrl</kbd> + <kbd>T</kbd>. |
+| `copyOnSelect` | Optional | Boolean | `false` | When set to `true`, a selection is immediately copied to your clipboard upon creation. When set to `false`, the selection persists and awaits further action. |
+| `defaultProfile` | _Required_ | String | PowerShell guid | Sets the default profile. Opens by typing <kbd>Ctrl</kbd> + <kbd>T</kbd> or by clicking the '+' icon. The guid of the desired default profile is used as the value. |
+| `initialCols` | _Required_ | Integer | `120` | The number of columns displayed in the window upon first load. |
+| `initialRows` | _Required_ | Integer | `30` | The number of rows displayed in the window upon first load. |
+| `rowsToScroll` | Optional | Integer | `system` | The number of rows to scroll at a time with the mouse wheel. This will override the system setting if the value is not zero or "system". |
+| `requestedTheme` | _Required_ | String | `system` | Sets the theme of the application. Possible values: `"light"`, `"dark"`, `"system"` |
+| `showTerminalTitleInTitlebar` | _Required_ | Boolean | `true` | When set to `true`, titlebar displays the title of the selected tab. When set to `false`, titlebar displays "Windows Terminal". |
+| `showTabsInTitlebar` | Optional | Boolean | `true` | When set to `true`, the tabs are moved into the titlebar and the titlebar disappears. When set to `false`, the titlebar sits above the tabs. |
+| `snapToGridOnResize` | Optional | Boolean | `false` | When set to `true`, the window will snap to the nearest character boundary on resize. When `false`, the window will resize "smoothly" |
+| `tabWidthMode` | Optional | String | `equal` | Sets the width of the tabs. Possible values: `"equal"`, `"titleLength"` |
+| `wordDelimiters` | Optional | String | <code>&nbsp;&#x2f;&#x5c;&#x28;&#x29;&#x22;&#x27;&#x2d;&#x3a;&#x2c;&#x2e;&#x3b;&#x3c;&#x3e;&#x7e;&#x21;&#x40;&#x23;&#x24;&#x25;&#x5e;&#x26;&#x2a;&#x7c;&#x2b;&#x3d;&#x5b;&#x5d;&#x7b;&#x7d;&#x7e;&#x3f;│</code><br>_(`│` is `U+2502 BOX DRAWINGS LIGHT VERTICAL`)_ | Determines the delimiters used in a double click selection. |
+
+## Profiles
+Properties listed below are specific to each unique profile.
+
+| Property | Necessity | Type | Default | Description |
+| -------- | --------- | ---- | ------- | ----------- |
+| `guid` | _Required_ | String | | Unique identifier of the profile. Written in registry format: `"{00000000-0000-0000-0000-000000000000}"`. |
+| `name` | _Required_ | String | | Name of the profile. Displays in the dropdown menu. <br>Additionally, this value will be used as the "title" to pass to the shell on startup. Some shells (like `bash`) may choose to ignore this initial value, while others (`cmd`, `powershell`) may use this value over the lifetime of the application. This "title" behavior can be overriden by using `tabTitle`. |
+| `acrylicOpacity` | Optional | Number | `0.5` | When `useAcrylic` is set to `true`, it sets the transparency of the window for the profile. Accepts floating point values from 0-1. |
+| `background` | Optional | String | | Sets the background color of the profile. Overrides `background` set in color scheme if `colorscheme` is set. Uses hex color format: `"#rrggbb"`. |
+| `backgroundImage` | Optional | String | | Sets the file location of the Image to draw over the window background. |
+| `backgroundImageAlignment` | Optional | String | `center` | Sets how the background image aligns to the boundaries of the window. Possible values: `"center"`, `"left"`, `"top"`, `"right"`, `"bottom"`, `"topLeft"`, `"topRight"`, `"bottomLeft"`, `"bottomRight"` |
+| `backgroundImageOpacity` | Optional | Number | `1.0` | Sets the transparency of the background image. Accepts floating point values from 0-1. |
+| `backgroundImageStretchMode` | Optional | String | `uniformToFill` | Sets how the background image is resized to fill the window. Possible values: `"none"`, `"fill"`, `"uniform"`, `"uniformToFill"` |
+| `closeOnExit` | Optional | String | `graceful` | Sets how the profile reacts to termination or failure to launch. Possible values: `"graceful"` (close when `exit` is typed or the process exits normally), `"always"` (always close) and `"never"` (never close). `true` and `false` are accepted as synonyms for `"graceful"` and `"never"` respectively. |
+| `colorScheme` | Optional | String | `Campbell` | Name of the terminal color scheme to use. Color schemes are defined under `schemes`. |
+| `colorTable` | Optional | Array[String] | | Array of colors used in the profile if `colorscheme` is not set. Array follows the format defined in `schemes`. |
+| `commandline` | Optional | String | | Executable used in the profile. |
+| `cursorColor` | Optional | String | `#FFFFFF` | Sets the cursor color for the profile. Uses hex color format: `"#rrggbb"`. |
+| `cursorHeight` | Optional | Integer | | Sets the percentage height of the cursor starting from the bottom. Only works when `cursorShape` is set to `"vintage"`. Accepts values from 25-100. |
+| `cursorShape` | Optional | String | `bar` | Sets the cursor shape for the profile. Possible values: `"vintage"` ( &#x2583; ), `"bar"` ( &#x2503; ), `"underscore"` ( &#x2581; ), `"filledBox"` ( &#x2588; ), `"emptyBox"` ( &#x25AF; ) |
+| `fontFace` | Optional | String | `Consolas` | Name of the font face used in the profile. We will try to fallback to Consolas if this can't be found or is invalid. |
+| `fontSize` | Optional | Integer | `12` | Sets the font size. |
+| `foreground` | Optional | String | | Sets the foreground color of the profile. Overrides `foreground` set in color scheme if `colorscheme` is set. Uses hex color format: `#rgb` or `"#rrggbb"`. |
+| `hidden` | Optional | Boolean | `false` | If set to true, the profile will not appear in the list of profiles. This can be used to hide default profiles and dynamicially generated profiles, while leaving them in your settings file. |
+| `historySize` | Optional | Integer | `9001` | The number of lines above the ones displayed in the window you can scroll back to. |
+| `icon` | Optional | String | | Image file location of the icon used in the profile. Displays within the tab and the dropdown menu. |
+| `padding` | Optional | String | `8, 8, 8, 8` | Sets the padding around the text within the window. Can have three different formats: `"#"` sets the same padding for all sides, `"#, #"` sets the same padding for left-right and top-bottom, and `"#, #, #, #"` sets the padding individually for left, top, right, and bottom. |
+| `scrollbarState` | Optional | String | | Defines the visibility of the scrollbar. Possible values: `"visible"`, `"hidden"` |
+| `selectionBackground` | Optional | String | | Sets the selection background color of the profile. Overrides `selectionBackground` set in color scheme if `colorscheme` is set. Uses hex color format: `"#rrggbb"`. |
+| `snapOnInput` | Optional | Boolean | `true` | When set to `true`, the window will scroll to the command input line when typing. When set to `false`, the window will not scroll when you start typing. |
+| `source` | Optional | String | | Stores the name of the profile generator that originated this profile. _There are no discoverable values for this field._ |
+| `startingDirectory` | Optional | String | `%USERPROFILE%` | The directory the shell starts in when it is loaded. |
+| `suppressApplicationTitle` | Optional | Boolean | | When set to `true`, `tabTitle` overrides the default title of the tab and any title change messages from the application will be suppressed. When set to `false`, `tabTitle` behaves as normal. |
+| `tabTitle` | Optional | String | | If set, will replace the `name` as the title to pass to the shell on startup. Some shells (like `bash`) may choose to ignore this initial value, while others (`cmd`, `powershell`) may use this value over the lifetime of the application.  |
+| `useAcrylic` | Optional | Boolean | `false` | When set to `true`, the window will have an acrylic background. When set to `false`, the window will have a plain, untextured background. |
+| `experimental.retroTerminalEffect` | Optional | Boolean | `false` | When set to `true`, enable retro terminal effects. This is an experimental feature, and its continued existence is not guaranteed. |
+
+## Schemes
+Properties listed below are specific to each color scheme. [ColorTool](https://github.com/microsoft/terminal/tree/master/src/tools/ColorTool) is a great tool you can use to create and explore new color schemes. All colors use hex color format.
+
+| Property | Necessity | Type | Description |
+| -------- | ---- | ----------- | ----------- |
+| `name` | _Required_ | String | Name of the color scheme. |
+| `foreground` | _Required_ | String | Sets the foreground color of the color scheme. |
+| `background` | _Required_ | String | Sets the background color of the color scheme. |
+| `selectionBackground` | Optional | String | Sets the selection background color of the color scheme. |
+| `black` | _Required_ | String | Sets the color used as ANSI black. |
+| `blue` | _Required_ | String | Sets the color used as ANSI blue. |
+| `brightBlack` | _Required_ | String | Sets the color used as ANSI bright black. |
+| `brightBlue` | _Required_ | String | Sets the color used as ANSI bright blue. |
+| `brightCyan` | _Required_ | String | Sets the color used as ANSI bright cyan. |
+| `brightGreen` | _Required_ | String | Sets the color used as ANSI bright green. |
+| `brightPurple` | _Required_ | String | Sets the color used as ANSI bright purple. |
+| `brightRed` | _Required_ | String | Sets the color used as ANSI bright red. |
+| `brightWhite` | _Required_ | String | Sets the color used as ANSI bright white. |
+| `brightYellow` | _Required_ | String | Sets the color used as ANSI bright yellow. |
+| `cyan` | _Required_ | String | Sets the color used as ANSI cyan. |
+| `green` | _Required_ | String | Sets the color used as ANSI green. |
+| `purple` | _Required_ | String | Sets the color used as ANSI purple. |
+| `red` | _Required_ | String | Sets the color used as ANSI red. |
+| `white` | _Required_ | String | Sets the color used as ANSI white. |
+| `yellow` | _Required_ | String | Sets the color used as ANSI yellow. |
+
+## Keybindings
+Properties listed below are specific to each custom key binding.
+
+| Property | Necessity | Type | Description |
+| -------- | ---- | ----------- | ----------- |
+| `command` | _Required_ | String | The command executed when the associated key bindings are pressed. |
+| `keys` | _Required_ | Array[String] | Defines the key combinations used to call the command. |
+
+### Implemented Commands
+
+Commands listed below are per the implementation in [`src/cascadia/TerminalApp/AppKeyBindingsSerialization.cpp`](https://github.com/microsoft/terminal/blob/master/src/cascadia/TerminalApp/AppKeyBindingsSerialization.cpp)
+
+- copy
+- copyTextWithoutNewlines
+- paste
+- newTab
+- openNewTabDropdown
+- duplicateTab
+- newTabProfile0
+- newTabProfile1
+- newTabProfile2
+- newTabProfile3
+- newTabProfile4
+- newTabProfile5
+- newTabProfile6
+- newTabProfile7
+- newTabProfile8
+- closeWindow
+- closeTab
+- closePane
+- switchToTab
+- nextTab
+- prevTab
+- increaseFontSize
+- decreaseFontSize
+- resetFontSize
+- scrollUp
+- scrollDown
+- scrollUpPage
+- scrollDownPage
+- switchToTab0
+- switchToTab1
+- switchToTab2
+- switchToTab3
+- switchToTab4
+- switchToTab5
+- switchToTab6
+- switchToTab7
+- switchToTab8
+- openSettings
+- splitPane
+- resizePaneLeft
+- resizePaneRight
+- resizePaneUp
+- resizePaneDown
+- moveFocusLeft
+- moveFocusRight
+- moveFocusUp
+- moveFocusDown
+- toggleFullscreen
+- find
+
+## Example Keys
+- ctrl+1
+- ctrl+plus
+- alt+-
+- shift+numpad_1
+- ctrL+shift+numpad_plus
+- ctrl+pgdn
+- ctrl+alt+shift+pgup
+
+## Background Images and Icons
+Some Terminal settings allow you to specify custom background images and icons. It is recommended that custom images and icons are stored in system-provided folders and are referred to using the correct [URI Schemes](https://docs.microsoft.com/en-us/windows/uwp/app-resources/uri-schemes). URI Schemes provide a way to reference files independent of their physical paths (which may change in the future).
+
+The most useful URI schemes to remember when customizing background images and icons are:
+
+| URI Scheme | Corresponding Physical Path | Use / description |
+| --- | --- | ---|
+| `ms-appdata:///Local/` | `%localappdata%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\` | Per-machine files |
+| `ms-appdata:///Roaming/` | `%localappdata%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\RoamingState\` | Common files |
+
+> ⚠ Note: Do not rely on file references using the `ms-appx` URI Scheme (i.e. icons). These files are considered an internal implementation detail and may change name/location or may be omitted in the future.
+
+### Icons
+Terminal displays icons for each of your profiles which Terminal generates for any built-in shells - PowerShell Core, PowerShell, and any installed Linux/WSL distros. Each profile refers to a stock icon via the `ms-appx` URI Scheme.
+
+> ⚠ Note: Do not rely on the files referenced by the `ms-appx` URI Scheme - they are considered an internal implementation detail and may change name/location or may be omitted in the future.
+
+You can refer to you own icons if you wish, e.g.:
+
+```json
+    "icon" : "C:\\Users\\richturn\\OneDrive\\WindowsTerminal\\icon-ubuntu-32.png",
+```
+
+> 👉 Tip: Icons should be sized to 32x32px in an appropriate raster image format (e.g. .PNG, .GIF, or .ICO) to avoid having to scale your icons during runtime (causing a noticeable delay and loss of quality.)
+
+### Custom Background Images
+You can apply a background image to each of your profiles, allowing you to configure/brand/style each of your profiles independently from one another if you wish.
+
+To do so, specify your preferred `backgroundImage`, position it using `backgroundImageAlignment`, set its opacity with `backgroundImageOpacity`, and/or specify how your image fill the available space using `backgroundImageStretchMode`.
+
+For example:
+```json
+    "backgroundImage": "C:\\Users\\richturn\\OneDrive\\WindowsTerminal\\bg-ubuntu-256.png",
+    "backgroundImageAlignment": "bottomRight",
+    "backgroundImageOpacity": 0.1,
+    "backgroundImageStretchMode": "none"
+```
+
+> 👉 Tip: You can easily roam your collection of images and icons across all your machines by storing your icons and images in OneDrive (as shown above).
+
+With these settings, your Terminal's Ubuntu profile would look similar to this:
+
+![Custom icon and background image](../images/custom-icon-and-background-image.jpg)

doc/cascadia/profiles.schema.json

@@ -0,0 +1,783 @@
+{
+  "$id": "https://github.com/microsoft/terminal/blob/master/doc/cascadia/profiles.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Microsoft's Windows Terminal Settings Profile Schema'",
+  "definitions": {
+    "Color": {
+      "default": "#",
+      "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$",
+      "type": "string",
+      "format": "color"
+    },
+    "ProfileGuid": {
+      "default": "{}",
+      "pattern": "^\\{[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}\\}$",
+      "type": "string"
+    },
+    "ShortcutActionName": {
+      "enum": [
+        "closePane",
+        "closeTab",
+        "closeWindow",
+        "copy",
+        "copyTextWithoutNewlines",
+        "decreaseFontSize",
+        "duplicateTab",
+        "increaseFontSize",
+        "moveFocus",
+        "moveFocusDown",
+        "moveFocusLeft",
+        "moveFocusRight",
+        "moveFocusUp",
+        "newTab",
+        "newTabProfile0",
+        "newTabProfile1",
+        "newTabProfile2",
+        "newTabProfile3",
+        "newTabProfile4",
+        "newTabProfile5",
+        "newTabProfile6",
+        "newTabProfile7",
+        "newTabProfile8",
+        "nextTab",
+        "openNewTabDropdown",
+        "openSettings",
+        "paste",
+        "prevTab",
+        "resetFontSize",
+        "resizePane",
+        "resizePaneDown",
+        "resizePaneLeft",
+        "resizePaneRight",
+        "resizePaneUp",
+        "scrollDown",
+        "scrollDownPage",
+        "scrollUp",
+        "scrollUpPage",
+        "splitHorizontal",
+        "splitVertical",
+        "splitPane",
+        "switchToTab",
+        "switchToTab0",
+        "switchToTab1",
+        "switchToTab2",
+        "switchToTab3",
+        "switchToTab4",
+        "switchToTab5",
+        "switchToTab6",
+        "switchToTab7",
+        "switchToTab8",
+        "toggleFullscreen"
+      ],
+      "type": "string"
+    },
+    "Direction": {
+      "enum": [
+        "left",
+        "right",
+        "up",
+        "down"
+      ],
+      "type": "string"
+    },
+    "SplitState": {
+      "enum": [
+        "vertical",
+        "horizontal"
+      ],
+      "type": "string"
+    },
+    "NewTerminalArgs": {
+      "properties": {
+        "commandline": {
+          "description": "A commandline to use instead of the profile's",
+          "type": "string"
+        },
+        "tabTitle": {
+          "description": "An initial tabTitle to use instead of the profile's",
+          "type": "string"
+        },
+        "startingDirectory": {
+          "description": "A startingDirectory to use instead of the profile's",
+          "type": "string"
+        },
+        "profile": {
+          "description": "Either the GUID or name of a profile to use, instead of launching the default",
+          "type": "string"
+        },
+        "index": {
+          "type": "integer",
+          "description": "The index of the profile in the new tab dropdown to open"
+        }
+      },
+      "type": "object"
+    },
+    "ShortcutAction": {
+      "properties": {
+        "action": {
+          "description": "The action to execute",
+          "$ref": "#/definitions/ShortcutActionName"
+        }
+      },
+      "required": [
+        "action"
+      ],
+      "type": "object"
+    },
+    "CopyAction": {
+      "description": "Arguments corresponding to a Copy Text Action",
+      "allOf": [
+        { "$ref": "#/definitions/ShortcutAction" },
+        {
+          "properties": {
+            "action": { "type": "string", "pattern": "copy" },
+            "trimWhitespace": {
+              "type": "boolean",
+              "default": true,
+              "description": "If true, whitespace is removed and newlines are maintained. If false, newlines are removed and whitespace is maintained."
+            }
+          }
+        }
+      ]
+    },
+    "NewTabAction": {
+      "description": "Arguments corresponding to a New Tab Action",
+      "allOf": [
+        { "$ref": "#/definitions/ShortcutAction" },
+        { "$ref": "#/definitions/NewTerminalArgs" },
+        {
+          "properties": {
+            "action": { "type":"string", "pattern": "newTab" }
+          }
+        }
+      ]
+    },
+    "SwitchToTabAction": {
+      "description": "Arguments corresponding to a Switch To Tab Action",
+      "allOf": [
+        { "$ref": "#/definitions/ShortcutAction" },
+        {
+          "properties": {
+            "action": { "type": "string", "pattern": "switchToTab" },
+            "index": {
+              "type": "integer",
+              "default": 0,
+              "description": "Which tab to switch to, with the first being 0"
+            }
+          }
+        }
+      ],
+      "required": [ "index" ]
+    },
+    "MoveFocusAction": {
+      "description": "Arguments corresponding to a Move Focus Action",
+      "allOf": [
+        { "$ref": "#/definitions/ShortcutAction" },
+        {
+          "properties": {
+            "action": { "type": "string", "pattern": "moveFocus" },
+            "direction": {
+              "$ref": "#/definitions/Direction",
+              "default": "left",
+              "description": "The direction to move focus in, between panes"
+            }
+          }
+        }
+      ],
+      "required": [ "direction" ]
+    },
+    "ResizePaneAction": {
+      "description": "Arguments corresponding to a Resize Pane Action",
+      "allOf": [
+        { "$ref": "#/definitions/ShortcutAction" },
+        {
+          "properties": {
+            "action": { "type": "string", "pattern": "resizePane" },
+            "direction": {
+              "$ref": "#/definitions/Direction",
+              "default": "left",
+              "description": "The direction to move the pane separator in"
+            }
+          }
+        }
+      ],
+      "required": [ "direction" ]
+    },
+    "SplitPaneAction": {
+      "description": "Arguments corresponding to a Split Pane Action",
+      "allOf": [
+        { "$ref": "#/definitions/ShortcutAction" },
+        { "$ref": "#/definitions/NewTerminalArgs" },
+        {
+          "properties": {
+            "action": { "type": "string", "pattern": "splitPane" },
+            "split": {
+              "$ref": "#/definitions/SplitState",
+              "default": "vertical",
+              "description": "The orientation to split the pane in, either vertical (think [|]) or horizontal (think [-])"
+            }
+          }
+        }
+      ],
+      "required": [ "split" ]
+    },
+    "Keybinding": {
+      "additionalProperties": false,
+      "properties": {
+        "command": {
+          "description": "The action executed when the associated key bindings are pressed.",
+            "oneOf": [
+              { "$ref": "#/definitions/CopyAction" },
+              { "$ref": "#/definitions/ShortcutActionName" },
+              { "$ref": "#/definitions/NewTabAction" },
+              { "$ref": "#/definitions/SwitchToTabAction" },
+              { "$ref": "#/definitions/MoveFocusAction" },
+              { "$ref": "#/definitions/ResizePaneAction" },
+              { "$ref": "#/definitions/SplitPaneAction" }
+            ]
+        },
+        "keys": {
+          "description": "Defines the key combinations used to call the command.",
+          "items": {
+            "pattern": "^(?<modifier>(ctrl|alt|shift)\\+?((ctrl|alt|shift)(?<!\\2)\\+?)?((ctrl|alt|shift)(?<!\\2|\\4))?\\+?)?(?<key>[^+\\s]+?)?(?<=[^+\\s])$",
+            "type": "string"
+          },
+          "minItems": 1,
+          "type": "array"
+        }
+      },
+      "required": [
+        "command",
+        "keys"
+      ],
+      "type": "object"
+    },
+    "Globals": {
+      "additionalProperties": true,
+      "description": "Properties that affect the entire window, regardless of the profile settings.",
+      "properties": {
+        "alwaysShowTabs": {
+          "default": true,
+          "description": "When set to true, tabs are always displayed. When set to false and showTabsInTitlebar is set to false, tabs only appear after opening a new tab.",
+          "type": "boolean"
+        },
+        "copyOnSelect": {
+          "default": false,
+          "description": "When set to true, a selection is immediately copied to your clipboard upon creation. When set to false, the selection persists and awaits further action.",
+          "type": "boolean"
+        },
+        "defaultProfile": {
+          "$ref": "#/definitions/ProfileGuid",
+          "description": "Sets the default profile. Opens by clicking the '+' icon or typing the key binding assigned to 'newTab'. The guid of the desired default profile is used as the value."
+        },
+        "initialCols": {
+          "default": 120,
+          "description": "The number of columns displayed in the window upon first load.",
+          "maximum": 999,
+          "minimum": 1,
+          "type": "integer"
+        },
+        "initialRows": {
+          "default": 30,
+          "description": "The number of rows displayed in the window upon first load.",
+          "maximum": 999,
+          "minimum": 1,
+          "type": "integer"
+        },
+        "rowsToScroll": {
+          "default": "system",
+          "description": "The number of rows to scroll at a time with the mouse wheel. This will override the system setting if the value is not zero or 'system'.",
+          "maximum": 999,
+          "minimum": 0,
+          "type": "integer"
+        },
+        "keybindings": {
+          "description": "Properties are specific to each custom key binding.",
+          "items": {
+            "$ref": "#/definitions/Keybinding"
+          },
+          "type": "array"
+        },
+        "requestedTheme": {
+          "default": "system",
+          "description": "Sets the theme of the application.",
+          "enum": [
+            "light",
+            "dark",
+            "system"
+          ],
+          "type": "string"
+        },
+        "showTabsInTitlebar": {
+          "default": true,
+          "description": "When set to true, the tabs are moved into the titlebar and the titlebar disappears. When set to false, the titlebar sits above the tabs.",
+          "type": "boolean"
+        },
+        "showTerminalTitleInTitlebar": {
+          "default": true,
+          "description": "When set to true, titlebar displays the title of the selected tab. When set to false, titlebar displays 'Windows Terminal'.",
+          "type": "boolean"
+        },
+        "snapToGridOnResize": {
+          "default": false,
+          "description": "When set to `true`, the window will snap to the nearest character boundary on resize. When `false`, the window will resize 'smoothly'",
+          "type": "boolean"
+        },
+        "tabWidthMode": {
+          "default": "equal",
+          "description": "Sets the width of the tabs.",
+          "enum": [
+            "equal",
+            "titleLength"
+          ],
+          "type": "string"
+        },
+        "wordDelimiters": {
+          "default": " ./\\()\"'-:,.;<>~!@#$%^&*|+=[]{}~?│",
+          "description": "Determines the delimiters used in a double click selection.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "defaultProfile"
+      ],
+      "type": "object"
+    },
+    "Profile": {
+      "description": "Properties specific to a unique profile.",
+      "additionalProperties": false,
+      "properties": {
+        "acrylicOpacity": {
+          "default": 0.5,
+          "description": "When useAcrylic is set to true, it sets the transparency of the window for the profile. Accepts floating point values from 0-1 (default 0.5).",
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        "background": {
+          "$ref": "#/definitions/Color",
+          "description": "Sets the background color of the profile. Overrides background set in color scheme if colorscheme is set. Uses hex color format: \"#rrggbb\". Default \"#000000\" (black).",
+          "type": ["string", "null"]
+        },
+        "backgroundImage": {
+          "description": "Sets the file location of the Image to draw over the window background.",
+          "type": "string"
+        },
+        "backgroundImageAlignment": {
+          "default": "center",
+          "enum": [
+            "bottom",
+            "bottomLeft",
+            "bottomRight",
+            "center",
+            "left",
+            "right",
+            "top",
+            "topLeft",
+            "topRight"
+          ],
+          "type": "string"
+        },
+        "backgroundImageOpacity": {
+          "description": "(Not in SettingsSchema.md)",
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        "backgroundImageStretchMode": {
+          "default": "uniformToFill",
+          "description": "Sets how the background image is resized to fill the window.",
+          "enum": [
+            "fill",
+            "none",
+            "uniform",
+            "uniformToFill"
+          ],
+          "type": "string"
+        },
+        "closeOnExit": {
+          "default": "graceful",
+          "description": "Sets how the profile reacts to termination or failure to launch. Possible values: \"graceful\" (close when exit is typed or the process exits normally), \"always\" (always close) and \"never\" (never close). true and false are accepted as synonyms for \"graceful\" and \"never\" respectively.",
+          "oneOf": [
+            {
+              "enum": [
+                "never",
+                "graceful",
+                "always"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "boolean"
+            }
+          ]
+        },
+        "colorScheme": {
+          "default": "Campbell",
+          "description": "Name of the terminal color scheme to use. Color schemes are defined under \"schemes\".",
+          "type": "string"
+        },
+        "colorTable": {
+          "description": "Array of colors used in the profile if colorscheme is not set. Colors use hex color format: \"#rrggbb\". Ordering is as follows: [black, red, green, yellow, blue, magenta, cyan, white, bright black, bright red, bright green, bright yellow, bright blue, bright magenta, bright cyan, bright white]",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "background": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the background color of the color table."
+              },
+              "black": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the color used as ANSI black."
+              },
+              "blue": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the color used as ANSI blue."
+              },
+              "brightBlack": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the color used as ANSI bright black."
+              },
+              "brightBlue": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the color used as ANSI bright blue."
+              },
+              "brightCyan": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the color used as ANSI bright cyan."
+              },
+              "brightGreen": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the color used as ANSI bright green."
+              },
+              "brightPurple": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the color used as ANSI bright purple."
+              },
+              "brightRed": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the color used as ANSI bright red."
+              },
+              "brightWhite": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the color used as ANSI bright white."
+              },
+              "brightYellow": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the color used as ANSI bright yellow."
+              },
+              "cyan": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the color used as ANSI cyan."
+              },
+              "foreground": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the foreground color of the color table."
+              },
+              "green": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the color used as ANSI green."
+              },
+              "purple": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the color used as ANSI purple."
+              },
+              "red": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the color used as ANSI red."
+              },
+              "white": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the color used as ANSI white."
+              },
+              "yellow": {
+                "$ref": "#/definitions/Color",
+                "description": "Sets the color used as ANSI yellow."
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "commandline": {
+          "description": "Executable used in the profile.",
+          "type": "string"
+        },
+        "connectionType": {
+          "$ref": "#/definitions/ProfileGuid",
+          "description": "A GUID reference to a connection type. Currently undocumented as of 0.3, this is used for Azure Cloud Shell"
+        },
+        "cursorColor": {
+          "$ref": "#/definitions/Color",
+          "default": "#FFFFFF",
+          "description": "Sets the cursor color for the profile. Uses hex color format: \"#rrggbb\"."
+        },
+        "cursorHeight": {
+          "description": "Sets the percentage height of the cursor starting from the bottom. Only works when cursorShape is set to \"vintage\". Accepts values from 25-100.",
+          "maximum": 100,
+          "minimum": 25,
+          "type": "integer"
+        },
+        "cursorShape": {
+          "default": "bar",
+          "description": "Sets the cursor shape for the profile. Possible values: \"vintage\" ( ▃ ), \"bar\" ( ┃, default ), \"underscore\" ( ▁ ), \"filledBox\" ( █ ), \"emptyBox\" ( ▯ )",
+          "enum": [
+            "bar",
+            "emptyBox",
+            "filledBox",
+            "underscore",
+            "vintage"
+          ],
+          "type": "string"
+        },
+        "experimental.retroTerminalEffect": {
+          "description": "When set to true, enable retro terminal effects. This is an experimental feature, and its continued existence is not guaranteed.",
+          "type": "boolean"
+        },
+        "fontFace": {
+          "default": "Consolas",
+          "description": "Name of the font face used in the profile.",
+          "type": "string"
+        },
+        "fontSize": {
+          "default": 12,
+          "description": "Sets the font size.",
+          "minimum": 1,
+          "type": "integer"
+        },
+        "foreground": {
+          "$ref": "#/definitions/Color",
+          "description": "Sets the foreground color of the profile. Overrides foreground set in color scheme if colorscheme is set. Uses hex color format: \"#rrggbb\". Default \"#ffffff\" (white).",
+          "type": ["string", "null"]
+        },
+        "guid": {
+          "$ref": "#/definitions/ProfileGuid",
+          "description": "Unique identifier of the profile. Written in registry format: \"{00000000-0000-0000-0000-000000000000}\"."
+        },
+        "hidden": {
+          "default": false,
+          "description": "If set to true, the profile will not appear in the list of profiles. This can be used to hide default profiles and dynamicially generated profiles, while leaving them in your settings file.",
+          "type": "boolean"
+        },
+        "historySize": {
+          "default": 9001,
+          "description": "The number of lines above the ones displayed in the window you can scroll back to.",
+          "minimum": -1,
+          "type": "integer"
+        },
+        "icon": {
+          "description": "Image file location of the icon used in the profile. Displays within the tab and the dropdown menu.",
+          "type": "string"
+        },
+        "name": {
+          "description": "Name of the profile. Displays in the dropdown menu.",
+          "minLength": 1,
+          "type": "string"
+        },
+        "padding": {
+          "default": "8, 8, 8, 8",
+          "description": "Sets the padding around the text within the window. Can have three different formats: \"#\" sets the same padding for all sides, \"#, #\" sets the same padding for left-right and top-bottom, and \"#, #, #, #\" sets the padding individually for left, top, right, and bottom.",
+          "pattern": "^-?[0-9]+(\\.[0-9]+)?( *, *-?[0-9]+(\\.[0-9]+)?|( *, *-?[0-9]+(\\.[0-9]+)?){3})?$",
+          "type": "string"
+        },
+        "scrollbarState": {
+          "default": "visible",
+          "description": "Defines the visibility of the scrollbar.",
+          "enum": [
+            "visible",
+            "hidden"
+          ],
+          "type": "string"
+        },
+        "selectionBackground": {
+          "$ref": "#/definitions/Color",
+          "description": "Sets the selection background color of the profile. Overrides selection background set in color scheme if colorscheme is set. Uses hex color format: \"#rrggbb\"."
+        },
+        "snapOnInput": {
+          "default": true,
+          "description": "When set to true, the window will scroll to the command input line when typing. When set to false, the window will not scroll when you start typing.",
+          "type": "boolean"
+        },
+        "source": {
+          "description": "Stores the name of the profile generator that originated this profile.",
+          "type": "string"
+        },
+        "startingDirectory": {
+          "description": "The directory the shell starts in when it is loaded.",
+          "type": "string"
+        },
+        "suppressApplicationTitle": {
+          "description": "When set to `true`, `tabTitle` overrides the default title of the tab and any title change messages from the application will be suppressed. When set to `false`, `tabTitle` behaves as normal.",
+          "type": "boolean"
+        },
+        "tabTitle": {
+          "description": "If set, will replace the name as the title to pass to the shell on startup. Some shells (like bash) may choose to ignore this initial value, while others (cmd, powershell) may use this value over the lifetime of the application.",
+          "type": "string"
+        },
+        "useAcrylic": {
+          "default": false,
+          "description": "When set to true, the window will have an acrylic background. When set to false, the window will have a plain, untextured background.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "ProfileList": {
+      "description": "A list of profiles and the properties specific to each.",
+      "items": {
+        "$ref": "#/definitions/Profile",
+        "required": [
+          "guid",
+          "name"
+        ]
+      },
+      "type": "array"
+    },
+    "ProfilesObject": {
+      "description": "A list of profiles and default settings that apply to all of them",
+      "properties": {
+        "list": {
+          "$ref": "#/definitions/ProfileList"
+        },
+        "defaults": {
+          "description": "The default settings that apply to every profile.",
+          "$ref": "#/definitions/Profile"
+        }
+      },
+      "type": "object"
+    },
+    "SchemeList": {
+      "description": "Properties are specific to each color scheme. ColorTool is a great tool you can use to create and explore new color schemes. All colors use hex color format.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "description": "Name of the color scheme.",
+            "minLength": 1,
+            "type": "string"
+          },
+          "background": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the background color of the color scheme."
+          },
+          "black": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the color used as ANSI black."
+          },
+          "blue": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the color used as ANSI blue."
+          },
+          "brightBlack": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the color used as ANSI bright black."
+          },
+          "brightBlue": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the color used as ANSI bright blue."
+          },
+          "brightCyan": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the color used as ANSI bright cyan."
+          },
+          "brightGreen": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the color used as ANSI bright green."
+          },
+          "brightPurple": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the color used as ANSI bright purple."
+          },
+          "brightRed": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the color used as ANSI bright red."
+          },
+          "brightWhite": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the color used as ANSI bright white."
+          },
+          "brightYellow": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the color used as ANSI bright yellow."
+          },
+          "cyan": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the color used as ANSI cyan."
+          },
+          "foreground": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the foreground color of the color scheme."
+          },
+          "green": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the color used as ANSI green."
+          },
+          "purple": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the color used as ANSI purple."
+          },
+          "red": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the color used as ANSI red."
+          },
+          "selectionBackground": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the selection background color of the color scheme."
+          },
+          "white": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the color used as ANSI white."
+          },
+          "yellow": {
+            "$ref": "#/definitions/Color",
+            "description": "Sets the color used as ANSI yellow."
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "oneOf": [
+    {
+      "allOf": [
+        { "$ref": "#/definitions/Globals" },
+        {
+          "additionalItems": true,
+          "properties": {
+            "profiles": {
+              "oneOf": [
+              { "$ref": "#/definitions/ProfileList" },
+              { "$ref": "#/definitions/ProfilesObject" }
+              ]
+            },
+            "schemes": { "$ref": "#/definitions/SchemeList" }
+          },
+          "required": [
+            "profiles",
+            "schemes",
+            "defaultProfile"
+          ]
+        }
+      ]
+    },
+    {
+      "additionalItems": false,
+      "properties": {
+        "globals": { "$ref": "#/definitions/Globals" },
+        "profiles": {
+          "oneOf": [
+          { "$ref": "#/definitions/ProfileList" },
+          { "$ref": "#/definitions/ProfilesObject" }
+          ]
+        },
+        "schemes": { "$ref": "#/definitions/SchemeList" }
+      },
+      "required": [
+        "profiles",
+        "schemes",
+        "globals"
+      ]
+    }
+  ]
+}

doc/specs/#1043 - Set the initial position of the Terminal/spec.md

@@ -0,0 +1,100 @@
+---
+author: Kaiyu Wang KaiyuWang16/kawa@microsoft.com
+created on: 2019-09-03
+last updated: 2020-01-02
+issue id: #1043
+---
+
+# Set the initial position for terminal
+
+## Abstract
+
+This spec is for task #1043 “Be able to set an initial position for the terminal”. It goes over the details of a new feature that allows users to set the initial position and size of the terminal. Expected behavior and design of this feature is included. Besides, future possible follow-up works are also addressed.
+
+## Inspiration
+
+The idea is to allow users to set the initial position of the Terminal when they launch it, prevent the Terminal from appearing on unexpected position (e.g. outside of the screen bounds). We are also going to let users choose to maximize the window when they launch it.
+
+## Solution Design
+
+For now, the Terminal window is put on a default initial position. The program uses CW_USEDEFAULT in the screen coordinates for top-left corner. We have two different types of window – client window and non-client window. However, code path for window creation (WM_CREATE message is shared by the two types of windows) are almost the same for the two types of windows, except that there are some differences in calculation of the width and height of the window.
+
+Two new properties should be added in the json settings file:
+
+**initialPosition**: string. This sets the initial horizontal and vertical position of the top-left corner of the window. This property follows a structure: "X value, Y value" and has following rules:
+
+1. All spaces will be ignored.
+
+2. Both X value and Y values are optional. If anyone of them is missing, or the value is invalid, system default value will be used. Examples:
+
+       ", 1000" equals to (default, 1000)
+       "1000, " equals to (1000, default)
+       "," equals to (default, default)
+       "abc, 1000" equals to (default, 1000)
+
+**launchMode**: string. Determine the launch mode. There are two modes for now
+
+1. maximize: the window will be maximized when launch.
+2. default: the window will be initialized with system default size.
+
+The steps of this process:
+
+1. Set the top-left origin, width and height to CW_USEDEFAULT.
+2. Get the dpi of the nearest monitor; Load settings.
+3. From settings, find the user-defined initial position and launch mode. 
+4. If the user sets custom initial position, calculate the new position considering the current dpi and monitor. If not, use system default value.
+5. If the user set launch mode as "maximize", calculate the new height and width. If the user choose "default", use system default size.
+6. SetWindowPos with the new position and dimension of the window. 
+
+Step 2 to 6 should be done in `AppHost::_HandleCreateWindow`, which is consistent to the current code.
+
+In step 4, we may need to consider the dpi of the current monitor and multi-monitor scenario when calculating the initial position of the window.
+
+Edge cases:
+
+1. Multiple monitors. The user should be able to set the initial position to any monitors attached. For the monitors on the left side of the major monitor, the initial position values are negative. 
+2. If the initial position is larger than the screen resolution and the window top left corner is off-screen, we should let user be able to see and drag the window back on screen. One solution is to set the initial position to the top left corner of the nearest monitor if the top left is off-screen.
+3. If the user wants to launch maximized and provides an initial position, we should launch the maximized window on the top left corner of the monitor where the position is located.
+4. Launch the Terminal on a monitor with custom dpi. Changing the dpi of the monitor will not affect the initial position of the top left corner. So we do not need to handle this case. 
+5. Launch the Terminal on a monitor with custom resolution. Changing the resolution will change the available point for the initial position. (2) already covers this case. 
+
+## UI/UX Design
+
+Upon successful implementation, the user is able to add new properties to the json profile file, which is illustrated in the code block below:
+```json
+"initialPosition": "500,500",
+"launchMode": "default"
+```
+The rest of the UI will be the same of the current Terminal experience, except that the initial position may be different.
+
+### Accessibility
+
+Users can only set the initial position and launch mode in the Json file with keyboard. Thus, this will not affect accessibility. 
+
+### Reliability
+We need to make sure that whatever the initial position is set, the user can access the Terminal window. This is guaranteed because if the top left corner position of the Terminal Window is out of screen, we put it on the top left corner of the screen. 
+
+### Performance, Power, and Efficiency
+
+More data reading and calculation will be included in Terminal Launch process, which may inversely influence the launch time. However, the impact is trivial. 
+
+## Potential Issues
+
+We need to consider multi-monitor scenario. If the user has multiple monitors, we must guarantee that the Terminal could be iniitalized as expected. We can keep an eye on the feedbacks of this feature from the community.
+
+## Future considerations
+
+For now, this feature only allows the user to set initial positon and choose whether to maximize the window when launch. In the future, we may consider follow-up features like:
+
+1. Save the position of the Terminal on exit, and restore the position on the next launch. This could be a true/false feature that users could choose to set.
+
+2. We may need to consider multiple Terminal windows scenario. If the user opens multiple Terminal windows, then we need to consider how to save and restore the position. 
+
+3. We may also consider more launch modes. Like full screen mode and minimized mode. 
+
+Github issue for future follow-ups: https://github.com/microsoft/terminal/issues/766
+
+## Resources
+
+Github issue:
+https://github.com/microsoft/terminal/issues/1043

doc/specs/#2325 - Default Profile Settings.md

@@ -0,0 +1,346 @@
+---
+author: Mike Griese @zadjii-msft
+created on: 2019-11-13
+last updated: 2019-12-05
+issue id: #2325
+---
+
+# Default Profile Settings
+
+## Abstract
+
+Oftentimes, users have some common settings that they'd like applied to all of
+their profiles, without needing to manually edit the settings of each of them.
+This doc will cover some of the many proposals on how to expose that
+functionality to the user in our JSON settings model. In this first document,
+we'll examine a number of proposed solutions, as well as state our finalized
+design.
+
+## Inspiration
+
+During the course of the pull request review on [#3369], the original pull
+request for this feature's implementation, it became apparent that the entire
+team has differing opinions on how this feature should be exposed to the user.
+This doc is born from that discussion.
+
+## Solution Proposals
+
+The following are a number of different proposals of different ways to achieve
+the proposed functionality:
+
+1. [`defaultSettings` Profile object in the global settings](#proposal-1-defaultsettings-profile-object-in-the-global-settings)
+2. [`__default__` Profile object in the user's profiles](#proposal-2-__default__-profile-object-in-the-users-profiles)
+3. [Change `profiles` to an object with a `list` of profiles and a `defaults`](#proposal-3-change-profiles-to-an-object-with-a-list-of-profiles-and-a-defaults-object)
+   object
+4. [`inheritFrom` in profiles](#proposal-4-inheritfrom-in-profiles)
+
+### Proposal 1: `defaultSettings` Profile object in the global settings
+
+```json
+{
+    "$schema": "https://aka.ms/terminal-profiles-schema",
+    "defaultProfile": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
+    "defaultSettings":
+    {
+        "useAcrylic": true,
+        "acrylicOpacity": 0.1,
+        "fontFace": "Cascadia Code",
+        "fontSize": 10
+    },
+    "requestedTheme" : "dark",
+    "showTabsInTitlebar" : true,
+    "profiles":
+    [
+        {
+            "guid": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
+            "name": "Windows PowerShell",
+            "commandline": "powershell.exe",
+            "hidden": false
+        },
+        {
+            "guid": "{0caa0dad-35be-5f56-a8ff-afceeeaa6101}",
+            "name": "cmd",
+            "commandline": "cmd.exe",
+            "hidden": false
+        }
+    ],
+    "schemes": [],
+    "keybindings": []
+}
+```
+#### Benefits
+
+##### Clearly encapsulates the default profile settings
+Puts all the default profiles settings in one object. It's immediately obvious
+when scanning the file where the defaults are.
+
+##### Simple to understand
+There's one object that applies to all the subsequent profiles, and that
+object is the `defaultSettings` object.
+
+#### Concerns
+
+##### What do we name this setting?
+People were concerned about the naming of this property. No one has a name that
+we're quite happy with:
+
+* `defaultSettings`: This kinda seems to conflict conceptually with
+  "defaults.json". It's different, but is that obvious?
+* `defaultProfileSettings`: Implies "settings of the default profile"
+* `defaults`: This kinda seems to conflict conceptually with "defaults.json"
+* `baseProfileSettings`: not the worst, but not terribly intuitive
+* Others considered with less enthusiasm
+    - `profiles.defaults`: people don't love the idea of a `.`, but hey, VsCode does it.
+    - `inheritedSettings`
+    - `rootSettings`
+    - `globalSettings`: again maybe conflicts a bit with other concepts/properties
+    - `profileSettings`
+    - `profilePrototype`
+
+##### Why is there this random floating profile in the global settings?
+
+Users may be confused about the purpose of this random `Profile` that's in the
+globals. What's that profile doing there? Is _it_ the default profile?
+
+### Proposal 2: `__default__` Profile object in the user's profiles
+```json
+{
+    "$schema": "https://aka.ms/terminal-profiles-schema",
+    "defaultProfile": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
+    "requestedTheme" : "dark",
+    "showTabsInTitlebar" : true,
+    "profiles":
+    [
+        {
+            "guid": "__default__",
+            "useAcrylic": true,
+            "acrylicOpacity": 0.1,
+            "fontFace": "Cascadia Code",
+            "fontSize": 10
+        },
+        {
+            "guid": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
+            "name": "Windows PowerShell",
+            "commandline": "powershell.exe",
+            "hidden": false
+        },
+        {
+            "guid": "{0caa0dad-35be-5f56-a8ff-afceeeaa6101}",
+            "name": "cmd",
+            "commandline": "cmd.exe",
+            "hidden": false
+        }
+    ],
+    "schemes": [],
+    "keybindings": []
+}
+```
+
+#### Benefits
+##### Encapsulates the default profile settings
+Puts all the default profiles settings in one object. Probably not as clear as
+proposal 1, since it could be _anywhere_ in the list of profiles.
+
+##### Groups default profile settings with profiles
+In this proposal, the default profile is grouped into the same list of objects
+as the other profiles. All the profiles, and the defaults are all under the
+`"profiles"` object. Makes sense.
+
+#### Concerns
+##### Mysterious `__defaults__` GUID
+The only way to _definitively_ identify that this profile is special is by
+giving it a constant string. This string is _not_ a guid, which again, would be
+obvious.
+
+##### Unintuitive
+Adding a profile that has a mysterious `guid` value use that profile as the
+"defaults" is _very_ unintuitive. Nothing aside from documentation would
+indicate to the user "hey, add this magic profile blob to use as defaults across
+all your profiles".
+
+##### Why does this one profile object apply to all the others
+It might be unintuitive that one profile from the list of profiles affects all
+the others.
+
+### Proposal 3: Change `profiles` to an object with a `list` of profiles and a `defaults` object
+
+```json
+{
+    "$schema": "https://aka.ms/terminal-profiles-schema",
+    "defaultProfile": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
+    "requestedTheme" : "dark",
+    "showTabsInTitlebar" : true,
+    "profiles":
+    {
+        "defaults": {
+            "useAcrylic": true,
+            "acrylicOpacity": 0.1,
+            "fontFace": "Cascadia Code",
+            "fontSize": 10
+        },
+        "list":[
+            {
+                "guid": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
+                "name": "Windows PowerShell",
+                "commandline": "powershell.exe",
+                "hidden": false
+            },
+            {
+                "guid": "{0caa0dad-35be-5f56-a8ff-afceeeaa6101}",
+                "name": "cmd",
+                "commandline": "cmd.exe",
+                "hidden": false
+            }
+        ]
+    },
+    "schemes": [],
+    "keybindings": []
+}
+```
+
+#### Benefits
+##### Groups default profile settings with profiles
+In this proposal, the default profile is grouped into the same object as the
+list of profiles. All the profiles, and the defaults are all under the
+`"profiles"` object. Makes sense.
+
+##### Backwards compatible
+Fortunately, we can add this functionality _without breaking the existing
+schema_. With Jsoncpp, we can determine at runtime if an object is an _array_ or
+an _object_. If it's an array, we can fall back to the current behavior, safe in
+our knowledge that there's no defaults object. If the object is an array
+however, we can then dig into the object to find the default profile and the
+list of profiles.
+
+#### Concerns
+##### Substantial schema change
+This is a pretty big delta to the settings schema. Instead of using `profiles`
+as a list of `Profile` objects, it instead becomes an object, with a list inside
+it.
+
+As noted above, we could gracefully upgrade this. If the `profiles` object is a
+list, then we can assume there's no `defaults`. This ensures that user's current
+settings files don't break. This is not a major problem.
+
+##### Adds another level of indentation to all profiles
+Some people just hate having things indented this much. 4 layers of indentation
+is quite a lot.
+
+### Proposal 4: `inheritFrom` in profiles
+
+```json
+{
+    "$schema": "https://aka.ms/terminal-profiles-schema",
+    "defaultProfile": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
+    "requestedTheme" : "dark",
+    "showTabsInTitlebar" : true,
+    "profiles":
+    [
+        {
+            "guid": "{11111111-1111-1111-1111-111111111111}",
+            "hidden": true,
+            "useAcrylic": true,
+            "acrylicOpacity": 0.1,
+            "fontFace": "Cascadia Code",
+            "fontSize": 10
+        },
+        {
+            "guid": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
+            "inheritFrom": "{11111111-1111-1111-1111-111111111111}",
+            "name": "Windows PowerShell",
+            "commandline": "powershell.exe",
+            "hidden": false
+        },
+        {
+            "guid": "{0caa0dad-35be-5f56-a8ff-afceeeaa6101}",
+            "inheritFrom": "{11111111-1111-1111-1111-111111111111}",
+            "name": "cmd",
+            "commandline": "cmd.exe",
+            "hidden": false
+        },
+        {
+            "guid": "{0caa0dad-ffff-5f56-a8ff-afceeeaa6101}",
+            "inheritFrom": "{0caa0dad-35be-5f56-a8ff-afceeeaa6101}",
+            "name": "This is another CMD",
+            "commandline": "cmd.exe /c myCoolScript.bat",
+            "hidden": false
+        }
+    ],
+    "schemes": [],
+    "keybindings": []
+}
+```
+
+#### Benefits
+
+##### Matches the existing settings model without major refactoring
+Simply adding a new property to `Profile` would not majorly alter the structure
+of the file.
+
+##### Property name is unique
+`inheritFrom` is very unique relative to other keys we already have.
+
+##### Powerful
+This lets the user have potentially many layers of settings grouping. hese
+layers would let the user seperate out common settings however they like,
+without forcing them to a single "default" profile. They could potentially have
+many "default" profiles, e.g.
+* one that's used for all their WSL profiles, with `startingDirectory` set to
+  `~` and `fontFace` set to "Ubuntu Mono"
+* One that's used for all their powershell profiles
+
+etc.
+
+#### Concerns
+
+##### GUIDs are not human friendly
+
+Using the guid in the `inheritFrom` field is the only way to be sure we're
+uniquely identifying profiles. However, guids are notoriously un-friendly. The
+above example manually uses `"{11111111-1111-1111-1111-111111111111}"` as the
+guid of the "default" profile, but inheriting from other profiles with "real"
+GUIDs would be less understandable. Consider the "This is another CMD" case,
+where it's inheriting from the "cmd" profile. That `"inheritFrom"` value does
+not mean at a quick glance "cmd".
+
+##### We have to make sure that there are no cycles as we're layering
+
+This is mostly a technical challenge, but this does make the implementation a
+bit trickier.
+
+##### How does this work with the settings UI?
+
+When the user edits settings for a profile with the UI, do we only place the
+changes in the top-most profile?
+
+How do we communicate in the UI that a profile is inheriting settings from other
+profiles?
+
+##### Harder to mentally parse
+Maybe not as easy to mentally picture how one profile inherits from another. The
+user would probably need to manually build the tree of profile inheritance in
+their own head to understand how a profile gets its settings.
+
+## Conclusions
+
+After discussion the available options, the team has settled on proposal 3. The
+major selling points being:
+* It groups the new "default profile settings" with the rest of the profile
+  settings
+* While being a schema change, it's not a _breaking_ schema change.
+* When looking at the settings, it's easy to understand how they're related
+
+We also like the idea of proposal 4, but felt that it was too heavy-handed of an
+approach for this relatively simple feature. It's been added to the backlog of
+terminal features, tracked in [#3818].
+
+## Resources
+
+* Default Profile for Common Profile Settings (the original issue) [#2325]
+* Add support for "User Default" settings (the original PR) [#3369]
+* Add support for inheriting and overriding another profile's settings [#3818]
+
+<!-- Footnotes -->
+[#2325]: https://github.com/microsoft/terminal/issues/2325
+[#3369]: https://github.com/microsoft/terminal/pull/3369
+[#3818]: https://github.com/microsoft/terminal/issues/3818

doc/specs/#2563 - closeOnExit and TerminalConnection evolution.md

@@ -0,0 +1,107 @@
+---
+author: Dustin Howett @DHowett-MSFT
+created on: 2019-07-19
+last updated: 2019-11-05
+issue id: "#2563"
+---
+
+# Improvements to CloseOnExit
+
+## Abstract
+
+This specification describes an improvement to the `closeOnExit` profile feature and the `ITerminalConnection` interface that will offer greater flexibility and allow us to provide saner defaults in the face of unreliable software.
+
+### Conventions and Terminology
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
+
+## Inspiration
+
+Other terminal emulators like ConEmu have a similar feature.
+
+## Solution Design
+
+### `ITerminalConnection` Changes
+
+* The `TerminalConnection` interface will be augmented with an enumerator and a set of events regarding connection state transitions.
+    * enum `TerminalConnection::ConnectionState`
+        * This enum attempts to encompass all potential connection states, even those which do not make sense for a local terminal.
+        * The wide variety of values will be useful to indicate state changes in a user interface.
+        * `NotConnected`: All new connections will start out in this state
+        * `Connecting`: The connection has been initated, but has not yet completed connecting.
+        * `Connected`: The connection is active.
+        * `Closing`: The connection is being closed (usually by request).
+        * `Closed`: The connection has been closed, either by request or from the remote end terminating successfully.
+        * `Failed`: The connection was unexpectedly terminated.
+    * event `StateChanged(ITerminalConnection, IInspectable)`
+        * (the `IInspectable` argument is recommended and required for a typed event handler, but it will bear no payload.)
+    * event `TerminalDisconnected` will be removed, as it is replaced by `StateChanged`
+    * **NOTE**: A conforming implementation MUST treat states as a directed acyclic graph. States MUST NOT be transitioned in reverse.
+* A helper class may be provided for managing state transitions.
+
+### `TerminalControl` Changes
+
+* As the decision as to whether to close a terminal control hosting a connection that has transitioned into a terminal state will be made by the application, the unexpressive `Close` event will be removed and replaced with a `ConnectionStateChanged` event.
+* `event ConnectionStateChanged(TerminalControl, IInspectable)` event will project its connection's `StateChanged` event.
+* TerminalControl's new `ConnectionState` will project its connection's `State`.
+    * (this is indicated for an eventual data binding; see Future Considerations.)
+
+### Application and Settings
+
+1. The existing `closeOnExit` profile key will be replaced with an enumerated string key supporting the following values (behaviours):
+    * `always` - a tab or pane hosting this profile will always be closed when the launched connection reaches a terminal state.
+    * `graceful` - a tab or pane hosting this profile will be closed if and only if the launched connection reaches the `Closed` terminal state.
+    * `never` - a tab or pane hosting this profile will not automatically close.
+    * See the Compatibility section for information on the legacy settings transition. 
+    * **The new default value for `closeOnExit` will be `graceful`.**
+2. `Pane` will remain responsible for making the final determination as to whether it is closed based on the settings of the profile it is hosting.
+
+## UI/UX Design
+
+* The existing `ITerminalConnection` implementations will be augmented to print out interesting and useful status information when they transition into a `Closed` or `Failed` state.
+    * Example (ConPTY connection)
+        * The pseudoconsole cannot be opened, or the process fails to launch.<br>`[failed to spawn 'thing': 0x80070002]`, transition to `Failed`.
+        * The process exited unexpectedly.<br>`[process exited with code 300]`, transition to `Failed`.
+        * The process exited normally.<br>`[process exited with code 0]`, transition to `Closed`.
+* _The final message will always be printed_ regardless of user configuration.
+* If the user's settings specify `closeOnExit: never/false`, the terminal hosting the connection will never be automatically closed. The message will remain on-screen.
+* If the user's settings specify `closeOnExit: graceful/true`, the terminal hosting the connection _will_ automatically be closed if the connection's state is `Closed`. A connection in the `Failed` state will not be closed, and the message will remain on-screen.
+* If the user's settings specify `closeOnExit: always`, the terminal hosting the connection will be closed. The message will not be seen.
+
+## Capabilities
+
+### Accessibility
+
+This will give users of all technologies a way to know when their shell has failed to launch or has exited with an unexpected status code.
+
+### Security
+
+There will be no impact to security.
+
+### Reliability
+
+Windows Terminal will no longer immediately terminate on startup if the user's shell doesn't exist.
+
+### Compatibility
+
+There is an existing `closeOnExit` _boolean_ key that a user may have configured in profiles.json. The boolean values should map as follows:
+
+* `true` -> `graceful`
+* `false` -> `never`
+
+This will make for a clean transition to Windows Terminal's sane new defaults.
+
+### Performance, Power, and Efficiency
+
+## Potential Issues
+
+There will be no impact to Performance, Power or Efficiency.
+
+## Future considerations
+
+* Eventually, we may want to implement a feature like "only close on graceful exit if the shell was running for more than X seconds". This puts us in a better position to do that, as we can detect graceful and clumsy exits more readily.
+    * (potential suggestion: `{ "closeOnExit": "10s" }`
+* The enumerator values for transitioning connection states will be useful for connections that require internet access.
+* Since the connection states are exposed through `TerminalControl`, they should be able to be data-bound to other Xaml elements. This can be used to provide discrete UI states for terminal controls, panes or tabs _hosting_ terminal controls.
+    * Example: a tab hosting a terminal control whose connection has been broken MAY display a red border.
+    * Example: an inactive tab that reaches the `Connected` state MAY flash to indicate that it is ready.

doc/specs/#605 - Search/spec.md

@@ -0,0 +1,126 @@
+---
+author: Kaiyu Wang KaiyuWang16
+created on: 2019-12-10
+last updated: 2019-12-10
+issue id: #605
+---
+
+# Search in Terminal
+
+## Abstract
+
+This spec is for feature request #605 "Search". It goes over the details of a new feature that allows users to search text in Terminal, within one tab or from all tabs. Expected behavior and design of this feature is included. Besides, future possible follow-up works are also addressed. 
+
+## Inspiration
+
+One of the superior features of iTerm2 is it's content search. The search comes in two variants: search from active tab and search from all tabs. In almost any editor, there is an roughly equivalent string search. We also want to realize search experience in Terminal. There will be two variants, search within one tab or from multiple tabs. We will start with one-tab search implementation. 
+
+## Solution Design
+
+Our ultimate goal is to provide both search within one tab and search from all tabs experiences. But we can start with one-tab search. The search experience should have following features:
+
+1. The search is triggered by KeyBindings. A new setting property named "find" will be enabled in the Json file. The user can set their own key bindings for search. The default is <kbd>ctrl+shift+f</kbd>. 
+2. The user search in a XAML TextBox, which is contained in a custom `SearchBoxControl`. The default position of the search box is the top right corner.
+3. We can have multiple search methods. The simplest one is exact text match. Other match methods include case-sensitive exact match and regex match. In the first phase, we will focus on case sensitive/insensitive text exact match. 
+4. If currently there is no active selection, the search starts from the last line of the mutableViewport. If there is an active selection, we start from the previous or the next text of the selected text. We automatically go around if we reach the start point of the search.
+5. The user should be able to fully interact with the terminal when the search box is on screen. 
+6. For accessibility concerns, the user should be able to navigate all the interactive elements on the search box using keyboard tab if the search box is focused. Searchbox could be created and closed with keyboard bindings. Close is usually bound to Esc.
+
+Conhost already has a module for search. It implements case sensitive or insensitive exact text match search, and it provides methods to select the found word. However, we want to make search as a shared component between Terminal and Console host. Now search module is part of Conhost, and its dependencies include BufferOut and some other types in ConHost such as SCREEN_INFORMATION. In order to make Search a shared component, we need to remove its dependency on ConHost types. BufferOut is already a shared component, but we need to make sure there is no other Conhost dependency.
+
+We will create a `SearchBoxControl` Xaml `UserControl` element. When a search process begins, a `SearchBoxControl` object will be created and attached to `TermControl` root grid. In other words, one SearchBox is added for each `TermControl`. The reasons for this design is:
+
+1. Each `TermControl` object is a Terminal Window and has a individual text buffer. In phase 1 we are going to search witin the current terminal text buffer. 
+2. If we put the search box under TerminalApp, then the search can only happen on the current focused Terminal. 
+3. If the community does not like the current design, we can lift SearchBox to a higher level. 
+
+### Search process implementation
+1. Once the user press <kbd>ctrl+shift+f</kbd> (or user's custom key binding), a new `SearchBoxControl` object will be created and attached as a child of `TermControl`. Focus will move to the TextBox within the `SearchBoxControl`. 
+2. Search is performed on a XAML TextBox. Once the user presses Enter or click up/down arrow button, we start to search from the last line of the current viewport or the current selection, and try to find the exact text in the text buffer. The nearest searched one will be selected. Then the search start point will be set to the selected text. The next search will start before or after the previous searched text.
+3. We re-use the Search module in conhost. It performs the search in a brute-force approach. Starting from every position in the text buffer, the search algorithm compares the span of the searched string with buffer characters, and if the current buffer text matches the whole string, it will return store the position of the text in the buffer and return. The stored position information will be used for selection. 
+3. The user can choose to search up or down. Search module realizes this, we just need to set a boolean flag. Default is search up. 
+4. The user can choose to do case sensitive or insensitive match. This also realized by Search module by setting a boolean flag. Default is search case-insensitively. 
+5. Tab navigation is realized by XAML. We just need to set TabNavigation="Cycle" in `SearchBoxControl`. 
+6. If the user clicks on the "X" button or press <kbd>Esc</kbd>, the search box will disappear and the object will be destructed and detached from the `TermControl` XAML tree. In phase one we do not store any state. 
+7. We need to guarantee full interaction with the terminal when the search box is open. To achieve this, search box and terminal input should be separated. If the current keyboard focus is on the search box, then keydown events will be handled on "search box level". 
+
+## UI/UX Design
+
+![SearchBox mockup](images/SearchBoxControl.png)
+
+Above is the `SearchBoxControl` in dark theme and light theme.
+  - The two buttons with up/down arrows controls the search direction, Each button will be styled to indicate which search direction is currently selected. 
+  - The button with a "Aa" icon, if pressed, means that we are searching case-sensitivily. 
+  - The current style puts all elements - the `X` button, the text box and the search pattern control buttons on one single line. This ensures that the `SearchBoxControl` won't be too high and block terminal text. This is similar with VSCode. Another possible layout style is to put elements in multiple layers. This will occupy more lines, but the search dialog will narrower. Considering that there is not many elements, we do not need multiple layers. 
+
+![SearchBox mockup, arrow button clicked](images/SearchBoxUpSelected.png)
+
+The search box defaults to be on the top right corner of the Terminal window. If the current tab is split into panes, each pane will have a individual searchbox. 
+
+#### Search process
+1. The user presses <kbd>ctrl+shift+f</kbd> (or user's custom key binding) to open the search box. Focus will move to the TextBox. 
+2. Search is performed on a XAML TextBox. Once the user presses Enter or click up/down arrow button, the search starts and searched text will be selected. Next search will be performed beginning from the current selection and go towards up/down. 
+3. The user can choose to search up or down by selecting up arrow or down arrow buttons. The chosen button will be styled to indicate it is selected. If the user does not click the arrows buttons, the default direction is up. 
+4. The user can choose to do case sensitive or insensitive match by checking a check box. The default is case insensitive. 
+5. If the search box is focused, the user can navigate all the elements on the search box using tab. When selected, press Enter equals to click. 
+6. If the user click the "X" button or press <kbd>Esc</kbd>, the search stopped and the search box disappears and focus will move back to Terminal.
+7. Once the search box is closed (exiting search mode), the selection will still be there. This coincides with the current VS Code and cmd experience. To get rid of the selection, the user can just click other area of the window.
+8. If the user clicks on the terminal when the search box is open, it will draw focus back to the terminal from the search box. The search box will still stay open. 
+9. The user can interact with the terminal when the search box is open, which means that the user can scroll the terminal content, or input text when the focus is on the terminal control. 
+10. If the user switches tabs while the search box is open, the focus will be moved back to the terminal. 
+
+## Capabilities
+
+1. The user can search exact matched text in the text buffer of the Terminal Screen. 
+2. The user can choose to search case sensitively and insensitively. 
+3. The user can search up or down. 
+4. Found text will be selected. 
+5. The search will start from the active selected text (inclusive) if there is one, or the end of the written text. 
+6. The search will automatically go around when it reaches the starting point.
+7. The user can use Tab to navigate all the elements in the search box. 
+8. The user can search in the opposite direction with <kbd>Shift + Enter</kbd> 
+
+### Accessibility
+
+The user should be able to use search by keyboard only.
+Once the searchbox is focused, the user can navigate between elements in the search box using Tab. And "click" using Enter. 
+
+### Security
+
+This feature should not introduce any new security issues.
+
+### Reliability
+
+1. The key input of Terminal command line and the search box should be separated. Search box should not block interaction with the command line when it is open. 
+2. The search box should not block too much text. The search box only occupies one line, so it won't have big impact on the readibility of the terminal output. 
+
+### Compatibility
+
+This feature won't break existing features of Terminal.
+
+### Performance, Power, and Efficiency
+
+This feature only launches in need. It does not impact the performance of Terminal. 
+
+## Potential Issues
+                                                              
+1. If the terminal window is not wide enough for the search box to be visible, the buttons on the right of the `TextBox` will become invisible, but the `TextBox` is still visible and the window could not be narrower than the `TextBox`. This is similar to the behavior of other editors. Please see the image below:
+   ![SearchBox width not enough](images/SearchBoxControlNoEnoughWidth.png)
+2. If the terminal window is not high enough for the search box to be visible, the whole terminal screen, inlcuding the `SearchBoxControl` can disappear. This is similar to the behavior of other editors.
+
+## Future considerations
+
+In version 1, we want realize a case sensitive/insensitive exact text match. But we may consider the following features in version 2:
+
+1. Add "Find" button in dropdown menu to trigger search. This enables the search feature to be operated with mouse only. However, this is not required by Accessibility so we do not cover this in phase one. 
+2. Search from all tabs. For Version 1 we just want to realize search within one tab. However, the community also requests search from all tabs. This may require a big change to the search algorithm, but it is not seen as a popular use scenario, so we put it future phase. To implement multi-tab search, we can let TerminalPage or App own a `SearchBoxControl` object, and provide the text buffer of the current focused terminal. We need to change the search algorithm.  
+3. Regular expression match. This is a useful search pattern and is implemented in some editors. However, this use scenario is not used as much as exact text search, thus, we put it in future phase.
+4. Search history. Sometimes users would do the same search for several times, thus, storing the search history is useful. This is not realized by VSCode so it would be a good highlighting point in the future. 
+5. High-light while you type. Emphasizing all the other matches in the buffer with an outline or selection with another color. This provides a clearer view of searched text. But we need to change the search and selection algorithm, so we put it in the future phase. 
+6. Add size handle. Some text editors let the user resize the search box, and there is a size handle on the left side of the search box. This helps user when they search for long text. If the community desires it we may add a similar feature.
+
+This open issue tracks the phase features of Search: https://github.com/microsoft/terminal/issues/3920
+
+## Resources
+
+Github Issue: https://github.com/microsoft/terminal/issues/605

doc/terminal-v1-roadmap.md

@@ -20,14 +20,14 @@ Ultimately, we're aiming for Terminal v1.0 to be feature-complete by Dec 2019, a
 
 > ⚠ Note: Terminal v1.0 will be a quality-oriented release driven in large part by the community. So, ___if you see bugs, find/file them___!
 
-| Milestone end date | Phase | Key features |
+| Milestone end date                   | Milestone Name | Key Deliverables |
 | --- | --- | --- |
 | 2019-05-07 | [Announcement](https://devblogs.microsoft.com/commandline/introducing-windows-terminal/) | Terminal announced & open-sourced ([Build 2019 Terminal session](https://www.youtube.com/watch?v=KMudkRcwjCw), ["Sizzle" video](https://www.youtube.com/watch?v=8gw0rXPMMPE&list=PLEHMQNlPj-Jzh9DkNpqipDGCZZuOwrQwR&index=2&t=0s)) |
 | 2019-07-09 | [v0.2 (update)](https://github.com/microsoft/terminal/releases/tag/v0.2.1831.0) | First version of the Terminal released via the Microsoft Store, fundamental features in place, basic tab control, basic UI layout, config & settings via JSON file |
 | 2019-08-02 | [v0.3](https://github.com/microsoft/terminal/releases/tag/v0.3.2142.0) | Major UI improvements, improved tab bar layout & color, basic a11y support, Azure Cloud Shell connection |
 | 2019-08-27 | [v0.4](https://github.com/microsoft/terminal/releases/tag/v0.4.2382.0) | HTML Copy, Tab Titles, Double/Triple Click Selection, Local Settings, JSON settings validation, A11y improvements |
 | 2019-09-24 | [1909]( http://devblogs.microsoft.com/commandline/windows-terminal-preview-1909) | Stability & Quality improvements, installs [Cascadia Code](https://github.com/microsoft/cascadia-code) font, adds JSON schema to `profiles.json` settings file enabling Intellisense in VSCode, etc. |
-| 2019-10-22 | 1910 | Cascading Settings, Dynamic Profiles |
+| 2019-10-22 | [1910](https://devblogs.microsoft.com/commandline/windows-terminal-preview-1910-release/) | Cascading Settings, Dynamic Profiles |
 | 2019-11-19 | 1911 | Final v1.0 feature work |
 | 2019-12-17 | 1912 | "Feature Complete" - All v1.0 Features in-place |
 | Winter Vacation | N/A | None planned |
@@ -58,13 +58,13 @@ Incoming issues/asks/etc. are triaged several times a week, labelled appropriate
 * P1/2 issues/features/asks  assigned to the current or future milestone, or to the [Terminal v1.0 milestone](https://github.com/microsoft/terminal/milestone/6) for future assignment, if required to deliver a v1.0 feature
 * Issues/features/asks not on our list of v1.0 features is assigned to the [Terminal Backlog](https://github.com/microsoft/terminal/milestone/7) for subsequent triage, prioritization & scheduling.
 
-## v1.0 Features
+## v1.0 Scenarios
 
-The following are a list of the key features/feature-areas we're aiming to deliver for Terminal v1.0.
+The following are a list of the key scenarios we're aiming to deliver for Terminal v1.0.
 
 > 👉 Note: There are many other features that don't fit within v1.0, but will be re-assessed and prioritized for v2.0, the plan for which will be published in early in 2020.
 
-| Release | Priority\* | Feature | Description/Notes |
+| Release | Priority\* | Scenario | Description/Notes |
 | --- | --- | --- | --- |
 | V1 | 0 | Performance & Efficiency | Terminal shall be fast and efficient. Input latency should be eliminated wherever possible. Terminal will be very memory-efficient, and will avoid utilizing unnecessary dependencies to minimize memory consumption and disk footprint |
 | V1 | 0 | Reliability | Every reasonable step should be taken to ensure that Terminal will not crash unexpectedly. Crashing is considered harmful to the user's well-being & state of mind. Crashing issues are prioritized Pri-0 by default |

doc/user-docs/ThirdPartyToolProfiles.md

@@ -0,0 +1,67 @@
+# Adding profiles for third-party tools
+
+This doc will hopefully provide a useful guide for adding profiles for common
+third-party tools to your
+[profiles.json](https://github.com/microsoft/terminal/blob/master/doc/user-docs/UsingJsonSettings.md)
+file.
+
+All of these profiles are provided _without_ their `guid` set. If you'd like to
+set any of these profiles as your _default_ profile, you'll need to make sure to
+[generate a unique guid](https://www.guidgenerator.com/) for them manually.
+
+## Anaconda
+
+Assuming that you've installed Anaconda into `%USERPROFILE%\Anaconda3`:
+
+```json
+{
+    "commandline" : "cmd.exe /K %USERPROFILE%\\Anaconda3\\Scripts\\activate.bat %USERPROFILE%\\Anaconda3",
+    "icon" : "%USERPROFILE%/Anaconda3/Menu/anaconda-navigator.ico",
+    "name" : "Anaconda3",
+    "startingDirectory" : "%USERPROFILE%"
+}
+```
+
+## cmder
+
+Assuming that you've installed cmder into `%CMDER_ROOT%`:
+
+```json
+{
+    "commandline" : "cmd.exe /k %CMDER_ROOT%\\vendor\\init.bat",
+    "name" : "cmder",
+    "startingDirectory" : "%USERPROFILE%"
+}
+```
+
+## Cygwin
+
+Assuming that you've installed Cygwin into `C:/Cygwin`:
+
+```json
+{
+    "name" : "Cygwin",
+    "commandline" : "C:/Cygwin/bin/bash --login -i",
+    "icon" : "C:/Cygwin/Cygwin.ico",
+    "startingDirectory" : "C:/Cygwin/bin"
+}
+```
+
+Note that the starting directory of Cygwin is set as it is to make the path
+work. The default directory opened when starting Cygwin will be `$HOME` because
+of the `--login` flag.
+
+## Git Bash
+
+Assuming that you've installed Git Bash into `C:/Program Files/Git`:
+
+```json
+{
+    "name" : "Git Bash",
+    "commandline" : "C:/Program Files/Git/bin/bash.exe",
+    "icon" : "C:/Program Files/Git/mingw64/share/git/git-for-windows.ico",
+    "startingDirectory" : "%USERPROFILE%"
+}
+````
+
+<!-- Adding a tool here? Make sure to add it in alphabetical order! -->

doc/user-docs/UsingJsonSettings.md

@@ -4,7 +4,7 @@ One way (currently the only way) to configure Windows Terminal is by editing the
 `profiles.json` settings file. At the time of writing you can open the settings
 file in your default editor by selecting `Settings` from the WT pull down menu.
 
-The settings are stored in the file `$env:LocalAppData\Packages\Microsoft.WindowsTerminal_<randomString>\LocalState\profiles.json`.
+The settings are stored in the file `$env:LocalAppData\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\profiles.json`.
 
 As of [#2515](https://github.com/microsoft/terminal/pull/2515), the settings are
 split into _two_ files: a hardcoded `defaults.json`, and `profiles.json`, which
@@ -72,6 +72,24 @@ For example, here's a sample of the default keybindings:
 
 ```
 
+### Unbinding keys
+
+If you ever come across a key binding that you're unhappy with, it's possible to
+easily change the keybindings. For example, vim uses <kbd>Ctrl+^</kbd> as a
+binding for "switch to previous buffer", which conflicts with the Terminal's
+default keybinding for "open a new tab with the sixth profile". If you'd like to
+unbind that keybinding, and allow the keystroke to fall through to vim, you can
+add the following to your keybindings:
+
+```json
+{
+    "command" : null, "keys" : ["ctrl+shift+6"]
+},
+```
+
+This will _unbind_ <kbd>Ctrl+Shift+6</kbd>, allowing vim to use the keystroke
+instead of the terminal.
+
 ## Profiles
 
 A profile contains the settings applied when a new WT tab is opened. Each
@@ -162,7 +180,7 @@ would like to only change the color scheme of the default `cmd` profile to
         }
 ```
 
-Here, we're know we're changing the `cmd` profile, because the `guid`
+Here, we know we're changing the `cmd` profile, because the `guid`
 `"{0caa0dad-35be-5f56-a8ff-afceeeaa6101}"` is `cmd`'s unique GUID. Any profiles
 with that GUID will all be treated as the same object. Any changes in that
 profile will overwrite those from the defaults.
@@ -183,6 +201,11 @@ When dynamic profiles are created at runtime, they'll be added to the
 a linux distro, then the profile will remain in your `profiles.json` file, but
 the profile will be hidden.
 
+The Windows Terminal uses the `guid` property of these dynamically-generated
+profiles to uniquely identify them. If you try to change the `guid` of a
+dynamically-generated profile, the Terminal will automatically recreate a new
+entry for that profile.
+
 If you'd like to disable a particular dynamic profile source, you can add that
 `source` to the global `"disabledProfileSources"` array. For example, if you'd
 like to hide all the WSL profiles, you could add the following setting:
@@ -194,6 +217,119 @@ like to hide all the WSL profiles, you could add the following setting:
 
 ```
 
+### Default settings
+
+In [#2325](https://github.com/microsoft/terminal/issues/2325), we introduced the
+concept of "Default Profile Settings". These are settings that will apply to all
+of your profiles by default. Profiles can still override these settings
+individually. With default profile settings, you can easily make changes to all
+your profiles at once. For example, given the following settings:
+
+```json
+    "defaultProfile": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
+    "profiles":
+    [
+        {
+            "guid": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
+            "name": "Windows PowerShell",
+            "commandline": "powershell.exe",
+            "fontFace": "Cascadia Code",
+            "fontSize": 14
+        },
+        {
+            "guid": "{0caa0dad-35be-5f56-a8ff-afceeeaa6101}",
+            "name": "cmd",
+            "commandline": "cmd.exe",
+            "fontFace": "Cascadia Code",
+            "fontSize": 14
+        },
+        {
+            "commandline" : "cmd.exe /k %CMDER_ROOT%\\vendor\\init.bat",
+            "name" : "cmder",
+            "startingDirectory" : "%USERPROFILE%",
+            "fontFace": "Cascadia Code",
+            "fontSize": 14
+        }
+    ],
+```
+
+All three of these profiles are using "Cascadia Code" as their `"fontFace"`, and
+14 as their `fontSize`. With default profile settings, you can easily set these
+properties for all your profiles, like so:
+
+```json
+    "defaultProfile": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
+    "profiles": {
+        "defaults":
+        {
+            "fontFace": "Cascadia Code",
+            "fontSize": 14
+        },
+        "list": [
+            {
+                "guid": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
+                "name": "Windows PowerShell",
+                "commandline": "powershell.exe",
+            },
+            {
+                "guid": "{0caa0dad-35be-5f56-a8ff-afceeeaa6101}",
+                "name": "cmd",
+                "commandline": "cmd.exe"
+            },
+            {
+                "commandline" : "cmd.exe /k %CMDER_ROOT%\\vendor\\init.bat",
+                "name" : "cmder",
+                "startingDirectory" : "%USERPROFILE%"
+            }
+        ],
+    }
+```
+
+Note that the `profiles` property has changed in this example from a _list_ of
+profiles, to an _object_ with two properties:
+* a `list` that contains the list of all the profiles
+* the new `defaults` object, which contains all the settings that should apply to
+  every profile.
+
+What if I wanted a profile to have a different value for a property other than
+the default? Simply set the property in the profile's entry to override the
+value from `defaults`. Let's say you want the `cmd` profile to have _"Consolas"_
+as the font, but the rest of your profiles to still have _"Cascadia Code"_. You
+could achieve that with the following:
+
+```json
+    "defaultProfile": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
+    "profiles": {
+        "defaults":
+        {
+            "fontFace": "Cascadia Code",
+            "fontSize": 14
+        },
+        "list": [
+            {
+                "guid": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
+                "name": "Windows PowerShell",
+                "commandline": "powershell.exe",
+            },
+            {
+                "guid": "{0caa0dad-35be-5f56-a8ff-afceeeaa6101}",
+                "name": "cmd",
+                "commandline": "cmd.exe",
+                "fontFace": "Consolas"
+            },
+            {
+                "commandline" : "cmd.exe /k %CMDER_ROOT%\\vendor\\init.bat",
+                "name" : "cmder",
+                "startingDirectory" : "%USERPROFILE%"
+            }
+        ],
+    }
+```
+
+In the above settings, the `"fontFace"` in the `cmd.exe` profile overrides the
+`"fontFace"` from the `defaults`.
+
+
 ## Configuration Examples:
 
 ### Add a custom background to the WSL Debian terminal profile
@@ -241,6 +377,8 @@ following objects into your `globals.keybindings` array:
 { "command": "paste", "keys": ["ctrl+shift+v"] }
 ```
 
+> 👉 **Note**: you can also add a keybinding for the `copyTextWithoutNewlines` command. This removes newlines as the text is copied to your clipboard.
+
 This will add copy and paste on <kbd>ctrl+shift+c</kbd>
 and <kbd>ctrl+shift+v</kbd> respectively.
 
@@ -270,8 +408,33 @@ You can even set multiple keybindings for a single action if you'd like. For exa
 will bind both <kbd>ctrl+shift+v</kbd> and
 <kbd>shift+Insert</kbd> to `paste`.
 
-Note: If you set your copy keybinding to `"ctrl+c"`, you'll only be able to send
+> 👉 **Note**: If you set your copy keybinding to `"ctrl+c"`, you'll only be able to send
 an interrupt to the commandline application using <kbd>Ctrl+C</kbd> when there's
 no text selection. Additionally, if you set `paste` to `"ctrl+v"`, commandline
 applications won't be able to read a ctrl+v from the input. For these reasons,
 we suggest `"ctrl+shift+c"` and `"ctrl+shift+v"`
+
+
+### Setting the `startingDirectory` of WSL Profiles to `~`
+
+By default, the `startingDirectory` of a profile is `%USERPROFILE%`
+(`C:\Users\<YourUsername>`). This is a Windows path. However, for WSL, you might
+want to use the WSL home path instead. At the time of writing (26decf1 / Nov.
+1st, 2019), `startingDirectory` only accepts a Windows-style path, so setting it
+to start within the WSL distro can be a little tricky.
+
+Fortunately, with Windows 1903, the filesystems of WSL distros can easily be
+addressed using the `\\wsl$\` prefix. For any WSL distro whose name is
+`DistroName`, you can use `\\wsl$\DistroName` as a Windows path that points to
+the root of that distro's filesystem.
+
+For example, the following works as a profile to launch the "Ubuntu-18.04"
+distro in it's home path:
+
+```json
+{
+    "name": "Ubuntu-18.04",
+    "commandline" : "wsl -d Ubuntu-18.04",
+    "startingDirectory" : "//wsl$/Ubuntu-18.04/home/<Your Ubuntu Username>",
+}
+```

doc/user-docs/index.md

@@ -3,7 +3,7 @@
 NOTE: At the time of writing Windows Terminal is still under active development and many things will
 change. If you notice an error in the docs, please raise an issue. Or better yet, please file a PR with an appropriate update!
 
-## Installing Windows Terminal 
+## Installing Windows Terminal
 
 ### From Source Code
 
@@ -18,12 +18,10 @@ To compile Windows Terminal yourself using the source code, follow the instructi
 
 ## Starting Windows Terminal
 
-From the Windows Start menu, select Windows Terminal and run the application.
-
-Note: You can right click on the application item and run with Windows Administrator privilege if required.
-
-The default shell is PowerShell.
+1. Locate the _Windows Terminal_ app in your Start menu.
+2. Click _Windows Terminal_ to launch the app. If you need administrative privileges, right-click the entry and click `Run as administrator`. Alternatively, you can highlight the app and press `Ctrl`+`Shift`+`Enter`.
 
+NOTE: The default shell is PowerShell; you can change this using the _Running a Different Shell_ procedure.
 
 ### Command line options
 
@@ -32,7 +30,7 @@ None at this time. See issue [#607](https://github.com/microsoft/terminal/issues
 ## Multiple Tabs
 
 Additional shells can be started by hitting the `+` button from the tab bar -- a new instance of the
-default shell is displayed (default shortcut `Ctrl+Shift+1`).
+default shell is displayed (default shortcut: <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>1</kbd>).
 
 ## Running a Different Shell
 
@@ -49,17 +47,17 @@ To customize the shell list, see the _Configuring Windows Terminal_ section belo
 
 There is no current plan to support this feature for security reasons. See issue [#623](https://github.com/microsoft/terminal/issues/632)
 
-## Using cut and paste in the Terminal window
+## Selecting and Copying Text in Windows Terminal
 
-### With PowerShell
+As in ConHost, a selection can be made by left-clicking and dragging the mouse across the terminal. This is a line selection by default, meaning that the selection will wrap to the end of the line and the beginning of the next one. You can select in block mode by holding down the <kbd>Alt</kbd> key when starting a selection.
 
-* Copy - Select the text with mouse (default left button), then right click with mouse
-* Paste - by default use `<ctrl>+v`>, or right click with mouse
+To copy the text to your clipboard, you can right-click the terminal when a selection is active. As of [#1224](https://github.com/microsoft/terminal/pull/1224) (first available in Windows Terminal v0.4), the Windows Terminal now supports HTML copy. The HTML is automatically copied to your clipboard along with the regular text in any copy operation.
 
-### With Bash
+If there is not an active selection, a right-click will paste the text content from your clipboard to the terminal.
 
-* Copy - Select the text with mouse (default left button), then right click with mouse
-* Paste - Right click with mouse
+Copy and paste operations can also be keybound. For more information on how to bind keys, see [Using Json Settings](UsingJsonSettings.md#adding-copy-and-paste-keybindings).
+
+> 👉 **Note**: If you have the `copyOnSelect` global setting enabled, a selection will persist and immediately copy the selected text to your clipboard. Right-clicking will always paste your clipboard data.
 
 ## Add a "Open Windows Terminal Here" to File Explorer
 
@@ -72,7 +70,7 @@ All Windows Terminal settings are currently managed using the `profiles.json` fi
 To open the settings file from Windows Terminal:
 
 1. Click the `⌵` button in the top bar.
-2. From the dropdown list, click `Settings`. You can also use a shortcut: `Ctrl+,`.
+2. From the dropdown list, click `Settings`. You can also use a shortcut: <kbd>Ctrl</kbd>+<kbd>,</kbd>.
 3. Your default `json` editor will open the settings file.
 
 For an introduction to the various settings, see [Using Json Settings](UsingJsonSettings.md). The list of valid settings can be found in the [profiles.json documentation](../cascadia/SettingsSchema.md) section.
@@ -86,6 +84,6 @@ For an introduction to the various settings, see [Using Json Settings](UsingJson
 
     (ref https://twitter.com/r_keith_hill/status/1142871145852440576)
 
-2. Terminal zoom can be changed by holding `Ctrl` and scrolling with mouse.
-3. If `useAcrylic` is enabled in profiles.json, background opacity can be changed by holding `Ctrl+Shift` and scrolling with mouse.
+2. Terminal zoom can be changed by holding <kbd>Ctrl</kbd> and scrolling with mouse.
+3. If `useAcrylic` is enabled in profiles.json, background opacity can be changed by holding <kbd>Ctrl</kbd>+<kbd>Shift</kbd> and scrolling with mouse.
 4. Please add more Tips and Tricks

pkg/appx/OpenConsolePackage.wapproj

@@ -1,86 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<Project ToolsVersion="15.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
-  <Import Project="..\..\common.openconsole.props" Condition="'$(OpenConsoleDir)'==''" />
-  <Import Project="$(OpenConsoleDir)src\wap-common.build.pre.props" />
-
-  <PropertyGroup Label="Configuration">
-    <TargetPlatformVersion>10.0.17763.0</TargetPlatformVersion>
-    <TargetPlatformMinVersion>10.0.17134.0</TargetPlatformMinVersion>
-    <!--
-    These two properties are very important!
-    Without them, msbuild will stomp MinVersion and MaxVersionTested in the
-    Package.appxmanifest and replace them with whatever our values for
-    TargetPlatformMinVersion and TargetPlatformVersion are.
-     -->
-    <AppxOSMinVersionReplaceManifestVersion>false</AppxOSMinVersionReplaceManifestVersion>
-    <AppxOSMaxVersionTestedReplaceManifestVersion>false</AppxOSMaxVersionTestedReplaceManifestVersion>
-
-    <!-- In a WAP project, this suppresses a spurious dependency on the non-Desktop VCLibs. -->
-    <IncludeGetResolvedSDKReferences>false</IncludeGetResolvedSDKReferences>
-
-    <!-- Suppress the inclusion of Windows.winmd in the appx. -->
-    <SkipUnionWinmd>true</SkipUnionWinmd>
-  </PropertyGroup>
-
-  <PropertyGroup>
-    <ProjectGuid>2D310963-F3E0-4EE5-8AC6-FBC94DCC3310</ProjectGuid>
-
-    <EntryPointExe>OpenConsole.exe</EntryPointExe>
-    <EntryPointProjectUniqueName>..\..\src\host\exe\Host.EXE.vcxproj</EntryPointProjectUniqueName>
-  </PropertyGroup>
-
-  <PropertyGroup>
-    <GenerateAppInstallerFile>False</GenerateAppInstallerFile>
-  </PropertyGroup>
-
-  <PropertyGroup Condition="!Exists('OpenConsolePackage_TemporaryKey.pfx')">
-    <AppxPackageSigningEnabled>false</AppxPackageSigningEnabled>
-    <AppxBundle>Never</AppxBundle>
-  </PropertyGroup>
-
-  <PropertyGroup Condition="Exists('OpenConsolePackage_TemporaryKey.pfx')">
-    <AppxPackageSigningEnabled>true</AppxPackageSigningEnabled>
-    <AppxAutoIncrementPackageRevision>False</AppxAutoIncrementPackageRevision>
-    <PackageCertificateKeyFile>OpenConsolePackage_TemporaryKey.pfx</PackageCertificateKeyFile>
-  </PropertyGroup>
-
-  <ItemGroup Condition="Exists('OpenConsolePackage_TemporaryKey.pfx')">
-    <None Include="OpenConsolePackage_TemporaryKey.pfx" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <AppxManifest Include="Package.appxmanifest">
-      <SubType>Designer</SubType>
-    </AppxManifest>
-  </ItemGroup>
-
-  <ItemGroup>
-    <Content Include="images\LockScreenLogo.scale-200.png" />
-    <Content Include="images\Square150x150Logo.scale-200.png" />
-    <Content Include="images\Square44x44Logo.scale-200.png" />
-    <Content Include="images\Square44x44Logo.targetsize-16_altform-unplated.png" />
-    <Content Include="images\Square44x44Logo.targetsize-24_altform-unplated.png" />
-    <Content Include="images\Square44x44Logo.targetsize-32_altform-unplated.png" />
-    <Content Include="images\Square44x44Logo.targetsize-48_altform-unplated.png" />
-    <Content Include="images\Square44x44Logo.targetsize-256_altform-unplated.png" />
-    <Content Include="images\StoreLogo.png" />
-    <Content Include="images\Wide310x150Logo.scale-200.png" />
-  </ItemGroup>
-
-  <Import Project="$(OpenConsoleDir)src\wap-common.build.post.props" />
-
-  <ItemGroup>
-    <ProjectReference Include="..\..\src\host\exe\Host.EXE.vcxproj" />
-    <ProjectReference Include="..\..\src\propsheet\propsheet.vcxproj" />
-  </ItemGroup>
-
-  <Target Name="OpenConsoleStompSourceProjectForWapProject" BeforeTargets="_ConvertItems">
-    <ItemGroup>
-      <_TemporaryFilteredWapProjOutput Include="@(_FilteredNonWapProjProjectOutput)" />
-      <_FilteredNonWapProjProjectOutput Remove="@(_FilteredNonWapProjProjectOutput)" />
-      <_FilteredNonWapProjProjectOutput Include="@(_TemporaryFilteredWapProjOutput)">
-        <SourceProject></SourceProject> <!-- Blank SourceProject, which WapProj uses to name subdirectories. -->
-      </_FilteredNonWapProjProjectOutput>
-    </ItemGroup>
-  </Target>
-</Project>

pkg/appx/Package.appxmanifest

@@ -1,34 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<Package xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10" xmlns:mp="http://schemas.microsoft.com/appx/2014/phone/manifest" xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10" xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities" xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3" xmlns:uap5="http://schemas.microsoft.com/appx/manifest/uap/windows10/5" xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10" xmlns:desktop4="http://schemas.microsoft.com/appx/manifest/desktop/windows10/4" IgnorableNamespaces="uap mp rescap">
-  <Identity Name="Microsoft.WindowsConsoleHost" Publisher="CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US" Version="0.9.0.0" />
-  <Properties>
-    <DisplayName>Windows Console (Preview)</DisplayName>
-    <PublisherDisplayName>Microsoft Corporation</PublisherDisplayName>
-    <Logo>images\StoreLogo.png</Logo>
-  </Properties>
-  <Dependencies>
-    <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.14393.0" MaxVersionTested="10.0.14393.0" />
-  </Dependencies>
-  <Resources>
-    <Resource Language="x-generate" />
-  </Resources>
-  <Applications>
-    <Application Id="App" Executable="OpenConsole.exe" EntryPoint="$targetentrypoint$">
-      <Extensions>
-        <uap3:Extension Category="windows.appExecutionAlias" EntryPoint="Windows.FullTrustApplication" Executable="OpenConsole.exe">
-          <uap3:AppExecutionAlias>
-            <desktop:ExecutionAlias Alias="OpenConsole.exe" />
-            <desktop:ExecutionAlias Alias="confans.exe" />
-          </uap3:AppExecutionAlias>
-        </uap3:Extension>
-      </Extensions>
-      <uap:VisualElements DisplayName="Windows Console (Preview)" Description="The Windows Console, but actually fun!" BackgroundColor="transparent" Square150x150Logo="images\Square150x150Logo.png" Square44x44Logo="images\Square44x44Logo.png">
-        <uap:DefaultTile Wide310x150Logo="images\Wide310x150Logo.png">
-        </uap:DefaultTile>
-      </uap:VisualElements>
-    </Application>
-  </Applications>
-  <Capabilities>
-    <rescap:Capability Name="runFullTrust" />
-  </Capabilities>
-</Package>

res/README.md

@@ -18,4 +18,4 @@ Please consult the [license](https://raw.githubusercontent.com/microsoft/cascadi
 ### Fonts Included
 
 * Cascadia Code
-   * from microsoft/cascadia-code@5f91b87e12c9af709fa406c22a79145879edc3d2
+   * from microsoft/cascadia-code@d733599504811e8f3969de20368817d20e162dba