@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/init.js

@@ -0,0 +1,1159 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/bongos/init.js — `bongos init`: scaffold a NEW Cloud Bongos instance.
+//
+// GDS-V4 · V4.R65 · task 1204 (ADR 0062 §7). The self-serve replacement for the
+// hand-written 35–83 KB seed-*.js-per-version pattern. It:
+//   1. gathers a spec (interactive interview, or --from <spec.json>),
+//   2. writes the instance config — config/branding.json + config/modules.json
+//      (lean OVERRIDES; config/*.neutral.json fills the rest, src/branding.js),
+//   3. seeds the first version + its done-when goal via POST /api/bongos/versions
+//      (the primitive added in this same task), then files the starter task and
+//      the human-only KICKOFF steps as real, tracked tasks via POST /tasks,
+//   4. points the owner at docs/branding-fill-prompt.md for the LOOK (a locked
+//      project rule: an owner brands with their OWN LLM — init never generates
+//      branding) and prints the remaining manual steps.
+//
+// It deliberately does NOT try to make launch one command: a fresh instance
+// needs irreducibly-manual owner steps (a GitHub OAuth app, first sign-in).
+// init's value is that it writes what it can AND turns the rest into a claimable,
+// tracked checklist so nothing is silently skipped.
+//
+// Infra arm (ADR 0111 §3, task 1946): when the owner opts into production hosting,
+// the interview's infra answers (hosting shape, bring-your-own domain, credential
+// ref, tier) become a real provisioning REQUEST — a POST to the provisioning
+// module's /provisioning/instances, which enqueues a provision intent the
+// control-plane runner drains — instead of only a manual "production topology"
+// task. OAuth-app creation + first sign-in stay guided/manual (no clean API). If
+// the target instance doesn't have the provisioning module enabled, init falls
+// back to filing the manual task (nothing is silently dropped).
+//
+// Safety: refuses to overwrite an existing config/branding.json unless --force
+// (so running it inside an already-configured instance — e.g. OTB — can't
+// clobber it). Use --dry-run to preview every file + API call without doing any.
+//
+// --adopt (brownfield, ADR 0121): the greenfield body above assumes a blank slate —
+// 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
+// @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
+// repo's real version/goal + importing its backlog is a later real-state step, and the
+// full conflict pre-flight is a later step too — this file lands the mode skeleton +
+// additive config layering (task 2042). Every other onboarding leg is identical.
+//
+// Usage:
+//   bongos init                       interactive interview (greenfield — a NEW instance)
+//   bongos init --adopt               LAYER onto an existing repo (brownfield; never clobbers).
+//                                       Runs a conflict PRE-FLIGHT + accept-gate: nothing writes
+//                                       until you confirm (interactive y/N) or pass --accept.
+//   bongos init --adopt --accept      apply the adopt without the interactive prompt (CI / non-interactive)
+//   bongos init --from spec.json      non-interactive (CI / the C8 self-build proof)
+//   bongos init --dry-run             print the plan; write nothing, call nothing
+//   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 @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, which
+//                                       resolves from the public npm registry (--registry-core).
+//   bongos init --registry-core       greenfield only: keep the caret pin and generate
+//                                       package-lock.json from the registry. @bongos/core is
+//                                       PUBLIC (task 1003872), so this needs no token, no login
+//                                       and no .npmrc — it resolves from the default registry
+//                                       like any other dependency.
+//                                       Mutually exclusive with --vendor-core (registry vs tarball).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const readline = require('node:readline');
+const { apiCall, arg, hasFlag } = require('./cli-lib');
+const { DEFAULT_HIERARCHY } = require('../../src/bongos/hierarchy-config');
+const { resolveCoreRoot, FALLBACK_ENV_PREFIX } = require('../../src/instance-config'); // ADR 0108 §1: where the core package lives
+const { materializeClaude } = require('./claude-materialize'); // ADR 0108 §3 (W3): copy .claude/ into the instance
+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 KNOWN_MODULES = ['game', 'art-pipeline', 'discord'];
+
+// The provisioning hosting shapes — a small mirror of modules/provisioning's
+// HOSTING_SHAPES. init deliberately does NOT import the (optional) provisioning
+// module: it stays self-contained and lets the server be the authority on a
+// request (POST /provisioning/instances validates slug/shape, and returns 404 when
+// the module isn't enabled on the target instance — init then falls back to filing
+// the manual production-topology task). ADR 0111 §3.
+// ADR 0323: 'byo-host' is the free front door and the default; 'co-tenant' is RETIRED
+// and the server refuses it outright, so it is absent here DELIBERATELY. Leaving it in
+// would let init write a spec the create route then 403s — a local list that accepts
+// more than the server does is worse than no list, because the refusal arrives a step
+// later with no useful message. Dropping it means `--shape co-tenant` fails here, naming
+// the shapes that work.
+//
+// 'dedicated' left for the same reason, one step further on: ADR 0327 decision 4 deleted
+// the shape outright, so it is not merely refused but unstorable (migration
+// provisioning_027 folded its value into 'cloud-host'). 'standalone' was renamed to
+// 'cloud-host' by the same migration. Both were requestable from here until task 1004182.
+const HOSTING_SHAPES = ['byo-host', 'cloud-host'];
+
+// The Cloud Bongos core npm package an instance pins as a dependency (ADR 0108).
+// `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 = '@bongos/core';
+
+const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
+
+// The version RANGE `--adopt` writes for the core dep: a caret over the running
+// core's CORE_VERSION — the declared intent. The CONCRETE artifact (a registry
+// install, or the vendored `file:` tarball a `bongos upgrade` pins) is resolved by
+// provisioning / upgrade per ADR 0108, not by init. Falls back to a safe floor if
+// module-api can't be resolved (e.g. a partial checkout).
+function coreDepRange() {
+  let v;
+  try { v = require('../../src/module-api').CORE_VERSION; } catch { v = null; }
+  return `^${v || '1.0.0'}`;
+}
+
+// The running core's bare version (no caret) — for deriving the vendored tarball name
+// when `--vendor-core`'s tarball is non-canonically named. Fail-soft like coreDepRange().
+function coreVersionSafe() {
+  try { return require('../../src/module-api').CORE_VERSION; } catch { return null; }
+}
+
+// The npm scripts a STANDALONE greenfield instance runs. They MIRROR how the control
+// plane runs a standalone instance (scripts/bongos/provision.js): `hall` = the systemd
+// ExecStart (`node <core>/src/platform-server.js`), `migrate` = standaloneMigrateCmd
+// (`bash <core>/scripts/migrate.sh`). Keeping them identical means `npm run hall` /
+// `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).
+// The hall is deliberately NOT `start` (task 1004484): `npm start` belongs to the
+// project's own app, and a host like Render reads it as "how this app starts" — given the
+// hall there, the deploy has no database and times out. Nothing runs an instance's
+// `npm start`: the box unit and `bongos dev` both start platform-server.js directly.
+const INSTANCE_CORE_PKG_DIR = 'node_modules/@bongos/core';
+const INSTANCE_HALL_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 @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 hall/migrate npm scripts a
+// standalone instance runs. Preserves any pre-existing fields + scripts (fills only what
+// is missing); greenfield OWNS the core dep, so it is always (re)set to `coreDep`. Never
+// spawns npm — generating the lockfile is a separate imperative step in main().
+// `moduleDeps` (ADR 0138 / task 2160): the merged external npm deps of the modules this
+// instance ENABLES. @bongos/core ships lean (express+pg, ADR 0108), so a bundled module that
+// needs more (e.g. discord → discord.js) declares it in its module.json `dependencies`, and the
+// consumer's package.json must carry it or boot crashes on the missing module (rehearsal F2).
+// Precedence: module deps FILL gaps, an explicit pre-existing pin WINS over them, @bongos/core
+// is always (re)set. With no moduleDeps this is byte-identical to before.
+function buildInstancePackageJson(existing, { name = 'cloudbongos-instance', coreDep, moduleDeps } = {}) {
+  const dep = coreDep || coreDepRange();
+  const pkg = isObj(existing) ? { ...existing } : {};
+  if (!pkg.name) pkg.name = name;
+  if (pkg.private === undefined) pkg.private = true;
+  pkg.scripts = { ...(isObj(pkg.scripts) ? pkg.scripts : {}) };
+  // A scaffold from before task 1004484 wrote the hall as `start`; move exactly that
+  // command (never an owner's own start) to `hall`, unless they already have a `hall`.
+  if (pkg.scripts.start === INSTANCE_HALL_SCRIPT && !pkg.scripts.hall) {
+    pkg.scripts.hall = pkg.scripts.start;
+    delete pkg.scripts.start;
+  }
+  if (!pkg.scripts.hall) pkg.scripts.hall = INSTANCE_HALL_SCRIPT;
+  if (!pkg.scripts.migrate) pkg.scripts.migrate = INSTANCE_MIGRATE_SCRIPT;
+  pkg.dependencies = {
+    ...(isObj(moduleDeps) ? moduleDeps : {}),
+    ...(isObj(pkg.dependencies) ? pkg.dependencies : {}),
+    [CORE_PKG]: dep,
+  };
+  return pkg;
+}
+
+// The external npm deps a single module declares in its module.json `dependencies` (ADR 0138).
+// I/O (reads the core-package module manifest); fail-soft → {} when absent/unreadable.
+function moduleDeclaredDeps(moduleKey, { coreRoot = resolveCoreRoot(), fsImpl = fs } = {}) {
+  try {
+    const mj = JSON.parse(fsImpl.readFileSync(path.join(coreRoot, 'modules', moduleKey, 'module.json'), 'utf8'));
+    return isObj(mj.dependencies) ? mj.dependencies : {};
+  } catch {
+    return {};
+  }
+}
+
+// Merge the declared deps of every ENABLED module (modulesConfig = { modules: { key: bool } })
+// into one object. PURE — `readDeps(key)` is injected (defaults to moduleDeclaredDeps) so this is
+// testable with no disk. A later-enabled module's range wins on a key collision (rare).
+function enabledModuleDeps(modulesConfig, { readDeps = (k) => moduleDeclaredDeps(k) } = {}) {
+  const enabled = isObj(modulesConfig) && isObj(modulesConfig.modules) ? modulesConfig.modules : {};
+  const out = {};
+  for (const [key, on] of Object.entries(enabled)) {
+    if (on === true) Object.assign(out, readDeps(key));
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Pure builders (exported for tests — no I/O, no network)
+// ---------------------------------------------------------------------------
+
+// A url-safe slug for a criterion_id derived from a short label.
+function slugify(s, fallback = 'goal') {
+  const out = String(s || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48);
+  return out || fallback;
+}
+
+// The DNS/db-safe instance slug a provisioning request carries — derived from an
+// explicit spec.provisioning.slug or the product name, lowercased/dashed, then
+// clamped to the module's 2–40-char rule (the server validates it too). Pure.
+function provisioningSlug(spec) {
+  const p = (spec && spec.provisioning) || {};
+  const base = p.slug || (spec && spec.identity && spec.identity.productName) || '';
+  return slugify(base, 'instance').slice(0, 40).replace(/-+$/, '');
+}
+
+// The POST /api/bongos/provisioning/instances body built from the interview's infra
+// answers — or null when the owner didn't opt into provisioning (no spec.provisioning
+// block). THE ADR 0111 §3 ARM: infra answers become a real provisioning REQUEST (a
+// provisioning_intents row the control-plane runner drains) instead of only a manual
+// runbook task. Pure — no I/O; the caller POSTs it. Shape defaults to the cheapest
+// byo-host ($0 to us — the owner supplies the host) per the budget DNA (ADR 0323).
+function provisioningRequest(spec) {
+  const p = spec && spec.provisioning;
+  if (!isObj(p)) return null;
+  const shape = HOSTING_SHAPES.includes(p.shape) ? p.shape : 'byo-host';
+  const body = { slug: provisioningSlug(spec), hosting_shape: shape };
+  if (p.domain) body.domain = String(p.domain).trim();
+  if (p.targetRef) body.target_ref = String(p.targetRef).trim();
+  if (p.tier) body.tier = String(p.tier).trim();
+  return body;
+}
+
+// The kickoff checklist itself (and the production-topology step the provisioning
+// module can automate) now live in modules/lifecycle/kickoff-checklist.js — ONE list shared
+// with the lifecycle module, which files the same steps at the founder's first
+// sign-in on the control-plane path (task 1003239). init keeps its names.
+const { kickoffChecklist, productionTopologyKickoff } = require('../../modules/lifecycle/kickoff-checklist');
+
+// The lean instance branding.json: ONLY the fields the owner supplied. Everything
+// else (theme, copy, rank labels, box subdomain pattern) resolves from
+// config/branding.neutral.json via src/branding.js. Writing less keeps an
+// instance's overrides legible and lets vanilla defaults flow through.
+function buildBrandingConfig(spec) {
+  const id = spec.identity || {};
+  const productName = id.productName;
+  const origin = (spec.domains && spec.domains.publicOrigin) || 'http://localhost:3000';
+  const branding = {
+    _note: `${productName} — instance brand pack (overrides over config/branding.neutral.json). ` +
+      'Authored by `bongos init`. Fill the LOOK (palette/fonts/wordmark) with your own LLM via docs/branding-fill-prompt.md.',
+    identity: {
+      productName,
+      worldName: id.worldName || productName,
+      company: { name: (id.company && id.company.name) || '', site: (id.company && id.company.site) || '' },
+    },
+    llmProjectName: productName,
+    domains: {
+      publicOrigin: origin,
+      buildersOrigin: origin,
+      statusOrigin: origin,
+      oauthOrigin: origin,
+    },
+    repo: { owner: spec.repo.owner, name: spec.repo.name },
+    firstAdmin: spec.firstAdmin,
+    currency: { label: (spec.currency && spec.currency.label) || 'credits', symbol: (spec.currency && spec.currency.symbol) || '' },
+    envPrefix: spec.envPrefix || FALLBACK_ENV_PREFIX,
+    // Every instance gets its OWN session/config dir (task 1002626). Without
+    // this, instance-config.js falls back to the shared 'cloudbongos' dir, so
+    // every un-branded instance on a machine reads/writes the SAME
+    // ~/.config/cloudbongos/bongos-session.json — signing in to one silently
+    // evicts the CLI session of every other, including the hub. Same slug
+    // family as the package name + provisioning slug.
+    configDir: spec.configDir ? String(spec.configDir).trim() : slugify(productName, 'instance'),
+  };
+  if (spec.tagline) branding.copy = { tagline: spec.tagline };
+  return branding;
+}
+
+// modules.json — every known module, explicit boolean. Default OFF (vanilla).
+function buildModulesConfig(spec) {
+  const on = new Set(Array.isArray(spec.modules) ? spec.modules : []);
+  const modules = {};
+  for (const m of KNOWN_MODULES) modules[m] = on.has(m);
+  return { modules };
+}
+
+// hierarchy.json — the work-tier preset (ADR 0086 §1). The six-tier default with
+// the instance's optional overrides applied: spec.hierarchy.labels ({tierKey:
+// label}), spec.hierarchy.enabled ({tierKey: bool}), spec.hierarchy.roles
+// ({scope/membership/criteria: tierKey}). Most instances keep the canonical six
+// tiers, so this writes them explicitly (self-documenting), resolved over the
+// baked DEFAULT_HIERARCHY by src/bongos/hierarchy-config.js at load.
+function buildHierarchyConfig(spec) {
+  const h = isObj(spec.hierarchy) ? spec.hierarchy : {};
+  const labels = isObj(h.labels) ? h.labels : {};
+  const enabled = isObj(h.enabled) ? h.enabled : {};
+  const tiers = DEFAULT_HIERARCHY.tiers.map((t) => ({
+    key: t.key,
+    label: typeof labels[t.key] === 'string' && labels[t.key].trim() ? labels[t.key].trim() : t.label,
+    enabled: typeof enabled[t.key] === 'boolean' ? enabled[t.key] : t.enabled,
+  }));
+  const roles = { ...DEFAULT_HIERARCHY.roles, ...(isObj(h.roles) ? h.roles : {}) };
+  const productName = (spec.identity && spec.identity.productName) || 'Instance';
+  return {
+    _note: `${productName} — work-hierarchy tiers (ADR 0086 §1): per-tier label/enabled + roles ` +
+      '(which tier carries scope_modules / members / done-when criteria), resolved over the six-tier ' +
+      'default in src/bongos/hierarchy-config.js. Authored by `bongos init`.',
+    tiers,
+    roles,
+  };
+}
+
+// PURE — layer the pinned core dependency into a parsed package.json (ADR 0121
+// §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
+// key order (action:'added'). The `--force`-overwrite path is never involved. The
+// caller only writes the file for 'added'/'created' — 'present' stays byte-untouched.
+function mergeCoreDependency(pkg, { corePkg = CORE_PKG, coreRange, name = 'cloudbongos-instance' } = {}) {
+  const range = coreRange || coreDepRange();
+  if (!isObj(pkg)) {
+    return { pkg: { name, private: true, dependencies: { [corePkg]: range } }, action: 'created' };
+  }
+  const already = (isObj(pkg.dependencies) && pkg.dependencies[corePkg]) ||
+                  (isObj(pkg.devDependencies) && pkg.devDependencies[corePkg]);
+  if (already) return { pkg, action: 'present' };
+  // Spread keeps the original key order — `dependencies` stays where it was (or is
+  // appended if absent). We add exactly one key; we never reorder or drop theirs.
+  const next = { ...pkg, dependencies: { ...(isObj(pkg.dependencies) ? pkg.dependencies : {}), [corePkg]: range } };
+  return { pkg: next, action: 'added' };
+}
+
+// The kickoff checklist, as tasks — the steps init CANNOT do for you (the shared
+// list, self-host shape). Production topology is omitted when the owner opted into
+// provisioning: the control-plane runner covers that leg (ADR 0111 §3).
+function kickoffTasks(spec) {
+  return kickoffChecklist(spec, { provisioned: !!provisioningRequest(spec) });
+}
+
+// Normalize a raw spec (from --from or the interview) to canonical shape +
+// defaults. Pure.
+function normalizeSpec(raw = {}) {
+  const spec = { ...raw };
+  spec.identity = spec.identity || {};
+  spec.repo = spec.repo || {};
+  spec.version = spec.version || {};
+  spec.modules = Array.isArray(spec.modules) ? spec.modules.filter((m) => KNOWN_MODULES.includes(m)) : [];
+  if (!spec.version.status) spec.version.status = 'building';
+  // Provisioning (ADR 0111 §3) — a block ⇒ the owner opted in. Coerce the shape to a
+  // known value (default byo-host, the free front door) and trim the free-text refs; drop the
+  // block entirely when absent so provisioningRequest() reads it as "not requested".
+  if (isObj(spec.provisioning)) {
+    const p = spec.provisioning;
+    spec.provisioning = {
+      shape: HOSTING_SHAPES.includes(p.shape) ? p.shape : 'byo-host',
+      ...(p.slug ? { slug: String(p.slug).trim() } : {}),
+      ...(p.domain ? { domain: String(p.domain).trim() } : {}),
+      ...(p.targetRef ? { targetRef: String(p.targetRef).trim() } : {}),
+      ...(p.tier ? { tier: String(p.tier).trim() } : {}),
+    };
+  } else {
+    delete spec.provisioning;
+  }
+  return spec;
+}
+
+// Validate a normalized spec → array of human-readable error strings ([] = ok).
+// Version fields are required whenever init will SEED — greenfield always, and
+// `--adopt` too (task 2044: adopt reflects the repo's REAL current version/goal, not
+// a synthetic V1). Only `--adopt --no-seed` (layering-only, the task-2042 skeleton
+// behavior) skips them, since it files nothing.
+function validateSpec(spec, { adopt = false, noSeed = false } = {}) {
+  const errs = [];
+  if (!spec.identity || !spec.identity.productName) errs.push('identity.productName is required');
+  if (!spec.repo || !spec.repo.owner || !spec.repo.name) errs.push('repo.owner and repo.name are required');
+  if (!spec.firstAdmin) errs.push('firstAdmin (the founding owner GitHub login) is required');
+  const seeds = !(adopt && noSeed);
+  if (seeds) {
+    const noun = adopt ? 'your current version/milestone' : 'the first version';
+    if (!spec.version || !spec.version.id) errs.push(`version.id is required (e.g. "V1") — ${noun}`);
+    if (!spec.version || !spec.version.name) errs.push('version.name is required');
+    if (!spec.version || !spec.version.done_when) errs.push(`version.done_when is required (what "done" means for ${noun})`);
+  }
+  for (const m of spec.modules || []) {
+    if (!KNOWN_MODULES.includes(m)) errs.push(`unknown module "${m}" (known: ${KNOWN_MODULES.join(', ')})`);
+  }
+  if (spec.provisioning) {
+    if (!HOSTING_SHAPES.includes(spec.provisioning.shape)) {
+      errs.push(`provisioning.shape must be one of: ${HOSTING_SHAPES.join(', ')}`);
+    }
+    if (provisioningSlug(spec).length < 2) {
+      errs.push('provisioning: could not derive a valid instance slug (need ≥2 chars of [a-z0-9-]) — set identity.productName or provisioning.slug');
+    }
+  }
+  return errs;
+}
+
+// Build the POST /api/bongos/versions body from the spec (pure). The first version's
+// done_when goal becomes both the version blurb and one done-when criterion, so
+// /status has a finish line to roll up from day one.
+function versionPayload(spec) {
+  const v = spec.version;
+  return {
+    id: v.id,
+    name: v.name,
+    status: v.status || 'building',
+    done_when: v.done_when,
+    criteria: [{ criterion_id: v.criterion_id ? slugify(v.criterion_id) : 'first-goal', criterion_md: v.done_when }],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Interview (interactive)
+// ---------------------------------------------------------------------------
+
+function ask(rl, question, def) {
+  const suffix = def ? ` [${def}]` : '';
+  return new Promise((resolve) => rl.question(`${question}${suffix}\n> `, (a) => resolve((a || '').trim() || def || '')));
+}
+
+async function interview({ adopt = false } = {}) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    console.log(adopt
+      ? "\nLet's adopt Cloud Bongos onto your existing repo.\n  (layering only — pre-existing files are left untouched, never overwritten)\n"
+      : "\nLet's stand up a new Cloud Bongos instance.\n");
+    const productName = await ask(rl, 'Project name?');
+    const tagline = await ask(rl, 'One-line tagline? (optional)');
+    const repoRaw = await ask(rl, 'GitHub repo the work lands in? (owner/name)');
+    const firstAdmin = await ask(rl, 'First owner (GitHub login)?');
+    const currency = await ask(rl, 'Name for the reward currency?', 'credits');
+    const publicOrigin = await ask(rl, 'Where will it run?', 'http://localhost:3000');
+
+    const modules = [];
+    console.log('\nFeature modules (all off = plain build platform):');
+    for (const m of KNOWN_MODULES) {
+      const yn = (await ask(rl, `  Enable "${m}"? (y/N)`, 'N')).toLowerCase();
+      if (yn === 'y' || yn === 'yes') modules.push(m);
+    }
+
+    // The version + goal. Greenfield seeds a SYNTHETIC first version; --adopt reflects
+    // the repo's REAL current version/milestone + open goal (ADR 0121 §Decision 3 /
+    // task 2044) — same questions, real-state framing, no "Prove the loop" default.
+    console.log(adopt ? '\nYour CURRENT version / milestone (adopt reflects real state):' : '\nYour first version:');
+    const versionId = await ask(rl, '  Version id?', adopt ? '' : 'V1');
+    const versionName = await ask(rl, '  Version name?', adopt ? '' : `${versionId} — Prove the loop`);
+    const doneWhen = await ask(rl, adopt ? '  What is the current goal — what does "done" mean right now?' : `  What does "done" mean for ${versionName}?`,
+      adopt ? '' : 'A task goes claim → grade → ship, with credits, on this instance.');
+    // Greenfield asks for one optional starter; --adopt IMPORTS the existing backlog
+    // (GitHub issues / a local TODO·ROADMAP·BACKLOG file) at seed time, so instead it
+    // just offers to point at a backlog file when auto-detection might miss it.
+    const starter = adopt ? '' : await ask(rl, '  First starter task to claim? (optional)');
+    const backlogFile = adopt ? await ask(rl, '  Path to a backlog file to import? (optional — blank = auto-detect TODO/ROADMAP/BACKLOG or GitHub issues)') : '';
+
+    // Production hosting (ADR 0111 §3) — opt-in. When the owner answers these infra
+    // questions, init files a real provisioning REQUEST via the API (not just a manual
+    // runbook task). Default N: most inits are localhost/dev and shouldn't queue infra.
+    console.log('\nProduction hosting (optional — needs the provisioning module + control-plane credentials):');
+    let provisioning;
+    const wantProv = (await ask(rl, '  Provision production hosting now? (y/N)', 'N')).toLowerCase();
+    if (wantProv === 'y' || wantProv === 'yes') {
+      // Describes each shape by WHAT IT DOES and never by its owner-facing product
+      // name. The stored value → owner-facing label translation lives in exactly one
+      // place — SHAPE_LABEL in modules/public-landing/public/projects.html (ADR 0323,
+      // and this module's CLAUDE.md says so) — so glossing '"cloud host"' here would
+      // be a second copy of it, in a file no designer renaming the product would
+      // think to open. A CLI prompt naming the stored value it is about to write is
+      // the right register anyway: this asks for a column value, not for a purchase.
+      const shape = (await ask(rl, '  Hosting shape? (byo-host = you run it on your own host / cloud-host = its own repo + pinned @bongos/core, stood up for you)', 'byo-host')).toLowerCase();
+      const domain = await ask(rl, '  Domain you own — bring-your-own (blank = the platform assigns <slug>.<its apex> when configured)?');
+      const targetRef = await ask(rl, '  Target credential ref? (which control-plane creds the runner should use; optional)');
+      // No tier question any more. It existed only for 'dedicated', which ADR 0327
+      // decision 4 deleted: on the owner's own platform account a bigger plan is a
+      // setting they choose, not a hosting shape we model. `tier` stays in the spec
+      // shape below because a previously-written spec may still carry one.
+      const tier = '';
+      provisioning = {
+        shape: HOSTING_SHAPES.includes(shape) ? shape : 'byo-host',
+        domain: domain || undefined,
+        targetRef: targetRef || undefined,
+        tier: tier || undefined,
+      };
+    }
+
+    const [owner, name] = repoRaw.includes('/') ? repoRaw.split('/') : [repoRaw, ''];
+    const spec = {
+      identity: { productName },
+      tagline: tagline || undefined,
+      repo: { owner, name },
+      firstAdmin,
+      currency: { label: currency },
+      domains: { publicOrigin },
+      modules,
+    };
+    spec.version = { id: versionId, name: versionName, done_when: doneWhen };
+    if (starter) spec.starterTasks = [{ title: starter, kind: 'unclassified' }];
+    if (backlogFile) spec.backlogFile = backlogFile;
+    if (provisioning) spec.provisioning = provisioning;
+    return spec;
+  } finally {
+    rl.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Write + seed
+// ---------------------------------------------------------------------------
+
+// PURE (exported for tests) — the root START-HERE guide (task 1002404, goal
+// 1000052; task 1003881 made it LAYER onto an existing README instead of
+// skipping one — see layerReadme below). A freshly-CLONED instance must tell a human what to run FIRST: the
+// `bongos` CLI ships INSIDE the not-yet-installed @bongos/core package, so
+// `npm install` has to come before any `bongos` command (including `bongos dev`).
+// `bongos init` runs npm install during scaffolding, but a later `git clone` of
+// the committed instance repo skips that — so this file is the signpost the clone
+// carries. Owner-friendly and plain-language (the owner may not be an engineer).
+function buildReadme(branding = {}) {
+  const identity = branding.identity || {};
+  const name = identity.productName || 'This Cloud Bongos instance';
+  const origin = (branding.domains && branding.domains.publicOrigin) || '';
+  const loginLine = origin
+    ? `3. \`bongos login ${origin}\` — only if you're signed in to a *different* instance (\`bongos dev\` signs you in the first time).`
+    : `3. \`bongos login <your-instance-url>\` — only if you're signed in to a *different* instance (\`bongos dev\` signs you in the first time).`;
+  return [
+    `# ${name}`,
+    '',
+    'A **Cloud Bongos** instance — an AI-first build platform: AI agents claim tasks and write the code; a human owner sets scope and the gates.',
+    '',
+    '## Start here (first run)',
+    '',
+    'Just cloned this repo? Run these **in order**. The `bongos` CLI ships *inside* the `@bongos/core` dependency, so step 1 comes first — until it runs there is no `bongos` command:',
+    '',
+    '1. `npm install` — installs the toolchain (this is what creates the `bongos` command).',
+    '2. `bongos dev` — one command to run this instance locally: starts Postgres, builds the tables, launches the server, and signs you in.',
+    loginLine,
+    '4. `bongos start` — see what you can work on. (Inside Claude Code, the same thing is `/builder-start`.)',
+    '',
+    'Requires Node >= 22 and Postgres installed locally (macOS/Linux; on Windows use WSL). If anything looks off, `bongos doctor` checks your setup and prints the fix.',
+    '',
+    '## Where to look next',
+    '',
+    '- `CLAUDE.md` — how this project is built (the operating manual agents read first).',
+    '- `bongos --help` — the full CLI: claim, ship, status, recall, and more.',
+    '',
+  ].join('\n');
+}
+
+// The START-HERE content as an APPENDABLE section, for a repo that already has a
+// README of its own. Fenced by a stable marker so re-running init is idempotent and so
+// an owner can find (and delete) the block we added.
+//
+// WHY this is not just buildReadme: an ADOPTED repo always has a README, and the
+// write-if-absent rule below therefore skipped the first-run guide on every single adopt
+// — silently, logging "already present — left untouched" as though nothing were owed.
+// That removed the one human-facing instruction to run `npm install`, without which the
+// repo has no `bongos` command at all. Appending mirrors how the adopt path already
+// treats .gitignore: keep what the owner wrote, add only what the instance needs.
+const README_MARKER = '<!-- cloud-bongos:start-here -->';
+
+function buildReadmeSection(branding = {}) {
+  const guide = buildReadme(branding);
+  // Reuse the canonical guide, demoted one heading level so it nests under the owner's
+  // own README, and drop its H1 title (their README already has one).
+  const body = guide
+    .split('\n')
+    .slice(1)                                   // drop "# <product>"
+    .join('\n')
+    .replace(/^## /gm, '### ')
+    .trim();
+  return `${README_MARKER}\n\n## Working on this project (Cloud Bongos)\n\n${body}\n`;
+}
+
+// Append the START-HERE section to an existing README unless it is already there.
+// PURE (text in → text out) so the idempotence is unit-testable without fs.
+// Returns { text, action } where action is 'appended' | 'present'.
+function appendReadmeSection(existing, section) {
+  const prev = String(existing == null ? '' : existing);
+  if (prev.includes(README_MARKER)) return { text: prev, action: 'present' };
+  return { text: `${prev.replace(/\n*$/, '\n')}\n---\n\n${section}`, action: 'appended' };
+}
+
+// Put the first-run guide in the repo's README whichever state it is in: mint the whole
+// guide when there is no README, else append the marked section. Shared by the greenfield
+// and adopt paths so neither can silently owe it. Returns the action taken.
+function layerReadme(branding, { dir, dryRun, log = console.log } = {}) {
+  const readmePath = path.join(dir, 'README.md');
+  if (!fs.existsSync(readmePath)) {
+    if (dryRun) { log(`  [dry-run] would write README.md (first-run START-HERE)`); return 'created'; }
+    fs.writeFileSync(readmePath, buildReadme(branding));
+    log(`  ✓ wrote README.md (first-run START-HERE)`);
+    return 'created';
+  }
+  const { text, action } = appendReadmeSection(fs.readFileSync(readmePath, 'utf8'), buildReadmeSection(branding));
+  if (action === 'present') {
+    log('  • README.md already carries the Cloud Bongos start-here section — left untouched.');
+    return 'present';
+  }
+  if (dryRun) { log('  [dry-run] would append the Cloud Bongos start-here section to the existing README.md'); return 'appended'; }
+  fs.writeFileSync(readmePath, text);
+  log('  ✓ appended the Cloud Bongos start-here section to README.md (your own content is untouched)');
+  return 'appended';
+}
+
+function writeConfigs(spec, { dir, force, dryRun, coreDep, log = console.log }) {
+  const configDir = path.join(dir, 'config');
+  const brandingPath = path.join(configDir, 'branding.json');
+  const modulesPath = path.join(configDir, 'modules.json');
+  const hierarchyPath = path.join(configDir, 'hierarchy.json');
+  const pkgPath = path.join(dir, 'package.json');
+  const readmePath = path.join(dir, 'README.md');
+  const branding = buildBrandingConfig(spec);
+  const modules = buildModulesConfig(spec);
+  const hierarchy = buildHierarchyConfig(spec);
+  // Greenfield OWNS package.json (ADR 0108 gap 1/4, task 2053): mint it — or augment one
+  // from a prior --force run — so the scaffold is `npm ci`-installable + runnable. Augment,
+  // never blind-overwrite, so a re-run keeps any hand-added fields/scripts.
+  const pkgName = slugify((spec.identity && spec.identity.productName) || '', 'cloudbongos-instance');
+  let existingPkg = null;
+  if (fs.existsSync(pkgPath)) { try { existingPkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')); } catch { existingPkg = null; } }
+  // Compose the deps of the ENABLED modules (ADR 0138 / task 2160) so an instance that turns a
+  // bundled module on gets that module's npm deps (e.g. discord → discord.js) in its package.json,
+  // rather than crashing at boot on a dep @bongos/core deliberately doesn't carry (rehearsal F2).
+  const moduleDeps = enabledModuleDeps(modules);
+  const pkg = buildInstancePackageJson(existingPkg, { name: pkgName, coreDep, moduleDeps });
+  const pinNote = pkg.dependencies[CORE_PKG];
+
+  if (dryRun) {
+    log(`\n[dry-run] would write ${brandingPath}:`);
+    log(JSON.stringify(branding, null, 2));
+    log(`\n[dry-run] would write ${modulesPath}:`);
+    log(JSON.stringify(modules, null, 2));
+    log(`\n[dry-run] would write ${hierarchyPath}:`);
+    log(JSON.stringify(hierarchy, null, 2));
+    log(`\n[dry-run] would write ${pkgPath} (pins ${CORE_PKG} → ${pinNote}):`);
+    log(JSON.stringify(pkg, null, 2));
+    log(`\n[dry-run] would write ${readmePath} (root START-HERE first-run guide) if absent`);
+    return { brandingPath, modulesPath, hierarchyPath, pkgPath, readmePath, wrote: false };
+  }
+  if (fs.existsSync(brandingPath) && !force) {
+    throw new Error(`${brandingPath} already exists — refusing to overwrite. Use --force to replace, or run init in a fresh --dir.`);
+  }
+  fs.mkdirSync(configDir, { recursive: true });
+  fs.writeFileSync(brandingPath, JSON.stringify(branding, null, 2) + '\n');
+  fs.writeFileSync(modulesPath, JSON.stringify(modules, null, 2) + '\n');
+  fs.writeFileSync(hierarchyPath, JSON.stringify(hierarchy, null, 2) + '\n');
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+  log(`  ✓ wrote ${path.relative(dir, brandingPath)}`);
+  log(`  ✓ wrote ${path.relative(dir, modulesPath)}`);
+  log(`  ✓ wrote ${path.relative(dir, hierarchyPath)}`);
+  log(`  ✓ wrote ${path.relative(dir, pkgPath)} (pins ${CORE_PKG} → ${pinNote})`);
+  // README START-HERE (task 1002404, layering added by task 1003881): mint it when
+  // absent, else APPEND the marked section. Never a blind overwrite — an owner's own
+  // README content always survives, which is why the guide stopped being skipped.
+  layerReadme(branding, { dir, dryRun: false, log });
+  return { brandingPath, modulesPath, hierarchyPath, pkgPath, readmePath, wrote: true };
+}
+
+// `--adopt` config layering (ADR 0121 §Decision 2 / task 2042). The additive
+// sibling of writeConfigs: it does NOT refuse where config/branding.json exists and
+// it NEVER overwrites. For each lean config file it WRITES only when absent, and
+// LEAVES-AND-REPORTS when present. The greenfield writeConfigs — with its --force
+// overwrite — is deliberately not reused: a brownfield repo is exactly where an
+// overwrite is expensive. Returns { wrote:[names], left:[names] }.
+function layerConfigs(spec, { dir, dryRun, log = console.log }) {
+  const configDir = path.join(dir, 'config');
+  const targets = [
+    ['branding.json', buildBrandingConfig(spec)],
+    ['modules.json', buildModulesConfig(spec)],
+    ['hierarchy.json', buildHierarchyConfig(spec)],
+  ];
+  const wrote = [];
+  const left = [];
+  for (const [name, content] of targets) {
+    const p = path.join(configDir, name);
+    if (fs.existsSync(p)) {
+      left.push(name);
+      log(`  • config/${name} already present — left untouched (adopt never overwrites).`);
+      continue;
+    }
+    wrote.push(name);
+    if (dryRun) { log(`  [dry-run] would write config/${name}`); continue; }
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(content, null, 2) + '\n');
+    log(`  ✓ wrote config/${name}`);
+  }
+  return { wrote, left };
+}
+
+// `--adopt` package.json layering (ADR 0121 §Decision 2 / task 2042): add the
+// 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
+// corrupting a file it can't safely rewrite. Returns { action, path }.
+function layerPackageJson(spec, { dir, dryRun, log = console.log, coreRange = coreDepRange() } = {}) {
+  const p = path.join(dir, 'package.json');
+  let existing = null;
+  if (fs.existsSync(p)) {
+    try { existing = JSON.parse(fs.readFileSync(p, 'utf8')); }
+    catch (e) {
+      log(`  • package.json exists but is not valid JSON (${e.message}) — left untouched; add "${CORE_PKG}": "${coreRange}" to its dependencies by hand.`);
+      return { action: 'unparseable', path: p };
+    }
+  }
+  const name = slugify((spec.identity && spec.identity.productName) || '', 'cloudbongos-instance');
+  const { pkg, action } = mergeCoreDependency(existing, { coreRange, name });
+  if (action === 'present') {
+    log(`  • ${CORE_PKG} already a dependency — package.json left untouched.`);
+    return { action, path: p };
+  }
+  const verb = action === 'created' ? 'create package.json pinning' : 'add';
+  const tail = action === 'added' ? ' to dependencies (existing fields preserved)' : '';
+  if (dryRun) { log(`  [dry-run] would ${verb} ${CORE_PKG}@${coreRange}${tail}`); return { action, path: p }; }
+  fs.writeFileSync(p, JSON.stringify(pkg, null, 2) + '\n');
+  log(`  ✓ ${action === 'created' ? 'created package.json pinning' : 'added'} ${CORE_PKG}@${coreRange}${tail}`);
+  return { action, path: p };
+}
+
+async function seedViaApi(spec, { dryRun, log = console.log, api = apiCall } = {}) {
+  const vp = versionPayload(spec);
+  const starters = Array.isArray(spec.starterTasks) ? spec.starterTasks : [];
+  const kickoff = kickoffTasks(spec);
+  const pr = provisioningRequest(spec); // ADR 0111 §3 — null unless the owner opted in
+
+  if (dryRun) {
+    log(`\n[dry-run] would POST /api/bongos/versions:`);
+    log(JSON.stringify(vp, null, 2));
+    log(`\n[dry-run] would create ${starters.length} starter + ${kickoff.length} kickoff task(s) under ${vp.id}.`);
+    if (pr) {
+      log(`\n[dry-run] would POST /api/bongos/provisioning/instances:`);
+      log(JSON.stringify(pr, null, 2));
+      log(`  (queues a 'provision' intent; the control-plane runner stands up hosting — ADR 0111 §2/§3.`);
+      log(`   production-topology is left OFF the kickoff list since it's now automated.)`);
+    }
+    return { seeded: false };
+  }
+
+  // 1. version + first goal
+  const vres = await api('POST', '/api/bongos/versions', vp);
+  if (!vres.ok && vres.status !== 409) {
+    throw new Error(`POST /versions failed (${vres.status}): ${JSON.stringify(vres.data)}`);
+  }
+  // The version's first goal — every task below needs its id (BV1.R11 refuses a
+  // goal-less task, and R03 refuses creating a goal on a version that is already
+  // 'building', which is what versionPayload makes). POST /versions now returns it
+  // alongside the version (task 1003701); on the 409 re-run path the version is
+  // already there, so read its goals back instead.
+  let goalId = vres.ok && vres.data && vres.data.goal ? vres.data.goal.id : null;
+  if (vres.status === 409) {
+    log(`  • version ${vp.id} already exists — continuing.`);
+    const gres = await api('GET', `/api/bongos/goals?version=${encodeURIComponent(vp.id)}`);
+    const goals = gres.ok ? (Array.isArray(gres.data) ? gres.data : (gres.data && gres.data.goals) || []) : [];
+    const open = goals.find((g) => g && g.status === 'open' && !g.is_maintenance) || goals.find((g) => g && g.status === 'open');
+    goalId = open ? open.id : null;
+  } else {
+    log(`  ✓ created version ${vp.id} + its first goal`);
+  }
+  // Fail LOUD rather than filing a wave of tasks the server will refuse one by one:
+  // with no goal every POST below returns 400 goal_id_required, and the run would
+  // report a pile of identical failures instead of the single reason behind them.
+  if (goalId == null) {
+    throw new Error(
+      `could not determine a goal for version ${vp.id} — every task needs one (goal_id_required). ` +
+      `The version exists but has no open goal to file under; create one and re-run.`
+    );
+  }
+  const criterionId = vp.criteria[0].criterion_id;
+
+  // A tracked kickoff/starter task (status ready). Returns true on success.
+  // The whole point of filing these is "nothing is silently skipped" — so a
+  // rejected POST must be LOUD: every failure is collected with its reason and
+  // reported against the expected count, never absorbed into a smaller total.
+  let attempted = 0;
+  const failures = [];
+  const postTask = async (t, extra = {}) => {
+    attempted++;
+    const res = await api('POST', '/api/bongos/tasks', {
+      version_id: vp.id, goal_id: goalId, title: t.title, description: t.description || '', status: 'ready',
+      kind: t.kind || 'infra', discipline: t.discipline || 'engineer', source: 'bongos-init', ...extra,
+    });
+    if (!res.ok) failures.push({ title: t.title, status: res.status, detail: JSON.stringify(res.data) });
+    return res.ok;
+  };
+
+  // 2. starter task(s) — linked to the first goal so /status rolls them up
+  let created = 0;
+  for (const t of starters) {
+    // task 1002988: `discipline: undefined` used to sit in this extras object, and
+    // because `...extra` spreads AFTER postTask's own `t.discipline || 'engineer'`
+    // it clobbered that default back to nothing — which is why a freshly scaffolded
+    // instance was born with role-less starter tasks. Dropped, so starters inherit
+    // the same default every other seeded task already got.
+    if (await postTask(t, { kind: t.kind || 'unclassified', criterion_ids: [criterionId] })) created++;
+  }
+  // 3. kickoff steps as tracked tasks
+  for (const t of kickoff) {
+    if (await postTask(t)) created++;
+  }
+
+  // 4. Provisioning arm (ADR 0111 §3): the infra answers become a real provisioning
+  // REQUEST, not just a manual runbook task. kickoffTasks already omitted the
+  // production-topology step when pr is set — so if the request can't be enqueued
+  // (module not enabled on the target instance → 404, or a transient failure), we
+  // re-file that manual step here so the leg is never silently dropped.
+  let provisioned = false;
+  if (pr) {
+    const pres = await api('POST', '/api/bongos/provisioning/instances', pr);
+    if (pres.ok) {
+      provisioned = true;
+      const inst = (pres.data && pres.data.instance) || {};
+      const cost = Number(inst.cost_estimate_usd || 0);
+      // Report the ROW's domain, not the request's: the server may have
+      // auto-assigned <slug>.<instanceBase> to a domainless request (task
+      // 1002704) — the operator must hear the address they actually got.
+      const addr = inst.domain
+        ? `, ${inst.domain}${pr.domain ? '' : ' (auto-assigned — attach your own domain any time to replace it)'}`
+        : ', no address yet';
+      log(`  ✓ requested provisioning of instance "${pr.slug}" (${pr.hosting_shape}${addr})` +
+          `${cost ? ` — est. $${cost}/mo` : ''} — a provision intent is queued for the control-plane runner`);
+    } else {
+      const why = pres.status === 404
+        ? 'the provisioning module is not enabled on this instance'
+        : `the provisioning request failed (${pres.status}: ${JSON.stringify(pres.data)})`;
+      log(`  • ${why} — filing the manual production-topology task instead`);
+      if (await postTask(productionTopologyKickoff())) created++;
+    }
+  }
+
+  const kickoffLabel = provisioned ? `${kickoff.length} kickoff + provisioning request` : `${kickoff.length} kickoff`;
+  if (failures.length) {
+    log(`  ✗ ${failures.length} of ${attempted} task(s) FAILED to file — the checklist below is INCOMPLETE:`);
+    for (const f of failures) log(`      ✗ "${f.title}" (${f.status}): ${f.detail}`);
+  }
+  log(`  ${failures.length ? '⚠' : '✓'} filed ${created} of ${attempted} task(s) (${starters.length} starter + ${kickoffLabel})`);
+  return { seeded: true, created, attempted, failures, provisioned };
+}
+
+// ---------------------------------------------------------------------------
+// adopt (brownfield) — LAYER onto an existing repo (ADR 0121 / task 2042)
+// ---------------------------------------------------------------------------
+
+// Interactive accept-gate for the pre-flight (ADR 0121 §Decision 5). Default No, so a
+// bare Enter never writes. Only reached when there are no BLOCKING findings (those hard-
+// stop before the prompt). Split out for testability (injectable input/output).
+function confirmProceed({ input = process.stdin, output = process.stdout } = {}) {
+  const rl = readline.createInterface({ input, output });
+  return new Promise((resolve) => rl.question('\nProceed with layering + seeding onto this repo? (y/N) ', (a) => { rl.close(); resolve(/^y(es)?$/i.test((a || '').trim())); }));
+}
+
+// The brownfield sibling of main()'s greenfield body: LAYER Cloud Bongos onto an
+// EXISTING repo without clobbering, then reflect its REAL state. It (1) detects the
+// stack (task 2043), (2) runs an accept-gated conflict PRE-FLIGHT (task 2045) — nothing
+// is written until the owner accepts — then, on accept, (3) writes the lean config where
+// absent + adds the pinned core dep + copies .claude/ ADDITIVELY (task 2042) and (4)
+// seeds the repo's REAL version/goal + IMPORTS its existing backlog (task 2044), NOT a
+// synthetic "V1 — Prove the loop". `--dry-run` previews everything and writes nothing;
+// `--no-seed` layers without seeding. Returns a process exit code.
+// `coreDep`/`vendorPlan` (task 1002562): adopt used to ALWAYS write the caret range,
+// which resolves NOWHERE on npm — so an adopted repo could not `npm ci --omit=dev`, the
+// exact command the provisioner runs on the box. Greenfield already had --vendor-core for
+// this; passing the same resolved pin through here makes an adopted repo equally
+// installable. Omitted (a plain `bongos init --adopt` on a laptop) → the caret, unchanged.
+async function runAdopt(spec, { dir, dryRun, noSeed = false, accept = false, coreDep = null, vendorPlan = null, log = console.log }) {
+  log(`\nAdopting Cloud Bongos onto the existing repo at "${dir}"${dryRun ? '  (dry run — nothing will be written or created)' : ''}:`);
+  log('  Layering — pre-existing files are left untouched; nothing is overwritten.');
+
+  // Inspect the tree BEFORE writing anything (ADR 0121 §Decision 4 / task 2043) so
+  // layering fits what is already here.
+  const stack = detectStack({ dir });
+  log('\nDetected stack + layout:');
+  for (const line of formatStackSummary(stack)) log(`  • ${line}`);
+
+  // Conflict PRE-FLIGHT (ADR 0121 §Decision 5 / task 2045): report the blast radius, then
+  // gate the writes on the owner's acceptance. --dry-run previews without writing, so it
+  // needs no gate; a real run proceeds only on --accept or an interactive yes.
+  const report = preflightAdopt({ dir, stack });
+  log('\nConflict pre-flight (nothing is written until you accept):');
+  for (const line of formatPreflight(report)) log(line);
+  log(`  → ${report.counts.blocking} blocking · ${report.counts.warning} warning · ${report.counts.info} ok`);
+  if (!dryRun) {
+    // A BLOCKING finding (e.g. a migration that WILL collide) is a hard stop — it can't
+    // be waved through with --accept; the owner must resolve it and re-run.
+    if (report.hasBlocking) {
+      log(`\n✗ ${report.counts.blocking} BLOCKING conflict(s) above — resolve them, then re-run. Nothing was written.`);
+      return 2;
+    }
+    const proceed = accept || (process.stdin.isTTY ? await confirmProceed() : false);
+    if (!proceed) {
+      log('\nPre-flight only — nothing was written. Re-run with --accept (or confirm interactively) to apply.');
+      return 0;
+    }
+  }
+
+  const cfg = layerConfigs(spec, { dir, dryRun, log });
+  const pkg = layerPackageJson(spec, { dir, dryRun, log, ...(coreDep ? { coreRange: coreDep } : {}) });
+  // The first-run guide, which adopt used to skip entirely: an adopted repo always has a
+  // README, so the greenfield write-if-absent rule never fired and the one instruction to
+  // run `npm install` was silently owed on every adopt.
+  layerReadme(buildBrandingConfig(spec), { dir, dryRun, log });
+
+  // Vendor the pinned core tarball + generate the lockfile, mirroring the greenfield
+  // --vendor-core steps, so the adopted repo is `npm ci --omit=dev`-installable (ADR 0108).
+  // Skipped when layerPackageJson found the dep ALREADY present — re-pinning someone's
+  // existing declaration is an overwrite, and adopt never overwrites.
+  if (vendorPlan && pkg.action !== 'present' && pkg.action !== 'unparseable') {
+    const upgrade = require('./upgrade');
+    if (dryRun) {
+      log(`\n  [dry-run] would vendor ${vendorPlan.tgz} → ${vendorPlan.vendorRel} and run \`npm install\` to generate package-lock.json`);
+    } else {
+      log('\nVendoring the pinned @bongos/core + generating the lockfile:');
+      upgrade.vendorTarball({ instanceDir: dir, fromTgz: vendorPlan.tgz, targetVersion: vendorPlan.version });
+      log(`  ✓ vendored ${vendorPlan.vendorRel}`);
+      const inst = upgrade.npmInstall(dir);
+      if (!inst.ok) {
+        log(`  ! npm install failed (${inst.reason || 'exit ' + inst.code}) — package-lock.json not generated; run \`npm install\` in ${dir} by hand before provisioning.`);
+      } else {
+        log('  ✓ npm install → package-lock.json generated (node_modules/@bongos/core installed)');
+      }
+    }
+  } else if (vendorPlan && pkg.action === 'present') {
+    log(`  • ${CORE_PKG} was already declared — left as-is; the vendored tarball was NOT pinned over it.`);
+  }
+
+  log('\nMaterializing the .claude/ methodology surface (additive — existing files left untouched):');
+  const claude = materializeClaude({ coreRoot: resolveCoreRoot(), instanceDir: dir, dryRun, overwrite: false, log });
+
+  // Reflect REAL state (ADR 0121 §Decision 3 / task 2044): import the existing backlog,
+  // then seed the repo's REAL version/goal + the imported tasks + the (identical) human-
+  // only kickoff steps via the same seedViaApi greenfield uses — so the ledger starts
+  // truthful, not empty. `--no-seed` layers only (the task-2042 skeleton behavior).
+  let backlog = { source: 'none', tasks: [], truncated: false };
+  if (!noSeed) {
+    const githubToken = process.env.GITHUB_TOKEN || process.env.GH_TOKEN || null;
+    backlog = await resolveBacklogTasks({ dir, repo: spec.repo, githubToken, backlogFile: spec.backlogFile, onWarn: (m) => log(`  • ${m}`) });
+    // Imported tasks ride in as starterTasks so seedViaApi links them to the goal's criterion.
+    if (backlog.tasks.length) spec.starterTasks = [...(spec.starterTasks || []), ...backlog.tasks];
+    const importNote = backlog.tasks.length
+      ? `${backlog.tasks.length} imported task(s) from ${backlog.source}${backlog.truncated ? ` (capped at ${BACKLOG_MAX})` : ''}`
+      : 'no backlog found (capture tasks later)';
+    log(`\nReflecting real state — seeding version "${spec.version && spec.version.id}" + goal + ${importNote}:`);
+    const seedResult = (await seedViaApi(spec, { dryRun, log })) || {};
+    if (Array.isArray(seedResult.failures) && seedResult.failures.length) {
+      log(`\n  ⚠ ${seedResult.failures.length} seed task(s) failed to file (details above) — re-file them by hand or re-run the seed; the tracked checklist is incomplete until they exist.`);
+    }
+  } else {
+    log('\n  (--no-seed: layered config only; skipped real-state seeding)');
+  }
+
+  const leftFiles = cfg.left.length
+    + (Array.isArray(claude.skippedFiles) ? claude.skippedFiles.length : 0)
+    + (pkg.action === 'present' || pkg.action === 'unparseable' ? 1 : 0);
+
+  log(`\n${dryRun ? 'Dry run complete — re-run without --dry-run (and --accept) to apply.' : 'Adopted.'} Next:`);
+  if (report.counts.warning > 0) log(`  • ${report.counts.warning} pre-flight warning(s) above — reconcile them (esp. migrations / CI check names) as you settle in.`);
+  if (leftFiles > 0) log(`  • ${leftFiles} pre-existing file(s) were left untouched — reconcile them against what a fresh instance ships.`);
+  log('  • fill the look: hand docs/branding-fill-prompt.md to your own LLM (or keep your existing branding).');
+  log(`  • sign in as ${spec.firstAdmin} to seat yourself as the founding owner.`);
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+
+async function main(argv) {
+  const args = argv.slice(2);
+  const fromPath = arg('--from', args);
+  const dir = path.resolve(arg('--dir', args) || process.cwd());
+  const dryRun = hasFlag('--dry-run', args);
+  const force = hasFlag('--force', args);
+  const noSeed = hasFlag('--no-seed', args);
+  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: keep the caret pin and generate the lockfile from the public registry (task 1003878)
+
+  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) {
+    try {
+      raw = JSON.parse(fs.readFileSync(path.resolve(fromPath), 'utf8'));
+    } catch (e) {
+      console.error(`init: could not read spec ${fromPath}: ${e.message}`);
+      return 1;
+    }
+  } else {
+    raw = await interview({ adopt });
+  }
+
+  const spec = normalizeSpec(raw);
+  const errs = validateSpec(spec, { adopt, noSeed });
+  if (errs.length) {
+    console.error('\ninit: the spec is incomplete:');
+    for (const e of errs) console.error(`  • ${e}`);
+    return 1;
+  }
+
+  // Core-dep resolution (ADR 0108 gap 1/4, task 2053). With --vendor-core, pin
+  // package.json to the vendored `file:` tarball (the caret range resolves NOWHERE on npm,
+  // so a caret-only scaffold can't `npm ci`); the tarball is copied + the lockfile generated
+  // below. Without it, the scaffold carries the declared caret (a local/dev scaffold the
+  // owner resolves another way). Reuses the bongos-upgrade vendoring + install steps.
+  //
+  // Resolved BEFORE the adopt branch (task 1002562) because BOTH paths need it: an adopted
+  // repo has to be `npm ci`-installable by the provisioner exactly like a scaffolded one.
+  const upgrade = require('./upgrade');
+  let coreDep = null; // null → writeConfigs/layerPackageJson write the caret range
+  let vendorPlan = null;
+  if (vendorCore) {
+    const tgz = path.resolve(vendorCore);
+    if (!fs.existsSync(tgz)) {
+      console.error(`init: --vendor-core tarball not found: ${tgz}`);
+      return 1;
+    }
+    const version = upgrade.versionFromTgzPath(tgz) || coreVersionSafe();
+    if (!version) {
+      console.error(`init: could not derive the core version from ${path.basename(tgz)} — expected a tarball named ${upgrade.ARTIFACT}-<version>.tgz (produced by \`node scripts/bongos/package-core.js\`).`);
+      return 1;
+    }
+    const vendorRel = upgrade.vendorRelFor(version);
+    coreDep = `file:${vendorRel}`;
+    vendorPlan = { tgz, version, vendorRel };
+  }
+
+  // Brownfield (ADR 0121): a distinct LAYER + real-state path — never the greenfield
+  // scaffold/overwrite below. Its own report + next-steps live in runAdopt.
+  if (adopt) return await runAdopt(spec, { dir, dryRun, noSeed, accept, coreDep, vendorPlan });
+
+  console.log(`\nScaffolding "${spec.identity.productName}"${dryRun ? '  (dry run — nothing will be written or created)' : ''}:`);
+  writeConfigs(spec, { dir, force, dryRun, coreDep });
+
+  // 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.
+  if (vendorPlan) {
+    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 @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/@bongos/core installed)');
+      }
+    }
+  }
+
+  // Registry-install path: keep the caret pin writeConfigs wrote and generate
+  // package-lock.json from the registry, so a later `npm ci` is reproducible.
+  //
+  // This used to write an env-fed npm auth file and skip the lockfile when no credential was
+  // present, because @bongos/core published PRIVATE. It is public now (task 1003872), so it
+  // resolves from the default registry like any other dependency: no auth file, no credential,
+  // and no tokenless-404 branch to explain (task 1003878).
+  if (registryCore) {
+    if (dryRun) {
+      console.log('\n[dry-run] would run `npm install` to generate package-lock.json from the registry');
+    } else {
+      console.log('\nWiring the registry-install path:');
+      const inst = upgrade.npmInstall(dir);
+      if (!inst.ok) {
+        console.error(`  ! npm install failed (${inst.reason || 'exit ' + inst.code}) — package-lock.json not generated. @bongos/core is public, so this is a real failure (network, registry outage, or an unpublished version), not a missing credential.`);
+      } else {
+        console.log('  ✓ npm install → package-lock.json generated (pulled @bongos/core from the registry)');
+      }
+    }
+  }
+
+  // Materialize the .claude/ methodology surface (ADR 0108 §3 / W3): Claude Code reads skills +
+  // hooks + settings.json from the project root, never node_modules, so init copies them from the
+  // core package into the instance and rewrites `node scripts/bongos/<x>.js` → the `bongos` bin.
+  // A no-op when the instance dir IS the core checkout (self-copy guard).
+  console.log('\nMaterializing the .claude/ methodology surface:');
+  materializeClaude({ coreRoot: resolveCoreRoot(), instanceDir: dir, dryRun, log: console.log });
+
+  // Regenerate the per-instance API artifacts (OpenAPI spec + api-reference + typed
+  // client) from the PINNED core's routes so this fresh consumer's COMMITTED artifacts
+  // match its core from day one — not the core package's build-time snapshot (task 2141).
+  // They ship as CORE starters (task 2078 — the hall/docs must render before first regen)
+  // yet are per-instance GENERATED; `bongos upgrade` does the same on a bump, this closes
+  // the gap at standup. Best-effort: a hiccup warns, never fails init — the instance-root
+  // drift guard (fitness `gen-api-docs --check` + the api_client byte-identity test)
+  // catches any lag on the consumer's first CI.
+  if (dryRun) {
+    console.log('\n[dry-run] would regenerate the API artifacts (OpenAPI spec + reference + typed client) from the pinned core');
+    console.log('[dry-run] would seed the whole-file navigation docs (session-log index) from the pinned core');
+  } else {
+    console.log('\nRegenerating the API artifacts from the pinned core (OpenAPI spec + reference + typed client):');
+    const regen = upgrade.regenerateApiArtifacts({ instanceDir: dir, coreRoot: resolveCoreRoot() });
+    if (regen.ok) console.log(`  ✓ regenerated (${regen.ran.join(', ')}) → docs/api/ + docs/api-reference.md + clients/bongos-client/`);
+    else console.error(`  ! API-artifact regen skipped (${regen.reason}) — regenerate in ${dir} by hand; the instance-root fitness gate flags the lag otherwise.`);
+    // Seed the whole-file navigation docs (session-log index) so a fresh instance's docs/ isn't
+    // empty before its first deploy-regen (ADR 0110 / task 1002314). Gitignored on the instance —
+    // this is a local seed; the ongoing refresh is regen-instance-docs.js on deploy + `bongos
+    // upgrade`. Best-effort, mirrors the api-artifacts line: a hiccup warns, never fails init.
+    console.log('\nSeeding the navigation docs from the pinned core (session-log index):');
+    const nav = upgrade.regenerateNavDocs({ instanceDir: dir, coreRoot: resolveCoreRoot() });
+    if (nav.ok) console.log(`  ✓ seeded (${nav.ran.join(', ')}) → docs/`);
+    else console.error(`  ! nav-doc seed incomplete (failed: ${nav.failed.map((f) => f.gen).join(', ')}) — the deploy regen (regen-instance-docs.js) retries.`);
+  }
+
+  let seedResult = {};
+  if (!noSeed) seedResult = (await seedViaApi(spec, { dryRun })) || {};
+  else console.log('  (--no-seed: skipped version/task seeding)');
+
+  console.log(`\n${dryRun ? 'Dry run complete.' : 'Done.'} Next:`);
+  if (Array.isArray(seedResult.failures) && seedResult.failures.length) {
+    console.log(`  ⚠ ${seedResult.failures.length} seed task(s) failed to file (details above) — re-file them by hand or re-run the seed; the tracked checklist is incomplete until they exist.`);
+  }
+  console.log('  • fill the look: hand docs/branding-fill-prompt.md to your own LLM');
+  console.log(`  • sign in as ${spec.firstAdmin} to become the owner, then run \`bongos start\` to see the kickoff tasks`);
+  console.log('  • work through the kickoff tasks the way you would any task: claim → ship');
+  if (seedResult.provisioned) {
+    console.log(`  • the control-plane runner (\`bongos provision run-intents --apply\`) will stand up your hosting — watch it in the hall's Instances panel`);
+  } else if (provisioningRequest(spec) && !dryRun) {
+    console.log('  • provisioning wasn\'t enqueued (module off / request failed) — the manual production-topology task is in your queue');
+  }
+  return 0;
+}
+
+module.exports = {
+  buildBrandingConfig, buildModulesConfig, buildHierarchyConfig, buildReadme, kickoffTasks, normalizeSpec,
+  validateSpec, versionPayload, slugify, writeConfigs, seedViaApi, interview, main,
+  provisioningSlug, provisioningRequest, productionTopologyKickoff,
+  // --adopt (brownfield layering, ADR 0121 / task 2042)
+  mergeCoreDependency, coreDepRange, layerConfigs, layerPackageJson, runAdopt,
+  buildReadmeSection, appendReadmeSection, layerReadme, README_MARKER,
+  KNOWN_MODULES, HOSTING_SHAPES, CORE_PKG,
+  // greenfield installability (ADR 0108 gap 1/4, task 2053)
+  buildInstancePackageJson, coreVersionSafe, INSTANCE_HALL_SCRIPT, INSTANCE_MIGRATE_SCRIPT,
+  // enabled-module dep composition (ADR 0138 / task 2160)
+  moduleDeclaredDeps, enabledModuleDeps,
+};
+
+if (require.main === module) {
+  main(process.argv).then((code) => process.exit(code)).catch((err) => {
+    console.error(`init: ${err.message}`);
+    process.exit(1);
+  });
+}