docs(permissions): state the allowed_ip_ranges save refusal, the live clear and the env recovery

content/docs/permissions/authentication.mdx

@@ -619,7 +619,7 @@ often before the account-level lock engages.
 
 | Setting | Effect |
 |---|---|
-| `allowed_ip_ranges` | Restrict authenticated access to one or more IPv4 CIDR ranges (or exact IPs). The address judged is the one the server establishes, by the same rule as the inbound rate limiter: `X-Forwarded-For` / `X-Real-IP` only when the stack declares `server.trustProxy`, the connection's peer address otherwise. Behind a reverse proxy, declare `server.trustProxy`, or the allow-list judges the proxy's own address. A request whose address cannot be established is refused with `403 IP_NOT_ALLOWED`, like one outside the ranges. `last_login_ip` records the same address. |
+| `allowed_ip_ranges` | Restrict authenticated access to one or more IPv4 CIDR ranges (or exact IPs). The address judged is the one the server establishes, by the same rule as the inbound rate limiter: `X-Forwarded-For` / `X-Real-IP` only when the stack declares `server.trustProxy`, the connection's peer address otherwise. Behind a reverse proxy, declare `server.trustProxy`, or the allow-list judges the proxy's own address. A request whose address cannot be established is refused with `403 IP_NOT_ALLOWED`, like one outside the ranges. `last_login_ip` records the same address. A save that leaves out your own address is refused, and clearing the field applies at once: see [Saving, clearing and lockout recovery](#saving-clearing-and-lockout-recovery). |
 
 > **How enforcement works.** Password expiry (an administrator-forced password
 > change included) and enforced MFA share a single *session-validation gate*.
@@ -650,6 +650,39 @@ often before the account-level lock engages.
 > can't read or change data, or administer the platform, until they fix the
 > issue.
 
+#### Saving, clearing and lockout recovery
+
+These rules apply to `allowed_ip_ranges`.
+
+- **A save that would lock you out is refused.** When you save the field, the server
+  checks the new list against the address your own request comes from. It finds that
+  address by the same rule as the gate (`server.trustProxy` decides whether the
+  forwarded headers count). If no entry matches it, the save is refused with
+  `400 SETTINGS_VALIDATION` and nothing is stored. The check sits on the settings
+  API save, `PUT /api/settings/auth`, which **Setup → Authentication** calls, so any
+  HTTP client gets the same answer. The message names your address, says the list
+  would refuse your own next sign-in, and asks you to add your address or its range,
+  or to save from an address the list matches. It ends with the recovery step below.
+  It is written in your language (English, Chinese, Japanese or Spanish). The field
+  error in `details.fields` also carries your address as `constraint.clientAddress`.
+  If the server cannot establish your address at all, any non-empty list is refused,
+  because the gate would refuse you too. Only a change is checked: saving the list
+  already in force again is not refused. Writes made inside the server (boot, seed,
+  migrations) carry no request and are not checked.
+- **Clearing takes effect at once.** Empty the field and save. No restart is needed:
+  the gate goes back to the list the deployment itself declares (`allowedIpRanges` in
+  its auth configuration, for example set by an `auth:configure` handler), or to no
+  restriction when it declares none. A clear is never refused.
+- **If you are already locked out**, start the server with
+  `OS_AUTH_ALLOWED_IP_RANGES` set to an empty value (`OS_AUTH_ALLOWED_IP_RANGES=`).
+  Environment variables are read at startup, so a restart is needed. An empty value
+  is not the same as an unset variable: any value that is set, the empty string
+  included, is an env override in force. It wins over the stored list, and an empty
+  list means no restriction. While the variable is set, the stored list is kept but
+  not used, and the field is locked: a save to it is refused with
+  `409 SETTINGS_LOCKED`. Remove the variable, and the stored list applies again at
+  the next restart.
+
 ---
 
 ## Advanced Features