@joy-loyalty/mcp 0.3.7 → 0.4.0

package/build/index.js

@@ -53,9 +53,19 @@ function loadConfig(env = process.env) {
   }
   const mode = privateBotKey ? "internal-bot" : "merchant";
   const writesEnabled = mode === "merchant" && env.JOY_MCP_ENABLE_WRITES === "true";
+  const configWritesEnabled = writesEnabled && env.JOY_MCP_ENABLE_CONFIG_WRITES === "true";
   const rawThreshold = Number(env.JOY_MCP_DEDUCT_DRYRUN_THRESHOLD ?? "1000");
   const deductDryRunThreshold = Number.isFinite(rawThreshold) && rawThreshold >= 0 ? rawThreshold : 1e3;
-  return { apiBaseUrl, appKey, secretKey, privateBotKey, mode, writesEnabled, deductDryRunThreshold };
+  return {
+    apiBaseUrl,
+    appKey,
+    secretKey,
+    privateBotKey,
+    mode,
+    writesEnabled,
+    configWritesEnabled,
+    deductDryRunThreshold
+  };
 }
 
 // ../mcp-core/build/client/joyApi.js
@@ -71,7 +81,7 @@ var JoyApiError = class extends Error {
     this.name = "JoyApiError";
   }
 };
-var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_TIMEOUT_MS = 2e4;
 function extractServerMessage(body) {
   if (!body || typeof body !== "object")
     return void 0;
@@ -112,11 +122,24 @@ function classifyError(status, serverMessage, retryAfter, credentialHint) {
     }
     return new JoyApiError("forbidden", `This operation is not permitted with the current credential (read-only key or insufficient scope).${detail} Do NOT retry with the same credential.`, status);
   }
+  if (status === 402) {
+    return new JoyApiError("plan_gate", `The shop's plan does not include REST API or MCP access.${detail} Do NOT retry \u2014 tell the merchant to upgrade their Joy plan; the response's upgrade_url links straight to their subscription page.`, status);
+  }
   if (status === 429) {
     const wait = retryAfter ? `${retryAfter} seconds` : "~10 seconds";
-    return new JoyApiError("rate_limit", `Rate limited: the Joy API allows 120 requests per 10 seconds per shop. Wait ${wait} before the next call, and prefer fewer, more specific queries (e.g. filter by email instead of listing pages). Do NOT retry immediately.`, status);
+    return new JoyApiError(
+      "rate_limit",
+      // No hard-coded ceiling here: the limit is per-plan (and there are two of them, a burst
+      // window and a daily quota), so any number written into this string is wrong for most
+      // shops. The server states the real one in `detail`, and Retry-After carries the wait.
+      `Rate limited by the Joy API.${detail} Wait ${wait} before the next call, and prefer fewer, more specific queries (e.g. filter by email instead of listing pages). Do NOT retry immediately.`,
+      status
+    );
   }
   if (status === 404) {
+    if (!serverMessage) {
+      return new JoyApiError("not_found", "This endpoint does not exist on the Joy backend this shop is connected to. Nothing is wrong with the arguments and there is no identifier to re-check \u2014 the shop is on a deployment older than this tool. Do NOT retry, do NOT try a lookup tool, and do NOT substitute data from another tool. Tell the merchant this feature is unavailable on their current Joy version.", status);
+    }
     return new JoyApiError("not_found", `Not found.${detail} Verify the identifier and try a lookup tool first (e.g. joy_find_member) instead of guessing IDs.`, status);
   }
   if (status === 400 || status === 422) {
@@ -184,7 +207,7 @@ var JoyApi = class {
       });
     } catch (error) {
       if (error instanceof Error && error.name === "TimeoutError") {
-        throw new JoyApiError("timeout", `The Joy API did not respond within ${Math.round(timeoutMs / 1e3)}s. Safe to retry ONCE; if it times out again, report the outage instead of retrying further.`);
+        throw new JoyApiError("timeout", `The Joy API did not respond within ${Math.round(timeoutMs / 1e3)}s. The first call after an idle period pays a Cloud Functions cold start, so a lone timeout is usually transient rather than an outage. Safe to retry ONCE; if it times out again, report the outage instead of retrying further.`);
       }
       throw new JoyApiError("network", `Could not reach the Joy API at ${this.config.apiBaseUrl}. Check network connectivity and JOY_API_BASE_URL. Safe to retry ONCE.`);
     }
@@ -232,9 +255,15 @@ var TtlCache = class {
     this.store.set(key, { expiresAt: now + ttlMs, promise });
     return promise;
   }
+  delete(key) {
+    this.store.delete(key);
+  }
 };
 
 // ../mcp-core/build/tools/members.js
+import { z as z2 } from "zod";
+
+// ../mcp-core/build/toolkit.js
 import { z } from "zod";
 
 // ../mcp-core/build/logger.js
@@ -247,56 +276,160 @@ var log = {
   }
 };
 
