@fleetless/sdk 2.0.2 → 2.1.0

package/dist/index.d.cts

@@ -543,7 +543,7 @@ type ParameterInvalidDetails = z.infer<typeof parameterInvalidDetails>;
  * list is the shared vocabulary, not a closed set, so a new refusal never
  * needs a contracts release before it can be reported honestly.
  */
-declare const ERROR_CODES: readonly ["not_found", "validation_error", "bad_request", "unknown_datapoint", "invalid_token", "protocol_mismatch", "invalid_frame", "duplicate_slug", "reserved_slug", "unknown_slug", "unknown_field_path", "unknown_type", "unknown_topic", "invalid_rate", "invalid_range", "config_conflict", "no_data", "robot_offline", "bridge_timeout", "unauthorized", "forbidden", "invalid_credentials", "token_expired", "token_revoked", "invite_expired", "invite_used", "email_taken", "identifier_taken", "weak_password", "account_blocked", "busy", "parameter_invalid", "job_lost", "publisher_busy", "unknown_command", "not_subscribable", "camera_offline", "no_snapshot_yet", "live_unavailable", "wrong_kind", "not_recorded", "not_aggregatable", "quota_exceeded", "credential_in_use", "goal_timeout", "robot_in_use", "robot_deletion_partial", "job_queue_full", "invalid_uuid", "rate_limited", "tier_required", "token_spent", "service_timeout", "asset_missing", "asset_too_large", "dynamic_registration_disabled", "client_limit_reached", "identity_conflict", "identity_not_provisioned", "idp_unavailable", "mcp_disabled", "tool_not_available", "capability_required", "last_owner", "group_not_deletable", "group_in_use", "target_state_conflict", "mcp_access_denied", "signup_closed"];
+declare const ERROR_CODES: readonly ["not_found", "validation_error", "bad_request", "unknown_datapoint", "invalid_token", "protocol_mismatch", "invalid_frame", "duplicate_slug", "reserved_slug", "unknown_slug", "unknown_field_path", "unknown_type", "unknown_topic", "invalid_rate", "invalid_range", "config_conflict", "no_data", "robot_offline", "bridge_timeout", "unauthorized", "forbidden", "invalid_credentials", "token_expired", "token_revoked", "invite_expired", "invite_used", "email_taken", "identifier_taken", "weak_password", "account_blocked", "busy", "parameter_invalid", "job_lost", "publisher_busy", "unknown_command", "not_subscribable", "camera_offline", "no_snapshot_yet", "live_unavailable", "wrong_kind", "not_recorded", "not_aggregatable", "quota_exceeded", "credential_in_use", "goal_timeout", "robot_in_use", "robot_deletion_partial", "job_queue_full", "invalid_uuid", "rate_limited", "tier_required", "token_spent", "service_timeout", "asset_missing", "asset_too_large", "dynamic_registration_disabled", "client_limit_reached", "identity_conflict", "identity_not_provisioned", "idp_unavailable", "mcp_disabled", "tool_not_available", "capability_required", "last_owner", "group_not_deletable", "group_in_use", "target_state_conflict", "mcp_access_denied", "signup_closed", "draft_not_a_document", "internal_error", "not_cancellable", "unsupported_media_type", "wrong_browser", "invalid_yaml", "unstorable_yaml"];
 type ErrorCode = (typeof ERROR_CODES)[number];
 
 /**
@@ -620,7 +620,7 @@ type ConsentRevokeResponse = z.infer<typeof consentRevokeResponse>;
  * Codes the SDK produces itself rather than relaying from the server. Kept
  * out of `@fleetless/contracts`' `ERROR_CODES` deliberately — that list is
  * the *wire* vocabulary, every entry something a server may actually send,
- * and none of these are. Two kinds:
+ * and none of these are.
  *
  * - `no_session` / `no_websocket`: a client-side refusal *before* a request
  *   ever reaches the network (not logged in; no WebSocket implementation
@@ -628,102 +628,106 @@ type ConsentRevokeResponse = z.infer<typeof consentRevokeResponse>;
  *   caller can tell "the server refused me" from "the SDK refused before
  *   asking" by the code alone.
  * - `unparseable_error`: the opposite direction — a real response *did*
- *   arrive, its body just wasn't shaped like §11.5's error format. Not a
- *   refusal at all, just "we don't know what the server said."
- * - `command_timeout` (W4): a realtime command (`invoke`/`cancel`/`publish`)
- *   got no `command_result` within its timeout. The server may still answer
+ *   arrive, its body just was not shaped like the platform's error format.
+ *   Not a refusal at all, just "we do not know what the server said."
+ * - `command_timeout`: a realtime command (`invoke`/`cancel`/`publish`) got
+ *   no `command_result` within its timeout. The server may still answer
  *   later on the same socket — nobody knows — but the caller cannot be made
  *   to wait forever for that.
- * - `command_outcome_unknown` (W4): worse than a timeout, and told apart
- *   from it on purpose — the realtime connection that carried the command
- *   was replaced by a new one (a reconnect) before any reply arrived. A
- *   reply can now never come: the server, if it answered at all, answered a
+ * - `command_outcome_unknown`: worse than a timeout, and told apart from it
+ *   on purpose — the realtime connection that carried the command was
+ *   replaced by a new one (a reconnect) before any reply arrived. A reply
+ *   can now never come: the server, if it answered at all, answered a
  *   socket that no longer exists. The command may or may not have run.
  *   Never retried automatically — that could run an action twice — the
  *   caller recovers by reading the job (e.g. `actions.subscribe`), since
  *   state is observed by slug regardless of which connection asked for it.
- * - `unexpected_response` (W4): the server answered `ok:true` but left out
+ * - `unexpected_response`: the server answered `ok:true` but left out
  *   something the command is defined to always return (e.g. no `job` on a
  *   successful `invoke`) — a contract violation the SDK noticed, not a
  *   refusal.
- * - `invalid_option` (W6b): the caller passed an *SDK-level* argument or
- *   option that cannot mean what it looks like it means. Two cases so far:
- *   `timeoutMs < patienceMs` on `invoke`/`call` (see `resolveLocalWaitMs` in
- *   `commands.ts`) — the SDK would give up locally before the platform's own
- *   patience runs out, and report `command_timeout` for a call the platform
- *   never actually refused; and a non-string, non-null, non-omitted `jobId`
- *   on `cancel` (D6, see `assertValidJobId`) — almost always a caller who
- *   upgraded past the pre-W6b `cancel(robotId, slug, options?)` signature
- *   and is still passing an options object third. Both are thrown
- *   synchronously, before any request is sent — a client-side mistake to
- *   fix, not something a server response could ever produce, which is why
- *   this code belongs here and not in `@fleetless/contracts`' `ERROR_CODES`.
- * - `untrusted_absolute_url` (W7): `HttpClient` refused to fetch an absolute
- *   URL whose origin does not match this client's own configured `baseUrl`
- *   — thrown before the request is ever sent, so no `Authorization` header
- *   is ever built for it, let alone attached. The one caller that hands
- *   `HttpClient` an absolute URL at all is `assets.createMeshLoader`
- *   (§4.6), fetching a URDF's rewritten mesh URIs — and a URDF is ROS graph
- *   input, not first-party data, so an app rendering one must not silently
- *   trust wherever it points. `assets.createMeshLoader`'s `onComplete`
- *   surfaces this the same way it surfaces a network failure: `(null, err)`.
- * - `no_urdf_synced` (W7a): `assets.prepareUrdfScene` looked for a
- *   `kind: 'urdf'` row in `assets.list()` and found none. Thrown before any
- *   asset fetch, rather than left to surface as a confusing downstream
- *   failure from `URDFLoader.parse(undefined)` or similar — the caller's
- *   fix is "sync a URDF first" (console, Owner-tier, §4.6), which this
- *   error can say directly.
- * - `no_hosted_login_attempt` (W7b, Momus's review): `auth.completeHostedLogin()`
- *   was called with an empty `expectedState` — nothing was persisted for
- *   this attempt. A callback landing in a different tab or window than the
- *   one that called `beginHostedLogin`, a restored session, or storage
- *   cleared in between all produce exactly this, and none of them is an
- *   attack. Told apart from `state_mismatch` on purpose: the two diagnoses
- *   have different remedies ("check how you persisted the value" versus
- *   "this response belongs to a login you did not start"), the same
- *   reasoning this wave already applied once to `identity_conflict` versus
- *   `identity_not_provisioned`. Also closes a real gap — comparing two
- *   *empty* strings with `!==` is `false`, so without this check first, a
- *   caller with nothing persisted at all could reach `state_mismatch`'s
- *   comparison having contributed no defence whatsoever.
- * - `aborted` (register row 244, W7c): `assets.prepareUrdfScene()` was given
- *   an `AbortSignal` and it fired — either already-aborted before the call
- *   started, or mid-flight while a fetch was in progress. Normalized to this
- *   one code regardless of which stage the abort landed in, rather than
- *   surfacing whatever shape the underlying `fetch()` rejects an aborted
- *   request with (a `DOMException` named `AbortError` in a browser, an
- *   `Error` named `AbortError` under Node's `fetch` — two different shapes a
- *   caller would otherwise have to detect themselves to tell "I cancelled
- *   this" from "the network actually failed"). Every partial resource this
- *   call had already created (`blob:` URLs) is revoked before this throws —
- *   an aborted load must not leak what it fetched before the signal fired,
- *   the same guarantee a failed load already had (D6).
- * - `state_mismatch` (W7b): `auth.completeHostedLogin()` was called with a
- *   `state` that does not match the `expectedState` its own `beginHostedLogin()`
+ * - `invalid_option`: the caller passed an *SDK-level* argument or option
+ *   that cannot mean what it looks like it means. Three cases so far:
+ *   `timeoutMs < patienceMs` on `invoke`/`call` — the SDK would give up
+ *   locally before the platform's own patience runs out, and report
+ *   `command_timeout` for a call the platform never actually refused; a
+ *   non-string, non-null, non-omitted `jobId` on `cancel` — almost always a
+ *   caller who upgraded past the older `cancel(robotId, slug, options?)`
+ *   signature and is still passing an options object third; and a
+ *   `concurrency` on `assets.prepareUrdfScene` that is not a positive
+ *   integer, which would otherwise fetch nothing and return a scene that
+ *   renders blank with no error to explain why. All three are refused
+ *   before any request is sent — as a rejection, since every one of those
+ *   methods is `async`. A client-side mistake to fix, not something a
+ *   server response could ever produce, which is why this code belongs here
+ *   and not in `@fleetless/contracts`' `ERROR_CODES`.
+ * - `untrusted_absolute_url`: the SDK refused to fetch an absolute URL
+ *   whose origin does not match this client's own `apiUrl` — thrown before
+ *   the request is ever sent, so no `Authorization` header is ever built for
+ *   it, let alone attached. The one caller that fetches an absolute URL at
+ *   all is `assets.createMeshLoader`, following a URDF's rewritten mesh
+ *   URIs — and a URDF is ROS graph input, not first-party data, so an app
+ *   rendering one must not silently trust wherever it points.
+ *   `assets.createMeshLoader`'s `onComplete` surfaces this the same way it
+ *   surfaces a network failure: `(null, err)`.
+ * - `no_urdf_synced`: `assets.prepareUrdfScene` looked for a `kind: 'urdf'`
+ *   row in `assets.list()` and found none. Thrown before any asset fetch,
+ *   rather than left to surface as a confusing downstream failure from
+ *   `URDFLoader.parse(undefined)` or similar — the caller's fix is "sync a
+ *   URDF first", which this error can say directly.
+ * - `no_hosted_login_attempt`: `auth.completeHostedLogin()` was called with
+ *   an empty `expectedState` — nothing was persisted for this attempt. A
+ *   callback landing in a different tab or window than the one that called
+ *   `beginHostedLogin`, a restored session, or storage cleared in between
+ *   all produce exactly this, and none of them is an attack. Told apart
+ *   from `state_mismatch` on purpose: the two diagnoses have different
+ *   remedies ("check how you persisted the value" versus "this response
+ *   belongs to a login you did not start"). It also closes a real gap —
+ *   comparing two *empty* strings with `!==` is `false`, so without this
+ *   check first, a caller with nothing persisted at all could reach
+ *   `state_mismatch`'s comparison having contributed no defence whatsoever.
+ * - `aborted`: `assets.prepareUrdfScene()` was given an `AbortSignal` and it
+ *   fired — either already-aborted before the call started, or mid-flight
+ *   while a fetch was in progress. Normalized to this one code regardless of
+ *   which stage the abort landed in, rather than surfacing whatever shape
+ *   the underlying `fetch()` rejects an aborted request with (a
+ *   `DOMException` named `AbortError` in a browser, an `Error` named
+ *   `AbortError` under Node's `fetch` — two different shapes a caller would
+ *   otherwise have to detect themselves to tell "I cancelled this" from "the
+ *   network actually failed"). Every partial resource this call had already
+ *   created (`blob:` URLs) is revoked before this throws — an aborted load
+ *   must not leak what it fetched before the signal fired, the same
+ *   guarantee a failed load already had.
+ * - `state_mismatch`: `auth.completeHostedLogin()` was called with a `state`
+ *   that does not match the `expectedState` its own `beginHostedLogin()`
  *   returned for this attempt (or with no `state` at all — `beginHostedLogin`
  *   always sets one, so a callback carrying none does not look like a reply
  *   to a flow this client started). Thrown before `/oauth/token` is ever
- *   called — RFC 6749 §10.12's whole point is that a caller must not
+ *   called: RFC 6749 section 10.12's whole point is that a caller must not
  *   complete an authorization response it did not itself request, so this
  *   check happens client-side, first, rather than being left to the server
- *   to catch (by which point a code exchange would already have been
- *   attempted for a flow this client never started).
+ *   to catch — by which point a code exchange would already have been
+ *   attempted for a flow this client never started.
  */
 declare const SDK_ERROR_CODES: readonly ["no_session", "no_websocket", "unparseable_error", "command_timeout", "command_outcome_unknown", "unexpected_response", "invalid_option", "untrusted_absolute_url", "state_mismatch", "no_hosted_login_attempt", "no_urdf_synced", "aborted"];
