@fleetless/contracts 1.0.0 → 1.0.3

package/CHANGELOG.md

@@ -5,15 +5,110 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
 project uses [semantic versioning](https://semver.org/spec/v2.0.0.html) over
 the wire shapes.
 
+## [1.0.3] — 2026-09-07
+
+The second half of 1.0.2's sweep. **No wire shape changes**: every file under
+`artifacts/schema-outgoing/` is byte-identical to 1.0.2, as are 226 of the 227
+files under `artifacts/schema/` — the one that moves carries a reworded
+`scopes` description. What changes is who the prose is addressed to.
+
+### Fixed
+
+- **Descriptions and comments that spoke inward.** 1.0.2 removed the markers — a
+  ticket id, a robot's hostname, a German paragraph — and left the stance. Text
+  that named an internal decision label (`D2`, `D7`), pointed at a file in
+  another repository (`cloud/src/routes/config.ts`), said "this project" or
+  "this repository", cited a document a reader does not have, or explained how
+  somebody discovered the behaviour rather than what the behaviour is. All of it
+  is rewritten for a reader who has only this package: 13 descriptions and every
+  affected doc comment across all 20 modules.
+- **The guard now covers that half too.** `test/published-prose.test.ts` gained
+  five patterns — an internal decision label, a path into another repository, a
+  reference to this project, a reference to a document the reader does not have,
+  and how-it-was-found prose — each with fixtures asserting both what it must
+  catch and what it must leave alone, because "caught by the body schema" and
+  "the row is found by token hash" are ordinary English and a detector that
+  reddens on them is one somebody deletes.
+- **The German detector no longer trips on a URL.** A path segment is not prose,
+  and `von`, `bei`, `nach` and `wie` are all ordinary path segments. URLs are
+  removed before that scan; a fixture asserts a URL alone stays green and that
+  one beside German prose still goes red.
+
+## [1.0.2] — 2026-09-07
+
+A documentation and packaging release. (1.0.1 was tagged and never published:
+its `verify` job went red on a licence-header guard that swept the pipeline's
+own scratch file. The tag pattern is protected and cannot be moved, so the
+release carries the next number. Nothing was ever served as 1.0.1.)
+
+**No wire shape changes**, and nothing generated from a schema changes either — `artifacts/schema/` and
+`artifacts/schema-outgoing/` are byte-identical to 1.0.0. What changes is what
+the package says about itself.
+
+### Fixed
+
+- **The internal engineering prose is gone from the published bytes.** Doc
+  comments in the source were written for the people who built this and `tsc`
+  carries them into `dist/*.js` and `dist/*.d.ts`, so 1.0.0 shipped German
+  paragraphs, a reference robot's workspace paths, measured mesh sizes and
+  internal tracker ids to anyone who hovered a symbol in an editor. Every
+  comment that ships has been rewritten for a reader who has only this package.
+  A test now greps the built `dist/` and `artifacts/` for those markers and
+  fails on a hit.
+- **The `artifacts/` table in the README described `schema-outgoing/`
+  backwards.** It said those files were the messages the cloud sends to a
+  bridge. They are the opposite: the frames a bridge **sends**, rendered in
+  output mode, and validating incoming cloud frames against them fails on every
+  real frame. The table now says what each directory holds and why there are
+  two.
+- **The README claimed the robot-side bridge validates incoming frames against
+  `artifacts/schema/` at runtime with Python's `jsonschema`.** It does not. The
+  bridge does not depend on this package at all — it vendors its own copies —
+  and only its test harness imports `jsonschema`. There is no runtime validation
+  of incoming frames against these schemas.
+- **The security reporting address was in nothing the package served.**
+  `SECURITY.md` was not in `files`, and the README linked to it relatively.
+  `SECURITY.md`, `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` now ship, and the
+  address is written out in the README under its own heading rather than behind
+  a link.
+- **Twenty-two of the forty published files carried no SPDX header.**
+  Declaration emit drops a leading `//` comment and two `.js` files had theirs
+  elided, so more than half of what a licence scanner sees was unmarked. Every
+  file in `dist/` now carries `// SPDX-License-Identifier: Apache-2.0`, and the
+  pack check asserts it over the tarball's own bytes.
+- **The CHANGELOG's account of 1.0.0 was wrong about which server it matched**
+  — see the corrected note below.
+
+### Changed
+
+- `zod` moves from `^4.0.0` to `^4.4.3`. It stays a range on purpose, and the
+  README now says why: zod is a peer in everything but name, and an exact pin
+  forces a second copy on any consumer whose lockfile resolves a different
+  patch. `^4.4.3` is the floor these schemas are built, tested and exported
+  against, rather than a version nobody has run.
+- `bugs` gains an email address, so a report has somewhere to go from the npm
+  page.
+
 ## [1.0.0] — 2026-09-07
 
-The first published version. Nothing about the shapes changes with it: they are
-exactly the shapes the Fleetless cloud serves at release 0.17.0, and they have
+The first published version. Nothing about the shapes changes with it: they have
 been the contract between the cloud, the console, the SDK and the robot-side
 bridge for as long as those have existed. What changes is who can read them —
 until now this package was resolvable only from a private git URL, so nobody
 outside the project could build a Fleetless client from source.
 
+**Corrected in 1.0.2:** this entry originally said these were "exactly the
+shapes the Fleetless cloud serves at release 0.17.0". They are not. This package
+tracks the cloud's `main` branch, not its releases, and 1.0.0 was cut from a
+commit that already carried the MCP consent-withdrawal change — so the route
+notes and the OpenAPI description for
+`DELETE /api/client/mcp/grants/:clientId` and its developer twin state that
+withdrawal ends a session at the client's very next call, which the deployed
+0.17.0 does not do. On 0.17.0 a withdrawn client keeps working for the remaining
+lifetime of its access token, up to fifteen minutes. **A shape or a note here may
+precede the release that serves it**; check the platform's own release notes
+before treating one as an operational control.
+
 Consumers should pin an exact version. A range cannot express "compatible with
 the server you are talking to", and that is the only compatibility question
 these schemas answer. Any change that makes a previously valid message invalid

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at hello@fleetless.dev. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

package/CONTRIBUTING.md

@@ -0,0 +1,136 @@
+# Contributing to `@fleetless/contracts`
+
+This package is the single source of wire truth for Fleetless: every shape the
+API accepts or returns, and every message the robot-side bridge exchanges with
+the cloud, is written here once as a zod schema and exported as JSON Schema and
+OpenAPI for consumers that are not TypeScript.
+
+That makes a change here a cross-repository change. A schema is not a detail of
+one program; it is the agreement between several.
+
+## Setup
+
+Node 22 and pnpm (through corepack):
+
+```sh
+nvm use 22
+corepack enable
+pnpm install
+```
+
+There are no private dependencies. `pnpm install` works from a clean checkout
+with nothing but a network connection to the npm registry.
+
+## The checks
+
+| Command | What it does |
+|---|---|
+| `pnpm typecheck` | `tsc --noEmit` over `src/`, then again over `test/` with its own project. Both halves, always — the root project is `src`-only and says nothing about test files. |
+| `pnpm test` | The vitest suite. No network, no server. |
+| `pnpm build` | `tsc` into `dist/`. |
+| `pnpm artifacts` | Regenerates `artifacts/` from the zod schemas. |
+| `pnpm run test:pack` | Packs the tarball, asserts what is and is not inside it, then installs it into a scratch project and imports it for real. |
+
+To run one test file, use `pnpm vitest run test/<name>.test.ts`. Do **not**
+use `pnpm test -- <pattern>`: it does not filter, it runs the whole suite, and
+the exit code you read is the suite's.
+
+## Changing a schema
+
+1. Edit the zod schema in `src/`.
+2. Run `pnpm artifacts`. This regenerates `artifacts/`, which is **committed**.
+   A test fails if the committed artifacts are stale, and so does CI.
+3. Run `pnpm typecheck && pnpm test`.
+4. Commit the schema change and the regenerated artifacts together. A commit
+   that changes one without the other is a commit that publishes a lie to every
+   consumer validating against the artifact.
+
+Every source file carries the SPDX header `// SPDX-License-Identifier:
+Apache-2.0` as its first line. A test asserts this over the whole set — and the
+directory list is derived from the repository rather than written down, so a new
+top-level directory is swept the day it exists.
+
+The published files carry it too, which `tsc` does not do on its own:
+declaration emit drops a leading comment, so `scripts/stamp-dist.mjs` puts the
+header back on every file in `dist/` and `pnpm run test:pack` asserts it over
+the tarball's own bytes.
+
+**Nothing internal reaches the published bytes.** Doc comments in `src/` are
+carried into `dist/*.js` and `dist/*.d.ts` by `tsc`, and every
+`.meta({ description })` is copied into the JSON Schema and OpenAPI artifacts —
+so a comment written for the people who build this is a comment an editor shows
+to somebody who installed it. Write a description as what a field means to a
+caller, never as how the behaviour was found, on which machine, or under which
+internal ticket. `test/published-prose.test.ts` greps the built output and fails
+on German prose, an internal ticket id, a developer machine path or a
+first-name attribution.
+
+## Pull requests
+
+**Pull requests are welcome on GitHub**, at
+<https://github.com/fleetless/contracts>. Open an issue first for anything that
+changes an existing shape, so we can say what else has to move with it.
+
+**CI runs on GitLab.** This repository is mirrored from an internal GitLab
+instance, which is where the pipeline that verifies and publishes it lives. You
+will not see a check run on your GitHub pull request; a maintainer runs the
+same checks, and the result comes back as a review comment. Run `pnpm
+typecheck && pnpm test && pnpm artifacts` yourself before you open the pull
+request and you will have seen everything CI would tell you.
+
+## The CLA
+
+The first pull request you open will ask you to sign a Contributor Licence
+Agreement. It grants Dehne Robotik GmbH the right to license your contribution
+under terms other than Apache-2.0 in future — that is the whole of what it is
+for, and it is why the project can relicense its own code later without having
+to find every past contributor. It does not take your copyright away and it
+does not stop you from using your own contribution however you like.
+
+## Commit messages
+
+[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/):
+`feat:`, `fix:`, `docs:`, `chore:`, `ci:`, `refactor:`, `test:`. A change that
+alters an existing wire shape is a breaking change; say so with a `!` and a
+`BREAKING CHANGE:` footer, because it decides the next version number.
+
+Everything in this repository is written in **English** — code, comments,
+commit messages, documentation.
+
+## Code of conduct
+
+By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+
+## Releasing (maintainers)
+
+The pipeline publishes, and `npm publish` from a working tree is refused by a
+`prepublishOnly` script — the rule has a mechanism rather than only a sentence.
+(The pipeline is unaffected: it publishes the tarball `verify` packed, and npm
+runs no prepare lifecycle for a tarball argument.)
+
+1. Update `CHANGELOG.md` and set the new version in `package.json`. **CI checks
+   both**, in `scripts/verify-version-tag.mjs`: `package.json` must equal the
+   tag without its `v`, and `CHANGELOG.md` must carry a dated heading reading
+   exactly `## [X.Y.Z] — YYYY-MM-DD`. `CHANGELOG.md` ships inside the tarball,
+   so a forgotten entry documents the wrong version to every consumer and npm
+   will not take a version back.
+
+   The same script refuses a release tag that would move npm's `latest`
+   backwards — a backported `v1.0.1` published while `latest` is `2.0.0` would
+   make `npm i @fleetless/contracts`, the command the README gives outsiders,
+   install a package a major version behind.
+2. Commit, push, and let the `verify` job go green on the branch.
+3. Tag `vX.Y.Z` (or `vX.Y.Z-beta.N` for a pre-release, which publishes to the
+   `next` dist-tag) and push the tag. The tag pipeline runs `verify` again and
+   then `publish`.
+
+`publish` needs an `NPM_TOKEN` variable, protected and masked. Protected means
+an unprotected ref receives an empty value rather than a missing one, so the
+tag pattern must be protected too; the job names that case before it can fail
+on it obliquely.
+
+**If the publish job goes red after `npm publish` has run, do not press
+retry.** npm refuses to republish a version, so a retry fails with a 403 that
+reads like a broken pipeline rather than like a release that already happened.
+Check `npm view @fleetless/contracts@<version>` first.

package/README.md

@@ -49,15 +49,28 @@ import openapi from '@fleetless/contracts/artifacts/openapi.json' with { type: '
 
 | Path | What it is |
 |---|---|
-| `artifacts/openapi.json` | The OpenAPI description of the REST API. |
-| `artifacts/routes.json` | Every route with its request and response schema names. |
-| `artifacts/schema/*.json` | One JSON Schema per wire shape, named after the shape. |
-| `artifacts/schema-outgoing/*.json` | The messages the cloud sends to a bridge. |
+| `artifacts/openapi.json` | The OpenAPI 3.1 description of the REST API, generated from the route manifest and the schemas. |
+| `artifacts/routes.json` | Every route with its request and response schema names, and the notes that explain each one. |
+| `artifacts/schema/*.json` | One JSON Schema per wire shape, named after the shape, rendered as **a receiver validates an incoming document**. |
+| `artifacts/schema-outgoing/*.json` | Twelve of those same shapes rendered again as **a sender must produce them** — the frames a robot's bridge sends to the cloud. |
 
-The robot-side bridge validates against `artifacts/schema/` with Python's
-`jsonschema`, which is why the artifacts are generated and committed rather
-than produced at install time: a consumer in another language needs them
-without running a TypeScript build.
+The two schema directories are the same shapes in zod's two rendering modes,
+and the difference matters if you are writing a bridge.
+
+`artifacts/schema/` is *input* mode: what a receiver accepts. Fleetless
+receivers strip unknown keys rather than refusing them, so these documents omit
+`additionalProperties: false`, and a field with a default is not marked
+required.
+
+`artifacts/schema-outgoing/` is *output* mode, for the twelve frames a bridge
+**sends**. There a relaxed schema points the wrong way: a misspelled key in an
+outgoing frame would pass an input-mode check and then be silently dropped by
+the server. Validate what you send against `schema-outgoing/`, and what you
+receive against `schema/`.
+
+The artifacts are generated and committed rather than produced at install time
+because a consumer in another language needs them without running a TypeScript
+build.
 
 ## Versioning
 
@@ -69,6 +82,13 @@ client may ignore, or a description is a minor or a patch.
 Pin an exact version. These shapes describe a running server, and "compatible
 with the server you are talking to" is not something a range can express.
 
+**The one dependency, `zod`, is deliberately a range and not a pin.** zod is a
+peer in everything but name: a consumer that imports both this package and zod
+must get one copy, or a schema from here fails an `instanceof` check against
+their own. An exact pin here forces a second copy on anyone whose lockfile
+resolves a different patch. The range floor is the version these schemas are
+built, tested and exported against, and a zod major is a major here too.
+
 ## Documentation
 
 The API reference at
@@ -76,12 +96,28 @@ The API reference at
 generated from these artifacts and is the place to read what a field means.
 This package is the place to read what it *is*.
 
-## Contributing and security
+## Reporting a security issue
+
+Email **security@fleetless.dev**. Please do not open a public issue for a
+security report.
+
+**A wrong schema is a security report.** If a schema here accepts a value that
+should never reach a server — an identifier that escapes its own grammar, a
+missing bound, a union that admits a shape the API does not expect — that is a
+vulnerability in this package, even though nothing in it executes anything. So
+is a generated artifact that disagrees with the zod schema it came from, because
+consumers that are not TypeScript validate against the artifact and never see
+the zod.
+
+`SECURITY.md` ships inside the published package and has the full policy: what
+is in scope, what is not, and the response times we hold ourselves to.
+
+## Contributing
 
-[CONTRIBUTING.md](CONTRIBUTING.md) has the setup, the checks and the pull
-request process. [SECURITY.md](SECURITY.md) has the reporting address and what
-counts as a security report here — a schema that lets a bad value through is
-one, even though nothing in this package executes it.
+`CONTRIBUTING.md` ships inside the published package and has the setup, the
+checks and the pull request process. In short: `pnpm install`, then `pnpm
+typecheck && pnpm test`; every schema change regenerates `artifacts/` with
+`pnpm artifacts` and commits it in the same commit.
 
 ## Licence
 

package/SECURITY.md

@@ -0,0 +1,55 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Email **security@fleetless.dev**. Please do not open a public GitHub issue for
+a security report.
+
+Include what you found, the schema or artifact it concerns, and — if you have
+one — a value that the schema accepts and should not, or rejects and should
+not. A minimal reproduction against a published version of this package is the
+most useful thing you can send.
+
+We acknowledge every report within **3 working days** and follow up with
+either a fix or a written plan within **30 days**. If a report leads to a
+released fix, we credit you by name unless you ask us not to.
+
+## What is in scope
+
+This repository is a schema library. It defines the wire shapes of the
+Fleetless API and the bridge–cloud protocol as zod schemas, and exports them
+as JSON Schema and OpenAPI documents under `artifacts/`.
+
+**A wrong schema is a security report.** If a schema accepts a value that
+should never reach a server — an identifier that escapes its own grammar, a
+bound that is missing, a union that admits a shape the API does not expect, a
+field that a validator lets through unchecked — that is a vulnerability in
+this package, even though nothing here executes it. The same is true of a
+generated artifact that disagrees with the zod schema it came from, because
+non-TypeScript consumers validate against the artifact and never see the zod.
+
+So, in scope:
+
+- the zod schemas in `src/`;
+- the JSON Schema and OpenAPI artifacts in `artifacts/`, including any
+  disagreement between an artifact and its source schema;
+- the build and export tooling in `scripts/`;
+- the published npm package `@fleetless/contracts` and its contents.
+
+## What is not in scope
+
+**The Fleetless cloud is not in this repository.** A server that fails to
+enforce a schema, an authentication or authorisation flaw, a rate limit, a
+data leak from an API endpoint — none of those live here, and none of them can
+be fixed by a change to this package. Report them to the same address; say
+which service you were looking at, and we will route it. What we cannot do is
+treat this repository's issue tracker as the place where they are tracked.
+
+Also out of scope here: the Fleetless console, the bridge, the SDK, the
+documentation site, and any deployment of Fleetless operated by someone else.
+
+## Supported versions
+
+The latest published minor of `@fleetless/contracts` receives fixes. Older
+minors do not; a security fix is released as a new patch on the current minor,
+and consumers pin exact versions, so upgrading is the remedy.

package/artifacts/openapi.json

@@ -1490,7 +1490,7 @@
             }
           }
         },
