@fleetless/contracts 1.0.6 → 1.2.0

package/dist/oauth.d.ts

@@ -168,26 +168,20 @@ export declare const dynamicClientRegistrationResponse: z.ZodObject<{
 }, z.core.$strip>;
 export type DynamicClientRegistrationResponse = z.infer<typeof dynamicClientRegistrationResponse>;
 /**
- * **The MCP token endpoint's request — one grant, because the servers serve
- * one.**
+ * **The MCP token endpoint's request — two grants, one per half of a
+ * session.**
  *
- * Both authorization servers, central and per-app, exchange through one
- * implementation, whose first act is to refuse anything but
- * `authorization_code` before a single lookup happens. There is no refresh grant here: a session ends when its token
- * expires and the client signs in again.
+ * `authorization_code` mints the first access token and a refresh token;
+ * `refresh_token` rotates that refresh token into a new pair. Both MCP
+ * authorization servers, central and per-app, answer both; the console's own
+ * OAuth portal answers the code grant only.
  *
- * **This was a `discriminatedUnion` with a `refresh_token` branch, and that
- * branch had no producer left.** It described the app-level OAuth surface,
- * which is deleted; an app user's refresh runs through `POST
- * /api/client/refresh` and `refreshRequest`, a different wire on a different
- * route. Keeping it would have published, to every MCP client author reading
- * `/openapi.json`, a grant the endpoint answers `unsupported_grant_type` to.
- * The argument the branch carried is worth keeping even though the branch is
- * not: **RFC 8707's `resource` has to survive rotation**, because a refresh
- * that drops the audience mints a successor with no `aud`, and the validating
- * resource then refuses a token the caller obtained legitimately — one token
- * lifetime after a login that worked, to somebody who did nothing wrong. If a
- * refresh grant is ever added here, it carries `resource`.
+ * **RFC 8707's `resource` has to survive rotation**: a refresh that drops the
+ * audience mints a successor with no `aud`, and the validating resource then
+ * refuses a token the caller obtained legitimately. So the server keeps the
+ * audience on the refresh token's own row, and a `resource` named here must
+ * match it or the answer is `invalid_target` — before the token is consumed,
+ * so a typo costs nothing.
  *
  * `code_verifier`'s bounds are RFC 7636 §4.1's, charset included. A verifier
  * is compared, not parsed, so a length nobody checks is a length an attacker
@@ -201,7 +195,7 @@ export type DynamicClientRegistrationResponse = z.infer<typeof dynamicClientRegi
  * **stripped**, which bit the test for this schema: `safeParse().success`
  * cannot tell a present field from an absent one. Assert on the parsed value.
  */
