@bongos/core 1.17.0 → 1.17.2

package/docs/api/openapi.json

@@ -4281,6 +4281,56 @@
       }
     },
     "/goals/{id}/requests": {
+      "get": {
+        "operationId": "get_goals_id_requests",
+        "tags": [
+          "goals"
+        ],
+        "summary": "GET /goals/:id/requests",
+        "description": "GET /goals/:id/requests — the goal's own pending invite/join-request queue (task 1953): every pending row on THIS goal, both kinds — outstanding invites the goal has sent (awaiting the invitee) and join-requests awaiting approval. db.listPendingRequestsForGoal was built for this route in task 1952's landing but never wired to HTTP; this is the goals-page manager view alongside the cross-goal GET /goals/inbox. rank: any-builder (requireBuilder) + the in-handler owner|manager|Archon gate (authorizeGoalManagement) — same wall as visibility/invite/request-respond.\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/GetGoalsIdRequestsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
       "post": {
         "operationId": "post_goals_id_requests",
         "tags": [
@@ -4415,6 +4465,67 @@
         ]
       }
     },
+    "/goals/{id}/requests/{reqId}/withdraw": {
+      "post": {
+        "operationId": "post_goals_id_requests_reqId_withdraw",
+        "tags": [
+          "goals"
+        ],
+        "summary": "POST /goals/:id/requests/:reqId/withdraw",
+        "description": "POST /goals/:id/requests/:reqId/withdraw — the requester cancels their OWN pending join-request (task 1953): the symmetric self-served mirror of a manager's deny. Sets status='cancelled' (kept as the audit trail, like a deny's 'rejected'); never touches an invitation row. rank: any-builder (requireBuilder) + the in-handler authorizeWithdrawJoinRequest.\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`."
+          },
+          {
+            "name": "reqId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `reqId`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostGoalsIdRequestsReqIdWithdrawResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/goals/{id}/scope": {
       "post": {
         "operationId": "post_goals_id_scope",
@@ -6586,6 +6697,44 @@
         ]
       }
     },
+    "/modules/submissions": {
+      "get": {
+        "operationId": "get_modules_submissions",
+        "tags": [
+          "modules"
+        ],
+        "summary": "GET /modules/submissions",
+        "description": "GET /api/gds/modules/submissions?status=&module_key= — the upstreaming review queue (task 1771 reads this). Metadata only — no file contents (a future GET .../:id can add a with-files fetch if the review UI needs it). rank: metic+archon — the review queue, same rank as filing into it.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "x-rank": "metic+archon",
+        "x-source": "src/bongos/routes/modules.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetModulesSubmissionsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/modules/{key}/enable": {
       "post": {
         "operationId": "post_modules_key_enable",
@@ -6656,7 +6805,7 @@
           "modules"
         ],
         "summary": "POST /modules/:key/submit",
-        "description": "the \"submit this module for review\" front door (501 until the submit pipeline, task 1770, ships).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "POST /api/gds/modules/:key/submit — ADR 0107 §1 upstreaming submission. task 1770. Body: { signed_by?: \"Name <email>\" }. Re-runs the §4 AGPL/publish pre-check + requires a DCO-style sign-off against THIS box's OWN on-disk copy of modules/:key (the authoritative check — a local `bongos module check` pass on a builder's box is a courtesy, not proof, if the module's changes aren't committed + shipped + deployed here yet). signed_by records a NEW sign-off only if none is on file; an existing .upstream-signoff.json is reused as-is (not overwritten). rank: metic+archon — files into a shared review queue, not just a toggle for the caller.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
         "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/modules.js",
         "parameters": [
@@ -6670,12 +6819,30 @@
             "description": "Path parameter `key`."
           }
         ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostModulesKeySubmitRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
         "responses": {
           "200": {
-            "description": "Success."
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostModulesKeySubmitResponse"
+                }
+              }
+            }
           },
           "400": {
-            "$ref": "#/components/responses/BadRequest"
+            "$ref": "#/components/responses/ValidationFailed"
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
@@ -6878,6 +7045,34 @@
         "security": []
       }
     },
+    "/provisioning/github-app/status": {
+      "get": {
+        "operationId": "get_provisioning_github_app_status",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/github-app/status",
+        "description": "GET /provisioning/github-app/status?state=<> — the PUBLIC progress read the onboarding callback page polls (task 2096) to know when setup is done + where to send the owner. Same public-by-state model as the callback: the unguessable, single-use `state` token is the only key, and the response reveals only the manifest lifecycle status + the instance's own (already-public) domain — never a secret. Per-IP rate-limited because the page polls it every ~3s. `ready` is true iff the manifest reached 'done' (creds placed + /healthz verified) — the page then auto-redirects to https://<domain>. rank: public — no session, no mutation, no secret; an unknown state is a 404 no-op.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/provisioning/routes/provisioning.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetProvisioningGithubAppStatusResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
     "/provisioning/health": {
       "get": {
         "operationId": "get_provisioning_health",
@@ -7203,6 +7398,34 @@
         ]
       }
     },
+    "/provisioning/onboard-plan": {
+      "get": {
+        "operationId": "get_provisioning_onboard_plan",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/onboard-plan",
+        "description": "GET /provisioning/onboard-plan?mode=greenfield|adopt — the CANONICAL onboarding step sequence (task 2085; goal 35 / criterion 165: \"the canonical step sequence is the source of truth; skill/CLI/hall are forms over it\"). The branded /create page + the hall wizard fetch it so their human-steps checklist can't drift from the CLI's (scripts/gds/onboard.js reads the same modules/provisioning/onboard-plan.js). rank: public — the signed-out /create landing page reads it; it is the same public runbook the /new-project skill documents (no write, no secret).\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/provisioning/routes/provisioning.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetProvisioningOnboardPlanResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
     "/provisioning/tls-check": {
       "get": {
         "operationId": "get_provisioning_tls_check",
@@ -10250,6 +10473,15 @@
           "cross_goals_considered"
         ]
       },
+      "GetGoalsIdRequestsResponse": {
+        "type": "object",
+        "properties": {
+          "requests": {}
+        },
+        "required": [
+          "requests"
+        ]
+      },
       "GetGoalsIdResponse": {
         "type": "object",
         "properties": {
@@ -10530,6 +10762,15 @@
           "submit_pipeline_live"
         ]
       },
+      "GetModulesSubmissionsResponse": {
+        "type": "object",
+        "properties": {
+          "submissions": {}
+        },
+        "required": [
+          "submissions"
+        ]
+      },
       "GetOverrideRequestsResponse": {
         "type": "object",
         "properties": {
@@ -10548,6 +10789,27 @@
           "instances"
         ]
       },
+      "GetProvisioningGithubAppStatusResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "status": {},
+          "ready": {},
+          "terminal": {},
+          "domain": {},
+          "instance_status": {}
+        },
+        "required": [
+          "ok",
+          "status",
+          "ready",
+          "terminal",
+          "domain",
+          "instance_status"
+        ]
+      },
       "GetProvisioningHealthResponse": {
         "type": "object",
         "properties": {
@@ -10583,6 +10845,17 @@
           "instances"
         ]
       },
+      "GetProvisioningOnboardPlanResponse": {
+        "type": "object",
+        "properties": {
+          "mode": {},
+          "steps": {}
+        },
+        "required": [
+          "mode",
+          "steps"
+        ]
+      },
       "GetPublicBlockersIdResponse": {
         "type": "object",
         "properties": {
@@ -12305,6 +12578,19 @@
           "request"
         ]
       },
+      "PostGoalsIdRequestsReqIdWithdrawResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "request": {}
+        },
+        "required": [
+          "ok",
+          "request"
+        ]
+      },
       "PostGoalsIdRequestsRequest": {
         "type": "object",
         "properties": {
@@ -12807,6 +13093,29 @@
           "note"
         ]
       },
+      "PostModulesKeySubmitRequest": {
+        "type": "object",
+        "properties": {
+          "signed_by": {
+            "type": "string",
+            "maxLength": 200
+          }
+        },
+        "additionalProperties": false
+      },
+      "PostModulesKeySubmitResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "submission": {}
+        },
+        "required": [
+          "ok",
+          "submission"
+        ]
+      },
       "PostOverrideRequestsIdDecideRequest": {
         "type": "object",
         "properties": {
@@ -13712,9 +14021,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 224,
-  "x-schema-count": 243,
+  "x-endpoint-count": 229,
+  "x-schema-count": 250,
   "x-undocumented-bodies": 8,
-  "x-response-schemas": 164,
+  "x-response-schemas": 170,
   "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. 224 endpoints across 38 route files.
+> **Generated from the live route files** — the route file is authoritative. 229 endpoints across 38 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`.
@@ -181,7 +181,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` (21)
+## `goals` (23)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -198,8 +198,10 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/goals/:id/members` | `any-builder` | `role`, `builder_id` | POST /goals/:id/members — the goal's own authority (owner \| manager \| Archon) invites a builder to the goal (task 1762: widened from Arch… |
 | PATCH | `/api/bongos/goals/:id/members/:builderId` | `any-builder` | `role` | PATCH /goals/:id/members/:builderId — role management by the goal's own authority (task 1735): the owner, a manager, or an Archon promote… |
 | POST | `/api/bongos/goals/:id/reopen` | `metic+archon` | — | POST /goals/:id/reopen — bring an archived goal back to open (ADR 0086 §6 / BV1.R64). |
+| GET | `/api/bongos/goals/:id/requests` | `any-builder` | — | GET /goals/:id/requests — the goal's own pending invite/join-request queue (task 1953): every pending row on THIS goal, both kinds — outs… |
 | POST | `/api/bongos/goals/:id/requests` | `any-builder` | `note` | POST /goals/:id/requests — a builder asks to join a (private or protected) goal (task 1952 / ADR 0112). |
 | 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). |
 | 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). |
