@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/oauth-secret.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/bongos/oauth-secret.js — SHELL-INDEPENDENT, VERIFIED placement of a
+// provisioned instance's GitHub OAuth App credentials (BONGOS-V1 goal 35, task 1979).
+//
+// WHY. During the Emersonian standup the manual hidden-input shell command used to
+// place the GitHub OAuth client secret failed SILENTLY on the server shell, leaving a
+// 26-char truncated value in web.env that broke sign-in with no obvious cause. The
+// onboarding flow needs a secret-placement step that is:
+//   (1) SHELL-INDEPENDENT — a Node rewrite of the specific env line, never a fragile
+//       `read -s`/`sed -i` that can truncate or silently no-op;
+//   (2) VALIDATED before it is written — length + charset checks that CATCH the 26-char
+//       truncation the runtime auth_configured probe MISSES (authConfigured() only
+//       checks PRESENCE, not validity — a truncated-but-present secret passes it);
+//   (3) VERIFIED after the service restarts — probe GET /healthz and assert
+//       auth_configured:true, so onboarding never "proceeds" past broken auth.
+// It APPLIES TO EVERY FORM of the flow — the /new-project skill (task 1981), the
+// `bongos onboard` CLI (task 1982), and the hall wizard (task 1983) drive it.
+//
+// Control-plane tool (like provision.js): it rewrites /etc/<slug>/web.env (chmod 600)
+// and restarts the instance's systemd unit, so it runs on the box, never the web tier.
+// DRY-RUN by DEFAULT: without --apply it validates + prints the plan and mutates nothing.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const cp = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+// Mirrors provision.js conventions (kept in lockstep — ADR 0111 / provision.js).
+const ETC_BASE = process.env.PROVISION_ETC_BASE || '/etc';
+const PROVISIONED_BRANDING_FILE = 'config/branding.neutral.json';
+
+// A GitHub OAuth App client SECRET is a 40-char hex string (classic); GitHub may issue
+// longer. Require a sane MINIMUM (catches the 26-char truncation) + a charset no real
+// secret violates; do NOT hard-cap length.
+const SECRET_MIN_LEN = 40;
+// A client ID: classic 20 hex chars, or an 'Iv1.'/'Iv23'/'Ov23' App prefix.
+const CLIENT_ID_MIN_LEN = 20;
+const PLACEHOLDER_RE = /^(x{3,}|placeholder|change[-_]?me|todo|your[-_]?(client[-_]?)?(id|secret))$/i;
+
+function validateClientSecret(secret) {
+  const s = String(secret == null ? '' : secret).trim();
+  if (!s) return { ok: false, reason: 'empty — no client secret provided' };
+  if (PLACEHOLDER_RE.test(s)) return { ok: false, reason: `looks like a placeholder ("${s.slice(0, 16)}")` };
+  if (s.length < SECRET_MIN_LEN) return { ok: false, reason: `too short (${s.length} chars; a GitHub OAuth client secret is ≥ ${SECRET_MIN_LEN}) — likely truncated by a silent shell failure (the task-1979 bug)` };
+  if (!/^[A-Za-z0-9._-]+$/.test(s)) return { ok: false, reason: 'contains characters no GitHub client secret uses (whitespace/quotes?) — likely a bad paste' };
+  return { ok: true };
+}
+
+function validateClientId(id) {
+  const s = String(id == null ? '' : id).trim();
+  if (!s) return { ok: false, reason: 'empty — no client id provided' };
+  if (PLACEHOLDER_RE.test(s)) return { ok: false, reason: `looks like a placeholder ("${s.slice(0, 16)}")` };
+  if (s.length < CLIENT_ID_MIN_LEN) return { ok: false, reason: `too short (${s.length} chars; a GitHub OAuth client id is ≥ ${CLIENT_ID_MIN_LEN})` };
+  if (!/^[A-Za-z0-9._]+$/.test(s)) return { ok: false, reason: 'contains unexpected characters — likely a bad paste' };
+  return { ok: true };
+}
+
+// The env-var prefix the provisioned instance resolves (the neutral pack's envPrefix,
+// mirroring provision.js provisionedEnvPrefix — the creds MUST be written under this
+// prefix or src/branding + auth never read them, task 1972). Fail-soft to the
+// core's own FALLBACK_ENV_PREFIX so this cannot drift from the pack again — it
+// was a hardcoded 'CLOUDBONGOS' until task 1003703 made BONGOS canonical.
+function provisionedEnvPrefix() {
+  const { FALLBACK_ENV_PREFIX } = require('../../src/instance-config');
+  try {
+    const pack = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, PROVISIONED_BRANDING_FILE), 'utf8'));
+    return pack.envPrefix || FALLBACK_ENV_PREFIX;
+  } catch { return FALLBACK_ENV_PREFIX; }
+}
+
+function webEnvPath(slug, { etcBase = ETC_BASE } = {}) {
+  return path.posix.join(etcBase, slug, 'web.env');
+}
+
+// Rewrite the CLIENT_ID / CLIENT_SECRET lines of a web.env body IN PLACE, matching the
+// pack's env prefix. PURE string transform — this IS the shell-independent placement
+// (no `read -s`, no `sed -i`). THROWS if a target key line is absent, so a
+// mismatched-prefix web.env can never silently no-op (the failure mode task 1979 hits).
+function fillOAuthEnv(body, { prefix, clientId, clientSecret }) {
+  const esc = (k) => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const setKey = (text, key, value) => {
+    const re = new RegExp(`^(${esc(key)})=.*$`, 'm');
+    if (!re.test(text)) throw new Error(`web.env has no "${key}=" line to fill (env-prefix mismatch?)`);
+    return text.replace(re, `$1=${value}`);
+  };
+  let out = body;
+  if (clientId != null) out = setKey(out, `${prefix}_GITHUB_CLIENT_ID`, clientId);
+  if (clientSecret != null) out = setKey(out, `${prefix}_GITHUB_CLIENT_SECRET`, clientSecret);
+  return out;
+}
+
+// The PORT= line a web.env carries (provision.js writes it) — the healthz probe target.
+function portFromEnv(body) {
+  const m = /^PORT=(\d+)$/m.exec(String(body || ''));
+  return m ? Number(m[1]) : null;
+}
+
+// Parse the /healthz JSON the post-restart probe returns → { ok, authConfigured }.
+function parseHealthzAuth(stdout) {
+  try {
+    const j = JSON.parse(String(stdout || '').trim());
+    return { ok: j.ok !== false, authConfigured: j.auth_configured === true };
+  } catch { return { ok: false, authConfigured: false, parseError: true }; }
+}
+
+// ---------------------------------------------------------------------------
+// CLI: place <slug> --client-id ID --client-secret SECRET [--apply] [--port N]
+// ---------------------------------------------------------------------------
+function argVal(args, name) { const i = args.indexOf(name); return i >= 0 && i + 1 < args.length ? args[i + 1] : null; }
+
+function usage() {
+  console.log(`oauth-secret.js — verified, shell-independent OAuth-secret placement (ADR 0111, task 1979)
+
+Usage:
+  node scripts/bongos/oauth-secret.js place <slug> --client-id <id> --client-secret <secret> [--apply] [--port <n>]
+
+Validates the creds (length/format — CATCHES the silent-truncation bug), rewrites the
+CLIENT_ID/CLIENT_SECRET lines of /etc/<slug>/web.env via Node (no fragile shell input),
+restarts the instance's systemd unit, then PROBES /healthz to confirm auth_configured.
+DRY-RUN by default; --apply performs the write + restart + probe on the control plane.`);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+  if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') { usage(); process.exit(0); }
+  if (cmd !== 'place') { console.error(`unknown command: ${cmd}\n`); usage(); process.exit(2); }
+  const slug = args[1] && !args[1].startsWith('--') ? args[1] : null;
+  if (!slug) { console.error('place needs a <slug>'); process.exit(2); }
+  const apply = args.includes('--apply');
+  const clientId = argVal(args, '--client-id');
+  const clientSecret = argVal(args, '--client-secret');
+
+  // (1) VALIDATE before touching anything — the truncation guard.
+  const idV = validateClientId(clientId);
+  const secV = validateClientSecret(clientSecret);
+  const problems = [];
+  if (!idV.ok) problems.push(`client id: ${idV.reason}`);
+  if (!secV.ok) problems.push(`client secret: ${secV.reason}`);
+  if (problems.length) {
+    console.error('✖ OAuth creds rejected before placement (nothing written):');
+    for (const p of problems) console.error(`   - ${p}`);
+    process.exit(2);
+  }
+  console.log('✓ creds validated (length + charset)');
+
+  const prefix = provisionedEnvPrefix();
+  const envPath = webEnvPath(slug);
+  let body;
+  try { body = fs.readFileSync(envPath, 'utf8'); }
+  catch (e) { console.error(`cannot read ${envPath}: ${e.message} — is ${slug} provisioned on this control plane?`); process.exit(1); }
+
+  // (2) SHELL-INDEPENDENT placement — rewrite the specific env lines via Node.
+  let next;
+  try { next = fillOAuthEnv(body, { prefix, clientId, clientSecret }); }
+  catch (e) { console.error(`✖ ${e.message}`); process.exit(1); }
+
+  const port = argVal(args, '--port') ? Number(argVal(args, '--port')) : portFromEnv(next);
+
+  if (!apply) {
+    console.log(`[dry-run] would rewrite ${envPath} (${prefix}_GITHUB_CLIENT_ID/_SECRET), chmod 600`);
+    console.log(`[dry-run] would restart systemd unit ${slug}, then probe http://127.0.0.1:${port || '<port>'}/healthz for auth_configured`);
+    console.log('re-run with --apply to place + verify.');
+    process.exit(0);
+  }
+
+  fs.writeFileSync(envPath, next, { mode: 0o600 });
+  fs.chmodSync(envPath, 0o600);
+  console.log(`✓ wrote ${envPath} (chmod 600)`);
+  cp.execSync(`systemctl restart ${slug}`, { stdio: 'inherit' });
+  console.log(`✓ restarted ${slug}`);
+
+  // (3) VERIFY — probe the JSON health answer for auth_configured (retry briefly for
+  // restart). /api/bongos/healthz, not the root /healthz, which answers a plain "ok"
+  // that never parses (task 1004577).
+  if (!port) { console.error('✖ no PORT in web.env and no --port given — cannot probe /healthz'); process.exit(1); }
+  let probe = { authConfigured: false };
+  for (let i = 0; i < 10; i++) {
+    try {
+      const out = cp.execSync(`curl -sS --max-time 5 http://127.0.0.1:${port}/api/bongos/healthz`, { stdio: ['ignore', 'pipe', 'pipe'] }).toString();
+      probe = parseHealthzAuth(out);
+      if (probe.ok || probe.authConfigured) break;
+    } catch { /* not up yet */ }
+    cp.execSync('sleep 1');
+  }
+  if (!probe.authConfigured) {
+    console.error(`✖ post-restart probe: /healthz reports auth_configured=false — the instance still cannot authenticate. Do NOT proceed; recheck the OAuth app creds.`);
+    process.exit(1);
+  }
+  console.log('✓ verified: /healthz reports auth_configured=true — sign-in is live');
+  process.exit(0);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  SECRET_MIN_LEN, CLIENT_ID_MIN_LEN,
+  validateClientSecret, validateClientId,
+  provisionedEnvPrefix, webEnvPath, fillOAuthEnv, portFromEnv, parseHealthzAuth,
+};

