@layers/amba 1.0.1 → 4.0.2

package/dist/index.js

@@ -1,15 +1,55 @@
 #!/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, 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 } from "node:os";
 import open from "open";
-import { createWriteStream } from "node:fs";
+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";
-import { createHash } from "node:crypto";
+//#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";
@@ -73,11 +113,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. */
@@ -249,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,
@@ -355,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}`);
 }
@@ -559,7 +613,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 +628,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 });
@@ -624,191 +678,2425 @@ async function validateApiKey(apiKey) {
 	};
 }
 //#endregion
-//#region src/context-files.ts
+//#region src/sandbox.ts
 /**
-* Generate AMBA.md project context file for AI agents.
+* 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.
 */
-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 />;
+/**
+* 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`;
 }
-\`\`\`
-
-### Using the Client
-
-\`\`\`tsx
-import { Amba } from '@layers/amba-expo';
+/**
+* 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,
+		developer_id: data.developer?.id ?? "",
+		developer_name: data.developer?.name
+	};
+}
+/**
+* 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 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, serverKey) {
+	const envPath = join(cwd, ".env.local");
+	const stanzaLines = [
+		"# Amba SDK configuration (sandbox tier)",
+		`AMBA_PROJECT_ID=${projectId}`,
+		`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$1(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 (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;
+	}
+	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)
 
-export default function MyComponent() {
-  const onPress = async () => {
-    // Track an event
-    await Amba.events.track('lesson_completed', { lesson_id: '123' });
+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.
 
-    // Sign in with Apple (requires expo-apple-authentication)
-    await Amba.signInWithApple();
+## What was provisioned
 
-    // Read remote config
-    const showBanner = await Amba.config.fetch();
+| Field | Value |
+| --- | --- |
+| Project ID | \`${ctx.projectId}\` |
+| Email | \`${ctx.email}\` |
+| API URL | \`${ctx.apiUrl}\` |
+| SDK | \`${ctx.sdkPackage}\` |
+| Framework | ${ctx.framework} |
 
-    // Email sign-in
-    await Amba.auth.signInWithEmail('user@example.com', 'hunter2');
-  };
+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\`.
 
-  // ...
-}
-\`\`\`` : `
-### Client Setup
+## SDK quickstart
 
-\`\`\`typescript
-import { Amba } from '${sdkPackage}';
+\`\`\`ts
+import { Amba } from '${ctx.sdkPackage}';
 
-await Amba.configure({
+Amba.configure({
   projectId: process.env.AMBA_PROJECT_ID!,
-  apiKey: process.env.AMBA_API_KEY!,
+  clientKey: process.env.AMBA_CLIENT_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}
+await Amba.events.track('app_opened');
+\`\`\`
 
-## Available Features
+## Sandbox limits
 
-- **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
+| Limit | Sandbox | Free (after verification) |
+| --- | --- | --- |
+| Monthly active users | 100 | 1,000 |
+| Database size | 10 MB | 500 MB |
+| Push notifications / mo | 1,000 | 10,000 |
 
-## API Reference
+## Upgrade past sandbox
 
-- Admin API: \`https://api.amba.dev/v1/admin\`
-- Client API: \`https://api.amba.dev/v1/client\`
-- Docs: \`https://docs.amba.dev\`
+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.
 
-## CLI Commands
+## Useful 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
+amba status            # health check
+amba projects list     # list your sandbox project
+amba seed --preset=starter   # populate sample data
 \`\`\`
+
+Docs: https://docs.amba.dev
 `;
 }
 /**
-* Generate .cursor/rules/amba.mdc Cursor rules file.
+* 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 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"]
----
+function buildAmbaMcpEntry(pat) {
+	return {
+		type: "http",
+		url: "https://mcp.amba.dev/mcp",
+		headers: { Authorization: `Bearer ${pat}` }
+	};
+}
+/**
+* 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$1(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$1(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 src/credentials.ts
+/**
+* Two-scope credential model for `amba init`.
+*
+* 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`).
+*
+* 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\`.
+- **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_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,
+* 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-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.
+
+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 -y @layers/amba init
+\`\`\`
+
+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. Verifies the PAT against the API and confirms it's good.
+
+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 -y @layers/amba init\`), 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 (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 (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
+
+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.
+- **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
+
+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
+/**
+* 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`.
+*
+* 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.
+*/
+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/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/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 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");
+	await mkdir(skillDir, { recursive: true });
+	const skillPath = join(skillDir, "SKILL.md");
+	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 SDK Rules
+Amba is the backend your app calls at runtime via the SDK; the MCP tools (\`amba_*\`) are for provisioning, called by the coding agent.
 
-## Project Setup
-- Project ID: \`${opts.projectId}\`
-- SDK: \`${sdk}\`
-- API URL: \`https://api.amba.dev\`
+## Bootstrap
 
-## 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
+\`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.
 
-## 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`}
+## Playbook
 
-## 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
+When the user asks you to wire Amba into this codebase, run this journey end-to-end:
 
-## 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
+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.
 
-## 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
+## Surfaces
 
-## 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
+- **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\`.
 `;
 }
 /**
-* Write both context files to the project directory.
+* 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`.
 */
-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;
+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
@@ -824,6 +3112,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);
@@ -923,173 +3290,411 @@ Docs: https://docs.amba.dev
 }
 async function initCommand(options = {}) {
 	const cwd = process.cwd();
-	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();
+	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,
+			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;
 	}
-	console.log(pc.bold("  Step 3/7 ") + pc.dim("Select project"));
-	console.log();
-	let projectId;
-	let projectName;
+	const environment = options.env ?? "development";
+	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})`)}`);
+				projectName = finalName;
 			}
+		}
+		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 name = await prompt("  Project name: ");
-			if (!name) {
-				console.log(pc.red("  ✗") + " Project name is required");
-				process.exit(1);
-			}
-			projectId = (await createProject({ name })).data.id;
-			projectName = name;
-			console.log(pc.green("  ✓") + ` Created: ${projectName}`);
+			const clientRes = await createApiKey(projectId, "client", environment);
+			const serverRes = await createApiKey(projectId, "server", environment);
+			clientKey = clientRes.data.key;
+			serverKey = serverRes.data.key;
 		}
-	} 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");
+		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);
 		}
-		projectId = (await createProject({ name })).data.id;
-		projectName = name;
-		console.log(pc.green("  ✓") + ` Created: ${projectName}`);
+		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.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();
 	}
-	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"));
+}
+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
+	});
+	setBearerOverride(identity.credentials.pat);
 	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,
+	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: project.credentials.project_id,
+		email: identity.credentials.email,
+		verifyUrl: identity.firstProject?.verify_url ?? null,
+		sdkPackage,
 		framework,
-		cwd
+		apiUrl: project.credentials.api_url
 	});
-	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");
+	let mcpConfigsWritten = [];
+	if (!options.noMcpConfig) mcpConfigsWritten = await writeAllMcpConfigs(cwd, identity.credentials.pat, {
+		homeDir: options.homeDir,
+		warn
+	});
+	let skillPath = null;
+	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: 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: identity.firstProject?.verify_url ?? null,
+		provisioningStatus: identity.firstProject?.provisioning_status ?? "active",
+		skillPath,
+		setupTargets
+	};
+}
+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,
+		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: [`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 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(`✓ 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}`);
+	}
+	return lines;
+}
+function printSandboxNextSteps(r) {
+	const lines = buildSandboxNextStepsLines(r);
 	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")}`);
+	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
@@ -1462,7 +4067,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}`);
@@ -1512,7 +4117,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) {
@@ -1538,6 +4143,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
 		});
@@ -1548,7 +4154,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.)"));
 		}
@@ -1557,7 +4163,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) {
@@ -1575,7 +4207,7 @@ async function projectsShowCommand(projectId) {
 			console.log();
 			process.exit(1);
 		}
-		handleError(err);
+		handleError$1(err);
 	}
 }
 async function projectsDeleteCommand(projectId, opts = {}) {
@@ -1600,7 +4232,7 @@ async function projectsDeleteCommand(projectId, opts = {}) {
 			console.log();
 			process.exit(1);
 		}
-		handleError(err);
+		handleError$1(err);
 	}
 }
 //#endregion
@@ -1904,14 +4536,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}`));
@@ -2257,45 +4889,108 @@ async function schemaExportCommand(opts) {
 		console.log();
 		process.exit(1);
 	}
-	const selected = domain === "all" ? Object.values(SCHEMAS) : [SCHEMAS[domain]];
-	const output = format === "json" ? renderJson(selected) : renderTypescript(selected);
-	process.stdout.write(output);
+	const selected = domain === "all" ? Object.values(SCHEMAS) : [SCHEMAS[domain]];
+	const output = format === "json" ? renderJson(selected) : renderTypescript(selected);
+	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`.
 *
-* 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";
@@ -2352,8 +5047,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) {
@@ -2370,51 +5067,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 +5099,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 +5117,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 +5137,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
@@ -2700,7 +5701,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() {
@@ -2712,7 +5712,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) {
@@ -2808,6 +5808,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.
@@ -3238,10 +6400,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 +6425,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 +6460,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 +6472,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 +6495,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 +6558,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 +6662,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,11 +6670,35 @@ 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("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);
 });
@@ -3542,14 +6727,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; 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). 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));
 });
@@ -3593,7 +6788,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 +6801,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 +6840,41 @@ 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 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));
 });
@@ -3681,7 +6913,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 +6924,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