docs: clarify capability contextlevel guidance

docs/apis/subsystems/access.md

@@ -66,6 +66,8 @@ Where the meaning of array keys is:
 | `archetypes`           | specifies defaults for roles with standard archetypes, this is used in installs, upgrades and when resetting roles (it is recommended to use only CAP_ALLOW here).  Archetypes are defined in mdl_role table.  See also [Role archetypes](https://docs.moodle.org/dev/Role_archetypes).                                                                                                                      |
 | `clonepermissionsfrom` | when you are adding a new capability, you can tell Moodle to copy the permissions for each role from the current settings for another capability. This may give better defaults than just using archetypes for administrators who have heavily customised their roles configuration. The full syntax is: `clonepermissionsfrom` => `moodle/quiz:attempt` |
 
+When choosing `contextlevel`, pick the highest context where the capability is expected to be checked and overridden. Moodle can still check the capability in lower contexts, but it only appears in override screens where changing it can affect the result. For example, `moodle/site:config` uses `CONTEXT_SYSTEM`, so it is not shown in course or activity overrides because changing it there would have no effect when the capability is checked at system context.
+
 It is necessary to bump up plugin version number after any change in db/access.php, so that the upgrade scripts can make the necessary changes to the database.  To run the upgrade scripts, log in to Moodle as administrator, navigate to the site home page, and follow the instructions.  (If you need to test the upgrade script without changing the plugin version, it is also possible to set back the version number in the mdl_block or mdl_modules table in the database.)
 
 The capability names are defined in plugin language files, the name of the string consists of "pluginname:capabilityname", in the example above it would be:

versioned_docs/version-4.5/apis/subsystems/access.md

@@ -66,6 +66,8 @@ Where the meaning of array keys is:
 | `archetypes`           | specifies defaults for roles with standard archetypes, this is used in installs, upgrades and when resetting roles (it is recommended to use only CAP_ALLOW here).  Archetypes are defined in mdl_role table.  See also [Role archetypes](https://docs.moodle.org/dev/Role_archetypes).                                                                                                                      |
 | `clonepermissionsfrom` | when you are adding a new capability, you can tell Moodle to copy the permissions for each role from the current settings for another capability. This may give better defaults than just using archetypes for administrators who have heavily customised their roles configuration. The full syntax is: `clonepermissionsfrom` => `moodle/quiz:attempt` |
 
+When choosing `contextlevel`, pick the highest context where the capability is expected to be checked and overridden. Moodle can still check the capability in lower contexts, but it only appears in override screens where changing it can affect the result. For example, `moodle/site:config` uses `CONTEXT_SYSTEM`, so it is not shown in course or activity overrides because changing it there would have no effect when the capability is checked at system context.
+
 It is necessary to bump up plugin version number after any change in db/access.php, so that the upgrade scripts can make the necessary changes to the database.  To run the upgrade scripts, log in to Moodle as administrator, navigate to the site home page, and follow the instructions.  (If you need to test the upgrade script without changing the plugin version, it is also possible to set back the version number in the mdl_block or mdl_modules table in the database.)
 
 The capability names are defined in plugin language files, the name of the string consists of "pluginname:capabilityname", in the example above it would be:

versioned_docs/version-5.0/apis/subsystems/access.md

@@ -66,6 +66,8 @@ Where the meaning of array keys is:
 | `archetypes`           | specifies defaults for roles with standard archetypes, this is used in installs, upgrades and when resetting roles (it is recommended to use only CAP_ALLOW here).  Archetypes are defined in mdl_role table.  See also [Role archetypes](https://docs.moodle.org/dev/Role_archetypes).                                                                                                                      |
 | `clonepermissionsfrom` | when you are adding a new capability, you can tell Moodle to copy the permissions for each role from the current settings for another capability. This may give better defaults than just using archetypes for administrators who have heavily customised their roles configuration. The full syntax is: `clonepermissionsfrom` => `moodle/quiz:attempt` |
 
+When choosing `contextlevel`, pick the highest context where the capability is expected to be checked and overridden. Moodle can still check the capability in lower contexts, but it only appears in override screens where changing it can affect the result. For example, `moodle/site:config` uses `CONTEXT_SYSTEM`, so it is not shown in course or activity overrides because changing it there would have no effect when the capability is checked at system context.
+
 It is necessary to bump up plugin version number after any change in db/access.php, so that the upgrade scripts can make the necessary changes to the database.  To run the upgrade scripts, log in to Moodle as administrator, navigate to the site home page, and follow the instructions.  (If you need to test the upgrade script without changing the plugin version, it is also possible to set back the version number in the mdl_block or mdl_modules table in the database.)
 
 The capability names are defined in plugin language files, the name of the string consists of "pluginname:capabilityname", in the example above it would be:

versioned_docs/version-5.1/apis/subsystems/access.md

@@ -66,6 +66,8 @@ Where the meaning of array keys is:
 | `archetypes`           | specifies defaults for roles with standard archetypes, this is used in installs, upgrades and when resetting roles (it is recommended to use only CAP_ALLOW here).  Archetypes are defined in mdl_role table.  See also [Role archetypes](https://docs.moodle.org/dev/Role_archetypes).                                                                                                                      |
 | `clonepermissionsfrom` | when you are adding a new capability, you can tell Moodle to copy the permissions for each role from the current settings for another capability. This may give better defaults than just using archetypes for administrators who have heavily customised their roles configuration. The full syntax is: `clonepermissionsfrom` => `moodle/quiz:attempt` |
 
+When choosing `contextlevel`, pick the highest context where the capability is expected to be checked and overridden. Moodle can still check the capability in lower contexts, but it only appears in override screens where changing it can affect the result. For example, `moodle/site:config` uses `CONTEXT_SYSTEM`, so it is not shown in course or activity overrides because changing it there would have no effect when the capability is checked at system context.
+
 It is necessary to bump up plugin version number after any change in db/access.php, so that the upgrade scripts can make the necessary changes to the database.  To run the upgrade scripts, log in to Moodle as administrator, navigate to the site home page, and follow the instructions.  (If you need to test the upgrade script without changing the plugin version, it is also possible to set back the version number in the mdl_block or mdl_modules table in the database.)
 
 The capability names are defined in plugin language files, the name of the string consists of "pluginname:capabilityname", in the example above it would be:

versioned_docs/version-5.2/apis/subsystems/access.md

@@ -66,6 +66,8 @@ Where the meaning of array keys is:
 | `archetypes`           | specifies defaults for roles with standard archetypes, this is used in installs, upgrades and when resetting roles (it is recommended to use only CAP_ALLOW here).  Archetypes are defined in mdl_role table.  See also [Role archetypes](https://docs.moodle.org/dev/Role_archetypes).                                                                                                                      |
 | `clonepermissionsfrom` | when you are adding a new capability, you can tell Moodle to copy the permissions for each role from the current settings for another capability. This may give better defaults than just using archetypes for administrators who have heavily customised their roles configuration. The full syntax is: `clonepermissionsfrom` => `moodle/quiz:attempt` |
 
+When choosing `contextlevel`, pick the highest context where the capability is expected to be checked and overridden. Moodle can still check the capability in lower contexts, but it only appears in override screens where changing it can affect the result. For example, `moodle/site:config` uses `CONTEXT_SYSTEM`, so it is not shown in course or activity overrides because changing it there would have no effect when the capability is checked at system context.
+
 It is necessary to bump up plugin version number after any change in db/access.php, so that the upgrade scripts can make the necessary changes to the database.  To run the upgrade scripts, log in to Moodle as administrator, navigate to the site home page, and follow the instructions.  (If you need to test the upgrade script without changing the plugin version, it is also possible to set back the version number in the mdl_block or mdl_modules table in the database.)
 
 The capability names are defined in plugin language files, the name of the string consists of "pluginname:capabilityname", in the example above it would be: