giovannibaratta · giovannibaratta · Jun 13, 2026
diff --git a/docs/agents.md b/docs/agents.md
@@ -57,33 +57,22 @@ To participate in a workflow, an agent must have the voter role for the specific
 
 Agents authenticate using a secure two-step challenge-response protocol:
 
-```text
-┌─────────┐                                            ┌─────────┐
-│  Agent  │                                            │ Server  │
-└────┬────┘                                            └────┬────┘
-     │                                                      │
-     │  1. Request Challenge                                │
-     │  POST /auth/agents/challenge                         │
-     │─────────────────────────────────────────────────────>│
-     │                                                      │
-     │  2. Encrypted Challenge (with nonce)                 │
-     │  RSA-encrypted with agent's public key               │
-     │<─────────────────────────────────────────────────────│
-     │                                                      │
-     │  [Agent decrypts challenge with private key]         │
-     │                                                      │
-     │  3. Signed JWT Assertion                             │
-     │  POST /auth/agents/token (with decrypted nonce)      │
-     │─────────────────────────────────────────────────────>│
-     │                                                      │
-     │  4. Access Token                                     │
-     │  JWT token for API access                            │
-     │<─────────────────────────────────────────────────────│
-     │                                                      │
-```
-
 ### Authentication Steps
 
+```mermaid
+sequenceDiagram
+    participant Agent
+    participant Server
+
+    Agent->>Server: POST /auth/agents/challenge { agentName }
+    Server-->>Agent: 200 Returns Encrypted Challenge (nonce)
+    Note over Agent: Decrypts challenge<br/>with private key
+    Note over Agent: Creates signed JWT<br/>assertion with nonce
+    Agent->>Server: POST /auth/agents/token { assertion }
+    Note over Server: Validates signature & nonce
+    Server-->>Agent: 200 Returns Access Token
+```
+
 The authentication process begins when an agent requests a challenge from the server using its unique name. The server responds by generating a unique one-time code (nonce) and encrypting it with the agent's registered public key.
 
 Upon receiving the encrypted challenge, the agent decrypts it using its private key. It then creates a signed assertion that includes this decrypted nonce. Finally, the agent submits this assertion back to the server. The server validates the signature, ensures the nonce has not been reused, and issues an access token granting the agent API access.
