@bongos/core 1.18.0 → 1.18.3

package/docs/api/openapi.json

@@ -93,6 +93,10 @@
       "name": "gate-approvals",
       "description": "Endpoints under `/api/bongos/gate-approvals`."
     },
+    {
+      "name": "github",
+      "description": "Endpoints under `/api/bongos/github`."
+    },
     {
       "name": "goals",
       "description": "Endpoints under `/api/bongos/goals`."
@@ -141,10 +145,18 @@
       "name": "modules",
       "description": "Endpoints under `/api/bongos/modules`."
     },
+    {
+      "name": "my-projects",
+      "description": "Endpoints under `/api/bongos/my-projects`."
+    },
     {
       "name": "override-requests",
       "description": "Endpoints under `/api/bongos/override-requests`."
     },
+    {
+      "name": "projects",
+      "description": "Endpoints under `/api/bongos/projects`."
+    },
     {
       "name": "provisioning",
       "description": "Endpoints under `/api/bongos/provisioning`."
@@ -153,6 +165,10 @@
       "name": "public",
       "description": "Endpoints under `/api/bongos/public`."
     },
+    {
+      "name": "scouting",
+      "description": "Endpoints under `/api/bongos/scouting`."
+    },
     {
       "name": "search",
       "description": "Endpoints under `/api/bongos/search`."
@@ -169,6 +185,10 @@
       "name": "sessions",
       "description": "Endpoints under `/api/bongos/sessions`."
     },
+    {
+      "name": "sso",
+      "description": "Endpoints under `/api/bongos/sso`."
+    },
     {
       "name": "tasks",
       "description": "Endpoints under `/api/bongos/tasks`."
@@ -662,6 +682,45 @@
         ]
       }
     },
+    "/auth/device/exchange": {
+      "post": {
+        "operationId": "post_auth_device_exchange",
+        "tags": [
+          "auth"
+        ],
+        "summary": "POST /auth/device/exchange",
+        "description": "POST /auth/device/exchange — CLI federation (ADR 0141 §1). The CLI ran the device flow against the HUB and got a hub-signed assertion; it presents it here. The instance verifies the Ed25519 signature OFFLINE against the provisioned hub public key (aud must equal this instance's client_id, unexpired), then runs the instance's OWN admission gate + upsertBuilder + createSession(source='cli') and returns the existing { token, builder }. Only reachable when auth.idp is set. rank: public — an auth-establishment endpoint; the hub-signed assertion IS the bearer and is cryptographically verified before any session is minted.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "src/bongos/routes/auth.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostAuthDeviceExchangeRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostAuthDeviceExchangeResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          }
+        },
+        "security": []
+      }
+    },
     "/auth/device/poll": {
       "post": {
         "operationId": "post_auth_device_poll",
@@ -3389,6 +3448,91 @@
         ]
       }
     },
+    "/github/repos": {
+      "get": {
+        "operationId": "get_github_repos",
+        "tags": [
+          "github"
+        ],
+        "summary": "GET /github/repos",
+        "description": "acts only on the caller's OWN GitHub identity (the token they granted). No rank gate beyond being a signed-in builder.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "src/bongos/routes/github.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetGithubReposResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "post": {
+        "operationId": "post_github_repos",
+        "tags": [
+          "github"
+        ],
+        "summary": "POST /github/repos",
+        "description": "creates a repo in the caller's OWN account.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "src/bongos/routes/github.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostGithubReposRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostGithubReposResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/goals": {
       "get": {
         "operationId": "get_goals",
@@ -6656,23 +6800,23 @@
         ]
       }
     },
-    "/override-requests": {
+    "/my-projects": {
       "get": {
-        "operationId": "get_override_requests",
+        "operationId": "get_my_projects",
         "tags": [
-          "override-requests"
+          "my-projects"
         ],
-        "summary": "GET /override-requests",
-        "description": "GET /override-requests?status=open — Archon queue. Status defaults to open; pass ?status=approved or ?status=denied for the resolved history. rank: archon — same gate as the audit log + Archon view.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
-        "x-source": "modules/lifecycle/routes/tasks.js",
+        "summary": "GET /my-projects",
+        "description": "the caller's OWN cross-project memberships (own data).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/my-projects.js",
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetOverrideRequestsResponse"
+                  "$ref": "#/components/schemas/GetMyProjectsResponse"
                 }
               }
             }
@@ -6694,44 +6838,78 @@
         ]
       }
     },
-    "/override-requests/{id}/decide": {
+    "/my-projects/invites": {
+      "get": {
+        "operationId": "get_my_projects_invites",
+        "tags": [
+          "my-projects"
+        ],
+        "summary": "GET /my-projects/invites",
+        "description": "the caller's OWN pending invitations (ADR 0141 §5).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/my-projects.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetMyProjectsInvitesResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/my-projects/invites/{clientId}/accept": {
       "post": {
-        "operationId": "post_override_requests_id_decide",
+        "operationId": "post_my_projects_invites_clientId_accept",
         "tags": [
-          "override-requests"
+          "my-projects"
         ],
-        "summary": "POST /override-requests/:id/decide",
-        "description": "POST /override-requests/:id/decide — body: { decision: 'approve'|'deny', note? } On approve, atomically flips the task completed→confirmed and awards the credits to the original requester (NOT the Archon). On deny, only the row updates; the task stays at completed and the builder must release or re-ship after fixing whatever the grader caught. rank: archon — grader-bypass authority; same gate as POST /tasks/:id/confirm.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
-        "x-source": "modules/lifecycle/routes/tasks.js",
+        "summary": "POST /my-projects/invites/:clientId/accept",
+        "description": "accept an invite (pending → builder) for the caller's OWN account.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/my-projects.js",
         "parameters": [
           {
-            "name": "id",
+            "name": "clientId",
             "in": "path",
             "required": true,
             "schema": {
               "type": "string"
             },
-            "description": "Path parameter `id`."
+            "description": "Path parameter `clientId`."
           }
         ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/PostOverrideRequestsIdDecideRequest"
-              }
-            }
-          },
-          "x-validated": true
-        },
         "responses": {
           "200": {
-            "description": "Success."
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostMyProjectsInvitesClientIdAcceptResponse"
+                }
+              }
+            }
           },
           "400": {
-            "$ref": "#/components/responses/ValidationFailed"
+            "$ref": "#/components/responses/BadRequest"
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
@@ -6750,23 +6928,34 @@
         ]
       }
     },
-    "/provisioning/fleet": {
-      "get": {
-        "operationId": "get_provisioning_fleet",
+    "/my-projects/invites/{clientId}/decline": {
+      "post": {
+        "operationId": "post_my_projects_invites_clientId_decline",
         "tags": [
-          "provisioning"
+          "my-projects"
+        ],
+        "summary": "POST /my-projects/invites/:clientId/decline",
+        "description": "decline an invite (delete the pending row) for the caller's OWN account.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/my-projects.js",
+        "parameters": [
+          {
+            "name": "clientId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `clientId`."
+          }
         ],
-        "summary": "GET /provisioning/fleet",
-        "description": "GET /provisioning/fleet — the full instance roster across all owners. rank: archon (exposes every owner's instance + cost; the /boxes precedent).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
-        "x-source": "modules/provisioning/routes/provisioning.js",
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetProvisioningFleetResponse"
+                  "$ref": "#/components/schemas/PostMyProjectsInvitesClientIdDeclineResponse"
                 }
               }
             }
@@ -6779,6 +6968,9 @@
           },
           "403": {
             "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           }
         },
         "security": [
@@ -6788,22 +6980,40 @@
         ]
       }
     },
-    "/provisioning/fleet/cost-ledger": {
-      "get": {
-        "operationId": "get_provisioning_fleet_cost_ledger",
+    "/my-projects/join": {
+      "post": {
+        "operationId": "post_my_projects_join",
         "tags": [
-          "provisioning"
+          "my-projects"
         ],
-        "summary": "GET /provisioning/fleet/cost-ledger",
-        "description": "GET /provisioning/fleet/cost-ledger — per-instance monthly estimate + total. rank: archon — cost oversight across the fleet (the /boxes/cost-ledger precedent). Declared among the archon routes (archon-first) for correct auditor classification.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
-        "x-source": "modules/provisioning/routes/provisioning.js",
+        "summary": "POST /my-projects/join",
+        "description": "request to join a project. The hub RELAYS the request to the target project's own admission surface (it does NOT admit locally — authority stays local). SSRF guard: only relay to an origin that is a REGISTERED, active client — never an arbitrary builder-supplied URL.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/my-projects.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostMyProjectsJoinRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
         "responses": {
           "200": {
-            "description": "Success."
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostMyProjectsJoinResponse"
+                }
+              }
+            }
           },
           "400": {
-            "$ref": "#/components/responses/BadRequest"
+            "$ref": "#/components/responses/ValidationFailed"
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
@@ -6819,100 +7029,75 @@
         ]
       }
     },
-    "/provisioning/github-app/callback": {
-      "get": {
-        "operationId": "get_provisioning_github_app_callback",
+    "/my-projects/{clientId}/leave": {
+      "post": {
+        "operationId": "post_my_projects_clientId_leave",
         "tags": [
-          "provisioning"
+          "my-projects"
         ],
-        "summary": "GET /provisioning/github-app/callback",
-        "description": "GET /provisioning/github-app/callback?code=&state= — GitHub redirects the owner's BROWSER here after they approve the App Manifest (task 2080, ADR 0133). It is a browser redirect with no session guaranteed, so it is PUBLIC — the unguessable, single-use, TTL'd `state` token (minted only for the signed-in owner and matched against provisioning_oauth_manifests) is the authorization, exactly as GitHub's own conversion `code` is \"the code IS the auth\". The web tier ONLY stores the code + flips status → 'code_received'; the control-plane runner (the sole token-holder) exchanges it for the client secret and places it in web.env. The secret NEVER touches the browser or the web tier. rank: public — no session, no mutation of authority, no secret revealed; a bad/expired/replayed state is a no-op error page.\n\n**Rank:** `public` — No authentication — any caller.",
-        "x-rank": "public",
-        "x-source": "modules/provisioning/routes/provisioning.js",
-        "responses": {
-          "200": {
-            "description": "Success."
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          }
-        },
-        "security": []
-      }
-    },
-    "/provisioning/github-app/status": {
-      "get": {
-        "operationId": "get_provisioning_github_app_status",
-        "tags": [
-          "provisioning"
-        ],
-        "summary": "GET /provisioning/github-app/status",
-        "description": "GET /provisioning/github-app/status?state=<> — the PUBLIC progress read the onboarding callback page polls (task 2096) to know when setup is done + where to send the owner. Same public-by-state model as the callback: the unguessable, single-use `state` token is the only key, and the response reveals only the manifest lifecycle status + the instance's own (already-public) domain — never a secret. Per-IP rate-limited because the page polls it every ~3s. `ready` is true iff the manifest reached 'done' (creds placed + /healthz verified) — the page then auto-redirects to https://<domain>. rank: public — no session, no mutation, no secret; an unknown state is a 404 no-op.\n\n**Rank:** `public` — No authentication — any caller.",
-        "x-rank": "public",
-        "x-source": "modules/provisioning/routes/provisioning.js",
-        "responses": {
-          "200": {
-            "description": "Success.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/GetProvisioningGithubAppStatusResponse"
-                }
-              }
-            }
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
+        "summary": "POST /my-projects/:clientId/leave",
+        "description": "leave a project from the caller's OWN membership list.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/my-projects.js",
+        "parameters": [
+          {
+            "name": "clientId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `clientId`."
           }
-        },
-        "security": []
-      }
-    },
-    "/provisioning/health": {
-      "get": {
-        "operationId": "get_provisioning_health",
-        "tags": [
-          "provisioning"
         ],
-        "summary": "GET /provisioning/health",
-        "description": "GET /provisioning/health — liveness + the core version this module mounted against. rank: public (a plain liveness read; no write, no sensitive data).\n\n**Rank:** `public` — No authentication — any caller.",
-        "x-rank": "public",
-        "x-source": "modules/provisioning/routes/provisioning.js",
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetProvisioningHealthResponse"
+                  "$ref": "#/components/schemas/PostMyProjectsClientIdLeaveResponse"
                 }
               }
             }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           }
         },
-        "security": []
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
       }
     },
-    "/provisioning/instances": {
+    "/override-requests": {
       "get": {
-        "operationId": "get_provisioning_instances",
+        "operationId": "get_override_requests",
         "tags": [
-          "provisioning"
+          "override-requests"
         ],
-        "summary": "GET /provisioning/instances",
-        "description": "GET /provisioning/instances — the caller's own instances + each open intent. rank: any authenticated builder (own resource read).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
-        "x-rank": "any-builder",
-        "x-source": "modules/provisioning/routes/provisioning.js",
+        "summary": "GET /override-requests",
+        "description": "GET /override-requests?status=open — Archon queue. Status defaults to open; pass ?status=approved or ?status=denied for the resolved history. rank: archon — same gate as the audit log + Archon view.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "modules/lifecycle/routes/tasks.js",
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetProvisioningInstancesResponse"
+                  "$ref": "#/components/schemas/GetOverrideRequestsResponse"
                 }
               }
             }
@@ -6932,22 +7117,35 @@
             "builderSession": []
           }
         ]
-      },
+      }
+    },
+    "/override-requests/{id}/decide": {
       "post": {
-        "operationId": "post_provisioning_instances",
+        "operationId": "post_override_requests_id_decide",
         "tags": [
-          "provisioning"
+          "override-requests"
+        ],
+        "summary": "POST /override-requests/:id/decide",
+        "description": "POST /override-requests/:id/decide — body: { decision: 'approve'|'deny', note? } On approve, atomically flips the task completed→confirmed and awards the credits to the original requester (NOT the Archon). On deny, only the row updates; the task stays at completed and the builder must release or re-ship after fixing whatever the grader caught. rank: archon — grader-bypass authority; same gate as POST /tasks/:id/confirm.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "modules/lifecycle/routes/tasks.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
         ],
-        "summary": "POST /provisioning/instances",
-        "description": "POST /provisioning/instances — request a new instance. rank: any authenticated builder (own resource). ENQUEUES a 'provision' intent + records the request; the runner (task P3) does the real standup. Idempotent on slug for the SAME owner (re-request returns the existing row); a slug owned by ANOTHER builder → 409. Body: { slug (required), target_ref?, hosting_shape? (co-tenant|dedicated), domain?, tier? }.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
-        "x-rank": "any-builder",
-        "x-source": "modules/provisioning/routes/provisioning.js",
         "requestBody": {
           "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/PostProvisioningInstancesRequest"
+                "$ref": "#/components/schemas/PostOverrideRequestsIdDecideRequest"
               }
             }
           },
@@ -6965,6 +7163,9 @@
           },
           "403": {
             "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           }
         },
         "security": [
@@ -6974,34 +7175,23 @@
         ]
       }
     },
-    "/provisioning/instances/{id}": {
+    "/projects": {
       "get": {
-        "operationId": "get_provisioning_instances_id",
+        "operationId": "get_projects",
         "tags": [
-          "provisioning"
-        ],
-        "summary": "GET /provisioning/instances/:id",
-        "description": "GET /provisioning/instances/:id — read one of the caller's own instances. rank: any authenticated builder (own resource). 404 when the id isn't the caller's (own-scoped; does not leak another owner's instance existence).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
-        "x-rank": "any-builder",
-        "x-source": "modules/provisioning/routes/provisioning.js",
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Path parameter `id`."
-          }
+          "projects"
         ],
+        "summary": "GET /projects",
+        "description": "the full curation list (includes unfeatured + owner attribution).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "modules/platform-identity/routes/projects.js",
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetProvisioningInstancesIdResponse"
+                  "$ref": "#/components/schemas/GetProjectsResponse"
                 }
               }
             }
@@ -7014,9 +7204,6 @@
           },
           "403": {
             "$ref": "#/components/responses/Forbidden"
-          },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
           }
         },
         "security": [
@@ -7024,51 +7211,46 @@
             "builderSession": []
           }
         ]
-      }
-    },
-    "/provisioning/instances/{id}/force-teardown": {
+      },
       "post": {
-        "operationId": "post_provisioning_instances_id_force_teardown",
+        "operationId": "post_projects",
         "tags": [
-          "provisioning"
+          "projects"
         ],
-        "summary": "POST /provisioning/instances/:id/force-teardown",
-        "description": "POST /provisioning/instances/:id/force-teardown — Archon tears down ANY instance. Trust-safe by the same mechanism as the owner's own teardown: it ENQUEUES a 'teardown' intent for the control-plane runner; the web tier never holds cloud tokens. rank: archon (acts on another owner's infrastructure). Declared among the archon routes (archon-first).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "summary": "POST /projects",
+        "description": "create / update a catalog entry (manual seed for hand-wired instances; federated projects auto-catalogue at registration).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
         "x-rank": "archon",
-        "x-source": "modules/provisioning/routes/provisioning.js",
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Path parameter `id`."
-          }
-        ],
+        "x-source": "modules/platform-identity/routes/projects.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostProjectsRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/PostProvisioningInstancesIdForceTeardownResponse"
+                  "$ref": "#/components/schemas/PostProjectsResponse"
                 }
               }
             }
           },
           "400": {
-            "$ref": "#/components/responses/BadRequest"
+            "$ref": "#/components/responses/ValidationFailed"
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
           "403": {
             "$ref": "#/components/responses/Forbidden"
-          },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
           }
         },
         "security": [
@@ -7078,33 +7260,50 @@
         ]
       }
     },
-    "/provisioning/instances/{id}/github-app": {
-      "post": {
-        "operationId": "post_provisioning_instances_id_github_app",
+    "/projects/featured": {
+      "get": {
+        "operationId": "get_projects_featured",
         "tags": [
-          "provisioning"
+          "projects"
         ],
-        "summary": "POST /provisioning/instances/:id/github-app",
-        "description": "POST /provisioning/instances/:id/github-app — mint a GitHub-App-Manifest onboarding link for the caller's OWN instance (task 2080, ADR 0133). rank: any authenticated builder (own resource). Returns the pre-filled manifest + the GitHub form-POST target (personal + org variants) + a one-time `state`; the browser POSTs the manifest to GitHub, the owner approves, and GitHub redirects back to the public callback below. The web tier only RECORDS the attempt (state token) — the control-plane runner does the token exchange + cred placement (trust boundary intact, ADR 0111 §2). Body: { account? ('personal'|'org') }.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
-        "x-rank": "any-builder",
-        "x-source": "modules/provisioning/routes/provisioning.js",
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Path parameter `id`."
+        "summary": "GET /projects/featured",
+        "description": "a curated public showcase; no auth by design.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/platform-identity/routes/projects.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetProjectsFeaturedResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
           }
+        },
+        "security": []
+      }
+    },
+    "/projects/invite": {
+      "post": {
+        "operationId": "post_projects_invite",
+        "tags": [
+          "projects"
         ],
+        "summary": "POST /projects/invite",
+        "description": "invite a builder into a project (ADR 0141 §5, task #1002115). Pre-seeds a 'pending' membership the invitee accepts from My Projects. V1 invites by github_login and requires the invitee to already have a platform account (they build on some project); inviting someone entirely new to the platform (GitHub-id resolution) is a follow-up.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "modules/platform-identity/routes/projects.js",
         "requestBody": {
-          "required": false,
+          "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/PostProvisioningInstancesIdGithubAppRequest"
+                "$ref": "#/components/schemas/PostProjectsInviteRequest"
               }
             }
           },
@@ -7112,14 +7311,7 @@
         },
         "responses": {
           "200": {
-            "description": "Success.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/PostProvisioningInstancesIdGithubAppResponse"
-                }
-              }
-            }
+            "description": "Success."
           },
           "400": {
             "$ref": "#/components/responses/ValidationFailed"
@@ -7129,9 +7321,6 @@
           },
           "403": {
             "$ref": "#/components/responses/Forbidden"
-          },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
           }
         },
         "security": [
@@ -7141,16 +7330,16 @@
         ]
       }
     },
-    "/provisioning/instances/{id}/teardown": {
-      "post": {
-        "operationId": "post_provisioning_instances_id_teardown",
+    "/projects/{id}/featured": {
+      "patch": {
+        "operationId": "patch_projects_id_featured",
         "tags": [
-          "provisioning"
+          "projects"
         ],
-        "summary": "POST /provisioning/instances/:id/teardown",
-        "description": "POST /provisioning/instances/:id/teardown — request teardown of the caller's OWN instance. rank: any authenticated builder (own resource). Enqueues a 'teardown' intent; the runner executes it (web tier holds no tokens). 404 when the id isn't the caller's; 409 when the instance isn't in a teardownable state.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
-        "x-rank": "any-builder",
-        "x-source": "modules/provisioning/routes/provisioning.js",
+        "summary": "PATCH /projects/:id/featured",
+        "description": "the feature / unfeature control (the ADR 0141 §5 curation gate).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "modules/platform-identity/routes/projects.js",
         "parameters": [
           {
             "name": "id",
@@ -7162,19 +7351,30 @@
             "description": "Path parameter `id`."
           }
         ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PatchProjectsIdFeaturedRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/PostProvisioningInstancesIdTeardownResponse"
+                  "$ref": "#/components/schemas/PatchProjectsIdFeaturedResponse"
                 }
               }
             }
           },
           "400": {
-            "$ref": "#/components/responses/BadRequest"
+            "$ref": "#/components/responses/ValidationFailed"
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
@@ -7193,15 +7393,15 @@
         ]
       }
     },