+// ../mcp-core/build/store.js
+function displayName(store) {
+  return store.name.replace(/[\u0000-\u001f\u007f[\]]+/g, " ").trim() || store.myshopifyDomain;
+}
+function storeLabel(store, maxNameLength = 60) {
+  const safeName = displayName(store);
+  const name = safeName.length > maxNameLength ? `${safeName.slice(0, Math.max(0, maxNameLength - 1))}\u2026` : safeName;
+  return `${name} (${store.myshopifyDomain})`;
+}
+function storeDescriptionPrefix(store) {
+  return `[Store: ${storeLabel(store)}] `;
+}
+function stampResult(text, store) {
+  return `[Store: ${storeLabel(store)}]
+${text}`;
+}
+function normalizeStoreInput(raw) {
+  let normalized = raw.trim().toLowerCase();
+  normalized = normalized.replace(/^https?:\/\//, "");
+  normalized = normalized.replace(/^www\./, "");
+  const slashIdx = normalized.indexOf("/");
+  if (slashIdx !== -1) {
+    normalized = normalized.slice(0, slashIdx);
+  }
+  normalized = normalized.split(/[?#]/)[0];
+  normalized = normalized.replace(/[./]+$/, "");
+  return normalized;
+}
+function matchesStore(raw, store) {
+  if (!raw || !raw.trim()) {
+    return false;
+  }
+  const normalized = normalizeStoreInput(raw);
+  if (normalized === normalizeStoreInput(store.myshopifyDomain)) {
+    return true;
+  }
+  if (store.primaryDomain && normalized === normalizeStoreInput(store.primaryDomain)) {
+    return true;
+  }
+  if (raw.trim().toLowerCase() === store.name.trim().toLowerCase()) {
+    return true;
+  }
+  return false;
+}
+function storeMismatchMessage(raw, store) {
+  const target = raw.length > 100 ? `${raw.slice(0, 99)}\u2026` : raw;
+  return `Rejected \u2014 this connector is bound to ${storeLabel(store)} but the call targeted "${target}". Nothing was changed. Use the connector for that store. Only retry here if the user explicitly confirms they mean ${displayName(store)} \u2014 ask them, do not assume.`;
+}
+var STORE_ARG_DESCRIPTION = `The store the USER asked to change \u2014 its name or domain, taken from the user's own words or an earlier turn, never copied from this tool's description. If it is not clear which store the user means, ask them before calling. The server rejects the call when this does not match the store this connector is bound to. If the user has not named a store and this is the only Joy connector enabled, the store this connector is bound to is the one meant.`;
+
 // ../mcp-core/build/toolkit.js
-async function runHandler(name, run) {
+async function runHandler(name, run, store) {
   try {
     const text = await run();
-    return { content: [{ type: "text", text }] };
+    return { content: [{ type: "text", text: store ? stampResult(text, store) : text }] };
   } catch (error) {
     if (error instanceof JoyApiError) {
-      return { isError: true, content: [{ type: "text", text: error.modelMessage }] };
+      const text2 = store ? stampResult(error.modelMessage, store) : error.modelMessage;
+      return { isError: true, content: [{ type: "text", text: text2 }] };
     }
     const message = error instanceof Error ? error.message : String(error);
     log.error(`${name} failed unexpectedly: ${message}`);
+    const text = `Unexpected error in ${name}: ${message}. This is likely a bug in the Joy MCP server, not your input \u2014 report it to the merchant rather than retrying.`;
     return {
       isError: true,
-      content: [
-        {
-          type: "text",
-          text: `Unexpected error in ${name}: ${message}. This is likely a bug in the Joy MCP server, not your input \u2014 report it to the merchant rather than retrying.`
-        }
-      ]
+      content: [{ type: "text", text: store ? stampResult(text, store) : text }]
     };
   }
 }
-function registerReadTool(server, spec) {
-  const callback = (async (args) => runHandler(spec.name, () => spec.handler(args ?? {})));
+function registerReadTool(server, ctx, spec) {
+  const callback = (async (args) => runHandler(spec.name, () => spec.handler(args ?? {}), ctx.store));
   server.registerTool(spec.name, {
     title: spec.title,
-    description: spec.description,
+    description: ctx.store ? storeDescriptionPrefix(ctx.store) + spec.description : spec.description,
     inputSchema: spec.inputSchema,
     annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
   }, callback);
 }
+function withStoreArg(shape, store) {
+  if (!store)
+    return shape;
+  return { ...shape, store: z.string().describe(STORE_ARG_DESCRIPTION) };
+}
+function checkStoreMismatch(name, args, store) {
+  const raw = typeof args?.store === "string" ? args.store : "";
+  if (matchesStore(raw, store))
+    return void 0;
+  log.info(`${name} rejected: store mismatch (bound=${store.myshopifyDomain})`);
+  return {
+    isError: true,
+    content: [{ type: "text", text: stampResult(storeMismatchMessage(raw, store), store) }]
+  };
+}
+function stripStoreArg(args) {
+  const { store: _store, ...rest } = args ?? {};
+  return rest;
+}
+function registerConfigWriteTool(server, ctx, spec) {
+  const strictStore = ctx.store && ctx.requireStoreArg ? ctx.store : void 0;
+  const callback = (async (args) => {
+    if (strictStore) {
+      const mismatch = checkStoreMismatch(spec.name, args, strictStore);
+      if (mismatch)
+        return mismatch;
+    }
+    if (!ctx.config.configWritesEnabled) {
+      const text = `${spec.name} is disabled: this server cannot change shop configuration. The merchant must set BOTH JOY_MCP_ENABLE_WRITES="true" and JOY_MCP_ENABLE_CONFIG_WRITES="true" (quoted strings, with their secret key) in the MCP config. Do not retry until they have \u2014 and do not fall back to a member-level write tool to approximate a configuration change.`;
+      return {
+        isError: true,
+        content: [{ type: "text", text: ctx.store ? stampResult(text, ctx.store) : text }]
+      };
+    }
+    const handlerArgs = strictStore ? stripStoreArg(args) : args ?? {};
+    return runHandler(spec.name, () => spec.handler(handlerArgs), ctx.store);
+  });
+  const registration = {
+    title: spec.title,
+    description: ctx.store ? storeDescriptionPrefix(ctx.store) + spec.description : spec.description,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: spec.destructiveHint,
+      idempotentHint: false,
+      openWorldHint: false
+    }
+  };
+  if (spec.strictArguments) {
+    const inputSchema = z.object(withStoreArg(spec.inputSchema, strictStore)).strict();
+    server.registerTool(spec.name, { ...registration, inputSchema }, callback);
+    return;
+  }
+  server.registerTool(spec.name, { ...registration, inputSchema: withStoreArg(spec.inputSchema, strictStore) }, callback);
+}
 function registerWriteTool(server, ctx, spec) {
+  const strictStore = ctx.store && ctx.requireStoreArg ? ctx.store : void 0;
   const callback = (async (args) => {
+    if (strictStore) {
+      const mismatch = checkStoreMismatch(spec.name, args, strictStore);
+      if (mismatch)
+        return mismatch;
+    }
     if (!ctx.config.writesEnabled) {
+      const text = `${spec.name} is disabled: this server is running read-only. The merchant must set JOY_MCP_ENABLE_WRITES=true (with their secret key) in the MCP config to allow write operations. Do not retry until they have.`;
       return {
         isError: true,
-        content: [
-          {
-            type: "text",
-            text: `${spec.name} is disabled: this server is running read-only. The merchant must set JOY_MCP_ENABLE_WRITES=true (with their secret key) in the MCP config to allow write operations. Do not retry until they have.`
-          }
-        ]
+        content: [{ type: "text", text: ctx.store ? stampResult(text, ctx.store) : text }]
       };
     }
-    return runHandler(spec.name, () => spec.handler(args ?? {}));
+    const handlerArgs = strictStore ? stripStoreArg(args) : args ?? {};
+    return runHandler(spec.name, () => spec.handler(handlerArgs), ctx.store);
   });
   server.registerTool(spec.name, {
     title: spec.title,
-    description: spec.description,
-    inputSchema: spec.inputSchema,
+    description: ctx.store ? storeDescriptionPrefix(ctx.store) + spec.description : spec.description,
+    inputSchema: withStoreArg(spec.inputSchema, strictStore),
     annotations: {
       readOnlyHint: false,
       destructiveHint: spec.destructiveHint,
@@ -415,8 +548,8 @@ var REWARD_KEYS = [
   "createdAt"
 ];
 var memberIdentifierSchema = {
-  email: z.string().optional().describe("Member email. Matched exactly after lowercasing/trimming \u2014 typos return no result."),
-  shopify_customer_id: z.string().optional().describe('Shopify customer ID (numeric string), e.g. "7348912345".')
+  email: z2.string().optional().describe("Member email. Matched exactly after lowercasing/trimming \u2014 typos return no result."),
+  shopify_customer_id: z2.string().optional().describe('Shopify customer ID (numeric string), e.g. "7348912345".')
 };
 function normalizeEmail(email) {
   return email.trim().toLowerCase();
@@ -456,7 +589,7 @@ function reclassifyCursorError(error, after) {
   throw error;
 }
 function registerMemberTools(server, ctx) {
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_find_member",
     title: "Find a loyalty member",
     description: 'Look up ONE loyalty member by email or Shopify customer ID and return their points balance, VIP tier, and lifetime stats. Use this first whenever the merchant refers to a specific customer. Email matching is exact (case-insensitive) \u2014 if it misses, confirm spelling before concluding the customer is not a member. Field notes: "point" is the CURRENT spendable balance; "totalEarnedPoints" is lifetime earned (not spendable); "pointsRemain" is points needed to reach the next tier. Shopify store credit (money) is NOT included here \u2014 use joy_get_member_store_credit for that.',
@@ -468,7 +601,7 @@ function registerMemberTools(server, ctx) {
       return summaryWithJson(`Member ${memberDisplayName(member)}: ${formatPoints(member.point)} points${tier}.`, shaped);
     }
   });
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_get_member_store_credit",
     title: "Get a member's store credit balance",
     description: "Shopify STORE CREDIT balance for ONE member (by email or Shopify customer ID). Store credit is real MONEY on the customer's Shopify account (e.g. from referral rewards or refunds) \u2014 it is NOT loyalty points; for the points balance use joy_find_member. A customer holds at most one account per currency, so multiple accounts mean multiple currencies. No account = zero store credit.",
@@ -496,17 +629,17 @@ function registerMemberTools(server, ctx) {
       });
     }
   });
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_list_members",
     title: "List loyalty members",
     description: 'List loyalty members a page at a time, with sorting and an optional VIP-tier filter. Default order is most RECENT ACTIVITY (updatedAt desc). For ranking questions use sort_by \u2014 "which customer has the most points?" / "top 10 members" is ONE call with sort_by "points" (the first page IS the leaderboard; never page through the whole list for this). "How many customers/members does the shop have?" is ONE call with include_total_count true and limit 1 \u2014 never sum tier counts or page the list for this. sort_by "created_at" answers newest/oldest signups; tier_id narrows any of these to one tier. To inspect ONE known customer, prefer joy_find_member (cheaper and more precise). Returns up to `limit` members plus `has_more` and `next_after`; pass `next_after` back as `after` for the next page. Do not page through the whole list to answer aggregate questions \u2014 that burns the shop\'s API rate limit.',
     inputSchema: {
-      limit: z.number().int().min(1).max(100).optional().describe("Members per page (default 20, max 100)."),
-      sort_by: z.enum(["points", "tier_points", "created_at", "recent_activity"]).optional().describe('Sort field (default recent_activity). "points" = current spendable balance (use for top/bottom members by points); "tier_points" = VIP tier progress points; "created_at" = signup date; "recent_activity" = last update.'),
-      direction: z.enum(["desc", "asc"]).optional().describe('"desc" (default) = highest/newest first; "asc" = lowest/oldest first.'),
-      tier_id: z.string().optional().describe("Only members currently in this VIP tier. Must be a tier `id` from joy_list_tiers, NOT the tier name."),
-      include_total_count: z.boolean().optional().describe("Set true when the merchant asks HOW MANY members/customers there are \u2014 returns total_members (exact count of the whole list, respecting tier_id). Combine with limit 1 when only the number is needed. Costs extra database reads; leave unset otherwise."),
-      after: z.string().optional().describe("Cursor: a next_after value returned by a previous call. Never invent one, and only reuse it with the SAME sort_by/direction/tier_id that produced it.")
+      limit: z2.number().int().min(1).max(100).optional().describe("Members per page (default 20, max 100)."),
+      sort_by: z2.enum(["points", "tier_points", "created_at", "recent_activity"]).optional().describe('Sort field (default recent_activity). "points" = current spendable balance (use for top/bottom members by points); "tier_points" = VIP tier progress points; "created_at" = signup date; "recent_activity" = last update.'),
+      direction: z2.enum(["desc", "asc"]).optional().describe('"desc" (default) = highest/newest first; "asc" = lowest/oldest first.'),
+      tier_id: z2.string().optional().describe("Only members currently in this VIP tier. Must be a tier `id` from joy_list_tiers, NOT the tier name."),
+      include_total_count: z2.boolean().optional().describe("Set true when the merchant asks HOW MANY members/customers there are \u2014 returns total_members (exact count of the whole list, respecting tier_id). Combine with limit 1 when only the number is needed. Costs extra database reads; leave unset otherwise."),
+      after: z2.string().optional().describe("Cursor: a next_after value returned by a previous call. Never invent one, and only reuse it with the SAME sort_by/direction/tier_id that produced it.")
     },
     handler: async (args) => {
       const limit = args.limit ?? 20;
@@ -557,14 +690,14 @@ function registerMemberTools(server, ctx) {
       });
     }
   });
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_get_member_activity",
     title: "Get a member's point activity",
     description: 'Point transactions (earned, spent, adjusted, refund deductions\u2026) for ONE member, most recent first. Use to answer "why is this customer\'s balance X?" or to audit changes. Each entry shows the point change, balance before/after (oldPoint \u2192 newPoint), the source system, and any notes. Returns `next_after` when more history exists \u2014 pass it back as `after` to keep auditing.',
     inputSchema: {
       ...memberIdentifierSchema,
-      limit: z.number().int().min(1).max(50).optional().describe("Transactions per page (default 10, max 50)."),
-      after: z.string().optional().describe("Cursor: a next_after value returned by a previous call. Never invent one.")
+      limit: z2.number().int().min(1).max(50).optional().describe("Transactions per page (default 10, max 50)."),
+      after: z2.string().optional().describe("Cursor: a next_after value returned by a previous call. Never invent one.")
     },
     handler: async (args) => {
       const limit = args.limit ?? 10;
@@ -594,14 +727,14 @@ function registerMemberTools(server, ctx) {
       });
     }
   });
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_get_member_rewards",
     title: "Get a member's reward/coupon history",
     description: `Coupons and rewards ONE member has already redeemed \u2014 code, discount program, status (active/used/expired), expiry. This is the member's OWN history, NOT the shop's catalog of what CAN be redeemed (use joy_list_redemption_rules for that). Use to answer "what coupons does this customer have?" or "did they already use that discount code?".`,
     inputSchema: {
       ...memberIdentifierSchema,
-      limit: z.number().int().min(1).max(50).optional().describe("Rewards per page (default 10, max 50)."),
-      after: z.string().optional().describe("Cursor: a next_after value returned by a previous call. Never invent one.")
+      limit: z2.number().int().min(1).max(50).optional().describe("Rewards per page (default 10, max 50)."),
+      after: z2.string().optional().describe("Cursor: a next_after value returned by a previous call. Never invent one.")
     },
     handler: async (args) => {
       const limit = args.limit ?? 10;
@@ -634,7 +767,7 @@ function registerMemberTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/tiers.js
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 var TIER_KEYS = [
   "id",
   "name",
@@ -650,23 +783,68 @@ var TIER_KEYS = [
   "systemType"
 ];
 var TIERS_TTL_MS = 15 * 60 * 1e3;
+var TIER_PROGRAM_KEYS = [
+  "status",
+  "entryMethod",
+  "startDate",
+  "prefix",
+  "isUsePrefixDiscountCode",
+  "showTierPointSettings",
+  "allowGiveEntryRewardAgain",
+  "useDemotionTier",
+  "typeDemotion",
+  "useResetTier",
+  "resetFrequency"
+];
+var LEVEL_UP_RULE_LABELS = {
+  pointEarned: "points earned",
+  moneySpent: "amount spent",
+  numberOfOrders: "number of orders"
+};
+function calculationSummary(settings, tiers) {
+  const entryMethod = typeof settings.entryMethod === "string" && settings.entryMethod || tiers.find((tier) => typeof tier.entryMethod === "string")?.entryMethod;
+  const label = typeof entryMethod === "string" ? LEVEL_UP_RULE_LABELS[entryMethod] : void 0;
+  if (!label)
+    return "";
+  const start = typeof settings.startDate === "string" && settings.startDate ? `, since ${settings.startDate.slice(0, 10)}` : "";
+  return ` Level-up rule: ${label}${start}.`;
+}
+async function readTierProgramSettings(ctx) {
+  try {
+    const { data } = await ctx.api.getData("/tiers/settings");
+    return data && typeof data === "object" ? data : {};
+  } catch (error) {
+    if (error instanceof JoyApiError && error.kind === "not_found")
+      return {};
+    throw error;
+  }
+}
 function getTiersCached(ctx) {
   return ctx.cache.get("tiers", TIERS_TTL_MS, async () => {
-    const { data } = await ctx.api.getData("/tiers");
-    return Array.isArray(data) ? data : [];
+    const [tiersResult, settings] = await Promise.all([
+      ctx.api.getData("/tiers"),
+      readTierProgramSettings(ctx)
+    ]);
+    return {
+      tiers: Array.isArray(tiersResult.data) ? tiersResult.data : [],
+      settings
+    };
   });
 }
 function registerTierTools(server, ctx) {
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_list_tiers",
     title: "List VIP tiers",
-    description: 'List the shop\'s VIP tiers with thresholds (targetPoint/targetAmount), earning multipliers, and per-tier benefits (tierRewards). Use to understand the tier ladder before answering tier questions. For "how many customers are in tier X?" set include_member_counts \u2014 it returns memberCount (live count of current members) per tier; the plain `members` field is a stale cached snapshot, NEVER quote it as the member count. Config-only calls are cached ~15 minutes \u2014 one call per conversation is enough.',
+    description: 'List the shop\'s VIP tiers plus the program "Tier calculation" settings (entryMethod, startDate, prefix). Thresholds (targetPoint) are in the unit of entryMethod \u2014 150 means 150 points, $150 spent, or 150 orders depending on that rule. Also includes earning multipliers and per-tier benefits (tierRewards). For "how many customers are in tier X?" set include_member_counts \u2014 it returns memberCount (live count of current members) per tier; the plain `members` field is a stale cached snapshot, NEVER quote it as the member count. Config-only calls are cached ~15 minutes \u2014 one call per conversation is enough. To change calculation / demotion / reset settings, use joy_configure_tier_settings.',
     inputSchema: {
-      include_member_counts: z2.boolean().optional().describe("Set true ONLY when the merchant asks how many customers/members are in tiers \u2014 adds memberCount (live count) per tier. Leave unset for tier-config questions; counting costs extra database reads.")
+      include_member_counts: z3.boolean().optional().describe("Set true ONLY when the merchant asks how many customers/members are in tiers \u2014 adds memberCount (live count) per tier. Leave unset for tier-config questions; counting costs extra database reads.")
     },
     handler: async (args) => {
       if (args.include_member_counts === true) {
-        const { data } = await ctx.api.getData("/tiers", { query: { hasCount: true } });
+        const [{ data }, settings2] = await Promise.all([
+          ctx.api.getData("/tiers", { query: { hasCount: true } }),
+          readTierProgramSettings(ctx)
+        ]);
         const tiers2 = Array.isArray(data) ? data : [];
         if (tiers2.length === 0) {
           return "This shop has no VIP tiers configured. Tier-related questions do not apply.";
@@ -674,13 +852,19 @@ function registerTierTools(server, ctx) {
         const keys = [...TIER_KEYS.filter((key) => key !== "members"), "memberCount"];
         const total = tiers2.reduce((sum, tier) => sum + (Number(tier.memberCount) || 0), 0);
         const top = [...tiers2].sort((a, b) => (Number(b.memberCount) || 0) - (Number(a.memberCount) || 0))[0];
-        return summaryWithJson(`${tiers2.length} VIP tier(s), ${total} member(s) total \u2014 largest: "${String(top.name)}" (${Number(top.memberCount) || 0} members).`, tiers2.map((tier) => compact(tier, keys)));
+        return summaryWithJson(`${tiers2.length} VIP tier(s), ${total} member(s) total \u2014 largest: "${String(top.name)}" (${Number(top.memberCount) || 0} members).${calculationSummary(settings2, tiers2)}`, {
+          program: compact(settings2, TIER_PROGRAM_KEYS),
+          tiers: tiers2.map((tier) => compact(tier, keys))
+        });
       }
-      const tiers = await getTiersCached(ctx);
+      const { tiers, settings } = await getTiersCached(ctx);
       if (tiers.length === 0) {
         return "This shop has no VIP tiers configured. Tier-related questions do not apply.";
       }
-      return summaryWithJson(`${tiers.length} VIP tier(s) configured.`, tiers.map((tier) => compact(tier, TIER_KEYS)));
+      return summaryWithJson(`${tiers.length} VIP tier(s) configured.${calculationSummary(settings, tiers)}`, {
+        program: compact(settings, TIER_PROGRAM_KEYS),
+        tiers: tiers.map((tier) => compact(tier, TIER_KEYS))
+      });
     }
   });
 }
@@ -691,9 +875,9 @@ function registerTierWriteTools(server, ctx) {
     description: "WRITE \u2014 manually moves ONE member to a VIP tier (may trigger tier rewards for the member). Find valid tier IDs via joy_list_tiers first. Setting the tier the member already has is a safe no-op. admin_note is recorded on the tier-change activity.",
     inputSchema: {
       ...memberIdentifierSchema,
-      tier_id: z2.string().describe("Target tier ID (from joy_list_tiers)."),
-      reason: z2.string().min(3).describe("Why the tier is being changed \u2014 REQUIRED, recorded on the tier-change activity."),
-      admin_note: z2.string().optional().describe("Optional extra note for the merchant team.")
+      tier_id: z3.string().describe("Target tier ID (from joy_list_tiers)."),
+      reason: z3.string().min(3).describe("Why the tier is being changed \u2014 REQUIRED, recorded on the tier-change activity."),
+      admin_note: z3.string().optional().describe("Optional extra note for the merchant team.")
     },
     destructiveHint: true,
     idempotentHint: true,
@@ -719,7 +903,7 @@ function registerTierWriteTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/programs.js
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var EARNING_KEYS = [
   "id",
   "event",
@@ -730,6 +914,9 @@ var EARNING_KEYS = [
   "rateMoney",
   "earnPoint",
   "earnPointsTiers",
+  "isAppliedVipTier",
+  "appliedPlaceOrderTo",
+  "skipEarnPointGuest",
   "conditions",
   "typeMilestone",
   "milestones",
@@ -737,7 +924,15 @@ var EARNING_KEYS = [
   "endDate",
   "priority",
   "isDraft",
-  "expired"
+  "expired",
+  // The artwork on this program's card, wherever the loyalty page draws it.
+  // Read-only here, and included because their ABSENCE was unreadable: the page
+  // design tool offers iconColor/iconBackground/iconRadius, which tells an agent
+  // a glyph exists without telling it where — one cold-context run spent three
+  // refused calls guessing `cardStyle.icon` before concluding, correctly, that
+  // artwork is not part of the page design at all.
+  "loyaltyPageIcon",
+  "loyaltyPageCustomIcon"
 ];
 var SPENDING_KEYS = [
   "id",
@@ -763,13 +958,49 @@ var SPENDING_KEYS = [
   "hasLimitShipping",
   "limitShipping",
   "enableMaxCapShipping",
-  "maxCapShipping"
+  "maxCapShipping",
+  // See EARNING_KEYS — same reason, same pair.
+  "loyaltyPageIcon",
+  "loyaltyPageCustomIcon"
 ];
+var CATALOGUE_ARRAYS = ["specificProducts", "variantIds", "freeProductIds", "appliedCollectionIds"];
+function compactReward(reward) {
+  if (!reward || typeof reward !== "object" || Array.isArray(reward))
+    return reward;
+  const out = {};
+  for (const [key, value] of Object.entries(reward)) {
+    if (CATALOGUE_ARRAYS.includes(key)) {
+      if (Array.isArray(value) && value.length)
+        out[`${key}Count`] = value.length;
+      continue;
+    }
+    out[key] = value;
+  }
+  return out;
+}
+function compactMilestones(milestones) {
+  if (!Array.isArray(milestones))
+    return milestones;
+  return milestones.map((milestone) => {
+    if (!milestone || typeof milestone !== "object" || Array.isArray(milestone))
+      return milestone;
+    const entry = milestone;
+    if (!Array.isArray(entry.rewards))
+      return entry;
+    return { ...entry, rewards: entry.rewards.map(compactReward) };
+  });
+}
+function compactEarningProgram(program) {
+  const compacted = compact(program, EARNING_KEYS);
+  if (compacted.milestones === void 0)
+    return compacted;
+  return { ...compacted, milestones: compactMilestones(compacted.milestones) };
+}
 function registerProgramTools(server, ctx) {
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_list_earning_rules",
     title: "List point-earning rules",
-    description: 'List the ways customers EARN points (place order, sign up, birthday, social follows\u2026). Use to answer "how do customers get points?". IMPORTANT: when a rule has earnPointsTiers, the per-VIP-tier multipliers there override the flat earnPoint \u2014 quote the tiered values, not just the base rate.',
+    description: 'List the ways customers EARN points (place order, sign up, birthday, social follows\u2026). Use to answer "how do customers get points?". For place_order, appliedPlaceOrderTo is the admin "Who to reward" radio (all = All loyalty members, vip-tier = VIP Tier only, member_and_guest = All customers) \u2014 quote that, not just earnPointsTiers. When a rule has earnPointsTiers AND appliedPlaceOrderTo is vip-tier, the per-VIP-tier rates override the flat earnPoint.',
     inputSchema: {},
     handler: async () => {
       const { data } = await ctx.api.getData("/programs/earning");
@@ -777,15 +1008,15 @@ function registerProgramTools(server, ctx) {
       if (programs.length === 0) {
         return "No earning rules configured \u2014 customers currently have no way to earn points.";
       }
-      return summaryWithJson(`${programs.length} earning rule(s) configured.`, programs.map((program) => compact(program, EARNING_KEYS)));
+      return summaryWithJson(`${programs.length} earning rule(s) configured.`, programs.map(compactEarningProgram));
     }
   });
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_list_redemption_rules",
     title: "List point-redemption rules",
     description: 'List the ways customers SPEND points (discount amount, percentage off, free shipping, free gift\u2026), including point costs (spendPoint) and min/max limits. Use to answer "what can customers redeem?" and to find the programId for a redemption. For USAGE questions \u2014 "which reward is redeemed most?", "how many times was program X redeemed?" \u2014 set include_redeem_counts to get redeemCount (all-time REDEMPTIONS, not unique customers) per rule in the same call. Redeeming itself is a separate write operation, not available through this tool.',
     inputSchema: {
-      include_redeem_counts: z3.boolean().optional().describe("Set true ONLY when the merchant asks about usage/popularity \u2014 adds redeemCount (all-time number of redemptions) to each rule. Leave unset for pure configuration questions; counting costs extra database reads.")
+      include_redeem_counts: z4.boolean().optional().describe("Set true ONLY when the merchant asks about usage/popularity \u2014 adds redeemCount (all-time number of redemptions) to each rule. Leave unset for pure configuration questions; counting costs extra database reads.")
     },
     handler: async (args) => {
       const withCounts = args.include_redeem_counts === true;
@@ -809,7 +1040,102 @@ function registerProgramTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/referrals.js
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
+
+// ../mcp-core/build/tools/configSupport.js
+function parseShopifyProductUrl(productUrl) {
+  try {
+    const url = new URL(productUrl);
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+      return { ok: false, error: "Product URLs must start with http:// or https://." };
+    }
+    const path = url.pathname.split("/").filter(Boolean);
+    const directHandle = path.length === 2 && path[0] === "products" ? path[1] : void 0;
+    const collectionHandle = path.length === 4 && path[0] === "collections" && path[2] === "products" ? path[3] : void 0;
+    const handle = directHandle ?? collectionHandle;
+    if (!handle) {
+      return {
+        ok: false,
+        error: "Use a Shopify product URL in the form https://shop.myshopify.com/products/<handle> or https://shop.myshopify.com/collections/<collection>/products/<handle>."
+      };
+    }
+    return { ok: true, handle: decodeURIComponent(handle) };
+  } catch {
+    return {
+      ok: false,
+      error: "Use a Shopify product URL in the form https://shop.myshopify.com/products/<handle> or https://shop.myshopify.com/collections/<collection>/products/<handle>."
+    };
+  }
+}
+function isSameValue(a, b) {
+  if (a === b)
+    return true;
+  if (typeof a === "number" && typeof b === "string")
+    return String(a) === b;
+  if (typeof a === "string" && typeof b === "number")
+    return a === String(b);
+  if (Array.isArray(a) && Array.isArray(b))
+    return JSON.stringify(a) === JSON.stringify(b);
+  return false;
+}
+function diffFields(current, incoming) {
+  const changes = [];
+  for (const [field, to] of Object.entries(incoming)) {
+    if (to === void 0)
+      continue;
+    const from = current[field];
+    if (isSameValue(from, to))
+      continue;
+    changes.push({ field, from, to });
+  }
+  return changes;
+}
+function droppedFields(incoming, allowedKeys) {
+  const allowed = new Set(allowedKeys);
+  return Object.entries(incoming).filter(([field, value]) => value !== void 0 && !allowed.has(field)).map(([field]) => field);
+}
+function findDuplicate(existing, candidate) {
+  const normalise = (value) => String(value ?? "").trim().toLowerCase();
+  const event = normalise(candidate.event);
+  const title = normalise(candidate.title);
+  return existing.find((item) => {
+    if (event && normalise(item.event) !== event)
+      return false;
+    if (title)
+      return normalise(item.title) === title;
+    return Boolean(event);
+  });
+}
+var formatValue = (value) => value === void 0 || value === null || value === "" ? "(unset)" : JSON.stringify(value);
+function buildChangePreview(input) {
+  const lines = [];
+  lines.push(`DRY RUN \u2014 nothing has been changed yet.`);
+  lines.push(`Would ${input.action} ${input.target}.`);
+  lines.push(`Reason given: ${input.reason}`);
+  if (input.duplicate) {
+    lines.push(`\u26A0\uFE0F A matching rule already exists (id ${String(input.duplicate.id)}, "${String(input.duplicate.title)}"). Creating this would leave TWO live rules for the same event \u2014 configuration writes are not idempotent, so this is not a replay. Update the existing one by passing its id instead, unless the merchant explicitly wants a second rule.`);
+  }
+  if (input.changes.length === 0) {
+    lines.push("No field would change \u2014 this call is a no-op. Do not report it as a change.");
+  } else {
+    lines.push("", "Changes:");
+    for (const change of input.changes) {
+      lines.push(`  ${change.field}: ${formatValue(change.from)} \u2192 ${formatValue(change.to)}`);
+    }
+  }
+  if (input.dropped && input.dropped.length > 0) {
+    lines.push("", `\u26A0\uFE0F These fields would be SILENTLY DISCARDED by the backend (not valid for this record type): ${input.dropped.join(", ")}. The call would still return success. Remove them or use the right tool \u2014 do not report them as applied.`);
+  }
+  for (const warning of input.warnings ?? [])
+    lines.push("", `\u26A0\uFE0F ${warning}`);
+  lines.push("", "This affects every customer, not one member, and takes effect as soon as it saves. Show this to the merchant and get an explicit yes; then call again with apply: true and the same arguments. Joy does not record who changed configuration or why, so this preview is the only audit trail.");
+  return lines.join("\n");
+}
+function requireApply(apply, preview) {
+  return apply === true ? void 0 : preview;
+}
+
+// ../mcp-core/build/tools/referrals.js
 var REFERRAL_ACTIVITY_KEYS = [
   "id",
   "email",
@@ -841,6 +1167,113 @@ var REFERRAL_PROGRAM_KEYS = [
   "referralSharingMode",
   "autoRevokeReferrerReward"
 ];
+var CUSTOMER_REWARD_DISCOUNT_TYPES = [
+  "percentage",
+  "amount",
+  "point",
+  "point_order_value",
+  "store_credit_fixed",
+  "store_credit_order_value"
+];
+var FRIEND_REWARD_DISCOUNT_TYPES = ["percentage", "amount", "store_credit_fixed"];
+var REFERRAL_EXPIRATION_PATTERN = /^(?:permanent|specific|\d+(?:min|D|W|M|Y))$/;
+var ORDER_REQUIREMENTS = ["none", "min_amount", "min_quantity"];
+var REFERRAL_PROGRAM_ARGUMENTS = {
+  status: "status",
+  title: "title",
+  customer_reward_earn_amount: "customerRewardEarnAmount",
+  customer_reward_discount_type: "customerRewardDiscountType",
+  customer_reward_expired_after: "customerRewardExpiredAfter",
+  customer_reward_order_req: "customerRewardOrderReq",
+  customer_reward_order_req_amount: "customerRewardOrderReqAmount",
+  friend_reward_earn_amount: "friendRewardEarnAmount",
+  friend_reward_discount_type: "friendRewardDiscountType",
+  friend_reward_expired_after: "friendRewardExpiredAfter",
+  friend_reward_order_req: "friendRewardOrderReq",
+  friend_reward_order_req_amount: "friendRewardOrderReqAmount",
+  max_referrals_per_customer: "maxReferralsPerCustomer"
+};
+var referralConfigInputShape = {
+  status: z5.boolean().optional().describe("Enable (true) or disable (false) the referral program."),
+  title: z5.string().trim().min(1).optional().describe("Merchant-facing referral program title."),
+  customer_reward_earn_amount: z5.number().min(0).optional().describe("Reward amount for the REFERRER (the existing customer/advocate)."),
+  customer_reward_discount_type: z5.enum(CUSTOMER_REWARD_DISCOUNT_TYPES).optional().describe("REFERRER reward type. Supports six methods: percentage, amount, point, point_order_value, store_credit_fixed, or store_credit_order_value. This is deliberately broader than friend_reward_discount_type."),
+  customer_reward_expired_after: z5.string().regex(REFERRAL_EXPIRATION_PATTERN).optional().describe("REFERRER reward expiration: permanent, specific, or a duration such as 30D, 2W, 3M, 1Y, or 90min."),
+  customer_reward_order_req: z5.enum(ORDER_REQUIREMENTS).optional().describe("Order requirement for the REFERRER reward: none, min_amount, or min_quantity."),
+  customer_reward_order_req_amount: z5.number().min(0).optional().describe("Minimum amount or quantity for the REFERRER reward order requirement."),
+  friend_reward_earn_amount: z5.number().min(0).optional().describe("Reward amount for the referred FRIEND. Must be 100 or less when friend_reward_discount_type is percentage."),
+  friend_reward_discount_type: z5.enum(FRIEND_REWARD_DISCOUNT_TYPES).optional().describe("Referred FRIEND reward type. ONLY percentage, amount, or store_credit_fixed are supported. Unlike the referrer reward, point and order-value reward types are invalid here."),
+  friend_reward_expired_after: z5.string().regex(REFERRAL_EXPIRATION_PATTERN).optional().describe("FRIEND reward expiration: permanent, specific, or a duration such as 30D, 2W, 3M, 1Y, or 90min."),
+  friend_reward_order_req: z5.enum(ORDER_REQUIREMENTS).optional().describe("Order requirement for the FRIEND reward: none, min_amount, or min_quantity."),
+  friend_reward_order_req_amount: z5.number().min(0).optional().describe("Minimum amount or quantity for the FRIEND reward order requirement."),
+  max_referrals_per_customer: z5.number().int().min(0).optional().describe("Maximum successful referrals allowed per customer. Use 0 only when the merchant intends that configured value."),
+  reason: z5.string().min(3).describe("Why the merchant wants this shop-wide referral configuration changed."),
+  apply: z5.boolean().optional().describe("Set true only after the merchant has approved the dry-run preview.")
+};
+var referralConfigArgsSchema = z5.object(referralConfigInputShape).strict().superRefine((args, ctx) => {
+  if (args.friend_reward_discount_type === "percentage" && (args.friend_reward_earn_amount ?? 0) > 100) {
+    ctx.addIssue({
+      code: z5.ZodIssueCode.custom,
+      path: ["friend_reward_earn_amount"],
+      message: "A percentage friend reward cannot exceed 100."
+    });
+  }
+});
+function toReferralProgramBody(args) {
+  const body = {};
+  for (const [argument, field] of Object.entries(REFERRAL_PROGRAM_ARGUMENTS)) {
+    const value = args[argument];
+    if (value !== void 0)
+      body[field] = value;
+  }
+  return body;
+}
+function parseReferralConfigArgs(args) {
+  const parsed = referralConfigArgsSchema.safeParse(args);
+  if (parsed.success)
+    return parsed.data;
+  const issue = parsed.error.issues[0];
+  const field = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+  throw new JoyApiError("validation", `Invalid referral configuration \u2014 ${field}${issue.message} Fix the named parameter and call again.`);
+}
+function validateEffectiveFriendPercentage(current, body) {
+  const type = body.friendRewardDiscountType ?? current.friendRewardDiscountType;
+  const amount = body.friendRewardEarnAmount ?? current.friendRewardEarnAmount;
+  if (type === "percentage" && typeof amount === "number" && amount > 100) {
+    throw new JoyApiError("validation", "Invalid referral configuration \u2014 friend_reward_earn_amount cannot exceed 100 when the effective friend reward type is percentage. Lower the amount or choose amount/store_credit_fixed, then call again.");
+  }
+}
+async function configureReferralProgram(ctx, input) {
+  const args = parseReferralConfigArgs(input);
+  const body = toReferralProgramBody(args);
+  if (Object.keys(body).length === 0) {
+    throw new JoyApiError("validation", `At least one referral configuration field is required. Valid fields: ${Object.keys(REFERRAL_PROGRAM_ARGUMENTS).join(", ")}.`);
+  }
+  const { data } = await ctx.api.getData("/referrals/program");
+  const current = data ?? {};
+  validateEffectiveFriendPercentage(current, body);
+  const changes = diffFields(current, body);
+  const preview = buildChangePreview({
+    action: "UPDATE",
+    target: `referral program "${String(body.title ?? current.title ?? "current")}"`,
+    reason: args.reason,
+    changes
+  });
+  if (changes.length === 0)
+    return preview;
+  const blocked = requireApply(args.apply, preview);
+  if (blocked)
+    return blocked;
+  await ctx.api.mutateData("/referrals/program", { method: "PUT", body });
+  const { data: refreshedData } = await ctx.api.getData("/referrals/program");
+  const refreshed = refreshedData ?? {};
+  const unconfirmed = diffFields(refreshed, body).map((change) => change.field);
+  if (unconfirmed.length > 0) {
+    throw new JoyApiError("server", `The referral program write was not confirmed: these requested fields did not match after the required read-back: ${unconfirmed.join(", ")}. Do not report the referral program as configured; ask the merchant to verify it in Joy admin and report this backend failure. Do not retry blindly.`);
+  }
+  const appliedFields = Object.keys(body);
+  return summaryWithJson(`Updated the referral program and confirmed ${appliedFields.length} field${appliedFields.length === 1 ? "" : "s"} by reading it back. This affects every customer immediately.`, compact(refreshed, appliedFields));
+}
 function formatReferralReward(amount, type) {
   if (amount === void 0 || amount === null)
     return "not configured";
@@ -853,7 +1286,7 @@ function formatReferralReward(amount, type) {
   return `${String(amount)} (${String(type ?? "unknown type")})`;
 }
 function registerReferralTools(server, ctx) {
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_get_referral_program",
     title: "Get referral program status & configuration",
     description: 'Whether the referral program is ENABLED plus its reward configuration \u2014 use this FIRST for "is the referral program on or off?", "what do referrers/friends get?". `status` is the on/off toggle: true = customers can refer friends, false = the program is turned off. Field naming: customerReward* = what the REFERRER (the advocate) gets; friendReward* = what the referred FRIEND gets; reward type may be "percentage", "amount" (fixed discount), "point", or store-credit. When isAppliedVipTier is true, earnPointsTiers overrides the flat referrer reward per VIP tier. For usage numbers use joy_get_referral_performance; for one member\'s results use joy_get_member_referrals.',
@@ -875,13 +1308,13 @@ function registerReferralTools(server, ctx) {
       return summaryWithJson(`Referral program is ${enabled ? "ENABLED (ON)" : "DISABLED (OFF)"} \u2014 referrer gets ${referrerReward}, referred friend gets ${friendReward}.`, compact(program, REFERRAL_PROGRAM_KEYS));
     }
   });
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_get_referral_performance",
     title: "Get referral program performance",
     description: "Shop-level referral analytics. NOTE: the underlying API currently reports one metric only \u2014 how many referral coupon codes were used (i.e. completed referrals). It does NOT report clicks, signups, or revenue, and it does NOT tell you whether the program is enabled \u2014 use joy_get_referral_program for status/config. Optionally filter by date range.",
     inputSchema: {
-      start_date: z4.string().optional().describe("ISO date (YYYY-MM-DD), inclusive start of the range."),
-      end_date: z4.string().optional().describe("ISO date (YYYY-MM-DD), inclusive end of the range.")
+      start_date: z5.string().optional().describe("ISO date (YYYY-MM-DD), inclusive start of the range."),
+      end_date: z5.string().optional().describe("ISO date (YYYY-MM-DD), inclusive end of the range.")
     },
     handler: async (args) => {
       const { data } = await ctx.api.getData("/referrals/analytics", {
@@ -892,7 +1325,7 @@ function registerReferralTools(server, ctx) {
       return summaryWithJson(`${count} referral coupon(s) were used${range} (completed referrals).`, compact(data ?? {}));
     }
   });
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_get_member_referrals",
     title: "Get one member's referral results",
     description: "Referral results for ONE member (identified by email or Shopify customer ID). Returns (1) aggregate totals \u2014 coupons redeemed via their referrals and points they earned from referring \u2014 and (2) their recent referral activity records. To generate/fetch their personal invite LINK, use joy_create_referral_invite instead.",
@@ -914,14 +1347,25 @@ function registerReferralTools(server, ctx) {
     }
   });
 }
+function registerReferralConfigTools(server, ctx) {
+  registerConfigWriteTool(server, ctx, {
+    name: "joy_configure_referral_program",
+    title: "Configure the referral program",
+    description: "CONFIGURATION WRITE \u2014 updates the shop's single existing referral program; there is no create branch and no program ID. customer_reward_* fields configure the REFERRER/advocate reward, while friend_reward_* fields configure the referred FRIEND reward. Their discount-type enums deliberately differ: the referrer supports six methods, but the friend supports ONLY percentage, amount, or store_credit_fixed (never point or order-value types). Previews by default, requires explicit approval to apply, and reads every requested field back before reporting success. Anti-cheat and eligibility settings are intentionally unavailable through this tool.",
+    inputSchema: referralConfigInputShape,
+    destructiveHint: true,
+    strictArguments: true,
+    handler: (args) => configureReferralProgram(ctx, args)
+  });
+}
 function registerReferralWriteTools(server, ctx) {
   registerWriteTool(server, ctx, {
     name: "joy_create_referral_invite",
     title: "Generate a referral invite link",
     description: "WRITE \u2014 generates a personal referral invite link for an email address. For an EXISTING member this just returns their own link (safe, cheap). For an email that is NOT yet a member, this CREATES A REAL SHOPIFY CUSTOMER RECORD \u2014 irreversible from this tool \u2014 and may trigger sign-up point rewards for them. Double-check the email spelling with the merchant before calling for a non-member; a typo creates a junk customer, not an error. Identify by email only (this can create a new record, so it never accepts shopify_customer_id).",
     inputSchema: {
-      email: z4.string().email().describe("Email address to generate the invite link for. Must be a real, verified address \u2014 a typo creates a real customer record, not an error."),
-      use_marketing: z4.boolean().optional().describe("Marketing consent for a NEW customer record. Defaults to false (no consent). Only pass true if the person actually opted in to marketing \u2014 this can set real email-marketing-consent on their Shopify customer record.")
+      email: z5.string().email().describe("Email address to generate the invite link for. Must be a real, verified address \u2014 a typo creates a real customer record, not an error."),
+      use_marketing: z5.boolean().optional().describe("Marketing consent for a NEW customer record. Defaults to false (no consent). Only pass true if the person actually opted in to marketing \u2014 this can set real email-marketing-consent on their Shopify customer record.")
     },
     destructiveHint: false,
     idempotentHint: false,
@@ -940,7 +1384,7 @@ function registerReferralWriteTools(server, ctx) {
 // ../mcp-core/build/tools/overview.js
 var OVERVIEW_TTL_MS = 15 * 60 * 1e3;
 function registerOverviewTools(server, ctx) {
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_get_loyalty_overview",
     title: "Get loyalty program overview",
     description: 'Orient yourself: shop identity (name, domain, plan, currency, timezone) plus the loyalty program settings. Call this FIRST in a conversation before other Joy tools \u2014 it tells you which shop you are operating on and how its program is configured. Cached ~15 minutes; repeat calls within a conversation are free. This is configuration only \u2014 for performance numbers (revenue impact, points issued, member growth, program health) use the joy_get_* analytics report tools instead, and for "how many members does the shop have?" use joy_list_members with include_total_count.',
@@ -967,7 +1411,7 @@ function registerOverviewTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/analytics.js
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 function toDateRangeQuery(args) {
   const query = {};
   if (args.start_date !== void 0)
@@ -1064,8 +1508,8 @@ var LOYALTY_REVENUE_KEYS = [
 var TIER_PERFORMANCE_KEYS = ["metric", "period", "rows", "topGroup"];
 var HEALTH_CHECK_KEYS = ["healthScore", "flagCount", "flags", "snapshot"];
 var reportDateRangeSchema = {
-  start_date: z5.string().optional().describe("ISO date (YYYY-MM-DD), inclusive start of the report window. Defaults to 30 days ago. Effective range max 366 days."),
-  end_date: z5.string().optional().describe("ISO date (YYYY-MM-DD), inclusive end of the report window. Defaults to today.")
+  start_date: z6.string().optional().describe("ISO date (YYYY-MM-DD), inclusive start of the report window. Defaults to 30 days ago. Effective range max 366 days."),
+  end_date: z6.string().optional().describe("ISO date (YYYY-MM-DD), inclusive end of the report window. Defaults to today.")
 };
 var SCOPE_HELP = "A 403 mentioning read_reports means the MERCHANT has not granted Shopify reports access to Joy \u2014 not a credential problem, do not retry; ask them to grant it from Joy settings.";
 function withScopeGuidance(error) {
@@ -1108,14 +1552,14 @@ async function getScopedReport(ctx, path, options = {}) {
   }
 }
 function registerAnalyticsTools(server, ctx) {
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_get_analytics_report",
     title: "Loyalty analytics report (Analytics V2)",
     description: 'THE primary tool for loyalty analytics questions \u2014 members, VIP tiers, points economy, rewards ROI, coupons, referrals, and loyalty revenue impact. Retrieves any Analytics V2 report using the SAME data and cache as the Analytics dashboard the merchant sees in the Joy admin, so your numbers always match theirs. Joy-internal data \u2014 no Shopify permission needed. Defaults to the last 30 days (max 366-day range, cached server-side ~1h). Returns a pre-digested text summary (time series are collapsed to count/total/latest; tables capped at 8 rows). A 409 error means the shop is still on Analytics V1 (no V2 data exists \u2014 follow the error guidance about migrating, never report zeros); a summary starting with "WARNING: \u2026 backfill" means the historical backfill is unfinished and numbers may be incomplete \u2014 relay that caveat. For Shopify-sales-attributed revenue (order-tag attribution) use joy_get_loyalty_revenue_report instead \u2014 a DIFFERENT data source whose numbers may legitimately differ from assisted_revenue.\n' + V2_REPORT_MENU,
     inputSchema: {
-      report_type: z5.enum(V2_REPORT_TYPES).describe("Which Analytics V2 loyalty report to retrieve (see the menu in the tool description)."),
+      report_type: z6.enum(V2_REPORT_TYPES).describe("Which Analytics V2 loyalty report to retrieve (see the menu in the tool description)."),
       ...reportDateRangeSchema,
-      unit: z5.enum(["day", "month"]).optional().describe("Time grain for trend reports. Defaults by range size (\u2264100 days \u2192 day, else month).")
+      unit: z6.enum(["day", "month"]).optional().describe("Time grain for trend reports. Defaults by range size (\u2264100 days \u2192 day, else month).")
     },
     handler: async (args) => {
       let report;
@@ -1136,16 +1580,16 @@ function registerAnalyticsTools(server, ctx) {
 ${summary}`);
     }
   });
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_get_loyalty_revenue_report",
     title: "Loyalty revenue impact (Shopify sales data)",
     description: `Loyalty revenue impact measured from SHOPIFY'S OWN sales dataset (ShopifyQL), attributed by the shop's "Joy assisted" order tag. Use for: loyalty ROI, "how much revenue does the loyalty program drive?", "is the program making money?", loyalty AOV, year-over-year (YoY) comparison. Metrics: total_sales = revenue from orders tagged "Joy assisted"; aov = average order value of those orders; returning_rate = returning-customer rate among customers tagged as active redeemers; orders = count of Joy-assisted orders. compare_to_last_year applies to total_sales ONLY and is IGNORED when a custom range is given. Custom range = BOTH start_date and end_date (ISO YYYY-MM-DD), max 366 days, not in the future. ` + SCOPE_HELP + " joy_get_analytics_report (reportType assisted_revenue) measures assisted revenue from Joy's own event log \u2014 a DIFFERENT data source with different attribution; the two numbers may legitimately disagree.",
     inputSchema: {
-      metric: z5.enum(["total_sales", "aov", "returning_rate", "orders"]).describe("Which revenue metric to compute (see description for definitions)."),
-      period: z5.enum(["last_7d", "last_30d", "last_90d", "last_1y", "this_month"]).optional().describe("Relative reporting period. Default last_30d. Ignored when start_date/end_date are given."),
-      compare_to_last_year: z5.boolean().optional().describe("Add previous-year comparison (previousValue + deltaPercent). total_sales only; ignored with a custom date range."),
-      start_date: z5.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom range start. Requires end_date too; max 366 days."),
-      end_date: z5.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom range end. Requires start_date too; not in the future.")
+      metric: z6.enum(["total_sales", "aov", "returning_rate", "orders"]).describe("Which revenue metric to compute (see description for definitions)."),
+      period: z6.enum(["last_7d", "last_30d", "last_90d", "last_1y", "this_month"]).optional().describe("Relative reporting period. Default last_30d. Ignored when start_date/end_date are given."),
+      compare_to_last_year: z6.boolean().optional().describe("Add previous-year comparison (previousValue + deltaPercent). total_sales only; ignored with a custom date range."),
+      start_date: z6.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom range start. Requires end_date too; max 366 days."),
+      end_date: z6.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom range end. Requires start_date too; not in the future.")
     },
     handler: async (args) => {
       const data = await getScopedReport(ctx, "/analytics/loyalty-revenue", {
@@ -1156,14 +1600,14 @@ ${summary}`);
       return summaryWithJson(summary, compact(data, LOYALTY_REVENUE_KEYS));
     }
   });
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_get_tier_performance_breakdown",
     title: "Sales performance by VIP tier",
     description: 'Shopify sales performance broken down by VIP tier (ShopifyQL, grouped by the Joy tier metafield). Use for: "which tier spends the most?", "revenue by tier", "AOV per tier", "orders per customer by tier". Default window is ALL-TIME; pass BOTH start_date and end_date (YYYY-MM-DD, max 366 days) to bound it. Rows are tier names sorted by value; "(unassigned)" = customers without a tier. A 422 METAFIELD_NOT_CONFIGURED error means the Joy tier metafield definition is DISABLED on this shop \u2014 that is a setup gate, NOT empty data; ask the merchant to enable it in Joy \u2192 Settings \u2192 General \u2192 Metafield section. For loyalty-side tier reports (member counts, upgrades/downgrades) use joy_get_analytics_report with tier_performance / tier_trend / tier_transitions. ' + SCOPE_HELP,
     inputSchema: {
-      metric: z5.enum(["total_sales", "aov", "orders_per_customer", "spend_per_customer"]).describe("Which per-tier metric to compute."),
-      start_date: z5.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom range start. Requires end_date too; max 366 days. Omit both for all-time."),
-      end_date: z5.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom range end. Requires start_date too.")
+      metric: z6.enum(["total_sales", "aov", "orders_per_customer", "spend_per_customer"]).describe("Which per-tier metric to compute."),
+      start_date: z6.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom range start. Requires end_date too; max 366 days. Omit both for all-time."),
+      end_date: z6.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom range end. Requires start_date too.")
     },
     handler: async (args) => {
       let data;
@@ -1183,13 +1627,13 @@ ${summary}`);
       return summaryWithJson(summary, compact(data, TIER_PERFORMANCE_KEYS));
     }
   });
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_get_loyalty_health_check",
     title: "Loyalty program health check",
     description: `Loyalty program health diagnostic \u2014 use FIRST for open-ended questions: "how is my loyalty program doing?", "is anything wrong?", "why aren't customers earning points?". Compares the current window (default last 30 days) against the equal-length prior window using Joy-internal data only \u2014 aggregate numbers, no customer PII, and NO Shopify permission needed. healthScore = 100 minus a penalty per flag (low 5, medium 15, high 25; floor 0): >=80 Healthy, 60-79 Watch, <60 Needs attention. Flags check: sandbox/test earning mode (real orders are NOT earning points \u2014 the most urgent flag), redemption rate, points-earned trend, redeem-revenue trend, data availability, and tier concentration. Pass start_date+end_date (both, YYYY-MM-DD) to move the current window. For the underlying detail behind a flag, follow up with joy_get_analytics_report.`,
     inputSchema: {
-      start_date: z5.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom current-window start. Requires end_date too."),
-      end_date: z5.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom current-window end. Requires start_date too.")
+      start_date: z6.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom current-window start. Requires end_date too."),
+      end_date: z6.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom current-window end. Requires start_date too.")
     },
     handler: async (args) => {
       const { data } = await ctx.api.getData("/analytics/health-check", {
@@ -1208,7 +1652,7 @@ function registerAnalyticsWriteTools(server, ctx) {
     title: "Switch the shop to Analytics V2 (starts data backfill)",
     description: 'WRITE \u2014 enables the new Analytics V2 for this shop and starts the historical data backfill in the background. Call this when joy_get_analytics_report returned the "shop is still on Analytics V1" error AND the merchant has EXPLICITLY agreed to switch \u2014 never call it unprompted: it changes the default Analytics experience in their Joy admin and runs a data migration that can take from a few minutes to a few tens of minutes. IDEMPOTENT and doubles as a STATUS CHECK: calling it again never restarts a running backfill \u2014 it returns progress (running/failed/already enabled) instead, so use it to answer "is the migration done yet?".',
     inputSchema: {
-      merchant_confirmed: z5.literal(true).describe("Must be true \u2014 pass it ONLY after the merchant explicitly agreed to switch to the new Analytics. If they have not been asked yet, ask first instead of calling this tool.")
+      merchant_confirmed: z6.literal(true).describe("Must be true \u2014 pass it ONLY after the merchant explicitly agreed to switch to the new Analytics. If they have not been asked yet, ask first instead of calling this tool.")
     },
     destructiveHint: false,
     idempotentHint: true,
@@ -1224,7 +1668,7 @@ function registerAnalyticsWriteTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/points.js
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 
 // ../mcp-core/build/tools/writeSupport.js
 import { randomUUID } from "node:crypto";
@@ -1290,9 +1734,9 @@ var MUTATION_RESULT_KEYS = [
 ];
 var writeArgsSchema = {
   ...memberIdentifierSchema,
-  reason: z6.string().min(3).describe("Why this change is being made \u2014 REQUIRED, recorded permanently in the audit trail."),
-  admin_note: z6.string().optional().describe("Optional internal note for the merchant team."),
-  idempotency_key: z6.string().max(255).optional().describe("Only pass this when RETRYING an uncertain outcome: reuse the exact key from the previous error message so the backend replays instead of applying twice. Omit for a new operation.")
+  reason: z7.string().min(3).describe("Why this change is being made \u2014 REQUIRED, recorded permanently in the audit trail."),
+  admin_note: z7.string().optional().describe("Optional internal note for the merchant team."),
+  idempotency_key: z7.string().max(255).optional().describe("Only pass this when RETRYING an uncertain outcome: reuse the exact key from the previous error message so the backend replays instead of applying twice. Omit for a new operation.")
 };
 async function executePointMutation(params) {
   const { ctx, path, member, point, reason, adminNote, idempotencyKey } = params;
@@ -1320,7 +1764,7 @@ function registerPointWriteTools(server, ctx) {
     description: "WRITE \u2014 gives points to ONE loyalty member (points are merchant money; the host will ask the user to approve). Identify the member by email or Shopify customer ID. reason is required and goes to the permanent audit trail. The operation is protected by an idempotency key, so a confirmed retry with the returned key can never double-award.",
     inputSchema: {
       ...writeArgsSchema,
-      points: z6.number().int().positive().describe("Points to add (positive integer).")
+      points: z7.number().int().positive().describe("Points to add (positive integer).")
     },
     destructiveHint: false,
     idempotentHint: false,
@@ -1345,8 +1789,8 @@ function registerPointWriteTools(server, ctx) {
     description: `WRITE, destructive \u2014 removes points from ONE member (points are merchant money; cannot be undone except by a compensating award). reason is required and audited. Deductions larger than ${ctx.config.deductDryRunThreshold} points return a DRY-RUN preview first \u2014 call again with apply: true to execute. Idempotency-protected.`,
     inputSchema: {
       ...writeArgsSchema,
-      points: z6.number().int().positive().describe("Points to remove (positive integer)."),
-      apply: z6.boolean().optional().describe(`Required (true) to EXECUTE a deduction above ${ctx.config.deductDryRunThreshold} points after reviewing the dry-run preview.`)
+      points: z7.number().int().positive().describe("Points to remove (positive integer)."),
+      apply: z7.boolean().optional().describe(`Required (true) to EXECUTE a deduction above ${ctx.config.deductDryRunThreshold} points after reviewing the dry-run preview.`)
     },
     destructiveHint: true,
     idempotentHint: false,
@@ -1387,8 +1831,8 @@ function registerPointWriteTools(server, ctx) {
     description: "WRITE, destructive \u2014 corrects a member's balance by a signed delta (points are merchant money). ALWAYS dry-runs first: the initial call returns a preview of current \u2192 resulting balance WITHOUT changing anything; call again with apply: true to execute. reason is required and audited. Idempotency-protected.",
     inputSchema: {
       ...writeArgsSchema,
-      points_delta: z6.number().int().refine((value) => value !== 0, { message: "points_delta must not be 0" }).describe("Signed change: positive adds, negative removes."),
-      apply: z6.boolean().optional().describe("Must be true to EXECUTE. Omit (or false) to get the dry-run preview.")
+      points_delta: z7.number().int().refine((value) => value !== 0, { message: "points_delta must not be 0" }).describe("Signed change: positive adds, negative removes."),
+      apply: z7.boolean().optional().describe("Must be true to EXECUTE. Omit (or false) to get the dry-run preview.")
     },
     destructiveHint: true,
     idempotentHint: false,
@@ -1423,8 +1867,8 @@ function registerPointWriteTools(server, ctx) {
     description: "WRITE, destructive \u2014 spends a member's points on a redemption program and returns the issued coupon code. Find the program_id via joy_list_redemption_rules first. Can take up to ~30s (a Shopify discount is minted inline). NO server-side retry protection yet: if the outcome is uncertain (timeout), verify via joy_get_member_activity BEFORE any retry \u2014 a blind retry can double-spend.",
     inputSchema: {
       ...memberIdentifierSchema,
-      program_id: z6.string().describe("Redemption program ID (from joy_list_redemption_rules)."),
-      redeem_points: z6.number().int().positive().describe("Points to spend on this redemption.")
+      program_id: z7.string().describe("Redemption program ID (from joy_list_redemption_rules)."),
+      redeem_points: z7.number().int().positive().describe("Points to spend for dynamic rewards only. Fixed rewards use the program's server-side cost.")
     },
     destructiveHint: true,
     idempotentHint: false,
@@ -1446,11 +1890,14 @@ function registerPointWriteTools(server, ctx) {
       }
       const discount = result?.discount ?? {};
       const customer = result?.customer ?? {};
+      const chargedPoints = typeof result.redeemPoint === "number" && Number.isFinite(result.redeemPoint) ? result.redeemPoint : typeof member.point === "number" && typeof customer.point === "number" && Number.isFinite(member.point) && Number.isFinite(customer.point) && member.point >= customer.point ? member.point - customer.point : void 0;
       if (!discount.code) {
         throw new JoyApiError("server", "The redeem response did not include a coupon code \u2014 treat this redemption as NOT completed. Common causes: insufficient points, program unavailable, or gift out of stock. Check the member balance and program via joy_find_member / joy_list_redemption_rules, and verify no redemption was recorded via joy_get_member_activity before trying again.");
       }
-      return summaryWithJson(`Redeemed ${formatPoints(args.redeem_points)} points from ${memberDisplayName(member)} for coupon "${String(discount.code)}" \u2014 balance now ${formatPoints(customer.point)}.`, {
+      const redemptionSummary = Number.isFinite(chargedPoints) ? `Redeemed ${formatPoints(chargedPoints)} points from ${memberDisplayName(member)}` : `Redeemed a server-priced reward for ${memberDisplayName(member)}`;
+      return summaryWithJson(`${redemptionSummary} for coupon "${String(discount.code)}" \u2014 balance now ${formatPoints(customer.point)}.`, {
         coupon: compact(discount, ["code", "title", "expiredAt"]),
+        charged_points: chargedPoints,
         member_balance: customer.point
       });
     }
@@ -1458,7 +1905,7 @@ function registerPointWriteTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/rewards.js
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 function registerRewardWriteTools(server, ctx) {
   registerWriteTool(server, ctx, {
     name: "joy_refund_coupon",
@@ -1466,8 +1913,8 @@ function registerRewardWriteTools(server, ctx) {
     description: 'WRITE \u2014 refunds, revokes, cancels, voids, or undoes a coupon a member redeemed with points (use this for ANY request to "revoke", "disable", "cancel", "void", or "undo" a point-redeemed coupon/discount code). IMPORTANT: this AUTOMATICALLY credits the spent points back to the member as part of the refund (a refund_point_redeem activity is recorded with your reason) \u2014 do NOT also call joy_award_points afterward, that would double-credit them. Only coupons that came from a POINT REDEMPTION can be refunded this way (not coupons from other sources, e.g. manual discounts). Identify the member by email or Shopify customer ID \u2014 do not ask the caller for a raw customer ID.',
     inputSchema: {
       ...memberIdentifierSchema,
-      coupon_code: z7.string().describe("The discount code to refund (from joy_get_member_rewards or joy_get_member_activity)."),
-      reason: z7.string().min(3).describe("Why this coupon is being refunded \u2014 REQUIRED, recorded in the audit trail.")
+      coupon_code: z8.string().describe("The discount code to refund (from joy_get_member_rewards or joy_get_member_activity)."),
+      reason: z8.string().min(3).describe("Why this coupon is being refunded \u2014 REQUIRED, recorded in the audit trail.")
     },
     destructiveHint: true,
     idempotentHint: false,
@@ -1493,7 +1940,7 @@ function registerRewardWriteTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/retention.js
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 var POINTS_EXPIRING_KEYS = [
   "customerId",
   "name",
@@ -1527,15 +1974,15 @@ function toRetentionRiskQuery(args) {
   return query;
 }
 function registerRetentionTools(server, ctx) {
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_get_retention_risk_members",
     title: "Find members at risk of losing points or dropping a VIP tier",
     description: 'READ-ONLY retention/outreach tool \u2014 "which members are about to lose points or drop a VIP tier, so I can proactively reach out?" Two independent signals via `signal`: "points_expiring" = members with points expiring within `window_days` (ONLY covers shops on earn-time/FIFO point expiration \u2014 shops using all-at-once expiration are not covered by this signal, so an empty result here does not mean no one is losing points); "tier_drop_risk" = members the REAL tier-demotion engine will demote soon \u2014 Joy demotes on INACTIVITY (no order since the tier program\'s configured demotion window), so a member is at risk when their last order is already past that cutoff (`daysUntilDemotion: 0` = demotable on the very next demotion run) or will pass it within `window_days` unless they order again; each row carries `demotion`: "down_one_tier" or "reset_to_lowest_tier" per the program\'s setting. A shop can also (or instead) run a SCHEDULED STORE-WIDE reset on a fixed calendar day \u2014 then the response carries `tier_scheduled_reset` (resetAt + daysUntilReset): EVERY member resets to the lowest tier on that date at once, so the correct answer is that DATE, not a per-member list. If the shop has tier demotion disabled, the response includes `tierDropRiskNote` saying the signal does not apply \u2014 report that note, never conclude "no one is at risk" from the empty list. Known limit: shops using assessment-based demotion (periodic spending re-evaluation) are not predicted by this signal. Optionally scope to one tier with `tier_id` (the lowest tier is never at risk \u2014 nothing to drop to). Default "both" returns both signals in one call. Results are HARD-CAPPED: window_days max 30, limit max 50 per signal (values above the cap are silently clamped, not rejected) \u2014 this is a shortlist for outreach, never the full at-risk population. Returns only the fields needed to act (name/email, expiring points/days, last-order date/days-until-demotion) plus has_more \u2014 never the member\'s full activity history.',
     inputSchema: {
-      signal: z8.enum(["points_expiring", "tier_drop_risk", "both"]).optional().describe('Which retention-risk signal to check. "points_expiring" for expiring-points questions, "tier_drop_risk" for tier-downgrade-risk questions, "both" (default) when the merchant asks broadly (e.g. "who is at risk of leaving?").'),
-      window_days: z8.number().int().min(1).max(30).optional().describe("Lookahead for BOTH signals (default 7, hard-capped at 30 \u2014 larger values are clamped, not rejected): points_expiring = points expiring within this many days; tier_drop_risk = members who are already demotable or become demotable within this many days."),
-      tier_id: z8.string().optional().describe("For tier_drop_risk: scope to one VIP tier ID (from joy_list_tiers). Omit to check every non-exclusive tier above the lowest \u2014 the result limit is split evenly across tiers."),
-      limit: z8.number().int().min(1).max(50).optional().describe("Max members per signal (default 20, hard-capped at 50).")
+      signal: z9.enum(["points_expiring", "tier_drop_risk", "both"]).optional().describe('Which retention-risk signal to check. "points_expiring" for expiring-points questions, "tier_drop_risk" for tier-downgrade-risk questions, "both" (default) when the merchant asks broadly (e.g. "who is at risk of leaving?").'),
+      window_days: z9.number().int().min(1).max(30).optional().describe("Lookahead for BOTH signals (default 7, hard-capped at 30 \u2014 larger values are clamped, not rejected): points_expiring = points expiring within this many days; tier_drop_risk = members who are already demotable or become demotable within this many days."),
+      tier_id: z9.string().optional().describe("For tier_drop_risk: scope to one VIP tier ID (from joy_list_tiers). Omit to check every non-exclusive tier above the lowest \u2014 the result limit is split evenly across tiers."),
+      limit: z9.number().int().min(1).max(50).optional().describe("Max members per signal (default 20, hard-capped at 50).")
     },
     handler: async (args) => {
       const { data } = await ctx.api.getData("/customers/retention-risk", {
@@ -1605,7 +2052,7 @@ function shapeSupportingData(supportingData) {
   return shaped;
 }
 function registerRiskTools(server, ctx) {
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_investigate_member_risk",
     title: "Investigate a member for referral/redemption abuse risk",
     description: `READ-ONLY fraud/abuse investigation for ONE member \u2014 "is this member doing anything suspicious?" Checks a FIXED, hard-coded set of flags (the same rules run every time, not a judgment call): referral_email_similarity (this member referred someone whose email closely matches their own \u2014 e.g. john+1@/john+2@ patterns); referral_device_match (this member's CURRENT last-known IP/device value matches their referrer's CURRENT last-known value); referee_had_prior_order (this member already had an order before being referred, so was not actually a new customer); high_daily_redemptions (redeemed more than a fixed threshold of rewards today). The response includes supporting data ONLY for flags that actually fired (e.g. the masked similar-email referrals, or today's redemption list) \u2014 if nothing is flagged, no supporting data is returned; this is NOT a full activity/history dump, so do not ask follow-up questions expecting more raw data from this same call. CRITICAL DATA LIMITS \u2014 do not claim more than this: there is NO IP/device HISTORY anywhere in Joy, only a single last-known value per customer that gets overwritten on every storefront visit \u2014 so referral_device_match is a live snapshot comparison, NOT a check of what the IP/device was at the actual moment the referral was claimed (that comparison happens live during the claim and is never stored). Do NOT say things like "this customer used N different IPs" or "here is their IP address" \u2014 that data does not exist and IPs are never returned, only a boolean match. Redemption velocity is checked at DAY granularity only \u2014 there is no minute/hour-level velocity check, so do not claim to detect rapid-fire redemption bursts within a single day. This tool never locks accounts, cancels rewards, or takes any action \u2014 it only surfaces flags for the merchant to review and decide next steps.`,
@@ -1634,7 +2081,7 @@ function registerRiskTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/orderExplain.js
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 var RULE_KEYS = ["programId", "title", "priority", "matched", "earnedPoints", "reasons"];
 function describeRule(rule) {
   const title = typeof rule.title === "string" ? rule.title : String(rule.programId ?? "rule");
@@ -1646,12 +2093,12 @@ function describeRule(rule) {
   return `${title}: did not match${reasons ? ` (${reasons})` : ""}`;
 }
 function registerOrderExplainTools(server, ctx) {
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_explain_order_points",
     title: "Explain why an order did or didn't earn points",
     description: "READ-ONLY explanation of the loyalty points earning rule engine for ONE order \u2014 \"why did/didn't this order earn points (or earn fewer than expected)?\" The response's `explainSource` field tells you which of two modes produced it: `recorded` means the answer comes from the decision-time trace the REAL earn pipeline stored on the order's activity when it was processed (historical ground truth \u2014 per-rule pass/fail with the exact condition fields that failed, recorded at `recordedAt`); `replay` means no stored trace exists (order processed before tracing shipped, or a legacy calculation path) and this is a RECONSTRUCTION run against the order's CURRENT Shopify snapshot, reusing the exact same gate and rule-matching functions the real earn pipeline uses \u2014 NOT a historical record. If the order was modified after points were originally calculated (e.g. a partial refund applied after the initial award), this tool reports against the order's current state, which may not match what was actually awarded at the time \u2014 do not present this as infallible ground truth for what happened historically; treat it as \"what the rules say NOW\". Evaluation order: (1) pre-rule-engine gates \u2014 no customer matched on the order, guest checkout not opted in, customer left the loyalty program, order not paid/fulfilled per the shop's setting, order fully refunded, or an update arriving after the order was already closed; if any gate blocks, `blockedByGate` explains which one and no rules were evaluated. (2) If gates pass, every active place-order earning rule is evaluated in priority order (`rules`), each with `matched` true/false/null and human-readable `reasons` \u2014 `matched: null` means the rule was NEVER evaluated because a higher-priority rule matched first with \"stop processing\" enabled (distinct from `false`, which means it WAS evaluated and did not match). (3) `maxTheoreticalPoints` is the total before the global per-customer/tier earning cap; `totalEarnedPoints` is after; `cappedBy` is set only when that cap actually reduced the total. Scope: covers the place_order (checkout) earning event only \u2014 birthday, sign-up, and milestone rewards are NOT covered by this tool.",
     inputSchema: {
-      order_id: z9.string().describe('The order to explain \u2014 either the internal Shopify order ID (numeric) or the order name as shown to the merchant, e.g. "#1234".')
+      order_id: z10.string().describe('The order to explain \u2014 either the internal Shopify order ID (numeric) or the order name as shown to the merchant, e.g. "#1234".')
     },
     handler: async (args) => {
       const { data } = await ctx.api.getData(`/orders/${encodeURIComponent(args.order_id)}/points-explanation`);
@@ -1691,7 +2138,7 @@ function registerOrderExplainTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/activityAudit.js
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 var AUDIT_GROUPS = [
   "tier_downgraded",
   "tier_upgraded",
@@ -1733,16 +2180,16 @@ function toActivityAuditQuery(args) {
   return query;
 }
 function registerActivityAuditTools(server, ctx) {
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_list_activities",
     title: "List loyalty activities across members (audit by activity group)",
     description: 'READ-ONLY shop-wide activity audit \u2014 "WHICH members did X in this period", the cross-member counterpart of joy_get_member_activity (one member\'s history) and of joy_get_analytics_report report_type=tier_transitions (aggregate COUNTS only, no names). Use this when the merchant asks WHO, use analytics when they ask HOW MANY. One semantic `group` per call, each spanning every raw activity type that feature area produces: "tier_downgraded" covers ALL THREE demotion mechanisms (reassessment demote_tier, inactivity downgrade_tier, relaunch reset_tier \u2014 never query one of these alone or you will miss mechanisms); "tier_upgraded" = tier upgrades; "points_earned" = program point earns (rows include orderName when the earn came from an order); "points_redeemed" = redemptions web + POS (each row carries programId/programTitle \u2014 combine with `program_id` for "who redeemed program A?"); "points_refunded" / "points_expired" / "points_adjusted" = the corresponding point movements; "referral" = referral outcomes (referred members, referred orders, referral rewards + revocations \u2014 rows carry referralCustomerEmail linking referrer and referee); "members_joined" = joins/rejoins. Time range: from_date/to_date (defaults to the last 30 days, range hard-capped at 366 days \u2014 an over-wide range is clamped to the most recent 366 days, not rejected). Results are a HARD-CAPPED shortlist: limit max 50 (default 20), newest first, plus has_more \u2014 never the full population; treat has_more:true as "narrow the range or filter, do not page exhaustively".',
     inputSchema: {
-      group: z10.enum(AUDIT_GROUPS).describe('Which activity group to audit. Pick by merchant intent: "who dropped a tier" \u2192 tier_downgraded; "who redeemed (program A)" \u2192 points_redeemed (+ program_id); "who earned points from orders" \u2192 points_earned; "who referred people" \u2192 referral.'),
-      program_id: z10.string().optional().describe("Scope to one program (from joy_list_earning_rules / joy_list_redemption_rules), e.g. redemptions of one specific reward. Applied as a post-filter \u2014 a sparse program in a busy shop may fill fewer rows than `limit`."),
-      from_date: z10.string().optional().describe("Start of the period, ISO date (e.g. 2026-07-01). Default: 30 days before to_date."),
-      to_date: z10.string().optional().describe("End of the period, ISO date. Default: now."),
-      limit: z10.number().int().min(1).max(50).optional().describe("Max rows (default 20, hard-capped at 50).")
+      group: z11.enum(AUDIT_GROUPS).describe('Which activity group to audit. Pick by merchant intent: "who dropped a tier" \u2192 tier_downgraded; "who redeemed (program A)" \u2192 points_redeemed (+ program_id); "who earned points from orders" \u2192 points_earned; "who referred people" \u2192 referral.'),
+      program_id: z11.string().optional().describe("Scope to one program (from joy_list_earning_rules / joy_list_redemption_rules), e.g. redemptions of one specific reward. Applied as a post-filter \u2014 a sparse program in a busy shop may fill fewer rows than `limit`."),
+      from_date: z11.string().optional().describe("Start of the period, ISO date (e.g. 2026-07-01). Default: 30 days before to_date."),
+      to_date: z11.string().optional().describe("End of the period, ISO date. Default: now."),
+      limit: z11.number().int().min(1).max(50).optional().describe("Max rows (default 20, hard-capped at 50).")
     },
     handler: async (args) => {
       const { data } = await ctx.api.getData("/activities/audit", {
@@ -1765,7 +2212,7 @@ function registerActivityAuditTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/tierUpgrade.js
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 var UPGRADE_ITEM_KEYS = [
   "customerId",
   "name",
@@ -1790,14 +2237,14 @@ function toTierUpgradeQuery(args) {
   return query;
 }
 function registerTierUpgradeTools(server, ctx) {
-  registerReadTool(server, {
+  registerReadTool(server, ctx, {
     name: "joy_get_tier_upgrade_candidates",
     title: "Find members close to reaching the next VIP tier",
     description: 'READ-ONLY growth/upsell outreach tool \u2014 "which members are ABOUT TO reach the next VIP tier, so I can nudge them over the line?" (e.g. "kh\xE1ch n\xE0o s\u1EAFp l\xEAn Gold?"). The mirror of joy_get_retention_risk_members\' tier_drop_risk signal: that one finds members about to FALL, this one finds members about to CLIMB. Upgrades in Joy apply immediately when tierPoint reaches the next tier\'s threshold, so distance-to-threshold is the exact signal \u2014 each row reports the member\'s current tier, tierPoint, the next tier and its threshold, and `pointsToNextTier` (how little they still need). Sorted closest-first. `margin_points` defines "close" (default: 10% of the next tier\'s own threshold, so it scales with the shop); note tierPoint is measured in the tier program\'s entry metric \u2014 points, money spent, or order count depending on the program setup \u2014 so quote distances in that unit, not always "points". Optionally scope to one CURRENT tier with `tier_id` (from joy_list_tiers); the highest tier is never a candidate (nothing to climb to), exclusive/VIP-deal tiers are excluded on both ends. Results are a HARD-CAPPED shortlist (limit max 50, default 20, split evenly across tiers when unscoped) plus has_more \u2014 never the full population. For ONE member\'s own distance to the next tier, prefer joy_find_member (field pointsRemain) instead.',
     inputSchema: {
-      tier_id: z11.string().optional().describe("Scope to members currently in this VIP tier ID (from joy_list_tiers). Omit to check every climbable tier \u2014 the result limit is split evenly across tiers."),
-      margin_points: z11.number().min(1).optional().describe(`How close (in the tier program's entry metric) counts as "near the next tier". Default: 10% of the next tier's threshold. Use an explicit value when the merchant names one ("within 100 points of Gold").`),
-      limit: z11.number().int().min(1).max(50).optional().describe("Max members returned (default 20, hard-capped at 50).")
+      tier_id: z12.string().optional().describe("Scope to members currently in this VIP tier ID (from joy_list_tiers). Omit to check every climbable tier \u2014 the result limit is split evenly across tiers."),
+      margin_points: z12.number().min(1).optional().describe(`How close (in the tier program's entry metric) counts as "near the next tier". Default: 10% of the next tier's threshold. Use an explicit value when the merchant names one ("within 100 points of Gold").`),
+      limit: z12.number().int().min(1).max(50).optional().describe("Max members returned (default 20, hard-capped at 50).")
     },
     handler: async (args) => {
       const { data } = await ctx.api.getData("/customers/tier-upgrade-candidates", {
@@ -1816,103 +2263,3032 @@ function registerTierUpgradeTools(server, ctx) {
   });
 }
 
-// ../mcp-core/build/prompts.js
-import { z as z12 } from "zod";
-function registerAllPrompts(server) {
-  server.registerPrompt("support_missing_points", {
-    title: "Investigate missing points for an order",
-    description: "Support workflow: verify whether a customer really is missing points for an order, explain why, and prepare a compensation proposal with a proper audit reason.",
-    argsSchema: {
-      email: z12.string().describe("Customer's email address"),
-      order_number: z12.string().optional().describe("Order name/number the customer says earned nothing, e.g. #1234")
+// ../mcp-core/build/tools/loyaltyPage.js
+import { z as z13 } from "zod";
+function summarizeDesign(data) {
+  const sections = data.design?.sections ?? [];
+  const on = sections.filter((section) => section.enabled !== false).map((section) => section.id);
+  const legacyWarning = data.renderPath === "legacy-blocks" ? `\u26A0 The storefront loyalty page renders through legacy blocks, so Loyalty Page V2 design changes will not appear there. The merchant must open ${data.v2BlockAddUrl || "the Loyalty Page V2 block link from joy_check_theme_setup"}, add the Loyalty Page V2 block, and save the theme. ` : "";
+  let live = "The shop still serves the older Loyalty Page V1, so changes here are not visible to customers yet.";
+  if (data.pageVersionActive && (data.renderPath === "v2-block" || data.renderPath === void 0)) {
+    live = "This page IS the shop\u2019s live loyalty page \u2014 changes are visible to customers.";
+  }
+  if (data.pageVersionActive && data.renderPath === "legacy-blocks") {
+    live = "Loyalty Page V2 is active for this shop.";
+  }
+  if (data.pageVersionActive && data.renderPath === "none") {
+    live = "Loyalty Page V2 is active for this shop, but no loyalty page block was detected in the live theme, so changes are not visible to customers.";
+  }
+  const css = data.canEditCustomCss ? "" : " Custom CSS is not available on this shop\u2019s plan.";
+  return `${legacyWarning}Loyalty Page V2 design. Sections on: ${on.join(", ") || "none"}. ${live}${css}`;
+}
+function summarizeAppliedChanges(applied2, published, warnings2 = []) {
+  const headline = applied2.slice(0, 5).map((change) => `${change.field}: ${String(change.from ?? "\u2014")} \u2192 ${String(change.to)}`).join("; ");
+  const more = applied2.length > 5 ? ` (+${applied2.length - 5} more)` : "";
+  const where = published ? "Published: live on the storefront now." : "Saved to the draft \u2014 visible in the merchant\u2019s editor now, and to customers once they publish.";
+  const caveat = warnings2.length ? `\u26A0 ${warnings2.join(" \u26A0 ")} ` : "";
+  return `${caveat}${applied2.length} design field${applied2.length === 1 ? "" : "s"} changed \u2014 ${headline}${more}. ${where} Undo with joy_revert_loyalty_page_design.`;
+}
+function registerLoyaltyPageTools(server, ctx) {
+  registerReadTool(server, ctx, {
+    name: "joy_get_loyalty_page_design",
+    title: "Get loyalty page design",
+    description: "Read the shop's Loyalty Page V2 appearance \u2014 page theme (colours, fonts, radii, widths), which sections are switched on, and each section's layout and card styling. It also audits whether the live theme renders this design through the V2 block, legacy blocks, or no loyalty page block; when legacy blocks are present, the result leads with the server-provided theme-editor link the merchant must use to add and save the V2 block. This read-only tool cannot add or enable a theme block itself. Also returns `writableFields`: the exact field names joy_update_loyalty_page_design accepts, per section. CALL THIS BEFORE any design change \u2014 the field vocabulary is large and specific, and guessing a name costs a failed call. This is appearance only: page text (headings, FAQ questions, program descriptions) is NOT here and cannot be changed through these tools.",
+    inputSchema: {},
+    handler: async () => {
+      const { data } = await ctx.api.getData("/loyalty-page/design");
+      return summaryWithJson(summarizeDesign(data), data);
     }
-  }, ({ email, order_number }) => ({
-    messages: [
-      {
-        role: "user",
-        content: {
-          type: "text",
-          text: [
-            `A customer (${email}) reports they did not receive loyalty points${order_number ? ` for order ${order_number}` : ""}. Investigate before changing anything:`,
-            "",
-            "1. Look up the member with joy_find_member \u2014 flag anything unusual (disabled state, guest, recently created).",
-            `2. Check joy_get_member_activity for an earn entry matching the order${order_number ? "" : " they describe (ask me for the order number if you cannot identify it)"}.`,
-            order_number ? `3. Run joy_explain_order_points for ${order_number} \u2014 it re-runs the actual earning engine and reports which gate or rule condition blocked earning, if any.` : "3. Once the order is identified, run joy_explain_order_points on it \u2014 it re-runs the actual earning engine and reports which gate or rule condition blocked earning, if any.",
-            "4. Conclude with exactly one of: (a) points were already awarded (show the activity entry), (b) points were correctly not awarded (show the blocking gate/rule \u2014 cite its configured threshold or condition, do not paraphrase from memory), or (c) points are genuinely missing.",
-            "5. Only for case (c): state the exact number of points owed and propose a joy_award_points call with a reason that names the order and the root cause. Wait for my explicit confirmation before executing \u2014 never award in the same turn as the diagnosis.",
-            "",
-            "Caveat to include when you rely on joy_explain_order_points: it recomputes against the order as it exists now \u2014 if the order changed after the original webhook (e.g. partial refund), the explanation reflects the current state, not the historical moment."
-          ].join("\n")
-        }
+  });
+}
+function registerLoyaltyPageWriteTools(server, ctx) {
+  registerWriteTool(server, ctx, {
+    name: "joy_update_loyalty_page_design",
+    title: "Update loyalty page design",
+    // Not idempotent in the annotation sense: repeating the call is harmless for
+    // the page, but each call overwrites the single undo snapshot, so a second
+    // identical call is not a no-op for what revert would restore.
+    destructiveHint: false,
+    idempotentHint: false,
+    description: "Change the appearance of the shop's Loyalty Page V2, including its media and program or tier artwork. Send ONLY the fields you are changing \u2014 anything you omit keeps its current value. WARNING: the `icons` branch has no draft \u2014 program and tier artwork is live data, so those changes reach shoppers immediately even when publish is false, and they also appear anywhere else that reads the program or tier. Tier artwork is dual-written to `imageBlock` for the loyalty page and `icon` for the tier-achieved email, membership card Widget V4, and account block: changing a tier icon changes those email and widget surfaces too, not just this page. For image artwork, first call joy_upload_image, then pass its returned URL to `hero.backgroundImage`, `hero.mobileBackgroundImage`, `inlineBanner.backgroundImage`, `inlineBanner.mobileBackgroundImage`, `earn.bannerImage`, `referral.image`, or `icons`; the other media fields are `hero.backgroundVideo` and `hero.mobileBackgroundVideo`. Image URLs must use http: or https: and contain no username or password; video URLs must use https: and end in .mp4. For a storefront-based starting point, send `applyScan` inside `design` in this tool \u2014 there is no separate apply-scan tool. Call joy_get_loyalty_page_design first and use the field names from its `writableFields`; a name outside that list is refused with the offending path rather than silently ignored. Saves to the DRAFT: the merchant sees it in their loyalty page editor immediately, and customers see it when they publish. Iterate freely here \u2014 refining a design costs nothing. Only pass publish=true when the merchant has asked for the change to go live, because publishing writes a Shopify metafield and re-syncs the FAQ projection every time. Undo with joy_revert_loyalty_page_design. Appearance only \u2014 this cannot change any text on the page.",
+    inputSchema: {
+      design: z13.record(z13.unknown()).describe('The fields to change, shaped like the `design` object from joy_get_loyalty_page_design. Branches: `theme` (page-wide tokens), `sections` (array of {id, enabled?, settings:{theme}}), `content` (per-section layout/style, keyed by section id), `advanced` ({customCss}), `icons` ({earning?:{...}, spending?:{...}, tiers?:{...}|[...]}, valued with an image URL or a built-in icon name), and `applyScan` ({url?: string, storefrontPassword?: string, colors?: boolean, images?: boolean}). Address earning/spending artwork by program id OR event; address tier artwork by tier id OR tier name (`name`/`title`), or pass an array in tier order. A tier artwork write updates both `imageBlock` (loyalty page) and `icon` (tier-achieved email, membership card Widget V4, and account block), so it changes email and widget surfaces too. Read current program artwork from joy_list_earning_rules / joy_list_redemption_rules. For `applyScan`, url defaults to this shop\'s storefront, storefrontPassword is only for a gated store, colors defaults to true, and images defaults to false so a scan does not unexpectedly replace artwork. If the scan returns 409 PASSWORD_REQUIRED, ask the merchant for the storefront password and pass it as `storefrontPassword`; never guess it. If it fails with 503, do not invent colours, fonts, or button styling; ask the merchant to retry later or configure the draft manually. Scan output is design input, not visual evidence of how the page looks after the change. NOTE on precedence: a value under `sections[].settings.theme` BEATS the same key in `theme`, so recolouring a page whose sections carry overrides means patching both. Example: {"theme":{"primary":"#0F4C3A"},"content":{"earn":{"columns":2}},"icons":{"earning":{"birthday":"https://cdn.../cake.png"}}}'),
+      publish: z13.boolean().optional().describe("Default false \u2014 the change lands on the draft, which the merchant sees in the loyalty page editor and nobody else. Pass true only when they asked for it to go live; each publish costs a Shopify metafield write, so do not send it on every tweak.")
+    },
+    handler: async (args) => {
+      const result = await ctx.api.mutateData("/loyalty-page/design", {
+        method: "PATCH",
+        timeoutMs: 2e4,
+        body: { design: args.design, ...args.publish === void 0 ? {} : { publish: args.publish } }
+      });
+      const applied2 = result?.applied ?? [];
+      if (!applied2.length) {
+        return "No change \u2014 every field you sent already had that value.";
       }
-    ]
-  }));
-  server.registerPrompt("program_review", {
-    title: "Loyalty program review (health + revenue + tiers + referral)",
-    description: "Periodic business review: program health check, revenue impact, tier performance, and referral results \u2014 with data-source rules so numbers from different systems are never mixed.",
-    argsSchema: {
-      period: z12.string().optional().describe("Reporting period, e.g. 'last 30 days', 'last month', 'this quarter'. Defaults to last 30 days.")
+      const published = result?.published ?? false;
+      const warnings2 = result?.warnings ?? [];
+      return summaryWithJson(summarizeAppliedChanges(applied2, published, warnings2), {
+        applied: applied2,
+        published,
+        ...warnings2.length ? { warnings: warnings2 } : {}
+      });
     }
-  }, ({ period }) => ({
-    messages: [
-      {
-        role: "user",
-        content: {
-          type: "text",
-          text: [
-            `Review my loyalty program for ${period ?? "the last 30 days"}. Run, in parallel where possible:`,
-            "",
-            "1. joy_get_loyalty_health_check \u2014 overall score and flags.",
-            "2. joy_get_loyalty_revenue_report \u2014 revenue impact (Shopify sales data).",
-            "3. joy_get_tier_performance_breakdown \u2014 which VIP tier earns its keep.",
-            "4. joy_get_analytics_report with report_type referral_summary, and points_movement for the same period.",
-            "",
-            "Data-source rules (important):",
-            "- joy_get_loyalty_revenue_report and joy_get_tier_performance_breakdown read Shopify sales data (ShopifyQL); joy_get_analytics_report reads the Joy event log (BigQuery). These measure differently \u2014 label the source of every figure and never combine numbers across the two sources into one derived metric.",
-            "- If a ShopifyQL tool returns a 403 about the read_reports scope, relay its grant instructions instead of substituting numbers from the other source.",
-            "- If any response carries a backfill WARNING, repeat that caveat next to the affected numbers \u2014 do not present them as final.",
-            "",
-            "Format: a 3-sentence executive summary first, then anomalies worth my attention (with the flag or figure that triggered each), then exactly one concrete recommended action. Skip metrics that are unremarkable."
-          ].join("\n")
-        }
-      }
-    ]
-  }));
-  server.registerPrompt("investigate_member", {
-    title: "Investigate a member for abuse risk",
-    description: "Fraud/abuse triage for one member: risk flags, point activity, and referral history \u2014 with the mandatory caveat about signal limitations and no punitive action.",
-    argsSchema: {
-      email: z12.string().describe("Email of the member to investigate")
+  });
+  registerWriteTool(server, ctx, {
+    name: "joy_revert_loyalty_page_design",
+    title: "Revert the last loyalty page design change",
+    // It removes work the merchant may have wanted, and calling it twice
+    // restores the same snapshot rather than stepping further back.
+    destructiveHint: true,
+    idempotentHint: true,
+    description: "Undo the last design change made through joy_update_loyalty_page_design, restoring the page exactly as it was before that call \u2014 including any program or tier artwork it changed, which goes back LIVE immediately because artwork has no draft \u2014 and republish. ONE step only \u2014 it is not a history, and a second call restores the same snapshot again rather than going further back. WARNING: it restores a whole saved design, so any edit the merchant made in the admin editor AFTER that update is discarded too \u2014 if they may have been editing, ask before calling this. Use it promptly when a change is judged wrong; the next update overwrites the snapshot.",
+    inputSchema: {
+      publish: z13.boolean().optional().describe("Default false \u2014 the restored design lands on the draft. Pass true to put it back on the storefront immediately.")
+    },
+    handler: async (args) => {
+      const result = await ctx.api.mutateData("/loyalty-page/design/revert", {
+        method: "POST",
+        timeoutMs: 2e4,
+        body: args.publish === void 0 ? {} : { publish: args.publish }
+      });
+      const programIcons = result?.programIconsRestored ?? 0;
+      const tierIcons = result?.tierIconsRestored ?? 0;
+      const icons = programIcons || tierIcons ? ` ${[
+        programIcons ? `${programIcons} program icon${programIcons === 1 ? "" : "s"}` : "",
+        tierIcons ? `${tierIcons} tier icon${tierIcons === 1 ? "" : "s"}` : ""
+      ].filter(Boolean).join(" and ")} were put back too, and artwork has no draft \u2014 those are LIVE now.` : "";
+      return summaryWithJson(`Reverted to the design from before the last update. ${result?.published ? "Live on the storefront again." : "The page is restored on the draft \u2014 publish to put it back for customers."}${icons}`, { design: result?.design, programIconsRestored: programIcons, tierIconsRestored: tierIcons });
     }
-  }, ({ email }) => ({
-    messages: [
-      {
-        role: "user",
-        content: {
-          type: "text",
-          text: [
-            `I suspect member ${email} may be abusing the loyalty program (referral self-dealing, unusual redemptions, or similar). Investigate:`,
-            "",
-            "1. joy_find_member \u2014 profile basics and state.",
-            "2. joy_investigate_member_risk \u2014 the pre-defined abuse flags. For every flag that fires, show the concrete supporting data the tool returns; do not add suspicions of your own beyond the flags.",
-            "3. joy_get_member_activity and joy_get_member_referrals \u2014 recent point movements and referral results, to give the flags context.",
-            "",
-            "Mandatory caveat in your answer: device/IP matching compares the MOST RECENT values only \u2014 there is no full history over time \u2014 so these flags are advisory signals to support my judgement, not proof of abuse.",
-            "",
-            "End with: which flags fired (if any), what specific records I should open in the Joy admin to verify each one, and your read on severity. Do NOT deduct points, refund coupons, or take any corrective action \u2014 this session is investigation only; I will decide separately."
-          ].join("\n")
-        }
-      }
-    ]
-  }));
+  });
 }
 
-// ../mcp-core/build/registry.js
-function registerAllTools(server, ctx) {
-  registerOverviewTools(server, ctx);
-  registerAnalyticsTools(server, ctx);
-  registerMemberTools(server, ctx);
-  registerTierTools(server, ctx);
+// ../mcp-core/build/tools/loyaltyPageText.js
+import { z as z14 } from "zod";
+var localeSchema = z14.string().min(2).optional().describe("Active locale code. Omit to use the shop's primary language.");
+function registerLoyaltyPageTextTools(server, ctx) {
+  registerReadTool(server, ctx, {
+    name: "joy_get_loyalty_page_text",
+    title: "Get loyalty page text",
+    description: "Loyalty Page V2 text has no draft: text edits are LIVE on the storefront immediately. Read the current text for one active locale, the placeholders each value must preserve, and the stable ids/keys for steps and tier benefits. CALL THIS BEFORE joy_update_loyalty_page_text; never guess keys or item positions. Editing the primary language automatically retranslates only those changed keys into every other active locale. `points.singular` and `points.plural` are shown for context but are read-only through this tool surface.",
+    inputSchema: { locale: localeSchema },
+    handler: async (args) => {
+      const { data } = await ctx.api.getData("/loyalty-page/text", {
+        query: { locale: args.locale }
+      });
+      return summaryWithJson(`${Object.keys(data.values).length} live Loyalty Page V2 text values for ${data.locale}. Primary language: ${data.primaryLanguage}; active locales: ${data.activeLocales.join(", ")}.`, data);
+    }
+  });
+}
+function registerLoyaltyPageTextWriteTools(server, ctx) {
+  registerWriteTool(server, ctx, {
+    name: "joy_update_loyalty_page_text",
+    title: "Update loyalty page text",
+    destructiveHint: true,
+    idempotentHint: false,
+    description: "Loyalty Page V2 text has no draft: every accepted change is LIVE on the storefront immediately. Update only exact keys returned by joy_get_loyalty_page_text; unknown or duplicate keys are skipped. Preserve every returned placeholder unless the merchant explicitly authored the replacement, in which case pass manual: true. Editing the primary language automatically retranslates the changed keys into every other active locale in the same operation; editing a secondary locale changes only that locale. This can replace merchant-authored translations for those same keys. Undo the latest text or design update with joy_revert_loyalty_page_design.",
+    inputSchema: {
+      locale: localeSchema,
+      changes: z14.array(z14.object({
+        key: z14.string().min(1),
+        value: z14.string(),
+        manual: z14.boolean().optional().describe("Set true only when the merchant authored this exact replacement.")
+      })).min(1).describe("Exact key/value edits from joy_get_loyalty_page_text.")
+    },
+    handler: async (args) => {
+      const result = await ctx.api.mutateData("/loyalty-page/text", {
+        method: "PATCH",
+        timeoutMs: 12e4,
+        body: { changes: args.changes, ...args.locale ? { locale: args.locale } : {} }
+      });
+      const propagation = result.translatedLocales.length ? ` Retranslated in ${result.translatedLocales.join(", ")}.` : "";
+      const skipped = result.skipped.length ? ` ${result.skipped.length} change(s) skipped.` : "";
+      return summaryWithJson(`\u26A0 Loyalty Page V2 text has no draft \u2014 ${result.applied.length} text change(s) are LIVE now.${propagation}${skipped} Undo with joy_revert_loyalty_page_design.`, result);
+    }
+  });
+}
+
+// ../mcp-core/build/tools/programsWrite.js
+import { z as z15 } from "zod";
+var PROGRAM_TYPE_BY_KIND = {
+  earning: "earning",
+  redemption: "spending"
+};
+var SIMPLE_SOCIAL_EVENTS = /* @__PURE__ */ new Set([
+  "like_facebook",
+  "follow_instagram",
+  "follow_twitter",
+  "follow_pinterest",
+  "follow_tiktok",
+  "subscribe_youtube",
+  "join_discord",
+  "join_telegram",
+  "join_reddit"
+]);
+var REVIEW_APPS = [
+  "airReviewApp",
+  "judgeMeApp",
+  "yotpoApp",
+  "feraApp",
+  "reviewRocketApp",
+  "klaviyoApp",
+  "stampedApp",
+  "looxApp",
+  "okendoApp",
+  "ReviewsIoApp",
+  "growaveApp",
+  "typdalApp"
+];
+var REVIEW_FLOW_APPS = /* @__PURE__ */ new Set([
+  "stampedApp",
+  "looxApp",
+  "okendoApp",
+  "ReviewsIoApp",
+  "growaveApp",
+  "typdalApp"
+]);
+var REVIEW_PHOTO_VIDEO_APPS = /* @__PURE__ */ new Set(["reviewRocketApp", "looxApp"]);
+var EARNING_CREATE_EVENTS = /* @__PURE__ */ new Set([
+  "place_order",
+  "sign_up",
+  "birthday",
+  "interact_website",
+  "write_review",
+  ...SIMPLE_SOCIAL_EVENTS
+]);
+var REDEMPTION_CREATE_EVENTS = /* @__PURE__ */ new Set([
+  "amount_discount",
+  "percentage_discount",
+  "free_shipping",
+  "free_gift"
+]);
+var FREE_GIFT_PROGRAM_APPLIED_TO = ["sf_product", "specific", "exclude_collection"];
+var EARNING_FIELDS = [
+  "event",
+  "title",
+  "status",
+  "priority",
+  "startDate",
+  "endDate",
+  "earnBy",
+  "rateMoney",
+  "rateItem",
+  "earnPoint",
+  "typeEarn",
+  "isUseLayoutMultiRewards",
+  "dateFormat",
+  "typeRewardTiming",
+  "limitUnit",
+  "limitInterval",
+  "urlAccount",
+  "reviewApp",
+  "descriptionReview",
+  "extraPoints",
+  "extraPointsForImages",
+  "extraPointsForVideos",
+  "isAppliedVipTier",
+  "earnPointsTiers",
+  "appliedPlaceOrderTo",
+  "skipEarnPointGuest"
+];
+var REDEMPTION_FIELDS = [
+  "event",
+  "title",
+  "status",
+  "priority",
+  "startDate",
+  "endDate",
+  "spendPoint",
+  "earnAmount",
+  "redeemType",
+  "shippingDiscountType",
+  "shippingDiscountAmount",
+  "appliedTo",
+  "specificProducts",
+  "specificCollections",
+  "appliedCollectionIds",
+  "collectionQuantity"
+];
+function withoutUnsetFields(body) {
+  return Object.fromEntries(Object.entries(body).filter(([, value]) => value !== void 0));
+}
+function missingFields(event, fields) {
+  return { ok: false, error: `Creating ${event} requires: ${fields.join(", ")}.` };
+}
+function unsupportedCreate(event) {
+  return {
+    ok: false,
+    error: `Cannot create the ${event} program through this tool. Create it once in Joy admin, then call this tool with its program_id to tune points/status/priority/dates.`
+  };
+}
+function vipTierFlagError(args, current = {}) {
+  if (!args.earn_points_tiers)
+    return void 0;
+  if (Object.keys(args.earn_points_tiers).length === 0) {
+    return "earn_points_tiers is empty. Provide at least one tier, or omit it.";
+  }
+  const willBeApplied = args.is_applied_vip_tier ?? current.isAppliedVipTier === true;
+  if (!willBeApplied) {
+    return "earn_points_tiers was given but per-tier earning is off for this rule, so the backend would ignore the whole map and keep using the flat earn_point. Pass is_applied_vip_tier: true in the same call to actually apply it.";
+  }
+  return void 0;
+}
+function unknownTierIds(earnPointsTiers, knownTierIds) {
+  if (!earnPointsTiers)
+    return [];
+  const known = new Set(knownTierIds);
+  return Object.keys(earnPointsTiers).filter((tierId) => !known.has(tierId));
+}
+function baseEarningBody(args) {
+  return withoutUnsetFields({
+    event: args.event,
+    title: args.title,
+    status: args.status,
+    priority: args.priority,
+    startDate: args.start_date,
+    endDate: args.end_date,
+    earnBy: args.earn_by,
+    rateMoney: args.rate_money,
+    rateItem: args.rate_item,
+    earnPoint: args.earn_point,
+    dateFormat: args.date_format,
+    typeRewardTiming: args.type_reward_timing,
+    limitUnit: args.limit_unit,
+    limitInterval: args.limit_interval,
+    urlAccount: args.url_account,
+    reviewApp: args.review_app,
+    descriptionReview: args.description_review,
+    extraPointsForImages: args.extra_points_for_images,
+    extraPointsForVideos: args.extra_points_for_videos,
+    isAppliedVipTier: args.is_applied_vip_tier,
+    appliedPlaceOrderTo: args.applied_place_order_to,
+    earnPointsTiers: args.earn_points_tiers ? Object.fromEntries(Object.entries(args.earn_points_tiers).map(([tierId, rate]) => [
+      tierId,
+      withoutUnsetFields({
+        earnPoint: rate.earn_point,
+        rateMoney: rate.rate_money,
+        typeEarn: rate.type_earn
+      })
+    ])) : void 0
+  });
+}
+function baseRedemptionBody(args) {
+  return withoutUnsetFields({
+    event: args.event,
+    title: args.title,
+    status: args.status,
+    priority: args.priority,
+    startDate: args.start_date,
+    endDate: args.end_date,
+    spendPoint: args.spend_point,
+    earnAmount: args.earn_amount,
+    shippingDiscountType: args.shipping_discount_type,
+    shippingDiscountAmount: args.shipping_discount_amount,
+    appliedTo: args.applied_to,
+    specificProducts: args.specific_products,
+    specificCollections: args.specific_collections,
+    appliedCollectionIds: args.applied_collection_ids,
+    collectionQuantity: args.collection_quantity
+  });
+}
+function freeGiftProgramSelectionError(args) {
+  if (args.event !== "free_gift")
+    return void 0;
+  if (!args.applied_to) {
+    return "Creating free_gift requires applied_to. Ask the merchant which product or collection is the gift; product and collection IDs must come from the merchant and cannot be invented.";
+  }
+  if (!FREE_GIFT_PROGRAM_APPLIED_TO.includes(args.applied_to)) {
+    return `free_gift applied_to must be one of: ${FREE_GIFT_PROGRAM_APPLIED_TO.join(", ")}. Tier-reward values such as "all" and "specific_product" do not apply here.`;
+  }
+  if (args.applied_to === "sf_product" && !args.specific_products?.length) {
+    return 'Creating free_gift with applied_to "sf_product" requires specific_products. Ask the merchant for the product IDs; product IDs cannot be invented.';
+  }
+  if ((args.applied_to === "specific" || args.applied_to === "exclude_collection") && !args.applied_collection_ids?.length) {
+    return `Creating free_gift with applied_to "${args.applied_to}" requires applied_collection_ids. Ask the merchant for the collection IDs; product or collection IDs cannot be invented.`;
+  }
+  if ((args.applied_to === "specific" || args.applied_to === "exclude_collection") && (!Number.isInteger(args.collection_quantity) || (args.collection_quantity ?? 0) < 1)) {
+    return `Creating free_gift with applied_to "${args.applied_to}" requires collection_quantity as a positive integer.`;
+  }
+  return void 0;
+}
+function toEarningProgramChange(args) {
+  const fractionalError = fractionalTierRateError(args.earn_points_tiers);
+  if (fractionalError)
+    return { ok: false, error: fractionalError };
+  const body = baseEarningBody(args);
+  if (args.program_id) {
+    return { ok: true, action: "UPDATE", programId: args.program_id, body, dropped: droppedFields(body, EARNING_FIELDS) };
+  }
+  const vipFlagError = vipTierFlagError(args);
+  if (vipFlagError)
+    return { ok: false, error: vipFlagError };
+  if (!args.event)
+    return { ok: false, error: "event is required when creating an earning program." };
+  if (!EARNING_CREATE_EVENTS.has(args.event))
+    return unsupportedCreate(args.event);
+  if (!args.title)
+    return missingFields(args.event, ["title"]);
+  if (args.event === "place_order") {
+    const earnBy = args.earn_by ?? "price";
+    if (!["price", "fixed_order", "quantity", "order"].includes(earnBy)) {
+      return { ok: false, error: "place_order earn_by must be price, fixed_order, quantity, or order." };
+    }
+    if (args.earn_point === void 0)
+      return missingFields(args.event, ["earn_point"]);
+    if (["price", "fixed_order"].includes(earnBy) && args.rate_money === void 0) {
+      return missingFields(args.event, ["rate_money"]);
+    }
+    if (earnBy === "quantity" && args.rate_item === void 0) {
+      return missingFields(args.event, ["rate_item"]);
+    }
+    const createBody2 = {
+      ...body,
+      earnBy,
+      typeEarn: "point",
+      ...placeOrderVipTierPatch(args.event, args)
+    };
+    return {
+      ok: true,
+      action: "CREATE",
+      body: createBody2,
+      dropped: droppedFields(createBody2, EARNING_FIELDS)
+    };
+  }
+  if (args.event === "sign_up") {
+    if (args.earn_point === void 0)
+      return missingFields(args.event, ["earn_point"]);
+    const createBody2 = { ...body, typeEarn: "point" };
+    return { ok: true, action: "CREATE", body: createBody2, dropped: droppedFields(createBody2, EARNING_FIELDS) };
+  }
+  if (args.event === "birthday") {
+    if (args.earn_point === void 0)
+      return missingFields(args.event, ["earn_point"]);
+    if (!args.date_format)
+      return missingFields(args.event, ["date_format"]);
+    if (!["MM/DD", "DD/MM", "MM/DD/YYYY", "DD/MM/YYYY", "YYYY/MM/DD"].includes(args.date_format)) {
+      return { ok: false, error: "birthday date_format is invalid." };
+    }
+    if (!args.type_reward_timing)
+      return missingFields(args.event, ["type_reward_timing"]);
+    if (!["exact_birthday", "begin_of_month", "around_birthday"].includes(args.type_reward_timing)) {
+      return { ok: false, error: "birthday type_reward_timing is invalid." };
+    }
+    const createBody2 = { ...body, typeEarn: "point", isUseLayoutMultiRewards: false };
+    return { ok: true, action: "CREATE", body: createBody2, dropped: droppedFields(createBody2, EARNING_FIELDS) };
+  }
+  if (SIMPLE_SOCIAL_EVENTS.has(args.event)) {
+    if (args.earn_point === void 0)
+      return missingFields(args.event, ["earn_point"]);
+    if (!args.url_account) {
+      return {
+        ok: false,
+        error: `Creating ${args.event} requires url_account \u2014 the full URL of the shop's profile on that network (e.g. https://instagram.com/yourbrand). Ask the merchant for it; do not invent one.`
+      };
+    }
+    const createBody2 = { ...body, typeEarn: "point" };
+    return { ok: true, action: "CREATE", body: createBody2, dropped: droppedFields(createBody2, EARNING_FIELDS) };
+  }
+  if (args.event === "write_review") {
+    if (args.earn_point === void 0)
+      return missingFields(args.event, ["earn_point"]);
+    if (!args.review_app) {
+      return {
+        ok: false,
+        error: `Creating write_review requires review_app \u2014 which review app the shop runs. One of: ${REVIEW_APPS.join(", ")}. Ask the merchant which one is installed; the wrong value means reviews never award points.`
+      };
+    }
+    if (REVIEW_FLOW_APPS.has(args.review_app) && !args.description_review) {
+      return {
+        ok: false,
+        error: `review_app "${args.review_app}" awards points through Shopify Flow, so description_review is required.`
+      };
+    }
+    const wantsMediaBonus = args.extra_points_for_images !== void 0 || args.extra_points_for_videos !== void 0;
+    if (wantsMediaBonus && !REVIEW_PHOTO_VIDEO_APPS.has(args.review_app)) {
+      return {
+        ok: false,
+        error: `Photo/video review bonuses only work with reviewRocketApp or looxApp \u2014 "${args.review_app}" does not report them, so those points would never be awarded. Remove extra_points_for_images/extra_points_for_videos, or confirm the shop's review app.`
+      };
+    }
+    const createBody2 = { ...body, typeEarn: "point" };
+    return { ok: true, action: "CREATE", body: createBody2, dropped: droppedFields(createBody2, EARNING_FIELDS) };
+  }
+  if (args.earn_point === void 0)
+    return missingFields(args.event, ["earn_point"]);
+  const createBody = {
+    ...body,
+    limitUnit: args.limit_unit ?? "day",
+    limitInterval: args.limit_interval ?? 1
+  };
+  return { ok: true, action: "CREATE", body: createBody, dropped: droppedFields(createBody, EARNING_FIELDS) };
+}
+function toRedemptionProgramChange(args) {
+  const body = baseRedemptionBody(args);
+  if (args.program_id) {
+    return { ok: true, action: "UPDATE", programId: args.program_id, body, dropped: droppedFields(body, REDEMPTION_FIELDS) };
+  }
+  if (!args.event)
+    return { ok: false, error: "event is required when creating a redemption program." };
+  if (!REDEMPTION_CREATE_EVENTS.has(args.event))
+    return unsupportedCreate(args.event);
+  if (!args.title)
+    return missingFields(args.event, ["title"]);
+  if (!Number.isInteger(args.spend_point) || (args.spend_point ?? 0) <= 0) {
+    return missingFields(args.event, ["spend_point (a positive integer)"]);
+  }
+  if (args.event === "free_gift") {
+    const selectionError = freeGiftProgramSelectionError(args);
+    if (selectionError)
+      return { ok: false, error: selectionError };
+    return { ok: true, action: "CREATE", body, dropped: droppedFields(body, REDEMPTION_FIELDS) };
+  }
+  if (args.event === "amount_discount") {
+    if (args.earn_amount === void 0)
+      return missingFields(args.event, ["earn_amount"]);
+    const createBody = { ...body, redeemType: "fixed" };
+    return { ok: true, action: "CREATE", body: createBody, dropped: droppedFields(createBody, REDEMPTION_FIELDS) };
+  }
+  if (args.event === "percentage_discount") {
+    if (args.earn_amount === void 0)
+      return missingFields(args.event, ["earn_amount"]);
+    if (args.earn_amount >= 100) {
+      return { ok: false, error: "percentage_discount earn_amount must be less than 100." };
+    }
+    return { ok: true, action: "CREATE", body, dropped: droppedFields(body, REDEMPTION_FIELDS) };
+  }
+  if (!args.shipping_discount_type)
+    return missingFields(args.event, ["shipping_discount_type"]);
+  if (!["percentage", "fixedAmount"].includes(args.shipping_discount_type)) {
+    return { ok: false, error: "free_shipping shipping_discount_type must be percentage or fixedAmount." };
+  }
+  if (args.shipping_discount_amount === void 0)
+    return missingFields(args.event, ["shipping_discount_amount"]);
+  if (args.shipping_discount_type === "percentage" && args.shipping_discount_amount > 100) {
+    return { ok: false, error: "free_shipping shipping_discount_amount must be 100 or less for percentage." };
+  }
+  return { ok: true, action: "CREATE", body, dropped: droppedFields(body, REDEMPTION_FIELDS) };
+}
+function toProgramList(value) {
+  if (Array.isArray(value))
+    return value.filter(isProgramRecord);
+  if (!isProgramRecord(value))
+    return [];
+  if (Array.isArray(value.items))
+    return value.items.filter(isProgramRecord);
+  if (Array.isArray(value.programs))
+    return value.programs.filter(isProgramRecord);
+  return [];
+}
+function isProgramRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function unsupportedUpdateProgramType(kind, current) {
+  const actualType = typeof current.type === "string" && current.type ? current.type : "unknown";
+  const expectedType = PROGRAM_TYPE_BY_KIND[kind];
+  if (actualType === expectedType)
+    return void 0;
+  return `Refusing to update this ${kind} program: its actual type is "${actualType}", not "${expectedType}". Configure ${actualType === "unknown" ? "this program" : `the ${actualType} program`} ${actualType === "referral" ? "with joy_configure_referral_program" : "in Joy admin"} instead; this tool only supports ${kind} programs and must not partially update another program type.`;
+}
+function buildProgramChangePreview(params) {
+  const { kind, args, prepared, current = {}, existing = [] } = params;
+  const title = String(prepared.body.title ?? current.title ?? prepared.body.event ?? "unnamed");
+  const duplicate = prepared.action === "CREATE" ? findDuplicate(existing, { event: String(prepared.body.event ?? ""), title: args.title }) : void 0;
+  return buildChangePreview({
+    action: prepared.action,
+    target: `${kind} program "${title}"`,
+    reason: args.reason,
+    changes: diffFields(current, prepared.body),
+    dropped: prepared.dropped,
+    duplicate
+  });
+}
+function isProgramChangeNoop(current, prepared) {
+  return diffFields(current, prepared.body).length === 0;
+}
+var programConfigInputSchema = {
+  program_id: z15.string().min(1).optional().describe("Existing Joy program ID. Omit to create a new program."),
+  event: z15.string().optional().describe("Program event. Required for create; optional for update."),
+  title: z15.string().min(1).optional().describe("Customer-facing program title."),
+  status: z15.boolean().optional().describe("Set false to disable this rule instead of deleting it."),
+  priority: z15.number().int().optional().describe("Optional program priority."),
+  start_date: z15.string().optional().describe("Optional ISO start date."),
+  end_date: z15.string().optional().describe("Optional ISO end date."),
+  earn_by: z15.enum(["price", "fixed_order", "quantity", "order"]).optional(),
+  rate_money: z15.number().optional(),
+  rate_item: z15.number().optional(),
+  earn_point: z15.number().optional(),
+  date_format: z15.enum(["MM/DD", "DD/MM", "MM/DD/YYYY", "DD/MM/YYYY", "YYYY/MM/DD"]).optional(),
+  type_reward_timing: z15.enum(["exact_birthday", "begin_of_month", "around_birthday"]).optional(),
+  limit_unit: z15.string().optional(),
+  limit_interval: z15.number().int().positive().optional(),
+  url_account: z15.string().regex(/^https?:\/\//, "url_account must start with http:// or https://").optional().describe("REQUIRED when creating a social rule (follow_instagram, subscribe_youtube, like_facebook, follow_tiktok, follow_twitter, follow_pinterest, join_discord, join_telegram, join_reddit). The full URL of the shop's profile on that network \u2014 customers are sent here to complete the action."),
+  review_app: z15.enum(REVIEW_APPS).optional().describe("REQUIRED when creating a write_review rule: the review app the shop actually runs. Points cannot be awarded for reviews unless this matches the installed app."),
+  description_review: z15.string().optional().describe("Required only when review_app is a Shopify Flow app (stampedApp, looxApp, okendoApp, ReviewsIoApp, growaveApp, typdalApp) \u2014 the merchant-facing note describing how the Flow awards points."),
+  extra_points_for_images: z15.number().int().nonnegative().optional().describe("Bonus points for a review with a photo. Only reviewRocketApp and looxApp report photos; ignored for every other review app."),
+  extra_points_for_videos: z15.number().int().nonnegative().optional().describe("Bonus points for a review with a video. Only reviewRocketApp and looxApp report videos; ignored for every other review app."),
+  spend_point: z15.number().int().positive().optional(),
+  earn_amount: z15.number().optional(),
+  shipping_discount_type: z15.enum(["percentage", "fixedAmount"]).optional(),
+  shipping_discount_amount: z15.number().optional(),
+  applied_to: z15.enum(FREE_GIFT_PROGRAM_APPLIED_TO).optional().describe("free_gift only \u2014 sf_product, specific, or exclude_collection. This is a program-level enum and differs from tier rewards; it has no all value."),
+  specific_products: z15.array(z15.unknown()).optional().describe("free_gift with applied_to sf_product only \u2014 the merchant-provided product records/IDs. Do not invent product IDs."),
+  specific_collections: z15.array(z15.unknown()).optional(),
+  applied_collection_ids: z15.array(z15.string()).optional().describe("free_gift with applied_to specific or exclude_collection only \u2014 merchant-provided collection IDs."),
+  collection_quantity: z15.number().int().positive().optional().describe("Required for collection-based free_gift rules (applied_to specific or exclude_collection)."),
+  product_url: z15.array(z15.string()).optional().describe("free_gift with applied_to sf_product only \u2014 Shopify product URLs to resolve into product IDs. Accepts /products/<handle> or /collections/<collection>/products/<handle>; do not invent IDs."),
+  applied_place_order_to: z15.enum(["all", "vip-tier", "member_and_guest"]).optional().describe('place_order "Who to reward" radio: all = All loyalty members, vip-tier = VIP Tier only, member_and_guest = All customers. The admin UI and the earning engine both key off this field, not is_applied_vip_tier. Enabling is_applied_vip_tier or earn_points_tiers FORCES vip-tier \u2014 sending all here is why per-tier rates can save while the radio stays on All loyalty members.'),
+  is_applied_vip_tier: z15.boolean().optional().describe("Turn per-VIP-tier earning on for this rule. MUST be true for earn_points_tiers to have any effect \u2014 the backend reads the per-tier map only when this flag is set, and otherwise silently uses the flat earn_point."),
+  earn_points_tiers: z15.record(z15.object({
+    earn_point: z15.number().optional().describe("Points this tier earns, replacing the flat earn_point."),
+    rate_money: z15.number().optional().describe("place_order only: money amount that earns earn_point for this tier."),
+    type_earn: z15.enum(["point", "store_credit"]).optional()
+  })).optional().describe("Per-VIP-tier earning, keyed by TIER ID (from joy_list_tiers) \u2014 not tier name. For place_order a \xD71.25 multiplier on a 1-point-per-$1 base is earn_point 1.25, not 1.25 as a factor: the value REPLACES the base rate. Requires is_applied_vip_tier: true."),
+  reason: z15.string().min(3).describe("Why the merchant wants this configuration change."),
+  apply: z15.boolean().optional().describe("Set true only after reviewing this tool's dry-run preview.")
+};
+var PLACE_ORDER_EVENTS = /* @__PURE__ */ new Set(["place_order", "place_order_subscription"]);
+function placeOrderVipTierPatch(event, args) {
+  const enablingVipTier = args.is_applied_vip_tier === true || args.earn_points_tiers !== void 0;
+  if (!enablingVipTier)
+    return {};
+  if (!PLACE_ORDER_EVENTS.has(String(event)))
+    return {};
+  return { appliedPlaceOrderTo: "vip-tier", skipEarnPointGuest: true };
+}
+function toIntegerRatio(earnPoint, rateMoney) {
+  const isWhole = (value) => Math.abs(value - Math.round(value)) < 1e-9;
+  for (let factor = 2; factor <= 1e3; factor++) {
+    const points = earnPoint * factor;
+    const money = rateMoney * factor;
+    if (isWhole(points) && isWhole(money)) {
+      return { earnPoint: Math.round(points), rateMoney: Math.round(money) };
+    }
+  }
+  return void 0;
+}
+function fractionalTierRateError(earnPointsTiers) {
+  if (!earnPointsTiers)
+    return void 0;
+  const offenders = [];
+  for (const [tierId, rate] of Object.entries(earnPointsTiers)) {
+    const points = rate.earn_point;
+    if (points === void 0 || Number.isInteger(points))
+      continue;
+    const ratio = toIntegerRatio(points, rate.rate_money ?? 1);
+    offenders.push(ratio ? `${tierId}: earn_point ${points} \u2192 use earn_point ${ratio.earnPoint} with rate_money ${ratio.rateMoney}` : `${tierId}: earn_point ${points} (no clean integer ratio found)`);
+  }
+  if (offenders.length === 0)
+    return void 0;
+  return `Fractional earn_point does not create a multiplier. Points are (amount / rate_money) * earn_point, then rounded, and the admin's point field is integer-stepped \u2014 a fractional value silently rounds, so a tier earns the wrong amount. Express the multiplier as an integer RATIO instead: ${offenders.join("; ")}. The backend stores the ratio as sent and derives ratePercent from it (verified against live staging: earn_point 5 / rate_money 4 reads back as ratePercent 125), so no extra flag is needed to stop it collapsing.`;
+}
+function earnPointsTiersDropped(sent, saved) {
+  if (!sent || Object.keys(sent).length === 0)
+    return false;
+  if (!saved || typeof saved !== "object")
+    return true;
+  return Object.keys(saved).length === 0;
+}
+async function vipTierIdError(ctx, args) {
+  if (!args.earn_points_tiers)
+    return void 0;
+  const { data } = await ctx.api.getData("/tiers");
+  const tiers = Array.isArray(data) ? data : [];
+  const knownIds = tiers.map((tier) => String(tier.id));
+  const unknown = unknownTierIds(args.earn_points_tiers, knownIds);
+  if (unknown.length === 0)
+    return void 0;
+  const known = tiers.map((tier) => `${String(tier.id)} (${String(tier.name)})`).join(", ");
+  return `earn_points_tiers is keyed by tier ID, and these keys are not tiers on this shop: ${unknown.join(", ")}. Points for those keys would never be awarded and the write would still succeed. Valid tiers: ${known}.`;
+}
+async function resolveProgramProductUrls(ctx, args) {
+  if (!args.product_url?.length)
+    return args;
+  if (args.event !== "free_gift" || args.applied_to !== "sf_product") {
+    throw new JoyApiError("validation", 'product_url is only supported for free_gift programs with applied_to "sf_product". Use merchant-provided product IDs for another selection mode.');
+  }
+  const resolvedProducts = await Promise.all(args.product_url.map(async (productUrl) => {
+    const parsed = parseShopifyProductUrl(productUrl);
+    if (!parsed.ok)
+      throw new JoyApiError("validation", `${parsed.error} Received: ${productUrl}`);
+    const { data } = await ctx.api.getData(`/products/resolve?handle=${encodeURIComponent(parsed.handle)}`);
+    if (!data || !Number.isSafeInteger(data.id) || data.id <= 0) {
+      throw new JoyApiError("not_found", `No Shopify product was found for handle "${parsed.handle}". Ask the merchant for a valid product link; never fabricate an ID.`);
+    }
+    return { id: data.id, title: data.title, handle: data.handle };
+  }));
+  return { ...args, specific_products: [...args.specific_products ?? [], ...resolvedProducts] };
+}
+async function executeProgramChange(ctx, kind, args, toChange) {
+  const resolvedArgs = await resolveProgramProductUrls(ctx, args);
+  const prepared = toChange(resolvedArgs);
+  if (!prepared.ok)
+    return prepared.error;
+  if (prepared.action === "UPDATE") {
+    const { data: data2 } = await ctx.api.getData(`/programs/${prepared.programId}`);
+    const current = data2 ?? {};
+    const flagError = vipTierFlagError(resolvedArgs, current);
+    if (flagError)
+      return flagError;
+    const fractionError = fractionalTierRateError(resolvedArgs.earn_points_tiers);
+    if (fractionError)
+      return fractionError;
+    Object.assign(prepared.body, placeOrderVipTierPatch(current.event, resolvedArgs));
+    const tierError = await vipTierIdError(ctx, resolvedArgs);
+    if (tierError)
+      return tierError;
+    const unsupportedType = unsupportedUpdateProgramType(kind, current);
+    if (unsupportedType)
+      return unsupportedType;
+    const preview2 = buildProgramChangePreview({ kind, args: resolvedArgs, prepared, current });
+    if (isProgramChangeNoop(current, prepared))
+      return preview2;
+    const stop2 = requireApply(resolvedArgs.apply, preview2);
+    if (stop2)
+      return stop2;
+    await ctx.api.mutateData(`/programs/${prepared.programId}`, { method: "PUT", body: prepared.body });
+    if (resolvedArgs.earn_points_tiers || prepared.body.appliedPlaceOrderTo === "vip-tier") {
+      const { data: after } = await ctx.api.getData(`/programs/${prepared.programId}`);
+      if (earnPointsTiersDropped(resolvedArgs.earn_points_tiers, after?.earnPointsTiers)) {
+        return `Every other field saved, but earnPointsTiers did NOT: the backend stored an empty map. REST v2 declares earnPointsTiers as a shapeless Yup.object() and validates with stripUnknown, which strips every tier key. Per-VIP-tier earning cannot currently be set through this API by any caller \u2014 configure it in Joy admin, and report this so the schema gets a real shape. Do not retry; the result will be the same.`;
+      }
+      if (prepared.body.appliedPlaceOrderTo === "vip-tier" && after?.appliedPlaceOrderTo !== "vip-tier") {
+        return `Per-tier rates may have saved, but Who to reward did not: appliedPlaceOrderTo is still "${String(after?.appliedPlaceOrderTo ?? "unset")}" (All loyalty members), not vip-tier. The admin radio and the earning engine both read this field. Do not report VIP Tier only as applied; verify the place_order program in Joy admin.`;
+      }
+    }
+    return `Updated ${kind} program ${prepared.programId}. This affects every customer immediately.`;
+  }
+  const createTierError = await vipTierIdError(ctx, resolvedArgs);
+  if (createTierError)
+    return createTierError;
+  const { data } = await ctx.api.getData(`/programs/${kind}`);
+  const preview = buildProgramChangePreview({ kind, args: resolvedArgs, prepared, existing: toProgramList(data) });
+  const stop = requireApply(resolvedArgs.apply, preview);
+  if (stop)
+    return stop;
+  await ctx.api.mutateData(`/programs/${kind}`, { method: "POST", body: prepared.body });
+  return `Created ${kind} program. This affects every customer immediately.`;
+}
+function registerProgramConfigTools(server, ctx) {
+  registerConfigWriteTool(server, ctx, {
+    name: "joy_configure_earning_program",
+    title: "Create or update an earning program",
+    description: "WRITE \u2014 changes earning behaviour for every customer immediately. Creates place_order, sign_up, birthday, interact_website, write_review, and the nine social-follow rules (Instagram, YouTube, TikTok, Facebook, X/Twitter, Pinterest, Discord, Telegram, Reddit); social rules need url_account and write_review needs review_app. For place_order, is_applied_vip_tier / earn_points_tiers also sets Who to reward (appliedPlaceOrderTo) to vip-tier \u2014 the admin radio is that field, not the per-tier map. Use program_id to update ANY existing earning rule, including types this tool cannot create. Previews by default. Joy has no safe delete here: set status: false to reversibly disable a rule instead.",
+    inputSchema: programConfigInputSchema,
+    destructiveHint: true,
+    handler: (args) => executeProgramChange(ctx, "earning", args, toEarningProgramChange)
+  });
+  registerConfigWriteTool(server, ctx, {
+    name: "joy_configure_redemption_program",
+    title: "Create or update a redemption program",
+    description: "WRITE \u2014 changes redemption behaviour for every customer immediately. Creates amount_discount, percentage_discount, free_shipping, and free_gift rules. A free_gift accepts merchant-provided product_url values (Shopify product links) or product/collection IDs: program-level applied_to is sf_product, specific, or exclude_collection (never all). Joy resolves product-link handles and never invents IDs. Use program_id to update any existing redemption rule. Previews by default. Joy has no safe delete here: set status: false to reversibly disable a rule instead.",
+    inputSchema: programConfigInputSchema,
+    destructiveHint: true,
+    handler: (args) => executeProgramChange(ctx, "redemption", args, toRedemptionProgramChange)
+  });
+}
+
+// ../mcp-core/build/tools/tiersWrite.js
+import { z as z16 } from "zod";
+var TIER_THRESHOLD_WARNING = "Threshold changes are STAGED, not live. Members are not re-evaluated until the merchant relaunches tiers in Joy admin \u2014 this tool cannot trigger that.";
+var ENTRY_METHOD_WARNING = "Level-up rule (entryMethod) is saved immediately. NEW points, spend, and orders start counting in the new unit at once. Existing members keep their current tierPoint until the merchant relaunches tiers in Joy admin \u2014 this tool cannot trigger that. Review each tier threshold (target_point): 0/150/350 means points, currency, or orders depending on this rule.";
+var START_DATE_WARNING = "Program start date (startDate) is saved immediately and is the calculation window for NEW activity. Existing members keep their current tierPoint until the merchant relaunches tiers in Joy admin \u2014 this tool cannot trigger that. This is the VIP program start date, not reset_start_date.";
+var RESET_SCHEDULE_FIELDS = [
+  "useResetTier",
+  "resetFrequency",
+  "resetIntervalValue",
+  "resetIntervalUnit",
+  "resetStartDate",
+  "monthResetTier",
+  "dayResetTier"
+];
+var TIER_UPDATE_FIELDS = [
+  "name",
+  "icon",
+  "iconCustom",
+  "bgImage",
+  "defaultAvatar",
+  "targetPointUpdate",
+  "imageBlock",
+  "isExclusiveTier",
+  "hideDefaultTier",
+  "textColor",
+  "progressBarColor",
+  "boxBgColor",
+  "boxTextColor",
+  "bgCardColor",
+  "cardOpacity",
+  "iconColor",
+  "bgType",
+  "tierNamesLanguage"
+];
+var TIER_REWARD_FIELDS = [
+  "title",
+  "status",
+  "event",
+  "type",
+  "earnAmount",
+  "spendPoint",
+  "bonusPoints",
+  "codeName",
+  "appliedTo",
+  "orderReq",
+  "orderReqAmount",
+  "specificProducts",
+  "specificCollections",
+  "appliedCollectionIds",
+  "combinedWith",
+  "hasLimitShipping",
+  "limitShipping",
+  "expiredAfter",
+  "expiredUnit",
+  "isRefundCoupon",
+  "priority",
+  "showLoyaltyPage",
+  "perkTitleLanguage",
+  "redeemType",
+  "minSpendPoint",
+  "maxSpendPoint",
+  "rewardProductSelectionMode",
+  "rewardProductQuantity"
+];
+var TIER_PERK_FIELDS = ["contentPerk"];
+var TIER_SETTINGS_FIELDS = [
+  "entryMethod",
+  "startDate",
+  "prefix",
+  "isUsePrefixDiscountCode",
+  "showTierPointSettings",
+  "allowGiveEntryRewardAgain",
+  "useDemotionTier",
+  "typeDemotion",
+  "downgradeAfter",
+  "downgradeAfterUnit",
+  "useResetTier",
+  "resetAfter",
+  "resetAfterUnit",
+  "resetFrequency",
+  "resetIntervalValue",
+  "resetIntervalUnit",
+  "resetStartDate",
+  "monthResetTier",
+  "dayResetTier",
+  "isSyncTagsCustomerTier",
+  "customerTierTagPrefix",
+  "notificationDowngradeBefore",
+  "notificationDowngradeBeforeUnit"
+];
+var rewardEventSchema = z16.enum([
+  "amount_discount",
+  "percentage_discount",
+  "free_shipping",
+  "free_gift",
+  "bonus_point",
+  "buy_x_get_y"
+]);
+var finiteNumber = () => z16.number().finite();
+var tierRewardInputSchema = z16.object({
+  event: rewardEventSchema.describe("Required reward kind."),
+  title: z16.string().min(1).optional(),
+  type: z16.enum(["tier_spending", "tier_privileges", "pre_tier_reward"]).optional(),
+  status: z16.boolean().optional(),
+  earn_amount: finiteNumber().optional(),
+  spend_point: finiteNumber().optional(),
+  bonus_points: finiteNumber().optional(),
+  code_name: z16.string().optional(),
+  redeem_type: z16.string().optional(),
+  applied_to: z16.enum(["all", "specific_product", "specific"]).optional().describe("Tier-reward scope only: all, specific_product, or specific. These literals differ from program-level reward tools."),
+  order_req: z16.enum(["none", "min_amount", "min_quantity"]).optional(),
+  order_req_amount: finiteNumber().optional(),
+  min_spend_point: finiteNumber().optional(),
+  max_spend_point: finiteNumber().optional(),
+  specific_products: z16.array(z16.unknown()).optional(),
+  specific_collections: z16.array(z16.unknown()).optional(),
+  applied_collection_ids: z16.array(z16.unknown()).optional(),
+  combined_with: z16.array(z16.enum(["orderDiscounts", "shippingDiscounts", "productDiscounts"])).optional(),
+  has_limit_shipping: z16.boolean().optional(),
+  limit_shipping: finiteNumber().optional(),
+  expired_after: finiteNumber().optional(),
+  expired_unit: z16.enum(["day", "month"]).optional(),
+  is_refund_coupon: z16.boolean().optional(),
+  priority: finiteNumber().optional(),
+  show_loyalty_page: z16.boolean().optional(),
+  perk_title_language: z16.record(z16.unknown()).optional(),
+  reward_product_selection_mode: z16.string().optional(),
+  reward_product_quantity: finiteNumber().optional()
+});
+var tierConfigInputSchema = {
+  tier_id: z16.string().min(1).optional().describe("Existing tier ID. Omit to create a tier."),
+  name: z16.string().min(1).optional(),
+  target_point: finiteNumber().nonnegative().optional().describe("Tier threshold. On an existing tier this is staged; it does not immediately re-evaluate members."),
+  icon: z16.string().optional(),
+  icon_custom: z16.string().optional(),
+  bg_image: z16.string().optional().describe("Membership card background image URL for this ONE tier. Pass bg_type: 'image' alongside bg_image for it to show, or '' to clear. Use a durable URL the merchant controls; joy_upload_image uploads to their Shopify Files CDN and returns one. Widget-wide membershipCard.beforeSignIn.bgImage and membershipCard.afterSignIn.bgImage are different fields, managed by joy_set_widget_fields."),
+  default_avatar: z16.string().optional().describe("Membership card avatar image URL for members in this ONE tier. Pass '' to clear. Use a durable URL the merchant controls; joy_upload_image uploads to their Shopify Files CDN and returns one. Widget-wide membershipCard.beforeSignIn.bgImage and membershipCard.afterSignIn.bgImage are different fields, managed by joy_set_widget_fields."),
+  image_block: z16.string().optional(),
+  is_exclusive_tier: z16.boolean().optional(),
+  hide_default_tier: z16.boolean().optional(),
+  text_color: z16.string().optional(),
+  progress_bar_color: z16.string().optional(),
+  box_bg_color: z16.string().optional(),
+  box_text_color: z16.string().optional(),
+  bg_card_color: z16.string().optional(),
+  card_opacity: finiteNumber().optional(),
+  icon_color: z16.string().optional(),
+  bg_type: z16.string().optional(),
+  tier_names_language: z16.record(z16.unknown()).optional(),
+  rewards: z16.array(tierRewardInputSchema).optional().describe("Optional rewards to create with a NEW tier in this one configuration write."),
+  reason: z16.string().min(3).describe("Why the merchant wants this tier configuration."),
+  apply: z16.boolean().optional().describe("Set true only after the dry-run preview is approved.")
+};
+var tierRewardToolInputSchema = {
+  tier_id: z16.string().min(1).describe("Tier ID from joy_list_tiers."),
+  reward_id: z16.string().min(1).optional().describe("Existing reward ID. Omit to create."),
+  ...tierRewardInputSchema.shape,
+  product_url: z16.array(z16.string()).optional().describe("free_gift with applied_to specific_product only \u2014 Shopify product URLs to resolve into product IDs. Accepts /products/<handle> or /collections/<collection>/products/<handle>; do not invent IDs."),
+  reason: z16.string().min(3).describe("Why the merchant wants this reward configuration."),
+  apply: z16.boolean().optional().describe("Set true only after the dry-run preview is approved.")
+};
+var tierSettingsInputSchema = {
+  entry_method: z16.enum(["pointEarned", "moneySpent", "numberOfOrders"]).optional().describe("Tier calculation / level-up rule: how members climb the ladder. pointEarned = points earned, moneySpent = amount spent, numberOfOrders = number of orders. Saved immediately \u2014 NEW activity counts in the new unit at once. Existing members keep their current tierPoint until the merchant relaunches in Joy admin; this tool cannot trigger that. After changing, review each tier's target_point: the same 0/150/350 numbers mean points, currency, or orders depending on this rule."),
+  start_date: z16.string().min(1).optional().describe('VIP program start date \u2014 the calculation window in the admin "Tier calculation" card (ISO date, YYYY-MM-DD). Distinct from reset_start_date, which is the custom reset-cycle anchor. Saved immediately; members keep their current tierPoint until the merchant relaunches in Joy admin.'),
+  prefix: z16.string().optional().describe("Custom discount-code prefix for tier rewards. Supports {{tier_name}}. Pair with use_prefix_discount_code: true, or the custom prefix is stored but unused."),
+  use_prefix_discount_code: z16.boolean().optional().describe("When true, tier reward codes use prefix instead of the shop default."),
+  show_tier_point_settings: z16.boolean().optional().describe("Show tier-point editing on the customer admin page."),
+  allow_give_entry_reward_again: z16.boolean().optional().describe("When true (Joy default), a member who is demoted and later re-enters a tier can receive that tier entry reward again. False grants it only once."),
+  use_demotion_tier: z16.boolean().optional(),
+  type_demotion: z16.enum(["downgrade_tier", "reset_tier"]).optional(),
+  downgrade_after: z16.number().int().positive().optional(),
+  downgrade_after_unit: z16.enum(["day", "month", "year"]).optional(),
+  use_reset_tier: z16.boolean().optional(),
+  reset_after: z16.number().int().positive().optional(),
+  reset_after_unit: z16.enum(["day", "month", "year"]).optional(),
+  reset_frequency: z16.enum(["monthly", "quarterly", "half_yearly", "yearly", "custom"]).optional(),
+  reset_interval_value: z16.number().int().positive().optional(),
+  reset_interval_unit: z16.enum(["day", "month", "year"]).optional(),
+  reset_start_date: z16.string().min(1).optional(),
+  month_reset_tier: z16.number().int().min(1).max(12).optional(),
+  day_reset_tier: z16.number().int().min(1).max(31).optional(),
+  is_sync_tags_customer_tier: z16.boolean().optional(),
+  customer_tier_tag_prefix: z16.string().optional(),
+  notification_downgrade_before: z16.number().int().positive().optional(),
+  notification_downgrade_before_unit: z16.enum(["day", "month"]).optional(),
+  reason: z16.string().min(3).describe("Why the merchant wants these tier settings."),
+  apply: z16.boolean().optional().describe("Set true only after the dry-run preview is approved.")
+};
+var tierPerksInputSchema = {
+  tier_id: z16.string().min(1).describe("Tier ID from joy_list_tiers."),
+  perks: z16.array(z16.string().min(1)).describe("The COMPLETE replacement list of display-only perks. Include every existing perk that should remain; omitted entries are removed, and [] clears the list. Each entry is perk text or an http(s) URL rendered as a tick/cross icon in the storefront benefits table."),
+  reason: z16.string().min(3).describe("Why the merchant wants to replace this tier perk list."),
+  apply: z16.boolean().optional().describe("Set true only after the dry-run preview is approved.")
+};
+function tierFreeGiftSelectionError(args, requireAppliedTo = false) {
+  if (args.event !== "free_gift")
+    return void 0;
+  if (!args.applied_to) {
+    if (!requireAppliedTo)
+      return void 0;
+    return "Creating free_gift requires applied_to. Ask the merchant which product or collection is the gift; product and collection IDs must come from the merchant and cannot be invented.";
+  }
+  if (args.applied_to === "specific_product" && !args.specific_products?.length) {
+    return 'Creating free_gift with applied_to "specific_product" requires specific_products. Ask the merchant for the product IDs; product IDs cannot be invented.';
+  }
+  if (args.applied_to === "specific" && !args.applied_collection_ids?.length) {
+    return 'Creating free_gift with applied_to "specific" requires applied_collection_ids. Ask the merchant for the collection IDs; product or collection IDs cannot be invented.';
+  }
+  return void 0;
+}
+function toTierConfigBody(args, action) {
+  const body = {
+    name: args.name,
+    icon: args.icon,
+    iconCustom: args.icon_custom,
+    bgImage: args.bg_image,
+    defaultAvatar: args.default_avatar,
+    imageBlock: args.image_block,
+    isExclusiveTier: args.is_exclusive_tier,
+    hideDefaultTier: args.hide_default_tier,
+    textColor: args.text_color,
+    progressBarColor: args.progress_bar_color,
+    boxBgColor: args.box_bg_color,
+    boxTextColor: args.box_text_color,
+    bgCardColor: args.bg_card_color,
+    cardOpacity: args.card_opacity,
+    iconColor: args.icon_color,
+    bgType: args.bg_type,
+    tierNamesLanguage: args.tier_names_language
+  };
+  if (action === "CREATE") {
+    body.targetPoint = args.target_point;
+    body.rewards = args.rewards?.map(toTierRewardFields);
+    return omitUndefined(body);
+  }
+  body.targetPointUpdate = args.target_point;
+  return omitUndefined(body);
+}
+function toTierUpdateBody(args) {
+  return toTierConfigBody(args, "UPDATE");
+}
+function assertValidTierConfigArgs(args) {
+  if (!args.tier_id && !args.name) {
+    throw new JoyApiError("validation", "Creating a tier requires name.");
+  }
+  if (!args.tier_id && args.target_point === void 0) {
+    throw new JoyApiError("validation", "Creating a tier requires target_point.");
+  }
+  if (!args.tier_id && args.target_point === 0) {
+    throw new JoyApiError("validation", "target_point 0 is reserved for the system Bronze tier. Choose a positive threshold for a new tier.");
+  }
+  if (!args.tier_id) {
+    for (const reward of args.rewards ?? []) {
+      const selectionError = tierFreeGiftSelectionError(reward, true);
+      if (selectionError)
+        throw new JoyApiError("validation", selectionError);
+    }
+  }
+  if (args.tier_id && Object.keys(toTierUpdateBody(args)).length === 0) {
+    throw new JoyApiError("validation", "Choose at least one tier field to update.");
+  }
+}
+function findTierDuplicate(tiers, args) {
+  const byName = findDuplicate(tiers.map((tier) => ({ ...tier, title: tier.name })), { title: args.name });
+  if (byName)
+    return byName;
+  if (args.target_point === void 0)
+    return void 0;
+  return findDuplicate(tiers.map((tier) => ({ ...tier, title: String(tier.targetPoint) })), { title: String(args.target_point) });
+}
+function buildTierConfigPreview(params) {
+  const action = params.args.tier_id ? "UPDATE" : "CREATE";
+  const body = toTierConfigBody(params.args, action);
+  const current = action === "UPDATE" ? {
+    ...params.current,
+    targetPointUpdate: params.current?.targetPointUpdate ?? params.current?.targetPoint
+  } : {};
+  const dropped = action === "UPDATE" ? droppedFields({ rewards: params.args.rewards }, TIER_UPDATE_FIELDS) : droppedFields(body, [...TIER_UPDATE_FIELDS, "targetPoint", "rewards"]);
+  const target = params.current?.name ?? params.args.name ?? params.args.tier_id ?? "new tier";
+  return buildChangePreview({
+    action,
+    target: `tier "${String(target)}"`,
+    reason: params.args.reason,
+    changes: diffFields(current, body),
+    dropped,
+    duplicate: params.duplicate,
+    warnings: action === "UPDATE" && params.args.target_point !== void 0 ? [TIER_THRESHOLD_WARNING] : void 0
+  });
+}
+function rethrowTierCreateConflict(error) {
+  if (error instanceof JoyApiError && error.status === 409) {
+    throw new JoyApiError("conflict", "Cannot create this tier because another tier already has this name or target_point. Call joy_list_tiers, then update the existing tier with tier_id instead of retrying the create.", error.status);
+  }
+  throw error;
+}
+async function configureTier(ctx, args) {
+  assertValidTierConfigArgs(args);
+  const action = args.tier_id ? "UPDATE" : "CREATE";
+  if (action === "UPDATE") {
+    const current = await readTier(ctx, args.tier_id);
+    const preview2 = buildTierConfigPreview({ args, current });
+    const blocked2 = requireApply(args.apply, preview2);
+    if (blocked2)
+      return blocked2;
+    const updated = await ctx.api.mutateData(`/tiers/${encodeURIComponent(args.tier_id)}`, {
+      method: "PUT",
+      timeoutMs: 15e3,
+      body: toTierUpdateBody(args)
+    });
+    return tierConfigSummary("UPDATE", updated, args.target_point !== void 0);
+  }
+  const { data } = await ctx.api.getData("/tiers");
+  const duplicate = findTierDuplicate(Array.isArray(data) ? data : [], args);
+  const preview = buildTierConfigPreview({ args, duplicate });
+  const blocked = requireApply(args.apply, preview);
+  if (blocked)
+    return blocked;
+  try {
+    const created = await ctx.api.mutateData("/tiers", {
+      method: "POST",
+      timeoutMs: 15e3,
+      body: toTierConfigBody(args, "CREATE")
+    });
+    return tierConfigSummary("CREATE", created, false);
+  } catch (error) {
+    rethrowTierCreateConflict(error);
+  }
+}
+async function readTier(ctx, tierId) {
+  const { data } = await ctx.api.getData(`/tiers/${encodeURIComponent(tierId)}`);
+  if (data && typeof data === "object")
+    return data;
+  throw new JoyApiError("not_found", `Tier "${tierId}" was not found. Call joy_list_tiers before changing it.`);
+}
+function tierConfigSummary(action, tier, changedThreshold) {
+  const name = String(tier.name ?? tier.id ?? "tier");
+  const prefix = action === "CREATE" ? `Created tier "${name}".` : `Updated tier "${name}".`;
+  const warning = changedThreshold ? ` ${TIER_THRESHOLD_WARNING}` : "";
+  return summaryWithJson(`${prefix}${warning}`, compact(tier, ["id", "name", "targetPoint", "targetPointUpdate", "tierRewards"]));
+}
+function toTierRewardBody(args) {
+  return toTierRewardFields(args);
+}
+function toTierRewardFields(args) {
+  return omitUndefined({
+    title: args.title,
+    status: args.status,
+    event: args.event,
+    type: args.type,
+    earnAmount: args.earn_amount,
+    spendPoint: args.spend_point,
+    bonusPoints: args.bonus_points,
+    codeName: args.code_name,
+    redeemType: args.redeem_type,
+    appliedTo: args.applied_to,
+    orderReq: args.order_req,
+    orderReqAmount: args.order_req_amount,
+    minSpendPoint: args.min_spend_point,
+    maxSpendPoint: args.max_spend_point,
+    specificProducts: args.specific_products,
+    specificCollections: args.specific_collections,
+    appliedCollectionIds: args.applied_collection_ids,
+    combinedWith: args.combined_with,
+    hasLimitShipping: args.has_limit_shipping,
+    limitShipping: args.limit_shipping,
+    expiredAfter: args.expired_after,
+    expiredUnit: args.expired_unit,
+    isRefundCoupon: args.is_refund_coupon,
+    priority: args.priority,
+    showLoyaltyPage: args.show_loyalty_page,
+    perkTitleLanguage: args.perk_title_language,
+    rewardProductSelectionMode: args.reward_product_selection_mode,
+    rewardProductQuantity: args.reward_product_quantity
+  });
+}
+function assertValidTierRewardArgs(args) {
+  if (!args.reward_id && !args.title) {
+    throw new JoyApiError("validation", "Creating a tier reward requires title.");
+  }
+  const selectionError = tierFreeGiftSelectionError(args, !args.reward_id);
+  if (selectionError)
+    throw new JoyApiError("validation", selectionError);
+  if (args.reward_id && Object.keys(toTierRewardBody(args)).length === 1) {
+    throw new JoyApiError("validation", "Choose at least one tier-reward field to update in addition to event.");
+  }
+}
+async function resolveTierRewardProductUrls(ctx, args) {
+  if (!args.product_url?.length)
+    return args;
+  if (args.event !== "free_gift" || args.applied_to !== "specific_product") {
+    throw new JoyApiError("validation", 'product_url is only supported for free_gift rewards with applied_to "specific_product". Use merchant-provided product IDs for another selection mode.');
+  }
+  const resolvedProducts = await Promise.all(args.product_url.map(async (productUrl) => {
+    const parsed = parseShopifyProductUrl(productUrl);
+    if (!parsed.ok)
+      throw new JoyApiError("validation", `${parsed.error} Received: ${productUrl}`);
+    const { data } = await ctx.api.getData(`/products/resolve?handle=${encodeURIComponent(parsed.handle)}`);
+    if (!data || !Number.isSafeInteger(data.id) || data.id <= 0) {
+      throw new JoyApiError("not_found", `No Shopify product was found for handle "${parsed.handle}". Ask the merchant for a valid product link; never fabricate an ID.`);
+    }
+    return { id: data.id, title: data.title, handle: data.handle };
+  }));
+  return { ...args, specific_products: [...args.specific_products ?? [], ...resolvedProducts] };
+}
+function findTierReward(tier, rewardId) {
+  const rewards = Array.isArray(tier.tierRewards) ? tier.tierRewards : [];
+  return rewards.find((reward) => isData(reward) && String(reward.id) === rewardId);
+}
+function buildTierRewardPreview(params) {
+  const action = params.args.reward_id ? "UPDATE" : "CREATE";
+  const body = toTierRewardBody(params.args);
+  return buildChangePreview({
+    action,
+    target: `tier reward "${String(params.current?.title ?? params.args.title ?? params.args.event)}"`,
+    reason: params.args.reason,
+    changes: diffFields(params.current ?? {}, body),
+    dropped: droppedFields(body, TIER_REWARD_FIELDS),
+    duplicate: params.duplicate
+  });
+}
+async function configureTierReward(ctx, args) {
+  const resolvedArgs = await resolveTierRewardProductUrls(ctx, args);
+  assertValidTierRewardArgs(resolvedArgs);
+  const tier = await readTier(ctx, resolvedArgs.tier_id);
+  const action = resolvedArgs.reward_id ? "UPDATE" : "CREATE";
+  const current = resolvedArgs.reward_id ? findTierReward(tier, resolvedArgs.reward_id) : void 0;
+  if (resolvedArgs.reward_id && !current) {
+    throw new JoyApiError("not_found", `Reward "${resolvedArgs.reward_id}" is not attached to tier "${resolvedArgs.tier_id}". Nothing was changed; verify the tier and reward IDs before retrying.`);
+  }
+  const duplicate = action === "CREATE" ? findDuplicate(Array.isArray(tier.tierRewards) ? tier.tierRewards : [], {
+    event: resolvedArgs.event,
+    title: resolvedArgs.title
+  }) : void 0;
+  const preview = buildTierRewardPreview({ args: resolvedArgs, current, duplicate });
+  const blocked = requireApply(resolvedArgs.apply, preview);
+  if (blocked)
+    return blocked;
+  const result = await ctx.api.mutateData(action === "CREATE" ? `/tiers/${encodeURIComponent(resolvedArgs.tier_id)}/rewards` : `/tiers/${encodeURIComponent(resolvedArgs.tier_id)}/rewards/${encodeURIComponent(resolvedArgs.reward_id)}`, { method: action === "CREATE" ? "POST" : "PUT", timeoutMs: 15e3, body: toTierRewardBody(resolvedArgs) });
+  const rewardId = action === "CREATE" ? String(result.id ?? "") : resolvedArgs.reward_id;
+  if (!rewardId) {
+    throw new JoyApiError("server", "The tier-reward create response did not include an id. Do not assume the reward was configured; re-read the tier in Joy admin before trying again.");
+  }
+  const refreshed = await readTier(ctx, resolvedArgs.tier_id);
+  const reward = findTierReward(refreshed, rewardId);
+  if (!reward) {
+    throw new JoyApiError("server", `The write response named reward "${rewardId}", but it is not attached to tier "${resolvedArgs.tier_id}" after re-reading. Do not report this change as applied; verify it in Joy admin.`);
+  }
+  return tierRewardSummary(action, reward, resolvedArgs.tier_id);
+}
+function tierRewardSummary(action, reward, tierId) {
+  const verb = action === "CREATE" ? "Created" : "Updated";
+  return summaryWithJson(`${verb} tier reward "${String(reward.title ?? reward.id)}" on tier "${tierId}".`, compact(reward, ["id", "title", "event", "status", "earnAmount", "spendPoint", "bonusPoints", "appliedTo"]));
+}
+function toTierPerksBody(args) {
+  return { contentPerk: args.perks };
+}
+function buildTierPerksPreview(current, args) {
+  const body = toTierPerksBody(args);
+  return buildChangePreview({
+    action: "UPDATE",
+    target: `display-only perks on tier "${String(current.name ?? args.tier_id)}"`,
+    reason: args.reason,
+    changes: diffFields({ contentPerk: Array.isArray(current.contentPerk) ? current.contentPerk : [] }, body),
+    dropped: droppedFields(body, TIER_PERK_FIELDS),
+    warnings: [
+      "This write REPLACES the entire perk list; it does not append. Any existing perk omitted from perks will be removed."
+    ]
+  });
+}
+async function configureTierPerks(ctx, args) {
+  const current = await readTier(ctx, args.tier_id);
+  const preview = buildTierPerksPreview(current, args);
+  const blocked = requireApply(args.apply, preview);
+  if (blocked)
+    return blocked;
+  await ctx.api.mutateData(`/tiers/${encodeURIComponent(args.tier_id)}`, {
+    method: "PUT",
+    timeoutMs: 15e3,
+    body: toTierPerksBody(args)
+  });
+  const refreshed = await readTier(ctx, args.tier_id);
+  if (!Array.isArray(refreshed.contentPerk) || JSON.stringify(refreshed.contentPerk) !== JSON.stringify(args.perks)) {
+    throw new JoyApiError("server", `The tier perk write was not confirmed: contentPerk did not match the complete replacement list after re-reading tier "${args.tier_id}". Do not report these perks as applied; verify the tier in Joy admin and report this backend failure.`);
+  }
+  return summaryWithJson(`Replaced the complete display-only perk list on tier "${String(refreshed.name ?? args.tier_id)}" and confirmed it by reading the tier back.`, compact(refreshed, ["id", "name", "contentPerk"]));
+}
+function toTierSettingsBody(args) {
+  return omitUndefined({
+    entryMethod: args.entry_method,
+    startDate: args.start_date,
+    prefix: args.prefix,
+    isUsePrefixDiscountCode: args.use_prefix_discount_code,
+    showTierPointSettings: args.show_tier_point_settings,
+    allowGiveEntryRewardAgain: args.allow_give_entry_reward_again,
+    useDemotionTier: args.use_demotion_tier,
+    typeDemotion: args.type_demotion,
+    downgradeAfter: args.downgrade_after === void 0 ? void 0 : String(args.downgrade_after),
+    downgradeAfterUnit: args.downgrade_after_unit,
+    useResetTier: args.use_reset_tier,
+    resetAfter: args.reset_after === void 0 ? void 0 : String(args.reset_after),
+    resetAfterUnit: args.reset_after_unit,
+    resetFrequency: args.reset_frequency,
+    resetIntervalValue: args.reset_interval_value,
+    resetIntervalUnit: args.reset_interval_unit,
+    resetStartDate: args.reset_start_date,
+    monthResetTier: args.month_reset_tier === void 0 ? void 0 : String(args.month_reset_tier),
+    dayResetTier: args.day_reset_tier === void 0 ? void 0 : String(args.day_reset_tier),
+    isSyncTagsCustomerTier: args.is_sync_tags_customer_tier,
+    customerTierTagPrefix: args.customer_tier_tag_prefix,
+    notificationDowngradeBefore: args.notification_downgrade_before === void 0 ? void 0 : String(args.notification_downgrade_before),
+    notificationDowngradeBeforeUnit: args.notification_downgrade_before_unit
+  });
+}
+function touchesResetSchedule(body) {
+  return RESET_SCHEDULE_FIELDS.some((field) => Object.hasOwn(body, field));
+}
+function buildTierSettingsPreview(current, args, now = /* @__PURE__ */ new Date()) {
+  const body = toTierSettingsBody(args);
+  const changes = diffFields(current, body);
+  const calculationWarnings = [
+    ...changes.some((change) => change.field === "entryMethod") ? [ENTRY_METHOD_WARNING] : [],
+    ...changes.some((change) => change.field === "startDate") ? [START_DATE_WARNING] : []
+  ];
+  const entryMethodWarning = calculationWarnings.length > 0 ? calculationWarnings : void 0;
+  if (!touchesResetSchedule(body)) {
+    return {
+      kind: "preview",
+      body,
+      preview: buildChangePreview({
+        action: "UPDATE",
+        target: "tier settings",
+        reason: args.reason,
+        changes,
+        dropped: droppedFields(body, TIER_SETTINGS_FIELDS),
+        warnings: entryMethodWarning
+      })
+    };
+  }
+  const projectedSettings = prepareProjectedResetSettings(current, body, now);
+  const projected = projectScheduleResetTierAt(projectedSettings, now);
+  if (projected === void 0) {
+    return {
+      kind: "refused",
+      body,
+      guidance: "Refusing this tier reset change: Joy cannot calculate the projected scheduleResetTierAt from the merged settings. Supply a complete valid reset frequency, interval, and anchor/start date, then preview again. Applying blind could reset or demote every member on the wrong day."
+    };
+  }
+  const calculatedCurrent = projectScheduleResetTierAt(prepareProjectedResetSettings(current, {}, now), now);
+  const currentSchedule = current.scheduleResetTierAt ?? calculatedCurrent;
+  const scheduleWarning = [
+    `Current scheduleResetTierAt: ${formatSchedule(currentSchedule)}.`,
+    `Projected scheduleResetTierAt: ${formatSchedule(projected)}.`,
+    "This cron anchor controls when Joy demotes or resets every member."
+  ].join(" ");
+  return {
+    kind: "preview",
+    body,
+    projectedScheduleResetTierAt: projected,
+    preview: buildChangePreview({
+      action: "UPDATE",
+      target: "tier settings",
+      reason: args.reason,
+      changes,
+      dropped: droppedFields(body, TIER_SETTINGS_FIELDS),
+      warnings: entryMethodWarning ? [scheduleWarning, ...entryMethodWarning] : [scheduleWarning]
+    })
+  };
+}
+async function configureTierSettings(ctx, args) {
+  const current = await readTierSettings(ctx);
+  const decision = buildTierSettingsPreview(current, args);
+  if (decision.kind === "refused")
+    return decision.guidance;
+  const blocked = requireApply(args.apply, decision.preview);
+  if (blocked)
+    return blocked;
+  try {
+    const updated = await ctx.api.mutateData("/tiers/settings", {
+      method: "PUT",
+      timeoutMs: 15e3,
+      body: decision.body
+    });
+    const unconfirmed = unconfirmedSettingsFields(decision.body, updated ?? {});
+    if (unconfirmed.length > 0) {
+      throw new JoyApiError("server", `The tier-settings write was not confirmed for: ${unconfirmed.join(", ")}. Do not report those fields as changed; verify them in Joy admin.`);
+    }
+    const schedule = touchesResetSchedule(decision.body) ? ` Projected scheduleResetTierAt: ${formatSchedule(decision.projectedScheduleResetTierAt)}.` : "";
+    const calculationChanged = decision.body.entryMethod !== void 0 && !sameSettingValue("entryMethod", current.entryMethod, decision.body.entryMethod) || decision.body.startDate !== void 0 && !sameSettingValue("startDate", current.startDate, decision.body.startDate);
+    if (calculationChanged)
+      ctx.cache?.delete("tiers");
+    const calculationNote = [
+      decision.body.entryMethod !== void 0 && !sameSettingValue("entryMethod", current.entryMethod, decision.body.entryMethod) ? ENTRY_METHOD_WARNING : "",
+      decision.body.startDate !== void 0 && !sameSettingValue("startDate", current.startDate, decision.body.startDate) ? START_DATE_WARNING : ""
+    ].filter(Boolean).map((warning) => ` ${warning}`).join("");
+    return summaryWithJson(`Updated tier settings.${schedule}${calculationNote}`, compact(updated, [...TIER_SETTINGS_FIELDS, "id"]));
+  } catch (error) {
+    rethrowTierSettingsNotLaunched(error);
+  }
+}
+async function readTierSettings(ctx) {
+  try {
+    const { data } = await ctx.api.getData("/tiers/settings");
+    if (data && typeof data === "object")
+      return data;
+    throw new JoyApiError("not_found", "Tier settings are not available. Launch tiers first in Joy admin.");
+  } catch (error) {
+    rethrowTierSettingsNotLaunched(error);
+  }
+}
+function rethrowTierSettingsNotLaunched(error) {
+  if (error instanceof JoyApiError && error.kind === "not_found") {
+    throw new JoyApiError("not_found", "This shop has never launched tiers, so tier settings do not exist yet. Launch the tier program in Joy admin first; this MCP tool cannot launch it.", error.status);
+  }
+  throw error;
+}
+function prepareProjectedResetSettings(current, body, now = /* @__PURE__ */ new Date()) {
+  const merged = {
+    useResetTier: false,
+    resetFrequency: "yearly",
+    monthResetTier: "12",
+    dayResetTier: "31",
+    ...current,
+    ...body
+  };
+  if (merged.resetFrequency !== "custom" || merged.resetIntervalUnit !== "year")
+    return merged;
+  const timingKeys = ["resetFrequency", "resetIntervalValue", "resetIntervalUnit", "monthResetTier", "dayResetTier"];
+  const timingChanged = timingKeys.some((key) => !sameValue(current[key], merged[key]));
+  if (!timingChanged && validDate(current.resetStartDate))
+    return merged;
+  const first = nextAnchorOccurrence(merged.monthResetTier, merged.dayResetTier, 12, now, true, 2e3);
+  if (!first)
+    return merged;
+  return { ...merged, resetStartDate: formatIsoDate(first) };
+}
+function projectScheduleResetTierAt(settings, now = /* @__PURE__ */ new Date()) {
+  if (settings.useResetTier !== true)
+    return null;
+  const frequency = settings.resetFrequency;
+  if (frequency === "monthly") {
+    const next2 = nextMonthlyOccurrence(settings.dayResetTier, now, true);
+    return next2 ? formatIsoDate(next2) : void 0;
+  }
+  if (frequency === "custom" && settings.resetIntervalUnit === "day") {
+    const next2 = nextCustomDayOccurrence(settings.resetStartDate, settings.resetIntervalValue, now, true);
+    return next2 ? formatIsoDate(next2) : void 0;
+  }
+  const stepMonths = resetStepMonths(frequency, settings.resetIntervalValue, settings.resetIntervalUnit);
+  if (!stepMonths)
+    return void 0;
+  const baseYear = frequency === "custom" && settings.resetIntervalUnit === "year" && validDate(settings.resetStartDate) ? utcDate(new Date(settings.resetStartDate)).getUTCFullYear() : 2e3;
+  const next = nextAnchorOccurrence(settings.monthResetTier, settings.dayResetTier, stepMonths, now, true, baseYear);
+  return next ? formatIsoDate(next) : void 0;
+}
+function registerTierConfigTools(server, ctx) {
+  registerConfigWriteTool(server, ctx, {
+    name: "joy_configure_tier",
+    title: "Create or update a VIP tier",
+    description: "CONFIGURATION WRITE \u2014 creates a VIP tier, including optional inline rewards, or updates an existing tier. New tiers require name and target_point; target_point 0 is the system Bronze tier and cannot be created. Updating target_point is STAGED rather than live: Joy only promotes it and re-evaluates members when tiers relaunch in Joy admin.",
+    inputSchema: tierConfigInputSchema,
+    destructiveHint: false,
+    handler: (args) => configureTier(ctx, args)
+  });
+  registerConfigWriteTool(server, ctx, {
+    name: "joy_configure_tier_reward",
+    title: "Create or update a VIP tier reward",
+    description: "CONFIGURATION WRITE \u2014 attaches a reward to a tier or changes an attached reward. event is required. Tier reward applied_to values are all, specific_product, and specific; this is a DIFFERENT literal set from program-level reward tools. Numeric fields are strictly numeric because the REST backend otherwise accepts invalid strings.",
+    inputSchema: tierRewardToolInputSchema,
+    destructiveHint: false,
+    handler: (args) => configureTierReward(ctx, args)
+  });
+  registerConfigWriteTool(server, ctx, {
+    name: "joy_configure_tier_perks",
+    title: "Replace display-only VIP tier perks",
+    description: "CONFIGURATION WRITE \u2014 replaces the ENTIRE legacy contentPerk list on one VIP tier; it never appends. Pass every display-only perk that should remain, or [] to clear the list. These are storefront benefit-table labels or http(s) icon URLs and are distinct from the redeemable tierRewards managed by joy_configure_tier_reward.",
+    inputSchema: tierPerksInputSchema,
+    destructiveHint: true,
+    handler: (args) => configureTierPerks(ctx, args)
+  });
+  registerConfigWriteTool(server, ctx, {
+    name: "joy_configure_tier_settings",
+    title: "Configure VIP tier calculation, demotion and reset settings",
+    description: 'CONFIGURATION WRITE \u2014 the admin "Tier calculation" card plus demotion/reset. Covers entry_method (pointEarned / moneySpent / numberOfOrders), start_date (program calculation window \u2014 not reset_start_date), prefix / use_prefix_discount_code, show_tier_point_settings, allow_give_entry_reward_again, demotion, reset, customer-tag, and downgrade-notification settings. Changing entry_method or start_date saves immediately and NEW activity uses the new rule/window; existing members keep their current tierPoint until the merchant relaunches in Joy admin \u2014 this tool cannot trigger that. Any reset-schedule change previews the current and projected scheduleResetTierAt before it may apply, because that daily-cron anchor affects every tier member.',
+    inputSchema: tierSettingsInputSchema,
+    destructiveHint: true,
+    handler: (args) => configureTierSettings(ctx, args)
+  });
+}
+function omitUndefined(record) {
+  return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== void 0));
+}
+function isData(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function sameValue(a, b) {
+  return a === b || String(a) === String(b);
+}
+function sameSettingValue(field, a, b) {
+  if (field === "startDate" || field === "resetStartDate") {
+    return String(a ?? "").slice(0, 10) === String(b ?? "").slice(0, 10);
+  }
+  return sameValue(a, b);
+}
+function unconfirmedSettingsFields(body, updated) {
+  return Object.keys(body).filter((field) => !sameSettingValue(field, body[field], updated[field]));
+}
+function formatSchedule(value) {
+  if (value === void 0)
+    return "(not exposed by REST v2)";
+  if (value === null)
+    return "(none)";
+  return JSON.stringify(value);
+}
+function utcDate(value) {
+  return new Date(Date.UTC(value.getUTCFullYear(), value.getUTCMonth(), value.getUTCDate()));
+}
+function formatIsoDate(value) {
+  return value.toISOString().slice(0, 10);
+}
+function validDate(value) {
+  return typeof value === "string" && !Number.isNaN(new Date(value).getTime());
+}
+function integer(value) {
+  const numeric = typeof value === "number" ? value : Number(value);
+  return Number.isInteger(numeric) ? numeric : void 0;
+}
+function resetStepMonths(frequency, value, unit) {
+  if (frequency === "quarterly")
+    return 3;
+  if (frequency === "half_yearly")
+    return 6;
+  if (frequency === "yearly")
+    return 12;
+  if (frequency !== "custom")
+    return void 0;
+  const interval = integer(value);
+  if (!interval || interval < 1)
+    return void 0;
+  if (unit === "month")
+    return [2, 3, 4, 6, 12].includes(interval) ? interval : void 0;
+  if (unit === "year")
+    return interval <= 5 ? interval * 12 : void 0;
+  return void 0;
+}
+function nextMonthlyOccurrence(dayValue, after, inclusive) {
+  const day = integer(dayValue);
+  if (!day || day < 1 || day > 28)
+    return void 0;
+  const cursor = utcDate(after);
+  const candidate = new Date(Date.UTC(cursor.getUTCFullYear(), cursor.getUTCMonth(), day));
+  if (isAfterOrEqual(candidate, cursor, inclusive))
+    return candidate;
+  return new Date(Date.UTC(cursor.getUTCFullYear(), cursor.getUTCMonth() + 1, day));
+}
+function nextCustomDayOccurrence(startValue, intervalValue, after, inclusive) {
+  const interval = integer(intervalValue);
+  if (!validDate(startValue) || !interval || interval < 30)
+    return void 0;
+  const start = utcDate(new Date(startValue));
+  const cursor = utcDate(after);
+  const days = Math.round((cursor.getTime() - start.getTime()) / 864e5);
+  let multiple = Math.max(0, Math.floor(days / interval));
+  let candidate = new Date(start.getTime() + multiple * interval * 864e5);
+  while (!isAfterOrEqual(candidate, cursor, inclusive)) {
+    multiple += 1;
+    candidate = new Date(start.getTime() + multiple * interval * 864e5);
+  }
+  return candidate;
+}
+function nextAnchorOccurrence(monthValue, dayValue, stepMonths, after, inclusive, baseYear) {
+  const month = integer(monthValue);
+  const day = integer(dayValue);
+  if (!month || month < 1 || month > 12 || !day || day < 1 || day > 31)
+    return void 0;
+  if (day > daysInMonth(2e3, month - 1))
+    return void 0;
+  const cursor = utcDate(after);
+  const anchorMonth = baseYear * 12 + month - 1;
+  const cursorMonth = cursor.getUTCFullYear() * 12 + cursor.getUTCMonth();
+  let step = Math.floor((cursorMonth - anchorMonth) / stepMonths);
+  let candidate = anchorOccurrence(anchorMonth, day, step, stepMonths);
+  while (!isAfterOrEqual(candidate, cursor, inclusive)) {
+    step += 1;
+    candidate = anchorOccurrence(anchorMonth, day, step, stepMonths);
+  }
+  return candidate;
+}
+function anchorOccurrence(anchorMonth, day, step, stepMonths) {
+  const absoluteMonth = anchorMonth + step * stepMonths;
+  const year = Math.floor(absoluteMonth / 12);
+  const month = (absoluteMonth % 12 + 12) % 12;
+  return new Date(Date.UTC(year, month, Math.min(day, daysInMonth(year, month))));
+}
+function daysInMonth(year, month) {
+  return new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+}
+function isAfterOrEqual(candidate, cursor, inclusive) {
+  return inclusive ? candidate.getTime() >= cursor.getTime() : candidate.getTime() > cursor.getTime();
+}
+
+// ../mcp-core/build/tools/shopConfig.js
+import { z as z17 } from "zod";
+var SHOP_SETTINGS_FIELDS = [
+  "primaryLanguageInApp",
+  "dateFormat",
+  "dateFormatForActivity",
+  "pointPosition",
+  "customerApplyDiscountBehavior",
+  "customerRedeemCouponBehavior",
+  "customerFreeGiftBehavior",
+  "statusForReview",
+  "earnByOrderStatus",
+  "enableGlobalEarningLimit",
+  "globalEarningLimitTimeframe",
+  "globalEarningLimitRollingDays"
+];
+var SHOP_SETTINGS_ARGUMENTS = {
+  primary_language_in_app: "primaryLanguageInApp",
+  date_format: "dateFormat",
+  date_format_for_activity: "dateFormatForActivity",
+  point_position: "pointPosition",
+  customer_apply_discount_behavior: "customerApplyDiscountBehavior",
+  customer_redeem_coupon_behavior: "customerRedeemCouponBehavior",
+  customer_free_gift_behavior: "customerFreeGiftBehavior",
+  status_for_review: "statusForReview",
+  earn_by_order_status: "earnByOrderStatus",
+  enable_global_earning_limit: "enableGlobalEarningLimit",
+  global_earning_limit_timeframe: "globalEarningLimitTimeframe",
+  global_earning_limit_rolling_days: "globalEarningLimitRollingDays"
+};
+var SHOP_SETTINGS_VALID_ARGUMENTS = [...Object.keys(SHOP_SETTINGS_ARGUMENTS), "reason", "apply"];
+var TRANSLATION_LANGUAGE_VALID_ARGUMENTS = ["primary_language", "additional_language", "reason", "apply"];
+var SHOP_COLLECTION_FIELDS = ["statusForReview", "earnByOrderStatus"];
+var SETTINGS_DOCUMENT_FIELDS = SHOP_SETTINGS_FIELDS.filter((field) => !SHOP_COLLECTION_FIELDS.includes(field));
+var TRANSLATION_LOCALES = [
+  "ar",
+  "ckb",
+  "cs",
+  "da",
+  "de",
+  "el",
+  "en",
+  "es",
+  "et",
+  "fi",
+  "fr",
+  "ga",
+  "he-IL",
+  "hi",
+  "hu",
+  "id",
+  "it",
+  "ja",
+  "ko",
+  "lb",
+  "lt",
+  "lv",
+  "ms",
+  "nl",
+  "nb",
+  "pl",
+  "pt",
+  "ro",
+  "ru",
+  "sk",
+  "sl",
+  "sr",
+  "sv",
+  "th",
+  "tr",
+  "ur",
+  "vi",
+  "zh-CN",
+  "zh-TW",
+  "uk",
+  "hr"
+];
+function getUnknownArguments(args, validArguments) {
+  const valid = new Set(validArguments);
+  return Object.keys(args).filter((argument) => !valid.has(argument));
+}
+function assertKnownArguments(args, validArguments) {
+  const unknown = getUnknownArguments(args, validArguments);
+  if (unknown.length > 0) {
+    throw new Error(`Unknown argument${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}. Valid arguments: ${validArguments.join(", ")}.`);
+  }
+}
+function toShopSettingsBody(args) {
+  assertKnownArguments(args, SHOP_SETTINGS_VALID_ARGUMENTS);
+  const body = {};
+  for (const [argument, field] of Object.entries(SHOP_SETTINGS_ARGUMENTS)) {
+    if (args[argument] !== void 0)
+      body[field] = args[argument];
+  }
+  return body;
+}
+function getDroppedShopSettingsFields(args) {
+  return getUnknownArguments(args, SHOP_SETTINGS_VALID_ARGUMENTS);
+}
+function selectedFields(body, fields) {
+  const selected = fields.filter((field) => body[field] !== void 0);
+  return selected.length > 0 ? selected.join(", ") : "none selected";
+}
+function buildShopSettingsPreview(current, args) {
+  const body = toShopSettingsBody(args);
+  return buildChangePreview({
+    action: "UPDATE",
+    target: "shop settings",
+    reason: args.reason,
+    changes: diffFields(current, body),
+    dropped: getDroppedShopSettingsFields(args),
+    warnings: [
+      `This endpoint performs two independent writes: fields for the shops collection (${selectedFields(body, SHOP_COLLECTION_FIELDS)}) and fields for the separate settings document (${selectedFields(body, SETTINGS_DOCUMENT_FIELDS)}). There is no atomic rollback, so a partial failure is possible.`
+    ]
+  });
+}
+function validateTranslationLanguages(args) {
+  const invalid = [args.primary_language, args.additional_language].filter((locale) => !TRANSLATION_LOCALES.includes(locale));
+  if (invalid.length > 0) {
+    throw new Error(`Invalid locale: ${invalid.join(", ")}. Valid locales: ${TRANSLATION_LOCALES.join(", ")}.`);
+  }
+}
+function buildTranslationLanguagePreview(args) {
+  assertKnownArguments(args, TRANSLATION_LANGUAGE_VALID_ARGUMENTS);
+  validateTranslationLanguages(args);
+  return buildChangePreview({
+    action: "CREATE",
+    target: `storefront language "${args.additional_language}" from primary language "${args.primary_language}"`,
+    reason: args.reason,
+    changes: diffFields({}, {
+      primaryLanguage: args.primary_language,
+      additionalLanguage: args.additional_language
+    }),
+    warnings: [
+      `Applying this machine-translates the shop's entire existing ${args.primary_language} primary-language content into ${args.additional_language}. This is expensive and hard to undo.`
+    ]
+  });
+}
+function registerShopConfigTools(server, ctx) {
+  registerConfigWriteTool(server, ctx, {
+    name: "joy_configure_shop_settings",
+    title: "Configure safe shop-level loyalty settings",
+    description: "WRITE \u2014 updates a deliberately limited set of shop-level loyalty settings. The backend splits this request between the shops collection and a separate settings document without atomic rollback, so a partial failure is possible. SSO controls, tier-specific earning limits, and weekly-report BCC recipients are intentionally unavailable through this tool.",
+    inputSchema: {
+      primary_language_in_app: z17.enum(["en", "en-US", "fr", "es", "de", "it", "ja", "id", "zh-CN"]).optional(),
+      date_format: z17.enum(["MM/DD/YYYY", "DD/MM/YYYY", "YYYY/MM/DD", "YYYY-MM-DD"]).optional(),
+      date_format_for_activity: z17.enum(["HH:mm", "hh:mm A"]).optional(),
+      point_position: z17.enum(["before", "after"]).optional(),
+      customer_apply_discount_behavior: z17.enum(["stay_current", "go_to_cart", "open_cart_drawer"]).optional(),
+      customer_redeem_coupon_behavior: z17.enum(["auto_apply", "save_for_later"]).optional(),
+      customer_free_gift_behavior: z17.enum(["manual_add_to_cart", "auto_add_to_cart"]).optional(),
+      status_for_review: z17.enum(["pending", "approveAuto"]).optional(),
+      earn_by_order_status: z17.enum(["financial_status", "fulfillment_status"]).optional(),
+      enable_global_earning_limit: z17.boolean().optional(),
+      global_earning_limit_timeframe: z17.enum(["yearly", "monthly", "rolling"]).optional(),
+      global_earning_limit_rolling_days: z17.number().int().min(1).max(365).optional(),
+      reason: z17.string().min(3).describe("Why the merchant wants these shop-wide settings changed."),
+      apply: z17.boolean().optional().describe("Set true only after the merchant has approved the dry-run preview.")
+    },
+    destructiveHint: false,
+    strictArguments: true,
+    handler: async (args) => {
+      const current = (await ctx.api.getData("/shop/settings")).data ?? {};
+      const preview = buildShopSettingsPreview(current, args);
+      const stop = requireApply(args.apply, preview);
+      if (stop)
+        return stop;
+      const body = toShopSettingsBody(args);
+      if (Object.keys(body).length === 0)
+        return preview;
+      await ctx.api.mutateData("/shop/settings", { method: "PUT", body });
+      return `Updated shop settings: ${Object.keys(body).join(", ")}. The backend writes the shops collection and settings document separately; verify both values if the request reported an error.`;
+    }
+  });
+  registerConfigWriteTool(server, ctx, {
+    name: "joy_add_translation_language",
+    title: "Add a storefront translation language",
+    description: "WRITE \u2014 adds one storefront language by machine-translating the shop's entire existing primary-language content. This can be expensive and is hard to undo, so it always requires a dry-run preview and explicit approval before applying.",
+    inputSchema: {
+      primary_language: z17.enum(TRANSLATION_LOCALES),
+      additional_language: z17.enum(TRANSLATION_LOCALES),
+      reason: z17.string().min(3).describe("Why the merchant wants this storefront language added."),
+      apply: z17.boolean().optional().describe("Set true only after the merchant has approved the dry-run preview.")
+    },
+    destructiveHint: false,
+    strictArguments: true,
+    handler: async (args) => {
+      const preview = buildTranslationLanguagePreview(args);
+      const stop = requireApply(args.apply, preview);
+      if (stop)
+        return stop;
+      await ctx.api.mutateData("/translations/languages", {
+        method: "POST",
+        body: { primaryLanguage: args.primary_language, additionalLanguage: args.additional_language }
+      });
+      return `Added storefront language ${args.additional_language}; Joy has started machine-translating the existing ${args.primary_language} primary-language content.`;
+    }
+  });
+}
+
+// ../mcp-core/build/tools/brandingWrite.js
+import { z as z18 } from "zod";
+var WIDGET_DRAFT_SAVED_MESSAGE = "Saved to the V4 draft. The storefront is unchanged until you publish it in Joy admin.";
+var HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+var COLOR_ROLE_PATHS = {
+  primary: [
+    "theme.primaryColor",
+    "theme.primaryButtonColor",
+    "theme.headerBackgroundColor",
+    "theme.footerActiveTextColor",
+    "launcher.bgColor",
+    "launcher.pointBalance.labelBgColor",
+    "membershipCard.beforeSignIn.buttonBgColor",
+    "membershipCard.afterSignIn.buttonBgColor"
+  ],
+  secondary: ["theme.secondaryColor"],
+  text: ["theme.textColor", "theme.blockTextColor"],
+  heading: ["theme.headingTextColor", "theme.cardHeaderColor", "header.textColor"],
+  background: [
+    "theme.widgetBackgroundColor",
+    "theme.blockBgColor",
+    "theme.footerBgColor",
+    "theme.secondaryButtonColor",
+    "membershipCard.beforeSignIn.bgColor",
+    "membershipCard.afterSignIn.bgColor",
+    "membershipCard.afterSignIn.boxBgColor"
+  ],
+  button: ["theme.buttonStyleMode", "theme.buttonBgColor"],
+  buttonText: [
+    "theme.buttonTextColor",
+    "theme.primaryTextColor",
+    "launcher.textColor",
+    "launcher.pointBalance.labelTextColor",
+    "membershipCard.beforeSignIn.buttonTextColor",
+    "membershipCard.afterSignIn.buttonTextColor"
+  ],
+  border: ["theme.cardBorderColor"]
+};
+var COLOR_ROLES = Object.keys(COLOR_ROLE_PATHS);
+var CORNER_RADIUS_VALUES = ["radiusNone", "radiusSharp", "radiusSoft", "radiusRounded", "radiusExtra"];
+var BUTTON_STYLE_VALUES = ["store", "preset", "custom"];
+var CONTENT_STYLE_VALUES = ["icons_and_text", "text_only"];
+var DISPLAY_TYPE_VALUES = ["widget", "drawer", "floating-drawer"];
+var widgetDraftInputSchema = {
+  version: z18.enum(["v3", "v4"]).describe("Widget version to change. A live target is accepted only when this is the shop\u2019s currently live version."),
+  target: z18.enum(["draft", "live"]).default("draft").describe("Draft by default. Set live only after the merchant approves a dry-run preview of the immediate storefront change."),
+  apply_scan: z18.boolean().optional().describe("Apply a storefront scan through Joy\u2019s shared backend design merge. Omit scan_url to scan this shop\u2019s own storefront."),
+  scan_url: z18.string().url().startsWith("https://").optional().describe("Optional public HTTPS storefront URL to scan when apply_scan is true."),
+  storefront_password: z18.string().min(1).optional().describe("Optional storefront password used only when apply_scan is true. It is sent only in the PUT body and is never returned."),
+  apply_images: z18.boolean().optional().describe("When apply_scan is true, also replace detected logo and card imagery. Defaults to false."),
+  color_overrides: z18.record(z18.string()).optional().describe(`Optional hex overrides for supported V4 color roles: ${COLOR_ROLES.join(", ")}.`),
+  design_overrides: z18.object({
+    corner_radius: z18.enum(CORNER_RADIUS_VALUES).optional().describe("Corner style. radiusNone is square/not rounded; radiusExtra is the most rounded."),
+    button_style: z18.enum(BUTTON_STYLE_VALUES).optional().describe("store matches the storefront, custom uses the widget\u2019s own button colours."),
+    content_style: z18.enum(CONTENT_STYLE_VALUES).optional().describe("text_only removes the icons beside earn/redeem rows; icons_and_text shows them."),
+    display_type: z18.enum(DISPLAY_TYPE_VALUES).optional().describe("widget is the inline panel; drawer slides in from the edge; floating-drawer is the floating panel with a launcher button.")
+  }).optional().describe("Optional non-colour design settings. Values are enums, not numbers or CSS lengths."),
+  font_overrides: z18.object({ heading: z18.string().min(1).optional(), body: z18.string().min(1).optional() }).optional().describe("Optional heading and body font overrides."),
+  reason: z18.string().min(3).describe("Why the merchant wants this widget draft."),
+  apply: z18.boolean().optional().describe("Omit or set false for a dry run. Set true only after the merchant approves the preview.")
+};
+var brandScanInputSchema = {
+  url: z18.string().url().startsWith("https://").optional().describe("Optional public HTTPS storefront URL. Omit it to scan this shop\u2019s own storefront."),
+  storefront_password: z18.string().min(1).optional().describe("Optional storefront password for a gated shop. It is sent only in the POST body and is never returned.")
+};
+function isHexColor(value) {
+  return typeof value === "string" && HEX_COLOR.test(value);
+}
+function validateColorOverrides(overrides) {
+  if (!overrides)
+    return void 0;
+  for (const [role, color] of Object.entries(overrides)) {
+    if (!Object.hasOwn(COLOR_ROLE_PATHS, role)) {
+      return `Unknown color role "${role}". Supported roles are: ${COLOR_ROLES.join(", ")}.`;
+    }
+    if (!isHexColor(color)) {
+      return `Color override for "${role}" must be a hex color such as #112233.`;
+    }
+  }
+  return void 0;
+}
+function brandingErrorGuidance(error, operation, target = "draft") {
+  if (!(error instanceof JoyApiError))
+    return void 0;
+  const errorCode = error.code;
+  const passwordIncorrect = errorCode === "PASSWORD_INCORRECT" || /PASSWORD_INCORRECT|storefront password (?:did not unlock|was not accepted)|incorrect storefront password/i.test(error.modelMessage);
+  const passwordRequired = errorCode === "PASSWORD_REQUIRED" || error.status === 409 || /PASSWORD_REQUIRED|storefront is password-protected|storefront password is required/i.test(error.modelMessage);
+  if (operation === "scan" && passwordIncorrect) {
+    return new JoyApiError("validation", "The storefront password was not accepted. Ask the merchant to verify the storefront password, then pass the corrected value as storefront_password. Do not guess it.", error.status);
+  }
+  if (operation === "scan" && passwordRequired) {
+    return new JoyApiError("conflict", "The storefront is password-protected. Ask the merchant for the storefront password, then pass it as storefront_password to joy_scan_brand_design. Do not guess the password, and do not invent colors or fonts.", error.status);
+  }
+  if (operation === "scan" && error.status === 503) {
+    return new JoyApiError("server", "Joy could not complete the storefront design scan. No design has been returned, so do not invent colors, fonts, or button styling. Ask the merchant to retry later or configure the draft manually.", error.status);
+  }
+  if (operation === "draft" && target === "live" && error.status === 409) {
+    return new JoyApiError("conflict", "The live widget document exists only for the version the shop is currently using. This target: 'live' request used a non-live version and was refused. Check which widget version is currently live before retrying; do not blindly retry the other version.", error.status);
+  }
+  if (operation === "draft" && error.status === 409) {
+    return new JoyApiError("conflict", "The requested widget version is currently live. This tool only writes the non-live draft so it cannot alter the storefront. Choose the other version or edit the live widget manually in Joy admin.", error.status);
+  }
+  return void 0;
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function getPath(source, path) {
+  let current = source;
+  for (const part of path.split(".")) {
+    if (!current || typeof current !== "object" || Array.isArray(current))
+      return void 0;
+    current = current[part];
+  }
+  return current;
+}
+function sameValue2(first, second) {
+  return stableJson(first) === stableJson(second);
+}
+function stableJson(value) {
+  return JSON.stringify(value, (_key, raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+      return raw;
+    const record = raw;
+    return Object.fromEntries(Object.keys(record).sort().map((key) => [key, record[key]]));
+  });
+}
+var DOCUMENT_METADATA_KEYS = /* @__PURE__ */ new Set(["id", "shopId", "createdAt", "updatedAt", "type"]);
+function unconfirmedScanFields(readBack, expected) {
+  return Object.keys(expected).filter((key) => !DOCUMENT_METADATA_KEYS.has(key)).filter((key) => !sameValue2(readBack[key], expected[key]));
+}
+function setPath(source, path, value) {
+  const [part, ...rest] = path.split(".");
+  if (!part)
+    return source;
+  if (rest.length === 0)
+    return { ...source, [part]: value };
+  const child = asRecord(source[part]);
+  return { ...source, [part]: setPath(child, rest.join("."), value) };
+}
+function applyPath(draft, changes, path, value) {
+  const from = getPath(draft, path);
+  if (sameValue2(from, value))
+    return draft;
+  changes.push({ path, from, to: value });
+  return setPath(draft, path, value);
+}
+function applyColorRole(draft, changes, role, color) {
+  const paths = COLOR_ROLE_PATHS[role] ?? [];
+  return paths.reduce((next, path) => {
+    const value = path === "theme.buttonStyleMode" ? "custom" : color;
+    return applyPath(next, changes, path, value);
+  }, draft);
+}
+function redactCredential(text, credential) {
+  if (!credential)
+    return text;
+  return text.split(credential).join("[REDACTED]");
+}
+function errorWithoutCredential(error, credential) {
+  if (!credential)
+    return error;
+  if (error instanceof JoyApiError) {
+    return new JoyApiError(error.kind, redactCredential(error.modelMessage, credential), error.status);
+  }
+  if (error instanceof Error)
+    return new Error(redactCredential(error.message, credential));
+  return new Error(redactCredential(String(error), credential));
+}
+function prepareWidgetDraft(current, args) {
+  const changes = [];
+  let draft = current;
+  for (const [role, color] of Object.entries(args.color_overrides ?? {})) {
+    draft = applyColorRole(draft, changes, role, color);
+  }
+  if (args.design_overrides?.corner_radius) {
+    draft = applyPath(draft, changes, "theme.cornerRadius", args.design_overrides.corner_radius);
+  }
+  if (args.design_overrides?.button_style) {
+    draft = applyPath(draft, changes, "theme.buttonStyleMode", args.design_overrides.button_style);
+  }
+  if (args.design_overrides?.content_style) {
+    draft = applyPath(draft, changes, "theme.hideProgramIcons", args.design_overrides.content_style === "text_only");
+  }
+  if (args.design_overrides?.display_type) {
+    draft = applyPath(draft, changes, "display.type", args.design_overrides.display_type);
+  }
+  if (args.font_overrides?.heading) {
+    draft = applyPath(draft, changes, "fonts.heading", args.font_overrides.heading);
+    draft = applyPath(draft, changes, "fonts.headline", args.font_overrides.heading);
+  }
+  if (args.font_overrides?.body) {
+    draft = applyPath(draft, changes, "fonts.body", args.font_overrides.body);
+    draft = applyPath(draft, changes, "fonts.action", args.font_overrides.body);
+  }
+  return { draft, changes };
+}
+function unappliedDraftPaths(readBack, changes) {
+  return changes.filter((change) => !sameValue2(getPath(readBack, change.path), change.to)).map((change) => change.path);
+}
+function buildWidgetDraftPreview(args, changes) {
+  const target = args.target ?? "draft";
+  const lines = [
+    "DRY RUN \u2014 nothing has been changed yet.",
+    target === "live" ? `Would update the live ${args.version.toUpperCase()} widget configuration.` : `Would update the ${args.version.toUpperCase()} widget draft.`,
+    `Reason given: ${args.reason}`
+  ];
+  if (args.apply_scan === true) {
+    lines.push("", "Storefront scan changes:", "  Joy\u2019s backend will merge the detected colors, fonts, button style, and corner radius into the widget.");
+    if (args.apply_images === true) {
+      lines.push("  Images will change where detected: the program logo, membership-card hero, REFERRAL section banner, and every VIP tier background.");
+    } else {
+      lines.push("  Images will not change (apply_images defaults to false).");
+    }
+  }
+  if (changes.length === 0 && args.apply_scan !== true) {
+    lines.push("No supported field would change \u2014 do not report this as a saved design.");
+  } else if (changes.length > 0) {
+    lines.push("", "Changes:");
+    for (const change of changes) {
+      lines.push(`  ${change.path}: ${JSON.stringify(change.from)} \u2192 ${JSON.stringify(change.to)}`);
+    }
+  }
+  if (target === "live") {
+    lines.push("", "WARNING \u2014 saving this changes the storefront immediately. There is NO publish step and NO undo.");
+  } else {
+    lines.push("", "This writes only a non-live draft. The agent cannot see the resulting widget, so the merchant must review it in Joy admin and publish it manually if they approve.");
+  }
+  return lines.join("\n");
+}
+async function getBrandScan(ctx, args = {}) {
+  try {
+    if (args.storefront_password !== void 0) {
+      return await ctx.api.mutateData("/shop/branding/scan", {
+        method: "POST",
+        // A storefront scan launches a headless browser and loads a real
+        // commercial page; measured at 33s against arrae.com. The 20s client
+        // default would abort a scan that is working, so this one call gets a
+        // budget sized to the work rather than to a normal API round trip.
+        timeoutMs: 9e4,
+        body: {
+          ...args.url === void 0 ? {} : { url: args.url },
+          storefrontPassword: args.storefront_password
+        }
+      });
+    }
+    const { data } = await ctx.api.getData("/shop/branding/scan", {
+      timeoutMs: 9e4,
+      ...args.url === void 0 ? {} : { query: { url: args.url } }
+    });
+    return data;
+  } catch (error) {
+    const guided = brandingErrorGuidance(error, "scan") ?? error;
+    throw errorWithoutCredential(guided, args.storefront_password);
+  }
+}
+function widgetWriteQuery(version2, target) {
+  return target === "live" ? { version: version2, target } : { version: version2 };
+}
+function isPasswordFailure(error) {
+  if (!(error instanceof JoyApiError))
+    return false;
+  const errorCode = error.code;
+  return errorCode === "PASSWORD_REQUIRED" || errorCode === "PASSWORD_INCORRECT" || /PASSWORD_REQUIRED|PASSWORD_INCORRECT|STOREFRONT_PASSWORD_ENABLED|storefront password/i.test(error.modelMessage);
+}
+function applyScanBody(args) {
+  return {
+    applyScan: {
+      ...args.scan_url === void 0 ? {} : { url: args.scan_url },
+      ...args.storefront_password === void 0 ? {} : { storefrontPassword: args.storefront_password },
+      colors: true,
+      ...args.apply_images === true ? { images: true } : {}
+    }
+  };
+}
+async function getWidgetDraft(ctx, version2) {
+  try {
+    const { data } = await ctx.api.getData("/shop/branding/widget/draft", { query: { version: version2 } });
+    return asRecord(data);
+  } catch (error) {
+    throw brandingErrorGuidance(error, "draft") ?? error;
+  }
+}
+async function putWidgetDraft(ctx, version2, target, draft) {
+  try {
+    const result = await ctx.api.mutateData("/shop/branding/widget/draft", {
+      method: "PUT",
+      query: widgetWriteQuery(version2, target),
+      body: draft
+    });
+    return asRecord(result);
+  } catch (error) {
+    throw brandingErrorGuidance(error, "draft", target) ?? error;
+  }
+}
+async function putWidgetScan(ctx, args) {
+  try {
+    const result = await ctx.api.mutateData("/shop/branding/widget/draft", {
+      method: "PUT",
+      query: widgetWriteQuery(args.version, args.target),
+      // The SERVER runs the storefront scan inside this request — a headless
+      // browser over a real commercial page, measured at 33-90s. The 20s
+      // default aborts a write that is working, and an aborted write leaves the
+      // caller unable to tell whether it landed. putWidgetDraft, which sends an
+      // explicit document, is an ordinary write and keeps the default.
+      timeoutMs: 12e4,
+      body: applyScanBody(args)
+    });
+    return asRecord(result);
+  } catch (error) {
+    if (isPasswordFailure(error))
+      throw brandingErrorGuidance(error, "scan") ?? error;
+    throw brandingErrorGuidance(error, "draft", args.target) ?? error;
+  }
+}
+function registerBrandingReadTools(server, ctx) {
+  registerReadTool(server, ctx, {
+    name: "joy_scan_brand_design",
+    title: "Scan a storefront\u2019s design",
+    description: "READ \u2014 scans an optional public HTTPS storefront URL, or this shop\u2019s storefront when omitted, and returns detected colors, heading/body fonts, button style, and whether the result was cached. For a gated storefront, ask the merchant for its password and pass storefront_password; never guess it. The result is a design input, not visual proof of how the widget will look.",
+    inputSchema: brandScanInputSchema,
+    handler: async (args) => {
+      const scan = await getBrandScan(ctx, args);
+      const source = asRecord(scan.source);
+      const cached = source.cached === true;
+      const domain = typeof source.domain === "string" ? source.domain : "the storefront";
+      return redactCredential(summaryWithJson(`Brand scan completed for ${domain}. This is a ${cached ? "cached" : "fresh"} scan result; present it as detected storefront data, not a visual review of the widget.`, {
+        colors: scan.colors,
+        fonts: scan.fonts ?? {},
+        buttons: scan.buttons ?? {},
+        ...scan.images === void 0 ? {} : { images: scan.images },
+        source: compact(source, ["domain", "scannedAt", "cached"])
+      }), args.storefront_password);
+    }
+  });
+}
+function registerBrandingWriteTools(server, ctx) {
+  registerConfigWriteTool(server, ctx, {
+    name: "joy_configure_widget_draft",
+    title: "Configure widget brand settings",
+    description: "WRITE \u2014 draft by default; live only on explicit target: 'live'. Applies this shop\u2019s or a reference storefront\u2019s scan through Joy\u2019s shared backend design merge, supports limited explicit color, corner-radius, button-style and font overrides, previews by default, and reads the document back after saving. Images change only with apply_images: true. A live save changes the storefront immediately with no publish step and no undo. The agent cannot see the result, so do not claim it looks good.",
+    inputSchema: widgetDraftInputSchema,
+    destructiveHint: true,
+    handler: async (args) => {
+      try {
+        const target = args.target ?? "draft";
+        const current = await getWidgetDraft(ctx, args.version);
+        const validationError = validateColorOverrides(args.color_overrides);
+        if (validationError)
+          throw new JoyApiError("validation", validationError);
+        const prepared = prepareWidgetDraft(current, args);
+        const preview = buildWidgetDraftPreview(args, prepared.changes);
+        if (args.apply !== true)
+          return redactCredential(preview, args.storefront_password);
+        if (args.apply_scan !== true && prepared.changes.length === 0) {
+          return redactCredential(`${preview}
+
+No write was sent because this would be a no-op.`, args.storefront_password);
+        }
+        let explicitBase = current;
+        let scanApplied = false;
+        if (args.apply_scan === true) {
+          const expected = await putWidgetScan(ctx, args);
+          const readBack = await getWidgetDraft(ctx, args.version);
+          const unconfirmed = unconfirmedScanFields(readBack, expected);
+          if (unconfirmed.length > 0) {
+            const scanFailureGuidance = target === "live" ? "The live scan-based widget write was not confirmed. Do not report the design as saved; the storefront may already have changed, so ask the merchant to inspect the live widget and report this backend failure." : "The scan-based draft write was not confirmed. Do not report the design as saved; ask the merchant to review the draft in Joy admin and report this backend failure.";
+            throw new JoyApiError("server", `${scanFailureGuidance} These fields did not survive the required read-back: ${unconfirmed.join(", ")}.`);
+          }
+          explicitBase = readBack;
+          scanApplied = true;
+        }
+        const explicit = prepareWidgetDraft(explicitBase, args);
+        if (explicit.changes.length > 0) {
+          await putWidgetDraft(ctx, args.version, target, explicit.draft);
+          const readBack = await getWidgetDraft(ctx, args.version);
+          const missing = unappliedDraftPaths(readBack, explicit.changes);
+          if (missing.length > 0) {
+            const failureGuidance = target === "live" ? "The live widget write was not confirmed. Do not report the design as saved; the storefront may already have changed, so ask the merchant to inspect the live widget and report this backend failure." : "The draft write was not confirmed. Do not report the design as saved; ask the merchant to review the draft in Joy admin and report this backend failure.";
+            throw new JoyApiError("server", `${failureGuidance} These fields were unchanged after the required read-back: ${missing.join(", ")}.`);
+          }
+        }
+        const confirmed2 = [
+          ...scanApplied ? ["the backend storefront-design merge"] : [],
+          ...explicit.changes.length > 0 ? [
+            `${explicit.changes.length} explicit field${explicit.changes.length === 1 ? "" : "s"}`
+          ] : []
+        ].join(" and ");
+        const savedSummary = target === "live" ? `Updated the live ${args.version.toUpperCase()} widget configuration and confirmed ${confirmed2} by reading it back. The storefront changed as soon as it saved; there is no publish step and no undo.` : `Updated ${args.version.toUpperCase()} widget draft and confirmed ${confirmed2} by reading it back. The agent cannot see the rendered result; review it in Joy admin.`;
+        const result = `${summaryWithJson(savedSummary, {
+          ...scanApplied ? { appliedScan: { colors: true, images: args.apply_images === true } } : {},
+          ...explicit.changes.length > 0 ? { applied: explicit.changes.map((change) => ({ path: change.path, value: change.to })) } : {}
+        })}${target === "draft" ? `
+${WIDGET_DRAFT_SAVED_MESSAGE}` : ""}`;
+        return redactCredential(result, args.storefront_password);
+      } catch (error) {
+        throw errorWithoutCredential(error, args.storefront_password);
+      }
+    }
+  });
+}
+
+// ../mcp-core/build/tools/widgetFields.js
+import { isDeepStrictEqual } from "node:util";
+import { z as z19 } from "zod";
+var fieldsPath = "/shop/branding/widget/fields";
+var HIDE_MASTER = "display.hideWidgetButton";
+var HIDE_ALL = "launcher.hideCompletely";
+var HIDE_MOBILE = "launcher.hideOnMobile";
+function expandLauncherHideFields(fields, current) {
+  const byPath = new Map(fields.map(({ path, value }) => [path, value]));
+  const currentOf = (path) => current.find((field) => field.path === path)?.current;
+  const get = (path) => byPath.has(path) ? byPath.get(path) : currentOf(path);
+  const hideMaster = get(HIDE_MASTER);
+  const hideAll = get(HIDE_ALL);
+  const hideMobile = get(HIDE_MOBILE);
+  if ((hideAll === true || hideMobile === true) && hideMaster !== true) {
+    byPath.set(HIDE_MASTER, true);
+  }
+  if (hideMaster === true && hideAll !== true && hideMobile !== true) {
+    byPath.set(HIDE_ALL, true);
+  }
+  return [...byPath.entries()].map(([path, value]) => ({ path, value }));
+}
+var versionSchema = z19.literal("v4").default("v4").describe("Widget version. Field discovery currently supports V4.");
+var widgetFieldsInputSchema = {
+  version: versionSchema,
+  target: z19.enum(["draft", "live"]).default("draft").describe("Draft by default. Use live only when the merchant explicitly requests and approves the immediate storefront change; there is no undo."),
+  fields: z19.array(z19.object({
+    path: z19.string().min(1),
+    value: z19.unknown().refine((value) => value !== void 0, "Each field must include a value; use null to clear it.")
+  })).min(1).describe("Paths and values to set. Discover paths and allowed values with joy_get_widget_fields. The server validates every value."),
+  reason: z19.string().min(3).describe("Why the merchant wants these widget changes."),
+  apply: z19.boolean().optional().describe("Omit or set false for a dry run. Set true only after the merchant approves the preview.")
+};
+var MAX_FIELD_RESPONSE_CHARS = 12e3;
+function estimateSize(fields) {
+  return fields.reduce((total, field) => total + field.path.length + field.label.length + 60 + (field.values?.join("").length ?? 0), 0);
+}
+async function getWidgetFields(ctx, version2) {
+  const { data } = await ctx.api.getData(fieldsPath, { query: { version: version2 } });
+  if (!Array.isArray(data?.fields)) {
+    throw new JoyApiError("server", "Joy did not return widget field metadata. Field values cannot be confirmed.");
+  }
+  return data.fields;
+}
+function registerWidgetFieldReadTools(server, ctx) {
+  registerReadTool(server, ctx, {
+    name: "joy_get_widget_fields",
+    title: "Get settable widget fields",
+    description: "READ \u2014 discovers settable V4 widget fields. With no arguments it returns the group index (names, counts, example paths); pass group or search to get those fields with merchant-facing labels, paths, types, current values and allowed enum values. Call before joy_set_widget_fields; never guess a field path or enum value.",
+    inputSchema: {
+      version: versionSchema,
+      group: z19.string().optional().describe("Return only this group. Omit to get the group index first."),
+      search: z19.string().optional().describe('Return only fields whose label or path contains this text, e.g. "corner" or "launcher".')
+    },
+    handler: async (args) => {
+      const fields = await getWidgetFields(ctx, args.version);
+      const term = args.search?.trim().toLocaleLowerCase();
+      const matched = fields.filter((field) => (args.group === void 0 || field.group === args.group) && (term === void 0 || term === "" || field.label.toLocaleLowerCase().includes(term) || field.path.toLocaleLowerCase().includes(term)));
+      const wouldNotFit = estimateSize(matched) > MAX_FIELD_RESPONSE_CHARS;
+      if (args.group === void 0 && !term && wouldNotFit) {
+        const index = {};
+        for (const field of fields) {
+          const entry = index[field.group] ?? { fields: 0, examples: [] };
+          entry.fields += 1;
+          if (entry.examples.length < 2)
+            entry.examples.push(field.path);
+          index[field.group] = entry;
+        }
+        return summaryWithJson(`${fields.length} settable ${args.version.toUpperCase()} widget fields across ${Object.keys(index).length} groups. Call again with group: "<name>" or search: "<text>" to see fields and their allowed values.`, { groups: index });
+      }
+      if (matched.length === 0) {
+        return `No ${args.version.toUpperCase()} widget field matches ${args.group === void 0 ? `search "${args.search}"` : `group "${args.group}"`}. Call joy_get_widget_fields with no arguments to list the groups.`;
+      }
+      const groups = /* @__PURE__ */ new Map();
+      for (const { group, path, label, type, current, values } of matched) {
+        const entries = groups.get(group) ?? [];
+        entries.push({ label, path, type, current, ...values === void 0 ? {} : { values } });
+        groups.set(group, entries);
+      }
+      return summaryWithJson(`${matched.length} of ${fields.length} settable ${args.version.toUpperCase()} widget fields. Use the server-provided paths and values when preparing changes.`, { groups: Object.fromEntries(groups) });
+    }
+  });
+}
+function registerWidgetFieldWriteTools(server, ctx) {
+  registerConfigWriteTool(server, ctx, {
+    name: "joy_set_widget_fields",
+    title: "Set widget fields",
+    description: "CONFIG WRITE \u2014 set paths discovered by joy_get_widget_fields; the server validates fields and values. Previews each before \u2192 after by default, surfaces every refusal, and reads back after writing. Hiding the floating button needs display.hideWidgetButton AND launcher.hideCompletely (or hideOnMobile); setting one expands the other to match the admin Display panel. Account icon opening the widget is links.replaceAccountLink, not links.openWidgetAfterLogin. Draft by default; never switch to live unless the merchant explicitly requests target: 'live'. A live save changes the storefront immediately with no publish step and no undo. Set apply: true only after preview approval; do not claim visual verification.",
+    inputSchema: widgetFieldsInputSchema,
+    strictArguments: true,
+    destructiveHint: true,
+    handler: async (args) => {
+      const current = await getWidgetFields(ctx, args.version);
+      const fields = expandLauncherHideFields(args.fields, current);
+      const changes = fields.map(({ path, value }) => ({
+        path,
+        from: current.find((field) => field.path === path)?.current,
+        to: value
+      }));
+      if (args.apply !== true) {
+        return `${buildWidgetDraftPreview(args, changes)}
+
+The server will validate every requested path and value when applied; this preview does not confirm acceptance. Show this preview to the merchant, then call again with apply: true and the same arguments only after approval.`;
+      }
+      let result;
+      try {
+        result = await ctx.api.mutateData(fieldsPath, {
+          method: "PUT",
+          query: { version: args.version, target: args.target },
+          body: { fields }
+        });
+      } catch (error) {
+        throw brandingErrorGuidance(error, "draft", args.target) ?? error;
+      }
+      let readBack = [];
+      let readBackFailure;
+      try {
+        readBack = await getWidgetFields(ctx, args.version);
+      } catch (error) {
+        readBackFailure = error instanceof Error ? error.message : String(error);
+      }
+      const refusedPaths = new Set(result.refused.map((field) => field.path));
+      const applied2 = [];
+      const unconfirmed = [];
+      for (const field of fields) {
+        if (refusedPaths.has(field.path))
+          continue;
+        const accepted = result.applied.find((entry) => entry.path === field.path);
+        const observed = readBack.find((entry) => entry.path === field.path);
+        if (!readBackFailure && accepted && observed && isDeepStrictEqual(accepted.value, field.value) && isDeepStrictEqual(observed.current, field.value)) {
+          applied2.push({ path: field.path, value: field.value });
+          continue;
+        }
+        unconfirmed.push({ path: field.path, requested: field.value, current: observed?.current });
+      }
+      const summary = `Widget field write: ${applied2.length} confirmed by read-back, ${result.refused.length} refused, ${unconfirmed.length} unconfirmed.`;
+      const details = `${summary}
+${JSON.stringify({ refused: result.refused, unconfirmed, applied: applied2 }, null, 1)}`;
+      const consequence = args.target === "live" ? "WARNING \u2014 saving this changes the storefront immediately. There is NO publish step and NO undo." : applied2.length > 0 ? WIDGET_DRAFT_SAVED_MESSAGE : "Review the V4 draft in Joy admin.";
+      const report = `${details}
+${consequence}${readBackFailure ? `
+Read-back failed: ${readBackFailure}` : ""}`;
+      if (result.refused.length > 0 || unconfirmed.length > 0 || readBackFailure) {
+        throw new JoyApiError(unconfirmed.length > 0 || readBackFailure ? "server" : "validation", `${report}
+Do not report refused or unconfirmed fields as saved. Inspect the current widget in Joy admin before retrying; some fields may already have changed.`);
+      }
+      return report;
+    }
+  });
+}
+
+// ../mcp-core/build/tools/referralBrandingWrite.js
+import { z as z20 } from "zod";
+var POPUP_DISPLAY_TYPES = ["auto_show_popup", "show_bubble_teaser", "do_not_show"];
+var REFERRAL_WIDGET_ARGUMENTS = {
+  brand_color: "brandColor",
+  text_color: "textColor",
+  action_bg_color: "actionBgColor",
+  action_text_color: "actionTextColor",
+  color_type: "colorType",
+  custom_solid_color: "customSolidColor",
+  theme_text_font: "themeTextFont",
+  type_show_popup: "typeShowPopup",
+  is_auto_close_pop_up: "isAutoClosePopUp",
+  closing_pop_up_time: "closingPopUpTime",
+  frequency_show_popup: "frequencyShowPopup",
+  is_show_subscribe_newsletter: "isShowSubscribeNewsletter"
+};
+var hexColor = (description) => z20.string().refine(isHexColor, { message: "Must be a 3- or 6-digit hex color such as #123 or #112233." }).optional().describe(description);
+var referralWidgetInputShape = {
+  brand_color: hexColor("Primary accent color for the referral widget."),
+  text_color: hexColor("Main referral-widget text color."),
+  action_bg_color: hexColor("Referral-widget action button background color."),
+  action_text_color: hexColor("Referral-widget action button text color."),
+  color_type: z20.enum(["template", "custom-solid", "custom-gradient"]).optional().describe("Color mode. This endpoint can select an existing template or gradient, but cannot define gradient stops."),
+  custom_solid_color: hexColor("Custom solid background color used when color_type is custom-solid."),
+  theme_text_font: z20.string().trim().min(1).optional().describe("Referral-widget font family, for example Open+Sans."),
+  type_show_popup: z20.enum(POPUP_DISPLAY_TYPES).optional().describe("How the referral popup appears: automatically, as a bubble teaser, or not at all."),
+  is_auto_close_pop_up: z20.boolean().optional().describe("Whether an automatically shown referral popup closes itself."),
+  closing_pop_up_time: z20.number().int().min(1).optional().describe("Auto-close delay in seconds; must be a positive integer."),
+  frequency_show_popup: z20.number().int().min(1).max(10).optional().describe("Number of automatic popup displays, from 1 through 10. The admin UI stores this as an integer."),
+  is_show_subscribe_newsletter: z20.boolean().optional().describe("Show the newsletter subscription option in the referral popup."),
+  reason: z20.string().min(3).describe("Why the merchant wants the live referral widget changed."),
+  apply: z20.boolean().optional().describe("Set true only after the merchant has approved the dry-run preview.")
+};
+var referralWidgetArgsSchema = z20.object(referralWidgetInputShape).strict();
+function parseReferralWidgetArgs(input) {
+  const parsed = referralWidgetArgsSchema.safeParse(input);
+  if (parsed.success)
+    return parsed.data;
+  const issue = parsed.error.issues[0];
+  const field = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+  throw new JoyApiError("validation", `Invalid referral widget configuration \u2014 ${field}${issue.message} Fix the named parameter and call again.`);
+}
+function toReferralWidgetBody(args) {
+  const body = {};
+  for (const [argument, field] of Object.entries(REFERRAL_WIDGET_ARGUMENTS)) {
+    const value = args[argument];
+    if (value !== void 0)
+      body[field] = value;
+  }
+  return body;
+}
+function buildReferralWidgetPreview(current, args, body = toReferralWidgetBody(args)) {
+  return buildChangePreview({
+    action: "UPDATE",
+    target: "the LIVE referral V3 widget",
+    reason: args.reason,
+    changes: diffFields(current, body),
+    warnings: [
+      "This changes the LIVE referral widget as soon as it saves. There is no draft and no publish step."
+    ]
+  });
+}
+async function configureReferralWidget(ctx, input) {
+  const args = parseReferralWidgetArgs(input);
+  const body = toReferralWidgetBody(args);
+  if (Object.keys(body).length === 0) {
+    throw new JoyApiError("validation", `At least one referral widget field is required. Valid fields: ${Object.keys(REFERRAL_WIDGET_ARGUMENTS).join(", ")}.`);
+  }
+  const { data } = await ctx.api.getData("/shop/branding/referral");
+  const current = data ?? {};
+  const changes = diffFields(current, body);
+  const preview = buildReferralWidgetPreview(current, args, body);
+  if (changes.length === 0)
+    return preview;
+  const blocked = requireApply(args.apply, preview);
+  if (blocked)
+    return blocked;
+  await ctx.api.mutateData("/shop/branding/referral", { method: "PUT", body });
+  const { data: refreshedData } = await ctx.api.getData("/shop/branding/referral");
+  const refreshed = refreshedData ?? {};
+  const unconfirmed = diffFields(refreshed, body).map((change) => change.field);
+  if (unconfirmed.length > 0) {
+    throw new JoyApiError("server", `The live referral widget write was not confirmed: these requested fields did not match after the required read-back: ${unconfirmed.join(", ")}. Do not report the referral widget as configured; ask the merchant to verify it in Joy admin and report this backend failure. Do not retry blindly.`);
+  }
+  const appliedFields = changes.map((change) => change.field);
+  return summaryWithJson(`Updated the LIVE referral widget and confirmed ${appliedFields.length} field${appliedFields.length === 1 ? "" : "s"} by reading it back. There is no draft and no publish step.`, compact(refreshed, appliedFields));
+}
+function registerReferralBrandingWriteTools(server, ctx) {
+  registerConfigWriteTool(server, ctx, {
+    name: "joy_configure_referral_widget",
+    title: "Configure the live referral widget",
+    description: "CONFIGURATION WRITE \u2014 updates the LIVE referral V3 storefront popup immediately. This is not Widget V4: there is no draft and no publish step. It previews by default, requires explicit approval to apply, validates every color as hex before any HTTP call, and reads every requested field back before reporting success.",
+    inputSchema: referralWidgetInputShape,
+    destructiveHint: true,
+    strictArguments: true,
+    handler: (args) => configureReferralWidget(ctx, args)
+  });
+}
+
+// ../mcp-core/build/tools/redeemInCart.js
+import { z as z21 } from "zod";
+var PATH = "/shop/branding/redeem-inline";
+var styles = [
+  "minimal",
+  "editorial",
+  "luxury",
+  "bold",
+  "brutalism",
+  "playful",
+  "tech",
+  "botanic"
+];
+var fills = ["solid", "gradient-br", "gradient-r", "gradient-b", "radial"];
+var gradients = ["gradient-br", "gradient-r", "gradient-b", "radial"];
+var hex = z21.string().refine((value) => value === "" || isHexColor(value), "Use a hex color or an empty string to clear.");
+var https = z21.string().refine((value) => value === "" || (() => {
+  try {
+    return new URL(value).protocol === "https:";
+  } catch {
+    return false;
+  }
+})(), "Use an HTTPS URL or an empty string to clear.");
+var fill = z21.object({
+  fillType: z21.enum(fills).optional(),
+  colors: z21.array(z21.string()).min(1).max(2).optional(),
+  lastGradient: z21.enum(gradients).optional()
+}).strict();
+var colorFields = [
+  "text",
+  "dropdown",
+  "primary",
+  "buttonText",
+  "buttonHover",
+  "buttonHoverText",
+  "savings",
+  "sliderPrimary",
+  "sliderTrack",
+  "icon",
+  "dropdownAccent"
+];
+var colorsSchema = z21.object({
+  background: fill.optional(),
+  button: fill.optional(),
+  ...Object.fromEntries(colorFields.map((key) => [key, hex.optional()])),
+  buttonBorder: z21.string().optional(),
+  buttonHoverBorder: z21.string().optional()
+}).strict();
+var cssShapeFields = [
+  "buttonHoverOpacity",
+  "buttonHoverTransform",
+  "buttonHoverShadow",
+  "buttonShadow",
+  "buttonBorderWidth",
+  "buttonBorderStyle",
+  "buttonFontWeight",
+  "buttonLetterSpacing",
+  "buttonTextCase",
+  "buttonTransition",
+  "buttonHeight",
+  "buttonFontSize",
+  "buttonPaddingInline",
+  "buttonSweepColor",
+  "buttonSweepFrom",
+  "buttonSweepTo",
+  "buttonSweepDuration",
+  "buttonSweepEasing"
+];
+var fonts = ["default", "inter", "space-grotesk", "playfair", "pt-serif", "nunito"];
+var shapeSchema = z21.object({
+  ...Object.fromEntries(cssShapeFields.map((key) => [key, z21.string().optional()])),
+  borderColor: hex.optional(),
+  patternColor: hex.optional(),
+  dividerColor: hex.optional(),
+  borderRadius: z21.enum(["none", "sharp", "soft", "rounded", "extra"]).optional(),
+  backgroundPattern: z21.enum(["none", "diagonal", "crosshatch", "grid", "column"]).optional(),
+  headingFont: z21.enum(fonts).optional(),
+  bodyFont: z21.enum(["", ...fonts]).optional(),
+  buttonFont: z21.enum(["", ...fonts]).optional(),
+  applyLoadingStyle: z21.enum(["spinner", "spinner-label", "dots"]).optional(),
+  buttonHoverEffect: z21.enum(["auto", "color", "fade", "lift", "none", "sweep"]).optional(),
+  boxShadow: z21.enum(["none", "small", "medium", "large", "hard"]).optional(),
+  iconName: z21.enum([
+    "gift",
+    "crown",
+    "shopping-bag",
+    "star",
+    "heart",
+    "trophy",
+    "sparkle",
+    "ticket",
+    "none"
+  ]).optional(),
+  iconImage: https.optional(),
+  backgroundImage: https.optional(),
+  backgroundImageOverlay: z21.number().min(0).max(100).optional(),
+  dividerWidth: z21.enum(["thin", "medium", "thick"]).optional(),
+  dividerStyle: z21.enum(["solid", "dashed", "dotted"]).optional()
+}).strict();
+var behaviorFields = {
+  hide_for_guest: "hideForGuest",
+  hide_not_enough_point: "hideNotEnoughPoint",
+  detail_view_layout: "detailViewLayout",
+  has_enable_cancel: "hasEnableCancel",
+  enable_revoke_discount_apply_failed: "enableRevokeDiscountApplyFailed",
+  show_points_input: "showPointsInput",
+  prefer_higher_value_reward: "preferHigherValueReward",
+  show_earn_back: "showEarnBack",
+  has_reload_page: "hasReloadPage"
+};
+var behaviorInput = Object.fromEntries(Object.keys(behaviorFields).map((key) => [key, z21.boolean().optional()]));
+var common = { reason: z21.string().min(3), apply: z21.boolean().optional() };
+var behaviorArgs = z21.object({
+  ...behaviorInput,
+  position_mode: z21.enum(["above_cart_summary", "custom"]).optional(),
+  custom_type: z21.enum(["snippet", "selector"]).optional(),
+  css_selector: z21.string().optional(),
+  ...common
+}).strict();
+var designArgs = z21.object({
+  style: z21.enum(styles).optional(),
+  set_active: z21.boolean().optional(),
+  colors: colorsSchema.optional(),
+  shape: shapeSchema.optional(),
+  ...common
+}).strict();
+function parse(schema, input) {
+  const result = schema.safeParse(input);
+  if (result.success)
+    return result.data;
+  const issue = result.error.issues[0];
+  throw new JoyApiError("validation", `${issue.path.join(".")}: ${issue.message}`);
+}
+function valueAt(data, path) {
+  return path.split(".").reduce((value, key) => value?.[key], data);
+}
+function changesFor(data, body) {
+  const changes = [];
+  function visit(value, prefix) {
+    for (const [key, to] of Object.entries(value)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      if (to && typeof to === "object" && !Array.isArray(to))
+        visit(to, path);
+      else
+        changes.push(...diffFields({ [path]: valueAt(data, path) }, { [path]: to }));
+    }
+  }
+  visit(body, "");
+  return changes;
+}
+function warnings(data) {
+  return [
+    ...data.redeemCartV4Ready === false ? [
+      "V4 is disabled for this shop; settings are stored but do not show until enabled and published."
+    ] : [],
+    "Storefront updates after background metafield publish and requires the app embed."
+  ];
+}
+function confirmed(data, body) {
+  const missing = changesFor(data, body).map((change) => change.field);
+  if (missing.length)
+    throw new JoyApiError("server", `Redeem-in-cart write was not confirmed by read-back: ${missing.join(", ")}. Verify in Joy admin; do not retry blindly.`);
+}
+function applied(changes, data) {
+  return summaryWithJson("Confirmed the Redeem-in-Cart settings in Firestore. Storefront updates after background metafield publish; the app embed is required. Prior values are included for manual restoration.", {
+    changes: changes.map(({ field, from, to }) => ({ field, from: from ?? "(unset)", to })),
+    current: Object.fromEntries(changes.map(({ field }) => [field, valueAt(data, field)]))
+  });
+}
+async function getRedeemInCart(ctx, input) {
+  const args = parse(z21.object({ style: z21.enum(styles).optional() }).strict(), input);
+  const { data: raw } = await ctx.api.getData(PATH);
+  const data = raw ?? {};
+  const active = data.design?.activeStyle ?? "minimal";
+  const legacy = data.design?.styles?.[active]?.earnBack?.show;
+  const behavior = { ...data.behavior };
+  for (const [field, fallback] of Object.entries({
+    hideForGuest: false,
+    hideNotEnoughPoint: false,
+    detailViewLayout: false,
+    hasEnableCancel: true,
+    enableRevokeDiscountApplyFailed: true,
+    showPointsInput: true,
+    preferHigherValueReward: false
+  }))
+    behavior[field] ??= fallback;
+  behavior.showEarnBackEffective = behavior.showEarnBack === void 0 ? legacy !== false : behavior.showEarnBack;
+  if (behavior.showEarnBack === void 0) {
+    behavior.showEarnBack = legacy === false ? "(unset \u2192 hidden by legacy preset)" : "(unset \u2192 shown)";
+  }
+  behavior.hasReloadPage = data.behavior?.hasReloadPage ?? "(unset)";
+  behavior.hasReloadPageNote = "V3 theme setting, no effect on V4";
+  const position = { ...data.position };
+  for (const [field, fallback] of Object.entries({
+    mode: "above_cart_summary",
+    customType: "snippet",
+    cssSelector: ""
+  }))
+    position[field] ??= fallback;
+  const status = data.redeemCartV4Ready === void 0 ? "Redeem in cart V2 (internal V4, redeemCartV4Ready) status unknown (older backend)." : data.redeemCartV4Ready ? "Redeem in cart V2 (internal V4, redeemCartV4Ready) enabled for this shop (storefront follows after metafield publish; requires the app embed)." : "Redeem in cart V2 (internal V4, redeemCartV4Ready) disabled for this shop; stored settings do not currently apply.";
+  const resolved = data.activeStyleResolved === void 0 ? "unknown (older backend)" : data.activeStyleResolved;
+  return summaryWithJson(status, {
+    behavior,
+    position,
+    activeStyle: active,
+    activeStyleResolved: resolved,
+    customisedStyles: Object.keys(data.design?.styles ?? {}),
+    ...args.style ? {
+      style: args.style,
+      styleResolved: data.stylesResolved?.[args.style] ?? (data.activeStyleResolved?.id === args.style ? data.activeStyleResolved : "unknown (older backend)"),
+      storedOverrides: data.design?.styles?.[args.style] ?? {},
+      overriddenKeys: {
+        colors: Object.keys(data.design?.styles?.[args.style]?.colors ?? {}),
+        shape: Object.keys(data.design?.styles?.[args.style]?.shape ?? {})
+      },
+      legacyEarnBackShow: data.design?.styles?.[args.style]?.earnBack?.show ?? "(unset)"
+    } : {}
+  });
+}
+async function configureRedeemInCart(ctx, input) {
+  const args = parse(behaviorArgs, input);
+  if (args.position_mode === "custom" && args.custom_type === "selector" && !args.css_selector?.trim()) {
+    throw new JoyApiError("validation", "custom selector position requires a non-empty css_selector.");
+  }
+  const body = {};
+  for (const [argument, field] of Object.entries(behaviorFields)) {
+    const value = args[argument];
+    if (value !== void 0)
+      (body.behavior ??= {})[field] = value;
+  }
+  for (const [argument, field] of Object.entries({
+    position_mode: "mode",
+    custom_type: "customType",
+    css_selector: "cssSelector"
+  })) {
+    const value = args[argument];
+    if (value !== void 0)
+      (body.position ??= {})[field] = value;
+  }
+  if (!Object.keys(body).length)
+    throw new JoyApiError("validation", "At least one behavior or position field is required.");
+  const { data: raw } = await ctx.api.getData(PATH);
+  const current = raw ?? {};
+  const position = { ...current.position, ...body.position };
+  if (position.mode === "custom" && position.customType === "selector" && !position.cssSelector?.trim())
+    throw new JoyApiError("validation", "custom selector position requires a non-empty css_selector.");
+  const changes = changesFor(current, body);
+  const preview = buildChangePreview({
+    action: "UPDATE",
+    target: "Redeem-in-Cart behavior and position",
+    reason: args.reason,
+    changes,
+    warnings: [
+      ...warnings(current),
+      ...position.mode === "custom" && position.customType === "snippet" ? ["Custom snippet position requires the snippet in the theme."] : [],
+      "A bad CSS selector silently falls back to the default position."
+    ]
+  });
+  if (!changes.length)
+    return preview;
+  const blocked = requireApply(args.apply, preview);
+  if (blocked)
+    return blocked;
+  await ctx.api.mutateData(PATH, { method: "PUT", body });
+  const { data } = await ctx.api.getData(PATH);
+  confirmed(data ?? {}, body);
+  return applied(changes, data ?? {});
+}
+async function configureRedeemInCartDesign(ctx, input) {
+  const args = parse(designArgs, input);
+  const { data: raw } = await ctx.api.getData(PATH);
+  const current = raw ?? {};
+  const style = args.style ?? current.design?.activeStyle ?? "minimal";
+  const body = { design: {} };
+  if (args.set_active === true)
+    body.design.activeStyle = style;
+  if (args.colors || args.shape) {
+    const override = {};
+    if (args.colors && Object.keys(args.colors).length) {
+      override.colors = { ...args.colors };
+      for (const key of ["background", "button"]) {
+        const requested = override.colors[key];
+        if (!requested)
+          continue;
+        const existing = current.design?.styles?.[style]?.colors?.[key] ?? current.stylesResolved?.[style]?.colors?.[key] ?? (current.activeStyleResolved?.id === style ? current.activeStyleResolved.colors?.[key] : void 0);
+        if (existing) {
+          if (requested.fillType === void 0 && existing.fillType)
+            requested.fillType = existing.fillType;
+          if (requested.colors?.length === 1 && existing.colors?.[1])
+            requested.colors = [requested.colors[0], existing.colors[1]];
+          if (requested.lastGradient === void 0 && existing.lastGradient)
+            requested.lastGradient = existing.lastGradient;
+        }
+      }
+    }
+    if (args.shape && Object.keys(args.shape).length)
+      override.shape = args.shape;
+    if (Object.keys(override).length)
+      body.design.styles = { [style]: override };
+  }
+  if (!Object.keys(body.design).length)
+    throw new JoyApiError("validation", "Set set_active, colors, or shape to change a design.");
+  const changes = changesFor(current, body);
+  const previewChanges = changes.map((change) => {
+    const prefix = `design.styles.${style}.`;
+    if (!change.field.startsWith(prefix))
+      return change;
+    const resolved = current.stylesResolved?.[style] ?? (current.activeStyleResolved?.id === style ? current.activeStyleResolved : void 0);
+    return {
+      ...change,
+      from: valueAt(resolved, change.field.slice(prefix.length)) ?? change.from ?? "(preset default)"
+    };
+  });
+  const preview = buildChangePreview({
+    action: "UPDATE",
+    target: `Redeem-in-Cart preset ${style}`,
+    reason: args.reason,
+    changes: previewChanges,
+    warnings: [
+      ...warnings(current),
+      "No visual preview exists; a wrong color can appear for every customer."
+    ]
+  });
+  if (!changes.length)
+    return preview;
+  const blocked = requireApply(args.apply, preview);
+  if (blocked)
+    return blocked;
+  await ctx.api.mutateData(PATH, { method: "PUT", body });
+  const { data } = await ctx.api.getData(PATH);
+  confirmed(data ?? {}, body);
+  return applied(previewChanges, data ?? {});
+}
+function registerRedeemInCartReadTools(server, ctx) {
+  registerReadTool(server, ctx, {
+    name: "joy_get_redeem_in_cart",
+    title: "Read Redeem-in-Cart settings",
+    description: 'Read all effective behavior flags, position, active preset, its resolved colors and shape, and stored per-preset overrides. Admin "Redeem in cart V2" uses the internal V4 engine (redeemCartV4Ready); availability requires metafield publish and the app embed. Pass style to inspect one preset, including read-only legacy earnBack.show.',
+    inputSchema: { style: z21.enum(styles).optional() },
+    handler: (args) => getRedeemInCart(ctx, args)
+  });
+}
+function registerRedeemInCartWriteTools(server, ctx) {
+  registerConfigWriteTool(server, ctx, {
+    name: "joy_configure_redeem_in_cart",
+    title: "Configure Redeem-in-Cart behavior and position",
+    description: "CONFIGURATION WRITE. Preview first, then apply explicitly. Includes every behavior flag, including hidden show_earn_back and V3-only has_reload_page. A bad CSS selector silently falls back to default position. Confirms by read-back.",
+    inputSchema: behaviorArgs.shape,
+    destructiveHint: true,
+    strictArguments: true,
+    handler: (args) => configureRedeemInCart(ctx, args)
+  });
+  registerConfigWriteTool(server, ctx, {
+    name: "joy_configure_redeem_in_cart_design",
+    title: "Configure Redeem-in-Cart design",
+    description: "CONFIGURATION WRITE. Set the active preset or update its colors and shape. Preview first, then apply explicitly. No visual preview exists; storefront updates after metafield publish. Confirms every requested field by read-back.",
+    inputSchema: designArgs.shape,
+    destructiveHint: true,
+    strictArguments: true,
+    handler: (args) => configureRedeemInCartDesign(ctx, args)
+  });
+}
+
+// ../mcp-core/build/tools/themeSetup.js
+function loyaltyWidget(embeds) {
+  return embeds.find((embed) => embed.name === "Joy Loyalty Widget" || embed.handle === "app-embed");
+}
+function formatThemeSetup(themeSetup) {
+  const embeds = Array.isArray(themeSetup.embeds) ? themeSetup.embeds : [];
+  const blocks = Array.isArray(themeSetup.blocks) ? themeSetup.blocks : [];
+  const widget = loyaltyWidget(embeds);
+  const inactiveEmbeds = embeds.filter((embed) => !embed.active);
+  const actions = [];
+  if (widget && !widget.active) {
+    actions.push({
+      item: widget.name,
+      instruction: "The merchant must open this link, switch it on, and save in the theme editor.",
+      url: widget.activateUrl
+    });
+  }
+  for (const embed of inactiveEmbeds) {
+    if (embed === widget)
+      continue;
+    actions.push({
+      item: embed.name,
+      instruction: "The merchant must open this link, switch it on, and save in the theme editor.",
+      url: embed.activateUrl
+    });
+  }
+  for (const block of blocks) {
+    if (block.added === true)
+      continue;
+    actions.push({
+      item: block.name,
+      instruction: "The merchant can add this missing block from the theme editor and save.",
+      url: block.addUrl
+    });
+  }
+  const passwordWarning = themeSetup.passwordEnabled === true ? " Storefront password protection is enabled, so the merchant cannot visually verify the widget until it is removed." : "";
+  if (widget?.active && actions.length === 0 && !themeSetup.passwordEnabled) {
+    return "Loyalty widget is active. Theme setup is complete \u2014 nothing to do.";
+  }
+  if (!widget) {
+    return summaryWithJson(`The loyalty widget was not included in the theme audit.${passwordWarning} This read-only tool cannot change the theme.`, { next_steps: actions });
+  }
+  const widgetStatus = widget.active ? "active" : "OFF";
+  return summaryWithJson(`Loyalty widget is ${widgetStatus}.${passwordWarning} This read-only tool cannot switch anything on; only the merchant can use the server-provided links and save the change.`, { next_steps: actions });
+}
+function registerThemeSetupTools(server, ctx) {
+  registerReadTool(server, ctx, {
+    name: "joy_check_theme_setup",
+    title: "Check storefront theme setup",
+    description: "Read-only diagnosis for the Joy loyalty widget, related theme embeds, and missing blocks. It cannot switch anything on or add anything: only the merchant can open the server-provided Shopify editor link, make the change, and save. Use it to answer why the widget is not showing and to get the exact setup links; never claim this tool enabled anything.",
+    inputSchema: {},
+    handler: async () => {
+      const { data } = await ctx.api.getData("/shop/theme/extensions");
+      return formatThemeSetup(data ?? {});
+    }
+  });
+}
+
+// ../mcp-core/build/tools/imageUpload.js
+import { z as z22 } from "zod";
+var imageUploadInputSchema = {
+  source_url: z22.string().url().optional().describe("Public URL of an already hosted image. Provide exactly one of source_url or data_url."),
+  data_url: z22.string().optional().describe("Image bytes as a data URL, for example an image the agent generated. Provide exactly one of data_url or source_url."),
+  filename: z22.string().min(1).max(200).optional().describe("Filename to use for the uploaded image."),
+  alt: z22.string().max(512).optional().describe("Merchant-provided alternative text for the image."),
+  reason: z22.string().min(3).describe("Why the merchant wants this image uploaded."),
+  apply: z22.boolean().optional().describe("Omit or set false for a dry run. Set true only after the merchant approves the preview.")
+};
+function imageUploadErrorGuidance(error) {
+  if (!(error instanceof JoyApiError))
+    return void 0;
+  if (error.status === 400) {
+    return new JoyApiError("validation", "The image source was rejected (not an image, unsupported type, or a blocked URL). Do not retry the same input.", error.status);
+  }
+  if (error.status === 413) {
+    return new JoyApiError("validation", "The image is too large; the upload cap is 20 MB. Resize or compress it before trying again.", error.status);
+  }
+  if (error.status === 502) {
+    return new JoyApiError("server", "Shopify rejected the upload or the file never went live. Safe to retry ONCE; if it fails again, stop and report the failure to the merchant.", error.status);
+  }
+  return void 0;
+}
+function registerImageUploadTools(server, ctx) {
+  registerConfigWriteTool(server, ctx, {
+    name: "joy_upload_image",
+    title: "Upload image to Shopify Files",
+    description: "CONFIG WRITE \u2014 uploads an image to the merchant's Shopify Files CDN and returns a permanent URL. Two-step flow: first call joy_upload_image, then pass its returned url to joy_set_widget_fields for any image field (sections.<ID>.bannerImage, membershipCard.*.bgImage, header.bannerImage, program.logo), or to joy_update_loyalty_page_design for `hero.backgroundImage`, `hero.mobileBackgroundImage`, `inlineBanner.backgroundImage`, `inlineBanner.mobileBackgroundImage`, `earn.bannerImage`, `referral.image`, or `icons`; that loyalty-page tool also accepts separate video URLs at `hero.backgroundVideo` and `hero.mobileBackgroundVideo`. Use data_url for image bytes the agent generated, or source_url for an image already hosted somewhere public; provide exactly one. The upload cap is 20 MB; the server validates the image type and source. This tool cannot see the image: do not describe, judge, or vouch for what was uploaded. The merchant reviews it in Joy admin. This writes into the merchant's store and is not undone by discarding a widget draft: the file stays in Shopify Files until the merchant deletes it. Dry run by default; set apply: true only after the merchant approves the preview.",
+    inputSchema: imageUploadInputSchema,
+    strictArguments: true,
+    destructiveHint: false,
+    handler: async (args) => {
+      if (args.source_url !== void 0 === (args.data_url !== void 0)) {
+        throw new JoyApiError("validation", "Provide exactly one of source_url or data_url, never both. No image was uploaded.");
+      }
+      const { source_url, data_url, filename, alt } = args;
+      const body = { source_url, data_url, filename, alt };
+      if (args.apply !== true) {
+        return summaryWithJson("DRY RUN \u2014 no image was uploaded. Applying writes a permanent file into the merchant's Shopify Files; discarding a widget draft does not remove it. The file stays until the merchant deletes it. This tool cannot see the image; the merchant reviews it in Joy admin. Show this preview to the merchant, then call again with apply: true and the same arguments only after approval.", { ...body, data_url: data_url === void 0 ? void 0 : "[provided image bytes; not inspected]", reason: args.reason });
+      }
+      let result;
+      try {
+        result = await ctx.api.mutateData("/files/images", { method: "POST", body });
+      } catch (error) {
+        throw imageUploadErrorGuidance(error) ?? error;
+      }
+      return summaryWithJson("Image uploaded to the merchant's Shopify Files CDN. Pass the returned url to joy_set_widget_fields for the desired image field. This tool cannot see or vouch for the image; the merchant reviews it in Joy admin. The file remains in Shopify Files until the merchant deletes it, even if the widget draft is discarded.", result);
+    }
+  });
+}
+
+// ../mcp-core/build/prompts.js
+import { z as z23 } from "zod";
+function registerAllPrompts(server) {
+  server.registerPrompt("support_missing_points", {
+    title: "Investigate missing points for an order",
+    description: "Support workflow: verify whether a customer really is missing points for an order, explain why, and prepare a compensation proposal with a proper audit reason.",
+    argsSchema: {
+      email: z23.string().describe("Customer's email address"),
+      order_number: z23.string().optional().describe("Order name/number the customer says earned nothing, e.g. #1234")
+    }
+  }, ({ email, order_number }) => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: [
+            `A customer (${email}) reports they did not receive loyalty points${order_number ? ` for order ${order_number}` : ""}. Investigate before changing anything:`,
+            "",
+            "1. Look up the member with joy_find_member \u2014 flag anything unusual (disabled state, guest, recently created).",
+            `2. Check joy_get_member_activity for an earn entry matching the order${order_number ? "" : " they describe (ask me for the order number if you cannot identify it)"}.`,
+            order_number ? `3. Run joy_explain_order_points for ${order_number} \u2014 it re-runs the actual earning engine and reports which gate or rule condition blocked earning, if any.` : "3. Once the order is identified, run joy_explain_order_points on it \u2014 it re-runs the actual earning engine and reports which gate or rule condition blocked earning, if any.",
+            "4. Conclude with exactly one of: (a) points were already awarded (show the activity entry), (b) points were correctly not awarded (show the blocking gate/rule \u2014 cite its configured threshold or condition, do not paraphrase from memory), or (c) points are genuinely missing.",
+            "5. Only for case (c): state the exact number of points owed and propose a joy_award_points call with a reason that names the order and the root cause. Wait for my explicit confirmation before executing \u2014 never award in the same turn as the diagnosis.",
+            "",
+            "Caveat to include when you rely on joy_explain_order_points: it recomputes against the order as it exists now \u2014 if the order changed after the original webhook (e.g. partial refund), the explanation reflects the current state, not the historical moment."
+          ].join("\n")
+        }
+      }
+    ]
+  }));
+  server.registerPrompt("program_review", {
+    title: "Loyalty program review (health + revenue + tiers + referral)",
+    description: "Periodic business review: program health check, revenue impact, tier performance, and referral results \u2014 with data-source rules so numbers from different systems are never mixed.",
+    argsSchema: {
+      period: z23.string().optional().describe("Reporting period, e.g. 'last 30 days', 'last month', 'this quarter'. Defaults to last 30 days.")
+    }
+  }, ({ period }) => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: [
+            `Review my loyalty program for ${period ?? "the last 30 days"}. Run, in parallel where possible:`,
+            "",
+            "1. joy_get_loyalty_health_check \u2014 overall score and flags.",
+            "2. joy_get_loyalty_revenue_report \u2014 revenue impact (Shopify sales data).",
+            "3. joy_get_tier_performance_breakdown \u2014 which VIP tier earns its keep.",
+            "4. joy_get_analytics_report with report_type referral_summary, and points_movement for the same period.",
+            "",
+            "Data-source rules (important):",
+            "- joy_get_loyalty_revenue_report and joy_get_tier_performance_breakdown read Shopify sales data (ShopifyQL); joy_get_analytics_report reads the Joy event log (BigQuery). These measure differently \u2014 label the source of every figure and never combine numbers across the two sources into one derived metric.",
+            "- If a ShopifyQL tool returns a 403 about the read_reports scope, relay its grant instructions instead of substituting numbers from the other source.",
+            "- If any response carries a backfill WARNING, repeat that caveat next to the affected numbers \u2014 do not present them as final.",
+            "",
+            "Format: a 3-sentence executive summary first, then anomalies worth my attention (with the flag or figure that triggered each), then exactly one concrete recommended action. Skip metrics that are unremarkable."
+          ].join("\n")
+        }
+      }
+    ]
+  }));
+  server.registerPrompt("investigate_member", {
+    title: "Investigate a member for abuse risk",
+    description: "Fraud/abuse triage for one member: risk flags, point activity, and referral history \u2014 with the mandatory caveat about signal limitations and no punitive action.",
+    argsSchema: {
+      email: z23.string().describe("Email of the member to investigate")
+    }
+  }, ({ email }) => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: [
+            `I suspect member ${email} may be abusing the loyalty program (referral self-dealing, unusual redemptions, or similar). Investigate:`,
+            "",
+            "1. joy_find_member \u2014 profile basics and state.",
+            "2. joy_investigate_member_risk \u2014 the pre-defined abuse flags. For every flag that fires, show the concrete supporting data the tool returns; do not add suspicions of your own beyond the flags.",
+            "3. joy_get_member_activity and joy_get_member_referrals \u2014 recent point movements and referral results, to give the flags context.",
+            "",
+            "Mandatory caveat in your answer: device/IP matching compares the MOST RECENT values only \u2014 there is no full history over time \u2014 so these flags are advisory signals to support my judgement, not proof of abuse.",
+            "",
+            "End with: which flags fired (if any), what specific records I should open in the Joy admin to verify each one, and your read on severity. Do NOT deduct points, refund coupons, or take any corrective action \u2014 this session is investigation only; I will decide separately."
+          ].join("\n")
+        }
+      }
+    ]
+  }));
+  server.registerPrompt("setup_loyalty_program", {
+    title: "Set up a loyalty program safely",
+    description: "Guided loyalty-program setup: inspect the current configuration, propose a minimal program, and make each approved configuration change one at a time.",
+    argsSchema: {
+      business_type: z23.string().optional().describe("Business type, e.g. 'fashion' or 'coffee shop'."),
+      goal: z23.string().optional().describe("Primary loyalty goal, e.g. 'increase repeat purchases'.")
+    }
+  }, ({ business_type, goal }) => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: [
+            `Help me set up a loyalty program${business_type ? ` for a ${business_type} business` : ""}${goal ? ` with the goal of ${goal}` : ""}. Follow this workflow exactly:`,
+            "",
+            "1. Read the current state first: use joy_get_loyalty_overview and the earning, redemption, and tier read tools. Never create or change anything before knowing what already exists.",
+            "2. Propose the smallest useful program set, then get my confirmation item by item before preparing each change.",
+            "3. For each approved configuration change, call the relevant joy_configure_* tool in DRY-RUN mode first, show me the diff, and wait for my approval.",
+            "4. Only after that approval, call the same tool with apply: true \u2014 one tool at a time. Never batch applies in one turn.",
+            "5. Close by listing exactly what changed and what MCP cannot do: widget branding, launching or relaunching tiers, and deleting anything."
+          ].join("\n")
+        }
+      }
+    ]
+  }));
+  server.registerPrompt("apply_brand_to_widget", {
+    title: "Apply storefront branding to a widget draft",
+    description: "Guided widget-branding workflow: scan the storefront, explain the detected design, get approval, and save the approved changes to the V4 draft for the merchant to review and publish manually.",
+    argsSchema: {
+      preferences: z23.string().optional().describe("Optional brand preferences or constraints, e.g. 'keep the current heading font' or 'use a softer button color'.")
+    }
+  }, ({ preferences }) => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: [
+            `Help me apply my storefront brand to the loyalty widget${preferences ? ` while following these preferences: ${preferences}` : ""}. Follow this workflow exactly:`,
+            "",
+            "1. Run joy_scan_brand_design. If it reports that the storefront is password-protected, stop and ask me to temporarily disable the password before trying again. If the scan fails, do not invent colors or fonts.",
+            "2. Describe the detected colors, fonts, and button treatment in plain language. Make clear that they are estimates derived from a storefront screenshot and that you cannot visually judge the finished widget.",
+            "3. Propose the smallest useful set of branding changes and wait for my confirmation before preparing them.",
+            "4. Run joy_configure_widget_draft in DRY-RUN mode first, show me the diff, and wait for my approval. Only after that approval, call it again with apply: true.",
+            "5. State the boundary plainly: joy_configure_widget_draft writes only the V4 draft, never the live widget version. The storefront remains unchanged, and publishing is a manual human step that I must complete in the Joy admin after reviewing the draft.",
+            "",
+            "Do not claim that you published, can publish, or visually verified the widget."
+          ].join("\n")
+        }
+      }
+    ]
+  }));
+  server.registerPrompt("set_up_storefront_widget", {
+    title: "Set up the storefront loyalty widget",
+    description: "Guided theme-setup workflow: audit the live theme, explain each missing Joy embed or block, and hand the merchant server-provided deep links to finish setup manually.",
+    argsSchema: {
+      focus: z23.string().optional().describe("Optional setup focus, e.g. 'loyalty widget', 'points calculator', or 'loyalty page'.")
+    }
+  }, ({ focus }) => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: [
+            `Help me set up Joy on my storefront${focus ? `, focusing on ${focus}` : ""}. Follow this workflow exactly:`,
+            "",
+            "1. Run joy_check_theme_setup against the live theme. If storefront password protection is enabled, warn me that the result cannot be visually verified while the password is active.",
+            "2. For every inactive or missing embed or block, explain what it does for the storefront before giving me its deep link. Copy each link verbatim from joy_check_theme_setup; never construct one yourself.",
+            "3. You cannot install, enable, or save a theme app embed or block for me. Ask me to open each deep link, enable or add the item, click Save in the Shopify theme editor, and then return here.",
+            "4. After I confirm that I saved the theme, run joy_check_theme_setup again and report only what the second audit verifies. Do not claim success from my confirmation alone.",
+            "5. Keep widget publishing separate from theme setup: joy_configure_widget_draft, if used in a separate branding workflow, writes only the V4 draft and never the live widget version. Publishing remains a manual human step in the Joy admin.",
+            "",
+            "Do not claim that you installed a theme embed or published a widget version."
+          ].join("\n")
+        }
+      }
+    ]
+  }));
+}
+
+// ../mcp-core/build/registry.js
+function registerAllTools(server, ctx) {
+  registerOverviewTools(server, ctx);
+  registerAnalyticsTools(server, ctx);
+  registerMemberTools(server, ctx);
+  registerTierTools(server, ctx);
   registerProgramTools(server, ctx);
   registerReferralTools(server, ctx);
   registerRetentionTools(server, ctx);
@@ -1920,14 +5296,34 @@ function registerAllTools(server, ctx) {
   registerOrderExplainTools(server, ctx);
   registerActivityAuditTools(server, ctx);
   registerTierUpgradeTools(server, ctx);
+  registerLoyaltyPageTools(server, ctx);
+  registerLoyaltyPageTextTools(server, ctx);
+  registerThemeSetupTools(server, ctx);
+  registerBrandingReadTools(server, ctx);
+  registerWidgetFieldReadTools(server, ctx);
+  registerRedeemInCartReadTools(server, ctx);
   if (ctx.config.writesEnabled) {
     registerPointWriteTools(server, ctx);
     registerTierWriteTools(server, ctx);
     registerRewardWriteTools(server, ctx);
     registerReferralWriteTools(server, ctx);
     registerAnalyticsWriteTools(server, ctx);
+    registerLoyaltyPageWriteTools(server, ctx);
+    registerLoyaltyPageTextWriteTools(server, ctx);
     log.info("write tools ENABLED (award/deduct/adjust/redeem/set-tier/refund-coupon/create-referral-invite/enable-analytics-v2). Requires the deployed REST v2 write-path (reason/source/Idempotency-Key support) \u2014 against an older backend, reason/source are silently dropped and idempotency is not enforced.");
   }
+  if (ctx.config.configWritesEnabled) {
+    registerProgramConfigTools(server, ctx);
+    registerTierConfigTools(server, ctx);
+    registerShopConfigTools(server, ctx);
+    registerReferralConfigTools(server, ctx);
+    registerBrandingWriteTools(server, ctx);
+    registerWidgetFieldWriteTools(server, ctx);
+    registerReferralBrandingWriteTools(server, ctx);
+    registerRedeemInCartWriteTools(server, ctx);
+    registerImageUploadTools(server, ctx);
+    log.info("CONFIG write tools ENABLED (configure earning/redemption/referral program, tier, tier reward, tier settings, shop settings, referral widget, add translation language). These change behaviour for every customer at once and every one of them previews by default \u2014 an apply requires a second call. No backend audit trail records who changed configuration or why, and the endpoints accept no Idempotency-Key, so a repeated create makes a second live record.");
+  }
 }
 
 // src/index.ts