@@ -303,13 +305,14 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/memory/files` | `any-builder` | — | GET /memory/files — list the AUTHENTICATED builder's memory files (metadata only, no content). |
 | POST | `/api/bongos/memory/sync` | `any-builder` | `files` | POST /memory/sync — push a builder's local memory files to the server. |
 
-## `modules` (3)
+## `modules` (4)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/modules` | `any-builder` | — | list every on-disk module with attribution + provenance (same read gate as the atlas/primer pages). |
 | POST | `/api/bongos/modules/:key/enable` | `metic+archon` | `enabled` | toggling a module changes running behavior for the whole instance, not just the caller. |
-| POST | `/api/bongos/modules/:key/submit` | `metic+archon` | — | the "submit this module for review" front door (501 until the submit pipeline, task 1770, ships). |
+| POST | `/api/bongos/modules/:key/submit` | `metic+archon` | `signed_by` | POST /api/gds/modules/:key/submit — ADR 0107 §1 upstreaming submission. |
+| GET | `/api/bongos/modules/submissions` | `metic+archon` | — | GET /api/gds/modules/submissions?status=&module_key= — the upstreaming review queue (task 1771 reads this). |
 
 ## `override-requests` (2)
 
@@ -318,13 +321,14 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/override-requests` | `archon` | — | GET /override-requests?status=open — Archon queue. |
 | POST | `/api/bongos/override-requests/:id/decide` | `archon` | `decision`, `note` | POST /override-requests/:id/decide — body: { decision: 'approve'\|'deny', note? } On approve, atomically flips the task completed→confirme… |
 
-## `provisioning` (11)
+## `provisioning` (13)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/provisioning/fleet` | `archon` | — | GET /provisioning/fleet — the full instance roster across all owners. |
 | GET | `/api/bongos/provisioning/fleet/cost-ledger` | `archon` | — | GET /provisioning/fleet/cost-ledger — per-instance monthly estimate + total. |
 | GET | `/api/bongos/provisioning/github-app/callback` | `public` | — | GET /provisioning/github-app/callback?code=&state= — GitHub redirects the owner's BROWSER here after they approve the App Manifest (task … |
