@layers/amba-mcp 4.0.4 → 4.0.6

package/dist/index.js

@@ -310,7 +310,13 @@ const READ_VERBS = new Set([
 	"logs",
 	"query",
 	"aggregate",
-	"results"
+	"results",
+	"explain",
+	"plan",
+	"diff",
+	"drift",
+	"balance",
+	"payouts"
 ]);
 /**
 * Destructive verbs. A tool whose name contains one of these MAY perform
@@ -367,10 +373,15 @@ const WRITE_VERBS = new Set([
 	"insert",
 	"invite",
 	"register",
+	"define",
+	"map",
+	"adopt",
 	"purchase",
 	"signup",
 	"login",
-	"refresh"
+	"refresh",
+	"track",
+	"charge"
 ]);
 /**
 * Split a tool name into lowercase verb-candidate tokens, dropping the
@@ -386,7 +397,17 @@ function toolNameTokens(name) {
 * 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.
 */
+/**
+* Per-tool classification overrides for names whose verb token is a noun
+* elsewhere. `catalog` is a NOUN in catalog-management tools
+* (`amba_create_catalog_item`, `amba_set_item_price`), so it can't be a global
+* read verb — but `amba_events_catalog` is a pure read/discovery tool. Override
+* it explicitly rather than polluting the verb sets.
+*/
+const VERB_CLASS_OVERRIDES = { amba_events_catalog: "read" };
 function classifyToolVerb(name) {
+	const override = VERB_CLASS_OVERRIDES[name];
+	if (override) return override;
 	const tokens = toolNameTokens(name);
 	let sawRead = false;
 	let sawWrite = false;
@@ -422,7 +443,9 @@ const NOUN_LIKE_VERBS = new Set([
 	"tiers",
 	"analytics",
 	"schedule",
-	"me"
+	"me",
+	"balance",
+	"payouts"
 ]);
 /**
 * The verbs eligible to be a title's leading word: every classification
@@ -613,7 +636,7 @@ function registerPublicTool(server, name, description, schema, handler, aliases
 }
 //#endregion
 //#region src/tools/projects.ts
-function registerTools$33(server, apiClient) {
+function registerTools$37(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: [{
@@ -631,7 +654,7 @@ function registerTools$33(server, apiClient) {
 	registerTool(server, apiClient, "amba_projects_create", "Create a new Amba project. A project represents a mobile app and contains all its engagement configuration (push, segments, config, content, streaks).", {
 		name: z.string().describe("Human-readable project name (e.g. \"My Fitness App\")"),
 		bundle_id: z.string().optional().describe("App bundle identifier (e.g. \"com.example.myapp\"). Doubles as the audience the server expects on Apple Sign In identity tokens — set this if your app uses Sign in with Apple, or sign-in will reject with AUDIENCE_NOT_CONFIGURED."),
-		google_oauth_client_id: z.string().optional().describe("Google OAuth 2.0 client id from Google Cloud Console. Doubles as the audience the server expects on Google Sign In id tokens — set this if your app uses Sign in with Google, or sign-in will reject with AUDIENCE_NOT_CONFIGURED. The client id is a public identifier (not a secret) — same value that ships in the app binary."),
+		google_oauth_client_id: z.string().optional().describe("Google OAuth 2.0 client id from your Google OAuth configuration. Doubles as the audience the server expects on Google Sign In id tokens — set this if your app uses Sign in with Google, or sign-in will reject with AUDIENCE_NOT_CONFIGURED. The client id is a public identifier (not a secret) — same value that ships in the app binary."),
 		platform: z.enum([
 			"ios",
 			"android",
@@ -720,7 +743,7 @@ function registerTools$33(server, apiClient) {
 }
 //#endregion
 //#region src/tools/push.ts
-function registerTools$32(server, apiClient) {
+function registerTools$36(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"),
@@ -850,7 +873,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$31(server, apiClient) {
+function registerTools$35(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.")
@@ -935,7 +958,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$30(server, apiClient) {
+function registerTools$34(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.")
@@ -1013,7 +1036,7 @@ 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$29(server, apiClient) {
+function registerTools$33(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\")"),
@@ -1069,14 +1092,16 @@ function registerTools$29(server, apiClient) {
 			"random",
 			"sequential"
 		]).describe("How content items are selected for delivery"),
-		config: z.record(z.unknown()).optional().describe("Schedule-specific configuration (e.g. delivery time, timezone)")
-	}, async ({ project_id, library_id, name, schedule_type, config }, { client }) => {
+		config: z.record(z.unknown()).optional().describe("Schedule-specific configuration (e.g. delivery time, timezone)"),
+		batch_size: z.number().int().min(1).max(100).optional().describe("How many items to publish per interval. Defaults to 1 (one item per run). Set to N to publish N items each interval — e.g. \"today's 3 tips\" — without hand-rolling a date-wrap rotation client-side. The selected items are delivered as an array the in-app SDK reads.")
+	}, async ({ project_id, library_id, name, schedule_type, config, batch_size }, { client }) => {
 		const payload = {
 			library_id,
 			name,
 			schedule_type
 		};
 		if (config !== void 0) payload.config = config;
+		if (batch_size !== void 0) payload.batch_size = batch_size;
 		const result = await client.post(`/projects/${project_id}/content/schedules`, payload);
 		return { content: [{
 			type: "text",
@@ -1150,14 +1175,16 @@ function registerTools$29(server, apiClient) {
 		cron: z.string().optional().describe("Cron expression (5-field) for delivery timing"),
 		timezone: z.string().optional().describe("IANA timezone (e.g. \"America/Los_Angeles\")"),
 		segment_id: z.string().nullable().optional().describe("Target segment, or null to broadcast to all users"),
-		is_active: z.boolean().optional().describe("Whether the schedule is active")
-	}, async ({ project_id, schedule_id, name, cron, timezone, segment_id, is_active }, { client }) => {
+		is_active: z.boolean().optional().describe("Whether the schedule is active"),
+		batch_size: z.number().int().min(1).max(100).optional().describe("How many items to publish per interval (1–100). Set to N to switch this schedule to publishing N items each run instead of one.")
+	}, async ({ project_id, schedule_id, name, cron, timezone, segment_id, is_active, batch_size }, { client }) => {
 		const payload = {};
 		if (name !== void 0) payload.name = name;
 		if (cron !== void 0) payload.cron = cron;
 		if (timezone !== void 0) payload.timezone = timezone;
 		if (segment_id !== void 0) payload.segment_id = segment_id;
 		if (is_active !== void 0) payload.is_active = is_active;
+		if (batch_size !== void 0) payload.batch_size = batch_size;
 		const result = await client.patch(`/projects/${project_id}/content/schedules/${schedule_id}`, payload);
 		return { content: [{
 			type: "text",
@@ -1174,6 +1201,45 @@ function registerTools$29(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
+	registerTool(server, apiClient, "amba_content_translations_set", "Set a per-language translation for a content item. The base item carries one title/body in the language it was authored in; this stores a localized title/body for a BCP-47 language tag (e.g. \"es-419\", \"pt-BR\"). In-app, a content read in that language (the SDK forwards the device locale) returns the translated copy, falling back to the base item when no translation exists — so a multi-locale app ships every language from one Amba content library instead of bundling per-language copies in the app binary. This is a PARTIAL update: only the fields you pass are written. Omit a field to leave a previously-stored value untouched (and to share the base item value on first create). Pass an explicit `null` for `title` or `body` to CLEAR a previously-stored translated value so that field falls back to the base item again.", {
+		project_id: z.string().describe("The project ID"),
+		item_id: z.string().describe("The content item ID to translate"),
+		language: z.string().describe("BCP-47 language tag for this translation (e.g. \"en\", \"es-419\", \"pt-BR\")"),
+		title: z.string().nullable().optional().describe("Translated title. Omit to leave the existing value untouched (shares the base item title on first create); pass null to clear a previously-stored title so it falls back to the base item."),
+		body: z.string().nullable().optional().describe("Translated body. Omit to leave the existing value untouched (shares the base item body on first create); pass null to clear a previously-stored body so it falls back to the base item."),
+		metadata: z.record(z.unknown()).optional().describe("Optional per-language metadata (e.g. locale-specific media URL)")
+	}, async ({ project_id, item_id, language, title, body, metadata }, { client }) => {
+		const payload = {};
+		if (title !== void 0) payload.title = title;
+		if (body !== void 0) payload.body = body;
+		if (metadata !== void 0) payload.metadata = metadata;
+		const result = await client.put(`/projects/${project_id}/content/items/${item_id}/translations/${encodeURIComponent(language)}`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_content_translations_list", "List every per-language translation for a content item (one row per language). Use this to see which locales an item is already translated into before adding more, or to audit translation coverage across a content library.", {
+		project_id: z.string().describe("The project ID"),
+		item_id: z.string().describe("The content item ID")
+	}, async ({ project_id, item_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/content/items/${item_id}/translations`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_content_translations_delete", "Delete a single per-language translation for a content item. After deletion, in-app reads in that language fall back to the base item.", {
+		project_id: z.string().describe("The project ID"),
+		item_id: z.string().describe("The content item ID"),
+		language: z.string().describe("BCP-47 language tag of the translation to delete")
+	}, async ({ project_id, item_id, language }, { client }) => {
+		const result = await client.delete(`/projects/${project_id}/content/items/${item_id}/translations/${encodeURIComponent(language)}`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
 	registerTool(server, apiClient, "amba_content_bulk_import", "Bulk-import multiple content items into a library in a single transactional call. Each item is upsert-on-key within the library. Useful for seed data and for migrating from external content sources.", {
 		project_id: z.string().describe("The project ID"),
 		library_id: z.string().describe("The content library ID"),
@@ -1188,7 +1254,7 @@ function registerTools$29(server, apiClient) {
 }
 //#endregion
 //#region src/tools/streaks.ts
-function registerTools$28(server, apiClient) {
+function registerTools$32(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`."),
@@ -1280,7 +1346,7 @@ function registerTools$28(server, apiClient) {
 //#endregion
 //#region src/tools/integrations.ts
 const providerEnum = z.enum(INTEGRATION_PROVIDERS);
-function registerTools$27(server, apiClient) {
+function registerTools$31(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"),
@@ -1350,7 +1416,7 @@ const PERIOD_DAYS = {
 	"30d": "30",
 	"90d": "90"
 };
-function registerTools$26(server, apiClient) {
+function registerTools$30(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([
@@ -1372,8 +1438,58 @@ function registerTools$26(server, apiClient) {
 	}, ["amba_get_analytics"]);
 }
 //#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/users.ts
-function registerTools$25(server, apiClient) {
+function registerTools$29(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)"),
@@ -1492,6 +1608,23 @@ function registerTools$25(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
+	registerTool(server, apiClient, "amba_users_create_cohort", [
+		"Mint N anonymous app_users at once, all sharing the same properties (and, optionally, the same segment memberships) in a single call.",
+		"The seed-a-test-cohort primitive: use it to populate a leaderboard, dry-run a push segment, or stand up a batch of users tagged `cohort: beta`.",
+		"Each user is anonymous-style (no external identity) — a shared-properties cohort has no per-user identity by definition. Pass `segment_ids` to enrol every minted user into those segments.",
+		"Capped at 500 per call (split larger seeds into multiple calls). Returns `{ user_ids, created_count }`.",
+		"Errors: 400 INVALID_COUNT (out of 1–500) / INVALID_SEGMENT_ID (segment does not exist), 500 COHORT_FAILED."
+	].join(" "), {
+		project_id: z.string().describe("The project ID."),
+		count: z.number().int().min(1).max(500).describe("How many users to mint (1–500). Larger counts return INVALID_COUNT."),
+		properties: z.record(z.unknown()).optional().describe("Properties stamped identically onto every minted user (JSON object). Optional."),
+		segment_ids: z.array(z.string()).optional().describe("Segment UUIDs every minted user is enrolled into. Optional.")
+	}, async ({ project_id, count, properties, segment_ids }, { client }) => {
+		const payload = { count };
+		if (properties !== void 0) payload.properties = properties;
+		if (segment_ids !== void 0) payload.segment_ids = segment_ids;
+		return jsonResult$1(await client.post(`/projects/${project_id}/users/cohort`, payload));
+	});
 	registerTool(server, apiClient, "amba_users_delete", [
 		"Hard-delete a single app_user. Pass exactly one of `user_id`",
 		"(uuid) or `anonymous_id` (string). Returns the deleted id plus",
@@ -1562,6 +1695,31 @@ function registerTools$25(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
+	registerTool(server, apiClient, "amba_users_reset_user", [
+		"Reset ONE app user to a brand-new state WITHOUT deleting them. Clears",
+		"that single user's gamification (XP + ledger, achievements,",
+		"leaderboard entries, challenges), economy (currency balances +",
+		"transactions, inventory, entitlements), streaks, engagement/telemetry",
+		"events, sessions, onboarding, roles, segment memberships, push tokens",
+		"and their social participation (friendships, group + conversation",
+		"memberships, messages, reviews, feed activity) — but keeps the",
+		"app_users row itself (email, anonymous_id, properties survive). This",
+		"is the scalpel to amba_users_reset_sandbox’s sledgehammer: reset a",
+		"single stuck/test user on a production project without touching a",
+		"seeded cohort. Developer-authored config (currencies, achievement",
+		"definitions, catalog) is never touched — the user goes to zero, the",
+		"project does not change. Pass `delete:true` to ALSO remove the",
+		"app_users row at the end (equivalent to amba_users_delete). Returns a",
+		"per-table summary of what was cleared. 404 USER_NOT_FOUND if no row",
+		"matched."
+	].join(" "), {
+		project_id: z.string().describe("The project ID"),
+		user_id: z.string().describe("The app user UUID to reset."),
+		delete: z.boolean().optional().describe("When true, also delete the app_users row after clearing its state (full removal). Defaults to false — the user is kept and only reset.")
+	}, async ({ project_id, user_id, delete: alsoDelete }, { client }) => {
+		const query = alsoDelete ? { delete: "true" } : void 0;
+		return jsonResult$1(await client.delete(`/projects/${project_id}/users/${user_id}/reset`, query));
+	});
 	registerTool(server, apiClient, "amba_sessions_analytics", "Get session analytics (DAU, active users, total sessions, average and median session duration) for a project across a rolling window.", {
 		project_id: z.string().describe("The project ID"),
 		period: z.enum([
@@ -1778,7 +1936,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$24(server, apiClient) {
+function registerTools$28(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",
@@ -1863,7 +2021,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$23(server, apiClient) {
+function registerTools$27(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\")"),
@@ -1968,7 +2126,7 @@ function registerTools$23(server, apiClient) {
 }
 //#endregion
 //#region src/tools/challenges.ts
-function registerTools$22(server, apiClient) {
+function registerTools$26(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\")"),
@@ -2079,7 +2237,7 @@ function registerTools$22(server, apiClient) {
 }
 //#endregion
 //#region src/tools/economy.ts
-function registerTools$21(server, apiClient) {
+function registerTools$25(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\")"),
@@ -2327,6 +2485,137 @@ function registerTools$21(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
+	registerTool(server, apiClient, "amba_entitlements_grant", [
+		"Grant or refresh a subscription entitlement directly on a user — the same `user_entitlements` row mobile store webhooks (Apple/Play) write to, so a server-side grant and an in-app purchase land in one unified place your client SDK reads with `Amba.entitlements`.",
+		"Covers the non-mobile cases that have no webhook: Stripe/Paddle web checkout, manual support grants, gift codes, legacy migrations. Set is_active=false to revoke (ToS violations, refunds).",
+		"Upserts on (user, entitlement_id) — a second call for the same pair refreshes the existing row in place rather than duplicating. Omit a nullable field to preserve it; pass null to clear it."
+	].join(" "), {
+		project_id: z.string().describe("The project ID"),
+		app_user_id: z.string().describe("The app_user UUID to grant the entitlement to"),
+		entitlement_id: z.string().describe("Entitlement identifier (e.g. \"premium\", \"pro_annual\"). Required."),
+		is_active: z.boolean().optional().describe("Whether the entitlement is active. Defaults to true on grant; pass false to revoke."),
+		product_id: z.string().nullable().optional().describe("Product identifier this grant is for (e.g. \"pro_yearly\"). When it matches a declared product (amba_products_create), the product's mapped entitlements are granted too. Pass null to clear."),
+		store: z.enum([
+			"app_store",
+			"play_store",
+			"web"
+		]).nullable().optional().describe("Originating store (\"web\" covers any non-native checkout). Pass null to clear."),
+		purchase_date: z.string().nullable().optional().describe("ISO-8601 purchase timestamp. Pass null to clear."),
+		expiration_date: z.string().nullable().optional().describe("ISO-8601 expiration timestamp. Pass null to clear (e.g. for a lifetime grant)."),
+		period_type: z.enum([
+			"trial",
+			"intro",
+			"normal"
+		]).nullable().optional().describe("Billing period type. Pass null to clear."),
+		raw_data: z.record(z.unknown()).nullable().optional().describe("Opaque JSON blob for audit (e.g. the raw webhook payload). Pass null to reset to {}.")
+	}, async ({ project_id, app_user_id, entitlement_id, is_active, product_id, store, purchase_date, expiration_date, period_type, raw_data }, { client }) => {
+		const payload = { entitlement_id };
+		if (is_active !== void 0) payload.is_active = is_active;
+		if (product_id !== void 0) payload.product_id = product_id;
+		if (store !== void 0) payload.store = store;
+		if (purchase_date !== void 0) payload.purchase_date = purchase_date;
+		if (expiration_date !== void 0) payload.expiration_date = expiration_date;
+		if (period_type !== void 0) payload.period_type = period_type;
+		if (raw_data !== void 0) payload.raw_data = raw_data;
+		const result = await client.post(`/projects/${project_id}/users/${app_user_id}/entitlements`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_entitlements_define", ["Define a canonical entitlement your app gates features on with `Amba.entitlements.has(\"pro\")`. Declaring it lets every grant path validate against a known set instead of free-typed strings, and lets you map products to it.", "This is the durable abstraction: features check the entitlement, never a product or a store — so you can change how it is sold without touching app code."].join(" "), {
+		project_id: z.string().describe("The project ID"),
+		key: z.string().describe("Stable entitlement key (e.g. \"pro\", \"premium_content\"). Required."),
+		display_name: z.string().optional().describe("Human-readable name for dashboards."),
+		description: z.string().optional().describe("What this entitlement unlocks."),
+		metadata: z.record(z.unknown()).optional().describe("Opaque metadata object.")
+	}, async ({ project_id, key, display_name, description, metadata }, { client }) => {
+		const payload = { key };
+		if (display_name !== void 0) payload.display_name = display_name;
+		if (description !== void 0) payload.description = description;
+		if (metadata !== void 0) payload.metadata = metadata;
+		const result = await client.post(`/projects/${project_id}/subscriptions/entitlements`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_products_create", ["Declare a sellable subscription product and the entitlement it grants. `store_product_refs` maps each store to its own identifier ({ \"app_store\": \"com.app.pro.yearly\", \"play_store\": \"pro_yearly\", \"web\": \"price_123\" }) so one Amba product resolves on whichever store a purchase came from.", "When `grants_entitlement_id` is set, an in-app purchase OR a server grant carrying this product unlocks that entitlement automatically — that resolution is what makes the payment engine swappable."].join(" "), {
+		project_id: z.string().describe("The project ID"),
+		product_id: z.string().describe("Stable, neutral product key (e.g. \"pro_yearly\"). Required."),
+		grants_entitlement_id: z.string().optional().describe("The entitlement key this product unlocks (must be defined first)."),
+		display_name: z.string().optional().describe("Human-readable product name."),
+		description: z.string().optional().describe("Marketing description for the paywall."),
+		product_type: z.enum([
+			"subscription",
+			"consumable",
+			"non_consumable",
+			"non_renewing"
+		]).optional().describe("Product type (default \"subscription\")."),
+		store_product_refs: z.record(z.string()).optional().describe("Map of store id → that store's product identifier."),
+		trial_period_days: z.number().int().nonnegative().optional().describe("Free-trial length in days (display hint)."),
+		duration: z.string().optional().describe("ISO-8601 duration display hint (e.g. \"P1M\", \"P1Y\")."),
+		metadata: z.record(z.unknown()).optional().describe("Opaque metadata object.")
+	}, async ({ project_id, product_id, grants_entitlement_id, display_name, description, product_type, store_product_refs, trial_period_days, duration, metadata }, { client }) => {
+		const payload = { product_id };
+		if (grants_entitlement_id !== void 0) payload.grants_entitlement_id = grants_entitlement_id;
+		if (display_name !== void 0) payload.display_name = display_name;
+		if (description !== void 0) payload.description = description;
+		if (product_type !== void 0) payload.product_type = product_type;
+		if (store_product_refs !== void 0) payload.store_product_refs = store_product_refs;
+		if (trial_period_days !== void 0) payload.trial_period_days = trial_period_days;
+		if (duration !== void 0) payload.duration = duration;
+		if (metadata !== void 0) payload.metadata = metadata;
+		const result = await client.post(`/projects/${project_id}/subscriptions/products`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_entitlements_map_product", "Map a product to an (additional) entitlement it unlocks. Products can unlock more than one entitlement (e.g. a bundle); this adds to the set beyond the product's primary grants_entitlement_id. Both the product and the entitlement must already be declared.", {
+		project_id: z.string().describe("The project ID"),
+		product_id: z.string().describe("The declared product id."),
+		entitlement_id: z.string().describe("The declared entitlement key to also grant.")
+	}, async ({ project_id, product_id, entitlement_id }, { client }) => {
+		const result = await client.post(`/projects/${project_id}/subscriptions/products/${product_id}/entitlements`, { entitlement_id });
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_offerings_create", ["Create (or replace) a subscription offering — the named set of packages your paywall renders, fetched at runtime with `Amba.offerings()`. Each package surfaces one product at a position (e.g. $monthly, $annual).", "Set is_current=true to make this the default offering the SDK returns; exactly one offering is current at a time. The response is fully provider-neutral."].join(" "), {
+		project_id: z.string().describe("The project ID"),
+		offering_id: z.string().describe("Stable offering id (e.g. \"default\", \"holiday_2026\")."),
+		display_name: z.string().optional().describe("Human-readable name."),
+		description: z.string().optional().describe("Internal description."),
+		is_current: z.boolean().optional().describe("Make this the default offering the SDK returns (default false)."),
+		packages: z.array(z.object({
+			package_id: z.string().describe("Package id unique within the offering (e.g. \"$annual\")."),
+			product_id: z.string().optional().describe("The product this package surfaces (by product_id)."),
+			position: z.number().int().nonnegative().optional().describe("Display order (lower first)."),
+			metadata: z.record(z.unknown()).optional().describe("Opaque package metadata.")
+		})).optional().describe("The packages in this offering (replaces the existing set)."),
+		metadata: z.record(z.unknown()).optional().describe("Opaque offering metadata.")
+	}, async ({ project_id, offering_id, display_name, description, is_current, packages, metadata }, { client }) => {
+		const payload = { offering_id };
+		if (display_name !== void 0) payload.display_name = display_name;
+		if (description !== void 0) payload.description = description;
+		if (is_current !== void 0) payload.is_current = is_current;
+		if (packages !== void 0) payload.packages = packages;
+		if (metadata !== void 0) payload.metadata = metadata;
+		const result = await client.post(`/projects/${project_id}/subscriptions/offerings`, payload);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_offerings_list", "List the project's subscription offerings with their packages and the product behind each — the same provider-neutral shape the client SDK's `offerings()` returns.", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/subscriptions/offerings`);
+		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")
@@ -2612,10 +2901,100 @@ function registerTools$21(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	}, ["amba_get_currency_transactions"]);
+	registerTool(server, apiClient, "amba_currencies_get_user_balance", [
+		"Read a user's current per-currency balances directly — the live value your client SDK and paywall logic see, returned in one call instead of replaying and summing the transaction ledger.",
+		"Returns one row per currency the user holds (balance, lifetime_earned, lifetime_spent, last_recharged_at), or an empty array if they hold none. Pass currency_id to narrow to a single currency.",
+		"Pair with amba_currencies_grant / amba_currencies_spend to verify a balance change landed, or with amba_currencies_get_transactions to reconcile the balance against its ledger history."
+	].join(" "), {
+		project_id: z.string().describe("The project ID"),
+		user_id: z.string().describe("The app user ID"),
+		currency_id: z.string().optional().describe("Filter to one currency (definition UUID).")
+	}, async ({ project_id, user_id, currency_id }, { client }) => {
+		const query = {};
+		if (currency_id !== void 0) query.currency_id = currency_id;
+		const result = await client.get(`/projects/${project_id}/currencies/balances/${user_id}`, query);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+}
+//#endregion
+//#region src/tools/monetization.ts
+const objectTypeSchema = z.enum([
+	"entitlement",
+	"product",
+	"offering",
+	"package",
+	"paywall"
+]);
+function registerTools$24(server, apiClient) {
+	registerTool(server, apiClient, "amba_monetization_plan", "Preview the monetization plan for a project: a three-way diff between the declared subscription config (entitlements, products, offerings, packages, paywalls), the last-adopted baseline, and the live config in the connected provider (RevenueCat). Returns the op-list an apply WOULD perform (create/update/archive/attach/detach/set-current), a store-floor preflight (referenced store product identifiers not yet present upstream), and any out-of-band drift. READ-ONLY — computes the plan; applies nothing. Use this before changing monetization so you can see exactly what differs.", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/monetization/plan`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_monetization_drift", "Show only the out-of-band drift for a project's monetization: Amba-managed subscription objects whose live state in the provider (RevenueCat) has changed since Amba last adopted them. READ-ONLY — reports drift; reconciles nothing. Use this to detect when someone edited the subscription config directly in the provider dashboard outside the declarative flow.", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/monetization/drift`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_monetization_export", "Snapshot a project's LIVE subscription monetization config (from the connected provider, RevenueCat) into a declarative bundle: entitlements, products, offerings, packages, and paywalls keyed by their stable identifiers. READ-ONLY. Use this to capture the current config as Infrastructure-as-Code you can review, version-control, and promote between projects.", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/monetization/export`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_monetization_definitions_list", "List the project's current DECLARED monetization definitions (the desired-state entitlements, products, offerings, packages, and paywalls stored in Amba). READ-ONLY. This is the authored Infrastructure-as-Code that `amba_monetization_plan` diffs against the live provider config.", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/monetization/definitions`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_monetization_apply", "Apply the declared monetization config to the connected provider (RevenueCat). Additive ops apply automatically: CREATE entitlements/offerings/packages/paywall-DRAFTS, ATTACH products to new packages/entitlements, update display metadata. DESTRUCTIVE ops (detach a product, archive an entitlement/offering, remove a package) are GATED: they apply ONLY when you re-call with `confirm` set to the plan_hash — otherwise the apply refuses with MONETIZATION_CONFIRM_REQUIRED and lists the gated ops (nothing is written). Setting the current/default offering and publishing a paywall live are NOT API-driven — they're returned in `refused` with the exact dashboard step. Pass the `plan_hash` from a fresh `amba_monetization_plan`; apply refuses a stale plan_hash (re-plan), hard-fails on a missing store product, enforces the ordering invariant (never archives the live current offering; never detaches a product a live customer resolves unless `allow_detach_live`), reads back every write, and STOPS on the first failure without rolling back. To execute gated ops, first review the plan, then call again with confirm = plan_hash.", {
+		project_id: z.string().describe("The project ID"),
+		plan_hash: z.string().describe("The plan_hash returned by a fresh amba_monetization_plan. Apply refuses if the provider drifted off this hash."),
+		confirm: z.string().optional().describe("Set to the SAME plan_hash to confirm and EXECUTE the gated destructive ops (detach/archive/remove). Omit for an additive-only apply — gated ops are then reported but not run."),
+		allow_detach_live: z.boolean().optional().describe("Accept detaching a product a live customer currently resolves. Off by default (the apply refuses such a detach to protect live purchases)."),
+		reconcile: z.enum(["amba", "adopt"]).optional().describe("Out-of-band drift mode: 'amba' (default) reverts the provider to the declared config on confirm; 'adopt' pulls the live change back into the declared config instead.")
+	}, async ({ project_id, plan_hash, confirm, allow_detach_live, reconcile }, { client }) => {
+		const body = { plan_hash };
+		if (confirm !== void 0) body["confirm"] = confirm;
+		if (allow_detach_live !== void 0) body["allow_detach_live"] = allow_detach_live;
+		if (reconcile !== void 0) body["reconcile"] = reconcile;
+		const result = await client.post(`/projects/${project_id}/monetization/apply`, body);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_monetization_adopt", "Adopt a project's live subscription config as Amba's managed baseline: writes the matching declared definitions AND records the current live state as the adopted baseline, so the NEXT plan is a clean no-op and future provider-side edits surface as drift. This writes ONLY Amba's own state — it NEVER changes the provider (RevenueCat). Idempotent. Pass adopt_all: true to adopt everything, or a specific objects list. Use this to bring an existing project's monetization under declarative management.", {
+		project_id: z.string().describe("The project ID"),
+		adopt_all: z.boolean().optional().describe("Adopt every live object. Mutually sufficient with `objects`."),
+		objects: z.array(z.object({
+			object_type: objectTypeSchema.describe("The kind of object to adopt"),
+			identifier: z.string().describe("The object stable identifier (provider id)")
+		})).optional().describe("Specific objects to adopt. Provide this OR adopt_all.")
+	}, async ({ project_id, adopt_all, objects }, { client }) => {
+		const body = {};
+		if (adopt_all !== void 0) body["adopt_all"] = adopt_all;
+		if (objects !== void 0) body["objects"] = objects;
+		const result = await client.post(`/projects/${project_id}/monetization/adopt`, body);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
 }
 //#endregion
 //#region src/tools/leaderboards.ts
-function registerTools$20(server, apiClient) {
+function registerTools$23(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\")"),
@@ -2727,10 +3106,10 @@ function registerTools$20(server, apiClient) {
 * 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`
+* rollover (the scheduled weekly rollover) and score live off `xp_awarded`
 * engagement events.
 */
-function registerTools$19(server, apiClient) {
+function registerTools$22(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\""),
@@ -2793,7 +3172,7 @@ function registerTools$19(server, apiClient) {
 }
 //#endregion
 //#region src/tools/platform.ts
-function registerTools$18(server, apiClient) {
+function registerTools$21(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\")"),
@@ -3068,6 +3447,83 @@ function registerTools$18(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
+	registerTool(server, apiClient, "amba_media_catalogs_create", "Create a curated media catalog — a named, slug-addressable bundle of media assets your app fetches in one call. Reach for this when an app needs a stable, ordered set of public images/assets (onboarding illustrations, a sticker pack, home-screen heroes) instead of hard-coding asset URLs client-side. Items are added separately with amba_media_catalogs_add_item. `is_public` (default true) gates whether end-user apps can read it via Amba.media.catalog(slug); set it false for drafts.", {
+		project_id: z.string().describe("The project ID"),
+		slug: z.string().describe("URL-safe handle your app reads the catalog by (lowercase, digits, hyphens; e.g. \"onboarding-art\"). Unique per project."),
+		name: z.string().describe("Human-readable catalog name (e.g. \"Onboarding Illustrations\")"),
+		description: z.string().optional().describe("Optional description of what the catalog holds"),
+		is_public: z.boolean().optional().describe("Whether end-user apps can read this catalog by slug. Defaults to true."),
+		metadata: z.record(z.unknown()).optional().describe("Custom metadata")
+	}, async ({ project_id, slug, name, description, is_public, metadata }, { client }) => {
+		const payload = {
+			slug,
+			name
+		};
+		if (description !== void 0) payload.description = description;
+		if (is_public !== void 0) payload.is_public = is_public;
+		if (metadata !== void 0) payload.metadata = metadata;
+		return jsonResult$1(await client.post(`/projects/${project_id}/media/catalogs`, payload));
+	});
+	registerTool(server, apiClient, "amba_media_catalogs_list", "List media catalogs for a project, each with its item count. Use this to see which curated asset bundles exist before adding to or reading one.", {
+		project_id: z.string().describe("The project ID"),
+		limit: z.number().optional().describe("Max results to return (default 50)"),
+		offset: z.number().optional().describe("Offset for pagination (default 0)")
+	}, async ({ project_id, limit, offset }, { client }) => {
+		const query = {};
+		if (limit !== void 0) query.limit = String(limit);
+		if (offset !== void 0) query.offset = String(offset);
+		return jsonResult$1(await client.get(`/projects/${project_id}/media/catalogs`, query));
+	});
+	registerTool(server, apiClient, "amba_media_catalogs_get", "Get a single media catalog and its ordered items, each resolved to a stable public asset URL. Use this to inspect exactly what an app will receive when it reads the catalog by slug.", {
+		project_id: z.string().describe("The project ID"),
+		catalog_id: z.string().describe("The catalog ID")
+	}, async ({ project_id, catalog_id }, { client }) => {
+		return jsonResult$1(await client.get(`/projects/${project_id}/media/catalogs/${catalog_id}`));
+	});
+	registerTool(server, apiClient, "amba_media_catalogs_update", "Update a media catalog's name, slug, description, visibility, or metadata. Flip `is_public` to publish a draft catalog or pull one back to internal.", {
+		project_id: z.string().describe("The project ID"),
+		catalog_id: z.string().describe("The catalog ID"),
+		slug: z.string().optional().describe("New URL-safe slug (lowercase, digits, hyphens)"),
+		name: z.string().optional().describe("New catalog name"),
+		description: z.string().optional().describe("New description"),
+		is_public: z.boolean().optional().describe("Whether end-user apps can read this catalog"),
+		metadata: z.record(z.unknown()).optional().describe("Replacement metadata object")
+	}, async ({ project_id, catalog_id, slug, name, description, is_public, metadata }, { client }) => {
+		const payload = {};
+		if (slug !== void 0) payload.slug = slug;
+		if (name !== void 0) payload.name = name;
+		if (description !== void 0) payload.description = description;
+		if (is_public !== void 0) payload.is_public = is_public;
+		if (metadata !== void 0) payload.metadata = metadata;
+		return jsonResult$1(await client.patch(`/projects/${project_id}/media/catalogs/${catalog_id}`, payload));
+	});
+	registerTool(server, apiClient, "amba_media_catalogs_delete", "Delete a media catalog. This removes the catalog and its item membership; the underlying media assets are NOT deleted (they stay in storage and any other catalog).", {
+		project_id: z.string().describe("The project ID"),
+		catalog_id: z.string().describe("The catalog ID")
+	}, async ({ project_id, catalog_id }, { client }) => {
+		return jsonResult$1(await client.delete(`/projects/${project_id}/media/catalogs/${catalog_id}`));
+	});
+	registerTool(server, apiClient, "amba_media_catalogs_add_item", "Add a media asset to a catalog. The asset keeps its canonical public URL — a catalog is a curated reference, not a copy. Set `position` to control where it lands in the catalog's order, and `caption` for a per-catalog label.", {
+		project_id: z.string().describe("The project ID"),
+		catalog_id: z.string().describe("The catalog ID"),
+		media_id: z.string().describe("ID of the media asset to add (from amba_media_list)"),
+		position: z.number().optional().describe("Sort position within the catalog (lower comes first). Defaults to 0."),
+		caption: z.string().optional().describe("Optional per-catalog caption for this asset"),
+		metadata: z.record(z.unknown()).optional().describe("Custom metadata for this catalog item")
+	}, async ({ project_id, catalog_id, media_id, position, caption, metadata }, { client }) => {
+		const payload = { media_id };
+		if (position !== void 0) payload.position = position;
+		if (caption !== void 0) payload.caption = caption;
+		if (metadata !== void 0) payload.metadata = metadata;
+		return jsonResult$1(await client.post(`/projects/${project_id}/media/catalogs/${catalog_id}/items`, payload));
+	});
+	registerTool(server, apiClient, "amba_media_catalogs_remove_item", "Remove a media asset from a catalog. The asset itself is untouched — only its membership in this catalog is removed.", {
+		project_id: z.string().describe("The project ID"),
+		catalog_id: z.string().describe("The catalog ID"),
+		media_id: z.string().describe("ID of the media asset to remove from the catalog")
+	}, async ({ project_id, catalog_id, media_id }, { client }) => {
+		return jsonResult$1(await client.delete(`/projects/${project_id}/media/catalogs/${catalog_id}/items/${media_id}`));
+	});
 	registerTool(server, apiClient, "amba_moderation_queue_get", "Get the content moderation queue for a project. Shows reported content pending review.", {
 		project_id: z.string().describe("The project ID"),
 		status: z.enum([
@@ -3369,7 +3825,7 @@ function registerTools$18(server, apiClient) {
 }
 //#endregion
 //#region src/tools/social.ts
-function registerTools$17(server, apiClient) {
+function registerTools$20(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: [{
@@ -3694,7 +4150,7 @@ function registerTools$17(server, apiClient) {
 }
 //#endregion
 //#region src/tools/xp.ts
-function registerTools$16(server, apiClient) {
+function registerTools$19(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\")"),
@@ -3817,7 +4273,7 @@ function registerTools$16(server, apiClient) {
 }
 //#endregion
 //#region src/tools/events.ts
-function registerTools$15(server, apiClient) {
+function registerTools$18(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."),
@@ -3857,9 +4313,103 @@ function registerTools$15(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
+	registerTool(server, apiClient, "amba_events_explain", [
+		"Dry-run an event against the rule engine: given a candidate event (name + properties + optional user), return which rules WOULD match and what each WOULD produce — XP awards, currency grants, feed items, streak qualification, and webhook deliveries — WITHOUT firing the event or committing any side effect. Pure read-only preview.",
+		"Use it to answer \"what happens if I track this?\" before you wire up the call: see the exact XP delta, currency amount, feed item, and webhook destinations a given event would trigger, so you can confirm your rules are configured the way you intend.",
+		"Pass `user_id` to also preview per-user gating (daily limits, cooldowns, balance caps) — the response notes when an effect would currently be suppressed or reduced. Omit it for the base, user-independent match. Nothing is written either way.",
+		"Returns `{data: {matched: [{rule_type, rule_id, name, would, note?}], evaluated_surfaces, unmatched_reason_samples?}}`. An empty `matched` with a reason sample means no rule targets this event yet."
+	].join(" "), {
+		project_id: z.string().describe("The project ID"),
+		event_name: z.string().describe("Candidate event name to evaluate (e.g. \"lesson_completed\")."),
+		properties: z.record(z.unknown()).optional().describe("Candidate event properties (e.g. {amount: 5}). Read by property-scaled grant rules."),
+		user_id: z.string().optional().describe("Optional app_user UUID. When supplied, the preview also reports per-user gating (daily limit / cooldown / balance cap) without mutating anything.")
+	}, async ({ project_id, event_name, properties, user_id }, { client }) => {
+		const event = { name: event_name };
+		if (properties !== void 0) event.properties = properties;
+		if (user_id !== void 0) event.user_id = user_id;
+		return jsonResult$1(await client.post(`/projects/${project_id}/events/explain`, { event }));
+	});
+	registerTool(server, apiClient, "amba_events_track", [
+		"Track an engagement event on behalf of a user from the server side — the one call that drives the whole reactive pipeline: streak qualification, currency grant rules, XP awards, achievements, segment membership, and any webhooks subscribed to the event all fan out from this single write.",
+		"Use it to dogfood the event→XP→achievement loop without a device: emit the exact event your app will (e.g. \"mission_completed\" with {xp: 100}) and watch the downstream effects land, then read them back with amba_users_get_xp / amba_achievements_list.",
+		"Pass `event_id` for exactly-once semantics — a re-POST with the same id is a silent no-op and never double-credits a streak or grant. Omit `app_user_id` for a project-scope event (no end-user attribution).",
+		"Send one event, or a `batch` of up to the per-request cap, in a single round-trip. Returns `{data: {tracked, inserted, skipped}}` — `skipped` counts idempotent replays."
+	].join(" "), {
+		project_id: z.string().describe("The project ID"),
+		event_name: z.string().describe("Event name (e.g. \"mission_completed\", \"lesson_finished\"). Required for a single event.").optional(),
+		app_user_id: z.string().nullable().optional().describe("The app_user UUID this event belongs to. Omit or pass null for a project-scope event with no end-user attribution."),
+		properties: z.record(z.unknown()).optional().describe("Arbitrary event properties (e.g. {xp: 100, level: 3}). Read by grant/XP rules."),
+		occurred_at: z.string().optional().describe("ISO-8601 timestamp the event occurred. Defaults to now."),
+		event_id: z.string().optional().describe("Idempotency key (≤255 chars). A re-POST with the same id is a silent no-op — no double-credit."),
+		batch: z.array(z.object({
+			event_name: z.string().describe("Event name. Required."),
+			app_user_id: z.string().nullable().optional().describe("The app_user UUID. Omit or pass null for a project-scope event."),
+			properties: z.record(z.unknown()).optional().describe("Arbitrary event properties."),
+			occurred_at: z.string().optional().describe("ISO-8601 occurrence timestamp."),
+			event_id: z.string().optional().describe("Idempotency key for this event.")
+		})).optional().describe("Track many events in one call. When provided, the top-level single-event fields are ignored.")
+	}, async ({ project_id, event_name, app_user_id, properties, occurred_at, event_id, batch }, { client }) => {
+		let payload;
+		if (batch !== void 0) payload = { events: batch };
+		else {
+			const single = { event_name };
+			if (app_user_id !== void 0) single.app_user_id = app_user_id;
+			if (properties !== void 0) single.properties = properties;
+			if (occurred_at !== void 0) single.occurred_at = occurred_at;
+			if (event_id !== void 0) single.event_id = event_id;
+			payload = single;
+		}
+		return jsonResult$1(await client.post(`/projects/${project_id}/events`, payload));
+	});
 }
 //#endregion
-//#region src/tools/funnels.ts
+//#region src/tools/event-catalog.ts
+function registerTools$17(server, apiClient) {
+	registerTool(server, apiClient, "amba_events_catalog", "Discover every event you can subscribe a webhook to — both APP events (inside your app: users, gamification, economy, social, content) and CONTROL-plane lifecycle events (about the project itself: provisioning, deploys, domains, billing). Returns each event's type, plane, payload example, and status (`live` = emitted today, `planned` = catalogued, not yet wired). Production pattern: after standing up a project, call this, then subscribe to the lifecycle events you care about (e.g. `domain.registered`, `site.deploy.completed`) with amba_control_webhooks_create and to app events with amba_webhooks_create. Subscriptions match an exact name, a namespace wildcard (`economy.*`), or all (`*`). Pass plane to filter.", {
+		project_id: z.string().describe("The project ID"),
+		plane: z.enum(["app", "control"]).optional().describe("Filter to one plane. Omit for both.")
+	}, async ({ project_id, plane }, { client }) => {
+		const qs = plane ? `?plane=${plane}` : "";
+		const result = await client.get(`/projects/${project_id}/webhooks/catalog${qs}`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_control_webhooks_create", "Subscribe a webhook to CONTROL-plane lifecycle events for this project — provisioning, deploys, domains, billing. Amba sends an HMAC-signed POST to target_url whenever a matching event fires. event_name is an exact event (`project.provisioned`), a namespace wildcard (`domain.*`), or all control events (`*`). The signing secret is returned ONCE — copy it into your receiver. target_url must be https:// (http:// only for localhost). Use amba_events_catalog (plane:'control') to see what's available. For APP events use amba_webhooks_create instead.", {
+		project_id: z.string().describe("The project ID"),
+		event_name: z.string().describe("Control event to subscribe to: exact (`project.provisioned`), wildcard (`domain.*`), or `*`."),
+		target_url: z.string().describe("HTTPS endpoint that receives the signed POST. http:// only for localhost.")
+	}, async ({ project_id, event_name, target_url }, { client }) => {
+		const result = await client.post(`/projects/${project_id}/control-webhooks`, {
+			event_name,
+			target_url
+		});
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_control_webhooks_list", "List this project's control-plane webhook subscriptions (most recent first). Secrets are never included.", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/control-webhooks`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_control_webhooks_delete", "Delete a control-plane webhook subscription by id.", {
+		project_id: z.string().describe("The project ID"),
+		id: z.string().describe("The subscription id")
+	}, async ({ project_id, id }, { client }) => {
+		const result = await client.delete(`/projects/${project_id}/control-webhooks/${id}`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+}
+//#endregion
+//#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([
@@ -3884,7 +4434,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$14(server, apiClient) {
+function registerTools$16(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: [{
@@ -3978,56 +4528,6 @@ function registerTools$14(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
 async function authFetch(apiClient, options) {
 	const url = `${apiClient.getApiRoot()}${options.path}`;
@@ -4150,7 +4650,7 @@ function enrichedAuthResult(result, agentInstructions) {
 		status: result.status
 	});
 }
-function registerTools$13(server, apiClient) {
+function registerTools$15(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",
@@ -4257,7 +4757,7 @@ function registerTools$13(server, apiClient) {
 }
 //#endregion
 //#region src/tools/collections.ts
-async function adminFetch(apiClient, options) {
+async function adminFetch$1(apiClient, options) {
 	let url = `${apiClient.getBaseUrl()}${options.path}`;
 	if (options.query && Object.keys(options.query).length > 0) url += `?${new URLSearchParams(options.query).toString()}`;
 	const headers = {
@@ -4359,10 +4859,10 @@ 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$12(server, apiClient) {
+function registerTools$14(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.",
+		"The schema change is applied server-side via an async workflow.",
 		"Authenticates as the developer/agent — pass `pat` (the Personal Access Token returned by amba_developer_signup) or send it as the inbound Bearer.",
 		"Returns the workflow id + version + status. Failure responses include `details.workflow_id` for debugging.",
 		"Errors: 400 RESERVED_NAME / INVALID_COLLECTION_SCHEMA / COLLECTION_MIGRATION_FAILED, 401 MISSING_PAT."
@@ -4379,7 +4879,7 @@ function registerTools$12(server, apiClient) {
 		};
 		if (indexes !== void 0) body.indexes = indexes;
 		if (shared !== void 0) body.shared = shared;
-		return passthroughResult(await adminFetch(apiClient, {
+		return passthroughResult(await adminFetch$1(apiClient, {
 			method: "POST",
 			path: `/projects/${project_id}/collections`,
 			body,
@@ -4398,7 +4898,7 @@ function registerTools$12(server, apiClient) {
 		const query = {};
 		if (limit !== void 0) query.limit = String(limit);
 		if (offset !== void 0) query.offset = String(offset);
-		return passthroughResult(await adminFetch(apiClient, {
+		return passthroughResult(await adminFetch$1(apiClient, {
 			method: "GET",
 			path: `/projects/${project_id}/collections`,
 			query,
@@ -4413,7 +4913,7 @@ function registerTools$12(server, apiClient) {
 		project_id: z.string().describe("The project ID."),
 		name: z.string().describe("Collection name (customer-facing, no `coll_` prefix).")
 	}, async ({ project_id, name }, { pat }) => {
-		return passthroughResult(await adminFetch(apiClient, {
+		return passthroughResult(await adminFetch$1(apiClient, {
 			method: "GET",
 			path: `/projects/${project_id}/collections/${encodeURIComponent(name)}`,
 			bearer: pat
@@ -4428,13 +4928,32 @@ function registerTools$12(server, apiClient) {
 		name: z.string().describe("Collection name to drop."),
 		confirm: z.string().describe("Must equal the collection name. Accident guard for destructive drops.")
 	}, async ({ project_id, name, confirm }, { pat }) => {
-		return passthroughResult(await adminFetch(apiClient, {
+		return passthroughResult(await adminFetch$1(apiClient, {
 			method: "DELETE",
 			path: `/projects/${project_id}/collections/${encodeURIComponent(name)}`,
 			query: { confirm },
 			bearer: pat
 		}));
 	}, ["amba_delete_collection"]);
+	registerTool(server, apiClient, "amba_collections_reset_data", [
+		"Reset a collection: empty ALL of its rows in one call WITHOUT dropping the collection — the schema, columns and indexes survive, only the data is cleared. Use this to wipe a fixture/test collection back to empty between runs without re-creating it (use amba_collections_delete to drop the collection itself).",
+		"Hard by default — rows are permanently removed. Pass `hard:false` to soft-delete instead (sets deleted_at so rows stay recoverable).",
+		"Authenticates as the developer/agent — pass `pat` or send as inbound Bearer.",
+		"Returns the number of rows cleared. Errors: 404 COLLECTION_NOT_FOUND if the collection does not exist."
+	].join(" "), {
+		project_id: z.string().describe("The project ID."),
+		name: z.string().describe("Collection name whose rows to clear."),
+		hard: z.boolean().optional().describe("true (default) permanently deletes every row; false soft-deletes (sets deleted_at) so rows remain recoverable.")
+	}, async ({ project_id, name, hard }, { pat }) => {
+		const query = {};
+		if (hard === false) query.hard = "false";
+		return passthroughResult(await adminFetch$1(apiClient, {
+			method: "DELETE",
+			path: `/projects/${project_id}/collections/${encodeURIComponent(name)}/data`,
+			query,
+			bearer: pat
+		}));
+	});
 	registerTool(server, apiClient, "amba_collections_alter", [
 		"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.",
@@ -4471,7 +4990,7 @@ function registerTools$12(server, apiClient) {
 		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, {
+		return passthroughResult(await adminFetch$1(apiClient, {
 			method: "PATCH",
 			path: `/projects/${project_id}/collections/${encodeURIComponent(name)}`,
 			body,
@@ -4482,13 +5001,15 @@ function registerTools$12(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).",
+		"For developer-seeded GLOBAL content (question banks, lookup tables, daily content) on a shared:true collection, pass as_system=true to write a row with NO owner (user_id = NULL). Rejected with NOT_SHARED_COLLECTION on a non-shared collection — create it with shared:true (or PATCH relax_user_id:true) first.",
 		"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 / INVALID_CONFLICT_TARGET, 404 COLLECTION_NOT_FOUND, 500 CREATE_FAILED."
+		"Errors: 400 INVALID_COLUMN / INVALID_CONFLICT_TARGET / NOT_SHARED_COLLECTION, 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."),
+		as_system: z.boolean().optional().describe("Write a developer-owned GLOBAL row (user_id = NULL) on a shared:true collection — for content the whole app reads (question banks, lookup tables) rather than data owned by one end-user. Mutually exclusive with a row.user_id. Rejected on non-shared collections."),
 		on_conflict: z.enum([
 			"error",
 			"ignore",
@@ -4496,15 +5017,19 @@ function registerTools$12(server, apiClient) {
 		]).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 }) => {
+	}, async ({ project_id, name, row, as_system, 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, {
+		const requestBody = as_system ? {
+			...row,
+			as_system: true
+		} : row;
+		const result = await adminFetch$1(apiClient, {
 			method: "POST",
 			path: `/projects/${project_id}/collections/${encodeURIComponent(name)}/rows`,
-			body: row,
+			body: requestBody,
 			query: Object.keys(query).length > 0 ? query : void 0,
 			bearer: pat
 		});
@@ -4532,7 +5057,7 @@ function registerTools$12(server, apiClient) {
 	}, 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, {
+		return passthroughResult(await adminFetch$1(apiClient, {
 			method: "POST",
 			path: `/projects/${project_id}/collections/${encodeURIComponent(name)}/rows:batch`,
 			body,
@@ -4564,7 +5089,7 @@ function registerTools$12(server, apiClient) {
 		if (cursor !== void 0) findQuery.cursor = cursor;
 		if (select !== void 0) findQuery.select = select;
 		if (include_deleted !== void 0) findQuery.includeDeleted = include_deleted;
-		return passthroughResult(await adminFetch(apiClient, {
+		return passthroughResult(await adminFetch$1(apiClient, {
 			method: "GET",
 			path: `/projects/${project_id}/collections/${encodeURIComponent(name)}/rows`,
 			query: Object.keys(findQuery).length > 0 ? { query: JSON.stringify(findQuery) } : void 0,
@@ -4599,13 +5124,109 @@ function registerTools$12(server, apiClient) {
 		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, {
+		return passthroughResult(await adminFetch$1(apiClient, {
 			method: "POST",
 			path: `/projects/${project_id}/collections/${encodeURIComponent(name)}/rows/aggregate`,
 			body,
 			bearer: pat
 		}));
 	});
+	registerTool(server, apiClient, "amba_admin_update_row", [
+		"Update a single row by id from the developer/agent side — BYPASSES the per-user row scoping the client tools enforce, so it can edit ANY row regardless of which app_user owns it.",
+		"Pass `set` (a column→value map of the fields to write). Server-managed columns (id, created_at, updated_at, deleted_at) are rejected with 400 PROTECTED_COLUMN.",
+		"JSON object values targeting jsonb columns MERGE into the stored object (shallow, atomic merge-patch) instead of replacing it, so concurrent writers patching different keys both survive. Arrays/scalars/null replace the column value. Pass `objects: \"replace\"` to overwrite the whole stored object instead.",
+		"Compare-and-set (optimistic concurrency): pass `expected` (a column→expected-value map) and the update applies ONLY if the row currently still matches those values — otherwise 409 PRECONDITION_FAILED and nothing is written. Null-safe, so `expected: {status: null}` matches a NULL column. Use this for safe read-modify-write (read the row, then update guarded by the values you read) without a transaction.",
+		"For updating many rows by a filter instead of one id, use amba_admin_bulk_update.",
+		"Authenticates as the developer/agent — pass `pat` or send as inbound Bearer.",
+		"Errors: 400 PROTECTED_COLUMN / INVALID_COLUMN / INVALID_BODY, 404 NOT_FOUND (no such row id), 409 PRECONDITION_FAILED (expected mismatch), 404 COLLECTION_NOT_FOUND."
+	].join(" "), {
+		project_id: z.string().describe("The project ID."),
+		name: z.string().describe("Collection name."),
+		id: z.string().describe("Row UUID to update."),
+		set: setSchema.describe("Column-value map to write. Server-managed columns are rejected."),
+		expected: z.record(z.unknown()).optional().describe("Compare-and-set precondition: column→expected-value map. The update applies only if the row currently matches every entry; otherwise 409 PRECONDITION_FAILED and no write occurs. Null-safe (an entry of null matches a NULL column)."),
+		objects: z.enum(["merge", "replace"]).optional().describe("How JSON object values apply to jsonb columns: \"merge\" (default — shallow merge-patch into the stored object) or \"replace\" (overwrite the whole stored object).")
+	}, async ({ project_id, name, id, set, expected, objects }, { pat }) => {
+		return passthroughResult(await adminFetch$1(apiClient, {
+			method: "PATCH",
+			path: `/projects/${project_id}/collections/${encodeURIComponent(name)}/rows/${encodeURIComponent(id)}`,
+			body: expected !== void 0 ? {
+				set,
+				expected
+			} : { set },
+			query: objects === "replace" ? { objects: "replace" } : void 0,
+			bearer: pat
+		}));
+	});
+	registerTool(server, apiClient, "amba_admin_delete_row", [
+		"Delete a single row by id from the developer/agent side — BYPASSES the per-user row scoping the client tools enforce, so it can delete ANY row regardless of which app_user owns it.",
+		"Soft-delete by default (sets deleted_at = NOW() so the row stays recoverable and still appears in admin_list_rows with include_deleted=true). Pass hard=true for a permanent, irreversible DELETE that removes the row entirely.",
+		"Deleting an already-soft-deleted row returns `already_deleted: true` (200), not an error.",
+		"For deleting many rows by a filter instead of one id, use amba_admin_bulk_delete.",
+		"Authenticates as the developer/agent — pass `pat` or send as inbound Bearer.",
+		"Errors: 404 NOT_FOUND (no such row id), 404 COLLECTION_NOT_FOUND, 400 INVALID_UUID."
+	].join(" "), {
+		project_id: z.string().describe("The project ID."),
+		name: z.string().describe("Collection name."),
+		id: z.string().describe("Row UUID to delete."),
+		hard: z.boolean().optional().describe("false (default) soft-deletes (sets deleted_at so the row stays recoverable); true permanently removes the row (irreversible).")
+	}, async ({ project_id, name, id, hard }, { pat }) => {
+		return passthroughResult(await adminFetch$1(apiClient, {
+			method: "DELETE",
+			path: `/projects/${project_id}/collections/${encodeURIComponent(name)}/rows/${encodeURIComponent(id)}`,
+			query: hard === true ? { hard: "true" } : void 0,
+			bearer: pat
+		}));
+	});
+	registerTool(server, apiClient, "amba_admin_bulk_update", [
+		"Update EVERY row matching a `where` filter in one statement, from the developer/agent side — BYPASSES the per-user row scoping the client tools enforce (updates rows across all app_users).",
+		"`where` is REQUIRED — a bulk update with no filter (which would touch the entire collection) is rejected with 400 WHERE_REQUIRED. To update a single row by id, use amba_admin_update_row instead.",
+		"`set` is the column→value map applied to every matched row. Server-managed columns are rejected with 400 PROTECTED_COLUMN.",
+		"JSON object values targeting jsonb columns MERGE into the stored object per row (shallow, atomic merge-patch) instead of replacing it. Arrays/scalars/null replace the column value. Pass `objects: \"replace\"` to overwrite the whole stored object instead.",
+		"Authenticates as the developer/agent — pass `pat` or send as inbound Bearer.",
+		"Returns `{data: {updated: <n>, ids: [...]}}`. Errors: 400 WHERE_REQUIRED / PROTECTED_COLUMN / INVALID_COLUMN, 404 COLLECTION_NOT_FOUND."
+	].join(" "), {
+		project_id: z.string().describe("The project ID."),
+		name: z.string().describe("Collection name."),
+		set: setSchema.describe("Column-value map applied to every matched row. Required."),
+		where: adminFindWhereSchema.describe("Server WhereClause selecting which rows to update. REQUIRED — there is no \"update all\" shortcut; pass a filter that matches the rows you intend to change."),
+		objects: z.enum(["merge", "replace"]).optional().describe("How JSON object values apply to jsonb columns: \"merge\" (default — shallow merge-patch into the stored object) or \"replace\" (overwrite the whole stored object).")
+	}, async ({ project_id, name, set, where, objects }, { pat }) => {
+		return passthroughResult(await adminFetch$1(apiClient, {
+			method: "PATCH",
+			path: `/projects/${project_id}/collections/${encodeURIComponent(name)}/rows`,
+			body: {
+				set,
+				where
+			},
+			query: objects === "replace" ? { objects: "replace" } : void 0,
+			bearer: pat
+		}));
+	});
+	registerTool(server, apiClient, "amba_admin_bulk_delete", [
+		"Delete EVERY row matching a `where` filter in one statement, from the developer/agent side — BYPASSES the per-user row scoping the client tools enforce (deletes rows across all app_users).",
+		"`where` is REQUIRED — a bulk delete with no filter is rejected. To delete a single row by id, use amba_admin_delete_row.",
+		"Foot-gun guard: `confirm` MUST equal the exact number of rows the `where` filter currently matches. Preview that count first with amba_admin_list_rows (or the count endpoint), then pass it as `confirm`. If the live count differs (e.g. a concurrent write changed it), the delete aborts with 400 CONFIRMATION_MISMATCH and nothing is removed.",
+		"Soft-delete by default (sets deleted_at). Pass hard=true for a permanent, irreversible DELETE of every matched row.",
+		"Authenticates as the developer/agent — pass `pat` or send as inbound Bearer.",
+		"Returns `{data: {deleted: <n>, ids: [...], mode}}`. Errors: 400 WHERE_REQUIRED / CONFIRMATION_REQUIRED / CONFIRMATION_MISMATCH, 404 COLLECTION_NOT_FOUND."
+	].join(" "), {
+		project_id: z.string().describe("The project ID."),
+		name: z.string().describe("Collection name."),
+		where: adminFindWhereSchema.describe("Server WhereClause selecting which rows to delete. REQUIRED."),
+		confirm: z.number().int().nonnegative().describe("The exact number of rows the `where` filter currently matches (preview via amba_admin_list_rows). The delete proceeds only if the live count equals this; otherwise 400 CONFIRMATION_MISMATCH and nothing is deleted."),
+		hard: z.boolean().optional().describe("false (default) soft-deletes (sets deleted_at, recoverable); true permanently removes every matched row (irreversible).")
+	}, async ({ project_id, name, where, confirm, hard }, { pat }) => {
+		const query = { confirm: String(confirm) };
+		if (hard === true) query.hard = "true";
+		return passthroughResult(await adminFetch$1(apiClient, {
+			method: "DELETE",
+			path: `/projects/${project_id}/collections/${encodeURIComponent(name)}/rows`,
+			body: { where },
+			query,
+			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.).",
@@ -4689,6 +5310,7 @@ function registerTools$12(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.",
+		"JSON object values targeting jsonb columns MERGE into the stored object (shallow, atomic merge-patch) instead of replacing it, so concurrent writers patching different keys both survive. Arrays/scalars/null replace the column value. Pass `objects: \"replace\"` to overwrite the whole stored object instead.",
 		"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.",
@@ -4700,10 +5322,12 @@ function registerTools$12(server, apiClient) {
 		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."),
+		objects: z.enum(["merge", "replace"]).optional().describe("How JSON object values apply to jsonb columns: \"merge\" (default — shallow merge-patch into the stored object) or \"replace\" (overwrite the whole stored object)."),
 		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, expected, limit, api_key, session_token }) => {
+	}, async ({ name, id, where, set, expected, limit, objects, api_key, session_token }) => {
 		if (!api_key) return MISSING_API_KEY_ERROR;
+		const objectsQuery = objects === "replace" ? { objects: "replace" } : void 0;
 		if (id !== void 0) return passthroughResult(await clientFetch(apiClient, {
 			method: "PATCH",
 			path: `/collections/${encodeURIComponent(name)}/${encodeURIComponent(id)}`,
@@ -4711,6 +5335,7 @@ function registerTools$12(server, apiClient) {
 				set,
 				expected
 			} : { set },
+			...objectsQuery !== void 0 && { query: objectsQuery },
 			apiKey: api_key,
 			...session_token !== void 0 && { sessionToken: session_token }
 		}));
@@ -4723,6 +5348,7 @@ function registerTools$12(server, apiClient) {
 			method: "PATCH",
 			path: `/collections/${encodeURIComponent(name)}`,
 			body,
+			...objectsQuery !== void 0 && { query: objectsQuery },
 			apiKey: api_key,
 			...session_token !== void 0 && { sessionToken: session_token }
 		}));
@@ -4863,6 +5489,47 @@ function registerTools$12(server, apiClient) {
 			...session_token !== void 0 && { sessionToken: session_token }
 		}));
 	});
+	server.tool("amba_client_aggregate_rows", [
+		"Run a group-by aggregation over a collection as the signed-in app_user — server-side, no rows shipped to the client.",
+		"Supports count / sum / avg / min / max, optionally grouped by one or more columns. count without a column = COUNT(*).",
+		"Auto-RLS — the aggregate covers only rows the app_user owns (plus shared/unowned rows) AND'd with the live deleted_at filter; pass include_deleted=true to include soft-deleted rows.",
+		"Roll a leaderboard, a spend total, a per-category count, or a daily streak summary in one round-trip instead of paging every row. Pairs naturally with amba_client_find_rows for the drill-down.",
+		"Authenticates as the end-user — pass `api_key` + `session_token`.",
+		"Returns `{data: [...]}` — one row per group (or a single row when group_by is omitted), each aggregation under its alias."
+	].join(" "), {
+		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."),
+		filter: sdkFilterSchema.optional(),
+		where: adminFindWhereSchema.optional(),
+		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, select, group_by, filter, where, include_deleted, api_key, session_token }) => {
+		if (!api_key) return MISSING_API_KEY_ERROR;
+		const body = { select };
+		if (group_by !== void 0) body.group_by = group_by;
+		if (filter !== void 0) body.filter = filter;
+		if (where !== void 0) body.where = where;
+		if (include_deleted !== void 0) body.include_deleted = include_deleted;
+		return passthroughResult(await clientFetch(apiClient, {
+			method: "POST",
+			path: `/collections/${encodeURIComponent(name)}/aggregate`,
+			body,
+			apiKey: api_key,
+			...session_token !== void 0 && { sessionToken: session_token }
+		}));
+	});
 }
 //#endregion
 //#region src/tools/_pat.ts
@@ -4978,7 +5645,7 @@ function jsonResult(payload) {
 * of a generic upstream 400.
 */
 const MAX_BUNDLE_BYTES = 10 * 1024 * 1024;
-function registerTools$11(server, apiClient) {
+function registerTools$13(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).",
@@ -5106,7 +5773,7 @@ function registerTools$11(server, apiClient) {
 }
 //#endregion
 //#region src/tools/sites.ts
-function registerTools$10(server, apiClient) {
+function registerTools$12(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`.",
@@ -5198,7 +5865,7 @@ function registerTools$10(server, apiClient) {
 }
 //#endregion
 //#region src/tools/domains.ts
-function registerTools$9(server, apiClient) {
+function registerTools$11(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\")."),
@@ -5253,8 +5920,41 @@ function registerTools$9(server, apiClient) {
 	});
 }
 //#endregion
+//#region src/tools/operations.ts
+function registerTools$10(server, apiClient) {
+	registerTool(server, apiClient, "amba_operations_get", [
+		"Poll an async operation by its operation_id to see whether it has finished.",
+		"Returns the operation `status` (pending | running | succeeded | failed); on `failed`, `failed_reason` says why, and on `succeeded`, `result` holds the outcome.",
+		"Use this after a tool returns an `operation_id` (e.g. amba_domains_purchase): re-call until status is succeeded or failed instead of re-running the action."
+	].join(" "), {
+		project_id: z.string().describe("The Amba project ID."),
+		operation_id: z.string().describe("The operation handle id returned by the tool that started the work.")
+	}, async ({ project_id, operation_id }, { pat }) => {
+		return jsonResult(await callWithPat(apiClient, pat, "GET", `/projects/${encodeURIComponent(project_id)}/operations/${encodeURIComponent(operation_id)}`));
+	});
+	registerTool(server, apiClient, "amba_operations_list", ["List async operations for a project, newest first. Optionally filter by `kind` (e.g. \"domain_purchase\") and/or `status` (pending | running | succeeded | failed).", "Read-only — useful to find an in-flight operation or review recent ones."].join(" "), {
+		project_id: z.string().describe("The Amba project ID."),
+		kind: z.string().optional().describe("Filter to one operation kind, e.g. \"domain_purchase\"."),
+		status: z.enum([
+			"pending",
+			"running",
+			"succeeded",
+			"failed"
+		]).optional().describe("Filter to one lifecycle status."),
+		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, kind, status, limit, offset }, { pat }) => {
+		const query = {};
+		if (kind !== void 0) query.kind = kind;
+		if (status !== void 0) query.status = status;
+		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)}/operations`, { query }));
+	});
+}
+//#endregion
 //#region src/tools/secrets.ts
-function registerTools$8(server, apiClient) {
+function registerTools$9(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).",
@@ -5327,17 +6027,249 @@ function registerTools$8(server, apiClient) {
 const PROVIDER_ENUM$1 = z.enum([
 	"anthropic",
 	"openai",
-	"mistral"
+	"mistral",
+	"gemini"
 ]);
 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$7(server, apiClient) {
+const DEFAULT_IMAGE_MIME = "image/png";
+/**
+* Normalize an image's `url` / `data` to non-empty values, trimming whitespace
+* and treating a blank result as absent. Returns `null` when NEITHER a real url
+* nor real data survives — such a block carries no image and is dropped by the
+* caller (instead of emitting an empty image URL or an empty base64 block).
+*/
+function normalizeImage(img) {
+	const url = typeof img.url === "string" && img.url.trim().length > 0 ? img.url.trim() : void 0;
+	const data = typeof img.data === "string" && img.data.trim().length > 0 ? img.data.trim() : void 0;
+	if (!url && !data) return null;
+	return {
+		url,
+		data,
+		mime: img.mime
+	};
+}
+/**
+* Map a NORMALIZED vendor-neutral image into the provider's native
+* content-block shape. Anthropic → `{type:'image', source:{...}}`;
+* OpenAI/Mistral → `{type:'image_url', image_url:{url}}` (base64 becomes a
+* data: URL); Gemini → a `parts[]` entry (`inline_data` for base64,
+* `file_data` for a URL). The input is guaranteed to have a real `url` or
+* real `data`.
+*
+* Note: Gemini's image shape is a `contents[].parts[]` entry, NOT a message
+* `content[]` block — so the Gemini path builds `contents[]` directly via
+* `geminiContentsFromMessages` and does NOT route image mapping through
+* `attachImagesToMessages` (which speaks the OpenAI/Anthropic message-content
+* shape). This helper is reused there for the per-part mapping.
+*/
+function imageBlockForProvider(img, provider) {
+	const mime = img.mime ?? DEFAULT_IMAGE_MIME;
+	if (provider === "anthropic") return img.url ? {
+		type: "image",
+		source: {
+			type: "url",
+			url: img.url
+		}
+	} : {
+		type: "image",
+		source: {
+			type: "base64",
+			media_type: mime,
+			data: img.data ?? ""
+		}
+	};
+	if (provider === "gemini") return img.url ? { file_data: {
+		mime_type: mime,
+		file_uri: img.url
+	} } : { inline_data: {
+		mime_type: mime,
+		data: img.data ?? ""
+	} };
+	return {
+		type: "image_url",
+		image_url: { url: img.url ?? `data:${mime};base64,${img.data ?? ""}` }
+	};
+}
+/**
+* Convert ONE content block from a message's content array into the provider's
+* native shape. A vendor-neutral `{type:'image', url|data}` block is mapped via
+* `imageBlockForProvider`; everything else (a `{type:'text'}` block, or an
+* already-native block the agent supplied) passes through unchanged. This keeps
+* the whole message in a SINGLE format so we never mix vendor-neutral and
+* pre-mapped native image blocks in one message (which would be malformed for
+* the raw `/ai/messages` passthrough).
+*
+* Returns `null` only for a vendor-neutral image block that normalizes away
+* (blank url + blank data) — the caller drops it.
+*/
+function nativeContentBlock(block, provider) {
+	if (typeof block === "object" && block !== null) {
+		const b = block;
+		if (b["type"] === "image" && ("url" in b || "data" in b) && !("source" in b)) {
+			const norm = normalizeImage({
+				url: typeof b["url"] === "string" ? b["url"] : void 0,
+				data: typeof b["data"] === "string" ? b["data"] : void 0,
+				mime: typeof b["mime"] === "string" ? b["mime"] : void 0
+			});
+			return norm ? imageBlockForProvider(norm, provider) : null;
+		}
+	}
+	return block;
+}
+/** Does a message's `content` array carry any vendor-neutral image block? */
+function contentHasNeutralImage(content) {
+	if (!Array.isArray(content)) return false;
+	return content.some((b) => {
+		if (typeof b !== "object" || b === null) return false;
+		const bb = b;
+		return bb["type"] === "image" && ("url" in bb || "data" in bb) && !("source" in bb);
+	});
+}
+/** Does ANY message carry a vendor-neutral image block in its content array? */
+function messagesHaveNeutralImage(messages) {
+	return messages.some((m) => contentHasNeutralImage(m?.content));
+}
+/**
+* Normalize ONE message's content array into a single native-shaped block list:
+* a string → a `[{type:'text', text}]` block (empty string → no block); an
+* array → its blocks mapped via `nativeContentBlock` (vendor-neutral images to
+* native, others untouched, normalize-away blocks dropped). Returns the block
+* list for the array/string cases; for any other value returns `null` so the
+* caller can leave it untouched (don't coerce a shape we don't understand).
+*/
+function normalizeContentBlocks(content, provider) {
+	if (typeof content === "string") return content.length > 0 ? [{
+		type: "text",
+		text: content
+	}] : [];
+	if (Array.isArray(content)) return content.map((b) => nativeContentBlock(b, provider)).filter((b) => b !== null);
+	return null;
+}
+/**
+* Map a registered prompt's `messages` into a single provider-native format AND
+* (optionally) attach extra `images` to the last user message.
+*
+* Because `amba_ai_prompts_invoke` posts through the raw `/ai/messages`
+* passthrough (byte-for-byte to the provider — the gateway does NOT remap this
+* path), any VENDOR-NEUTRAL `{type:'image', url|data}` block — whether it came
+* from the `images` convenience param OR was put directly in `messages` by the
+* caller — must be mapped to the provider's native shape HERE.
+*
+* Conservative by design: a message is rewritten ONLY when it needs it — it
+* carries vendor-neutral image blocks, OR it's the last user message receiving
+* appended `images`. Plain text / already-native messages pass through
+* byte-identical (no needless string→block conversion). When no user message
+* exists but extra `images` were supplied, a fresh user message is appended.
+* Returns a NEW array — the caller's `messages` is never mutated.
+*/
+function attachImagesToMessages(messages, images, provider) {
+	const imageBlocks = images.map(normalizeImage).filter((img) => img !== null).map((img) => imageBlockForProvider(img, provider));
+	const out = messages.map((m) => ({ ...m }));
+	let lastUserIdx = -1;
+	for (let i = out.length - 1; i >= 0; i--) if (out[i].role === "user") {
+		lastUserIdx = i;
+		break;
+	}
+	for (let i = 0; i < out.length; i++) {
+		const isTarget = i === lastUserIdx && imageBlocks.length > 0;
+		const needsImageMapping = contentHasNeutralImage(out[i].content);
+		if (!isTarget && !needsImageMapping) continue;
+		const blocks = normalizeContentBlocks(out[i].content, provider);
+		if (blocks === null) {
+			if (isTarget) out[i] = {
+				...out[i],
+				content: [{
+					type: "text",
+					text: JSON.stringify(out[i].content ?? "")
+				}, ...imageBlocks]
+			};
+			continue;
+		}
+		const withImages = isTarget ? [...blocks, ...imageBlocks] : blocks;
+		if (withImages.length === 0) continue;
+		out[i] = {
+			...out[i],
+			content: withImages
+		};
+	}
+	if (lastUserIdx === -1 && imageBlocks.length > 0) out.push({
+		role: "user",
+		content: imageBlocks
+	});
+	return out;
+}
+/**
+* Map ONE message's content into Gemini `parts`. A string → a single
+* `{text}` part; a non-string, non-array value → one JSON-stringified `{text}`
+* part; an array → each block mapped (vendor-neutral text → `{text}`,
+* vendor-neutral image → `inline_data`/`file_data`, a normalize-away image
+* dropped, and any UNKNOWN/alien block — e.g. an OpenAI `image_url` or
+* Anthropic `source` shape — dropped). Mirrors the gateway's
+* `mapContentGeminiParts` exactly so a server-side test invocation produces the
+* same upstream body the production `/prompts/:name/invoke` path does.
+*/
+function geminiPartsForContent(content) {
+	if (typeof content === "string") return [{ text: content }];
+	if (!Array.isArray(content)) return [{ text: JSON.stringify(content ?? "") }];
+	const parts = [];
+	for (const block of content) {
+		if (typeof block !== "object" || block === null) continue;
+		const b = block;
+		if (b["type"] === "text" && typeof b["text"] === "string") {
+			parts.push({ text: b["text"] });
+			continue;
+		}
+		if (b["type"] === "image" && ("url" in b || "data" in b)) {
+			const norm = normalizeImage({
+				url: typeof b["url"] === "string" ? b["url"] : void 0,
+				data: typeof b["data"] === "string" ? b["data"] : void 0,
+				mime: typeof b["mime"] === "string" ? b["mime"] : void 0
+			});
+			if (norm) parts.push(imageBlockForProvider(norm, "gemini"));
+			continue;
+		}
+	}
+	return parts;
+}
+/**
+* Build Gemini's `contents[]` from a registered prompt's `messages`, mapping
+* roles (assistant/model → "model", everything else → "user"), translating
+* content into `parts`, and appending any extra `images` to the last user turn
+* (creating one if none exists). Messages whose content maps to NO parts are
+* dropped (an empty turn is rejected upstream). Returns a NEW array — the
+* caller's `messages` is never mutated.
+*/
+function geminiContentsFromMessages(messages, images) {
+	const imageParts = images.map(normalizeImage).filter((img) => img !== null).map((img) => imageBlockForProvider(img, "gemini"));
+	const contents = messages.map((m) => ({
+		role: m.role === "assistant" || m.role === "model" ? "model" : "user",
+		parts: geminiPartsForContent(m.content)
+	}));
+	if (imageParts.length > 0) {
+		let lastUserIdx = -1;
+		for (let i = contents.length - 1; i >= 0; i--) if (contents[i].role === "user") {
+			lastUserIdx = i;
+			break;
+		}
+		if (lastUserIdx === -1) contents.push({
+			role: "user",
+			parts: [...imageParts]
+		});
+		else contents[lastUserIdx] = {
+			role: "user",
+			parts: [...contents[lastUserIdx].parts, ...imageParts]
+		};
+	}
+	return contents.filter((c) => c.parts.length > 0);
+}
+function registerTools$8(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\", \"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\").",
+		"Name must match /^[a-z][a-z0-9_-]{0,127}$/. Provider must be \"anthropic\", \"openai\", \"mistral\", or \"gemini\" 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\", \"gemini-2.5-flash\").",
 		"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(" "), {
@@ -5401,8 +6333,9 @@ function registerTools$7(server, apiClient) {
 		});
 	}, ["amba_delete_ai_prompt"]);
 	registerTool(server, apiClient, "amba_ai_prompts_invoke", [
-		"Server-side test invocation of a registered AI prompt. Looks up the prompt's provider + model + system_prompt + max_tokens, then proxies a Messages-API call through the admin AI gateway using the customer's registered provider key.",
-		"Provide `messages` as a provider-shaped array (e.g. Anthropic: `[{role: \"user\", content: \"...\"}]`). For testing — production traffic goes through the SDK or the function-side `ctx.ai.run()` helper.",
+		"Server-side test invocation of a registered AI prompt. Looks up the prompt's provider + model + system_prompt + max_tokens, then proxies the call through the admin AI gateway using the customer's registered provider key. Works for every provider — Anthropic / OpenAI / Mistral build a Messages-style body; Gemini builds its contents[] body automatically.",
+		"Provide `messages` as a simple `[{role: \"user\", content: \"...\"}]` array (roles: \"user\"/\"assistant\"/\"system\"; for Gemini, \"assistant\" maps to \"model\" and \"system\" is taken from the prompt). For testing — production traffic goes through the SDK or the function-side `ctx.ai.run()` helper.",
+		"To send IMAGES to a vision-capable model, pass `images` (each `{url}` or `{data, mime}`) — they attach to the last user message, mapped to the provider's native image format for you. The prompt's model must be vision-capable.",
 		"`extra_body` lets you pass additional provider-native parameters (temperature, top_p, response_format, …). These are merged shallow on top of the prompt-derived body — so a `model` override here wins."
 	].join(" "), {
 		project_id: z.string().describe("The Amba project ID."),
@@ -5411,21 +6344,39 @@ function registerTools$7(server, apiClient) {
 			role: z.string().describe("Anthropic / OpenAI role (e.g. \"user\", \"assistant\", \"system\")."),
 			content: z.unknown().describe("Message content. String or provider-native array form.")
 		})).min(1).describe("Provider-shaped messages array. At least one message required."),
+		images: z.array(z.object({
+			url: z.string().optional().describe("Remote image URL. Use this OR `data` (base64), not both."),
+			data: z.string().optional().describe("Base64-encoded image bytes (no data: prefix)."),
+			mime: z.string().optional().describe("MIME type for a base64 image (e.g. \"image/png\"). Defaults to image/png.")
+		})).optional().describe("Optional vision input. Each image attaches to the last user message and is mapped to the provider's native image format. The prompt's model must be vision-capable (e.g. claude-sonnet-4-5, gpt-4o, gemini-2.5-pro)."),
 		extra_body: z.record(z.unknown()).optional().describe("Optional extra fields merged into the upstream body. Allowlisted keys only: temperature, top_p, top_k, stop, stop_sequences, response_format, frequency_penalty, presence_penalty, seed, tools, tool_choice, metadata. Unrecognised keys are rejected to prevent provider-body smuggling (e.g. authorization, model overrides).")
-	}, async ({ project_id, name, messages, extra_body }, { pat }) => {
+	}, async ({ project_id, name, messages, images, extra_body }, { pat }) => {
 		const prompt = (await callWithPat(apiClient, pat, "GET", `/projects/${encodeURIComponent(project_id)}/ai/prompts/${encodeURIComponent(name)}`) ?? {}).data;
 		if (!prompt) throw new Error(`Prompt "${name}" not found.`);
-		const body = {
-			model: prompt.model,
-			max_tokens: prompt.max_tokens
-		};
-		if (prompt.provider === "anthropic") {
-			if (prompt.system_prompt) body.system = prompt.system_prompt;
-			body.messages = messages;
-		} else body.messages = prompt.system_prompt ? [{
-			role: "system",
-			content: prompt.system_prompt
-		}, ...messages] : messages;
+		const hasImagesParam = Array.isArray(images) && images.length > 0;
+		let body;
+		if (prompt.provider === "gemini") {
+			body = {
+				model: prompt.model,
+				contents: geminiContentsFromMessages(messages, images ?? []),
+				generationConfig: { maxOutputTokens: prompt.max_tokens }
+			};
+			if (prompt.system_prompt) body.systemInstruction = { parts: [{ text: prompt.system_prompt }] };
+		} else {
+			const messagesHaveImageBlocks = messagesHaveNeutralImage(messages);
+			const effectiveMessages = hasImagesParam || messagesHaveImageBlocks ? attachImagesToMessages(messages, images ?? [], prompt.provider) : messages;
+			body = {
+				model: prompt.model,
+				max_tokens: prompt.max_tokens
+			};
+			if (prompt.provider === "anthropic") {
+				if (prompt.system_prompt) body.system = prompt.system_prompt;
+				body.messages = effectiveMessages;
+			} else body.messages = prompt.system_prompt ? [{
+				role: "system",
+				content: prompt.system_prompt
+			}, ...effectiveMessages] : effectiveMessages;
+		}
 		if (extra_body) {
 			const ALLOWED_EXTRA_KEYS = new Set([
 				"temperature",
@@ -5441,16 +6392,67 @@ function registerTools$7(server, apiClient) {
 				"tool_choice",
 				"metadata"
 			]);
-			for (const [k, v] of Object.entries(extra_body)) {
-				if (!ALLOWED_EXTRA_KEYS.has(k)) throw new Error(`extra_body key "${k}" is not allowed. Allowlist: ${Array.from(ALLOWED_EXTRA_KEYS).join(", ")}`);
-				body[k] = v;
-			}
+			for (const k of Object.keys(extra_body)) if (!ALLOWED_EXTRA_KEYS.has(k)) throw new Error(`extra_body key "${k}" is not allowed. Allowlist: ${Array.from(ALLOWED_EXTRA_KEYS).join(", ")}`);
+			if (prompt.provider === "gemini") {
+				const gc = body.generationConfig ?? {};
+				const GEMINI_KEY = {
+					temperature: "temperature",
+					top_p: "topP",
+					top_k: "topK",
+					seed: "seed",
+					frequency_penalty: "frequencyPenalty",
+					presence_penalty: "presencePenalty"
+				};
+				for (const [k, v] of Object.entries(extra_body)) if (k === "stop" || k === "stop_sequences") gc.stopSequences = Array.isArray(v) ? v : [v];
+				else if (k === "response_format") {
+					const rf = typeof v === "object" && v !== null ? v : null;
+					const rfType = rf?.["type"];
+					if (rfType === "json_object") gc.responseMimeType = "application/json";
+					else if (rfType === "json_schema") {
+						gc.responseMimeType = "application/json";
+						const schema = rf && typeof rf["schema"] === "object" && rf["schema"] !== null ? rf["schema"] : void 0;
+						if (schema !== void 0) gc.responseSchema = schema;
+					}
+				} else if (k in GEMINI_KEY) gc[GEMINI_KEY[k]] = v;
+				else body[k] = v;
+				body.generationConfig = gc;
+			} else for (const [k, v] of Object.entries(extra_body)) body[k] = v;
 		}
 		return jsonResult(await callWithPat(apiClient, pat, "POST", `/projects/${encodeURIComponent(project_id)}/ai/messages`, { body: {
 			provider: prompt.provider,
 			body
 		} }));
 	}, ["amba_invoke_ai_prompt"]);
+	registerTool(server, apiClient, "amba_ai_prompts_set_budget", [
+		"Set (or clear) a per-prompt AI spend budget. Caps how much this one prompt can spend on model calls per period; once the period's spend reaches the budget, invocations are denied with a clear `ai_budget_exceeded` error until the period resets — so an exposed prompt can't burn unbounded spend.",
+		"Pass `budget_usd` as a dollar amount (e.g. 25 = $25). Pass `budget_usd: null` to remove the budget (unlimited — the default). `budget_period` is the reset cadence: \"monthly\" (default), \"daily\", or \"total\" (never resets).",
+		"Returns the persisted budget. For the whole-project ceiling instead, use `amba_billing_set_ceiling`."
+	].join(" "), {
+		project_id: z.string().describe("The Amba project ID."),
+		name: z.string().describe("Registered prompt name to budget."),
+		budget_usd: z.number().min(0).max(1e6).nullable().describe("Per-period USD ceiling. Pass null to clear the budget (unlimited)."),
+		budget_period: z.enum([
+			"daily",
+			"monthly",
+			"total"
+		]).optional().describe("Reset cadence. Defaults to \"monthly\" when a budget is set.")
+	}, async ({ project_id, name, budget_usd, budget_period }, { pat }) => {
+		const body = { budget_usd };
+		if (budget_period !== void 0) body.budget_period = budget_period;
+		return jsonResult(await callWithPat(apiClient, pat, "PUT", `/projects/${encodeURIComponent(project_id)}/ai/prompts/${encodeURIComponent(name)}/budget`, { body }));
+	});
+	registerTool(server, apiClient, "amba_ai_prompts_get_spend", ["Read a prompt's AI spend for the current budget period, alongside its budget (if any). Returns { name, period, period_start, spend_usd, budget_usd, exceeded }.", "Spend is summed from the per-call cost of every invocation in the period. Use this to check headroom before raising a budget, or to diagnose an `ai_budget_exceeded` denial. Pass `period` to inspect a different window (defaults to the prompt's configured period, or \"monthly\")."].join(" "), {
+		project_id: z.string().describe("The Amba project ID."),
+		name: z.string().describe("Registered prompt name."),
+		period: z.enum([
+			"daily",
+			"monthly",
+			"total"
+		]).optional().describe("Spend window to report. Defaults to the prompt's configured budget period.")
+	}, async ({ project_id, name, period }, { pat }) => {
+		const query = period ? `?period=${encodeURIComponent(period)}` : "";
+		return jsonResult(await callWithPat(apiClient, pat, "GET", `/projects/${encodeURIComponent(project_id)}/ai/prompts/${encodeURIComponent(name)}/spend${query}`));
+	});
 }
 //#endregion
 //#region src/tools/ai-providers-admin.ts
@@ -5460,7 +6462,7 @@ const PROVIDER_ENUM = z.enum([
 	"mistral",
 	"gemini"
 ]);
-function registerTools$6(server, apiClient) {
+function registerTools$7(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.",
@@ -5500,7 +6502,7 @@ const STATUS_ENUM = z.enum([
 	"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) {
+function registerTools$6(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",
@@ -5603,7 +6605,7 @@ function registerTools$5(server, apiClient) {
 }
 //#endregion
 //#region src/tools/promotion.ts
-function registerTools$4(server, apiClient) {
+function registerTools$5(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.",
@@ -5709,7 +6711,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$3(server, apiClient) {
+function registerTools$4(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: [{
@@ -5735,6 +6737,80 @@ function registerTools$3(server, apiClient) {
 	});
 }
 //#endregion
+//#region src/tools/payments.ts
+function registerTools$3(server, apiClient) {
+	registerTool(server, apiClient, "amba_payments_account_create", "Create the project's connected payments account so the app can accept payments from its users (the app is the seller; Amba takes a platform fee, Stripe carries the money). Idempotent — returns the existing account if one is already set up. After this, call amba_payments_onboarding_link to finish setup. Note: payments must be enabled on the Amba platform by the platform owner before live accounts can be created.", {
+		project_id: z.string().describe("The project ID"),
+		country: z.string().length(2).optional().describe("Two-letter ISO country code for the seller (e.g. \"US\")"),
+		email: z.string().optional().describe("Contact email for the connected account")
+	}, async ({ project_id, country, email }, { client }) => {
+		const result = await client.post(`/projects/${project_id}/payments/accounts`, {
+			...country ? { country } : {},
+			...email ? { email } : {}
+		});
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_payments_create_onboarding_link", "Generate a hosted onboarding URL the seller opens to finish setting up payments (identity, bank details — handled entirely by the payment provider, Amba never sees identity documents). Surface this URL to the human as a copy box. The link is single-use and short-lived; generate a fresh one if it expires.", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
+		const result = await client.post(`/projects/${project_id}/payments/accounts/link`, {});
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_payments_account_status", "Read the connected payments account status — onboarding stage, whether charges and payouts are enabled, and the configured default platform fee. Returns connected_account: null when payments are not set up for the project yet. Check this before attempting a charge.", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/payments/accounts`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_payments_set_fee", "Set the default platform fee taken on each payment, in basis points (e.g. 250 = 2.5%). Applied when a charge does not specify its own fee. Pass null to clear the default (each charge must then specify a fee explicitly). This is a money-affecting setting — surface it to the human before calling.", {
+		project_id: z.string().describe("The project ID"),
+		default_platform_fee_bps: z.number().int().min(0).max(1e4).nullable().describe("Platform fee in basis points (250 = 2.5%), or null to clear")
+	}, async ({ project_id, default_platform_fee_bps }, { client }) => {
+		const result = await client.put(`/projects/${project_id}/payments/config`, { default_platform_fee_bps });
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_payments_charge", "Create a payment (destination charge) on behalf of the seller, taking the platform fee. amount is in the smallest currency unit (cents). The fee is the platform fee (application_fee_amount) — provide application_fee_amount (cents) OR platform_fee_bps (basis points), else the project default is used. Returns a client_secret the app uses to confirm the payment on-device. Money-moving action — surface to the human before calling.", {
+		project_id: z.string().describe("The project ID"),
+		amount: z.number().int().positive().describe("Amount in smallest currency unit (cents)"),
+		currency: z.string().length(3).describe("3-letter ISO currency code (lowercase, e.g. \"usd\")"),
+		application_fee_amount: z.number().int().min(0).optional().describe("Platform fee in cents (overrides bps/default)"),
+		platform_fee_bps: z.number().int().min(0).max(1e4).optional().describe("Platform fee in basis points (250 = 2.5%)"),
+		client_reference: z.string().optional().describe("Opaque reference (e.g. your order id) stored with the payment")
+	}, async ({ project_id, ...body }, { client }) => {
+		const result = await client.post(`/projects/${project_id}/payments/charges`, body);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_payments_balance", "Read the seller's available and pending payment balance per currency. Use this to show the developer how much they've earned that hasn't yet been paid out.", { project_id: z.string().describe("The project ID") }, async ({ project_id }, { client }) => {
+		const result = await client.get(`/projects/${project_id}/payments/balance`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	registerTool(server, apiClient, "amba_payments_payouts", "List the seller's recent payouts (transfers from the payment balance to their bank), with amount, currency, status, and arrival date.", {
+		project_id: z.string().describe("The project ID"),
+		limit: z.number().int().min(1).max(100).optional().describe("How many payouts to return (default 10)")
+	}, async ({ project_id, limit }, { client }) => {
+		const qs = limit ? `?limit=${limit}` : "";
+		const result = await client.get(`/projects/${project_id}/payments/payouts${qs}`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+}
+//#endregion
 //#region src/tools/invites.ts
 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).", {
@@ -7846,7 +8922,9 @@ const TOOL_CATEGORY = {
 	amba_users_delete: "identity",
 	amba_users_export: "identity",
 	amba_users_bulk_update: "identity",
+	amba_users_create_cohort: "identity",
 	amba_users_reset_sandbox: "identity",
+	amba_users_reset_user: "identity",
 	amba_users_events_export: "identity",
 	amba_users_list_events: "identity",
 	amba_api_keys_create: "identity",
@@ -7898,6 +8976,9 @@ const TOOL_CATEGORY = {
 	amba_content_list_items: "engagement",
 	amba_content_update_item: "engagement",
 	amba_content_delete_item: "engagement",
+	amba_content_translations_set: "engagement",
+	amba_content_translations_list: "engagement",
+	amba_content_translations_delete: "engagement",
 	amba_content_bulk_import: "engagement",
 	amba_content_schedules_create: "engagement",
 	amba_create_content_schedule: "engagement",
@@ -7980,6 +9061,16 @@ const TOOL_CATEGORY = {
 	amba_delete_challenge: "gamification",
 	amba_challenges_list_participants: "gamification",
 	amba_list_challenge_participants: "gamification",
+	amba_monetization_plan: "economy",
+	amba_monetization_drift: "economy",
+	amba_monetization_export: "economy",
+	amba_monetization_definitions_list: "economy",
+	amba_monetization_adopt: "economy",
+	amba_entitlements_define: "economy",
+	amba_products_create: "economy",
+	amba_entitlements_map_product: "economy",
+	amba_offerings_create: "economy",
+	amba_offerings_list: "economy",
 	amba_currencies_create: "economy",
 	amba_create_currency: "economy",
 	amba_currencies_list: "economy",
@@ -7993,6 +9084,7 @@ const TOOL_CATEGORY = {
 	amba_currencies_spend: "economy",
 	amba_currencies_get_transactions: "economy",
 	amba_get_currency_transactions: "economy",
+	amba_currencies_get_user_balance: "economy",
 	amba_currency_grant_rules_create: "economy",
 	amba_currency_grant_rules_list: "economy",
 	amba_currency_grant_rules_delete: "economy",
@@ -8026,6 +9118,7 @@ const TOOL_CATEGORY = {
 	amba_stores_delete_listing: "economy",
 	amba_inventory_grant_item: "economy",
 	amba_inventory_revoke_item: "economy",
+	amba_entitlements_grant: "economy",
 	amba_grant_item: "economy",
 	amba_users_get_inventory: "economy",
 	amba_get_user_inventory: "economy",
@@ -8086,6 +9179,8 @@ const TOOL_CATEGORY = {
 	amba_moderation_list_trust: "social",
 	amba_events_list: "analytics",
 	amba_events_count: "analytics",
+	amba_events_track: "analytics",
+	amba_events_explain: "analytics",
 	amba_analytics_get: "analytics",
 	amba_get_analytics: "analytics",
 	amba_sessions_list: "analytics",
@@ -8128,7 +9223,12 @@ const TOOL_CATEGORY = {
 	amba_alter_collection: "infrastructure",
 	amba_collections_delete: "infrastructure",
 	amba_delete_collection: "infrastructure",
+	amba_collections_reset_data: "infrastructure",
 	amba_admin_insert_row: "infrastructure",
+	amba_admin_update_row: "infrastructure",
+	amba_admin_delete_row: "infrastructure",
+	amba_admin_bulk_update: "infrastructure",
+	amba_admin_bulk_delete: "infrastructure",
 	amba_admin_list_rows: "infrastructure",
 	amba_admin_aggregate_rows: "infrastructure",
 	amba_client_insert_row: "infrastructure",
@@ -8137,6 +9237,7 @@ const TOOL_CATEGORY = {
 	amba_client_count_rows: "infrastructure",
 	amba_client_find_rows: "infrastructure",
 	amba_client_find_nearest_rows: "infrastructure",
+	amba_client_aggregate_rows: "infrastructure",
 	amba_client_update_row: "infrastructure",
 	amba_client_delete_row: "infrastructure",
 	amba_functions_list: "infrastructure",
@@ -8175,6 +9276,8 @@ const TOOL_CATEGORY = {
 	amba_domains_check: "infrastructure",
 	amba_domains_purchase: "infrastructure",
 	amba_domains_list: "infrastructure",
+	amba_operations_get: "infrastructure",
+	amba_operations_list: "infrastructure",
 	amba_media_upload: "infrastructure",
 	amba_upload_media: "infrastructure",
 	amba_media_list: "infrastructure",
@@ -8183,6 +9286,13 @@ const TOOL_CATEGORY = {
 	amba_media_create_folder: "infrastructure",
 	amba_media_delete_folder: "infrastructure",
 	amba_media_list_folders: "infrastructure",
+	amba_media_catalogs_create: "infrastructure",
+	amba_media_catalogs_list: "infrastructure",
+	amba_media_catalogs_get: "infrastructure",
+	amba_media_catalogs_update: "infrastructure",
+	amba_media_catalogs_delete: "infrastructure",
+	amba_media_catalogs_add_item: "infrastructure",
+	amba_media_catalogs_remove_item: "infrastructure",
 	amba_secrets_set: "infrastructure",
 	amba_set_secret: "infrastructure",
 	amba_secrets_get: "infrastructure",
@@ -8221,11 +9331,20 @@ const TOOL_CATEGORY = {
 	amba_delete_ai_prompt: "infrastructure",
 	amba_ai_prompts_invoke: "infrastructure",
 	amba_invoke_ai_prompt: "infrastructure",
+	amba_ai_prompts_set_budget: "infrastructure",
+	amba_ai_prompts_get_spend: "infrastructure",
 	amba_sdk_get_setup_instructions: "infrastructure",
 	amba_get_sdk_setup_instructions: "infrastructure",
 	amba_billing_status: "infrastructure",
 	amba_billing_tiers: "infrastructure",
 	amba_billing_set_ceiling: "infrastructure",
+	amba_payments_account_create: "economy",
+	amba_payments_create_onboarding_link: "economy",
+	amba_payments_account_status: "economy",
+	amba_payments_set_fee: "economy",
+	amba_payments_charge: "economy",
+	amba_payments_balance: "economy",
+	amba_payments_payouts: "economy",
 	amba_projects_invite_member: "infrastructure",
 	amba_projects_list_members: "infrastructure",
 	amba_projects_remove_member: "infrastructure",
@@ -8240,6 +9359,10 @@ const TOOL_CATEGORY = {
 	amba_webhooks_deliveries_list: "infrastructure",
 	amba_webhooks_deliveries_get: "infrastructure",
 	amba_webhooks_deliveries_replay: "infrastructure",
+	amba_events_catalog: "infrastructure",
+	amba_control_webhooks_create: "infrastructure",
+	amba_control_webhooks_list: "infrastructure",
+	amba_control_webhooks_delete: "infrastructure",
 	amba_email_templates_create: "engagement",
 	amba_email_templates_list: "engagement",
 	amba_email_templates_get: "engagement",
@@ -8268,6 +9391,691 @@ function getToolCategory(toolName) {
 	return TOOL_CATEGORY[toolName] ?? null;
 }
 //#endregion
+//#region src/auto/schema-to-zod.ts
+/**
+* Pure mapper: a collection's live schema (the JSON returned by the
+* `GET .../collections/:name` describe endpoint) → the zod raw shapes the
+* auto-generated MCP tools register.
+*
+* Three derived shapes per collection (the auto-MCP wedge §2.2):
+*
+*   - `insertShape` — the typed body of an `insert` tool. Server-managed
+*     columns (`id`, `user_id`, `created_at`, `updated_at`, `deleted_at`)
+*     are omitted (the route stamps them); a column is REQUIRED when it is
+*     NOT NULL and has no default, OPTIONAL otherwise.
+*   - `whereShape` — the typed `where` of a `find` tool: one optional key
+*     per non-vector column whose value is `value | { eq?, ne?, gt?, … }`
+*     typed to the column. This is the single highest-value projection —
+*     it makes the generated tool read like a hand-built typed client
+*     rather than a free-form `where: object` blob.
+*   - `updateShape` — the typed `set` of an `update` tool: every non
+*     server-managed column, all optional (merge-patch semantics).
+*
+* Plus `rowTypeHints` — a column→plain-English type label map the
+* description generator (`describe.ts`) reads, and `vectorColumns` — the
+* vector columns (excluded from row input; they drive `find_nearest`).
+*
+* The mapper is PURE (no I/O, no zod-runtime coupling beyond building the
+* shape) so it unit-tests in isolation and so the same projection can run
+* in the hosted server today and in the CLI / console later.
+*/
+/**
+* Columns Amba manages on every collection. They are stamped by the
+* route, never accepted as tool input, and so are omitted from the
+* insert / update shapes. They ARE filterable (`where`) and selectable.
+*/
+const SERVER_MANAGED_COLUMNS = new Set([
+	"id",
+	"user_id",
+	"created_at",
+	"updated_at",
+	"deleted_at"
+]);
+/**
+* Classify a column into a coarse {@link ColumnKind}. Reads `data_type`
+* first (the only reliable array signal — `data_type === 'ARRAY'`), then
+* `udt_name`. Unknown types fall back to `unknown` (mapped to free JSON)
+* rather than throwing, so a future column type never breaks generation.
+*/
+function classifyColumn(column) {
+	const udt = column.udt_name.toLowerCase();
+	if (column.data_type.toUpperCase() === "ARRAY" || udt.startsWith("_")) switch (udt.replace(/^_/, "")) {
+		case "text":
+		case "varchar":
+		case "bpchar": return "text[]";
+		case "int2":
+		case "int4":
+		case "int8": return "integer[]";
+		case "numeric":
+		case "float4":
+		case "float8": return "number[]";
+		case "bool": return "boolean[]";
+		case "uuid": return "uuid[]";
+		default: return "unknown";
+	}
+	switch (udt) {
+		case "text":
+		case "varchar":
+		case "bpchar": return "text";
+		case "int2":
+		case "int4":
+		case "int8": return "integer";
+		case "numeric":
+		case "float4":
+		case "float8": return "number";
+		case "bool": return "boolean";
+		case "jsonb":
+		case "json": return "json";
+		case "uuid": return "uuid";
+		case "date": return "date";
+		case "timestamptz":
+		case "timestamp": return "timestamp";
+		case "vector": return "vector";
+		default: return "unknown";
+	}
+}
+/** Build the base (scalar/array) zod type for a column kind. */
+function baseTypeForKind(kind) {
+	switch (kind) {
+		case "text": return z.string();
+		case "uuid": return z.string().describe("uuid");
+		case "date": return z.string().describe("ISO-8601 date (YYYY-MM-DD)");
+		case "timestamp": return z.string().describe("ISO-8601 timestamp");
+		case "integer": return z.number().int();
+		case "number": return z.number();
+		case "boolean": return z.boolean();
+		case "json": return z.unknown();
+		case "text[]": return z.array(z.string());
+		case "integer[]": return z.array(z.number().int());
+		case "number[]": return z.array(z.number());
+		case "boolean[]": return z.array(z.boolean());
+		case "uuid[]": return z.array(z.string());
+		case "vector": return z.array(z.number());
+		default: return z.unknown();
+	}
+}
+/**
+* Build the per-column `where` operator object. Every operator is
+* optional; the value type matches the column. A bare value is also
+* accepted as shorthand for `{ eq: value }` (mirrors the server, which
+* treats a non-object field value as equality).
+*/
+function whereTypeForKind(kind, columnName) {
+	const base = baseTypeForKind(kind);
+	const isArray = kind.endsWith("[]");
+	const isComparable = kind === "integer" || kind === "number" || kind === "date" || kind === "timestamp" || kind === "text";
+	const isText = kind === "text";
+	const ops = {
+		eq: base.optional(),
+		ne: base.optional(),
+		in: z.array(base).optional(),
+		notIn: z.array(base).optional(),
+		isNull: z.boolean().optional(),
+		isNotNull: z.boolean().optional()
+	};
+	if (isComparable) {
+		ops.gt = base.optional();
+		ops.gte = base.optional();
+		ops.lt = base.optional();
+		ops.lte = base.optional();
+	}
+	if (isText) {
+		ops.like = z.string().optional().describe("SQL LIKE pattern (case-sensitive).");
+		ops.ilike = z.string().optional().describe("SQL ILIKE pattern (case-insensitive).");
+	}
+	if (isArray) {
+		ops.contains = base.optional().describe("Rows whose array contains all of these elements.");
+		ops.containedBy = base.optional().describe("Rows whose array is contained by these elements.");
+		ops.overlaps = base.optional().describe("Rows whose array shares any element with these.");
+	}
+	return z.union([z.object(ops), base]).optional().describe(`Filter on \`${columnName}\`. Bare value = equality; or an operator object.`);
+}
+/**
+* Whether a column is required on insert: NOT NULL and no column default.
+* A defaulted NOT NULL column is optional (the DB fills it).
+*/
+function isRequiredOnInsert(column) {
+	return column.is_nullable === "NO" && column.column_default === null;
+}
+/**
+* Project a collection schema into the zod raw shapes the auto-MCP tools
+* register. Pure — same input always yields the same shapes.
+*/
+function mapCollectionSchema(schema, options = {}) {
+	const insertShape = {};
+	const whereShape = {};
+	const updateShape = {};
+	const rowTypeHints = {};
+	const vectorColumns = [];
+	for (const column of schema.columns) {
+		const name = column.column_name;
+		const kind = classifyColumn(column);
+		rowTypeHints[name] = kind;
+		if (kind === "vector") {
+			vectorColumns.push(name);
+			continue;
+		}
+		whereShape[name] = whereTypeForKind(kind, name);
+		if (SERVER_MANAGED_COLUMNS.has(name)) {
+			if (name === "user_id" && options.includeUserIdInInsert) insertShape[name] = baseTypeForKind(kind).optional().describe("Optional. The app user id to attribute this row to. Omit to insert without an owner (requires a shared collection) or use as_system.");
+			continue;
+		}
+		const base = baseTypeForKind(kind);
+		updateShape[name] = base.optional();
+		insertShape[name] = isRequiredOnInsert(column) ? base : base.optional();
+	}
+	return {
+		insertShape,
+		whereShape,
+		updateShape,
+		rowTypeHints,
+		vectorColumns,
+		hasVector: vectorColumns.length > 0
+	};
+}
+//#endregion
+//#region src/auto/describe.ts
+/**
+* SDK-grade per-tool description generator for the auto-MCP wedge.
+*
+* The wedge is only worth shipping if the generated tools read like a
+* hand-built typed client, not a thin `find_rows({collection, where})`
+* wrapper (design doc §7). These descriptions are generated from the live
+* column list + access policy so an agent never needs external docs:
+* column names, types, nullability, the access policy in plain words, and
+* a worked example per verb.
+*
+* Pure string builders — snapshot-friendly, no I/O. NO provider leakage:
+* "collection", "row", "column", "function" only — never the underlying
+* storage engine.
+*/
+/** A human-friendly type label for a column kind. */
+function labelForKind(kind) {
+	switch (kind) {
+		case "integer": return "integer";
+		case "number": return "number";
+		case "boolean": return "boolean";
+		case "json": return "JSON";
+		case "uuid": return "uuid (string)";
+		case "date": return "date string";
+		case "timestamp": return "timestamp string";
+		case "vector": return "vector";
+		case "text[]": return "string array";
+		case "integer[]": return "integer array";
+		case "number[]": return "number array";
+		case "boolean[]": return "boolean array";
+		case "uuid[]": return "uuid array";
+		case "text": return "text";
+		default: return "value";
+	}
+}
+/**
+* One-line summary of the collection's columns an agent can write to
+* (insert/update). Server-managed columns are excluded — the route stamps
+* them.
+*/
+function writableColumnSummary(mapped) {
+	const cols = Object.keys(mapped.rowTypeHints).filter((c) => !SERVER_MANAGED_COLUMNS.has(c) && mapped.rowTypeHints[c] !== "vector");
+	if (cols.length === 0) return "(no writable columns)";
+	return cols.map((c) => `${c} (${labelForKind(mapped.rowTypeHints[c])})`).join(", ");
+}
+/** All columns with types, for the find/list filter description. */
+function allColumnSummary(mapped) {
+	const cols = Object.keys(mapped.rowTypeHints);
+	if (cols.length === 0) return "(no columns)";
+	return cols.map((c) => `${c} (${labelForKind(mapped.rowTypeHints[c])})`).join(", ");
+}
+/** Plain-words access-policy sentence for the given scope. */
+function policySentence(ctx) {
+	if (ctx.scope === "admin") return "Developer/admin scope: sees and mutates EVERY row regardless of which app user owns it (no per-user scoping).";
+	return `End-user scope: ${ctx.readPolicy === "public" ? "Reads return all rows (this collection is public-read)." : "Reads return only the signed-in user's own rows (plus shared/unowned rows)."} ${ctx.writePolicy === "authenticated" ? "Any signed-in user may write." : "Writes affect only the signed-in user's own rows."}`;
+}
+/** Build the first writable column name for worked examples. */
+function exampleWritableColumn(mapped) {
+	return Object.keys(mapped.rowTypeHints).find((c) => !SERVER_MANAGED_COLUMNS.has(c) && mapped.rowTypeHints[c] !== "vector") ?? null;
+}
+/** Example value literal for a column kind (for worked examples). */
+function exampleValue(kind) {
+	switch (kind) {
+		case "integer": return "42";
+		case "number": return "3.14";
+		case "boolean": return "true";
+		case "json": return "{\"key\":\"value\"}";
+		case "uuid": return "\"00000000-0000-0000-0000-000000000000\"";
+		case "date": return "\"2026-01-31\"";
+		case "timestamp": return "\"2026-01-31T12:00:00Z\"";
+		case "text[]": return "[\"a\",\"b\"]";
+		case "integer[]": return "[1,2,3]";
+		case "number[]": return "[1.5,2.5]";
+		case "boolean[]": return "[true,false]";
+		case "uuid[]": return "[\"00000000-0000-0000-0000-000000000000\"]";
+		default: return "\"example\"";
+	}
+}
+/**
+* Generate the description string for a single collection tool.
+*/
+function describeCollectionTool(verb, ctx) {
+	const { collection, mapped } = ctx;
+	const policy = policySentence(ctx);
+	const exampleCol = exampleWritableColumn(mapped);
+	const exampleKind = exampleCol ? mapped.rowTypeHints[exampleCol] : "text";
+	switch (verb) {
+		case "list": return [
+			`List rows in the "${collection}" collection, newest first.`,
+			`Returns a page of rows plus a \`next_cursor\` — pass it back as \`cursor\` to fetch the next page.`,
+			`Columns: ${allColumnSummary(mapped)}.`,
+			policy,
+			`Example: { "limit": 20 }.`
+		].join(" ");
+		case "get": return [
+			`Fetch one row from "${collection}" by its \`id\`.`,
+			`Returns the full row, or a 404 if no row with that id exists (or it is outside your scope).`,
+			policy,
+			`Example: { "id": "00000000-0000-0000-0000-000000000000" }.`
+		].join(" ");
+		case "find": return [
+			`Find rows in "${collection}" with a typed, per-column filter.`,
+			`Each \`where\` key is a column; its value is a bare value (equality) or an operator object`,
+			`({ eq, ne, gt, gte, lt, lte, in, notIn, like, ilike, isNull, isNotNull, contains, containedBy, overlaps }).`,
+			`Combine with top-level \`and\`/\`or\`/\`not\`. Supports \`order\`, \`limit\`, and \`cursor\` pagination (returns \`next_cursor\`).`,
+			`Columns: ${allColumnSummary(mapped)}.`,
+			policy,
+			exampleCol ? `Example: { "where": { "${exampleCol}": { "eq": ${exampleValue(exampleKind)} } }, "limit": 20 }.` : `Example: { "where": {}, "limit": 20 }.`
+		].join(" ");
+		case "insert": return [
+			`Insert a new row into "${collection}".`,
+			`Provide values for the writable columns: ${writableColumnSummary(mapped)}.`,
+			`Server-managed columns (id, user_id, created_at, updated_at, deleted_at) are stamped automatically — do not send them.`,
+			policy,
+			exampleCol ? `Example: { "${exampleCol}": ${exampleValue(exampleKind)} }.` : `Example: {}.`
+		].join(" ");
+		case "update": return [
+			`Update an existing row in "${collection}" by \`id\` (merge-patch — only the fields you send change).`,
+			`Writable columns: ${writableColumnSummary(mapped)}.`,
+			`Server-managed columns are rejected.`,
+			policy,
+			exampleCol ? `Example: { "id": "…", "set": { "${exampleCol}": ${exampleValue(exampleKind)} } }.` : `Example: { "id": "…", "set": {} }.`
+		].join(" ");
+		case "delete": return [
+			`Delete a row from "${collection}" by \`id\`.`,
+			`Soft-delete by default (recoverable); pass \`hard: true\` for a permanent removal.`,
+			policy,
+			`Example: { "id": "00000000-0000-0000-0000-000000000000" }.`
+		].join(" ");
+		case "aggregate": return [
+			`Compute aggregates over "${collection}": count / sum / avg / min / max, optionally grouped by columns.`,
+			`\`count\` with no column = COUNT(*). Combine with a typed \`where\` to aggregate a subset.`,
+			`Columns: ${allColumnSummary(mapped)}.`,
+			policy,
+			`Example: { "select": [{ "fn": "count" }] }.`
+		].join(" ");
+		case "find_nearest": return [
+			`Vector similarity search over "${collection}" — returns the rows whose embedding is closest to your query vector.`,
+			`This tool exists because "${collection}" has a vector column (${mapped.vectorColumns.join(", ")}).`,
+			policy,
+			`Example: { "vector": [0.1, 0.2, …], "limit": 5 }.`
+		].join(" ");
+		default: return `Operate on the "${collection}" collection.`;
+	}
+}
+/** Description for the `<ns>_list_collections` meta tool. */
+function describeListCollections(namespace) {
+	return [
+		`List every collection exposed by this app's agent surface (namespace "${namespace}").`,
+		`Each collection projects typed list/get/find/insert/update/delete/aggregate tools you can call directly —`,
+		`this tool is the index. Returns each collection's name and column summary.`
+	].join(" ");
+}
+/** Description for the `<ns>_whoami` meta tool. */
+function describeWhoami(namespace) {
+	return [`Report which app project this agent surface is connected to and the scope of the current credential`, `(namespace "${namespace}"). Use it to confirm you are pointed at the right app before mutating data.`].join(" ");
+}
+//#endregion
+//#region src/auto/collection-tools.ts
+/** Admin-route fetch (mirrors tools/collections.ts adminFetch). */
+async function adminFetch(apiClient, bearer, options) {
+	let url = `${apiClient.getBaseUrl()}${options.path}`;
+	if (options.query && Object.keys(options.query).length > 0) url += `?${new URLSearchParams(options.query).toString()}`;
+	const headers = {
+		Authorization: `Bearer ${bearer}`,
+		Accept: "application/json"
+	};
+	if (options.body !== void 0) headers["Content-Type"] = "application/json";
+	const res = await fetch(url, {
+		method: options.method,
+		headers,
+		body: options.body !== void 0 ? JSON.stringify(options.body) : void 0
+	});
+	let body;
+	try {
+		body = await res.json();
+	} catch {
+		body = { error: {
+			code: "INVALID_RESPONSE",
+			message: res.statusText
+		} };
+	}
+	return {
+		status: res.status,
+		body
+	};
+}
+/**
+* Tool-name fragment regex. MCP + `tool-naming.test.ts` require lowercase
+* `_`-separated names. The namespace + collection are sanitized to that
+* shape so a slug like "My App" or a collection like "MyRecipes" never
+* produces an invalid tool name.
+*/
+function sanitizeNameFragment(raw) {
+	const cleaned = raw.toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+	return /^[a-z]/.test(cleaned) ? cleaned : `c_${cleaned}`;
+}
+/** Build the `<ns>_<coll>_<verb>` tool name. */
+function collectionToolName(namespace, collection, verb) {
+	return `${sanitizeNameFragment(namespace)}_${sanitizeNameFragment(collection)}_${verb}`;
+}
+/**
+* Register the typed CRUD tools for a single collection on `server`,
+* proxying to the existing admin routes via `apiClient`.
+*/
+function registerCollectionToolsFor(server, apiClient, options) {
+	const { projectId, namespace, collection, schema, policy, scope } = options;
+	const mapped = mapCollectionSchema(schema, { includeUserIdInInsert: scope === "admin" });
+	const describeCtx = {
+		collection,
+		mapped,
+		readPolicy: policy.read_policy,
+		writePolicy: policy.write_policy,
+		scope
+	};
+	const rowsPath = `/projects/${projectId}/collections/${encodeURIComponent(collection)}/rows`;
+	const name = (verb) => collectionToolName(namespace, collection, verb);
+	registerTool(server, apiClient, name("list"), describeCollectionTool("list", describeCtx), {
+		limit: z.number().int().positive().optional().describe("Max rows (default 50)."),
+		cursor: z.string().optional().describe("Opaque cursor from a prior page."),
+		order: z.union([z.string(), z.array(z.string())]).optional().describe("Order spec, e.g. \"created_at desc\"."),
+		select: z.array(z.string()).optional().describe("Subset of columns to return."),
+		include_deleted: z.boolean().optional().describe("Include soft-deleted rows. Default false.")
+	}, async ({ limit, cursor, order, select, include_deleted }, { pat }) => {
+		const findQuery = {};
+		if (limit !== void 0) findQuery.limit = limit;
+		if (cursor !== void 0) findQuery.cursor = cursor;
+		if (order !== void 0) findQuery.order = order;
+		if (select !== void 0) findQuery.select = select;
+		if (include_deleted !== void 0) findQuery.includeDeleted = include_deleted;
+		return passthroughResult(await adminFetch(apiClient, pat, {
+			method: "GET",
+			path: rowsPath,
+			query: Object.keys(findQuery).length > 0 ? { query: JSON.stringify(findQuery) } : void 0
+		}));
+	});
+	registerTool(server, apiClient, name("get"), describeCollectionTool("get", describeCtx), { id: z.string().describe("Row id (uuid).") }, async ({ id }, { pat }) => {
+		return passthroughResult(await adminFetch(apiClient, pat, {
+			method: "GET",
+			path: `${rowsPath}/${encodeURIComponent(id)}`
+		}));
+	});
+	registerTool(server, apiClient, name("find"), describeCollectionTool("find", describeCtx), {
+		where: z.object({
+			...mapped.whereShape,
+			and: z.array(z.unknown()).optional().describe("AND-combine nested where clauses."),
+			or: z.array(z.unknown()).optional().describe("OR-combine nested where clauses."),
+			not: z.unknown().optional().describe("Negate a nested where clause.")
+		}).partial().optional().describe("Typed, per-column filter."),
+		order: z.union([z.string(), z.array(z.string())]).optional().describe("Order spec, e.g. \"created_at desc\"."),
+		limit: z.number().int().positive().optional().describe("Max rows (default 50)."),
+		cursor: z.string().optional().describe("Opaque cursor from 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.")
+	}, async ({ where, order, limit, cursor, select, include_deleted }, { pat }) => {
+		const findQuery = {};
+		if (where !== void 0) findQuery.where = where;
+		if (order !== void 0) findQuery.order = order;
+		if (limit !== void 0) findQuery.limit = limit;
+		if (cursor !== void 0) findQuery.cursor = cursor;
+		if (select !== void 0) findQuery.select = select;
+		if (include_deleted !== void 0) findQuery.includeDeleted = include_deleted;
+		return passthroughResult(await adminFetch(apiClient, pat, {
+			method: "GET",
+			path: rowsPath,
+			query: Object.keys(findQuery).length > 0 ? { query: JSON.stringify(findQuery) } : void 0
+		}));
+	});
+	registerTool(server, apiClient, name("insert"), describeCollectionTool("insert", describeCtx), {
+		...mapped.insertShape,
+		...scope === "admin" ? { as_system: z.boolean().optional().describe("Admin only. On a shared collection, insert a global row with no owner (user_id NULL). Mutually exclusive with user_id.") } : {}
+	}, async (args, { pat }) => {
+		const row = {};
+		for (const [k, v] of Object.entries(args)) {
+			if (k === "pat") continue;
+			if (v !== void 0) row[k] = v;
+		}
+		return passthroughResult(await adminFetch(apiClient, pat, {
+			method: "POST",
+			path: rowsPath,
+			body: row
+		}));
+	});
+	registerTool(server, apiClient, name("update"), describeCollectionTool("update", describeCtx), {
+		id: z.string().describe("Row id (uuid) to update."),
+		set: z.object({ ...mapped.updateShape }).describe("Column→value map of the fields to change (merge-patch).")
+	}, async ({ id, set }, { pat }) => {
+		return passthroughResult(await adminFetch(apiClient, pat, {
+			method: "PATCH",
+			path: `${rowsPath}/${encodeURIComponent(id)}`,
+			body: { set }
+		}));
+	});
+	registerTool(server, apiClient, name("delete"), describeCollectionTool("delete", describeCtx), {
+		id: z.string().describe("Row id (uuid) to delete."),
+		hard: z.boolean().optional().describe("false (default) soft-deletes (recoverable); true permanently removes.")
+	}, async ({ id, hard }, { pat }) => {
+		return passthroughResult(await adminFetch(apiClient, pat, {
+			method: "DELETE",
+			path: `${rowsPath}/${encodeURIComponent(id)}`,
+			query: hard === true ? { hard: "true" } : void 0
+		}));
+	});
+	registerTool(server, apiClient, name("aggregate"), describeCollectionTool("aggregate", describeCtx), {
+		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.")
+		})).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: z.object({ ...mapped.whereShape }).partial().optional().describe("Typed, per-column filter to aggregate a subset."),
+		include_deleted: z.boolean().optional().describe("Include soft-deleted rows. Default false.")
+	}, async ({ 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, pat, {
+			method: "POST",
+			path: `${rowsPath}/aggregate`,
+			body
+		}));
+	});
+}
+//#endregion
+//#region src/auto/index.ts
+/** Page size for the admin collections list (the route caps at 200). */
+const COLLECTION_PAGE_SIZE = 200;
+/**
+* Hard cap on total pages fetched, so a bad `total` (or a route that never
+* advances) can't spin forever. 200 * 100 = 20k collections — far beyond
+* any real project.
+*/
+const COLLECTION_MAX_PAGES = 100;
+/**
+* Fetch EVERY collection name for a project, advancing `offset` until the
+* reported `pagination.total` is reached (the admin list route caps each
+* page at 200).
+*
+* Returns `{ ok, names }`. `ok` is `false` if ANY page (first OR a later
+* one) returns a non-success status — a partial list must not masquerade
+* as complete, or the caller would silently register only some of the
+* project's collections as tools. On a mid-pagination failure the
+* already-fetched `names` are still returned alongside `ok:false` so a
+* caller can surface a diagnostic that includes what it did see.
+*/
+async function listAllCollections(apiClient, projectId) {
+	const names = [];
+	let offset = 0;
+	for (let page = 0; page < COLLECTION_MAX_PAGES; page++) {
+		const res = await adminGet(apiClient, `/projects/${projectId}/collections?limit=${COLLECTION_PAGE_SIZE}&offset=${offset}`);
+		if (res.status < 200 || res.status >= 300) return {
+			ok: false,
+			names
+		};
+		const pageNames = (res.body.data ?? []).map((c) => c.name).filter((n) => typeof n === "string" && n.length > 0);
+		names.push(...pageNames);
+		const total = res.body.pagination?.total;
+		offset += COLLECTION_PAGE_SIZE;
+		if (typeof total === "number") {
+			if (offset >= total) break;
+		} else if (pageNames.length < COLLECTION_PAGE_SIZE) break;
+	}
+	return {
+		ok: true,
+		names
+	};
+}
+/** Admin GET helper bound to a Bearer (no pat-arg machinery needed here). */
+async function adminGet(apiClient, path) {
+	const res = await fetch(`${apiClient.getBaseUrl()}${path}`, {
+		method: "GET",
+		headers: {
+			Authorization: `Bearer ${await apiClientToken(apiClient)}`,
+			Accept: "application/json"
+		}
+	});
+	let body;
+	try {
+		body = await res.json();
+	} catch {
+		body = {};
+	}
+	return {
+		status: res.status,
+		body
+	};
+}
+async function apiClientToken(apiClient) {
+	return await apiClient.resolveTokenOrNull() ?? "";
+}
+/**
+* Register the auto-MCP tool surface for one project on `server`.
+*
+* Lists + introspects the project's collections (admin routes) and
+* registers a typed tool set per collection, plus the two meta tools.
+* Returns the names of the collections that were exposed plus `listOk`
+* (false when the collection listing was incomplete — a paginated page
+* failed — in which case typed tools are deliberately NOT registered so a
+* truncated set never masquerades as the whole project).
+*/
+async function registerAutoMcpTools(server, apiClient, options) {
+	const { projectId, scope } = options;
+	const namespace = sanitizeNameFragment(options.namespace ?? projectId);
+	registerTool(server, apiClient, `${namespace}_whoami`, describeWhoami(namespace), {}, async (_args, { pat }) => {
+		const me = await adminGet(apiClient.withToken(pat), `/projects/${projectId}`);
+		return jsonResult$1({
+			status: me.status,
+			project_id: projectId,
+			scope,
+			namespace,
+			authenticated: me.status >= 200 && me.status < 300
+		});
+	});
+	let collections = [];
+	let listOk = false;
+	try {
+		const all = await listAllCollections(apiClient, projectId);
+		listOk = all.ok;
+		collections = all.ok ? all.names : [];
+	} catch {
+		collections = [];
+		listOk = false;
+	}
+	registerTool(server, apiClient, `${namespace}_list_collections`, describeListCollections(namespace), {}, async (_args, { pat }) => {
+		const boundClient = apiClient.withToken(pat);
+		const all = await listAllCollections(boundClient, projectId);
+		const names = all.names;
+		const described = await Promise.all(names.map(async (collection) => {
+			let exposed = false;
+			try {
+				const res = await adminGet(boundClient, `/projects/${projectId}/collections/${encodeURIComponent(collection)}`);
+				exposed = res.status >= 200 && res.status < 300 && Array.isArray(res.body.data?.columns);
+			} catch {
+				exposed = false;
+			}
+			return {
+				collection,
+				exposed
+			};
+		}));
+		return jsonResult$1({
+			status: all.ok ? 200 : 502,
+			list_complete: all.ok,
+			namespace,
+			project_id: projectId,
+			scope,
+			collections: described.map(({ collection, exposed }) => ({
+				collection,
+				exposed,
+				tools: exposed ? [
+					"list",
+					"get",
+					"find",
+					"insert",
+					"update",
+					"delete",
+					"aggregate"
+				].map((v) => collectionToolName(namespace, collection, v)) : []
+			}))
+		});
+	});
+	for (const collection of collections) {
+		let described;
+		try {
+			const res = await adminGet(apiClient, `/projects/${projectId}/collections/${encodeURIComponent(collection)}`);
+			if (res.status < 200 || res.status >= 300) continue;
+			described = res.body;
+		} catch {
+			continue;
+		}
+		const data = described.data;
+		if (!data || !Array.isArray(data.columns)) continue;
+		const policy = {
+			read_policy: data.read_policy ?? "owner",
+			write_policy: data.write_policy ?? "owner"
+		};
+		registerCollectionToolsFor(server, apiClient, {
+			projectId,
+			namespace,
+			collection,
+			schema: {
+				name: data.name,
+				columns: data.columns
+			},
+			policy,
+			scope
+		});
+	}
+	return {
+		namespace,
+		collections,
+		listOk
+	};
+}
+//#endregion
 //#region src/index.ts
 /**
 * Register every Amba MCP tool group against the given server, using the
@@ -8275,7 +10083,11 @@ function getToolCategory(toolName) {
 * called against it once.
 */
 function registerAllTools(server, apiClient) {
-	registerTools$13(server, apiClient);
+	registerTools$15(server, apiClient);
+	registerTools$37(server, apiClient);
+	registerTools$36(server, apiClient);
+	registerTools$35(server, apiClient);
+	registerTools$34(server, apiClient);
 	registerTools$33(server, apiClient);
 	registerTools$32(server, apiClient);
 	registerTools$31(server, apiClient);
@@ -8294,8 +10106,8 @@ function registerAllTools(server, apiClient) {
 	registerTools$18(server, apiClient);
 	registerTools$17(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);
@@ -8329,4 +10141,4 @@ function createApiClient(options) {
 	return new ApiClient(opts);
 }
 //#endregion
-export { AMBA_SETUP_ECONOMY_MD, AMBA_SETUP_ECONOMY_MIME, AMBA_SETUP_ECONOMY_URI, AMBA_SETUP_ENGAGEMENT_MD, AMBA_SETUP_ENGAGEMENT_MIME, AMBA_SETUP_ENGAGEMENT_URI, AMBA_SETUP_GAMIFICATION_MD, AMBA_SETUP_GAMIFICATION_MIME, AMBA_SETUP_GAMIFICATION_URI, AMBA_SETUP_GUIDE_BODY_VERSION, AMBA_SETUP_GUIDE_MD, AMBA_SETUP_GUIDE_MIME, AMBA_SETUP_GUIDE_URI, AMBA_SETUP_IDENTITY_MD, AMBA_SETUP_IDENTITY_MIME, AMBA_SETUP_IDENTITY_URI, AMBA_SETUP_INFRASTRUCTURE_MD, AMBA_SETUP_INFRASTRUCTURE_MIME, AMBA_SETUP_INFRASTRUCTURE_URI, AMBA_SETUP_SOCIAL_MD, AMBA_SETUP_SOCIAL_MIME, AMBA_SETUP_SOCIAL_URI, AMBA_SETUP_SUB_RESOURCES, ApiClient, CATEGORY_META, CATEGORY_ORDER, EXPO_BUILD_PROMPT_MD, EXPO_BUILD_PROMPT_MIME, EXPO_BUILD_PROMPT_URI, TOOL_CATEGORY, createApiClient, getToolCategory, registerAllResources, registerAllTools };
+export { AMBA_SETUP_ECONOMY_MD, AMBA_SETUP_ECONOMY_MIME, AMBA_SETUP_ECONOMY_URI, AMBA_SETUP_ENGAGEMENT_MD, AMBA_SETUP_ENGAGEMENT_MIME, AMBA_SETUP_ENGAGEMENT_URI, AMBA_SETUP_GAMIFICATION_MD, AMBA_SETUP_GAMIFICATION_MIME, AMBA_SETUP_GAMIFICATION_URI, AMBA_SETUP_GUIDE_BODY_VERSION, AMBA_SETUP_GUIDE_MD, AMBA_SETUP_GUIDE_MIME, AMBA_SETUP_GUIDE_URI, AMBA_SETUP_IDENTITY_MD, AMBA_SETUP_IDENTITY_MIME, AMBA_SETUP_IDENTITY_URI, AMBA_SETUP_INFRASTRUCTURE_MD, AMBA_SETUP_INFRASTRUCTURE_MIME, AMBA_SETUP_INFRASTRUCTURE_URI, AMBA_SETUP_SOCIAL_MD, AMBA_SETUP_SOCIAL_MIME, AMBA_SETUP_SOCIAL_URI, AMBA_SETUP_SUB_RESOURCES, ApiClient, CATEGORY_META, CATEGORY_ORDER, EXPO_BUILD_PROMPT_MD, EXPO_BUILD_PROMPT_MIME, EXPO_BUILD_PROMPT_URI, SERVER_MANAGED_COLUMNS, TOOL_CATEGORY, classifyColumn, collectionToolName, createApiClient, describeCollectionTool, describeListCollections, describeWhoami, getToolCategory, mapCollectionSchema, registerAllResources, registerAllTools, registerAutoMcpTools, registerCollectionToolsFor, sanitizeNameFragment };