@fleetless/contracts 5.3.0-next.1 → 6.0.0-next.2

package/artifacts/routes.json

@@ -76,29 +76,6 @@
       "transport": "http",
       "notes": "Answers `{ ok, dependencies: { database, storage, liveKit } }` — a cloud-local shape, not a wire contract, so nothing here pins it. The status is always `200`: each dependency is probed independently and a failure is reported in the body rather than thrown, because `/healthz` must never itself be a reason the process looks down. Read `ok`, not the status code."
     },
-    {
-      "method": "POST",
-      "path": "/api/auth/signup",
-      "section": "developer-auth",
-      "summary": "Creates an org and its founding Owner, and answers a developer session.",
-      "audience": "developer",
-      "auth": "none",
-      "rateLimited": true,
-      "ownerTier": false,
-      "status": 201,
-      "params": [],
-      "query": null,
-      "request": "sign-up-request",
-      "response": "sign-up-response",
-      "errors": [
-        "rate_limited",
-        "signup_closed",
-        "validation_error",
-        "email_taken"
-      ],
-      "transport": "http",
-      "notes": "While the deployment runs in closed beta this answers `403 signup_closed` before it looks at the body — there is nothing for a validation message, or an `email_taken` answer, to be right about when nothing will be created. Email is globally unique, so an address already registered in any org is refused."
-    },
     {
       "method": "POST",
       "path": "/api/auth/refresh",
@@ -120,7 +97,7 @@
         "token_revoked"
       ],
       "transport": "http",
-      "notes": "The whole family is re-checked here, not just the token: an account that has been removed from the org, or whose `token_version` was bumped by a password change, cannot mint a fresh console token and answers `token_revoked`. Refusing that only on the other routes would leave a session that is dead everywhere but here."
+      "notes": "The whole family is re-checked here, not just the token: an account that has been removed from the org, or whose `token_version` was bumped by an owner's two-factor reset, cannot mint a fresh console token and answers `token_revoked`. Refusing that only on the other routes would leave a session that is dead everywhere but here."
     },
     {
       "method": "POST",
@@ -188,10 +165,10 @@
       "notes": "No Owner tier: this can only ever touch the caller's own row, so there is nothing for a tier check to gate. Saving the name already held writes nothing and records no audit event — the org activity stream reaches every developer with the console open, and an event for a no-op would misreport that something changed."
     },
     {
-      "method": "POST",
-      "path": "/api/auth/password/change",
+      "method": "GET",
+      "path": "/api/auth/two-factor",
       "section": "developer-auth",
-      "summary": "Verifies the current password, sets a new one and answers a fresh session.",
+      "summary": "Answers the calling developer's passkeys, authenticator, recovery codes left and the org's policy.",
       "audience": "developer",
       "auth": "developer",
       "rateLimited": false,
@@ -199,119 +176,232 @@
       "status": 200,
       "params": [],
       "query": null,
-      "request": "password-change-request",
-      "response": "session-tokens",
+      "request": null,
+      "response": "developer-two-factor",
       "errors": [
         "unauthorized",
         "token_expired",
-        "token_revoked",
-        "validation_error",
-        "invalid_credentials"
+        "token_revoked"
       ],
       "transport": "http",
-      "notes": "Every session of this account ends, including the caller's — the request carries nothing identifying its own refresh family, so there is none to spare. The answer is a working replacement pair, which is what the promise has to mean when nothing distinguishes one session from another."
+      "notes": "What Settings › Profile › Security draws. No key material, secret or code travels here — the passkeys are names and dates, the authenticator is a date, the recovery codes are a count."
     },
     {
       "method": "POST",
-      "path": "/api/auth/password/reset",
+      "path": "/api/auth/passkeys/options",
       "section": "developer-auth",
-      "summary": "Mails a password-reset link to the address, and answers the same either way.",
+      "summary": "Answers the WebAuthn creation options for registering a passkey.",
       "audience": "developer",
-      "auth": "none",
-      "rateLimited": true,
+      "auth": "developer",
+      "rateLimited": false,
       "ownerTier": false,
-      "status": 202,
+      "status": 200,
       "params": [],
       "query": null,
-      "request": "password-reset-request",
-      "response": null,
+      "request": null,
+      "response": "webauthn-options-response",
       "errors": [
-        "rate_limited",
-        "validation_error"
+        "unauthorized",
+        "token_expired",
+        "token_revoked"
       ],
       "transport": "http",
-      "notes": "Status, body and timing are identical for a known and an unknown address — any difference is an account-enumeration oracle, which is why the unknown branch still pays a real SMTP round trip to a discard address. An account provisioned through OIDC has no Fleetless password and is mailed nothing. A browser form post gets a `303` to the \"check your mail\" card instead of this `202`."
+      "notes": "Hand `options` to the browser's WebAuthn API as it is. The relying party is `fleetless.dev`, so the passkey works on the auth portal and in the console alike; user verification is required and the credential is discoverable, so it can sign the person in without an address. The passkeys the caller already has are excluded. The challenge is single-use and expires with the ceremony."
     },
     {
-      "method": "GET",
-      "path": "/reset-password",
-      "section": "client-auth",
-      "summary": "Serves the auth portal's \"forgot your password\" card as an HTML page.",
-      "audience": "internal",
-      "auth": "none",
+      "method": "POST",
+      "path": "/api/auth/passkeys",
+      "section": "developer-auth",
+      "summary": "Registers a passkey from the browser's answer to the creation options.",
+      "audience": "developer",
+      "auth": "developer",
       "rateLimited": false,
       "ownerTier": false,
-      "status": 200,
+      "status": 201,
       "params": [],
       "query": null,
-      "request": null,
-      "response": null,
-      "errors": [],
+      "request": "create-passkey-request",
+      "response": "create-passkey-response",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "validation_error"
+      ],
       "transport": "http",
-      "notes": "HTML, not JSON: this is a page a person opens, served by the cloud from the auth portal origin. `?sent=1` draws the \"check your mail\" state instead — one path, because that second card has no inputs and a second path would exist only to be redirected to. The value is caller-settable and discloses nothing, since the page it draws is a constant."
+      "notes": "A ceremony that does not verify — a wrong challenge, origin or relying party, no user verification — is `400 validation_error` naming `credential`. When this is the account's first second factor, ten recovery codes are issued and answered once; otherwise `recovery_codes` is `null` and the existing ones stay valid. Audited as `developer.two_factor_added` with `details.kind` `passkey`."
     },
     {
-      "method": "GET",
-      "path": "/reset-password/:token",
-      "section": "client-auth",
-      "summary": "Serves the \"pick a new password\" page for a mailed reset link.",
-      "audience": "internal",
-      "auth": "none",
+      "method": "PATCH",
+      "path": "/api/auth/passkeys/:id",
+      "section": "developer-auth",
+      "summary": "Renames one of the caller's passkeys.",
+      "audience": "developer",
+      "auth": "developer",
       "rateLimited": false,
       "ownerTier": false,
       "status": 200,
       "params": [
         {
-          "name": "token",
-          "description": "The opaque reset token from the mailed link; it is never sent as a query parameter."
+          "name": "id",
+          "description": "The passkey's uuid, as listed by `GET /api/auth/two-factor`; another person's passkey answers `404`."
+        }
+      ],
+      "query": null,
+      "request": "rename-passkey-request",
+      "response": "developer-passkey",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "validation_error",
+        "not_found"
+      ],
+      "transport": "http"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/auth/passkeys/:id",
+      "section": "developer-auth",
+      "summary": "Removes one of the caller's passkeys.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 204,
+      "params": [
+        {
+          "name": "id",
+          "description": "The passkey's uuid, as listed by `GET /api/auth/two-factor`; another person's passkey answers `404`."
         }
       ],
       "query": null,
       "request": null,
       "response": null,
-      "errors": [],
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "not_found",
+        "target_state_conflict"
+      ],
       "transport": "http",
-      "notes": "HTML. An unknown, spent or expired token renders one \"link no longer valid\" page at `410` — they are one refusal on the wire already, and splitting them here would tell a stranger which tokens ever existed. No rate limiter: the GET changes nothing, and the POST it leads to is limited per IP."
+      "notes": "`409 target_state_conflict` names `two_factor` with rule `required_by_org` when this is the caller's last second factor and the organisation requires one. Removing the last one otherwise also voids the recovery codes. Audited as `developer.two_factor_removed` with `details.kind` `passkey`."
     },
     {
-      "method": "GET",
-      "path": "/favicon.svg",
-      "section": "client-auth",
-      "summary": "Serves the Fleetless icon for the auth portal's and the MCP welcome page's browser tab.",
-      "audience": "internal",
-      "auth": "none",
+      "method": "POST",
+      "path": "/api/auth/totp",
+      "section": "developer-auth",
+      "summary": "Starts an authenticator setup and answers its secret and otpauth URL.",
+      "audience": "developer",
+      "auth": "developer",
       "rateLimited": false,
       "ownerTier": false,
       "status": 200,
       "params": [],
       "query": null,
       "request": null,
-      "response": null,
-      "errors": [],
+      "response": "two-factor-setup-response",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked"
+      ],
       "transport": "http",
-      "notes": "An SVG, not JSON. Those pages carry a Content-Security-Policy that admits no `data:` image, so the icon is a file on their own origin — the one source `img-src 'self'` names. Cached for a day: the bytes change when the brand does, not per deploy."
+      "notes": "The secret is pending until `POST /api/auth/totp/confirm` accepts a code from it; a second call replaces a pending secret. A developer who already has an authenticator keeps it until the new one is confirmed, which is how `Replace…` works."
     },
     {
       "method": "POST",
-      "path": "/api/auth/password/reset/confirm",
+      "path": "/api/auth/totp/confirm",
       "section": "developer-auth",
-      "summary": "Spends a reset token, sets the new password and ends every session of the account.",
+      "summary": "Confirms the pending authenticator with a code it shows now.",
       "audience": "developer",
-      "auth": "none",
+      "auth": "developer",
       "rateLimited": true,
       "ownerTier": false,
-      "status": 204,
+      "status": 200,
       "params": [],
       "query": null,
-      "request": "password-reset-confirm",
-      "response": null,
+      "request": "totp-confirm-request",
+      "response": "totp-confirm-response",
       "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
         "rate_limited",
         "validation_error",
+        "invalid_code",
         "token_spent"
       ],
       "transport": "http",
-      "notes": "Unknown, spent and expired tokens all answer `410 token_spent`. Sessions are revoked under the account's actual kind — a console admin holds developer sessions, an app user holds end-user ones — so an app user's open `/realtime` socket does not outlive the reset. A browser form post gets the rendered \"done\" page instead of this `204`."
+      "notes": "A code that does not match the pending secret is `400 invalid_code`; no pending setup is `410 token_spent`. On success the new authenticator replaces any earlier one. Ten recovery codes are answered when it is the account's first second factor, otherwise `null`. Audited as `developer.two_factor_added` with `details.kind` `authenticator`."
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/auth/totp",
+      "section": "developer-auth",
+      "summary": "Removes the caller's authenticator app.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 204,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "not_found",
+        "target_state_conflict"
+      ],
+      "transport": "http",
+      "notes": "`404 not_found` when there is no authenticator. `409 target_state_conflict` names `two_factor` with rule `required_by_org` when it is the caller's last second factor and the organisation requires one. Audited as `developer.two_factor_removed` with `details.kind` `authenticator`."
+    },
+    {
+      "method": "POST",
+      "path": "/api/auth/recovery-codes",
+      "section": "developer-auth",
+      "summary": "Issues ten new recovery codes and voids the old ones.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "recovery-codes-response",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "target_state_conflict"
+      ],
+      "transport": "http",
+      "notes": "The codes are shown this once. `409 target_state_conflict` names `two_factor` with rule `off` when the caller has no second factor: recovery codes only stand in for one. Audited as `developer.recovery_codes_generated`."
+    },
+    {
+      "method": "GET",
+      "path": "/favicon.svg",
+      "section": "client-auth",
+      "summary": "Serves the Fleetless icon for the auth portal's and the MCP welcome page's browser tab.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [],
+      "transport": "http",
+      "notes": "An SVG, not JSON. Those pages carry a Content-Security-Policy that admits no `data:` image, so the icon is a file on their own origin — the one source `img-src 'self'` names. Cached for a day: the bytes change when the brand does, not per deploy."
     },
     {
       "method": "POST",
@@ -574,7 +664,7 @@
         "validation_error"
       ],
       "transport": "http",
-      "notes": "The body is `{ \"name\": string }` — non-empty, trimmed, at most 60 characters as on `role.name` — and is deliberately not a contract shape: contracts define the `role` this answers with, not this one trivial request. **The answer is a bare `role`, not an envelope**, unlike the listing beside it."
+      "notes": "The body is `{ \"name\": string }` — non-empty, trimmed, at most 120 characters — and is deliberately not a contract shape: contracts define the `role` this answers with, not this one trivial request. **The answer is a bare `role`, not an envelope**, unlike the listing beside it."
     },
     {
       "method": "GET",
@@ -704,77 +794,6 @@
       "transport": "http",
       "notes": "Built by the same builder the MCP server's own `robot_describe` uses, so the two cannot drift. It answers what the role *would* be offered and consults nothing about any user's actual MCP entitlement. A robot the role grants nothing on still appears, with an empty `exposures` — dropping it would read as \"not attached\", which is a different fact."
     },
