@bongos/core 1.17.2 → 1.18.0

package/docs/api/openapi.json

@@ -1,7 +1,7 @@
 {
   "openapi": "3.1.0",
   "info": {
-    "title": "Off the Boats — GDS API",
+    "title": "Cloud Bongos — GDS API",
     "version": "0.0.2",
     "license": {
       "name": "AGPL-3.0-or-later",
@@ -77,10 +77,6 @@
       "name": "cost",
       "description": "Endpoints under `/api/bongos/cost`."
     },
-    {
-      "name": "demo",
-      "description": "Endpoints under `/api/bongos/demo`."
-    },
     {
       "name": "dependencies",
       "description": "Endpoints under `/api/bongos/dependencies`."
@@ -3007,83 +3003,6 @@
         ]
       }
     },
-    "/demo/health": {
-      "get": {
-        "operationId": "get_demo_health",
-        "tags": [
-          "demo"
-        ],
-        "summary": "GET /demo/health",
-        "description": "READ — liveness + the core version this module was mounted against. No rank gate beyond the requireBuilder the loader composes around every module route. rank: public\n\n**Rank:** `public` — No authentication — any caller.",
-        "x-rank": "public",
-        "x-source": "modules/demo/routes/demo.js",
-        "responses": {
-          "200": {
-            "description": "Success.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/GetDemoHealthResponse"
-                }
-              }
-            }
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          }
-        },
-        "security": []
-      }
-    },
-    "/demo/ping": {
-      "post": {
-        "operationId": "post_demo_ping",
-        "tags": [
-          "demo"
-        ],
-        "summary": "POST /demo/ping",
-        "description": "WRITE — EVERY module write route MUST be rank-gated (the BV1.R44 fitness check reds the build on an ungated module write route). `requireRank('metic', 'archon')` is Metic-and-above (the route-rank classifier records it as metic+archon). This records a ping into the module's own namespaced table (demo_pings) via the doorway pool.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
-        "x-rank": "metic+archon",
-        "x-source": "modules/demo/routes/demo.js",
-        "requestBody": {
-          "required": false,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/PostDemoPingRequest"
-              }
-            }
-          },
-          "x-validated": true
-        },
-        "responses": {
-          "200": {
-            "description": "Success.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/PostDemoPingResponse"
-                }
-              }
-            }
-          },
-          "400": {
-            "$ref": "#/components/responses/ValidationFailed"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "403": {
-            "$ref": "#/components/responses/Forbidden"
-          }
-        },
-        "security": [
-          {
-            "builderSession": []
-          }
-        ]
-      }
-    },
     "/dependencies": {
       "post": {
         "operationId": "post_dependencies",
@@ -4589,6 +4508,58 @@
         ]
       }
     },
