@layers/amba 1.0.1 → 1.1.0

package/dist/index.js

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import pc from "picocolors";
-import { access, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { access, chmod, mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { createServer } from "node:http";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import open from "open";
-import { createWriteStream } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import { createWriteStream, watch } from "node:fs";
+import { spawn } from "node:child_process";
 import { build } from "esbuild";
-import { createHash } from "node:crypto";
 //#region src/_internal/shared.ts
 const DEFAULT_API_URL = "https://api.amba.dev";
 const CONSOLE_URL = "https://app.amba.dev";
@@ -73,11 +74,7 @@ function getReservationReason(name) {
 	return null;
 }
 const RESERVED_BINDING_PREFIXES = ["AMBA_", "EDGE_"];
-const RESERVED_BINDING_EXACT_NAMES = [
-	"STORAGE",
-	"HYPERDRIVE",
-	"EDGE_DB_PROXY"
-];
+const RESERVED_BINDING_EXACT_NAMES = ["STORAGE", "EDGE_DB_PROXY"];
 const VALID_BINDING_NAME_RE = /^[A-Z][A-Z0-9_]*$/;
 const MAX_BINDING_NAME_LENGTH = 64;
 /** Return why a binding name is reserved/invalid, or `null` if acceptable. */
@@ -559,7 +556,7 @@ async function updateSite(projectId, name, patch) {
 }
 /**
 * Add a custom domain to a site. The server-side proxy registers the
-* custom hostname, persists the resulting `cf_hostname_id`, and returns
+* custom hostname, persists the resulting `provider_hostname_id`, and returns
 * the CNAME target the customer should point their DNS at.
 */
 async function addSiteDomainViaApi(projectId, siteName, hostname) {
@@ -574,10 +571,10 @@ async function removeSiteDomainViaApi(projectId, siteName, hostname) {
 	return request("DELETE", `/projects/${projectId}/sites/${encodeURIComponent(siteName)}/domains/${encodeURIComponent(hostname)}`);
 }
 /**
-* Roll a live CF Pages deployment back to a prior `deployment_id`. CF's
-* rollback creates a NEW deployment that serves the prior bundle (git-
-* revert semantics, not git-reset), so the response shape mirrors
-* `DeploySiteResult` and the new `deployment_id` is what's now live.
+* Roll a live deployment back to a prior `deployment_id`. Rollback creates
+* a NEW deployment that serves the prior bundle (git-revert semantics,
+* not git-reset), so the response shape mirrors `DeploySiteResult` and
+* the new `deployment_id` is what's now live.
 */
 async function rollbackSiteViaApi(projectId, siteName, deploymentId) {
 	return request("POST", `/projects/${projectId}/sites/${encodeURIComponent(siteName)}/rollback`, { deployment_id: deploymentId });
@@ -811,6 +808,933 @@ async function generateContextFiles(opts) {
 	return files;
 }
 //#endregion
+//#region src/sandbox.ts
+/**
+* Headless agentic sandbox bootstrap.
+*
+* Implements `amba init --sandbox`: the zero-question, no-browser path
+* an AI coding agent runs when a developer pastes the homepage prompt:
+*
+*     Run `npx @layers/amba init --sandbox` and follow the
+*     instructions it prints.
+*
+* The CLI does everything: synthesize an anonymous email + password,
+* sign the developer up via the public `/v1/auth/developer/signup`
+* endpoint (no Bearer needed), pluck the returned PAT + project
+* credentials, and write them into:
+*
+*   - `~/.amba/credentials.json`     (chmod 0600)
+*   - `<cwd>/.env.local`             (.gitignored — SDK reads it)
+*   - `<cwd>/AMBA.md`                (markdown context for the agent)
+*   - every detected MCP client config (`~/.claude.json`,
+*     `~/.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`,
+*     plus their project-local equivalents WHEN already present —
+*     never created from scratch, to avoid cluttering repos)
+*
+* The MCP-config merge is non-destructive: an existing `mcpServers.amba`
+* entry is replaced with the new PAT, but the prior file is copied
+* aside to `<path>.bak-<unix-ms>` first so a developer who had a real
+* production PAT wired in can recover. Every other server entry is
+* preserved. JSON files that already exist but lack an `mcpServers`
+* key gain one; missing files for the global locations get scaffolded
+* with a minimal `{ "mcpServers": { "amba": … }}`.
+*
+* Similarly, a pre-existing `~/.amba/credentials.json` whose `source`
+* is not `'sandbox-init'` is backed up to `credentials.json.bak-<ms>`
+* before the sandbox PAT replaces it. Idempotent re-runs from our own
+* sandbox session do NOT trigger a backup.
+*
+* Provisioning polling: deliberately skipped. The server returns the
+* project row with `provisioning_status: 'provisioning'` immediately and
+* the workflow flips it to `'active'` within ~5s. The agent's next SDK
+* call may briefly retry — fine. Blocking the CLI here would just hide
+* the same wait behind a different progress indicator.
+*/
+/**
+* Generate a deterministic-looking but globally-unique sandbox email.
+*
+* Pattern: `sandbox-<epoch>-<6char>@layers.com`.
+*
+* The control DB's `developers` table has a UNIQUE(email) constraint and
+* a 5-per-minute / 50-per-day per-IP rate limit on signup. Embedding the
+* epoch + a 6-char nonce keeps the collision probability negligible even
+* across a herd of CI agents all running `amba init --sandbox` from the
+* same VPC.
+*
+* We use `@layers.com` (not the customer's own domain) because the
+* sandbox tier is pre-verification — the developer never receives or
+* actions a verification email for this address. When they want to
+* upgrade, the CLI prints the verify URL the API returned so they can
+* claim a real email in the console.
+*/
+function generateSandboxEmail() {
+	return `sandbox-${Math.floor(Date.now() / 1e3)}-${randomBytes(4).toString("base64url").slice(0, 6).toLowerCase()}@layers.com`;
+}
+/**
+* Random URL-safe password. 24 raw bytes → 32 base64url chars; well over
+* the 8-char minimum the API enforces, with ~192 bits of entropy.
+*
+* The password is never shown to the developer or written anywhere — the
+* PAT is what gets stored. We generate it solely because `POST /signup`
+* requires it (and demands a non-empty value); a future API change could
+* accept "agent signup" with no password and we'd drop this entirely.
+*/
+function generateSandboxPassword() {
+	return randomBytes(24).toString("base64url");
+}
+/**
+* POST the synthesized credentials at the public signup endpoint.
+*
+* No Bearer auth — this is the bootstrap call that mints one. We use
+* `fetch` directly (not the api-client wrapper) because that wrapper
+* always resolves a bearer token first, which is exactly what we don't
+* have yet.
+*
+* Returns the unwrapped, flattened shape consumed by the rest of the
+* sandbox flow. Throws with a human-readable message on any non-2xx so
+* the CLI's `runAction` wrapper can surface it without crashing on a
+* generic 'fetch failed'.
+*/
+async function performSandboxSignup(req, options = {}) {
+	const apiUrl = options.apiUrl ?? process.env["AMBA_API_URL"] ?? "https://api.amba.dev";
+	const res = await (options.fetchImpl ?? fetch)(`${apiUrl}/v1/auth/developer/signup`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"User-Agent": "amba-cli/sandbox"
+		},
+		body: JSON.stringify({
+			email: req.email,
+			password: req.password,
+			name: req.name ?? "amba-sandbox-cli"
+		})
+	});
+	if (!res.ok) {
+		let detail = `${res.status} ${res.statusText}`;
+		try {
+			const body = await res.json();
+			if (body.error?.message) detail = body.error.message;
+		} catch {}
+		throw new Error(`Sandbox signup failed: ${detail}`);
+	}
+	let raw;
+	try {
+		raw = await res.json();
+	} catch (parseErr) {
+		const reason = parseErr instanceof Error ? parseErr.message : String(parseErr);
+		throw new Error(`Sandbox signup returned ${res.status} but the response body was not valid JSON: ${reason}`);
+	}
+	const data = raw.data;
+	if (!data?.pat || !data.project?.project_id || !data.project.client_key) throw new Error("Sandbox signup response missing required fields (pat / project_id / client_key)");
+	return {
+		pat: data.pat,
+		project_id: data.project.project_id,
+		client_key: data.project.client_key,
+		server_key: data.project.server_key,
+		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
+	};
+}
+/**
+* Write or update `<cwd>/.env.local` with the sandbox project's keys.
+*
+* 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
+* fresh stanza.
+*/
+async function writeSandboxEnvLocal(cwd, projectId, clientKey, apiUrl) {
+	const envPath = join(cwd, ".env.local");
+	const stanza = [
+		"# Amba SDK configuration (sandbox tier)",
+		`AMBA_PROJECT_ID=${projectId}`,
+		`AMBA_CLIENT_KEY=${clientKey}`,
+		`AMBA_API_URL=${apiUrl}`,
+		""
+	].join("\n");
+	let existing = "";
+	try {
+		existing = await readFile(envPath, "utf-8");
+	} catch (err) {
+		if (!isEnoent(err)) throw err;
+	}
+	if (existing.length === 0) {
+		await writeFile(envPath, stanza, "utf-8");
+		return envPath;
+	}
+	if (/^AMBA_PROJECT_ID=/m.test(existing)) {
+		let updated = existing;
+		updated = updated.replace(/^AMBA_PROJECT_ID=.*/m, () => `AMBA_PROJECT_ID=${projectId}`);
+		updated = updated.replace(/^AMBA_API_URL=.*/m, () => `AMBA_API_URL=${apiUrl}`);
+		const hadClientKey = /^AMBA_CLIENT_KEY=/m.test(updated);
+		const hadApiKey = /^AMBA_API_KEY=/m.test(updated);
+		if (hadClientKey && hadApiKey) {
+			updated = updated.replace(/^AMBA_CLIENT_KEY=.*\n?/m, "");
+			updated = updated.replace(/^AMBA_API_KEY=.*/m, () => `AMBA_CLIENT_KEY=${clientKey}`);
+		} 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 (!/^AMBA_API_URL=/m.test(updated)) updated += (updated.endsWith("\n") ? "" : "\n") + `AMBA_API_URL=${apiUrl}\n`;
+		await writeFile(envPath, updated, "utf-8");
+		return envPath;
+	}
+	const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+	await writeFile(envPath, existing + separator + stanza, "utf-8");
+	return envPath;
+}
+/**
+* Write the AMBA.md sandbox-tier guide to `<cwd>/AMBA.md`.
+*
+* Always overwrites — the file is meant to be regenerated, and the
+* interactive `init` flow's longer AMBA.md template is replaced here
+* with a sandbox-specific shorter one (with upgrade instructions).
+*/
+async function writeSandboxAmbaMd(cwd, ctx) {
+	const ambaMdPath = join(cwd, "AMBA.md");
+	await writeFile(ambaMdPath, sandboxAmbaMdContent(ctx), "utf-8");
+	return ambaMdPath;
+}
+function sandboxAmbaMdContent(ctx) {
+	return `# Amba (Sandbox tier)
+
+This project was provisioned by \`amba init --sandbox\`. The sandbox is
+real (real database, real API, real MCP) but capped so you can try Amba
+without a credit card or email verification.
+
+## What was provisioned
+
+| Field | Value |
+| --- | --- |
+| Project ID | \`${ctx.projectId}\` |
+| Email | \`${ctx.email}\` |
+| API URL | \`${ctx.apiUrl}\` |
+| SDK | \`${ctx.sdkPackage}\` |
+| Framework | ${ctx.framework} |
+
+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.
+
+## SDK quickstart
+
+\`\`\`ts
+import { Amba } from '${ctx.sdkPackage}';
+
+Amba.configure({
+  projectId: process.env.AMBA_PROJECT_ID!,
+  clientKey: process.env.AMBA_CLIENT_KEY!,
+});
+
+await Amba.events.track('app_opened');
+\`\`\`
+
+## Sandbox limits
+
+| Limit | Sandbox | Free (after verification) |
+| --- | --- | --- |
+| Monthly active users | 100 | 1,000 |
+| Database size | 10 MB | 500 MB |
+| Push notifications / mo | 1,000 | 10,000 |
+
+## 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.`}
+
+## Useful commands
+
+\`\`\`bash
+amba status            # health check
+amba projects list     # list your sandbox project
+amba seed --preset=starter   # populate sample data
+\`\`\`
+
+Docs: https://docs.amba.dev
+`;
+}
+/**
+* The canonical Amba MCP entry. Used as the value of
+* `mcpServers.amba` in every detected client config.
+*
+* Shape note: Claude Code, Cursor, and Windsurf all read the same
+* `type` + `url` + `headers` triple. (Windsurf historically also
+* accepted `serverUrl` — we emit `url` to match the modern shape it
+* also accepts, and skip emitting the legacy alias to keep the JSON
+* minimal.)
+*/
+function buildAmbaMcpEntry(pat) {
+	return {
+		type: "http",
+		url: "https://mcp.amba.dev/mcp",
+		headers: { Authorization: `Bearer ${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.
+*
+* Project-local entries are listed but only get touched when the file
+* already exists in CWD — we don't want to scatter `.mcp.json` /
+* `.cursor/mcp.json` files into random user repos that have never been
+* MCP-configured.
+*/
+function mcpClientTargets(cwd, options = {}) {
+	const home = options.homeDir ?? homedir();
+	return [
+		{
+			label: "Claude Code (global)",
+			path: join(home, ".claude.json"),
+			scaffoldIfMissing: true
+		},
+		{
+			label: "Claude Code (project)",
+			path: join(cwd, ".mcp.json"),
+			scaffoldIfMissing: false
+		},
+		{
+			label: "Cursor (global)",
+			path: join(home, ".cursor", "mcp.json"),
+			scaffoldIfMissing: true
+		},
+		{
+			label: "Cursor (project)",
+			path: join(cwd, ".cursor", "mcp.json"),
+			scaffoldIfMissing: false
+		},
+		{
+			label: "Windsurf",
+			path: join(home, ".codeium", "windsurf", "mcp_config.json"),
+			scaffoldIfMissing: true
+		}
+	];
+}
+/**
+* Merge the `amba` entry into a single client config file.
+*
+* Strategy:
+*   - If the file exists, load + JSON-parse. If parse fails, throw with
+*     a clear "we won't clobber malformed JSON" error.
+*   - If the file doesn't exist and scaffolding is allowed, create the
+*     parent dir and write `{ "mcpServers": { "amba": ... } }`.
+*   - In all cases, `mcpServers.amba` ends up set; every other
+*     `mcpServers.*` entry is preserved.
+*
+* Real-credential safety: if the existing file ALREADY has a
+* `mcpServers.amba` entry, we copy the whole file aside to
+* `<path>.bak-<unix-ms>` BEFORE merging. This protects a developer who
+* had a real production PAT wired in and then ran `amba init --sandbox`
+* to "try" the flow. Idempotent re-runs from the same sandbox session
+* still trigger a backup — cheap, and the developer can `rm *.bak-*`
+* any time.
+*/
+async function mergeMcpConfigFile(target, pat) {
+	let existing = null;
+	let rawExisting = null;
+	try {
+		rawExisting = await readFile(target.path, "utf-8");
+		const parsed = JSON.parse(rawExisting);
+		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 (!target.scaffoldIfMissing) return {
+				path: null,
+				backedUpTo: null
+			};
+			existing = {};
+		} else if (err instanceof SyntaxError) throw new Error(`Refusing to overwrite malformed JSON at ${target.path}: ${err.message}. Fix the file or remove it, then re-run \`amba init --sandbox\`.`);
+		else throw err;
+	}
+	const config = existing ?? {};
+	const serversRaw = config["mcpServers"];
+	const servers = typeof serversRaw === "object" && serversRaw !== null && !Array.isArray(serversRaw) ? serversRaw : {};
+	let backedUpTo = null;
+	if ("amba" in servers && rawExisting !== null) {
+		backedUpTo = `${target.path}.bak-${Date.now()}`;
+		await writeFile(backedUpTo, rawExisting, "utf-8");
+	}
+	servers["amba"] = buildAmbaMcpEntry(pat);
+	config["mcpServers"] = servers;
+	await mkdir(dirname(target.path), { recursive: true });
+	await writeFile(target.path, JSON.stringify(config, null, 2) + "\n", "utf-8");
+	return {
+		path: target.path,
+		backedUpTo
+	};
+}
+/**
+* Probe every known MCP client location and merge our entry into the
+* ones that exist (or that are flagged scaffoldIfMissing). Returns one
+* record per touched file (skipped files are omitted).
+*
+* `warn` is invoked (instead of `console.warn`) for per-target errors
+* so callers using `--json` can route those notices to stderr and keep
+* stdout machine-parseable.
+*/
+async function writeAllMcpConfigs(cwd, pat, options = {}) {
+	const warn = options.warn ?? ((msg) => console.warn(msg));
+	const written = [];
+	const targets = mcpClientTargets(cwd, options);
+	for (const target of targets) {
+		let result = {
+			path: null,
+			backedUpTo: null
+		};
+		try {
+			if (!target.scaffoldIfMissing) {
+				if (!await fileExists$1(target.path)) continue;
+			}
+			result = await mergeMcpConfigFile(target, pat);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			warn(`  ! Skipped ${target.label}: ${message}`);
+			continue;
+		}
+		if (result.path) written.push({
+			path: result.path,
+			backedUpTo: result.backedUpTo
+		});
+	}
+	return written;
+}
+async function fileExists$1(path) {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function isEnoent(err) {
+	return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+}
+/**
+* Render the canonical Amba MCP snippet for clients we can't auto-wire
+* (anything outside the {Claude Code, Cursor, Windsurf} set). Printed by
+* the CLI when no client configs are detected so the developer at least
+* has a paste-ready JSON blob.
+*/
+function formatManualMcpSnippet(pat) {
+	return JSON.stringify({ mcpServers: { amba: buildAmbaMcpEntry(pat) } }, null, 2);
+}
+//#endregion
+//#region ../mcp/dist/expo-build-prompt.js
+/**
+* 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/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`).
+*
+* Drift between this constant and the MDX file is caught by
+* `expo-build-prompt.test.ts` — that test reads the MDX from disk,
+* strips the YAML frontmatter, and asserts it equals `EXPO_BUILD_PROMPT_MD`.
+*
+* **Update protocol:** edit the MDX (it's the human-facing surface;
+* it renders on docs.amba.dev). Re-run the drift test. The test will
+* fail with a diff. Apply the same diff here. The two are kept in
+* sync by hand because the MDX must be statically parseable for
+* fumadocs + we can't import `.md` files as raw strings without a
+* build-step that pulls in extra config.
+*
+* The body itself is plain CommonMark — no MDX components, no JSX —
+* 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).
+> If you're reading an inlined snapshot from your
+> \`.claude/skills/amba-build/SKILL.md\`, check the URL above for updates.
+
+This is the prompt an AI coding agent runs to build a full Expo app
+where Amba is the only backend. It's structured as a single \`/goal\`
+directive — paste it, replace \`<DESIGN_HASH>\` with whatever describes
+your design (a URL, a description, a Figma link), and let the agent
+execute.
+
+## Quick setup
+
+The CLI handles signup, project provisioning, env-file writes, and MCP
+client config wiring in one command:
+
+\`\`\`bash
+npx @layers/amba init --sandbox
+\`\`\`
+
+That's the entire setup. The CLI:
+
+1. Signs up an agent-mode developer account (no browser, no email
+   verification needed for sandbox).
+2. Creates an Amba project and mints a client key + admin PAT.
+3. Writes \`.env.local\` (\`AMBA_PROJECT_ID\`, \`AMBA_CLIENT_KEY\`,
+   \`AMBA_API_URL\`).
+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.
+
+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.
+
+If you have the \`/amba-build\` skill installed (via
+\`npx @layers/amba init --sandbox\`), invoke it directly:
+
+\`\`\`
+/amba-build <DESIGN_HASH>
+\`\`\`
+
+Otherwise paste the prompt below.
+
+## Current known gotchas
+
+Three remaining wrinkles you may hit. Everything else from the 2026-05
+DX cascade is fixed.
+
+- **Web CORS** — the public API does not currently send
+  \`Access-Control-Allow-Origin\` for browser-origin requests. Use the
+  agent's circuit-break-on-second-failure rule for web targets; for
+  Expo (iOS + Android) you'll never see this.
+- **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
+  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.
+
+## How to read the design
+
+If \`<DESIGN_HASH>\` is a URL to a packaged design (e.g. a download
+link from your design tool of choice), unpack it before you start:
+
+\`\`\`bash
+mkdir -p design && cd design
+curl -L "<DESIGN_HASH>" -o design.tar.gz
+gunzip -c design.tar.gz | tar -x
+ls
+# Expected: README, chats/, project/ (or equivalent)
+\`\`\`
+
+Read the README first — it should tell you what each subdirectory
+holds. The \`chats/\` directory typically contains conversation logs
+that capture the design intent in dialog form; treat them as the
+authoritative source for tone and feature priorities. The \`project/\`
+directory holds the structured asset graph (screens, components,
+styles).
+
+If \`<DESIGN_HASH>\` is a freeform description (not a URL), skip the
+unpacking and treat the description text as the design brief.
+
+## Use Amba for everything
+
+The rule: any feature that touches data, identity, scheduling,
+notifications, content, or social — use Amba. Don't reach for
+AsyncStorage-as-database, don't bring in Firebase / Supabase / your
+own server, don't roll a custom auth layer. The point of this build
+is that Amba covers it all.
+
+Specifically: every feature in the design that needs a backend maps
+to an Amba primitive. If you can't find a fit, the rule is **escalate
+in the gaps log** (see the verification gate), not "ship without
+Amba." Skipping a primitive needs a written justification — the
+verification gate enforces this.
+
+## Feature → Amba primitive map
+
+| App feature                                        | Amba primitive                          | MCP tools                                                                                                                                                                           |
+| -------------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| User accounts (anonymous + Apple + Google + email) | Auth                                    | \`amba_developer_signup\` (one-time bootstrap), \`Amba.signIn()\` SDK calls                                                                                                             |
+| Profile data (name, avatar, prefs)                 | App users                               | \`amba_users_list\`, \`amba_users_get\`, \`amba_users_bulk_update\`                                                                                                                       |
+| Daily content (tips, lessons, quotes)              | Content libraries + schedules           | \`amba_content_libraries_create\`, \`amba_content_items_add\`, \`amba_content_schedules_create\`, \`amba_content_list_libraries\`, \`amba_content_list_items\`, \`amba_content_list_schedules\` |
+| Push notifications                                 | Push campaigns                          | \`amba_push_campaigns_create\`, \`amba_push_campaigns_send\`, \`amba_push_send_test\`, \`amba_push_list_campaigns\`                                                                         |
+| User segments (e.g. inactive 7d, premium)          | Segments                                | \`amba_segments_create\`, \`amba_segments_list\`, \`amba_segments_evaluate\`                                                                                                              |
+| Daily streaks                                      | Streaks                                 | \`amba_streaks_create\`, \`amba_streaks_list\` (call \`streaks.qualify()\` from the SDK to record activity)                                                                               |
+| XP and levels                                      | XP rules                                | \`amba_xp_rules_create\`, \`amba_xp_rules_list\`, \`amba_users_get_xp\`                                                                                                                   |
+| Achievements / badges                              | Achievements                            | \`amba_achievements_create\`, \`amba_achievements_list\`, \`amba_achievements_get\`                                                                                                       |
+| Challenges (time-limited goals)                    | Challenges                              | \`amba_challenges_create\`, \`amba_challenges_list\`, \`amba_challenges_list_participants\`                                                                                               |
+| Leaderboards                                       | Leaderboards                            | \`amba_leaderboards_create\`, \`amba_leaderboards_list\`, \`amba_leaderboards_get\`                                                                                                       |
+| In-app currency / virtual goods                    | Economy (currencies + catalog + stores) | \`amba_currencies_create\`, \`amba_catalog_items_create\`, \`amba_stores_create\`, \`amba_currencies_grant\`, \`amba_users_get_inventory\`                                                    |
+| Social (friends, groups, feed, DMs)                | Social primitives                       | \`amba_create_group\`, \`amba_groups_list\`, \`amba_groups_update_member\`, \`amba_friendships_list\` (feeds + messaging via SDK: \`Amba.feeds.*\`, \`Amba.messaging.*\`)                       |
+| Remote feature flags / config                      | Configs                                 | \`amba_configs_create\`, \`amba_configs_list\`, \`amba_configs_update\`                                                                                                                   |
+| Entitlements (premium / paywall)                   | RevenueCat / Superwall integration      | \`amba_integrations_configure\`, \`amba_integrations_test\`                                                                                                                             |
+| Custom data (anything not above)                   | Collections                             | \`amba_collections_create\`, \`amba_collections_alter\`, \`amba_collections_list\`, \`amba_admin_insert_row\`, \`amba_admin_list_rows\`, plus client-side \`Amba.collections.*\`                |
+| Analytics / event tracking                         | Events                                  | \`Amba.events.track(...)\` from the SDK; query with \`amba_analytics_get\`, \`amba_users_list_events\`                                                                                    |
+
+Every primitive above has list / read MCP tools you can use to verify
+seed data after creation — the verification gate uses these to catch
+"fake implementation" failure modes (where the app code thinks a thing
+was created but nothing actually landed in the backend).
+
+## Seed data
+
+Before writing app code, seed the backend with enough data that every
+screen in the design has something realistic to render. Order:
+
+1. **Configs** — feature flags + tunable constants the app reads at
+   boot (\`amba_configs_create\`).
+2. **Segments** — at least one (e.g. "new_user", first 7 days) so
+   targeting works downstream.
+3. **Content libraries + schedules** — daily content for any
+   tips/quotes/lessons screen. Seed ≥30 items so the carousel /
+   day-stepper doesn't loop visibly.
+4. **Streaks** — define the streak shape (daily / weekly, grace
+   window, freeze policy).
+5. **XP rules** — events → XP-award rules so XP accrues from real
+   gameplay.
+6. **Achievements** — unlock criteria for badges.
+7. **Challenges** — at least one active challenge with rewards.
+8. **Leaderboards** — XP, streaks, or any custom metric.
+9. **Currencies + catalog + stores** — virtual currency, catalog
+   items, store listings (only if the design has an economy screen).
+10. **Collections** — schemas + sample rows for any custom data the
+    app needs (e.g. user-generated content, journal entries, custom
+    list items).
+11. **Push campaigns** — at least one welcome push + one re-engagement
+    push targeting your "new_user" segment.
+
+After seeding, the verification gate (below) confirms each primitive
+exists by calling the matching \`amba_*_list\` MCP tool. Empty list →
+failure.
+
+## Engineering rules
+
+These are non-negotiable. Violating any one of them fails the build
+gate.
+
+- **Expo Router with typed routes.** Use \`expo-router\` and enable
+  \`experiments.typedRoutes\` in \`app.json\`. Every screen is a
+  filesystem route; no manual navigation stacks.
+- **TypeScript strict mode.** \`strict: true\` in \`tsconfig.json\`. Zero
+  \`any\`. Zero \`@ts-ignore\`. \`tsc --noEmit\` must pass.
+- **React Native primitives only.** \`View\`, \`Text\`, \`Pressable\`,
+  \`ScrollView\`, \`FlatList\`, \`Image\`. No \`div\`, no \`span\`, no DOM-only
+  libs. The build target is iOS + Android + Web — every screen has to
+  render on all three.
+- **Fonts via expo-font.** Don't ship system-font-only screens; load
+  the design's typography via \`useFonts\` and gate the splash screen
+  on load.
+- **Persistence via AsyncStorage.** Anything you cache client-side
+  (theme choice, last-viewed-item, dismissed banners) goes in
+  AsyncStorage. Never sprinkle direct file I/O.
+- **Theme system.** A single \`theme.ts\` exports light + dark token
+  maps; consume via a \`useTheme()\` hook. The verification gate
+  toggles light ↔ dark and screenshots; if any screen has hardcoded
+  colors that don't flip, the gate fails.
+- **Circuit-break on second failure.** If two consecutive Amba API
+  calls fail with the same error, stop retrying and surface a clean
+  empty-state to the user. Don't loop forever; don't crash. The web
+  CORS issue (above) is the most likely trigger.
+- **Deterministic offline fallback.** When \`fetch\` fails (airplane
+  mode, network drop), the app renders **deterministic** placeholder
+  content — same content per \`userId + day\` — never random. Real data
+  swaps in when the network returns.
+- **Three-platform bundle gate.** \`expo export --platform web\`,
+  \`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.
+
+## Verification gate
+
+Before declaring the build done, run every check in this list. Any
+failure means the build is not done — fix and re-run.
+
+\`\`\`bash
+# Type-check
+pnpm tsc --noEmit
+
+# Three-platform export
+pnpm expo export --platform web
+pnpm expo export --platform ios
+pnpm expo export --platform android
+\`\`\`
+
+Then, from inside the agent (use the Amba MCP tools):
+
+- \`amba_analytics_get\` → at least one event tracked end-to-end
+  through \`Amba.events.track()\` from the app.
+- \`amba_users_list\` → at least one user exists (the agent's own
+  anonymous signin counts).
+- For every primitive the seed step created, call the matching
+  \`amba_*_list\` and assert non-empty:
+  - \`amba_configs_list\`
+  - \`amba_segments_list\`
+  - \`amba_content_list_libraries\`, \`amba_content_list_items\`,
+    \`amba_content_list_schedules\`
+  - \`amba_streaks_list\`
+  - \`amba_xp_rules_list\`
+  - \`amba_achievements_list\`
+  - \`amba_challenges_list\`
+  - \`amba_leaderboards_list\`
+  - \`amba_currencies_list\` (if economy seeded)
+  - \`amba_catalog_list\` (if catalog seeded)
+  - \`amba_collections_list\` + \`amba_admin_list_rows\` per collection
+  - \`amba_push_list_campaigns\`
+- Empty list for any seeded primitive → the implementation is fake
+  (UI exists but never wrote to the backend). Failure.
+- Manually walk every route in the browser (\`expo start --web\`),
+  screenshot each, and confirm:
+  - Light theme renders cleanly.
+  - Dark theme renders cleanly (toggle and re-screenshot every
+    route).
+  - Empty states render when collections are empty (fresh-install
+    simulation: wipe AsyncStorage, reload).
+- \`amba_users_reset_sandbox\` to confirm you can recover from the MAU
+  cap if you blew past 50 during testing.
+
+Skipping any primitive's seed step requires a one-line written
+justification in the gaps log (next section). "We don't need
+streaks" is fine; silence is not.
+
+## Final output
+
+When done, write a final report to \`BUILD_REPORT.md\` in the project
+root. Required sections:
+
+- **Start timestamp** (when the agent started).
+- **End timestamp** (when the verification gate last passed).
+- **MCP call inventory** — every \`amba_*\` tool you invoked, with a
+  count. Lets a human reviewer audit "did this agent actually use
+  Amba for X" at a glance.
+- **Primitive coverage table** — one row per primitive from the
+  Feature → Amba primitive map. Mark each ✅ (used), ⚠️ (used with
+  caveats — explain), or ⏭ (skipped — justify in one line).
+- **Gaps log** — every primitive you skipped, every feature you
+  couldn't fit cleanly to an Amba primitive, every workaround. One
+  line per gap, no marketing language.
+- **\`seed-report.json\`** — machine-readable seed summary:
+  \`{ "primitive": "<name>", "created": <count>, "listed": <count> }\`
+  for every primitive. The \`listed\` count comes from the
+  \`amba_*_list\` call in the verification gate. \`created ===
+listed\` for every row is the success condition.
+
+If \`BUILD_REPORT.md\` is missing any required section, or
+\`seed-report.json\` is missing, the build is not done.
+`;
+//#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.
+*/
+/**
+* Build the contents of `.claude/skills/amba-build/SKILL.md`.
+*
+* 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 `---
+description: Canonical /goal prompt for building a full Expo app with Amba as the only backend. Use as a starter when integrating Amba — Claude Code, Cursor, Windsurf.
+---
+
+# /amba-build
+
+When invoked, fetch the canonical prompt from
+\`https://docs.amba.dev/docs/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
+prompt before executing.
+
+## Usage
+
+\`\`\`
+/amba-build <DESIGN_HASH>
+\`\`\`
+
+Replace \`<DESIGN_HASH>\` with:
+
+- A URL to a packaged design tarball, OR
+- A freeform description of the design intent.
+
+## Fetcher
+
+\`\`\`bash
+curl -sf https://docs.amba.dev/docs/prompts/expo-build.md
+\`\`\`
+
+If \`curl\` fails (404, 5xx, network error, no internet), fall back to
+the **inlined snapshot** below — it was captured at CLI install time
+and is a complete, self-contained version of the prompt.
+
+When the fetcher succeeds, prefer the live version: it's the source of
+truth and may have been updated since this skill was installed.
+
+## Inlined snapshot
+
+The block between the AMBA-BUILD-PROMPT-START / -END markers is the
+prompt content captured at CLI install time. Re-run
+\`npx @layers/amba init --sandbox\` (or a future \`amba update-skills\`
+command) to refresh.
+
+<!-- AMBA-BUILD-PROMPT-START -->
+${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.
+*/
+async function writeAmbaBuildSkill(options = {}) {
+	const skillDir = join(options.baseDir ?? process.cwd(), ".claude", "skills", "amba-build");
+	await mkdir(skillDir, { recursive: true });
+	const skillPath = join(skillDir, "SKILL.md");
+	await writeFile(skillPath, buildAmbaBuildSkillContent(), "utf-8");
+	return { path: skillPath };
+}
+//#endregion
 //#region src/commands/init.ts
 function prompt(question) {
 	const rl = createInterface({
@@ -923,6 +1847,18 @@ Docs: https://docs.amba.dev
 }
 async function initCommand(options = {}) {
 	const cwd = process.cwd();
+	if (options.sandbox) {
+		const result = await runSandboxInit(cwd, {
+			sandboxEmail: options.sandboxEmail,
+			noMcpConfig: options.noMcpConfig,
+			noSkills: options.noSkills,
+			json: options.json,
+			homeDir: options.homeDir
+		});
+		if (options.json) process.stdout.write(JSON.stringify(sandboxResultToJson(result), null, 2) + "\n");
+		else printSandboxNextSteps(result);
+		return;
+	}
 	const environment = options.env ?? "development";
 	console.log();
 	console.log(pc.bold("  amba init"));
@@ -1092,6 +2028,159 @@ async function initCommand(options = {}) {
 	console.log(`  Docs: ${pc.underline("https://docs.amba.dev")}`);
 	console.log();
 }
+async function runSandboxInit(cwd, options) {
+	if (!options.json) {
+		console.log();
+		console.log(pc.bold("  amba init --sandbox"));
+		console.log(pc.dim("  ─────────────────────────────────"));
+		console.log();
+	}
+	const signup = await performSandboxSignup({
+		email: options.sandboxEmail?.trim() || generateSandboxEmail(),
+		password: generateSandboxPassword()
+	});
+	const envLocalPath = await writeSandboxEnvLocal(cwd, signup.project_id, signup.client_key, signup.api_url);
+	const framework = await detectFramework(cwd);
+	const sdkPackage = getSdkPackage(framework);
+	const ambaMdPath = await writeSandboxAmbaMd(cwd, {
+		projectId: signup.project_id,
+		email: signup.email,
+		verifyUrl: signup.verify_url ?? null,
+		sdkPackage,
+		framework,
+		apiUrl: signup.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, {
+		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)}`);
+	}
+	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,
+		envLocalPath,
+		ambaMdPath,
+		mcpConfigsWritten,
+		sdkPackage,
+		framework,
+		verifyUrl: signup.verify_url ?? null,
+		provisioningStatus: signup.provisioning_status ?? "unknown",
+		skillPath
+	};
+}
+function sandboxResultToJson(r) {
+	return {
+		ok: true,
+		mode: "sandbox",
+		email: r.email,
+		project_id: r.projectId,
+		pat_preview: r.patPreview,
+		client_key: r.clientKey,
+		api_url: r.apiUrl,
+		framework: r.framework,
+		sdk_package: r.sdkPackage,
+		credentials_path: r.credentialsPath,
+		credentials_backed_up_to: r.credentialsBackedUpTo,
+		env_local_path: r.envLocalPath,
+		amba_md_path: r.ambaMdPath,
+		mcp_configs_written: r.mcpConfigsWritten.map((m) => ({
+			path: m.path,
+			backed_up_to: m.backedUpTo
+		})),
+		skill_path: r.skillPath,
+		verify_url: r.verifyUrl,
+		provisioning_status: r.provisioningStatus,
+		next_steps: ["restart your MCP client"]
+	};
+}
+/**
+* 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.
+*/
+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("");
+		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);
+	console.log();
+}
 //#endregion
 //#region src/commands/login.ts
 async function loginCommand() {
@@ -2262,6 +3351,61 @@ async function schemaExportCommand(opts) {
 	process.stdout.write(output);
 }
 //#endregion
+//#region src/project-config.ts
+/**
+* Local project config loader.
+*
+* `amba init` writes `.env.local` with `AMBA_PROJECT_ID` + `AMBA_API_KEY`.
+* Subsequent commands resolve the active project by reading `.env.local`
+* (or the OS env if exported); fail with a clear "run amba init first"
+* error if neither is set.
+*
+* Kept tiny on purpose — the CLI's full config story (per-environment
+* dev/prod selection) is a v2 follow-up; v1 just needs project id.
+*/
+const ENV_LOCAL_FILES = [".env.local", ".env"];
+async function loadProjectConfig(cwd = process.cwd()) {
+	let projectId = process.env["AMBA_PROJECT_ID"];
+	let apiUrl = process.env["AMBA_API_URL"];
+	if (!projectId || !apiUrl) for (const filename of ENV_LOCAL_FILES) {
+		const content = await readFile(join(cwd, filename), "utf-8").catch(() => null);
+		if (!content) continue;
+		const parsed = parseEnv(content);
+		if (!projectId) projectId = parsed["AMBA_PROJECT_ID"];
+		if (!apiUrl) apiUrl = parsed["AMBA_API_URL"];
+		if (projectId && apiUrl) break;
+	}
+	if (!projectId) throw new Error(`AMBA_PROJECT_ID not found. Run ${pc.cyan("amba init")} or set it in .env.local.`);
+	return {
+		projectId,
+		apiUrl: apiUrl ?? "https://api.amba.dev"
+	};
+}
+/**
+* Parse a `.env`-style file body into a flat string map.
+*
+* Lines are trimmed; blank lines and `#`-comments are skipped; lines
+* without an `=` are skipped. Values may be wrapped in matching single
+* or double quotes which are stripped on read. Bug fixes should land
+* here once — both `project-config.ts` (resolves `AMBA_PROJECT_ID`)
+* and `commands/functions.ts` (loads `.env.local` for the local dev
+* server) call this.
+*/
+function parseEnv(content) {
+	const out = {};
+	for (const rawLine of content.split("\n")) {
+		const line = rawLine.trim();
+		if (!line || line.startsWith("#")) continue;
+		const eq = line.indexOf("=");
+		if (eq === -1) continue;
+		const key = line.slice(0, eq).trim();
+		let value = line.slice(eq + 1).trim();
+		if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
+		out[key] = value;
+	}
+	return out;
+}
+//#endregion
 //#region src/bundle.ts
 /**
 * Customer-function bundling for `amba functions deploy`.
@@ -2370,51 +3514,6 @@ function formatBytes$1(n) {
 	return `${(n / 1024 / 1024).toFixed(2)}MB`;
 }
 //#endregion
-//#region src/project-config.ts
-/**
-* Local project config loader.
-*
-* `amba init` writes `.env.local` with `AMBA_PROJECT_ID` + `AMBA_API_KEY`.
-* Subsequent commands resolve the active project by reading `.env.local`
-* (or the OS env if exported); fail with a clear "run amba init first"
-* error if neither is set.
-*
-* Kept tiny on purpose — the CLI's full config story (per-environment
-* dev/prod selection) is a v2 follow-up; v1 just needs project id.
-*/
-const ENV_LOCAL_FILES = [".env.local", ".env"];
-async function loadProjectConfig(cwd = process.cwd()) {
-	let projectId = process.env["AMBA_PROJECT_ID"];
-	let apiUrl = process.env["AMBA_API_URL"];
-	if (!projectId || !apiUrl) for (const filename of ENV_LOCAL_FILES) {
-		const content = await readFile(join(cwd, filename), "utf-8").catch(() => null);
-		if (!content) continue;
-		const parsed = parseEnv(content);
-		if (!projectId) projectId = parsed["AMBA_PROJECT_ID"];
-		if (!apiUrl) apiUrl = parsed["AMBA_API_URL"];
-		if (projectId && apiUrl) break;
-	}
-	if (!projectId) throw new Error(`AMBA_PROJECT_ID not found. Run ${pc.cyan("amba init")} or set it in .env.local.`);
-	return {
-		projectId,
-		apiUrl: apiUrl ?? "https://api.amba.dev"
-	};
-}
-function parseEnv(content) {
-	const out = {};
-	for (const rawLine of content.split("\n")) {
-		const line = rawLine.trim();
-		if (!line || line.startsWith("#")) continue;
-		const eq = line.indexOf("=");
-		if (eq === -1) continue;
-		const key = line.slice(0, eq).trim();
-		let value = line.slice(eq + 1).trim();
-		if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
-		out[key] = value;
-	}
-	return out;
-}
-//#endregion
 //#region src/commands/functions.ts
 /**
 * `amba functions ...` commands.
@@ -2447,7 +3546,7 @@ async function functionsDeployCommand(entryPoint, options = {}) {
 		bundleCode: bundle.code,
 		rate_limit: rateLimit
 	});
-	console.log(pc.green("  ✓") + ` Deployed ${pc.cyan(functionName)} ${pc.dim(`v${result.data.version} (${result.data.cf_script_name})`)}`);
+	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`));
 	console.log();
@@ -2465,10 +3564,10 @@ async function functionsListCommand() {
 }
 async function functionsDeleteCommand(name, options = {}) {
 	validateFunctionName(name);
-	if (!options.confirm || options.confirm !== name) throw new Error(`Delete is destructive. Pass --confirm ${name} to proceed. Customer Workers calling this function will start 404'ing immediately.`);
+	if (!options.confirm || options.confirm !== name) throw new Error(`Delete is destructive. Pass --confirm ${name} to proceed. Clients calling this function will start 404'ing immediately.`);
 	const cascade = (await deleteFunctionViaApi((await loadProjectConfig()).projectId, name, { confirm: name })).data.cascade;
 	console.log(pc.green("  ✓") + ` Deleted ${pc.bold(name)}.`);
-	console.log(pc.dim(`    Cascade: cf_dispatch_script_deleted=${cascade.cf_dispatch_script_deleted ?? false}, function_deployments_marked_disabled=${cascade.function_deployments_marked_disabled ?? 0}`));
+	console.log(pc.dim(`    Cascade: runtime_script_removed=${cascade.runtime_script_removed ?? false}, function_deployments_marked_disabled=${cascade.function_deployments_marked_disabled ?? 0}`));
 }
 async function functionsScheduleCommand(name, cron, options = {}) {
 	const projectConfig = await loadProjectConfig();
@@ -2485,15 +3584,364 @@ async function functionsScheduleCommand(name, cron, options = {}) {
 	console.log();
 }
 /**
-* `amba functions dev` — not configured in this release. Use
-* `amba functions deploy <file>` to deploy via the platform API.
+* `amba functions dev <file>` — run the function locally with file-change
+* hot reload.
+*
+* Architecture: the CLI process owns the file watcher + bundler; the
+* actual HTTP server lives in a child Node process that imports the
+* bundle and binds to the user's port. On file change, the parent kills
+* the child, writes a fresh bundle, and respawns. This bounds memory
+* (each rebuild = fresh V8 heap) and isolates customer-handler crashes
+* from the CLI. Brief downtime per rebuild (~100ms while the port is
+* released and re-bound); incoming connections during the swap queue
+* at the TCP listen backlog and complete once the new child is up.
+*
+* The bundler is the same esbuild pipeline `amba functions deploy` uses
+* — 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>`.
+* `.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).
 */
-async function functionsDevCommand(_entryPoint) {
-	console.error(pc.red("  Error: `amba functions dev` is not available in this release."));
-	console.error(pc.dim("    Use `amba functions deploy <file>` to deploy via the platform API."));
-	process.exit(1);
+async function functionsDevCommand(entryPoint, options = {}) {
+	const port = validatePort(options.port);
+	const resolvedEntry = resolve(entryPoint);
+	const childEnv = {
+		...await loadEnvLocal(),
+		...process.env
+	};
+	const tmpRoot = await mkdtemp(join(tmpdir(), "amba-fn-dev-"));
+	const bundlePath = join(tmpRoot, "fn.mjs");
+	const runnerPath = join(tmpRoot, "runner.mjs");
+	await writeFile(runnerPath, DEV_RUNNER_SOURCE, "utf8");
+	let child = null;
+	let buildSeq = 0;
+	let shuttingDown = false;
+	let inFlightRebuild = null;
+	let rebuildQueue = Promise.resolve(true);
+	const scheduleRebuild = () => {
+		rebuildQueue = rebuildQueue.then(() => rebuildLocked());
+		inFlightRebuild = rebuildQueue;
+		return rebuildQueue;
+	};
+	/**
+	* Returns true when the child was spawned and serving on the port,
+	* false on any failure path. The caller decides whether to surface a
+	* "server is listening" banner based on that — a green checkmark
+	* after a red error would mislead users.
+	*/
+	async function rebuildLocked() {
+		buildSeq++;
+		const seq = buildSeq;
+		let bundleResult;
+		try {
+			bundleResult = await bundleFunction({
+				entryPoint: resolvedEntry,
+				sourcemap: "inline"
+			});
+		} catch (err) {
+			console.error(pc.red("  Bundle failed:"), err instanceof Error ? err.message : String(err));
+			return false;
+		}
+		if (seq !== buildSeq || shuttingDown) return false;
+		try {
+			await writeFile(bundlePath, bundleResult.code, "utf8");
+		} catch (err) {
+			console.error(pc.red("  Write failed:"), err instanceof Error ? err.message : String(err));
+			return false;
+		}
+		if (seq !== buildSeq || shuttingDown) return false;
+		if (child) {
+			const prev = child;
+			prev.kill("SIGTERM");
+			await waitForChildExit(prev, 2e3);
+			if (child === prev) child = null;
+		}
+		if (seq !== buildSeq || shuttingDown) return false;
+		const next = spawn(process.execPath, [
+			runnerPath,
+			bundlePath,
+			String(port)
+		], {
+			env: childEnv,
+			stdio: [
+				"ignore",
+				"pipe",
+				"inherit"
+			]
+		});
+		let spawnError = null;
+		next.on("error", (err) => {
+			spawnError = err;
+		});
+		try {
+			await waitForChildReady(next, 5e3);
+		} catch (err) {
+			const cause = spawnError ?? (err instanceof Error ? err : new Error(String(err)));
+			console.error(pc.red("  Child failed to start:"), cause.message);
+			next.kill("SIGKILL");
+			return false;
+		}
+		if (spawnError) {
+			console.error(pc.red("  Child failed to start:"), spawnError.message);
+			next.kill("SIGKILL");
+			return false;
+		}
+		if (seq !== buildSeq || shuttingDown) {
+			next.kill("SIGTERM");
+			return false;
+		}
+		child = next;
+		next.stdout?.on("data", (chunk) => process.stdout.write(chunk));
+		next.on("exit", (code, signal) => {
+			if (child === next && !shuttingDown && signal !== "SIGTERM") {
+				console.error(pc.red(`  Child exited unexpectedly (code=${code}, signal=${signal ?? "none"})`));
+				child = null;
+			}
+		});
+		console.log(pc.green("  ✓") + pc.dim(` bundle ready — ${bundleResult.uncompressedSize} bytes (${bundleResult.sha256.slice(0, 12)}…)`));
+		return true;
+	}
+	const initialOk = await scheduleRebuild();
+	let watcherCloser = null;
+	let pendingRebuildTimer = null;
+	if (!options.noWatch) {
+		const watcher = watch(resolvedEntry, () => {
+			if (shuttingDown) return;
+			if (pendingRebuildTimer) clearTimeout(pendingRebuildTimer);
+			pendingRebuildTimer = setTimeout(() => {
+				pendingRebuildTimer = null;
+				if (shuttingDown) return;
+				console.log(pc.dim("\n  ↻ file changed — rebuilding"));
+				scheduleRebuild();
+			}, 100);
+		});
+		watcherCloser = () => watcher.close();
+	}
+	console.log();
+	if (initialOk) console.log(pc.green("  ✓") + ` Local dev server: ${pc.underline(`http://localhost:${port}`)}`);
+	else console.log(pc.yellow("  !") + " Dev server is NOT listening — fix the bundle / handler errors above and save the file.");
+	console.log(pc.dim(`    Entry: ${entryPoint}`));
+	if (!options.noWatch) console.log(pc.dim("    Watching for changes. Ctrl+C to stop."));
+	console.log();
+	const shutdown = async (exitCode = 0) => {
+		if (shuttingDown) return;
+		shuttingDown = true;
+		if (pendingRebuildTimer) clearTimeout(pendingRebuildTimer);
+		watcherCloser?.();
+		if (inFlightRebuild) try {
+			await inFlightRebuild;
+		} catch {}
+		if (child) {
+			const c = child;
+			child = null;
+			c.kill("SIGTERM");
+			await waitForChildExit(c, 2e3);
+		}
+		await rm(tmpRoot, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+		process.exit(exitCode);
+	};
+	process.on("SIGINT", () => void shutdown(0));
+	process.on("SIGTERM", () => void shutdown(0));
+	process.on("SIGHUP", () => void shutdown(0));
+	process.on("uncaughtException", (err) => {
+		console.error(pc.red("  Uncaught exception in CLI:"), err);
+		shutdown(1);
+	});
+	process.on("unhandledRejection", (err) => {
+		console.error(pc.red("  Unhandled rejection in CLI:"), err);
+		shutdown(1);
+	});
+}
+/**
+* Validate `--port` value. Defaults to 8787 when unset. Rejects
+* non-integers, ports below 1024 (which need root on POSIX), and
+* anything above 65535. Bailing here means the spawned child never
+* gets a NaN port that quietly picks a random ephemeral port — that
+* was confusing for customers ("the banner says :NaN").
+*/
+function validatePort(raw) {
+	if (raw === void 0) return 8787;
+	if (!Number.isInteger(raw) || raw < 1 || raw > 65535) throw new Error(`Invalid --port ${raw}; must be an integer between 1 and 65535`);
+	if (raw < 1024) throw new Error(`--port ${raw} is in the privileged range (<1024) and would need root on POSIX. Pick a port ≥ 1024.`);
+	return raw;
+}
+/**
+* Reads `.env.local` from the current working directory (if present)
+* and returns the parsed KEY → VALUE map. Uses the shared `parseEnv`
+* from `project-config.ts` so any fix to the parser propagates here
+* automatically.
+*/
+async function loadEnvLocal() {
+	try {
+		return parseEnv(await readFile(".env.local", "utf8"));
+	} catch {
+		return {};
+	}
+}
+/**
+* Wait for a child process to print `AMBA_DEV_READY` on stdout (the
+* marker emitted by `DEV_RUNNER_SOURCE` once its HTTP server has bound
+* to the port). Rejects if the child exits before the marker arrives
+* or the timeout elapses.
+*/
+function waitForChildReady(child, timeoutMs) {
+	return new Promise((resolveReady, rejectReady) => {
+		let buffered = "";
+		let settled = false;
+		const settle = (fn) => {
+			if (settled) return;
+			settled = true;
+			child.stdout?.off("data", onData);
+			child.off("exit", onExit);
+			clearTimeout(timer);
+			fn();
+		};
+		const onData = (chunk) => {
+			buffered += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+			const idx = buffered.indexOf("AMBA_DEV_READY\n");
+			if (idx === -1) return;
+			const before = buffered.slice(0, idx);
+			const after = buffered.slice(idx + 15);
+			if (before.length > 0) process.stdout.write(before);
+			if (after.length > 0) process.stdout.write(after);
+			settle(() => resolveReady());
+		};
+		const onExit = (code, signal) => {
+			settle(() => rejectReady(/* @__PURE__ */ new Error(`child exited before ready (code=${code}, signal=${signal ?? "-"})`)));
+		};
+		const timer = setTimeout(() => {
+			settle(() => rejectReady(/* @__PURE__ */ new Error(`timed out after ${timeoutMs}ms waiting for child ready`)));
+		}, timeoutMs);
+		child.stdout?.on("data", onData);
+		child.on("exit", onExit);
+	});
+}
+/**
+* Wait for a child to exit. If `timeoutMs` elapses first, SIGKILL it
+* and resolve anyway — the caller doesn't care which path closed the
+* port, only that it's closed.
+*/
+function waitForChildExit(child, timeoutMs) {
+	return new Promise((resolveExit) => {
+		if (child.exitCode !== null || child.signalCode !== null) return resolveExit();
+		const timer = setTimeout(() => {
+			child.kill("SIGKILL");
+		}, timeoutMs);
+		child.once("exit", () => {
+			clearTimeout(timer);
+			resolveExit();
+		});
+	});
 }
 /**
+* The script the child Node process runs. Bound as a string template
+* so the parent CLI ships with no separate file to package. The runner
+* imports the bundle once at startup (so the V8 heap holds exactly one
+* version of the customer code) and serves it on the user's port.
+*
+* READY handshake: the runner writes `AMBA_DEV_READY\n` to stdout once
+* `server.listen()` calls back — the parent uses that to gate killing
+* the previous child.
+*/
+const DEV_RUNNER_SOURCE = `
+import { createServer } from 'node:http';
+import { pathToFileURL } from 'node:url';
+
+const bundlePath = process.argv[2];
+const port = Number(process.argv[3]);
+const parentPid = process.ppid;
+
+// Parent-pid watchdog. If the CLI gets SIGKILL'd or its terminal
+// closes without delivering SIGHUP, the parent's signal handlers
+// don't run and this child would orphan — keep holding the port,
+// keep serving stale code. Polling ppid every 2s catches the orphan
+// case: when the parent dies, the OS reparents us (ppid changes,
+// becomes 1 on POSIX). On a clean SIGTERM from the parent, the
+// signal handler at the bottom exits us first so this never fires.
+setInterval(() => {
+  if (process.ppid !== parentPid) {
+    process.stderr.write('  Parent CLI is gone; exiting child to free port.\\n');
+    process.exit(0);
+  }
+}, 2000).unref();
+
+let handler;
+try {
+  // Node's ESM \`import()\` requires a URL on Windows — a raw absolute
+  // path like C:\\\\foo\\\\bar.mjs throws ERR_UNSUPPORTED_ESM_URL_SCHEME.
+  // \`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');
+    process.exit(2);
+  }
+  handler = mod.default;
+} catch (err) {
+  process.stderr.write('  Bundle import failed: ' + (err && err.stack ? err.stack : err) + '\\n');
+  process.exit(2);
+}
+
+const server = createServer(async (req, res) => {
+  try {
+    const proto = req.socket && req.socket.encrypted ? 'https' : 'http';
+    const url = proto + '://' + (req.headers.host || 'localhost') + (req.url || '/');
+    const headers = new Headers();
+    for (const [k, v] of Object.entries(req.headers)) {
+      if (typeof v === 'string') headers.set(k, v);
+      else if (Array.isArray(v)) for (const vv of v) headers.append(k, vv);
+    }
+    let body = null;
+    if (req.method && req.method !== 'GET' && req.method !== 'HEAD') {
+      const chunks = [];
+      for await (const chunk of req) chunks.push(chunk);
+      body = Buffer.concat(chunks);
+    }
+    const request = new Request(url, { method: req.method, headers, body });
+    const response = await handler(request);
+    res.statusCode = response.status;
+    response.headers.forEach((value, key) => res.setHeader(key, value));
+    res.end(Buffer.from(await response.arrayBuffer()));
+  } catch (err) {
+    process.stderr.write('  Handler error: ' + (err && err.stack ? err.stack : err) + '\\n');
+    if (!res.headersSent) {
+      res.statusCode = 500;
+      res.setHeader('content-type', 'text/plain; charset=utf-8');
+    }
+    res.end('Internal Server Error');
+  }
+});
+
+server.on('error', (err) => {
+  process.stderr.write('  Server error: ' + (err && err.message ? err.message : err) + '\\n');
+  process.exit(3);
+});
+
+// Bind to 127.0.0.1 explicitly so the dev server is loopback-only.
+// Node's default \`server.listen(port)\` binds 0.0.0.0 (or ::), which
+// exposes the local handler — potentially reading secrets from
+// .env.local — to every device on the same Wi-Fi. The banner says
+// "localhost" so the customer's mental model expects local-only;
+// match that. Aligns with Vite / wrangler / next dev defaults.
+server.listen(port, '127.0.0.1', () => {
+  process.stdout.write('AMBA_DEV_READY\\n');
+});
+
+const shutdown = (signal) => {
+  server.close(() => process.exit(0));
+  setTimeout(() => process.exit(0), 1000).unref();
+};
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+`;
+/**
 * `amba functions consume <queue> <function>` — bind a function as the
 * consumer for a queue. Customers send to a queue with `ctx.queue.send`;
 * the genericQueueJobWorkflow looks up the binding and invokes the
@@ -3238,10 +4686,9 @@ 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).`);
 }
 /**
-* Per-deploy size cap. CF Pages enforces 25 MiB per file + 25k files; we
-* pre-flight at 100 MiB total so the developer sees an actionable error
-* before we spend their time on a multi-second upload. Above this, point
-* them at a Pages-only deployment outside amba.
+* Per-deploy size cap. The hosting provider enforces 25 MiB per file +
+* 25k files; we pre-flight at 100 MiB total so the developer sees an
+* actionable error before we spend their time on a multi-second upload.
 */
 const MAX_DEPLOYMENT_BYTES = 100 * 1024 * 1024;
 const MAX_DEPLOYMENT_FILES = 2e4;
@@ -3264,23 +4711,23 @@ async function sitesDeployCommand(inputDir, options = {}) {
 	if (totalBytes > MAX_DEPLOYMENT_BYTES) throw new Error(`Deployment too large (${formatBytes(totalBytes)} > ${formatBytes(MAX_DEPLOYMENT_BYTES)}). Trim assets or split into multiple sites.`);
 	console.log(pc.dim(`    ${files.length} files, ${formatBytes(totalBytes)}`));
 	if (options.dryRun) {
-		console.log(pc.yellow("  ! Dry run — skipping CF Pages upload + control-plane write."));
+		console.log(pc.yellow("  ! Dry run — skipping upload + control-plane write."));
 		console.log();
 		return;
 	}
-	let cfPagesProjectName;
+	let slug;
 	try {
-		cfPagesProjectName = (await createSite(projectId, { name: siteName })).data.cf_pages_project_name;
-		console.log(pc.green("  ✓") + ` Registered site (cf_pages_project=${cfPagesProjectName})`);
+		slug = (await createSite(projectId, { name: siteName })).data.slug;
+		console.log(pc.green("  ✓") + ` Registered site (slug=${slug})`);
 	} catch (err) {
-		cfPagesProjectName = (await describeSite(projectId, siteName)).data.cf_pages_project_name;
-		console.log(pc.dim(`  Site already registered (cf_pages_project=${cfPagesProjectName})`));
+		slug = (await describeSite(projectId, siteName)).data.slug;
+		console.log(pc.dim(`  Site already registered (slug=${slug})`));
 	}
 	console.log(pc.dim("  Uploading…"));
 	const dep = (await deploySiteViaApi(projectId, siteName, await buildPagesDeploymentForm(files))).data;
 	console.log(pc.green("  ✓") + ` Deployed ${dep.deployment_id.slice(0, 12)} ${pc.dim(`(branch=${dep.branch}, status=${dep.status})`)}`);
 	console.log(pc.green("  ✓") + ` URL: ${pc.underline(dep.url)}`);
-	if (dep.preview_url && dep.preview_url !== dep.url) console.log(pc.dim(`    preview (CF): ${dep.preview_url}`));
+	if (dep.preview_url && dep.preview_url !== dep.url) console.log(pc.dim(`    preview: ${dep.preview_url}`));
 	const domains = await listSiteDomains(projectId, siteName);
 	if (domains.data.length > 0) {
 		console.log();
@@ -3299,7 +4746,7 @@ async function sitesListCommand() {
 	}
 	for (const s of res.data) {
 		const status = s.status === "active" ? pc.green("active") : pc.yellow(s.status);
-		console.log(`  ${pc.bold(s.name)}  ${status}  ${pc.dim(`pages=${s.cf_pages_project_name}  ${s.created_at}`)}`);
+		console.log(`  ${pc.bold(s.name)}  ${status}  ${pc.dim(`slug=${s.slug}  ${s.created_at}`)}`);
 	}
 	console.log();
 }
@@ -3311,7 +4758,7 @@ async function sitesListCommand() {
 async function sitesLogsCommand(name) {
 	validateSiteName(name);
 	console.log();
-	console.log(pc.yellow("  ! `amba sites logs` is not available in this release."));
+	console.log(pc.yellow("  ! `amba sites logs` is not available via the CLI."));
 	console.log();
 	console.log(pc.dim("  Alternatives:"));
 	console.log(pc.dim("    amba sites describe <name>   (current state + domains/certs)"));
@@ -3334,7 +4781,7 @@ async function sitesDomainAddCommand(hostname, options) {
 	console.log(pc.dim(`  → site ${pc.cyan(options.site)}`));
 	console.log();
 	const res = await addSiteDomainViaApi(projectId, options.site, hostname);
-	console.log(pc.green("  ✓") + ` Custom Hostname registered (cf_id=${res.data.cf_hostname_id})`);
+	console.log(pc.green("  ✓") + ` Custom hostname registered`);
 	console.log();
 	console.log(pc.dim("  Point your DNS at:"));
 	console.log(`    ${pc.bold("CNAME")} ${hostname}  →  ${pc.cyan(res.data.dns_target)}`);
@@ -3397,7 +4844,7 @@ async function sitesArchiveCommand(name, options = {}) {
 	if (!options.confirm || options.confirm !== name) throw new Error(`Archive is destructive. Pass --confirm ${name} to proceed. The site project will be removed and traffic will 404.`);
 	const cascade = (await deleteSiteViaApi((await loadProjectConfig()).projectId, name, { confirm: name })).data.cascade;
 	console.log(pc.green("  ✓") + ` Archived ${name}.`);
-	console.log(pc.dim(`    Cascade: domains_removed=${cascade.domains_removed ?? 0}, cf_pages_project_deleted=${cascade.cf_pages_project_deleted ?? false}`));
+	console.log(pc.dim(`    Cascade: domains_removed=${cascade.domains_removed ?? 0}, site_runtime_removed=${cascade.site_runtime_removed ?? false}`));
 }
 /**
 * Sites are static-only. Dynamic logic belongs in `amba functions deploy`;
@@ -3501,7 +4948,7 @@ function runAction(fn) {
 		process.exit(1);
 	});
 }
-program.command("init").description("Initialize Amba in the current project (mints a personal dev project by default)").option("--with-example", "Scaffold a sample app.tsx + README snippet into the current directory").option("--env <env>", "'development' (default) or 'production'").action(async (opts) => {
+program.command("init").description("Initialize Amba in the current project (mints a personal dev project by default)").option("--with-example", "Scaffold a sample app.tsx + README snippet into the current directory").option("--env <env>", "'development' (default) or 'production'").option("--sandbox", "Headless agentic mode: auto-signup, write .env.local + AMBA.md, auto-wire MCP client configs. No prompts.").option("--email <email>", "Override the auto-generated sandbox email (requires --sandbox)").option("--no-mcp-config", "Skip writing MCP client config files (rare; mostly for testing)").option("--no-skills", "Skip installing the project-local /amba-build Claude Code skill (default: install during --sandbox)").option("--json", "Emit a machine-readable JSON summary on stdout instead of human-readable lines").action(async (opts) => {
 	let env;
 	if (opts.env === "development" || opts.env === "dev") env = "development";
 	else if (opts.env === "production" || opts.env === "prod") env = "production";
@@ -3509,9 +4956,30 @@ program.command("init").description("Initialize Amba in the current project (min
 		console.error(`Error: --env must be 'development' or 'production' (got '${opts.env}').`);
 		process.exit(1);
 	}
+	if (opts.email && !opts.sandbox) {
+		console.error("Error: --email is only valid with --sandbox.");
+		process.exit(1);
+	}
+	if (opts.json && !opts.sandbox) {
+		console.error("Error: --json is only valid with --sandbox.");
+		process.exit(1);
+	}
+	if (opts.mcpConfig === false && !opts.sandbox) {
+		console.error("Error: --no-mcp-config is only valid with --sandbox.");
+		process.exit(1);
+	}
+	if (opts.skills === false && !opts.sandbox) {
+		console.error("Error: --no-skills is only valid with --sandbox.");
+		process.exit(1);
+	}
 	await runAction(() => initCommand({
 		withExample: opts.withExample,
-		env
+		env,
+		sandbox: opts.sandbox,
+		sandboxEmail: opts.email,
+		noMcpConfig: opts.mcpConfig === false,
+		noSkills: opts.skills === false,
+		json: opts.json
 	}));
 });
 program.command("login").description("Authenticate with Amba").action(async () => {
@@ -3542,7 +5010,7 @@ 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; projects start in development)").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)").option("--platform <platform>", "Platform: 'ios' | 'android' | 'all'").action(async (opts) => {
 	await runAction(() => projectsCreateCommand({
 		name: opts.name,
 		env: opts.env,
@@ -3593,7 +5061,7 @@ program.command("schema").description("Schema export commands").command("export"
 		format: opts.format ?? "json"
 	}));
 });
-const functions = program.command("functions").description("Customer Worker functions (Cloudflare Workers for Platforms)");
+const functions = program.command("functions").description("Customer serverless functions deployed to the edge");
 functions.command("deploy <file>").description("Bundle a function file and deploy to the dispatch namespace").option("--name <name>", "Function name (default: filename without extension)").option("--dry-run", "Bundle and report size without uploading").option("--rate-limit-window <duration>", "Rate-limit window: 60s | 5m | 1h").option("--rate-limit-max <int>", "Rate-limit max requests per window", (v) => Number.parseInt(v, 10)).option("--rate-limit-key <kind>", "Rate-limit bucket key: user_id | ip").action(async (file, opts) => {
 	await runAction(() => functionsDeployCommand(file, opts));
 });
@@ -3606,8 +5074,11 @@ functions.command("delete <name>").description("Disable + remove a function from
 functions.command("schedule <name> <cron>").description("Register a cron schedule that invokes a deployed function").option("--tz <iana>", "IANA timezone for the schedule (default: UTC)").action(async (name, cron, opts) => {
 	await runAction(() => functionsScheduleCommand(name, cron, opts));
 });
-functions.command("dev <file>").description("Run wrangler dev --remote against your dev project").action(async (file) => {
-	await runAction(() => functionsDevCommand(file));
+functions.command("dev <file>").description("Run a local dev server for your function with hot reload on file changes").option("--port <n>", "Port to listen on (default 8787)", (v) => parseInt(v, 10)).option("--no-watch", "Disable file-change hot reload").action(async (file, opts) => {
+	await runAction(() => functionsDevCommand(file, {
+		port: opts.port,
+		noWatch: opts.watch === false
+	}));
 });
 functions.command("logs <name>").description("Stream log events for a deployed function").option("--since <iso>", "Start of the time range (default: 1 hour ago)").option("--until <iso>", "End of the time range (default: now). Ignored on --tail.").option("--limit <n>", "Max events per fetch (default 100, max 1000)", (v) => parseInt(v, 10)).option("--tail", "Follow new events; polls every 3s. Ctrl+C to stop.").option("--follow", "Alias for --tail (kept for backwards compatibility with v1 log commands).").option("--json", "NDJSON output to stdout (one event per line)").action(async (name, opts) => {
 	await runAction(() => functionsLogsCommand(name, {
@@ -3642,7 +5113,7 @@ secrets.command("list").description("List secret sync status for the current pro
 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) => {
 	await runAction(() => secretsUnsetCommand(name, opts));
 });
-const collections = program.command("collections").description("Customer collections (schema-first Postgres in tenant Neon)");
+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));
 });
@@ -3681,7 +5152,7 @@ sites.command("archive <name>").description("Archive a site (DESTRUCTIVE — del
 	await runAction(() => sitesArchiveCommand(name, opts));
 });
 const sitesDomain = sites.command("domain").description("Manage custom hostnames per site");
-sitesDomain.command("add <hostname>").description("Attach a custom hostname (CF for SaaS — DV cert, polls until active)").requiredOption("--site <name>", "Site name to attach the hostname to").option("--zone-id <id>", "CF zone id (default: env CLOUDFLARE_AMBA_HOST_ZONE_ID)").option("--no-wait", "Skip the cert-status poll loop; return as soon as the row is recorded").option("--timeout <seconds>", "Cert poll timeout (default 600)", (v) => parseInt(v, 10)).action(async (hostname, opts) => {
+sitesDomain.command("add <hostname>").description("Attach a custom hostname (DV cert, polls until active)").requiredOption("--site <name>", "Site name to attach the hostname to").option("--zone-id <id>", "DNS zone id (default: env AMBA_DNS_ZONE_ID)").option("--no-wait", "Skip the cert-status poll loop; return as soon as the row is recorded").option("--timeout <seconds>", "Cert poll timeout (default 600)", (v) => parseInt(v, 10)).action(async (hostname, opts) => {
 	await runAction(() => sitesDomainAddCommand(hostname, {
 		site: opts.site,
 		zoneId: opts.zoneId,
@@ -3692,7 +5163,7 @@ sitesDomain.command("add <hostname>").description("Attach a custom hostname (CF
 sitesDomain.command("list <site>").description("List custom hostnames attached to a site").action(async (site) => {
 	await runAction(() => sitesDomainListCommand(site));
 });
-sitesDomain.command("remove <hostname>").description("Detach a custom hostname (best-effort CF detach + control-plane row delete)").requiredOption("--site <name>", "Site name the hostname is attached to").option("--zone-id <id>", "CF zone id (default: env CLOUDFLARE_AMBA_HOST_ZONE_ID)").action(async (hostname, opts) => {
+sitesDomain.command("remove <hostname>").description("Detach a custom hostname (best-effort edge detach + control-plane row delete)").requiredOption("--site <name>", "Site name the hostname is attached to").option("--zone-id <id>", "DNS zone id (default: env AMBA_DNS_ZONE_ID)").action(async (hostname, opts) => {
 	await runAction(() => sitesDomainRemoveCommand(hostname, {
 		site: opts.site,
 		zoneId: opts.zoneId