diff --git a/docs/roles.md b/docs/roles.md
index 39ccd73c..bd543bd9 100644
--- a/docs/roles.md
+++ b/docs/roles.md
@@ -2,20 +2,19 @@
 title: Roles, Role Members, and Role Actions
 ---
 
-
-## **Roles**  
+## **Roles**
 
 A role is a collection of permissions (actions) that define what members of the role are allowed to do within a specific entity. Each entity (like a `Client`, `Channel`, `Group`, or `Domain`) can have multiple roles, each with its own members and actions.
 
-- **Role Members**: These are users assigned to a role. Members are the only users allowed to perform the role's actions on the entity.  
+- **Role Members**: These are users assigned to a role. Members are the only users allowed to perform the role's actions on the entity.
 - **Role Actions**: These are permissions defining what members of the role can do. For example, actions can include `read`, `update`, `delete`, or more specific actions like `publish` or `connect_to_channel`. **Refer to `authz-spec.md` for the available actions for each entity type.**
 
 ---
 
-## **Base URL**  
+## **Base URL**
 
 All API requests use the base URL:  
-`http://localhost/<entity_type>/<entity_id>`  
+`http://localhost/<entity_type>/<entity_id>`
 
 Replace `<entity_type>` with one of the entity types (`clients`, `channels`, `groups`, `domains`) and `<entity_id>` with the ID of the specific entity.
 
