Lockout guides pilot

docs/custom-flows/error-handling.mdx

@@ -97,4 +97,31 @@ const signIn = await client.signIn.create({
   .then((result) => console.log("result", result))
   .catch((err) => console.error("error", err.errors[0].message));
 ```
-</CodeBlockTabs>
+</CodeBlockTabs>
+
+## Special error cases
+
+### User locked
+
+If you have Account Lockout enabled on your instance and the user reaches the maximum allowed attempts for password or
+backup code verification, you will receive an HTTP status of 403 (Forbidden) and the following error payload:
+
+
+```json
+{
+    "errors": [
+        {
+            "message": "Account locked",
+            "long_message": "Your account is locked. You will be able to try again in 30 minutes. For more information, please contact support.",
+            "code": "user_locked",
+            "meta": {
+                "duration_in_seconds": 1800
+            }
+        }
+    ]
+}
+```
+
+Note: Actual remaining duration will vary depending on your configuration.
+
+You can opt to render the error message returned as-is or format the supplied `duration_in_seconds` as per your liking.

docs/guides/customize-user-lockout.mdx

@@ -0,0 +1,35 @@
+---
+title: Customize max login attempts and duration of user lockout
+description: 
+---
+
+# Customize the max attempts before getting locked out and duration of lock out
+
+<Callout type="info">
+This feature is only available for user accounts that use [passwords](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) and [backup codes](https://dashboard.clerk.com/last-active?path=user-authentication/multi-factor).
+</Callout>
+
+1. In your [Clerk Dashboard](https://dashboard.clerk.com/), navigate to **User & Authentication > [Attack Protection](https://dashboard.clerk.com/last-active?path=user-authentication/attack-protection)**.
+2. To change the number of failed attempts before a user is locked out, under **Maximum attempts,** select "Custom attempts" and enter a new number of failed attempts allowed. (The default is 100 attempts.)
+3. To change the duration, under **Duration,** select "Custom duration" and select the unit of time (minutes/hours/days/years) and enter the number of units you want lockouts to last.
+4. Select "Apply changes" to apply your settings.
+
+<Images
+width={1512}
+height={914}
+src="/docs/images/guides/userlock_custom-attempts-and-duration.png"
+alt=" "
+/>
+
+## Lock a user account forever until an admin unlocks the account
+
+1. In your [Clerk Dashboard](https://dashboard.clerk.com/), navigate to **User & Authentication > [Attack Protection](https://dashboard.clerk.com/last-active?path=user-authentication/attack-protection)**.
+2. Under **Duration,** select "Indefinitely."
+3. Select "Apply changes" to apply your settings.
+
+<Images
+width={1512}
+height={914}
+src="/docs/images/guides/userlock_indefinite.png"
+alt=" "
+/>

docs/guides/overview.mdx

@@ -0,0 +1,8 @@
+---
+title: Clerk Guides
+description: Learn how to use Clerk's components, APIs and the Clerk Dashboard together to protect your users and authenticate your application.
+---
+
+# Clerk Guides
+
+Clerk provides a suite of [prebuilt components](/docs/components/overview) for getting your app authenticated fast, the [Clerk Dashboard](https://dashboard.clerk.com/) for managing your users' accounts and identies, and a [backend API](https://clerk.com/docs/reference/backend-api) for tailoring custom flows to your design and app needs. These guides show you how to use these features together to build delightful, safe, and secure experiences.

docs/guides/programmatically-lock-user-accounts.mdx

@@ -0,0 +1,33 @@
+---
+title: Programmatically locking and unlocking user accounts
+description: Lock users to prevent them from signing in based on your own custom criteria.
+---
+
+# Programmatically locking and unlocking user accounts
+
+## Unlocking a user programmatically
+
+You can programmatically unlock a user using the [UnlockUser](https://clerk.com/docs/reference/backend-api/tag/Users#operation/LockUser) Backend API operation. 
+
+## Usecases
+
+### "Unlock button"
+
+Your custom sign-in page could expose a button or link to request an unlock token when they are locked out of their account.
+
+* Your app should be able to generate a random unlock token and associate it with the user.
+* The unlock token can be sent to the user via email or SMS.
+* After successful entry of the unlock token, your app's backend can issue an unlock request to the Clerk Backend API.
+
+### Send an unlock request to an admin
+
+If your app supports users submitting admin requests, it could expose a way of requesting an admin unlock.
+
+* A request for unlock could arrive in your app's admin dashboard.
+* If an admin reviews the request and decides to grant access back to the user, they can request an unlock from your app's backend, which should in turn call the Clerk Backend API.
+
+# Locking a user programmatically
+
+You can programmatically lock a user based on your own custom criteria, e.g. if they are violating your app's code of conduct.
+
+You can do so via the [LockUser](https://clerk.com/docs/reference/backend-api/tag/Users#operation/LockUser) Backend API operation. Keep in mind that Clerk will still lock the user based on failed verification attempts.

docs/guides/unlock-user-accounts.mdx

@@ -0,0 +1,33 @@
+---
+title: Unlock user accounts from the Clerk Dashboard
+description: 
+---
+
+# Unlock user accounts from the Clerk Dashboard
+
+<Callout type="info">
+This feature is only available for user accounts that use [passwords](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) and [backup codes](https://dashboard.clerk.com/last-active?path=user-authentication/multi-factor).
+</Callout>
+
+Users with admin roles can override lockouts through the Clerk dashboard.
+
+1. In your [Clerk Dashboard](https://dashboard.clerk.com/), navigate to **[Users](https://dashboard.clerk.com/last-active?path=users)**.
+2. Locate the locked user by looking for a "locked" badge next to their username/email. 
+3. Open the admin menu (three little dots).
+4. Select "Unlock" to unlock the user account.
+
+<Images
+width={1512}
+height={914}
+src="/docs/images/guides/userlock_dashboard.png"
+alt=" "
+/>
+
+Alternatively, you can unlock a user's account on their profile page by scrolling to the "Unlock user" section and selecting "Unlock user."
+
+<Images
+width={1512}
+height={914}
+src="/docs/images/guides/userlock_profile.png"
+alt=" "
+/>

docs/guides/user-lock-guide.mdx

@@ -0,0 +1,37 @@
+---
+title: Brute force attacks and locking user accounts
+description: 
+---
+
+# Brute force attacks and locking user accounts
+
+User accounts are a vector for malicious attacks for many reasons from impersonation to collecting personally identifiable information (PII). One method is a "brute force" attack, where a script will attempt many different passwords to log into an account. One line of defense against these attacks is to temporarily deny attempts to log into accounts that attempt too many failed logins in a short period of time. Locking out login attempts disrupts the attack and makes the account a less attractive target.
+
+## How Clerk protects against brute force attacks
+
+**Account Lockout** is a Clerk feature that enables you to protect your users from brute-force attacks on static credentials such as passwords and backup codes. If enabled on your instance, Clerk will automatically track users' failed verification attempts when they try to authenticate via password on backup code.
+
+### How Account Lockout works
+
+If the maximum allowed attempts are reached, the user will be locked out from signing in again until the lockout duration lapses. Lockout can also be [configured to never expire](/docs/guides/customize-user-lockout#lock-a-user-account-forever-until-an-admin-unlocks-the-account), in which case the user will not be able to sign in unless an admin unlocks them.
+
+An admin can [unlock a user before the expiry of the lockout period via the Clerk dashboard](/docs/guides/unlock-user-accounts).
+
+### Defaults
+
+By default, Clerk applications with  will lock user accounts after 100 failed login attempts and require a one hour cool down period before anyone can attempt to log into that account again. (While 100 attempts may seem like a lot to a human, it is very easy to reach this maximum for a bot!)
+
+## What a locked out user sees
+
+When a user exceeds the maximum login attempts, the Clerk [`<SignIn />`](/docs/components/authentication/sign-in) component will inform them how long they've been locked out and to contact support for more information.
+
+<Images
+width={1512}
+height={914}
+src="/docs/images/guides/userlock_login.png"
+alt="The Clerk component login form with a red alert stating 'Your account is locked. You will be able to try again in 59 minutes. For more information, please contact support.'"
+/>
+
+<Callout type="info">
+Currently, users cannot unlock their own account or submit a request to the admin to be unlocked ("self-service unlock"). This is an upcoming feature, so please check our [changelog](https://clerk.com/blog) periodically to find out when it is available. Until then, you can [programmatically lock and unlock user accounts with a custom flow](/docs/guides/programmatically-lock-user-accounts).
+</Callout>

docs/integrations/webhooks.mdx

@@ -89,6 +89,7 @@ Below is an example of a webhook payload for a `user.created` event:
     "gender": "",
     "id": "user_29w83sxmDNGwOuEthce5gg56FcC",
     "last_name": "Example",
+    "locked": false,
     "last_sign_in_at": 1654012591514,
     "object": "user",
     "password_enabled": true,

docs/manifest.json

@@ -23,6 +23,20 @@
       ["Fastify", "/quickstarts/fastify"]
     ]
   ],
+  [
+    {
+      "title": "Guides",
+      "icon": "book-open",
+      "root": "guides"
+    },
+    [ ["Overview","/guides/overview"],
+      "# Protect accounts from attacks",
+      ["Brute force attacks and locking user accounts","/guides/user-lock-guide"],
+      ["Customize user lockout duration and login attempts limits", "/guides/customize-user-lockout"],
+      ["Unlock accounts from the Clerk Dashboard", "/guides/unlock-user-accounts"],
+      ["Programmatically lock and unlock accounts", "/guides/programmatically-lock-user-accounts"]
+    ]
+  ],
   "---",
   [
     {
@@ -293,7 +307,7 @@
   ],
   [
     {
-      "title": "Migrations & Deployments",
+      "title": "Deployments & Migrations",
       "icon": "rocket",
       "root": "deployments"
     },
@@ -341,6 +355,7 @@
       ["Email Deliverability", "/troubleshooting/email-deliverability"],
       ["Script Loading", "/troubleshooting/script-loading"],
       "# Help & Support",
+      ["Create a minimal reproduction", "/troubleshooting/create-a-minimal-reproduction"],
       ["Community Discord", "https://clerk.com/discord"],
       ["Contact Support", "https://clerk.com/support"]
     ]