docs: Document grant normalization

website/content/docs/commands/roles/add-grant-scopes.mdx

@@ -33,10 +33,14 @@ $ boundary roles add-grant-scopes [options] [args]
 ### Command options
 
 - `-grant-scope-id=<string>` - The scope IDs that inherit grants set on the role.
-You can specify the following values:
+  You can specify the following values:
   - `this` - Applies to the current scope.
   - `children` - Applies to all direct children of the scope and can only be used with global and org scopes.
   - `descendants` - Applies to all descendants of the scope and can only be used with the global scope.
+
+  Boundary does not allow you to create redudnant grant scopes.
+  For example, if an org scope inherits a grant from the global scope, you cannot apply the same grant directly to the org scope.
+
 - `-id=<string>` - The ID of the role you want to add grant scopes to.
 - `-version=<int>` The version of the role to add grant scopes to.
 If you do not specify a version, the command performs a check-and-set automatically.

website/content/docs/commands/roles/remove-grant-scopes.mdx

@@ -34,10 +34,14 @@ $ boundary roles remove-grant-scopes [options] [args]
 ### Command options
 
 - `-grant-scope-id=<string>` - The scope IDs that inherit grants removed from the role.
-You can specify the following values:
+  You can specify the following values:
   - `this` - Applies to the current scope.
   - `children` - Applies to all direct children of the scope and can only be used with global and org scopes.
   - `descendants` - Applies to all descendants of the scope and can only be used with the global scope.
+
+  Boundary does not allow you to create redudnant grant scopes.
+  For example, if an org scope inherits a grant from the global scope, you cannot apply the same grant directly to the org scope.
+
 - `-id=<string>` - The ID of the role you want to remove grant scopes from.
 - `-version=<int>` The version of the role to remove grant scopes from.
 If you do not specify a version, the command performs a check-and-set automatically.

website/content/docs/commands/roles/set-grant-scopes.mdx

@@ -33,10 +33,14 @@ $ boundary roles set-grant-scopes [options] [args]
 ### Command options
 
 - `-grant-scope-id=<string>` - The scope IDs that inherit grants set on the role.
-You can specify the following values:
+  You can specify the following values:
   - `this` - Applies to the current scope.
   - `children` - Applies to all direct children of the scope and can only be used with global and org scopes.
   - `descendants` - Applies to all descendants of the scope and can only be used with the global scope.
+
+  Boundary does not allow you to create redudnant grant scopes.
+  For example, if an org scope inherits a grant from the global scope, you cannot apply the same grant directly to the org scope.
+
 - `-id=<string>` - The ID of the role you want to set grant scopes on.
 - `-version=<int>` The version of the role to set grant scopes on.
 If you do not specify a version, the command performs a check-and-set automatically.

website/content/docs/commands/scopes/create.mdx

@@ -38,7 +38,13 @@ The default is `global`.
 You can also specify the scope using the **BOUNDARY_SCOPE_ID** environment variable.
 - `-skip-admin-role-creation` - If set, Boundary does not create a role that grants the current user administrative access to the newly created scope.
 The default value is `false`.
+
+   This option is being deprecated in Boundary version 0.19.3.
+   It will be removed from the product in two releases and will be replaced with a new option to create default roles.
 - `-skip-default-role-creation` - If set, Boundary does not create a role that grants the anonymous user access to log in to auth methods and other actions within the newly created scope.
 The default value is `false`.
 
+   This option is being deprecated in Boundary version 0.19.3.
+   It will be removed from the product in two releases and will be replaced with a new option to create default roles.
+
 @include 'cmd-option-note.mdx'

website/content/docs/concepts/domain-model/scopes.mdx

@@ -24,6 +24,33 @@ Within the software itself and elsewhere in the documentation, Boundary reliably
 
 You can only associate certain resources with specific levels of scopes.
 For example, while you can create users at the global or org level, you can only create targets within a project.
+Refer to the table below for a list of resources and their valid scope types:
+
+| Resource             | Valid scope types    |
+| -------------------- | -------------------- |
+| Accounts             | Global, org          |
+| Aliases              | Global               |
+| Auth methods         | Global, org          |
+| Auth tokens          | Global, org          |
+| Billing              | Global               |
+| Credential libraries | Project              |
+| Credentials          | Project              |
+| Credential stores    | Project              |
+| Groups               | Global, org, project |
+| Host catalogs        | Project              |
+| Host sets            | Project              |
+| Hosts                | Project              |
+| Managed groups       | Global, org          |
+| Policies             | Global, org          |
+| Roles                | Global, org, project |
+| Scopes               | Global, org          |
+| Session recordings   | Global, org          |
+| Sessions             | Project              |
+| Storage buckets      | Global, org          |
+| Targets              | Project              |
+| Users                | Global, org          |
+| Workers              | Global               |
+
 You can nest projects within orgs to configure access to resources.
 
 For example, you may create an org scope called `IT-Support` that contains the users or groups that make up your IT department.