@bongos/core 1.20.44 → 1.20.46

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

@@ -250,6 +250,10 @@ function createClient(opts = {}) {
       // POST /claims/batch/validate — rank: any-builder — POST /claims/batch/validate
       postClaimsBatchValidate: (args) => request("POST", "/claims/batch/validate", { hasBody: true }, args),
     },
+    "cli": {
+      // GET /cli/commands — rank: any-builder — GET /cli/commands
+      getCliCommands: (args) => request("GET", "/cli/commands", { hasBody: false }, args),
+    },
     "closeness": {
       // GET /closeness/for-me — rank: any-builder — GET /closeness/for-me
       getClosenessForMe: (args) => request("GET", "/closeness/for-me", { hasBody: false }, args),
@@ -1049,6 +1053,8 @@ function createClient(opts = {}) {
       getStoreModulesKeyEntitlement: (args) => request("GET", "/store/modules/{key}/entitlement", { hasBody: false }, args),
       // POST /store/modules/{key}/versions — rank: metic+archon — POST /store/modules/:key/versions
       postStoreModulesKeyVersions: (args) => request("POST", "/store/modules/{key}/versions", { hasBody: true }, args),
+      // GET /store/modules/{key}/versions/{version}/howto — rank: any-builder — GET /store/modules/:key/versions/:version/howto
+      getStoreModulesKeyVersionsVersionHowto: (args) => request("GET", "/store/modules/{key}/versions/{version}/howto", { hasBody: false }, args),
       // GET /store/modules/{key}/versions/{version}/tarball — rank: any-builder — GET /store/modules/:key/versions/:version/tarball
       getStoreModulesKeyVersionsVersionTarball: (args) => request("GET", "/store/modules/{key}/versions/{version}/tarball", { hasBody: false }, args),
     },

package/clients/bongos-client/index.cjs

@@ -249,6 +249,10 @@ function createClient(opts = {}) {
       // POST /claims/batch/validate — rank: any-builder — POST /claims/batch/validate
       postClaimsBatchValidate: (args) => request("POST", "/claims/batch/validate", { hasBody: true }, args),
     },
+    "cli": {
+      // GET /cli/commands — rank: any-builder — GET /cli/commands
+      getCliCommands: (args) => request("GET", "/cli/commands", { hasBody: false }, args),
+    },
     "closeness": {
       // GET /closeness/for-me — rank: any-builder — GET /closeness/for-me
       getClosenessForMe: (args) => request("GET", "/closeness/for-me", { hasBody: false }, args),
@@ -1048,6 +1052,8 @@ function createClient(opts = {}) {
       getStoreModulesKeyEntitlement: (args) => request("GET", "/store/modules/{key}/entitlement", { hasBody: false }, args),
       // POST /store/modules/{key}/versions — rank: metic+archon — POST /store/modules/:key/versions
       postStoreModulesKeyVersions: (args) => request("POST", "/store/modules/{key}/versions", { hasBody: true }, args),
+      // GET /store/modules/{key}/versions/{version}/howto — rank: any-builder — GET /store/modules/:key/versions/:version/howto
+      getStoreModulesKeyVersionsVersionHowto: (args) => request("GET", "/store/modules/{key}/versions/{version}/howto", { hasBody: false }, args),
       // GET /store/modules/{key}/versions/{version}/tarball — rank: any-builder — GET /store/modules/:key/versions/:version/tarball
       getStoreModulesKeyVersionsVersionTarball: (args) => request("GET", "/store/modules/{key}/versions/{version}/tarball", { hasBody: false }, args),
     },

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

@@ -46,6 +46,7 @@ export interface GetBuildersIdOnboardingResponse { builder_id: unknown; onboardi
 export interface GetBuildersIdProfileResponse { builder: unknown; shipped_count: unknown; recent_ships: unknown; achievements: unknown; cross_project?: unknown; handle?: unknown }
 export interface GetBuildersMePendingRankChangeResponse { change: unknown; greeting?: unknown }
 export interface GetBuildersRosterResponse { builders: unknown; stale_hours: unknown; stale_hours_source: unknown }
+export interface GetCliCommandsResponse { version: unknown; groups: unknown }
 export interface GetClosenessForMeResponse { closeness: unknown; count: unknown; returned: unknown }
 export interface GetClosenessWeightsResponse { weights: unknown; window_days: unknown; note: unknown }
 export interface GetClosenessWithBuilderIdResponse { closeness: unknown; why: unknown }
@@ -164,6 +165,7 @@ export interface GetSpecialitiesOfferedResponse { suggestions: unknown }
 export interface GetSpecialitiesResponse { specialities: unknown }
 export interface GetSsoPubkeyResponse { alg: unknown; format: unknown; public_key_b64: unknown }
 export interface GetStoreEntitlementsResponse { entitlements: unknown }
+export interface GetStoreModulesKeyVersionsVersionHowtoResponse { module_key: unknown; title: unknown; version: unknown; published_at: unknown; delisted: unknown; markdown: unknown; artifact_url: unknown }
 export interface GetTaskRecommendationsForMeResponse { recommendations: unknown; count: unknown }
 export interface GetTaskRecommendationsMineResponse { recommendations: unknown; count: unknown }
 export interface GetTasksClaimableResponse { claimable: unknown; claimable_total: unknown; active_claims: unknown }
@@ -684,6 +686,10 @@ export interface BongosClient {
     /** POST /claims/batch/validate — rank: any-builder */
     postClaimsBatchValidate(args: RequestArgs & { body: PostClaimsBatchValidateRequest }): Promise<ApiResponse>;
   };
+  "cli": {
+    /** GET /cli/commands — rank: any-builder */
+    getCliCommands(args?: RequestArgs): Promise<GetCliCommandsResponse>;
+  };
   "closeness": {
     /** GET /closeness/for-me — rank: any-builder */
     getClosenessForMe(args?: RequestArgs): Promise<GetClosenessForMeResponse>;
@@ -1483,6 +1489,8 @@ export interface BongosClient {
     getStoreModulesKeyEntitlement(args?: RequestArgs): Promise<ApiResponse>;
     /** POST /store/modules/{key}/versions — rank: metic+archon */
     postStoreModulesKeyVersions(args?: RequestArgs): Promise<PostStoreModulesKeyVersionsResponse>;
+    /** GET /store/modules/{key}/versions/{version}/howto — rank: any-builder */
+    getStoreModulesKeyVersionsVersionHowto(args?: RequestArgs): Promise<GetStoreModulesKeyVersionsVersionHowtoResponse>;
     /** GET /store/modules/{key}/versions/{version}/tarball — rank: any-builder */
     getStoreModulesKeyVersionsVersionTarball(args?: RequestArgs): Promise<ApiResponse>;
   };

package/clients/bongos-client/index.mjs

@@ -246,6 +246,10 @@ export function createClient(opts = {}) {
       // POST /claims/batch/validate — rank: any-builder — POST /claims/batch/validate
       postClaimsBatchValidate: (args) => request("POST", "/claims/batch/validate", { hasBody: true }, args),
     },
+    "cli": {
+      // GET /cli/commands — rank: any-builder — GET /cli/commands
+      getCliCommands: (args) => request("GET", "/cli/commands", { hasBody: false }, args),
+    },
     "closeness": {
       // GET /closeness/for-me — rank: any-builder — GET /closeness/for-me
       getClosenessForMe: (args) => request("GET", "/closeness/for-me", { hasBody: false }, args),
@@ -1045,6 +1049,8 @@ export function createClient(opts = {}) {
       getStoreModulesKeyEntitlement: (args) => request("GET", "/store/modules/{key}/entitlement", { hasBody: false }, args),
       // POST /store/modules/{key}/versions — rank: metic+archon — POST /store/modules/:key/versions
       postStoreModulesKeyVersions: (args) => request("POST", "/store/modules/{key}/versions", { hasBody: true }, args),
+      // GET /store/modules/{key}/versions/{version}/howto — rank: any-builder — GET /store/modules/:key/versions/:version/howto
+      getStoreModulesKeyVersionsVersionHowto: (args) => request("GET", "/store/modules/{key}/versions/{version}/howto", { hasBody: false }, args),
       // GET /store/modules/{key}/versions/{version}/tarball — rank: any-builder — GET /store/modules/:key/versions/:version/tarball
       getStoreModulesKeyVersionsVersionTarball: (args) => request("GET", "/store/modules/{key}/versions/{version}/tarball", { hasBody: false }, args),
     },

package/docs/api/openapi.json

@@ -77,6 +77,10 @@
       "name": "claims",
       "description": "Endpoints under `/api/bongos/claims`."
     },
+    {
+      "name": "cli",
+      "description": "Endpoints under `/api/bongos/cli`."
+    },
     {
       "name": "closeness",
       "description": "Endpoints under `/api/bongos/closeness`."
@@ -3395,6 +3399,44 @@
         ]
       }
     },
+    "/cli/commands": {
+      "get": {
+        "operationId": "get_cli_commands",
+        "tags": [
+          "cli"
+        ],
+        "summary": "GET /cli/commands",
+        "description": "GET /cli/commands — the bongos CLI's verbs, grouped like `bongos --help`. rank: any builder — read-only reference; the hall's Commands page is sign-in gated.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "src/bongos/routes/cli-commands.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetCliCommandsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/closeness/for-me": {
       "get": {
         "operationId": "get_closeness_for_me",
@@ -19343,6 +19385,67 @@
         ]
       }
     },
+    "/store/modules/{key}/versions/{version}/howto": {
+      "get": {
+        "operationId": "get_store_modules_key_versions_version_howto",
+        "tags": [
+          "store"
+        ],
+        "summary": "GET /store/modules/:key/versions/:version/howto",
+        "description": "GET /api/bongos/store/modules/:key/versions/:version/howto — the how-to a version shipped with (task 1004366, ADR 0347 D1/D3), read from that version's own stored tarball after the install hash check, so it always matches the version and cannot change after publishing. Returns the markdown as TEXT, never HTML: the hall's Modules tab renders it through its one escaping markdown reader (md-reader.js), because the file is author-written and must be treated as untrusted input. rank: any-builder — no entitlement needed, since a buyer reads the how-to before deciding. The one exception is a delisted module: ADR 0338 D2 keeps it readable only for the people who already hold it, so there the caller's own entitlement is checked (own-scoped, like the reads above).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "src/bongos/routes/modules.js",
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `key`."
+          },
+          {
+            "name": "version",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `version`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetStoreModulesKeyVersionsVersionHowtoResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/store/modules/{key}/versions/{version}/tarball": {
       "get": {
         "operationId": "get_store_modules_key_versions_version_tarball",
@@ -22507,6 +22610,17 @@
           "stale_hours_source"
         ]
       },
+      "GetCliCommandsResponse": {
+        "type": "object",
+        "properties": {
+          "version": {},
+          "groups": {}
+        },
+        "required": [
+          "version",
+          "groups"
+        ]
+      },
       "GetClosenessForMeResponse": {
         "type": "object",
         "properties": {
@@ -24049,6 +24163,27 @@
           "entitlements"
         ]
       },
+      "GetStoreModulesKeyVersionsVersionHowtoResponse": {
+        "type": "object",
+        "properties": {
+          "module_key": {},
+          "title": {},
+          "version": {},
+          "published_at": {},
+          "delisted": {},
+          "markdown": {},
+          "artifact_url": {}
+        },
+        "required": [
+          "module_key",
+          "title",
+          "version",
+          "published_at",
+          "delisted",
+          "markdown",
+          "artifact_url"
+        ]
+      },
       "GetTaskRecommendationsForMeResponse": {
         "type": "object",
         "properties": {
@@ -29998,9 +30133,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 469,
-  "x-schema-count": 501,
+  "x-endpoint-count": 471,
+  "x-schema-count": 503,
   "x-undocumented-bodies": 12,
-  "x-response-schemas": 337,
+  "x-response-schemas": 339,
   "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. 469 endpoints across 84 route files.
+> **Generated from the live route files** — the route file is authoritative. 471 endpoints across 85 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`.
@@ -146,6 +146,12 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/claims/batch/release` | `any-builder` | `claim_ids`, `force` | Bulk release (task 1758) — the batch twin of resolve(outcome='abandoned'). |
 | POST | `/api/bongos/claims/batch/validate` | `any-builder` | `task_ids` | Dry-run validate (task 1758) — read-only twin of claimTasksBatch's pre-flight checks. |
 
+## `cli` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/cli/commands` | `any-builder` | — | GET /cli/commands — the bongos CLI's verbs, grouped like `bongos --help`. |
+
 ## `closeness` (3)
 
 | Method | Path | Rank | Body | Description |
@@ -744,7 +750,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | 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. |
 
-## `store` (6)
+## `store` (7)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -753,6 +759,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/store/modules/:key/acquired` | `any-builder` | `version` |  |
 | GET | `/api/bongos/store/modules/:key/entitlement` | `any-builder` | — |  |
 | POST | `/api/bongos/store/modules/:key/versions` | `metic+archon` | _undocumented_ | POST /api/bongos/store/modules/:key/versions — publish one module version to the store (task 1004271, ADR 0338 D1). |
+| GET | `/api/bongos/store/modules/:key/versions/:version/howto` | `any-builder` | — | GET /api/bongos/store/modules/:key/versions/:version/howto — the how-to a version shipped with (task 1004366, ADR 0347 D1/D3), read from … |
 | GET | `/api/bongos/store/modules/:key/versions/:version/tarball` | `any-builder` | — |  |
 
 ## `task-recommendations` (4)