@bongos/core 1.20.20 → 1.20.22

package/docs/adr/0353-a-hub-invite-is-a-notice-of-the-projects-own-invite.md

@@ -0,0 +1,70 @@
+# ADR 0353 — A hub invite is a notice of the project's own invite, and signing in accepts it
+
+- **Status:** accepted
+- **Date:** 2026-09-30
+- **Task:** [task 1002818](https://cloudbongos.com/builders#/task/1002818) (R6 of the project admin console wave, goal 1000110 — BONGOS-V2)
+- **Builds on:** [ADR 0335](0335-an-invite-is-a-pre-approved-row-on-the-projects-own-instance.md) D1/D2 (authority lives on the project's own instance; an invite is a pre-approved `access_requests` row; signing in is the acceptance act)
+- **Interacts with:** [ADR 0141](<redacted>.md) §3 (membership check-in), [ADR 0205](0205-federated-checkin-needs-the-hubs-own-signin-witness.md) (client credentials never mint a membership), [ADR 0352](0352-a-rollup-report-carries-its-as-of-in-a-header.md) (hub↔instance wire skew)
+- **Decided with:** the owner chose the split in D3 on 2026-09-30, over building the signed-assertion relay in this task.
+
+## Context
+
+ADR 0335 left one dead end that real users could reach. The hub had its own invite, `POST /projects/invite`, called from the creation wizard's invite step and from a project's manage page. It wrote a `pending` row in `<redacted>`, and accepting it (`POST /my-projects/invites/:clientId/accept`) flipped that row to `member`. No project reads that table to decide who may enter. So the invitee "accepted" and then met the project's own sign-in gate, which knew nothing about them. A hosted project's join door defaults to `apply`, so this was the common case, not an edge case.
+
+The project's own invite (`POST /access-requests/invite`, R2) does admit: it writes the `invited` row the sign-in gate reads. But nothing told the invitee it existed, and rescinding it left nothing to clean up on the hub because the hub had never heard of it.
+
+The task's done-when: **no state where an accepted invite leads to a locked door.**
+
+## Decision
+
+### D1 — The hub's `pending` row is a NOTICE of the project's own invite
+
+The row stays, and My Projects lists it as before, but only the project writes it now. Two new server-to-server routes, authenticated by `client_id` + `client_secret` like the membership check-in:
+
+| Route | When the project calls it | What the hub does |
+|---|---|---|
+| `POST /sso/invites/notify` | every outcome of its invite route that leaves the login holding an `invited` row: a fresh invite, a pending application approved in place, and a re-invite of one already standing | `INSERT … 'pending' ON CONFLICT DO NOTHING` for the account that login resolves to |
+| `POST /sso/invites/clear` | a dismissal after which the login holds no `invited` row | `DELETE` that `pending` row, and only a `pending` one |
+
+Both calls touch a `pending` row only, so client credentials still cannot create, change or remove a membership (ADR 0205). A login with no hub account is a no-op, because there is nobody on the hub to notify; the project's row still admits them. **The answer is always `{ ok: true }` once the client authenticates**, whether or not anything was written, so a project cannot use the route to learn which GitHub logins have platform accounts.
+
+The sender is core's `notifyHubOfInvite` (`src/bongos/auth-admission.js`). It sits in the kernel beside the other hub calls that hold the client secret, and modules reach it as a narrow doorway port. It is fire-and-forget, time-bounded and swallows every failure: an invite must never wait on the hub or fail because of it. Re-inviting is how a notice the hub missed is healed, since the hub's insert is idempotent.
+
+Only a dismissal that leaves no `invited` row clears the notice. If two archons invited the same login and one rescinds, the other invite still admits, so the notice stays. A declined application also sends a clear. That is a no-op unless the hub still holds a pre-ADR-0353 row for that login, which would be a dead end anyway.
+
+### D2 — Accepting is signing in to the project; the hub-side accept is retired
+
+`POST /my-projects/invites/:clientId/accept` is deleted, and `resolveInvite` becomes the decline-only `removePendingInvite`. The hub page has not called accept since the invitations list came back (task 1003774): each invitation renders as **Open project →** with "Sign in there to accept." What was missing was the server half, so no caller (an old cached page, a script) can still flip a row and admit nobody.
+
+Signing in closes the loop without any new code. The hub's own sign-in witness (`recordFederatedSignin`, stamped at `/sso/token` and `/sso/device/poll`) already turns a `pending` row into `member` when the invitee signs in to that project.
+
+### D3 — The hub's own invite writes nothing; it hands the owner to the project's hall
+
+`POST /projects/invite` keeps its owner-or-curator gate and its byte-identical 403, and it still resolves the catalog client. It no longer writes. It answers `200 { invited: false, invite_url }`: the project's hall invite box with the login filled in, `<origin>/builders/watch?invite=<login>`. A 200 rather than a refusal, because it is the answer every admitted caller gets, and a 4xx on that path would log a failed request in the owner's browser on every invite. Every instance already canonicalises `/builders/watch` to its hall (a one-host instance serves `/watch`, a two-host one redirects to `builders.<apex>/watch`, both keeping the query), so the hub needs no hall address of its own. The sign-in redirect carries the full URL, so the name survives signing in.
+
+The wizard and manage-page widget keep their field, their suggestions and their Skip button. Each name becomes a line reading "not sent yet — finish it on your project's hall" with a **Send the invite →** link. It is a link the owner clicks, never a window opened for them: an open triggered by a network answer is blocked by browsers, and a surprise navigation would lose the wizard.
+
+The hall's Watch page reads `?invite=` once, only if it is a valid GitHub username, and **only fills the box**. Sending stays the owner's click, because a link anyone can craft must never be the act that admits.
+
+The owner chose this over building the relay ADR 0335 foresaw (see Alternatives) in this task.
+
+### D4 — Wire skew (ADR 0352's rule)
+
+The two notice routes are **new**. An older hub answers 404, the sender swallows it, and the invite still admits: only the notice is lost. A newer hub with an older instance simply receives no notices. Each route's body is validated strictly (three fields), so a field added later must ride a header, or ship on the hub and be released before any instance sends it.
+
+## Consequences
+
+- **The done-when holds for every invite created from now on.** A hub notice exists only because the project wrote an `invited` row, and a rescind that closes the door removes the notice. The hub's own invite creates no row at all.
+- **Rows written before this change are untouched.** Pending rows the old hub invite wrote still render as **Open project →**, and on a door other than `open` they still lead to the project's gate. The invitee can decline them, and the project can clear one by inviting and then rescinding. Deleting them at deploy would need a data migration, and it would also delete notices that do work (on `open` doors). That is left to the owner (see the task's handoff), not done silently here.
+- **The hub's invite now reaches people with no platform account.** The project's own invite takes any GitHub login, so the old `account_not_found` refusal is gone. Such an invitee sees no hub notice, because there is no account to show it to, but they are admitted when they sign in.
+- **Three things still bypass the notice**, all by scope: the reviewer queue's approve (`PATCH` pending → invited), the Discord approval reaction, and R3's future recruiter rescind route. The first two are approvals of an application the applicant already knows about. R3 (task 1002815) must call the same port when it adds its rescind.
+- **The 30-day invite expiry** (task 1002969) is read-time on the instance. An expired invite's hub notice stays until the invitee declines it or the project re-invites and rescinds. Task 1002969 owns closing that.
+
+## Alternatives considered
+
+- **The signed-assertion relay (ADR 0335's foreseen design).** The hub mints a new `purpose: 'invite'` token for the inviter, and a new token-authenticated route on the project checks that builder's own permission and writes the real row. It keeps the in-place form, but it adds an authentication path to every instance (security-sensitive), roughly doubles this task, needs a fallback for every older instance, and cannot work until the owner has signed in to a new project once (there is no local builder to check the permission against). The owner deferred it. D3's hand-off leaves room for it: if it is built, the route's `invited: false` becomes `true` for instances that support it.
+- **Seed the hub row only when the project's door is `open`.** An owner who later closes the door strands every such notice in front of a locked door, and a self-hosted project's door is not known to the hub reliably.
+- **Keep the hub-side accept, but have the instance read hub memberships at sign-in.** This puts a hub call inside the admission gate and moves a verdict onto the hub, which ADR 0335 D1 forbids.
+- **A body field on the membership check-in instead of new routes.** The check-in body is validated strictly, so an older hub would 400 the whole check-in (ADR 0352), and a check-in is sent at sign-in, not at invite time.
+
+Proof: `tests/hub_invite_notices.mjs` (the hub routes over the real domain functions: pending-only writes keyed on the authenticated client, the identical answer for an unknown login, the credential refusals, the three-field body, the hand-off link, and the sender), `tests/access_requests_invite.mjs` and `tests/application_lifecycle.mjs` (which invite outcomes notify and which dismissals clear), `tests/project_invite_ownership.mjs` and `tests/catalog_only_client.mjs` (the gate is unchanged and nothing is written), `tests/project_invite_ui.mjs` (the hand-off line, no non-http link, no window opened), `tests/watch_applications_queue.mjs` (the prefill fills and never sends), `tests/my_projects_surface.mjs` and `modules/platform-identity/tests/platform-identity.mjs` (the accept route and flip are gone).

package/docs/adr/README.md

@@ -471,3 +471,4 @@ These 20 numbers are each shared by exactly two files. They are **accepted histo
 | 0350 | [**The hub holds a per-project WRITE deploy key, so a hosted project's upgraded pin always reaches its GitHub repo** ([task 1004291](https://cloudbongos.com/builders#/task/1004291), follow-up to task 1004065). Amends ADR 0176. The owner's token lasts one hour and the checkout's own key is read-only, so most hosted upgrades ended "GitHub was not updated". **D1:** a second deploy key per repo, registered `read_only: false` as `cloudbongos-pin-<slug>`, the pull key untouched. **D2:** kept outside every checkout in the runner's own directory (0700 dir, 0600 key, modes verified), unreadable by the project's account. **D3:** minted at standup and whenever a fresh owner token finds none, so reconnecting GitHub once is enough. **D4:** `pushUpgradePin` tries write key, then owner token, then origin, never forced. **D5:** revoked on teardown and disconnect. **D6:** a project on the shared app user is refused a key: "needs its own account first". **D7:** /deploy says reconnecting sets up lasting access.](0350-the-hub-holds-a-per-project-write-deploy-key-so-a-hosted-upgrade-reaches-github.md) | provisioning / security |
 | 0351 | [**A criterion closes on a UAT, not on its linked tasks shipping** ([task 1004392](https://cloudbongos.com/builders#/task/1004392), goal 1000089 — working area 3). Supersedes ADR 0183's close rule. `wa7-government` had closed on six Board Room navigation tasks while nothing it describes was on the live site. **D1:** three checks — Code (linked tasks done, ≥1 shipped; automatic), Live, UAT — and the sweep closes a criterion only with a CURRENT sign-off (no older than the newest linked ship). **D2 (owner):** "Awaiting UAT" is a visible state. **D3 (owner):** one step; the signer is refused if they shipped linked work, the project owner excepted. **D4 (owner):** an mp4/webm up to 100 MB on the project's own server. **D5 (owner):** backend-only is set while a criterion is open and takes a recording-free sign-off. **D6 (owner):** Live is read via the `deploy.taskWhere` port where the site can tell, attested otherwise. **D7 (owner):** already-closed criteria stay closed ("Closed before UAT"). **D8:** `/satisfy` is a recorded override that needs a reason. **D9:** `/goal-uat` + `scripts/gds/uat.js`; the hall is task 1004402.](0351-a-criterion-closes-on-a-uat.md) | lifecycle / criteria / review |
 | 0352 | [**A rollup report carries its "as of" in a header, and the hub keeps the newest** ([task 1004268](https://cloudbongos.com/builders#/task/1004268), goal 1000110). `POST /sso/activity/rollup` was last-writer-wins with no report timestamp, so a sign-in push read earlier and a ship push read later could land the older totals last. **D1:** the instance's read time rides a `Bongos-Report-As-Of` HEADER, not a body field, because the hub validates the body strictly and hub and instances upgrade independently: a body field from a newer instance would 400 on an older hub and lose the report, while an unknown header is ignored. **D2:** missing or unparseable = unstamped = last-writer-wins, never a 400. **D3:** the guard is a WHERE on the upsert's conflict branch (migration 026, `reported_as_of`, no backfill); a skipped update keeps the row lock, so the task 1004244 snapshot stays in step. **D4:** the stamp is compared only with the same client's, and clamped to the hub's `now()`.](0352-a-rollup-report-carries-its-as-of-in-a-header.md) | platform identity / federation |
+| 0353 | [**A hub invite is a notice of the project's own invite, and signing in accepts it** ([task 1002818](https://cloudbongos.com/builders#/task/1002818), goal 1000110 — R6 of the admin console wave). The hub's own invite wrote a `pending` membership that no project reads, so an "accepted" invite met a locked door (new projects default to `apply`). **D1:** that row is now a NOTICE the PROJECT writes: its invite route calls `POST /sso/invites/notify` and a dismissal that leaves no invited row calls `/sso/invites/clear` (client credentials, pending rows only, always `{ ok: true }` so no account oracle); core's `notifyHubOfInvite` is fire-and-forget. **D2:** the hub-side accept route is deleted; signing in to the project accepts, and the hub's own sign-in witness turns the row into a membership. **D3 (owner):** `POST /projects/invite` writes nothing and answers `{ invited: false, invite_url }`, the project's hall invite link (`/builders/watch?invite=<login>`, which only pre-fills); the signed-assertion relay is deferred. **D4:** new routes, so an older hub 404s and only the notice is lost (ADR 0352).](0353-a-hub-invite-is-a-notice-of-the-projects-own-invite.md) | platform identity / federation |

package/docs/api/openapi.json

@@ -388,7 +388,7 @@
           "access-requests"
         ],
         "summary": "POST /access-requests/invite",
-        "description": "POST /access-requests/invite — an Archon admits a GitHub username BEFORE any request exists (task 1003044): the only way in on an invite-only project, where the public POST refuses, and a shortcut on an apply one. It writes the same access_request row the sign-in gate reads (status 'invited' — hasInvitedAccessRequest), so nothing new is consulted at sign-in; a pending request for that login is resolved in place rather than duplicated. Two Archons inviting the same login at once can each insert a row (the unique index covers pending only): harmless — the gate reads \"any invited row\" — and it shows as two lines in the invited history, so no lock is taken. A fresh row is marked kind='invite' with created_by = the sender (a rescind overwrites resolved_by) and the optional note as the inviter's words. A pending request resolved in place stays an application with its applicant's own note (ADR 0335 D2.1–D2.3; task 1002814). body: { github_login, note? }. 201 with a new row; 200 with the row when a pending request was resolved; 200 already_invited when an invite already stands; 409 already_member when they have an account. rank: archon — the same gate as resolving a request.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `access_request.review` (all required).",
+        "description": "POST /access-requests/invite — an Archon admits a GitHub username BEFORE any request exists (task 1003044): the only way in on an invite-only project, where the public POST refuses, and a shortcut on an apply one. It writes the same access_request row the sign-in gate reads (status 'invited' — hasInvitedAccessRequest), so nothing new is consulted at sign-in; a pending request for that login is resolved in place rather than duplicated. Two Archons inviting the same login at once can each insert a row (the unique index covers pending only): harmless — the gate reads \"any invited row\" — and it shows as two lines in the invited history, so no lock is taken. A fresh row is marked kind='invite' with created_by = the sender (a rescind overwrites resolved_by) and the optional note as the inviter's words. A pending request resolved in place stays an application with its applicant's own note (ADR 0335 D2.1–D2.3; task 1002814). Every outcome that leaves the login invited also notifies the hub, so the invitee sees it in My Projects (ADR 0353). body: { github_login, note? }. 201 with a new row; 200 with the row when a pending request was resolved; 200 already_invited when an invite already stands; 409 already_member when they have an account. rank: archon — the same gate as resolving a request.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `access_request.review` (all required).",
         "x-rank": "archon",
         "x-source": "modules/onboarding/routes/access-requests.js",
         "x-permissions": [
@@ -8590,6 +8590,32 @@
       }
     },
     "/guilds": {
+      "get": {
+        "operationId": "get_guilds",
+        "tags": [
+          "guilds"
+        ],
+        "summary": "GET /guilds",
+        "description": "the guild map (?order=size|shipped, default size; ?limit=&offset=). Viewer-independent: it reads no session. size is the public roster's length; shipped is R26's stored band floor (ADR 0337 D4.4), never an exact sum, null before a guild's first refresh. no-store: a hide or a visibility flip moves size on the very next read (ADR 0171 D5).\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/platform-identity/routes/guilds-public.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetGuildsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      },
       "post": {
         "operationId": "post_guilds",
         "tags": [
@@ -13168,58 +13194,6 @@
         ]
       }
     },
-    "/my-projects/invites/{clientId}/accept": {
-      "post": {
-        "operationId": "post_my_projects_invites_clientId_accept",
-        "tags": [
-          "my-projects"
-        ],
-        "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": "clientId",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Path parameter `clientId`."
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Success.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/PostMyProjectsInvitesClientIdAcceptResponse"
-                }
-              }
-            }
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "403": {
-            "$ref": "#/components/responses/Forbidden"
-          },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
-          }
-        },
-        "security": [
-          {
-            "builderSession": []
-          }
-        ]
-      }
-    },
     "/my-projects/invites/{clientId}/decline": {
       "post": {
         "operationId": "post_my_projects_invites_clientId_decline",
@@ -13975,7 +13949,7 @@
           "projects"
         ],
         "summary": "POST /projects/invite",
-        "description": "own-or-metic in effect: invite a builder into a project (ADR 0141 §5, task 1002115), called by a `project.curate` holder OR the project's OWN OWNER (task 1003580; the ownership proof is `provisioning_instances.owner_builder_id`, reached through a port — see invite-authz.js). The wizard's audience is any signed-in GitHub user, typically a xenos who used to get 403 on their own project. A caller who is neither gets the unchanged permission refusal, identical whether or not the project exists. 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:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `project.curate` (all required).",
+        "description": "own-or-metic in effect: where to invite a builder into a project, asked by a `project.curate` holder OR the project's OWN OWNER (task 1003580; the ownership proof is `provisioning_instances.owner_builder_id`, reached through a port — see invite-authz.js). The wizard's audience is any signed-in GitHub user, typically a xenos who used to get 403 on their own project. A caller who is neither gets the unchanged permission refusal, identical whether or not the project exists. IT WRITES NOTHING (task 1002818, ADR 0353). It used to pre-seed a 'pending' hub membership, but the hub holds no verdict: that row let nobody in, and on any door but `open` (new projects default to `apply`) the invitee who signed in met a locked door. Only the project's own invite admits (ADR 0335 D1/D2), so the answer is 200 `{ invited: false, invite_url }` — the project's hall invite box with the login pre-filled. A 200, not a refusal: it is the answer every admitted caller gets, and a 4xx on the normal path would log a failed request in the owner's browser on every invite. Sending it there also reaches this hub: the project notifies it (POST /sso/invites/notify), and the invitee sees it in My Projects.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `project.curate` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/platform-identity/routes/projects.js",
         "x-permissions": [
@@ -13994,7 +13968,14 @@
         },
         "responses": {
           "200": {
-            "description": "Success."
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostProjectsInviteResponse"
+                }
+              }
+            }
           },
           "400": {
             "$ref": "#/components/responses/ValidationFailed"
@@ -18658,6 +18639,70 @@
         "security": []
       }
     },
+    "/sso/invites/clear": {
+      "post": {
+        "operationId": "post_sso_invites_clear",
+        "tags": [
+          "sso"
+        ],
+        "summary": "POST /sso/invites/clear",
+        "description": "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-invites.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostSsoInvitesClearRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          }
+        },
+        "security": []
+      }
+    },
+    "/sso/invites/notify": {
+      "post": {
+        "operationId": "post_sso_invites_notify",
+        "tags": [
+          "sso"
+        ],
+        "summary": "POST /sso/invites/notify",
+        "description": "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-invites.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostSsoInvitesNotifyRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          }
+        },
+        "security": []
+      }
+    },
     "/sso/membership/check-in": {
       "post": {
         "operationId": "post_sso_membership_check_in",
@@ -22551,6 +22596,21 @@
           "builders"
         ]
       },