diff --git a/docs/audit-logs.md b/docs/audit-logs.md
@@ -0,0 +1,56 @@
+# Audit Logs
+
+The Approvio platform includes a comprehensive auditing system that tracks modifications to core entities. The audit logs provide a reliable historical ledger of who changed what and when, ensuring accountability and data integrity across the system.
+
+## Accessing Audit Logs
+
+Access to the audit logs is strictly controlled to ensure sensitive organizational history is only visible to authorized personnel.
+
+To view audit logs, a user must be assigned the **`AuditorViewer`** role. This role operates exclusively at the Organization (`org`) scope, meaning that once granted, the user has visibility into all audited events across all spaces and groups within the organization.
+
+## Tracked Events
+
+The auditing system focuses on tracking Create, Update, and Delete (CUD) operations for critical resources, as well as significant state changes.
+
+Currently, the system tracks the following events:
+
+| Audit Type             | Entity | Description                                                 |
+| :--------------------- | :----- | :---------------------------------------------------------- |
+| `SPACE_CREATED`        | Space  | Recorded when a new space is created.                       |
+| `SPACE_DELETED`        | Space  | Recorded when a space is permanently deleted.               |
+| `GROUP_CREATED`        | Group  | Recorded when a new group is created.                       |
+| `MEMBERSHIPS_ADDED`    | Group  | Recorded when users or agents are added to a group.         |
+| `MEMBERSHIPS_REMOVED`  | Group  | Recorded when users or agents are removed from a group.     |
+| `USER_ROLES_ASSIGNED`  | User   | Recorded when new roles are assigned to a human user.       |
+| `USER_ROLES_REMOVED`   | User   | Recorded when roles are removed from a human user.          |
+| `AGENT_ROLES_ASSIGNED` | Agent  | Recorded when new roles are assigned to an automated agent. |
+| `AGENT_ROLES_REMOVED`  | Agent  | Recorded when roles are removed from an automated agent.    |
+
+## Audit Log Structure
+
+Every audit log entry contains standardized metadata providing context about the event, along with a structured payload specific to the action performed.
+
+### Standard Metadata
+
+All audit logs share the following core attributes:
+
+- **Entity ID**: The unique identifier of the resource that was modified (e.g., the Space ID or Group ID).
+- **Entity Type**: The category of the resource (`SPACE`, `GROUP`, `USER`, or `AGENT`).
+- **Audit Type**: The specific action that occurred (e.g., `SPACE_CREATED`).
+- **Actor**: The entity that performed the action. This includes the Actor's ID and Type (`user` or `agent`), providing a clear "who" for every event.
+- **Timestamp**: The exact date and time the action was recorded.
+
+### Event Payloads
+
+The `payload` field contains a JSON object detailing the specific changes made during the event. The structure of this payload varies depending on the `Audit Type`.
+
+**Examples:**
+
+- **Creation Events (`SPACE_CREATED`, `GROUP_CREATED`)**: The payload typically includes foundational details like the `name` and `description` of the newly created resource.
+- **Membership Events (`MEMBERSHIPS_ADDED`, `MEMBERSHIPS_REMOVED`)**: The payload contains an array of `members`, specifying the ID and type (user or agent) of each entity affected by the change.
+- **Role Events (`USER_ROLES_ASSIGNED`, `AGENT_ROLES_REMOVED`)**: The payload contains an array of `roles`, detailing the `roleName` and the exact `scope` (e.g., Space ID, Template ID) where the role was applied or removed.
+- **Deletion Events (`SPACE_DELETED`)**: Deletion events generally have an empty payload, as the primary information (which entity was deleted and by whom) is captured in the standard metadata.
+
+## System Architecture
+
+Approvio uses an append-only architecture for audit logs. Audit records are generated synchronously alongside the primary business transaction. Once recorded, audit logs are strictly immutable at the application level—they can never be updated or deleted. This ensures the integrity and reliability of the historical record for compliance and security reviews.
diff --git a/docs/authentication.md b/docs/authentication.md
@@ -149,20 +149,21 @@ sequenceDiagram
 
 Agents use an asymmetric key-pair (JWT Assertion) mechanism to securely authenticate without interactive logins.
 
