@fleetless/contracts 6.0.0-next.1 → 6.0.0-next.3

package/artifacts/routes.json

@@ -664,7 +664,7 @@
         "validation_error"
       ],
       "transport": "http",
-      "notes": "The body is `{ \"name\": string }` — non-empty, trimmed, at most 120 characters — and is deliberately not a contract shape: contracts define the `role` this answers with, not this one trivial request. **The answer is a bare `role`, not an envelope**, unlike the listing beside it."
+      "notes": "The body is `{ \"name\": string }` — non-empty, trimmed, at most 60 characters as on `role.name` — and is deliberately not a contract shape: contracts define the `role` this answers with, not this one trivial request. **The answer is a bare `role`, not an envelope**, unlike the listing beside it."
     },
     {
       "method": "GET",
@@ -794,6 +794,77 @@
       "transport": "http",
       "notes": "Built by the same builder the MCP server's own `robot_describe` uses, so the two cannot drift. It answers what the role *would* be offered and consults nothing about any user's actual MCP entitlement. A robot the role grants nothing on still appears, with an empty `exposures` — dropping it would read as \"not attached\", which is a different fact."
     },
+    {
+      "method": "PATCH",
+      "path": "/api/apps/:id/roles/:roleId",
+      "section": "apps",
+      "summary": "Renames a role; its users keep it.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
+        },
+        {
+          "name": "roleId",
+          "description": "The role's uuid, from `GET /api/apps/:id/roles`; a role of another app answers `404`."
+        }
+      ],
+      "query": null,
+      "request": "role-rename-request",
+      "response": "role",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "not_found",
+        "validation_error",
+        "role_name_taken"
+      ],
+      "transport": "http",
+      "notes": "Names are unique per app, compared exactly as stored after trimming. Built-in roles can be renamed."
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/apps/:id/roles/:roleId",
+      "section": "apps",
+      "summary": "Deletes a role, moving its users, pending invitations and default-role status to another role.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 204,
+      "params": [
+        {
+          "name": "id",
+          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
+        },
+        {
+          "name": "roleId",
+          "description": "The role's uuid, from `GET /api/apps/:id/roles`; a role of another app answers `404`."
+        }
+      ],
+      "query": "role-delete-query",
+      "request": null,
+      "response": null,
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "not_found",
+        "validation_error",
+        "role_in_use",
+        "last_role"
+      ],
+      "transport": "http",
+      "notes": "Without `move_to`, a role that app users or pending invitations hold, or that is the app's default, answers `409 role_in_use` with `{ users, invitations, is_default }`. With `move_to` — another role of the same app, else `400 validation_error` — one transaction moves `app_users.role_id`, pending invitations and `default_role_id`, then deletes the role and its permissions. The app's only role answers `409 last_role`. Built-in roles can be deleted like any other."
+    },
     {
       "method": "POST",
       "path": "/api/apps/:id/server-keys",
@@ -1114,10 +1185,11 @@
         "token_revoked",
         "invalid_uuid",
         "not_found",
-        "target_state_conflict"
+        "target_state_conflict",
+        "method_not_allowed"
       ],
       "transport": "http",
-      "notes": "The support door beside `POST /api/client/password/reset`: the same one-hour token and the same link, triggered by a developer for a user who asked them rather than the form. **No enumeration discipline applies** — the caller is authenticated into the app and can read the user list — so this one answers what actually happened: `{ \"mail\": mailStatus }`, where `not_configured` is a deployment without a mailer and `failed` is the state worth somebody's attention. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none. `409 target_state_conflict` names `password` with rule `not_set` for an account that has none — an OIDC-only app user, whom a reset link would hand a second, quieter door — and `status` with rule `blocked` for a blocked one, since `POST /api/client/password/reset` mails a blocked account nothing and the two doors may not disagree. Setting the password directly is deliberately not offered; a developer who could would hold their customers' credentials."
+      "notes": "The support door beside `POST /api/client/password/reset`, refused like it with `403 method_not_allowed` while the app has the password method off: the same one-hour token and the same link, triggered by a developer for a user who asked them rather than the form. **No enumeration discipline applies** — the caller is authenticated into the app and can read the user list — so this one answers what actually happened: `{ \"mail\": mailStatus }`, where `not_configured` is a deployment without a mailer and `failed` is the state worth somebody's attention. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none. `409 target_state_conflict` names `password` with rule `not_set` for an account that has none — an OIDC-only app user, whom a reset link would hand a second, quieter door — and `status` with rule `blocked` for a blocked one, since `POST /api/client/password/reset` mails a blocked account nothing and the two doors may not disagree. Setting the password directly is deliberately not offered; a developer who could would hold their customers' credentials."
     },
     {
       "method": "DELETE",
@@ -1800,7 +1872,7 @@
         },
         {
           "name": "kind",
-          "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`."
+          "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`."
         }
       ],
       "query": null,
