@bongos/core 1.19.810 → 1.19.812

package/docs/api/openapi.json

@@ -229,6 +229,10 @@
       "name": "sessions",
       "description": "Endpoints under `/api/bongos/sessions`."
     },
+    {
+      "name": "specialities",
+      "description": "Endpoints under `/api/bongos/specialities`."
+    },
     {
       "name": "sso",
       "description": "Endpoints under `/api/bongos/sso`."
@@ -10246,6 +10250,44 @@
         ]
       }
     },
+    "/me/specialities": {
+      "get": {
+        "operationId": "get_me_specialities",
+        "tags": [
+          "me"
+        ],
+        "summary": "GET /me/specialities",
+        "description": "**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/specialities/routes/specialities.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetMeSpecialitiesResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/me/wandering": {
       "get": {
         "operationId": "get_me_wandering",
@@ -12032,6 +12074,69 @@
         ]
       }
     },
+    "/projects/{projectId}/specialities": {
+      "post": {
+        "operationId": "post_projects_projectId_specialities",
+        "tags": [
+          "projects"
+        ],
+        "summary": "POST /projects/:projectId/specialities",
+        "description": "POST /projects/:projectId/specialities — author one OWNED BY A PROJECT. The target is in the PATH, not the body, which is what makes it auditable: the gate below is membership of that same project, checked server-side.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/specialities/routes/specialities.js",
+        "parameters": [
+          {
+            "name": "projectId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `projectId`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostProjectsProjectIdSpecialitiesRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostProjectsProjectIdSpecialitiesResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/provisioning/control-plane": {
       "get": {
         "operationId": "get_provisioning_control_plane",
@@ -14711,61 +14816,58 @@
         ]
       }
     },
-    "/sso/activity/rollup": {
-      "post": {
-        "operationId": "post_sso_activity_rollup",
+    "/specialities": {
+      "get": {
+        "operationId": "get_specialities",
         "tags": [
-          "sso"
+          "specialities"
         ],
-        "summary": "POST /sso/activity/rollup",
-        "description": "POST /sso/activity/rollup — a federated instance reports a builder's activity snapshot (ADR 0141 §4). Server-to-server, client_id+client_secret auth. Keyed to the AUTHENTICATED client_id. Descriptive analytics for the Archon-only scouting view — never authority. rank: public — authenticated by client_id + client_secret, not a builder rank.\n\n**Rank:** `public` — No authentication — any caller.",
-        "x-rank": "public",
-        "x-source": "modules/platform-identity/routes/sso.js",
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/PostSsoActivityRollupRequest"
-              }
-            }
-          },
-          "x-validated": true
-        },
+        "summary": "GET /specialities",
+        "description": "GET /specialities — the catalogue this builder may see. `?discipline=` narrows it to one craft, which is what the settings surface asks for.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/specialities/routes/specialities.js",
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/PostSsoActivityRollupResponse"
+                  "$ref": "#/components/schemas/GetSpecialitiesResponse"
                 }
               }
             }
           },
           "400": {
-            "$ref": "#/components/responses/ValidationFailed"
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
           }
         },
