@layers/amba-mcp 4.0.2 → 4.0.4

package/dist/index.js

@@ -3,7 +3,7 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { z } from "zod";
-import { INTEGRATION_PROVIDERS } from "@layers/amba-shared";
+import { INTEGRATION_PROVIDERS, integrationConfigSummary } from "@layers/amba-shared";
 //#region src/auth.ts
 const CREDENTIALS_PATH = join(homedir(), ".amba", "credentials.json");
 async function loadCredentials() {
@@ -286,6 +286,236 @@ function warnDeprecatedAlias(alias, canonical) {
 	console.warn(`[amba-mcp] tool "${alias}" is deprecated; use "${canonical}" instead. The alias still works but will be removed in a future release.`);
 }
 //#endregion
+//#region src/lib/annotations.ts
+/**
+* Read-only verbs. A tool whose name contains one of these (and no
+* destructive verb) does not mutate project state — it reads/derives/
+* exports data. Maps to `readOnlyHint: true`.
+*/
+const READ_VERBS = new Set([
+	"get",
+	"list",
+	"find",
+	"describe",
+	"stats",
+	"export",
+	"analytics",
+	"me",
+	"status",
+	"count",
+	"search",
+	"check",
+	"tiers",
+	"verify",
+	"logs",
+	"query",
+	"aggregate",
+	"results"
+]);
+/**
+* Destructive verbs. A tool whose name contains one of these MAY perform
+* a destructive update (irreversible removal of existing state). Maps to
+* `destructiveHint: true`. `reset` is included because `*_reset_sandbox`
+* wipes end-user data.
+*/
+const DESTRUCTIVE_VERBS = new Set([
+	"delete",
+	"remove",
+	"revoke",
+	"drop",
+	"reset"
+]);
+/**
+* Write verbs — mutations that are additive / non-destructive (create a
+* row, update fields, grant currency, deploy a function, send a push, …).
+* Maps to `destructiveHint: false`. This set exists so a write tool that
+* matches NONE of the read/destructive verbs is still positively
+* classified (rather than falling through unannotated). Kept explicit so
+* an unrecognised verb surfaces as a test failure instead of silently
+* defaulting.
+*/
+const WRITE_VERBS = new Set([
+	"create",
+	"update",
+	"set",
+	"patch",
+	"grant",
+	"spend",
+	"deduct",
+	"deploy",
+	"send",
+	"add",
+	"configure",
+	"invoke",
+	"schedule",
+	"assign",
+	"upload",
+	"rotate",
+	"reprovision",
+	"transfer",
+	"pause",
+	"resume",
+	"trigger",
+	"evaluate",
+	"test",
+	"approve",
+	"reject",
+	"escalate",
+	"replay",
+	"import",
+	"alter",
+	"insert",
+	"invite",
+	"register",
+	"purchase",
+	"signup",
+	"login",
+	"refresh"
+]);
+/**
+* Split a tool name into lowercase verb-candidate tokens, dropping the
+* `amba_` prefix. Exported for the test suite.
+*/
+function toolNameTokens(name) {
+	return name.replace(/^amba_/, "").split("_").filter(Boolean);
+}
+/**
+* Classify a tool name into its behavioural class by PRECEDENCE
+* (destructive > read > write). Returns `null` if no token matches any
+* known verb — that should never happen for a real Amba tool and the
+* test suite asserts it doesn't, so a `null` at runtime means a new tool
+* used an unrecognised verb and needs a verb-set entry here.
+*/
+function classifyToolVerb(name) {
+	const tokens = toolNameTokens(name);
+	let sawRead = false;
+	let sawWrite = false;
+	for (const token of tokens) {
+		if (DESTRUCTIVE_VERBS.has(token)) return "destructive";
+		if (READ_VERBS.has(token)) sawRead = true;
+		else if (WRITE_VERBS.has(token)) sawWrite = true;
+	}
+	if (sawRead) return "read";
+	if (sawWrite) return "write";
+	return null;
+}
+/** Title-case a single token (`currencies` → `Currencies`). */
+function capitalize(token) {
+	return token.length === 0 ? token : token[0].toUpperCase() + token.slice(1);
+}
+/**
+* Verb-set tokens that read as nouns/objects far more often than as the
+* operation verb, so they must NOT be chosen as the title's leading verb.
+* They stay in the verb sets above for CLASSIFICATION (e.g. `*_status`,
+* `*_stats` are read-only), but for TITLE purposes they're objects:
+*
+*   amba_get_friendship_stats   → "Get Friendship Stats"  (not "Stats …")
+*   amba_pause_function_schedule→ "Pause Function Schedule" (not "Schedule …")
+*   amba_functions_get_logs     → "Get Functions Logs"
+*   amba_billing_status         → "Billing Status"  (no action verb at all)
+*   amba_sessions_analytics     → "Sessions Analytics"
+*/
+const NOUN_LIKE_VERBS = new Set([
+	"stats",
+	"status",
+	"logs",
+	"tiers",
+	"analytics",
+	"schedule",
+	"me"
+]);
+/**
+* The verbs eligible to be a title's leading word: every classification
+* verb that isn't a noun-like token. These are unambiguous action verbs
+* (`create`, `get`, `delete`, `set`, `pause`, …).
+*/
+const STRONG_TITLE_VERBS = new Set([
+	...READ_VERBS,
+	...WRITE_VERBS,
+	...DESTRUCTIVE_VERBS
+].filter((v) => !NOUN_LIKE_VERBS.has(v)));
+/**
+* Pick the index of the OPERATIVE action verb for the title, or -1 if the
+* name has no action verb (e.g. `billing_status`, `sessions_analytics`).
+*
+* A naive `tokens.find()` is wrong two different ways:
+*   - `amba_currency_grant_rules_create` has `grant` (a noun-modifier in
+*     `grant_rules`) AND `create`; `find` picks `grant` → "Grant … Create".
+*   - `amba_get_friendship_stats` has `get` AND `stats`; preferring the
+*     trailing match picks `stats` → "Stats Get Friendship".
+*
+* Amba's naming puts the operation verb at a token-list BOUNDARY: leading
+* for legacy `amba_<verb>_<resource>`, trailing/mid for canonical
+* `amba_<resource>_<verb>[_<object>]`. So:
+*   1. If the FIRST token is a strong verb → it's the operative verb
+*      (legacy alias: `get_friendship_stats`, `create_currency`).
+*   2. Else take the LAST strong verb — skips trailing object nouns like
+*      `stats`/`schedule` (excluded from `STRONG_TITLE_VERBS`) and skips
+*      mid-name noun-modifiers like `grant` in `grant_rules_create`
+*      (`get_stats`/`set_price`/`grant_rules_create` all resolve right).
+*   3. No strong verb → -1 (caller title-cases in order).
+*/
+function operativeVerbIndex(tokens) {
+	if (tokens.length > 0 && STRONG_TITLE_VERBS.has(tokens[0])) return 0;
+	let lastStrong = -1;
+	for (let i = 0; i < tokens.length; i += 1) if (STRONG_TITLE_VERBS.has(tokens[i])) lastStrong = i;
+	return lastStrong;
+}
+/**
+* Derive a human-readable Title-Case title from the tool name. The
+* operative action verb (see `operativeVerbIndex`) is moved to the front
+* so the title reads as an imperative; remaining tokens keep their order:
+*
+*   amba_currencies_create             → "Create Currencies"
+*   amba_content_delete_schedule       → "Delete Content Schedule"
+*   amba_currency_grant_rules_create   → "Create Currency Grant Rules"
+*   amba_get_friendship_stats          → "Get Friendship Stats"
+*   amba_pause_function_schedule       → "Pause Function Schedule"
+*   amba_catalog_items_set_price       → "Set Catalog Items Price"
+*   amba_users_get                     → "Get Users"
+*
+* When there is no action verb (`billing_status`, `sessions_analytics`)
+* the tokens are title-cased in order — a readable noun-phrase fallback.
+*/
+function deriveToolTitle(name) {
+	const tokens = toolNameTokens(name);
+	const idx = operativeVerbIndex(tokens);
+	if (idx >= 0) {
+		const rest = tokens.filter((_, i) => i !== idx);
+		return [tokens[idx], ...rest].map(capitalize).join(" ");
+	}
+	return tokens.map(capitalize).join(" ");
+}
+/**
+* Derive the full `ToolAnnotations` (title + read-only/destructive hints)
+* for a tool name. This is the single function `with-pat.ts` calls for
+* every tool it registers, so annotations stay uniform and automatic.
+*/
+function deriveToolAnnotations(name) {
+	const title = deriveToolTitle(name);
+	switch (classifyToolVerb(name)) {
+		case "read": return {
+			title,
+			readOnlyHint: true
+		};
+		case "destructive": return {
+			title,
+			readOnlyHint: false,
+			destructiveHint: true
+		};
+		case "write": return {
+			title,
+			readOnlyHint: false,
+			destructiveHint: false
+		};
+		default: return {
+			title,
+			readOnlyHint: false,
+			destructiveHint: true
+		};
+	}
+}
+//#endregion
 //#region src/lib/with-pat.ts
 /**
 * The `pat` schema entry injected into every tool that goes through
@@ -362,8 +592,8 @@ function registerTool(server, apiClient, name, description, schema, handler, ali
 			client
 		});
 	};
-	server.tool(name, description, extendedSchema, wrappedHandler(name));
-	for (const alias of aliases) server.tool(alias, description, extendedSchema, (async (rawArgs) => {
+	server.tool(name, description, extendedSchema, deriveToolAnnotations(name), wrappedHandler(name));
+	for (const alias of aliases) server.tool(alias, description, extendedSchema, deriveToolAnnotations(alias), (async (rawArgs) => {
 		warnDeprecatedAlias(alias, name);
 		return wrappedHandler(name)(rawArgs);
 	}));
@@ -375,15 +605,15 @@ function registerTool(server, apiClient, name, description, schema, handler, ali
 * should go through `registerTool`.
 */
 function registerPublicTool(server, name, description, schema, handler, aliases = []) {
-	server.tool(name, description, schema, handler);
-	for (const alias of aliases) server.tool(alias, description, schema, (async (args) => {
+	server.tool(name, description, schema, deriveToolAnnotations(name), handler);
+	for (const alias of aliases) server.tool(alias, description, schema, deriveToolAnnotations(alias), (async (args) => {
 		warnDeprecatedAlias(alias, name);
 		return handler(args);
 	}));
 }
 //#endregion
 //#region src/tools/projects.ts
-function registerTools$25(server, apiClient) {
+function registerTools$33(server, apiClient) {
 	registerTool(server, apiClient, "amba_projects_list", "List all Amba projects owned by the authenticated developer. Returns project id, name, bundle_id, platform, and environment.", {}, async (_, { client }) => {
 		const result = await client.get("/projects");
 		return { content: [{
@@ -490,7 +720,7 @@ function registerTools$25(server, apiClient) {
 }
 //#endregion
 //#region src/tools/push.ts
-function registerTools$24(server, apiClient) {
+function registerTools$32(server, apiClient) {
 	registerTool(server, apiClient, "amba_push_campaigns_create", "Create a new push notification campaign for a project. The campaign starts in \"draft\" status. You can optionally target a segment and schedule delivery.", {
 		project_id: z.string().describe("The project ID"),
 		title: z.string().describe("Push notification title shown to the user"),
@@ -620,7 +850,7 @@ const segmentRulesSchema = z.object({
 	operator: z.enum(["AND", "OR"]).describe("Logical operator combining conditions"),
 	conditions: z.array(segmentConditionSchema).describe("Array of filter conditions")
 });
-function registerTools$23(server, apiClient) {
+function registerTools$31(server, apiClient) {
 	registerTool(server, apiClient, "amba_segments_list", "List user segments for a project. Segments define groups of users based on rules (e.g. \"active in last 7 days\", \"premium users\"). Returns only project-custom segments by default. Pass include_system: true to also include the built-in system segments (e.g. \"all\", \"active_7d\", \"premium\").", {
 		project_id: z.string().describe("The project ID"),
 		include_system: z.boolean().optional().describe("Include built-in system segments in the result. Defaults to false.")
@@ -705,8 +935,8 @@ const configConditionSchema = z.object({
 	percentage: z.number().optional().describe("Percentage rollout (0-100)"),
 	value: z.unknown().describe("Override value for this condition")
 });
-function registerTools$22(server, apiClient) {
-	registerTool(server, apiClient, "amba_configs_list", "List remote-config keys for a project. Returns key, value, value_type, description, conditions, and version per active row. Remote config lets you change app behavior without deploying an update. Returns only project-created config keys by default. Pass include_system: true to also include platform-provided defaults (e.g. app_version_min, maintenance_mode).", {
+function registerTools$30(server, apiClient) {
+	registerTool(server, apiClient, "amba_remote_configs_list", "List remote-config keys for a project. Returns key, value, value_type, description, conditions, and version per active row. Remote config lets you change app behavior without deploying an update. Returns only project-created config keys by default. Pass include_system: true to also include platform-provided defaults (e.g. app_version_min, maintenance_mode).", {
 		project_id: z.string().describe("The project ID"),
 		include_system: z.boolean().optional().describe("Include platform-provided default config keys in the result. Defaults to false.")
 	}, async ({ project_id, include_system }, { client }) => {
@@ -717,8 +947,8 @@ function registerTools$22(server, apiClient) {
 			type: "text",
 			text: JSON.stringify(result, null, 2)
 		}] };
-	}, ["amba_list_configs"]);
-	registerTool(server, apiClient, "amba_configs_create", "Create or upsert a remote-config key. Supports string, number, boolean, and JSON value types. Can include segment-based or percentage-based conditions for targeted rollouts. The handler is upsert-on-key — calling this for an existing key replaces it.", {
+	}, ["amba_configs_list", "amba_list_configs"]);
+	registerTool(server, apiClient, "amba_remote_configs_create", "Create or upsert a remote-config key. Supports string, number, boolean, and JSON value types. Can include segment-based or percentage-based conditions for targeted rollouts. The handler is upsert-on-key — calling this for an existing key replaces it.", {
 		project_id: z.string().describe("The project ID"),
 		key: z.string().describe("Config key name (e.g. \"feature_paywall_v2\", \"daily_limit\")"),
 		value: z.unknown().describe("The default config value"),
@@ -743,8 +973,8 @@ function registerTools$22(server, apiClient) {
 			type: "text",
 			text: JSON.stringify(result, null, 2)
 		}] };
-	}, ["amba_create_config"]);
-	registerTool(server, apiClient, "amba_configs_update", "Partially update a single remote-config key. Only fields provided are touched — other fields are preserved. Updating `value` bumps the per-row version counter; any successful mutation also recomputes the singleton config_versions hash so cached clients see the change.", {
+	}, ["amba_configs_create", "amba_create_config"]);
+	registerTool(server, apiClient, "amba_remote_configs_update", "Partially update a single remote-config key. Only fields provided are touched — other fields are preserved. Updating `value` bumps the per-row version counter; any successful mutation also recomputes the singleton config_versions hash so cached clients see the change.", {
 		project_id: z.string().describe("The project ID"),
 		key: z.string().describe("The config key to update"),
 		value: z.unknown().optional().describe("New default value (omit to leave unchanged)"),
@@ -760,8 +990,8 @@ function registerTools$22(server, apiClient) {
 			type: "text",
 			text: JSON.stringify(result, null, 2)
 		}] };
-	}, ["amba_update_config"]);
-	registerTool(server, apiClient, "amba_configs_delete", "Delete a remote-config key. Idempotent — deleting a non-existent key returns success. Recomputes the config_versions hash so clients refresh cached config on next fetch.", {
+	}, ["amba_configs_update", "amba_update_config"]);
+	registerTool(server, apiClient, "amba_remote_configs_delete", "Delete a remote-config key. Idempotent — deleting a non-existent key returns success. Recomputes the config_versions hash so clients refresh cached config on next fetch.", {
 		project_id: z.string().describe("The project ID"),
 		key: z.string().describe("The config key to delete")
 	}, async ({ project_id, key }, { client }) => {
@@ -770,7 +1000,7 @@ function registerTools$22(server, apiClient) {
 			type: "text",
 			text: JSON.stringify(result, null, 2)
 		}] };
-	}, ["amba_delete_config"]);
+	}, ["amba_configs_delete", "amba_delete_config"]);
 }
 //#endregion
 //#region src/tools/content.ts
@@ -783,8 +1013,8 @@ const contentItemSchema = z.object({
 	metadata: z.record(z.unknown()).optional().describe("Arbitrary metadata key-value pairs"),
 	is_premium: z.boolean().optional().describe("Whether this content requires a premium entitlement")
 });
-function registerTools$21(server, apiClient) {
-	registerTool(server, apiClient, "amba_content_libraries_create", "Create a content library for a project. A content library is a collection of content items (tips, quotes, articles) that can be delivered on a schedule to keep users engaged.", {
+function registerTools$29(server, apiClient) {
+	registerTool(server, apiClient, "amba_content_libraries_create", "Create a content library for a project. A content library is a collection of content items (tips, quotes, articles) that can be delivered on a schedule to keep users engaged. The library `name` IS the channel handle the in-app SDK uses: `Amba.content.library(name)` reads this library (names are unique). The response echoes it as `channel`.", {
 		project_id: z.string().describe("The project ID"),
 		name: z.string().describe("Library name (e.g. \"Daily Motivation\", \"Workout Tips\")"),
 		description: z.string().optional().describe("Description of the library content"),
@@ -799,6 +1029,17 @@ function registerTools$21(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	}, ["amba_create_content_library"]);
+	registerTool(server, apiClient, "amba_content_libraries_delete", "Delete a content library. A library with items is refused unless cascade=true, which deletes the library and ALL its items, schedules, and deliveries in one call (irreversible). Use this to clean up orphan libraries instead of deleting items one at a time.", {
+		project_id: z.string().describe("The project ID"),
+		library_id: z.string().describe("The content library ID to delete"),
+		cascade: z.boolean().optional().describe("Required to delete a non-empty library. When true, deletes the library and all its items, schedules, and deliveries. Defaults to false (a non-empty library returns 409 LIBRARY_NOT_EMPTY).")
+	}, async ({ project_id, library_id, cascade }, { client }) => {
+		const result = await client.delete(`/projects/${project_id}/content/libraries/${library_id}`, cascade ? { cascade: "true" } : void 0);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
 	registerTool(server, apiClient, "amba_content_items_add", "Add one or more content items to an existing content library. Items can include text, media URLs, categories, tags, and metadata.", {
 		project_id: z.string().describe("The project ID"),
 		library_id: z.string().describe("The content library ID"),
@@ -842,7 +1083,7 @@ function registerTools$21(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	}, ["amba_create_content_schedule"]);
-	registerTool(server, apiClient, "amba_content_list_libraries", "List content libraries for a project.", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
+	registerTool(server, apiClient, "amba_content_list_libraries", "List content libraries for a project. Each library exposes `channel` (= name) — the handle the in-app SDK passes to `Amba.content.library(channel)` (and `Amba.content.today(scheduleName)` for scheduled rotations).", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
 		const result = await client.get(`/projects/${project_id}/content/libraries`);
 		return { content: [{
 			type: "text",
@@ -947,7 +1188,7 @@ function registerTools$21(server, apiClient) {
 }
 //#endregion
 //#region src/tools/streaks.ts
-function registerTools$20(server, apiClient) {
+function registerTools$28(server, apiClient) {
 	registerTool(server, apiClient, "amba_streaks_create", "Create a streak definition for a project. Streaks track consecutive user engagement (e.g. daily logins, workout completions). Supports configurable periods, grace periods, and freeze mechanics.", {
 		project_id: z.string().describe("The project ID"),
 		key: z.string().regex(/^[a-z0-9_-]{1,64}$/).optional().describe("Stable identifier used by the SDK to qualify a streak without knowing its UUID: `Amba.streaks.qualify(\"daily_login\")`. Lowercase letters, digits, underscore, hyphen, 1-64 characters. Immutable after creation — changing it breaks live SDK calls. When omitted the server derives one from `name`."),
@@ -1021,15 +1262,29 @@ function registerTools$20(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
+	registerTool(server, apiClient, "amba_streaks_reset", "Reset or correct a specific user's streak — for support fixing a wrongly-broken streak (e.g. after an outage). Sets the user's current count and marks the streak active again. Omit set_count to zero the streak (clean restart); pass set_count to restore it to a specific value (longest_count is bumped if exceeded). Returns 404 if the user has no streak row for this definition yet.", {
+		project_id: z.string().describe("The project ID"),
+		streak_id: z.string().describe("The streak definition ID"),
+		app_user_id: z.string().describe("The user whose streak to reset"),
+		set_count: z.number().int().nonnegative().optional().describe("Restore the streak to this count. Omit to zero the streak (clean restart).")
+	}, async ({ project_id, streak_id, app_user_id, set_count }, { client }) => {
+		const payload = { app_user_id };
+		if (set_count !== void 0) payload.set_count = set_count;
+		const result = await client.post(`/projects/${project_id}/streaks/${streak_id}/reset`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
 }
 //#endregion
 //#region src/tools/integrations.ts
 const providerEnum = z.enum(INTEGRATION_PROVIDERS);
-function registerTools$19(server, apiClient) {
-	registerTool(server, apiClient, "amba_integrations_configure", "Configure (create or replace) a third-party integration for a project. Supported providers: \"apns\" (Apple Push), \"fcm\" (Firebase Cloud Messaging), \"revenuecat\" (subscription management), \"superwall\" (paywall management). Each provider requires specific config fields.", {
+function registerTools$27(server, apiClient) {
+	registerTool(server, apiClient, "amba_integrations_configure", "Configure (create or replace) a third-party integration for a project. Supported providers: \"apns\" (Apple Push), \"fcm\" (Firebase Cloud Messaging), \"revenuecat\" (subscription management), \"superwall\" (paywall management). Each provider requires specific config fields. Push credentials (.p8 / service-account JSON) are passed inline here and stored server-side automatically — no separate secrets step.", {
 		project_id: z.string().describe("The project ID"),
 		provider: providerEnum.describe("Integration provider name"),
-		config: z.record(z.unknown()).describe("Provider-specific configuration. For APNs: { key_id, team_id, bundle_id, key_p8 }. For FCM: { service_account_json }. For RevenueCat: { api_key, webhook_secret }. For Superwall: { api_key }.")
+		config: z.record(z.unknown()).describe("Provider-specific configuration. " + integrationConfigSummary())
 	}, async ({ project_id, provider, config }, { client }) => {
 		const result = await client.post(`/projects/${project_id}/integrations`, {
 			provider,
@@ -1095,7 +1350,7 @@ const PERIOD_DAYS = {
 	"30d": "30",
 	"90d": "90"
 };
-function registerTools$18(server, apiClient) {
+function registerTools$26(server, apiClient) {
 	registerTool(server, apiClient, "amba_analytics_get", "Get daily analytics for a project. Returns per-day event counts and unique-user counts for the requested window, plus totals. Use this to verify that end-to-end event tracking is working after seeding and testing.", {
 		project_id: z.string().describe("The project ID"),
 		period: z.enum([
@@ -1118,7 +1373,7 @@ function registerTools$18(server, apiClient) {
 }
 //#endregion
 //#region src/tools/users.ts
-function registerTools$17(server, apiClient) {
+function registerTools$25(server, apiClient) {
 	registerTool(server, apiClient, "amba_users_list", "List app users for a project. Supports pagination with offset and limit, plus optional search (matches email / external_id / display_name with ILIKE) and segment filter. Returns user profiles including external_id, email, display_name, properties, and activity timestamps.", {
 		project_id: z.string().describe("The project ID"),
 		limit: z.number().optional().describe("Maximum number of users to return (default 50)"),
@@ -1137,6 +1392,30 @@ function registerTools$17(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	}, ["amba_list_users"]);
+	registerTool(server, apiClient, "amba_users_create", "Admin-create an app user from the developer/agent side. Use this to mint a system/seed user to attribute migrated rows to — e.g. after amba_users_reset_sandbox wiped everyone. All fields are optional; with no fields it mints an anonymous user. Collisions on external_id/anonymous_id/email return 409 USER_ALREADY_EXISTS.", {
+		project_id: z.string().describe("The project ID"),
+		external_id: z.string().optional().describe("Your stable external identifier for this user (unique). Optional."),
+		anonymous_id: z.string().optional().describe("Anonymous device id (unique). Optional; auto-generated if no identity given."),
+		email: z.string().optional().describe("Email address. Optional."),
+		phone: z.string().optional().describe("Phone number. Optional."),
+		display_name: z.string().optional().describe("Display name. Optional."),
+		avatar_url: z.string().optional().describe("Avatar URL. Optional."),
+		properties: z.record(z.unknown()).optional().describe("Arbitrary user properties (JSON object). Optional.")
+	}, async ({ project_id, external_id, anonymous_id, email, phone, display_name, avatar_url, properties }, { client }) => {
+		const payload = {};
+		if (external_id !== void 0) payload.external_id = external_id;
+		if (anonymous_id !== void 0) payload.anonymous_id = anonymous_id;
+		if (email !== void 0) payload.email = email;
+		if (phone !== void 0) payload.phone = phone;
+		if (display_name !== void 0) payload.display_name = display_name;
+		if (avatar_url !== void 0) payload.avatar_url = avatar_url;
+		if (properties !== void 0) payload.properties = properties;
+		const result = await client.post(`/projects/${project_id}/users`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	}, ["amba_create_user"]);
 	registerTool(server, apiClient, "amba_users_get", "Get a single app user by id, with their streaks and entitlements joined in.", {
 		project_id: z.string().describe("The project ID"),
 		user_id: z.string().describe("The app user ID")
@@ -1396,12 +1675,18 @@ println("Current streak: \${streak.currentCount}")`,
 // For Expo apps, use @layers/amba-expo instead.
 import { Amba } from '@layers/amba-react-native';
 
-// Configure once at app startup
+// Configure once at app startup. The first authenticated call lazily
+// establishes an anonymous session, so reads work without a manual sign-in.
+// Call signInAnonymously() explicitly if you want to control when the
+// anonymous user is created.
 await Amba.configure({
   projectId: 'YOUR_PROJECT_ID',
-  apiKey: 'YOUR_CLIENT_API_KEY',
+  clientKey: 'YOUR_CLIENT_API_KEY',
 });
 
+// Optional — establish the session up front instead of lazily:
+// await Amba.auth.signInAnonymously();
+
 // Track events
 await Amba.events.track('workout_completed', {
   duration_minutes: 30,
@@ -1423,9 +1708,11 @@ import { Amba } from '@layers/amba-expo';
 
 export default function RootLayout() {
   useEffect(() => {
-    Amba.configure({
+    // configure() is async. Reads lazily establish an anonymous session on the
+    // first authenticated call, so no manual sign-in is required to start.
+    void Amba.configure({
       projectId: process.env.EXPO_PUBLIC_AMBA_PROJECT_ID!,
-      apiKey: 'YOUR_CLIENT_API_KEY',
+      clientKey: 'YOUR_CLIENT_API_KEY',
     });
   }, []);
 
@@ -1491,7 +1778,7 @@ final dailyLimit = await Amba.config.get<int>('daily_limit', defaultValue: 10);
 final streak = await Amba.streaks.get('daily_login');
 print('Current streak: \${streak.currentCount}');`
 };
-function registerTools$16(server, apiClient) {
+function registerTools$24(server, apiClient) {
 	registerTool(server, apiClient, "amba_sdk_get_setup_instructions", "Get platform-specific code snippets and setup instructions for integrating the Amba client SDK into a mobile app. Supports iOS (Swift), Android (Kotlin), React Native, Expo, and Flutter.", { platform: z.enum([
 		"ios",
 		"android",
@@ -1547,7 +1834,7 @@ function registerTools$16(server, apiClient) {
 				"1. Replace YOUR_CLIENT_API_KEY with your project's client API key (find it with amba_projects_get)",
 				"2. Configure push notification integration (APNs for iOS, FCM for Android) using amba_integrations_configure",
 				"3. Create segments to target user groups with amba_segments_create",
-				"4. Set up remote config values with amba_configs_create",
+				"4. Set up remote config values with amba_remote_configs_create",
 				"5. Create streaks to track user engagement with amba_streaks_create",
 				"",
 				"## Content delivery loop (worked example — DX-12)",
@@ -1576,7 +1863,7 @@ const criteriaSchema = z.object({
 	property_key: z.string().optional().describe("User property key (required for property_value type)"),
 	target_value: z.number().describe("Target value to unlock the achievement")
 });
-function registerTools$15(server, apiClient) {
+function registerTools$23(server, apiClient) {
 	registerTool(server, apiClient, "amba_achievements_create", "Create an achievement/badge definition. Achievements unlock automatically when users meet the criteria (e.g. track 5 workouts, reach a 7-day streak, earn 5000 XP). Can optionally award bonus XP on unlock.", {
 		project_id: z.string().describe("The project ID"),
 		key: z.string().describe("Unique key for this achievement (e.g. \"first_workout\", \"streak_master_7\")"),
@@ -1656,10 +1943,32 @@ function registerTools$15(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	}, ["amba_delete_achievement"]);
+	registerTool(server, apiClient, "amba_achievements_grant", "Manually award an achievement to a specific user (marks it unlocked now). For support, promos, or corrections — the rest of the achievement surface only defines criteria the system evaluates automatically. Idempotent: re-granting an already-unlocked achievement keeps the original unlock time. Note: this does NOT auto-award the achievement's xp_reward; award XP separately with amba_xp_grant if intended.", {
+		project_id: z.string().describe("The project ID"),
+		achievement_id: z.string().describe("The achievement definition ID"),
+		app_user_id: z.string().describe("The user to award the achievement to")
+	}, async ({ project_id, achievement_id, app_user_id }, { client }) => {
+		const result = await client.post(`/projects/${project_id}/achievements/${achievement_id}/grant`, { app_user_id });
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_achievements_revoke", "Claw back an achievement from a specific user — the inverse of grant. Removes the user's unlock entirely. Returns 404 if the user does not currently hold the achievement.", {
+		project_id: z.string().describe("The project ID"),
+		achievement_id: z.string().describe("The achievement definition ID"),
+		app_user_id: z.string().describe("The user to revoke the achievement from")
+	}, async ({ project_id, achievement_id, app_user_id }, { client }) => {
+		const result = await client.post(`/projects/${project_id}/achievements/${achievement_id}/revoke`, { app_user_id });
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
 }
 //#endregion
 //#region src/tools/challenges.ts
-function registerTools$14(server, apiClient) {
+function registerTools$22(server, apiClient) {
 	registerTool(server, apiClient, "amba_challenges_create", "Create a time-limited challenge. Challenges are events that run between start_at and end_at, where users try to reach a goal (e.g. track 10 workouts this week, earn 500 XP in 3 days). Can reward XP and/or unlock an achievement on completion.", {
 		project_id: z.string().describe("The project ID"),
 		name: z.string().describe("Challenge name (e.g. \"7-Day Fitness Sprint\", \"XP Weekend Blitz\")"),
@@ -1770,7 +2079,7 @@ function registerTools$14(server, apiClient) {
 }
 //#endregion
 //#region src/tools/economy.ts
-function registerTools$13(server, apiClient) {
+function registerTools$21(server, apiClient) {
 	registerTool(server, apiClient, "amba_currencies_create", "Create a virtual currency for a project. Currencies can be soft (earned through gameplay) or premium (purchased with real money). Supports auto-recharge for time-gated mechanics like hearts/energy.", {
 		project_id: z.string().describe("The project ID"),
 		code: z.string().describe("Unique currency code (e.g. \"gold\", \"gems\", \"hearts\")"),
@@ -1805,25 +2114,48 @@ function registerTools$13(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	}, ["amba_list_currencies"]);
-	registerTool(server, apiClient, "amba_currencies_grant", "Grant virtual currency to a specific user. Useful for rewards, promotions, or admin adjustments.", {
+	registerTool(server, apiClient, "amba_currencies_grant", "Grant virtual currency to a specific user. Useful for rewards, promotions, or admin adjustments. Pass idempotency_key to make a grant exactly-once: a repeat with the same key for the same (user, currency) returns the original transaction (HTTP 200, idempotent_replay:true) without re-applying — e.g. encode `share:{userId}:{yyyy-mm-dd}` to cap \"one per share per day\" without a guard collection.", {
 		project_id: z.string().describe("The project ID"),
 		app_user_id: z.string().describe("The user to grant currency to"),
 		currency_code: z.string().describe("Currency code (e.g. \"gold\")"),
 		amount: z.number().describe("Amount to grant (positive integer)"),
-		reason: z.string().optional().describe("Reason for the grant (for audit trail)")
-	}, async ({ project_id, app_user_id, currency_code, amount, reason }, { client }) => {
+		reason: z.string().optional().describe("Reason for the grant (for audit trail)"),
+		idempotency_key: z.string().optional().describe("Dedup key (≤255 chars). A repeat with the same key for this (user, currency) returns the original grant without re-applying. The key is permanent — encode the window into it (e.g. include the date for once-per-day).")
+	}, async ({ project_id, app_user_id, currency_code, amount, reason, idempotency_key }, { client }) => {
 		const payload = {
 			app_user_id,
 			currency_code,
 			amount
 		};
 		if (reason !== void 0) payload.reason = reason;
+		if (idempotency_key !== void 0) payload.idempotency_key = idempotency_key;
 		const result = await client.post(`/projects/${project_id}/currencies/grant`, payload);
 		return { content: [{
 			type: "text",
 			text: JSON.stringify(result, null, 2)
 		}] };
 	}, ["amba_grant_currency"]);
+	registerTool(server, apiClient, "amba_currencies_spend", "Debit virtual currency from a specific user. Atomic — returns 400 INSUFFICIENT_FUNDS if the balance is too low (no partial debit). Use for in-app purchases priced in soft currency, gameplay consumes, or admin adjustments. The amount parameter is positive; the ledger records the spend as a negative delta automatically. Pass idempotency_key to make a debit exactly-once: a repeat with the same key returns the original debit (HTTP 200, idempotent_replay:true) without double-charging.", {
+		project_id: z.string().describe("The project ID"),
+		app_user_id: z.string().describe("The user to debit currency from"),
+		currency_code: z.string().describe("Currency code (e.g. \"gold\")"),
+		amount: z.number().describe("Positive amount to debit. The endpoint records this as a negative delta on the ledger."),
+		reason: z.string().optional().describe("Reason for the spend (stored as reference_id, useful for the audit trail)"),
+		idempotency_key: z.string().optional().describe("Dedup key (≤255 chars). A repeat with the same key for this (user, currency) returns the original debit without double-charging. A spend that failed with INSUFFICIENT_FUNDS stores no key, so retrying it is allowed.")
+	}, async ({ project_id, app_user_id, currency_code, amount, reason, idempotency_key }, { client }) => {
+		const payload = {
+			app_user_id,
+			currency_code,
+			amount
+		};
+		if (reason !== void 0) payload.reason = reason;
+		if (idempotency_key !== void 0) payload.idempotency_key = idempotency_key;
+		const result = await client.post(`/projects/${project_id}/currencies/spend`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
 	registerTool(server, apiClient, "amba_currency_grant_rules_create", "Create a rule that automatically grants virtual currency when a specific event is tracked. Supports flat-amount grants and property-scaled grants (e.g. points per minute). Optional daily cap prevents farming.", {
 		project_id: z.string().describe("The project ID"),
 		currency_key: z.string().describe("Currency code to grant (e.g. \"calm_points\")"),
@@ -1978,6 +2310,23 @@ function registerTools$13(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	}, ["amba_grant_item"]);
+	registerTool(server, apiClient, "amba_inventory_revoke_item", "Remove a catalog item from a user's inventory — the inverse of grant. Decrements the held quantity; returns 400 INSUFFICIENT_QUANTITY if you try to revoke more than the user holds, and 404 if they don't hold the item at all. Revoking down to zero removes the holding entirely.", {
+		project_id: z.string().describe("The project ID"),
+		app_user_id: z.string().describe("The user to remove the item from"),
+		catalog_item_id: z.string().describe("The catalog item ID to revoke"),
+		quantity: z.number().optional().describe("Quantity to revoke (default 1)")
+	}, async ({ project_id, app_user_id, catalog_item_id, quantity }, { client }) => {
+		const payload = {
+			app_user_id,
+			catalog_item_id
+		};
+		if (quantity !== void 0) payload.quantity = quantity;
+		const result = await client.post(`/projects/${project_id}/inventory/revoke`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
 	registerTool(server, apiClient, "amba_users_get_inventory", "View a user's inventory including all owned items and quantities.", {
 		project_id: z.string().describe("The project ID"),
 		app_user_id: z.string().describe("The user ID to look up")
@@ -2266,8 +2615,8 @@ function registerTools$13(server, apiClient) {
 }
 //#endregion
 //#region src/tools/leaderboards.ts
-function registerTools$12(server, apiClient) {
-	registerTool(server, apiClient, "amba_leaderboards_create", "Create a leaderboard definition. Leaderboards rank users by XP, streak length, or a custom metric. Supports all-time, daily, weekly, and monthly periods with configurable max entries.", {
+function registerTools$20(server, apiClient) {
+	registerTool(server, apiClient, "amba_leaderboards_create", "Create a leaderboard definition. Leaderboards rank users by XP, streak length, or a custom metric. Supports all-time, daily, weekly, and monthly periods with configurable max entries. The returned `key` (which equals `name`) is the exact value the in-app SDK passes to `Amba.leaderboards.getEntries(key)` / `getRank(key)`.", {
 		project_id: z.string().describe("The project ID"),
 		name: z.string().describe("Leaderboard name (e.g. \"Top XP Earners\", \"Weekly Streak Leaders\")"),
 		metric: z.enum([
@@ -2312,7 +2661,7 @@ function registerTools$12(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	}, ["amba_get_leaderboard"]);
-	registerTool(server, apiClient, "amba_leaderboards_list", "List all leaderboard definitions for a project. Returns name, metric, period, and max_entries per leaderboard. (Use `amba_leaderboards_get` to fetch ranked entries for a specific leaderboard.)", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
+	registerTool(server, apiClient, "amba_leaderboards_list", "List all leaderboard definitions for a project. Returns `key` (= name, the handle the in-app SDK `leaderboards.getEntries(key)` expects), name, metric, period, and max_entries per leaderboard. (Use `amba_leaderboards_get` to fetch ranked entries for a specific leaderboard.)", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
 		const result = await client.get(`/projects/${project_id}/leaderboards`);
 		return { content: [{
 			type: "text",
@@ -2371,8 +2720,80 @@ function registerTools$12(server, apiClient) {
 	}, ["amba_delete_leaderboard"]);
 }
 //#endregion
+//#region src/tools/leagues.ts
+/**
+* Leagues — the Duolingo-style promote/demote tiers (Bronze/Silver/Gold/…).
+* Distinct from leaderboards (a single ranked list): a league has weekly
+* cohorts that the rollover workflow reshuffles. These tools provision and
+* inspect leagues; the admin routes are mounted at
+* `/v1/admin/projects/:projectId/leagues`. Members are assigned by the weekly
+* rollover (the registered Temporal schedule) and score live off `xp_awarded`
+* engagement events.
+*/
+function registerTools$19(server, apiClient) {
+	registerTool(server, apiClient, "amba_leagues_create", "Create a league tier (e.g. \"Bronze\", tier_order=1). Leagues are the promote/demote ladder: each week users are grouped into cohorts of `cohort_size`, the top `promote_count` move up a tier and the bottom `demote_count` move down. Create one league per tier (lowest tier_order = entry tier). Members are assigned by the weekly rollover, not at create time.", {
+		project_id: z.string().describe("The project ID"),
+		name: z.string().describe("League tier name, e.g. \"Bronze\", \"Silver\", \"Gold\""),
+		tier_order: z.number().describe("Tier rank, 1 = lowest/entry tier. Higher tiers have higher tier_order."),
+		promote_count: z.number().optional().describe("How many top members of a cohort promote each week (default 5)"),
+		demote_count: z.number().optional().describe("How many bottom members of a cohort demote each week (default 5)"),
+		cohort_size: z.number().optional().describe("Target members per weekly cohort (default 30)")
+	}, async ({ project_id, name, tier_order, promote_count, demote_count, cohort_size }, { client }) => {
+		const payload = {
+			name,
+			tier_order
+		};
+		if (promote_count !== void 0) payload.promote_count = promote_count;
+		if (demote_count !== void 0) payload.demote_count = demote_count;
+		if (cohort_size !== void 0) payload.cohort_size = cohort_size;
+		const result = await client.post(`/projects/${project_id}/leagues`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	}, ["amba_create_league"]);
+	registerTool(server, apiClient, "amba_leagues_list", "List all league tiers for a project, ordered by tier. Returns name, tier_order, promote_count, demote_count, and cohort_size per league.", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/leagues`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	}, ["amba_list_leagues"]);
+	registerTool(server, apiClient, "amba_leagues_update", "Partially update a league tier. Only the supplied fields change. `tier_order` is intentionally immutable (re-ranking mid-week would require re-cohorting every active membership).", {
+		project_id: z.string().describe("The project ID"),
+		league_id: z.string().describe("The league ID"),
+		name: z.string().optional().describe("New tier name"),
+		promote_count: z.number().optional().describe("New weekly promote count"),
+		demote_count: z.number().optional().describe("New weekly demote count"),
+		cohort_size: z.number().optional().describe("New target cohort size"),
+		is_active: z.boolean().optional().describe("Enable/disable the tier")
+	}, async ({ project_id, league_id, name, promote_count, demote_count, cohort_size, is_active }, { client }) => {
+		const payload = {};
+		if (name !== void 0) payload.name = name;
+		if (promote_count !== void 0) payload.promote_count = promote_count;
+		if (demote_count !== void 0) payload.demote_count = demote_count;
+		if (cohort_size !== void 0) payload.cohort_size = cohort_size;
+		if (is_active !== void 0) payload.is_active = is_active;
+		const result = await client.patch(`/projects/${project_id}/leagues/${league_id}`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	}, ["amba_update_league"]);
+	registerTool(server, apiClient, "amba_leagues_list_cohorts", "List this week's active cohorts for a league, each with a member_count. Cohorts (and their memberships) are created by the weekly rollover — a freshly created league shows no cohorts until the first rollover runs.", {
+		project_id: z.string().describe("The project ID"),
+		league_id: z.string().describe("The league ID")
+	}, async ({ project_id, league_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/leagues/${league_id}/cohorts/current`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	}, ["amba_list_league_cohorts"]);
+}
+//#endregion
 //#region src/tools/platform.ts
-function registerTools$11(server, apiClient) {
+function registerTools$18(server, apiClient) {
 	registerTool(server, apiClient, "amba_onboarding_create", "Create an onboarding flow for a project. Onboarding flows define step-by-step experiences for new users (e.g. welcome screens, permission prompts, feature tours).", {
 		project_id: z.string().describe("The project ID"),
 		name: z.string().describe("Flow name (e.g. \"Welcome Flow\", \"Premium Onboarding\")"),
@@ -2791,6 +3212,44 @@ function registerTools$11(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
+	registerTool(server, apiClient, "amba_messaging_create_conversation", "Create a conversation server-side. Unlike the client path, this allows ZERO or more initial participants — a matchmaker can create an empty circle then populate it over time. Returns the new conversation row.", {
+		project_id: z.string().describe("The project ID"),
+		type: z.enum(["direct", "group"]).optional().describe("Conversation type. Defaults to \"group\"."),
+		name: z.string().optional().describe("Optional conversation name (group conversations)."),
+		participant_ids: z.array(z.string()).optional().describe("Initial participant app_user IDs. May be empty or omitted.")
+	}, async ({ project_id, type, name, participant_ids }, { client }) => {
+		const payload = {};
+		if (type !== void 0) payload.type = type;
+		if (name !== void 0) payload.name = name;
+		if (participant_ids !== void 0) payload.participant_ids = participant_ids;
+		const result = await client.post(`/projects/${project_id}/messaging/conversations`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_messaging_add_participant", "Add a user to an existing conversation (idempotent). The matchmaker primitive: as each user qualifies for a circle, add them to its conversation so they can read, send, and receive messages. Re-adding an existing member is a no-op.", {
+		project_id: z.string().describe("The project ID"),
+		conversation_id: z.string().describe("The conversation ID"),
+		user_id: z.string().describe("The app_user ID to add")
+	}, async ({ project_id, conversation_id, user_id }, { client }) => {
+		const result = await client.post(`/projects/${project_id}/messaging/conversations/${conversation_id}/participants`, { user_id });
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_messaging_remove_participant", "Remove a user from a conversation (idempotent inverse of add). Removing a non-member returns removed: false.", {
+		project_id: z.string().describe("The project ID"),
+		conversation_id: z.string().describe("The conversation ID"),
+		user_id: z.string().describe("The app_user ID to remove")
+	}, async ({ project_id, conversation_id, user_id }, { client }) => {
+		const result = await client.delete(`/projects/${project_id}/messaging/conversations/${conversation_id}/participants/${user_id}`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
 	registerTool(server, apiClient, "amba_messaging_list_conversations", "List message conversations for a project, newest first. Pagination via limit+offset.", {
 		project_id: z.string().describe("The project ID"),
 		limit: z.number().optional().describe("Max results to return (default 50)"),
@@ -2910,7 +3369,7 @@ function registerTools$11(server, apiClient) {
 }
 //#endregion
 //#region src/tools/social.ts
-function registerTools$10(server, apiClient) {
+function registerTools$17(server, apiClient) {
 	registerTool(server, apiClient, "amba_friendships_get_stats", "Get friendship statistics for a project. Returns total friendships, pending requests, accepted friendships, and blocked count.", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
 		const result = await client.get(`/projects/${project_id}/friends/stats`);
 		return { content: [{
@@ -3235,7 +3694,7 @@ function registerTools$10(server, apiClient) {
 }
 //#endregion
 //#region src/tools/xp.ts
-function registerTools$9(server, apiClient) {
+function registerTools$16(server, apiClient) {
 	registerTool(server, apiClient, "amba_xp_rules_create", "Create an XP rule that auto-awards XP when a matching engagement event is tracked. For example, award 50 XP every time a user completes a workout, with optional daily caps and cooldowns.", {
 		project_id: z.string().describe("The project ID"),
 		name: z.string().describe("Rule name (e.g. \"Workout Completed\", \"Daily Login Bonus\")"),
@@ -3307,6 +3766,40 @@ function registerTools$9(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
+	registerTool(server, apiClient, "amba_xp_grant", "Directly add XP to a user's total — for rewards, promos, or support corrections. This is a manual adjustment: it does NOT replay rule side-effects (level-up events, achievement re-evaluation) the way event-driven XP does. The user's displayed level is still recomputed from the new total. The amount is a positive magnitude; the ledger records it as a positive delta.", {
+		project_id: z.string().describe("The project ID"),
+		app_user_id: z.string().describe("The user to grant XP to"),
+		amount: z.number().describe("Positive amount of XP to add"),
+		reason: z.string().optional().describe("Reason for the grant (stored on the ledger row for the audit trail)")
+	}, async ({ project_id, app_user_id, amount, reason }, { client }) => {
+		const payload = {
+			app_user_id,
+			amount
+		};
+		if (reason !== void 0) payload.reason = reason;
+		const result = await client.post(`/projects/${project_id}/xp/grant`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_xp_deduct", "Directly subtract XP from a user's total — the inverse of grant. Atomic: returns 400 INSUFFICIENT_XP if the deduction would drive the total below zero (no partial deduct). Like grant, this is a manual adjustment that does NOT replay rule side-effects. The amount is a positive magnitude; the ledger records it as a negative delta.", {
+		project_id: z.string().describe("The project ID"),
+		app_user_id: z.string().describe("The user to deduct XP from"),
+		amount: z.number().describe("Positive amount of XP to subtract"),
+		reason: z.string().optional().describe("Reason for the deduction (stored on the ledger row for the audit trail)")
+	}, async ({ project_id, app_user_id, amount, reason }, { client }) => {
+		const payload = {
+			app_user_id,
+			amount
+		};
+		if (reason !== void 0) payload.reason = reason;
+		const result = await client.post(`/projects/${project_id}/xp/deduct`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
 	registerTool(server, apiClient, "amba_xp_list_users", "List users by total XP (leaderboard view). Ordered by total_xp descending with pagination.", {
 		project_id: z.string().describe("The project ID"),
 		limit: z.number().optional().describe("Max results to return (default 50)"),
@@ -3324,7 +3817,7 @@ function registerTools$9(server, apiClient) {
 }
 //#endregion
 //#region src/tools/events.ts
-function registerTools$8(server, apiClient) {
+function registerTools$15(server, apiClient) {
 	registerTool(server, apiClient, "amba_events_list", "List engagement events for a project (most recent first) with cursor pagination on (occurred_at, id). Defaults to the last 24 hours when `since` is omitted. Pass `next_cursor` from a previous page back as `cursor` to continue.", {
 		project_id: z.string().describe("The project ID"),
 		since: z.string().optional().describe("ISO-8601 lower bound for occurred_at. Defaults to 24h ago."),
@@ -3366,57 +3859,176 @@ function registerTools$8(server, apiClient) {
 	});
 }
 //#endregion
-//#region src/lib/tool-result.ts
-/**
-* Shared MCP tool result helpers.
-*
-* Every tool emits the same `{ content: [{ type: 'text', text: <json> }] }`
-* envelope. Two helpers centralize that:
-*
-*   - [`jsonResult`] — wraps an arbitrary payload.
-*   - [`passthroughResult`] — flattens an upstream HTTP response
-*     (status + parsed body) into the same envelope. Status is written
-*     LAST so a colliding top-level `status` field in the API response
-*     cannot shadow the HTTP status — agents look at `parsed.status` to
-*     distinguish 2xx from 4xx/5xx.
-*
-* Lives in `src/lib/` (vs. `src/tools/_helpers.ts`) to set the same
-* cross-cutting-helper precedent as `src/lib/with-pat.ts` (task #36).
-* `tools/*` files stay strictly tool registrations.
-*/
-/**
-* Wire-shape every MCP tool handler returns.
-*
-* The MCP SDK's `tool()` callback signature is structurally typed and
-* carries an open index signature for `_meta` etc. Declaring our return
-* type as a plain `{ content: [...] }` interface won't satisfy that
-* structural check — so the helpers' return type is left as the actual
-* inferred shape (no explicit interface) and consumers rely on the
-* inference + the SDK's structural compatibility. If we ever want a
-* named alias, write it as a type-alias over the inferred shape rather
-* than a closed interface.
-*/
-/** Wrap an arbitrary payload as a JSON-text tool result. */
-function jsonResult$1(payload) {
-	return { content: [{
-		type: "text",
-		text: JSON.stringify(payload, null, 2)
-	}] };
-}
-/**
-* Flatten an upstream HTTP response into the agent-facing tool payload.
-* Body fields are spread FIRST so a future top-level `status` key in
-* the API response cannot shadow the HTTP `status` — agents read
-* `parsed.status` to distinguish 2xx from 4xx/5xx.
-*/
-function passthroughResult(result) {
-	return jsonResult$1({
-		...result.body ?? {},
-		status: result.status
-	});
-}
-//#endregion
-//#region src/tools/auth.ts
+//#region src/tools/funnels.ts
+const funnelFilterSchema = z.object({
+	property: z.string().describe("Dot-path into the event `properties` JSON (e.g. \"source\" or \"plan.tier\")."),
+	op: z.enum([
+		"eq",
+		"neq",
+		"gt",
+		"gte",
+		"lt",
+		"lte",
+		"contains",
+		"not_contains",
+		"exists",
+		"not_exists"
+	]).describe("Comparison operator. exists/not_exists ignore `value`."),
+	value: z.union([
+		z.string(),
+		z.number(),
+		z.boolean()
+	]).optional().describe("Scalar to compare against. Required for every op except exists/not_exists.")
+});
+const funnelStepSchema = z.object({
+	event: z.string().describe("Event name to match (engagement event_name)."),
+	filters: z.array(funnelFilterSchema).optional().describe("Optional property predicates, ANDed together, that an event must satisfy.")
+});
+function registerTools$14(server, apiClient) {
+	registerTool(server, apiClient, "amba_funnels_list", "List conversion funnels for a project. A funnel is a saved, ordered sequence of steps (event + optional property filters) plus a conversion window. Returns the definitions only — use amba_funnels_query to compute per-step counts.", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/funnels`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_funnels_create", [
+		"Create a conversion funnel definition. Steps are ORDERED: a user is credited with",
+		"step N only if they emitted step N after their matched step N-1, all within the",
+		"conversion window measured from their first step-0 event. conversion_window_seconds",
+		"defaults to 604800 (7 days). Needs at least 2 steps."
+	].join(" "), {
+		project_id: z.string().describe("The project ID"),
+		name: z.string().describe("Funnel name (unique per project)."),
+		description: z.string().optional().describe("Human-readable description."),
+		steps: z.array(funnelStepSchema).describe("Ordered steps (2-10). Each step is an event + optional property filters."),
+		conversion_window_seconds: z.number().int().optional().describe("Conversion window in seconds (60 .. 7776000). Defaults to 604800 (7 days).")
+	}, async ({ project_id, name, description, steps, conversion_window_seconds }, { client }) => {
+		const payload = {
+			name,
+			steps
+		};
+		if (description !== void 0) payload.description = description;
+		if (conversion_window_seconds !== void 0) payload.conversion_window_seconds = conversion_window_seconds;
+		const result = await client.post(`/projects/${project_id}/funnels`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_funnels_get", "Get a single funnel definition by id (name, ordered steps, conversion window).", {
+		project_id: z.string().describe("The project ID"),
+		funnel_id: z.string().describe("The funnel ID")
+	}, async ({ project_id, funnel_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/funnels/${funnel_id}`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_funnels_update", "Update a funnel's name, description, steps, and/or conversion window. Only the provided fields change; steps (when supplied) replace the whole ordered list.", {
+		project_id: z.string().describe("The project ID"),
+		funnel_id: z.string().describe("The funnel ID"),
+		name: z.string().optional().describe("New funnel name."),
+		description: z.string().nullable().optional().describe("New description; pass null to clear."),
+		steps: z.array(funnelStepSchema).optional().describe("Replacement ordered step list (2-10)."),
+		conversion_window_seconds: z.number().int().optional().describe("New conversion window in seconds (60 .. 7776000).")
+	}, async ({ project_id, funnel_id, name, description, steps, conversion_window_seconds }, { client }) => {
+		const payload = {};
+		if (name !== void 0) payload.name = name;
+		if (description !== void 0) payload.description = description;
+		if (steps !== void 0) payload.steps = steps;
+		if (conversion_window_seconds !== void 0) payload.conversion_window_seconds = conversion_window_seconds;
+		const result = await client.patch(`/projects/${project_id}/funnels/${funnel_id}`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_funnels_delete", "Delete a funnel definition by id.", {
+		project_id: z.string().describe("The project ID"),
+		funnel_id: z.string().describe("The funnel ID")
+	}, async ({ project_id, funnel_id }, { client }) => {
+		const result = await client.delete(`/projects/${project_id}/funnels/${funnel_id}`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_funnels_query", [
+		"Compute a funnel: per-step distinct-user counts, conversion rates, and drop-off over",
+		"an entry date range. `from`/`to` (ISO-8601) bound which step-0 events count as funnel",
+		"entries (default: last 30 days). Each entrant then has their own conversion window in",
+		"which later steps must occur (it may extend past `to`). Returns total_entered,",
+		"total_converted, overall_conversion_rate, and a per-step breakdown."
+	].join(" "), {
+		project_id: z.string().describe("The project ID"),
+		funnel_id: z.string().describe("The funnel ID"),
+		from: z.string().optional().describe("ISO-8601 lower bound for funnel entries. Defaults to 30 days ago."),
+		to: z.string().optional().describe("ISO-8601 upper bound for funnel entries. Defaults to now.")
+	}, async ({ project_id, funnel_id, from, to }, { client }) => {
+		const query = {};
+		if (from !== void 0) query.from = from;
+		if (to !== void 0) query.to = to;
+		const result = await client.get(`/projects/${project_id}/funnels/${funnel_id}/query`, query);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+}
+//#endregion
+//#region src/lib/tool-result.ts
+/**
+* Shared MCP tool result helpers.
+*
+* Every tool emits the same `{ content: [{ type: 'text', text: <json> }] }`
+* envelope. Two helpers centralize that:
+*
+*   - [`jsonResult`] — wraps an arbitrary payload.
+*   - [`passthroughResult`] — flattens an upstream HTTP response
+*     (status + parsed body) into the same envelope. Status is written
+*     LAST so a colliding top-level `status` field in the API response
+*     cannot shadow the HTTP status — agents look at `parsed.status` to
+*     distinguish 2xx from 4xx/5xx.
+*
+* Lives in `src/lib/` (vs. `src/tools/_helpers.ts`) to set the same
+* cross-cutting-helper precedent as `src/lib/with-pat.ts` (task #36).
+* `tools/*` files stay strictly tool registrations.
+*/
+/**
+* Wire-shape every MCP tool handler returns.
+*
+* The MCP SDK's `tool()` callback signature is structurally typed and
+* carries an open index signature for `_meta` etc. Declaring our return
+* type as a plain `{ content: [...] }` interface won't satisfy that
+* structural check — so the helpers' return type is left as the actual
+* inferred shape (no explicit interface) and consumers rely on the
+* inference + the SDK's structural compatibility. If we ever want a
+* named alias, write it as a type-alias over the inferred shape rather
+* than a closed interface.
+*/
+/** Wrap an arbitrary payload as a JSON-text tool result. */
+function jsonResult$1(payload) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(payload, null, 2)
+	}] };
+}
+/**
+* Flatten an upstream HTTP response into the agent-facing tool payload.
+* Body fields are spread FIRST so a future top-level `status` key in
+* the API response cannot shadow the HTTP `status` — agents read
+* `parsed.status` to distinguish 2xx from 4xx/5xx.
+*/
+function passthroughResult(result) {
+	return jsonResult$1({
+		...result.body ?? {},
+		status: result.status
+	});
+}
+//#endregion
+//#region src/tools/auth.ts
 async function authFetch(apiClient, options) {
 	const url = `${apiClient.getApiRoot()}${options.path}`;
 	const headers = { Accept: "application/json" };
@@ -3538,7 +4150,7 @@ function enrichedAuthResult(result, agentInstructions) {
 		status: result.status
 	});
 }
-function registerTools$7(server, apiClient) {
+function registerTools$13(server, apiClient) {
 	registerPublicTool(server, "amba_developer_signup", [
 		"Create a new Amba developer account. Returns a long-lived Personal Access Token (PAT)",
 		"plus a real isolated Amba project (provisioning asynchronously), plus ready-to-paste",
@@ -3672,6 +4284,18 @@ async function adminFetch(apiClient, options) {
 		body
 	};
 }
+const CATALOG_SHAPE_KEYS = [
+	"is_published",
+	"published_at",
+	"is_public",
+	"published"
+];
+function catalogShapeWarning(row) {
+	const hit = CATALOG_SHAPE_KEYS.filter((k) => k in row);
+	if (hit.length === 0) return null;
+	const ownership = "user_id" in row ? `attributed to user_id "${String(row["user_id"])}"` : "attributed to the seeding user (or rejected if the collection requires user_id)";
+	return [`⚠️ This row has catalog-shaped column(s) [${hit.join(", ")}] but is being inserted into a per-user collection, so it will be ${ownership} — other users will NOT see it via the client SDK.`, "If this is shared/global content (a catalog, articles, a media library), use a Content Library (amba_content_libraries_create) or create the collection with shared:true so its rows are readable by every user. Proceeding anyway."].join(" ");
+}
 async function clientFetch(apiClient, options) {
 	let url = `${apiClient.getApiRoot()}/client${options.path}`;
 	if (options.query && Object.keys(options.query).length > 0) url += `?${new URLSearchParams(options.query).toString()}`;
@@ -3709,7 +4333,7 @@ const MISSING_API_KEY_ERROR = jsonResult$1({
 });
 const columnSchema = z.object({
 	name: z.string().describe("Column name. Must match /^[a-z][a-z0-9_]*$/."),
-	type: z.string().describe("Column type. One of: text, integer, bigint, boolean, jsonb, timestamptz, uuid, numeric, real, double, vector. Vector columns require a \"dimensions\" hint."),
+	type: z.string().describe("Column type. One of: text, integer, bigint, boolean, jsonb, timestamptz, date, uuid, numeric, vector, or an array type (text[], integer[], bigint[], numeric[], boolean[], uuid[]). Array columns support the contains/containedBy/overlaps query operators. Vector columns require a \"dimensions\" hint."),
 	nullable: z.boolean().optional().describe("Whether the column accepts NULL. Defaults to true."),
 	default: z.unknown().optional().describe("Default SQL literal (e.g. \"NOW()\", 0, \"''\"). Optional."),
 	dimensions: z.number().optional().describe("Required for `vector` columns; ignored otherwise.")
@@ -3735,7 +4359,7 @@ const sdkOrderSchema = z.array(z.object({
 })).describe("Ordering. `[{column: \"created_at\", direction: \"desc\"}, ...]`.");
 const adminFindWhereSchema = z.unknown().describe("Server WhereClause shape: column-keyed FieldOps, e.g. {tag: {eq: \"x\"}, count: {gte: 5}} plus optional `and|or|not` combinators.");
 const setSchema = z.record(z.unknown()).describe("Column-value map. Server-managed columns (id, created_at, etc.) are rejected.");
-function registerTools$6(server, apiClient) {
+function registerTools$12(server, apiClient) {
 	registerTool(server, apiClient, "amba_collections_create", [
 		"Create a new collection (schema-first Postgres table) in a project.",
 		"The DDL is emitted server-side and applied via a Temporal saga.",
@@ -3746,13 +4370,15 @@ function registerTools$6(server, apiClient) {
 		project_id: z.string().describe("The project ID owning the collection."),
 		name: z.string().describe("Collection name. Must match /^[a-z][a-z0-9_]*$/. Reserved prefixes (amba_, coll_amba_) are rejected."),
 		columns: z.array(columnSchema).describe("Column definitions. Server adds id/user_id/created_at/updated_at/deleted_at."),
-		indexes: z.array(indexSchema).optional().describe("Optional extra indexes (server creates a primary key + user_id index by default).")
-	}, async ({ project_id, name, columns, indexes }, { pat }) => {
+		indexes: z.array(indexSchema).optional().describe("Optional extra indexes (server creates a primary key + user_id index by default)."),
+		shared: z.boolean().optional().describe("Set true for developer-seeded GLOBAL content not owned by any single user (question banks, content libraries, lookup tables). Makes user_id NULLABLE so rows can be inserted without a user_id. Defaults to false (every row requires a user_id).")
+	}, async ({ project_id, name, columns, indexes, shared }, { pat }) => {
 		const body = {
 			name,
 			columns
 		};
 		if (indexes !== void 0) body.indexes = indexes;
+		if (shared !== void 0) body.shared = shared;
 		return passthroughResult(await adminFetch(apiClient, {
 			method: "POST",
 			path: `/projects/${project_id}/collections`,
@@ -3810,22 +4436,39 @@ function registerTools$6(server, apiClient) {
 		}));
 	}, ["amba_delete_collection"]);
 	registerTool(server, apiClient, "amba_collections_alter", [
-		"Alter a collection: exactly one of `add_column`, `add_index`, or `drop_column` per call (the underlying saga is built around one SQL blob per workflow).",
+		"Alter a collection: exactly one of `add_column`, `add_index`, `change_type`, `rename_column`, `drop_column`, or `relax_user_id` per call (the underlying saga is built around one SQL blob per workflow).",
 		"Drop-column is destructive — requires `confirm` to equal the dropped column name.",
+		"change_type changes an existing column to a new type. It REWRITES THE WHOLE TABLE under an exclusive lock — the collection is briefly unreadable/unwritable while it runs, so prefer low-traffic windows for large collections. Casts that are not trivially safe (e.g. text→integer) require a `using` cast expression; known-safe casts (anything→text, integer→bigint, integer/bigint→numeric) do not. Without a `using` for an unsafe cast you get a 400 up front rather than a mid-migration failure.",
+		"rename_column renames a column (metadata-only, fast). It BREAKS any app code referencing the old name — re-run `amba types generate` and update call sites afterward. The new name can’t collide with a server-managed column (id, user_id, created_at, updated_at, deleted_at) or a reserved query keyword (and, or, not).",
+		"relax_user_id converts an EXISTING collection to shared (drops the user_id NOT NULL so global rows can be inserted) — the post-hoc equivalent of creating it with shared:true.",
 		"Authenticates as the developer/agent — pass `pat` or send as inbound Bearer.",
-		"Errors: 400 INVALID_PATCH if not exactly one operation, 400 CONFIRMATION_REQUIRED on drop_column without matching confirm."
+		"Errors: 400 INVALID_PATCH if not exactly one operation, 400 CONFIRMATION_REQUIRED on drop_column without matching confirm, 400 INVALID_COLLECTION_SCHEMA on an unsafe change_type cast or a reserved rename target, 400 COLLECTION_MIGRATION_FAILED if the cast fails at apply time."
 	].join(" "), {
 		project_id: z.string().describe("The project ID."),
 		name: z.string().describe("Collection name to alter."),
-		add_column: columnSchema.optional().describe("Column to add. Mutually exclusive with add_index / drop_column."),
-		add_index: indexSchema.optional().describe("Index to add. Mutually exclusive with add_column / drop_column."),
+		add_column: columnSchema.optional().describe("Column to add. Mutually exclusive with the other alter operations."),
+		add_index: indexSchema.optional().describe("Index to add. Mutually exclusive with the other alter operations."),
+		change_type: z.object({
+			column: z.string().describe("Existing column to change."),
+			to_type: z.string().describe("Target type (text, integer, bigint, numeric, boolean, timestamptz, date, jsonb, uuid)."),
+			from_type: z.string().optional().describe("Optional current type. When provided, known-safe widening casts (integer→bigint, integer/bigint→numeric) skip the `using` requirement."),
+			using: z.string().optional().describe("SQL cast expression for the USING clause, e.g. \"score::integer\". Required for casts that are not trivially safe; omit only for anything→text or a known-safe widening cast.")
+		}).optional().describe("Change a column’s type. REWRITES THE WHOLE TABLE under an exclusive lock (briefly unreadable/unwritable). Mutually exclusive with the other alter operations."),
+		rename_column: z.object({
+			from: z.string().describe("Current column name."),
+			to: z.string().describe("New column name. Must match /^[a-z][a-z0-9_]*$/.")
+		}).optional().describe("Rename a column (metadata-only, fast). BREAKS code referencing the old name — re-run `amba types generate` afterward. Mutually exclusive with the other alter operations."),
 		drop_column: z.string().optional().describe("Column name to drop. Requires `confirm` query param to match."),
+		relax_user_id: z.boolean().optional().describe("Set true to drop the user_id NOT NULL constraint so this collection can hold shared/global rows (NULL user_id). Mutually exclusive with the other operations."),
 		confirm: z.string().optional().describe("Required when drop_column is set; must equal the column name.")
-	}, async ({ project_id, name, add_column, add_index, drop_column, confirm }, { pat }) => {
+	}, async ({ project_id, name, add_column, add_index, change_type, rename_column, drop_column, relax_user_id, confirm }, { pat }) => {
 		const body = {};
 		if (add_column !== void 0) body.add_column = add_column;
 		if (add_index !== void 0) body.add_index = add_index;
+		if (change_type !== void 0) body.change_type = change_type;
+		if (rename_column !== void 0) body.rename_column = rename_column;
 		if (drop_column !== void 0) body.drop_column = drop_column;
+		if (relax_user_id !== void 0) body.relax_user_id = relax_user_id;
 		const query = {};
 		if (drop_column !== void 0 && confirm !== void 0) query.confirm = confirm;
 		return passthroughResult(await adminFetch(apiClient, {
@@ -3839,23 +4482,67 @@ function registerTools$6(server, apiClient) {
 	registerTool(server, apiClient, "amba_admin_insert_row", [
 		"Insert a row directly into a collection from the developer/agent side — BYPASSES auto-RLS.",
 		"Server-managed columns (id, created_at, updated_at, deleted_at) are stripped from the body. `user_id` is honored if present (admins can create rows attributed to any app_user).",
+		"Atomic upsert: pass on_conflict=\"ignore\" (return the existing row, no change) or \"update\" (merge) plus conflict_target (the unique-index columns). Replaces read-then-write races.",
 		"Authenticates as the developer/agent — pass `pat` or send as inbound Bearer.",
-		"Errors: 400 INVALID_COLUMN, 404 COLLECTION_NOT_FOUND, 500 CREATE_FAILED."
+		"Errors: 400 INVALID_COLUMN / INVALID_CONFLICT_TARGET, 404 COLLECTION_NOT_FOUND, 500 CREATE_FAILED."
 	].join(" "), {
 		project_id: z.string().describe("The project ID."),
 		name: z.string().describe("Collection name."),
-		row: z.record(z.unknown()).describe("Column-value map for the new row. Server-managed columns are stripped.")
-	}, async ({ project_id, name, row }, { pat }) => {
-		return passthroughResult(await adminFetch(apiClient, {
+		row: z.record(z.unknown()).describe("Column-value map for the new row. Server-managed columns are stripped."),
+		on_conflict: z.enum([
+			"error",
+			"ignore",
+			"update"
+		]).optional().describe("Conflict policy. \"error\" (default) fails on a unique-constraint clash; \"ignore\" returns the existing row (HTTP 200) unchanged; \"update\" merges the provided columns. Requires conflict_target."),
+		conflict_target: z.array(z.string()).optional().describe("Columns that form the unique index to conflict on (e.g. [\"user_id\",\"kind\"]). Required when on_conflict is \"ignore\" or \"update\"."),
+		return_minimal: z.boolean().optional().describe("When true, the response returns only the inserted row id instead of the full row. Use this for rows with large columns (big JSON blobs) to avoid bloating the response — essential for bulk migrations where echoing full rows exhausts the token budget.")
+	}, async ({ project_id, name, row, on_conflict, conflict_target, return_minimal }, { pat }) => {
+		const query = {};
+		if (on_conflict !== void 0) query.on_conflict = on_conflict;
+		if (conflict_target !== void 0) query.conflict_target = conflict_target.join(",");
+		if (return_minimal) query.return = "minimal";
+		const result = await adminFetch(apiClient, {
 			method: "POST",
 			path: `/projects/${project_id}/collections/${encodeURIComponent(name)}/rows`,
 			body: row,
+			query: Object.keys(query).length > 0 ? query : void 0,
+			bearer: pat
+		});
+		const warning = catalogShapeWarning(row);
+		const base = passthroughResult(result);
+		if (warning) base.content.unshift({
+			type: "text",
+			text: warning
+		});
+		return base;
+	});
+	registerTool(server, apiClient, "amba_admin_insert_rows", [
+		"Bulk-insert up to 500 rows into a collection in a single atomic statement — BYPASSES auto-RLS.",
+		"Use for developer-seeded data (question banks, content libraries, lookup tables); far faster than calling amba_admin_insert_row in a loop.",
+		"Server-managed columns (id, created_at, updated_at, deleted_at) are stripped per row; `user_id` is honored if present. Rows may be sparse — a column absent from a row is inserted as NULL.",
+		"on_conflict \"error\" (default) aborts the whole batch on any conflict; \"skip\" emits ON CONFLICT DO NOTHING and reports how many rows were skipped.",
+		"Authenticates as the developer/agent — pass `pat` or send as inbound Bearer.",
+		"Errors: 400 BATCH_TOO_LARGE (>500) / INVALID_COLUMN / NOT_NULL_VIOLATION, 404 COLLECTION_NOT_FOUND, 409 CONFLICT (on_conflict:\"error\")."
+	].join(" "), {
+		project_id: z.string().describe("The project ID."),
+		name: z.string().describe("Collection name."),
+		rows: z.array(z.record(z.unknown())).min(1).max(500).describe("1–500 column-value maps. Server-managed columns are stripped per row."),
+		on_conflict: z.enum(["error", "skip"]).optional().describe("Conflict policy. \"error\" (default) fails the batch; \"skip\" ignores conflicts."),
+		return_minimal: z.boolean().optional().describe("When true, returns only the inserted row ids instead of the full rows. Strongly recommended for large batches or rows with big columns — echoing 500 full rows can exhaust the token budget.")
+	}, async ({ project_id, name, rows, on_conflict, return_minimal }, { pat }) => {
+		const body = { rows };
+		if (on_conflict !== void 0) body.on_conflict = on_conflict;
+		return passthroughResult(await adminFetch(apiClient, {
+			method: "POST",
+			path: `/projects/${project_id}/collections/${encodeURIComponent(name)}/rows:batch`,
+			body,
+			query: return_minimal ? { return: "minimal" } : void 0,
 			bearer: pat
 		}));
 	});
 	registerTool(server, apiClient, "amba_admin_list_rows", [
 		"List rows in a collection from the admin side. BYPASSES auto-RLS — every row in the collection is visible.",
-		"Default behavior includes soft-deleted rows (devs debugging \"where did the row go\" need them); pass `include_deleted=false` to hide them.",
+		"Default behavior EXCLUDES soft-deleted rows; pass `include_deleted=true` to include them (e.g. debugging \"where did the row go\").",
 		"Authenticates as the developer/agent — pass `pat` or send as inbound Bearer.",
 		"Supports the server FindQuery DSL via `where` + `order` + `limit` + `offset` + `cursor` + `select`."
 	].join(" "), {
@@ -3867,7 +4554,7 @@ function registerTools$6(server, apiClient) {
 		offset: z.number().optional().describe("Offset for pagination."),
 		cursor: z.string().optional().describe("Opaque cursor returned by a prior page."),
 		select: z.array(z.string()).optional().describe("Subset of columns to return."),
-		include_deleted: z.boolean().optional().describe("Whether to include soft-deleted rows. Admin default is TRUE.")
+		include_deleted: z.boolean().optional().describe("Whether to include soft-deleted rows. Admin default is FALSE.")
 	}, async ({ project_id, name, where, order, limit, offset, cursor, select, include_deleted }, { pat }) => {
 		const findQuery = {};
 		if (where !== void 0) findQuery.where = where;
@@ -3884,21 +4571,67 @@ function registerTools$6(server, apiClient) {
 			bearer: pat
 		}));
 	});
+	registerTool(server, apiClient, "amba_admin_aggregate_rows", [
+		"Run a group-by aggregation over a collection from the admin side — BYPASSES auto-RLS.",
+		"Supports count / sum / avg / min / max, optionally grouped by one or more columns. count without a column = COUNT(*).",
+		"Default EXCLUDES soft-deleted rows; pass include_deleted=true to include them.",
+		"Authenticates as the developer/agent — pass `pat` or send as inbound Bearer.",
+		"Returns one row per group (or a single row when group_by is omitted), with each aggregation under its alias."
+	].join(" "), {
+		project_id: z.string().describe("The project ID."),
+		name: z.string().describe("Collection name."),
+		select: z.array(z.object({
+			fn: z.enum([
+				"count",
+				"sum",
+				"avg",
+				"min",
+				"max"
+			]),
+			column: z.string().optional().describe("Column to aggregate. Required for sum/avg/min/max; omit for COUNT(*)."),
+			as: z.string().optional().describe("Output alias (defaults to fn or fn_column).")
+		})).min(1).describe("One or more aggregations to compute."),
+		group_by: z.union([z.string(), z.array(z.string())]).optional().describe("Column(s) to group by. Omit for a whole-collection aggregate."),
+		where: adminFindWhereSchema.optional(),
+		include_deleted: z.boolean().optional().describe("Include soft-deleted rows. Default FALSE.")
+	}, async ({ project_id, name, select, group_by, where, include_deleted }, { pat }) => {
+		const body = { select };
+		if (group_by !== void 0) body.group_by = group_by;
+		if (where !== void 0) body.where = where;
+		if (include_deleted !== void 0) body.includeDeleted = include_deleted;
+		return passthroughResult(await adminFetch(apiClient, {
+			method: "POST",
+			path: `/projects/${project_id}/collections/${encodeURIComponent(name)}/rows/aggregate`,
+			body,
+			bearer: pat
+		}));
+	});
 	server.tool("amba_client_insert_row", [
 		"Insert a row into a collection as the signed-in app_user. Auto-RLS injects `user_id = <session app_user>` server-side; the body cannot override it.",
+		"Atomic upsert: pass on_conflict=\"ignore\" (return existing row, HTTP 200) or \"update\" (merge) plus conflict_target (unique-index columns, may include user_id). Removes read-then-write races (duplicate profiles, split rooms, etc.).",
 		"Authenticates as the end-user — pass `api_key` (project client X-Api-Key) plus `session_token` (the app_user's Bearer).",
-		"Errors: 400 INVALID_COLUMN, 401 if api_key/session missing, 404 COLLECTION_NOT_FOUND."
+		"Errors: 400 INVALID_COLUMN / INVALID_CONFLICT_TARGET, 401 if api_key/session missing, 404 COLLECTION_NOT_FOUND."
 	].join(" "), {
 		name: z.string().describe("Collection name."),
 		row: z.record(z.unknown()).describe("Column-value map. Server-managed columns and user_id are stripped/overridden."),
+		on_conflict: z.enum([
+			"error",
+			"ignore",
+			"update"
+		]).optional().describe("Conflict policy. \"error\" (default), \"ignore\" (return existing unchanged), or \"update\" (merge). Requires conflict_target."),
+		conflict_target: z.array(z.string()).optional().describe("Unique-index columns to conflict on (e.g. [\"user_id\",\"kind\"]). Required for ignore/update."),
 		api_key: z.string().describe("Project client X-Api-Key. End-user tools authenticate via this + an optional session token, NOT via a developer PAT."),
 		session_token: z.string().optional().describe("Optional app_user session Bearer token. Required by the route's clientSessionAuth.")
-	}, async ({ name, row, api_key, session_token }) => {
+	}, async ({ name, row, on_conflict, conflict_target, api_key, session_token }) => {
 		if (!api_key) return MISSING_API_KEY_ERROR;
+		const query = {};
+		if (on_conflict !== void 0) query.on_conflict = on_conflict;
+		if (conflict_target !== void 0) query.conflict_target = conflict_target.join(",");
 		return passthroughResult(await clientFetch(apiClient, {
 			method: "POST",
 			path: `/collections/${encodeURIComponent(name)}`,
 			body: row,
+			...Object.keys(query).length > 0 && { query },
 			apiKey: api_key,
 			...session_token !== void 0 && { sessionToken: session_token }
 		}));
@@ -3956,6 +4689,7 @@ function registerTools$6(server, apiClient) {
 	});
 	server.tool("amba_client_update_row", [
 		"Update a single row by id. Auto-RLS — only succeeds if the row belongs to the signed-in app_user.",
+		"Compare-and-set: pass `expected` (a column→value map) on a single-row update; the write applies only if the row still matches, else 409 PRECONDITION_FAILED. Null-safe. Optimistic concurrency without a transaction.",
 		"For bulk updates with a where-clause, omit `id` and pass `where` + `set`.",
 		"Server-managed columns and user_id are rejected with 400 INVALID_COLUMN.",
 		"Authenticates as the end-user — pass `api_key` + `session_token`."
@@ -3964,15 +4698,19 @@ function registerTools$6(server, apiClient) {
 		id: z.string().optional().describe("Row UUID for single-row update. Omit to bulk update via `where`."),
 		where: adminFindWhereSchema.optional().describe("Required for bulk update (when `id` is omitted). `where: {}` matches all rows the user owns."),
 		set: setSchema.describe("Column-value map to write. Required."),
+		expected: z.record(z.unknown()).optional().describe("Compare-and-set precondition (single-row only): column→expected-value map. The update applies only if the row currently matches; otherwise 409 PRECONDITION_FAILED."),
 		limit: z.number().optional().describe("Bulk-update cap (default 1000, max 10000). Ignored when `id` is set."),
 		api_key: z.string().describe("Project client X-Api-Key."),
 		session_token: z.string().optional().describe("App_user session Bearer. Required by the route.")
-	}, async ({ name, id, where, set, limit, api_key, session_token }) => {
+	}, async ({ name, id, where, set, expected, limit, api_key, session_token }) => {
 		if (!api_key) return MISSING_API_KEY_ERROR;
 		if (id !== void 0) return passthroughResult(await clientFetch(apiClient, {
 			method: "PATCH",
 			path: `/collections/${encodeURIComponent(name)}/${encodeURIComponent(id)}`,
-			body: { set },
+			body: expected !== void 0 ? {
+				set,
+				expected
+			} : { set },
 			apiKey: api_key,
 			...session_token !== void 0 && { sessionToken: session_token }
 		}));
@@ -4043,24 +4781,32 @@ function registerTools$6(server, apiClient) {
 	});
 	server.tool("amba_client_find_rows", [
 		"Query rows with the @layers/amba SDK-shaped filter body. POSTs to `/v1/client/collections/:name/find` — preferred over `amba_client_list_rows` for anything beyond a flat scan because GET-with-body is fragile across HTTP intermediaries.",
-		"Filter shape: leaf `{column, op, value}` (op ∈ eq|ne|gt|gte|lt|lte|in|not_in|like|ilike|is_null|is_not_null) or combinator `{and: [...]}` / `{or: [...]}` / `{not: {...}}`.",
-		"Auto-RLS — every match is AND'd with `user_id = <session app_user> AND deleted_at IS NULL` server-side.",
+		"Filter shape: leaf `{column, op, value}` (op ∈ eq|ne|gt|gte|lt|lte|in|not_in|like|ilike|is_null|is_not_null|contains|contained_by|overlaps) or combinator `{and: [...]}` / `{or: [...]}` / `{not: {...}}`.",
+		"Keyword/fuzzy search: pass `search: { q, columns, fuzzy?, threshold? }` for classical catalog search across text columns (title/author/tags). Substring (ILIKE) by default; `fuzzy: true` is typo-tolerant and ranks by relevance.",
+		"Auto-RLS — every match is AND'd with `user_id = <session app_user> AND deleted_at IS NULL` server-side (shared/unowned rows are also returned).",
 		"Authenticates as the end-user — pass `api_key` + `session_token`."
 	].join(" "), {
 		name: z.string().describe("Collection name."),
 		filter: sdkFilterSchema.optional(),
 		order: sdkOrderSchema.optional(),
+		search: z.object({
+			q: z.string().describe("Search text."),
+			columns: z.array(z.string()).min(1).describe("Text columns to search."),
+			fuzzy: z.boolean().optional().describe("Typo-tolerant trigram match + relevance ranking. Default false (substring)."),
+			threshold: z.number().optional().describe("Fuzzy only: similarity threshold 0..1 (default 0.3).")
+		}).optional().describe("Keyword / fuzzy text search across columns."),
 		limit: z.number().optional().describe("Max rows."),
 		cursor: z.string().optional().describe("Opaque cursor returned by a prior page."),
 		select: z.array(z.string()).optional().describe("Subset of columns to return."),
 		include_deleted: z.boolean().optional().describe("Include soft-deleted rows. Default FALSE."),
 		api_key: z.string().describe("Project client X-Api-Key."),
 		session_token: z.string().optional().describe("App_user session Bearer. Required by the route.")
-	}, async ({ name, filter, order, limit, cursor, select, include_deleted, api_key, session_token }) => {
+	}, async ({ name, filter, order, search, limit, cursor, select, include_deleted, api_key, session_token }) => {
 		if (!api_key) return MISSING_API_KEY_ERROR;
 		const body = {};
 		if (filter !== void 0) body.filter = filter;
 		if (order !== void 0) body.order = order;
+		if (search !== void 0) body.search = search;
 		if (limit !== void 0) body.limit = limit;
 		if (cursor !== void 0) body.cursor = cursor;
 		if (select !== void 0) body.select = select;
@@ -4232,24 +4978,27 @@ function jsonResult(payload) {
 * of a generic upstream 400.
 */
 const MAX_BUNDLE_BYTES = 10 * 1024 * 1024;
-function registerTools$5(server, apiClient) {
+function registerTools$11(server, apiClient) {
 	registerTool(server, apiClient, "amba_functions_deploy", [
 		"Deploy a function to an Amba project. The supplied `code` is a fully bundled JavaScript module (one entry file) — the deploy endpoint uploads it server-side and records a new active deployment row, superseding any prior active version for the same `name`.",
 		"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.",
 		"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.")
-	}, async ({ project_id, name, code, rate_limit }, { pat }) => {
+		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 }) => {
 		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();
 		form.append("script", new Blob([code], { type: "application/javascript" }), "bundle.js");
 		const metadata = { name };
 		if (rate_limit !== void 0 && rate_limit !== null) metadata.rate_limit = rate_limit;
+		if (isPublic === true) metadata.public = true;
 		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"]);
@@ -4357,7 +5106,7 @@ function registerTools$5(server, apiClient) {
 }
 //#endregion
 //#region src/tools/sites.ts
-function registerTools$4(server, apiClient) {
+function registerTools$10(server, apiClient) {
 	registerTool(server, apiClient, "amba_sites_deploy", [
 		"Deploy a static site to an Amba project. Creates the site if it does not yet exist, then uploads the supplied files as a new deployment.",
 		"The deployment is immutable — its files live forever under the site's storage prefix — and the site flips to serve the new deployment atomically. Older deployments are kept for rollback via `amba_sites_list`.",
@@ -4448,22 +5197,81 @@ function registerTools$4(server, apiClient) {
 	}, ["amba_remove_site_domain"]);
 }
 //#endregion
+//#region src/tools/domains.ts
+function registerTools$9(server, apiClient) {
+	registerTool(server, apiClient, "amba_domains_search", ["Search for available domains to buy through Amba. Pass a keyword or a full domain; returns candidate domains with availability and first-year price (USD).", "Free — searching never costs anything. Use this to help a user pick a name, then `amba_domains_check` to price specific picks and `amba_domains_purchase` to buy."].join(" "), {
+		project_id: z.string().describe("The Amba project ID."),
+		query: z.string().describe("A keyword (e.g. \"getunbury\") or a full domain (e.g. \"unbury.com\")."),
+		limit: z.number().int().min(1).max(50).optional().describe("Max suggestions (1-50, default 20).")
+	}, async ({ project_id, query, limit }, { pat }) => {
+		const q = { q: query };
+		if (limit !== void 0) q.limit = String(limit);
+		return jsonResult(await callWithPat(apiClient, pat, "GET", `/projects/${encodeURIComponent(project_id)}/domains/search`, { query: q }));
+	});
+	registerTool(server, apiClient, "amba_domains_check", ["Check authoritative availability + price for specific domains (up to 20 at once). Free.", "Returns, per domain: whether it is available, the first-year price (USD), whether it is a premium name, and whether Amba can register that extension."].join(" "), {
+		project_id: z.string().describe("The Amba project ID."),
+		domains: z.array(z.string()).min(1).max(20).describe("Domains to check, e.g. [\"unbury.com\", \"unbury.app\"]. Lowercased at the boundary.")
+	}, async ({ project_id, domains }, { pat }) => {
+		const normalised = domains.map((d) => d.toLowerCase());
+		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.",
+		"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)."
+	].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)."),
+		site: z.string().describe("The site name to connect the domain to (from amba_sites_list)."),
+		accept_price_usd: z.number().optional().describe("Required to execute: the price (USD) you were quoted. Omit on the first (quote) call."),
+		confirm: z.boolean().optional().describe("Set true ONLY after the user has approved the cost. Omit on the first (quote) call."),
+		auto_renew: z.boolean().optional().describe("Auto-renew the domain each year (default true)."),
+		privacy: z.boolean().optional().describe("Enable WHOIS privacy (default true)."),
+		years: z.number().int().min(1).max(10).optional().describe("Registration length in years (default 1).")
+	}, async ({ project_id, domain, site, accept_price_usd, confirm, auto_renew, privacy, years }, { pat }) => {
+		const body = {
+			domain: domain.toLowerCase(),
+			site
+		};
+		if (accept_price_usd !== void 0) body.accept_price_usd = accept_price_usd;
+		if (confirm !== void 0) body.confirm = confirm;
+		if (auto_renew !== void 0) body.auto_renew = auto_renew;
+		if (privacy !== void 0) body.privacy = privacy;
+		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.", {
+		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).")
+	}, async ({ project_id, limit, offset }, { pat }) => {
+		const query = {};
+		if (limit !== void 0) query.limit = String(limit);
+		if (offset !== void 0) query.offset = String(offset);
+		return jsonResult(await callWithPat(apiClient, pat, "GET", `/projects/${encodeURIComponent(project_id)}/domains`, { query }));
+	});
+}
+//#endregion
 //#region src/tools/secrets.ts
-function registerTools$3(server, apiClient) {
+function registerTools$8(server, apiClient) {
 	registerTool(server, apiClient, "amba_secrets_set", [
-		"Set or rotate a function-scoped secret. Every secret belongs to exactly one function — the `function` arg is required.",
-		"Writes a new version to the backing secret store and enqueues a Workers-side sync. Subsequent function invocations see the new value once sync_status flips to \"synced\" (typically <30s).",
-		"Secret name must match /^[A-Z][A-Z0-9_]{0,62}$/. Function name must match /^[a-z][a-z0-9_-]{0,57}$/.",
+		"Set or rotate a secret. Omit `function` for a PROJECT-WIDE secret (one value visible to every function in the project, including ones deployed later) — set it once instead of repeating per function. Pass `function` to scope the secret to just that function.",
+		"Writes a new version to the backing secret store and enqueues the sync. Subsequent function invocations see the new value once sync_status flips to \"synced\" (typically <30s).",
+		"Secret name must match /^[A-Z][A-Z0-9_]{0,62}$/. Function name (when given) must match /^[a-z][a-z0-9_-]{0,57}$/.",
 		"Reserved binding names (AMBA_INTERNAL_TOKEN, EDGE_HEADER_SIGNING_SECRET, STORAGE, EDGE_DB_PROXY, AMBA_API_URL, AMBA_AI_GATEWAY_URL, AMBA_PROJECT_ID) are platform-managed and rejected with 400 RESERVED_BINDING.",
-		"The function must already have at least one deployment row (deploy it first via `amba_functions_deploy`).",
+		"Secrets may be set BEFORE deploying the function — the sync drains once a deployment lands, so you can set every secret first and deploy once.",
 		"Value cap: 64 KiB. Plaintext is never returned afterwards."
 	].join(" "), {
 		project_id: z.string().describe("The Amba project ID."),
 		name: z.string().describe("Secret name. UPPER_SNAKE_CASE. /^[A-Z][A-Z0-9_]{0,62}$/."),
 		value: z.string().describe("Secret value. Stored encrypted at rest; never returned in plaintext afterwards."),
-		function: z.string().describe("Function name this secret binds to. Required — secrets are function-scoped.")
+		function: z.string().optional().describe("Function this secret binds to. OMIT for a project-wide secret (applied to every function in the project).")
 	}, async ({ project_id, name, value, function: functionName }, { pat }) => {
-		return jsonResult(await callWithPat(apiClient, pat, "POST", `/projects/${encodeURIComponent(project_id)}/secrets`, { body: {
+		return jsonResult(await callWithPat(apiClient, pat, "POST", `/projects/${encodeURIComponent(project_id)}/secrets`, { body: functionName === void 0 ? {
+			name,
+			value
+		} : {
 			name,
 			value,
 			function: functionName
@@ -4488,25 +5296,26 @@ function registerTools$3(server, apiClient) {
 		return jsonResult(await callWithPat(apiClient, pat, "GET", `/projects/${encodeURIComponent(project_id)}/secrets`));
 	}, ["amba_list_secrets"]);
 	registerTool(server, apiClient, "amba_secrets_delete", [
-		"Delete a function-scoped secret. Removes the version from the backing store AND the sync-pending row. The Workers-side binding is reaped on the next deploy of the function (the binding list is re-emitted without the secret).",
-		"The `function` arg is required — secrets are function-scoped.",
+		"Delete a secret. Removes the version from the backing store AND the sync-pending row. The Worker-side binding is reaped on the next deploy of the affected function(s) (the binding list is re-emitted without the secret).",
+		"Pass `function` to delete a function-scoped secret; OMIT it to delete the project-wide secret of this name.",
 		"Idempotent: deleting a secret that no longer exists succeeds."
 	].join(" "), {
 		project_id: z.string().describe("The Amba project ID."),
 		name: z.string().describe("Secret name. /^[A-Z][A-Z0-9_]{0,62}$/."),
-		function: z.string().describe("Function name this secret was bound to.")
+		function: z.string().optional().describe("Function this secret was bound to. OMIT to delete the project-wide secret.")
 	}, async ({ project_id, name, function: functionName }, { pat }) => {
+		const scope = functionName ?? null;
 		try {
-			return jsonResult(await callWithPat(apiClient, pat, "DELETE", `/projects/${encodeURIComponent(project_id)}/secrets/${encodeURIComponent(name)}`, { query: { function: functionName } }) ?? {
+			return jsonResult(await callWithPat(apiClient, pat, "DELETE", `/projects/${encodeURIComponent(project_id)}/secrets/${encodeURIComponent(name)}`, functionName === void 0 ? {} : { query: { function: functionName } }) ?? {
 				deleted: true,
 				name,
-				function: functionName
+				function: scope
 			});
 		} catch (err) {
 			if (err instanceof AmbaApiError && err.status === 404) return jsonResult({
 				deleted: true,
 				name,
-				function: functionName,
+				function: scope,
 				already_absent: true
 			});
 			throw err;
@@ -4515,22 +5324,26 @@ function registerTools$3(server, apiClient) {
 }
 //#endregion
 //#region src/tools/ai-prompts-admin.ts
-const PROVIDER_ENUM = z.enum(["anthropic", "openai"]);
+const PROVIDER_ENUM$1 = z.enum([
+	"anthropic",
+	"openai",
+	"mistral"
+]);
 const RATE_LIMIT_SHAPE = z.object({
 	window: z.string().optional().describe("Window length (e.g. \"60s\", \"1m\", \"1h\"). Defaults to \"60s\"."),
 	max: z.number().int().min(1).optional().describe("Max invocations per window. Defaults to 20."),
 	key: z.string().optional().describe("Bucketing key. Typically \"user_id\" or \"session_id\". Defaults to \"user_id\".")
 }).strict();
-function registerTools$2(server, apiClient) {
+function registerTools$7(server, apiClient) {
 	registerTool(server, apiClient, "amba_ai_prompts_create", [
 		"Register a new AI prompt template on a project. Returns the persisted prompt row (name, version, provider, model, client_invokable).",
-		"Name must match /^[a-z][a-z0-9_-]{0,127}$/. Provider must be \"anthropic\" or \"openai\" and must already be registered (POST /ai/providers — currently CLI / console). Model is the provider-native model id (e.g. \"claude-sonnet-4-5-20250929\", \"gpt-4o-2024-08-06\").",
+		"Name must match /^[a-z][a-z0-9_-]{0,127}$/. Provider must be \"anthropic\", \"openai\", or \"mistral\" and must already be registered via `amba_ai_providers_set`. Model is the provider-native model id (e.g. \"claude-sonnet-4-5-20250929\", \"gpt-4o-2024-08-06\").",
 		"Set `client_invokable=true` to allow SDK callers (e.g. amba-web, amba-react) to invoke the prompt via `Amba.ai.run()`. Defaults false — server-side / admin invocation only.",
 		"Re-issuing this tool with an existing `name` will bump the prompt to a new version; prefer `amba_ai_prompts_update` for that intent."
 	].join(" "), {
 		project_id: z.string().describe("The Amba project ID."),
 		name: z.string().describe("Prompt name. /^[a-z][a-z0-9_-]{0,127}$/."),
-		provider: PROVIDER_ENUM.describe("AI provider. Must already be registered."),
+		provider: PROVIDER_ENUM$1.describe("AI provider. Must already be registered via `amba_ai_providers_set`."),
 		model: z.string().describe("Provider-native model id."),
 		system_prompt: z.string().nullable().optional().describe("System prompt sent on every invocation. Omit or null for no system prompt."),
 		max_tokens: z.number().int().min(1).max(2e5).optional().describe("Max output tokens per invocation. Defaults to 4096."),
@@ -4560,7 +5373,7 @@ function registerTools$2(server, apiClient) {
 	registerTool(server, apiClient, "amba_ai_prompts_update", ["Update an existing AI prompt template. The new version replaces the old (incrementing `version`). Every field you supply overwrites the prior value; the API replaces ALL fields on every upsert, so always pass the full intended state.", "Returns the persisted row (with the bumped version)."].join(" "), {
 		project_id: z.string().describe("The Amba project ID."),
 		name: z.string().describe("Prompt name to update."),
-		provider: PROVIDER_ENUM.describe("AI provider."),
+		provider: PROVIDER_ENUM$1.describe("AI provider."),
 		model: z.string().describe("Provider-native model id."),
 		system_prompt: z.string().nullable().optional().describe("System prompt; null/omit to clear."),
 		max_tokens: z.number().int().min(1).max(2e5).optional().describe("Max output tokens."),
@@ -4640,6 +5453,179 @@ function registerTools$2(server, apiClient) {
 	}, ["amba_invoke_ai_prompt"]);
 }
 //#endregion
+//#region src/tools/ai-providers-admin.ts
+const PROVIDER_ENUM = z.enum([
+	"anthropic",
+	"openai",
+	"mistral",
+	"gemini"
+]);
+function registerTools$6(server, apiClient) {
+	registerTool(server, apiClient, "amba_ai_providers_set", [
+		"Register or rotate the upstream AI provider API key for a project. This is the key the AI gateway uses to call the model on your behalf when you invoke a prompt or `Amba.ai.*`.",
+		"Call this BEFORE `amba_ai_prompts_create` — a prompt references a registered provider, and invocations fail with `provider_not_configured` (424) until a key is set.",
+		"This is NOT `amba_secrets_set`: that writes function-scoped Worker secrets, which the AI gateway never reads. The provider key lives in a separate gateway-owned namespace and is set only here.",
+		"The key is stored server-side; it is never returned. The response includes a short masked preview (`api_key_preview`) so you can confirm which key is active."
+	].join(" "), {
+		project_id: z.string().describe("The Amba project ID."),
+		provider: PROVIDER_ENUM.describe("Provider the key belongs to: \"anthropic\", \"openai\", \"mistral\", or \"gemini\"."),
+		api_key: z.string().min(10).describe("The upstream provider API key (e.g. an Anthropic or OpenAI account key).")
+	}, async ({ project_id, provider, api_key }, { pat }) => {
+		return jsonResult(await callWithPat(apiClient, pat, "POST", `/projects/${encodeURIComponent(project_id)}/ai/providers`, { body: {
+			name: provider,
+			api_key
+		} }));
+	});
+	registerTool(server, apiClient, "amba_ai_providers_list", "List the AI providers registered on a project. Returns each provider with a `configured` boolean (true once a key is set) and timestamps. Keys themselves are never returned.", { project_id: z.string().describe("The Amba project ID.") }, async ({ project_id }, { pat }) => {
+		return jsonResult(await callWithPat(apiClient, pat, "GET", `/projects/${encodeURIComponent(project_id)}/ai/providers`));
+	});
+	registerTool(server, apiClient, "amba_ai_providers_delete", "Revoke a registered AI provider key. Rejected with 409 PROVIDER_HAS_PROMPTS if any prompt still references the provider — delete those prompts first.", {
+		project_id: z.string().describe("The Amba project ID."),
+		provider: PROVIDER_ENUM.describe("Provider to revoke.")
+	}, async ({ project_id, provider }, { pat }) => {
+		return jsonResult(await callWithPat(apiClient, pat, "DELETE", `/projects/${encodeURIComponent(project_id)}/ai/providers/${encodeURIComponent(provider)}`) ?? {
+			name: provider,
+			deleted: true
+		});
+	});
+}
+//#endregion
+//#region src/tools/experiments.ts
+const variantSchema = z.object({
+	key: z.string().describe("Variant key (e.g. \"control\", \"treatment\"). Unique within the experiment."),
+	weight: z.number().int().min(1).max(1e6).describe("Relative allocation weight (positive integer). Weights need not sum to 100.")
+});
+const STATUS_ENUM = z.enum([
+	"active",
+	"paused",
+	"ended"
+]).describe("active = assigns + exposes new users; paused = serves existing assignments but issues no new ones; ended = read-only.");
+function registerTools$5(server, apiClient) {
+	registerTool(server, apiClient, "amba_experiments_create", [
+		"Create an A/B experiment: a stable `key`, a display `name`, and >= 2 weighted variants.",
+		"End-users are bucketed into a STICKY variant the first time they request an assignment",
+		"(via the SDK) using a deterministic hash over the variant weights; the bucket then never",
+		"changes even if you re-weight later. The FIRST variant is the control for significance."
+	].join(" "), {
+		project_id: z.string().describe("The Amba project ID."),
+		key: z.string().describe("Stable experiment key (the SDK addresses the experiment by this)."),
+		name: z.string().describe("Human-readable experiment name."),
+		description: z.string().nullable().optional().describe("Optional description."),
+		variants: z.array(variantSchema).min(2).describe("At least 2 weighted variants. First is the control."),
+		status: STATUS_ENUM.optional().describe("Initial status. Defaults to \"active\".")
+	}, async ({ project_id, key, name, description, variants, status }, { client }) => {
+		const payload = {
+			key,
+			name,
+			variants
+		};
+		if (description !== void 0) payload.description = description;
+		if (status !== void 0) payload.status = status;
+		const result = await client.post(`/projects/${encodeURIComponent(project_id)}/experiments`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_experiments_list", "List every experiment on a project (key, name, variants, status, timestamps), ordered by key.", { project_id: z.string().describe("The Amba project ID.") }, async ({ project_id }, { client }) => {
+		const result = await client.get(`/projects/${encodeURIComponent(project_id)}/experiments`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_experiments_get", "Get a single experiment by key (name, variants, status, timestamps). 404 if not found.", {
+		project_id: z.string().describe("The Amba project ID."),
+		key: z.string().describe("Experiment key.")
+	}, async ({ project_id, key }, { client }) => {
+		const result = await client.get(`/projects/${encodeURIComponent(project_id)}/experiments/${encodeURIComponent(key)}`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_experiments_update", [
+		"Update an experiment's name, description, variants, and/or status. Only the supplied",
+		"fields change; variants (when supplied) replace the whole list. Re-weighting NEVER",
+		"re-rolls already-assigned users (assignments are sticky); it only affects users assigned",
+		"after the edit. Set status to \"paused\" to stop new assignments or \"ended\" to freeze it."
+	].join(" "), {
+		project_id: z.string().describe("The Amba project ID."),
+		key: z.string().describe("Experiment key to update."),
+		name: z.string().optional().describe("New name."),
+		description: z.string().nullable().optional().describe("New description; null to clear."),
+		variants: z.array(variantSchema).min(2).optional().describe("Replacement variant list (>= 2). First is the control."),
+		status: STATUS_ENUM.optional().describe("New status.")
+	}, async ({ project_id, key, name, description, variants, status }, { client }) => {
+		const payload = {};
+		if (name !== void 0) payload.name = name;
+		if (description !== void 0) payload.description = description;
+		if (variants !== void 0) payload.variants = variants;
+		if (status !== void 0) payload.status = status;
+		const result = await client.patch(`/projects/${encodeURIComponent(project_id)}/experiments/${encodeURIComponent(key)}`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_experiments_delete", "Delete an experiment by key. Cascades its assignments + exposures. Hard delete.", {
+		project_id: z.string().describe("The Amba project ID."),
+		key: z.string().describe("Experiment key to delete.")
+	}, async ({ project_id, key }, { client }) => {
+		const result = await client.delete(`/projects/${encodeURIComponent(project_id)}/experiments/${encodeURIComponent(key)}`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result ?? {
+				key,
+				deleted: true
+			}, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_experiments_results", [
+		"Compute per-variant results for an experiment: assigned_count, exposed_count, and",
+		"(when `conversion_event` is supplied) converted_count + conversion_rate — the distinct",
+		"exposed users who emitted that analytics event at/after their assignment. Each non-control",
+		"variant also gets a two-proportion z-test vs the control (first variant): a z_score and an",
+		"approximate two-sided p_value. The control variant's z_score/p_value are null."
+	].join(" "), {
+		project_id: z.string().describe("The Amba project ID."),
+		key: z.string().describe("Experiment key."),
+		conversion_event: z.string().optional().describe("Analytics event_name to treat as the conversion goal. Omit to get assigned/exposed counts only (conversions reported as 0).")
+	}, async ({ project_id, key, conversion_event }, { client }) => {
+		const query = {};
+		if (conversion_event !== void 0) query.conversion_event = conversion_event;
+		const result = await client.get(`/projects/${encodeURIComponent(project_id)}/experiments/${encodeURIComponent(key)}/results`, query);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+}
+//#endregion
+//#region src/tools/promotion.ts
+function registerTools$4(server, apiClient) {
+	registerTool(server, apiClient, "amba_project_export", [
+		"Export a declarative bundle of a project's reusable configuration so it can be re-created in another project (e.g. promote dev → prod) in one operation.",
+		"The bundle includes (each section only when present): remote configs, collection SCHEMAS (column defs + indexes, no rows), content libraries + their items, and the full gamification set — currencies, achievements, streaks, challenges, leaderboards, and xp rules — as DEFINITIONS only.",
+		"It carries NO secrets, NO per-user data, and NO end-user rows. Pass the returned `bundle` to `amba_project_import` against the target project."
+	].join(" "), { project_id: z.string().describe("The Amba project ID to export configuration FROM.") }, async ({ project_id }, { pat }) => {
+		return jsonResult(await callWithPat(apiClient, pat, "GET", `/projects/${encodeURIComponent(project_id)}/promotion/export`));
+	});
+	registerTool(server, apiClient, "amba_project_import", [
+		"Import a declarative configuration bundle (from `amba_project_export`) into a project. Idempotently creates remote configs, collections, content libraries + items, and gamification definitions (currencies, achievements, streaks, challenges, leaderboards, xp rules).",
+		"mode=\"skip_existing\" (default) leaves any entity that already exists (by name/key/code) untouched; mode=\"merge\" refreshes the definition of existing entities. Either mode is safe to run twice — re-import never duplicates.",
+		"Returns a per-section summary of { created, skipped, updated }. Collections are create-if-absent only (an existing collection is skipped; alter the schema via the dedicated collection tools)."
+	].join(" "), {
+		project_id: z.string().describe("The Amba project ID to import configuration INTO."),
+		bundle: z.record(z.unknown()).describe("The bundle object returned by `amba_project_export` (its `data` field)."),
+		mode: z.enum(["merge", "skip_existing"]).optional().describe("Conflict resolution. \"skip_existing\" (default) no-ops on a name/key/code conflict; \"merge\" updates the existing definition.")
+	}, async ({ project_id, bundle, mode }, { pat }) => {
+		const body = { bundle };
+		if (mode !== void 0) body.mode = mode;
+		return jsonResult(await callWithPat(apiClient, pat, "POST", `/projects/${encodeURIComponent(project_id)}/promotion/import`, { body }));
+	});
+}
+//#endregion
 //#region src/tools/billing.ts
 /**
 * Static tier catalog. Mirrors the marketing-page structure shipped in
@@ -4723,7 +5709,7 @@ const TIER_CATALOG = {
 		note: "Use Amba.track(name, props, { telemetry: true }) for high-volume telemetry. Cheaper, no fan-out to segments/workflows/push."
 	}
 };
-function registerTools$1(server, apiClient) {
+function registerTools$3(server, apiClient) {
 	registerTool(server, apiClient, "amba_billing_status", "Get the current billing tier, headroom on each metered axis (MAU, events, push, db_storage, media_storage), projected overage for the current period, spend ceiling, and what (if any) human action is required before the agent can continue safely. Use this BEFORE provisioning new features or running data-heavy workloads so the agent can self-throttle or escalate to the human.", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
 		const result = await client.get(`/projects/${project_id}/billing/status`);
 		return { content: [{
@@ -4750,7 +5736,7 @@ function registerTools$1(server, apiClient) {
 }
 //#endregion
 //#region src/tools/invites.ts
-function registerTools(server, apiClient) {
+function registerTools$2(server, apiClient) {
 	registerTool(server, apiClient, "amba_projects_invite_member", "Invite a teammate by email to collaborate on this project. Returns the invite URL the human should send to their teammate. Roles: admin (can manage members + integrations), member (can write data), viewer (read-only).", {
 		project_id: z.string().describe("The project ID"),
 		email: z.string().describe("Teammate's email address"),
@@ -4777,7 +5763,7 @@ function registerTools(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
-	registerTool(server, apiClient, "amba_projects_remove_member", "Remove a member from a project. The owner cannot be removed (transfer ownership first via amba_projects_transfer_owner — not yet implemented). Members can remove themselves.", {
+	registerTool(server, apiClient, "amba_projects_remove_member", "Remove a member from a project. The owner cannot be removed — transfer ownership first via amba_projects_transfer_owner, then remove the demoted ex-owner like any admin. Members can remove themselves.", {
 		project_id: z.string().describe("The project ID"),
 		developer_id: z.string().describe("The developer ID to remove")
 	}, async ({ project_id, developer_id }, { client }) => {
@@ -4787,6 +5773,304 @@ function registerTools(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
+	registerTool(server, apiClient, "amba_projects_transfer_owner", "Transfer project ownership to an existing member. Only the current owner can do this. The new owner must already be a member (invite + accept them first if not). The previous owner is automatically demoted to admin, retaining member and integration management. Use this before removing the current owner — owners cannot be removed directly.", {
+		project_id: z.string().describe("The project ID"),
+		new_owner_developer_id: z.string().describe("Developer ID of the existing member who should become the new owner.")
+	}, async ({ project_id, new_owner_developer_id }, { client }) => {
+		const result = await client.post(`/projects/${project_id}/transfer-ownership`, { new_owner_developer_id });
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+}
+//#endregion
+//#region src/tools/webhooks.ts
+function registerTools$1(server, apiClient) {
+	registerTool(server, apiClient, "amba_webhooks_create", "Register an outbound webhook subscription. Amba sends an HMAC-signed POST to target_url every time an event named event_name fires. The signing secret is returned ONCE in this response — copy it into your receiver config; later reads never include it. target_url must be https:// (http:// is allowed only for localhost during development).", {
+		project_id: z.string().describe("The project ID"),
+		event_name: z.string().describe("Event name to subscribe to. Must match ^[a-z][a-z0-9_.-]{0,127}$ (case-insensitive)."),
+		target_url: z.string().describe("HTTPS endpoint that receives the signed POST. http:// allowed only for localhost.")
+	}, async ({ project_id, event_name, target_url }, { client }) => {
+		const result = await client.post(`/projects/${project_id}/webhooks/subscriptions`, {
+			event_name,
+			target_url
+		});
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_webhooks_list", "List all webhook subscriptions for a project (most recent first). Secrets are never included — only id, event_name, target_url, status, and timestamps. status is \"active\", \"degraded\" (the delivery circuit breaker tripped on repeated failures), or \"disabled\".", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/webhooks/subscriptions`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_webhooks_get", "Describe a single webhook subscription by id. Returns event_name, target_url, status, attempt metadata, and timestamps (no secret).", {
+		project_id: z.string().describe("The project ID"),
+		subscription_id: z.string().describe("The subscription UUID")
+	}, async ({ project_id, subscription_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/webhooks/subscriptions/${subscription_id}`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_webhooks_update", "Update a webhook subscription. Any of event_name, target_url, or status may be changed; supply at least one. status accepts only \"active\" or \"disabled\" — \"degraded\" is reserved for the automatic failure circuit breaker and cannot be set manually.", {
+		project_id: z.string().describe("The project ID"),
+		subscription_id: z.string().describe("The subscription UUID"),
+		event_name: z.string().optional().describe("New event name. Must match ^[a-z][a-z0-9_.-]{0,127}$ (case-insensitive)."),
+		target_url: z.string().optional().describe("New HTTPS endpoint. http:// allowed only for localhost."),
+		status: z.enum(["active", "disabled"]).optional().describe("Enable or disable delivery. \"degraded\" cannot be set manually.")
+	}, async ({ project_id, subscription_id, event_name, target_url, status }, { client }) => {
+		const body = {};
+		if (event_name !== void 0) body.event_name = event_name;
+		if (target_url !== void 0) body.target_url = target_url;
+		if (status !== void 0) body.status = status;
+		const result = await client.patch(`/projects/${project_id}/webhooks/subscriptions/${subscription_id}`, body);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_webhooks_delete", "Delete a webhook subscription. No further events are delivered to its target_url after this.", {
+		project_id: z.string().describe("The project ID"),
+		subscription_id: z.string().describe("The subscription UUID")
+	}, async ({ project_id, subscription_id }, { client }) => {
+		const result = await client.delete(`/projects/${project_id}/webhooks/subscriptions/${subscription_id}`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_webhooks_rotate_secret", "Rotate the HMAC signing secret for a subscription. The new secret is returned ONCE — update your receiver config with it. To avoid dropped deliveries, have your receiver accept both the old and new secret for a brief overlap window before retiring the old one.", {
+		project_id: z.string().describe("The project ID"),
+		subscription_id: z.string().describe("The subscription UUID")
+	}, async ({ project_id, subscription_id }, { client }) => {
+		const result = await client.post(`/projects/${project_id}/webhooks/subscriptions/${subscription_id}/rotate-secret`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_webhooks_test", "Send a synthetic test delivery to a subscription to verify receiver setup. The test payload is tagged so it does not affect the failure circuit breaker or pollute your real event history. Returns a workflow id; poll amba_webhooks_deliveries_list shortly after for the result. Fails with 409 if the subscription is disabled.", {
+		project_id: z.string().describe("The project ID"),
+		subscription_id: z.string().describe("The subscription UUID")
+	}, async ({ project_id, subscription_id }, { client }) => {
+		const result = await client.post(`/projects/${project_id}/webhooks/subscriptions/${subscription_id}/test`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_webhooks_deliveries_list", "List recent webhook delivery attempts (most recent first). Optionally filter by subscription_id and/or status. status is \"pending\", \"delivered\", \"failed\", or \"dlq\" (dead-lettered after exhausting retries). Default page size 50, max 200.", {
+		project_id: z.string().describe("The project ID"),
+		subscription_id: z.string().optional().describe("Filter to deliveries for a single subscription UUID."),
+		status: z.enum([
+			"pending",
+			"delivered",
+			"failed",
+			"dlq"
+		]).optional().describe("Filter by delivery status."),
+		limit: z.number().optional().describe("Page size (default 50, max 200).")
+	}, async ({ project_id, subscription_id, status, limit }, { client }) => {
+		const query = {};
+		if (subscription_id !== void 0) query.subscription_id = subscription_id;
+		if (status !== void 0) query.status = status;
+		if (limit !== void 0) query.limit = String(limit);
+		const result = await client.get(`/projects/${project_id}/webhooks/deliveries`, query);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_webhooks_deliveries_get", "Describe a single webhook delivery by id, including the full attempt log, attempt count, and last error.", {
+		project_id: z.string().describe("The project ID"),
+		delivery_id: z.string().describe("The delivery UUID")
+	}, async ({ project_id, delivery_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/webhooks/deliveries/${delivery_id}`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_webhooks_deliveries_replay", "Re-enqueue a terminated (failed or dead-lettered) delivery, rebuilding the original payload from the source event. The original idempotency key is preserved so receiver-side dedup treats it as a re-delivery, not a new event. Returns 409 if the delivery is still pending, or 410 if the source event has been purged.", {
+		project_id: z.string().describe("The project ID"),
+		delivery_id: z.string().describe("The delivery UUID to replay")
+	}, async ({ project_id, delivery_id }, { client }) => {
+		const result = await client.post(`/projects/${project_id}/webhooks/deliveries/${delivery_id}/replay`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+}
+//#endregion
+//#region src/tools/email.ts
+function registerTools(server, apiClient) {
+	registerTool(server, apiClient, "amba_email_templates_create", "Create or update a transactional email template (upsert keyed by name — re-creating an existing name overwrites it). Templates are referenced by name when sending. Subject and html_body are required; text_body is an optional plain-text fallback. name must match ^[a-z][a-z0-9_]*$.", {
+		project_id: z.string().describe("The project ID"),
+		name: z.string().describe("Template name. Must match ^[a-z][a-z0-9_]*$."),
+		subject: z.string().describe("Email subject line. Supports template variables."),
+		html_body: z.string().describe("HTML body. Supports template variables."),
+		text_body: z.string().nullable().optional().describe("Optional plain-text fallback body. Pass null to leave unset.")
+	}, async ({ project_id, name, subject, html_body, text_body }, { client }) => {
+		const body = {
+			name,
+			subject,
+			html_body
+		};
+		if (text_body !== void 0) body.text_body = text_body;
+		const result = await client.post(`/projects/${project_id}/email/templates`, body);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_email_templates_list", "List all transactional email templates for a project, ordered by name.", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/email/templates`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_email_templates_get", "Get a single transactional email template by name, including its subject, html_body, and text_body.", {
+		project_id: z.string().describe("The project ID"),
+		name: z.string().describe("The template name")
+	}, async ({ project_id, name }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/email/templates/${encodeURIComponent(name)}`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_email_templates_update", "Update fields on an existing email template. Supply at least one of subject, html_body, or text_body. For text_body: pass a string to set it, or null to explicitly clear it; omit it to leave it unchanged.", {
+		project_id: z.string().describe("The project ID"),
+		name: z.string().describe("The template name to update"),
+		subject: z.string().optional().describe("New subject line."),
+		html_body: z.string().optional().describe("New HTML body."),
+		text_body: z.string().nullable().optional().describe("New plain-text body; pass null to clear it, omit to leave unchanged.")
+	}, async ({ project_id, name, subject, html_body, text_body }, { client }) => {
+		const body = {};
+		if (subject !== void 0) body.subject = subject;
+		if (html_body !== void 0) body.html_body = html_body;
+		if (text_body !== void 0) body.text_body = text_body;
+		const result = await client.patch(`/projects/${project_id}/email/templates/${encodeURIComponent(name)}`, body);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_email_templates_delete", "Delete a transactional email template by name. Sends that reference a deleted template will fail with TEMPLATE_NOT_FOUND.", {
+		project_id: z.string().describe("The project ID"),
+		name: z.string().describe("The template name to delete")
+	}, async ({ project_id, name }, { client }) => {
+		const result = await client.delete(`/projects/${project_id}/email/templates/${encodeURIComponent(name)}`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_email_suppressions_create", "Add an email address to the suppression list (upsert). Suppressed addresses are skipped on send. reason is \"bounce\", \"complaint\", or \"manual\" (default). Use this to honor unsubscribe or block requests.", {
+		project_id: z.string().describe("The project ID"),
+		email: z.string().describe("Email address to suppress (must contain @)."),
+		reason: z.enum([
+			"bounce",
+			"complaint",
+			"manual"
+		]).optional().describe("Why the address is suppressed. Defaults to \"manual\".")
+	}, async ({ project_id, email, reason }, { client }) => {
+		const body = { email };
+		if (reason !== void 0) body.reason = reason;
+		const result = await client.post(`/projects/${project_id}/email/suppressions`, body);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_email_suppressions_list", "List suppressed email addresses (most recent first, up to 500). Optionally filter by reason (\"bounce\", \"complaint\", or \"manual\").", {
+		project_id: z.string().describe("The project ID"),
+		reason: z.enum([
+			"bounce",
+			"complaint",
+			"manual"
+		]).optional().describe("Filter to a single suppression reason.")
+	}, async ({ project_id, reason }, { client }) => {
+		const query = {};
+		if (reason !== void 0) query.reason = reason;
+		const result = await client.get(`/projects/${project_id}/email/suppressions`, query);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_email_suppressions_delete", "Remove an email address from the suppression list (operator unblock). Subsequent sends to this address are no longer skipped.", {
+		project_id: z.string().describe("The project ID"),
+		email: z.string().describe("Email address to unsuppress.")
+	}, async ({ project_id, email }, { client }) => {
+		const result = await client.delete(`/projects/${project_id}/email/suppressions/${encodeURIComponent(email)}`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_email_send", "Send a transactional email. Recipient is either a user (to.user_id — resolves the user's email) or a raw address (to.email). Send via a template (template + optional data variables) OR ad-hoc to a raw address (subject + html/text). Suppressed recipients are skipped and returned with status \"suppressed\".", {
+		project_id: z.string().describe("The project ID"),
+		to: z.object({
+			user_id: z.string().optional().describe("App user UUID; resolves the user's email server-side."),
+			email: z.string().optional().describe("Raw recipient email address.")
+		}).describe("Recipient. Provide exactly one of user_id or email."),
+		template: z.string().optional().describe("Template name to render. Mutually exclusive with subject/html/text."),
+		data: z.record(z.unknown()).optional().describe("Template variable map (used with `template`)."),
+		subject: z.string().optional().describe("Ad-hoc subject. Requires to.email; mutually exclusive with `template`."),
+		html: z.string().optional().describe("Ad-hoc HTML body (ad-hoc send only)."),
+		text: z.string().optional().describe("Ad-hoc plain-text body (ad-hoc send only).")
+	}, async ({ project_id, to, template, data, subject, html, text }, { client }) => {
+		const body = { to };
+		if (template !== void 0) body.template = template;
+		if (data !== void 0) body.data = data;
+		if (subject !== void 0) body.subject = subject;
+		if (html !== void 0) body.html = html;
+		if (text !== void 0) body.text = text;
+		const result = await client.post(`/projects/${project_id}/email/send`, body);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_email_deliveries_list", "List recent email delivery records (most recent first). Optionally filter by template name and/or status (\"queued\", \"sent\", \"suppressed\", \"failed\"). Default page size 50, max 200.", {
+		project_id: z.string().describe("The project ID"),
+		template: z.string().optional().describe("Filter to a single template name."),
+		status: z.enum([
+			"queued",
+			"sent",
+			"suppressed",
+			"failed"
+		]).optional().describe("Filter by delivery status."),
+		limit: z.number().optional().describe("Page size (default 50, max 200).")
+	}, async ({ project_id, template, status, limit }, { client }) => {
+		const query = {};
+		if (template !== void 0) query.template = template;
+		if (status !== void 0) query.status = status;
+		if (limit !== void 0) query.limit = String(limit);
+		const result = await client.get(`/projects/${project_id}/email/deliveries`, query);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_email_deliveries_get", "Describe a single email delivery by id, including recipient, template, status, and last error if it failed.", {
+		project_id: z.string().describe("The project ID"),
+		delivery_id: z.string().describe("The delivery UUID")
+	}, async ({ project_id, delivery_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/email/deliveries/${delivery_id}`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
 }
 //#endregion
 //#region src/resources/amba-setup-identity.ts
@@ -5586,6 +6870,7 @@ Real-money purchases need a billing integration configured separately — see \`
 | \`amba_currencies_update\` | Edit (rename, change caps, change auto-recharge). | \`{ project_id, currency_id, max_balance: 10000 }\` |
 | \`amba_currencies_delete\` | Delete a currency (irreversible — users lose their balance). | \`{ project_id, currency_id }\` |
 | \`amba_currencies_grant\` | Grant currency to a specific user. | \`{ project_id, app_user_id, currency_code: "gems", amount: 100, reason: "welcome_bonus" }\` |
+| \`amba_currencies_spend\` | Debit currency from a specific user. Atomic; returns INSUFFICIENT_FUNDS if balance is too low (no partial debit). | \`{ project_id, app_user_id, currency_code: "gems", amount: 5, reason: "ai_generation" }\` |
 | \`amba_currencies_get_transactions\` | Per-user transaction ledger. | \`{ project_id, user_id, currency_code: "gems", limit: 100 }\` |
 
 #### Currency grant rules (auto-grants)
@@ -5871,6 +7156,9 @@ Mostly SDK-side — admin tools are for moderation + stats.
 
 | Tool | Purpose | Example args |
 | --- | --- | --- |
+| \`amba_messaging_create_conversation\` | Create a conversation server-side (zero or more initial participants — for matchmaker-built circles). | \`{ project_id, type: "group", name: "Circle" }\` |
+| \`amba_messaging_add_participant\` | Add a user to a conversation (idempotent). The matchmaker primitive for growing membership over time. | \`{ project_id, conversation_id, user_id }\` |
+| \`amba_messaging_remove_participant\` | Remove a user from a conversation (idempotent). | \`{ project_id, conversation_id, user_id }\` |
 | \`amba_messaging_list_conversations\` | List conversations (admin / moderation view). | \`{ project_id, limit: 50 }\` |
 | \`amba_messaging_list_messages\` | List messages in a conversation. | \`{ project_id, conversation_id, limit: 100 }\` |
 | \`amba_messaging_delete_message\` | Hard-delete a message (moderation). | \`{ project_id, conversation_id, message_id }\` |
@@ -6092,25 +7380,28 @@ If gamification, economy, and social are the playable surface, **infrastructure
 
 A collection is a schema-first table inside the project's isolated tenant database. 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.
 
+Admin 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\`.
+
 | Tool | Purpose | Example args |
 | --- | --- | --- |
-| \`amba_collections_create\` | Create a typed collection. | \`{ project_id, name: "todos", columns: [{ name: "title", type: "text", nullable: false }, { name: "done", type: "boolean", nullable: false, default: false }, { name: "due_at", type: "timestamptz", nullable: true }] }\` |
+| \`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, default: false }, { name: "due_at", type: "timestamptz", nullable: true }], shared: false }\` |
 | \`amba_collections_list\` | List collections in this project. | \`{ project_id }\` |
-| \`amba_collections_get\` | Read one collection's schema. | \`{ project_id, collection_name: "todos" }\` |
-| \`amba_collections_alter\` | Add / drop columns, add / drop indexes. | \`{ project_id, collection_name: "todos", add_columns: [{ name: "priority", type: "int", nullable: true }] }\` |
-| \`amba_collections_delete\` | Drop the table (destructive). | \`{ project_id, collection_name }\` |
-| \`amba_admin_insert_row\` | Insert a row as the developer (bypasses user-scope). | \`{ project_id, collection: "todos", row: { title: "Sample", done: false } }\` |
-| \`amba_admin_list_rows\` | Read rows as the developer. | \`{ project_id, collection: "todos", limit: 100 }\` |
-| \`amba_client_insert_row\` | Insert as an end-user. Requires \`api_key\` + \`session_token\`. | \`{ project_id, api_key, session_token, collection: "todos", row: {...} }\` |
-| \`amba_client_list_rows\` | Read as an end-user (auto user-scoped). | \`{ project_id, api_key, session_token, collection: "todos" }\` |
-| \`amba_client_get_row\` | Get one row by id (end-user). | \`{ project_id, api_key, session_token, collection, row_id }\` |
-| \`amba_client_update_row\` | Update one row (end-user). | \`{ project_id, api_key, session_token, collection, row_id, patch: {...} }\` |
-| \`amba_client_delete_row\` | Delete one row (end-user). | \`{ project_id, api_key, session_token, collection, row_id }\` |
-| \`amba_client_count_rows\` | Count rows matching a filter. | \`{ project_id, api_key, session_token, collection, filter: {...} }\` |
-| \`amba_client_find_rows\` | Filter / sort / paginate rows. | \`{ project_id, api_key, session_token, collection, filter: {...}, order_by: [...], limit: 50 }\` |
-| \`amba_client_find_nearest_rows\` | Vector-similarity search (rows with a \`vector(<dim>)\` column). | \`{ project_id, api_key, session_token, collection, vector_column: "embedding", query_vector: [...], k: 10 }\` |
-
-Column types: \`text\`, \`int\`, \`bigint\`, \`float\`, \`boolean\`, \`timestamptz\`, \`date\`, \`json\`, \`jsonb\`, \`uuid\`, \`vector(<dim>)\` (e.g. \`vector(1536)\` for OpenAI embeddings).
+| \`amba_collections_get\` | Read one collection's schema. | \`{ project_id, name: "todos" }\` |
+| \`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 } }\` |
+| \`amba_collections_delete\` | Drop the table (destructive). \`confirm\` must equal the collection name. | \`{ project_id, name: "todos", confirm: "todos" }\` |
+| \`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 } }\` |
+| \`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" }\` |
+| \`amba_admin_list_rows\` | Read rows as the developer. | \`{ project_id, name: "todos", limit: 100 }\` |
+| \`amba_client_insert_row\` | Insert as an end-user. Requires \`api_key\` (+ \`session_token\`). | \`{ api_key, session_token, name: "todos", row: {...} }\` |
+| \`amba_client_list_rows\` | Read as an end-user (auto user-scoped). | \`{ api_key, session_token, name: "todos" }\` |
+| \`amba_client_get_row\` | Get one row by id (end-user). | \`{ api_key, session_token, name: "todos", id }\` |
+| \`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: {...} }\` |
+| \`amba_client_delete_row\` | Soft-delete one row by id (end-user). | \`{ api_key, session_token, name: "todos", id }\` |
+| \`amba_client_count_rows\` | Count rows matching an optional \`where\`. | \`{ api_key, session_token, name: "todos", where: {...} }\` |
+| \`amba_client_find_rows\` | Filter / sort / paginate rows (SDK-shaped \`filter\`). | \`{ api_key, session_token, name: "todos", filter: {...}, order: ["created_at desc"], limit: 50 }\` |
+| \`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 }\` |
+
+Column types: \`text\`, \`integer\`, \`bigint\`, \`numeric\`, \`boolean\`, \`timestamptz\`, \`date\`, \`jsonb\`, \`uuid\`, \`vector(<dim>)\` (e.g. \`vector(1536)\` for OpenAI embeddings), plus array forms \`text[]\`, \`integer[]\`, \`bigint[]\`, \`numeric[]\`, \`boolean[]\`, \`uuid[]\`. Use \`integer\` (not \`int\`), \`numeric\` (not \`float\`/\`real\`/\`double\`), and \`jsonb\` (not \`json\`) — the validator rejects the aliases.
 
 ### Functions (serverless code)
 
@@ -6130,16 +7421,23 @@ Run user code in a sandbox triggered by HTTP, cron, or webhook. The function get
 
 ### AI prompts
 
-Managed LLM templates: stored prompt with model + system message + variables, callable by name from the SDK. The actual LLM call is rewritten per-tenant — the customer's API keys (Anthropic / OpenAI) live in the tenant secrets, never on the device.
+Managed 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.
+
+**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.
+
+> 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\`.
 
 | Tool | Purpose | Example args |
 | --- | --- | --- |
-| \`amba_ai_prompts_create\` | Create a prompt template. | \`{ project_id, key: "summarize", model: "claude-opus-4-5", system: "Summarize the user's text in 2 sentences.", variables: ["text"] }\` |
+| \`amba_ai_providers_set\` | Register / rotate the upstream provider API key. **Do this first.** | \`{ project_id, provider: "anthropic", api_key: "sk-ant-..." }\` |
+| \`amba_ai_providers_list\` | List registered providers (\`configured\` = key set). | \`{ project_id }\` |
+| \`amba_ai_providers_delete\` | Revoke a provider key (fails if prompts still reference it). | \`{ project_id, provider: "anthropic" }\` |
+| \`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 }\` |
 | \`amba_ai_prompts_list\` | List prompts. | \`{ project_id }\` |
-| \`amba_ai_prompts_get\` | Read one prompt. | \`{ project_id, key }\` |
-| \`amba_ai_prompts_update\` | Edit a prompt. | \`{ project_id, key, system: "..." }\` |
-| \`amba_ai_prompts_invoke\` | Invoke a prompt server-side (admin testing). | \`{ project_id, key, variables: { text: "..." } }\` |
-| \`amba_ai_prompts_delete\` | Delete. | \`{ project_id, key }\` |
+| \`amba_ai_prompts_get\` | Read one prompt. | \`{ project_id, name }\` |
+| \`amba_ai_prompts_update\` | Edit a prompt (replaces all fields; bumps version). | \`{ project_id, name, provider, model, system_prompt: "..." }\` |
+| \`amba_ai_prompts_invoke\` | Invoke a prompt server-side (admin testing). \`messages\` is a provider-shaped array. | \`{ project_id, name, messages: [{ role: "user", content: "..." }] }\` |
+| \`amba_ai_prompts_delete\` | Delete. | \`{ project_id, name }\` |
 
 ### Analytics + events + sessions
 
@@ -6155,9 +7453,11 @@ Managed LLM templates: stored prompt with model + system message + variables, ca
 
 ### Secrets + configs + integrations
 
+Secrets here are **function-scoped** — they become environment bindings on your deployed functions. They are NOT where AI provider keys go (use \`amba_ai_providers_set\` for those — see AI prompts above).
+
 | Tool | Purpose | Example args |
 | --- | --- | --- |
-| \`amba_secrets_set\` | Set a tenant secret (encrypted at rest). | \`{ project_id, name: "OPENAI_API_KEY", value: "sk-..." }\` |
+| \`amba_secrets_set\` | Set a function-scoped secret (encrypted at rest; bound on the next deploy). | \`{ project_id, name: "STRIPE_WEBHOOK_SECRET", value: "whsec_..." }\` |
 | \`amba_secrets_get\` | Read a secret (returns \`"<redacted>"\` unless explicitly requested). | \`{ project_id, name }\` |
 | \`amba_secrets_list\` | List secret names. | \`{ project_id }\` |
 | \`amba_secrets_delete\` | Delete. | \`{ project_id, name }\` |
@@ -6216,9 +7516,9 @@ const newTodo = await Amba.collections.insert('todos', { title: 'Ship the app',
 await Amba.collections.update('todos', newTodo.id, { done: true });
 await Amba.collections.delete('todos', newTodo.id);
 
-// AI — call a managed prompt
+// AI — call a managed prompt (prompt_slug names the registered prompt)
 const response = await Amba.ai.anthropic.messages.create({
-  prompt_key: 'summarize',
+  prompt_slug: 'summarize',
   variables: { text: 'A long article about backend services …' },
 });
 
@@ -6286,8 +7586,7 @@ let showBeta = try await Amba.flags.get(name: "beta_feature")
 try await Amba.events.track("app_opened", properties: ["source": "deep_link"])
 
 let reply = try await Amba.ai.anthropic.messages.create(
-    promptKey: "summarize",
-    variables: ["text": "A long article..."]
+    request: AiMessageRequest(promptSlug: "summarize", variables: ["text": "A long article..."])
 )
 \`\`\`
 
@@ -6344,7 +7643,7 @@ Batch.
    - [ ] Resend (transactional email)
    - [ ] Stripe (web payments / subscriptions)
    - [ ] Mixpanel / PostHog / Segment (analytics forwarding)
-   - [ ] OpenAI / Anthropic (LLM keys — required for \`Amba.ai.*\` calls)
+   - [ ] OpenAI / Anthropic / Mistral / Gemini LLM keys (required for \`Amba.ai.*\` — set via \`amba_ai_providers_set\`, **not** \`amba_integrations_configure\`)
 
 6. **Feature flags:** seed any starter flags?
    - Yes — wire \`beta_feature\` (off by default) so I can ship the wiring before the feature exists
@@ -6359,7 +7658,7 @@ Batch.
 1. Before creating:
    - \`amba_collections_list\` — match on \`name\`. Collisions: never silently recreate (data loss). Offer \`amba_collections_alter\` to add new columns instead.
    - \`amba_functions_list\` — match on \`name\`. Collisions: ask to redeploy (with the new source) or skip.
-   - \`amba_ai_prompts_list\` — match on \`key\`. Same.
+   - \`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.)
    - \`amba_integrations_list\` — match on \`provider\`. Same.
    - \`amba_configs_list\` — match on \`key\`. Same.
 
@@ -6541,6 +7840,8 @@ const TOOL_CATEGORY = {
 	amba_developer_rotate_pat: "identity",
 	amba_users_list: "identity",
 	amba_list_users: "identity",
+	amba_users_create: "identity",
+	amba_create_user: "identity",
 	amba_users_get: "identity",
 	amba_users_delete: "identity",
 	amba_users_export: "identity",
@@ -6589,6 +7890,7 @@ const TOOL_CATEGORY = {
 	amba_onboarding_get_stats: "engagement",
 	amba_get_onboarding_stats: "engagement",
 	amba_content_libraries_create: "engagement",
+	amba_content_libraries_delete: "engagement",
 	amba_create_content_library: "engagement",
 	amba_content_list_libraries: "engagement",
 	amba_content_items_add: "engagement",
@@ -6623,6 +7925,8 @@ const TOOL_CATEGORY = {
 	amba_list_xp_rules: "gamification",
 	amba_xp_update_rule: "gamification",
 	amba_xp_delete_rule: "gamification",
+	amba_xp_grant: "gamification",
+	amba_xp_deduct: "gamification",
 	amba_xp_list_users: "gamification",
 	amba_users_get_xp: "gamification",
 	amba_get_user_xp: "gamification",
@@ -6636,11 +7940,14 @@ const TOOL_CATEGORY = {
 	amba_update_achievement: "gamification",
 	amba_achievements_delete: "gamification",
 	amba_delete_achievement: "gamification",
+	amba_achievements_grant: "gamification",
+	amba_achievements_revoke: "gamification",
 	amba_streaks_create: "gamification",
 	amba_create_streak: "gamification",
 	amba_streaks_list: "gamification",
 	amba_streaks_update: "gamification",
 	amba_streaks_delete: "gamification",
+	amba_streaks_reset: "gamification",
 	amba_leaderboards_create: "gamification",
 	amba_create_leaderboard: "gamification",
 	amba_leaderboards_list: "gamification",
@@ -6653,6 +7960,14 @@ const TOOL_CATEGORY = {
 	amba_update_leaderboard: "gamification",
 	amba_leaderboards_delete: "gamification",
 	amba_delete_leaderboard: "gamification",
+	amba_leagues_create: "gamification",
+	amba_create_league: "gamification",
+	amba_leagues_list: "gamification",
+	amba_list_leagues: "gamification",
+	amba_leagues_update: "gamification",
+	amba_update_league: "gamification",
+	amba_leagues_list_cohorts: "gamification",
+	amba_list_league_cohorts: "gamification",
 	amba_challenges_create: "gamification",
 	amba_create_challenge: "gamification",
 	amba_challenges_list: "gamification",
@@ -6675,6 +7990,7 @@ const TOOL_CATEGORY = {
 	amba_delete_currency: "economy",
 	amba_currencies_grant: "economy",
 	amba_grant_currency: "economy",
+	amba_currencies_spend: "economy",
 	amba_currencies_get_transactions: "economy",
 	amba_get_currency_transactions: "economy",
 	amba_currency_grant_rules_create: "economy",
@@ -6709,6 +8025,7 @@ const TOOL_CATEGORY = {
 	amba_stores_patch_listing: "economy",
 	amba_stores_delete_listing: "economy",
 	amba_inventory_grant_item: "economy",
+	amba_inventory_revoke_item: "economy",
 	amba_grant_item: "economy",
 	amba_users_get_inventory: "economy",
 	amba_get_user_inventory: "economy",
@@ -6732,6 +8049,9 @@ const TOOL_CATEGORY = {
 	amba_update_group_member: "social",
 	amba_groups_remove_member: "social",
 	amba_remove_group_member: "social",
+	amba_messaging_create_conversation: "social",
+	amba_messaging_add_participant: "social",
+	amba_messaging_remove_participant: "social",
 	amba_messaging_list_conversations: "social",
 	amba_messaging_list_messages: "social",
 	amba_messaging_delete_message: "social",
@@ -6770,6 +8090,20 @@ const TOOL_CATEGORY = {
 	amba_get_analytics: "analytics",
 	amba_sessions_list: "analytics",
 	amba_sessions_analytics: "analytics",
+	amba_funnels_list: "analytics",
+	amba_funnels_create: "analytics",
+	amba_funnels_get: "analytics",
+	amba_funnels_update: "analytics",
+	amba_funnels_delete: "analytics",
+	amba_funnels_query: "analytics",
+	amba_experiments_create: "analytics",
+	amba_experiments_list: "analytics",
+	amba_experiments_get: "analytics",
+	amba_experiments_update: "analytics",
+	amba_experiments_delete: "analytics",
+	amba_experiments_results: "analytics",
+	amba_project_export: "infrastructure",
+	amba_project_import: "infrastructure",
 	amba_projects_create: "infrastructure",
 	amba_create_project: "infrastructure",
 	amba_projects_list: "infrastructure",
@@ -6796,6 +8130,7 @@ const TOOL_CATEGORY = {
 	amba_delete_collection: "infrastructure",
 	amba_admin_insert_row: "infrastructure",
 	amba_admin_list_rows: "infrastructure",
+	amba_admin_aggregate_rows: "infrastructure",
 	amba_client_insert_row: "infrastructure",
 	amba_client_list_rows: "infrastructure",
 	amba_client_get_row: "infrastructure",
@@ -6836,6 +8171,10 @@ const TOOL_CATEGORY = {
 	amba_remove_site_domain: "infrastructure",
 	amba_sites_list_domains: "infrastructure",
 	amba_list_site_domains: "infrastructure",
+	amba_domains_search: "infrastructure",
+	amba_domains_check: "infrastructure",
+	amba_domains_purchase: "infrastructure",
+	amba_domains_list: "infrastructure",
 	amba_media_upload: "infrastructure",
 	amba_upload_media: "infrastructure",
 	amba_media_list: "infrastructure",
@@ -6867,6 +8206,9 @@ const TOOL_CATEGORY = {
 	amba_integrations_patch: "infrastructure",
 	amba_integrations_test: "infrastructure",
 	amba_test_integration: "infrastructure",
+	amba_ai_providers_set: "infrastructure",
+	amba_ai_providers_list: "infrastructure",
+	amba_ai_providers_delete: "infrastructure",
 	amba_ai_prompts_create: "infrastructure",
 	amba_create_ai_prompt: "infrastructure",
 	amba_ai_prompts_list: "infrastructure",
@@ -6886,7 +8228,34 @@ const TOOL_CATEGORY = {
 	amba_billing_set_ceiling: "infrastructure",
 	amba_projects_invite_member: "infrastructure",
 	amba_projects_list_members: "infrastructure",
-	amba_projects_remove_member: "infrastructure"
+	amba_projects_remove_member: "infrastructure",
+	amba_projects_transfer_owner: "infrastructure",
+	amba_webhooks_create: "infrastructure",
+	amba_webhooks_list: "infrastructure",
+	amba_webhooks_get: "infrastructure",
+	amba_webhooks_update: "infrastructure",
+	amba_webhooks_delete: "infrastructure",
+	amba_webhooks_rotate_secret: "infrastructure",
+	amba_webhooks_test: "infrastructure",
+	amba_webhooks_deliveries_list: "infrastructure",
+	amba_webhooks_deliveries_get: "infrastructure",
+	amba_webhooks_deliveries_replay: "infrastructure",
+	amba_email_templates_create: "engagement",
+	amba_email_templates_list: "engagement",
+	amba_email_templates_get: "engagement",
+	amba_email_templates_update: "engagement",
+	amba_email_templates_delete: "engagement",
+	amba_email_suppressions_create: "engagement",
+	amba_email_suppressions_list: "engagement",
+	amba_email_suppressions_delete: "engagement",
+	amba_email_send: "engagement",
+	amba_email_deliveries_list: "engagement",
+	amba_email_deliveries_get: "engagement",
+	amba_admin_insert_rows: "infrastructure",
+	amba_remote_configs_create: "infrastructure",
+	amba_remote_configs_list: "infrastructure",
+	amba_remote_configs_update: "infrastructure",
+	amba_remote_configs_delete: "infrastructure"
 };
 /**
 * Look up the canonical category for an MCP tool name. Accepts both
@@ -6906,7 +8275,15 @@ function getToolCategory(toolName) {
 * called against it once.
 */
 function registerAllTools(server, apiClient) {
-	registerTools$7(server, apiClient);
+	registerTools$13(server, apiClient);
+	registerTools$33(server, apiClient);
+	registerTools$32(server, apiClient);
+	registerTools$31(server, apiClient);
+	registerTools$30(server, apiClient);
+	registerTools$29(server, apiClient);
+	registerTools$28(server, apiClient);
+	registerTools$27(server, apiClient);
+	registerTools$26(server, apiClient);
 	registerTools$25(server, apiClient);
 	registerTools$24(server, apiClient);
 	registerTools$23(server, apiClient);
@@ -6919,12 +8296,12 @@ function registerAllTools(server, apiClient) {
 	registerTools$16(server, apiClient);
 	registerTools$15(server, apiClient);
 	registerTools$14(server, apiClient);
-	registerTools$13(server, apiClient);
 	registerTools$12(server, apiClient);
 	registerTools$11(server, apiClient);
 	registerTools$10(server, apiClient);
 	registerTools$9(server, apiClient);
 	registerTools$8(server, apiClient);
+	registerTools$7(server, apiClient);
 	registerTools$6(server, apiClient);
 	registerTools$5(server, apiClient);
 	registerTools$4(server, apiClient);