@@ -1834,7 +1906,7 @@
         },
         {
           "name": "kind",
-          "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`."
+          "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`."
         }
       ],
       "query": null,
@@ -1870,7 +1942,7 @@
         },
         {
           "name": "kind",
-          "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`."
+          "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`."
         }
       ],
       "query": null,
@@ -1904,7 +1976,7 @@
         },
         {
           "name": "kind",
-          "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`."
+          "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`."
         }
       ],
       "query": null,
@@ -1940,7 +2012,7 @@
         },
         {
           "name": "kind",
-          "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`."
+          "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`."
         }
       ],
       "query": null,
@@ -2406,7 +2478,7 @@
       "response": null,
       "errors": [],
       "transport": "http",
-      "notes": "HTML, and a GET rather than the body of the authorize response — so it is reloadable, bookmarkable and survives a back button, which the inline page it replaced was not. An expired, consumed, unknown or hand-edited interaction renders one page at `410`, and so does a client whose dynamic registration lapsed in between."
+      "notes": "HTML, and a GET rather than the body of the authorize response — so it is reloadable, bookmarkable and survives a back button, which the inline page it replaced was not. An expired, consumed, unknown or hand-edited interaction renders one page at `410`, and so does a client whose dynamic registration lapsed in between. It offers the email field and `Sign in with a passkey`, and opening it binds the interaction to this browser with the browser-proof cookie, which every sign-in step after it checks."
     },
     {
       "method": "POST",
@@ -2425,10 +2497,11 @@
       "errors": [
         "rate_limited",
         "validation_error",
-        "token_spent"
+        "token_spent",
+        "wrong_browser"
       ],
       "transport": "http",
-      "notes": "The page answers `Check your email` **for every address**: a known one gets `Your Fleetless sign-in code`, six digits valid ten minutes; an unknown one gets a mail saying no Fleetless account uses it, with a link to sign up (or the waiting list while sign-up is closed). So the page never reveals who has an account, and the address is trimmed and compared case-insensitively. A request within sixty seconds of the last one for the same address renders the same page without a second mail. The browser-proof cookie is set here. A browser form post gets the code card; a JSON caller gets `{ \"next\": \"/mcp/oauth/code\" }`, which has no schema. A dead interaction is `410 token_spent`."
+      "notes": "The page answers `Check your email` **for every address**: a known one gets `Your Fleetless sign-in code`, six digits valid ten minutes; an unknown one gets a mail saying no Fleetless account uses it, with a link to sign up (or the waiting list while sign-up is closed). So the page never reveals who has an account, and the address is trimmed and compared case-insensitively. A request within sixty seconds of the last one for the same address renders the same page without a second mail. The browser-proof cookie is set here when the interaction has none yet, and checked when it has. A browser form post gets the code card; a JSON caller gets `{ \"next\": \"/mcp/oauth/code\" }`, which has no schema. A dead interaction is `410 token_spent`."
     },
     {
       "method": "POST",
@@ -2544,7 +2617,7 @@
         "wrong_browser"
       ],
       "transport": "http",