-        "security": []
-      }
-    },
-    "/sso/applicant-profile": {
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
       "post": {
-        "operationId": "post_sso_applicant_profile",
+        "operationId": "post_specialities",
         "tags": [
-          "sso"
+          "specialities"
         ],
-        "summary": "POST /sso/applicant-profile",
-        "description": "POST /sso/applicant-profile — a federated instance resolves ONE applicant's profile view for its own reviewer queue, LIVE at render (privacy spec D7, task 1002972). Server-to-server, client_id+client_secret auth, like the two routes above. Answers { profile: null | { view:'public', … } | { view: 'sliver', … } } — the D7 rule, decided entirely inside ../applicant-profile.js. WHY A POST FOR A READ. The same reason /sso/activity/rollup is one: the credentials are in the body, and a client_secret in a query string lands in access logs and proxy history. Nothing is written. THE ECHO IS THE GATE, AND IT IS THE WHOLE SECURITY ARGUMENT (ADR 0205, security report 1000027). Client credentials prove WHICH PROJECT is calling and nothing about WHO the github_id is, so authenticating the caller is not enough: without a per-subject witness this route is a bulk disclosure oracle over every account on the platform, private ones included, readable by any registered project holding only its own secret. applicationBacksProfileRead demands a HUB-WRITTEN echo for exactly (this account, this client) inside the 30-day window — a row only the hub's own join relay creates, and only after the project accepted the relayed application. A project may therefore read the profile of someone who applied TO IT, and of nobody else. 404, never 403, when the echo is absent — the /scouting/:handle posture. A 403 would confirm that the github_id names a real account, which is the disclosure the whole rule exists to withhold. An account that exists but discloses nothing (provisional, terms never accepted) answers the SAME { profile: null } as one that consented but is simply not readable, so the caller cannot tell those apart either (ADR 0171 D4). NOT AUTHORITY (ADR 0016). The answer is descriptive; the project's own admission gate reads status='invited' and never this. rank: public — authenticated by client_id + client_secret, not a builder rank. The limiter runs BEFORE the client lookup, so a refused probe costs no DB work — the accountExistenceReadRateLimit posture.\n\n**Rank:** `public` — No authentication — any caller.",
-        "x-rank": "public",
-        "x-source": "modules/platform-identity/routes/sso.js",
+        "summary": "POST /specialities",
+        "description": "POST /specialities — author one for YOURSELF. The owner is req.builder and is never read from the body: a route whose path names no subject must act on the caller (tests/own_scope_guard.mjs). A PROJECT speciality names its project in the path instead — see POST /projects/:projectId/specialities below.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/specialities/routes/specialities.js",
         "requestBody": {
           "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/PostSsoApplicantProfileRequest"
+                "$ref": "#/components/schemas/PostSpecialitiesRequest"
               }
             }
           },
@@ -14777,55 +14879,105 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/PostSsoApplicantProfileResponse"
+                  "$ref": "#/components/schemas/PostSpecialitiesResponse"
                 }
               }
             }
           },
           "400": {
             "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
           }
         },
-        "security": []
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
       }
     },
-    "/sso/authorize": {
+    "/specialities/{id}": {
       "get": {
-        "operationId": "get_sso_authorize",
+        "operationId": "get_specialities_id",
         "tags": [
-          "sso"
+          "specialities"
+        ],
+        "summary": "GET /specialities/:id",
+        "description": "**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/specialities/routes/specialities.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
         ],
-        "summary": "GET /sso/authorize",
-        "description": "GET /sso/authorize?client_id=&redirect_uri=&state= — the browser authorize leg. rank: public — this is an authentication entry point, not an authorization surface. It is gated on a LIVE HUB SESSION (resolved inline via resolveSession; a missing session 302s to the hub's own web sign-in and returns here), NOT on a builder RANK. It mints identity-only codes.\n\n**Rank:** `public` — No authentication — any caller.",
-        "x-rank": "public",
-        "x-source": "modules/platform-identity/routes/sso.js",
         "responses": {
           "200": {
-            "description": "Success."
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetSpecialitiesIdResponse"
+                }
+              }
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           }
         },
-        "security": []
-      }
-    },
-    "/sso/device/poll": {
-      "post": {
-        "operationId": "post_sso_device_poll",
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "patch": {
+        "operationId": "patch_specialities_id",
         "tags": [
-          "sso"
+          "specialities"
+        ],
+        "summary": "PATCH /specialities/:id",
+        "description": "PATCH — owner only. `discipline` is absent from db.UPDATABLE on purpose: see the note there, and the adoption rows that carry a denormalised copy.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/specialities/routes/specialities.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
         ],
-        "summary": "POST /sso/device/poll",
-        "description": "POST /sso/device/poll — poll the hub device flow. On GitHub approval, upsert the platform account and mint an audience-scoped EdDSA assertion for the client that was BOUND at start (from the origin) — the poll takes NO client_id, so the CLI cannot influence the audience. Returns the SAME poll states as the core device flow, plus { state:'ok', assertion } on success. rank: public — the device_code (GitHub's) is the bearer; the assertion carries identity ONLY and is useless to anyone but the origin-bound client (aud-scoped).\n\n**Rank:** `public` — No authentication — any caller.",
-        "x-rank": "public",
-        "x-source": "modules/platform-identity/routes/sso.js",
         "requestBody": {
-          "required": true,
+          "required": false,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/PostSsoDevicePollRequest"
+                "$ref": "#/components/schemas/PatchSpecialitiesIdRequest"
               }
             }
           },
@@ -14833,31 +14985,460 @@
         },
         "responses": {
           "200": {
-            "description": "Success."
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PatchSpecialitiesIdResponse"
+                }
+              }
+            }
           },
           "400": {
             "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           }
         },
-        "security": []
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
       }
     },
-    "/sso/device/start": {
+    "/specialities/{id}/abandon": {
       "post": {
-        "operationId": "post_sso_device_start",
+        "operationId": "post_specialities_id_abandon",
         "tags": [
-          "sso"
+          "specialities"
         ],
-        "summary": "POST /sso/device/start",
-        "description": "POST /sso/device/start — begin CLI federation. The client is resolved from the USER-TYPED instance ORIGIN via the registry (getClientByOrigin) and BOUND to the device flow — the CLI never names the audience. This closes the confused-deputy where a malicious instance manifest could steer the mint at a victim client_id (ADR 0141 §1 security fix). Runs the GitHub device flow against the HUB's app and returns the codes. Identity is established as a platform ACCOUNT at poll time — never a hub-builder session (ADR 0141: identity federated, authority local). rank: public — an authentication entry point; the origin is public, and the poll's GitHub approval is the real gate.\n\n**Rank:** `public` — No authentication — any caller.",
-        "x-rank": "public",
-        "x-source": "modules/platform-identity/routes/sso.js",
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/PostSsoDeviceStartRequest"
+        "summary": "POST /specialities/:id/abandon",
+        "description": "**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/specialities/routes/specialities.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostSpecialitiesIdAbandonResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/specialities/{id}/adopt": {
+      "post": {
+        "operationId": "post_specialities_id_adopt",
+        "tags": [
+          "specialities"
+        ],
+        "summary": "POST /specialities/:id/adopt",
+        "description": "── adoption ──────────────────────────────────────────────────────────────\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/specialities/routes/specialities.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostSpecialitiesIdAdoptResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/specialities/{id}/documents": {
+      "get": {
+        "operationId": "get_specialities_id_documents",
+        "tags": [
+          "specialities"
+        ],
+        "summary": "GET /specialities/:id/documents",
+        "description": "**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/specialities/routes/specialities.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetSpecialitiesIdDocumentsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "post": {
+        "operationId": "post_specialities_id_documents",
+        "tags": [
+          "specialities"
+        ],
+        "summary": "POST /specialities/:id/documents",
+        "description": "── training (a): the owner's own documents ───────────────────────────────\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/specialities/routes/specialities.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostSpecialitiesIdDocumentsRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostSpecialitiesIdDocumentsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/specialities/{id}/documents/{docId}": {
+      "delete": {
+        "operationId": "delete_specialities_id_documents_docId",
+        "tags": [
+          "specialities"
+        ],
+        "summary": "DELETE /specialities/:id/documents/:docId",
+        "description": "**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/specialities/routes/specialities.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          },
+          {
+            "name": "docId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `docId`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeleteSpecialitiesIdDocumentsDocIdResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/sso/activity/rollup": {
+      "post": {
+        "operationId": "post_sso_activity_rollup",
+        "tags": [
+          "sso"
+        ],
+        "summary": "POST /sso/activity/rollup",
+        "description": "POST /sso/activity/rollup — a federated instance reports a builder's activity snapshot (ADR 0141 §4). Server-to-server, client_id+client_secret auth. Keyed to the AUTHENTICATED client_id. Descriptive analytics for the Archon-only scouting view — never authority. rank: public — authenticated by client_id + client_secret, not a builder rank.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/platform-identity/routes/sso.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostSsoActivityRollupRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostSsoActivityRollupResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          }
+        },
+        "security": []
+      }
+    },
+    "/sso/applicant-profile": {
+      "post": {
+        "operationId": "post_sso_applicant_profile",
+        "tags": [
+          "sso"
+        ],
+        "summary": "POST /sso/applicant-profile",
+        "description": "POST /sso/applicant-profile — a federated instance resolves ONE applicant's profile view for its own reviewer queue, LIVE at render (privacy spec D7, task 1002972). Server-to-server, client_id+client_secret auth, like the two routes above. Answers { profile: null | { view:'public', … } | { view: 'sliver', … } } — the D7 rule, decided entirely inside ../applicant-profile.js. WHY A POST FOR A READ. The same reason /sso/activity/rollup is one: the credentials are in the body, and a client_secret in a query string lands in access logs and proxy history. Nothing is written. THE ECHO IS THE GATE, AND IT IS THE WHOLE SECURITY ARGUMENT (ADR 0205, security report 1000027). Client credentials prove WHICH PROJECT is calling and nothing about WHO the github_id is, so authenticating the caller is not enough: without a per-subject witness this route is a bulk disclosure oracle over every account on the platform, private ones included, readable by any registered project holding only its own secret. applicationBacksProfileRead demands a HUB-WRITTEN echo for exactly (this account, this client) inside the 30-day window — a row only the hub's own join relay creates, and only after the project accepted the relayed application. A project may therefore read the profile of someone who applied TO IT, and of nobody else. 404, never 403, when the echo is absent — the /scouting/:handle posture. A 403 would confirm that the github_id names a real account, which is the disclosure the whole rule exists to withhold. An account that exists but discloses nothing (provisional, terms never accepted) answers the SAME { profile: null } as one that consented but is simply not readable, so the caller cannot tell those apart either (ADR 0171 D4). NOT AUTHORITY (ADR 0016). The answer is descriptive; the project's own admission gate reads status='invited' and never this. rank: public — authenticated by client_id + client_secret, not a builder rank. The limiter runs BEFORE the client lookup, so a refused probe costs no DB work — the accountExistenceReadRateLimit posture.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/platform-identity/routes/sso.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostSsoApplicantProfileRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostSsoApplicantProfileResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          }
+        },
+        "security": []
+      }
+    },
+    "/sso/authorize": {
+      "get": {
+        "operationId": "get_sso_authorize",
+        "tags": [
+          "sso"
+        ],
+        "summary": "GET /sso/authorize",
+        "description": "GET /sso/authorize?client_id=&redirect_uri=&state= — the browser authorize leg. rank: public — this is an authentication entry point, not an authorization surface. It is gated on a LIVE HUB SESSION (resolved inline via resolveSession; a missing session 302s to the hub's own web sign-in and returns here), NOT on a builder RANK. It mints identity-only codes.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/platform-identity/routes/sso.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
+    "/sso/device/poll": {
+      "post": {
+        "operationId": "post_sso_device_poll",
+        "tags": [
+          "sso"
+        ],
+        "summary": "POST /sso/device/poll",
+        "description": "POST /sso/device/poll — poll the hub device flow. On GitHub approval, upsert the platform account and mint an audience-scoped EdDSA assertion for the client that was BOUND at start (from the origin) — the poll takes NO client_id, so the CLI cannot influence the audience. Returns the SAME poll states as the core device flow, plus { state:'ok', assertion } on success. rank: public — the device_code (GitHub's) is the bearer; the assertion carries identity ONLY and is useless to anyone but the origin-bound client (aud-scoped).\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/platform-identity/routes/sso.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostSsoDevicePollRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          }
+        },
+        "security": []
+      }
+    },
+    "/sso/device/start": {
+      "post": {
+        "operationId": "post_sso_device_start",
+        "tags": [
+          "sso"
+        ],
+        "summary": "POST /sso/device/start",
+        "description": "POST /sso/device/start — begin CLI federation. The client is resolved from the USER-TYPED instance ORIGIN via the registry (getClientByOrigin) and BOUND to the device flow — the CLI never names the audience. This closes the confused-deputy where a malicious instance manifest could steer the mint at a victim client_id (ADR 0141 §1 security fix). Runs the GitHub device flow against the HUB's app and returns the codes. Identity is established as a platform ACCOUNT at poll time — never a hub-builder session (ADR 0141: identity federated, authority local). rank: public — an authentication entry point; the origin is public, and the poll's GitHub approval is the real gate.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/platform-identity/routes/sso.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostSsoDeviceStartRequest"
               }
             }
           },
@@ -17502,6 +18083,17 @@
           "path"
         ]
       },
+      "DeleteSpecialitiesIdDocumentsDocIdResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "ok"
+        ]
+      },
       "DeleteTasksIdCriteriaCriterionIdResponse": {
         "type": "object",
         "properties": {
@@ -18440,6 +19032,15 @@
           "known_sounds"
         ]
       },
+      "GetMeSpecialitiesResponse": {
+        "type": "object",
+        "properties": {
+          "adoptions": {}
+        },
+        "required": [
+          "adoptions"
+        ]
+      },
       "GetMemoryBfgBuildersBuilderIdFileResponse": {
         "type": "object",
         "properties": {
@@ -19080,6 +19681,33 @@
           "offset"
         ]
       },
+      "GetSpecialitiesIdDocumentsResponse": {
+        "type": "object",
+        "properties": {
+          "documents": {}
+        },
+        "required": [
+          "documents"
+        ]
+      },
+      "GetSpecialitiesIdResponse": {
+        "type": "object",
+        "properties": {
+          "speciality": {}
+        },
+        "required": [
+          "speciality"
+        ]
+      },
+      "GetSpecialitiesResponse": {
+        "type": "object",
+        "properties": {
+          "specialities": {}
+        },
+        "required": [
+          "specialities"
+        ]
+      },
       "GetSsoPubkeyResponse": {
         "type": "object",
         "properties": {
@@ -19858,6 +20486,38 @@
           "push"
         ]
       },
+      "PatchSpecialitiesIdRequest": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "summary": {
+            "type": "string"
+          },
+          "contract_md": {
+            "type": "string"
+          },
+          "visibility": {
+            "type": "string",
+            "maxLength": 16
+          },
+          "sellable": {
+            "type": "boolean"
+          }
+        },
+        "additionalProperties": false
+      },
+      "PatchSpecialitiesIdResponse": {
+        "type": "object",
+        "properties": {
+          "speciality": {}
+        },
+        "required": [
+          "speciality"
+        ]
+      },
       "PatchTaskRecommendationsIdRequest": {
         "type": "object",
         "properties": {
@@ -22396,6 +23056,46 @@
         ],
         "additionalProperties": false
       },
+      "PostProjectsProjectIdSpecialitiesRequest": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "discipline": {
+            "type": "string",
+            "maxLength": 64
+          },
+          "summary": {
+            "type": "string"
+          },
+          "contract_md": {
+            "type": "string"
+          },
+          "visibility": {
+            "type": "string",
+            "maxLength": 16
+          },
+          "sellable": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "name",
+          "discipline"
+        ],
+        "additionalProperties": false
+      },
+      "PostProjectsProjectIdSpecialitiesResponse": {
+        "type": "object",
+        "properties": {
+          "speciality": {}
+        },
+        "required": [
+          "speciality"
+        ]
+      },
       "PostProjectsRequest": {
         "type": "object",
         "properties": {
@@ -22993,6 +23693,100 @@
           "token_reward": {}
         }
       },
+      "PostSpecialitiesIdAbandonResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "was_active": {}
+        },
+        "required": [
+          "ok",
+          "was_active"
+        ]
+      },
+      "PostSpecialitiesIdAdoptResponse": {
+        "type": "object",
+        "properties": {
+          "adoption": {}
+        },
+        "required": [
+          "adoption"
+        ]
+      },
+      "PostSpecialitiesIdDocumentsRequest": {
+        "type": "object",
+        "properties": {
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "body_md": {
+            "type": "string",
+            "minLength": 1
+          },
+          "source": {
+            "type": "string",
+            "maxLength": 64
+          }
+        },
+        "required": [
+          "title",
+          "body_md"
+        ],
+        "additionalProperties": false
+      },
+      "PostSpecialitiesIdDocumentsResponse": {
+        "type": "object",
+        "properties": {
+          "skipped": {
+            "type": "boolean"
+          },
+          "reason": {},
+          "document": {}
+        }
+      },
+      "PostSpecialitiesRequest": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "discipline": {
+            "type": "string",
+            "maxLength": 64
+          },
+          "summary": {
+            "type": "string"
+          },
+          "contract_md": {
+            "type": "string"
+          },
+          "visibility": {
+            "type": "string",
+            "maxLength": 16
+          },
+          "sellable": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "name",
+          "discipline"
+        ],
+        "additionalProperties": false
+      },
+      "PostSpecialitiesResponse": {
+        "type": "object",
+        "properties": {
+          "speciality": {}
+        },
+        "required": [
+          "speciality"
+        ]
+      },
       "PostSsoActivityRollupRequest": {
         "type": "object",
         "properties": {
@@ -23988,9 +24782,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 379,
-  "x-schema-count": 415,
+  "x-endpoint-count": 390,
+  "x-schema-count": 430,
   "x-undocumented-bodies": 9,
-  "x-response-schemas": 282,
+  "x-response-schemas": 293,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }