@fleetless/contracts 1.1.0 → 2.0.0

package/artifacts/openapi.json

@@ -3382,7 +3382,7 @@
             }
           }
         },
-        "description": "RFC 7591. **The request schema is what this endpoint accepts, not what it parses**: the handler reads the body field by field, because §3.2.2 distinguishes `invalid_redirect_uri` from `invalid_client_metadata` and one `safeParse` failure cannot say which of the two a caller earned. The shape is deliberately **not** strict, which is the schema agreeing with §3.1 rather than a gap in it — a conforming client sends `client_uri`, `logo_uri` and `software_id`, and both the schema and the server ignore them. `client_name` and `redirect_uris` are the two fields read; `grant_types`, `response_types` and `scope` are accepted and ignored. What comes back is what was actually granted, which §3.2.1 allows a server to substitute — this authorization server issues `authorization_code` only, so a client that asked for `refresh_token` is registered and told plainly that it did not get one. The registration carries a TTL. Refusals are `oauthError`; the rate limiter answers `apiError`.",
+        "description": "RFC 7591. **The request schema is what this endpoint accepts, not what it parses**: the handler reads the body field by field, because §3.2.2 distinguishes `invalid_redirect_uri` from `invalid_client_metadata` and one `safeParse` failure cannot say which of the two a caller earned. The shape is deliberately **not** strict, which is the schema agreeing with §3.1 rather than a gap in it — a conforming client sends `client_uri`, `logo_uri` and `software_id`, and both the schema and the server ignore them. `client_name` and `redirect_uris` are the two fields read; `grant_types`, `response_types` and `scope` are accepted and ignored. What comes back is what was actually granted, which §3.2.1 allows a server to substitute — this authorization server grants `authorization_code` and `refresh_token` to every registration. The registration carries a TTL. Refusals are `oauthError`; the rate limiter answers `apiError`.",
         "requestBody": {
           "required": true,
           "content": {
@@ -3522,7 +3522,7 @@
             }
           }
         },
-        "description": "Only `authorization_code` is supported — there is no refresh grant here, so a session ends when its token expires and the client signs in again. Refusals are RFC 6749 §5.2's `oauthError`, so this route emits none of the codes in this reference. The response carries no `refresh_token`; the shape is the same `oauthTokenResponse` the app flow answers, whose refresh field is optional. The code is single-use, PKCE-verified, and its `resource` must match the audience it was authorized for.",
+        "description": "`authorization_code` mints an `mcp_session` access token bound to the central resource and a refresh token; `refresh_token` rotates that pair, and the presented refresh token is consumed — a second presentation revokes the session, as on `/api/auth/refresh`. The refresh token lives ninety days from its last use and is bound to the `client_id` it was issued to. A refresh re-reads the Fleetless user, so a removed account cannot refresh. Refusals are RFC 6749 §5.2's `oauthError`, so this route emits none of the codes in this reference. The code is single-use, PKCE-verified, and its `resource` must match the audience it was authorized for; a `resource` on a refresh must match the session's audience, and is checked before the token is consumed.",
         "requestBody": {
           "required": true,
           "content": {
@@ -3814,7 +3814,7 @@
             }
           }
         },
-        "description": "RFC 7591, the same wire and the same handler as `POST /mcp/oauth/register` — one implementation, because a second answer to \"is this redirect URI acceptable\" would agree with the first only by luck. The request schema is what the endpoint accepts rather than what it parses, for the reason that row gives: §3.2.2 needs two distinguishable refusals and one `safeParse` failure offers one. `client_name` and `redirect_uris` are read; `grant_types`, `response_types` and `scope` are accepted and ignored, and what comes back is what was actually granted, which §3.2.1 allows — `authorization_code` only, so a client that asked for `refresh_token` is registered and told plainly that it did not get one. The registration carries a TTL. \n\n**The registration is scoped to this app.** A `client_id` minted here authorizes at this app's endpoint and nowhere else, so a client registered against one app cannot walk into another's authorize with it, and a developer who switches MCP off is not left with strangers' registrations valid somewhere adjacent. \n\nRefusals are `oauthError`; the rate limiter and `404 not_found` answer `apiError`. That `404` covers an unknown identifier **and** an app with the switch off, mirroring the two metadata documents this endpoint is discovered from — a client that could not read those has no business registering here, and giving it a third distinct answer would only tell it something the documents deliberately do not.",
+        "description": "RFC 7591, the same wire and the same handler as `POST /mcp/oauth/register` — one implementation, because a second answer to \"is this redirect URI acceptable\" would agree with the first only by luck. The request schema is what the endpoint accepts rather than what it parses, for the reason that row gives: §3.2.2 needs two distinguishable refusals and one `safeParse` failure offers one. `client_name` and `redirect_uris` are read; `grant_types`, `response_types` and `scope` are accepted and ignored, and what comes back is what was actually granted, which §3.2.1 allows — this authorization server grants `authorization_code` and `refresh_token` to every registration. The registration carries a TTL. \n\n**The registration is scoped to this app.** A `client_id` minted here authorizes at this app's endpoint and nowhere else, so a client registered against one app cannot walk into another's authorize with it, and a developer who switches MCP off is not left with strangers' registrations valid somewhere adjacent. \n\nRefusals are `oauthError`; the rate limiter and `404 not_found` answer `apiError`. That `404` covers an unknown identifier **and** an app with the switch off, mirroring the two metadata documents this endpoint is discovered from — a client that could not read those has no business registering here, and giving it a third distinct answer would only tell it something the documents deliberately do not.",
         "requestBody": {
           "required": true,
           "content": {
@@ -3973,7 +3973,7 @@
             }
           }
         },
-        "description": "Only `authorization_code`, PKCE-verified and single-use. There is no refresh grant here either, so a session ends when its token expires and the client signs in again; the shape is the same `oauthTokenResponse` the central endpoint answers, whose refresh field is optional and stays empty. **The `aud` is this app's endpoint URL on the canonical public base**, and the code's `resource` must match it — that is the whole of what stops a token minted for one app being spent at another's endpoint. \n\n**Every refusal is RFC 6749 §5.2's `oauthError`, so this route emits none of the codes in this reference — including the ones about the app.** An unknown identifier and a switched-off app are `invalid_client` here, not the `404` and `403` the authorize route beside it answers. The difference is who reads the answer: authorize is walked by a browser and its refusal is read by a person, while this endpoint is called by a client's own code in the middle of a flow, and handing that code an envelope its OAuth library cannot parse turns a clean refusal into an unexplained crash.",
+        "description": "`authorization_code`, PKCE-verified and single-use, and `refresh_token`, which rotates the pair the exchange minted; the refresh token lives ninety days from its last use, is bound to its client and to this app, and a refresh re-reads the app user's status and their standing consent to the client, so a block or a withdrawn consent ends the session at its next refresh at the latest. **The `aud` is this app's endpoint URL on the canonical public base**, and the code's `resource` must match it — that is the whole of what stops a token minted for one app being spent at another's endpoint. \n\n**Every refusal is RFC 6749 §5.2's `oauthError`, so this route emits none of the codes in this reference — including the ones about the app.** An unknown identifier and a switched-off app are `invalid_client` here, not the `404` and `403` the authorize route beside it answers. The difference is who reads the answer: authorize is walked by a browser and its refusal is read by a person, while this endpoint is called by a client's own code in the middle of a flow, and handing that code an envelope its OAuth library cannot parse turns a clean refusal into an unexplained crash.",
         "requestBody": {
           "required": true,
           "content": {
@@ -5022,6 +5022,112 @@
         }
       }
     },
