@bongos/core 1.17.0

package/scripts/gds/init.js

@@ -0,0 +1,903 @@
+#!/usr/bin/env node
+'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/gds/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
+// @cloudbongos/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 @cloudbongos/core .tgz + pin
+//                                       package.json to file:vendor/… + generate package-lock.json,
+//                                       so the scaffold is `npm ci`-installable (ADR 0108 gap 1/4).
+//                                       Without it the scaffold pins the caret range (unresolvable
+//                                       on npm today) — a local/dev scaffold you resolve another way.
+
+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 } = 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', 'dev-box'];
+
+// 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.
+const HOSTING_SHAPES = ['co-tenant', 'dedicated', 'standalone'];
+
+// 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 = '@cloudbongos/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): `start` = the systemd
+// ExecStart (`node <core>/src/platform-server.js`), `migrate` = standaloneMigrateCmd
+// (`bash <core>/scripts/migrate.sh`). Keeping them identical means `npm start` /
+// `npm run migrate` on the instance behave like production, and `bongos upgrade`'s
+// `npm run migrate` step resolves to the core's migrate.sh (ADR 0108).
+const INSTANCE_CORE_PKG_DIR = 'node_modules/@cloudbongos/core';
+const INSTANCE_START_SCRIPT = `node ${INSTANCE_CORE_PKG_DIR}/src/platform-server.js`;
+const INSTANCE_MIGRATE_SCRIPT = `bash ${INSTANCE_CORE_PKG_DIR}/scripts/migrate.sh`;
+
+// PURE (exported for tests) — build/augment the greenfield instance package.json so a
+// fresh instance is `npm ci`-installable and runnable (ADR 0108 greenfield gap 1/4,
+// task 2053): the @cloudbongos/core dependency (the `file:` tarball pin when a tarball is
+// vendored, else the declared caret range — the CARET RESOLVES NOWHERE on npm, which is
+// exactly why the vendored path pins `file:`) plus the start/migrate npm scripts a
+// standalone instance runs. Preserves any pre-existing fields + scripts (fills only what
+// 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().
+function buildInstancePackageJson(existing, { name = 'cloudbongos-instance', coreDep } = {}) {
+  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 : {}) };
+  if (!pkg.scripts.start) pkg.scripts.start = INSTANCE_START_SCRIPT;
+  if (!pkg.scripts.migrate) pkg.scripts.migrate = INSTANCE_MIGRATE_SCRIPT;
+  pkg.dependencies = { ...(isObj(pkg.dependencies) ? pkg.dependencies : {}), [CORE_PKG]: dep };
+  return pkg;
+}
+
+// ---------------------------------------------------------------------------
+// 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/gds/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
+// co-tenant ($0) per the budget DNA (ADR 0111 §6).
+function provisioningRequest(spec) {
+  const p = spec && spec.provisioning;
+  if (!isObj(p)) return null;
+  const shape = HOSTING_SHAPES.includes(p.shape) ? p.shape : 'co-tenant';
+  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 one kickoff step the provisioning module AUTOMATES (ADR 0111 §3): standing up
+// production hosting/TLS/DNS/managed-DB. Kept as a named builder so init can either
+// FILE it (no provisioning requested, or the request couldn't be enqueued) or OMIT
+// it (a request went in — the control-plane runner covers this leg).
+function productionTopologyKickoff() {
+  return {
+    title: 'Production topology: TLS, real origins, managed Postgres',
+    kind: 'infra',
+    description: 'For a real (non-localhost) launch: front the instance with TLS (Caddy/Cloudflare/nginx), point ' +
+      'publicOrigin/buildersOrigin/statusOrigin at the real domain (the OAuth callback depends on this), and move off the bundled container DB volume to managed/backed-up Postgres.',
+  };
+}
+
+// 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 || 'CLOUDBONGOS',
+  };
+  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 `@cloudbongos/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. These are the steps init CANNOT do for you —
+// the human-only setup a fresh instance needs to actually launch (grounded in
+// the onboarding/deploy surfaces; see the task 1204 mapping pass). Each becomes
+// a real, claimable task so it's tracked, never silently skipped. Per-module
+// prerequisites are appended only for the modules the owner enabled.
+function kickoffTasks(spec) {
+  const origin = (spec.domains && spec.domains.publicOrigin) || 'http://localhost:3000';
+  const tasks = [
+    {
+      title: 'Register a GitHub OAuth app and set its credentials',
+      kind: 'infra',
+      description: 'Auth is the hard prerequisite for every sign-in — without it the server returns 503 ' +
+        'auth_not_configured and nobody (including you) can log in. Create a GitHub OAuth app, set ' +
+        `<ENVPREFIX>_GITHUB_CLIENT_ID/SECRET, tick "Enable Device Flow" (a separate save), and set the callback URL to ${origin}/api/gds/auth/web/callback.`,
+    },
+    {
+      title: `Sign in once as ${spec.firstAdmin} to seat the founding owner`,
+      kind: 'infra',
+      description: `A fresh database has no owner. Signing in as the configured firstAdmin (${spec.firstAdmin}) ` +
+        'the first time auto-seats that account as the founding Archon (owner). Config alone does nothing — you must actually sign in.',
+    },
+    {
+      title: 'Confirm the GitHub repo binding and deploy mode',
+      kind: 'infra',
+      description: `This instance ships work to ${spec.repo.owner}/${spec.repo.name}. Confirm the git remote / repo binding ` +
+        'and pick deploy mode in config/deploy.json (ci = server-mediated PR auto-merge, or laptop). A wrong/absent repo binding lets a task grade but never merge.',
+    },
+    {
+      title: 'Set the admission posture and invite the first builders',
+      kind: 'infra',
+      description: 'Enrollment is invite-only by default. Beyond you, no one can join until you approve an access request ' +
+        'or set <ENVPREFIX>_OPEN_XENOS_ENROLLMENT=1. Decide who can join and invite/approve the first builders.',
+    },
+    {
+      title: 'Arm the merge gate before a second builder joins (ci deploy mode)',
+      kind: 'infra',
+      description: 'For a shared instance on ci deploy mode, enable branch protection on main + required checks ' +
+        '(unit / secret-scan / gate-review) + CODEOWNERS, so untrusted builders cannot push straight to production. Skippable for a solo/local instance.',
+    },
+  ];
+  // Production topology is either AUTOMATED (the owner opted into provisioning — the
+  // control-plane runner stands up TLS/DNS/managed-DB) or a tracked manual step.
+  // Keep it in its infra slot, before the look step, when it's still manual. (ADR 0111 §3)
+  if (!provisioningRequest(spec)) tasks.push(productionTopologyKickoff());
+  tasks.push({
+    title: 'Fill the instance look with your own LLM',
+    kind: 'ideator',
+    description: 'init wrote a lean config/branding.json and left the LOOK to you (a locked project rule: brand with your ' +
+      'own LLM, not a generator). Hand docs/branding-fill-prompt.md to your AI to design a palette/fonts/wordmark, or keep the vanilla look.',
+  });
+  const enabled = new Set(Array.isArray(spec.modules) ? spec.modules : []);
+  if (enabled.has('art-pipeline')) {
+    tasks.push({ title: 'Provide a Google Gemini API key for the art pipeline', kind: 'infra',
+      description: 'The art-pipeline module needs a Google AI Studio (Gemini) key (GOOGLE_AI_STUDIO_KEY, a shared key, or per-builder keys) or it cannot generate art.' });
+  }
+  if (enabled.has('discord')) {
+    tasks.push({ title: 'Provide Discord bot token + webhooks', kind: 'infra',
+      description: 'The discord module needs a bot token + webhook URLs + DISCORD_BOT_ENABLED=true. Note: outbound/link surfaces fire on credentials even if the module flag is later turned off.' });
+  }
+  if (enabled.has('dev-box')) {
+    tasks.push({ title: 'Provide a DigitalOcean API token for dev boxes', kind: 'infra',
+      description: 'The dev-box module needs a DigitalOcean API token (and optionally Cloudflare) on the operator control plane before any builder box can be provisioned.' });
+  }
+  return tasks;
+}
+
+// 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 the cheapest co-tenant) 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 : 'co-tenant',
+      ...(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/gds/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') {
+      const shape = (await ask(rl, '  Hosting shape? (co-tenant = share an existing box, $0 / dedicated = its own droplet / standalone = its own repo + pinned @cloudbongos/core, ADR 0108)', 'co-tenant')).toLowerCase();
+      const domain = await ask(rl, '  Domain you own — bring-your-own (blank = none yet)?');
+      const targetRef = await ask(rl, '  Target credential ref? (which control-plane creds the runner should use; optional)');
+      let tier = '';
+      if (shape === 'dedicated') tier = await ask(rl, '  Droplet tier? (e.g. s-1vcpu-2gb; optional)');
+      provisioning = {
+        shape: HOSTING_SHAPES.includes(shape) ? shape : 'co-tenant',
+        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
+// ---------------------------------------------------------------------------
+
+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 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; } }
+  const pkg = buildInstancePackageJson(existingPkg, { name: pkgName, coreDep });
+  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));
+    return { brandingPath, modulesPath, hierarchyPath, pkgPath, 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})`);
+  return { brandingPath, modulesPath, hierarchyPath, pkgPath, 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 @cloudbongos/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/gds/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/gds/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/gds/versions', vp);
+  if (!vres.ok && vres.status !== 409) {
+    throw new Error(`POST /versions failed (${vres.status}): ${JSON.stringify(vres.data)}`);
+  }
+  if (vres.status === 409) log(`  • version ${vp.id} already exists — continuing.`);
+  else log(`  ✓ created version ${vp.id} + 1 done-when goal`);
+  const criterionId = vp.criteria[0].criterion_id;
+
+  // A tracked kickoff/starter task (status ready, engineer discipline). Returns true on success.
+  const postTask = async (t, extra = {}) => {
+    const res = await api('POST', '/api/gds/tasks', {
+      version_id: vp.id, title: t.title, description: t.description || '', status: 'ready',
+      kind: t.kind || 'infra', discipline: 'engineer', source: 'bongos-init', ...extra,
+    });
+    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) {
+    if (await postTask(t, { kind: t.kind || 'unclassified', discipline: undefined, 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/gds/provisioning/instances', pr);
+    if (pres.ok) {
+      provisioned = true;
+      const inst = (pres.data && pres.data.instance) || {};
+      const cost = Number(inst.cost_estimate_usd || 0);
+      log(`  ✓ requested provisioning of instance "${pr.slug}" (${pr.hosting_shape}${pr.domain ? `, ${pr.domain}` : ''})` +
+          `${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`;
+  log(`  ✓ filed ${created} task(s) (${starters.length} starter + ${kickoffLabel})`);
+  return { seeded: true, created, 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.
+async function runAdopt(spec, { dir, dryRun, noSeed = false, accept = false, 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 });
+
+  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}:`);
+    await seedViaApi(spec, { dryRun, log });
+  } 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)
+
+  if (adopt && force) {
+    console.error('init: --force is a greenfield-only overwrite; --adopt never overwrites, so --force is ignored.');
+  }
+
+  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;
+  }
+
+  // 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 });
+
+  // Greenfield 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
+  // just 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.
+  const upgrade = require('./upgrade');
+  let coreDep = null; // null → writeConfigs writes 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 = path.join('vendor', `${upgrade.ARTIFACT}-${version}.tgz`);
+    coreDep = `file:${vendorRel}`;
+    vendorPlan = { tgz, version, vendorRel };
+  }
+
+  console.log(`\nScaffolding "${spec.identity.productName}"${dryRun ? '  (dry run — nothing will be written or created)' : ''}:`);
+  writeConfigs(spec, { dir, force, dryRun, coreDep });
+
+  // Vendor the pinned @cloudbongos/core tarball + generate the lockfile so the scaffold is
+  // `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 @cloudbongos/core + generating the lockfile:');
+      upgrade.vendorTarball({ instanceDir: dir, fromTgz: vendorPlan.tgz, targetVersion: vendorPlan.version });
+      console.log(`  ✓ vendored ${vendorPlan.vendorRel}`);
+      const inst = upgrade.npmInstall(dir);
+      if (!inst.ok) {
+        console.error(`  ! npm install failed (${inst.reason || 'exit ' + inst.code}) — package-lock.json not generated; run \`npm install\` in ${dir} by hand before provisioning.`);
+      } else {
+        console.log('  ✓ npm install → package-lock.json generated (node_modules/@cloudbongos/core installed)');
+      }
+    }
+  }
+
+  // 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 });
+
+  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:`);
+  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, kickoffTasks, normalizeSpec,
+  validateSpec, versionPayload, slugify, writeConfigs, seedViaApi, interview, main,
+  provisioningSlug, provisioningRequest, productionTopologyKickoff,
+  // --adopt (brownfield layering, ADR 0121 / task 2042)
+  mergeCoreDependency, coreDepRange, layerConfigs, layerPackageJson, runAdopt,
+  KNOWN_MODULES, HOSTING_SHAPES, CORE_PKG,
+  // greenfield installability (ADR 0108 gap 1/4, task 2053)
+  buildInstancePackageJson, coreVersionSafe, INSTANCE_START_SCRIPT, INSTANCE_MIGRATE_SCRIPT,
+};
+
+if (require.main === module) {
+  main(process.argv).then((code) => process.exit(code)).catch((err) => {
+    console.error(`init: ${err.message}`);
+    process.exit(1);
+  });
+}