@layers/amba 1.1.0 → 4.0.3

package/dist/index.js

@@ -1,16 +1,55 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import pc from "picocolors";
-import { access, chmod, mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { access, chmod, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
-import { createInterface } from "node:readline";
 import { createServer } from "node:http";
-import { homedir, tmpdir } from "node:os";
 import open from "open";
 import { createHash, randomBytes } from "node:crypto";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
 import { createWriteStream, watch } from "node:fs";
 import { spawn } from "node:child_process";
 import { build } from "esbuild";
+//#region ../shared/dist/index.js
+/**
+* Shared email-shape validation.
+*
+* Lives in `@layers/amba-shared` so the API (validates inbound emails
+* server-side before minting tokens / writing DB rows) and the CLI
+* (validates locally before round-tripping `amba claim <email>`) share
+* one canonical implementation. Previous drift between the two
+* implementations caused a real BugBot finding: a >320-char email
+* passed the CLI's loose regex but bounced server-side with
+* `INVALID_INPUT` — confusing UX.
+*
+* Intentionally permissive: validates the structural shape ("no
+* whitespace, has an `@`, has a dot in the domain part, ≤320 chars")
+* rather than running the full RFC-5321 grammar. Most callers
+* (hosted dashboard, Expo app form, CLI prompts) already validate
+* client-side; anything weirder than this check will bounce at the
+* upstream email provider anyway.
+*
+* The check exists so a 400 INVALID_INPUT surfaces before we mint a
+* token / write a DB row / fire an outbound provider request — that's
+* the load-bearing property, not "exactly RFC-compliant."
+*
+* The 320-char cap matches RFC 5321 §4.5.3.1.3 (path length, which
+* includes the email + envelope wrappers). It's the conventional
+* upper bound most validators converge on.
+*/
+function isPlausibleEmail(value) {
+	if (typeof value !== "string") return false;
+	const trimmed = value.trim();
+	if (trimmed.length === 0 || trimmed.length > 320) return false;
+	const at = trimmed.indexOf("@");
+	if (at <= 0 || at === trimmed.length - 1) return false;
+	if (/\s/.test(trimmed)) return false;
+	if (!trimmed.slice(at + 1).includes(".")) return false;
+	return true;
+}
+//#endregion
 //#region src/_internal/shared.ts
 const DEFAULT_API_URL = "https://api.amba.dev";
 const CONSOLE_URL = "https://app.amba.dev";
@@ -246,6 +285,16 @@ function setBearerOverride(token) {
 	bearerOverride = token === null || token.length === 0 ? null : token;
 }
 /**
+* Read the current bearer override without consuming it. Returns
+* `null` when no override is set. Used by commands that need to know
+* "did the operator supply a PAT for this invocation?" — e.g. `init`
+* branches on whether to bypass stored-creds and use the supplied
+* token verbatim.
+*/
+function getBearerOverride() {
+	return bearerOverride;
+}
+/**
 * Resolve the bearer token to send on the next admin API call.
 *
 * Returns the override (PAT or JWT supplied via flag/env) when set,
@@ -328,7 +377,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 {}
@@ -352,6 +401,14 @@ async function listProjects() {
 async function createProject(input) {
 	return request("POST", "/projects", input);
 }
+/**
+* PATCH /admin/projects/:projectId — update mutable fields. Server
+* silently ignores unknown keys; we filter to the documented allow-list
+* before sending so a typo at the CLI doesn't pass the wire silently.
+*/
+async function updateProject(projectId, patch) {
+	return request("PATCH", `/projects/${projectId}`, patch);
+}
 async function getProject(projectId) {
 	return request("GET", `/projects/${projectId}`);
 }
@@ -441,7 +498,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 {}
@@ -503,12 +560,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);
@@ -588,6 +645,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
@@ -621,193 +692,6 @@ async function validateApiKey(apiKey) {
 	};
 }
 //#endregion
-//#region src/context-files.ts
-/**
-* Generate AMBA.md project context file for AI agents.
-*/
-function generateAmbaMarkdown(opts) {
-	const sdkPackage = opts.framework === "expo" ? "@layers/amba-expo" : opts.framework === "react-native" ? "@layers/amba-react-native" : "@layers/amba-web";
-	const providerExample = opts.framework === "expo" ? `
-### Client Setup
-
-\`\`\`tsx
-// app/_layout.tsx
-import { useEffect } from 'react';
-import { Slot } from 'expo-router';
-import { Amba } from '@layers/amba-expo';
-
-export default function RootLayout() {
-  useEffect(() => {
-    Amba.configure({
-      projectId: process.env.EXPO_PUBLIC_AMBA_PROJECT_ID!,
-      apiKey: process.env.EXPO_PUBLIC_AMBA_API_KEY!,
-    });
-  }, []);
-
-  return <Slot />;
-}
-\`\`\`
-
-### Using the Client
-
-\`\`\`tsx
-import { Amba } from '@layers/amba-expo';
-
-export default function MyComponent() {
-  const onPress = async () => {
-    // Track an event
-    await Amba.events.track('lesson_completed', { lesson_id: '123' });
-
-    // Sign in with Apple (requires expo-apple-authentication)
-    await Amba.signInWithApple();
-
-    // Read remote config
-    const showBanner = await Amba.config.fetch();
-
-    // Email sign-in
-    await Amba.auth.signInWithEmail('user@example.com', 'hunter2');
-  };
-
-  // ...
-}
-\`\`\`` : `
-### Client Setup
-
-\`\`\`typescript
-import { Amba } from '${sdkPackage}';
-
-await Amba.configure({
-  projectId: process.env.AMBA_PROJECT_ID!,
-  apiKey: process.env.AMBA_API_KEY!,
-});
-
-// Track an event
-await Amba.events.track('page_viewed', { page: '/pricing' });
-
-// Read remote config
-const config = await Amba.config.fetch();
-
-// Email sign-in
-await Amba.auth.signInWithEmail('user@example.com', 'hunter2');
-\`\`\``;
-	return `# Amba Project Context
-
-> This file provides context about the Amba integration for AI coding agents.
-
-## Project Info
-
-| Key | Value |
-|-----|-------|
-| Project ID | \`${opts.projectId}\` |
-| Project Name | ${opts.projectName} |
-| Framework | ${opts.framework} |
-| SDK | \`${sdkPackage}\` |
-
-## Environment Variables
-
-These are configured in \`.env.local\`:
-
-- \`AMBA_PROJECT_ID\` — Your project identifier
-- \`AMBA_API_KEY\` — Client API key (safe for client-side use)
-- \`AMBA_API_URL\` — API endpoint (defaults to https://api.amba.dev)
-
-## SDK Usage
-${providerExample}
-
-## Available Features
-
-- **Push Notifications** — Send targeted push notifications to user segments
-- **Remote Config** — Key-value configuration that updates without app releases
-- **Segments** — Group users by behavior, properties, or entitlements
-- **Streaks** — Track user engagement streaks (daily, weekly)
-- **Content Libraries** — Scheduled content delivery (daily tips, weekly challenges)
-- **Entitlements** — Subscription status via RevenueCat integration
-- **Analytics** — DAU, MAU, retention, and custom event tracking
-
-## API Reference
-
-- Admin API: \`https://api.amba.dev/v1/admin\`
-- Client API: \`https://api.amba.dev/v1/client\`
-- Docs: \`https://docs.amba.dev\`
-
-## CLI Commands
-
-\`\`\`bash
-amba status          # Check project health
-amba push test       # Send a test push notification
-amba config list     # List remote config values
-amba config set <key> <value>  # Set a config value
-\`\`\`
-`;
-}
-/**
-* Generate .cursor/rules/amba.mdc Cursor rules file.
-*/
-function generateCursorRules(opts) {
-	const sdk = opts.framework === "expo" ? "@layers/amba-expo" : opts.framework === "react-native" ? "@layers/amba-react-native" : "@layers/amba-web";
-	return `---
-description: Rules for working with the Amba SDK in this project
-globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
----
-
-# Amba SDK Rules
-
-## Project Setup
-- Project ID: \`${opts.projectId}\`
-- SDK: \`${sdk}\`
-- API URL: \`https://api.amba.dev\`
-
-## Environment Variables
-- Always read Amba config from environment variables, never hardcode
-- Use \`process.env.AMBA_PROJECT_ID\` and \`process.env.AMBA_API_KEY\`
-- The .env.local file contains the project credentials
-
-## SDK Patterns
-${opts.framework === "expo" ? `- Import the \`Amba\` singleton from \`@layers/amba-expo\`
-- Call \`Amba.init({ projectId, apiKey })\` once in the root layout (inside a \`useEffect\`)
-- The Expo wrapper auto-wires AsyncStorage, push tokens, and Apple/Google sign-in
-- Use \`Amba.signInWithApple()\` / \`Amba.signInWithGoogle()\` for social auth one-liners
-- Call \`Amba.track()\` for engagement events, don't build custom analytics` : `- Initialize the Amba client once and export it as a singleton
-- Use \`Amba.client.track()\` for all engagement events
-- Use \`Amba.client.config.get()\` for remote configuration
-- Use \`Amba.client.auth\` for sign-up / sign-in flows`}
-
-## Push Notifications
-- Register push tokens via the SDK \`registerPushToken()\` method
-- Handle notification payloads using the SDK's notification listener
-- Don't implement custom push token management
-
-## Remote Config
-- Use remote config for feature flags and dynamic values
-- Always provide sensible defaults when reading config values
-- Config values are cached — don't fetch on every render
-
-## Streaks
-- Streaks are server-managed; the SDK provides read-only access
-- Use \`track()\` to record qualifying events — the server evaluates streaks
-- Show streak state from \`streak.current()\`, don't calculate manually
-
-## Best Practices
-- Don't store Amba API keys in source code or commit them to git
-- Use \`.env.local\` for local development credentials
-- The client API key (prefixed \`amb_dev_ck_\` or \`amb_live_ck_\`) is safe for client-side use
-- Server keys (prefixed \`amb_dev_sk_\` or \`amb_live_sk_\`) must stay server-side only
-`;
-}
-/**
-* Write both context files to the project directory.
-*/
-async function generateContextFiles(opts) {
-	const files = [];
-	await writeFile(join(opts.cwd, "AMBA.md"), generateAmbaMarkdown(opts), "utf-8");
-	files.push("AMBA.md");
-	const cursorDir = join(opts.cwd, ".cursor", "rules");
-	await mkdir(cursorDir, { recursive: true });
-	await writeFile(join(cursorDir, "amba.mdc"), generateCursorRules(opts), "utf-8");
-	files.push(".cursor/rules/amba.mdc");
-	return files;
-}
-//#endregion
 //#region src/sandbox.ts
 /**
 * Headless agentic sandbox bootstrap.
@@ -934,60 +818,9 @@ async function performSandboxSignup(req, options = {}) {
 		api_url: apiUrl,
 		provisioning_status: data.project.provisioning_status,
 		verify_url: data.project.verify_url,
-		email: req.email
-	};
-}
-/**
-* Write the PAT to `~/.amba/credentials.json` (chmod 0600) in a shape
-* the existing `loadCredentials` reader recognises.
-*
-* `auth.ts` was built around browser-OAuth tokens (`access_token` +
-* `refresh_token` + `expires_at`). PATs are long-lived and don't refresh
-* — but the stored-creds reader only inspects `access_token`, so we
-* write the PAT there and leave `refresh_token` empty + a far-future
-* `expires_at` so the expiry guard never fires.
-*
-* Real-credential safety: if the file already exists AND its `source`
-* is NOT `'sandbox-init'` AND `access_token` is non-empty, we treat it
-* as a real OAuth/PAT session and back it up to
-* `credentials.json.bak-<unix-ms>` before overwriting. The next
-* `--sandbox` run reuses our own previous sandbox creds without
-* back-up. This keeps the agentic flow idempotent while preventing a
-* silent clobber of a developer's real account.
-*/
-async function writeSandboxCredentials(pat, options = {}) {
-	const dir = join(options.homeDir ?? homedir(), ".amba");
-	const path = join(dir, "credentials.json");
-	await mkdir(dir, { recursive: true });
-	let backedUpTo = null;
-	try {
-		const existingRaw = await readFile(path, "utf-8");
-		const existing = JSON.parse(existingRaw);
-		const hasToken = typeof existing.access_token === "string" && existing.access_token.length > 0;
-		const isSandboxOwned = existing.source === "sandbox-init";
-		if (hasToken && !isSandboxOwned) {
-			backedUpTo = `${path}.bak-${Date.now()}`;
-			await writeFile(backedUpTo, existingRaw, "utf-8");
-			try {
-				await chmod(backedUpTo, 384);
-			} catch {}
-		}
-	} catch (err) {
-		if (!isEnoent(err)) {}
-	}
-	const payload = {
-		access_token: pat,
-		refresh_token: "",
-		expires_at: (/* @__PURE__ */ new Date("2099-12-31T00:00:00.000Z")).toISOString(),
-		source: "sandbox-init"
-	};
-	await writeFile(path, JSON.stringify(payload, null, 2), "utf-8");
-	try {
-		await chmod(path, 384);
-	} catch {}
-	return {
-		path,
-		backedUpTo
+		email: req.email,
+		developer_id: data.developer?.id ?? "",
+		developer_name: data.developer?.name
 	};
 }
 /**
@@ -996,23 +829,30 @@ async function writeSandboxCredentials(pat, options = {}) {
 * Mirrors the `init` interactive flow exactly so the existing env-read
 * conventions in the SDKs and CLI commands keep working. The merge
 * logic: if the file already exists and contains an `AMBA_PROJECT_ID`
-* line we replace the three Amba lines in place; otherwise we append a
+* line we replace the Amba lines in place; otherwise we append a
 * fresh stanza.
+*
+* `serverKey` is optional — pass it on the new two-scope credential
+* model where init mints both client+server. Pre-existing AMBA_SERVER_KEY
+* lines are refreshed when a new value is provided and removed when
+* serverKey is null AND no prior line existed (no-op on second case).
 */
-async function writeSandboxEnvLocal(cwd, projectId, clientKey, apiUrl) {
+async function writeSandboxEnvLocal(cwd, projectId, clientKey, apiUrl, serverKey) {
 	const envPath = join(cwd, ".env.local");
-	const stanza = [
+	const stanzaLines = [
 		"# Amba SDK configuration (sandbox tier)",
 		`AMBA_PROJECT_ID=${projectId}`,
-		`AMBA_CLIENT_KEY=${clientKey}`,
-		`AMBA_API_URL=${apiUrl}`,
-		""
-	].join("\n");
+		`AMBA_CLIENT_KEY=${clientKey}`
+	];
+	if (serverKey) stanzaLines.push(`AMBA_SERVER_KEY=${serverKey}`);
+	stanzaLines.push(`AMBA_API_URL=${apiUrl}`);
+	stanzaLines.push("");
+	const stanza = stanzaLines.join("\n");
 	let existing = "";
 	try {
 		existing = await readFile(envPath, "utf-8");
 	} catch (err) {
-		if (!isEnoent(err)) throw err;
+		if (!isEnoent$1(err)) throw err;
 	}
 	if (existing.length === 0) {
 		await writeFile(envPath, stanza, "utf-8");
@@ -1030,6 +870,14 @@ async function writeSandboxEnvLocal(cwd, projectId, clientKey, apiUrl) {
 		} else if (hadApiKey) updated = updated.replace(/^AMBA_API_KEY=.*/m, () => `AMBA_CLIENT_KEY=${clientKey}`);
 		else if (hadClientKey) updated = updated.replace(/^AMBA_CLIENT_KEY=.*/m, () => `AMBA_CLIENT_KEY=${clientKey}`);
 		else updated += (updated.endsWith("\n") ? "" : "\n") + `AMBA_CLIENT_KEY=${clientKey}\n`;
+		if (serverKey) if (/^AMBA_SERVER_KEY=/m.test(updated)) updated = updated.replace(/^AMBA_SERVER_KEY=.*/m, () => `AMBA_SERVER_KEY=${serverKey}`);
+		else {
+			const clientKeyMatch = updated.match(/^AMBA_CLIENT_KEY=.*\n?/m);
+			if (clientKeyMatch) {
+				const insertAt = (clientKeyMatch.index ?? 0) + clientKeyMatch[0].length;
+				updated = updated.slice(0, insertAt) + `AMBA_SERVER_KEY=${serverKey}\n` + updated.slice(insertAt);
+			} else updated += (updated.endsWith("\n") ? "" : "\n") + `AMBA_SERVER_KEY=${serverKey}\n`;
+		}
 		if (!/^AMBA_API_URL=/m.test(updated)) updated += (updated.endsWith("\n") ? "" : "\n") + `AMBA_API_URL=${apiUrl}\n`;
 		await writeFile(envPath, updated, "utf-8");
 		return envPath;
@@ -1069,8 +917,7 @@ without a credit card or email verification.
 
 The credentials live in **\`.env.local\`** (\`AMBA_PROJECT_ID\`,
 \`AMBA_CLIENT_KEY\`, \`AMBA_API_URL\`) — gitignored by convention. Your
-Personal Access Token is stored in \`~/.amba/credentials.json\` and was
-written into every MCP client config we could detect.
+Personal Access Token is stored in \`~/.amba/credentials.json\`.
 
 ## SDK quickstart
 
@@ -1095,10 +942,11 @@ await Amba.events.track('app_opened');
 
 ## Upgrade past sandbox
 
-The account is unverified. To upgrade to the Free tier (and stop being
-capped at 100 MAU / 10 MB DB), claim the email on the account:
-
-${ctx.verifyUrl ? `1. Open ${ctx.verifyUrl}\n2. Change the email on the developer record to one you control via [app.amba.dev](https://app.amba.dev/settings).` : `1. Open [app.amba.dev](https://app.amba.dev) and request a password reset for \`${ctx.email}\` — the sandbox password was random and isn't recoverable.\n2. Change the email on the developer record to one you control.`}
+This account uses an auto-generated email (\`${ctx.email}\`). Run
+\`amba claim me@example.com\` to bind it to a real address — you'll get
+a one-click link in your inbox that promotes the project to the Free
+tier (1,000 MAU, 500 MB DB) and lets you sign in from a browser if you
+ever need to.
 
 ## Useful commands
 
@@ -1129,42 +977,6 @@ function buildAmbaMcpEntry(pat) {
 	};
 }
 /**
-* Map an MCP config file path back to its client family. Returns null
-* for paths that don't match any known config location — defensive
-* against future additions to `mcpClientTargets`.
-*
-* The match is on path tail rather than full equality so the cwd /
-* homedir-injected variants both classify correctly. We deliberately
-* accept both global and project-local Claude Code paths
-* (`.claude.json` and `.mcp.json`) as 'claude-code'.
-*/
-function classifyMcpPath(path) {
-	if (path.endsWith(".claude.json") || path.endsWith(".mcp.json")) return "claude-code";
-	if (path.includes(`/.cursor/`) || path.includes(`\\.cursor\\`)) return "cursor";
-	if (path.includes("/windsurf/mcp_config.json") || path.includes("\\windsurf\\mcp_config.json")) return "windsurf";
-	return null;
-}
-/**
-* Reduce a list of written-config paths to the set of unique client
-* families they belong to. Order: claude-code, cursor, windsurf (so
-* the done-message renders consistently). Skips unclassified paths
-* silently.
-*/
-function clientKindsFromPaths(paths) {
-	const present = /* @__PURE__ */ new Set();
-	for (const p of paths) {
-		const kind = classifyMcpPath(p);
-		if (kind) present.add(kind);
-	}
-	const ordered = [];
-	for (const k of [
-		"claude-code",
-		"cursor",
-		"windsurf"
-	]) if (present.has(k)) ordered.push(k);
-	return ordered;
-}
-/**
 * The list of MCP client config files we probe. Order matters only for
 * the printed report.
 *
@@ -1231,7 +1043,7 @@ async function mergeMcpConfigFile(target, pat) {
 		if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) existing = parsed;
 		else throw new Error(`Existing config at ${target.path} is not a JSON object`);
 	} catch (err) {
-		if (isEnoent(err)) {
+		if (isEnoent$1(err)) {
 			if (!target.scaffoldIfMissing) return {
 				path: null,
 				backedUpTo: null
@@ -1300,7 +1112,7 @@ async function fileExists$1(path) {
 		return false;
 	}
 }
-function isEnoent(err) {
+function isEnoent$1(err) {
 	return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
 }
 /**
@@ -1313,21 +1125,1254 @@ function formatManualMcpSnippet(pat) {
 	return JSON.stringify({ mcpServers: { amba: buildAmbaMcpEntry(pat) } }, null, 2);
 }
 //#endregion
-//#region ../mcp/dist/expo-build-prompt.js
+//#region src/credentials.ts
 /**
-* Canonical Amba Expo build prompt — markdown body (no MDX frontmatter).
+* Two-scope credential model for `amba init`.
 *
-* Source of truth for three customer-facing surfaces:
+* Identity is **developer-scoped** (one machine identity, persisted in
+* `~/.amba/credentials.json`). State is **project-scoped** (one per
+* project directory, persisted in `<cwd>/.amba/project.json`).
 *
-*   1. The published docs page at
-*      `https://docs.amba.dev/docs/prompts/expo-build` — the MDX file at
-*      `apps/docs/content/docs/prompts/expo-build.mdx` ships the same
-*      body wrapped in fumadocs frontmatter.
-*   2. The MCP resource `amba://prompts/expo-build` registered by
-*      `registerAllResources()` in `./index.ts` and exposed by the
-*      hosted MCP server at `mcp.amba.dev`.
-*   3. The inlined snapshot baked into the `/amba-build` Claude Code
-*      skill by `amba init --sandbox` (see `packages/cli/src/skills.ts`).
+* One Amba account can own N projects. Running `amba init` in five
+* different folders under one identity yields one developer row + five
+* project rows — exactly the model `apps/console` and the API enforce.
+*
+* Backward compatibility
+* ----------------------
+* The legacy `~/.amba/credentials.json` (browser-OAuth era) carried
+* `{ access_token, refresh_token, expires_at }`. We read both shapes —
+* a missing `version` key signals legacy and triggers a one-shot
+* in-place upgrade after the first successful `developer_me` verify.
+*
+* Idempotency
+* -----------
+* `ensureDeveloperIdentity` + `ensureProjectForCwd` are the two entry
+* points. Both are safe to call on every `amba init` run:
+*   - identity: load → verify → upgrade-or-keep; only signs up if no
+*     verified PAT exists anywhere.
+*   - project: load `<cwd>/.amba/project.json` → verify the
+*     `project_id` still belongs to the current developer; if missing
+*     or stale, mint a new project under the dev's identity.
+*/
+function developerCredentialsPath(homeDir) {
+	return join(homeDir ?? homedir(), ".amba", "credentials.json");
+}
+function projectCredentialsPath(cwd) {
+	return join(cwd, ".amba", "project.json");
+}
+/**
+* Read `~/.amba/credentials.json`. Returns null when the file is
+* missing, malformed, or empty. Handles both new (versioned) and
+* legacy shapes — legacy returns `version: 1` after migration but
+* with `source: 'legacy'` so callers can tell.
+*
+* Does NOT verify the PAT against the API. Caller must follow up
+* with `verifyPat` before trusting the identity.
+*/
+async function loadDeveloperCredentials(options = {}) {
+	const path = developerCredentialsPath(options.homeDir);
+	let raw;
+	try {
+		raw = await readFile(path, "utf-8");
+	} catch (err) {
+		if (isEnoent(err)) return null;
+		throw err;
+	}
+	if (raw.trim().length === 0) return null;
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+	const obj = parsed;
+	if (obj["version"] === 1) {
+		const v = obj;
+		if (typeof v["pat"] !== "string" || v["pat"].length === 0) return null;
+		return {
+			version: 1,
+			developer_id: typeof v["developer_id"] === "string" ? v["developer_id"] : null,
+			email: typeof v["email"] === "string" ? v["email"] : "unknown",
+			pat: v["pat"],
+			api_url: typeof v["api_url"] === "string" ? v["api_url"] : DEFAULT_API_URL,
+			source: normalizeSource(v["source"]),
+			created_at: typeof v["created_at"] === "string" ? v["created_at"] : (/* @__PURE__ */ new Date()).toISOString(),
+			access_token: v["pat"],
+			refresh_token: "",
+			expires_at: typeof v["expires_at"] === "string" ? v["expires_at"] : (/* @__PURE__ */ new Date("2099-12-31T00:00:00.000Z")).toISOString()
+		};
+	}
+	const accessToken = obj["access_token"];
+	if (typeof accessToken !== "string" || accessToken.length === 0) return null;
+	const onDiskSource = normalizeSource(obj["source"]);
+	return {
+		version: 1,
+		developer_id: null,
+		email: "unknown",
+		pat: accessToken,
+		api_url: DEFAULT_API_URL,
+		source: typeof obj["source"] === "string" ? onDiskSource : "legacy",
+		created_at: (/* @__PURE__ */ new Date()).toISOString(),
+		access_token: accessToken,
+		refresh_token: "",
+		expires_at: typeof obj["expires_at"] === "string" ? obj["expires_at"] : (/* @__PURE__ */ new Date("2099-12-31T00:00:00.000Z")).toISOString()
+	};
+}
+function normalizeSource(value) {
+	if (value === "sandbox-init" || value === "browser-auth" || value === "manual" || value === "legacy") return value;
+	return "manual";
+}
+/**
+* Atomically write developer credentials to `~/.amba/credentials.json`
+* with mode 0600. Writes to a sibling `.tmp` first and renames into
+* place so a crash mid-write doesn't leave the file empty.
+*
+* Backs up an existing file when its `source` is not one of the
+* managed sources OR when the existing PAT differs from the one being
+* written. The backup goes to `credentials.json.bak-<unix-ms>`.
+*/
+async function writeDeveloperCredentials(creds, options = {}) {
+	const path = developerCredentialsPath(options.homeDir);
+	await mkdir(join(options.homeDir ?? homedir(), ".amba"), { recursive: true });
+	let backedUpTo = null;
+	try {
+		const existingRaw = await readFile(path, "utf-8");
+		const existing = JSON.parse(existingRaw);
+		const existingToken = typeof existing.pat === "string" && existing.pat.length > 0 ? existing.pat : typeof existing.access_token === "string" ? existing.access_token : "";
+		if (existingToken.length > 0 && existingToken !== creds.pat) {
+			backedUpTo = `${path}.bak-${Date.now()}`;
+			await writeFile(backedUpTo, existingRaw, "utf-8");
+			try {
+				await chmod(backedUpTo, 384);
+			} catch {}
+		}
+	} catch {}
+	const tmpPath = `${path}.tmp-${Date.now()}`;
+	await writeFile(tmpPath, JSON.stringify(creds, null, 2), "utf-8");
+	try {
+		await chmod(tmpPath, 384);
+	} catch {}
+	await rename(tmpPath, path);
+	return {
+		path,
+		backedUpTo
+	};
+}
+async function loadProjectCredentials(cwd) {
+	const path = projectCredentialsPath(cwd);
+	let raw;
+	try {
+		raw = await readFile(path, "utf-8");
+	} catch (err) {
+		if (isEnoent(err)) return null;
+		throw err;
+	}
+	if (raw.trim().length === 0) return null;
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+	const obj = parsed;
+	if (obj["version"] !== 1) return null;
+	if (typeof obj["project_id"] !== "string" || obj["project_id"].length === 0) return null;
+	if (typeof obj["client_key"] !== "string" || obj["client_key"].length === 0) return null;
+	return {
+		version: 1,
+		project_id: obj["project_id"],
+		project_name: typeof obj["project_name"] === "string" ? obj["project_name"] : "unknown",
+		environment: obj["environment"] === "production" ? "production" : "development",
+		client_key: obj["client_key"],
+		server_key: typeof obj["server_key"] === "string" && obj["server_key"].length > 0 ? obj["server_key"] : null,
+		api_url: typeof obj["api_url"] === "string" ? obj["api_url"] : DEFAULT_API_URL,
+		wired_surfaces: Array.isArray(obj["wired_surfaces"]) ? obj["wired_surfaces"].filter((s) => typeof s === "string") : [],
+		created_at: typeof obj["created_at"] === "string" ? obj["created_at"] : (/* @__PURE__ */ new Date()).toISOString(),
+		updated_at: typeof obj["updated_at"] === "string" ? obj["updated_at"] : (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+async function writeProjectCredentials(cwd, creds) {
+	const path = projectCredentialsPath(cwd);
+	await mkdir(join(cwd, ".amba"), { recursive: true });
+	const tmpPath = `${path}.tmp-${Date.now()}`;
+	await writeFile(tmpPath, JSON.stringify(creds, null, 2), "utf-8");
+	try {
+		await chmod(tmpPath, 384);
+	} catch {}
+	await rename(tmpPath, path);
+	return path;
+}
+/**
+* Verify a PAT by calling `GET /v1/auth/developer/me`. Returns the
+* developer row on success, `null` on 401/403/404 (PAT invalid or
+* developer not found), or throws on network / 5xx errors.
+*
+* This is the single source of truth for "do we have a working
+* identity." Used at the top of every init run.
+*/
+async function verifyPat(pat, options = {}) {
+	const apiUrl = options.apiUrl ?? process.env["AMBA_API_URL"] ?? "https://api.amba.dev";
+	const res = await (options.fetchImpl ?? fetch)(`${apiUrl}/v1/auth/developer/me`, {
+		method: "GET",
+		headers: {
+			Authorization: `Bearer ${pat}`,
+			"User-Agent": "amba-cli/credentials"
+		}
+	});
+	if (res.status === 401 || res.status === 403 || res.status === 404) return null;
+	if (!res.ok) throw new Error(`developer/me verify returned ${res.status} ${res.statusText}`);
+	let raw;
+	try {
+		raw = await res.json();
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		throw new Error(`developer/me returned 2xx but body was not JSON: ${reason}`);
+	}
+	if (!raw.data?.id) return null;
+	return {
+		id: raw.data.id,
+		email: raw.data.email ?? "unknown",
+		name: raw.data.name
+	};
+}
+/**
+* Ensure the machine has a verified Amba developer identity.
+*
+* Decision tree:
+*   1. Load existing `~/.amba/credentials.json`.
+*   2. If found, verify the PAT via `developer/me`.
+*      - Valid → migrate shape if legacy, return.
+*      - Invalid → fall through to signup (unless `signupOnMissing: false`).
+*   3. No creds (or invalid) + `signupOnMissing !== false` → call
+*      `performSandboxSignup` with generated email/password, write the
+*      result, return.
+*   4. No creds + `signupOnMissing === false` → throw.
+*/
+async function ensureDeveloperIdentity(options = {}) {
+	const apiUrl = options.apiUrl ?? process.env["AMBA_API_URL"] ?? "https://api.amba.dev";
+	const fetchImpl = options.fetchImpl ?? fetch;
+	const existing = await loadDeveloperCredentials({ homeDir: options.homeDir });
+	if (existing) {
+		let verified = null;
+		try {
+			verified = await verifyPat(existing.pat, {
+				apiUrl,
+				fetchImpl
+			});
+		} catch {
+			throw new Error(`Could not verify existing Amba credentials at ${developerCredentialsPath(options.homeDir)} — check your network and try again.`);
+		}
+		if (verified) {
+			if (existing.source === "legacy" || existing.developer_id !== verified.id || existing.email !== verified.email) {
+				const upgraded = {
+					...existing,
+					version: 1,
+					developer_id: verified.id,
+					email: verified.email,
+					api_url: apiUrl,
+					source: existing.source === "legacy" ? "manual" : existing.source,
+					created_at: existing.created_at
+				};
+				const write = await writeDeveloperCredentials(upgraded, { homeDir: options.homeDir });
+				return {
+					credentials: upgraded,
+					newlySignedUp: false,
+					developer: verified,
+					firstProject: null,
+					credentialsBackedUpTo: write.backedUpTo,
+					credentialsPath: write.path
+				};
+			}
+			return {
+				credentials: existing,
+				newlySignedUp: false,
+				developer: verified,
+				firstProject: null,
+				credentialsBackedUpTo: null,
+				credentialsPath: developerCredentialsPath(options.homeDir)
+			};
+		}
+	}
+	if (options.signupOnMissing === false) throw new Error(`No verified Amba identity at ${developerCredentialsPath(options.homeDir)} and signup-on-missing is disabled. Run \`amba login\` to authenticate.`);
+	const signup = await performSandboxSignup({
+		email: options.sandboxEmail?.trim() || generateSandboxEmail(),
+		password: generateSandboxPassword()
+	}, {
+		apiUrl,
+		fetchImpl
+	});
+	const developerId = signup.developer_id.length > 0 ? signup.developer_id : null;
+	const developer = {
+		id: developerId ?? "pending",
+		email: signup.email,
+		...signup.developer_name ? { name: signup.developer_name } : {}
+	};
+	const newCreds = {
+		version: 1,
+		developer_id: developerId,
+		email: signup.email,
+		pat: signup.pat,
+		api_url: signup.api_url,
+		source: "sandbox-init",
+		created_at: (/* @__PURE__ */ new Date()).toISOString(),
+		access_token: signup.pat,
+		refresh_token: "",
+		expires_at: (/* @__PURE__ */ new Date("2099-12-31T00:00:00.000Z")).toISOString()
+	};
+	const write = await writeDeveloperCredentials(newCreds, { homeDir: options.homeDir });
+	return {
+		credentials: newCreds,
+		newlySignedUp: true,
+		developer,
+		firstProject: {
+			project_id: signup.project_id,
+			client_key: signup.client_key,
+			server_key: signup.server_key ?? null,
+			provisioning_status: signup.provisioning_status,
+			verify_url: signup.verify_url
+		},
+		credentialsBackedUpTo: write.backedUpTo,
+		credentialsPath: write.path
+	};
+}
+/**
+* Ensure the current working directory is attached to an Amba project.
+*
+* Decision tree:
+*   1. Load existing `<cwd>/.amba/project.json`.
+*      - Present → return (no API call; we trust the file's metadata
+*        until something downstream fails, at which point the caller
+*        re-keys).
+*   2. Missing + `signupFirstProject` provided → use those keys, write
+*      `<cwd>/.amba/project.json`, return (newlyCreated=true).
+*   3. Missing + no signup payload + `attachToProjectId` provided →
+*      mint a new client+server key under that project, write the
+*      file, return.
+*   4. Missing + no signup payload + no attach → call
+*      `createProject({ name, environment })` under the dev's PAT,
+*      mint both keys, write the file, return.
+*/
+async function ensureProjectForCwd(cwd, options) {
+	const existing = await loadProjectCredentials(cwd);
+	if (existing) return {
+		credentials: existing,
+		newlyCreated: false
+	};
+	const environment = options.environment ?? "development";
+	const apiUrl = process.env["AMBA_API_URL"] ?? "https://api.amba.dev";
+	setBearerOverride(options.pat);
+	if (options.signupFirstProject) {
+		const creds = {
+			version: 1,
+			project_id: options.signupFirstProject.project_id,
+			project_name: options.defaultName ?? (basename(cwd) || "amba-sandbox"),
+			environment,
+			client_key: options.signupFirstProject.client_key,
+			server_key: options.signupFirstProject.server_key,
+			api_url: apiUrl,
+			wired_surfaces: [],
+			created_at: (/* @__PURE__ */ new Date()).toISOString(),
+			updated_at: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		await writeProjectCredentials(cwd, creds);
+		return {
+			credentials: creds,
+			newlyCreated: true
+		};
+	}
+	if (options.attachToProjectId) {
+		const { clientKey, serverKey } = await mintProjectKeyPair(options.attachToProjectId, environment);
+		const creds = {
+			version: 1,
+			project_id: options.attachToProjectId,
+			project_name: options.defaultName ?? (basename(cwd) || "amba-project"),
+			environment,
+			client_key: clientKey,
+			server_key: serverKey,
+			api_url: apiUrl,
+			wired_surfaces: [],
+			created_at: (/* @__PURE__ */ new Date()).toISOString(),
+			updated_at: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		await writeProjectCredentials(cwd, creds);
+		return {
+			credentials: creds,
+			newlyCreated: true
+		};
+	}
+	const uniqueName = await uniqueProjectName(sanitizeProjectName(options.defaultName ?? (basename(cwd) || "amba-project")));
+	const project = await createProject({
+		name: uniqueName,
+		environment
+	});
+	const { clientKey, serverKey } = await mintProjectKeyPair(project.data.id, environment);
+	const creds = {
+		version: 1,
+		project_id: project.data.id,
+		project_name: uniqueName,
+		environment,
+		client_key: clientKey,
+		server_key: serverKey,
+		api_url: apiUrl,
+		wired_surfaces: [],
+		created_at: (/* @__PURE__ */ new Date()).toISOString(),
+		updated_at: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	await writeProjectCredentials(cwd, creds);
+	return {
+		credentials: creds,
+		newlyCreated: true
+	};
+}
+async function mintProjectKeyPair(projectId, environment) {
+	const clientRes = await createApiKey(projectId, "client", environment);
+	const serverRes = await createApiKey(projectId, "server", environment);
+	return {
+		clientKey: clientRes.data.key,
+		serverKey: serverRes.data.key
+	};
+}
+/**
+* Pick a project name unique against the developer's current set.
+*
+* Multi-folder reality: a developer running `amba init` from
+* `~/code/fitness-app` then `~/code/fitness-app-v2` will get names
+* derived from different basenames already; the disambiguation is
+* only for the rare case where two folders end up with the same
+* basename (e.g. `~/work/fitness` and `~/personal/fitness`).
+*/
+async function uniqueProjectName(base) {
+	let existing;
+	try {
+		existing = (await listProjects()).data.map((p) => p.name);
+	} catch {
+		return base;
+	}
+	if (!existing.includes(base)) return base;
+	for (let i = 2; i < 100; i += 1) {
+		const candidate = `${base}-${i}`;
+		if (!existing.includes(candidate)) return candidate;
+	}
+	return `${base}-${Date.now().toString(36)}`;
+}
+/**
+* Sanitize a candidate project name. The control-plane enforces
+* `^[a-zA-Z0-9-_]{1,64}$` (see `apps/api/src/routes/projects.ts`); the
+* basename of a project folder often contains spaces or dots. We
+* collapse runs of non-allowed chars to `-`, trim outer dashes, and
+* truncate to 64.
+*/
+function sanitizeProjectName(input) {
+	const collapsed = input.normalize("NFKD").replace(/[^a-zA-Z0-9-_]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
+	return collapsed.length > 0 ? collapsed : "amba-project";
+}
+function isEnoent(err) {
+	return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+}
+//#endregion
+//#region src/commands/claim.ts
+/**
+* `amba claim <email>` — bind a sandbox account to a real email address
+* via a one-click magic link.
+*
+* Sandbox accounts are minted with an auto-generated address
+* (`sandbox-<epoch>-<nonce>@layers.com`) and remain capped at 100 MAU /
+* 10 MB DB until the developer claims a real email. This command POSTs
+* the target email to `/v1/auth/developer/claim` under the developer's
+* stored PAT; the backend emails a single-use magic link that — when
+* clicked — updates the developer row and flips the project tier from
+* `sandbox` to `verified_free` (1,000 MAU, 500 MB DB).
+*
+* Wire shape:
+*
+*   POST {AMBA_API_URL}/v1/auth/developer/claim
+*   Authorization: Bearer {pat}
+*   Content-Type: application/json
+*   Body: { "email": "<target-email>" }
+*
+* Success: HTTP 200 `{ "ok": true }`
+* Errors:  HTTP 400 INVALID_INPUT
+*          HTTP 409 EMAIL_TAKEN     — that address already owns another account
+*          HTTP 409 ALREADY_CLAIMED — this account is already verified
+*          HTTP 429                  — rate-limited
+*          HTTP 5xx                  — surface verbatim with code + message
+*
+* UX contract: a single ✓ line + a hint that the link expires in 15
+* minutes. No copy-paste tokens, no follow-up commands. The click in
+* the email is the whole flow.
+*/
+async function claimCommand(email, options = {}) {
+	console.log();
+	console.log(pc.bold("  amba claim"));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	const trimmed = email.trim();
+	if (!isPlausibleEmail(trimmed)) {
+		console.log(pc.red("  ✗") + " Invalid email format.");
+		console.log();
+		process.exit(1);
+	}
+	let pat = options.pat ?? null;
+	if (!pat) try {
+		const dev = await loadDeveloperCredentials({ homeDir: options.homeDir });
+		if (dev?.pat) pat = dev.pat;
+	} catch {}
+	if (!pat) {
+		console.log(pc.red("  ✗") + " No Amba credentials found. Run " + pc.bold("amba init") + " first.");
+		console.log();
+		process.exit(1);
+	}
+	const url = `${options.apiUrl?.trim() || process.env["AMBA_API_URL"]?.trim() || "https://api.amba.dev"}/v1/auth/developer/claim`;
+	const fetchImpl = options.fetchImpl ?? fetch;
+	let res;
+	try {
+		res = await fetchImpl(url, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${pat}`,
+				"Content-Type": "application/json",
+				"User-Agent": "amba-cli/claim"
+			},
+			body: JSON.stringify({ email: trimmed })
+		});
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		console.log(pc.red("  ✗") + ` Could not reach Amba: ${reason}`);
+		console.log();
+		process.exit(1);
+	}
+	if (res.status === 200) {
+		try {
+			await res.text();
+		} catch {}
+		console.log(pc.green("  ✓") + ` Check ${pc.bold(trimmed)} for a one-click link.`);
+		console.log(pc.dim("    (Link expires in 15 minutes.)"));
+		console.log();
+		return;
+	}
+	let errCode = "";
+	let errMessage = "";
+	try {
+		const body = await res.json();
+		errCode = body.error?.code ?? "";
+		errMessage = body.error?.message ?? "";
+	} catch {}
+	if (res.status === 400 && errCode === "INVALID_INPUT") {
+		console.log(pc.red("  ✗") + " Invalid email format.");
+		console.log();
+		process.exit(1);
+	}
+	if (res.status === 409 && errCode === "EMAIL_TAKEN") {
+		console.log(pc.red("  ✗") + ` That email is already on another Amba account. If it's yours, sign in via ` + pc.bold("amba login") + " or reach out to support@layers.com.");
+		console.log();
+		process.exit(1);
+	}
+	if (res.status === 409 && errCode === "ALREADY_CLAIMED") {
+		console.log(pc.red("  ✗") + " This account is already verified.");
+		console.log();
+		process.exit(1);
+	}
+	if (res.status === 429) {
+		console.log(pc.red("  ✗") + " Too many claim attempts. Try again in a minute.");
+		console.log();
+		process.exit(1);
+	}
+	const codeLabel = errCode || `HTTP_${res.status}`;
+	const messageLabel = errMessage || res.statusText || "Request failed";
+	console.log(pc.red("  ✗") + ` ${codeLabel}: ${messageLabel}`);
+	console.log();
+	process.exit(1);
+}
+//#endregion
+//#region src/context-files.ts
+/**
+* Generate AMBA.md project context file for AI agents.
+*/
+function generateAmbaMarkdown(opts) {
+	const sdkPackage = opts.framework === "expo" ? "@layers/amba-expo" : opts.framework === "react-native" ? "@layers/amba-react-native" : "@layers/amba-web";
+	const providerExample = opts.framework === "expo" ? `
+### Client Setup
+
+\`\`\`tsx
+// app/_layout.tsx
+import { useEffect } from 'react';
+import { Slot } from 'expo-router';
+import { Amba } from '@layers/amba-expo';
+
+export default function RootLayout() {
+  useEffect(() => {
+    Amba.configure({
+      projectId: process.env.EXPO_PUBLIC_AMBA_PROJECT_ID!,
+      apiKey: process.env.EXPO_PUBLIC_AMBA_API_KEY!,
+    });
+  }, []);
+
+  return <Slot />;
+}
+\`\`\`
+
+### Using the Client
+
+\`\`\`tsx
+import { Amba } from '@layers/amba-expo';
+
+export default function MyComponent() {
+  const onPress = async () => {
+    // Track an event
+    await Amba.events.track('lesson_completed', { lesson_id: '123' });
+
+    // Sign in with Apple (requires expo-apple-authentication)
+    await Amba.signInWithApple();
+
+    // Read remote config
+    const showBanner = await Amba.config.fetch();
+
+    // Email sign-in
+    await Amba.auth.signInWithEmail('user@example.com', 'hunter2');
+  };
+
+  // ...
+}
+\`\`\`` : `
+### Client Setup
+
+\`\`\`typescript
+import { Amba } from '${sdkPackage}';
+
+await Amba.configure({
+  projectId: process.env.AMBA_PROJECT_ID!,
+  apiKey: process.env.AMBA_API_KEY!,
+});
+
+// Track an event
+await Amba.events.track('page_viewed', { page: '/pricing' });
+
+// Read remote config
+const config = await Amba.config.fetch();
+
+// Email sign-in
+await Amba.auth.signInWithEmail('user@example.com', 'hunter2');
+\`\`\``;
+	return `# Amba Project Context
+
+> This file provides context about the Amba integration for AI coding agents.
+
+## Project Info
+
+| Key | Value |
+|-----|-------|
+| Project ID | \`${opts.projectId}\` |
+| Project Name | ${opts.projectName} |
+| Framework | ${opts.framework} |
+| SDK | \`${sdkPackage}\` |
+
+## Environment Variables
+
+These are configured in \`.env.local\`:
+
+- \`AMBA_PROJECT_ID\` — Your project identifier
+- \`AMBA_API_KEY\` — Client API key (safe for client-side use)
+- \`AMBA_API_URL\` — API endpoint (defaults to https://api.amba.dev)
+
+## SDK Usage
+${providerExample}
+
+## Available Features
+
+- **Push Notifications** — Send targeted push notifications to user segments
+- **Remote Config** — Key-value configuration that updates without app releases
+- **Segments** — Group users by behavior, properties, or entitlements
+- **Streaks** — Track user engagement streaks (daily, weekly)
+- **Content Libraries** — Scheduled content delivery (daily tips, weekly challenges)
+- **Entitlements** — Subscription status via RevenueCat integration
+- **Analytics** — DAU, MAU, retention, and custom event tracking
+
+## API Reference
+
+- Admin API: \`https://api.amba.dev/v1/admin\`
+- Client API: \`https://api.amba.dev/v1/client\`
+- Docs: \`https://docs.amba.dev\`
+
+## CLI Commands
+
+\`\`\`bash
+amba status          # Check project health
+amba push test       # Send a test push notification
+amba config list     # List remote config values
+amba config set <key> <value>  # Set a config value
+\`\`\`
+`;
+}
+/**
+* Generate .cursor/rules/amba.mdc Cursor rules file.
+*/
+function generateCursorRules(opts) {
+	const sdk = opts.framework === "expo" ? "@layers/amba-expo" : opts.framework === "react-native" ? "@layers/amba-react-native" : "@layers/amba-web";
+	return `---
+description: Rules for working with the Amba SDK in this project
+globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
+---
+
+# Amba SDK Rules
+
+## Project Setup
+- Project ID: \`${opts.projectId}\`
+- SDK: \`${sdk}\`
+- API URL: \`https://api.amba.dev\`
+
+## Environment Variables
+- Always read Amba config from environment variables, never hardcode
+- Use \`process.env.AMBA_PROJECT_ID\` and \`process.env.AMBA_API_KEY\`
+- The .env.local file contains the project credentials
+
+## SDK Patterns
+${opts.framework === "expo" ? `- Import the \`Amba\` singleton from \`@layers/amba-expo\`
+- Call \`Amba.init({ projectId, apiKey })\` once in the root layout (inside a \`useEffect\`)
+- The Expo wrapper auto-wires AsyncStorage, push tokens, and Apple/Google sign-in
+- Use \`Amba.signInWithApple()\` / \`Amba.signInWithGoogle()\` for social auth one-liners
+- Call \`Amba.track()\` for engagement events, don't build custom analytics` : `- Initialize the Amba client once and export it as a singleton
+- Use \`Amba.client.track()\` for all engagement events
+- Use \`Amba.client.config.get()\` for remote configuration
+- Use \`Amba.client.auth\` for sign-up / sign-in flows`}
+
+## Push Notifications
+- Register push tokens via the SDK \`registerPushToken()\` method
+- Handle notification payloads using the SDK's notification listener
+- Don't implement custom push token management
+
+## Remote Config
+- Use remote config for feature flags and dynamic values
+- Always provide sensible defaults when reading config values
+- Config values are cached — don't fetch on every render
+
+## Streaks
+- Streaks are server-managed; the SDK provides read-only access
+- Use \`track()\` to record qualifying events — the server evaluates streaks
+- Show streak state from \`streak.current()\`, don't calculate manually
+
+## Best Practices
+- Don't store Amba API keys in source code or commit them to git
+- Use \`.env.local\` for local development credentials
+- The client API key (prefixed \`amb_dev_ck_\` or \`amb_live_ck_\`) is safe for client-side use
+- Server keys (prefixed \`amb_dev_sk_\` or \`amb_live_sk_\`) must stay server-side only
+`;
+}
+/**
+* Write both context files to the project directory.
+*/
+async function generateContextFiles(opts) {
+	const files = [];
+	await writeFile(join(opts.cwd, "AMBA.md"), generateAmbaMarkdown(opts), "utf-8");
+	files.push("AMBA.md");
+	const cursorDir = join(opts.cwd, ".cursor", "rules");
+	await mkdir(cursorDir, { recursive: true });
+	await writeFile(join(cursorDir, "amba.mdc"), generateCursorRules(opts), "utf-8");
+	files.push(".cursor/rules/amba.mdc");
+	return files;
+}
+//#endregion
+//#region src/skill-installer.ts
+/**
+* Amba skill bundle installer.
+*
+* The bundled `skill-bundle/` directory contains `SKILL.md` plus a
+* `references/` folder with one file per Amba surface area. The skill
+* teaches the agent the classify → confirm → wire-up playbook for
+* adding Amba primitives to a developer's codebase. See
+* `packages/cli/skill-bundle/SKILL.md` for the source.
+*
+* Why ship a bundled skill (instead of `npx skills add layers/amba`):
+* the CLI run is the same install step. Bundling avoids a second
+* fetch, keeps the skill version locked to the CLI version, and means
+* `amba init` produces a fully-wired agent on offline networks too.
+*
+* Cross-agent install — we drop the same body into every detected
+* coding agent's skill directory. Agents read their own location:
+*
+*   - Claude Code:  `.claude/skills/amba/`
+*   - Cursor:       `.cursor/skills/amba/`
+*   - Codex CLI:    `.codex/skills/amba/`
+*   - Windsurf:     `.windsurf/skills/amba/`
+*
+* We also write a project-root copy at `.agents/skills/amba/` which
+* the `npx skills add ...` distribution tool reads from (and which any
+* agent that pre-registers an `.agents/skills/` lookup picks up). Five
+* locations, one body — same fan-out pattern `writeAllSetupTargets`
+* already uses for the legacy setup guide.
+*
+* Idempotency: re-running `amba init` overwrites the bundled
+* `SKILL.md` and `references/*.md` so every developer ends up on the
+* latest playbook. We back up a pre-existing `SKILL.md` to a sibling
+* `.bak-<unix-ms>` ONLY when its first frontmatter key (`name:`) is
+* not `amba` — that's the signal it was hand-authored / unrelated and
+* shouldn't be silently clobbered. Bundled Amba files are refreshed
+* without backup.
+*/
+/**
+* Resolve the bundled skill source directory.
+*
+* The bundle lives at `<package-root>/skill-bundle/` in both the
+* source tree and the published tarball (via `files[]` in
+* `package.json`). From a built `dist/commands/init.js` the path is
+* `../../skill-bundle/`. From the source tree
+* (`src/skill-installer.ts`) the path is `../skill-bundle/`. We try
+* both relative to `import.meta.url` and pick the one that exists.
+*/
+async function resolveBundleDir() {
+	const here = fileURLToPath(import.meta.url);
+	const candidates = [
+		join(dirname(here), "..", "skill-bundle"),
+		join(dirname(here), "..", "..", "skill-bundle"),
+		join(dirname(here), "..", "..", "..", "skill-bundle")
+	];
+	for (const candidate of candidates) try {
+		await access(join(candidate, "SKILL.md"));
+		return candidate;
+	} catch {}
+	throw new Error(`Amba skill bundle not found. Looked at: ${candidates.join(", ")}. This is a CLI packaging bug — please file an issue at https://github.com/layers/amba/issues.`);
+}
+/**
+* List the five install targets the CLI fans out to. Project-local
+* directories (`<cwd>/.claude/skills/amba/`, etc.) — the agent reads
+* project-local skills with priority over global ones, so this is the
+* canonical install location for a tool meant to wire up THIS project.
+*/
+function skillInstallTargets(cwd) {
+	return [
+		{
+			kind: "claude-code",
+			path: join(cwd, ".claude", "skills", "amba")
+		},
+		{
+			kind: "cursor",
+			path: join(cwd, ".cursor", "skills", "amba")
+		},
+		{
+			kind: "codex",
+			path: join(cwd, ".codex", "skills", "amba")
+		},
+		{
+			kind: "windsurf",
+			path: join(cwd, ".windsurf", "skills", "amba")
+		},
+		{
+			kind: "generic-agents",
+			path: join(cwd, ".agents", "skills", "amba")
+		}
+	];
+}
+/**
+* Copy SKILL.md + every file under references/ into the target
+* directory. Creates the directory tree if missing. Returns the list
+* of files touched and any backup paths.
+*
+* Backup rule: a pre-existing `SKILL.md` is backed up to
+* `SKILL.md.bak-<unix-ms>` ONLY when its first `name:` frontmatter
+* line is NOT `name: amba`. That's the signal it was authored by the
+* user for an unrelated purpose and shouldn't be silently overwritten.
+* Amba-owned files get refreshed without backup so developers
+* tracking the latest playbook don't accumulate junk.
+*/
+async function installSkillBundle(cwd, options = {}) {
+	const bundleDir = options.bundleDir ?? await resolveBundleDir();
+	const targets = skillInstallTargets(cwd);
+	const results = [];
+	const skillBody = await readFile(join(bundleDir, "SKILL.md"), "utf-8");
+	const referencesDir = join(bundleDir, "references");
+	let referenceEntries = [];
+	try {
+		referenceEntries = await readdir(referencesDir);
+	} catch {
+		referenceEntries = [];
+	}
+	const referenceBodies = /* @__PURE__ */ new Map();
+	for (const entry of referenceEntries) {
+		if (!entry.endsWith(".md")) continue;
+		const body = await readFile(join(referencesDir, entry), "utf-8");
+		referenceBodies.set(entry, body);
+	}
+	for (const target of targets) {
+		await mkdir(join(target.path, "references"), { recursive: true });
+		const files = [];
+		const skillPath = join(target.path, "SKILL.md");
+		const skillBackup = await backupIfForeignSkill(skillPath);
+		await writeFile(skillPath, skillBody, "utf-8");
+		files.push({
+			path: skillPath,
+			backedUpTo: skillBackup
+		});
+		for (const [name, body] of referenceBodies) {
+			const refPath = join(target.path, "references", name);
+			await writeFile(refPath, body, "utf-8");
+			files.push({
+				path: refPath,
+				backedUpTo: null
+			});
+		}
+		results.push({
+			target,
+			files
+		});
+	}
+	return results;
+}
+/**
+* If a pre-existing `SKILL.md` at `path` has a different `name:`
+* frontmatter value than `amba`, copy it to a timestamped backup and
+* return the backup path. Otherwise return null (no backup needed).
+*
+* Frontmatter parsing is intentionally cheap — just the first
+* occurrence of `^name:\s*<value>` within the leading `---` block. A
+* malformed file falls through to "back up" (safe default).
+*/
+async function backupIfForeignSkill(path) {
+	let raw;
+	try {
+		raw = await readFile(path, "utf-8");
+	} catch {
+		return null;
+	}
+	const nameMatch = raw.slice(0, 512).match(/^name:\s*([A-Za-z0-9_-]+)/m);
+	if (nameMatch && nameMatch[1] === "amba") return null;
+	const backupPath = `${path}.bak-${Date.now()}`;
+	await writeFile(backupPath, raw, "utf-8");
+	return backupPath;
+}
+/**
+* Convenience: returns the count of skill files written and the list
+* of target kinds, for the CLI's done-message summary.
+*/
+function summarizeSkillInstall(results) {
+	return {
+		totalFiles: results.reduce((sum, r) => sum + r.files.length, 0),
+		targetKinds: results.map((r) => r.target.kind)
+	};
+}
+//#endregion
+//#region ../mcp/dist/expo-build-prompt.js
+/**
+* Canonical long-form Amba setup guide — markdown body.
+*
+* Companion to the short-form `instructions` field served by the MCP
+* server's initialize response. The pointer "Full guide: amba://setup"
+* in those instructions tells the agent to fetch this resource when it
+* needs more detail than the ~1 KB summary provides.
+*
+* Consumed by:
+*
+*   - The MCP resource at `amba://setup`, registered by
+*     `registerAllResources()` in `./index.ts` and exposed by the
+*     hosted MCP server at `mcp.amba.dev`. Any client (Claude Code,
+*     Cursor, Codex, Cowork, etc.) can fetch it via `resources/read`.
+*
+* Twin: this body is the server-side mirror of
+* `packages/cli/skill-bundle/SKILL.md`, which the CLI installs locally
+* during `npx @layers/amba init`. The two surfaces target two
+* different audiences:
+*
+*   - `SKILL.md` ships to a local `.claude/skills/amba/` and assumes
+*     the agent CAN shell out (the bootstrap path can `npx @layers/amba
+*     signup`). It also writes credentials into `.env.local` + `~/.amba/`.
+*   - `AMBA_SETUP_GUIDE_MD` (this constant) is served by the hosted MCP
+*     and assumes the agent CANNOT shell out (e.g. Claude.ai web).
+*     The bootstrap path must therefore use the `amba_developer_signup`
+*     MCP tool (the only pre-auth tool the server registers).
+*
+* The playbook shape (Step 0 → Step 1 classify → Step 2 confirm →
+* Step 3 wire → Step 4 report) is identical between the two, so an
+* agent reading either ends up at the same outcome. A drift gate test
+* in `amba-setup.test.ts` asserts the structural anchors match.
+*
+* Taxonomy: the SDK capability map below is grouped under the canonical
+* 7-category taxonomy (Identity / Engagement / Gamification / Economy /
+* Social / Analytics / Infrastructure) — same shape as `categories.ts`,
+* the marketing-site feature grid, and the docs IA. Drift is caught by
+* `amba-setup.test.ts`.
+*
+* The body is plain CommonMark — no MDX, no JSX — so it renders
+* identically wherever it lands.
+*/
+const AMBA_SETUP_GUIDE_MD = `# Amba
+
+## What Amba is
+
+Amba is the backend your app calls at runtime via the SDK. The MCP tools (\`amba_*\`) are for provisioning at build time — call them as the coding agent.
+
+One Amba project = one isolated tenant database + one set of API keys + a hosted MCP at \`mcp.amba.dev\` for agent-driven provisioning. The runtime traffic goes through an SDK (\`@layers/amba-*\` on npm, \`Amba\` on SPM / Maven / pub.dev). The provisioning traffic — what you're about to do — goes through the tools listed below.
+
+Your job is to take the user from "I have an app" to "Amba is wired in and the features are real" in one pass, without 12 follow-up questions. The journey below is the standard playbook. Don't deviate without a reason.
+
+## Step 0 — Bootstrap credentials
+
+You're in an MCP client (Claude.ai web, Claude Desktop, Cursor, Windsurf, etc.) without a local CLI. The MCP server has one tool that works **without** a Bearer token: \`amba_developer_signup\`. Use it to mint a personal access token (PAT), project, and client/server keys in a single round trip — no browser, no email verification.
+
+Call:
+
+\`\`\`
+amba_developer_signup({
+  email: "sandbox-<unix-seconds>-<6char-nonce>@layers.com",
+  password: "<32 random base64url chars>",
+  name: "amba-sandbox-agent"
+})
+\`\`\`
+
+The response shape:
+
+\`\`\`json
+{
+  "data": {
+    "pat": "amb_dpat_…",
+    "developer": { "id": "…", "email": "…", "tier": "agent_sandbox" },
+    "project": {
+      "project_id": "…",
+      "client_key": "amb_ck_…",
+      "server_key": "amb_sk_…",
+      "provisioning_status": "provisioning",
+      "verify_url": "https://app.amba.dev/verify?token=…",
+      "verify_token": "…"
+    }
+  }
+}
+\`\`\`
+
+After signup, the PAT is in your hand — keep building in THIS session immediately. Pass \`pat: "<the PAT from the response>"\` as an inline argument on every subsequent \`amba_*\` tool call; the inline arg overrides the inbound Bearer for that one call so no client config change is needed mid-session. For future sessions, write the matching snippet from \`mcp_config\` to the customer's MCP-client config file so the static Bearer takes over automatically on the next launch.
+
+The project status is \`"provisioning"\` immediately after signup; the per-tenant DB activates within ~5 seconds. Don't block — your next call may briefly retry, that's fine. If you want to be polite, call \`amba_projects_get_provisioning_status({ project_id })\` once and proceed when it returns \`"active"\` (or after 15s, whichever first).
+
+Tell the user where their credentials live:
+
+- \`pat\` — the Bearer they should configure in this MCP client's settings (and treat like a password).
+- \`project_id\`, \`client_key\` — the values they paste into their app's \`.env.local\` / \`.env\`.
+- \`server_key\` — never ship to user devices; only into a server \`.env\` or a secret manager. The \`amb_dev_sk_\` / \`amb_live_sk_\` prefix is the marker.
+
+**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"\`.
+
+## 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:
+
+- The user's prompt — "I'm building a fitness tracker" / "a marketplace for…" / "a Duolingo for X".
+- README content if shared.
+- \`package.json\` / \`pubspec.yaml\` / \`build.gradle.kts\` / \`Package.swift\` — framework + dependencies.
+- Screen / view names — \`WorkoutScreen\`, \`MatchView\`, \`LessonPage\`, \`CartView\`, \`ProductDetail\`, \`ChatThread\`.
+
+Pick the closest match:
+
+| Preset | When | Default Amba surfaces |
+| --- | --- | --- |
+| **fitness** | health / fitness tracker (workouts, steps, meditation) | identity (Apple+Google), push, XP, achievements, streaks, leaderboards, content (daily tips) |
+| **social** | social network / community (friends, feeds, groups) | identity, push, friends, groups, feeds, messaging, moderation, content |
+| **marketplace** | commerce / marketplace (catalog, stores, payments) | identity, push, catalog, stores, currencies (loyalty), reviews, segments |
+| **productivity** | productivity / SaaS tool (collaboration, milestones) | identity (Apple+Google+OTP), push, collections, achievements, content (changelog), segments |
+| **education** | education / learning app (courses, progress, rewards) | identity, push, XP, achievements, streaks, leaderboards, content (lessons), onboarding |
+| **game** | game / casual gaming | identity (anon-first), push, XP, achievements, currencies, inventory, leaderboards, challenges, stores |
+| **dating** | dating / matching app | identity (phone-OTP), push, friends (matches), messaging, moderation (heavy), reviews |
+| **content_creator** | content platform (feeds, subscriptions, tips) | identity, push, feeds, content, currencies (tips), referrals, stores (subscriptions) |
+| **ai_chatbot** | AI / chatbot / assistant app | identity, push, AI prompts, currencies (credits), content (system prompts), onboarding |
+| **custom** | none of the above | pick features individually |
+
+Detection heuristics, in priority order:
+
+1. The user's own description — most direct signal.
+2. Filename match in \`screens/\` or \`views/\` (high signal).
+3. Dependency in \`package.json\` — \`react-native-health\` → fitness, \`@stream-io/*\` → social or dating, \`@stripe/*\` → marketplace, \`revenuecat\` → marketplace or content_creator.
+4. README copy — "fitness", "habit", "match", "chat", "store", "subscription".
+
+If two presets tie, pick the one the user's filenames match more closely. If still tied or no signal, fall back to **custom** and let them pick.
+
+## Step 2 — Confirm with the user
+
+Use a single multi-choice. Quote the surfaces from the table above so they know what they're getting.
+
+**Question 1: classification + scope**
+
+> I'm reading this as a **\\{kind\\}** app. I'd wire up: **\\{surfaces\\}**. Sound right?
+>
+> 1. Yes, wire it up as proposed (Recommended)
+> 2. Same kind but I want to pick features individually
+> 3. Wrong kind — let me pick from the list
+> 4. Custom — I'll pick features manually
+
+If the user picks 1, go to Step 3. If 2 or 4, follow up with a multi-select of surfaces. If 3, present the table again and pick a different preset.
+
+**Question 2 (preset-specific):** see the per-surface sub-resources (\`amba://setup/<surface>\`) for the full "Common follow-ups" list. Examples:
+
+- **fitness / game / education** — leaderboard scope? (all-time, weekly, daily, none)
+- **game / content_creator** — virtual currency name? (\`gold\`, \`gems\`, \`coins\`, \`credits\` — defaults to \`coins\`)
+- **content_creator** — monetization? (tips, subscriptions, both)
+- **dating** — phone OTP or email-only? (phone strongly recommended)
+- **ai_chatbot** — daily free credit cap?
+
+Batch the follow-ups into one or two multi-choice rounds. Don't drip-feed six separate questions.
+
+## Step 3 — Wire it up
+
+For each surface in the confirmed set, read the relevant sub-resource and execute its procedure. Each sub-resource is the full per-surface playbook (MCP tools + SDK init per stack + common follow-ups + re-run behavior):
+
+- **identity** (auth, anonymous/Apple/Google/OTP/magic-link, link/unlink) → \`amba://setup/identity\`
+- **engagement** (push, segments, content libraries, onboarding flows, deeplinks, referrals, tracked links) → \`amba://setup/engagement\`
+- **gamification** (XP rules, achievements, streaks, leaderboards, challenges) → \`amba://setup/gamification\`
+- **economy** (currencies, catalog, stores, inventory) → \`amba://setup/economy\`
+- **social** (friends, groups, feeds, messaging, moderation, reviews) → \`amba://setup/social\`
+- **infrastructure** (collections / DB tables, functions, analytics, AI prompts, media, secrets, configs, integrations, sites) → \`amba://setup/infrastructure\`
+
+The general flow for every surface:
+
+1. **Detect stack.** Look at \`package.json\`, \`pubspec.yaml\`, \`build.gradle.kts\`, \`ios/*.xcodeproj\`. The detection rules:
+   - \`pubspec.yaml\` present → Flutter.
+   - \`package.json\` with \`expo\` → Expo.
+   - \`package.json\` with \`react-native\` (no \`expo\`) → bare React Native.
+   - \`package.json\` with \`react\` (no \`react-native\`) → web (or Next.js — same SDK).
+   - \`Package.swift\` or \`*.xcodeproj\` only → iOS Swift.
+   - \`build.gradle.kts\` or \`build.gradle\` with \`com.android.application\` → Android Kotlin.
+   - Multiple (e.g. \`ios/\` + \`android/\` inside an Expo repo) → Expo wins.
+
+2. **Create resources via MCP.** Call the \`amba_<surface>_create\` tools to mint the definitions. Always include \`project_id\` from the project you created in Step 0. Always show the user the tool call before making destructive changes (creating a resource isn't destructive — but creating 30 of them is noisy).
+
+3. **Write SDK init code.** Drop the per-stack snippet (from the sub-resource) into the user's entry file. Detection:
+   - Expo / React Native: \`app/_layout.tsx\`, \`App.tsx\`, \`index.js\` (in that order)
+   - web / Next.js: \`app/layout.tsx\`, \`pages/_app.tsx\`, \`src/main.tsx\`, \`src/App.tsx\`
+   - iOS Swift: \`Sources/<App>/<App>App.swift\`, \`App/AppDelegate.swift\`
+   - Android Kotlin: \`app/src/main/java/.../<App>.kt\` (the \`Application\` subclass — create one if missing)
+   - Flutter: \`lib/main.dart\`
+
+   Always make additive edits — \`await Amba.configure(...)\` next to existing init, not replacing it. Never refactor existing auth or storage code; if the user has Firebase Auth or Supabase, leave it. Amba's auth is opt-in per call.
+
+4. **Run the project's existing test command** to confirm nothing broke. Detection:
+   - \`package.json\` \`scripts.test\` → \`npm test\` (or \`pnpm test\` if \`pnpm-lock.yaml\` present)
+   - \`pubspec.yaml\` → \`flutter test\`
+   - \`build.gradle.kts\` → \`./gradlew test\` (skip on first wire-up — slow)
+   - iOS — skip (need a simulator).
+
+   If tests fail because of your edits, undo the offending edit and surface a clear error. If they fail for unrelated reasons (pre-existing red), note it and proceed.
+
+5. **Verify with the SDK.** Tell the user to call \`Amba.diagnostics.ping()\` (\`Amba.Diagnostics.Ping()\` on Unity) in their entry file. It returns \`{ ok, server_project_id, environment, key_fingerprint, latency_ms }\`. \`ok: true\` with the expected \`server_project_id\` confirms the wiring.
+
+## Step 4 — Report
+
+Tell the user a structured summary. Use this exact shape so they can skim it fast:
+
+\`\`\`
+Amba is wired in. Here's what changed:
+
+DONE
+  - identity: Apple + Google sign-in available; signInAnonymously() called at app start
+  - gamification: 3 achievements, 1 streak, 1 leaderboard created
+    resources: first_workout, week_warrior, century_club / daily_workout / weekly_xp
+  - engagement: push registration wired; default segment "active_users" created
+
+SKIPPED (low signal — re-run with /amba <feature> if you want them)
+  - economy: no in-app currency UI found in your screens
+  - social: no friends/feed surfaces found
+
+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.
+
+NEXT STEPS
+  - Paste AMBA_CLIENT_KEY into your build env (already shown above)
+  - Trigger a workout in your existing flow — watch the achievement unlock + XP land
+  - Open https://app.amba.dev to see users pour in
+\`\`\`
+
+Be specific. List resources by key, not "some achievements". If something needs the user's input (third-party credentials, OAuth client IDs, push certs), say it clearly with the exact next action.
+
+## Stance (read this once)
+
+- **Don't ask which surfaces to use.** Classify, then confirm in one multi-choice. The taxonomy is the whole point.
+- **Default to additive, non-breaking changes.** Don't refactor existing auth, storage, or networking code. Drop in \`await Amba.configure(...)\` next to whatever the user already has.
+- **Never create resources without the user's confirmation in Step 2.** A 3rd-party "convenience" achievement called \`first_login\` is debt.
+- **If something is genuinely ambiguous** (leaderboard scope, currency real-money vs virtual, dating phone vs email), ask via a follow-up multi-choice. Don't guess and don't paragraph-it.
+- **clientKey vs serverKey.** \`AMBA_CLIENT_KEY\` (\`amb_dev_ck_…\` in dev, \`amb_live_ck_…\` in prod) ships to user devices. \`AMBA_SERVER_KEY\` (\`amb_dev_sk_…\` / \`amb_live_sk_…\`) never does — only into server \`.env\` or a secret manager. Mixing them is the #1 security mistake; if you're writing into a file that ships with the app binary, it's the client key, period.
+- **Don't echo the PAT in chat output on every call.** Showing it once after signup is fine; do not repeat it.
+
+## Get credentials (cheat sheet)
+
+- No terminal, in an MCP client: call \`amba_developer_signup\` (no Bearer required) — this guide's Step 0.
+- With a terminal: \`npx -y @layers/amba init\` signs up, mints a project + client/server keys, writes \`.env.local\` + \`AMBA.md\`, installs the \`/amba\` skill, and wires \`mcpServers.amba\` into every detected MCP-client config in one command. Auto-detects non-TTY invocations (the coding-agent bash-tool case) and runs headlessly.
+- Bind the sandbox account to a real email later: \`npx @layers/amba claim me@example.com\`. The backend emails a one-click magic link; clicking it lifts the sandbox cap to the Free tier.
+- Hosted MCP endpoint: \`https://mcp.amba.dev/mcp\` (Streamable HTTP, Bearer auth).
+
+## SDKs
+
+| Stack | Registry | Package |
+|---|---|---|
+| Browser / Node / React / React Native / Expo | npm | \`@layers/amba-{web,node,react,react-native,expo}\` |
+| Swift | SPM | \`https://github.com/layers/amba-sdk-ios\` |
+| Kotlin | Maven Central | \`com.layers.amba:amba-sdk-android\` |
+| Flutter | pub.dev | \`amba\` |
+| Unity | UPM (git) | \`https://github.com/layers/amba-sdk-unity.git\` |
+
+All SDKs expose the same surface: \`Amba.configure({ projectId, apiKey })\`, then \`Amba.events.track(...)\`, \`Amba.users.*\`, \`Amba.collections.*\`, etc. Per-stack quickstart pages with the exact initialization snippet: \`https://docs.amba.dev/sdk/<framework>\`.
+
+## What Amba does
+
+### Identity
+- **users** — app-user registry. Auto-created on first SDK call; admin via \`amba_users_*\`.
+- **roles + permissions** — RBAC. Define with \`amba_roles_create\`; assign via \`amba_roles_assign\`.
+- **api_keys** — client + server keys per project. Mint via \`amba_api_keys_create\`.
+
+### Engagement
+- **onboarding** — multi-step first-run flows. Define with \`amba_onboarding_create\`; SDK \`Amba.onboarding.next()\`.
+- **segments** — user cohorts. Define with \`amba_segments_create\`; used as push/feed targets.
+- **push** — scheduled or triggered notifications. Chain: configure integrations (apns/fcm) → \`amba_push_campaigns_create\` → \`amba_push_campaigns_send\` (or schedule).
+- **referrals** — referral codes. Define with \`amba_referrals_create\`.
+- **deeplinks** — universal links. Set domain with \`amba_deeplinks_set_config\`.
+- **tracked_links** — UTM-tagged outbound links. Define with \`amba_tracked_links_create\`.
+- **content** — episodic delivery (lessons, quotes, daily prompts). Chain: \`amba_content_libraries_create\` → \`amba_content_items_add\` → \`amba_content_schedules_create\`.
+
+### Gamification
+- **xp** — experience points + level. Define rules with \`amba_xp_rules_create\`; SDK \`Amba.xp.getBalance\`.
+- **achievements** — earnable badges. Define with \`amba_achievements_create\`; unlock via xp rules or \`amba_inventory_grant_item\`.
+- **streaks** — recurring engagement counters. Define with \`amba_streaks_create\`; client calls \`Amba.streaks.qualify(key)\`.
+- **leaderboards** — ranked user lists. Define with \`amba_leaderboards_create\`; populated from events.
+- **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\`; 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\`.
+
+### Social
+- **friendships** — friend graph. SDK \`Amba.friends.*\`; admin via \`amba_friendships_*\`.
+- **groups** — guilds/parties/chats. Define with \`amba_groups_create\`; members managed via SDK + admin tools.
+- **messaging** — DMs + group chat. Enabled by default; moderate via \`amba_messaging_*\`.
+- **feeds** — algorithmic activity feeds. Define ranking with \`amba_feeds_rules_create\`.
+- **reviews** — user-submitted reviews. Enabled by default; moderate via \`amba_reviews_*\`.
+- **moderation** — content review queue + trust scores. Configure with \`amba_moderation_configure\`; review via \`amba_moderation_queue_list\`.
+
+### Analytics
+- **events** — track user actions. SDK \`Amba.events.track()\`; query via \`amba_events_count\`.
+- **sessions** — session telemetry. Tracked automatically; query via \`amba_sessions_list\`.
+- **analytics** — funnels + retention. Query via \`amba_analytics_get\`.
+
+### Infrastructure
+- **collections** — your own typed key-value tables. Define with \`amba_collections_create\`; read/write from SDK \`Amba.client.*\`.
+- **functions** — serverless TypeScript handlers. Deploy with \`amba_functions_deploy\`; schedule with \`amba_functions_schedule\`.
+- **sites** — static site hosting at \`*.app.amba.host\`. Deploy with \`amba_sites_deploy\`.
+- **media** — file storage + CDN. Upload via \`amba_media_upload\`.
+- **secrets** — env vars for functions. Set via \`amba_secrets_set\`.
+- **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\`.
+`;
+/**
+* Canonical Amba Expo build prompt — markdown body (no MDX frontmatter).
+*
+* Source of truth for three customer-facing surfaces:
+*
+*   1. The published docs page at
+*      `https://docs.amba.dev/prompts/expo-build` — the MDX file at
+*      `apps/docs/content/docs/prompts/expo-build.mdx` ships the same
+*      body wrapped in fumadocs frontmatter.
+*   2. The MCP resource `amba://prompts/expo-build` registered by
+*      `registerAllResources()` in `./index.ts` and exposed by the
+*      hosted MCP server at `mcp.amba.dev`.
+*   3. The inlined snapshot baked into the `/amba-build` Claude Code
+*      skill by `amba init --sandbox` (see `packages/cli/src/skills.ts`).
 *
 * Drift between this constant and the MDX file is caught by
 * `expo-build-prompt.test.ts` — that test reads the MDX from disk,
@@ -1344,8 +2389,8 @@ function formatManualMcpSnippet(pat) {
 * so it renders identically as `.md` (the MCP / skill consumers) and
 * as `.mdx` (the docs site).
 */
-const EXPO_BUILD_PROMPT_MD = `> **Last reviewed:** 2026-05-16. The canonical version of this page lives
-> at [docs.amba.dev/docs/prompts/expo-build](https://docs.amba.dev/docs/prompts/expo-build).
+const EXPO_BUILD_PROMPT_MD = `> **Last reviewed:** 2026-05-17. The canonical version of this page lives
+> at [docs.amba.dev/prompts/expo-build](https://docs.amba.dev/prompts/expo-build).
 > If you're reading an inlined snapshot from your
 > \`.claude/skills/amba-build/SKILL.md\`, check the URL above for updates.
 
@@ -1361,7 +2406,7 @@ The CLI handles signup, project provisioning, env-file writes, and MCP
 client config wiring in one command:
 
 \`\`\`bash
-npx @layers/amba init --sandbox
+npx -y @layers/amba init
 \`\`\`
 
 That's the entire setup. The CLI:
@@ -1374,14 +2419,17 @@ That's the entire setup. The CLI:
 4. Writes \`AMBA.md\` (project-scoped context for the agent).
 5. Auto-wires \`mcpServers.amba\` into every MCP client config it
    detects on disk — Claude Code, Cursor, Windsurf.
-6. Prints a per-client restart instruction.
+6. Verifies the PAT against the API and confirms it's good.
 
-After restarting your MCP client, the Amba MCP toolset is available
-(\`amba_*\` tools — ~130 of them) and the agent can drive the backend
-end-to-end.
+The Amba MCP toolset (\`amba_*\` tools — ~130 of them) is available to
+the agent immediately: pass the freshly-minted \`pat\` as an inline
+argument on every \`amba_*\` call in the current session. The next time
+your MCP client starts it picks the PAT up from the config as the
+inbound Bearer automatically — at that point the \`pat\` arg becomes
+optional. No restart needed; nothing for you to do.
 
 If you have the \`/amba-build\` skill installed (via
-\`npx @layers/amba init --sandbox\`), invoke it directly:
+\`npx -y @layers/amba init\`), invoke it directly:
 
 \`\`\`
 /amba-build <DESIGN_HASH>
@@ -1401,11 +2449,13 @@ DX cascade is fixed.
 - **React Native bundle size** — the React Native SDK adds ~4 MB to
   the JS bundle today. Functional, just heavier than the long-term
   goal. Tracked separately.
-- **Sandbox MAU cap (50)** — the agent-mode sandbox tier caps at 50
+- **Sandbox MAU cap (100)** — the agent-mode sandbox tier caps at 100
   monthly active users. If you blow through it during testing, call
   \`amba_users_reset_sandbox\` to clear the counter — that tool exists
-  specifically for this. Upgrade to the Free tier (claim the email)
-  to lift the cap to 1,000.
+  specifically for this. Upgrade to the Free tier (1,000 MAU, 500 MB
+  DB) by running \`amba claim me@example.com\` from the terminal — the
+  backend emails a one-click magic link to the address you pass in;
+  clicking it binds the account to that email and lifts the cap.
 
 ## How to read the design
 
@@ -1537,6 +2587,12 @@ gate.
   \`expo export --platform ios\`, and \`expo export --platform android\`
   must all succeed. If any one fails, the build fails. No
   "shipped iOS-only, web is broken" — the rule is parity.
+- **Don't name a tab \`settings.tsx\`.** Use \`account.tsx\` or
+  \`preferences.tsx\` instead. Expo Router's static web export generates
+  \`settings.html\` correctly but does not resolve direct URL navigation
+  to \`/settings\` — the client-side router shows an unmatched-route
+  error while other tab names work fine. (Observed in dogfood; upstream
+  behavior, not an Amba issue.)
 
 ## Verification gate
 
@@ -1618,33 +2674,47 @@ If \`BUILD_REPORT.md\` is missing any required section, or
 //#endregion
 //#region src/skills.ts
 /**
-* Claude Code skill installer for `amba init --sandbox`.
-*
-* Writes a project-local `.claude/skills/amba-build/SKILL.md` file
-* containing the canonical "/goal" prompt for building a full Expo
-* app with Amba as the only backend. Two behaviors:
-*
-*   1. **Live fetch first.** The skill's runtime instructions tell
-*      Claude Code to `curl` the live MDX from
-*      `https://docs.amba.dev/docs/prompts/expo-build.md`. So as long
-*      as docs is reachable, the agent always uses the latest version.
-*
-*   2. **Inlined snapshot fallback.** The same SKILL.md file embeds a
-*      verbatim copy of the prompt body — captured at CLI install
-*      time from `@layers/amba-mcp/prompts`. Offline agents (or ones
-*      whose curl 404s during the docs deploy gap) still get a
-*      usable prompt.
-*
-* Out of scope (per DX-16): Cursor / Windsurf shortcut files. Those
-* editors don't ingest Claude Code skills; their users paste the
-* URL directly. The CLI's success line still surfaces the
-* `/amba-build` command + the docs URL so both audiences are served.
-*
-* Project-local install is the default because skills written into
-* `~/.claude/skills/` are user-global and would persist across
-* unrelated projects (and accumulate stale copies of the inlined
-* snapshot from old `amba init` runs). A project-scoped install
-* disappears when the user `rm -rf`s the project.
+* Per-agent skill / rule file installer for `amba init`.
+*
+* Two distinct surfaces, both project-local:
+*
+*   1. **Build task skill** — `.claude/skills/amba-build/SKILL.md`.
+*      Scaffolds a full Expo app via the canonical "/goal" prompt.
+*      Task-shaped: the user invokes it explicitly. Lives behind
+*      `writeAmbaBuildSkill` (legacy export, unchanged).
+*
+*   2. **Reference / setup skill** — fanned out into five locations,
+*      one per agent family, so the same Amba setup guide reaches
+*      whatever coding agent the user has installed:
+*
+*      | Surface                                  | Path                          | Wrapper                  |
+*      |------------------------------------------|-------------------------------|--------------------------|
+*      | Claude Code (proactive, auto-injected)   | \`CLAUDE.md\` (append)          | plain markdown           |
+*      | Claude Code (invokable skill)            | \`.claude/skills/amba/SKILL.md\` | \`description:\` frontmatter |
+*      | Cursor                                   | \`.cursor/rules/amba.mdc\`      | \`alwaysApply\`/\`description\`/\`globs\` |
+*      | Codex / Aider / Zed / Copilot / Gemini   | \`AGENTS.md\` (append)          | plain markdown           |
+*      | Windsurf                                 | \`.windsurf/rules/amba.md\`     | \`trigger: always_on\`     |
+*
+* The two append targets (\`CLAUDE.md\`, \`AGENTS.md\`) use marker
+* fencing — \`<!-- AMBA-SETUP-START -->\` / \`<!-- AMBA-SETUP-END -->\` —
+* so a re-init refreshes only Amba's section without clobbering user
+* edits to the surrounding file. The standalone targets (\`.cursor\`,
+* \`.windsurf\`, \`.claude/skills/amba\`) live in their own files and
+* are overwritten wholesale per re-init.
+*
+* The shared body comes from \`@layers/amba-mcp/prompts\`
+* (\`AMBA_SETUP_GUIDE_MD\`) — one canonical source, five wrappers. The
+* CLI bundles that constant at publish time via tsdown's
+* \`noExternal: [/^@layers\\/amba-/]\` rule (same path \`EXPO_BUILD_PROMPT_MD\`
+* already uses).
+*
+* Vendor-name discipline
+* ----------------------
+* Everything written by this module is customer-facing. The body
+* (sourced from the MCP package) is vetted there; the wrappers below
+* intentionally avoid naming Cloudflare / GCP / Neon / Temporal /
+* Rust / WASM / UniFFI / Resend / Doppler. See \`skills.test.ts\` for
+* the per-writer drift gate.
 */
 /**
 * Build the contents of `.claude/skills/amba-build/SKILL.md`.
@@ -1652,17 +2722,6 @@ If \`BUILD_REPORT.md\` is missing any required section, or
 * Exported as a pure function so the unit tests can assert structural
 * properties (frontmatter, fetcher block, inlined snapshot fence)
 * without round-tripping through the filesystem.
-*
-* Structure:
-*   1. YAML frontmatter — `description` so Claude Code's skill
-*      indexer picks it up.
-*   2. Skill body — invocation instructions, fetcher one-liner,
-*      fallback rule.
-*   3. Inlined snapshot — fenced code block containing the
-*      EXPO_BUILD_PROMPT_MD body verbatim. The snapshot is bounded
-*      by a marker comment so a future `amba update-skills` command
-*      can find and refresh just the inlined region without
-*      clobbering user customizations above it.
 */
 function buildAmbaBuildSkillContent() {
 	return `---
@@ -1672,7 +2731,7 @@ description: Canonical /goal prompt for building a full Expo app with Amba as th
 # /amba-build
 
 When invoked, fetch the canonical prompt from
-\`https://docs.amba.dev/docs/prompts/expo-build.md\` and use it as the
+\`https://docs.amba.dev/prompts/expo-build.md\` and use it as the
 \`/goal\` directive for building a full Expo app with Amba as the only
 backend. The user supplies a design hash (URL or description) as the
 argument; substitute it for every \`<DESIGN_HASH>\` placeholder in the
@@ -1692,7 +2751,7 @@ Replace \`<DESIGN_HASH>\` with:
 ## Fetcher
 
 \`\`\`bash
-curl -sf https://docs.amba.dev/docs/prompts/expo-build.md
+curl -sf https://docs.amba.dev/prompts/expo-build.md
 \`\`\`
 
 If \`curl\` fails (404, 5xx, network error, no internet), fall back to
@@ -1715,17 +2774,8 @@ ${EXPO_BUILD_PROMPT_MD}<!-- AMBA-BUILD-PROMPT-END -->
 }
 /**
 * Write `.claude/skills/amba-build/SKILL.md` into the target project.
-*
-* Always overwrites — the skill file is meant to be regenerated each
-* time `amba init --sandbox` runs (so the inlined snapshot stays
-* fresh). Anything the user customized above the snapshot markers
-* would be lost on a re-init; that's an accepted trade-off for the
-* agentic single-command flow.
-*
-* If a future need for "preserve user edits across re-init" surfaces,
-* the right shape is a separate `amba update-skills` command that
-* surgically rewrites the inlined-snapshot region only — leaving the
-* surrounding text untouched. Out of scope for DX-16.
+* Always overwrites — the inlined snapshot is meant to be regenerated
+* on each `amba init --sandbox` run.
 */
 async function writeAmbaBuildSkill(options = {}) {
 	const skillDir = join(options.baseDir ?? process.cwd(), ".claude", "skills", "amba-build");
@@ -1734,6 +2784,334 @@ async function writeAmbaBuildSkill(options = {}) {
 	await writeFile(skillPath, buildAmbaBuildSkillContent(), "utf-8");
 	return { path: skillPath };
 }
+/**
+* Marker fence sentinels for the two append-targets (`CLAUDE.md`,
+* `AGENTS.md`). Used by `markerFencedAppend` to find + refresh the
+* Amba section without clobbering surrounding user content.
+*/
+const AMBA_SETUP_START_MARKER = "<!-- AMBA-SETUP-START -->";
+const AMBA_SETUP_END_MARKER = "<!-- AMBA-SETUP-END -->";
+var AmbaSkillFileCorrupted = class extends Error {
+	path;
+	shape;
+	constructor(filePath, shape) {
+		super(`Found ${shape.startCount} AMBA-SETUP-START marker(s) and ${shape.endCount} AMBA-SETUP-END marker(s) in ${filePath}; expected exactly 1 of each in order. Refusing to auto-fix: cutting either side could discard user content. Please remove the extras (or the orphan marker) manually and re-run \`amba init\`.`);
+		this.name = "AmbaSkillFileCorrupted";
+		this.path = filePath;
+		this.shape = shape;
+	}
+};
+/**
+* Insert or refresh a marker-fenced block in a file.
+*
+* Marker-shape invariant: the target file must have either
+*   (a) zero start/end markers (clean append), or
+*   (b) exactly one start marker and one end marker, with the end
+*       marker after the start (clean in-place refresh).
+*
+* Any other shape — orphan single marker, duplicate paired blocks,
+* end-before-start, mixed counts (e.g. 1 start + 2 ends) — is
+* treated as corruption and throws `AmbaSkillFileCorrupted`. The
+* caller's `warn` sink surfaces the error to the developer; the
+* file is left untouched. Earlier revisions tried to auto-recover
+* malformed states via strip-and-replace, but every recovery
+* heuristic risked deleting user content outside the Amba block
+* (BugBot cycle-5..7 all flagged adjacent failure modes — the
+* strict invariant kills the whole class).
+*
+* Behavior:
+*
+*   - File does not exist (`ENOENT`) → create with just the block.
+*     **Any other read error (EACCES, EISDIR, transient I/O) is
+*     re-thrown** — we never silently overwrite a file we couldn't
+*     read.
+*   - File exists, zero markers → append the block (with a blank-
+*     line separator so it doesn't fuse onto the last paragraph).
+*   - File exists, well-formed 1+1 pair (end after start) → replace
+*     the content between markers, preserving surrounding text.
+*   - Any other marker shape → throw `AmbaSkillFileCorrupted` with
+*     the observed (startCount, endCount, startIdx, endIdx).
+*
+* Returns the absolute path + whether this was a fresh create or a
+* refresh.
+*
+* The `body` argument is the text we want **inside** the markers —
+* the markers themselves are added by this helper. Callers must NOT
+* include the start/end marker lines in `body`.
+*/
+async function markerFencedAppend(filePath, body, startMarker, endMarker) {
+	await mkdir(dirname(filePath), { recursive: true });
+	let existing = null;
+	try {
+		existing = await readFile(filePath, "utf-8");
+	} catch (err) {
+		if (err?.code === "ENOENT") existing = null;
+		else throw err;
+	}
+	const block = `${startMarker}\n${body}\n${endMarker}`;
+	if (existing === null) {
+		await writeFile(filePath, block + "\n", "utf-8");
+		return {
+			path: filePath,
+			mode: "created"
+		};
+	}
+	const startCount = countOccurrences(existing, startMarker);
+	const endCount = countOccurrences(existing, endMarker);
+	const startIdx = existing.indexOf(startMarker);
+	const endIdx = existing.indexOf(endMarker);
+	if (startCount === 1 && endCount === 1 && endIdx > startIdx) {
+		const before = existing.slice(0, startIdx);
+		const after = existing.slice(endIdx + endMarker.length);
+		await writeFile(filePath, before + block + after, "utf-8");
+		return {
+			path: filePath,
+			mode: "refreshed"
+		};
+	}
+	if (startCount === 0 && endCount === 0) {
+		const separator = existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+		await writeFile(filePath, existing + separator + block + "\n", "utf-8");
+		return {
+			path: filePath,
+			mode: "refreshed"
+		};
+	}
+	throw new AmbaSkillFileCorrupted(filePath, {
+		startCount,
+		endCount,
+		startIdx,
+		endIdx
+	});
+}
+/**
+* Count non-overlapping occurrences of `needle` in `haystack`.
+* Used to classify the marker state of an existing file.
+*/
+function countOccurrences(haystack, needle) {
+	if (needle.length === 0) return 0;
+	let count = 0;
+	let pos = 0;
+	while (true) {
+		const idx = haystack.indexOf(needle, pos);
+		if (idx === -1) break;
+		count += 1;
+		pos = idx + needle.length;
+	}
+	return count;
+}
+/**
+* Build the canonical setup body. Sourced from the MCP package so
+* docs + MCP + every coding-agent surface stay in sync.
+*
+* Exposed as a function (not a const) so future versions can swap in
+* a build-time generator without breaking import sites.
+*/
+function buildAmbaSetupBody() {
+	return AMBA_SETUP_GUIDE_MD;
+}
+/**
+* Build the Cursor `.cursor/rules/amba.mdc` flavor.
+*
+* `alwaysApply: true` makes Cursor inject the rule at the start of
+* every turn (Cursor's most-proactive mode). `globs: ""` keeps the
+* rule globally-scoped instead of file-pattern-attached.
+*/
+function buildCursorRuleContent() {
+	return `---
+alwaysApply: true
+description: "Amba SDK + MCP guide"
+globs: ""
+---
+
+${buildAmbaSetupBody()}
+`;
+}
+/**
+* Build the Windsurf `.windsurf/rules/amba.md` flavor.
+*
+* `trigger: always_on` is Windsurf's equivalent of Cursor's
+* `alwaysApply: true`. Workspace rules **cap at 12k chars** — a hard
+* Windsurf limit, not negotiable. The canonical
+* `AMBA_SETUP_GUIDE_MD` body is the full classify → confirm →
+* wire-up playbook (~17k) and won't fit, so Windsurf gets a
+* trimmed-down summary that points at the long-form resource
+* (`amba://setup`) for full detail. Same posture as
+* `AMBA_INIT_INSTRUCTIONS` in the hosted MCP server.
+*/
+function buildWindsurfRuleContent() {
+	return `---
+trigger: always_on
+---
+
+${buildWindsurfSummaryBody()}
+`;
+}
+/**
+* Shorter summary of the Amba setup playbook for Windsurf rules.
+*
+* Constraints:
+*   - Wrapped frontmatter + body must fit under Windsurf's 12k cap.
+*   - Must name the same five-step journey shape so an agent acting
+*     on this summary doesn't drift from the canonical guide.
+*   - Customer-facing — no vendor leakage.
+*
+* For full detail (per-surface MCP tool tables, per-stack SDK init
+* snippets, common follow-ups, re-run rules), the agent fetches
+* `amba://setup` (or per-surface \`amba://setup/<surface>\`) from the
+* hosted MCP server.
+*/
+function buildWindsurfSummaryBody() {
+	return `# Amba
+
+Amba is the backend your app calls at runtime via the SDK; the MCP tools (\`amba_*\`) are for provisioning, called by the coding agent.
+
+## Bootstrap
+
+\`amba_developer_signup\` is the only pre-auth MCP tool — call it with no Bearer to mint a PAT, project, and client/server keys in one round trip. After signup, set \`Authorization: Bearer <pat>\` on every subsequent MCP call. Save \`project_id\` + \`client_key\` to \`.env.local\`; never write \`server_key\` next to client code.
+
+## Playbook
+
+When the user asks you to wire Amba into this codebase, run this journey end-to-end:
+
+1. **Step 0 — Bootstrap credentials.** Call \`amba_developer_signup\` (pre-auth) OR \`amba_developer_me\` if a PAT already exists. Persist \`project_id\` + \`client_key\` to \`.env.local\`.
+2. **Step 1 — Classify the app.** Pick one of ten presets (fitness / social / marketplace / productivity / education / game / dating / content_creator / ai_chatbot / custom) using README + filenames + dependencies.
+3. **Step 2 — Confirm with the user.** One multi-choice question listing the surfaces the preset implies. Don't drip-feed.
+4. **Step 3 — Wire it up.** For each surface in the confirmed scope, fetch its sub-resource (\`amba://setup/<surface>\`) and execute its MCP tools + drop in the per-stack SDK init snippet.
+5. **Step 4 — Report.** Structured DONE / SKIPPED / NEEDS YOUR INPUT / NEXT STEPS summary.
+
+## Surfaces
+
+- **identity** — anonymous + Apple + Google + OTP + magic link (see \`amba://setup/identity\`).
+- **engagement** — push, segments, content, onboarding, deeplinks, referrals, tracked links (\`amba://setup/engagement\`).
+- **gamification** — XP, achievements, streaks, leaderboards, challenges (\`amba://setup/gamification\`).
+- **economy** — currencies, catalog, stores, inventory (\`amba://setup/economy\`).
+- **social** — friends, groups, feeds, messaging, moderation, reviews (\`amba://setup/social\`).
+- **infrastructure** — collections (typed tables), functions, AI prompts, secrets, configs, integrations, media, sites (\`amba://setup/infrastructure\`).
+
+## SDKs
+
+| Stack | Registry | Package |
+|---|---|---|
+| Browser / Node / React / RN / Expo | npm | \`@layers/amba-{web,node,react,react-native,expo}\` |
+| Swift | SPM | \`https://github.com/layers/amba-sdk-ios\` |
+| Kotlin | Maven Central | \`com.layers.amba:amba-sdk-android\` |
+| Flutter | pub.dev | \`amba\` |
+| Unity | UPM (git) | \`https://github.com/layers/amba-sdk-unity.git\` |
+
+All SDKs expose \`Amba.configure({ projectId, apiKey })\` then \`Amba.events.track(...)\`, \`Amba.users.*\`, \`Amba.collections.*\`, etc.
+
+## Stance
+
+- **clientKey vs serverKey.** \`AMBA_CLIENT_KEY\` (\`amb_dev_ck_…\` / \`amb_live_ck_…\`) ships to user devices. \`AMBA_SERVER_KEY\` (\`amb_dev_sk_…\` / \`amb_live_sk_…\`) never does — server \`.env\` or a secret manager. Mixing them is the #1 security mistake.
+- **Default to additive, non-breaking edits.** Drop \`await Amba.configure(...)\` next to existing init, don't refactor.
+- **Don't create resources without Step 2 confirmation.**
+- **Use canonical (post-DX-12) tool names** — \`amba_<resource>_<verb>\` form. Legacy verb-leading aliases (\`amba_create_*\`, \`amba_list_*\`, etc.) still resolve but the canonical names are what to advertise.
+
+For the full playbook (per-surface MCP tool tables, per-stack SDK init snippets, common follow-ups, re-run behavior), read \`amba://setup\` and \`amba://setup/<surface>\` from the hosted MCP at \`mcp.amba.dev\`.
+`;
+}
+/**
+* Body for the marker-fenced append into `CLAUDE.md` or `AGENTS.md`.
+*
+* Plain markdown, no frontmatter — both conventions are
+* frontmatter-free. Returns the inner body only; the marker fence is
+* added by `markerFencedAppend`.
+*/
+function buildAppendableSetupBody() {
+	return buildAmbaSetupBody();
+}
+/** Write `.cursor/rules/amba.mdc`. */
+async function writeCursorRule(options = {}) {
+	const ruleDir = join(options.baseDir ?? process.cwd(), ".cursor", "rules");
+	await mkdir(ruleDir, { recursive: true });
+	const rulePath = join(ruleDir, "amba.mdc");
+	let mode = "created";
+	try {
+		await readFile(rulePath, "utf-8");
+		mode = "refreshed";
+	} catch {
+		mode = "created";
+	}
+	await writeFile(rulePath, buildCursorRuleContent(), "utf-8");
+	return {
+		path: rulePath,
+		mode
+	};
+}
+/** Write `.windsurf/rules/amba.md`. */
+async function writeWindsurfRule(options = {}) {
+	const ruleDir = join(options.baseDir ?? process.cwd(), ".windsurf", "rules");
+	await mkdir(ruleDir, { recursive: true });
+	const rulePath = join(ruleDir, "amba.md");
+	let mode = "created";
+	try {
+		await readFile(rulePath, "utf-8");
+		mode = "refreshed";
+	} catch {
+		mode = "created";
+	}
+	await writeFile(rulePath, buildWindsurfRuleContent(), "utf-8");
+	return {
+		path: rulePath,
+		mode
+	};
+}
+/**
+* Append (or refresh) the Amba setup section in `CLAUDE.md` at the
+* project root. Marker-fenced so it can be safely refreshed by
+* subsequent re-inits.
+*/
+async function writeClaudeMd(options = {}) {
+	return markerFencedAppend(join(options.baseDir ?? process.cwd(), "CLAUDE.md"), buildAppendableSetupBody(), AMBA_SETUP_START_MARKER, AMBA_SETUP_END_MARKER);
+}
+/**
+* Append (or refresh) the Amba setup section in `AGENTS.md` at the
+* project root. The `AGENTS.md` convention is read by 20+ agentic
+* tools (Codex, Aider, Zed, Copilot, Gemini CLI, Warp, etc.) so this
+* single file covers most of the long tail.
+*/
+async function writeAgentsMd(options = {}) {
+	return markerFencedAppend(join(options.baseDir ?? process.cwd(), "AGENTS.md"), buildAppendableSetupBody(), AMBA_SETUP_START_MARKER, AMBA_SETUP_END_MARKER);
+}
+async function writeAllSetupTargets(options = {}) {
+	const baseDir = options.baseDir ?? process.cwd();
+	const warn = options.warn ?? (() => {});
+	const written = [];
+	const tasks = [
+		{
+			target: "claude-md",
+			write: () => writeClaudeMd({ baseDir })
+		},
+		{
+			target: "cursor-rule",
+			write: () => writeCursorRule({ baseDir })
+		},
+		{
+			target: "agents-md",
+			write: () => writeAgentsMd({ baseDir })
+		},
+		{
+			target: "windsurf-rule",
+			write: () => writeWindsurfRule({ baseDir })
+		}
+	];
+	for (const task of tasks) try {
+		const res = await task.write();
+		written.push({
+			target: task.target,
+			path: res.path,
+			mode: res.mode
+		});
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		warn(`  ! Skipped ${task.target} setup file: ${message}`);
+	}
+	return {
+		written,
+		bodyVersion: "v2"
+	};
+}
 //#endregion
 //#region src/commands/init.ts
 function prompt(question) {
@@ -1748,6 +3126,85 @@ function prompt(question) {
 		});
 	});
 }
+function createSpinner(label) {
+	if (!process.stdout.isTTY) return {
+		setLabel: () => {},
+		stop: () => {},
+		get stopped() {
+			return true;
+		}
+	};
+	const frames = [
+		"⠋",
+		"⠙",
+		"⠹",
+		"⠸",
+		"⠼",
+		"⠴",
+		"⠦",
+		"⠧",
+		"⠇",
+		"⠏"
+	];
+	let i = 0;
+	let current = label;
+	let isStopped = false;
+	const render = () => {
+		const frame = frames[i % frames.length];
+		process.stdout.write(`\r  ${pc.cyan(frame)} ${pc.dim(current)}${" ".repeat(8)}`);
+		i += 1;
+	};
+	render();
+	const handle = setInterval(render, 80);
+	return {
+		setLabel: (next) => {
+			current = next;
+		},
+		stop: () => {
+			if (isStopped) return;
+			isStopped = true;
+			clearInterval(handle);
+			process.stdout.write("\r" + " ".repeat(80) + "\r");
+		},
+		get stopped() {
+			return isStopped;
+		}
+	};
+}
+/**
+* Pretty-print the elapsed time. Sub-minute renders as seconds
+* ("12s"); above that renders as "1m 04s". The spinner ends with this
+* stamped into the first line of the success block so a developer who
+* just ran the command knows how long the network round trips took.
+*/
+function formatElapsed(ms) {
+	const totalSec = Math.max(0, Math.round(ms / 1e3));
+	if (totalSec < 60) return `${totalSec}s`;
+	const m = Math.floor(totalSec / 60);
+	const s = totalSec % 60;
+	return `${m}m ${String(s).padStart(2, "0")}s`;
+}
+/**
+* Truncate a long id to a compact preview — first 7 chars + ellipsis.
+* Mirrors how the API surfaces `id.slice(0, 8)` in other places. Keeps
+* the success block readable when project ids are full UUIDs.
+*/
+function shortId(id) {
+	if (id.length <= 10) return id;
+	return `${id.slice(0, 7)}…`;
+}
+/**
+* Strip the project root from an absolute path for compact display in
+* the success block — `/Users/me/proj/.env.local` → `.env.local`,
+* `/Users/me/.claude.json` → `~/.claude.json` when a home dir is
+* provided. Pure cosmetic, never used for actual fs operations.
+*/
+function relPathForDisplay(absPath, cwd, home) {
+	if (absPath.startsWith(cwd + "/")) return absPath.slice(cwd.length + 1);
+	const homeDir = home ?? process.env["HOME"] ?? "";
+	if (homeDir && absPath.startsWith(homeDir + "/")) return "~/" + absPath.slice(homeDir.length + 1);
+	return absPath;
+}
 async function fileExists(path) {
 	try {
 		await access(path);
@@ -1847,7 +3304,8 @@ Docs: https://docs.amba.dev
 }
 async function initCommand(options = {}) {
 	const cwd = process.cwd();
-	if (options.sandbox) {
+	const isNonTTY = process.stdin.isTTY !== true;
+	if (options.sandbox === true || options.json === true || isNonTTY) {
 		const result = await runSandboxInit(cwd, {
 			sandboxEmail: options.sandboxEmail,
 			noMcpConfig: options.noMcpConfig,
@@ -1860,226 +3318,298 @@ async function initCommand(options = {}) {
 		return;
 	}
 	const environment = options.env ?? "development";
-	console.log();
-	console.log(pc.bold("  amba init"));
-	console.log(pc.dim("  ─────────────────────────────────"));
-	console.log();
-	console.log(pc.bold("  Step 1/7 ") + pc.dim("Authenticate"));
-	console.log();
-	const headlessActive = resolveTokenSource({
-		flagToken: void 0,
-		envToken: process.env["AMBA_PAT"]
-	}) !== null || process.argv.includes("--token") && process.argv.length > 2;
-	let needsAuth = true;
-	if (headlessActive) {
-		console.log(pc.green("  ✓") + " Headless auth — using PAT from --token / AMBA_PAT");
-		console.log(pc.dim("    (browser flow skipped; no credentials written to disk)"));
-		console.log();
-		needsAuth = false;
-	} else try {
-		if (!isTokenExpired(await loadCredentials())) {
-			console.log(pc.green("  ✓") + " Already authenticated");
-			console.log();
-			needsAuth = false;
-		}
-	} catch {}
-	if (needsAuth) {
-		const creds = await browserAuthFlow();
-		console.log(pc.bold("  Step 2/7 ") + pc.dim("Store credentials"));
-		await storeCredentials(creds);
-		console.log(pc.green("  ✓") + " Credentials saved to ~/.amba/credentials.json");
-		console.log();
-	} else {
-		console.log(pc.bold("  Step 2/7 ") + pc.dim("Store credentials"));
-		if (headlessActive) console.log(pc.green("  ✓") + " (skipped — PAT supplied)");
-		else console.log(pc.green("  ✓") + " Using existing credentials");
-		console.log();
-	}
-	console.log(pc.bold("  Step 3/7 ") + pc.dim("Select project"));
-	console.log();
-	let projectId;
-	let projectName;
+	const startedAt = Date.now();
+	const overridePat = getBearerOverride() ?? resolveTokenSource({ envToken: process.env["AMBA_PAT"] });
+	const headlessActive = overridePat !== null;
+	let identityPat = null;
+	let identity = null;
+	let credsBackedUpTo = null;
+	let spinner = createSpinner("authenticating");
 	try {
-		const projects = (await listProjects()).data;
-		if (projects.length > 0) {
-			console.log("  Existing projects:");
-			projects.forEach((p, i) => {
-				console.log(pc.dim(`    ${i + 1}.`) + ` ${p.name} ` + pc.dim(`(${p.id})`));
-			});
-			console.log(pc.dim(`    ${projects.length + 1}.`) + " Create new project");
-			console.log();
-			const choice = await prompt(`  Select project (1-${projects.length + 1}): `);
-			const choiceNum = parseInt(choice, 10);
-			if (choiceNum > 0 && choiceNum <= projects.length) {
-				const selected = projects[choiceNum - 1];
-				if (!selected) throw new Error("Invalid selection");
-				projectId = selected.id;
-				projectName = selected.name;
-				console.log(pc.green("  ✓") + ` Selected: ${projectName}`);
-			} else {
-				const name = await prompt("  Project name: ");
-				if (!name) {
-					console.log(pc.red("  ✗") + " Project name is required");
-					process.exit(1);
+		if (headlessActive) {
+			identityPat = overridePat;
+			try {
+				identity = await verifyPat(identityPat);
+			} catch (err) {
+				const reason = err instanceof Error ? err.message : String(err);
+				spinner.stop();
+				console.error(pc.red("  ✗") + ` Could not verify supplied token: ${reason}`);
+				process.exit(1);
+			}
+			if (!identity) {
+				spinner.stop();
+				console.error(pc.red("  ✗") + " Supplied token failed verification. Check --token / AMBA_PAT and try again.");
+				process.exit(1);
+			}
+		} else {
+			let needsBrowser = false;
+			try {
+				const ensured = await ensureDeveloperIdentity({ signupOnMissing: false });
+				identity = ensured.developer;
+				identityPat = ensured.credentials.pat;
+				credsBackedUpTo = ensured.credentialsBackedUpTo;
+				setBearerOverride(ensured.credentials.pat);
+			} catch {
+				needsBrowser = true;
+			}
+			if (needsBrowser) {
+				spinner.stop();
+				await storeCredentials(await browserAuthFlow());
+				const ensured = await ensureDeveloperIdentity({ signupOnMissing: false });
+				identity = ensured.developer;
+				identityPat = ensured.credentials.pat;
+				credsBackedUpTo = ensured.credentialsBackedUpTo;
+			}
+		}
+		if (!identityPat || !identity) {
+			spinner.stop();
+			console.error(pc.red("  ✗") + " Could not establish an Amba identity.");
+			process.exit(1);
+			return;
+		}
+		const linkedProject = await loadProjectCredentials(cwd);
+		const defaultProjectName = basename(cwd) || "amba-project";
+		let projectId;
+		let projectName;
+		if (linkedProject) {
+			projectId = linkedProject.project_id;
+			projectName = linkedProject.project_name;
+		} else {
+			spinner.setLabel("loading projects");
+			let projectsList = [];
+			try {
+				projectsList = (await listProjects()).data;
+			} catch (err) {
+				if (err instanceof Error && err.message.includes("authenticate")) {
+					spinner.stop();
+					throw err;
+				}
+				projectsList = [];
+			}
+			spinner.stop();
+			if (projectsList.length > 0) {
+				console.log();
+				console.log("  Existing projects:");
+				projectsList.forEach((p, i) => {
+					const envBadge = p.environment ? pc.dim(` [${p.environment}]`) : "";
+					console.log(pc.dim(`    ${i + 1}.`) + ` ${p.name}${envBadge} ` + pc.dim(`(${p.id.slice(0, 8)}…)`));
+				});
+				const newOptionIdx = projectsList.length + 1;
+				console.log(pc.dim(`    ${newOptionIdx}.`) + ` Create new project ` + pc.dim(`(default name: ${defaultProjectName})`));
+				console.log();
+				const choice = await prompt(`  Select project (1-${newOptionIdx}, default ${newOptionIdx}): `);
+				const choiceNum = choice.length === 0 ? newOptionIdx : parseInt(choice, 10);
+				if (choiceNum > 0 && choiceNum <= projectsList.length) {
+					const selected = projectsList[choiceNum - 1];
+					if (!selected) throw new Error("Invalid selection");
+					projectId = selected.id;
+					projectName = selected.name;
+				} else {
+					const name = await prompt(`  Project name (default: ${defaultProjectName}): `);
+					const finalName = name.length > 0 ? name : defaultProjectName;
+					projectId = (await createProject({
+						name: finalName,
+						environment
+					})).data.id;
+					projectName = finalName;
 				}
+			} else {
+				const name = await prompt(`  Project name (default: ${defaultProjectName}): `);
+				const finalName = name.length > 0 ? name : defaultProjectName;
 				projectId = (await createProject({
-					name,
+					name: finalName,
 					environment
 				})).data.id;
-				projectName = name;
-				console.log(pc.green("  ✓") + ` Created: ${projectName} ${pc.dim(`(${environment})`)}`);
-			}
-		} else {
-			const name = await prompt("  Project name: ");
-			if (!name) {
-				console.log(pc.red("  ✗") + " Project name is required");
-				process.exit(1);
+				projectName = finalName;
 			}
-			projectId = (await createProject({ name })).data.id;
-			projectName = name;
-			console.log(pc.green("  ✓") + ` Created: ${projectName}`);
 		}
-	} catch (err) {
-		if (err instanceof Error && err.message.includes("authenticate")) throw err;
-		const name = await prompt("  Project name: ");
-		if (!name) {
-			console.log(pc.red("  ✗") + " Project name is required");
-			process.exit(1);
+		if (spinner.stopped) spinner = createSpinner("minting keys");
+		const work = spinner;
+		work.setLabel("minting keys");
+		let clientKey;
+		let serverKey;
+		if (linkedProject) {
+			clientKey = linkedProject.client_key;
+			if (linkedProject.server_key) serverKey = linkedProject.server_key;
+			else serverKey = (await createApiKey(projectId, "server", environment)).data.key;
+		} else {
+			const clientRes = await createApiKey(projectId, "client", environment);
+			const serverRes = await createApiKey(projectId, "server", environment);
+			clientKey = clientRes.data.key;
+			serverKey = serverRes.data.key;
 		}
-		projectId = (await createProject({ name })).data.id;
-		projectName = name;
-		console.log(pc.green("  ✓") + ` Created: ${projectName}`);
-	}
-	console.log();
-	console.log(pc.bold("  Step 4/7 ") + pc.dim("Generate API keys"));
-	const keyRes = await createApiKey(projectId, "client", "development");
-	const apiKey = keyRes.data.key;
-	console.log(pc.green("  ✓") + " Development client key created");
-	console.log(pc.dim(`    ${keyRes.data.key_prefix}...`));
-	console.log();
-	console.log(pc.bold("  Step 5/7 ") + pc.dim("Write environment file"));
-	const envPath = join(cwd, ".env.local");
-	const envLines = [
-		"# Amba SDK Configuration",
-		`AMBA_PROJECT_ID=${projectId}`,
-		`AMBA_API_KEY=${apiKey}`,
-		`AMBA_API_URL=https://api.amba.dev`,
-		""
-	];
-	if (await fileExists(envPath)) {
-		const existing = await readFile(envPath, "utf-8");
-		if (existing.includes("AMBA_PROJECT_ID")) {
-			console.log(pc.yellow("  !") + " .env.local already contains Amba config — updating");
-			let updated = existing;
-			updated = updated.replace(/AMBA_PROJECT_ID=.*/, `AMBA_PROJECT_ID=${projectId}`);
-			updated = updated.replace(/AMBA_API_KEY=.*/, `AMBA_API_KEY=${apiKey}`);
-			updated = updated.replace(/AMBA_API_URL=.*/, `AMBA_API_URL=https://api.amba.dev`);
-			await writeFile(envPath, updated, "utf-8");
-		} else await writeFile(envPath, existing + (existing.endsWith("\n") ? "\n" : "\n\n") + envLines.join("\n"), "utf-8");
-	} else await writeFile(envPath, envLines.join("\n"), "utf-8");
-	console.log(pc.green("  ✓") + " .env.local written");
-	console.log();
-	console.log(pc.bold("  Step 6/7 ") + pc.dim("Detect framework"));
-	const framework = await detectFramework(cwd);
-	const sdkPkg = getSdkPackage(framework);
-	if (framework !== "unknown") console.log(pc.green("  ✓") + ` Detected: ${pc.bold(framework)}`);
-	else console.log(pc.yellow("  !") + " Could not detect framework");
-	let installCmd = `npm install ${sdkPkg}`;
-	if (await fileExists(join(cwd, "bun.lockb"))) installCmd = `bun add ${sdkPkg}`;
-	else if (await fileExists(join(cwd, "pnpm-lock.yaml"))) installCmd = `pnpm add ${sdkPkg}`;
-	else if (await fileExists(join(cwd, "yarn.lock"))) installCmd = `yarn add ${sdkPkg}`;
-	console.log(pc.dim(`    Install SDK: ${installCmd}`));
-	console.log();
-	console.log(pc.bold("  Step 7/7 ") + pc.dim("Generate context files"));
-	const generatedFiles = await generateContextFiles({
-		projectId,
-		projectName,
-		apiKey,
-		framework,
-		cwd
-	});
-	for (const file of generatedFiles) console.log(pc.green("  ✓") + ` ${file}`);
-	if (options.withExample) {
-		const exampleFiles = await writeExampleScaffold(cwd, framework, projectName);
-		if (exampleFiles.length > 0) for (const file of exampleFiles) console.log(pc.green("  ✓") + ` ${file} ` + pc.dim("(example)"));
-		else console.log(pc.dim("  -") + " example files already present — skipping");
-	}
-	console.log();
-	console.log(pc.dim("  ─────────────────────────────────"));
-	console.log();
-	console.log(pc.bold(pc.green("  ✓ Project initialized!")));
-	console.log();
-	console.log("  Quick start:");
-	console.log();
-	console.log(pc.dim("    1.") + ` Install the SDK`);
-	console.log(`       ${pc.cyan(installCmd)}`);
-	console.log();
-	console.log(pc.dim("    2.") + ` Add the provider to your app`);
-	if (framework === "expo") console.log(pc.dim(`       See AMBA.md for Amba.init() setup`));
-	else if (framework === "react-native") console.log(pc.dim(`       See AMBA.md for client initialization`));
-	else console.log(pc.dim(`       See AMBA.md for client initialization`));
-	console.log();
-	console.log(pc.dim("    3.") + ` Test the integration`);
-	console.log(`       ${pc.cyan("amba status")}`);
-	console.log();
-	console.log(pc.dim("    4.") + ` Send a test notification`);
-	console.log(`       ${pc.cyan("amba push test")}`);
-	console.log();
-	console.log(`  Docs: ${pc.underline("https://docs.amba.dev")}`);
-	console.log();
-}
-async function runSandboxInit(cwd, options) {
-	if (!options.json) {
+		work.setLabel("writing project state");
+		const apiUrl = process.env["AMBA_API_URL"] ?? "https://api.amba.dev";
+		const envLocalPath = await writeSandboxEnvLocal(cwd, projectId, clientKey, apiUrl, serverKey);
+		const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+		const projectJsonPath = await writeProjectCredentials(cwd, linkedProject ? {
+			...linkedProject,
+			client_key: clientKey,
+			server_key: serverKey,
+			environment,
+			api_url: apiUrl,
+			updated_at: nowIso
+		} : {
+			version: 1,
+			project_id: projectId,
+			project_name: projectName,
+			environment,
+			client_key: clientKey,
+			server_key: serverKey,
+			api_url: apiUrl,
+			wired_surfaces: [],
+			created_at: nowIso,
+			updated_at: nowIso
+		});
+		work.setLabel("detecting framework");
+		const framework = await detectFramework(cwd);
+		const sdkPkg = getSdkPackage(framework);
+		let installCmd = `npm install ${sdkPkg}`;
+		if (await fileExists(join(cwd, "bun.lockb"))) installCmd = `bun add ${sdkPkg}`;
+		else if (await fileExists(join(cwd, "pnpm-lock.yaml"))) installCmd = `pnpm add ${sdkPkg}`;
+		else if (await fileExists(join(cwd, "yarn.lock"))) installCmd = `yarn add ${sdkPkg}`;
+		work.setLabel("wiring agents");
+		await generateContextFiles({
+			projectId,
+			projectName,
+			apiKey: clientKey,
+			framework,
+			cwd
+		});
+		let mcpResults = [];
+		let mcpManualSnippetNeeded = false;
+		if (!options.noMcpConfig) {
+			mcpResults = await writeAllMcpConfigs(cwd, identityPat, {
+				homeDir: options.homeDir,
+				warn: (msg) => process.stderr.write(msg + "\n")
+			});
+			mcpManualSnippetNeeded = mcpResults.length === 0;
+		}
+		if (options.withExample) await writeExampleScaffold(cwd, framework, projectName);
+		work.setLabel("verifying");
+		const finalVerify = await verifyPat(identityPat);
+		work.stop();
+		if (!finalVerify) {
+			console.error(pc.red("  ✗") + " Post-write verify failed. PAT was minted but no longer accepted.");
+			console.error(pc.dim("    Inspect ~/.amba/credentials.json + ") + pc.dim(".env.local — your provisioning may be incomplete."));
+			process.exit(1);
+		}
+		const elapsed = formatElapsed(Date.now() - startedAt);
+		const homeForDisplay = options.homeDir;
+		const envRel = relPathForDisplay(envLocalPath, cwd, homeForDisplay);
+		const projectJsonRel = relPathForDisplay(projectJsonPath, cwd, homeForDisplay);
 		console.log();
-		console.log(pc.bold("  amba init --sandbox"));
-		console.log(pc.dim("  ─────────────────────────────────"));
+		console.log(pc.green("  ✓") + pc.bold(` Amba ready in ${elapsed}`));
+		console.log(pc.dim("    project: ") + projectName + pc.dim(` (id: ${shortId(projectId)})`));
+		console.log(pc.dim("    keys → ") + envRel + pc.dim(` · state → ${projectJsonRel}`));
+		if (mcpResults.length > 0) {
+			const mcpPathsRel = mcpResults.map((m) => relPathForDisplay(m.path, cwd, homeForDisplay)).join(", ");
+			console.log(pc.dim("    mcp → ") + mcpPathsRel + pc.dim(" (active next agent launch)"));
+			for (const m of mcpResults) if (m.backedUpTo) console.log(pc.yellow("    note: previous amba entry backed up to ") + relPathForDisplay(m.backedUpTo, cwd, homeForDisplay));
+		} else if (mcpManualSnippetNeeded) console.log(pc.dim("    mcp → ") + "no MCP client config detected (paste snippet below)");
+		if (credsBackedUpTo) console.log(pc.dim("    note: previous credentials backed up to ") + credsBackedUpTo);
 		console.log();
+		console.log(pc.dim("    next: ") + pc.cyan(installCmd));
+		console.log(pc.dim("    later: ") + pc.cyan("amba claim <your-email>") + pc.dim(" to upgrade past sandbox"));
+		console.log();
+		if (mcpManualSnippetNeeded && !options.noMcpConfig) {
+			console.log(pc.dim("  Paste into your MCP client config:"));
+			for (const line of formatManualMcpSnippet(identityPat).split("\n")) console.log(pc.dim("    ") + line);
+			console.log();
+		}
+	} finally {
+		spinner.stop();
 	}
-	const signup = await performSandboxSignup({
-		email: options.sandboxEmail?.trim() || generateSandboxEmail(),
-		password: generateSandboxPassword()
+}
+async function runSandboxInit(cwd, options) {
+	const warn = (msg) => {
+		process.stderr.write(msg + "\n");
+	};
+	const overridePat = getBearerOverride() ?? resolveTokenSource({ envToken: process.env["AMBA_PAT"] });
+	let identity;
+	if (overridePat) {
+		const verified = await verifyPat(overridePat);
+		if (!verified) throw new Error("Supplied --token / AMBA_PAT failed verification against /developer/me. Check that the token is valid and try again.");
+		identity = {
+			credentials: {
+				pat: overridePat,
+				email: verified.email
+			},
+			newlySignedUp: false,
+			developer: verified,
+			firstProject: null,
+			credentialsBackedUpTo: null,
+			credentialsPath: "(supplied via --token / AMBA_PAT — not persisted)"
+		};
+	} else identity = await ensureDeveloperIdentity({
+		homeDir: options.homeDir,
+		sandboxEmail: options.sandboxEmail
 	});
-	const envLocalPath = await writeSandboxEnvLocal(cwd, signup.project_id, signup.client_key, signup.api_url);
+	setBearerOverride(identity.credentials.pat);
 	const framework = await detectFramework(cwd);
 	const sdkPackage = getSdkPackage(framework);
+	const project = await ensureProjectForCwd(cwd, {
+		pat: identity.credentials.pat,
+		signupFirstProject: identity.firstProject ?? void 0,
+		defaultName: basename(cwd) || "amba-sandbox"
+	});
+	const envLocalPath = await writeSandboxEnvLocal(cwd, project.credentials.project_id, project.credentials.client_key, project.credentials.api_url, project.credentials.server_key);
 	const ambaMdPath = await writeSandboxAmbaMd(cwd, {
-		projectId: signup.project_id,
-		email: signup.email,
-		verifyUrl: signup.verify_url ?? null,
+		projectId: project.credentials.project_id,
+		email: identity.credentials.email,
+		verifyUrl: identity.firstProject?.verify_url ?? null,
 		sdkPackage,
 		framework,
-		apiUrl: signup.api_url
+		apiUrl: project.credentials.api_url
 	});
-	const warn = options.json ? (msg) => process.stderr.write(msg + "\n") : (msg) => console.warn(msg);
 	let mcpConfigsWritten = [];
-	if (!options.noMcpConfig) mcpConfigsWritten = await writeAllMcpConfigs(cwd, signup.pat, {
+	if (!options.noMcpConfig) mcpConfigsWritten = await writeAllMcpConfigs(cwd, identity.credentials.pat, {
 		homeDir: options.homeDir,
 		warn
 	});
-	const credentialsResult = await writeSandboxCredentials(signup.pat, { homeDir: options.homeDir });
 	let skillPath = null;
-	if (!options.noSkills) try {
-		skillPath = (await writeAmbaBuildSkill({ baseDir: cwd })).path;
-	} catch (err) {
-		warn(`  ! Skipped /amba-build skill install: ${err instanceof Error ? err.message : String(err)}`);
+	let setupTargets = [];
+	if (!options.noSkills) {
+		try {
+			const installResults = await installSkillBundle(cwd);
+			summarizeSkillInstall(installResults);
+			skillPath = (installResults.find((r) => r.target.kind === "claude-code")?.files.find((f) => f.path.endsWith("SKILL.md")))?.path ?? null;
+		} catch (err) {
+			warn(`  ! Skipped amba skill bundle install: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		try {
+			await writeAmbaBuildSkill({ baseDir: cwd });
+		} catch (err) {
+			warn(`  ! Skipped legacy /amba-build skill: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		setupTargets = (await writeAllSetupTargets({
+			baseDir: cwd,
+			warn
+		})).written.map((w) => ({
+			target: w.target,
+			path: w.path,
+			mode: w.mode
+		}));
 	}
+	if (!await verifyPat(identity.credentials.pat, { apiUrl: project.credentials.api_url })) throw new Error("Post-write verify failed: PAT was provisioned but no longer accepted by /developer/me. This usually means the control-plane signup race hasn't settled yet — retry in 5s.");
 	return {
-		email: signup.email,
-		projectId: signup.project_id,
-		pat: signup.pat,
-		patPreview: `${signup.pat.slice(0, 12)}…${signup.pat.slice(-4)}`,
-		clientKey: signup.client_key,
-		apiUrl: signup.api_url,
-		credentialsPath: credentialsResult.path,
-		credentialsBackedUpTo: credentialsResult.backedUpTo,
+		email: identity.credentials.email,
+		projectId: project.credentials.project_id,
+		pat: identity.credentials.pat,
+		patPreview: `${identity.credentials.pat.slice(0, 12)}…${identity.credentials.pat.slice(-4)}`,
+		clientKey: project.credentials.client_key,
+		apiUrl: project.credentials.api_url,
+		credentialsPath: identity.credentialsPath,
+		credentialsBackedUpTo: identity.credentialsBackedUpTo,
 		envLocalPath,
 		ambaMdPath,
 		mcpConfigsWritten,
 		sdkPackage,
 		framework,
-		verifyUrl: signup.verify_url ?? null,
-		provisioningStatus: signup.provisioning_status ?? "unknown",
-		skillPath
+		verifyUrl: identity.firstProject?.verify_url ?? null,
+		provisioningStatus: identity.firstProject?.provisioning_status ?? "active",
+		skillPath,
+		setupTargets
 	};
 }
 function sandboxResultToJson(r) {
@@ -2102,83 +3632,83 @@ function sandboxResultToJson(r) {
 			backed_up_to: m.backedUpTo
 		})),
 		skill_path: r.skillPath,
+		setup_targets: r.setupTargets.map((t) => ({
+			target: t.target,
+			path: t.path,
+			mode: t.mode
+		})),
 		verify_url: r.verifyUrl,
 		provisioning_status: r.provisioningStatus,
-		next_steps: ["restart your MCP client"]
+		next_steps: [`npm install ${r.sdkPackage}`, "call Amba.configure({ projectId, clientKey }) at app startup"],
+		runtime_mcp: {
+			configs_written: r.mcpConfigsWritten.map((m) => m.path),
+			activates_on: "next agent launch",
+			in_session_inline_pat: true
+		}
 	};
 }
 /**
 * Build the plaintext (no ANSI) success-output block printed at the
-* end of `amba init --sandbox`. Pure function — exported only for the
-* vitest cases that assert on per-line content. The CLI wraps each
-* line with picocolors in `printSandboxNextSteps` below.
-*
-* Structure (in order):
-*   1. Per-artifact checklist (`✓ ...` lines)
-*   2. SDK install + configure hint
-*   3. "Done." + per-client restart bullets — ONLY for clients we
-*      actually wrote configs to. Never instruct the user to "restart
-*      Cursor" if we only touched `~/.claude.json`. When no config
-*      was written (manual-paste path), falls back to a generic
-*      "quit + reopen" line.
-*   4. Tail-line resume hint + sandbox limits + verify URL.
-*
-* We intentionally do NOT print any "kill -HUP / SIGHUP" advanced
-* workaround. Telling the agent to surface a clean "restart your MCP
-* client" instruction to the human is the whole optimization — adding
-* an experimental fallback just dilutes the signal and risks the
-* agent surfacing the workaround instead.
+* end of `amba init --sandbox`. Pure function — exported for the
+* vitest cases that assert on per-line content. The CLI wraps the
+* output with picocolors in `printSandboxNextSteps` below.
+*
+* Design: silent-until-done. The install (provision account, mint
+* keys, write .env.local, write MCP config, install skill) is COMPLETE
+* the moment this output lands. The MCP config has been persisted —
+* it activates on the next launch of the developer's coding agent. We
+* do NOT instruct the developer to restart anything; we just state
+* what's wired and what's next.
+*
+* Shape (~6 lines, Vercel/Stripe aesthetic):
+*   ✓ Amba ready
+*     project: <id>
+*     keys → .env.local
+*     mcp → <paths> (active next agent launch)
+*     skill → <skill paths> (when installed)
+*
+*     next: npm install <sdk-pkg>
+*           Amba.configure({ projectId, clientKey }) at app startup
+*
+* The fallback for "no MCP client config detected" is a one-line
+* note + a paste-ready snippet — still no restart copy.
 */
 function buildSandboxNextStepsLines(r) {
 	const lines = [];
-	lines.push(`✓ Sandbox account provisioned (${r.email})`);
-	lines.push(`✓ Project created: ${r.projectId}`);
-	lines.push(`✓ Credentials saved to ~/.amba/credentials.json`);
-	if (r.credentialsBackedUpTo) lines.push(`  ! Existing non-sandbox credentials backed up to ${r.credentialsBackedUpTo}`);
-	lines.push(`✓ .env.local updated with AMBA_PROJECT_ID + AMBA_CLIENT_KEY + AMBA_API_URL`);
-	lines.push(`✓ AMBA.md written (sandbox guide)`);
-	if (r.skillPath) lines.push(`✓ /amba-build skill installed: ${r.skillPath}`);
-	const clientKinds = clientKindsFromPaths(r.mcpConfigsWritten.map((m) => m.path));
-	if (r.mcpConfigsWritten.length > 0) for (const m of r.mcpConfigsWritten) {
-		lines.push(`✓ MCP config updated: ${m.path} (entry: 'amba')`);
-		if (m.backedUpTo) lines.push(`  ! Existing amba entry backed up to ${m.backedUpTo}`);
-	}
-	else {
-		lines.push(`! No MCP client config detected — paste this into your MCP client's config manually:`);
+	lines.push(`✓ Amba ready`);
+	lines.push(`  project: ${shortId(r.projectId)} (${r.email})`);
+	lines.push(`  keys → ${r.envLocalPath}`);
+	if (r.mcpConfigsWritten.length > 0) {
+		const mcpPaths = r.mcpConfigsWritten.map((m) => m.path).join(", ");
+		lines.push(`  mcp → ${mcpPaths} (active next agent launch)`);
+		for (const m of r.mcpConfigsWritten) if (m.backedUpTo) lines.push(`  note: previous amba entry backed up to ${m.backedUpTo}`);
+	} else lines.push(`  mcp → no MCP client config detected (paste snippet below)`);
+	if (r.skillPath) lines.push(`  skill → ${r.skillPath}`);
+	if (r.credentialsBackedUpTo) lines.push(`  note: previous non-sandbox credentials backed up to ${r.credentialsBackedUpTo}`);
+	lines.push("");
+	lines.push(`  next: npm install ${r.sdkPackage}`);
+	lines.push(`        Amba.configure({ projectId: process.env.AMBA_PROJECT_ID, clientKey: process.env.AMBA_CLIENT_KEY })`);
+	lines.push(`  later: amba claim <your-email> to upgrade past sandbox`);
+	if (r.mcpConfigsWritten.length === 0) {
 		lines.push("");
+		lines.push(`  Paste into your MCP client config:`);
 		for (const snippetLine of formatManualMcpSnippet(r.pat).split("\n")) lines.push(`    ${snippetLine}`);
-		lines.push("");
 	}
-	lines.push("");
-	lines.push("Next:");
-	lines.push(`  → npm install ${r.sdkPackage}`);
-	lines.push(`  → Initialize the SDK in your app entry: Amba.configure({ projectId: process.env.AMBA_PROJECT_ID, clientKey: process.env.AMBA_CLIENT_KEY })`);
-	lines.push("");
-	lines.push("Done. Restart your MCP client so it loads the Amba MCP server:");
-	if (clientKinds.length === 0) lines.push("  • Quit your MCP client (Cmd+Q on macOS) and reopen it.");
-	else for (const kind of clientKinds) lines.push(`  • ${restartHintForClient(kind)}`);
-	lines.push("");
-	lines.push("After the restart, re-ask the original question — Amba's MCP toolset will be available.");
-	if (r.skillPath) lines.push("Tip: paste `/amba-build <design-url>` to scaffold a full Expo app with Amba as the backend.");
-	lines.push("");
-	lines.push(`Sandbox limits: 100 MAU, 10 MB DB. Verify ${r.email} in the console to upgrade to Free.`);
-	if (r.verifyUrl) lines.push(`Verify URL: ${r.verifyUrl}`);
 	return lines;
 }
-function restartHintForClient(kind) {
-	switch (kind) {
-		case "claude-code": return "Claude Code: Cmd+Q, then reopen";
-		case "cursor": return "Cursor: Cmd+Q, then reopen";
-		case "windsurf": return "Windsurf: quit + relaunch";
-	}
-}
 function printSandboxNextSteps(r) {
-	for (const line of buildSandboxNextStepsLines(r)) if (line.startsWith("✓ ")) console.log(pc.green("  " + line.slice(0, 2)) + line.slice(2));
-	else if (line.startsWith("! ")) console.log(pc.yellow("  " + line.slice(0, 2)) + line.slice(2));
-	else if (line.startsWith("  ! ")) console.log(pc.yellow("    ! ") + line.slice(4));
-	else if (line.startsWith("Next:") || line.startsWith("Done. Restart your MCP client")) console.log(pc.bold("  " + line));
-	else if (line.startsWith("Sandbox limits:") || line.startsWith("Verify URL:") || line.startsWith("After the restart")) console.log(pc.dim("  " + line));
-	else console.log("  " + line);
+	const lines = buildSandboxNextStepsLines(r);
+	console.log();
+	for (const line of lines) if (line.startsWith("✓ ")) console.log("  " + pc.green("✓") + pc.bold(line.slice(1)));
+	else if (line.startsWith("  note:")) console.log("  " + pc.yellow(line.slice(2)));
+	else if (line.startsWith("  next:")) {
+		const cmd = line.slice(8);
+		console.log("  " + pc.dim("next: ") + pc.cyan(cmd));
+	} else if (line.startsWith("  later:")) {
+		const cmd = line.slice(9);
+		console.log("  " + pc.dim("later: ") + pc.cyan(cmd));
+	} else if (line.startsWith("  project:") || line.startsWith("  keys") || line.startsWith("  mcp") || line.startsWith("  skill")) console.log(pc.dim(line));
+	else console.log(line);
 	console.log();
 }
 //#endregion
@@ -2539,7 +4069,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
@@ -2551,7 +4081,7 @@ function confirm(question) {
 		});
 	});
 }
-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}`);
@@ -2601,7 +4131,7 @@ async function projectsListCommand() {
 		console.log(pc.dim(`  ${projects.length} project${projects.length === 1 ? "" : "s"}`));
 		console.log();
 	} catch (err) {
-		handleError(err);
+		handleError$1(err);
 	}
 }
 async function projectsCreateCommand(input) {
@@ -2627,6 +4157,7 @@ async function projectsCreateCommand(input) {
 		const res = await createProject({
 			name: input.name,
 			bundle_id: input.bundleId,
+			google_oauth_client_id: input.googleOauthClientId,
 			platform: input.platform,
 			environment
 		});
@@ -2637,7 +4168,7 @@ async function projectsCreateCommand(input) {
 		try {
 			const s = (await getProvisioningStatus(id)).data;
 			console.log(pc.dim(`    Status: ${s.status}`));
-			if (s.errorMessage) console.log(pc.yellow("    !") + ` ${s.errorMessage}`);
+			if (s.region) console.log(pc.dim(`    Region: ${s.region}`));
 		} catch {
 			console.log(pc.dim("    (Provisioning runs asynchronously.)"));
 		}
@@ -2646,7 +4177,33 @@ async function projectsCreateCommand(input) {
 		console.log(pc.dim("  Next: ") + pc.cyan(`amba projects show ${id}`));
 		console.log();
 	} catch (err) {
-		handleError(err);
+		handleError$1(err);
+	}
+}
+async function projectsUpdateCommand(projectId, input) {
+	console.log();
+	console.log(pc.bold(`  amba projects update ${projectId}`));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	const patch = {};
+	if (input.name !== void 0) patch.name = input.name;
+	if (input.bundleId !== void 0) patch.bundle_id = input.bundleId;
+	if (input.googleOauthClientId !== void 0) patch.google_oauth_client_id = input.googleOauthClientId;
+	if (input.platform !== void 0) patch.platform = input.platform;
+	if (input.environment !== void 0) patch.environment = input.environment;
+	try {
+		const res = await updateProject(projectId, patch);
+		console.log(pc.green("  ✓") + ` Updated ${pc.bold(res.data.name)} ${pc.dim(`(${res.data.id})`)}`);
+		if (res.data.bundle_id) console.log(pc.dim(`    Bundle ID: ${res.data.bundle_id}`));
+		if (res.data.google_oauth_client_id) console.log(pc.dim(`    Google OAuth client id: ${res.data.google_oauth_client_id}`));
+		console.log();
+	} catch (err) {
+		if (err instanceof ApiClientError && err.statusCode === 404) {
+			console.log(pc.red("  ✗") + ` Project not found: ${projectId}`);
+			console.log();
+			process.exit(1);
+		}
+		handleError$1(err);
 	}
 }
 async function projectsShowCommand(projectId) {
@@ -2664,7 +4221,7 @@ async function projectsShowCommand(projectId) {
 			console.log();
 			process.exit(1);
 		}
-		handleError(err);
+		handleError$1(err);
 	}
 }
 async function projectsDeleteCommand(projectId, opts = {}) {
@@ -2673,7 +4230,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;
@@ -2689,7 +4246,7 @@ async function projectsDeleteCommand(projectId, opts = {}) {
 			console.log();
 			process.exit(1);
 		}
-		handleError(err);
+		handleError$1(err);
 	}
 }
 //#endregion
@@ -2993,14 +4550,14 @@ async function dbMigrateCommand(opts = {}) {
 	console.log(pc.dim("  Running tenant migrations..."));
 	console.log();
 	try {
-		const workflowId = (await reprovisionProject(projectId)).data.workflowId;
-		console.log(pc.green("  ✓") + " Reprovision workflow started");
-		if (workflowId) console.log(pc.dim(`    workflowId: ${workflowId}`));
+		const jobId = (await reprovisionProject(projectId)).data.job_id;
+		console.log(pc.green("  ✓") + " Reprovision started");
+		if (jobId) console.log(pc.dim(`    job: ${jobId}`));
 		console.log();
 		try {
 			const status = await getProvisioningStatus(projectId);
 			console.log(pc.dim(`  Status: ${status.data.status}`));
-			if (status.data.errorMessage) console.log(pc.yellow("  !") + ` ${status.data.errorMessage}`);
+			if (status.data.region) console.log(pc.dim(`  Region: ${status.data.region}`));
 		} catch {}
 		console.log();
 		console.log(pc.dim("  Check again with: ") + pc.cyan(`amba projects show ${projectId}`));
@@ -3410,36 +4967,44 @@ function parseEnv(content) {
 /**
 * Customer-function bundling for `amba functions deploy`.
 *
-* Uses esbuild (the Workers ecosystem bundler-of-record). The shared
-* runtime stdlib is marked `external` so customer bundles don't
-* re-include megabytes of `@anthropic-ai/sdk`, `postgres`, `zod`, etc.;
-* these resolve at dispatch time via platform-level bindings.
+* Uses esbuild. Customer code is bundled into a single self-contained
+* ES module — the upstream runtime resolves nothing at dispatch time
+* except built-in JavaScript globals.
 *
 * Two checks gate the bundle before upload:
 *   1. Pre-upload size check against `BUNDLE_MAX_SIZE_BYTES` (8 MB
 *      default — the platform's 10 MB compressed cap minus 2 MB
 *      headroom) with a clear error pointing at the externalization
 *      config.
-*   2. Bundle-shape report — the CLI prints what's externalized vs
-*      bundled at deploy time so size issues are debuggable.
+*   2. Bundle-shape report — the CLI prints what's bundled vs
+*      externalized at deploy time so size issues are debuggable.
+*
+* History note (2026-05-27): the prior version of this file pinned
+* `@layers/amba-functions` + `@layers/amba-api-middleware` as
+* "platform-level bindings" externals. Neither is — they were
+* server-side packages, and `@layers/amba-functions` was unpublished
+* in the 4.0.2 cutover (a deprecated wrapper that never matched the
+* actual runtime). Any function importing one of them was rejected
+* upstream as "no such module." The default externals list is now
+* empty; customer code is expected to be self-contained.
 */
 /**
-* Modules customer code MUST externalize. The runtime exposes these as
-* platform-level bindings; bundling them per-script wastes hundreds of
-* KB to MBs and quickly hits the script-size cap.
+* 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.
+*
+* The `extraExternals` field on `BundleOptions` is a programmatic
+* escape hatch (used by tests + future CLI wiring). It's intentionally
+* not exposed as a `amba functions deploy` flag today — externalizing
+* a module that isn't actually provided at runtime is exactly the
+* footgun this list-defaults-to-empty change closes.
 */
-const RUNTIME_STDLIB_EXTERNALS = [
-	"@layers/amba-functions",
-	"@layers/amba-api-middleware",
-	"@anthropic-ai/sdk",
-	"postgres",
-	"zod"
-];
+const RUNTIME_STDLIB_EXTERNALS = [];
 var BundleSizeError = class extends Error {
 	sizeBytes;
 	maxBytes;
 	constructor(sizeBytes, maxBytes) {
-		super(`Function bundle is ${formatBytes$1(sizeBytes)} which exceeds the ${formatBytes$1(maxBytes)} cap. Externalize heavy dependencies via the runtime stdlib (see RUNTIME_STDLIB_EXTERNALS) or split your function into smaller pieces.`);
+		super(`Function bundle is ${formatBytes$1(sizeBytes)} which exceeds the ${formatBytes$1(maxBytes)} cap. Split the function into smaller pieces or drop heavy dependencies. (There is no runtime-provided npm stdlib to externalize against — every import must bundle.)`);
 		this.sizeBytes = sizeBytes;
 		this.maxBytes = maxBytes;
 		this.name = "BundleSizeError";
@@ -3496,8 +5061,10 @@ function printBundleReport(bundle) {
 	console.log(pc.dim("  Bundle:"));
 	console.log(pc.dim("    size: ") + `${formatBytes$1(bundle.compressedSize)} compressed ` + pc.dim(`(${formatBytes$1(bundle.uncompressedSize)} raw)`));
 	console.log(pc.dim("    sha:  ") + bundle.sha256.slice(0, 16) + pc.dim("…"));
-	console.log(pc.dim("    externalized:"));
-	for (const e of bundle.externals) console.log(pc.dim("      • ") + e);
+	if (bundle.externals.length > 0) {
+		console.log(pc.dim("    externalized:"));
+		for (const e of bundle.externals) console.log(pc.dim("      • ") + e);
+	}
 	console.log();
 }
 async function gzipSizeOf(bytes) {
@@ -3541,11 +5108,21 @@ 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
+		});
+	} 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`));
@@ -3600,11 +5177,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);
@@ -3879,11 +5457,37 @@ 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 plain-function shape — still accepted for backward compat but env
+    // parameter is not available (secrets only reachable via process.env).
+    handler = mod.default;
+  } else {
+    process.stderr.write('  Error: entry file must export default { async fetch(req, env, ctx) { ... } }\\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);
@@ -4033,8 +5637,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.
@@ -4087,7 +5691,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);
@@ -4148,7 +5752,6 @@ async function aiProvidersAddCommand(provider, options) {
 	});
 	console.log(pc.green("  ✓") + ` Registered ${provider}`);
 	if (res.data.api_key_preview) console.log(pc.dim(`    key preview: ${res.data.api_key_preview}`));
-	console.log(pc.dim(`    secret_name: ${res.data.api_key_secret_name ?? "(unset)"}`));
 	console.log();
 }
 async function aiProvidersListCommand() {
@@ -4160,7 +5763,7 @@ async function aiProvidersListCommand() {
 		console.log();
 		return;
 	}
-	for (const p of res.data) console.log(`  ${pc.bold(p.name)}  ` + pc.dim(`secret=${p.api_key_secret_name ?? "(unset)"}`) + (p.updated_at ? pc.dim(`  updated=${p.updated_at}`) : ""));
+	for (const p of res.data) console.log(`  ${pc.bold(p.name)}  ` + pc.dim(`configured=${p.configured ? "yes" : "no"}`) + (p.updated_at ? pc.dim(`  updated=${p.updated_at}`) : ""));
 	console.log();
 }
 async function aiProvidersDeleteCommand(provider) {
@@ -4194,11 +5797,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);
@@ -4208,14 +5820,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`);
@@ -4223,17 +5836,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();
 }
@@ -4256,6 +5874,168 @@ function renderStatus(status) {
 	}
 }
 //#endregion
+//#region src/commands/billing.ts
+/**
+* `amba billing *` subcommands — CLI access to the per-project billing
+* surface that ships behind `/v1/admin/projects/:id/billing/*`.
+*
+*   amba billing status                    — tier, headroom on each
+*                                            metered axis, next-bill date,
+*                                            human_action_required.
+*
+*   amba billing upgrade --tier <t>        — print the Stripe Checkout
+*                                            URL for tier ∈ {pro, scale}
+*     [--interval month|year]               at the chosen interval. CLI
+*                                            deliberately does NOT auto-
+*                                            open a browser: agents pipe
+*                                            the URL into a confirmation
+*                                            step, humans copy-paste.
+*
+*   amba billing portal                    — print the Customer Portal
+*                                            URL for card / cancel / etc.
+*
+*   amba billing set-ceiling <usd|off>     — cap (or remove) the monthly
+*                                            spend ceiling.
+*
+* Project is resolved via `loadProjectConfig` (AMBA_PROJECT_ID env, then
+* .env / .env.local in the cwd) — same pattern as `amba secrets *`.
+*/
+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 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);
+}
+/**
+* Issue a POST/PUT to the admin API. `api-client.ts` doesn't export a
+* generic POST helper for arbitrary paths, so this command file owns
+* 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) {
+	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)
+	});
+	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 formatAxis(label, axis, isStorage) {
+	const used = axis.used === null ? "—" : isStorage ? axis.used >= 1024 ? `${(axis.used / 1024).toFixed(2)} GB` : `${axis.used} MB` : axis.used.toLocaleString();
+	const limit = axis.limit === null ? "unlimited" : isStorage ? axis.limit >= 1024 ? `${(axis.limit / 1024).toFixed(0)} GB` : `${axis.limit} MB` : axis.limit.toLocaleString();
+	const pct = axis.pct === null ? "—" : `${Math.round(axis.pct * 100)}%`;
+	return `  ${pc.dim(label.padEnd(22))} ${used} / ${limit}  ${pc.dim(`(${pct})`)}`;
+}
+async function billingStatusCommand() {
+	console.log();
+	console.log(pc.bold("  amba billing status"));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	try {
+		const { projectId } = await loadProjectConfig();
+		const s = (await adminGet(`/projects/${projectId}/billing/status`)).data;
+		console.log(`  Tier:               ${pc.bold(s.tier)}`);
+		console.log(`  Subscription:       ${s.subscription_status ?? pc.dim("—")}`);
+		console.log(`  Next bill anchor:   ${s.current_period_end ? new Date(s.current_period_end).toLocaleDateString() : pc.dim("—")}`);
+		console.log(`  Spend ceiling:      ${s.ceiling_usd === null ? pc.dim("no cap") : `$${s.ceiling_usd}`}`);
+		console.log(`  Spend mode:         ${s.mode}`);
+		console.log(`  Projected overage:  $${s.projected_overage_usd_this_month.toFixed(2)}`);
+		if (s.paused_at) console.log(`  ${pc.yellow("Paused at:")}          ${s.paused_at} ${pc.dim("(wakes on next request)")}`);
+		console.log();
+		console.log(pc.bold("  Usage — rolling 30 days"));
+		console.log(formatAxis("Monthly active users", s.headroom.mau, false));
+		console.log(formatAxis("Engagement events", s.headroom.engagement_events, false));
+		console.log(formatAxis("Telemetry events", s.headroom.telemetry_events, false));
+		console.log(formatAxis("Push deliveries", s.headroom.push, false));
+		console.log(formatAxis("Database storage", s.headroom.db_storage_mb, true));
+		console.log(formatAxis("Media storage", s.headroom.media_storage_mb, true));
+		console.log();
+		if (s.human_action_required !== "none") {
+			const action = s.human_action_required.replaceAll("_", " ");
+			console.log(pc.yellow("  Action required: ") + pc.bold(action));
+			console.log();
+		}
+	} catch (err) {
+		handleError(err);
+	}
+}
+async function billingUpgradeCommand(input) {
+	console.log();
+	console.log(pc.bold("  amba billing upgrade"));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	try {
+		const { projectId } = await loadProjectConfig();
+		const interval = input.interval ?? "month";
+		const res = await adminWrite("POST", `/projects/${projectId}/billing/checkout`, {
+			tier: input.tier,
+			interval
+		});
+		console.log(`  Tier:       ${input.tier} (${interval}ly)`);
+		console.log(`  Session:    ${pc.dim(res.data.session_id)}`);
+		console.log();
+		console.log(pc.bold("  Open this URL to complete checkout:"));
+		console.log();
+		console.log(`  ${pc.cyan(res.data.url)}`);
+		console.log();
+		console.log(pc.dim("  Subscription status updates automatically once Stripe confirms (a few seconds)."));
+		console.log();
+	} catch (err) {
+		handleError(err);
+	}
+}
+async function billingPortalCommand() {
+	console.log();
+	console.log(pc.bold("  amba billing portal"));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	try {
+		const { projectId } = await loadProjectConfig();
+		const res = await adminWrite("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);
+	}
+}
+async function billingSetCeilingCommand(input) {
+	console.log();
+	console.log(pc.bold("  amba billing set-ceiling"));
+	console.log(pc.dim("  ─────────────────────────────────"));
+	console.log();
+	try {
+		const { projectId } = await loadProjectConfig();
+		await adminWrite(`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);
+	}
+}
+//#endregion
 //#region src/commands/collections.ts
 /**
 * `amba collections ...` — thin shells over the admin collection routes.
@@ -4677,13 +6457,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 +
@@ -4732,7 +6520,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();
 }
@@ -4782,32 +6570,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);
@@ -4818,7 +6625,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) {
@@ -4927,10 +6734,157 @@ 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/index.ts
 const program = new Command();
 program.name("amba").description("amba — agent-native backend-as-a-service for mobile apps.").version("0.1.0");
@@ -4982,6 +6936,9 @@ program.command("init").description("Initialize Amba in the current project (min
 		json: opts.json
 	}));
 });
+program.command("claim <email>").description("Bind your sandbox account to a real email (sends a one-click magic link)").action(async (email) => {
+	await runAction(() => claimCommand(email));
+});
 program.command("login").description("Authenticate with Amba").action(async () => {
 	await runAction(loginCommand);
 });
@@ -5010,14 +6967,24 @@ const projects = program.command("projects").description("Project management com
 projects.command("list").description("List all projects in the authenticated developer account").action(async () => {
 	await runAction(projectsListCommand);
 });
-projects.command("create").description("Create a new project").requiredOption("--name <name>", "Project name").option("--env <env>", "Environment hint (informational; new projects default to the 'development' environment)").option("--bundle-id <id>", "Bundle identifier (iOS/Android)").option("--platform <platform>", "Platform: 'ios' | 'android' | 'all'").action(async (opts) => {
+projects.command("create").description("Create a new project").requiredOption("--name <name>", "Project name").option("--env <env>", "Environment hint (informational; new projects default to the 'development' environment)").option("--bundle-id <id>", "Bundle identifier (iOS/Android). Audience for Sign in with Apple.").option("--google-oauth-client-id <id>", "Google OAuth 2.0 client id. Audience for Sign in with Google.").option("--platform <platform>", "Platform: 'ios' | 'android' | 'all'").action(async (opts) => {
 	await runAction(() => projectsCreateCommand({
 		name: opts.name,
 		env: opts.env,
 		bundleId: opts.bundleId,
+		googleOauthClientId: opts.googleOauthClientId,
 		platform: opts.platform
 	}));
 });
+projects.command("update <projectId>").description("Update mutable fields on a project").option("--name <name>", "Display name").option("--bundle-id <id>", "Bundle identifier (Apple Sign In audience)").option("--google-oauth-client-id <id>", "Google OAuth 2.0 client id (Google Sign In audience). Public identifier, not a secret.").option("--platform <platform>", "Platform: 'ios' | 'android' | 'all'").option("--environment <env>", "Environment label: 'development' | 'production'").action(async (projectId, opts) => {
+	await runAction(() => projectsUpdateCommand(projectId, {
+		name: opts.name,
+		bundleId: opts.bundleId,
+		googleOauthClientId: opts.googleOauthClientId,
+		platform: opts.platform,
+		environment: opts.environment
+	}));
+});
 projects.command("show <projectId>").description("Show full project details as JSON").action(async (projectId) => {
 	await runAction(() => projectsShowCommand(projectId));
 });
@@ -5100,19 +7067,53 @@ 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");
+billing.command("status").description("Show current tier, headroom on each metered axis, and projected overage").action(async () => {
+	await runAction(billingStatusCommand);
+});
+billing.command("upgrade").description("Print the Stripe Checkout URL for the chosen tier (does not auto-open a browser)").requiredOption("--tier <tier>", "'pro' or 'scale'").option("--interval <interval>", "'month' (default) or 'year' (20% off)", "month").action(async (opts) => {
+	if (opts.tier !== "pro" && opts.tier !== "scale") {
+		console.log("  ✗ --tier must be \"pro\" or \"scale\"");
+		process.exit(1);
+	}
+	if (opts.interval !== "month" && opts.interval !== "year") {
+		console.log("  ✗ --interval must be \"month\" or \"year\"");
+		process.exit(1);
+	}
+	await runAction(() => billingUpgradeCommand({
+		tier: opts.tier,
+		interval: opts.interval
+	}));
+});
+billing.command("portal").description("Print the Stripe Customer Portal URL (card, cancel, invoice download)").action(async () => {
+	await runAction(billingPortalCommand);
+});
+billing.command("set-ceiling <amount>").description("Cap the monthly bill at <amount> USD, or pass 'off' to remove the cap").action(async (amount) => {
+	let ceiling;
+	if (amount.toLowerCase() === "off" || amount === "") ceiling = null;
+	else {
+		const parsed = Number(amount);
+		if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1e5) {
+			console.log("  ✗ amount must be a number between 0 and 100000, or \"off\"");
+			process.exit(1);
+		}
+		ceiling = parsed;
+	}
+	await runAction(() => billingSetCeilingCommand({ ceiling }));
+});
 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));
@@ -5169,6 +7170,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));