--- a/README.md	Fri Jun 17 17:57:11 2016 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,26 +0,0 @@
-[pyramid\_cubicweb][] is one specific way of integrating [CubicWeb][] with a
-[Pyramid][] web application.
-
-### Features
-
-* provides a default route that let a cubicweb instance handle the request.
-
-### Usage
-
-To use, install pyramid\_cubicweb in your python environment,
-and then [include][] the package:
-
-    config.include('pyramid_cubicweb')
-
-### Configuration
-
-Requires the following [INI setting / environment variable][]:
-
-* `cubicweb.instance` / `CUBICWEB_INSTANCE`
-
-
-[pyramid\_cubicweb]: https://www.cubicweb.org/project/pyramid-cubicweb
-[CubicWeb]: http://www.cubicweb.com/
-[Pyramid]: http://pypi.python.org/pypi/pyramid
-[include]: http://docs.pylonsproject.org/projects/pyramid/en/latest/api/config.html#pyramid.config.Configurator.include
-[INI setting / environment variable]: http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html#adding-a-custom-setting

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.rst	Wed May 11 11:26:16 2016 +0200
@@ -0,0 +1,85 @@
+
+pyramid_cubicweb_ is one specific way of integrating CubicWeb_ with a
+Pyramid_ web application.
+
+Features
+========
+
+* provides a default route that let a cubicweb instance handle the request.
+
+Usage
+=====
+
+To use, install ``pyramid_cubicweb`` in your python environment, and
+then include_ the package::
+
+    config.include('pyramid_cubicweb')
+
+    
+Configuration
+=============
+
+Requires the following `INI setting / environment variable`_:
+
+* `cubicweb.instance` / `CW_INSTANCE`: the cubicweb instance name
+
+Authentication cookies
+----------------------
+
+When using the `pyramid_cubicweb.auth` (CubicWeb AuthTkt
+authentication policy), which is the default in most cases, you may
+have to configure the behaviour of these authentication policies using
+standard's Pyramid configuration. You may want to configure in your
+``pyramid.ini``:
+
+:Session Authentication:
+
+    This is a `AuthTktAuthenticationPolicy`_ so you may overwrite default
+    configuration values by adding configuration entries using the prefix
+    ``cubicweb.auth.authtkt.session``. Default values are:
+
+    ::
+
+        cubicweb.auth.authtkt.session.hashalg = sha512
+        cubicweb.auth.authtkt.session.cookie_name = auth_tkt
+        cubicweb.auth.authtkt.session.timeout = 1200
+        cubicweb.auth.authtkt.session.reissue_time = 120
+        cubicweb.auth.authtkt.session.http_only = True
+        cubicweb.auth.authtkt.session.secure = True
+
+
+:Persistent Authentication:
+
+    This is also a `AuthTktAuthenticationPolicy`_. It is used when persistent
+    sessions are activated (typically when using the cubicweb-rememberme_
+    cube). You may overwrite default configuration values by adding
+    configuration entries using the prefix
+    ``cubicweb.auth.authtkt.persistent``. Default values are:
+
+    ::
+
+        cubicweb.auth.authtkt.persistent.hashalg = sha512
+        cubicweb.auth.authtkt.persistent.cookie_name = pauth_tkt
+        cubicweb.auth.authtkt.persistent.max_age = 3600*24*30
+        cubicweb.auth.authtkt.persistent.reissue_time = 3600*24
+        cubicweb.auth.authtkt.persistent.http_only = True
+        cubicweb.auth.authtkt.persistent.secure = True
+
+
+.. Warning:: Legacy timeout values from the instance's
+             ``all-in-one.conf`` are **not** used at all (``
+             http-session-time`` and ``cleanup-session-time``)
+
+Please refer to the documentation_ for more details (available in the
+``docs`` directory of the source code).
+
+.. _pyramid_cubicweb: https://www.cubicweb.org/project/pyramid-cubicweb
+.. _CubicWeb: https://www.cubicweb.org/
+.. _`cubicweb-rememberme`: \
+    https://www.cubicweb.org/project/cubicweb-rememberme
+.. _Pyramid: http://pypi.python.org/pypi/pyramid
+.. _include: http://docs.pylonsproject.org/projects/pyramid/en/latest/api/config.html#pyramid.config.Configurator.include
+.. _`INI setting / environment variable`: http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html#adding-a-custom-setting
+.. _documentation: http://pyramid-cubicweb.readthedocs.org/
+.. _AuthTktAuthenticationPolicy: \
+    http://docs.pylonsproject.org/projects/pyramid/en/latest/api/authentication.html#pyramid.authentication.AuthTktAuthenticationPolicy

--- a/docs/narr/settings.rst	Fri Jun 17 17:57:11 2016 +0200
+++ b/docs/narr/settings.rst	Wed May 11 11:26:16 2016 +0200
@@ -6,32 +6,9 @@
 Cubicweb Settings
 -----------------
 
-Pyramid CubicWeb will make use of the following configuration entries if found
-in the cubicweb configuration (a.k.a. `all-in-one.conf`):
-
-.. warning::
-
-    These settings requires the `pyramid` cube to be enabled on the instance.
-
-.. confval:: pyramid-session-secret
-
-    Secret phrase to sign the session cookie
-    
-    Used by :func:`pyramid_cubicweb.session.includeme` to configure the default session factory.
-
-    .. code-block:: ini
-
-        pyramid-session-secret = <some very secret passphrase>
-
-.. confval:: pyramid-auth-secret
-
-    Secret phrase to sign the authentication cookie
-    
-    Used by :func:`pyramid_cubicweb.auth.includeme` to configure the default authentication policy.
-
-    .. code-block:: ini
-
-        pyramid-auth-secret = <some other very secret passphrase>
+Pyramid CubicWeb will **not** make use of the configuration entries
+found in the cubicweb configuration (a.k.a. `all-in-one.conf`) for any
+pyramid related configuration value.
 
 
 .. _pyramid_settings: