@joy-loyalty/mcp 0.3.8 → 0.4.0

package/build/index.js

@@ -255,6 +255,9 @@ 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
@@ -273,55 +276,124 @@ 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: `${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.`
-          }
-        ]
+        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);
   });
   const registration = {
     title: spec.title,
-    description: spec.description,
+    description: ctx.store ? storeDescriptionPrefix(ctx.store) + spec.description : spec.description,
     annotations: {
       readOnlyHint: false,
       destructiveHint: spec.destructiveHint,
@@ -330,31 +402,34 @@ function registerConfigWriteTool(server, ctx, spec) {
     }
   };
   if (spec.strictArguments) {
-    const inputSchema = z.object(spec.inputSchema).strict();
+    const inputSchema = z.object(withStoreArg(spec.inputSchema, strictStore)).strict();
     server.registerTool(spec.name, { ...registration, inputSchema }, callback);
     return;
   }
-  server.registerTool(spec.name, { ...registration, inputSchema: spec.inputSchema }, callback);
+  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,
@@ -514,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.',
@@ -526,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.",
@@ -554,7 +629,7 @@ 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.',
@@ -615,7 +690,7 @@ 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.',
@@ -652,7 +727,7 @@ 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?".`,
@@ -708,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: 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.";
@@ -732,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))
+      });
     }
   });
 }
