Further document new features

docs/features/experimental/application-service.md

@@ -2,7 +2,7 @@
 **WARNING:** These features are currently highly experimental. They can be removed or modified without notice.  
 All the features requires a Homeserver capable of connecting [Application Services](https://matrix.org/docs/spec/application_service/r0.1.0.html).
 
-The following capabilities are provided in this features:
+The following capabilities are provided in this feature:
 - [Admin commands](#admin-commands)
 - [Email Notification about room invites by Matrix IDs](#email-notification-about-room-invites-by-matrix-ids)
 - [Auto-reject of expired 3PID invites](#auto-reject-of-expired-3pid-invites)
@@ -26,7 +26,7 @@ Under the `appsvc` namespace:
 | `endpoint.toHS.url`   | string  | Yes      | *None*  | Base URL to the Homeserver                                     |
 | `endpoint.toHS.token` | string  | Yes      | *None*  | Token to use when sending requests to the Homeserver           |
 | `endpoint.toAS.url`   | string  | Yes      | *None*  | Base URL to mxisd from the Homeserver                          |
-| `endpoint.toHS.token` | string  | Yes      | *None*  | Token for the Homeserver to use when sending requests to mxisd |
+| `endpoint.toAS.token` | string  | Yes      | *None*  | Token for the Homeserver to use when sending requests to mxisd |
 
 #### Example
 ```yaml
@@ -88,7 +88,7 @@ The following steps assume:
 - `appsvc.user.main` set to `mxisd` or not set
 
 1. Invite `@mxisd:example.org` to a new direct chat
-2. Type `!help`
+2. Type `!help` to get all available commands
 
 ### Email Notification about room invites by Matrix IDs
 This feature allows for users found in Identity stores to be instantly notified about Room Invites, regardless if their

docs/features/identity.md

@@ -29,7 +29,7 @@ To provide this functionality, mxisd uses a workaround: resolve the invite to a
 controlled by mxisd or a bot/service that will then reject the invite.
 
 If this dedicated User ID is to be controlled by mxisd, the [Application Service](experimental/application-service.md)
-feature must be configured and integrated with your Homeserver.
+feature must be configured and integrated with your Homeserver, as well as the *Auto-reject 3PID invite capability*.
 
 #### Configuration
 ```yaml
@@ -52,9 +52,23 @@ invite:
 - Default: Computed from `appsvc.user.inviteExpired` and `matrix.domain`
 
 ### Policies
+3PID invite policies are the companion feature of [Registration](registration.md). While the Registration feature acts on
+requirements for the invitee/register, this feature acts on requirement for the one(s) performing 3PID invites, ensuring
+a coherent system.
+
+It relies on only allowing people with specific [Roles](profile.md) to perform 3PID invites. This would typically allow
+a tight-control on a server setup with is "invite-only" or semi-open (relying on trusted people to invite new members).
+
+It's a middle ground between a closed server, where every user must be created or already exists in an Identity store,
+and an open server, where anyone can register.
+ 
 #### Integration
+Because Identity Servers do not control 3PID invites as per Matrix spec, mxisd needs to intercept a set of Homeserver
+endpoints to apply the policies.
+
 ##### Reverse Proxy
 ###### nginx
+**IMPORTANT**: Must be placed before your global `/_matrix` entry:
 ```nginx
 location ~* ^/_matrix/client/r0/rooms/([^/]+)/invite$ {
     proxy_pass		    http://127.0.0.1:8090;
@@ -63,7 +77,9 @@ location ~* ^/_matrix/client/r0/rooms/([^/]+)/invite$ {
 }
 ```
 
-##### Configuration
+#### Configuration
+The only policy currently available is to restrict 3PID invite to users having a specific (set of) role(s), like so:
+
 ```yaml
 invite:
   policy:

docs/features/registration.md

@@ -6,6 +6,9 @@
     - [Apache](#apache)
   - [Homeserver](#homeserver)
     - [synapse](#synapse)
+- [Configuration](#configuration)
+  - [Example](#example)
+- [Usage](#usage)
 
 ## Overview
 **NOTE**: This feature is beta: it is considered stable enough for production but is incomplete and may contain bugs.
@@ -22,7 +25,7 @@ can register on a given server in a implementation-agnostic manner.
 the registration process.  
 As such, it relies on the homeserver to require 3PIDs with the registration flows.
 
-This feature is not part of the Matrix spec.
+This feature is not part of the Matrix Identity Server spec.
 
 ## Integration
 mxisd needs to be integrated at several levels for this feature to work:
@@ -87,7 +90,7 @@ The following table illustrates pattern and maching status against example value
 | `.example.org` | No                    | Yes                       |
 | `example.org`  | Yes                   | No                        |
 
-### Full example
+### Example
 For the following example configuration:
 ```yaml
 register: