Merge remote-tracking branch 'origin/main' into pr899

# Conflicts:
#	CHANGELOG.md

docs/api/openapi.yaml

@@ -2782,8 +2782,8 @@ paths:
         not because a wildcard lacks the reach, but because of the lifetimes involved: a native access token lives a day
         and what it could mint here lives a year, so admitting one would let a short-lived compromise leave behind a
         credential that outlives revoking it. Gated by the operator's instance-wide API switch. Body capped at 16 KiB;
-        10 mints per user per minute. Tokens appear in `GET /api/tokens` and are revoked at `DELETE /api/tokens/{id}`
-        like any other.
+        10 mints per user per minute, and at most 10 live tokens held at once. Tokens appear in `GET /api/tokens` and
+        are revoked at `DELETE /api/tokens/{id}` like any other — revoking frees a slot against the ceiling.
       requestBody:
         required: true
         content:
@@ -2811,6 +2811,17 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorEnvelope"
+        "409":
+          description: "The account already holds 10 live measurement tokens (`meta.errorCode` =
+            `tokens.measurements.ceiling_reached`). Nothing was minted. Distinct from the 429 above: that one is a rate
+            and clears by waiting, this one is a conflict with the account's current state and clears by revoking a
+            token at `DELETE /api/tokens/{id}`. Only LIVE tokens count — revoked and expired rows do not occupy a slot —
+            and only those carrying `measurements:write`, so the wildcard tokens a sign-in mints never consume the
+            budget."
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorEnvelope"
         "413":
           description: Body exceeds 16 KiB.
           content:

docs/integrations/home-assistant.md

@@ -22,6 +22,14 @@ Tokens expire after a year by default. They appear in the API Tokens list on
 the same page alongside every other credential on the account, and are revoked
 there.
 
+An account can hold at most ten live measurement tokens at once — across every
+automation platform combined, not ten per platform. Past that, minting another
+is refused with a 409 until you revoke one; revoking frees the slot
+immediately, and an expired token stops counting on its own. It is not a
+security boundary, just a backstop against a script stuck minting in a retry
+loop, so a household running a scale, a watch bridge and a couple of scripts
+will never come close.
+
 ## What the token can and cannot do
 
 It can add readings, on your own record, through: