@layers/amba-mcp 4.0.4 → 4.0.5

package/dist/index.js

@@ -370,7 +370,8 @@ const WRITE_VERBS = new Set([
 	"purchase",
 	"signup",
 	"login",
-	"refresh"
+	"refresh",
+	"track"
 ]);
 /**
 * Split a tool name into lowercase verb-candidate tokens, dropping the
@@ -386,7 +387,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;
@@ -613,7 +624,7 @@ function registerPublicTool(server, name, description, schema, handler, aliases
 }
 //#endregion
 //#region src/tools/projects.ts
-function registerTools$33(server, apiClient) {
+function registerTools$35(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 +642,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 +731,7 @@ function registerTools$33(server, apiClient) {
 }
 //#endregion
 //#region src/tools/push.ts
-function registerTools$32(server, apiClient) {
+function registerTools$34(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 +861,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$33(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 +946,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$32(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 +1024,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$31(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 +1080,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 +1163,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",
@@ -1188,7 +1203,7 @@ function registerTools$29(server, apiClient) {
 }
 //#endregion
 //#region src/tools/streaks.ts
-function registerTools$28(server, apiClient) {
+function registerTools$30(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 +1295,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$29(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 +1365,7 @@ const PERIOD_DAYS = {
 	"30d": "30",
 	"90d": "90"
 };
-function registerTools$26(server, apiClient) {
+function registerTools$28(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 +1387,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$27(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 +1557,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 +1644,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 +1885,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$26(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 +1970,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$25(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 +2075,7 @@ function registerTools$23(server, apiClient) {
 }
 //#endregion
 //#region src/tools/challenges.ts
-function registerTools$22(server, apiClient) {
+function registerTools$24(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 +2186,7 @@ function registerTools$22(server, apiClient) {
 }
 //#endregion
 //#region src/tools/economy.ts
-function registerTools$21(server, apiClient) {
+function registerTools$23(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 +2434,44 @@ 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("Store product identifier (e.g. \"stripe_premium_yr\"). Pass null to clear."),
+		store: z.enum([
+			"app_store",
+			"play_store",
+			"stripe"
+		]).nullable().optional().describe("Originating store. 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_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 +2757,27 @@ 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/leaderboards.ts
-function registerTools$20(server, apiClient) {
+function registerTools$22(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 +2889,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$21(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 +2955,7 @@ function registerTools$19(server, apiClient) {
 }
 //#endregion
 //#region src/tools/platform.ts
-function registerTools$18(server, apiClient) {
+function registerTools$20(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\")"),
@@ -3369,7 +3531,7 @@ function registerTools$18(server, apiClient) {
 }
 //#endregion
 //#region src/tools/social.ts
-function registerTools$17(server, apiClient) {
+function registerTools$19(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 +3856,7 @@ function registerTools$17(server, apiClient) {
 }
 //#endregion
 //#region src/tools/xp.ts
-function registerTools$16(server, apiClient) {
+function registerTools$18(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 +3979,7 @@ function registerTools$16(server, apiClient) {
 }
 //#endregion
 //#region src/tools/events.ts
-function registerTools$15(server, apiClient) {
+function registerTools$17(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,6 +4019,84 @@ function registerTools$15(server, apiClient) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
+	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/event-catalog.ts
+function registerTools$16(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
@@ -3884,7 +4124,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$15(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 +4218,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 +4340,7 @@ function enrichedAuthResult(result, agentInstructions) {
 		status: result.status
 	});
 }
-function registerTools$13(server, apiClient) {
+function registerTools$14(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",
@@ -4359,10 +4549,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$13(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."
@@ -4435,6 +4625,25 @@ function registerTools$12(server, apiClient) {
 			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(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.",
@@ -4482,13 +4691,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 +4707,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 requestBody = as_system ? {
+			...row,
+			as_system: true
+		} : row;
 		const result = await adminFetch(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
 		});
@@ -4606,6 +4821,96 @@ function registerTools$12(server, apiClient) {
 			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.",
+		"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).")
+	}, async ({ project_id, name, id, set, expected }, { pat }) => {
+		return passthroughResult(await adminFetch(apiClient, {
+			method: "PATCH",
+			path: `/projects/${project_id}/collections/${encodeURIComponent(name)}/rows/${encodeURIComponent(id)}`,
+			body: expected !== void 0 ? {
+				set,
+				expected
+			} : { set },
+			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(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.",
+		"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.")
+	}, async ({ project_id, name, set, where }, { pat }) => {
+		return passthroughResult(await adminFetch(apiClient, {
+			method: "PATCH",
+			path: `/projects/${project_id}/collections/${encodeURIComponent(name)}/rows`,
+			body: {
+				set,
+				where
+			},
+			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(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.).",
@@ -4863,6 +5168,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 +5324,7 @@ function jsonResult(payload) {
 * of a generic upstream 400.
 */
 const MAX_BUNDLE_BYTES = 10 * 1024 * 1024;