@@ -788,6 +914,9 @@ var EARNING_KEYS = [
   "rateMoney",
   "earnPoint",
   "earnPointsTiers",
+  "isAppliedVipTier",
+  "appliedPlaceOrderTo",
+  "skipEarnPointGuest",
   "conditions",
   "typeMilestone",
   "milestones",
@@ -795,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",
@@ -821,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");
@@ -835,10 +1008,10 @@ 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.',
@@ -1113,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.',
@@ -1135,7 +1308,7 @@ 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.",
@@ -1152,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.",
@@ -1211,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.',
@@ -1379,7 +1552,7 @@ 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,
@@ -1407,7 +1580,7 @@ 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.",
@@ -1427,7 +1600,7 @@ ${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,
@@ -1454,7 +1627,7 @@ ${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.`,
@@ -1695,7 +1868,7 @@ function registerPointWriteTools(server, ctx) {
     inputSchema: {
       ...memberIdentifierSchema,
       program_id: z7.string().describe("Redemption program ID (from joy_list_redemption_rules)."),
-      redeem_points: z7.number().int().positive().describe("Points to spend on this redemption.")
+      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,
@@ -1717,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
       });
     }
@@ -1798,7 +1974,7 @@ 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.',
@@ -1876,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.`,
@@ -1917,7 +2093,7 @@ 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.",
@@ -2004,7 +2180,7 @@ 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".',
@@ -2061,7 +2237,7 @@ 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.',
@@ -2087,8 +2263,152 @@ function registerTierUpgradeTools(server, ctx) {
   });
 }
 
-// ../mcp-core/build/tools/programsWrite.js
+// ../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);
+    }
+  });
+}
+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.";
+      }
+      const published = result?.published ?? false;
+      const warnings2 = result?.warnings ?? [];
+      return summaryWithJson(summarizeAppliedChanges(applied2, published, warnings2), {
+        applied: applied2,
+        published,
+        ...warnings2.length ? { warnings: warnings2 } : {}
+      });
+    }
+  });
+  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 });
+    }
+  });
+}
+
+// ../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"
@@ -2167,7 +2487,8 @@ var EARNING_FIELDS = [
   "extraPointsForVideos",
   "isAppliedVipTier",
   "earnPointsTiers",
-  "appliedPlaceOrderTo"
+  "appliedPlaceOrderTo",
+  "skipEarnPointGuest"
 ];
 var REDEMPTION_FIELDS = [
   "event",
@@ -2484,45 +2805,45 @@ function isProgramChangeNoop(current, prepared) {
   return diffFields(current, prepared.body).length === 0;
 }
 var programConfigInputSchema = {
-  program_id: z13.string().min(1).optional().describe("Existing Joy program ID. Omit to create a new program."),
-  event: z13.string().optional().describe("Program event. Required for create; optional for update."),
-  title: z13.string().min(1).optional().describe("Customer-facing program title."),
-  status: z13.boolean().optional().describe("Set false to disable this rule instead of deleting it."),
-  priority: z13.number().int().optional().describe("Optional program priority."),
-  start_date: z13.string().optional().describe("Optional ISO start date."),
-  end_date: z13.string().optional().describe("Optional ISO end date."),
-  earn_by: z13.enum(["price", "fixed_order", "quantity", "order"]).optional(),
-  rate_money: z13.number().optional(),
-  rate_item: z13.number().optional(),
-  earn_point: z13.number().optional(),
-  date_format: z13.enum(["MM/DD", "DD/MM", "MM/DD/YYYY", "DD/MM/YYYY", "YYYY/MM/DD"]).optional(),
-  type_reward_timing: z13.enum(["exact_birthday", "begin_of_month", "around_birthday"]).optional(),
-  limit_unit: z13.string().optional(),
-  limit_interval: z13.number().int().positive().optional(),
-  url_account: z13.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: z13.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: z13.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: z13.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: z13.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: z13.number().int().positive().optional(),
-  earn_amount: z13.number().optional(),
-  shipping_discount_type: z13.enum(["percentage", "fixedAmount"]).optional(),
-  shipping_discount_amount: z13.number().optional(),
-  applied_to: z13.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: z13.array(z13.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: z13.array(z13.unknown()).optional(),
-  applied_collection_ids: z13.array(z13.string()).optional().describe("free_gift with applied_to specific or exclude_collection only \u2014 merchant-provided collection IDs."),
-  collection_quantity: z13.number().int().positive().optional().describe("Required for collection-based free_gift rules (applied_to specific or exclude_collection)."),
-  product_url: z13.array(z13.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: z13.enum(["all", "vip-tier", "member_and_guest"]).optional().describe(`place_order only \u2014 the admin's "Who to reward" setting. Leave unset: enabling per-tier earning sets 'vip-tier' automatically, which legacy place_order programs REQUIRE (they predate isEventPlaceOrderV2 and ignore is_applied_vip_tier).`),
-  is_applied_vip_tier: z13.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: z13.record(z13.object({
-    earn_point: z13.number().optional().describe("Points this tier earns, replacing the flat earn_point."),
-    rate_money: z13.number().optional().describe("place_order only: money amount that earns earn_point for this tier."),
-    type_earn: z13.enum(["point", "store_credit"]).optional()
+  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: z13.string().min(3).describe("Why the merchant wants this configuration change."),
-  apply: z13.boolean().optional().describe("Set true only after reviewing this tool's dry-run preview.")
+  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) {
@@ -2531,9 +2852,7 @@ function placeOrderVipTierPatch(event, args) {
     return {};
   if (!PLACE_ORDER_EVENTS.has(String(event)))
     return {};
-  if (args.applied_place_order_to)
-    return {};
-  return { appliedPlaceOrderTo: "vip-tier" };
+  return { appliedPlaceOrderTo: "vip-tier", skipEarnPointGuest: true };
 }
 function toIntegerRatio(earnPoint, rateMoney) {
   const isWhole = (value) => Math.abs(value - Math.round(value)) < 1e-9;
@@ -2626,11 +2945,14 @@ async function executeProgramChange(ctx, kind, args, toChange) {
     if (stop2)
       return stop2;
     await ctx.api.mutateData(`/programs/${prepared.programId}`, { method: "PUT", body: prepared.body });
-    if (resolvedArgs.earn_points_tiers) {
+    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.`;
   }
@@ -2649,7 +2971,7 @@ 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. 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.",
+    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)
@@ -2665,8 +2987,10 @@ function registerProgramConfigTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/tiersWrite.js
-import { z as z14 } from "zod";
+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",
@@ -2728,6 +3052,12 @@ var TIER_REWARD_FIELDS = [
 ];
 var TIER_PERK_FIELDS = ["contentPerk"];
 var TIER_SETTINGS_FIELDS = [
+  "entryMethod",
+  "startDate",
+  "prefix",
+  "isUsePrefixDiscountCode",
+  "showTierPointSettings",
+  "allowGiveEntryRewardAgain",
   "useDemotionTier",
   "typeDemotion",
   "downgradeAfter",
@@ -2746,7 +3076,7 @@ var TIER_SETTINGS_FIELDS = [
   "notificationDowngradeBefore",
   "notificationDowngradeBeforeUnit"
 ];
-var rewardEventSchema = z14.enum([
+var rewardEventSchema = z16.enum([
   "amount_discount",
   "percentage_discount",
   "free_shipping",
@@ -2754,95 +3084,101 @@ var rewardEventSchema = z14.enum([
   "bonus_point",
   "buy_x_get_y"
 ]);
-var finiteNumber = () => z14.number().finite();
-var tierRewardInputSchema = z14.object({
+var finiteNumber = () => z16.number().finite();
+var tierRewardInputSchema = z16.object({
   event: rewardEventSchema.describe("Required reward kind."),
-  title: z14.string().min(1).optional(),
-  type: z14.enum(["tier_spending", "tier_privileges", "pre_tier_reward"]).optional(),
-  status: z14.boolean().optional(),
+  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: z14.string().optional(),
-  redeem_type: z14.string().optional(),
-  applied_to: z14.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: z14.enum(["none", "min_amount", "min_quantity"]).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: z14.array(z14.unknown()).optional(),
-  specific_collections: z14.array(z14.unknown()).optional(),
-  applied_collection_ids: z14.array(z14.unknown()).optional(),
-  combined_with: z14.array(z14.enum(["orderDiscounts", "shippingDiscounts", "productDiscounts"])).optional(),
-  has_limit_shipping: z14.boolean().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: z14.enum(["day", "month"]).optional(),
-  is_refund_coupon: z14.boolean().optional(),
+  expired_unit: z16.enum(["day", "month"]).optional(),
+  is_refund_coupon: z16.boolean().optional(),
   priority: finiteNumber().optional(),
-  show_loyalty_page: z14.boolean().optional(),
-  perk_title_language: z14.record(z14.unknown()).optional(),
-  reward_product_selection_mode: z14.string().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: z14.string().min(1).optional().describe("Existing tier ID. Omit to create a tier."),
-  name: z14.string().min(1).optional(),
+  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: z14.string().optional(),
-  icon_custom: z14.string().optional(),
-  bg_image: z14.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: z14.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: z14.string().optional(),
-  is_exclusive_tier: z14.boolean().optional(),
-  hide_default_tier: z14.boolean().optional(),
-  text_color: z14.string().optional(),
-  progress_bar_color: z14.string().optional(),
-  box_bg_color: z14.string().optional(),
-  box_text_color: z14.string().optional(),
-  bg_card_color: z14.string().optional(),
+  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: z14.string().optional(),
-  bg_type: z14.string().optional(),
-  tier_names_language: z14.record(z14.unknown()).optional(),
-  rewards: z14.array(tierRewardInputSchema).optional().describe("Optional rewards to create with a NEW tier in this one configuration write."),
-  reason: z14.string().min(3).describe("Why the merchant wants this tier configuration."),
-  apply: z14.boolean().optional().describe("Set true only after the dry-run preview is approved.")
+  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: z14.string().min(1).describe("Tier ID from joy_list_tiers."),
-  reward_id: z14.string().min(1).optional().describe("Existing reward ID. Omit to create."),
+  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: z14.array(z14.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: z14.string().min(3).describe("Why the merchant wants this reward configuration."),
-  apply: z14.boolean().optional().describe("Set true only after the dry-run preview is approved.")
+  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 = {
-  use_demotion_tier: z14.boolean().optional(),
-  type_demotion: z14.enum(["downgrade_tier", "reset_tier"]).optional(),
-  downgrade_after: z14.number().int().positive().optional(),
-  downgrade_after_unit: z14.enum(["day", "month", "year"]).optional(),
-  use_reset_tier: z14.boolean().optional(),
-  reset_after: z14.number().int().positive().optional(),
-  reset_after_unit: z14.enum(["day", "month", "year"]).optional(),
-  reset_frequency: z14.enum(["monthly", "quarterly", "half_yearly", "yearly", "custom"]).optional(),
-  reset_interval_value: z14.number().int().positive().optional(),
-  reset_interval_unit: z14.enum(["day", "month", "year"]).optional(),
-  reset_start_date: z14.string().min(1).optional(),
-  month_reset_tier: z14.number().int().min(1).max(12).optional(),
-  day_reset_tier: z14.number().int().min(1).max(31).optional(),
-  is_sync_tags_customer_tier: z14.boolean().optional(),
-  customer_tier_tag_prefix: z14.string().optional(),
-  notification_downgrade_before: z14.number().int().positive().optional(),
-  notification_downgrade_before_unit: z14.enum(["day", "month"]).optional(),
-  reason: z14.string().min(3).describe("Why the merchant wants these tier settings."),
-  apply: z14.boolean().optional().describe("Set true only after the dry-run preview is approved.")
+  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: z14.string().min(1).describe("Tier ID from joy_list_tiers."),
-  perks: z14.array(z14.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: z14.string().min(3).describe("Why the merchant wants to replace this tier perk list."),
-  apply: z14.boolean().optional().describe("Set true only after the dry-run preview is approved.")
+  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")
@@ -3138,6 +3474,12 @@ async function configureTierPerks(ctx, args) {
 }
 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),
@@ -3163,6 +3505,11 @@ function touchesResetSchedule(body) {
 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",
@@ -3172,7 +3519,8 @@ function buildTierSettingsPreview(current, args, now = /* @__PURE__ */ new Date(
         target: "tier settings",
         reason: args.reason,
         changes,
-        dropped: droppedFields(body, TIER_SETTINGS_FIELDS)
+        dropped: droppedFields(body, TIER_SETTINGS_FIELDS),
+        warnings: entryMethodWarning
       })
     };
   }
@@ -3202,7 +3550,7 @@ function buildTierSettingsPreview(current, args, now = /* @__PURE__ */ new Date(
       reason: args.reason,
       changes,
       dropped: droppedFields(body, TIER_SETTINGS_FIELDS),
-      warnings: [scheduleWarning]
+      warnings: entryMethodWarning ? [scheduleWarning, ...entryMethodWarning] : [scheduleWarning]
     })
   };
 }
@@ -3220,8 +3568,19 @@ async function configureTierSettings(ctx, args) {
       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)}.` : "";
-    return summaryWithJson(`Updated tier settings.${schedule}`, compact(updated, [...TIER_SETTINGS_FIELDS, "id"]));
+    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);
   }
@@ -3308,8 +3667,8 @@ function registerTierConfigTools(server, ctx) {
   });
   registerConfigWriteTool(server, ctx, {
     name: "joy_configure_tier_settings",
-    title: "Configure VIP tier demotion and reset settings",
-    description: "CONFIGURATION WRITE \u2014 changes tier demotion, reset, customer-tag, and downgrade-notification settings. Any reset-schedule change previews the current and projected scheduleResetTierAt before it may apply, because that daily-cron anchor affects every tier member.",
+    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)
@@ -3324,6 +3683,15 @@ function isData(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)";
@@ -3419,7 +3787,7 @@ function isAfterOrEqual(candidate, cursor, inclusive) {
 }
 
 // ../mcp-core/build/tools/shopConfig.js
-import { z as z15 } from "zod";
+import { z as z17 } from "zod";
 var SHOP_SETTINGS_FIELDS = [
   "primaryLanguageInApp",
   "dateFormat",
@@ -3562,20 +3930,20 @@ function registerShopConfigTools(server, ctx) {
     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: z15.enum(["en", "en-US", "fr", "es", "de", "it", "ja", "id", "zh-CN"]).optional(),
-      date_format: z15.enum(["MM/DD/YYYY", "DD/MM/YYYY", "YYYY/MM/DD", "YYYY-MM-DD"]).optional(),
-      date_format_for_activity: z15.enum(["HH:mm", "hh:mm A"]).optional(),
-      point_position: z15.enum(["before", "after"]).optional(),
-      customer_apply_discount_behavior: z15.enum(["stay_current", "go_to_cart", "open_cart_drawer"]).optional(),
-      customer_redeem_coupon_behavior: z15.enum(["auto_apply", "save_for_later"]).optional(),
-      customer_free_gift_behavior: z15.enum(["manual_add_to_cart", "auto_add_to_cart"]).optional(),
-      status_for_review: z15.enum(["pending", "approveAuto"]).optional(),
-      earn_by_order_status: z15.enum(["financial_status", "fulfillment_status"]).optional(),
-      enable_global_earning_limit: z15.boolean().optional(),
-      global_earning_limit_timeframe: z15.enum(["yearly", "monthly", "rolling"]).optional(),
-      global_earning_limit_rolling_days: z15.number().int().min(1).max(365).optional(),
-      reason: z15.string().min(3).describe("Why the merchant wants these shop-wide settings changed."),
-      apply: z15.boolean().optional().describe("Set true only after the merchant has approved the dry-run preview.")
+      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,
@@ -3597,10 +3965,10 @@ function registerShopConfigTools(server, ctx) {
     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: z15.enum(TRANSLATION_LOCALES),
-      additional_language: z15.enum(TRANSLATION_LOCALES),
-      reason: z15.string().min(3).describe("Why the merchant wants this storefront language added."),
-      apply: z15.boolean().optional().describe("Set true only after the merchant has approved the dry-run preview.")
+      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,
@@ -3619,7 +3987,7 @@ function registerShopConfigTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/brandingWrite.js
-import { z as z16 } from "zod";
+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 = {
@@ -3662,26 +4030,26 @@ 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: z16.enum(["v3", "v4"]).describe("Widget version to change. A live target is accepted only when this is the shop\u2019s currently live version."),
-  target: z16.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: z16.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: z16.string().url().startsWith("https://").optional().describe("Optional public HTTPS storefront URL to scan when apply_scan is true."),
-  storefront_password: z16.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: z16.boolean().optional().describe("When apply_scan is true, also replace detected logo and card imagery. Defaults to false."),
-  color_overrides: z16.record(z16.string()).optional().describe(`Optional hex overrides for supported V4 color roles: ${COLOR_ROLES.join(", ")}.`),
-  design_overrides: z16.object({
-    corner_radius: z16.enum(CORNER_RADIUS_VALUES).optional().describe("Corner style. radiusNone is square/not rounded; radiusExtra is the most rounded."),
-    button_style: z16.enum(BUTTON_STYLE_VALUES).optional().describe("store matches the storefront, custom uses the widget\u2019s own button colours."),
-    content_style: z16.enum(CONTENT_STYLE_VALUES).optional().describe("text_only removes the icons beside earn/redeem rows; icons_and_text shows them."),
-    display_type: z16.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.")
+  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: z16.object({ heading: z16.string().min(1).optional(), body: z16.string().min(1).optional() }).optional().describe("Optional heading and body font overrides."),
-  reason: z16.string().min(3).describe("Why the merchant wants this widget draft."),
-  apply: z16.boolean().optional().describe("Omit or set false for a dry run. Set true only after the merchant approves the preview.")
+  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: z16.string().url().startsWith("https://").optional().describe("Optional public HTTPS storefront URL. Omit it to scan this shop\u2019s own storefront."),
-  storefront_password: z16.string().min(1).optional().describe("Optional storefront password for a gated shop. It is sent only in the POST body and is never returned.")
+  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);
@@ -3934,7 +4302,7 @@ async function putWidgetScan(ctx, args) {
   }
 }
 function registerBrandingReadTools(server, ctx) {
-  registerReadTool(server, {
+  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.",
@@ -4000,13 +4368,13 @@ No write was sent because this would be a no-op.`, args.storefront_password);
             throw new JoyApiError("server", `${failureGuidance} These fields were unchanged after the required read-back: ${missing.join(", ")}.`);
           }
         }
-        const confirmed = [
+        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 ${confirmed} 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 ${confirmed} by reading it back. The agent cannot see the rendered result; review it in Joy admin.`;
+        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 })) } : {}
@@ -4022,18 +4390,36 @@ ${WIDGET_DRAFT_SAVED_MESSAGE}` : ""}`;
 
 // ../mcp-core/build/tools/widgetFields.js
 import { isDeepStrictEqual } from "node:util";
-import { z as z17 } from "zod";
+import { z as z19 } from "zod";
 var fieldsPath = "/shop/branding/widget/fields";
-var versionSchema = z17.literal("v4").default("v4").describe("Widget version. Field discovery currently supports V4.");
+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: z17.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: z17.array(z17.object({
-    path: z17.string().min(1),
-    value: z17.unknown().refine((value) => value !== void 0, "Each field must include a value; use null to clear it.")
+  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: z17.string().min(3).describe("Why the merchant wants these widget changes."),
-  apply: z17.boolean().optional().describe("Omit or set false for a dry run. Set true only after the merchant approves the preview.")
+  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) {
@@ -4047,14 +4433,14 @@ async function getWidgetFields(ctx, version2) {
   return data.fields;
 }
 function registerWidgetFieldReadTools(server, ctx) {
-  registerReadTool(server, {
+  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: z17.string().optional().describe("Return only this group. Omit to get the group index first."),
-      search: z17.string().optional().describe('Return only fields whose label or path contains this text, e.g. "corner" or "launcher".')
+      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);
@@ -4089,13 +4475,14 @@ 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. 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.",
+    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 changes = args.fields.map(({ path, value }) => ({
+      const fields = expandLauncherHideFields(args.fields, current);
+      const changes = fields.map(({ path, value }) => ({
         path,
         from: current.find((field) => field.path === path)?.current,
         to: value
@@ -4110,7 +4497,7 @@ The server will validate every requested path and value when applied; this previ
         result = await ctx.api.mutateData(fieldsPath, {
           method: "PUT",
           query: { version: args.version, target: args.target },
-          body: { fields: args.fields }
+          body: { fields }
         });
       } catch (error) {
         throw brandingErrorGuidance(error, "draft", args.target) ?? error;
@@ -4123,23 +4510,23 @@ The server will validate every requested path and value when applied; this previ
         readBackFailure = error instanceof Error ? error.message : String(error);
       }
       const refusedPaths = new Set(result.refused.map((field) => field.path));
-      const applied = [];
+      const applied2 = [];
       const unconfirmed = [];
-      for (const field of args.fields) {
+      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)) {
-          applied.push({ path: field.path, value: 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: ${applied.length} confirmed by read-back, ${result.refused.length} refused, ${unconfirmed.length} unconfirmed.`;
+      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 }, null, 1)}`;
-      const consequence = args.target === "live" ? "WARNING \u2014 saving this changes the storefront immediately. There is NO publish step and NO undo." : applied.length > 0 ? WIDGET_DRAFT_SAVED_MESSAGE : "Review the V4 draft in Joy admin.";
+${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}` : ""}`;
@@ -4153,7 +4540,7 @@ Do not report refused or unconfirmed fields as saved. Inspect the current widget
 }
 
 // ../mcp-core/build/tools/referralBrandingWrite.js
-import { z as z18 } from "zod";
+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",
@@ -4169,24 +4556,24 @@ var REFERRAL_WIDGET_ARGUMENTS = {
   frequency_show_popup: "frequencyShowPopup",
   is_show_subscribe_newsletter: "isShowSubscribeNewsletter"
 };
-var hexColor = (description) => z18.string().refine(isHexColor, { message: "Must be a 3- or 6-digit hex color such as #123 or #112233." }).optional().describe(description);
+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: z18.enum(["template", "custom-solid", "custom-gradient"]).optional().describe("Color mode. This endpoint can select an existing template or gradient, but cannot define gradient stops."),
+  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: z18.string().trim().min(1).optional().describe("Referral-widget font family, for example Open+Sans."),
-  type_show_popup: z18.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: z18.boolean().optional().describe("Whether an automatically shown referral popup closes itself."),
-  closing_pop_up_time: z18.number().int().min(1).optional().describe("Auto-close delay in seconds; must be a positive integer."),
-  frequency_show_popup: z18.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: z18.boolean().optional().describe("Show the newsletter subscription option in the referral popup."),
-  reason: z18.string().min(3).describe("Why the merchant wants the live referral widget changed."),
-  apply: z18.boolean().optional().describe("Set true only after the merchant has approved the dry-run preview.")
+  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 = z18.object(referralWidgetInputShape).strict();
+var referralWidgetArgsSchema = z20.object(referralWidgetInputShape).strict();
 function parseReferralWidgetArgs(input) {
   const parsed = referralWidgetArgsSchema.safeParse(input);
   if (parsed.success)
@@ -4252,6 +4639,369 @@ function registerReferralBrandingWriteTools(server, ctx) {
   });
 }
 
+// ../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");
@@ -4279,6 +5029,8 @@ function formatThemeSetup(themeSetup) {
     });
   }
   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.",
@@ -4296,7 +5048,7 @@ function formatThemeSetup(themeSetup) {
   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, {
+  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.",
@@ -4309,14 +5061,14 @@ function registerThemeSetupTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/imageUpload.js
-import { z as z19 } from "zod";
+import { z as z22 } from "zod";
 var imageUploadInputSchema = {
-  source_url: z19.string().url().optional().describe("Public URL of an already hosted image. Provide exactly one of source_url or data_url."),
-  data_url: z19.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: z19.string().min(1).max(200).optional().describe("Filename to use for the uploaded image."),
-  alt: z19.string().max(512).optional().describe("Merchant-provided alternative text for the image."),
-  reason: z19.string().min(3).describe("Why the merchant wants this image uploaded."),
-  apply: z19.boolean().optional().describe("Omit or set false for a dry run. Set true only after the merchant approves the preview.")
+  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))
@@ -4336,7 +5088,7 @@ 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). 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.",
+    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,
@@ -4361,14 +5113,14 @@ function registerImageUploadTools(server, ctx) {
 }
 
 // ../mcp-core/build/prompts.js
-import { z as z20 } from "zod";
+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: z20.string().describe("Customer's email address"),
-      order_number: z20.string().optional().describe("Order name/number the customer says earned nothing, e.g. #1234")
+      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: [
@@ -4395,7 +5147,7 @@ function registerAllPrompts(server) {
     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: z20.string().optional().describe("Reporting period, e.g. 'last 30 days', 'last month', 'this quarter'. Defaults to last 30 days.")
+      period: z23.string().optional().describe("Reporting period, e.g. 'last 30 days', 'last month', 'this quarter'. Defaults to last 30 days.")
     }
   }, ({ period }) => ({
     messages: [
@@ -4426,7 +5178,7 @@ function registerAllPrompts(server) {
     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: z20.string().describe("Email of the member to investigate")
+      email: z23.string().describe("Email of the member to investigate")
     }
   }, ({ email }) => ({
     messages: [
@@ -4453,8 +5205,8 @@ function registerAllPrompts(server) {
     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: z20.string().optional().describe("Business type, e.g. 'fashion' or 'coffee shop'."),
-      goal: z20.string().optional().describe("Primary loyalty goal, e.g. 'increase repeat purchases'.")
+      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: [
@@ -4479,7 +5231,7 @@ function registerAllPrompts(server) {
     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: z20.string().optional().describe("Optional brand preferences or constraints, e.g. 'keep the current heading font' or 'use a softer button color'.")
+      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: [
@@ -4506,7 +5258,7 @@ function registerAllPrompts(server) {
     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: z20.string().optional().describe("Optional setup focus, e.g. 'loyalty widget', 'points calculator', or 'loyalty page'.")
+      focus: z23.string().optional().describe("Optional setup focus, e.g. 'loyalty widget', 'points calculator', or 'loyalty page'.")
     }
   }, ({ focus }) => ({
     messages: [
@@ -4544,15 +5296,20 @@ 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) {
@@ -4563,6 +5320,7 @@ function registerAllTools(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.");
   }