-- **Challenge:** The agent requests an authentication challenge from the server.
-- **Sign:** The agent signs the challenge with its private key, creating a Client Assertion JWT.
-- **Token:** The server validates the signature and returns Access and Refresh tokens for the agent to use.
+- **Challenge:** The agent requests an authentication challenge from the server. The server generates a nonce, encrypts it with the agent's registered public key, and returns the encrypted challenge.
+- **Sign:** The agent decrypts the challenge using its private key. It then creates and signs a Client Assertion JWT that includes the decrypted nonce.
+- **Token:** The server validates the JWT signature and the nonce, and returns Access and Refresh tokens for the agent to use.
 
 ```mermaid
 sequenceDiagram
     participant M as Trusted Agent
     participant A as Backend
 
-    M->>A: POST /auth/agents/challenge { agentId }
-    A-->>M: 200 Returns PKCE Challenge
-    Note over M: Agent signs the challenge <br/> with its private key (Client Assertion JWT)
-    M->>A: POST /auth/agents/token { clientAssertion }
-    Note over A: Validates JWT Signature <br/> Registers agent if applicable
+    M->>A: POST /auth/agents/challenge { agentName }
+    A-->>M: 200 Returns Encrypted Challenge (nonce)
+    Note over M: Agent decrypts the challenge <br/> with its private key
+    Note over M: Creates signed JWT <br/> assertion with nonce
+    M->>A: POST /auth/agents/token { assertion }
+    Note over A: Validates JWT Signature & nonce
     A-->>M: 200 Returns Access + Refresh Tokens
 
     Note over M,A: Token Refresh

diff --git a/docs/groups.md b/docs/groups.md
@@ -0,0 +1,59 @@
+# Groups
+
+Groups are collections of entities (users and agents) that define who can participate in approval processes. They are the primary mechanism for assigning voting responsibilities within workflows.
+
+## Core Concepts
+
+### What Are Groups?
+
+A group is an organizational structure that allows multiple entities to be treated as a single collective unit for the purpose of approval workflows. Instead of assigning approval rules to specific individuals, you assign them to groups. This provides flexibility and resilience, ensuring that workflows do not stall if a specific individual is unavailable or leaves the organization.
+
+Groups operate at the organization level, meaning a single group can be referenced by any workflow template across any space within the organization.
+
+### Group Memberships
+
+Groups can contain two types of entities:
+
+- **Users**: Human participants who review details and cast votes through the user interface or API.
+- **Agents**: Automated systems configured to vote programmatically based on pre-defined checks.
+
+An entity can belong to multiple groups, and a group can contain multiple entities. The maximum number of entities a single group can hold is determined by the `MAX_ENTITIES_PER_GROUP` quota.
+
+## Role Management
+
+Access to manage groups is controlled through group-scoped roles. These roles determine who can view or modify the group's details and memberships.
+
+| Role              | Permissions         | Description                                                      |
+| :---------------- | :------------------ | :--------------------------------------------------------------- |
+| **GroupReadOnly** | read                | View group information, including its members.                   |
+| **GroupWrite**    | read, write         | Modify the group's name and description.                         |
+| **GroupManager**  | read, write, manage | Full control, including the ability to add/remove group members. |
+
+**Important Restrictions:**
+
+- Every group must have at least one active **User** who holds the `GroupManager` role. The system prevents the removal of the last remaining group manager to ensure that the group does not become unmanageable.
+- Automated agents cannot be group administrators.
+
+## Integration with Workflows
+
+### Approval Rules
+
+When designing a workflow template, administrators define Approval Rules based on group requirements. For example, a template might require at least 2 votes from the "Finance Approvers" group and 1 vote from the "Legal Approvers" group.
+
+### Voting Eligibility
+
+Being a member of a required group is necessary but not sufficient on its own to vote on a workflow. To successfully cast a vote, an entity must satisfy two conditions simultaneously:
+
+1. **Group Membership**: The entity must belong to a group explicitly referenced in the workflow's approval rules.
+2. **Voter Role**: The entity must hold the `WorkflowTemplateVoter` role for the specific workflow template (either assigned directly at the template scope, or inherited from the space or organization scope).
+
+### Dynamic Evaluation
+
+Voting eligibility is evaluated dynamically at the time the vote is cast. If a user is added to a required group while a workflow is actively in progress, they immediately become eligible to vote. Conversely, if a user is removed from a group, they lose their eligibility, although any votes they cast prior to their removal remain valid and are retained in the workflow's history.
+
+## Quotas
+
+The group system is subject to two primary quotas:
+
+- `MAX_GROUPS`: Enforced at the Organization level, this limits the total number of groups that can be created within the entire organization.
+- `MAX_ENTITIES_PER_GROUP`: Enforced at the Group level (but configurable at the Organization level as a default), this limits the maximum number of members (users and agents combined) that can belong to a single group.
diff --git a/docs/roles.md b/docs/roles.md
@@ -88,6 +88,18 @@ Control who can view, cancel, and manage workflow instances:
 - Space-level: Applies to workflows from all templates in a space
 - Organization-wide: Applies to all workflows
 
+### Audit Roles
+
+Control access to view system-wide audit logs:
+
+| Role              | Permissions | Description                                         |
+| ----------------- | ----------- | --------------------------------------------------- |
+| **AuditorViewer** | read        | View all system audit logs across the organization. |
+
+**Scopes Available:**
+
+- Organization-wide: Applies to all audit logs in the system
+
 ## Role Limits
 
 The system enforces specific limits and behaviors regarding roles to maintain efficiency and clarity. A user or agent can have a maximum of 128 roles assigned to them. If duplicate roles—meaning roles with the exact same name and scope—are assigned, the system automatically deduplicates them.