-function registerTools$11(server, apiClient) {
+function registerTools$12(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 +5452,7 @@ function registerTools$11(server, apiClient) {
 }
 //#endregion
 //#region src/tools/sites.ts
-function registerTools$10(server, apiClient) {
+function registerTools$11(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 +5544,7 @@ function registerTools$10(server, apiClient) {
 }
 //#endregion
 //#region src/tools/domains.ts
-function registerTools$9(server, apiClient) {
+function registerTools$10(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,6 +5599,39 @@ function registerTools$9(server, apiClient) {
 	});
 }
 //#endregion
+//#region src/tools/operations.ts
+function registerTools$9(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) {
 	registerTool(server, apiClient, "amba_secrets_set", [
@@ -7846,7 +8225,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",
@@ -7993,6 +8374,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 +8408,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 +8469,7 @@ const TOOL_CATEGORY = {
 	amba_moderation_list_trust: "social",
 	amba_events_list: "analytics",
 	amba_events_count: "analytics",
+	amba_events_track: "analytics",
 	amba_analytics_get: "analytics",
 	amba_get_analytics: "analytics",
 	amba_sessions_list: "analytics",
@@ -8128,7 +8512,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 +8526,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 +8565,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",
@@ -8240,6 +8632,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",
@@ -8275,7 +8671,9 @@ function getToolCategory(toolName) {
 * called against it once.
 */
 function registerAllTools(server, apiClient) {
-	registerTools$13(server, apiClient);
+	registerTools$14(server, apiClient);
+	registerTools$35(server, apiClient);
+	registerTools$34(server, apiClient);
 	registerTools$33(server, apiClient);
 	registerTools$32(server, apiClient);
 	registerTools$31(server, apiClient);
@@ -8295,7 +8693,7 @@ function registerAllTools(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);

package/dist/lib/annotations.d.ts

@@ -80,13 +80,6 @@ export type ToolVerbClass = 'read' | 'destructive' | 'write';
  * `amba_` prefix. Exported for the test suite.
  */
 export declare function toolNameTokens(name: string): string[];
-/**
- * Classify a tool name into its behavioural class by PRECEDENCE
- * (destructive > read > write). Returns `null` if no token matches any
- * known verb — that should never happen for a real Amba tool and the
- * test suite asserts it doesn't, so a `null` at runtime means a new tool
- * used an unrecognised verb and needs a verb-set entry here.
- */
 export declare function classifyToolVerb(name: string): ToolVerbClass | null;
 /**
  * Derive a human-readable Title-Case title from the tool name. The

package/dist/tools/event-catalog.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Event catalog + control-plane webhook tools — discover what a project can
+ * emit, and subscribe webhooks to PLATFORM lifecycle events.
+ *
+ *   amba_events_catalog            GET    /webhooks/catalog
+ *   amba_control_webhooks_create   POST   /control-webhooks
+ *   amba_control_webhooks_list     GET    /control-webhooks
+ *   amba_control_webhooks_delete   DELETE /control-webhooks/:id
+ *
+ * Tenant/app-event subscription tools live in `webhooks.ts` (those subscribe to
+ * APP events like `economy.currency.spent`). These cover CONTROL-plane events
+ * about the project itself — provisioning, deploys, domains, billing — which is
+ * what an autonomous provisioning agent wants to react to.
+ *
+ * Descriptions stay provider-neutral and nudge toward the production pattern
+ * (discover the catalog → wire the lifecycle events) without overclaiming.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../api-client.js';
+export declare function registerTools(server: McpServer, apiClient: ApiClient): void;

package/dist/tools/functions.d.ts

@@ -5,7 +5,7 @@
  * deploy a bundled script, list deployments, describe one, delete a
  * function (cascade), and full schedule lifecycle (create, pause,
  * resume, trigger now). Logs read is the last operation in the set —
- * Workers Logpush events for a single function over a bounded time
+ * Function logs for a single function over a bounded time
  * range.
  *
  * Wire details:

package/dist/tools/leagues.d.ts

@@ -6,7 +6,7 @@ import type { ApiClient } from '../api-client.js';
  * 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.
  */
 export declare function registerTools(server: McpServer, apiClient: ApiClient): void;

package/dist/tools/operations.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Operation-handle MCP tools — poll an async operation to done | failed.
+ *
+ * Several Amba actions kick off work that may take a moment (e.g. buying a
+ * domain). Those endpoints return an `operation_id`; pass it to
+ * `amba_operations_get` to read the current status without re-triggering the
+ * action. Poll until `status` is `succeeded` or `failed` — on `failed`,
+ * `failed_reason` explains why.
+ *
+ * Tools:
+ *   - `amba_operations_get`  — read one operation's status (poll to done).
+ *   - `amba_operations_list` — list operations, optionally filtered by kind
+ *                              and/or status.
+ *
+ * Both are READ-ONLY — they never start or change an operation, only report
+ * it. The producing tool (e.g. `amba_domains_purchase`) is what creates the
+ * operation and returns its id.
+ *
+ * Authentication: every tool accepts an optional inline `pat` via the
+ * `registerTool` helper (see `../lib/with-pat.ts`).
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../api-client.js';
+export declare function registerTools(server: McpServer, apiClient: ApiClient): void;

package/package.json

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