-    {
-      "method": "PATCH",
-      "path": "/api/apps/:id/roles/:roleId",
-      "section": "apps",
-      "summary": "Renames a role; its users keep it.",
-      "audience": "developer",
-      "auth": "developer",
-      "rateLimited": false,
-      "ownerTier": false,
-      "status": 200,
-      "params": [
-        {
-          "name": "id",
-          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
-        },
-        {
-          "name": "roleId",
-          "description": "The role's uuid, from `GET /api/apps/:id/roles`; a role of another app answers `404`."
-        }
-      ],
-      "query": null,
-      "request": "role-rename-request",
-      "response": "role",
-      "errors": [
-        "unauthorized",
-        "token_expired",
-        "token_revoked",
-        "invalid_uuid",
-        "not_found",
-        "validation_error",
-        "role_name_taken"
-      ],
-      "transport": "http",
-      "notes": "Names are unique per app, compared exactly as stored after trimming. Built-in roles can be renamed."
-    },
-    {
-      "method": "DELETE",
-      "path": "/api/apps/:id/roles/:roleId",
-      "section": "apps",
-      "summary": "Deletes a role, moving its users, pending invitations and default-role status to another role.",
-      "audience": "developer",
-      "auth": "developer",
-      "rateLimited": false,
-      "ownerTier": false,
-      "status": 204,
-      "params": [
-        {
-          "name": "id",
-          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
-        },
-        {
-          "name": "roleId",
-          "description": "The role's uuid, from `GET /api/apps/:id/roles`; a role of another app answers `404`."
-        }
-      ],
-      "query": "role-delete-query",
-      "request": null,
-      "response": null,
-      "errors": [
-        "unauthorized",
-        "token_expired",
-        "token_revoked",
-        "invalid_uuid",
-        "not_found",
-        "validation_error",
-        "role_in_use",
-        "last_role"
-      ],
-      "transport": "http",
-      "notes": "Without `move_to`, a role that app users or pending invitations hold, or that is the app's default, answers `409 role_in_use` with `{ users, invitations, is_default }`. With `move_to` — another role of the same app, else `400 validation_error` — one transaction moves `app_users.role_id`, pending invitations and `default_role_id`, then deletes the role and its permissions. The app's only role answers `409 last_role`. Built-in roles can be deleted like any other."
-    },
     {
       "method": "POST",
       "path": "/api/apps/:id/server-keys",
@@ -1095,21 +1114,22 @@
         "token_revoked",
         "invalid_uuid",
         "not_found",
-        "target_state_conflict"
+        "target_state_conflict",
+        "method_not_allowed"
       ],
       "transport": "http",
-      "notes": "The support door beside `POST /api/client/password/reset`: the same one-hour token and the same link, triggered by a developer for a user who asked them rather than the form. **No enumeration discipline applies** — the caller is authenticated into the app and can read the user list — so this one answers what actually happened: `{ \"mail\": mailStatus }`, where `not_configured` is a deployment without a mailer and `failed` is the state worth somebody's attention. `409 target_state_conflict` names `reset_url` when the app has configured none: the token would be minted and the link would point nowhere, so nothing is minted. The same `409` names `password` with rule `not_set` for an account that has none — an OIDC-only app user, whom a reset link would hand a second, quieter door — and `status` with rule `blocked` for a blocked one, since `POST /api/client/password/reset` mails a blocked account nothing and the two doors may not disagree. Setting the password directly is deliberately not offered; a developer who could would hold their customers' credentials."
+      "notes": "The support door beside `POST /api/client/password/reset`, refused like it with `403 method_not_allowed` while the app has the password method off: the same one-hour token and the same link, triggered by a developer for a user who asked them rather than the form. **No enumeration discipline applies** — the caller is authenticated into the app and can read the user list — so this one answers what actually happened: `{ \"mail\": mailStatus }`, where `not_configured` is a deployment without a mailer and `failed` is the state worth somebody's attention. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none. `409 target_state_conflict` names `password` with rule `not_set` for an account that has none — an OIDC-only app user, whom a reset link would hand a second, quieter door — and `status` with rule `blocked` for a blocked one, since `POST /api/client/password/reset` mails a blocked account nothing and the two doors may not disagree. Setting the password directly is deliberately not offered; a developer who could would hold their customers' credentials."
     },
     {
-      "method": "GET",
-      "path": "/api/apps/:id/users/:userId/mcp-grants",
+      "method": "DELETE",
+      "path": "/api/apps/:id/users/:userId/two-factor",
       "section": "apps",
-      "summary": "Lists the MCP clients one app user has consented to.",
+      "summary": "Removes an app user's authenticator and recovery codes and ends every session they hold.",
       "audience": "developer",
       "auth": "developer",
       "rateLimited": false,
       "ownerTier": false,
-      "status": 200,
+      "status": 204,
       "params": [
         {
           "name": "id",
@@ -1122,7 +1142,40 @@
       ],
       "query": null,
       "request": null,
-      "response": "mcp-consent-grant-list-response",
+      "response": null,
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "The support door for a person who lost their authenticator and their recovery codes. The authenticator and every recovery code go, and so does every session of the account — whoever held one may be the reason for the reset. **A user with no second factor answers `204` too**: that is the end state being asked for. When the app requires two-factor, the person sets it up again at their next sign-in, before any session exists. Audited as `app_user.two_factor_reset`."
+    },
+    {
+      "method": "GET",
+      "path": "/api/apps/:id/users/:userId/mcp-grants",
+      "section": "apps",
+      "summary": "Lists the MCP clients one app user has consented to.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
+        },
+        {
+          "name": "userId",
+          "description": "The app user's uuid, from `GET /api/apps/:id/users`; a user of another app answers `404`."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": "mcp-consent-grant-list-response",
       "errors": [
         "unauthorized",
         "token_expired",
@@ -1230,7 +1283,7 @@
         "rate_limited"
       ],
       "transport": "http",
-      "notes": "**An app user, not a team member.** `POST /api/org/invitations` is the other space and leads to the console; this link leads into the developer's own app. The role is resolved and stored now, so a later change to `default_role_id` does not re-aim a link already sent. An invitation **always bypasses `allowed_domains`**. \n\nThe answer carries `accept_url`, which is `null` when the app has configured no `invite_url` — there is nowhere for the link to point, and Fleetless serves an app user no page of its own. That is a `201` with a null link, not a refusal: the invitation exists and a developer may hand the token over by another route. Asking to **mail** it in that state is `409 target_state_conflict` naming `invite_url`, because a mail carrying a dead link is worse than no mail. The same `409` names `default_role_id` when `role_id` is absent and the app has no default role, or its default no longer resolves: an invitation that names no role has nothing to hand its acceptor, so it is refused here rather than at the acceptance a week later. `409 email_taken` is an address the app already has as a user; `404 not_found` is the app or a `role_id` that is not one of its roles. \n\nCreating shares the reissue route's ceiling of **five invitation mails a minute per app**, answering `429 rate_limited` with `retry_after_ms`: re-creating an invitation for one address replaces it and mails again, so a limit that bound only reissue would be a limit on the wrong door."
+      "notes": "**An app user, not a team member.** `POST /api/org/invitations` is the other space and leads to the console; this link leads into the developer's own app. The role is resolved and stored now, so a later change to `default_role_id` does not re-aim a link already sent. An invitation **always bypasses `allowed_domains`**. \n\nThe answer carries `accept_url`: the app's `invite_url` with the token in it, or the Fleetless-hosted invitation page when the app has configured none — so mailing it is never refused for a missing URL. `409 target_state_conflict` names `default_role_id` when `role_id` is absent and the app has no default role, or its default no longer resolves: an invitation that names no role has nothing to hand its acceptor, so it is refused here rather than at the acceptance a week later. `409 email_taken` is an address the app already has as a user; `404 not_found` is the app or a `role_id` that is not one of its roles. \n\nCreating shares the reissue route's ceiling of **five invitation mails a minute per app**, answering `429 rate_limited` with `retry_after_ms`: re-creating an invitation for one address replaces it and mails again, so a limit that bound only reissue would be a limit on the wrong door."
     },
     {
       "method": "POST",
@@ -1467,7 +1520,7 @@
       "method": "GET",
       "path": "/api/apps/:id/auth-config",
       "section": "apps",
-      "summary": "Reads the app's auth settings: self-registration, domains, origins, URLs and the MCP switch.",
+      "summary": "Reads the app's auth settings: sign-in methods, two-factor, registration, pages, the hosted look and the MCP switch.",
       "audience": "developer",
       "auth": "developer",
       "rateLimited": false,
@@ -1490,7 +1543,7 @@
         "not_found"
       ],
       "transport": "http",
-      "notes": "One row per app, created with the app and never absent — an app that has configured nothing reads back the defaults rather than a `404`. `oidc_callback_url` is in the answer and not in the request: it is minted by the cloud from its own public base URL, is the same for every app and every provider, and is the value a developer registers at their identity provider. It stays read-only on every slice write below for a second reason: a writable callback URL would let a caller point the return leg of an OIDC sign-in, which carries an authorization code, at a host they own. `updated_at` is read-only for a duller one: the server stamps it on every write, and a client-supplied value would be a lie about when the row last changed."
+      "notes": "One row per app, created with the app and never absent — an app that has configured nothing reads back the defaults rather than a `404`. `oidc_callback_url` is in the answer and not in the request: it is minted by the cloud from its own public base URL, is the same for every app and every provider, and is the value a developer registers at their identity provider. It stays read-only on every slice write below for a second reason: a writable callback URL would let a caller point the return leg of an OIDC sign-in, which carries an authorization code, at a host they own. `updated_at` is read-only for a duller one: the server stamps it on every write, and a client-supplied value would be a lie about when the row last changed. `hosted_pages` and `hosted_logo_url` are read-only as well: the cloud mints both from the auth portal's base URL and the app's identifier."
     },
     {
       "method": "PUT",
@@ -1520,13 +1573,43 @@
         "not_found"
       ],
       "transport": "http",
-      "notes": "**A replace, not a merge, and `.strict()`**: `self_registration`, `allowed_domains` and `allowed_origins` all arrive or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's — see `GET`'s notes for why. \n\n`400 validation_error` is where the two field rules land: an entry in `allowed_domains` must be lowercase, since a capitalised one can never match a lowercased address, and an entry in `allowed_origins` must be a bare scheme-host-port with no path, since a browser sends nothing longer in its `Origin` header. Each refuses at configuration time rather than failing silently later. \n\nThe merge is server-side against the stored row, so this write never disturbs the urls or mcp slice."
+      "notes": "**A replace, not a merge, and `.strict()`**: `self_registration`, `allowed_domains` and `allowed_origins` all arrive or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's — see `GET`'s notes for why. \n\n`400 validation_error` is where the two field rules land: an entry in `allowed_domains` must be lowercase, since a capitalised one can never match a lowercased address, and an entry in `allowed_origins` must be a bare scheme-host-port with no path, since a browser sends nothing longer in its `Origin` header. Each refuses at configuration time rather than failing silently later. \n\nThe merge is server-side against the stored row, so this write never disturbs another slice."
+    },
+    {
+      "method": "PUT",
+      "path": "/api/apps/:id/auth-config/sign-in",
+      "section": "apps",
+      "summary": "Replaces how the app's users sign in and whether they give a second factor.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
+        }
+      ],
+      "query": null,
+      "request": "put-app-auth-sign-in-request",
+      "response": "app-auth-config",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "validation_error",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "**A replace, not a merge, and `.strict()`**: `sign_in_methods` and `two_factor` both arrive or the write is refused. Both methods off is `400 validation_error` naming `sign_in_methods.password` — an app needs at least one door besides its identity providers. \n\nTurning a method off refuses its routes with `method_not_allowed` from the next request on; a stored password stays stored. Setting `two_factor` to `required` signs nobody out: each person without an authenticator sets one up at their next sign-in, before any session exists. Audited with both old and new values. The merge is server-side against the stored row, so this write never disturbs another slice."
     },
     {
       "method": "PUT",
       "path": "/api/apps/:id/auth-config/urls",
       "section": "apps",
-      "summary": "Replaces the three pages Fleetless's mails point at.",
+      "summary": "Replaces the app's home page and the four pages Fleetless's mails and MCP sign-in point at.",
       "audience": "developer",
       "auth": "developer",
       "rateLimited": false,
@@ -1550,13 +1633,13 @@
         "not_found"
       ],
       "transport": "http",
-      "notes": "**A replace, not a merge, and `.strict()`**: `invite_url`, `verify_url` and `reset_url` all arrive or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's — see `GET`'s notes for why. \n\n`400 validation_error` is where the field rule lands: a URL template must be https (or `http` on `localhost`) and carry its placeholder exactly once — a second occurrence leaves one literal in a mailed link, refused here rather than failing silently once the mail is sent. \n\nThe merge is server-side against the stored row, so this write never disturbs the registration or mcp slice."
+      "notes": "**A replace, not a merge, and `.strict()`**: `app_url`, `invite_url`, `verify_url`, `reset_url` and `mcp_login_url` all arrive or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's — see `GET`'s notes for why. \n\nEach may be `null`, and then the Fleetless-hosted page in `hosted_pages` stands in for it: nothing is refused for a missing URL. `400 validation_error` is where the field rules land: a URL template must be https (or `http` on `localhost`) and carry its placeholder exactly once — a second occurrence leaves one literal in a mailed link, refused here rather than failing silently once the mail is sent — and `app_url` takes the same host rule with no placeholder. `mcp_login_url` moved here from the `mcp` slice, because one screen owns all four pages. \n\nThe merge is server-side against the stored row, so this write never disturbs another slice."
     },
     {
       "method": "PUT",
       "path": "/api/apps/:id/auth-config/mcp",
       "section": "apps",
-      "summary": "Replaces the MCP switch and its login URL together.",
+      "summary": "Turns the app's MCP endpoint on or off.",
       "audience": "developer",
       "auth": "developer",
       "rateLimited": false,
@@ -1580,7 +1663,97 @@
         "not_found"
       ],
       "transport": "http",
-      "notes": "**A replace, not a merge, and `.strict()`**: `mcp_enabled` and `mcp_login_url` both arrive or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's — see `GET`'s notes for why. \n\n`mcp_login_url` answers to the same rule as the `urls` slice's three templates — https (or `http` on `localhost`), its placeholder exactly once — refused as `400 validation_error` rather than left to fail mid-OAuth, in a client's browser where no console screen is watching. \n\nThe merge is server-side against the stored row, so this write never disturbs the registration or urls slice."
+      "notes": "**A replace, not a merge, and `.strict()`**: `mcp_enabled` arrives or the write is refused. It used to take `mcp_login_url` as well, because on without a URL refused every sign-in; the hosted MCP sign-in now stands in for an unset URL, and the URL moved to the `urls` slice. A body still carrying it is `400 validation_error`. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's. The merge is server-side against the stored row, so this write never disturbs another slice."
+    },
+    {
+      "method": "PUT",
+      "path": "/api/apps/:id/auth-config/look",
+      "section": "apps",
+      "summary": "Replaces the hosted pages' accent colour.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
+        }
+      ],
+      "query": null,
+      "request": "put-app-auth-look-request",
+      "response": "app-auth-config",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "validation_error",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "**A replace, and `.strict()`**: `hosted_accent` arrives, `#rrggbb` in lowercase, or `null` for the neutral shell's own accent. The logo is its own write, `PUT /api/apps/:id/auth-config/logo`, because it is an image rather than a field. The merge is server-side against the stored row, so this write never disturbs another slice."
+    },
+    {
+      "method": "PUT",
+      "path": "/api/apps/:id/auth-config/logo",
+      "section": "apps",
+      "summary": "Stores the logo the hosted pages show above the app's name.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": "app-auth-config",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "validation_error",
+        "not_found",
+        "unsupported_media_type"
+      ],
+      "transport": "http",
+      "notes": "The body is the **raw image**, not JSON, so it has no request schema: `Content-Type` is one of `HOSTED_LOGO_TYPES` (`image/png`, `image/svg+xml`) and anything else is `415 unsupported_media_type`. At most `HOSTED_LOGO_MAX_BYTES` (100 KB); a larger body, or one that is not the image its type names, is `400 validation_error`. A new logo replaces the stored one. The hosted pages load it from `hosted_logo_url` as an image only, and the cloud serves an SVG sandboxed, so a script inside one never runs."
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/apps/:id/auth-config/logo",
+      "section": "apps",
+      "summary": "Removes the logo from the hosted pages.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": "app-auth-config",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "Answers the whole configuration, with `hosted_logo_url` now `null`; the hosted pages show the app's name alone. An app with no logo answers the same: that is the end state being asked for."
     },
     {
       "method": "GET",
@@ -1609,7 +1782,7 @@
         "not_found"
       ],
       "transport": "http",
-      "notes": "Answers `{ \"templates\": [appMailTemplate, …] }` with **only the kinds that have a custom template** — at most three. A kind that does not appear is one using the Fleetless default text, which is an ordinary state and not a missing row. Mails to *Fleetless* users, a team invitation or a console password reset, are not in this list and are deliberately not customisable: they are about this platform, not about the developer's product."
+      "notes": "Answers `{ \"templates\": [appMailTemplate, …] }` with **only the kinds that have a custom template** — at most four. A kind that does not appear is one using the Fleetless default text, which is an ordinary state and not a missing row. Mails to *Fleetless* users, a team invitation or a console sign-in code, are not in this list and are deliberately not customisable: they are about this platform, not about the developer's product."
     },
     {
       "method": "GET",
@@ -1628,7 +1801,7 @@
         },
         {
           "name": "kind",
-          "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`."
+          "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`."
         }
       ],
       "query": null,
@@ -1662,7 +1835,7 @@
         },
         {
           "name": "kind",
-          "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`."
+          "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`."
         }
       ],
       "query": null,
@@ -1698,7 +1871,7 @@
         },
         {
           "name": "kind",
-          "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`."
+          "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`."
         }
       ],
       "query": null,
@@ -1732,7 +1905,7 @@
         },
         {
           "name": "kind",
-          "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`."
+          "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`."
         }
       ],
       "query": null,
@@ -1768,7 +1941,7 @@
         },
         {
           "name": "kind",
-          "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`."
+          "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`."
         }
       ],
       "query": null,
@@ -1949,7 +2122,7 @@
       "method": "POST",
       "path": "/api/org/invitations/accept",
       "section": "users",
-      "summary": "Spends an invitation token and creates the login it was addressed to.",
+      "summary": "Spends an invitation token and creates the account it was addressed to.",
       "audience": "developer",
       "auth": "none",
       "rateLimited": true,
@@ -1966,7 +2139,7 @@
         "email_taken"
       ],
       "transport": "http",
-      "notes": "**`204`, not a session.** The console signs in through its own OAuth portal, so a session minted here would be a second credential door for one account — and every security property would then have to be right in two places. Unknown, expired and already-accepted tokens collapse into `410 token_spent`. A browser form post gets the rendered \"you're in\" page instead."
+      "notes": "**`204`, not a session.** The console signs in through its own OAuth portal, so a session minted here would be a second credential door for one account — and every security property would then have to be right in two places. **No password**: the mailed link proves the address, so accepting needs no code either, and the new member signs in by emailed code from then on. When the organisation requires two-factor, the member sets one up at their first sign-in. Unknown, expired and already-accepted tokens collapse into `410 token_spent`. A browser form post gets the rendered \"you're in\" page instead."
     },
     {
       "method": "GET",
@@ -1989,7 +2162,7 @@
       "response": null,
       "errors": [],
       "transport": "http",
-      "notes": "HTML, served by the cloud from the auth portal origin; the form on it posts to `POST /api/org/invitations/accept`. An unknown, spent or expired token renders the \"link no longer valid\" page at `410`, which offers the password-reset page — the only self-service door the portal has, since an invitation cannot be re-issued by the person holding it."
+      "notes": "HTML, served by the cloud from the auth portal origin; the form on it posts to `POST /api/org/invitations/accept`. **The GET spends nothing** — a mail scanner opening the link must not accept the invitation — only the form's POST does. An unknown, spent or expired token renders the \"link no longer valid\" page at `410`, which says to ask the organisation for a new invitation: the person holding a dead link cannot re-issue it."
     },
     {
       "method": "PATCH",
@@ -2084,11 +2257,42 @@
       "transport": "http",
       "notes": "Owner tier, unconditionally — this is the route the whole owner-exclusive list is about. A uuid that is not a Fleetless user of this org answers `404 not_found`, the same as one that does not exist anywhere: the `409 target_state_conflict` documented here until the two-space cut had exactly one producer, the Org Admins membership check, and went with it. Demoting the last Owner is `409 last_owner`, decided by a row lock inside the writing transaction rather than by a read beforehand. Setting the tier already held changes nothing and writes no audit event. No session is revoked: a tier is re-read from the row on every request, so no issued token carries a stale copy of it."
     },
+    {
+      "method": "DELETE",
+      "path": "/api/org/users/:id/two-factor",
+      "section": "users",
+      "summary": "Removes a team member's passkeys, authenticator and recovery codes and ends their sessions.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": true,
+      "status": 204,
+      "params": [
+        {
+          "name": "id",
+          "description": "The Fleetless user's uuid, as listed by `GET /api/org/users`."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required",
+        "invalid_uuid",
+        "not_found",
+        "target_state_conflict"
+      ],
+      "transport": "http",
+      "notes": "Owner tier: the door for a member who lost every second factor and every recovery code. Every session of the member ends, and when the organisation requires two-factor they set one up again at their next sign-in. **An owner cannot reset their own** — `409 target_state_conflict` naming `user_id` with rule `self`; Settings › Profile is where they change it. A member with no second factor answers `204` too. Audited as `developer.two_factor_reset`, naming the owner who did it."
+    },
     {
       "method": "PATCH",
       "path": "/api/org",
       "section": "org",
-      "summary": "Renames the org.",
+      "summary": "Renames the org, requires two-factor for its members, or both.",
       "audience": "developer",
       "auth": "developer",
       "rateLimited": false,
@@ -2106,7 +2310,7 @@
         "validation_error"
       ],
       "transport": "http",
-      "notes": "Answers `{ \"org\": org }`. Owner tier, and the gate runs before the body is looked at, so a malformed rename and a forbidden one answer the same way. Renaming to the name already held writes nothing and records no audit event."
+      "notes": "Answers `{ \"org\": org }`. Owner tier, and the gate runs before the body is looked at, so a malformed patch and a forbidden one answer the same way — `403 tier_required` for a developer, whichever field they sent. An empty body is `400 validation_error`. Writing the values already held writes nothing and records no audit event. \n\n`require_two_factor` on signs nobody out: each member without a passkey or authenticator sets one up at their next sign-in, before any session exists, on the console and the central MCP endpoint alike. Server keys and robot bridges are not people and are not affected. Audited as `org.two_factor_required_changed`."
     },
     {
       "method": "GET",
@@ -2180,7 +2384,7 @@
       "response": null,
       "errors": [],
       "transport": "http",
-      "notes": "**The query schema is what this endpoint accepts, not what it parses**: the handler reads it parameter by parameter because the answers differ, and one parse would collapse them. Client and `redirect_uri` are validated first and a failure there never redirects, the same open-redirect discipline the app flow applies; those refusals are `oauthError`. Exact `redirect_uri` matching for both client kinds — the loopback-port wildcard of RFC 8252 §7.3 belongs to the one central client alone, whose URIs are configured ahead of time and cannot name an ephemeral port. A client that registered itself seconds ago can name the port it bound, and widening the wildcard there would only widen where a stolen `client_id` may send a browser. Nothing about the person is decided here — the next card asks for an email address and the password step after it resolves the account; this route knows only the client."
+      "notes": "**The query schema is what this endpoint accepts, not what it parses**: the handler reads it parameter by parameter because the answers differ, and one parse would collapse them. Client and `redirect_uri` are validated first and a failure there never redirects, the same open-redirect discipline the app flow applies; those refusals are `oauthError`. Exact `redirect_uri` matching for both client kinds — the loopback-port wildcard of RFC 8252 §7.3 belongs to the one central client alone, whose URIs are configured ahead of time and cannot name an ephemeral port. A client that registered itself seconds ago can name the port it bound, and widening the wildcard there would only widen where a stolen `client_id` may send a browser. Nothing about the person is decided here — the next card asks for an email address, or a passkey, and the steps after it resolve the account; this route knows only the client."
     },
     {
       "method": "GET",
@@ -2203,13 +2407,13 @@
       "response": null,
       "errors": [],
       "transport": "http",
-      "notes": "HTML, and a GET rather than the body of the authorize response — so it is reloadable, bookmarkable and survives a back button, which the inline page it replaced was not. An expired, consumed, unknown or hand-edited interaction renders one page at `410`, and so does a client whose dynamic registration lapsed in between."
+      "notes": "HTML, and a GET rather than the body of the authorize response — so it is reloadable, bookmarkable and survives a back button, which the inline page it replaced was not. An expired, consumed, unknown or hand-edited interaction renders one page at `410`, and so does a client whose dynamic registration lapsed in between. It offers the email field and `Sign in with a passkey`, and opening it binds the interaction to this browser with the browser-proof cookie, which every sign-in step after it checks."
     },
     {
       "method": "POST",
       "path": "/mcp/oauth/identify",
       "section": "mcp",
-      "summary": "Takes the email address and hands back the password step.",
+      "summary": "Takes the email address, mails a sign-in code and hands back the code step.",
       "audience": "internal",
       "auth": "none",
       "rateLimited": true,
@@ -2222,16 +2426,17 @@
       "errors": [
         "rate_limited",
         "validation_error",
-        "token_spent"
+        "token_spent",
+        "wrong_browser"
       ],
       "transport": "http",
-      "notes": "The identifier-first step, with nothing left to identify: Fleetless users are password-only, so **this step does not read the address at all** — it renders the password card for a known address, an unknown one and an empty one alike, and the login step below answers the same `401` for all three. That is a property of the shape rather than of two branches agreeing: there is no lookup here whose result could differ. A browser form post gets the password card; a JSON caller gets `{ \"next\" }`, which has no schema. Still rate limited per (route, ip, email), because it is an unauthenticated endpoint that renders a page."
+      "notes": "The page answers `Check your email` **for every address**: a known one gets `Your Fleetless sign-in code`, six digits valid ten minutes; an unknown one gets a mail saying no Fleetless account uses it, with a link to sign up (or the waiting list while sign-up is closed). So the page never reveals who has an account, and the address is trimmed and compared case-insensitively. A request within sixty seconds of the last one for the same address renders the same page without a second mail. The browser-proof cookie is set here when the interaction has none yet, and checked when it has. A browser form post gets the code card; a JSON caller gets `{ \"next\": \"/mcp/oauth/code\" }`, which has no schema. A dead interaction is `410 token_spent`."
     },
     {
       "method": "POST",
-      "path": "/mcp/oauth/login",
+      "path": "/mcp/oauth/code",
       "section": "mcp",
-      "summary": "Checks the password and hands back where the MCP sign-in continues.",
+      "summary": "Checks the emailed code and finishes the sign-in, or hands back the second step.",
       "audience": "internal",
       "auth": "none",
       "rateLimited": true,
@@ -2245,16 +2450,17 @@
         "rate_limited",
         "validation_error",
         "token_spent",
-        "invalid_credentials"
+        "wrong_browser",
+        "invalid_code"
       ],
       "transport": "http",
-      "notes": "The body is `{ \"interaction_id\", \"email\", \"password\" }`, read field by field rather than through a contract shape. A browser gets a `303` — to the consent screen for a self-registered client, or straight to the callback for the central one — where a JSON caller gets this `200` and `redirect_to`."
+      "notes": "A wrong code renders the code card again with the attempts left (`400 invalid_code`, `details.attempts_left`); a code spent, past its ten minutes or out of its five attempts is `410 token_spent` and a new one has to be asked for. Spaces inside a typed code are removed before it is checked. With no second factor to give, a browser gets a `303` to the consent screen for a self-registered client, or straight to the callback for the central one, and a JSON caller that URL as `redirect_to`. Otherwise the next step: a JSON caller gets `{ \"next\" }` naming `/mcp/oauth/two-factor` — the person has a passkey or an authenticator — or `/mcp/oauth/two-factor/setup` — the organisation requires one and the person has none — and a browser the page itself. Audited as `developer.login` with `details.method` `email_code` once the sign-in completes."
     },
     {
       "method": "GET",
-      "path": "/mcp/oauth/consent/:id",
+      "path": "/mcp/oauth/two-factor/:id",
       "section": "mcp",
-      "summary": "Serves the consent screen for an MCP client that registered itself.",
+      "summary": "Serves the second step: the authenticator code, or the passkey prompt.",
       "audience": "internal",
       "auth": "none",
       "rateLimited": false,
@@ -2263,7 +2469,7 @@
       "params": [
         {
           "name": "id",
-          "description": "The interaction id from the sign-in; the login step redirects the browser here."
+          "description": "The interaction id of this sign-in; the step before redirects the browser here."
         }
       ],
       "query": null,
@@ -2271,13 +2477,36 @@
       "response": null,
       "errors": [],
       "transport": "http",
-      "notes": "HTML. The browser-proof cookie is checked on this GET, not only on the POST. The **central** client never reaches this screen and renders the `410` page instead: it is configured by the operator, so there is no self-registered stranger for a person to weigh up."
+      "notes": "HTML. Six boxes for the authenticator code, `Use a passkey`, and `Use a recovery code`; a developer with passkeys only sees the passkey prompt directly. The browser-proof cookie is checked on this GET too. A dead interaction renders the `410` page."
+    },
+    {
+      "method": "GET",
+      "path": "/mcp/oauth/two-factor/:id/recovery",
+      "section": "mcp",
+      "summary": "Serves the recovery-code page of the second step.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The interaction id of this sign-in; the step before redirects the browser here."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [],
+      "transport": "http",
+      "notes": "HTML. One field for a recovery code, and the way out when none is left: an owner of the organisation can reset the member's two-factor in Settings › Team."
     },
     {
       "method": "POST",
-      "path": "/mcp/oauth/consent",
+      "path": "/mcp/oauth/two-factor",
       "section": "mcp",
-      "summary": "Records the allow-or-deny and sends the browser back to the MCP client.",
+      "summary": "Checks an authenticator code or a recovery code and finishes the sign-in.",
       "audience": "internal",
       "auth": "none",
       "rateLimited": true,
@@ -2290,52 +2519,64 @@
       "errors": [
         "rate_limited",
         "validation_error",
-        "token_spent"
+        "token_spent",
+        "wrong_browser",
+        "invalid_code"
       ],
       "transport": "http",
-      "notes": "Fail-closed exactly as the app flow's consent POST is: the body carries the pressed button's `decision`, and anything that is not the Allow value — a missing field included — denies. A denial still answers a `redirect_to`, carrying `error=access_denied` back to the client, because a client that is refused must learn so from its own callback rather than from a page nobody sent it."
+      "notes": "The form carries either `code` or `recovery_code`. **An authenticator code is accepted at most once**, so the same code sent twice finishes one sign-in. A recovery code is spent by its use. Five wrong codes end the interaction (`410 token_spent`). A browser gets a `303` to the consent screen for a self-registered client, or straight to the callback for the central one; a JSON caller that URL as `redirect_to`."
     },
     {
       "method": "POST",
-      "path": "/mcp/oauth/token",
+      "path": "/mcp/oauth/passkey/options",
       "section": "mcp",
-      "summary": "Exchanges an MCP authorization code for an access token.",
-      "audience": "client",
+      "summary": "Answers the WebAuthn request options for a passkey sign-in or second step.",
+      "audience": "internal",
       "auth": "none",
-      "rateLimited": false,
+      "rateLimited": true,
       "ownerTier": false,
       "status": 200,
       "params": [],
       "query": null,
-      "request": "oauth-token-request",
-      "response": "oauth-token-response",
-      "errors": [],
+      "request": null,
+      "response": "webauthn-options-response",
+      "errors": [
+        "rate_limited",
+        "token_spent",
+        "wrong_browser"
+      ],
       "transport": "http",
-      "notes": "`authorization_code` mints an `mcp_session` access token bound to the central resource and a refresh token; `refresh_token` rotates that pair, and the presented refresh token is consumed — a second presentation revokes the session, as on `/api/auth/refresh`. The refresh token lives ninety days from its last use and is bound to the `client_id` it was issued to. A refresh re-reads the Fleetless user, so a removed account cannot refresh. Refusals are RFC 6749 §5.2's `oauthError`, so this route emits none of the codes in this reference. The code is single-use, PKCE-verified, and its `resource` must match the audience it was authorized for; a `resource` on a refresh must match the session's audience, and is checked before the token is consumed."
+      "notes": "Before an address is known the options name no credential, so the browser offers every discoverable passkey for `fleetless.dev` (`Sign in with a passkey`); after the code step they name the account's own passkeys. User verification is required. The challenge is bound to the interaction and single-use. **This is the first step of a passkey sign-in**, which has no email step: the browser-proof cookie is set here when the interaction has none yet, and checked when it has — so `POST /mcp/oauth/passkey` can require it."
     },
     {
-      "method": "GET",
-      "path": "/console/oauth/authorize",
-      "section": "developer-auth",
-      "summary": "Starts a console sign-in and redirects the browser to the identify card.",
+      "method": "POST",
+      "path": "/mcp/oauth/passkey",
+      "section": "mcp",
+      "summary": "Checks a passkey assertion; a passkey completes the sign-in on its own.",
       "audience": "internal",
       "auth": "none",
-      "rateLimited": false,
+      "rateLimited": true,
       "ownerTier": false,
-      "status": 302,
+      "status": 200,
       "params": [],
       "query": null,
       "request": null,
-      "response": null,
-      "errors": [],
+      "response": "oauth-redirect-response",
+      "errors": [
+        "rate_limited",
+        "validation_error",
+        "token_spent",
+        "wrong_browser",
+        "invalid_credentials"
+      ],
       "transport": "http",
-      "notes": "The authorization-code leg of the console's own OAuth flow: PKCE `S256` is required and `redirect_uri` must match a configured console callback exactly, never a prefix. Refusals use RFC 6749's flat `oauthError` shape, not the `apiError` envelope, so they carry none of the codes in this reference. A bad `redirect_uri` never redirects — until the URI is known-good, sending a browser to it is the attack; later errors go back to the callback as query parameters. `?prompt=create` starts at sign-up rather than sign-in."
+      "notes": "**A passkey is a full sign-in**: it proves possession and user verification, two factors, so it skips the emailed code and the second step — used as the second step, it finishes it. An assertion that does not verify, or names no passkey of an account, is `401 invalid_credentials`, the same answer for both. When the organisation requires two-factor, a passkey satisfies it. A browser gets a `303` to the consent screen for a self-registered client, or straight to the callback for the central one; a JSON caller that URL as `redirect_to`. Audited as `developer.login` with `details.method` `passkey`."
     },
     {
       "method": "GET",
-      "path": "/console/oauth/interaction/:id",
-      "section": "developer-auth",
-      "summary": "Serves the \"what is your email address\" card of a console sign-in.",
+      "path": "/mcp/oauth/two-factor/setup/:id",
+      "section": "mcp",
+      "summary": "Serves the \"your organisation requires two-factor\" choice between a passkey and an authenticator.",
       "audience": "internal",
       "auth": "none",
       "rateLimited": false,
@@ -2344,64 +2585,1045 @@
       "params": [
         {
           "name": "id",
-          "description": "The interaction id minted by `GET /console/oauth/authorize`, which redirects the browser here."
+          "description": "The interaction id of this sign-in; the step before redirects the browser here."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [],
+      "transport": "http",
+      "notes": "HTML. Reached when the organisation requires two-factor and the person has none; no session exists until the setup is done. Two options, the passkey recommended because it also signs the person in without an emailed code. `Signed in as <email> · Sign out` under it."
+    },
+    {
+      "method": "POST",
+      "path": "/mcp/oauth/two-factor/setup/totp",
+      "section": "mcp",
+      "summary": "Starts an authenticator setup inside the sign-in and hands back its QR code and key.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "two-factor-setup-response",
+      "errors": [
+        "rate_limited",
+        "token_spent",
+        "wrong_browser"
+      ],
+      "transport": "http",
+      "notes": "A browser gets the page with the QR code, the key and the confirm field; a JSON caller the secret and `otpauth_url`. Nothing is stored as confirmed yet."
+    },
+    {
+      "method": "POST",
+      "path": "/mcp/oauth/two-factor/setup/totp/confirm",
+      "section": "mcp",
+      "summary": "Confirms the new authenticator and hands back the ten recovery codes.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "recovery-codes-response",
+      "errors": [
+        "rate_limited",
+        "validation_error",
+        "token_spent",
+        "wrong_browser",
+        "invalid_code"
+      ],
+      "transport": "http",
+      "notes": "A code that does not match is `400 invalid_code`. On success the authenticator is on and ten recovery codes are shown once; `I saved my recovery codes` then finishes the sign-in. Audited as `developer.two_factor_added` with `details.kind` `authenticator`."
+    },
+    {
+      "method": "POST",
+      "path": "/mcp/oauth/two-factor/setup/passkey/options",
+      "section": "mcp",
+      "summary": "Answers the WebAuthn creation options for a passkey set up inside the sign-in.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "webauthn-options-response",
+      "errors": [
+        "rate_limited",
+        "token_spent",
+        "wrong_browser"
+      ],
+      "transport": "http",
+      "notes": "The same options `POST /api/auth/passkeys/options` answers a signed-in developer: relying party `fleetless.dev`, user verification required, a discoverable credential."
+    },
+    {
+      "method": "POST",
+      "path": "/mcp/oauth/two-factor/setup/passkey",
+      "section": "mcp",
+      "summary": "Registers the passkey and hands back the ten recovery codes.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "recovery-codes-response",
+      "errors": [
+        "rate_limited",
+        "validation_error",
+        "token_spent",
+        "wrong_browser"
+      ],
+      "transport": "http",
+      "notes": "A ceremony that does not verify is `400 validation_error`. On success the passkey is stored, named after the browser's device where it says so, and ten recovery codes are shown once. Audited as `developer.two_factor_added` with `details.kind` `passkey`."
+    },
+    {
+      "method": "POST",
+      "path": "/mcp/oauth/two-factor/setup/done",
+      "section": "mcp",
+      "summary": "Finishes the sign-in once the recovery codes are saved.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "oauth-redirect-response",
+      "errors": [
+        "rate_limited",
+        "token_spent",
+        "wrong_browser"
+      ],
+      "transport": "http",
+      "notes": "`I saved my recovery codes` gates the button on the page; the step itself only checks that a second factor now exists. A browser gets a `303` to the consent screen for a self-registered client, or straight to the callback for the central one; a JSON caller that URL as `redirect_to`."
+    },
+    {
+      "method": "GET",
+      "path": "/mcp/oauth/consent/:id",
+      "section": "mcp",
+      "summary": "Serves the consent screen for an MCP client that registered itself.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The interaction id from the sign-in; the last sign-in step redirects the browser here."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [],
+      "transport": "http",
+      "notes": "HTML. The browser-proof cookie is checked on this GET, not only on the POST. The **central** client never reaches this screen and renders the `410` page instead: it is configured by the operator, so there is no self-registered stranger for a person to weigh up."
+    },
+    {
+      "method": "POST",
+      "path": "/mcp/oauth/consent",
+      "section": "mcp",
+      "summary": "Records the allow-or-deny and sends the browser back to the MCP client.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "oauth-redirect-response",
+      "errors": [
+        "rate_limited",
+        "validation_error",
+        "token_spent"
+      ],
+      "transport": "http",
+      "notes": "Fail-closed exactly as the app flow's consent POST is: the body carries the pressed button's `decision`, and anything that is not the Allow value — a missing field included — denies. A denial still answers a `redirect_to`, carrying `error=access_denied` back to the client, because a client that is refused must learn so from its own callback rather than from a page nobody sent it."
+    },
+    {
+      "method": "POST",
+      "path": "/mcp/oauth/token",
+      "section": "mcp",
+      "summary": "Exchanges an MCP authorization code for an access token.",
+      "audience": "client",
+      "auth": "none",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": "oauth-token-request",
+      "response": "oauth-token-response",
+      "errors": [],
+      "transport": "http",
+      "notes": "`authorization_code` mints an `mcp_session` access token bound to the central resource and a refresh token; `refresh_token` rotates that pair, and the presented refresh token is consumed — a second presentation revokes the session, as on `/api/auth/refresh`. The refresh token lives ninety days from its last use and is bound to the `client_id` it was issued to. A refresh re-reads the Fleetless user, so a removed account cannot refresh. Refusals are RFC 6749 §5.2's `oauthError`, so this route emits none of the codes in this reference. The code is single-use, PKCE-verified, and its `resource` must match the audience it was authorized for; a `resource` on a refresh must match the session's audience, and is checked before the token is consumed."
+    },
+    {
+      "method": "GET",
+      "path": "/console/oauth/authorize",
+      "section": "developer-auth",
+      "summary": "Starts a console sign-in and redirects the browser to the identify card.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 302,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [],
+      "transport": "http",
+      "notes": "The authorization-code leg of the console's own OAuth flow: PKCE `S256` is required and `redirect_uri` must match a configured console callback exactly, never a prefix. Refusals use RFC 6749's flat `oauthError` shape, not the `apiError` envelope, so they carry none of the codes in this reference. A bad `redirect_uri` never redirects — until the URI is known-good, sending a browser to it is the attack; later errors go back to the callback as query parameters. `?prompt=create` starts at sign-up rather than sign-in."
+    },
+    {
+      "method": "GET",
+      "path": "/console/oauth/interaction/:id",
+      "section": "developer-auth",
+      "summary": "Serves the \"what is your email address\" card of a console sign-in.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The interaction id minted by `GET /console/oauth/authorize`, which redirects the browser here."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [],
+      "transport": "http",
+      "notes": "HTML: the email field, `Email me a code`, and `Sign in with a passkey`. Opening it binds the interaction to this browser with the browser-proof cookie, which every sign-in step after it checks. An expired, consumed, unknown or hand-edited interaction renders one page at `410`: which of the four it was is not a fact a stranger may learn, and to the person it is one fact anyway. The page resolves nothing about the address typed into it, so there is no enumeration oracle here at all."
+    },
+    {
+      "method": "POST",
+      "path": "/console/oauth/identify",
+      "section": "developer-auth",
+      "summary": "Takes the email address, mails a sign-in code and hands back the code step.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [
+        "rate_limited",
+        "validation_error",
+        "token_spent",
+        "wrong_browser"
+      ],
+      "transport": "http",
+      "notes": "The page answers `Check your email` **for every address**: a known one gets `Your Fleetless sign-in code`, six digits valid ten minutes; an unknown one gets a mail saying no Fleetless account uses it, with a link to sign up (or the waiting list while sign-up is closed). So the page never reveals who has an account, and the address is trimmed and compared case-insensitively. A request within sixty seconds of the last one for the same address renders the same page without a second mail. The browser-proof cookie is set here when the interaction has none yet, and checked when it has. A browser form post gets the code card; a JSON caller gets `{ \"next\": \"/console/oauth/code\" }`, which has no schema. A dead interaction is `410 token_spent`."
+    },
+    {
+      "method": "POST",
+      "path": "/console/oauth/code",
+      "section": "developer-auth",
+      "summary": "Checks the emailed code and finishes the sign-in, or hands back the second step.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "oauth-redirect-response",
+      "errors": [
+        "rate_limited",
+        "validation_error",
+        "token_spent",
+        "wrong_browser",
+        "invalid_code"
+      ],
+      "transport": "http",
+      "notes": "A wrong code renders the code card again with the attempts left (`400 invalid_code`, `details.attempts_left`); a code spent, past its ten minutes or out of its five attempts is `410 token_spent` and a new one has to be asked for. Spaces inside a typed code are removed before it is checked. With no second factor to give, a browser gets a `303` to the console callback with the authorization code, and a JSON caller that URL as `redirect_to`. Otherwise the next step: a JSON caller gets `{ \"next\" }` naming `/console/oauth/two-factor` — the person has a passkey or an authenticator — or `/console/oauth/two-factor/setup` — the organisation requires one and the person has none — and a browser the page itself. Audited as `developer.login` with `details.method` `email_code` once the sign-in completes."
+    },
+    {
+      "method": "GET",
+      "path": "/console/oauth/two-factor/:id",
+      "section": "developer-auth",
+      "summary": "Serves the second step: the authenticator code, or the passkey prompt.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The interaction id of this sign-in; the step before redirects the browser here."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [],
+      "transport": "http",
+      "notes": "HTML. Six boxes for the authenticator code, `Use a passkey`, and `Use a recovery code`; a developer with passkeys only sees the passkey prompt directly. The browser-proof cookie is checked on this GET too. A dead interaction renders the `410` page."
+    },
+    {
+      "method": "GET",
+      "path": "/console/oauth/two-factor/:id/recovery",
+      "section": "developer-auth",
+      "summary": "Serves the recovery-code page of the second step.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The interaction id of this sign-in; the step before redirects the browser here."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [],
+      "transport": "http",
+      "notes": "HTML. One field for a recovery code, and the way out when none is left: an owner of the organisation can reset the member's two-factor in Settings › Team."
+    },
+    {
+      "method": "POST",
+      "path": "/console/oauth/two-factor",
+      "section": "developer-auth",
+      "summary": "Checks an authenticator code or a recovery code and finishes the sign-in.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "oauth-redirect-response",
+      "errors": [
+        "rate_limited",
+        "validation_error",
+        "token_spent",
+        "wrong_browser",
+        "invalid_code"
+      ],
+      "transport": "http",
+      "notes": "The form carries either `code` or `recovery_code`. **An authenticator code is accepted at most once**, so the same code sent twice finishes one sign-in. A recovery code is spent by its use. Five wrong codes end the interaction (`410 token_spent`). A browser gets a `303` to the console callback with the authorization code; a JSON caller that URL as `redirect_to`."
+    },
+    {
+      "method": "POST",
+      "path": "/console/oauth/passkey/options",
+      "section": "developer-auth",
+      "summary": "Answers the WebAuthn request options for a passkey sign-in or second step.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "webauthn-options-response",
+      "errors": [
+        "rate_limited",
+        "token_spent",
+        "wrong_browser"
+      ],
+      "transport": "http",
+      "notes": "Before an address is known the options name no credential, so the browser offers every discoverable passkey for `fleetless.dev` (`Sign in with a passkey`); after the code step they name the account's own passkeys. User verification is required. The challenge is bound to the interaction and single-use. **This is the first step of a passkey sign-in**, which has no email step: the browser-proof cookie is set here when the interaction has none yet, and checked when it has — so `POST /console/oauth/passkey` can require it."
+    },
+    {
+      "method": "POST",
+      "path": "/console/oauth/passkey",
+      "section": "developer-auth",
+      "summary": "Checks a passkey assertion; a passkey completes the sign-in on its own.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "oauth-redirect-response",
+      "errors": [
+        "rate_limited",
+        "validation_error",
+        "token_spent",
+        "wrong_browser",
+        "invalid_credentials"
+      ],
+      "transport": "http",
+      "notes": "**A passkey is a full sign-in**: it proves possession and user verification, two factors, so it skips the emailed code and the second step — used as the second step, it finishes it. An assertion that does not verify, or names no passkey of an account, is `401 invalid_credentials`, the same answer for both. When the organisation requires two-factor, a passkey satisfies it. A browser gets a `303` to the console callback with the authorization code; a JSON caller that URL as `redirect_to`. Audited as `developer.login` with `details.method` `passkey`."
+    },
+    {
+      "method": "GET",
+      "path": "/console/oauth/two-factor/setup/:id",
+      "section": "developer-auth",
+      "summary": "Serves the \"your organisation requires two-factor\" choice between a passkey and an authenticator.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The interaction id of this sign-in; the step before redirects the browser here."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [],
+      "transport": "http",
+      "notes": "HTML. Reached when the organisation requires two-factor and the person has none; no session exists until the setup is done. Two options, the passkey recommended because it also signs the person in without an emailed code. `Signed in as <email> · Sign out` under it."
+    },
+    {
+      "method": "POST",
+      "path": "/console/oauth/two-factor/setup/totp",
+      "section": "developer-auth",
+      "summary": "Starts an authenticator setup inside the sign-in and hands back its QR code and key.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "two-factor-setup-response",
+      "errors": [
+        "rate_limited",
+        "token_spent",
+        "wrong_browser"
+      ],
+      "transport": "http",
+      "notes": "A browser gets the page with the QR code, the key and the confirm field; a JSON caller the secret and `otpauth_url`. Nothing is stored as confirmed yet."
+    },
+    {
+      "method": "POST",
+      "path": "/console/oauth/two-factor/setup/totp/confirm",
+      "section": "developer-auth",
+      "summary": "Confirms the new authenticator and hands back the ten recovery codes.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "recovery-codes-response",
+      "errors": [
+        "rate_limited",
+        "validation_error",
+        "token_spent",
+        "wrong_browser",
+        "invalid_code"
+      ],
+      "transport": "http",
+      "notes": "A code that does not match is `400 invalid_code`. On success the authenticator is on and ten recovery codes are shown once; `I saved my recovery codes` then finishes the sign-in. Audited as `developer.two_factor_added` with `details.kind` `authenticator`."
+    },
+    {
+      "method": "POST",
+      "path": "/console/oauth/two-factor/setup/passkey/options",
+      "section": "developer-auth",
+      "summary": "Answers the WebAuthn creation options for a passkey set up inside the sign-in.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "webauthn-options-response",
+      "errors": [
+        "rate_limited",
+        "token_spent",
+        "wrong_browser"
+      ],
+      "transport": "http",
+      "notes": "The same options `POST /api/auth/passkeys/options` answers a signed-in developer: relying party `fleetless.dev`, user verification required, a discoverable credential."
+    },
+    {
+      "method": "POST",
+      "path": "/console/oauth/two-factor/setup/passkey",
+      "section": "developer-auth",
+      "summary": "Registers the passkey and hands back the ten recovery codes.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "recovery-codes-response",
+      "errors": [
+        "rate_limited",
+        "validation_error",
+        "token_spent",
+        "wrong_browser"
+      ],
+      "transport": "http",
+      "notes": "A ceremony that does not verify is `400 validation_error`. On success the passkey is stored, named after the browser's device where it says so, and ten recovery codes are shown once. Audited as `developer.two_factor_added` with `details.kind` `passkey`."
+    },
+    {
+      "method": "POST",
+      "path": "/console/oauth/two-factor/setup/done",
+      "section": "developer-auth",
+      "summary": "Finishes the sign-in once the recovery codes are saved.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "oauth-redirect-response",
+      "errors": [
+        "rate_limited",
+        "token_spent",
+        "wrong_browser"
+      ],
+      "transport": "http",
+      "notes": "`I saved my recovery codes` gates the button on the page; the step itself only checks that a second factor now exists. A browser gets a `303` to the console callback with the authorization code; a JSON caller that URL as `redirect_to`."
+    },
+    {
+      "method": "GET",
+      "path": "/console/oauth/signup/:id",
+      "section": "developer-auth",
+      "summary": "Serves step one of console sign-up, the email card.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The interaction id minted by `GET /console/oauth/authorize` with `?prompt=create`."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [],
+      "transport": "http",
+      "notes": "HTML: the email field and `Email me a code`, the first of three steps — email, code, organization. While the deployment runs in closed beta this renders the \"sign-up is closed\" card at `403` instead, keeping the interaction alive and pointing back at sign-in and the waiting list — the person may well already have an account."
+    },
+    {
+      "method": "POST",
+      "path": "/console/oauth/signup",
+      "section": "developer-auth",
+      "summary": "Takes the sign-up email, mails a code and hands back the code step.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [
+        "rate_limited",
+        "token_spent",
+        "signup_closed",
+        "validation_error",
+        "email_taken"
+      ],
+      "transport": "http",
+      "notes": "A browser form post gets the code card; a JSON caller gets `{ \"next\", \"email\" }`, which has no schema. **No password**: the code mailed here, six digits valid ten minutes, proves the address. A per-interaction proof cookie is set here — it is what stops a third party from finishing a sign-up somebody else started. Sign-up is the one surface whose job is to say an address is taken, so `409 email_taken` is not a leak here."
+    },
+    {
+      "method": "POST",
+      "path": "/console/oauth/signup/code",
+      "section": "developer-auth",
+      "summary": "Checks the sign-up code and hands back the organization step.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [
+        "rate_limited",
+        "token_spent",
+        "signup_closed",
+        "wrong_browser",
+        "validation_error",
+        "invalid_code"
+      ],
+      "transport": "http",
+      "notes": "A wrong code renders the code card again with the attempts left (`400 invalid_code`); a spent, expired or exhausted one is `410 token_spent`. The step before must have run in **this** browser (`401 wrong_browser`). A browser form post gets the organization card, the address shown `confirmed`; a JSON caller gets `{ \"next\" }`, which has no schema."
+    },
+    {
+      "method": "POST",
+      "path": "/console/oauth/signup/organization",
+      "section": "developer-auth",
+      "summary": "Takes the organization name and creates the org and its founding Owner.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "oauth-redirect-response",
+      "errors": [
+        "rate_limited",
+        "token_spent",
+        "signup_closed",
+        "wrong_browser",
+        "validation_error",
+        "email_taken"
+      ],
+      "transport": "http",
+      "notes": "The form carries `org_name` only. The org and its founding Owner are created in one transaction, and only after the code step confirmed the address. Both steps before must have run in **this** browser: a missing or mismatched proof cookie is `401 wrong_browser` and the person is sent back to step one. `409 email_taken` when the address was taken meanwhile. A browser form post gets a `303` to the console callback; a JSON caller gets `redirect_to` at `200`. This is the only way an organisation is created: `POST /api/auth/signup` is gone, because without a password it would hand a session to anybody who names an address."
+    },
+    {
+      "method": "POST",
+      "path": "/console/oauth/token",
+      "section": "developer-auth",
+      "summary": "Exchanges the console's authorization code for a developer session.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "session-tokens",
+      "errors": [],
+      "transport": "http",
+      "notes": "Called by the console's own server, never by a browser. Refusals use RFC 6749 §5.2's flat `oauthError` shape — it is a token endpoint, and that is the dialect a caller of one expects — so it emits none of the codes in this reference. Proof of possession is checked before the replay check, and the single-use consume is atomic, so exactly one caller ever mints. The Org Admins membership is re-read here: the code was minted earlier, and a user moved out in between must not get a console session."
+    },
+    {
+      "method": "GET",
+      "path": "/app/:appIdentifier/logo",
+      "section": "client-auth",
+      "summary": "Serves the app's logo for its hosted pages.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [],
+      "transport": "http",
+      "notes": "The stored PNG or SVG, as written through `PUT /api/apps/:id/auth-config/logo`; `404` when the app has none. **Served sandboxed**: `X-Content-Type-Options: nosniff` and `Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; sandbox`, so a script inside an SVG never runs, even opened directly. The hosted pages embed it as an image only."
+    },
+    {
+      "method": "GET",
+      "path": "/app/:appIdentifier/mcp/:interaction",
+      "section": "client-auth",
+      "summary": "Serves the hosted MCP sign-in, the page an unset `mcp_login_url` falls back to.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
+        },
+        {
+          "name": "interaction",
+          "description": "The interaction id `GET /mcp/:appIdentifier/oauth/authorize` put into the hosted MCP sign-in URL."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [],
+      "transport": "http",
+      "notes": "HTML: the app's identity providers, then the sign-in the app offers — email and password with `Email me a sign-in code instead`, or email and `Email me a code` for a code-only app — and `Create one` when self-registration is on. A dead interaction renders the `410` page. The browser-proof cookie is set here."
+    },
+    {
+      "method": "POST",
+      "path": "/app/:appIdentifier/mcp/:interaction/password",
+      "section": "client-auth",
+      "summary": "Checks the email and password of the hosted MCP sign-in.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
+        },
+        {
+          "name": "interaction",
+          "description": "The interaction id `GET /mcp/:appIdentifier/oauth/authorize` put into the hosted MCP sign-in URL."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [
+        "rate_limited"
+      ],
+      "transport": "http",
+      "notes": "HTML: the next page on success, the same page with the problem named on a refusal. One refusal for every miss, as `POST /api/client/login` answers. With a second factor to give, the two-factor page follows; otherwise the consent page."
+    },
+    {
+      "method": "POST",
+      "path": "/app/:appIdentifier/mcp/:interaction/code",
+      "section": "client-auth",
+      "summary": "Mails a sign-in code for the hosted MCP sign-in and renders the code page.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
+        },
+        {
+          "name": "interaction",
+          "description": "The interaction id `GET /mcp/:appIdentifier/oauth/authorize` put into the hosted MCP sign-in URL."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [
+        "rate_limited"
+      ],
+      "transport": "http",
+      "notes": "HTML: the next page on success, the same page with the problem named on a refusal. The same page for a known and an unknown address, as `POST /api/client/login/code` answers; six boxes, `Resend code in 0:42`, and `Use password instead` where the app has passwords on."
+    },
+    {
+      "method": "POST",
+      "path": "/app/:appIdentifier/mcp/:interaction/code/verify",
+      "section": "client-auth",
+      "summary": "Checks the emailed code of the hosted MCP sign-in.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
+        },
+        {
+          "name": "interaction",
+          "description": "The interaction id `GET /mcp/:appIdentifier/oauth/authorize` put into the hosted MCP sign-in URL."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [
+        "rate_limited"
+      ],
+      "transport": "http",
+      "notes": "HTML: the next page on success, the same page with the problem named on a refusal. A wrong code renders the code page with the attempts left; a spent one asks for a new code. With a second factor to give, the two-factor page follows; otherwise the consent page."
+    },
+    {
+      "method": "POST",
+      "path": "/app/:appIdentifier/mcp/:interaction/consent",
+      "section": "client-auth",
+      "summary": "Records the allow-or-deny of the hosted MCP sign-in and sends the browser back to the client.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
+        },
+        {
+          "name": "interaction",
+          "description": "The interaction id `GET /mcp/:appIdentifier/oauth/authorize` put into the hosted MCP sign-in URL."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [
+        "rate_limited"
+      ],
+      "transport": "http",
+      "notes": "Answers a `303` to the MCP client's callback, carrying the code or `error=access_denied`, as `POST /api/client/mcp/interactions/:id/approve` and `…/deny` do. Fail-closed: anything but the Allow value denies. The browser-proof cookie set at the sign-in must match, or the `wrong_browser` page renders."
+    },
+    {
+      "method": "POST",
+      "path": "/app/:appIdentifier/two-factor",
+      "section": "client-auth",
+      "summary": "Checks an authenticator or recovery code on a hosted page and finishes the sign-in it interrupted.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [
+        "rate_limited"
+      ],
+      "transport": "http",
+      "notes": "HTML: the next page on success, the same page with the problem named on a refusal. The form carries the challenge the step before answered and either `code` or `recovery_code`, checked as `POST /api/client/two-factor/verify` checks them. Success continues where the sign-in was going: the MCP consent, or the done page."
+    },
+    {
+      "method": "POST",
+      "path": "/app/:appIdentifier/two-factor/setup",
+      "section": "client-auth",
+      "summary": "Starts an authenticator setup on a hosted page, when the app requires two-factor.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [
+        "rate_limited"
+      ],
+      "transport": "http",
+      "notes": "HTML: the next page on success, the same page with the problem named on a refusal. Renders the QR code, the key with `Copy key`, and the confirm field, for the challenge the step before answered."
+    },
+    {
+      "method": "POST",
+      "path": "/app/:appIdentifier/two-factor/setup/confirm",
+      "section": "client-auth",
+      "summary": "Confirms the new authenticator on a hosted page and shows the ten recovery codes.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [
+        "rate_limited"
+      ],
+      "transport": "http",
+      "notes": "HTML: the next page on success, the same page with the problem named on a refusal. A wrong code renders the setup page again. On success the ten recovery codes are shown once, with `Copy` and `Download .txt`; `I saved my recovery codes` gates `Continue`."
+    },
+    {
+      "method": "GET",
+      "path": "/app/:appIdentifier/invite/:token",
+      "section": "client-auth",
+      "summary": "Serves the hosted invitation page, the one an unset `invite_url` falls back to.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
+        },
+        {
+          "name": "token",
+          "description": "The opaque token from the mailed link; it is never sent as a query parameter."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [],
+      "transport": "http",
+      "notes": "HTML. Renders a form; only its `POST` spends the token, so a mail scanner opening the link changes nothing. Asks for a name, and a password only while the app has passwords on; announces the two-factor setup when the app requires it. A spent, expired or unknown token renders the `410` page with the next step for its kind."
+    },
+    {
+      "method": "POST",
+      "path": "/app/:appIdentifier/invite",
+      "section": "client-auth",
+      "summary": "Accepts an invitation from the hosted invitation page.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [
+        "rate_limited"
+      ],
+      "transport": "http",
+      "notes": "HTML: the next page on success, the same page with the problem named on a refusal. Spends the token as `POST /api/client/invitations/accept` does; the two-factor setup follows when the app requires it, then the done page."
+    },
+    {
+      "method": "GET",
+      "path": "/app/:appIdentifier/reset/:token",
+      "section": "client-auth",
+      "summary": "Serves the hosted new-password page, the one an unset `reset_url` falls back to.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
+        },
+        {
+          "name": "token",
+          "description": "The opaque token from the mailed link; it is never sent as a query parameter."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [],
+      "transport": "http",
+      "notes": "HTML. Renders a form; only its `POST` spends the token, so a mail scanner opening the link changes nothing. Says that two-factor stays on. A spent, expired or unknown token renders the `410` page with the next step for its kind."
+    },
+    {
+      "method": "POST",
+      "path": "/app/:appIdentifier/reset",
+      "section": "client-auth",
+      "summary": "Sets the new password from the hosted new-password page.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
         }
       ],
       "query": null,
       "request": null,
       "response": null,