-      "notes": "Before an address is known the options name no credential, so the browser offers every discoverable passkey for `fleetless.dev` (`Sign in with a passkey`); after the code step they name the account's own passkeys. User verification is required. The challenge is bound to the interaction and single-use."
+      "notes": "Before an address is known the options name no credential, so the browser offers every discoverable passkey for `fleetless.dev` (`Sign in with a passkey`); after the code step they name the account's own passkeys. User verification is required. The challenge is bound to the interaction and single-use. **This is the first step of a passkey sign-in**, which has no email step: the browser-proof cookie is set here when the interaction has none yet, and checked when it has — so `POST /mcp/oauth/passkey` can require it."
     },
     {
       "method": "POST",
@@ -2808,7 +2881,7 @@
       "response": null,
       "errors": [],
       "transport": "http",
-      "notes": "HTML: the email field, `Email me a code`, and `Sign in with a passkey`. An expired, consumed, unknown or hand-edited interaction renders one page at `410`: which of the four it was is not a fact a stranger may learn, and to the person it is one fact anyway. The page resolves nothing about the address typed into it, so there is no enumeration oracle here at all."
+      "notes": "HTML: the email field, `Email me a code`, and `Sign in with a passkey`. Opening it binds the interaction to this browser with the browser-proof cookie, which every sign-in step after it checks. An expired, consumed, unknown or hand-edited interaction renders one page at `410`: which of the four it was is not a fact a stranger may learn, and to the person it is one fact anyway. The page resolves nothing about the address typed into it, so there is no enumeration oracle here at all."
     },
     {
       "method": "POST",
@@ -2827,10 +2900,11 @@
       "errors": [
         "rate_limited",
         "validation_error",
-        "token_spent"
+        "token_spent",
+        "wrong_browser"
       ],
       "transport": "http",
-      "notes": "The page answers `Check your email` **for every address**: a known one gets `Your Fleetless sign-in code`, six digits valid ten minutes; an unknown one gets a mail saying no Fleetless account uses it, with a link to sign up (or the waiting list while sign-up is closed). So the page never reveals who has an account, and the address is trimmed and compared case-insensitively. A request within sixty seconds of the last one for the same address renders the same page without a second mail. The browser-proof cookie is set here. A browser form post gets the code card; a JSON caller gets `{ \"next\": \"/console/oauth/code\" }`, which has no schema. A dead interaction is `410 token_spent`."
+      "notes": "The page answers `Check your email` **for every address**: a known one gets `Your Fleetless sign-in code`, six digits valid ten minutes; an unknown one gets a mail saying no Fleetless account uses it, with a link to sign up (or the waiting list while sign-up is closed). So the page never reveals who has an account, and the address is trimmed and compared case-insensitively. A request within sixty seconds of the last one for the same address renders the same page without a second mail. The browser-proof cookie is set here when the interaction has none yet, and checked when it has. A browser form post gets the code card; a JSON caller gets `{ \"next\": \"/console/oauth/code\" }`, which has no schema. A dead interaction is `410 token_spent`."
     },
     {
       "method": "POST",
@@ -2946,7 +3020,7 @@
         "wrong_browser"
       ],
       "transport": "http",
-      "notes": "Before an address is known the options name no credential, so the browser offers every discoverable passkey for `fleetless.dev` (`Sign in with a passkey`); after the code step they name the account's own passkeys. User verification is required. The challenge is bound to the interaction and single-use."
+      "notes": "Before an address is known the options name no credential, so the browser offers every discoverable passkey for `fleetless.dev` (`Sign in with a passkey`); after the code step they name the account's own passkeys. User verification is required. The challenge is bound to the interaction and single-use. **This is the first step of a passkey sign-in**, which has no email step: the browser-proof cookie is set here when the interaction has none yet, and checked when it has — so `POST /console/oauth/passkey` can require it."
     },
     {
       "method": "POST",
@@ -4004,7 +4078,7 @@
         "method_not_allowed"
       ],
       "transport": "http",
