--- a/doc/components.rst	Sun Sep 26 16:41:55 2021 +0200
+++ b/doc/components.rst	Sun Sep 26 16:41:58 2021 +0200
@@ -151,3 +151,107 @@
     }
 
   .. _SI prefixes and binary prefixes: https://en.wikipedia.org/wiki/Octet_(computing)#Unit_multiples
+
+
+ActivityPub Gateway
+-------------------
+
+**entry_point:** ``ap-gateway``
+
+.. note::
+
+  this component is currently in active development, and not yet usable for end-user. This
+  documentation will be updated during evolution of component.
+
+  You can follow the development by reading `Libervia Progress Notes`_.
+
+  .. _Libervia Progress Notes: https://www.goffi.org/tag/Libervia%20progress
+
+This gateway will provide a bidirectional gateway between XMPP and `ActivityPub`_ (or AP
+below). That means that user from XMPP will be able to follow actors or comments messages
+from any software compatible with ActivityPub protocol, and vice versa.
+
+.. _ActivityPub: https://activitypub.rocks/
+
+.. note::
+
+  this component is mostly tested with Prosody as XMPP server reference, and Mastodon as
+  AP server reference, but it should work with any XMPP or AP server.
+
+The component launches a HTTP server (necessary to communicate with AP software). This
+server needs to handle HTTP requests made at paths ``/.well-known/webfinger`` and ``/_ap``
+(or the ``ap_path`` set in configuration, see below). If the component is not directly
+facing internet (e.g. integrated in an existing website though a proxy), you'll have to
+redirect the requests made to those path to the HTTP server (i.e. to component host at the
+port set at ``http_port``, see configuration below). Please check your HTTP server
+documentation to find how this must be done.
+
+how to address an AP actor from XMPP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When addressing an ActivityPub actor from XMPP, you must use a JID corresponding to the
+actor. The domain part of the JID correspond to the gateway JID (the one set in gateway
+profile), while the local part (before the ``@``) is used to specify the AP actor.
+
+`XEP-0106`_ (JID Escaping) is used to indicate the AP actor identifier, thus the ``@``
+must be escaped with ``\40``.
+
+.. _XEP-0106: JID Escaping
+
+**example**
+
+If Louise wants to talk to Pierre which is on the ``example.net`` AP server, she can use
+her XMPP AP gateway which is at ``ap.example.org``. Pierre AP's actor identifier is
+``pierre@example.net``, Louise can access it via the JID
+``pierre\40example.net@ap.example.org``.
+
+Of course, this is a bit cumbersome to do by hand, it is expected that XMPP clients will
+do the (un)escaping automatically for end-user, in a way that Louise could enter
+``pierre@example.net`` directly, with an indicator to show that this is an ActivityPub
+actor identifier rather than an XMPP JID.
+
+how to address an XMPP entity from AP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To access an XMPP entity, just use its bare JID as AP actor.
+
+**example**
+
+If Pierre wants to talk Louise, he can directly use the JID which is the same as the AP
+actor identifier, i.e. ``louise@example.org`` (note that on AP software, a ``@`` prefix is
+often required, thus Pierre will look for ``@louise@example.org``).
+
+.. note::
+
+   Currently the gateway only uses bare JID, and character set must be recognised by the
+   AP software to be used. This will evolve in the close future to have a way to access
+   various XMPP Pubsub nodes.
+
+   The actor endpoint can also be used directly in AP software (in the example above, it
+   would be by default ``https://example.org/_ap/actor/louise%40example.org``).
+
+
+using the component
+~~~~~~~~~~~~~~~~~~~
+
+The component is currently only usable for development purpose, and it can be used with
+the following method (with can be accessed through the ``APSend`` bridge method, client is
+then replaced by the ``profile`` name, as last argument):
+
+.. automethod:: sat.plugins.plugin_comp_ap_gateway.APGateway.publishMessage
+
+The method can be used either with CLI's :ref:`debug bridge method
+<li_debug_bridge_method>` or with any D-Bus tool like ``qdbus`` or ``d-feet`` (only if you
+use the D-Bus bridge).
+
+example
+~~~~~~~
+
+On its ``example.net`` Mastodon instance, Pierre has published a message with the id
+``https://example.net/@pierre/106986412193109832``. To send a reply to this message,
+Louise can use the following command::
+
+  $ li debug bridge method -c APSend '"{\"node\": \"https://example.net/@pierre/106986412193109832\", \"content\": \"A lille hello from XMPP\"}","pierre\\40example.net@ap.example.org", "louise"'
+
+Note the double escaping, one for the shell argument, and the other to specify JSON
+object.

--- a/doc/libervia-cli/debug.rst	Sun Sep 26 16:41:55 2021 +0200
+++ b/doc/libervia-cli/debug.rst	Sun Sep 26 16:41:58 2021 +0200
@@ -4,7 +4,7 @@
 
 ``debug`` groups commands to monitor or manipulate Libervia and XMPP stream.
 
-.. _libervia-cli_debug_bridge_method:
+.. _li_debug_bridge_method:
 
 bridge method
 =============