@bongos/core 1.17.0 → 1.17.1

package/scripts/gds/init.js

@@ -37,7 +37,7 @@
 // it refuses where config/branding.json exists, and --force OVERWRITES. `--adopt` is
 // the opposite: it LAYERS Cloud Bongos onto an EXISTING repo (app code, git history,
 // a package.json). It writes the lean config only where absent, adds the pinned
-// @cloudbongos/core dependency to the owner's package.json without touching any other
+// @bongos/core dependency to the owner's package.json without touching any other
 // field, and materializes .claude/ ADDITIVELY — for any pre-existing file it
 // MERGES-or-LEAVES-AND-REPORTS, it NEVER overwrites, and it does not reuse the --force
 // path. It deliberately does NOT seed a synthetic "V1 — Prove the loop": capturing the
@@ -56,11 +56,17 @@
 //   bongos init --dir <path>          target dir for the config files (default: cwd)
 //   bongos init --no-seed             write config only; skip the version/task seeding
 //   bongos init --force               overwrite existing config files (greenfield only; ignored by --adopt)
-//   bongos init --vendor-core <tgz>   greenfield only: vendor the @cloudbongos/core .tgz + pin
+//   bongos init --vendor-core <tgz>   greenfield only: vendor the @bongos/core .tgz + pin
 //                                       package.json to file:vendor/… + generate package-lock.json,
 //                                       so the scaffold is `npm ci`-installable (ADR 0108 gap 1/4).
-//                                       Without it the scaffold pins the caret range (unresolvable
-//                                       on npm today) — a local/dev scaffold you resolve another way.
+//                                       Without it the scaffold pins the caret range (which now
+//                                       resolves from the PRIVATE registry — see --registry-core).
+//   bongos init --registry-core       greenfield only: keep the caret pin + write an env-fed
+//                                       .npmrc (`_authToken=${NPM_TOKEN}`) so `npm ci` pulls the
+//                                       PRIVATE @bongos/core from the npm registry (ADR 0134).
+//                                       With NPM_TOKEN set it also generates package-lock.json;
+//                                       without a token it 404s (the expected tokenless outcome).
+//                                       Mutually exclusive with --vendor-core (registry vs tarball).
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -72,6 +78,7 @@ const { materializeClaude } = require('./claude-materialize'); // ADR 0108 §3 (
 const { detectStack, formatStackSummary } = require('./adopt-detect'); // ADR 0121 §Decision 4 (task 2043): inspect an existing repo before layering
 const { resolveBacklogTasks, DEFAULT_MAX: BACKLOG_MAX } = require('./adopt-import'); // ADR 0121 §Decision 3 (task 2044): import an existing backlog
 const { preflightAdopt, formatPreflight } = require('./adopt-preflight'); // ADR 0121 §Decision 5 (task 2045): the accept-gated conflict pre-flight
+const { writeNpmrc, hasNpmToken } = require('./npmrc'); // ADR 0134 (task 2090): the registry-install path's env-fed .npmrc
 
 const KNOWN_MODULES = ['game', 'art-pipeline', 'discord', 'dev-box'];
 
@@ -87,7 +94,7 @@ const HOSTING_SHAPES = ['co-tenant', 'dedicated', 'standalone'];
 // `bongos init --adopt` LAYERS this onto an existing repo's package.json; `bongos
 // upgrade` later re-pins it to a vendored `file:` tarball. Named so the adopt
 // layering and the upgrade re-pin agree on the dependency name.
-const CORE_PKG = '@cloudbongos/core';
+const CORE_PKG = '@bongos/core';
 
 const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
 
@@ -114,13 +121,13 @@ function coreVersionSafe() {
 // (`bash <core>/scripts/migrate.sh`). Keeping them identical means `npm start` /
 // `npm run migrate` on the instance behave like production, and `bongos upgrade`'s
 // `npm run migrate` step resolves to the core's migrate.sh (ADR 0108).
-const INSTANCE_CORE_PKG_DIR = 'node_modules/@cloudbongos/core';
+const INSTANCE_CORE_PKG_DIR = 'node_modules/@bongos/core';
 const INSTANCE_START_SCRIPT = `node ${INSTANCE_CORE_PKG_DIR}/src/platform-server.js`;
 const INSTANCE_MIGRATE_SCRIPT = `bash ${INSTANCE_CORE_PKG_DIR}/scripts/migrate.sh`;
 
 // PURE (exported for tests) — build/augment the greenfield instance package.json so a
 // fresh instance is `npm ci`-installable and runnable (ADR 0108 greenfield gap 1/4,
-// task 2053): the @cloudbongos/core dependency (the `file:` tarball pin when a tarball is
+// task 2053): the @bongos/core dependency (the `file:` tarball pin when a tarball is
 // vendored, else the declared caret range — the CARET RESOLVES NOWHERE on npm, which is
 // exactly why the vendored path pins `file:`) plus the start/migrate npm scripts a
 // standalone instance runs. Preserves any pre-existing fields + scripts (fills only what
@@ -258,7 +265,7 @@ function buildHierarchyConfig(spec) {
 }
 
 // PURE — layer the pinned core dependency into a parsed package.json (ADR 0121
-// §Decision 2 / task 2042). NEVER clobbers: if `@cloudbongos/core` is already a dep
+// §Decision 2 / task 2042). NEVER clobbers: if `@bongos/core` is already a dep
 // (in dependencies OR devDependencies) it returns the object untouched with
 // action:'present'; if there is no package.json at all it MINTS a minimal one
 // (action:'created'); otherwise it ADDS the dep, preserving every existing field and
@@ -466,7 +473,7 @@ async function interview({ adopt = false } = {}) {
     let provisioning;
     const wantProv = (await ask(rl, '  Provision production hosting now? (y/N)', 'N')).toLowerCase();
     if (wantProv === 'y' || wantProv === 'yes') {
-      const shape = (await ask(rl, '  Hosting shape? (co-tenant = share an existing box, $0 / dedicated = its own droplet / standalone = its own repo + pinned @cloudbongos/core, ADR 0108)', 'co-tenant')).toLowerCase();
+      const shape = (await ask(rl, '  Hosting shape? (co-tenant = share an existing box, $0 / dedicated = its own droplet / standalone = its own repo + pinned @bongos/core, ADR 0108)', 'co-tenant')).toLowerCase();
       const domain = await ask(rl, '  Domain you own — bring-your-own (blank = none yet)?');
       const targetRef = await ask(rl, '  Target credential ref? (which control-plane creds the runner should use; optional)');
       let tier = '';
@@ -579,7 +586,7 @@ function layerConfigs(spec, { dir, dryRun, log = console.log }) {
 }
 
 // `--adopt` package.json layering (ADR 0121 §Decision 2 / task 2042): add the
-// pinned @cloudbongos/core dependency to the owner's EXISTING package.json without
+// pinned @bongos/core dependency to the owner's EXISTING package.json without
 // touching any other field, or MINT a minimal one when the repo has none. When the
 // dep is already present the file is left byte-untouched (no reserialize). An
 // unparseable package.json is left alone with a report — adopt never risks
@@ -785,10 +792,15 @@ async function main(argv) {
   const adopt = hasFlag('--adopt', args); // brownfield: LAYER onto an existing repo (ADR 0121)
   const accept = hasFlag('--accept', args) || hasFlag('--yes', args) || hasFlag('-y', args); // adopt pre-flight accept-gate (§Decision 5)
   const vendorCore = arg('--vendor-core', args); // greenfield: vendor + file:-pin a core .tgz, then generate the lockfile (ADR 0108 gap 1/4, task 2053)
+  const registryCore = hasFlag('--registry-core', args); // greenfield: caret pin + env-fed .npmrc → `npm ci` pulls the PRIVATE core from the registry (ADR 0134, task 2090)
 
   if (adopt && force) {
     console.error('init: --force is a greenfield-only overwrite; --adopt never overwrites, so --force is ignored.');
   }
+  if (vendorCore && registryCore) {
+    console.error('init: --vendor-core and --registry-core are mutually exclusive — the vendored tarball and the registry pull are two ways to resolve the same core dependency. Pick one.');
+    return 1;
+  }
 
   let raw;
   if (fromPath) {
@@ -841,7 +853,7 @@ async function main(argv) {
   console.log(`\nScaffolding "${spec.identity.productName}"${dryRun ? '  (dry run — nothing will be written or created)' : ''}:`);
   writeConfigs(spec, { dir, force, dryRun, coreDep });
 
-  // Vendor the pinned @cloudbongos/core tarball + generate the lockfile so the scaffold is
+  // Vendor the pinned @bongos/core tarball + generate the lockfile so the scaffold is
   // `npm ci --omit=dev`-installable by the provisioner (ADR 0108 gap 1/4, task 2053). The
   // `npm install` here is the ONLY heavy step — it CREATES package-lock.json from the file:
   // tarball; the provisioner later runs `npm ci` against that committed lockfile.
@@ -849,14 +861,42 @@ async function main(argv) {
     if (dryRun) {
       console.log(`\n[dry-run] would vendor ${vendorPlan.tgz} → ${vendorPlan.vendorRel} and run \`npm install\` to generate package-lock.json`);
     } else {
-      console.log('\nVendoring the pinned @cloudbongos/core + generating the lockfile:');
+      console.log('\nVendoring the pinned @bongos/core + generating the lockfile:');
       upgrade.vendorTarball({ instanceDir: dir, fromTgz: vendorPlan.tgz, targetVersion: vendorPlan.version });
       console.log(`  ✓ vendored ${vendorPlan.vendorRel}`);
       const inst = upgrade.npmInstall(dir);
       if (!inst.ok) {
         console.error(`  ! npm install failed (${inst.reason || 'exit ' + inst.code}) — package-lock.json not generated; run \`npm install\` in ${dir} by hand before provisioning.`);
       } else {
-        console.log('  ✓ npm install → package-lock.json generated (node_modules/@cloudbongos/core installed)');
+        console.log('  ✓ npm install → package-lock.json generated (node_modules/@bongos/core installed)');
+      }
+    }
+  }
+
+  // Registry-install path (ADR 0134, task 2090): keep the caret pin writeConfigs wrote
+  // and add an env-fed .npmrc so `npm ci` pulls the PRIVATE @bongos/core from the
+  // registry. With NPM_TOKEN present we also generate package-lock.json (a reproducible
+  // `npm ci` later); without a token we still write the caret pin + .npmrc so the
+  // scaffold is registry-shaped, and say plainly that the private package 404s until a
+  // token is provided — the expected tokenless outcome the ADR calls to verify.
+  if (registryCore) {
+    if (dryRun) {
+      console.log(`\n[dry-run] would write .npmrc (env-fed @bongos auth) and ${hasNpmToken()
+        ? 'run `npm install` to generate package-lock.json from the registry'
+        : 'SKIP lockfile generation (no NPM_TOKEN — the private core 404s until one is provided)'}`);
+    } else {
+      console.log('\nWiring the registry-install path (ADR 0134):');
+      writeNpmrc(dir, { log: console.log });
+      if (hasNpmToken()) {
+        const inst = upgrade.npmInstall(dir);
+        if (!inst.ok) {
+          console.error(`  ! npm install failed (${inst.reason || 'exit ' + inst.code}) — confirm NPM_TOKEN reaches the private @bongos org; package-lock.json not generated.`);
+        } else {
+          console.log('  ✓ npm install → package-lock.json generated (pulled @bongos/core from the registry)');
+        }
+      } else {
+        console.log('  • no NPM_TOKEN in the environment — wrote the caret pin + .npmrc but skipped lockfile generation.');
+        console.log('    Provide a read-only automation token (paid `bongos` org) as NPM_TOKEN before `npm ci`; without it the private package 404s cleanly.');
       }
     }
   }

package/scripts/gds/migration-namespace.js

@@ -13,7 +13,7 @@
 //
 // DISCIPLINE. Every migration SOURCE owns a distinct filename namespace, so stems can
 // never collide across sources and each source's allocator counts only its own numbers:
-//   • CORE      (the @cloudbongos/core package's  migrations/*.sql)        → core_NNN_slug.sql
+//   • CORE      (the @bongos/core package's  migrations/*.sql)        → core_NNN_slug.sql
 //   • MODULE    (modules/<key>/migrations/*.sql)                           → <key>_NNN_slug.sql   (key: dev-box → dev_box_)
 //   • INSTANCE  (the host repo's                   migrations/instance/*.sql) → NNN_slug.sql        (BARE — the instance owns the bare namespace)
 //

package/scripts/gds/module.js

@@ -351,6 +351,40 @@ function recordSignOff(key, signedBy, { modulesDir = MODULES_DIR } = {}) {
   return { ...record, path: path.relative(REPO_ROOT, file) };
 }
 
+// Reads a previously-recorded sign-off (recordSignOff above), or null if the
+// module has never been signed off. Never throws on a missing/garbled file —
+// "no sign-off yet" is the expected common case, not an error.
+function readSignOff(key, { modulesDir = MODULES_DIR } = {}) {
+  return readJson(path.join(modulesDir, key, '.upstream-signoff.json'));
+}
+
+// ---------------------------------------------------------------------------
+// bongos module submit <key> — ADR 0107 §1 upstreaming submission
+// ---------------------------------------------------------------------------
+
+// Packages a module for the upstreaming queue: its manifest + a full file
+// snapshot (base64, so binary assets round-trip identically) + whatever
+// sign-off is on disk. Pure fs read — no pre-check, no network; the caller
+// (cmdSubmit locally, the POST /modules/:key/submit route server-side) is
+// responsible for having already run checkModulePublishability() and for
+// deciding whether a missing sign-off is fatal.
+function packageModuleForSubmission(key, { modulesDir = MODULES_DIR } = {}) {
+  const dir = path.join(modulesDir, key);
+  const manifest = readJson(path.join(dir, 'module.json'));
+  if (!manifest) throw new Error(`modules/${key}/module.json missing or unreadable`);
+  let totalBytes = 0;
+  const files = listModuleFiles(dir)
+    .map((abs) => {
+      const rel = path.relative(dir, abs).split(path.sep).join('/');
+      const buf = fs.readFileSync(abs);
+      totalBytes += buf.length;
+      return { path: rel, contentBase64: buf.toString('base64'), bytes: buf.length };
+    })
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const signOff = readSignOff(key, { modulesDir });
+  return { key, manifest, files, totalBytes, signOff };
+}
+
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
@@ -445,6 +479,79 @@ function cmdCheck(args, { log = console.log, errlog = console.error, check = che
   return 0;
 }
 
+// `bongos module submit <key>` — ADR 0107 §1. Runs the §4 pre-check + requires
+// a sign-off (locally, for fast refusal without a network round trip), then
+// POSTs to POST /modules/:key/submit — the SAME route the hall "Modules" tab's
+// submit button calls (src/bongos/routes/modules.js). That route re-runs the
+// pre-check against ITS OWN on-disk copy of the module and is the authoritative
+// gate: a local pass here is a courtesy, not a guarantee, if the module's
+// changes aren't committed + shipped + deployed yet.
+async function cmdSubmit(args, {
+  log = console.log, errlog = console.error,
+  check = checkModulePublishability, sign = recordSignOff, readSign = readSignOff,
+  submit,
+} = {}) {
+  const key = args.find((a) => !a.startsWith('-'));
+  if (!key) {
+    errlog('usage: bongos module submit <key> [--sign-off "Name <email>"]');
+    return 2;
+  }
+  const signIdx = args.indexOf('--sign-off');
+  const signedBy = signIdx !== -1 ? args[signIdx + 1] : null;
+
+  log(`bongos module submit — upstreaming "${key}" (ADR 0107 §1)`);
+
+  let result;
+  try { result = check(key); }
+  catch (e) { errlog(`bongos module submit: ${e.message}`); return 1; }
+
+  if (!result.ok) {
+    for (const f of result.findings) errlog(`  ✗ ${f.kind}: ${f.detail}`);
+    errlog(`\nREFUSING: "${key}" is not clear to submit upstream. Fix the finding(s) above and re-run.`);
+    return 1;
+  }
+  log('  ✓ AGPL/publish pre-check passed.');
+
+  let signOff = readSign(key);
+  if (!signOff && signedBy) {
+    const record = sign(key, signedBy);
+    log(`  ✓ Sign-off recorded — ${record.path}`);
+    signOff = readSign(key);
+  }
+  if (!signOff) {
+    errlog(`\nREFUSING: no DCO-style sign-off on file for "${key}". Pass --sign-off "Name <email>" (or run \`bongos module check ${key} --sign-off "Name <email>"\` first).`);
+    return 1;
+  }
+  log(`  ✓ Sign-off on file — "${signOff.signOff.signedBy}", ${signOff.signOff.date}.`);
+
+  const doSubmit = submit || (async (k, body) => {
+    // Lazy require: cli-lib.js carries session/fetch plumbing that must NEVER
+    // load into the always-on server process — this file is also required by
+    // src/bongos/routes/modules.js for the pre-check it reuses. A real network
+    // call only happens when a human/agent actually invokes this CLI command.
+    const { cliClient, requireSession } = require('./cli-lib');
+    await requireSession();
+    const api = await cliClient();
+    return api.modules.postModulesKeySubmit({ key: k, body });
+  });
+
+  let res;
+  try { res = await doSubmit(key, { signed_by: signedBy || undefined }); }
+  catch (e) { errlog(`bongos module submit: request failed — ${e.message}`); return 1; }
+
+  if (!res.ok) {
+    const detail = (res.data && (res.data.message || res.data.error)) || JSON.stringify(res.data);
+    errlog(`\nREFUSING: the review queue rejected the submission (HTTP ${res.status}): ${detail}`);
+    if (res.status === 422) errlog('(the server re-runs the pre-check/sign-off check against its OWN deployed copy — commit + ship first if this module has local-only changes.)');
+    return 1;
+  }
+
+  const submission = res.data && res.data.submission;
+  log(`\n✓ Filed — submission id ${submission ? submission.id : '?'} for "${key}", status ${submission ? submission.status : 'pending'}.`);
+  log('Task 1771 (core-side review & accept flow) picks it up from here.');
+  return 0;
+}
+
 function printHelp(out = console.log) {
   out('bongos module — scaffold + manage Cloud Bongos modules\n');
   out('Usage:');
@@ -452,14 +559,17 @@ function printHelp(out = console.log) {
   out('  bongos upgrade              Pre-check enabled modules against the core version (fail-closed)');
   out('  bongos module check <key> [--sign-off "Name <email>"]');
   out('                              AGPL/publish pre-check before upstreaming + record a DCO-style sign-off');
+  out('  bongos module submit <key> [--sign-off "Name <email>"]');
+  out('                              Pre-check + sign-off, then file into the rank-gated upstreaming review queue');
 }
 
-function main(argv) {
+async function main(argv) {
   const args = argv.slice(2);
   const sub = args[0];
   if (sub === 'new') return cmdNew(args.slice(1));
   if (sub === 'upgrade') return cmdUpgrade(args.slice(1));
   if (sub === 'check') return cmdCheck(args.slice(1));
+  if (sub === 'submit') return cmdSubmit(args.slice(1));
   if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
     printHelp();
     return sub ? 0 : 2;
@@ -470,13 +580,17 @@ function main(argv) {
 }
 
 module.exports = {
-  main, cmdNew, cmdUpgrade, cmdCheck, printHelp,
+  main, cmdNew, cmdUpgrade, cmdCheck, cmdSubmit, printHelp,
   scaffoldModule, gatherUpgrade, evaluateUpgrade, buildManifest,
-  checkModulePublishability, recordSignOff, DCO_STATEMENT,
+  checkModulePublishability, recordSignOff, readSignOff, DCO_STATEMENT,
+  listModuleFiles, packageModuleForSubmission,
   routeTemplate, claudeMdTemplate, titleize, camel, coreVersion,
   MODULES_DIR,
 };
 
 if (require.main === module) {
-  process.exit(main(process.argv));
+  Promise.resolve(main(process.argv)).then(
+    (code) => process.exit(code),
+    (e) => { console.error(e); process.exit(1); }
+  );
 }

package/scripts/gds/npmrc.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/gds/npmrc.js — env-fed `.npmrc` for installing the PRIVATE @bongos/* core
+// from the npm registry (ADR 0134, task 2090). The single place that knows the
+// registry host + scope + the `.npmrc` shape + the opt-in/token gates, shared by:
+//   • init.js       — the greenfield `--registry-core` scaffold
+//   • provision.js  — the standalone scaffold's registry path (opt-in, fail-soft)
+//   • upgrade.js     — the `--registry <version>` update channel
+//
+// WHY private + env-fed. `@bongos/core` publishes as a SCOPED, PRIVATE package (ADR
+// 0134): a private scoped package can only be installed with auth. Consumers
+// authenticate with an `.npmrc` whose token EXPANDS FROM THE ENVIRONMENT at install
+// time (`_authToken=${NPM_TOKEN}`) — so the committed file carries NO secret, and a
+// tokenless install 404s cleanly (the expected pre-launch outcome).
+//
+// The vendored-tarball path (task 2053) stays the DEFAULT/fallback until this registry
+// path is proven end-to-end on a real greenfield standup (ADR 0134 §Consequences).
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REGISTRY_HOST = 'registry.npmjs.org';
+const CORE_SCOPE = '@bongos'; // the paid, canonical npm org (ADR 0134 scope correction, task 2092)
+const TOKEN_ENV = 'NPM_TOKEN';
+const REQUEST_ENV = 'PROVISION_CORE_FROM_REGISTRY';
+
+// The `.npmrc` a scaffolded instance commits. The token is the LITERAL `${NPM_TOKEN}`
+// (npm expands env vars in `.npmrc` values at read time), so the file is safe to
+// commit — it holds no secret. Scoping @bongos to the registry keeps every unrelated
+// install on the default public registry.
+function npmrcContent({ scope = CORE_SCOPE, host = REGISTRY_HOST, tokenEnv = TOKEN_ENV } = {}) {
+  return [
+    `; Cloud Bongos — env-fed auth for the PRIVATE ${scope}/* packages (ADR 0134, task 2090).`,
+    `; The token EXPANDS FROM THE ENVIRONMENT at install time; nothing secret is committed here.`,
+    `; \`npm ci\` needs ${tokenEnv} set (a read-only automation token from the paid \`bongos\` org);`,
+    `; without it the private package 404s — that is the expected tokenless outcome.`,
+    `${scope}:registry=https://${host}/`,
+    `//${host}/:_authToken=\${${tokenEnv}}`,
+    '',
+  ].join('\n');
+}
+
+// Is a registry token present in the environment? The fail-soft gate: provisioning
+// falls back to the vendored tarball when this is false, so a tokenless standup still
+// works (never a broken instance).
+function hasNpmToken(env = process.env) {
+  return !!String(env[TOKEN_ENV] || '').trim();
+}
+
+// Has the operator opted the standalone scaffold into the registry path? OFF by
+// default — the vendored tarball stays the default until the registry path is proven
+// end-to-end (ADR 0134). '1'/'true'/'yes'/'on' (case-insensitive) → true.
+function registryCoreRequested(env = process.env) {
+  return /^(1|true|yes|on)$/i.test(String(env[REQUEST_ENV] || '').trim());
+}
+
+// Write the env-fed `.npmrc` into an instance dir. Default overwrites (a greenfield
+// scaffold owns the file); pass overwrite:false to leave a pre-existing `.npmrc`
+// untouched (an upgrade must not clobber a consumer's other registries). Returns the
+// path (or null when skipped). Dry-run writes nothing.
+function writeNpmrc(dir, { fsImpl = fs, dryRun = false, overwrite = true, log = () => {} } = {}) {
+  const p = path.join(dir, '.npmrc');
+  if (!overwrite && fsImpl.existsSync(p)) {
+    log(`  • .npmrc already present — left untouched (add \`${CORE_SCOPE}:registry\` + \`_authToken=\${${TOKEN_ENV}}\` if the private core doesn't resolve).`);
+    return null;
+  }
+  if (dryRun) {
+    log(`  [dry-run] would write ${p} (env-fed ${CORE_SCOPE} auth; token via $${TOKEN_ENV}, never committed)`);
+    return p;
+  }
+  fsImpl.writeFileSync(p, npmrcContent());
+  log(`  ✓ wrote .npmrc (env-fed ${CORE_SCOPE} auth; token via $${TOKEN_ENV}, never committed)`);
+  return p;
+}
+
+module.exports = {
+  REGISTRY_HOST, CORE_SCOPE, TOKEN_ENV, REQUEST_ENV,
+  npmrcContent, hasNpmToken, registryCoreRequested, writeNpmrc,
+};
+
+// Tiny CLI: `node scripts/gds/npmrc.js [--print | --write <dir>]` — print the `.npmrc`
+// body or materialize it into <dir>. Handy for a manual registry-standup rehearsal.
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const writeIdx = args.indexOf('--write');
+  if (writeIdx !== -1 && args[writeIdx + 1]) {
+    const p = writeNpmrc(path.resolve(args[writeIdx + 1]), { log: console.log });
+    process.stdout.write(`${p}\n`);
+  } else {
+    process.stdout.write(npmrcContent());
+  }
+}

package/scripts/gds/onboard.js

@@ -22,28 +22,12 @@ const oauth = require(path.join(__dirname, 'oauth-secret.js'));     // validateC
 
 // ── PURE core (exported for tests) ───────────────────────────────────────────
 
-// The canonical step sequence — the SINGLE source of truth the skill + hall wizard
-// mirror. `kind: 'human'` steps are the irreducibly-manual ones (UI-first prompts).
-// The sequence branches at exactly ONE leg — scaffold — into greenfield (`bongos init`,
-// a fresh empty repo) vs brownfield (`bongos init --adopt`, LAYER onto an existing repo;
-// ADR 0121 §Decision 1 / task 2046). Every other leg is identical, so passing `mode`
-// only relabels the github-repo / init / scaffold steps.
-function onboardPlan(mode = 'greenfield') {
-  const adopt = mode === 'adopt';
-  return [
-    { key: 'name-address', kind: 'auto', label: 'Decide name + address (interview)' },
-    { key: 'github-repo', kind: 'human', label: adopt ? 'Use your EXISTING GitHub repository' : 'Create the empty GitHub repository' },
-    { key: 'dns-preflight', kind: 'auto', label: 'DNS token preflight — before the address step (task 1980)' },
-    { key: 'init', kind: 'auto', label: adopt ? 'bongos init --adopt — LAYER onto the existing repo (pre-flight + accept)' : 'bongos init — scaffold the instance config' },
-    { key: 'scaffold', kind: 'auto', label: adopt ? 'Layer config + pinned @cloudbongos/core onto the existing repo (no clobber)' : 'Scaffold the standalone repo (own repo + pinned @cloudbongos/core)' },
-    { key: 'provision', kind: 'auto', label: 'Provision core + DB + address + service (standalone, task 1978)' },
-    { key: 'oauth-app', kind: 'human', label: 'Wire GitHub sign-in — one-click GitHub App (task 2080), or a manual OAuth app' },
-    { key: 'oauth-place', kind: 'auto', label: 'Place the OAuth secret — auto via the Manifest flow, or verified manual (task 1979)' },
-    { key: 'first-sign-in', kind: 'human', label: 'First sign-in (seats the founding Archon)' },
-    { key: 'verify', kind: 'auto', label: 'Verify /healthz auth_configured' },
-    { key: 'brand', kind: 'auto', label: 'Brand the instance look' },
-  ];
-}
+// The canonical step sequence now lives in ONE place — the provisioning module — so the
+// CLI (here), the branded /create page, and the hall wizard can't drift (task 2085; goal
+// 35 / criterion 165: "the canonical step sequence is the source of truth; skill/CLI/hall
+// are forms over it"). The web forms read it over GET /provisioning/onboard-plan; the CLI
+// requires it directly. Re-exported below so `bongos onboard` + tests keep the same API.
+const { onboardPlan } = require(path.join(__dirname, '..', '..', 'modules', 'provisioning', 'onboard-plan.js'));
 
 // The exact GitHub OAuth-app values for a domain. The callback is PINNED to the apex
 // /api/gds/auth/web/callback (auth.js WEB_REDIRECT_ORIGIN — a sign-in begun on a
@@ -54,6 +38,10 @@ function oauthAppInstructions(domain) {
     location: "GitHub → your ACCOUNT's Settings → Developer settings → OAuth Apps → New OAuth App",
     homepageUrl: origin,
     callbackUrl: `${origin}/api/gds/auth/web/callback`,
+    // GitHub disables Device Flow on a new OAuth App by DEFAULT, but the terminal
+    // `bongos login` uses it — leaving it off makes CLI sign-in fail with
+    // device_flow_disabled (the 2026-07-08 demo login-500). Must be enabled. (task 2127)
+    enableDeviceFlow: 'Check "Enable Device Flow" on the app page and save — off by default; the terminal `bongos login` needs it.',
   };
 }
 
@@ -149,13 +137,13 @@ async function run() {
     // Step 5 — the standalone repo (greenfield scaffolds it; adopt already layered it in ③)
     if (adopt) {
       log('\n④ Your repo is now the standalone instance (ADR 0108):');
-      log('   `bongos init --adopt` already layered config/ + .claude/ + the pinned @cloudbongos/core dep onto it.');
+      log('   `bongos init --adopt` already layered config/ + .claude/ + the pinned @bongos/core dep onto it.');
       log(`   Commit + push ${a.repoOwner}/${a.repoName}. That checkout is what the service runs.`);
       await ask(rl, 'Press Enter once the layered repo is committed + pushed…');
     } else {
       log('\n④ Scaffold the STANDALONE repo (ADR 0108):');
       log(`   Clone ${a.repoOwner}/${a.repoName} to the control-plane standalone root, add the config/ + .claude/`);
-      log('   from init, pin @cloudbongos/core in its package.json, commit + push. That checkout is what the service runs.');
+      log('   from init, pin @bongos/core in its package.json, commit + push. That checkout is what the service runs.');
       await ask(rl, 'Press Enter once the standalone repo is pushed…');
     }
 
@@ -180,6 +168,7 @@ async function run() {
       log('   (Developer settings is under your ACCOUNT, not the repository.)');
       log(`   Homepage URL:              ${oa.homepageUrl}`);
       log(`   Authorization callback URL: ${oa.callbackUrl}`);
+      log(`   Enable Device Flow:        ✅  ${oa.enableDeviceFlow}`);
       log('   Copy the Client ID; Generate a new client secret and copy it (shown once).');
       const clientId = await ask(rl, 'Paste the OAuth Client ID:');
       const clientSecret = await ask(rl, 'Paste the OAuth Client Secret:');