+      "GetGuildsResponse": {
+        "type": "object",
+        "properties": {
+          "order": {},
+          "count": {},
+          "results": {},
+          "page": {}
+        },
+        "required": [
+          "order",
+          "count",
+          "results",
+          "page"
+        ]
+      },
       "GetGuildsSlugMembersResponse": {
         "type": "object",
         "properties": {
@@ -27248,21 +27308,6 @@
           "left"
         ]
       },
-      "PostMyProjectsInvitesClientIdAcceptResponse": {
-        "type": "object",
-        "properties": {
-          "ok": {
-            "type": "boolean"
-          },
-          "accepted": {
-            "type": "boolean"
-          }
-        },
-        "required": [
-          "ok",
-          "accepted"
-        ]
-      },
       "PostMyProjectsInvitesClientIdDeclineResponse": {
         "type": "object",
         "properties": {
@@ -27359,6 +27404,19 @@
         ],
         "additionalProperties": false
       },
+      "PostProjectsInviteResponse": {
+        "type": "object",
+        "properties": {
+          "invited": {
+            "type": "boolean"
+          },
+          "invite_url": {}
+        },
+        "required": [
+          "invited",
+          "invite_url"
+        ]
+      },
       "PostProjectsProjectIdSpecialitiesRequest": {
         "type": "object",
         "properties": {
@@ -28411,6 +28469,54 @@
         ],
         "additionalProperties": false
       },
