@layers/amba-mcp 4.0.3 → 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() {
@@ -308,7 +308,9 @@ const READ_VERBS = new Set([
 	"tiers",
 	"verify",
 	"logs",
-	"query"
+	"query",
+	"aggregate",
+	"results"
 ]);
 /**
 * Destructive verbs. A tool whose name contains one of these MAY perform
@@ -611,7 +613,7 @@ function registerPublicTool(server, name, description, schema, handler, aliases
 }
 //#endregion
 //#region src/tools/projects.ts
-function registerTools$29(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: [{
@@ -718,7 +720,7 @@ function registerTools$29(server, apiClient) {
 }
 //#endregion
 //#region src/tools/push.ts
-function registerTools$28(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"),
@@ -848,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$27(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.")
@@ -933,7 +935,7 @@ const configConditionSchema = z.object({
 	percentage: z.number().optional().describe("Percentage rollout (0-100)"),
 	value: z.unknown().describe("Override value for this condition")
 });
-function registerTools$26(server, apiClient) {
+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.")
@@ -1011,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$25(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"),
@@ -1027,6 +1029,17 @@ function registerTools$25(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"),
@@ -1070,7 +1083,7 @@ function registerTools$25(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",
@@ -1175,7 +1188,7 @@ function registerTools$25(server, apiClient) {
 }
 //#endregion
 //#region src/tools/streaks.ts
-function registerTools$24(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`."),
@@ -1267,11 +1280,11 @@ function registerTools$24(server, apiClient) {
 //#endregion
 //#region src/tools/integrations.ts
 const providerEnum = z.enum(INTEGRATION_PROVIDERS);
-function registerTools$23(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,
@@ -1337,7 +1350,7 @@ const PERIOD_DAYS = {
 	"30d": "30",
 	"90d": "90"
 };
-function registerTools$22(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([
@@ -1360,7 +1373,7 @@ function registerTools$22(server, apiClient) {
 }
 //#endregion
 //#region src/tools/users.ts
-function registerTools$21(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)"),
@@ -1379,6 +1392,30 @@ function registerTools$21(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")
@@ -1638,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,
@@ -1665,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',
     });
   }, []);
 
@@ -1733,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$20(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",
@@ -1818,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$19(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\")"),
@@ -1923,7 +1968,7 @@ function registerTools$19(server, apiClient) {
 }
 //#endregion
 //#region src/tools/challenges.ts
-function registerTools$18(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\")"),
@@ -2034,7 +2079,7 @@ function registerTools$18(server, apiClient) {
 }
 //#endregion
 //#region src/tools/economy.ts
-function registerTools$17(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\")"),
@@ -2069,38 +2114,42 @@ function registerTools$17(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.", {
+	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)")
-	}, async ({ project_id, app_user_id, currency_code, amount, reason }, { client }) => {
+		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",
@@ -2566,8 +2615,8 @@ function registerTools$17(server, apiClient) {
 }
 //#endregion
 //#region src/tools/leaderboards.ts
-function registerTools$16(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([
@@ -2612,7 +2661,7 @@ function registerTools$16(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",
@@ -2671,8 +2720,80 @@ function registerTools$16(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$15(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\")"),
@@ -3248,7 +3369,7 @@ function registerTools$15(server, apiClient) {
 }
 //#endregion
 //#region src/tools/social.ts
-function registerTools$14(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: [{
@@ -3573,7 +3694,7 @@ function registerTools$14(server, apiClient) {
 }
 //#endregion
 //#region src/tools/xp.ts
-function registerTools$13(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\")"),
@@ -3696,7 +3817,7 @@ function registerTools$13(server, apiClient) {
 }
 //#endregion
 //#region src/tools/events.ts
-function registerTools$12(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."),
@@ -3763,7 +3884,7 @@ 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$11(server, apiClient) {
+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: [{
@@ -4029,7 +4150,7 @@ function enrichedAuthResult(result, agentInstructions) {
 		status: result.status
 	});
 }
-function registerTools$10(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",
@@ -4163,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()}`;
@@ -4200,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.")
@@ -4226,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$9(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.",
@@ -4349,19 +4482,39 @@ function registerTools$9(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.",
@@ -4374,20 +4527,22 @@ function registerTools$9(server, apiClient) {
 		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.")
-	}, async ({ project_id, name, rows, on_conflict }, { pat }) => {
+		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(" "), {
@@ -4399,7 +4554,7 @@ function registerTools$9(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;
@@ -4416,21 +4571,67 @@ function registerTools$9(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 }
 		}));
@@ -4488,6 +4689,7 @@ function registerTools$9(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`."
@@ -4496,15 +4698,19 @@ function registerTools$9(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 }
 		}));
@@ -4575,24 +4781,32 @@ function registerTools$9(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;
@@ -4764,24 +4978,27 @@ function jsonResult(payload) {
 * of a generic upstream 400.
 */
 const MAX_BUNDLE_BYTES = 10 * 1024 * 1024;
-function registerTools$8(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"]);
@@ -4889,7 +5106,7 @@ function registerTools$8(server, apiClient) {
 }
 //#endregion
 //#region src/tools/sites.ts
-function registerTools$7(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`.",
@@ -4981,7 +5198,7 @@ function registerTools$7(server, apiClient) {
 }
 //#endregion
 //#region src/tools/domains.ts
-function registerTools$6(server, apiClient) {
+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\")."),
@@ -5037,7 +5254,7 @@ function registerTools$6(server, apiClient) {
 }
 //#endregion
 //#region src/tools/secrets.ts
-function registerTools$5(server, apiClient) {
+function registerTools$8(server, apiClient) {
 	registerTool(server, apiClient, "amba_secrets_set", [
 		"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).",
@@ -5107,22 +5324,26 @@ function registerTools$5(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$4(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."),
@@ -5152,7 +5373,7 @@ function registerTools$4(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."),
@@ -5232,6 +5453,179 @@ function registerTools$4(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
@@ -6993,7 +7387,7 @@ Admin tools authenticate the developer/agent (pass \`pat\` or send it as the inb
 | \`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, 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: "int", nullable: true } }\` |
+| \`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" }\` |
@@ -7007,7 +7401,7 @@ Admin tools authenticate the developer/agent (pass \`pat\` or send it as the inb
 | \`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\`, \`int\`, \`bigint\`, \`float\`, \`boolean\`, \`timestamptz\`, \`date\`, \`json\`, \`jsonb\`, \`uuid\`, \`vector(<dim>)\` (e.g. \`vector(1536)\` for OpenAI embeddings).
+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)
 
@@ -7027,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
 
@@ -7052,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 }\` |
@@ -7113,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 …' },
 });
 
@@ -7183,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..."])
 )
 \`\`\`
 
@@ -7241,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
@@ -7256,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.
 
@@ -7438,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",
@@ -7486,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",
@@ -7555,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",
@@ -7683,6 +8096,14 @@ const TOOL_CATEGORY = {
 	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",
@@ -7709,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",
@@ -7784,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",
@@ -7850,7 +8275,11 @@ function getToolCategory(toolName) {
 * called against it once.
 */
 function registerAllTools(server, apiClient) {
-	registerTools$10(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);
@@ -7867,9 +8296,9 @@ 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);