+/**
+ * The union of `SDK_ERROR_CODES` — the SDK's own client-side error
+ * vocabulary. A `FleetlessError` whose `code` is one of these was raised by
+ * this SDK rather than relayed from the server.
+ */
 type SdkErrorCode = (typeof SDK_ERROR_CODES)[number];
 /**
  * A stable code a caller can branch on: a server-defined code (open-ended —
- * see `ErrorCode`'s own doc comment), one of the SDK's own client-side
- * codes above, or, since neither list is exhaustive, any other string.
+ * see `ErrorCode`'s own doc comment), one of `SdkErrorCode`'s client-side
+ * codes, or, since neither list is exhaustive, any other string.
  * `(string & {})` is the standard trick to keep autocomplete on the known
  * values while still accepting an arbitrary one.
  */
 type FleetlessErrorCode = ErrorCode | SdkErrorCode | (string & {});
 /**
- * The one error type the SDK throws for a refused API call (spec §11.5): a
- * stable machine-readable `code` a caller can branch on (`forbidden` vs
- * `token_expired`) plus a human `message` for logs and debugging. Never
- * parse `message` — it is not part of the contract, only `code` is.
+ * The third argument of `FleetlessError`'s constructor: what a thrower can
+ * attach beyond the code and the message. Both fields are optional, and
+ * both are absent on the codes the SDK raises before any request is sent.
  */
 interface FleetlessErrorOptions {
     /** Field-level detail for validation errors, passed through verbatim. */
@@ -731,79 +735,126 @@ interface FleetlessErrorOptions {
     /** The HTTP status of the response that produced this error, if any. */
     status?: number;
 }
+/**
+ * The one error type the SDK throws for a refused API call: a stable
+ * machine-readable `code` a caller can branch on (`forbidden` versus
+ * `token_expired`) plus a human `message` for logs and debugging. Never
+ * parse `message` — it is not part of the contract, only `code` is.
+ *
+ * Catch it by shape rather than by class where you can (`err.code`), since
+ * a bundler that ends up with two copies of the SDK also ends up with two
+ * classes and `instanceof` then answers `false` for a genuine one.
+ */
 declare class FleetlessError extends Error {
+    /** What went wrong, as a stable string — the field to branch on. */
     readonly code: FleetlessErrorCode;
+    /**
+     * 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.
+     */
     readonly details?: unknown;
+    /** The HTTP status of the response that produced this error, if it came from one. */
     readonly status?: number;
+    /**
+     * 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: FleetlessErrorCode, message: string, options?: FleetlessErrorOptions);
 }
 
+/**
+ * The options every realtime command accepts — `actions.cancel` and
+ * `publishers.publish` take exactly these; `InvokeOptions` extends them for
+ * `actions.invoke` and `services.call`.
+ */
 interface SendCommandOptions {
     /** How long to wait for a `command_result` before rejecting `command_timeout`. Default 10s. */
     timeoutMs?: number;
 }
 /**
- * `invoke`-only: how long **the platform itself** should wait for this one
- * call before giving up on the robot (W6b) — the whole wait for a service
- * call, goal *acceptance* only for an action (once accepted, a job runs as
- * long as it runs and is observed, not awaited).
- *
- * Optional; absent means the platform's own default (`DEFAULT_PATIENCE_MS`,
- * 15s) — exactly today's behaviour for a caller who names no preference.
- * Outside `[MIN_PATIENCE_MS, MAX_PATIENCE_MS]` the platform refuses with
- * `validation_error` rather than clamping, and this SDK does not clamp
- * locally or retry — surfacing the refusal is the whole of what it does
- * with this field. The floor exists because impatience reaches the robot,
- * not just the platform: a patience too short to survive a goal-acceptance
- * round trip made the bridge report `goal_timeout` and then issue a
- * *corrective cancel* against a goal an action server accepted a moment
- * later — a caller who names an unreachable deadline was causing a real
- * cancellation on the machine, repeatably, not just receiving an error.
- *
- * `timeoutMs` bounds how long *this SDK* waits locally for a reply on the
- * wire it already sent on; `patienceMs` travels to the platform and bounds
- * what *it* is willing to wait for from the robot. **They are not set
- * independently of each other, and D3a exists because the first version of
- * this doc comment said they were.** `timeoutMs` left unset is *derived*
- * from `patienceMs` (see `resolveLocalWaitMs`), not defaulted to a fixed
- * number that might be shorter — the SDK giving up locally before the
- * platform's own deadline would report `command_timeout` for a call the
- * platform never actually refused, which is exactly the two-clocks defect
- * this wave exists to remove, just relocated into this SDK instead of
- * between the cloud and the bridge. Setting both explicitly with
- * `timeoutMs < patienceMs` is refused with `invalid_option` before any
- * request is sent, for the same reason.
+ * What `actions.invoke` and `services.call` accept on top of
+ * `SendCommandOptions`: the two clocks a command runs under, one local to
+ * this SDK and one on the platform.
  */
 interface InvokeOptions extends SendCommandOptions {
+    /**
+     * How long **the platform itself** should wait for this one call before
+     * giving up on the robot — the whole wait for a service call, goal
+     * *acceptance* only for an action (once accepted, a job runs as long as it
+     * runs and is observed, not awaited).
+     *
+     * Optional; absent means the platform's own `DEFAULT_PATIENCE_MS`, 15s —
+     * exactly the behaviour of a caller who names no preference. Outside
+     * `MIN_PATIENCE_MS` to `MAX_PATIENCE_MS` (1s to 120s, both exported by
+     * `@fleetless/contracts`) the platform refuses with `validation_error`
+     * rather than clamping, and this SDK does not clamp locally or retry:
+     * surfacing the refusal is the whole of what it does with this field.
+     * The floor exists because
+     * impatience reaches the robot, not just the platform — a patience too
+     * short to survive a goal-acceptance round trip made the bridge report
+     * `goal_timeout` and then issue a *corrective cancel* against a goal an
+     * action server accepted a moment later, so a caller who names an
+     * unreachable deadline was causing a real cancellation on the machine,
+     * repeatably, not just receiving an error.
+     *
+     * `timeoutMs` bounds how long *this SDK* waits locally for a reply on the
+     * wire it already sent on; `patienceMs` travels to the platform and bounds
+     * what *it* is willing to wait for from the robot. **They are not set
+     * independently of each other.** `timeoutMs` left unset is *derived* from
+     * `patienceMs`, not defaulted to a fixed number that might be shorter —
+     * the SDK giving up locally before the platform's own deadline would
+     * report `command_timeout` for a call the platform never actually refused.
+     * Setting both explicitly with `timeoutMs < patienceMs` is refused with
+     * `invalid_option` before any request is sent, for the same reason.
+     */
     patienceMs?: number;
 }
 
+/**
+ * The callbacks `actions.subscribe` reports through: one for every job
+ * update on the slug, one for a refusal of the subscription itself.
+ */
 interface JobSubscriptionHandlers {
     /** Called on every update pushed for the slug's current job — state, feedback, progress and result. */
     onJob(event: JobEvent): void;
-    /** Called once if the subscription is refused (§11.5: e.g. `forbidden`, an unknown slug). */
+    /** Called once if the subscription is refused, e.g. `forbidden` or an unknown slug. */
     onError?(error: FleetlessError): void;
 }
+/** A live job subscription, returned by `actions.subscribe`. */
 interface JobSubscription {
-    /** Stops the subscription and, if the channel is currently connected, tells the server. */
+    /**
+     * Stops this subscription. The `unsubscribe` frame reaches the server only
+     * when this was the **last** holder of the robot and slug pair, and only if
+     * the channel is connected — subscriptions are reference-counted across
+     * kinds, so releasing this one while a second `actions.subscribe`, a
+     * `datapoints.subscribe` or an in-flight `services.call` still holds the
+     * same pair leaves that one's stream running untouched. Safe to call more
+     * than once.
+     */
     unsubscribe(): void;
 }
 
+/**
+ * Long-running work on a robot, reachable as `client.actions`. An action is
+ * a ROS action the developer exposed under a slug: it is invoked, it runs
+ * for as long as it runs, and it reports back while it does.
+ */
 interface ActionsApi {
     /**
-     * Invokes an action (spec §11.3). Resolves as soon as the job is created
+     * Invokes an action. Resolves as soon as the job is created
      * — the job id is informative, not the result. Feedback, progress and the
      * eventual result arrive separately over `subscribe`. A second invoke of
      * the same slug while one is already running is refused `busy`, with
      * `error.details.running` naming the job that is running.
      *
-     * `options.patienceMs` bounds goal *acceptance* only (W6b) — once a goal
+     * `options.patienceMs` bounds goal *acceptance* only — once a goal
      * is accepted this call has already resolved; the job then runs as long
      * as it runs, observed via `subscribe`, never awaited. `options.timeoutMs`
      * (this SDK's own local wait for the acceptance reply) is derived from
      * `patienceMs` when left unset, and the combination `timeoutMs <
-     * patienceMs` is refused with `invalid_option` rather than raced — see
-     * `resolveLocalWaitMs` in `commands.ts`, D3a.
+     * patienceMs` is refused with `invalid_option` rather than raced.
      */
     invoke(robotId: string, slug: string, params: Record<string, unknown>, options?: InvokeOptions): Promise<Job>;
     /**
@@ -811,10 +862,9 @@ interface ActionsApi {
      * Resolves with the `Job` the cancel was actually sent to, or `null` if
      * nothing matched.
      *
-     * **Two different requests, both legitimate (W6b):**
+     * **Two different requests, both legitimate:**
      * - `cancel(robotId, slug)` — no `jobId` — is the operator's stop button:
-     *   whatever is running on this slug, stop it. This is unchanged from
-     *   before W6b.
+     *   whatever is running on this slug, stop it.
      * - `cancel(robotId, slug, jobId)` cancels **that** job specifically. If
      *   it is not the one running, the platform answers `not_found` — this
      *   never silently falls back to stopping whatever *is* running, because
@@ -830,7 +880,7 @@ interface ActionsApi {
     cancel(robotId: string, slug: string, jobId?: string | null, options?: SendCommandOptions): Promise<Job | null>;
     /**
      * Subscribes to the slug's job: state, feedback, progress and result, as
-     * they happen. State is observed **by slug**, not by job id (§11.3) — this
+     * they happen. State is observed **by slug**, not by job id — this
      * is what makes late delivery after a reconnect and a second observer
      * watching the same job both work without special-casing either. Naming a
      * job to `cancel` does not change this: a slug is still a *place a job may
@@ -841,7 +891,9 @@ interface ActionsApi {
 
 /** An asset's bytes plus its declared media type — the shape `assets.get` answers with. */
 interface AssetBytes {
+    /** The asset's raw bytes, exactly as stored. */
     body: Uint8Array;
+    /** The declared media type, or `null` if the store did not record one. */
     mime: string | null;
 }
 /**
@@ -856,6 +908,7 @@ interface AssetBytes {
  * not only that one library.
  */
 type MeshLoaderDelegate = (path: string, manager: unknown, material: unknown, onComplete: (obj: unknown | null, err?: Error) => void) => void;
+/** What `assets.createMeshLoader` accepts beyond the robot and the delegate. */
 interface CreateMeshLoaderOptions {
     /**
      * How long to wait for `delegate`'s `onComplete` before giving up.
@@ -867,12 +920,14 @@ interface CreateMeshLoaderOptions {
     timeoutMs?: number;
 }
 /**
- * three.js's own `LoadingManager.setURLModifier(callback)` shape (W7a, D2).
+ * three.js's own `LoadingManager.setURLModifier(callback)` shape — the
+ * only thing `assets.prepareUrdfScene` needs from a three.js
+ * `LoadingManager`, so a caller passes theirs straight in.
  * Every load the manager oversees is routed through `callback` first — not
  * only the loader you handed the manager to, but every loader it constructs
  * internally on the same manager (`ColladaLoader`'s own `TextureLoader` for
  * a `.dae`'s `<init_from>` images, in particular). That is the one hook
- * that exists "one level up, for everything" (D2) where `createMeshLoader`'s
+ * that exists one level up, for everything, where `createMeshLoader`'s
  * per-loader `loadMeshCb` override does not reach: `TextureLoader` has no
  * override hook of its own.
  *
@@ -880,8 +935,10 @@ interface CreateMeshLoaderOptions {
  * or `urdf-loader`, same discipline as `MeshLoaderDelegate` above.
  */
 interface UrdfSceneManager {
+    /** Installs a callback every load through this manager is routed through first. */
     setURLModifier(callback: (url: string) => string): unknown;
 }
+/** What `assets.prepareUrdfScene` accepts beyond the robot and the manager. */
 interface PrepareUrdfSceneOptions {
     /**
      * How many assets to fetch in parallel. Default 6 — a default that keeps
@@ -889,24 +946,23 @@ interface PrepareUrdfSceneOptions {
      * meshes), not a number with a sweep behind it. Pass your own if you have
      * a reason to.
      *
-     * Must be a positive integer — `0` or negative throws `invalid_option`
-     * rather than silently fetching nothing and returning a scene that
-     * renders completely blank with no error to explain why.
+     * Must be a positive integer — `0` or negative rejects with
+     * `invalid_option` rather than silently fetching nothing and returning a
+     * scene that renders completely blank with no error to explain why.
      */
     concurrency?: number;
     /**
-     * Cancels this call (register row 244, W7c) — a caller who navigates away
+     * Cancels this call — a caller who navigates away
      * or switches to a different robot mid-load can abort every in-flight
      * fetch this method has started, not merely stop it from starting new
      * ones. Checked before the first request; if it fires while a request is
-     * already in progress, `HttpClient` forwards it straight to `fetch()`
-     * (`http.ts`'s own `RequestOptions.signal`), so the connection itself is
-     * torn down, not just abandoned by this SDK while it keeps running in the
-     * background.
+     * already in progress, the SDK forwards it straight to `fetch()`, so the
+     * connection itself is torn down, not just abandoned by this SDK while it
+     * keeps running in the background.
      *
      * Every `blob:` URL already created before the abort is revoked before
      * this call rejects with `FleetlessError('aborted', ...)` — the same
-     * guarantee a load that fails outright already had (D6): an aborted load
+     * guarantee a load that fails outright already had: an aborted load
      * must not leak what it had already fetched.
      *
      * `manager`'s URL modifier is only ever installed once every asset has
@@ -916,6 +972,10 @@ interface PrepareUrdfSceneOptions {
      */
     signal?: AbortSignal;
 }
+/**
+ * What `assets.prepareUrdfScene` resolves with: the URDF text to parse, what
+ * the sync could not resolve, and the cleanup for everything it fetched.
+ */
 interface UrdfSceneResources {
     /**
      * The robot's URDF as raw text — `package://` URIs intact, not rewritten
@@ -926,24 +986,21 @@ interface UrdfSceneResources {
     urdfText: string;
     /**
      * The same entries `assets.list()`'s `urdf.missing` reports — verbatim,
-     * not reduced to bare strings (W9b, DEF-081). Each carries `element`
+     * not reduced to bare strings. Each carries `element`
      * (`'mesh' | 'texture'`) alongside `uri`: before this, both kinds arrived
      * as an undifferentiated `string[]` and a caller could only ever say "N
-     * meshes missing", wrongly, for a URDF whose gap was actually a texture —
-     * the same defect W9b fixed one layer up, in the console. Reducing this
-     * field back to `string[]` here would throw the distinction away again at
+     * meshes missing", wrongly, for a URDF whose gap was actually a texture.
+     * Reducing this field back to `string[]` here would throw the distinction
+     * away again at
      * exactly the point a caller would render it. If you only need the URIs,
      * `missing.map(m => m.uri)`.
      *
-     * **Top-level only — not a `.dae`'s internal references (Kassandra-W7a
-     * review correction).** The cloud builds this list from the URDF text
+     * **Top-level only — not a `.dae`'s internal references.** The cloud
+     * builds this list from the URDF text
      * alone (`<mesh>`/`<texture>` `filename` attributes), which is the only
      * place it can see without parsing every `.dae` a sync touches; it never
-     * has and never can include an internal `<init_from>` reference. An
-     * earlier version of this comment claimed both — wrong, and worth naming
-     * as a correction rather than silently widening the sentence, since a
-     * caller who trusted "both" to mean both would build a completeness check
-     * against a list that structurally cannot report the second half. A
+     * has and never can include an internal `<init_from>` reference. Do not
+     * build a completeness check on it as though it covered both: a
      * `.dae`-internal reference the sync could not resolve surfaces through
      * the sync's own failure reporting instead, not here.
      *
@@ -955,44 +1012,53 @@ interface UrdfSceneResources {
      */
     missing: UrdfCompleteness['missing'];
     /**
-     * Revokes every `blob:` URL this call created. Call once the scene has
-     * finished loading (success or failure) or on unmount — safe to call more
-     * than once.
+     * Revokes every object URL this call created that carries bytes. Call
+     * once the scene has finished loading (success or failure) or on unmount
+     * — safe to call more than once.
+     *
+     * One object URL is deliberately kept: the shared zero-byte placeholder
+     * every refused reference resolves to. It costs nothing to leave alive,
+     * and leaving it is what lets this method stay simple — the installed URL
+     * modifier goes on refusing an owned-but-gone reference correctly, rather
+     * than falling back to the original string once the map is empty.
      *
-     * **Does not touch `manager`'s URL modifier (D7, Kassandra-W7a review).**
-     * An earlier version reset it to the identity function here, which
-     * silently reopened D4 the moment the same manager was used again — for a
-     * second robot, or for anything else — before a later `prepareUrdfScene`
-     * call happened to overwrite it. The installed modifier is left running,
+     * **Does not touch `manager`'s URL modifier.** Resetting it to the
+     * identity function here would reopen the very hole the modifier exists to
+     * close, the moment the same manager was used again — for a second robot,
+     * or for anything else — until a later `prepareUrdfScene` call happened to
+     * overwrite it. The installed modifier is left running,
      * and with this call's map now empty it already refuses anything it would
      * have owned and passes through anything it would not have, correctly,
      * on its own.
      */
     dispose(): void;
 }
+/**
+ * A robot's synced files, reachable as `client.assets`: its URDF, the meshes
+ * and textures that URDF references, and the glue a three.js renderer needs
+ * to fetch them with this client's credentials.
+ */
 interface AssetsApi {
     /**
-     * Every asset a robot has, plus whether its URDF is complete (spec §4.6).
+     * Every asset a robot has, plus whether its URDF is complete.
      * `urdf.missing` names the `package://` URIs the sync could not resolve —
-     * the number alone ("2 Meshes fehlen") sends a developer looking through a
+     * a count alone ("2 meshes missing") sends a developer looking through a
      * workspace by hand, the URIs are what they can act on.
      */
     list(robotId: string): Promise<AssetListResponse>;
     /**
      * The status of one sync by id — for **reconnecting** to a sync already in
-     * flight, not for starting one (W9b, DEF-147).
+     * flight, not for starting one.
      *
-     * **Starting a sync stays out of this SDK, on purpose (spec §4.6):**
-     * "übertragen wird ausschließlich auf explizite Anforderung des
-     * Entwicklers über die Console" — a developer action, Owner-tier, done
-     * once, from the console. This method is a different thing: `list()`'s
+     * **Starting a sync stays out of this SDK, on purpose.** Assets are
+     * transferred only on a developer's explicit request from the console —
+     * an Owner-tier action, done once. This method is a different thing:
+     * `list()`'s
      * `active_sync` (or a `busy` refusal's `assetSyncBusyDetails`) hands a
      * caller a `sync_id` for a sync that is **already running**, and before
      * this method existed there was no way for anything built on this SDK to
-     * do anything with that id except throw it away. That was the actual
-     * shape of DEF-147: the id was recoverable server-side the whole time
-     * (`GET .../assets/sync/{id}` has existed since W7) — nothing reachable
-     * from this SDK ever called it.
+     * do anything with that id except throw it away, even though the sync was
+     * readable server-side the whole time.
      *
      * A page reload is the case this exists for: whatever held the `sync_id`
      * in memory is gone, `list()` (or a fresh `busy` refusal) hands it back,
@@ -1010,11 +1076,11 @@ interface AssetsApi {
      */
     urdf(robotId: string): Promise<string>;
     /**
-     * The mesh callback for `urdf-loader` (spec §4.6): an `<img>` tag and the
-     * default three.js loaders cannot set an `Authorization` header, and the
-     * platform deliberately has no signed URLs and no token in the query
-     * string (see `@fleetless/contracts` `assets.ts`), so every app would
-     * otherwise write this glue itself, and each one differently.
+     * The mesh callback for `urdf-loader`: an `<img>` tag and the default
+     * three.js loaders cannot set an `Authorization` header, and the platform
+     * deliberately has no signed URLs and no token in the query string, so
+     * every app would otherwise write this glue itself, and each one
+     * differently.
      *
      * Returns a function with `loadMeshCb`'s own signature — assign it
      * directly:
@@ -1043,7 +1109,7 @@ interface AssetsApi {
     createMeshLoader(robotId: string, delegate: MeshLoaderDelegate, options?: CreateMeshLoaderOptions): MeshLoaderDelegate;
     /**
      * Authenticated loading for everything three.js fetches to render a
-     * textured robot — not only meshes (spec §4.6, W7a, D2). Installs
+     * textured robot — not only meshes. Installs
      * `manager.setURLModifier` so **every** load `manager` oversees resolves
      * to a pre-fetched `blob:` URL: a top-level `<mesh>`, a `<material>`'s
      * `<texture>`, and an image a `.dae` references internally via
@@ -1065,9 +1131,8 @@ interface AssetsApi {
      * **Do not also install `createMeshLoader` on the same manager.** The two
      * consume different URDF sources — this method fetches the URDF's *raw*
      * bytes, `createMeshLoader` is meant to pair with `urdf()`'s
-     * cloud-rewritten text. **Not "double-fetches every mesh" — a first
-     * version of this comment said that, and Momus-W7a's review traced it
-     * and found it wrong.** What actually happens is asymmetric breakage,
+     * cloud-rewritten text. **It is not that every mesh gets fetched twice.**
+     * What actually happens is asymmetric breakage,
      * whichever URDF text the combination ends up parsing: paired with
      * *this* method's raw text, `createMeshLoader` receives urdf-loader's
      * `resolvePath()` output (`/pkg/rel`) rather than an absolute Fleetless
@@ -1079,12 +1144,11 @@ interface AssetsApi {
      * debug the wrong symptom, which is worse than the original (already
      * wrong) warning being merely unhelpful.
      *
-     * **Enforced, not only documented (Momus-W7a review, via the team
-     * lead).** `createMeshLoader`'s returned callback checks whether the
-     * `manager` it is handed already has this method's URL modifier
-     * installed and fails loudly via `onComplete(null, err)` before ever
-     * touching the network, rather than relying on a developer having read
-     * this paragraph. See `managersWithPreparedUrdfScene`.
+     * **Enforced, not only documented.** `createMeshLoader`'s returned
+     * callback checks whether the `manager` it is handed already has this
+     * method's URL modifier installed and fails loudly via
+     * `onComplete(null, err)` before ever touching the network, rather than
+     * relying on a developer having read this paragraph.
      *
      * **Why raw bytes, not `urdf()`'s rewritten text.** Both `urdf-loader`'s
      * default mesh loading and `ColladaLoader` compute the base path they use
@@ -1099,9 +1163,8 @@ interface AssetsApi {
      * in sync.
      *
      * **`urdf-loader` resolves `package://` itself, before any of this runs —
-     * a second resolution stage this method has to account for, found by
-     * Threepio-W7a running the recipe demo in a real browser rather than
-     * reading the source.** `URDFLoader.parse()`'s own `resolvePath()`
+     * a second resolution stage this method has to account for, measured in a
+     * real browser rather than read off the source.** `URDFLoader.parse()`'s own `resolvePath()`
      * rewrites `package://pkg/rel` using `this.packages` (default `''`) to
      * `/pkg/rel` — a root-relative URL — and *that* is what reaches
      * `loadMeshCb`/`ColladaLoader`/`manager.resolveURL()`, not the original
@@ -1121,29 +1184,29 @@ interface AssetsApi {
      * outside what this method can predict — see the ownership rule below
      * for what happens to that reference.
      *
-     * **This method only claims what it owns (D4, revised after Argus-W7a's
-     * review) — not every unmapped reference.** `manager` is frequently the
+     * **This method only claims what it owns — not every unmapped
+     * reference.** `manager` is frequently the
      * caller's own scene-wide `LoadingManager`, shared for an HDRI, an
      * environment map, a font atlas, a ground texture — none of which have
-     * anything to do with this robot. A first version refused everything
-     * unmapped, which silently emptied every one of those the moment a
-     * caller shared their manager. So the rule is narrower: a `package://`
+     * anything to do with this robot. Refusing everything unmapped would
+     * silently empty every one of those the moment a caller shares their
+     * manager. So the rule is narrower: a `package://`
      * reference, or a root-relative path whose leading segment names a ROS
      * package this robot's assets (or `missing`) actually mention, is this
      * method's to resolve or refuse; an unmapped one falls back to the
-     * normalized form (D5, below) and then to a shared, inert, page-local
+     * normalized form (below) and then to a shared, inert, page-local
      * `blob:` URL — never the original string, so a hostile URDF naming an
      * unsynced or off-namespace reference still cannot make three.js touch
      * the network for it. Anything else — not in that namespace — is left
      * completely alone, **except** an absolute `http(s)` URL, which is
      * refused regardless of namespace: the one case this method cannot leave
      * ambiguous, because a hostile URDF naming an attacker's host directly
-     * (bypassing `package://` entirely) is exactly what D4 exists to close,
-     * and three.js would otherwise fetch it for real, off-origin, the moment
+     * (bypassing `package://` entirely) is exactly what this rule exists to
+     * close, and three.js would otherwise fetch it for real, off-origin, the moment
      * the direct and namespace checks both miss.
      *
      * **A `.dae`'s own internal reference gets a second-chance, normalized
-     * lookup (D5, Momus-W7a review, reproduced in a real browser).** three.js
+     * lookup, reproduced in a real browser.** three.js
      * builds the request for one by plain string concatenation — no `..`/`.`
      * collapsing — while `asset.name` carries the *normalized* tail
      * (`@fleetless/contracts`' naming rule). So `../textures/skin.png` or
@@ -1154,17 +1217,17 @@ interface AssetsApi {
      * verbatim and `resolvePath()` rewrites it by the same unnormalized
      * concatenation on both sides, so the direct key already matches.
      *
-     * **`dispose()` does not undo any of this (D7, Kassandra-W7a review).**
-     * See its own doc comment on `UrdfSceneResources`.
+     * **`dispose()` does not undo any of this.** See its own doc comment on
+     * `UrdfSceneResources`.
      *
      * **Pre-fetch is unavoidable**, not merely a choice: a URL modifier
      * cannot be asynchronous, so every asset it might be asked for has to
      * already be a `blob:` URL before `URDFLoader.parse` runs. Bounded by
      * `options.concurrency` (default 6) and scoped to only `kind: 'mesh'` and
-     * `kind: 'texture'` assets — which is already "what the URDF references"
-     * (`@fleetless/contracts`' `rest.ts`: a re-sync reconciles, so assets the
-     * current URDF no longer references stop belonging to the robot), not an
-     * unbounded fetch of everything the robot has ever had.
+     * `kind: 'texture'` assets — which is already "what the URDF references",
+     * since a re-sync reconciles and assets the current URDF no longer
+     * references stop belonging to the robot. Not an unbounded fetch of
+     * everything the robot has ever had.
      */
     prepareUrdfScene(robotId: string, manager: UrdfSceneManager, options?: PrepareUrdfSceneOptions): Promise<UrdfSceneResources>;
 }
@@ -1182,35 +1245,56 @@ type StoredSession = SessionTokens;
  * assumes a browser, or any storage, exists.
  */
 interface TokenStore {
+    /**
+     * Returns the stored session, or `null` when nobody is logged in. May be
+     * async, so a store backed by a native keystore or an IndexedDB read
+     * works without a synchronous cache in front of it.
+     */
     load(): StoredSession | null | Promise<StoredSession | null>;
+    /**
+     * Writes the session, or clears it when passed `null`. Called after a
+     * login, after every silent refresh, and on logout — so an implementation
+     * that persists must expect to be called often, not once.
+     */
     save(session: StoredSession | null): void | Promise<void>;
 }
 /** The default store: works out of the box, forgets the session on reload. */
 declare class InMemoryTokenStore implements TokenStore {
     #private;
+    /** 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(): StoredSession | null;
+    /** Replaces the session held in memory; `null` clears it. */
     save(session: StoredSession | null): void;
 }
 
-/** `beginHostedLogin()`'s input (spec §3.4, §17, W7b). */
+/**
+ * `beginHostedLogin()`'s input: the OAuth client the developer registered
+ * for this app, where the browser should come back to, and optionally what
+ * the resulting token should be usable against.
+ */
 interface BeginHostedLoginOptions {
     /**
      * The opaque `client_id` issued when the developer registered this app's
      * OAuth client (console, App Settings). **Never `appIdentifier`** — they
-     * are deliberately different identifiers (`contracts/src/oauth.ts`,
-     * `oauthClient`'s doc comment: "the `client_id` on the wire — opaque, and
-     * not the app identifier").
+     * are deliberately different identifiers — the contracts call this "the
+     * `client_id` on the wire: opaque, and not the app identifier".
      */
     clientId: string;
     /**
      * Must be registered, byte-for-byte, as one of that client's
      * `redirect_uris` — matching at the server is exact-string, never a
-     * prefix (`contracts/src/oauth.ts`, `redirectUri`'s doc comment).
+     * prefix (the contracts' `redirectUri` doc comment says why).
      */
     redirectUri: string;
+    /**
+     * The OAuth scopes to request, space-separated. Omit it to get the
+     * client's registered default, which is what an ordinary app login wants.
+     */
     scope?: string;
     /**
-     * RFC 8707 audience binding (register row, W7b): the resource this
+     * RFC 8707 audience binding: the resource this
      * session's token should be usable against. **Omit it for an ordinary app
      * login.** A token with no `resource` carries no `aud` and works
      * unrestricted against this app's own REST surface exactly as it always
@@ -1220,7 +1304,7 @@ interface BeginHostedLoginOptions {
      *
      * **`/oauth/authorize` accepts exactly two shapes** — anything else is
      * refused with `invalid_target` on the redirect back, before a code is
-     * ever issued (`cloud/src/routes/oauth.ts`, `isKnownResource`):
+     * ever issued (the cloud's own known-resource check):
      *
      * - `<base>/mcp-stub/resource` — the global OAuth resource stub, matched
      *   byte-for-byte.
@@ -1230,21 +1314,21 @@ interface BeginHostedLoginOptions {
      *   be the one this `clientId` is registered to, so a client on app A can
      *   never be minted a token whose `aud` names app B.
      *
-     * Both are served and validated by
-     * `cloud/src/routes/oauth-resource-stub.ts`, whose validator refuses a
-     * token with **no** `aud` exactly as hard as one with the wrong `aud` —
+     * Both are served and validated by the platform's resource stub, whose
+     * validator refuses a token with **no** `aud` exactly as hard as one with
+     * the wrong `aud` —
      * "unscoped" must never read as "for me" — comparing by equality, never
      * by prefix.
      *
      * **`<base>/mcp/<app_identifier>` is not a resource any more.** There is
      * no per-app MCP endpoint: the cloud registers one central, non-parametric
-     * `POST /mcp` (`cloud/src/routes/mcp.ts`, contracts'
-     * `MCP_ENDPOINT_PATH`), and the `/oauth/authorize` branch that used to
+     * `POST /mcp` (the contracts' `MCP_ENDPOINT_PATH`), and the
+     * `/oauth/authorize` branch that used to
      * accept a `/mcp/<app>` resource was deleted along with the app-level
      * `mcp_enabled` flag. Asking for one now yields `invalid_target` for
      * every app, **including your own**. The central MCP endpoint has its own
-     * OAuth flow (`cloud/src/routes/mcp-oauth.ts`) which this SDK's hosted
-     * login does not drive — `beginHostedLogin` always targets
+     * OAuth flow, which this SDK's hosted login does not drive —
+     * `beginHostedLogin` always targets
      * `OAUTH_PATHS.authorize`.
      *
      * Whatever you name here is re-checked at the token exchange: it must
@@ -1262,8 +1346,8 @@ interface HostedLoginRequest {
      * both back into `completeHostedLogin`. **This SDK does not persist them
      * for you.** The redirect back to `redirectUri` is a fresh page load for a
      * browser app — nothing kept in this SDK's own memory survives it (the
-     * same reasoning `client.ts` states for `TokenStore`: "the SDK itself
-     * never assumes a browser, or any storage, exists"). An in-memory default
+     * same reasoning `TokenStore` states: the SDK itself never assumes a
+     * browser, or any storage, exists). An in-memory default
      * here would not be merely suboptimal, it would be broken for the primary
      * use case while looking like it worked for anything that never actually
      * navigates away. `sessionStorage`, a signed cookie, or a plain variable
@@ -1271,6 +1355,11 @@ interface HostedLoginRequest {
      * the caller's.
      */
     state: string;
+    /**
+     * The PKCE code verifier for this attempt. Persist it exactly as
+     * `state` above and pass it back to `completeHostedLogin` — it is what
+     * proves the code exchange comes from the client that started the flow.
+     */
     codeVerifier: string;
 }
 /** `completeHostedLogin()`'s input — the redirect back, plus what `beginHostedLogin` returned for this same attempt. */
@@ -1281,13 +1370,14 @@ interface CompleteHostedLoginOptions {
     state: string;
     /**
      * The `state` this attempt's `beginHostedLogin` returned. Checked against
-     * `state` above **before any network call** — RFC 6749 §10.12's whole
-     * point is that a caller must not complete an authorization response it
-     * did not itself request.
+     * `state` above **before any network call** — the whole point of RFC
+     * 6749 section 10.12 is that a caller must not complete an authorization
+     * response it did not itself request.
      */
     expectedState: string;
     /** The `codeVerifier` this attempt's `beginHostedLogin` returned. */
     codeVerifier: string;
+    /** Must be the exact same `client_id` passed to `beginHostedLogin`. */
     clientId: string;
     /** Must be the exact same string passed to `beginHostedLogin`. */
     redirectUri: string;
@@ -1296,22 +1386,31 @@ interface CompleteHostedLoginOptions {
      * Resending it here is not what binds the audience — the server already
      * bound `resource` to the authorization code at `/oauth/authorize` and
      * mints `aud` from that stored value regardless of what this call sends —
-     * but RFC 8707 §2 expects a client to name the resource at both steps,
+     * but RFC 8707 section 2 expects a client to name the resource at both steps,
      * and the cloud rejects a *mismatched* resend outright (`invalid_target`).
      * Omit it here exactly when it was omitted at `beginHostedLogin`.
      */
     resource?: string;
 }
 /**
- * What `logout()` resolves with (W9c, DEF-098) — five separable facts, not
- * one nullable URL, mirroring the wire's `clientLogoutResponse`.
+ * What `logout()` resolves with — five separable facts, not one nullable
+ * URL, mirroring the wire's `clientLogoutResponse`.
+ *
+ * **`idp_logout` is `null` whenever the server never answered**, which
+ * happens for two different reasons: there was no local session to ask
+ * about, or the request itself failed. Either way there is nothing to
+ * report — not even "not federated", because this client never learned that
+ * either.
  *
- * `idp_logout` is `null` exactly when `revoked` is `false`: the server call
- * that would have produced it never got a chance to answer (no local
- * session, or the request itself failed), so there is nothing to report —
- * not even "not federated", because this client never learned that either.
- * When `revoked` is `true` and a real response came back, `idp_logout` is
- * one of:
+ * `revoked` does not identify which of the two you got. It is `false` only
+ * for the failed request; **a logout with no local session at all resolves
+ * `{ revoked: true, idp_logout: null }`**, since nothing lingers
+ * server-side and that counts as revoked. So `revoked: false` does imply
+ * `idp_logout: null`, and the converse does not hold. Do not read the two
+ * fields as one bit.
+ *
+ * When a real response did come back, `revoked` is `true` and `idp_logout`
+ * is one of:
  *
  * - `{ status: 'redirect', url }` — send the browser here to end the
  *   session at the IdP too. Nothing else in this SDK does that navigation
@@ -1334,27 +1433,61 @@ interface CompleteHostedLoginOptions {
  * isn't.
  *
  * **`session_unknown` is a different kind of nothing, and the reason it
- * exists is a second logout** (W9 review). A double click, a repeated POST, an
+ * exists is a second logout.** A double click, a repeated POST, an
  * app that logs out on unmount *and* on a route change: the last call wins,
  * and before this outcome existed it answered `not_federated` — a positive
  * claim about an IdP the server had never looked up. An app that treats it as
  * *"fully logged out"* skips a redirect the **first** call may well have
  * returned, and the user stays signed in at the IdP after clicking log out.
  *
- * Note that `revoked` cannot help you here: it reports whether the HTTP call
- * succeeded, not whether a session was found — so this case arrives as
- * `{ revoked: true, idp_logout: { status: 'session_unknown' } }`, never as the
- * `null` below.
+ * Note that `revoked` cannot help you here either: it reports whether the
+ * HTTP call succeeded, not whether a session was found — so this case
+ * arrives as `{ revoked: true, idp_logout: { status: 'session_unknown' } }`,
+ * never as `null`.
  */
 interface LogoutResult {
+    /**
+     * Whether the server-side revoke actually happened. It reports the fate
+     * of the HTTP call, not whether a session was found — `false` means the
+     * refresh family may still be alive even though this client has
+     * forgotten it.
+     */
     revoked: boolean;
+    /**
+     * What the server could say about the identity provider behind this
+     * session, or `null` when there was no answer to report at all — either
+     * because there was no local session to ask about, or because the request
+     * failed. `null` is **not** the same as `not_federated`, which is a real
+     * finding about a real session.
+     *
+     * When it is not `null` it is one of five statuses: `redirect` (with a
+     * `url` to send the browser to, to end the session at the identity
+     * provider too), `not_federated` (this session never came from one),
+     * `unsupported_by_idp` (it did, and the provider offers no
+     * RP-initiated logout), `hint_unavailable` (it did, the provider can end
+     * the session, and Fleetless has nothing to ask it with), or
+     * `session_unknown` (the server did not find this session, so it can say
+     * nothing about a provider).
+     *
+     * **`unsupported_by_idp` and `hint_unavailable` both mean the identity
+     * provider's session survives and this platform cannot end it.** Render
+     * either one like `not_federated` and you report a session as fully ended
+     * when it is not.
+     */
     idp_logout: ClientLogoutResponse['idp_logout'] | null;
 }
+/**
+ * Who the caller is, reachable as `client.auth`. A client built with a
+ * `tokenStore` uses the full surface. One built with a `serverKey` already
+ * has an identity and no user session, so **`me()` is the only method it
+ * can call** — `login`, `beginHostedLogin`, `completeHostedLogin`,
+ * `logout`, `changePassword` and `passwordResetUrl` all throw on one.
+ */
 interface AuthApi {
     /** Exchanges email + password, and the client's configured app identifier, for a session. */
     login(email: string, password: string): Promise<void>;
     /**
-     * Starts the hosted login flow (spec §3.4, §17, W7b): a Fleetless-served
+     * Starts the hosted login flow: a Fleetless-served
      * login page an app's end user is redirected to, with optional
      * per-app IdP federation. Builds the `/oauth/authorize` URL (Authorization
      * Code + PKCE, S256 only — OAuth 2.1 removes `plain`) and generates the
@@ -1386,12 +1519,12 @@ interface AuthApi {
      *
      * Once past that check and the exchange completes, `me()`, `logout()`,
      * `changePassword()` and silent refresh all behave identically afterwards,
-     * regardless of which flow the session started from. That is the actual
-     * content of §3.4's *"Beide Wege enden im selben Fleetless-Token"*: not
-     * merely that the bytes match, but that every existing code path treats
-     * the result the same way.
+     * regardless of which flow the session started from. Both routes into a
+     * session end at the same Fleetless token: not merely that the bytes
+     * match, but that every existing code path treats the result the same
+     * way.
      *
-     * The wire response is RFC 6749 §5.1's envelope (`token_type`, optional
+     * The wire response is the envelope of RFC 6749 section 5.1 (`token_type`, optional
      * `scope`), not `sessionTokens` — this method normalizes one into the
      * other before storing. **Refresh needs no separate handling**: the cloud
      * mints these tokens through the same session mechanism `/api/client/login`
@@ -1403,7 +1536,7 @@ interface AuthApi {
      * Throws with the OAuth error code as `.code` (e.g. `invalid_grant` for an
      * expired or already-used `code`) if the exchange itself fails — a
      * different vocabulary from every other method on this interface, because
-     * `/oauth/token` answers in RFC 6749 §5.2's shape, not `apiError`.
+     * `/oauth/token` answers in the shape of RFC 6749 section 5.2, not `apiError`.
      *
      * **Makes exactly one request to `/oauth/token` — never retried, no
      * timeout-and-resend, no internal concurrency of its own.** Stated
@@ -1412,16 +1545,16 @@ interface AuthApi {
      * while a first call is still in flight** (a plain "the first attempt
      * looked like it timed out, so retry" is exactly the shape this warns
      * against — it is not a defect in this method, since this method itself
-     * has nothing that could ever cause that). André's decision, 2026-08-18:
-     * the platform treats a second presentation of an authorization code as
-     * theft and revokes the whole token family it belongs to, deliberately,
-     * even though a plain double-submission looks identical on the wire —
+     * has nothing that could ever cause that). The platform treats a second
+     * presentation of an authorization code as theft and revokes the whole
+     * token family it belongs to, deliberately, even though a plain
+     * double-submission looks identical on the wire —
      * because the blast radius is bounded (only a caller already holding the
      * correct `code_verifier` and `client_id` can trigger it, so a merely
      * *sniffed* code cannot lock anyone out) and the alternative is a
      * narrower defence against a real theft.
      *
-     * **What actually happens if two requests race (measured, Argus-W7c):**
+     * **What actually happens if two requests race, measured:**
      * one of the two receives `200` with a refresh token that the server has
      * already revoked. The access token in that same response keeps working
      * normally for the rest of its short TTL — nothing about the race is
@@ -1459,8 +1592,8 @@ interface AuthApi {
      * request without a fresh token), not a bug — but a kiosk or shared
      * workstation needs to know that number.
      *
-     * **Nor does it end a federated session at the identity provider (W9c,
-     * DEF-098).** Ending the Fleetless session and ending the IdP session are
+     * **Nor does it end a federated session at the identity provider.**
+     * Ending the Fleetless session and ending the IdP session are
      * two different things — see `LogoutResult.idp_logout`. This method does
      * not act on that information itself (no redirect, no fetch to the IdP);
      * it only reports what the server found, the same "this SDK stays thin"
@@ -1470,30 +1603,22 @@ interface AuthApi {
      * **`idp_logout` is `null` when there was no server answer to report** —
      * and that is *not* the same as `revoked === false`.
      *
-     * This block used to state the biconditional (*"`null` exactly when
-     * `revoked` is `false`"*), and **it is measurably wrong** (Argus-W9, W9
-     * review): calling `logout()` with **no local session** returns
-     * `{ revoked: true, idp_logout: null }`. The implementation says so six
-     * lines above itself — *"Nothing to revoke: no server-side session lingers,
-     * so this counts as revoked — but there is no IdP fact to report either"* —
-     * so the public docblock and the code contradicted each other in one file.
-     *
-     * That mattered more than a wrong sentence usually does, because **this is
-     * the rule the text tells a caller to branch on**. Someone who reads
-     * `revoked === true` and trusts the promise does not expect `null`.
-     * TypeScript catches it (the type is `| null`); a JavaScript caller does
-     * not.
+     * Calling `logout()` with **no local session** returns
+     * `{ revoked: true, idp_logout: null }`, so `null` is not the same as
+     * `revoked === false` and the two fields are not one bit. TypeScript
+     * catches a caller who forgets (the type is `| null`); a JavaScript caller
+     * does not.
      *
      * So: **`null` means this client had nothing to send or the request never
      * answered.** It is not `not_federated`, which is a real finding about a
      * real session — conflating the two is the ambiguity this shape exists to
-     * remove, and it is still the reason to read both fields rather than one.
+     * remove, and it is the reason to read both fields rather than one.
      */
     logout(): Promise<LogoutResult>;
     /** Who the caller turned out to be, without decoding a token client-side. */
     me(): Promise<ClientIdentity>;
     /**
-     * Changes the current end user's password (spec §3, W6c).
+     * Changes the current end user's password.
      *
      * `currentPassword` is required by the server even though the session
      * already proves identity — it is what stops a stolen *session* from
@@ -1531,7 +1656,7 @@ interface AuthApi {
 }
 
 /**
- * The snapshot's metadata alone, without the bytes (spec §10). All fields
+ * The snapshot's metadata alone, without the bytes. All fields
  * are `null` together when nothing has been captured yet for this camera —
  * a fresh configuration before the first `snapshot_interval_ms` elapses, say
  * — which is a state, not a failure: the wire answers it with
@@ -1546,36 +1671,49 @@ interface AuthApi {
  * `SNAPSHOT_HEADERS`'s doc comment in `@fleetless/contracts`).
  */
 interface CameraSnapshotMeta {
+    /** The image's media type, e.g. `image/jpeg`. */
     mime: string | null;
+    /** The image's width in pixels. */
     width: number | null;
+    /** The image's height in pixels. */
     height: number | null;
-    /** The bridge's capture time (§6.3). */
+    /** The bridge's capture time, in unix milliseconds — when the frame was taken, not when it was served. */
     timestamp_ms: number | null;
+    /** How long the cloud has held this frame, in milliseconds. The one figure to read for freshness. */
     age_ms: number | null;
 }
-/** One snapshot read: the image bytes plus everything needed to state how old they are (spec §10). */
+/** One snapshot read: the image bytes plus everything needed to state how old they are. */
 interface CameraSnapshot extends CameraSnapshotMeta {
+    /** The encoded image, or `null` when nothing has been captured yet. */
     image: Uint8Array | null;
 }
 /**
- * What a LiveKit client needs to join, plus the means to leave (spec §10,
- * §14.3: "Kamera (Snapshot-URL + LiveKit-Track-Handle)"). Hand `url`/`token`
- * straight to a LiveKit client SDK (e.g. `Room.connect(url, token)`) — this
- * SDK stops there on purpose: no video widget, no teleop-style helper
- * (§14.3 keeps it thin).
+ * What a LiveKit client needs to join, plus the means to leave. Returned by
+ * `cameras.live`. Hand `url` and `token` straight to a LiveKit client SDK
+ * (e.g. `Room.connect(url, token)`) — this SDK stops there on purpose: no
+ * video widget and no teleop-style helper, so that the app owns how the
+ * video is presented.
  */
 interface CameraLiveSession {
     /**
-     * This viewer's own hold (W6b) — what `release()` releases, and the only
+     * This viewer's own hold — what `release()` releases, and the only
      * thing distinguishing this session from every other tab of the same
-     * identity watching the same camera. Not previously addressable: a `DELETE`
-     * with no id released **all** of this identity's holds on the slug, so one
-     * tab closing stopped the robot for every other tab too. See `release()`'s
-     * doc comment for what changed and what did not.
+     * identity watching the same camera.
      */
     session_id: string;
+    /** The LiveKit server URL to connect to. */
     url: string;
+    /** The LiveKit room this session joins. */
     room: string;
+    /**
+     * The LiveKit access token for this session. It is checked when the
+     * participant connects and not again afterwards, so it bounds *joining*,
+     * not the session: a viewer who has already joined keeps receiving video
+     * past `expires_at`. What ends a joined session is `release()` together
+     * with disconnecting the room, the cloud reconciling the hold away
+     * against LiveKit's real participants, or a revocation — a membership,
+     * role or key change — kicking the participant out.
+     */
     token: string;
     /**
      * When this token can no longer be used to **join** — not when an
@@ -1594,14 +1732,10 @@ interface CameraLiveSession {
     expires_at: string;
     /**
      * Tells the cloud this viewer no longer wants to hold the camera live —
-     * **this** hold, addressed by `session_id` (W6b), and no other tab's.
-     *
-     * Before W6b, `DELETE` carried no id and released every hold this identity
-     * had on the slug — so one tab's `release()` (or its unmount cleanup)
-     * stopped the robot out from under every other tab of the same logged-in
-     * user, which kept rendering a frozen frame because a LiveKit token is
-     * checked at join and never again. Each `CameraLiveSession` now releases
-     * only the hold it itself took.
+     * **this** hold, addressed by `session_id`, and no other tab's. Each
+     * `CameraLiveSession` releases only the hold it itself took, so one tab's
+     * cleanup never stops the robot out from under another tab of the same
+     * logged-in user.
      *
      * **This alone does not stop the stream.** The cloud makes LiveKit room
      * participation the authoritative refcount, not this call — precisely
@@ -1622,7 +1756,7 @@ interface CameraLiveSession {
      *
      * **A failed DELETE here is not observable anywhere** — not as a
      * rejection, not as a realtime event, not as a field on this object. This
-     * is a deliberate decision, not an oversight (W6b review): the only
+     * is a deliberate decision, not an oversight: the only
      * consumer of that information would be code deciding whether to retry,
      * and the backstop this comment already describes — the cloud's own
      * LiveKit-participation reconciliation — makes a retry unnecessary for
@@ -1632,13 +1766,18 @@ interface CameraLiveSession {
      */
     release(): Promise<void>;
 }
+/**
+ * A robot's cameras, reachable as `client.cameras`: what exists, the latest
+ * still frame, and a live video session. All of it is REST — no realtime
+ * channel is involved.
+ */
 interface CamerasApi {
-    /** Every camera exposed on this robot (spec §11.2's per-robot descriptor list, extended to the camera kind). */
+    /** Every camera exposed on this robot, as descriptors — the same per-robot list the other kinds use. */
     list(robotId: string): Promise<CameraDescriptor[]>;
     /**
      * The current snapshot: image bytes plus its age. Independent of `live` —
      * a snapshot keeps updating on `snapshot_interval_ms` whether or not
-     * anyone is watching live (§10), and keeps being served, with a growing
+     * anyone is watching live, and keeps being served, with a growing
      * age, even while the bridge is offline.
      */
     snapshot(robotId: string, slug: string): Promise<CameraSnapshot>;
@@ -1650,30 +1789,44 @@ interface CamerasApi {
      */
     snapshotMeta(robotId: string, slug: string): Promise<CameraSnapshotMeta>;
     /**
-     * Takes a refcounted hold on this camera's live stream (spec §10): the
+     * Takes a refcounted hold on this camera's live stream: the
      * first `live()` on a slug starts the robot publishing, the last viewer
      * leaving stops it. Deliberately not deduplicated locally across multiple
      * `live()` calls for the same `(robotId, slug)` — unlike a datapoint
      * subscription, each call needs its own distinct LiveKit participant, so
-     * a local counter here would just be the same shared-count bug
-     * `slug-subscriptions.ts` fixed, self-inflicted on a resource the cloud
-     * already counts correctly.
+     * a local counter here would just be the same shared-count bug the
+     * subscription layer already fixed, self-inflicted on a resource the
+     * cloud counts correctly on its own.
      */
     live(robotId: string, slug: string): Promise<CameraLiveSession>;
 }
 
+/**
+ * The callbacks `datapoints.subscribe` reports through: one for values, one
+ * for a refusal. `onEvent` fires immediately with the current value and
+ * again on every change.
+ */
 interface DatapointSubscriptionHandlers {
     /** Called with the current value on subscribe, then again on every change. */
     onEvent(event: DatapointEvent): void;
-    /** Called once if the subscription is refused (§11.5: e.g. `forbidden`, `unknown_datapoint`). */
+    /** Called once if the subscription is refused, e.g. `forbidden` or `unknown_datapoint`. */
     onError?(error: FleetlessError): void;
 }
+/** A live datapoint subscription, returned by `datapoints.subscribe`. */
 interface DatapointSubscription {
-    /** Stops the subscription and, if the channel is currently connected, tells the server. */
+    /**
+     * Stops this subscription. The `unsubscribe` frame reaches the server only
+     * when this was the **last** holder of the robot and slug pair, and only if
+     * the channel is connected — subscriptions are reference-counted across
+     * kinds, so releasing this one while a second `datapoints.subscribe`, an
+     * `actions.subscribe` or an in-flight `services.call` still holds the same
+     * pair leaves that one's stream running untouched. Safe to call more than
+     * once.
+     */
     unsubscribe(): void;
 }
 /**
- * Window aggregation for `history` (spec §8). `window` and `agg` always
+ * Window aggregation for `datapoints.history`. `window` and `agg` always
  * travel together on the wire — the cloud refuses one without the other
  * rather than defaulting either, since a silently chosen aggregation is a
  * chart that lies quietly — so they live in one object here instead of two
@@ -1685,10 +1838,16 @@ interface DatapointSubscription {
 interface HistoryAggregation {
     /** Bucket width, e.g. `10s`, `1m`. */
     window: string;
+    /** How to reduce each bucket's samples to one number. */
     agg: 'min' | 'max' | 'avg';
-    /** A numeric field inside an object value, e.g. `pose.x` (§4.4 paths). Only meaningful when the datapoint's own value is not itself a number. */
+    /** A numeric field inside an object value, e.g. `pose.x`. Only meaningful when the datapoint's own value is not itself a number. */
     field?: string;
 }
+/**
+ * The window `datapoints.history` reads, and whether it comes back as raw
+ * samples or as aggregated buckets. `aggregate` is what decides which of
+ * the two responses you get.
+ */
 interface HistoryOptions {
     /**
      * `now-30s` / `now-5m` / `now-1h`, or absolute unix milliseconds — as a
@@ -1701,11 +1860,22 @@ interface HistoryOptions {
     from: string;
     /** Same two forms as `from`. Defaults to now. */
     to?: string;
+    /** The most rows to return. The platform applies its own ceiling regardless. */
     limit?: number;
     /** Present: the result is aggregated buckets. Absent: raw samples. */
     aggregate?: HistoryAggregation;
 }
+/**
+ * A robot's exposed values, reachable as `client.datapoints`: the latest
+ * one, a live subscription to it, and — for a datapoint configured with
+ * retention — its recorded history.
+ */
 interface DatapointsApi {
+    /**
+     * Reads the datapoint's latest value over REST, once. It carries the
+     * bridge's own capture time, so a caller can tell a fresh value from a
+     * stale one without a subscription.
+     */
     get(robotId: string, slug: string): Promise<DatapointValue>;
     /**
      * Subscribes over the realtime channel. Reconnect and re-authentication
@@ -1718,25 +1888,27 @@ interface DatapointsApi {
      * other — the `unsubscribe` frame is sent only when the last subscriber
      * on that pair goes away. This matters in practice: two widgets showing
      * the same battery value, or a component mounted twice under React
-     * StrictMode, both subscribe to the same key. The count itself lives in
-     * `slug-subscriptions.ts`, shared with `actions.subscribe`/`services.call`
-     * — a slug is one namespace across kinds, and so is its subscription.
+     * StrictMode, both subscribe to the same key. That count is shared with
+     * `actions.subscribe` and `services.call` — a slug is one namespace across
+     * kinds, and so is its subscription.
      */
     subscribe(robotId: string, slug: string, handlers: DatapointSubscriptionHandlers): DatapointSubscription;
     /**
-     * Reads recorded history for a `retention: true` datapoint (spec §8) over
-     * REST — no realtime channel involved, the same way `cameras.snapshot`
-     * isn't. Returns a **discriminated result**: passing `aggregate` gets you
-     * back `HistoryBucketsResponse` (`kind: 'buckets'`), leaving it out gets
-     * you `HistorySamplesResponse` (`kind: 'samples'`) — two overloads so a
-     * caller who already knows which one they asked for isn't forced to
-     * narrow something they determined themselves. `kind` still carries the
-     * same information on both, so code that holds the result dynamically
-     * (e.g. read from a variable typed as the union) can still branch on it.
+     * Reads recorded history for a `retention: true` datapoint over REST — no
+     * realtime channel involved, the same way `cameras.snapshot` isn't. **This
+     * overload is the aggregated one:** `aggregate` is given, so it resolves
+     * with `HistoryBucketsResponse` (`kind: 'buckets'`) — one row per window,
+     * reduced by `aggregate.agg`. Leave `aggregate` out and the other overload
+     * gives you raw samples instead.
+     *
+     * Two overloads rather than one union so a caller who already knows which
+     * they asked for isn't forced to narrow something they determined
+     * themselves. `kind` still carries the same information on both, so code
+     * holding the result dynamically can still branch on it.
      *
      * **Rejects, does not silently empty out, two specific refusals** —
      * unlike `cameras.snapshot`'s absorption of `no_snapshot_yet` into a null
-     * read, these two must reach the caller as thrown `FleetlessError`s:
+     * read, these two must reach the caller as a rejected `FleetlessError`:
      * - `not_recorded` — the slug exists and is granted, but is configured
      *   live-only. An empty result here would look exactly like "recorded,
      *   but nothing in this window", and the two need opposite fixes: turn
@@ -1747,20 +1919,34 @@ interface DatapointsApi {
     history(robotId: string, slug: string, options: HistoryOptions & {
         aggregate: HistoryAggregation;
     }): Promise<HistoryBucketsResponse>;
+    /**
+     * The same read without `aggregate`: resolves with
+     * `HistorySamplesResponse` (`kind: 'samples'`), every recorded sample in
+     * the window as a `timestamp_ms` and a `value`. `timestamp_ms` is the
+     * bridge's own capture time, the same instant the live value carried, so a
+     * recorded point and a live one sit on one axis without apology.
+     *
+     * **Read `truncated`.** The platform caps how much one read returns, by
+     * row count or by bytes, and `truncated_by` says which. A short array that
+     * does not admit it is indistinguishable from a quiet period, and the two
+     * lead to opposite conclusions. Refuses `not_recorded` the same way the
+     * aggregated overload does.
+     */
     history(robotId: string, slug: string, options: HistoryOptions & {
         aggregate?: undefined;
     }): Promise<HistorySamplesResponse>;
 }
 
 /**
- * An end user's own consent grants (spec §3.4/§17, W9c, DEF-099) — every
+ * An end user's own consent grants, reachable as `client.grants` — every
  * client this identity has ever authorized, and the means to take one back
  * without touching any of the others.
  *
  * **End-user only.** A server key acts with the app's own full rights and
  * never went through a consent screen itself — there is no "self" here for
- * it to list or revoke, same reasoning as `auth.login`/`auth.register` on a
- * `serverKey` client.
+ * it to list or revoke, same reasoning as `auth.login` on a `serverKey`
+ * client. An end user reaches a group by invitation and signs in through
+ * `auth.login` or the hosted login; a server key never does either.
  */
 interface GrantsApi {
     /**
@@ -1769,9 +1955,9 @@ interface GrantsApi {
      * `role_name`) — the id is what `revoke()` addresses, but a person
      * deciding whether to revoke something needs to *recognise* it first, and
      * an id is not recognisable. **`client_name` is not trusted** — a
-     * self-registered client chooses its own display name (W7c already
-     * measured what that buys: one called itself "Fleetless Official
-     * Helper") — do not render it as if Fleetless vouched for it.
+     * self-registered client chooses its own display name, and one has
+     * already been measured calling itself "Fleetless Official Helper" — do
+     * not render it as if Fleetless vouched for it.
      */
     list(): Promise<ConsentGrantSummary[]>;
     /**
@@ -1786,9 +1972,8 @@ interface GrantsApi {
      * about access tokens, which are stateless and short-lived by design.
      *
      * **What actually happens to an already-issued access token is stronger
-     * than that count implies, and it was measured, not assumed (W9c gate
-     * step 1, 2026-08-19, end to end through this SDK against a real
-     * cloud).** It does not simply expire on its own: the cloud re-checks
+     * than that count implies.** It does not simply expire on its own: the
+     * cloud re-checks
      * every request for a revoked grant, so **any** currently-valid access
      * token minted through this same client's OAuth flow for this end user
      * — not only the one used to call `revoke()` — answers `401
@@ -1804,18 +1989,22 @@ interface GrantsApi {
     revoke(clientId: string): Promise<ConsentRevokeResponse>;
 }
 
+/**
+ * Robot-wide job reads, reachable as `client.jobs`. Everything here is
+ * addressed by robot rather than by slug, which is what `actions` and
+ * `services` cannot do.
+ */
 interface JobsApi {
     /**
-     * Every job the platform currently believes this robot has — `GET
-     * /api/robots/:id/jobs` (W6b, contracts `robotJobsResponse` doc comment).
+     * Every job the platform currently believes this robot has.
      *
      * `actions.subscribe`/`services.call` and `GET /jobs/:slug` (the per-slug
      * route those build on) all require already knowing the slug. That is not
      * always true: a reconnecting bridge can name a job the cloud only
      * *adopted*, and a configuration change can leave a job on a slug the
      * published document no longer contains. Both are jobs no slug can name,
-     * which is exactly what this method is for (register row 2k) — an app
-     * developer had no way to reach them before this.
+     * which is exactly what this method is for — an app developer has no
+     * other way to reach them.
      *
      * At most one entry per slug: the current job there, exactly what a
      * per-slug read would answer for that slug. Not a history endpoint.
@@ -1832,18 +2021,22 @@ interface JobsApi {
      * `hello`, having never minted it, and has no other honest value to put
      * there. So this is newest-*known*-first: a job the robot has been
      * running for an hour can sit above one started a minute ago, if the
-     * hour-long one was only just adopted (contracts `robotJobsResponse` doc
-     * comment).
+     * hour-long one was only just adopted.
      */
     list(robotId: string): Promise<Job[]>;
 }
 
+/**
+ * One-way messages to a robot's publishers, reachable as
+ * `client.publishers` — a velocity command, a goal pose, anything the
+ * developer exposed as a publisher.
+ */
 interface PublishersApi {
     /**
-     * Publishes one message to a publisher (spec §4.2, §6.4).
+     * Publishes one message to a publisher.
      *
      * This is a plain method call — there is deliberately no deadman switch,
-     * rate governor or "takt" helper here (spec §14.3). The bridge's own
+     * rate governor or "takt" helper here. The bridge's own
      * `timeout_ms` failsafe is the platform's safety primitive: if messages
      * stop arriving — including because this process crashed — the bridge
      * publishes the configured failsafe message itself. That does **not**
@@ -1854,45 +2047,54 @@ interface PublishersApi {
      * building a publisher-driven control loop.
      *
      * Rejects `publisher_busy` while a different user is publishing and has
-     * not been quiet for `quiet_timeout_ms` yet (§6.4) — whoever publishes
+     * not been quiet for its configured quiet timeout yet — whoever publishes
      * holds the publisher implicitly exclusive.
      */
     publish(robotId: string, slug: string, message: Record<string, unknown>, options?: SendCommandOptions): Promise<void>;
 }
 
+/**
+ * Request/response calls to a robot, reachable as `client.services`. A
+ * service answers once and is done, which is why this namespace has a
+ * single method and nothing to subscribe to.
+ */
 interface ServicesApi {
     /**
-     * Calls a service and resolves with its result (spec §4.2, §11.3). A
-     * service call is a job underneath — the same `job_id` exchange and
-     * disconnect survival as an action (§6.1: "an action goal or a service
-     * call") — but that is deliberately invisible here: the caller gets a
+     * Calls a service and resolves with its result. A service call is a job
+     * underneath — the same `job_id` exchange and disconnect survival as an
+     * action — but that is deliberately invisible here: the caller gets a
      * plain `Promise<result>`, matching the REST `serviceCallResponse` shape's
      * developer experience. There is nothing to subscribe to for a service —
      * no feedback, no progress, no cancel — so this call already waits for
      * the terminal state internally.
      *
-     * `options.patienceMs` bounds the **whole wait** for a service call (W6b)
-     * — unlike an action, where it bounds acceptance only — because a service
+     * `options.patienceMs` bounds the **whole wait** for a service call —
+     * unlike an action, where it bounds acceptance only — because a service
      * has no further state to observe once it settles; the platform gives up
      * on the ROS call itself after this long.
      *
      * `options.timeoutMs` bounds this SDK's own local wait for the WHOLE
      * call — the ack that a job was created, plus however much of the
-     * budget is left for it to then reach a terminal state (D10) — not two
+     * budget is left for it to then reach a terminal state — not two
      * separate `timeoutMs`-length windows back to back. A caller who sets
      * `timeoutMs: 5000` is bounding total latency at ~5s, not ~10s; the
      * number means what it says, once, for the whole call.
      *
-     * It is also **not independent** of `patienceMs` (D3a): left unset, it
+     * It is also **not independent** of `patienceMs`: left unset, it
      * is derived from `patienceMs` so this SDK's local clock cannot fire
      * before the platform's own deadline has even been reached. Setting
-     * both, with `timeoutMs` shorter than `patienceMs`, throws
-     * `invalid_option` synchronously rather than letting the two race — see
-     * `resolveLocalWaitMs` in `commands.ts` for the full reasoning.
+     * both, with `timeoutMs` shorter than `patienceMs`, rejects with
+     * `invalid_option` before any request is sent rather than letting the two
+     * race — see `InvokeOptions.patienceMs` for the full reasoning.
      */
     call(robotId: string, slug: string, params: Record<string, unknown>, options?: InvokeOptions): Promise<unknown>;
 }
 
+/**
+ * Everything `createClient` accepts. `apiUrl` and `appIdentifier` are
+ * required; the rest either select the kind of caller (`tokenStore` versus
+ * `serverKey`) or replace a global the SDK would otherwise reach for.
+ */
 interface FleetlessClientOptions {
     /** Base URL of the Fleetless REST API, e.g. `https://api.fleetless.dev`. */
     apiUrl: string;
@@ -1918,27 +2120,48 @@ interface FleetlessClientOptions {
     /** Defaults to `apiUrl` with http(s) swapped for ws(s) and `/realtime` appended. */
     realtimeUrl?: string;
 }
+/**
+ * The settled configuration of a client, reachable as `client.config`. It
+ * is frozen and reflects the defaults `createClient` filled in, which is
+ * what makes it worth reading: `realtimeUrl` is usually derived rather than
+ * passed.
+ */
 interface FleetlessClientConfig {
+    /** The REST base URL this client calls, exactly as passed to `createClient`. */
     readonly apiUrl: string;
+    /** The app this client acts as, exactly as passed to `createClient`. */
     readonly appIdentifier: string;
+    /** The realtime WebSocket URL in use, derived from `apiUrl` unless one was passed. */
     readonly realtimeUrl: string;
 }
+/**
+ * One app's client, returned by `createClient`. Every API the SDK offers is
+ * a property on it, and all of them share this client's identity, its
+ * single realtime channel and its token refresh.
+ */
 interface FleetlessClient {
+    /** The settled configuration, including the defaults `createClient` filled in. */
     readonly config: FleetlessClientConfig;
+    /** Logging in, logging out, and reading who the caller currently is. */
     readonly auth: AuthApi;
-    /** An end user's own consent grants (spec §3.4/§17, W9c) — not available on a `serverKey` client, same reasoning as `auth`'s session-only methods. */
+    /** An end user's own consent grants — not available on a `serverKey` client, same reasoning as `auth`'s session-only methods. */
     readonly grants: GrantsApi;
+    /** A topic's latest value, a live subscription to it, and its recorded history. */
     readonly datapoints: DatapointsApi;
+    /** Long-running work on the robot: invoke, cancel, and watch a job as it runs. */
     readonly actions: ActionsApi;
+    /** Request/response calls to the robot that answer once and are done. */
     readonly services: ServicesApi;
+    /** One-way messages to a robot's publisher, such as a velocity command. */
     readonly publishers: PublishersApi;
+    /** Camera snapshots, their age, and live video sessions. */
     readonly cameras: CamerasApi;
     /**
      * Robot-wide job reads that do not fit under `actions`/`services` because
      * they are not addressed by slug — see `JobsApi.list`.
      */
     readonly jobs: JobsApi;
-    /** URDF + mesh reads (spec §4.6) — list/get/urdf, plus the `urdf-loader` mesh callback. */
+    /** URDF and mesh reads — list/get/urdf, plus the `urdf-loader` mesh callback. */
     readonly assets: AssetsApi;
     /**
      * Closes the realtime channel and stops it from reconnecting. Safe to
@@ -1951,6 +2174,16 @@ interface FleetlessClient {
      */
     close(): void;
 }
+/**
+ * Builds a client for one app. Pass `tokenStore` (or nothing — the default
+ * keeps the session in memory) for an end-user client that logs in with
+ * `auth.login` or the hosted login; pass `serverKey` for a server-side
+ * caller that never holds a user session. Passing both throws, because the
+ * two are different identities and a client acts as exactly one.
+ *
+ * Nothing is fetched here: the realtime channel opens on the first
+ * subscription and closes on `close()` or `auth.logout()`.
+ */
 declare function createClient(options: FleetlessClientOptions): FleetlessClient;
 
-export { type ActionsApi, type Asset, type AssetBytes, type AssetListResponse, type AssetsApi, type AuthApi, type BeginHostedLoginOptions, type BusyDetails, type CameraDescriptor, type CameraLiveSession, type CameraSnapshot, type CameraSnapshotMeta, type CamerasApi, type ClientIdentity, type CompleteHostedLoginOptions, type ConsentGrantSummary, type ConsentRevokeResponse, type CreateMeshLoaderOptions, type DatapointEvent, type DatapointSubscription, type DatapointSubscriptionHandlers, type DatapointValue, type DatapointsApi, type FleetlessClient, type FleetlessClientConfig, type FleetlessClientOptions, FleetlessError, type FleetlessErrorCode, type FleetlessErrorOptions, type GrantsApi, type HistoryAggregation, type HistoryBucketsResponse, type HistoryOptions, type HistorySamplesResponse, type HostedLoginRequest, InMemoryTokenStore, type Job, type JobEvent, type JobState, type JobSubscription, type JobSubscriptionHandlers, type JobsApi, type LogoutResult, type MeshLoaderDelegate, type ParameterInvalidDetails, type ParameterViolation, type PrepareUrdfSceneOptions, type PublishersApi, type RateLimitDetails, SDK_ERROR_CODES, type SdkErrorCode, type SendCommandOptions, type ServicesApi, type StoredSession, type TokenStore, type UrdfCompleteness, type UrdfSceneManager, type UrdfSceneResources, createClient, parameterInvalidDetails };
+export { type ActionsApi, type Asset, type AssetBytes, type AssetListResponse, type AssetsApi, type AuthApi, type BeginHostedLoginOptions, type BusyDetails, type CameraDescriptor, type CameraLiveSession, type CameraSnapshot, type CameraSnapshotMeta, type CamerasApi, type ClientIdentity, type CompleteHostedLoginOptions, type ConsentGrantSummary, type ConsentRevokeResponse, type CreateMeshLoaderOptions, type DatapointEvent, type DatapointSubscription, type DatapointSubscriptionHandlers, type DatapointValue, type DatapointsApi, type FleetlessClient, type FleetlessClientConfig, type FleetlessClientOptions, FleetlessError, type FleetlessErrorCode, type FleetlessErrorOptions, type GrantsApi, type HistoryAggregation, type HistoryBucketsResponse, type HistoryOptions, type HistorySamplesResponse, type HostedLoginRequest, InMemoryTokenStore, type InvokeOptions, type Job, type JobEvent, type JobState, type JobSubscription, type JobSubscriptionHandlers, type JobsApi, type LogoutResult, type MeshLoaderDelegate, type ParameterInvalidDetails, type ParameterViolation, type PrepareUrdfSceneOptions, type PublishersApi, type RateLimitDetails, SDK_ERROR_CODES, type SdkErrorCode, type SendCommandOptions, type ServicesApi, type StoredSession, type TokenStore, type UrdfCompleteness, type UrdfSceneManager, type UrdfSceneResources, createClient, parameterInvalidDetails };