+| 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`, `tier` | POST /provisioning/instances — request a new instance. |
@@ -332,6 +336,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/provisioning/instances/:id/force-teardown` | `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… |
 | POST | `/api/bongos/provisioning/instances/:id/teardown` | `any-builder` | — | POST /provisioning/instances/:id/teardown — request teardown of the caller's OWN instance. |
+| GET | `/api/bongos/provisioning/onboard-plan` | `public` | — | GET /provisioning/onboard-plan?mode=greenfield\|adopt — the CANONICAL onboarding step sequence (task 2085; goal 35 / criterion 165: "the c… |
 | GET | `/api/bongos/provisioning/tls-check` | `public` | — | GET /provisioning/tls-check?domain=<host> — the Caddy on-demand-TLS ALLOW-LIST (ADR 0111 §4, task P4 task 1945). |
 
 ## `public` (18)

package/docs/architecture.md

@@ -69,7 +69,7 @@ The product is organized as a small kernel (`src/`) + **19 modules** under `modu
 - **Post-merge branch cleanup (standard practice):** Every feature branch that lands on main via `--no-ff` merge gets deleted on origin once the deploy succeeds. The merge commit itself preserves the branch's history in main, so the named ref isn't carrying any signal — keeping it just clutters GitHub's branch list and tricks the UI into offering empty PRs against zero-diff branches. The auto-merge in [`scripts/gds/ship.js`](../scripts/gds/ship.js) does this automatically after `~/deploy.sh` returns 0; the manual [`/merge-mode`](../.claude/skills/merge-mode/SKILL.md) flow follows the same step 5b. Local refs and worktree directories stay — only the origin branch and the local tracking ref (cleaned on next `git fetch --prune`) go.
 - **Local dev machine:** Lars's MacBook Air (Apple Silicon, macOS Sequoia). Tooling installed via Homebrew at `/opt/homebrew/`. Node v26.0.0 locally; `package.json` declares `"engines": { "node": ">=22" }`. Single ed25519 SSH key (`~/.ssh/id_ed25519`) authenticates to GitHub and droplet.
 - **Smoke tests:** lightweight scripts in `/tmp/colyseus-*-smoketest.js` verify joinOrCreate, move protocol, interact, identity, queue. Run any after deploy with `node /tmp/colyseus-<name>-smoketest.js`.
