Elaborate on user statuses, credentialed users

docs/5.x/reference/element-types/users.md

@@ -9,31 +9,17 @@ related:
 
 Users are Craft’s representation of people.
 
-Each user has an email address and username by default, as well as optional fields for a name, photo, and password. Like other [elements](./elements.md), users support custom fields by way of a [field layout](./fields.md#field-layouts).
+Each user has an email address and username by default, as well as optional fields for a name, photo, and password. Like other [elements](../../system/elements.md), users support custom fields by way of a [field layout](../../system/fields.md#field-layouts).
 
 There are also preferences for localization, accessibility, and debugging that may be relevant depending on how you build your site and whether you grant the user access to the control panel.
 
-What a user can do is determined by which [groups](user-management.md#user-groups) they belong to, and what individual [permissions](user-management.md#permissions) they have been granted.
+What a user can do is determined by which [groups](../../system/user-management.md#user-groups) they belong to, and what individual [permissions](../../system/user-management.md#permissions) they have been granted.
 
-### Active and Inactive Users
-
-A Craft user can be active or inactive, meaning they have a credentialed account or simply exist as a record in the system. Navigate to the **Users** screen and you’ll find these represented by **Credentialed** and **Inactive** groupings under the “Account Type” heading.
-
-![](../../images/account-type-subnav.png)
-
-You’ll most likely be creating active user accounts for content managers or site members to log in and do things. Each active account has its own status to describe that user’s level of access to the system:
-
-- **Active** – Account was activated by an admin, or the user set credentials to gain system access.
-- **Pending** – User was invited to activate their account but hasn’t completed the process.
-- **Suspended** – Account’s system access was explicitly revoked by another user with sufficient permissions.
-- **Locked** – Account was locked because of too many failed login attempts per the <config4:maxInvalidLogins> and <config4:cooldownDuration> config settings.
-- **Inactive** – Account never had credentials, or was explicitly deactivated.
-
-You can’t create an inactive user from the control panel, but you can deactivate a user account by choosing **Deactivate...** from its action menu (<icon kind="settings" />). Inactive user accounts are best suited for specific circumstances, like Craft Commerce guest customers or an imaginary Craft-based CRM that manages contacts.
+<See path="../../system/user-management.md" hash="statuses" label="User Statuses" description="Learn about how a user’s status affects their capabilities." />
 
 ### Addresses
 
-Users each have an address book. [Addresses](./addresses.md) can be managed on behalf of a user via the control panel, or [by the user themselves](../controllers/README.md#post-users-save-address).
+Users each have an address book. [Addresses](addresses.md) can be managed on behalf of a user via the control panel, or [by the user themselves](addresses.md#managing-addresses).
 
 ## Querying Users
 
@@ -50,10 +36,10 @@ $myUserQuery = \craft\elements\User::find();
 ```
 :::
 
-Once you’ve created a user query, you can set [parameters](#parameters) on it to narrow down the results, and then [execute it](element-queries.md#executing-element-queries) by calling `.all()`. An array of [User](craft4:craft\elements\User) objects will be returned.
+Once you’ve created a user query, you can set [parameters](#parameters) on it to narrow down the results, and then [execute it](../../system/element-queries.md#executing-element-queries) by calling `.all()`. An array of [User](craft4:craft\elements\User) objects will be returned.
 
 ::: tip
-See [Element Queries](element-queries.md) to learn about how element queries work.
+See [Element Queries](../../system/element-queries.md) to learn about how element queries work.
 :::
 
 ### Example

docs/5.x/system/user-management.md

@@ -3,10 +3,48 @@ keywords: permissions
 ---
 # User Management
 
-Craft’s “[Users](users.md)” represent humans in the system. These may be member accounts, or records that represent people in general.
+[Users](../reference/element-types/users.md) in Craft represent humans in the system. These may be member accounts, or records that represent people in general.
 
 The first user account is created during [installation](installation.md). If you stick with the Solo edition, this is the only account you will be able to create. If you need more (or you want to support [public registration](#public-registration)) you can upgrade to the Pro edition, which offers additional user accounts.
 
+## Statuses
+
+Users may exist in the system in a number of states. A user is typically created in a **Pending** state (ready to be activated via an activation link)
+
+### Active
+
+An **Active** user is able perform any task their permissions allow. Users are put in this state following account activation (either via an activation link or action taken by another user). However, an active account does not necessarily have a password—but once one is set (or the current password is reset), they _would_ be able to log in normally.
+
+### Pending
+
+A user is typically created in **Pending** state. The only difference between a **Pending** and **Active** user is that they have never activated their account with an activation link, or had a user with the **Moderate users** permission activate it for them.
+
+### Suspended
+
+**Suspended** users have been explicitly
+
+### Inactive
+
+Users that have been explicitly deactivated are marked as **Inactive**. An inactive user cannot log in, reset their password, or reactivate their account.
+
+### Special States
+
+#### Credentialed
+
+Craft has a special distinction for users who are able to log in _or could become able to log in_ under their own power. Any user that is either **Active** or **Pending** is considered **Credentialed**.
+
+#### Locked
+
+Once a user has made too many unsuccessful login attempts (according to the <config5:maxInvalidLogins> setting), their account will be **Locked**. Another user with the **Moderate users** [permission](#permissions) can manually unlock a user in this state at any time, or the user can wait until the <config5:cooldownDuration> elapses and try again.
+
+::: warning
+User locking is an automatic abuse-prevention behavior, not a moderation tool. If you need to prevent someone from accessing the site or control panel, [suspend](#suspended) or [deactivate](#inactive) their user.
+:::
+
+#### Trashed
+
+Like other elements, users can be _soft-deleted_. A trashed user cannot log in or restore themselves, and the user may be garbage-collected after remaining trashed for the configured <config5:softDeleteDuration>.
+
 ## Admin Accounts
 
 Admin accounts are special accounts that can do everything within Craft, including some things that don’t have explicit permissions:
@@ -45,18 +83,18 @@ The permissions Craft comes with are:
 | Access the control panel | `accessCp`
 | ↳&nbsp;Access the control panel when the system is offline | `accessCpWhenSystemIsOff`
 | ↳&nbsp; Perform Craft CMS and plugin updates | `performUpdates`
-| ↳&nbsp; Access _[plugin name]_ | `accessPlugin-[PluginHandle]`
+| ↳&nbsp; Access <CodePlaceholder>Plugin Name</CodePlaceholder> | `accessPlugin-[PluginHandle]`
 | Edit users | `editUsers`
 | ↳&nbsp; Register users | `registerUsers`
 | ↳&nbsp; Moderate users | `moderateUsers`
 | ↳&nbsp; Administrate users | `administrateUsers`
-| ↳&nbsp; Impersonate users | `impersonateUsers`
+| ↳&nbsp; Impersonate users <InfoHud>User impersonation allows one user to temporarily access the site as though they were another user with the same (or more restrictive) permissions.</InfoHud> | `impersonateUsers`
 | ↳&nbsp; Assign user permissions | `assignUserPermissions`
-| ↳&nbsp; Assign users to this group <InfoHud>This is not an actual permission so much as a convenience feature for automatically granting the ability to add peers to the group.</InfoHud> | See note.
-| ↳&nbsp; Assign users to _[group]_ | `assignUserGroup:[UserGroupUID]`
+| ↳&nbsp; Assign users to this group <InfoHud>This is not an actual permission so much as a convenience feature for automatically granting the ability to add peers to the group you are currently editing, as its handle may not be known, yet!</InfoHud> | See note.
+| ↳&nbsp; Assign users to <CodePlaceholder>Group Name</CodePlaceholder> | `assignUserGroup:[UserGroupUID]`
 | Delete users | `deleteUsers`
-| Edit _[site name]_ | `editSite:[SiteUID]`
-| View entries | `viewEntries:[SectionUID]`
+| Edit <CodePlaceholder>Site Name</CodePlaceholder> <InfoHud>Site permissions are intersected with other permissions. A user will only be able to edit something if they have access to the site <em>and</em> the element itself.</InfoHud> | `editSite:[SiteUID]`
+| View entries <InfoHud>This section is repeated for each configured section.</InfoHud> | `viewEntries:[SectionUID]`
 | ↳&nbsp; Create entries | `createEntries:[SectionUID]`
 | ↳&nbsp; Save entries | `saveEntries:[SectionUID]`
 | ↳&nbsp; Delete entries | `deleteEntries:[SectionUID]`
@@ -66,8 +104,8 @@ The permissions Craft comes with are:
 | ↳&nbsp;View other users’ drafts | `viewPeerEntryDrafts:[SectionUID]`
 | &nbsp;&nbsp;&nbsp; ↳&nbsp; Save other users’ drafts | `savePeerEntryDrafts:[SectionUID]`
 | &nbsp;&nbsp;&nbsp; ↳&nbsp; Delete other users’ drafts | `deletePeerEntryDrafts:[SectionUID]`
-| Edit _[global set name]_ | `editGlobalSet:[GlobalSetUID]`
-| View categories | `viewCategories:[CategoryGroupUID]`
+| Edit <CodePlaceholder>Global Set Name</CodePlaceholder> | `editGlobalSet:[GlobalSetUID]`
+| View categories <InfoHud>This section is repeated for each configured category group.</InfoHud> | `viewCategories:[CategoryGroupUID]`
 | ↳&nbsp; Save categories | `saveCategories:[CategoryGroupUID]`
 | ↳&nbsp; Delete categories | `deleteCategories:[CategoryGroupUID]`
 | ↳&nbsp; View other users’ drafts | `viewPeerCategoryDrafts:[CategoryGroupUID]`
@@ -149,10 +187,16 @@ You can also require the logged-in user to have a specific permission to access
 {% requirePermission 'accessCp' %}
 ```
 
-## Public Registration
+If the requirements are not met, Craft will send a 403 _Forbidden_ response with the site’s [error template](routing.md#error-templates). Logged-out visitors will be forwarded to the `loginPath`; after signing in, the user will be redirected to the original path—but may still encounter a _Forbidden_ error if their account doesn’t have the correct permissions.
+
+## Public Registration <badge type="edition" title="Craft Pro only">Pro</badge>
 
-Craft Pro has the option of allowing public user registration, which is disabled by default.
+Public user registration is disabled by default, but can be turned on in any Craft Pro project.
 
-To enable public registration, go to **Settings** → **Users** → **Settings**, and check **Allow public registration**. With that checked, you will also have the ability to choose a default user group to which Craft will assign the publicly-registered users.
+To enable public registration, go to **Settings** → **Users** → **Settings**, and check **Allow public registration**. With that checked, you will also have the ability to choose a **Default User Group** that publicly-registered users will be automatically added to.
 
-Once you set up your site to allow public user registration, the last step is to create a [user registration form](kb:front-end-user-accounts#registration-form) on your site’s front end. For a full list of params a user can set during registration (or when updating their account, later on), read about the [`users/save-user` controller action](../reference/controllers/controller-actions.md#post-users-save-user).
+Once you set up your site to allow public user registration, the last step is to create a front-end [user registration form](kb:front-end-user-accounts#registration-form). For a full list of params a user can set during registration (or when updating their account, later on), read about the [`users/save-user` controller action](../reference/controllers/controller-actions.md#post-users-save-user).
+
+::: tip
+By default, Craft puts new users in a [pending](#pending) state and allows them to activate their own accounts via email. You can instead select **Deactivate users by default** to place a moderation buffer between public registration and eventual access.
+:::