@bongos/core 1.17.2 → 1.18.0

package/GOVERNANCE.md

@@ -8,7 +8,7 @@ Cloud Bongos is an **AI-first build platform**: a human owner sets scope and the
 
 1. **Open, free, and protected from capture.** Cloud Bongos is released as open source under the **GNU AGPL-3.0** ([`LICENSE`](LICENSE)). The AGPL's §13 (Remote Network Interaction) closes the hosted-closed-fork loophole: anyone who runs a modified Cloud Bongos as a network service must offer that service's complete source to its users. This is the anti-monopoly guarantee — the platform stays a commons even when it is *operated*, not just when it is shipped.
 
-2. **Non-profit.** The project is **not monetized from its contributors**. No one pays to contribute, and no contribution is resold by the project as a proprietary add-on. The in-platform credit/example economy is an **instance-internal** mechanism (an instance rewards its own builders from its own budget) — it is not the project monetizing the commons.
+2. **Non-profit.** The project is **not monetized from its contributors**. No one pays to contribute, and no contribution is resold by the project as a proprietary add-on. The in-platform credit economy is an **instance-internal** mechanism (an instance rewards its own builders from its own budget) — it is not the project monetizing the commons.
 
 3. **AI-first.** The expectation is that **AI agents write the code**. This is a documented norm, not a technical gate (see [CONTRIBUTING.md](CONTRIBUTING.md)). The whole methodology — the task lifecycle, the quality grader, the session economy — is designed around agents as the primary authors.
 

package/README.md

@@ -1,10 +1,21 @@
-# Example
+# Cloud Bongos
 