-        "description": "The developer-authenticated door into the app's user table, and the one place `409 email_taken` is an honest answer about an app user: the caller is authenticated into this app already, so telling them the address is taken discloses nothing they could not read from the listing beside it. `POST /api/client/register` answers `202` to the same fact, because there the caller is a stranger. `404 not_found` is the app, or a `role_id` that is not a role of it — a role of another app is refused rather than stored, since a user holding one would carry rights nothing in this app can resolve. **The password policy answers `400 validation_error`**, not a code of its own: the twelve-character minimum is the `password` field's schema rule, and every route in this repository that takes a password refuses a short one exactly the way it refuses any other malformed field. An account created here is `active` immediately: a developer entering somebody by hand has made the decision the verification mail automates, and its address counts as proven. `409 target_state_conflict` names `default_role_id` when `role_id` is absent and the app has no default role, or its default names a role that no longer resolves — a user with no role holds rights nothing in this app can read, so nothing is created. \n\n**`409 quota_exceeded` when the org holds as many app users as `max_end_users` allows**, counted across every app of the org — the same number `GET /api/org/quotas` reports as `usage.max_end_users`, since the same address in two apps is two accounts. `details` carries `{ quota, limit }`, as every count quota's refusal does. The check is at **creation** only: an existing user signs in, is patched and is deleted at the quota exactly as under it, because a protection limit that also froze the accounts already made would be an outage rather than a limit.",
+        "description": "The developer-authenticated door into the app's user table, and the one place `409 email_taken` is an honest answer about an app user: the caller is authenticated into this app already, so telling them the address is taken discloses nothing they could not read from the listing beside it. `POST /api/client/register` answers `202` to the same fact, because there the caller is a stranger. `404 not_found` is the app, or a `role_id` that is not a role of it — a role of another app is refused rather than stored, since a user holding one would carry rights nothing in this app can resolve. **The password policy answers `400 validation_error`**, not a code of its own: the twelve-character minimum is the `password` field's schema rule, and every route that takes a password refuses a short one exactly the way it refuses any other malformed field. An account created here is `active` immediately: a developer entering somebody by hand has made the decision the verification mail automates, and its address counts as proven. `409 target_state_conflict` names `default_role_id` when `role_id` is absent and the app has no default role, or its default names a role that no longer resolves — a user with no role holds rights nothing in this app can read, so nothing is created. \n\n**`409 quota_exceeded` when the org holds as many app users as `max_end_users` allows**, counted across every app of the org — the same number `GET /api/org/quotas` reports as `usage.max_end_users`, since the same address in two apps is two accounts. `details` carries `{ quota, limit }`, as every count quota's refusal does. The check is at **creation** only: an existing user signs in, is patched and is deleted at the quota exactly as under it, because a protection limit that also froze the accounts already made would be an outage rather than a limit.",
         "requestBody": {
           "required": true,
           "content": {
@@ -3563,7 +3563,7 @@
             }
           }
         },
-        "description": "JSON-RPC over MCP's Streamable HTTP, so neither the request nor the response is a shape contracts describes; the tool arguments and results are the schemas in each tool definition. **Fleetless users only** — an app's users reach their own app endpoint instead. **The bearer is verified inside the handler**, not by a route guard: the identity comes from the token and the path names none, and the refusal has to carry a `WWW-Authenticate` challenge that a guard shared with the REST surface does not send. `Origin` is checked against the cloud's own, and a foreign one is the `403 forbidden` above. **Both catalogs, unconditionally**: every caller admitted here is a Fleetless user, so the tool list has nothing left to vary with and the admin-ness check on `tools/call` is gone — a console tool that is still narrower than the catalog refuses for itself (`console_robot_delete` answers `tier_required` to a non-Owner). `403 forbidden` is also what an `mcp_session` token whose subject is an **app user** gets: this endpoint serves the team only, and such a token belongs to its own app's endpoint. The code is `forbidden` rather than `mcp_disabled` because nothing is switched off — the caller is at the wrong server — and per-app sign-in mints exactly such tokens, so the two states must not share a word. `mcp_access_denied` is gone with the per-user override and the group flag it read: every Fleetless user has MCP access here (D1). Stateless: a fresh transport per request, no session id, nothing survives the call."
+        "description": "JSON-RPC over MCP's Streamable HTTP, so neither the request nor the response is a shape contracts describes; the tool arguments and results are the schemas in each tool definition. **Fleetless users only** — an app's users reach their own app endpoint instead. **The bearer is verified inside the handler**, not by a route guard: the identity comes from the token and the path names none, and the refusal has to carry a `WWW-Authenticate` challenge that a guard shared with the REST surface does not send. `Origin` is checked against the cloud's own, and a foreign one is the `403 forbidden` above. **Both catalogs, unconditionally**: every caller admitted here is a Fleetless user, so the tool list has nothing left to vary with and the admin-ness check on `tools/call` is gone — a console tool that is still narrower than the catalog refuses for itself (`console_robot_delete` answers `tier_required` to a non-Owner). `403 forbidden` is also what an `mcp_session` token whose subject is an **app user** gets: this endpoint serves the team only, and such a token belongs to its own app's endpoint. The code is `forbidden` rather than `mcp_disabled` because nothing is switched off — the caller is at the wrong server — and per-app sign-in mints exactly such tokens, so the two states must not share a word. `mcp_access_denied` is gone with the per-user override and the group flag it read: every Fleetless user has MCP access here. Stateless: a fresh transport per request, no session id, nothing survives the call."
       }
     },
     "/mcp/{appIdentifier}": {
@@ -3643,7 +3643,7 @@
             }
           }
         },
