@bongos/core 1.21.47 → 1.21.49

package/modules/hall-ui/public/commands-lib.js

@@ -24,7 +24,7 @@
     {
       key: 'find', label: 'Finding things out and working with others',
       blurb: 'Looking up what the project already knows, asking for help, and passing work on.',
-      names: ['status', 'recall', 'ask-for-help', 'collab-review', 'session-handoff', 'read-session-export', 'feedback'],
+      names: ['status', 'recall', 'ask-for-help', 'collab-review', 'session-handoff', 'read-session-export'],
     },
     {
       key: 'owner', label: 'Owner routines',

package/modules/hall-ui/public/hall-render.js

@@ -808,11 +808,11 @@
       ? `Stuck on any step? <a href="${API}/auth/discord/start">Join our Discord</a> and ask in <strong>#support</strong>.`
       : `Stuck on any step? See the project's README and docs.`;
     const setupSteps = `
-        <p class="setup__intro">Build from your own machine — clone the repository, run the platform locally, and sign in from the terminal.</p>
+        <p class="setup__intro">Build from your own machine — get a copy of the project, sign in once, then work in Claude.</p>
         <ol class="setup__steps">
           <li><strong>Clone the repository</strong> and install dependencies (<code>npm install</code>).</li>
-          <li><strong><a href="https://claude.com/download" target="_blank" rel="noopener noreferrer">Download Claude</a></strong> (or use the Claude Code CLI) and open the project.</li>
-          <li><strong>Run <code>/builder-setup</code></strong> to authenticate this machine, then <code>/builder-start</code> to claim your first task.</li>
+          <li><strong>Run <code>npx bongos setup</code></strong> in that folder to sign this machine in.</li>
+          <li><strong><a href="https://claude.com/download" target="_blank" rel="noopener noreferrer">Download Claude</a></strong> (or use the Claude Code CLI), open the project, and run <code>/builder-start</code> to claim your first task.</li>
         </ol>
     `;
     // task 469: a "Set up your machine / get the code" door. The steps above
@@ -821,24 +821,26 @@
     // how do I get it onto my own laptop?". It's the hall mirror of the primer's
     // "Step 0 — get the project onto your machine". Collapsed by default so it
     // doesn't crowd the recommended path; the clone block is click-to-copy
-    // (copy-on-click.js picks up .welcome__paste). The commands mirror
-    // scripts/setup-builder.sh's own header verbatim so they can't drift.
+    // (copy-on-click.js picks up .welcome__paste). Sign-in is `npx bongos setup`
+    // (bin/bongos.js → scripts/gds/setup.js), one line on every OS — bare
+    // `bongos` is not on a fresh clone's PATH, `npx` finds the repo's own bin.
     // The clone commands come from the instance's own repo coords (loaded from
     // GET /api/bongos/instance), not a hardcoded repo, so a fresh instance's newcomer
     // clones ITS project (ADR 0062 §3, task 1705). Falls back to generic guidance
     // until the coords load (or if they're unavailable).
     const cloneBlock = ctx.instanceRepo
-      ? `git clone ${escapeHtml(ctx.instanceRepo.url)}.git\ncd ${escapeHtml(ctx.instanceRepo.repo)}\n./scripts/setup-builder.sh`
-      : `# clone your instance's repository, cd into it, then run:\n./scripts/setup-builder.sh`;
+      ? `git clone ${escapeHtml(ctx.instanceRepo.url)}.git\ncd ${escapeHtml(ctx.instanceRepo.repo)}\nnpm install\nnpx bongos setup`
+      : `# clone your instance's repository, cd into it, then run:\nnpm install\nnpx bongos setup`;
     const getCode = `
         <details class="setup__getcode">
           <summary class="setup__getcode-summary">Set up your machine / get the code</summary>
           <div class="setup__getcode-body">
-            <p class="setup__hint">First install <a href="https://git-scm.com/downloads" target="_blank" rel="noopener noreferrer">Git</a>
+            <p class="setup__hint">First install <a href="https://git-scm.com/downloads" target="_blank" rel="noopener noreferrer">Git</a>,
+              <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">Node</a> (version 22 or newer)
               and <a href="https://claude.com/download" target="_blank" rel="noopener noreferrer">Claude Code</a> — that's all the tooling you need up front.</p>
-            <p class="setup__getcode-lede">Then copy the project onto your machine and run the one-shot bootstrap (it checks your setup, installs dependencies, and signs you in):</p>
+            <p class="setup__getcode-lede">Then copy the project onto your machine, install its dependencies, and sign in:</p>
             <code class="welcome__paste">${cloneBlock}</code>
-            <p class="setup__hint">On Windows, run <code>node scripts/setup-builder.js</code> instead of the last line. New to the steps? The
+            <p class="setup__hint">The same commands work on Mac, Windows and Linux. New to the steps? The
               <a href="/primer">primer</a> walks the whole path in plain language.</p>
           </div>
         </details>`;
@@ -898,7 +900,7 @@
         <span class="onboarding-item__mark" aria-hidden="true">›</span>
         <div class="onboarding-item__body">
           <p class="onboarding-item__label">First — obtain the repo</p>
-          <p class="onboarding-item__hint">Clone the project to your machine. The build commands live inside the repo, so this comes first. The remaining steps below are tracked automatically.</p>
+          <p class="onboarding-item__hint">Clone the project to your machine and run <code>npm install</code> in it. The build commands live inside the repo, so this comes first. The remaining steps below are tracked automatically.</p>
         </div>
       </li>`;
 

package/modules/hall-ui/public/settings.html

@@ -140,13 +140,13 @@
             <section class="scroll" id="cli-scroll" aria-labelledby="cli-h" data-group="access" hidden>
               <h2 id="cli-h" class="scroll__h">CLI access</h2>
               <p class="scroll__lede">
-                Mint a fresh CLI token using this browser session and paste it into
-                your terminal — the quick way back in when a <code>/builder-*</code>
-                command says your session expired.
+                Mint a fresh CLI token using this browser session and paste the
+                command it gives you into a terminal in your project folder — the quick
+                way back in when a <code>/builder-*</code> command says your session expired.
               </p>
               <div class="settings-card">
                 <button type="button" class="settings-btn" id="cli-reissue-btn">Re-issue CLI token</button>
-                <span class="settings-card__hint">paste it into your terminal — bypasses Device Flow.</span>
+                <span class="settings-card__hint">no GitHub code to type in.</span>
                 <div id="cli-reissue-result" class="cli-result" hidden></div>
               </div>
               <p class="section-note">Tokens refresh on use; re-issuing never signs you out anywhere else.</p>

package/modules/hall-ui/public/settings.js

@@ -792,7 +792,7 @@
       // three out of the copy registry, blinding the artist's queue to this panel.
       const el = (tag, cls) => Object.assign(document.createElement(tag), { className: cls });
       const say = el('p', 'cli-result__say');
-      say.textContent = 'Fresh CLI token issued. Paste it in your terminal:';
+      say.textContent = 'Fresh CLI token issued. Paste this into a terminal in your project folder:';
       const eyebrow = el('p', 'quote__eyebrow');
       eyebrow.textContent = 'paste command';
       const pre = el('pre', 'quote__pre');

package/modules/hall-ui/public/style.css

@@ -3206,6 +3206,15 @@ main [id] { scroll-margin-top: calc(var(--topbar-h) + 16px); }
   padding: 8px 12px;
   overflow-x: auto;
 }
+/* The get-the-code block is several commands, one per line. Without `pre` the
+   line breaks collapse on screen AND in copy-on-click (it copies innerText),
+   so a builder pasted every command onto one line. Both axes named: see the
+   one-axis-strip rule in this module's CLAUDE.md. */
+.setup__getcode .welcome__paste {
+  display: block;
+  white-space: pre;
+  overflow-y: hidden;
+}
 
 .setup { margin-top: 12px; }
 .setup__intro { font-size: 13px; color: var(--ink-soft); }

package/modules/onboarding/onboarding-state.js

@@ -92,7 +92,7 @@ const ALL_STAGES = [...STAGES, GRADUATED];
 const PRE_AUTH_STEP = {
   id: 'obtain_repo',
   label: 'Obtain the repo',
-  hint: 'Clone the project to thy machine. The build commands live inside the repo, so this comes first.',
+  hint: 'Clone the project to thy machine and run npm install in it. The build commands live inside the repo, so this comes first.',
   informational: true,
 };
 
@@ -126,7 +126,7 @@ const STAGE_LABELS = {
 // onboarding model never named that step, so the hint now points at it ahead of
 // the sign-in itself. See PRE_AUTH_STEP below for the standalone representation.
 const STAGE_HINTS = {
-  auth_complete:    'First obtain the repo — clone it — then sign in via GitHub Device Flow or the web sign-in.',
+  auth_complete:    'First obtain the repo — clone it — then sign in with npx bongos setup in that folder.',
   pick_disciplines: 'Pick the work that calls thee — engineer, artist, ideator, or any mix.',
   first_start:      'Run /builder-start to see claimable works.',
   first_claim:      'Claim a task with /builder-claim N — it is thine alone until thou shippest it.',
@@ -153,7 +153,7 @@ function isKnownStage(stage) {
 //                         clears the step. `source: 'discord'`.
 //   2. pick_disciplines — the real engine stage, cleared by the craft picker.
 //   3. cli_setup        — cleared once the builder has authenticated the CLI
-//                         (ran /builder-setup, which mints a source='cli'
+//                         (ran `npx bongos setup`, which mints a source='cli'
 //                         session). Detected via db.hasCliSession; passed in as
 //                         `cliAuthed`. `source: 'cli'`.
 //   4. ship_three       — the real engine stage. Auto, live "N of 3" counter,
@@ -178,14 +178,14 @@ const DISPLAY_STEPS = [
 const DISPLAY_LABELS = {
   join_discord:     'Join the Discord server',
   pick_disciplines: 'Choose thy craft — engineer, artist, or ideator',
-  cli_setup:        'Run /builder-setup',
+  cli_setup:        'Run npx bongos setup',
   ship_three:       'Ship three works — and rise to Thetes',
 };
 
 const DISPLAY_HINTS = {
   join_discord:     'Connect Discord — thou art auto-joined to the city\'s server and given thy rank.',
   pick_disciplines: 'Pick the work that calls thee — engineer, artist, ideator, or any mix.',
-  cli_setup:        'Sign the CLI in with /builder-setup — this ticks itself once thou art signed in.',
+  cli_setup:        'In thy copy of the project, run npx bongos setup — this ticks itself once thou art signed in.',
   ship_three:       'Carry three tasks through with /builder-ship — the third makes thee a Thetes.',
 };
 

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.47",
+  "version": "1.21.49",
   "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/release-notes.json

@@ -9046,5 +9046,21 @@
       "id": "1004562",
       "text": "Walked every building and floor desk of the Governor City in light, dark and on a phone, and fixed what did not match the design: number tiles now say what they count, a cleared floor no longer shows a stale count, counts read"
     }
+  ],
+  "1.21.48": [
+    {
+      "id": "1004576",
+      "text": "Saying \"Bongos feedback: …\" or suggesting how Bongos should behave now reliably sends it to the Bongos team; an unused leftover skill that confused this was removed."
+    },
+    {
+      "id": "1004573",
+      "text": "A project brought in from an existing repo now always picks up the sign-in and settings the platform gives it, instead of silently ignoring them."
+    }
+  ],
+  "1.21.49": [
+    {
+      "id": "1004575",
+      "text": "New builders get setup steps that actually work end to end: the sign-in commands in Settings and the primer now run from a fresh copy of the project, the primer's terminal commands display properly, and the setup no longer lea"
+    }
   ]
 }

package/scripts/gds/claude-materialize.js

@@ -346,6 +346,9 @@ const STARTER_COMMANDS = [
   'bongos release:*',
   'bongos reauth:*',
   'bongos paste-token:*',
+  // What Settings → CLI access hands out since task 1004575: a clone has no
+  // bare `bongos` on PATH, so the copied command runs through npx.
+  'npx bongos paste-token:*',
   'bongos exec scripts/gds/api.js:*',
   // The read-only subset (task 1003992, ADR 0304). `git branch` and `git fetch`
   // are exact forms on purpose: a flag turns either into a write or an exec. No

package/scripts/gds/pack-env-prefix.js

@@ -0,0 +1,73 @@
+'use strict';
+
+// scripts/gds/pack-env-prefix.js — which env-var names a hosted project reads, and
+// whether its own pack agrees with what the provisioning runner writes (task 1004573).
+//
+// WHY. The runner writes every hosted project's /etc/<slug>/web.env under ONE prefix
+// (provisionedEnvPrefix). A project ADOPTED from an existing repo brings its own
+// config/branding.json, and mercury's said envPrefix CLOUDBONGOS while web.env carried
+// BONGOS_* — so the project read none of its sign-in credentials, its address or any
+// setting, and the only symptom anyone saw was "did not report sign-in ready".
+//
+// Its own file because both provision-units.js (web.env) and provision-repo.js (the
+// adopt scaffold) need it, and provision-units already requires provision-repo — a
+// helper living in either would make a require cycle. Requires only provision-config.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { REPO_ROOT } = require('./provision-config.js');
+
+// The pack whose envPrefix a provisioned instance inherits unless its own pack says
+// otherwise (see the long note on ENV_PREFIX_PACK's history in provision-units.js).
+const ENV_PREFIX_PACK = 'config/branding.neutral.json';
+
+// The env-var prefix a provisioned instance actually RESOLVES — i.e. the envPrefix
+// of the pack it loads (ENV_PREFIX_PACK). src/instance-config.resolveEnv
+// reads <envPrefix>_<SUFFIX>, and src/branding.resolveBranding applies
+// <envPrefix>_{PUBLIC,BUILDERS,…}_ORIGIN overrides — so a web.env var only takes
+// effect under THIS prefix. Read from the pack (fail-soft to the vanilla default)
+// so it stays in lockstep instead of a magic string. (The prior slug-based prefix
+// was a latent bug: it never matched the neutral pack's CLOUDBONGOS envPrefix, so
+// the OAuth creds were silently unreadable — task 1972.)
+function provisionedEnvPrefix() {
+  const { FALLBACK_ENV_PREFIX } = require('../../src/instance-config'); // eslint-disable-line global-require
+  try {
+    const pack = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, ENV_PREFIX_PACK), 'utf8'));
+    return pack.envPrefix || FALLBACK_ENV_PREFIX;
+  } catch { return FALLBACK_ENV_PREFIX; }
+}
+
+// The envPrefix a pack's text names, or null (no pack, not JSON, no envPrefix).
+function packEnvPrefix(packText) {
+  try {
+    const pack = JSON.parse(String(packText || ''));
+    return pack && typeof pack.envPrefix === 'string' ? pack.envPrefix : null;
+  } catch { return null; }
+}
+
+// Does the instance's OWN pack read the names this runner writes? PURE: give it the
+// pack's text (or null when it could not be read) and the prefix written; it returns
+// a sentence naming the mismatch, or null when the names agree or the pack says nothing.
+function envPrefixMismatch(packText, written = provisionedEnvPrefix()) {
+  const own = packEnvPrefix(packText);
+  if (!own || own === written) return null;
+  return `the project's config/branding.json reads settings named ${own}_*, but the platform wrote ${written}_* — set its envPrefix to "${written}"`;
+}
+
+// The adopt scaffold's half of the fix: rewrite ONLY the envPrefix value in an adopted
+// repo's config/branding.json so the project reads the names this runner writes,
+// leaving every other byte of the owner's file as they wrote it (a JSON round-trip
+// would reflow it). PURE. Returns { text, from } when it changed something, or null
+// when the names already agree, the pack names no prefix, or it is not JSON.
+function normalizePackEnvPrefix(packText, written = provisionedEnvPrefix()) {
+  const raw = String(packText || '');
+  const own = packEnvPrefix(raw);
+  if (!own || own === written) return null;
+  const re = /("envPrefix"\s*:\s*)"[^"]*"/;
+  if (!re.test(raw)) return null;
+  const text = raw.replace(re, (_m, key) => `${key}"${written}"`);
+  if (packEnvPrefix(text) !== written) return null;
+  return { text, from: own };
+}
+
+module.exports = { ENV_PREFIX_PACK, provisionedEnvPrefix, envPrefixMismatch, normalizePackEnvPrefix };

package/scripts/gds/provision-repo.js

@@ -19,6 +19,7 @@ const { CONFIG, REPO_ROOT, coreVersionSafe, provisionerBotEmail, provisionerBotN
 // upgrade.js can reach these three without pulling provision*.js into the merge
 // resolver's executed closure; re-exported below so every existing caller is unchanged.
 const { instanceRepoRemote, parseTargetRef, resolveOwnerGithubToken } = require('./provision-repo-auth.js');
+const { normalizePackEnvPrefix } = require('./pack-env-prefix.js');   // an adopted pack's envPrefix (task 1004573)
 const { CORE_PKG, compareSemver, isStable } = require('./update-channel.js');
 
 function dbName(inst) { return inst.db_name || inst.slug; }
@@ -832,6 +833,18 @@ async function scaffoldStandaloneRepo(inst, deps) {
     } else {
       writeFile(giPath, INSTANCE_GITIGNORE);
     }
+    // Adopt layers config only where ABSENT, so an owner's existing config/branding.json
+    // keeps whatever envPrefix it carried — and web.env is written under the platform's.
+    // Mercury's said CLOUDBONGOS: it read none of its credentials or settings (task 1004573).
+    // Rewrite just that one value, in this same commit, so the repo and web.env agree.
+    const packPath = path.join(root, 'config', 'branding.json');
+    if (mode === 'adopt' && fs.existsSync(packPath)) {
+      const fixed = normalizePackEnvPrefix(fs.readFileSync(packPath, 'utf8'));
+      if (fixed) {
+        writeFile(packPath, fixed.text);
+        log(`  [scaffold] config/branding.json envPrefix ${fixed.from} → the platform's, so the project reads the settings it is given`);
+      }
+    }
     exec(`git -C ${root} config user.name "${provisionerBotName()}"`);
     exec(`git -C ${root} config user.email "${provisionerBotEmail()}"`);
     exec(`git -C ${root} add -A`);

package/scripts/gds/provision-units.js

@@ -162,23 +162,10 @@ WantedBy=timers.target
 // branding-file env line is written at all. Reading the neutral pack HERE is still correct: it is
 // the prefix floor an instance inherits unless its own pack overrides envPrefix, and every live
 // co-tenant pack pins `envPrefix: "CLOUDBONGOS"` explicitly.
-const ENV_PREFIX_PACK = 'config/branding.neutral.json';
-
-// The env-var prefix a provisioned instance actually RESOLVES — i.e. the envPrefix
-// of the pack it loads (ENV_PREFIX_PACK). src/instance-config.resolveEnv
-// reads <envPrefix>_<SUFFIX>, and src/branding.resolveBranding applies
-// <envPrefix>_{PUBLIC,BUILDERS,…}_ORIGIN overrides — so a web.env var only takes
-// effect under THIS prefix. Read from the pack (fail-soft to the vanilla default)
-// so it stays in lockstep instead of a magic string. (The prior slug-based prefix
-// was a latent bug: it never matched the neutral pack's CLOUDBONGOS envPrefix, so
-// the OAuth creds were silently unreadable — task 1972.)
-function provisionedEnvPrefix() {
-  const { FALLBACK_ENV_PREFIX } = require('../../src/instance-config');
-  try {
-    const pack = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, ENV_PREFIX_PACK), 'utf8'));
-    return pack.envPrefix || FALLBACK_ENV_PREFIX;
-  } catch { return FALLBACK_ENV_PREFIX; }
-}
+// ENV_PREFIX_PACK + provisionedEnvPrefix (and the task-1004573 pack checks) live in
+// pack-env-prefix.js — provision-repo.js needs them too, and it cannot require this file
+// (this file requires it). Re-exported below so every existing caller is unchanged.
+const { ENV_PREFIX_PACK, provisionedEnvPrefix, envPrefixMismatch, normalizePackEnvPrefix } = require('./pack-env-prefix.js');
 
 // The per-instance secrets file body (the standup runbook's /etc/<inst>/web.env).
 // The OAuth client id/secret are GUIDED/manual inputs (no GitHub create-API) — the
