@layers/amba 4.1.8 → 4.1.9

package/README.md

@@ -42,6 +42,21 @@ fetches the canonical prompt from
 falls back to an inlined snapshot when offline. Use `--no-skills` to
 skip the skill install.
 
+### Invite-only signups
+
+While new accounts are invite-only, pass your invite code:
+
+```bash
+npx @layers/amba init --invite <code-from-your-invite-email>
+```
+
+`AMBA_INVITE_CODE` works too; the flag wins when both are set. Without
+a valid code, init stops with `INVITE_REQUIRED`, `INVITE_INVALID` or
+`SIGNUPS_CLOSED` and prints where to request access
+(<https://app.amba.dev/request-access>). The invite code arrives by
+email. With `--json`, the failure is a JSON document on stdout carrying
+`error.code`.
+
 ## Configure + first call
 
 ```bash

package/dist/commands/billing.d.ts

@@ -23,6 +23,37 @@
  * Project is resolved via `loadProjectConfig` (AMBA_PROJECT_ID env, then
  * .env / .env.local in the cwd) — same pattern as `amba secrets *`.
  */
+/** Database limits block (free-tier compute + storage caps). */
+interface DatabaseLimits {
+    limits_enforced: boolean;
+    source?: 'tier' | 'override' | 'unmanaged';
+    compute: {
+        max_cu: number;
+        used_cu_hours: number | null;
+        limit_cu_hours: number | null;
+        pct: number | null;
+    };
+    storage: {
+        used_mb: number | null;
+        limit_mb: number | null;
+        pct: number | null;
+    };
+    period: {
+        start: string;
+        resets_at: string;
+    } | null;
+    limit_reached: ('database_compute' | 'database_storage')[];
+    observed_at: string | null;
+    upgrade?: {
+        cli?: string;
+        mcp_tool?: string;
+    } | null;
+}
+/**
+ * Print the database limits block. Exported for `amba status`'s one-line
+ * summary + tests.
+ */
+export declare function formatDatabaseLimits(db: DatabaseLimits): string[];
 export declare function billingStatusCommand(): Promise<void>;
 export declare function billingUpgradeCommand(input: {
     tier: 'pro' | 'scale';
@@ -32,3 +63,4 @@ export declare function billingPortalCommand(): Promise<void>;
 export declare function billingSetCeilingCommand(input: {
     ceiling: number | null;
 }): Promise<void>;
+export {};

package/dist/commands/init.d.ts

@@ -21,6 +21,12 @@ export interface InitOptions {
     sandbox?: boolean;
     /** Override the auto-generated sandbox email. Only meaningful with `--sandbox`. */
     sandboxEmail?: string;
+    /**
+     * Platform invite code (`--invite`) sent with the sandbox signup when
+     * new accounts are invite-only. Falls back to `AMBA_INVITE_CODE`.
+     * Passing the flag selects the headless signup path.
+     */
+    inviteCode?: string;
     /** Skip MCP-client-config writes. Mostly for testing. */
     noMcpConfig?: boolean;
     /**
@@ -38,6 +44,8 @@ export interface InitOptions {
 export declare function initCommand(options?: InitOptions): Promise<void>;
 export declare function runSandboxInit(cwd: string, options: {
     sandboxEmail?: string;
+    /** Platform invite code for a fresh signup; falls back to `AMBA_INVITE_CODE`. */
+    inviteCode?: string;
     noMcpConfig?: boolean;
     /**
      * Skip the project-local skill install. Default is to install. Set
@@ -52,6 +60,11 @@ export declare function runSandboxInit(cwd: string, options: {
      */
     homeDir?: string;
 }): Promise<SandboxResult>;
+/**
+ * `--json` failure document. A gated signup carries its 403 code plus
+ * where to request access; every other failure reports `INIT_FAILED`.
+ */
+export declare function sandboxErrorToJson(err: unknown): Record<string, unknown>;
 /**
  * Build the plaintext (no ANSI) success-output block printed at the
  * end of `amba init --sandbox`. Pure function — exported for the

package/dist/credentials.d.ts

@@ -148,6 +148,11 @@ export interface EnsureDeveloperOptions {
      * identity is reused.
      */
     sandboxEmail?: string;
+    /**
+     * Platform invite code for the sandbox signup (`--invite`). Falls back
+     * to `AMBA_INVITE_CODE`. Ignored when an existing identity is reused.
+     */
+    inviteCode?: string;
 }
 export interface EnsureDeveloperResult {
     credentials: DeveloperCredentials;

package/dist/index.js

@@ -1326,6 +1326,64 @@ function generateSandboxPassword() {
 }
 /** Request header carrying AMBA_SIGNUP_TOKEN on the signup call. */
 const SIGNUP_TOKEN_HEADER = "X-Amba-Signup-Token";
+/** Environment variable read when `--invite` is absent. */
+const INVITE_CODE_ENV = "AMBA_INVITE_CODE";
+/** The 403 codes signup answers with when the platform is gated. */
+const SIGNUP_ACCESS_ERROR_CODES = [
+	"SIGNUPS_CLOSED",
+	"INVITE_REQUIRED",
+	"INVITE_INVALID"
+];
+const DEFAULT_REQUEST_ACCESS_URL = `${CONSOLE_URL}/request-access`;
+const REQUEST_ACCESS_ENDPOINT = `POST /v1/auth/developer/waitlist`;
+const RERUN_WITH_INVITE = "npx @layers/amba init --invite <code>";
+function isSignupAccessErrorCode(code) {
+	return SIGNUP_ACCESS_ERROR_CODES.includes(code);
+}
+/**
+* The flag value when set, else `AMBA_INVITE_CODE`, else undefined. Blank
+* values count as absent so an empty env var never sends `invite_code: ""`.
+*/
+function resolveInviteCode(flag) {
+	const fromFlag = flag?.trim();
+	if (fromFlag) return fromFlag;
+	return process.env["AMBA_INVITE_CODE"]?.trim() || void 0;
+}
+/**
+* Ordered next steps for a gated signup, phrased for whoever runs the CLI
+* (a developer or their coding agent).
+*/
+function signupAccessNextSteps(code, requestAccessUrl) {
+	const requestAccess = `Request access at ${requestAccessUrl}; the invite code arrives by email.`;
+	switch (code) {
+		case "INVITE_REQUIRED": return [`Have an invite code? Rerun \`${RERUN_WITH_INVITE}\` (or set ${INVITE_CODE_ENV}).`, `No code yet? ${requestAccess}`];
+		case "INVITE_INVALID": return [`Check the code and rerun \`${RERUN_WITH_INVITE}\` (or correct ${INVITE_CODE_ENV}).`, `Need a fresh code? ${requestAccess}`];
+		case "SIGNUPS_CLOSED": return [`${requestAccess} Rerun \`${RERUN_WITH_INVITE}\` once it lands.`];
+	}
+}
+/**
+* Thrown when signup answers 403 SIGNUPS_CLOSED / INVITE_REQUIRED /
+* INVITE_INVALID. `message` carries the server's sentence plus the next
+* steps; the structured fields feed `amba init --json`.
+*/
+var SignupAccessError = class extends Error {
+	code;
+	serverMessage;
+	requestAccessUrl;
+	requestAccessEndpoint;
+	nextSteps;
+	constructor(input) {
+		const requestAccessUrl = input.requestAccessUrl ?? DEFAULT_REQUEST_ACCESS_URL;
+		const nextSteps = signupAccessNextSteps(input.code, requestAccessUrl);
+		super([`Sandbox signup failed (${input.code}): ${input.serverMessage}`, ...nextSteps].join("\n  "));
+		this.name = "SignupAccessError";
+		this.code = input.code;
+		this.serverMessage = input.serverMessage;
+		this.requestAccessUrl = requestAccessUrl;
+		this.requestAccessEndpoint = input.requestAccessEndpoint ?? REQUEST_ACCESS_ENDPOINT;
+		this.nextSteps = nextSteps;
+	}
+};
 /**
 * POST the synthesized credentials at the public signup endpoint.
 *
@@ -1337,7 +1395,8 @@ const SIGNUP_TOKEN_HEADER = "X-Amba-Signup-Token";
 * Returns the unwrapped, flattened shape consumed by the rest of the
 * sandbox flow. Throws with a human-readable message on any non-2xx so
 * the CLI's `runAction` wrapper can surface it without crashing on a
-* generic 'fetch failed'.
+* generic 'fetch failed'. A gated platform (403 SIGNUPS_CLOSED /
+* INVITE_REQUIRED / INVITE_INVALID) throws `SignupAccessError`.
 */
 async function performSandboxSignup(req, options = {}) {
 	const apiUrl = options.apiUrl ?? process.env["AMBA_API_URL"] ?? "https://api.amba.dev";
@@ -1349,21 +1408,32 @@ async function performSandboxSignup(req, options = {}) {
 	};
 	const signupToken = process.env["AMBA_SIGNUP_TOKEN"]?.trim();
 	if (signupToken) headers[SIGNUP_TOKEN_HEADER] = signupToken;
+	const body = {
+		email: req.email,
+		password: req.password,
+		name: req.name ?? "amba-sandbox-cli"
+	};
+	const inviteCode = resolveInviteCode(req.inviteCode);
+	if (inviteCode) body["invite_code"] = inviteCode;
 	const res = await fetchImpl(url, {
 		method: "POST",
 		headers,
-		body: JSON.stringify({
-			email: req.email,
-			password: req.password,
-			name: req.name ?? "amba-sandbox-cli"
-		})
+		body: JSON.stringify(body)
 	});
 	if (!res.ok) {
 		let detail = `${res.status} ${res.statusText}`;
+		let errorBody = {};
 		try {
-			const body = await res.json();
-			if (body.error?.message) detail = body.error.message;
+			errorBody = await res.json();
+			if (errorBody.error?.message) detail = errorBody.error.message;
 		} catch {}
+		const code = errorBody.error?.code;
+		if (res.status === 403 && isSignupAccessErrorCode(code)) throw new SignupAccessError({
+			code,
+			serverMessage: detail,
+			requestAccessUrl: errorBody.error?.details?.request_access_url,
+			requestAccessEndpoint: errorBody.error?.details?.request_access_endpoint
+		});
 		throw new Error(`Sandbox signup failed: ${detail}`);
 	}
 	let raw;
@@ -1963,7 +2033,8 @@ async function ensureDeveloperIdentity(options = {}) {
 	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()
+		password: generateSandboxPassword(),
+		inviteCode: options.inviteCode
 	}, {
 		apiUrl,
 		fetchImpl
@@ -2716,6 +2787,8 @@ Tell the user where their credentials live:
 - \`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.
 
+**Signup refused with 403 \`INVITE_REQUIRED\` or \`INVITE_INVALID\`?** New accounts need an invite code right now. Ask the developer for theirs (it starts with \`AMBA-\` and arrives in their invite email) and call \`amba_developer_signup\` again with the same arguments plus \`invite_code\`. If they have no code, or the answer is \`SIGNUPS_CLOSED\`, offer to request access for them: \`POST https://api.amba.dev/v1/auth/developer/waitlist\` with \`{ "email": "<their own email>", "note": "<optional>" }\`, or send them to the \`error.details.request_access_url\` page. Tell them the invite code arrives by email, then stop. Retry only with a code the developer hands you; never retry in a loop, invent codes, or try other email addresses. From a terminal, the code goes to \`npx @layers/amba init --invite <code>\` (or the \`AMBA_INVITE_CODE\` env var).
+
 **Already have a PAT?** Skip the signup. Call \`amba_developer_me({})\` to verify the Bearer; if it succeeds, either reuse the most recent project (\`amba_projects_list\`) or call \`amba_projects_create({ name: "<app-name>", platform: "all" })\` and then \`amba_api_keys_create\` twice to mint client + server keys for \`environment: "development"\`.
 
 **Can't reach \`amba_developer_signup\` — it's not in your tool list, or your harness blocks the call?** Do NOT try to work around it by adding the MCP server yourself, running an installer, or editing your own settings/permissions — refusing to self-modify or widen your own permissions is the correct call, and you should not circumvent it. Instead, hand the developer **one** command to run in **their own** terminal (which is not subject to your sandbox):
@@ -2869,8 +2942,8 @@ Be specific. List resources by key, not "some achievements". If something needs
 ## 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.
+- 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. While signups are invite-only, add \`--invite <code>\` (or set \`AMBA_INVITE_CODE\`).
+- Bind the sandbox account to its human owner as soon as you know who that is: \`amba_developer_claim\` with their email (or \`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. Each free project of an unclaimed sandbox runs its own clock from when it was created: a claim notice from day 7, a hold on day 14, and an archive on day 90 after a full hold (archiving deletes nothing); claiming lifts all of it.
 - Hosted MCP endpoint: \`https://mcp.amba.dev/mcp\` (Streamable HTTP, Bearer auth).
 
 ## SDKs
@@ -3882,14 +3955,21 @@ Docs: https://docs.amba.dev
 async function initCommand(options = {}) {
 	const cwd = process.cwd();
 	const isNonTTY = process.stdin.isTTY !== true;
-	if (options.sandbox === true || options.json === true || isNonTTY) {
-		const result = await runSandboxInit(cwd, {
-			sandboxEmail: options.sandboxEmail,
-			noMcpConfig: options.noMcpConfig,
-			noSkills: options.noSkills,
-			json: options.json,
-			homeDir: options.homeDir
-		});
+	if (options.sandbox === true || options.json === true || Boolean(options.inviteCode?.trim()) || isNonTTY) {
+		let result;
+		try {
+			result = await runSandboxInit(cwd, {
+				sandboxEmail: options.sandboxEmail,
+				inviteCode: options.inviteCode,
+				noMcpConfig: options.noMcpConfig,
+				noSkills: options.noSkills,
+				json: options.json,
+				homeDir: options.homeDir
+			});
+		} catch (err) {
+			if (options.json) process.stdout.write(JSON.stringify(sandboxErrorToJson(err), null, 2) + "\n");
+			throw err;
+		}
 		if (options.json) process.stdout.write(JSON.stringify(sandboxResultToJson(result), null, 2) + "\n");
 		else printSandboxNextSteps(result);
 		return;
@@ -4134,7 +4214,8 @@ async function runSandboxInit(cwd, options) {
 		};
 	} else identity = await ensureDeveloperIdentity({
 		homeDir: options.homeDir,
-		sandboxEmail: options.sandboxEmail
+		sandboxEmail: options.sandboxEmail,
+		inviteCode: options.inviteCode
 	});
 	setBearerOverride(identity.credentials.pat);
 	const framework = await detectFramework(cwd);
@@ -4203,6 +4284,31 @@ async function runSandboxInit(cwd, options) {
 		setupTargets
 	};
 }
+/**
+* `--json` failure document. A gated signup carries its 403 code plus
+* where to request access; every other failure reports `INIT_FAILED`.
+*/
+function sandboxErrorToJson(err) {
+	if (err instanceof SignupAccessError) return {
+		ok: false,
+		mode: "sandbox",
+		error: {
+			code: err.code,
+			message: err.serverMessage,
+			request_access_url: err.requestAccessUrl,
+			request_access_endpoint: err.requestAccessEndpoint
+		},
+		next_steps: err.nextSteps
+	};
+	return {
+		ok: false,
+		mode: "sandbox",
+		error: {
+			code: "INIT_FAILED",
+			message: err instanceof Error ? err.message : String(err)
+		}
+	};
+}
 function sandboxResultToJson(r) {
 	return {
 		ok: true,
@@ -6861,6 +6967,28 @@ async function adminWrite$1(method, path, body) {
 	}
 	return await res.json();
 }
+function pctLabel(pct) {
+	return pct === null ? "" : pc.dim(` (${Math.round(pct * 100)}%)`);
+}
+/**
+* Print the database limits block. Exported for `amba status`'s one-line
+* summary + tests.
+*/
+function formatDatabaseLimits(db) {
+	const lines = [];
+	const computeUsed = db.compute.used_cu_hours === null ? "—" : `${db.compute.used_cu_hours}`;
+	const computeLimit = db.compute.limit_cu_hours === null ? "no cap" : `${db.compute.limit_cu_hours} CU-hours`;
+	lines.push(`  ${pc.dim("Database compute".padEnd(22))} ${computeUsed} / ${computeLimit}${pctLabel(db.compute.pct)}` + pc.dim(`  max ${db.compute.max_cu} CU`));
+	const storageUsed = db.storage.used_mb === null ? "—" : `${db.storage.used_mb} MB`;
+	const storageLimit = db.storage.limit_mb === null ? "no cap" : `${db.storage.limit_mb} MB`;
+	lines.push(`  ${pc.dim("Database size".padEnd(22))} ${storageUsed} / ${storageLimit}${pctLabel(db.storage.pct)}`);
+	if (db.period && db.compute.limit_cu_hours !== null) lines.push(`  ${pc.dim("Compute resets".padEnd(22))} ${new Date(db.period.resets_at).toLocaleDateString(void 0, { timeZone: "UTC" })} UTC`);
+	const upgrade = db.upgrade?.cli ?? "amba billing upgrade --tier pro";
+	if (db.limit_reached.includes("database_compute")) lines.push(pc.red("  Database paused: ") + `compute limit reached; database calls return 402 FREE_TIER_LIMIT_REACHED until the period resets. Upgrade now: ${pc.bold(upgrade)}`);
+	if (db.limit_reached.includes("database_storage")) lines.push(pc.red("  Database full: ") + `storage limit reached; writes that add data return 402. Delete data or upgrade: ${pc.bold(upgrade)}`);
+	else if (!db.limit_reached.includes("database_compute") && db.compute.pct !== null && db.compute.pct >= .8) lines.push(pc.yellow("  Near the compute limit: ") + `upgrade before the database pauses: ${pc.bold(upgrade)}`);
+	return lines;
+}
 /** Append "· $X.XX" to a usage line when the meter accrued cost this period. */
 function costSuffix(cost) {
 	if (!cost || cost.cost_usd <= 0) return "";
@@ -6909,6 +7037,11 @@ async function billingStatusCommand() {
 		console.log(formatAxis("Database storage", s.headroom.db_storage_mb, true) + costSuffix(cost.db_storage_mb));
 		console.log(formatAxis("Media storage", s.headroom.media_storage_mb, true) + costSuffix(cost.media_storage_mb));
 		if (s.headroom.app_mcp_tool_calls) console.log(formatAxis("Agent tool calls", s.headroom.app_mcp_tool_calls, false) + costSuffix(cost.app_mcp_tool_calls));
+		if (s.database) {
+			console.log();
+			console.log(pc.bold("  Database limits") + (s.database.observed_at ? pc.dim(` — measured ${new Date(s.database.observed_at).toLocaleString()}`) : ""));
+			for (const line of formatDatabaseLimits(s.database)) console.log(line);
+		}
 		console.log();
 		if (s.human_action_required !== "none") {
 			const action = s.human_action_required.replaceAll("_", " ");
@@ -6939,6 +7072,7 @@ async function billingUpgradeCommand(input) {
 		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(pc.dim("  Paid plans lift the free-tier database compute cap; a paused database resumes within seconds."));
 		console.log();
 	} catch (err) {
 		handleError$1(err);
@@ -9811,7 +9945,7 @@ async function diffConfigCommand(file = DEFAULT_BUNDLE_FILE, options = {}) {
 //#endregion
 //#region src/index.ts
 const program = new Command();
-program.name("amba").description("amba — agent-native backend-as-a-service for mobile apps.").version("4.1.8");
+program.name("amba").description("amba — agent-native backend-as-a-service for mobile apps.").version("4.1.9");
 program.option("--token <pat>", "Use a Personal Access Token for headless / CI / agent use (overrides ~/.amba/credentials.json + AMBA_PAT env)");
 program.hook("preAction", (thisCommand) => {
 	setBearerOverride(resolveTokenSource({
@@ -9826,7 +9960,7 @@ function runAction(fn) {
 		process.exit(1);
 	});
 }
-program.command("init").description("Initialize Amba in the current project (mints a personal dev project by default)").option("--with-example", "Scaffold a sample app.tsx + README snippet into the current directory").option("--env <env>", "'development' (default) or 'production'").option("--sandbox", "Headless agentic mode: auto-signup, write .env.local + AMBA.md, auto-wire MCP client configs. No prompts.").option("--email <email>", "Override the auto-generated sandbox email (requires --sandbox)").option("--no-mcp-config", "Skip writing MCP client config files (rare; mostly for testing)").option("--no-skills", "Skip installing the project-local /amba-build Claude Code skill (default: install during --sandbox)").option("--json", "Emit a machine-readable JSON summary on stdout instead of human-readable lines").action(async (opts) => {
+program.command("init").description("Initialize Amba in the current project (mints a personal dev project by default)").option("--with-example", "Scaffold a sample app.tsx + README snippet into the current directory").option("--env <env>", "'development' (default) or 'production'").option("--sandbox", "Headless agentic mode: auto-signup, write .env.local + AMBA.md, auto-wire MCP client configs. No prompts.").option("--email <email>", "Override the auto-generated sandbox email (requires --sandbox)").option("--invite <code>", "Invite code for creating a new account while signups are invite-only (implies --sandbox; also read from AMBA_INVITE_CODE)").option("--no-mcp-config", "Skip writing MCP client config files (rare; mostly for testing)").option("--no-skills", "Skip installing the project-local /amba-build Claude Code skill (default: install during --sandbox)").option("--json", "Emit a machine-readable JSON summary on stdout instead of human-readable lines").action(async (opts) => {
 	let env;
 	if (opts.env === "development" || opts.env === "dev") env = "development";
 	else if (opts.env === "production" || opts.env === "prod") env = "production";
@@ -9834,27 +9968,29 @@ program.command("init").description("Initialize Amba in the current project (min
 		console.error(`Error: --env must be 'development' or 'production' (got '${opts.env}').`);
 		process.exit(1);
 	}
-	if (opts.email && !opts.sandbox) {
+	const sandbox = opts.sandbox === true || Boolean(opts.invite?.trim());
+	if (opts.email && !sandbox) {
 		console.error("Error: --email is only valid with --sandbox.");
 		process.exit(1);
 	}
-	if (opts.json && !opts.sandbox) {
+	if (opts.json && !sandbox) {
 		console.error("Error: --json is only valid with --sandbox.");
 		process.exit(1);
 	}
-	if (opts.mcpConfig === false && !opts.sandbox) {
+	if (opts.mcpConfig === false && !sandbox) {
 		console.error("Error: --no-mcp-config is only valid with --sandbox.");
 		process.exit(1);
 	}
-	if (opts.skills === false && !opts.sandbox) {
+	if (opts.skills === false && !sandbox) {
 		console.error("Error: --no-skills is only valid with --sandbox.");
 		process.exit(1);
 	}
 	await runAction(() => initCommand({
 		withExample: opts.withExample,
 		env,
-		sandbox: opts.sandbox,
+		sandbox,
 		sandboxEmail: opts.email,
+		inviteCode: opts.invite,
 		noMcpConfig: opts.mcpConfig === false,
 		noSkills: opts.skills === false,
 		json: opts.json

package/dist/sandbox.d.ts

@@ -43,6 +43,12 @@ export interface SandboxSignupRequest {
     email: string;
     password: string;
     name?: string;
+    /**
+     * Platform invite code (`--invite`). Falls back to `AMBA_INVITE_CODE`
+     * when absent. Sent as `invite_code`; the server ignores case, spaces
+     * and dashes.
+     */
+    inviteCode?: string;
 }
 /**
  * Shape returned by `POST /v1/auth/developer/signup`. Only the fields the
@@ -148,6 +154,34 @@ export declare function generateSandboxEmail(): string;
 export declare function generateSandboxPassword(): string;
 /** Request header carrying AMBA_SIGNUP_TOKEN on the signup call. */
 export declare const SIGNUP_TOKEN_HEADER = "X-Amba-Signup-Token";
+/** Environment variable read when `--invite` is absent. */
+export declare const INVITE_CODE_ENV = "AMBA_INVITE_CODE";
+/** The 403 codes signup answers with when the platform is gated. */
+export declare const SIGNUP_ACCESS_ERROR_CODES: readonly ["SIGNUPS_CLOSED", "INVITE_REQUIRED", "INVITE_INVALID"];
+export type SignupAccessErrorCode = (typeof SIGNUP_ACCESS_ERROR_CODES)[number];
+/**
+ * The flag value when set, else `AMBA_INVITE_CODE`, else undefined. Blank
+ * values count as absent so an empty env var never sends `invite_code: ""`.
+ */
+export declare function resolveInviteCode(flag?: string): string | undefined;
+/**
+ * Thrown when signup answers 403 SIGNUPS_CLOSED / INVITE_REQUIRED /
+ * INVITE_INVALID. `message` carries the server's sentence plus the next
+ * steps; the structured fields feed `amba init --json`.
+ */
+export declare class SignupAccessError extends Error {
+    readonly code: SignupAccessErrorCode;
+    readonly serverMessage: string;
+    readonly requestAccessUrl: string;
+    readonly requestAccessEndpoint: string;
+    readonly nextSteps: string[];
+    constructor(input: {
+        code: SignupAccessErrorCode;
+        serverMessage: string;
+        requestAccessUrl?: string;
+        requestAccessEndpoint?: string;
+    });
+}
 /**
  * POST the synthesized credentials at the public signup endpoint.
  *
@@ -159,7 +193,8 @@ export declare const SIGNUP_TOKEN_HEADER = "X-Amba-Signup-Token";
  * Returns the unwrapped, flattened shape consumed by the rest of the
  * sandbox flow. Throws with a human-readable message on any non-2xx so
  * the CLI's `runAction` wrapper can surface it without crashing on a
- * generic 'fetch failed'.
+ * generic 'fetch failed'. A gated platform (403 SIGNUPS_CLOSED /
+ * INVITE_REQUIRED / INVITE_INVALID) throws `SignupAccessError`.
  */
 export declare function performSandboxSignup(req: SandboxSignupRequest, options?: {
     apiUrl?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layers/amba",
-  "version": "4.1.8",
+  "version": "4.1.9",
   "description": "amba — agent-native backend-as-a-service. Functions, collections, storage, AI, email, queues, sites, and `amba ship` to take an Expo app live on the App Store + Google Play. `npx @layers/amba init` to start.",
   "type": "module",
   "bin": {
@@ -49,8 +49,8 @@
     "tsdown": "^0.12.5",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@layers/amba-shared": "4.0.6",
-    "@layers/amba-mcp": "4.0.11"
+    "@layers/amba-mcp": "4.0.12",
+    "@layers/amba-shared": "4.0.6"
   },
   "scripts": {
     "build": "tsdown && tsc --emitDeclarationOnly",

package/skill-bundle/SKILL.md

@@ -69,7 +69,9 @@ Check whether a project exists in this directory:
 
    The project status is `"provisioning"` immediately after signup; the per-tenant DB activates within ~5 seconds. Don't block — your next SDK or MCP 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).
 
-> **If you don't see Amba MCP tools available** (no `mcp__amba__*` in your tool list), Amba's MCP server isn't wired into your agent's tool surface this session. Run `npx -y @layers/amba init` via your bash tool — it provisions the account/project, writes `.env.local`, installs this skill, and wires the MCP entry into the user's agent config so the typed tools light up on the next agent launch.
+   **Signup refused with 403 `INVITE_REQUIRED` or `INVITE_INVALID`?** New accounts need an invite code right now. Ask the developer for theirs (it starts with `AMBA-` and arrives in their invite email) and call `amba_developer_signup` again with the same arguments plus `invite_code` (or rerun `npx -y @layers/amba init --invite <code>`; `AMBA_INVITE_CODE` works too). If they have no code, or the answer is `SIGNUPS_CLOSED`, offer to request access for them: `POST https://api.amba.dev/v1/auth/developer/waitlist` with `{ "email": "<their own email>", "note": "<optional>" }`, or send them to the `error.details.request_access_url` page. Tell them the invite code arrives by email, then stop. Retry only with a code the developer hands you; never retry in a loop, invent codes, or try other email addresses.
+
+> **If you don't see Amba MCP tools available** (no `mcp__amba__*` in your tool list), Amba's MCP server isn't wired into your agent's tool surface this session. Run `npx -y @layers/amba init` via your bash tool — it provisions the account/project, writes `.env.local`, installs this skill, and wires the MCP entry into the user's agent config so the typed tools light up on the next agent launch. While signups are invite-only, add `--invite <code>` with the developer's invite code; without one, init stops and prints where to request access.
 >
 > **If your harness ALSO blocks that bash command** (a locked-down agent: no installer, no network egress, no settings edits) — do NOT try to add the MCP server yourself, run the installer another way, or edit your own settings/permissions to authorize it. Refusing to self-modify or widen your own permissions is correct; don't circumvent it. Instead, ask the developer to run **one** command in **their own** terminal (not subject to your sandbox): `npx @layers/amba init`. It creates the account with no browser and writes `AMBA_PROJECT_ID` + `AMBA_CLIENT_KEY` to `.env.local`. Ask them to run it, say when it's done, then resume from Step 0 by reading `.env.local`. Pasting an `amb_ck_…` client key is the last-resort lite path — enough to wire `Amba.configure()` + verify events land, but a client key alone can't do admin provisioning (achievements, collections, segments), which needs the PAT/server key.
 >