-    "/provisioning/onboard-plan": {
+    "/provisioning/fleet": {
       "get": {
-        "operationId": "get_provisioning_onboard_plan",
+        "operationId": "get_provisioning_fleet",
         "tags": [
           "provisioning"
         ],
-        "summary": "GET /provisioning/onboard-plan",
-        "description": "GET /provisioning/onboard-plan?mode=greenfield|adopt — the CANONICAL onboarding step sequence (task 2085; goal 35 / criterion 165: \"the canonical step sequence is the source of truth; skill/CLI/hall are forms over it\"). The branded /create page + the hall wizard fetch it so their human-steps checklist can't drift from the CLI's (scripts/gds/onboard.js reads the same modules/provisioning/onboard-plan.js). rank: public — the signed-out /create landing page reads it; it is the same public runbook the /new-project skill documents (no write, no secret).\n\n**Rank:** `public` — No authentication — any caller.",
-        "x-rank": "public",
+        "summary": "GET /provisioning/fleet",
+        "description": "GET /provisioning/fleet — the full instance roster across all owners. rank: archon (exposes every owner's instance + cost; the /boxes precedent).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
         "x-source": "modules/provisioning/routes/provisioning.js",
         "responses": {
           "200": {
@@ -7209,7 +7409,450 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetProvisioningOnboardPlanResponse"
+                  "$ref": "#/components/schemas/GetProvisioningFleetResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/provisioning/fleet/cost-ledger": {
+      "get": {
+        "operationId": "get_provisioning_fleet_cost_ledger",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/fleet/cost-ledger",
+        "description": "GET /provisioning/fleet/cost-ledger — per-instance monthly estimate + total. rank: archon — cost oversight across the fleet (the /boxes/cost-ledger precedent). Declared among the archon routes (archon-first) for correct auditor classification.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "modules/provisioning/routes/provisioning.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/provisioning/github-app/callback": {
+      "get": {
+        "operationId": "get_provisioning_github_app_callback",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/github-app/callback",
+        "description": "GET /provisioning/github-app/callback?code=&state= — GitHub redirects the owner's BROWSER here after they approve the App Manifest (task 2080, ADR 0133). It is a browser redirect with no session guaranteed, so it is PUBLIC — the unguessable, single-use, TTL'd `state` token (minted only for the signed-in owner and matched against provisioning_oauth_manifests) is the authorization, exactly as GitHub's own conversion `code` is \"the code IS the auth\". The web tier ONLY stores the code + flips status → 'code_received'; the control-plane runner (the sole token-holder) exchanges it for the client secret and places it in web.env. The secret NEVER touches the browser or the web tier. rank: public — no session, no mutation of authority, no secret revealed; a bad/expired/replayed state is a no-op error page.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/provisioning/routes/provisioning.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
+    "/provisioning/github-app/status": {
+      "get": {
+        "operationId": "get_provisioning_github_app_status",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/github-app/status",
+        "description": "GET /provisioning/github-app/status?state=<> — the PUBLIC progress read the onboarding callback page polls (task 2096) to know when setup is done + where to send the owner. Same public-by-state model as the callback: the unguessable, single-use `state` token is the only key, and the response reveals only the manifest lifecycle status + the instance's own (already-public) domain — never a secret. Per-IP rate-limited because the page polls it every ~3s. `ready` is true iff the manifest reached 'done' (creds placed + /healthz verified) — the page then auto-redirects to https://<domain>. rank: public — no session, no mutation, no secret; an unknown state is a 404 no-op.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/provisioning/routes/provisioning.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetProvisioningGithubAppStatusResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
+    "/provisioning/health": {
+      "get": {
+        "operationId": "get_provisioning_health",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/health",
+        "description": "GET /provisioning/health — liveness + the core version this module mounted against. rank: public (a plain liveness read; no write, no sensitive data).\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/provisioning/routes/provisioning.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetProvisioningHealthResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
+    "/provisioning/instances": {
+      "get": {
+        "operationId": "get_provisioning_instances",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/instances",
+        "description": "GET /provisioning/instances — the caller's own instances + each open intent. rank: any authenticated builder (own resource read).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/provisioning/routes/provisioning.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetProvisioningInstancesResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "post": {
+        "operationId": "post_provisioning_instances",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "POST /provisioning/instances",
+        "description": "POST /provisioning/instances — request a new instance. rank: any authenticated builder (own resource). ENQUEUES a 'provision' intent + records the request; the runner (task P3) does the real standup. Idempotent on slug for the SAME owner (re-request returns the existing row); a slug owned by ANOTHER builder → 409. Body: { slug (required), target_ref?, hosting_shape? (co-tenant|dedicated), domain?, tier? }.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/provisioning/routes/provisioning.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostProvisioningInstancesRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/provisioning/instances/{id}": {
+      "get": {
+        "operationId": "get_provisioning_instances_id",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/instances/:id",
+        "description": "GET /provisioning/instances/:id — read one of the caller's own instances. rank: any authenticated builder (own resource). 404 when the id isn't the caller's (own-scoped; does not leak another owner's instance existence).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/provisioning/routes/provisioning.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/GetProvisioningInstancesIdResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/provisioning/instances/{id}/force-teardown": {
+      "post": {
+        "operationId": "post_provisioning_instances_id_force_teardown",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "POST /provisioning/instances/:id/force-teardown",
+        "description": "POST /provisioning/instances/:id/force-teardown — Archon tears down ANY instance. Trust-safe by the same mechanism as the owner's own teardown: it ENQUEUES a 'teardown' intent for the control-plane runner; the web tier never holds cloud tokens. rank: archon (acts on another owner's infrastructure). Declared among the archon routes (archon-first).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "modules/provisioning/routes/provisioning.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/PostProvisioningInstancesIdForceTeardownResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/provisioning/instances/{id}/github-app": {
+      "post": {
+        "operationId": "post_provisioning_instances_id_github_app",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "POST /provisioning/instances/:id/github-app",
+        "description": "POST /provisioning/instances/:id/github-app — mint a GitHub-App-Manifest onboarding link for the caller's OWN instance (task 2080, ADR 0133). rank: any authenticated builder (own resource). Returns the pre-filled manifest + the GitHub form-POST target (personal + org variants) + a one-time `state`; the browser POSTs the manifest to GitHub, the owner approves, and GitHub redirects back to the public callback below. The web tier only RECORDS the attempt (state token) — the control-plane runner does the token exchange + cred placement (trust boundary intact, ADR 0111 §2). Body: { account? ('personal'|'org') }.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/provisioning/routes/provisioning.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostProvisioningInstancesIdGithubAppRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostProvisioningInstancesIdGithubAppResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/provisioning/instances/{id}/teardown": {
+      "post": {
+        "operationId": "post_provisioning_instances_id_teardown",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "POST /provisioning/instances/:id/teardown",
+        "description": "POST /provisioning/instances/:id/teardown — request teardown of the caller's OWN instance. rank: any authenticated builder (own resource). Enqueues a 'teardown' intent; the runner executes it (web tier holds no tokens). 404 when the id isn't the caller's; 409 when the instance isn't in a teardownable state.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/provisioning/routes/provisioning.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/PostProvisioningInstancesIdTeardownResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/provisioning/onboard-plan": {
+      "get": {
+        "operationId": "get_provisioning_onboard_plan",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/onboard-plan",
+        "description": "GET /provisioning/onboard-plan?mode=greenfield|adopt — the CANONICAL onboarding step sequence (task 2085; goal 35 / criterion 165: \"the canonical step sequence is the source of truth; skill/CLI/hall are forms over it\"). The branded /create page + the hall wizard fetch it so their human-steps checklist can't drift from the CLI's (scripts/gds/onboard.js reads the same modules/provisioning/onboard-plan.js). rank: public — the signed-out /create landing page reads it; it is the same public runbook the /new-project skill documents (no write, no secret).\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/provisioning/routes/provisioning.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetProvisioningOnboardPlanResponse"
                 }
               }
             }
@@ -7687,88 +8330,354 @@
               }
             }
           },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
-          }
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": []
+      }
+    },
+    "/public/uptime": {
+      "get": {
+        "operationId": "get_public_uptime",
+        "tags": [
+          "public"
+        ],
+        "summary": "GET /public/uptime",
+        "description": "Uptime: current status + 90-day history bucketed by hour. Returns per-service: current_status, uptime_pct_90d, history (array of { hour: ISO string, up: n, total: n } for the last 90*24 hours). rank: public — uptime feed (90-day hourly history).\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "src/bongos/routes/public.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetPublicUptimeResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
+    "/public/versions": {
+      "get": {
+        "operationId": "get_public_versions",
+        "tags": [
+          "public"
+        ],
+        "summary": "GET /public/versions",
+        "description": "read-only surface for status.amazonprimea.com.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "src/bongos/routes/public.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetPublicVersionsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
+    "/scouting": {
+      "get": {
+        "operationId": "get_scouting",
+        "tags": [
+          "scouting"
+        ],
+        "summary": "GET /scouting",
+        "description": "the internal talent directory across every project. The Archon gate here is the load-bearing protection (\"NOT shown to builders\"): a non-Archon is 403'd before any cross-builder data is read.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "modules/platform-identity/routes/scouting.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetScoutingResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/search": {
+      "post": {
+        "operationId": "post_search",
+        "tags": [
+          "search"
+        ],
+        "summary": "POST /search",
+        "description": "POST /search — two modes (ADR 0095 C1 / task 1658, progressive disclosure): 1. SUMMARY (default): body { q: string, limit?: 1..50, source_kind? }. Returns the ranked compact layer — each hit carries a snippet plus `snippet_tokens` (what you already see) and `full_tokens` (what a full expansion would COST), so the caller sees the price before paying it. 2. EXPAND: body { expand: <chunkId> } (with q optional). Returns that one chunk's FULL body + `body_tokens`, scoped exactly like search (rank + owner from the session), so expand can't widen visibility. Both shapes stay backward-compatible: the old { q } request still returns { query, count, results } — the new per-hit fields are additive. Single-line opener so the deterministic route-rank auditor classifies the chain (requireBuilder → 'any-builder') — ADR 0016 / route-rank-check.js.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/memory/routes/search.js",
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostSearchRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostSearchResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/search/mark": {
+      "post": {
+        "operationId": "post_search_mark",
+        "tags": [
+          "search"
+        ],
+        "summary": "POST /search/mark",
+        "description": "POST /search/mark — the write half of the memory-usefulness feedback loop (ADR 0095 C3, task 1660). Body { chunk_id: int, useful?: bool }. Records that a recalled chunk did (useful=true, the default) or did NOT (useful=false) help, so the ranker lifts the useful and fades the dead-end. SCOPING (ADR 0016): the caller's id + rank come ONLY from the session, never the body — searchChunks-equivalent scope is re-applied in the UPDATE WHERE, so a chunk the caller couldn't have seen can't be voted on (→ updated:false). Single-line opener so the route-rank auditor classifies the chain.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/memory/routes/search.js",
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostSearchMarkRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/security/docs": {
+      "get": {
+        "operationId": "get_security_docs",
+        "tags": [
+          "security"
+        ],
+        "summary": "GET /security/docs",
+        "description": "GET /api/gds/security/docs — list doc METADATA (no content). rank: archon — index of exploit-detail engagement reports.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "src/bongos/routes/security.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetSecurityDocsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "post": {
+        "operationId": "post_security_docs",
+        "tags": [
+          "security"
+        ],
+        "summary": "POST /security/docs",
+        "description": "POST /api/gds/security/docs — upsert a doc by slug. The director uploads each dated engagement report here after deploy. Body: { slug, title, content_md }. content_md uses a large explicit cap (full reports), NOT the small LIMITS.DESCRIPTION. Returns 201 + the row. rank: archon — writes exploit-detail report bodies.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "src/bongos/routes/security.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostSecurityDocsRequest"
+              }
+            }
+          },
+          "x-validated": true
         },
-        "security": []
-      }
-    },
-    "/public/uptime": {
-      "get": {
-        "operationId": "get_public_uptime",
-        "tags": [
-          "public"
-        ],
-        "summary": "GET /public/uptime",
-        "description": "Uptime: current status + 90-day history bucketed by hour. Returns per-service: current_status, uptime_pct_90d, history (array of { hour: ISO string, up: n, total: n } for the last 90*24 hours). rank: public — uptime feed (90-day hourly history).\n\n**Rank:** `public` — No authentication — any caller.",
-        "x-rank": "public",
-        "x-source": "src/bongos/routes/public.js",
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetPublicUptimeResponse"
+                  "$ref": "#/components/schemas/PostSecurityDocsResponse"
                 }
               }
             }
           },
           "400": {
-            "$ref": "#/components/responses/BadRequest"
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
           }
         },
-        "security": []
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
       }
     },
-    "/public/versions": {
+    "/security/docs/{slug}": {
       "get": {
-        "operationId": "get_public_versions",
+        "operationId": "get_security_docs_slug",
         "tags": [
-          "public"
+          "security"
+        ],
+        "summary": "GET /security/docs/:slug",
+        "description": "GET /api/gds/security/docs/:slug — one doc WITH content, or 404. rank: archon — reads the full exploit-detail report body.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "x-rank": "archon",
+        "x-source": "src/bongos/routes/security.js",
+        "parameters": [
+          {
+            "name": "slug",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `slug`."
+          }
         ],
-        "summary": "GET /public/versions",
-        "description": "read-only surface for status.amazonprimea.com.\n\n**Rank:** `public` — No authentication — any caller.",
-        "x-rank": "public",
-        "x-source": "src/bongos/routes/public.js",
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetPublicVersionsResponse"
+                  "$ref": "#/components/schemas/GetSecurityDocsSlugResponse"
                 }
               }
             }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           }
         },
-        "security": []
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
       }
     },
-    "/search": {
+    "/session/optimize": {
       "post": {
-        "operationId": "post_search",
+        "operationId": "post_session_optimize",
         "tags": [
-          "search"
+          "session"
         ],
-        "summary": "POST /search",
-        "description": "POST /search — two modes (ADR 0095 C1 / task 1658, progressive disclosure): 1. SUMMARY (default): body { q: string, limit?: 1..50, source_kind? }. Returns the ranked compact layer — each hit carries a snippet plus `snippet_tokens` (what you already see) and `full_tokens` (what a full expansion would COST), so the caller sees the price before paying it. 2. EXPAND: body { expand: <chunkId> } (with q optional). Returns that one chunk's FULL body + `body_tokens`, scoped exactly like search (rank + owner from the session), so expand can't widen visibility. Both shapes stay backward-compatible: the old { q } request still returns { query, count, results } — the new per-hit fields are additive. Single-line opener so the deterministic route-rank auditor classifies the chain (requireBuilder → 'any-builder') — ADR 0016 / route-rank-check.js.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "summary": "POST /session/optimize",
+        "description": "pick own next work; the optimizer reads/recommends only.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
         "x-rank": "any-builder",
-        "x-source": "modules/memory/routes/search.js",
+        "x-source": "src/bongos/routes/optimizer.js",
         "requestBody": {
           "required": false,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/PostSearchRequest"
+                "$ref": "#/components/schemas/PostSessionOptimizeRequest"
               }
             }
           },
@@ -7776,14 +8685,7 @@
         },
         "responses": {
           "200": {
-            "description": "Success.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/PostSearchResponse"
-                }
-              }
-            }
+            "description": "Success."
           },
           "400": {
             "$ref": "#/components/responses/ValidationFailed"
@@ -7802,22 +8704,22 @@
         ]
       }
     },
-    "/search/mark": {
+    "/sessions": {
       "post": {
-        "operationId": "post_search_mark",
+        "operationId": "post_sessions",
         "tags": [
-          "search"
+          "sessions"
         ],
-        "summary": "POST /search/mark",
-        "description": "POST /search/mark — the write half of the memory-usefulness feedback loop (ADR 0095 C3, task 1660). Body { chunk_id: int, useful?: bool }. Records that a recalled chunk did (useful=true, the default) or did NOT (useful=false) help, so the ranker lifts the useful and fades the dead-end. SCOPING (ADR 0016): the caller's id + rank come ONLY from the session, never the body — searchChunks-equivalent scope is re-applied in the UPDATE WHERE, so a chunk the caller couldn't have seen can't be voted on (→ updated:false). Single-line opener so the route-rank auditor classifies the chain.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "summary": "POST /sessions",
+        "description": "upload your OWN session digest. Owner is forced to the authenticated caller; the body cannot attribute a record to another builder.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
         "x-rank": "any-builder",
-        "x-source": "modules/memory/routes/search.js",
+        "x-source": "modules/sessions/routes/sessions.js",
         "requestBody": {
-          "required": false,
+          "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/PostSearchMarkRequest"
+                "$ref": "#/components/schemas/PostSessionsRequest"
               }
             }
           },
@@ -7825,7 +8727,14 @@
         },
         "responses": {
           "200": {
-            "description": "Success."
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostSessionsResponse"
+                }
+              }
+            }
           },
           "400": {
             "$ref": "#/components/responses/ValidationFailed"
@@ -7844,23 +8753,23 @@
         ]
       }
     },
-    "/security/docs": {
+    "/sessions/mine": {
       "get": {
-        "operationId": "get_security_docs",
+        "operationId": "get_sessions_mine",
         "tags": [
-          "security"
+          "sessions"
         ],
-        "summary": "GET /security/docs",
-        "description": "GET /api/gds/security/docs — list doc METADATA (no content). rank: archon — index of exploit-detail engagement reports.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
-        "x-source": "src/bongos/routes/security.js",
+        "summary": "GET /sessions/mine",
+        "description": "your OWN sessions (self-serve; no audit needed).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/sessions/routes/sessions.js",
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetSecurityDocsResponse"
+                  "$ref": "#/components/schemas/GetSessionsMineResponse"
                 }
               }
             }
@@ -7880,40 +8789,31 @@
             "builderSession": []
           }
         ]