-      "errors": [],
+      "errors": [
+        "rate_limited"
+      ],
       "transport": "http",
-      "notes": "HTML. An expired, consumed, unknown or hand-edited interaction renders one page at `410`: which of the four it was is not a fact a stranger may learn, and to the person it is one fact anyway. The page resolves nothing about the address typed into it, so there is no enumeration oracle here at all."
+      "notes": "HTML: the next page on success, the same page with the problem named on a refusal. Spends the token as `POST /api/client/password/reset/confirm` does; a person with an authenticator gives a code before the done page."
     },
     {
-      "method": "POST",
-      "path": "/console/oauth/identify",
-      "section": "developer-auth",
-      "summary": "Takes the email address and hands back the password step.",
+      "method": "GET",
+      "path": "/app/:appIdentifier/forgot",
+      "section": "client-auth",
+      "summary": "Serves the hosted \"forgot your password\" page.",
       "audience": "internal",
       "auth": "none",
-      "rateLimited": true,
+      "rateLimited": false,
       "ownerTier": false,
       "status": 200,
-      "params": [],
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
+        }
+      ],
       "query": null,
       "request": null,
       "response": null,
-      "errors": [
-        "rate_limited",
-        "token_spent"
-      ],
+      "errors": [],
       "transport": "http",
-      "notes": "A browser form post gets the password card as HTML; a JSON caller gets `{ \"next\": \"/console/oauth/login\" }`, which has no schema — the step made no decision, and it says so rather than inventing a redirect. A dead interaction is `410 token_spent`. Rate limited despite spending no credential: it is an unauthenticated endpoint that renders a page."
+      "notes": "HTML: the address field. Reached from the hosted sign-in and the dead-link page."
     },
     {
       "method": "POST",
-      "path": "/console/oauth/login",
-      "section": "developer-auth",
-      "summary": "Checks the password and mints the authorization code the console exchanges.",
+      "path": "/app/:appIdentifier/forgot",
+      "section": "client-auth",
+      "summary": "Mails a reset link from the hosted \"forgot your password\" page.",
       "audience": "internal",
       "auth": "none",
       "rateLimited": true,
       "ownerTier": false,
       "status": 200,
-      "params": [],
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
+        }
+      ],
       "query": null,
       "request": null,