-A persistent, shared 16-bit pixel-art world — the e-commerce experience for [Example](https://example.com), powered by [Example](https://example.com).
+**Cloud Bongos is an AI-first software build platform.** A human owner sets scope, direction, and the hard gates (rank, approval, deploy); AI agents claim tasks and do the day-to-day building — code, docs, migrations, reviews. This repository is the **portable core**: the methodology, the Game Development System (GDS) that tracks all work, the platform engine, and a neutral branding template each instance fills in.
 
-Project memory — architecture, scope, V1 limitations, future ideas, session log — lives in [`CLAUDE.md`](./CLAUDE.md). Read it before editing code.
+Cloud Bongos is free software under the **GNU AGPL-3.0** (see [`LICENSE`](./LICENSE)), with non-profit, AI-first governance ([`GOVERNANCE.md`](./GOVERNANCE.md)).
 
-> **Reading this on GitHub?** [`builders.example.com`](https://builders.example.com) is the canonical place to read project docs — task refs (`#NNN`) render as working links there. GitHub is the code host: great for diffs and PRs, but a bare `#NNN` here links to a GitHub issue and 404s.
+> **Provenance.** This core was extracted with fresh history from **Amazonprimea** — the reference instance, built by Hermeslines, and the first project to run on Cloud Bongos. Amazonprimea now consumes this core as a pinned dependency, the same shape as any other instance. The extraction is a redacted subtree (no instance secrets, IPs, or private identity); the exact pin — `core_version`, `source_commit`, `tree_sha256` — is recorded in [`.cloudbongos-core.json`](./.cloudbongos-core.json).
+
+The durable framing for AI agents — methodology, working rules, session protocol, architecture — lives in [`CLAUDE.md`](./CLAUDE.md). Read it before editing code.
+
+## What's in here
+
+- **The GDS** (`src/`, `modules/`, `scripts/gds/`) — the build state machine: tasks, claims, versions, goals, dependencies, the claim→ship→grade→credit lifecycle, and the `/builder-*` CLI.
+- **Platform modules** (`modules/`) — lifecycle, grading, economy, memory, onboarding, ideas, sessions, autonomy, security, the builders' hall + status dashboard, dev-box, and Discord integration. Each is configurable (and most are toggleable) per instance.
+- **Neutral branding template** (`config/*.neutral.json`, `docs/project-context.template.md`) — the identity scaffold a new instance fills in ([`docs/branding-contract.md`](./docs/branding-contract.md)). The vanilla pack in `config/branding.neutral.json` is the identity Cloud Bongos itself runs on.
+- **Methodology + decisions** (`CLAUDE.md`, `docs/adr/`, `docs/recipes/`, `.claude/skills/`).
+
+> **This is the core, not a ready-to-run instance.** An instance layers its own content, branding, and product modules on top of a pinned core (that is the whole point of the two-repo model). `server.js` and some entrypoints still reference the reference instance's product layer; standing the core up standalone — a clean vanilla boot — is deliberately the job of the consumer path, proven first by the next instance to install it.
 
 ## New builder? Start here
 
@@ -14,16 +25,11 @@ You'll need three things on your machine first:
 
 - **Git** — the tool that copies the code down. Check with `git --version`; install from [git-scm.com](https://git-scm.com/downloads) if it's missing.
 - **Claude Code** — your pair-programmer for every session. Download the desktop app at [claude.com/download](https://claude.com/download) (Mac and Windows).
-- **A GitHub account with access to this repo** — the project is private, so an Archon must invite you first. Accept the emailed invitation before cloning. (The bootstrap script below also checks for Node ≥ 22 and Python ≥ 3.10, and prints the install command if either is missing — you don't need them installed *before* cloning.)
+- **A GitHub account with access to this repo.** While the repo is private, the owner must invite you first; accept the invitation before cloning. (The bootstrap below also checks for Node ≥ 22 and Python ≥ 3.10, and prints the install command if either is missing.)
 
 ### Step 0 — get the project onto your machine
 
-Clone the repo, then `cd` into it. Everything below runs from inside that folder:
-
-```sh
-git clone https://github.com/example-owner/example.git
-cd example
-```
+Clone the repo, then `cd` into it. Everything below runs from inside that folder.
 
 ### Step 1 — bootstrap
 
@@ -36,15 +42,15 @@ One command bootstraps a fresh clone end-to-end — toolchain checks, JS deps, l
 node scripts/setup-builder.js
 ```
 
-It checks Node ≥ 22 and Python ≥ 3.10 (prints the install command if either is missing), runs `npm ci`, copies `.env.local.example` to `.env.local` (optionally prompting for your Google AI Studio key — pass `--skip-keys` to leave it blank), and hands off to `node scripts/gds/setup.js` to authenticate against the GDS via the GitHub Device Flow. The script is idempotent: re-running on an already-set-up checkout reports "already done" rather than clobbering.
+It checks Node ≥ 22 and Python ≥ 3.10 (prints the install command if either is missing), runs `npm ci`, copies `.env.local.example` to `.env.local`, and hands off to `node scripts/gds/setup.js` to authenticate against the GDS via the GitHub Device Flow. The script is idempotent: re-running on an already-set-up checkout reports "already done" rather than clobbering.
 
 When it finishes, open Claude Code and run `/builder-start` to see what tasks are claimable.
 
 ## Secrets scanning
 
-We keep secrets (`.env` files, API keys, private keys) out of the repo with two layers:
+We keep secrets (`.env` files, API keys, private keys) out of the repo with two layers. Both are **instance topology** — the git hook (`.husky/`) and CI (`.github/`) are provided when you stand up an instance and are not shipped in the portable core; the pattern below is the recommended posture:
 
-- **Pre-commit hook** ([`.husky/pre-commit`](./.husky/pre-commit)) — scans your *staged* changes before each commit and aborts if it finds a secret. Activate it **once per clone**:
+- **Pre-commit hook** (`.husky/pre-commit`) — scans your *staged* changes before each commit and aborts if it finds a secret. Activate it **once per clone**:
 
   ```sh
   git config core.hooksPath .husky
@@ -54,20 +60,20 @@ We keep secrets (`.env` files, API keys, private keys) out of the repo with two
 
   > **Windows:** git runs the `.husky/pre-commit` hook through the Git-Bash `sh` bundled with Git for Windows, so the hook works if you installed Git for Windows (the usual case). If you don't have a `sh` available, the local hook silently no-ops — CI's full-history TruffleHog scan is then your only gate (and it always runs regardless of platform).
 
-- **CI scan** ([`.github/workflows/secrets-scan.yml`](./.github/workflows/secrets-scan.yml)) — every PR to `main` runs TruffleHog over the **full git history**. This must pass before merge.
+- **CI scan** (`.github/workflows/secrets-scan.yml`) — every PR to `main` runs TruffleHog over the **full git history**. This must pass before merge.
 
 ### If a commit is blocked, here's how to investigate
 
 1. **Read the output.** The hook prints the offending file(s) and why.
-2. **Is it a real secret?** Then it must never be committed. Remove it from the commit (`git restore --staged <file>`), move the value out of the repo — local secrets go in `.env.local` (gitignored; run `/builder-setup`), production secrets live on the droplet at `/etc/example/`. If it was *already committed in an earlier commit*, the history scan will keep failing until the history is scrubbed — flag this to Lars, since rewriting shared history needs care.
+2. **Is it a real secret?** Then it must never be committed. Remove it from the commit (`git restore --staged <file>`), and move the value out of the repo — local secrets go in `.env.local` (gitignored; run `/builder-setup`); production secrets live in your instance's secret store, never in the tree. If it was *already committed in an earlier commit*, the history scan will keep failing until the history is scrubbed — flag this to the owner, since rewriting shared history needs care.
 3. **Is it a false positive?** (e.g. an example key in docs, a test fixture, a Stripe `pk_test_` publishable key.) Add a path regex — one per line — to [`.husky/secrets-allowlist.txt`](./.husky/secrets-allowlist.txt). Both the hook and CI read that allowlist. Keep entries narrow and only add them after confirming the match is genuinely not a secret.
 4. **Genuine emergency commit** (you're sure it's clean and need to move now): `git commit --no-verify` skips the local hook — but CI will still scan the PR, so this only defers the check, it doesn't bypass it.
 
 ## If your CLI starts 401'ing
 
-GDS CLI calls (`node scripts/gds/start.js`, `claim.js`, `ship.js`, etc.) authenticate against `example.com` using a session token at `~/.config/otb/gds-session.json`. Migration 035 (V3.R38 / [#259](https://example.com/builders#/task/259)) put a 1-hour rolling TTL on every session — every authenticated request resets it, so an active session never silently expires. But after a long idle, a token revocation, or an auth-changing deploy (e.g. mig 035 itself when it landed), the local token can stop working.
+GDS CLI calls (`node scripts/gds/start.js`, `claim.js`, `ship.js`, etc.) authenticate against your instance's GDS host using a session token stored under `~/.config/<configDir>/gds-session.json` (the neutral core uses `cloudbongos`; an instance may pin its own). Sessions carry a rolling TTL — every authenticated request resets it, so an active session never silently expires — but after a long idle, a token revocation, or an auth-changing deploy, the local token can stop working.
 
-`apiCall` in `scripts/gds/cli-lib.js` detects HTTP 401 and exits with a clear recovery message rather than letting the failure cascade through downstream calls. When you see that message:
+`apiCall` in `scripts/gds/cli-lib.js` detects HTTP 401 and exits with a clear recovery message rather than letting the failure cascade. When you see it:
 
 1. **Re-auth via Device Flow:**
 
@@ -75,7 +81,7 @@ GDS CLI calls (`node scripts/gds/start.js`, `claim.js`, `ship.js`, etc.) authent
    node scripts/gds/setup.js --force
    ```
 
-   This pre-flights `GET /api/gds/me` against your existing session before doing anything. If the token is valid, it tells you who you're authenticated as and exits. If the token is dead (401), it falls through to the Device Flow *automatically* — no second `--force` needed. Browser opens to `github.com/login/device`; paste the printed code, authorize as the right GitHub account, you're back.
+   It pre-flights `GET /api/gds/me` against your existing session first. If the token is valid, it tells you who you're authenticated as and exits. If the token is dead (401), it falls through to the Device Flow automatically — browser opens to `github.com/login/device`; paste the printed code, authorize as the right GitHub account, you're back.
 
 2. **If something feels off and you're not sure what,** run the doctor:
 
@@ -83,6 +89,4 @@ GDS CLI calls (`node scripts/gds/start.js`, `claim.js`, `ship.js`, etc.) authent
    node scripts/gds/doctor.js
    ```
 
-   It checks session validity (`/me` returns 200, identity + rank), git plumbing (`core.hooksPath` resolves), repo state (on a branch, working-tree status), and environment files (`.env.local`, `~/.config/otb/env`). Green/red checklist, no arguments. Exits 0 if every check passes, 1 if any red.
-
-Mirrors the "if a commit is blocked" pattern above: actionable, single command, no guessing.
+   It checks session validity (`/me` returns 200, identity + rank), git plumbing (`core.hooksPath` resolves), repo state (on a branch, working-tree status), and environment files. Green/red checklist, no arguments. Exits 0 if every check passes, 1 if any red.

package/clients/bongos-client/README.md

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

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

@@ -317,6 +317,8 @@ function createClient(opts = {}) {
       postGoalsIdRequestsReqIdWithdraw: (args) => request("POST", "/goals/{id}/requests/{reqId}/withdraw", { hasBody: true }, args),
       // POST /goals/{id}/scope — rank: metic+archon — POST /goals/:id/scope
       postGoalsIdScope: (args) => request("POST", "/goals/{id}/scope", { hasBody: true }, args),
+      // GET /goals/{id}/suggest-criteria — rank: any-builder — GET /goals/:id/suggest-criteria
+      getGoalsIdSuggestCriteria: (args) => request("GET", "/goals/{id}/suggest-criteria", { hasBody: false }, args),
       // POST /goals/{id}/tasks — rank: any-builder — POST /goals/:id/tasks
       postGoalsIdTasks: (args) => request("POST", "/goals/{id}/tasks", { hasBody: true }, args),
       // POST /goals/{id}/transfer — rank: any-builder — POST /goals/:id/transfer

package/clients/bongos-client/index.cjs

@@ -316,6 +316,8 @@ function createClient(opts = {}) {
       postGoalsIdRequestsReqIdWithdraw: (args) => request("POST", "/goals/{id}/requests/{reqId}/withdraw", { hasBody: true }, args),
       // POST /goals/{id}/scope — rank: metic+archon — POST /goals/:id/scope
       postGoalsIdScope: (args) => request("POST", "/goals/{id}/scope", { hasBody: true }, args),
+      // GET /goals/{id}/suggest-criteria — rank: any-builder — GET /goals/:id/suggest-criteria
+      getGoalsIdSuggestCriteria: (args) => request("GET", "/goals/{id}/suggest-criteria", { hasBody: false }, args),
       // POST /goals/{id}/tasks — rank: any-builder — POST /goals/:id/tasks
       postGoalsIdTasks: (args) => request("POST", "/goals/{id}/tasks", { hasBody: true }, args),
       // POST /goals/{id}/transfer — rank: any-builder — POST /goals/:id/transfer

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

@@ -36,6 +36,7 @@ export interface GetDoneWhenPendingReviewResponse { criteria: unknown; count: un
 export interface GetGoalsIdConflictsResponse { ok: boolean; goal_id: unknown; conflicts: unknown; cross_goals_considered: unknown }
 export interface GetGoalsIdRequestsResponse { requests: unknown }
 export interface GetGoalsIdResponse { goal: unknown; members: unknown; criteria: unknown; dependencies: unknown }
+export interface GetGoalsIdSuggestCriteriaResponse { goal_id: unknown; suggestions: unknown }
 export interface GetGoalsResponse { goals: unknown }
 export interface GetGradesByBuilderResponse { window_days: unknown; builders: unknown }
 export interface GetHealthzResponse { ok: boolean; auth_configured: unknown }
@@ -245,7 +246,6 @@ export interface PostTasksIdVoteRequest { vote: -1 | 0 | 1 }
 export interface PostTasksIdVoteResponse { ok: boolean; task_id: unknown; my_vote: unknown; net_votes: unknown; total_votes: unknown }
 export interface PostTasksNewcomerRestockResponse { ok: boolean; stamped: unknown; results: unknown }
 export interface PostTasksRequest { version_id: string; title: string; description?: string; status?: string; touches?: string[]; est_minutes?: number; est_cost_usd?: number; manual_degree?: number; priority?: number; automation_tag?: string; credits_reward?: number; source?: string; source_ref?: string; value_summary?: string; kind?: string; discipline?: string; parallel_safe?: unknown; newcomer_friendly?: boolean; security_sensitive?: boolean; requires_rank?: string; auto_detect_touches?: boolean; criterion_ids?: unknown[]; module_key?: string; goal_id?: number }
-export interface PostTasksResponse { task: unknown; needs_migration: unknown; criteria: unknown; idempotent?: boolean; credits_reward?: unknown }
 export interface PostVersionsIdDoneWhenRequest { criterion_id: string; criterion_md: string; goal_id?: number; sort_order?: number }
 export interface PostVersionsIdDoneWhenResponse { ok: boolean; criterion: unknown }
 export interface PostVersionsRequest { id: string; name: string; status?: string; done_when?: string; scope_doc_path?: string; criteria?: unknown[] }
@@ -500,6 +500,8 @@ export interface BongosClient {
     postGoalsIdRequestsReqIdWithdraw(args?: RequestArgs): Promise<PostGoalsIdRequestsReqIdWithdrawResponse>;
     /** POST /goals/{id}/scope — rank: metic+archon */
     postGoalsIdScope(args: RequestArgs & { body: PostGoalsIdScopeRequest }): Promise<PostGoalsIdScopeResponse>;
+    /** GET /goals/{id}/suggest-criteria — rank: any-builder */
+    getGoalsIdSuggestCriteria(args?: RequestArgs): Promise<GetGoalsIdSuggestCriteriaResponse>;
     /** POST /goals/{id}/tasks — rank: any-builder */
     postGoalsIdTasks(args: RequestArgs & { body: PostGoalsIdTasksRequest }): Promise<PostGoalsIdTasksResponse>;
     /** POST /goals/{id}/transfer — rank: any-builder */
@@ -737,7 +739,7 @@ export interface BongosClient {
     /** GET /tasks — rank: any-builder */
     getTasks(args?: RequestArgs): Promise<GetTasksResponse>;
     /** POST /tasks — rank: metic+archon */
-    postTasks(args: RequestArgs & { body: PostTasksRequest }): Promise<PostTasksResponse>;
+    postTasks(args: RequestArgs & { body: PostTasksRequest }): Promise<ApiResponse>;
     /** GET /tasks/{id} — rank: any-builder */
     getTasksId(args?: RequestArgs): Promise<ApiResponse>;
     /** PATCH /tasks/{id} — rank: metic+archon */

package/clients/bongos-client/index.mjs

@@ -313,6 +313,8 @@ export function createClient(opts = {}) {
       postGoalsIdRequestsReqIdWithdraw: (args) => request("POST", "/goals/{id}/requests/{reqId}/withdraw", { hasBody: true }, args),
       // POST /goals/{id}/scope — rank: metic+archon — POST /goals/:id/scope
       postGoalsIdScope: (args) => request("POST", "/goals/{id}/scope", { hasBody: true }, args),
+      // GET /goals/{id}/suggest-criteria — rank: any-builder — GET /goals/:id/suggest-criteria
+      getGoalsIdSuggestCriteria: (args) => request("GET", "/goals/{id}/suggest-criteria", { hasBody: false }, args),
       // POST /goals/{id}/tasks — rank: any-builder — POST /goals/:id/tasks
       postGoalsIdTasks: (args) => request("POST", "/goals/{id}/tasks", { hasBody: true }, args),
       // POST /goals/{id}/transfer — rank: any-builder — POST /goals/:id/transfer

package/docs/adr/0139-platform-history-migration-to-cloudbongos.md

@@ -0,0 +1,94 @@
+# ADR 0139 — Migrate the platform work-history from the Off the Boats instance DB to the cloudbongos DB
+
+- **Status:** Accepted — **MIGRATION COMPLETE 2026-07-11** (owner greenlit the production run + the cut). Load into cloudbongos + verification done; TIER-2 valuable-history sweep done; and the WS-6 clean cut **fired + verified on live amazonprimea** (now game-only). The CB↔OTB split is complete (code + data). See the **Execution record** at the end.
+- **Date:** 2026-07-10
+- **Track:** internal (platform)
+- **Decides:** whether — and how — the Cloud Bongos *platform* work-history (tasks, goals, done-when criteria, the credit ledger, builder identities + balances) is physically relocated from the `amazonprimea` (Off the Boats "customer zero") Postgres database to the `cloudbongos` database, so a builder signing into the cloudbongos hall with the same GitHub sees their earned balance.
+- **Builds on:** ADR 0103 (core-first extraction; cloud-bongos is the trunk), ADR 0108 (configurable-root; the code half), ADR 0100 §3 (per-repo GDS), ADR 0016 (server-enforced permissions / trust boundary).
+- **Supersedes framing of:** ADR 0107 §3, which *deferred* cross-instance identity/payout as an open question, and the goal-41 "identity federated, authority per-project" design string. This ADR is the deliberate, bounded decision those left open — see Context.
+- **Companion:** the **code half** of the CB↔OTB split (amazonprimea task 1728 / R89 cutover; cloud-bongos re-seeded to the authoritative source by amazonprimea task 2190). This ADR is the **data half**.
+
+## Context
+
+Off the Boats (`amazonprimea` DB) is where Cloud Bongos itself was built — "customer zero." The R89 cutover already moved the platform **code** out: amazonprimea now consumes `@bongos/core` as a vendored dependency, and cloud-bongos is the authoritative editable core source. What remains inside the `amazonprimea` database is the platform's entire **work-history**: ~2,000+ platform tasks/goals/criteria, the credit ledger, and the builder identities that earned those credits — interleaved with the game's own ~57 tasks and game-earned credits.
+
+The requirement: a builder who signs into the cloudbongos hall with the same GitHub account should see the platform balance they earned. The platform's *own* design deliberately drew a line against this — goal-41's design says "identity is federated, authority (ranks/credits) is **not**," and ADR 0107 §3 explicitly defers cross-instance payout. So **relocating balances runs counter to that line and therefore needs its own decision record** — this ADR. It is *not* the future federation hub (goal 41), and it is not "finishing" an existing plan; it is a one-time, supervised data move.
+
+No cross-instance data-mover exists today. The only tooling is per-instance `pg_dump` backup; provisioning creates an *empty* DB; the public-mirror export moves *source code*, not data. The mover (WS-2) is therefore bespoke and is the bulk of the effort.
+
+## Decision
+
+### Locked decisions (owner)
+
+1. **Clean move, not copy.** The platform history *leaves* Off the Boats. No frozen dual copy — two diverging ledgers would double-count balances and rot.
+2. **Game credits stay at Off the Boats.** Everything else — platform credits, including orphan/no-task session & bonus awards — moves.
+3. **Identity is keyed by `builders.github_id`** (a stable global value present in both DBs). The migrated balance surfaces automatically on the builder's *existing* per-instance GitHub sign-in — **no federation hub is required**.
+4. **Currency: the number moves, the label adapts.** The reward unit is the integer `credits`; the label ("drachmae" at OTB, "credits" at the neutral starter) is pure instance config (`branding.currency.label`, ADR-referenced `<redacted>`). A 1,000 balance arrives as 1,000 in cloudbongos's unit automatically. *(Open: whether cloudbongos relabels to "drachmae" — see Open Questions.)*
+5. **The cloudbongos DB is near-empty → clean load, not a merge.** Only `lars589` (auto-seated founding Archon) and one CB-V1 test task exist; preserve them.
+6. **The ETL runs one-time, supervised, from the owner's Mac over SSH**, reaching both droplets' databases. It is not a builder-facing tool.
+
+### Classification is decided at the version level
+
+Every task/goal/criterion/credit inherits its **version's** label. `versions.id` is a text PK, so version rows copy without renumbering.
+
+| MOVE → cloudbongos (platform) | STAY at Off the Boats (game) |
+|---|---|
+| PMS-V1, PMS-V2, GDS-V3, GDS-V4 → BONGOS-V1 and all their tasks/goals/criteria/credits | Off the Boats V1/V2/V3 and their tasks/goals/pixel-art |
+| The dependency graph among those records | Credits earned on game work |
+| A copy of each builder identity (keyed by github_id) carrying the platform balance | The live game world + Colyseus server (untouched) |
+
+Edge cases: work that *built* the art pipeline = platform (moves); *running* it to draw tiles = game (stays) — WS-1 includes a human review pass. Orphan credits (`task_id = NULL`) move with the platform (reversible if the owner disagrees).
+
+## Workstreams (filed under switchover goal 26; execution owner-gated)
+
+- **WS-0 — Re-provision cloudbongos.com onto core 1.17.3 on a fresh DB, FIRST.** The box still runs a lift-and-shift clone whose deploy script references R89-removed paths; a re-provision *after* a load would wipe it. Must precede any data load. Preserve/re-seat the `lars589` Archon.
+- **WS-1 — Label every version game vs platform** (the single line that decides the move-set) + human pass over art-pipeline-style edge cases.
+- **WS-2 — Build the one-time mover (most effort).** Renumber bigint PKs; match builders by `github_id`; remap every FK; handle the polymorphic `dependencies` table per-kind; load with sync/promotion triggers OFF; preserve the `credit_log` idempotency key. **Prove on a throwaway copy first — never run blind on live.**
+- **WS-3 — This ADR.**
+- **WS-4 — Move day (OWNER GREENLIGHT REQUIRED).** Brief platform-write freeze at amazonprimea; full DB snapshots of both sides; run the mover into cloudbongos; rebuild balances from the ledger. Still reversible — amazonprimea untouched until WS-6.
+- **WS-5 — Prove it.** Reconcile record counts both sides; sample balances to the drachma; and the real test — a live GitHub sign-in at cloudbongos shows the right person with the right balance.
+- **WS-6 — Clean cut at Off the Boats.** Only after WS-5: delete the moved records from amazonprimea (reverse FK/dependency order), rebuild amazonprimea balances to game-only, repoint platform doc-links to cloudbongos.
+- **WS-7 — Close the switchover.** Tie off the goal; tell builders where their history now lives.
+
+## DB mechanics (the production hazards the mover must respect)
+
+- **Schema lives in `@bongos/core`** under `package/migrations/*.sql` (not in the amazonprimea repo anymore). `003_pms.sql` is foundational.
+- **Bigserial PK collision.** Both DBs allocate 1,2,3…; a naive copy collides on PK and *silently mis-links* FKs. Collide: `builders/tasks/claims/goals/credit_log/cost_log/karma_log/done_when_criteria/builder_sessions/idea_inbox/learnings/goal_membership_requests/core_upgrades`. Only text/natural PKs copy cleanly (`versions`, `achievements`). People are re-keyed off the natural `builders.github_id` (UNIQUE); everything else gets a fresh offset, and **every FK is rewritten** to the remapped ids.
+- **Polymorphic `dependencies` table — highest risk.** `(from_kind, from_id, to_kind, to_id)` over {task, goal, criterion} has **NO foreign keys** — ids are bare bigints disambiguated only by `*_kind`. The mover must remap `from_id`/`to_id` **per-kind**, or edges silently repoint. (The older `020_task_dependencies` task→task list also needs remapping.)
+- **`credit_log` double-count trap.** `credit_log` is an append-only ledger; `builders.total_credits` is a trigger-maintained cache (`trg_credit_log_apply` → `+= delta` on INSERT). Authoritative balance = `SUM(credit_log.delta)` per builder. **Load with triggers OFF, then rebuild `total_credits` from `SUM(delta)`** — else balances double. Same shape for `karma_log` → `builders.karma`.
+- **Idempotency key must be preserved.** A partial unique index on `credit_log(session_id) WHERE reason='session.token_reward'` enforces one token-reward payout per session. If the index or `session_id` values are lost, the token-reward path **double-pays on replay**.
+- **Promotion triggers also fire on status writes** (auto-promote backlog→ready on ship/satisfy/achieve). Load with all triggers disabled, then re-enable.
+
+## Consequences
+
+- **Positive:** the platform's work-history + rewards live at their true home; builders keep their earned balance across the sign-in they already use; the CB↔OTB separation is completed (data + code); no standing federation infrastructure is incurred.
+- **Reversibility:** everything through WS-5 is reversible — amazonprimea is untouched until WS-6, and both sides are snapshotted on move day. The point of no return is WS-6 (the clean cut).
+- **Risk:** a mistimed trigger or a missed FK/idempotency remap corrupts balances. Mitigation: prove the mover on a throwaway clone (WS-2), triggers-off load + ledger rebuild (WS-4), and full reconciliation before the cut (WS-5).
+
+## Open questions (owner)
+
+1. Confirm the exact game/platform version line (the single decision that fixes the move-set).
+2. Currency label at cloudbongos — keep "credits" or relabel to "drachmae" (one-line config; balances identical either way).
+3. Confirm tracking home for WS-0…WS-7 (proposed: switchover goal 26).
+4. Greenlight to *execute* (WS-4 onward) — nothing runs against production until then.
+5. WS-0 reality check — confirm cloudbongos.com was fully re-provisioned onto core 1.17.3 on a fresh DB, not merely code-updated.
+6. Orphan credits (`task_id = NULL`) — confirm the "move with platform" rule.
+
+### Open questions — RESOLVED (owner, 2026-07-11)
+
+1. Version line: **game V1/V2/V3 stay; PMS-V1, PMS-V2, GDS-V3, GDS-V4, BONGOS-V1 move** (as tabled). 2. Currency: **keep label "credits" at cloudbongos, 1:1 with drachmae** (no relabel). 3. Tracking home: **cloudbongos**. 4. **Greenlight given** — execute through production. 5. WS-0 reality check delegated to the executor → **verified: cloudbongos.com already runs @bongos/core 1.17.4 on the dependency model; no re-provision performed** (would have wiped legit native data). 6. Orphan credits: **move with platform** (confirmed).
+
+## Execution record (2026-07-11)
+
+Executed from the cloudbongos droplet (the ETL host): reads amazonprimea via the live `cohost-db-tunnel` (`127.0.0.1:5433`), writes the local cloudbongos DB. Scripts + full snapshots persist at `/home/lars/mig/` (`mover.js`, `verify.js`, `cut.js`, both pg_dumps, a pre-load cloudbongos snapshot). Tracked as amazonprimea switchover tasks 2192–2198.
+
+- **WS-0 (2192):** verified already-provisioned (core 1.17.4); no re-provision.
+- **WS-1 (2193):** per-table move-set classified (14 platform-history tables; ~50 OTB-instance-infra tables correctly stay).
+- **WS-2 (2194):** mover built (Node ETL: +1,000,000 PK offset; builders merged by `github_id`; versions upsert; deletes the target's core-seeded placeholder platform goals/criteria first; triggers-off load then rebuild `total_credits`/`karma` from `SUM(delta)`; `credit_log` `ON CONFLICT` on the token-reward partial index `DO NOTHING`). **Rehearsed on a throwaway copy: 25/25 checks pass.**
+- **WS-4 (2195):** **live load into cloudbongos COMMITTED** — 1,865 tasks, 27 goals, 69 criteria, 1,678 claims, 1,373 credit rows (1 token-reward idempotency skip), + full history; FK-check clean. Pre-load snapshot taken; amazonprimea untouched (fully reversible).
+- **WS-5 (2196):** **verified on live cloudbongos — 25/25.** All table counts + all six builder balances reconcile (lars589 **37,072**; jaxri 5,341; scootermack 2,389; IAMMASTERQUA 195; LarsCode 44; kingaonline 36). Game/native preserved; 0 FK orphans. `cloudbongos.com` leaderboard serves the migrated builders.
+- **WS-5b (2199) — TIER-2 valuable sweep (post-audit):** a full 59-table completeness audit confirmed the core move was 100% complete (2 flagged gaps were false positives), and surfaced ~13k deferred TIER-2 rows. Owner chose the valuable sweep → `sweep2.js` carried builder_memory, grading history, session_records/BFG, vulnerability_reports, builder_sessions (tokens redacted; restored 1,442 nulled claim links), + governance rows to cloudbongos; **verified 18/18**. Only the rebuildable `search_chunks` retrieval index was intentionally skipped.
+- **WS-6 (2197) — clean cut: FIRED + verified on live amazonprimea.** Pre-fire review found the first-draft cut too aggressive (it would delete live-game learnings/ideas/blockers), so it was rewritten **surgical** (`cut2.js`): deletes only platform-version-scoped work + the platform/orphan credit ledger, and preserves game + unlinked methodology, karma, builder-level tables, and all auth/game data. Run as the non-superuser app user (no trigger-disable) with children-before-parents + FK enforcement (safer). Rehearsed clean on a fresh copy, then fired after a final backup. Result: amazonprimea is game-only (versions V1/V2/V3, 157 game tasks, 123 game claims + auth intact, lars589 38,919→**1,824**, ledger reconciles, 0 platform residue, 0 FK orphans, app healthy).
+- **WS-7 (2198):** data + cut complete. Sole remaining owner step: announce to builders (Discord) where their history now lives.
+
+**Notes:** the migration's own bookkeeping tasks (2192–2199, all BONGOS-V1) moved to cloudbongos and were then removed from amazonprimea by the cut — self-referential, expected; their record lives here + in session memory. The 56-credit token-reward for the shared session `1b57dcb4` is dropped by the idempotency skip. Minor residue intentionally kept on amazonprimea (harmless, also on cloudbongos): platform karma, unlinked ideas/learnings, and vuln/achievement rows with nulled platform refs. Doc-links to platform tasks in the OTB repo now resolve on the cloudbongos hall. Scripts + backups: `/home/lars/mig/` on the cloudbongos droplet.

package/docs/adr/0140-cloudbongos-standalone-reprovision.md

@@ -0,0 +1,43 @@
+# ADR 0140 — cloudbongos.com re-provisioned to the standalone model, DB-preserving (closes ADR 0139 WS-0)
+
+- **Status:** Accepted — executed 2026-07-12
+- **Date:** 2026-07-12
+- **Deciders:** Lars (owner)
+- **Track:** internal (platform / infra)
+- **Builds on:** ADR 0108 (configurable-root / standalone consumer model), ADR 0126 (dedicated cloudbongos.com droplet), ADR 0129 (pull-timer deploy), ADR 0139 (CB↔OTB data migration — this closes its WS-0)
+
+## Context
+
+cloudbongos.com ran as a **lift-and-shift clone of the `amazonprimea` game repo** (ADR 0126): the `cloudbongos` systemd service executed `src/platform-server.js` out of `/home/lars/cloudbongos` (a checkout whose `origin` was `lars589/amazonprimea`), branded via `GDS_BRANDING_FILE`, against the separate `cloudbongos` DB.
+
+ADR 0139's **WS-0** called for re-provisioning cloudbongos.com onto the ADR 0108 standalone `@bongos/core` model *first, on a fresh DB*. WS-0 was recorded as "verified already-provisioned; no re-provision performed" — but that verification was wrong: the box kept running the amazonprimea clone. The data-half workstreams (WS-4/5/6) then loaded the platform history into the `cloudbongos` DB and cut OTB.
+
+The gap surfaced on 2026-07-12: `builders.cloudbongos.com` served a bare, unstyled shell — every `/builders/*` asset 404'd. Root cause: the running process was frozen on stale amazonprimea code (its pull-deploy silently no-op'd because `origin` tracked the unchanged amazonprimea repo, not a cloudbongos instance). The site had **never run the restored code**.
+
+The key constraint that inverts WS-0's original plan: the `cloudbongos` DB is now **full** — the migrated work-history and credit balances (e.g. `lars589` = 37,072). WS-0's "fresh DB" re-provision would wipe it. So the re-provision had to be **DB-preserving**.
+
+## Decision
+
+We will convert cloudbongos.com to a proper ADR 0108 **standalone instance**, preserving the existing `cloudbongos` DB, via a **build-alongside-then-flip** procedure:
+
+1. **Its own instance repo** — `cloudbongos/cloudbongos-instance` (private): lean `config/` (`branding.json` = the real cloudbongos.com domains over the neutral "Cloud Bongos" brand; `modules.json` = game-less + `provisioning`), a `bongos.config.json` instance-root pointer, and a **pinned `@bongos/core@1.17.3`** dependency. The engine, hall, and all platform code come from the package.
+2. **Materialize beside the old checkout** — clone + `npm ci` into a new dir (`/home/lars/cloudbongos-instance`); the old `/home/lars/cloudbongos` stays untouched as rollback.
+3. **Prove before flipping** — boot on a spare port against the live DB; confirm the hall serves and the leaderboard reads migrated balances; confirm `migrate` is a **no-op** (the DB already carries all 112 of 1.17.3's migrations).
+4. **Flip the service** — `cloudbongos.service` `WorkingDirectory` → the instance, `ExecStart` → `node_modules/@bongos/core/src/platform-server.js`; drop `GDS_BRANDING_FILE`; add `CLOUDBONGOS_INSTANCE_ROOT`; keep `PGDATABASE` + OAuth via `/etc/cloudbongos/web.env`. Back up the old unit first.
+5. **Repoint the ADR 0129 pull-deploy** — rewrite `/home/lars/deploy.sh` to fetch/reset the instance repo → `npm ci` (lockfile-gated) → core-package `migrate` → restart → healthz.
+
+The engine **source stays authoritative at `lars589/cloud-bongos`** (not relocated); the instance consumes `@bongos/core` from npm. A **verified DB backup precedes all changes**, and the old checkout + old unit + old deploy script are retained for instant rollback.
+
+## Alternatives considered
+
+- **Run cloudbongos.com directly from the `cloud-bongos` engine repo.** Rejected: it forces one host's identity into the shared/authoritative engine (the very anti-pattern that entangled cloudbongos with the amazonprimea repo), and it would ride the engine's development `main` with no stable pin — any work-in-progress commit could take the live site down.
+- **Keep the amazonprimea lift-and-shift; just restart / repoint that checkout.** Rejected: leaves the intended standalone model unfinished and keeps cloudbongos coupled to the OTB repo.
+- **Vanilla WS-0 (fresh-DB re-provision).** Rejected now: it would wipe the freshly-migrated history and balances — the whole point of ADR 0139. Hence the DB-preserving variant.
+- **Reuse an existing repo for the site** — `cloud-bongos` (the engine) or `cloudbongos/bongos` (the public AGPL source mirror). Rejected: both hold load-bearing roles; a dedicated `cloudbongos/cloudbongos-instance` keeps host identity out of both.
+
+## Consequences
+
+- cloudbongos.com runs the clean standalone model: hall renders, all three hosts (apex/builders/status) healthy, DB + balances intact. Future platform updates are a one-line `@bongos/core` pin bump, auto-deployed within ~2 min by the repointed pull-timer.
+- **Closes ADR 0139 WS-0** (belatedly, in DB-preserving form).
+- Deploy keys had to be **enabled org-wide on the `cloudbongos` org** so the box's read-only deploy key could attach to an org repo (they were disabled by default).
+- Follow-ups (non-blocking): retire `/home/lars/cloudbongos` + the backups after a soak; version `/home/lars/deploy.sh` into the instance repo and restore the ADR 0129 self-heal step; the packaged engine's `CORE_VERSION` constant lags its `package.json` (reports 1.17.2 while running 1.17.3) — cosmetic, flag upstream.

package/docs/adr/README.md

@@ -209,4 +209,7 @@ This keeps the decision history honest and traceable.
 | 0137 | [Upstream publish policy: `@bongos/core` patches are published MANUALLY (owner-gated), NOT auto-published on merge (task [#2158](https://example.com/builders#/task/2158), BONGOS-V1, goal 26; the SUPPLY half split out of ADR 0136 §5 / task 2150, builds on ADR 0134). Owner chose manual over auto. Decision: the owner runs `package-core.js --publish --live` to cut a release (optional `core-v<version>` git tag as the auditable marker — triggers no CI); `CORE_VERSION` (src/module-api.js) is bumped by hand in-task with a changelog line (provenance stays in git, not a release-tool side effect); NO npm write-token at rest (preserves ADR 0134 tokenless tooling — owner auths at publish time; only the read token exists); the no-leak/mirror-redact gate is already fail-closed inside `package-core.js`, so `--publish` cannot upload a leaking artifact. The ADR 0136 subscription consumes whatever is published; freshness is owner-paced by design. Rejected: auto-publish-on-merge (needs a standing npm write-token as a CI secret — reverses the tokenless posture for little gain at low, deliberate release volume). Revisit as a tag-triggered CI publish when the managed-fleet epic (task 1948) makes the manual step a real bottleneck. Ritual: docs/recipes/private-npm-distribution.md "Cutting a core release".](<redacted>.md) | distribution / npm |
 | 0138 | [A core-bundled module's external npm deps are declared per-module; the consumer composes them, core stays lean (task [#2160](https://example.com/builders#/task/2160), BONGOS-V1, goal 26; R89 cutover rehearsal finding F2, builds on ADR 0108 + ADR 0083). The discord module ships inside `@bongos/core` but `package-core.js` declares only express+pg, so a consumer that enables discord crashed at boot on missing `discord.js` (the only such case; discord is `default:false`). Owner chose lean-core over hoisting. Decision: core deps stay express+pg; a bundled module declares its own npm deps in `module.json` `dependencies` (schema-validated in `manifest-schema.js`; discord declares `discord.js`); greenfield `bongos init` composes the ENABLED modules' deps into the instance package.json (`enabledModuleDeps`→`buildInstancePackageJson`, existing pin wins, core always set); the R89 cutover preserves the monolith's existing closure ∪ core. Rejected: hoisting `discord.js` into core `optionalDependencies` (installs for EVERY consumer though discord is opt-in — cuts against ADR 0108 lean-core); `peerDependencies` (optional peers aren't auto-installed → crash remains; required peers = hoisting-with-warnings).](<redacted>.md) | modules / distribution |
 
+| 0139 | [Migrate the platform work-history (tasks/goals/credits/builder identities) from the Off the Boats instance DB to the cloudbongos DB — the DATA half of the CB↔OTB split (companion to the R89 code half). Owner-locked: clean move (platform history leaves OTB), game credits stay, identity keyed by `builders.github_id` (balance surfaces on the existing GitHub sign-in, no federation hub), currency number moves + label adapts, near-empty target = clean load. Needs its own ADR because it deliberately crosses the goal-41 "authority stays per-project" line + ADR 0107 §3's deferral. WS-0 (re-provision cloudbongos.com onto core 1.17.3 first) … WS-7; the mover (WS-2) is bespoke — bigint PK renumber + full FK remap, the polymorphic `dependencies` table per-kind, `credit_log` load-with-triggers-off then rebuild `total_credits` from `SUM(delta)`, preserve the `session.token_reward` idempotency index. EXECUTION is owner-gated (WS-4+); nothing runs against production until greenlit; prove on a throwaway copy first.](<redacted>.md) | platform / migration |
+| 0140 | [cloudbongos.com re-provisioned to the ADR 0108 standalone model, DB-PRESERVING — closing ADR 0139's skipped WS-0 (executed 2026-07-12). The site was a lift-and-shift clone of the `amazonprimea` repo frozen on stale code — every `/builders/*` asset 404'd — because its pull-deploy silently no-op'd against the unchanged game repo (`origin` was `lars589/amazonprimea`, not a cloudbongos instance); it had never run the restored code. WS-0's original fresh-DB re-provision would now WIPE the migrated history/balances, so a build-alongside-then-flip variant was used: a dedicated private `cloudbongos/cloudbongos-instance` repo (lean config over the neutral brand + a pinned `@bongos/core@1.17.3`), materialized beside the untouched old checkout, proven on a spare port against the live DB (migrate = clean no-op; leaderboard read migrated balances), then `cloudbongos.service` flipped to the instance + engine and the ADR 0129 pull-timer repointed at the instance repo. Engine source stays authoritative at `lars589/cloud-bongos` (not relocated); verified DB backup + retained old checkout/unit/deploy-script give instant rollback. Enabled org-wide deploy keys on the `cloudbongos` org so the box's read-only deploy key could attach.](<redacted>.md) | infra / Cloud Bongos |
+
 > ⚠️ **Numbering collision (known):** two ADRs share `0008`. The numbers were assigned in parallel sessions before the lock could be enforced. The files are kept under their existing filenames to preserve git history, but the table disambiguates them as `0008-a` / `0008-b`. New ADRs should resume at `0040` to avoid further collisions. (`0024` is also a real on-disk duplicate: the cloneable-repo/local-first-memory ADR and the multi-agent-system-architecture ADR were both numbered `0024` in parallel; both keep their filenames, disambiguated as `0024-a` / `0024-b` like `0008`. Likewise `0025` ended up with two on-disk files — the offsite-backup ADR and the structured-criterion↔task-link ADR — both kept under their existing filenames and disambiguated as `0025-a` / `0025-b`; separately, the BFG ADR had also claimed `0025` on 2026-05-30 and yielded to `0026`. A third happened 2026-06-06: `0036` was claimed in parallel by the builders-subdomain ADR ([#726](https://example.com/builders#/task/726)) and this Discord-channels ADR ([#727](https://example.com/builders#/task/727)); the Discord-channels ADR yielded to `0037`. A fourth landed 2026-06-10: `0044` was claimed in parallel by the palette-replacement ADR and the per-box game-preview ADR ([#897](https://example.com/builders#/task/897)); both keep their filenames, disambiguated as `0044-a` / `0044-b` like `0008`. A fifth was caught pre-land 2026-06-13: `0050` was claimed in parallel by the device-flow-admission ADR ([#1000](https://example.com/builders#/task/1000)) and the sandbox-for-everyone ADR ([#1001](https://example.com/builders#/task/1001)); the latter yielded to `0052` before merging, so there is no `0050` duplicate. A sixth was caught pre-land 2026-06-21: the tool-agnostic-design-layer ADR ([#1375](https://example.com/builders#/task/1375)) first collided at `0079` with the value-gated-autonomous-engagement ADR, then at `0080` with the llm-cache-api-transport ADR (both part of the 0075–0080 LLM-cost-reduction series, landed on `main` in parallel); it yielded to `0081` before merging, so there is no `0079`/`0080` design-layer duplicate. A seventh landed 2026-06-23: `0084` was claimed in parallel by the auto-derived-per-task-rank-floor ADR and the remove-default-spend-cap ADR (task 1499); the rank-floor ADR landed on `main` first, so the spend-cap ADR yielded to `0085`, leaving no `0084` duplicate. An eighth landed 2026-06-27: `0095` was claimed in parallel by the borrowed-memory-and-retrieval-concepts ADR (PR #459, landed first) and the cross-agent-context-management ADR ([#1651](https://example.com/builders#/task/1651), PR #460); both keep their filenames, disambiguated as `0095-a` / `0095-b` like `0008`. These two are companions — `0095-a` adopts the memory/retrieval concepts and explicitly defers the grep-vs-semantic question to `0095-b`.)