@bongos/core 1.19.418 → 1.19.420

package/docs/api/openapi.json

@@ -77,6 +77,10 @@
       "name": "closeness",
       "description": "Endpoints under `/api/bongos/closeness`."
     },
+    {
+      "name": "connections",
+      "description": "Endpoints under `/api/bongos/connections`."
+    },
     {
       "name": "copy-desk",
       "description": "Endpoints under `/api/bongos/copy-desk`."
@@ -368,7 +372,7 @@
           "access-requests"
         ],
         "summary": "GET /access-requests/status",
-        "description": "GET /access-requests/status?github_login=X — PUBLIC. The `bongos login` CLI polls this after filing a request: the device flow's not_approved is TERMINAL (the device_code is spent), so the CLI can't re-poll the flow — it polls this instead, then restarts sign-in once admitted. Exposes nothing the public POST above doesn't already reveal through its 409s (already_member / already_approved). status ∈ member | invited | pending | dismissed | none; admitted = member||invited. rank: public — a would-be builder is by definition outside the system. Declared BEFORE `GET /access-requests` so the literal `/status` path is matched as its own route (not swallowed as a query on the list route).\n\n**Rank:** `public` — No authentication — any caller.",
+        "description": "GET /access-requests/status?github_login=X — PUBLIC. The `bongos login` CLI polls this after filing a request: the device flow's not_approved is TERMINAL (the device_code is spent), so the CLI can't re-poll the flow — it polls this instead, then restarts sign-in once admitted. Exposes nothing the public POST above doesn't already reveal through its 409s (already_member / already_approved). status ∈ member | invited | pending | dismissed | none; admitted = member||invited. rank: public — a would-be builder is by definition outside the system. Declared BEFORE `GET /access-requests` so the literal `/status` path is matched as its own route (not swallowed as a query on the list route). RATE-LIMITED (task 1003339 / ADR 0209). Public + unthrottled, this was a login→membership oracle an attacker could script at line rate to learn who builds here. accountExistenceReadRateLimit is the doorway's SHARED 120/60s per-IP budget: core's GET /auth/web/admission-status (the boolean twin of this answer) mounts the very same instance, so the two cannot be alternated for double the rate. The limiter runs before the queries, so a refused probe costs no DB work. Whether the ANSWER should also collapse — so a caller who is not the subject cannot tell pending/dismissed/none apart — is the owner's call and is filed as a blocker, not decided here.\n\n**Rank:** `public` — No authentication — any caller.",
         "x-rank": "public",
         "x-source": "modules/onboarding/routes/access-requests.js",
         "responses": {
@@ -1155,7 +1159,7 @@
           "auth"
         ],
         "summary": "GET /auth/web/admission-status",