+    "/goals/{id}/suggest-criteria": {
+      "get": {
+        "operationId": "get_goals_id_suggest_criteria",
+        "tags": [
+          "goals"
+        ],
+        "summary": "GET /goals/:id/suggest-criteria",
+        "description": "GET /goals/:id/suggest-criteria?title=&description=&limit= — task 2165. Rank THIS goal's unsatisfied criteria by lexical overlap with a candidate task, so a create flow can SUGGEST which done-when criterion to link (the author confirms/overrides — nothing is auto-linked). Read-only + advisory; rank: any-builder (same as GET /goals/:id).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/goals.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/GetGoalsIdSuggestCriteriaResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/goals/{id}/tasks": {
       "post": {
         "operationId": "post_goals_id_tasks",
@@ -5423,182 +5394,6 @@
         ]
       }
     },
-    "/me/art-key": {
-      "get": {
-        "operationId": "get_me_art_key",
-        "tags": [
-          "me"
-        ],
-        "summary": "GET /me/art-key",
-        "description": "Shared art key for newcomers (task 1281 / ADR 0068). Hands a SHARED Google AI Studio (Gemini) key to rank=xenos builders so their first art task works without their own key — we pay up front. The session-start sync (scripts/gds/fetch-art-key.js) calls this and writes/removes the local shared_gemini_api_key slot from the response. Thetes+ get a 200 with entitled:false (NOT a 403) — the sync needs an unambiguous \"remove the shared key\" signal it can tell apart from an auth failure, and the rank is the gate, not the route. The secret is attached ONLY when entitled && configured; the response is no-store and the key is never logged. Rank is read live from the DB (no caching, per ADR 0016). rank: any-builder — any authenticated builder may ask; `entitled` in the body is the server-enforced gate. A non-newcomer never receives the secret.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
-        "x-rank": "any-builder",
-        "x-source": "modules/art-pipeline/routes/art-key.js",
-        "responses": {
-          "200": {
-            "description": "Success."
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "403": {
-            "$ref": "#/components/responses/Forbidden"
-          }
-        },
-        "security": [
-          {
-            "builderSession": []
-          }
-        ]
-      }
-    },
-    "/me/art-key/own": {
-      "get": {
-        "operationId": "get_me_art_key_own",
-        "tags": [
-          "me"
-        ],
-        "summary": "GET /me/art-key/own",
-        "description": "Masked metadata for the browser: { set, last4, set_at, storage_configured }.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
-        "x-rank": "any-builder",
-        "x-source": "modules/art-pipeline/routes/art-key.js",
-        "responses": {
-          "200": {
-            "description": "Success.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/GetMeArtKeyOwnResponse"
-                }
-              }
-            }
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "403": {
-            "$ref": "#/components/responses/Forbidden"
-          }
-        },
-        "security": [
-          {
-            "builderSession": []
-          }
-        ]
-      },
-      "put": {
-        "operationId": "put_me_art_key_own",
-        "tags": [
-          "me"
-        ],
-        "summary": "PUT /me/art-key/own",
-        "description": "Set or replace the builder's own key. Body: { key }. Validates the key with one cheap call to Google (catches typos), encrypts it, stores it. Returns the masked metadata — never the key.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
-        "x-rank": "any-builder",
-        "x-source": "modules/art-pipeline/routes/art-key.js",
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/PutMeArtKeyOwnRequest"
-              }
-            }
-          },
-          "x-validated": true
-        },
-        "responses": {
-          "200": {
-            "description": "Success."
-          },
-          "400": {
-            "$ref": "#/components/responses/ValidationFailed"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "403": {
-            "$ref": "#/components/responses/Forbidden"
-          }
-        },
-        "security": [
-          {
-            "builderSession": []
-          }
-        ]
-      },
-      "delete": {
-        "operationId": "delete_me_art_key_own",
-        "tags": [
-          "me"
-        ],
-        "summary": "DELETE /me/art-key/own",
-        "description": "Remove the builder's own key (back to \"not set\"). The session-start sync then withdraws the managed local copy on its next run.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
-        "x-rank": "any-builder",
-        "x-source": "modules/art-pipeline/routes/art-key.js",
-        "responses": {
-          "200": {
-            "description": "Success."
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "403": {
-            "$ref": "#/components/responses/Forbidden"
-          }
-        },
-        "security": [
-          {
-            "builderSession": []
-          }
-        ]
-      }
-    },
-    "/me/art-key/storage-init": {
-      "post": {
-        "operationId": "post_me_art_key_storage_init",
-        "tags": [
-          "me"
-        ],
-        "summary": "POST /me/art-key/storage-init",
-        "description": "Archon-only: provision the server's secret-box master key so per-builder key storage can turn on (task 1398, blocker 41). Idempotent — NEVER overwrites an existing key. Lives under /me/art-key/* for client locality, but is a server-wide admin action — hence the requireRank('archon') gate.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
-        "x-source": "modules/art-pipeline/routes/art-key.js",
-        "responses": {
-          "200": {
-            "description": "Success.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/PostMeArtKeyStorageInitResponse"
-                }
-              }
-            }
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "403": {
-            "$ref": "#/components/responses/Forbidden"
-          }
-        },
-        "security": [
-          {
-            "builderSession": []
-          }
-        ]
-      }
-    },
     "/me/disciplines": {
       "patch": {
         "operationId": "patch_me_disciplines",
@@ -8464,14 +8259,7 @@
         },
         "responses": {
           "200": {
-            "description": "Success.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/PostTasksResponse"
-                }
-              }
-            }
+            "description": "Success."
           },
           "400": {
             "$ref": "#/components/responses/ValidationFailed"
@@ -10411,21 +10199,6 @@
           "stale_hours"
         ]
       },
