@bongos/core 1.19.325 → 1.19.326

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.325",
-  "core_contract": "1.19.325",
-  "source_commit": "9a1a1c67f80e8d01c562568c4565b9c2b4fb9420",
+  "core_version": "1.19.326",
+  "core_contract": "1.19.326",
+  "source_commit": "e45bd1d46602e4398fd004b0f58482821d9272d2",
   "source_ref": "HEAD",
-  "built_at": "2026-08-24T14:28:39.280Z",
+  "built_at": "2026-08-24T21:08:08.576Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 324,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1460,
+    "functional_verbatim": 1464,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1806,
-  "tree_sha256": "d455b7b84d748804468edea9e50ab188ef60da26a3538ede625b0766ca673f9b",
+  "file_count": 1810,
+  "tree_sha256": "56db7faea7aa522af7f8ce16375f10d64ccf6177d82985d1eb678f5e72cabc98",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -347,12 +347,12 @@
     {
       "path": "clients/bongos-client/README.md",
       "mode": "0000644",
-      "sha256": "162edc8df3b6354b06337ad981f473ea798151002d6c2eda728b25c0545ea70c"
+      "sha256": "615510285a7e398d5f0c188fa32a8d915ecc3b8bc420fc0f0e6b476e1a819a9d"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "f8df65df7eaaccb15fe2a1aeda1c690e377cecc3617b408c4ff8a71f4c79edea"
+      "sha256": "4854a4975a05b0b7914a6c087f85c9b15130debefebde75e438fa73cc85df7d0"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -362,17 +362,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "53dec4d0e2958ddb66fe794b74cdc0bb8823fa7d8a5da90a4c2dd731a1bb0e04"
+      "sha256": "482572aaeacfa0b195bcb7fa9b812c746a8304b85d4ca423674cff85bc46e71c"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "356ef6ee04671774868423f5312cedd2ae194f1f4abcdcaaac01828b044c1c14"
+      "sha256": "ef27d2f4e7e92b3c47c8bb372dd1e4eba7358986471efab9b626597970e4d94e"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "f01af61309e843cf15fc8b5c4cb01e8383927890ea1734d91a2ed490424d2d77"
+      "sha256": "5d6cd728c907810d2a55e0c3ef1c73ed122cb2fbbd858c85654860ce42dbdf70"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -1422,12 +1422,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "25a1978be80e817a5a9b54609aaa52dc0e172c941110183b9cfc93d193430f0b"
+      "sha256": "7d9a216f5a2638037ba64868c4f6b0298417492f391c57ad38d1fa7920e6e937"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "1cbc9af7fe828c5c81e6348a1a219b53ab484f9df67ec9ccb41e6f6cdef1693e"
+      "sha256": "3f3d991bab5069ad0877c6a44f22de50a4f06b9d9835b9f75ce43f55e76fbf27"
     },
     {
       "path": "docs/architecture.md",
@@ -2497,7 +2497,7 @@
     {
       "path": "modules/builder-settings/builder-needs.js",
       "mode": "0000644",
-      "sha256": "3cb7478d9e347147e331f0954a9178a1770918067a678efdb8caef96241dfb5a"
+      "sha256": "01f32e6f160ffbfde7240cfc1dd0e0bdc3501f13578e073c9397a2a0cccb793b"
     },
     {
       "path": "modules/builder-settings/db.js",
@@ -2827,7 +2827,7 @@
     {
       "path": "modules/dev-box/app/src/vendor/bongos-client.cjs",
       "mode": "0000644",
-      "sha256": "53dec4d0e2958ddb66fe794b74cdc0bb8823fa7d8a5da90a4c2dd731a1bb0e04"
+      "sha256": "482572aaeacfa0b195bcb7fa9b812c746a8304b85d4ca423674cff85bc46e71c"
     },
     {
       "path": "modules/dev-box/app/test/unit.mjs",
@@ -3944,6 +3944,11 @@
       "mode": "0000644",
       "sha256": "5fac15e501d6e5639b9e14d08ab34723b60e3569af913f4d15bb703a4e126a77"
     },
+    {
+      "path": "modules/lifecycle/help-requests.js",
+      "mode": "0000644",
+      "sha256": "140fce2462a0013d2d863cb9ae4ae8ca93aac8045917cb8906d1a6e52c6b2549"
+    },
     {
       "path": "modules/lifecycle/hierarchy.js",
       "mode": "0000644",
@@ -3952,7 +3957,7 @@
     {
       "path": "modules/lifecycle/lifecycle.js",
       "mode": "0000644",
-      "sha256": "8f62f50c5a81d649df6b85ef7c89e57a0bf0e8877482693861a4f9cd5cfafe5a"
+      "sha256": "07ea278ae8c0f0055d6ac332d7580af55e82fecefda2d1cf46dad1bf27678c59"
     },
     {
       "path": "modules/lifecycle/merge-lock.js",
@@ -3969,10 +3974,15 @@
       "mode": "0000644",
       "sha256": "b63517ec3b8c686a83c52e58a87b24a252b02e25833af9bfab1d647dcc068d62"
     },
+    {
+      "path": "modules/lifecycle/migrations/lifecycle_004_help_requests.sql",
+      "mode": "0000644",
+      "sha256": "d52627071dcfbf70e9bccef60803d246e49b08c22da4c374d706e1f5712fbb11"
+    },
     {
       "path": "modules/lifecycle/module.json",
       "mode": "0000644",
-      "sha256": "1ccd8ce521c084ede265c318a71896b508aae0172fda2a67dd6e355c5dfefa0f"
+      "sha256": "8f94f0609ee66725a31147da7ced78d4a9736ec1ee1f88daf6f3cf5df6b984c4"
     },
     {
       "path": "modules/lifecycle/pollers/publish-reconciler.js",
@@ -4014,6 +4024,11 @@
       "mode": "0000644",
       "sha256": "a58f01647120ce0b1143314f5edab2501bc18b8a748073dac788c92aaa0484ca"
     },
+    {
+      "path": "modules/lifecycle/routes/help-requests.js",
+      "mode": "0000644",
+      "sha256": "0e9430101ce99d0a84f1893d13bcf1434af13325c2ce531e693b6bce42cb9385"
+    },
     {
       "path": "modules/lifecycle/routes/lifecycle.js",
       "mode": "0000644",
@@ -4652,12 +4667,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "1a460f0c695ba6d590ee9bab9b281626de4747e164ca416098658ae054843ad6"
+      "sha256": "3bd132ca17ee7b22c34513aaa13a26bad931dfc74588117c6400bd2473c9a575"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "7cc398a8e7f341aee2272da252afc4abd5213349ece88962764c6bde65f27f25"
+      "sha256": "6c02b85a00c26a316ccc71869f26bb4922e11b7a442afc86b76335efbb29bad6"
     },
     {
       "path": "public-docs/index.html",
@@ -6367,7 +6382,7 @@
     {
       "path": "src/bongos/routes/me.js",
       "mode": "0000644",
-      "sha256": "83657d8a2f8e1d81a80324350ddd983baf5346da3f88ce1f41c2211275f34440"
+      "sha256": "dc32a25a531f9ea76c25df57930e0566259737bbd1c559409df61f5b5f87813e"
     },
     {
       "path": "src/bongos/routes/modules.js",
@@ -6437,7 +6452,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "cc999c875729b68c2b78cf1f16a34184412b4d2b87b82be7b182627d313e9628"
+      "sha256": "bdd8762b9a99257de8474de64cfc78cd7c38ab741847c41a370a4cb7a398de72"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7709,6 +7724,11 @@
       "mode": "0000644",
       "sha256": "a86e615af8b148572abf562b3c7b0d556076286e76e2d8d576f782a90ba3d457"
     },
+    {
+      "path": "tests/help_requests.mjs",
+      "mode": "0000644",
+      "sha256": "19d743c063d5e35c63d33c163e3830175a129bea18ea662319997c4d416899bb"
+    },
     {
       "path": "tests/helpers.mjs",
       "mode": "0000644",

package/clients/bongos-client/README.md

@@ -5,7 +5,7 @@ A **generated**, zero-dependency typed client for the Bongos API — produced fr
 by hand; it regenerates when the spec changes, so it can never drift from the routes.
 
 - API version: **v1** (served at `/api/bongos/v1`)
-- 300 operations across 47 resource groups
+- 304 operations across 48 resource groups
 
 ## Install
 

package/clients/bongos-client/bongos-client.global.js

@@ -394,6 +394,16 @@ function createClient(opts = {}) {
       // GET /healthz — rank: public — GET /healthz
       getHealthz: (args) => request("GET", "/healthz", { hasBody: false }, args),
     },
+    "helpRequests": {
+      // POST /help-requests — rank: any-builder — POST /help-requests
+      postHelpRequests: (args) => request("POST", "/help-requests", { hasBody: true }, args),
+      // PATCH /help-requests/{id} — rank: any-builder — PATCH /help-requests/:id
+      patchHelpRequestsId: (args) => request("PATCH", "/help-requests/{id}", { hasBody: true }, args),
+      // GET /help-requests/for-me — rank: any-builder — GET /help-requests/for-me
+      getHelpRequestsForMe: (args) => request("GET", "/help-requests/for-me", { hasBody: false }, args),
+      // GET /help-requests/mine — rank: any-builder — GET /help-requests/mine
+      getHelpRequestsMine: (args) => request("GET", "/help-requests/mine", { hasBody: false }, args),
+    },
     "inbox": {
       // GET /inbox — rank: any-builder — GET /inbox
       getInbox: (args) => request("GET", "/inbox", { hasBody: false }, args),

package/clients/bongos-client/index.cjs

@@ -393,6 +393,16 @@ function createClient(opts = {}) {
       // GET /healthz — rank: public — GET /healthz
       getHealthz: (args) => request("GET", "/healthz", { hasBody: false }, args),
     },
+    "helpRequests": {
+      // POST /help-requests — rank: any-builder — POST /help-requests
+      postHelpRequests: (args) => request("POST", "/help-requests", { hasBody: true }, args),
+      // PATCH /help-requests/{id} — rank: any-builder — PATCH /help-requests/:id
+      patchHelpRequestsId: (args) => request("PATCH", "/help-requests/{id}", { hasBody: true }, args),
+      // GET /help-requests/for-me — rank: any-builder — GET /help-requests/for-me
+      getHelpRequestsForMe: (args) => request("GET", "/help-requests/for-me", { hasBody: false }, args),
+      // GET /help-requests/mine — rank: any-builder — GET /help-requests/mine
+      getHelpRequestsMine: (args) => request("GET", "/help-requests/mine", { hasBody: false }, args),
+    },
     "inbox": {
       // GET /inbox — rank: any-builder — GET /inbox
       getInbox: (args) => request("GET", "/inbox", { hasBody: false }, args),

package/clients/bongos-client/index.d.ts

@@ -47,6 +47,8 @@ export interface GetGovernmentPermissionsResponse { permissions: unknown; princi
 export interface GetGovernmentRanksResponse { ranks: unknown }
 export interface GetGradesByBuilderResponse { window_days: unknown; builders: unknown }
 export interface GetHealthzResponse { ok: boolean; auth_configured: unknown }
+export interface GetHelpRequestsForMeResponse { help_requests: unknown; count: unknown; crafts: unknown }
+export interface GetHelpRequestsMineResponse { help_requests: unknown; count: unknown }
 export interface GetInboxAwaitingNodResponse { awaiting: unknown; count: unknown }
 export interface GetInboxIdResponse { idea: unknown }
 export interface GetInboxResponse { ideas: unknown; open_count: unknown }
@@ -129,6 +131,8 @@ export interface PatchDoneWhenCriterionIdRequest { criterion_md: string }
 export interface PatchDoneWhenCriterionIdResponse { ok: boolean; criterion: unknown; deltas: unknown; unchanged: boolean }
 export interface PatchGoalsIdMembersBuilderIdRequest { membership_kind: string }
 export interface PatchGoalsIdMembersBuilderIdResponse { ok: boolean; member: unknown; changed: boolean }
+export interface PatchHelpRequestsIdRequest { status: "answered" | "withdrawn" }
+export interface PatchHelpRequestsIdResponse { ok: boolean; help_request: unknown }
 export interface PatchInboxIdBodyRequest { body_md: string }
 export interface PatchInboxIdBodyResponse { ok: boolean; idea: unknown; delta: unknown; unchanged: unknown }
 export interface PatchInboxIdRequest { status?: "open" | "promoted" | "discarded" | "merged"; kind?: string; promoted_to_task_id?: number; reviewed_at?: unknown; merged_into_idea_id?: number; triage_note?: string }
@@ -247,6 +251,8 @@ export interface PostGovernmentBoardItemsResponse { ok: boolean; amendment: unkn
 export interface PostGovernmentRanksRankKeyResetResponse { ok: boolean; rank_key: unknown; seeded_rank: unknown; permission_count: unknown }
 export interface PostGovernmentRanksRequest { rank_key: string; label: string; description?: string }
 export interface PostGovernmentRanksResponse { rank: unknown }
+export interface PostHelpRequestsRequest { needs_craft?: string; needs_builder_id?: number; what_is_stuck: string; task_id?: number; goal_id?: number }
+export interface PostHelpRequestsResponse { ok: boolean; help_request: unknown }
 export interface PostInboxIdDevelopRequest { field_values: Record<string, unknown>; template_key?: string }
 export interface PostInboxIdRatifyRequest { notes_md?: string }
 export interface PostInboxIdResubmitRequest { field_values: Record<string, unknown>; template_key?: string }
@@ -661,6 +667,16 @@ export interface BongosClient {
     /** GET /healthz — rank: public */
     getHealthz(args?: RequestArgs): Promise<GetHealthzResponse>;
   };
+  "helpRequests": {
+    /** POST /help-requests — rank: any-builder */
+    postHelpRequests(args: RequestArgs & { body: PostHelpRequestsRequest }): Promise<PostHelpRequestsResponse>;
+    /** PATCH /help-requests/{id} — rank: any-builder */
+    patchHelpRequestsId(args: RequestArgs & { body: PatchHelpRequestsIdRequest }): Promise<PatchHelpRequestsIdResponse>;
+    /** GET /help-requests/for-me — rank: any-builder */
+    getHelpRequestsForMe(args?: RequestArgs): Promise<GetHelpRequestsForMeResponse>;
+    /** GET /help-requests/mine — rank: any-builder */
+    getHelpRequestsMine(args?: RequestArgs): Promise<GetHelpRequestsMineResponse>;
+  };
   "inbox": {
     /** GET /inbox — rank: any-builder */
     getInbox(args?: RequestArgs): Promise<GetInboxResponse>;

package/clients/bongos-client/index.mjs

@@ -390,6 +390,16 @@ export function createClient(opts = {}) {
       // GET /healthz — rank: public — GET /healthz
       getHealthz: (args) => request("GET", "/healthz", { hasBody: false }, args),
     },
+    "helpRequests": {
+      // POST /help-requests — rank: any-builder — POST /help-requests
+      postHelpRequests: (args) => request("POST", "/help-requests", { hasBody: true }, args),
+      // PATCH /help-requests/{id} — rank: any-builder — PATCH /help-requests/:id
+      patchHelpRequestsId: (args) => request("PATCH", "/help-requests/{id}", { hasBody: true }, args),
+      // GET /help-requests/for-me — rank: any-builder — GET /help-requests/for-me
+      getHelpRequestsForMe: (args) => request("GET", "/help-requests/for-me", { hasBody: false }, args),
+      // GET /help-requests/mine — rank: any-builder — GET /help-requests/mine
+      getHelpRequestsMine: (args) => request("GET", "/help-requests/mine", { hasBody: false }, args),
+    },
     "inbox": {
       // GET /inbox — rank: any-builder — GET /inbox
       getInbox: (args) => request("GET", "/inbox", { hasBody: false }, args),

package/docs/api/openapi.json

@@ -117,6 +117,10 @@
       "name": "healthz",
       "description": "Endpoints under `/api/bongos/healthz`."
     },
+    {
+      "name": "help-requests",
+      "description": "Endpoints under `/api/bongos/help-requests`."
+    },
     {
       "name": "inbox",
       "description": "Endpoints under `/api/bongos/inbox`."
@@ -6188,6 +6192,194 @@
         "security": []
       }
     },
+    "/help-requests": {
+      "post": {
+        "operationId": "post_help_requests",
+        "tags": [
+          "help-requests"
+        ],
+        "summary": "POST /help-requests",
+        "description": "asking for help is not a privileged act, and gating it would exclude exactly the newcomers most likely to be stuck.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/help-requests.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostHelpRequestsRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostHelpRequestsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/help-requests/for-me": {
+      "get": {
+        "operationId": "get_help_requests_for_me",
+        "tags": [
+          "help-requests"
+        ],
+        "summary": "GET /help-requests/for-me",
+        "description": "The addressed read — C01's answer to \"and fires a notification\". A request is immediately visible to the person or craft it names. A true PUSH lives in the builder-needs feed (`builder-settings`), which is outside this goal's scope wall, so it is recorded as a gap rather than reached for. rank: any-builder — you only ever see what is addressed to you.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/help-requests.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetHelpRequestsForMeResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/help-requests/mine": {
+      "get": {
+        "operationId": "get_help_requests_mine",
+        "tags": [
+          "help-requests"
+        ],
+        "summary": "GET /help-requests/mine",
+        "description": "your own asks, so you can settle them.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/help-requests.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetHelpRequestsMineResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/help-requests/{id}": {
+      "patch": {
+        "operationId": "patch_help_requests_id",
+        "tags": [
+          "help-requests"
+        ],
+        "summary": "PATCH /help-requests/:id",
+        "description": "Only the ASKER settles their own request: 'answered' when someone helped, 'withdrawn' when they no longer need it. Nobody is assigned by being asked — the same consent posture ADR 0187 §3 gives task recommendations. rank: any-builder — ownership is enforced in the UPDATE's WHERE, not by rank.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/help-requests.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PatchHelpRequestsIdRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PatchHelpRequestsIdResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/inbox": {
       "get": {
         "operationId": "get_inbox",
@@ -14178,6 +14370,30 @@
           "auth_configured"
         ]
       },
+      "GetHelpRequestsForMeResponse": {
+        "type": "object",
+        "properties": {
+          "help_requests": {},
+          "count": {},
+          "crafts": {}
+        },
+        "required": [
+          "help_requests",
+          "count",
+          "crafts"
+        ]
+      },
+      "GetHelpRequestsMineResponse": {
+        "type": "object",
+        "properties": {
+          "help_requests": {},
+          "count": {}
+        },
+        "required": [
+          "help_requests",
+          "count"
+        ]
+      },
       "GetInboxAwaitingNodResponse": {
         "type": "object",
         "properties": {
@@ -15235,6 +15451,35 @@
           "changed"
         ]
       },
+      "PatchHelpRequestsIdRequest": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "answered",
+              "withdrawn"
+            ]
+          }
+        },
+        "required": [
+          "status"
+        ],
+        "additionalProperties": false
+      },
+      "PatchHelpRequestsIdResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "help_request": {}
+        },
+        "required": [
+          "ok",
+          "help_request"
+        ]
+      },
       "PatchInboxIdBodyRequest": {
         "type": "object",
         "properties": {
@@ -17153,6 +17398,48 @@
           "rank"
         ]
       },
+      "PostHelpRequestsRequest": {
+        "type": "object",
+        "properties": {
+          "needs_craft": {
+            "type": "string",
+            "maxLength": 32
+          },
+          "needs_builder_id": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "what_is_stuck": {
+            "type": "string",
+            "minLength": 1
+          },
+          "task_id": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "goal_id": {
+            "type": "integer",
+            "minimum": 1
+          }
+        },
+        "required": [
+          "what_is_stuck"
+        ],
+        "additionalProperties": false
+      },
+      "PostHelpRequestsResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "help_request": {}
+        },
+        "required": [
+          "ok",
+          "help_request"
+        ]
+      },
       "PostInboxIdDevelopRequest": {
         "type": "object",
         "properties": {
@@ -18956,9 +19243,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 300,
-  "x-schema-count": 334,
+  "x-endpoint-count": 304,
+  "x-schema-count": 340,
   "x-undocumented-bodies": 8,
-  "x-response-schemas": 223,
+  "x-response-schemas": 227,
   "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. 300 endpoints across 47 route files.
+> **Generated from the live route files** — the route file is authoritative. 304 endpoints across 48 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`.
@@ -258,6 +258,15 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 |---|---|---|---|---|
 | GET | `/api/bongos/healthz` | `public` | — | liveness probe; the status dashboard (status.<apex>) hits this anonymously. |
 
+## `help-requests` (4)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/help-requests` | `any-builder` | `needs_craft`, `needs_builder_id`, `what_is_stuck`, `task_id`, `goal_id` | asking for help is not a privileged act, and gating it would exclude exactly the newcomers most likely to be stuck. |
+| PATCH | `/api/bongos/help-requests/:id` | `any-builder` | `status` | Only the ASKER settles their own request: 'answered' when someone helped, 'withdrawn' when they no longer need it. |
+| GET | `/api/bongos/help-requests/for-me` | `any-builder` | — | The addressed read — C01's answer to "and fires a notification". |
+| GET | `/api/bongos/help-requests/mine` | `any-builder` | — | your own asks, so you can settle them. |
+
 ## `inbox` (14)
 
 | Method | Path | Rank | Body | Description |