-      "notes": "**`202` and an empty body for every request the policy allows**, in status, body and timing, whether or not the address names an active account of this app — a decoy like `POST /api/client/resend-verification`, so this is no enumeration oracle. A mail goes out only for an account that may sign in. The code is six digits, valid ten minutes, takes five wrong attempts, and a new request expires the previous one for the same address; a request within sixty seconds of the last sends no second mail. The address is trimmed and compared case-insensitively. `404 not_found` is the **app identifier**, never the address; `403 method_not_allowed` when the app has the email-code method off. Limited per app, address and IP, so it cannot be used to mail somebody repeatedly."
+      "notes": "**`202` and an empty body for every request the policy allows**, in status, body and timing, whether or not the address names an active account of this app — a decoy like `POST /api/client/resend-verification`, so this is no enumeration oracle. A mail goes out for an `active` account and for one still `pending_verification` — spending the code proves the address, as the verification link would — and never for a `blocked` one or an unknown address. The code is six digits, valid ten minutes, takes five wrong attempts, and a new request expires the previous one for the same address; a request within sixty seconds of the last sends no second mail. The address is trimmed and compared case-insensitively. `404 not_found` is the **app identifier**, never the address; `403 method_not_allowed` when the app has the email-code method off. Limited per app, address and IP, so it cannot be used to mail somebody repeatedly."
     },
     {
       "method": "POST",
@@ -4117,10 +4191,11 @@
       "errors": [
         "rate_limited",
         "validation_error",
-        "not_found"
+        "not_found",
+        "method_not_allowed"
       ],
       "transport": "http",
-      "notes": "The pair of app identifier and address is the identifier: an app user's address is unique only within their app. Status, body and timing are identical for a known and an unknown address. An account with no password — one created through an identity provider — is mailed nothing and still answers `202`. `404 not_found` is the **app identifier**, never the address. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none."
+      "notes": "The pair of app identifier and address is the identifier: an app user's address is unique only within their app. `403 method_not_allowed` when the app has the password method off — a reset link whose confirmation would be refused is not mailed; the code names the app's policy, not a person. Status, body and timing are identical for a known and an unknown address. An account with no password — one created through an identity provider — is mailed nothing and still answers `202`. `404 not_found` is the **app identifier**, never the address. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none."
     },
     {
       "method": "POST",
@@ -4235,10 +4310,11 @@
         "forbidden",
         "validation_error",
         "invalid_credentials",
-        "target_state_conflict"
+        "target_state_conflict",
+        "method_not_allowed"
       ],
       "transport": "http",
-      "notes": "The guard admits all three caller kinds, but a password belongs to an app user specifically — a developer bearer or a server key reaching this is `401 unauthorized`. Every other session of the account ends; the answer is the replacement pair, so the tab that made the change stays signed in. An app user belongs to one app, so \"every session\" is this app's. An account that has **no password** — an OIDC-only app user, which the schema admits — answers `409 target_state_conflict` naming the `password` field with rule `not_set`, not `401`: the session is live and the token is fine, it is the account that has nothing to change, and telling such a caller to sign in again sends them round a loop that ends here."
+      "notes": "`403 method_not_allowed` when the app has the password method off: a stored password stays stored but is not in use, so it is not changed either. The guard admits all three caller kinds, but a password belongs to an app user specifically — a developer bearer or a server key reaching this is `401 unauthorized`. Every other session of the account ends; the answer is the replacement pair, so the tab that made the change stays signed in. An app user belongs to one app, so \"every session\" is this app's. An account that has **no password** — an OIDC-only app user, which the schema admits — answers `409 target_state_conflict` naming the `password` field with rule `not_set`, not `401`: the session is live and the token is fine, it is the account that has nothing to change, and telling such a caller to sign in again sends them round a loop that ends here."
     },
     {
       "method": "GET",
@@ -4299,6 +4375,7 @@
       "params": [],
       "query": null,
       "request": "client-two-factor-setup-request",
+      "requestOptional": true,
       "response": "two-factor-setup-response",
       "errors": [
         "rate_limited",
@@ -4308,7 +4385,7 @@
         "target_state_conflict"
       ],
       "transport": "http",
-      "notes": "**Two ways in, decided in the handler.** During sign-in the body carries the `two_factor_setup_required` challenge, and that is the credential; from the app's own account settings the app user's bearer is, with no challenge. Neither is `401 unauthorized`, and a dead challenge is `410 token_spent`. `409 target_state_conflict` names `two_factor` with rule `off` when the app's policy is `off`. The secret is not in use until `POST /api/client/two-factor/setup/confirm` accepts a code from it; a second call replaces a pending secret, and an account that already has an authenticator keeps it until the new one is confirmed."
+      "notes": "**Two ways in, decided in the handler.** During sign-in the body carries the `two_factor_setup_required` challenge, and that is the credential; from the app's own account settings the app user's bearer is, with no challenge and an empty or missing body. Neither is `401 unauthorized`, and a dead challenge is `410 token_spent`. `409 target_state_conflict` names `two_factor` with rule `off` when the app's policy is `off`. The secret is not in use until `POST /api/client/two-factor/setup/confirm` accepts a code from it; a second call replaces a pending secret, and an account that already has an authenticator keeps it until the new one is confirmed."
     },
     {
       "method": "POST",
@@ -6267,6 +6344,30 @@
       "transport": "http",
       "notes": "A window longer than `USAGE_WINDOW_MAX_DAYS` is refused naming the field, not silently capped: a caller who asked for more than the platform will answer is owed a refusal, not a shorter answer they will mistake for the whole picture. `from_day <= to_day` is a cross-field rule no JSON Schema can express and is enforced here. The window is echoed back."
     },