@@ -430,6 +417,8 @@ function renamedEnvCarry(body) {
 
 module.exports = {
   ENV_PREFIX_PACK,
+  envPrefixMismatch,
+  normalizePackEnvPrefix,
   backupScriptPath,
   backupService,
   backupServicePath,

package/scripts/gds/provision.js

@@ -50,7 +50,7 @@ const crypto = require('node:crypto');
 const retry = require('./intent-retry.js'); // when a failed intent is tried again (task 1004447)
 const { CONFIG, MANIFEST_UA, softFailResult, MANIFEST_VERIFY_INTERVAL_MS, MANIFEST_VERIFY_TRIES, MAX_INTENT_ATTEMPTS, REPO_ROOT, coreVersionSafe, hasFlag, loadDeps, oauthSecret, provisionerBotEmail } = require('./provision-config.js');
 const { accountPreflight, appUser, alreadyScaffolded, buildCorePinRefreshCommit, coreCheckoutHasGit, dbCreateCmd, dbName, dbRoleCmd, dbRoleCmdShown, dbRoleGrantsCmd, ensureInstanceUserCmd, generateDbPassword, grantInstanceRepoReadCmd, instanceDbRole, instanceStateDir, instanceUser, deployKeyPath, deployKeyTitle, ensurePrivateRepoAccess, installedCorePackDir, installedCoreTarball, instanceInitSpec, instanceRepoRemote, migrateCmd, onboardMode, ownerLoginOf, parseTargetRef, planCorePinRefresh, refreshStandaloneCorePin, resolveOwnerGithubToken, resolveVendorableCoreTarball, safeVersionLabel, scaffoldStandaloneRepo, seedFirstVersionCmd, standaloneInstallCmd, standaloneMigrateCmd, standalonePullCmd, standaloneRegenDocsCmd, standaloneRoot } = require('./provision-repo.js');
-const { backupScriptPath, backupService, backupServicePath, backupTimer, backupTimerPath, backupUnitName, instanceManifestCmd, originEnvVarsFor, serviceUnit, serviceUnitPath, settingsConsumed, settingsEnvVarsFor, renamedEnvCarry, upsertEnvVars, webEnvBody, webEnvPath } = require('./provision-units.js');
+const { backupScriptPath, backupService, backupServicePath, backupTimer, backupTimerPath, backupUnitName, envPrefixMismatch, instanceManifestCmd, originEnvVarsFor, serviceUnit, serviceUnitPath, settingsConsumed, settingsEnvVarsFor, renamedEnvCarry, upsertEnvVars, webEnvBody, webEnvPath } = require('./provision-units.js');
 const { caddyBlock, caddySnippetPath, checkCaddyWiring, checkDnsTokenScope, classifyZoneScope, dnsReleaseEnv, dnsUpsertEnv, federateInstance, federationHubOrigin, healthzCmd, identityCmd, identityVerdict, ingressPlaneGap, ingressPreflight, shouldFederate, zoneForDomain } = require('./provision-net.js');
 const { resolveProcessManager } = require('./provision-process.js');
 const { capacityPreflight, statusCapacityLine } = require('./provision-capacity.js');
@@ -1097,7 +1097,13 @@ async function placeManifestCreds(inst, mrow, deps) {
     if (!authConfigured) {
       // The App now EXISTS on the owner's account — keep its id + slug on the row so
       // the wizard can name it and say why "try again" makes a second one (task 1004572).
-      return { ok: false, codeSpent: true, appId: creds.appId, appSlug: creds.appSlug, error: 'the credentials are placed, but the project did not report sign-in ready in time' };
+      // Say WHY when we can see it: an adopted repo's own pack may read other names (task 1004573).
+      // A cloud-host checkout lives on the control plane (the scaffold reads it the same way), so
+      // this is a plain file read — no shell. An unreadable or non-JSON pack names nothing.
+      let packText = null;
+      if (standalone) { try { packText = (deps.readFile || fs.readFileSync)(path.join(standaloneRoot(inst), 'config', 'branding.json'), 'utf8'); } catch { packText = null; } }
+      const why = envPrefixMismatch(packText);
+      return { ok: false, codeSpent: true, appId: creds.appId, appSlug: creds.appSlug, error: `the credentials are placed, but the project did not report sign-in ready in time${why ? ` — ${why}` : ''}` };
     }
     log('  [oauth-manifest] ✓ /healthz auth_configured=true — sign-in is live');
   } else {

package/src/bongos/routes/auth.js

@@ -1306,17 +1306,18 @@ module.exports = function buildAuthRouter() {
         // THERE — on an instance, where the core is an installed dependency and
         // `scripts/gds/` does not exist, so the previous
         // `node scripts/gds/paste-token.js <token>` named a file the builder did not
-        // have and the copy button handed out a command that could not run. `bongos`
-        // is on PATH in any installed instance, so the verb form is layout- and
-        // directory-independent.
+        // have and the copy button handed out a command that could not run. The verb
+        // is run through `npx` (task 1004575): a builder's clone does not put bare
+        // `bongos` on PATH, and `npx bongos` resolves the project's own bin there.
+        // The hall tells them to paste it in their project folder.
         //
         // The --api-base flag carries the issuer above. Omitted when this instance
         // cannot state its own origin, because a flag with an empty value would be
         // worse than none: paste-token would take '' as an explicit instruction and
         // stop falling back to the resolution that works today.
         paste_command: issuer
-          ? `bongos paste-token ${token} --api-base ${issuer}`
-          : `bongos paste-token ${token}`,
+          ? `npx bongos paste-token ${token} --api-base ${issuer}`
+          : `npx bongos paste-token ${token}`,
       });
     } catch (err) {
       log.error('[gds] POST /auth/cli-token/issue', err);

package/src/instance-config.js

@@ -190,7 +190,7 @@ function readConfigFileSync(name, { encoding = 'utf8', b = safeBrand() } = {}) {
 // per process naming the old spelling, the new one, and the release the old
 // stops working in; see warnLegacyEnv below. `warn` is injectable so a test can
 // assert the warning fires rather than only that the value resolves.
-function resolveEnv(suffix, { env = process.env, prefix = envPrefix(), legacy = LEGACY_ENV_PREFIXES, warn = warnLegacyEnv } = {}) {
+function resolveEnv(suffix, { env = process.env, prefix = envPrefix(), legacy = LEGACY_ENV_PREFIXES, warn = warnLegacyEnv, warnPack = warnPackPrefix } = {}) {
   const canonical = `${prefix}_${suffix}`;
   const canonicalValue = prefix ? env[canonical] : undefined;
   const canonicalSet = canonicalValue !== undefined && canonicalValue !== '';
@@ -200,6 +200,22 @@ function resolveEnv(suffix, { env = process.env, prefix = envPrefix(), legacy =
   // on the winner would leave the "both set" operator with no notice at all.
   const seen = new Set([prefix].filter(Boolean));
   let winner = canonicalSet ? canonicalValue : undefined;
+  // THE PLATFORM'S SPELLING IS ALWAYS HEARD (task 1004573). The platform writes
+  // every hosted project's web.env as BONGOS_* whatever that project's own pack
+  // says. A project adopted from a repo whose config/branding.json still carried
+  // envPrefix CLOUDBONGOS read none of it — not its sign-in credentials, not its
+  // address, not one setting its owner chose — and nothing said so (mercury,
+  // 2026-10-04). So when the pack names another prefix, BONGOS_* is read right
+  // after it, ahead of the legacy list. The pack's own spelling still wins.
+  if (prefix && prefix !== FALLBACK_ENV_PREFIX) {
+    seen.add(FALLBACK_ENV_PREFIX);
+    const name = `${FALLBACK_ENV_PREFIX}_${suffix}`;
+    const v = env[name];
+    if (!canonicalSet && v !== undefined && v !== '') {
+      winner = v;
+      warnPack({ prefix, name });
+    }
+  }
   for (const pfx of legacy) {
     if (!pfx || seen.has(pfx)) continue;
     seen.add(pfx);
@@ -229,6 +245,17 @@ function warnLegacyEnv({ legacyName, canonicalName, shadowed, differs, log = con
   return true;
 }
 
+// One line per process when a value had to come from the platform's BONGOS_*
+// spelling because this project's pack names another prefix. Not a deprecation —
+// BONGOS_ is the canonical name — so it says what to change instead: the pack.
+let _packPrefixWarned = false;
+function warnPackPrefix({ prefix, name, log = console } = {}) {
+  if (_packPrefixWarned) return false;
+  _packPrefixWarned = true;
+  log.warn(`[bongos] config/branding.json sets envPrefix "${prefix}", but ${name} (the platform's spelling) is what is set — reading it. Set envPrefix to "${FALLBACK_ENV_PREFIX}" to match.`);
+  return true;
+}
+
 // NOT exported, deliberately: warnLegacyEnv, LEGACY_ENV_SUNSET_RELEASE and the
 // ledger are internals. resolveEnv's injectable `warn` is the whole test seam a
 // caller needs, and a test of the DEFAULT path captures console.warn — which

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.47'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.49'; // 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('discord'); log.info('mounted');

package/tests/bongos_cli.mjs

@@ -75,7 +75,8 @@ test('the server emits exactly the verb the CLI registers', () => {
   const cmds = [...tail.matchAll(/`([^`]*bongos paste-token[^`]*)`/g)].map((x) => x[1]);
   assert.ok(cmds.length > 0, 'auth.js should emit at least one paste_command template literal');
   for (const cmd of cmds) {
-    const verb = cmd.split(' ')[1];
+    // `npx bongos <verb> …` since task 1004575 — a clone has no bare `bongos` on PATH.
+    const verb = cmd.replace(/^npx /, '').split(' ')[1];
     assert.ok(cli.VERBS[verb], `server emits "bongos ${verb}" but the CLI has no such verb`);
   }
 });

package/tests/cli_allowlist_permissions.mjs

@@ -210,6 +210,10 @@ const GIT_GH_COMMANDS = [
   'git branch --list', 'git branch --show-current', 'git branch -a', 'git branch -vv',
   'git fetch', 'git fetch origin', 'git fetch origin main',
   'gh pr view:*', 'gh pr checks:*', 'gh pr list:*', 'gh run view:*', 'gh run list:*',
+  // Not git/gh, but the one non-script verb a session is handed to paste: Settings →
+  // CLI access gives `npx bongos paste-token <token>` (task 1004575), a blessed writer
+  // (see BLESSED_WRITERS) spelled the way a clone can run it.
+  'npx bongos paste-token:*',
 ];
 // gds CLIs audited read-only under EVERY flag they take — a prefix rule allows them all.
 // Audited and left OUT: backlog-review.js (POSTs from its default walk) and

package/tests/cli_token_reissue.mjs

@@ -176,8 +176,10 @@ t('paste_command names a CLI VERB, never a filesystem path', () => {
   const cmds = [...tail.matchAll(/`([^`]*bongos paste-token[^`]*)`/g)].map((m) => m[1]);
   assert.equal(cmds.length, 2, `expected both ternary branches, got ${cmds.length}`);
   for (const cmd of cmds) {
-  assert.ok(/^bongos paste-token /.test(cmd),
-    `paste_command must start with the verb form, got: ${cmd}`);
+  // Through npx (task 1004575): a builder's clone does not put bare `bongos` on
+  // PATH, so a bare verb was "command not found" when pasted in the project folder.
+  assert.ok(/^npx bongos paste-token /.test(cmd),
+    `paste_command must start with the npx verb form, got: ${cmd}`);
   // The invariant is "names no FILE ON THE RECIPIENT'S DISK", which the original
   // spelling approximated as "contains no slash". That was too broad once the command
   // had to carry the issuer URL (task 1003722) — `https://host` is not a filesystem
@@ -208,7 +210,7 @@ t('paste_command carries the issuing instance, so the CLI cannot guess wrong', (
 t('an instance that cannot state its own origin omits the flag rather than sending an empty one', () => {
   // `--api-base ''` would read at the far end as an explicit instruction and suppress
   // the fallback that works today — strictly worse than sending no flag at all.
-  assert.ok(/:\s*`bongos paste-token \$\{token\}`/.test(issueBlock),
+  assert.ok(/:\s*`npx bongos paste-token \$\{token\}`/.test(issueBlock),
     'there must be a flagless branch for the empty-issuer case');
 });