doc (cli/contacts): Add documentation for contacts:

describe the new `contacts` commands to handle pubsub contacts.

fix 475

doc/libervia-cli/contacts.rst

@@ -0,0 +1,50 @@
+==================================
+contacts: handle contacts metadata
+==================================
+
+Contacts use the `End-to-End Encrypted Contacts Metadata`_ to handle contact metadata.
+This is a new mechanism that complements the XMPP native “Roster” mechanism. The
+advantages are that contacts can be optionally end-to-end encrypted, preventing metadata
+from being accessible to the server, and that additional metadata can be associated with
+contacts and groups. The disadvantages are that most clients do not support it, so your
+contacts may not appear in them. Also, the server may need to access your contacts list to
+make decisions, for instance, to filter undesirable messages, which is not possible with
+end-to-end encrypted contacts (and no server currently supports pubsub contacts).
+
+This feature is experimental and designed to reduce XMPP metadata exposure. For backward
+compatibility, use :ref:`li_roster` (note that the native roster cannot be end-to-end
+encrypted).
+
+.. _End-to-End Encrypted Contacts Metadata: https://xmpp.org/extensions/inbox/contacts-e2e.html
+
+get
+===
+
+Retrieve the current contacts and their associated groups. By default, they are displayed
+in a table showing all metadata, along with an indicator of whether they are end-to-end
+encrypted.
+
+Groups are displayed with their name, ID, and description (if available).
+
+examples
+--------
+
+Retrieve all contacts and their associated groups::
+
+  $ li contacts get
+
+set
+===
+
+Add or replace a contact. By default, the contact metadata will be end-to-end encrypted,
+but you can store it in plaintext by using the ``--no-encrypt`` flag.
+
+You can specify contact groups by ID (using ``-G, --group-ids GROUP_ID``) or by name
+(using ``-g, --group-names GROUP_NAME``). Both options can be provided multiple times.
+
+examples
+--------
+
+Add Louise as a new contact::
+
+  $ li contacts set -n Louise louise@example.org -g friends -g school

doc/libervia-cli/roster.rst

@@ -1,6 +1,8 @@
-================================
-roster: manager an entity roster
-================================
+.. _li_roster:
+
+===============================
+roster: manage an entity roster
+===============================
 
 "Roster" is the name used in XMPP for the contact list. In addition to list of contacts,
 you have also data like subscription information or groups associated to a contact.