+    "/api/robots/{id}/token/rotate": {
+      "post": {
+        "operationId": "post_api_robots_id_token_rotate",
+        "summary": "Mints a new bridge token for the robot and invalidates the old one.",
+        "tags": [
+          "robots"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "201": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/robot-token-rotate-response"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `tier_required`, `invalid_uuid`, `not_found`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "Owner tier, behind the org-scoped lookup, so a developer-tier admin sees the `404` a stranger would for a robot outside their org rather than a tier refusal that confirms the id exists. `token` is the only moment the new secret exists outside the caller's hands — the cloud stores a hash — so a caller who loses it rotates again. Audited as `robot.token_rotated`, with no `details`: the one interesting value here is the token. \n\n**It stops the bridge that is connected right now.** The old secret is gone the instant the hash is replaced, so the cloud closes that socket with `CLOSE_TOKEN_ROTATED` rather than leaving a bridge speaking on a credential nothing would accept again. A bridge that does not know the code reconnects and is refused at hello as `invalid_token`, which is the honest answer and ends the same way. **The robot is offline until somebody puts the new token on it** — this is a deliberate interruption, not a background rekey, and a fleet cannot be rotated without a visit to each robot."
+      }
+    },
+    "/api/robots/{id}/urdf/joint-state": {
+      "put": {
+        "operationId": "put_api_robots_id_urdf_joint_state",
+        "summary": "Chooses the datapoint whose joint positions move the robot's URDF, or clears it.",
+        "tags": [
+          "robots"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/joint-state-put-response"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `invalid_uuid`, `not_found`, `validation_error`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "**What qualifies**: a datapoint of the **published** configuration whose ROS type is `sensor_msgs/msg/JointState` and which carries no `field` — the whole message, because positions and names arrive together and a single extracted field is half of a pose. Anything else is a `validation_error` naming that rule rather than a stored mapping that renders a battery reading as a robot. `{ \"slug\": null }` clears it, which is why the field is required and nullable rather than optional. \n\n**The mapping cannot outlive what it points at.** Every successful publish re-checks it against the new document and clears it when it no longer qualifies, recording `robot.joint_state_cleared` with the version that did it; a slug rename rewrites it like every other reference the editor already rewrites; deleting the robot takes it along. Every write through this route — a slug or `null` — is on the record too, as `robot.joint_state_set` with the actor and the slug, so a clear a person made is never mistaken for one a publish made. The stored value reads back on `GET /api/robots/:id/assets` as `joint_state_slug`, so a renderer fetches the URDF, the meshes and the mapping from one place.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/joint-state-put-request"
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/robots/{id}": {
       "get": {
         "operationId": "get_api_robots_id",
@@ -7282,6 +7388,58 @@
           }
         },
         "description": "Needs the `assets` capability, refused as `403 capability_required` rather than a bare `forbidden`: the code says a capability is missing and the message says which, so a developer who switched the wrong toggle on is told what to switch. The capability is checked before existence, so a denied robot and an absent one read alike to a caller with no right to tell them apart. `urdf` reports whether a URDF is present and which of its mesh references have no stored asset."
+      },
+      "delete": {
+        "operationId": "delete_api_robots_id_assets",
+        "summary": "Empties a robot's asset store: every URDF, mesh and texture, gone at once.",
+        "tags": [
+          "assets"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          },
+          {
+            "clientToken": []
+          },
+          {
+            "serverKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/assets-clear-response"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `forbidden`, `tier_required`, `invalid_uuid`, `not_found`, `busy`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "The store's escape hatch: a full store is never a dead end, and this is the blunt third of the three answers to it — the URDF upload is exempt from the gate, reconcile after a sync already frees what the new URDF stopped referencing, and this route lets an Owner clear the robot outright. Owner tier, unconditionally, like starting a sync. Removes every asset of the robot and resets its store to `0`; the next sync fills it again. It does not touch the bridge's availability report — `urdf_available` still answers from the connected robot, unrelated to what this cloud happens to have stored. A clear while a sync is running is `409 busy` naming that sync's details, the same refusal starting a second sync gets, because deleting under a running upload would leave the store counter wrong."
       }
     },
     "/api/robots/{id}/assets/{assetId}": {
@@ -9244,10 +9402,9 @@
                   "enum": [
                     "urdf",
                     "mesh",
-                    "texture",
-                    "other"
+                    "texture"
                   ],
-                  "description": "What the file is: the `urdf` itself, a `mesh` it references, a `texture` a mesh or the URDF paints with, or `other`. A renderer decides from this alone, before fetching anything, what to pre-fetch."
+                  "description": "What the file is: the `urdf` itself, a `mesh` it references, or a `texture` a mesh or the URDF paints with. A renderer decides from this alone, before fetching anything, what to pre-fetch."
                 },
                 "name": {
                   "type": "string",
@@ -9348,32 +9505,38 @@
                           "enum": [
                             "unresolvable",
                             "upload_failed",
-                            "refused",
-                            "too_large"
+                            "refused"
                           ],
-                          "description": "Why it failed. `unresolvable` means the reference names nothing the producer can find or may read, and is **permanent** — the only kind reconciliation may treat as gone. `upload_failed` means the bytes exist and the transfer did not succeed, `refused` means it was never attempted because a producer-side ceiling was hit, and `too_large` means it exceeds the upload limit and carries both numbers in `details`."
+                          "description": "Why it failed. `unresolvable` means the reference names nothing the producer can find or may read, and is **permanent** — the only kind reconciliation may treat as gone. `upload_failed` means the bytes exist and the transfer did not succeed, and `refused` means it was never attempted, either because the robot's asset store had no room — then `details` carries the three numbers — or because a producer-side ceiling was hit."
                         },
                         "details": {
-                          "description": "The two numbers behind a `too_large` failure, and absent for every other kind — a forced `null` on every `unresolvable` entry buys nothing. The pairing is enforced, not merely described.",
+                          "description": "The three numbers behind a `refused` entry the robot's store had no room for, and absent for every other kind — a forced `null` on every `unresolvable` entry buys nothing. A `refused` entry may also carry no details: the producer's own ceiling is the other half of that kind, and no store number describes it.",
                           "anyOf": [
                             {
                               "type": "object",
                               "properties": {
-                                "limit_bytes": {
+                                "store_bytes": {
                                   "type": "integer",
                                   "exclusiveMinimum": 0,
                                   "maximum": 9007199254740991,
-                                  "description": "The upload ceiling, in bytes."
+                                  "description": "The robot's store, in bytes."
+                                },
+                                "used_bytes": {
+                                  "type": "integer",
+                                  "minimum": 0,
+                                  "maximum": 9007199254740991,
+                                  "description": "Bytes the robot's assets occupy before this upload."
                                 },
                                 "size_bytes": {
                                   "type": "integer",
                                   "exclusiveMinimum": 0,
                                   "maximum": 9007199254740991,
-                                  "description": "How large the refused file is, in bytes. With `limit_bytes` beside it a developer can tell whether to shrink the mesh or raise the limit; \"too large\" alone answers neither."
+                                  "description": "The refused upload, in bytes."
                                 }
                               },
                               "required": [
-                                "limit_bytes",
+                                "store_bytes",
+                                "used_bytes",
                                 "size_bytes"
                               ],
                               "additionalProperties": false
@@ -9404,6 +9567,25 @@
                     ],
                     "description": "Why the sync ended as it did, when that is not a per-reference fact. `null` when `failed` already says everything there is to say."
                   },
+                  "stored": {
+                    "anyOf": [
+                      {
+                        "type": "integer",
+                        "minimum": 0,
+                        "maximum": 9007199254740991
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "How many of the announced files the cloud's store actually holds. Counted once, after the robot reports the sync done, and `null` until then — nobody has looked yet. Read it against `announced`: `state` is what the robot reported, this is what arrived."
+                  },
+                  "announced": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991,
+                    "description": "How many files the robot announced for this sync — the URDF, if it has one, plus every mesh URI its description references. `0` when the robot announced nothing, and also `0` until it has answered at all: read it beside `stored`, which stays `null` until the terminal frame."
+                  },
                   "started_at": {
                     "type": "string",
                     "format": "date-time",
@@ -9425,6 +9607,8 @@
                   "total",
                   "failed",
                   "reason",
+                  "stored",
+                  "announced",
                   "started_at",
                   "updated_at"
                 ],
@@ -9496,13 +9680,52 @@
               }
             ],
             "description": "What the connected bridge says it *could* transfer — deliberately separate from what has been transferred. `null` when no bridge is connected, distinct from `false`: \"no robot is online to ask\" and \"the robot has no URDF\" send a developer to different places. After a publisher is killed rather than shut down this can read `true` for some seconds, on the underlying DDS liveliness timeout rather than on any check made here."
+          },
+          "store": {
+            "type": "object",
+            "properties": {
+              "bytes": {
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991,
+                "description": "The robot's asset store, `ROBOT_ASSET_STORE_BYTES`."
+              },
+              "used_bytes": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Bytes its assets occupy."
+              }
+            },
+            "required": [
+              "bytes",
+              "used_bytes"
+            ],
+            "additionalProperties": false,
+            "description": "How full this robot's store is."
+          },
+          "joint_state_slug": {
+            "anyOf": [
+              {
+                "type": "string",
+                "minLength": 2,
+                "maxLength": 63,
+                "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The whole-message `sensor_msgs/msg/JointState` datapoint that drives the console's URDF viewer; null when none is chosen or a publish removed it. Set through `PUT /api/robots/:id/urdf/joint-state`."
           }
         },
         "required": [
           "assets",
           "active_sync",
           "urdf",
-          "urdf_available"
+          "urdf_available",
+          "store",
+          "joint_state_slug"
         ],
         "additionalProperties": false
       },
@@ -9590,32 +9813,38 @@
                   "enum": [
                     "unresolvable",
                     "upload_failed",
-                    "refused",
-                    "too_large"
+                    "refused"
                   ],
-                  "description": "Why it failed. `unresolvable` means the reference names nothing the producer can find or may read, and is **permanent** — the only kind reconciliation may treat as gone. `upload_failed` means the bytes exist and the transfer did not succeed, `refused` means it was never attempted because a producer-side ceiling was hit, and `too_large` means it exceeds the upload limit and carries both numbers in `details`."
+                  "description": "Why it failed. `unresolvable` means the reference names nothing the producer can find or may read, and is **permanent** — the only kind reconciliation may treat as gone. `upload_failed` means the bytes exist and the transfer did not succeed, and `refused` means it was never attempted, either because the robot's asset store had no room — then `details` carries the three numbers — or because a producer-side ceiling was hit."
                 },
                 "details": {
-                  "description": "The two numbers behind a `too_large` failure, and absent for every other kind — a forced `null` on every `unresolvable` entry buys nothing. The pairing is enforced, not merely described.",
+                  "description": "The three numbers behind a `refused` entry the robot's store had no room for, and absent for every other kind — a forced `null` on every `unresolvable` entry buys nothing. A `refused` entry may also carry no details: the producer's own ceiling is the other half of that kind, and no store number describes it.",
                   "anyOf": [
                     {
                       "type": "object",
                       "properties": {
-                        "limit_bytes": {
+                        "store_bytes": {
                           "type": "integer",
                           "exclusiveMinimum": 0,
                           "maximum": 9007199254740991,
-                          "description": "The upload ceiling, in bytes."
+                          "description": "The robot's store, in bytes."
+                        },
+                        "used_bytes": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 9007199254740991,
+                          "description": "Bytes the robot's assets occupy before this upload."
                         },
                         "size_bytes": {
                           "type": "integer",
                           "exclusiveMinimum": 0,
                           "maximum": 9007199254740991,
-                          "description": "How large the refused file is, in bytes. With `limit_bytes` beside it a developer can tell whether to shrink the mesh or raise the limit; \"too large\" alone answers neither."
+                          "description": "The refused upload, in bytes."
                         }
                       },
                       "required": [
-                        "limit_bytes",
+                        "store_bytes",
+                        "used_bytes",
                         "size_bytes"
                       ],
                       "additionalProperties": false
@@ -9646,6 +9875,25 @@
             ],
             "description": "Why the sync ended as it did, when that is not a per-reference fact. `null` when `failed` already says everything there is to say."
           },
+          "stored": {
+            "anyOf": [
+              {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "How many of the announced files the cloud's store actually holds. Counted once, after the robot reports the sync done, and `null` until then — nobody has looked yet. Read it against `announced`: `state` is what the robot reported, this is what arrived."
+          },
+          "announced": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "How many files the robot announced for this sync — the URDF, if it has one, plus every mesh URI its description references. `0` when the robot announced nothing, and also `0` until it has answered at all: read it beside `stored`, which stays `null` until the terminal frame."
+          },
           "started_at": {
             "type": "string",
             "format": "date-time",
@@ -9667,11 +9915,35 @@
           "total",
           "failed",
           "reason",
+          "stored",
+          "announced",
           "started_at",
           "updated_at"
         ],
         "additionalProperties": false
       },
+      "assets-clear-response": {
+        "type": "object",
+        "properties": {
+          "deleted": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "How many assets — URDF, meshes and textures together — were removed."
+          },
+          "bytes_freed": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "The bytes the robot's store got back."
+          }
+        },
+        "required": [
+          "deleted",
+          "bytes_freed"
+        ],
+        "additionalProperties": false
+      },
       "audit-list-response": {
         "type": "object",
         "properties": {
@@ -9953,7 +10225,7 @@
                 "refresh_token"
               ]
             },