+      "PostSsoInvitesClearRequest": {
+        "type": "object",
+        "properties": {
+          "client_id": {
+            "type": "string",
+            "maxLength": 200
+          },
+          "client_secret": {
+            "type": "string",
+            "maxLength": 512
+          },
+          "github_login": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          }
+        },
+        "required": [
+          "client_id",
+          "client_secret",
+          "github_login"
+        ],
+        "additionalProperties": false
+      },
+      "PostSsoInvitesNotifyRequest": {
+        "type": "object",
+        "properties": {
+          "client_id": {
+            "type": "string",
+            "maxLength": 200
+          },
+          "client_secret": {
+            "type": "string",
+            "maxLength": 512
+          },
+          "github_login": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          }
+        },
+        "required": [
+          "client_id",
+          "client_secret",
+          "github_login"
+        ],
+        "additionalProperties": false
+      },
       "PostSsoMembershipCheckInRequest": {
         "type": "object",
         "properties": {
@@ -29523,9 +29629,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 461,
-  "x-schema-count": 493,
+  "x-endpoint-count": 463,
+  "x-schema-count": 496,
   "x-undocumented-bodies": 12,
-  "x-response-schemas": 335,
+  "x-response-schemas": 336,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 461 endpoints across 82 route files.
+> **Generated from the live route files** — the route file is authoritative. 463 endpoints across 83 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -342,10 +342,11 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/guild-requests/:id/accept` | `any-builder` | `visibility`, `counted_in_totals` | accept an invite addressed to ME, or (as the guild's owner) a request to join it. |
 | POST | `/api/bongos/guild-requests/:id/decline` | `any-builder` | — | decline an invite to ME, or (as owner) a request to my guild. |
 
-## `guilds` (12)
+## `guilds` (13)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
+| GET | `/api/bongos/guilds` | `public` | — | the guild map (?order=size\|shipped, default size; ?limit=&offset=). |
 | POST | `/api/bongos/guilds` | `any-builder` | `slug`, `name`, `description`, `visibility` | create a guild. |
 | GET | `/api/bongos/guilds/:slug` | `public` | — | a public guild's page data. |
 | PATCH | `/api/bongos/guilds/:slug` | `any-builder` | `name`, `description`, `visibility` | owner: edit name, description or visibility. |
@@ -505,14 +506,13 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/modules/:key/submit` | `metic+archon` | `signed_by` | POST /api/bongos/modules/:key/submit — ADR 0107 §1 upstreaming submission. |
 | GET | `/api/bongos/modules/submissions` | `metic+archon` | — | GET /api/bongos/modules/submissions?status=&module_key= — the upstreaming review queue (task 1771 reads this). |
 
-## `my-projects` (6)
+## `my-projects` (5)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/my-projects` | `any-builder` | — | the caller's OWN cross-project memberships (own data). |
 | POST | `/api/bongos/my-projects/:clientId/leave` | `any-builder` | — | leave a project from the caller's OWN membership list. |
 | GET | `/api/bongos/my-projects/invites` | `any-builder` | — | the caller's OWN pending invitations (ADR 0141 §5). |
-| POST | `/api/bongos/my-projects/invites/:clientId/accept` | `any-builder` | — | accept an invite (pending → builder) for the caller's OWN account. |
 | POST | `/api/bongos/my-projects/invites/:clientId/decline` | `any-builder` | — | decline an invite (delete the pending row) for the caller's OWN account. |
 | POST | `/api/bongos/my-projects/join` | `any-builder` | `origin`, `note` | request to join a project. |
 
@@ -558,7 +558,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | PATCH | `/api/bongos/projects/:id/status` | `metic+archon` | `status` | THE TAKEDOWN LEVER (R08, task 1002327; ADR 0252 §5.1). |
 | POST | `/api/bongos/projects/:projectId/specialities` | `any-builder` | `name`, `discipline`, `summary`, `contract_md`, `visibility`, `sellable`, `skills` | POST /projects/:projectId/specialities — author one OWNED BY A PROJECT. |
 | GET | `/api/bongos/projects/featured` | `public` | — | the public map of projects; no auth by design. |
-| POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | own-or-metic in effect: invite a builder into a project (ADR 0141 §5, task 1002115), called by a `project.curate` holder OR the project's… |
+| POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | own-or-metic in effect: where to invite a builder into a project, asked by a `project.curate` holder OR the project's OWN OWNER (task 100… |
 
 ## `provisioning` (34)
 
@@ -718,7 +718,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/specialities/installed-skills` | `any-builder` | — | GET /specialities/installed-skills — every skill THIS instance has, each explained the way the adoption walkthrough explains it, so a spe… |
 | GET | `/api/bongos/specialities/offered` | `any-builder` | — | GET /specialities/offered — the suggestions for THIS builder. |
 
-## `sso` (8)
+## `sso` (10)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -727,6 +727,8 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/sso/authorize` | `public` | — | GET /sso/authorize?client_id=&redirect_uri=&state= — the browser authorize leg. |
 | POST | `/api/bongos/sso/device/poll` | `public` | `device_code` | POST /sso/device/poll — poll the hub device flow. |
 | POST | `/api/bongos/sso/device/start` | `public` | `origin` | POST /sso/device/start — begin CLI federation. |
+| POST | `/api/bongos/sso/invites/clear` | `public` | `client_id`, `client_secret`, `github_login` | authenticated by client_id + client_secret, not a builder rank. |
+| POST | `/api/bongos/sso/invites/notify` | `public` | `client_id`, `client_secret`, `github_login` | authenticated by client_id + client_secret, not a builder rank. |
 | POST | `/api/bongos/sso/membership/check-in` | `public` | `client_id`, `client_secret`, `github_id`, `github_login`, `display_name`, `avatar_url`, `membership_kind` | POST /sso/membership/check-in — a federated instance reports, on every sign-in, that a builder builds on its project (ADR 0141 §3). |
 | GET | `/api/bongos/sso/pubkey` | `public` | — | GET /sso/pubkey — the hub's Ed25519 assertion-verification key (public). |
 | POST | `/api/bongos/sso/token` | `public` | `client_id`, `client_secret`, `code`, `redirect_uri` | POST /sso/token — server-to-server code redemption. |