+    {
+      "method": "POST",
+      "path": "/api/feedback",
+      "section": "org",
+      "summary": "Sends a message from a developer to the people who build Fleetless.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 202,
+      "params": [],
+      "query": null,
+      "request": "feedback-request",
+      "response": "feedback-response",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "validation_error",
+        "rate_limited"
+      ],
+      "transport": "http",
+      "notes": "The message is stored before any mail is tried, so `202` means it is kept whatever `mail` says: `sent`, `failed`, or `not_configured` when this cloud has no feedback address. At most 10 messages per developer per hour; the 11th answers `429 rate_limited` with `retry_after_ms`. Replies come by mail, to the sender's address."
+    },
     {
       "method": "POST",
       "path": "/api/bridge/assets",

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

@@ -33,17 +33,10 @@
       "description": "When the token stops working. Seven days from issue; an expired token answers exactly as an unknown one does."
     },
     "accept_url": {
-      "anyOf": [
-        {
-          "type": "string",
-          "maxLength": 500,
-          "format": "uri"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "description": "The link to give the invitee: the app's `invite_url` with the token substituted for `{token}`, or the Fleetless-hosted invitation page when the app has configured none. Bounded like every other URL that gets mailed, logged and rendered. Nullable for readers of the earlier shape; the cloud always fills it."
+      "type": "string",
+      "maxLength": 500,
+      "format": "uri",
+      "description": "The link to give the invitee: the app's `invite_url` with the token substituted for `{token}`, or the Fleetless-hosted invitation page when the app has configured none. Bounded like every other URL that gets mailed, logged and rendered."
     },
     "mail": {
       "type": "string",

package/artifacts/schema/audit-query.schema.json

@@ -48,6 +48,12 @@
       "minLength": 1,
       "maxLength": 40
     },
+    "target_id": {
+      "description": "Events whose target is this id; for a robot also the events that name it in `details.robot_id` (`action.invoked`, `service.called`, …), so a robot's events include what was started on it.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200
+    },
     "from_ms": {
       "anyOf": [
         {

package/artifacts/schema/feedback-request.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "kind": {
+      "type": "string",
+      "enum": [
+        "idea",
+        "problem",
+        "question",
+        "other"
+      ],
+      "description": "What the message is: an `idea`, a `problem`, a `question` or `other`. It only sorts the inbox; it changes nothing about how the message is handled."
+    },
+    "message": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 5000,
+      "description": "What the developer wrote, trimmed. At most 5000 characters; a message that is only whitespace is refused."
+    },
+    "page": {
+      "type": "string",
+      "maxLength": 512,
+      "pattern": "^\\/.*",
+      "description": "The console path the message was sent from, e.g. `/robots/:id/jobs` with its real id. A path, never a full URL, so no host and no query string reach the inbox by accident."
+    }
+  },
+  "required": [
+    "kind",
+    "message",
+    "page"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/feedback-response.schema.json

@@ -0,0 +1,27 @@
+{
+  "$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 stored message. It exists whatever `mail` says."
+    },
+    "mail": {
+      "type": "string",
+      "enum": [
+        "sent",
+        "not_requested",
+        "not_configured",
+        "failed"
+      ],
+      "description": "What happened to the notification mail: `sent`, `failed`, or `not_configured` when this cloud has no feedback address. The message is stored in every case, so a client shows success for all three."
+    }
+  },
+  "required": [
+    "id",
+    "mail"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/job-actor.schema.json

@@ -23,12 +23,26 @@
       "minLength": 1,
       "maxLength": 200,
       "description": "A display name taken at invoke time — the email for a Fleetless user or an app user, the key's own name for a server key. Storing it rather than joining is the point: renaming a key afterwards does not rewrite history."
+    },
+    "name": {
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The person's display name when the job started: the Fleetless user's `display_name` for a developer, the app user's `display_name` for an app user. `null` for a server key, when the person had no name set, and for runs recorded before contracts 5.3.0. Show `label` when it is null."
     }
   },
   "required": [
     "kind",
     "id",
-    "label"
+    "label",
+    "name"
   ],
   "additionalProperties": false
 }

package/artifacts/schema/job-run-list-response.schema.json

@@ -142,12 +142,26 @@
                 "minLength": 1,
                 "maxLength": 200,
                 "description": "A display name taken at invoke time — the email for a Fleetless user or an app user, the key's own name for a server key. Storing it rather than joining is the point: renaming a key afterwards does not rewrite history."
+              },
+              "name": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 200
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "The person's display name when the job started: the Fleetless user's `display_name` for a developer, the app user's `display_name` for an app user. `null` for a server key, when the person had no name set, and for runs recorded before contracts 5.3.0. Show `label` when it is null."
               }
             },
             "required": [
               "kind",
               "id",
-              "label"
+              "label",
+              "name"
             ],
             "additionalProperties": false,
             "description": "Who invoked the run, and what they were acting as at the time."

