diff --git a/doc/api/mainpage.dox b/doc/api/mainpage.dox
index 471ed77..cd671c9 100644
--- a/doc/api/mainpage.dox
+++ b/doc/api/mainpage.dox
@@ -1,19 +1,21 @@
 /**
 @mainpage
 
-This is the libei API reference.
+This is the libei API reference. For the protocol documentation see
+[here](https://libinput.pages.freedesktop.org/libei/).
 
 libei provides two different libraries, `libei` for clients that need to
-emulate input events and `libeis` for servers that manage those input events
-(read: compositors). A common setup looks like this:
+emulate or capture input events and `libeis` for servers that manage those
+input events (read: compositors). A common setup looks like this:
 
 ```
-                   +-----------------------+
-physical devices - | libinput | compositor |
-                   +----------+------------+
-                              |   libeis   |
-                              +------------+
+                   +-----------------------+       +----------------+
+physical devices - | libinput | compositor | ----- | Wayland client |
+                   +----------+------------+   ^   +----------------+
+                              |   libeis   |   |
+                              +------------+   Wayland events
                                     ||
+                                    || <-- EI events
                                     ||
                               +-------------+
                               |    libei    |
@@ -26,8 +28,8 @@ Notably, the process using `libeis` is **in control of all input devices**. A
 `libei` client can send events but it is up to the EIS implementation to
 process them.
 
-The two libraries are independently and usually consumers of either `libei` or
-`libeis` should never need the other library.
+The two libraries are independently and usually a process uses either `libei` or
+`libeis` but not both.
 
 @section sec-ei EI - the client implementation
 
diff --git a/src/libei.h b/src/libei.h
index b0403b5..7798b85 100644
--- a/src/libei.h
+++ b/src/libei.h
@@ -36,14 +36,17 @@ extern "C" {
  * @addtogroup libei EI - The client API
  *
  * libei is the client-side module. This API should be used by processes
- * that need to emulate devices.
+ * that need to emulate devices or capture logical events from existing devices.
  *
- * libei clients come in "sender" and "receiver" modes, depending on whether
- * the client sends or receives events. A libeis context however may accept
- * both sender and receiver clients, the EIS implementation works as
- * corresponding receiver or sender for this client. It is up to the
- * implementation to disconnect clients that it does not want to allow. See
- * eis_client_is_sender() for details.
+ * libei clients come in @ref ei_new_sender "sender" and @ref ei_new_receiver
+ * "receiver" modes, depending on whether the client sends or receives events
+ * from the EIS implementation.
+ *
+ * @note A libei context is restricted to either sender or receiver mode, not
+ * both. The EIS implementation however may accept both sender and receiver clients,
+ * and will work as corresponding receiver or sender for this
+ * client. It is up to the implementation to disconnect clients that it does not
+ * want to allow. See eis_client_is_sender() for details.
  *
  * @{
  */