-            "description": "The grants this server offers. OAuth 2.1 removes the implicit and password grants, so neither appears here."
+            "description": "The grants this server offers: `authorization_code` and `refresh_token`. OAuth 2.1 removes the implicit and password grants, so neither appears here."
           },
           "code_challenge_methods_supported": {
             "type": "array",
@@ -10535,11 +10807,16 @@
                           "type": "null"
                         }
                       ]
+                    },
+                    "low_bandwidth": {
+                      "type": "boolean",
+                      "description": "Whether the bridge is in its low-bandwidth mode: datapoints capped, cameras reduced or stopped. Bridge-reported."
                     }
                   },
                   "required": [
                     "online",
-                    "latency_ms"
+                    "latency_ms",
+                    "low_bandwidth"
                   ],
                   "additionalProperties": false,
                   "description": "The built-in `bridge_state` datapoint as the cloud observes it right now: whether the bridge is connected, and its latency when it is."
@@ -10665,6 +10942,11 @@
                             0.5
                           ]
                         },
+                        "low_bandwidth": {
+                          "description": "`keep` exempts this datapoint from the low-bandwidth rate cap; its backfill still pauses.",
+                          "type": "string",
+                          "const": "keep"
+                        },
                         "description": {
                           "description": "Prose about what this value is, for whoever meets it in the console. It changes nothing the robot does, so a publish that touches only it pushes no configuration at all — but it is carried verbatim into `robot_describe`, where a model that has never seen this robot reads it. The datapoint is offered whenever the role grants it; without one it is offered with `description: null` and the model has less to go on, as for actions, services, publishers and cameras. Omission is the only way to say nothing; an empty string is refused, here and on all five.",
                           "examples": [
@@ -10862,7 +11144,7 @@
                       ],
                       "additionalProperties": false
                     },
-                    "description": "Values the robot publishes, each one field of one topic or a whole topic, and **never several topics**. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                    "description": "Values the robot publishes, each one field of one topic or a whole topic, and **never several topics**. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
                   },
                   "actions": {
                     "type": "object",
@@ -11012,7 +11294,7 @@
                       ],
                       "additionalProperties": false
                     },
-                    "description": "Things the robot does on request that take time, each reported as a job with progress. **At most one job runs per action slug**: a second call is refused `busy`, and every observer of that slug watches the same job. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                    "description": "Things the robot does on request that take time, each reported as a job with progress. **At most one job runs per action slug**: a second call is refused `busy`, and every observer of that slug watches the same job. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
                   },
                   "services": {
                     "type": "object",
@@ -11162,7 +11444,7 @@
                       ],
                       "additionalProperties": false
                     },