-        "description": "MCP's Streamable HTTP gives this path three verbs: `POST` carries JSON-RPC, `GET` opens the server-initiated SSE stream, and `DELETE` ends a session. This server has no sessions — the argument is in `MCP_PROTOCOL_VERSION`'s own note, and W8's second cloud instance is where a per-process session map would break — so `GET` and `DELETE` answer `405`, which is what a client is built to fall back from. \n\n**The `405` is this cloud's own answer, not the SDK's**, and the difference was measured: MCP SDK 1.30.0 opens an SSE stream on `GET` (`handleGetRequest`) and answers `200` on `DELETE` (`handleDeleteRequest`), neither of which a stateless server has any business doing, so the cloud writes the `405` itself in the transport's own JSON-RPC error shape with `Allow: POST`. \n\n**The row exists so that the `405` is not a `404`.** An unregistered verb answers `404`, and at a path whose last segment is an app identifier a `404` already means *no such app* — one answer for two states, which is the failure this project keeps paying for. Registering the verb lets the endpoint say \"this app's server is here; this verb is not part of it\". The central `/mcp` registers neither verb and does not need to: its path takes no parameter, so nothing can misread its `404`. \n\n**The `405` body is the transport's JSON-RPC error object, not the `apiError` envelope.** The three codes above are the refusals that come *first* — the app, its switch, then the bearer, in the order `POST` describes — and they are `apiError` because they are answered before the transport is reached at all. If this server ever becomes stateful, this row and the `DELETE` beside it are where that lands, and the cloud's route-manifest test is what would make both repositories notice."
+        "description": "MCP's Streamable HTTP gives this path three verbs: `POST` carries JSON-RPC, `GET` opens the server-initiated SSE stream, and `DELETE` ends a session. This server has no sessions — the argument is in `MCP_PROTOCOL_VERSION`'s own note, and a per-process session map is what breaks at the second cloud instance — so `GET` and `DELETE` answer `405`, which is what a client is built to fall back from. \n\n**The `405` is this cloud's own answer, not the SDK's**, and the two differ: MCP SDK 1.30.0 opens an SSE stream on `GET` (`handleGetRequest`) and answers `200` on `DELETE` (`handleDeleteRequest`), neither of which a stateless server has any business doing, so the cloud writes the `405` itself in the transport's own JSON-RPC error shape with `Allow: POST`. \n\n**The row exists so that the `405` is not a `404`.** An unregistered verb answers `404`, and at a path whose last segment is an app identifier a `404` already means *no such app* — one answer for two states, which is one answer for two states. Registering the verb lets the endpoint say \"this app's server is here; this verb is not part of it\". The central `/mcp` registers neither verb and does not need to: its path takes no parameter, so nothing can misread its `404`. \n\n**The `405` body is the transport's JSON-RPC error object, not the `apiError` envelope.** The three codes above are the refusals that come *first* — the app, its switch, then the bearer, in the order `POST` describes — and they are `apiError` because they are answered before the transport is reached at all. If this server ever becomes stateful, this row and the `DELETE` beside it are where that lands, and the cloud's route-manifest test is what would make both repositories notice."
       },
       "delete": {
         "operationId": "delete_mcp_appIdentifier",
@@ -3770,7 +3770,7 @@
             }
           }
         },
-        "description": "RFC 8414, for the issuer `<PUBLIC_API_BASE_URL>/mcp/<identifier>` — the same path rule as the document above, and the same `404` for a switched-off app. `registration_endpoint` is present for the reason the central document states: a client that finds it registers itself and never asks a person for a `client_id`. \n\n**`issuer`, `token_endpoint` and the resource identifier are minted from the canonical public base, never from the friendly `mcp.fleetless.dev` alias or the request's `Host`**, because a client checks a minted token's `iss` and `aud` against these exact strings. \n\n**Unlike the central document, `authorization_endpoint` does not move to an auth-portal origin**, and there is nothing here for one to serve: this authorization step renders no Fleetless page at all. It redirects to the app's own `mcp_login_url` (D7), which is on the developer's origin already."
+        "description": "RFC 8414, for the issuer `<PUBLIC_API_BASE_URL>/mcp/<identifier>` — the same path rule as the document above, and the same `404` for a switched-off app. `registration_endpoint` is present for the reason the central document states: a client that finds it registers itself and never asks a person for a `client_id`. \n\n**`issuer`, `token_endpoint` and the resource identifier are minted from the canonical public base, never from the friendly `mcp.fleetless.dev` alias or the request's `Host`**, because a client checks a minted token's `iss` and `aud` against these exact strings. \n\n**Unlike the central document, `authorization_endpoint` does not move to an auth-portal origin**, and there is nothing here for one to serve: this authorization step renders no Fleetless page at all. It redirects to the app's own `mcp_login_url`, which is on the developer's origin already."
       }
     },
     "/mcp/{appIdentifier}/oauth/register": {
@@ -3814,7 +3814,7 @@
             }
           }
         },