@@ -23,12 +22,12 @@ Replace `<entity_type>` with one of the entity types (`clients`, `channels`, `gr
 
 ### **Endpoints and Examples**
 
-### **1. Create a Role**  
+### **1. Create a Role**
 
 **POST /role**  
-Creates a role for the given entity.  
+Creates a role for the given entity.
 
-**Request Body**:  
+**Request Body**:
 
 ```json
 {
@@ -41,9 +40,9 @@ Creates a role for the given entity.
 #### Example for a `Channel`
 
 **Request**:  
-`POST http://localhost/channels/<channel_id>/role`  
+`POST http://localhost/channels/<channel_id>/role`
 
-**Response**:  
+**Response**:
 
 ```json
 {
@@ -56,17 +55,17 @@ Creates a role for the given entity.
 
 ---
 
-### **2. List Roles**  
+### **2. List Roles**
 
 **GET /roles**  
-Retrieves all roles for the given entity.  
+Retrieves all roles for the given entity.
 
 #### List Roles Example for a `Client`
 
 **Request**:  
-`GET http://localhost/clients/<client_id>/roles`  
+`GET http://localhost/clients/<client_id>/roles`
 
-**Response**:  
+**Response**:
 
 ```json
 [
@@ -87,17 +86,17 @@ Retrieves all roles for the given entity.
 
 ---
 
-### **3. Retrieve a Role**  
+### **3. Retrieve a Role**
 
 **GET /roles/`role_id`**  
-Fetches details of a specific role.  
+Fetches details of a specific role.
 
 #### Retrieve a Role Example for a `Group`
 
 **Request**:  
-`GET http://localhost/groups/<group_id>/roles/<role_id>`  
+`GET http://localhost/groups/<group_id>/roles/<role_id>`
 
-**Response**:  
+**Response**:
 
 ```json
 {
@@ -110,24 +109,32 @@ Fetches details of a specific role.
 
 ---
 
-### **4. Delete a Role**  
+### 4. **Update a Role**
+
+**PUT /roles/`roleID`**
+
+Updates the role's name, actions, or other properties.
+
+---
+
+### **5. Delete a Role**
 
 **DELETE /roles/`role_id`**  
-Deletes the specified role.  
+Deletes the specified role.
 
 #### Delete a Role Example for a `Domain`
 
 **Request**:  
-`DELETE http://localhost/domains/<domain_id>/roles/<role_id>`  
+`DELETE http://localhost/domains/<domain_id>/roles/<role_id>`
 
 ---
 
-### **5. Add Role Members**  
+### **6. Add Role Members**
 
 **POST /roles/`role_id`/members**  
-Adds members to the specified role.  
+Adds members to the specified role.
 
-**Request Body**:  
+**Request Body**:
 
 ```json
 {
@@ -138,9 +145,9 @@ Adds members to the specified role.
 #### Add Role Members Example for a `Client`
 
 **Request**:  
-`POST http://localhost/clients/<client_id>/roles/<role_id>/members`  
+`POST http://localhost/clients/<client_id>/roles/<role_id>/members`
 
-**Request Body**:  
+**Request Body**:
 
 ```json
 {
@@ -150,17 +157,17 @@ Adds members to the specified role.
 
 ---
 
-### **6. List Role Members**  
+### **7. List Role Members**
 
 **GET /roles/`role_id`/members**  
-Retrieves all members of the specified role.  
+Retrieves all members of the specified role.
 
 #### List Role Members Example for a `Channel`
 
 **Request**:  
-`GET http://localhost/channels/<channel_id>/roles/<role_id>/members`  
+`GET http://localhost/channels/<channel_id>/roles/<role_id>/members`
 
-**Response**:  
+**Response**:
 
 ```json
 
@@ -168,12 +175,16 @@ Retrieves all members of the specified role.
 
 ---
 
-### **7. Delete Specific Role Members**  
+### **8. Delete Specific Role Members**
 
 **POST /roles/`role_id`/members/delete**  
-Deletes specific members from the role.  
+Deletes specific members from the role.
 
-**Request Body**:  
+> If the role being modified is the built-in `admin` role, the system **will reject the request** if it would result in removing all remaining members from the role.
+>
+> This restriction ensures that **every domain always retains at least one administrator** to prevent orphaned domains.
+
+**Request Body**:
 
 ```json
 {
@@ -184,9 +195,9 @@ Deletes specific members from the role.
 #### Delete Specific Role Members Example for a `Group`
 
 **Request**:  
-`POST http://localhost/groups/<group_id>/roles/<role_id>/members/delete`  
+`POST http://localhost/groups/<group_id>/roles/<role_id>/members/delete`
 
-**Response**:  
+**Response**:
 
 ```json
 {
@@ -196,24 +207,28 @@ Deletes specific members from the role.
 
 ---
 
-### **8. Delete All Role Members**  
+### **9. Delete All Role Members**
 
 **POST /roles/`role_id`/members/delete-all**  
-Removes all members from the role.  
+Removes all members from the role.
+
+> For the built-in `admin` role, this operation is **not permitted**.  
+> The system will reject any request that attempts to remove all members from the `admin` role to **prevent administrative lockout**.  
+> This ensures that **every domain retains at least one user with administrative privileges** at all times.
 
 #### Delete All Role Members Example for a `Domain`
 
 **Request**:  
-`POST http://localhost/domains/<domain_id>/roles/<role_id>/members/delete-all`  
+`POST http://localhost/domains/<domain_id>/roles/<role_id>/members/delete-all`
 
 ---
 
-### **9. Add Role Actions**  
+### **10. Add Role Actions**
 
 **POST /roles/`role_id`/actions**  
-Adds actions to the specified role.  
+Adds actions to the specified role.
 
-**Request Body**:  
+**Request Body**:
 
 ```json
 {
@@ -224,21 +239,21 @@ Adds actions to the specified role.
 #### Add Role Actions Example for a `Client`
 
 **Request**:  
-`POST http://localhost/clients/<client_id>/roles/<role_id>/actions`  
+`POST http://localhost/clients/<client_id>/roles/<role_id>/actions`
 
 ---
 
-### **10. List Role Actions**  
+### **11. List Role Actions**
 
 **GET /roles/`role_id`/actions**  
-Retrieves all actions of the specified role.  
+Retrieves all actions of the specified role.
 
 #### List Role Actions Example for a `Channel`
 
 **Request**:  
-`GET http://localhost/channels/<channel_id>/roles/<role_id>/actions`  
+`GET http://localhost/channels/<channel_id>/roles/<role_id>/actions`
 
-**Response**:  
+**Response**:
 
 ```json
 ["read", "update", "publish"]
@@ -246,24 +261,24 @@ Retrieves all actions of the specified role.
 
 ---
 
-### **11. Delete Specific Role Actions**  
+### **12. Delete Specific Role Actions**
 
 **POST /roles/`role_id`/actions/delete**  
-Deletes specific actions from the role.  
+Deletes specific actions from the role.
 
 #### Delete Specific Role Actions Example for a `Group`
 
 **Request**:  
-`POST http://localhost/groups/<group_id>/roles/<role_id>/actions/delete`  
+`POST http://localhost/groups/<group_id>/roles/<role_id>/actions/delete`
 
 ---
 
-### **12. Delete All Role Actions**  
+### **13. Delete All Role Actions**
 
 **POST /roles/`role_id`/actions/delete-all**  
-Removes all actions from the role.  
+Removes all actions from the role.
 
 #### Delete All Role Actions Example for a `Domain`
 
 **Request**:  
-`POST http://localhost/domains/<domain_id>/roles/<role_id>/actions/delete-all`  
+`POST http://localhost/domains/<domain_id>/roles/<role_id>/actions/delete-all`