@businessdash/sdk 0.9.60

package/src/cli.ts

@@ -0,0 +1,2517 @@
+#!/usr/bin/env node
+/**
+ * `biab-dev` CLI entry point.
+ *
+ * Two independent flows, deliberately sharing nothing but transport
+ * conventions — a website's content shape and an org's database shape are
+ * different artifacts, with different review cadence and blast radius.
+ *
+ * WEBSITE CONTENT (`biab.config.{ts,mjs,js}`):
+ *   - `sync-schema`      — resolve the config, compute the canonical SHA-256,
+ *                          POST to the draft-schema endpoint. Idempotent.
+ *   - `sync-content`     — walk `<contentSync.rootDir>/<locale>/<page>/
+ *                          <section>.json`, batch, POST to bulk-sections.
+ *                          Per-row failures are reported but don't abort.
+ *   - `print-schema`     — resolved schema + checksum, no upload.
+ *
+ * CUSTOM DATABASE (`biab.data-model.config.{ts,mjs,js}`):
+ *   - `view-data-model`  — what's LIVE (not what was last pushed — the
+ *                          dashboard writes this model too). `--diff` for the
+ *                          migration plan, `--out` to scaffold a config.
+ *   - `print-data-model` — resolved local config + checksum, no network.
+ *   - `sync-data-model`  — push to the draft slot. Prints the plan first.
+ *   - `sync-records`     — upsert rows from JSON, keyed on row identity so
+ *                          re-running converges instead of duplicating.
+ *   - `wipe-collections` — hard-delete records from explicitly named custom
+ *                          collections, only after a verified Media backup and
+ *                          two interactive confirmations.
+ *
+ * The CLI never promotes, restores, or inspects schema history. Those live in the
+ * dashboard, gated on the operator's permission (`website.manage` /
+ * `metadata.manage`), NOT on the API key. Wiping records is the deliberately
+ * destructive exception: it requires a user-bound secret key, a state-bound
+ * preview, a verified backup in Media, and typed confirmation. The schema
+ * invariant still holds: **a key proposes, a human promotes.** A schema key
+ * cannot promote a draft or change what visitors see. The wipe endpoint does
+ * change record contents, so its backup and confirmation guards are
+ * load-bearing.
+ *
+ * Auth: `BIAB_API_KEY`, `BIAB_SITE_ID`, and `BIAB_PACKAGE_API_BASE_URL` from
+ * the environment (or a `.env` / `.env.local` in the cwd). Scopes:
+ * `marketing:write_schema` / `marketing:write_content` for the website flow;
+ * `metadata:read_schema` (view/plan), `metadata:write_schema` (push), and
+ * `metadata:write_records` (seed/wipe) for the data model.
+ */
+
+import {
+	existsSync,
+	readdirSync,
+	readFileSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { pathToFileURL } from "node:url";
+import {
+	computeDataModelChecksum,
+	type GeneratedFormCandidate,
+} from "./data-model-schema.js";
+import { dataModelToGraphqlSdl, type GraphqlSdlModel } from "./graphql.js";
+import type {
+	SiteMarketingClientShape,
+	SiteMarketingContentSyncConfig,
+} from "./marketing-schema.js";
+import {
+	isReservedPagePath,
+	reservedPagePathErrorMessage,
+} from "./reserved-paths.js";
+
+const COMMANDS = [
+	"sync-schema",
+	"sync-content",
+	"print-schema",
+	// Data model (custom database). Separate config, separate endpoint,
+	// separate scopes — see data-model-schema.ts.
+	"view-data-model",
+	"print-data-model",
+	"export-data-model",
+	"export-graphql-schema",
+	"sync-data-model",
+	"sync-records",
+	"wipe-collections",
+	"wipe-database",
+	"help",
+] as const;
+type Command = (typeof COMMANDS)[number];
+
+/** Config candidates per flow. The marketing and data-model configs are
+ *  deliberately different files: different artifacts, different blast radius.
+ *  `businessdash.*` names are preferred going forward; the `biab.*` names
+ *  remain a permanent filesystem contract with every existing consumer. */
+const MARKETING_CONFIG_CANDIDATES = [
+	"businessdash.config.ts",
+	"businessdash.config.mjs",
+	"businessdash.config.js",
+	"biab.config.ts",
+	"biab.config.mjs",
+	"biab.config.js",
+];
+const DATA_MODEL_CONFIG_CANDIDATES = [
+	"businessdash.data-model.config.ts",
+	"businessdash.data-model.config.mjs",
+	"businessdash.data-model.config.js",
+	"biab.data-model.config.ts",
+	"biab.data-model.config.mjs",
+	"biab.data-model.config.js",
+];
+
+// V7-styled output: matches the dashboard's status-pill colors so the
+// CLI feels like the same product (✓ = "done" green-accent, ⚠ =
+// "partial" orange-accent, ✕ = "missing" red-accent). We only emit
+// ANSI when stdout is a TTY so CI logs stay plain.
+const USE_COLOR = process.stdout.isTTY && !process.env["NO_COLOR"];
+const fg = {
+	green: (s: string) => (USE_COLOR ? `\x1b[32m${s}\x1b[0m` : s),
+	red: (s: string) => (USE_COLOR ? `\x1b[31m${s}\x1b[0m` : s),
+	amber: (s: string) => (USE_COLOR ? `\x1b[33m${s}\x1b[0m` : s),
+	dim: (s: string) => (USE_COLOR ? `\x1b[2m${s}\x1b[0m` : s),
+	bold: (s: string) => (USE_COLOR ? `\x1b[1m${s}\x1b[0m` : s),
+};
+
+function logStep(msg: string): void {
+	console.log(`[biab-dev] ${msg}`);
+}
+
+/**
+ * A single progress line for long, batched work.
+ *
+ * On a TTY it rewrites one line in place (`\r` + erase), so a run with many
+ * network round-trips shows live movement instead of a silent wait. Without a
+ * TTY (CI) it prints a plain line per tick — no carriage returns to mangle the
+ * log, just a bounded trail of progress.
+ *
+ * `tick(0)` up front makes the line appear before the first round-trip returns,
+ * so the user sees it engage rather than staring at nothing.
+ */
+function makeProgress(total: number): {
+	tick: (done: number, note?: string) => void;
+	clear: () => void;
+} {
+	const tty = Boolean(process.stdout.isTTY);
+	return {
+		tick(done, note = "") {
+			const pct = total === 0 ? 100 : Math.floor((done / total) * 100);
+			// No nested color: the whole line is dimmed, so the note stays plain
+			// text (a reset inside would cancel the dim for everything after it).
+			const line = `  ↻ ${done}/${total} (${pct}%)${note ? ` · ${note}` : ""}`;
+			if (tty) process.stdout.write(`\r\x1b[2K${fg.dim(line)}`);
+			else console.log(line);
+		},
+		clear() {
+			if (tty) process.stdout.write("\r\x1b[2K");
+		},
+	};
+}
+
+function logError(msg: string): void {
+	console.error(`[biab-dev] ${msg}`);
+}
+
+function parseEnvFile(path: string): Record<string, string> {
+	if (!existsSync(path)) return {};
+	const out: Record<string, string> = {};
+	for (const raw of readFileSync(path, "utf8").split(/\r?\n/)) {
+		const line = raw.trim();
+		if (!line || line.startsWith("#")) continue;
+		const eq = line.indexOf("=");
+		if (eq === -1) continue;
+		const key = line.slice(0, eq).trim();
+		let value = line.slice(eq + 1).trim();
+		if (
+			(value.startsWith('"') && value.endsWith('"')) ||
+			(value.startsWith("'") && value.endsWith("'"))
+		) {
+			value = value.slice(1, -1);
+		}
+		if (key && value !== undefined) out[key] = value;
+	}
+	return out;
+}
+
+function loadEnv(cwd: string): Record<string, string> {
+	const merged: Record<string, string> = {
+		...parseEnvFile(resolve(cwd, ".env")),
+		...parseEnvFile(resolve(cwd, ".env.local")),
+		...(process.env as Record<string, string>),
+	};
+	return merged;
+}
+
+function findConfigPath(
+	cwd: string,
+	override?: string,
+	candidates: string[] = MARKETING_CONFIG_CANDIDATES,
+	hint = "Create one with `defineSiteMarketingSchema({...})` exported as default.",
+): string {
+	if (override) {
+		const p = isAbsolute(override) ? override : resolve(cwd, override);
+		if (!existsSync(p)) throw new Error(`Config not found at ${p}`);
+		return p;
+	}
+	for (const candidate of candidates) {
+		const p = resolve(cwd, candidate);
+		if (existsSync(p)) return p;
+	}
+	const names = candidates.join(", ");
+	throw new Error(`None of [${names}] found in ${cwd}. ${hint}`);
+}
+
+function findDataModelConfigPath(cwd: string, override?: string): string {
+	return findConfigPath(
+		cwd,
+		override,
+		DATA_MODEL_CONFIG_CANDIDATES,
+		"Create one with `defineDataModel({...})` exported as default.",
+	);
+}
+
+/**
+ * Load the consumer's `biab.config.*`. Supports .ts (via the
+ * consumer's tsx / ts-node setup — we only invoke if `--require tsx`
+ * or `tsx`/`ts-node` registered the loader), .mjs (native ESM), and
+ * .js (CJS or ESM depending on package.json).
+ */
+async function loadConfig(
+	configPath: string,
+): Promise<SiteMarketingClientShape<Record<string, never>>> {
+	const url = pathToFileURL(configPath).href;
+	let mod: { default?: unknown; marketing?: unknown };
+	try {
+		mod = (await import(url)) as typeof mod;
+	} catch (err) {
+		if (configPath.endsWith(".ts")) {
+			throw new Error(
+				`Could not load TypeScript config at ${configPath}. Run the CLI under tsx or ts-node, e.g.: ` +
+					`\`pnpm exec tsx node_modules/@businessdash/sdk/dist/cli.js sync-schema\`.\nUnderlying: ${
+						err instanceof Error ? err.message : String(err)
+					}`,
+			);
+		}
+		throw err;
+	}
+	const fromDefault = mod.default;
+	const fromNamed = mod.marketing;
+	const chosen = fromDefault ?? fromNamed;
+	if (
+		!chosen ||
+		typeof (chosen as { toJSONSchema?: unknown }).toJSONSchema !== "function"
+	) {
+		throw new Error(
+			`${configPath} did not export a marketing schema. Default-export the result of \`defineSiteMarketingSchema({...})\` (or named-export it as \`marketing\`).`,
+		);
+	}
+	return chosen as SiteMarketingClientShape<Record<string, never>>;
+}
+
+function normalizeBaseUrl(input: string): string {
+	let next = input.trim();
+	if (!/^https?:\/\//i.test(next)) {
+		throw new Error(
+			`BIAB_PACKAGE_API_BASE_URL must start with http(s):// — got "${input}".`,
+		);
+	}
+	if (!next.endsWith("/api/package/v1") && !next.endsWith("/api/package/v1/")) {
+		// Accept either the bare host or the full prefix; canonicalize to
+		// "<origin>/api/package/v1".
+		next = next.replace(/\/+$/, "");
+		next = `${next}/api/package/v1`;
+	}
+	return next.replace(/\/+$/, "");
+}
+
+async function cmdPrintSchema(opts: { configPath: string }) {
+	const schema = await loadConfig(opts.configPath);
+	const artifact = schema.toJSONSchema();
+	const checksum = await schema.checksum();
+	console.log(JSON.stringify({ checksum, artifact }, null, 2));
+}
+
+async function cmdSyncSchema(opts: {
+	configPath: string;
+	env: Record<string, string>;
+	dryRun: boolean;
+}) {
+	const schema = await loadConfig(opts.configPath);
+	const artifact = schema.toJSONSchema();
+	const checksum = await schema.checksum();
+
+	// Reject any `contentSync.pages[].pageKey` that collides with a BIAB
+	// platform-reserved route. Catches the misconfiguration before any
+	// upload happens.
+	const declaredPages = schema.contentSync?.pages ?? [];
+	const reservedDeclared = declaredPages.filter((p) =>
+		isReservedPagePath(p.pageKey),
+	);
+	if (reservedDeclared.length > 0) {
+		for (const p of reservedDeclared) {
+			logError(reservedPagePathErrorMessage(p.pageKey));
+		}
+		throw new Error(
+			`Refusing to sync schema: ${reservedDeclared.length} reserved pageKey(s) declared in contentSync.pages.`,
+		);
+	}
+
+	logStep(
+		`Loaded schema with ${Object.keys(artifact.sections).length} section(s).`,
+	);
+	logStep(`Checksum: ${checksum}`);
+
+	if (opts.dryRun) {
+		logStep("--dry-run was set, skipping upload.");
+		return;
+	}
+
+	const apiKey = opts.env["BIAB_API_KEY"];
+	const siteId = opts.env["BIAB_SITE_ID"];
+	const rawBase =
+		opts.env["BIAB_PACKAGE_API_BASE_URL"] ??
+		opts.env["NEXT_PUBLIC_BIAB_PACKAGE_API_BASE_URL"];
+	if (!apiKey) throw new Error("Missing BIAB_API_KEY in env or .env.local.");
+	if (!siteId) throw new Error("Missing BIAB_SITE_ID in env or .env.local.");
+	if (!rawBase) {
+		throw new Error(
+			"Missing BIAB_PACKAGE_API_BASE_URL in env or .env.local (e.g. https://your-host.tld/api/package/v1).",
+		);
+	}
+
+	const baseUrl = normalizeBaseUrl(rawBase);
+	const target = `${baseUrl}/sites/${encodeURIComponent(siteId)}/marketing/draft-schema`;
+	logStep(`POST ${target}`);
+
+	const res = await fetch(target, {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			authorization: `Bearer ${apiKey}`,
+		},
+		body: JSON.stringify({
+			schema: artifact,
+			checksum,
+		}),
+	});
+
+	const bodyText = await res.text();
+	type ResponseBody = {
+		ok?: boolean;
+		noop?: boolean;
+		version?: number;
+		message?: string;
+	};
+	let body: ResponseBody | null = null;
+	try {
+		body = JSON.parse(bodyText) as ResponseBody;
+	} catch {
+		body = null;
+	}
+
+	if (!res.ok) {
+		logError(`Upload failed (${res.status} ${res.statusText}).`);
+		if (body?.message) logError(`Server: ${body.message}`);
+		else logError(`Raw response: ${bodyText.slice(0, 500)}`);
+		process.exitCode = 1;
+		return;
+	}
+
+	if (body?.noop) {
+		logStep(`No changes — schema already at v${body.version}.`);
+	} else if (body?.version) {
+		logStep(`Uploaded draft v${body.version}.`);
+		logStep(
+			"Promote in the dashboard at Site Builder → Site Data → Schema to make this live.",
+		);
+	} else {
+		logStep("Upload succeeded.");
+	}
+}
+
+// ── data model (custom database) ──────────────────────────────────────
+
+type DataModelShape = {
+	toJSONSchema(): Record<string, unknown>;
+	checksum(): Promise<string>;
+};
+
+type LoadedDataModelConfig = {
+	model: DataModelShape;
+	generatedForms: GeneratedFormCandidate[];
+};
+
+/**
+ * Load either a plain data model or createFormSchemaOrchestrator() output.
+ * The latter intentionally keeps its database artifact and generated form
+ * candidates together in one config.
+ */
+async function loadDataModelConfig(
+	configPath: string,
+): Promise<LoadedDataModelConfig> {
+	const url = pathToFileURL(configPath).href;
+	let mod: { default?: unknown; dataModel?: unknown };
+	try {
+		mod = (await import(url)) as typeof mod;
+	} catch (err) {
+		if (configPath.endsWith(".ts")) {
+			throw new Error(
+				`Could not load TypeScript config at ${configPath}. Run the CLI under tsx or ts-node, e.g.: ` +
+					`\`npx tsx node_modules/@businessdash/sdk/dist/cli.js sync-data-model\`.\nUnderlying: ${
+						err instanceof Error ? err.message : String(err)
+					}`,
+			);
+		}
+		throw err;
+	}
+	const chosen = mod.default ?? mod.dataModel;
+	const orchestrated = chosen as
+		| {
+				databaseSchema?: unknown;
+				generatedForms?: unknown;
+		  }
+		| undefined;
+	const model = orchestrated?.databaseSchema ?? chosen;
+	if (
+		!model ||
+		typeof (model as { toJSONSchema?: unknown }).toJSONSchema !== "function"
+	) {
+		throw new Error(
+			`${configPath} did not export a data model. Default-export createSchema(...) or createFormSchemaOrchestrator(...).`,
+		);
+	}
+	return {
+		model: model as DataModelShape,
+		generatedForms: Array.isArray(orchestrated?.generatedForms)
+			? (orchestrated.generatedForms as GeneratedFormCandidate[])
+			: [],
+	};
+}
+
+type ApiTarget = { baseUrl: string; apiKey: string; siteId: string };
+
+function resolveApiTarget(env: Record<string, string>): ApiTarget {
+	const apiKey = env["BIAB_API_KEY"];
+	const siteId = env["BIAB_SITE_ID"];
+	const rawBase =
+		env["BIAB_PACKAGE_API_BASE_URL"] ??
+		env["NEXT_PUBLIC_BIAB_PACKAGE_API_BASE_URL"];
+	if (!apiKey) throw new Error("Missing BIAB_API_KEY in env or .env.local.");
+	if (!siteId) throw new Error("Missing BIAB_SITE_ID in env or .env.local.");
+	if (!rawBase) {
+		throw new Error(
+			"Missing BIAB_PACKAGE_API_BASE_URL in env or .env.local (e.g. https://your-host.tld/api/package/v1).",
+		);
+	}
+	return { baseUrl: normalizeBaseUrl(rawBase), apiKey, siteId };
+}
+
+async function callDataModelApi(input: {
+	target: ApiTarget;
+	path: string;
+	method: "GET" | "POST";
+	body?: unknown;
+}): Promise<Record<string, unknown>> {
+	const { target, path, method, body } = input;
+	const url = `${target.baseUrl}/sites/${encodeURIComponent(target.siteId)}/data-model/${path}`;
+	const res = await fetch(url, {
+		method,
+		headers: {
+			"content-type": "application/json",
+			authorization: `Bearer ${target.apiKey}`,
+		},
+		...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+	});
+	const text = await res.text();
+	let parsed: Record<string, unknown> | null = null;
+	try {
+		parsed = JSON.parse(text) as Record<string, unknown>;
+	} catch {
+		parsed = null;
+	}
+	if (!res.ok) {
+		const message =
+			typeof parsed?.["message"] === "string"
+				? parsed["message"]
+				: `HTTP ${res.status} ${res.statusText} — ${text.slice(0, 240)}`;
+		throw new Error(message);
+	}
+	if (!parsed) {
+		throw new Error(
+			`Server replied ${res.status} but the body wasn't JSON — first 240 chars: ${text.slice(0, 240)}`,
+		);
+	}
+	return parsed;
+}
+
+type PlanChange = {
+	class: "safe" | "backfill" | "destructive" | "exposure";
+	kind: string;
+	object: string;
+	field?: string;
+	option?: string;
+	summary: string;
+	risk?: string;
+};
+type MigrationPlan = {
+	changes: PlanChange[];
+	counts: {
+		safe: number;
+		backfill: number;
+		destructive: number;
+		exposure: number;
+	};
+	hasDestructive: boolean;
+	hasExposure: boolean;
+	unmanaged: Array<{ object: string; field?: string }>;
+};
+
+/**
+ * Render a migration plan. Grouped by class rather than by object, because the
+ * question a developer is actually asking is "is this safe?" — not "what
+ * changed on permits?".
+ */
+function printPlan(plan: MigrationPlan): void {
+	if (plan.changes.length === 0) {
+		console.log(`  ${fg.dim("No changes — the live model already matches.")}`);
+	}
+
+	const order = ["exposure", "destructive", "backfill", "safe"] as const;
+	const marks = {
+		exposure: fg.red("◉"),
+		destructive: fg.red("✕"),
+		backfill: fg.amber("⚠"),
+		safe: fg.green("✓"),
+	};
+	for (const cls of order) {
+		const changes = plan.changes.filter((c) => c.class === cls);
+		if (changes.length === 0) continue;
+		console.log("");
+		console.log(`  ${fg.bold(cls.toUpperCase())} (${changes.length})`);
+		for (const change of changes) {
+			console.log(`    ${marks[cls]} ${change.summary}`);
+			if (change.risk) console.log(`      ${fg.dim(change.risk)}`);
+		}
+	}
+
+	if (plan.unmanaged.length > 0) {
+		console.log("");
+		console.log(
+			`  ${fg.dim(`${plan.unmanaged.length} live object/field(s) aren't in this config. They're left alone — pass --prune to remove them.`)}`,
+		);
+		for (const item of plan.unmanaged) {
+			const label = item.field ? `${item.object}.${item.field}` : item.object;
+			console.log(`      ${fg.dim(`· ${label}`)}`);
+		}
+	}
+
+	if (plan.hasExposure) {
+		console.log("");
+		console.log(
+			`  ${fg.red("This plan changes who can READ your data.")} ${fg.dim("Opening a table to signed-in customers or the public is confirmed separately in the dashboard, and can't be undone for data that's already been read.")}`,
+		);
+	}
+
+	if (plan.hasDestructive) {
+		console.log("");
+		console.log(
+			`  ${fg.red("This plan contains destructive changes.")} ${fg.dim("They need an explicit confirmation in the dashboard before they apply.")}`,
+		);
+	}
+}
+
+async function cmdPrintDataModel(opts: { configPath: string }) {
+	const loaded = await loadDataModelConfig(opts.configPath);
+	const artifact: Record<string, unknown> = {
+		...loaded.model.toJSONSchema(),
+		...(loaded.generatedForms.length > 0
+			? { generatedForms: loaded.generatedForms }
+			: {}),
+	};
+	const checksum = await computeDataModelChecksum(artifact);
+	console.log(JSON.stringify({ checksum, artifact }, null, 2));
+}
+
+/**
+ * What's actually live — read from the metadata engine, not from whatever was
+ * last pushed. The dashboard is a second writer, so those differ.
+ */
+async function cmdViewDataModel(opts: {
+	env: Record<string, string>;
+	json: boolean;
+	diff: boolean;
+	out: string | null;
+	configOverride: string | undefined;
+	cwd: string;
+	prune: boolean;
+}) {
+	const target = resolveApiTarget(opts.env);
+	const res = await callDataModelApi({ target, path: "live", method: "GET" });
+	const model = res["model"] as { objects?: unknown[] } | undefined;
+	const objects = (model?.objects ?? []) as Array<{
+		nameSingular: string;
+		namePlural: string;
+		kind: string;
+		fields: Array<{ name: string; type: string; options?: unknown[] }>;
+	}>;
+
+	if (opts.json) {
+		console.log(JSON.stringify(res, null, 2));
+		return;
+	}
+
+	if (opts.diff) {
+		const configPath = findDataModelConfigPath(opts.cwd, opts.configOverride);
+		const local = await loadDataModelConfig(configPath);
+		const planRes = await callDataModelApi({
+			target,
+			path: "plan",
+			method: "POST",
+			body: { schema: local.model.toJSONSchema(), prune: opts.prune },
+		});
+		logStep("Plan (local config vs live model):");
+		printPlan(planRes["plan"] as MigrationPlan);
+		return;
+	}
+
+	if (opts.out) {
+		const path = isAbsolute(opts.out) ? opts.out : resolve(opts.cwd, opts.out);
+		writeFileSync(path, renderConfigModule(objects), "utf8");
+		logStep(`${fg.green("✓")} Wrote ${path}`);
+		logStep(
+			fg.dim(
+				"Review it, then `sync-data-model` to push. Your model is code from here on.",
+			),
+		);
+		return;
+	}
+
+	logStep(
+		`Live model — ${fg.bold(String(objects.length))} object(s) ${fg.dim(`(checksum ${String(res["checksum"]).slice(0, 12)}…)`)}`,
+	);
+	for (const object of objects) {
+		const tag = object.kind === "standard" ? fg.dim(" (standard)") : "";
+		console.log("");
+		console.log(`  ${fg.bold(object.namePlural)}${tag}`);
+		for (const field of object.fields ?? []) {
+			const enumValues = Array.isArray(field.options)
+				? fg.dim(
+						` [${(field.options as Array<{ value: string }>).map((o) => o.value).join(", ")}]`,
+					)
+				: "";
+			console.log(`    ${field.name} ${fg.dim(field.type)}${enumValues}`);
+		}
+	}
+}
+
+/**
+ * Pull the ENTIRE custom database — schema + records + relations — into one
+ * portable snapshot file. The read side `view-data-model` never had: it emits
+ * the schema, but records could only be pushed IN (`sync-records`), never
+ * pulled OUT.
+ *
+ * Commit the file next to your code and it becomes a Drizzle/Convex-style
+ * snapshot: deterministic ordering means successive exports git-diff cleanly,
+ * so an AI agent (or a human) can read the collection's state and how it
+ * changed over time without querying BIAB live. It also re-seeds a fresh org —
+ * the `schema` half is the same shape `sync-data-model` pushes, the `records`
+ * half is the same shape `sync-records` ingests.
+ */
+async function cmdExportDataModel(opts: {
+	env: Record<string, string>;
+	out: string | null;
+	schemaOnly: boolean;
+	cwd: string;
+}) {
+	const target = resolveApiTarget(opts.env);
+	const path = opts.schemaOnly ? "export?records=0" : "export";
+	const res = await callDataModelApi({ target, path, method: "GET" });
+	const seed = res["seed"] as
+		| {
+				checksum: string;
+				counts: {
+					objects: number;
+					customObjects: number;
+					records: number;
+					syntheticIdentifiers: number;
+					truncated: boolean;
+				};
+		  }
+		| undefined;
+	if (!seed) {
+		throw new Error("Server did not return a seed. Check your key's scopes.");
+	}
+
+	const outPath = opts.out
+		? isAbsolute(opts.out)
+			? opts.out
+			: resolve(opts.cwd, opts.out)
+		: resolve(opts.cwd, "biab.data-model.snapshot.json");
+	writeFileSync(outPath, `${JSON.stringify(seed, null, 2)}\n`, "utf8");
+
+	const c = seed.counts;
+	logStep(`${fg.green("✓")} Wrote ${outPath}`);
+	logStep(
+		fg.dim(
+			`${c.customObjects} custom object(s), ${c.records} record(s)` +
+				(opts.schemaOnly ? " (schema only)" : "") +
+				` · checksum ${seed.checksum.slice(0, 12)}…`,
+		),
+	);
+	if (c.syntheticIdentifiers > 0) {
+		logStep(
+			fg.amber(
+				`⚠ ${c.syntheticIdentifiers} dashboard-authored row(s) were given a synthetic id. Re-seeding those into the SAME org duplicates them — target a fresh org.`,
+			),
+		);
+	}
+	if (c.truncated) {
+		logStep(
+			fg.amber(
+				"⚠ An object hit the per-object cap; some rows were left out. Pass --out to a full export or page the records endpoint.",
+			),
+		);
+	}
+	logStep(
+		fg.dim(
+			"Commit this file. Re-seed with `sync-data-model` (schema) + `sync-records` (rows).",
+		),
+	);
+}
+
+/**
+ * Emit a GraphQL SDL schema of the org's custom data model.
+ *
+ * "GraphQL layer compatibility": a real, typed GraphQL schema of the custom
+ * collections that any GraphQL codegen / tooling can consume, and that an AI
+ * agent can read next to an `export-data-model` snapshot — the schema of the
+ * data beside the data. This emits the SCHEMA; it does not stand up a GraphQL
+ * server (execution is a separate layer).
+ *
+ * Reads the live model (same source as `view-data-model`) and renders SDL
+ * locally — no server-side GraphQL runtime involved.
+ */
+async function cmdExportGraphqlSchema(opts: {
+	env: Record<string, string>;
+	out: string | null;
+	includeStandard: boolean;
+	cwd: string;
+}) {
+	const target = resolveApiTarget(opts.env);
+	const res = await callDataModelApi({ target, path: "live", method: "GET" });
+	const model = res["model"] as GraphqlSdlModel | undefined;
+	if (!model?.objects) {
+		throw new Error("Server did not return a model. Check your key's scopes.");
+	}
+	const sdl = dataModelToGraphqlSdl(model, {
+		includeStandard: opts.includeStandard,
+	});
+
+	const outPath = opts.out
+		? isAbsolute(opts.out)
+			? opts.out
+			: resolve(opts.cwd, opts.out)
+		: resolve(opts.cwd, "biab.data-model.graphql");
+	writeFileSync(outPath, sdl, "utf8");
+
+	const typeCount = (sdl.match(/^type \w/gm) ?? []).length;
+	logStep(`${fg.green("✓")} Wrote ${outPath}`);
+	logStep(
+		fg.dim(
+			`${typeCount} GraphQL type(s)${opts.includeStandard ? " (incl. standard)" : ""}. Feed it to codegen or commit it as a contract.`,
+		),
+	);
+}
+
+/**
+ * Scaffold a config from live state. The adoption path for an org that already
+ * built its model in the dashboard — without it, data-model-as-code would only
+ * serve greenfield orgs.
+ */
+function renderConfigModule(
+	objects: Array<{
+		universalIdentifier?: string;
+		nameSingular: string;
+		namePlural: string;
+		labelSingular?: string;
+		labelPlural?: string;
+		kind: string;
+		labelIdentifierFieldName?: string;
+		standardEntityName?: string;
+		fields: Array<Record<string, unknown>>;
+	}>,
+): string {
+	const lines: string[] = [
+		"// Generated by `biab-dev view-data-model --out`.",
+		"// This is your org's live data model, as code. Edit it, push it with",
+		"// `biab-dev sync-data-model`, then promote in the dashboard.",
+		"",
+		'import { createSchema, defineCollection, defineField } from "@businessdash/sdk";',
+		"",
+		"export default createSchema({",
+		"\tcollections: [",
+	];
+	for (const object of objects) {
+		lines.push("\t\tdefineField({");
+		lines.push(
+			`\t\t\tuniversalIdentifier: ${JSON.stringify(object.universalIdentifier)},`,
+		);
+		if (object.kind === "standard") {
+			lines.push('\t\t\tkind: "standard",');
+			lines.push(
+				`\t\t\tstandardEntityName: ${JSON.stringify(object.standardEntityName)},`,
+			);
+		}
+		lines.push(`\t\t\tnameSingular: ${JSON.stringify(object.nameSingular)},`);
+		lines.push(`\t\t\tnamePlural: ${JSON.stringify(object.namePlural)},`);
+		lines.push(`\t\t\tlabelSingular: ${JSON.stringify(object.labelSingular)},`);
+		lines.push(`\t\t\tlabelPlural: ${JSON.stringify(object.labelPlural)},`);
+		if (object.labelIdentifierFieldName) {
+			lines.push(
+				`\t\t\tlabelIdentifierFieldName: ${JSON.stringify(object.labelIdentifierFieldName)},`,
+			);
+		}
+		lines.push("\t\t\tfields: [");
+		for (const field of object.fields ?? []) {
+			lines.push(`\t\t\t\tdefineCollection(${JSON.stringify(field)}),`);
+		}
+		lines.push("\t\t\t],");
+		lines.push("\t\t}),");
+	}
+	lines.push("\t],");
+	lines.push("})");
+	lines.push("");
+	return lines.join("\n");
+}
+
+async function cmdSyncDataModel(opts: {
+	configPath: string;
+	env: Record<string, string>;
+	dryRun: boolean;
+	prune: boolean;
+	note: string | null;
+	forms: string;
+}) {
+	const loaded = await loadDataModelConfig(opts.configPath);
+	const selectedForms = await selectGeneratedForms(
+		loaded.generatedForms,
+		opts.forms,
+	);
+	const artifact: Record<string, unknown> = {
+		...loaded.model.toJSONSchema(),
+		...(selectedForms.length > 0 ? { generatedForms: selectedForms } : {}),
+	};
+	const checksum = await computeDataModelChecksum(artifact);
+	const objects = (artifact["objects"] ?? []) as unknown[];
+
+	logStep(`Loaded data model with ${objects.length} object(s).`);
+	if (loaded.generatedForms.length > 0) {
+		logStep(
+			`Including ${selectedForms.length}/${loaded.generatedForms.length} generated inactive form draft(s).`,
+		);
+	}
+	logStep(`Checksum: ${checksum}`);
+
+	const target = resolveApiTarget(opts.env);
+
+	// Always plan before pushing. A push is harmless on its own — it only
+	// writes the draft slot — but showing what promoting it WOULD do is the
+	// whole point of the flow, and it costs one request.
+	const planRes = await callDataModelApi({
+		target,
+		path: "plan",
+		method: "POST",
+		body: { schema: artifact, prune: opts.prune },
+	});
+	const plan = planRes["plan"] as MigrationPlan;
+	console.log("");
+	logStep("Plan (what promoting this would do):");
+	printPlan(plan);
+	console.log("");
+
+	if (opts.dryRun) {
+		logStep("--dry-run was set, skipping upload.");
+		return;
+	}
+
+	const res = await callDataModelApi({
+		target,
+		path: "draft-schema",
+		method: "POST",
+		body: { schema: artifact, checksum, note: opts.note },
+	});
+
+	if (res["noop"]) {
+		logStep(`No changes — the draft is already at v${String(res["version"])}.`);
+		return;
+	}
+	logStep(`${fg.green("✓")} Uploaded draft v${String(res["version"])}.`);
+	logStep(
+		fg.dim(
+			"Nothing has changed yet. Promote in the dashboard at Site Builder → Site Data → Database to apply the collections and create/update the selected forms as inactive drafts.",
+		),
+	);
+}
+
+async function selectGeneratedForms(
+	candidates: GeneratedFormCandidate[],
+	mode: string,
+): Promise<GeneratedFormCandidate[]> {
+	if (candidates.length === 0 || mode === "none") return [];
+	if (mode === "all") return candidates;
+	if (mode.startsWith("list:")) {
+		const requested = new Set(
+			mode
+				.slice(5)
+				.split(",")
+				.map((value) => value.trim())
+				.filter(Boolean),
+		);
+		const selected = candidates.filter(
+			(candidate) =>
+				requested.has(candidate.slug) || requested.has(candidate.sourceKey),
+		);
+		const found = new Set(
+			selected.flatMap((candidate) => [candidate.slug, candidate.sourceKey]),
+		);
+		const unknown = [...requested].filter((value) => !found.has(value));
+		if (unknown.length > 0) {
+			throw new Error(
+				`Unknown generated form candidate(s): ${unknown.join(", ")}. Available slugs: ${candidates.map((candidate) => candidate.slug).join(", ")}.`,
+			);
+		}
+		return selected;
+	}
+
+	// CI/non-interactive runs remain deterministic and useful: all candidates
+	// are included, but promotion still creates them inactive.
+	if (!process.stdin.isTTY || !process.stdout.isTTY) return candidates;
+
+	console.log("");
+	logStep("Generated form candidates (all selected by default):");
+	candidates.forEach((candidate, index) => {
+		console.log(
+			`  ${index + 1}. ${candidate.name} ${fg.dim(`(${candidate.slug}, ${candidate.fields.length} fields)`)}`,
+		);
+	});
+	const prompt = createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+	const answer = await prompt.question(
+		"Select forms by number (comma-separated), press Enter for all, or type none: ",
+	);
+	prompt.close();
+	const value = answer.trim().toLowerCase();
+	if (!value) return candidates;
+	if (value === "none") return [];
+	const indexes = new Set(
+		value
+			.split(",")
+			.map((part) => Number(part.trim()) - 1)
+			.filter((index) => Number.isInteger(index)),
+	);
+	if ([...indexes].some((index) => index < 0 || index >= candidates.length)) {
+		throw new Error(
+			`Form selection must contain numbers from 1 to ${candidates.length}.`,
+		);
+	}
+	return candidates.filter((_, index) => indexes.has(index));
+}
+
+// ── sync-records ─────────────────────────────────────────────────────
+
+type SeedRow = {
+	object: string;
+	universalIdentifier: string;
+	values: Record<string, unknown>;
+	/**
+	 * RELATION values, keyed by field name → the TARGET row's
+	 * `universalIdentifier` (or a list of them). Links live in the platform's
+	 * relation table, not in `values` — a relation key inside `values` is
+	 * silently stripped server-side, so this is the only channel that works.
+	 * Synced in a second pass after every record exists, so seed files can
+	 * reference rows in any file, in any order.
+	 */
+	relations?: Record<string, string | string[]>;
+};
+
+type SeedResult =
+	| { ok: true; object: string; universalIdentifier: string; created: boolean }
+	| { ok: false; object: string; universalIdentifier: string; error: string };
+
+/**
+ * Seed rows for custom objects from JSON on disk.
+ *
+ * Layout: `<rootDir>/<anything>.json`, each file an array of
+ * `{ object, universalIdentifier, values }`. Row identity is required — it's
+ * what makes running this on every deploy converge instead of duplicating.
+ */
+function discoverSeedFiles(rootDir: string): {
+	rows: SeedRow[];
+	warnings: string[];
+} {
+	const rows: SeedRow[] = [];
+	const warnings: string[] = [];
+
+	const walk = (dir: string): void => {
+		for (const entry of readdirSync(dir)) {
+			const abs = join(dir, entry);
+			if (statSync(abs).isDirectory()) {
+				walk(abs);
+				continue;
+			}
+			if (!entry.endsWith(".json")) continue;
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(readFileSync(abs, "utf8"));
+			} catch (err) {
+				warnings.push(
+					`Invalid JSON in ${abs}: ${err instanceof Error ? err.message : String(err)}`,
+				);
+				continue;
+			}
+			if (!Array.isArray(parsed)) {
+				warnings.push(`Skipping ${abs} — expected an array of rows.`);
+				continue;
+			}
+			for (const [i, raw] of parsed.entries()) {
+				const row = raw as Partial<SeedRow>;
+				if (!row?.object || !row.universalIdentifier || !row.values) {
+					warnings.push(
+						`Skipping ${abs}[${i}] — needs object, universalIdentifier, and values.`,
+					);
+					continue;
+				}
+				if (
+					row.relations !== undefined &&
+					(typeof row.relations !== "object" ||
+						row.relations === null ||
+						Array.isArray(row.relations))
+				) {
+					warnings.push(
+						`Skipping ${abs}[${i}] — relations must be an object of { fieldName: targetUid | targetUid[] }.`,
+					);
+					continue;
+				}
+				rows.push({
+					object: row.object,
+					universalIdentifier: row.universalIdentifier,
+					values: row.values,
+					...(row.relations ? { relations: row.relations } : {}),
+				});
+			}
+		}
+	};
+
+	walk(rootDir);
+	return { rows, warnings };
+}
+
+async function cmdSyncRecords(opts: {
+	env: Record<string, string>;
+	cwd: string;
+	rootDir: string;
+	dryRun: boolean;
+}) {
+	const rootDir = isAbsolute(opts.rootDir)
+		? opts.rootDir
+		: resolve(opts.cwd, opts.rootDir);
+	if (!existsSync(rootDir) || !statSync(rootDir).isDirectory()) {
+		throw new Error(
+			`--records-dir resolves to "${rootDir}", which doesn't exist or isn't a directory.`,
+		);
+	}
+
+	const { rows, warnings } = discoverSeedFiles(rootDir);
+	logStep(
+		`Discovered ${fg.bold(String(rows.length))} row(s) under ${rootDir}.`,
+	);
+	for (const warning of warnings) {
+		console.log(`  ${fg.amber("⚠")} ${fg.dim(warning)}`);
+	}
+	if (rows.length === 0) {
+		logStep("Nothing to seed.");
+		return;
+	}
+
+	if (opts.dryRun) {
+		logStep("--dry-run was set, skipping upload.");
+		for (const row of rows) {
+			const relNote = row.relations
+				? ` ${fg.dim(`(+${Object.keys(row.relations).length} relation field(s))`)}`
+				: "";
+			console.log(
+				`  ${fg.dim("→")} ${row.object} ${fg.dim(row.universalIdentifier)}${relNote}`,
+			);
+		}
+		return;
+	}
+
+	const target = resolveApiTarget(opts.env);
+	const BATCH = 64; // well under the server's 256 cap; smaller = faster feedback
+	let created = 0;
+	let updated = 0;
+	const failures: SeedResult[] = [];
+
+	// 893 rows is ~14 sequential round-trips; without this the CLI sits silent
+	// between "Discovered" and the final tally the whole time.
+	const progress = makeProgress(rows.length);
+	progress.tick(0);
+
+	for (let i = 0; i < rows.length; i += BATCH) {
+		// Pass 1 sends values only. Relations go in a second pass below, after
+		// EVERY record exists — so a link can point at a row from any file,
+		// in any order, without a "target not found yet" failure.
+		const batch = rows.slice(i, i + BATCH).map((row) => ({
+			object: row.object,
+			universalIdentifier: row.universalIdentifier,
+			values: row.values,
+		}));
+		const res = await callDataModelApi({
+			target,
+			path: "records",
+			method: "POST",
+			body: { items: batch },
+		});
+		for (const result of (res["results"] ?? []) as SeedResult[]) {
+			if (result.ok) {
+				if (result.created) created += 1;
+				else updated += 1;
+			} else {
+				failures.push(result);
+			}
+		}
+		const note = `${created} created, ${updated} updated${
+			failures.length > 0 ? `, ${failures.length} failed` : ""
+		}`;
+		progress.tick(Math.min(i + BATCH, rows.length), note);
+	}
+
+	progress.clear();
+	console.log("");
+	logStep(
+		`${fg.green(`✓ ${created} created`)}  ${fg.green(`${updated} updated`)}${
+			failures.length > 0 ? `  ${fg.red(`✕ ${failures.length} failed`)}` : ""
+		}`,
+	);
+	for (const failure of failures) {
+		if (failure.ok) continue;
+		console.log(
+			`  ${fg.red("✕")} ${failure.object} ${fg.dim(failure.universalIdentifier)} — ${fg.dim(failure.error)}`,
+		);
+	}
+
+	// Pass 2: converge declared relations, now that every record exists.
+	// Rows whose record failed in pass 1 are skipped — no point linking a row
+	// that isn't there.
+	const failedIdentity = new Set(
+		failures.map((f) => `${f.object}:${f.universalIdentifier}`),
+	);
+	const relationRows = rows.filter(
+		(row) =>
+			row.relations &&
+			Object.keys(row.relations).length > 0 &&
+			!failedIdentity.has(`${row.object}:${row.universalIdentifier}`),
+	);
+	if (relationRows.length > 0) {
+		logStep(
+			`Syncing relations for ${fg.bold(String(relationRows.length))} row(s)…`,
+		);
+		let linksApplied = 0;
+		const relationFailures: SeedResult[] = [];
+		for (let i = 0; i < relationRows.length; i += BATCH) {
+			const batch = relationRows.slice(i, i + BATCH).map((row) => ({
+				object: row.object,
+				universalIdentifier: row.universalIdentifier,
+				relations: row.relations,
+			}));
+			const res = await callDataModelApi({
+				target,
+				path: "records",
+				method: "POST",
+				body: { items: batch },
+			});
+			for (const result of (res["results"] ?? []) as (SeedResult & {
+				relationsApplied?: number;
+			})[]) {
+				if (result.ok) linksApplied += result.relationsApplied ?? 0;
+				else relationFailures.push(result);
+			}
+		}
+		logStep(
+			`${fg.green(`✓ ${linksApplied} link change(s) applied`)}${
+				relationFailures.length > 0
+					? `  ${fg.red(`✕ ${relationFailures.length} failed`)}`
+					: ""
+			}`,
+		);
+		for (const failure of relationFailures) {
+			if (failure.ok) continue;
+			console.log(
+				`  ${fg.red("✕")} ${failure.object} ${fg.dim(failure.universalIdentifier)} — ${fg.dim(failure.error)}`,
+			);
+		}
+		if (relationFailures.length > 0) process.exitCode = 1;
+	}
+
+	if (failures.length > 0) process.exitCode = 1;
+}
+
+// ── wipe-collections ──────────────────────────────────────────────────
+
+type WipeCollectionsPreview = {
+	planToken: string;
+	confirmationPhrase: string;
+	collections: Array<{
+		universalIdentifier: string;
+		name: string;
+		label: string;
+		records: number;
+		activeRecords: number;
+		softDeletedRecords: number;
+	}>;
+	recordCount: number;
+	relationCount: number;
+	backupFolder: string;
+};
+
+type WipeCollectionsResult = {
+	ok: true;
+	deleted: { records: number; relations: number };
+	backup: {
+		mediaId: string;
+		folderId: string;
+		name: string;
+		sha256: string;
+		sizeBytes: number;
+		folder: string;
+	};
+};
+
+/**
+ * Wipe record contents, never collection definitions. There is intentionally
+ * no `--all` and no `--yes`: a human must name the targets, review live counts,
+ * answer once, and then type a state-bound phrase exactly.
+ */
+async function cmdWipeCollections(opts: {
+	env: Record<string, string>;
+	collections: string[];
+	dryRun: boolean;
+}) {
+	const collections = [
+		...new Set(
+			opts.collections
+				.map((value) => value.trim())
+				.filter((value) => value.length > 0),
+		),
+	];
+	if (collections.length === 0) {
+		throw new Error(
+			"wipe-collections requires --collections name-a,name-b. There is no implicit all-collections mode.",
+		);
+	}
+
+	const target = resolveApiTarget(opts.env);
+	const path = `records/wipe?collections=${encodeURIComponent(collections.join(","))}`;
+	const preview = (await callDataModelApi({
+		target,
+		path,
+		method: "GET",
+	})) as WipeCollectionsPreview;
+
+	console.log("");
+	logStep(fg.red(fg.bold("DESTRUCTIVE RECORD WIPE PREVIEW")));
+	for (const collection of preview.collections) {
+		console.log(
+			`  ${fg.red("✕")} ${fg.bold(collection.name)} — ${collection.records} record(s) ` +
+				fg.dim(
+					`(${collection.activeRecords} active, ${collection.softDeletedRecords} soft-deleted)`,
+				),
+		);
+	}
+	console.log(
+		`  ${fg.amber("↳")} ${preview.relationCount} relationship link(s) also removed`,
+	);
+	console.log(
+		`  ${fg.green("↳")} Backup required at Media / ${preview.backupFolder}`,
+	);
+	console.log(
+		`  ${fg.dim("↳")} Plan ${preview.planToken.slice(0, 12)}… — any intervening data change invalidates it`,
+	);
+	console.log("");
+
+	if (opts.dryRun) {
+		logStep("--dry-run was set. Nothing was backed up or wiped.");
+		return;
+	}
+	if (preview.recordCount === 0 && preview.relationCount === 0) {
+		logStep("Nothing to wipe.");
+		return;
+	}
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
+		throw new Error(
+			"wipe-collections only runs in an interactive terminal. It deliberately has no --yes bypass.",
+		);
+	}
+
+	const prompt = createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+	try {
+		const first = await prompt.question(
+			"Continue to the final typed confirmation? Type yes to continue: ",
+		);
+		if (first.trim().toLowerCase() !== "yes") {
+			logStep("Cancelled. No backup was created and nothing was wiped.");
+			return;
+		}
+		console.log("");
+		console.log(
+			fg.amber(
+				"The server will save and verify the backup before deleting any record.",
+			),
+		);
+		const confirmation = await prompt.question(
+			`Type exactly "${preview.confirmationPhrase}" to wipe: `,
+		);
+		if (confirmation !== preview.confirmationPhrase) {
+			throw new Error(
+				`Confirmation did not match. Expected exactly: ${preview.confirmationPhrase}`,
+			);
+		}
+
+		const result = (await callDataModelApi({
+			target,
+			path: "records/wipe",
+			method: "POST",
+			body: {
+				collections,
+				planToken: preview.planToken,
+				confirmation,
+			},
+		})) as WipeCollectionsResult;
+
+		console.log("");
+		logStep(
+			`${fg.green(`✓ Verified backup: ${result.backup.name}`)} ${fg.dim(
+				`(${result.backup.sizeBytes} bytes, sha256 ${result.backup.sha256.slice(0, 12)}…)`,
+			)}`,
+		);
+		logStep(
+			`${fg.green(`✓ Wiped ${result.deleted.records} record(s)`)} and ${result.deleted.relations} relationship link(s).`,
+		);
+		logStep(`Backup location: Media / ${result.backup.folder}`);
+	} finally {
+		prompt.close();
+	}
+}
+
+// ── wipe-database ────────────────────────────────────────────────────
+
+type ResetPreview = {
+	planToken: string;
+	confirmationPhrase: string;
+	objectCount: number;
+	fieldCount: number;
+	viewCount: number;
+	recordCount: number;
+	relationCount: number;
+	generatedFormCount: number;
+	hasDraftSchema: boolean;
+	hasPublishedSchema: boolean;
+	backupFolder: string;
+};
+
+type ResetResult = {
+	ok: boolean;
+	objectsSoftDeleted: number;
+	fieldsSoftDeleted: number;
+	viewsSoftDeleted: number;
+	relationsDeleted: number;
+	recordsDeleted: number;
+	formsSoftDeleted: number;
+	backup: {
+		mediaId: string;
+		folderId: string;
+		name: string;
+		sha256: string;
+		sizeBytes: number;
+		folder: string;
+	};
+};
+
+/**
+ * Developer shortcut that wipes records AND removes the named collections
+ * from the schema.  Combines the data-wipe flow (with backup) with a
+ * pruned schema draft push; the schema change still requires dashboard
+ * promotion.
+ *
+ * When --all is used, calls the data-model/reset endpoint which atomically
+ * soft-deletes all metadata, clears records, and removes schema slots.
+ *
+ * Accepts --yes to skip the interactive prompt (single confirmation).
+ */
+async function cmdWipeDatabase(opts: {
+	configPath: string;
+	env: Record<string, string>;
+	collections: string[];
+	dryRun: boolean;
+	yes: boolean;
+	all: boolean;
+}) {
+	const explicitNames = [
+		...new Set(opts.collections.map((v) => v.trim()).filter(Boolean)),
+	];
+	if (!opts.all && explicitNames.length === 0) {
+		throw new Error(
+			"wipe-database requires --collections name-a,name-b or --all.",
+		);
+	}
+
+	const target = resolveApiTarget(opts.env);
+
+	// ── BRANCH: Full reset via data-model/reset ──
+	if (opts.all) {
+		const preview = (await callDataModelApi({
+			target,
+			path: "reset",
+			method: "GET",
+		})) as ResetPreview;
+
+		console.log("");
+		logStep(fg.red(fg.bold("DATA MODEL RESET PREVIEW")));
+		console.log(
+			`  ${fg.red("✕")} ${preview.objectCount} object(s) will be soft-deleted`,
+		);
+		console.log(
+			`  ${fg.dim("↳")} ${preview.fieldCount} field(s), ${preview.viewCount} view(s)`,
+		);
+		console.log(
+			`  ${fg.red("✕")} ${preview.recordCount} record(s) and ${preview.relationCount} relation(s) will be hard-deleted`,
+		);
+		if (preview.generatedFormCount > 0) {
+			console.log(
+				`  ${fg.amber("⚠")} ${preview.generatedFormCount} generated form(s) will be deactivated`,
+			);
+		}
+		if (preview.hasDraftSchema) {
+			console.log(`  ${fg.amber("↳")} Draft schema slot will be cleared`);
+		}
+		if (preview.hasPublishedSchema) {
+			console.log(`  ${fg.amber("↳")} Published schema slot will be cleared`);
+		}
+		console.log(`  ${fg.green("↳")} Backup at Media / ${preview.backupFolder}`);
+		console.log(`  ${fg.dim("↳")} Plan ${preview.planToken.slice(0, 12)}…`);
+		console.log("");
+
+		if (opts.dryRun) {
+			logStep("--dry-run was set. Nothing was backed up or reset.");
+			return;
+		}
+
+		// ── Confirmation ──
+		if (!opts.yes) {
+			if (!process.stdin.isTTY || !process.stdout.isTTY) {
+				throw new Error(
+					"wipe-database --all requires an interactive terminal or --yes.",
+				);
+			}
+			const prompt = createInterface({
+				input: process.stdin,
+				output: process.stdout,
+			});
+			try {
+				const first = await prompt.question(
+					"Continue to the final typed confirmation? Type yes to continue: ",
+				);
+				if (first.trim().toLowerCase() !== "yes") {
+					logStep("Cancelled. No backup was created and nothing was reset.");
+					return;
+				}
+				console.log("");
+				console.log(
+					fg.amber(
+						"The server will save and verify the backup before resetting any data.",
+					),
+				);
+				const confirmation = await prompt.question(
+					`Type exactly "${preview.confirmationPhrase}" to reset: `,
+				);
+				if (confirmation !== preview.confirmationPhrase) {
+					throw new Error(
+						`Confirmation did not match. Expected exactly: ${preview.confirmationPhrase}`,
+					);
+				}
+			} finally {
+				prompt.close();
+			}
+		}
+
+		// ── Execute reset ──
+		logStep("Backing up and resetting data model…");
+		try {
+			const result = (await callDataModelApi({
+				target,
+				path: "reset",
+				method: "POST",
+				body: {
+					planToken: preview.planToken,
+					confirmation: preview.confirmationPhrase,
+				},
+			})) as ResetResult;
+
+			console.log("");
+			logStep(
+				`${fg.green("✓")} Backup: ${result.backup.name} (${result.backup.sizeBytes} bytes, sha256 ${result.backup.sha256.slice(0, 12)}…)`,
+			);
+			logStep(
+				`${fg.green("✓")} Reset: ${result.objectsSoftDeleted} object(s), ${result.fieldsSoftDeleted} field(s), ${result.viewsSoftDeleted} view(s)`,
+			);
+			logStep(
+				`${fg.green("✓")} Wiped: ${result.recordsDeleted} record(s), ${result.relationsDeleted} relation(s)`,
+			);
+			if (result.formsSoftDeleted > 0) {
+				logStep(
+					`${fg.green("✓")} Deactivated ${result.formsSoftDeleted} generated form(s)`,
+				);
+			}
+		} catch (err) {
+			throw new Error(
+				`Data model reset failed: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
+		return;
+	}
+
+	// ── BRANCH: Targeted wipe via records/wipe + pruned schema draft ──
+
+	// ── 1. Load local config and determine which collections to remove ──
+	const loaded = await loadDataModelConfig(opts.configPath);
+	const artifact = loaded.model.toJSONSchema() as {
+		$schema: string;
+		version: number;
+		metadata: Record<string, string | number | boolean>;
+		objects: Array<Record<string, unknown>>;
+	};
+
+	const names = explicitNames;
+
+	const targetNames = new Set(names);
+	const keep: Array<Record<string, unknown>> = [];
+	const removed: Array<Record<string, unknown>> = [];
+	for (const obj of artifact.objects) {
+		const singular = String(obj["nameSingular"] ?? "");
+		const plural = String(obj["namePlural"] ?? "");
+		if (targetNames.has(singular) || targetNames.has(plural)) {
+			removed.push(obj);
+		} else {
+			keep.push(obj);
+		}
+	}
+
+	if (removed.length === 0 && artifact.objects.length > 0) {
+		throw new Error(
+			`wipe-database: none of the named collections match any object in the config. ` +
+				`Config has: ${artifact.objects.map((o) => String(o["nameSingular"] ?? "?")).join(", ")}`,
+		);
+	}
+
+	const prunedArtifact = { ...artifact, objects: keep };
+	// Remove generated forms that reference wiped collections
+	const wipedUis = new Set(
+		removed.map((o) => String(o["universalIdentifier"] ?? "")),
+	);
+	const loadedForms = loaded.generatedForms;
+	const keptForms = loadedForms.filter((f) => {
+		const refs =
+			f.settings.generatedFrom.objectIdentifiers ??
+			(f.settings.generatedFrom.objectIdentifier
+				? [f.settings.generatedFrom.objectIdentifier]
+				: []);
+		return !refs.some((r) => wipedUis.has(r));
+	});
+	const prunedForms =
+		keptForms.length < loadedForms.length ? keptForms : loadedForms;
+	const pushArtifact: Record<string, unknown> = {
+		...prunedArtifact,
+		...(prunedForms.length > 0 ? { generatedForms: prunedForms } : {}),
+	};
+
+	logStep(
+		`Loaded config with ${artifact.objects.length} object(s), ` +
+			`removing ${removed.length} (${removed.map((o) => String(o["nameSingular"] ?? "?")).join(", ")}), ` +
+			`keeping ${keep.length}.`,
+	);
+
+	// ── 2. Fetch the wipe preview to show live record counts ──
+	const wipePath = `records/wipe?collections=${encodeURIComponent(names.join(","))}`;
+	let wipePreview: WipeCollectionsPreview | null = null;
+	let wipeError: string | null = null;
+	try {
+		wipePreview = (await callDataModelApi({
+			target,
+			path: wipePath,
+			method: "GET",
+		})) as WipeCollectionsPreview;
+	} catch (err) {
+		wipeError = err instanceof Error ? err.message : String(err);
+	}
+
+	console.log("");
+	logStep(fg.red(fg.bold("WIPE-DATABASE PREVIEW")));
+
+	// -- data preview --
+	if (wipePreview && wipePreview.collections.length > 0) {
+		for (const c of wipePreview.collections) {
+			console.log(
+				`  ${fg.red("✕")} ${fg.bold(c.name)} — ${c.records} record(s) ` +
+					fg.dim(
+						`(${c.activeRecords} active, ${c.softDeletedRecords} soft-deleted)`,
+					),
+			);
+		}
+		console.log(
+			`  ${fg.amber("↳")} ${wipePreview.relationCount} relationship link(s) also removed`,
+		);
+		console.log(
+			`  ${fg.green("↳")} Backup required at Media / ${wipePreview.backupFolder}`,
+		);
+	} else if (wipeError) {
+		console.log(`  ${fg.dim("Data wipe preview unavailable:")} ${wipeError}`);
+	} else {
+		console.log(
+			`  ${fg.dim("No live records found for the named collections.")}`,
+		);
+	}
+
+	// -- schema preview (skip if no objects remain) --
+	const hasSchemaChanges =
+		keep.length > 0 && keep.length < artifact.objects.length;
+	if (hasSchemaChanges) {
+		const planRes = await callDataModelApi({
+			target,
+			path: "plan",
+			method: "POST",
+			body: { schema: pushArtifact, prune: true },
+		});
+		const plan = planRes["plan"] as MigrationPlan;
+		console.log("");
+		logStep("Schema plan (what promoting this draft would do):");
+		printPlan(plan);
+	} else {
+		console.log("");
+		logStep(
+			keep.length === 0
+				? "No collections remain in config — schema draft will be left unchanged."
+				: "No schema changes needed.",
+		);
+	}
+
+	if (opts.dryRun) {
+		console.log("");
+		logStep("--dry-run was set. Nothing was wiped or pushed.");
+		return;
+	}
+
+	// ── 3. Confirmation ──
+	if (!opts.yes) {
+		if (!process.stdin.isTTY || !process.stdout.isTTY) {
+			throw new Error(
+				"wipe-database requires an interactive terminal or --yes.",
+			);
+		}
+		const prompt = createInterface({
+			input: process.stdin,
+			output: process.stdout,
+		});
+		try {
+			const answer = await prompt.question(
+				`\nThis will delete records (with backup) and push a pruned schema draft. ${fg.red("This cannot be undone.")}\nType the collection name "` +
+					`${removed[0]?.["nameSingular"] ?? ""}" to confirm: `,
+			);
+			if (answer.trim() !== (removed[0]?.["nameSingular"] ?? "")) {
+				logStep("Cancelled.");
+				return;
+			}
+		} finally {
+			prompt.close();
+		}
+	}
+
+	// ── 4. Execute data wipe ──
+	if (wipePreview && wipePreview.recordCount + wipePreview.relationCount > 0) {
+		const backupPhrase = wipePreview.confirmationPhrase;
+		logStep("Backing up and wiping records…");
+		try {
+			const wipeResult = (await callDataModelApi({
+				target,
+				path: "records/wipe",
+				method: "POST",
+				body: {
+					collections: names,
+					planToken: wipePreview.planToken,
+					confirmation: backupPhrase,
+				},
+			})) as WipeCollectionsResult;
+			console.log(
+				`  ${fg.green("✓")} Backup: ${wipeResult.backup.name} (${wipeResult.backup.sizeBytes} bytes)`,
+			);
+			console.log(
+				`  ${fg.green("✓")} Wiped ${wipeResult.deleted.records} record(s) and ${wipeResult.deleted.relations} relation(s).`,
+			);
+		} catch (err) {
+			throw new Error(
+				`Data wipe failed: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
+	} else {
+		logStep("No records to wipe.");
+	}
+
+	// ── 5. Push schema draft (skip if no objects remain) ──
+	if (hasSchemaChanges) {
+		const checksum = await computeDataModelChecksum(pushArtifact);
+		logStep("Pushing pruned schema draft…");
+		try {
+			const pushRes = await callDataModelApi({
+				target,
+				path: "draft-schema",
+				method: "POST",
+				body: {
+					schema: pushArtifact,
+					checksum,
+					note: `wipe-database: removed ${removed.map((o) => String(o["nameSingular"] ?? "?")).join(", ")}`,
+				},
+			});
+			if (pushRes["noop"]) {
+				logStep("Schema already matches — no draft update needed.");
+			} else {
+				logStep(
+					`${fg.green("✓")} Uploaded draft v${String(pushRes["version"])}.`,
+				);
+			}
+		} catch (err) {
+			throw new Error(
+				`Schema push failed: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
+	} else if (keep.length === 0) {
+		logStep(
+			fg.dim(
+				"Schema draft unchanged — all collections were removed from the config. Remove or edit biab.data-model.config.ts to rebuild.",
+			),
+		);
+	}
+
+	console.log("");
+	logStep(
+		`${fg.green("✓")} Data wiped for ${removed.map((o) => String(o["nameSingular"] ?? "?")).join(", ")}.`,
+	);
+}
+
+// ── sync-content ─────────────────────────────────────────────────────
+
+/**
+ * Convert a basename like `value-props` or `value_props` to camelCase
+ * (`valueProps`). Used as the default mapping when the consumer hasn't
+ * supplied a `sectionAliases` entry. Pure identity for already-camelCased
+ * names like `hero`. Matches the convention enforced by the package-API
+ * sectionKey regex.
+ */
+function toCamelCase(input: string): string {
+	return input.replace(/[-_]+([a-zA-Z0-9])/g, (_m, c: string) =>
+		c.toUpperCase(),
+	);
+}
+
+type DiscoveredItem = {
+	pageKey: string;
+	locale: string;
+	sectionKey: string;
+	filename: string;
+	payload: unknown;
+};
+
+type DiscoveryWarning = { kind: "skipped" | "unknown"; message: string };
+
+/**
+ * Resolve the list of `(pageKey, dir-on-disk)` entries to walk for a
+ * given locale. If `pages` is supplied we substitute `{locale}` into
+ * each entry's `dir`. Otherwise we fall back to auto-discovery:
+ * iterate `<rootDir>/<locale>/*` and use the leaf name as pageKey.
+ */
+function resolvePageDirs(input: {
+	rootDir: string;
+	locale: string;
+	pages: SiteMarketingContentSyncConfig["pages"];
+}): Array<{ pageKey: string; absDir: string }> {
+	const { rootDir, locale, pages } = input;
+	if (pages && pages.length > 0) {
+		return pages.map((p) => ({
+			pageKey: p.pageKey,
+			absDir: join(rootDir, p.dir.replaceAll("{locale}", locale)),
+		}));
+	}
+	const localeDir = join(rootDir, locale);
+	if (!existsSync(localeDir) || !statSync(localeDir).isDirectory()) {
+		return [];
+	}
+	const out: Array<{ pageKey: string; absDir: string }> = [];
+	for (const dirent of readdirSync(localeDir)) {
+		const abs = join(localeDir, dirent);
+		if (statSync(abs).isDirectory()) {
+			out.push({ pageKey: dirent, absDir: abs });
+		}
+	}
+	return out;
+}
+
+function discoverContentFiles(input: {
+	rootDir: string;
+	cfg: SiteMarketingContentSyncConfig;
+	knownSectionKeys: ReadonlySet<string>;
+}): { items: DiscoveredItem[]; warnings: DiscoveryWarning[] } {
+	const { rootDir, cfg, knownSectionKeys } = input;
+	const items: DiscoveredItem[] = [];
+	const warnings: DiscoveryWarning[] = [];
+
+	const locales = cfg.locales && cfg.locales.length > 0 ? cfg.locales : ["en"];
+	const sectionAliases = cfg.sectionAliases ?? {};
+	const skip = new Set(cfg.skipSections ?? []);
+
+	for (const locale of locales) {
+		const pageDirs = resolvePageDirs({ rootDir, locale, pages: cfg.pages });
+		if (pageDirs.length === 0) {
+			warnings.push({
+				kind: "skipped",
+				message: `No page directories resolved for locale "${locale}". Check contentSync.pages / rootDir.`,
+			});
+			continue;
+		}
+
+		for (const { pageKey, absDir } of pageDirs) {
+			if (!existsSync(absDir) || !statSync(absDir).isDirectory()) {
+				warnings.push({
+					kind: "skipped",
+					message: `Page dir not found: ${absDir} (pageKey="${pageKey}")`,
+				});
+				continue;
+			}
+
+			for (const fileDirent of readdirSync(absDir)) {
+				if (!fileDirent.endsWith(".json")) continue;
+				const basename = fileDirent.slice(0, -".json".length);
+				// Scoped alias wins over global alias wins over camelCase
+				// fallback. Lets `about/page` map to `aboutPage` while
+				// `services/page` maps to `servicesPage` from the same
+				// file basename.
+				const aliased =
+					sectionAliases[`${pageKey}/${basename}`] ?? sectionAliases[basename];
+				const sectionKey = aliased ?? toCamelCase(basename);
+
+				if (skip.has(sectionKey)) {
+					warnings.push({
+						kind: "skipped",
+						message: `Skipping ${pageKey}/${basename}.json (sectionKey "${sectionKey}" is in skipSections).`,
+					});
+					continue;
+				}
+				if (!knownSectionKeys.has(sectionKey)) {
+					warnings.push({
+						kind: "unknown",
+						message: `Skipping ${pageKey}/${basename}.json — no matching schema section "${sectionKey}". Add to contentSync.sectionAliases?`,
+					});
+					continue;
+				}
+
+				const filePath = join(absDir, fileDirent);
+				const raw = readFileSync(filePath, "utf8");
+				let payload: unknown;
+				try {
+					payload = JSON.parse(raw);
+				} catch (err) {
+					warnings.push({
+						kind: "unknown",
+						message: `Invalid JSON in ${filePath}: ${err instanceof Error ? err.message : String(err)}`,
+					});
+					continue;
+				}
+
+				items.push({
+					pageKey,
+					locale,
+					sectionKey,
+					filename: filePath,
+					payload,
+				});
+			}
+		}
+	}
+
+	return { items, warnings };
+}
+
+type BulkResultItem =
+	| {
+			ok: true;
+			pageKey: string;
+			locale: string;
+			sectionKey: string;
+			version: number;
+	  }
+	| {
+			ok: false;
+			pageKey: string;
+			locale: string;
+			sectionKey: string;
+			error: string;
+	  };
+
+async function postSectionBatch(input: {
+	baseUrl: string;
+	apiKey: string;
+	siteId: string;
+	items: ReadonlyArray<{
+		pageKey: string;
+		locale: string;
+		sectionKey: string;
+		payload: unknown;
+	}>;
+	validate: boolean;
+	note: string | null;
+}): Promise<
+	| { ok: true; results: BulkResultItem[] }
+	| { ok: false; status: number; message: string }
+> {
+	const target = `${input.baseUrl}/sites/${encodeURIComponent(input.siteId)}/marketing/sections`;
+	const res = await fetch(target, {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			authorization: `Bearer ${input.apiKey}`,
+		},
+		body: JSON.stringify({
+			items: input.items,
+			validate: input.validate,
+			note: input.note,
+		}),
+	});
+	const bodyText = await res.text();
+	if (!res.ok) {
+		let message = `HTTP ${res.status} ${res.statusText}`.trim();
+		try {
+			const parsed = JSON.parse(bodyText) as { message?: string };
+			if (parsed.message) message = parsed.message;
+		} catch {
+			const looksHtml = /^\s*<(?:!doctype|html|head|body)/i.test(bodyText);
+			if (looksHtml) {
+				message = `${message} (server returned an HTML page, not JSON — the bulk-upsert route may not exist on this host yet. Make sure BIAB is deployed with the marketing/sections endpoint, and that BIAB_PACKAGE_API_BASE_URL points at the right host.)`;
+			} else if (bodyText.trim()) {
+				message = `${message} — ${bodyText.slice(0, 240).trim()}`;
+			}
+		}
+		return { ok: false, status: res.status, message };
+	}
+	// Successful 2xx response. Defend against an HTML body here too —
+	// some edge proxies (Vercel preview deployments, CDNs) can wrap
+	// the JSON in an HTML shell if the route lookup actually missed.
+	try {
+		const parsed = JSON.parse(bodyText) as { results?: BulkResultItem[] };
+		return { ok: true, results: parsed.results ?? [] };
+	} catch {
+		return {
+			ok: false,
+			status: res.status,
+			message: `Server replied 200 OK but the body wasn't JSON — first 240 chars: ${bodyText.slice(0, 240).trim()}`,
+		};
+	}
+}
+
+async function cmdSyncContent(opts: {
+	configPath: string;
+	env: Record<string, string>;
+	dryRun: boolean;
+	lax: boolean;
+	note: string | null;
+}) {
+	const schema = await loadConfig(opts.configPath);
+	const artifact = schema.toJSONSchema();
+	const cfg = schema.contentSync;
+
+	if (!cfg) {
+		throw new Error(
+			`${opts.configPath} doesn't declare a \`contentSync\` config. Add one to your defineSiteMarketingSchema({...}) call, for example: contentSync: { rootDir: "src/content", sectionAliases: { ... } }`,
+		);
+	}
+
+	const configDir = dirname(opts.configPath);
+	const rootDir = isAbsolute(cfg.rootDir)
+		? cfg.rootDir
+		: resolve(configDir, cfg.rootDir);
+
+	if (!existsSync(rootDir) || !statSync(rootDir).isDirectory()) {
+		throw new Error(
+			`contentSync.rootDir resolves to "${rootDir}", which does not exist or is not a directory.`,
+		);
+	}
+
+	const knownSectionKeys = new Set(Object.keys(artifact.sections));
+
+	const { items, warnings } = discoverContentFiles({
+		rootDir,
+		cfg,
+		knownSectionKeys,
+	});
+
+	logStep(
+		`Discovered ${fg.bold(String(items.length))} section file(s) under ${rootDir}.`,
+	);
+	for (const w of warnings) {
+		console.log(`  ${fg.amber("⚠")} ${fg.dim(w.message)}`);
+	}
+
+	// Reject content syncs that target a BIAB-reserved pageKey. We dedupe
+	// so we report each offending key once rather than per-file.
+	const reservedKeys = Array.from(
+		new Set(
+			items
+				.filter((it) => isReservedPagePath(it.pageKey))
+				.map((it) => it.pageKey),
+		),
+	);
+	if (reservedKeys.length > 0) {
+		for (const key of reservedKeys) {
+			logError(reservedPagePathErrorMessage(key));
+		}
+		throw new Error(
+			`Refusing to sync content: ${reservedKeys.length} reserved pageKey(s) found in discovered files.`,
+		);
+	}
+
+	if (items.length === 0) {
+		logStep("Nothing to sync.");
+		return;
+	}
+
+	if (opts.dryRun) {
+		logStep("--dry-run was set, skipping upload.");
+		for (const it of items) {
+			console.log(
+				`  ${fg.dim("→")} ${it.locale}/${it.pageKey}/${it.sectionKey} ${fg.dim(`(from ${it.filename})`)}`,
+			);
+		}
+		return;
+	}
+
+	const apiKey = opts.env["BIAB_API_KEY"];
+	const siteId = opts.env["BIAB_SITE_ID"];
+	const rawBase =
+		opts.env["BIAB_PACKAGE_API_BASE_URL"] ??
+		opts.env["NEXT_PUBLIC_BIAB_PACKAGE_API_BASE_URL"];
+	if (!apiKey) throw new Error("Missing BIAB_API_KEY in env or .env.local.");
+	if (!siteId) throw new Error("Missing BIAB_SITE_ID in env or .env.local.");
+	if (!rawBase) {
+		throw new Error(
+			"Missing BIAB_PACKAGE_API_BASE_URL in env or .env.local (e.g. https://your-host.tld/api/package/v1).",
+		);
+	}
+
+	const baseUrl = normalizeBaseUrl(rawBase);
+	const BATCH_SIZE = 64; // well under the server's 256 cap; smaller = faster failure feedback
+	const batches: DiscoveredItem[][] = [];
+	for (let i = 0; i < items.length; i += BATCH_SIZE) {
+		batches.push(items.slice(i, i + BATCH_SIZE));
+	}
+
+	let okCount = 0;
+	let failCount = 0;
+	const failures: BulkResultItem[] = [];
+
+	logStep(
+		`POST ${fg.dim(`${baseUrl}/sites/${siteId}/marketing/sections`)} in ${batches.length} batch(es)…`,
+	);
+
+	for (let i = 0; i < batches.length; i++) {
+		const batch = batches[i]!;
+		const res = await postSectionBatch({
+			baseUrl,
+			apiKey,
+			siteId,
+			items: batch.map((b) => ({
+				pageKey: b.pageKey,
+				locale: b.locale,
+				sectionKey: b.sectionKey,
+				payload: b.payload,
+			})),
+			validate: !opts.lax,
+			note: opts.note,
+		});
+		if (!res.ok) {
+			logError(
+				`Batch ${i + 1}/${batches.length} failed (${res.status}): ${res.message}`,
+			);
+			process.exitCode = 1;
+			return;
+		}
+		for (const r of res.results) {
+			if (r.ok) {
+				okCount += 1;
+			} else {
+				failCount += 1;
+				failures.push(r);
+			}
+		}
+		logStep(
+			`Batch ${i + 1}/${batches.length}: ${fg.green(`✓ ${res.results.filter((r) => r.ok).length}`)} ${
+				res.results.some((r) => !r.ok)
+					? fg.red(`✕ ${res.results.filter((r) => !r.ok).length}`)
+					: ""
+			}`.trimEnd(),
+		);
+	}
+
+	console.log("");
+	if (failCount === 0) {
+		logStep(
+			`${fg.green(`✓ Synced ${okCount} section(s).`)} ${fg.dim("Check the dashboard at Site Builder → Site Data → Pages.")}`,
+		);
+	} else {
+		logStep(
+			`${fg.green(`✓ ${okCount} succeeded`)}  ${fg.red(`✕ ${failCount} failed`)}`,
+		);
+		for (const f of failures) {
+			if (f.ok) continue;
+			console.log(
+				`  ${fg.red("✕")} ${f.locale}/${f.pageKey}/${f.sectionKey} — ${fg.dim(f.error)}`,
+			);
+		}
+		console.log("");
+		console.log(
+			fg.dim(
+				`  Tip: pass --lax to skip validation for this run (writes raw JSON without enforcing the published schema).`,
+			),
+		);
+		process.exitCode = 1;
+	}
+}
+
+function printHelp(): void {
+	console.log(`biab-dev — Business In A Box developer CLI
+
+Run via your package runner — biab-dev is a package bin, not a global:
+  npx biab-dev <command>          (or: pnpm exec biab-dev <command>)
+
+WEBSITE CONTENT (biab.config.ts)
+  npx biab-dev sync-schema      [--config path] [--dry-run]
+  npx biab-dev sync-content     [--config path] [--dry-run] [--lax] [--note "first import"]
+  npx biab-dev print-schema     [--config path]
+
+CUSTOM DATABASE (biab.data-model.config.ts)
+  npx biab-dev view-data-model  [--json] [--diff] [--out path] [--prune]
+  npx biab-dev print-data-model [--config path]
+  npx biab-dev export-data-model [--out path] [--schema-only]
+  npx biab-dev export-graphql-schema [--out path] [--include-standard]
+  npx biab-dev sync-data-model  [--config path] [--dry-run] [--prune] [--forms [slugs]] [--no-forms] [--note "..."]
+  npx biab-dev sync-records     [--records-dir path] [--dry-run]
+  npx biab-dev wipe-collections --collections name-a,name-b [--dry-run]
+  npx biab-dev wipe-database     --collections name-a,name-b [--config path] [--dry-run] [--yes]
+  npx biab-dev wipe-database     --all [--config path] [--dry-run] [--yes]
+
+  view    what's LIVE in BIAB right now (the dashboard can change it too, so
+          this is not just "what I last pushed")
+  print   what your local config resolves to — no network
+  export  pull the WHOLE custom database — schema + records + relations — into
+          one portable snapshot (default: ./biab.data-model.snapshot.json).
+          Deterministic order, so committing it gives a git-diffable history an
+          AI agent can read without querying BIAB. Re-seeds a fresh org via
+          sync-data-model (schema) + sync-records (rows). --schema-only skips
+          the row scan. Needs metadata:read_schema + metadata:read_records.
+  export-graphql-schema
+          render a GraphQL SDL schema of your custom collections (default:
+          ./biab.data-model.graphql) — every object a type, relations as lists,
+          SELECTs as enums where valid. Feed it to GraphQL codegen or commit it
+          as a typed contract. Schema only; this does not run a GraphQL server.
+          --include-standard also emits standard CRM types. Needs
+          metadata:read_schema.
+  sync    push your config to the draft slot. Prints the migration plan first;
+          nothing changes until you promote in the dashboard.
+
+  seed    upsert rows from JSON (default dir: ./biab-records). Each file is an
+          array of { object, universalIdentifier, values, relations? }; identity
+          is what makes re-running converge instead of duplicating. relations
+          links rows by the TARGET row's universalIdentifier, e.g.
+          { "tech": "<uid>" } or { "tags": ["<uid>", "<uid>"] } — synced after
+          all records exist, so files can reference each other in any order.
+
+  wipe    hard-delete records (not schemas) from only the explicitly named
+          custom collections. The CLI previews live counts, requires two
+          interactive confirmations, writes + verifies a JSON backup under
+          Media / Database Backups / Collection Wipes, then deletes. There is
+          intentionally no --all or --yes bypass.
+
+  wipe-database
+          developer shortcut: wipes records AND removes the named collections
+          (or all collections with --all) from your schema draft. Combines
+          data deletion (with backup) with a pruned schema push; requires
+          dashboard promotion to finalise the schema change. Uses a single
+          confirmation with --yes to skip the interactive prompt.
+
+  --diff       show the migration plan for your local config without pushing
+  --out path   write a config file from the live model (adopt an existing
+               dashboard-built model as code)
+  --prune      reconcile fully: remove anything live but absent from the
+               config. Everything it removes is a destructive change.
+  --forms      include all generated form drafts (the non-interactive default).
+  --forms a,b  include only the generated forms with those slugs/source keys.
+  --no-forms   push only collections. Generated forms are created inactive on
+               promotion and must be activated separately in the dashboard.
+
+  npx biab-dev help
+
+Environment (read from process.env, .env, or .env.local in the cwd):
+  BIAB_API_KEY                 API key. Website flow needs marketing:write_schema
+                               / marketing:write_content. Data-model flow needs
+                               metadata:read_schema (view/plan) and
+                               metadata:write_schema (push) or
+                               metadata:write_records (seed/wipe).
+  BIAB_SITE_ID                 UUID of the site to publish to
+  BIAB_PACKAGE_API_BASE_URL    Host URL (any path; the CLI canonicalises
+                               to "<origin>/api/package/v1" automatically).
+                               Use the APEX host — e.g. https://biab.app, NOT
+                               https://www.biab.app. A www→apex redirect makes
+                               fetch drop the Authorization header (it's a
+                               cross-origin hop), and the server then reports
+                               "Missing bearer API key" as if your key were
+                               absent.
+
+Schema pushes cannot change what an org's database or website serves: they
+write a draft and a human promotes it in the dashboard. wipe-collections is
+the explicit record-data exception, guarded by preview, verified backup, and
+two interactive confirmations. wipe-database combines a data wipe with a
+pruned schema push for developer convenience.
+
+Config files (override either with --config path):
+  biab.config.ts             → defineSiteMarketingSchema  (website content)
+  biab.data-model.config.ts  → createFormSchemaOrchestrator / createSchema
+
+sync-content also reads the optional \`contentSync\` field on your
+defineSiteMarketingSchema({...}) call. Minimal form (default layout
+\`<rootDir>/<locale>/<page>/<section>.json\`):
+
+  contentSync: {
+    rootDir: "src/content",
+    sectionAliases: { marquee: "trustMarquee" },
+    locales: ["en"],
+    skipSections: ["gallery", "blogFeed"], // managed by other surfaces
+  }
+
+Explicit form (when pages aren't direct children of the locale dir, or
+when shared/cross-page sections live in a sibling dir):
+
+  contentSync: {
+    rootDir: "src/content",
+    locales: ["en"],
+    pages: [
+      { dir: "{locale}/shared",         pageKey: "shared" },
+      { dir: "{locale}/pages/home",     pageKey: "home" },
+      { dir: "{locale}/pages/about",    pageKey: "about" },
+    ],
+    sectionAliases: {
+      "home/marquee": "trustMarquee",   // scoped: only inside home/
+      "about/page":   "aboutPage",      // scoped
+      "service-areas": "serviceAreas",  // global
+    },
+  }
+`);
+}
+
+type ParsedArgs = {
+	command: Command;
+	configOverride?: string;
+	dryRun: boolean;
+	lax: boolean;
+	note: string | null;
+	json: boolean;
+	diff: boolean;
+	out: string | null;
+	prune: boolean;
+	recordsDir: string;
+	forms: string;
+	collections: string[];
+	yes: boolean;
+	all: boolean;
+	schemaOnly: boolean;
+	includeStandard: boolean;
+};
+
+function parseArgs(argv: string[]): ParsedArgs {
+	const args = argv.slice(2);
+	const out: ParsedArgs = {
+		command: "help",
+		dryRun: false,
+		lax: false,
+		note: null,
+		json: false,
+		diff: false,
+		out: null,
+		prune: false,
+		recordsDir: "biab-records",
+		forms: "prompt",
+		collections: [],
+		yes: false,
+		all: false,
+		schemaOnly: false,
+		includeStandard: false,
+	};
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (!arg) continue;
+		if (i === 0 && (COMMANDS as readonly string[]).includes(arg)) {
+			out.command = arg as Command;
+			continue;
+		}
+		if (arg === "--config" && i + 1 < args.length) {
+			const next = args[++i];
+			if (next) out.configOverride = next;
+			continue;
+		}
+		if (arg === "--dry-run") {
+			out.dryRun = true;
+			continue;
+		}
+		if (arg === "--lax") {
+			out.lax = true;
+			continue;
+		}
+		if (arg === "--json") {
+			out.json = true;
+			continue;
+		}
+		if (arg === "--diff") {
+			out.diff = true;
+			continue;
+		}
+		if (arg === "--prune") {
+			out.prune = true;
+			continue;
+		}
+		if (arg === "--schema-only") {
+			out.schemaOnly = true;
+			continue;
+		}
+		if (arg === "--include-standard") {
+			out.includeStandard = true;
+			continue;
+		}
+		if (arg === "--no-forms") {
+			out.forms = "none";
+			continue;
+		}
+		if (arg === "--forms") {
+			const next = args[i + 1];
+			if (next && !next.startsWith("--")) {
+				i++;
+				out.forms = `list:${next}`;
+			} else {
+				out.forms = "all";
+			}
+			continue;
+		}
+		if (arg === "--records-dir" && i + 1 < args.length) {
+			const next = args[++i];
+			if (next) out.recordsDir = next;
+			continue;
+		}
+		if (arg === "--collections" && i + 1 < args.length) {
+			const next = args[++i];
+			if (next) {
+				out.collections.push(...next.split(",").map((value) => value.trim()));
+			}
+			continue;
+		}
+		if (arg === "--out" && i + 1 < args.length) {
+			const next = args[++i];
+			if (next) out.out = next;
+			continue;
+		}
+		if (arg === "--note" && i + 1 < args.length) {
+			const next = args[++i];
+			if (next) out.note = next;
+			continue;
+		}
+		if (arg === "--yes") {
+			out.yes = true;
+			continue;
+		}
+		if (arg === "--all") {
+			out.all = true;
+			continue;
+		}
+		if (arg === "--help" || arg === "-h") {
+			out.command = "help";
+			break;
+		}
+	}
+	return out;
+}
+
+async function main(): Promise<void> {
+	const cwd = process.cwd();
+	const {
+		command,
+		configOverride,
+		dryRun,
+		lax,
+		note,
+		json,
+		diff,
+		out,
+		prune,
+		recordsDir,
+		forms,
+		collections,
+		yes,
+		all,
+		schemaOnly,
+		includeStandard,
+	} = parseArgs(process.argv);
+	if (command === "help") {
+		printHelp();
+		return;
+	}
+	const env = loadEnv(cwd);
+
+	// Data-model commands read their own config file (D9) — and `view` needs
+	// no local config at all unless --diff/--out is in play, so resolve lazily.
+	if (command === "view-data-model") {
+		await cmdViewDataModel({
+			env,
+			json,
+			diff,
+			out,
+			configOverride,
+			cwd,
+			prune,
+		});
+		return;
+	}
+	if (command === "print-data-model") {
+		await cmdPrintDataModel({
+			configPath: findDataModelConfigPath(cwd, configOverride),
+		});
+		return;
+	}
+	if (command === "export-data-model") {
+		await cmdExportDataModel({ env, out, schemaOnly, cwd });
+		return;
+	}
+	if (command === "export-graphql-schema") {
+		await cmdExportGraphqlSchema({ env, out, includeStandard, cwd });
+		return;
+	}
+	if (command === "sync-records") {
+		await cmdSyncRecords({ env, cwd, rootDir: recordsDir, dryRun });
+		return;
+	}
+	if (command === "wipe-collections") {
+		await cmdWipeCollections({ env, collections, dryRun });
+		return;
+	}
+	if (command === "wipe-database") {
+		await cmdWipeDatabase({
+			configPath: findDataModelConfigPath(cwd, configOverride),
+			env,
+			collections,
+			dryRun,
+			yes,
+			all,
+		});
+		return;
+	}
+	if (command === "sync-data-model") {
+		await cmdSyncDataModel({
+			configPath: findDataModelConfigPath(cwd, configOverride),
+			env,
+			dryRun,
+			prune,
+			note,
+			forms,
+		});
+		return;
+	}
+
+	const configPath = findConfigPath(cwd, configOverride);
+	if (command === "print-schema") {
+		await cmdPrintSchema({ configPath });
+		return;
+	}
+	if (command === "sync-schema") {
+		await cmdSyncSchema({ configPath, env, dryRun });
+		return;
+	}
+	if (command === "sync-content") {
+		await cmdSyncContent({ configPath, env, dryRun, lax, note });
+		return;
+	}
+	printHelp();
+}
+
+main().catch((err) => {
+	logError(err instanceof Error ? err.message : String(err));
+	process.exitCode = 1;
+});
+
+// Silence "createRequire is unused" since some bundlers strip the static
+// import above; keep it as a runtime hook in case downstream needs to
+// resolve relative paths the same way the loader would.
+void createRequire(import.meta.url);
+void dirname;