@bongos/core 1.21.174 → 1.21.176

package/scripts/gds/init.js

@@ -1,1159 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/init.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/init.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-//
-// scripts/gds/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/gds/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/gds/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/gds/<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);
-  });
-}
+require('../bongos/forwarder.js').forward(module, 'init.js');