-      },
-      "post": {
-        "operationId": "post_security_docs",
+      }
+    },
+    "/sessions/search": {
+      "get": {
+        "operationId": "get_sessions_search",
         "tags": [
-          "security"
+          "sessions"
         ],
-        "summary": "POST /security/docs",
-        "description": "POST /api/gds/security/docs — upsert a doc by slug. The director uploads each dated engagement report here after deploy. Body: { slug, title, content_md }. content_md uses a large explicit cap (full reports), NOT the small LIMITS.DESCRIPTION. Returns 201 + the row. rank: archon — writes exploit-detail report bodies.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "summary": "GET /sessions/search",
+        "description": "cross-builder corpus search (BFG-principal posture until 6C.1).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
         "x-rank": "archon",
-        "x-source": "src/bongos/routes/security.js",
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/PostSecurityDocsRequest"
-              }
-            }
-          },
-          "x-validated": true
-        },
+        "x-source": "modules/sessions/routes/sessions.js",
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/PostSecurityDocsResponse"
+                  "$ref": "#/components/schemas/GetSessionsSearchResponse"
                 }
               }
             }
           },
           "400": {
-            "$ref": "#/components/responses/ValidationFailed"
+            "$ref": "#/components/responses/BadRequest"
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
@@ -7929,25 +8829,25 @@
         ]
       }
     },
