@fleetless/sdk 2.0.2 → 3.0.0

package/dist/index.d.cts

@@ -18,9 +18,9 @@ import { z } from 'zod';
  *    admits it lost track.
  */
 declare const jobState: z.ZodEnum<{
+    failed: "failed";
     running: "running";
     succeeded: "succeeded";
-    failed: "failed";
     cancelled: "cancelled";
     lost: "lost";
 }>;
@@ -30,9 +30,9 @@ declare const job: z.ZodObject<{
     robot_id: z.ZodUUID;
     slug: z.ZodString;
     state: z.ZodEnum<{
+        failed: "failed";
         running: "running";
         succeeded: "succeeded";
-        failed: "failed";
         cancelled: "cancelled";
         lost: "lost";
     }>;
@@ -65,9 +65,9 @@ declare const jobEvent: z.ZodObject<{
         robot_id: z.ZodUUID;
         slug: z.ZodString;
         state: z.ZodEnum<{
+            failed: "failed";
             running: "running";
             succeeded: "succeeded";
-            failed: "failed";
             cancelled: "cancelled";
             lost: "lost";
         }>;
@@ -97,9 +97,9 @@ declare const busyDetails: z.ZodObject<{
         robot_id: z.ZodUUID;
         slug: z.ZodString;
         state: z.ZodEnum<{
+            failed: "failed";
             running: "running";
             succeeded: "succeeded";
-            failed: "failed";
             cancelled: "cancelled";
             lost: "lost";
         }>;
@@ -256,6 +256,9 @@ type DatapointEvent = z.infer<typeof datapointEvent>;
  * Access plus refresh (spec §3.4). The access token is short-lived; the
  * refresh token rotates on every use, so a stolen one is detectable when the
  * original is presented again.
+ *
+ * One shape for both identity spaces: a session is a session, and the claims
+ * inside the token are what differ.
  */
 declare const sessionTokens: z.ZodObject<{
     access_token: z.ZodString;
@@ -265,105 +268,149 @@ declare const sessionTokens: z.ZodObject<{
 type SessionTokens = z.infer<typeof sessionTokens>;
 
 /**
- * **What logout can and cannot end, said in three separable facts (W9c,
- * DEF-098).**
+ * **Why a federated sign-in ended without a session, in a code the app can
+ * branch on** — carried back to the app's own `redirect_uri` as `error`, not
+ * rendered by Fleetless (D2). The only Fleetless-rendered page in this flow is
+ * the one for a state that can no longer be resolved to a redirect URI, because
+ * then there is nowhere to send the answer.
  *
- * Until now this route answered `204`: the Fleetless session was over and the
- * response had nothing to say about the *other* session. For a federated user
- * that is the larger half — they clicked "log out", the IdP's cookie survived,
- * and the next login goes straight through without a password. The register
- * row calls that an expectation gap, and it is: the word on the button is
- * "log out", not "log out of this app".
+ * The five rows of D4's table are the first five values plus `no_access`:
+ *
+ * - `no_access` — the identity is unknown and nothing admits it, or the account
+ *   it names is not `active`. **One code for both**, because to the person the
+ *   remedy is the same — ask somebody to let you in — and a code that split an
+ *   outcome nobody acts on differently would tell a stranger which half applied.
+ * - `email_taken` — the address already belongs to another app user, and the
+ *   provider is not permitted to link (`link_verified_emails`, or the provider
+ *   did not assert `email_verified`). Deliberately not `no_access`: the remedy
+ *   is different — *sign in the way you signed up*.
+ * - `email_unverified` — the provider asserted an address without
+ *   `email_verified`. **An unverified address never produces or links an
+ *   account**, whatever the rest of the policy says.
+ * - `domain_not_allowed`, `registration_closed` — the self-registration policy
+ *   refused. Honest, because neither is about whether a person exists.
+ * - `idp_unavailable`, `exchange_failed`, `claims_incomplete`,
+ *   `provider_misconfigured`, `provider_disabled` — the provider's or the
+ *   developer's to fix, and the app can say so.
+ * - `invalid_request` — the start parameters did not hold up.
+ * - `quota_exceeded` — the org has as many app users as its `max_end_users`
+ *   quota allows, so no account can be created for this identity. Named rather
+ *   than folded into `no_access`, for `domain_not_allowed`'s reason: it is not
+ *   about the person, the app can say what happened, and the remedy belongs to
+ *   the developer rather than to whoever is trying to sign in. It is raised
+ *   **only where an account would be created** — an identity that already has
+ *   one signs in at the quota exactly as it does under it, because refusing a
+ *   sign-in would turn a protection limit into an outage.
+ */
+declare const clientOidcErrorCode: z.ZodEnum<{
+    no_access: "no_access";
+    email_taken: "email_taken";
+    email_unverified: "email_unverified";
+    domain_not_allowed: "domain_not_allowed";
+    registration_closed: "registration_closed";
+    idp_unavailable: "idp_unavailable";
+    exchange_failed: "exchange_failed";
+    claims_incomplete: "claims_incomplete";
+    provider_misconfigured: "provider_misconfigured";
+    provider_disabled: "provider_disabled";
+    invalid_request: "invalid_request";
+    quota_exceeded: "quota_exceeded";
+}>;
+type ClientOidcErrorCode = z.infer<typeof clientOidcErrorCode>;
+/**
+ * **A pending MCP authorization, as the app's own consent screen reads it**
+ * (D7). Fleetless renders no page here either: `authorize` redirects to the
+ * app's `mcp_login_url` with an interaction id, the app authenticates the user
+ * with its normal UI, shows this, and approves or denies through the API.
  *
- * **The Fleetless session is ended before this is computed, unconditionally.**
- * Nothing below can fail in a way that leaves the caller logged in here — a
- * logout that depends on reaching a third party is not a logout.
+ * `client_name_verified` is `z.literal(false)`, and that is the whole point of
+ * the field. The name comes from an **unauthenticated** dynamic registration —
+ * the client typed it about itself, nobody checked it — so a consent screen
+ * that rendered it as though it were an identity would be teaching people to
+ * trust a string an attacker chooses. A literal rather than a boolean because
+ * there is no verified case to distinguish: an app that reads this field at all
+ * has to handle the untrusted one, and a `true` branch would be dead code
+ * pretending to be a safeguard.
+ */
+declare const clientMcpInteraction: z.ZodObject<{
+    id: z.ZodString;
+    app_id: z.ZodUUID;
+    client_name: z.ZodNullable<z.ZodString>;
+    client_name_verified: z.ZodLiteral<false>;
+    scopes: z.ZodArray<z.ZodString>;
+    already_granted: z.ZodBoolean;
+    expires_at: z.ZodISODateTime;
+}, z.core.$strip>;
+type ClientMcpInteraction = z.infer<typeof clientMcpInteraction>;
+/**
+ * **One standing MCP consent, as both withdrawal doors list it.**
  *
- * **Four outcomes**, and they are deliberately not collapsed into a nullable
- * URL. *No IdP was involved* and *an IdP was involved and publishes no
- * `end_session_endpoint`* are different things: the first needs no action and
- * the second means a session survives that this platform cannot end. A caller
- * that renders them identically is choosing to; a contract that cannot tell
- * them apart makes the choice for everyone.
+ * A grant is what lets a later authorization skip the app's consent screen:
+ * `clientMcpInteraction.already_granted` is a read of exactly this row. It is
+ * written when a person approves and it is removed by neither the client's
+ * registration lapsing nor its access token expiring — so without a door it
+ * was a decision a person could make once and never unmake.
  *
- * **This sentence said "three" for a whole wave, directly above a four-branch
- * union in this same file** — found by Momus-W9, along with the same number in
- * `sdk/src/auth.ts` and `sdk/README.md`. The type is derived
- * (`ClientLogoutResponse['idp_logout']`), so `tsc` had nothing to say, and the
- * sweep shows the mechanism plainly: `sdk d065447` is literally titled *"logout
- * says three separable things"* — correct when written, never carried forward
- * when `hint_unavailable` arrived in `b417d2a`.
+ * **Standing only.** A withdrawn grant is stamped rather than deleted, so the
+ * store still holds it; neither listing returns one. The question both doors
+ * ask is *what is connected right now*, and a row that answered "connected,
+ * but no" would be a state every caller has to filter for itself.
  *
- * The count is not the point. **`hint_unavailable` is precisely the case this
- * comment warns about** — the IdP session survives — so a caller who handles
- * the three documented branches drops it into an `else` they believe means
- * *nothing to do*.
+ * `client_name_verified` is `z.literal(false)` for the reason
+ * `clientMcpInteraction` gives at length: the name comes from an
+ * unauthenticated dynamic registration, the client chose it about itself, and
+ * a list that rendered it as an identity would be teaching people to trust a
+ * string an attacker picked. Here it matters more than on the consent screen,
+ * not less — a "connected apps" list is read long after the moment of
+ * approval, when nobody remembers what they clicked.
  */
-declare const clientLogoutResponse: z.ZodObject<{
-    idp_logout: z.ZodDiscriminatedUnion<[z.ZodObject<{
-        status: z.ZodLiteral<"redirect">;
-        url: z.ZodURL;
-    }, z.core.$strip>, z.ZodObject<{
-        status: z.ZodLiteral<"not_federated">;
-    }, z.core.$strip>, z.ZodObject<{
-        status: z.ZodLiteral<"unsupported_by_idp">;
-    }, z.core.$strip>, z.ZodObject<{
-        status: z.ZodLiteral<"hint_unavailable">;
-    }, z.core.$strip>, z.ZodObject<{
-        status: z.ZodLiteral<"session_unknown">;
-    }, z.core.$strip>], "status">;
+declare const mcpConsentGrant: z.ZodObject<{
+    client_id: z.ZodString;
+    client_name: z.ZodNullable<z.ZodString>;
+    client_name_verified: z.ZodLiteral<false>;
+    granted_at: z.ZodISODateTime;
 }, z.core.$strip>;
-type ClientLogoutResponse = z.infer<typeof clientLogoutResponse>;
+type McpConsentGrant = z.infer<typeof mcpConsentGrant>;
 /**
  * Who the caller turned out to be. Returned by the "who am I" endpoint and by
  * the realtime `auth_ok` frame, so a client can render a session without
  * decoding a token itself — decoding a JWT in the client is how apps end up
  * trusting claims nobody verified.
  *
- * **Three kinds of caller reach the client API, not two.** Besides end users
- * and server keys, a **developer** does: spec §15.2 says the console's
- * playground runs over the real client API and appears in the audit as the
- * developer, and the console's own live views (robot list badges, the Live
- * tab) subscribe on `/realtime` as one. A developer is **org-scoped, not
+ * **Three kinds of caller reach the client API.** Besides app users and server
+ * keys, a **developer** does: the console's playground runs over the real
+ * client API and appears in the audit as the developer, and the console's own
+ * live views subscribe on `/realtime` as one. A developer is **org-scoped, not
  * app-scoped** — they own the configuration of every robot in their org — so
  * `app_id` and `role_id` are null for them, and roles do not filter what they
- * see. `kind` states this explicitly rather than leaving it to be inferred
- * from which id happens to be set.
+ * see. `kind` states this explicitly rather than leaving it to be inferred from
+ * which id happens to be set.
  *
- * **`act` is the real admin behind an impersonation** (spec
- * `2026-08-29-org-identity-redesign`, D4, the `act`-claim pattern of RFC
- * 8693). An Org Admins member entering an app through the interstitial
- * (`impersonationChoice`) gets a token whose *effective* identity is the role
- * or user they chose — that is what the rest of this shape describes — while
- * `act` names **the admin who is actually driving**. So every action can
- * audit as "Admin A as User B / as role X", and a client can render the "you
- * are acting as …" banner without decoding the token.
+ * **`end_user_id` became `app_user_id`, and that is a rename with a meaning.**
+ * The old subject was a member of the org's one pool, reachable through an
+ * assignment; the new one is a row that belongs to exactly one app. Renaming
+ * rather than keeping the key is deliberate: a consumer reading `.end_user_id`
+ * would have typechecked and meant something subtly different, which is the
+ * quietest way for a cut like this to go wrong.
  *
- * **Optional, not a nullable actor, for `orgUser.tier`'s reason:** absence
- * means *this is an ordinary session, nobody is delegating*, which is not the
- * same fact as *the actor is unknown*. The overwhelming majority of sessions
- * are ordinary and carry no `act` at all; a session that has one is a
- * delegation and says who by. The schema cannot check that `act` is present
- * exactly when the effective identity was impersonated — that pairing is the
- * cloud's, minted at the authorize step. Only the admin's **id** rides here:
- * the label is resolved by whoever renders it, not carried as a second
- * unverified name on the wire.
+ * **`act` is gone.** It named the org admin behind an impersonation (the RFC
+ * 8693 pattern). Impersonation is deleted with no successor (D1), so a field
+ * that could still arrive would describe a delegation nothing can mint — and a
+ * client rendering "you are acting as …" from it would be showing a state the
+ * platform cannot enter.
  */
 declare const clientIdentity: z.ZodObject<{
     kind: z.ZodEnum<{
-        server_key: "server_key";
         developer: "developer";
-        end_user: "end_user";
+        server_key: "server_key";
+        app_user: "app_user";
     }>;
     developer_id: z.ZodNullable<z.ZodUUID>;
-    end_user_id: z.ZodNullable<z.ZodUUID>;
+    app_user_id: z.ZodNullable<z.ZodUUID>;
     server_key_id: z.ZodNullable<z.ZodUUID>;
     app_id: z.ZodNullable<z.ZodUUID>;
     role_id: z.ZodNullable<z.ZodUUID>;
     email: z.ZodNullable<z.ZodEmail>;
-    act: z.ZodOptional<z.ZodObject<{
-        admin_user_id: z.ZodUUID;
-    }, z.core.$strict>>;
 }, z.core.$strip>;
 type ClientIdentity = z.infer<typeof clientIdentity>;
 
@@ -423,9 +470,9 @@ declare const assetSyncStatus: z.ZodObject<{
     sync_id: z.ZodUUID;
     robot_id: z.ZodUUID;
     state: z.ZodEnum<{
+        failed: "failed";
         running: "running";
         succeeded: "succeeded";
-        failed: "failed";
     }>;
     done: z.ZodNumber;
     total: z.ZodNumber;
@@ -467,9 +514,9 @@ declare const assetListResponse: z.ZodObject<{
         sync_id: z.ZodUUID;
         robot_id: z.ZodUUID;
         state: z.ZodEnum<{
+            failed: "failed";
             running: "running";
             succeeded: "succeeded";
-            failed: "failed";
         }>;
         done: z.ZodNumber;
         total: z.ZodNumber;
@@ -543,84 +590,14 @@ 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", "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", "idp_unavailable", "mcp_disabled", "tool_not_available", "capability_required", "last_owner", "target_state_conflict", "signup_closed", "draft_not_a_document", "internal_error", "not_cancellable", "unsupported_media_type", "wrong_browser", "invalid_yaml", "unstorable_yaml", "registration_closed", "domain_not_allowed", "email_unverified", "origin_not_allowed", "template_invalid", "provider_disabled", "provider_misconfigured", "invalid_redirect_uri", "interaction_expired"];
 type ErrorCode = (typeof ERROR_CODES)[number];
 
-/**
- * **What an end user sees about their own consents, and why it is not
- * `consentGrant` (W9c, DEF-099).**
- *
- * `consentGrant` is the *record* — four ids and a scope string. A person
- * deciding whether to revoke something needs to recognise it, and an id is
- * not recognisable. So this carries the names that were on the screen when
- * they consented: the client's, the app's, and the role's.
- *
- * `client_id` stays, because it is what a revocation addresses — the names
- * are for reading, the id is for acting.
- */
-declare const consentGrantSummary: z.ZodObject<{
-    client_id: z.ZodString;
-    client_name: z.ZodString;
-    app_id: z.ZodUUID;
-    app_name: z.ZodString;
-    role_id: z.ZodUUID;
-    role_name: z.ZodString;
-    scope: z.ZodString;
-    granted_at: z.ZodISODateTime;
-}, z.core.$strip>;
-type ConsentGrantSummary = z.infer<typeof consentGrantSummary>;
-/**
- * **Revoking one grant must end the access it authorised, not merely forget
- * that it happened (W9c, DEF-099).**
- *
- * The register row is about a user who wants a specific client to stop, and
- * the failure mode to avoid is a revocation that deletes the consent row
- * while every already-issued token keeps working until it expires. So the
- * response says what was actually ended, and a caller can tell *nothing
- * matched* from *matched and ended*.
- *
- * `tokens_revoked` is the count of refresh **families** ended. It is not a
- * count of access tokens, and deliberately so: an access token is stateless
- * and short-lived, and a number that claimed to have revoked one would be the
- * kind of sentence this project keeps having to take back.
- *
- * **What actually happens to the access token is stronger than this comment
- * first claimed, and narrower than its correction (W9c, 2026-08-19).** The
- * first version said *"let the access token expire"*. It does not. The
- * correction then said *"the same access token dies"*, which is true and
- * under-specified — Data-W9c read `resolveAnyToken` instead of copying the
- * sentence and found what the check is actually bound to:
- *
- *   `if (claims.client_id) { ...consent-grant lookup... }`
- *
- * So the immediate death is scoped to **`client_id`, not to a session and not
- * to the end user.** Every currently-valid token issued through *this
- * client's* OAuth flow for this end user dies at once — including a second
- * tab holding a different token from the same client. A plain `auth.login()`
- * session is untouched, because it carries no `client_id` for the check to
- * read, and a token bound to a *different* client is untouched too.
- *
- * That distinction is the whole point of revoking one grant rather than
- * logging somebody out: *"without touching any other client's access"* is
- * what this route promises, and the check is what makes it true.
- *
- * That is a better outcome than the contract promised, and it is written down
- * here for one reason: **a caller must not build on the weaker sentence.** If
- * this platform ever moves to stateless verification without the revocation
- * re-check, the access token would start living out its TTL again, and
- * anything that quietly relied on immediate death would break silently.
- */
-declare const consentRevokeResponse: z.ZodObject<{
-    revoked: z.ZodBoolean;
-    tokens_revoked: z.ZodNumber;
-}, z.core.$strip>;
-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 +605,109 @@ 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()`
- *   returned for this attempt (or with no `state` at all — `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. **A fourth since 3.0.0:**
+ *   every `auth` method needing an app user's own session, called on a client
+ *   built with a `serverKey` — `register`, `login`, `logout`, the password
+ *   and invitation calls, both OIDC calls, the two MCP decisions and the two
+ *   grant calls. Those threw a bare `Error` before, which a caller could only
+ *   catch by message. All of them 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.
+ * - `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.completeOidcLogin()` was called with a `state`
+ *   that does not match the `expectedState` its own `beginOidcLogin()`
+ *   returned for this attempt — or with no `state` at all (`beginOidcLogin`
  *   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
- *   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 a flow this client started), or with an **empty `expectedState`**,
+ *   meaning nothing was persisted for this attempt at all. That last case is
+ *   folded in rather than given its own code: two empty strings compare
+ *   equal, so it has to be checked explicitly or the comparison defends
+ *   nothing for exactly the callers most likely to hit it — but a caller
+ *   branching on the code has the same next step either way, which is to
+ *   start the sign-in again. Which of the two happened is in the message,
+ *   because the *developer's* remedies do differ ("check how your app
+ *   persisted the value" versus "this response belongs to a sign-in you did
+ *   not start"). Thrown before `/api/client/oidc/exchange` is ever 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 one-time code would already have been spent 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_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.
  */
-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"];
 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 +715,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 +842,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 +860,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 +871,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 +888,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 +900,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 +915,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 +926,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 +952,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 +966,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 +992,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 +1056,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 +1089,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 +1111,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 +1124,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 +1143,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 +1164,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 +1197,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,356 +1225,380 @@ 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). */
-interface BeginHostedLoginOptions {
+/**
+ * `register()`'s input. The app identifier is **not** here: the client already
+ * holds one (`createClient({ appIdentifier })`) and sends it itself, so there
+ * is no way for a caller to register somebody into a different app than the
+ * one this client speaks for.
+ */
+interface RegisterOptions {
+    /** The address the verification mail goes to. Nothing works until that link is spent. */
+    email: string;
+    /** At least 12 characters — `clientRegisterRequest` refuses less with a `validation_error`. */
+    password: string;
     /**
-     * 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").
+     * What the app should call this person. Optional, and **omitted from the
+     * request entirely** when you do not pass it — `clientRegisterRequest` is a
+     * strict schema, so a key carrying `undefined` would be a `422` rather than a
+     * default.
      */
-    clientId: string;
+    displayName?: string;
+}
+/** `acceptInvitation()`'s input — the token out of the mailed link, plus the password the account gets. */
+interface AcceptInvitationOptions {
+    /** The `token` from the invitation link the developer's app was linked to. */
+    token: string;
+    /** At least 12 characters. The invitation fixes the role; this call fixes the credential. */
+    password: string;
+    /** Optional, and omitted from the request entirely when absent — same strict-schema reason as `RegisterOptions.displayName`. */
+    displayName?: string;
+}
+/** One sign-in button on the app's own login screen, as `listProviders()` lists it. */
+interface ProviderButton {
+    /** What `beginOidcLogin` addresses this provider by. */
+    slug: string;
+    /** The label the developer configured, to be rendered on the button. */
+    name: string;
+}
+/** `beginOidcLogin()`'s input: which provider, and where Fleetless should send the browser back to. */
+interface BeginOidcLoginOptions {
+    /** A `slug` from `listProviders()`. An unknown one is a `404` when the browser reaches the start route, not here. */
+    slug: 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).
+     * Where the browser comes back to with `?code=…&state=…` (or `?error=…`).
+     * Checked against the app's **allowed origins** server-side, by origin — so
+     * the path is yours to choose and the origin is not.
+     *
+     * **Two shapes are refused outright, before the origin is compared**, and
+     * neither refusal mentions them: a URL carrying a **fragment**
+     * (`https://app.example.com/#/auth/callback`) and one carrying **userinfo**
+     * (`https://someone@app.example.com/cb`). Both come back as a flat
+     * `400 invalid_redirect_uri` reading "The redirect_uri is not an origin this
+     * app answers for", which sends people to re-check an allow-list that was
+     * never the problem.
+     *
+     * The fragment case is the one that costs time, because hash routing is the
+     * default for a static-hosted SPA with no server rewrite. Give the callback
+     * a real path (`/auth/callback`) and let your router pick the hash route up
+     * from there; a fragment is a browser-side construct the redirect could not
+     * carry a code in anyway.
      */
     redirectUri: string;
-    scope?: string;
+}
+/** What `beginOidcLogin()` returns. Nothing here has touched the network. */
+interface OidcLoginRequest {
     /**
-     * RFC 8707 audience binding (register row, W7b): 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
-     * has; that path is unaffected by this field's existence. Only a caller
-     * that is itself going to present the token to an audience-checking
-     * resource needs to ask for one.
-     *
-     * **`/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`):
-     *
-     * - `<base>/mcp-stub/resource` — the global OAuth resource stub, matched
-     *   byte-for-byte.
-     * - `<base>/mcp-stub/resource/<app_identifier>` — the per-app stub, and
-     *   only for **the calling client's own app**. This is an existence check
-     *   plus an ownership check, not a shape check: the app must exist *and*
-     *   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` —
-     * "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
-     * 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_PATHS.authorize`.
-     *
-     * Whatever you name here is re-checked at the token exchange: it must
-     * match what the code was authorized for, and it must still name a
-     * resource this client may be issued a token for.
+     * Send the end user's browser here. **This SDK does not navigate** — it has
+     * no opinion about whether that is a full page load, a popup or a native web
+     * view, the same boundary `cameras.live` draws by handing back a URL and a
+     * token and stopping there.
      */
-    resource?: string;
-}
-/** What `beginHostedLogin()` returns — nothing here has touched the network yet. */
-interface HostedLoginRequest {
-    /** Send the end user's browser here to start the hosted login page. */
     url: string;
     /**
-     * Persist this alongside `codeVerifier` before navigating away, and pass
-     * 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
-     * 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
-     * (a popup flow that never truly navigates) are all valid — that choice is
-     * the caller's.
+     * Persist this next to `codeVerifier` **before navigating away**, and pass
+     * both back into `completeOidcLogin`. The SDK does not persist them for you:
+     * the redirect back is a fresh page load for a browser app, and nothing kept
+     * in this SDK's memory survives it. `sessionStorage`, a signed cookie or a
+     * plain variable (a popup flow that never truly navigates) are all valid —
+     * that choice is the caller's, and an in-memory default here would look like
+     * it worked right up until the first real redirect.
      */
     state: string;
+    /**
+     * The PKCE code verifier for this attempt — persist it exactly as `state`.
+     * **The app runs its own PKCE against Fleetless**, a second exchange
+     * independent of the one Fleetless runs against the identity provider, which
+     * is what makes the one-time code in the redirect worth nothing to whoever
+     * else reads that URL.
+     */
     codeVerifier: string;
 }
-/** `completeHostedLogin()`'s input — the redirect back, plus what `beginHostedLogin` returned for this same attempt. */
-interface CompleteHostedLoginOptions {
-    /** The `code` query parameter from the redirect back to `redirectUri`. */
+/** `completeOidcLogin()`'s input — the redirect back, plus what `beginOidcLogin` returned for this same attempt. */
+interface CompleteOidcLoginOptions {
+    /** The `code` query parameter from the redirect back to `redirectUri`. It lives 60 seconds. */
     code: string;
     /** The `state` query parameter from that same redirect. */
     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.
-     */
+    /** The `state` this attempt's `beginOidcLogin` returned. Compared **before any network call**. */
     expectedState: string;
-    /** The `codeVerifier` this attempt's `beginHostedLogin` returned. */
+    /** The `codeVerifier` this attempt's `beginOidcLogin` returned. */
     codeVerifier: string;
-    clientId: string;
-    /** Must be the exact same string passed to `beginHostedLogin`. */
-    redirectUri: string;
-    /**
-     * Must be the exact same string passed to `beginHostedLogin`, if any.
-     * 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,
-     * 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 `approveMcpInteraction`/`denyMcpInteraction` resolve with: **where to
+ * send the browser**, and nothing else.
  *
- * `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:
- *
- * - `{ status: 'redirect', url }` — send the browser here to end the
- *   session at the IdP too. Nothing else in this SDK does that navigation
- *   for you (same "this SDK is thin" reasoning as `cameras.live`).
- * - `{ status: 'not_federated' }` — this session never came from an IdP;
- *   there is nothing else to end.
- * - `{ status: 'unsupported_by_idp' }` — it did, and the IdP publishes no
- *   `end_session_endpoint` (RP-initiated logout is optional in OIDC).
- * - `{ status: 'hint_unavailable' }` — it did, the IdP *can* end the
- *   session, and Fleetless has nothing to ask it with: the stored
- *   `id_token_hint` could not be decrypted, or the session predates the fix
- *   that started keeping one.
- * - `{ status: 'session_unknown' }` — the server did not find this session at
- *   all (the token was unknown, already superseded, revoked, or expired), so
- *   it can say **nothing** about an IdP.
+ * A denial carries a redirect too, with `error=access_denied` on it — a client
+ * that is refused has to learn so from its own callback rather than from a page
+ * nobody sent it, so both outcomes end the same way for the app: navigate here.
+ */
+interface McpInteractionDecision {
+    /** The absolute URL to navigate to. Wire field `redirect_to`. */
+    redirectTo: string;
+}
+/**
+ * Who the caller is, reachable as `client.auth` — the whole client auth API of
+ * spec §4, as JSON.
  *
- * **`unsupported_by_idp` and `hint_unavailable` both mean the IdP session
- * survives and this platform cannot end it** — do not render either one the
- * same as `not_federated`; that reports a session as fully ended when it
- * isn't.
+ * **Fleetless serves an app user no page.** The developer's own UI owns every
+ * screen: login, registration, verification, invitation acceptance, password
+ * reset, the provider buttons and the MCP consent. These methods are what those
+ * screens call. The hosted, app-branded login and consent pages this SDK used
+ * to drive are gone, along with `beginHostedLogin`/`completeHostedLogin`.
  *
- * **`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
- * 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.
+ * **The enumeration discipline is the design's, and it shapes this surface.**
+ * `register`, `resendVerification` and `requestPasswordReset` resolve for every
+ * policy-allowed request whether or not the address exists, and `login` answers
+ * the identical `invalid_credentials` for a wrong password, a blocked account
+ * and an unverified one. So: *resolving does not mean an account exists*, and
+ * the only honest refusals are the ones about policy rather than about a
+ * person — `registration_closed`, `domain_not_allowed`, `quota_exceeded`.
  *
- * 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.
+ * **A client built with a `serverKey` refuses everything that needs an app
+ * user's own session** with `invalid_option`, before any request. `me()`,
+ * `listProviders()`, `mcpInteraction()` and `oidcErrorFromCallback()` still
+ * work on one: the first is what a server key is *for*, the next two are public
+ * reads the cloud answers without any credential at all, and the last touches
+ * no network.
  */
-interface LogoutResult {
-    revoked: boolean;
-    idp_logout: ClientLogoutResponse['idp_logout'] | null;
-}
 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
-     * 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
-     * `state`/`codeVerifier` PKCE and CSRF protection need. **Makes no network
-     * call** — everything here is local, so nothing about the app, the
-     * client, or the redirect URI is validated until the browser actually
-     * reaches `/oauth/authorize`.
-     *
-     * Async only because computing the S256 `code_challenge` needs
-     * `crypto.subtle.digest`, which the Web Crypto API only ever offers as a
-     * promise — there is no synchronous digest to call instead.
+     * Self-registration. Writes the account as `pending_verification` and mails
+     * the app's verification link; **the account cannot log in until that link is
+     * spent** (`verifyEmail`).
+     *
+     * Resolves on the route's `202` — which the cloud answers for every
+     * policy-allowed request, whether the address was new or already known. It is
+     * not a claim that an account was created, and an app that renders it as one
+     * ("welcome, Ada!") is showing a stranger the enumeration oracle this whole
+     * family is built to avoid. Render "check your mail" instead.
+     *
+     * Throws a `FleetlessError` carrying the cloud's own code for a refusal, and
+     * that is the distinction this method exists to preserve: `registration_closed`
+     * (the app has self-registration off), `domain_not_allowed` (the address is
+     * outside the app's allowed domains), `quota_exceeded` (the org has as many
+     * app users as its quota allows) and `not_found` (no app carries this
+     * client's `appIdentifier`) are all things the app can say out loud, because
+     * none of them is about whether a person exists.
+     */
+    register(input: RegisterOptions): Promise<void>;
+    /**
+     * Spends a verification token and **stores the session it answers with**, so
+     * the person is not asked to log in immediately after proving they can read
+     * the mail.
+     *
+     * `token_spent` covers unknown, expired and already-used alike — one code,
+     * because the remedy is one thing: ask for a fresh link with
+     * `resendVerification`. An app rendering this refusal should offer that.
      */
-    beginHostedLogin(options: BeginHostedLoginOptions): Promise<HostedLoginRequest>;
+    verifyEmail(token: string): Promise<void>;
+    /** Asks for the verification mail again. Resolves on `202` for every policy-allowed request, existing address or not — same reason as `register`. */
+    resendVerification(email: string): Promise<void>;
     /**
-     * Completes the hosted login flow: checks `state` against `expectedState`
-     * (before any network call — see `CompleteHostedLoginOptions.expectedState`),
-     * exchanges `code` for tokens at `/oauth/token`, and stores them via the
-     * same `tokenStore` `login()` uses.
-     *
-     * **Two distinct refusals before that check, not one.** An empty
-     * `expectedState` throws `no_hosted_login_attempt` — nothing was
-     * persisted for this attempt (a different tab, a restored session,
-     * cleared storage), not necessarily an attack. Only once `expectedState`
-     * is actually present does a mismatch (or a missing `state` on the
-     * callback itself) throw `state_mismatch`. The two are told apart on
-     * purpose: they call for different remedies, and collapsing them would
-     * tell a developer debugging an ordinary storage gap that their app is
-     * under attack.
-     *
-     * 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.
-     *
-     * The wire response is RFC 6749 §5.1's envelope (`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`
-     * uses (same `refresh_tokens` row, same rotation), so the existing silent
-     * refresh (`/api/client/refresh`) already works for a hosted-login
-     * session — nothing about the origin of a session is tracked or needs to
-     * be.
-     *
-     * 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`.
-     *
-     * **Makes exactly one request to `/oauth/token` — never retried, no
-     * timeout-and-resend, no internal concurrency of its own.** Stated
-     * because the constraint that matters here is not this method's, it is
-     * the caller's: **never call this a second time for the same `code`
-     * 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 —
-     * 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):**
-     * 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
-     * visible yet. The failure surfaces at this session's **first silent
-     * refresh**, as `token_revoked`, potentially many minutes after the race
-     * that actually caused it and with nothing in that later error pointing
-     * back to a retry that "worked". If your own framework, an HTTP client
-     * wrapper, or a user's impatient double-click can cause this method to
-     * be invoked twice concurrently for the same redirect, guard against
-     * that at the call site — a simple in-flight flag or disabling the
-     * triggering control is enough, since there is only ever one legitimate
-     * exchange per authorization code.
+     * Exchanges email + password, and the client's configured app identifier, for
+     * a session.
+     *
+     * `invalid_credentials` is answered identically for a wrong password, a
+     * blocked account and one still waiting to verify. Do not try to tell them
+     * apart — there is nothing in the answer that does, deliberately.
      */
-    completeHostedLogin(options: CompleteHostedLoginOptions): Promise<void>;
+    login(email: string, password: string): Promise<void>;
     /**
-     * Ends the session: revokes the whole refresh-token family server-side
-     * (a stolen refresh token stops working immediately) and closes this
-     * client's live realtime connection, if it has one. Then clears the
-     * local store. Never rejects and always clears the store, even if the
-     * server call fails: a user who presses "log out" must end up logged out
-     * locally regardless of the network. `revoked` reports whether the
-     * server-side revoke actually happened — `false` means the refresh
-     * family may still be alive server-side even though this client has
-     * forgotten it; an app that cares (a kiosk, a shared workstation) can
-     * warn the user or retry, one that doesn't can ignore it.
+     * Ends the session: revokes the whole refresh-token family server-side (a
+     * stolen refresh token stops working immediately), closes this client's live
+     * realtime connection if it has one, and clears the local store.
+     *
+     * **Never rejects, and always clears the store**, even if the server call
+     * fails: a user who presses "log out" must end up logged out locally
+     * regardless of the network.
      *
      * **What this does not do:** invalidate the access token already issued.
-     * Access-token checks are stateless (a signed JWT, verified without a
-     * server-side lookup) — logout has nothing to flip on that token, only
-     * on the refresh family behind it. A token stolen before logout keeps
-     * working on REST, and can still open a *new* realtime connection, until
-     * it expires on its own — at most 15 minutes. This is a deliberate
-     * boundary of the stateless-JWT design (the same one that lets a role
-     * change, a block, or a membership removal take effect on the very next
-     * 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
-     * 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"
-     * boundary as everywhere else (`cameras.live` hands back a URL and a
-     * token and stops there too).
-     *
-     * **`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.
-     *
-     * 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.
+     * Access-token checks are stateless (a signed JWT, verified without a lookup),
+     * so logout has nothing to flip on that token — only on the refresh family
+     * behind it. A token stolen before logout keeps working on REST, and can
+     * still open a *new* realtime connection, until it expires on its own, at
+     * most 15 minutes. That is a deliberate boundary of the stateless-JWT design,
+     * not a bug, but a kiosk or a shared workstation needs to know the number.
+     *
+     * **Nor does it end a session at the identity provider.** It used to report
+     * what was left of one; that apparatus belonged to the hosted login, where
+     * Fleetless owned the browser. The app owns it now, and an app that wants to
+     * end a provider session redirects there itself — knowing its own provider,
+     * which Fleetless never did better than it.
      */
-    logout(): Promise<LogoutResult>;
-    /** Who the caller turned out to be, without decoding a token client-side. */
+    logout(): Promise<void>;
+    /** Who the caller turned out to be, without decoding a token client-side — which is how apps end up trusting claims nobody verified. */
     me(): Promise<ClientIdentity>;
     /**
-     * Changes the current end user's password (spec §3, W6c).
-     *
-     * `currentPassword` is required by the server even though the session
-     * already proves identity — it is what stops a stolen *session* from
-     * becoming a stolen *account* (see `passwordChangeRequest` in
-     * `@fleetless/contracts`).
-     *
-     * **Every other session of this identity is revoked on success, and this
-     * call's own session is re-issued, not left alone.** `passwordChangeRequest`
-     * carries nothing that identifies the caller's own refresh family, so the
-     * server cannot spare one token out of the family it just revoked — it
-     * revokes all of them and hands back a fresh pair, which this method
-     * stores exactly like `login` does. Skipping that store would leave the
-     * caller holding tokens the server has already revoked, working only
-     * until the access token expires and then silently logged out —
-     * indistinguishable from the change having failed, which is the one
-     * outcome this route exists to prevent. A user with other tabs or
-     * devices logged in will see *those* signed out the moment this
-     * resolves; if your app does not already make that consequence visible
-     * before they confirm, they will find out from a support ticket instead
-     * of from you.
+     * Changes the current app user's password.
+     *
+     * `currentPassword` is required even though the session already proves
+     * identity — it is what stops a stolen *session* from becoming a stolen
+     * *account*.
+     *
+     * **Every other session of this identity is revoked, and this call's own
+     * session is re-issued rather than spared.** The request carries nothing
+     * identifying the caller's own refresh family, so the server revokes all of
+     * them and hands back a fresh pair, which this method stores exactly like
+     * `login`. A user with other tabs or devices signed in will see those signed
+     * out the moment this resolves; if your app does not make that consequence
+     * visible before they confirm, they will find out from a support ticket.
      */
     changePassword(currentPassword: string, newPassword: string): Promise<void>;
+    /** Asks for a reset link. Resolves on `202` for a known and an unknown address alike — the answer says nothing about which it was. */
+    requestPasswordReset(email: string): Promise<void>;
     /**
-     * The hosted password-reset page, served by the platform on the API
-     * origin (`/reset-password`). An app links a user there; nothing is
-     * called. The two former methods that posted to `/api/client/password/…`
-     * are gone with the routes they named (2.0.0).
-     *
-     * The page owns the whole flow — it takes the address, mails a
-     * single-use link, and takes the new password on the way back — so there
-     * is nothing for an app to sequence and nothing here that could reveal
-     * whether an address belongs to an account.
+     * Spends a reset token, sets the new password and **stores the session it
+     * answers with**. Every refresh family of that user is revoked first — a
+     * forgotten password is one of the two states where somebody else may be
+     * holding a session.
      */
-    passwordResetUrl(): string;
+    confirmPasswordReset(token: string, newPassword: string): Promise<void>;
+    /**
+     * Accepts an app invitation: creates the account (or activates one invited
+     * before it existed) with the role the invitation fixed, and **stores the
+     * session**.
+     *
+     * An invitation always bypasses the app's domain whitelist — a developer
+     * inviting somebody by hand has already made the decision the whitelist
+     * automates.
+     */
+    acceptInvitation(input: AcceptInvitationOptions): Promise<void>;
+    /**
+     * The app's **enabled** sign-in providers, for drawing the buttons on your
+     * own login screen. A disabled provider is not a button that refuses; it is a
+     * button that is not there.
+     *
+     * Public and unauthenticated, and it carries nothing but `slug` and `name` on
+     * purpose: the issuer, the client id, the scopes and the linking policy are
+     * management-side facts that would tell a stranger how the app's federation
+     * is configured.
+     */
+    listProviders(): Promise<ProviderButton[]>;
+    /**
+     * Builds the URL that starts a federated sign-in, with a fresh `state` and a
+     * fresh PKCE verifier. **Makes no network call and does not navigate** —
+     * persist `state` and `codeVerifier`, then send the browser to `url`.
+     *
+     * Nothing about the app, the provider or the redirect URI is validated here;
+     * it is all checked when the browser actually reaches the route, in that
+     * order, with the redirect target checked before the provider so that a
+     * caller who got the target wrong learns nothing about which providers the
+     * app has.
+     *
+     * Async only because the S256 `code_challenge` needs `crypto.subtle.digest`,
+     * which the Web Crypto API only ever offers as a promise.
+     */
+    beginOidcLogin(input: BeginOidcLoginOptions): Promise<OidcLoginRequest>;
+    /**
+     * Completes a federated sign-in: checks `state` against `expectedState`,
+     * trades the one-time `code` for a session, and stores it.
+     *
+     * **The state check runs before any request is sent.** RFC 6749 §10.12's
+     * whole point is that a client must not complete an authorization response it
+     * did not itself request — a check made after the exchange would already have
+     * spent a code for a flow this client never started. Both an outright
+     * mismatch and an *empty* `expectedState` throw `state_mismatch`; the message
+     * says which, because the remedies differ ("check how your app persisted the
+     * value" versus "this response belongs to a sign-in you did not start") even
+     * though the next step is the same either way — start the sign-in again.
+     *
+     * The code lives 60 seconds and is single-use. Unknown, expired, replayed and
+     * "the account was blocked in between" all arrive as one `token_spent`,
+     * because the app has nothing different to do about any of them.
+     */
+    completeOidcLogin(input: CompleteOidcLoginOptions): Promise<void>;
+    /**
+     * Reads a **failed** federated sign-in off the redirect back, as a
+     * `FleetlessError` you can branch on, or `null` when the callback carries no
+     * `error` at all.
+     *
+     * Fleetless renders no page for these: the reason is carried to your own
+     * `redirectUri` as `?error=<code>`, and this turns that string into the same
+     * error type every other method throws. A code the contracts define (see
+     * `ClientOidcErrorCode`) becomes that code verbatim; anything else becomes
+     * `unexpected_response` with the raw value in the message, rather than being
+     * passed through as a code neither side defines.
+     *
+     * Purely local — it parses a query string and asks nothing.
+     */
+    oidcErrorFromCallback(params: URLSearchParams): FleetlessError | null;
+    /**
+     * Reads a pending MCP authorization by the interaction id the browser
+     * arrived with, so the app can render its own consent screen.
+     *
+     * **`client_name` is a string the client typed about itself** during an
+     * unauthenticated dynamic registration — nobody checked it, which is why
+     * `client_name_verified` is the literal `false` rather than a boolean with a
+     * `true` branch that could never happen. Do not render it as an identity.
+     *
+     * `interaction_expired` means exactly that: ten minutes ran out, or the id
+     * was never real. Both answer the same way, so the screen to show is "that
+     * took too long, start again" rather than an error.
+     *
+     * **Call this with the app user already signed in.** The route needs no
+     * credential, but it reads one if present, and `already_granted` is `false`
+     * for an anonymous read whatever the truth is — so a consent screen rendered
+     * from an unauthenticated call asks a person to agree to something they
+     * agreed to already. An **expired** token counts as anonymous to this route,
+     * which answers `200` rather than refusing, so this method probes the
+     * session's liveness first and refreshes if it can; a session that cannot be
+     * refreshed is not an error here, it is genuinely anonymous.
+     */
+    mcpInteraction(id: string): Promise<ClientMcpInteraction>;
+    /** Approves a pending MCP authorization on behalf of the signed-in app user, and returns where to send the browser. */
+    approveMcpInteraction(id: string): Promise<McpInteractionDecision>;
+    /** Denies one. Also returns a redirect — with `error=access_denied` on it, so the client learns from its own callback. */
+    denyMcpInteraction(id: string): Promise<McpInteractionDecision>;
+    /**
+     * Every MCP client this app user has standing consent for — the "connected
+     * apps" list, and the door out of a decision a person could otherwise make
+     * once and never unmake. A withdrawn grant is never listed.
+     *
+     * `client_name_verified` is `false` here for the reason it is on
+     * `mcpInteraction`, and it matters more rather than less: a list like this is
+     * read long after the moment of approval, when nobody remembers what they
+     * clicked.
+     */
+    listMcpGrants(): Promise<McpConsentGrant[]>;
+    /**
+     * Withdraws one standing consent by the client's id.
+     *
+     * Resolves whether or not there was anything to withdraw — a client id this
+     * account never approved and one it withdrew a minute ago both land on the
+     * end state the caller asked for. A refusal there would tell a caller which
+     * clients an account has connected, and would turn a double-clicked button
+     * into a failure.
+     */
+    revokeMcpGrant(clientId: string): Promise<void>;
 }
 
 /**
- * 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 +1613,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 +1674,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 +1698,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 +1708,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 +1731,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 +1780,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 +1802,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 +1830,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,75 +1861,40 @@ 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
- * 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.
+ * 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 GrantsApi {
-    /**
-     * Every client this end user has consented to, most-recently-granted
-     * first. Each entry carries names, not only ids (`client_name`, `app_name`,
-     * `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.
-     */
-    list(): Promise<ConsentGrantSummary[]>;
-    /**
-     * Revokes one grant by the client's id — the `client_id` from a
-     * `list()` entry — without touching any other client's access.
-     *
-     * `revoked` tells "nothing matched" (`false`) from "matched and ended"
-     * (`true`) — revoking a grant that is already gone (a stale id, a double
-     * click) is not an error, just a no-op the caller can still tell apart
-     * from a real revocation. `tokens_revoked` counts refresh **families**
-     * ended, not access tokens — that count is deliberately never a claim
-     * 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
-     * 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
-     * token_revoked` on its very next request, no wait for its TTL. This is
-     * scoped to that one client: a session that never went through this
-     * client's consent (a plain `auth.login()` session, or one bound to a
-     * different client) carries no trace of this client's id and is
-     * unaffected. Do not build on the weaker "it will expire eventually" —
-     * if this platform ever moves to stateless verification without that
-     * re-check, this immediacy would go away silently, which is exactly why
-     * it is written down here instead of left implied.
-     */
-    revoke(clientId: string): Promise<ConsentRevokeResponse>;
-}
-
 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 +1911,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 +1937,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 +2010,50 @@ 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;
+    /**
+     * The whole client auth API: registration, verification, login, logout,
+     * password reset, invitations, the app's federated sign-in providers, the
+     * MCP consent screen, and the app user's own standing MCP grants.
+     */
     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. */
-    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 +2066,16 @@ interface FleetlessClient {
      */
     close(): void;
 }
+/**
+ * Builds a client for one app. Pass `tokenStore` (or nothing — the default
+ * keeps the session in memory) for an app-user client that signs in with
+ * `auth.login` or a federated provider; 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 AcceptInvitationOptions, type ActionsApi, type Asset, type AssetBytes, type AssetListResponse, type AssetsApi, type AuthApi, type BeginOidcLoginOptions, type BusyDetails, type CameraDescriptor, type CameraLiveSession, type CameraSnapshot, type CameraSnapshotMeta, type CamerasApi, type ClientIdentity, type ClientMcpInteraction, type ClientOidcErrorCode, type CompleteOidcLoginOptions, type CreateMeshLoaderOptions, type DatapointEvent, type DatapointSubscription, type DatapointSubscriptionHandlers, type DatapointValue, type DatapointsApi, type FleetlessClient, type FleetlessClientConfig, type FleetlessClientOptions, FleetlessError, type FleetlessErrorCode, type FleetlessErrorOptions, type HistoryAggregation, type HistoryBucketsResponse, type HistoryOptions, type HistorySamplesResponse, InMemoryTokenStore, type InvokeOptions, type Job, type JobEvent, type JobState, type JobSubscription, type JobSubscriptionHandlers, type JobsApi, type McpConsentGrant, type McpInteractionDecision, type MeshLoaderDelegate, type OidcLoginRequest, type ParameterInvalidDetails, type ParameterViolation, type PrepareUrdfSceneOptions, type ProviderButton, type PublishersApi, type RateLimitDetails, type RegisterOptions, SDK_ERROR_CODES, type SdkErrorCode, type SendCommandOptions, type ServicesApi, type StoredSession, type TokenStore, type UrdfCompleteness, type UrdfSceneManager, type UrdfSceneResources, createClient, parameterInvalidDetails };