package/artifacts/schema/job-run.schema.json

@@ -137,12 +137,26 @@
           "minLength": 1,
           "maxLength": 200,
           "description": "A display name taken at invoke time — the email for a Fleetless user or an app user, the key's own name for a server key. Storing it rather than joining is the point: renaming a key afterwards does not rewrite history."
+        },
+        "name": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 200
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The person's display name when the job started: the Fleetless user's `display_name` for a developer, the app user's `display_name` for an app user. `null` for a server key, when the person had no name set, and for runs recorded before contracts 5.3.0. Show `label` when it is null."
         }
       },
       "required": [
         "kind",
         "id",
-        "label"
+        "label",
+        "name"
       ],
       "additionalProperties": false,
       "description": "Who invoked the run, and what they were acting as at the time."

package/artifacts/schema/role-delete-query.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "move_to": {
+      "description": "Another role of the same app that takes over the deleted role's app users, pending invitations and, when it applies, the app's default. The role itself or a role of another app answers `400 validation_error`.",
+      "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)$"
+    }
+  },
+  "additionalProperties": false
+}

package/artifacts/schema/role-in-use-details.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "users": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "App users whose role this is."
+    },
+    "invitations": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Pending invitations that would grant this role when accepted."
+    },
+    "is_default": {
+      "type": "boolean",
+      "description": "`true` when this is the app's `default_role_id`; the default then moves with the users to `move_to`."
+    }
+  },
+  "required": [
+    "users",
+    "invitations",
+    "is_default"
+  ],
+  "additionalProperties": false
+}

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