-        "description": "GET /auth/web/admission-status?login=X — the probe renderAccessPendingPage polls (task 1002097). Answers ONE question: would this login be admitted right now? It mirrors the real gate via auth.webAdmissionStatus so the page can never invite someone in the gate would refuse. rank: public — it must be reachable by a visitor with no session (that is the entire situation it exists for). It grants nothing: admission still runs through the normal sign-in, and this only reads state. WHAT IT LEAKS, stated plainly (task 1002430 — an earlier version of this comment claimed the opposite and was wrong). Returning only a boolean does NOT make it non-enumerable: with open enrollment off, and for any login that is not the configured firstAdmin, `admitted:true` means that login is a member or has been invited. That reveals account existence to an unauthenticated caller. It is also NOT throttled — rateLimitMiddleware returns early for non-write methods, so GETs bypass it entirely; the page's 3s poll bounds the honest client, not an attacker. Why it is nonetheless not a new exposure: the onboarding module's GET /access-requests/status?github_login=X is ALREADY public and returns the strictly richer member|invited|pending|dismissed|none plus its own `admitted`. Anything derivable here is already derivable there, so this adds no net-new surface — and hardening only this route would accomplish nothing while that one stays open. Whether unauthenticated login-existence probing is acceptable at all is a real question, but it belongs to both routes together, not to a comment here. That endpoint is also why this one exists: it models neither the firstAdmin bypass nor open enrollment, so it reports the OWNER as 'none' forever — the exact case this page has to resolve.\n\n**Rank:** `public` — No authentication — any caller.",
+        "description": "GET /auth/web/admission-status?login=X — the probe renderAccessPendingPage polls (task 1002097). Answers ONE question: would this login be admitted right now? It mirrors the real gate via auth.webAdmissionStatus so the page can never invite someone in the gate would refuse. rank: public — it must be reachable by a visitor with no session (that is the entire situation it exists for). It grants nothing: admission still runs through the normal sign-in, and this only reads state. WHAT IT LEAKS, stated plainly (task 1002430 — an earlier version of this comment claimed the opposite and was wrong). Returning only a boolean does NOT make it non-enumerable: with open enrollment off, and for any login that is not the configured firstAdmin, `admitted:true` means that login is a member or has been invited. That reveals account existence to an unauthenticated caller. IT IS NOW THROTTLED (task 1003339 / ADR 0209). It used to say \"NOT throttled\" here, and that was true: rateLimitMiddleware returns early for non-write methods, so GETs bypassed it entirely and the page's 3s poll bounded the honest client, not an attacker. accountExistenceReadRateLimit below is the ceiling — 120 reads/60s per IP, and the SAME instance is mounted on the onboarding module's GET /access-requests/status, which is this route's strictly richer twin (member|invited|pending|dismissed|none plus its own `admitted`). One budget across both, because they are one oracle: hardening either alone would accomplish nothing, and giving each its own budget would just let an enumerator alternate for double the rate. WHAT IS STILL OPEN and is deliberately NOT decided here: whether the answer itself should collapse, so a caller who is not the subject cannot tell pending/dismissed/none apart from a bare \"not admitted\". That changes what a real invited user sees during onboarding, so it is the owner's call — filed as a blocker against task 1003339, not settled by a comment in this file. That endpoint is also why this one exists: it models neither the firstAdmin bypass nor open enrollment, so it reports the OWNER as 'none' forever — the exact case this page has to resolve.\n\n**Rank:** `public` — No authentication — any caller.",
         "x-rank": "public",
         "x-source": "src/bongos/routes/auth.js",
         "responses": {
@@ -3435,6 +3439,330 @@
         ]
       }
     },
