@bongos/core 1.17.0

package/docs/adr/0126-dedicated-cloudbongos-control-plane-droplet.md

@@ -0,0 +1,30 @@
+# ADR 0126 — Dedicated cloudbongos.com control-plane droplet (infra split from the co-hosting box)
+
+**Status:** Accepted — implemented 2026-07-05 (task [#2063](https://example.com/builders#/task/2063)).
+
+## Context
+
+cloudbongos.com (Customer 0, the vanilla dogfood instance — [ADR 0062](<redacted>.md) §2, [`docs/recipes/cloudbongos-standup.md`](../recipes/cloudbongos-standup.md)) ran as a **co-tenant on the OTB game droplet** (`REDACTED_IP`): same checkout, port 3002, its own `cloudbongos` DB. The token-holding **control plane** lived on that same box — `/etc/example/box.env` holds the account's DigitalOcean token **and** the Cloudflare token, drained by `scripts/gds/provision.js` (the instance provisioner, [ADR 0111](<redacted>.md)) and `scripts/gds/box.js` (dev boxes).
+
+That co-location is the weak point in the trust posture: the powerful, account-wide cloud tokens sat on the **same machine** as the game and any co-hosted third-party instance (`emersonian-circles.`, `staging.`). A compromise of any co-hosted workload could reach <redacted> and droplet creation. The existing plan ([ADR 0100](<redacted>.md)/[0108](<redacted>.md), spine R84→R89) only separated cloudbongos.com as a *side effect* of the deferred "Example split" (R89, [#1728](https://example.com/builders#/task/1728)), keeping it co-tenant "for cost" until then.
+
+The owner elected to pull the **infrastructure** separation forward, explicitly accepting a second droplet's cost, for the security division.
+
+## Decision
+
+Run cloudbongos.com on its **own dedicated droplet** that is also the **sole token-holding control plane**:
+
+- **New droplet** `cloudbongos` — DigitalOcean `REDACTED_IP`, nyc3, `s-1vcpu-2gb` ($12/mo), Ubuntu 24.04, tagged `cloudbongos-control` (deliberately **not** `PROVISION_TAG`, so the provisioning reconciler never treats the control plane as a disposable instance).
+- **Structural SSH separation** — reached only via a dedicated `cloudbongos_ed25519` key, distinct from the example box's key.
+- **Own stack** — Node 22 / PostgreSQL 16 / Caddy, IPv6 egress disabled (so the IPv4-locked Cloudflare token can never be spuriously rejected — `checkDnsTokenScope` uses plain `fetch` with no `-4`, unlike `infra/box-dns-cloudflare.sh`).
+- **Holds the tokens** — `/etc/cloudbongos/box.env` (mode 600) carries a **new account-wide Cloudflare token** (Edit-zone-DNS, all zones, IP-locked to `REDACTED_IP`) + the DigitalOcean token. This is the box that provisions instance subdomains for the hosting/provisioning module ([ADR 0111](<redacted>.md) §2 — tokens on the control plane, never the web tier; mirrors [ADR 0031](<redacted>.md) §6).
+- **The co-hosting box** (the former OTB droplet, `REDACTED_IP`) stays as-is for the game + co-hosted project instances; the cloudbongos co-tenant unit was removed.
+
+The checkout is still a clone of `example-owner/example` running `src/platform-server.js` with `GDS_BRANDING_FILE=config/branding.cloudbongos.json` (a **lift-and-shift**, not the ADR 0108 pinned-`@cloudbongos/core` standalone model — that remains the longer-term shape).
+
+## Consequences
+
+- The account-wide cloud tokens no longer sit next to the game or third-party workloads — the division the owner asked for. This also **de-risks R89**: cloudbongos.com is already infra-decoupled, so splitting Example can't break it.
+- cloudbongos.com's data was migrated (pg_dump → restore) and DNS cut over (apex + `builders.` + `status.` A records → `REDACTED_IP`, kept proxied); `emersonian-circles.`/`staging.` deliberately stayed on the co-hosting box.
+- **Not yet done (tracked):** the co-hosting box **still holds its own DO token + a narrow (example.com-locked) CF token** for dev-box (`box.js`) + `provision-intent-runner` duties — reaching "zero cloud tokens on the co-hosting box" needs dev-box + instance orchestration to move to this control plane first (`provision.js` does local ops today; remote-orchestrating co-tenant workloads is unbuilt) — task [#2065](https://example.com/builders#/task/2065). The new box has **no deploy automation** yet (it won't track `main` until wired) — task [#2064](https://example.com/builders#/task/2064). The old `cloudbongos` DB is retained on the co-hosting box as a rollback net until a bake period passes.
+- No hardening drop-in on `cloudbongos.service` yet (mirror `infra/example.service.d/hardening.conf` once proven — the standup recipe's standing note).

package/docs/adr/0127-cross-box-fleet-observability.md

@@ -0,0 +1,64 @@
+# ADR 0127 — Cross-box fleet observability on the control-plane droplet
+
+Status: Accepted (2026-07-05, task [#2059](https://example.com/builders#/task/2059))
+
+## Context
+
+Task 2020 stood up Grafana + Prometheus on the co-hosting box, scraping that one
+box's Bongos API. The owner then re-scoped it: the exported metrics (`gds_http`,
+`gds_tasks`, `gds_claims`, `gds_builders`, `gds_auth_failures`) measure the **Bongos
+platform API**, not any single game — so the dashboards are *platform* observability
+and belong on the **cloudbongos** domain, watching **every** instance, not a
+project-specific one.
+
+Then [ADR 0126](<redacted>.md) moved
+cloudbongos.com onto a dedicated **control-plane droplet** (REDACTED_IP) that
+holds the account-wide Cloudflare token and serves `*.cloudbongos.com`. That split
+the fleet across two droplets:
+
+- **control-plane box** (REDACTED_IP): `cloudbongos` instance.
+- **co-hosting box** (REDACTED_IP): `example` (the game) + `emersonian-circles`.
+
+So platform observability must (a) live where a `metrics.cloudbongos.com` surface
+belongs — the control-plane box (it has the cloudbongos origin cert + Caddy + the
+DNS token), and (b) scrape instances on **both** boxes. The apps' `/metrics`
+exporters bind `127.0.0.1` only, and a remote scrape normally needs a `METRICS_TOKEN`
+(Bearer). Both droplets share a DigitalOcean **private VPC** (`10.108.0.0/20`).
+
+## Decision
+
+- **Grafana + Prometheus run on the control-plane box.** `metrics.cloudbongos.com`
+  (proxied A record → REDACTED_IP, on the `*.cloudbongos.com` origin cert) is
+  reverse-proxied to Grafana, Archon-only (Caddy `basic_auth` + Grafana admin login).
+- **Prometheus scrapes the whole fleet with a per-`project` label.** `cloudbongos`
+  is local (`127.0.0.1:3002`). The co-hosting box's instances are scraped **over the
+  private VPC** via two tiny `socat` TCP forwarders on that box (`metrics-fwd-*`
+  systemd units) bound to its private IP (`10.108.0.2:9101→127.0.0.1:3000`,
+  `:9102→:3004`), **ufw-locked to the control-plane box's private IP** only.
+- **socat (raw TCP relay), not a Caddy/token proxy, for the cross-box hop.** A raw
+  relay preserves the exporter's loopback-with-no-`X-Forwarded-For` semantics, so the
+  app serves metrics **without a token and without a restart**. The security boundary
+  is the private VPC + the ufw allow-list (only the control-plane box) + the fact that
+  the control-plane box is already the most-trusted host in the fleet. The exporter's
+  `METRICS_TOKEN` Bearer path is **reserved for future off-VPC / dedicated-droplet
+  instances**, which can't use a private forwarder.
+- Dashboards gain a `project` template variable; every query filters by
+  `project=~"$project"` (default All), so each panel shows one instance or the fleet.
+
+## Consequences
+
+- **+** Clean separation matching ADR 0126: the cloudbongos-branded metrics surface
+  lives on the cloudbongos box, not the game box. One fleet-wide pane. Neither
+  Prometheus nor Grafana is publicly bound; the cross-box hop never leaves the VPC.
+  No live-game restart was needed to wire it.
+- **−** Each socat forwarder exposes the **whole** app port (not just `/metrics`) to
+  the control-plane box over the VPC. Accepted: ufw restricts the source to the one
+  trusted control-plane IP, the traffic stays on the private VPC, and a compromise of
+  the control-plane box is already game-over (it holds the account-wide CF + DO
+  tokens). A `/metrics`-only exposure would require a Caddy proxy + `METRICS_TOKEN` +
+  restarting the instances — not worth it for this trust posture.
+- **−** Cross-box scraping depends on the DO VPC + the `metrics-fwd-*` units + ufw
+  rules on the co-hosting box. If that box is re-provisioned, re-add them (see
+  [`infra/grafana/README.md`](../../infra/grafana/README.md)).
+- **Follow-up:** token-based (or DNS-SD) discovery for provisioned / dedicated-droplet
+  instances — the general hosting-module case, not yet wired.

package/docs/adr/0128-provisioning-runner-privilege-and-db-auth-model.md

@@ -0,0 +1,46 @@
+# ADR 0128 — Provisioning runner privilege + DB-auth model (`PROVISION_SUDO`)
+
+**Status:** Accepted — implemented 2026-07-05 (task [#2066](https://example.com/builders#/task/2066), BONGOS-V1, goal 35 / criterion `project-creation-flow`).
+
+## Context
+
+[ADR 0111](<redacted>.md) built `scripts/gds/provision.js` — the control-plane runner that drains `provisioning_intents` and composes the [cloudbongos-standup](../recipes/cloudbongos-standup.md) runbook (createdb → GDS-only migrate → per-instance `/etc/<slug>/web.env` → systemd unit → per-instance Caddy snippet → `/healthz`). It was written injectable + dry-run-default and unit-tested, **but never run end-to-end** — every existing co-located instance (`emersonian-circles`, the vanity doors) was hand-wired by an operator. The 2026-07-05 first real greenfield standup attempt ([#2053](https://example.com/builders#/task/2053)–[#2056](https://example.com/builders#/task/2056)) surfaced three ops gaps. Two were resolved on-box (Cloudflare token scope → [ADR 0126](<redacted>.md); the Caddy on-demand-TLS global that the live `/etc/caddy/Caddyfile` lacked). This ADR is the third, load-bearing one.
+
+`provision-intent-runner.service` runs as **`User=lars`** (a non-root user). But every mutating step assumed a privilege the runner does not have when driven headlessly:
+
+- **`/etc` writes** — `web.env` (`/etc/<slug>/`), the systemd unit (`/etc/systemd/system/`), and the Caddy snippet (`/etc/caddy/sites/`) went through a bare `fs.writeFileSync`. Confirmed on the box: `lars` cannot write under `/etc` (`mkdir /etc/_provtest` → `EACCES`).
+- **`systemctl` / `caddy` reloads** — `daemon-reload`, `enable --now`, `reload caddy`, `disable --now` ran without `sudo`.
+- **`createdb` + `migrate`** — both authenticate to Postgres by **peer auth as the running user**. On this box `lars` is *not* a usable PG role (the app connects via `DATABASE_URL`), so `createdb <slug>` and `migrate.sh`'s `psql` both fail.
+
+Two things additionally made a naive "just add `sudo`" fix silently fail: the unit set **`NoNewPrivileges=true`** (which sets `PR_SET_NO_NEW_PRIVS` and *blocks the setuid `sudo` binary from escalating at all*), and `sudo` resets the environment (so a bare `sudo -u postgres PGDATABASE=x ./migrate.sh` would have `sudo` parse `PGDATABASE=x` as a command).
+
+The whole point is that this runner must NOT bake operator identity into behavior ([ADR 0016](<redacted>.md)), tests must stay hermetic (no shell/DB/network), and the same code drives co-tenant, standalone, and (via cloud-init) dedicated shapes.
+
+## Decision
+
+Add a single config knob, **`PROVISION_SUDO=1`** (alias `PROVISION_PRIVILEGED=1`), read once into `CONFIG.privileged`. **Default OFF** preserves the exact current behavior (bare commands, direct `fs` writes) — so tests, a root context, and the co-tenant-legacy path are byte-for-byte unaffected. When ON, exactly the privileged steps escalate, and **dry-run still logs the exact command** either way:
+
+- **`/etc` writes** → the body is staged in a temp file (`os.tmpdir()`, lars-writable) and placed atomically with **`sudo install -D -m <mode> <tmp> <dest>`** (`-D` creates the parent dir, e.g. `/etc/<slug>/`; `-m` sets the mode). The install runs through the *same* injected `exec`, so it shares the dry-run/apply + logging path. `makeWriteFile` escalates only when a call opts in with `{ sudo: true }` — the three `/etc` destinations do; the scaffold's temp/`.gitignore` writes (under `/tmp` and `/srv/<slug>`) stay direct.
+- **`systemctl` / `rm` under `/etc`** → `sudo`-prefixed at the call site (`provisionInstance` + `teardownInstance`).
+- **`createdb` + `migrate`** → run as the **postgres** OS user (`sudo -u postgres …`), which peer-auths as the PG superuser (the Ubuntu default) — so the runner never needs `lars` to be a PG role. `migrate` passes its env via `env PGDATABASE=… MEDUSA_GDS_ONLY=1` and runs the script via `bash …` so the vars survive `sudo`'s env reset. Applies to both the co-tenant (`migrateCmd`) and standalone (`standaloneMigrateCmd`) legs.
+
+`infra/provision-intent-runner.service` is updated to make the model operational: **`Environment=PROVISION_SUDO=1`** turns the knob on for the deployed runner, and **`NoNewPrivileges=false`** (with an explanatory comment) is required — a `true` value silently defeats every `sudo` above. `PrivateTmp=true` stays (the `sudo install` temp files live in the service's private `/tmp`, which its sudo children share).
+
+**Preconditions** (operational, documented — the same class as "the runner holds the DO/CF tokens"):
+
+1. The runner's user has **passwordless sudo** on the control-plane box (true on `REDACTED_IP`).
+2. The checkout `migrate` runs from must be **readable by the `postgres` OS user** (on `REDACTED_IP` the standalone base is `/srv/cloudbongos`, world-traversable — *not* under a `700` home).
+
+## Consequences
+
+- **Goal-35 automation can complete end-to-end** — this was the blocker for the real greenfield standup ([#2056](https://example.com/builders#/task/2056)) and criterion `project-creation-flow`.
+- **No blast radius when off.** The knob defaults false; all 30 pre-existing unit tests stay green, and any non-runner invocation (a CLI dry-run, a root context) is unchanged. 8 new tests pin both the escalated command shapes (`sudo -u postgres createdb`, `env`+`bash` migrate, `sudo install -D -m`, `sudo systemctl`) and the *absence* of any `sudo` in the default path.
+- **The runner is intentionally less sandboxed** (`NoNewPrivileges=false`, sudo enabled). Accepted: this runner is already the sole holder of the DO/Cloudflare tokens and performs inherently privileged control-plane ops; least-privilege here means *explicit, per-step* `sudo` (not running the whole process as root).
+- **The dedicated-droplet cloud-init path is deliberately unchanged** (`dedicatedUserData`). It runs as root on a fresh droplet — a different privilege + file-perms model — and is out of the co-tenant/standalone scope this task exercised; escalating it is a separate change.
+- **Follow-ups noted from the standup:** the live `/etc/caddy/Caddyfile` drifts from `infra/Caddyfile` with no auto-sync (a deploy-time reconcile is worth considering); the migrate-as-postgres readable-checkout precondition should be asserted by the box provisioning, not just documented.
+
+## Alternatives considered
+
+- **Grant `lars` a PG login role + writable `/etc`.** Rejected: non-portable per-box setup, and it weakens the trust boundary — the runner shouldn't *own* `/etc` or be a standing PG superuser; `sudo -u postgres` is scoped to the two DB commands.
+- **Run the whole runner as root** (`User=root`). Rejected: over-privileged for the many non-privileged steps (git, npm, node, healthz, the DNS hook). Per-step `sudo` keeps the default footprint small and every escalation greppable.
+- **Do createdb/migrate via the app `DATABASE_URL` connection** instead of `sudo -u postgres`. A valid option the task description named, and one an instance may adopt — but the runner doesn't hold the app DB creds today and the standup env uses peer auth, so `sudo -u postgres` is the portable default. Left open for a future instance that wires DB creds into the runner's box.env.

package/docs/adr/0129-cloudbongos-control-plane-pull-deploy.md

@@ -0,0 +1,34 @@
+# ADR 0129 — cloudbongos.com control-plane box deploys by a pull timer, not the CI push
+
+**Status:** Accepted — implemented 2026-07-05 (task [#2064](https://example.com/builders#/task/2064)). Follows [ADR 0126](<redacted>.md).
+
+## Context
+
+The 2026-07-05 dedicated-droplet migration ([ADR 0126](<redacted>.md), task [#2063](https://example.com/builders#/task/2063)) moved cloudbongos.com onto its own box (`REDACTED_IP`, checkout `/home/lars/cloudbongos`, `cloudbongos.service`, port 3002). The co-hosting box (`REDACTED_IP`) still auto-deploys **example.com** via [`.github/workflows/deploy-prod.yml`](../../.github/workflows/deploy-prod.yml) (SSH → `~/deploy.sh` on merge to `main`, [ADR 0042](<redacted>.md)). That path only touches the co-hosting box. **Nothing pulled `main` onto the new box**, so cloudbongos.com served its boot-time code and drifted — ADR 0126 §Consequences flagged this as task 2064.
+
+The task allowed either extending the CI push workflow to also target the new box, **or** a pull-based timer on the box.
+
+## Decision
+
+Deploy the control-plane box with a **pull-based systemd timer**, not by extending the CI push.
+
+- [`scripts/deploy/deploy-cloudbongos.sh`](../../scripts/deploy/deploy-cloudbongos.sh) — the deploy: `git fetch` + reset to `origin/main` → `npm ci --omit=dev` (only if `package-lock.json` changed) → `PGDATABASE=cloudbongos MEDUSA_GDS_ONLY=1 ./scripts/migrate.sh` → `sudo systemctl restart cloudbongos` → poll `127.0.0.1:3002/healthz`, then rebuild the gitignored Hall nav surfaces. Idempotent, with a fast no-op exit when `HEAD == origin/main`.
+- [`infra/cloudbongos-deploy.service`](../../infra/cloudbongos-deploy.service) + [`infra/cloudbongos-deploy.timer`](../../infra/cloudbongos-deploy.timer) — a `oneshot` service fired every ~2 min (measured from the end of the last run).
+
+### Why pull, not CI push
+
+1. **Blast radius.** The dedicated box exists to shrink the cloud-token / prod-SSH-key exposure (ADR 0126). Extending CI would require storing **this box's** prod SSH key as a GitHub Actions secret — more secret sprawl, against the migration's whole grain. A pull uses the box's **existing** GitHub deploy key (`git@github-deploy:…`), so no new secret leaves the box and the shared `deploy-prod.yml` is untouched.
+2. **Convention.** It matches the self-healing `*-runner.timer` units already in `infra/` (e.g. `provision-intent-runner.timer`), and the deploy self-installs its own unit changes on the next run (the [ADR 0110](<redacted>.md) self-heal pattern) — no manual re-install.
+3. **Cost of staleness is low.** Worst case is one tick (~2 min) behind `main` for a Customer-0 dogfood instance. The idle-tick cost is a single `git fetch` + SHA compare (the no-op fast path).
+
+### Two deliberate divergences from `deploy-prod.sh`
+
+- **The executed script is a stable copy at `/home/lars/deploy.sh`, not the in-checkout file.** This script `git reset --hard`s its own checkout; a running bash script whose backing file is rewritten mid-run can read garbage. Keeping the executed copy outside the checkout makes the reset harmless — the same reason the co-hosting box hand-installs `deploy-prod.sh`. The copy is refreshed from the checkout at the end of each successful run, so improving the repo script propagates on the next deploy.
+- **The SEC [#863](https://example.com/builders#/task/863) main-audit gate is non-fatal here.** On the co-hosting box it is a hard blocker resolving ranks from the *owning* OTB DB. Here `PGDATABASE=cloudbongos`, so it resolves ranks from the cloudbongos builder set (OTB authors are unknown to it) — it can only ever misfire, and the authoritative preventive gate already runs on the co-hosting box + CI against this **same** shared `main` before it advances. So it runs for the signal but never blocks; a spurious abort must not strand cloudbongos.com on stale code — the very failure 2064 fixes.
+
+## Consequences
+
+- cloudbongos.com now tracks `main` within ~2 min of a merge, with no new GitHub secret and no change to the shared prod deploy.
+- **One-time bootstrap is unavoidable** (the box can't install its own first deploy automation): an operator installs `/home/lars/deploy.sh` + the two units over SSH once — see [`docs/recipes/cloudbongos-standup.md`](../recipes/cloudbongos-standup.md) §"Deploy automation". After that it self-heals.
+- When cloudbongos.com moves to the pinned-`@cloudbongos/core` standalone model ([ADR 0108](<redacted>.md)), this script is the seam that converts `git reset --hard` → `git pull` + `npm ci` (the [`deploy-instance.sh`](../../scripts/deploy/deploy-instance.sh) shape) — a one-file change, not a new pipeline.
+- Does not affect task [#2065](https://example.com/builders#/task/2065) (stripping cloud tokens off the co-hosting box); that is orthogonal.

package/docs/adr/0130-provision-remote-exec-over-ssh.md

@@ -0,0 +1,61 @@
+# ADR 0130 — provision.js remote-exec over SSH: the control plane orchestrates co-tenant workloads on the co-hosting box
+
+**Status:** Accepted — code implemented 2026-07-05 (task [#2065](https://example.com/builders#/task/2065)); **activation (SSH trust + token rotation) is a sequenced owner-op**, see §Activation. Follows [ADR 0126](<redacted>.md).
+
+> **Superseded in part by [ADR 0132](<redacted>.md)** (task 2071). The remote-exec *mechanism* here stands, but activation found the co-hosting box runs **five** token-consuming runners (not one), each reading its queue from a **localhost-only** Postgres. So the migration also needs an SSH DB tunnel + control-plane variants of all five runners, and the runner unit named below (`provision-intent-runner-cloudbongos.*`) is replaced by `cohost-provision-intent-runner.*`. **Follow ADR 0132's §Activation, not the §Config + runner move step here.**
+
+## Context
+
+[ADR 0126](<redacted>.md) moved cloudbongos.com onto its own dedicated droplet that is also the **sole token-holding control plane** (`/etc/cloudbongos/box.env` holds the account-wide DigitalOcean + Cloudflare tokens). But it left the **co-hosting box** (`REDACTED_IP`) still holding its own DO token + a narrow Cloudflare token, used by two control-plane duties that still run *there*:
+
+- `box.js` — dev-box lifecycle (create/destroy droplets, DNS).
+- `provision.js` + `provision-intent-runner` — instance provisioning for co-tenant instances (`emersonian-circles.`, `staging.`) that **run on the co-hosting box**.
+
+Reaching the owner's goal — **zero cloud tokens on the co-hosting box** — means moving both duties onto the control plane. The obstacle ADR 0126 named: **`provision.js` does its box-mutating steps LOCALLY** (`createdb`, `migrate`, write `/etc/<slug>/…`, `systemctl`, Caddy, healthz). If it runs on the control plane, those steps would hit the *control-plane* box — but the co-tenant instances live on the *co-hosting* box. So the runner needs a way to execute those steps **on the co-hosting box, remotely.**
+
+## Decision
+
+Add a **remote-exec-over-SSH path** to `provision.js` (`scripts/gds/provision.js`), gated behind `PROVISION_REMOTE_HOST` and **OFF by default** (unset ⇒ every step runs locally, byte-identical to today).
+
+### The executor split
+
+`provision.js` already runs every runbook step through two injected factories (`makeExec` / `makeWriteFile`). The change threads a **target** through them:
+
+- **`exec` / `writeFile` — box-target.** When `PROVISION_REMOTE_HOST` is set, box-mutating steps run on that host over `ssh` (else local). `makeExec` composes `cd <remoteCwd> && <env> <cmd>` and feeds it to `ssh <host> bash -s` via **stdin** — so nothing needs shell-quoting on the way over (the classic remote-exec footgun). `makeWriteFile` base64-encodes the body and decodes it into place with `sudo tee` on the box (no raw secret on a command line).
+- **`controlExec` / `controlWriteFile` — always local (the control plane).** Two steps must NOT cross to the co-hosting box because they need the cloud token / the packaging toolchain that live only on the control plane:
+  - the **Cloudflare DNS hook** (`BOX_DNS_HOOK`) — the whole point is that the co-hosting box has no token;
+  - the **standalone repo scaffold** (`git clone` / `package-core` / `bongos init` / `git push`).
+
+`sudo` (from `PROVISION_SUDO`, [ADR 0128](<redacted>.md)) composes cleanly: for a remote step the `sudo` runs on the co-hosting box (as its passwordless-sudo user). Co-tenant A records point at `PROVISION_PUBLIC_IP` = the **co-hosting box's** IP (where the co-tenant actually runs), which is the "point `PROVISION_PUBLIC_IP` appropriately" clause of the task.
+
+### `box.js` needs no code change
+
+`box.js` is entirely **API-driven** (DigitalOcean + Cloudflare clients + the DNS hook) — it does no local box-mutating ops. So the dev-box lifecycle "moves to the control plane" simply by *running there* (it reads the tokens from `/etc/cloudbongos/box.env`) + relocating the `box-intent-runner` timer — a box-side op, no code.
+
+### Why remote-exec (SSH) over the alternatives
+
+- **vs. running the runner as-is on the co-hosting box** — that is the status quo, and it *requires* the tokens to stay there. Rejected: it's exactly what we're removing.
+- **vs. a small agent/API on the co-hosting box the control plane calls** — more moving parts, a new listening surface + its own auth. SSH is already the trust primitive for these boxes (the 2063 migration itself was SSH-driven); reuse it.
+- **vs. making every co-tenant a dedicated droplet** (no remote-exec needed) — real money per instance + a migration of the existing co-tenants; out of scope.
+
+## The trust boundary this creates (the owner's call)
+
+This gives the **control-plane box SSH command authority over the co-hosting box** (a key from the control plane in the co-hosting box's `authorized_keys`). The arrow points **control-plane → co-hosting**, never the reverse — the token-holding box commands the token-free box, not vice-versa, so a compromise of the co-hosting box still cannot reach the tokens. This is the deliberate posture; the SSH trust is installed as an explicit operator step (below), not by any auto-deploy.
+
+## Activation (sequenced owner-op — do NOT reorder)
+
+The code is inert until activated. Because both a remove-tokens step and a runner-move are involved, order matters (tracked in the blocker attached to task 2065):
+
+1. **SSH trust** — put the control-plane box's key in the co-hosting box's `authorized_keys` (control-plane → co-hosting). Verify `ssh lars@REDACTED_IP true` from the control plane.
+2. **Config + runner move** — install `infra/provision-intent-runner-cloudbongos.{service,timer}` on the control plane (carries `PROVISION_REMOTE_HOST` / `PROVISION_REMOTE_CHECKOUT` / `PROVISION_PUBLIC_IP`), `enable --now` the control-plane timer, and **disable the generic `provision-intent-runner.timer` on the co-hosting box in the same window** (never both — they'd double-drain). Run `box.js` (dev-box duties) from the control plane too.
+3. **Verify** — provision/reconcile a co-tenant end-to-end from the control plane (its steps land on the co-hosting box; DNS lands from the control plane).
+4. **Remove + rotate the tokens** — only once (1)–(3) are proven: delete `DO_API_TOKEN` + `CLOUDFLARE_API_TOKEN` from `/etc/example/box.env` and **rotate** them (DigitalOcean + Cloudflare consoles) so the old values are dead even if they leaked. **Irreversible / console-only — the owner does this.**
+5. **Drop the rollback DB** — after a bake period, drop the retained `cloudbongos` DB on the co-hosting box (ADR 0126 rollback net).
+
+## Consequences
+
+- The co-hosting box can reach zero cloud tokens once activated; the control plane orchestrates the co-tenants it hosts over SSH.
+- Default-OFF means this lands safely on `main` and changes nothing until the owner runs the activation — the co-hosting runner keeps working meanwhile.
+- New trust edge (control-plane → co-hosting SSH), accepted as above.
+- ~~Not addressed here (future): a co-tenant that should run *on the control plane* while `PROVISION_REMOTE_HOST` is set — today the flag is global (all co-tenant provisions go to the remote host). Fine for the current fleet (co-tenants live on the co-hosting box); revisit if a control-plane-local co-tenant is ever wanted.~~ **Resolved (task [#2074](https://example.com/builders#/task/2074)).** A **standalone** instance (`hosting_shape='standalone'`, its own repo dir — ADR 0108) IS the control-plane-local case: `scaffoldStandaloneRepo` already builds its repo dir on the control plane, so the follow-up box steps (code sync, migrate, `/etc`, systemd, Caddy, healthz) must run **there too**, not cross to the co-hosting box that never had that dir. `provision.js` now picks the executor **per hosting shape**, not by the global flag: standalone → the control-plane executors (`controlExec`/`controlWriteFile`); co-tenant + dedicated unchanged. A standalone's DNS A record targets `PROVISION_CONTROL_PLANE_IP` (this box), not `PROVISION_PUBLIC_IP` (the co-hosting box); a greenfield `demo.cloudbongos.com` was the driving case (goal 35 criterion 165). The per-instance override is shape-derived, so no new global flag was needed.
+- **TLS companion to the above (task [#2077](https://example.com/builders#/task/2077)).** Because a standalone now runs control-plane-local under the control plane's `*.cloudbongos.com` **wildcard Cloudflare Origin cert**, Caddy already has a matching cert and never fires on-demand ACME — so the co-tenant posture (DNS `proxied=false` + on-demand Let's Encrypt, which needs the challenge to reach the origin) would serve that origin cert to *direct* clients: publicly **untrusted**, and it exposes the control-plane IP. So `provision.js` sets the standalone A record **`proxied=true`** (via a new `BOX_PROXIED` flag on `infra/box-dns-cloudflare.sh`, default off): the Cloudflare edge fronts it with a public cert (origin cert valid behind Full-strict) and the origin IP stays hidden. Co-tenant + dedicated stay `proxied=false` (their on-demand ACME is load-bearing). Same shape-derived split as the executor/IP decision above. Known follow-up: a standalone on a **custom** domain (no wildcard origin cert) would still want `proxied=false` + on-demand ACME — no such instance exists today (idea 528).

package/docs/adr/0131-rank-scoped-skill-visibility.md

@@ -0,0 +1,47 @@
+# 0131 — Rank-scoped skill visibility: feasibility spike + recommended approach
+
+- **Status:** Spike outcome — **Proposed** (pending owner go-ahead to build). Documents a feasibility finding so future agents don't re-attempt the approach that doesn't work.
+- **Date:** 2026-07-05
+- **Deciders:** jaxri (Metic), Claude. Owner chose "design spike first" for task 1650.
+- **Task:** [#1650](https://example.com/builders#/task/1650)
+
+## Context
+
+Task 1650 asks that a builder's Claude session list **only** the skills their live rank can use. Today every session lists every skill, so a lower-rank builder can invoke a gated skill (e.g. `/planning-session`, `/blocker-review`) and only gets stopped partway through — a confusing dead-end.
+
+**This is UX decluttering, not a permission boundary.** Authority is already enforced two ways that stay exactly as-is: the server's `requireRank` (→ 403, [ADR 0016](<redacted>.md)) and each gated skill's own early rank self-check. Hiding a skill from the menu removes a dead-end; it grants and removes nothing. The task's assumed mechanism was **a `SessionStart` hook that filters the skill list by the rank we fetch at session start** (we already run such a hook, `.claude/hooks/session-start.js`).
+
+## Finding (the spike result)
+
+**Claude Code hooks cannot filter, hide, remove, or rewrite the skill listing the model sees.** This is unambiguous in the current docs:
+
+- Skills are discovered by **directory scan** at session start (`.claude/skills/<name>/SKILL.md`); each skill's `name` + `description` is injected into context as a "skill listing" (the full body loads only on invoke).
+- `SessionStart`'s only skill-relevant outputs are `additionalContext` (inject text) and `reloadSkills: true` (re-scan so **newly-written** skills appear — it can only **add**, never subtract). There is no field to hide or remove a skill.
+- `PreToolUse` fires on the `Skill` tool at **invocation**, not on what's advertised. `UserPromptExpansion` can block a `/skill` **when the user types it**, but doesn't remove it from the menu.
+- Hooks **cannot mutate settings at runtime** — settings are read from files at startup.
+
+So the <redacted> design **does not exist**.
+
+## Options that CAN achieve it
+
+| # | Mechanism | Hide strength | Cost / caveats |
+|---|---|---|---|
+| **A** | Pre-launch step writes per-builder `skillOverrides: "off"` into `.claude/settings.local.json` **before** `claude` starts | **HARD** (menu + model + Remote Control/SDK) | Must be written by the **launcher** (the wrapper/box bootstrap that already fetches rank), NOT the SessionStart hook. Per-builder file; subject to the workspace-trust dialog; does **not** cover plugin-namespaced skills (`/engineering:*` etc.). |
+| **B** | `Skill(name)` **deny** rules in settings | **HARD** on invocation (still shows in menu) | Belt-and-suspenders enforcement next to the server checks; same "written to a file, not by a live hook" constraint. |
+| **D** | `SessionStart` `additionalContext` — inject "you are rank X; don't use skills P, Q, R" | **SOFT** (advisory) | Zero new infra — rank already comes from the existing hook. Menu unchanged; the model *can* still invoke a listed skill. |
+| **E** | Per-skill self-check + bail (already in place) | menu unchanged, **effect gated** | This is what we do today; composes with server enforcement. |
+
+## Recommendation
+
+1. **Abandon the hook-filter premise** — it's not buildable. Record it here so we don't retry it.
+2. **Don't invest in the heavy launcher change (A) yet.** Because this is UX-only — the server (ADR 0016) and each skill's self-check already enforce rank — a hard menu hide is a *nicety*, not a fix. Mechanism A rewires the launch path, generates a per-builder `settings.local.json`, and still misses plugin skills, for a purely cosmetic gain.
+3. **If we want *some* declutter cheaply now,** ship mechanism **D**: extend the existing `session-start.js` hook to emit an `additionalContext` line naming the skills the builder's rank can't use ("these are visible but off-limits to your rank — don't reach for them"). It's a soft nudge, but it removes the dead-end surprise with zero new infra and no trust-dialog/plugin caveats.
+4. **Revisit A** only if menu clutter becomes a real, reported pain — then move the `skillOverrides` write into whatever launches `claude` (a launcher wrapper or the box bootstrap), driven by the live rank.
+
+Either way, the **server rank gate and the per-skill self-checks stay** — consistent with the trust-boundary rule that the DB enforces and markdown/settings only describe.
+
+## References
+
+- Claude Code docs: *Extend Claude with skills* (skill listing, `skillOverrides`, `Skill(...)` permissions), *Hooks* (`SessionStart` `additionalContext`/`reloadSkills`; no runtime settings mutation), *Configure permissions* (`Skill(name)` deny rules).
+- Local: `.claude/hooks/session-start.js` (where rank is fetched today), `.claude/settings.json` (hooks/permissions wiring).
+- [ADR 0016](<redacted>.md) — server-enforced permissions (the real gate this UX never replaces).

package/docs/adr/0132-cohost-fleet-control-plane-migration.md

@@ -0,0 +1,54 @@
+# ADR 0132 — Migrating the co-hosting fleet to the control plane over an SSH DB tunnel
+
+**Status:** Accepted — repo half implemented 2026-07-05 (task [#2071](https://example.com/builders#/task/2071)); **units ship additive + not-enabled — activation is a sequenced operator-op** (see §Activation). Extends [ADR 0130](<redacted>.md); completes the "zero cloud tokens on the co-hosting box" goal of [ADR 0126](<redacted>.md) (task 2065 / blocker 64).
+
+## Context
+
+[ADR 0130](<redacted>.md) shipped the *code* to run `provision.js` from the control plane and remote-exec box steps over SSH. But when we went to actually strip the tokens (blocker 64), the endgame proved **not a switch-flip**. Three findings:
+
+1. **The co-hosting box (`REDACTED_IP`) runs FIVE token-consuming timers, not one.** ADR 0130 addressed only `provision-intent-runner`. The other four are the whole `box.js` **dev-box lifecycle**: `box-intent-runner` (provision/wake, 1-min), `box-idle-suspend` (15-min), `box-drift-reconcile` (hourly), `box-dormant-reclaim` (daily). Each needs the DO token; none were migrated.
+2. **Every runner reads its work-queue from the *local* `example` Postgres, which is firewalled to localhost** (`pg_hba`: `host … 127.0.0.1/32 scram-sha-256`; `:5432` is closed to the network — the correct posture). A runner moved to the control plane cannot reach the `box_intents` / `provisioning_intents` queues remotely. This is the real obstacle ADR 0130 did not solve: it moved *box-step execution*, not *queue reading*.
+3. **`box.js` needs no code change** — its only shell-outs are `scripts/discord/post.js` and the `BOX_DNS_HOOK` (both present on the control plane with its tokens); everything else is DigitalOcean/Cloudflare HTTP. So the blocker is purely *"how does a control-plane runner reach the example queues."*
+
+At migration time the fleet was **dormant** — 0 live dev-box droplets, 0 hosted co-tenants, empty provisioning queue — so the cutover risk was low, but the dev-box capability is real (builders connect to dev boxes via Claude Desktop), so it must keep working. The owner chose the full migration over a token-strip-and-defer.
+
+## Decision
+
+Give the control plane a secure path into the co-hosting box's `example` Postgres via a **persistent SSH tunnel**, and run **all five runners on the control plane** as `cohost-*` unit variants that read the queues through the tunnel, call the DO/CF APIs with the control-plane tokens, and (for provisioning) remote-exec box steps over SSH per ADR 0130.
+
+### The tunnel
+
+`infra/cohost-db-tunnel.service` holds a long-lived `ssh -N -L 127.0.0.1:5433:127.0.0.1:5432 cohost` (Restart=always, ServerAlive keepalives). The runners set `DATABASE_URL=<redacted> (`pool.js` honors `DATABASE_URL` first), so they read/write the example queues through the encrypted forward. **No Postgres port is ever exposed to the network** — the tunnel terminates at the co-hosting box's own localhost.
+
+**Why a tunnel, not the alternatives.** (a) *Expose Postgres over DO private networking* — still opens a TCP surface + needs `pg_hba`/credential work, and the two droplets aren't guaranteed same-VPC. (b) *A token-signing broker on the co-hosting box* — leaves runners (and thus tokens' blast radius) on the co-hosting box, the opposite of the goal, and is far more code. (c) *Move the queue tables to the cloudbongos DB* — the OTB web tier enqueues them and can't reach the control-plane DB either (firewall symmetry); it splits the game's data. The tunnel keeps the data where it is, moves only execution, and reuses the SSH trust ADR 0130 already needs.
+
+### The DB credential
+
+`pg_hba` already permits `host … 127.0.0.1/32 scram-sha-256`, and the `lars` role had **no password**. Activation sets a scram password on the existing `lars` role (`ALTER ROLE lars WITH PASSWORD …`) and stores it only in the chmod-600 `/etc/cloudbongos/cohost-fleet.env` on the control plane. We reuse `lars` (not a new scoped role) deliberately: it is the **same role the runners already run as** on the co-hosting box (via peer auth), so privileges are identical and nothing can be under-granted. The password widens nothing — the role is reachable only from `127.0.0.1` (the tunnel endpoint), and SSH-as-`lars` is already full box access.
+
+### The units
+
+Eleven files in `infra/`: the tunnel + control-plane variants of all five runners (`cohost-box-intent-runner`, `cohost-box-idle-suspend`, `cohost-box-drift-reconcile`, `cohost-box-dormant-reclaim`, `cohost-provision-intent-runner`) with their timers. Each differs from the co-hosting original only in `WorkingDirectory=/home/lars/cloudbongos`, `EnvironmentFile=/etc/cloudbongos/{box.env,cohost-fleet.env}`, and (provision only) the ADR 0130 remote-exec env pointing `PROVISION_REMOTE_HOST=cohost`. **`cohost-provision-intent-runner` supersedes the confusingly-named `provision-intent-runner-cloudbongos.*` from task 2065** (same design, named for the fleet it drives, wired to the example DB via the tunnel; the old files are deleted). The pre-existing `cloudbongos-provision-intent-runner` (task 2056, local `cloudbongos` DB) is unrelated and stays.
+
+`deploy-cloudbongos.sh` self-heals these units **install-only** (copy + daemon-reload, never enable) so a redeploy/re-provision keeps them fresh without ever auto-activating (ADR 0129 durability, but activation stays manual).
+
+## Security posture
+
+A one-directional **control-plane → co-hosting SSH edge**: the token-holder commands the token-free box, never the reverse. The tunnel + the ADR 0130 remote-exec both ride the single `cohost` key (this box's key in the co-hosting box's `authorized_keys`, restrictable `from="REDACTED_IP"`). After activation + rotation the co-hosting box — the public-facing box that runs the live game — holds **zero account-wide cloud tokens**, which is the whole point (ADR 0126).
+
+## Activation (sequenced operator-op — do NOT reorder)
+
+1. **SSH trust.** On the control plane, generate `~lars/.ssh/cohost_ed25519` + a `cohost` `~/.ssh/config` alias; add its pubkey to `~lars/.ssh/authorized_keys` on the co-hosting box. Verify `sudo -u lars ssh cohost true` from the control plane.
+2. **DB password + fleet env.** `ALTER ROLE lars WITH PASSWORD …` on the co-hosting box; write `/etc/cloudbongos/cohost-fleet.env` (chmod 600) with `HOME=/home/lars` + `DATABASE_URL=…@127.0.0.1:5433/example`.
+3. **Tunnel up.** `systemctl enable --now cohost-db-tunnel`; verify `psql "$DATABASE_URL" -c 'select 1'` from the control plane.
+4. **Enable the 5 `cohost-*` runners** on the control plane AND **disable the 5 generic runners on the co-hosting box in the same window** — never both (double-drain). Run each `cohost-*` once to confirm a clean connect + drain.
+5. **Verify** end-to-end via `cohost-box-drift-reconcile` from the control plane (DB read via tunnel + DO API + DB write).
+6. **Bake with the tokens still in place** as the rollback net: any problem ⇒ re-enable the co-hosting timers (their tokens still work) and disable the control-plane ones.
+7. **Owner, after bake (irreversible, cloud-console — stays blocker 64):** remove `DO_API_TOKEN` + `CLOUDFLARE_API_TOKEN` from `/etc/example/box.env` and **rotate both** in the DigitalOcean + Cloudflare dashboards; then `dropdb cloudbongos` on the co-hosting box (the ADR 0126 rollback DB) once cloudbongos.com has baked healthy on its own droplet.
+
+## Consequences
+
+- The co-hosting box's provisioning/dev-box control moves off it entirely; after step 7 it is token-free.
+- One new always-on SSH connection (the tunnel) — negligible cost; auto-reconnects.
+- A runner tick that fires while the tunnel is momentarily down just fails its DB connect and retries next tick (1–2 min) — acceptable, no state corruption (`claimNextIntent` is `FOR UPDATE SKIP LOCKED`).
+- Rollback is a two-command switch (re-enable co-hosting timers, disable control-plane ones) as long as step 7 hasn't run — which is why the token strip/rotate is gated behind a bake.

package/docs/adr/0133-github-app-manifest-onboarding-signin.md

@@ -0,0 +1,42 @@
+# 0133 — One-click GitHub sign-in for onboarding via the GitHub App Manifest flow
+
+- **Status:** Accepted — built in task 2080.
+- **Date:** 2026-07-07
+- **Deciders:** example-owner (owner/Archon), Claude. Owner asked to automate the GitHub step after demo.cloudbongos.com hit `auth_not_configured`.
+- **Task:** [#2080](https://example.com/builders#/task/2080) · **Goal:** 35 (greenfield onboarding), criterion 165.
+
+## Context
+
+The last human friction in greenfield onboarding was wiring GitHub sign-in. The owner had to: open GitHub → Developer settings → **create an OAuth App by hand**, set homepage + callback, **generate a client secret**, copy it, and hand it to the box (`oauth-secret.js place`). It is the one step no prior automation removed because **GitHub has no API to create an OAuth App** — so it can't be scripted as-is. It surfaced concretely when demo.cloudbongos.com came up post-[#2078](https://example.com/builders#/task/2078) and reported `auth_configured:false`.
+
+## Decision
+
+Use GitHub's **App Manifest flow** — the only real automation path GitHub offers. Instead of a hand-built OAuth App, the owner registers a GitHub **App** from a **pre-filled manifest**: one click, approve on GitHub, and GitHub hands *us* the credentials. Sign-in works unchanged because a GitHub App's user-to-server token hits the same `GET /user` the OAuth-app flow used; GitHub simply ignores the extra `scope` param for Apps, and we only use the token once at sign-in to identify the user before minting our own `builder_session` (so the App token's expiry is irrelevant).
+
+**The flow spans the trust boundary ([ADR 0111](<redacted>.md) §2 / [ADR 0016](<redacted>.md)) — deliberately:**
+
+1. **Web tier** (the mothership hall, where the signed-in owner requested the instance) — `POST /api/bongos/provisioning/instances/:id/github-app` (own-scoped) mints a one-time `state` token, stores a `provisioning_oauth_manifests` row (status `pending`, TTL 30 min), and returns the pre-filled manifest + the GitHub form-POST target. The browser POSTs the manifest to GitHub.
+2. **GitHub** creates the App and redirects the owner's browser to the **mothership** callback `GET /api/bongos/provisioning/github-app/callback?code=&state=` (public — a browser redirect with no session; the unguessable single-use `state` is the authorization, exactly as GitHub's own conversion `code` is "the code IS the auth"). The callback stores the `code`, flips the row to `code_received`, and shows a "finishing setup" page.
+3. **Control-plane runner** (`provision.js`, the sole token-holder) drains `code_received` rows on its existing timer tick, exchanges the code via `POST https://api.github.com/app-manifests/{code}/conversions` for `client_id`/`client_secret`, writes them into `/etc/<slug>/web.env` (the `oauth-secret.js` placement it already used), restarts the unit, and verifies `/healthz` reports `auth_configured:true`.
+
+**The client secret never touches the browser, chat, or the web tier.** Only GitHub's short-lived, single-use `code` is web-tier-visible; the secret is fetched by the control plane and written straight to disk.
+
+### Why DB-backed state, not the in-memory OAuth-state cookie
+
+The web tier and the control-plane runner are **separate processes**. The existing web sign-in `state` lives in an apex cookie + memory because one process owns the whole round-trip. Here the callback (web) and the conversion (runner) are different processes, so the `state`/`code` lease is a DB row with `expires_at` (the `merge_lease` / `builder_sessions` pattern), not `deviceFlows`/`pairStore`.
+
+### Why conversion is control-plane-side, not web-side
+
+The conversion endpoint is unauthenticated (the code is the auth), so the web tier *could* call it — but the resulting secret must land in `/etc/<slug>/web.env` on the box, which is a control-plane privilege. Doing the exchange on the control plane keeps the secret out of the web tier and DB entirely: the web tier only ever holds the short-lived code.
+
+### Manifest shape
+
+`redirect_url` = the **mothership** callback (the instance can't do the exchange). `callback_urls` = the **instance's** own `/api/gds/auth/web/callback` (what `auth.js` actually builds) **and** the `/api/bongos/...` alias, so sign-in works regardless of which prefix a build emits. `default_permissions: {}` (sign-in needs none), `hook_attributes.active:false`, `public:false`. Personal vs org differs only in the POST URL (derived from the repo owner); the App works for sign-in either way.
+
+## Consequences
+
+- **Back-compat preserved.** An instance already on an OAuth App keeps working untouched — `loadGithubCreds()` reads the same `<PREFIX>_GITHUB_CLIENT_ID/SECRET`. The manifest path is the new *default* for fresh instances; nothing about `auth.js` changed.
+- **All three onboarding surfaces stay in lockstep** (the goal-35 rule): the hall "Start a project" wizard gets a one-click **Set up GitHub sign-in** button (primary); the `bongos onboard` CLI + the `/new-project` skill present it as recommended with the manual OAuth-app path kept as a documented fallback.
+- **Runner gating.** Conversion only runs once the instance is `active` (its unit exists), so a code that arrives mid-provision waits instead of failing; a dedicated droplet (web.env baked into cloud-init, no post-hoc exec path here) is refused with guidance and uses the manual path.
+- **Residual risk (accepted).** If a valid `pending` `state` leaked, an attacker could return their own App's code and wire the victim instance to their App. Mitigations: the state is 256-bit, minted only for the signed-in owner, single-use, 30-min TTL, never logged — the same posture as the existing OAuth-state cookie. A `code_received` row whose instance never goes active lingers (benign, visible); a TTL sweep for those is a later hardening.
+- **New module surface:** table `provisioning_oauth_manifests` (migration `provisioning_003`), two routes, and the runner's `convertManifestCode`/`placeManifestCreds`/`drainOAuthManifests`. The intent-action CHECK is widened to include `oauth-manifest` for a future intent-driven path, though today the runner drains by scanning the table on the same timer tick.

package/docs/adr/0134-private-first-npm-distribution.md

@@ -0,0 +1,38 @@
+# 0134 — Private-first npm distribution for the core + client (paid scoped, then public at launch)
+
+- **Status:** Accepted — publish path + private-by-default config built in task 2089; the real publish is a gated owner step.
+- **Date:** 2026-07-07
+- **Deciders:** example-owner (owner/Archon), Claude. Owner asked to have the npm/CLI onboarding commands ready but kept private pre-launch, choosing paid private npm over the free GitHub Packages option.
+- **Task:** [#2089](https://example.com/builders#/task/2089) · **Goal:** 35 (project-creation flow), criterion 165.
+- **Refines:** [#2025](https://example.com/builders#/task/2025) (the 2026-07-04 *public* unscoped `cloudbongos` decision — now the launch-time go-public step, not superseded) · **Builds on:** [ADR 0108](<redacted>.md) (core-as-npm-dep), [#2053](https://example.com/builders#/task/2053) (vendored-tarball install).
+
+## Context
+
+A new owner stands up a standalone instance that depends on `@cloudbongos/core` (ADR 0108), and external programs call the API through `@cloudbongos/client` (ADR 0118). Today neither is on a registry: `package-core.js` produces a real, installable `.tgz`, and provisioning **vendors that tarball** into each instance repo (a `file:` pin `npm ci` resolves — task 2053). That works, but the onboarding experience isn't the clean `npm install @cloudbongos/core` an owner expects, and the client's on-ramp doc referenced a nonexistent "internal registry."
+
+The owner wants the npm/CLI commands **ready and usable pre-launch, but not public** — Cloud Bongos shouldn't be installable by the general public before launch. Two prior decisions bear on this: the *public* install name was set to the unscoped **`cloudbongos`** (task 2025, deferred), and the `bongos` + ~10 defensive npm orgs were reserved under the owner's login.
+
+One npm rule forces the shape: **unscoped packages are always public — only *scoped* packages can be private, and only on a paid plan.** So the unscoped `cloudbongos` name *cannot* be the private form; the private artifact must stay scoped.
+
+## Decision
+
+Publish **`@cloudbongos/core`** and **`@cloudbongos/client`** as **scoped, private** npm packages during pre-launch, on a **paid** `cloudbongos` npm org. Both already use the `@cloudbongos` scope (an org the owner holds), so **no rename is needed now**.
+
+- **Private by default in code, not just by flag.** The synthesized core `package.json` (`buildPackageJson`) and the generated client `package.json` (`gen-api-client.js`) both carry `publishConfig: { access: "restricted" }`. `package-core.js --publish` additionally passes `--access restricted` on the CLI — belt-and-suspenders so a stray config edit can't silently make the pre-launch artifact public.
+- **The publish is a gated owner step; the tooling holds no token.** `package-core.js --publish` **dry-runs** by default; the real, permanent publish needs `--publish --live` plus the owner's `npm login` and the org on a paid plan. npm owns auth — this repo never stores a token.
+- **Consumers authenticate with an env-fed `.npmrc`:** `//registry.npmjs.org/:_authToken=<redacted> The token expands from the environment, so it never lands in a committed file. Only members of the paid org can install.
+- **The vendored-tarball path stays as the working default/fallback.** Rewiring provision/init to auto-pull the pinned core from the registry (env-fed token on the control plane) is a follow-up — it touches a proven, protected control-plane flow and isn't required for "commands ready + private." Publishing privately + documented auth already delivers a real `npm install`.
+- **Going public at launch is one step**, chosen then: either `npm access public @cloudbongos/core` (keeps the scoped name), or execute task 2025 to *also* publish the unscoped vanity `cloudbongos` for `npm install -g cloudbongos`. Task 2025 is therefore the launch-time go-public leg, not replaced by this.
+
+The daily command stays `bongos` regardless of package name (the `bin` mapping in the synthesized package.json is name-independent), so `npm install -g @cloudbongos/core` → `bongos init` works today, and the eventual public `cloudbongos` name changes nothing for users.
+
+## Why paid private npm over the free GitHub Packages alternative
+
+The owner chose it deliberately, knowing the trade-off. GitHub Packages is free but ties every consumer to a GitHub token + org membership and a non-default registry; npm private packages give the canonical `npm install` on the default registry with a clean one-flag flip to public — the same registry, name, and command the public launch will use. The recurring per-seat cost (~$7/member/month) is small at pre-launch scale (a handful of trusted early instances) and disappears at launch when the packages go public (public installs need no seat).
+
+## Consequences
+
+- Cost: a paid `cloudbongos` npm org seat per person who needs to install during pre-launch. Gone at launch.
+- Owner-only steps (out of the build session; capture as a blocker if they gate verification): put the org on a paid plan; generate an npm access token (automation — read-write to publish, read for CI/provision installs); run `package-core.js --publish --live` (permanent; login + 2FA).
+- Follow-up: wire provision/init to install the pinned core from the private registry (env-fed `NPM_TOKEN`), keeping the vendored tarball as fallback.
+- Full operator runbook — org, plan, token, publish, consumer `.npmrc`, and the go-public flip — is [`docs/recipes/private-npm-distribution.md`](../recipes/private-npm-distribution.md).