@fleetless/sdk 3.0.2 → 3.0.3

package/dist/index.d.ts

@@ -607,13 +607,13 @@ type ErrorCode = (typeof ERROR_CODES)[number];
  *   later on the same socket — nobody knows — but the caller cannot be made
  *   to wait forever for that.
  * - `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.
+ *   on purpose — the connection that carried the command was replaced by a
+ *   new one (a reconnect) before any reply arrived. The server, if it
+ *   answered at all, answered a socket that no longer exists, so 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`: 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
@@ -801,20 +801,19 @@ interface JobSubscriptionHandlers {
 interface JobSubscription {
     /**
      * 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.
+     * when this was the **last** holder of the robot/slug pair and the channel
+     * is connected — subscriptions are reference-counted across kinds, so a
+     * second `actions.subscribe`, `datapoints.subscribe` or in-flight
+     * `services.call` on the same pair keeps its stream running. 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.
+ * a ROS action the developer exposed under a slug: it is invoked, runs as
+ * long as it runs, and reports back while it does.
  */
 interface ActionsApi {
     /**
@@ -822,7 +821,7 @@ interface ActionsApi {
      * — 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.
+     * `error.details.running` naming the running job.
      *
      * `options.patienceMs` bounds goal *acceptance* only — once a goal
      * is accepted this call has already resolved; the job then runs as long
@@ -1106,7 +1105,7 @@ 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. **It is not that every mesh gets fetched twice.**
+     * cloud-rewritten text. **Not a double-fetch.**
      * 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
@@ -1236,7 +1235,7 @@ interface TokenStore {
 /** 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. */
+    /** 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;
@@ -1680,8 +1679,8 @@ interface CameraLiveSession {
      * courteous fast path; the robot actually stops publishing once every
      * viewer's LiveKit `Room` has disconnected, which the SFU notices on its
      * own with no cooperation required. **Always pair this with disconnecting
-     * the `Room` you connected with `url`/`token`** — see the README's
-     * Cameras section for the paired cleanup pattern; a `release()` that ran
+     * the `Room` you connected with `url`/`token`** — see the Cameras
+     * section of the SDK reference for the paired cleanup pattern; a `release()` that ran
      * alone while the `Room` stayed connected would stop nothing.
      *
      * Safe to call more than once (only the first call does anything) and
@@ -1692,14 +1691,12 @@ interface CameraLiveSession {
      * from `beforeunload`, where a call that could throw would be a liability.
      *
      * **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: 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
-     * correctness. If a future caller needs to know "did my release actually
-     * reach the cloud" (telemetry, say), that is a new, additive signal to
-     * design, not a change to this method's contract.
+     * rejection, a realtime event, or a field on this object. Deliberate, not
+     * an oversight: the only consumer of that information would be code
+     * deciding whether to retry, and the reconciliation backstop described
+     * above already makes a retry unnecessary for correctness. A future need
+     * to know "did my release actually reach the cloud" (telemetry, say) is a
+     * new, additive signal to design, not a change to this method's contract.
      */
     release(): Promise<void>;
 }
@@ -1753,12 +1750,11 @@ interface DatapointSubscriptionHandlers {
 interface DatapointSubscription {
     /**
      * 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.
+     * when this was the **last** holder of the robot/slug pair and the channel
+     * is connected — subscriptions are reference-counted across kinds, so
+     * releasing this one while a `datapoints.subscribe`, `actions.subscribe` or
+     * in-flight `services.call` still holds the same pair leaves that one's
+     * stream running. Safe to call more than once.
      */
     unsubscribe(): void;
 }
@@ -1766,11 +1762,10 @@ interface DatapointSubscription {
  * 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
- * independent optional fields a caller could set only one of. The same
- * reasoning as `cameraSource` being a discriminated union rather than
- * optional fields: make the impossible combination unrepresentable, not
- * merely rejected.
+ * chart that lies quietly — so they live in one object instead of two
+ * optional fields a caller could set only one of. Same reasoning as
+ * `cameraSource`'s discriminated union: make the impossible combination
+ * unrepresentable, not merely rejected.
  */
 interface HistoryAggregation {
     /** Bucket width, e.g. `10s`, `1m`. */
@@ -1781,9 +1776,8 @@ interface HistoryAggregation {
     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.
+ * The window `datapoints.history` reads. `aggregate` decides whether the
+ * response is raw samples or aggregated buckets.
  */
 interface HistoryOptions {
     /**
@@ -1823,9 +1817,9 @@ interface DatapointsApi {
      * Reference-counted per `(robotId, slug)`: two subscriptions to the same
      * pair share one wire subscription. Unsubscribing one never affects the
      * 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. That count is shared with
+     * on that pair goes away. In practice: two widgets showing the same
+     * battery value, or a component mounted twice under React StrictMode,
+     * 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.
      */
@@ -1838,10 +1832,9 @@ interface DatapointsApi {
      * 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.
+     * Two overloads rather than one union, so a caller who already knows which
+     * one they asked for isn't forced to narrow it. `kind` carries the same
+     * information either way, so dynamic code 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
@@ -1875,28 +1868,26 @@ interface DatapointsApi {
 }
 
 /**
- * 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.
+ * Robot-wide job reads, reachable as `client.jobs` — addressed by robot,
+ * not slug, which `actions` and `services` cannot do.
  */
 interface JobsApi {
     /**
      * 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 — 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.
-     * Grant-filtered same as `cameras.list`/`datapoints` — an end user or
-     * server key sees only jobs on slugs their role grants; a developer
-     * session sees every job on the robot. Never empty-vs-missing ambiguity:
-     * a robot doing nothing resolves `[]`.
+     * `actions.subscribe`/`services.call` and `GET /jobs/:slug` — the per-slug
+     * route those build on — all require knowing the slug already. Two cases
+     * don't: a reconnecting bridge naming a job the cloud only *adopted*, and
+     * a config change leaving a job on a slug the published document no
+     * longer contains. Neither has a slug to give — this method is the only
+     * way an app developer reaches them.
+     *
+     * At most one entry per slug: the current job there, same as a per-slug
+     * read would answer. Not a history endpoint. Grant-filtered same as
+     * `cameras.list`/`datapoints` — an end user or server key sees only jobs
+     * on slugs their role grants, a developer session sees every job on the
+     * robot. Never empty-vs-missing ambiguity: a robot doing nothing
+     * resolves `[]`.
      *
      * **Ordered newest first by `started_at`, with `job.seq` as the
      * tiebreaker** (`started_at` alone is not a total order — two jobs minted
@@ -1920,16 +1911,15 @@ interface PublishersApi {
     /**
      * Publishes one message to a publisher.
      *
-     * This is a plain method call — there is deliberately no deadman switch,
-     * 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**
-     * mean the SDK protects a caller who stops calling `publish` on purpose
-     * without stopping cleanly (e.g. no repeated call at a safe rate): the
-     * safety pattern for *how often* and *when* to publish belongs in the
-     * app, not here. See the README's "Publishers, and no teleop helpers"
-     * section before building a publisher-driven control loop.
+     * A plain method call — deliberately no deadman switch, rate governor or
+     * "takt" helper. The bridge's own `timeout_ms` failsafe is the platform's
+     * safety primitive: when messages stop arriving, crash included, the
+     * bridge publishes its configured failsafe message. That does **not**
+     * cover a caller who stops calling `publish` on purpose without stopping
+     * cleanly (e.g. no repeated call at a safe rate) — how often and when to
+     * publish is the app's pattern, not the SDK's. See the Publishers
+     * section of the SDK reference before building a
+     * publisher-driven control loop.
      *
      * Rejects `publisher_busy` while a different user is publishing and has
      * not been quiet for its configured quiet timeout yet — whoever publishes
@@ -1940,16 +1930,15 @@ interface PublishersApi {
 
 /**
  * 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.
+ * service answers once and is done — one method, nothing to subscribe to.
  */
 interface ServicesApi {
     /**
      * 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 —
+     * plain `Promise<result>`, matching the REST `serviceCallResponse` shape.
+     * 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.
      *
@@ -1962,8 +1951,7 @@ interface ServicesApi {
      * call — the ack that a job was created, plus however much of the
      * 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.
+     * `timeoutMs: 5000` bounds total latency at ~5s, not ~10s.
      *
      * It is also **not independent** of `patienceMs`: left unset, it
      * is derived from `patienceMs` so this SDK's local clock cannot fire
@@ -1986,10 +1974,9 @@ interface FleetlessClientOptions {
     /** The app's identifier (the slug shown in the console), sent on every login. */
     appIdentifier: string;
     /**
-     * Where refresh/access tokens are kept between calls. Defaults to an
-     * in-memory store — pass your own (localStorage, a cookie, a native
-     * keystore) to persist a session across reloads. The SDK never assumes a
-     * browser exists.
+     * Where refresh/access tokens live between calls. Defaults to in-memory —
+     * pass your own (localStorage, a cookie, a native keystore) to persist a
+     * session across reloads. The SDK never assumes a browser exists.
      */
     tokenStore?: TokenStore;
     /**
@@ -2051,13 +2038,13 @@ interface FleetlessClient {
     /** 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
-     * call whether or not any subscription was ever made, and safe to call
-     * more than once. A Node script (the exact use case `serverKey` is for)
-     * that never calls this after subscribing will not exit on its own — an
-     * open WebSocket keeps the event loop alive. `auth.logout()` calls this
-     * automatically; call it yourself too if the process should exit without
-     * logging out (e.g. a server-side caller shutting down).
+     * Closes the realtime channel and stops it from reconnecting. Safe with
+     * no subscription ever made, and safe to call twice. A Node script (the
+     * exact use case `serverKey` is for) that never calls this after
+     * subscribing will not exit on its own — an open WebSocket keeps the
+     * event loop alive. `auth.logout()` calls this automatically; call it
+     * yourself if the process should exit without logging out (e.g. a
+     * server-side shutdown).
      */
     close(): void;
 }

package/dist/index.js

@@ -304,7 +304,7 @@ function createAssetsApi(http) {
           finish(
             null,
             new Error(
-              `createMeshLoader and prepareUrdfScene were both installed on the same LoadingManager for robot ${robotId}. Use one or the other on a given manager, not both \u2014 see the README.`
+              `createMeshLoader and prepareUrdfScene were both installed on the same LoadingManager for robot ${robotId}. Use one or the other on a given manager, not both \u2014 see the SDK reference.`
             )
           );
           return;
@@ -8302,21 +8302,21 @@ function assertValidJobId(jobId) {
   if (jobId === void 0 || jobId === null || typeof jobId === "string") return;
   throw new FleetlessError(
     "invalid_option",
-    `cancel()'s third argument must be a job id (string), null, or omitted \u2014 got ${typeof jobId === "object" ? "an object" : typeof jobId}. If you are passing an options object (e.g. {timeoutMs}) as the third argument, note the signature changed in this release: cancel(robotId, slug) is unchanged, but a third positional argument is now the job id to cancel and options moved to a fourth argument \u2014 cancel(robotId, slug, jobId, options). See the README's Actions section.`
+    `cancel()'s third argument must be a job id (string), null, or omitted \u2014 got ${typeof jobId === "object" ? "an object" : typeof jobId}. If you are passing an options object (e.g. {timeoutMs}) as the third argument, note the signature changed in this release: cancel(robotId, slug) is unchanged, but a third positional argument is now the job id to cancel and options moved to a fourth argument \u2014 cancel(robotId, slug, jobId, options). See the Actions section of the SDK reference at https://docs.fleetless.dev/reference/sdk/`
   );
 }
 function createRealtimeCommandTransport(channel) {
   return {
-    // Declared `async` deliberately, unlike `cancel`/`publish` below: it is
+    // Declared `async` deliberately, unlike `cancel`/`publish` below: it's
     // the only one of the three that can refuse *before* sending anything
-    // (`resolveLocalWaitMs`'s `invalid_option`), and every caller of
-    // this interface — starting with this file's own `sendCommand` callers
-    // — is entitled to assume `CommandTransport.invoke` always returns a
-    // promise rather than throwing synchronously. Without `async` here, a
-    // synchronous throw from `resolveLocalWaitMs` would escape as a thrown
-    // exception instead of a rejection, breaking that assumption for any
-    // caller that isn't itself inside an `async` function (e.g. a test
-    // calling this transport directly).
+    // (`resolveLocalWaitMs`'s `invalid_option`), and every caller of this
+    // interface — starting with this file's own `sendCommand` callers —
+    // assumes `CommandTransport.invoke` always returns a promise, never
+    // throws synchronously. Without `async` here, a synchronous throw from
+    // `resolveLocalWaitMs` would escape as a thrown exception instead of a
+    // rejection, breaking that assumption for a caller that isn't itself
+    // inside an `async` function (e.g. a test calling this transport
+    // directly).
     async invoke(robotId, slug2, params, options) {
       const timeoutMs = resolveLocalWaitMs(options ?? {}, DEFAULT_COMMAND_TIMEOUT_MS);
       const frame = {
@@ -8516,12 +8516,11 @@ var RealtimeChannel = class {
   }
   /**
    * Increments on every successful authentication (first connect and every
-   * reconnect). A command sent on one physical socket can only ever be
-   * answered on that socket — comparing the epoch captured at send time
-   * against the current one is how a caller (see `commands.ts`) tells "still
-   * waiting on the connection it was sent over" from "that connection is
-   * gone and a new one has taken its place", the moment it happens rather
-   * than after a timeout elapses.
+   * reconnect). A command sent on one socket can only be answered on that
+   * socket — comparing the epoch at send time against the current one is
+   * how a caller (see `commands.ts`) tells "still waiting on the connection
+   * it was sent over" from "that connection is gone and a new one has taken
+   * its place", the moment it happens rather than after a timeout elapses.
    */
   get connectionEpoch() {
     return this.#connectionEpoch;
@@ -8822,7 +8821,7 @@ function createSlugSubscriptions(channel) {
 // src/token-store.ts
 var InMemoryTokenStore = class {
   #session = null;
-  /** Creates an empty store. Nothing is loaded from anywhere — a client built with it starts logged out. */
+  /** 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. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fleetless/sdk",
-  "version": "3.0.2",
-  "description": "The official TypeScript SDK for Fleetless client apps \u2014 a ROS 2 robot as a REST and realtime API, cameras, jobs, and the app's own user accounts, federated sign-in and MCP consent.",
+  "version": "3.0.3",
+  "description": "The official TypeScript SDK for Fleetless client apps — a ROS 2 robot as a REST and realtime API, cameras, jobs, and the app's own user accounts, federated sign-in and MCP consent.",
   "license": "MIT",
   "author": {
     "name": "Dehne Robotik GmbH",
@@ -9,6 +9,10 @@
     "url": "https://dehne-robotik.de"
   },
   "homepage": "https://docs.fleetless.dev/reference/sdk/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fleetless/sdk"
+  },
   "bugs": {
     "email": "hello@fleetless.dev"
   },
@@ -51,8 +55,7 @@
     "CHANGELOG.md",
     "SECURITY.md",
     "CONTRIBUTING.md",
-    "CODE_OF_CONDUCT.md",
-    "RELEASING.md"
+    "CODE_OF_CONDUCT.md"
   ],
   "engines": {
     "node": ">=20"
@@ -61,6 +64,7 @@
   "scripts": {
     "build": "tsup && node scripts/stamp-dist.mjs",
     "prepare": "tsup && node scripts/stamp-dist.mjs",
+    "prepublishOnly": "node scripts/refuse-manual-publish.mjs",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:pack": "node scripts/verify-published-types.mjs",

package/RELEASING.md

@@ -1,195 +0,0 @@
-# Releasing `@fleetless/sdk`
-
-Maintainer notes: the development setup, the checks, and the release
-procedure. This file is not part of the published package.
-
-**CI runs on GitLab; the repository will mirror to GitHub.** The pipeline
-that verifies and publishes this package lives on an internal GitLab instance,
-and that is the only thing that publishes to npm. The public repository does not
-exist yet; when it does it is a mirror, where issues and pull requests arrive
-and no check runs. A contributor's pull request is verified by a maintainer
-running the same commands locally — see
-[CONTRIBUTING.md](CONTRIBUTING.md), which says so to the contributor as well.
-
-A mirror pushes what it is given, so **everything in a commit becomes public
-the moment it is pushed**, including the commit message and every file the
-branch touched.
-## Development setup
-
-Node 22 via `nvm`, and pnpm through corepack:
-
-```sh
-nvm use 22
-corepack enable
-pnpm install
-```
-
-**That install needs nothing private.** `@fleetless/contracts` — the source
-of truth for every wire type this SDK reads or writes — is a devDependency on
-the public npm package, pinned to an exact version. It used to be a private
-`git+ssh://` URL that only somebody with GitLab group access could install;
-that is over. The published SDK is unaffected either way: `tsup` inlines
-contracts' types into `dist/`, so a consumer of `@fleetless/sdk` never
-resolves it.
-
-Never redefine a shape the SDK sends to or reads from the API. Import it from
-`@fleetless/contracts` instead.
-
-## Checks
-
-| Command | What it does |
-|---|---|
-| `pnpm typecheck` | `tsc --noEmit` over the package. |
-| `pnpm test` | vitest. Most suites drive a fake `fetch` and a fake WebSocket; the three auth suites drive the SDK's own default `fetch` against a real `node:http` server (`test/local-api.ts`). No cloud needed. |
-| `pnpm build` | tsup into `dist/` — ESM, CJS and `.d.ts`. |
-| `pnpm run test:pack` | `npm pack`s the tarball, installs it into a bare project with nothing but `typescript`, and typechecks and runs real usage against it. This is what catches a `dist/index.d.ts` that still imports from `@fleetless/contracts` — a devDependency, so a consumer of the SDK never installs it. |
-
-Two further scripts check the built package against a **running** cloud
-(`./infra/dev.sh` in the umbrella repo). Each one runs against `dist/`, not
-`src/`, so run `pnpm build` first, and each fails by name on a missing
-variable rather than defaulting quietly.
-
-- `pnpm run verify:live` — a `busy` refusal carrying the job that is already
-  running, `command_outcome_unknown` and its documented recovery, a
-  `parameter_invalid` naming the flat key, job-id-addressed cancel, and
-  per-session camera release. Needs `FLEETLESS_API_URL` (or `API`),
-  `APP_IDENTIFIER`, `EMAIL`, `PASSWORD`, `ROBOT_ID`, `ACTION_SLUG`,
-  `SERVICE_SLUG`, `CAMERA_SLUG`, and two optional identities:
-  - `SECOND_EMAIL` — a second, distinct **app user** with the same role,
-    without which the busy check only proves that a second request is refused,
-    not that a different user's is.
-  - `OBSERVER_EMAIL` — a **third** app user, and the one whose password check
-    [6] rotates and restores. Leave it unset and the round trip runs on
-    `EMAIL`, the identity every other check in the file signs in as; the
-    script says so out loud when that happens. `infra/seed-dev.mjs --env`
-    exports all three.
-
-  Since 3.0.0 it also drives the client auth API as check [6]: `listProviders`
-  without a session, `login`, `me` (kind, app, role, address), `logout`, the
-  `changePassword` round trip with its restore, and the reset acknowledgement
-  compared byte for byte across a known and an unknown address. What it does
-  **not** drive is anything needing a mailed token — `register`,
-  `verifyEmail`, `acceptInvitation`, `confirmPasswordReset` — or the federated
-  and MCP-consent flows. Those are `infra/browser/app-auth-check.mjs`'s
-  subject, which reads maildev and drives a real Keycloak.
-- `pnpm run verify:history` — a relative range and its absolute equivalent
-  returning the same samples, aggregation matching arithmetic done here from
-  the raw rows, and the `not_recorded` / `not_aggregatable` refusals. Needs
-  `FLEETLESS_API_URL`, `APP_IDENTIFIER`, `EMAIL`, `PASSWORD`, `ROBOT_ID`,
-  `RECORDED_NUMERIC_SLUG`, `LIVE_ONLY_SLUG`, and optionally
-  `NON_NUMERIC_RECORDED_SLUG`.
-(`verify:hosted-login` is gone. The hosted login flow it drove —
-`beginHostedLogin` / `completeHostedLogin` and the app OAuth client behind
-them — was removed in 3.0.0 along with the script and its `package.json`
-entry.)
-
-`infra/seed-dev.mjs --env` in the umbrella repo exports most of those
-variables for a freshly seeded world.
-
-## Commits
-
-[Conventional Commits](https://www.conventionalcommits.org/). English, for
-code, comments, commit messages and everything else that lands in the
-repository.
-
-## Releasing
-
-Every version on npm is published by this repository's GitLab pipeline from a
-release tag. `npm publish` by hand is retired.
-
-1. Add the version's entry to `CHANGELOG.md` and set `version` in
-   `package.json` to the same number.
-2. Commit (`chore(release): X.Y.Z`), push, and wait for the branch pipeline's
-   `verify` job to go green.
-3. `git tag vX.Y.Z && git push origin vX.Y.Z`. The tag pipeline runs `verify`
-   again and then `publish`.
-4. Check the registry yourself. The `publish` job already asserts the first
-   line; this is the independent look, and the second line is the one that
-   says which dist-tag moved.
-
-   ```sh
-   npm view @fleetless/sdk@X.Y.Z version   # answers X.Y.Z
-   npm view @fleetless/sdk dist-tags       # latest -> X.Y.Z, or next -> X.Y.Z
-   ```
-
-   Name the version. A bare `npm view @fleetless/sdk version` resolves the
-   `latest` dist-tag, so after a pre-release publish it answers the *previous*
-   stable release and reads as a publish that did not happen.
-
-A pre-release tag — `vX.Y.Z-beta.1`, `vX.Y.Z-rc.2` — publishes under the npm
-dist-tag `next` instead of `latest`. Nothing else about it differs, and it is
-exactly why step 4 names the version.
-
-**A red `publish` job does not mean nothing was published.** The job runs
-`npm publish` and then looks the version up on the registry for about two
-minutes; npm answers reads from a replica that lags a publish, so the lookup
-can time out on a version that did land. The job says so itself, and it is
-worth repeating here because a red pipeline invites exactly one reaction —
-press retry — and that reaction cannot work: npm refuses to publish over an
-existing version, so the retry ends in a 403 that reads like a broken
-pipeline rather than like a release that already happened.
-
-> publish may have succeeded; the registry has not served the version yet; do
-> NOT retry this job (npm refuses to republish a version) — check
-> `npm view @fleetless/sdk@$VERSION` by hand
-
-If the hand check answers the version, the release is done: move the dist-tag
-by hand if it is wrong (`npm dist-tag add @fleetless/sdk@X.Y.Z latest`) and
-leave the job red. If it answers nothing after several minutes, the publish
-genuinely did not land and the job can be retried.
-
-**A red `publish` job that ends in `npm error code EOTP` published nothing.**
-npm is asking for a one-time password, which a pipeline cannot supply: the
-token in `NPM_TOKEN` does not bypass two-factor authentication, or the
-package's *Publishing access* setting on npmjs.com disallows tokens. Fix the
-token (a granular access token created with *Bypass two-factor
-authentication*) or the package setting (*Require two-factor authentication
-or an automation token*), then retry the job — nothing reached the registry,
-so a retry is safe here — measured on a pipeline that hit it.
-
-**The pipeline refuses a tag whose version disagrees with `package.json`.**
-`scripts/verify-version-tag.mjs` is the one place that rule lives; `verify`
-runs it first on a tag pipeline, so a mistyped tag fails in seconds and
-`publish` never starts (measured: `verify-version-tag: tag v9.9.9 names
-9.9.9 but package.json says 1.0.0`, publish skipped).
-
-Removing that bad tag takes the API, not git. `v*` is a **protected** tag
-pattern, so a delete over git is refused by the server with nothing but
-`! [remote rejected] v9.9.9 (pre-receive hook declined)`:
-
-```sh
-git tag -d vX.Y.Z                                          # local
-glab api -X DELETE projects/37/repository/tags/vX.Y.Z      # remote
-```
-
-Then fix `package.json` and tag again.
-
-### The one-time setting
-
-It is already in place; it is written down because nothing in this repository
-would tell you it exists if it were removed.
-
-There used to be a second one — `fleetless/fleetless-sdk` on the job-token
-allow-list of `fleetless/fleetless-contracts`, so the pipeline could rewrite
-the private `git+ssh://` contracts URL to HTTPS with `CI_JOB_TOKEN`. Contracts
-is a public npm package now, the rewrite is gone from `.gitlab-ci.yml`, and
-the allow-list entry buys this project nothing. Removing it is safe; leaving
-it is harmless.
-
-- **`NPM_TOKEN` is a protected, masked CI variable on this project**, holding
-  an npm granular automation token with publish rights on `@fleetless/sdk`.
-  Protected means an unprotected ref receives an *empty* value rather than no
-  value, which is why the tag pattern `v*` is a protected tag and why the
-  `publish` job's first action is to refuse an empty `NPM_TOKEN` by name.
-
-  ```sh
-  glab api projects/37/protected_tags     # v*, create access: Maintainers
-  ```
-
-The token reaches npm through an `.npmrc` written in the job's working
-directory holding `//registry.npmjs.org/:_authToken=${NPM_TOKEN}` **literally**
-— npm expands the variable when it reads the file, so the secret itself never
-lands on disk, and `after_script` removes the file either way. It cannot be
-passed as an environment assignment instead: `NPM_CONFIG_//registry…` is not a
-valid shell identifier, so both `bash` and `dash` parse it as a command name.
-