@layers/amba 1.1.0 → 4.0.2

package/dist/index.js

@@ -1,16 +1,55 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import pc from "picocolors";
-import { access, chmod, mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { access, chmod, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
-import { createInterface } from "node:readline";
 import { createServer } from "node:http";
-import { homedir, tmpdir } from "node:os";
 import open from "open";
 import { createHash, randomBytes } from "node:crypto";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
 import { createWriteStream, watch } from "node:fs";
 import { spawn } from "node:child_process";
 import { build } from "esbuild";
+//#region ../shared/dist/index.js
+/**
+* Shared email-shape validation.
+*
+* Lives in `@layers/amba-shared` so the API (validates inbound emails
+* server-side before minting tokens / writing DB rows) and the CLI
+* (validates locally before round-tripping `amba claim <email>`) share
+* one canonical implementation. Previous drift between the two
+* implementations caused a real BugBot finding: a >320-char email
+* passed the CLI's loose regex but bounced server-side with
+* `INVALID_INPUT` — confusing UX.
+*
+* Intentionally permissive: validates the structural shape ("no
+* whitespace, has an `@`, has a dot in the domain part, ≤320 chars")
+* rather than running the full RFC-5321 grammar. Most callers
+* (hosted dashboard, Expo app form, CLI prompts) already validate
+* client-side; anything weirder than this check will bounce at the
+* upstream email provider anyway.
+*
+* The check exists so a 400 INVALID_INPUT surfaces before we mint a
+* token / write a DB row / fire an outbound provider request — that's
+* the load-bearing property, not "exactly RFC-compliant."
+*
+* The 320-char cap matches RFC 5321 §4.5.3.1.3 (path length, which
+* includes the email + envelope wrappers). It's the conventional
+* upper bound most validators converge on.
+*/
+function isPlausibleEmail(value) {
+	if (typeof value !== "string") return false;
+	const trimmed = value.trim();
+	if (trimmed.length === 0 || trimmed.length > 320) return false;
+	const at = trimmed.indexOf("@");
+	if (at <= 0 || at === trimmed.length - 1) return false;
+	if (/\s/.test(trimmed)) return false;
+	if (!trimmed.slice(at + 1).includes(".")) return false;
+	return true;
+}
+//#endregion
 //#region src/_internal/shared.ts
 const DEFAULT_API_URL = "https://api.amba.dev";
 const CONSOLE_URL = "https://app.amba.dev";
@@ -246,6 +285,16 @@ function setBearerOverride(token) {
 	bearerOverride = token === null || token.length === 0 ? null : token;
 }
 /**
+* Read the current bearer override without consuming it. Returns
+* `null` when no override is set. Used by commands that need to know
+* "did the operator supply a PAT for this invocation?" — e.g. `init`
+* branches on whether to bypass stored-creds and use the supplied
+* token verbatim.
+*/
+function getBearerOverride() {
+	return bearerOverride;
+}
+/**
 * Resolve the bearer token to send on the next admin API call.
 *
 * Returns the override (PAT or JWT supplied via flag/env) when set,
@@ -352,6 +401,14 @@ async function listProjects() {
 async function createProject(input) {
 	return request("POST", "/projects", input);
 }
+/**
+* PATCH /admin/projects/:projectId — update mutable fields. Server
+* silently ignores unknown keys; we filter to the documented allow-list
+* before sending so a typo at the CLI doesn't pass the wire silently.
+*/
+async function updateProject(projectId, patch) {
+	return request("PATCH", `/projects/${projectId}`, patch);
+}
 async function getProject(projectId) {
 	return request("GET", `/projects/${projectId}`);
 }
@@ -621,193 +678,6 @@ async function validateApiKey(apiKey) {
 	};
 }
 //#endregion
-//#region src/context-files.ts
-/**
-* Generate AMBA.md project context file for AI agents.
-*/
-function generateAmbaMarkdown(opts) {
-	const sdkPackage = opts.framework === "expo" ? "@layers/amba-expo" : opts.framework === "react-native" ? "@layers/amba-react-native" : "@layers/amba-web";
-	const providerExample = opts.framework === "expo" ? `
-### Client Setup
-
-\`\`\`tsx
-// app/_layout.tsx
-import { useEffect } from 'react';
-import { Slot } from 'expo-router';
-import { Amba } from '@layers/amba-expo';
-
-export default function RootLayout() {
-  useEffect(() => {
-    Amba.configure({
-      projectId: process.env.EXPO_PUBLIC_AMBA_PROJECT_ID!,
-      apiKey: process.env.EXPO_PUBLIC_AMBA_API_KEY!,
-    });
-  }, []);
-
-  return <Slot />;
-}
-\`\`\`
-
-### Using the Client
-
-\`\`\`tsx
-import { Amba } from '@layers/amba-expo';
-
-export default function MyComponent() {
-  const onPress = async () => {
-    // Track an event
-    await Amba.events.track('lesson_completed', { lesson_id: '123' });
-
-    // Sign in with Apple (requires expo-apple-authentication)
-    await Amba.signInWithApple();
-
-    // Read remote config
-    const showBanner = await Amba.config.fetch();
-
-    // Email sign-in
-    await Amba.auth.signInWithEmail('user@example.com', 'hunter2');
-  };
-
-  // ...
-}
-\`\`\`` : `
-### Client Setup
-
-\`\`\`typescript
-import { Amba } from '${sdkPackage}';
-
-await Amba.configure({
-  projectId: process.env.AMBA_PROJECT_ID!,
-  apiKey: process.env.AMBA_API_KEY!,
-});
-
-// Track an event
-await Amba.events.track('page_viewed', { page: '/pricing' });
-
-// Read remote config
-const config = await Amba.config.fetch();
-
-// Email sign-in
-await Amba.auth.signInWithEmail('user@example.com', 'hunter2');
-\`\`\``;
-	return `# Amba Project Context
-
-> This file provides context about the Amba integration for AI coding agents.
-
-## Project Info
-
-| Key | Value |
-|-----|-------|
-| Project ID | \`${opts.projectId}\` |
-| Project Name | ${opts.projectName} |
-| Framework | ${opts.framework} |
-| SDK | \`${sdkPackage}\` |
-
-## Environment Variables
-
-These are configured in \`.env.local\`:
-
-- \`AMBA_PROJECT_ID\` — Your project identifier
-- \`AMBA_API_KEY\` — Client API key (safe for client-side use)
-- \`AMBA_API_URL\` — API endpoint (defaults to https://api.amba.dev)
-
-## SDK Usage
-${providerExample}
-
-## Available Features
-
-- **Push Notifications** — Send targeted push notifications to user segments
-- **Remote Config** — Key-value configuration that updates without app releases
-- **Segments** — Group users by behavior, properties, or entitlements
-- **Streaks** — Track user engagement streaks (daily, weekly)
-- **Content Libraries** — Scheduled content delivery (daily tips, weekly challenges)
-- **Entitlements** — Subscription status via RevenueCat integration
-- **Analytics** — DAU, MAU, retention, and custom event tracking
-
-## API Reference
-
-- Admin API: \`https://api.amba.dev/v1/admin\`
-- Client API: \`https://api.amba.dev/v1/client\`
-- Docs: \`https://docs.amba.dev\`
-
-## CLI Commands
-
-\`\`\`bash
-amba status          # Check project health
-amba push test       # Send a test push notification
-amba config list     # List remote config values
-amba config set <key> <value>  # Set a config value
-\`\`\`
-`;
-}
-/**
-* Generate .cursor/rules/amba.mdc Cursor rules file.
-*/
-function generateCursorRules(opts) {
-	const sdk = opts.framework === "expo" ? "@layers/amba-expo" : opts.framework === "react-native" ? "@layers/amba-react-native" : "@layers/amba-web";
-	return `---
-description: Rules for working with the Amba SDK in this project
-globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
----
-
-# Amba SDK Rules
-
-## Project Setup
-- Project ID: \`${opts.projectId}\`
-- SDK: \`${sdk}\`
-- API URL: \`https://api.amba.dev\`
-
-## Environment Variables
-- Always read Amba config from environment variables, never hardcode
-- Use \`process.env.AMBA_PROJECT_ID\` and \`process.env.AMBA_API_KEY\`
-- The .env.local file contains the project credentials
-
-## SDK Patterns
-${opts.framework === "expo" ? `- Import the \`Amba\` singleton from \`@layers/amba-expo\`
-- Call \`Amba.init({ projectId, apiKey })\` once in the root layout (inside a \`useEffect\`)
-- The Expo wrapper auto-wires AsyncStorage, push tokens, and Apple/Google sign-in
-- Use \`Amba.signInWithApple()\` / \`Amba.signInWithGoogle()\` for social auth one-liners
-- Call \`Amba.track()\` for engagement events, don't build custom analytics` : `- Initialize the Amba client once and export it as a singleton
-- Use \`Amba.client.track()\` for all engagement events
-- Use \`Amba.client.config.get()\` for remote configuration
-- Use \`Amba.client.auth\` for sign-up / sign-in flows`}
-
-## Push Notifications
-- Register push tokens via the SDK \`registerPushToken()\` method
-- Handle notification payloads using the SDK's notification listener
-- Don't implement custom push token management
-
-## Remote Config
-- Use remote config for feature flags and dynamic values
-- Always provide sensible defaults when reading config values
-- Config values are cached — don't fetch on every render
-
-## Streaks
-- Streaks are server-managed; the SDK provides read-only access
-- Use \`track()\` to record qualifying events — the server evaluates streaks
-- Show streak state from \`streak.current()\`, don't calculate manually
-
-## Best Practices
-- Don't store Amba API keys in source code or commit them to git
-- Use \`.env.local\` for local development credentials
-- The client API key (prefixed \`amb_dev_ck_\` or \`amb_live_ck_\`) is safe for client-side use
-- Server keys (prefixed \`amb_dev_sk_\` or \`amb_live_sk_\`) must stay server-side only
-`;
-}
-/**
-* Write both context files to the project directory.
-*/
-async function generateContextFiles(opts) {
-	const files = [];
-	await writeFile(join(opts.cwd, "AMBA.md"), generateAmbaMarkdown(opts), "utf-8");
-	files.push("AMBA.md");
-	const cursorDir = join(opts.cwd, ".cursor", "rules");
-	await mkdir(cursorDir, { recursive: true });
-	await writeFile(join(cursorDir, "amba.mdc"), generateCursorRules(opts), "utf-8");
-	files.push(".cursor/rules/amba.mdc");
-	return files;
-}
-//#endregion
 //#region src/sandbox.ts
 /**
 * Headless agentic sandbox bootstrap.
@@ -934,60 +804,9 @@ async function performSandboxSignup(req, options = {}) {
 		api_url: apiUrl,
 		provisioning_status: data.project.provisioning_status,
 		verify_url: data.project.verify_url,
-		email: req.email
-	};
-}
-/**
-* Write the PAT to `~/.amba/credentials.json` (chmod 0600) in a shape
-* the existing `loadCredentials` reader recognises.
-*
-* `auth.ts` was built around browser-OAuth tokens (`access_token` +
-* `refresh_token` + `expires_at`). PATs are long-lived and don't refresh
-* — but the stored-creds reader only inspects `access_token`, so we
-* write the PAT there and leave `refresh_token` empty + a far-future
-* `expires_at` so the expiry guard never fires.
-*
-* Real-credential safety: if the file already exists AND its `source`
-* is NOT `'sandbox-init'` AND `access_token` is non-empty, we treat it
-* as a real OAuth/PAT session and back it up to
-* `credentials.json.bak-<unix-ms>` before overwriting. The next
-* `--sandbox` run reuses our own previous sandbox creds without
-* back-up. This keeps the agentic flow idempotent while preventing a
-* silent clobber of a developer's real account.
-*/
-async function writeSandboxCredentials(pat, options = {}) {
-	const dir = join(options.homeDir ?? homedir(), ".amba");
-	const path = join(dir, "credentials.json");
-	await mkdir(dir, { recursive: true });
-	let backedUpTo = null;
-	try {
-		const existingRaw = await readFile(path, "utf-8");
-		const existing = JSON.parse(existingRaw);
-		const hasToken = typeof existing.access_token === "string" && existing.access_token.length > 0;
-		const isSandboxOwned = existing.source === "sandbox-init";
-		if (hasToken && !isSandboxOwned) {
-			backedUpTo = `${path}.bak-${Date.now()}`;
-			await writeFile(backedUpTo, existingRaw, "utf-8");
-			try {
-				await chmod(backedUpTo, 384);
-			} catch {}
-		}
-	} catch (err) {
-		if (!isEnoent(err)) {}
-	}
-	const payload = {
-		access_token: pat,
-		refresh_token: "",
-		expires_at: (/* @__PURE__ */ new Date("2099-12-31T00:00:00.000Z")).toISOString(),
-		source: "sandbox-init"
-	};
-	await writeFile(path, JSON.stringify(payload, null, 2), "utf-8");
-	try {
-		await chmod(path, 384);
-	} catch {}
-	return {
-		path,
-		backedUpTo
+		email: req.email,
+		developer_id: data.developer?.id ?? "",
+		developer_name: data.developer?.name
 	};
 }
 /**
@@ -996,23 +815,30 @@ async function writeSandboxCredentials(pat, options = {}) {
 * Mirrors the `init` interactive flow exactly so the existing env-read
 * conventions in the SDKs and CLI commands keep working. The merge
 * logic: if the file already exists and contains an `AMBA_PROJECT_ID`
-* line we replace the three Amba lines in place; otherwise we append a
+* line we replace the Amba lines in place; otherwise we append a
 * fresh stanza.
+*
+* `serverKey` is optional — pass it on the new two-scope credential
+* model where init mints both client+server. Pre-existing AMBA_SERVER_KEY
+* lines are refreshed when a new value is provided and removed when
+* serverKey is null AND no prior line existed (no-op on second case).
 */