package/scripts/bongos/onboard.js

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/bongos/onboard.js — `bongos onboard`: the interactive CLI FORM over the
+// canonical onboarding runbook (BONGOS-V1 goal 35, task 1982). Self-serve for a
+// terminal-comfortable owner; drives the SAME step sequence the /new-project skill
+// (task 1981) defines and the hall wizard (task 1983) renders — so all three stay in
+// lockstep. It EXTENDS `bongos init` (which only writes config) with the scaffold →
+// provision → OAuth → verify → brand legs. Standalone model only (ADR 0108).
+//
+// It automates what it can (DNS token preflight, OAuth-cred validation, /healthz
+// verify) and renders the irreducibly-human steps (create the GitHub repo, the
+// OAuth app + secret, install the App on the repo, own the domain, first sign-in)
+// as precise, copy-paste-safe prompts. It does NOT hold cloud tokens: the actual provision runs on the control
+// plane (it prints the exact `provision.js` command), preserving the trust boundary.
+
+const readline = require('node:readline');
+const path = require('node:path');
+
+const provision = require(path.join(__dirname, 'provision.js'));   // checkDnsTokenScope, zoneForDomain
+const oauth = require(path.join(__dirname, 'oauth-secret.js'));     // validateClientId/Secret
+
+// ── PURE core (exported for tests) ───────────────────────────────────────────
+
+// The canonical step sequence now lives in ONE place — the provisioning module — so the
+// CLI (here) and the hub's ?view=new 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
+// builders. subdomain still calls back to the apex). PURE.
+function oauthAppInstructions(domain) {
+  const origin = `https://${domain}`;
+  return {
+    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.',
+  };
+}
+
+// Build the `bongos init` spec from the interview answers (standalone shape). PURE.
+function buildInitSpec(a = {}) {
+  const spec = {
+    identity: { productName: a.productName, worldName: a.worldName || a.productName, company: a.company ? { name: a.company } : {} },
+    repo: { owner: a.repoOwner, name: a.repoName },
+    firstAdmin: a.firstAdmin || a.repoOwner,
+    version: { id: a.versionId || 'V1', name: a.versionName || `${a.versionId || 'V1'} — Prove the loop`, done_when: a.doneWhen || 'The loop is proven end-to-end.' },
+  };
+  if (a.domain) spec.domains = { publicOrigin: `https://${a.domain}` };
+  if (a.domain || a.slug) spec.provisioning = { shape: 'cloud-host', domain: a.domain || null, slug: a.slug || null };
+  return spec;
+}
+
+function healthzUrl(domain) { return `https://${domain}/healthz`; }
+
+// The optional project-detail step's answers, as the CLI collects them (task
+// 1002334) — the same shape POST /provisioning/instances takes, so the terminal
+// form and the web wizard file identical requests. A blank answer is a SKIP, and a
+// skip is a supported default: the project stands up, it just stays off the map
+// until a description exists (ADR 0182 D4). Off-vocabulary team answers are dropped
+// rather than guessed — the server's normalizeProjectDetail applies the same rule.
+// PURE.
+const TEAM_SHAPES = ['solo', 'small-team', 'community'];
+function buildProjectDetail(a = {}) {
+  const out = {};
+  const told = typeof a.description === 'string' ? a.description.replace(/\s+/g, ' ').trim() : '';
+  if (told) out.description = told;
+  const team = String(a.teamShape || '').trim().toLowerCase();
+  if (TEAM_SHAPES.includes(team)) out.detail = { team_shape: team };
+  return out;
+}
+
+// ── Interactive shell ────────────────────────────────────────────────────────
+
+function ask(rl, q, dflt) {
+  const suffix = dflt ? ` [${dflt}]` : '';
+  return new Promise((res) => rl.question(`  ${q}${suffix} `, (ans) => res((ans || '').trim() || dflt || '')));
+}
+
+async function run() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const log = (m = '') => console.log(m);
+  try {
+    log('\nbongos onboard — stand up a STANDALONE Cloud Bongos instance (ADR 0108).');
+    log('The canonical sequence; the /new-project skill + hall wizard drive the same steps.\n');
+
+    // Greenfield vs adopt — the one branch in the sequence (ADR 0121 §Decision 1). Greenfield
+    // scaffolds a fresh empty repo; adopt LAYERS onto an existing repo (its own pre-flight + accept).
+    const modeAns = (await ask(rl, 'Greenfield (a NEW empty repo) or adopt (an EXISTING repo)?', 'greenfield')).toLowerCase();
+    const adopt = modeAns.startsWith('a');
+    const a = { mode: adopt ? 'adopt' : 'greenfield' };
+
+    // Step 1 — name + address
+    a.productName = await ask(rl, 'Product name?');
+    a.worldName = await ask(rl, 'World name?', a.productName);
+    a.company = await ask(rl, 'Company (optional)?');
+    a.repoOwner = await ask(rl, 'GitHub repo owner?');
+    a.repoName = await ask(rl, 'GitHub repo name?');
+    a.firstAdmin = await ask(rl, 'First admin (GitHub login — the founding Archon)?', a.repoOwner);
+    a.slug = await ask(rl, 'Instance slug? (DNS/db-safe, e.g. mercury)');
+    a.domain = await ask(rl, 'Domain you own (bring-your-own; blank = the platform assigns <slug>.<its apex> when configured)?');
+
+    // Step 1b — the OPTIONAL project detail (task 1002334). Every form in the
+    // sequence offers it and every owner may skip it: Enter past both questions and
+    // the standup is unaffected. Say what skipping costs BEFORE asking, so the skip
+    // is an informed choice rather than a shrug — a project with no description
+    // stays off the map (ADR 0182 D4) and `bongos` can recommend nothing.
+    log('\nTell us about your project — optional. Press Enter to skip either question.');
+    log('  A description is what puts your project on the map (you can add it later);');
+    log(`  who's building it is what the platform's setup recommendations read.`);
+    a.description = await ask(rl, 'What are you building, in a sentence or two?');
+    a.teamShape = await ask(rl, `Who's building it — ${TEAM_SHAPES.join(' / ')}?`);
+    const detail = buildProjectDetail(a);
+    if (Object.keys(detail).length) {
+      // This CLI prints commands rather than calling the API (the trust boundary),
+      // so it shows the answers as the request fields they are — the SAME body the
+      // web wizard files, which is what keeps the two forms in lockstep.
+      log('  These ride the project\'s provisioning request (POST /provisioning/instances):');
+      log('  ' + JSON.stringify(detail));
+    }
+    if (!detail.description) {
+      log('  → no description. Your project stands up either way; it stays off the public map until it');
+      log('    has one, and you can add it any time (PATCH /provisioning/instances/:id/detail).');
+    }
+
+    // Step 2 — human: the GitHub repo (create empty for greenfield; use existing for adopt)
+    if (adopt) {
+      log('\n① Use your EXISTING GitHub repository:');
+      log(`   ${a.repoOwner}/${a.repoName} — the repo you're bringing under Cloud Bongos. Nothing is created or emptied.`);
+      await ask(rl, 'Press Enter once you have that repo checked out locally…');
+    } else {
+      log('\n① Create the GitHub repository (empty):');
+      log(`   github.com → New repository → name it "${a.repoName}" under ${a.repoOwner}, leave it empty, Create.`);
+      await ask(rl, 'Press Enter once the empty repo exists…');
+    }
+
+    // Step 3 — DNS token preflight (before committing the address)
+    if (a.domain) {
+      log('\n② DNS token preflight…');
+      const scope = await provision.checkDnsTokenScope(a.domain);
+      if (scope.reachable) {
+        log(`   ✓ the DNS token can reach zone ${scope.zone}.`);
+      } else {
+        log(`   ✖ ${scope.reason}`);
+        log(`   → ${scope.guidance}`);
+        log('   Resolve this BEFORE provisioning, then re-run `bongos onboard`. Stopping here.');
+        return;
+      }
+    } else {
+      log('\n② DNS preflight skipped (no domain yet) — add one before provisioning, then `bongos provision dns-check <domain>`.');
+    }
+
+    // Step 4 — bongos init (greenfield: scaffold from a spec; adopt: LAYER onto the existing repo)
+    if (adopt) {
+      log('\n③ Layer Cloud Bongos onto the existing repo with `bongos init --adopt`:');
+      log(`   cd into your ${a.repoOwner}/${a.repoName} checkout, then:  node bin/bongos.js init --adopt`);
+      log('   It detects your stack, shows a conflict PRE-FLIGHT (migration / CI / protected-path / boundary), and writes');
+      log('   NOTHING until you accept (interactive y/N, or --accept). It captures your CURRENT version + imports your existing');
+      log('   backlog (GitHub issues / a TODO·ROADMAP·BACKLOG file) — never a synthetic V1, and it never overwrites a file.');
+      await ask(rl, 'Press Enter once `bongos init --adopt` reports "Adopted."…');
+    } else {
+      const spec = buildInitSpec(a);
+      log('\n③ Scaffold the instance config with `bongos init`:');
+      log(`   node bin/bongos.js init --from <spec.json>   (shape: standalone)`);
+      log('   Spec built from your answers:');
+      log('   ' + JSON.stringify(spec));
+      await ask(rl, 'Press Enter once `bongos init` has written config/…');
+    }
+
+    // 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 @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 @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…');
+    }
+
+    // Step 6 — provision (control plane; trust boundary → print the command)
+    log('\n⑤ Provision (runs on the control plane — it alone holds the cloud tokens):');
+    log(`   node scripts/bongos/provision.js provision ${a.slug || '<slug>'} --apply`);
+    log('   (standalone: pull + npm ci → createdb + instance-root migrate → web.env → systemd → DNS → Caddy → /healthz)');
+    await ask(rl, 'Press Enter once provisioning reports the instance active…');
+
+    // Step 7 — human: GitHub sign-in. The ONE-CLICK GitHub App Manifest flow (task 2080)
+    // is the recommended path when a control-plane hall is provisioning this instance —
+    // no OAuth app to hand-create, no secret to paste. This terminal CLI keeps the manual
+    // OAuth-app path below for the standalone/no-hall case.
+    if (a.domain) {
+      const oa = oauthAppInstructions(a.domain);
+      log('\n⑥ Wire GitHub sign-in:');
+      log('   RECOMMENDED — one click: in the control-plane hall, open “Start a project” →');
+      log('   “Set up GitHub sign-in”. Approve the pre-filled GitHub App; the control plane');
+      log('   places the credentials automatically (no secret to paste). Then skip to ⑦.');
+      log('   ⚠ Terminal CLI only: the one-click App cannot enable Device Flow via the manifest,');
+      log('     but `bongos login` needs it. After approving, open the app (github.com → Settings');
+      log('     → Developer settings → GitHub Apps → your app), check "Enable Device Flow", save.');
+      log('     Web sign-in works without this.');
+      log('   — or, to create an OAuth app BY HAND —');
+      log(`   ${oa.location}`);
+      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:');
+      const idV = oauth.validateClientId(clientId);
+      const secV = oauth.validateClientSecret(clientSecret);
+      if (!idV.ok || !secV.ok) {
+        if (!idV.ok) log(`   ✖ client id: ${idV.reason}`);
+        if (!secV.ok) log(`   ✖ client secret: ${secV.reason}`);
+        log('   These look wrong — recheck the OAuth app and re-run. Stopping (nothing placed).');
+        return;
+      }
+      log('   ✓ creds validated. Place them VERIFIED on the control plane:');
+      log(`   node scripts/bongos/oauth-secret.js place ${a.slug || '<slug>'} --client-id ${clientId} --client-secret <secret> --apply`);
+      log('   (validates + rewrites web.env via Node + restarts + probes /healthz auth_configured — never hand-edit web.env.)');
+      await ask(rl, 'Press Enter once oauth-secret reports auth_configured=true…');
+
+      // The publish credential (task 1003049, ADR 0055): the one-click App carries the
+      // repo scopes, but only an INSTALLED App can mint push tokens — skip this click
+      // and every ship strands at 'confirmed' behind a manual merge.
+      log('\n   Install the GitHub App on the repo — the publish credential that lets shipped work land itself:');
+      log('   github.com → Settings → Developer settings → GitHub Apps → your app → Install App → pick this project’s repo.');
+      log('   (On the manual OAuth-app path instead? Set a fine-grained GITHUB_PUSH_TOKEN in web.env — ADR 0055.)');
+      await ask(rl, 'Press Enter once the App is installed on the repo…');
+
+      // Step 8/9 — first sign-in + verify
+      log('\n⑦ First sign-in (seats the founding Archon):');
+      log(`   Open ${oauthAppInstructions(a.domain).homepageUrl} and sign in with GitHub once.`);
+      await ask(rl, 'Press Enter once you are signed in…');
+      log('\n⑧ Verify:');
+      log(`   curl -s ${healthzUrl(a.domain)}   → expect {"ok":true,"auth_configured":true}`);
+    }
+
+    // Step 10 — brand
+    log('\n⑨ Brand the instance look — fill theme/palette/fonts in config/branding.json (docs/branding-fill-prompt.md).');
+
+    // Step 11 — enter the builders hall (task 1002703): the point of all of the above.
+    // With a domain the hall lives on the instance; without one, `bongos dev` runs it locally.
+    if (a.domain) {
+      log(`\n⑩ Enter your builders hall — open https://${a.domain}/builders. That's your project's home.`);
+    } else {
+      log('\n⑩ Enter your builders hall — no domain yet, so run `bongos dev` in your repo checkout:');
+      log('   it stands the instance up locally and serves the hall on your machine.');
+    }
+    log('\n✓ onboard walkthrough complete. Your standalone instance is live and owned.\n');
+  } finally {
+    rl.close();
+  }
+}
+
+if (require.main === module) run().catch((e) => { console.error('onboard failed:', e && e.message ? e.message : e); process.exit(1); });
+
+module.exports = { onboardPlan, oauthAppInstructions, buildInitSpec, healthzUrl, buildProjectDetail, TEAM_SHAPES };