-        "description": "RFC 7591, the same wire and the same handler as `POST /mcp/oauth/register` — `registerMcpDynamicClient`, one implementation, because a second answer to \"is this redirect URI acceptable\" would agree with the first only by luck. The request schema is what the endpoint accepts rather than what it parses, for the reason that row gives: §3.2.2 needs two distinguishable refusals and one `safeParse` failure offers one. `client_name` and `redirect_uris` are read; `grant_types`, `response_types` and `scope` are accepted and ignored, and what comes back is what was actually granted, which §3.2.1 allows — `authorization_code` only, so a client that asked for `refresh_token` is registered and told plainly that it did not get one. The registration carries a TTL. \n\n**The registration is scoped to this app.** A `client_id` minted here authorizes at this app's endpoint and nowhere else, so a client registered against one app cannot walk into another's authorize with it, and a developer who switches MCP off is not left with strangers' registrations valid somewhere adjacent. \n\nRefusals are `oauthError`; the rate limiter and `404 not_found` answer `apiError`. That `404` covers an unknown identifier **and** an app with the switch off, mirroring the two metadata documents this endpoint is discovered from — a client that could not read those has no business registering here, and giving it a third distinct answer would only tell it something the documents deliberately do not.",
+        "description": "RFC 7591, the same wire and the same handler as `POST /mcp/oauth/register` — one implementation, because a second answer to \"is this redirect URI acceptable\" would agree with the first only by luck. The request schema is what the endpoint accepts rather than what it parses, for the reason that row gives: §3.2.2 needs two distinguishable refusals and one `safeParse` failure offers one. `client_name` and `redirect_uris` are read; `grant_types`, `response_types` and `scope` are accepted and ignored, and what comes back is what was actually granted, which §3.2.1 allows — `authorization_code` only, so a client that asked for `refresh_token` is registered and told plainly that it did not get one. The registration carries a TTL. \n\n**The registration is scoped to this app.** A `client_id` minted here authorizes at this app's endpoint and nowhere else, so a client registered against one app cannot walk into another's authorize with it, and a developer who switches MCP off is not left with strangers' registrations valid somewhere adjacent. \n\nRefusals are `oauthError`; the rate limiter and `404 not_found` answer `apiError`. That `404` covers an unknown identifier **and** an app with the switch off, mirroring the two metadata documents this endpoint is discovered from — a client that could not read those has no business registering here, and giving it a third distinct answer would only tell it something the documents deliberately do not.",
         "requestBody": {
           "required": true,
           "content": {
@@ -3929,7 +3929,7 @@
             }
           }
         },
-        "description": "The same query as `GET /mcp/oauth/authorize`, read the same way — parameter by parameter, because the answers differ and one parse would collapse them. \n\n**Fleetless renders no page here, and that is the whole of D7.** The route writes an interaction — ten minutes, as the OIDC ones live — and redirects to `appAuthConfig.mcp_login_url` with `{interaction}` filled in. The app then authenticates the person with its own UI, reads `GET /api/client/mcp/interactions/:id` to show the client's claimed name and the scopes it asked for, and calls approve or deny. \n\nClient and `redirect_uri` are validated first and a failure there never redirects — the open-redirect discipline `GET /mcp/oauth/authorize` and `GET /api/client/oidc/:slug/start` both keep — and those refusals are RFC 6749's flat `oauthError`, which is why none of them appear above. `redirect_uri` is matched **exactly** against the registration, with no loopback-port wildcard: every client here registered itself minutes ago and can name the port it bound, so a wildcard would only widen where a stolen `client_id` may send a browser. \n\nThe two codes above are the `apiError` envelope because they are refusals about the **app**, decided before an OAuth parameter is looked at. **`404 not_found` covers an identifier no app carries AND an app with MCP switched off** — the same single answer the two metadata documents, `register` and the transport give. An earlier draft answered `403 mcp_disabled` here, on the argument that a client which registered while the switch was on is owed the difference between \"turned off\" and \"mistyped\"; that argument does not survive the caller being anonymous. This route takes no credential, so the extra code was readable by anyone who could type an identifier, and it handed back precisely the existence distinction every neighbouring route collapses. `mcp_disabled` survives only where the caller has already proved they belong to the app — the two decision routes under `/api/client/mcp/interactions/:id`. `409 target_state_conflict` names `mcp_login_url` with rule `not_set`: MCP is enabled and no page is configured to send the person to. It is the same code and the same shape `send_mail` answers for an unconfigured `invite_url`, and the refusal is the honest one — Fleetless has nowhere to redirect, and rendering a page of its own instead would contradict D2."
+        "description": "The same query as `GET /mcp/oauth/authorize`, read the same way — parameter by parameter, because the answers differ and one parse would collapse them. \n\n**Fleetless renders no page here**, and that is the whole of it. The route writes an interaction — ten minutes, as the OIDC ones live — and redirects to `appAuthConfig.mcp_login_url` with `{interaction}` filled in. The app then authenticates the person with its own UI, reads `GET /api/client/mcp/interactions/:id` to show the client's claimed name and the scopes it asked for, and calls approve or deny. \n\nClient and `redirect_uri` are validated first and a failure there never redirects — the open-redirect discipline `GET /mcp/oauth/authorize` and `GET /api/client/oidc/:slug/start` both keep — and those refusals are RFC 6749's flat `oauthError`, which is why none of them appear above. `redirect_uri` is matched **exactly** against the registration, with no loopback-port wildcard: every client here registered itself minutes ago and can name the port it bound, so a wildcard would only widen where a stolen `client_id` may send a browser. \n\nThe two codes above are the `apiError` envelope because they are refusals about the **app**, decided before an OAuth parameter is looked at. **`404 not_found` covers an identifier no app carries AND an app with MCP switched off** — the same single answer the two metadata documents, `register` and the transport give. An earlier draft answered `403 mcp_disabled` here, on the argument that a client which registered while the switch was on is owed the difference between \"turned off\" and \"mistyped\"; that argument does not survive the caller being anonymous. This route takes no credential, so the extra code was readable by anyone who could type an identifier, and it handed back precisely the existence distinction every neighbouring route collapses. `mcp_disabled` survives only where the caller has already proved they belong to the app — the two decision routes under `/api/client/mcp/interactions/:id`. `409 target_state_conflict` names `mcp_login_url` with rule `not_set`: MCP is enabled and no page is configured to send the person to. It is the same code and the same shape `send_mail` answers for an unconfigured `invite_url`, and the refusal is the honest one — Fleetless has nowhere to redirect, and rendering a page of its own would contradict the rule that Fleetless shows an app user no page."
       }
     },
     "/mcp/{appIdentifier}/oauth/token": {
@@ -4644,7 +4644,7 @@
             }
           }
         },