-async function writeSandboxEnvLocal(cwd, projectId, clientKey, apiUrl) {
+async function writeSandboxEnvLocal(cwd, projectId, clientKey, apiUrl, serverKey) {
 	const envPath = join(cwd, ".env.local");
-	const stanza = [
+	const stanzaLines = [
 		"# Amba SDK configuration (sandbox tier)",
 		`AMBA_PROJECT_ID=${projectId}`,
-		`AMBA_CLIENT_KEY=${clientKey}`,
-		`AMBA_API_URL=${apiUrl}`,
-		""
-	].join("\n");
+		`AMBA_CLIENT_KEY=${clientKey}`
+	];
+	if (serverKey) stanzaLines.push(`AMBA_SERVER_KEY=${serverKey}`);
+	stanzaLines.push(`AMBA_API_URL=${apiUrl}`);
+	stanzaLines.push("");
+	const stanza = stanzaLines.join("\n");
 	let existing = "";
 	try {
 		existing = await readFile(envPath, "utf-8");
 	} catch (err) {
-		if (!isEnoent(err)) throw err;
+		if (!isEnoent$1(err)) throw err;
 	}
 	if (existing.length === 0) {
 		await writeFile(envPath, stanza, "utf-8");
@@ -1030,6 +856,14 @@ async function writeSandboxEnvLocal(cwd, projectId, clientKey, apiUrl) {
 		} else if (hadApiKey) updated = updated.replace(/^AMBA_API_KEY=.*/m, () => `AMBA_CLIENT_KEY=${clientKey}`);
 		else if (hadClientKey) updated = updated.replace(/^AMBA_CLIENT_KEY=.*/m, () => `AMBA_CLIENT_KEY=${clientKey}`);
 		else updated += (updated.endsWith("\n") ? "" : "\n") + `AMBA_CLIENT_KEY=${clientKey}\n`;
+		if (serverKey) if (/^AMBA_SERVER_KEY=/m.test(updated)) updated = updated.replace(/^AMBA_SERVER_KEY=.*/m, () => `AMBA_SERVER_KEY=${serverKey}`);
+		else {
+			const clientKeyMatch = updated.match(/^AMBA_CLIENT_KEY=.*\n?/m);
+			if (clientKeyMatch) {
+				const insertAt = (clientKeyMatch.index ?? 0) + clientKeyMatch[0].length;
+				updated = updated.slice(0, insertAt) + `AMBA_SERVER_KEY=${serverKey}\n` + updated.slice(insertAt);
+			} else updated += (updated.endsWith("\n") ? "" : "\n") + `AMBA_SERVER_KEY=${serverKey}\n`;
+		}
 		if (!/^AMBA_API_URL=/m.test(updated)) updated += (updated.endsWith("\n") ? "" : "\n") + `AMBA_API_URL=${apiUrl}\n`;
 		await writeFile(envPath, updated, "utf-8");
 		return envPath;
@@ -1069,8 +903,7 @@ without a credit card or email verification.
 
 The credentials live in **\`.env.local\`** (\`AMBA_PROJECT_ID\`,
 \`AMBA_CLIENT_KEY\`, \`AMBA_API_URL\`) — gitignored by convention. Your
-Personal Access Token is stored in \`~/.amba/credentials.json\` and was
-written into every MCP client config we could detect.
+Personal Access Token is stored in \`~/.amba/credentials.json\`.
 
 ## SDK quickstart
 
@@ -1095,10 +928,11 @@ await Amba.events.track('app_opened');
 
 ## Upgrade past sandbox
 
-The account is unverified. To upgrade to the Free tier (and stop being
-capped at 100 MAU / 10 MB DB), claim the email on the account:
-
-${ctx.verifyUrl ? `1. Open ${ctx.verifyUrl}\n2. Change the email on the developer record to one you control via [app.amba.dev](https://app.amba.dev/settings).` : `1. Open [app.amba.dev](https://app.amba.dev) and request a password reset for \`${ctx.email}\` — the sandbox password was random and isn't recoverable.\n2. Change the email on the developer record to one you control.`}
+This account uses an auto-generated email (\`${ctx.email}\`). Run
+\`amba claim me@example.com\` to bind it to a real address — you'll get
+a one-click link in your inbox that promotes the project to the Free
+tier (1,000 MAU, 500 MB DB) and lets you sign in from a browser if you
+ever need to.
 
 ## Useful commands
 
@@ -1129,42 +963,6 @@ function buildAmbaMcpEntry(pat) {
 	};
 }
 /**
-* Map an MCP config file path back to its client family. Returns null
-* for paths that don't match any known config location — defensive
-* against future additions to `mcpClientTargets`.
-*
-* The match is on path tail rather than full equality so the cwd /
-* homedir-injected variants both classify correctly. We deliberately
-* accept both global and project-local Claude Code paths
-* (`.claude.json` and `.mcp.json`) as 'claude-code'.
-*/
-function classifyMcpPath(path) {
-	if (path.endsWith(".claude.json") || path.endsWith(".mcp.json")) return "claude-code";
-	if (path.includes(`/.cursor/`) || path.includes(`\\.cursor\\`)) return "cursor";
-	if (path.includes("/windsurf/mcp_config.json") || path.includes("\\windsurf\\mcp_config.json")) return "windsurf";
-	return null;
-}
-/**
-* Reduce a list of written-config paths to the set of unique client
-* families they belong to. Order: claude-code, cursor, windsurf (so
-* the done-message renders consistently). Skips unclassified paths
-* silently.
-*/
-function clientKindsFromPaths(paths) {
-	const present = /* @__PURE__ */ new Set();
-	for (const p of paths) {
-		const kind = classifyMcpPath(p);
-		if (kind) present.add(kind);
-	}
-	const ordered = [];
-	for (const k of [
-		"claude-code",
-		"cursor",
-		"windsurf"
-	]) if (present.has(k)) ordered.push(k);
-	return ordered;
-}
-/**
 * The list of MCP client config files we probe. Order matters only for
 * the printed report.
 *
@@ -1231,7 +1029,7 @@ async function mergeMcpConfigFile(target, pat) {
 		if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) existing = parsed;
 		else throw new Error(`Existing config at ${target.path} is not a JSON object`);
 	} catch (err) {
-		if (isEnoent(err)) {
+		if (isEnoent$1(err)) {
 			if (!target.scaffoldIfMissing) return {
 				path: null,
 				backedUpTo: null
@@ -1300,7 +1098,7 @@ async function fileExists$1(path) {
 		return false;
 	}
 }
-function isEnoent(err) {
+function isEnoent$1(err) {
 	return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
 }
 /**
@@ -1313,27 +1111,1260 @@ function formatManualMcpSnippet(pat) {
 	return JSON.stringify({ mcpServers: { amba: buildAmbaMcpEntry(pat) } }, null, 2);
 }
 //#endregion
-//#region ../mcp/dist/expo-build-prompt.js
+//#region src/credentials.ts
 /**
-* Canonical Amba Expo build prompt — markdown body (no MDX frontmatter).
+* Two-scope credential model for `amba init`.
 *
-* Source of truth for three customer-facing surfaces:
+* Identity is **developer-scoped** (one machine identity, persisted in
+* `~/.amba/credentials.json`). State is **project-scoped** (one per
+* project directory, persisted in `<cwd>/.amba/project.json`).
 *
-*   1. The published docs page at
-*      `https://docs.amba.dev/docs/prompts/expo-build` — the MDX file at
-*      `apps/docs/content/docs/prompts/expo-build.mdx` ships the same
-*      body wrapped in fumadocs frontmatter.
-*   2. The MCP resource `amba://prompts/expo-build` registered by
-*      `registerAllResources()` in `./index.ts` and exposed by the
-*      hosted MCP server at `mcp.amba.dev`.
-*   3. The inlined snapshot baked into the `/amba-build` Claude Code
-*      skill by `amba init --sandbox` (see `packages/cli/src/skills.ts`).
+* One Amba account can own N projects. Running `amba init` in five
+* different folders under one identity yields one developer row + five
+* project rows — exactly the model `apps/console` and the API enforce.
 *
-* 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`.
+* 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.
 *
-* **Update protocol:** edit the MDX (it's the human-facing surface;
+* 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
@@ -1344,8 +2375,8 @@ function formatManualMcpSnippet(pat) {
 * so it renders identically as `.md` (the MCP / skill consumers) and
 * as `.mdx` (the docs site).
 */
-const EXPO_BUILD_PROMPT_MD = `> **Last reviewed:** 2026-05-16. The canonical version of this page lives
-> at [docs.amba.dev/docs/prompts/expo-build](https://docs.amba.dev/docs/prompts/expo-build).
+const EXPO_BUILD_PROMPT_MD = `> **Last reviewed:** 2026-05-17. The canonical version of this page lives
+> at [docs.amba.dev/prompts/expo-build](https://docs.amba.dev/prompts/expo-build).
 > If you're reading an inlined snapshot from your
 > \`.claude/skills/amba-build/SKILL.md\`, check the URL above for updates.
 
@@ -1361,7 +2392,7 @@ The CLI handles signup, project provisioning, env-file writes, and MCP
 client config wiring in one command:
 
 \`\`\`bash
-npx @layers/amba init --sandbox
+npx -y @layers/amba init
 \`\`\`
 
 That's the entire setup. The CLI:
@@ -1374,14 +2405,17 @@ That's the entire setup. The CLI:
 4. Writes \`AMBA.md\` (project-scoped context for the agent).
 5. Auto-wires \`mcpServers.amba\` into every MCP client config it
    detects on disk — Claude Code, Cursor, Windsurf.
-6. Prints a per-client restart instruction.
+6. Verifies the PAT against the API and confirms it's good.
 
-After restarting your MCP client, the Amba MCP toolset is available
-(\`amba_*\` tools — ~130 of them) and the agent can drive the backend
-end-to-end.
+The Amba MCP toolset (\`amba_*\` tools — ~130 of them) is available to
+the agent immediately: pass the freshly-minted \`pat\` as an inline
+argument on every \`amba_*\` call in the current session. The next time
+your MCP client starts it picks the PAT up from the config as the
+inbound Bearer automatically — at that point the \`pat\` arg becomes
+optional. No restart needed; nothing for you to do.
 
 If you have the \`/amba-build\` skill installed (via
-\`npx @layers/amba init --sandbox\`), invoke it directly:
+\`npx -y @layers/amba init\`), invoke it directly:
 
 \`\`\`
 /amba-build <DESIGN_HASH>
@@ -1401,11 +2435,13 @@ DX cascade is fixed.
 - **React Native bundle size** — the React Native SDK adds ~4 MB to
   the JS bundle today. Functional, just heavier than the long-term
   goal. Tracked separately.
-- **Sandbox MAU cap (50)** — the agent-mode sandbox tier caps at 50
+- **Sandbox MAU cap (100)** — the agent-mode sandbox tier caps at 100
   monthly active users. If you blow through it during testing, call
   \`amba_users_reset_sandbox\` to clear the counter — that tool exists
-  specifically for this. Upgrade to the Free tier (claim the email)
-  to lift the cap to 1,000.
+  specifically for this. Upgrade to the Free tier (1,000 MAU, 500 MB
+  DB) by running \`amba claim me@example.com\` from the terminal — the
+  backend emails a one-click magic link to the address you pass in;
+  clicking it binds the account to that email and lifts the cap.
 
 ## How to read the design
 
@@ -1537,6 +2573,12 @@ gate.
   \`expo export --platform ios\`, and \`expo export --platform android\`
   must all succeed. If any one fails, the build fails. No
   "shipped iOS-only, web is broken" — the rule is parity.
+- **Don't name a tab \`settings.tsx\`.** Use \`account.tsx\` or
+  \`preferences.tsx\` instead. Expo Router's static web export generates
+  \`settings.html\` correctly but does not resolve direct URL navigation
+  to \`/settings\` — the client-side router shows an unmatched-route
+  error while other tab names work fine. (Observed in dogfood; upstream
+  behavior, not an Amba issue.)
 
 ## Verification gate
 
@@ -1618,33 +2660,47 @@ If \`BUILD_REPORT.md\` is missing any required section, or
 //#endregion
 //#region src/skills.ts
 /**
-* Claude Code skill installer for `amba init --sandbox`.
-*
-* Writes a project-local `.claude/skills/amba-build/SKILL.md` file
-* containing the canonical "/goal" prompt for building a full Expo
-* app with Amba as the only backend. Two behaviors:
-*
-*   1. **Live fetch first.** The skill's runtime instructions tell
-*      Claude Code to `curl` the live MDX from
-*      `https://docs.amba.dev/docs/prompts/expo-build.md`. So as long
-*      as docs is reachable, the agent always uses the latest version.
-*
-*   2. **Inlined snapshot fallback.** The same SKILL.md file embeds a
-*      verbatim copy of the prompt body — captured at CLI install
-*      time from `@layers/amba-mcp/prompts`. Offline agents (or ones
-*      whose curl 404s during the docs deploy gap) still get a
-*      usable prompt.
-*
-* Out of scope (per DX-16): Cursor / Windsurf shortcut files. Those
-* editors don't ingest Claude Code skills; their users paste the
-* URL directly. The CLI's success line still surfaces the
-* `/amba-build` command + the docs URL so both audiences are served.
-*
-* Project-local install is the default because skills written into
-* `~/.claude/skills/` are user-global and would persist across
-* unrelated projects (and accumulate stale copies of the inlined
-* snapshot from old `amba init` runs). A project-scoped install
-* disappears when the user `rm -rf`s the project.
+* Per-agent skill / rule file installer for `amba init`.
+*
+* Two distinct surfaces, both project-local:
+*
+*   1. **Build task skill** — `.claude/skills/amba-build/SKILL.md`.
+*      Scaffolds a full Expo app via the canonical "/goal" prompt.
+*      Task-shaped: the user invokes it explicitly. Lives behind
+*      `writeAmbaBuildSkill` (legacy export, unchanged).
+*
+*   2. **Reference / setup skill** — fanned out into five locations,
+*      one per agent family, so the same Amba setup guide reaches
+*      whatever coding agent the user has installed:
+*
+*      | Surface                                  | Path                          | Wrapper                  |
+*      |------------------------------------------|-------------------------------|--------------------------|
+*      | Claude Code (proactive, auto-injected)   | \`CLAUDE.md\` (append)          | plain markdown           |
+*      | Claude Code (invokable skill)            | \`.claude/skills/amba/SKILL.md\` | \`description:\` frontmatter |
+*      | Cursor                                   | \`.cursor/rules/amba.mdc\`      | \`alwaysApply\`/\`description\`/\`globs\` |
+*      | Codex / Aider / Zed / Copilot / Gemini   | \`AGENTS.md\` (append)          | plain markdown           |
+*      | Windsurf                                 | \`.windsurf/rules/amba.md\`     | \`trigger: always_on\`     |
+*
+* The two append targets (\`CLAUDE.md\`, \`AGENTS.md\`) use marker
+* fencing — \`<!-- AMBA-SETUP-START -->\` / \`<!-- AMBA-SETUP-END -->\` —
+* so a re-init refreshes only Amba's section without clobbering user
+* edits to the surrounding file. The standalone targets (\`.cursor\`,
+* \`.windsurf\`, \`.claude/skills/amba\`) live in their own files and
+* are overwritten wholesale per re-init.
+*
+* The shared body comes from \`@layers/amba-mcp/prompts\`
+* (\`AMBA_SETUP_GUIDE_MD\`) — one canonical source, five wrappers. The
+* CLI bundles that constant at publish time via tsdown's
+* \`noExternal: [/^@layers\\/amba-/]\` rule (same path \`EXPO_BUILD_PROMPT_MD\`
+* already uses).
+*
+* Vendor-name discipline
+* ----------------------
+* Everything written by this module is customer-facing. The body
+* (sourced from the MCP package) is vetted there; the wrappers below
+* intentionally avoid naming Cloudflare / GCP / Neon / Temporal /
+* Rust / WASM / UniFFI / Resend / Doppler. See \`skills.test.ts\` for
+* the per-writer drift gate.
 */
 /**
 * Build the contents of `.claude/skills/amba-build/SKILL.md`.
@@ -1652,17 +2708,6 @@ If \`BUILD_REPORT.md\` is missing any required section, or
 * Exported as a pure function so the unit tests can assert structural
 * properties (frontmatter, fetcher block, inlined snapshot fence)
 * without round-tripping through the filesystem.
-*
-* Structure:
-*   1. YAML frontmatter — `description` so Claude Code's skill
-*      indexer picks it up.
-*   2. Skill body — invocation instructions, fetcher one-liner,
-*      fallback rule.
-*   3. Inlined snapshot — fenced code block containing the
-*      EXPO_BUILD_PROMPT_MD body verbatim. The snapshot is bounded
-*      by a marker comment so a future `amba update-skills` command
-*      can find and refresh just the inlined region without
-*      clobbering user customizations above it.
 */
 function buildAmbaBuildSkillContent() {
 	return `---
@@ -1672,7 +2717,7 @@ description: Canonical /goal prompt for building a full Expo app with Amba as th
 # /amba-build
 
 When invoked, fetch the canonical prompt from
-\`https://docs.amba.dev/docs/prompts/expo-build.md\` and use it as the
+\`https://docs.amba.dev/prompts/expo-build.md\` and use it as the
 \`/goal\` directive for building a full Expo app with Amba as the only
 backend. The user supplies a design hash (URL or description) as the
 argument; substitute it for every \`<DESIGN_HASH>\` placeholder in the
@@ -1692,7 +2737,7 @@ Replace \`<DESIGN_HASH>\` with:
 ## Fetcher
 
 \`\`\`bash
-curl -sf https://docs.amba.dev/docs/prompts/expo-build.md
+curl -sf https://docs.amba.dev/prompts/expo-build.md
 \`\`\`
 
 If \`curl\` fails (404, 5xx, network error, no internet), fall back to
@@ -1715,17 +2760,8 @@ ${EXPO_BUILD_PROMPT_MD}<!-- AMBA-BUILD-PROMPT-END -->
 }
 /**
 * Write `.claude/skills/amba-build/SKILL.md` into the target project.
-*
-* Always overwrites — the skill file is meant to be regenerated each
-* time `amba init --sandbox` runs (so the inlined snapshot stays
-* fresh). Anything the user customized above the snapshot markers
-* would be lost on a re-init; that's an accepted trade-off for the
-* agentic single-command flow.
-*
-* If a future need for "preserve user edits across re-init" surfaces,
-* the right shape is a separate `amba update-skills` command that
-* surgically rewrites the inlined-snapshot region only — leaving the
-* surrounding text untouched. Out of scope for DX-16.
+* Always overwrites — the inlined snapshot is meant to be regenerated
+* on each `amba init --sandbox` run.
 */
 async function writeAmbaBuildSkill(options = {}) {
 	const skillDir = join(options.baseDir ?? process.cwd(), ".claude", "skills", "amba-build");
@@ -1734,6 +2770,334 @@ async function writeAmbaBuildSkill(options = {}) {
 	await writeFile(skillPath, buildAmbaBuildSkillContent(), "utf-8");
 	return { path: skillPath };
 }
+/**
+* Marker fence sentinels for the two append-targets (`CLAUDE.md`,
+* `AGENTS.md`). Used by `markerFencedAppend` to find + refresh the
+* Amba section without clobbering surrounding user content.
+*/
+const AMBA_SETUP_START_MARKER = "<!-- AMBA-SETUP-START -->";
+const AMBA_SETUP_END_MARKER = "<!-- AMBA-SETUP-END -->";
+var AmbaSkillFileCorrupted = class extends Error {
+	path;
+	shape;
+	constructor(filePath, shape) {
+		super(`Found ${shape.startCount} AMBA-SETUP-START marker(s) and ${shape.endCount} AMBA-SETUP-END marker(s) in ${filePath}; expected exactly 1 of each in order. Refusing to auto-fix: cutting either side could discard user content. Please remove the extras (or the orphan marker) manually and re-run \`amba init\`.`);
+		this.name = "AmbaSkillFileCorrupted";
+		this.path = filePath;
+		this.shape = shape;
+	}
+};
+/**
+* Insert or refresh a marker-fenced block in a file.
+*
+* Marker-shape invariant: the target file must have either
+*   (a) zero start/end markers (clean append), or
+*   (b) exactly one start marker and one end marker, with the end
+*       marker after the start (clean in-place refresh).
+*
+* Any other shape — orphan single marker, duplicate paired blocks,
+* end-before-start, mixed counts (e.g. 1 start + 2 ends) — is
+* treated as corruption and throws `AmbaSkillFileCorrupted`. The
+* caller's `warn` sink surfaces the error to the developer; the
+* file is left untouched. Earlier revisions tried to auto-recover
+* malformed states via strip-and-replace, but every recovery
+* heuristic risked deleting user content outside the Amba block
+* (BugBot cycle-5..7 all flagged adjacent failure modes — the
+* strict invariant kills the whole class).
+*
+* Behavior:
+*
+*   - File does not exist (`ENOENT`) → create with just the block.
+*     **Any other read error (EACCES, EISDIR, transient I/O) is
+*     re-thrown** — we never silently overwrite a file we couldn't
+*     read.
+*   - File exists, zero markers → append the block (with a blank-
+*     line separator so it doesn't fuse onto the last paragraph).
+*   - File exists, well-formed 1+1 pair (end after start) → replace
+*     the content between markers, preserving surrounding text.
+*   - Any other marker shape → throw `AmbaSkillFileCorrupted` with
+*     the observed (startCount, endCount, startIdx, endIdx).
+*
+* Returns the absolute path + whether this was a fresh create or a
+* refresh.
+*
+* The `body` argument is the text we want **inside** the markers —
+* the markers themselves are added by this helper. Callers must NOT
+* include the start/end marker lines in `body`.
+*/
+async function markerFencedAppend(filePath, body, startMarker, endMarker) {
+	await mkdir(dirname(filePath), { recursive: true });
+	let existing = null;
+	try {
+		existing = await readFile(filePath, "utf-8");
+	} catch (err) {
+		if (err?.code === "ENOENT") existing = null;
+		else throw err;
+	}
+	const block = `${startMarker}\n${body}\n${endMarker}`;
+	if (existing === null) {
+		await writeFile(filePath, block + "\n", "utf-8");
+		return {
+			path: filePath,
+			mode: "created"
+		};
+	}
+	const startCount = countOccurrences(existing, startMarker);
+	const endCount = countOccurrences(existing, endMarker);
+	const startIdx = existing.indexOf(startMarker);
+	const endIdx = existing.indexOf(endMarker);
+	if (startCount === 1 && endCount === 1 && endIdx > startIdx) {
+		const before = existing.slice(0, startIdx);
+		const after = existing.slice(endIdx + endMarker.length);
+		await writeFile(filePath, before + block + after, "utf-8");
+		return {
+			path: filePath,
+			mode: "refreshed"
+		};
+	}
+	if (startCount === 0 && endCount === 0) {
+		const separator = existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+		await writeFile(filePath, existing + separator + block + "\n", "utf-8");
+		return {
+			path: filePath,
+			mode: "refreshed"
+		};
+	}
+	throw new AmbaSkillFileCorrupted(filePath, {
+		startCount,
+		endCount,
+		startIdx,
+		endIdx
+	});
+}
+/**
+* Count non-overlapping occurrences of `needle` in `haystack`.
+* Used to classify the marker state of an existing file.
+*/
+function countOccurrences(haystack, needle) {
+	if (needle.length === 0) return 0;
+	let count = 0;
+	let pos = 0;
+	while (true) {
+		const idx = haystack.indexOf(needle, pos);
+		if (idx === -1) break;
+		count += 1;
+		pos = idx + needle.length;
+	}
+	return count;
+}
+/**
+* Build the canonical setup body. Sourced from the MCP package so
+* docs + MCP + every coding-agent surface stay in sync.
+*
+* Exposed as a function (not a const) so future versions can swap in
+* a build-time generator without breaking import sites.
+*/
+function buildAmbaSetupBody() {
+	return AMBA_SETUP_GUIDE_MD;
+}
+/**
+* Build the Cursor `.cursor/rules/amba.mdc` flavor.
+*
+* `alwaysApply: true` makes Cursor inject the rule at the start of
+* every turn (Cursor's most-proactive mode). `globs: ""` keeps the
+* rule globally-scoped instead of file-pattern-attached.
+*/
+function buildCursorRuleContent() {
+	return `---
+alwaysApply: true
+description: "Amba SDK + MCP guide"
+globs: ""
+---
+
+${buildAmbaSetupBody()}
+`;
+}
+/**
+* Build the Windsurf `.windsurf/rules/amba.md` flavor.
+*
+* `trigger: always_on` is Windsurf's equivalent of Cursor's
+* `alwaysApply: true`. Workspace rules **cap at 12k chars** — a hard
+* Windsurf limit, not negotiable. The canonical
+* `AMBA_SETUP_GUIDE_MD` body is the full classify → confirm →
+* wire-up playbook (~17k) and won't fit, so Windsurf gets a
+* trimmed-down summary that points at the long-form resource
+* (`amba://setup`) for full detail. Same posture as
+* `AMBA_INIT_INSTRUCTIONS` in the hosted MCP server.
+*/
+function buildWindsurfRuleContent() {
+	return `---
+trigger: always_on
+---
+
+${buildWindsurfSummaryBody()}
+`;
+}
+/**
+* Shorter summary of the Amba setup playbook for Windsurf rules.
+*
+* Constraints:
+*   - Wrapped frontmatter + body must fit under Windsurf's 12k cap.
+*   - Must name the same five-step journey shape so an agent acting
+*     on this summary doesn't drift from the canonical guide.
+*   - Customer-facing — no vendor leakage.
+*
+* For full detail (per-surface MCP tool tables, per-stack SDK init
+* snippets, common follow-ups, re-run rules), the agent fetches
+* `amba://setup` (or per-surface \`amba://setup/<surface>\`) from the
+* hosted MCP server.
+*/
+function buildWindsurfSummaryBody() {
+	return `# Amba
+
+Amba is the backend your app calls at runtime via the SDK; the MCP tools (\`amba_*\`) are for provisioning, called by the coding agent.
+
+## Bootstrap
+
+\`amba_developer_signup\` is the only pre-auth MCP tool — call it with no Bearer to mint a PAT, project, and client/server keys in one round trip. After signup, set \`Authorization: Bearer <pat>\` on every subsequent MCP call. Save \`project_id\` + \`client_key\` to \`.env.local\`; never write \`server_key\` next to client code.
+
+## Playbook
+
+When the user asks you to wire Amba into this codebase, run this journey end-to-end:
+
+1. **Step 0 — Bootstrap credentials.** Call \`amba_developer_signup\` (pre-auth) OR \`amba_developer_me\` if a PAT already exists. Persist \`project_id\` + \`client_key\` to \`.env.local\`.
+2. **Step 1 — Classify the app.** Pick one of ten presets (fitness / social / marketplace / productivity / education / game / dating / content_creator / ai_chatbot / custom) using README + filenames + dependencies.
+3. **Step 2 — Confirm with the user.** One multi-choice question listing the surfaces the preset implies. Don't drip-feed.
+4. **Step 3 — Wire it up.** For each surface in the confirmed scope, fetch its sub-resource (\`amba://setup/<surface>\`) and execute its MCP tools + drop in the per-stack SDK init snippet.
+5. **Step 4 — Report.** Structured DONE / SKIPPED / NEEDS YOUR INPUT / NEXT STEPS summary.
+
+## Surfaces
+
+- **identity** — anonymous + Apple + Google + OTP + magic link (see \`amba://setup/identity\`).
+- **engagement** — push, segments, content, onboarding, deeplinks, referrals, tracked links (\`amba://setup/engagement\`).
+- **gamification** — XP, achievements, streaks, leaderboards, challenges (\`amba://setup/gamification\`).
+- **economy** — currencies, catalog, stores, inventory (\`amba://setup/economy\`).
+- **social** — friends, groups, feeds, messaging, moderation, reviews (\`amba://setup/social\`).
+- **infrastructure** — collections (typed tables), functions, AI prompts, secrets, configs, integrations, media, sites (\`amba://setup/infrastructure\`).
+
+## SDKs
+
+| Stack | Registry | Package |
+|---|---|---|
+| Browser / Node / React / RN / Expo | npm | \`@layers/amba-{web,node,react,react-native,expo}\` |
+| Swift | SPM | \`https://github.com/layers/amba-sdk-ios\` |
+| Kotlin | Maven Central | \`com.layers.amba:amba-sdk-android\` |
+| Flutter | pub.dev | \`amba\` |
+| Unity | UPM (git) | \`https://github.com/layers/amba-sdk-unity.git\` |
+
+All SDKs expose \`Amba.configure({ projectId, apiKey })\` then \`Amba.events.track(...)\`, \`Amba.users.*\`, \`Amba.collections.*\`, etc.
+
+## Stance
+
+- **clientKey vs serverKey.** \`AMBA_CLIENT_KEY\` (\`amb_dev_ck_…\` / \`amb_live_ck_…\`) ships to user devices. \`AMBA_SERVER_KEY\` (\`amb_dev_sk_…\` / \`amb_live_sk_…\`) never does — server \`.env\` or a secret manager. Mixing them is the #1 security mistake.
+- **Default to additive, non-breaking edits.** Drop \`await Amba.configure(...)\` next to existing init, don't refactor.
+- **Don't create resources without Step 2 confirmation.**
+- **Use canonical (post-DX-12) tool names** — \`amba_<resource>_<verb>\` form. Legacy verb-leading aliases (\`amba_create_*\`, \`amba_list_*\`, etc.) still resolve but the canonical names are what to advertise.
+
+For the full playbook (per-surface MCP tool tables, per-stack SDK init snippets, common follow-ups, re-run behavior), read \`amba://setup\` and \`amba://setup/<surface>\` from the hosted MCP at \`mcp.amba.dev\`.
+`;
+}
+/**
+* Body for the marker-fenced append into `CLAUDE.md` or `AGENTS.md`.
+*
+* Plain markdown, no frontmatter — both conventions are
+* frontmatter-free. Returns the inner body only; the marker fence is
+* added by `markerFencedAppend`.
+*/
+function buildAppendableSetupBody() {
+	return buildAmbaSetupBody();
+}
+/** Write `.cursor/rules/amba.mdc`. */
+async function writeCursorRule(options = {}) {
+	const ruleDir = join(options.baseDir ?? process.cwd(), ".cursor", "rules");
+	await mkdir(ruleDir, { recursive: true });
+	const rulePath = join(ruleDir, "amba.mdc");
+	let mode = "created";
+	try {
+		await readFile(rulePath, "utf-8");
+		mode = "refreshed";
+	} catch {
+		mode = "created";
+	}
+	await writeFile(rulePath, buildCursorRuleContent(), "utf-8");
+	return {
+		path: rulePath,
+		mode
+	};
+}
+/** Write `.windsurf/rules/amba.md`. */
+async function writeWindsurfRule(options = {}) {
+	const ruleDir = join(options.baseDir ?? process.cwd(), ".windsurf", "rules");
+	await mkdir(ruleDir, { recursive: true });
+	const rulePath = join(ruleDir, "amba.md");
+	let mode = "created";
+	try {
+		await readFile(rulePath, "utf-8");
+		mode = "refreshed";
+	} catch {
+		mode = "created";
+	}
+	await writeFile(rulePath, buildWindsurfRuleContent(), "utf-8");
+	return {
+		path: rulePath,
+		mode
+	};
+}
+/**
+* Append (or refresh) the Amba setup section in `CLAUDE.md` at the
+* project root. Marker-fenced so it can be safely refreshed by
+* subsequent re-inits.
+*/
+async function writeClaudeMd(options = {}) {
+	return markerFencedAppend(join(options.baseDir ?? process.cwd(), "CLAUDE.md"), buildAppendableSetupBody(), AMBA_SETUP_START_MARKER, AMBA_SETUP_END_MARKER);
+}
+/**
+* Append (or refresh) the Amba setup section in `AGENTS.md` at the
+* project root. The `AGENTS.md` convention is read by 20+ agentic
+* tools (Codex, Aider, Zed, Copilot, Gemini CLI, Warp, etc.) so this
+* single file covers most of the long tail.
+*/
+async function writeAgentsMd(options = {}) {
+	return markerFencedAppend(join(options.baseDir ?? process.cwd(), "AGENTS.md"), buildAppendableSetupBody(), AMBA_SETUP_START_MARKER, AMBA_SETUP_END_MARKER);
+}
+async function writeAllSetupTargets(options = {}) {
+	const baseDir = options.baseDir ?? process.cwd();
+	const warn = options.warn ?? (() => {});
+	const written = [];
+	const tasks = [
+		{
+			target: "claude-md",
+			write: () => writeClaudeMd({ baseDir })
+		},
+		{
+			target: "cursor-rule",
+			write: () => writeCursorRule({ baseDir })
+		},
+		{
+			target: "agents-md",
+			write: () => writeAgentsMd({ baseDir })
+		},
+		{
+			target: "windsurf-rule",
+			write: () => writeWindsurfRule({ baseDir })
+		}
+	];
+	for (const task of tasks) try {
+		const res = await task.write();
+		written.push({
+			target: task.target,
+			path: res.path,
+			mode: res.mode
+		});
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		warn(`  ! Skipped ${task.target} setup file: ${message}`);
+	}
+	return {
+		written,
+		bodyVersion: "v2"
+	};
+}
 //#endregion
 //#region src/commands/init.ts
 function prompt(question) {
@@ -1748,6 +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);
@@ -1847,7 +3290,8 @@ Docs: https://docs.amba.dev
 }
 async function initCommand(options = {}) {
 	const cwd = process.cwd();
-	if (options.sandbox) {
+	const isNonTTY = process.stdin.isTTY !== true;
+	if (options.sandbox === true || options.json === true || isNonTTY) {
 		const result = await runSandboxInit(cwd, {
 			sandboxEmail: options.sandboxEmail,
 			noMcpConfig: options.noMcpConfig,
@@ -1860,226 +3304,298 @@ async function initCommand(options = {}) {
 		return;
 	}
 	const environment = options.env ?? "development";
-	console.log();
-	console.log(pc.bold("  amba init"));
-	console.log(pc.dim("  ─────────────────────────────────"));
-	console.log();
-	console.log(pc.bold("  Step 1/7 ") + pc.dim("Authenticate"));
-	console.log();
-	const headlessActive = resolveTokenSource({
-		flagToken: void 0,
-		envToken: process.env["AMBA_PAT"]
-	}) !== null || process.argv.includes("--token") && process.argv.length > 2;
-	let needsAuth = true;
-	if (headlessActive) {
-		console.log(pc.green("  ✓") + " Headless auth — using PAT from --token / AMBA_PAT");
-		console.log(pc.dim("    (browser flow skipped; no credentials written to disk)"));
-		console.log();
-		needsAuth = false;
-	} else try {
-		if (!isTokenExpired(await loadCredentials())) {
-			console.log(pc.green("  ✓") + " Already authenticated");
-			console.log();
-			needsAuth = false;
-		}
-	} catch {}
-	if (needsAuth) {
-		const creds = await browserAuthFlow();
-		console.log(pc.bold("  Step 2/7 ") + pc.dim("Store credentials"));
-		await storeCredentials(creds);
-		console.log(pc.green("  ✓") + " Credentials saved to ~/.amba/credentials.json");
-		console.log();
-	} else {
-		console.log(pc.bold("  Step 2/7 ") + pc.dim("Store credentials"));
-		if (headlessActive) console.log(pc.green("  ✓") + " (skipped — PAT supplied)");
-		else console.log(pc.green("  ✓") + " Using existing credentials");
-		console.log();
-	}
-	console.log(pc.bold("  Step 3/7 ") + pc.dim("Select project"));
-	console.log();
-	let projectId;
-	let projectName;
+	const startedAt = Date.now();
+	const overridePat = getBearerOverride() ?? resolveTokenSource({ envToken: process.env["AMBA_PAT"] });
+	const headlessActive = overridePat !== null;
+	let identityPat = null;
+	let identity = null;
+	let credsBackedUpTo = null;
+	let spinner = createSpinner("authenticating");
 	try {
-		const projects = (await listProjects()).data;
-		if (projects.length > 0) {
-			console.log("  Existing projects:");
-			projects.forEach((p, i) => {
-				console.log(pc.dim(`    ${i + 1}.`) + ` ${p.name} ` + pc.dim(`(${p.id})`));
-			});
-			console.log(pc.dim(`    ${projects.length + 1}.`) + " Create new project");
-			console.log();
-			const choice = await prompt(`  Select project (1-${projects.length + 1}): `);
-			const choiceNum = parseInt(choice, 10);
-			if (choiceNum > 0 && choiceNum <= projects.length) {
-				const selected = projects[choiceNum - 1];
-				if (!selected) throw new Error("Invalid selection");
-				projectId = selected.id;
-				projectName = selected.name;
-				console.log(pc.green("  ✓") + ` Selected: ${projectName}`);
-			} else {
-				const name = await prompt("  Project name: ");
-				if (!name) {
-					console.log(pc.red("  ✗") + " Project name is required");
-					process.exit(1);
+		if (headlessActive) {
+			identityPat = overridePat;
+			try {
+				identity = await verifyPat(identityPat);
+			} catch (err) {
+				const reason = err instanceof Error ? err.message : String(err);
+				spinner.stop();
+				console.error(pc.red("  ✗") + ` Could not verify supplied token: ${reason}`);
+				process.exit(1);
+			}
+			if (!identity) {
+				spinner.stop();
+				console.error(pc.red("  ✗") + " Supplied token failed verification. Check --token / AMBA_PAT and try again.");
+				process.exit(1);
+			}
+		} else {
+			let needsBrowser = false;
+			try {
+				const ensured = await ensureDeveloperIdentity({ signupOnMissing: false });
+				identity = ensured.developer;
+				identityPat = ensured.credentials.pat;
+				credsBackedUpTo = ensured.credentialsBackedUpTo;
+				setBearerOverride(ensured.credentials.pat);
+			} catch {
+				needsBrowser = true;
+			}
+			if (needsBrowser) {
+				spinner.stop();
+				await storeCredentials(await browserAuthFlow());
+				const ensured = await ensureDeveloperIdentity({ signupOnMissing: false });
+				identity = ensured.developer;
+				identityPat = ensured.credentials.pat;
+				credsBackedUpTo = ensured.credentialsBackedUpTo;
+			}
+		}
+		if (!identityPat || !identity) {
+			spinner.stop();
+			console.error(pc.red("  ✗") + " Could not establish an Amba identity.");
+			process.exit(1);
+			return;
+		}
+		const linkedProject = await loadProjectCredentials(cwd);
+		const defaultProjectName = basename(cwd) || "amba-project";
+		let projectId;
+		let projectName;
+		if (linkedProject) {
+			projectId = linkedProject.project_id;
+			projectName = linkedProject.project_name;
+		} else {
+			spinner.setLabel("loading projects");
+			let projectsList = [];
+			try {
+				projectsList = (await listProjects()).data;
+			} catch (err) {
+				if (err instanceof Error && err.message.includes("authenticate")) {
+					spinner.stop();
+					throw err;
+				}
+				projectsList = [];
+			}
+			spinner.stop();
+			if (projectsList.length > 0) {
+				console.log();
+				console.log("  Existing projects:");
+				projectsList.forEach((p, i) => {
+					const envBadge = p.environment ? pc.dim(` [${p.environment}]`) : "";
+					console.log(pc.dim(`    ${i + 1}.`) + ` ${p.name}${envBadge} ` + pc.dim(`(${p.id.slice(0, 8)}…)`));
+				});
+				const newOptionIdx = projectsList.length + 1;
+				console.log(pc.dim(`    ${newOptionIdx}.`) + ` Create new project ` + pc.dim(`(default name: ${defaultProjectName})`));
+				console.log();
+				const choice = await prompt(`  Select project (1-${newOptionIdx}, default ${newOptionIdx}): `);
+				const choiceNum = choice.length === 0 ? newOptionIdx : parseInt(choice, 10);
+				if (choiceNum > 0 && choiceNum <= projectsList.length) {
+					const selected = projectsList[choiceNum - 1];
+					if (!selected) throw new Error("Invalid selection");
+					projectId = selected.id;
+					projectName = selected.name;
+				} else {
+					const name = await prompt(`  Project name (default: ${defaultProjectName}): `);
+					const finalName = name.length > 0 ? name : defaultProjectName;
+					projectId = (await createProject({
+						name: finalName,
+						environment
+					})).data.id;
+					projectName = finalName;
 				}
+			} else {
+				const name = await prompt(`  Project name (default: ${defaultProjectName}): `);
+				const finalName = name.length > 0 ? name : defaultProjectName;
 				projectId = (await createProject({
-					name,
+					name: finalName,
 					environment
 				})).data.id;
-				projectName = name;
-				console.log(pc.green("  ✓") + ` Created: ${projectName} ${pc.dim(`(${environment})`)}`);
+				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}`);
-	}
-	console.log();
-	console.log(pc.bold("  Step 4/7 ") + pc.dim("Generate API keys"));
-	const keyRes = await createApiKey(projectId, "client", "development");
-	const apiKey = keyRes.data.key;
-	console.log(pc.green("  ✓") + " Development client key created");
-	console.log(pc.dim(`    ${keyRes.data.key_prefix}...`));
-	console.log();
-	console.log(pc.bold("  Step 5/7 ") + pc.dim("Write environment file"));
-	const envPath = join(cwd, ".env.local");
-	const envLines = [
-		"# Amba SDK Configuration",
-		`AMBA_PROJECT_ID=${projectId}`,
-		`AMBA_API_KEY=${apiKey}`,
-		`AMBA_API_URL=https://api.amba.dev`,
-		""
-	];
-	if (await fileExists(envPath)) {
-		const existing = await readFile(envPath, "utf-8");
-		if (existing.includes("AMBA_PROJECT_ID")) {
-			console.log(pc.yellow("  !") + " .env.local already contains Amba config — updating");
-			let updated = existing;
-			updated = updated.replace(/AMBA_PROJECT_ID=.*/, `AMBA_PROJECT_ID=${projectId}`);
-			updated = updated.replace(/AMBA_API_KEY=.*/, `AMBA_API_KEY=${apiKey}`);
-			updated = updated.replace(/AMBA_API_URL=.*/, `AMBA_API_URL=https://api.amba.dev`);
-			await writeFile(envPath, updated, "utf-8");
-		} else await writeFile(envPath, existing + (existing.endsWith("\n") ? "\n" : "\n\n") + envLines.join("\n"), "utf-8");
-	} else await writeFile(envPath, envLines.join("\n"), "utf-8");
-	console.log(pc.green("  ✓") + " .env.local written");
-	console.log();
-	console.log(pc.bold("  Step 6/7 ") + pc.dim("Detect framework"));
-	const framework = await detectFramework(cwd);
-	const sdkPkg = getSdkPackage(framework);
-	if (framework !== "unknown") console.log(pc.green("  ✓") + ` Detected: ${pc.bold(framework)}`);
-	else console.log(pc.yellow("  !") + " Could not detect framework");
-	let installCmd = `npm install ${sdkPkg}`;
-	if (await fileExists(join(cwd, "bun.lockb"))) installCmd = `bun add ${sdkPkg}`;
-	else if (await fileExists(join(cwd, "pnpm-lock.yaml"))) installCmd = `pnpm add ${sdkPkg}`;
-	else if (await fileExists(join(cwd, "yarn.lock"))) installCmd = `yarn add ${sdkPkg}`;
-	console.log(pc.dim(`    Install SDK: ${installCmd}`));
-	console.log();
-	console.log(pc.bold("  Step 7/7 ") + pc.dim("Generate context files"));
-	const generatedFiles = await generateContextFiles({
-		projectId,
-		projectName,
-		apiKey,
-		framework,
-		cwd
-	});
-	for (const file of generatedFiles) console.log(pc.green("  ✓") + ` ${file}`);
-	if (options.withExample) {
-		const exampleFiles = await writeExampleScaffold(cwd, framework, projectName);
-		if (exampleFiles.length > 0) for (const file of exampleFiles) console.log(pc.green("  ✓") + ` ${file} ` + pc.dim("(example)"));
-		else console.log(pc.dim("  -") + " example files already present — skipping");
-	}
-	console.log();
-	console.log(pc.dim("  ─────────────────────────────────"));
-	console.log();
-	console.log(pc.bold(pc.green("  ✓ Project initialized!")));
-	console.log();
-	console.log("  Quick start:");
-	console.log();
-	console.log(pc.dim("    1.") + ` Install the SDK`);
-	console.log(`       ${pc.cyan(installCmd)}`);
-	console.log();
-	console.log(pc.dim("    2.") + ` Add the provider to your app`);
-	if (framework === "expo") console.log(pc.dim(`       See AMBA.md for Amba.init() setup`));
-	else if (framework === "react-native") console.log(pc.dim(`       See AMBA.md for client initialization`));
-	else console.log(pc.dim(`       See AMBA.md for client initialization`));
-	console.log();
-	console.log(pc.dim("    3.") + ` Test the integration`);
-	console.log(`       ${pc.cyan("amba status")}`);
-	console.log();
-	console.log(pc.dim("    4.") + ` Send a test notification`);
-	console.log(`       ${pc.cyan("amba push test")}`);
-	console.log();
-	console.log(`  Docs: ${pc.underline("https://docs.amba.dev")}`);
-	console.log();
-}
-async function runSandboxInit(cwd, options) {
-	if (!options.json) {
+		const elapsed = formatElapsed(Date.now() - startedAt);
+		const homeForDisplay = options.homeDir;
+		const envRel = relPathForDisplay(envLocalPath, cwd, homeForDisplay);
+		const projectJsonRel = relPathForDisplay(projectJsonPath, cwd, homeForDisplay);
 		console.log();
-		console.log(pc.bold("  amba init --sandbox"));
-		console.log(pc.dim("  ─────────────────────────────────"));
+		console.log(pc.green("  ✓") + pc.bold(` Amba ready in ${elapsed}`));
+		console.log(pc.dim("    project: ") + projectName + pc.dim(` (id: ${shortId(projectId)})`));
+		console.log(pc.dim("    keys → ") + envRel + pc.dim(` · state → ${projectJsonRel}`));
+		if (mcpResults.length > 0) {
+			const mcpPathsRel = mcpResults.map((m) => relPathForDisplay(m.path, cwd, homeForDisplay)).join(", ");
+			console.log(pc.dim("    mcp → ") + mcpPathsRel + pc.dim(" (active next agent launch)"));
+			for (const m of mcpResults) if (m.backedUpTo) console.log(pc.yellow("    note: previous amba entry backed up to ") + relPathForDisplay(m.backedUpTo, cwd, homeForDisplay));
+		} else if (mcpManualSnippetNeeded) console.log(pc.dim("    mcp → ") + "no MCP client config detected (paste snippet below)");
+		if (credsBackedUpTo) console.log(pc.dim("    note: previous credentials backed up to ") + credsBackedUpTo);
 		console.log();
+		console.log(pc.dim("    next: ") + pc.cyan(installCmd));
+		console.log(pc.dim("    later: ") + pc.cyan("amba claim <your-email>") + pc.dim(" to upgrade past sandbox"));
+		console.log();
+		if (mcpManualSnippetNeeded && !options.noMcpConfig) {
+			console.log(pc.dim("  Paste into your MCP client config:"));
+			for (const line of formatManualMcpSnippet(identityPat).split("\n")) console.log(pc.dim("    ") + line);
+			console.log();
+		}
+	} finally {
+		spinner.stop();
 	}
-	const signup = await performSandboxSignup({
-		email: options.sandboxEmail?.trim() || generateSandboxEmail(),
-		password: generateSandboxPassword()
+}
+async function runSandboxInit(cwd, options) {
+	const warn = (msg) => {
+		process.stderr.write(msg + "\n");
+	};
+	const overridePat = getBearerOverride() ?? resolveTokenSource({ envToken: process.env["AMBA_PAT"] });
+	let identity;
+	if (overridePat) {
+		const verified = await verifyPat(overridePat);
+		if (!verified) throw new Error("Supplied --token / AMBA_PAT failed verification against /developer/me. Check that the token is valid and try again.");
+		identity = {
+			credentials: {
+				pat: overridePat,
+				email: verified.email
+			},
+			newlySignedUp: false,
+			developer: verified,
+			firstProject: null,
+			credentialsBackedUpTo: null,
+			credentialsPath: "(supplied via --token / AMBA_PAT — not persisted)"
+		};
+	} else identity = await ensureDeveloperIdentity({
+		homeDir: options.homeDir,
+		sandboxEmail: options.sandboxEmail
 	});
-	const envLocalPath = await writeSandboxEnvLocal(cwd, signup.project_id, signup.client_key, signup.api_url);
+	setBearerOverride(identity.credentials.pat);
 	const framework = await detectFramework(cwd);
 	const sdkPackage = getSdkPackage(framework);
+	const project = await ensureProjectForCwd(cwd, {
+		pat: identity.credentials.pat,
+		signupFirstProject: identity.firstProject ?? void 0,
+		defaultName: basename(cwd) || "amba-sandbox"
+	});
+	const envLocalPath = await writeSandboxEnvLocal(cwd, project.credentials.project_id, project.credentials.client_key, project.credentials.api_url, project.credentials.server_key);
 	const ambaMdPath = await writeSandboxAmbaMd(cwd, {
-		projectId: signup.project_id,
-		email: signup.email,
-		verifyUrl: signup.verify_url ?? null,
+		projectId: project.credentials.project_id,
+		email: identity.credentials.email,
+		verifyUrl: identity.firstProject?.verify_url ?? null,
 		sdkPackage,
 		framework,
-		apiUrl: signup.api_url
+		apiUrl: project.credentials.api_url
 	});
-	const warn = options.json ? (msg) => process.stderr.write(msg + "\n") : (msg) => console.warn(msg);
 	let mcpConfigsWritten = [];
-	if (!options.noMcpConfig) mcpConfigsWritten = await writeAllMcpConfigs(cwd, signup.pat, {
+	if (!options.noMcpConfig) mcpConfigsWritten = await writeAllMcpConfigs(cwd, identity.credentials.pat, {
 		homeDir: options.homeDir,
 		warn
 	});
-	const credentialsResult = await writeSandboxCredentials(signup.pat, { homeDir: options.homeDir });
 	let skillPath = null;
-	if (!options.noSkills) try {
-		skillPath = (await writeAmbaBuildSkill({ baseDir: cwd })).path;
-	} catch (err) {
-		warn(`  ! Skipped /amba-build skill install: ${err instanceof Error ? err.message : String(err)}`);
+	let setupTargets = [];
+	if (!options.noSkills) {
+		try {
+			const installResults = await installSkillBundle(cwd);
+			summarizeSkillInstall(installResults);
+			skillPath = (installResults.find((r) => r.target.kind === "claude-code")?.files.find((f) => f.path.endsWith("SKILL.md")))?.path ?? null;
+		} catch (err) {
+			warn(`  ! Skipped amba skill bundle install: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		try {
+			await writeAmbaBuildSkill({ baseDir: cwd });
+		} catch (err) {
+			warn(`  ! Skipped legacy /amba-build skill: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		setupTargets = (await writeAllSetupTargets({
+			baseDir: cwd,
+			warn
+		})).written.map((w) => ({
+			target: w.target,
+			path: w.path,
+			mode: w.mode
+		}));
 	}
+	if (!await verifyPat(identity.credentials.pat, { apiUrl: project.credentials.api_url })) throw new Error("Post-write verify failed: PAT was provisioned but no longer accepted by /developer/me. This usually means the control-plane signup race hasn't settled yet — retry in 5s.");
 	return {
-		email: signup.email,
-		projectId: signup.project_id,
-		pat: signup.pat,
-		patPreview: `${signup.pat.slice(0, 12)}…${signup.pat.slice(-4)}`,
-		clientKey: signup.client_key,
-		apiUrl: signup.api_url,
-		credentialsPath: credentialsResult.path,
-		credentialsBackedUpTo: credentialsResult.backedUpTo,
+		email: identity.credentials.email,
+		projectId: project.credentials.project_id,
+		pat: identity.credentials.pat,
+		patPreview: `${identity.credentials.pat.slice(0, 12)}…${identity.credentials.pat.slice(-4)}`,
+		clientKey: project.credentials.client_key,
+		apiUrl: project.credentials.api_url,
+		credentialsPath: identity.credentialsPath,
+		credentialsBackedUpTo: identity.credentialsBackedUpTo,
 		envLocalPath,
 		ambaMdPath,
 		mcpConfigsWritten,
 		sdkPackage,
 		framework,
-		verifyUrl: signup.verify_url ?? null,
-		provisioningStatus: signup.provisioning_status ?? "unknown",
-		skillPath
+		verifyUrl: identity.firstProject?.verify_url ?? null,
+		provisioningStatus: identity.firstProject?.provisioning_status ?? "active",
+		skillPath,
+		setupTargets
 	};
 }
 function sandboxResultToJson(r) {
@@ -2102,83 +3618,83 @@ function sandboxResultToJson(r) {
 			backed_up_to: m.backedUpTo
 		})),
 		skill_path: r.skillPath,
+		setup_targets: r.setupTargets.map((t) => ({
+			target: t.target,
+			path: t.path,
+			mode: t.mode
+		})),
 		verify_url: r.verifyUrl,
 		provisioning_status: r.provisioningStatus,
-		next_steps: ["restart your MCP client"]
+		next_steps: [`npm install ${r.sdkPackage}`, "call Amba.configure({ projectId, clientKey }) at app startup"],
+		runtime_mcp: {
+			configs_written: r.mcpConfigsWritten.map((m) => m.path),
+			activates_on: "next agent launch",
+			in_session_inline_pat: true
+		}
 	};
 }
 /**
 * Build the plaintext (no ANSI) success-output block printed at the
-* end of `amba init --sandbox`. Pure function — exported only for the
-* vitest cases that assert on per-line content. The CLI wraps each
-* line with picocolors in `printSandboxNextSteps` below.
-*
-* Structure (in order):
-*   1. Per-artifact checklist (`✓ ...` lines)
-*   2. SDK install + configure hint
-*   3. "Done." + per-client restart bullets — ONLY for clients we
-*      actually wrote configs to. Never instruct the user to "restart
-*      Cursor" if we only touched `~/.claude.json`. When no config
-*      was written (manual-paste path), falls back to a generic
-*      "quit + reopen" line.
-*   4. Tail-line resume hint + sandbox limits + verify URL.
-*
-* We intentionally do NOT print any "kill -HUP / SIGHUP" advanced
-* workaround. Telling the agent to surface a clean "restart your MCP
-* client" instruction to the human is the whole optimization — adding
-* an experimental fallback just dilutes the signal and risks the
-* agent surfacing the workaround instead.
+* end of `amba init --sandbox`. Pure function — exported for the
+* vitest cases that assert on per-line content. The CLI wraps the
+* output with picocolors in `printSandboxNextSteps` below.
+*
+* Design: silent-until-done. The install (provision account, mint
+* keys, write .env.local, write MCP config, install skill) is COMPLETE
+* the moment this output lands. The MCP config has been persisted —
+* it activates on the next launch of the developer's coding agent. We
+* do NOT instruct the developer to restart anything; we just state
+* what's wired and what's next.
+*
+* Shape (~6 lines, Vercel/Stripe aesthetic):
+*   ✓ Amba ready
+*     project: <id>
+*     keys → .env.local
+*     mcp → <paths> (active next agent launch)
+*     skill → <skill paths> (when installed)
+*
+*     next: npm install <sdk-pkg>
+*           Amba.configure({ projectId, clientKey }) at app startup
+*
+* The fallback for "no MCP client config detected" is a one-line
+* note + a paste-ready snippet — still no restart copy.
 */
 function buildSandboxNextStepsLines(r) {
 	const lines = [];
-	lines.push(`✓ Sandbox account provisioned (${r.email})`);
-	lines.push(`✓ Project created: ${r.projectId}`);
-	lines.push(`✓ Credentials saved to ~/.amba/credentials.json`);
-	if (r.credentialsBackedUpTo) lines.push(`  ! Existing non-sandbox credentials backed up to ${r.credentialsBackedUpTo}`);
-	lines.push(`✓ .env.local updated with AMBA_PROJECT_ID + AMBA_CLIENT_KEY + AMBA_API_URL`);
-	lines.push(`✓ AMBA.md written (sandbox guide)`);
-	if (r.skillPath) lines.push(`✓ /amba-build skill installed: ${r.skillPath}`);
-	const clientKinds = clientKindsFromPaths(r.mcpConfigsWritten.map((m) => m.path));
-	if (r.mcpConfigsWritten.length > 0) for (const m of r.mcpConfigsWritten) {
-		lines.push(`✓ MCP config updated: ${m.path} (entry: 'amba')`);
-		if (m.backedUpTo) lines.push(`  ! Existing amba entry backed up to ${m.backedUpTo}`);
-	}
-	else {
-		lines.push(`! No MCP client config detected — paste this into your MCP client's config manually:`);
+	lines.push(`✓ Amba ready`);
+	lines.push(`  project: ${shortId(r.projectId)} (${r.email})`);
+	lines.push(`  keys → ${r.envLocalPath}`);
+	if (r.mcpConfigsWritten.length > 0) {
+		const mcpPaths = r.mcpConfigsWritten.map((m) => m.path).join(", ");
+		lines.push(`  mcp → ${mcpPaths} (active next agent launch)`);
+		for (const m of r.mcpConfigsWritten) if (m.backedUpTo) lines.push(`  note: previous amba entry backed up to ${m.backedUpTo}`);
+	} else lines.push(`  mcp → no MCP client config detected (paste snippet below)`);
+	if (r.skillPath) lines.push(`  skill → ${r.skillPath}`);
+	if (r.credentialsBackedUpTo) lines.push(`  note: previous non-sandbox credentials backed up to ${r.credentialsBackedUpTo}`);
+	lines.push("");
+	lines.push(`  next: npm install ${r.sdkPackage}`);
+	lines.push(`        Amba.configure({ projectId: process.env.AMBA_PROJECT_ID, clientKey: process.env.AMBA_CLIENT_KEY })`);
+	lines.push(`  later: amba claim <your-email> to upgrade past sandbox`);
+	if (r.mcpConfigsWritten.length === 0) {
 		lines.push("");
+		lines.push(`  Paste into your MCP client config:`);
 		for (const snippetLine of formatManualMcpSnippet(r.pat).split("\n")) lines.push(`    ${snippetLine}`);
-		lines.push("");
 	}
-	lines.push("");
-	lines.push("Next:");
-	lines.push(`  → npm install ${r.sdkPackage}`);
-	lines.push(`  → Initialize the SDK in your app entry: Amba.configure({ projectId: process.env.AMBA_PROJECT_ID, clientKey: process.env.AMBA_CLIENT_KEY })`);
-	lines.push("");
-	lines.push("Done. Restart your MCP client so it loads the Amba MCP server:");
-	if (clientKinds.length === 0) lines.push("  • Quit your MCP client (Cmd+Q on macOS) and reopen it.");
-	else for (const kind of clientKinds) lines.push(`  • ${restartHintForClient(kind)}`);
-	lines.push("");
-	lines.push("After the restart, re-ask the original question — Amba's MCP toolset will be available.");
-	if (r.skillPath) lines.push("Tip: paste `/amba-build <design-url>` to scaffold a full Expo app with Amba as the backend.");
-	lines.push("");
-	lines.push(`Sandbox limits: 100 MAU, 10 MB DB. Verify ${r.email} in the console to upgrade to Free.`);
-	if (r.verifyUrl) lines.push(`Verify URL: ${r.verifyUrl}`);
 	return lines;
 }
-function restartHintForClient(kind) {
-	switch (kind) {
-		case "claude-code": return "Claude Code: Cmd+Q, then reopen";
-		case "cursor": return "Cursor: Cmd+Q, then reopen";
-		case "windsurf": return "Windsurf: quit + relaunch";
-	}
-}
 function printSandboxNextSteps(r) {
-	for (const line of buildSandboxNextStepsLines(r)) if (line.startsWith("✓ ")) console.log(pc.green("  " + line.slice(0, 2)) + line.slice(2));
-	else if (line.startsWith("! ")) console.log(pc.yellow("  " + line.slice(0, 2)) + line.slice(2));
-	else if (line.startsWith("  ! ")) console.log(pc.yellow("    ! ") + line.slice(4));
-	else if (line.startsWith("Next:") || line.startsWith("Done. Restart your MCP client")) console.log(pc.bold("  " + line));
-	else if (line.startsWith("Sandbox limits:") || line.startsWith("Verify URL:") || line.startsWith("After the restart")) console.log(pc.dim("  " + line));
-	else console.log("  " + line);
+	const lines = buildSandboxNextStepsLines(r);
+	console.log();
+	for (const line of lines) if (line.startsWith("✓ ")) console.log("  " + pc.green("✓") + pc.bold(line.slice(1)));
+	else if (line.startsWith("  note:")) console.log("  " + pc.yellow(line.slice(2)));
+	else if (line.startsWith("  next:")) {
+		const cmd = line.slice(8);
+		console.log("  " + pc.dim("next: ") + pc.cyan(cmd));
+	} else if (line.startsWith("  later:")) {
+		const cmd = line.slice(9);
+		console.log("  " + pc.dim("later: ") + pc.cyan(cmd));
+	} else if (line.startsWith("  project:") || line.startsWith("  keys") || line.startsWith("  mcp") || line.startsWith("  skill")) console.log(pc.dim(line));
+	else console.log(line);
 	console.log();
 }
 //#endregion
@@ -2551,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}`);
@@ -2601,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) {
@@ -2627,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
 		});
@@ -2637,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.)"));
 		}
@@ -2646,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) {
@@ -2664,7 +4207,7 @@ async function projectsShowCommand(projectId) {
 			console.log();
 			process.exit(1);
 		}
-		handleError(err);
+		handleError$1(err);
 	}
 }
 async function projectsDeleteCommand(projectId, opts = {}) {
@@ -2689,7 +4232,7 @@ async function projectsDeleteCommand(projectId, opts = {}) {
 			console.log();
 			process.exit(1);
 		}
-		handleError(err);
+		handleError$1(err);
 	}
 }
 //#endregion
@@ -2993,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}`));
@@ -3410,36 +4953,44 @@ function parseEnv(content) {
 /**
 * Customer-function bundling for `amba functions deploy`.
 *
-* Uses esbuild (the Workers ecosystem bundler-of-record). The shared
-* runtime stdlib is marked `external` so customer bundles don't
-* re-include megabytes of `@anthropic-ai/sdk`, `postgres`, `zod`, etc.;
-* these resolve at dispatch time via platform-level bindings.
+* Uses esbuild. Customer code is bundled into a single self-contained
+* ES module — the upstream runtime resolves nothing at dispatch time
+* except built-in JavaScript globals.
 *
 * Two checks gate the bundle before upload:
 *   1. Pre-upload size check against `BUNDLE_MAX_SIZE_BYTES` (8 MB
 *      default — the platform's 10 MB compressed cap minus 2 MB
 *      headroom) with a clear error pointing at the externalization
 *      config.
-*   2. Bundle-shape report — the CLI prints what's externalized vs
-*      bundled at deploy time so size issues are debuggable.
+*   2. Bundle-shape report — the CLI prints what's bundled vs
+*      externalized at deploy time so size issues are debuggable.
+*
+* History note (2026-05-27): the prior version of this file pinned
+* `@layers/amba-functions` + `@layers/amba-api-middleware` as
+* "platform-level bindings" externals. Neither is — they were
+* server-side packages, and `@layers/amba-functions` was unpublished
+* in the 4.0.2 cutover (a deprecated wrapper that never matched the
+* actual runtime). Any function importing one of them was rejected
+* upstream as "no such module." The default externals list is now
+* empty; customer code is expected to be self-contained.
 */
 /**
-* Modules customer code MUST externalize. The runtime exposes these as
-* platform-level bindings; bundling them per-script wastes hundreds of
-* KB to MBs and quickly hits the script-size cap.
+* Modules the bundler treats as `external` by default. The Amba
+* function runtime exposes zero npm packages — there is no "platform
+* stdlib" for customer functions to import. Keep this list empty.
+*
+* The `extraExternals` field on `BundleOptions` is a programmatic
+* escape hatch (used by tests + future CLI wiring). It's intentionally
+* not exposed as a `amba functions deploy` flag today — externalizing
+* a module that isn't actually provided at runtime is exactly the
+* footgun this list-defaults-to-empty change closes.
 */
-const RUNTIME_STDLIB_EXTERNALS = [
-	"@layers/amba-functions",
-	"@layers/amba-api-middleware",
-	"@anthropic-ai/sdk",
-	"postgres",
-	"zod"
-];
+const RUNTIME_STDLIB_EXTERNALS = [];
 var BundleSizeError = class extends Error {
 	sizeBytes;
 	maxBytes;
 	constructor(sizeBytes, maxBytes) {
-		super(`Function bundle is ${formatBytes$1(sizeBytes)} which exceeds the ${formatBytes$1(maxBytes)} cap. Externalize heavy dependencies via the runtime stdlib (see RUNTIME_STDLIB_EXTERNALS) or split your function into smaller pieces.`);
+		super(`Function bundle is ${formatBytes$1(sizeBytes)} which exceeds the ${formatBytes$1(maxBytes)} cap. Split the function into smaller pieces or drop heavy dependencies. (There is no runtime-provided npm stdlib to externalize against — every import must bundle.)`);
 		this.sizeBytes = sizeBytes;
 		this.maxBytes = maxBytes;
 		this.name = "BundleSizeError";
@@ -3496,8 +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) {
@@ -4148,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() {
@@ -4160,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) {
@@ -4256,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.
@@ -4982,6 +6696,9 @@ program.command("init").description("Initialize Amba in the current project (min
 		json: opts.json
 	}));
 });
+program.command("claim <email>").description("Bind your sandbox account to a real email (sends a one-click magic link)").action(async (email) => {
+	await runAction(() => claimCommand(email));
+});
 program.command("login").description("Authenticate with Amba").action(async () => {
 	await runAction(loginCommand);
 });
@@ -5010,14 +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; new projects default to the 'development' environment)").option("--bundle-id <id>", "Bundle identifier (iOS/Android)").option("--platform <platform>", "Platform: 'ios' | 'android' | 'all'").action(async (opts) => {
+projects.command("create").description("Create a new project").requiredOption("--name <name>", "Project name").option("--env <env>", "Environment hint (informational; new projects default to the 'development' environment)").option("--bundle-id <id>", "Bundle identifier (iOS/Android). Audience for Sign in with Apple.").option("--google-oauth-client-id <id>", "Google OAuth 2.0 client id. Audience for Sign in with Google.").option("--platform <platform>", "Platform: 'ios' | 'android' | 'all'").action(async (opts) => {
 	await runAction(() => projectsCreateCommand({
 		name: opts.name,
 		env: opts.env,
 		bundleId: opts.bundleId,
+		googleOauthClientId: opts.googleOauthClientId,
 		platform: opts.platform
 	}));
 });
+projects.command("update <projectId>").description("Update mutable fields on a project").option("--name <name>", "Display name").option("--bundle-id <id>", "Bundle identifier (Apple Sign In audience)").option("--google-oauth-client-id <id>", "Google OAuth 2.0 client id (Google Sign In audience). Public identifier, not a secret.").option("--platform <platform>", "Platform: 'ios' | 'android' | 'all'").option("--environment <env>", "Environment label: 'development' | 'production'").action(async (projectId, opts) => {
+	await runAction(() => projectsUpdateCommand(projectId, {
+		name: opts.name,
+		bundleId: opts.bundleId,
+		googleOauthClientId: opts.googleOauthClientId,
+		platform: opts.platform,
+		environment: opts.environment
+	}));
+});
 projects.command("show <projectId>").description("Show full project details as JSON").action(async (projectId) => {
 	await runAction(() => projectsShowCommand(projectId));
 });
@@ -5113,6 +6840,40 @@ 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 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));