docs: add username policy guide

docs/end-user-flows/sign-up-and-sign-in/disable-user-registration.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 8
 sidebar_label: Disable user registration
 ---
 

docs/end-user-flows/sign-up-and-sign-in/error-pages.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 9
 sidebar_label: Error pages
 ---
 

docs/end-user-flows/sign-up-and-sign-in/sign-up.mdx

@@ -14,7 +14,7 @@ Visit <CloudLink to="/sign-in-experience/sign-up-and-sign-in">Console > Sign-in
 
 To successfully create a new user account in Logto, users must provide at least one **identifier** that uniquely identifies them within Logto's system. As the first step, select the identifiers that users must provide during the sign-up process. The available options are:
 
-- **Username**: A unique [username](/user-management/user-data#username) the user can use to sign in to the application.
+- **Username**: A unique [username](/user-management/user-data#username) the user can use to sign in to the application. The accepted username format can be customized with the [username policy](/end-user-flows/sign-up-and-sign-in/username-policy).
 - **Email address**: A valid [email address](/user-management/user-data#primary_email) the user can use to sign in to the application.
 - **Phone number**: A valid [phone number](/user-management/user-data#primary_phone) the user can use to sign in to the application.
 - **Email address or phone number**: Allow users to sign up with either a valid email address or phone number.

docs/end-user-flows/sign-up-and-sign-in/username-policy.mdx

@@ -0,0 +1,40 @@
+---
+sidebar_position: 7
+sidebar_label: Username policy
+---
+
+# Username policy
+
+Logto always enforces a baseline set of username rules: a username contains only letters, numbers, and underscores (`_`), does NOT start with a number, and is no longer than 128 characters. On top of this baseline, you can configure a username policy to further restrict the usernames end users can choose, such as making usernames case-insensitive, narrowing the length range, or limiting the allowed character types.
+
+Logto applies the username policy in different ways depending on how the username is created or updated:
+
+- End-user flows such as [the out-of-the-box sign-in experience](/end-user-flows/sign-up-and-sign-in/sign-up), the [Account API](/end-user-flows/account-settings/by-account-api), and the [Account Center](/end-user-flows/account-settings/by-account-center-ui) always enforce the current username policy. Users see the policy requirements on the username pages and get inline errors when an entered username violates them.
+- Administrator actions via the Management API (e.g., [`POST /api/users`](https://openapi.logto.io/operation/operation-createuser)) are exempt from the policy and only apply the baseline rules, allowing you to provision or migrate users without policy checks when needed.
+
+Updating the policy does not modify or invalidate existing usernames: users keep signing in with their current usernames even if those usernames would no longer be accepted for new registrations.
+
+## Set up username policy \{#set-up-username-policy}
+
+To configure the username policy, follow these steps:
+
+1. Navigate to the <CloudLink to="/sign-in-experience/sign-up-and-sign-in">Console > Sign-in & account > Sign-up and sign-in</CloudLink> page.
+2. Under the **Advanced options** section, click **Manage** on the **Username policy** field.
+
+The following settings are available:
+
+1. **Case sensitive**: Whether usernames that differ only by letter case (e.g., `Alice` and `alice`) are treated as different usernames. Enabled by default. When disabled, users can sign in with any casing of their username, and new usernames that collide with an existing one case-insensitively are rejected.
+2. **Length**: Set the minimum and maximum number of characters allowed for the username, within the baseline range of 1 to 128.
+3. **Allowed characters**: Choose which character types users can include: uppercase letters `(A-Z)`, lowercase letters `(a-z)`, numbers `(0-9)`, and underscores `(_)`. At least one of uppercase letters, lowercase letters, or underscores must stay enabled, since the baseline rules don't allow a username to start with a number.
+
+## Switch to case-insensitive usernames \{#switch-to-case-insensitive-usernames}
+
+Switching an existing tenant from case-sensitive to case-insensitive usernames requires that no two existing usernames collide when compared case-insensitively (e.g., `Alice` and `alice` belonging to two different users). While such conflicts exist, saving the policy is rejected with a `409` error.
+
+When you toggle off **Case sensitive** in the Console, Logto proactively checks for conflicts and lists the colliding usernames so you can resolve them (e.g., by renaming or removing one of the accounts) before saving. You can also query the conflicts directly via [`GET /api/sign-in-exp/username-policy/case-sensitivity-conflicts`](https://openapi.logto.io/operation/operation-getusernamecasesensitivityconflicts).
+
+## Related resources \{#related-resources}
+
+<Url href="/user-management/user-data#username">User data: username</Url>
+<Url href="/end-user-flows/sign-up-and-sign-in/sign-up">Email / phone / username sign-up</Url>
+<Url href="/security/password-policy">Password policy</Url>

docs/user-management/user-data.mdx

@@ -62,7 +62,7 @@ _id_ is a unique auto-generated key to identify the user in Logto.
 
 _username_ is used for sign-in with _username_ and password.
 
-Its value is from the username that the user first registered with. It may be `null`. Its non-null value should be no longer than 128 characters, only contain letters, numbers, and underscores (`_`), and NOT start with a number. It's case-sensitive.
+Its value is from the username that the user first registered with. It may be `null`. Its non-null value should be no longer than 128 characters, only contain letters, numbers, and underscores (`_`), and NOT start with a number. It's case-sensitive by default. These rules can be further restricted per tenant with the [username policy](/end-user-flows/sign-up-and-sign-in/username-policy).
 
 ### primary_email \{#primary_email}
 
@@ -134,6 +134,8 @@ type UserProfile = Partial<{
 
 A difference compared to the other standard claims is that the properties in `profile` will only be included in the [ID token](https://auth.wiki/id-token) or userinfo endpoint response when their values are not empty, while other standard claims will return `null` if the values are empty.
 
+One exception is the `preferred_username` claim: when `preferredUsername` in `profile` is empty, the claim falls back to the user's [username](/user-management/user-data#username), so standards-compliant clients receive a usable value out of the box. The explicit `preferredUsername` value always takes precedence when set.
+
 ### application_id \{#application_id}
 
 The value of _application_id_ is from the application the user first signed in to. It may be `null`.