-- **Repo topology today vs. the configurable-root future ([ADR 0108](adr/<redacted>.md)):** everything above describes the current **single checkout** — `git reset --hard` deploy, `resolveCoreRoot()`/`resolveInstanceRoot()` ([`src/instance-config.js`](../src/instance-config.js)) both resolving to this same repo root. ADR 0108 lands (Mercury-first, then Example last) a model where Example instead installs a versioned `@cloudbongos/core` npm package and deploy becomes `git pull` (the instance repo) → `npm ci` (the pinned core) → migrate → restart — no more `git reset --hard` on a shared checkout. This section gets rewritten for the new topology once Example actually splits (ADR 0108 §6, task 1884/W4); until then it is unchanged and accurate.
+- **Repo topology today vs. the configurable-root future ([ADR 0108](adr/<redacted>.md)):** everything above describes the current **single checkout** — `git reset --hard` deploy, `resolveCoreRoot()`/`resolveInstanceRoot()` ([`src/instance-config.js`](../src/instance-config.js)) both resolving to this same repo root. ADR 0108 lands (Mercury-first, then Example last) a model where Example instead installs a versioned `@bongos/core` npm package and deploy becomes `git pull` (the instance repo) → `npm ci` (the pinned core) → migrate → restart — no more `git reset --hard` on a shared checkout. This section gets rewritten for the new topology once Example actually splits (ADR 0108 §6, task 1884/W4); until then it is unchanged and accurate.
 
 **Database (`example` on Postgres 16, peer auth as `lars`):**
 