@@ -27,7 +27,7 @@
           },
           "builtin": {
             "type": "boolean",
-            "description": "`true` for the two roles every app starts with. Their **rights may be re-scoped** exactly like a custom role's, through `PUT /api/apps/:id/roles/:roleId/permissions` — the flag exists so the console can explain where they came from, not to protect them. It does not make them renamable or deletable — no route does that for any role."
+            "description": "`true` for the two roles every app starts with. Their **rights may be re-scoped** exactly like a custom role's, through `PUT /api/apps/:id/roles/:roleId/permissions` — the flag exists so the console can explain where they came from, not to protect them. Built-in roles can be renamed and deleted like any other; the flag only records that the cloud seeded them."
           }
         },
         "required": [

package/artifacts/schema/role-rename-request.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 60,
+      "description": "The new name, trimmed, 1 to 60 characters. Unique per app: another role of this app with the same name answers `409 role_name_taken`. The role's users keep it under its new name."
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/role.schema.json

@@ -22,7 +22,7 @@
     },
     "builtin": {
       "type": "boolean",
-      "description": "`true` for the two roles every app starts with. Their **rights may be re-scoped** exactly like a custom role's, through `PUT /api/apps/:id/roles/:roleId/permissions` — the flag exists so the console can explain where they came from, not to protect them. It does not make them renamable or deletable — no route does that for any role."
+      "description": "`true` for the two roles every app starts with. Their **rights may be re-scoped** exactly like a custom role's, through `PUT /api/apps/:id/roles/:roleId/permissions` — the flag exists so the console can explain where they came from, not to protect them. Built-in roles can be renamed and deleted like any other; the flag only records that the cloud seeded them."
     }
   },
   "required": [

package/dist/app-users.d.ts

@@ -177,9 +177,8 @@ export type CreateAppInvitationRequest = z.infer<typeof createAppInvitationReque
  *
  * The link points into the developer's app, at their configured `invite_url`,
  * or at the Fleetless-hosted invitation page (`appAuthConfig.hosted_pages`)
- * when the app has configured none. **`accept_url` stays nullable** so a
- * reader written against the earlier shape keeps parsing; the cloud fills it
- * in every case now that a hosted page always exists.
+ * when the app has configured none — so there is always a link, and
+ * `accept_url` is never `null`.
  */
 export declare const appInvitation: z.ZodObject<{
     id: z.ZodUUID;
@@ -187,7 +186,7 @@ export declare const appInvitation: z.ZodObject<{
     email: z.ZodEmail;
     role_id: z.ZodUUID;
     expires_at: z.ZodISODateTime;
-    accept_url: z.ZodNullable<z.ZodURL>;
+    accept_url: z.ZodURL;
     mail: z.ZodEnum<{
         sent: "sent";
         not_requested: "not_requested";

package/dist/app-users.js

@@ -210,9 +210,8 @@ export const createAppInvitationRequest = z
  *
  * The link points into the developer's app, at their configured `invite_url`,
  * or at the Fleetless-hosted invitation page (`appAuthConfig.hosted_pages`)
- * when the app has configured none. **`accept_url` stays nullable** so a
- * reader written against the earlier shape keeps parsing; the cloud fills it
- * in every case now that a hosted page always exists.
+ * when the app has configured none — so there is always a link, and
+ * `accept_url` is never `null`.
  */
 export const appInvitation = z.object({
     id: z.uuid().meta({ description: 'The invitation, as listed and revoked by the developer.' }),
@@ -220,8 +219,8 @@ export const appInvitation = z.object({
     email: z.email().meta({ description: 'The address the invitation was addressed to.' }),
     role_id: z.uuid().meta({ description: 'The role the invitee holds once they accept. Resolved at creation, so a later change to the app\'s default role does not silently re-aim an outstanding invitation.' }),
     expires_at: z.iso.datetime().meta({ description: 'When the token stops working. Seven days from issue; an expired token answers exactly as an unknown one does.' }),
-    accept_url: z.url().max(500).nullable().meta({
-        description: 'The link to give the invitee: the app\'s `invite_url` with the token substituted for `{token}`, or the Fleetless-hosted invitation page when the app has configured none. Bounded like every other URL that gets mailed, logged and rendered. Nullable for readers of the earlier shape; the cloud always fills it.',
+    accept_url: z.url().max(500).meta({
+        description: 'The link to give the invitee: the app\'s `invite_url` with the token substituted for `{token}`, or the Fleetless-hosted invitation page when the app has configured none. Bounded like every other URL that gets mailed, logged and rendered.',
     }),
     mail: mailStatus.meta({
         description: 'What happened to the mail: `sent` means the SMTP server accepted it, not that it was delivered; `not_requested` means none was attempted because the caller asked for none; `not_configured` is an expected state and not a failure; `failed` is the one worth somebody\'s attention.',