diff --git a/src/content/docs/components/iota/endpoints.md b/src/content/docs/components/iota/endpoints.md
index 7636270..47d4133 100644
--- a/src/content/docs/components/iota/endpoints.md
+++ b/src/content/docs/components/iota/endpoints.md
@@ -10,6 +10,25 @@ When a message comes from an iota without a `sender-id` that the iota has access
 
 ## Messages
 
+### Messaging Lifecycle
+
+The messaging system follows a strict derivation loop to ensure delivery and correct state synchronization:
+
+1. The client sends a `message_send` to its Iota.
+2. The Iota sends a response `message_send` as confirmation back to the client.
+3. The Iota sends a `message_other_iota` to the chat partner's Iota.
+   - **If it times out:**
+     - The initial Iota sends a `message_state` to the client with the state `"sending"`.
+   - **If successful:**
+     - The other Iota receives the `message_other_iota` and handles it.
+     - The other Iota informs its client with a `message_live`.
+     - **If the client doesn't answer:**
+       1. The other Iota will send a `message_state` to the initial Iota with the state `"sent"`.
+       2. The initial Iota will store the state and forward the `message_state` to its client.
+     - **If the client answers with `message_state`:**
+       1. The other Iota will store the state (either `"received"` or `"read"`) and forward the `message_state` to the initial Iota.
+       2. The initial Iota will store the state and forward the `message_state` to its client.
+
 ### Client adds someone to their contacts
 When adding via name, the omikron will intercept and fill the chat_partner_id.
 The iota will never read, or handle the chat_partner_name.
diff --git a/src/content/docs/components/omikron/endpoints.md b/src/content/docs/components/omikron/endpoints.md
index 640a07c..30bc9b2 100644
--- a/src/content/docs/components/omikron/endpoints.md
+++ b/src/content/docs/components/omikron/endpoints.md
@@ -175,3 +175,68 @@ The ping request should contain the last Client or Iota ping and the pong answer
   }
 }
 ```
+
+## User Online Status
+
+### Set Client Status
+
+The client can change their online status by sending a `client_changed` message.  
+Supported status values: `user_online`, `user_offline`, `user_dnd`, `user_idle`, `user_wc`, `user_invisible`.
+
+When `user_invisible` is set, the user remains connected and can send/receive messages, but appears as `user_offline` to all other users.
+
+#### `REQ` (Client → Omikron):
+
+```json
+{
+  "id": "<uuid>",
+  "type": "client_changed",
+  "data": {
+    "user_state": "<status>"
+  }
+}
+```
+
+### Online Status Notifications
+
+When a connected user changes their status, interested clients receive a notification:
+
+#### `EVENT` (Omikron → Client):
+
+```json
+{
+  "type": "client_changed",
+  "data": {
+    "user_id": "<user-id>",
+    "user_state": "<status>"
+  }
+}
+```
+
+### Online Status in User Data
+
+When fetching another user's profile via `get_user_data`, their online status is included in the response. Invisible users are reported as `user_offline`.
+
+#### `RES` (Omikron → Client, field in `get_user_data`):
+
+```json
+{
+  "id": "<uuid>",
+  "type": "get_user_data",
+  "data": {
+    "user_id": long,
+    "username": "<string>",
+    "display": "<string>",
+    "public_key": "<base64>",
+    "iota_id": long,
+    "online_status": "<status>",
+    "omikron_id": long,
+    "omikron_connections": [long, ...],
+    "sub_level": long,
+    "sub_end": long,
+    "about": "<string>?",
+    "avatar": "<base64>?",
+    "status": "<string>?"
+  }
+}
+```