@bongos/core 1.19.576 → 1.19.577

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.576",
-  "core_contract": "1.19.576",
-  "source_commit": "a97463936d818b3a6be556837447748b3a2abaa1",
+  "core_version": "1.19.577",
+  "core_contract": "1.19.577",
+  "source_commit": "762e093b407c02f640fd7c4f28f35b4aba92b905",
   "source_ref": "HEAD",
-  "built_at": "2026-09-07T14:24:36.180Z",
+  "built_at": "2026-09-07T16:20:42.564Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 450,
+    "docs_redacted": 451,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2044,
+    "functional_verbatim": 2046,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2518,
-  "tree_sha256": "9b56f557f5e1d8d63c314cb2990df89c75d7230c3f16bdd41416396d95e2b6bd",
+  "file_count": 2521,
+  "tree_sha256": "681bcb585fd2e75cf4e37463230354417f0f352734aa5057de24da8cfb8d8712",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1804,10 +1804,15 @@
       "mode": "0000644",
       "sha256": "5ebfaa564a125f2c5bb0b391b8ff01914f147c15c9ef3f4caa91bafa8bd2e8ed"
     },
+    {
+      "path": "docs/adr/0258-the-public-cli-is-a-generated-client-package-not-the-published-core.md",
+      "mode": "0000644",
+      "sha256": "28f3644d3d9dcd2985b7e3f42cf2135af86203eee35b6e509d1ff98f630f1228"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "e9b47055a52c284035c201fae3f172215c746caabf938922821f4efcda2e8980"
+      "sha256": "30bb35e65ebd2dc8c5eb0aad7e30d5875d0c764265f398547abd545b62ee7d7c"
     },
     {
       "path": "docs/api-reference.md",
@@ -2682,7 +2687,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "dd40cd29025789ec5a9447aa44ec6c7d3bee6aaae183c65713a6a3ca8ed8275b"
+      "sha256": "f43e8946ecb5c96dc7af0bcee49010245df577eee62381701d2aef1c67455662"
     },
     {
       "path": "docs/handoff-template.md",
@@ -2692,7 +2697,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "8f122cc3f3ca35dcc6569b98bad34967f2a4bbf9ebcbc0e645ca2b1016245fbc"
+      "sha256": "39e12981a4c704b133c9afc6c10cdb225fbe2cc882e667916eed2785ce0ae5ef"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7552,12 +7557,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "8a58247d11bee28e30582d0860bd54cac15c8f3cb30753111063711a9369c390"
+      "sha256": "b2a595c7b297963949c8f0c4d662c56d6ce4334a8f9e92231f47f0cd9233d624"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "e2f634e2e1deae3517a6b545c91a2b4818c51b04cb56daa4f1528b822cc1d14e"
+      "sha256": "a2009a9bab221342b0b8b9c3c75a21d2ae02fb2fc281235f6fa7e17513a99ff8"
     },
     {
       "path": "public-docs/index.html",
@@ -7727,7 +7732,7 @@
     {
       "path": "scripts/gds/box-connect-lib.js",
       "mode": "0000644",
-      "sha256": "73172141b376910a6b6bc5a326e6bebae1fb8d0a80441e18c9f5f7acf689b67d"
+      "sha256": "56c6f3eae23d427d9c74763521739bae5b704bcd02ad234e43a5434645657519"
     },
     {
       "path": "scripts/gds/box-infra.js",
@@ -7754,6 +7759,11 @@
       "mode": "0000644",
       "sha256": "6a696f9291da2d071d8a8aa0f92bf0be08445569a73196f9204f696bf6cb6cb5"
     },
+    {
+      "path": "scripts/gds/build-cli-package.js",
+      "mode": "0000644",
+      "sha256": "4b2428615e3c81c14a3b3144eca35fcb2c4523c4debef0f7d4596e5934857a6b"
+    },
     {
       "path": "scripts/gds/bump-version.js",
       "mode": "0000644",
@@ -9257,7 +9267,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "fb020c72dfb07b789b7e281ba766fe8f0f9c4fe67c359c8b5c9928c8e86b85da"
+      "sha256": "a06af2e38ee9044c10f14f0ce1392ab85adb8058421222bf894f0f7ed6d77326"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9839,6 +9849,11 @@
       "mode": "0000644",
       "sha256": "d0ea5b273c24527190f6ed01555ddb6b022a6ea94f3efcc7bdbd17f834c7d2ad"
     },
+    {
+      "path": "tests/cli_package.mjs",
+      "mode": "0000644",
+      "sha256": "a57516ed9e904cf1c86fe99688415f834dcae1a19f01b22e986f199fa5473258"
+    },
     {
       "path": "tests/cli_token_reissue.mjs",
       "mode": "0000644",

package/docs/adr/0258-the-public-cli-is-a-generated-client-package-not-the-published-core.md

@@ -0,0 +1,140 @@
+# ADR 0258 — The public CLI is a generated client-only package, and its file list is proven by running it
+
+- **Status:** accepted
+- **Date:** 2026-09-07
+- **Task:** [task 1003679](https://cloudbongos.com/builders#/task/1003679) (BONGOS-V1, goal 1000054 — *A newcomer can build without the UI*)
+- **Deciders:** Claude, under the Archon's standing scope
+- **Related:** [ADR 0083](<redacted>.md) (a module may import only `src/module-api.js` — the reason a static closure cannot answer this question) · [ADR 0099](<redacted>.md) (the lagged, redacted public mirror — still dormant) · [ADR 0108](<redacted>.md) (the core ships as a private versioned dependency) · [ADR 0118](<redacted>.md) (the generated client this package vendors) · [ADR 0161](<redacted>.md) (why the core's version moves many times a day)
+
+---
+
+## Context
+
+The core ships as `@bongos/core`, which is **private**. That is deliberate (ADR 0108), and it
+has an unintended consequence at the front door: a newcomer with no credential can install
+nothing. There is no terminal path into an instance at all, so the web hall is the only way in.
+
+The owner put it plainly: *"how am I supposed to easily take on tasks as a new builder? I should
+be able to do everything without the UI."*
+
+An open task, 1002025, proposed the obvious fix — publish the core to npm. That is the wrong
+instrument on two counts. It publishes the **server**: routes, auth middleware, pool, migrations,
+provisioning. And it bypasses ADR 0099's redaction pipeline, which is the mechanism that is
+supposed to decide what leaves this repo and does not run until ~2026-11. The premise was also
+stale (it named `@cloudbongos/core`; the package is `@bongos/core`).
+
+Two refactors landed the night before this decision and are what make a narrower answer possible:
+[task 1003676](https://cloudbongos.com/builders#/task/1003676) cut the one edge that dragged the
+server into the CLI, and [task 1003677](https://cloudbongos.com/builders#/task/1003677) made
+`src/module-api.js` resolve its kernel capabilities on read rather than on import.
+
+## Decision
+
+**Generate a separate, public, client-only package — `@cloudbongos/cli` — from the core, and do
+not publish the core.** `scripts/gds/build-cli-package.js` emits it; `tests/cli_package.mjs`
+proves it.
+
+Four parts of this are load-bearing.
+
+### 1. The name is scoped because the org already exists
+
+The owner holds the npm org `cloudbongos`. On npm, org names and unscoped package names share one
+namespace, so the bare name `cloudbongos` is **not publishable precisely because that org
+exists** — npm reports it as invalid, which reads like the name is taken when in fact the owner
+owns it. A public scoped package is free and `npx @cloudbongos/cli` is not a worse experience
+than `npx cloudbongos`. (Registry checked 2026-09-07: `cloudbongos`, `@cloudbongos/cli` and
+`@cloudbongos/core` all 404, search total 0.)
+
+Related and worth writing down because it wasted the owner's time: **a package name cannot be
+created or reserved on the npm website.** The name comes into existence on first `npm publish`.
+Every field on the org settings pages operates on packages that already exist, which is why
+"Add Existing Package" answered `Forbidden` for a package nobody had published.
+
+### 2. The file list is DECLARED, and proven by behaviour — not computed
+
+The tempting approach is to derive the package from a static require-closure of the CLI entry
+points. **That instrument does not work here, and cannot be made to.** `src/module-api.js` is the
+published module doorway (ADR 0083): a module may import *only* it, so any script that touches a
+module file statically reaches the doorway, and the doorway by design *names* every kernel
+capability. A static walk therefore sees the whole server — 33 `src/` files from
+`scripts/gds/start.js` alone — even though every one of those names is behind a lazy getter that
+never resolves. Measured at runtime the same set is **one** `src/bongos/` file
+(`api-prefix.js`, which imports nothing).
+
+This is the same trap as task 1003677's original done-when ("zero `src/bongos` in the
+require-closure"), which was unsatisfiable for exactly this reason: a getter still *contains* the
+require text.
+
+So `FILES` in the build script is an explicit, grouped, auditable list, and the test packs the
+tarball, installs it into an empty directory **with no repo present**, and runs every advertised
+verb. A verb may fail for want of a session or a network; it may not fail because a file is
+missing. That test is the only thing that can prove the list complete, and it earned its keep
+immediately — the first build shipped without `clients/bongos-client/index.mjs`, which
+`cli-lib.js` reaches by a dynamic `import()` that no `require()`-based reasoning would ever see.
+The build now refuses any relative `import()` target the manifest omits, and the generated
+`package.json` `files` array is derived from the manifest rather than hand-listed (the hand-listed
+one had already dropped `clients/`, producing a tarball that installed cleanly and died on first
+use).
+
+### 3. `claim` and `ship` are absent, and the CLI says why
+
+Writing code needs a real checkout and a worktree, so `claim`, `ship`, `dev`, `serve`, `module`,
+`upgrade`, `onboard`, `doctor`, `exec` and `package-core` are not in the public CLI. A newcomer
+who types one gets the reason and the next step — `bongos shell` opens a terminal on a cloud dev
+box that already has the full CLI — rather than `unknown command`. A bare unknown-command error
+teaches nothing, which is the precise failure this whole task exists to fix, so it would be
+perverse to reintroduce it at the boundary.
+
+The journey the package supports end to end is: `bongos login <instance>` → `bongos start` →
+`bongos shell`. Steps one and two are what had no terminal path at all.
+
+`onboard` is excluded for a second reason: it drags ten provisioning files that talk to
+DigitalOcean and GitHub. It is owner tooling, and it is the widest redaction surface in the
+candidate set.
+
+### 4. A redaction gate runs on every build, and it fails closed
+
+The package is public, so the build scans the emitted tree and **refuses to emit** on a hit:
+non-loopback IPv4 (RFC 5737 documentation ranges and link-local exempted — those can never name
+real infrastructure, so they are the correct thing to write in an example), GitHub/npm token
+shapes, private-key blocks, AWS keys, plus every domain and owner login it can read out of the
+instance's own `config/branding.json`.
+
+The needles come from host config rather than a list in the core, so the core carries no instance
+identity (the ADR 0062 §7 split). A neutral core has no `config/branding.json`, so that half is
+inert there — which is correct: the gate exists to stop someone building this package from an
+*instance* checkout. `cloudbongos.com` is allowlisted as public by design, the way
+`registry.npmjs.org` is baked into npm.
+
+The generated `package.json` carries **no `repository` field**: the core repo is private, so a
+repository URL would 404 for every user *and* put the owner's login into a public artifact for no
+benefit. It gains one when ADR 0099's mirror lands.
+
+## Consequences
+
+- 31 files, ~450 KB, 13 verbs, **one** runtime dependency (`undici`). Small enough to audit by
+  reading, which was the point.
+- The package's version is independent of the core's. The core moves many times a day under
+  ADR 0161; a public CLI's contract should not.
+- The generated tree is gitignored (`dist/`). It is rebuilt, never committed.
+- **Publishing is the owner's action, not a builder's.** It is the owner's npm account, and a
+  public package name cannot be un-taken. The build stops at a packed tarball and hands over one
+  `npm publish --access public`.
+- `@bongos/client` stays private and is **vendored** as a single file rather than declared as a
+  dependency — a public package that depended on a private one would be uninstallable for
+  everyone.
+- Task 1002025 is superseded and should be closed against this ADR rather than done.
+
+## Rejected
+
+- **Publishing the core** (task 1002025 as written) — ships the server and bypasses ADR 0099.
+- **Deriving the package from a static require-closure** — structurally impossible past the
+  module doorway; see §2.
+- **Waiting for the ADR 0099 mirror** — it is dormant until ~2026-11 and the front door is broken
+  now. The two are independent: this package is a build product, not a source release.
+- **An unscoped `cloudbongos` package** — unpublishable while the owner's org of that name exists.
+- **Depending on `@bongos/client`** — private, so the public package would not install.
+- **Including `claim`/`ship` in a degraded form** — a half-working claim that cannot materialize
+  into a checkout is worse than one that explains where to go.
+- **Shipping all of `src/`** to make lazy getters safe — reintroduces the server surface and the
+  redaction problem the narrow list exists to avoid.

package/docs/adr/README.md

@@ -349,3 +349,4 @@ This keeps the decision history honest and traceable.
 
 > ⚠️ **Numbering collisions are now machine-enforced, not narrated.** Twenty numbers are shared by two ADRs each — assigned in parallel sessions before anything checked. The files keep their filenames (renumbering would break every existing citation, and a number once assigned is never reused), and this table disambiguates each pair as `NNNN-a` / `NNNN-b`. The authoritative list is `LEGACY_DUPLICATE_ADRS` in [`scripts/gds/adr-namespace.js`](../../scripts/gds/adr-namespace.js), frozen by exact filename: a **new** collision — or a third file joining a legacy number, or a rename of either half — hard-fails the `unit` CI gate, as does an index row that points at no file or an ADR with no row. The list may only shrink. This paragraph used to narrate the collisions one by one and had fallen eight behind reality; see [ADR 0195](<redacted>.md) for why the check exists and why the pairs are grandfathered rather than renumbered.
 | 0257 | [**Auth resolves before the hall mounts anything, and a widget's boot read may never navigate** ([task 1003673](https://cloudbongos.com/builders#/task/1003673) · goal 1000063 — *The front door*). An invite-only instance could not admit its FIRST builder, and the symptom lied about where the fault was: an owner saw an empty Access-requests queue and no approve button, because **signing in does not file a request** — only the landing's *Request access* form does, and that form was unreachable. A signed-out visitor to `/builders` was bounced to GitHub, refused as a first-timer ("request access first"), and pointed back at `/builders` to be bounced again. Reproduced against `main`, not just an old pin. `builders.js` was already careful — `/me` is read `softAuth` and a 401 there renders the landing — but `DOMContentLoaded` called `mountHallWidgets()` FIRST, synchronously, and `goals.js`'s mount-time read of `/goals` goes through a `getJSON` with no `softAuth`, which answers 401 by NAVIGATING. The widget's read raced `renderLanding()` and won. **Decision: the front door settles which page this is before anything else runs** — `boot()` reads `/me` (soft), then either renders the landing and stops (nothing mounts, nothing else fetches) or mounts the hall, handing the resolved payload to `loadAll()` so the page still asks once. Widgets are member surfaces (`renderLanding` hid them all after the fact anyway), so not mounting them while signed out removes the CLASS rather than the one instance of it that was found; **a widget's own boot read may never navigate** is the belt beside it (`goals.js` reads soft and renders nothing without a session). A 401 during boot is not an instruction to go and sign in — only a user action is. `tests/hall_landing_boot.mjs` executes the real `builders.js` in a DOM stub and was confirmed to FAIL against the pre-fix file. Rejected: patching `goals.js` alone (it was merely first); making the 401 redirect soft everywhere (an expired session mid-visit SHOULD be sent to sign in — the line is boot vs user action); open enrollment as the cure (removes the gate [ADR 0050](<redacted>.md) chose deliberately instead of repairing the door).](<redacted>.md) | hall-ui / admission / front door |
+| 0258 | [**The public CLI is a generated client-only package, and its file list is proven by running it** ([task 1003679](https://cloudbongos.com/builders#/task/1003679) · goal 1000054 — *A newcomer can build without the UI*). The core ships private as `@bongos/core` ([ADR 0108](<redacted>.md)), so a newcomer with no credential can install NOTHING and the web hall is the only way in — the owner's words: "how am I supposed to easily take on tasks as a new builder? I should be able to do everything without the UI." Open task 1002025 proposed publishing the core, which ships the SERVER and bypasses [ADR 0099](<redacted>.md)'s redaction pipeline (dormant until ~2026-11). **Decision: generate a separate public `@cloudbongos/cli` from the core and do not publish the core.** Four load-bearing parts. (1) SCOPED NAME, because npm shares one namespace between org names and unscoped packages — the bare `cloudbongos` is unpublishable *precisely because the owner owns that org*, which npm reports as "invalid" and reads like the name is taken; and a package name cannot be created on the npm website at all (it exists on first publish, which is why "Add Existing Package" answered `Forbidden`). (2) THE FILE LIST IS DECLARED AND PROVEN BY BEHAVIOUR, never computed — a static require-closure CANNOT answer this, because `src/module-api.js` is the doorway a module may only import ([ADR 0083](<redacted>.md)) and it *names* every kernel capability, so a static walk sees 33 `src/` files from `start.js` alone where runtime resolves **one** (`api-prefix.js`, which imports nothing) — the same trap as task 1003677's unsatisfiable done-when. So the test packs the tarball, installs it into an empty dir with NO repo, and runs every verb: it may fail for want of a session, never for a missing file. That caught two real holes on its first strengthened run — `clients/bongos-client/index.mjs`, reached by a dynamic `import()` no `require()` walk can see, and a hand-listed `files` array that dropped `clients/` and produced a tarball which installed cleanly then died on first use; both are now build-time refusals, and the `files` array is derived from the manifest. (3) `claim`/`ship`/`dev`/`serve`/`module`/`upgrade`/`onboard`/`doctor`/`exec`/`package-core` are ABSENT and the CLI says WHY plus the next step (`bongos shell` → a cloud box with the full CLI) — a bare `unknown command` teaches nothing, which is the exact failure being fixed. The supported journey is `login` → `start` → `shell`. (4) A REDACTION GATE fails the build closed on non-loopback IPv4 (RFC 5737 doc ranges exempt), token/key shapes, and every domain + owner login readable from the instance's own `config/branding.json` — needles come from host config so the core carries no instance identity ([ADR 0062 §7](<redacted>.md)); `cloudbongos.com` is allowlisted as public by design. No `repository` field while the core repo is private (it would 404 for every user and publish the owner's login for nothing). 31 files, one dependency (`undici`), version independent of the core's ([ADR 0161](<redacted>.md)). `@bongos/client` is VENDORED, not depended on — a public package depending on a private one is uninstallable. **The owner runs `npm publish`; a builder must not.** Task 1002025 is superseded. Rejected: publishing the core; deriving from a static closure (structurally impossible past the doorway); waiting for the mirror (dormant, and this is a build product not a source release); an unscoped name; depending on `@bongos/client`; a degraded `claim`; shipping all of `src/` to make lazy getters safe.](<redacted>.md) | cli / distribution / public surface |

package/docs/file-map.md

@@ -167,6 +167,7 @@
 │       ├── ship.js              ← resolve claim as shipped, award credits (`/builder-ship`); also uploads a secret-scrubbed session digest to the corpus (6D.1, ADR 0027); on a dev box runs the sandbox-first review gate before resolving (#927, ADR 0046)
 │       ├── ship-visual.js       ← the OPTIONAL `--visual <image> [--visual-alt "…"]` leg of a ship (task 1003109): screens the file BEFORE the claim resolves (bad input costs no claim), uploads it AFTER (a failed picture never fails a ship)
 │       ├── package-core.js      ← package the core as a versioned, installable artifact + pin manifest (`bongos package-core`; R84, ADR 0100 §1, [#1688](https://example.com/builders#/task/1688)): isPublishable() selection + mirror redaction + fail-closed no-leak gate → dist/bongos-core-<version>.{tgz,manifest.json}; version = src/module-api CORE_VERSION. Recipe: docs/recipes/packaging-the-core.md
+│       ├── build-cli-package.js ← generate the PUBLIC, client-only `@cloudbongos/cli` npm package from this repo (task 1003679, ADR 0258): declared FILES manifest (no server/routes/auth/pool/provisioning) + generated dispatcher, README and package.json whose `files` array is DERIVED from the manifest; refuses to emit on a relative `import()` the manifest omits, and on a redaction hit (non-loopback IPv4, token/key shapes, instance domains + owner login read from config/branding.json). Sibling of package-core.js, opposite audience: that one packages the private core for an instance, this one packages the client surface for the public. Proven by tests/cli_package.mjs, which installs the packed tarball into an empty dir and runs every verb. `npm publish` is the OWNER's step, never a builder's → dist/cloudbongos-cli/
 │       ├── sandbox-stage.js     ← stage the working tree on the live game preview (box OR local) for browser review before ship; resolvePreviewContext picks the context (`/builder-stage`; #927, ADR 0046; local: task 1056)
 │       ├── local-preview.js     ← builder CLI for the LOCAL sandbox: start/stop/status/restart/logs/url of the game-only preview at http://localhost:3100 (`npm run preview`; task 1056)
 │       ├── local-preview-lib.js ← core of the local sandbox launcher (detached `node src/preview-server.js`, pid/health/port mgmt); shared by local-preview.js + sandbox-stage.js (task 1056)

package/docs/module-api-changelog.md

@@ -1601,5 +1601,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.574 with no explicit bump. run 34076465465. (task 1002620)
   1.19.576 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.575 with no explicit bump. run 34132732488. (task 1002620)
+  1.19.577 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.576 with no explicit bump. run 34142767912. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.576",
+  "version": "1.19.577",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.576",
+      "version": "1.19.577",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.576",
+  "version": "1.19.577",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/box-connect-lib.js

@@ -124,7 +124,7 @@ function knownHostsLineNamesAny(line, names) {
 // line for the same box.
 //
 // It used to compare field 1 to the hostname with `!==`, which missed the two forms
-// OpenSSH actually writes — `host,1.2.3.4` (what `StrictHostKeyChecking=accept-new`
+// OpenSSH actually writes — `host,192.0.2.4` (what `StrictHostKeyChecking=accept-new`
 // records) and the hashed `|1|salt|hash`. Those lines survived the "replace", so
 // every re-pin ACCUMULATED another entry and the client kept verifying against the
 // first, now-wrong one: "Host denied (verification failed)" on a box that had just

package/scripts/gds/build-cli-package.js

@@ -0,0 +1,517 @@
+#!/usr/bin/env node
+// scripts/gds/build-cli-package.js — generate the public, client-only `@cloudbongos/cli`
+// npm package from this repo (task 1003679, goal 1000054).
+//
+// WHY THIS EXISTS
+// The core ships as `@bongos/core`, which is PRIVATE. That makes the front door unusable for
+// anyone without a credential: a newcomer cannot install anything, so "take on a task" has no
+// terminal path at all and the web hall is the only way in. This script cuts the CLI *surface*
+// out of the core and emits a small, public, server-free package, so `npx @cloudbongos/cli
+// login <instance>` works from a bare laptop.
+//
+// WHAT IT IS NOT
+// It does NOT publish the core. No server, no routes, no auth middleware, no pool/db, no
+// provisioning. Publishing the core would bypass the ADR 0099 redaction pipeline; this package
+// carries a file list narrow enough to actually audit, and REDACTION_PATTERNS below fails the
+// build if instance identity leaks into it.
+//
+// WHY THE FILE LIST IS DECLARED, NOT COMPUTED
+// A static require-closure is unusable here. `src/module-api.js` is the published module doorway
+// (ADR 0083) and by design *names* every kernel capability, so any static walk that reaches a
+// module file appears to reach the whole server — even though the getters are lazy and never
+// resolve. The honest instrument is behaviour: FILES is declared, and tests/cli_package.mjs packs
+// the tarball, installs it into an empty directory with no repo present, and RUNS every verb.
+// If a real code path needs a file that isn't here, that test fails with MODULE_NOT_FOUND.
+//
+// Usage:
+//   node scripts/gds/build-cli-package.js [--out dist/cloudbongos-cli] [--version 0.1.0] [--quiet]
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.join(__dirname, '..', '..');
+
+// The package's OWN version — deliberately independent of the core's. The core moves many times
+// a day (CI auto-patch, ADR 0161); the CLI's public contract should not.
+const PACKAGE_VERSION = '0.1.0';
+const PACKAGE_NAME = '@cloudbongos/cli';
+
+// ── What the package carries ────────────────────────────────────────────────────────────────
+// Every entry is repo-relative and copied verbatim. Grouped by why it's here, because the
+// grouping is the audit: anything that doesn't fit a group below does not belong in a public
+// client package.
+const FILES = [
+  // The shared CLI plumbing every verb goes through: session file, HTTP, error shapes.
+  'scripts/gds/cli-lib.js',
+  'scripts/gds/api.js',
+
+  // Account + sign-in. login.js is the whole point — GitHub device flow, no paste, no credential.
+  'scripts/gds/login.js',
+  'scripts/gds/reauth.js',
+  'scripts/gds/setup.js',
+  'scripts/gds/onboarding-config.js', // lazy dep of setup.js
+  'scripts/gds/install-git-hooks.js', // lazy dep of setup.js
+  'scripts/gds/preflight.js',
+
+  // Read the board and move your own work along.
+  'scripts/gds/start.js',
+  'scripts/gds/context-pack.js', // start.js renders through this
+  'scripts/gds/status.js',
+  'scripts/gds/task.js',
+  'scripts/gds/recall.js',
+  'scripts/gds/cost.js',
+  'scripts/gds/release.js',
+
+  // Get onto a real environment without installing one: the cloud dev box.
+  'scripts/gds/shell.js',
+  'scripts/gds/code.js',
+  'scripts/gds/box-connect-lib.js',
+
+  // Module files the above touch. Each imports nothing from the kernel at load time.
+  'modules/lifecycle/task-classifier.js',
+  'modules/lifecycle/task-visuals.js',
+  'modules/economy/reward-policy.js',
+
+  // The only core files in the package: config/branding readers and one constant table.
+  // src/module-api.js is here because task-classifier.js reads branding through the doorway
+  // (ADR 0083 forbids a module importing src/branding directly). Its `branding` getter resolves
+  // against src/branding.js, which ships; the other getters point at server files that do not,
+  // and no client path touches them — the smoke test is what proves that.
+  'src/branding.js',
+  'src/instance-config.js',
+  'src/module-seams.js',
+  'src/module-api.js',
+  'src/bongos/api-prefix.js',
+
+  // The generated typed API client (ADR 0118), which cli-lib.js reaches by a dynamic
+  // `import()` of this exact path. Vendored as a single file rather than depended on: it is
+  // published as `@bongos/client`, which is PRIVATE, so a public package that declared it as a
+  // dependency would be uninstallable for everyone. index.mjs is self-contained and imports
+  // nothing; the sibling package.json is deliberately NOT shipped (it carries
+  // publishConfig.access=restricted and a nested manifest only confuses packing).
+  'clients/bongos-client/index.mjs',
+
+  // Neutral branding defaults, so the CLI has sane strings with no instance checkout present.
+  'config/branding.neutral.json',
+];
+
+// Paths that must NEVER appear in the generated tree, whatever FILES says. A belt-and-braces
+// assertion against a future edit quietly widening the package back into the server.
+const FORBIDDEN_PREFIXES = [
+  'src/bongos/routes/',
+  'src/server',
+  'migrations/',
+  'infra/',
+  'public/',
+  'modules/hall-ui/',
+  '.github/',
+  'devbox-app/',
+];
+const FORBIDDEN_BASENAMES = [
+  'pool.js', 'auth.js', 'db.js', 'server.js', 'serve-internal.js',
+  'logger.js', 'project-door.js', 'project-settings.js',
+];
+// src/bongos/ is the kernel. Exactly one file from it is allowed, and it imports nothing.
+const ALLOWED_SRC_BONGOS = new Set(['src/bongos/api-prefix.js']);
+
+// ── The verbs the package advertises ────────────────────────────────────────────────────────
+// `script` is resolved inside the package. Keep in lockstep with FILES.
+const VERBS = {
+  login:   { script: 'login.js',   group: 'account', summary: 'Sign in to an instance  (bongos login <url> — browser click, no paste)' },
+  reauth:  { script: 'reauth.js',  group: 'account', summary: 'Refresh your session' },
+  setup:   { script: 'setup.js',   group: 'account', summary: 'Finish builder setup on this instance (disciplines, consent)' },
+  box:     { script: 'api.js', prefixArgs: ['POST', '/api/gds/box/ensure'], group: 'account', summary: 'Turn on / wake your cloud dev box' },
+  shell:   { script: 'shell.js',   group: 'account', summary: 'Open a terminal on your dev box' },
+  code:    { script: 'code.js',    group: 'account', summary: 'Open VS Code on your dev box over Remote-SSH' },
+
+  start:   { script: 'start.js',   group: 'work', summary: 'List tasks you can claim right now' },
+  status:  { script: 'status.js',  group: 'work', summary: 'Version / criterion progress  (bongos status C8)', selfHelp: true },
+  task:    { script: 'task.js',    group: 'work', summary: 'Create or show a task', selfHelp: true },
+  recall:  { script: 'recall.js',  group: 'work', summary: 'Search the docs + project knowledge  (bongos recall "x")' },
+  cost:    { script: 'cost.js',    group: 'work', summary: 'Log a cost entry' },
+  release: { script: 'release.js', group: 'work', summary: 'Cancel a claim — task returns to ready' },
+
+  api:     { script: 'api.js',     group: 'work', summary: 'Call any instance endpoint  (bongos api GET /api/gds/me)' },
+};
+
+// Verbs that exist in the full core CLI and are deliberately absent here. The dispatcher prints
+// the reason and the actual next step, because a newcomer hitting a bare "unknown command" learns
+// nothing — that silence is the exact failure this whole task is fixing.
+const CHECKOUT_ONLY = {
+  claim:   'Claiming a task writes code, so it needs a real checkout and a worktree.',
+  ship:    'Shipping grades, merges and deploys from a real checkout.',
+  dev:     'Runs an instance locally — needs the instance repo.',
+  serve:   'Runs an instance on a host — needs the instance repo.',
+  module:  'Scaffolds a module into an instance repo.',
+  upgrade: 'Moves an instance to a new core version.',
+  onboard: 'Provisions new infrastructure — owner tooling, not in the public CLI.',
+  doctor:  'Checks a local checkout toolchain.',
+  exec:    'Runs a core script from inside the core package.',
+  'package-core': 'Packages the core — owner tooling.',
+};
+
+// ── Redaction gate ──────────────────────────────────────────────────────────────────────────
+// Generic shapes only. Instance-specific needles are discovered at build time from the host's
+// own config (below) so the core itself carries no instance identity — the ADR 0062 §7 split.
+const REDACTION_PATTERNS = [
+  { name: 'non-loopback IPv4', re: /\b(?!127\.|0\.0\.0\.0|255\.)(?:\d{1,3}\.){3}\d{1,3}\b/g },
+  { name: 'github token', re: /\bgh[pousr]_[A-Za-z0-9]{16,}/g },
+  { name: 'github fine-grained token', re: /\bgithub_pat_[A-Za-z0-9_]{20,}/g },
+  { name: 'npm token', re: /\bnpm_[A-Za-z0-9]{30,}/g },
+  { name: 'private key block', re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/g },
+  { name: 'aws access key', re: /\bAKIA[0-9A-Z]{16}\b/g },
+];
+
+// Version strings (1.19.576) and dotted identifiers look like IPv4 to a loose regex; a real
+// address has four all-numeric octets each <= 255 and is not a semver.
+//
+// The documentation ranges (RFC 5737) and link-local are exempt: they can never name real
+// infrastructure, so they are the CORRECT thing to write in an example. Nothing else is
+// exempt — private ranges included, because an internal address still leaks topology and
+// deserves a human look before it goes public.
+const DOC_IPV4 = [/^192\.0\.2\./, /^198\.51\.100\./, /^203\.0\.113\./, /^169\.254\./];
+
+function isRealIPv4(s) {
+  const parts = s.split('.');
+  if (parts.length !== 4) return false;
+  if (!parts.every((p) => /^\d{1,3}$/.test(p) && Number(p) <= 255)) return false;
+  return !DOC_IPV4.some((re) => re.test(s));
+}
+
+// The project's own public identity. `cloudbongos.com` is the flagship instance and the CLI's
+// documented default — the way `registry.npmjs.org` is baked into npm — so it is published on
+// purpose and must not trip the gate. Anything NOT on this list that comes out of an instance's
+// branding is treated as private identity and blocks the build.
+const PUBLIC_BY_DESIGN = new Set(['cloudbongos.com']);
+
+// Instance identity to refuse: the host's own domains and owner login, read from the instance's
+// committed branding if this checkout has one. Absent (a neutral core), the gate still runs the
+// generic patterns above.
+function instanceNeedles() {
+  const needles = new Set();
+  const add = (v) => {
+    if (typeof v !== 'string') return;
+    const s = v.trim().toLowerCase();
+    if (s.length > 3 && !PUBLIC_BY_DESIGN.has(s)) needles.add(s);
+  };
+  try {
+    const b = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'config', 'branding.json'), 'utf8'));
+    for (const v of Object.values(b.domains || {})) add(String(v).replace(/^https?:\/\//, '').replace(/\/.*$/, ''));
+    add(b.identity && b.identity.ownerLogin);
+    add(b.repo && b.repo.owner);
+  } catch (_) { /* neutral core: no instance branding, nothing to redact */ }
+  for (const extra of String(process.env.CLI_PACKAGE_FORBIDDEN || '').split(',')) add(extra);
+  return [...needles];
+}
+
+function scanRedaction(outDir, files) {
+  const needles = instanceNeedles();
+  const hits = [];
+  for (const rel of files) {
+    const abs = path.join(outDir, rel);
+    let text;
+    try { text = fs.readFileSync(abs, 'utf8'); } catch { continue; }
+    for (const { name, re } of REDACTION_PATTERNS) {
+      for (const m of text.matchAll(re)) {
+        if (name === 'non-loopback IPv4' && !isRealIPv4(m[0])) continue;
+        const line = text.slice(0, m.index).split('\n').length;
+        hits.push(`${rel}:${line}  ${name}: ${m[0]}`);
+      }
+    }
+    const lower = text.toLowerCase();
+    for (const n of needles) {
+      let i = lower.indexOf(n);
+      while (i !== -1) {
+        hits.push(`${rel}:${text.slice(0, i).split('\n').length}  instance identity: ${n}`);
+        i = lower.indexOf(n, i + n.length);
+      }
+    }
+  }
+  return hits;
+}
+
+// ── Generated files ─────────────────────────────────────────────────────────────────────────
+
+function dispatcherSource() {
+  const verbs = JSON.stringify(VERBS, null, 2).replace(/\n/g, '\n');
+  const checkout = JSON.stringify(CHECKOUT_ONLY, null, 2).replace(/\n/g, '\n');
+  return `#!/usr/bin/env node
+// bin/bongos.js — the public Cloud Bongos CLI.
+//
+// GENERATED by scripts/gds/build-cli-package.js in the Cloud Bongos core. Do not edit by hand:
+// edit the generator and rebuild.
+//
+// A thin dispatcher over the client scripts in this package. It spawns each with process.execPath
+// and forwards argv + the exit code; no auth or API logic lives here (that is cli-lib.js).
+
+'use strict';
+
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const PKG_ROOT = path.join(__dirname, '..');
+const SCRIPTS_DIR = path.join(PKG_ROOT, 'scripts', 'gds');
+const VERSION = require('../package.json').version;
+
+const VERBS = ${verbs};
+
+const CHECKOUT_ONLY = ${checkout};
+
+const GROUPS = [['account', 'Account & environment'], ['work', 'Work']];
+
+function helpText() {
+  const lines = ['bongos — the Cloud Bongos CLI', '', 'Usage:  bongos <command> [args]'];
+  lines.push('', 'First time here?');
+  lines.push('  bongos login https://your-instance.com    sign in with a browser click');
+  lines.push('  bongos start                              see what you can pick up');
+  for (const [key, label] of GROUPS) {
+    lines.push('', label + ':');
+    for (const [verb, def] of Object.entries(VERBS)) {
+      if (def.group !== key) continue;
+      lines.push('  ' + verb.padEnd(10) + ' ' + def.summary);
+    }
+  }
+  lines.push('', '  help        Show this help', '  version     Show the bongos version');
+  lines.push('');
+  lines.push('Writing code (claim, ship) happens in a checkout. \`bongos shell\` opens one');
+  lines.push('on a cloud dev box with nothing to install locally.');
+  return lines.join('\\n');
+}
+
+function verbHelpText(verb, def) {
+  return [
+    'bongos ' + verb + ' — ' + def.summary,
+    '',
+    'Forwards to scripts/gds/' + def.script + '; extra arguments are passed through.',
+    'Run \`bongos help\` to see every command.',
+  ].join('\\n');
+}
+
+// Returns the exit code (does not call process.exit, so it stays testable).
+function main(argv) {
+  const args = argv.slice(2);
+  const verb = args[0];
+
+  if (!verb || verb === 'help' || verb === '--help' || verb === '-h') {
+    process.stdout.write(helpText() + '\\n');
+    return 0;
+  }
+  if (verb === 'version' || verb === '--version' || verb === '-v') {
+    process.stdout.write('bongos ' + VERSION + '\\n');
+    return 0;
+  }
+
+  if (CHECKOUT_ONLY[verb]) {
+    process.stderr.write(
+      'bongos: "' + verb + '" is not in the public CLI.\\n  ' + CHECKOUT_ONLY[verb] + '\\n\\n' +
+      'To get a checkout without installing anything locally:\\n' +
+      '  bongos shell            open a terminal on your cloud dev box\\n' +
+      '  bongos code             open VS Code on it over Remote-SSH\\n\\n' +
+      'The full CLI (including ' + verb + ') is already installed inside that box.\\n'
+    );
+    return 2;
+  }
+
+  const def = VERBS[verb];
+  if (!def) {
+    process.stderr.write('bongos: unknown command "' + verb + '"\\n\\n' + helpText() + '\\n');
+    return 2;
+  }
+
+  if (!def.selfHelp && args.slice(1).some((a) => a === '--help' || a === '-h')) {
+    process.stdout.write(verbHelpText(verb, def) + '\\n');
+    return 0;
+  }
+
+  const target = path.join(SCRIPTS_DIR, def.script);
+  const spawnArgs = [target, ...(def.prefixArgs || []), ...args.slice(1)];
+  const res = spawnSync(process.execPath, spawnArgs, { stdio: 'inherit' });
+  if (res.error) {
+    process.stderr.write('bongos: could not run ' + def.script + ': ' + res.error.message + '\\n');
+    return 1;
+  }
+  return res.status == null ? 1 : res.status;
+}
+
+if (require.main === module) process.exit(main(process.argv));
+module.exports = { main, helpText, VERBS, CHECKOUT_ONLY };
+`;
+}
+
+function packageJsonSource(version) {
+  // DERIVED from the manifest, never hand-listed. A hand-written `files` array silently drops
+  // whatever it forgets: the first build of this package copied clients/bongos-client/index.mjs
+  // correctly and then `npm pack` left it out, so the tarball installed and died on first use.
+  const roots = [...new Set(FILES.map((f) => f.split('/')[0] + '/'))].sort();
+  return JSON.stringify({
+    name: PACKAGE_NAME,
+    version,
+    description: 'The Cloud Bongos CLI — sign in to an instance, see what you can build, and get onto a dev box. Client only: no server.',
+    bin: { bongos: 'bin/bongos.js' },
+    files: ['bin/', ...roots, 'README.md'],
+    engines: { node: '>=20' },
+    dependencies: { undici: '^6.19.8' },
+    keywords: ['cloud-bongos', 'cli', 'ai-agents', 'build-platform'],
+    license: 'AGPL-3.0-or-later',
+    // No `repository` field on purpose. The core repo is private today, so a repository URL
+    // would 404 for every user of a public package AND put the owner's login in it for nothing.
+    // Point it at the redacted public mirror once that lands (ADR 0099).
+    homepage: 'https://cloudbongos.com',
+    bugs: { url: 'https://cloudbongos.com/builders' },
+    publishConfig: { access: 'public' },
+  }, null, 2) + '\n';
+}
+
+function readmeSource(version) {
+  return `# ${PACKAGE_NAME}
+
+The [Cloud Bongos](https://cloudbongos.com) CLI. Sign in to an instance, see what you can pick
+up, and get onto a dev box — from a terminal, with nothing installed.
+
+## Start here
+
+\`\`\`sh
+npx ${PACKAGE_NAME} login https://your-instance.com
+npx ${PACKAGE_NAME} start
+\`\`\`
+
+\`login\` opens your browser, you click once, and the session is written to
+\`~/.config/cloudbongos/\`. There is no token to copy and no password to set. If the instance
+gates admission, \`login\` files your access request and the owner approves it.
+
+Install it properly once you're past the first run:
+
+\`\`\`sh
+npm install -g ${PACKAGE_NAME}
+bongos start
+\`\`\`
+
+## Commands
+
+Run \`bongos help\` for the current list. In short: \`login\`, \`reauth\`, \`setup\`, \`box\`,
+\`shell\`, \`code\` for your account and environment; \`start\`, \`status\`, \`task\`, \`recall\`,
+\`cost\`, \`release\`, \`api\` for the work.
+
+\`bongos api\` is the escape hatch — it calls any endpoint on the instance as you, so anything
+the web hall can do is reachable from the terminal:
+
+\`\`\`sh
+bongos api GET /api/gds/me
+\`\`\`
+
+## Writing code
+
+\`claim\` and \`ship\` need a real checkout, so they aren't in this package. The shortest path to
+one is a cloud dev box, which needs nothing on your machine:
+
+\`\`\`sh
+bongos box       # turn it on
+bongos shell     # a terminal on it, full CLI already installed
+bongos code      # or VS Code over Remote-SSH
+\`\`\`
+
+## What this package is
+
+The client surface of the Cloud Bongos core, and nothing else — no server, no routes, no
+database, no provisioning. It is generated from the core by
+\`scripts/gds/build-cli-package.js\` and verified by installing the packed tarball into an empty
+directory and running every command.
+
+Version ${version} · AGPL-3.0-or-later
+`;
+}
+
+// ── Build ───────────────────────────────────────────────────────────────────────────────────
+
+function build(opts = {}) {
+  const outDir = path.resolve(REPO_ROOT, opts.out || 'dist/cloudbongos-cli');
+  const version = opts.version || PACKAGE_VERSION;
+  const log = opts.quiet ? () => {} : (m) => process.stdout.write(m + '\n');
+
+  // Refuse a file list that contradicts the package's whole premise, before copying anything.
+  const violations = [];
+  for (const rel of FILES) {
+    if (rel.startsWith('src/bongos/') && !ALLOWED_SRC_BONGOS.has(rel)) {
+      violations.push(`${rel} — src/bongos/ is the kernel; only ${[...ALLOWED_SRC_BONGOS].join(', ')} may ship`);
+    }
+    if (FORBIDDEN_PREFIXES.some((p) => rel.startsWith(p))) violations.push(`${rel} — forbidden path prefix`);
+    if (FORBIDDEN_BASENAMES.includes(path.basename(rel)) && !ALLOWED_SRC_BONGOS.has(rel)) {
+      violations.push(`${rel} — forbidden filename (server surface)`);
+    }
+    if (!fs.existsSync(path.join(REPO_ROOT, rel))) violations.push(`${rel} — missing from the repo`);
+  }
+  if (violations.length) {
+    const err = new Error('cli package manifest rejected:\n  ' + violations.join('\n  '));
+    err.violations = violations;
+    throw err;
+  }
+
+  // Dynamic `import()` of a relative path is invisible to any require()-based reasoning, and
+  // that is not hypothetical: cli-lib.js reaches the generated API client that way, and the
+  // first build shipped without it. Every relative import target in a shipped file must itself
+  // be shipped, or the package installs fine and dies on first use.
+  const unshipped = [];
+  for (const rel of FILES) {
+    if (!/\.(js|mjs|cjs)$/.test(rel)) continue;
+    const text = fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8');
+    for (const m of text.matchAll(/\bimport\(\s*['"](\.[^'"]+)['"]\s*\)/g)) {
+      const target = path.relative(REPO_ROOT, path.resolve(path.dirname(path.join(REPO_ROOT, rel)), m[1]));
+      if (!FILES.includes(target)) unshipped.push(`${rel} dynamically imports ${target}, which the manifest does not ship`);
+    }
+  }
+  if (unshipped.length) {
+    const err = new Error('cli package manifest incomplete:\n  ' + unshipped.join('\n  '));
+    err.violations = unshipped;
+    throw err;
+  }
+
+  fs.rmSync(outDir, { recursive: true, force: true });
+  fs.mkdirSync(outDir, { recursive: true });
+
+  for (const rel of FILES) {
+    const dest = path.join(outDir, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(path.join(REPO_ROOT, rel), dest);
+  }
+
+  fs.mkdirSync(path.join(outDir, 'bin'), { recursive: true });
+  fs.writeFileSync(path.join(outDir, 'bin', 'bongos.js'), dispatcherSource(), { mode: 0o755 });
+  fs.writeFileSync(path.join(outDir, 'package.json'), packageJsonSource(version));
+  fs.writeFileSync(path.join(outDir, 'README.md'), readmeSource(version));
+
+  const generated = [...FILES, 'bin/bongos.js', 'package.json', 'README.md'];
+  const leaks = scanRedaction(outDir, generated);
+  if (leaks.length) {
+    const err = new Error(
+      'cli package redaction gate FAILED — refusing to emit:\n  ' + leaks.join('\n  ') +
+      '\n\nThis package is PUBLIC. Build it from the neutral core, not from an instance checkout' +
+      '\n(an instance\'s config/branding.json names its own domains and owner).'
+    );
+    err.leaks = leaks;
+    throw err;
+  }
+
+  const bytes = generated.reduce((n, rel) => {
+    try { return n + fs.statSync(path.join(outDir, rel)).size; } catch { return n; }
+  }, 0);
+
+  log(`${PACKAGE_NAME}@${version} → ${path.relative(REPO_ROOT, outDir)}`);
+  log(`  ${generated.length} files · ${(bytes / 1024).toFixed(0)} KB · ${Object.keys(VERBS).length} verbs · 1 dependency (undici)`);
+  log(`  redaction gate: clean (${instanceNeedles().length} instance needles checked)`);
+  return { outDir, version, files: generated, verbs: Object.keys(VERBS) };
+}
+
+module.exports = { build, FILES, VERBS, CHECKOUT_ONLY, FORBIDDEN_PREFIXES, FORBIDDEN_BASENAMES, ALLOWED_SRC_BONGOS, PACKAGE_NAME, PACKAGE_VERSION, scanRedaction, instanceNeedles };
+
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  const flag = (name) => { const i = argv.indexOf(name); return i === -1 ? null : argv[i + 1]; };
+  try {
+    build({ out: flag('--out'), version: flag('--version'), quiet: argv.includes('--quiet') });
+  } catch (err) {
+    process.stderr.write(String(err.message) + '\n');
+    process.exit(1);
+  }
+}

package/src/module-api.js

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.576'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.577'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/cli_package.mjs

@@ -0,0 +1,217 @@
+// tests/cli_package.mjs — the public @cloudbongos/cli package is client-only AND actually runs.
+//
+// Guards task 1003679. Two halves, and the second is the one that matters:
+//
+//  1. Shape: the generated tree carries no server surface, and the redaction gate really fails
+//     a build when instance identity or a credential shape appears in it.
+//
+//  2. BEHAVIOUR: pack the tarball, install it into an empty directory with NO repo present, and
+//     run every advertised verb. This is the only instrument that can prove the file list is
+//     complete. A static require-closure cannot: src/module-api.js is the module doorway
+//     (ADR 0083) and by design *names* every kernel capability, so a static walk sees the whole
+//     server even though the getters are lazy and never resolve. If a real code path needs a
+//     file the manifest omits, the verb exits with MODULE_NOT_FOUND and this test says so.
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const BUILDER = path.join(REPO_ROOT, 'scripts', 'gds', 'build-cli-package.js');
+
+const mod = await import(path.join(REPO_ROOT, 'scripts', 'gds', 'build-cli-package.js'));
+const { build, FILES, VERBS, CHECKOUT_ONLY, ALLOWED_SRC_BONGOS, PACKAGE_NAME } = mod.default ?? mod;
+
+function tmpdir(tag) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), `cli-pkg-${tag}-`));
+}
+
+// ── 1. Shape ────────────────────────────────────────────────────────────────────────────────
+
+test('the generated package contains no server surface', () => {
+  const out = tmpdir('shape');
+  const { files } = build({ out, quiet: true });
+
+  const kernel = files.filter((f) => f.startsWith('src/bongos/'));
+  assert.deepEqual(kernel, [...ALLOWED_SRC_BONGOS],
+    `only ${[...ALLOWED_SRC_BONGOS].join(', ')} may ship from the kernel, got ${kernel.join(', ')}`);
+
+  for (const f of files) {
+    assert.ok(!f.startsWith('src/bongos/routes/'), `${f}: routes must never ship`);
+    assert.ok(!/(^|\/)(pool|db|server|serve-internal)\.js$/.test(f), `${f}: server surface must never ship`);
+    assert.ok(!f.startsWith('migrations/'), `${f}: migrations must never ship`);
+    assert.ok(!f.startsWith('infra/'), `${f}: infra must never ship`);
+  }
+  fs.rmSync(out, { recursive: true, force: true });
+});
+
+test('the one kernel file that ships imports nothing', () => {
+  const src = fs.readFileSync(path.join(REPO_ROOT, 'src', 'bongos', 'api-prefix.js'), 'utf8');
+  const rel = [...src.matchAll(/require\(\s*['"](\.[^'"]+)['"]\s*\)/g)].map((m) => m[1]);
+  assert.deepEqual(rel, [], `api-prefix.js must stay dependency-free, found: ${rel.join(', ')}`);
+});
+
+test('every file in the manifest exists', () => {
+  for (const rel of FILES) {
+    assert.ok(fs.existsSync(path.join(REPO_ROOT, rel)), `manifest names a missing file: ${rel}`);
+  }
+});
+
+test('every advertised verb maps to a script the manifest ships', () => {
+  for (const [verb, def] of Object.entries(VERBS)) {
+    assert.ok(FILES.includes(`scripts/gds/${def.script}`),
+      `verb "${verb}" runs scripts/gds/${def.script}, which the manifest does not ship`);
+  }
+});
+
+test('the redaction gate fails the build on an injected needle and on a credential shape', () => {
+  const out = tmpdir('gate');
+
+  // A domain that really is in the tree, supplied as forbidden → must refuse to emit.
+  const withNeedle = spawnSync(process.execPath, [BUILDER, '--out', out, '--quiet'], {
+    cwd: REPO_ROOT, encoding: 'utf8',
+    env: { ...process.env, CLI_PACKAGE_FORBIDDEN: 'cli-lib' },
+  });
+  assert.notEqual(withNeedle.status, 0, 'an instance needle present in the tree must fail the build');
+  assert.match(withNeedle.stderr, /redaction gate FAILED/);
+
+  // A planted credential shape must fail too, with no needle configured at all.
+  const planted = path.join(REPO_ROOT, 'scripts', 'gds', '.cli-pkg-gate-probe.js');
+  const victim = path.join(REPO_ROOT, 'scripts', 'gds', 'preflight.js');
+  const original = fs.readFileSync(victim, 'utf8');
+  try {
+    fs.writeFileSync(victim, `${original}\n// ghp_0123456789abcdefghijABCDEFGHIJ0123\n`);
+    const withToken = spawnSync(process.execPath, [BUILDER, '--out', out, '--quiet'], {
+      cwd: REPO_ROOT, encoding: 'utf8',
+    });
+    assert.notEqual(withToken.status, 0, 'a github token shape must fail the build');
+    assert.match(withToken.stderr, /github token/);
+  } finally {
+    fs.writeFileSync(victim, original);
+    fs.rmSync(planted, { force: true });
+  }
+  fs.rmSync(out, { recursive: true, force: true });
+});
+
+test('a clean build emits and reports itself', () => {
+  const out = tmpdir('clean');
+  const res = spawnSync(process.execPath, [BUILDER, '--out', out], { cwd: REPO_ROOT, encoding: 'utf8' });
+  assert.equal(res.status, 0, `clean build failed:\n${res.stderr}`);
+  assert.match(res.stdout, /redaction gate: clean/);
+  assert.ok(fs.existsSync(path.join(out, 'package.json')));
+  assert.ok(fs.existsSync(path.join(out, 'bin', 'bongos.js')));
+
+  const pkg = JSON.parse(fs.readFileSync(path.join(out, 'package.json'), 'utf8'));
+  assert.equal(pkg.name, PACKAGE_NAME);
+  assert.deepEqual(Object.keys(pkg.dependencies), ['undici'], 'exactly one runtime dependency');
+  assert.equal(pkg.bin.bongos, 'bin/bongos.js');
+  assert.equal(pkg.publishConfig.access, 'public');
+  assert.ok(!('repository' in pkg), 'no repository URL while the core repo is private');
+  fs.rmSync(out, { recursive: true, force: true });
+});
+
+// ── 2. Behaviour: install the tarball where there is no repo, and run it ─────────────────────
+
+test('the packed tarball installs and every verb runs with no repo present', (t) => {
+  const buildOut = tmpdir('pack');
+  const home = tmpdir('home');
+  const site = tmpdir('site');
+
+  const built = spawnSync(process.execPath, [BUILDER, '--out', buildOut, '--quiet'], {
+    cwd: REPO_ROOT, encoding: 'utf8',
+  });
+  assert.equal(built.status, 0, `build failed:\n${built.stderr}`);
+
+  const packed = spawnSync('npm', ['pack', '--silent', '--pack-destination', site], {
+    cwd: buildOut, encoding: 'utf8',
+  });
+  assert.equal(packed.status, 0, `npm pack failed:\n${packed.stderr}`);
+  const tarball = fs.readdirSync(site).find((f) => f.endsWith('.tgz'));
+  assert.ok(tarball, `no tarball produced in ${site}`);
+
+  // An empty directory: no repo, no core, no config, and a HOME of its own so a real session
+  // file on this machine cannot make a verb look healthier than it is.
+  fs.writeFileSync(path.join(site, 'package.json'), JSON.stringify({ name: 'probe', private: true }));
+  const installed = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--silent', path.join(site, tarball)], {
+    cwd: site, encoding: 'utf8', env: { ...process.env, HOME: home },
+  });
+  assert.equal(installed.status, 0, `npm install failed:\n${installed.stderr}`);
+
+  const bongos = path.join(site, 'node_modules', '.bin', 'bongos');
+  assert.ok(fs.existsSync(bongos), 'the package did not install a `bongos` binary');
+
+  const runVerb = (args) => spawnSync(bongos, args, {
+    cwd: site, encoding: 'utf8', input: '',
+    env: { ...process.env, HOME: home, CLOUDBONGOS_API_BASE: 'http://127.0.0.1:45999', NO_COLOR: '1' },
+  });
+
+  // help and version must work with nothing configured at all.
+  const help = runVerb(['help']);
+  assert.equal(help.status, 0, `bongos help failed:\n${help.stderr}`);
+  assert.match(help.stdout, /bongos login https:\/\//, 'help must lead with how to sign in');
+
+  const version = runVerb(['version']);
+  assert.equal(version.status, 0);
+  assert.match(version.stdout, /^bongos \d+\.\d+\.\d+/m);
+
+  // Every advertised verb must actually LOAD its script. Args are chosen so the dispatcher
+  // cannot answer on the script's behalf — `--help` on a non-selfHelp verb is intercepted by
+  // the dispatcher and would leave the script untouched, which is how this test could pass
+  // while proving nothing. Each verb below reaches its own code, then fails on the dead API
+  // base or on missing arguments. Failing that way is fine; failing to find a file is not.
+  const LOAD_ARGS = {
+    login:   ['login'],
+    reauth:  ['reauth'],
+    setup:   ['setup'],
+    box:     ['box'],
+    shell:   ['shell'],
+    code:    ['code'],
+    start:   ['start'],
+    status:  ['status'],
+    task:    ['task', 'show', '1'],
+    recall:  ['recall', 'probe'],
+    cost:    ['cost'],
+    release: ['release'],
+    api:     ['api', 'GET', '/api/gds/me'],
+  };
+  assert.deepEqual(
+    Object.keys(LOAD_ARGS).sort(), Object.keys(VERBS).sort(),
+    'every advertised verb needs an entry here, or it goes unexercised',
+  );
+
+  for (const [verb, args] of Object.entries(LOAD_ARGS)) {
+    const res = runVerb(args);
+    const all = `${res.stdout}\n${res.stderr}`;
+    assert.ok(!/Cannot find module|MODULE_NOT_FOUND|ERR_MODULE_NOT_FOUND/.test(all),
+      `bongos ${verb} hit a missing file — the manifest is incomplete:\n${all}`);
+    assert.ok(!/ERR_REQUIRE_ESM|SyntaxError|ReferenceError/.test(all),
+      `bongos ${verb} failed to load:\n${all}`);
+    // `TypeError: fetch failed` is what an unreachable API base looks like and is expected
+    // here; any OTHER TypeError means the package itself is broken.
+    assert.ok(!/TypeError(?!: fetch failed)/.test(all),
+      `bongos ${verb} threw a real TypeError:\n${all}`);
+    assert.notEqual(res.status, null, `bongos ${verb} was killed by a signal:\n${all}`);
+    // The dispatcher's own help card is proof the script was never reached.
+    assert.ok(!/^bongos \w+ — .*\nForwards to scripts/m.test(all),
+      `bongos ${verb} was answered by the dispatcher instead of loading:\n${all}`);
+  }
+
+  // The excluded verbs must teach the next step, not print a bare "unknown command".
+  for (const verb of Object.keys(CHECKOUT_ONLY)) {
+    const res = runVerb([verb]);
+    const all = `${res.stdout}\n${res.stderr}`;
+    assert.match(all, /is not in the public CLI/, `bongos ${verb} must say why it is absent`);
+    assert.match(all, /bongos shell/, `bongos ${verb} must point at a way to get a checkout`);
+    assert.ok(!/unknown command/.test(all), `bongos ${verb} must not read as a typo`);
+  }
+
+  // An unknown verb still behaves like one.
+  const bogus = runVerb(['definitely-not-a-verb']);
+  assert.match(bogus.stderr, /unknown command/);
+
+  for (const d of [buildOut, home, site]) fs.rmSync(d, { recursive: true, force: true });
+});