-                    "description": "ROS service calls the robot answers — one request, one reply. Unlike an action a service reports **no progress** and the call returns with its result already on the job, so there is nothing left to observe; a second concurrent call is still refused `busy`, exactly as for an action. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                    "description": "ROS service calls the robot answers — one request, one reply. Unlike an action a service reports **no progress** and the call returns with its result already on the job, so there is nothing left to observe; a second concurrent call is still refused `busy`, exactly as for an action. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
                   },
                   "publishers": {
                     "type": "object",
@@ -11348,7 +11630,7 @@
                       ],
                       "additionalProperties": false
                     },
-                    "description": "Topics clients may send to, and where the format's whole safety story lives. The `message` template fixes every value a caller cannot change, and **`failsafe` is required**: once a client falls silent the bridge sends the failsafe message itself, so an operator whose window closed does not leave a robot driving. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                    "description": "Topics clients may send to, and where the format's whole safety story lives. The `message` template fixes every value a caller cannot change, and **`failsafe` is required**: once a client falls silent the bridge sends the failsafe message itself, so an operator whose window closed does not leave a robot driving. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
                   },
                   "cameras": {
                     "type": "object",
@@ -11596,7 +11878,67 @@
                       ],
                       "additionalProperties": false
                     },
-                    "description": "Video the robot streams, and the still frames the cloud serves from it. `width`, `height`, `fps` and `bitrate_kbps` are what **the bridge produces before sending**, not what the camera captures — they live in the configuration rather than in a viewer's request precisely so that no viewer can make a robot send more. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                    "description": "Video the robot streams, and the still frames the cloud serves from it. `width`, `height`, `fps` and `bitrate_kbps` are what **the bridge produces before sending**, not what the camera captures — they live in the configuration rather than in a viewer's request precisely so that no viewer can make a robot send more. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
+                  },
+                  "low_bandwidth": {
+                    "description": "Overrides for the bridge's low-bandwidth mode; see the section schema.",
+                    "type": "object",
+                    "properties": {
+                      "mode": {
+                        "description": "`auto` decides from the measured lag; `on` and `off` force the mode, for tests and for an operator who knows the link.",
+                        "type": "string",
+                        "enum": [
+                          "auto",
+                          "on",
+                          "off"
+                        ]
+                      },
+                      "enter_lag_ms": {
+                        "description": "Lag or queue dwell above this enters the mode. Checked against exit_lag_ms only when both are in this document; a lone key composes with the bridge's parameter or the default on the robot, and a crossed pair is refused there when the configuration is applied, so name both when you change either.",
+                        "type": "integer",
+                        "minimum": 100,
+                        "maximum": 9007199254740991
+                      },
+                      "enter_after_s": {
+                        "description": "The entry condition must hold this long.",
+                        "type": "integer",
+                        "minimum": 1,
+                        "maximum": 9007199254740991
+                      },
+                      "exit_lag_ms": {
+                        "description": "Lag and dwell both at or below this leave the mode. Must be at or below enter_lag_ms: a crossed pair is a mode that leaves as it arrives. Checked here only when both keys are present; a lone key is checked on the robot against the parameter or default it composes with.",
+                        "type": "integer",
+                        "minimum": 0,
+                        "maximum": 9007199254740991
+                      },
+                      "exit_after_s": {
+                        "description": "The exit condition must hold this long.",
+                        "type": "integer",
+                        "minimum": 1,
+                        "maximum": 9007199254740991
+                      },
+                      "datapoint_max_hz": {
+                        "description": "The long-run rate for every datapoint in the mode, unless the datapoint says `low_bandwidth: keep`. It is an average, not a minimum gap: after a quiet spell two samples may go out close together, and over any longer window the rate holds.",
+                        "type": "number",
+                        "exclusiveMinimum": 0,
+                        "maximum": 20
+                      },
+                      "camera": {
+                        "description": "What happens to a running stream in the mode. New streams are refused either way.",
+                        "type": "string",
+                        "enum": [
+                          "reduce",
+                          "stop"
+                        ]
+                      },
+                      "camera_bitrate_kbps": {
+                        "description": "Bitrate applied to running streams under `reduce`.",
+                        "type": "integer",
+                        "minimum": 50,
+                        "maximum": 20000
+                      }
+                    },
+                    "additionalProperties": false
                   }
                 },
                 "required": [
@@ -11762,6 +12104,11 @@
                         0.5
                       ]
                     },
+                    "low_bandwidth": {
+                      "description": "`keep` exempts this datapoint from the low-bandwidth rate cap; its backfill still pauses.",
+                      "type": "string",
+                      "const": "keep"
+                    },
                     "description": {
                       "description": "Prose about what this value is, for whoever meets it in the console. It changes nothing the robot does, so a publish that touches only it pushes no configuration at all — but it is carried verbatim into `robot_describe`, where a model that has never seen this robot reads it. The datapoint is offered whenever the role grants it; without one it is offered with `description: null` and the model has less to go on, as for actions, services, publishers and cameras. Omission is the only way to say nothing; an empty string is refused, here and on all five.",
                       "examples": [
@@ -11959,7 +12306,7 @@
                   ],
                   "additionalProperties": false
                 },
-                "description": "Values the robot publishes, each one field of one topic or a whole topic, and **never several topics**. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                "description": "Values the robot publishes, each one field of one topic or a whole topic, and **never several topics**. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
               },
               "actions": {
                 "type": "object",
@@ -12109,7 +12456,7 @@
                   ],
                   "additionalProperties": false
                 },
-                "description": "Things the robot does on request that take time, each reported as a job with progress. **At most one job runs per action slug**: a second call is refused `busy`, and every observer of that slug watches the same job. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                "description": "Things the robot does on request that take time, each reported as a job with progress. **At most one job runs per action slug**: a second call is refused `busy`, and every observer of that slug watches the same job. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
               },
               "services": {
                 "type": "object",
@@ -12259,7 +12606,7 @@
                   ],
                   "additionalProperties": false
                 },
