Update 'README.md'

README.md

@@ -66,12 +66,14 @@ OAuth3 is intended to work in URL-based flows such as `https://`, `app://`, and
 
 Just a quick intro to vocabulary that will be explained more thoroughly later on:
 
-* **subject** - typically a username or email address that references the real, live person that we care about
+* **subject** (**sub**)- typically a username or email address that references the real, live person that we care about
-* **issuer** - the service or device that issues tokens (or manages public keys). In the old-world model this is Facebook, Twitter, etc
+* **issuer** (**iss**) - the service or device that issues tokens (or manages public keys). In the old-world model this is Facebook, Twitter, etc
-* **audience** - the service or device that exchanges tokens for goods or services. In the old-world model this is Facebook, Twitter, etc
+* **audience** (**aud**) - the service or device that exchanges tokens for goods or services. In the old-world model this is Facebook, Twitter, etc
-* **authorized party** - the service or device that uses tokens to accomplish the subject's goals. In the old-world model this is a site that has a "Login with Facebook" button
+* **authorized party** (**azp**) - the service or device that uses tokens to accomplish the subject's goals. In the old-world model this is a site that has a "Login with Facebook" button
 
-### There are 4 potential Identity Delegation styles
+## There are 4 potential Identity Delegation styles
+
+The following are just sample UX to show the difference in the styles. Typically, a single UX can encompass all 4 styles.
 
 ![](https://media.daplie.com/oauth3/oauth3-flows-800x800.png)
 
@@ -83,13 +85,17 @@ In this scenario a default identity issuer has already been selected (presumably
 
 The advanced button presents another input box that can be used to enter an address.
 
+Why you would want this: If you want to have as little code as possible and you don't care that the user may have to perform an additional step.
+
 ### Type 2: Address Flow (email - no discovery)
 
 In this flow a default identity issuer has also already been selected and the user provides their email address which will be passed to the issuer as the subject.
 
 The advanced button presents another input box that can be used to manually specify an identity issuer (requires discovery).
 
-### Type 3: Address Flow (oauth3 - discovery)
+Why you would want this: If you want to collect the user's email address up front without waiting to request permission from the issuer/audience.
+
+### Type 3: [OPTIMAL] Address Flow (oauth3 - discovery)
 
 In this flow the identity issuer will be chosen based on the address provided by the user. If the address is discovered to be an oauth3 address it will be used as such. Otherwise the flow will fallback to type 2.
 
@@ -97,8 +103,32 @@ In this flow the identity issuer will be chosen based on the address provided by
 
 **oauth3 address**: the identity issuer specified will be used, the username is optional
 
+Why you would want this: You want your users to enjoy the most choice with the least friction.
+
 ### Type 4: Advanced Flow (manual + discovery)
 
 There is a chance that someone would like to use an oauth3 subject address (i.e. jane@smithfam.net) with a different identity issuer than the one identified by the subject.
 
-In this flow the subject and the identity issuer can be manually selected independently, ignoring the discovery of the subject.
+In this flow the subject and the identity issuer can be manually selected independently, ignoring any discovery of the subject.
+
+Why you would want this: You want to support every possible OAuth3 use case.
+
+## OAuth3 Issuer Discovery Endpoints
+
+Any site (**iss**) which supports OAuth3 (oauth3.org, for example) can be discovered automatically and all configuration details can be taken care of without human intervention.
+
+To be compatible the site MUST provide a static json file (`directives.json`) containing all of the directives and endpoints required to complete the OAuth3 processes.
+
+It must also provide an `index.html` which can be used to pass the contents of `directives.json` via url parameters so that OAuth3 can work on simple static servers that do not have CORS support.
+
+
+```
+https://issuer.tld/.well-known/oauth3/directives.json
+https://issuer.tld/.well-known/oauth3/                 (index.html)
+```
+
+The site receiving the url parameters (**azp**) must have its own `directives.json` which must specify `/.well-known/oauth3/callback.html` as the callback frame through which it receives 
+
+```
+https://azp.tld/.well-known/oauth3/callback.html
+```