extract tenant acl to its own chapter

docs/intro/graphql.mdx

@@ -164,8 +164,8 @@ The Tenant API facilitates user logins and registrations, membership management,
   <DocsCard header="How Tenant API works" href="/reference/engine/tenant/overview">
     <p>Basic explanation of Tenant API functionality.</p>
   </DocsCard>
-  <DocsCard header="Managing users" href="/reference/engine/tenant/users">
-    <p>Manage users in your project over Tenant API.</p>
+  <DocsCard header="Managing users" href="/reference/engine/tenant/invites">
+    <p>Invite users to your projects.</p>
   </DocsCard>
   <DocsCard header="Memberships" href="/reference/engine/tenant/memberships">
     <p>Explaining relationship between users and projects.</p>

docs/reference/engine/schema/acl.md

@@ -151,112 +151,8 @@ Each variable must be exported from schema definition using `export const ...`
 
 ## Tenant permissions
 
-Here, you can also setup [Tenant API] permissions for a role. It is done under the `tenant` field of the role.
+See [tenant permissions](./tenant-acl.md)
 
-### Invite permissions
-
-By setting `invite` to `true` you can allow a user to invite other users. Keep in mind, you also need to set appropriate [manage permissions](#manage-permissions) for the role.
-
-There is also `unmanagedInvite` flag, which allows you to invite users using `unmanagedInvite` mutation.
-
-#### Example: enabling invite
-
-```typescript
-const editorRole = {
-	// ...
-	tenant: {
-		invite: true,
-	},
-}
-```
-
-### Manage permissions
-
-Defines which other roles and their variables a user can manage. First you define a role, which you want to manage as a object key:
-
-```typescript
-const editorRole = {
-	// ...
-	tenant: {
-		manage: {
-			editor: {
-				// ...
-			},
-		},
-	},
-}
-```
-
-With this, you would be able to manage users with the role `editor`, but not their variables.
-
-To allow managing all variable, just pass `variables: true`,
-
-```typescript
-const editorRole = {
-	// ...
-	tenant: {
-		manage: {
-			editor: {
-				variables: true,
-			},
-		},
-	},
-}
-```
-
-To granularly define which variables a user can manage, you can pass an object with variable names as keys and either `true` or source variable name as a value.
-
-```typescript
-const editorRole = {
-	// ...
-	tenant: {
-		manage: {
-			editor: {
-				variables: {
-					language: true,
-					site: 'assignable_site',
-				},
-			},
-		},
-	},
-}
-```
-
-This would allow a user manage `editor` role and assign any value to `language` variable. For `site` variable, user can only assign values from his own `assignable_site` source variable.
-
-
-## System API permissions
-
-You can also set some flags affecting system API.
-
-### [History API](/reference/engine/content/event-log.md)
-
-By setting `history` flag under `system` section to `true` you can allow a user to access the history API.
-
-```typescript
-const editorRole = {
-	// ...
-	system: {
-		history: true,
-	}
-}
-```
-:::caution
-Allowing history API access will allow user to access all the data in history API, ignoring entity rules.
-:::
-
-### Migrations
-
-Allow a role to run [migrations](migrations.md). Project admin (and superadmin) can always run migrations. Also, there is a default `deployer` role with this and only permission.
-
-```typescript
-const editorRole = {
-  // ...
-  system: {
-    migrations: true,
-  }
-}
-```
 
 ### Assume identity
 

docs/reference/engine/schema/tenant-acl.md

@@ -0,0 +1,83 @@
+---
+title: Tenant Permissions
+---
+
+The Tenant permissions feature in Contember allows you to fine-tune control over various actions and roles. These permissions are specified under the `tenant` field when you define a role.
+
+## Invite Permissions
+
+The `invite` permission controls the ability to invite other users to a project. You can use either a simple boolean value or a more advanced [membership match rule](#understanding-membership-match-rules) object. If `invite` is set to `true`, the existing rules under `manage` will apply.
+
+#### Example: Simple Invite Permission
+
+```typescript
+export const editorRole = acl.createRole('editor', {
+  tenant: {
+    invite: true,
+  },
+});
+```
+
+### Unmanaged Invite Permissions
+
+Similar to `invite`, the `unmanagedInvite` field can accept a boolean value or a [membership match rule](#understanding-membership-match-rules)  object. This permission allows you to use the `unmanagedInvite` mutation.
+
+### View Permissions
+
+The `view` field enables you to specify which roles and their associated variables a user can view.
+
+#### Example: View Permissions
+
+```typescript
+export const editorRole = acl.createRole('editor', {
+  tenant: {
+    view: {
+      editor: {
+        variables: {
+          language: true,
+        },
+      },
+    },
+  },
+});
+```
+
+### Manage Permissions
+
+The `manage` field helps you specify the roles and their variables that a user can manage.
+
+#### Example: Manage Permissions
+
+```typescript
+export const editorRole = acl.createRole('editor', {
+  tenant: {
+    manage: {
+      editor: {
+        variables: true,
+      },
+    },
+  },
+});
+```
+
+## Understanding membership match rules
+
+The membership match rules is an object that enables you to define more granular rules for managing memberships, roles, and variables. It comes into play when you set values for `invite`, `unmanagedInvite`, `view`, and `manage` fields in the `tenant` permissions.
+
+This rule allows you to:
+
+- Define which roles can be managed
+- Specify what variables within those roles can be managed
+
+For example, if you only want to allow a user to manage the `editor` role and assign any value to the `language` variable but restrict values for the `site` variable, your rule would look like this:
+
+```typescript
+{
+  editor: {
+    variables: {
+      language: true,
+      site: 'assignable_site',
+    },
+  },
+}
+```

sidebars.js

@@ -164,6 +164,7 @@ module.exports = {
 						"reference/engine/schema/views",
 						"reference/engine/schema/migrations",
 						"reference/engine/schema/acl",
+						"reference/engine/schema/tenant-acl",
 						"reference/engine/schema/validations",
 					],
 				},