-                "description": "ROS service calls the robot answers — one request, one reply. Unlike an action a service reports **no progress** and the call returns with its result already on the job, so there is nothing left to observe; a second concurrent call is still refused `busy`, exactly as for an action. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                "description": "ROS service calls the robot answers — one request, one reply. Unlike an action a service reports **no progress** and the call returns with its result already on the job, so there is nothing left to observe; a second concurrent call is still refused `busy`, exactly as for an action. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
               },
               "publishers": {
                 "type": "object",
@@ -12445,7 +12792,7 @@
                   ],
                   "additionalProperties": false
                 },
-                "description": "Topics clients may send to, and where the format's whole safety story lives. The `message` template fixes every value a caller cannot change, and **`failsafe` is required**: once a client falls silent the bridge sends the failsafe message itself, so an operator whose window closed does not leave a robot driving. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                "description": "Topics clients may send to, and where the format's whole safety story lives. The `message` template fixes every value a caller cannot change, and **`failsafe` is required**: once a client falls silent the bridge sends the failsafe message itself, so an operator whose window closed does not leave a robot driving. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
               },
               "cameras": {
                 "type": "object",
@@ -12693,7 +13040,67 @@
                   ],
                   "additionalProperties": false
                 },
-                "description": "Video the robot streams, and the still frames the cloud serves from it. `width`, `height`, `fps` and `bitrate_kbps` are what **the bridge produces before sending**, not what the camera captures — they live in the configuration rather than in a viewer's request precisely so that no viewer can make a robot send more. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                "description": "Video the robot streams, and the still frames the cloud serves from it. `width`, `height`, `fps` and `bitrate_kbps` are what **the bridge produces before sending**, not what the camera captures — they live in the configuration rather than in a viewer's request precisely so that no viewer can make a robot send more. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
+              },
+              "low_bandwidth": {
+                "description": "Overrides for the bridge's low-bandwidth mode; see the section schema.",
+                "type": "object",
+                "properties": {
+                  "mode": {
+                    "description": "`auto` decides from the measured lag; `on` and `off` force the mode, for tests and for an operator who knows the link.",
+                    "type": "string",
+                    "enum": [
+                      "auto",
+                      "on",
+                      "off"
+                    ]
+                  },
+                  "enter_lag_ms": {
+                    "description": "Lag or queue dwell above this enters the mode. Checked against exit_lag_ms only when both are in this document; a lone key composes with the bridge's parameter or the default on the robot, and a crossed pair is refused there when the configuration is applied, so name both when you change either.",
+                    "type": "integer",
+                    "minimum": 100,
+                    "maximum": 9007199254740991
+                  },
+                  "enter_after_s": {
+                    "description": "The entry condition must hold this long.",
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 9007199254740991
+                  },
+                  "exit_lag_ms": {
+                    "description": "Lag and dwell both at or below this leave the mode. Must be at or below enter_lag_ms: a crossed pair is a mode that leaves as it arrives. Checked here only when both keys are present; a lone key is checked on the robot against the parameter or default it composes with.",
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  "exit_after_s": {
+                    "description": "The exit condition must hold this long.",
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 9007199254740991
+                  },
+                  "datapoint_max_hz": {
+                    "description": "The long-run rate for every datapoint in the mode, unless the datapoint says `low_bandwidth: keep`. It is an average, not a minimum gap: after a quiet spell two samples may go out close together, and over any longer window the rate holds.",
+                    "type": "number",
+                    "exclusiveMinimum": 0,
+                    "maximum": 20
+                  },
+                  "camera": {
+                    "description": "What happens to a running stream in the mode. New streams are refused either way.",
+                    "type": "string",
+                    "enum": [
+                      "reduce",
+                      "stop"
+                    ]
+                  },
+                  "camera_bitrate_kbps": {
+                    "description": "Bitrate applied to running streams under `reduce`.",
+                    "type": "integer",
+                    "minimum": 50,
+                    "maximum": 20000
+                  }
+                },
+                "additionalProperties": false
               }
             },
             "required": [
@@ -13102,7 +13509,7 @@
                 },
                 "builtin": {
                   "type": "boolean",
-                  "description": "`true` for the datapoints every robot has — `bridge_state`, `robot_details` and `bridge_pressure` — and `false` for everything the published configuration adds."
+                  "description": "`true` for the datapoints every robot has — `bridge_state` and `robot_details` — and `false` for everything the published configuration adds."
                 },
                 "unit": {
                   "anyOf": [
@@ -13137,7 +13544,7 @@
               ],
               "additionalProperties": false
             },
-            "description": "Everything a client may read on this robot: the three built-ins, plus every datapoint the published configuration exposes and the caller's role grants."
+            "description": "Everything a client may read on this robot: the two built-ins, plus every datapoint the published configuration exposes and the caller's role grants."
           }
         },
         "required": [
@@ -13200,7 +13607,7 @@
             ]
           },
           "grant_types": {
-            "description": "Accepted for conformance with RFC 7591 and then **ignored**. What comes back is what was actually granted, which §3.2.1 permits a server to substitute: `authorization_code` and nothing else, so a client that asks for `refresh_token` is registered and told plainly that it did not get one.",
+            "description": "Accepted for conformance with RFC 7591 and then **ignored**: both MCP authorization servers grant `authorization_code` and `refresh_token` to every registration, and the answer states what was granted (§3.2.1) rather than what was asked.",
             "type": "array",
             "items": {
               "type": "string",
@@ -13260,7 +13667,7 @@
             "items": {
               "type": "string"
             },
-            "description": "The grants this client may use. Always exactly `[\"authorization_code\"]` — a client that asked for `refresh_token` is registered and told here that it did not get one, which is the substitution RFC 7591 §3.2.1 permits."
+            "description": "The grants this client may use. Always exactly `[\"authorization_code\", \"refresh_token\"]` — an exchange mints a refresh token and the token endpoint rotates it."
           },
           "response_types": {
             "type": "array",
@@ -14452,6 +14859,51 @@
         ],
         "additionalProperties": false
       },
