--- a/doc/components.rst	Wed Jun 29 14:06:33 2022 +0200
+++ b/doc/components.rst	Wed Jun 29 14:23:16 2022 +0200
@@ -584,6 +584,27 @@
 
 .. _XEP-0191 (Blocking Command): https://xmpp.org/extensions/xep-0191.html
 
+Identity and Avatar
+~~~~~~~~~~~~~~~~~~~
+
+The gateway does the conversion between XMPP identity and AP actor metadata.
+
+XMPP "identity" is actually a compilaton of data coming from various locations and in
+particular `XEP-0292 (vCard4 Over XMPP)`_. In those data, vCard's ``nickname`` (first
+found) is used as AP ``name`` field, and vCard's ``note`` is used as AP's ``summary``
+(it's generally a self-description of users).
+
+For avatars, `XEP-0084 (User Avatar)`_ is used (and actor's ``icon`` field is used on AP
+side). Avatars are downloaded the first time that they are requested, and kept in cache
+for future requests.
+
+Even if XEP-0292 and XEP-0084 are the main XEPs used, Libervia checks various locations,
+and other extensions like `XEP-0054 (vcard-temp)`_ may be used as fallback.
+
+.. _XEP-0292 (vCard4 Over XMPP): https://xmpp.org/extensions/xep-0292.html
+.. _XEP-0084 (User Avatar): https://xmpp.org/extensions/xep-0084.html
+.. _XEP-0054 (vcard-temp): https://xmpp.org/extensions/xep-0054.html
+
 Using the Component (for developers)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~