@@ -93,7 +93,7 @@ builders(id, github_id UNIQUE, github_login, display_name, avatar_url, total_cre
          gemini_key_enc, gemini_key_last4, gemini_key_set_at)  -- mig 122: per-builder Gemini key, AES-256-GCM at rest (ADR 0073); master key BUILDER_SECRET_KEY in server env only
   rank text NOT NULL DEFAULT 'xenos' (mig 023; default flipped to xenos in mig 029)
        CHECK IN 16-value ladder; LIVE: archon|metic|xenos (three-rank model, #360/ADR 0018)
-  karma integer NOT NULL DEFAULT 0 (mig 040) -- good-citizenship track alongside drachmae
+  karma integer NOT NULL DEFAULT 0 (mig 040) -- good-citizenship track alongside example
        (=total_credits); append-only karma_log + AFTER INSERT trigger keep it in sync
   status text DEFAULT 'active' (mig 025) -- 'active'|'inactive'; a deactivated builder can't claim (#307)
   system_role text NULL (mig 065) -- NULL for every human; 'bfg' = the BFG service principal
@@ -168,7 +168,7 @@ task_grades(id, task_id UNIQUE, score NUMERIC(3,1), passed bool, threshold NUMER
 grade_attempts(id, task_id, builder_id?, passed bool, score NUMERIC(3,1), attempted_at)
             -- mig 064 (6D.6, ADR 0027): APPEND-ONLY, one row per grade run, so
             -- re-grade thrash is countable (task_grades keeps only the latest)
-session_records(id, session_id UNIQUE, builder_id, task_ids bigint[], drachmae_earned,
+session_records(id, session_id UNIQUE, builder_id, task_ids bigint[], example_earned,
             total_tokens, duration_seconds, started_at, ended_at, uploaded_at,
             detail jsonb, metrics jsonb)  -- mig 062 (6D.1, ADR 0027): per-shipped-session
             -- secret-scrubbed digest (per-turn metadata + short snippets); idx on

package/docs/branding-contract.md

@@ -19,7 +19,7 @@ env override   →   instance config (config/branding.json)   →   neutral star
 
 | Path | Meaning |
 |---|---|
-| `identity.productName` | The product name (e.g. "Off the Boats"). **Required.** |
+| `identity.productName` | The product name (e.g. "Example"). **Required.** |
 | `identity.worldName` | The in-world / civilization name rendered at runtime (e.g. "Example"). **Required.** |
 | `identity.company` | `{ name, site }` of the operating company (may be empty). |
 | `llmProjectName` | The project name injected into grader / architect / onboarding **LLM prompts**, so a non-OTB instance is graded against its own identity. **Required.** |
@@ -27,13 +27,14 @@ env override   →   instance config (config/branding.json)   →   neutral star
 | `domains.buildersOrigin` / `statusOrigin` | Hall + status origins. **These three (`publicOrigin`/`buildersOrigin`/`statusOrigin`) are the docs-discovery contract** ([ADR 0114](adr/<redacted>.md)): the hall is the canonical doc-reading surface, `/docs` on `publicOrigin` renders the API reference, the status page is the outage fallback. `GET <publicOrigin>/api/bongos` re-advertises them (`hall`/`status`/`public`) so an agent resolves the surfaces with no hard-coded host. |
 | `domains.cookieDomain` | Session cookie domain (`""` = host-only — the safe default; never widen to a parent domain by accident). |
 | `domains.oauthOrigin` | Canonical sign-in origin. |
+| `domains.provisioningOrigin` | **Optional.** Control-plane front-door origin the [provisioning module](../../modules/provisioning/CLAUDE.md) uses to build a new customer's GitHub-App `redirect_url`. Set it when the control plane co-hosts a game whose `publicOrigin` is the game's own domain (OTB = customer 0) so the customer's App carries the PLATFORM brand (e.g. `https://get.cloudbongos.com`), not the game's. **Falls back to `publicOrigin` when unset** — an instance whose `publicOrigin` is already the platform needs no override. Env-overridable: `<PREFIX>_PROVISIONING_ORIGIN`. ([#2101](https://example.com/builders#/task/2101)) |
 | `domains.devBoxBase` | Apex zone the **proxied** browser-terminal + sandbox hosts ride (`term-<login>.<devBoxBase>`, `sandbox-<login>.<devBoxBase>`). Must be a one-label-under-apex zone so free edge TLS (`*.<apex>`) covers it — a two-label host fails edge TLS (the [#771](https://example.com/builders#/task/771) lesson). Empty ⇒ no managed boxes. |
 | `domains.sshBoxBase` | Zone for the **legacy direct-IP SSH** box host (`box-<login>.<sshBoxBase>`, unproxied). Deliberately distinct from `devBoxBase` (one proxied/edge-TLS, one direct-IP). |
 | `domains.sandboxPrefix` / `termPrefix` | Subdomain prefixes for the sandbox-preview + browser-terminal hosts. |
 | `repo` | `{ owner, name }` GitHub binding. |
 | `db.database` | DB name the GDS pool connects to when neither `DATABASE_URL` nor `PGHOST`/`PGDATABASE` is set (`src/bongos/pool.js`, ADR 0062 §5). `null` in the neutral starter = **fail loud** rather than silently target a host DB. |
-| `currency` | `{ label, symbol }` — the reward unit label (e.g. "drachmae"). Display only. |
-| `reward` | `{ marginPct, usdPeg }` — the per-instance reward POLICY the economy module reads ([ADR 0054](adr/<redacted>.md), task 2009): the cost-plus margin percent (default `20`) and the drachmae-per-USD peg (default `1`). A committed, code-reviewed change — not a live UI knob. Omit ⇒ code defaults (20% margin, 1:1 peg). |
+| `currency` | `{ label, symbol }` — the reward unit label (e.g. "example"). Display only. |
+| `reward` | `{ marginPct, usdPeg }` — the per-instance reward POLICY the economy module reads ([ADR 0054](adr/<redacted>.md), task 2009): the cost-plus margin percent (default `20`) and the example-per-USD peg (default `1`). A committed, code-reviewed change — not a live UI knob. Omit ⇒ code defaults (20% margin, 1:1 peg). |
 | `models` | `{ main, subagentDefault, subagentRoutine }` — the per-instance subagent model-allocation DEFAULT the builder-settings module reads (task 2011): the tier for the main session, subagent-default work, and routine plumbing (tiers: `haiku`/`sonnet`/`opus`/`fable`). A per-builder override resolves over this. Omit ⇒ code defaults (`opus`/`opus`/`haiku`). |
 | `tracks` | The configurable version-track set (replaces the hardcoded `product\|internal`). |
 | `theme` | `{ palette, mode }` — palette file ref + theme mode. |
@@ -59,7 +60,7 @@ The browser never sees the full pack — only the **client-safe projection** `cl
 - **On-box (hall + status served from the droplet):** injected synchronously by `mountInternalSurfaces` (`src/bongos/serve-internal.js` → `injectBrandingGlobal`) into the page `<head>` as **`window.__BRANDING__`** (the strings) **plus theme markup** (`themeMarkup` → a `:root` palette/font-var override `<style>`, the web-font `<link>`s, and the favicon `<link>`). The `<style>` lands after the page's own stylesheet so the pack wins. No fetch, no flash-of-default.
 - **Off-box (the GitHub-Pages status page):** read cross-origin from **`GET /api/gds/public/branding`**.
 
-R56 seeded the projection with the configurable **currency label** (`public-builders/brand-apply.js` fills `[data-currency-label]` / `[data-currency-tmpl]` markup + `window.OTBBranding.currencyLabel()`). R57 widens it to the **LOOK** — `theme.ui` (palette + fonts + favicon; note this is the WEB theme, distinct from the server-only `theme.palette` game pixel-art path) — and the **rank display-label map** (`window.OTB.rankLabel()` reads `rankLabels`; the rank ENUM stays Greek by decision, only the label is presentation). The remaining archaic **page copy + identity strings** (titles, ledes, "washed ashore" flavor) are tracked as the R57 copy-pack follow-up.
+R56 seeded the projection with the configurable **currency label** (`public-builders/brand-apply.js` fills `[data-currency-label]` / `[data-currency-tmpl]` markup + `window.OTBBranding.currencyLabel()`). R57 widens it to the **LOOK** — `theme.ui` (palette + fonts + favicon; note this is the WEB theme, distinct from the server-only `theme.palette` game pixel-art path) — and the **rank display-label map** (`window.OTB.rankLabel()` reads `rankLabels`; the rank ENUM stays Greek by decision, only the label is presentation). The remaining themed **page copy + identity strings** (titles, ledes, world-flavor copy) are tracked as the R57 copy-pack follow-up.
 
 ## Branding a new instance
 

package/docs/canonical-permissions.md

@@ -86,7 +86,7 @@ forming the ordered claim-gate tier **`xenos` (1) < `thetes` (2) < `metic` (3) <
   `db.claimTask` / `claimTasksBatch`, returns `rank_too_low_for_task`). Cannot triage, resolve
   blockers, or run planning/priority sessions. This is also the tier a deactivated/offboarded builder
   is dropped to by `/builder-exit` (migration `025`); for them `status='inactive'` additionally blocks
-  *all* claims. Either way, drachmae / credit history / shipped-task attribution are preserved.
+  *all* claims. Either way, example / credit history / shipped-task attribution are preserved.
 
 Everything else on the citizen ladder (`strategos`…`zeugitai`), the divine tiers, and the other
 sub-citizen tiers (`periokoi`/`doulos`/`helot`) stay **reserved but unwired** — promoting anyone to

package/docs/design/vanilla-hall-ui-redesign-scope.md

@@ -227,7 +227,7 @@ Not layout, but it rides along. Most of this already flows through the brand pac
 | "The Builders' Hall" · "chronicles of the city" epigraph | "Builders" · no epigraph | brand pack + markup |
 | "scroll" (section) | card / panel | markup + CSS class |
 | "Thy Standing in the City" | Standing / Profile | markup |
-| drachmae | credits (`currency-label`) | brand pack (already) |
+| example | credits (`currency-label`) | brand pack (already) |
 | Honours / laurels | Achievements | markup |
 | "Works Wrought by Thy Hand" | Your work | markup |
 | "Marks of the Inspector" | Reviews / quality marks | markup |