-      "response": "oauth-redirect-response",
+      "response": null,
       "errors": [
-        "rate_limited",
-        "token_spent",
-        "invalid_credentials"
+        "rate_limited"
       ],
       "transport": "http",
-      "notes": "This is the only place a Fleetless developer password may be typed; `POST /api/auth/login` is gone, because a second credential door means every security property has to be right in two places. A browser form post gets a `303` to the callback URL; a JSON caller gets that same URL as `redirect_to` at `200`. An argon2 verify runs whether or not the address exists, and the Org Admins check runs after it — filtering first would hand back a faster \"no\" for a non-admin account, which is a timing oracle. Wrong password, unknown address and \"not an org admin\" render identical bytes under one `401`."
+      "notes": "HTML: the next page on success, the same page with the problem named on a refusal. The same \"check your mail\" page for a known and an unknown address, as `POST /api/client/password/reset` answers."
     },
     {
       "method": "GET",
-      "path": "/console/oauth/signup/:id",
-      "section": "developer-auth",
-      "summary": "Serves step one of console sign-up, the account card.",
+      "path": "/app/:appIdentifier/sign-up",
+      "section": "client-auth",
+      "summary": "Serves the hosted sign-up page, when the app has self-registration on.",
       "audience": "internal",
       "auth": "none",
       "rateLimited": false,
@@ -2409,8 +3631,8 @@
       "status": 200,
       "params": [
         {
-          "name": "id",
-          "description": "The interaction id minted by `GET /console/oauth/authorize` with `?prompt=create`."
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
         }
       ],
       "query": null,
@@ -2418,74 +3640,84 @@
       "response": null,
       "errors": [],
       "transport": "http",
-      "notes": "HTML. While the deployment runs in closed beta this renders the \"sign-up is closed\" card at `403` instead, keeping the interaction alive and pointing back at sign-in — the person may well already have an account."
+      "notes": "HTML: the address, a password while the app has passwords on, and an optional name. With self-registration off it renders the \"registration closed\" page."
     },
     {
       "method": "POST",
-      "path": "/console/oauth/signup",
-      "section": "developer-auth",
-      "summary": "Takes the sign-up email and password and hands back the organization step.",
+      "path": "/app/:appIdentifier/sign-up",
+      "section": "client-auth",
+      "summary": "Creates an account from the hosted sign-up page and mails the confirmation link.",
       "audience": "internal",
       "auth": "none",
       "rateLimited": true,
       "ownerTier": false,
       "status": 200,
-      "params": [],
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
+        }
+      ],
       "query": null,
       "request": null,
       "response": null,
       "errors": [
-        "rate_limited",
-        "token_spent",
-        "signup_closed",
-        "validation_error",
-        "email_taken"
+        "rate_limited"
       ],
       "transport": "http",
-      "notes": "A browser form post gets the organization card; a JSON caller gets `{ \"next\", \"email\" }`, which has no schema. The plaintext password exists for this one request: what is stored is its argon2 hash, on the interaction row, which expires with it. A per-interaction proof cookie is set here — it is what stops a third party from finishing a sign-up somebody else started. Sign-up is the one surface whose job is to say an address is taken, so `409 email_taken` is not a leak here."
+      "notes": "HTML: the next page on success, the same page with the problem named on a refusal. Registers as `POST /api/client/register` does, and renders the same \"check your mail\" page for a new and a known address."
     },
     {
-      "method": "POST",
-      "path": "/console/oauth/signup/organization",
-      "section": "developer-auth",
-      "summary": "Takes the organization name and creates the org and its founding Owner.",
+      "method": "GET",
+      "path": "/app/:appIdentifier/verify/:token",
+      "section": "client-auth",
+      "summary": "Serves the hosted email-confirmation page, the one an unset `verify_url` falls back to.",
       "audience": "internal",
       "auth": "none",
-      "rateLimited": true,
+      "rateLimited": false,
       "ownerTier": false,
       "status": 200,
-      "params": [],
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
+        },
+        {
+          "name": "token",
+          "description": "The opaque token from the mailed link; it is never sent as a query parameter."
+        }
+      ],
       "query": null,
       "request": null,
-      "response": "oauth-redirect-response",
-      "errors": [
-        "rate_limited",
-        "token_spent",
-        "signup_closed",
-        "wrong_browser",
-        "validation_error",
-        "email_taken"
-      ],
+      "response": null,
+      "errors": [],
       "transport": "http",