-    "/security/docs/{slug}": {
+    "/sessions/{id}": {
       "get": {
-        "operationId": "get_security_docs_slug",
+        "operationId": "get_sessions_id",
         "tags": [
-          "security"
+          "sessions"
         ],
-        "summary": "GET /security/docs/:slug",
-        "description": "GET /api/gds/security/docs/:slug — one doc WITH content, or 404. rank: archon — reads the full exploit-detail report body.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
-        "x-source": "src/bongos/routes/security.js",
+        "summary": "GET /sessions/:id",
+        "description": "own session full detail (deep-dive); cross-builder fetch requires Archon + a fail-closed audit row (BFG-principal posture until 6C.1).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/sessions/routes/sessions.js",
         "parameters": [
           {
-            "name": "slug",
+            "name": "id",
             "in": "path",
             "required": true,
             "schema": {
               "type": "string"
             },
-            "description": "Path parameter `slug`."
+            "description": "Path parameter `id`."
           }
         ],
         "responses": {
@@ -7956,7 +8856,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetSecurityDocsSlugResponse"
+                  "$ref": "#/components/schemas/GetSessionsIdResponse"
                 }
               }
             }
@@ -7970,33 +8870,93 @@
           "403": {
             "$ref": "#/components/responses/Forbidden"
           },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
+          "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/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": [
-          {
-            "builderSession": []
-          }
-        ]
+        "security": []
       }
     },
-    "/session/optimize": {
+    "/sso/device/poll": {
       "post": {
-        "operationId": "post_session_optimize",
+        "operationId": "post_sso_device_poll",
         "tags": [
-          "session"
+          "sso"
         ],
-        "summary": "POST /session/optimize",
-        "description": "pick own next work; the optimizer reads/recommends only.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
-        "x-rank": "any-builder",
-        "x-source": "src/bongos/routes/optimizer.js",
+        "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": false,
+          "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/PostSessionOptimizeRequest"
+                "$ref": "#/components/schemas/PostSsoDevicePollRequest"
               }
             }
           },
@@ -8008,37 +8968,27 @@
           },
           "400": {
             "$ref": "#/components/responses/ValidationFailed"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "403": {
-            "$ref": "#/components/responses/Forbidden"
           }
         },
-        "security": [
-          {
-            "builderSession": []
-          }
-        ]
+        "security": []
       }
     },
-    "/sessions": {
+    "/sso/device/start": {
       "post": {
-        "operationId": "post_sessions",
+        "operationId": "post_sso_device_start",
         "tags": [
-          "sessions"
+          "sso"
         ],
-        "summary": "POST /sessions",
-        "description": "upload your OWN session digest. Owner is forced to the authenticated caller; the body cannot attribute a record to another builder.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
-        "x-rank": "any-builder",
-        "x-source": "modules/sessions/routes/sessions.js",
+        "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/PostSessionsRequest"
+                "$ref": "#/components/schemas/PostSsoDeviceStartRequest"
               }
             }
           },