-      "GetDemoHealthResponse": {
-        "type": "object",
-        "properties": {
-          "module": {},
-          "ok": {
-            "type": "boolean"
-          },
-          "coreVersion": {}
-        },
-        "required": [
-          "module",
-          "ok",
-          "coreVersion"
-        ]
-      },
       "GetDiscordChannelsPlanResponse": {
         "type": "object",
         "properties": {
@@ -10497,6 +10270,17 @@
           "dependencies"
         ]
       },
+      "GetGoalsIdSuggestCriteriaResponse": {
+        "type": "object",
+        "properties": {
+          "goal_id": {},
+          "suggestions": {}
+        },
+        "required": [
+          "goal_id",
+          "suggestions"
+        ]
+      },
       "GetGoalsResponse": {
         "type": "object",
         "properties": {
@@ -10579,21 +10363,6 @@
           "unlocked"
         ]
       },
-      "GetMeArtKeyOwnResponse": {
-        "type": "object",
-        "properties": {
-          "set": {},
-          "last4": {},
-          "set_at": {},
-          "storage_configured": {}
-        },
-        "required": [
-          "set",
-          "last4",
-          "set_at",
-          "storage_configured"
-        ]
-      },
       "GetMeDisplayNameResponse": {
         "type": "object",
         "properties": {
@@ -12258,30 +12027,6 @@
           "recorded_at": {}
         }
       },
-      "PostDemoPingRequest": {
-        "type": "object",
-        "properties": {
-          "note": {
-            "type": "string"
-          }
-        },
-        "additionalProperties": false
-      },
-      "PostDemoPingResponse": {
-        "type": "object",
-        "properties": {
-          "module": {},
-          "ok": {
-            "type": "boolean"
-          },
-          "ping": {}
-        },
-        "required": [
-          "module",
-          "ok",
-          "ping"
-        ]
-      },
       "PostDependenciesResponse": {
         "type": "object",
         "properties": {
@@ -12992,23 +12737,6 @@
           "linked"
         ]
       },
-      "PostMeArtKeyStorageInitResponse": {
-        "type": "object",
-        "properties": {
-          "ok": {
-            "type": "boolean"
-          },
-          "created": {},
-          "reason": {},
-          "storage_configured": {}
-        },
-        "required": [
-          "ok",
-          "created",
-          "reason",
-          "storage_configured"
-        ]
-      },
       "PostMemoryBuildersBuilderIdBfgWriteRequest": {
         "type": "object",
         "properties": {
@@ -13752,23 +13480,6 @@
         ],
         "additionalProperties": false
       },
-      "PostTasksResponse": {
-        "type": "object",
-        "properties": {
-          "task": {},
-          "needs_migration": {},
-          "criteria": {},
-          "idempotent": {
-            "type": "boolean"
-          },
-          "credits_reward": {}
-        },
-        "required": [
-          "task",
-          "needs_migration",
-          "criteria"
-        ]
-      },
       "PostVersionsIdDoneWhenRequest": {
         "type": "object",
         "properties": {
@@ -13857,19 +13568,6 @@
           "criteria"
         ]
       },
-      "PutMeArtKeyOwnRequest": {
-        "type": "object",
-        "properties": {
-          "key": {
-            "type": "string",
-            "maxLength": 400
-          }
-        },
-        "required": [
-          "key"
-        ],
-        "additionalProperties": false
-      },
       "PutTasksIdDependenciesRequest": {
         "type": "object",
         "properties": {
@@ -14021,9 +13719,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 229,
-  "x-schema-count": 250,
+  "x-endpoint-count": 223,
+  "x-schema-count": 244,
   "x-undocumented-bodies": 8,
-  "x-response-schemas": 170,
+  "x-response-schemas": 166,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # GDS API reference
 
-> **Generated from the live route files** — the route file is authoritative. 229 endpoints across 38 route files.
+> **Generated from the live route files** — the route file is authoritative. 223 endpoints across 36 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`.
@@ -145,13 +145,6 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 |---|---|---|---|---|
 | POST | `/api/bongos/cost` | `any-builder` | `task_id`, `amount_usd`, `category`, `description`, `source`, `source_ref`, `recorded_at`, `fresh_input_usd`, `cache_read_usd`, `cache_write_usd`, `output_usd`, `builder_id`, `skill_name` | log cost on own claim (idempotent via source/source_ref). |
 
-## `demo` (2)
-
-| Method | Path | Rank | Body | Description |
-|---|---|---|---|---|
-| GET | `/api/bongos/demo/health` | `public` | — | READ — liveness + the core version this module was mounted against. |
-| POST | `/api/bongos/demo/ping` | `metic+archon` | `note` | WRITE — EVERY module write route MUST be rank-gated (the BV1.R44 fitness check reds the build on an ungated module write route). |
-
 ## `dependencies` (2)
 
 | Method | Path | Rank | Body | Description |
@@ -181,7 +174,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/gate-approvals` | `archon` | — | GET /gate-approvals — open PRs awaiting owner approval (gate-review red), with the verdict + per-file reasons + changed files + diff link. |
 | POST | `/api/bongos/gate-approvals/:pr/approve` | `archon` | — | POST /gate-approvals/:pr/approve — record owner approval for a stuck gate PR and re-run the gate-review check so it clears. |
 
-## `goals` (23)
+## `goals` (24)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -203,6 +196,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/goals/:id/requests/:reqId/respond` | `any-builder` | `action` | POST /goals/:id/requests/:reqId/respond { action: approve\|deny } — an owner\| manager\|Archon resolves a pending join-request (task 1952). |
 | POST | `/api/bongos/goals/:id/requests/:reqId/withdraw` | `any-builder` | — | POST /goals/:id/requests/:reqId/withdraw — the requester cancels their OWN pending join-request (task 1953): the symmetric self-served mi… |
 | POST | `/api/bongos/goals/:id/scope` | `metic+archon` | `add` | POST /goals/:id/scope — "ask to widen": add module(s) to a goal's scope_modules (ADR 0086 §4 / BV1.R64). |
+| GET | `/api/bongos/goals/:id/suggest-criteria` | `any-builder` | — | GET /goals/:id/suggest-criteria?title=&description=&limit= — task 2165. |
 | POST | `/api/bongos/goals/:id/tasks` | `any-builder` | `title`, `description`, `touches`, `est_minutes`, `priority`, `kind`, `discipline`, `value_summary`, `parent_task_id` | POST /goals/:id/tasks — bounded task authoring within a goal's scope (BV1.R60 / ADR 0086 §3). |
 | POST | `/api/bongos/goals/:id/transfer` | `any-builder` | `builder_id` | POST /goals/:id/transfer — hand the goal to a new owner (task 1735). |
 | PATCH | `/api/bongos/goals/:id/visibility` | `any-builder` | `visibility` | PATCH /goals/:id/visibility — make a goal public\|private (task 1952 / ADR 0112). |
@@ -219,7 +213,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
-| GET | `/api/bongos/healthz` | `public` | — | liveness probe; status.example.com hits this anonymously. |
+| GET | `/api/bongos/healthz` | `public` | — | liveness probe; status.amazonprimea.com hits this anonymously. |
 
 ## `inbox` (4)
 
@@ -262,18 +256,13 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/llm-cache/lookup` | `metic+archon` | `cache_key`, `tokens_saved_est` | POST /llm-cache/lookup — hit/miss + atomic hit_count bump. |
 | POST | `/api/bongos/llm-cache/store` | `metic+archon` | `spec`, `result_stdout`, `result_cost_usd` | POST /llm-cache/store — upsert a freshly-produced result. |
 
-## `me` (26)
+## `me` (21)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/me` | `any-builder` | — | PMS-V2 task 188: response now also carries `unlocked` (server-joined achievement metadata) + `locked_with_progress` (server-computed huma… |
 | GET | `/api/bongos/me/achievements` | `any-builder` | — | The builder's unlocked achievements (joined to achievement metadata). |
 | POST | `/api/bongos/me/anthropic-link` | `any-builder` | `anthropic_email`, `anthropic_user_id` | V3.R10 (task 235), criterion C3 — link the authed builder's Anthropic account. |
-| GET | `/api/bongos/me/art-key` | `any-builder` | — | Shared art key for newcomers (task 1281 / ADR 0068). |
-| GET | `/api/bongos/me/art-key/own` | `any-builder` | — | Masked metadata for the browser: { set, last4, set_at, storage_configured }. |
-| PUT | `/api/bongos/me/art-key/own` | `any-builder` | `key` | Set or replace the builder's own key. |
-| DELETE | `/api/bongos/me/art-key/own` | `any-builder` | — | Remove the builder's own key (back to "not set"). |
-| POST | `/api/bongos/me/art-key/storage-init` | `archon` | — | Archon-only: provision the server's secret-box master key so per-builder key storage can turn on (task 1398, blocker 41). |
 | PATCH | `/api/bongos/me/disciplines` | `any-builder` | `preferred_disciplines` | Self-service edit of the authenticated builder's preferred disciplines (migrations 027 + 086 / V3.R80). |
 | GET | `/api/bongos/me/display-name` | `any-builder` | — | Per-builder DISPLAY NAME (task 1669). |
 | PATCH | `/api/bongos/me/display-name` | `any-builder` | _undocumented_ | PATCH the display name. |
@@ -360,7 +349,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/public/repo-info` | `public` | — | GitHub URL bases for the deployed checkout (V3.R13-followup-2 task 411). |
 | GET | `/api/bongos/public/tasks/:id` | `public` | — | Single-task resolver for "#NNN" deep links. |
 | GET | `/api/bongos/public/uptime` | `public` | — | Uptime: current status + 90-day history bucketed by hour. |
-| GET | `/api/bongos/public/versions` | `public` | — | read-only surface for status.example.com. |
+| GET | `/api/bongos/public/versions` | `public` | — | read-only surface for status.amazonprimea.com. |
 
 ## `search` (2)
 
@@ -430,7 +419,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 |---|---|---|---|---|
 | GET | `/api/bongos/versions` | `public` | — | read-only version list; mirrors /public/versions. |
 | POST | `/api/bongos/versions` | `archon` | `id`, `name`, `status`, `done_when`, `scope_doc_path`, `criteria` | POST /versions — create a version + its done-when criteria in one call. |
-| GET | `/api/bongos/versions/:id/done-when` | `public` | — | Public: status.example.com fetches this every 60s alongside other public/* surfaces. |
+| GET | `/api/bongos/versions/:id/done-when` | `public` | — | Public: status.amazonprimea.com fetches this every 60s alongside other public/* surfaces. |
 | POST | `/api/bongos/versions/:id/done-when` | `archon` | `criterion_id`, `criterion_md`, `goal_id`, `sort_order` | Auth (Archon): create a done-when criterion at RUNTIME. |
 | GET | `/api/bongos/versions/:id/progress` | `public` | — | Per-criterion progress rollup: each done-when criterion → the tasks that gate it (task_criteria, migration 055) → live statuses → what re… |
 | GET | `/api/bongos/versions/close-suggestions` | `public` | — | Close-flow gate suggestions for every version still 'building'. |