more details and clarity

doc/specs/Proto extensions-spec.md

@@ -40,14 +40,12 @@ in between 2 and 3:
    1. modifications to existing profiles
    2. additions of full profiles
    3. additions of colour schemes
-   4. modifications to colour schemes
 4. Layer the user settings on top of all the profiles created in steps 1 through 3
 5. Validate the settings
 
 ### Specifications of the json stubs
 
-As written above, the json stubs could be modifications to existing profiles, additions to full profiles, modifications to
-existing colour schemes or additions of colour schemes.
+As written above, the json stubs could be modifications to existing profiles, additions to full profiles, or additions of colour schemes.
 
 #### Modifications to existing profiles
 
@@ -59,10 +57,10 @@ Note that currently, we generate a GUID for dynamic profiles using the "initial"
 any user changes are applied). For example, the "initial" name of a WSL profile is the \<name\> argument to
 "wsl.exe -d \<name\>", and the "initial" name of a Powershell profile is something like "Powershell (ARM)" - depending
 on the version. Thus, the stub creator could simply use the same uuidv5 GUID generator we do on that name to obtain the
-GUID. Then, in the stub they provide the GUID can be used to identify which profile to modify. 
+GUID. Then, in the stub they provide the GUID can be used to identify which profile to modify.
 
-Since dynamic profiles also have a "source" field which we use as matching criteria, the stub would also need to
-have that field if it wants to modify a dynamic profile. These are just static strings that we can easily provide. 
+Naturally, we will have to provide documentation on how they could generate the desired GUID themselves. In that documentation,
+we will also provide examples showing how the current GUIDs are generated for clarity's sake. 
 
 We might run into the case where multiple json stubs modify the same profile and so they override each other. For the initial implementation, we
 are simply going to apply _all_ the changes. Eventually, we will probably want some sort of hierarchy to determine
@@ -73,12 +71,24 @@ Here is an example of a json stub that modifies an existing profile (specificall
 ```js
 {
     "guid": "{b453ae62-4e3d-5e58-b989-0a998ec441b8}",
-    "source": "Windows.Terminal.Azure",
     "fontSize": 16,
     "fontWeight": "thin"
 }
 ```
 
+**NOTE**: This will *not* change the way the profile looks in the user's settings file. The Azure cloud shell profile
+in their settings file (assuming they have made no changes) will still be as below. 
+
+```js
+{
+    "guid": "{b453ae62-4e3d-5e58-b989-0a998ec441b8}",
+    "hidden": false,
+    "name": "Azure Cloud Shell",
+    "source": "Windows.Terminal.Azure"
+}
+```
+However, the user is free to make changes to it as usual and those changes will have the 'final say'. 
+
 #### Full profile stubs
 
 Technically, full profile stubs do not need to contain anything (they could just be '\{\}'). However we should
@@ -92,6 +102,10 @@ new profile objects from stubs that contain at least the following
 As in the case of the dynamic profile generator, if we create a profile that did not exist before (i.e. does not
 exist in the user settings), we need to add the profile to the user settings file and re-save that file.
 
+Furthermore, we will add a source field to profiles created this way (again, similar to what we do for dynamic profiles).
+The source field value is dependent on how we obtained this json file, and will be touched on in more detail later in the
+spec (see "Creation and location(s) of the json files" - "The source field"). 
+
 Here is an example of a json stub that contains a full profile:
 
 ```js
@@ -105,26 +119,88 @@ Here is an example of a json stub that contains a full profile:
 }
 ```
 
-#### Colour schemes
+When this profile gets added back to the user's settings file, it will look similar to the way we currently add
+new dynamic profiles to the user's settings file. Going along with the example above, the corresponding
+json stub in the user's settings file will be:
+
+```js
+{
+    "guid": "{a821ae62-9d4a-3e34-b989-0a998ec283e6}",
+    "name": "Cool Profile",
+    "hidden": "false",
+    "source": "local"
+}
+```
+Again, the user will be able to make changes to it as they do for all other profiles. 
+
+#### Creation of colour schemes
+
+As with full profiles, we will have some qualifying criteria for what we accept as full colour schemes: color schemes
+must have
+* A name
+* A background
+* A foreground
+
+This will cause the issue of colour schemes being overridden if there are many creations of a colour scheme with the
+same name. Since for now all we have to uniquely identify colour schemes *is* the name, we will just let this be.
 
-Once again, we could run into the problem of several json stubs wanting to modify the same colour scheme. We
-will require a hierarchy here as well. Though since the 'owner' of a colour scheme is a lot more dubious, I wonder
-if we should only allow creation of new colour schemes for now and ignore requests to modify existing colour
-schemes. 
+Here is an example of a json stub that contains a colour scheme:
+
+```js
+{
+    "name": "Postmodern Tango Light",
+    "background": '#61D6D6',
+    "foreground": '#E74856'
+}
+```
+
+This stub will *not* show up in the users settings file, similar to the way our default colour schemes do not show up.
 
 ### Creation and location(s) of the json files
 
 #### For apps installed through Microsoft store (or similar)
 
 For apps that are installed through something like the Microsoft Store, they should add their json file(s) to
 an app extension. During our profile generation, we will probe the OS for app extensions of this type that it
-knows about and obtain the json files.
+knows about and obtain the json files or objects. These apps should should use msappx for us to know about
+their extensions.
 
 #### For apps installed 'traditionally' and third parties/independent users
 
-For apps that are installed 'traditionally', their installer could simply add a json file to a specific local folder
-(specified by us) that we will look through every time we generate profiles. This is also where independent users will
-add their own json files for Terminal to generate/modify profiles. 
+For apps that are installed 'traditionally', there are 2 cases. The first is that this installation is for all
+the users of the system - in this case, the installer should add their json files to the global folder:
+
+```
+C:\ProgramData\Microsoft\Windows\Terminal
+```
+
+Note: `C:\ProgramData` is a [known folder](https://docs.microsoft.com/en-us/previous-versions/windows/desktop/legacy/bb776911(v=vs.85))
+that apps should be able to access. It will be on us to create the folder `Terminal` in `C:\ProgramData\Microsoft\Windows` for this to happen. 
+
+In the second case, the installation is only for the current user. For this case, the installer should add the
+json files to the local folder:
+
+```C:\Users\<user>\AppData\Local\Microsoft\Windows\Terminal```
+
+This is also where independent users will add their own json files for Terminal to generate/modify profiles.
+
+We will look through both folders mentioned above during profile generation. 
+
+#### The source field
+
+Currently, we allow users an easy way to disable/enable profiles that are generated from certain sources. For
+example, a user can easily hide all dynamic profiles with the source `"Windows.Terminal.Wsl"` if they wish to.
+To retain this functionality, we will add source fields to profiles we create through proto-extensions. 
+
+For full profiles that came from the *global* folder `C:\ProgramData\Microsoft\Windows\Terminal`,
+we will give the value `global` to the source field.
+
+For full profiles that came from the *local* folder `C:\Users\<user>\AppData\Local\Microsoft\Windows\Terminal`,
+we will give the value `local` to the source field.
+
+For full profiles that came from app extensions, we will the value `app` to the source field.
+
+
 
 ## UI/UX Design
 
@@ -163,12 +239,11 @@ Looking through the additional json files could negatively impact startup time.
 
 Cases which would likely be frustrating:
 
-* An installer dumps a _lot_ of json files into the folder which we need to look through
-* An installer dumps some badly formatted settings that cause our validate settings check to fail, resulting in default settings being used everywhere
+* An installer dumps a _lot_ of json files into the folder which we need to look through.
 
 ## Future considerations
 
-How would this affect the Settings UI? 
+How will this affect the settings UI?
 
 ## Resources