+    "/connections": {
+      "get": {
+        "operationId": "get_connections",
+        "tags": [
+          "connections"
+        ],
+        "summary": "GET /connections",
+        "description": "MY accepted connections (own data, keyed on the session). Own scope, so the counterparty floors on profile_state alone: a private account you connected with appears here and in no public list (D4 §2).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/connections.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetConnectionsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "post": {
+        "operationId": "post_connections",
+        "tags": [
+          "connections"
+        ],
+        "summary": "POST /connections",
+        "description": "ask to connect. The REQUESTER is always the session; the body names only who is being asked, and it names them by public handle.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/connections.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostConnectionsRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostConnectionsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/connections/degree/{handle}": {
+      "get": {
+        "operationId": "get_connections_degree_handle",
+        "tags": [
+          "connections"
+        ],
+        "summary": "GET /connections/degree/:handle",
+        "description": "the degree label between the CALLER and one handle, plus the mutuals it was computed from (own-scope read, D4 §4). Bounded by construction: degreeBetween caps every level and answers null past the caps.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/connections.js",
+        "parameters": [
+          {
+            "name": "handle",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `handle`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetConnectionsDegreeHandleResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/connections/requests": {
+      "get": {
+        "operationId": "get_connections_requests",
+        "tags": [
+          "connections"
+        ],
+        "summary": "GET /connections/requests",
+        "description": "MY pending requests, both directions (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/connections.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetConnectionsRequestsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/connections/{id}": {
+      "delete": {
+        "operationId": "delete_connections_id",
+        "tags": [
+          "connections"
+        ],
+        "summary": "DELETE /connections/:id",
+        "description": "remove an accepted connection (either side may end it) or cancel a pending request I sent. An ADDRESSEE ending a pending row is a decline, not a delete, and is 404'd here so the cooldown cannot be dodged.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/connections.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/DeleteConnectionsIdResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/connections/{id}/accept": {
+      "post": {
+        "operationId": "post_connections_id_accept",
+        "tags": [
+          "connections"
+        ],
+        "summary": "POST /connections/:id/accept",
+        "description": "accept a request addressed to ME. The addressee is the session; a row belonging to anyone else simply does not match, and the 404 that follows is what stops a builder acting on someone else's connection.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/connections.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/PostConnectionsIdAcceptResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/connections/{id}/decline": {
+      "post": {
+        "operationId": "post_connections_id_decline",
+        "tags": [
+          "connections"
+        ],
+        "summary": "POST /connections/:id/decline",
+        "description": "decline a request addressed to ME. 204: the requester is never told, so there is nothing to return that they could ever observe.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/connections.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/copy-desk/flags": {
       "post": {
         "operationId": "post_copy_desk_flags",
@@ -10661,6 +10989,69 @@
         ]
       }
     },
+    "/provisioning/instances/{id}/detail": {
+      "patch": {
+        "operationId": "patch_provisioning_instances_id_detail",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "PATCH /provisioning/instances/:id/detail",
+        "description": "── The optional project detail (task 1002334, goal 1000046) ────────────── PATCH /provisioning/instances/:id/detail — answer (or re-answer) the \"tell us about your project\" step after creation. Body: any subset of { description, detail }. rank: any authenticated builder (own resource; archon may change any — same gate as settings). THIS ROUTE IS WHAT MAKES THE STEP SKIPPABLE. Skipping at creation leaves the project dark-matter — off the map and un-joinable (ADR 0182 D4) — and that is a supported default only because there is a way back. Without this route \"optional\" would mean \"permanently unpublishable\", i.e. a dead end, which is precisely what criterion `proj-detail-interview` refuses. Deliberately NOT a settings-apply: nothing here is a policy the running instance obeys, so there is no web.env to patch and no restart to queue. The answers live on the platform row until a catalog row materializes (the provisioning_007 `type` precedent), and R16 (task 1002335) is the surface that reads `description` to compute publishability and name what is still missing.\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/PatchProvisioningInstancesIdDetailRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PatchProvisioningInstancesIdDetailResponse"
+                }
+              }
+            }
+          },
+          "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}/domain": {
       "post": {
         "operationId": "post_provisioning_instances_id_domain",
@@ -15051,6 +15442,15 @@
           "deleted"
         ]
       },
+      "DeleteConnectionsIdResponse": {
+        "type": "object",
+        "properties": {
+          "outcome": {}
+        },
+        "required": [
+          "outcome"
+        ]
+      },
       "DeleteDependenciesResponse": {
         "type": "object",
         "properties": {
@@ -15485,6 +15885,49 @@
           "why"
         ]
       },
+      "GetConnectionsDegreeHandleResponse": {
+        "type": "object",
+        "properties": {
+          "handle": {},
+          "degree": {},
+          "mutuals": {},
+          "mutual_count": {},
+          "truncated": {}
+        },
+        "required": [
+          "handle",
+          "degree",
+          "mutuals",
+          "mutual_count",
+          "truncated"
+        ]
+      },
+      "GetConnectionsRequestsResponse": {
+        "type": "object",
+        "properties": {
+          "incoming": {},
+          "outgoing": {},
+          "incoming_count": {},
+          "outgoing_count": {}
+        },
+        "required": [
+          "incoming",
+          "outgoing",
+          "incoming_count",
+          "outgoing_count"
+        ]
+      },
+      "GetConnectionsResponse": {
+        "type": "object",
+        "properties": {
+          "connections": {},
+          "count": {}
+        },
+        "required": [
+          "connections",
+          "count"
+        ]
+      },
       "GetDiscordChannelsPlanResponse": {
         "type": "object",
         "properties": {
@@ -17090,6 +17533,35 @@
           "project"
         ]
       },
+      "PatchProvisioningInstancesIdDetailRequest": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "type": "string"
+          },
+          "detail": {
+            "type": "object"
+          }
+        },
+        "additionalProperties": false
+      },
+      "PatchProvisioningInstancesIdDetailResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "description": {},
+          "detail": {},
+          "options": {}
+        },
+        "required": [
+          "ok",
+          "description",
+          "detail",
+          "options"
+        ]
+      },
       "PatchProvisioningInstancesIdSettingsRequest": {
         "type": "object",
         "properties": {
@@ -17932,6 +18404,41 @@
           "reward"
         ]
       },
+      "PostConnectionsIdAcceptResponse": {
+        "type": "object",
+        "properties": {
+          "status": {}
+        },
+        "required": [
+          "status"
+        ]
+      },
+      "PostConnectionsRequest": {
+        "type": "object",
+        "properties": {
+          "handle": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39
+          },
+          "note": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "handle"
+        ],
+        "additionalProperties": false
+      },
+      "PostConnectionsResponse": {
+        "type": "object",
+        "properties": {
+          "status": {}
+        },
+        "required": [
+          "status"
+        ]
+      },
       "PostCopyDeskFlagsIdCloseRequest": {
         "type": "object",
         "properties": {
@@ -19604,6 +20111,12 @@
           },
           "type": {
             "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "detail": {
+            "type": "object"
           }
         },
         "required": [
@@ -20847,9 +21360,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 330,
-  "x-schema-count": 365,
+  "x-endpoint-count": 338,
+  "x-schema-count": 374,
   "x-undocumented-bodies": 9,
-  "x-response-schemas": 247,
+  "x-response-schemas": 254,
   "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. 330 endpoints across 53 route files.
+> **Generated from the live route files** — the route file is authoritative. 338 endpoints across 54 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/<redacted>.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -153,6 +153,18 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/closeness/weights` | `any-builder` | — | the MODEL is not private, and publishing it is the whole point of the weights being data. |
 | GET | `/api/bongos/closeness/with/:builderId` | `any-builder` | — | One pair — "why am I close to THEM", asked directly rather than by paging the graph. |
 
+## `connections` (7)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/connections` | `any-builder` | — | MY accepted connections (own data, keyed on the session). |
+| POST | `/api/bongos/connections` | `any-builder` | `handle`, `note` | ask to connect. |
+| DELETE | `/api/bongos/connections/:id` | `any-builder` | — | remove an accepted connection (either side may end it) or cancel a pending request I sent. |
+| POST | `/api/bongos/connections/:id/accept` | `any-builder` | — | accept a request addressed to ME. |
+| POST | `/api/bongos/connections/:id/decline` | `any-builder` | — | decline a request addressed to ME. |
+| GET | `/api/bongos/connections/degree/:handle` | `any-builder` | — | the degree label between the CALLER and one handle, plus the mutuals it was computed from (own-scope read, D4 §4). |
+| GET | `/api/bongos/connections/requests` | `any-builder` | — | MY pending requests, both directions (own data). |
+
 ## `copy-desk` (4)
 
 | Method | Path | Rank | Body | Description |
@@ -425,7 +437,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/projects/featured` | `public` | — | a curated public showcase; no auth by design. |
 | POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | invite a builder into a project (ADR 0141 §5, task #1002115). |
 
-## `provisioning` (18)
+## `provisioning` (19)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -435,8 +447,9 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/provisioning/github-app/status` | `public` | — | GET /provisioning/github-app/status?state=<> — the PUBLIC progress read the onboarding callback page polls (task 2096) to know when setup… |
 | GET | `/api/bongos/provisioning/health` | `public` | — | GET /provisioning/health — liveness + the core version this module mounted against. |
 | GET | `/api/bongos/provisioning/instances` | `any-builder` | — | GET /provisioning/instances — the caller's own instances + each open intent. |
-| POST | `/api/bongos/provisioning/instances` | `any-builder` | `slug`, `target_ref`, `hosting_shape`, `domain`, `no_address`, `tier`, `onboard_mode`, `type` | POST /provisioning/instances — request a new instance. |
+| POST | `/api/bongos/provisioning/instances` | `any-builder` | `slug`, `target_ref`, `hosting_shape`, `domain`, `no_address`, `tier`, `onboard_mode`, `type`, `description`, `detail` | POST /provisioning/instances — request a new instance. |
 | GET | `/api/bongos/provisioning/instances/:id` | `any-builder` | — | GET /provisioning/instances/:id — read one instance (the manage page's read). |
+| PATCH | `/api/bongos/provisioning/instances/:id/detail` | `any-builder` | `description`, `detail` | ── The optional project detail (task 1002334, goal 1000046) ────────────── PATCH /provisioning/instances/:id/detail — answer (or re-answe… |
 | POST | `/api/bongos/provisioning/instances/:id/domain` | `any-builder` | `domain` | POST /provisioning/instances/:id/domain — give the caller's OWN instance its address (task 1002692, gap 5: no path existed to add a domai… |
 | POST | `/api/bongos/provisioning/instances/:id/force-teardown` | `metic+archon` | — | POST /provisioning/instances/:id/force-teardown — Archon tears down ANY instance. |
 | POST | `/api/bongos/provisioning/instances/:id/github-app` | `any-builder` | `account` | POST /provisioning/instances/:id/github-app — mint a GitHub-App-Manifest onboarding link for the caller's OWN instance (task 2080, ADR 01… |