@fleetless/contracts 1.0.5 → 1.1.0

package/artifacts/routes.json

@@ -273,6 +273,24 @@
       "transport": "http",
       "notes": "HTML. An unknown, spent or expired token renders one \"link no longer valid\" page at `410` — they are one refusal on the wire already, and splitting them here would tell a stranger which tokens ever existed. No rate limiter: the GET changes nothing, and the POST it leads to is limited per IP."
     },
+    {
+      "method": "GET",
+      "path": "/favicon.svg",
+      "section": "client-auth",
+      "summary": "Serves the Fleetless icon for the auth portal's and the MCP welcome page's browser tab.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [],
+      "transport": "http",
+      "notes": "An SVG, not JSON. Those pages carry a Content-Security-Policy that admits no `data:` image, so the icon is a file on their own origin — the one source `img-src 'self'` names. Cached for a day: the bytes change when the brand does, not per deploy."
+    },
     {
       "method": "POST",
       "path": "/api/auth/password/reset/confirm",
@@ -1006,7 +1024,7 @@
         },
         {
           "name": "clientId",
-          "description": "The MCP client, as `GET /api/apps/:id/users/:userId/mcp-grants` reports its `client_id`. Not a uuid — it is the identifier the dynamic registration issued."
+          "description": "The MCP client, as `GET /api/apps/:id/users/:userId/mcp-grants` reports its `client_id`. Not a uuid — the identifier dynamic registration issued."
         }
       ],
       "query": null,
@@ -2995,7 +3013,7 @@
       "params": [
         {
           "name": "clientId",
-          "description": "The MCP client, as `GET /api/client/mcp/grants` reports its `client_id`. Not a uuid — it is the identifier the dynamic registration issued."
+          "description": "The MCP client, as `GET /api/client/mcp/grants` reports its `client_id`. Not a uuid — the identifier dynamic registration issued."
         }
       ],
       "query": null,
@@ -3300,6 +3318,59 @@
       "transport": "http",
       "notes": "For a client caller the grant check runs **before** any existence lookup, with no extra query on either path to time: a denied slug and a nonexistent one must be one answer. That is why an ungranted slug is `403 forbidden` while a granted-but-unconfigured one is `404 unknown_datapoint` and a configured one with no sample yet is `404 no_data` — three facts a caller who is entitled to them needs told apart. The plane built-ins (`bridge_state`, `robot_details`) answer here too, without appearing in any document."
     },
+    {
+      "method": "GET",
+      "path": "/api/client/robots",
+      "section": "robots",
+      "summary": "Lists the robots the caller reaches, with bridge state and the published configuration version.",
+      "audience": "client",
+      "auth": "developer_or_client",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "client-robot-list-response",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "forbidden"
+      ],
+      "transport": "http",
+      "notes": "**The REST twin of the MCP tool `robots_list`**, and the one robot question no robot-scoped route can answer: which robots may I name at all. An app user sees the robots their app attaches on which their role grants at least one slug or capability; a server key sees every robot its app attaches; a developer bearer sees the organisation's robots. Name order, id as the tiebreak. A robot on which the role grants nothing is absent rather than listed empty — the same answer `robots_list` gives, for the same reason: reach is a grant, not an attachment. Under `/api/client/` because it names no robot; every robot-scoped read stays under `/api/robots/:id/…`."
+    },
+    {
+      "method": "GET",
+      "path": "/api/robots/:id/datasheet",
+      "section": "robots",
+      "summary": "Describes everything the caller's role lets them do on one robot, with parameter schemas.",
+      "audience": "client",
+      "auth": "developer_or_client",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The robot's uuid, as `GET /api/client/robots` lists it."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": "mcp-robot-datasheet",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "forbidden",
+        "invalid_uuid",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "**The REST twin of the MCP tool `robot_describe`**: one answer per robot — every datapoint, action, service, publisher and camera the role grants, each with its `input_schema` where it takes parameters, plus the two capabilities that gate whole features, `action_history` and `assets`. A robot with nothing published answers an empty `exposures` list, never a refusal. A robot the caller does not reach — not attached to their app, or attached with a role that grants nothing on it — answers `404` exactly as one that does not exist. The app-user datapoint and camera listings under this prefix stay; this is the one read that also names actions, services, publishers and capabilities, which is what an app needs before it can draw a screen."
+    },
     {
       "method": "GET",
       "path": "/api/robots/:id/config/draft",
@@ -3807,7 +3878,7 @@
         },
         {
           "name": "slug",
-          "description": "The action or service slug from the published configuration; the cloud already knows which kind it is."
+          "description": "The action or service slug from the published configuration — the cloud already knows which kind."
         }
       ],
       "query": null,

package/artifacts/schema/app-list-response.schema.json

@@ -30,7 +30,7 @@
             "minLength": 2,
             "maxLength": 63,
             "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$",
-            "description": "The stable handle a client sends at login, lowercase and underscore-separated. **Globally unique, not per organisation** — `clientLoginRequest` carries no org context to disambiguate with, so a collision is refused with `identifier_taken`."
+            "description": "The stable handle a client sends at login, lowercase and underscore-separated. **Globally unique, not per organisation** — `clientLoginRequest` carries no org context, so a collision is refused with `identifier_taken`."
           },
           "robot_ids": {
             "type": "array",
@@ -52,7 +52,7 @@
                 "type": "null"
               }
             ],
-            "description": "The role an app user gets when they are created or invited without an explicit one. `null` means this app has not chosen a default, the normal state of an app created before its roles were configured — and then a create or invite that omits `role_id` is a `validation_error` rather than a user with no role. An invitation resolves the role when it is issued, so changing this never re-aims an outstanding one. The role must belong to this app, which `PATCH /api/apps/:id` checks and the schema cannot."
+            "description": "The role an app user gets when created or invited without an explicit one. `null` means this app has not chosen a default, the normal state of an app created before its roles were configured — and then a create or invite that omits `role_id` gets `validation_error`, not a user with no role. An invitation resolves the role when issued, so changing this never re-aims an outstanding one. The role must belong to this app, which `PATCH /api/apps/:id` checks and the schema cannot."
           },
           "created_at": {
             "type": "string",

package/artifacts/schema/app-oidc-provider-list-response.schema.json

@@ -60,7 +60,7 @@
           },
           "enabled": {
             "type": "boolean",
-            "description": "Whether this provider is offered at all. A disabled provider disappears from `GET /api/client/providers` and refuses a start with `provider_disabled`, without the row and its linked identities being deleted."
+            "description": "Whether this provider is offered. A disabled provider disappears from `GET /api/client/providers` and refuses a start with `provider_disabled`, without the row and its linked identities being deleted."
           },
           "created_at": {
             "type": "string",

package/artifacts/schema/app-oidc-provider.schema.json

@@ -55,7 +55,7 @@
     },
     "enabled": {
       "type": "boolean",
-      "description": "Whether this provider is offered at all. A disabled provider disappears from `GET /api/client/providers` and refuses a start with `provider_disabled`, without the row and its linked identities being deleted."
+      "description": "Whether this provider is offered. A disabled provider disappears from `GET /api/client/providers` and refuses a start with `provider_disabled`, without the row and its linked identities being deleted."
     },
     "created_at": {
       "type": "string",

package/artifacts/schema/app-user-list-response.schema.json

@@ -55,7 +55,7 @@
           },
           "has_password": {
             "type": "boolean",
-            "description": "Whether this account has a Fleetless-held password at all. `false` is an identity-provider-only account, or an invitation not yet accepted — it does not mean blocked and it does not mean without access. No hash, no algorithm and no \"last changed\" travels here, and nothing on the wire can say whether a password is strong or already known to somebody else."
+            "description": "Whether this account has a Fleetless-held password. `false` is an identity-provider-only account, or an invitation not yet accepted — it does not mean blocked and it does not mean without access. No hash, no algorithm and no \"last changed\" travels here, and nothing on the wire can say whether a password is strong or already known to somebody else."
           },
           "providers": {
             "maxItems": 20,
@@ -65,7 +65,7 @@
               "maxLength": 40,
               "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
             },
-            "description": "The slugs of the identity providers this account is linked to, empty for a password-only user. It is what lets a developer's user list say where an account came from without a second request."
+            "description": "The slugs of the identity providers this account is linked to, empty for a password-only user. Lets a developer's user list say where an account came from without a second request."
           },
           "last_login_at": {
             "anyOf": [

package/artifacts/schema/app-user.schema.json

@@ -50,7 +50,7 @@
     },
     "has_password": {
       "type": "boolean",
-      "description": "Whether this account has a Fleetless-held password at all. `false` is an identity-provider-only account, or an invitation not yet accepted — it does not mean blocked and it does not mean without access. No hash, no algorithm and no \"last changed\" travels here, and nothing on the wire can say whether a password is strong or already known to somebody else."
+      "description": "Whether this account has a Fleetless-held password. `false` is an identity-provider-only account, or an invitation not yet accepted — it does not mean blocked and it does not mean without access. No hash, no algorithm and no \"last changed\" travels here, and nothing on the wire can say whether a password is strong or already known to somebody else."
     },
     "providers": {
       "maxItems": 20,
@@ -60,7 +60,7 @@
         "maxLength": 40,
         "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
       },
-      "description": "The slugs of the identity providers this account is linked to, empty for a password-only user. It is what lets a developer's user list say where an account came from without a second request."
+      "description": "The slugs of the identity providers this account is linked to, empty for a password-only user. Lets a developer's user list say where an account came from without a second request."
     },
     "last_login_at": {
       "anyOf": [

package/artifacts/schema/app.schema.json

@@ -25,7 +25,7 @@
       "minLength": 2,
       "maxLength": 63,
       "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$",
-      "description": "The stable handle a client sends at login, lowercase and underscore-separated. **Globally unique, not per organisation** — `clientLoginRequest` carries no org context to disambiguate with, so a collision is refused with `identifier_taken`."
+      "description": "The stable handle a client sends at login, lowercase and underscore-separated. **Globally unique, not per organisation** — `clientLoginRequest` carries no org context, so a collision is refused with `identifier_taken`."
     },
     "robot_ids": {
       "type": "array",
@@ -47,7 +47,7 @@
           "type": "null"
         }
       ],
-      "description": "The role an app user gets when they are created or invited without an explicit one. `null` means this app has not chosen a default, the normal state of an app created before its roles were configured — and then a create or invite that omits `role_id` is a `validation_error` rather than a user with no role. An invitation resolves the role when it is issued, so changing this never re-aims an outstanding one. The role must belong to this app, which `PATCH /api/apps/:id` checks and the schema cannot."
+      "description": "The role an app user gets when created or invited without an explicit one. `null` means this app has not chosen a default, the normal state of an app created before its roles were configured — and then a create or invite that omits `role_id` gets `validation_error`, not a user with no role. An invitation resolves the role when issued, so changing this never re-aims an outstanding one. The role must belong to this app, which `PATCH /api/apps/:id` checks and the schema cannot."
     },
     "created_at": {
       "type": "string",

package/artifacts/schema/asset-list-response.schema.json

@@ -27,13 +27,13 @@
               "texture",
               "other"
             ],
-            "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 it has to pre-fetch."
+            "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."
           },
           "name": {
             "type": "string",
             "minLength": 1,
             "maxLength": 500,
-            "description": "What the robot called it — for a mesh, the `package://` URI the URDF references, verbatim, which is the only string a developer can match against their own workspace. A file the URDF never names (an image a `.dae` loads for itself) is named by joining the mesh's own directory with that internal reference."
+            "description": "What the robot called it — for a mesh, the `package://` URI the URDF references, verbatim, the only string a developer can match against their own workspace. A file the URDF never names (an image a `.dae` loads for itself) is named by joining the mesh's own directory with that internal reference."
           },
           "media_type": {
             "type": "string",
@@ -50,7 +50,7 @@
           "sha256": {
             "type": "string",
             "pattern": "^[a-f0-9]{64}$",
-            "description": "The content hash, lowercase hex, and the reason two robots sharing a mesh cost one copy. It is exposed because it is the only way a client can tell \"this is the same mesh I already have\" across robots."
+            "description": "The content hash, lowercase hex. Exposed because it is the only way a client can tell \"this is the same mesh I already have\" across robots — the reason two robots sharing a mesh cost one copy."
           },
           "created_at": {
             "type": "string",
@@ -149,7 +149,7 @@
                             "type": "integer",
                             "exclusiveMinimum": 0,
                             "maximum": 9007199254740991,
-                            "description": "How large the refused file actually 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": "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."
                           }
                         },
                         "required": [
@@ -238,7 +238,7 @@
                 "type": "string",
                 "minLength": 1,
                 "maxLength": 500,
-                "description": "The reference, verbatim, that no stored asset answers — a `package://` URI the workspace does not hold, or an absolute or bare relative path nothing will ever fetch. A developer whose URDF names one of the latter is entitled to be told so."
+                "description": "The reference, verbatim, that no stored asset answers — a `package://` URI the workspace does not hold, or an absolute or bare relative path nothing will ever fetch."
               },
               "element": {
                 "type": "string",
@@ -255,7 +255,7 @@
             ],
             "additionalProperties": false
           },
-          "description": "The references nothing in the store answers, each with the element that asked for it. A bare count is a dead end that sends a developer hunting through a workspace by hand; the references are what they can act on, so the references travel."
+          "description": "The references nothing in the store answers, each with the element that asked for it. A bare count would send a developer hunting through the workspace by hand; the references are what they can act on."
         }
       },
       "required": [
@@ -275,7 +275,7 @@
           "type": "null"
         }
       ],
-      "description": "What the connected bridge says it *could* transfer, which is deliberately separate from what has been transferred. `null` when no bridge is connected — distinct from `false`, because \"no robot is online to ask\" and \"the robot has no URDF\" send a developer to two 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."
+      "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."
     }
   },
   "required": [

package/artifacts/schema/asset-sync-request.schema.json

@@ -7,7 +7,7 @@
       "enum": [
         "bridge"
       ],
-      "description": "Where the bytes come from. `bridge` is the only value today: the connected bridge reads them from the robot's own workspace. It is validated rather than ignored, so a caller naming a source that does not exist yet learns that instead of silently getting a bridge sync."
+      "description": "Where the bytes come from. `bridge` is the only value today: the connected bridge reads them from the robot's own workspace. Validated rather than ignored, so a caller naming an unknown source is told so instead of silently getting a bridge sync."
     }
   },
   "required": [

package/artifacts/schema/asset-sync-status.schema.json

@@ -73,7 +73,7 @@
                     "type": "integer",
                     "exclusiveMinimum": 0,
                     "maximum": 9007199254740991,
-                    "description": "How large the refused file actually 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": "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."
                   }
                 },
                 "required": [

package/artifacts/schema/asset.schema.json

@@ -22,13 +22,13 @@
         "texture",
         "other"
       ],
-      "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 it has to pre-fetch."
+      "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."
     },
     "name": {
       "type": "string",
       "minLength": 1,
       "maxLength": 500,
-      "description": "What the robot called it — for a mesh, the `package://` URI the URDF references, verbatim, which is the only string a developer can match against their own workspace. A file the URDF never names (an image a `.dae` loads for itself) is named by joining the mesh's own directory with that internal reference."
+      "description": "What the robot called it — for a mesh, the `package://` URI the URDF references, verbatim, the only string a developer can match against their own workspace. A file the URDF never names (an image a `.dae` loads for itself) is named by joining the mesh's own directory with that internal reference."
     },
     "media_type": {
       "type": "string",
@@ -45,7 +45,7 @@
     "sha256": {
       "type": "string",
       "pattern": "^[a-f0-9]{64}$",
-      "description": "The content hash, lowercase hex, and the reason two robots sharing a mesh cost one copy. It is exposed because it is the only way a client can tell \"this is the same mesh I already have\" across robots."
+      "description": "The content hash, lowercase hex. Exposed because it is the only way a client can tell \"this is the same mesh I already have\" across robots — the reason two robots sharing a mesh cost one copy."
     },
     "created_at": {
       "type": "string",

package/artifacts/schema/auth-me-response.schema.json

@@ -44,7 +44,7 @@
           "type": "string",
           "format": "uuid",
           "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
-          "description": "The organisation this person belongs to. Every developer route is already scoped to the caller's org, so this confirms what a client is looking at rather than being a filter it applies."
+          "description": "The organisation this person belongs to. Every developer route is already scoped to the caller's org, so this confirms what a client is looking at, not a filter it applies."
         },
         "email": {
           "type": "string",
@@ -71,7 +71,7 @@
             "owner",
             "developer"
           ],
-          "description": "The console powers this person holds. **Required** — every Fleetless user is a member of the team and has a tier; the optional version of this field existed only while the org also held people with no console powers to grade, and that pool is gone."
+          "description": "The console powers this person holds. **Required** — every Fleetless user has a tier; it was optional only while the org also held people with no console powers to grade, and that pool is gone."
         },
         "created_at": {
           "type": "string",

package/artifacts/schema/auth-ok.schema.json

@@ -16,7 +16,7 @@
             "app_user",
             "server_key"
           ],
-          "description": "Which of the three kinds of caller this is: a `developer` working through the console, an `app_user` holding a token from a client login, or a `server_key` used by server-side code. Stated outright rather than left to be inferred from which id happens to be set."
+          "description": "Which of the three kinds of caller this is: a `developer` working through the console, an `app_user` holding a token from a client login, or a `server_key` used by server-side code. Stated outright, not inferred from which id is set."
         },
         "developer_id": {
           "anyOf": [

package/artifacts/schema/authorization-server-metadata.schema.json

@@ -10,7 +10,7 @@
     "authorization_endpoint": {
       "type": "string",
       "format": "uri",
-      "description": "The URL a client sends the user to in order to authorize."
+      "description": "Where a client sends the user to authorize."
     },
     "token_endpoint": {
       "type": "string",

package/artifacts/schema/bridge-asset-progress.schema.json

@@ -59,7 +59,7 @@
                     "type": "integer",
                     "exclusiveMinimum": 0,
                     "maximum": 9007199254740991,
-                    "description": "How large the refused file actually 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": "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."
                   }
                 },
                 "required": [

package/artifacts/schema/busy-details.schema.json

@@ -9,7 +9,7 @@
           "type": "string",
           "format": "uuid",
           "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
-          "description": "The job's id, minted by the cloud when the invocation is accepted. Informative: state is observed by slug, and this id is what a cancel names when a caller wants to stop one specific job rather than whatever is running."
+          "description": "The job's id, minted by the cloud when the invocation is accepted. Informative — state is observed by slug; a cancel names this id to stop one specific job rather than whatever is running."
         },
         "robot_id": {
           "type": "string",
@@ -33,13 +33,13 @@
             "cancelled",
             "lost"
           ],
-          "description": "Where the job stands: `running`, `succeeded`, `failed`, `cancelled` or `lost`. `lost` is a real outcome — the bridge restarted mid-job and the result is gone — and is said out loud rather than left reading `running` because nobody contradicted it."
+          "description": "Where the job stands: `running`, `succeeded`, `failed`, `cancelled` or `lost`. `lost` is a real outcome — the bridge restarted mid-job and the result is gone — stated rather than left reading `running` by default."
         },
         "started_at": {
           "type": "string",
           "format": "date-time",
           "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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
-          "description": "When the cloud minted this job, as an ISO 8601 timestamp. For a job adopted from a reconnecting bridge it is **adoption time**, not the real start, because the cloud never minted it and has no honest alternative."
+          "description": "When the cloud minted this job, as an ISO 8601 timestamp. For a job adopted from a reconnecting bridge, this is **adoption time**, not the real start — the cloud never minted it."
         },
         "updated_at": {
           "type": "string",

package/artifacts/schema/client-identity.schema.json

@@ -9,7 +9,7 @@
         "app_user",
         "server_key"
       ],
