@layers/amba 4.0.4 → 4.1.1

package/dist/index.js

@@ -3,15 +3,16 @@ import { Command } from "commander";
 import pc from "picocolors";
 import { access, chmod, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import path, { basename, dirname, join, relative, resolve } from "node:path";
 import { createServer } from "node:http";
 import open from "open";
 import { createHash, randomBytes } from "node:crypto";
 import { createInterface } from "node:readline";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { createWriteStream, watch } from "node:fs";
+import fs, { createWriteStream, watch } from "node:fs";
 import { spawn } from "node:child_process";
 import { build } from "esbuild";
+import process$1 from "node:process";
 new Map([
 	{
 		type: "user.created",
@@ -460,6 +461,37 @@ new Map([
 			reason: "card_declined"
 		},
 		status: "live"
+	},
+	{
+		type: "billing.ceiling_warning",
+		plane: "control",
+		description: "The project's current-period usage cost crossed 80% of its spend ceiling. Fires at most once per billing period.",
+		payloadExample: {
+			project_id: "prj_1",
+			threshold_pct: 80,
+			ceiling_usd: 100,
+			current_overage_usd: 82.4,
+			pct_consumed: .824,
+			billing_period: "2026-06-01",
+			resets_at: "2026-07-01T00:00:00.000Z"
+		},
+		status: "live"
+	},
+	{
+		type: "billing.ceiling_reached",
+		plane: "control",
+		description: "The project's current-period usage cost reached its spend ceiling — metered writes now return 402 (read-only mode) until the period resets or the ceiling changes. Fires at most once per billing period.",
+		payloadExample: {
+			project_id: "prj_1",
+			threshold_pct: 100,
+			ceiling_usd: 100,
+			current_overage_usd: 101.1,
+			pct_consumed: 1.011,
+			billing_period: "2026-06-01",
+			resets_at: "2026-07-01T00:00:00.000Z",
+			read_only: true
+		},
+		status: "live"
 	}
 ].map((e) => [e.type, e]));
 /**
@@ -996,6 +1028,7 @@ async function getFunctionLogs(projectId, functionName, options = {}) {
 	if (options.until) params.set("until", options.until);
 	if (options.limit !== void 0) params.set("limit", String(options.limit));
 	if (options.requestId) params.set("request_id", options.requestId);
+	if (options.sinceRequestId) params.set("since_request_id", options.sinceRequestId);
 	const qs = params.toString();
 	return request("GET", `/projects/${projectId}/functions/${functionName}/logs${qs ? `?${qs}` : ""}`);
 }
@@ -2820,7 +2853,7 @@ All SDKs expose the same surface: \`Amba.configure({ projectId, apiKey })\`, the
 - **analytics** — funnels + retention. Query via \`amba_analytics_get\`.
 
 ### Infrastructure
-- **collections** — your own typed key-value tables. Define with \`amba_collections_create\`; read/write from SDK \`Amba.client.*\`.
+- **collections** — your own relational Postgres tables (typed columns, foreign keys, transactions, unique indexes, vector search). Define with \`amba_collections_create\`; read/write from SDK \`Amba.client.*\`.
 - **functions** — serverless TypeScript handlers. Deploy with \`amba_functions_deploy\`; schedule with \`amba_functions_schedule\`.
 - **sites** — static site hosting at \`*.app.amba.host\`. Deploy with \`amba_sites_deploy\`.
 - **media** — file storage + CDN. Upload via \`amba_media_upload\`.
@@ -3457,7 +3490,7 @@ When the user asks you to wire Amba into this codebase, run this journey end-to-
 - **gamification** — XP, achievements, streaks, leaderboards, challenges (\`amba://setup/gamification\`).
 - **economy** — currencies, catalog, stores, inventory (\`amba://setup/economy\`).
 - **social** — friends, groups, feeds, messaging, moderation, reviews (\`amba://setup/social\`).
-- **infrastructure** — collections (typed tables), functions, AI prompts, secrets, configs, integrations, media, sites (\`amba://setup/infrastructure\`).
+- **infrastructure** — collections (relational Postgres tables), functions, AI prompts, secrets, configs, integrations, media, sites (\`amba://setup/infrastructure\`).
 
 ## SDKs
 
@@ -6240,6 +6273,10 @@ function parseRateLimitFlags(options) {
 *   - `--tail`: print the last hour's events, then poll every 3s for
 *     new events past the highest seen `EventTimestampMs`. Ctrl+C to stop.
 *
+* `--since-request-id <r_...>` anchors the range start at the oldest event
+* mentioning that request id ("show me everything from this request
+* onward") — the server resolves the anchor; works in both modes.
+*
 * Output formatting:
 *   - `--json`: NDJSON to stdout (one event per line) so `| jq` works.
 *   - default: human-readable lines:
@@ -6260,8 +6297,10 @@ async function functionsLogsCommand(functionName, options = {}) {
 		since: options.since,
 		until: options.until,
 		limit: options.limit,
-		requestId: options.requestId
+		requestId: options.requestId,
+		sinceRequestId: options.sinceRequestId
 	});
+	if (res.data.anchor && !options.json) console.error(pc.dim(`  Anchored at ${res.data.anchor} (--since-request-id).`));
 	printEvents(res.data.events, options.json);
 	if (res.data.truncated) if (options.json) process.stderr.write(`{"truncated":true}\n`);
 	else console.error(pc.yellow(`  ! Result truncated at limit; narrow --since / --until or raise --limit.`));
@@ -6269,21 +6308,33 @@ async function functionsLogsCommand(functionName, options = {}) {
 async function runTail(projectId, functionName, options) {
 	let sinceMs = options.since ? Date.parse(options.since) : Date.now() - 3600 * 1e3;
 	if (Number.isNaN(sinceMs)) throw new Error("--since must be a valid ISO 8601 timestamp");
-	if (!options.json) console.error(pc.dim(`  Tailing ${functionName} — Ctrl+C to stop. Initial backfill from ${new Date(sinceMs).toISOString()}.`));
+	if (!options.json) console.error(pc.dim(options.sinceRequestId ? `  Tailing ${functionName} — Ctrl+C to stop. Anchoring backfill at request ${options.sinceRequestId}.` : `  Tailing ${functionName} — Ctrl+C to stop. Initial backfill from ${new Date(sinceMs).toISOString()}.`));
 	let highWaterMs = sinceMs;
+	let firstFetch = true;
 	for (;;) {
 		let result;
+		const anchored = firstFetch && options.sinceRequestId !== void 0;
 		try {
 			result = await getFunctionLogs(projectId, functionName, {
-				since: new Date(highWaterMs).toISOString(),
+				...anchored ? { sinceRequestId: options.sinceRequestId } : { since: new Date(highWaterMs).toISOString() },
+				...anchored && options.since ? { since: options.since } : {},
 				limit: options.limit ?? 200,
 				requestId: options.requestId
 			});
 		} catch (err) {
+			if (anchored) throw err;
 			console.error(pc.yellow(`  ! tail fetch failed: `) + (err instanceof Error ? err.message : String(err)));
 			await sleep$1(TAIL_POLL_MS);
 			continue;
 		}
+		if (anchored) {
+			firstFetch = false;
+			if (result.data.anchor) {
+				if (!options.json) console.error(pc.dim(`  Anchored at ${result.data.anchor} (--since-request-id).`));
+				const anchorMs = Date.parse(result.data.anchor);
+				if (!Number.isNaN(anchorMs)) highWaterMs = anchorMs;
+			}
+		}
 		if (result.data.events.length > 0) {
 			printEvents(result.data.events, options.json);
 			highWaterMs = result.data.events.reduce((m, e) => Math.max(m, e.EventTimestampMs ?? 0), highWaterMs) + 1;
@@ -6548,6 +6599,11 @@ async function adminWrite$1(method, path, body) {
 	}
 	return await res.json();
 }
+/** Append "· $X.XX" to a usage line when the meter accrued cost this period. */
+function costSuffix(cost) {
+	if (!cost || cost.cost_usd <= 0) return "";
+	return `  ${pc.yellow(`$${cost.cost_usd.toFixed(2)}`)}`;
+}
 function formatAxis(label, axis, isStorage) {
 	const used = axis.used === null ? "—" : isStorage ? axis.used >= 1024 ? `${(axis.used / 1024).toFixed(2)} GB` : `${axis.used} MB` : axis.used.toLocaleString();
 	const limit = axis.limit === null ? "unlimited" : isStorage ? axis.limit >= 1024 ? `${(axis.limit / 1024).toFixed(0)} GB` : `${axis.limit} MB` : axis.limit.toLocaleString();
@@ -6565,18 +6621,29 @@ async function billingStatusCommand() {
 		console.log(`  Tier:               ${pc.bold(s.tier)}`);
 		console.log(`  Subscription:       ${s.subscription_status ?? pc.dim("—")}`);
 		console.log(`  Next bill anchor:   ${s.current_period_end ? new Date(s.current_period_end).toLocaleDateString() : pc.dim("—")}`);
-		console.log(`  Spend ceiling:      ${s.ceiling_usd === null ? pc.dim("no cap") : `$${s.ceiling_usd}`}`);
+		const pctCeiling = s.ceiling_pct_consumed === null || s.ceiling_pct_consumed === void 0 ? null : Math.round(s.ceiling_pct_consumed * 100);
+		console.log(`  Spend ceiling:      ${s.ceiling_usd === null ? pc.dim("no cap") : `$${s.ceiling_usd}${pctCeiling === null ? "" : pc.dim(` (${pctCeiling}% consumed)`)}`}`);
 		console.log(`  Spend mode:         ${s.mode}`);
 		console.log(`  Projected overage:  $${s.projected_overage_usd_this_month.toFixed(2)}`);
+		if (s.projected_end_of_period_overage_usd !== void 0 && s.period) console.log(`  End-of-period est.: $${s.projected_end_of_period_overage_usd.toFixed(2)} ${pc.dim(`(period resets ${new Date(s.period.resets_at).toLocaleDateString()})`)}`);
 		if (s.paused_at) console.log(`  ${pc.yellow("Paused at:")}          ${s.paused_at} ${pc.dim("(wakes on next request)")}`);
+		if (s.enforcement?.read_only) {
+			console.log();
+			console.log(pc.red("  READ-ONLY MODE: ") + "spend ceiling reached — metered writes return 402 until the period resets or the ceiling is raised.");
+		} else if (s.enforcement && s.enforcement.over_quota_meters.length > 0) {
+			console.log();
+			console.log(pc.yellow("  Over quota: ") + s.enforcement.over_quota_meters.join(", ") + pc.dim(" — writes on these meters are refused on throttle mode (402; new signups 429 at the MAU quota)."));
+		}
 		console.log();
 		console.log(pc.bold("  Usage — rolling 30 days"));
-		console.log(formatAxis("Monthly active users", s.headroom.mau, false));
-		console.log(formatAxis("Engagement events", s.headroom.engagement_events, false));
-		console.log(formatAxis("Telemetry events", s.headroom.telemetry_events, false));
-		console.log(formatAxis("Push deliveries", s.headroom.push, false));
-		console.log(formatAxis("Database storage", s.headroom.db_storage_mb, true));
-		console.log(formatAxis("Media storage", s.headroom.media_storage_mb, true));
+		const cost = s.usage_cost_by_meter ?? {};
+		console.log(formatAxis("Monthly active users", s.headroom.mau, false) + costSuffix(cost.mau));
+		console.log(formatAxis("Engagement events", s.headroom.engagement_events, false) + costSuffix(cost.engagement_events));
+		console.log(formatAxis("Telemetry events", s.headroom.telemetry_events, false) + costSuffix(cost.telemetry_events));
+		console.log(formatAxis("Push deliveries", s.headroom.push, false) + costSuffix(cost.push));
+		console.log(formatAxis("Database storage", s.headroom.db_storage_mb, true) + costSuffix(cost.db_storage_mb));
+		console.log(formatAxis("Media storage", s.headroom.media_storage_mb, true) + costSuffix(cost.media_storage_mb));
+		if (s.headroom.app_mcp_tool_calls) console.log(formatAxis("Agent tool calls", s.headroom.app_mcp_tool_calls, false) + costSuffix(cost.app_mcp_tool_calls));
 		console.log();
 		if (s.human_action_required !== "none") {
 			const action = s.human_action_required.replaceAll("_", " ");
@@ -6825,10 +6892,22 @@ async function paymentsPayoutsCommand(input) {
 *                                so the next plan is a no-op. Writes ONLY Amba's
 *                                own state — never the provider. Idempotent.
 *   amba monetization apply    — push the declared config to the provider.
-*                                ADDITIVE only: create entitlements/offerings/
-*                                packages/paywall-drafts + attach products.
-*                                Refuses if the provider drifted since the plan;
-*                                never does destructive changes.
+*                                DURABLE: the API returns a pollable
+*                                operation_id and the CLI polls it to a
+*                                terminal state. Additive changes apply
+*                                automatically; destructive changes run only
+*                                behind --confirm (which approves the exact
+*                                plan_hash — a pending apply awaiting
+*                                confirmation is approved by re-running with
+*                                --confirm). STORE-PRODUCT steps (creating
+*                                declared products in the provider and, for
+*                                App Store products with push intent in App
+*                                Store Connect, and Google Play one-time
+*                                products with push intent in Google Play)
+*                                ALWAYS wait for an explicit approval of the
+*                                started apply — an up-front --confirm never
+*                                auto-runs them. Refuses if the provider
+*                                drifted since the plan.
 *
 * Project is resolved via `loadProjectConfig` — same pattern as the other
 * project-scoped CLI commands.
@@ -6885,16 +6964,31 @@ async function monetizationPlanCommand() {
 		console.log();
 	}
 	if (plan.store_floor.length > 0) {
-		console.log(pc.yellow("  Store-floor preflight — referenced products missing in the provider:"));
-		for (const sf of plan.store_floor) console.log(`    ${pc.bold(sf.product_key)} → ${sf.store_identifier} (${sf.store})`);
+		console.log(pc.yellow("  Store-floor preflight — blocking gaps apply can neither resolve nor create:"));
+		for (const sf of plan.store_floor) {
+			console.log(`    ${pc.bold(sf.product_key)} → ${sf.store_identifier} (${sf.store})`);
+			console.log(pc.dim(`      ${sf.reason}`));
+		}
 		console.log();
 	}
+	printHumanFloor(plan.human_floor);
 	if (plan.drift.length > 0) {
 		console.log(pc.yellow("  Drift — managed objects changed out-of-band in the provider:"));
 		for (const d of plan.drift) console.log(`    ${pc.bold(d.object_type)} ${d.identifier}`);
 		console.log();
 	}
 }
+/** Print the store-side human-floor checklist (exact console locations). */
+function printHumanFloor(items) {
+	if (!items || items.length === 0) return;
+	console.log(pc.yellow("  Store checklist — steps no API can do (with exact locations):"));
+	for (const h of items) {
+		console.log(`    ${pc.bold("□")} ${h.title}${h.product_key ? pc.dim(` (${h.product_key})`) : ""}`);
+		console.log(pc.dim(`      ${h.detail}`));
+		console.log(pc.dim(`      where: ${h.location}`));
+	}
+	console.log();
+}
 async function monetizationDriftCommand() {
 	const { projectId } = await loadProjectConfig();
 	header("drift");
@@ -6939,10 +7033,13 @@ async function monetizationApplyCommand(options = {}) {
 	header("apply");
 	const plan = (await adminGet(`/projects/${projectId}/monetization/plan`)).data;
 	if (plan.store_floor.length > 0) {
-		console.log(pc.yellow("  Store floor not satisfied — these products must exist in the provider first:"));
-		for (const sf of plan.store_floor) console.log(`    ${pc.bold(sf.product_key)} → ${sf.store_identifier} (${sf.store})`);
+		console.log(pc.yellow("  Store floor not satisfied — apply can neither resolve nor create these:"));
+		for (const sf of plan.store_floor) {
+			console.log(`    ${pc.bold(sf.product_key)} → ${sf.store_identifier} (${sf.store})`);
+			console.log(pc.dim(`      ${sf.reason}`));
+		}
 		console.log();
-		console.log("  ✗ Configure these in the store, then run plan + apply again.");
+		console.log("  ✗ Fix the declaration (or connect the app), then run plan + apply again.");
 		process.exit(1);
 	}
 	if (plan.clean) {
@@ -6958,49 +7055,77 @@ async function monetizationApplyCommand(options = {}) {
 	if (options.confirm) body["confirm"] = plan.plan_hash;
 	if (options.allowDetachLive) body["allow_detach_live"] = true;
 	if (options.reconcile) body["reconcile"] = options.reconcile;
-	let res;
+	let start;
 	try {
-		res = await adminPost(`/projects/${projectId}/monetization/apply`, body);
+		start = (await adminPost(`/projects/${projectId}/monetization/apply`, body)).data;
 	} catch (err) {
-		if (err instanceof ApiClientError && err.errorCode === "MONETIZATION_CONFIRM_REQUIRED") {
-			console.log(pc.yellow("  ⚠ This plan includes gated destructive operation(s) — nothing was applied."));
-			console.log(pc.dim("    Review the plan, then re-run with --confirm to execute the gated ops:"));
-			console.log(`    ${pc.cyan("amba monetization apply --confirm")}`);
-			console.log();
-			process.exit(1);
-		}
-		if (err instanceof ApiClientError && err.errorCode === "MONETIZATION_INVARIANT") {
-			console.log(pc.red("  ✗ Blocked by the ordering invariant — nothing was applied:"));
-			console.log(pc.dim(`    ${err.message}`));
+		if (err instanceof ApiClientError && err.errorCode === "MONETIZATION_APPLY_IN_PROGRESS") {
+			console.log(pc.yellow("  ⚠ An apply is already in progress for this project."));
+			console.log(pc.dim("    Wait for it to finish, or re-run with --confirm to approve a pending confirmation."));
 			console.log();
 			process.exit(1);
 		}
 		throw err;
 	}
-	const d = res.data;
-	if (d.sandbox_stage?.ran) {
-		const tag = d.sandbox_stage.passed ? pc.green("✓ sandbox passed") : pc.red("✗ sandbox failed");
-		console.log(`  ${tag} ` + pc.dim(d.sandbox_stage.detail));
+	if (start.refused.length > 0) {
+		console.log(pc.yellow("  Not applicable via API (do these in the provider dashboard):"));
+		for (const r of start.refused) console.log(`    ${pc.bold(r.op)} ${r.object_type} ${r.identifier}`);
 		console.log();
 	}
-	if (d.status === "succeeded") console.log(pc.green("  ✓") + ` Applied ${d.applied} change(s) to the provider ` + pc.dim(`(${d.skipped_existing} already present, ${d.gated_applied} destructive)`));
-	else {
-		console.log(pc.red("  ✗") + ` Apply stopped after a failure (${d.applied} applied, ${d.failed} failed).` + (d.stopped_at ? ` Stopped at: ${d.stopped_at}` : ""));
-		const failed = d.results.find((r) => r.status === "failed");
-		if (failed?.error) console.log(pc.dim(`    ${failed.error}`));
+	if (start.status === "succeeded") {
+		console.log(pc.green("  ✓") + " Nothing to apply — declared config matches the provider.");
+		console.log();
+		return;
 	}
-	if (d.gated.length > 0) {
+	if (start.confirm_required) {
+		const storeSteps = start.gated.filter((g) => g.store === true);
+		console.log(pc.yellow("  ⚠ This plan includes gated operation(s) — they are NOT applied yet."));
+		for (const g of start.gated) {
+			const tag = g.store === true ? pc.magenta(" [store]") : "";
+			console.log(`    ${pc.bold(g.op)} ${g.object_type} ${g.identifier}${tag}`);
+		}
 		console.log();
-		console.log(pc.yellow("  Gated (destructive — run with --confirm to execute):"));
-		for (const g of d.gated) console.log(`    ${pc.bold(g.op.op)} ${g.op.object_type} ${g.op.identifier}`);
+		if (storeSteps.length > 0) console.log(pc.dim("    Store catalog steps require an explicit approval of THIS apply — an up-front --confirm never auto-runs them."));
+		printHumanFloor(start.human_floor);
+		console.log(pc.dim("    Review the plan, then approve the pending apply:"));
+		console.log(`    ${pc.cyan("amba monetization apply --confirm")}`);
+		console.log();
+		console.log(pc.dim(`    operation: ${start.operation_id}`));
+		console.log();
+		process.exit(1);
 	}
-	if (d.refused.length > 0) {
+	console.log(pc.dim(`  Applying… (operation ${start.operation_id} — safe to Ctrl-C; the apply continues)`));
+	const op = await pollApplyOperation(projectId, start.operation_id);
+	if (op.result?.sandbox_stage?.ran) {
+		const s = op.result.sandbox_stage;
+		const tag = s.passed ? pc.green("✓ sandbox passed") : pc.red("✗ sandbox failed");
+		console.log(`  ${tag} ` + pc.dim(s.detail));
 		console.log();
-		console.log(pc.yellow("  Not applicable via API (do these in the provider dashboard):"));
-		for (const r of d.refused) console.log(`    ${pc.bold(r.op.op)} ${r.op.object_type} ${r.op.identifier}`);
 	}
+	if (op.status === "succeeded") {
+		const r = op.result ?? {};
+		console.log(pc.green("  ✓") + ` Applied ${r.applied ?? 0} change(s) to the provider ` + pc.dim(`(${r.skipped_existing ?? 0} already present, ${r.gated_applied ?? 0} destructive)`));
+		console.log();
+		return;
+	}
+	console.log(pc.red("  ✗") + " Apply did not complete.");
+	if (op.failed_reason) console.log(pc.dim(`    ${op.failed_reason}`));
 	console.log();
-	if (d.status !== "succeeded") process.exit(1);
+	process.exit(1);
+}
+/** Poll GET /operations/:id until the apply reaches a terminal state. */
+async function pollApplyOperation(projectId, operationId) {
+	const POLL_INTERVAL_MS = 3e3;
+	const deadline = Date.now() + 900 * 1e3;
+	for (;;) {
+		const op = (await adminGet(`/projects/${projectId}/operations/${operationId}`)).data;
+		if (op.status === "succeeded" || op.status === "failed") return op;
+		if (Date.now() >= deadline) {
+			console.log(pc.yellow(`  ⚠ Still running server-side (operation ${operationId}).`) + pc.dim(" Re-run `amba monetization plan` later — a clean plan means it finished."));
+			process.exit(1);
+		}
+		await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+	}
 }
 //#endregion
 //#region src/commands/collections.ts
@@ -7044,7 +7169,13 @@ const ALLOWED_TYPES = new Set([
 	"timestamptz",
 	"date",
 	"jsonb",
-	"vector"
+	"vector",
+	"text[]",
+	"integer[]",
+	"bigint[]",
+	"numeric[]",
+	"boolean[]",
+	"uuid[]"
 ]);
 const TYPE_SYNONYMS = {
 	int: "integer",
@@ -7111,7 +7242,10 @@ async function collectionsDropCommand(name, options = {}) {
 }
 function normalizeColumnType(raw) {
 	const baseRaw = (raw.split("(")[0] ?? raw).trim().toLowerCase();
-	const base = TYPE_SYNONYMS[baseRaw] ?? baseRaw;
+	const isArray = baseRaw.endsWith("[]");
+	const elementRaw = isArray ? baseRaw.slice(0, -2) : baseRaw;
+	const element = TYPE_SYNONYMS[elementRaw] ?? elementRaw;
+	const base = isArray ? `${element}[]` : element;
 	if (!ALLOWED_TYPES.has(base)) throw new Error(`Unknown type '${raw}'. Allowed: ${[...ALLOWED_TYPES].join(", ")}.`);
 	return base;
 }
@@ -7121,7 +7255,11 @@ function normalizeColumnType(raw) {
 * Accepted grammars:
 *
 *   1. **Plain column:** `name:type[:nullable]`
-*      Examples: `letter_id:uuid`, `parsed:jsonb:nullable`.
+*      Examples: `letter_id:uuid`, `parsed:jsonb:nullable`, `tags:text[]`,
+*      `scores:integer[]:nullable`. Array types (`text[]`, `integer[]`,
+*      `bigint[]`, `numeric[]`, `boolean[]`, `uuid[]`) follow the same
+*      grammar as scalars and unlock the contains/containedBy/overlaps
+*      query operators.
 *
 *   2. **Foreign key:** `name:type:fk(<table>[.<column>][:onDelete])`
 *      Examples:
@@ -7148,12 +7286,14 @@ function normalizeColumnType(raw) {
 * left-to-right: the third segment is the FK / vector / nullable
 * marker; if it's an FK or vector, the optional fourth segment is
 * `nullable`. Plain columns put `nullable` in slot 3.
+*
+* Exported for tests.
 */
 function parseColumnSpec(spec) {
 	const parts = spec.replace(/^([a-z_][a-z0-9_]*):vector\((\d+)\)/i, "$1:vector:$2").replace(/fk\(([^)]+)\)/i, (_match, inner) => {
 		return `fk(${inner.replace(/:/g, "|")})`;
 	}).split(":");
-	if (parts.length < 2 || parts.length > 4) throw new Error(`Invalid field spec '${spec}'. Grammar:\n  name:type[:nullable]                          (plain)\n  name:type:fk(table[.col][:onDelete])[:nullable] (foreign key)\n  name:vector:<dim>[:nullable]                  (vector / pgvector)\nExamples: user_id:uuid, parsed:jsonb:nullable, plan_id:uuid:fk(plans),\n          embedding:vector:1536, comment_id:uuid:fk(comments.id:set_null).`);
+	if (parts.length < 2 || parts.length > 4) throw new Error(`Invalid field spec '${spec}'. Grammar:\n  name:type[:nullable]                          (plain)\n  name:type:fk(table[.col][:onDelete])[:nullable] (foreign key)\n  name:vector:<dim>[:nullable]                  (vector / pgvector)\nExamples: user_id:uuid, tags:text[], parsed:jsonb:nullable, plan_id:uuid:fk(plans),\n          embedding:vector:1536, comment_id:uuid:fk(comments.id:set_null).`);
 	const colName = parts[0];
 	const type = parts[1];
 	const slot3 = parts[2];
@@ -7243,6 +7383,8 @@ function normalizeOnDelete(raw) {
 *
 * Bare column names (no direction) are passed through verbatim; the
 * default sort direction is the DDL emit's responsibility.
+*
+* Exported for tests.
 */
 function parseIndexSpec(spec) {
 	const cols = [];
@@ -7258,6 +7400,1184 @@ function parseIndexSpec(spec) {
 	return { columns: cols };
 }
 //#endregion
+//#region src/ship/config.ts
+/**
+* `amba ship` config — the typed, hand-validated launch config.
+*
+* One file per repo (default `amba.ship.json`) describes how to take this Expo
+* app from code-complete to live on the App Store and Google Play. It carries
+* NON-SECRET identifiers and the NAME of the env var holding the Expo token —
+* never secret values (the App Store Connect `.p8` and Play service-account
+* JSON live in `eas.json`, owned by the app repo, exactly where the build runs).
+*
+* Validation is hand-rolled (the CLI deliberately ships no `zod` — see
+* `_internal/shared.ts` for the same return-all-errors-at-once pattern). The
+* field names are the canonical contract; `validateShipConfig` reports every
+* problem in one pass and enforces the cross-field invariants.
+*
+* Monetization is NOT described here: the App Store / Play product catalog is
+* Amba's monetization control plane (`amba monetization`, the durable Track H
+* apply against the provider). `ship` only flips `monetization.enabled` to
+* decide whether to verify that catalog is in sync before building.
+*/
+/** The ordered launch phases. `ship` runs them in this sequence. */
+const SHIP_PHASES = [
+	"preflight",
+	"monetization",
+	"build",
+	"submit",
+	"metadata",
+	"release"
+];
+const SHIP_PLATFORMS = ["ios", "android"];
+/** Google Play release tracks `ship` can submit to. */
+const PLAY_TRACKS = [
+	"internal",
+	"alpha",
+	"beta",
+	"production"
+];
+/** Default config filename when no `--config <path>` is passed. */
+const DEFAULT_SHIP_CONFIG_FILE = "amba.ship.json";
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+const REVERSE_DNS_RE = /^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)+$/;
+function asObject(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+	return value;
+}
+/**
+* Validate an untrusted parsed JSON value into a typed `ShipConfig`,
+* collecting EVERY problem (not just the first) so a misconfigured file
+* surfaces all its issues in one run. Returns the typed config on success.
+*/
+function validateShipConfig(raw) {
+	const errors = [];
+	const root = asObject(raw);
+	if (!root) return {
+		ok: false,
+		errors: ["config must be a JSON object"]
+	};
+	if (typeof root["version"] !== "number") errors.push("version must be a number");
+	const app = asObject(root["app"]);
+	if (!app) errors.push("app must be an object");
+	else {
+		const slug = app["slug"];
+		if (typeof slug !== "string" || !SLUG_RE.test(slug)) errors.push("app.slug must be lowercase letters, digits and dashes");
+		if (typeof app["name"] !== "string" || app["name"].trim().length === 0) errors.push("app.name must be a non-empty string");
+		if (typeof app["version"] !== "string" || !SEMVER_RE.test(app["version"])) errors.push("app.version must be semver MAJOR.MINOR.PATCH");
+		if (typeof app["bundleId"] !== "string" || !REVERSE_DNS_RE.test(app["bundleId"])) errors.push("app.bundleId must be a reverse-DNS identifier like ai.uselayers.unbury");
+		if (typeof app["androidPackage"] !== "string" || !REVERSE_DNS_RE.test(app["androidPackage"])) errors.push("app.androidPackage must be a reverse-DNS identifier like ai.uselayers.unbury");
+	}
+	const build = asObject(root["build"]);
+	if (!build) errors.push("build must be an object");
+	else {
+		if (typeof build["profile"] !== "string" || build["profile"].trim().length === 0) errors.push("build.profile must be a non-empty string (an eas.json build profile)");
+		const platforms = build["platforms"];
+		if (!Array.isArray(platforms) || platforms.length === 0) errors.push("build.platforms must be a non-empty array of \"ios\" | \"android\"");
+		else {
+			const seen = /* @__PURE__ */ new Set();
+			for (const p of platforms) if (p !== "ios" && p !== "android") errors.push(`build.platforms entries must be "ios" or "android" (got ${JSON.stringify(p)})`);
+			else if (seen.has(p)) errors.push(`build.platforms has a duplicate entry "${p}"`);
+			else seen.add(p);
+		}
+	}
+	const ios = asObject(root["ios"]);
+	if (!ios) errors.push("ios must be an object");
+	else if (ios["ascAppId"] !== null && typeof ios["ascAppId"] !== "string") errors.push("ios.ascAppId must be a string or null");
+	else if (typeof ios["ascAppId"] === "string" && ios["ascAppId"].trim().length === 0) errors.push("ios.ascAppId must be a non-empty string when set (or null)");
+	const android = asObject(root["android"]);
+	if (!android) errors.push("android must be an object");
+	else if (!PLAY_TRACKS.includes(android["track"])) errors.push(`android.track must be one of ${PLAY_TRACKS.join(" | ")}`);
+	const monetization = asObject(root["monetization"]);
+	if (!monetization) errors.push("monetization must be an object");
+	else if (typeof monetization["enabled"] !== "boolean") errors.push("monetization.enabled must be a boolean");
+	const secrets = asObject(root["secrets"]);
+	if (!secrets) errors.push("secrets must be an object");
+	else if (typeof secrets["expoTokenEnvVar"] !== "string" || secrets["expoTokenEnvVar"].trim().length === 0) errors.push("secrets.expoTokenEnvVar must be a non-empty env var NAME (e.g. \"EXPO_TOKEN\")");
+	if (errors.length > 0) return {
+		ok: false,
+		errors
+	};
+	const a = app;
+	const b = build;
+	return {
+		ok: true,
+		config: {
+			version: root["version"],
+			app: {
+				slug: a["slug"],
+				name: a["name"].trim(),
+				version: a["version"],
+				bundleId: a["bundleId"],
+				androidPackage: a["androidPackage"]
+			},
+			build: {
+				profile: b["profile"].trim(),
+				platforms: b["platforms"].slice()
+			},
+			ios: { ascAppId: ios["ascAppId"] },
+			android: { track: android["track"] },
+			monetization: { enabled: monetization["enabled"] },
+			secrets: { expoTokenEnvVar: secrets["expoTokenEnvVar"].trim() }
+		}
+	};
+}
+/**
+* A starter config written by `amba ship init`. Placeholders are intentionally
+* obvious so the validator's invariants don't pass on an unedited file's IDs
+* (the reverse-DNS / semver placeholders DO validate so `--phase preflight`
+* works immediately; the operator swaps in their real values).
+*/
+function shipConfigTemplate(slug) {
+	return {
+		version: 1,
+		app: {
+			slug,
+			name: "My App",
+			version: "1.0.0",
+			bundleId: `com.example.${slug.replace(/-/g, "")}`,
+			androidPackage: `com.example.${slug.replace(/-/g, "")}`
+		},
+		build: {
+			profile: "production",
+			platforms: ["ios", "android"]
+		},
+		ios: { ascAppId: null },
+		android: { track: "internal" },
+		monetization: { enabled: false },
+		secrets: { expoTokenEnvVar: "EXPO_TOKEN" }
+	};
+}
+//#endregion
+//#region src/ship/exec.ts
+/**
+* The external-command boundary for `amba ship`.
+*
+* Every shell-out (always `eas`) goes through an `Executor`, so the phase
+* logic — which args get built, how `--json` output is parsed, which failures
+* map to which manual gate — is unit-tested against a fake executor with NO
+* live cloud, no EAS account, and no Apple/Google credentials. The default
+* `createNodeExecutor()` is a thin, shell-free wrapper around
+* `node:child_process.spawn` (mirrors the launch toolkit's `lib/exec`).
+*/
+/**
+* Redact secret-shaped tokens from a string before it is logged. A backstop,
+* not a license — `ship` never puts secret values on a command line (EAS reads
+* its token from the env and its store creds from eas.json). Covers Expo /
+* common access-token shapes and `Bearer`/`sk_` prefixes.
+*/
+function redactSecrets(text) {
+	return text.replace(/\b(Bearer)\s+[A-Za-z0-9._-]+/gi, "$1 ***").replace(/\b(sk|pk|rcb)_[A-Za-z0-9]+/g, "$1_***").replace(/\bamb_dpat_[A-Za-z0-9_-]+/g, "amb_dpat_***").replace(/\b[A-Za-z0-9_-]*EXPO_TOKEN[A-Za-z0-9_-]*=\S+/g, "EXPO_TOKEN=***");
+}
+/** A backing executor over `node:child_process.spawn`. Never invokes a shell. */
+function createNodeExecutor(globalDryRun = false) {
+	return { run(cmd, args, opts = {}) {
+		const dryRun = opts.dryRun ?? globalDryRun;
+		const printable = redactSecrets([cmd, ...args].join(" "));
+		if (dryRun) return Promise.resolve({
+			command: printable,
+			code: 0,
+			stdout: "",
+			stderr: "",
+			dryRun: true
+		});
+		const stream = opts.stream ?? false;
+		return new Promise((resolve, reject) => {
+			const child = spawn(cmd, args, {
+				cwd: opts.cwd ?? process$1.cwd(),
+				env: opts.env ? {
+					...process$1.env,
+					...opts.env
+				} : process$1.env,
+				shell: false
+			});
+			let stdout = "";
+			let stderr = "";
+			let timedOut = false;
+			let timer;
+			if (opts.timeoutMs && opts.timeoutMs > 0) timer = setTimeout(() => {
+				timedOut = true;
+				child.kill("SIGKILL");
+			}, opts.timeoutMs);
+			child.stdout?.on("data", (chunk) => {
+				const s = chunk.toString();
+				stdout += s;
+				if (stream) process$1.stdout.write(redactSecrets(s));
+			});
+			child.stderr?.on("data", (chunk) => {
+				const s = chunk.toString();
+				stderr += s;
+				if (stream) process$1.stderr.write(redactSecrets(s));
+			});
+			child.on("error", (err) => {
+				if (timer) clearTimeout(timer);
+				const hint = err.code === "ENOENT" ? `Command "${cmd}" not found. Is it installed and on PATH?` : err.message;
+				reject(/* @__PURE__ */ new Error(`Failed to start "${printable}": ${hint}`));
+			});
+			child.on("close", (code) => {
+				if (timer) clearTimeout(timer);
+				if (timedOut) {
+					reject(/* @__PURE__ */ new Error(`Command timed out after ${opts.timeoutMs}ms: ${printable}\n  stderr tail: ${redactSecrets(stderr.slice(-400))}`));
+					return;
+				}
+				if ((code ?? -1) !== 0) {
+					reject(/* @__PURE__ */ new Error(`Command failed (exit ${code ?? -1}): ${printable}\n  stderr tail: ${redactSecrets(stderr.slice(-400) || stdout.slice(-400) || "(no output)")}`));
+					return;
+				}
+				resolve({
+					command: printable,
+					code: code ?? 0,
+					stdout,
+					stderr,
+					dryRun: false
+				});
+			});
+		});
+	} };
+}
+/**
+* Run a command and report success/failure WITHOUT throwing — for read-only
+* "is this CLI installed/authed?" probes where a non-zero exit is data, not a
+* fatal error.
+*/
+async function probe(exec, cmd, args, opts = {}) {
+	try {
+		return {
+			ok: true,
+			result: await exec.run(cmd, args, {
+				...opts,
+				dryRun: false
+			})
+		};
+	} catch {
+		return { ok: false };
+	}
+}
+//#endregion
+//#region src/ship/state.ts
+/**
+* `amba ship` per-app idempotency state.
+*
+* Each app's launch progress is a JSON file at `.amba/ship-state/<slug>.json`
+* recording, per phase, whether it is done / failed / blocked-by-a-human-gate /
+* in-progress, when, and an optional structured `note` (e.g. the build ids a
+* later phase reads back). The orchestrator uses it to skip already-done phases
+* and to resume the "clear a gate → re-run" loop.
+*
+* PURITY RULE: this module NEVER reads the clock itself — callers pass an
+* ISO-8601 timestamp into every mutation so it stays deterministically
+* testable (the orchestrator owns the clock). The file is purely an
+* optimization/audit log: deleting it is safe because every phase re-detects
+* real cloud state before mutating.
+*/
+const STATE_DIR = path.join(".amba", "ship-state");
+/** Path to the state file for a slug, under `<baseDir>/.amba/ship-state/`. */
+function shipStatePath(slug, baseDir = process.cwd()) {
+	return path.join(baseDir, STATE_DIR, `${slug}.json`);
+}
+/** Load state for a slug, or a fresh empty state if none exists. Pure read. */
+function loadShipState(slug, baseDir = process.cwd()) {
+	const file = shipStatePath(slug, baseDir);
+	if (!fs.existsSync(file)) return {
+		slug,
+		stateVersion: 1,
+		phases: {}
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+	} catch (err) {
+		throw new Error(`Corrupt ship state at ${file}: ${err instanceof Error ? err.message : String(err)}. Delete it to start fresh (phases re-detect cloud state).`);
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`Corrupt ship state at ${file}: expected a JSON object. Delete it to start fresh.`);
+	const state = parsed;
+	if (state.slug !== slug) throw new Error(`State file ${file} is for slug "${state.slug}", expected "${slug}".`);
+	if (!state.phases || typeof state.phases !== "object") state.phases = {};
+	return state;
+}
+/** Write state atomically (write temp, then rename) to avoid partial files. */
+function saveShipState(state, baseDir = process.cwd()) {
+	const file = shipStatePath(state.slug, baseDir);
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	const tmp = `${file}.tmp`;
+	fs.writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n", "utf8");
+	fs.renameSync(tmp, file);
+}
+/**
+* Return a NEW state with one phase updated. Pure: does not touch disk and does
+* not read the clock — the caller passes `timestamp`. Use `saveShipState` to
+* persist.
+*/
+function withPhase(state, phase, status, timestamp, note) {
+	return {
+		...state,
+		phases: {
+			...state.phases,
+			[phase]: {
+				status,
+				updatedAt: timestamp,
+				...note !== void 0 ? { note } : {}
+			}
+		}
+	};
+}
+/** True if a phase is recorded as done. Used by the orchestrator for idempotency. */
+function isPhaseDone(state, phase) {
+	return state.phases[phase]?.status === "done";
+}
+//#endregion
+//#region src/ship/phases.ts
+const EAS = "eas";
+const EXEC_TIMEOUT_MS = 10 * 6e4;
+function easBuildArgs(platform, profile) {
+	return [
+		"build",
+		"--platform",
+		platform,
+		"--profile",
+		profile,
+		"--non-interactive",
+		"--json",
+		"--no-wait"
+	];
+}
+function easSubmitArgs(input) {
+	const selector = input.buildId ? ["--id", input.buildId] : ["--latest"];
+	const track = input.track ? ["--track", input.track] : [];
+	return [
+		"submit",
+		"--platform",
+		input.platform,
+		"--profile",
+		input.profile,
+		...selector,
+		...track,
+		"--non-interactive",
+		"--json",
+		"--no-wait"
+	];
+}
+function easBuildViewArgs(buildId) {
+	return [
+		"build:view",
+		buildId,
+		"--json",
+		"--non-interactive"
+	];
+}
+function easMetadataArgs(profile) {
+	return [
+		"metadata:push",
+		"--profile",
+		profile,
+		"--non-interactive"
+	];
+}
+/** Parse the first JSON value out of CLI stdout, tolerating a leaked banner. */
+function parseLooseJson(raw) {
+	const trimmed = (raw || "").trim();
+	if (!trimmed) return null;
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		const start = trimmed.search(/[[{]/);
+		if (start === -1) return null;
+		try {
+			return JSON.parse(trimmed.slice(start));
+		} catch {
+			return null;
+		}
+	}
+}
+/** Pull the build object for `platform` out of `eas build --json` stdout. */
+function extractBuild(raw, platform) {
+	const parsed = parseLooseJson(raw);
+	if (parsed === null) throw new Error("eas build --json produced no parseable output. Is the Expo token set and the project linked (eas init)?");
+	const builds = Array.isArray(parsed) ? parsed : [parsed];
+	const want = platform.toUpperCase();
+	const match = builds.find((b) => (b.platform ?? "").toUpperCase() === want);
+	if (match?.id) return match;
+	const sole = builds.length === 1 ? builds[0] : void 0;
+	if (sole?.id && (!sole.platform || sole.platform.toUpperCase() === want)) return sole;
+	throw new Error(`eas build --json did not return a build id for ${platform}.`);
+}
+function artifactUrlOf(b) {
+	return b.artifacts?.applicationArchiveUrl ?? b.artifacts?.buildUrl ?? null;
+}
+/** Parse the submission object for `platform` out of `eas submit --json` stdout. */
+function parseSubmission(raw, platform) {
+	const parsed = parseLooseJson(raw);
+	if (parsed === null) return { platform };
+	const subs = Array.isArray(parsed) ? parsed : [parsed];
+	const want = platform.toUpperCase();
+	const match = subs.find((s) => (s.platform ?? "").toUpperCase() === want);
+	if (match) return match;
+	const sole = subs.length === 1 ? subs[0] : void 0;
+	if (sole && (!sole.platform || sole.platform.toUpperCase() === want)) return sole;
+	return { platform };
+}
+function diagnoseBuildFailure(message) {
+	const o = (message || "").toLowerCase();
+	if (o.includes("not found") && o.includes("eas")) return "eas CLI not installed. Install it with `npm i -g eas-cli`, then re-run.";
+	if (o.includes("not logged in") || o.includes("expo_token") || o.includes("authenticate")) return "Auth: set your Expo token env var (non-interactive) or run `eas login`.";
+	if (o.includes("eas.json") || o.includes("build profile")) return "Missing/invalid eas.json or the build profile. Add a build.<profile> entry to eas.json.";
+	if (o.includes("project") && o.includes("id") || o.includes("eas init")) return "Project not linked. Run `eas init` once (writes extra.eas.projectId into app.json), then re-run.";
+	if (o.includes("credential") || o.includes("keystore") || o.includes("distribution certificate") || o.includes("provisioning profile")) return "Missing signing credentials. Under --non-interactive EAS will not create them — run `eas credentials` once.";
+	return "See the eas build prerequisites (eas.json build profile, linked project, signing credentials).";
+}
+/** A submit failure that needs a human store action, or null for a plain error. */
+function diagnoseSubmitGate(platform, message) {
+	const o = (message || "").toLowerCase();
+	if (platform === "ios") {
+		if (o.includes("ascappid") || o.includes("app store connect") && o.includes("not found")) return "The App Store Connect app record is missing. Create it at appstoreconnect.apple.com → Apps → +, then set ios.ascAppId. EAS Submit cannot create it (eas-cli #2418).";
+		if (o.includes("export compliance") || o.includes("encryption")) return "The first upload needs an export-compliance answer in App Store Connect (appstoreconnect.apple.com).";
+	} else {
+		if (o.includes("manually at least once") || o.includes("upload your app manually")) return "Google requires the Play app + first release to be created/published ONCE in Play Console (play.google.com/console) before API submissions work.";
+		if (o.includes("service account") || o.includes("permission") || o.includes("androidpublisher")) return "The Play service account lacks access, or the Play Developer API is disabled — grant it in Play Console and enable androidpublisher.googleapis.com.";
+	}
+	return null;
+}
+function readNote(ctx, phase) {
+	const raw = ctx.getNote(phase);
+	if (!raw) return null;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+const TERMINAL_OK = "finished";
+const TERMINAL_BAD = new Set(["errored", "canceled"]);
+/**
+* The env to pass to every `eas` child. EAS reads the token from `EXPO_TOKEN`
+* specifically, so a config that names a DIFFERENT env var
+* (`secrets.expoTokenEnvVar`) must map that value onto `EXPO_TOKEN` — otherwise
+* a non-default name passes preflight while `eas build`/`submit` run
+* unauthenticated.
+*/
+function easEnv(ctx) {
+	const varName = ctx.config.secrets.expoTokenEnvVar;
+	const token = ctx.env[varName];
+	if (varName !== "EXPO_TOKEN" && token) return {
+		...ctx.env,
+		EXPO_TOKEN: token
+	};
+	return ctx.env;
+}
+/** Config-derived store gates (no external call) — surfaced by preflight. */
+function storeGateWarnings(ctx) {
+	const warnings = [];
+	if (ctx.platforms.includes("ios") && !ctx.config.ios.ascAppId) warnings.push("ios.ascAppId is null — create the App Store Connect app record (appstoreconnect.apple.com → Apps → +) and set it before the submit phase.");
+	if (ctx.platforms.includes("android")) warnings.push("Android: the Play app + first release must be created/published once in Play Console before API submissions work.");
+	return warnings;
+}
+const runPreflight = async (ctx) => {
+	const tokenVar = ctx.config.secrets.expoTokenEnvVar;
+	if (ctx.dryRun) {
+		ctx.log("would verify: eas installed + authenticated");
+		const warnings = storeGateWarnings(ctx);
+		for (const w of warnings) ctx.log(`warning: ${w}`);
+		return {
+			status: "done",
+			detail: "dry-run: eas probes not executed"
+		};
+	}
+	const warnings = [];
+	if (!(await probe(ctx.exec, EAS, ["--version"])).ok) return {
+		status: "failed",
+		detail: "eas CLI not found on PATH. Install it with `npm i -g eas-cli`, then re-run preflight."
+	};
+	ctx.log("eas CLI installed");
+	const tokenSet = (ctx.env[tokenVar] ?? "").trim().length > 0;
+	if ((await probe(ctx.exec, EAS, ["whoami"], { env: easEnv(ctx) })).ok) ctx.log(`eas authenticated ${tokenSet ? `(via ${tokenVar})` : "(via stored CLI session)"}`);
+	else if (tokenSet) ctx.log(`${tokenVar} is set (eas whoami unavailable — token used at build time)`);
+	else warnings.push(`Not authenticated with EAS: set ${tokenVar} (CI) or run \`eas login\`. Build will fail without it.`);
+	warnings.push(...storeGateWarnings(ctx));
+	for (const w of warnings) ctx.log(`warning: ${w}`);
+	return {
+		status: "done",
+		detail: warnings.length === 0 ? "all checks passed" : `${warnings.length} warning(s)`
+	};
+};
+const runMonetization = async (ctx) => {
+	if (!ctx.config.monetization.enabled) return {
+		status: "skipped",
+		detail: "monetization disabled in config"
+	};
+	const projectId = await ctx.resolveProjectId();
+	if (!projectId) return {
+		status: "skipped",
+		detail: "no Amba project linked — run `amba init` to manage the store product catalog"
+	};
+	if (ctx.dryRun) return {
+		status: "done",
+		detail: `would verify the monetization catalog for project ${projectId}`
+	};
+	let plan;
+	try {
+		plan = (await ctx.adminGet(`/projects/${projectId}/monetization/plan`)).data;
+	} catch (err) {
+		if (err instanceof ApiClientError && (err.errorCode === "MONETIZATION_NOT_CONFIGURED" || err.errorCode === "MONETIZATION_NOT_MIGRATED")) return {
+			status: "skipped",
+			detail: "no monetization configured for this project (nothing to verify)"
+		};
+		return {
+			status: "failed",
+			detail: `could not verify monetization: ${err instanceof Error ? err.message : String(err)}. Fix API access (or set monetization.enabled=false) and re-run.`
+		};
+	}
+	if (plan.clean) return {
+		status: "done",
+		detail: "store product catalog is in sync"
+	};
+	const gates = [];
+	for (const op of plan.ops) gates.push(`${op.op} ${op.object_type} ${op.identifier}`);
+	for (const sf of plan.store_floor) gates.push(`store floor: ${sf.product_key} → ${sf.store_identifier} (${sf.store}) — ${sf.reason}`);
+	for (const h of plan.human_floor ?? []) gates.push(`${h.title} — ${h.detail} (${h.location})`);
+	gates.push("Apply with `amba monetization apply`.");
+	return {
+		status: "gate",
+		detail: `monetization catalog has ${plan.ops.length} pending change(s)`,
+		gates
+	};
+};
+const runBuild = async (ctx) => {
+	const { profile } = ctx.config.build;
+	const tokenVar = ctx.config.secrets.expoTokenEnvVar;
+	if ((ctx.env[tokenVar] ?? "").trim().length === 0) ctx.log(`warning: ${tokenVar} not set — eas build needs it for non-interactive CI auth.`);
+	const builds = { ...readNote(ctx, "build")?.builds };
+	for (const platform of ctx.platforms) {
+		const existing = builds[platform];
+		if (existing && existing.appVersion === ctx.config.app.version && existing.profile === profile && !TERMINAL_BAD.has((existing.status || "").toLowerCase()) && !ctx.force) {
+			ctx.log(`${platform}: reusing build ${existing.buildId} (${existing.status}) — pass --force to rebuild`);
+			continue;
+		}
+		ctx.log(`${platform}: triggering eas ${profile} build…`);
+		let stdout = "";
+		let isDry = false;
+		try {
+			const res = await ctx.exec.run(EAS, easBuildArgs(platform, profile), {
+				env: easEnv(ctx),
+				timeoutMs: EXEC_TIMEOUT_MS,
+				dryRun: ctx.dryRun
+			});
+			stdout = res.stdout;
+			isDry = res.dryRun;
+		} catch (err) {
+			return {
+				status: "failed",
+				detail: `${platform} build failed: ${diagnoseBuildFailure(err instanceof Error ? err.message : String(err))}`,
+				note: JSON.stringify({
+					profile,
+					appVersion: ctx.config.app.version,
+					builds
+				})
+			};
+		}
+		const record = isDry ? {
+			buildId: `dry-run-${platform}`,
+			status: "dry-run",
+			platform,
+			artifactUrl: null,
+			buildPageUrl: null,
+			appVersion: ctx.config.app.version,
+			profile,
+			triggeredAt: ctx.now()
+		} : (() => {
+			const b = extractBuild(stdout, platform);
+			return {
+				buildId: b.id,
+				status: b.status ?? "in-queue",
+				platform,
+				artifactUrl: artifactUrlOf(b),
+				buildPageUrl: b.buildDetailsPageUrl ?? null,
+				appVersion: b.appVersion ?? ctx.config.app.version,
+				profile,
+				triggeredAt: ctx.now()
+			};
+		})();
+		builds[platform] = record;
+		ctx.log(`${platform}: queued build ${record.buildId} (${record.status})`);
+		ctx.checkpoint("build", "in-progress", JSON.stringify({
+			profile,
+			appVersion: ctx.config.app.version,
+			builds
+		}));
+	}
+	const note = {
+		profile,
+		appVersion: ctx.config.app.version,
+		builds
+	};
+	return {
+		status: "done",
+		detail: Object.values(builds).map((r) => `${r.platform}=${r.buildId}(${r.status})`).join(" "),
+		note: JSON.stringify(note)
+	};
+};
+const runSubmit = async (ctx) => {
+	const { profile } = ctx.config.build;
+	const prior = readNote(ctx, "submit");
+	const buildNote = readNote(ctx, "build");
+	const submissions = { ...prior?.submissions };
+	const gates = [];
+	let failure = null;
+	for (const platform of ctx.platforms) {
+		if (platform === "ios" && !ctx.config.ios.ascAppId) {
+			gates.push("iOS: create the App Store Connect app record (appstoreconnect.apple.com → Apps → +) and set ios.ascAppId, then re-run submit.");
+			continue;
+		}
+		const buildId = buildNote?.builds?.[platform]?.buildId ?? null;
+		if (!buildId) ctx.log(`${platform}: no recorded build id — submitting --latest (run the build phase first for a deterministic mapping)`);
+		const existing = submissions[platform];
+		if (existing && existing.buildId === buildId && !TERMINAL_BAD.has((existing.status || "").toLowerCase()) && !ctx.force) {
+			ctx.log(`${platform}: already submitted for build ${buildId ?? "(latest)"} (${existing.status}) — pass --force to resubmit`);
+			continue;
+		}
+		ctx.log(`${platform}: submitting to the store…`);
+		const track = platform === "android" ? ctx.config.android.track : void 0;
+		let stdout = "";
+		let isDry = false;
+		try {
+			const res = await ctx.exec.run(EAS, easSubmitArgs({
+				platform,
+				profile,
+				buildId,
+				track
+			}), {
+				env: easEnv(ctx),
+				timeoutMs: EXEC_TIMEOUT_MS,
+				dryRun: ctx.dryRun
+			});
+			stdout = res.stdout;
+			isDry = res.dryRun;
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			const gate = diagnoseSubmitGate(platform, msg);
+			if (gate) {
+				gates.push(`${platform}: ${gate}`);
+				continue;
+			}
+			failure = `${platform} submit failed: ${msg}`;
+			break;
+		}
+		const record = isDry ? {
+			submissionId: `dry-run-${platform}`,
+			status: "dry-run",
+			platform,
+			buildId,
+			detailsPageUrl: null,
+			submittedAt: ctx.now()
+		} : (() => {
+			const s = parseSubmission(stdout, platform);
+			return {
+				submissionId: s.id ?? null,
+				status: s.status ?? "in-queue",
+				platform,
+				buildId: s.buildId ?? buildId,
+				detailsPageUrl: s.submissionDetailsPageUrl ?? null,
+				submittedAt: ctx.now()
+			};
+		})();
+		submissions[platform] = record;
+		ctx.log(`${platform}: submitted (${record.status})`);
+		ctx.checkpoint("submit", "in-progress", JSON.stringify({
+			profile,
+			submissions
+		}));
+	}
+	const note = JSON.stringify({
+		profile,
+		submissions
+	});
+	if (failure) return {
+		status: "failed",
+		detail: failure,
+		note
+	};
+	if (gates.length > 0) return {
+		status: "gate",
+		detail: `${gates.length} platform(s) need a store action`,
+		note,
+		gates
+	};
+	return {
+		status: "done",
+		detail: Object.values(submissions).map((r) => `${r.platform}=${r.status}`).join(" "),
+		note
+	};
+};
+const runMetadata = async (ctx) => {
+	const reminders = [];
+	if (ctx.platforms.includes("ios")) reminders.push("iOS: capture screenshots and complete the App Privacy questionnaire in App Store Connect.");
+	if (ctx.platforms.includes("android")) reminders.push("Android: complete the Play listing (graphics, Data safety, Content rating) in Play Console.");
+	if (ctx.platforms.includes("ios")) {
+		ctx.log("pushing App Store listing metadata…");
+		try {
+			await ctx.exec.run(EAS, easMetadataArgs(ctx.config.build.profile), {
+				env: easEnv(ctx),
+				timeoutMs: EXEC_TIMEOUT_MS,
+				dryRun: ctx.dryRun
+			});
+			ctx.log("App Store listing metadata pushed");
+		} catch (err) {
+			return {
+				status: "gate",
+				detail: `eas metadata:push did not run: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
+				gates: ["Configure the App Store listing (eas.json metadata) or complete it in App Store Connect.", ...reminders]
+			};
+		}
+	}
+	for (const r of reminders) ctx.log(`reminder: ${r}`);
+	return {
+		status: "done",
+		detail: "listing metadata pushed; complete the store-side checklist",
+		gates: reminders
+	};
+};
+/** Poll a build to a terminal state via `eas build:view`. Returns the last status. */
+async function waitForBuild(ctx, buildId) {
+	if (ctx.dryRun) return TERMINAL_OK;
+	const deadline = Date.now() + ctx.releaseMaxWaitMs;
+	let last = "unknown";
+	for (;;) {
+		const res = await probe(ctx.exec, EAS, easBuildViewArgs(buildId), { env: easEnv(ctx) });
+		if (res.ok && res.result) {
+			if (res.result.dryRun) return TERMINAL_OK;
+			const parsed = parseLooseJson(res.result.stdout);
+			last = ((Array.isArray(parsed) ? parsed[0] : parsed)?.status ?? last ?? "unknown").toLowerCase();
+		}
+		if (last === TERMINAL_OK || TERMINAL_BAD.has(last)) return last;
+		if (Date.now() >= deadline) return last;
+		ctx.log(`build ${buildId}: ${last} — re-checking…`);
+		await ctx.sleep(ctx.releasePollMs);
+	}
+}
+const runRelease = async (ctx) => {
+	const profile = ctx.config.build.profile;
+	const prior = readNote(ctx, "release");
+	const buildNote = readNote(ctx, "build");
+	const submitNote = readNote(ctx, "submit");
+	const releases = { ...prior?.releases };
+	const gates = [];
+	let failure = null;
+	for (const platform of ctx.platforms) {
+		const buildRec = buildNote?.builds?.[platform];
+		if (!buildRec?.buildId) {
+			gates.push(`${platform}: no recorded build — run \`amba ship --phase build\` first.`);
+			releases[platform] = {
+				platform,
+				buildId: null,
+				buildStatus: "unknown",
+				releaseState: "pending-build",
+				gate: true,
+				detail: "No recorded build."
+			};
+			continue;
+		}
+		ctx.log(`${platform}: waiting for build ${buildRec.buildId} to finish…`);
+		const buildStatus = await waitForBuild(ctx, buildRec.buildId);
+		if (TERMINAL_BAD.has(buildStatus)) {
+			failure = `${platform}: build ${buildRec.buildId} is ${buildStatus}; re-run the build phase.`;
+			releases[platform] = {
+				platform,
+				buildId: buildRec.buildId,
+				buildStatus,
+				releaseState: "blocked",
+				gate: false,
+				detail: failure
+			};
+			break;
+		}
+		if (buildStatus !== TERMINAL_OK) {
+			gates.push(`${platform}: build ${buildRec.buildId} still ${buildStatus} — re-run release once it finishes.`);
+			releases[platform] = {
+				platform,
+				buildId: buildRec.buildId,
+				buildStatus,
+				releaseState: "pending-build",
+				gate: true,
+				detail: `Build still ${buildStatus}.`
+			};
+			continue;
+		}
+		if (platform === "ios") {
+			gates.push("iOS: in App Store Connect, attach the build to a version, then \"Add for Review\" → \"Submit for Review\" (appstoreconnect.apple.com).");
+			releases[platform] = {
+				platform,
+				buildId: buildRec.buildId,
+				buildStatus,
+				releaseState: "in-testflight",
+				gate: true,
+				detail: "Uploaded to App Store Connect / TestFlight; Submit-for-Review is manual."
+			};
+			continue;
+		}
+		const priorAndroid = releases[platform];
+		if (priorAndroid && priorAndroid.buildId === buildRec.buildId && priorAndroid.releaseState === "promoted-to-production" && !ctx.force) {
+			ctx.log("android: build already promoted to production — pass --force to re-promote");
+			continue;
+		}
+		if (ctx.config.android.track === "production") {
+			if (!submitNote?.submissions?.["android"]) {
+				gates.push("android: nothing submitted to Play yet — run `amba ship --phase submit` first (your track is \"production\").");
+				releases[platform] = {
+					platform,
+					buildId: buildRec.buildId,
+					buildStatus,
+					releaseState: "blocked",
+					gate: true,
+					detail: "No submission recorded; run the submit phase before release."
+				};
+				continue;
+			}
+			releases[platform] = {
+				platform,
+				buildId: buildRec.buildId,
+				buildStatus,
+				releaseState: "promoted-to-production",
+				gate: false,
+				detail: "Submitted directly to the production track."
+			};
+			ctx.log("android: already on the production track");
+			continue;
+		}
+		ctx.log(`android: promoting build ${buildRec.buildId} to the production track…`);
+		try {
+			await ctx.exec.run(EAS, easSubmitArgs({
+				platform: "android",
+				profile,
+				buildId: buildRec.buildId,
+				track: "production"
+			}), {
+				env: easEnv(ctx),
+				timeoutMs: EXEC_TIMEOUT_MS,
+				dryRun: ctx.dryRun
+			});
+			releases[platform] = {
+				platform,
+				buildId: buildRec.buildId,
+				buildStatus,
+				releaseState: "promoted-to-production",
+				gate: false,
+				detail: "Promoted internal → production via eas submit."
+			};
+			ctx.log("android: promotion to production queued");
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			const gate = diagnoseSubmitGate("android", msg);
+			releases[platform] = {
+				platform,
+				buildId: buildRec.buildId,
+				buildStatus,
+				releaseState: "blocked",
+				gate: gate !== null,
+				detail: gate ?? msg
+			};
+			if (gate) gates.push(`android: ${gate}`);
+			else failure = `android promotion failed: ${msg}`;
+			if (failure) break;
+		}
+	}
+	const note = JSON.stringify({
+		profile,
+		releases
+	});
+	if (failure) return {
+		status: "failed",
+		detail: failure,
+		note
+	};
+	if (gates.length > 0) return {
+		status: "gate",
+		detail: `${gates.length} platform(s) need a store action`,
+		note,
+		gates
+	};
+	return {
+		status: "done",
+		detail: Object.values(releases).map((r) => `${r.platform}=${r.releaseState}`).join(" "),
+		note
+	};
+};
+const PHASE_RUNNERS = {
+	preflight: runPreflight,
+	monetization: runMonetization,
+	build: runBuild,
+	submit: runSubmit,
+	metadata: runMetadata,
+	release: runRelease
+};
+//#endregion
+//#region src/ship/orchestrator.ts
+/** Phases that ship a specific binary version (invalidated on a version bump). */
+const VERSION_SCOPED_PHASES = [
+	"build",
+	"submit",
+	"metadata",
+	"release"
+];
+/** The canonical run order, filtered to the requested subset. */
+function orderedPhases(requested) {
+	const want = new Set(requested);
+	return SHIP_PHASES.filter((p) => want.has(p));
+}
+async function defaultResolveProjectId() {
+	try {
+		const { projectId } = await loadProjectConfig();
+		return projectId;
+	} catch {
+		return null;
+	}
+}
+async function runShip(opts) {
+	const slug = opts.config.app.slug;
+	const baseDir = opts.stateBaseDir ?? process.cwd();
+	const now = opts.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+	const log = opts.log ?? (() => {});
+	const runners = opts.runners ?? PHASE_RUNNERS;
+	let state = loadShipState(slug, baseDir);
+	if (state.appVersion !== void 0 && state.appVersion !== opts.config.app.version) {
+		const phases = { ...state.phases };
+		for (const p of VERSION_SCOPED_PHASES) delete phases[p];
+		state = {
+			...state,
+			phases
+		};
+	}
+	state = {
+		...state,
+		appVersion: opts.config.app.version
+	};
+	const persist = (phase, status, note) => {
+		state = withPhase(state, phase, status, now(), note);
+		if (!opts.dryRun) saveShipState(state, baseDir);
+	};
+	const ctx = {
+		config: opts.config,
+		exec: opts.exec,
+		platforms: opts.platforms,
+		dryRun: opts.dryRun,
+		force: opts.force,
+		env: opts.env ?? process.env,
+		now,
+		log,
+		getNote: (phase) => state.phases[phase]?.note ?? null,
+		checkpoint: (phase, status, note) => persist(phase, status, note),
+		resolveProjectId: opts.resolveProjectId ?? defaultResolveProjectId,
+		adminGet: opts.adminGet ?? adminGet,
+		sleep: opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))),
+		releasePollMs: opts.releasePollMs ?? 3e4,
+		releaseMaxWaitMs: opts.releaseMaxWaitMs ?? 45 * 6e4
+	};
+	const rows = [];
+	let blocked = false;
+	let failed = false;
+	for (const phase of orderedPhases(opts.phases)) {
+		if (!opts.force && isPhaseDone(state, phase)) {
+			const rec = state.phases[phase];
+			rows.push({
+				phase,
+				status: "skipped",
+				detail: `already done ${rec?.updatedAt ?? ""}`.trim()
+			});
+			continue;
+		}
+		if ((blocked || failed) && !opts.dryRun) {
+			rows.push({
+				phase,
+				status: "pending",
+				detail: "not reached (earlier phase needs action)"
+			});
+			continue;
+		}
+		const outcome = await runners[phase](ctx);
+		if (opts.dryRun) {
+			const status = outcome.status === "done" ? "dry-run" : outcome.status;
+			rows.push({
+				phase,
+				status,
+				detail: outcome.detail,
+				...outcome.gates ? { gates: outcome.gates } : {}
+			});
+			if (outcome.status === "failed") failed = true;
+			continue;
+		}
+		switch (outcome.status) {
+			case "done":
+				persist(phase, "done", outcome.note);
+				rows.push({
+					phase,
+					status: "done",
+					detail: outcome.detail,
+					...outcome.gates ? { gates: outcome.gates } : {}
+				});
+				break;
+			case "skipped":
+				rows.push({
+					phase,
+					status: "skipped",
+					detail: outcome.detail
+				});
+				break;
+			case "gate":
+				persist(phase, "gate", outcome.note);
+				rows.push({
+					phase,
+					status: "gate",
+					detail: outcome.detail,
+					...outcome.gates ? { gates: outcome.gates } : {}
+				});
+				blocked = true;
+				break;
+			case "failed":
+				persist(phase, "failed", outcome.note);
+				rows.push({
+					phase,
+					status: "failed",
+					detail: outcome.detail
+				});
+				failed = true;
+				break;
+		}
+	}
+	return {
+		rows,
+		blocked,
+		failed
+	};
+}
+//#endregion
+//#region src/commands/ship.ts
+/**
+* `amba ship` — take this Expo app from code-complete to live on the App Store
+* and Google Play, and `amba ship init` to scaffold its config.
+*
+*   amba ship                 run the full pipeline (preflight → monetization →
+*                             build → submit → metadata → release)
+*   amba ship --phase build   run a single phase
+*   amba ship --dry-run       print the plan; touch nothing
+*   amba ship init            scaffold amba.ship.json
+*
+* Build/submit/release shell out to `eas` (the Expo toolchain owns the build,
+* the signing credentials, and the store submit). Monetization delegates to the
+* Amba control plane (`amba monetization`). Steps no API can do — create the
+* store app record, the Apple Paid-Apps agreement, screenshots, store review —
+* are detected and surfaced as manual gates with the exact console action.
+*/
+/** Read + parse + validate a ship config file. Throws with every error joined. */
+async function loadShipConfig(file) {
+	const path = resolve(file);
+	let raw;
+	try {
+		raw = await readFile(path, "utf-8");
+	} catch {
+		throw new Error(`Config not found: ${file}. Run ${pc.cyan("amba ship init")} to scaffold one.`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`Failed to parse ${file} as JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	const result = validateShipConfig(parsed);
+	if (!result.ok) throw new Error(`Invalid ${file}:\n${result.errors.map((e) => `  • ${e}`).join("\n")}`);
+	return result.config;
+}
+function parseShipPhase(raw) {
+	if (raw === void 0 || raw === "all") return "all";
+	if (SHIP_PHASES.includes(raw)) return raw;
+	throw new Error(`Unknown --phase "${raw}". Expected one of: ${SHIP_PHASES.join(", ")}, all.`);
+}
+/** Resolve the platforms to act on: --platform override, else the config's. */
+function resolvePlatforms(raw, configPlatforms) {
+	if (raw === void 0 || raw === "all") return configPlatforms;
+	if (!SHIP_PLATFORMS.includes(raw)) throw new Error(`Unknown --platform "${raw}". Expected one of: ${SHIP_PLATFORMS.join(", ")}, all.`);
+	const platform = raw;
+	if (!configPlatforms.includes(platform)) throw new Error(`Platform "${platform}" is not in build.platforms (${configPlatforms.join(", ")}).`);
+	return [platform];
+}
+const STATUS_BADGE = {
+	done: pc.green("done"),
+	"dry-run": pc.cyan("dry-run"),
+	skipped: pc.dim("skipped"),
+	gate: pc.yellow("GATE"),
+	failed: pc.red("failed"),
+	pending: pc.dim("pending")
+};
+function renderTable(rows) {
+	console.log();
+	for (const row of rows) console.log(`  ${row.phase.padEnd(13)} ${STATUS_BADGE[row.status].padEnd(18)} ${pc.dim(row.detail)}`);
+	console.log();
+}
+function renderGates(rows) {
+	const gateRows = rows.filter((r) => r.gates && r.gates.length > 0);
+	if (gateRows.length === 0) return;
+	console.log(pc.yellow("  Manual gates — steps no API can do (with exact locations):"));
+	for (const row of gateRows) for (const gate of row.gates ?? []) console.log(`    ${pc.bold("□")} ${pc.dim(`[${row.phase}]`)} ${gate}`);
+	console.log();
+}
+async function shipCommand(options = {}, deps = {}) {
+	const config = await loadShipConfig(options.config ?? "amba.ship.json");
+	const phase = parseShipPhase(options.phase);
+	const platforms = resolvePlatforms(options.platform, config.build.platforms);
+	const dryRun = options.dryRun === true;
+	const phases = phase === "all" ? [...SHIP_PHASES] : [phase];
+	console.log();
+	console.log(pc.bold(`  amba ship ${pc.cyan(config.app.name)} ${pc.dim(`v${config.app.version}`)}`));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log(pc.dim(`  phase=${phase} · platforms=${platforms.join(",")}${dryRun ? " · DRY-RUN" : ""}${options.force ? " · FORCE" : ""}`));
+	const result = await runShip({
+		config,
+		phases,
+		platforms,
+		exec: deps.exec ?? createNodeExecutor(dryRun),
+		dryRun,
+		force: options.force === true,
+		log: (line) => console.log(pc.dim(`    ${line}`)),
+		...deps.stateBaseDir !== void 0 ? { stateBaseDir: deps.stateBaseDir } : {},
+		...deps.resolveProjectId ? { resolveProjectId: deps.resolveProjectId } : {},
+		...deps.adminGet ? { adminGet: deps.adminGet } : {},
+		...deps.now ? { now: deps.now } : {},
+		...deps.sleep ? { sleep: deps.sleep } : {},
+		...deps.releasePollMs !== void 0 ? { releasePollMs: deps.releasePollMs } : {},
+		...deps.releaseMaxWaitMs !== void 0 ? { releaseMaxWaitMs: deps.releaseMaxWaitMs } : {}
+	});
+	renderTable(result.rows);
+	renderGates(result.rows);
+	if (result.failed) {
+		const bad = result.rows.find((r) => r.status === "failed");
+		throw new Error(`Launch failed${bad ? ` at ${bad.phase}` : ""}: ${bad?.detail ?? "see above"}`);
+	}
+	if (dryRun) {
+		console.log(pc.green("  ✓") + " Dry-run complete — nothing was changed.");
+		console.log();
+		return;
+	}
+	if (result.blocked) {
+		const gates = result.rows.filter((r) => r.status === "gate").length;
+		console.log(pc.yellow("  ⏸ Launch paused") + pc.dim(` — ${gates} gate(s) need a manual store action (above). Clear them, then re-run `) + pc.cyan("amba ship") + pc.dim("."));
+		console.log();
+		return;
+	}
+	console.log(pc.green("  ✓") + " Launch run complete.");
+	console.log();
+}
+async function shipInitCommand(options = {}) {
+	const file = options.config ?? "amba.ship.json";
+	const path = resolve(file);
+	if (!options.force) {
+		if (await access(path).then(() => true, () => false)) throw new Error(`${file} already exists. Pass ${pc.cyan("--force")} to overwrite it.`);
+	}
+	const template = shipConfigTemplate((options.slug ?? "my-app").toLowerCase());
+	await writeFile(path, JSON.stringify(template, null, 2) + "\n", "utf-8");
+	console.log();
+	console.log(pc.green("  ✓") + ` Wrote ${pc.cyan(file)}.`);
+	console.log(pc.dim("    Edit the app IDs, then ") + pc.cyan("amba ship --phase preflight") + pc.dim(" to check your setup."));
+	console.log();
+}
+//#endregion
 //#region src/_internal/codegen.ts
 /** Read every collection schema and emit a single `.amba/types.d.ts` body. */
 async function generateCollectionTypes(input) {
@@ -8210,7 +9530,7 @@ async function diffConfigCommand(file = DEFAULT_BUNDLE_FILE, options = {}) {
 //#endregion
 //#region src/index.ts
 const program = new Command();
-program.name("amba").description("amba — agent-native backend-as-a-service for mobile apps.").version("4.0.4");
+program.name("amba").description("amba — agent-native backend-as-a-service for mobile apps.").version("4.1.1");
 program.option("--token <pat>", "Use a Personal Access Token for headless / CI / agent use (overrides ~/.amba/credentials.json + AMBA_PAT env)");
 program.hook("preAction", (thisCommand) => {
 	setBearerOverride(resolveTokenSource({
@@ -8370,12 +9690,13 @@ functions.command("dev <file>").description("Run a local dev server for your fun
 		noWatch: opts.watch === false
 	}));
 });
-functions.command("logs <name>").description("Stream log events for a deployed function").option("--since <iso>", "Start of the time range (default: 1 hour ago)").option("--until <iso>", "End of the time range (default: now). Ignored on --tail.").option("--limit <n>", "Max events per fetch (default 100, max 1000)", (v) => parseInt(v, 10)).option("--request-id <id>", "Only show events whose logs mention this request id (e.g. r_...). Works with --tail.").option("--tail", "Follow new events; polls every 3s. Ctrl+C to stop.").option("--follow", "Alias for --tail (kept for backwards compatibility with v1 log commands).").option("--json", "NDJSON output to stdout (one event per line)").action(async (name, opts) => {
+functions.command("logs <name>").description("Stream log events for a deployed function").option("--since <iso>", "Start of the time range (default: 1 hour ago)").option("--until <iso>", "End of the time range (default: now). Ignored on --tail.").option("--limit <n>", "Max events per fetch (default 100, max 1000)", (v) => parseInt(v, 10)).option("--request-id <id>", "Only show events whose logs mention this request id (e.g. r_...). Works with --tail.").option("--since-request-id <id>", "Start the range at the oldest event mentioning this request id (e.g. r_...) — \"everything from this request onward\". Searches the last 24h (or --since/--until when given). Works with --tail.").option("--tail", "Follow new events; polls every 3s. Ctrl+C to stop.").option("--follow", "Alias for --tail (kept for backwards compatibility with v1 log commands).").option("--json", "NDJSON output to stdout (one event per line)").action(async (name, opts) => {
 	await runAction(() => functionsLogsCommand(name, {
 		since: opts.since,
 		until: opts.until,
 		limit: opts.limit,
 		requestId: opts.requestId,
+		sinceRequestId: opts.sinceRequestId,
 		tail: opts.tail || opts.follow,
 		json: opts.json
 	}));
@@ -8492,8 +9813,23 @@ monetization.command("adopt").description("Record the live config as the managed
 monetization.command("apply").description("Apply the declared config to the provider. Additive ops (create entitlements/offerings/packages/paywall-drafts + attach products) apply automatically; destructive ops (detach/archive/remove) need --confirm.").option("--confirm", "Confirm and execute the gated destructive ops (detach/archive/remove). Without it they are reported but not run.").option("--allow-detach-live", "Accept detaching a product a live customer currently resolves (otherwise refused).").option("--reconcile <mode>", "Out-of-band drift mode: 'amba' (default) or 'adopt'.").action(async (opts) => {
 	await runAction(() => monetizationApplyCommand(opts));
 });
+program.command("ship").description("Take this Expo app from code-complete to live on the App Store + Google Play (preflight → monetization → build → submit → metadata → release).").option("--phase <phase>", `Run a single phase (${SHIP_PHASES.join(" | ")}) instead of the whole pipeline.`).option("--platform <platform>", "Limit to 'ios' | 'android' (default: build.platforms from the config).").option("--dry-run", "Print the plan; make no cloud changes and no state writes.").option("--force", "Re-run phases already recorded as done.").option("--config <path>", `Config file (default: ${DEFAULT_SHIP_CONFIG_FILE}).`).action(async (opts) => {
+	await runAction(() => shipCommand({
+		phase: opts.phase,
+		platform: opts.platform,
+		dryRun: opts.dryRun,
+		force: opts.force,
+		config: opts.config
+	}));
+}).command("init").description(`Scaffold a ${DEFAULT_SHIP_CONFIG_FILE} for this app`).option("--config <path>", `Output file (default: ${DEFAULT_SHIP_CONFIG_FILE})`).option("--slug <slug>", "App slug used to scope the launch state (default: my-app)").option("--force", "Overwrite an existing config file").action(async (opts) => {
+	await runAction(() => shipInitCommand({
+		config: opts.config,
+		slug: opts.slug,
+		force: opts.force
+	}));
+});
 const collections = program.command("collections").description("Customer collections (schema-first Postgres in each tenant database)");
-collections.command("create <name>").description("Create a collection with the given fields").option("--field <spec>", "Field spec: name:type[:nullable] (e.g. user_id:uuid, parsed:jsonb:nullable). Repeatable.", (val, prev) => [...prev ?? [], val], []).option("--index <spec>", "Index spec: \"col1 [asc|desc], col2 [asc|desc]\". Repeatable.", (val, prev) => [...prev ?? [], val], []).action(async (name, opts) => {
+collections.command("create <name>").description("Create a collection with the given fields").option("--field <spec>", "Field spec: name:type[:nullable] (e.g. user_id:uuid, tags:text[], parsed:jsonb:nullable, embedding:vector:1536). Repeatable.", (val, prev) => [...prev ?? [], val], []).option("--index <spec>", "Index spec: \"col1 [asc|desc], col2 [asc|desc]\". Repeatable.", (val, prev) => [...prev ?? [], val], []).action(async (name, opts) => {
 	await runAction(() => collectionsCreateCommand(name, opts));
 });
 collections.command("alter <name>").description("Add columns / indexes or drop columns on an existing collection").option("--add-field <spec>", "Column to add (name:type[:nullable]). Repeatable.", (val, prev) => [...prev ?? [], val], []).option("--add-index <spec>", "Index to add (\"col [asc|desc], …\"). Repeatable.", (val, prev) => [...prev ?? [], val], []).option("--drop-field <name>", "Column to drop (DESTRUCTIVE — requires --confirm <name>). Repeatable.", (val, prev) => [...prev ?? [], val], []).option("--confirm <name>", "Confirm a destructive --drop-field <name>. Repeatable.", (val, prev) => [...prev ?? [], val], []).action(async (name, opts) => {
@@ -8509,7 +9845,7 @@ program.command("types").description("TypeScript codegen for collections").comma
 	await runAction(() => typesGenerateCommand(opts));
 });
 const sites = program.command("sites").description("Static site hosting");
-sites.command("deploy <dir>").description("Upload a built static-site directory to Pages-for-Platforms").option("--name <name>", "Site name (default: basename of dir, slug-cleaned)").option("--dry-run", "Scan + size-check without uploading").action(async (dir, opts) => {
+sites.command("deploy <dir>").description("Upload a built static-site directory to Amba site hosting").option("--name <name>", "Site name (default: basename of dir, slug-cleaned)").option("--dry-run", "Scan + size-check without uploading").action(async (dir, opts) => {
 	await runAction(() => sitesDeployCommand(dir, opts));
 });
 sites.command("list").description("List sites for the current project").action(async () => {