@@ -8046,158 +8996,119 @@
         },
         "responses": {
           "200": {
-            "description": "Success.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/PostSessionsResponse"
-                }
-              }
-            }
+            "description": "Success."
           },
           "400": {
             "$ref": "#/components/responses/ValidationFailed"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "403": {
-            "$ref": "#/components/responses/Forbidden"
           }
         },
-        "security": [
-          {
-            "builderSession": []
-          }
-        ]
+        "security": []
       }
     },
-    "/sessions/mine": {
-      "get": {
-        "operationId": "get_sessions_mine",
+    "/sso/membership/check-in": {
+      "post": {
+        "operationId": "post_sso_membership_check_in",
         "tags": [
-          "sessions"
+          "sso"
         ],
-        "summary": "GET /sessions/mine",
-        "description": "your OWN sessions (self-serve; no audit needed).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
-        "x-rank": "any-builder",
-        "x-source": "modules/sessions/routes/sessions.js",
+        "summary": "POST /sso/membership/check-in",
+        "description": "POST /sso/membership/check-in — a federated instance reports, on every sign-in, that a builder builds on its project (ADR 0141 §3). Server-to-server, authed by client_id + client_secret (same constant-time check as /sso/token). Upserts the account (so a CLI-only builder still appears in My Projects) + the membership with a COARSE role. The client_id is taken from the AUTHENTICATED client — the caller cannot report membership for a project it doesn't hold the secret for. 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/PostSsoMembershipCheckInRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetSessionsMineResponse"
+                  "$ref": "#/components/schemas/PostSsoMembershipCheckInResponse"
                 }
               }
             }
           },
           "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "403": {
-            "$ref": "#/components/responses/Forbidden"
+            "$ref": "#/components/responses/ValidationFailed"
           }
         },
-        "security": [
-          {
-            "builderSession": []
-          }
-        ]
+        "security": []
       }
     },
-    "/sessions/search": {
+    "/sso/pubkey": {
       "get": {
-        "operationId": "get_sessions_search",
+        "operationId": "get_sso_pubkey",
         "tags": [
-          "sessions"
+          "sso"
         ],
-        "summary": "GET /sessions/search",
-        "description": "cross-builder corpus search (BFG-principal posture until 6C.1).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
-        "x-source": "modules/sessions/routes/sessions.js",
+        "summary": "GET /sso/pubkey",
+        "description": "GET /sso/pubkey — the hub's Ed25519 assertion-verification key (public). An instance provisioned WITHOUT the key in env can fetch it here; the value is public by design (it only VERIFIES assertions, never signs). rank: public — a public key is not a secret; no auth needed.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/platform-identity/routes/sso.js",
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetSessionsSearchResponse"
+                  "$ref": "#/components/schemas/GetSsoPubkeyResponse"
                 }
               }
             }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "403": {
-            "$ref": "#/components/responses/Forbidden"
           }
         },
-        "security": [
-          {
-            "builderSession": []
-          }
-        ]
+        "security": []
       }
     },
-    "/sessions/{id}": {
-      "get": {
-        "operationId": "get_sessions_id",
+    "/sso/token": {
+      "post": {
+        "operationId": "post_sso_token",
         "tags": [
-          "sessions"
-        ],
-        "summary": "GET /sessions/:id",
-        "description": "own session full detail (deep-dive); cross-builder fetch requires Archon + a fail-closed audit row (BFG-principal posture until 6C.1).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
-        "x-rank": "any-builder",
-        "x-source": "modules/sessions/routes/sessions.js",
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Path parameter `id`."
-          }
+          "sso"
         ],
+        "summary": "POST /sso/token",
+        "description": "POST /sso/token — server-to-server code redemption. rank: public — authenticated by client_id + client_secret (constant-time hash compare in clientSecretValid), NOT a builder session/rank. This is the confidential-client leg; the instance calls it from its server, never the browser. Returns IDENTITY ONLY (github_id, login, display_name, avatar_url).\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/PostSsoTokenRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetSessionsIdResponse"
+                  "$ref": "#/components/schemas/PostSsoTokenResponse"
                 }
               }
             }
           },
           "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "403": {
-            "$ref": "#/components/responses/Forbidden"
-          },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
+            "$ref": "#/components/responses/ValidationFailed"
           }
         },
-        "security": [
-          {
-            "builderSession": []
-          }
-        ]
+        "security": []
       }
     },
     "/tasks": {
@@ -10229,6 +11140,15 @@
           "count"
         ]
       },
+      "GetGithubReposResponse": {
+        "type": "object",
+        "properties": {
+          "repos": {}
+        },
+        "required": [
+          "repos"
+        ]
+      },
       "GetGoalsIdConflictsResponse": {
         "type": "object",
         "properties": {
@@ -10540,6 +11460,26 @@
           "submissions"
         ]
       },
+      "GetMyProjectsInvitesResponse": {
+        "type": "object",
+        "properties": {
+          "invites": {}
+        },
+        "required": [
+          "invites"
+        ]
+      },
+      "GetMyProjectsResponse": {
+        "type": "object",
+        "properties": {
+          "owned": {},
+          "building": {}
+        },
+        "required": [
+          "owned",
+          "building"
+        ]
+      },
       "GetOverrideRequestsResponse": {
         "type": "object",
         "properties": {
@@ -10549,6 +11489,24 @@
           "requests"
         ]
       },
+      "GetProjectsFeaturedResponse": {
+        "type": "object",
+        "properties": {
+          "projects": {}
+        },
+        "required": [
+          "projects"
+        ]
+      },
+      "GetProjectsResponse": {
+        "type": "object",
+        "properties": {
+          "projects": {}
+        },
+        "required": [
+          "projects"
+        ]
+      },
       "GetProvisioningFleetResponse": {
         "type": "object",
         "properties": {
@@ -10776,6 +11734,15 @@
           "page"
         ]
       },
+      "GetScoutingResponse": {
+        "type": "object",
+        "properties": {
+          "builders": {}
+        },
+        "required": [
+          "builders"
+        ]
+      },
       "GetSecurityDocsResponse": {
         "type": "object",
         "properties": {
@@ -10833,6 +11800,19 @@
           "offset"
         ]
       },
+      "GetSsoPubkeyResponse": {
+        "type": "object",
+        "properties": {
+          "alg": {},
+          "format": {},
+          "public_key_b64": {}
+        },
+        "required": [
+          "alg",
+          "format",
+          "public_key_b64"
+        ]
+      },
       "GetTasksClaimableResponse": {
         "type": "object",
         "properties": {
@@ -11258,6 +12238,27 @@
           "known_sounds"
         ]
       },
+      "PatchProjectsIdFeaturedRequest": {
+        "type": "object",
+        "properties": {
+          "featured": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "featured"
+        ],
+        "additionalProperties": false
+      },
+      "PatchProjectsIdFeaturedResponse": {
+        "type": "object",
+        "properties": {
+          "project": {}
+        },
+        "required": [
+          "project"
+        ]
+      },
       "PatchTasksIdRequest": {
         "type": "object",
         "properties": {
@@ -11408,23 +12409,47 @@
           "interval"
         ]
       },