-      "description": "Which of the three kinds of caller this is: a `developer` working through the console, an `app_user` holding a token from a client login, or a `server_key` used by server-side code. Stated outright rather than left to be inferred from which id happens to be set."
+      "description": "Which of the three kinds of caller this is: a `developer` working through the console, an `app_user` holding a token from a client login, or a `server_key` used by server-side code. Stated outright, not inferred from which id is set."
     },
     "developer_id": {
       "anyOf": [

package/artifacts/schema/client-login-request.schema.json

@@ -7,7 +7,7 @@
       "minLength": 2,
       "maxLength": 63,
       "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$",
-      "description": "The app being logged in to, as its globally unique identifier — the lowercase, underscore-separated string the developer chose when the app was created. There is no organisation context at login, so this is what decides which app the credentials are checked for."
+      "description": "The app being logged in to: its globally unique, lowercase, underscore-separated identifier, chosen by the developer at creation. There is no organisation context at login, so this is what decides which app the credentials are checked for."
     },
     "email": {
       "type": "string",

package/artifacts/schema/client-logout-request.schema.json

@@ -5,7 +5,7 @@
     "refresh_token": {
       "type": "string",
       "minLength": 1,
-      "description": "Any refresh token of the session to end. The whole token family is revoked server-side, so a token stolen before this call stops working too — clearing a client-side store is a gesture, not a revocation. The answer is `204`: a token the server does not recognise gets it too, since the end state a caller asked for is the end state they get."
+      "description": "Any refresh token of the session to end. The whole token family is revoked server-side, so a token stolen before this call stops working too — clearing a client-side store is a gesture, not a revocation. The answer is `204`: a token the server does not recognise gets it too, since that is the end state being asked for."
     }
   },
   "required": [

package/artifacts/schema/client-mcp-interaction.schema.json

@@ -26,7 +26,7 @@
     "client_name_verified": {
       "type": "boolean",
       "const": false,
-      "description": "Always `false`. The client registered itself without authentication and chose this name about itself, so it must be rendered as a claim and never as an identity. There is no verified case, which is why this is a literal and not a boolean: a `true` branch would be dead code that looked like a safeguard."
+      "description": "Always `false`. The client registered itself without authentication and named itself, so it must be rendered as a claim and never as an identity. There is no verified case, which is why this is a literal and not a boolean: a `true` branch would be dead code that looked like a safeguard."
     },
     "scopes": {
       "type": "array",

package/artifacts/schema/client-robot-list-item.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "format": "uuid",
+      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+      "description": "The robot, and what every robot-scoped route takes as its `:id`."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 63,
+      "description": "The robot's display name, at most 63 characters. Free text, changed through `PATCH /api/robots/:id`."
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
+      "description": "When the robot was created, as an ISO 8601 timestamp."
+    },
+    "bridge_state": {
+      "type": "object",
+      "properties": {
+        "online": {
+          "type": "boolean"
+        },
+        "latency_ms": {
+          "anyOf": [
+            {
+              "type": "number",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "online",
+        "latency_ms"
+      ],
+      "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."
+    },
+    "published_version": {
+      "anyOf": [
+        {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The published configuration version, or `null` when nothing has been published yet. A robot with nothing published is still listed — \"not configured yet\" is a real state, and the caller is entitled to it — and its datasheet answers an empty exposure list."
+    }
+  },
+  "required": [
+    "id",
+    "name",
+    "created_at",
+    "bridge_state",
+    "published_version"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/client-robot-list-response.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "robots": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+            "description": "The robot, and what every robot-scoped route takes as its `:id`."
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 63,
+            "description": "The robot's display name, at most 63 characters. Free text, changed through `PATCH /api/robots/:id`."
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
+            "description": "When the robot was created, as an ISO 8601 timestamp."
+          },
+          "bridge_state": {
+            "type": "object",
+            "properties": {
+              "online": {
+                "type": "boolean"
+              },
+              "latency_ms": {
+                "anyOf": [
+                  {
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              }
+            },
+            "required": [
+              "online",
+              "latency_ms"
+            ],
+            "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."
+          },
+          "published_version": {
+            "anyOf": [
+              {
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The published configuration version, or `null` when nothing has been published yet. A robot with nothing published is still listed — \"not configured yet\" is a real state, and the caller is entitled to it — and its datasheet answers an empty exposure list."
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "created_at",
+          "bridge_state",
+          "published_version"
+        ],
+        "additionalProperties": false
+      },
+      "description": "Every robot the caller reaches, in name order with the id as the tiebreak. An app user reaches the robots their app attaches on which their role grants at least one slug or capability; a server key reaches every robot its app attaches; a developer reaches every robot of the organisation."
+    }
+  },
+  "required": [
+    "robots"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/cloud-config.schema.json

@@ -118,7 +118,7 @@
                 ]
               },
               "description": {
-                "description": "Prose about what this value is, for whoever meets it in the console later. 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.",
+                "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": [
                   "What this value is, for whoever meets it in the console."
                 ],