@fleetless/contracts 1.0.5 → 1.0.6

package/dist/apps.js

@@ -6,7 +6,7 @@ import { slug } from './common.js';
  *
  * The rule that shapes all of this: **roles are the only filter**. A robot
  * assigned to an app exposes every one of its services to that app; what a
- * role does not grant simply does not exist for that user. There is no second
+ * role does not grant does not exist for that user. There is no second
  * visibility mechanism, and adding one later would create two places to look
  * when someone cannot see something.
  */
@@ -16,8 +16,8 @@ import { slug } from './common.js';
  *
  * **Globally unique, not per org.** `clientLoginRequest` carries only the
  * identifier, the email and the password — there is no org context to
- * disambiguate with, so a per-org identifier could not be resolved at login
- * at all. A collision is refused with `identifier_taken`.
+ * disambiguate with, so a per-org identifier could not be resolved at login.
+ * A collision is refused with `identifier_taken`.
  */
 export const appIdentifier = slug;
 export const app = z.object({
@@ -31,7 +31,7 @@ export const app = z.object({
         description: 'The display name, shown in the console and available to the developer\'s own pages through the `app.name` mail-template variable. Free text, changed through `PATCH /api/apps/:id`.',
     }),
     identifier: appIdentifier.meta({
-        description: 'The stable handle a client sends at login, lowercase and underscore-separated. **Globally unique, not per organisation** — `clientLoginRequest` carries no org context to disambiguate with, so a collision is refused with `identifier_taken`.',
+        description: 'The stable handle a client sends at login, lowercase and underscore-separated. **Globally unique, not per organisation** — `clientLoginRequest` carries no org context, so a collision is refused with `identifier_taken`.',
     }),
     /** Robots are referenced individually; tags never grant rights. */
     robot_ids: z.array(z.uuid()).meta({
@@ -49,7 +49,7 @@ export const app = z.object({
      * (`createAppUserRequest`, `createAppInvitationRequest`) rather than
      * pre-filling a form.
      *
-     * That is worth saying out loud because it changes what a wrong value costs.
+     * Worth saying: it changes what a wrong value costs.
      * A prefill somebody can see and correct became a default applied on the
      * server, and the obvious next question — should it be required instead? —
      * has a deliberate answer: no, because an invitation resolves the role at
@@ -66,7 +66,7 @@ export const app = z.object({
      * check that, so `PATCH /api/apps/:id` does.
      */
     default_role_id: z.uuid().nullable().meta({
-        description: 'The role an app user gets when they are created or invited without an explicit one. `null` means this app has not chosen a default, the normal state of an app created before its roles were configured — and then a create or invite that omits `role_id` is a `validation_error` rather than a user with no role. An invitation resolves the role when it is issued, so changing this never re-aims an outstanding one. The role must belong to this app, which `PATCH /api/apps/:id` checks and the schema cannot.',
+        description: 'The role an app user gets when created or invited without an explicit one. `null` means this app has not chosen a default, the normal state of an app created before its roles were configured — and then a create or invite that omits `role_id` gets `validation_error`, not a user with no role. An invitation resolves the role when issued, so changing this never re-aims an outstanding one. The role must belong to this app, which `PATCH /api/apps/:id` checks and the schema cannot.',
     }),
     created_at: z.iso.datetime().meta({
         description: 'When the app was created, as an ISO 8601 timestamp. `GET /api/apps` orders by this field.',
@@ -145,7 +145,7 @@ export const updateAppRequest = z.object({
 export const serverKeyToken = z.string().regex(/^flk_[0-9a-f]{32}$/);
 export const serverKey = z.object({
     id: z.uuid().meta({
-        description: 'The key row, and what the rotate and delete routes address. It is not the key: the secret itself is never carried by this shape.',
+        description: 'The key row, and what the rotate and delete routes address. It is not the key: this shape never carries the secret.',
     }),
     app_id: z.uuid().meta({
         description: 'The app whose full rights this key carries. A key is never shared between apps.',
@@ -164,7 +164,7 @@ export const serverKey = z.object({
 /** What `GET /api/apps/:id/server-keys` answers — metadata only; the raw secret exists once, in `createServerKeyResponse`, and never here. */
 export const serverKeyListResponse = z.object({
     server_keys: z.array(serverKey).meta({
-        description: 'The app\'s server keys as metadata, oldest first by `created_at`. The raw secret is not here and never will be: it exists once, in the answer to the request that created or rotated the key.',
+        description: 'The app\'s server keys as metadata, oldest first by `created_at`. The raw secret is not here and never will be: it exists once, in the response that created or rotated the key.',
     }),
 });
 export const createServerKeyResponse = z.object({
@@ -173,9 +173,8 @@ export const createServerKeyResponse = z.object({
 });
 /**
  * Every app starts with `observe` and `operate`; custom roles are allowed
- * too. `builtin` marks the two starting roles — they may be
- * edited like any other, the flag exists so the console can explain where
- * they came from.
+ * too. `builtin` marks the two starting roles — editable like any other,
+ * the flag only tells the console where they came from.
  */
 export const role = z.object({
     id: z.uuid().meta({
@@ -188,7 +187,7 @@ export const role = z.object({
         description: 'The role\'s name, shown wherever a user\'s access is chosen. The two roles every app starts with are named `observe` and `operate`.',
     }),
     builtin: z.boolean().meta({
-        description: '`true` for the two roles every app starts with. Their **rights may be re-scoped** exactly like a custom role\'s, through `PUT /api/apps/:id/roles/:roleId/permissions` — the flag exists so the console can explain where they came from, not to protect them. It does not make them renamable or deletable, because no route renames or deletes any role.',
+        description: '`true` for the two roles every app starts with. Their **rights may be re-scoped** exactly like a custom role\'s, through `PUT /api/apps/:id/roles/:roleId/permissions` — the flag exists so the console can explain where they came from, not to protect them. It does not make them renamable or deletable — no route does that for any role.',
     }),
 });
 /** What `GET /api/apps/:id/roles` answers: the app's roles, builtin and custom alike. */

package/dist/assets.js

@@ -70,7 +70,7 @@ export const asset = z.object({
     id: z.uuid().meta({ description: 'The asset\'s id in the store.' }),
     robot_id: z.uuid().meta({ description: 'The robot this asset belongs to.' }),
     kind: assetKind.meta({
-        description: 'What the file is: the `urdf` itself, a `mesh` it references, a `texture` a mesh or the URDF paints with, or `other`. A renderer decides from this alone, before fetching anything, what it has to pre-fetch.',
+        description: 'What the file is: the `urdf` itself, a `mesh` it references, a `texture` a mesh or the URDF paints with, or `other`. A renderer decides from this alone, before fetching anything, what to pre-fetch.',
     }),
     /**
      * What the robot called it — for a mesh, the `package://` URI the URDF
@@ -105,7 +105,7 @@ export const asset = z.object({
      * rules, one enforced and one only documented, is how a traversal gets in.
      */
     name: z.string().min(1).max(500).meta({
-        description: 'What the robot called it — for a mesh, the `package://` URI the URDF references, verbatim, which is the only string a developer can match against their own workspace. A file the URDF never names (an image a `.dae` loads for itself) is named by joining the mesh\'s own directory with that internal reference.',
+        description: 'What the robot called it — for a mesh, the `package://` URI the URDF references, verbatim, the only string a developer can match against their own workspace. A file the URDF never names (an image a `.dae` loads for itself) is named by joining the mesh\'s own directory with that internal reference.',
     }),
     media_type: z.string().min(1).max(120).meta({
         description: 'The media type of the stored bytes, as the producer reported it.',
@@ -122,7 +122,7 @@ export const asset = z.object({
      * predictable failure of a store that hides it.
      */
     sha256: z.string().regex(/^[a-f0-9]{64}$/).meta({
-        description: 'The content hash, lowercase hex, and the reason two robots sharing a mesh cost one copy. It is exposed because it is the only way a client can tell "this is the same mesh I already have" across robots.',
+        description: 'The content hash, lowercase hex. Exposed because it is the only way a client can tell "this is the same mesh I already have" across robots — the reason two robots sharing a mesh cost one copy.',
     }),
     created_at: z.iso.datetime().meta({
         description: 'When the asset was first stored, as an ISO 8601 timestamp.',
@@ -169,13 +169,13 @@ export const urdfCompleteness = z.object({
      */
     missing: z.array(z.object({
         uri: z.string().min(1).max(500).meta({
-            description: 'The reference, verbatim, that no stored asset answers — a `package://` URI the workspace does not hold, or an absolute or bare relative path nothing will ever fetch. A developer whose URDF names one of the latter is entitled to be told so.',
+            description: 'The reference, verbatim, that no stored asset answers — a `package://` URI the workspace does not hold, or an absolute or bare relative path nothing will ever fetch.',
         }),
         element: z.enum(['mesh', 'texture']).meta({
             description: 'Which kind of reference it was: geometry the URDF names as a `mesh`, or a `texture` a surface paints with. Without it a client reports a missing texture as a missing mesh, contradicting `mesh_count` beside it.',
         }),
     })).meta({
-        description: 'The references nothing in the store answers, each with the element that asked for it. A bare count is a dead end that sends a developer hunting through a workspace by hand; the references are what they can act on, so the references travel.',
+        description: 'The references nothing in the store answers, each with the element that asked for it. A bare count would send a developer hunting through the workspace by hand; the references are what they can act on.',
     }),
 });
 /**
@@ -193,7 +193,7 @@ export const urdfCompleteness = z.object({
  */
 export const assetSyncRequest = z.object({
     source: z.enum(['bridge']).meta({
-        description: 'Where the bytes come from. `bridge` is the only value today: the connected bridge reads them from the robot\'s own workspace. It is validated rather than ignored, so a caller naming a source that does not exist yet learns that instead of silently getting a bridge sync.',
+        description: 'Where the bytes come from. `bridge` is the only value today: the connected bridge reads them from the robot\'s own workspace. Validated rather than ignored, so a caller naming an unknown source is told so instead of silently getting a bridge sync.',
     }),
 }).strict();
 export const assetSyncResponse = z.object({
@@ -253,7 +253,7 @@ export const assetTooLargeDetails = z.object({
         description: 'The upload ceiling, in bytes.',
     }),
     size_bytes: z.number().int().positive().meta({
-        description: 'How large the refused file actually is, in bytes. With `limit_bytes` beside it a developer can tell whether to shrink the mesh or raise the limit; "too large" alone answers neither.',
+        description: 'How large the refused file is, in bytes. With `limit_bytes` beside it a developer can tell whether to shrink the mesh or raise the limit; "too large" alone answers neither.',
     }),
 });
 /**
@@ -312,9 +312,8 @@ export const assetFailure = z.object({
         description: 'The two numbers behind a `too_large` failure, and absent for every other kind — a forced `null` on every `unresolvable` entry buys nothing. The pairing is enforced, not merely described.',
     }),
 }).superRefine((f, ctx) => {
-    // **Enforced, not merely described.** A rule that lives only in a comment is
-    // a request, and a field whose meaning sits beside it rather than in it gets
-    // filled with something else.
+    // Enforced here, not merely described above — a rule that lives only in a
+    // comment gets filled with something else.
     if (f.kind === 'too_large' && f.details == null) {
         ctx.addIssue({ code: 'custom', path: ['details'], message: '`too_large` without limit_bytes/size_bytes says nothing a developer can act on' });
     }
@@ -377,8 +376,6 @@ export const assetListResponse = z.object({
         description: 'Every asset stored for this robot: the URDF, the meshes it references, and the textures those paint with.',
     }),
     /**
-     * The sync running right now, or `null`.
-     *
      * **This field exists for the reload case.** A client that holds the
      * `sync_id` only in memory loses its progress display on a refresh, and the
      * state is still there server-side under `GET .../assets/sync/<id>` —
@@ -409,7 +406,7 @@ export const assetListResponse = z.object({
      * crash, and no amount of polling shortens it.
      */
     urdf_available: z.boolean().nullable().meta({
-        description: 'What the connected bridge says it *could* transfer, which is deliberately separate from what has been transferred. `null` when no bridge is connected — distinct from `false`, because "no robot is online to ask" and "the robot has no URDF" send a developer to two different places. After a publisher is killed rather than shut down this can read `true` for some seconds, on the underlying DDS liveliness timeout rather than on any check made here.',
+        description: 'What the connected bridge says it *could* transfer — deliberately separate from what has been transferred. `null` when no bridge is connected, distinct from `false`: "no robot is online to ask" and "the robot has no URDF" send a developer to different places. After a publisher is killed rather than shut down this can read `true` for some seconds, on the underlying DDS liveliness timeout rather than on any check made here.',
     }),
 });
 /**

package/dist/audit.d.ts

@@ -14,21 +14,19 @@ import { z } from 'zod';
  * log — an email, a key name, a robot name — so the console never has to
  * resolve four different id kinds to render a row.
  *
- * **`end_user` stays, and it stays for the rows already written.** The
- * split into two identity spaces replaced the org's one user pool with
- * Fleetless users and per-app app users; every new row an app user writes
- * carries `app_user`. But an audit log is the one thing this platform must
- * never rewrite, and there are stored rows whose `kind` is `end_user`. Dropping
- * the member would leave those rows failing their own schema — a log that
- * cannot be read back is worse than one carrying a retired word.
+ * **`end_user` stays, for the rows already written.** The identity split
+ * replaced the org's one user pool with Fleetless users and per-app app
+ * users; new rows from an app user carry `app_user`. But an audit log must
+ * never be rewritten, and stored rows still have `kind: end_user` — dropping
+ * the member would fail their own schema. A log that can't be read back is
+ * worse than one carrying a retired word.
  *
- * So this enum is deliberately **wider than what any producer emits**: nothing
- * writes `end_user` any more, and nothing may start again. That is said here
- * rather than left to be inferred from a search somebody runs in a year.
+ * So the enum is deliberately **wider than what any producer emits**:
+ * nothing writes `end_user` any more, and nothing should start again — said
+ * here rather than left for a future search to infer.
  *
  * `developer` is a Fleetless user. It kept its name through both redesigns
- * because it was always right about what it named: the person who configures
- * robots.
+ * because it was always right: the person who configures robots.
  */
 export declare const auditActor: z.ZodObject<{
     kind: z.ZodEnum<{

package/dist/audit.js

@@ -15,21 +15,19 @@ import { wireSeqCursor, wireTimestampMs } from './common.js';
  * log — an email, a key name, a robot name — so the console never has to
  * resolve four different id kinds to render a row.
  *
- * **`end_user` stays, and it stays for the rows already written.** The
- * split into two identity spaces replaced the org's one user pool with
- * Fleetless users and per-app app users; every new row an app user writes
- * carries `app_user`. But an audit log is the one thing this platform must
- * never rewrite, and there are stored rows whose `kind` is `end_user`. Dropping
- * the member would leave those rows failing their own schema — a log that
- * cannot be read back is worse than one carrying a retired word.
+ * **`end_user` stays, for the rows already written.** The identity split
+ * replaced the org's one user pool with Fleetless users and per-app app
+ * users; new rows from an app user carry `app_user`. But an audit log must
+ * never be rewritten, and stored rows still have `kind: end_user` — dropping
+ * the member would fail their own schema. A log that can't be read back is
+ * worse than one carrying a retired word.
  *
- * So this enum is deliberately **wider than what any producer emits**: nothing
- * writes `end_user` any more, and nothing may start again. That is said here
- * rather than left to be inferred from a search somebody runs in a year.
+ * So the enum is deliberately **wider than what any producer emits**:
+ * nothing writes `end_user` any more, and nothing should start again — said
+ * here rather than left for a future search to infer.
  *
  * `developer` is a Fleetless user. It kept its name through both redesigns
- * because it was always right about what it named: the person who configures
- * robots.
+ * because it was always right: the person who configures robots.
  */
 export const auditActor = z.object({
     kind: z.enum(['developer', 'end_user', 'app_user', 'server_key', 'bridge']),
@@ -130,12 +128,11 @@ export const auditQuery = z.object({
      * Everything under a dotted prefix, e.g. `server_key.` for all three
      * server-key actions.
      *
-     * **A separate parameter, not a widening of `action`.** The sentence on
-     * `action` above — a filter that matches more than it says is not one —
-     * still stands; this is a different question with a name that says which
-     * one it is. Setting both is refused rather than resolved, because a query
+     * **A separate parameter, not a widening of `action`.** The rule on
+     * `action` above still stands; this is a different question with a name
+     * that says which one it is. Setting both is refused, not resolved —
      * naming an exact action *and* a prefix is a caller mistake, not a
-     * combination anyone should have to guess the meaning of.
+     * combination to guess the meaning of.
      *
      * **The published artifact cannot express that refusal**: a cross-field
      * `.refine()` has no JSON Schema rendering, so `audit-query.schema.json`

package/dist/client-auth.d.ts

@@ -48,13 +48,12 @@ export type ClientRefreshRequest = z.infer<typeof clientRefreshRequest>;
  *
  * **The route answers `204` and has no response shape.** It used to answer a
  * `clientLogoutResponse` reporting what was left of the session at the identity
- * provider — RP-initiated logout, an `end_session_endpoint` to redirect to,
- * four ways of saying "we cannot end that session". That whole apparatus
- * belonged to the hosted login flow, where Fleetless owned the browser. It does
- * not own it any more: the developer's app does, and an app that wants to end
- * a provider session redirects there itself, knowing its own provider, which
- * Fleetless never did better than it. Listed as a breaking change rather than
- * quietly kept as a field nobody fills.
+ * provider — RP-initiated logout, an `end_session_endpoint`, four ways of
+ * saying "we cannot end that session". That belonged to the hosted login flow,
+ * where Fleetless owned the browser; it doesn't any more. The developer's app
+ * does, and knows its own provider better than Fleetless ever did — ending a
+ * provider session is its own redirect to make. Listed as a breaking change,
+ * not quietly kept as a field nobody fills.
  */
 export declare const clientLogoutRequest: z.ZodObject<{
     refresh_token: z.ZodString;
@@ -110,8 +109,8 @@ export type ClientResendVerificationRequest = z.infer<typeof clientResendVerific
  * to be. An **app identifier** no app carries is the one refusal, `404
  * not_found`, because an identifier is public and an address is not.
  *
- * Moved here from `identity.ts`, where it sat because the client surface had no
- * file of its own for it. It is an app-user shape and belongs with them.
+ * Moved here from `identity.ts`, which predates a client-surface file — it's
+ * an app-user shape and belongs with them.
  */
 export declare const clientPasswordResetRequest: z.ZodObject<{
     app_identifier: z.ZodString;

package/dist/client-auth.js

@@ -37,7 +37,7 @@ import { password } from './identity.js';
 /* ------------------------------------------------------ password login -- */
 export const clientLoginRequest = z.object({
     app_identifier: appIdentifier.meta({
-        description: 'The app being logged in to, as its globally unique identifier — the lowercase, underscore-separated string the developer chose when the app was created. There is no organisation context at login, so this is what decides which app the credentials are checked for.',
+        description: 'The app being logged in to: its globally unique, lowercase, underscore-separated identifier, chosen by the developer at creation. There is no organisation context at login, so this is what decides which app the credentials are checked for.',
     }),
     email: z.email().meta({
         description: 'The app user\'s address. Addresses are unique **per app**, not across Fleetless: the same address may be an unrelated account in another app of the same organisation, so this pair is what identifies a person here.',
@@ -58,17 +58,16 @@ export const clientRefreshRequest = z.object({
  *
  * **The route answers `204` and has no response shape.** It used to answer a
  * `clientLogoutResponse` reporting what was left of the session at the identity
- * provider — RP-initiated logout, an `end_session_endpoint` to redirect to,
- * four ways of saying "we cannot end that session". That whole apparatus
- * belonged to the hosted login flow, where Fleetless owned the browser. It does
- * not own it any more: the developer's app does, and an app that wants to end
- * a provider session redirects there itself, knowing its own provider, which
- * Fleetless never did better than it. Listed as a breaking change rather than
- * quietly kept as a field nobody fills.
+ * provider — RP-initiated logout, an `end_session_endpoint`, four ways of
+ * saying "we cannot end that session". That belonged to the hosted login flow,
+ * where Fleetless owned the browser; it doesn't any more. The developer's app
+ * does, and knows its own provider better than Fleetless ever did — ending a
+ * provider session is its own redirect to make. Listed as a breaking change,
+ * not quietly kept as a field nobody fills.
  */
 export const clientLogoutRequest = z.object({
     refresh_token: z.string().min(1).meta({
-        description: 'Any refresh token of the session to end. The whole token family is revoked server-side, so a token stolen before this call stops working too — clearing a client-side store is a gesture, not a revocation. The answer is `204`: a token the server does not recognise gets it too, since the end state a caller asked for is the end state they get.',
+        description: 'Any refresh token of the session to end. The whole token family is revoked server-side, so a token stolen before this call stops working too — clearing a client-side store is a gesture, not a revocation. The answer is `204`: a token the server does not recognise gets it too, since that is the end state being asked for.',
     }),
 });
 /* ---------------------------------------------- registration and mails -- */
@@ -137,8 +136,8 @@ export const clientResendVerificationRequest = z
  * to be. An **app identifier** no app carries is the one refusal, `404
  * not_found`, because an identifier is public and an address is not.
  *
- * Moved here from `identity.ts`, where it sat because the client surface had no
- * file of its own for it. It is an app-user shape and belongs with them.
+ * Moved here from `identity.ts`, which predates a client-surface file — it's
+ * an app-user shape and belongs with them.
  */
 export const clientPasswordResetRequest = z
     .object({
@@ -373,7 +372,7 @@ export const clientMcpInteraction = z.object({
     app_id: z.uuid().meta({ description: 'The app this authorization is for. The approving token\'s `app_id` must match it — an interaction of one app cannot be approved with a session from another.' }),
     client_name: z.string().nullable().meta({ description: 'What the MCP client calls itself, or `null` if it named nothing. **Unverified** — see `client_name_verified`.' }),
     client_name_verified: z.literal(false).meta({
-        description: 'Always `false`. The client registered itself without authentication and chose this name about itself, so it must be rendered as a claim and never as an identity. There is no verified case, which is why this is a literal and not a boolean: a `true` branch would be dead code that looked like a safeguard.',
+        description: 'Always `false`. The client registered itself without authentication and named itself, so it must be rendered as a claim and never as an identity. There is no verified case, which is why this is a literal and not a boolean: a `true` branch would be dead code that looked like a safeguard.',
     }),
     scopes: z.array(z.string()).meta({ description: 'The scopes the client asked for, to show the person before they approve.' }),
     already_granted: z.boolean().meta({ description: 'Whether this user has already approved this client. It is a record of what they answered last time, and **this route makes no second use of it**: an app that skips its own consent screen when this is `true` is the only thing deciding that, and approve succeeds identically for a user who holds no grant at all. The standing grant is read elsewhere, on every request to the app\'s MCP endpoint. Withdrawing it is `DELETE /api/client/mcp/grants/:clientId` for the person themselves and `DELETE /api/apps/:id/users/:userId/mcp-grants/:clientId` for the developer. A withdrawal makes this `false` again at the next authorization **and stops the client at its very next MCP call**, unexpired access token and all — up to fifteen minutes of it — because the endpoint keys that check on the `client_id` the token carries.' }),
@@ -417,10 +416,10 @@ export const mcpConsentGrant = z.object({
         description: 'The MCP client this consent is for, as its dynamic registration was issued. It is the value the withdrawal routes take in their path, and it is the only stable handle on a client — the name beside it is not one.',
     }),
     client_name: z.string().nullable().meta({
-        description: 'What the client calls itself, or `null` when its registration is gone and there is no longer anything to have named. **Unverified** — see `client_name_verified`.',
+        description: 'What the client calls itself, or `null` once its registration is gone. **Unverified** — see `client_name_verified`.',
     }),
     client_name_verified: z.literal(false).meta({
-        description: 'Always `false`. The client registered itself without authentication and chose this name about itself, so it must be rendered as a claim and never as an identity. There is no verified case, which is why this is a literal and not a boolean: a `true` branch would be dead code that looked like a safeguard.',
+        description: 'Always `false`. The client registered itself without authentication and named itself, so it must be rendered as a claim and never as an identity. There is no verified case, which is why this is a literal and not a boolean: a `true` branch would be dead code that looked like a safeguard.',
     }),
     granted_at: z.iso.datetime().meta({
         description: 'When the consent was last given. A withdrawal followed by a fresh approval moves it, because the second approval is the agreement that stands — it is not a record of the first time anybody ever said yes.',
@@ -463,7 +462,7 @@ export const mcpConsentGrantListResponse = z.object({
  */
 export const clientIdentity = z.object({
     kind: z.enum(['developer', 'app_user', 'server_key']).meta({
-        description: 'Which of the three kinds of caller this is: a `developer` working through the console, an `app_user` holding a token from a client login, or a `server_key` used by server-side code. Stated outright rather than left to be inferred from which id happens to be set.',
+        description: 'Which of the three kinds of caller this is: a `developer` working through the console, an `app_user` holding a token from a client login, or a `server_key` used by server-side code. Stated outright, not inferred from which id is set.',
     }),
     developer_id: z.uuid().nullable().meta({
         description: 'The Fleetless user behind this session, or `null` when `kind` is not `developer`.',

package/dist/config-issues.d.ts

@@ -92,9 +92,9 @@ export declare function schemaIssues(value: unknown, issues: readonly SchemaIssu
  * `configDraftResponse`, not one issue: a client's `safeParse` drops the
  * response and hands the editor nothing, for two characters typed.
  *
- * The quoted spelling is the segment's JSON string literal, and that is the
- * whole of the reason for choosing it: JSON's string syntax is a subset of
- * YAML's double-quoted scalar syntax, so `""`, `" "` and `"\t"` are each a
+ * The quoted spelling is the segment's JSON string literal — the whole reason
+ * for choosing it: JSON's string syntax is a subset of YAML's double-quoted
+ * scalar syntax, so `""`, `" "` and `"\t"` are each a
  * valid YAML spelling of exactly the key being complained about. The path is
  * therefore text the developer can search their own file for — which is the
  * bar this has to clear. It is also the same move `DOCUMENT_ROOT_PATH` makes

package/dist/config-issues.js

@@ -111,9 +111,9 @@ function slugOf(path) {
  * `configDraftResponse`, not one issue: a client's `safeParse` drops the
  * response and hands the editor nothing, for two characters typed.
  *
- * The quoted spelling is the segment's JSON string literal, and that is the
- * whole of the reason for choosing it: JSON's string syntax is a subset of
- * YAML's double-quoted scalar syntax, so `""`, `" "` and `"\t"` are each a
+ * The quoted spelling is the segment's JSON string literal — the whole reason
+ * for choosing it: JSON's string syntax is a subset of YAML's double-quoted
+ * scalar syntax, so `""`, `" "` and `"\t"` are each a
  * valid YAML spelling of exactly the key being complained about. The path is
  * therefore text the developer can search their own file for — which is the
  * bar this has to clear. It is also the same move `DOCUMENT_ROOT_PATH` makes

package/dist/config.d.ts

@@ -20,8 +20,8 @@ import { z } from 'zod';
  * field as **required** in the generated JSON Schema, because after parsing
  * it is always present. That is recorded in `scripts/export-schemas.ts`, whose
  * remedy (`io: 'input'`, applied per schema) is a judgement call across dozens
- * of schemas and every consumer that vendors them. So this field simply does
- * not add another instance: optional is optional in both modes, and *absent* is
+ * of schemas and every consumer that vendors them. So this field does not add
+ * another instance: optional is optional in both modes, and *absent* is
  * the single spelling of "not described". `.min(1)` keeps the empty string from
  * becoming a second.
  */
@@ -144,10 +144,9 @@ export declare const parameterMap: z.ZodRecord<z.ZodString, z.ZodObject<{
  *
  * **This constant is the only list.** The cloud builds its set from it and
  * emits `reserved_slug`; the rename path reads it for the target; an editor
- * reads it for slug suggestion and repairs. Nothing copies the members. Note
- * that it is NOT the enumeration of built-in datapoints — those are kept
- * separately, and must be, because a reserved name exists that nothing
- * publishes.
+ * reads it for slug suggestion and repairs. Nothing copies the members. It is
+ * NOT the enumeration of built-in datapoints — those are kept separately,
+ * and must be, because a reserved name exists that nothing publishes.
  *
  * **What it does not do: `robotConfigDoc` does not enforce it.** Reservation is
  * a semantic check that belongs with the ones that need the robot's context,

package/dist/config.js

@@ -379,8 +379,8 @@ const underSlug = (slugKey, snippet) => ({ ...snippet, body: { [slugKey]: snippe
  * field as **required** in the generated JSON Schema, because after parsing
  * it is always present. That is recorded in `scripts/export-schemas.ts`, whose
  * remedy (`io: 'input'`, applied per schema) is a judgement call across dozens
- * of schemas and every consumer that vendors them. So this field simply does
- * not add another instance: optional is optional in both modes, and *absent* is
+ * of schemas and every consumer that vendors them. So this field does not add
+ * another instance: optional is optional in both modes, and *absent* is
  * the single spelling of "not described". `.min(1)` keeps the empty string from
  * becoming a second.
  */
@@ -582,7 +582,7 @@ export const parameterSpec = strictObject({
      * Without this, a default is the one way past bounds that are otherwise
      * the enforcement point. `min_value`/`max_value` are the speed limit that
      * actually holds, enforced in the cloud before anything reaches the robot.
-     * But a caller who simply omits the parameter gets the
+     * But a caller who omits the parameter gets the
      * default, and the bridge fills it at the template walk without
      * re-checking bounds, deliberately: a second enforcement point there
      * would be the weaker of two policies. So `{min_value: -1, max_value: 1,
@@ -658,10 +658,9 @@ export const parameterMap = slugKeyed(parameterSpec)
  *
  * **This constant is the only list.** The cloud builds its set from it and
  * emits `reserved_slug`; the rename path reads it for the target; an editor
- * reads it for slug suggestion and repairs. Nothing copies the members. Note
- * that it is NOT the enumeration of built-in datapoints — those are kept
- * separately, and must be, because a reserved name exists that nothing
- * publishes.
+ * reads it for slug suggestion and repairs. Nothing copies the members. It is
+ * NOT the enumeration of built-in datapoints — those are kept separately,
+ * and must be, because a reserved name exists that nothing publishes.
  *
  * **What it does not do: `robotConfigDoc` does not enforce it.** Reservation is
  * a semantic check that belongs with the ones that need the robot's context,
@@ -993,7 +992,7 @@ export const datapointConfig = strictObject({
         examples: [2, 0.5],
     }).optional(),
     description: serviceDescription.meta({
-        description: 'Prose about what this value is, for whoever meets it in the console later. It changes nothing the robot does, so a publish that touches only it pushes no configuration at all — but it is carried verbatim into `robot_describe`, where a model that has never seen this robot reads it. The datapoint is offered whenever the role grants it; without one it is offered with `description: null` and the model has less to go on, as for actions, services, publishers and cameras. Omission is the only way to say nothing; an empty string is refused, here and on all five.',
+        description: 'Prose about what this value is, for whoever meets it in the console. It changes nothing the robot does, so a publish that touches only it pushes no configuration at all — but it is carried verbatim into `robot_describe`, where a model that has never seen this robot reads it. The datapoint is offered whenever the role grants it; without one it is offered with `description: null` and the model has less to go on, as for actions, services, publishers and cameras. Omission is the only way to say nothing; an empty string is refused, here and on all five.',
         /**
          * The sentence both datapoint snippets already place here, verbatim. Its
          * four siblings — an action's, a service's, a publisher's, a camera's —

package/dist/errors.d.ts

@@ -19,10 +19,10 @@ export type ApiError = z.infer<typeof apiError>;
  * console renders a third, and each is right in its own tests.
  *
  * `field` is the **flat key exactly as the caller sent it** — the same string
- * as the `parameterSpec.name` it violated. That is the entire justification
- * for the flat parameter form: a refusal has to name something the caller can
- * find in what they typed, and a console can attach the error to that one
- * input rather than to the form.
+ * as the `parameterSpec.name` it violated. That is why the parameter form
+ * stays flat: a refusal has to name something the caller can find in what
+ * they typed, and a console can attach the error to that one input rather
+ * than to the form.
  */
 export declare const parameterViolation: z.ZodObject<{
     field: z.ZodString;

package/dist/errors.js

@@ -18,10 +18,10 @@ export const apiError = z.object({
  * console renders a third, and each is right in its own tests.
  *
  * `field` is the **flat key exactly as the caller sent it** — the same string
- * as the `parameterSpec.name` it violated. That is the entire justification
- * for the flat parameter form: a refusal has to name something the caller can
- * find in what they typed, and a console can attach the error to that one
- * input rather than to the form.
+ * as the `parameterSpec.name` it violated. That is why the parameter form
+ * stays flat: a refusal has to name something the caller can find in what
+ * they typed, and a console can attach the error to that one input rather
+ * than to the form.
  */
 export const parameterViolation = z.object({
     field: z.string().min(1),
@@ -81,11 +81,10 @@ export const ERROR_CODES = [
     'invalid_credentials',
     'token_expired',
     'token_revoked',
-    /* `invite_expired` and `invite_used` were removed on 2026-09-05, by the same
-     * reasoning that removed `not_a_member` and with the same evidence: a `grep`
-     * across contracts, cloud, sdk, console and bridge found their own entries
-     * here and one test asserting those entries existed. Nothing has ever emitted
-     * either.
+    /* `invite_expired` and `invite_used` were removed on 2026-09-05 — same
+     * reasoning and evidence as `not_a_member`: a `grep` across contracts, cloud,
+     * sdk, console and bridge found only their own entries here and one test
+     * asserting those entries existed. Nothing has ever emitted either.
      *
      * They were written for `POST /api/client/invitations/accept`, to tell an
      * expired invitation from an already-accepted one. That route answers `410

package/dist/identity.d.ts

@@ -19,11 +19,10 @@ import { z } from 'zod';
  *
  * **What that deleted, with no successor**: groups and the Org Admins
  * group, app assignments, impersonation, the per-user MCP override and the
- * org-level federation policy. The 2026-08-29 model had put developers and end
- * users into one pool per org and connected them with all of the above; in use
- * it turned out to model the wrong thing — the two populations have different
- * lifecycles, and every mechanism joining them was cost without a product
- * reason.
+ * org-level federation policy. The 2026-08-29 model pooled developers and end
+ * users per org and joined them with all of the above. In use, wrong model:
+ * the two populations have different lifecycles, and every joining mechanism
+ * was cost without a product reason.
  *
  * What did **not** change: the password rules, the session and token shapes,
  * and the enumeration-oracle reasoning on password reset. None of those was

package/dist/identity.js

@@ -19,11 +19,10 @@ import { z } from 'zod';
  *
  * **What that deleted, with no successor**: groups and the Org Admins
  * group, app assignments, impersonation, the per-user MCP override and the
- * org-level federation policy. The 2026-08-29 model had put developers and end
- * users into one pool per org and connected them with all of the above; in use
- * it turned out to model the wrong thing — the two populations have different
- * lifecycles, and every mechanism joining them was cost without a product
- * reason.
+ * org-level federation policy. The 2026-08-29 model pooled developers and end
+ * users per org and joined them with all of the above. In use, wrong model:
+ * the two populations have different lifecycles, and every joining mechanism
+ * was cost without a product reason.
  *
  * What did **not** change: the password rules, the session and token shapes,
  * and the enumeration-oracle reasoning on password reset. None of those was
@@ -78,7 +77,7 @@ export const org = z.object({
 /** What `PATCH /api/org` answers: the org as it now stands. */
 export const patchOrgResponse = z.object({
     org: org.meta({
-        description: 'The organisation as it now stands, after the patch was applied. The whole resource comes back, not only the fields that changed.',
+        description: 'The organisation as it now stands, after the patch. The whole resource comes back, not only the changed fields.',
     }),
 });
 /**
@@ -104,7 +103,7 @@ export const fleetlessUser = z.object({
         description: 'The Fleetless user in the API, assigned by the cloud and stable for the life of the account.',
     }),
     org_id: z.uuid().meta({
-        description: 'The organisation this person belongs to. Every developer route is already scoped to the caller\'s org, so this confirms what a client is looking at rather than being a filter it applies.',
+        description: 'The organisation this person belongs to. Every developer route is already scoped to the caller\'s org, so this confirms what a client is looking at, not a filter it applies.',
     }),
     email: z.email().meta({
         description: 'The address the account is identified by, **globally unique** across every organisation. Immutable after creation: it is what every invitation, reset link and audit line names.',
@@ -113,7 +112,7 @@ export const fleetlessUser = z.object({
         description: 'Optional human name, shown by the console instead of the address where present. Self-service through `PATCH /api/auth/me`; never used for authentication. `null` when the person never supplied one.',
     }),
     tier: orgAdminTier.meta({
-        description: 'The console powers this person holds. **Required** — every Fleetless user is a member of the team and has a tier; the optional version of this field existed only while the org also held people with no console powers to grade, and that pool is gone.',
+        description: 'The console powers this person holds. **Required** — every Fleetless user has a tier; it was optional only while the org also held people with no console powers to grade, and that pool is gone.',
     }),
     created_at: z.iso.datetime().meta({
         description: 'When the account was created, as an ISO 8601 timestamp.',

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export type { ParameterType, ParameterSpec, ActionConfig, ServiceConfig, Publish
 /**
  * The one account of what is wrong with a configuration document, shared by
  * every layer that reports on one. See `config-issues.ts`'s header for why a
- * second copy of this vocabulary is a defect rather than a convenience.
+ * second copy of this vocabulary is a defect, not a convenience.
  */
 export { DOCUMENT_ROOT_PATH, EXPOSURE_SECTIONS, schemaIssues, formatPath, splitFormatPath, configSchemaHash, } from './config-issues.js';
 export type { SchemaIssue, ExposureSection } from './config-issues.js';

package/dist/index.js

@@ -16,7 +16,7 @@ cameraSource, cameraCredentials, } from './config.js';
 /**
  * The one account of what is wrong with a configuration document, shared by
  * every layer that reports on one. See `config-issues.ts`'s header for why a
- * second copy of this vocabulary is a defect rather than a convenience.
+ * second copy of this vocabulary is a defect, not a convenience.
  */
 export { DOCUMENT_ROOT_PATH, EXPOSURE_SECTIONS, schemaIssues, formatPath, splitFormatPath, configSchemaHash, } from './config-issues.js';
 export { rosGraphEntry, rosGraph, typeField, typeDefinition, parameterFieldsOf } from './introspection.js';