@layers/amba 4.0.2 → 4.0.4

package/dist/index.js

@@ -8,11 +8,460 @@ import { createServer } from "node:http";
 import open from "open";
 import { createHash, randomBytes } from "node:crypto";
 import { createInterface } from "node:readline";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { createWriteStream, watch } from "node:fs";
 import { spawn } from "node:child_process";
 import { build } from "esbuild";
-//#region ../shared/dist/index.js
+new Map([
+	{
+		type: "user.created",
+		plane: "app",
+		description: "An app user (end user) was created in the project.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			external_id: "auth0|abc",
+			created_at: "2026-06-03T00:00:00Z"
+		},
+		status: "live"
+	},
+	{
+		type: "user.updated",
+		plane: "app",
+		description: "An app user's profile or attributes changed.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			changed: ["display_name"]
+		},
+		status: "live"
+	},
+	{
+		type: "user.deleted",
+		plane: "app",
+		description: "An app user was deleted.",
+		payloadExample: { app_user_id: "usr_123" },
+		status: "live"
+	},
+	{
+		type: "user.reset",
+		plane: "app",
+		description: "An app user's gamification, economy, engagement and participation state was reset to zero (the user row itself was kept).",
+		payloadExample: {
+			app_user_id: "usr_123",
+			cleared: {
+				user_xp: 1,
+				xp_ledger: 12
+			}
+		},
+		status: "live"
+	},
+	{
+		type: "engagement.push.delivered",
+		plane: "app",
+		description: "A push notification was delivered to a device.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			campaign_id: "cmp_1",
+			delivered_at: "2026-06-03T00:00:00Z"
+		},
+		status: "live"
+	},
+	{
+		type: "engagement.push.failed",
+		plane: "app",
+		description: "A push notification failed to deliver.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			campaign_id: "cmp_1",
+			reason: "unregistered_token"
+		},
+		status: "live"
+	},
+	{
+		type: "email.sent",
+		plane: "app",
+		description: "A transactional email was accepted by the provider for delivery.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			template: "welcome",
+			to: "a@b.com"
+		},
+		status: "live"
+	},
+	{
+		type: "email.failed",
+		plane: "app",
+		description: "A transactional email failed to send.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			template: "welcome",
+			reason: "bounce"
+		},
+		status: "live"
+	},
+	{
+		type: "email.suppressed",
+		plane: "app",
+		description: "An email was suppressed (recipient on the suppression list).",
+		payloadExample: {
+			app_user_id: "usr_123",
+			to: "a@b.com",
+			reason: "unsubscribed"
+		},
+		status: "live"
+	},
+	{
+		type: "gamification.xp.granted",
+		plane: "app",
+		description: "XP was granted to a user.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			amount: 50,
+			total_xp: 1250,
+			rule: "mission_completed",
+			transaction_id: "xpl_abc"
+		},
+		status: "live"
+	},
+	{
+		type: "gamification.level.up",
+		plane: "app",
+		description: "A user crossed an XP threshold into a new level.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			level: 7,
+			previous_level: 6
+		},
+		status: "live"
+	},
+	{
+		type: "gamification.achievement.unlocked",
+		plane: "app",
+		description: "A user unlocked an achievement.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			achievement_id: "first_win",
+			unlocked_at: "2026-06-03T00:00:00Z"
+		},
+		status: "live"
+	},
+	{
+		type: "gamification.streak.advanced",
+		plane: "app",
+		description: "A user's streak advanced (a qualifying action extended it).",
+		payloadExample: {
+			app_user_id: "usr_123",
+			streak_id: "daily",
+			count: 12
+		},
+		status: "live"
+	},
+	{
+		type: "gamification.streak.broken",
+		plane: "app",
+		description: "A user's streak reset to zero after a missed window.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			streak_id: "daily",
+			previous_count: 12
+		},
+		status: "live"
+	},
+	{
+		type: "gamification.challenge.completed",
+		plane: "app",
+		description: "A user completed a challenge.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			challenge_id: "ch_1"
+		},
+		status: "live"
+	},
+	{
+		type: "economy.currency.granted",
+		plane: "app",
+		description: "Currency was granted to a user.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			currency: "coins",
+			amount: 100,
+			balance: 350,
+			transaction_id: "ctx_abc"
+		},
+		status: "live"
+	},
+	{
+		type: "economy.currency.spent",
+		plane: "app",
+		description: "A user spent currency.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			currency: "coins",
+			amount: 100,
+			balance: 250,
+			transaction_id: "ctx_def"
+		},
+		status: "live"
+	},
+	{
+		type: "economy.catalog.purchased",
+		plane: "app",
+		description: "A user purchased a catalog item.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			item_id: "sword",
+			price: 100,
+			currency: "coins"
+		},
+		status: "live"
+	},
+	{
+		type: "economy.inventory.granted",
+		plane: "app",
+		description: "An item was granted into a user inventory.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			item_id: "sword",
+			quantity: 1
+		},
+		status: "live"
+	},
+	{
+		type: "subscription.started",
+		plane: "app",
+		description: "A user gained an active subscription / entitlement.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			entitlement_id: "pro",
+			product_id: "pro_yearly",
+			store: "app_store",
+			period_type: "normal"
+		},
+		status: "live"
+	},
+	{
+		type: "subscription.renewed",
+		plane: "app",
+		description: "An active subscription renewed for another billing period.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			entitlement_id: "pro",
+			product_id: "pro_yearly",
+			store: "app_store"
+		},
+		status: "live"
+	},
+	{
+		type: "subscription.expired",
+		plane: "app",
+		description: "A subscription lapsed / was revoked and access ended.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			entitlement_id: "pro",
+			product_id: "pro_yearly"
+		},
+		status: "live"
+	},
+	{
+		type: "entitlement.granted",
+		plane: "app",
+		description: "An entitlement became active for a user (any source).",
+		payloadExample: {
+			app_user_id: "usr_123",
+			entitlement_id: "pro",
+			product_id: "pro_yearly",
+			source: "webhook"
+		},
+		status: "live"
+	},
+	{
+		type: "entitlement.revoked",
+		plane: "app",
+		description: "An entitlement became inactive for a user (any source).",
+		payloadExample: {
+			app_user_id: "usr_123",
+			entitlement_id: "pro",
+			source: "manual"
+		},
+		status: "live"
+	},
+	{
+		type: "social.friendship.created",
+		plane: "app",
+		description: "A friendship was established between two users.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			friend_id: "usr_456"
+		},
+		status: "live"
+	},
+	{
+		type: "social.message.sent",
+		plane: "app",
+		description: "A message was sent in a conversation.",
+		payloadExample: {
+			conversation_id: "cnv_1",
+			sender_id: "usr_123"
+		},
+		status: "live"
+	},
+	{
+		type: "social.review.created",
+		plane: "app",
+		description: "A review was submitted.",
+		payloadExample: {
+			app_user_id: "usr_123",
+			rating: 5,
+			target_id: "item_1"
+		},
+		status: "live"
+	},
+	{
+		type: "content.published",
+		plane: "app",
+		description: "A content item was published / went live.",
+		payloadExample: {
+			item_id: "post_1",
+			library: "news"
+		},
+		status: "live"
+	},
+	{
+		type: "moderation.flagged",
+		plane: "app",
+		description: "User content entered the moderation queue.",
+		payloadExample: {
+			queue_id: "mq_1",
+			content_type: "message",
+			reason: "auto_flag"
+		},
+		status: "live"
+	},
+	{
+		type: "moderation.rejected",
+		plane: "app",
+		description: "Moderated content was rejected.",
+		payloadExample: {
+			queue_id: "mq_1",
+			moderator: "auto"
+		},
+		status: "live"
+	},
+	{
+		type: "project.provisioning.started",
+		plane: "control",
+		description: "Project provisioning began (tenant DB + keys being created).",
+		payloadExample: { project_id: "prj_1" },
+		status: "live"
+	},
+	{
+		type: "project.provisioned",
+		plane: "control",
+		description: "The project finished provisioning and is ready to use.",
+		payloadExample: {
+			project_id: "prj_1",
+			provisioned_at: "2026-06-03T00:00:00Z"
+		},
+		status: "live"
+	},
+	{
+		type: "project.provisioning.failed",
+		plane: "control",
+		description: "Project provisioning failed and was compensated.",
+		payloadExample: {
+			project_id: "prj_1",
+			reason: "neon_quota"
+		},
+		status: "live"
+	},
+	{
+		type: "site.deploy.completed",
+		plane: "control",
+		description: "A static site deploy completed and is serving.",
+		payloadExample: {
+			site: "marketing",
+			deployment_id: "dep_1",
+			url: "https://x.app.amba.host",
+			file_count: 4,
+			serving_configured: true
+		},
+		status: "live"
+	},
+	{
+		type: "site.deploy.failed",
+		plane: "control",
+		description: "A static site deploy failed.",
+		payloadExample: {
+			project_id: "prj_1",
+			site: "marketing",
+			reason: "storage_write_failed"
+		},
+		status: "live"
+	},
+	{
+		type: "domain.registered",
+		plane: "control",
+		description: "A domain was registered through Amba.",
+		payloadExample: {
+			domain: "myapp.com",
+			site: "marketing"
+		},
+		status: "live"
+	},
+	{
+		type: "domain.cert.issued",
+		plane: "control",
+		description: "The TLS certificate for an attached domain became active.",
+		payloadExample: {
+			project_id: "prj_1",
+			domain: "app.myapp.com"
+		},
+		status: "live"
+	},
+	{
+		type: "domain.connected",
+		plane: "control",
+		description: "A domain is fully connected to a site and serving.",
+		payloadExample: {
+			project_id: "prj_1",
+			domain: "myapp.com",
+			site: "marketing"
+		},
+		status: "live"
+	},
+	{
+		type: "billing.subscription.updated",
+		plane: "control",
+		description: "The project's subscription state changed.",
+		payloadExample: {
+			project_id: "prj_1",
+			tier: "pro",
+			status: "active"
+		},
+		status: "live"
+	},
+	{
+		type: "billing.invoice.paid",
+		plane: "control",
+		description: "An invoice was paid.",
+		payloadExample: {
+			project_id: "prj_1",
+			invoice_id: "in_1",
+			amount_usd: 49
+		},
+		status: "live"
+	},
+	{
+		type: "billing.payment_failed",
+		plane: "control",
+		description: "A payment attempt failed.",
+		payloadExample: {
+			project_id: "prj_1",
+			invoice_id: "in_1",
+			reason: "card_declined"
+		},
+		status: "live"
+	}
+].map((e) => [e.type, e]));
 /**
 * Shared email-shape validation.
 *
@@ -377,7 +826,7 @@ async function request(method, path, body) {
 		try {
 			const errorBody = await res.json();
 			if (errorBody.error?.message) {
-				errorMessage = errorBody.error.message;
+				errorMessage = `${res.status} — ${errorBody.error.message}`;
 				errorCode = errorBody.error.code;
 			}
 		} catch {}
@@ -498,7 +947,7 @@ async function streamUsersExport(projectId, query = {}) {
 		try {
 			const errorBody = await res.json();
 			if (errorBody.error?.message) {
-				errorMessage = errorBody.error.message;
+				errorMessage = `${res.status} — ${errorBody.error.message}`;
 				errorCode = errorBody.error.code;
 			}
 		} catch {}
@@ -529,7 +978,8 @@ async function deployFunctionViaApi(projectId, input) {
 	fd.set("script", new Blob([input.bundleCode], { type: "application/javascript+module" }), `${input.name}.js`);
 	const metadata = {
 		name: input.name,
-		...input.rate_limit !== void 0 ? { rate_limit: input.rate_limit } : {}
+		...input.rate_limit !== void 0 ? { rate_limit: input.rate_limit } : {},
+		...input.public === true ? { public: true } : {}
 	};
 	fd.set("metadata", new Blob([JSON.stringify(metadata)], { type: "application/json" }), "metadata.json");
 	return request("POST", `/projects/${projectId}/functions/deploy`, fd);
@@ -545,6 +995,7 @@ async function getFunctionLogs(projectId, functionName, options = {}) {
 	if (options.since) params.set("since", options.since);
 	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);
 	const qs = params.toString();
 	return request("GET", `/projects/${projectId}/functions/${functionName}/logs${qs ? `?${qs}` : ""}`);
 }
@@ -560,12 +1011,12 @@ async function deleteQueueBinding(projectId, queueName) {
 async function setSecretViaApi(projectId, input) {
 	return request("POST", `/projects/${projectId}/secrets`, input);
 }
-async function listSecretsViaApi(projectId) {
-	return request("GET", `/projects/${projectId}/secrets`);
+async function listSecretsViaApi(projectId, options = {}) {
+	return request("GET", `/projects/${projectId}/secrets${options.function ? `?${new URLSearchParams({ function: options.function }).toString()}` : ""}`);
 }
-async function deleteSecretViaApi(projectId, name, options) {
-	const qs = new URLSearchParams({ function: options.function });
-	return request("DELETE", `/projects/${projectId}/secrets/${encodeURIComponent(name)}?${qs.toString()}`);
+async function deleteSecretViaApi(projectId, name, options = {}) {
+	const qs = options.function ? `?${new URLSearchParams({ function: options.function }).toString()}` : "";
+	return request("DELETE", `/projects/${projectId}/secrets/${encodeURIComponent(name)}${qs}`);
 }
 async function createCollection(projectId, input) {
 	return request("POST", `/projects/${projectId}/collections`, input);
@@ -645,6 +1096,20 @@ async function rollbackSiteViaApi(projectId, siteName, deploymentId) {
 async function deleteSiteViaApi(projectId, siteName, options) {
 	return request("DELETE", `/projects/${projectId}/sites/${encodeURIComponent(siteName)}?confirm=${encodeURIComponent(options.confirm)}`);
 }
+async function searchDomainsViaApi(projectId, query, limit) {
+	const params = new URLSearchParams({ q: query });
+	if (limit !== void 0) params.set("limit", String(limit));
+	return request("GET", `/projects/${projectId}/domains/search?${params.toString()}`);
+}
+async function checkDomainsViaApi(projectId, domains) {
+	return request("POST", `/projects/${projectId}/domains/check`, { domains });
+}
+async function purchaseDomainViaApi(projectId, body) {
+	return request("POST", `/projects/${projectId}/domains/purchase`, body);
+}
+async function listPurchasedDomainsViaApi(projectId) {
+	return request("GET", `/projects/${projectId}/domains`);
+}
 /**
 * Delete a function entirely. Cascade: removes the deployed script
 * (backend 404 treated as success), then marks every historical
@@ -658,6 +1123,17 @@ async function deleteFunctionViaApi(projectId, functionName, options) {
 async function listSiteDomains(projectId, siteName) {
 	return request("GET", `/projects/${projectId}/sites/${encodeURIComponent(siteName)}/domains`);
 }
+/** GET the current project's declarative configuration bundle. */
+async function exportPromotionBundle(projectId) {
+	return request("GET", `/projects/${projectId}/promotion/export`);
+}
+/** POST a declarative bundle to import it into the project. */
+async function importPromotionBundle(projectId, bundle, mode) {
+	return request("POST", `/projects/${projectId}/promotion/import`, {
+		bundle,
+		mode
+	});
+}
 async function validateApiKey(apiKey) {
 	const res = await fetch(`${getApiRoot()}/v1/auth/validate`, {
 		method: "POST",
@@ -2135,6 +2611,14 @@ Tell the user where their credentials live:
 
 **Already have a PAT?** Skip the signup. Call \`amba_developer_me({})\` to verify the Bearer; if it succeeds, either reuse the most recent project (\`amba_projects_list\`) or call \`amba_projects_create({ name: "<app-name>", platform: "all" })\` and then \`amba_api_keys_create\` twice to mint client + server keys for \`environment: "development"\`.
 
+**Can't reach \`amba_developer_signup\` — it's not in your tool list, or your harness blocks the call?** Do NOT try to work around it by adding the MCP server yourself, running an installer, or editing your own settings/permissions — refusing to self-modify or widen your own permissions is the correct call, and you should not circumvent it. Instead, hand the developer **one** command to run in **their own** terminal (which is not subject to your sandbox):
+
+\`\`\`bash
+npx @layers/amba init
+\`\`\`
+
+It creates the account with no browser and writes \`AMBA_PROJECT_ID\` + \`AMBA_CLIENT_KEY\` to \`.env.local\` (and wires this MCP server up for your next session). Ask them to run it, tell you when it's done, then resume from this Step 0 by reading \`.env.local\`. Asking the developer to paste an \`amb_ck_…\` client key is the last-resort lite path — it's enough to wire \`Amba.configure()\` + runtime calls and verify events land, but a client key alone can't do admin provisioning (creating achievements, collections, segments, etc.), which needs the PAT or server key.
+
 ## Step 1 — Classify the app
 
 Look at what the user told you and at any files they shared. You're trying to pick one of ten presets in 30 seconds, not write a treatise. Inputs:
@@ -2256,7 +2740,7 @@ SKIPPED (low signal — re-run with /amba <feature> if you want them)
 NEEDS YOUR INPUT
   - Apple Sign In: add the "Sign in with Apple" capability in Xcode > Signing & Capabilities.
   - Google Sign In: paste your Google OAuth client ID into amba_projects_update({ google_oauth_client_id: "..." }).
-  - APNs / FCM: upload credentials in app.amba.dev before push delivers.
+  - APNs / FCM: configure credentials with amba_integrations_configure (paste the .p8 / service-account JSON inline) before push delivers.
 
 NEXT STEPS
   - Paste AMBA_CLIENT_KEY into your build env (already shown above)
@@ -2318,7 +2802,7 @@ All SDKs expose the same surface: \`Amba.configure({ projectId, apiKey })\`, the
 - **challenges** — time-bounded goals. Define with \`amba_challenges_create\`; progress via SDK.
 
 ### Economy
-- **currencies** — virtual currencies (coins, gems). Define with \`amba_currencies_create\`; grant via \`amba_currencies_grant\` or event rules via \`amba_currency_grant_rules_create\`.
+- **currencies** — virtual currencies (coins, gems). Define with \`amba_currencies_create\`; grant via \`amba_currencies_grant\` or event rules via \`amba_currency_grant_rules_create\`; debit via \`amba_currencies_spend\` (atomic, rejects on insufficient funds).
 - **catalog + stores** — purchasable items + storefronts. Chain: \`amba_catalog_items_create\` → \`amba_catalog_items_set_price\` → \`amba_stores_create\` → \`amba_stores_add_listing\`. (Define currency first.)
 - **inventory** — items users own. Read via SDK \`Amba.inventory.*\`; grant with \`amba_inventory_grant_item\`.
 
@@ -2341,7 +2825,7 @@ All SDKs expose the same surface: \`Amba.configure({ projectId, apiKey })\`, the
 - **sites** — static site hosting at \`*.app.amba.host\`. Deploy with \`amba_sites_deploy\`.
 - **media** — file storage + CDN. Upload via \`amba_media_upload\`.
 - **secrets** — env vars for functions. Set via \`amba_secrets_set\`.
-- **configs** — remote config flags. Define with \`amba_configs_create\`.
+- **configs** — remote config flags. Define with \`amba_remote_configs_create\`.
 - **integrations** — third-party webhooks (RevenueCat, Superwall, AppsFlyer, etc.). Configure with \`amba_integrations_configure\`.
 - **ai_prompts** — versioned LLM prompts callable from SDK. Define with \`amba_ai_prompts_create\`; call via \`amba_ai_prompts_invoke\`.
 `;
@@ -4055,7 +4539,7 @@ async function configSetCommand(key, rawValue) {
 }
 //#endregion
 //#region src/commands/projects.ts
-function confirm(question) {
+function confirm$1(question) {
 	const rl = createInterface({
 		input: process.stdin,
 		output: process.stdout
@@ -4067,7 +4551,7 @@ function confirm(question) {
 		});
 	});
 }
-function handleError$1(err) {
+function handleError$2(err) {
 	if (err instanceof ApiClientError) if (err.statusCode === 401 || err.statusCode === 403) console.log(pc.red("  ✗") + " Not authenticated — run `amba login` first.");
 	else console.log(pc.red("  ✗") + ` ${err.message}`);
 	else if (err instanceof Error) console.log(pc.red("  ✗") + ` ${err.message}`);
@@ -4117,7 +4601,7 @@ async function projectsListCommand() {
 		console.log(pc.dim(`  ${projects.length} project${projects.length === 1 ? "" : "s"}`));
 		console.log();
 	} catch (err) {
-		handleError$1(err);
+		handleError$2(err);
 	}
 }
 async function projectsCreateCommand(input) {
@@ -4163,7 +4647,7 @@ async function projectsCreateCommand(input) {
 		console.log(pc.dim("  Next: ") + pc.cyan(`amba projects show ${id}`));
 		console.log();
 	} catch (err) {
-		handleError$1(err);
+		handleError$2(err);
 	}
 }
 async function projectsUpdateCommand(projectId, input) {
@@ -4189,7 +4673,7 @@ async function projectsUpdateCommand(projectId, input) {
 			console.log();
 			process.exit(1);
 		}
-		handleError$1(err);
+		handleError$2(err);
 	}
 }
 async function projectsShowCommand(projectId) {
@@ -4207,7 +4691,7 @@ async function projectsShowCommand(projectId) {
 			console.log();
 			process.exit(1);
 		}
-		handleError$1(err);
+		handleError$2(err);
 	}
 }
 async function projectsDeleteCommand(projectId, opts = {}) {
@@ -4216,7 +4700,7 @@ async function projectsDeleteCommand(projectId, opts = {}) {
 	console.log(pc.dim("  ─────────────────────────────────"));
 	console.log();
 	if (!opts.yes) {
-		if (!await confirm(pc.yellow(`  Delete project ${projectId}? This is irreversible. (y/N) `))) {
+		if (!await confirm$1(pc.yellow(`  Delete project ${projectId}? This is irreversible. (y/N) `))) {
 			console.log(pc.dim("  Aborted."));
 			console.log();
 			return;
@@ -4232,7 +4716,7 @@ async function projectsDeleteCommand(projectId, opts = {}) {
 			console.log();
 			process.exit(1);
 		}
-		handleError$1(err);
+		handleError$2(err);
 	}
 }
 //#endregion
@@ -4975,6 +5459,47 @@ function parseEnv(content) {
 * empty; customer code is expected to be self-contained.
 */
 /**
+* Conventional entry-point filenames probed (in order) when
+* `amba functions deploy <dir>` is pointed at a directory rather than a
+* single file. Mirrors the Node / bundler convention (`index.*`) so a
+* developer can `amba functions deploy ./my-fn` with an `index.ts` inside.
+*/
+const FUNCTION_ENTRY_CANDIDATES = [
+	"index.ts",
+	"index.js",
+	"index.mjs"
+];
+/**
+* Resolve the bundler entry point from a deploy target that may be either a
+* single file OR a directory.
+*
+*   - File  → returned as-is (single-file back-compat path).
+*   - Dir   → resolved by convention to `index.{ts,js,mjs}`, or to an
+*             explicit `entry` (relative to the directory) when provided.
+*
+* Throws an actionable error when the target doesn't exist, or when a
+* directory has no resolvable entry point (and no `--entry` was passed).
+*/
+async function resolveFunctionEntry(target, explicitEntry) {
+	const st = await stat(target).catch(() => null);
+	if (!st) throw new Error(`Deploy target not found: ${target}`);
+	if (st.isFile()) {
+		if (explicitEntry) throw new Error(`--entry is only valid when deploying a directory; ${target} is a file. Drop --entry, or point the deploy at the directory containing ${explicitEntry}.`);
+		return target;
+	}
+	if (!st.isDirectory()) throw new Error(`Deploy target is neither a file nor a directory: ${target}`);
+	if (explicitEntry) {
+		const candidate = join(target, explicitEntry);
+		if (!(await stat(candidate).catch(() => null))?.isFile()) throw new Error(`--entry file not found: ${candidate}`);
+		return candidate;
+	}
+	for (const name of FUNCTION_ENTRY_CANDIDATES) {
+		const candidate = join(target, name);
+		if ((await stat(candidate).catch(() => null))?.isFile()) return candidate;
+	}
+	throw new Error(`No entry point found in directory ${target}. Add one of ${FUNCTION_ENTRY_CANDIDATES.join(", ")}, or pass --entry <file> (relative to the directory).`);
+}
+/**
 * Modules the bundler treats as `external` by default. The Amba
 * function runtime exposes zero npm packages — there is no "platform
 * stdlib" for customer functions to import. Keep this list empty.
@@ -4997,6 +5522,91 @@ var BundleSizeError = class extends Error {
 	}
 };
 /**
+* The single source-of-truth message for the wrong-handler-shape failure.
+* Shared between the CLI bundler (pre-upload), the local `dev` runner, and
+* the server-side deploy hint so dev / deploy / prod all describe the fix
+* identically. Customer functions run as Module Workers; the legacy
+* service-worker shape (`export default async function (req) { … }`) is
+* rejected by the runtime at upload, so we reject it before the round-trip.
+*/
+const HANDLER_SHAPE_FIX_MESSAGE = "Function entrypoint must `export default { async fetch(req, env, ctx) { … } }` (the Module Worker shape). Found a default-exported function instead.";
+/** Message used when the entry file has no `export default` at all. */
+const HANDLER_SHAPE_MISSING_DEFAULT_MESSAGE = "Function entrypoint must `export default { async fetch(req, env, ctx) { … } }` (the Module Worker shape). No default export was found.";
+/** Message used when the default export is present but has no `fetch` method. */
+const HANDLER_SHAPE_NO_FETCH_MESSAGE = "Function entrypoint must `export default { async fetch(req, env, ctx) { … } }` (the Module Worker shape). The default export has no `fetch` method.";
+/**
+* Thrown when the bundled entry's `export default` is not the Module Worker
+* shape (`{ fetch(req, env, ctx) }`). Raised BEFORE any upload so a wrong
+* handler shape fails fast on the developer's machine with an actionable
+* message instead of an opaque upstream rejection at deploy time.
+*/
+var HandlerShapeError = class extends Error {
+	kind;
+	constructor(message, kind) {
+		super(message);
+		this.kind = kind;
+		this.name = "HandlerShapeError";
+	}
+};
+/**
+* Inspect an already-imported module namespace and assert it has the
+* Module Worker handler shape: a default export that is an object (or
+* function-with-properties) carrying a callable `fetch`.
+*
+* Pure + side-effect free — it only reads the shape of `mod.default`, never
+* invokes `fetch`. This is the unit-testable core; `assertModuleWorkerShape`
+* wraps the import-from-code plumbing around it.
+*
+* Throws `HandlerShapeError` on:
+*   - no default export (`missing-default`)
+*   - a default-exported plain function — the legacy service-worker shape
+*     (`plain-function`)
+*   - a default export with no callable `fetch` (`no-fetch`)
+*/
+function assertHandlerShape(mod) {
+	const def = mod.default;
+	if (def === void 0 || def === null) throw new HandlerShapeError(HANDLER_SHAPE_MISSING_DEFAULT_MESSAGE, "missing-default");
+	if (typeof def === "function") {
+		if (typeof def.fetch !== "function") throw new HandlerShapeError(HANDLER_SHAPE_FIX_MESSAGE, "plain-function");
+		return;
+	}
+	if (typeof def !== "object") throw new HandlerShapeError(HANDLER_SHAPE_NO_FETCH_MESSAGE, "no-fetch");
+	if (typeof def.fetch !== "function") throw new HandlerShapeError(HANDLER_SHAPE_NO_FETCH_MESSAGE, "no-fetch");
+}
+/**
+* Validate that the bundled customer code exports the Module Worker handler
+* shape, by importing it in isolation and inspecting `mod.default`.
+*
+* Mechanism: write the bundle to a throwaway temp `.mjs` and dynamic-import
+* it, then hand the namespace to `assertHandlerShape`. This is the same
+* import-and-inspect approach the local `dev` runner uses
+* (`functions.ts` DEV_RUNNER_SOURCE) — reused here so the pre-upload check
+* and the dev runner agree on what "valid shape" means. Importing runs the
+* module's top-level code (unavoidable to read the export), but the handler
+* itself is NEVER invoked — we only read the shape of the exported object.
+*
+* The temp file is always cleaned up (best-effort) before returning.
+*/
+async function assertModuleWorkerShape(code) {
+	const dir = await mkdtemp(join(tmpdir(), "amba-fn-shape-"));
+	const filePath = join(dir, "fn.mjs");
+	try {
+		await writeFile(filePath, code, "utf8");
+		let mod;
+		try {
+			mod = await import(pathToFileURL(filePath).href);
+		} catch (err) {
+			throw new Error(`Failed to load the function entrypoint while validating its handler shape: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		assertHandlerShape(mod);
+	} finally {
+		await rm(dir, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	}
+}
+/**
 * Bundle a customer function file for upload to a Workers dispatch
 * namespace. Returns the bundled code + metadata; throws
 * `BundleSizeError` when the compressed size exceeds the cap so the CLI
@@ -5029,6 +5639,7 @@ async function bundleFunction(options) {
 	const compressedSize = await gzipSizeOf(output.contents);
 	const max = options.maxSizeBytes ?? 8388608;
 	if (compressedSize > max) throw new BundleSizeError(compressedSize, max);
+	if (options.validateHandlerShape !== false) await assertModuleWorkerShape(code);
 	return {
 		code,
 		sha256: await hashSha256Hex(output.contents),
@@ -5077,16 +5688,19 @@ function formatBytes$1(n) {
 * records the deployment in a single round-trip. The other subcommands
 * are thin shells over the admin API helpers in `api-client.ts`.
 */
-async function functionsDeployCommand(entryPoint, options = {}) {
+async function functionsDeployCommand(target, options = {}) {
 	const projectId = (await loadProjectConfig()).projectId;
-	const functionName = options.name ?? basename(entryPoint).replace(/\.[^.]+$/, "");
+	const targetIsDir = (await stat(target).catch(() => null))?.isDirectory() ?? false;
+	const entryPoint = await resolveFunctionEntry(target, options.entry);
+	const defaultName = targetIsDir ? basename(target.replace(/[/\\]+$/, "")) : basename(entryPoint).replace(/\.[^.]+$/, "");
+	const functionName = options.name ?? defaultName;
 	validateFunctionName(functionName);
 	const rateLimit = parseRateLimitFlags(options);
 	console.log();
 	console.log(pc.bold(`  amba functions deploy ${pc.cyan(functionName)}`));
 	console.log(pc.dim("  ─────────────────────────────────"));
 	console.log();
-	console.log(pc.dim("  Bundling…"));
+	console.log(pc.dim(`  Bundling ${entryPoint}…`));
 	const bundle = await bundleFunction({ entryPoint });
 	printBundleReport(bundle);
 	if (options.dryRun) {
@@ -5094,14 +5708,26 @@ async function functionsDeployCommand(entryPoint, options = {}) {
 		return;
 	}
 	console.log(pc.dim("  Uploading…"));
-	const result = await deployFunctionViaApi(projectId, {
-		name: functionName,
-		bundleCode: bundle.code,
-		rate_limit: rateLimit
-	});
+	let result;
+	try {
+		result = await deployFunctionViaApi(projectId, {
+			name: functionName,
+			bundleCode: bundle.code,
+			rate_limit: rateLimit,
+			public: options.public === true ? true : void 0
+		});
+	} catch (err) {
+		if (err instanceof ApiClientError && err.statusCode === 503) {
+			const base = err.message.trimEnd();
+			const sep = /[.!?]$/.test(base) ? " " : ". ";
+			throw new Error(`${base}${sep}The function platform is temporarily unavailable; retry in ~30s.`);
+		}
+		throw err;
+	}
 	console.log(pc.green("  ✓") + ` Deployed ${pc.cyan(functionName)} ${pc.dim(`v${result.data.version}`)}`);
 	console.log(pc.green("  ✓") + ` URL: ${pc.underline(result.fn_url)}`);
 	if (rateLimit) console.log(pc.dim(`  Rate limit: ${rateLimit.max} per ${rateLimit.window} (key=${rateLimit.key}) — enforced pre-dispatch`));
+	if (options.public === true) console.log(pc.yellow("  ! Public") + pc.dim(" — no X-Api-Key required. Verify the webhook signature inside your handler."));
 	console.log();
 }
 async function functionsListCommand() {
@@ -5153,11 +5779,12 @@ async function functionsScheduleCommand(name, cron, options = {}) {
 * — externalization rules, size cap, and source-map handling are
 * identical so dev → prod parity is automatic.
 *
-* Handler shape: `export default async function (req: Request): Promise<Response>`.
+* Handler shape: `export default { async fetch(req, env, ctx) { ... } }`.
 * `.env.local` values in the customer's working directory are passed
-* through to the child process so the handler can read them via
-* `process.env.MY_KEY`. Existing values in the parent's env take
-* priority (so `MY_KEY=x amba functions dev …` wins).
+* through to the child process and bridged into the `env` parameter so
+* the handler reads them the same way as in production (`env.MY_KEY`).
+* Existing values in the parent's env take priority (so
+* `MY_KEY=x amba functions dev …` wins).
 */
 async function functionsDevCommand(entryPoint, options = {}) {
 	const port = validatePort(options.port);
@@ -5432,11 +6059,41 @@ try {
   // \`pathToFileURL\` is a no-op equivalent on POSIX (returns file:///...).
   const bundleUrl = pathToFileURL(bundlePath).href;
   const mod = await import(bundleUrl);
-  if (typeof mod.default !== 'function') {
-    process.stderr.write('  Error: entry file must export default async function (req: Request): Promise<Response>\\n');
+  // Support the canonical modules export shape: export default { async fetch(req, env, ctx) { ... } }
+  // .env.local values are already in process.env (parent passes childEnv to the child process).
+  // Bridge them into the env parameter so dev/prod parity holds — production injects the same
+  // names as env bindings; local dev reads them from .env.local via process.env.
+  if (mod.default && typeof mod.default.fetch === 'function') {
+    const env = Object.assign(Object.create(null), process.env);
+    const fetchFn = mod.default.fetch.bind(mod.default);
+    handler = (req) => {
+      // Fresh ctx per request — production gives each request its own
+      // ExecutionContext; a shared stub would leak per-request state
+      // across concurrent requests in dev but not in prod.
+      const ctx = {
+        waitUntil: (p) => {
+          // Swallow rejections from background promises — prod handles
+          // waitUntil rejections without crashing. Leaving the rejection
+          // unhandled would cause Node 15+ to crash the child process
+          // even though the HTTP response was already sent.
+          Promise.resolve(p).catch(() => {});
+        },
+        passThroughOnException: () => {},
+      };
+      return fetchFn(req, env, ctx);
+    };
+  } else if (typeof mod.default === 'function') {
+    // Legacy service-worker shape (\`export default async function (req) { ... }\`).
+    // REJECTED — production runs functions as Module Workers and the runtime
+    // rejects this shape at upload. Accepting it in dev was a dev/prod parity
+    // trap: a function that ran here would fail \`amba functions deploy\`. Reject
+    // with the same fix the bundler + server hint use so dev and prod agree.
+    process.stderr.write('  Error: Function entrypoint must \`export default { async fetch(req, env, ctx) { … } }\` (the Module Worker shape). Found a default-exported function instead.\\n');
+    process.exit(2);
+  } else {
+    process.stderr.write('  Error: Function entrypoint must \`export default { async fetch(req, env, ctx) { … } }\` (the Module Worker shape). The default export has no \`fetch\` method.\\n');
     process.exit(2);
   }
-  handler = mod.default;
 } catch (err) {
   process.stderr.write('  Bundle import failed: ' + (err && err.stack ? err.stack : err) + '\\n');
   process.exit(2);
@@ -5586,8 +6243,8 @@ function parseRateLimitFlags(options) {
 * Output formatting:
 *   - `--json`: NDJSON to stdout (one event per line) so `| jq` works.
 *   - default: human-readable lines:
-*       2026-05-08T12:34:56.789Z scan-letter-v3 [info] "scanning"
-*       2026-05-08T12:34:57.012Z scan-letter-v3 [exception] TypeError: …
+*       2026-05-08T12:34:56.789Z scan-letter@v3 [info] "scanning"
+*       2026-05-08T12:34:57.012Z scan-letter@v3 [exception] TypeError: …
 *
 * Server-side scoping is enforced — the API filters by ScriptName
 * prefix so a developer can never read another tenant's logs.
@@ -5602,7 +6259,8 @@ async function functionsLogsCommand(functionName, options = {}) {
 	const res = await getFunctionLogs(projectConfig.projectId, functionName, {
 		since: options.since,
 		until: options.until,
-		limit: options.limit
+		limit: options.limit,
+		requestId: options.requestId
 	});
 	printEvents(res.data.events, options.json);
 	if (res.data.truncated) if (options.json) process.stderr.write(`{"truncated":true}\n`);
@@ -5618,7 +6276,8 @@ async function runTail(projectId, functionName, options) {
 		try {
 			result = await getFunctionLogs(projectId, functionName, {
 				since: new Date(highWaterMs).toISOString(),
-				limit: options.limit ?? 200
+				limit: options.limit ?? 200,
+				requestId: options.requestId
 			});
 		} catch (err) {
 			console.error(pc.yellow(`  ! tail fetch failed: `) + (err instanceof Error ? err.message : String(err)));
@@ -5640,7 +6299,7 @@ function printEvents(events, asJson) {
 	}
 	for (const e of ordered) {
 		const ts = e.EventTimestampMs ? new Date(e.EventTimestampMs).toISOString() : "????-??-??T??:??:??Z";
-		const script = e.ScriptName ?? "<unknown-script>";
+		const script = e.function_name ? `${e.function_name}@v${e.version ?? "?"}` : "<unknown-function>";
 		if (e.Logs && e.Logs.length > 0) for (const logLine of e.Logs) {
 			const level = renderLevel(logLine.Level);
 			const msg = renderMessage(logLine.Message);
@@ -5746,11 +6405,20 @@ async function resolveSecretValue(opts) {
 //#endregion
 //#region src/commands/secrets.ts
 /**
-* `amba secrets ...` — write per-function secrets through the platform
-* API. The CLI sends `{name, value, function}` to the admin endpoint;
-* the server stores the value, validates reserved binding names, and
-* propagates it to the deployed Worker's binding. Sync is eventual —
-* `amba secrets list` shows progress.
+* `amba secrets ...` — write secrets through the platform API. The CLI
+* sends `{name, value, function?}` to the admin endpoint; the server
+* stores the value, validates reserved binding names, and propagates it to
+* the deployed Worker binding(s). Sync is eventual — `amba secrets list`
+* shows progress.
+*
+* Two scopes:
+*   - `--function <name>` → the secret binds to that one function.
+*   - no `--function`     → a PROJECT-WIDE secret, visible to every
+*     function in the project (and to any function deployed later). Set it
+*     once instead of repeating the same value per function.
+*
+* Secrets may be set BEFORE the function is deployed. The sync drains once
+* a deployment lands (and `amba functions deploy` re-syncs at the end).
 */
 async function secretsSetCommand(name, value, options) {
 	validateSecretName(name);
@@ -5760,14 +6428,15 @@ async function secretsSetCommand(name, value, options) {
 	});
 	const projectConfig = await loadProjectConfig();
 	if (options.env === "prod") console.log(pc.dim("  Note: --env is informational; prod and dev share one secret namespace per project."));
+	const scopeLabel = options.function ? options.function : "project-wide";
 	console.log();
 	console.log(pc.bold(`  amba secrets set ${pc.cyan(name)}`));
-	console.log(pc.dim(`  function=${options.function}  env=${options.env ?? "dev"}`));
+	console.log(pc.dim(`  scope=${scopeLabel}  env=${options.env ?? "dev"}`));
 	console.log();
 	const res = await setSecretViaApi(projectConfig.projectId, {
 		name,
 		value: resolvedValue,
-		function: options.function
+		...options.function ? { function: options.function } : {}
 	});
 	console.log(pc.green("  ✓") + ` Secret ${pc.cyan(name)} stored ${pc.dim(`v${res.data.version}`)}`);
 	console.log(pc.green("  ✓") + ` Workers Secret sync ${pc.dim(`(status=${res.data.sync_status})`)} queued`);
@@ -5775,17 +6444,22 @@ async function secretsSetCommand(name, value, options) {
 	console.log(pc.dim("  Workers Secret will be live within ~30s. Run `amba secrets list` to check sync status."));
 	console.log();
 }
-async function secretsListCommand() {
-	const res = await listSecretsViaApi((await loadProjectConfig()).projectId);
+async function secretsListCommand(options = {}) {
+	const res = await listSecretsViaApi((await loadProjectConfig()).projectId, { function: options.function });
 	console.log();
+	if (options.function) {
+		console.log(pc.dim(`  Secrets for function ${pc.bold(options.function)}:`));
+		console.log();
+	}
 	if (res.data.length === 0) {
-		console.log(pc.dim("  No secrets configured."));
+		console.log(pc.dim(options.function ? `  No secrets configured for ${options.function}.` : "  No secrets configured."));
 		console.log();
 		return;
 	}
 	for (const row of res.data) {
 		const status = renderStatus(row.sync_status);
-		console.log(`  ${pc.bold(row.name)} ` + pc.dim(`(${row.function})`) + ` v${row.version}  ${status}` + (row.last_error ? pc.dim(`  — ${row.last_error}`) : ""));
+		const scope = row.function ?? "project-wide";
+		console.log(`  ${pc.bold(row.name)} ` + pc.dim(`(${scope})`) + ` v${row.version}  ${status}` + (row.last_error ? pc.dim(`  — ${row.last_error}`) : ""));
 	}
 	console.log();
 }
@@ -5834,7 +6508,7 @@ function renderStatus(status) {
 * Project is resolved via `loadProjectConfig` (AMBA_PROJECT_ID env, then
 * .env / .env.local in the cwd) — same pattern as `amba secrets *`.
 */
-function handleError(err) {
+function handleError$1(err) {
 	if (err instanceof ApiClientError) if (err.statusCode === 401 || err.statusCode === 403) console.log(pc.red("  ✗") + " Not authenticated — run `amba login` first.");
 	else console.log(pc.red("  ✗") + ` ${err.message}`);
 	else if (err instanceof Error) console.log(pc.red("  ✗") + ` ${err.message}`);
@@ -5848,7 +6522,7 @@ function handleError(err) {
 * its own request wrapper — same auth flow as `request()` in api-client,
 * intentionally not exported there so we don't grow the public surface.
 */
-async function adminWrite(method, path, body) {
+async function adminWrite$1(method, path, body) {
 	const token = await resolveBearerToken();
 	const url = `${process.env["AMBA_API_URL"] ?? "https://api.amba.dev"}/v1/admin${path}`;
 	const res = await fetch(url, {
@@ -5910,7 +6584,7 @@ async function billingStatusCommand() {
 			console.log();
 		}
 	} catch (err) {
-		handleError(err);
+		handleError$1(err);
 	}
 }
 async function billingUpgradeCommand(input) {
@@ -5921,7 +6595,7 @@ async function billingUpgradeCommand(input) {
 	try {
 		const { projectId } = await loadProjectConfig();
 		const interval = input.interval ?? "month";
-		const res = await adminWrite("POST", `/projects/${projectId}/billing/checkout`, {
+		const res = await adminWrite$1("POST", `/projects/${projectId}/billing/checkout`, {
 			tier: input.tier,
 			interval
 		});
@@ -5935,7 +6609,7 @@ async function billingUpgradeCommand(input) {
 		console.log(pc.dim("  Subscription status updates automatically once Stripe confirms (a few seconds)."));
 		console.log();
 	} catch (err) {
-		handleError(err);
+		handleError$1(err);
 	}
 }
 async function billingPortalCommand() {
@@ -5945,13 +6619,13 @@ async function billingPortalCommand() {
 	console.log();
 	try {
 		const { projectId } = await loadProjectConfig();
-		const res = await adminWrite("POST", `/projects/${projectId}/billing/portal`);
+		const res = await adminWrite$1("POST", `/projects/${projectId}/billing/portal`);
 		console.log(pc.bold("  Open this URL to manage your subscription:"));
 		console.log();
 		console.log(`  ${pc.cyan(res.data.url)}`);
 		console.log();
 	} catch (err) {
-		handleError(err);
+		handleError$1(err);
 	}
 }
 async function billingSetCeilingCommand(input) {
@@ -5961,88 +6635,447 @@ async function billingSetCeilingCommand(input) {
 	console.log();
 	try {
 		const { projectId } = await loadProjectConfig();
-		await adminWrite(`PUT`, `/projects/${projectId}/billing/ceiling`, { ceiling_usd: input.ceiling });
+		await adminWrite$1(`PUT`, `/projects/${projectId}/billing/ceiling`, { ceiling_usd: input.ceiling });
 		if (input.ceiling === null) console.log(pc.green("  ✓") + " Spend ceiling removed (linear overage continues).");
 		else console.log(pc.green("  ✓") + ` Spend ceiling set to $${input.ceiling}/mo.`);
 		console.log();
 	} catch (err) {
-		handleError(err);
+		handleError$1(err);
 	}
 }
 //#endregion
-//#region src/commands/collections.ts
+//#region src/commands/payments.ts
 /**
-* `amba collections ...` — thin shells over the admin collection routes.
-*
-* Wire shapes:
-*
-*   POST   /admin/projects/:p/collections             — create (full schema)
-*   GET    /admin/projects/:p/collections             — list
-*   PATCH  /admin/projects/:p/collections/:name       — single-op alter
-*   DELETE /admin/projects/:p/collections/:name       — drop (requires ?confirm)
-*
-* The CLI's job is to:
-*   1. Validate names / types client-side so an obviously-bad invocation
-*      doesn't round-trip.
-*   2. Translate the user-friendly CLI flag shape (`--field name:type`,
-*      `--add-field`, `--drop-field`) into the wire shape (single op per
-*      PATCH).
-*   3. Block until the server reports success.
-*   4. Surface server errors with a sensible CLI message.
-*
-* Multi-op alters are issued sequentially so the operator audit trail
-* stays one-to-one with developer actions.
+* `amba payments *` subcommands — CLI access to the Amba Payments (Stripe
+* Connect platform) surface at `/v1/admin/projects/:id/payments/*`
+* (tracker #10).
+*
+* Amba is the payments rail for the developer's app: the app is the seller,
+* Amba takes a platform fee, Stripe carries money-transmission. This is the
+* developer-facing onboarding + config + reporting surface, so naming Stripe
+* here is by intent (same as `amba billing`).
+*
+*   amba payments setup                    — create the connected account +
+*                                            print the hosted onboarding URL.
+*   amba payments status                   — onboarding stage + capability flags.
+*   amba payments set-fee <bps|off>        — default platform fee (basis points).
+*   amba payments balance                  — connected-account balance.
+*   amba payments payouts                  — recent payouts.
+*
+* Every live call is gated by the platform's PAYMENTS_CONNECT_LIVE
+* kill-switch — when off the API returns PAYMENTS_NOT_ENABLED, surfaced
+* verbatim here. Project resolved via loadProjectConfig (same as billing).
 */
+function handleError(err) {
+	if (err instanceof ApiClientError) if (err.statusCode === 401 || err.statusCode === 403) console.log(pc.red("  ✗") + " Not authenticated — run `amba login` first.");
+	else if (err.errorCode === "PAYMENTS_NOT_ENABLED") console.log(pc.yellow("  •") + " Payments are not enabled on this Amba platform yet. The platform owner must finish setup before payments go live.");
+	else console.log(pc.red("  ✗") + ` ${err.message}`);
+	else if (err instanceof Error) console.log(pc.red("  ✗") + ` ${err.message}`);
+	else console.log(pc.red("  ✗") + " Unknown error");
+	console.log();
+	process.exit(1);
+}
 /**
-* Closed-set type catalog. Matches data's `ColumnType` exactly — keeps
-* the CLI fail-fast path aligned with the DDL emit's accepted shapes.
-*
-* The CLI accepts customer-friendly synonyms (e.g. `int` → `integer`)
-* via `normalizeColumnType` so the `--field` flag stays ergonomic
-* without the API needing to relax its closed catalog.
+* POST/PUT to the admin API. Mirrors the helper in billing.ts (api-client
+* doesn't export a generic write for arbitrary paths).
 */
-const ALLOWED_TYPES = new Set([
-	"uuid",
-	"text",
-	"integer",
-	"bigint",
-	"numeric",
-	"boolean",
-	"timestamptz",
-	"date",
-	"jsonb",
-	"vector"
-]);
-const TYPE_SYNONYMS = {
-	int: "integer",
-	int4: "integer",
-	int8: "bigint",
-	bool: "boolean",
-	json: "jsonb",
-	string: "text"
-};
-async function collectionsCreateCommand(name, options) {
-	const reason = getReservationReason(name);
-	if (reason) throw new Error(`Cannot create collection '${name}': ${reason}`);
-	const columns = options.field.map(parseColumnSpec);
-	const indexes = options.index.map(parseIndexSpec);
-	const projectConfig = await loadProjectConfig();
-	console.log();
-	console.log(pc.bold(`  amba collections create ${pc.cyan(name)}`));
-	for (const c of columns) console.log(pc.dim("    ") + c.name + pc.dim(": ") + c.type + (c.nullable ? pc.dim(" NULL") : pc.dim(" NOT NULL")));
-	console.log();
-	const res = await createCollection(projectConfig.projectId, {
-		name,
-		columns,
-		indexes
+async function adminWrite(method, path, body) {
+	const token = await resolveBearerToken();
+	const url = `${process.env["AMBA_API_URL"] ?? "https://api.amba.dev"}/v1/admin${path}`;
+	const res = await fetch(url, {
+		method,
+		headers: {
+			Authorization: `Bearer ${token}`,
+			"Content-Type": "application/json",
+			"User-Agent": "amba-cli/0.1.1"
+		},
+		body: body === void 0 ? void 0 : JSON.stringify(body)
 	});
-	console.log(pc.green("  ✓") + ` Created — version ${res.data.version}`);
-	console.log(pc.dim(`    workflow_id: ${res.data.workflow_id}`));
-	console.log();
+	if (!res.ok) {
+		let message = `API request failed: ${res.status} ${res.statusText}`;
+		let code;
+		try {
+			const errorBody = await res.json();
+			if (errorBody.error?.message) {
+				message = errorBody.error.message;
+				code = errorBody.error.code;
+			}
+		} catch {}
+		throw new ApiClientError(message, res.status, code);
+	}
+	return await res.json();
 }
-async function collectionsAlterCommand(name, options) {
-	if (options.addField.length === 0 && options.dropField.length === 0 && options.addIndex.length === 0) throw new Error("amba collections alter: at least one of --add-field, --add-index, or --drop-field is required.");
-	const confirmed = new Set(options.confirm ?? []);
+function printAccount(a) {
+	console.log(`  Account:            ${pc.dim(a.stripe_account_id)}`);
+	console.log(`  Onboarding:         ${pc.bold(a.onboarding_status)}`);
+	console.log(`  Charges enabled:    ${a.charges_enabled ? pc.green("yes") : pc.yellow("no")}`);
+	console.log(`  Payouts enabled:    ${a.payouts_enabled ? pc.green("yes") : pc.yellow("no")}`);
+	console.log(`  Country:            ${a.country ?? pc.dim("—")}`);
+	console.log(`  Default fee:        ${a.default_platform_fee_bps === null ? pc.dim("none") : `${a.default_platform_fee_bps} bps (${(a.default_platform_fee_bps / 100).toFixed(2)}%)`}`);
+}
+async function paymentsSetupCommand(input) {
+	console.log();
+	console.log(pc.bold("  amba payments setup"));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	try {
+		const { projectId } = await loadProjectConfig();
+		printAccount((await adminWrite("POST", `/projects/${projectId}/payments/accounts`, {
+			...input.country ? { country: input.country } : {},
+			...input.email ? { email: input.email } : {}
+		})).data);
+		console.log();
+		const link = await adminWrite("POST", `/projects/${projectId}/payments/accounts/link`);
+		console.log(pc.bold("  Open this URL to finish setting up payments:"));
+		console.log();
+		console.log(`  ${pc.cyan(link.data.url)}`);
+		console.log();
+		console.log(pc.dim("  Status updates automatically once setup completes."));
+		console.log();
+	} catch (err) {
+		handleError(err);
+	}
+}
+async function paymentsStatusCommand() {
+	console.log();
+	console.log(pc.bold("  amba payments status"));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	try {
+		const { projectId } = await loadProjectConfig();
+		const res = await adminGet(`/projects/${projectId}/payments/accounts`);
+		if (!res.data.connected_account) {
+			console.log(pc.dim("  No payments account yet. Run `amba payments setup`."));
+			console.log();
+			return;
+		}
+		printAccount(res.data.connected_account);
+		console.log();
+	} catch (err) {
+		handleError(err);
+	}
+}
+async function paymentsSetFeeCommand(input) {
+	console.log();
+	console.log(pc.bold("  amba payments set-fee"));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	try {
+		const { projectId } = await loadProjectConfig();
+		await adminWrite("PUT", `/projects/${projectId}/payments/config`, { default_platform_fee_bps: input.bps });
+		if (input.bps === null) console.log(pc.green("  ✓") + " Default platform fee cleared.");
+		else console.log(pc.green("  ✓") + ` Default platform fee set to ${input.bps} bps (${(input.bps / 100).toFixed(2)}%).`);
+		console.log();
+	} catch (err) {
+		handleError(err);
+	}
+}
+async function paymentsBalanceCommand() {
+	console.log();
+	console.log(pc.bold("  amba payments balance"));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	try {
+		const { projectId } = await loadProjectConfig();
+		const res = await adminGet(`/projects/${projectId}/payments/balance`);
+		const fmt = (b) => `${(b.amount / 100).toFixed(2)} ${b.currency.toUpperCase()}`;
+		console.log(`  Available:  ${res.data.available.length ? res.data.available.map(fmt).join(", ") : pc.dim("—")}`);
+		console.log(`  Pending:    ${res.data.pending.length ? res.data.pending.map(fmt).join(", ") : pc.dim("—")}`);
+		console.log();
+	} catch (err) {
+		handleError(err);
+	}
+}
+async function paymentsPayoutsCommand(input) {
+	console.log();
+	console.log(pc.bold("  amba payments payouts"));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	try {
+		const { projectId } = await loadProjectConfig();
+		const res = await adminGet(`/projects/${projectId}/payments/payouts${input.limit ? `?limit=${input.limit}` : ""}`);
+		if (res.data.length === 0) {
+			console.log(pc.dim("  No payouts yet."));
+			console.log();
+			return;
+		}
+		for (const p of res.data) {
+			const arrival = (/* @__PURE__ */ new Date(p.arrival_date * 1e3)).toLocaleDateString();
+			console.log(`  ${pc.dim(p.id.padEnd(28))} ${(p.amount / 100).toFixed(2)} ${p.currency.toUpperCase().padEnd(4)} ${pc.dim(p.status.padEnd(12))} arrives ${arrival}`);
+		}
+		console.log();
+	} catch (err) {
+		handleError(err);
+	}
+}
+//#endregion
+//#region src/commands/monetization.ts
+/**
+* `amba monetization *` subcommands — CLI access to the monetization control
+* plane behind `/v1/admin/projects/:id/monetization/*`.
+*
+*   amba monetization plan     — three-way diff (declared vs adopted baseline
+*                                vs live provider) + store-floor preflight +
+*                                drift. READ-ONLY — previews; applies nothing.
+*   amba monetization drift    — out-of-band changes to Amba-managed objects.
+*   amba monetization export   — snapshot the live config to a declarative
+*                                bundle (the `monetization` section), to stdout
+*                                or a file.
+*   amba monetization adopt    — record the live config as the managed baseline
+*                                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.
+*
+* Project is resolved via `loadProjectConfig` — same pattern as the other
+* project-scoped CLI commands.
+*/
+/**
+* Authenticated write helper (POST). Mirrors the `adminWrite` in
+* `commands/billing.ts` — kept local so the api-client public surface doesn't
+* grow a generic POST.
+*/
+async function adminPost(path, body) {
+	const token = await resolveBearerToken();
+	const url = `${process.env["AMBA_API_URL"] ?? "https://api.amba.dev"}/v1/admin${path}`;
+	const res = await fetch(url, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${token}`,
+			"Content-Type": "application/json",
+			"User-Agent": "amba-cli/0.1.1"
+		},
+		body: body === void 0 ? void 0 : JSON.stringify(body)
+	});
+	if (!res.ok) {
+		let message = `API request failed: ${res.status} ${res.statusText}`;
+		let code;
+		try {
+			const errorBody = await res.json();
+			if (errorBody.error?.message) {
+				message = errorBody.error.message;
+				code = errorBody.error.code;
+			}
+		} catch {}
+		throw new ApiClientError(message, res.status, code);
+	}
+	return await res.json();
+}
+function header(title) {
+	console.log();
+	console.log(pc.bold(`  amba monetization ${title}`));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+}
+async function monetizationPlanCommand() {
+	const { projectId } = await loadProjectConfig();
+	header("plan");
+	const plan = (await adminGet(`/projects/${projectId}/monetization/plan`)).data;
+	if (plan.clean) {
+		console.log(pc.green("  ✓") + " No changes — declared config matches the live provider.");
+		console.log();
+		return;
+	}
+	if (plan.ops.length > 0) {
+		console.log(pc.bold("  Pending operations (preview — nothing is applied):"));
+		for (const op of plan.ops) console.log(`    ${pc.cyan(op.op.padEnd(12))} ${pc.bold(op.object_type)} ${op.identifier}  ${pc.dim(`[${op.status}]`)}`);
+		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();
+	}
+	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();
+	}
+}
+async function monetizationDriftCommand() {
+	const { projectId } = await loadProjectConfig();
+	header("drift");
+	const data = (await adminGet(`/projects/${projectId}/monetization/drift`)).data;
+	if (!data.has_drift) {
+		console.log(pc.green("  ✓") + " No drift — managed config matches the live provider.");
+		console.log();
+		return;
+	}
+	console.log(pc.yellow("  Drift detected:"));
+	for (const d of data.drift) console.log(`    ${pc.bold(d.object_type)} ${d.identifier}`);
+	console.log();
+}
+async function monetizationExportCommand(options = {}) {
+	const { projectId } = await loadProjectConfig();
+	const bundle = {
+		version: 1,
+		monetization: (await adminGet(`/projects/${projectId}/monetization/export`)).data.monetization
+	};
+	const json = JSON.stringify(bundle, null, 2);
+	if (options.file) {
+		await writeFile(resolve(options.file), json + "\n", "utf-8");
+		console.log();
+		console.log(pc.green("  ✓") + ` Wrote live monetization config to ${pc.cyan(options.file)}.`);
+		console.log();
+	} else console.log(json);
+}
+async function monetizationAdoptCommand(options = {}) {
+	const { projectId } = await loadProjectConfig();
+	header("adopt");
+	if (!options.all) {
+		console.log("  ✗ Pass --all to adopt the entire live config as the managed baseline.");
+		process.exit(1);
+	}
+	const d = (await adminPost(`/projects/${projectId}/monetization/adopt`, { adopt_all: true })).data;
+	console.log(pc.green("  ✓") + ` Adopted ${d.adopted} object(s) as the managed baseline ` + pc.dim(`(${d.entitlements} entitlements · ${d.products} products · ${d.offerings} offerings · ${d.packages} packages · ${d.paywalls} paywalls)`));
+	console.log(pc.dim("    The next `amba monetization plan` is now a clean no-op."));
+	console.log();
+}
+async function monetizationApplyCommand(options = {}) {
+	const { projectId } = await loadProjectConfig();
+	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();
+		console.log("  ✗ Configure these in the store, then run plan + apply again.");
+		process.exit(1);
+	}
+	if (plan.clean) {
+		console.log(pc.green("  ✓") + " Nothing to apply — declared config matches the provider.");
+		console.log();
+		return;
+	}
+	if (options.reconcile && options.reconcile !== "amba" && options.reconcile !== "adopt") {
+		console.log(pc.red("  ✗") + " --reconcile must be 'amba' or 'adopt'.");
+		process.exit(1);
+	}
+	const body = { plan_hash: plan.plan_hash };
+	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;
+	try {
+		res = await adminPost(`/projects/${projectId}/monetization/apply`, body);
+	} 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}`));
+			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));
+		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 (d.gated.length > 0) {
+		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 (d.refused.length > 0) {
+		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}`);
+	}
+	console.log();
+	if (d.status !== "succeeded") process.exit(1);
+}
+//#endregion
+//#region src/commands/collections.ts
+/**
+* `amba collections ...` — thin shells over the admin collection routes.
+*
+* Wire shapes:
+*
+*   POST   /admin/projects/:p/collections             — create (full schema)
+*   GET    /admin/projects/:p/collections             — list
+*   PATCH  /admin/projects/:p/collections/:name       — single-op alter
+*   DELETE /admin/projects/:p/collections/:name       — drop (requires ?confirm)
+*
+* The CLI's job is to:
+*   1. Validate names / types client-side so an obviously-bad invocation
+*      doesn't round-trip.
+*   2. Translate the user-friendly CLI flag shape (`--field name:type`,
+*      `--add-field`, `--drop-field`) into the wire shape (single op per
+*      PATCH).
+*   3. Block until the server reports success.
+*   4. Surface server errors with a sensible CLI message.
+*
+* Multi-op alters are issued sequentially so the operator audit trail
+* stays one-to-one with developer actions.
+*/
+/**
+* Closed-set type catalog. Matches data's `ColumnType` exactly — keeps
+* the CLI fail-fast path aligned with the DDL emit's accepted shapes.
+*
+* The CLI accepts customer-friendly synonyms (e.g. `int` → `integer`)
+* via `normalizeColumnType` so the `--field` flag stays ergonomic
+* without the API needing to relax its closed catalog.
+*/
+const ALLOWED_TYPES = new Set([
+	"uuid",
+	"text",
+	"integer",
+	"bigint",
+	"numeric",
+	"boolean",
+	"timestamptz",
+	"date",
+	"jsonb",
+	"vector"
+]);
+const TYPE_SYNONYMS = {
+	int: "integer",
+	int4: "integer",
+	int8: "bigint",
+	bool: "boolean",
+	json: "jsonb",
+	string: "text"
+};
+async function collectionsCreateCommand(name, options) {
+	const reason = getReservationReason(name);
+	if (reason) throw new Error(`Cannot create collection '${name}': ${reason}`);
+	const columns = options.field.map(parseColumnSpec);
+	const indexes = options.index.map(parseIndexSpec);
+	const projectConfig = await loadProjectConfig();
+	console.log();
+	console.log(pc.bold(`  amba collections create ${pc.cyan(name)}`));
+	for (const c of columns) console.log(pc.dim("    ") + c.name + pc.dim(": ") + c.type + (c.nullable ? pc.dim(" NULL") : pc.dim(" NOT NULL")));
+	console.log();
+	const res = await createCollection(projectConfig.projectId, {
+		name,
+		columns,
+		indexes
+	});
+	console.log(pc.green("  ✓") + ` Created — version ${res.data.version}`);
+	console.log(pc.dim(`    workflow_id: ${res.data.workflow_id}`));
+	console.log();
+}
+async function collectionsAlterCommand(name, options) {
+	if (options.addField.length === 0 && options.dropField.length === 0 && options.addIndex.length === 0) throw new Error("amba collections alter: at least one of --add-field, --add-index, or --drop-field is required.");
+	const confirmed = new Set(options.confirm ?? []);
 	for (const col of options.dropField) if (!confirmed.has(col)) throw new Error(`Refusing to drop column '${col}' without --confirm ${col} (DROP COLUMN is destructive).`);
 	const projectConfig = await loadProjectConfig();
 	for (const fieldSpec of options.addField) {
@@ -6268,8 +7301,22 @@ const PG_TYPE_TO_TS = {
 	jsonb: "unknown",
 	json: "unknown"
 };
+const ARRAY_UDT_TO_TS = {
+	_text: "string",
+	_varchar: "string",
+	_uuid: "string",
+	_int4: "number",
+	_int8: "number",
+	_int2: "number",
+	_numeric: "number",
+	_float8: "number",
+	_float4: "number",
+	_bool: "boolean"
+};
 function tsTypeForColumn(col) {
-	const base = PG_TYPE_TO_TS[col.data_type] ?? "unknown";
+	let base;
+	if (col.data_type === "ARRAY") base = `${col.udt_name ? ARRAY_UDT_TO_TS[col.udt_name] ?? "unknown" : "unknown"}[]`;
+	else base = PG_TYPE_TO_TS[col.data_type] ?? "unknown";
 	if (col.column_name === "deleted_at") return "string | null";
 	if (col.is_nullable === "YES") return `${base} | null`;
 	return base;
@@ -6391,13 +7438,21 @@ function makeCodegenHttpClient() {
 * directory (mirrors `wrangler pages deploy ./out` semantics). Dynamic
 * logic belongs in `amba functions deploy`, not in a site directory.
 */
-const SITE_NAME_RE = /^[a-z][a-z0-9_-]{0,49}$/;
-const HOSTNAME_RE = /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
+const SITE_NAME_RE$1 = /^[a-z][a-z0-9_-]{0,49}$/;
+const HOSTNAME_RE$1 = /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
+const MAX_CERT_CN_LENGTH = 64;
+const PLATFORM_DOMAINS = ["amba.host", "amba.dev"];
+function isPlatformDomain(host) {
+	return PLATFORM_DOMAINS.some((d) => host === d || host.endsWith(`.${d}`));
+}
 function validateSiteName(name) {
-	if (!SITE_NAME_RE.test(name)) throw new Error(`Invalid site name '${name}'. Must match /^[a-z][a-z0-9_-]{0,49}$/ (lowercase ASCII, digits, underscore or hyphen; ≤50 chars).`);
+	if (!SITE_NAME_RE$1.test(name)) throw new Error(`Invalid site name '${name}'. Must match /^[a-z][a-z0-9_-]{0,49}$/ (lowercase ASCII, digits, underscore or hyphen; ≤50 chars).`);
 }
 function validateHostname(host) {
-	if (!HOSTNAME_RE.test(host)) throw new Error(`Invalid hostname '${host}'. Must be a DNS-shaped name (e.g. site.example.com).`);
+	const h = host.trim().toLowerCase();
+	if (!HOSTNAME_RE$1.test(h)) throw new Error(`Invalid hostname '${host}'. Must be a DNS-shaped name (e.g. site.example.com).`);
+	if (h.length > MAX_CERT_CN_LENGTH) throw new Error(`Hostname '${host}' is too long for certificate issuance (max ${MAX_CERT_CN_LENGTH} characters). Use a shorter subdomain.`);
+	if (isPlatformDomain(h)) throw new Error(`'${host}' is reserved by the platform. Attach a domain you own, e.g. app.yourdomain.com.`);
 }
 /**
 * Per-deploy size cap. The hosting provider enforces 25 MiB per file +
@@ -6446,7 +7501,7 @@ async function sitesDeployCommand(inputDir, options = {}) {
 	if (domains.data.length > 0) {
 		console.log();
 		console.log(pc.dim("  Domains:"));
-		for (const d of domains.data) console.log(`    ${pc.bold(d.hostname)}  ${formatCertStatus(d.cert_status)}`);
+		for (const d of domains.data) console.log(`    ${pc.bold(d.hostname)}  ${formatDomainStatus(d)}`);
 	}
 	console.log();
 }
@@ -6496,32 +7551,51 @@ async function sitesDomainAddCommand(hostname, options) {
 	console.log();
 	const res = await addSiteDomainViaApi(projectId, options.site, hostname);
 	console.log(pc.green("  ✓") + ` Custom hostname registered`);
+	const validation = res.data.ssl_validation ?? [];
+	const ownership = res.data.ownership_verification;
+	const isApex = res.data.is_apex ?? false;
+	if (validation.length > 0 || ownership) {
+		console.log();
+		console.log(pc.dim("  1. Publish these DNS records to verify ownership:"));
+		for (const rec of validation) if (rec.txt_name && rec.txt_value) console.log(`     ${pc.bold("TXT")} ${rec.txt_name}  →  ${pc.cyan(rec.txt_value)}`);
+		if (ownership?.name && ownership.value) console.log(`     ${pc.bold("TXT")} ${ownership.name}  →  ${pc.cyan(ownership.value)}`);
+		console.log();
+		console.log(pc.dim("  2. Point your hostname at the Amba target:"));
+	} else {
+		console.log();
+		console.log(pc.dim("  Point your hostname at the Amba target:"));
+	}
+	console.log(`     ${pc.bold("CNAME")} ${hostname}  →  ${pc.cyan(res.data.dns_target)}`);
 	console.log();
-	console.log(pc.dim("  Point your DNS at:"));
-	console.log(`    ${pc.bold("CNAME")} ${hostname}  →  ${pc.cyan(res.data.dns_target)}`);
-	console.log();
+	if (isApex) {
+		console.log(pc.dim(`  ${hostname} is a root domain — the CNAME above works only if your DNS provider`));
+		console.log(pc.dim(`  flattens CNAME-at-root. If it doesn't, A-record apex support is coming soon;`));
+		console.log(pc.dim(`  use a subdomain like app.${hostname} in the meantime.`));
+		console.log();
+	}
 	if (options.noWait) {
-		console.log(pc.yellow("  ! --no-wait — skipping cert poll. Run `amba sites describe` later."));
+		console.log(pc.yellow("  ! --no-wait — skipping status poll. Run `amba sites describe` later."));
 		return;
 	}
 	const timeout = (options.timeout ?? 600) * 1e3;
 	const start = Date.now();
-	let lastStatus = "";
+	let lastLine = "";
 	while (Date.now() - start < timeout) {
 		const row = (await listSiteDomains(projectId, options.site)).data.find((d) => d.hostname === hostname);
 		if (!row) throw new Error(`Domain ${hostname} disappeared from listing — check API state.`);
-		if (row.cert_status !== lastStatus) {
-			console.log(pc.dim(`  cert_status: ${formatCertStatus(row.cert_status)}`));
-			lastStatus = row.cert_status;
+		const line = formatDomainStatus(row);
+		if (line !== lastLine) {
+			console.log(pc.dim(`  ${line}`));
+			lastLine = line;
 		}
-		if (row.cert_status === "active") {
-			console.log(pc.green("  ✓") + ` ${hostname} live with valid cert.`);
+		if (row.cert_status === "active" && row.ownership_status === "active") {
+			console.log(pc.green("  ✓") + ` ${hostname} is live with a valid certificate.`);
 			return;
 		}
-		if (row.cert_status === "error") throw new Error(`Cert provisioning failed for ${hostname}. Check that the CNAME points at ${res.data.dns_target}.`);
+		if (row.cert_status === "error" || row.ownership_status === "error") throw new Error(`Domain setup failed for ${hostname}. Confirm the TXT record(s) above are published and the CNAME points at ${res.data.dns_target}.`);
 		await sleep(5e3);
 	}
-	console.log(pc.yellow(`  ! Timed out after ${options.timeout ?? 600}s waiting for cert. Re-run \`amba sites describe ${options.site}\` to check status.`));
+	console.log(pc.yellow(`  ! Timed out after ${options.timeout ?? 600}s. Re-run \`amba sites describe ${options.site}\` to check status.`));
 }
 async function sitesDomainListCommand(siteName) {
 	validateSiteName(siteName);
@@ -6532,7 +7606,7 @@ async function sitesDomainListCommand(siteName) {
 		console.log();
 		return;
 	}
-	for (const d of res.data) console.log(`  ${pc.bold(d.hostname)}  ${formatCertStatus(d.cert_status)}`);
+	for (const d of res.data) console.log(`  ${pc.bold(d.hostname)}  ${formatDomainStatus(d)}`);
 	console.log();
 }
 async function sitesDomainRemoveCommand(hostname, options) {
@@ -6641,13 +7715,502 @@ function formatCertStatus(s) {
 	if (s === "error") return pc.red(s);
 	return pc.yellow(s);
 }
+/**
+* Render BOTH lifecycle states for a domain row. A domain is only live when
+* ownership AND cert are both `active`, so display paths must show both —
+* showing cert alone reads "live" while ownership is still pending.
+*/
+function formatDomainStatus(d) {
+	return `ownership: ${formatCertStatus(d.ownership_status)}  cert: ${formatCertStatus(d.cert_status)}`;
+}
 function sleep(ms) {
 	return new Promise((r) => setTimeout(r, ms));
 }
 //#endregion
+//#region src/commands/domains.ts
+/**
+* `amba domains ...` commands — buy a domain through Amba.
+*
+*   amba domains search <query>         find available domains + prices
+*   amba domains check <domain...>      authoritative availability + price
+*   amba domains buy <domain> --site s  buy + connect to a site
+*   amba domains list                   domains this project has purchased
+*
+* Search + check are free. `buy` surfaces the cost and requires explicit
+* confirmation (interactive y/N, or `--yes`) before it submits a purchase —
+* and the API itself only executes a real, paid registration when the
+* platform has live purchasing enabled. A registered domain is auto-
+* connected to the chosen site with no DNS setup by the customer.
+*/
+const HOSTNAME_RE = /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
+const SITE_NAME_RE = /^[a-z][a-z0-9_-]{0,49}$/;
+function confirm(question) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	return new Promise((resolve) => {
+		rl.question(question, (answer) => {
+			rl.close();
+			resolve(/^y(es)?$/i.test(answer.trim()));
+		});
+	});
+}
+function formatPrice(price, currency) {
+	if (price === null) return pc.dim("price unavailable");
+	return pc.bold(`$${price.toFixed(2)} ${currency}/yr`);
+}
+async function domainsSearchCommand(query, options = {}) {
+	const { projectId } = await loadProjectConfig();
+	const res = await searchDomainsViaApi(projectId, query, options.limit);
+	console.log();
+	if (res.data.length === 0) {
+		console.log(pc.dim(`  No suggestions for "${query}".`));
+		console.log();
+		return;
+	}
+	for (const s of res.data) {
+		const tag = s.available ? pc.green("available") : pc.red("taken");
+		const premium = s.premium ? pc.yellow(" premium") : "";
+		console.log(`  ${pc.bold(s.domain)}  ${tag}${premium}  ${formatPrice(s.price_usd, s.currency)}`);
+	}
+	console.log();
+	console.log(pc.dim("  Buy one with:  amba domains buy <domain> --site <site>"));
+	console.log();
+}
+async function domainsCheckCommand(domains) {
+	if (domains.length === 0) throw new Error("Pass at least one domain to check.");
+	if (domains.length > 20) throw new Error("At most 20 domains per check.");
+	const normalised = domains.map((d) => d.toLowerCase());
+	for (const d of normalised) if (!HOSTNAME_RE.test(d)) throw new Error(`Invalid domain '${d}'.`);
+	const { projectId } = await loadProjectConfig();
+	const res = await checkDomainsViaApi(projectId, normalised);
+	console.log();
+	for (const a of res.data) {
+		const tag = a.available ? pc.green("available") : pc.red("taken");
+		const unsupported = a.supported ? "" : pc.yellow(" (extension not supported)");
+		console.log(`  ${pc.bold(a.domain)}  ${tag}${unsupported}  ${formatPrice(a.price_usd, a.currency)}`);
+	}
+	console.log();
+}
+async function domainsBuyCommand(domain, options) {
+	const hostname = domain.toLowerCase();
+	if (!HOSTNAME_RE.test(hostname)) throw new Error(`Invalid domain '${domain}'.`);
+	if (!options.site || !SITE_NAME_RE.test(options.site)) throw new Error("--site <name> is required (the site to connect the domain to).");
+	const { projectId } = await loadProjectConfig();
+	console.log();
+	console.log(pc.bold(`  amba domains buy ${pc.cyan(hostname)}`));
+	console.log(pc.dim(`  → connect to site ${pc.cyan(options.site)}`));
+	console.log();
+	const check = await checkDomainsViaApi(projectId, [hostname]);
+	const availability = check.data.find((d) => d.domain === hostname) ?? check.data[0];
+	if (!availability) throw new Error("Could not determine availability for that domain.");
+	if (!availability.available) throw new Error(`${hostname} is not available to register. Try \`amba domains search\`.`);
+	if (!availability.supported) throw new Error(`${hostname} uses an extension we can't register yet.`);
+	if (availability.price_usd === null) throw new Error(`${hostname} can't be priced right now — try again shortly.`);
+	const price = availability.price_usd;
+	console.log(`  Price: ${formatPrice(price, availability.currency)}` + (availability.premium ? pc.yellow("  (premium)") : ""));
+	console.log(pc.dim(`  Includes: registration${options.noPrivacy ? "" : " + WHOIS privacy"}${options.noAutoRenew ? "" : " + auto-renew"}, auto-connected to ${options.site} (no DNS setup).`));
+	console.log();
+	if (!options.yes) {
+		if (!await confirm(pc.yellow(`  Buy ${hostname} for $${price.toFixed(2)} ${availability.currency}? `) + "(y/N) ")) {
+			console.log(pc.dim("  Cancelled — nothing was purchased."));
+			console.log();
+			return;
+		}
+	}
+	const r = (await purchaseDomainViaApi(projectId, {
+		domain: hostname,
+		site: options.site,
+		accept_price_usd: price,
+		confirm: true,
+		privacy: !options.noPrivacy,
+		auto_renew: !options.noAutoRenew,
+		...options.years ? { years: options.years } : {}
+	})).data;
+	if (!r.executed) {
+		if (r.gated) {
+			console.log(pc.yellow("  ! Domain purchasing is not enabled on this deployment."));
+			console.log(pc.dim("    The domain is available at the price shown; no charge was made."));
+		} else {
+			console.log(pc.yellow("  ! Purchase not completed."));
+			if (r.message) console.log(pc.dim(`    ${r.message}`));
+		}
+		console.log();
+		return;
+	}
+	console.log(pc.green("  ✓") + ` Registered ${pc.bold(hostname)}`);
+	if (r.provisioned) {
+		console.log(pc.green("  ✓") + ` Connected to ${options.site}${r.dns_autoconfigured ? " — no DNS setup needed" : ""}.`);
+		if (r.public_url) console.log(pc.green("  ✓") + ` Live at ${pc.underline(r.public_url)}`);
+		console.log(pc.dim("    The TLS certificate is issuing now (usually a minute or two)."));
+	} else if (r.message) console.log(pc.dim(`    ${r.message}`));
+	console.log();
+}
+async function domainsListCommand() {
+	const { projectId } = await loadProjectConfig();
+	const res = await listPurchasedDomainsViaApi(projectId);
+	console.log();
+	if (res.data.length === 0) {
+		console.log(pc.dim("  No domains purchased through Amba yet."));
+		console.log(pc.dim("  Buy one with: amba domains buy <domain> --site <site>"));
+		console.log();
+		return;
+	}
+	for (const d of res.data) {
+		const domain = String(d.domain ?? "");
+		const status = String(d.status ?? "");
+		const coloured = status === "active" ? pc.green(status) : status === "failed" ? pc.red(status) : pc.yellow(status);
+		console.log(`  ${pc.bold(domain)}  ${coloured}`);
+	}
+	console.log();
+}
+//#endregion
+//#region src/commands/iac.ts
+/**
+* `amba apply` / `amba diff` / `amba export` — declarative
+* infrastructure-as-code for a project's reusable configuration.
+*
+* A declarative bundle (default `amba.config.json`) captures the entities a
+* developer hand-builds once and wants to stand up identically elsewhere:
+* remote configs, collection schemas, content libraries + items, currencies,
+* achievements, streaks, challenges, leaderboards, and xp_rules. It carries
+* CONFIGURATION ONLY — no secrets, no per-user data.
+*
+* These commands wrap the platform's promotion endpoints:
+*   GET  /v1/admin/projects/:p/promotion/export
+*   POST /v1/admin/projects/:p/promotion/import   (mode=skip_existing|merge)
+*
+*   - `amba export [file]`  writes the current project's bundle to disk.
+*   - `amba apply  [file]`  POSTs the local bundle to the import endpoint and
+*                           prints a `{ created, updated, skipped }` summary
+*                           per section (the server's authoritative result).
+*   - `amba diff   [file]`  shows what `apply` WOULD change without writing.
+*                           The import route has NO server-side dry-run, so
+*                           `diff` exports the current project and computes the
+*                           created/updated/skipped per section LOCALLY.
+*/
+/** Default declarative bundle filename when no `[file]` is passed. */
+const DEFAULT_BUNDLE_FILE = "amba.config.json";
+/** The ordered list of bundle sections + their natural-key field. */
+const BUNDLE_SECTIONS = [
+	{
+		key: "remote_configs",
+		naturalKey: "key"
+	},
+	{
+		key: "collections",
+		naturalKey: "name"
+	},
+	{
+		key: "currencies",
+		naturalKey: "code"
+	},
+	{
+		key: "achievements",
+		naturalKey: "key"
+	},
+	{
+		key: "streaks",
+		naturalKey: "key"
+	},
+	{
+		key: "leaderboards",
+		naturalKey: "name"
+	},
+	{
+		key: "xp_rules",
+		naturalKey: "name"
+	},
+	{
+		key: "challenges",
+		naturalKey: "name"
+	},
+	{
+		key: "content_libraries",
+		naturalKey: "name"
+	},
+	{
+		key: "monetization",
+		naturalKey: "key"
+	}
+];
+/**
+* Read + parse a declarative bundle from disk. JSON only — we deliberately
+* don't pull in a YAML dependency the CLI doesn't already ship (the package
+* has no YAML lib), so `.yaml`/`.yml` files are rejected with a clear hint
+* rather than silently mis-parsed.
+*/
+async function readBundleFile(file) {
+	const path = resolve(file);
+	if (/\.ya?ml$/i.test(path)) throw new Error(`YAML bundles are not supported. Convert ${file} to JSON (the bundle format is plain JSON).`);
+	let raw;
+	try {
+		raw = await readFile(path, "utf-8");
+	} catch {
+		throw new Error(`Bundle file not found: ${file}. Run \`amba export\` to scaffold one from your current project.`);
+	}
+	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)}`);
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`Bundle in ${file} must be a JSON object with a \`version\` field.`);
+	const bundle = parsed;
+	if (typeof bundle["version"] !== "number") throw new Error(`Bundle in ${file} is missing a numeric \`version\` field. Re-export it with \`amba export\`.`);
+	return bundle;
+}
+/**
+* Index a section array by its natural key. Definitions missing the key (or
+* non-object entries) are skipped — they can't be matched and the server
+* will reject them on apply.
+*/
+function indexByNaturalKey(items, naturalKey) {
+	const out = /* @__PURE__ */ new Map();
+	if (!Array.isArray(items)) return out;
+	for (const item of items) {
+		if (item === null || typeof item !== "object" || Array.isArray(item)) continue;
+		const rec = item;
+		const k = rec[naturalKey];
+		if (typeof k !== "string" && typeof k !== "number") continue;
+		out.set(String(k), rec);
+	}
+	return out;
+}
+/**
+* Pure section-by-section diff of a desired bundle against the current
+* project's exported bundle. The classification MIRRORS the server's import
+* (`apps/api/src/lib/promotion-bundle.ts`) so `amba diff` agrees with what
+* `amba apply` will report:
+*   - created — natural key absent in current.
+*   - updated — natural key present AND `mode === 'merge'`. The server runs an
+*               UNCONDITIONAL update for every existing key in merge mode and
+*               increments `updated` — it does NOT compare field values, so we
+*               don't either (a local field comparison made `diff` under-report).
+*   - skipped — natural key present under `skip_existing`; OR an existing
+*               collection (always — collections are create-if-absent, never
+*               merged); OR a `remote_configs` row flagged `is_system: true`
+*               (the server always skips those before any existence check); OR
+*               a desired row with no valid natural key (can't be matched
+*               against the export, and the server import dedups by that key —
+*               so it is never a reliable create).
+*
+* Within one bundle section, the server walks rows sequentially and each
+* insert mutates the DB, so a SECOND row sharing a natural key already created
+* by an EARLIER row in the same section is seen as existing (→ skip under
+* skip_existing, update under merge) rather than created a second time. We
+* track already-seen keys per section to mirror that, so duplicate-keyed local
+* rows don't inflate the `created` total versus what `apply` does.
+*/
+function computeLocalDiff(desired, current, mode) {
+	const diff = {};
+	for (const { key, naturalKey } of BUNDLE_SECTIONS) {
+		const desiredItems = desired[key];
+		if (!Array.isArray(desiredItems) || desiredItems.length === 0) continue;
+		const currentIndex = indexByNaturalKey(current[key], naturalKey);
+		const section = {
+			created: 0,
+			updated: 0,
+			skipped: 0
+		};
+		const seen = /* @__PURE__ */ new Set();
+		for (const item of desiredItems) {
+			if (item === null || typeof item !== "object" || Array.isArray(item)) continue;
+			const rec = item;
+			if (key === "remote_configs" && rec["is_system"] === true) {
+				section.skipped++;
+				continue;
+			}
+			const k = rec[naturalKey];
+			const matchKey = typeof k === "string" || typeof k === "number" ? String(k) : null;
+			if (matchKey === null) {
+				section.skipped++;
+				continue;
+			}
+			const existing = currentIndex.has(matchKey) || seen.has(matchKey);
+			seen.add(matchKey);
+			if (!existing) {
+				section.created++;
+				continue;
+			}
+			if (key === "collections" || mode === "skip_existing") {
+				section.skipped++;
+				continue;
+			}
+			section.updated++;
+		}
+		diff[key] = section;
+	}
+	const monDiff = computeMonetizationLocalDiff(desired["monetization"], current["monetization"], mode);
+	if (monDiff) diff["monetization"] = monDiff;
+	return diff;
+}
+/**
+* Natural keys per monetization sub-collection. All key on `key` except the
+* package join, which is unique within an offering — but for diff purposes the
+* package counts roll into their owning offering, so only the four top-level
+* collections are counted here.
+*/
+const MONETIZATION_SUBSECTIONS = [
+	"entitlements",
+	"products",
+	"offerings",
+	"paywalls"
+];
+function computeMonetizationLocalDiff(desired, current, mode) {
+	if (desired === null || typeof desired !== "object" || Array.isArray(desired)) return null;
+	const desiredObj = desired;
+	const currentObj = current !== null && typeof current === "object" && !Array.isArray(current) ? current : {};
+	const section = {
+		created: 0,
+		updated: 0,
+		skipped: 0
+	};
+	let any = false;
+	for (const sub of MONETIZATION_SUBSECTIONS) {
+		const desiredItems = desiredObj[sub];
+		if (!Array.isArray(desiredItems) || desiredItems.length === 0) continue;
+		any = true;
+		const currentIndex = indexByNaturalKey(currentObj[sub], "key");
+		const seen = /* @__PURE__ */ new Set();
+		for (const item of desiredItems) {
+			if (item === null || typeof item !== "object" || Array.isArray(item)) continue;
+			const k = item["key"];
+			const matchKey = typeof k === "string" || typeof k === "number" ? String(k) : null;
+			if (matchKey === null) {
+				section.skipped++;
+				continue;
+			}
+			const existing = currentIndex.has(matchKey) || seen.has(matchKey);
+			seen.add(matchKey);
+			if (!existing) section.created++;
+			else if (mode === "skip_existing") section.skipped++;
+			else section.updated++;
+		}
+	}
+	return any ? section : null;
+}
+/** Roll a per-section diff up into grand totals across every section. */
+function summarizeDiff(diff) {
+	return Object.values(diff).reduce((acc, s) => ({
+		created: acc.created + s.created,
+		updated: acc.updated + s.updated,
+		skipped: acc.skipped + s.skipped
+	}), {
+		created: 0,
+		updated: 0,
+		skipped: 0
+	});
+}
+function renderSummary(summary, verb) {
+	let created = 0;
+	let updated = 0;
+	let skipped = 0;
+	const sections = Object.keys(summary);
+	if (sections.length === 0) console.log(pc.dim("  Nothing to " + verb + " — bundle is empty."));
+	for (const section of sections) {
+		const s = summary[section];
+		created += s.created;
+		updated += s.updated;
+		skipped += s.skipped;
+		console.log(`  ${pc.bold(section)}  ${pc.green(`${s.created} created`)} · ${pc.cyan(`${s.updated} updated`)} · ` + pc.dim(`${s.skipped} skipped`));
+	}
+	console.log();
+	console.log(pc.dim(`  Total: ${created} created · ${updated} updated · ${skipped} skipped`));
+}
+/**
+* `amba export [file]` — write the current project's declarative bundle to
+* disk so it can be checked in, diffed, and re-applied.
+*/
+async function exportConfigCommand(file = DEFAULT_BUNDLE_FILE, options = {}) {
+	const projectId = await requireProjectId(process.cwd(), options.project);
+	const path = resolve(file);
+	console.log();
+	console.log(pc.bold(`  amba export ${pc.cyan(file)}`));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	console.log(pc.dim(`  Project: ${projectId}`));
+	console.log(pc.dim("  Fetching current configuration…"));
+	const bundle = (await exportPromotionBundle(projectId)).data;
+	await writeFile(path, JSON.stringify(bundle, null, 2) + "\n", "utf-8");
+	const sectionCount = BUNDLE_SECTIONS.reduce((sum, { key }) => {
+		const v = bundle[key];
+		if (Array.isArray(v)) return sum + v.length;
+		if (key === "monetization" && v !== null && typeof v === "object") {
+			const m = v;
+			return sum + MONETIZATION_SUBSECTIONS.reduce((n, sub) => n + (Array.isArray(m[sub]) ? m[sub].length : 0), 0);
+		}
+		return sum;
+	}, 0);
+	console.log();
+	console.log(pc.green("  ✓") + ` Wrote ${pc.cyan(file)} (${sectionCount} definitions).`);
+	console.log(pc.dim("    Edit it, then ") + pc.cyan("amba diff") + pc.dim(" to preview and ") + pc.cyan("amba apply") + pc.dim(" to apply."));
+	console.log();
+}
+/**
+* `amba apply [file]` — read a local declarative bundle and POST it to the
+* import endpoint. Prints the server's authoritative `{ created, updated,
+* skipped }` per section.
+*/
+async function applyConfigCommand(file = DEFAULT_BUNDLE_FILE, options = {}) {
+	const projectId = await requireProjectId(process.cwd(), options.project);
+	const mode = options.mode ?? "skip_existing";
+	const bundle = await readBundleFile(file);
+	console.log();
+	console.log(pc.bold(`  amba apply ${pc.cyan(file)}`));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	console.log(pc.dim(`  Project: ${projectId}`));
+	console.log(pc.dim(`  Mode:    ${mode}`));
+	console.log(pc.dim("  Applying…"));
+	console.log();
+	let res;
+	try {
+		res = await importPromotionBundle(projectId, bundle, mode);
+	} catch (err) {
+		if (err instanceof ApiClientError && (err.statusCode === 400 || err.statusCode === 422)) throw new Error(`${err.message}\n  → Re-export a fresh bundle with \`amba export\` if this was hand-edited.`);
+		throw err;
+	}
+	renderSummary(res.data.summary, "apply");
+	console.log();
+}
+/**
+* `amba diff [file]` — show what `apply` WOULD change without writing.
+*
+* The import route has no server-side dry-run, so this fetches the current
+* project's exported bundle and computes the diff LOCALLY. Output mirrors the
+* `apply` summary shape so the two read identically.
+*/
+async function diffConfigCommand(file = DEFAULT_BUNDLE_FILE, options = {}) {
+	const projectId = await requireProjectId(process.cwd(), options.project);
+	const mode = options.mode ?? "skip_existing";
+	const desired = await readBundleFile(file);
+	console.log();
+	console.log(pc.bold(`  amba diff ${pc.cyan(file)}`));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	console.log(pc.dim(`  Project: ${projectId}`));
+	console.log(pc.dim(`  Mode:    ${mode}`));
+	console.log(pc.dim("  (computed locally — the import route has no server dry-run)"));
+	console.log(pc.dim("  Fetching current configuration…"));
+	console.log();
+	const diff = computeLocalDiff(desired, (await exportPromotionBundle(projectId)).data, mode);
+	renderSummary(diff, "change");
+	const totals = summarizeDiff(diff);
+	console.log();
+	if (totals.created > 0 || totals.updated > 0) console.log(pc.dim("  Run ") + pc.cyan(`amba apply ${file}`) + pc.dim(" to apply these changes."));
+	else if (totals.skipped > 0) if (mode === "skip_existing") {
+		console.log(pc.green("  ✓") + " apply would make no changes (skip_existing leaves existing entities untouched).");
+		console.log(pc.dim("    Skipped entities are NOT compared — re-run with ") + pc.cyan("--mode merge") + pc.dim(" to overwrite them, or `amba export` to see current values."));
+	} else console.log(pc.green("  ✓") + " apply would make no changes.");
+	else console.log(pc.green("  ✓") + " No changes — nothing in the bundle to apply.");
+	console.log();
+}
+//#endregion
 //#region src/index.ts
 const program = new Command();
-program.name("amba").description("amba — agent-native backend-as-a-service for mobile apps.").version("0.1.0");
+program.name("amba").description("amba — agent-native backend-as-a-service for mobile apps.").version("4.0.4");
 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({
@@ -6789,8 +8352,8 @@ program.command("schema").description("Schema export commands").command("export"
 	}));
 });
 const functions = program.command("functions").description("Customer serverless functions deployed to the edge");
-functions.command("deploy <file>").description("Bundle a function file and deploy to the dispatch namespace").option("--name <name>", "Function name (default: filename without extension)").option("--dry-run", "Bundle and report size without uploading").option("--rate-limit-window <duration>", "Rate-limit window: 60s | 5m | 1h").option("--rate-limit-max <int>", "Rate-limit max requests per window", (v) => Number.parseInt(v, 10)).option("--rate-limit-key <kind>", "Rate-limit bucket key: user_id | ip").action(async (file, opts) => {
-	await runAction(() => functionsDeployCommand(file, opts));
+functions.command("deploy <target>").description("Bundle a function (a single file OR a directory) and deploy to the dispatch namespace. A directory resolves its entry by convention (index.ts/js/mjs) or via --entry.").option("--name <name>", "Function name (default: file name without extension, or the directory leaf name)").option("--entry <file>", "Entry file when <target> is a directory (relative to it). Default: index.ts/js/mjs.").option("--dry-run", "Bundle and report size without uploading").option("--rate-limit-window <duration>", "Rate-limit window: 60s | 5m | 1h").option("--rate-limit-max <int>", "Rate-limit max requests per window", (v) => Number.parseInt(v, 10)).option("--rate-limit-key <kind>", "Rate-limit bucket key: user_id | ip").option("--public", "Deploy WITHOUT the X-Api-Key gate so external webhook senders can call it. You MUST verify the webhook signature in your handler. Default: private.").action(async (target, opts) => {
+	await runAction(() => functionsDeployCommand(target, opts));
 });
 functions.command("list").description("List active functions for the current project").action(async () => {
 	await runAction(functionsListCommand);
@@ -6807,11 +8370,12 @@ 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("--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("--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,
 		tail: opts.tail || opts.follow,
 		json: opts.json
 	}));
@@ -6827,17 +8391,17 @@ consumers.command("unbind <queue-name>").description("Remove the binding for a q
 	await runAction(() => functionsConsumersUnbindCommand(queueName));
 });
 const secrets = program.command("secrets").description("Function secrets (GCP canonical, Workers-Secret synced)");
-secrets.command("set <name> [value]").description("Write a secret to GCP Secret Manager and queue Workers Secret sync. Use --from-stdin to keep the value out of shell history.").requiredOption("--function <name>", "Function name the secret binds to. Secrets are scoped per dispatched script — there is no project-wide secret in v1; every secret belongs to exactly one function. Use the same name as the entry passed to 'amba functions deploy'.").option("--env <env>", "'dev' | 'prod' — INFORMATIONAL ONLY. Both share one secret namespace per project. Use distinct secret names (e.g. STRIPE_KEY_DEV / STRIPE_KEY_PROD) or two amba projects for real env isolation.").option("--from-stdin", "Read the secret value from stdin instead of the positional arg. Mutually exclusive with <value>. Pipe in: `echo $KEY | amba secrets set NAME --function fn --from-stdin`.").action(async (name, value, opts) => {
+secrets.command("set <name> [value]").description("Store a secret and queue its sync to your deployed function(s). Omit --function for a project-wide secret. Use --from-stdin to keep the value out of shell history.").option("--function <name>", "Function the secret binds to. OMIT this flag to set a PROJECT-WIDE secret — one value visible to every function in the project (and to any function deployed later). With it, the secret is scoped to just that function. Use the same name as the entry passed to 'amba functions deploy'. Secrets may be set before the function is deployed; the sync drains once you deploy.").option("--env <env>", "'dev' | 'prod' — INFORMATIONAL ONLY. Both share one secret namespace per project. Use distinct secret names (e.g. STRIPE_KEY_DEV / STRIPE_KEY_PROD) or two amba projects for real env isolation.").option("--from-stdin", "Read the secret value from stdin instead of the positional arg. Mutually exclusive with <value>. Pipe in: `echo $KEY | amba secrets set NAME --from-stdin`.").action(async (name, value, opts) => {
 	await runAction(() => secretsSetCommand(name, value, {
 		function: opts.function,
 		env: opts.env ?? "dev",
 		fromStdin: opts.fromStdin
 	}));
 });
-secrets.command("list").description("List secret sync status for the current project").action(async () => {
-	await runAction(secretsListCommand);
+secrets.command("list").description("List secret sync status for the current project").option("--function <name>", "Filter to secrets for a single function (avoids listing all functions at once)").action(async (opts) => {
+	await runAction(() => secretsListCommand({ function: opts.function }));
 });
-secrets.command("unset <name>").description("Remove a secret from GCP Secret Manager (Workers Secret cleared on next deploy)").requiredOption("--function <name>", "Function name the secret binds to").action(async (name, opts) => {
+secrets.command("unset <name>").description("Remove a secret (Worker binding cleared on next deploy)").option("--function <name>", "Function the secret was bound to. Omit to remove the project-wide secret of this name.").action(async (name, opts) => {
 	await runAction(() => secretsUnsetCommand(name, opts));
 });
 const billing = program.command("billing").description("Per-project subscription, headroom, and spend controls");
@@ -6874,6 +8438,60 @@ billing.command("set-ceiling <amount>").description("Cap the monthly bill at <am
 	}
 	await runAction(() => billingSetCeilingCommand({ ceiling }));
 });
+const payments = program.command("payments").description("Accept payments in your app (Amba is the rail; your app is the seller)");
+payments.command("setup").description("Create the connected payments account and print the hosted onboarding URL").option("--country <code>", "Two-letter ISO country code for the seller (e.g. US)").option("--email <email>", "Contact email for the connected account").action(async (opts) => {
+	if (opts.country && !/^[A-Za-z]{2}$/.test(opts.country)) {
+		console.log("  ✗ --country must be a two-letter ISO code (e.g. US)");
+		process.exit(1);
+	}
+	await runAction(() => paymentsSetupCommand({
+		country: opts.country ? opts.country.toUpperCase() : void 0,
+		email: opts.email
+	}));
+});
+payments.command("status").description("Show onboarding stage + whether charges/payouts are enabled").action(async () => {
+	await runAction(paymentsStatusCommand);
+});
+payments.command("set-fee <bps>").description("Set the default platform fee in basis points (250 = 2.5%), or 'off' to clear").action(async (bps) => {
+	let value;
+	if (bps.toLowerCase() === "off" || bps === "") value = null;
+	else {
+		const parsed = Number(bps);
+		if (!Number.isInteger(parsed) || parsed < 0 || parsed > 1e4) {
+			console.log("  ✗ bps must be an integer between 0 and 10000, or \"off\"");
+			process.exit(1);
+		}
+		value = parsed;
+	}
+	await runAction(() => paymentsSetFeeCommand({ bps: value }));
+});
+payments.command("balance").description("Show the connected account's available and pending balance").action(async () => {
+	await runAction(paymentsBalanceCommand);
+});
+payments.command("payouts").description("List recent payouts to the seller bank account").option("--limit <n>", "How many payouts to show (default 10)").action(async (opts) => {
+	const limit = opts.limit ? Number(opts.limit) : void 0;
+	if (limit !== void 0 && (!Number.isInteger(limit) || limit < 1 || limit > 100)) {
+		console.log("  ✗ --limit must be an integer between 1 and 100");
+		process.exit(1);
+	}
+	await runAction(() => paymentsPayoutsCommand({ limit }));
+});
+const monetization = program.command("monetization").description("Monetization control plane: plan, drift, export, adopt, and apply your subscription config as Infrastructure-as-Code.");
+monetization.command("plan").description("Preview the three-way diff (declared vs adopted vs live) + store-floor + drift").action(async () => {
+	await runAction(monetizationPlanCommand);
+});
+monetization.command("drift").description("Show managed objects changed out-of-band in the provider").action(async () => {
+	await runAction(monetizationDriftCommand);
+});
+monetization.command("export").description("Snapshot the live monetization config to a declarative bundle (stdout or --file)").option("--file <path>", "Write the bundle to this file instead of stdout").action(async (opts) => {
+	await runAction(() => monetizationExportCommand(opts));
+});
+monetization.command("adopt").description("Record the live config as the managed baseline (writes Amba state only; idempotent)").option("--all", "Adopt the entire live config").action(async (opts) => {
+	await runAction(() => monetizationAdoptCommand(opts));
+});
+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));
+});
 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) => {
 	await runAction(() => collectionsCreateCommand(name, opts));
@@ -6930,6 +8548,25 @@ sitesDomain.command("remove <hostname>").description("Detach a custom hostname (
 		zoneId: opts.zoneId
 	}));
 });
+const domains = program.command("domains").description("Buy a domain through Amba and connect it to a site");
+domains.command("search <query>").description("Search for available domains + prices (free)").option("--limit <n>", "Max suggestions (1-50, default 20)", (v) => parseInt(v, 10)).action(async (query, opts) => {
+	await runAction(() => domainsSearchCommand(query, { limit: opts.limit }));
+});
+domains.command("check <domains...>").description("Authoritative availability + price for specific domains (free)").action(async (domainArgs) => {
+	await runAction(() => domainsCheckCommand(domainArgs));
+});
+domains.command("buy <domain>").description("Buy a domain + connect it to a site (surfaces cost, asks to confirm)").requiredOption("--site <name>", "Site name to connect the domain to").option("--yes", "Skip the interactive cost confirmation prompt").option("--no-privacy", "Disable WHOIS privacy (privacy is on by default)").option("--no-auto-renew", "Disable auto-renew (on by default)").option("--years <n>", "Registration length in years (default 1)", (v) => parseInt(v, 10)).action(async (domain, opts) => {
+	await runAction(() => domainsBuyCommand(domain, {
+		site: opts.site,
+		yes: opts.yes,
+		noPrivacy: opts.privacy === false,
+		noAutoRenew: opts.autoRenew === false,
+		years: opts.years
+	}));
+});
+domains.command("list").description("List domains this project has purchased through Amba").action(async () => {
+	await runAction(domainsListCommand);
+});
 const aiProviders = program.command("ai").description("AI gateway — manage provider keys + prompts").command("providers").description("Per-project provider key registration (Anthropic, OpenAI)");
 aiProviders.command("add <provider>").description("Register an AI provider key. Plaintext stored securely server-side; a preview (first-6+last-4) is printed back. Use --from-stdin to keep the key out of shell history.").option("--key <value>", "Provider API key plaintext (alternative: --from-stdin)").option("--from-stdin", "Read the key from stdin instead of --key").action(async (provider, opts) => {
 	await runAction(() => aiProvidersAddCommand(provider, opts));
@@ -6940,6 +8577,29 @@ aiProviders.command("list").description("List registered AI providers for the cu
 aiProviders.command("delete <provider>").description("Remove a provider registration (refuses if active prompts reference it)").action(async (provider) => {
 	await runAction(() => aiProvidersDeleteCommand(provider));
 });
+function parseImportMode(raw) {
+	if (raw === void 0) return "skip_existing";
+	if (raw === "merge" || raw === "skip_existing") return raw;
+	console.log("  ✗ --mode must be \"skip_existing\" (default) or \"merge\"");
+	process.exit(1);
+}
+program.command("export [file]").description("Write the current project's declarative configuration bundle to disk (default: amba.config.json)").option("--project <id>", "Project id (overrides .env.local)").action(async (file, opts) => {
+	await runAction(() => exportConfigCommand(file, { project: opts.project }));
+});
+program.command("diff [file]").description("Show what `amba apply` WOULD change (created/updated/skipped per section) without writing. Computed locally by exporting the current project and comparing — the import route has no server dry-run.").option("--project <id>", "Project id (overrides .env.local)").option("--mode <mode>", "'skip_existing' (default) or 'merge'").action(async (file, opts) => {
+	const mode = parseImportMode(opts.mode);
+	await runAction(() => diffConfigCommand(file, {
+		project: opts.project,
+		mode
+	}));
+});
+program.command("apply [file]").description("Apply a declarative configuration bundle (default: amba.config.json) — JSON only. Prints { created, updated, skipped } per section.").option("--project <id>", "Project id (overrides .env.local)").option("--mode <mode>", "'skip_existing' (default — no-op on conflict) or 'merge' (refresh existing definitions)").action(async (file, opts) => {
+	const mode = parseImportMode(opts.mode);
+	await runAction(() => applyConfigCommand(file, {
+		project: opts.project,
+		mode
+	}));
+});
 program.parse();
 //#endregion
 export {};