@layers/amba-mcp 4.0.7 → 4.0.9

package/dist/auto/collection-tools.d.ts

@@ -51,6 +51,8 @@ export interface CollectionPolicy {
 export interface AppMcpClientAuth {
     apiKey: string;
     sessionToken?: string;
+    /** Verified by the client API on every request; never trusted locally. */
+    groupContext?: string;
     baseUrl: string;
 }
 export interface RegisterCollectionToolsOptions {

package/dist/auto/function-tools.d.ts

@@ -26,12 +26,14 @@
  * named `recipes`.
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import { type AppMcpClientAuth } from './collection-tools.js';
 /** One exposed function from the app-MCP manifest. */
 export interface AppMcpManifestFunction {
     name: string;
     description?: string | null;
     input_schema?: Record<string, unknown> | null;
+    annotations?: ToolAnnotations | null;
     public?: boolean;
     invoke_url: string;
 }

package/dist/index.js

@@ -641,9 +641,9 @@ function registerTool(server, apiClient, name, description, schema, handler, ali
 * `amba_developer_login`, `amba_developer_refresh`) — anything else
 * should go through `registerTool`.
 */
-function registerPublicTool(server, name, description, schema, handler, aliases = []) {
-	server.tool(name, description, schema, deriveToolAnnotations(name), handler);
-	for (const alias of aliases) server.tool(alias, description, schema, deriveToolAnnotations(alias), (async (args) => {
+function registerPublicTool(server, name, description, schema, handler, aliases = [], annotations) {
+	server.tool(name, description, schema, annotations ?? deriveToolAnnotations(name), handler);
+	for (const alias of aliases) server.tool(alias, description, schema, annotations ?? deriveToolAnnotations(alias), (async (args) => {
 		warnDeprecatedAlias(alias, name);
 		return handler(args);
 	}));
@@ -1489,6 +1489,13 @@ function jsonResult$1(payload) {
 		text: JSON.stringify(payload, null, 2)
 	}] };
 }
+/** Preserve an HTTP response wrapper while mapping failures to MCP isError. */
+function httpResult(result) {
+	return {
+		...jsonResult$1(result),
+		...result.status >= 400 ? { isError: true } : {}
+	};
+}
 /**
 * Flatten an upstream HTTP response into the agent-facing tool payload.
 * Body fields are spread FIRST so a future top-level `status` key in
@@ -1496,10 +1503,13 @@ function jsonResult$1(payload) {
 * `parsed.status` to distinguish 2xx from 4xx/5xx.
 */
 function passthroughResult(result) {
-	return jsonResult$1({
-		...result.body ?? {},
-		status: result.status
-	});
+	return {
+		...jsonResult$1({
+			...result.body !== null && typeof result.body === "object" ? result.body : {},
+			status: result.status
+		}),
+		...result.status >= 400 ? { isError: true } : {}
+	};
 }
 //#endregion
 //#region src/tools/users.ts
@@ -5755,14 +5765,17 @@ function registerTools$18(server, apiClient) {
 		"Function name must match /^[a-z][a-z0-9_-]*$/ and be ≤58 chars. Bundle size cap: 10 MiB (enforced client-side too — oversize uploads are rejected before the round-trip).",
 		"Optional `rate_limit` declares a per-function rate-limit config (validated server-side). Pass null/omit for no rate limit.",
 		"Optional `public` (default false) deploys the function WITHOUT the X-Api-Key gate, so third-party webhook senders (RevenueCat, Stripe, GitHub, Slack) that cannot attach a custom header can reach it. SECURITY: when public, YOU must verify the webhook signature (HMAC) inside the function body — the runtime no longer requires a caller credential. `public: true` only skips the key requirement; rate-limiting and the per-request signed identity context still apply. Leave it false for functions only your own app calls.",
+		"Optional `forward_authorization` (default false) forwards a verified client Bearer to customer code. X-Api-Key and platform internal-trigger credentials are always stripped. Enable only when the function must validate or proxy the end-user session.",
 		"Returns the function deployment row + the public URL (`fn_url`: `https://{project_slug}.fn.amba.host/{name}`)."
 	].join(" "), {
 		project_id: z.string().describe("The Amba project ID."),
 		name: z.string().describe("Function name. Lowercase, /^[a-z][a-z0-9_-]*$/, ≤58 chars."),
 		code: z.string().describe("Bundled JavaScript module source (one entry file)."),
 		rate_limit: z.unknown().optional().describe("Optional rate-limit config object. Shape: see @layers/amba-shared:RateLimitConfig."),
-		public: z.boolean().optional().describe("Deploy the function as PUBLIC (no X-Api-Key required) so external webhook senders can reach it. Default false. When true, you MUST verify the webhook HMAC signature inside the function body — public skips the credential gate only; rate-limiting and signed identity context still apply.")
-	}, async ({ project_id, name, code, rate_limit, public: isPublic }, { pat }) => {
+		public: z.boolean().optional().describe("Deploy the function as PUBLIC (no X-Api-Key required) so external webhook senders can reach it. Default false. When true, you MUST verify the webhook HMAC signature inside the function body — public skips the credential gate only; rate-limiting and signed identity context still apply."),
+		forward_authorization: z.boolean().optional().describe("Forward a verified client Authorization Bearer to customer code. Default false. X-Api-Key and platform internal credentials are never forwarded."),
+		mcp: z.unknown().optional().describe("Optional app-MCP tool config: {description?, input_schema?, annotations?}. Safety annotations support readOnlyHint, destructiveHint, idempotentHint, and openWorldHint booleans.")
+	}, async ({ project_id, name, code, rate_limit, public: isPublic, forward_authorization: forwardAuthorization, mcp }, { pat }) => {
 		const byteLen = Buffer.byteLength(code, "utf8");
 		if (byteLen > MAX_BUNDLE_BYTES) throw new Error(`Bundle size ${byteLen} bytes exceeds ${MAX_BUNDLE_BYTES}-byte cap (10 MiB).`);
 		const form = new FormData();
@@ -5770,6 +5783,8 @@ function registerTools$18(server, apiClient) {
 		const metadata = { name };
 		if (rate_limit !== void 0 && rate_limit !== null) metadata.rate_limit = rate_limit;
 		if (isPublic === true) metadata.public = true;
+		if (forwardAuthorization === true) metadata.forward_authorization = true;
+		if (mcp !== void 0) metadata.mcp = mcp;
 		form.append("metadata", new Blob([JSON.stringify(metadata)], { type: "application/json" }), "metadata.json");
 		return jsonResult(await callWithPat(apiClient, pat, "POST", `/projects/${encodeURIComponent(project_id)}/functions/deploy`, { formData: form }));
 	}, ["amba_deploy_function"]);
@@ -5826,6 +5841,7 @@ function registerTools$18(server, apiClient) {
 		"Attach one exact custom hostname to one deployed function. The complete incoming path and query string are preserved when the hostname routes to the function.",
 		"MVP constraints: exact lowercase hostnames only; no wildcards or path rewrites. Attaching a subdomain does NOT create a `www` hostname automatically.",
 		"The response contains provider-neutral certificate/ownership status plus DNS validation instructions. Publish the returned CNAME and validation records, then call `amba_function_domains_refresh` until `live=true` (both statuses active and routing reconciliation successful).",
+		"For every hostname, publish the real provider-stored CNAME and heed the unconditional `dns_note`. ALIAS, ANAME, and copied A/AAAA addresses do not preserve the relationship required for standard activation; use www or another subdomain if authoritative DNS cannot store an apex CNAME.",
 		"MVP limits use the effective project tier (free 1, pro 5, scale 20, enterprise or comped 50), with five attach attempts per project per hour. An unverified claim becomes eligible for exact-host reclaim after 24 hours; Worker route/KV allocation waits for active ownership.",
 		"Podcast/feed clients cannot supply an Amba API key. Their function must be deployed with `public: true`; validate any application-specific private token in the handler."
 	].join(" "), {
@@ -5858,6 +5874,9 @@ function registerTools$18(server, apiClient) {
 			deleted: true
 		});
 	});
+	registerTool(server, apiClient, "amba_functions_list_schedules", "List function schedules with their cron expression, timezone, pause state, next fire time, and most recent fire time. Rows degrade with enriched=false if one provider describe call fails.", { project_id: z.string().describe("The Amba project ID.") }, async ({ project_id }, { pat }) => {
+		return jsonResult(await callWithPat(apiClient, pat, "GET", `/projects/${encodeURIComponent(project_id)}/functions/schedules`));
+	});
 	registerTool(server, apiClient, "amba_functions_schedule", [
 		"Register a cron Schedule for a function. The schedule is keyed deterministically per (project, function) — re-calling with a different cron/timezone replaces the prior schedule rather than creating a duplicate.",
 		"Cron must be a standard 5- or 6-field whitespace-separated expression. `timezone` defaults to \"UTC\" if omitted. Timezones are IANA strings (e.g. \"America/Los_Angeles\").",
@@ -5972,7 +5991,8 @@ function registerTools$17(server, apiClient) {
 	registerTool(server, apiClient, "amba_sites_add_domain", [
 		"Attach a custom hostname to a site. The API registers the hostname with the upstream CDN provider server-side and persists the binding row with `cert_status=\"pending_validation\"`.",
 		"Response includes the DNS target (`<slug>.app.amba.host`) to set as a CNAME, plus any SSL validation records (DCV TXT/HTTP tokens) the customer must publish.",
-		"Poll `amba_sites_list_domains` (or the per-row `cert_status`) to watch the cert progress through pending_validation → pending_issuance → pending_deployment → active."
+		"For every hostname, publish the real provider-stored CNAME and heed the unconditional `dns_note`; do not substitute ALIAS, ANAME, or copied A/AAAA addresses. Use www or another subdomain if authoritative DNS cannot store an apex CNAME.",
+		"Poll `amba_sites_list_domains` until server-derived `live=true`. Certificate, hostname ownership, Worker route, host KV, and managed DNS (when applicable) are independent; never report success from provider status alone."
 	].join(" "), {
 		project_id: z.string().describe("The Amba project ID."),
 		name: z.string().describe("Site name to attach the domain to."),
@@ -5981,7 +6001,7 @@ function registerTools$17(server, apiClient) {
 		const normalisedHostname = hostname.toLowerCase();
 		return jsonResult(await callWithPat(apiClient, pat, "POST", `/projects/${encodeURIComponent(project_id)}/sites/${encodeURIComponent(name)}/domains`, { body: { hostname: normalisedHostname } }));
 	}, ["amba_add_site_domain"]);
-	registerTool(server, apiClient, "amba_sites_list_domains", "List custom hostnames attached to a site, with their cert lifecycle status.", {
+	registerTool(server, apiClient, "amba_sites_list_domains", "List custom hostnames attached to a site and re-poll readiness across certificate, ownership, Worker route, host KV, and managed DNS. Treat a hostname as ready only when server-derived `live=true`.", {
 		project_id: z.string().describe("The Amba project ID."),
 		name: z.string().describe("Site name.")
 	}, async ({ project_id, name }, { pat }) => {
@@ -6036,10 +6056,10 @@ function registerTools$16(server, apiClient) {
 		return jsonResult(await callWithPat(apiClient, pat, "POST", `/projects/${encodeURIComponent(project_id)}/domains/check`, { body: { domains: normalised } }));
 	});
 	registerTool(server, apiClient, "amba_domains_purchase", [
-		"Buy a domain through Amba and connect it to one of the project's sites as a live custom domain — the customer never touches DNS.",
+		"Buy a domain through Amba and create a custom-domain binding to one of the project's sites.",
 		"TWO-STEP / MONEY SAFETY: the first call (without `confirm`) returns a QUOTE with the price and `confirmation_required: true` and charges nothing. Surface the price to the user and get their go-ahead, then call again with `confirm: true` and `accept_price_usd` set to the quoted price to execute the purchase.",
 		"A real domain registration spends money and is permanent. If purchasing is not enabled on the deployment, the call returns the quote with `gated: true` and still charges nothing.",
-		"On success: the domain is registered, DNS is auto-configured, and the site begins serving on the new domain (the TLS certificate issues automatically)."
+		"Registration and binding creation do not prove reachability. Report the public URL as live only when server-derived `hostname_live=true` (certificate, ownership, Worker route, host KV, and managed DNS are all reconciled); otherwise describe it as pending activation."
 	].join(" "), {
 		project_id: z.string().describe("The Amba project ID."),
 		domain: z.string().describe("The domain to buy, e.g. \"unbury.com\". Must be available (check first)."),
@@ -6061,7 +6081,7 @@ function registerTools$16(server, apiClient) {
 		if (years !== void 0) body.years = years;
 		return jsonResult(await callWithPat(apiClient, pat, "POST", `/projects/${encodeURIComponent(project_id)}/domains/purchase`, { body }));
 	});
-	registerTool(server, apiClient, "amba_domains_list", "List domains this project has purchased through Amba, with registration status and the site each is connected to.", {
+	registerTool(server, apiClient, "amba_domains_list", "List domains this project has purchased through Amba, with registration status, connected site, and authoritative hostname readiness. This call re-polls pending binding lifecycle; treat only `hostname_live=true` as reachable. Purchase/payment completion is reported separately by registration `status`.", {
 		project_id: z.string().describe("The Amba project ID."),
 		limit: z.number().int().min(1).max(200).optional().describe("Page size (1-200, default 50)."),
 		offset: z.number().int().min(0).optional().describe("Skip rows (default 0).")
@@ -9322,7 +9342,11 @@ function must be deployed with \`public: true\` and validate any private token
 inside the handler. Effective-tier caps are free 1, pro 5, scale 20, and
 enterprise/comped 50; attach is limited to five attempts per project per hour.
 Unverified claims become eligible for reclaim after 24 hours, and routing
-resources are allocated only after ownership is active.
+resources are allocated only after ownership is active. Every hostname response
+includes an unconditional \`dns_note\`: publish a real provider-stored CNAME;
+ALIAS, ANAME, and copied A/AAAA addresses are not
+substitutes. Treat a hostname as ready only when \`live=true\`, never from TLS or
+\`cert_status=active\` alone.
 
 ### AI prompts
 
@@ -10142,6 +10166,7 @@ const TOOL_CATEGORY = {
 	amba_functions_get_logs: "infrastructure",
 	amba_get_function_logs: "infrastructure",
 	amba_functions_schedule: "infrastructure",
+	amba_functions_list_schedules: "infrastructure",
 	amba_schedule_function: "infrastructure",
 	amba_functions_pause_schedule: "infrastructure",
 	amba_pause_function_schedule: "infrastructure",
@@ -10700,6 +10725,7 @@ async function adminFetch(apiClient, bearer, call) {
 async function clientFetch(clientAuth, call) {
 	const headers = { "X-Api-Key": clientAuth.apiKey };
 	if (clientAuth.sessionToken) headers["Authorization"] = `Bearer ${clientAuth.sessionToken}`;
+	if (clientAuth.groupContext) headers["X-Group-Context"] = clientAuth.groupContext;
 	return proxyFetch(clientAuth.baseUrl, headers, call);
 }
 /**
@@ -11061,23 +11087,23 @@ function registerFunctionToolsFor(server, options) {
 	});
 	if (declaredShape) {
 		registerPublicTool(server, toolName, description, declaredShape, async (args) => {
-			return jsonResult$1(await invokeFunction({
+			return httpResult(await invokeFunction({
 				invokeUrl: fn.invoke_url,
 				clientAuth,
 				body: args
 			}));
-		});
+		}, [], fn.annotations ?? void 0);
 		return;
 	}
 	registerPublicTool(server, toolName, description, GENERIC_FUNCTION_SHAPE, async (args) => {
 		const { body, query } = args;
-		return jsonResult$1(await invokeFunction({
+		return httpResult(await invokeFunction({
 			invokeUrl: fn.invoke_url,
 			clientAuth,
 			body,
 			...query ? { query } : {}
 		}));
-	});
+	}, [], fn.annotations ?? void 0);
 }
 //#endregion
 //#region src/auto/index.ts
@@ -11216,7 +11242,8 @@ async function registerAutoMcpTools(server, apiClient, options) {
 		fn,
 		clientAuth: {
 			apiKey: clientAuth.apiKey,
-			...clientAuth.sessionToken ? { sessionToken: clientAuth.sessionToken } : {}
+			...clientAuth.sessionToken ? { sessionToken: clientAuth.sessionToken } : {},
+			...clientAuth.groupContext ? { groupContext: clientAuth.groupContext } : {}
 		}
 	});
 	return {

package/dist/lib/tool-result.d.ts

@@ -34,6 +34,17 @@ export declare function jsonResult(payload: unknown): {
         text: string;
     }[];
 };
+/** Preserve an HTTP response wrapper while mapping failures to MCP isError. */
+export declare function httpResult(result: {
+    status: number;
+    body: unknown;
+}): {
+    isError?: boolean | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
 /**
  * Flatten an upstream HTTP response into the agent-facing tool payload.
  * Body fields are spread FIRST so a future top-level `status` key in
@@ -44,6 +55,7 @@ export declare function passthroughResult(result: {
     status: number;
     body: unknown;
 }): {
+    isError?: boolean | undefined;
     content: {
         type: "text";
         text: string;

package/dist/lib/with-pat.d.ts

@@ -41,6 +41,7 @@
  * the same call shape without the pat machinery.
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import { z, type ZodRawShape } from 'zod';
 import type { ApiClient } from '../api-client.js';
 /** Wire-shape returned by an MCP tool handler. */
@@ -49,6 +50,8 @@ export interface ToolResult {
         type: 'text';
         text: string;
     }>;
+    /** MCP-native failure signal. Tool transports still return HTTP 200. */
+    isError?: boolean;
 }
 /** Context passed to handlers registered via `registerTool`. */
 export interface WithPatHandlerContext {
@@ -122,4 +125,6 @@ export declare function registerPublicTool<S extends ZodRawShape>(server: McpSer
  * warning per alias per process. No active auth-tool rename uses this
  * yet, but the parameter exists so future renames stay consistent.
  */
-aliases?: readonly string[]): void;
+aliases?: readonly string[], 
+/** Explicit app-declared safety hints; absent keeps conservative derivation. */
+annotations?: ToolAnnotations): void;

package/dist/resources/amba-setup-infrastructure.d.ts

@@ -14,6 +14,6 @@
  * Postgres tables; the hosting supplier (Neon) and the rest of the infra
  * stack (Temporal / R2) stay scrubbed before exposing on the wire.
  */
-export declare const AMBA_SETUP_INFRASTRUCTURE_MD = "# Infrastructure\n\nThe plumbing that sits behind every other surface: relational Postgres tables (Collections \u2014 schema-first, per-tenant), serverless functions (run server-side code without standing up a backend), analytics (events + sessions), AI prompts (managed LLM templates, callable from the SDK with per-tenant keys), secrets, runtime configs, feature flags, third-party integrations (RevenueCat / Superwall / Stripe / push credentials), media (file storage + CDN), and sites (static asset hosting at `*.app.amba.host`).\n\nIf gamification, economy, and social are the playable surface, **infrastructure is what you build a custom product on top of**. Anything that doesn't fit the canned surfaces lands here.\n\n## MCP tools\n\n### Collections (relational Postgres tables)\n\nA collection is a relational Postgres table inside the project's isolated tenant database \u2014 typed columns, foreign keys, transactions, unique indexes, and vector search. You describe the columns, the server creates the table and any indexes. Rows are scoped to the signed-in `app_user` automatically (server-enforced auto row-level isolation) for SDK clients \u2014 admin tools bypass this.\n\nAdmin tools authenticate the developer/agent (pass `pat` or send it as the inbound Bearer) and take `project_id`. Client tools authenticate an end-user and take `api_key` (+ `session_token`) \u2014 NOT `project_id` and NOT a `pat`. Every row tool names the collection with `name`, never `collection`.\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_collections_create` | Create a typed collection. Pass `shared: true` for developer-seeded GLOBAL content (question banks, lookup tables) so `user_id` is nullable. | `{ project_id, name: \"todos\", columns: [{ name: \"title\", type: \"text\", nullable: false }, { name: \"done\", type: \"boolean\", nullable: false }, { name: \"due_at\", type: \"timestamptz\", nullable: true }], shared: false }` |\n| `amba_collections_list` | List collections in this project. | `{ project_id }` |\n| `amba_collections_get` | Read one collection's schema. | `{ project_id, name: \"todos\" }` |\n| `amba_collections_alter` | Exactly ONE of: `add_column`, `add_index`, `drop_column`, or `relax_user_id` per call. `relax_user_id: true` converts an existing collection to shared (drops the `user_id` NOT NULL). | `{ project_id, name: \"todos\", add_column: { name: \"priority\", type: \"integer\", nullable: true } }` |\n| `amba_collections_delete` | Drop the table (destructive). `confirm` must equal the collection name. | `{ project_id, name: \"todos\", confirm: \"todos\" }` |\n| `amba_admin_insert_row` | Insert one row as the developer (bypasses user-scope; `user_id` honored if present). | `{ project_id, name: \"todos\", row: { title: \"Sample\", done: false } }` |\n| `amba_admin_insert_rows` | Bulk-insert up to 500 rows in one atomic statement \u2014 the canonical seeding/migration path. `on_conflict`: `\"error\"` (default) or `\"skip\"`. | `{ project_id, name: \"questions\", rows: [{ q: \"...\" }, { q: \"...\" }], on_conflict: \"skip\" }` |\n| `amba_admin_list_rows` | Read rows as the developer. | `{ project_id, name: \"todos\", limit: 100 }` |\n| `amba_client_insert_row` | Insert as an end-user. Requires `api_key` (+ `session_token`). | `{ api_key, session_token, name: \"todos\", row: {...} }` |\n| `amba_client_list_rows` | Read as an end-user (auto user-scoped). | `{ api_key, session_token, name: \"todos\" }` |\n| `amba_client_get_row` | Get one row by id (end-user). | `{ api_key, session_token, name: \"todos\", id }` |\n| `amba_client_update_row` | Update one row by id (end-user). Fields go in `set`. Omit `id` + pass `where` for a bulk update. | `{ api_key, session_token, name: \"todos\", id, set: {...} }` |\n| `amba_client_delete_row` | Soft-delete one row by id (end-user). | `{ api_key, session_token, name: \"todos\", id }` |\n| `amba_client_count_rows` | Count rows matching an optional `where`. | `{ api_key, session_token, name: \"todos\", where: {...} }` |\n| `amba_client_find_rows` | Filter / sort / paginate rows (SDK-shaped `filter`). | `{ api_key, session_token, name: \"todos\", filter: {...}, order: [\"created_at desc\"], limit: 50 }` |\n| `amba_client_find_nearest_rows` | Vector-similarity search (rows with a `vector(<dim>)` column). | `{ api_key, session_token, name: \"todos\", column: \"embedding\", to_vector: [...], k: 10 }` |\n\nColumn types: `text`, `integer`, `bigint`, `numeric`, `boolean`, `timestamptz`, `date`, `jsonb`, `uuid`, `vector` (pass a separate `dimension` field, e.g. `{ name: \"embedding\", type: \"vector\", dimension: 1536 }` for OpenAI embeddings), plus array forms `text[]`, `integer[]`, `bigint[]`, `numeric[]`, `boolean[]`, `uuid[]`. Columns are NOT NULL unless `nullable: true`; column defaults are not supported (set values at insert time). Use `integer` (not `int`), `numeric` (not `float`/`real`/`double`), and `jsonb` (not `json`) \u2014 the validator rejects the aliases.\n\n### Functions (serverless code)\n\nRun user code in a sandbox triggered by HTTP, cron, or webhook. The function gets the tenant connection automatically via injected env.\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_functions_deploy` | Deploy a function from source. | `{ project_id, name: \"send_welcome_email\", runtime: \"node22\", source: \"export default async (req) => { ... }\", trigger: { type: \"http\" } }` |\n| `amba_functions_list` | List functions. | `{ project_id }` |\n| `amba_functions_get` | Read function metadata. | `{ project_id, function_id }` |\n| `amba_functions_get_logs` | Recent invocation logs. | `{ project_id, function_id, limit: 100 }` |\n| `amba_functions_delete` | Delete a function. | `{ project_id, function_id }` |\n| `amba_functions_schedule` | Attach a cron schedule. | `{ project_id, function_id, cron: \"0 9 * * *\", timezone: \"America/Los_Angeles\" }` |\n| `amba_functions_pause_schedule` | Pause a scheduled trigger without deleting it. | `{ project_id, function_id }` |\n| `amba_functions_resume_schedule` | Resume. | `{ project_id, function_id }` |\n| `amba_functions_trigger_schedule` | Fire a scheduled function ad-hoc (testing). | `{ project_id, function_id }` |\n| `amba_function_domains_attach` | Attach one exact hostname to one function; returns DNS validation instructions. | `{ project_id, name: \"feed\", hostname: \"feeds.example.com\" }` |\n| `amba_function_domains_list` | List provider-neutral hostname, ownership, and certificate status. | `{ project_id, name: \"feed\" }` |\n| `amba_function_domains_refresh` | Re-poll DNS ownership and certificate state. | `{ project_id, name: \"feed\", hostname: \"feeds.example.com\" }` |\n| `amba_function_domains_remove` | Detach an exact function hostname. | `{ project_id, name: \"feed\", hostname: \"feeds.example.com\" }` |\n\nFunction-domain routing preserves the complete incoming path and query string.\nIt is exact-host only (no wildcard/path rewrite and no automatic `www` for a\nsubdomain). Podcast/feed clients cannot attach an Amba API key, so their\nfunction must be deployed with `public: true` and validate any private token\ninside the handler. Effective-tier caps are free 1, pro 5, scale 20, and\nenterprise/comped 50; attach is limited to five attempts per project per hour.\nUnverified claims become eligible for reclaim after 24 hours, and routing\nresources are allocated only after ownership is active.\n\n### AI prompts\n\nManaged LLM templates: a stored prompt with provider + model + system message, invoked by name from the SDK. The actual LLM call is rewritten server-side per-tenant \u2014 the customer's provider API key (Anthropic / OpenAI / Mistral / Gemini) stays server-side, never on the device.\n\n**Two steps, in order:** first register the provider key with `amba_ai_providers_set`, then create prompts against it. A prompt registered before its provider has a key still saves, but invocations fail with `provider_not_configured` (424) until the key is set.\n\n> The provider key is **not** a function secret. `amba_secrets_set` writes function-scoped Worker secrets, which the AI gateway never reads. Provider keys live in a separate gateway-owned store and are set **only** via `amba_ai_providers_set`.\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_ai_providers_set` | Register / rotate the upstream provider API key. **Do this first.** | `{ project_id, provider: \"anthropic\", api_key: \"sk-ant-...\" }` |\n| `amba_ai_providers_list` | List registered providers (`configured` = key set). | `{ project_id }` |\n| `amba_ai_providers_delete` | Revoke a provider key (fails if prompts still reference it). | `{ project_id, provider: \"anthropic\" }` |\n| `amba_ai_prompts_create` | Create a prompt template. `client_invokable: true` lets the device SDK invoke it directly. | `{ project_id, name: \"summarize\", provider: \"anthropic\", model: \"claude-opus-4-5\", system_prompt: \"Summarize the user's text in 2 sentences.\", client_invokable: true }` |\n| `amba_ai_prompts_list` | List prompts. | `{ project_id }` |\n| `amba_ai_prompts_get` | Read one prompt. | `{ project_id, name }` |\n| `amba_ai_prompts_update` | Edit a prompt (replaces all fields; bumps version). | `{ project_id, name, provider, model, system_prompt: \"...\" }` |\n| `amba_ai_prompts_invoke` | Invoke by name server-side (admin testing; works with `client_invokable: false`). Uses the named gateway path, so the prompt budget, rate limit, token cap, and spend attribution are enforced. | `{ project_id, name, messages: [{ role: \"user\", content: \"...\" }] }` |\n| `amba_ai_prompts_delete` | Delete. | `{ project_id, name }` |\n\n### Analytics + events + sessions\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_analytics_get` | Top-level metrics dashboard (MAU, DAU, retention). | `{ project_id, period: \"7d\" }` |\n| `amba_events_list` | Browse raw events. | `{ project_id, limit: 100, since: \"2026-05-19T00:00:00Z\" }` |\n| `amba_events_count` | Count events matching a filter. | `{ project_id, event: \"workout_completed\", since: \"...\" }` |\n| `amba_sessions_list` | List user sessions. | `{ project_id, limit: 50 }` |\n| `amba_sessions_analytics` | Session-level metrics. | `{ project_id, period: \"7d\" }` |\n| `amba_users_list_events` | Per-user event history. | `{ project_id, user_id }` |\n| `amba_users_export` | Export the full user list. | `{ project_id, format: \"csv\" }` |\n\n### Secrets + configs + integrations\n\nSecrets here become environment bindings on deployed functions. Omit `function`\nfor a project-wide secret or pass it to scope the value to one function. Setting\nor rotating a secret queues an asynchronous update for already-deployed\nfunctions; later deployments reconcile the binding too. They are NOT where AI\nprovider keys go (use `amba_ai_providers_set` for those \u2014 see AI prompts above).\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_secrets_set` | Set or rotate a function secret; omit `function` for project-wide scope or pass it for one function. Already-deployed functions receive it asynchronously. | `{ project_id, name: \"STRIPE_WEBHOOK_SECRET\", value: \"whsec_...\" }` |\n| `amba_secrets_get` | Read a secret (returns `\"<redacted>\"` unless explicitly requested). | `{ project_id, name }` |\n| `amba_secrets_list` | List secret names. | `{ project_id }` |\n| `amba_secrets_delete` | Delete. | `{ project_id, name }` |\n| `amba_configs_create` | Create a runtime config value (read from SDK as `Amba.config.fetch()`). | `{ project_id, key: \"primary_color\", value: \"#ff0066\", segment_id: null }` |\n| `amba_configs_list` | List configs. | `{ project_id }` |\n| `amba_configs_update` | Edit. | `{ project_id, config_id, value: \"...\" }` |\n| `amba_configs_delete` | Delete. | `{ project_id, config_id }` |\n| `amba_integrations_list` | List third-party integrations. | `{ project_id }` |\n| `amba_integrations_configure` | Configure a provider. | `{ project_id, provider: \"revenuecat\", config: { webhook_secret: \"...\", default_offering: \"...\" } }` |\n| `amba_integrations_set` | Set/replace integration config wholesale. | `{ project_id, provider, config }` |\n| `amba_integrations_patch` | Patch one field. | `{ project_id, provider, patch: { webhook_secret: \"...\" } }` |\n| `amba_integrations_test` | Send a test event to a configured provider. | `{ project_id, provider }` |\n\n### Media (file storage + CDN)\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_media_upload` | Upload a file (returns a tenant-scoped URL). | `{ project_id, name: \"logo.png\", content_type: \"image/png\", data: \"<base64>\" }` |\n| `amba_media_list` | List files. | `{ project_id, folder: \"/\", limit: 100 }` |\n| `amba_media_delete` | Delete a file. | `{ project_id, file_id }` |\n| `amba_media_create_folder` | Create a logical folder. | `{ project_id, path: \"/uploads/avatars\" }` |\n| `amba_media_list_folders` | List folders. | `{ project_id }` |\n| `amba_media_delete_folder` | Delete a folder (must be empty). | `{ project_id, path }` |\n\n### Sites (static asset hosting)\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_sites_deploy` | Deploy a static site bundle (zip / tar). | `{ project_id, name: \"marketing\", bundle: \"<base64>\", index: \"index.html\" }` |\n| `amba_sites_list` | List sites. | `{ project_id }` |\n| `amba_sites_get` | Read a site. | `{ project_id, site_id }` |\n| `amba_sites_add_domain` | Attach a custom domain. | `{ project_id, site_id, domain: \"marketing.example.com\" }` |\n| `amba_sites_list_domains` | List domains on a site. | `{ project_id, site_id }` |\n| `amba_sites_remove_domain` | Detach a domain. | `{ project_id, site_id, domain }` |\n| `amba_sites_delete` | Delete a site. | `{ project_id, site_id }` |\n\n### Purchased domains + email forwarding\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_domains_search` | Search available domains (free). | `{ project_id, query: \"myapp\" }` |\n| `amba_domains_check` | Check authoritative price + availability. | `{ project_id, domains: [\"myapp.com\"] }` |\n| `amba_domains_purchase` | Quote, then confirm, a domain purchase. | `{ project_id, domain: \"myapp.com\", site: \"marketing\" }` |\n| `amba_domains_list` | List purchased domains. | `{ project_id }` |\n| `amba_domains_email_enable` | Enable inbound routing when no MX conflict exists. | `{ project_id, domain: \"myapp.com\" }` |\n| `amba_domains_email_destinations_add` | Add a destination mailbox; returns action-required until verified. | `{ project_id, domain: \"myapp.com\", email: \"owner@example.net\" }` |\n| `amba_domains_email_destinations_get` | Poll destination verification. | `{ project_id, domain: \"myapp.com\", destination_id }` |\n| `amba_domains_email_forwards_set` | Create/update a literal forward. | `{ project_id, domain: \"myapp.com\", source: \"support\", destination: \"owner@example.net\" }` |\n| `amba_domains_email_forwards_list` | List literal forwards. | `{ project_id, domain: \"myapp.com\" }` |\n| `amba_domains_email_forwards_delete` | Delete a literal forward. | `{ project_id, domain: \"myapp.com\", forward_id }` |\n| `amba_domains_email_catch_all_set` | Enable/update/disable catch-all. | `{ project_id, domain: \"myapp.com\", enabled: true, destination: \"owner@example.net\" }` |\n| `amba_domains_email_catch_all_get` | Read catch-all state. | `{ project_id, domain: \"myapp.com\" }` |\n\n## SDK init per stack\n\n`Amba.configure(...)` runs first. The infrastructure surfaces \u2014 collections, AI, config, flags, events \u2014 are SDK-side reads; the snippets below show what the client calls look like.\n\n### Expo / React Native\n\n```tsx\nimport { Amba } from '@layers/amba-expo';\n\n// Collections \u2014 typed table, user-scoped reads + writes\ntype Todo = { id: string; title: string; done: boolean; created_at: string };\n\nconst { data: todos } = await Amba.collections.find<Todo>('todos', {\n  filter: Amba.collections.where.eq('done', false),\n  order: [{ column: 'created_at', direction: 'desc' }],\n  limit: 50,\n});\n\nconst newTodo = await Amba.collections.insert('todos', { title: 'Ship the app', done: false });\nawait Amba.collections.update('todos', newTodo.id, { done: true });\nawait Amba.collections.delete('todos', newTodo.id);\n\n// AI \u2014 call a managed prompt (prompt_slug names the registered prompt)\nconst response = await Amba.ai.anthropic.messages.create({\n  prompt_slug: 'summarize',\n  variables: { text: 'A long article about backend services \u2026' },\n});\n\n// Track an analytics event\nawait Amba.events.track('button_clicked', { button: 'cta' });\n\n// Read runtime config\nconst config = await Amba.config.fetch();\n\n// Read a feature flag\nconst showBeta = await Amba.flags.get('beta_feature');\n\n// Diagnostics \u2014 wire-verify\nconst ping = await Amba.diagnostics.ping();\nif (!ping.ok) console.error('Amba misconfigured:', ping);\n```\n\n### Web\n\n```ts\nimport { Amba } from '@layers/amba-web';\n\nconst { data: todos } = await Amba.collections.find('todos', {\n  filter: Amba.collections.where.eq('done', false),\n  limit: 50,\n});\nawait Amba.collections.insert('todos', { title: 'Ship', done: false });\nawait Amba.events.track('page_view', { path: location.pathname });\n```\n\nWith `@layers/amba-react`:\n\n```tsx\nimport { useCollection, useFlag } from '@layers/amba-react';\n\nfunction TodoList() {\n  const { data: todos, loading, refetch } = useCollection<{ id: string; title: string }>('todos');\n  const showArchive = useFlag('archive_todos');\n  if (loading) return <Spinner />;\n  return (\n    <ul>\n      {todos?.map(t => <li key={t.id}>{t.title}</li>)}\n      {showArchive && <ArchiveButton onArchive={refetch} />}\n    </ul>\n  );\n}\n```\n\n### iOS (Swift)\n\n```swift\nimport Amba\n\nstruct Todo: Codable {\n    let id: String\n    let title: String\n    let done: Bool\n}\n\nlet response = try await Amba.collections.find(\"todos\", as: Todo.self)\n_ = try await Amba.collections.insert(\"todos\", row: [\"title\": \"Ship\", \"done\": false])\n\nlet config = try await Amba.config.fetch()\nlet showBeta = try await Amba.flags.get(name: \"beta_feature\")\ntry await Amba.events.track(\"app_opened\", properties: [\"source\": \"deep_link\"])\n\nlet reply = try await Amba.ai.anthropic.messages.create(\n    request: AiMessageRequest(promptSlug: \"summarize\", variables: [\"text\": \"A long article...\"])\n)\n```\n\n### Android (Kotlin)\n\n```kotlin\ndata class Todo(val id: String, val title: String, val done: Boolean)\n\nval todos = Amba.collections.find<Todo>(\"todos\")\nAmba.collections.insert(\"todos\", mapOf(\"title\" to \"Ship\", \"done\" to false))\n\nval config = Amba.config.fetch()\nval showBeta = Amba.flags.get(\"beta_feature\")\nAmba.events.track(\"app_opened\", mapOf(\"source\" to \"deep_link\"))\n```\n\n### Flutter\n\n```dart\nimport 'package:amba/amba.dart';\n\nfinal response = await Amba.collections.find('todos', limit: 50);\nawait Amba.collections.insert('todos', {'title': 'Ship', 'done': false});\nfinal config = await Amba.config.fetch();\nfinal showBeta = await Amba.flags.get('beta_feature');\nawait Amba.events.track('app_opened', {'source': 'deep_link'});\n```\n\n## Common follow-ups\n\nBatch.\n\n1. **Custom data tables (collections):** any domain-specific tables to create?\n   - Yes \u2014 I'll list them. (For each: name + columns + types.)\n   - No, just use the canned Amba surfaces (auth, push, gamification, etc.)\n   - Auto-create from the existing code's models \u2014 read `lib/models/`, `src/types/`, `Models/`, infer column lists, confirm with me.\n\n2. **Custom backend logic (functions):** any server-side code to deploy?\n   - Yes \u2014 describe what it should do. (Then offer to scaffold a function template and deploy.)\n   - No\n\n3. **AI features:** want managed LLM prompts?\n   - Yes \u2014 what's the use case? (summarize, translate, classify, generate, custom)\n   - No\n\n4. **Analytics:** which tracker do you want?\n   - Only Amba's built-in events (recommended \u2014 already wired)\n   - Amba + your own analytics pipeline (subscribe a webhook to project events via `amba_webhooks_create` and forward server-side)\n   - None (rarely useful \u2014 events drive XP / achievements / streaks; disabling cripples gamification)\n\n5. **Third-party integrations to set up:**\n   - [ ] RevenueCat (IAP / subscriptions on iOS + Android)\n   - [ ] Superwall (paywall A/B)\n   - [ ] Stripe Billing (web subscriptions through the app's own Stripe account \u2014 provider `stripe_billing`)\n   - [ ] OpenAI / Anthropic / Mistral / Gemini LLM keys (required for `Amba.ai.*` \u2014 set via `amba_ai_providers_set`, **not** `amba_integrations_configure`)\n\n6. **Feature flags:** seed any starter flags?\n   - Yes \u2014 wire `beta_feature` (off by default) so I can ship the wiring before the feature exists\n   - No\n\n7. **Static site:** want a marketing page hosted under your tenant subdomain?\n   - Yes \u2014 scaffold and deploy a 1-page index\n   - No\n\n## Re-run behavior\n\n1. Before creating:\n   - `amba_collections_list` \u2014 match on `name`. Collisions: never silently recreate (data loss). Offer `amba_collections_alter` to add new columns instead.\n   - `amba_functions_list` \u2014 match on `name`. Collisions: ask to redeploy (with the new source) or skip.\n   - `amba_ai_prompts_list` \u2014 match on `name`. Same. (And `amba_ai_providers_list` \u2014 match on `provider`; re-running `amba_ai_providers_set` rotates the key in place.)\n   - `amba_integrations_list` \u2014 match on `provider`. Same.\n   - `amba_configs_list` \u2014 match on `key`. Same.\n\n2. **Never call `amba_collections_delete` on re-run unless the user explicitly asks** \u2014 this drops the underlying table and every row in it across every user of the tenant.\n\n3. For functions: re-deploying replaces source in place (versioned server-side). It's safe to call `amba_functions_deploy` with the same name + new source.\n\n4. For integrations: if a provider is already configured, prefer `amba_integrations_patch` (partial update) over `amba_integrations_set` (full replace).\n\n5. Secrets: don't list secret values in chat output, even on read. Just confirm \"OPENAI_API_KEY is set\" / \"not set\".\n";
+export declare const AMBA_SETUP_INFRASTRUCTURE_MD = "# Infrastructure\n\nThe plumbing that sits behind every other surface: relational Postgres tables (Collections \u2014 schema-first, per-tenant), serverless functions (run server-side code without standing up a backend), analytics (events + sessions), AI prompts (managed LLM templates, callable from the SDK with per-tenant keys), secrets, runtime configs, feature flags, third-party integrations (RevenueCat / Superwall / Stripe / push credentials), media (file storage + CDN), and sites (static asset hosting at `*.app.amba.host`).\n\nIf gamification, economy, and social are the playable surface, **infrastructure is what you build a custom product on top of**. Anything that doesn't fit the canned surfaces lands here.\n\n## MCP tools\n\n### Collections (relational Postgres tables)\n\nA collection is a relational Postgres table inside the project's isolated tenant database \u2014 typed columns, foreign keys, transactions, unique indexes, and vector search. You describe the columns, the server creates the table and any indexes. Rows are scoped to the signed-in `app_user` automatically (server-enforced auto row-level isolation) for SDK clients \u2014 admin tools bypass this.\n\nAdmin tools authenticate the developer/agent (pass `pat` or send it as the inbound Bearer) and take `project_id`. Client tools authenticate an end-user and take `api_key` (+ `session_token`) \u2014 NOT `project_id` and NOT a `pat`. Every row tool names the collection with `name`, never `collection`.\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_collections_create` | Create a typed collection. Pass `shared: true` for developer-seeded GLOBAL content (question banks, lookup tables) so `user_id` is nullable. | `{ project_id, name: \"todos\", columns: [{ name: \"title\", type: \"text\", nullable: false }, { name: \"done\", type: \"boolean\", nullable: false }, { name: \"due_at\", type: \"timestamptz\", nullable: true }], shared: false }` |\n| `amba_collections_list` | List collections in this project. | `{ project_id }` |\n| `amba_collections_get` | Read one collection's schema. | `{ project_id, name: \"todos\" }` |\n| `amba_collections_alter` | Exactly ONE of: `add_column`, `add_index`, `drop_column`, or `relax_user_id` per call. `relax_user_id: true` converts an existing collection to shared (drops the `user_id` NOT NULL). | `{ project_id, name: \"todos\", add_column: { name: \"priority\", type: \"integer\", nullable: true } }` |\n| `amba_collections_delete` | Drop the table (destructive). `confirm` must equal the collection name. | `{ project_id, name: \"todos\", confirm: \"todos\" }` |\n| `amba_admin_insert_row` | Insert one row as the developer (bypasses user-scope; `user_id` honored if present). | `{ project_id, name: \"todos\", row: { title: \"Sample\", done: false } }` |\n| `amba_admin_insert_rows` | Bulk-insert up to 500 rows in one atomic statement \u2014 the canonical seeding/migration path. `on_conflict`: `\"error\"` (default) or `\"skip\"`. | `{ project_id, name: \"questions\", rows: [{ q: \"...\" }, { q: \"...\" }], on_conflict: \"skip\" }` |\n| `amba_admin_list_rows` | Read rows as the developer. | `{ project_id, name: \"todos\", limit: 100 }` |\n| `amba_client_insert_row` | Insert as an end-user. Requires `api_key` (+ `session_token`). | `{ api_key, session_token, name: \"todos\", row: {...} }` |\n| `amba_client_list_rows` | Read as an end-user (auto user-scoped). | `{ api_key, session_token, name: \"todos\" }` |\n| `amba_client_get_row` | Get one row by id (end-user). | `{ api_key, session_token, name: \"todos\", id }` |\n| `amba_client_update_row` | Update one row by id (end-user). Fields go in `set`. Omit `id` + pass `where` for a bulk update. | `{ api_key, session_token, name: \"todos\", id, set: {...} }` |\n| `amba_client_delete_row` | Soft-delete one row by id (end-user). | `{ api_key, session_token, name: \"todos\", id }` |\n| `amba_client_count_rows` | Count rows matching an optional `where`. | `{ api_key, session_token, name: \"todos\", where: {...} }` |\n| `amba_client_find_rows` | Filter / sort / paginate rows (SDK-shaped `filter`). | `{ api_key, session_token, name: \"todos\", filter: {...}, order: [\"created_at desc\"], limit: 50 }` |\n| `amba_client_find_nearest_rows` | Vector-similarity search (rows with a `vector(<dim>)` column). | `{ api_key, session_token, name: \"todos\", column: \"embedding\", to_vector: [...], k: 10 }` |\n\nColumn types: `text`, `integer`, `bigint`, `numeric`, `boolean`, `timestamptz`, `date`, `jsonb`, `uuid`, `vector` (pass a separate `dimension` field, e.g. `{ name: \"embedding\", type: \"vector\", dimension: 1536 }` for OpenAI embeddings), plus array forms `text[]`, `integer[]`, `bigint[]`, `numeric[]`, `boolean[]`, `uuid[]`. Columns are NOT NULL unless `nullable: true`; column defaults are not supported (set values at insert time). Use `integer` (not `int`), `numeric` (not `float`/`real`/`double`), and `jsonb` (not `json`) \u2014 the validator rejects the aliases.\n\n### Functions (serverless code)\n\nRun user code in a sandbox triggered by HTTP, cron, or webhook. The function gets the tenant connection automatically via injected env.\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_functions_deploy` | Deploy a function from source. | `{ project_id, name: \"send_welcome_email\", runtime: \"node22\", source: \"export default async (req) => { ... }\", trigger: { type: \"http\" } }` |\n| `amba_functions_list` | List functions. | `{ project_id }` |\n| `amba_functions_get` | Read function metadata. | `{ project_id, function_id }` |\n| `amba_functions_get_logs` | Recent invocation logs. | `{ project_id, function_id, limit: 100 }` |\n| `amba_functions_delete` | Delete a function. | `{ project_id, function_id }` |\n| `amba_functions_schedule` | Attach a cron schedule. | `{ project_id, function_id, cron: \"0 9 * * *\", timezone: \"America/Los_Angeles\" }` |\n| `amba_functions_pause_schedule` | Pause a scheduled trigger without deleting it. | `{ project_id, function_id }` |\n| `amba_functions_resume_schedule` | Resume. | `{ project_id, function_id }` |\n| `amba_functions_trigger_schedule` | Fire a scheduled function ad-hoc (testing). | `{ project_id, function_id }` |\n| `amba_function_domains_attach` | Attach one exact hostname to one function; returns DNS validation instructions. | `{ project_id, name: \"feed\", hostname: \"feeds.example.com\" }` |\n| `amba_function_domains_list` | List provider-neutral hostname, ownership, and certificate status. | `{ project_id, name: \"feed\" }` |\n| `amba_function_domains_refresh` | Re-poll DNS ownership and certificate state. | `{ project_id, name: \"feed\", hostname: \"feeds.example.com\" }` |\n| `amba_function_domains_remove` | Detach an exact function hostname. | `{ project_id, name: \"feed\", hostname: \"feeds.example.com\" }` |\n\nFunction-domain routing preserves the complete incoming path and query string.\nIt is exact-host only (no wildcard/path rewrite and no automatic `www` for a\nsubdomain). Podcast/feed clients cannot attach an Amba API key, so their\nfunction must be deployed with `public: true` and validate any private token\ninside the handler. Effective-tier caps are free 1, pro 5, scale 20, and\nenterprise/comped 50; attach is limited to five attempts per project per hour.\nUnverified claims become eligible for reclaim after 24 hours, and routing\nresources are allocated only after ownership is active. Every hostname response\nincludes an unconditional `dns_note`: publish a real provider-stored CNAME;\nALIAS, ANAME, and copied A/AAAA addresses are not\nsubstitutes. Treat a hostname as ready only when `live=true`, never from TLS or\n`cert_status=active` alone.\n\n### AI prompts\n\nManaged LLM templates: a stored prompt with provider + model + system message, invoked by name from the SDK. The actual LLM call is rewritten server-side per-tenant \u2014 the customer's provider API key (Anthropic / OpenAI / Mistral / Gemini) stays server-side, never on the device.\n\n**Two steps, in order:** first register the provider key with `amba_ai_providers_set`, then create prompts against it. A prompt registered before its provider has a key still saves, but invocations fail with `provider_not_configured` (424) until the key is set.\n\n> The provider key is **not** a function secret. `amba_secrets_set` writes function-scoped Worker secrets, which the AI gateway never reads. Provider keys live in a separate gateway-owned store and are set **only** via `amba_ai_providers_set`.\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_ai_providers_set` | Register / rotate the upstream provider API key. **Do this first.** | `{ project_id, provider: \"anthropic\", api_key: \"sk-ant-...\" }` |\n| `amba_ai_providers_list` | List registered providers (`configured` = key set). | `{ project_id }` |\n| `amba_ai_providers_delete` | Revoke a provider key (fails if prompts still reference it). | `{ project_id, provider: \"anthropic\" }` |\n| `amba_ai_prompts_create` | Create a prompt template. `client_invokable: true` lets the device SDK invoke it directly. | `{ project_id, name: \"summarize\", provider: \"anthropic\", model: \"claude-opus-4-5\", system_prompt: \"Summarize the user's text in 2 sentences.\", client_invokable: true }` |\n| `amba_ai_prompts_list` | List prompts. | `{ project_id }` |\n| `amba_ai_prompts_get` | Read one prompt. | `{ project_id, name }` |\n| `amba_ai_prompts_update` | Edit a prompt (replaces all fields; bumps version). | `{ project_id, name, provider, model, system_prompt: \"...\" }` |\n| `amba_ai_prompts_invoke` | Invoke by name server-side (admin testing; works with `client_invokable: false`). Uses the named gateway path, so the prompt budget, rate limit, token cap, and spend attribution are enforced. | `{ project_id, name, messages: [{ role: \"user\", content: \"...\" }] }` |\n| `amba_ai_prompts_delete` | Delete. | `{ project_id, name }` |\n\n### Analytics + events + sessions\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_analytics_get` | Top-level metrics dashboard (MAU, DAU, retention). | `{ project_id, period: \"7d\" }` |\n| `amba_events_list` | Browse raw events. | `{ project_id, limit: 100, since: \"2026-05-19T00:00:00Z\" }` |\n| `amba_events_count` | Count events matching a filter. | `{ project_id, event: \"workout_completed\", since: \"...\" }` |\n| `amba_sessions_list` | List user sessions. | `{ project_id, limit: 50 }` |\n| `amba_sessions_analytics` | Session-level metrics. | `{ project_id, period: \"7d\" }` |\n| `amba_users_list_events` | Per-user event history. | `{ project_id, user_id }` |\n| `amba_users_export` | Export the full user list. | `{ project_id, format: \"csv\" }` |\n\n### Secrets + configs + integrations\n\nSecrets here become environment bindings on deployed functions. Omit `function`\nfor a project-wide secret or pass it to scope the value to one function. Setting\nor rotating a secret queues an asynchronous update for already-deployed\nfunctions; later deployments reconcile the binding too. They are NOT where AI\nprovider keys go (use `amba_ai_providers_set` for those \u2014 see AI prompts above).\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_secrets_set` | Set or rotate a function secret; omit `function` for project-wide scope or pass it for one function. Already-deployed functions receive it asynchronously. | `{ project_id, name: \"STRIPE_WEBHOOK_SECRET\", value: \"whsec_...\" }` |\n| `amba_secrets_get` | Read a secret (returns `\"<redacted>\"` unless explicitly requested). | `{ project_id, name }` |\n| `amba_secrets_list` | List secret names. | `{ project_id }` |\n| `amba_secrets_delete` | Delete. | `{ project_id, name }` |\n| `amba_configs_create` | Create a runtime config value (read from SDK as `Amba.config.fetch()`). | `{ project_id, key: \"primary_color\", value: \"#ff0066\", segment_id: null }` |\n| `amba_configs_list` | List configs. | `{ project_id }` |\n| `amba_configs_update` | Edit. | `{ project_id, config_id, value: \"...\" }` |\n| `amba_configs_delete` | Delete. | `{ project_id, config_id }` |\n| `amba_integrations_list` | List third-party integrations. | `{ project_id }` |\n| `amba_integrations_configure` | Configure a provider. | `{ project_id, provider: \"revenuecat\", config: { webhook_secret: \"...\", default_offering: \"...\" } }` |\n| `amba_integrations_set` | Set/replace integration config wholesale. | `{ project_id, provider, config }` |\n| `amba_integrations_patch` | Patch one field. | `{ project_id, provider, patch: { webhook_secret: \"...\" } }` |\n| `amba_integrations_test` | Send a test event to a configured provider. | `{ project_id, provider }` |\n\n### Media (file storage + CDN)\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_media_upload` | Upload a file (returns a tenant-scoped URL). | `{ project_id, name: \"logo.png\", content_type: \"image/png\", data: \"<base64>\" }` |\n| `amba_media_list` | List files. | `{ project_id, folder: \"/\", limit: 100 }` |\n| `amba_media_delete` | Delete a file. | `{ project_id, file_id }` |\n| `amba_media_create_folder` | Create a logical folder. | `{ project_id, path: \"/uploads/avatars\" }` |\n| `amba_media_list_folders` | List folders. | `{ project_id }` |\n| `amba_media_delete_folder` | Delete a folder (must be empty). | `{ project_id, path }` |\n\n### Sites (static asset hosting)\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_sites_deploy` | Deploy a static site bundle (zip / tar). | `{ project_id, name: \"marketing\", bundle: \"<base64>\", index: \"index.html\" }` |\n| `amba_sites_list` | List sites. | `{ project_id }` |\n| `amba_sites_get` | Read a site. | `{ project_id, site_id }` |\n| `amba_sites_add_domain` | Attach a custom domain. | `{ project_id, site_id, domain: \"marketing.example.com\" }` |\n| `amba_sites_list_domains` | List domains on a site. | `{ project_id, site_id }` |\n| `amba_sites_remove_domain` | Detach a domain. | `{ project_id, site_id, domain }` |\n| `amba_sites_delete` | Delete a site. | `{ project_id, site_id }` |\n\n### Purchased domains + email forwarding\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_domains_search` | Search available domains (free). | `{ project_id, query: \"myapp\" }` |\n| `amba_domains_check` | Check authoritative price + availability. | `{ project_id, domains: [\"myapp.com\"] }` |\n| `amba_domains_purchase` | Quote, then confirm, a domain purchase. | `{ project_id, domain: \"myapp.com\", site: \"marketing\" }` |\n| `amba_domains_list` | List purchased domains. | `{ project_id }` |\n| `amba_domains_email_enable` | Enable inbound routing when no MX conflict exists. | `{ project_id, domain: \"myapp.com\" }` |\n| `amba_domains_email_destinations_add` | Add a destination mailbox; returns action-required until verified. | `{ project_id, domain: \"myapp.com\", email: \"owner@example.net\" }` |\n| `amba_domains_email_destinations_get` | Poll destination verification. | `{ project_id, domain: \"myapp.com\", destination_id }` |\n| `amba_domains_email_forwards_set` | Create/update a literal forward. | `{ project_id, domain: \"myapp.com\", source: \"support\", destination: \"owner@example.net\" }` |\n| `amba_domains_email_forwards_list` | List literal forwards. | `{ project_id, domain: \"myapp.com\" }` |\n| `amba_domains_email_forwards_delete` | Delete a literal forward. | `{ project_id, domain: \"myapp.com\", forward_id }` |\n| `amba_domains_email_catch_all_set` | Enable/update/disable catch-all. | `{ project_id, domain: \"myapp.com\", enabled: true, destination: \"owner@example.net\" }` |\n| `amba_domains_email_catch_all_get` | Read catch-all state. | `{ project_id, domain: \"myapp.com\" }` |\n\n## SDK init per stack\n\n`Amba.configure(...)` runs first. The infrastructure surfaces \u2014 collections, AI, config, flags, events \u2014 are SDK-side reads; the snippets below show what the client calls look like.\n\n### Expo / React Native\n\n```tsx\nimport { Amba } from '@layers/amba-expo';\n\n// Collections \u2014 typed table, user-scoped reads + writes\ntype Todo = { id: string; title: string; done: boolean; created_at: string };\n\nconst { data: todos } = await Amba.collections.find<Todo>('todos', {\n  filter: Amba.collections.where.eq('done', false),\n  order: [{ column: 'created_at', direction: 'desc' }],\n  limit: 50,\n});\n\nconst newTodo = await Amba.collections.insert('todos', { title: 'Ship the app', done: false });\nawait Amba.collections.update('todos', newTodo.id, { done: true });\nawait Amba.collections.delete('todos', newTodo.id);\n\n// AI \u2014 call a managed prompt (prompt_slug names the registered prompt)\nconst response = await Amba.ai.anthropic.messages.create({\n  prompt_slug: 'summarize',\n  variables: { text: 'A long article about backend services \u2026' },\n});\n\n// Track an analytics event\nawait Amba.events.track('button_clicked', { button: 'cta' });\n\n// Read runtime config\nconst config = await Amba.config.fetch();\n\n// Read a feature flag\nconst showBeta = await Amba.flags.get('beta_feature');\n\n// Diagnostics \u2014 wire-verify\nconst ping = await Amba.diagnostics.ping();\nif (!ping.ok) console.error('Amba misconfigured:', ping);\n```\n\n### Web\n\n```ts\nimport { Amba } from '@layers/amba-web';\n\nconst { data: todos } = await Amba.collections.find('todos', {\n  filter: Amba.collections.where.eq('done', false),\n  limit: 50,\n});\nawait Amba.collections.insert('todos', { title: 'Ship', done: false });\nawait Amba.events.track('page_view', { path: location.pathname });\n```\n\nWith `@layers/amba-react`:\n\n```tsx\nimport { useCollection, useFlag } from '@layers/amba-react';\n\nfunction TodoList() {\n  const { data: todos, loading, refetch } = useCollection<{ id: string; title: string }>('todos');\n  const showArchive = useFlag('archive_todos');\n  if (loading) return <Spinner />;\n  return (\n    <ul>\n      {todos?.map(t => <li key={t.id}>{t.title}</li>)}\n      {showArchive && <ArchiveButton onArchive={refetch} />}\n    </ul>\n  );\n}\n```\n\n### iOS (Swift)\n\n```swift\nimport Amba\n\nstruct Todo: Codable {\n    let id: String\n    let title: String\n    let done: Bool\n}\n\nlet response = try await Amba.collections.find(\"todos\", as: Todo.self)\n_ = try await Amba.collections.insert(\"todos\", row: [\"title\": \"Ship\", \"done\": false])\n\nlet config = try await Amba.config.fetch()\nlet showBeta = try await Amba.flags.get(name: \"beta_feature\")\ntry await Amba.events.track(\"app_opened\", properties: [\"source\": \"deep_link\"])\n\nlet reply = try await Amba.ai.anthropic.messages.create(\n    request: AiMessageRequest(promptSlug: \"summarize\", variables: [\"text\": \"A long article...\"])\n)\n```\n\n### Android (Kotlin)\n\n```kotlin\ndata class Todo(val id: String, val title: String, val done: Boolean)\n\nval todos = Amba.collections.find<Todo>(\"todos\")\nAmba.collections.insert(\"todos\", mapOf(\"title\" to \"Ship\", \"done\" to false))\n\nval config = Amba.config.fetch()\nval showBeta = Amba.flags.get(\"beta_feature\")\nAmba.events.track(\"app_opened\", mapOf(\"source\" to \"deep_link\"))\n```\n\n### Flutter\n\n```dart\nimport 'package:amba/amba.dart';\n\nfinal response = await Amba.collections.find('todos', limit: 50);\nawait Amba.collections.insert('todos', {'title': 'Ship', 'done': false});\nfinal config = await Amba.config.fetch();\nfinal showBeta = await Amba.flags.get('beta_feature');\nawait Amba.events.track('app_opened', {'source': 'deep_link'});\n```\n\n## Common follow-ups\n\nBatch.\n\n1. **Custom data tables (collections):** any domain-specific tables to create?\n   - Yes \u2014 I'll list them. (For each: name + columns + types.)\n   - No, just use the canned Amba surfaces (auth, push, gamification, etc.)\n   - Auto-create from the existing code's models \u2014 read `lib/models/`, `src/types/`, `Models/`, infer column lists, confirm with me.\n\n2. **Custom backend logic (functions):** any server-side code to deploy?\n   - Yes \u2014 describe what it should do. (Then offer to scaffold a function template and deploy.)\n   - No\n\n3. **AI features:** want managed LLM prompts?\n   - Yes \u2014 what's the use case? (summarize, translate, classify, generate, custom)\n   - No\n\n4. **Analytics:** which tracker do you want?\n   - Only Amba's built-in events (recommended \u2014 already wired)\n   - Amba + your own analytics pipeline (subscribe a webhook to project events via `amba_webhooks_create` and forward server-side)\n   - None (rarely useful \u2014 events drive XP / achievements / streaks; disabling cripples gamification)\n\n5. **Third-party integrations to set up:**\n   - [ ] RevenueCat (IAP / subscriptions on iOS + Android)\n   - [ ] Superwall (paywall A/B)\n   - [ ] Stripe Billing (web subscriptions through the app's own Stripe account \u2014 provider `stripe_billing`)\n   - [ ] OpenAI / Anthropic / Mistral / Gemini LLM keys (required for `Amba.ai.*` \u2014 set via `amba_ai_providers_set`, **not** `amba_integrations_configure`)\n\n6. **Feature flags:** seed any starter flags?\n   - Yes \u2014 wire `beta_feature` (off by default) so I can ship the wiring before the feature exists\n   - No\n\n7. **Static site:** want a marketing page hosted under your tenant subdomain?\n   - Yes \u2014 scaffold and deploy a 1-page index\n   - No\n\n## Re-run behavior\n\n1. Before creating:\n   - `amba_collections_list` \u2014 match on `name`. Collisions: never silently recreate (data loss). Offer `amba_collections_alter` to add new columns instead.\n   - `amba_functions_list` \u2014 match on `name`. Collisions: ask to redeploy (with the new source) or skip.\n   - `amba_ai_prompts_list` \u2014 match on `name`. Same. (And `amba_ai_providers_list` \u2014 match on `provider`; re-running `amba_ai_providers_set` rotates the key in place.)\n   - `amba_integrations_list` \u2014 match on `provider`. Same.\n   - `amba_configs_list` \u2014 match on `key`. Same.\n\n2. **Never call `amba_collections_delete` on re-run unless the user explicitly asks** \u2014 this drops the underlying table and every row in it across every user of the tenant.\n\n3. For functions: re-deploying replaces source in place (versioned server-side). It's safe to call `amba_functions_deploy` with the same name + new source.\n\n4. For integrations: if a provider is already configured, prefer `amba_integrations_patch` (partial update) over `amba_integrations_set` (full replace).\n\n5. Secrets: don't list secret values in chat output, even on read. Just confirm \"OPENAI_API_KEY is set\" / \"not set\".\n";
 export declare const AMBA_SETUP_INFRASTRUCTURE_URI = "amba://setup/infrastructure";
 export declare const AMBA_SETUP_INFRASTRUCTURE_MIME = "text/markdown";

package/dist/resources/index.d.ts

@@ -93,7 +93,7 @@ export declare const AMBA_SETUP_SUB_RESOURCES: readonly [{
     readonly name: "amba-setup-infrastructure";
     readonly uri: "amba://setup/infrastructure";
     readonly mime: "text/markdown";
-    readonly body: "# Infrastructure\n\nThe plumbing that sits behind every other surface: relational Postgres tables (Collections — schema-first, per-tenant), serverless functions (run server-side code without standing up a backend), analytics (events + sessions), AI prompts (managed LLM templates, callable from the SDK with per-tenant keys), secrets, runtime configs, feature flags, third-party integrations (RevenueCat / Superwall / Stripe / push credentials), media (file storage + CDN), and sites (static asset hosting at `*.app.amba.host`).\n\nIf gamification, economy, and social are the playable surface, **infrastructure is what you build a custom product on top of**. Anything that doesn't fit the canned surfaces lands here.\n\n## MCP tools\n\n### Collections (relational Postgres tables)\n\nA collection is a relational Postgres table inside the project's isolated tenant database — typed columns, foreign keys, transactions, unique indexes, and vector search. You describe the columns, the server creates the table and any indexes. Rows are scoped to the signed-in `app_user` automatically (server-enforced auto row-level isolation) for SDK clients — admin tools bypass this.\n\nAdmin tools authenticate the developer/agent (pass `pat` or send it as the inbound Bearer) and take `project_id`. Client tools authenticate an end-user and take `api_key` (+ `session_token`) — NOT `project_id` and NOT a `pat`. Every row tool names the collection with `name`, never `collection`.\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_collections_create` | Create a typed collection. Pass `shared: true` for developer-seeded GLOBAL content (question banks, lookup tables) so `user_id` is nullable. | `{ project_id, name: \"todos\", columns: [{ name: \"title\", type: \"text\", nullable: false }, { name: \"done\", type: \"boolean\", nullable: false }, { name: \"due_at\", type: \"timestamptz\", nullable: true }], shared: false }` |\n| `amba_collections_list` | List collections in this project. | `{ project_id }` |\n| `amba_collections_get` | Read one collection's schema. | `{ project_id, name: \"todos\" }` |\n| `amba_collections_alter` | Exactly ONE of: `add_column`, `add_index`, `drop_column`, or `relax_user_id` per call. `relax_user_id: true` converts an existing collection to shared (drops the `user_id` NOT NULL). | `{ project_id, name: \"todos\", add_column: { name: \"priority\", type: \"integer\", nullable: true } }` |\n| `amba_collections_delete` | Drop the table (destructive). `confirm` must equal the collection name. | `{ project_id, name: \"todos\", confirm: \"todos\" }` |\n| `amba_admin_insert_row` | Insert one row as the developer (bypasses user-scope; `user_id` honored if present). | `{ project_id, name: \"todos\", row: { title: \"Sample\", done: false } }` |\n| `amba_admin_insert_rows` | Bulk-insert up to 500 rows in one atomic statement — the canonical seeding/migration path. `on_conflict`: `\"error\"` (default) or `\"skip\"`. | `{ project_id, name: \"questions\", rows: [{ q: \"...\" }, { q: \"...\" }], on_conflict: \"skip\" }` |\n| `amba_admin_list_rows` | Read rows as the developer. | `{ project_id, name: \"todos\", limit: 100 }` |\n| `amba_client_insert_row` | Insert as an end-user. Requires `api_key` (+ `session_token`). | `{ api_key, session_token, name: \"todos\", row: {...} }` |\n| `amba_client_list_rows` | Read as an end-user (auto user-scoped). | `{ api_key, session_token, name: \"todos\" }` |\n| `amba_client_get_row` | Get one row by id (end-user). | `{ api_key, session_token, name: \"todos\", id }` |\n| `amba_client_update_row` | Update one row by id (end-user). Fields go in `set`. Omit `id` + pass `where` for a bulk update. | `{ api_key, session_token, name: \"todos\", id, set: {...} }` |\n| `amba_client_delete_row` | Soft-delete one row by id (end-user). | `{ api_key, session_token, name: \"todos\", id }` |\n| `amba_client_count_rows` | Count rows matching an optional `where`. | `{ api_key, session_token, name: \"todos\", where: {...} }` |\n| `amba_client_find_rows` | Filter / sort / paginate rows (SDK-shaped `filter`). | `{ api_key, session_token, name: \"todos\", filter: {...}, order: [\"created_at desc\"], limit: 50 }` |\n| `amba_client_find_nearest_rows` | Vector-similarity search (rows with a `vector(<dim>)` column). | `{ api_key, session_token, name: \"todos\", column: \"embedding\", to_vector: [...], k: 10 }` |\n\nColumn types: `text`, `integer`, `bigint`, `numeric`, `boolean`, `timestamptz`, `date`, `jsonb`, `uuid`, `vector` (pass a separate `dimension` field, e.g. `{ name: \"embedding\", type: \"vector\", dimension: 1536 }` for OpenAI embeddings), plus array forms `text[]`, `integer[]`, `bigint[]`, `numeric[]`, `boolean[]`, `uuid[]`. Columns are NOT NULL unless `nullable: true`; column defaults are not supported (set values at insert time). Use `integer` (not `int`), `numeric` (not `float`/`real`/`double`), and `jsonb` (not `json`) — the validator rejects the aliases.\n\n### Functions (serverless code)\n\nRun user code in a sandbox triggered by HTTP, cron, or webhook. The function gets the tenant connection automatically via injected env.\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_functions_deploy` | Deploy a function from source. | `{ project_id, name: \"send_welcome_email\", runtime: \"node22\", source: \"export default async (req) => { ... }\", trigger: { type: \"http\" } }` |\n| `amba_functions_list` | List functions. | `{ project_id }` |\n| `amba_functions_get` | Read function metadata. | `{ project_id, function_id }` |\n| `amba_functions_get_logs` | Recent invocation logs. | `{ project_id, function_id, limit: 100 }` |\n| `amba_functions_delete` | Delete a function. | `{ project_id, function_id }` |\n| `amba_functions_schedule` | Attach a cron schedule. | `{ project_id, function_id, cron: \"0 9 * * *\", timezone: \"America/Los_Angeles\" }` |\n| `amba_functions_pause_schedule` | Pause a scheduled trigger without deleting it. | `{ project_id, function_id }` |\n| `amba_functions_resume_schedule` | Resume. | `{ project_id, function_id }` |\n| `amba_functions_trigger_schedule` | Fire a scheduled function ad-hoc (testing). | `{ project_id, function_id }` |\n| `amba_function_domains_attach` | Attach one exact hostname to one function; returns DNS validation instructions. | `{ project_id, name: \"feed\", hostname: \"feeds.example.com\" }` |\n| `amba_function_domains_list` | List provider-neutral hostname, ownership, and certificate status. | `{ project_id, name: \"feed\" }` |\n| `amba_function_domains_refresh` | Re-poll DNS ownership and certificate state. | `{ project_id, name: \"feed\", hostname: \"feeds.example.com\" }` |\n| `amba_function_domains_remove` | Detach an exact function hostname. | `{ project_id, name: \"feed\", hostname: \"feeds.example.com\" }` |\n\nFunction-domain routing preserves the complete incoming path and query string.\nIt is exact-host only (no wildcard/path rewrite and no automatic `www` for a\nsubdomain). Podcast/feed clients cannot attach an Amba API key, so their\nfunction must be deployed with `public: true` and validate any private token\ninside the handler. Effective-tier caps are free 1, pro 5, scale 20, and\nenterprise/comped 50; attach is limited to five attempts per project per hour.\nUnverified claims become eligible for reclaim after 24 hours, and routing\nresources are allocated only after ownership is active.\n\n### AI prompts\n\nManaged LLM templates: a stored prompt with provider + model + system message, invoked by name from the SDK. The actual LLM call is rewritten server-side per-tenant — the customer's provider API key (Anthropic / OpenAI / Mistral / Gemini) stays server-side, never on the device.\n\n**Two steps, in order:** first register the provider key with `amba_ai_providers_set`, then create prompts against it. A prompt registered before its provider has a key still saves, but invocations fail with `provider_not_configured` (424) until the key is set.\n\n> The provider key is **not** a function secret. `amba_secrets_set` writes function-scoped Worker secrets, which the AI gateway never reads. Provider keys live in a separate gateway-owned store and are set **only** via `amba_ai_providers_set`.\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_ai_providers_set` | Register / rotate the upstream provider API key. **Do this first.** | `{ project_id, provider: \"anthropic\", api_key: \"sk-ant-...\" }` |\n| `amba_ai_providers_list` | List registered providers (`configured` = key set). | `{ project_id }` |\n| `amba_ai_providers_delete` | Revoke a provider key (fails if prompts still reference it). | `{ project_id, provider: \"anthropic\" }` |\n| `amba_ai_prompts_create` | Create a prompt template. `client_invokable: true` lets the device SDK invoke it directly. | `{ project_id, name: \"summarize\", provider: \"anthropic\", model: \"claude-opus-4-5\", system_prompt: \"Summarize the user's text in 2 sentences.\", client_invokable: true }` |\n| `amba_ai_prompts_list` | List prompts. | `{ project_id }` |\n| `amba_ai_prompts_get` | Read one prompt. | `{ project_id, name }` |\n| `amba_ai_prompts_update` | Edit a prompt (replaces all fields; bumps version). | `{ project_id, name, provider, model, system_prompt: \"...\" }` |\n| `amba_ai_prompts_invoke` | Invoke by name server-side (admin testing; works with `client_invokable: false`). Uses the named gateway path, so the prompt budget, rate limit, token cap, and spend attribution are enforced. | `{ project_id, name, messages: [{ role: \"user\", content: \"...\" }] }` |\n| `amba_ai_prompts_delete` | Delete. | `{ project_id, name }` |\n\n### Analytics + events + sessions\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_analytics_get` | Top-level metrics dashboard (MAU, DAU, retention). | `{ project_id, period: \"7d\" }` |\n| `amba_events_list` | Browse raw events. | `{ project_id, limit: 100, since: \"2026-05-19T00:00:00Z\" }` |\n| `amba_events_count` | Count events matching a filter. | `{ project_id, event: \"workout_completed\", since: \"...\" }` |\n| `amba_sessions_list` | List user sessions. | `{ project_id, limit: 50 }` |\n| `amba_sessions_analytics` | Session-level metrics. | `{ project_id, period: \"7d\" }` |\n| `amba_users_list_events` | Per-user event history. | `{ project_id, user_id }` |\n| `amba_users_export` | Export the full user list. | `{ project_id, format: \"csv\" }` |\n\n### Secrets + configs + integrations\n\nSecrets here become environment bindings on deployed functions. Omit `function`\nfor a project-wide secret or pass it to scope the value to one function. Setting\nor rotating a secret queues an asynchronous update for already-deployed\nfunctions; later deployments reconcile the binding too. They are NOT where AI\nprovider keys go (use `amba_ai_providers_set` for those — see AI prompts above).\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_secrets_set` | Set or rotate a function secret; omit `function` for project-wide scope or pass it for one function. Already-deployed functions receive it asynchronously. | `{ project_id, name: \"STRIPE_WEBHOOK_SECRET\", value: \"whsec_...\" }` |\n| `amba_secrets_get` | Read a secret (returns `\"<redacted>\"` unless explicitly requested). | `{ project_id, name }` |\n| `amba_secrets_list` | List secret names. | `{ project_id }` |\n| `amba_secrets_delete` | Delete. | `{ project_id, name }` |\n| `amba_configs_create` | Create a runtime config value (read from SDK as `Amba.config.fetch()`). | `{ project_id, key: \"primary_color\", value: \"#ff0066\", segment_id: null }` |\n| `amba_configs_list` | List configs. | `{ project_id }` |\n| `amba_configs_update` | Edit. | `{ project_id, config_id, value: \"...\" }` |\n| `amba_configs_delete` | Delete. | `{ project_id, config_id }` |\n| `amba_integrations_list` | List third-party integrations. | `{ project_id }` |\n| `amba_integrations_configure` | Configure a provider. | `{ project_id, provider: \"revenuecat\", config: { webhook_secret: \"...\", default_offering: \"...\" } }` |\n| `amba_integrations_set` | Set/replace integration config wholesale. | `{ project_id, provider, config }` |\n| `amba_integrations_patch` | Patch one field. | `{ project_id, provider, patch: { webhook_secret: \"...\" } }` |\n| `amba_integrations_test` | Send a test event to a configured provider. | `{ project_id, provider }` |\n\n### Media (file storage + CDN)\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_media_upload` | Upload a file (returns a tenant-scoped URL). | `{ project_id, name: \"logo.png\", content_type: \"image/png\", data: \"<base64>\" }` |\n| `amba_media_list` | List files. | `{ project_id, folder: \"/\", limit: 100 }` |\n| `amba_media_delete` | Delete a file. | `{ project_id, file_id }` |\n| `amba_media_create_folder` | Create a logical folder. | `{ project_id, path: \"/uploads/avatars\" }` |\n| `amba_media_list_folders` | List folders. | `{ project_id }` |\n| `amba_media_delete_folder` | Delete a folder (must be empty). | `{ project_id, path }` |\n\n### Sites (static asset hosting)\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_sites_deploy` | Deploy a static site bundle (zip / tar). | `{ project_id, name: \"marketing\", bundle: \"<base64>\", index: \"index.html\" }` |\n| `amba_sites_list` | List sites. | `{ project_id }` |\n| `amba_sites_get` | Read a site. | `{ project_id, site_id }` |\n| `amba_sites_add_domain` | Attach a custom domain. | `{ project_id, site_id, domain: \"marketing.example.com\" }` |\n| `amba_sites_list_domains` | List domains on a site. | `{ project_id, site_id }` |\n| `amba_sites_remove_domain` | Detach a domain. | `{ project_id, site_id, domain }` |\n| `amba_sites_delete` | Delete a site. | `{ project_id, site_id }` |\n\n### Purchased domains + email forwarding\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_domains_search` | Search available domains (free). | `{ project_id, query: \"myapp\" }` |\n| `amba_domains_check` | Check authoritative price + availability. | `{ project_id, domains: [\"myapp.com\"] }` |\n| `amba_domains_purchase` | Quote, then confirm, a domain purchase. | `{ project_id, domain: \"myapp.com\", site: \"marketing\" }` |\n| `amba_domains_list` | List purchased domains. | `{ project_id }` |\n| `amba_domains_email_enable` | Enable inbound routing when no MX conflict exists. | `{ project_id, domain: \"myapp.com\" }` |\n| `amba_domains_email_destinations_add` | Add a destination mailbox; returns action-required until verified. | `{ project_id, domain: \"myapp.com\", email: \"owner@example.net\" }` |\n| `amba_domains_email_destinations_get` | Poll destination verification. | `{ project_id, domain: \"myapp.com\", destination_id }` |\n| `amba_domains_email_forwards_set` | Create/update a literal forward. | `{ project_id, domain: \"myapp.com\", source: \"support\", destination: \"owner@example.net\" }` |\n| `amba_domains_email_forwards_list` | List literal forwards. | `{ project_id, domain: \"myapp.com\" }` |\n| `amba_domains_email_forwards_delete` | Delete a literal forward. | `{ project_id, domain: \"myapp.com\", forward_id }` |\n| `amba_domains_email_catch_all_set` | Enable/update/disable catch-all. | `{ project_id, domain: \"myapp.com\", enabled: true, destination: \"owner@example.net\" }` |\n| `amba_domains_email_catch_all_get` | Read catch-all state. | `{ project_id, domain: \"myapp.com\" }` |\n\n## SDK init per stack\n\n`Amba.configure(...)` runs first. The infrastructure surfaces — collections, AI, config, flags, events — are SDK-side reads; the snippets below show what the client calls look like.\n\n### Expo / React Native\n\n```tsx\nimport { Amba } from '@layers/amba-expo';\n\n// Collections — typed table, user-scoped reads + writes\ntype Todo = { id: string; title: string; done: boolean; created_at: string };\n\nconst { data: todos } = await Amba.collections.find<Todo>('todos', {\n  filter: Amba.collections.where.eq('done', false),\n  order: [{ column: 'created_at', direction: 'desc' }],\n  limit: 50,\n});\n\nconst newTodo = await Amba.collections.insert('todos', { title: 'Ship the app', done: false });\nawait Amba.collections.update('todos', newTodo.id, { done: true });\nawait Amba.collections.delete('todos', newTodo.id);\n\n// AI — call a managed prompt (prompt_slug names the registered prompt)\nconst response = await Amba.ai.anthropic.messages.create({\n  prompt_slug: 'summarize',\n  variables: { text: 'A long article about backend services …' },\n});\n\n// Track an analytics event\nawait Amba.events.track('button_clicked', { button: 'cta' });\n\n// Read runtime config\nconst config = await Amba.config.fetch();\n\n// Read a feature flag\nconst showBeta = await Amba.flags.get('beta_feature');\n\n// Diagnostics — wire-verify\nconst ping = await Amba.diagnostics.ping();\nif (!ping.ok) console.error('Amba misconfigured:', ping);\n```\n\n### Web\n\n```ts\nimport { Amba } from '@layers/amba-web';\n\nconst { data: todos } = await Amba.collections.find('todos', {\n  filter: Amba.collections.where.eq('done', false),\n  limit: 50,\n});\nawait Amba.collections.insert('todos', { title: 'Ship', done: false });\nawait Amba.events.track('page_view', { path: location.pathname });\n```\n\nWith `@layers/amba-react`:\n\n```tsx\nimport { useCollection, useFlag } from '@layers/amba-react';\n\nfunction TodoList() {\n  const { data: todos, loading, refetch } = useCollection<{ id: string; title: string }>('todos');\n  const showArchive = useFlag('archive_todos');\n  if (loading) return <Spinner />;\n  return (\n    <ul>\n      {todos?.map(t => <li key={t.id}>{t.title}</li>)}\n      {showArchive && <ArchiveButton onArchive={refetch} />}\n    </ul>\n  );\n}\n```\n\n### iOS (Swift)\n\n```swift\nimport Amba\n\nstruct Todo: Codable {\n    let id: String\n    let title: String\n    let done: Bool\n}\n\nlet response = try await Amba.collections.find(\"todos\", as: Todo.self)\n_ = try await Amba.collections.insert(\"todos\", row: [\"title\": \"Ship\", \"done\": false])\n\nlet config = try await Amba.config.fetch()\nlet showBeta = try await Amba.flags.get(name: \"beta_feature\")\ntry await Amba.events.track(\"app_opened\", properties: [\"source\": \"deep_link\"])\n\nlet reply = try await Amba.ai.anthropic.messages.create(\n    request: AiMessageRequest(promptSlug: \"summarize\", variables: [\"text\": \"A long article...\"])\n)\n```\n\n### Android (Kotlin)\n\n```kotlin\ndata class Todo(val id: String, val title: String, val done: Boolean)\n\nval todos = Amba.collections.find<Todo>(\"todos\")\nAmba.collections.insert(\"todos\", mapOf(\"title\" to \"Ship\", \"done\" to false))\n\nval config = Amba.config.fetch()\nval showBeta = Amba.flags.get(\"beta_feature\")\nAmba.events.track(\"app_opened\", mapOf(\"source\" to \"deep_link\"))\n```\n\n### Flutter\n\n```dart\nimport 'package:amba/amba.dart';\n\nfinal response = await Amba.collections.find('todos', limit: 50);\nawait Amba.collections.insert('todos', {'title': 'Ship', 'done': false});\nfinal config = await Amba.config.fetch();\nfinal showBeta = await Amba.flags.get('beta_feature');\nawait Amba.events.track('app_opened', {'source': 'deep_link'});\n```\n\n## Common follow-ups\n\nBatch.\n\n1. **Custom data tables (collections):** any domain-specific tables to create?\n   - Yes — I'll list them. (For each: name + columns + types.)\n   - No, just use the canned Amba surfaces (auth, push, gamification, etc.)\n   - Auto-create from the existing code's models — read `lib/models/`, `src/types/`, `Models/`, infer column lists, confirm with me.\n\n2. **Custom backend logic (functions):** any server-side code to deploy?\n   - Yes — describe what it should do. (Then offer to scaffold a function template and deploy.)\n   - No\n\n3. **AI features:** want managed LLM prompts?\n   - Yes — what's the use case? (summarize, translate, classify, generate, custom)\n   - No\n\n4. **Analytics:** which tracker do you want?\n   - Only Amba's built-in events (recommended — already wired)\n   - Amba + your own analytics pipeline (subscribe a webhook to project events via `amba_webhooks_create` and forward server-side)\n   - None (rarely useful — events drive XP / achievements / streaks; disabling cripples gamification)\n\n5. **Third-party integrations to set up:**\n   - [ ] RevenueCat (IAP / subscriptions on iOS + Android)\n   - [ ] Superwall (paywall A/B)\n   - [ ] Stripe Billing (web subscriptions through the app's own Stripe account — provider `stripe_billing`)\n   - [ ] OpenAI / Anthropic / Mistral / Gemini LLM keys (required for `Amba.ai.*` — set via `amba_ai_providers_set`, **not** `amba_integrations_configure`)\n\n6. **Feature flags:** seed any starter flags?\n   - Yes — wire `beta_feature` (off by default) so I can ship the wiring before the feature exists\n   - No\n\n7. **Static site:** want a marketing page hosted under your tenant subdomain?\n   - Yes — scaffold and deploy a 1-page index\n   - No\n\n## Re-run behavior\n\n1. Before creating:\n   - `amba_collections_list` — match on `name`. Collisions: never silently recreate (data loss). Offer `amba_collections_alter` to add new columns instead.\n   - `amba_functions_list` — match on `name`. Collisions: ask to redeploy (with the new source) or skip.\n   - `amba_ai_prompts_list` — match on `name`. Same. (And `amba_ai_providers_list` — match on `provider`; re-running `amba_ai_providers_set` rotates the key in place.)\n   - `amba_integrations_list` — match on `provider`. Same.\n   - `amba_configs_list` — match on `key`. Same.\n\n2. **Never call `amba_collections_delete` on re-run unless the user explicitly asks** — this drops the underlying table and every row in it across every user of the tenant.\n\n3. For functions: re-deploying replaces source in place (versioned server-side). It's safe to call `amba_functions_deploy` with the same name + new source.\n\n4. For integrations: if a provider is already configured, prefer `amba_integrations_patch` (partial update) over `amba_integrations_set` (full replace).\n\n5. Secrets: don't list secret values in chat output, even on read. Just confirm \"OPENAI_API_KEY is set\" / \"not set\".\n";
+    readonly body: "# Infrastructure\n\nThe plumbing that sits behind every other surface: relational Postgres tables (Collections — schema-first, per-tenant), serverless functions (run server-side code without standing up a backend), analytics (events + sessions), AI prompts (managed LLM templates, callable from the SDK with per-tenant keys), secrets, runtime configs, feature flags, third-party integrations (RevenueCat / Superwall / Stripe / push credentials), media (file storage + CDN), and sites (static asset hosting at `*.app.amba.host`).\n\nIf gamification, economy, and social are the playable surface, **infrastructure is what you build a custom product on top of**. Anything that doesn't fit the canned surfaces lands here.\n\n## MCP tools\n\n### Collections (relational Postgres tables)\n\nA collection is a relational Postgres table inside the project's isolated tenant database — typed columns, foreign keys, transactions, unique indexes, and vector search. You describe the columns, the server creates the table and any indexes. Rows are scoped to the signed-in `app_user` automatically (server-enforced auto row-level isolation) for SDK clients — admin tools bypass this.\n\nAdmin tools authenticate the developer/agent (pass `pat` or send it as the inbound Bearer) and take `project_id`. Client tools authenticate an end-user and take `api_key` (+ `session_token`) — NOT `project_id` and NOT a `pat`. Every row tool names the collection with `name`, never `collection`.\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_collections_create` | Create a typed collection. Pass `shared: true` for developer-seeded GLOBAL content (question banks, lookup tables) so `user_id` is nullable. | `{ project_id, name: \"todos\", columns: [{ name: \"title\", type: \"text\", nullable: false }, { name: \"done\", type: \"boolean\", nullable: false }, { name: \"due_at\", type: \"timestamptz\", nullable: true }], shared: false }` |\n| `amba_collections_list` | List collections in this project. | `{ project_id }` |\n| `amba_collections_get` | Read one collection's schema. | `{ project_id, name: \"todos\" }` |\n| `amba_collections_alter` | Exactly ONE of: `add_column`, `add_index`, `drop_column`, or `relax_user_id` per call. `relax_user_id: true` converts an existing collection to shared (drops the `user_id` NOT NULL). | `{ project_id, name: \"todos\", add_column: { name: \"priority\", type: \"integer\", nullable: true } }` |\n| `amba_collections_delete` | Drop the table (destructive). `confirm` must equal the collection name. | `{ project_id, name: \"todos\", confirm: \"todos\" }` |\n| `amba_admin_insert_row` | Insert one row as the developer (bypasses user-scope; `user_id` honored if present). | `{ project_id, name: \"todos\", row: { title: \"Sample\", done: false } }` |\n| `amba_admin_insert_rows` | Bulk-insert up to 500 rows in one atomic statement — the canonical seeding/migration path. `on_conflict`: `\"error\"` (default) or `\"skip\"`. | `{ project_id, name: \"questions\", rows: [{ q: \"...\" }, { q: \"...\" }], on_conflict: \"skip\" }` |\n| `amba_admin_list_rows` | Read rows as the developer. | `{ project_id, name: \"todos\", limit: 100 }` |\n| `amba_client_insert_row` | Insert as an end-user. Requires `api_key` (+ `session_token`). | `{ api_key, session_token, name: \"todos\", row: {...} }` |\n| `amba_client_list_rows` | Read as an end-user (auto user-scoped). | `{ api_key, session_token, name: \"todos\" }` |\n| `amba_client_get_row` | Get one row by id (end-user). | `{ api_key, session_token, name: \"todos\", id }` |\n| `amba_client_update_row` | Update one row by id (end-user). Fields go in `set`. Omit `id` + pass `where` for a bulk update. | `{ api_key, session_token, name: \"todos\", id, set: {...} }` |\n| `amba_client_delete_row` | Soft-delete one row by id (end-user). | `{ api_key, session_token, name: \"todos\", id }` |\n| `amba_client_count_rows` | Count rows matching an optional `where`. | `{ api_key, session_token, name: \"todos\", where: {...} }` |\n| `amba_client_find_rows` | Filter / sort / paginate rows (SDK-shaped `filter`). | `{ api_key, session_token, name: \"todos\", filter: {...}, order: [\"created_at desc\"], limit: 50 }` |\n| `amba_client_find_nearest_rows` | Vector-similarity search (rows with a `vector(<dim>)` column). | `{ api_key, session_token, name: \"todos\", column: \"embedding\", to_vector: [...], k: 10 }` |\n\nColumn types: `text`, `integer`, `bigint`, `numeric`, `boolean`, `timestamptz`, `date`, `jsonb`, `uuid`, `vector` (pass a separate `dimension` field, e.g. `{ name: \"embedding\", type: \"vector\", dimension: 1536 }` for OpenAI embeddings), plus array forms `text[]`, `integer[]`, `bigint[]`, `numeric[]`, `boolean[]`, `uuid[]`. Columns are NOT NULL unless `nullable: true`; column defaults are not supported (set values at insert time). Use `integer` (not `int`), `numeric` (not `float`/`real`/`double`), and `jsonb` (not `json`) — the validator rejects the aliases.\n\n### Functions (serverless code)\n\nRun user code in a sandbox triggered by HTTP, cron, or webhook. The function gets the tenant connection automatically via injected env.\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_functions_deploy` | Deploy a function from source. | `{ project_id, name: \"send_welcome_email\", runtime: \"node22\", source: \"export default async (req) => { ... }\", trigger: { type: \"http\" } }` |\n| `amba_functions_list` | List functions. | `{ project_id }` |\n| `amba_functions_get` | Read function metadata. | `{ project_id, function_id }` |\n| `amba_functions_get_logs` | Recent invocation logs. | `{ project_id, function_id, limit: 100 }` |\n| `amba_functions_delete` | Delete a function. | `{ project_id, function_id }` |\n| `amba_functions_schedule` | Attach a cron schedule. | `{ project_id, function_id, cron: \"0 9 * * *\", timezone: \"America/Los_Angeles\" }` |\n| `amba_functions_pause_schedule` | Pause a scheduled trigger without deleting it. | `{ project_id, function_id }` |\n| `amba_functions_resume_schedule` | Resume. | `{ project_id, function_id }` |\n| `amba_functions_trigger_schedule` | Fire a scheduled function ad-hoc (testing). | `{ project_id, function_id }` |\n| `amba_function_domains_attach` | Attach one exact hostname to one function; returns DNS validation instructions. | `{ project_id, name: \"feed\", hostname: \"feeds.example.com\" }` |\n| `amba_function_domains_list` | List provider-neutral hostname, ownership, and certificate status. | `{ project_id, name: \"feed\" }` |\n| `amba_function_domains_refresh` | Re-poll DNS ownership and certificate state. | `{ project_id, name: \"feed\", hostname: \"feeds.example.com\" }` |\n| `amba_function_domains_remove` | Detach an exact function hostname. | `{ project_id, name: \"feed\", hostname: \"feeds.example.com\" }` |\n\nFunction-domain routing preserves the complete incoming path and query string.\nIt is exact-host only (no wildcard/path rewrite and no automatic `www` for a\nsubdomain). Podcast/feed clients cannot attach an Amba API key, so their\nfunction must be deployed with `public: true` and validate any private token\ninside the handler. Effective-tier caps are free 1, pro 5, scale 20, and\nenterprise/comped 50; attach is limited to five attempts per project per hour.\nUnverified claims become eligible for reclaim after 24 hours, and routing\nresources are allocated only after ownership is active. Every hostname response\nincludes an unconditional `dns_note`: publish a real provider-stored CNAME;\nALIAS, ANAME, and copied A/AAAA addresses are not\nsubstitutes. Treat a hostname as ready only when `live=true`, never from TLS or\n`cert_status=active` alone.\n\n### AI prompts\n\nManaged LLM templates: a stored prompt with provider + model + system message, invoked by name from the SDK. The actual LLM call is rewritten server-side per-tenant — the customer's provider API key (Anthropic / OpenAI / Mistral / Gemini) stays server-side, never on the device.\n\n**Two steps, in order:** first register the provider key with `amba_ai_providers_set`, then create prompts against it. A prompt registered before its provider has a key still saves, but invocations fail with `provider_not_configured` (424) until the key is set.\n\n> The provider key is **not** a function secret. `amba_secrets_set` writes function-scoped Worker secrets, which the AI gateway never reads. Provider keys live in a separate gateway-owned store and are set **only** via `amba_ai_providers_set`.\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_ai_providers_set` | Register / rotate the upstream provider API key. **Do this first.** | `{ project_id, provider: \"anthropic\", api_key: \"sk-ant-...\" }` |\n| `amba_ai_providers_list` | List registered providers (`configured` = key set). | `{ project_id }` |\n| `amba_ai_providers_delete` | Revoke a provider key (fails if prompts still reference it). | `{ project_id, provider: \"anthropic\" }` |\n| `amba_ai_prompts_create` | Create a prompt template. `client_invokable: true` lets the device SDK invoke it directly. | `{ project_id, name: \"summarize\", provider: \"anthropic\", model: \"claude-opus-4-5\", system_prompt: \"Summarize the user's text in 2 sentences.\", client_invokable: true }` |\n| `amba_ai_prompts_list` | List prompts. | `{ project_id }` |\n| `amba_ai_prompts_get` | Read one prompt. | `{ project_id, name }` |\n| `amba_ai_prompts_update` | Edit a prompt (replaces all fields; bumps version). | `{ project_id, name, provider, model, system_prompt: \"...\" }` |\n| `amba_ai_prompts_invoke` | Invoke by name server-side (admin testing; works with `client_invokable: false`). Uses the named gateway path, so the prompt budget, rate limit, token cap, and spend attribution are enforced. | `{ project_id, name, messages: [{ role: \"user\", content: \"...\" }] }` |\n| `amba_ai_prompts_delete` | Delete. | `{ project_id, name }` |\n\n### Analytics + events + sessions\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_analytics_get` | Top-level metrics dashboard (MAU, DAU, retention). | `{ project_id, period: \"7d\" }` |\n| `amba_events_list` | Browse raw events. | `{ project_id, limit: 100, since: \"2026-05-19T00:00:00Z\" }` |\n| `amba_events_count` | Count events matching a filter. | `{ project_id, event: \"workout_completed\", since: \"...\" }` |\n| `amba_sessions_list` | List user sessions. | `{ project_id, limit: 50 }` |\n| `amba_sessions_analytics` | Session-level metrics. | `{ project_id, period: \"7d\" }` |\n| `amba_users_list_events` | Per-user event history. | `{ project_id, user_id }` |\n| `amba_users_export` | Export the full user list. | `{ project_id, format: \"csv\" }` |\n\n### Secrets + configs + integrations\n\nSecrets here become environment bindings on deployed functions. Omit `function`\nfor a project-wide secret or pass it to scope the value to one function. Setting\nor rotating a secret queues an asynchronous update for already-deployed\nfunctions; later deployments reconcile the binding too. They are NOT where AI\nprovider keys go (use `amba_ai_providers_set` for those — see AI prompts above).\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_secrets_set` | Set or rotate a function secret; omit `function` for project-wide scope or pass it for one function. Already-deployed functions receive it asynchronously. | `{ project_id, name: \"STRIPE_WEBHOOK_SECRET\", value: \"whsec_...\" }` |\n| `amba_secrets_get` | Read a secret (returns `\"<redacted>\"` unless explicitly requested). | `{ project_id, name }` |\n| `amba_secrets_list` | List secret names. | `{ project_id }` |\n| `amba_secrets_delete` | Delete. | `{ project_id, name }` |\n| `amba_configs_create` | Create a runtime config value (read from SDK as `Amba.config.fetch()`). | `{ project_id, key: \"primary_color\", value: \"#ff0066\", segment_id: null }` |\n| `amba_configs_list` | List configs. | `{ project_id }` |\n| `amba_configs_update` | Edit. | `{ project_id, config_id, value: \"...\" }` |\n| `amba_configs_delete` | Delete. | `{ project_id, config_id }` |\n| `amba_integrations_list` | List third-party integrations. | `{ project_id }` |\n| `amba_integrations_configure` | Configure a provider. | `{ project_id, provider: \"revenuecat\", config: { webhook_secret: \"...\", default_offering: \"...\" } }` |\n| `amba_integrations_set` | Set/replace integration config wholesale. | `{ project_id, provider, config }` |\n| `amba_integrations_patch` | Patch one field. | `{ project_id, provider, patch: { webhook_secret: \"...\" } }` |\n| `amba_integrations_test` | Send a test event to a configured provider. | `{ project_id, provider }` |\n\n### Media (file storage + CDN)\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_media_upload` | Upload a file (returns a tenant-scoped URL). | `{ project_id, name: \"logo.png\", content_type: \"image/png\", data: \"<base64>\" }` |\n| `amba_media_list` | List files. | `{ project_id, folder: \"/\", limit: 100 }` |\n| `amba_media_delete` | Delete a file. | `{ project_id, file_id }` |\n| `amba_media_create_folder` | Create a logical folder. | `{ project_id, path: \"/uploads/avatars\" }` |\n| `amba_media_list_folders` | List folders. | `{ project_id }` |\n| `amba_media_delete_folder` | Delete a folder (must be empty). | `{ project_id, path }` |\n\n### Sites (static asset hosting)\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_sites_deploy` | Deploy a static site bundle (zip / tar). | `{ project_id, name: \"marketing\", bundle: \"<base64>\", index: \"index.html\" }` |\n| `amba_sites_list` | List sites. | `{ project_id }` |\n| `amba_sites_get` | Read a site. | `{ project_id, site_id }` |\n| `amba_sites_add_domain` | Attach a custom domain. | `{ project_id, site_id, domain: \"marketing.example.com\" }` |\n| `amba_sites_list_domains` | List domains on a site. | `{ project_id, site_id }` |\n| `amba_sites_remove_domain` | Detach a domain. | `{ project_id, site_id, domain }` |\n| `amba_sites_delete` | Delete a site. | `{ project_id, site_id }` |\n\n### Purchased domains + email forwarding\n\n| Tool | Purpose | Example args |\n| --- | --- | --- |\n| `amba_domains_search` | Search available domains (free). | `{ project_id, query: \"myapp\" }` |\n| `amba_domains_check` | Check authoritative price + availability. | `{ project_id, domains: [\"myapp.com\"] }` |\n| `amba_domains_purchase` | Quote, then confirm, a domain purchase. | `{ project_id, domain: \"myapp.com\", site: \"marketing\" }` |\n| `amba_domains_list` | List purchased domains. | `{ project_id }` |\n| `amba_domains_email_enable` | Enable inbound routing when no MX conflict exists. | `{ project_id, domain: \"myapp.com\" }` |\n| `amba_domains_email_destinations_add` | Add a destination mailbox; returns action-required until verified. | `{ project_id, domain: \"myapp.com\", email: \"owner@example.net\" }` |\n| `amba_domains_email_destinations_get` | Poll destination verification. | `{ project_id, domain: \"myapp.com\", destination_id }` |\n| `amba_domains_email_forwards_set` | Create/update a literal forward. | `{ project_id, domain: \"myapp.com\", source: \"support\", destination: \"owner@example.net\" }` |\n| `amba_domains_email_forwards_list` | List literal forwards. | `{ project_id, domain: \"myapp.com\" }` |\n| `amba_domains_email_forwards_delete` | Delete a literal forward. | `{ project_id, domain: \"myapp.com\", forward_id }` |\n| `amba_domains_email_catch_all_set` | Enable/update/disable catch-all. | `{ project_id, domain: \"myapp.com\", enabled: true, destination: \"owner@example.net\" }` |\n| `amba_domains_email_catch_all_get` | Read catch-all state. | `{ project_id, domain: \"myapp.com\" }` |\n\n## SDK init per stack\n\n`Amba.configure(...)` runs first. The infrastructure surfaces — collections, AI, config, flags, events — are SDK-side reads; the snippets below show what the client calls look like.\n\n### Expo / React Native\n\n```tsx\nimport { Amba } from '@layers/amba-expo';\n\n// Collections — typed table, user-scoped reads + writes\ntype Todo = { id: string; title: string; done: boolean; created_at: string };\n\nconst { data: todos } = await Amba.collections.find<Todo>('todos', {\n  filter: Amba.collections.where.eq('done', false),\n  order: [{ column: 'created_at', direction: 'desc' }],\n  limit: 50,\n});\n\nconst newTodo = await Amba.collections.insert('todos', { title: 'Ship the app', done: false });\nawait Amba.collections.update('todos', newTodo.id, { done: true });\nawait Amba.collections.delete('todos', newTodo.id);\n\n// AI — call a managed prompt (prompt_slug names the registered prompt)\nconst response = await Amba.ai.anthropic.messages.create({\n  prompt_slug: 'summarize',\n  variables: { text: 'A long article about backend services …' },\n});\n\n// Track an analytics event\nawait Amba.events.track('button_clicked', { button: 'cta' });\n\n// Read runtime config\nconst config = await Amba.config.fetch();\n\n// Read a feature flag\nconst showBeta = await Amba.flags.get('beta_feature');\n\n// Diagnostics — wire-verify\nconst ping = await Amba.diagnostics.ping();\nif (!ping.ok) console.error('Amba misconfigured:', ping);\n```\n\n### Web\n\n```ts\nimport { Amba } from '@layers/amba-web';\n\nconst { data: todos } = await Amba.collections.find('todos', {\n  filter: Amba.collections.where.eq('done', false),\n  limit: 50,\n});\nawait Amba.collections.insert('todos', { title: 'Ship', done: false });\nawait Amba.events.track('page_view', { path: location.pathname });\n```\n\nWith `@layers/amba-react`:\n\n```tsx\nimport { useCollection, useFlag } from '@layers/amba-react';\n\nfunction TodoList() {\n  const { data: todos, loading, refetch } = useCollection<{ id: string; title: string }>('todos');\n  const showArchive = useFlag('archive_todos');\n  if (loading) return <Spinner />;\n  return (\n    <ul>\n      {todos?.map(t => <li key={t.id}>{t.title}</li>)}\n      {showArchive && <ArchiveButton onArchive={refetch} />}\n    </ul>\n  );\n}\n```\n\n### iOS (Swift)\n\n```swift\nimport Amba\n\nstruct Todo: Codable {\n    let id: String\n    let title: String\n    let done: Bool\n}\n\nlet response = try await Amba.collections.find(\"todos\", as: Todo.self)\n_ = try await Amba.collections.insert(\"todos\", row: [\"title\": \"Ship\", \"done\": false])\n\nlet config = try await Amba.config.fetch()\nlet showBeta = try await Amba.flags.get(name: \"beta_feature\")\ntry await Amba.events.track(\"app_opened\", properties: [\"source\": \"deep_link\"])\n\nlet reply = try await Amba.ai.anthropic.messages.create(\n    request: AiMessageRequest(promptSlug: \"summarize\", variables: [\"text\": \"A long article...\"])\n)\n```\n\n### Android (Kotlin)\n\n```kotlin\ndata class Todo(val id: String, val title: String, val done: Boolean)\n\nval todos = Amba.collections.find<Todo>(\"todos\")\nAmba.collections.insert(\"todos\", mapOf(\"title\" to \"Ship\", \"done\" to false))\n\nval config = Amba.config.fetch()\nval showBeta = Amba.flags.get(\"beta_feature\")\nAmba.events.track(\"app_opened\", mapOf(\"source\" to \"deep_link\"))\n```\n\n### Flutter\n\n```dart\nimport 'package:amba/amba.dart';\n\nfinal response = await Amba.collections.find('todos', limit: 50);\nawait Amba.collections.insert('todos', {'title': 'Ship', 'done': false});\nfinal config = await Amba.config.fetch();\nfinal showBeta = await Amba.flags.get('beta_feature');\nawait Amba.events.track('app_opened', {'source': 'deep_link'});\n```\n\n## Common follow-ups\n\nBatch.\n\n1. **Custom data tables (collections):** any domain-specific tables to create?\n   - Yes — I'll list them. (For each: name + columns + types.)\n   - No, just use the canned Amba surfaces (auth, push, gamification, etc.)\n   - Auto-create from the existing code's models — read `lib/models/`, `src/types/`, `Models/`, infer column lists, confirm with me.\n\n2. **Custom backend logic (functions):** any server-side code to deploy?\n   - Yes — describe what it should do. (Then offer to scaffold a function template and deploy.)\n   - No\n\n3. **AI features:** want managed LLM prompts?\n   - Yes — what's the use case? (summarize, translate, classify, generate, custom)\n   - No\n\n4. **Analytics:** which tracker do you want?\n   - Only Amba's built-in events (recommended — already wired)\n   - Amba + your own analytics pipeline (subscribe a webhook to project events via `amba_webhooks_create` and forward server-side)\n   - None (rarely useful — events drive XP / achievements / streaks; disabling cripples gamification)\n\n5. **Third-party integrations to set up:**\n   - [ ] RevenueCat (IAP / subscriptions on iOS + Android)\n   - [ ] Superwall (paywall A/B)\n   - [ ] Stripe Billing (web subscriptions through the app's own Stripe account — provider `stripe_billing`)\n   - [ ] OpenAI / Anthropic / Mistral / Gemini LLM keys (required for `Amba.ai.*` — set via `amba_ai_providers_set`, **not** `amba_integrations_configure`)\n\n6. **Feature flags:** seed any starter flags?\n   - Yes — wire `beta_feature` (off by default) so I can ship the wiring before the feature exists\n   - No\n\n7. **Static site:** want a marketing page hosted under your tenant subdomain?\n   - Yes — scaffold and deploy a 1-page index\n   - No\n\n## Re-run behavior\n\n1. Before creating:\n   - `amba_collections_list` — match on `name`. Collisions: never silently recreate (data loss). Offer `amba_collections_alter` to add new columns instead.\n   - `amba_functions_list` — match on `name`. Collisions: ask to redeploy (with the new source) or skip.\n   - `amba_ai_prompts_list` — match on `name`. Same. (And `amba_ai_providers_list` — match on `provider`; re-running `amba_ai_providers_set` rotates the key in place.)\n   - `amba_integrations_list` — match on `provider`. Same.\n   - `amba_configs_list` — match on `key`. Same.\n\n2. **Never call `amba_collections_delete` on re-run unless the user explicitly asks** — this drops the underlying table and every row in it across every user of the tenant.\n\n3. For functions: re-deploying replaces source in place (versioned server-side). It's safe to call `amba_functions_deploy` with the same name + new source.\n\n4. For integrations: if a provider is already configured, prefer `amba_integrations_patch` (partial update) over `amba_integrations_set` (full replace).\n\n5. Secrets: don't list secret values in chat output, even on read. Just confirm \"OPENAI_API_KEY is set\" / \"not set\".\n";
     readonly surface: "infrastructure";
     readonly title: "Amba setup — infrastructure";
     readonly description: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layers/amba-mcp",
-  "version": "4.0.7",
+  "version": "4.0.9",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22"