@fleetless/sdk 2.0.1 → 2.1.0

package/dist/index.js

@@ -14,9 +14,21 @@ var SDK_ERROR_CODES = [
   "aborted"
 ];
 var FleetlessError = class extends Error {
+  /** What went wrong, as a stable string — the field to branch on. */
   code;
+  /**
+   * Structured detail the server sent with the refusal, if any: the
+   * violations behind `parameter_invalid`, the running job behind `busy`,
+   * `retry_after_ms` behind `rate_limited`. Parse it rather than assume
+   * its shape — `parameterInvalidDetails` is exported for exactly that.
+   */
   details;
+  /** The HTTP status of the response that produced this error, if it came from one. */
   status;
+  /**
+   * Builds an error. `code` is what a caller branches on and `message` is
+   * for a human; anything else the refusal carried goes in `options`.
+   */
   constructor(code, message, options = {}) {
     super(message);
     this.name = "FleetlessError";
@@ -82,7 +94,7 @@ var HttpClient = class {
     this.#credentials = credentials;
   }
   /**
-   * D8 (W6c): calling `request()` with one of `RequestBodyByRoute`'s
+   * Calling `request()` with one of `RequestBodyByRoute`'s
    * literal paths requires `options.body` to match that route's contract
    * type exactly, via `RequestOptionsFor<P>` below.
    *
@@ -102,7 +114,7 @@ var HttpClient = class {
    * RequestOptionsFor<P>` would type-check by construction — the cast
    * bypasses the very check this exists to add, which is the identical
    * "special case that quietly exempts calls from the general rule" shape
-   * D7 already found once in this file. Every current call site to a route
+   * this file has already been caught by once. Every current call site to a route
    * with no body already passes `{}` explicitly for exactly this reason.
    */
   async request(path, options) {
@@ -119,7 +131,7 @@ var HttpClient = class {
   }
   /**
    * Like `request`, but for an endpoint that answers with raw bytes instead
-   * of a JSON body (a camera snapshot, W5) — same auth attachment, same
+   * of a JSON body (a camera snapshot) — same auth attachment, same
    * single retry on `token_expired`, same `FleetlessError` on a non-2xx
    * response; only what a *successful* response is made of differs, so both
    * methods share `#send` rather than duplicating that logic.
@@ -139,7 +151,7 @@ var HttpClient = class {
     return this.#baseUrl;
   }
   /**
-   * `/oauth/token` (RFC 6749 §3.2, §5), and nothing else — deliberately not
+   * `/oauth/token` (RFC 6749 sections 3.2 and 5), and nothing else — deliberately not
    * routed through `request()`/`#send()`, because every difference from
    * those follows from one fact: this is not our own API.
    *
@@ -156,7 +168,7 @@ var HttpClient = class {
    *   OAuth/`apiError` split is "by audience, not by accident"; folding this
    *   into `request()`'s error handling would be the identical mistake one
    *   level down. A failure here answers `{ error, error_description }`
-   *   (RFC 6749 §5.2), never `{ code, message }`. `error` becomes this
+   *   (RFC 6749 section 5.2), never `{ code, message }`. `error` becomes this
    *   `FleetlessError`'s `.code` directly — an OAuth error code (e.g.
    *   `invalid_grant`) IS the stable, branch-on value here, exactly as
    *   `apiError`'s `code` is for every other route.
@@ -456,7 +468,7 @@ function createAssetsApi(http) {
   };
 }
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/common.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/common.js
 import { z } from "zod";
 var SLUG_RULE = "A name is lower-case: it starts with a letter, continues with letters and digits, and joins further words with a single underscore \u2014 `battery_voltage`. Capitals, dashes, dots, spaces, a leading digit and a doubled or trailing underscore are all refused.";
 var slug = z.string().min(2).max(63).regex(/^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/, SLUG_RULE);
@@ -480,7 +492,7 @@ var applyError = z.object({
   details: z.record(z.string(), z.unknown()).optional()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/mcp.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/mcp.js
 import { z as z2 } from "zod";
 var mcpToolKind = z2.enum(["datapoint", "service", "action", "publisher", "camera"]);
 var mcpExposure = z2.object({
@@ -515,16 +527,18 @@ var mcpRolePreviewResponse = z2.object({
 });
 var MCP_ASSET_LINK_TTL_MS = 15 * 60 * 1e3;
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/protocol.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/protocol.js
 import { z as z8 } from "zod";
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/assets.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/assets.js
 import { z as z3 } from "zod";
 var assetKind = z3.enum(["urdf", "mesh", "texture", "other"]);
 var asset = z3.object({
-  id: z3.uuid(),
-  robot_id: z3.uuid(),
-  kind: assetKind,
+  id: z3.uuid().meta({ description: "The asset's id in the store." }),
+  robot_id: z3.uuid().meta({ description: "The robot this asset belongs to." }),
+  kind: assetKind.meta({
+    description: "What the file is: the `urdf` itself, a `mesh` it references, a `texture` a mesh or the URDF paints with, or `other`. A renderer decides from this alone, before fetching anything, what it has to pre-fetch."
+  }),
   /**
    * What the robot called it — for a mesh, the `package://` URI the URDF
    * references, verbatim. That is the only string a developer can match
@@ -559,9 +573,15 @@ var asset = z3.object({
    * Two identical rules, one of which is enforced and one of which is
    * documented, is how W7's traversal happened in the first place.
    */
-  name: z3.string().min(1).max(500),
-  media_type: z3.string().min(1).max(120),
-  size_bytes: z3.number().int().nonnegative(),
+  name: z3.string().min(1).max(500).meta({
+    description: "What the robot called it \u2014 for a mesh, the `package://` URI the URDF references, verbatim, which is the only string a developer can match against their own workspace. A file the URDF never names (an image a `.dae` loads for itself) is named by joining the mesh's own directory with that internal reference."
+  }),
+  media_type: z3.string().min(1).max(120).meta({
+    description: "The media type of the stored bytes, as the producer reported it."
+  }),
+  size_bytes: z3.number().int().nonnegative().meta({
+    description: "How large the stored file is, in bytes."
+  }),
   /**
    * The content hash, and the reason two robots sharing a mesh cost one copy.
    *
@@ -570,14 +590,20 @@ var asset = z3.object({
    * that re-downloads an identical arm for every robot in a fleet is the
    * predictable failure of a store that hides it.
    */
-  sha256: z3.string().regex(/^[a-f0-9]{64}$/),
-  created_at: z3.iso.datetime()
+  sha256: z3.string().regex(/^[a-f0-9]{64}$/).meta({
+    description: 'The content hash, lowercase hex, and the reason two robots sharing a mesh cost one copy. It is exposed because it is the only way a client can tell "this is the same mesh I already have" across robots.'
+  }),
+  created_at: z3.iso.datetime().meta({
+    description: "When the asset was first stored, as an ISO 8601 timestamp."
+  })
 });
 var urdfCompleteness = z3.object({
-  /** Whether a URDF has been synced at all. Availability is a different question. */
-  present: z3.boolean(),
-  /** How many distinct meshes the URDF references. */
-  mesh_count: z3.number().int().nonnegative(),
+  present: z3.boolean().meta({
+    description: "Whether a URDF has been synced at all. Whether one *could* be synced is a different question, answered by `urdf_available`."
+  }),
+  mesh_count: z3.number().int().nonnegative().meta({
+    description: "How many distinct meshes the URDF references."
+  }),
   /**
    * **Was fehlt, und wovon (W9b, DEF-081).**
    *
@@ -593,20 +619,34 @@ var urdfCompleteness = z3.object({
    * Herleitung derselben Tatsache, die von der ersten abweichen kann.
    */
   missing: z3.array(z3.object({
-    uri: z3.string().min(1).max(500),
-    element: z3.enum(["mesh", "texture"])
-  }))
+    uri: z3.string().min(1).max(500).meta({
+      description: "The reference, verbatim, that no stored asset answers \u2014 a `package://` URI the workspace does not hold, or an absolute or bare relative path nothing will ever fetch. A developer whose URDF names one of the latter is entitled to be told so."
+    }),
+    element: z3.enum(["mesh", "texture"]).meta({
+      description: "Which kind of reference it was: geometry the URDF names as a `mesh`, or a `texture` a surface paints with. Without it a client reports a missing texture as a missing mesh, contradicting `mesh_count` beside it."
+    })
+  })).meta({
+    description: "The references nothing in the store answers, each with the element that asked for it. A bare count is a dead end that sends a developer hunting through a workspace by hand; the references are what they can act on, so the references travel."
+  })
 });
 var assetSyncRequest = z3.object({
-  source: z3.enum(["bridge"])
+  source: z3.enum(["bridge"]).meta({
+    description: "Where the bytes come from. `bridge` is the only value today: the connected bridge reads them from the robot's own workspace. It is validated rather than ignored, so a caller naming a source that does not exist yet learns that instead of silently getting a bridge sync."
+  })
 }).strict();
 var assetSyncResponse = z3.object({
-  sync_id: z3.uuid()
+  sync_id: z3.uuid().meta({
+    description: "The sync that has just started. A sync is long-running, so the answer is something to watch rather than a status that was true at the moment of asking."
+  })
 });
 var ASSET_UPLOAD_MAX_BYTES = 64 * 1024 * 1024;
 var assetTooLargeDetails = z3.object({
-  limit_bytes: z3.number().int().positive(),
-  size_bytes: z3.number().int().positive()
+  limit_bytes: z3.number().int().positive().meta({
+    description: "The upload ceiling, in bytes."
+  }),
+  size_bytes: z3.number().int().positive().meta({
+    description: 'How large the refused file actually is, in bytes. With `limit_bytes` beside it a developer can tell whether to shrink the mesh or raise the limit; "too large" alone answers neither.'
+  })
 });
 var assetFailureKind = z3.enum(["unresolvable", "upload_failed", "refused", "too_large"]);
 var assetFailure = z3.object({
@@ -617,8 +657,12 @@ var assetFailure = z3.object({
    * is `URDF_ASSET_NAME`, which is **not** a mesh URI: a consumer rendering
    * this list must not assume every entry is one.
    */
-  reference: z3.string().min(1).max(500),
-  kind: assetFailureKind,
+  reference: z3.string().min(1).max(500).meta({
+    description: "What could not be provided, verbatim \u2014 the same string the asset would have been stored under, so a developer can match it against their own workspace by eye. For a failed URDF upload it is `robot_description`, which is **not** a mesh URI: a consumer must not assume every entry is one."
+  }),
+  kind: assetFailureKind.meta({
+    description: "Why it failed. `unresolvable` means the reference names nothing the producer can find or may read, and is **permanent** \u2014 the only kind reconciliation may treat as gone. `upload_failed` means the bytes exist and the transfer did not succeed, `refused` means it was never attempted because a producer-side ceiling was hit, and `too_large` means it exceeds the upload limit and carries both numbers in `details`."
+  }),
   /**
    * **Die zwei Zahlen, und warum `too_large` eine eigene Art ist (W9b).**
    *
@@ -638,7 +682,9 @@ var assetFailure = z3.object({
    * beschrieben: ein Feld, dessen Regel nur im Kommentar steht, ist eine
    * Bitte.
    */
-  details: assetTooLargeDetails.nullish()
+  details: assetTooLargeDetails.nullish().meta({
+    description: "The two numbers behind a `too_large` failure, and absent for every other kind \u2014 a forced `null` on every `unresolvable` entry buys nothing. The pairing is enforced, not merely described."
+  })
 }).superRefine((f, ctx) => {
   if (f.kind === "too_large" && f.details == null) {
     ctx.addIssue({ code: "custom", path: ["details"], message: "`too_large` without limit_bytes/size_bytes says nothing a developer can act on" });
@@ -649,11 +695,17 @@ var assetFailure = z3.object({
 });
 var assetSyncState = z3.enum(["running", "succeeded", "failed"]);
 var assetSyncStatus = z3.object({
-  sync_id: z3.uuid(),
-  robot_id: z3.uuid(),
-  state: assetSyncState,
-  done: z3.number().int().nonnegative(),
-  total: z3.number().int().nonnegative(),
+  sync_id: z3.uuid().meta({ description: "The sync this status describes." }),
+  robot_id: z3.uuid().meta({ description: "The robot whose assets are being synced." }),
+  state: assetSyncState.meta({
+    description: "Whether the sync is still `running`, or ended `succeeded` or `failed`. It ends `succeeded` only when nothing was left behind: a single entry in `failed` makes the whole sync `failed`."
+  }),
+  done: z3.number().int().nonnegative().meta({
+    description: "How many files have been transferred so far."
+  }),
+  total: z3.number().int().nonnegative().meta({
+    description: "How many files this sync set out to transfer. It is `0` until the producer has finished working out what there is."
+  }),
   /**
    * **Every entry says *why*, because reconciliation could not work without
    * it and a developer could not read it without it** (W7a review, André's
@@ -698,14 +750,23 @@ var assetSyncStatus = z3.object({
    *
    * 1000 x 500 bytes is ~0.5 MiB of names, comfortably inside a 2 MiB frame.
    */
-  failed: z3.array(assetFailure).max(1e3),
-  /** Why the sync ended as it did, when that is not a per-URI fact. */
-  reason: z3.string().min(1).nullable(),
-  started_at: z3.iso.datetime(),
-  updated_at: z3.iso.datetime()
+  failed: z3.array(assetFailure).max(1e3).meta({
+    description: "What could not be provided, one entry per reference, each saying why. Required rather than optional: a sync that quietly drops three meshes and reports success moves the failure into somebody's renderer, where it shows up as a robot with missing limbs and no cause. At most `1000` entries \u2014 a producer at its own ceiling reports one entry saying so rather than growing the list."
+  }),
+  reason: z3.string().min(1).nullable().meta({
+    description: "Why the sync ended as it did, when that is not a per-reference fact. `null` when `failed` already says everything there is to say."
+  }),
+  started_at: z3.iso.datetime().meta({
+    description: "When the sync started, as an ISO 8601 timestamp."
+  }),
+  updated_at: z3.iso.datetime().meta({
+    description: "When this status last changed, as an ISO 8601 timestamp. A sync that stops moving is visible here rather than only in `state`."
+  })
 });
 var assetListResponse = z3.object({
-  assets: z3.array(asset),
+  assets: z3.array(asset).meta({
+    description: "Every asset stored for this robot: the URDF, the meshes it references, and the textures those paint with."
+  }),
   /**
    * Der gerade laufende Sync, oder `null` (W9b, DEF-147).
    *
@@ -716,8 +777,12 @@ var assetListResponse = z3.object({
    * die id nicht aufgehoben hatte. Eine Seite, die frisch lädt, drückt keinen
    * Knopf; sie fragt diese Liste. Also muss die Liste es sagen.
    */
-  active_sync: assetSyncStatus.nullable(),
-  urdf: urdfCompleteness,
+  active_sync: assetSyncStatus.nullable().meta({
+    description: "The sync running right now, or `null`. It is on this list so a page that reloads and has lost the sync id can still show progress \u2014 a freshly loaded page presses no button, it asks this list."
+  }),
+  urdf: urdfCompleteness.meta({
+    description: "Whether the stored URDF can actually be rendered, and what it is still missing. Not the same question as whether one was uploaded."
+  }),
   /**
    * What the connected bridge says it *could* transfer, which is deliberately
    * separate from what has been transferred (§4.6: the bridge "meldet nur
@@ -745,7 +810,9 @@ var assetListResponse = z3.object({
    * Rosie-W7a closing it, and this comment was still describing the gap a wave
    * after it was fixed (Momus-W7a, W7a review).
    */
-  urdf_available: z3.boolean().nullable()
+  urdf_available: z3.boolean().nullable().meta({
+    description: 'What the connected bridge says it *could* transfer, which is deliberately separate from what has been transferred. `null` when no bridge is connected \u2014 distinct from `false`, because "no robot is online to ask" and "the robot has no URDF" send a developer to two different places. After a publisher is killed rather than shut down this can read `true` for some seconds, on the underlying DDS liveliness timeout rather than on any check made here.'
+  })
 });
 var assetSyncBusyDetails = z3.object({
   sync_id: z3.uuid(),
@@ -753,10 +820,10 @@ var assetSyncBusyDetails = z3.object({
   started_at_ms: z3.number().int().nonnegative()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/config.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/config.js
 import { z as z5 } from "zod";
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/alerts.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/alerts.js
 import { z as z4 } from "zod";
 var alertRowCondition = z4.discriminatedUnion("kind", [
   z4.strictObject({
@@ -821,7 +888,7 @@ var putDatapointDisplayRequest = z4.object({
   y_max: z4.number().finite().nullable()
 }).strict();
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/config.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/config.js
 var RTSP_URL_RULE = "The URL has to begin with `rtsp://` or `rtsps://` \u2014 `rtsp://cam-1.plant.local/stream1`. No other scheme is accepted: the bridge opens this with a library that would equally honour `file:`.";
 var MJPEG_URL_RULE = "The URL has to begin with `http://` or `https://` \u2014 `http://cam-1.plant.local/video.mjpg`. No other scheme is accepted: the bridge opens this with a library that would equally serve `file:`.";
 var DEVICE_PATH_RULE = "A capture device is a path under `/dev/`, and the character straight after it is a letter or a digit \u2014 `/dev/video0`, or a stable `/dev/v4l/by-id/...` symlink. Nothing outside `/dev/` is accepted: the string reaches OpenCV, which would as happily open an ordinary file.";
@@ -1876,7 +1943,7 @@ var configState = z5.object({
   applied_errors: z5.array(applyError).nullable()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/introspection.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/introspection.js
 import { z as z6 } from "zod";
 var rosGraphEntry = z6.object({
   name: rosName,
@@ -1915,16 +1982,26 @@ var typeDefinition = z6.discriminatedUnion("kind", [
   })
 ]);
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/jobs.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/jobs.js
 import { z as z7 } from "zod";
 var jobState = z7.enum(["running", "succeeded", "failed", "cancelled", "lost"]);
 var job = z7.object({
-  id: z7.uuid(),
-  robot_id: z7.uuid(),
-  slug,
-  state: jobState,
-  started_at: z7.iso.datetime(),
-  updated_at: z7.iso.datetime(),
+  id: z7.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."
+  }),
+  robot_id: z7.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 \u2014 the bridge restarted mid-job and the result is gone \u2014 and is said out loud rather than left reading `running` because nobody contradicted it."
+  }),
+  started_at: z7.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."
+  }),
+  updated_at: z7.iso.datetime().meta({
+    description: "When this job last changed, as an ISO 8601 timestamp."
+  }),
   /**
    * A monotonic counter, ascending in mint order (W7), and the **named**
    * tiebreaker for any listing that claims an order.
@@ -1941,9 +2018,12 @@ var job = z7.object({
    * orders jobs that coexist in one registry — and stated, because a reader
    * who assumed `auditEvent.seq`'s durable semantics would be wrong.
    */
-  seq: z7.number().int().positive(),
-  /** Present once the job succeeded; shape is the ROS result's. */
-  result: z7.unknown().nullable(),
+  seq: z7.number().int().positive().meta({
+    description: "A monotonic counter ascending in mint order, and the named tiebreaker for any listing that claims one \u2014 `started_at` alone is not a total order. Scoped per cloud process and per run: job state lives in memory, so this restarts with the registry it orders."
+  }),
+  result: z7.unknown().nullable().meta({
+    description: "What the call returned once it succeeded, shaped by the ROS action or service itself. `null` until then, and for a job that did not succeed."
+  }),
   /**
    * Present on `failed`; a human message, plus a code where one exists.
    *
@@ -1962,10 +2042,18 @@ var job = z7.object({
    * `jobQueueFullDetails` — it belongs here, not in the sentence.
    */
   error: z7.object({
-    code: z7.string().min(1),
-    message: z7.string().min(1),
-    details: z7.unknown().optional()
-  }).nullable()
+    code: z7.string().min(1).meta({
+      description: "A machine-readable code for the failure, such as `job_queue_full`, where one exists for it."
+    }),
+    message: z7.string().min(1).meta({
+      description: "A human-readable sentence saying what went wrong."
+    }),
+    details: z7.unknown().optional().meta({
+      description: "The structured payload belonging to `code`, for the codes that document one \u2014 `job_queue_full` carries its `limit` and its `queued` count here. Absent for a failure with nothing structured to add, which is most of them."
+    })
+  }).nullable().meta({
+    description: "Why the job failed: a human `message`, a `code` where one exists, and `details` for the codes that carry a documented payload. `null` unless `state` is `failed`."
+  })
 });
 var jobEvent = z7.object({
   type: z7.literal("job"),
@@ -1995,66 +2083,118 @@ var jobQueueFullDetails = z7.object({
 });
 var JOB_RUN_PAGE_MAX = 200;
 var jobActor = z7.object({
-  kind: z7.enum(["developer", "end_user", "server_key"]),
-  id: z7.uuid(),
+  kind: z7.enum(["developer", "end_user", "server_key"]).meta({
+    description: "What the caller was acting as: a `developer` in the console, an `end_user` of an app, or a `server_key` used by server-side code. A bridge invokes nothing, so it is deliberately not a case here."
+  }),
+  id: z7.uuid().meta({
+    description: "The id of the developer, end user or server key that invoked the run."
+  }),
   /**
    * The email for a developer or end user, the key's `name` for a server key.
    * A display snapshot taken at invoke time: renaming a key afterwards does not
    * rewrite history, which is the point of storing it rather than joining.
    */
-  label: z7.string().min(1).max(200)
+  label: z7.string().min(1).max(200).meta({
+    description: "A display name taken at invoke time \u2014 the email for a developer or end 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."
+  })
 });
 var jobRunKind = z7.enum(["action", "service"]);
 var jobRun = z7.object({
-  id: z7.uuid(),
-  robot_id: z7.uuid(),
-  slug,
-  kind: jobRunKind,
-  state: jobState,
-  started_at: z7.iso.datetime(),
-  /** `null` while `running` — a run has an end only once it has one. */
-  ended_at: z7.iso.datetime().nullable(),
-  /** `null` while `running`. Not "0 so far". */
-  duration_ms: z7.number().int().nonnegative().nullable(),
-  result: z7.unknown().nullable(),
-  error: z7.object({ code: z7.string().min(1), message: z7.string().min(1), details: z7.unknown().optional() }).nullable(),
-  actor: jobActor,
+  id: z7.uuid().meta({
+    description: "The run's id, which is the same id the invocation was answered with \u2014 so a caller that kept a job id can find its durable record here later."
+  }),
+  robot_id: z7.uuid().meta({ description: "The robot the run happened on." }),
+  slug: slug.meta({
+    description: "The action or service that was invoked, as the published configuration exposed it at the time."
+  }),
+  kind: jobRunKind.meta({
+    description: "Whether the slug was an `action` or a `service`."
+  }),
+  state: jobState.meta({
+    description: "How the run ended, or `running` while it is still going. `lost` means the bridge restarted mid-run and the outcome is unknowable rather than unknown."
+  }),
+  started_at: z7.iso.datetime().meta({
+    description: "When the run started, as an ISO 8601 timestamp. Runs are listed and filtered by this instant."
+  }),
+  ended_at: z7.iso.datetime().nullable().meta({
+    description: "When the run finished, as an ISO 8601 timestamp. `null` while it is still `running` \u2014 a run has an end only once it has one."
+  }),
+  duration_ms: z7.number().int().nonnegative().nullable().meta({
+    description: 'How long the run took, in milliseconds. `null` while it is still `running`, never `0` standing in for "nothing so far".'
+  }),
+  result: z7.unknown().nullable().meta({
+    description: "What the action or service returned once it succeeded, shaped by ROS itself. `null` otherwise."
+  }),
+  error: z7.object({
+    code: z7.string().min(1).meta({
+      description: "A machine-readable code for the failure, such as `job_queue_full`, where one exists for it."
+    }),
+    message: z7.string().min(1).meta({
+      description: "A human-readable sentence saying what went wrong."
+    }),
+    details: z7.unknown().optional().meta({
+      description: "The structured payload belonging to `code`, for the codes that document one. Absent for a failure with nothing structured to add."
+    })
+  }).nullable().meta({
+    description: "Why the run failed \u2014 a `message`, a `code` where one exists, and the structured `details` some codes carry. `null` unless it failed."
+  }),
+  actor: jobActor.meta({
+    description: "Who invoked the run, and what they were acting as at the time."
+  }),
   /**
    * **Durable, unlike `job.seq`.** That one is a per-process counter that
    * restarts with the cloud; this is a postgres `bigserial` and is the cursor
    * `before_seq` walks.
    */
-  seq: z7.number().int().positive(),
-  /**
-   * Live-only, read from the in-memory registry for rows that are still
-   * running. `null` means **"not known right now"** — after a cloud restart,
-   * before the bridge reconnects — and never "0 %". A fraction, as in
-   * `jobEvent.progress`, not a percentage.
-   */
-  progress: z7.number().min(0).max(1).nullable(),
-  feedback: z7.unknown().nullable()
+  seq: z7.number().int().positive().meta({
+    description: "The durable cursor this history is ordered and paged by. Unlike `job.seq` it does not restart when the cloud does; it is the value a caller sends back as `before_seq`."
+  }),
+  progress: z7.number().min(0).max(1).nullable().meta({
+    description: 'How far a still-running run has got, as a fraction from `0` to `1`, read live from the in-memory registry. `null` means **not known right now** \u2014 after a cloud restart, before the bridge reconnects \u2014 and never a `0` standing in for "no progress yet".'
+  }),
+  feedback: z7.unknown().nullable().meta({
+    description: "The most recent action feedback for a run that is still running, shaped by the ROS action. Live-only, so it is `null` for every settled run and whenever the registry has nothing."
+  })
 });
 var jobRunQuery = z7.object({
-  /** Only runs with a smaller `seq` — the next, older page. */
-  before_seq: wireSeqCursor.optional(),
-  limit: z7.union([z7.string().regex(/^\d{1,4}$/), z7.number().int()]).transform((v) => Number(v)).pipe(z7.number().int().positive().max(JOB_RUN_PAGE_MAX)).optional(),
-  robot_id: z7.uuid().optional(),
-  slug: slug.optional(),
-  state: jobState.optional(),
-  kind: jobRunKind.optional(),
-  /** Half-open `[from, to)`, the same rule the history shapes follow (DEF-062). */
-  from_ms: wireTimestampMs.optional(),
-  to_ms: wireTimestampMs.optional()
+  before_seq: wireSeqCursor.optional().meta({
+    description: "Return only runs with a `seq` below this value \u2014 the next, older page. Send back the `next_cursor` of the previous response rather than computing one."
+  }),
+  limit: z7.union([z7.string().regex(/^\d{1,4}$/), z7.number().int()]).transform((v) => Number(v)).pipe(z7.number().int().positive().max(JOB_RUN_PAGE_MAX)).optional().meta({
+    description: "How many runs to return, from `1` to `200`. Absent means `100`. It arrives on the query string, so a numeric string and a number are both accepted."
+  }),
+  robot_id: z7.uuid().optional().meta({
+    description: "Only runs on this robot. Absent means every robot in the organisation."
+  }),
+  slug: slug.optional().meta({
+    description: "Only runs of this action or service."
+  }),
+  state: jobState.optional().meta({
+    description: "Only runs in this state \u2014 `running`, `succeeded`, `failed`, `cancelled` or `lost`."
+  }),
+  kind: jobRunKind.optional().meta({
+    description: "Only `action` runs, or only `service` runs."
+  }),
+  from_ms: wireTimestampMs.optional().meta({
+    description: "Only runs that started at or after this unix timestamp in milliseconds. Together with `to_ms` the window is half-open, `[from, to)`, so adjacent windows tile without counting a run twice."
+  }),
+  to_ms: wireTimestampMs.optional().meta({
+    description: "Only runs that started **before** this unix timestamp in milliseconds. The window is half-open, so a run starting exactly on `to_ms` belongs to the next one."
+  })
 }).strict();
 var jobRunListResponse = z7.object({
-  runs: z7.array(jobRun),
+  runs: z7.array(jobRun).meta({
+    description: "This page of runs, newest first by `seq`. Empty means the filter matched nothing, not that the history is gone."
+  }),
   /**
    * The `seq` a caller sends as `before_seq` to keep reading — or `null` when
    * there is nothing further. **`null` means the end, and that is a promise
    * rather than an observation.** A caller who instead compares `runs.length`
    * against `limit` is wrong the moment a filter makes a page thin.
    */
-  next_cursor: z7.number().int().positive().nullable()
+  next_cursor: z7.number().int().positive().nullable().meta({
+    description: "The `seq` to send as `before_seq` to keep reading, or `null` when there is nothing further. **`null` is a promise, not an observation** \u2014 a caller who instead compares the page length against `limit` is wrong the moment a filter makes a page thin."
+  })
 });
 var jobRunSummaryQuery = z7.object({ since_ms: wireTimestampMs }).strict();
 var jobRunSummary = z7.object({
@@ -2064,7 +2204,7 @@ var jobRunSummary = z7.object({
   since_ms: z7.number().int().nonnegative()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/protocol.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/protocol.js
 var MAX_PATIENCE_MS = 12e4;
 var MIN_PATIENCE_MS = 1e3;
 var activeJob = z8.object({
@@ -2483,11 +2623,11 @@ var bridgeCameraState = z8.object({
   request_id: z8.string().min(1).max(64).nullable()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/config-issues.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/config-issues.js
 var EXPOSURE_SECTIONS = ["datapoints", "actions", "services", "publishers", "cameras"];
 var EXPOSURE_SECTION_NAMES = new Set(EXPOSURE_SECTIONS);
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/rest.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/rest.js
 import { z as z9 } from "zod";
 var robot = z9.object({
   id: z9.uuid(),
@@ -2519,9 +2659,13 @@ var robotListResponse = z9.object({
   robots: z9.array(robotListItem)
 });
 var datapointValue = z9.object({
-  slug,
-  value: z9.unknown(),
-  timestamp_ms: z9.number().int().nonnegative()
+  slug: slug.meta({ description: "The datapoint this value belongs to." }),
+  value: z9.unknown().meta({
+    description: "The value itself, shaped by the datapoint: a number, a boolean, a string, or the whole ROS message where the configuration names no field inside it. Any `scale` and `offset` the configuration declares have already been applied, at the robot."
+  }),
+  timestamp_ms: z9.number().int().nonnegative().meta({
+    description: "When the value was captured, as a unix timestamp in milliseconds. This is the **bridge's capture time**, never the time the cloud received it \u2014 the one exception is the built-in `bridge_state`, which the cloud observes by construction."
+  })
 });
 var robotDetailResponse = z9.object({
   ...robotListItem.shape,
@@ -2577,9 +2721,13 @@ var fetchTypesResponse = z9.object({
   unresolved: z9.array(z9.string())
 });
 var datapointDescriptor = z9.object({
-  slug,
-  builtin: z9.boolean(),
-  unit: z9.string().nullable(),
+  slug: slug.meta({ description: "The name a client reads this datapoint by." }),
+  builtin: z9.boolean().meta({
+    description: "`true` for the datapoints every robot has \u2014 `bridge_state`, `robot_details` and `bridge_pressure` \u2014 and `false` for everything the published configuration adds."
+  }),
+  unit: z9.string().nullable().meta({
+    description: "The unit the value carries **after** any scale and offset, shown beside the number so nobody has to guess whether `15` means percent, volts or minutes. `null` when the configuration names none."
+  }),
   /**
    * `null` for a built-in and for a datapoint published with no throttle —
    * the same "no ceiling configured" fact `datapointConfig.rate_throttle_hz`
@@ -2587,15 +2735,21 @@ var datapointDescriptor = z9.object({
    * optional because this shape is a read response, not a document a caller
    * writes. Reuses `rateThrottleHz` so the 20 Hz ceiling is written once.
    */
-  rate_throttle_hz: rateThrottleHz.nullable()
+  rate_throttle_hz: rateThrottleHz.nullable().meta({
+    description: "The ceiling on how often this datapoint is sent, in hertz. `null` means no ceiling is configured, which is also the answer for every built-in. A ceiling, not a clock: a slow topic stays slow and no value is repeated to manufacture a rate."
+  })
 });
 var datapointListResponse = z9.object({
-  datapoints: z9.array(datapointDescriptor)
+  datapoints: z9.array(datapointDescriptor).meta({
+    description: "Everything a client may read on this robot: the three built-ins, plus every datapoint the published configuration exposes and the caller's role grants."
+  })
 });
 var robotDetailsDoc = z9.record(z9.string().regex(/^[a-z][a-z0-9_-]{0,63}$/), z9.union([z9.string().max(4096), z9.number(), z9.boolean(), z9.array(z9.unknown()), z9.record(z9.string(), z9.unknown())]));
 var putRobotDetailsRequest = z9.object({ details: robotDetailsDoc });
 var invokeRequest = z9.object({
-  params: z9.record(z9.string(), z9.unknown()),
+  params: z9.record(z9.string(), z9.unknown()).meta({
+    description: "The values this call needs, keyed by **parameter name** rather than by field path \u2014 so a name survives the field moving inside the message. Every parameter without a default must be present, and the bounds the configuration declares are enforced in the cloud, before anything reaches the robot."
+  }),
   /**
    * How long **this call** is worth waiting for, in milliseconds (W6b).
    *
@@ -2622,31 +2776,52 @@ var invokeRequest = z9.object({
    * *acceptance* — once a goal is accepted the job runs as long as it runs,
    * and is observed, not awaited.
    */
-  patience_ms: z9.number().int().min(MIN_PATIENCE_MS).max(MAX_PATIENCE_MS).optional()
+  patience_ms: z9.number().int().min(MIN_PATIENCE_MS).max(MAX_PATIENCE_MS).optional().meta({
+    description: "How long **this call** is worth waiting for, in milliseconds; absent means the platform default. The number travels to the robot too, so one deadline governs both sides. Above the maximum the call is refused rather than quietly clamped, because a caller given less than they asked for would read the timeout as the robot's failure."
+  })
 });
 var cancelRequest = z9.object({
-  job_id: z9.uuid().nullable().optional()
+  job_id: z9.uuid().nullable().optional().meta({
+    description: "The one job to stop. Absent or `null` cancels whatever is currently running on the slug, which is what every caller written before this field existed means. Unknown keys are refused rather than stripped, so a misspelling cannot silently become the slug-wide cancel."
+  })
 }).strict();
 var releaseLiveQuery = z9.object({
-  session_id: z9.uuid().optional()
+  session_id: z9.uuid().optional().meta({
+    description: "The one hold to release, as the live session returned it. Absent releases **all** of this identity's holds on this camera \u2014 the blunt form, still needed by a client that has lost its id or is going away, and the one that strands the identity's other tabs."
+  })
 }).strict();
 var invokeResponse = z9.object({
-  job,
+  job: job.meta({
+    description: "The job that now exists on this slug. It is returned as soon as the goal is accepted, so `state` is `running` here \u2014 the outcome is observed afterwards, by slug, over polling or a subscription."
+  }),
   /** The slug's kind — see `commandResult.kind` for why the caller needs it. */
-  kind: z9.enum(["action", "service"])
+  kind: z9.enum(["action", "service"]).meta({
+    description: "Always `action` in this shape. A caller sends the same request for both kinds and cannot tell from a role grant which it invoked, so the answer says which it was rather than leaving it to be inferred from the shape."
+  })
 });
 var serviceCallResponse = z9.object({
-  result: z9.unknown()
+  result: z9.unknown().meta({
+    description: "What the service returned, shaped by the ROS service itself. A service call is awaited to completion, so there is no job to observe afterwards and no id to hold on to."
+  })
 });
+var invokeOrServiceResponse = z9.union([invokeResponse, serviceCallResponse]);
 var publishRequest = z9.object({
-  message: z9.record(z9.string(), z9.unknown())
+  message: z9.record(z9.string(), z9.unknown()).meta({
+    description: "The values to publish, keyed by the **parameter names** the publisher declares \u2014 the same flat form an invoke takes for `params`. They are checked against the declared bounds in the cloud before anything reaches the robot, and a slug another caller is still holding is refused with the remaining wait."
+  })
+});
+var jobResponse = z9.object({
+  job: job.nullable().meta({
+    description: "The **most recent** job on this slug, running or already finished, and `null` only when nothing has ever run there. Read `state` to tell a live job from a settled one: a route that forgot a job the moment it settled would let a poller see `running` and then nothing."
+  })
 });
-var jobResponse = z9.object({ job: job.nullable() });
 var rateLimitDetails = z9.object({
   retry_after_ms: z9.number().int().nonnegative()
 });
 var robotJobsResponse = z9.object({
-  jobs: z9.array(job)
+  jobs: z9.array(job).meta({
+    description: "At most one entry per slug \u2014 the current job there \u2014 ordered newest **known** first, and never `null`: a robot doing nothing answers an empty array. This is not a history endpoint. For an adopted job `started_at` is adoption time, so a job that has been running for an hour can sit above one started a minute ago."
+  })
 });
 var exposure = z9.object({
   slug,
@@ -2663,10 +2838,16 @@ var SNAPSHOT_HEADERS = {
   height: "x-fleetless-height"
 };
 var cameraDescriptor = z9.object({
-  slug,
-  width: z9.number().int().positive(),
-  height: z9.number().int().positive(),
-  fps: z9.number().int().positive(),
+  slug: slug.meta({ description: "The name a client addresses this camera by." }),
+  width: z9.number().int().positive().meta({
+    description: "Frame width in pixels, as the published configuration declares it."
+  }),
+  height: z9.number().int().positive().meta({
+    description: "Frame height in pixels, as the published configuration declares it."
+  }),
+  fps: z9.number().int().positive().meta({
+    description: "How many frames per second the camera is configured to publish while somebody is watching live."
+  }),
   /**
    * Seconds, as the document spells it, reusing `snapshotIntervalSeconds` so
    * the 1–3600 bound is written once. It was `snapshot_interval_ms` after the
@@ -2674,9 +2855,15 @@ var cameraDescriptor = z9.object({
    * this descriptor and not on `datapointDescriptor` beside it — the same
    * drift `rateThrottleHz` was extracted to stop.
    */
-  snapshot_interval_seconds: snapshotIntervalSeconds
+  snapshot_interval_seconds: snapshotIntervalSeconds.meta({
+    description: "How often a still frame is captured for the cheap snapshot reads, in seconds, between `1` and `3600`. Independent of `fps`, which is about live video."
+  })
+});
+var cameraListResponse = z9.object({
+  cameras: z9.array(cameraDescriptor).meta({
+    description: "Every camera the published configuration exposes on this robot **and** the caller's role grants. A developer sees all of them; an end user sees what their role allows."
+  })
 });
-var cameraListResponse = z9.object({ cameras: z9.array(cameraDescriptor) });
 var liveSessionResponse = z9.object({
   /**
    * This viewer's hold, and the **only** thing `DELETE` should be given
@@ -2695,29 +2882,56 @@ var liveSessionResponse = z9.object({
    * is going away entirely, still needs a way to let go. It is the blunt
    * form, and it is the one that strands other tabs; new callers pass the id.
    */
-  session_id: z9.uuid(),
-  url: z9.string().min(1),
-  room: z9.string().min(1),
-  token: z9.string().min(1),
-  expires_at: z9.iso.datetime()
+  session_id: z9.uuid().meta({
+    description: "This viewer's hold, and the only thing a release should be given. Two tabs of one logged-in user are two holds; releasing without an id lets go of both and leaves the other tab rendering a stream the robot has already stopped producing."
+  }),
+  url: z9.string().min(1).meta({
+    description: "The LiveKit server to connect to, as a WebSocket URL."
+  }),
+  room: z9.string().min(1).meta({
+    description: "The LiveKit room carrying this camera. Every viewer of one camera on one robot joins the same room, which is what makes the refcount hold meaningful."
+  }),
+  token: z9.string().min(1).meta({
+    description: "The LiveKit access token to join `room` with. It is checked when the participant connects and **not again afterwards** \u2014 which is not the same as irrevocable: the cloud can still disconnect a participant after the fact, and does when membership, a role or a key changes."
+  }),
+  expires_at: z9.iso.datetime().meta({
+    description: "The deadline for **joining**, as an ISO 8601 timestamp \u2014 not a session backstop. A viewer who has already joined keeps receiving video past this moment, so cleanup belongs in an explicit release, never in a timer built on this value."
+  })
 });
 var snapshotMetaResponse = z9.object({
-  slug,
-  timestamp_ms: z9.number().int().nonnegative().nullable(),
-  age_ms: z9.number().int().nonnegative().nullable(),
-  width: z9.number().int().positive().nullable(),
-  height: z9.number().int().positive().nullable(),
-  mime: z9.string().nullable()
+  slug: slug.meta({ description: "The camera this snapshot belongs to." }),
+  timestamp_ms: z9.number().int().nonnegative().nullable().meta({
+    description: "When the stored frame was captured, as a unix timestamp in milliseconds. `null` means nothing has been captured yet, which is an answer rather than an error."
+  }),
+  age_ms: z9.number().int().nonnegative().nullable().meta({
+    description: "How old the stored frame is right now, in milliseconds; `null` when there is none. Snapshots are deliberately cheap and therefore deliberately old, and a cached frame served without its age is indistinguishable from a live one."
+  }),
+  width: z9.number().int().positive().nullable().meta({
+    description: "Width of the stored frame in pixels, or `null` when nothing has been captured yet."
+  }),
+  height: z9.number().int().positive().nullable().meta({
+    description: "Height of the stored frame in pixels, or `null` when nothing has been captured yet."
+  }),
+  mime: z9.string().nullable().meta({
+    description: "The media type of the stored frame, such as `image/jpeg`, or `null` when nothing has been captured yet."
+  })
 });
 var historyQuery = z9.object({
-  from: z9.string().min(1).max(32),
-  /** Defaults to now. */
-  to: z9.string().min(1).max(32).optional(),
-  /** Bucket width, e.g. `10s`, `1m`. Absent means raw samples. */
-  window: z9.string().min(2).max(16).optional(),
-  agg: z9.enum(["min", "max", "avg"]).optional(),
-  /** A numeric field inside an object value, e.g. `pose.x` (§4.4 paths). */
-  field: z9.string().min(1).max(128).optional(),
+  from: z9.string().min(1).max(32).meta({
+    description: "The start of the window: either a relative expression \u2014 `now-30s`, `now-5m`, `now-1h` \u2014 or absolute unix milliseconds. A chart asks the first way and a report asks the second, and making a client convert would be making it guess our clock."
+  }),
+  to: z9.string().min(1).max(32).optional().meta({
+    description: "The end of the window, in the same two spellings as `from`; absent means now. The window is half-open, `[from, to)`, so a sample landing exactly on `to` belongs to the next window and adjacent windows tile without double-counting."
+  }),
+  window: z9.string().min(2).max(16).optional().meta({
+    description: "The bucket width, such as `10s` or `1m`. Absent means raw samples. It is meaningless without `agg`, and the pair is refused apart rather than defaulted \u2014 a silently chosen aggregation is a chart that lies quietly."
+  }),
+  agg: z9.enum(["min", "max", "avg"]).optional().meta({
+    description: "How each bucket reduces the samples inside it. Valid only together with `window`."
+  }),
+  field: z9.string().min(1).max(128).optional().meta({
+    description: "A dotted path to a numeric field inside an object value, such as `pose.x`. Without it the datapoint's value is used whole, which only works when it is already a number."
+  }),
   /**
    * **A union whose input branch IS the wire, not a coercion (W9d, DEF-059).**
    *
@@ -2758,13 +2972,28 @@ var historyQuery = z9.object({
     // that is arguably stronger: without it the artifact publishes the full
     // safe-integer range, which reads as *nine quadrillion is fine*.
     z9.number().int().describe("Positive integer, 1-10000. The ceiling is enforced after parsing, not by this type.")
-  ]).transform((v) => Number(v)).pipe(z9.number().int().positive().max(1e4)).optional()
+  ]).transform((v) => Number(v)).pipe(z9.number().int().positive().max(1e4)).optional().meta({
+    description: "The most samples or buckets to return, from `1` to `10000`. It arrives as text on the query string, so both a numeric string and a number are accepted; the ceiling is enforced after parsing rather than by the published shape."
+  })
 });
 var historySamplesResponse = z9.object({
-  slug,
-  kind: z9.literal("samples"),
-  samples: z9.array(z9.object({ timestamp_ms: z9.number().int().nonnegative(), value: z9.unknown() })),
-  truncated: z9.boolean(),
+  slug: slug.meta({ description: "The datapoint these samples belong to." }),
+  kind: z9.literal("samples").meta({
+    description: "Says this is the raw-sample shape, which the query asked for by omitting `window`. A client reads this rather than inspecting which fields arrived."
+  }),
+  samples: z9.array(z9.object({
+    timestamp_ms: z9.number().int().nonnegative().meta({
+      description: "When the sample was captured, as a unix timestamp in milliseconds. It is the **bridge's capture time** \u2014 the same instant the live value carried, so a recorded point and a live one sit on one axis without apology."
+    }),
+    value: z9.unknown().meta({
+      description: "The value as it was stored, shaped by the datapoint. A `field` in the query narrows a message down to one number; without one the whole stored value comes back."
+    })
+  })).meta({
+    description: "The samples in the queried window, oldest first. The window is half-open, `[from, to)`, so a sample landing exactly on `to` belongs to the next window."
+  }),
+  truncated: z9.boolean().meta({
+    description: "Whether the response was cut short. A short array that does not admit it is indistinguishable from a quiet period, and the two lead a developer to opposite conclusions."
+  }),
   /**
    * Why it was cut, `null` when it was not — because the two causes have
    * **different remedies** and a single boolean cannot tell them apart:
@@ -2783,15 +3012,25 @@ var historySamplesResponse = z9.object({
    * `required` in the JSON Schema artifacts, which is the contradiction this
    * project has now hit five times.
    */
-  truncated_by: z9.enum(["limit", "bytes"]).nullable()
+  truncated_by: z9.enum(["limit", "bytes"]).nullable().meta({
+    description: "Why it was cut, and `null` when it was not \u2014 the two causes have **different remedies** and one boolean cannot tell them apart. `limit` means too many rows, so raising `limit` helps. `bytes` means the rows are large, so raising `limit` changes nothing: narrow the range, or name a numeric `field` so whole messages are not carried."
+  })
 });
 var historyBucketsResponse = z9.object({
-  slug,
-  kind: z9.literal("buckets"),
-  window_ms: z9.number().int().positive(),
-  agg: z9.enum(["min", "max", "avg"]),
+  slug: slug.meta({ description: "The datapoint these buckets summarise." }),
+  kind: z9.literal("buckets").meta({
+    description: "Says this is the aggregated shape, which the query asked for by naming a `window`. A separate shape rather than the sample shape with nulls in it, so a client knows by type what it received rather than by inspection."
+  }),
+  window_ms: z9.number().int().positive().meta({
+    description: "The bucket width actually used, in milliseconds \u2014 the query's `window` resolved to a number, so a rendered chart can say what it is drawing without re-parsing the expression it sent."
+  }),
+  agg: z9.enum(["min", "max", "avg"]).meta({
+    description: "How each bucket reduced the samples inside it, echoed back from the query."
+  }),
   buckets: z9.array(z9.object({
-    bucket_start_ms: z9.number().int().nonnegative(),
+    bucket_start_ms: z9.number().int().nonnegative().meta({
+      description: "The instant this bucket opens, as a unix timestamp in milliseconds. Buckets are half-open and `window_ms` wide, so this one covers up to but not including `bucket_start_ms + window_ms`."
+    }),
     /**
      * The aggregate over this bucket's **numeric** samples — or `null` when
      * none of them were numeric, which is **not** the same as the bucket
@@ -2809,7 +3048,9 @@ var historyBucketsResponse = z9.object({
      * so the second row above was indistinguishable from the first and the
      * console rendered "empty — no samples" over live data.
      */
-    value: z9.number().nullable(),
+    value: z9.number().nullable().meta({
+      description: "The aggregate over this bucket's **numeric** samples, or `null` when none of them were numeric \u2014 which is **not** the same as the bucket being empty. `sample_count` separates those: `null` with a count of `0` is a gap a chart should draw as a break, `null` with a count above `0` is data that simply has no height."
+    }),
     /**
      * Every sample that landed in this bucket and inside the queried range,
      * whether or not it contributed to `value` — which is the point of the
@@ -2826,9 +3067,14 @@ var historyBucketsResponse = z9.object({
      *   and only in-range samples are counted. A low edge count is a
      *   boundary effect, not a quiet period.
      */
-    sample_count: z9.number().int().nonnegative()
-  }))
+    sample_count: z9.number().int().nonnegative().meta({
+      description: "Every sample that landed in this bucket and inside the queried range, whether or not it contributed to `value` \u2014 only a count of *all* samples can prove a bucket empty rather than merely unplottable. Two consequences: `value * sample_count` is **not** a sum, and on a first or last bucket the count reflects the range rather than the bucket, so a low edge count is a boundary effect and not a quiet period."
+    })
+  })).meta({
+    description: "The buckets covering the queried window, oldest first. A range and window that would produce more than `limit` buckets is refused before the query runs, because this shape carries no `truncated` field and a refusal is then the only honest answer."
+  })
 });
+var historyResponse = z9.union([historySamplesResponse, historyBucketsResponse]);
 var robotDeletionSummary = z9.object({
   /**
    * Datapoints, actions, services and publishers in the **published**
@@ -3125,13 +3371,13 @@ var slugUsageResponse = z9.object({
   alert_count: z9.number().int().nonnegative()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/realtime.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/realtime.js
 import { z as z12 } from "zod";
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/client-auth.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/client-auth.js
 import { z as z11 } from "zod";
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/apps.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/apps.js
 import { z as z10 } from "zod";
 var appIdentifier = slug;
 var app = z10.object({
@@ -3327,33 +3573,53 @@ var brandingConfig = z10.object({
   footer_text: z10.string().min(1).max(200).optional()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/client-auth.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/client-auth.js
 var clientLoginRequest = z11.object({
-  app_identifier: appIdentifier,
-  email: z11.email(),
-  password: z11.string().min(1)
+  app_identifier: appIdentifier.meta({
+    description: "The app being logged in to, as its globally unique identifier \u2014 the lowercase, underscore-separated string the developer chose when the app was created. There is no organisation context at login, so this is what decides which app the credentials are checked for."
+  }),
+  email: z11.email().meta({
+    description: "The end user's email address. Addresses are global across Fleetless rather than per app, so one person is one identity however many apps they reach."
+  }),
+  password: z11.string().min(1).meta({
+    description: "The end user's password. A wrong pair is refused without saying which half was wrong, so a failed login is not an account-enumeration oracle."
+  })
 });
 var clientRefreshRequest = z11.object({
-  refresh_token: z11.string().min(1)
+  refresh_token: z11.string().min(1).meta({
+    description: "The refresh token from the last login or refresh. Refresh tokens rotate on every use, so the value sent here is spent \u2014 keep the one that comes back, and presenting a spent one is treated as theft and ends the whole family."
+  })
 });
 var clientLogoutRequest = z11.object({
-  refresh_token: z11.string().min(1)
+  refresh_token: z11.string().min(1).meta({
+    description: "Any refresh token of the session to end. The whole token family is revoked server-side, so a token stolen before this call stops working too \u2014 clearing a client-side store is a gesture, not a revocation."
+  })
 });
 var clientLogoutResponse = z11.object({
   idp_logout: z11.discriminatedUnion("status", [
     z11.object({
-      status: z11.literal("redirect"),
-      /** Send the browser here. Built from the IdP's own `end_session_endpoint`. */
-      url: z11.url().max(2e3)
+      status: z11.literal("redirect").meta({
+        description: "The identity provider publishes an `end_session_endpoint` and `url` says where to send the browser to finish logging out there."
+      }),
+      url: z11.url().max(2e3).meta({
+        description: "Send the browser here to end the session at the identity provider. Built from the provider's own `end_session_endpoint`."
+      })
+    }),
+    z11.object({
+      status: z11.literal("not_federated").meta({
+        description: "This session did not come from an identity provider, so there is no second session and nothing further to do."
+      })
     }),
-    /** This session did not come from an IdP — there is nothing else to end. */
-    z11.object({ status: z11.literal("not_federated") }),
     /**
      * It did, and the IdP's discovery document names no `end_session_endpoint`
      * (RP-initiated logout is optional in OIDC). **The IdP session survives and
      * this platform cannot end it** — say so rather than implying success.
      */
-    z11.object({ status: z11.literal("unsupported_by_idp") }),
+    z11.object({
+      status: z11.literal("unsupported_by_idp").meta({
+        description: "The session was federated and the provider's discovery document names no `end_session_endpoint`, which OpenID Connect leaves optional. **The provider session survives and Fleetless cannot end it.**"
+      })
+    }),
     /**
      * **Federated, the IdP *can* end the session, and we cannot ask it to
      * (W9c, Nimbus-W9c's proposal).**
@@ -3378,7 +3644,11 @@ var clientLogoutResponse = z11.object({
      * to carry a fact no consumer can act on is how a contract grows keys
      * nobody reads.
      */
-    z11.object({ status: z11.literal("hint_unavailable") }),
+    z11.object({
+      status: z11.literal("hint_unavailable").meta({
+        description: "The session was federated, the provider *could* end it, and the `id_token_hint` needed to ask is not available. The provider session survives, as with `unsupported_by_idp` \u2014 the difference is that here the cause is on the Fleetless side."
+      })
+    }),
     /**
      * **The server does not know this session, so it can say nothing about an
      * IdP** (W9 review, Argus-W9; André, 2026-08-19).
@@ -3398,22 +3668,47 @@ var clientLogoutResponse = z11.object({
      * a `redirect` that is still worth following. Reading this as *"the user is
      * fully logged out"* is exactly the mistake a second logout invites.
      */
-    z11.object({ status: z11.literal("session_unknown") })
-  ])
+    z11.object({
+      status: z11.literal("session_unknown").meta({
+        description: "The token was unknown, already superseded, revoked or expired, so the server knows nothing about this session and claims nothing about a provider. Not the same as `not_federated`, and not a statement that the user is fully logged out."
+      })
+    })
+  ]).meta({
+    description: "What is left of the login at the identity provider, if one was involved. The Fleetless session is already over before this is computed, so it says only whether a second session survives and whether this platform can end it."
+  })
 });
 var clientIdentity = z11.object({
-  kind: z11.enum(["developer", "end_user", "server_key"]),
-  developer_id: z11.uuid().nullable(),
-  end_user_id: z11.uuid().nullable(),
-  server_key_id: z11.uuid().nullable(),
-  app_id: z11.uuid().nullable(),
-  role_id: z11.uuid().nullable(),
-  email: z11.email().nullable(),
-  /** Present only under impersonation — the real admin's user id (D4, `act`-claim). */
-  act: z11.object({ admin_user_id: z11.uuid() }).strict().optional()
+  kind: z11.enum(["developer", "end_user", "server_key"]).meta({
+    description: "Which of the three kinds of caller this is: a `developer` working through the console, an `end_user` holding a token from a client login, or a `server_key` used by server-side code. Stated outright rather than left to be inferred from which id happens to be set."
+  }),
+  developer_id: z11.uuid().nullable().meta({
+    description: "The developer behind this session, or `null` when `kind` is not `developer`."
+  }),
+  end_user_id: z11.uuid().nullable().meta({
+    description: "The end user behind this session, or `null` when `kind` is not `end_user`."
+  }),
+  server_key_id: z11.uuid().nullable().meta({
+    description: "The server key this session was authenticated with, or `null` when `kind` is not `server_key`."
+  }),
+  app_id: z11.uuid().nullable().meta({
+    description: "The app this session belongs to, and `null` for a developer \u2014 a developer is organisation-scoped and owns the configuration of every robot in the organisation rather than reaching one through an app."
+  }),
+  role_id: z11.uuid().nullable().meta({
+    description: "The role that decides what this caller may reach, and `null` for a developer. Roles are the only visibility filter: what a role does not grant does not exist for that user."
+  }),
+  email: z11.email().nullable().meta({
+    description: "The email of the developer or end user behind this session, and `null` for a server key, which is not a person."
+  }),
+  act: z11.object({
+    admin_user_id: z11.uuid().meta({
+      description: `The real admin's user id. Only the id travels; whoever renders the "you are acting as \u2026" banner resolves the name itself rather than trusting a second unverified one on the wire.`
+    })
+  }).strict().optional().meta({
+    description: "Present only under impersonation, naming the organisation admin who is actually driving. The rest of this shape describes the identity they are acting **as**; absence means an ordinary session with nobody delegating, which is not the same fact as an unknown actor."
+  })
 });
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/realtime.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/realtime.js
 var clientAuth = z12.object({
   type: z12.literal("auth"),
   token: z12.string().min(1)
@@ -3701,7 +3996,7 @@ var orgEventDropped = z12.object({
   dropped: z12.number().int().positive()
 }).strict();
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/identity.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/identity.js
 import { z as z13 } from "zod";
 var password = z13.string().min(12).max(256);
 var GROUP_NAME_MAX = 120;
@@ -3798,9 +4093,15 @@ var groupListResponse = z13.object({ groups: z13.array(orgGroup) });
 var orgUserListResponse = z13.object({ users: z13.array(orgUser) });
 var appAssignmentListResponse = z13.object({ assignments: z13.array(appAssignment) });
 var sessionTokens = z13.object({
-  access_token: z13.string().min(1),
-  refresh_token: z13.string().min(1),
-  expires_in: z13.number().int().positive()
+  access_token: z13.string().min(1).meta({
+    description: "The token to send as `Authorization: Bearer <token>` on every call. Short-lived: read `expires_in` rather than assuming a lifetime."
+  }),
+  refresh_token: z13.string().min(1).meta({
+    description: "The token that buys the next access token. It rotates on every use, so a value presented twice is detectable theft and ends the whole family."
+  }),
+  expires_in: z13.number().int().positive().meta({
+    description: "How long the access token stays valid, in **seconds** from now. Not a timestamp, and not milliseconds."
+  })
 });
 var refreshRequest = z13.object({ refresh_token: z13.string().min(1) });
 var signUpRequest = z13.object({
@@ -3900,8 +4201,12 @@ var tierRequiredDetails = z13.object({
   actual: orgAdminTier
 });
 var passwordChangeRequest = z13.object({
-  current_password: z13.string().min(1),
-  new_password: password
+  current_password: z13.string().min(1).meta({
+    description: "The password in use right now. It is required even though the session already proves identity: it is what makes a stolen *session* insufficient to take the *account*."
+  }),
+  new_password: password.meta({
+    description: "The replacement password. Every other session is revoked when it is accepted, while the session that made the change survives \u2014 logging somebody out of the tab they just used is indistinguishable from the change having failed."
+  })
 });
 var passwordResetRequest = z13.object({
   email: z13.email()
@@ -4026,7 +4331,7 @@ var authMeResponse = z13.object({ org, user: orgUser });
 var patchOrgRequest = z13.object({ name: z13.string().min(1).max(120) }).strict();
 var patchAuthMeRequest = z13.object({ display_name: z13.string().min(1).max(USER_DISPLAY_NAME_MAX).nullable() }).strict();
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/audit.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/audit.js
 import { z as z14 } from "zod";
 var auditActor = z14.object({
   kind: z14.enum(["developer", "end_user", "server_key", "bridge"]),
@@ -4173,7 +4478,7 @@ var auditListResponse = z14.object({
   next_cursor: z14.number().int().positive().nullable()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/errors.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/errors.js
 import { z as z15 } from "zod";
 var apiError = z15.object({
   code: z15.string().min(1),
@@ -4190,7 +4495,7 @@ var parameterInvalidDetails = z15.object({
   violations: z15.array(parameterViolation).min(1)
 });
 
-// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_1727a3f05719ef3ec49509ea01c84aa4/node_modules/@fleetless/contracts/dist/oauth.js
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/oauth.js
 import { z as z16 } from "zod";
 var oauthErrorCode = z16.enum([
   "invalid_request",
@@ -4266,68 +4571,149 @@ var oauthClient = z16.object({
   last_used_at: z16.iso.datetime().nullable()
 });
 var dynamicClientRegistrationRequest = z16.object({
-  client_name: z16.string().min(1).max(200),
-  redirect_uris: z16.array(redirectUri).min(1).max(20),
-  /** Accepted and echoed for conformance; this server issues only this pair. */
-  grant_types: z16.array(z16.enum(["authorization_code", "refresh_token"])).optional(),
-  response_types: z16.array(z16.enum(["code"])).optional(),
-  /** RFC 7591 allows `none` for public clients; OAuth 2.1 + PKCE is the defence. */
-  token_endpoint_auth_method: z16.enum(["none"]).optional(),
-  scope: z16.string().max(500).optional()
+  client_name: z16.string().min(1).max(200).meta({
+    description: 'The name the client calls itself. It is **not** vouched for by Fleetless and must never be rendered as if it were \u2014 a self-registered client chooses this string, and one has called itself *"Fleetless Official Helper"*.'
+  }),
+  redirect_uris: z16.array(redirectUri).min(1).max(20).meta({
+    description: "Where the authorization code may be returned. 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 `20` of them."
+  }),
+  grant_types: z16.array(z16.enum(["authorization_code", "refresh_token"])).optional().meta({
+    description: "Accepted and echoed back for conformance with RFC 7591. This server issues `authorization_code` and `refresh_token` and nothing else."
+  }),
+  response_types: z16.array(z16.enum(["code"])).optional().meta({
+    description: "Accepted and echoed back for conformance. `code` is the only response type OAuth 2.1 leaves, the implicit grant having been removed."
+  }),
+  token_endpoint_auth_method: z16.enum(["none"]).optional().meta({
+    description: "`none`, RFC 7591's value for a public client. There is no client secret to hold: mandatory PKCE is the defence."
+  }),
+  scope: z16.string().max(500).optional().meta({
+    description: "The scopes the client asks to be registered for, space-separated."
+  })
 }).strict();
 var dynamicClientRegistrationResponse = z16.object({
-  client_id: z16.string().min(1).max(200),
-  client_name: z16.string().min(1).max(200),
-  redirect_uris: z16.array(redirectUri),
-  grant_types: z16.array(z16.string()),
-  response_types: z16.array(z16.string()),
-  token_endpoint_auth_method: z16.literal("none"),
-  client_id_issued_at: z16.number().int().nonnegative(),
-  /** Seconds since the epoch, per RFC 7591. `0` would mean "never expires". */
-  client_secret_expires_at: z16.literal(0)
+  client_id: z16.string().min(1).max(200).meta({
+    description: "The identifier this client sends at the authorize and token endpoints. Opaque, and not the app identifier."
+  }),
+  client_name: z16.string().min(1).max(200).meta({
+    description: "The name the client registered under, echoed back. Chosen by the client and not vouched for by Fleetless."
+  }),
+  redirect_uris: z16.array(redirectUri).meta({
+    description: "The redirect URIs this registration was accepted for. A code is returned to one of these and nowhere else."
+  }),
+  grant_types: z16.array(z16.string()).meta({
+    description: "The grants this client may use: `authorization_code` and `refresh_token`."
+  }),
+  response_types: z16.array(z16.string()).meta({
+    description: "The response types this client may ask for: `code`."
+  }),
+  token_endpoint_auth_method: z16.literal("none").meta({
+    description: "`none` \u2014 this server registers public clients only, and PKCE rather than a secret is what protects the exchange."
+  }),
+  client_id_issued_at: z16.number().int().nonnegative().meta({
+    description: "When the registration was created, in seconds since the epoch, per RFC 7591."
+  }),
+  client_secret_expires_at: z16.literal(0).meta({
+    description: "Always `0`, which is RFC 7591's way of saying the client secret never expires \u2014 there is none. The **registration** itself does expire: a self-registered client that never completes a flow is an unauthenticated write somebody left behind."
+  })
 });
 var oauthTokenRequest = z16.discriminatedUnion("grant_type", [
   z16.object({
-    grant_type: z16.literal("authorization_code"),
-    code: z16.string().min(1).max(500),
-    redirect_uri: redirectUri,
-    client_id: z16.string().min(1).max(200),
-    code_verifier: z16.string().regex(/^[A-Za-z0-9\-._~]{43,128}$/, "code_verifier must be 43-128 unreserved characters (RFC 7636 \xA74.1)"),
-    resource: z16.url().optional()
+    grant_type: z16.literal("authorization_code").meta({
+      description: "This request exchanges the code from the authorize redirect for tokens."
+    }),
+    code: z16.string().min(1).max(500).meta({
+      description: "The authorization code from the redirect. It may be exchanged once."
+    }),
+    redirect_uri: redirectUri.meta({
+      description: "The same redirect URI the authorize request used. It is compared, not merely recorded."
+    }),
+    client_id: z16.string().min(1).max(200).meta({
+      description: "The client making the exchange, as registered."
+    }),
+    code_verifier: z16.string().regex(/^[A-Za-z0-9\-._~]{43,128}$/, "code_verifier must be 43-128 unreserved characters (RFC 7636 \xA74.1)").meta({
+      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 \xA74.1 \u2014 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: z16.url().optional().meta({
+      description: "The resource the token is being requested for, per RFC 8707. It becomes the token's audience, and a resource refuses a token whose audience names something else."
+    })
   }),
   z16.object({
-    grant_type: z16.literal("refresh_token"),
-    refresh_token: z16.string().min(1).max(500),
-    client_id: z16.string().min(1).max(200),
-    resource: z16.url().optional(),
-    /** RFC 6749 §6 — a refresh may narrow scope, never widen it. */
-    scope: z16.string().max(500).optional()
+    grant_type: z16.literal("refresh_token").meta({
+      description: "This request trades a refresh token for a fresh access token."
+    }),
+    refresh_token: z16.string().min(1).max(500).meta({
+      description: "The refresh token to spend. Refresh tokens rotate, and presenting one twice is treated as theft rather than as a retry."
+    }),
+    client_id: z16.string().min(1).max(200).meta({
+      description: "The client refreshing, as registered."
+    }),
+    resource: z16.url().optional().meta({
+      description: "The resource the successor token should be bound to, per RFC 8707. **Carry it forward**: a refresh that drops it mints a token with no audience, and the resource then refuses it one token lifetime after a login that worked, to somebody who did nothing wrong."
+    }),
+    scope: z16.string().max(500).optional().meta({
+      description: "A narrower scope for the successor token. RFC 6749 \xA76 lets a refresh narrow scope, never widen it."
+    })
   })
 ]);
 var oauthTokenResponse = z16.object({
-  access_token: z16.string().min(1),
-  token_type: z16.literal("Bearer"),
-  /** Seconds, per RFC 6749 §5.1 — not a timestamp, and not milliseconds. */
-  expires_in: z16.number().int().positive(),
-  refresh_token: z16.string().min(1).optional(),
-  scope: z16.string().max(500).optional()
+  access_token: z16.string().min(1).meta({
+    description: "The bearer token. It is the same token the client login mints \u2014 only the envelope differs, because an RFC-compliant client parses this one and knows nothing about Fleetless."
+  }),
+  token_type: z16.literal("Bearer").meta({
+    description: "`Bearer`. RFC 6749 \xA75.1 makes the value case-insensitive for a client reading it; this is the spelling this server emits."
+  }),
+  expires_in: z16.number().int().positive().meta({
+    description: "How long the access token is valid, in **seconds**, per RFC 6749 \xA75.1. Not a timestamp, and not milliseconds."
+  }),
+  refresh_token: z16.string().min(1).optional().meta({
+    description: "The refresh token, when one was issued. It rotates on every use."
+  }),
+  scope: z16.string().max(500).optional().meta({
+    description: "The scopes the issued token actually carries, space-separated."
+  })
 });
 var authorizationServerMetadata = z16.object({
-  issuer: z16.url(),
-  authorization_endpoint: z16.url(),
-  token_endpoint: z16.url(),
-  registration_endpoint: z16.url().optional(),
-  response_types_supported: z16.array(z16.literal("code")),
-  grant_types_supported: z16.array(z16.enum(["authorization_code", "refresh_token"])),
-  code_challenge_methods_supported: z16.array(codeChallengeMethod),
-  token_endpoint_auth_methods_supported: z16.array(z16.literal("none")),
-  scopes_supported: z16.array(z16.string()).optional()
+  issuer: z16.url().meta({
+    description: "The issuer identifier of this authorization server, per RFC 8414 \xA72. It is what a client checks a token's `iss` against."
+  }),
+  authorization_endpoint: z16.url().meta({
+    description: "The URL a client sends the user to in order to authorize."
+  }),
+  token_endpoint: z16.url().meta({
+    description: "The URL where a client exchanges an authorization code, or a refresh token, for tokens."
+  }),
+  registration_endpoint: z16.url().optional().meta({
+    description: "The URL where a client may register itself, per RFC 7591. Absent when the app does not accept dynamic clients."
+  }),
+  response_types_supported: z16.array(z16.literal("code")).meta({
+    description: "The response types this server offers: `code` only, the implicit grant being gone with OAuth 2.1."
+  }),
+  grant_types_supported: z16.array(z16.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."
+  }),
+  code_challenge_methods_supported: z16.array(codeChallengeMethod).meta({
+    description: "The PKCE challenge methods accepted: `S256` only. `plain` is not offered \u2014 a challenge equal to its verifier defends against nothing, and offering it would make a downgrade negotiable."
+  }),
+  token_endpoint_auth_methods_supported: z16.array(z16.literal("none")).meta({
+    description: "How a client authenticates at the token endpoint: `none`, the public-client method, with PKCE protecting the exchange."
+  }),
+  scopes_supported: z16.array(z16.string()).optional().meta({
+    description: "The scopes this server knows about, where it publishes a list."
+  })
 });
 var protectedResourceMetadata = z16.object({
-  resource: z16.url(),
-  authorization_servers: z16.array(z16.url()).min(1),
-  bearer_methods_supported: z16.array(z16.literal("header")),
-  scopes_supported: z16.array(z16.string()).optional()
+  resource: z16.url().meta({
+    description: "The resource identifier this document describes, per RFC 9728. A token whose audience names something else is rejected here rather than merely noted."
+  }),
+  authorization_servers: z16.array(z16.url()).min(1).meta({
+    description: "The authorization servers that may issue tokens for this resource. There is always at least one."
+  }),
+  bearer_methods_supported: z16.array(z16.literal("header")).meta({
+    description: "How a token may be presented: in the `Authorization` header only, never in a query parameter or a form field."
+  }),
+  scopes_supported: z16.array(z16.string()).optional().meta({
+    description: "The scopes this resource understands, where it publishes a list."
+  })
 });
 var consentGrant = z16.object({
   client_id: z16.string().min(1).max(200),
@@ -4338,23 +4724,41 @@ var consentGrant = z16.object({
   granted_at: z16.iso.datetime()
 });
 var consentGrantSummary = z16.object({
-  client_id: z16.string().min(1).max(200),
+  client_id: z16.string().min(1).max(200).meta({
+    description: "The client this grant is for, and what a revocation addresses. The names beside it are for reading; this is for acting."
+  }),
   /**
    * The client's own declared name. **Not trusted, and the console/page must
    * not render it as if Fleetless vouched for it** — a self-registered client
    * chooses this string, and W7c already measured what that buys: one called
    * itself *"Fleetless Official Helper"*.
    */
-  client_name: z16.string().min(1).max(200),
-  app_id: z16.uuid(),
-  app_name: z16.string().min(1).max(120),
-  role_id: z16.uuid(),
-  role_name: z16.string().min(1).max(120),
-  scope: z16.string().max(500),
-  granted_at: z16.iso.datetime()
+  client_name: z16.string().min(1).max(200).meta({
+    description: `The client's own declared name, carried so a user recognises what they consented to. **Not trusted**: a self-registered client chooses this string, and one has called itself *"Fleetless Official Helper"*.`
+  }),
+  app_id: z16.uuid().meta({
+    description: "The app the grant was given within. A consent recorded against a client alone would be reusable for a different app."
+  }),
+  app_name: z16.string().min(1).max(120).meta({
+    description: "The app's name as it stood on the consent screen."
+  }),
+  role_id: z16.uuid().meta({
+    description: "The role that tokens issued under this grant carry, and therefore the limit of what the client can reach."
+  }),
+  role_name: z16.string().min(1).max(120).meta({
+    description: "The role's name as it stood on the consent screen. A user consented to a sentence, and every noun in it is stored so the list can show the sentence again."
+  }),
+  scope: z16.string().max(500).meta({
+    description: "The scopes consented to, space-separated."
+  }),
+  granted_at: z16.iso.datetime().meta({
+    description: "When consent was given, as an ISO 8601 timestamp."
+  })
 });
 var consentGrantListResponse = z16.object({
-  grants: z16.array(consentGrantSummary).max(200),
+  grants: z16.array(consentGrantSummary).max(200).meta({
+    description: "The user's consent grants, **newest first** \u2014 this list exists to be revoked from, and the grant somebody came for is almost always the one they just gave. At most `200`; when there are more, `truncated` says so."
+  }),
   /**
    * **`true` heisst: es gibt mehr, und diese Antwort zeigt sie nicht** (W9
    * review, Argus-W9; DEF-151).
@@ -4377,11 +4781,17 @@ var consentGrantListResponse = z16.object({
    * sagt, was der Nutzer wissen muss — **hier fehlt etwas, frag jemanden** —
    * ohne einen Mechanismus zu versprechen, den es nicht gibt.
    */
-  truncated: z16.boolean()
+  truncated: z16.boolean().meta({
+    description: '`true` means there are more grants than this response shows. A short page is not a promise that the list is exhausted \u2014 and on the one list a user comes to **switch something off**, "I cannot see it" and "it does not exist" is the most expensive difference there is.'
+  })
 });
 var consentRevokeResponse = z16.object({
-  revoked: z16.boolean(),
-  tokens_revoked: z16.number().int().nonnegative()
+  revoked: z16.boolean().meta({
+    description: "Whether a grant actually matched and was ended. `false` means nothing matched, which a caller has to be able to tell from a successful revocation."
+  }),
+  tokens_revoked: z16.number().int().nonnegative().meta({
+    description: "How many refresh **families** were ended. Deliberately not a count of access tokens, which are stateless and short-lived \u2014 though every currently-valid one issued through this client for this user does stop working at once."
+  })
 });
 var oauthInteraction = z16.object({
   interaction_id: z16.string().min(1).max(200),
@@ -4430,24 +4840,20 @@ var OAUTH_PATHS = {
    */
   consent: "/oauth/consent",
   /**
-   * The two federation legs. **Server-owned redirect targets a client never
+   * The federation return leg. **A server-owned redirect target a client never
    * constructs** — the same category as `authorize`, `token` and `register`,
-   * and the reason they belong here rather than as literals.
-   *
-   * Kassandra-W7b found `/oauth/idp-start` written as a literal in
-   * `cloud/src/routes/oauth-federation.ts` **and** in
-   * `console/oauth-pages/login/src/App.vue` — two repos agreeing on a string
-   * with nothing shared between them. Worse than the `/idp` versus
-   * `/idp-config` mismatch this wave already met, because the console half
-   * ships as a **committed artifact**: the drift would survive a re-pin and an
-   * install, and the symptom is a federation button that navigates to a 404,
-   * invisible to both suites.
-   *
-   * `OAUTH_PATHS` was created in this wave with a doc comment citing W7a's
-   * five hand-written copies of `assetKind`. The rule was applied to `login`
-   * and `consent` and stopped there.
+   * and the reason it belongs here rather than as a literal.
+   *
+   * `OAUTH_PATHS` was created in W7b with a doc comment citing W7a's five
+   * hand-written copies of `assetKind`. The rule was applied to `login` and
+   * `consent` and stopped there.
+   *
+   * It once had a twin, `idpStart: '/oauth/idp-start'`, for the *outbound*
+   * leg. The cloud deleted that route — `/oauth/authorize` redirects to the
+   * IdP directly — and the entry stayed here for months, naming a path
+   * nothing served. Removed in FL-007; the cloud's route-manifest test is
+   * what keeps a second one from accumulating.
    */
-  idpStart: "/oauth/idp-start",
   idpCallback: "/oauth/idp-callback",
   /**
    * The console-built page the cloud serves from its own origin (see §3.4) —
@@ -4477,7 +4883,7 @@ var OAUTH_PATHS = {
    * role to preview or a user to sign in as. The page is **server-rendered by
    * the cloud from its own origin** — the console never builds it and never
    * hardcodes this path; the login page merely follows the `redirect_to` it is
-   * handed. It belongs in this list for the reason `idpStart`/`idpCallback` do:
+   * handed. It belongs in this list for the reason `idpCallback` does:
    * a server-owned target a client is sent to, which must have exactly one
    * definition rather than a literal in `cloud/src/routes/oauth.ts` that a
    * second reader could drift from.
@@ -4485,6 +4891,3021 @@ var OAUTH_PATHS = {
   impersonate: "/oauth/impersonate"
 };
 
+// node_modules/.pnpm/@fleetless+contracts@git+ssh+++git@gitlab.dehne-robotik.de+fleetless+fleetless-contract_caf295a2dfcb59061dae71fef9f47725/node_modules/@fleetless/contracts/dist/routes.js
+var DEVELOPER_GUARD = ["unauthorized", "token_expired", "token_revoked", "forbidden"];
+var CLIENT_GUARD = ["unauthorized", "token_expired", "token_revoked", "forbidden"];
+var ROUTES = [
+  /* ------------------------------------------------------------- health */
+  {
+    method: "GET",
+    path: "/healthz",
+    section: "health",
+    summary: "Reports whether the database, the object store and LiveKit each answered a probe.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: "Answers `{ ok, dependencies: { database, storage, liveKit } }` \u2014 a cloud-local shape, not a wire contract, so nothing here pins it. The status is always `200`: each dependency is probed independently and a failure is reported in the body rather than thrown, because `/healthz` must never itself be a reason the process looks down. Read `ok`, not the status code."
+  },
+  /* ----------------------------------------------------- developer auth */
+  {
+    method: "POST",
+    path: "/api/auth/signup",
+    section: "developer-auth",
+    summary: "Creates an org, its Org Admins group and the founding Owner, and answers a developer session.",
+    audience: "developer",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 201,
+    params: [],
+    query: null,
+    request: signUpRequest,
+    response: signUpResponse,
+    errors: ["rate_limited", "signup_closed", "validation_error", "email_taken"],
+    transport: "http",
+    notes: "While the deployment runs in closed beta this answers `403 signup_closed` before it looks at the body \u2014 there is nothing for a validation message, or an `email_taken` answer, to be right about when nothing will be created. Email is globally unique, so an address already registered in any org is refused."
+  },
+  {
+    method: "POST",
+    path: "/api/auth/refresh",
+    section: "developer-auth",
+    summary: "Rotates a developer refresh token and mints a fresh access token.",
+    audience: "developer",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: refreshRequest,
+    response: sessionTokens,
+    errors: ["rate_limited", "validation_error", "token_expired", "token_revoked"],
+    transport: "http",
+    notes: "The whole family is re-checked here, not just the token: an account that has left the Org Admins group cannot mint a fresh console token, and answers `token_revoked`. Refusing that only on the other routes would leave a session that is dead everywhere but here."
+  },
+  {
+    method: "POST",
+    path: "/api/auth/logout",
+    section: "developer-auth",
+    summary: "Revokes the whole refresh family behind a developer refresh token.",
+    audience: "developer",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 204,
+    params: [],
+    query: null,
+    request: refreshRequest,
+    response: null,
+    errors: ["rate_limited", "validation_error"],
+    transport: "http",
+    notes: "Unauthenticated by design \u2014 the refresh token in the body is the credential. A token the server does not recognise is still a `204`: the end state a caller asked for is the end state they get, and distinguishing the two would say whether a token ever existed. Open `/realtime` sockets for the session are closed too."
+  },
+  {
+    method: "GET",
+    path: "/api/auth/me",
+    section: "developer-auth",
+    summary: "Answers the calling developer and the org they belong to.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: authMeResponse,
+    errors: [...DEVELOPER_GUARD],
+    transport: "http"
+  },
+  {
+    method: "PATCH",
+    path: "/api/auth/me",
+    section: "developer-auth",
+    summary: "Changes the calling developer's own display name and nothing else.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: patchAuthMeRequest,
+    response: authMeResponse,
+    errors: [...DEVELOPER_GUARD, "validation_error"],
+    transport: "http",
+    notes: "No Owner tier: this can only ever touch the caller's own row, so there is nothing for a tier check to gate. Saving the name already held writes nothing and records no audit event \u2014 the org activity stream reaches every developer with the console open, and an event for a no-op would misreport that something changed."
+  },
+  {
+    method: "POST",
+    path: "/api/auth/password/change",
+    section: "developer-auth",
+    summary: "Verifies the current password, sets a new one and answers a fresh session.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: passwordChangeRequest,
+    response: sessionTokens,
+    errors: [...DEVELOPER_GUARD, "validation_error", "invalid_credentials"],
+    transport: "http",
+    notes: "Every session of this account ends, including the caller's \u2014 the request carries nothing identifying its own refresh family, so there is none to spare. The answer is a working replacement pair, which is what the promise has to mean when nothing distinguishes one session from another."
+  },
+  {
+    method: "POST",
+    path: "/api/auth/password/reset",
+    section: "developer-auth",
+    summary: "Mails a password-reset link to the address, and answers the same either way.",
+    audience: "developer",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 202,
+    params: [],
+    query: null,
+    request: passwordResetRequest,
+    response: null,
+    errors: ["rate_limited", "validation_error"],
+    transport: "http",
+    notes: 'Status, body and timing are identical for a known and an unknown address \u2014 any difference is an account-enumeration oracle, which is why the unknown branch still pays a real SMTP round trip to a discard address. An account provisioned through OIDC has no Fleetless password and is mailed nothing. A browser form post gets a `303` to the "check your mail" card instead of this `202`.'
+  },
+  /* ------------------------------------------- client auth (portal pages) */
+  {
+    method: "GET",
+    path: "/reset-password",
+    section: "client-auth",
+    summary: `Serves the auth portal's "forgot your password" card as an HTML page.`,
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: 'HTML, not JSON: this is a page a person opens, served by the cloud from the auth portal origin. `?sent=1` draws the "check your mail" state instead \u2014 one path, because that second card has no inputs and a second path would exist only to be redirected to. The value is caller-settable and discloses nothing, since the page it draws is a constant.'
+  },
+  {
+    method: "GET",
+    path: "/reset-password/:token",
+    section: "client-auth",
+    summary: 'Serves the "pick a new password" page for a mailed reset link.',
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "token", description: "The opaque reset token from the mailed link; it is never sent as a query parameter." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: 'HTML. An unknown, spent or expired token renders one "link no longer valid" page at `410` \u2014 they are one refusal on the wire already, and splitting them here would tell a stranger which tokens ever existed. No rate limiter: the GET changes nothing, and the POST it leads to is limited per IP.'
+  },
+  {
+    method: "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.",
+    audience: "developer",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 204,
+    params: [],
+    query: null,
+    request: passwordResetConfirm,
+    response: null,
+    errors: ["rate_limited", "validation_error", "token_spent"],
+    transport: "http",
+    notes: "Unknown, spent and expired tokens all answer `410 token_spent`. Sessions are revoked under the account's actual kind \u2014 a console admin holds developer sessions, an app user holds end-user ones \u2014 so an app user's open `/realtime` socket does not outlive the reset. A browser form post gets the rendered \"done\" page instead of this `204`."
+  },
+  {
+    method: "POST",
+    path: "/api/waitlist",
+    section: "developer-auth",
+    summary: "Adds an address to the closed-beta waiting list.",
+    audience: "developer",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 202,
+    params: [],
+    query: null,
+    request: waitlistRequest,
+    response: null,
+    errors: ["rate_limited", "validation_error"],
+    transport: "http",
+    notes: "Answers `202` whether or not the address was already listed: the landing page's form must not be an oracle for who signed up. The operator notification is detached from the response \u2014 awaiting it made latency answer the question the status code refuses to \u2014 and is capped by its own global ceiling, above which the row is still written and the mail is skipped."
+  },
+  /* ---------------------------------------------------------------- org */
+  {
+    method: "GET",
+    path: "/api/audit",
+    section: "org",
+    summary: "Reads the org's audit log, newest first, cursor-paged over the durable sequence number.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: auditQuery,
+    request: null,
+    response: auditListResponse,
+    errors: [...DEVELOPER_GUARD, "validation_error"],
+    transport: "http",
+    notes: "`action` and `action_prefix` are mutually exclusive, a cross-field rule no JSON Schema can express \u2014 this route is where it is enforced. Nothing redacts an event's `details`: it is returned exactly as the call site wrote it."
+  },
+  {
+    method: "GET",
+    path: "/api/audit/export",
+    section: "org",
+    summary: "Downloads every audit event matching the same filters as a CSV attachment.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: auditQuery,
+    request: null,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "validation_error"],
+    transport: "http",
+    notes: "Answers `text/csv` with a `Content-Disposition` attachment, not JSON \u2014 so it has no response schema. `AUDIT_CSV_COLUMNS` names the columns and their order. Takes the same filters as `GET /api/audit` but refuses `before_seq` and `limit` with `400 validation_error`: an export is not a page, it is everything the filter matches up to a fixed row ceiling."
+  },
+  /* --------------------------------------------------------------- apps */
+  {
+    method: "POST",
+    path: "/api/apps",
+    section: "apps",
+    summary: "Creates an app in a group, optionally attaching robots to it at the same time.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 201,
+    params: [],
+    query: null,
+    request: createAppRequest,
+    response: app,
+    errors: [...DEVELOPER_GUARD, "validation_error", "target_state_conflict", "identifier_taken", "quota_exceeded"],
+    transport: "http",
+    notes: "Every robot id is checked before anything is created, so a bad one never leaves a robotless app to clean up. The Org Admins group is refused with `409 target_state_conflict`: admins hold no assignments, so an app there would be one nobody can be assigned to. The identifier `mcp` is reserved by the central MCP server and refused as a `validation_error`."
+  },
+  {
+    method: "GET",
+    path: "/api/apps",
+    section: "apps",
+    summary: "Lists every app in the caller's org.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...DEVELOPER_GUARD],
+    transport: "http",
+    notes: 'Answers `{ "apps": [app, \u2026] }`. The envelope has no schema of its own in contracts; each element is an `app`.'
+  },
+  {
+    method: "GET",
+    path: "/api/apps/:id",
+    section: "apps",
+    summary: "Reads one app of the org, with its group, robots and default role.",
+    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`." }],
+    query: null,
+    request: null,
+    response: app,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "An app belonging to another org reads exactly like one that does not exist \u2014 `404`, never a `403`."
+  },
+  {
+    method: "PATCH",
+    path: "/api/apps/:id",
+    section: "apps",
+    summary: "Changes an app's name, its attached robots, its default role or whether it accepts dynamic clients.",
+    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`." }],
+    query: null,
+    request: updateAppRequest,
+    response: app,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "validation_error", "not_found"],
+    transport: "http",
+    notes: "A `default_role_id` naming a role of another app is refused: it is the one cross-app authorization check this shape can carry. Changing the robot set closes every live subscription the app's users hold, since a grant may no longer name a reachable robot."
+  },
+  {
+    method: "POST",
+    path: "/api/apps/:id/roles",
+    section: "apps",
+    summary: "Creates a custom role on the app.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 201,
+    params: [{ name: "id", description: "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "validation_error"],
+    transport: "http",
+    notes: 'The body is `{ "name": string }` \u2014 non-empty, trimmed, at most 120 characters \u2014 and is deliberately not a contract shape: contracts define the `role` this answers with, not this one trivial request. The answer is a `role`.'
+  },
+  {
+    method: "GET",
+    path: "/api/apps/:id/roles",
+    section: "apps",
+    summary: "Lists the app's roles, builtin and custom.",
+    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`." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: 'Answers `{ "roles": [role, \u2026] }`. The envelope has no schema of its own in contracts; each element is a `role`.'
+  },
+  {
+    method: "PUT",
+    path: "/api/apps/:id/roles/:roleId/permissions",
+    section: "apps",
+    summary: "Replaces a role's grants and capabilities in one write.",
+    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: rolePermissions,
+    response: rolePermissions,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "validation_error"],
+    transport: "http",
+    notes: "`role_id` in the body must name the role in the path, compared case-insensitively \u2014 a uuid is a value, not a string, and a client that uppercases them consistently must not be refused for repeating what the path says. A grant naming a robot the app does not have is refused rather than stored: a permission for something the role cannot reach reads as authoritative to whoever writes the next consumer. Every user holding this role has their live subscriptions re-authorized."
+  },
+  {
+    method: "GET",
+    path: "/api/apps/:id/roles/:roleId/permissions",
+    section: "apps",
+    summary: "Reads a role's grants and capabilities.",
+    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: null,
+    response: rolePermissions,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http"
+  },
+  {
+    method: "GET",
+    path: "/api/apps/:id/roles/:roleId/mcp-tools",
+    section: "apps",
+    summary: "Previews the robot datasheets an MCP caller holding this role would be offered.",
+    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: null,
+    response: mcpRolePreviewResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    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` \u2014 dropping it would read as \"not attached\", which is a different fact."
+  },
+  {
+    method: "POST",
+    path: "/api/apps/:id/server-keys",
+    section: "apps",
+    summary: "Mints a server key for the app and returns the raw secret once.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: true,
+    status: 201,
+    params: [{ name: "id", description: "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`." }],
+    query: null,
+    request: null,
+    response: createServerKeyResponse,
+    errors: [...DEVELOPER_GUARD, "tier_required", "invalid_uuid", "not_found", "validation_error"],
+    transport: "http",
+    notes: "Owner tier only: a server key carries full app rights and outlives its creator's removal. The body is `{ \"name\": string }`, the same trivial shape role creation takes. `key` is the only moment the raw secret exists outside the caller's hands \u2014 it is never in a listing, never in an audit event, and cannot be read back."
+  },
+  {
+    method: "GET",
+    path: "/api/apps/:id/server-keys",
+    section: "apps",
+    summary: "Lists the app's server keys as metadata, never the secrets.",
+    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`." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: 'Answers `{ "server_keys": [serverKey, \u2026] }`. The envelope has no schema of its own in contracts; each element is a `serverKey`, which names the five fields it carries rather than spreading the stored row \u2014 that is what keeps this listing from becoming a second place a credential leaves the cloud.'
+  },
+  {
+    method: "POST",
+    path: "/api/apps/:id/server-keys/:keyId/rotate",
+    section: "apps",
+    summary: "Replaces a server key's secret in place and returns the new one once.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: true,
+    status: 200,
+    params: [
+      { name: "id", description: "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`." },
+      { name: "keyId", description: "The server key's uuid, from `GET /api/apps/:id/server-keys`; a key of another app answers `404`." }
+    ],
+    query: null,
+    request: null,
+    response: createServerKeyResponse,
+    errors: [...DEVELOPER_GUARD, "tier_required", "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "Owner tier, for the reason creation is. The old secret is refused from this call on, and any `/realtime` socket that authenticated with it is closed \u2014 rotation is what a developer reaches for when a key has leaked, and the holder of that socket is exactly who they are rotating against."
+  },
+  {
+    method: "DELETE",
+    path: "/api/apps/:id/server-keys/:keyId",
+    section: "apps",
+    summary: "Revokes a server key and closes every socket holding it.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: true,
+    status: 204,
+    params: [
+      { name: "id", description: "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`." },
+      { name: "keyId", description: "The server key's uuid, from `GET /api/apps/:id/server-keys`; a key of another app answers `404`." }
+    ],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "tier_required", "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "Owner tier, like minting and rotating: all three decide who may speak for the whole app."
+  },
+  /* ------------------------------------- users, groups and assignments */
+  {
+    method: "GET",
+    path: "/api/org/groups",
+    section: "users",
+    summary: "Lists every group in the org with its member and app counts.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: groupListResponse,
+    errors: [...DEVELOPER_GUARD],
+    transport: "http"
+  },
+  {
+    method: "GET",
+    path: "/api/org/groups/:id",
+    section: "users",
+    summary: "Reads one group with its member and app counts.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The group's uuid, as listed by `GET /api/org/groups`." }],
+    query: null,
+    request: null,
+    response: orgGroup,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "A group of another org reads exactly like one that does not exist."
+  },
+  {
+    method: "POST",
+    path: "/api/org/groups",
+    section: "users",
+    summary: "Creates a group, optionally with MCP access enabled for its members.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 201,
+    params: [],
+    query: null,
+    request: createGroupRequest,
+    response: orgGroup,
+    errors: [...DEVELOPER_GUARD, "validation_error"],
+    transport: "http",
+    notes: "The `is_org_admins` flag is not an argument here and cannot be: it has exactly one writer, org creation, so no door can mint a second admin group even by accident."
+  },
+  {
+    method: "PATCH",
+    path: "/api/org/groups/:id",
+    section: "users",
+    summary: "Renames a group or flips its MCP gate.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The group's uuid, as listed by `GET /api/org/groups`." }],
+    query: null,
+    request: patchGroupRequest,
+    response: orgGroup,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "validation_error"],
+    transport: "http",
+    notes: "The Org Admins group is renamable through exactly this door. `is_org_admins` cannot arrive at all \u2014 the shape is strict and does not carry it, so offering it is a refusal rather than a silent drop."
+  },
+  {
+    method: "DELETE",
+    path: "/api/org/groups/:id",
+    section: "users",
+    summary: "Deletes an empty group.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 204,
+    params: [{ name: "id", description: "The group's uuid, as listed by `GET /api/org/groups`." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "group_not_deletable", "group_in_use"],
+    transport: "http",
+    notes: "The Org Admins group answers `409 group_not_deletable`; a group still holding users or apps answers `409 group_in_use` with both counts. Both refusals are re-counted inside the deleting transaction rather than pre-checked, so there is one policy and not a weaker second one. `GET /api/org/groups/:id/usage` is the read that explains them."
+  },
+  {
+    method: "GET",
+    path: "/api/org/groups/:id/usage",
+    section: "users",
+    summary: "Reports what a group holds, before an admin decides to delete it.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The group's uuid, as listed by `GET /api/org/groups`." }],
+    query: null,
+    request: null,
+    response: groupUsageResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "`users_affected` is the group's whole membership, not only the members holding assignments: deleting a group affects everyone in it, and a count that excluded the unassigned would understate exactly the people an admin has to re-home first. Counts for showing, never for deciding \u2014 the delete re-counts in its own transaction."
+  },
+  {
+    method: "GET",
+    path: "/api/org/users",
+    section: "users",
+    summary: "Lists the org's user pool, optionally narrowed to one group.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: orgUserListResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: '`?group_id=` narrows it; there is no query schema, the parameter is read directly. A group of another org answers `404` rather than an empty list, which would be indistinguishable from "that group exists here and is empty" \u2014 a statement about somebody else\'s org. A malformed value is `400 invalid_uuid`, so a typo can be told from a deletion.'
+  },
+  {
+    method: "GET",
+    path: "/api/org/users/:id",
+    section: "users",
+    summary: "Reads one user of the org.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The user's uuid, as listed by `GET /api/org/users`." }],
+    query: null,
+    request: null,
+    response: orgUser,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http"
+  },
+  {
+    method: "POST",
+    path: "/api/org/users/invitations",
+    section: "users",
+    summary: "Invites an address into a group and returns the accept link.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 201,
+    params: [],
+    query: null,
+    request: createUserInviteRequest,
+    response: userInvite,
+    errors: [...DEVELOPER_GUARD, "tier_required", "validation_error", "target_state_conflict", "email_taken"],
+    transport: "http",
+    notes: 'One invitation flow for every group; what the invitee becomes is `group_id`. **Inviting an Owner is Owner-only** \u2014 an invitation carrying `tier: "owner"` is a promotion with an extra step, since the response hands back the `accept_url`. `ownerTier` is `false` here because the gate is on that value, not on the route: any org admin may invite a developer. A tier is required for the Org Admins group and refused for every other.'
+  },
+  {
+    method: "GET",
+    path: "/api/org/users/invitations",
+    section: "users",
+    summary: "Lists the pending invitations of the org, without their tokens.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: userInviteListResponse,
+    errors: [...DEVELOPER_GUARD],
+    transport: "http",
+    notes: "No `accept_url` is in this listing, and that omission is the point: it exists so an admin can spot a backdoor invitation planted for an address they merely control, not so anyone can re-read a link."
+  },
+  {
+    method: "DELETE",
+    path: "/api/org/users/invitations/:id",
+    section: "users",
+    summary: "Revokes a pending invitation so its link stops resolving.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 204,
+    params: [{ name: "id", description: "The invitation's uuid, as listed by `GET /api/org/users/invitations`." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "An invitation that was already accepted is not pending and answers `404`, the same answer one that never existed gets."
+  },
+  {
+    method: "POST",
+    path: "/api/org/users/invitations/:id/reissue",
+    section: "users",
+    summary: "Mints a fresh token onto the same invitation and returns the new accept link.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The invitation's uuid, as listed by `GET /api/org/users/invitations`." }],
+    query: null,
+    request: null,
+    response: userInvite,
+    errors: [...DEVELOPER_GUARD, "tier_required", "invalid_uuid", "not_found", "rate_limited"],
+    transport: "http",
+    notes: "The old link stops resolving the instant this returns \u2014 the row is looked up by token hash and the previous hash is gone. Two live links to one invitation would reopen the door the listing's missing `accept_url` closes. Limited server-side to once a minute per invitation, answering `429 rate_limited` with `retry_after_ms`; a disabled button is a hint, this is the limit. Re-issuing an owner-tier invitation needs Owner tier, exactly as creating one does."
+  },
+  {
+    method: "POST",
+    path: "/api/org/users/invitations/accept",
+    section: "users",
+    summary: "Spends an invitation token and creates the login it was addressed to.",
+    audience: "developer",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 204,
+    params: [],
+    query: null,
+    request: acceptUserInviteRequest,
+    response: null,
+    errors: ["rate_limited", "validation_error", "token_spent", "email_taken"],
+    transport: "http",
+    notes: "**`204`, not a session.** Most invitees are not org admins, so a console session minted here would be refused on the very next request; and a body whose shape depended on the invitee's group would give one route two answers. Unknown, expired and already-accepted tokens collapse into `410 token_spent`. A browser form post gets the rendered \"you're in\" page instead."
+  },
+  {
+    method: "GET",
+    path: "/accept-invite/:token",
+    section: "users",
+    summary: "Serves the invitation card a mailed accept link opens.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "token", description: "The opaque invitation token from the mailed link; it is never sent as a query parameter." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: 'HTML, served by the cloud from the auth portal origin; the form on it posts to `POST /api/org/users/invitations/accept`. An unknown, spent or expired token renders the "link no longer valid" page at `410`, which offers the password-reset page \u2014 the only self-service door the portal has, since an invitation cannot be re-issued by the person holding it.'
+  },
+  {
+    method: "PATCH",
+    path: "/api/org/users/:id",
+    section: "users",
+    summary: "Changes a user's display name or their MCP access override.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The user's uuid, as listed by `GET /api/org/users`." }],
+    query: null,
+    request: patchUserRequest,
+    response: orgUser,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "validation_error"],
+    transport: "http",
+    notes: "Nothing here has a consequence a PATCH body cannot carry: the group and the tier are their own routes, because both cascade. The audit event records which fields were addressed, never their values."
+  },
+  {
+    method: "GET",
+    path: "/api/org/users/:id/usage",
+    section: "users",
+    summary: "Previews what moving a user into another group would delete.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The user's uuid, as listed by `GET /api/org/users`." }],
+    query: null,
+    request: null,
+    response: groupUsageResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "validation_error"],
+    transport: "http",
+    notes: "`?group_id=` names the group the user would move into and is required; there is no query schema, the parameter is read directly. Absent is `400 validation_error` with rule `required`, malformed is `400 invalid_uuid`, and well-formed but not a group of this org is `validation_error` with rule `unknown_group` \u2014 three different facts a caller needs told apart. Reads only, and never a lock."
+  },
+  {
+    method: "POST",
+    path: "/api/org/users/:id/move-group",
+    section: "users",
+    summary: "Moves a user into another group, deleting every assignment the move invalidates.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The user's uuid, as listed by `GET /api/org/users`." }],
+    query: null,
+    request: moveUserGroupRequest,
+    response: orgUser,
+    errors: [...DEVELOPER_GUARD, "tier_required", "invalid_uuid", "not_found", "validation_error", "last_owner"],
+    transport: "http",
+    notes: "`acknowledge_assignment_loss: true` is a literal in the shape, so there is no request of this form without it and nothing has to remember to check. **Moving an Owner needs Owner tier** \u2014 it takes the Owner capability away, which is a demotion by another door \u2014 but `ownerTier` is `false` because that gate fires only when the target is an Owner. Moving the last Owner out is `409 last_owner`. A move out of Org Admins closes the user's open `/realtime` socket."
+  },
+  {
+    method: "DELETE",
+    path: "/api/org/users/:id",
+    section: "users",
+    summary: "Removes a user and ends every session they hold.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 204,
+    params: [{ name: "id", description: "The user's uuid, as listed by `GET /api/org/users`." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "tier_required", "invalid_uuid", "not_found", "last_owner"],
+    transport: "http",
+    notes: "Sessions are revoked before the row is deleted: a still-existing user with a dead session is recoverable by retrying, a deleted user whose old token still works is not. Both kinds go, since one row can hold console and app sessions at once. Any invitation still outstanding for that address is expired too \u2014 a link mailed before the removal is a standing re-admission ticket. Removing an Owner needs Owner tier, and removing the last one is `409 last_owner`."
+  },
+  {
+    method: "PUT",
+    path: "/api/org/users/:id/tier",
+    section: "users",
+    summary: "Promotes or demotes an org admin between Owner and developer tier.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: true,
+    status: 200,
+    params: [{ name: "id", description: "The user's uuid, as listed by `GET /api/org/users`; must be a member of the Org Admins group." }],
+    query: null,
+    request: tierChangeRequest,
+    response: orgUser,
+    errors: [...DEVELOPER_GUARD, "tier_required", "invalid_uuid", "not_found", "validation_error", "target_state_conflict", "last_owner"],
+    transport: "http",
+    notes: "Owner tier, unconditionally \u2014 this is the route the whole owner-exclusive list is about. A user outside the Org Admins group carries no tier at all and answers `409 target_state_conflict`. Demoting the last Owner is `409 last_owner`, decided by a row lock inside the writing transaction rather than by a read beforehand. Setting the tier already held changes nothing and writes no audit event. No session is revoked: a tier is re-read from the row on every request, so no issued token carries a stale copy of it."
+  },
+  {
+    method: "GET",
+    path: "/api/org/users/:id/assignments",
+    section: "users",
+    summary: "Lists the apps a user is assigned to and the role they hold in each.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The user's uuid, as listed by `GET /api/org/users`." }],
+    query: null,
+    request: null,
+    response: appAssignmentListResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http"
+  },
+  {
+    method: "PUT",
+    path: "/api/org/users/:id/assignments/:appId",
+    section: "users",
+    summary: "Assigns a user to an app in a role, or changes the role they already hold.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [
+      { name: "id", description: "The user's uuid, as listed by `GET /api/org/users`." },
+      { name: "appId", description: "The app's uuid; it must belong to the same group as the user." }
+    ],
+    query: null,
+    request: putAssignmentRequest,
+    response: appAssignment,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "target_state_conflict", "validation_error"],
+    transport: "http",
+    notes: "An app outside the user's group is `409 target_state_conflict` with rule `group_mismatch` \u2014 the group is what pairs a user with the apps they can be assigned to. A role belonging to another app is a `validation_error`. Re-roling closes the user's live subscriptions on that app."
+  },
+  {
+    method: "DELETE",
+    path: "/api/org/users/:id/assignments/:appId",
+    section: "users",
+    summary: "Removes a user's assignment to one app and ends their sessions for it.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 204,
+    params: [
+      { name: "id", description: "The user's uuid, as listed by `GET /api/org/users`." },
+      { name: "appId", description: "The app's uuid; only sessions and subscriptions for this app are ended." }
+    ],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "Only that app's sessions end; the user's access to every other app they are assigned to is untouched."
+  },
+  {
+    method: "GET",
+    path: "/api/apps/:id/group-usage",
+    section: "users",
+    summary: "Previews what re-linking an app to another group would delete.",
+    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`." }],
+    query: null,
+    request: null,
+    response: groupUsageResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "validation_error"],
+    transport: "http",
+    notes: "`?group_id=` names the target group and is required, with the same three distinct refusals `GET /api/org/users/:id/usage` gives. The app is scoped first, so none of them can confirm that an app the caller does not own exists."
+  },
+  {
+    method: "PUT",
+    path: "/api/apps/:id/group",
+    section: "users",
+    summary: "Re-links an app to another group, deleting every assignment the move invalidates.",
+    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`." }],
+    query: null,
+    request: putAppGroupRequest,
+    response: app,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "validation_error", "target_state_conflict"],
+    transport: "http",
+    notes: "The destructive half of the pair: every assignment naming this app whose user is not in the new group dies with the change, which is why the shape demands a literal acknowledgement. The Org Admins group is refused for the reason app creation refuses it. One edit can cut a whole team off at once, so every live subscription on the app is closed."
+  },
+  /* ------------------------------------------------ org (federation, OIDC) */
+  {
+    method: "GET",
+    path: "/api/org/federation",
+    section: "org",
+    summary: "Reads whether a federated login may join an existing account by verified email.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: orgFederationPolicy,
+    errors: [...DEVELOPER_GUARD],
+    transport: "http",
+    notes: "Any org admin may read it; only an Owner may change it."
+  },
+  {
+    method: "PUT",
+    path: "/api/org/federation",
+    section: "org",
+    summary: "Sets whether a federated login may join an existing account by verified email.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: true,
+    status: 200,
+    params: [],
+    query: null,
+    request: orgFederationPolicyRequest,
+    response: orgFederationPolicy,
+    errors: [...DEVELOPER_GUARD, "tier_required", "validation_error"],
+    transport: "http",
+    notes: "Owner tier: what this flag decides is account linking across the whole org, not a per-app setting. It lives on the org rather than on an app because the thing it governs \u2014 one user row per address \u2014 is org-scoped."
+  },
+  {
+    method: "GET",
+    path: "/api/org/groups/:id/oidc-provider",
+    section: "org",
+    summary: "Reads a group's OIDC provider configuration, without the client secret.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The group's uuid, as listed by `GET /api/org/groups`." }],
+    query: null,
+    request: null,
+    response: groupOidcProvider,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "A group with no provider answers `404`, not an empty object. The secret is write-only and comes back through nothing \u2014 not this read, not the PUT's own response, not an audit detail; the stored row this maps from has none to carry."
+  },
+  {
+    method: "PUT",
+    path: "/api/org/groups/:id/oidc-provider",
+    section: "org",
+    summary: "Sets or rotates a group's OIDC provider and its just-in-time grants.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The group's uuid, as listed by `GET /api/org/groups`." }],
+    query: null,
+    request: putGroupOidcProviderRequest,
+    response: groupOidcProvider,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "target_state_conflict", "validation_error"],
+    transport: "http",
+    notes: "Any org admin, not Owner only: configuring a group's provider is member management. The Org Admins group is refused with `409 target_state_conflict` \u2014 console login is always the Fleetless password provider. `client_secret` is optional so a rotation need not resend it, but the first write of a provider must carry one. Each JIT grant's app must belong to this group, its role to that app, and no two grants may name the same app. An issuer resolving to a loopback or private address is refused here as a shape check; the authoritative SSRF defence is at the discovery fetch."
+  },
+  {
+    method: "DELETE",
+    path: "/api/org/groups/:id/oidc-provider",
+    section: "org",
+    summary: "Removes a group's OIDC provider.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 204,
+    params: [{ name: "id", description: "The group's uuid, as listed by `GET /api/org/groups`." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "Deleting a provider a group never had is an honest `404`, not a silent `204`."
+  },
+  {
+    method: "PATCH",
+    path: "/api/org",
+    section: "org",
+    summary: "Renames the org.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: true,
+    status: 200,
+    params: [],
+    query: null,
+    request: patchOrgRequest,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "tier_required", "validation_error"],
+    transport: "http",
+    notes: 'Answers `{ "org": org }`. The envelope has no schema of its own in contracts; the value is an `org`. Owner tier, and the gate runs before the body is looked at, so a malformed rename and a forbidden one answer the same way. Renaming to the name already held writes nothing and records no audit event.'
+  },
+  /* --------------------------------------------- oauth (app-scoped clients) */
+  {
+    method: "POST",
+    path: "/api/apps/:id/oauth-clients",
+    section: "oauth",
+    summary: "Registers an OAuth client on the app and returns its `client_id`.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 201,
+    params: [{ name: "id", description: "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`." }],
+    query: null,
+    request: null,
+    response: oauthClient,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "validation_error"],
+    transport: "http",
+    notes: 'The body is `{ "client_name": string, "redirect_uris": string[] }` and has no contract shape of its own: `dynamicClientRegistrationRequest` is RFC 7591\'s wire for `POST /oauth/register` and carries four fields this route ignores, so reusing it here would document a request that is not this one. A `redirect_uri` is refused as `validation_error` with rule `invalid_redirect_uri`. This is a developer\'s own credential-bearing action, so it answers the `apiError` envelope, not RFC 6749\'s.'
+  },
+  {
+    method: "GET",
+    path: "/api/apps/:id/oauth-clients",
+    section: "oauth",
+    summary: "Lists the app's OAuth clients, developer-registered and self-registered alike.",
+    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`." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: 'Answers `{ "oauth_clients": [oauthClient, \u2026] }`. The envelope has no schema of its own in contracts; each element is an `oauthClient`, and each carries its `registration` \u2014 a developer could otherwise not see the self-registered clients holding their own dynamic-client ceiling shut.'
+  },
+  {
+    method: "DELETE",
+    path: "/api/apps/:id/oauth-clients/:clientId",
+    section: "oauth",
+    summary: "Removes an OAuth client registration from the app.",
+    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: "clientId", description: "The OAuth `client_id` string, as listed by `GET /api/apps/:id/oauth-clients`; a client of another app answers `404`." }
+    ],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "The harsher of the two doors: the registration itself is gone, so the client cannot ask for consent again. `DELETE \u2026/consent` is the other one, which leaves the registration in place."
+  },
+  {
+    method: "DELETE",
+    path: "/api/apps/:id/oauth-clients/:clientId/consent",
+    section: "oauth",
+    summary: "Revokes every end user's consent grant to one OAuth client of the app.",
+    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: "clientId", description: "The OAuth `client_id` string, as listed by `GET /api/apps/:id/oauth-clients`; a client of another app answers `404`." }
+    ],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: '"Disconnect that AI tool", without deleting the registration. The revocation is read on the client\'s very next call, so no token refresh has to happen first, and every other client the same end users granted is untouched. A client with no active grant answers `404` rather than a `204` that would claim something was revoked.'
+  },
+  /* ----------------------------------------------- oauth (RFC metadata) */
+  {
+    method: "GET",
+    path: "/.well-known/oauth-authorization-server",
+    section: "oauth",
+    summary: "Publishes the authorization-server metadata every OAuth 2.1 client reads before it does anything else.",
+    audience: "client",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: authorizationServerMetadata,
+    errors: [],
+    transport: "http",
+    notes: 'RFC 8414. No auth and no database read, so a client that can reach only this document can still plan the whole flow. `code_challenge_methods_supported` is `["S256"]` and `token_endpoint_auth_methods_supported` is `["none"]`: every client here is public and PKCE is required.'
+  },
+  {
+    method: "GET",
+    path: "/.well-known/oauth-authorization-server/:appIdentifier",
+    section: "oauth",
+    summary: "The same metadata for one app, whose `registration_endpoint` already carries the app identifier.",
+    audience: "client",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "appIdentifier", description: "The app's `identifier`, the slug a developer chose when the app was created." }],
+    query: null,
+    request: null,
+    response: authorizationServerMetadata,
+    errors: ["not_found"],
+    transport: "http",
+    notes: "RFC 8414 \xA73.1's suffix-insertion rule: an issuer with a path component publishes its document here. The one functional difference from the global document is `registration_endpoint`, which already names `?app_identifier=` \u2014 so a client that starts from this document never needs that value from anywhere else. `authorization_endpoint` and `token_endpoint` stay the global ones, since `client_id` already says which app. An unknown identifier is `404`, not a document describing nothing."
+  },
+  {
+    method: "GET",
+    path: "/.well-known/oauth-protected-resource",
+    section: "oauth",
+    summary: "Publishes what the stub resource says about who may authorize for it.",
+    audience: "client",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: protectedResourceMetadata,
+    errors: [],
+    transport: "http",
+    notes: "RFC 9728, for the global `/mcp-stub/resource`. The per-app document lives under `/.well-known/oauth-protected-resource/mcp-stub/resource/:appIdentifier`."
+  },
+  /* ------------------------------------------- oauth (the app sign-in flow) */
+  {
+    method: "GET",
+    path: "/oauth/authorize",
+    section: "oauth",
+    summary: "Starts an end-user sign-in for an app and redirects the browser to the login card.",
+    audience: "client",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 302,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: ["rate_limited"],
+    transport: "http",
+    notes: "The query is RFC 6749 \xA74.1.1's \u2014 `client_id`, `redirect_uri`, `response_type`, `code_challenge`, `code_challenge_method`, `state`, `resource` \u2014 read parameter by parameter, and contracts declares no schema for it, so nothing here pins its shape. **`client_id` and `redirect_uri` are validated first, and a failure there never redirects** \u2014 until the URI is known-good, sending a browser to it is the attack. Those two refusals are RFC 6749's flat `oauthError` shape at `400`; everything validated afterwards (`response_type`, PKCE, `resource`) goes back to the callback as query parameters, per \xA74.1.2.1. `S256` is required. A group with a configured OIDC provider is sent to that provider instead of to the Fleetless login card. The only `apiError` this route sends is the rate limiter's `429 rate_limited`."
+  },
+  {
+    method: "POST",
+    path: "/login",
+    section: "oauth",
+    summary: "Checks an end user's password and hands back where the sign-in continues.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: oauthLoginRequest,
+    response: oauthRedirectResponse,
+    errors: ["rate_limited", "validation_error", "token_spent", "invalid_credentials", "forbidden"],
+    transport: "http",
+    notes: "`interaction_id` travels in the **body**, never the URL: which app is being signed into is a property of the pending request the server already holds, not an assertion the page gets to make. Two dialects, decided on the request body's content type \u2014 a real `<form>` submission gets a `303` to the next step and the rendered pages for every refusal, a programmatic caller gets this `200` and the `apiError` codes above. An org admin is redirected to the impersonation interstitial rather than straight on. `oauthLoginResponse` is contracts' alias for this response shape."
+  },
+  {
+    method: "GET",
+    path: "/login",
+    section: "oauth",
+    summary: "Serves the app login card the authorize step redirects a browser to.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: 'HTML, branded per app. One path, both verbs: this GET draws the form and the POST above takes it. An expired, consumed, unknown or hand-edited interaction renders one "sign-in is over" page at `410` \u2014 and so does a lapsed dynamic client, because a form whose submission is already known to fail is a password typed for nothing.'
+  },
+  {
+    method: "GET",
+    path: "/oauth/impersonate",
+    section: "oauth",
+    summary: 'Serves the "sign in as" card an org admin sees instead of going straight to the app.',
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: "HTML, and the most disclosive page the portal has: it lists every assignable user of the app's group by email address. So the browser-proof cookie is checked on this **GET** as well as on the POST \u2014 `interaction_id` is not a secret, since the client that starts the flow learns its own from the authorize redirect, and without the cookie a self-registering client could read a customer's roster off a page it never authenticated for. Refusals render the problem page carrying `wrong_browser` or `forbidden` as a document attribute, not as an `apiError` body."
+  },
+  {
+    method: "POST",
+    path: "/oauth/impersonate",
+    section: "oauth",
+    summary: "Takes the org admin's choice of role or user and resumes the app sign-in as them.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: oauthRedirectResponse,
+    errors: ["rate_limited", "validation_error", "token_spent", "unauthorized", "forbidden"],
+    transport: "http",
+    notes: 'The JSON body is `{ "interaction_id": string, "choice": impersonationChoice }`; that wrapper has no schema of its own, only the `choice` does. A `<form>` cannot nest an object, so a browser sends one `act_as` field spelled `role:<id>` or `user:<id>`, parsed back into the identical `choice` before anything downstream sees a difference. Signing in as another org admin is refused. The browser-proof cookie is re-checked here, and a browser gets the rendered problem page where a JSON caller gets these codes.'
+  },
+  {
+    method: "GET",
+    path: "/oauth/consent",
+    section: "oauth",
+    summary: "Serves the consent screen for a client asking to act for an end user.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: "HTML. The browser-proof cookie is checked on the GET as well as on the POST \u2014 the same gap that had to be closed on the impersonation interstitial and the MCP consent screen. An interaction that is not authenticated yet, a lapsed dynamic client and the central client all render the same `410` page."
+  },
+  {
+    method: "POST",
+    path: "/oauth/consent",
+    section: "oauth",
+    summary: "Records the end user's allow-or-deny and sends the browser back to the client.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: consentDecision,
+    response: oauthRedirectResponse,
+    errors: ["rate_limited", "validation_error", "token_spent", "unauthorized", "invalid_credentials"],
+    transport: "http",
+    notes: "A JSON caller sends `consentDecision` and its bytes are untouched. A `<form>` cannot send a boolean, so a browser sends the pressed button's `decision` value and **anything that is not exactly the Allow value denies**, including a submission carrying none \u2014 fail-closed is the only defensible default on a screen whose whole job is to require a deliberate yes. `oauthConsentResponse` is contracts' alias for this response shape."
+  },
+  {
+    method: "POST",
+    path: "/oauth/token",
+    section: "oauth",
+    summary: "Exchanges an authorization code, or a refresh token, for an end-user access token.",
+    audience: "client",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: oauthTokenRequest,
+    response: oauthTokenResponse,
+    errors: ["rate_limited"],
+    transport: "http",
+    notes: "Refusals use RFC 6749 \xA75.2's flat `oauthError` shape \u2014 it is a token endpoint, and that is the dialect a caller of one expects \u2014 so it emits none of the other codes in this reference; only the rate limiter answers an `apiError`. The request is a discriminated union on `grant_type` and is deliberately **not** strict: a conformant client may send parameters this server does not read, and refusing those would be a conformance bug. `resource` (RFC 8707) is carried across every refresh rotation \u2014 a successor token minted without it would be refused by the resource one token lifetime after a login that worked."
+  },
+  {
+    method: "POST",
+    path: "/oauth/register",
+    section: "oauth",
+    summary: "Registers a client dynamically against one app, when that app accepts dynamic clients.",
+    audience: "client",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 201,
+    params: [],
+    query: null,
+    request: dynamicClientRegistrationRequest,
+    response: dynamicClientRegistrationResponse,
+    errors: ["rate_limited"],
+    transport: "http",
+    notes: "RFC 7591. `?app_identifier=` names the app and is required; it is read directly and contracts declares no schema for this query, so it appears in no parameter table. An app that does not accept dynamic clients answers `oauthError` `access_denied`, as does one that has reached its per-app ceiling. Every refusal here is `oauthError`, not `apiError` \u2014 again, only the rate limiter differs. A registration expires: an unused dynamic client stops working rather than merely stopping to count."
+  },
+  /* ------------------------------- oauth (the validating stub resource) */
+  {
+    method: "GET",
+    path: "/mcp-stub/resource",
+    section: "oauth",
+    summary: "A resource that validates an access token's audience, so the minting side has something that refuses.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: "Answers `{ ok, sub, resource }`, a cloud-local shape with no wire contract. It exists because a minting mechanism with no validator is a check that cannot fail: this refuses a token whose `aud` names something else, and the gate measures the refusal. Its refusals are RFC 6750's tiny `{ error, error_description }` with a `WWW-Authenticate` header naming its own metadata document, not `apiError`."
+  },
+  {
+    method: "GET",
+    path: "/mcp-stub/resource/:appIdentifier",
+    section: "oauth",
+    summary: "The same validating stub, scoped to one app.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "appIdentifier", description: "The app's `identifier`, the slug a developer chose when the app was created." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: 'The per-app half of the discovery walk: a client holding only this URL follows `401` \u2192 `WWW-Authenticate: resource_metadata=` \u2192 the per-app protected-resource document \u2192 the per-app authorization-server document \u2192 `registration_endpoint`, and needs nothing told to it out of band. An unknown identifier answers RFC 6750\'s `{ error: "invalid_request" }` at `404`, not the `apiError` envelope.'
+  },
+  {
+    method: "GET",
+    path: "/.well-known/oauth-protected-resource/mcp-stub/resource/:appIdentifier",
+    section: "oauth",
+    summary: "The protected-resource metadata for one app's stub resource.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "appIdentifier", description: "The app's `identifier`, the slug a developer chose when the app was created." }],
+    query: null,
+    request: null,
+    response: protectedResourceMetadata,
+    errors: ["not_found"],
+    transport: "http",
+    notes: "RFC 9728's path-suffix construction, the same rule the per-app authorization-server document follows. `authorization_servers` names the per-app issuer, which is what lets a client reach the whole chain from the resource URL alone."
+  },
+  {
+    method: "GET",
+    path: "/oauth/idp-callback",
+    section: "oauth",
+    summary: "Takes the identity provider's redirect back and resumes the app sign-in as the federated user.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 302,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: "**Every failure renders the honest error page and never the Fleetless login form** \u2014 a form asking for a Fleetless password after an identity-provider round trip is the phishing door this design closes by name. The page carries an `oidcCallbackError` code (`invalid_request`, `exchange_failed`, `provider_misconfigured`, `idp_unreachable`, `claims_incomplete`, `jit_disabled`, `email_collision`, `forbidden`), which is a different vocabulary from this reference's: none of these answers is an `apiError` envelope. `state` is signed and checked before any database read. The SSRF defence sits at the discovery fetch and at the token exchange, on the URL the provider's own document named."
+  },
+  /* --------------------------------------------------------------- mcp */
+  {
+    method: "GET",
+    path: "/.well-known/oauth-protected-resource/mcp",
+    section: "mcp",
+    summary: "Publishes what the MCP endpoint says about who may authorize for it.",
+    audience: "client",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: protectedResourceMetadata,
+    errors: [],
+    transport: "http",
+    notes: "RFC 9728, for the one central MCP endpoint. `resource` and `authorization_servers` are the same URL: the MCP server is its own authorization server here. There is no per-group document, because the path names no group \u2014 the token does."
+  },
+  {
+    method: "GET",
+    path: "/.well-known/oauth-authorization-server/mcp",
+    section: "mcp",
+    summary: "Publishes the authorization-server metadata an MCP client reads to sign a person in.",
+    audience: "client",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: authorizationServerMetadata,
+    errors: [],
+    transport: "http",
+    notes: "`registration_endpoint` being present is the whole point of the dynamic-registration work: a client that finds it registers itself and never asks a person for a `client_id`. `authorization_endpoint` is the only field that moves to the auth-portal origin when one is configured \u2014 `issuer`, `token_endpoint` and the resource identifier stay canonical, because a client checks a token's `iss` and `aud` against those strings and moving them would invalidate every token ever minted."
+  },
+  {
+    method: "POST",
+    path: "/mcp/oauth/register",
+    section: "mcp",
+    summary: "Registers an MCP client dynamically, with no app identifier and no human in the loop.",
+    audience: "client",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 201,
+    params: [],
+    query: null,
+    request: null,
+    response: dynamicClientRegistrationResponse,
+    errors: ["rate_limited"],
+    transport: "http",
+    notes: "RFC 7591, and deliberately **not** parsed against `dynamicClientRegistrationRequest`: that shape is strict, and a strict schema here would answer `400` to a conforming client and take the whole paste-the-URL flow down with it. `client_name` and `redirect_uris` are read by hand; everything else is ignored. What comes back is what was actually granted, which \xA73.2.1 allows a server to substitute \u2014 this authorization server issues `authorization_code` only, so a client that asked for `refresh_token` is registered and told plainly that it did not get one. The registration carries a TTL. Refusals are `oauthError`; the rate limiter answers `apiError`."
+  },
+  {
+    method: "GET",
+    path: "/mcp/oauth/authorize",
+    section: "mcp",
+    summary: "Starts an MCP sign-in and redirects the browser to the identify card.",
+    audience: "client",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 302,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: "Client and `redirect_uri` are validated first and a failure there never redirects, the same open-redirect discipline the app flow applies; those refusals are `oauthError`. Exact `redirect_uri` matching for both client kinds \u2014 the loopback-port wildcard of RFC 8252 \xA77.3 belongs to the one central client alone, whose URIs are configured ahead of time and cannot name an ephemeral port. A client that registered itself seconds ago can name the port it bound, and widening the wildcard there would only widen where a stolen `client_id` may send a browser. No group is chosen here: the email address on the next card decides it."
+  },
+  {
+    method: "GET",
+    path: "/mcp/oauth/interaction/:id",
+    section: "mcp",
+    summary: 'Serves the "what is your email address" card of an MCP sign-in.',
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The interaction id minted by `GET /mcp/oauth/authorize`, which redirects the browser here." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: "HTML, and a GET rather than the body of the authorize response \u2014 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."
+  },
+  {
+    method: "POST",
+    path: "/mcp/oauth/identify",
+    section: "mcp",
+    summary: "Takes the email address and decides whether this person signs in with a password or through their identity provider.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: ["rate_limited", "validation_error", "token_spent"],
+    transport: "http",
+    notes: 'The identifier-first step: the **resolved user** decides the group and the provider, never a path segment and never the client. A browser form post gets the password card, or a `303` to the identity provider; a JSON caller gets `{ "next" }`, which has no schema. Rate limited per (route, ip, email) despite spending no credential, because a federated address sends this endpoint on an outbound discovery request. A provider that is misconfigured or unreachable renders the problem page, not an `apiError`.'
+  },
+  {
+    method: "POST",
+    path: "/mcp/oauth/login",
+    section: "mcp",
+    summary: "Checks the password and hands back where the MCP sign-in continues.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: oauthRedirectResponse,
+    errors: ["rate_limited", "validation_error", "token_spent", "invalid_credentials"],
+    transport: "http",
+    notes: 'The body is `{ "interaction_id", "email", "password" }`, read field by field rather than through a contract shape. A browser gets a `303` \u2014 to the consent screen for a self-registered client, or straight to the callback for the central one \u2014 where a JSON caller gets this `200` and `redirect_to`.'
+  },
+  {
+    method: "GET",
+    path: "/mcp/oauth/idp-callback",
+    section: "mcp",
+    summary: "Takes the identity provider's redirect back and resumes the MCP sign-in as the federated user.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 302,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: "One central callback for every group \u2014 the group is recovered from the interaction the signed `state` names, which is why this URL is a constant a customer can register with their own identity provider once. Every failure renders the honest problem page with an `oidcCallbackError` code, never the Fleetless login form and never an `apiError` envelope, for the reason the app flow's callback gives."
+  },
+  {
+    method: "GET",
+    path: "/mcp/oauth/consent/:id",
+    section: "mcp",
+    summary: "Serves the consent screen for an MCP client that registered itself.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The interaction id from the sign-in; the login step redirects the browser here." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: "HTML. The browser-proof cookie is checked on this GET, not only on the POST. The **central** client never reaches this screen and renders the `410` page instead: it is configured by the operator, so there is no self-registered stranger for a person to weigh up."
+  },
+  {
+    method: "POST",
+    path: "/mcp/oauth/consent",
+    section: "mcp",
+    summary: "Records the allow-or-deny and sends the browser back to the MCP client.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: oauthRedirectResponse,
+    errors: ["rate_limited", "validation_error", "token_spent"],
+    transport: "http",
+    notes: "Fail-closed exactly as the app flow's consent POST is: the body carries the pressed button's `decision`, and anything that is not the Allow value \u2014 a missing field included \u2014 denies. A denial still answers a `redirect_to`, carrying `error=access_denied` back to the client, because a client that is refused must learn so from its own callback rather than from a page nobody sent it."
+  },
+  {
+    method: "POST",
+    path: "/mcp/oauth/token",
+    section: "mcp",
+    summary: "Exchanges an MCP authorization code for an access token.",
+    audience: "client",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: oauthTokenResponse,
+    errors: [],
+    transport: "http",
+    notes: "Only `authorization_code` is supported \u2014 there is no refresh grant here, so a session ends when its token expires and the client signs in again. Refusals are RFC 6749 \xA75.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."
+  },
+  /* ------------------------------- developer auth (the console\'s OAuth portal) */
+  {
+    method: "GET",
+    path: "/console/oauth/authorize",
+    section: "developer-auth",
+    summary: "Starts a console sign-in and redirects the browser to the identify card.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 302,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: "The authorization-code leg of the console's own OAuth flow: PKCE `S256` is required and `redirect_uri` must match a configured console callback exactly, never a prefix. Refusals use RFC 6749's flat `oauthError` shape, not the `apiError` envelope, so they carry none of the codes in this reference. A bad `redirect_uri` never redirects \u2014 until the URI is known-good, sending a browser to it is the attack; later errors go back to the callback as query parameters. `?prompt=create` starts at sign-up rather than sign-in."
+  },
+  {
+    method: "GET",
+    path: "/console/oauth/interaction/:id",
+    section: "developer-auth",
+    summary: 'Serves the "what is your email address" card of a console sign-in.',
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The interaction id minted by `GET /console/oauth/authorize`, which redirects the browser here." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: "HTML. 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",
+    path: "/console/oauth/identify",
+    section: "developer-auth",
+    summary: "Takes the email address and hands back the password step.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: ["rate_limited", "token_spent"],
+    transport: "http",
+    notes: 'A browser form post gets the password card as HTML; a JSON caller gets `{ "next": "/console/oauth/login" }`, which has no schema \u2014 the step made no decision, and it says so rather than inventing a redirect. A dead interaction is `410 token_spent`. Rate limited despite spending no credential: it is an unauthenticated endpoint that renders a page.'
+  },
+  {
+    method: "POST",
+    path: "/console/oauth/login",
+    section: "developer-auth",
+    summary: "Checks the password and mints the authorization code the console exchanges.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: oauthRedirectResponse,
+    errors: ["rate_limited", "token_spent", "invalid_credentials"],
+    transport: "http",
+    notes: 'This is the only place a Fleetless developer password may be typed; `POST /api/auth/login` is gone, because a second credential door means every security property has to be right in two places. A browser form post gets a `303` to the callback URL; a JSON caller gets that same URL as `redirect_to` at `200`. An argon2 verify runs whether or not the address exists, and the Org Admins check runs after it \u2014 filtering first would hand back a faster "no" for a non-admin account, which is a timing oracle. Wrong password, unknown address and "not an org admin" render identical bytes under one `401`.'
+  },
+  {
+    method: "GET",
+    path: "/console/oauth/signup/:id",
+    section: "developer-auth",
+    summary: "Serves step one of console sign-up, the account card.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The interaction id minted by `GET /console/oauth/authorize` with `?prompt=create`." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: 'HTML. While the deployment runs in closed beta this renders the "sign-up is closed" card at `403` instead, keeping the interaction alive and pointing back at sign-in \u2014 the person may well already have an account.'
+  },
+  {
+    method: "POST",
+    path: "/console/oauth/signup",
+    section: "developer-auth",
+    summary: "Takes the sign-up email and password and hands back the organization step.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: ["rate_limited", "token_spent", "signup_closed", "validation_error", "email_taken"],
+    transport: "http",
+    notes: 'A browser form post gets the organization card; a JSON caller gets `{ "next", "email" }`, which has no schema. The plaintext password exists for this one request: what is stored is its argon2 hash, on the interaction row, which expires with it. A per-interaction proof cookie is set here \u2014 it is what stops a third party from finishing a sign-up somebody else started. Sign-up is the one surface whose job is to say an address is taken, so `409 email_taken` is not a leak here.'
+  },
+  {
+    method: "POST",
+    path: "/console/oauth/signup/organization",
+    section: "developer-auth",
+    summary: "Takes the organization name and creates the org, its admin group and its founding Owner.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: oauthRedirectResponse,
+    errors: ["rate_limited", "token_spent", "signup_closed", "wrong_browser", "validation_error", "email_taken"],
+    transport: "http",
+    notes: "The same single transaction `POST /api/auth/signup` runs. Step one must have run in **this** browser: a missing or mismatched proof cookie is `401 wrong_browser` and the person is sent back to step one. A browser form post gets a `303` to the console callback; a JSON caller gets `redirect_to` at `200`."
+  },
+  {
+    method: "POST",
+    path: "/console/oauth/token",
+    section: "developer-auth",
+    summary: "Exchanges the console's authorization code for a developer session.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: sessionTokens,
+    errors: [],
+    transport: "http",
+    notes: "Called by the console's own server, never by a browser. Refusals use RFC 6749 \xA75.2's flat `oauthError` shape \u2014 it is a token endpoint, and that is the dialect a caller of one expects \u2014 so it emits none of the codes in this reference. Proof of possession is checked before the replay check, and the single-use consume is atomic, so exactly one caller ever mints. The Org Admins membership is re-read here: the code was minted earlier, and a user moved out in between must not get a console session."
+  },
+  /* ---------------------------------------------------- mcp (the endpoint) */
+  {
+    method: "GET",
+    path: "/mcp/welcome",
+    section: "mcp",
+    summary: "Serves the page that tells a person which URL to paste into their MCP client.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: [],
+    transport: "http",
+    notes: "HTML, one fixed document rendered once at startup \u2014 its inputs are process configuration, not request state. Cached for five minutes rather than a day, because the URLs it names can change with a deployment. Its content security policy admits the page's own inline style and script by SHA-256 rather than by `unsafe-inline`, and forbids every external fetch outright. A configured friendly URL that is not a usable absolute http(s) URL is ignored rather than rendered: a typo in a deployment variable must not put a broken URL in front of every end user."
+  },
+  {
+    method: "POST",
+    path: "/mcp",
+    section: "mcp",
+    summary: "The one MCP endpoint: a stateless Streamable HTTP transport carrying the robot and console tool catalogs.",
+    audience: "client",
+    auth: "in_handler",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: ["unauthorized", "forbidden", "mcp_access_denied"],
+    transport: "http",
+    notes: "JSON-RPC over MCP's Streamable HTTP, so neither the request nor the response is a shape contracts describes; the tool arguments and results are the schemas in each tool definition. **The bearer is verified inside the handler**, not by a route guard: the group comes from the token and the path names none, and the refusal has to carry a `WWW-Authenticate` challenge that a guard shared with the REST surface does not send. A `401 unauthorized` carries that challenge; a `403 mcp_access_denied` deliberately does not, because re-authenticating cannot help. `Origin` is checked against the cloud's own. The catalog is re-derived per request, so an admin demoted mid-conversation loses the console tools on the next call \u2014 and a console tool name learned elsewhere is refused there too, as a `forbidden` result rather than an unknown-tool error, since the name is real and saying otherwise sends the model hunting for a spelling mistake it did not make. Stateless: a fresh transport per request, no session id, nothing survives the call."
+  },
+  /* ------------------------------------------------------- apps (branding) */
+  {
+    method: "GET",
+    path: "/api/apps/:id/branding",
+    section: "apps",
+    summary: "Reads the app's login-page branding, or null when it has none.",
+    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`." }],
+    query: null,
+    request: null,
+    response: brandingConfig,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "`null` is an answer, not an absence: an app that never configured branding is in that state and renders neutral Fleetless. So this is `200` with a `null` body rather than a `404`, and rather than a default object a caller could mistake for a stored one."
+  },
+  {
+    method: "PUT",
+    path: "/api/apps/:id/branding",
+    section: "apps",
+    summary: "Replaces the app's login-page branding.",
+    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`." }],
+    query: null,
+    request: brandingConfig,
+    response: brandingConfig,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "validation_error"],
+    transport: "http",
+    notes: "A replace, not a merge. The app is scoped before the body is parsed, so an app the caller does not own answers `404` whether or not the colour was also malformed."
+  },
+  {
+    method: "DELETE",
+    path: "/api/apps/:id/branding",
+    section: "apps",
+    summary: "Drops the app back to neutral Fleetless branding.",
+    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`." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "Deleting branding an app never had is not an error: the end state is what was asked for."
+  },
+  /* --------------------------------------------------- end-user (client) auth */
+  {
+    method: "POST",
+    path: "/api/client/login",
+    section: "client-auth",
+    summary: "Signs an app user in with an app identifier, an email address and a password.",
+    audience: "client",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: clientLoginRequest,
+    response: sessionTokens,
+    errors: ["rate_limited", "validation_error", "invalid_credentials"],
+    transport: "http",
+    notes: 'One refusal for every miss \u2014 unknown app, unknown address, wrong password, or no assignment to this app \u2014 because the caller supplies the `app_identifier` unauthenticated, so "this app knows this user" is not a fact the answer may carry. The argon2 verify is paid unconditionally, including for an unknown app identifier, so response time is not an oracle either.'
+  },
+  {
+    method: "POST",
+    path: "/api/client/refresh",
+    section: "client-auth",
+    summary: "Rotates an app-user refresh token and mints a fresh access token.",
+    audience: "client",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: clientRefreshRequest,
+    response: sessionTokens,
+    errors: ["rate_limited", "validation_error", "token_expired", "token_revoked"],
+    transport: "http",
+    notes: "The assignment is re-proved here, not just the token: refresh is where every session eventually re-proves itself, so a user whose assignment to this app was removed loses the family here even if the proactive revoke had not landed. A family minted from a `resource`-carrying token exchange keeps its audience across every rotation."
+  },
+  {
+    method: "POST",
+    path: "/api/client/logout",
+    section: "client-auth",
+    summary: "Revokes an app-user refresh family and reports whether the identity provider can also be signed out.",
+    audience: "client",
+    auth: "none",
+    rateLimited: true,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: clientLogoutRequest,
+    response: clientLogoutResponse,
+    errors: ["rate_limited", "validation_error"],
+    transport: "http",
+    notes: 'The Fleetless session is over before the identity provider is consulted, and nothing in that outbound call can put it back. `idp_logout` reports which of five outcomes applies; `session_unknown` means no live session was found for the token, which is not the same fact as "this session had no identity provider". A row that cannot produce an `id_token_hint` is never reported as `redirect`. Open `/realtime` sockets are closed.'
+  },
+  {
+    method: "POST",
+    path: "/api/client/password/change",
+    section: "client-auth",
+    summary: "Changes an app user's own password and answers a fresh session.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: passwordChangeRequest,
+    response: sessionTokens,
+    errors: [...CLIENT_GUARD, "validation_error", "invalid_credentials"],
+    transport: "http",
+    notes: "The guard admits all three caller kinds, but a password belongs to an app user specifically \u2014 a developer bearer or a server key reaching this is `401 unauthorized`. Every session of the account ends, across every app, since a password is account-wide; the answer is the replacement pair."
+  },
+  {
+    method: "GET",
+    path: "/api/client/grants",
+    section: "client-auth",
+    summary: "Lists the OAuth clients this app user has consented to.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: consentGrantListResponse,
+    errors: [...CLIENT_GUARD],
+    transport: "http",
+    notes: "App-user only: a developer bearer or a server key reaching this through the client surface is `401 unauthorized`."
+  },
+  {
+    method: "DELETE",
+    path: "/api/client/grants/:client_id",
+    section: "client-auth",
+    summary: "Revokes one consent grant and every refresh family issued under it.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "client_id", description: "The OAuth client id, as listed by `GET /api/client/grants`." }],
+    query: null,
+    request: null,
+    response: consentRevokeResponse,
+    errors: [...CLIENT_GUARD, "not_found"],
+    transport: "http",
+    notes: "Ends both the future and the already-issued: the consent stops being usable, and every refresh family for that client and user is revoked. `tokens_revoked` reports how many. App-user only."
+  },
+  {
+    method: "GET",
+    path: "/api/client/me",
+    section: "client-auth",
+    summary: "Answers who the calling token is and what it is allowed to reach.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: clientIdentity,
+    errors: [...CLIENT_GUARD],
+    transport: "http",
+    notes: "The one route that answers for all three caller kinds \u2014 a developer bearer, an app-user bearer and a server key \u2014 which is why the shape names each of `developer_id`, `end_user_id` and `server_key_id` and fills exactly one."
+  },
+  /* ------------------------------------------------------------- robots */
+  {
+    method: "POST",
+    path: "/api/robots",
+    section: "robots",
+    summary: "Creates a robot and returns its bridge token once.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 201,
+    params: [],
+    query: null,
+    request: createRobotRequest,
+    response: createRobotResponse,
+    errors: [...DEVELOPER_GUARD, "validation_error", "quota_exceeded"],
+    transport: "http",
+    notes: "`token` is the only moment the raw bridge token exists outside the caller's hands \u2014 the cloud stores a hash, so nothing can read it back and a caller who loses it rotates rather than recovers. Audited: this mints a credential that can speak for the org from anywhere, and the event carries no `details`, because the one interesting value here is the token. `max_robots` is checked before anything is created, which is only safe because robot deletion exists."
+  },
+  {
+    method: "GET",
+    path: "/api/robots",
+    section: "robots",
+    summary: "Lists the org's robots with their connection state and exposure counts.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: robotListResponse,
+    errors: [...DEVELOPER_GUARD],
+    transport: "http"
+  },
+  {
+    method: "GET",
+    path: "/api/robots/:id",
+    section: "robots",
+    summary: "Reads one robot with its published configuration state and live bridge state.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: null,
+    response: robotDetailResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "A robot belonging to another org reads exactly like one that does not exist \u2014 `404`, never a `403`."
+  },
+  {
+    method: "PATCH",
+    path: "/api/robots/:id",
+    section: "robots",
+    summary: "Renames the robot.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: patchRobotRequest,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "validation_error"],
+    transport: "http",
+    notes: 'Answers `{ "robot": robot }`. The envelope has no schema of its own in contracts; the value is a `robot`. The lookup runs before the body is parsed, so a robot outside the caller\'s org answers `404` whether or not the body was also malformed. Saving the name already held writes nothing and records no audit event.'
+  },
+  {
+    method: "GET",
+    path: "/api/robots/:id/deletion-preview",
+    section: "robots",
+    summary: "Reports what deleting the robot would destroy, without destroying it.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: null,
+    response: robotDeletionSummary,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "The same shape the delete's own audit event carries, computed by the same function on purpose: the confirmation dialog and the eventual receipt agree by construction, and any difference between them is real drift \u2014 a robot that kept recording in between \u2014 rather than two estimates that quietly disagree."
+  },
+  {
+    method: "DELETE",
+    path: "/api/robots/:id",
+    section: "robots",
+    summary: "Deletes a robot and everything it produced.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: true,
+    status: 204,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "tier_required", "invalid_uuid", "not_found", "robot_in_use", "robot_deletion_partial"],
+    transport: "http",
+    notes: 'Owner tier, and the gate runs **after** the org-scoped lookup: a developer-tier admin therefore sees the same `404` a stranger would for a robot outside their org, rather than a tier refusal that confirms the id exists. A full cascade \u2014 everything the robot produced goes, except the audit trail, which is a record of what happened and must survive the thing it happened to. An open live session is `409 robot_in_use` unless `?force=true` is passed, matched as the bare string so the caller has to actually say it. A cascade that fails partway is `500 robot_deletion_partial` with the progress, never a bare `internal_error` that would read as "nothing happened".'
+  },
+  {
+    method: "PUT",
+    path: "/api/robots/:id/details",
+    section: "robots",
+    summary: "Replaces the developer-maintained details document shown alongside the robot.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: putRobotDetailsRequest,
+    response: null,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "validation_error"],
+    transport: "http",
+    notes: 'Answers `{ "details": robotDetailsDoc }`. The envelope has no schema of its own in contracts. The update is fanned out to every `/realtime` subscriber of the `robot_details` built-in, so a client watching the robot sees the new document without polling.'
+  },
+  {
+    method: "GET",
+    path: "/api/robots/:id/datapoints",
+    section: "robots",
+    summary: "Lists the datapoints of a robot, filtered to what the caller's role grants.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." }],
+    query: null,
+    request: null,
+    response: datapointListResponse,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "A developer bearer sees the robot's whole list unfiltered; an end user or a server key sees only the slugs their role grants, and a robot their app does not attach answers `404` exactly as one that does not exist."
+  },
+  {
+    method: "GET",
+    path: "/api/robots/:id/exposures",
+    section: "robots",
+    summary: "Lists every grantable slug of a robot with its kind \u2014 the material the roles matrix is built from.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: null,
+    response: exposureListResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "Developer-only: this is what a role *could* be granted, which is a configuration fact rather than something an end user is entitled to enumerate."
+  },
+  {
+    method: "GET",
+    path: "/api/robots/:id/datapoints/:slug",
+    section: "robots",
+    summary: "Reads the latest value of one datapoint.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [
+      { name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." },
+      { name: "slug", description: "The datapoint's slug from the published configuration, as listed by `GET /api/robots/:id/datapoints`." }
+    ],
+    query: null,
+    request: null,
+    response: datapointValue,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found", "unknown_datapoint", "no_data"],
+    transport: "http",
+    notes: "For a client caller the grant check runs **before** any existence lookup, with no extra query on either path to time: a denied slug and a nonexistent one must be one answer. That is why an ungranted slug is `403 forbidden` while a granted-but-unconfigured one is `404 unknown_datapoint` and a configured one with no sample yet is `404 no_data` \u2014 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."
+  },
+  /* ------------------------------------------------- config (draft/publish) */
+  {
+    method: "GET",
+    path: "/api/robots/:id/config/draft",
+    section: "config",
+    summary: "Reads the robot's configuration draft, its author text and its current issues.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: null,
+    response: configDraftResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "Issues are recomputed on every read and every write, so an editor never has to guess whether it may publish. `doc` is `null` for a draft that is valid YAML but not a Fleetless configuration \u2014 a state the format admits and the publish route refuses."
+  },
+  {
+    method: "PUT",
+    path: "/api/robots/:id/config/draft",
+    section: "config",
+    summary: "Replaces the draft with the author's text and answers the parsed document with its issues.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: putConfigDraftRequest,
+    response: configDraftResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "validation_error", "invalid_yaml", "unstorable_yaml"],
+    transport: "http",
+    notes: "The request carries the **text**, not a document: the author's comments and layout are what a restore has to give back, so the source is what is stored and the document is derived from it. Text that is not YAML at all is `422 invalid_yaml`, and text that parses but cannot be stored \u2014 an anchor cycle, say \u2014 is `422 unstorable_yaml`. A document with schema errors is still stored, because the draft is where a developer works; publishing is where the errors block."
+  },
+  {
+    method: "POST",
+    path: "/api/robots/:id/config/publish",
+    section: "config",
+    summary: "Publishes the draft as an immutable version and sends it to the robot.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: null,
+    response: publishConfigResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "validation_error", "draft_not_a_document"],
+    transport: "http",
+    notes: 'A draft that is valid YAML but not a Fleetless configuration is `422 draft_not_a_document`, carrying every issue rather than the blocking subset \u2014 nothing about that text is publishable, so there is no subset to pick, and the warning naming the checks that could not run is part of reading the list correctly. A document with `severity: "error"` issues is `422 validation_error` with just those. The draft\'s own text travels into the version, so a restore later returns what the author wrote rather than a re-rendering of it.'
+  },
+  {
+    method: "GET",
+    path: "/api/robots/:id/config/versions",
+    section: "config",
+    summary: "Lists the published configuration versions of a robot with their publish times.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: null,
+    response: configVersionsResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http"
+  },
+  {
+    method: "GET",
+    path: "/api/robots/:id/config/versions/:v",
+    section: "config",
+    summary: "Reads one published version: its document and the author text it was published from.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [
+      { name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." },
+      { name: "v", description: "The version number, as listed by `GET /api/robots/:id/config/versions`." }
+    ],
+    query: null,
+    request: null,
+    response: configVersionResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "A `:v` that is not a version number and one that names no version of this robot are the same `404`; the refusal quotes what the caller actually sent."
+  },
+  {
+    method: "POST",
+    path: "/api/robots/:id/config/versions/:v/restore",
+    section: "config",
+    summary: "Copies a published version back into the draft, text and document both.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [
+      { name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." },
+      { name: "v", description: "The version number, as listed by `GET /api/robots/:id/config/versions`." }
+    ],
+    query: null,
+    request: null,
+    response: configDraftResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "**Both halves, not just the document** \u2014 a restore that put back the document alone would hand the author a configuration stripped of every comment they wrote, which is the loss this format exists to prevent. The answer is read off the row that was written, not off the version that was meant to be written. Nothing is published: the restored draft still has to be published to reach the robot."
+  },
+  {
+    method: "POST",
+    path: "/api/robots/:id/config/rename-slug",
+    section: "config",
+    summary: "Renames a slug in the draft and rewrites every role grant and history row that named it.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: renameSlugRequest,
+    response: renameSlugResponse,
+    errors: [
+      ...DEVELOPER_GUARD,
+      "invalid_uuid",
+      "not_found",
+      "validation_error",
+      "draft_not_a_document",
+      "unknown_slug",
+      "reserved_slug",
+      "duplicate_slug",
+      "internal_error"
+    ],
+    transport: "http",
+    notes: "One transaction over three places a slug is written down: the draft document, every app-role grant carrying it, and the recorded history rows. The published configuration is immutable, so `requires_publish` says the rename is not live on the robot yet. A draft that is not a document is `409 draft_not_a_document` \u2014 the same word the usage preview uses for the same state."
+  },
+  {
+    method: "GET",
+    path: "/api/robots/:id/config/slug-usage/:slug",
+    section: "config",
+    summary: "Reports what a rename of one slug would touch, before a developer confirms it.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [
+      { name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." },
+      { name: "slug", description: "The slug in the **draft** whose blast radius is being previewed." }
+    ],
+    query: null,
+    request: null,
+    response: slugUsageResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "draft_not_a_document"],
+    transport: "http",
+    notes: "A draft that is valid YAML but not a Fleetless document is refused rather than answered with `alert_count: 0`: the two states are *this slug has no alerts* and *there is no document to ask*, and a zero cannot tell them apart \u2014 it would show a smaller blast radius than the rename actually has. The other three counts are real whatever the draft holds, and a partial answer to a preview whose whole purpose is to be complete is not worth the ambiguity."
+  },
+  /* -------------------------------------------------------------- alerts */
+  {
+    method: "GET",
+    path: "/api/robots/:id/alerts",
+    section: "alerts",
+    summary: "Lists a robot's alerts as defined in its published configuration, joined with their runtime state.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: null,
+    response: alertListResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "**Read-only, and that is the design.** An alert used to be created, edited and deleted through this file; it is now a key in the published document, which is what makes every change to one versioned, comparable and revertible. The **published** version is read, never the draft: an alert typed but not published is evaluated by nothing, and reporting its state would claim a reading no machine has taken."
+  },
+  {
+    method: "GET",
+    path: "/api/org/alerts",
+    section: "alerts",
+    summary: "Lists every firing alert across the org, with the robot each belongs to.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: orgFiringAlertsResponse,
+    errors: [...DEVELOPER_GUARD, "validation_error"],
+    transport: "http",
+    notes: "`?state=firing` is required and is the only value accepted \u2014 refused rather than silently ignored, because a door with one answer must not advertise a dial. There is no query schema; the parameter is read directly. A firing row whose definition has left the document, or has been disabled, is skipped: it can never be evaluated again, so it can never resolve, and it would otherwise sit in the overview's open-issues tile forever."
+  },
+  /* ------------------------------------------------- robots (introspection) */
+  {
+    method: "GET",
+    path: "/api/robots/:id/introspection",
+    section: "robots",
+    summary: "Reads the cached ROS graph of a robot and whether it is stale.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: null,
+    response: introspectionResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "A robot that has never been introspected answers `200` with a **`null` body**, not a `404`: an enrichment that has not happened yet is not a missing resource. The response schema describes the non-null case. `stale` is true whenever the bridge is offline \u2014 the snapshot survives a disconnect, since a robot that has never connected is still configurable."
+  },
+  {
+    method: "POST",
+    path: "/api/robots/:id/introspection/refresh",
+    section: "robots",
+    summary: "Asks the robot for a fresh ROS graph, stores it and answers it.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: null,
+    response: introspectionResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "robot_offline", "bridge_timeout"],
+    transport: "http",
+    notes: "`stale` is `false` by construction here: the graph came from the robot just now. `409 robot_offline` means nothing is connected; `504 bridge_timeout` means something was and did not answer. Anything else is rethrown rather than turned into a tidy status."
+  },
+  {
+    method: "GET",
+    path: "/api/robots/:id/types",
+    section: "robots",
+    summary: "Lists every ROS message type definition stored for the robot.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: null,
+    response: typesResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "A plain read with no bridge involved \u2014 the robot need not be online."
+  },
+  {
+    method: "POST",
+    path: "/api/robots/:id/types/fetch",
+    section: "robots",
+    summary: "Fetches named message type definitions from the robot and stores them.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: fetchTypesRequest,
+    response: fetchTypesResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "validation_error", "robot_offline", "bridge_timeout"],
+    transport: "http",
+    notes: "`unresolved` names the types the robot could not produce; it is an answer, not a failure, because a graph often references a type whose package is not installed. The robot lookup runs before the body is parsed, so a robot outside the caller's org answers `404` whether or not the body was also malformed."
+  },
+  /* ---------------------------------------------- commands (jobs, publishers) */
+  {
+    method: "GET",
+    path: "/api/robots/:id/jobs",
+    section: "commands",
+    summary: "Reads the current job on every slug of the robot the caller is granted.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." }],
+    query: null,
+    request: null,
+    response: robotJobsResponse,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "**At most one entry per slug, and not a history endpoint.** The first version answered every job the registry still held \u2014 six rows and four full result payloads after a few minutes of traffic on one robot, unbounded for a robot that has run all day. This reads the one-current-job-per-slug map instead. It exists because the per-slug route alone cannot cover it: a reconciled-but-unminted job, or one left on a slug a republish removed, has no slug-shaped door to be found through."
+  },
+  {
+    method: "GET",
+    path: "/api/robots/:id/jobs/history",
+    section: "commands",
+    summary: "Reads what has run on the robot, newest first, cursor-paged.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." }],
+    query: jobRunQuery,
+    request: null,
+    response: jobRunListResponse,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found", "capability_required", "validation_error"],
+    transport: "http",
+    notes: "Needs the `action_history` capability, and **this route is what makes that switch mean something** \u2014 it was unkeepable while nothing durable recorded what had run. Two residuals worth stating rather than implying away. `history` is a syntactically valid slug and Fastify matches a static segment first, so a robot with a service literally slugged `history` can no longer be **read** through `GET /api/robots/:id/jobs/:slug`; invoking, cancelling and the listing are unaffected. And a run row names its actor by email address, so an end user holding this capability learns which other people have been driving the machine. `robot_id` in the query is shared with the org-wide read; a *different* one here is refused rather than quietly answered about the robot in the path."
+  },
+  {
+    method: "POST",
+    path: "/api/robots/:id/jobs/:slug",
+    section: "commands",
+    summary: "Invokes an action or calls a service on the robot.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 202,
+    params: [
+      { name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." },
+      { name: "slug", description: "The action or service slug from the published configuration; the cloud already knows which kind it is." }
+    ],
+    query: null,
+    request: invokeRequest,
+    response: invokeOrServiceResponse,
+    errors: [
+      ...CLIENT_GUARD,
+      "invalid_uuid",
+      "not_found",
+      "validation_error",
+      "parameter_invalid",
+      "robot_offline",
+      "busy",
+      "bridge_timeout",
+      "internal_error"
+    ],
+    transport: "http",
+    notes: "**One route for both kinds**, because a path segment naming the kind would demand a fact a role grant does not carry. An action answers `202` with an `invokeResponse` the moment the job exists; a service answers `200` with a `serviceCallResponse` once the result is in \u2014 two shapes, carried by one union (`invokeOrServiceResponse`) and told apart by whether `kind` or a bare `result` arrives. Parameters are checked **before** anything about the world (offline, busy): the same request must get the same verdict whether or not the robot happens to be reachable, or a developer testing against an offline robot never learns their parameters were wrong. A service the robot reports as failed answers `502` carrying **the job's own error code**, which is an open set and not one of the codes above."
+  },
+  {
+    method: "GET",
+    path: "/api/robots/:id/jobs/:slug",
+    section: "commands",
+    summary: "Reads the most recent job on one slug.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [
+      { name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." },
+      { name: "slug", description: "The action or service slug from the published configuration." }
+    ],
+    query: null,
+    request: null,
+    response: jobResponse,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "`job` is `null` when nothing has ever run on that slug \u2014 an answer, not a `404`."
+  },
+  {
+    method: "POST",
+    path: "/api/robots/:id/jobs/:slug/cancel",
+    section: "commands",
+    summary: "Cancels the job running on one slug.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [
+      { name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." },
+      { name: "slug", description: "The action slug from the published configuration; a service slug is refused." }
+    ],
+    query: null,
+    request: cancelRequest,
+    requestOptional: true,
+    response: jobResponse,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found", "validation_error", "not_cancellable", "robot_offline"],
+    transport: "http",
+    notes: 'The body is optional: a bodyless `POST` was every caller\'s shape before `job_id` existed, and absent or `job_id: null` both mean "cancel whatever is running". A named `job_id` that is **not** what is running cancels nothing and answers `404` \u2014 the caller named an id and thereby ruled the other one out. A service is `422 not_cancellable`: a service call has no goal to cancel. Nothing running is a `200` with `job: null`.'
+  },
+  {
+    method: "POST",
+    path: "/api/robots/:id/publishers/:slug",
+    section: "commands",
+    summary: "Publishes one message onto a configured publisher.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 204,
+    params: [
+      { name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." },
+      { name: "slug", description: "The publisher slug from the published configuration." }
+    ],
+    query: null,
+    request: publishRequest,
+    response: null,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found", "validation_error", "parameter_invalid", "robot_offline", "publisher_busy"],
+    transport: "http",
+    notes: "Fire and forget \u2014 not a job, so there is nothing to poll and nothing to cancel. A publisher is held exclusively by one caller until it has been quiet long enough, and another caller meanwhile is `409 publisher_busy` with the timeout and a retry hint. Parameters are checked before offline and before exclusivity, the same order the invoke path uses and for the same reason. The **acquisition** is audited, not every message: auditing only takeovers left the single-operator case with no record of who was driving at all."
+  },
+  /* ------------------------------------------------------------- cameras */
+  {
+    method: "GET",
+    path: "/api/robots/:id/cameras",
+    section: "cameras",
+    summary: "Lists the cameras of a robot, filtered to what the caller's role grants.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." }],
+    query: null,
+    request: null,
+    response: cameraListResponse,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found"],
+    transport: "http"
+  },
+  {
+    method: "GET",
+    path: "/api/robots/:id/cameras/:slug/snapshot",
+    section: "cameras",
+    summary: "Returns the most recent snapshot frame as image bytes.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [
+      { name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." },
+      { name: "slug", description: "The camera slug from the published configuration, as listed by `GET /api/robots/:id/cameras`." }
+    ],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found", "no_snapshot_yet"],
+    transport: "http",
+    notes: 'Image bytes, not JSON, so it has no response schema; the age, capture time and dimensions ride in the `x-fleetless-*` headers `SNAPSHOT_HEADERS` names \u2014 which a browser can only read because CORS exposes them. **Never checks whether the bridge is online**: a snapshot read is a pure cache read, which is what makes "the last frame, with its real age" true for free across a disconnect. There is nothing here to refuse, and `age_ms` carries the whole honesty story. `cache-control: no-store`, because a picture of someone\'s premises does not belong on disk longer than the request that fetched it.'
+  },
+  {
+    method: "GET",
+    path: "/api/robots/:id/cameras/:slug/snapshot/meta",
+    section: "cameras",
+    summary: "Reports the age and dimensions of the latest snapshot without downloading it.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [
+      { name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." },
+      { name: "slug", description: "The camera slug from the published configuration, as listed by `GET /api/robots/:id/cameras`." }
+    ],
+    query: null,
+    request: null,
+    response: snapshotMetaResponse,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: 'Exists so a client polling at the camera\'s own interval does not re-fetch a whole frame merely to learn whether a newer one arrived. Nothing captured yet is **nulls, not a `404`**: "nothing yet" is an answer.'
+  },
+  {
+    method: "POST",
+    path: "/api/robots/:id/cameras/:slug/live",
+    section: "cameras",
+    summary: "Takes a hold on a live camera stream and returns a room token.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 201,
+    params: [
+      { name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." },
+      { name: "slug", description: "The camera slug from the published configuration, as listed by `GET /api/robots/:id/cameras`." }
+    ],
+    query: null,
+    request: null,
+    response: liveSessionResponse,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found", "robot_offline", "camera_offline", "live_unavailable"],
+    transport: "http",
+    notes: "Refcounted: the first viewer starts the robot publishing and the last release stops it. No token is ever minted for an ungranted or offline camera \u2014 both refusals return before the hold is taken. `409 camera_offline` means the **robot itself** reported the failure; `502 live_unavailable` means this cloud could not start the stream. The difference matters, and it is why a failure the robot named is never dressed up as one this side invented."
+  },
+  {
+    method: "DELETE",
+    path: "/api/robots/:id/cameras/:slug/live",
+    section: "cameras",
+    summary: "Releases a live hold, one session or all of this caller's.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 204,
+    params: [
+      { name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." },
+      { name: "slug", description: "The camera slug from the published configuration, as listed by `GET /api/robots/:id/cameras`." }
+    ],
+    query: releaseLiveQuery,
+    request: null,
+    response: null,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "`?session_id=` releases that one hold; omitting it releases every hold this caller's identity has on this camera, which a client that lost its id \u2014 or a tab that is already closing \u2014 still needs. A malformed `session_id` is `400 invalid_uuid`, never a silent fallback to the blunt form, which would strand this identity's other tabs over a typo. A named-and-unknown id is `404`; a stale one, real and already ended, is idempotently `204`."
+  },
+  /* -------------------------------------------------------- robots (history) */
+  {
+    method: "GET",
+    path: "/api/robots/:id/datapoints/:slug/history",
+    section: "robots",
+    summary: "Reads recorded samples of one datapoint, or aggregated buckets over a window.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [
+      { name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." },
+      { name: "slug", description: "The datapoint's slug from the published configuration." }
+    ],
+    query: historyQuery,
+    request: null,
+    response: historyResponse,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found", "validation_error", "invalid_range", "not_recorded", "not_aggregatable"],
+    transport: "http",
+    notes: "Two answers, carried by one union (`historyResponse`): without `window` it is a `historySamplesResponse`, with one it is a `historyBucketsResponse`, told apart by `kind`. `window` and `agg` must be given together or not at all \u2014 one without the other is refused rather than defaulted, since a silently chosen aggregation is a chart that lies quietly. A range and window that would produce more buckets than `limit` is `400 invalid_range` computed **before** the query runs: the bucket response carries no `truncated` field, so a refusal is the only honest answer. `409 not_recorded` says retention is off for this slug **right now** and deliberately does not claim the table is empty \u2014 rows written before the switch was flipped still exist, unreadable through any route and still counting against the quota."
+  },
+  /* ------------------------------------------------------ assets (URDF, meshes) */
+  {
+    method: "GET",
+    path: "/api/robots/:id/assets",
+    section: "assets",
+    summary: "Lists the robot's synced assets and how complete its URDF is.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." }],
+    query: null,
+    request: null,
+    response: assetListResponse,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found", "capability_required"],
+    transport: "http",
+    notes: "Needs the `assets` capability, refused as `403 capability_required` rather than a bare `forbidden`: the code says a capability is missing and the message says which, so a developer who switched the wrong toggle on is told what to switch. The capability is checked before existence, so a denied robot and an absent one read alike to a caller with no right to tell them apart. `urdf` reports whether a URDF is present and which of its mesh references have no stored asset."
+  },
+  {
+    method: "GET",
+    path: "/api/robots/:id/assets/:assetId",
+    section: "assets",
+    summary: "Returns one stored asset as bytes.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [
+      { name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." },
+      { name: "assetId", description: "The asset's uuid, as listed by `GET /api/robots/:id/assets`." }
+    ],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found", "capability_required", "internal_error"],
+    transport: "http",
+    notes: 'Bytes in the asset\'s own media type, so it has no response schema. A row whose blob has vanished from object storage is a logged `500 internal_error`, not a `404`: the asset exists and this cloud could not read it, which is a different fact from "there is no such asset".'
+  },
+  {
+    method: "GET",
+    path: "/api/robots/:id/urdf",
+    section: "assets",
+    summary: "Returns the robot's URDF with every mesh reference rewritten to a Fleetless URL.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found", "capability_required", "internal_error"],
+    transport: "http",
+    notes: "XML, so no response schema. **Every `filename` is rewritten, not only a resolvable `package://` one** \u2014 an absolute URL that arrived in a URDF from ROS graph input must never be served through untouched, because a mesh loader attaches the caller's bearer token to whatever absolute URL it is handed. Anything with no stored asset points at `GET /api/robots/:id/assets/missing` instead. A robot with no synced URDF is `404`."
+  },
+  {
+    method: "GET",
+    path: "/api/robots/:id/assets/missing",
+    section: "assets",
+    summary: "The placeholder a rewritten URDF points at for a mesh Fleetless does not hold.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 404,
+    params: [{ name: "id", description: "The robot's uuid; an end user reaches it through an app that attaches it." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found", "capability_required", "asset_missing"],
+    transport: "http",
+    notes: "**This route has no success answer** \u2014 `404 asset_missing` naming the unresolved reference is what it exists to give, and `status` says so rather than declaring a `200` no caller can ever receive. `?name=` is echoed into the message and is read directly, with no query schema; it discloses nothing, since it is what the caller sent. It carries the same `assets` capability gate as the real bytes would: a missing-asset placeholder is not an exemption from the authorization the thing it stands in for needs."
+  },
+  {
+    method: "GET",
+    path: "/api/asset-links/missing",
+    section: "assets",
+    summary: "The bearer-free placeholder a *linked* URDF points at for an unresolvable mesh.",
+    audience: "client",
+    auth: "in_handler",
+    rateLimited: false,
+    ownerTier: false,
+    status: 404,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: ["asset_missing"],
+    transport: "http",
+    notes: "**No success answer either**, for the reason its authenticated twin has none. Unauthenticated by design and unauthenticated in fact: it reads nothing and reveals nothing the caller did not put in the query string itself, so there is no credential for the handler to verify and none is required. It sits under the signed-link prefix because that is where a linked URDF's references have to point."
+  },
+  {
+    method: "GET",
+    path: "/api/asset-links/:token",
+    section: "assets",
+    summary: "Serves one asset, or a rendered URDF, to whoever holds a signed link.",
+    audience: "client",
+    auth: "in_handler",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "token", description: "The signed, time-limited link an MCP tool minted; it is the whole credential." }],
+    query: null,
+    request: null,
+    response: null,
+    errors: ["not_found", "internal_error"],
+    transport: "http",
+    notes: "**The token is the authorization** \u2014 there is no route guard on purpose, and verifying it is the whole gate. An MCP session token is refused on REST by design, so the asset tools mint a fifteen-minute signed link instead and this spends it. The capability was checked at mint against the minting caller's own access; the residual \u2014 whoever holds the URL reads that asset until it expires \u2014 is named rather than closed by a second gate, which would be a different policy for one decision. Every refusal collapses into one `404` with one message, including a malformed id inside a validly signed token, because a link holder has no business learning which of them it was. A URDF served this way has **its own references minted as links**, back-dated so they expire with the parent \u2014 otherwise spending a link in its last second would hand out another fifteen minutes, and each of those another. `cache-control: no-store`, since the URL itself is the credential."
+  },
+  {
+    method: "POST",
+    path: "/api/robots/:id/assets/sync",
+    section: "assets",
+    summary: "Asks the robot to upload its URDF and meshes, and returns the sync id.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: true,
+    status: 202,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: assetSyncRequest,
+    response: assetSyncResponse,
+    errors: [...CLIENT_GUARD, "tier_required", "invalid_uuid", "validation_error", "not_found", "robot_offline", "busy"],
+    transport: "http",
+    notes: "Owner tier, unconditionally. The guard admits an end user or a server key, but only a developer session gets past the handler \u2014 and the body is parsed **before** that `401`, because this route has always answered a malformed body first and the order has to survive. The request is strict: a caller naming a source that does not exist learns so, instead of silently getting a bridge sync they did not ask for. A robot that has reported nothing available to sync is `404`. A second sync is `409 busy` naming the `sync_id` that is actually running, so the caller who pressed the button twice can pick it straight up."
+  },
+  {
+    method: "GET",
+    path: "/api/robots/:id/assets/sync/:syncId",
+    section: "assets",
+    summary: "Reports how far an asset sync has got.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [
+      { name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." },
+      { name: "syncId", description: "The sync id from `POST /api/robots/:id/assets/sync`, or from its `409 busy` refusal." }
+    ],
+    query: null,
+    request: null,
+    response: assetSyncStatus,
+    errors: [...CLIENT_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "Developer sessions only, like starting a sync: the guard admits three caller kinds and the handler answers `401 unauthorized` to the other two. A sync belonging to another robot reads exactly like one that never existed, which is why the robot is resolved first."
+  },
+  /* ------------------------------------------------ org (quotas and fleet reads) */
+  {
+    method: "GET",
+    path: "/api/org/quotas",
+    section: "org",
+    summary: "Reports every quota's limit next to what the org is currently using.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: orgQuotaUsage,
+    errors: [...DEVELOPER_GUARD],
+    transport: "http",
+    notes: "Every dial is read at the moment of the call and nothing is cached, so an exhausted quota is self-evident from this one answer rather than something a developer needs audit access to discover. `max_end_users` counts app users only \u2014 an org admin is not an app user, and counting the whole pool would report the Owner an org has by construction as consumption."
+  },
+  {
+    method: "GET",
+    path: "/api/org/health",
+    section: "org",
+    summary: "Reports the health of every camera and streaming resource across the org.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: null,
+    request: null,
+    response: resourceHealthListResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "`?robot_id=` narrows it to one robot; there is no query schema, the parameter is read directly. Org-wide rather than per-robot because the console shows health on the robot list too, and a per-robot path would make that N requests to render one screen. This is the snapshot half of the channel; the live half is the `/realtime` socket."
+  },
+  {
+    method: "GET",
+    path: "/api/org/jobs",
+    section: "org",
+    summary: "Reads durable job-run history across the org, newest first, cursor-paged.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: jobRunQuery,
+    request: null,
+    response: jobRunListResponse,
+    errors: [...DEVELOPER_GUARD, "validation_error"],
+    transport: "http",
+    notes: "Developer-only, and that is a property of the scope: a run row names the actor who invoked it, so a client-facing version would tell one end user which others have been driving the machine. Page until the cursor is null, not until a page looks short. A malformed `robot_id` is refused by the query schema as a `validation_error`; an unknown but well-formed one is an empty list, never a `404` \u2014 it is a filter."
+  },
+  {
+    method: "GET",
+    path: "/api/org/jobs/summary",
+    section: "org",
+    summary: "Counts the running, started and failed job runs since a moment the caller names.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: jobRunSummaryQuery,
+    request: null,
+    response: jobRunSummary,
+    errors: [...DEVELOPER_GUARD, "validation_error"],
+    transport: "http",
+    notes: '`since_ms` is required and has no default: which day "today" is, only the browser knows, and a cloud that chose its own boundary would show a developer in another timezone a number they cannot reproduce. The window is echoed back so a rendered tile can say what it is describing.'
+  },
+  {
+    method: "GET",
+    path: "/api/org/latency",
+    section: "org",
+    summary: "Reads one-minute bridge latency buckets per robot over a window the caller names.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: orgLatencyQuery,
+    request: null,
+    response: orgLatencyResponse,
+    errors: [...DEVELOPER_GUARD, "validation_error"],
+    transport: "http",
+    notes: 'Both bounds are required: the table holds a bucket per robot per minute, so "everything" is thousands of rows per robot and a default window would be a query size chosen by whoever forgot to pass one. `from_ms < to_ms` is a cross-field rule the published JSON Schema cannot express, so this route is the only place it is enforced. `truncated` costs whole robots off the end of the id order, not the tail of every series \u2014 narrow the window or name a `robot_id`.'
+  },
+  {
+    method: "GET",
+    path: "/api/org/usage",
+    section: "org",
+    summary: "Reads what the org consumed per day, per app and per metric.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [],
+    query: orgUsageQuery,
+    request: null,
+    response: orgUsageResponse,
+    errors: [...DEVELOPER_GUARD, "validation_error"],
+    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."
+  },
+  /* ------------------------------------------------- assets (robot upload) */
+  {
+    method: "POST",
+    path: "/api/bridge/assets",
+    section: "assets",
+    summary: "Takes one asset file from a robot during a sync.",
+    audience: "internal",
+    auth: "robot_upload",
+    rateLimited: false,
+    ownerTier: false,
+    status: 201,
+    params: [],
+    query: null,
+    request: null,
+    response: asset,
+    errors: ["unauthorized", "rate_limited", "asset_too_large", "validation_error", "not_found", "quota_exceeded", "bad_request"],
+    transport: "http",
+    notes: "The body is the **raw file bytes**, not JSON, so it has no request schema; everything about the file \u2014 its kind, its name, its sync id and its announced size \u2014 rides in the `x-fleetless-asset-*` headers `ASSET_UPLOAD_HEADERS` names. The credential is a short-lived upload token minted by `POST /api/robots/:id/assets/sync`, verified in a `preParsing` hook so a refusal precedes the work rather than following it: a `preHandler` would already have buffered the whole file. The announced size is refused there too, before a single byte is read \u2014 it is an announcement and not a proof, so it only ever rejects early and never accepts early, and a body that lies small is still caught by the real length check. Past both, Fastify's own body limit answers a bare `413 bad_request` with neither ceiling nor size in it. Rate limited per robot inside that same hook, which is why `rateLimited` is `false`: there is no rate-limiting preHandler registered on this route."
+  },
+  /* ------------------------------------ realtime and bridge transports */
+  {
+    method: "GET",
+    path: "/bridge",
+    section: "transports",
+    summary: "The robot bridge's WebSocket: the versioned bridge protocol, not a client-facing surface.",
+    audience: "internal",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 101,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: ["protocol_mismatch", "invalid_token"],
+    transport: "websocket"
+  },
+  {
+    method: "GET",
+    path: "/realtime",
+    section: "transports",
+    summary: "The client WebSocket: subscriptions on datapoints, jobs, bridge state and presence, plus full command parity with REST.",
+    audience: "client",
+    auth: "none",
+    rateLimited: false,
+    ownerTier: false,
+    status: 101,
+    params: [],
+    query: null,
+    request: null,
+    response: null,
+    errors: ["invalid_token", "rate_limited"],
+    transport: "websocket",
+    notes: "Authentication happens in the first frame, not on the upgrade. The frame types are the `realtime` schemas."
+  }
+];
+
 // src/pkce.ts
 function requireCrypto() {
   const c = globalThis.crypto;
@@ -5391,9 +8812,14 @@ function createSlugSubscriptions(channel) {
 // src/token-store.ts
 var InMemoryTokenStore = class {
   #session = null;
+  /** Creates an empty store. Nothing is loaded from anywhere — a client built with it starts logged out. */
+  constructor() {
+  }
+  /** Returns the session held in memory, or `null` if there is none. */
   load() {
     return this.#session;
   }
+  /** Replaces the session held in memory; `null` clears it. */
   save(session) {
     this.#session = session;
   }