-        "description": "**One callback URL for every app and every provider**, and the value of `appAuthConfig.oidc_callback_url` — the string a developer registers at their IdP. `CLIENT_OIDC_CALLBACK_PATH` in `client-auth.ts` is the single spelling of this path; the URL is that path on the cloud's canonical public base, never a friendly alias, because the provider compares the redirect target against the one string it was given. \n\n**Rate limited per ip, generously.** The first draft left this route unlimited on the argument that the caller is an identity provider redirecting somebody's browser, so a limiter would drop real sign-ins on the strength of traffic none of those people sent. The cost of that argument is a `state` obtained from one `start` being replayable for the interaction's full ten minutes, unbounded and unauthenticated, with every replay driving a server-side POST to the developer's token endpoint and one audit row into their org — an amplifier against a third party. The interaction is now spent on **every** terminal outcome, refusals included, which closes the replay itself; the limiter is the ceiling on how fast the attempts may arrive at all. It is per ip and sized for a browser, so a person completing a sign-in never meets it. `429 rate_limited` is the one `apiError` this route can answer, and it is not a sign-in outcome — it is a refusal to begin the work, which is why it does not ride back to the app as an `?error=`. \n\nThe query is the **provider's** rather than a Fleetless shape, and `clientOidcCallbackQuery` describes it **without being strict**: `state` always, `code` on success, `error` and `error_description` on the provider's own refusal, and whatever else that provider adds — RFC 9207's `iss`, a `session_state`, a vendor field. Refusing those would refuse conforming providers, the trap `POST /mcp/oauth/register` documents avoiding. `state` is the required field because it is the only one Fleetless minted. \n\n**It lists `rate_limited` and no other code, because every sign-in outcome it has is a redirect.** Success and failure alike are a `302` to the app's own `redirect_uri`: `?code=…&state=…` when a session was resolved, `?error=<clientOidcErrorCode>&state=…` when it was not, so the app renders its own message and can bind either answer to the request it started. Fleetless shows an app user no page (D2). \n\n**The one exception is a `state` that resolves to no interaction** — unknown, hand-edited, or past its ten minutes. Then there is no confirmed redirect target to carry the answer to, and bouncing a browser to an unvalidated one is the hole the whole flow is arranged to avoid, so the cloud renders an HTML problem page at `400`. That is the only Fleetless-rendered surface an app user can reach. It is HTML rather than an `apiError`, which is why no code is listed: a code here would document an envelope no caller receives, and this manifest's other HTML pages (`GET /mcp/oauth/interaction/:id`, `GET /console/oauth/interaction/:id`) say their status in prose for the same reason."
+        "description": "**One callback URL for every app and every provider**, and the value of `appAuthConfig.oidc_callback_url` — the string a developer registers at their IdP. `CLIENT_OIDC_CALLBACK_PATH` in `client-auth.ts` is the single spelling of this path; the URL is that path on the cloud's canonical public base, never a friendly alias, because the provider compares the redirect target against the one string it was given. \n\n**Rate limited per ip, generously.** The first draft left this route unlimited on the argument that the caller is an identity provider redirecting somebody's browser, so a limiter would drop real sign-ins on the strength of traffic none of those people sent. The cost of that argument is a `state` obtained from one `start` being replayable for the interaction's full ten minutes, unbounded and unauthenticated, with every replay driving a server-side POST to the developer's token endpoint and one audit row into their org — an amplifier against a third party. The interaction is now spent on **every** terminal outcome, refusals included, which closes the replay itself; the limiter is the ceiling on how fast the attempts may arrive at all. It is per ip and sized for a browser, so a person completing a sign-in never meets it. `429 rate_limited` is the one `apiError` this route can answer, and it is not a sign-in outcome — it is a refusal to begin the work, which is why it does not ride back to the app as an `?error=`. \n\nThe query is the **provider's** rather than a Fleetless shape, and `clientOidcCallbackQuery` describes it **without being strict**: `state` always, `code` on success, `error` and `error_description` on the provider's own refusal, and whatever else that provider adds — RFC 9207's `iss`, a `session_state`, a vendor field. Refusing those would refuse conforming providers, the trap `POST /mcp/oauth/register` documents avoiding. `state` is the required field because it is the only one Fleetless minted. \n\n**It lists `rate_limited` and no other code, because every sign-in outcome it has is a redirect.** Success and failure alike are a `302` to the app's own `redirect_uri`: `?code=…&state=…` when a session was resolved, `?error=<clientOidcErrorCode>&state=…` when it was not, so the app renders its own message and can bind either answer to the request it started. Fleetless shows an app user no page. \n\n**The one exception is a `state` that resolves to no interaction** — unknown, hand-edited, or past its ten minutes. Then there is no confirmed redirect target to carry the answer to, and bouncing a browser to an unvalidated one is the hole the whole flow is arranged to avoid, so the cloud renders an HTML problem page at `400`. That is the only Fleetless-rendered surface an app user can reach. It is HTML rather than an `apiError`, which is why no code is listed: a code here would document an envelope no caller receives, and this manifest's other HTML pages (`GET /mcp/oauth/interaction/:id`, `GET /console/oauth/interaction/:id`) say their status in prose for the same reason."
       }
     },
     "/api/client/oidc/exchange": {
@@ -4791,7 +4791,7 @@
             }
           }
         },
