@bongos/core 1.18.0 → 1.18.18

package/clients/bongos-client/index.mjs

@@ -111,8 +111,12 @@ export function createClient(opts = {}) {
       postAuthAppPairPoll: (args) => request("POST", "/auth/app-pair/poll", { hasBody: true }, args),
       // POST /auth/app-pair/start — rank: public — POST /auth/app-pair/start
       postAuthAppPairStart: (args) => request("POST", "/auth/app-pair/start", { hasBody: true }, args),
+      // POST /auth/backchannel-logout — rank: public — POST /auth/backchannel-logout
+      postAuthBackchannelLogout: (args) => request("POST", "/auth/backchannel-logout", { hasBody: true }, args),
       // POST /auth/cli-token/issue — rank: any-builder — POST /auth/cli-token/issue
       postAuthCliTokenIssue: (args) => request("POST", "/auth/cli-token/issue", { hasBody: true }, args),
+      // POST /auth/device/exchange — rank: public — POST /auth/device/exchange
+      postAuthDeviceExchange: (args) => request("POST", "/auth/device/exchange", { hasBody: true }, args),
       // POST /auth/device/poll — rank: public — POST /auth/device/poll
       postAuthDevicePoll: (args) => request("POST", "/auth/device/poll", { hasBody: true }, args),
       // POST /auth/device/start — rank: public — POST /auth/device/start
@@ -129,6 +133,8 @@ export function createClient(opts = {}) {
       postAuthRevoke: (args) => request("POST", "/auth/revoke", { hasBody: true }, args),
       // POST /auth/revoke-all — rank: archon — POST /auth/revoke-all
       postAuthRevokeAll: (args) => request("POST", "/auth/revoke-all", { hasBody: true }, args),
+      // GET /auth/web/admission-status — rank: public — GET /auth/web/admission-status
+      getAuthWebAdmissionStatus: (args) => request("GET", "/auth/web/admission-status", { hasBody: false }, args),
       // GET /auth/web/callback — rank: public — GET /auth/web/callback
       getAuthWebCallback: (args) => request("GET", "/auth/web/callback", { hasBody: false }, args),
       // GET /auth/web/start — rank: public — GET /auth/web/start
@@ -177,6 +183,8 @@ export function createClient(opts = {}) {
       getBoxManagedSettings: (args) => request("GET", "/box/managed-settings", { hasBody: false }, args),
       // GET /box/me — rank: any-builder — GET /box/me
       getBoxMe: (args) => request("GET", "/box/me", { hasBody: false }, args),
+      // GET /box/scope — rank: any-builder — GET /box/scope
+      getBoxScope: (args) => request("GET", "/box/scope", { hasBody: false }, args),
       // GET /box/source-access — rank: any-builder — GET /box/source-access
       getBoxSourceAccess: (args) => request("GET", "/box/source-access", { hasBody: false }, args),
       // GET /box/ssh-key — rank: any-builder — GET /box/ssh-key
@@ -244,12 +252,6 @@ export function createClient(opts = {}) {
       // POST /cost — rank: any-builder — POST /cost
       postCost: (args) => request("POST", "/cost", { hasBody: true }, args),
     },
-    "demo": {
-      // GET /demo/health — rank: public — GET /demo/health
-      getDemoHealth: (args) => request("GET", "/demo/health", { hasBody: false }, args),
-      // POST /demo/ping — rank: metic+archon — POST /demo/ping
-      postDemoPing: (args) => request("POST", "/demo/ping", { hasBody: true }, args),
-    },
     "dependencies": {
       // DELETE /dependencies — rank: archon — DELETE /dependencies
       deleteDependencies: (args) => request("DELETE", "/dependencies", { hasBody: false }, args),
@@ -276,6 +278,12 @@ export function createClient(opts = {}) {
       // POST /gate-approvals/{pr}/approve — rank: archon — POST /gate-approvals/:pr/approve
       postGateApprovalsPrApprove: (args) => request("POST", "/gate-approvals/{pr}/approve", { hasBody: true }, args),
     },
+    "github": {
+      // GET /github/repos — rank: any-builder — GET /github/repos
+      getGithubRepos: (args) => request("GET", "/github/repos", { hasBody: false }, args),
+      // POST /github/repos — rank: any-builder — POST /github/repos
+      postGithubRepos: (args) => request("POST", "/github/repos", { hasBody: true }, args),
+    },
     "goals": {
       // GET /goals — rank: any-builder — GET /goals
       getGoals: (args) => request("GET", "/goals", { hasBody: false }, args),
@@ -343,6 +351,8 @@ export function createClient(opts = {}) {
       getInboxId: (args) => request("GET", "/inbox/{id}", { hasBody: false }, args),
       // PATCH /inbox/{id} — rank: metic+archon — PATCH /inbox/:id
       patchInboxId: (args) => request("PATCH", "/inbox/{id}", { hasBody: true }, args),
+      // POST /inbox/{id}/ratify — rank: archon — POST /inbox/:id/ratify
+      postInboxIdRatify: (args) => request("POST", "/inbox/{id}/ratify", { hasBody: true }, args),
     },
     "instance": {
       // GET /instance — rank: public — GET /instance
@@ -375,16 +385,6 @@ export function createClient(opts = {}) {
       getMeAchievements: (args) => request("GET", "/me/achievements", { hasBody: false }, args),
       // POST /me/anthropic-link — rank: any-builder — POST /me/anthropic-link
       postMeAnthropicLink: (args) => request("POST", "/me/anthropic-link", { hasBody: true }, args),
-      // GET /me/art-key — rank: any-builder — GET /me/art-key
-      getMeArtKey: (args) => request("GET", "/me/art-key", { hasBody: false }, args),
-      // DELETE /me/art-key/own — rank: any-builder — DELETE /me/art-key/own
-      deleteMeArtKeyOwn: (args) => request("DELETE", "/me/art-key/own", { hasBody: false }, args),
-      // GET /me/art-key/own — rank: any-builder — GET /me/art-key/own
-      getMeArtKeyOwn: (args) => request("GET", "/me/art-key/own", { hasBody: false }, args),
-      // PUT /me/art-key/own — rank: any-builder — PUT /me/art-key/own
-      putMeArtKeyOwn: (args) => request("PUT", "/me/art-key/own", { hasBody: true }, args),
-      // POST /me/art-key/storage-init — rank: archon — POST /me/art-key/storage-init
-      postMeArtKeyStorageInit: (args) => request("POST", "/me/art-key/storage-init", { hasBody: true }, args),
       // PATCH /me/disciplines — rank: any-builder — PATCH /me/disciplines
       patchMeDisciplines: (args) => request("PATCH", "/me/disciplines", { hasBody: true }, args),
       // GET /me/display-name — rank: any-builder — GET /me/display-name
@@ -429,6 +429,10 @@ export function createClient(opts = {}) {
       getMemoryBfgBuildersBuilderIdFiles: (args) => request("GET", "/memory/bfg/builders/{builderId}/files", { hasBody: false }, args),
       // POST /memory/builders/{builderId}/bfg-write — rank: bfg-principal — POST /memory/builders/:builderId/bfg-write
       postMemoryBuildersBuilderIdBfgWrite: (args) => request("POST", "/memory/builders/{builderId}/bfg-write", { hasBody: true }, args),
+      // GET /memory/builders/{builderId}/file — rank: archon — GET /memory/builders/:builderId/file
+      getMemoryBuildersBuilderIdFile: (args) => request("GET", "/memory/builders/{builderId}/file", { hasBody: false }, args),
+      // GET /memory/builders/{builderId}/files — rank: archon — GET /memory/builders/:builderId/files
+      getMemoryBuildersBuilderIdFiles: (args) => request("GET", "/memory/builders/{builderId}/files", { hasBody: false }, args),
       // DELETE /memory/file — rank: any-builder — DELETE /memory/file
       deleteMemoryFile: (args) => request("DELETE", "/memory/file", { hasBody: true }, args),
       // GET /memory/file — rank: any-builder — GET /memory/file
@@ -448,12 +452,38 @@ export function createClient(opts = {}) {
       // GET /modules/submissions — rank: metic+archon — GET /modules/submissions
       getModulesSubmissions: (args) => request("GET", "/modules/submissions", { hasBody: false }, args),
     },
+    "myProjects": {
+      // GET /my-projects — rank: any-builder — GET /my-projects
+      getMyProjects: (args) => request("GET", "/my-projects", { hasBody: false }, args),
+      // POST /my-projects/{clientId}/leave — rank: any-builder — POST /my-projects/:clientId/leave
+      postMyProjectsClientIdLeave: (args) => request("POST", "/my-projects/{clientId}/leave", { hasBody: true }, args),
+      // GET /my-projects/invites — rank: any-builder — GET /my-projects/invites
+      getMyProjectsInvites: (args) => request("GET", "/my-projects/invites", { hasBody: false }, args),
+      // POST /my-projects/invites/{clientId}/accept — rank: any-builder — POST /my-projects/invites/:clientId/accept
+      postMyProjectsInvitesClientIdAccept: (args) => request("POST", "/my-projects/invites/{clientId}/accept", { hasBody: true }, args),
+      // POST /my-projects/invites/{clientId}/decline — rank: any-builder — POST /my-projects/invites/:clientId/decline
+      postMyProjectsInvitesClientIdDecline: (args) => request("POST", "/my-projects/invites/{clientId}/decline", { hasBody: true }, args),
+      // POST /my-projects/join — rank: any-builder — POST /my-projects/join
+      postMyProjectsJoin: (args) => request("POST", "/my-projects/join", { hasBody: true }, args),
+    },
     "overrideRequests": {
       // GET /override-requests — rank: archon — GET /override-requests
       getOverrideRequests: (args) => request("GET", "/override-requests", { hasBody: false }, args),
       // POST /override-requests/{id}/decide — rank: archon — POST /override-requests/:id/decide
       postOverrideRequestsIdDecide: (args) => request("POST", "/override-requests/{id}/decide", { hasBody: true }, args),
     },
+    "projects": {
+      // GET /projects — rank: archon — GET /projects
+      getProjects: (args) => request("GET", "/projects", { hasBody: false }, args),
+      // POST /projects — rank: archon — POST /projects
+      postProjects: (args) => request("POST", "/projects", { hasBody: true }, args),
+      // PATCH /projects/{id}/featured — rank: archon — PATCH /projects/:id/featured
+      patchProjectsIdFeatured: (args) => request("PATCH", "/projects/{id}/featured", { hasBody: true }, args),
+      // GET /projects/featured — rank: public — GET /projects/featured
+      getProjectsFeatured: (args) => request("GET", "/projects/featured", { hasBody: false }, args),
+      // POST /projects/invite — rank: archon — POST /projects/invite
+      postProjectsInvite: (args) => request("POST", "/projects/invite", { hasBody: true }, args),
+    },
     "provisioning": {
       // GET /provisioning/fleet — rank: archon — GET /provisioning/fleet
       getProvisioningFleet: (args) => request("GET", "/provisioning/fleet", { hasBody: false }, args),
@@ -520,6 +550,10 @@ export function createClient(opts = {}) {
       // GET /public/versions — rank: public — GET /public/versions
       getPublicVersions: (args) => request("GET", "/public/versions", { hasBody: false }, args),
     },
+    "scouting": {
+      // GET /scouting — rank: archon — GET /scouting
+      getScouting: (args) => request("GET", "/scouting", { hasBody: false }, args),
+    },
     "search": {
       // POST /search — rank: any-builder — POST /search
       postSearch: (args) => request("POST", "/search", { hasBody: true }, args),
@@ -527,12 +561,26 @@ export function createClient(opts = {}) {
       postSearchMark: (args) => request("POST", "/search/mark", { hasBody: true }, args),
     },
     "security": {
+      // GET /security/adr — rank: metic+archon — GET /security/adr
+      getSecurityAdr: (args) => request("GET", "/security/adr", { hasBody: false }, args),
       // GET /security/docs — rank: archon — GET /security/docs
       getSecurityDocs: (args) => request("GET", "/security/docs", { hasBody: false }, args),
       // POST /security/docs — rank: archon — POST /security/docs
       postSecurityDocs: (args) => request("POST", "/security/docs", { hasBody: true }, args),
       // GET /security/docs/{slug} — rank: archon — GET /security/docs/:slug
       getSecurityDocsSlug: (args) => request("GET", "/security/docs/{slug}", { hasBody: false }, args),
+      // GET /security/reports — rank: archon — GET /security/reports
+      getSecurityReports: (args) => request("GET", "/security/reports", { hasBody: false }, args),
+      // POST /security/reports — rank: metic+archon — POST /security/reports
+      postSecurityReports: (args) => request("POST", "/security/reports", { hasBody: true }, args),
+      // POST /security/reports/{id}/confirm — rank: archon — POST /security/reports/:id/confirm
+      postSecurityReportsIdConfirm: (args) => request("POST", "/security/reports/{id}/confirm", { hasBody: true }, args),
+      // POST /security/reports/{id}/dispute — rank: archon — POST /security/reports/:id/dispute
+      postSecurityReportsIdDispute: (args) => request("POST", "/security/reports/{id}/dispute", { hasBody: true }, args),
+      // POST /security/reports/{id}/fix — rank: archon — POST /security/reports/:id/fix
+      postSecurityReportsIdFix: (args) => request("POST", "/security/reports/{id}/fix", { hasBody: true }, args),
+      // POST /security/reports/{id}/link-fix — rank: archon — POST /security/reports/:id/link-fix
+      postSecurityReportsIdLinkFix: (args) => request("POST", "/security/reports/{id}/link-fix", { hasBody: true }, args),
     },
     "session": {
       // POST /session/optimize — rank: any-builder — POST /session/optimize
@@ -548,6 +596,22 @@ export function createClient(opts = {}) {
       // GET /sessions/search — rank: archon — GET /sessions/search
       getSessionsSearch: (args) => request("GET", "/sessions/search", { hasBody: false }, args),
     },
+    "sso": {
+      // POST /sso/activity/rollup — rank: public — POST /sso/activity/rollup
+      postSsoActivityRollup: (args) => request("POST", "/sso/activity/rollup", { hasBody: true }, args),
+      // GET /sso/authorize — rank: public — GET /sso/authorize
+      getSsoAuthorize: (args) => request("GET", "/sso/authorize", { hasBody: false }, args),
+      // POST /sso/device/poll — rank: public — POST /sso/device/poll
+      postSsoDevicePoll: (args) => request("POST", "/sso/device/poll", { hasBody: true }, args),
+      // POST /sso/device/start — rank: public — POST /sso/device/start
+      postSsoDeviceStart: (args) => request("POST", "/sso/device/start", { hasBody: true }, args),
+      // POST /sso/membership/check-in — rank: public — POST /sso/membership/check-in
+      postSsoMembershipCheckIn: (args) => request("POST", "/sso/membership/check-in", { hasBody: true }, args),
+      // GET /sso/pubkey — rank: public — GET /sso/pubkey
+      getSsoPubkey: (args) => request("GET", "/sso/pubkey", { hasBody: false }, args),
+      // POST /sso/token — rank: public — POST /sso/token
+      postSsoToken: (args) => request("POST", "/sso/token", { hasBody: true }, args),
+    },
     "tasks": {
       // GET /tasks — rank: any-builder — GET /tasks
       getTasks: (args) => request("GET", "/tasks", { hasBody: false }, args),
@@ -557,7 +621,7 @@ export function createClient(opts = {}) {
       getTasksId: (args) => request("GET", "/tasks/{id}", { hasBody: false }, args),
       // PATCH /tasks/{id} — rank: metic+archon — PATCH /tasks/:id
       patchTasksId: (args) => request("PATCH", "/tasks/{id}", { hasBody: true }, args),
-      // POST /tasks/{id}/abandon — rank: archon — POST /tasks/:id/abandon
+      // POST /tasks/{id}/abandon — rank: metic+archon — POST /tasks/:id/abandon
       postTasksIdAbandon: (args) => request("POST", "/tasks/{id}/abandon", { hasBody: true }, args),
       // POST /tasks/{id}/attest-gate — rank: any-builder — POST /tasks/:id/attest-gate
       postTasksIdAttestGate: (args) => request("POST", "/tasks/{id}/attest-gate", { hasBody: true }, args),
@@ -611,7 +675,7 @@ export function createClient(opts = {}) {
       postVersions: (args) => request("POST", "/versions", { hasBody: true }, args),
       // GET /versions/{id}/done-when — rank: public — GET /versions/:id/done-when
       getVersionsIdDoneWhen: (args) => request("GET", "/versions/{id}/done-when", { hasBody: false }, args),
-      // POST /versions/{id}/done-when — rank: archon — POST /versions/:id/done-when
+      // POST /versions/{id}/done-when — rank: metic+archon — POST /versions/:id/done-when
       postVersionsIdDoneWhen: (args) => request("POST", "/versions/{id}/done-when", { hasBody: true }, args),
       // GET /versions/{id}/progress — rank: public — GET /versions/:id/progress
       getVersionsIdProgress: (args) => request("GET", "/versions/{id}/progress", { hasBody: false }, args),

package/config/branding.neutral.json

@@ -1,5 +1,5 @@
 {
-  "_note": "Cloud Bongos vanilla brand pack — customer 0, the identity Cloud Bongos itself runs on (Amazonprimea is customer 1). The neutral starter every instance resolves over. Light + joyful — 'playing in the clouds', where building software is laying down a beat (ADR 0064). The LOOK ships via theme.ui, injected by src/bongos/serve-internal.js (R57): a Lion-King sunrise backdrop, warm palette, Baloo 2 (display/wordmark) + Quicksand (interface) + Fira Code (code) type, and a bongo-pair favicon. To brand a NEW instance, copy this to config/branding.json and fill it in (docs/branding-fill-prompt.md). Authored by task 1216 / V4.R74. See docs/branding-contract.md.",
+  "_note": "Cloud Bongos vanilla brand pack — customer 0, the identity Cloud Bongos itself runs on. The neutral starter every instance resolves over. Light + joyful — 'playing in the clouds', where building software is laying down a beat (ADR 0064). The LOOK ships via theme.ui, injected by src/bongos/serve-internal.js (R57): a Lion-King sunrise backdrop, warm palette, Baloo 2 (display/wordmark) + Quicksand (interface) + Fira Code (code) type, and a bongo-pair favicon. To brand a NEW instance, copy this to config/branding.json and fill it in (docs/branding-fill-prompt.md). Authored by task 1216 / V4.R74. See docs/branding-contract.md.",
   "identity": {
     "productName": "Cloud Bongos",
     "worldName": "Cloud Bongos",
@@ -10,6 +10,7 @@
     "publicOrigin": "http://localhost:3000",
     "buildersOrigin": "http://localhost:3000",
     "statusOrigin": "http://localhost:3000",
+    "statusDataUrl": "",
     "cookieDomain": "",
     "oauthOrigin": "http://localhost:3000",
     "devBoxBase": "",
@@ -17,12 +18,16 @@
     "sandboxPrefix": "sandbox-",
     "termPrefix": "term-"
   },
+  "auth": {
+    "_note": "Cross-site identity (ADR 0141). idp=false → this instance owns its auth outright (its own GitHub app; the default + the self-hosted path). A HOSTED instance sets idp=true and gets its hub origin + client credentials from env (<PREFIX>_HUB_ORIGIN / _HUB_CLIENT_ID / _HUB_CLIENT_SECRET, written by provisioning) so web + CLI sign-in federate through the Cloud Bongos hub with no GitHub app of its own. Identity is federated; authority stays local.",
+    "idp": false
+  },
   "repo": { "owner": "", "name": "" },
   "db": { "database": null },
   "configDir": "cloudbongos",
   "firstAdmin": "",
   "currency": { "label": "credits", "symbol": "" },
-  "reward": { "marginPct": 20, "usdPeg": 1 },
+  "reward": { "marginPct": 20, "usdPeg": 1, "mode": "cost-plus-and-estimate" },
   "models": { "main": "opus", "subagentDefault": "opus", "subagentRoutine": "haiku" },
   "theme": {
     "palette": "",
@@ -56,5 +61,9 @@
       "ctaLabel": "Try signing in again"
     }
   },
+  "landing": {
+    "_note": "Where a successful sign-in lands when no explicit ?return= / same-apex Referer was carried (auth.js postLoginLanding). Portable default '/builders' — the hall always exists. A platform-home instance points this at its own front door (cloudbongos.com → '/gate/', the orbs). Validated through the open-redirect allowlist; env override <PREFIX>_POST_LOGIN_LANDING. Task 1002240.",
+    "postLogin": "/builders"
+  },
   "envPrefix": "CLOUDBONGOS"
 }

package/config/governance.neutral.json

@@ -0,0 +1,21 @@
+{
+  "_note": "Neutral governance starter — the role TEMPLATES a fresh instance inherits (BV1.R96, ADR 0151). Resolved by modules/governance/config.js with the branding precedence: env override -> config/governance.json (instance) -> this file. TEMPLATES AND DEFAULTS ONLY. Live roles, grants, and per-builder assignments are DB rows (governance_roles / governance_role_permissions / governance_builder_roles), resolved server-side per request by resolver.js — putting a live grant here would make config a second source of authority truth and break ADR 0016. The four seeded rank-roles carry label + description only: their grants derive from catalog.js floors and are materialised by governance_002, so config may relabel a seeded role, never re-grant it. A CUSTOM role template may propose a `permissions` array, but a `system: true` key or a key the catalog does not define is stripped fail-closed — a config file is editable by anyone who can write the checkout, so it is not a trust boundary. Carries NO host identity: a vanilla instance boots sane from this file alone (proved by R102). To customise, copy to config/governance.json and edit there.",
+  "roles": {
+    "xenos": {
+      "label": "Xenos",
+      "description": "Seeded rank-role — the sandboxed entry rank. Own-work + public read."
+    },
+    "thetes": {
+      "label": "Thetes",
+      "description": "Seeded rank-role — graduated newcomer. Adds the general claim queue."
+    },
+    "metic": {
+      "label": "Metic",
+      "description": "Seeded rank-role — the trusted working rank. Adds review/triage/authoring."
+    },
+    "archon": {
+      "label": "Archon",
+      "description": "Seeded rank-role — top authority. Adds the admin + system (non-grantable) powers."
+    }
+  }
+}

package/docs/adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md

@@ -69,6 +69,30 @@ After shipping, the fix was adversarially red-teamed (a 4-dimension panel + per-
 
 **Not yet done (finding `#7`, follow-up):** the permission-path pre-pass (layer 2) runs only client-side in `ship.js`; the server `/grade` and `/confirm` routes don't re-run it. Layer 3 is the server-side backstop today; re-running the pre-pass server-side (the server holds the live rank in `req.builder.rank`) would harden the cooperative path.
 
+## Branch-protection status: re-verified 2026-07-24 (task [#1001840](https://cloudbongos.com/builders#/task/1001840))
+
+The 2026-07-03 authority sweep reported that `main` had since gained live branch protection (required
+checks + code-owner review, direct push blocked), which would have demoted `main-audit.js` from
+*authoritative* to *defense-in-depth*. **That report was wrong.** Re-checked against the live GitHub
+API — every probe agrees there is no protection on `main`:
+
+| Probe | Result |
+|---|---|
+| `GET /repos/:o/:r/branches/main` | `protected: false` |
+| `GET /repos/:o/:r/branches/main/protection` | `404` (a *protected* branch returns `403` to a non-admin, not `404`) |
+| `GET /repos/:o/:r/rulesets` | `[]` |
+| `GET /repos/:o/:r/rules/branches/main` (effective rules; readable by non-admins) | `[]` |
+| `.github/CODEOWNERS` | absent |
+| PR #19, merged 2026-07-24 by a **non-admin** collaborator | `statusCheckRollup: []`, no review decision — a merge that required checks + code-owner review would forbid |
+
+So §"The gap" ¶1 and the layer table above stand **as written**: the repo is still a personal-account
+private repo with no protection available, and **layer 3 (`main-audit.js`) remains the authoritative
+enforcement**, not a redundant second net. Option B (blocker
+[#17](https://cloudbongos.com/builders#/blocker/17)) is still open and still the durable closure.
+
+Treat this as the freshness stamp: re-run the probes above before asserting the claim has changed —
+a plan upgrade or a new ruleset would flip it, and this section is what a future sweep should update.
+
 ## Notes
 
 We did **not** take immediate action against Builder 25 — Lars was overseeing the session and the change itself was a legitimate bug fix. The point of this ADR is the *mechanism*, not the person: the system must make the bypass hard and visible regardless of intent.

package/docs/adr/0090-metic-task-authoring.md

@@ -1,6 +1,6 @@
 # 0090 — Metic gains task authoring: create / promote / edit + dependency & criteria shaping
 
-- **Status:** Accepted
+- **Status:** Accepted — one line amended by [ADR 0152](<redacted>.md) (2026-07-27): `POST /tasks/:id/abandon`, listed below under "What stays Archon-only", moved to Metic+ alongside create/promote/edit, paired with an `abandoned → backlog` restore on `/promote`. The rest of this ADR stands.
 - **Date:** 2026-06-26
 - **Deciders:** Lars (Archon), Claude
 

package/docs/adr/0142-project-context-is-prose-only.md

@@ -0,0 +1,41 @@
+# 0142 — Project context is prose-only; the structured host contract is branding
+
+- **Status:** Accepted
+- **Date:** 2026-07-13
+- **Deciders:** Claude (acting builder, autonomous session under goal 1000042); owner to ratify. Presented the fork the audit named — build a structured neutral+instance+resolver for project context (mirroring branding), or keep project context prose-only — and chose prose-only.
+- **Task:** [#1002224](https://example.com/builders#/task/1002224) (BONGOS-V1, goal 1000042 — *Harden the Cloud Bongos update pipeline*). Closes hardening item **H11** / finding **F7** of [`docs/audits/update-pipeline-audit.md`](../audits/update-pipeline-audit.md).
+- **Builds on:** [ADR 0062](<redacted>.md) §7 (the core↔host split — CLAUDE.md is portable methodology; host identity lives beside it), the branding contract ([`docs/branding-contract.md`](../branding-contract.md), [`src/branding.js`](../../src/branding.js)), and the agent-doc stub (task 2121).
+
+## Context
+
+The audit's finding F7 asked a fair question: **branding** flows as a *structured* contract — `config/branding.neutral.json` (ships) ⊕ `config/branding.json` (publish-excluded) → a validated resolver ([`src/branding.js`](../../src/branding.js)) with env-override precedence and a client-safe projection — while **project context** flows only as *prose*: [`docs/project-context.template.md`](../project-context.template.md) ships (the scaffold `cloudbongos init` fills), `docs/project-context.md` (the instance's filled-in prose) is publish-excluded, plus the `CLAUDE.md`/`AGENTS.md` brand-free stub (task 2121) so a consumer's `node_modules` can't auto-load core project-memory.
+
+So the two match at the **publish-boundary** level (a neutral template ships; the instance's filled-in copy is excluded) but NOT at the **structured-resolution** level: there is no runtime resolver, no required-field validation, and no env override for project context — code never reads a merged "project-context object." F7 framed closing that gap as a decision: introduce a parallel structured resolver, or explicitly document prose-only.
+
+## Decision
+
+**Project context stays prose-only. We do NOT build a parallel structured neutral+instance+resolver for it.** The structured, code-read host contract is **branding** (and only branding). Project context is deliberately narrative — written for the *AI agents* who read it (product, vision, world, visual style), not for code to consume as fields.
+
+Concretely, the contract is:
+
+1. **Machine-readable host identity → branding.** Every instance-identity string code actually renders or injects (names, domains/origins, currency label, cookie/OAuth/dev-box hosts, theme, track set, the project name injected into LLM prompts) lives in the branding contract: `branding.neutral.json` (ships) ⊕ `branding.json` (excluded) → `resolveBranding()` with env precedence and fail-to-vanilla. If a new host string needs to be *code-read*, it goes in **branding**, not a new project-context resolver.
+2. **Prose host context → project-context, unstructured.** Vision / world / visual-style narrative for agents lives in `docs/project-context.md` (instance, excluded) scaffolded from `docs/project-context.template.md` (ships). It is read by humans and agents, never parsed by code.
+3. **The boundary is enforced at the publish layer, which already exists.** `isPublishable()` ships the neutral template and excludes the instance's filled copy ([`scripts/gds/publish-manifest.js`](../../scripts/gds/publish-manifest.js)); the `CLAUDE.md`/`AGENTS.md` stub stops a consumer auto-loading core project-memory. No runtime contract is needed because nothing at runtime consumes project context as data.
+
+## Why prose-only over a structured resolver (the trade-off)
+
+- **No consumer → YAGNI.** A structured resolver earns its keep only when *code* must read merged, validated fields with env precedence — exactly branding's job, which already exists. Nothing in the platform reads a "project-context object": it is documentation. Building a second resolver, schema, and validation layer for a thing only agents read is speculative infrastructure against the bootstrapped posture ([CLAUDE.md §4](../../CLAUDE.md)).
+- **It matches the core↔host split as already drawn** ([ADR 0062](<redacted>.md) §7): CLAUDE.md is portable methodology; the host authors identity beside it — the *strings code reads* in branding (structured), the *prose agents read* in project-context (narrative). F7 is not a gap in that split; it is the split working as designed.
+- **Redaction stays simple + correct.** Project-context prose flows through the same doc-redaction + publish-exclusion path as every other doc. A structured project-context file would add another schema the no-leak gate and the `init` flow must understand, for no functional gain.
+- **One place to add a host string.** "Where does a new instance-identity value go?" has a single answer — branding — instead of a judgment call between two parallel contracts.
+
+## When to revisit
+
+Revisit if a concrete need appears for **code to read project-context as structured data** — e.g. the product runtime (not just agents) must branch on a world/vision field, or an automated flow must validate that an instance filled in required narrative before it can ship. At that point the value under question would really be a *branding* field (add it there), or a genuinely new structured need would justify its own resolver. Until such a consumer exists, prose-only is correct.
+
+## Consequences
+
+- **No new code.** No project-context resolver, schema, or env-override layer is added; `src/branding.js` carries a short pointer comment so the next person who wonders "why isn't there a project-context resolver?" finds this ADR at the natural place they'd add one.
+- **Init unchanged.** `cloudbongos init` keeps scaffolding `docs/project-context.md` from the template as prose; there is nothing to validate at standup beyond the existing branding validation.
+- **Publish boundary unchanged.** The template ships, the filled instance prose is excluded, the agent-doc stub stands — already true, now documented as the deliberate contract rather than an accidental asymmetry.
+- **Audit H11 closed** without expanding the surface the update pipeline must keep neutral (which the sibling PROVE-NO-LEAK work — H4/H5/H6 — is separately hardening).

package/docs/adr/0143-onboarding-repo-picker-oauth-scope.md

@@ -0,0 +1,35 @@
+# 0143 — Onboarding repo picker & auto-create: broaden the OAuth scope (not a GitHub App), store a short-lived token
+
+- **Status:** Accepted — built in task 1002099.
+- **Date:** 2026-07-13
+- **Deciders:** Lars (owner/Archon) chose the credential approach; Claude designed + built.
+- **Task:** [#1002099](https://cloudbongos.com/builders#/task/1002099) · **Goal:** 35 (greenfield onboarding).
+
+## Context
+
+The onboarding wizard at `/create` ([public-landing/create.html](../../public-landing/create.html)) had the visitor **type `owner/repo` by hand** (adopt) and, for a fresh project, do a **manual** "New repository on github.com → leave it empty" step. Owner feedback: make it real — let the signed-in user **pick from their own repos** (adopt) and **auto-create the empty repo** (fresh).
+
+Blocker: the wizard's GitHub sign-in requests only `read:user` ([auth.js `SCOPE`](../../src/bongos/auth.js)), which cannot list or create repos, and `completeWebFlow` discarded the OAuth token after reading the username. Two ways forward were weighed:
+
+- **(A) Broaden the OAuth scope** and act as the user via their own token.
+- **(B) A central "Cloud Bongos" GitHub App** the user installs (fine-grained `Administration:write` to create, `Metadata:read` to list).
+
+The existing per-instance GitHub **App-manifest** flow ([ADR 0133](<redacted>.md)) is *not* reusable here — it builds a sign-in-only App with `default_permissions:{}`, one per provisioned instance, not a central repo-acting App.
+
+## Decision
+
+**Take (A) — broaden the scope — per the owner's explicit call**, accepting that it is less least-privilege than a GitHub App, in exchange for no install step and a single sign-in. Within (A):
+
+1. **Scope = `public_repo`, not `repo`.** There is no OAuth scope for "create a repo only"; `repo` grants read/write to *all* the user's code (public **and** private) — a serious liability for a token we now persist on an internet-facing tier. `public_repo` lists/creates **public** repos with a much gentler consent screen and a far smaller blast radius. Cloud Bongos instances are open-source / capture-resistant by design, so public is the norm. **Accepted limitation:** private repos can't be listed/adopted or created; revisit to `repo` only if private support is needed.
+2. **Opt-in per sign-in.** The scope is requested **only** by the wizard, via `?repos=1` on `/auth/web/start` (a `gds_oauth_repos` intent cookie carried to the callback). The builders'-hall web sign-in and the CLI Device Flow stay `read:user`. A single pure `scopeForWebFlow({repos})` is the one place the scope string is decided (unit-tested).
+3. **Lazy consent.** The step-0 gate sign-in stays identity-only; repo access is requested at **step 2**, when the user reaches the picker/creator — more private, and the "grant access" path is the well-exercised normal path.
+4. **Token persistence, contained.** The captured `public_repo` token is stored **encrypted** (secret-box, master key in server env only) in `github_oauth_tokens` (migration `core_192`), keyed to the builder, with a **short TTL (1h = one wizard sitting)** and a lazy expiry sweep on read. This lives in **core auth**, not the provisioning module: it is the auth system's *own* handshake token, not a feature's third-party API key (contrast the art module's Gemini key, [ADR 0102](<redacted>.md)), and the provisioning module's charter forbids holding tokens / calling cloud APIs ([ADR 0111](<redacted>.md) §2 / [ADR 0016](<redacted>.md)). Endpoints `GET/POST /github/repos` ([src/bongos/routes/github.js](../../src/bongos/routes/github.js)) read it back, `requireBuilder` + router-wide rate-limited.
+5. **v1 = the user's own personal repos** (`affiliation=owner`), so `full_name` is unambiguously `login/repo` and org OAuth-policy complexity (an org can restrict/approve OAuth apps; repos silently omitted) is out of scope. Org/collaborator repos are a later enhancement.
+6. **Progressive enhancement / graceful degrade.** If secret-box is **unconfigured** (`BUILDER_SECRET_KEY` unset), no token is ever stored: `GET /github/repos` returns `503 github_repos_unavailable` and the wizard **keeps the manual owner/repo inputs + the manual create-repo done-step** as the fallback. Onboarding never regresses.
+
+## Consequences
+
+- **New surface:** `scopeForWebFlow` + `captureRepoToken` in auth.js; `?repos=1` handling in the web routes; `github_oauth_tokens` (core_192) + `upsert/get/deleteGithubToken` in db.js; `src/bongos/github-repos.js` (raw-fetch `listUserRepos`/`createUserRepo`); `src/bongos/routes/github.js`; the wizard's picker/auto-create UI.
+- **Security posture:** a stored `public_repo` token is a smaller honeypot than `repo`, and it is encrypted at rest, short-lived, and swept — but it *is* new liability the web tier didn't carry before. The 503-fallback means an instance that doesn't configure secret-box simply doesn't get the feature (no plaintext token is ever written).
+- **Consent friction:** a returning user who signed in months ago has only `read:user`; the picker's `repo_scope_required` (403) prompts a one-click reconnect. The sessionStorage draft round-trips through the OAuth hop (same-tab), so no wizard state is lost.
+- **Reversal path:** switching to `repo` (private support) is a one-line scope change; switching to a GitHub App later would supersede this ADR (append a new one, don't edit).

package/docs/adr/0144-devbox-rehome-onto-cloudbongos-plane.md

@@ -0,0 +1,41 @@
+# 0144 — Re-home the dev-box fleet onto the cloudbongos.com plane (native runners, local DB, isolated fleet tag)
+
+- **Status:** Accepted — Phases 1–3 built in task 1002239. **Phase 4 part (a) (stop legacy `cohost-box-*` runners) done in task 1002248** (2026-07-15); part (b) (disable dev-box on example.com) flagged to owner — not reachable from the cloudbongos control plane.
+- **Date:** 2026-07-15
+- **Deciders:** Lars (owner/Archon) chose "re-home properly, not a legacy band-aid" + pre-approved box spend; Claude designed + executed autonomously.
+- **Task:** [#1002239](https://cloudbongos.com/builders#/task/1002239) · supersedes stale incident [#1002031](https://cloudbongos.com/builders#/task/1002031) · **Goal:** 1000025 (builder experience — hall, dev box, skills).
+
+## Context
+
+"Get the dev box up and running again for cloud bongos" surfaced a split that was invisible from the platform:
+
+- **The dev-box feature was disabled on cloudbongos.com** — `config/modules.json` listed only `provisioning` + `platform-identity`, so `/api/gds/box/*` 404'd. The instance note said dev-box stays off "until box infra is confirmed present."
+- **The live dev-box data plane was the *legacy* `example` Postgres** (on the co-hosting box), drained by the cloudbongos control plane's `cohost-box-*` systemd runners over an SSH DB tunnel ([ADR 0132](<redacted>.md)). Builder identities even diverged: `example-owner` is builder **1** in the example DB, **3** on cloudbongos.com.
+- **The fleet was dormant** — all 9 boxes `destroyed`, control-plane timers green but idle (`ran=0`). So nothing was *broken*; the box capability simply lived on the old plane and was never brought onto the platform after the [ADR 0139] work-history migration.
+
+The owner chose to **re-home the box feature onto the cloudbongos.com plane** (its own DB, its own domains) rather than revive a box on the legacy `example` infra. Feasibility was high: the box tables already exist in the cloudbongos DB, `cloudbongos.com` is a live Cloudflare zone on the same account the control plane already uses, the DO/CF tokens are already on the control plane, and box domains are branding-driven (`domains.devBoxBase`/`sshBoxBase`) — not hardcoded.
+
+## Decision
+
+Stand up a **cloudbongos-native box plane** alongside (not replacing) the legacy one, in four moves:
+
+1. **Enable the feature (persisted).** `config/modules.json` → `dev-box: true`; `config/branding.json` → `domains.devBoxBase=cloudbongos.com`, `sshBoxBase=dev.cloudbongos.com`. **Persistence is by pushing to the instance `origin/main`, not a local commit** — `deploy.sh` (the ~3-min pull-deploy, ADR 0129) does `git reset --hard origin/main`, which silently reverts any local-only change. (Learned the hard way: a local commit was reset away within one deploy cycle.)
+
+2. **Native lifecycle runners against the LOCAL DB.** Four systemd service+timer pairs (`cloudbongos-box-{intent-runner,idle-suspend,drift-reconcile,dormant-reclaim}`) modeled on the `cohost-box-*` units but pointed at the **local `cloudbongos` Postgres** (peer auth, `PGDATABASE=cloudbongos`, **no tunnel, no `DATABASE_URL`**). Box domain/zone come from env, not branding, for the CLI: `CLOUDFLARE_ZONE`, `BOX_TERMINAL_ZONE`, `BOX_DNS_ZONE`, `GDS_PUBLIC_ORIGIN` (all cloudbongos.com). Overrides live in `/etc/cloudbongos/cloudbongos-box.env`, layered over `/etc/cloudbongos/box.env` (which holds the tokens).
+
+3. **Fleet isolation by a DISTINCT tag — the load-bearing safety decision.** Both planes share one DigitalOcean + one Cloudflare account. `boxes.js planDropletDrift` treats any fleet-tagged droplet **not in its own DB as a "zombie" and force-deletes it** (30-min grace). With a shared `otb-builder-box` tag, the legacy plane's hourly drift-reconcile would reap a cloudbongos box within ~30–90 min. So the native plane uses **`BOX_TAG=cloudbongos-builder-box`**. This is watertight because `cmdReconcileDrift` lists droplets `{tag: CONFIG.tag}`, and the sweeps act only on their own DB's rows — so each plane manages exactly its own fleet.
+
+4. **Legacy plane untouched.** The `example` (cohost) plane keeps running, fully isolated by tag/DB. Retiring it (disable dev-box on example.com, stop the cohost tunnel/runners) is **Phase 4** — deferred to an explicit owner go-ahead because it is the one hard-to-reverse step and is unnecessary for the cloudbongos plane to work.
+
+## Consequences
+
+- cloudbongos.com now serves `/box/*` and provisions boxes on its own plane, at `term-<login>.cloudbongos.com` / `sandbox-<login>.cloudbongos.com`, tracked in the cloudbongos DB, isolated from the legacy fleet.
+- **Verified end-to-end (2026-07-15):** web `POST /box/ensure` → intent in the cloudbongos DB → native `cloudbongos-box-intent-runner` drained it (`ran=1 ok=1`) → droplet `584756519 @ REDACTED_IP`, tunnel + DNS on cloudbongos.com, box `active`. Drift-reconcile confirmed `fleet tag=cloudbongos-builder-box: 0 droplets` before provisioning — proving isolation.
+- Two planes now exist until Phase 4. That is intentional and safe (tag + DB isolation), but means dev-box is "on" in two places.
+
+## Follow-ups (open)
+
+1. **Box first-boot convergence — ROOT-CAUSED + fixed (workaround live; proper fix open, task 1002243).** Symptom: provisioned boxes reached `active` but `cloudflared`/terminal never came up (`term-…` = CF 530) and SSH keys weren't applied. Root cause: **`box.js` provisioned droplets with EMPTY user-data** (`/var/lib/cloud/instance/user-data.txt` = 0 bytes; cloud-init logged "No user-data found"). `box.js` renders the box cloud-init from `<REPO_ROOT>/infra/` (the 26 KB `builder-box-cloud-init.yaml` + ~12 gz+b64-inlined scripts), and `fileGzB64` **silently returns `''` on a missing file**, so a missing `infra/` yields empty user-data with no error. The R89 split moved `scripts/gds/` into the `@bongos/core` package but **kept `infra/` in the instance repo** — yet `box.js` still resolves `infra/` relative to *its own* location (the vendored core), where `infra/` **isn't shipped at all** (0 files). So every box on any vendored/installed instance booted with only DigitalOcean's default user-data. **Workaround applied (temporary):** populated the vendored core's `infra/` from the instance's `infra/` (`/home/lars/cloudbongos/node_modules/@bongos/core/infra/`); re-provision then rendered a 62 KB user-data and the box converged — `cloudflared` active, `term-example-owner.cloudbongos.com` → 200 (authed), builder SSH key baked + working. **Proper fix (task 1002243):** ship `infra/` in the core publish-manifest, OR make `box.js` resolve `infra/` from the instance root (like `core-node.sh`'s candidate-base search), AND make `fileGzB64`/the template render **fail loudly** instead of emitting empty user-data. The workaround is under `node_modules` and will be lost on the next `npm ci`/core reinstall until the proper fix lands.
+2. **Cloudflare token scope.** Provision warned the ADR 0053 cookie-strip Transform Rule was **not** applied — `CLOUDFLARE_API_TOKEN` lacks "Transform Rules" edit scope on the cloudbongos.com zone. Add the scope (or apply the rule once in the dashboard) **before** other builders get boxes on `*.cloudbongos.com`, so platform cookies (`cookieDomain=<redacted> aren't sent to box subdomains.
+3. **Cosmetic `otb-` prefix.** Tunnel names (`otb-term-<login>`) and the droplet name (`otb-box-<login>`) are still hardcoded in `box-onboard.js`/`box.js`. Harmless (fleet separation is by tag, and DNS is per-zone), but a branding leak worth parameterizing.
+4. **Phase 4 — retire the legacy example plane** (owner decision) — **part (a) DONE in task 1002248 (2026-07-15).** Pre-checked read-only that the legacy fleet was empty (0 `otb-builder-box` droplets on DigitalOcean; cohost intent queue `ran=0`), then `systemctl disable --now` on the four `cohost-box-*` timers (intent-runner / idle-suspend / drift-reconcile / dormant-reclaim) on the control-plane host — now `disabled`/`inactive`; the native `cloudbongos-box-*` timers were left `enabled`/`active`. **Part (b) — disabling the dev-box module on example.com itself — NOT reachable from the control plane, flagged to owner:** example's web app + instance checkout are not co-located on the cloudbongos droplet (no local checkout, no ssh alias) and the local example GDS token is expired, so a durable module-disable needs owner access to example's own config/host. Harmless meanwhile: with the runners stopped there is no cost/security impact — worst case is a box request on the legacy instance that now hangs unfulfilled.

package/docs/adr/0144-federated-single-logout-backchannel.md

@@ -0,0 +1,42 @@
+# 0144 — Federated single-logout: hub-initiated back-channel session revocation
+
+- **Status:** Accepted — built in task 1002238.
+- **Date:** 2026-07-15
+- **Deciders:** Lars (owner/Archon) chose the back-channel approach; Claude designed + built.
+- **Task:** [#1002238](https://cloudbongos.com/builders#/task/1002238) · **Goal:** 41 (cross-site identity). Follow-up to [ADR 0141](<redacted>.md).
+
+## Context
+
+Cross-site identity ([ADR 0141](<redacted>.md)) gave single sign-**on**: one hub login (cloudbongos.com) reaches every federated project's hall with no second GitHub sign-in. But sign-**off** stayed local. When a federated instance completes the SSO handshake it mints its **own** local session (`completeIdpFlow` → `createSession`) with its own cookie on its own domain. `POST /auth/logout` revokes only *that* instance's session + clears *that* apex cookie — so signing out of the hub left every federated project (e.g. demo) still signed in. Owner request (2026-07-14): make sign-out universal.
+
+Three approaches were weighed (the task's options):
+
+- **(a) Back-channel SLO** — on hub logout the hub server calls each entered instance's revoke endpoint (server-to-server).
+- **(b) Front-channel SLO** — the browser is bounced through each instance's logout URL (classic OIDC front-channel).
+- **(c) Soft sessions** — federated instances stop holding durable sessions and re-check the hub continuously.
+
+## Decision
+
+**Take (a) — back-channel single-logout — per the owner's explicit call.** It is the robust, browser-independent choice for a session-lifecycle security feature, and it reuses the federation machinery ADR 0141 already built.
+
+1. **A hub-signed, purpose-tagged EdDSA logout token.** The hub mints (`platform-identity/hub-keys.js` `mintHubLogoutToken`) a compact Ed25519 JWT — the **same envelope + asymmetric key + ~120s TTL + audience-binding** as the login assertion (`mintHubAssertion`), so a token minted for instance A can't be replayed against instance B, and a compromised instance (holding only the public key) can't forge one. The payload carries **only** `{ iss, aud:<client_id>, sub:<github_id>, purpose:"backchannel-logout", iat, exp, jti }` — never identity, a rank, or a session token. The **`purpose` marker is load-bearing**: a login assertion has no `purpose` (rejected by the logout verifier) and a logout token has no `github_login` (rejected by the login verifier `verifyHubAssertion`), so the two token types are **mutually non-interchangeable** — a captured login assertion can't trigger a logout, and a logout token can't mint a session. The instance verifier (`auth.js verifyHubLogoutToken`) is the boundary-mirrored sibling of `verifyHubAssertion` (ADR 0091 §2), alg **hardcoded to Ed25519** (no algorithm-confusion), signature verified **before** any claim is trusted.
+
+2. **Kernel-mediated seam event, so core stays module-agnostic.** `POST /auth/logout` (core) revokes the local session as before, then **emits** a `builder.logout` seam event (fire-and-forget). On a non-hub instance nothing listens → no-op. On the hub, the `platform-identity` module (enabled only there) reacts. Core never references the module (ADR 0083 one-way rule); the switchboard (`src/module-seams.js`) is the seam.
+
+3. **The hub fans out; the instance revokes.** The module's listener looks up the builder's entered projects and POSTs a per-project logout token to each `{origin}/api/gds/auth/backchannel-logout`. That endpoint (core `auth.js`/`routes/auth.js`, **dormant unless the instance federates** — `idpConfigured()`, else a plain 404) verifies the token against the hub public key it already trusts (`/sso/pubkey`), resolves the builder by `github_id`, and calls `revokeAllSessionsForBuilder` — killing **all** of that builder's local sessions (web + CLI).
+
+4. **Entered-instance list = memberships (ADR 0141 §3).** The hub uses `listMembershipsForAccount(github_id)` — the projects the builder is known to build on — as the fan-out target list, per the task's sanctioned V1 signal. **Over-notifying is safe:** an instance with no live session for that builder just revokes nothing (revoke is idempotent). A precise per-SSO-session entry ledger (notify *only* instances with a live federated session) is a deliberate follow-up, not V1.
+
+5. **Best-effort, bounded, isolated fan-out.** The user's hub session is revoked **synchronously** (the part they experience); the cross-instance sweep runs server-side off the fire-and-forget event, each POST bounded by a 4s timeout, all under `Promise.allSettled` — a slow or down project can never wedge the sweep or the logout, and the fan-out never throws. **Accepted limitation:** if an instance is unreachable at logout time, its local session survives until its own TTL; a retry/queue is out of scope for V1 (logged, not retried).
+
+6. **Anti-replay on the instance side.** A logout token's `jti` is honored **once** (`logoutTokenJtiSeenAndRecord`, symmetric with the CLI-assertion path): the first use revokes, a replay within the ~120s TTL is an idempotent no-op. Without this, a captured token would stay a repeatable "log this builder out" primitive for its whole life — it could keep killing sessions the builder legitimately creates *after* the token was minted (revoking already-dead sessions is otherwise harmless).
+
+## Consequences
+
+- **Trust boundary preserved (ADR 0016 / 0141).** The logout token, like every other hub→instance message, carries **identity only** (a subject to sign out) — never authority. The instance decides locally what "sign this github_id out" means (revoke its own sessions). Authority stays local.
+- **Deploys to both sides.** The instance half (`/auth/backchannel-logout`, `verifyHubLogoutToken`, the `builder.logout` emit) ships in **core** (dormant on non-federated instances); the hub fan-out ships in the **platform-identity** module. So this go-live re-vendors **both** the hub (cloudbongos.com) and every federated instance (demo). Core `1.18.5 → 1.18.7` (the `1.18.6` cut on `main` is the unrelated task 1002241 `?return=` fix, carried along).
+- **No new schema.** Reuses the existing `<redacted>` + `sso_clients` (origin) rows and the existing Ed25519 hub keypair. No migration.
+- **Not front-channel (b):** modern third-party-cookie / iframe restrictions (Safari ITP, Chrome's trajectory) make browser-driven cross-site logout unreliable, and it doesn't complete if the tab closes mid-chain. Rejected for a security guarantee.
+- **Not soft sessions (c):** re-checking the hub per-request adds latency to every request and makes a federated instance's sign-in fail whenever the hub is down (a hard runtime dependency) — too heavy for a bootstrapped setup.
+- **V1 scope:** hub-initiated logout only. A federated instance's own logout does **not** yet propagate back to the hub + siblings (it has no client registry); that's a follow-up if wanted.
+- **Known limitation — a membership-spoof presence oracle (security review, medium).** The fan-out targets a builder's `<redacted>`, and `POST /sso/membership/check-in` (ADR 0141 §3) trusts a caller-named `github_id` under any active `client_secret`. So a client-secret holder can assert a membership for an arbitrary `github_id` and thereafter receive a hub-signed logout callback naming that builder on each of their hub logouts — a cross-account presence/existence oracle. It is **contained** (the token is `aud`-bound to the attacker's own `client_id`, so it can't be replayed against the victim's real instances — no session compromise) and **gated** (an `sso_client` is registered only by the operator-run `provision.js`, never a public route, so today every secret-holder is an operator-provisioned, trusted instance — the only client is `demo`). The root cause predates this ADR; this feature newly turns it into an active signed callback. **The proper fix — bind the fan-out to evidence of a real federated session for that `github_id` (a per-SSO-session ledger), or prove user consent at check-in — is the deferred follow-up (task [#1002244](https://cloudbongos.com/builders#/task/1002244)); it must land before federation opens to untrusted third-party clients.**

package/docs/adr/0145-devbox-app-branding-driven-module.md

@@ -0,0 +1,44 @@
+# 0145 — The Dev Box app becomes a branding-driven module (one source, per-instance builds)
+
+- **Status:** Accepted — Phase 1 built in task [#1002255](https://cloudbongos.com/builders#/task/1002255). Downloads (1002257), CI + releases repo + signing (1002258), and end-to-end verify (1002256) follow.
+- **Date:** 2026-07-15
+- **Deciders:** Lars (owner) — "re-set up the dev box app so it's properly installable for cloudbongos; the design should not be linked to a specific project but to the Cloud Bongos design; it should live on cloudbongos and be maintained there as a module, and Example should borrow it."
+- **Extends:** ADR 0045 (the Dev Box desktop app), ADR 0072 (app signing posture), ADR 0083 (module system), ADR 0004/0062 (brand discipline — no hardcoded host identity), [branding contract](../branding-contract.md).
+
+## Context
+
+The Dev Box desktop app (ADR 0045 — an Electron menu-bar/tray switch that pairs sign-in, flips the box on/off, and wires the local SSH + Claude-Desktop last mile) was **built for Example and lived outside the Cloud Bongos core**:
+
+- Its source was only in the OTB monolith (`~/dev/Claude-OTB/devbox-app/`), never in the neutral core.
+- It was **hardcoded to Example/OTB**: `src/brand.js` (`CIV_NAME: 'Example'`, `PRODUCT_NAME: 'OTB Dev Box'`, `example.com` origins), `appId com.offtheboats.devbox`, artifact names `OTB-Dev-Box-*`, the renderer's parchment/ancient-Greek theme (Cinzel/EB Garamond, tan `#ece0c2`) and an archaic "thy/thee" voice ("a gift of Hermes").
+- cloudbongos already ships the *download-redirect server* (`src/devbox-downloads.js`) but with no `config/devbox-app.json` and no Cloud-Bongos app to point it at — so a cloudbongos builder had **no installable app**, only the browser terminal + manual SSH.
+
+## Decision
+
+Vendor the app into the dev-box module and make **every brand input a build-time value read from the instance branding**, so one source tree builds any instance's app.
+
+1. **House it in the module:** `modules/dev-box/app/` (40 files, ~600K; `node_modules`/`dist` excluded). The desktop app is not a formal module `contributes` type (the manifest schema has no "app" — routes/pollers/uiSections/webSurfaces only), so it lives as **source inside the module**; `module.json` is unchanged. The generic `src/devbox-downloads.js` stays in core and reads the instance's `config/devbox-app.json` (Phase 2).
+
+2. **Build-time brand generator** — `scripts/gen-brand.js` reads `config/branding.json` (→ `branding.neutral.json` fallback, the Cloud Bongos pack) and emits three generated, committed artifacts:
+   - `src/brand.generated.json` — `PRODUCT_NAME`, `APP_ID` (`com.<worldslug>.devbox`), `PRODUCT_SLUG` (artifact filenames), origins, `DESKTOP_ENV_NAME`, `COPYRIGHT`, `CONFIG_DIR`, `BG_COLOR`, `TAGLINE`. `src/brand.js` is now just `module.exports = require('./brand.generated.json')`.
+   - `renderer/theme.generated.css` — the `:root` design tokens (palette + fonts) from `theme.ui`; `styles.css` keeps only layout and consumes the vars, so the panel re-skins entirely from branding.
+   - `electron-builder.yml` — rendered from `electron-builder.tmpl.yml` (appId/productName/copyright/artifact slug substituted; electron-builder's own `${version}/${arch}` left literal).
+   It runs in `prep` (→ `prestart`/`pretest`/`predist:*`), so every build regenerates for the building instance. Same source → **"Cloud Bongos Dev Box" here, "Example Dev Box" there** — the ADR 0004 posture generalised to every instance, enforced by the `no hardcoded host identity` fitness gate (which this now passes).
+
+3. **Example borrows it as a module** — it enables `dev-box` and its build runs `gen-brand` against its own `config/branding.json`, producing the OTB-branded app from the shared source. No forked copy.
+
+4. **Functional cross-component constants stay** (not "design", so not rebranded): the ttyd terminal user `otb` and the SSH key filename `~/.ssh/otb_builder` are contracts with the box image (`box-terminal.service`, the authorized-keys fetch, `/builder-connect`); the `window.otb` renderer↔preload bridge is an internal namespace. The session file dir, however, **is** branding-driven now (`~/.config/<configDir>/gds-session.json`) so pairing the app still signs in the instance's own `/builder-*` CLI.
+
+## Consequences
+
+- The neutral core now carries a **Cloud-Bongos-branded** Dev Box app by default (warm palette, Baloo 2/Quicksand, plain modern voice, `com.cloudbongos.devbox`). Committed generated defaults come from `branding.neutral.json` (Cloud Bongos brand pack; `localhost` origins are the neutral dev default — a real instance build bakes its own origins + the runtime session/API base overrides them anyway).
+- Verified Phase 1: `gen-brand` renders cleanly; the app's 56 unit tests pass (the one OTB-hardcoded assertion is now brand-agnostic); `node --check` clean; the client-vendor path fixed for the two-levels-deeper location; **all architecture fitness checks pass** (module→doorway-only, no hardcoded host identity, repo-map fresh).
+- The **API/builders origins the distributed app pairs against must be baked from the instance branding at build time** — so the real cloudbongos installer must be built with the cloudbongos instance `config/branding.json` (`cloudbongos.com`), not the neutral core's `localhost`. This shapes Phase 3 (where the branded build runs).
+
+## Follow-ups (open)
+
+1. **Downloads (task 1002257) — DONE 2026-07-17.** `config/devbox-app.json` pushed to the instance repo → `cloudbongos.com/downloads/devbox/*` 302 to the v1.0.10 release assets (all targets verified through Caddy). ⚠ **Vendored-config quirk:** `serve-internal.js` reads the config via a naive `require('../../config/devbox-app.json')` that in a *vendored* instance resolves to `node_modules/@bongos/core/config/`, **not** the instance root where the file lives (unlike branding/modules). Workaround: copied the config there on the host + restarted `cloudbongos.service` — **lost on next core upgrade / `npm ci`**. Proper instance-root-resolve fix = **task 1002371** (same class as ADR 0144's `infra/`).
+2. **Distribution (task 1002258) — DONE 2026-07-17.** CI `.github/workflows/build-devbox-app.yml` builds **signed + notarized** mac (arm64+x64) + win (x64+arm64); public releases repo `example-owner/cloudbongos-devbox-releases` hosts them; **v1.0.10 published**. Release origins baked via CI repo variables `DEVBOX_PUBLIC_ORIGIN`/`_BUILDERS_ORIGIN` (= cloudbongos.com). Gotcha found live: notarization 403'd until the owner accepted a lapsed **Apple Developer Program License Agreement** — then the signed+notarized build went green. Publishing = download CI artifacts → `gh release create/upload` (manual, no cross-repo CI token; ADR 0045).
+3. **App icon still OTB art.** `scripts/gen-icons.js` draws the app/tray/DMG icons from **pixel grids in the script** (currently the OTB design); the committed PNGs are OTB. Regenerating them from the Cloud Bongos bongo motif (edit the grids + re-run `npm run icons`) is a distinct art follow-up — the app's *name/colors/voice* are Cloud Bongos, but the *icon* is not yet.
+4. **Dev/CI env-var names** (`OTB_DEVBOX_API_BASE`/`_SCREENSHOT_DIR`/`_AUTOFLOW`) keep the `OTB_` prefix — harmless dev hooks, not user-visible; prefix-neutralising them is optional polish.
+5. **ADR number collision:** `0144` is used twice on this branch (`devbox-rehome` + `federated-single-logout`, from a parallel merge). Cosmetic; a renumber is worth a follow-up.