wip

docs/auth/permissions/command-permissions.mdx

@@ -4,14 +4,15 @@ sidebar_position: 3
 
 # Command Permissions
 
+To limit what **commands** are available to a role in your supergraph, you define a `CommandPermissions` object.
+
 By default, whenever a new command is created in your supergraph, it is only executable by the `admin` role.
 
 You can enable or restrict access to commands by adding a new item to the `permissions` array in the
 `CommandPermissions` object. Each item in the array should have a `role` field and an `allowExecution` field. The
 `allowExecution` field should be set to `true` if the command is executable by the role.
 
-Further, you can use argument presets to pass actual logical expressions to your data sources to control how they do
-things.
+You can also use argument presets to pass actual logical expressions to your data sources to control how they do things.
 
 For example, a data connector might expose a `Command` called `delete_user_by_id` with two arguments - `user_id` and
 `pre_check`. `user_id` is the primary key of the user you'd like to remove, and `pre_check` lets you provide a custom
@@ -73,5 +74,3 @@ definition:
 | **definition.permissions[].role**            | The role for which permissions are being defined.                                       | [Role](#commandpermissions-role)                                 |
 | **definition.permissions[].allowExecution**  | Indicates whether the command is executable by the role.                                | [CommandPermission](#commandpermissions-commandpermission)       |
 | **definition.permissions[].argumentPresets** | Preset values for arguments that are enforced when the command is executed by the role. | [ArgumentPreset](#commandpermissions-argumentpreset)             |
-
----

docs/auth/permissions/model-permissions.mdx

@@ -4,18 +4,30 @@ sidebar_position: 2
 
 # Model Permissions
 
+To limit what **data** in a model is available to a role in your supergraph, you define a `ModelPermissions` object with
+a `filter` expression.
+
 By default, whenever a new model is created in your supergraph, all records are only accessible to the `admin` role. You
-can think of these as permissions on rows in a database table.
+can think of these as permissions on rows in a typical relational database table.
 
-You can restrict access to certain rows by adding a new item to the `permissions` array in the `ModelPermissions`
+You can restrict access to certain data by adding a new item to the `permissions` array in the `ModelPermissions`
 object. Each item in the array should have a `role` field and a `select` field. The `select` field should contain a
 `filter` expression that determines which rows are accessible to the role when selecting from the model.
 
-Most commonly, you'll use session variables — provided via your configured
-[authentication mechanism](/auth/authentication/index.mdx) — to restrict access to rows based on the user's identity or
-other criteria. You can also use argument presets to enforce row-level security. You can see an example of this below.
+Most commonly, you'll use session variables — accessed by Hasura Engine via your configured
+[authentication mechanism](/auth/authentication/index.mdx) in a JWT or body of a webhook response — to restrict access
+to rows based on the user's role, identity or other criteria.
+
+This filter expression can reference
+
+- The fields in your Model
+- Logical operators: `and`, `or` and `not`
+- `fieldIsNull` predicate
+- `fieldComparison` predicate
+- Relationship predicates
+- `null`
 
-To make a new ModelPermission or role available in your supergraph, after updating your metadata, you'll need to
+To make a new `ModelPermission` or role available in your supergraph, after updating your metadata, you'll need to
 [create a new build](/cli/commands/ddn_supergraph_build_local.mdx) using the CLI.
 
 ### Examples

docs/auth/permissions/type-permissions.mdx

@@ -4,6 +4,8 @@ sidebar_position: 1
 
 # Type Permissions
 
+To make API fields available to a role in your supergraph, you define a `TypePermissions` object.
+
 By default, whenever a new type is created in your supergraph, each field is defined as being only accessible to the
 `admin` role.