From 3cf38d138eacb6177ebd42d4c94d9c66c025163a Mon Sep 17 00:00:00 2001
From: Goffi <goffi@goffi.org>
Date: Mon, 23 Feb 2026 13:15:16 +0100
Subject: [PATCH] doc (cli/contacts): Add documentation for `contacts`:

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

fix 475
---
 doc/libervia-cli/contacts.rst | 50 +++++++++++++++++++++++++++++++++++
 doc/libervia-cli/roster.rst   |  8 +++---
 2 files changed, 55 insertions(+), 3 deletions(-)
 create mode 100644 doc/libervia-cli/contacts.rst

diff --git a/doc/libervia-cli/contacts.rst b/doc/libervia-cli/contacts.rst
new file mode 100644
index 00000000..541d5e3c
--- /dev/null
+++ b/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
diff --git a/doc/libervia-cli/roster.rst b/doc/libervia-cli/roster.rst
index 33c00b53..33a428f2 100644
--- a/doc/libervia-cli/roster.rst
+++ b/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.