-        "description": "The person is already signed in **at the app**, by whatever means that app uses, and this is the app telling Fleetless what they decided. Fleetless never sees that sign-in, which is D7 in one sentence. \n\nThe guard admits all three caller kinds and the handler takes one: a developer bearer or a server key reaching this is `401 unauthorized`, because a consent is a person's and a server key is not a person — the same shape `POST /api/client/password/change` has. `403 mcp_disabled` is the app's switch, re-read here as it is on every request — and it is the one refusal on this surface that names the switch, because reaching it needs an app-user session of that very app. \n\n**An interaction of ANOTHER app answers `410 interaction_expired`, not `403`.** An interaction of one app cannot be decided with a session from another — that is what stops a developer running two apps from letting one speak for the other — but saying so with a distinct code would tell any bearer holder that the id names a real, live interaction somewhere else, which is the existence answer the shared `410` exists to withhold. Unknown, expired, already decided, an interaction of the central flow, and one belonging to a different app are one status and one body. Approve and deny spend an interaction alike, so the second call gets it whichever route made the first. \n\n**Rate limited per app user, unlike the read.** The read is a public document about a request the server already holds; this one spends something, and a decision is the one thing a leaked interaction id would be worth hammering for. The limit is on the signed-in account rather than on the ip, because that is what the caller has had to prove. \n\n**The answer is a redirect target, not a redirect.** `redirect_to` is the MCP client's own callback carrying the authorization code, and the app's page sends the browser there. The app is holding that browser and Fleetless is answering its JSON call, so a `302` here would be a redirect on the wrong request. Approving records the grant for this user and this client, which is what a later `already_granted` reads back."
+        "description": "The person is already signed in **at the app**, by whatever means that app uses, and this is the app telling Fleetless what they decided. Fleetless never sees that sign-in. \n\nThe guard admits all three caller kinds and the handler takes one: a developer bearer or a server key reaching this is `401 unauthorized`, because a consent is a person's and a server key is not a person — the same shape `POST /api/client/password/change` has. `403 mcp_disabled` is the app's switch, re-read here as it is on every request — and it is the one refusal on this surface that names the switch, because reaching it needs an app-user session of that very app. \n\n**An interaction of ANOTHER app answers `410 interaction_expired`, not `403`.** An interaction of one app cannot be decided with a session from another — that is what stops a developer running two apps from letting one speak for the other — but saying so with a distinct code would tell any bearer holder that the id names a real, live interaction somewhere else, which is the existence answer the shared `410` exists to withhold. Unknown, expired, already decided, an interaction of the central flow, and one belonging to a different app are one status and one body. Approve and deny spend an interaction alike, so the second call gets it whichever route made the first. \n\n**Rate limited per app user, unlike the read.** The read is a public document about a request the server already holds; this one spends something, and a decision is the one thing a leaked interaction id would be worth hammering for. The limit is on the signed-in account rather than on the ip, because that is what the caller has had to prove. \n\n**The answer is a redirect target, not a redirect.** `redirect_to` is the MCP client's own callback carrying the authorization code, and the app's page sends the browser there. The app is holding that browser and Fleetless is answering its JSON call, so a `302` here would be a redirect on the wrong request. Approving records the grant for this user and this client, which is what a later `already_granted` reads back."
       }
     },
     "/api/client/mcp/interactions/{id}/deny": {
@@ -4889,7 +4889,7 @@
             }
           }
         },
-        "description": "**So the developer's app can offer a \"connected apps\" screen of its own**, which is the only place an end user could ever be shown this: Fleetless renders no page for an app's users (D2), and the console is the developer's tool rather than their customers'. \n\nThe answer is about the bearer's own account and takes no user id — there is no id to pass and therefore nothing to pass the wrong one. The guard admits all three caller kinds because it is shared, and the handler takes one: a developer bearer or a server key is `401 unauthorized`, the shape `POST /api/client/password/change` has, because a consent is a person's and a server key is not a person. \n\n**Every `client_name` is unverified**, on every row: dynamic registration takes no credential, so the name is text the client chose about itself and `client_name_verified` is the literal `false`. A screen that renders it as an identity is showing somebody a string an attacker picked, and this list is read long after the moment of approval, when nobody remembers what they clicked. **Withdrawn grants are absent**, not listed as withdrawn. \n\n**Not rate limited and not gated on the app's MCP switch.** It reads one small table for one account, and a person must be able to see and end what they agreed to even after a developer switches MCP off — a withdrawal door that closes with the feature is a door that is shut exactly when somebody wants it."
+        "description": "**So the developer's app can offer a \"connected apps\" screen of its own**, which is the only place an end user could ever be shown this: Fleetless renders no page for an app's users, and the console is the developer's tool rather than their customers'. \n\nThe answer is about the bearer's own account and takes no user id — there is no id to pass and therefore nothing to pass the wrong one. The guard admits all three caller kinds because it is shared, and the handler takes one: a developer bearer or a server key is `401 unauthorized`, the shape `POST /api/client/password/change` has, because a consent is a person's and a server key is not a person. \n\n**Every `client_name` is unverified**, on every row: dynamic registration takes no credential, so the name is text the client chose about itself and `client_name_verified` is the literal `false`. A screen that renders it as an identity is showing somebody a string an attacker picked, and this list is read long after the moment of approval, when nobody remembers what they clicked. **Withdrawn grants are absent**, not listed as withdrawn. \n\n**Not rate limited and not gated on the app's MCP switch.** It reads one small table for one account, and a person must be able to see and end what they agreed to even after a developer switches MCP off — a withdrawal door that closes with the feature is a door that is shut exactly when somebody wants it."
       }
     },
     "/api/client/mcp/grants/{clientId}": {
@@ -6406,7 +6406,7 @@
             }
           }
         },
-        "description": "Needs the `action_history` capability, and **this route is what makes that switch mean something** — it was unkeepable while nothing durable recorded what had run. Two residuals worth stating rather than implying away. `history` is a syntactically valid slug and Fastify matches a static segment first, so a robot with a service literally slugged `history` can no longer be **read** through `GET /api/robots/:id/jobs/:slug`; invoking, cancelling and the listing are unaffected. And a run row names its actor by email address, so an end user holding this capability learns which other people have been driving the machine. `robot_id` in the query is shared with the org-wide read; a *different* one here is refused rather than quietly answered about the robot in the path."
+        "description": "Needs the `action_history` capability, and **this route is what makes that switch mean something** — it was unkeepable while nothing durable recorded what had run. Two residuals worth stating rather than implying away. `history` is a syntactically valid slug and The router matches a static segment first, so a robot with a service literally slugged `history` can no longer be **read** through `GET /api/robots/:id/jobs/:slug`; invoking, cancelling and the listing are unaffected. And a run row names its actor by email address, so an end user holding this capability learns which other people have been driving the machine. `robot_id` in the query is shared with the org-wide read; a *different* one here is refused rather than quietly answered about the robot in the path."
       }
     },
     "/api/robots/{id}/jobs/{slug}": {
@@ -12643,7 +12643,7 @@
               "email",
               "profile"
             ],
-            "description": "The scopes to request. Defaults to `openid email profile`, which is what the linking rules in this design actually read: the subject, the address and its verified flag, and a name.",
+            "description": "The scopes to request. Defaults to `openid email profile`, which is what account linking actually reads: the subject, the address and its verified flag, and a name.",
             "minItems": 1,
             "maxItems": 20,
             "type": "array",