+      "joint-state-put-request": {
+        "type": "object",
+        "properties": {
+          "slug": {
+            "anyOf": [
+              {
+                "type": "string",
+                "minLength": 2,
+                "maxLength": 63,
+                "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The datapoint to read joint positions from, or `null` to choose none. It must name a whole-message `sensor_msgs/msg/JointState` datapoint of the published configuration; anything else is a `validation_error` naming the rule."
+          }
+        },
+        "required": [
+          "slug"
+        ]
+      },
+      "joint-state-put-response": {
+        "type": "object",
+        "properties": {
+          "joint_state_slug": {
+            "anyOf": [
+              {
+                "type": "string",
+                "minLength": 2,
+                "maxLength": 63,
+                "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The stored mapping after the call, `null` when none is chosen. The same value `assetListResponse.joint_state_slug` carries."
+          }
+        },
+        "required": [
+          "joint_state_slug"
+        ],
+        "additionalProperties": false
+      },
       "live-session-response": {
         "type": "object",
         "properties": {
@@ -14874,50 +15326,88 @@
         "additionalProperties": false
       },
       "oauth-token-request": {
-        "type": "object",
-        "properties": {
-          "grant_type": {
-            "type": "string",
-            "const": "authorization_code",
-            "description": "Always `authorization_code`: this request exchanges the code from the authorize redirect for tokens. Any other value — `refresh_token` included — is `unsupported_grant_type`, refused before the code is looked up."
-          },
-          "code": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 500,
-            "description": "The authorization code from the redirect. It may be exchanged once; a second presentation is `invalid_grant`, the same answer a fabricated code gets."
-          },
-          "redirect_uri": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 2000,
-            "description": "The same redirect URI the authorize request used. It is compared, not merely recorded."
-          },
-          "client_id": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 200,
-            "description": "The client making the exchange, as registered."
-          },
-          "code_verifier": {
-            "type": "string",
-            "pattern": "^[A-Za-z0-9\\-._~]{43,128}$",
-            "description": "The PKCE verifier whose `S256` hash was sent as the challenge at the authorize step. Between `43` and `128` unreserved characters, per RFC 7636 §4.1 — it is compared rather than parsed, so a length nobody checks is a length an attacker chooses. PKCE is mandatory for every client under OAuth 2.1."
+        "oneOf": [
+          {
+            "type": "object",
+            "properties": {
+              "grant_type": {
+                "type": "string",
+                "const": "authorization_code",
+                "description": "`authorization_code`: this request exchanges the code from the authorize redirect for an access token and a refresh token."
+              },
+              "code": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 500,
+                "description": "The authorization code from the redirect. It may be exchanged once; a second presentation is `invalid_grant`, the same answer a fabricated code gets."
+              },
+              "redirect_uri": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 2000,
+                "description": "The same redirect URI the authorize request used. It is compared, not merely recorded."
+              },
+              "client_id": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 200,
+                "description": "The client making the exchange, as registered."
+              },
+              "code_verifier": {
+                "type": "string",
+                "pattern": "^[A-Za-z0-9\\-._~]{43,128}$",
+                "description": "The PKCE verifier whose `S256` hash was sent as the challenge at the authorize step. Between `43` and `128` unreserved characters, per RFC 7636 §4.1 — it is compared rather than parsed, so a length nobody checks is a length an attacker chooses. PKCE is mandatory for every client under OAuth 2.1."
+              },
+              "resource": {
+                "description": "The resource the token is requested for, per RFC 8707. It must match the audience the code was authorized for, or the answer is `invalid_target`; omitted, the code's own audience stands. It becomes the token's `aud`, and a resource refuses a token whose audience names something else — which is what keeps a token minted for one app out of another app's endpoint.",
+                "type": "string",
+                "format": "uri"
+              }
+            },
+            "required": [
+              "grant_type",
+              "code",
+              "redirect_uri",
+              "client_id",
+              "code_verifier"
+            ],
+            "description": "RFC 6749 §4.1.3's authorization-code exchange with PKCE, as either MCP authorization server reads it. Sent as `application/x-www-form-urlencoded`, per §4.1.3, though the server accepts a JSON body too."
           },
-          "resource": {
-            "description": "The resource the token is requested for, per RFC 8707. It must match the audience the code was authorized for, or the answer is `invalid_target`; omitted, the code's own audience stands. It becomes the token's `aud`, and a resource refuses a token whose audience names something else — which is what keeps a token minted for one app out of another app's endpoint.",
-            "type": "string",
-            "format": "uri"
+          {
+            "type": "object",
+            "properties": {
+              "grant_type": {
+                "type": "string",
+                "const": "refresh_token",
+                "description": "`refresh_token`: this request rotates a refresh token into a new access token and a new refresh token. The presented token is consumed; presenting it again revokes the whole session."
+              },
+              "refresh_token": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 500,
+                "description": "The refresh token from the last token response. Bound to the client that received it and to one identity space: presented by another client, or at the other MCP server, it is `invalid_grant` and stays unconsumed."
+              },
+              "client_id": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 200,
+                "description": "The client the refresh token was issued to, as registered. A refresh token is not transferable between clients."
+              },
+              "resource": {
+                "description": "The resource the new token is for, per RFC 8707. Optional; when named it must be the audience the session was issued for, or the answer is `invalid_target` and the refresh token is left untouched. The successor carries the same audience either way.",
+                "type": "string",
+                "format": "uri"
+              }
+            },
+            "required": [
+              "grant_type",
+              "refresh_token",
+              "client_id"
+            ],
+            "description": "RFC 6749 §6's refresh, as either MCP authorization server reads it. Every use rotates: the answer carries a new refresh token and the presented one is dead."
           }
-        },
-        "required": [
-          "grant_type",
-          "code",
-          "redirect_uri",
-          "client_id",
-          "code_verifier"
         ],
-        "description": "RFC 6749 §4.1.3's authorization-code exchange with PKCE, as either MCP authorization server reads it. Sent as `application/x-www-form-urlencoded`, per §4.1.3, though the server accepts a JSON body too."
+        "description": "What an MCP token endpoint accepts: the authorization-code exchange, or a refresh. Any other `grant_type` is `unsupported_grant_type`, refused before a lookup happens."
       },
       "oauth-token-response": {
         "type": "object",
@@ -14939,7 +15429,7 @@
             "description": "How long the access token is valid, in **seconds**, per RFC 6749 §5.1. Not a timestamp, and not milliseconds."
           },
           "refresh_token": {
-            "description": "The refresh token, when one was issued. It rotates on every use.",
+            "description": "The refresh token. Both MCP token endpoints issue one on every exchange and every refresh; it rotates on every use, lives ninety days from its last use, and dies with the account's sessions — a block, a password change, a withdrawn consent. The console's own OAuth portal issues none.",
             "type": "string",
             "minLength": 1
           },