-      "PostAuthCliTokenIssueResponse": {
+      "PostAuthCliTokenIssueResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "token": {},
+          "expires_at": {},
+          "builder_login": {},
+          "paste_command": {}
+        },
+        "required": [
+          "ok",
+          "token",
+          "expires_at",
+          "builder_login",
+          "paste_command"
+        ]
+      },
+      "PostAuthDeviceExchangeRequest": {
+        "type": "object",
+        "properties": {
+          "assertion": {
+            "type": "string",
+            "maxLength": 4096
+          }
+        },
+        "required": [
+          "assertion"
+        ],
+        "additionalProperties": false
+      },
+      "PostAuthDeviceExchangeResponse": {
         "type": "object",
         "properties": {
-          "ok": {
-            "type": "boolean"
-          },
           "token": {},
-          "expires_at": {},
-          "builder_login": {},
-          "paste_command": {}
+          "builder": {}
         },
         "required": [
-          "ok",
           "token",
-          "expires_at",
-          "builder_login",
-          "paste_command"
+          "builder"
         ]
       },
       "PostAuthDevicePollRequest": {
@@ -12114,6 +13139,28 @@
           "message"
         ]
       },
+      "PostGithubReposRequest": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "maxLength": 100
+          }
+        },
+        "required": [
+          "name"
+        ],
+        "additionalProperties": false
+      },
+      "PostGithubReposResponse": {
+        "type": "object",
+        "properties": {
+          "repo": {}
+        },
+        "required": [
+          "repo"
+        ]
+      },
       "PostGoalsIdArchiveResponse": {
         "type": "object",
         "properties": {
@@ -12844,6 +13891,79 @@
           "submission"
         ]
       },
+      "PostMyProjectsClientIdLeaveResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "left": {}
+        },
+        "required": [
+          "ok",
+          "left"
+        ]
+      },
+      "PostMyProjectsInvitesClientIdAcceptResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "accepted": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "ok",
+          "accepted"
+        ]
+      },
+      "PostMyProjectsInvitesClientIdDeclineResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "accepted": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "ok",
+          "accepted"
+        ]
+      },
+      "PostMyProjectsJoinRequest": {
+        "type": "object",
+        "properties": {
+          "origin": {
+            "type": "string",
+            "maxLength": 512
+          }
+        },
+        "required": [
+          "origin"
+        ],
+        "additionalProperties": false
+      },
+      "PostMyProjectsJoinResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "status": {},
+          "project": {},
+          "message": {}
+        },
+        "required": [
+          "ok",
+          "status",
+          "project",
+          "message"
+        ]
+      },
       "PostOverrideRequestsIdDecideRequest": {
         "type": "object",
         "properties": {
@@ -12860,6 +13980,59 @@
         ],
         "additionalProperties": false
       },
+      "PostProjectsInviteRequest": {
+        "type": "object",
+        "properties": {
+          "client_id": {
+            "type": "string",
+            "maxLength": 200
+          },
+          "github_login": {
+            "type": "string",
+            "maxLength": 200
+          }
+        },
+        "required": [
+          "client_id",
+          "github_login"
+        ],
+        "additionalProperties": false
+      },
+      "PostProjectsRequest": {
+        "type": "object",
+        "properties": {
+          "origin": {
+            "type": "string",
+            "maxLength": 512
+          },
+          "name": {
+            "type": "string",
+            "maxLength": 200
+          },
+          "tagline": {
+            "type": "string",
+            "maxLength": 400
+          },
+          "art_url": {
+            "type": "string",
+            "maxLength": 2048
+          }
+        },
+        "required": [
+          "origin",
+          "name"
+        ],
+        "additionalProperties": false
+      },
+      "PostProjectsResponse": {
+        "type": "object",
+        "properties": {
+          "project": {}
+        },
+        "required": [
+          "project"
+        ]
+      },
       "PostProvisioningInstancesIdForceTeardownResponse": {
         "type": "object",
         "properties": {
@@ -13105,6 +14278,172 @@
           "token_reward": {}
         }
       },
+      "PostSsoActivityRollupRequest": {
+        "type": "object",
+        "properties": {
+          "client_id": {
+            "type": "string",
+            "maxLength": 200
+          },
+          "client_secret": {
+            "type": "string",
+            "maxLength": 512
+          },
+          "github_id": {
+            "$ref": "#/components/schemas/StringifiableId"
+          },
+          "credits": {
+            "type": "number"
+          },
+          "tasks_shipped": {
+            "type": "number"
+          },
+          "karma": {
+            "type": "number"
+          },
+          "rank": {
+            "type": "string",
+            "maxLength": 32
+          },
+          "disciplines": {}
+        },
+        "required": [
+          "client_id",
+          "client_secret",
+          "github_id"
+        ],
+        "additionalProperties": false
+      },
+      "PostSsoActivityRollupResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "ok"
+        ]
+      },
+      "PostSsoDevicePollRequest": {
+        "type": "object",
+        "properties": {
+          "device_code": {
+            "type": "string",
+            "maxLength": 512
+          }
+        },
+        "required": [
+          "device_code"
+        ],
+        "additionalProperties": false
+      },
+      "PostSsoDeviceStartRequest": {
+        "type": "object",
+        "properties": {
+          "origin": {
+            "type": "string",
+            "maxLength": 512
+          }
+        },
+        "required": [
+          "origin"
+        ],
+        "additionalProperties": false
+      },
+      "PostSsoMembershipCheckInRequest": {
+        "type": "object",
+        "properties": {
+          "client_id": {
+            "type": "string",
+            "maxLength": 200
+          },
+          "client_secret": {
+            "type": "string",
+            "maxLength": 512
+          },
+          "github_id": {
+            "$ref": "#/components/schemas/StringifiableId"
+          },
+          "github_login": {
+            "type": "string",
+            "maxLength": 200
+          },
+          "display_name": {
+            "type": "string",
+            "maxLength": 400
+          },
+          "avatar_url": {
+            "type": "string",
+            "maxLength": 2048
+          },
+          "role": {
+            "type": "string",
+            "maxLength": 16
+          }
+        },
+        "required": [
+          "client_id",
+          "client_secret",
+          "github_id",
+          "github_login"
+        ],
+        "additionalProperties": false
+      },
+      "PostSsoMembershipCheckInResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "ok"
+        ]
+      },
+      "PostSsoTokenRequest": {
+        "type": "object",
+        "properties": {
+          "client_id": {
+            "type": "string",
+            "maxLength": 200
+          },
+          "client_secret": {
+            "type": "string",
+            "maxLength": 512
+          },
+          "code": {
+            "type": "string",
+            "maxLength": 512
+          },
+          "redirect_uri": {
+            "type": "string",
+            "maxLength": 2048
+          }
+        },
+        "required": [
+          "client_id",
+          "client_secret",
+          "code",
+          "redirect_uri"
+        ],
+        "additionalProperties": false
+      },
+      "PostSsoTokenResponse": {
+        "type": "object",
+        "properties": {
+          "github_id": {},
+          "github_login": {},
+          "display_name": {},
+          "avatar_url": {}
+        },
+        "required": [
+          "github_id",
+          "github_login",
+          "display_name",
+          "avatar_url"
+        ]
+      },
       "PostTasksIdAbandonRequest": {
         "type": "object",
         "properties": {
@@ -13719,9 +15058,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 223,
-  "x-schema-count": 244,
+  "x-endpoint-count": 245,
+  "x-schema-count": 273,
   "x-undocumented-bodies": 8,
-  "x-response-schemas": 166,
+  "x-response-schemas": 184,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }