@fleetless/contracts 1.0.5 → 1.1.0

package/dist/client-robots.d.ts

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+/**
+ * One robot as `GET /api/client/robots` lists it — 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.
+ *
+ * Deliberately not `robotListItem`: that one carries `exposes`, the per-kind
+ * counts a developer's list shows, which are a configuration fact rather than
+ * something an app user's role grants. What an app user is entitled to is the
+ * robot, its bridge state, and whether anything is published on it yet.
+ */
+export declare const clientRobotListItem: z.ZodObject<{
+    bridge_state: z.ZodObject<{
+        online: z.ZodBoolean;
+        latency_ms: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    published_version: z.ZodNullable<z.ZodNumber>;
+    id: z.ZodUUID;
+    name: z.ZodString;
+    created_at: z.ZodISODateTime;
+}, z.core.$strip>;
+export type ClientRobotListItem = z.infer<typeof clientRobotListItem>;
+/** What `GET /api/client/robots` answers. Never null: a caller who reaches nothing gets an empty array, and an absent key would make "nothing" and "not answered" the same reading. */
+export declare const clientRobotListResponse: z.ZodObject<{
+    robots: z.ZodArray<z.ZodObject<{
+        bridge_state: z.ZodObject<{
+            online: z.ZodBoolean;
+            latency_ms: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>;
+        published_version: z.ZodNullable<z.ZodNumber>;
+        id: z.ZodUUID;
+        name: z.ZodString;
+        created_at: z.ZodISODateTime;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ClientRobotListResponse = z.infer<typeof clientRobotListResponse>;

package/dist/client-robots.js

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+import { bridgeState } from './protocol.js';
+import { robot } from './rest.js';
+/* ------------------------------------------ the robots an app user reaches */
+/**
+ * One robot as `GET /api/client/robots` lists it — 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.
+ *
+ * Deliberately not `robotListItem`: that one carries `exposes`, the per-kind
+ * counts a developer's list shows, which are a configuration fact rather than
+ * something an app user's role grants. What an app user is entitled to is the
+ * robot, its bridge state, and whether anything is published on it yet.
+ */
+export const clientRobotListItem = z.object({
+    ...robot.shape,
+    bridge_state: bridgeState.meta({
+        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: z.number().int().positive().nullable().meta({
+        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.',
+    }),
+});
+/** What `GET /api/client/robots` answers. Never null: a caller who reaches nothing gets an empty array, and an absent key would make "nothing" and "not answered" the same reading. */
+export const clientRobotListResponse = z.object({
+    robots: z.array(clientRobotListItem).meta({
+        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.',
+    }),
+});

package/dist/config-issues.d.ts

@@ -92,9 +92,9 @@ export declare function schemaIssues(value: unknown, issues: readonly SchemaIssu
  * `configDraftResponse`, not one issue: a client's `safeParse` drops the
  * response and hands the editor nothing, for two characters typed.
  *
- * The quoted spelling is the segment's JSON string literal, and that is the
- * whole of the reason for choosing it: JSON's string syntax is a subset of
- * YAML's double-quoted scalar syntax, so `""`, `" "` and `"\t"` are each a
+ * The quoted spelling is the segment's JSON string literal — the whole reason
+ * for choosing it: JSON's string syntax is a subset of YAML's double-quoted
+ * scalar syntax, so `""`, `" "` and `"\t"` are each a
  * valid YAML spelling of exactly the key being complained about. The path is
  * therefore text the developer can search their own file for — which is the
  * bar this has to clear. It is also the same move `DOCUMENT_ROOT_PATH` makes

package/dist/config-issues.js

@@ -111,9 +111,9 @@ function slugOf(path) {
  * `configDraftResponse`, not one issue: a client's `safeParse` drops the
  * response and hands the editor nothing, for two characters typed.
  *
- * The quoted spelling is the segment's JSON string literal, and that is the
- * whole of the reason for choosing it: JSON's string syntax is a subset of
- * YAML's double-quoted scalar syntax, so `""`, `" "` and `"\t"` are each a
+ * The quoted spelling is the segment's JSON string literal — the whole reason
+ * for choosing it: JSON's string syntax is a subset of YAML's double-quoted
+ * scalar syntax, so `""`, `" "` and `"\t"` are each a
  * valid YAML spelling of exactly the key being complained about. The path is
  * therefore text the developer can search their own file for — which is the
  * bar this has to clear. It is also the same move `DOCUMENT_ROOT_PATH` makes

package/dist/config.d.ts

@@ -20,8 +20,8 @@ import { z } from 'zod';
  * field as **required** in the generated JSON Schema, because after parsing
  * it is always present. That is recorded in `scripts/export-schemas.ts`, whose
  * remedy (`io: 'input'`, applied per schema) is a judgement call across dozens
- * of schemas and every consumer that vendors them. So this field simply does
- * not add another instance: optional is optional in both modes, and *absent* is
+ * of schemas and every consumer that vendors them. So this field does not add
+ * another instance: optional is optional in both modes, and *absent* is
  * the single spelling of "not described". `.min(1)` keeps the empty string from
  * becoming a second.
  */
@@ -144,10 +144,9 @@ export declare const parameterMap: z.ZodRecord<z.ZodString, z.ZodObject<{
  *
  * **This constant is the only list.** The cloud builds its set from it and
  * emits `reserved_slug`; the rename path reads it for the target; an editor
- * reads it for slug suggestion and repairs. Nothing copies the members. Note
- * that it is NOT the enumeration of built-in datapoints — those are kept
- * separately, and must be, because a reserved name exists that nothing
- * publishes.
+ * reads it for slug suggestion and repairs. Nothing copies the members. It is
+ * NOT the enumeration of built-in datapoints — those are kept separately,
+ * and must be, because a reserved name exists that nothing publishes.
  *
  * **What it does not do: `robotConfigDoc` does not enforce it.** Reservation is
  * a semantic check that belongs with the ones that need the robot's context,

package/dist/config.js

@@ -379,8 +379,8 @@ const underSlug = (slugKey, snippet) => ({ ...snippet, body: { [slugKey]: snippe
  * field as **required** in the generated JSON Schema, because after parsing
  * it is always present. That is recorded in `scripts/export-schemas.ts`, whose
  * remedy (`io: 'input'`, applied per schema) is a judgement call across dozens
- * of schemas and every consumer that vendors them. So this field simply does
- * not add another instance: optional is optional in both modes, and *absent* is
+ * of schemas and every consumer that vendors them. So this field does not add
+ * another instance: optional is optional in both modes, and *absent* is
  * the single spelling of "not described". `.min(1)` keeps the empty string from
  * becoming a second.
  */
@@ -582,7 +582,7 @@ export const parameterSpec = strictObject({
      * Without this, a default is the one way past bounds that are otherwise
      * the enforcement point. `min_value`/`max_value` are the speed limit that
      * actually holds, enforced in the cloud before anything reaches the robot.
-     * But a caller who simply omits the parameter gets the
+     * But a caller who omits the parameter gets the
      * default, and the bridge fills it at the template walk without
      * re-checking bounds, deliberately: a second enforcement point there
      * would be the weaker of two policies. So `{min_value: -1, max_value: 1,
@@ -658,10 +658,9 @@ export const parameterMap = slugKeyed(parameterSpec)
  *
  * **This constant is the only list.** The cloud builds its set from it and
  * emits `reserved_slug`; the rename path reads it for the target; an editor
- * reads it for slug suggestion and repairs. Nothing copies the members. Note
- * that it is NOT the enumeration of built-in datapoints — those are kept
- * separately, and must be, because a reserved name exists that nothing
- * publishes.
+ * reads it for slug suggestion and repairs. Nothing copies the members. It is
+ * NOT the enumeration of built-in datapoints — those are kept separately,
+ * and must be, because a reserved name exists that nothing publishes.
  *
  * **What it does not do: `robotConfigDoc` does not enforce it.** Reservation is
  * a semantic check that belongs with the ones that need the robot's context,
@@ -993,7 +992,7 @@ export const datapointConfig = strictObject({
         examples: [2, 0.5],
     }).optional(),
     description: serviceDescription.meta({
-        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.',
         /**
          * The sentence both datapoint snippets already place here, verbatim. Its
          * four siblings — an action's, a service's, a publisher's, a camera's —

package/dist/errors.d.ts

@@ -19,10 +19,10 @@ export type ApiError = z.infer<typeof apiError>;
  * console renders a third, and each is right in its own tests.
  *
  * `field` is the **flat key exactly as the caller sent it** — the same string
- * as the `parameterSpec.name` it violated. That is the entire justification
- * for the flat parameter form: a refusal has to name something the caller can
- * find in what they typed, and a console can attach the error to that one
- * input rather than to the form.
+ * as the `parameterSpec.name` it violated. That is why the parameter form
+ * stays flat: a refusal has to name something the caller can find in what
+ * they typed, and a console can attach the error to that one input rather
+ * than to the form.
  */
 export declare const parameterViolation: z.ZodObject<{
     field: z.ZodString;

package/dist/errors.js

@@ -18,10 +18,10 @@ export const apiError = z.object({
  * console renders a third, and each is right in its own tests.
  *
  * `field` is the **flat key exactly as the caller sent it** — the same string
- * as the `parameterSpec.name` it violated. That is the entire justification
- * for the flat parameter form: a refusal has to name something the caller can
- * find in what they typed, and a console can attach the error to that one
- * input rather than to the form.
+ * as the `parameterSpec.name` it violated. That is why the parameter form
+ * stays flat: a refusal has to name something the caller can find in what
+ * they typed, and a console can attach the error to that one input rather
+ * than to the form.
  */
 export const parameterViolation = z.object({
     field: z.string().min(1),
@@ -81,11 +81,10 @@ export const ERROR_CODES = [
     'invalid_credentials',
     'token_expired',
     'token_revoked',
-    /* `invite_expired` and `invite_used` were removed on 2026-09-05, by the same
-     * reasoning that removed `not_a_member` and with the same evidence: a `grep`
-     * across contracts, cloud, sdk, console and bridge found their own entries
-     * here and one test asserting those entries existed. Nothing has ever emitted
-     * either.
+    /* `invite_expired` and `invite_used` were removed on 2026-09-05 — same
+     * reasoning and evidence as `not_a_member`: a `grep` across contracts, cloud,
+     * sdk, console and bridge found only their own entries here and one test
+     * asserting those entries existed. Nothing has ever emitted either.
      *
      * They were written for `POST /api/client/invitations/accept`, to tell an
      * expired invitation from an already-accepted one. That route answers `410

package/dist/identity.d.ts

@@ -19,11 +19,10 @@ import { z } from 'zod';
  *
  * **What that deleted, with no successor**: groups and the Org Admins
  * group, app assignments, impersonation, the per-user MCP override and the
- * org-level federation policy. The 2026-08-29 model had put developers and end
- * users into one pool per org and connected them with all of the above; in use
- * it turned out to model the wrong thing — the two populations have different
- * lifecycles, and every mechanism joining them was cost without a product
- * reason.
+ * org-level federation policy. The 2026-08-29 model pooled developers and end
+ * users per org and joined them with all of the above. In use, wrong model:
+ * the two populations have different lifecycles, and every joining mechanism
+ * was cost without a product reason.
  *
  * What did **not** change: the password rules, the session and token shapes,
  * and the enumeration-oracle reasoning on password reset. None of those was

package/dist/identity.js

@@ -19,11 +19,10 @@ import { z } from 'zod';
  *
  * **What that deleted, with no successor**: groups and the Org Admins
  * group, app assignments, impersonation, the per-user MCP override and the
- * org-level federation policy. The 2026-08-29 model had put developers and end
- * users into one pool per org and connected them with all of the above; in use
- * it turned out to model the wrong thing — the two populations have different
- * lifecycles, and every mechanism joining them was cost without a product
- * reason.
+ * org-level federation policy. The 2026-08-29 model pooled developers and end
+ * users per org and joined them with all of the above. In use, wrong model:
+ * the two populations have different lifecycles, and every joining mechanism
+ * was cost without a product reason.
  *
  * What did **not** change: the password rules, the session and token shapes,
  * and the enumeration-oracle reasoning on password reset. None of those was
@@ -78,7 +77,7 @@ export const org = z.object({
 /** What `PATCH /api/org` answers: the org as it now stands. */
 export const patchOrgResponse = z.object({
     org: org.meta({
-        description: 'The organisation as it now stands, after the patch was applied. The whole resource comes back, not only the fields that changed.',
+        description: 'The organisation as it now stands, after the patch. The whole resource comes back, not only the changed fields.',
     }),
 });
 /**
@@ -104,7 +103,7 @@ export const fleetlessUser = z.object({
         description: 'The Fleetless user in the API, assigned by the cloud and stable for the life of the account.',
     }),
     org_id: z.uuid().meta({
-        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: z.email().meta({
         description: 'The address the account is identified by, **globally unique** across every organisation. Immutable after creation: it is what every invitation, reset link and audit line names.',
@@ -113,7 +112,7 @@ export const fleetlessUser = z.object({
         description: 'Optional human name, shown by the console instead of the address where present. Self-service through `PATCH /api/auth/me`; never used for authentication. `null` when the person never supplied one.',
     }),
     tier: orgAdminTier.meta({
-        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: z.iso.datetime().meta({
         description: 'When the account was created, as an ISO 8601 timestamp.',

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export type { ParameterType, ParameterSpec, ActionConfig, ServiceConfig, Publish
 /**
  * The one account of what is wrong with a configuration document, shared by
  * every layer that reports on one. See `config-issues.ts`'s header for why a
- * second copy of this vocabulary is a defect rather than a convenience.
+ * second copy of this vocabulary is a defect, not a convenience.
  */
 export { DOCUMENT_ROOT_PATH, EXPOSURE_SECTIONS, schemaIssues, formatPath, splitFormatPath, configSchemaHash, } from './config-issues.js';
 export type { SchemaIssue, ExposureSection } from './config-issues.js';
@@ -35,6 +35,8 @@ export { appIdentifier, app, appListResponse, createAppRequest, updateAppRequest
 export type { App, AppListResponse, CreateAppRequest, UpdateAppRequest, ServerKey, ServerKeyListResponse, CreateServerKeyResponse, Role, RoleListResponse, RolePermissions, } from './apps.js';
 export { clientLoginRequest, clientRefreshRequest, clientLogoutRequest, clientRegisterRequest, clientVerifyEmailRequest, clientResendVerificationRequest, clientPasswordResetRequest, clientPasswordResetConfirmRequest, clientAcceptInvitationRequest, CLIENT_OIDC_CALLBACK_PATH, clientProviderListQuery, clientProviderListResponse, clientOidcStartQuery, clientOidcCallbackQuery, clientOidcExchangeRequest, clientOidcErrorCode, clientMcpInteraction, clientMcpInteractionDecisionResponse, mcpConsentGrant, mcpConsentGrantListResponse, clientIdentity, } from './client-auth.js';
 export type { ClientLoginRequest, ClientRefreshRequest, ClientLogoutRequest, ClientRegisterRequest, ClientVerifyEmailRequest, ClientResendVerificationRequest, ClientPasswordResetRequest, ClientPasswordResetConfirmRequest, ClientAcceptInvitationRequest, ClientProviderListQuery, ClientProviderListResponse, ClientOidcStartQuery, ClientOidcCallbackQuery, ClientOidcExchangeRequest, ClientOidcErrorCode, ClientMcpInteraction, ClientMcpInteractionDecisionResponse, McpConsentGrant, McpConsentGrantListResponse, ClientIdentity, } from './client-auth.js';
+export { clientRobotListItem, clientRobotListResponse } from './client-robots.js';
+export type { ClientRobotListItem, ClientRobotListResponse } from './client-robots.js';
 export { APP_USER_DISPLAY_NAME_MAX, APP_URL_PLACEHOLDERS, MAIL_TEMPLATE_VARIABLES, DEFAULT_MAIL_TEMPLATES, providerSlug, appUserStatus, appUser, appUserListResponse, createAppUserRequest, patchAppUserRequest, createAppInvitationRequest, appInvitation, pendingAppInvitation, appInvitationListResponse, appOidcProvider, appOidcProviderListResponse, createAppOidcProviderRequest, patchAppOidcProviderRequest, appUrlTemplate, allowedOrigin, emailDomain, appAuthConfig, putAppAuthConfigRequest, mailTemplateKind, appMailTemplate, appMailTemplateListResponse, putAppMailTemplateRequest, mailTemplatePreviewRequest, mailTemplatePreviewResponse, mailTemplateProblemDetails, mailOutcome, } from './app-users.js';
 export type { AppUserStatus, AppUser, AppUserListResponse, CreateAppUserRequest, PatchAppUserRequest, CreateAppInvitationRequest, AppInvitation, PendingAppInvitation, AppInvitationListResponse, AppOidcProvider, AppOidcProviderListResponse, CreateAppOidcProviderRequest, PatchAppOidcProviderRequest, AppAuthConfig, PutAppAuthConfigRequest, MailTemplateKind, AppMailTemplate, AppMailTemplateListResponse, PutAppMailTemplateRequest, MailTemplatePreviewRequest, MailTemplatePreviewResponse, MailTemplateProblemDetails, MailOutcome, } from './app-users.js';
 export { assetKind, URDF_ASSET_NAME, asset, urdfCompleteness, assetListResponse, missingAssetQuery, assetSyncRequest, assetSyncResponse, assetSyncState, assetSyncStatus, assetFailure, assetFailureKind, assetTooLargeDetails, assetSyncBusyDetails, ASSET_UPLOAD_MAX_BYTES, } from './assets.js';

package/dist/index.js

@@ -16,7 +16,7 @@ cameraSource, cameraCredentials, } from './config.js';
 /**
  * The one account of what is wrong with a configuration document, shared by
  * every layer that reports on one. See `config-issues.ts`'s header for why a
- * second copy of this vocabulary is a defect rather than a convenience.
+ * second copy of this vocabulary is a defect, not a convenience.
  */
 export { DOCUMENT_ROOT_PATH, EXPOSURE_SECTIONS, schemaIssues, formatPath, splitFormatPath, configSchemaHash, } from './config-issues.js';
 export { rosGraphEntry, rosGraph, typeField, typeDefinition, parameterFieldsOf } from './introspection.js';
@@ -40,6 +40,7 @@ mailStatus, tierRequiredDetails, passwordChangeRequest, passwordResetRequest, pa
 authMeResponse, patchOrgRequest, patchAuthMeRequest, } from './identity.js';
 export { appIdentifier, app, appListResponse, createAppRequest, updateAppRequest, serverKeyToken, serverKey, serverKeyListResponse, createServerKeyResponse, role, roleListResponse, rolePermissions, } from './apps.js';
 export { clientLoginRequest, clientRefreshRequest, clientLogoutRequest, clientRegisterRequest, clientVerifyEmailRequest, clientResendVerificationRequest, clientPasswordResetRequest, clientPasswordResetConfirmRequest, clientAcceptInvitationRequest, CLIENT_OIDC_CALLBACK_PATH, clientProviderListQuery, clientProviderListResponse, clientOidcStartQuery, clientOidcCallbackQuery, clientOidcExchangeRequest, clientOidcErrorCode, clientMcpInteraction, clientMcpInteractionDecisionResponse, mcpConsentGrant, mcpConsentGrantListResponse, clientIdentity, } from './client-auth.js';
+export { clientRobotListItem, clientRobotListResponse } from './client-robots.js';
 // The per-app identity space.
 export { APP_USER_DISPLAY_NAME_MAX, APP_URL_PLACEHOLDERS, MAIL_TEMPLATE_VARIABLES, DEFAULT_MAIL_TEMPLATES, providerSlug, appUserStatus, appUser, appUserListResponse, createAppUserRequest, patchAppUserRequest, createAppInvitationRequest, appInvitation, pendingAppInvitation, appInvitationListResponse, appOidcProvider, appOidcProviderListResponse, createAppOidcProviderRequest, patchAppOidcProviderRequest, appUrlTemplate, allowedOrigin, emailDomain, appAuthConfig, putAppAuthConfigRequest, mailTemplateKind, appMailTemplate, appMailTemplateListResponse, putAppMailTemplateRequest, mailTemplatePreviewRequest, mailTemplatePreviewResponse, mailTemplateProblemDetails, mailOutcome, } from './app-users.js';
 export { assetKind, URDF_ASSET_NAME, asset, urdfCompleteness, assetListResponse, missingAssetQuery, assetSyncRequest, assetSyncResponse, assetSyncState, assetSyncStatus, assetFailure, assetFailureKind, assetTooLargeDetails, assetSyncBusyDetails, ASSET_UPLOAD_MAX_BYTES, } from './assets.js';

package/dist/jobs.js

@@ -21,17 +21,17 @@ import { slug, wireSeqCursor, wireTimestampMs } from './common.js';
 export const jobState = z.enum(['running', 'succeeded', 'failed', 'cancelled', 'lost']);
 export const job = z.object({
     id: z.uuid().meta({
-        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: z.uuid().meta({ description: 'The robot this job is running on.' }),
     slug: slug.meta({
         description: 'The action or service this job is running, as the published configuration exposes it. One slug carries one job at a time, so every observer of that slug sees the same one.',
     }),
     state: jobState.meta({
-        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: z.iso.datetime().meta({
-        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: z.iso.datetime().meta({
         description: 'When this job last changed, as an ISO 8601 timestamp.',
@@ -176,7 +176,7 @@ export const JOB_RUN_RETENTION_DAYS = 90;
  */
 export const jobActor = z.object({
     kind: z.enum(['developer', 'end_user', 'app_user', 'server_key']).meta({
-        description: 'What the caller was acting as: a `developer` in the console, an `app_user` of one app, or a `server_key` used by server-side code. A bridge invokes nothing, so it is deliberately not a case here. `end_user` appears only on runs recorded before app users replaced the organisation-wide user pool — it is kept so a history page can still render them, and nothing writes it any more.',
+        description: 'What the caller was acting as: a `developer` in the console, an `app_user` of one app, or a `server_key` used by server-side code. A bridge invokes nothing, so it is deliberately not a case here. `end_user` appears only on runs recorded before app users replaced the organisation-wide user pool — kept so old runs still render; nothing writes it now.',
     }),
     id: z.uuid().meta({
         description: 'The id of the Fleetless user, app user or server key that invoked the run.',
@@ -200,7 +200,7 @@ export const jobRunKind = z.enum(['action', 'service']);
  */
 export const jobRun = z.object({
     id: z.uuid().meta({
-        description: 'The run\'s id, which is the same id the invocation was answered with — so a caller that kept a job id can find its durable record here later.',
+        description: 'The run\'s id — the same id the invocation was answered with, so a caller that kept a job id can find its durable record here later.',
     }),
     robot_id: z.uuid().meta({ description: 'The robot the run happened on.' }),
     slug: slug.meta({

package/dist/mcp.d.ts

@@ -8,8 +8,8 @@ import { z } from 'zod';
  * **This file describes the seam, not the protocol.** The MCP messages
  * themselves (`initialize`, `tools/list`, `tools/call`) are defined by the
  * Model Context Protocol and implemented with its official SDK — writing our
- * own zod copies of them would create a second source of truth for somebody
- * else's specification, which is the one thing this package exists to avoid.
+ * own zod copies of them would duplicate somebody else's specification, the
+ * one thing this package exists to avoid.
  * What lives here is what *Fleetless* decides: which revision we speak, where
  * the endpoint is, how a tool is named, and what the console is shown before
  * an end user ever connects.
@@ -94,12 +94,9 @@ export declare function mcpAppEndpointPath(appIdentifier: string): string;
  * ever fetch. Writing them here is what keeps that reading from being made
  * twice.
  *
- * **These are paths, not URLs.** Append them to `PUBLIC_API_BASE_URL`, for the
- * reason `mcpAppEndpointPath` states: the cloud mints every issuer, resource
- * and `aud` from the canonical base and compares a token's `aud` against that
- * string, never against the request's `Host`. The friendly alias is a proxy in
- * front of the same cloud, and a URL built on it hands a client an audience
- * the token endpoint will refuse.
+ * **These are paths, not URLs.** Append them to `PUBLIC_API_BASE_URL`, not the
+ * friendly `mcp.fleetless.dev` alias — see `mcpAppEndpointPath` for why: a URL
+ * built on the alias carries an audience the token endpoint refuses.
  *
  * Named in the shape `OAUTH_PATHS` had, and deliberately a **function** rather
  * than the object that constant was: there is one set of these per app, and a
@@ -172,7 +169,12 @@ export declare const mcpCapabilities: z.ZodObject<{
     assets: z.ZodBoolean;
 }, z.core.$strip>;
 export type McpCapabilities = z.infer<typeof mcpCapabilities>;
-/** What one caller may do on one robot — the answer to `robot_describe`. */
+/**
+ * What one caller may do on one robot — the answer to `robot_describe`, and
+ * since 1.1.0 to `GET /api/robots/:id/datasheet` as well. One schema for both
+ * surfaces on purpose: an app and an AI tool read the same description of the
+ * same grant. The `mcp` prefix is history, not scope.
+ */
 export declare const mcpRobotDatasheet: z.ZodObject<{
     robot_id: z.ZodUUID;
     robot_name: z.ZodString;

package/dist/mcp.js

@@ -9,8 +9,8 @@ import { slug } from './common.js';
  * **This file describes the seam, not the protocol.** The MCP messages
  * themselves (`initialize`, `tools/list`, `tools/call`) are defined by the
  * Model Context Protocol and implemented with its official SDK — writing our
- * own zod copies of them would create a second source of truth for somebody
- * else's specification, which is the one thing this package exists to avoid.
+ * own zod copies of them would duplicate somebody else's specification, the
+ * one thing this package exists to avoid.
  * What lives here is what *Fleetless* decides: which revision we speak, where
  * the endpoint is, how a tool is named, and what the console is shown before
  * an end user ever connects.
@@ -124,7 +124,12 @@ export const mcpCapabilities = z.object({
     action_history: z.boolean(),
     assets: z.boolean(),
 });
-/** What one caller may do on one robot — the answer to `robot_describe`. */
+/**
+ * What one caller may do on one robot — the answer to `robot_describe`, and
+ * since 1.1.0 to `GET /api/robots/:id/datasheet` as well. One schema for both
+ * surfaces on purpose: an app and an AI tool read the same description of the
+ * same grant. The `mcp` prefix is history, not scope.
+ */
 export const mcpRobotDatasheet = z.object({
     robot_id: z.uuid(),
     robot_name: z.string().min(1).max(200),

package/dist/oauth.d.ts

@@ -14,8 +14,8 @@ import { z } from 'zod';
  * and per app for an app's users — and the console's own OAuth portal, which
  * answers `oauthRedirectResponse` at its login and sign-up steps.
  *
- * The client model this file was written to get right is still the important
- * part, and it survived the cut intact: an MCP client **registers itself**
+ * The client model this file was written to get right survived the cut
+ * intact: an MCP client **registers itself**
  * (RFC 7591) because the person only ever pastes a URL into an AI tool.
  * Nobody vetted it, its redirect URIs arrive from the client itself, and the
  * tools it will call move a physical robot. That is why consent names the
@@ -37,10 +37,9 @@ import { z } from 'zod';
  * app's auth settings — are ordinary console API and use `apiError` with
  * `ERROR_CODES` like everything else.
  *
- * So: **two shapes, split by audience, not by accident.** Written down here
- * because the natural instinct on finding two error formats in one server is
- * to unify them, and doing so silently removes the reason the standard one is
- * there.
+ * So: **two shapes, split by audience, not by accident.** Written down
+ * because two error formats in one server invite unifying them — which would
+ * silently erase the reason the standard one exists.
  *
  * **The split is by audience and the path prefix will mislead you.**
  * `/mcp/oauth/consent` sits under an `/oauth/` segment and is nevertheless an
@@ -198,10 +197,9 @@ export type DynamicClientRegistrationResponse = z.infer<typeof dynamicClientRegi
  * from a client we are about to trust, where an unknown key is a caller
  * assuming a feature into existence, while a token request comes from any
  * RFC-compliant client, which may legitimately send parameters this server
- * does not read. Refusing those would be a conformance bug. The consequence
- * is worth stating because it bit the test for this very schema: unknown keys
- * are **stripped**, so `safeParse().success` cannot tell a present field from
- * an absent one. Assert on the parsed value.
+ * does not read. Refusing those would be a conformance bug. Unknown keys are
+ * **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<{
     grant_type: z.ZodLiteral<"authorization_code">;

package/dist/oauth.js

@@ -14,8 +14,8 @@ import { z } from 'zod';
  * and per app for an app's users — and the console's own OAuth portal, which
  * answers `oauthRedirectResponse` at its login and sign-up steps.
  *
- * The client model this file was written to get right is still the important
- * part, and it survived the cut intact: an MCP client **registers itself**
+ * The client model this file was written to get right survived the cut
+ * intact: an MCP client **registers itself**
  * (RFC 7591) because the person only ever pastes a URL into an AI tool.
  * Nobody vetted it, its redirect URIs arrive from the client itself, and the
  * tools it will call move a physical robot. That is why consent names the
@@ -37,10 +37,9 @@ import { z } from 'zod';
  * app's auth settings — are ordinary console API and use `apiError` with
  * `ERROR_CODES` like everything else.
  *
- * So: **two shapes, split by audience, not by accident.** Written down here
- * because the natural instinct on finding two error formats in one server is
- * to unify them, and doing so silently removes the reason the standard one is
- * there.
+ * So: **two shapes, split by audience, not by accident.** Written down
+ * because two error formats in one server invite unifying them — which would
+ * silently erase the reason the standard one exists.
  *
  * **The split is by audience and the path prefix will mislead you.**
  * `/mcp/oauth/consent` sits under an `/oauth/` segment and is nevertheless an
@@ -180,10 +179,10 @@ export const MCP_DCR_MAX_REDIRECT_URIS = 5;
 export const dynamicClientRegistrationRequest = z
     .object({
     redirect_uris: z.array(redirectUri).min(1).max(MCP_DCR_MAX_REDIRECT_URIS).meta({
-        description: `Where the authorization code may be returned, and the one field a registration cannot omit. Each must be an \`https\` URL, or \`http\` on an explicit loopback address for a native app that cannot hold a certificate, and none may carry a fragment. There must be between \`1\` and \`${MCP_DCR_MAX_REDIRECT_URIS}\` of them; duplicates are collapsed rather than counted twice. Matched **exactly** at the authorize step against what was registered here.`,
+        description: `Where the authorization code may be returned, and the one field a registration cannot omit. Each must be an \`https\` URL, or \`http\` on an explicit loopback address for a native app that cannot hold a certificate, and none may carry a fragment. Between \`1\` and \`${MCP_DCR_MAX_REDIRECT_URIS}\` of them; duplicates are collapsed rather than counted twice. Matched **exactly** at the authorize step against what was registered here.`,
     }),
     client_name: z.string().min(1).max(200).optional().meta({
-        description: 'The name the client calls itself. Optional — a registration without one is recorded under a default name, per RFC 7591\'s making every metadata field optional. It is **not** vouched for by Fleetless and must never be rendered as if it were: a self-registered client chooses this string, and one has called itself *"Fleetless Official Helper"*.',
+        description: 'The name the client calls itself. Optional: RFC 7591 makes every metadata field optional, so a registration without one is recorded under a default name. It is **not** vouched for by Fleetless and must never be rendered as if it were: a self-registered client chooses this string, and one has called itself *"Fleetless Official Helper"*.',
     }),
     token_endpoint_auth_method: z.enum(['none']).optional().meta({
         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.',
@@ -257,10 +256,9 @@ export const dynamicClientRegistrationResponse = z.object({
  * from a client we are about to trust, where an unknown key is a caller
  * assuming a feature into existence, while a token request comes from any
  * RFC-compliant client, which may legitimately send parameters this server
- * does not read. Refusing those would be a conformance bug. The consequence
- * is worth stating because it bit the test for this very schema: unknown keys
- * are **stripped**, so `safeParse().success` cannot tell a present field from
- * an absent one. Assert on the parsed value.
+ * does not read. Refusing those would be a conformance bug. Unknown keys are
+ * **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
     .object({
@@ -280,7 +278,7 @@ export const oauthTokenRequest = z
         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: z.url().optional().meta({
-        description: 'The resource the token is being 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.',
+        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.',
     }),
 })
     .meta({
@@ -325,7 +323,7 @@ export const authorizationServerMetadata = z.object({
         description: 'The issuer identifier of this authorization server, per RFC 8414 §2. It is what a client checks a token\'s `iss` against.',
     }),
     authorization_endpoint: z.url().meta({
-        description: 'The URL a client sends the user to in order to authorize.',
+        description: 'Where a client sends the user to authorize.',
     }),
     token_endpoint: z.url().meta({
         description: 'The URL where a client exchanges an authorization code, or a refresh token, for tokens.',
@@ -438,7 +436,7 @@ export const oauthAuthorizeQuery = z
         description: 'One of the client\'s registered redirect URIs, compared **exactly** — string equality against the registered list, never a prefix or a host match. Both the shape (`redirectUri`) and the registration are checked, and a failure of either is a `400 invalid_request` with no redirect.',
     }),
     code_challenge: z.string().min(1).meta({
-        description: 'The PKCE challenge; the verifier is presented at the token endpoint. Only non-emptiness is checked here — length and alphabet are not — since the verifier is what actually has to match.',
+        description: 'The PKCE challenge; the verifier is presented at the token endpoint. Only non-emptiness is checked here — length and alphabet are not — since the verifier is what has to match.',
     }),
     code_challenge_method: z.literal('S256').meta({
         description: 'Only `S256`. `plain` is refused: a challenge equal to its verifier defends against nothing.',

package/dist/protocol.d.ts

@@ -4,8 +4,8 @@ import { z } from 'zod';
  * Bridge <-> cloud protocol, version 2.
  *
  * The version is exchanged in the hello handshake; the cloud refuses an
- * incompatible bridge with a clear message: `protocol_mismatch`, which names
- * both versions and reaches the robot's detail view as `last_hello_error`.
+ * incompatible bridge: `protocol_mismatch`, which names both versions and
+ * reaches the robot's detail view as `last_hello_error`.
  *
  * **2 (2026-08-21):** `config_applied.errors` entries gained `kind` and `code`
  * beside `message`. The check is `!==`, not a floor, so a bridge that is not
@@ -72,12 +72,11 @@ export { slug } from './common.js';
  *
  * It carries the **slug and the state**, not only the id, because the cloud's
  * reconciliation needs both and had neither. Reading `active_job_ids` as bare
- * uuids, a restarted cloud could answer exactly one question — "is this job
- * still alive?" — for jobs it already knew about. It could not name what the
- * robot is doing, could not tell a job that is still `running` from one that
- * finished while the cloud was down, and had nothing at all to say about a
- * job it never recorded because it crashed between minting the id and writing
- * the row.
+ * uuids, a restarted cloud could only ask "is this job still alive?" for jobs
+ * it already knew about — not what the robot is doing, not whether a
+ * `running` job had actually finished while the cloud was down, and nothing
+ * at all about a job it never recorded because it crashed between minting the
+ * id and writing the row.
  *
  * `state` is the bridge's own current answer, not a history. A bridge that
  * has a terminal result still in hand reports it here and the cloud writes it