@@ -15291,11 +15781,6 @@
                 "type": "integer",
                 "exclusiveMinimum": 0,
                 "maximum": 9007199254740991
-              },
-              "max_asset_storage_bytes": {
-                "type": "integer",
-                "minimum": 0,
-                "maximum": 9007199254740991
               }
             },
             "required": [
@@ -15304,8 +15789,7 @@
               "max_end_users",
               "max_retention_bytes",
               "max_retention_writes_per_minute",
-              "max_realtime_connections",
-              "max_asset_storage_bytes"
+              "max_realtime_connections"
             ],
             "additionalProperties": false
           },
@@ -15332,11 +15816,6 @@
                 "minimum": 0,
                 "maximum": 9007199254740991
               },
-              "max_asset_storage_bytes": {
-                "type": "integer",
-                "minimum": 0,
-                "maximum": 9007199254740991
-              },
               "max_retention_writes_per_minute": {
                 "type": "integer",
                 "minimum": 0,
@@ -16230,7 +16709,8 @@
           "asset_bytes_freed": {
             "type": "integer",
             "minimum": 0,
-            "maximum": 9007199254740991
+            "maximum": 9007199254740991,
+            "description": "What the robot's store gives back: every distinct mesh or texture blob it holds, counted once, URDF excluded; a blob another robot also references stays in the object store but is still credited here, because each robot's counter carries it."
           },
           "job_run_count": {
             "type": "integer",
@@ -16294,11 +16774,16 @@
                     "type": "null"
                   }
                 ]
+              },
+              "low_bandwidth": {
+                "type": "boolean",
+                "description": "Whether the bridge is in its low-bandwidth mode: datapoints capped, cameras reduced or stopped. Bridge-reported."
               }
             },
             "required": [
               "online",
-              "latency_ms"
+              "latency_ms",
+              "low_bandwidth"
             ],
             "additionalProperties": false
           },
@@ -16340,6 +16825,15 @@
             ],
             "additionalProperties": false
           },
+          "protocol_status": {
+            "description": "Where this robot's bridge stands against the protocol window: `current`, `deprecated` (still served, sunset date on the detail), or `refused` (its last hello was refused for its version; offline until upgraded). Absent from a cloud older than 0.21.0; read absence as `current`.",
+            "type": "string",
+            "enum": [
+              "current",
+              "deprecated",
+              "refused"
+            ]
+          },
           "bridge_version": {
             "anyOf": [
               {
@@ -16351,6 +16845,52 @@
               }
             ]
           },
+          "protocol_version": {
+            "description": "The protocol version the bridge announced in its last accepted hello; `null` before the first. Absent from a cloud older than 0.21.0.",
+            "anyOf": [
+              {
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "protocol": {
+            "description": "The window verdict for `protocol_version`.",
+            "type": "object",
+            "properties": {
+              "status": {
+                "type": "string",
+                "enum": [
+                  "current",
+                  "deprecated",
+                  "refused"
+                ],
+                "description": "Same values as `protocol_status`."
+              },
+              "sunset_at": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "format": "date",
+                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "ISO date the announced version stops being served; `null` when current or unknown."
+              }
+            },
+            "required": [
+              "status",
+              "sunset_at"
+            ],
+            "additionalProperties": false
+          },
           "last_hello_error": {
             "anyOf": [
               {
@@ -16460,7 +17000,8 @@
                             "action",
                             "service",
                             "publisher",
-                            "camera"
+                            "camera",
+                            "low_bandwidth"
                           ]
                         },
                         "code": {
@@ -16678,11 +17219,16 @@
                           "type": "null"
                         }
                       ]
+                    },
+                    "low_bandwidth": {
+                      "type": "boolean",
+                      "description": "Whether the bridge is in its low-bandwidth mode: datapoints capped, cameras reduced or stopped. Bridge-reported."
                     }
                   },
                   "required": [
                     "online",
-                    "latency_ms"
+                    "latency_ms",
+                    "low_bandwidth"
                   ],
                   "additionalProperties": false
                 },
@@ -16723,6 +17269,15 @@
                     "cameras"
                   ],
                   "additionalProperties": false
+                },
+                "protocol_status": {
+                  "description": "Where this robot's bridge stands against the protocol window: `current`, `deprecated` (still served, sunset date on the detail), or `refused` (its last hello was refused for its version; offline until upgraded). Absent from a cloud older than 0.21.0; read absence as `current`.",
+                  "type": "string",
+                  "enum": [
+                    "current",
+                    "deprecated",
+                    "refused"
+                  ]
                 }
               },
               "required": [
@@ -16741,6 +17296,20 @@
         ],
         "additionalProperties": false
       },
+      "robot-token-rotate-response": {
+        "type": "object",
+        "properties": {
+          "token": {
+            "type": "string",
+            "pattern": "^frt_[0-9a-f]{32}$",
+            "description": "The robot's new bridge token. Returned exactly once; the previous token stops working at the bridge's next hello."
+          }
+        },
+        "required": [
+          "token"
+        ],
+        "additionalProperties": false
+      },
       "role": {
         "type": "object",
         "properties": {