___ wip: update documentation

docs/features.rst

@@ -19,7 +19,29 @@ FIXME).
 Authentication
 --------------
 
-FIXME
+**Cogite** uses the HTTP API of the Git host to create pull requests
+and, more generally, retrieve information from the host. For this to
+work, it needs to authenticate itself. You need only do so once for
+each host.
+
+There are two ways to authenticate:
+
+- Use the default, guided, semi-automatic mechanism (known as "OAuth
+  device flow" or "OAuth Device Authorization Grant") that defines a
+  new, properly configured authentication token that you can revoke at
+  any time. Basically, **Cogite** will display a one-time verification
+  code and open a browser window for you, where you can enter this
+  code to validate your token on the requested Git host.
+
+  FIXME: include screencast
+
+- If you already have a properly configured authentication token, or
+  if you don't trust **Cogite** mechanism above, you can use your own
+  authentication token. It MUST grant the "repo" scope. It is probably
+  a good idea to define a specific token for **Cogite** instead of
+  re-using the same token for many applications. That way, you can
+  revoke the token of a single application without affecting other
+  applications.
 
 
 .. _features_merge:

docs/getting_started.rst

@@ -30,8 +30,6 @@ Minimal configuration
 
 2. Run ``cogite auth add`` and follow instructions.
 
-   FIXME: explain the two current options : manual token or automatic configuration.
-
    For further details about authentication-related commands, see
    :ref:`features_authentication` and :ref:`commands_auth`.