Explain registration autofill logic

readme.md

@@ -55,3 +55,41 @@ in a message with the wrong error path specified.
 `style` specifies the bootstrap style to use for the button (class name `btn-$style` is used). Without custom css, its value must be one of `default`, `primary`, `success`, `info`, `warning`, `danger`.
 `icon` is the FontAwesome icon name to use for the service. It defaults to the icon provided on the service name.
 
+### Registration
+
+When a logged-out user logs in with an external account that is not linked to an existing account,
+they will be redirected to the registration page.
+Since the user already has a means to log in, the registration form will not ask to set an account password.
+However, the user is still able to set their password afterwards from their profile page.
+
+#### Prefilling email addresses during registration
+
+If there is a property mapped to `email` available when logging in to register a new account,
+the email address is automatically filled in into the form.
+
+When `trust_email_verification` is enabled on a resource owner and the user does not modify the prefilled email address,
+it will immediately be marked as verified.
+
+Email rules and registration rules still apply to the email address when provided by the resource owner.
+If the email rules configuration rejects the email address, or the registration rules do not allow the mail address to self-register,
+the email address received from the resource owner will not be filled in the form.
+
+### Example
+
+```
+oauth:
+    resource_owners:
+        fb:
+            config:
+                type: facebook
+                client_id: xxxxxxxxxxxx
+                client_secret: xxxxxxxxxxx
+                scope: email
+                infos_url:     "https://graph.facebook.com/me?fields=id,name,email,picture.type(square)"
+                paths:
+                    email:          email
+                    profilepicture: picture.data.url
+            trust_email_verification: true
+            service_name: 'Facebook'
+            icon: facebook-official
+```