-export declare const oauthTokenRequest: z.ZodObject<{
+export declare const oauthCodeTokenRequest: z.ZodObject<{
     grant_type: z.ZodLiteral<"authorization_code">;
     code: z.ZodString;
     redirect_uri: z.ZodString;
@@ -209,6 +203,27 @@ export declare const oauthTokenRequest: z.ZodObject<{
     code_verifier: z.ZodString;
     resource: z.ZodOptional<z.ZodURL>;
 }, z.core.$strip>;
+export type OauthCodeTokenRequest = z.infer<typeof oauthCodeTokenRequest>;
+export declare const oauthRefreshTokenRequest: z.ZodObject<{
+    grant_type: z.ZodLiteral<"refresh_token">;
+    refresh_token: z.ZodString;
+    client_id: z.ZodString;
+    resource: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>;
+export type OauthRefreshTokenRequest = z.infer<typeof oauthRefreshTokenRequest>;
+export declare const oauthTokenRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    grant_type: z.ZodLiteral<"authorization_code">;
+    code: z.ZodString;
+    redirect_uri: z.ZodString;
+    client_id: z.ZodString;
+    code_verifier: z.ZodString;
+    resource: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>, z.ZodObject<{
+    grant_type: z.ZodLiteral<"refresh_token">;
+    refresh_token: z.ZodString;
+    client_id: z.ZodString;
+    resource: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>], "grant_type">;
 export type OauthTokenRequest = z.infer<typeof oauthTokenRequest>;
 /**
  * RFC 6749 §5.1's success envelope — **the second deliberate dialect, and this

package/dist/oauth.js

@@ -188,7 +188,7 @@ export const dynamicClientRegistrationRequest = z
         description: '`none`, RFC 7591\'s value for a public client, and the only value either server registers. Any other value is **refused rather than silently downgraded**: a client that believes it holds a secret and does not has a wrong mental model of its own security. There is no client secret to hold — mandatory PKCE (`S256`) is the defence.',
     }),
     grant_types: z.array(z.enum(['authorization_code', 'refresh_token'])).optional().meta({
-        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.',
     }),
     response_types: z.array(z.enum(['code'])).optional().meta({
         description: 'Accepted for conformance and then **ignored**; the response names `code`, which is the only response type OAuth 2.1 leaves, the implicit grant having been removed.',
@@ -211,7 +211,7 @@ export const dynamicClientRegistrationResponse = z.object({
         description: 'The redirect URIs this registration was accepted for. A code is returned to one of these and nowhere else.',
     }),
     grant_types: z.array(z.string()).meta({
-        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: z.array(z.string()).meta({
         description: 'The response types this client may ask for: `code`.',
@@ -227,26 +227,20 @@ export const dynamicClientRegistrationResponse = z.object({
     }),
 });
 /**
- * **The MCP token endpoint's request — one grant, because the servers serve
- * one.**
+ * **The MCP token endpoint's request — two grants, one per half of a
+ * session.**
  *
- * Both authorization servers, central and per-app, exchange through one
- * implementation, whose first act is to refuse anything but
- * `authorization_code` before a single lookup happens. There is no refresh grant here: a session ends when its token
- * expires and the client signs in again.
+ * `authorization_code` mints the first access token and a refresh token;
+ * `refresh_token` rotates that refresh token into a new pair. Both MCP
+ * authorization servers, central and per-app, answer both; the console's own
+ * OAuth portal answers the code grant only.
  *
- * **This was a `discriminatedUnion` with a `refresh_token` branch, and that
- * branch had no producer left.** It described the app-level OAuth surface,
- * which is deleted; an app user's refresh runs through `POST
- * /api/client/refresh` and `refreshRequest`, a different wire on a different
- * route. Keeping it would have published, to every MCP client author reading
- * `/openapi.json`, a grant the endpoint answers `unsupported_grant_type` to.
- * The argument the branch carried is worth keeping even though the branch is
- * not: **RFC 8707's `resource` has to survive rotation**, because a refresh
- * that drops the audience mints a successor with no `aud`, and the validating
- * resource then refuses a token the caller obtained legitimately — one token
- * lifetime after a login that worked, to somebody who did nothing wrong. If a
- * refresh grant is ever added here, it carries `resource`.
+ * **RFC 8707's `resource` has to survive rotation**: a refresh that drops the
+ * audience mints a successor with no `aud`, and the validating resource then
+ * refuses a token the caller obtained legitimately. So the server keeps the
+ * audience on the refresh token's own row, and a `resource` named here must
+ * match it or the answer is `invalid_target` — before the token is consumed,
+ * so a typo costs nothing.
  *
  * `code_verifier`'s bounds are RFC 7636 §4.1's, charset included. A verifier
  * is compared, not parsed, so a length nobody checks is a length an attacker
@@ -260,10 +254,10 @@ export const dynamicClientRegistrationResponse = z.object({
  * **stripped**, which bit the test for this schema: `safeParse().success`
  * cannot tell a present field from an absent one. Assert on the parsed value.
  */
-export const oauthTokenRequest = z
+export const oauthCodeTokenRequest = z
     .object({
     grant_type: z.literal('authorization_code').meta({
-        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.',
+        description: '`authorization_code`: this request exchanges the code from the authorize redirect for an access token and a refresh token.',
     }),
     code: z.string().min(1).max(500).meta({
         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.',
@@ -284,6 +278,27 @@ export const oauthTokenRequest = z
     .meta({
     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.",
 });
+export const oauthRefreshTokenRequest = z
+    .object({
+    grant_type: z.literal('refresh_token').meta({
+        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: z.string().min(1).max(500).meta({
+        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: z.string().min(1).max(200).meta({
+        description: 'The client the refresh token was issued to, as registered. A refresh token is not transferable between clients.',
+    }),
+    resource: z.url().optional().meta({
+        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.',
+    }),
+})
+    .meta({
+    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.",
+});
+export const oauthTokenRequest = z.discriminatedUnion('grant_type', [oauthCodeTokenRequest, oauthRefreshTokenRequest]).meta({
+    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.',
+});
 /**
  * RFC 6749 §5.1's success envelope — **the second deliberate dialect, and this
  * one is a success shape rather than an error shape.**
@@ -311,7 +326,7 @@ export const oauthTokenResponse = z.object({
         description: 'How long the access token is valid, in **seconds**, per RFC 6749 §5.1. Not a timestamp, and not milliseconds.',
     }),
     refresh_token: z.string().min(1).optional().meta({
-        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.',
     }),
     scope: z.string().max(500).optional().meta({
         description: 'The scopes the issued token actually carries, space-separated.',
@@ -335,7 +350,7 @@ export const authorizationServerMetadata = z.object({
         description: 'The response types this server offers: `code` only, the implicit grant being gone with OAuth 2.1.',
     }),
     grant_types_supported: z.array(z.enum(['authorization_code', 'refresh_token'])).meta({
-        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: z.array(codeChallengeMethod).meta({
         description: 'The PKCE challenge methods accepted: `S256` only. `plain` is not offered — a challenge equal to its verifier defends against nothing, and offering it would make a downgrade negotiable.',

package/dist/realtime.d.ts

@@ -254,8 +254,8 @@ export type DatapointEvent = z.infer<typeof datapointEvent>;
  */
 export declare const liveSessionEndReason: z.ZodEnum<{
     unknown: "unknown";
-    robot_offline: "robot_offline";
     publish_failed: "publish_failed";
+    robot_offline: "robot_offline";
     released_by_peer: "released_by_peer";
     config_changed: "config_changed";
     revoked: "revoked";
@@ -285,8 +285,8 @@ export declare const liveSessionEvent: z.ZodObject<{
     state: z.ZodLiteral<"ended">;
     reason: z.ZodEnum<{
         unknown: "unknown";
-        robot_offline: "robot_offline";
         publish_failed: "publish_failed";
+        robot_offline: "robot_offline";
         released_by_peer: "released_by_peer";
         config_changed: "config_changed";
         revoked: "revoked";

package/dist/routes.js

@@ -4,10 +4,11 @@ import { alertListResponse, orgAlertsQuery, orgFiringAlertsResponse } from './al
 import { asset, assetListResponse, assetSyncRequest, assetSyncResponse, assetSyncStatus, missingAssetQuery } from './assets.js';
 import { auditListResponse, auditQuery } from './audit.js';
 import { CLIENT_OIDC_CALLBACK_PATH, clientAcceptInvitationRequest, clientIdentity, clientLoginRequest, clientLogoutRequest, clientMcpInteraction, clientMcpInteractionDecisionResponse, clientOidcCallbackQuery, clientOidcExchangeRequest, clientOidcStartQuery, clientPasswordResetConfirmRequest, clientPasswordResetRequest, clientProviderListQuery, clientProviderListResponse, clientRefreshRequest, clientRegisterRequest, clientResendVerificationRequest, clientVerifyEmailRequest, mcpConsentGrantListResponse, } from './client-auth.js';
+import { clientRobotListResponse } from './client-robots.js';
 import { appAuthConfig, appInvitation, appInvitationListResponse, appMailTemplate, appMailTemplateListResponse, appOidcProvider, appOidcProviderListResponse, appUser, appUserListResponse, createAppInvitationRequest, createAppOidcProviderRequest, createAppUserRequest, mailOutcome, mailTemplatePreviewRequest, mailTemplatePreviewResponse, patchAppOidcProviderRequest, patchAppUserRequest, putAppAuthConfigRequest, putAppMailTemplateRequest, } from './app-users.js';
 import { acceptTeamInviteRequest, authMeResponse, createTeamInviteRequest, fleetlessUser, fleetlessUserListResponse, passwordChangeRequest, passwordResetConfirm, passwordResetRequest, patchAuthMeRequest, patchFleetlessUserRequest, patchOrgRequest, patchOrgResponse, pendingTeamInviteListResponse, refreshRequest, sessionTokens, signUpRequest, signUpResponse, teamInvite, tierChangeRequest, waitlistRequest, } from './identity.js';
 import { jobRunListResponse, jobRunQuery, jobRunSummary, jobRunSummaryQuery } from './jobs.js';
-import { MCP_APP_PATHS, mcpRolePreviewResponse } from './mcp.js';
+import { MCP_APP_PATHS, mcpRobotDatasheet, mcpRolePreviewResponse } from './mcp.js';
 import { authorizationServerMetadata, dynamicClientRegistrationRequest, dynamicClientRegistrationResponse, oauthAuthorizeQuery, oauthRedirectResponse, oauthTokenRequest, oauthTokenResponse, protectedResourceMetadata, } from './oauth.js';
 import { cameraListResponse, cancelRequest, configDraftResponse, configVersionResponse, configVersionsResponse, createRobotRequest, createRobotResponse, datapointListResponse, datapointValue, exposureListResponse, fetchTypesRequest, fetchTypesResponse, historyQuery, historyResponse, introspectionResponse, invokeOrServiceResponse, invokeRequest, jobResponse, liveSessionResponse, orgHealthQuery, orgLatencyQuery, orgLatencyResponse, orgQuotaUsage, orgUsageQuery, orgUsageResponse, patchRobotRequest, patchRobotResponse, publishConfigResponse, publishRequest, putConfigDraftRequest, putRobotDetailsRequest, putRobotDetailsResponse, releaseLiveQuery, renameSlugRequest, renameSlugResponse, robotDeleteQuery, resourceHealthListResponse, robotDeletionSummary, robotDetailResponse, robotJobsResponse, robotListResponse, slugUsageResponse, snapshotMetaResponse, typesResponse, } from './rest.js';
 export const ROUTE_SECTIONS = [
@@ -208,6 +209,14 @@ export const ROUTES = [
             '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', section: 'developer-auth',
         summary: 'Spends a reset token, sets the new password and ends every session of the account.',
@@ -939,8 +948,8 @@ export const ROUTES = [
             '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 ' +
+            '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`.',
     },
     {
@@ -1014,10 +1023,11 @@ export const ROUTES = [
         audience: 'client', auth: 'none', rateLimited: false, ownerTier: false, status: 200,
         params: [], query: null, request: oauthTokenRequest, response: oauthTokenResponse,
         errors: [], transport: 'http',
-        notes: '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.',
+        notes: '`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.',
     },
     /* ------------------------------- developer auth (the console\'s OAuth portal) */
     {
@@ -1239,8 +1249,8 @@ export const ROUTES = [
             '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 ' +
+            '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 ' +
@@ -1279,9 +1289,8 @@ export const ROUTES = [
         audience: 'client', auth: 'none', rateLimited: false, ownerTier: false, status: 200,
         params: [APP_IDENTIFIER], query: null, request: oauthTokenRequest, response: oauthTokenResponse,
         errors: [], transport: 'http',
-        notes: '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 ' +
+        notes: '`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 ' +
@@ -1750,6 +1759,33 @@ export const ROUTES = [
             '`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.',
     },
+    /* ------------------------------------------ discovery: the REST twins of the two MCP tools a session starts from */
+    {
+        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: clientRobotListResponse,
+        errors: [...CLIENT_GUARD], 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: mcpRobotDatasheet,
+        errors: [...CLIENT_GUARD, '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.',
+    },
     /* ------------------------------------------------- config (draft/publish) */
     {
         method: 'GET', path: '/api/robots/:id/config/draft', section: 'config',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fleetless/contracts",
-  "version": "1.0.6",
+  "version": "1.2.0",
   "description": "Fleetless wire contracts: the bridge-cloud protocol, the REST API schemas and the error codes, as zod schemas with generated JSON Schema and OpenAPI artifacts.",
   "license": "Apache-2.0",
   "author": "Dehne Robotik GmbH",