-      "notes": "The same single transaction `POST /api/auth/signup` runs. Step one must have run in **this** browser: a missing or mismatched proof cookie is `401 wrong_browser` and the person is sent back to step one. A browser form post gets a `303` to the console callback; a JSON caller gets `redirect_to` at `200`."
+      "notes": "HTML. Renders a form; only its `POST` spends the token, so a mail scanner opening the link changes nothing. A spent, expired or unknown token renders the `410` page with the next step for its kind."
     },
     {
       "method": "POST",
-      "path": "/console/oauth/token",
-      "section": "developer-auth",
-      "summary": "Exchanges the console's authorization code for a developer session.",
+      "path": "/app/:appIdentifier/verify",
+      "section": "client-auth",
+      "summary": "Confirms the address from the hosted email-confirmation page.",
       "audience": "internal",
       "auth": "none",
-      "rateLimited": false,
+      "rateLimited": true,
       "ownerTier": false,
       "status": 200,
-      "params": [],
+      "params": [
+        {
+          "name": "appIdentifier",
+          "description": "The app's public identifier — `app.identifier`, what the console prints beside its copy button. It is not a secret: it appears in this path, in both metadata documents, and in the URL an app user pastes into their AI tool."
+        }
+      ],
       "query": null,
       "request": null,
-      "response": "session-tokens",
-      "errors": [],
+      "response": null,
+      "errors": [
+        "rate_limited"
+      ],
       "transport": "http",
-      "notes": "Called by the console's own server, never by a browser. Refusals use RFC 6749 §5.2's flat `oauthError` shape — it is a token endpoint, and that is the dialect a caller of one expects — so it emits none of the codes in this reference. Proof of possession is checked before the replay check, and the single-use consume is atomic, so exactly one caller ever mints. The Org Admins membership is re-read here: the code was minted earlier, and a user moved out in between must not get a console session."
+      "notes": "HTML: the next page on success, the same page with the problem named on a refusal. Spends the token as `POST /api/client/verify-email` does; the two-factor setup follows when the app requires it, then the done page."
     },
     {
       "method": "GET",
@@ -2655,7 +3887,7 @@
         "not_found"
       ],
       "transport": "http",
-      "notes": "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."
+      "notes": "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**: the authorization step renders no page itself. It redirects to the app's own `mcp_login_url`, or to the hosted MCP sign-in on the auth portal when the app has configured none."
     },
     {
       "method": "POST",
@@ -2687,7 +3919,7 @@
       "method": "GET",
       "path": "/mcp/:appIdentifier/oauth/authorize",
       "section": "mcp",
-      "summary": "Starts an MCP sign-in and redirects the browser to the app's own login page.",
+      "summary": "Starts an MCP sign-in and redirects the browser to the app's own login page, or to the hosted one.",
       "audience": "client",
       "auth": "none",
       "rateLimited": false,
@@ -2703,11 +3935,10 @@
       "request": null,
       "response": null,
       "errors": [
-        "not_found",
-        "target_state_conflict"
+        "not_found"
       ],
       "transport": "http",
-      "notes": "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."
+      "notes": "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**This route renders no page.** It 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. **An app with no `mcp_login_url` is redirected to the hosted MCP sign-in** (`GET /app/:appIdentifier/mcp/:interaction`), which runs the same steps on the auth portal; nothing is refused for a missing URL. \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 code above is the `apiError` envelope because it is a refusal 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`."
     },
     {
       "method": "POST",
@@ -2745,14 +3976,62 @@
       "params": [],
       "query": null,
       "request": "client-login-request",
-      "response": "session-tokens",
+      "response": "client-sign-in-result",
       "errors": [
         "rate_limited",
         "validation_error",
-        "invalid_credentials"
+        "invalid_credentials",
+        "method_not_allowed"
+      ],
+      "transport": "http",
+      "notes": "One refusal for every miss — unknown app, unknown address, wrong password, a `blocked` account and one still `pending_verification` — because the caller supplies the `app_identifier` unauthenticated, so \"this app knows this user\" is not a fact the answer may carry. The argon2 verify is paid unconditionally, including for an unknown app identifier, so response time is not an oracle either. \n\n**The answer is a `clientSignInResult`**: session tokens, or a `twoFactorChallenge` when the person has a confirmed authenticator or the app requires one — then no session exists until `POST /api/client/two-factor/verify` or the setup is done. `403 method_not_allowed` when the app has the password method off; it names the app's policy, not a person."
+    },
+    {
+      "method": "POST",
+      "path": "/api/client/login/code",
+      "section": "client-auth",
+      "summary": "Mails a six-digit sign-in code, and answers the same whether or not the address exists.",
+      "audience": "client",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 202,
+      "params": [],
+      "query": null,
+      "request": "client-login-code-request",
+      "response": null,
+      "errors": [
+        "rate_limited",
+        "validation_error",
+        "not_found",
+        "method_not_allowed"
+      ],
+      "transport": "http",
+      "notes": "**`202` and an empty body for every request the policy allows**, in status, body and timing, whether or not the address names an active account of this app — a decoy like `POST /api/client/resend-verification`, so this is no enumeration oracle. A mail goes out for an `active` account and for one still `pending_verification` — spending the code proves the address, as the verification link would — and never for a `blocked` one or an unknown address. The code is six digits, valid ten minutes, takes five wrong attempts, and a new request expires the previous one for the same address; a request within sixty seconds of the last sends no second mail. The address is trimmed and compared case-insensitively. `404 not_found` is the **app identifier**, never the address; `403 method_not_allowed` when the app has the email-code method off. Limited per app, address and IP, so it cannot be used to mail somebody repeatedly."
+    },
+    {
+      "method": "POST",
+      "path": "/api/client/login/code/verify",
+      "section": "client-auth",
+      "summary": "Spends a mailed sign-in code and answers a session or a two-factor challenge.",
+      "audience": "client",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": "client-login-code-verify-request",
+      "response": "client-sign-in-result",
+      "errors": [
+        "rate_limited",
+        "validation_error",
+        "invalid_code",
+        "token_spent",
+        "method_not_allowed"
       ],
       "transport": "http",
-      "notes": "One refusal for every miss — unknown app, unknown address, wrong password, a `blocked` account and one still `pending_verification` — because the caller supplies the `app_identifier` unauthenticated, so \"this app knows this user\" is not a fact the answer may carry. The argon2 verify is paid unconditionally, including for an unknown app identifier, so response time is not an oracle either."
+      "notes": "A wrong code is `400 invalid_code` with `details.attempts_left` (`invalidCodeDetails`). A code that is spent, past its ten minutes, out of attempts, or was never mailed is `410 token_spent` — one answer, because telling them apart would say whether a code was ever sent to that address; the recovery is the same, ask for a new code. The address is trimmed and compared case-insensitively, so the address typed at the request and here need not match in case. \n\n**The answer is a `clientSignInResult`**, like the password login: tokens, or a `twoFactorChallenge` when the person has an authenticator or the app requires one. A pending-verification account that spends a code is activated — reading a mail at that address is the proof verification asks for."
     },
     {
       "method": "POST",
@@ -2778,7 +4057,7 @@
         "quota_exceeded"
       ],
       "transport": "http",
-      "notes": "**`202` and an empty body for every request policy allows** — a new address, one this app already knows and one it does not answer identically, in status, body and timing. An answer that depended on existence would be the account-enumeration oracle the whole client family is built to avoid. The account cannot log in until the mailed link is spent; `POST /api/client/verify-email` is what does that. \n\n**An address on an account still `pending_verification` is re-registered, not ignored.** The password and display name from this call replace what is stored, every outstanding verification link for the address stops working, and a fresh one is mailed. Otherwise whoever typed an address first would own the password of the account its real owner later verifies. An address on an `active` account changes nothing and sends nothing — that account has already been proven, and its way back in is `POST /api/client/password/reset`. Neither case is visible in the answer. \n\nThe refusals it *does* make are about policy or about what the caller typed, never about a person. `403 registration_closed` when the app has self-registration off and `403 domain_not_allowed` when the address is outside `allowed_domains`: both are the developer's own configuration, and a stranger learns the app's policy rather than who is in it. **A password under twelve characters is part of that `400 validation_error`** and not a code of its own — the minimum is the `password` field's schema rule, and the error names the field, which is what a form needs to mark it. `404 not_found` names an **app identifier no app carries**, and never an address: an app identifier is already public (it is in the MCP metadata path and in the developer's own URLs), while collapsing it into `registration_closed` sent a developer who mistyped their own identifier hunting a configuration bug that was not there. `409 target_state_conflict` when the app has configured no `verify_url` or has no default role — there would be nowhere to send the person and no role to give them, and mailing a link that leads nowhere is worse than refusing. \n\n**`409 quota_exceeded` when the org is at its `max_end_users` limit**, counted across every app of the org. It is the one refusal here that is answered **before the address is looked at** — and that ordering is the point rather than an implementation detail: a quota checked after the existence branch would answer `202` for an address the app already knows and `409` for one it does not, which is precisely the enumeration oracle every other line of this route exists to close. At the quota, every registration is refused identically, including one that would only have re-mailed a pending account's link."
+      "notes": "**`202` and an empty body for every request policy allows** — a new address, one this app already knows and one it does not answer identically, in status, body and timing. An answer that depended on existence would be the account-enumeration oracle the whole client family is built to avoid. The account cannot log in until the mailed link is spent; `POST /api/client/verify-email` is what does that. \n\n**An address on an account still `pending_verification` is re-registered, not ignored.** The password and display name from this call replace what is stored, every outstanding verification link for the address stops working, and a fresh one is mailed. Otherwise whoever typed an address first would own the password of the account its real owner later verifies. An address on an `active` account changes nothing and sends nothing — that account has already been proven, and its way back in is `POST /api/client/password/reset`. Neither case is visible in the answer. \n\nThe refusals it *does* make are about policy or about what the caller typed, never about a person. `403 registration_closed` when the app has self-registration off and `403 domain_not_allowed` when the address is outside `allowed_domains`: both are the developer's own configuration, and a stranger learns the app's policy rather than who is in it. **A password under twelve characters is part of that `400 validation_error`** and not a code of its own — the minimum is the `password` field's schema rule, and the error names the field, which is what a form needs to mark it. The same `400` names `password` when one is missing while the app's password method is on, or sent while it is off: an email-code-only app registers people without one. `404 not_found` names an **app identifier no app carries**, and never an address: an app identifier is already public (it is in the MCP metadata path and in the developer's own URLs), while collapsing it into `registration_closed` sent a developer who mistyped their own identifier hunting a configuration bug that was not there. `409 target_state_conflict` when the app has no default role — there would be no role to give the person. An app with no `verify_url` is not refused: the mailed link points at the hosted confirmation page instead. \n\n**`409 quota_exceeded` when the org is at its `max_end_users` limit**, counted across every app of the org. It is the one refusal here that is answered **before the address is looked at** — and that ordering is the point rather than an implementation detail: a quota checked after the existence branch would answer `202` for an address the app already knows and `409` for one it does not, which is precisely the enumeration oracle every other line of this route exists to close. At the quota, every registration is refused identically, including one that would only have re-mailed a pending account's link."
     },
     {
       "method": "POST",
@@ -2793,14 +4072,14 @@
       "params": [],
       "query": null,
       "request": "client-verify-email-request",
-      "response": "session-tokens",
+      "response": "client-sign-in-result",
       "errors": [
         "rate_limited",
         "validation_error",
         "token_spent"
       ],
       "transport": "http",
-      "notes": "**The answer is a session, not a `204`.** Somebody who has just proved they can read the mail should not be asked to type their password again on the next screen, and the app has an access token to carry them into it. The token is spent first and the account is activated second, as **two writes**: the spend is the atomic one, so a link opened twice cannot mint two sessions, but a process that died between them would leave a spent token on an account still `pending_verification`, whose recovery is `POST /api/client/resend-verification`. Spending the token also proves the address, so a later `PATCH` may return the account to `active` after a block. \n\n**One refusal for every token that does not work: `410 token_spent`** — unknown, past its twenty-four hours, or already used. There is one code because distinguishing them would tell a stranger whether a token ever existed, and because the recovery is the same in all three cases: ask for a fresh link with `POST /api/client/resend-verification`. An app rendering this refusal should offer that and nothing conditional on which of the three it was."
+      "notes": "**The answer is a session, not a `204`** — or, as on every sign-in step, a `twoFactorChallenge` when the app requires two-factor (`clientSignInResult`). Somebody who has just proved they can read the mail should not be asked to type their password again on the next screen, and the app has an access token to carry them into it. The token is spent first and the account is activated second, as **two writes**: the spend is the atomic one, so a link opened twice cannot mint two sessions, but a process that died between them would leave a spent token on an account still `pending_verification`, whose recovery is `POST /api/client/resend-verification`. Spending the token also proves the address, so a later `PATCH` may return the account to `active` after a block. \n\n**One refusal for every token that does not work: `410 token_spent`** — unknown, past its twenty-four hours, or already used. There is one code because distinguishing them would tell a stranger whether a token ever existed, and because the recovery is the same in all three cases: ask for a fresh link with `POST /api/client/resend-verification`. An app rendering this refusal should offer that and nothing conditional on which of the three it was."
     },
     {
       "method": "POST",
@@ -2841,10 +4120,11 @@
       "errors": [
         "rate_limited",
         "validation_error",
-        "not_found"
+        "not_found",
+        "method_not_allowed"
       ],
       "transport": "http",
-      "notes": "**The app-user twin of `POST /api/auth/password/reset`, and a different shape** because the two surfaces name a person differently: a Fleetless address is globally unique and resolves alone, an app user's is unique only within their app, so the pair is the identifier. Status, body and timing are identical for a known and an unknown address. An account with no Fleetless password — one created through an identity provider — is mailed nothing and still answers `202`. `404 not_found` is the **app identifier**, never the address. The link points at the app's `reset_url`; an app that has configured none can send no mail, which the `202` does not distinguish, because saying so would answer for the address as well."
+      "notes": "The pair of app identifier and address is the identifier: an app user's address is unique only within their app. `403 method_not_allowed` when the app has the password method off — a reset link whose confirmation would be refused is not mailed; the code names the app's policy, not a person. Status, body and timing are identical for a known and an unknown address. An account with no password — one created through an identity provider — is mailed nothing and still answers `202`. `404 not_found` is the **app identifier**, never the address. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none."
     },
     {
       "method": "POST",
@@ -2859,14 +4139,15 @@
       "params": [],
       "query": null,
       "request": "client-password-reset-confirm-request",
-      "response": "session-tokens",
+      "response": "client-sign-in-result",
       "errors": [
         "rate_limited",
         "validation_error",
-        "token_spent"
+        "token_spent",
+        "method_not_allowed"
       ],
       "transport": "http",
-      "notes": "**Every refresh family of that account is revoked**, then a fresh pair is minted for the caller — a forgotten password is one of the two states where somebody else may be holding a live session, and the person completing the reset is the one who should keep theirs. The account is activated if it was still `pending_verification`: reading a mail at that address is the same proof verification asks for. \n\n**One refusal for every token that does not work: `410 token_spent`** — unknown, past its hour, or already used. There is one code because distinguishing them would tell a stranger whether a token ever existed, and the recovery is identical either way: ask for a new link. A replacement password under twelve characters is a `400 validation_error` naming the `new_password` field — the twelve-character minimum is that field's schema rule, and it is refused the way any other malformed field is."
+      "notes": "**A new password does not bypass the second factor**: a person with an authenticator, or in an app that requires one, gets a `twoFactorChallenge` instead of tokens (`clientSignInResult`), and the authenticator stays on. `403 method_not_allowed` when the app has the password method off. \n\n**Every refresh family of that account is revoked**, then a fresh pair is minted for the caller — a forgotten password is one of the two states where somebody else may be holding a live session, and the person completing the reset is the one who should keep theirs. The account is activated if it was still `pending_verification`: reading a mail at that address is the same proof verification asks for. \n\n**One refusal for every token that does not work: `410 token_spent`** — unknown, past its hour, or already used. There is one code because distinguishing them would tell a stranger whether a token ever existed, and the recovery is identical either way: ask for a new link. A replacement password under twelve characters is a `400 validation_error` naming the `new_password` field — the twelve-character minimum is that field's schema rule, and it is refused the way any other malformed field is."
     },
     {
       "method": "POST",
@@ -2881,7 +4162,7 @@
       "params": [],
       "query": null,
       "request": "client-accept-invitation-request",
-      "response": "session-tokens",
+      "response": "client-sign-in-result",
       "errors": [
         "rate_limited",
         "validation_error",
@@ -2891,7 +4172,7 @@
         "quota_exceeded"
       ],
       "transport": "http",
-      "notes": "**An app invitation, not a team one.** `POST /api/org/invitations/accept` is the other space and answers `204`; this one answers a session, because the person is landing in the developer's app and there is no second door for them to sign in through. The role is the one the invitation fixed at creation, so a later change to the app's default role does not re-aim a link already in somebody's inbox, and the invitation **bypasses `allowed_domains`** — a developer inviting somebody by hand has already made the decision the whitelist automates. \n\n**One refusal for every token that does not work: `410 token_spent`** — unknown, expired past the seven days, revoked by the developer, or already accepted. There is one code because telling them apart would say whether a token ever existed, and because the one thing the holder of a dead link can do is ask the developer for a new one, whichever of the four it was. A chosen password under twelve characters is part of the `400 validation_error`, naming the `password` field. `409 email_taken` is an address this app has acquired since the invitation was written **as an account that is already in use** — the invitation stays outstanding rather than being spent, so the developer can revoke it or point the person at the login. An address that registered itself and is still `pending_verification` is not that state: accepting sets the password the invitee just chose, activates the account and gives it the invitation's role, because reading the invitation mail proves the address the verification link was waiting on. \n\n`409 target_state_conflict` names `role_id` with rule `not_set` when the role the invitation was fixed to has since been deleted and the app has no default role to fall back on: there is no access to hand the acceptor, and creating an account with none would be worse than saying so. \n\n**`409 quota_exceeded` when accepting would CREATE an account and the org is at its `max_end_users` limit**, counted across every app of the org. An invitation that names a row the developer already created, and one whose address is held by an unfinished self-registration, both finish an account that already counts — those are not refused, because the org is not one account larger afterwards. The token is not spent by the refusal: the developer can raise the limit, or delete somebody, and the same link still works."
+      "notes": "**An app invitation, not a team one.** `POST /api/org/invitations/accept` is the other space and answers `204`; this one answers a session, because the person is landing in the developer's app and there is no second door for them to sign in through. The role is the one the invitation fixed at creation, so a later change to the app's default role does not re-aim a link already in somebody's inbox, and the invitation **bypasses `allowed_domains`** — a developer inviting somebody by hand has already made the decision the whitelist automates. The answer is a `clientSignInResult`: a `twoFactorChallenge` instead of tokens when the app requires two-factor. `password` is required while the app's password method is on and refused while it is off, both as `400 validation_error` naming the field. \n\n**One refusal for every token that does not work: `410 token_spent`** — unknown, expired past the seven days, revoked by the developer, or already accepted. There is one code because telling them apart would say whether a token ever existed, and because the one thing the holder of a dead link can do is ask the developer for a new one, whichever of the four it was. A chosen password under twelve characters is part of the `400 validation_error`, naming the `password` field. `409 email_taken` is an address this app has acquired since the invitation was written **as an account that is already in use** — the invitation stays outstanding rather than being spent, so the developer can revoke it or point the person at the login. An address that registered itself and is still `pending_verification` is not that state: accepting sets the password the invitee just chose, activates the account and gives it the invitation's role, because reading the invitation mail proves the address the verification link was waiting on. \n\n`409 target_state_conflict` names `role_id` with rule `not_set` when the role the invitation was fixed to has since been deleted and the app has no default role to fall back on: there is no access to hand the acceptor, and creating an account with none would be worse than saying so. \n\n**`409 quota_exceeded` when accepting would CREATE an account and the org is at its `max_end_users` limit**, counted across every app of the org. An invitation that names a row the developer already created, and one whose address is held by an unfinished self-registration, both finish an account that already counts — those are not refused, because the org is not one account larger afterwards. The token is not spent by the refusal: the developer can raise the limit, or delete somebody, and the same link still works."
     },
     {
       "method": "POST",
@@ -2958,10 +4239,11 @@
         "forbidden",
         "validation_error",
         "invalid_credentials",
-        "target_state_conflict"
+        "target_state_conflict",
+        "method_not_allowed"
       ],
       "transport": "http",
-      "notes": "The guard admits all three caller kinds, but a password belongs to an app user specifically — a developer bearer or a server key reaching this is `401 unauthorized`. Every other session of the account ends; the answer is the replacement pair, so the tab that made the change stays signed in. An app user belongs to one app, so \"every session\" is this app's. An account that has **no password** — an OIDC-only app user, which the schema admits — answers `409 target_state_conflict` naming the `password` field with rule `not_set`, not `401`: the session is live and the token is fine, it is the account that has nothing to change, and telling such a caller to sign in again sends them round a loop that ends here."
+      "notes": "`403 method_not_allowed` when the app has the password method off: a stored password stays stored but is not in use, so it is not changed either. The guard admits all three caller kinds, but a password belongs to an app user specifically — a developer bearer or a server key reaching this is `401 unauthorized`. Every other session of the account ends; the answer is the replacement pair, so the tab that made the change stays signed in. An app user belongs to one app, so \"every session\" is this app's. An account that has **no password** — an OIDC-only app user, which the schema admits — answers `409 target_state_conflict` naming the `password` field with rule `not_set`, not `401`: the session is live and the token is fine, it is the account that has nothing to change, and telling such a caller to sign in again sends them round a loop that ends here."
     },
     {
       "method": "GET",
@@ -2986,6 +4268,105 @@
       "transport": "http",
       "notes": "The one route that answers for all three caller kinds — a developer bearer, an app-user bearer and a server key — which is why the shape names each of `developer_id`, `app_user_id` and `server_key_id` and fills exactly one."
     },
+    {
+      "method": "POST",
+      "path": "/api/client/two-factor/verify",
+      "section": "client-auth",
+      "summary": "Answers a two-factor challenge with an authenticator or recovery code, and answers the session.",
+      "audience": "client",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": "client-two-factor-verify-request",
+      "response": "session-tokens",
+      "errors": [
+        "rate_limited",
+        "validation_error",
+        "invalid_code",
+        "token_spent"
+      ],
+      "transport": "http",
+      "notes": "The challenge is the one a sign-in step answered with `two_factor_required`; it lives five minutes and takes five wrong codes, after which it is `410 token_spent` and the sign-in starts over. A wrong code is `400 invalid_code` with `details.attempts_left`. **A code is accepted at most once**: the same authenticator code sent twice, even at the same moment, signs in exactly once. A recovery code is spent by its use and audited as `app_user.recovery_code_used`. Exactly one of `code` and `recovery_code`, or `400 validation_error`."
+    },
+    {
+      "method": "POST",
+      "path": "/api/client/two-factor/setup",
+      "section": "client-auth",
+      "summary": "Starts an authenticator setup and answers its secret and otpauth URL.",
+      "audience": "client",
+      "auth": "in_handler",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": "client-two-factor-setup-request",
+      "requestOptional": true,
+      "response": "two-factor-setup-response",
+      "errors": [
+        "rate_limited",
+        "validation_error",
+        "token_spent",
+        "unauthorized",
+        "target_state_conflict"
+      ],
+      "transport": "http",
+      "notes": "**Two ways in, decided in the handler.** During sign-in the body carries the `two_factor_setup_required` challenge, and that is the credential; from the app's own account settings the app user's bearer is, with no challenge and an empty or missing body. Neither is `401 unauthorized`, and a dead challenge is `410 token_spent`. `409 target_state_conflict` names `two_factor` with rule `off` when the app's policy is `off`. The secret is not in use until `POST /api/client/two-factor/setup/confirm` accepts a code from it; a second call replaces a pending secret, and an account that already has an authenticator keeps it until the new one is confirmed."
+    },
+    {
+      "method": "POST",
+      "path": "/api/client/two-factor/setup/confirm",
+      "section": "client-auth",
+      "summary": "Confirms the new authenticator with a code and answers the recovery codes and a session.",
+      "audience": "client",
+      "auth": "in_handler",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": "client-two-factor-setup-confirm-request",
+      "response": "client-two-factor-setup-confirm-response",
+      "errors": [
+        "rate_limited",
+        "validation_error",
+        "invalid_code",
+        "token_spent",
+        "unauthorized"
+      ],
+      "transport": "http",
+      "notes": "The same two ways in as `setup`. A code that does not match the pending secret is `400 invalid_code`; no pending setup, or a dead challenge, is `410 token_spent`. On success the authenticator is on, ten recovery codes are issued — shown this once, any earlier set void — and the answer carries a session: the one the sign-in was waiting for, or, from account settings, a fresh one while every other session of the account ends. Audited as `app_user.two_factor_enabled`."
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/client/two-factor",
+      "section": "client-auth",
+      "summary": "Turns the signed-in app user's authenticator off.",
+      "audience": "client",
+      "auth": "developer_or_client",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 204,
+      "params": [],
+      "query": null,
+      "request": "client-two-factor-disable-request",
+      "response": null,
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "forbidden",
+        "rate_limited",
+        "validation_error",
+        "invalid_code",
+        "target_state_conflict"
+      ],
+      "transport": "http",
+      "notes": "The app user's own door; a developer bearer or a server key is `401 unauthorized`, because the factor is the person's. A current code proves they still hold the authenticator: a stolen session alone cannot remove it. The authenticator and every recovery code go. `409 target_state_conflict` names `two_factor` with rule `required` while the app requires two-factor, and with rule `off` when there is none to remove. Audited as `app_user.two_factor_disabled`. The developer's support door is `DELETE /api/apps/:id/users/:userId/two-factor`."
+    },
     {
       "method": "GET",
       "path": "/api/client/providers",
@@ -3056,7 +4437,7 @@
         "rate_limited"
       ],
       "transport": "http",
-      "notes": "**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."
+      "notes": "**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. This route renders no page for an outcome. \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`. 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."
     },
     {
       "method": "POST",
@@ -4892,30 +6273,6 @@
       "transport": "http",
       "notes": "A window longer than `USAGE_WINDOW_MAX_DAYS` is refused naming the field, not silently capped: a caller who asked for more than the platform will answer is owed a refusal, not a shorter answer they will mistake for the whole picture. `from_day <= to_day` is a cross-field rule no JSON Schema can express and is enforced here. The window is echoed back."
     },
-    {
-      "method": "POST",
-      "path": "/api/feedback",
-      "section": "org",
-      "summary": "Sends a message from a developer to the people who build Fleetless.",
-      "audience": "developer",
-      "auth": "developer",
-      "rateLimited": true,
-      "ownerTier": false,
-      "status": 202,
-      "params": [],
-      "query": null,
-      "request": "feedback-request",
-      "response": "feedback-response",
-      "errors": [
-        "unauthorized",
-        "token_expired",
-        "token_revoked",
-        "validation_error",
-        "rate_limited"
-      ],
-      "transport": "http",
-      "notes": "The message is stored before any mail is tried, so `202` means it is kept whatever `mail` says: `sent`, `failed`, or `not_configured` when this cloud has no feedback address. At most 10 messages per developer per hour; the 11th answers `429 rate_limited` with `retry_after_ms`. Replies come by mail, to the sender's address."
-    },
     {
       "method": "POST",
       "path": "/api/bridge/assets",