@joy-loyalty/mcp 0.3.8 → 0.5.0

package/build/index.js

@@ -2,6 +2,7 @@
 
 // src/index.ts
 import { createRequire } from "node:module";
+import { randomUUID as randomUUID3 } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
@@ -67,17 +68,368 @@ function loadConfig(env = process.env) {
     deductDryRunThreshold
   };
 }
+var DEFAULT_TELEMETRY_MODE = "headers";
+function telemetryMode(env = process.env) {
+  const mode = (env.JOY_MCP_TELEMETRY ?? "").trim().toLowerCase();
+  const doNotTrack = (env.DO_NOT_TRACK ?? "").trim().toLowerCase();
+  if (["1", "true"].includes(doNotTrack) || ["off", "false", "0"].includes(mode)) return "off";
+  if (mode === "on") return "full";
+  return DEFAULT_TELEMETRY_MODE;
+}
+
+// ../mcp-core/build/telemetry/callContext.js
+import { AsyncLocalStorage } from "node:async_hooks";
+
+// ../mcp-core/build/logger.js
+var log = {
+  info(message) {
+    console.error(`[joy-mcp] ${message}`);
+  },
+  error(message) {
+    console.error(`[joy-mcp:error] ${message}`);
+  }
+};
+
+// ../mcp-core/build/telemetry/schema.js
+var SCHEMA_VERSION = 1;
+var UUID = "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$";
+var SHOP_ID = "^[A-Za-z0-9]{1,40}$";
+var SHOP_DOMAIN = "^[a-z0-9][a-z0-9.-]{0,254}$";
+var PLAN = "^[A-Za-z0-9_. -]{1,64}$";
+var VERSION = "^[A-Za-z0-9._+-]{1,64}$";
+var TOOL = "^[a-z0-9_]{1,64}$";
+var ERROR_CODE = "^[A-Za-z][A-Za-z0-9_]{0,63}$";
+var CLIENT_NAME = "^[\\x20-\\x7E]{1,64}$";
+var CLIENT_VERSION = "^[A-Za-z0-9._+-]{1,32}$";
+var CAPABILITIES = "^[a-z][a-zA-Z0-9_]{0,31}(,[a-z][a-zA-Z0-9_]{0,31}){0,9}$";
+var MAX_MS = 36e5;
+var MCP = ["remote", "stdio"];
+var REMOTE = ["remote"];
+var STDIO = ["stdio"];
+var BACKEND = ["backend"];
+var OUTCOMES = ["success", "tool_error", "rejected", "internal_error", "cancelled"];
+var ERROR_KINDS = [
+  // JoyApiError kinds (client/joyApi.ts ErrorKind)
+  "auth",
+  "plan_gate",
+  "forbidden",
+  "rate_limit",
+  "not_found",
+  "validation",
+  "conflict",
+  "server",
+  "timeout",
+  "network",
+  // handler / toolkit
+  "exception",
+  "store_mismatch",
+  "writes_disabled",
+  "config_writes_disabled",
+  // rejected before the handler ran
+  "invalid_input",
+  "tool_not_exposed",
+  "unknown_tool",
+  // recorder
+  "unclassified",
+  "jsonrpc_error",
+  "duplicate_request_id",
+  "client_cancelled",
+  "no_response"
+];
+function envelope(event, origins) {
+  return {
+    event: { type: "string", required: true, transports: origins, enum: [event] },
+    schema_version: { type: "integer", required: true, transports: origins, min: SCHEMA_VERSION, max: SCHEMA_VERSION },
+    event_id: { type: "string", required: true, transports: origins, pattern: UUID }
+  };
+}
+var MCP_IDENTITY = {
+  transport: { type: "string", required: true, transports: MCP, server_stamped: true, enum: ["remote", "stdio"] },
+  server_version: { type: "string", required: true, transports: MCP, pattern: VERSION },
+  shop_id: { type: "string", required: true, transports: MCP, server_stamped: true, pattern: SHOP_ID },
+  shop_domain: { type: "string", transports: MCP, server_stamped: true, pattern: SHOP_DOMAIN },
+  joy_plan: { type: "string", transports: MCP, server_stamped: true, pattern: PLAN },
+  shopify_plan: { type: "string", transports: MCP, server_stamped: true, pattern: PLAN },
+  auth_mode: { type: "string", required: true, transports: MCP, server_stamped: true, enum: ["oauth", "api_key", "private_bot"] },
+  access_scope: { type: "string", required: true, transports: MCP, server_stamped: true, enum: ["full", "read"] },
+  oauth_client_id: { type: "string", transports: REMOTE, pattern: "^[\\x21-\\x7E]{1,512}$" },
+  connection_id: { type: "string", transports: REMOTE, pattern: UUID },
+  user_id: { type: "string", transports: REMOTE, pattern: "^[A-Za-z0-9_-]{1,64}$" },
+  session_id: { type: "string", transports: STDIO, pattern: UUID },
+  connector_mode: { type: "string", transports: REMOTE, enum: ["soft", "strict"] }
+};
+var TELEMETRY_SCHEMA = {
+  schema_version: SCHEMA_VERSION,
+  ingest_events: ["mcp.tool_call", "mcp.session_start"],
+  forbidden_keys: [
+    "args",
+    "arguments",
+    "params",
+    "input",
+    "result",
+    "content",
+    "text",
+    "prompt",
+    "sql",
+    "query",
+    "message",
+    "severity",
+    "model_message",
+    "error_message",
+    "path",
+    "url",
+    "store_name",
+    "email",
+    "ip",
+    "user_agent",
+    "secret",
+    "secret_key",
+    "token",
+    "authorization"
+  ],
+  events: {
+    "mcp.tool_call": {
+      fields: {
+        ...envelope("mcp.tool_call", MCP),
+        ...MCP_IDENTITY,
+        mcp_client_name: { type: "string", transports: STDIO, pattern: CLIENT_NAME },
+        mcp_client_version: { type: "string", transports: STDIO, pattern: CLIENT_VERSION },
+        call_id: { type: "string", required: true, transports: MCP, pattern: UUID },
+        tool: { type: "string", required: true, transports: MCP, pattern: TOOL },
+        tool_kind: { type: "string", required: true, transports: MCP, enum: ["read", "write", "config_write", "unknown"] },
+        outcome: { type: "string", required: true, transports: MCP, enum: OUTCOMES },
+        error_kind: { type: "string", transports: MCP, enum: ERROR_KINDS },
+        error_code: { type: "string", transports: MCP, pattern: ERROR_CODE },
+        http_status: { type: "integer", transports: MCP, min: 100, max: 599 },
+        duration_ms: { type: "integer", required: true, transports: MCP, min: 0, max: MAX_MS },
+        pre_ms: { type: "integer", transports: REMOTE, min: 0, max: MAX_MS },
+        api_calls: { type: "integer", required: true, transports: MCP, min: 0, max: 1e4 },
+        api_ms: { type: "integer", required: true, transports: MCP, min: 0, max: MAX_MS },
+        result_bytes: { type: "integer", required: true, transports: MCP, min: 0, max: 1e9 }
+      }
+    },
+    "mcp.session_start": {
+      fields: {
+        ...envelope("mcp.session_start", MCP),
+        ...MCP_IDENTITY,
+        mcp_client_name: { type: "string", transports: MCP, pattern: CLIENT_NAME },
+        mcp_client_version: { type: "string", transports: MCP, pattern: CLIENT_VERSION },
+        protocol_version: { type: "string", transports: MCP, pattern: "^\\d{4}-\\d{2}-\\d{2}$" },
+        client_capabilities: { type: "string", transports: MCP, pattern: CAPABILITIES },
+        tools_exposed: { type: "integer", transports: MCP, min: 0, max: 1e4 }
+      }
+    },
+    "api.request": {
+      fields: {
+        ...envelope("api.request", BACKEND),
+        source: { type: "string", required: true, transports: BACKEND, enum: ["mcp", "direct_api", "private_bot", "internal"] },
+        call_id: { type: "string", transports: BACKEND, pattern: UUID },
+        tool: { type: "string", transports: BACKEND, pattern: TOOL },
+        transport: { type: "string", transports: BACKEND, enum: ["remote", "stdio"] },
+        server_version: { type: "string", transports: BACKEND, pattern: VERSION },
+        mcp_client_name: { type: "string", transports: BACKEND, pattern: CLIENT_NAME },
+        session_id: { type: "string", transports: BACKEND, pattern: UUID },
+        shop_verified: { type: "boolean", required: true, transports: BACKEND },
+        shop_id: { type: "string", transports: BACKEND, pattern: SHOP_ID },
+        claimed_shop_id: { type: "string", transports: BACKEND, pattern: SHOP_ID },
+        shop_domain: { type: "string", transports: BACKEND, pattern: SHOP_DOMAIN },
+        joy_plan: { type: "string", transports: BACKEND, pattern: PLAN },
+        shopify_plan: { type: "string", transports: BACKEND, pattern: PLAN },
+        auth_mode: { type: "string", transports: BACKEND, enum: ["api_key", "private_bot"] },
+        access_scope: { type: "string", transports: BACKEND, enum: ["full", "read"] },
+        access_policy: {
+          type: "string",
+          transports: BACKEND,
+          enum: ["plan_quota", "unlimited_plan", "manual_grant", "shop_override", "private_bot", "no_access"]
+        },
+        method: { type: "string", required: true, transports: BACKEND, enum: ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"] },
+        route: { type: "string", transports: BACKEND, pattern: "^/[A-Za-z0-9/:_.()*-]{0,199}$" },
+        http_status: { type: "integer", required: true, transports: BACKEND, min: 100, max: 599 },
+        error_code: { type: "string", transports: BACKEND, pattern: ERROR_CODE },
+        response_error: { type: "boolean", transports: BACKEND },
+        duration_ms: { type: "integer", required: true, transports: BACKEND, min: 0, max: MAX_MS },
+        bq_jobs: { type: "integer", transports: BACKEND, min: 0, max: 1e4 },
+        bq_bytes_processed: { type: "integer", transports: BACKEND, min: 0, max: 1e15 },
+        bq_bytes_billed_est: { type: "integer", transports: BACKEND, min: 0, max: 1e15 }
+      }
+    }
+  }
+};
+
+// ../mcp-core/build/telemetry/validate.js
+var patternCache = /* @__PURE__ */ new Map();
+function regexFor(pattern) {
+  let regex = patternCache.get(pattern);
+  if (!regex) {
+    regex = new RegExp(pattern);
+    patternCache.set(pattern, regex);
+  }
+  return regex;
+}
+function isValidValue(spec, value) {
+  if (spec.type === "boolean")
+    return typeof value === "boolean";
+  if (spec.type === "integer") {
+    if (typeof value !== "number" || !Number.isInteger(value))
+      return false;
+    if (spec.min !== void 0 && value < spec.min)
+      return false;
+    return spec.max === void 0 || value <= spec.max;
+  }
+  if (typeof value !== "string")
+    return false;
+  if (spec.maxLength !== void 0 && value.length > spec.maxLength)
+    return false;
+  if (spec.enum && !spec.enum.includes(value))
+    return false;
+  return !spec.pattern || regexFor(spec.pattern).test(value);
+}
+function own(table, key) {
+  return Object.prototype.hasOwnProperty.call(table, key) ? table[key] : void 0;
+}
+function isApplicable(spec, transport) {
+  return !transport || spec.transports.includes(transport);
+}
+function validateEvent(schema, event, options) {
+  const errors = [];
+  const cleaned = {};
+  if (!event || typeof event !== "object" || Array.isArray(event)) {
+    return { ok: false, event: cleaned, errors: ["not_an_object"] };
+  }
+  const record = event;
+  const spec = typeof record.event === "string" ? own(schema.events, record.event) : void 0;
+  if (!spec)
+    return { ok: false, event: cleaned, errors: ["unknown_event"] };
+  for (const key of schema.forbidden_keys) {
+    if (Object.prototype.hasOwnProperty.call(record, key))
+      errors.push(`forbidden:${key}`);
+  }
+  for (const [key, value] of Object.entries(record)) {
+    const field = own(spec.fields, key);
+    if (!field || !isApplicable(field, options.transport) || value === void 0)
+      continue;
+    if (isValidValue(field, value)) {
+      cleaned[key] = value;
+    } else {
+      errors.push(`invalid:${key}`);
+    }
+  }
+  for (const [key, field] of Object.entries(spec.fields)) {
+    if (!field.required || !isApplicable(field, options.transport))
+      continue;
+    if (options.mode === "client" && field.server_stamped)
+      continue;
+    if (!(key in cleaned) && !errors.includes(`invalid:${key}`))
+      errors.push(`missing:${key}`);
+  }
+  return { ok: errors.length === 0, event: cleaned, errors };
+}
+function sanitizeString(schema, eventName, field, value) {
+  const eventSpec = own(schema.events, eventName);
+  const spec = eventSpec ? own(eventSpec.fields, field) : void 0;
+  if (!spec || spec.type !== "string" || typeof value !== "string")
+    return void 0;
+  return isValidValue(spec, value) ? value : void 0;
+}
+
+// ../mcp-core/build/telemetry/callContext.js
+var als = new AsyncLocalStorage();
+var reported = /* @__PURE__ */ new Set();
+function reportOnce(message) {
+  if (reported.has(message))
+    return;
+  reported.add(message);
+  try {
+    log.error(message);
+  } catch {
+  }
+}
+function telemetrySafe(label, action) {
+  try {
+    return action();
+  } catch {
+    reportOnce(`Telemetry ${label} failed`);
+    return void 0;
+  }
+}
+function currentCall() {
+  return telemetrySafe("context", () => als.getStore());
+}
+function update(action) {
+  telemetrySafe("context", () => {
+    const record = currentCall();
+    if (record && !record.closed)
+      action(record);
+  });
+}
+function markEntered() {
+  update((record) => {
+    record.entered = true;
+  });
+}
+function setOutcome(value, kind) {
+  update((record) => {
+    record.outcome = value;
+    delete record.error_kind;
+    delete record.error_code;
+    delete record.http_status;
+    if (kind)
+      record.error_kind = kind;
+  });
+}
+function markSuccess() {
+  setOutcome("success");
+}
+function markRejected(kind) {
+  setOutcome("rejected", kind);
+}
+function markInternalError() {
+  setOutcome("internal_error", "exception");
+}
+function markToolError(error) {
+  update((record) => {
+    setOutcome("tool_error");
+    const kind = sanitizeString(TELEMETRY_SCHEMA, "mcp.tool_call", "error_kind", error.kind);
+    record.error_kind = kind ?? "unclassified";
+    const code = sanitizeString(TELEMETRY_SCHEMA, "mcp.tool_call", "error_code", error.serverCode);
+    if (code)
+      record.error_code = code;
+    const status = error.status;
+    if (typeof status === "number" && Number.isInteger(status) && status >= 100 && status <= 599) {
+      record.http_status = status;
+    }
+  });
+}
+function apiStart() {
+  update((record) => {
+    record.api_calls++;
+    if (record.api_inflight++ === 0)
+      record.api_busy_since = record.now();
+  });
+}
+function apiEnd() {
+  update((record) => {
+    if (record.api_inflight === 0)
+      return;
+    if (--record.api_inflight !== 0)
+      return;
+    record.api_ms_acc += Math.max(0, record.now() - (record.api_busy_since ?? record.now()));
+    delete record.api_busy_since;
+  });
+}
 
 // ../mcp-core/build/client/joyApi.js
 var JoyApiError = class extends Error {
   kind;
   modelMessage;
   status;
-  constructor(kind, modelMessage, status) {
+  serverCode;
+  constructor(kind, modelMessage, status, serverCode) {
     super(modelMessage);
     this.kind = kind;
     this.modelMessage = modelMessage;
     this.status = status;
+    this.serverCode = serverCode;
     this.name = "JoyApiError";
   }
 };
@@ -110,20 +462,20 @@ function extractServerCode(body) {
   }
   return void 0;
 }
-function classifyError(status, serverMessage, retryAfter, credentialHint) {
+function classifyError(status, serverMessage, retryAfter, credentialHint, serverCode) {
   const detail = serverMessage ? ` Server said: "${serverMessage}".` : "";
   if (status === 401) {
-    return new JoyApiError("auth", `Authentication failed \u2014 the app key or credential is wrong.${detail} This is a server configuration problem; do NOT retry. Ask the merchant to re-check ${credentialHint} in the MCP config.`, status);
+    return new JoyApiError("auth", `Authentication failed \u2014 the app key or credential is wrong.${detail} This is a server configuration problem; do NOT retry. Ask the merchant to re-check ${credentialHint} in the MCP config.`, status, serverCode);
   }
   if (status === 403) {
     const text = (serverMessage ?? "").toLowerCase();
     if (text.includes("plan")) {
-      return new JoyApiError("plan_gate", `The shop's subscription plan does not include REST API access (Advanced plan or higher is required).${detail} Do NOT retry \u2014 the merchant must upgrade their Joy plan first.`, status);
+      return new JoyApiError("plan_gate", `The shop's subscription plan does not include REST API access (Advanced plan or higher is required).${detail} Do NOT retry \u2014 the merchant must upgrade their Joy plan first.`, status, serverCode);
     }
-    return new JoyApiError("forbidden", `This operation is not permitted with the current credential (read-only key or insufficient scope).${detail} Do NOT retry with the same credential.`, status);
+    return new JoyApiError("forbidden", `This operation is not permitted with the current credential (read-only key or insufficient scope).${detail} Do NOT retry with the same credential.`, status, serverCode);
   }
   if (status === 402) {
-    return new JoyApiError("plan_gate", `The shop's plan does not include REST API or MCP access.${detail} Do NOT retry \u2014 tell the merchant to upgrade their Joy plan; the response's upgrade_url links straight to their subscription page.`, status);
+    return new JoyApiError("plan_gate", `The shop's plan does not include REST API or MCP access.${detail} Do NOT retry \u2014 tell the merchant to upgrade their Joy plan; the response's upgrade_url links straight to their subscription page.`, status, serverCode);
   }
   if (status === 429) {
     const wait = retryAfter ? `${retryAfter} seconds` : "~10 seconds";
@@ -133,22 +485,23 @@ function classifyError(status, serverMessage, retryAfter, credentialHint) {
       // window and a daily quota), so any number written into this string is wrong for most
       // shops. The server states the real one in `detail`, and Retry-After carries the wait.
       `Rate limited by the Joy API.${detail} Wait ${wait} before the next call, and prefer fewer, more specific queries (e.g. filter by email instead of listing pages). Do NOT retry immediately.`,
-      status
+      status,
+      serverCode
     );
   }
   if (status === 404) {
     if (!serverMessage) {
-      return new JoyApiError("not_found", "This endpoint does not exist on the Joy backend this shop is connected to. Nothing is wrong with the arguments and there is no identifier to re-check \u2014 the shop is on a deployment older than this tool. Do NOT retry, do NOT try a lookup tool, and do NOT substitute data from another tool. Tell the merchant this feature is unavailable on their current Joy version.", status);
+      return new JoyApiError("not_found", "This endpoint does not exist on the Joy backend this shop is connected to. Nothing is wrong with the arguments and there is no identifier to re-check \u2014 the shop is on a deployment older than this tool. Do NOT retry, do NOT try a lookup tool, and do NOT substitute data from another tool. Tell the merchant this feature is unavailable on their current Joy version.", status, serverCode);
     }
-    return new JoyApiError("not_found", `Not found.${detail} Verify the identifier and try a lookup tool first (e.g. joy_find_member) instead of guessing IDs.`, status);
+    return new JoyApiError("not_found", `Not found.${detail} Verify the identifier and try a lookup tool first (e.g. joy_find_member) instead of guessing IDs.`, status, serverCode);
   }
   if (status === 400 || status === 422) {
-    return new JoyApiError("validation", `Invalid request.${detail} Fix the named parameter and call again.`, status);
+    return new JoyApiError("validation", `Invalid request.${detail} Fix the named parameter and call again.`, status, serverCode);
   }
   if (status === 409) {
-    return new JoyApiError("conflict", `Conflict.${detail} Another attempt with the same Idempotency-Key is still in flight \u2014 wait ~30 seconds and call again with the SAME idempotency_key to retrieve its result. Never switch to a new key for the same operation; if this persists for minutes, verify the outcome via joy_get_member_activity instead.`, status);
+    return new JoyApiError("conflict", `Conflict.${detail} Another attempt with the same Idempotency-Key is still in flight \u2014 wait ~30 seconds and call again with the SAME idempotency_key to retrieve its result. Never switch to a new key for the same operation; if this persists for minutes, verify the outcome via joy_get_member_activity instead.`, status, serverCode);
   }
-  return new JoyApiError("server", `Joy API internal error (HTTP ${status}).${detail} Safe to retry ONCE after a short wait; if it persists, stop and report the failure to the merchant.`, status);
+  return new JoyApiError("server", `Joy API internal error (HTTP ${status}).${detail} Safe to retry ONCE after a short wait; if it persists, stop and report the failure to the merchant.`, status, serverCode);
 }
 function errorFromOkBody(body) {
   if (!body || typeof body !== "object")
@@ -160,12 +513,28 @@ function errorFromOkBody(body) {
   const message = extractServerMessage(record);
   const code = extractServerCode(record);
   if (code === "SHOP_UNINSTALLED" || /uninstall/i.test(message ?? "")) {
-    return new JoyApiError("forbidden", "The shop has uninstalled the Joy app \u2014 no loyalty data is available. Stop and inform the merchant; do NOT retry.");
+    return new JoyApiError("forbidden", "The shop has uninstalled the Joy app \u2014 no loyalty data is available. Stop and inform the merchant; do NOT retry.", void 0, telemetryServerCode(record));
   }
   if (code === "VALIDATION_ERROR") {
-    return new JoyApiError("validation", `Invalid request${message ? `: "${message}"` : ""}. Fix the named parameter and call again.`);
+    return new JoyApiError("validation", `Invalid request${message ? `: "${message}"` : ""}. Fix the named parameter and call again.`, void 0, telemetryServerCode(record));
+  }
+  return new JoyApiError("server", `The Joy API reported an error: "${message ?? "unknown error"}". Do not treat this as an empty result. First re-check your parameters against the message; if they look correct, retry ONCE, then report the failure to the merchant.`, void 0, telemetryServerCode(record));
+}
+function telemetryServerCode(body) {
+  const record = body && typeof body === "object" ? body : {};
+  return sanitizeString(TELEMETRY_SCHEMA, "mcp.tool_call", "error_code", extractServerCode(body)) ?? sanitizeString(TELEMETRY_SCHEMA, "mcp.tool_call", "error_code", record.error);
+}
+function authHeaders(config) {
+  const headers = {
+    "Content-Type": "application/json",
+    "X-Joy-Loyalty-App-Key": config.appKey
+  };
+  if (config.privateBotKey) {
+    headers["X-Joy-Private-Bot-Key"] = config.privateBotKey;
+  } else if (config.secretKey) {
+    headers["X-Joy-Loyalty-Secret-Key"] = config.secretKey;
   }
-  return new JoyApiError("server", `The Joy API reported an error: "${message ?? "unknown error"}". Do not treat this as an empty result. First re-check your parameters against the message; if they look correct, retry ONCE, then report the failure to the merchant.`);
+  return headers;
 }
 var JoyApi = class {
   config;
@@ -176,16 +545,7 @@ var JoyApi = class {
     return this.config.mode === "internal-bot" ? "JOY_APP_KEY and JOY_PRIVATE_BOT_KEY" : "JOY_APP_KEY and JOY_SECRET_KEY";
   }
   headers() {
-    const headers = {
-      "Content-Type": "application/json",
-      "X-Joy-Loyalty-App-Key": this.config.appKey
-    };
-    if (this.config.privateBotKey) {
-      headers["X-Joy-Private-Bot-Key"] = this.config.privateBotKey;
-    } else if (this.config.secretKey) {
-      headers["X-Joy-Loyalty-Secret-Key"] = this.config.secretKey;
-    }
-    return headers;
+    return authHeaders(this.config);
   }
   async request(path, options = {}) {
     const { method = "GET", query, body, timeoutMs = DEFAULT_TIMEOUT_MS, headers } = options;
@@ -194,49 +554,57 @@ var JoyApi = class {
       if (value !== void 0)
         url.searchParams.set(key, String(value));
     }
-    let response;
+    const record = currentCall();
+    if (record)
+      apiStart();
     try {
-      response = await fetch(url, {
-        method,
-        headers: { ...headers, ...this.headers() },
-        body: body === void 0 ? void 0 : JSON.stringify(body),
-        // fetch strips authorization on cross-origin redirects but NOT custom
-        // headers — an open redirect would forward the shop key elsewhere
-        redirect: "error",
-        signal: AbortSignal.timeout(timeoutMs)
-      });
-    } catch (error) {
-      if (error instanceof Error && error.name === "TimeoutError") {
-        throw new JoyApiError("timeout", `The Joy API did not respond within ${Math.round(timeoutMs / 1e3)}s. The first call after an idle period pays a Cloud Functions cold start, so a lone timeout is usually transient rather than an outage. Safe to retry ONCE; if it times out again, report the outage instead of retrying further.`);
+      let response;
+      try {
+        response = await fetch(url, {
+          method,
+          headers: { ...headers, ...record?.headers, ...this.headers() },
+          body: body === void 0 ? void 0 : JSON.stringify(body),
+          // fetch strips authorization on cross-origin redirects but NOT custom
+          // headers — an open redirect would forward the shop key elsewhere
+          redirect: "error",
+          signal: AbortSignal.timeout(timeoutMs)
+        });
+      } catch (error) {
+        if (error instanceof Error && error.name === "TimeoutError") {
+          throw new JoyApiError("timeout", `The Joy API did not respond within ${Math.round(timeoutMs / 1e3)}s. The first call after an idle period pays a Cloud Functions cold start, so a lone timeout is usually transient rather than an outage. Safe to retry ONCE; if it times out again, report the outage instead of retrying further.`);
+        }
+        throw new JoyApiError("network", `Could not reach the Joy API at ${this.config.apiBaseUrl}. Check network connectivity and JOY_API_BASE_URL. Safe to retry ONCE.`);
       }
-      throw new JoyApiError("network", `Could not reach the Joy API at ${this.config.apiBaseUrl}. Check network connectivity and JOY_API_BASE_URL. Safe to retry ONCE.`);
-    }
-    let parsed;
-    try {
-      parsed = await response.json();
-    } catch {
-      parsed = void 0;
-    }
-    if (!response.ok) {
-      throw classifyError(response.status, extractServerMessage(parsed), response.headers.get("Retry-After"), this.credentialHint());
+      let parsed;
+      try {
+        parsed = await response.json();
+      } catch {
+        parsed = void 0;
+      }
+      if (!response.ok) {
+        throw classifyError(response.status, extractServerMessage(parsed), response.headers.get("Retry-After"), this.credentialHint(), telemetryServerCode(parsed));
+      }
+      const okBodyError = errorFromOkBody(parsed);
+      if (okBodyError)
+        throw okBodyError;
+      return parsed ?? {};
+    } finally {
+      if (record)
+        apiEnd();
     }
-    const okBodyError = errorFromOkBody(parsed);
-    if (okBodyError)
-      throw okBodyError;
-    return parsed ?? {};
   }
   /** GET that unwraps the {success, data, meta} envelope — agent context never sees the wrapper. */
   async getData(path, options = {}) {
-    const envelope = await this.request(path, options);
+    const envelope2 = await this.request(path, options);
     return {
-      data: envelope.data,
-      hasNext: envelope.meta?.pagination?.hasNext === true
+      data: envelope2.data,
+      hasNext: envelope2.meta?.pagination?.hasNext === true
     };
   }
   /** POST/PUT that unwraps the envelope — for write tools. */
   async mutateData(path, options = {}) {
-    const envelope = await this.request(path, options);
-    return envelope.data;
+    const envelope2 = await this.request(path, options);
+    return envelope2.data;
   }
 };
 
@@ -255,6 +623,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
@@ -263,65 +634,139 @@ import { z as z2 } from "zod";
 // ../mcp-core/build/toolkit.js
 import { z } from "zod";
 
-// ../mcp-core/build/logger.js
-var log = {
-  info(message) {
-    console.error(`[joy-mcp] ${message}`);
-  },
-  error(message) {
-    console.error(`[joy-mcp:error] ${message}`);
+// ../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 }] };
+    markSuccess();
+    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 }] };
+      markToolError(error);
+      const text2 = store ? stampResult(error.modelMessage, store) : error.modelMessage;
+      return { isError: true, content: [{ type: "text", text: text2 }] };
     }
+    markInternalError();
     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 withTelemetry(ctx, name, callback) {
+  if (!ctx.telemetry)
+    return callback;
+  telemetrySafe("expose", () => ctx.telemetry?.expose(name));
+  return ((...args) => {
+    markEntered();
+    return callback(...args);
+  });
+}
+function registerReadTool(server, ctx, spec) {
+  const callback = withTelemetry(ctx, spec.name, (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 callback = (async (args) => {
+  const strictStore = ctx.store && ctx.requireStoreArg ? ctx.store : void 0;
+  const callback = withTelemetry(ctx, spec.name, (async (args) => {
+    if (strictStore) {
+      const mismatch = checkStoreMismatch(spec.name, args, strictStore);
+      if (mismatch) {
+        markRejected("store_mismatch");
+        return mismatch;
+      }
+    }
     if (!ctx.config.configWritesEnabled) {
+      markRejected("config_writes_disabled");
+      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 +775,37 @@ 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 callback = (async (args) => {
+  const strictStore = ctx.store && ctx.requireStoreArg ? ctx.store : void 0;
+  const callback = withTelemetry(ctx, spec.name, (async (args) => {
+    if (strictStore) {
+      const mismatch = checkStoreMismatch(spec.name, args, strictStore);
+      if (mismatch) {
+        markRejected("store_mismatch");
+        return mismatch;
+      }
+    }
     if (!ctx.config.writesEnabled) {
+      markRejected("writes_disabled");
+      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,
@@ -428,6 +879,9 @@ var MEMBER_DETAIL_KEYS = [
   "pointsRemain",
   "tierPoint",
   "pendingPoint",
+  // REST v2 detail fields, plus computed pointExpiration on the single-customer GETs.
+  "pointExpiration",
+  "pointExpirationUnavailable",
   "totalSpent",
   "totalEarnedPoints",
   "tierId",
@@ -470,6 +924,8 @@ var REWARD_KEYS = [
   "orderReqAmount",
   "expiredAt",
   "usedAt",
+  "isRevokedCode",
+  "revokedAt",
   "createdAt"
 ];
 var memberIdentifierSchema = {
@@ -514,19 +970,30 @@ 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.',
+    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. "pointExpiration" is the NEXT scheduled expiry: nextExpiryAt (ISO date) and nextExpiryPoints (how many points expire then). It is omitted when the shop's points never expire, the balance is 0, or no expiry is scheduled. If "pointExpirationUnavailable" is true the expiry could not be loaded \u2014 do not claim points never expire.`,
     inputSchema: memberIdentifierSchema,
     handler: async (args) => {
-      const member = await resolveMember(ctx.api, args);
+      let member = await resolveMember(ctx.api, args);
+      if (!args.shopify_customer_id && member.id && !Object.hasOwn(member, "pointExpiration")) {
+        try {
+          const { data } = await ctx.api.getData(`/customers/${encodeURIComponent(String(member.id))}`);
+          if (data && typeof data === "object")
+            member = data;
+        } catch {
+          member = { ...member, pointExpirationUnavailable: true };
+        }
+      }
       const shaped = compact(member, MEMBER_DETAIL_KEYS);
       const tier = member.tierName ? `, tier ${String(member.tierName)}` : "";
-      return summaryWithJson(`Member ${memberDisplayName(member)}: ${formatPoints(member.point)} points${tier}.`, shaped);
+      const pointExpiration = member.pointExpiration && typeof member.pointExpiration === "object" ? member.pointExpiration : void 0;
+      const expiry = pointExpiration && typeof pointExpiration.nextExpiryAt === "string" && typeof pointExpiration.nextExpiryPoints === "number" ? `, ${formatPoints(pointExpiration.nextExpiryPoints)} expire on ${pointExpiration.nextExpiryAt.slice(0, 10)}` : "";
+      return summaryWithJson(`Member ${memberDisplayName(member)}: ${formatPoints(member.point)} points${tier}${expiry}.`, 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 +1021,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.',
@@ -572,9 +1039,9 @@ function registerMemberTools(server, ctx) {
       const direction = args.direction ?? "desc";
       const withTotal = args.include_total_count === true;
       const sort = MEMBER_SORTS[sortBy];
-      let envelope;
+      let envelope2;
       try {
-        envelope = await ctx.api.request("/customers", {
+        envelope2 = await ctx.api.request("/customers", {
           query: {
             limit,
             after: args.after,
@@ -587,10 +1054,10 @@ function registerMemberTools(server, ctx) {
         reclassifyCursorError(error, args.after);
       }
       const result = {
-        data: envelope.data,
-        hasNext: envelope.meta?.pagination?.hasNext === true
+        data: envelope2.data,
+        hasNext: envelope2.meta?.pagination?.hasNext === true
       };
-      const totalMembers = withTotal ? envelope.meta?.pagination?.total : void 0;
+      const totalMembers = withTotal ? envelope2.meta?.pagination?.total : void 0;
       const members = Array.isArray(result.data) ? result.data : [];
       if (members.length === 0) {
         if (args.after)
@@ -615,7 +1082,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,10 +1119,10 @@ 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?".`,
+    description: `Coupons and rewards ONE member has already redeemed \u2014 code, discount program, status (active/used/expired/revoked), expiry. A revoked coupon has discountStatus "revoked" plus isRevokedCode/revokedAt: its points were refunded and the code no longer works. This is the member's OWN history, NOT the shop's catalog of what CAN be redeemed (use joy_list_redemption_rules for that). Use to answer "what coupons does this customer have?" or "did they already use that discount code?".`,
     inputSchema: {
       ...memberIdentifierSchema,
       limit: z2.number().int().min(1).max(50).optional().describe("Rewards per page (default 10, max 50)."),
@@ -708,23 +1175,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 +1244,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 +1306,9 @@ var EARNING_KEYS = [
   "rateMoney",
   "earnPoint",
   "earnPointsTiers",
+  "isAppliedVipTier",
+  "appliedPlaceOrderTo",
+  "skipEarnPointGuest",
   "conditions",
   "typeMilestone",
   "milestones",
@@ -795,7 +1316,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 +1350,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 +1400,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 +1678,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 +1700,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 +1717,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 +1776,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.',
@@ -1341,13 +1906,13 @@ var reportDateRangeSchema = {
 var SCOPE_HELP = "A 403 mentioning read_reports means the MERCHANT has not granted Shopify reports access to Joy \u2014 not a credential problem, do not retry; ask them to grant it from Joy settings.";
 function withScopeGuidance(error) {
   if (error instanceof JoyApiError && error.status === 403 && /read_reports/i.test(error.message)) {
-    return new JoyApiError("forbidden", "This report needs the Shopify read_reports permission, which the merchant has not granted to Joy yet. This is NOT a credential problem \u2014 do NOT retry. Ask the merchant to grant reports access from the Joy admin settings, then call again.", 403);
+    return new JoyApiError("forbidden", "This report needs the Shopify read_reports permission, which the merchant has not granted to Joy yet. This is NOT a credential problem \u2014 do NOT retry. Ask the merchant to grant reports access from the Joy admin settings, then call again.", 403, error.serverCode);
   }
   return error;
 }
 function withV2EnablementGuidance(error) {
   if (error instanceof JoyApiError && error.status === 409 && /Analytics V2 is not enabled/i.test(error.message)) {
-    return new JoyApiError("conflict", "This shop is still on Analytics V1 \u2014 Analytics V2 report data does not exist yet, so there are NO numbers to quote (do not report zeros). Ask the merchant if they want to switch to the new Analytics; switching also backfills their historical data. If they agree and the joy_enable_analytics_v2 tool is available, call it; otherwise tell them to switch in Joy admin \u2192 Analytics. Do not retry this report until V2 is enabled.", 409);
+    return new JoyApiError("conflict", "This shop is still on Analytics V1 \u2014 Analytics V2 report data does not exist yet, so there are NO numbers to quote (do not report zeros). Ask the merchant if they want to switch to the new Analytics; switching also backfills their historical data. If they agree and the joy_enable_analytics_v2 tool is available, call it; otherwise tell them to switch in Joy admin \u2192 Analytics. Do not retry this report until V2 is enabled.", 409, error.serverCode);
   }
   return error;
 }
@@ -1379,7 +1944,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 +1972,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 +1992,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,
@@ -1445,7 +2010,7 @@ ${summary}`);
         });
       } catch (error) {
         if (error instanceof JoyApiError && error.status === 422) {
-          throw new JoyApiError("validation", "Tier performance needs the Joy tier metafield definition, which is currently DISABLED on this shop. This is a setup gate, not empty data and not a parameter problem \u2014 do not retry. Ask the merchant to enable it in Joy \u2192 Settings \u2192 General \u2192 Metafield section, then call again.", 422);
+          throw new JoyApiError("validation", "Tier performance needs the Joy tier metafield definition, which is currently DISABLED on this shop. This is a setup gate, not empty data and not a parameter problem \u2014 do not retry. Ask the merchant to enable it in Joy \u2192 Settings \u2192 General \u2192 Metafield section, then call again.", 422, error.serverCode);
         }
         throw error;
       }
@@ -1454,7 +2019,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.`,
@@ -1505,19 +2070,19 @@ function resolveIdempotencyKey(provided) {
 }
 function rethrowWithRetryKey(error, idempotencyKey) {
   if (error instanceof JoyApiError && (error.kind === "timeout" || error.kind === "network" || error.kind === "server")) {
-    throw new JoyApiError(error.kind, `${error.modelMessage} IMPORTANT: this was a write \u2014 it may or may not have been applied. Do NOT assume failure and do NOT retry with a fresh call. To retry safely, call the same tool again with idempotency_key: "${idempotencyKey}" within 24 hours (keys expire after that) \u2014 the backend will return the original result instead of applying the change twice.`, error.status);
+    throw new JoyApiError(error.kind, `${error.modelMessage} IMPORTANT: this was a write \u2014 it may or may not have been applied. Do NOT assume failure and do NOT retry with a fresh call. To retry safely, call the same tool again with idempotency_key: "${idempotencyKey}" within 24 hours (keys expire after that) \u2014 the backend will return the original result instead of applying the change twice.`, error.status, error.serverCode);
   }
   throw error;
 }
 function rethrowRedeemUncertain(error) {
   if (error instanceof JoyApiError && (error.kind === "timeout" || error.kind === "network" || error.kind === "server")) {
-    throw new JoyApiError(error.kind, `The redeem request failed with an UNCERTAIN outcome (${error.kind}) \u2014 it may have completed anyway, and redeem has NO retry protection. Do NOT retry now. First call joy_get_member_activity for this member and check for a redemption in the last few minutes: if one exists, the redeem succeeded (do not repeat it); only if none exists is it safe to try again.`, error.status);
+    throw new JoyApiError(error.kind, `The redeem request failed with an UNCERTAIN outcome (${error.kind}) \u2014 it may have completed anyway, and redeem has NO retry protection. Do NOT retry now. First call joy_get_member_activity for this member and check for a redemption in the last few minutes: if one exists, the redeem succeeded (do not repeat it); only if none exists is it safe to try again.`, error.status, error.serverCode);
   }
   throw error;
 }
 function rethrowRefundUncertain(error) {
   if (error instanceof JoyApiError && (error.kind === "timeout" || error.kind === "network" || error.kind === "server")) {
-    throw new JoyApiError(error.kind, `The refund request failed with an UNCERTAIN outcome (${error.kind}) \u2014 it may have completed anyway, and refund has NO retry protection. Do NOT retry now. First call joy_get_member_activity for this member and look for a refund_point_redeem entry with this coupon code: if one exists, the refund succeeded and points were already restored (do not award them again). If the retry itself returns "coupon does not exist or has expired", that most likely means the first attempt SUCCEEDED \u2014 a revoked coupon no longer shows up in lookups.`, error.status);
+    throw new JoyApiError(error.kind, `The refund request failed with an UNCERTAIN outcome (${error.kind}) \u2014 it may have completed anyway, and refund has NO retry protection. Do NOT retry now. First call joy_get_member_activity for this member and look for a refund_point_redeem entry with this coupon code: if one exists, the refund succeeded and points were already restored (do not award them again). If the retry itself returns "coupon does not exist or has expired", that most likely means the first attempt SUCCEEDED \u2014 a revoked coupon no longer shows up in lookups.`, error.status, error.serverCode);
   }
   throw error;
 }
@@ -1695,7 +2260,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 +2282,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 +2366,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 +2444,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 +2485,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 +2572,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 +2629,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 +2655,290 @@ 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 new loyalty page design changes will not appear there. The merchant must open ${data.v2BlockAddUrl || "the new loyalty page block link from joy_check_theme_setup"}, add the Joy: New Loyalty Page block, and save the theme. ` : "";
+  let live = "The shop still serves the classic loyalty page, 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 = "The new loyalty page is active for this shop.";
+  }
+  if (data.pageVersionActive && data.renderPath === "none") {
+    live = "The new loyalty page 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}New loyalty page 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 new loyalty page 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 new loyalty page 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 new loyalty page 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 new loyalty page, 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: "New loyalty page 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 new loyalty page 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: "New loyalty page 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 New loyalty page 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/loyaltyHub.js
+import { z as z15 } from "zod";
+function summarizeHubDesign(data) {
+  const sections = data.design?.sections ?? [];
+  const on = sections.filter((s) => s.enabled !== false).map((s) => s.id);
+  return `Loyalty Hub design. Sections on: ${on.join(", ") || "none"}. The Hub is LIVE \u2014 every logged-in customer sees changes immediately. Programs, tier icons and program icons are shared with the Loyalty Page, widget and emails.`;
+}
+function summarizeHubAppliedChanges(applied2, warnings2 = []) {
+  const headline = applied2.slice(0, 5).join("; ");
+  const more = applied2.length > 5 ? ` (+${applied2.length - 5} more)` : "";
+  const caveat = warnings2.length ? `\u26A0 ${warnings2.join(" \u26A0 ")} ` : "";
+  return `${caveat}${applied2.length} design field${applied2.length === 1 ? "" : "s"} changed \u2014 ${headline}${more}. LIVE now for every logged-in customer. Undo with joy_revert_loyalty_hub_design.`;
+}
+function registerLoyaltyHubTools(server, ctx) {
+  registerReadTool(server, ctx, {
+    name: "joy_get_loyalty_hub_design",
+    title: "Get Loyalty Hub design",
+    description: "Read the shop's Loyalty Hub appearance \u2014 which sections are switched on and their layout and styling, plus the shared program and tier icons. Also returns `writableFields`: the exact field names joy_update_loyalty_hub_design accepts, with the allowed values of each. redeemButtonVariant (secondary by default, or primary) changes only voucher-card Redeem buttons. Section card border overrides are rewardsCardBorderStyle (My coupons), earnCardBorderStyle (Ways to earn), redeemCardBorderStyle (Redeem), and vipCardBorderStyle (VIP); each accepts inherit (default), solid, or dashed. Inherit follows the global border style. IMPORTANT: the Loyalty Hub has NO draft \u2014 every change is LIVE for every logged-in customer immediately. Programs, program icons and tier icons are SHARED with the Loyalty Page, widget and emails: changing them here also changes those other surfaces. CALL THIS BEFORE any design change \u2014 the field vocabulary is large and specific, and guessing a name costs a failed call. This tool reads appearance only: Hub text (headings, descriptions) is read by joy_get_loyalty_hub_text.",
+    inputSchema: {},
+    handler: async () => {
+      const { data } = await ctx.api.getData("/loyalty-hub/design");
+      return summaryWithJson(summarizeHubDesign(data), data);
+    }
+  });
+}
+function registerLoyaltyHubWriteTools(server, ctx) {
+  registerWriteTool(server, ctx, {
+    name: "joy_update_loyalty_hub_design",
+    title: "Update Loyalty Hub design",
+    destructiveHint: false,
+    idempotentHint: true,
+    description: "Change the Loyalty Hub's appearance. WARNING: the Hub has NO draft \u2014 every accepted change is LIVE for every logged-in customer immediately. Send ONLY the fields you are changing; anything omitted keeps its current value. redeemButtonVariant (secondary by default, or primary) changes only voucher-card Redeem buttons. Section card border overrides: rewardsCardBorderStyle (My coupons), earnCardBorderStyle (Ways to earn), redeemCardBorderStyle (Redeem), vipCardBorderStyle (VIP). Each accepts inherit (default), solid, or dashed and changes only card border line style. Inherit follows the global border style; border width, radius, background, density, inner separators and current-tier highlights remain unchanged. Programs, tier icons and program icons are SHARED with the Loyalty Page, widget and emails \u2014 changing them here also changes those other surfaces. If the merchant has the Hub editor open, it will ask them to reload. Call joy_get_loyalty_hub_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. Undo with joy_revert_loyalty_hub_design. Appearance only \u2014 this cannot change any text on the Hub.",
+    inputSchema: {
+      design: z15.record(z15.unknown()).describe('The fields to change. Flat Hub keys named in `writableFields` from joy_get_loyalty_hub_design (section switches, layouts, visible counts, hero image, Redeem-only redeemButtonVariant: secondary|primary, section border overrides rewardsCardBorderStyle/earnCardBorderStyle/redeemCardBorderStyle/vipCardBorderStyle: inherit|solid|dashed (default inherit follows global), and the Design tab: cardBorderWidth, cardBorderStyle, cardRadius, cardBackground, density, earnIconColor as #RRGGBB), plus optional `programs` ({earning?:[{id, showLoyaltyPage}], spending?:[...]}), `programOrder` ({earning?:[program ids], spending?:[...]}, position sets the order) and `icons` ({earning?:{...}, spending?:{...}, tiers?:{...}|[...]}, valued with an image URL or a built-in icon name; address earning/spending artwork by program id OR event, tiers by tier id, tier name or array position). Read current program artwork from joy_list_earning_rules / joy_list_redemption_rules. Example: {"cardRadius":"max","earnIconColor":"#0F4C3A","icons":{"earning":{"birthday":"https://cdn.../cake.png"}}}')
+    },
+    handler: async (args) => {
+      const result = await ctx.api.mutateData("/loyalty-hub/design", {
+        method: "PATCH",
+        timeoutMs: 2e4,
+        body: { design: args.design }
+      });
+      const applied2 = result?.applied ?? [];
+      if (!applied2.length) {
+        return "No change \u2014 every field you sent already had that value.";
+      }
+      const warnings2 = result?.warnings ?? [];
+      return summaryWithJson(summarizeHubAppliedChanges(applied2, warnings2), {
+        applied: applied2,
+        ...warnings2.length ? { warnings: warnings2 } : {}
+      });
+    }
+  });
+  registerWriteTool(server, ctx, {
+    name: "joy_revert_loyalty_hub_design",
+    title: "Revert the last Loyalty Hub design change",
+    destructiveHint: true,
+    idempotentHint: true,
+    description: "Undo the last design change made through joy_update_loyalty_hub_design, restoring the Hub exactly as it was before that call \u2014 LIVE immediately for every logged-in customer. ONE step only \u2014 a second call restores the same snapshot again rather than going further back. Program and tier icons go back LIVE immediately because they are shared data with no draft. WARNING: it restores a whole saved design, so any edit the merchant made in the Hub editor AFTER that update is discarded too \u2014 if they may have been editing, ask before calling this. Use it promptly; the next update overwrites the snapshot.",
+    inputSchema: {},
+    handler: async () => {
+      const result = await ctx.api.mutateData("/loyalty-hub/design/revert", {
+        method: "POST",
+        timeoutMs: 2e4,
+        body: {}
+      });
+      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 ")} restored \u2014 LIVE now (shared data, no draft).` : "";
+      return summaryWithJson(`Reverted to the Loyalty Hub design from before the last update. LIVE immediately for every logged-in customer.${icons}`, { design: result?.design, programIconsRestored: programIcons, tierIconsRestored: tierIcons });
+    }
+  });
+}
+
+// ../mcp-core/build/tools/loyaltyHubText.js
+import { z as z16 } from "zod";
+var localeSchema2 = z16.string().min(2).optional().describe("Active locale code. Omit to use the shop's primary language.");
+function registerLoyaltyHubTextTools(server, ctx) {
+  registerReadTool(server, ctx, {
+    name: "joy_get_loyalty_hub_text",
+    title: "Get Loyalty Hub text",
+    description: "Loyalty Hub text has no draft: text edits are LIVE on the Hub 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_hub_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: localeSchema2 },
+    handler: async (args) => {
+      const { data } = await ctx.api.getData("/loyalty-hub/text", {
+        query: { locale: args.locale }
+      });
+      return summaryWithJson(`${Object.keys(data.values).length} live Loyalty Hub text values for ${data.locale}. Primary language: ${data.primaryLanguage}; active locales: ${data.activeLocales.join(", ")}.`, data);
+    }
+  });
+}
+function registerLoyaltyHubTextWriteTools(server, ctx) {
+  registerWriteTool(server, ctx, {
+    name: "joy_update_loyalty_hub_text",
+    title: "Update Loyalty Hub text",
+    destructiveHint: true,
+    idempotentHint: false,
+    description: "Loyalty Hub text has no draft: every accepted change is LIVE on the Hub immediately. Update only exact keys returned by joy_get_loyalty_hub_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 Hub text change with joy_revert_loyalty_hub_text.",
+    inputSchema: {
+      locale: localeSchema2,
+      changes: z16.array(z16.object({
+        key: z16.string().min(1),
+        value: z16.string(),
+        manual: z16.boolean().optional().describe("Set true only when the merchant authored this exact replacement.")
+      })).min(1).describe("Exact key/value edits from joy_get_loyalty_hub_text.")
+    },
+    handler: async (args) => {
+      const result = await ctx.api.mutateData("/loyalty-hub/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 Hub text has no draft \u2014 ${result.applied.length} text change(s) are LIVE now.${propagation}${skipped} Undo with joy_revert_loyalty_hub_text.`, result);
+    }
+  });
+  registerWriteTool(server, ctx, {
+    name: "joy_revert_loyalty_hub_text",
+    title: "Revert the last Loyalty Hub text change",
+    destructiveHint: true,
+    idempotentHint: true,
+    description: "Undo the last text change made through joy_update_loyalty_hub_text, restoring the Loyalty Hub text exactly as it was before that call \u2014 LIVE immediately. ONE step only \u2014 a second call restores the same snapshot again rather than going further back. This undoes Hub text only; use joy_revert_loyalty_hub_design to undo Hub design changes.",
+    inputSchema: {},
+    handler: async () => {
+      const result = await ctx.api.mutateData("/loyalty-hub/text/revert", {
+        method: "POST",
+        timeoutMs: 2e4,
+        body: {}
+      });
+      const count = result?.textKeysRestored ?? 0;
+      return summaryWithJson(`Reverted Loyalty Hub text \u2014 ${count} value${count === 1 ? "" : "s"} restored. LIVE immediately.`, result);
+    }
+  });
+}
+
+// ../mcp-core/build/tools/programsWrite.js
+import { z as z17 } from "zod";
 var PROGRAM_TYPE_BY_KIND = {
   earning: "earning",
   redemption: "spending"
@@ -2116,7 +2966,7 @@ var REVIEW_APPS = [
   "okendoApp",
   "ReviewsIoApp",
   "growaveApp",
-  "typdalApp"
+  "segunoReviewApp"
 ];
 var REVIEW_FLOW_APPS = /* @__PURE__ */ new Set([
   "stampedApp",
@@ -2124,6 +2974,7 @@ var REVIEW_FLOW_APPS = /* @__PURE__ */ new Set([
   "okendoApp",
   "ReviewsIoApp",
   "growaveApp",
+  "segunoReviewApp",
   "typdalApp"
 ]);
 var REVIEW_PHOTO_VIDEO_APPS = /* @__PURE__ */ new Set(["reviewRocketApp", "looxApp"]);
@@ -2167,7 +3018,8 @@ var EARNING_FIELDS = [
   "extraPointsForVideos",
   "isAppliedVipTier",
   "earnPointsTiers",
-  "appliedPlaceOrderTo"
+  "appliedPlaceOrderTo",
+  "skipEarnPointGuest"
 ];
 var REDEMPTION_FIELDS = [
   "event",
@@ -2190,8 +3042,8 @@ var REDEMPTION_FIELDS = [
 function withoutUnsetFields(body) {
   return Object.fromEntries(Object.entries(body).filter(([, value]) => value !== void 0));
 }
-function missingFields(event, fields) {
-  return { ok: false, error: `Creating ${event} requires: ${fields.join(", ")}.` };
+function missingFields(event, fields2) {
+  return { ok: false, error: `Creating ${event} requires: ${fields2.join(", ")}.` };
 }
 function unsupportedCreate(event) {
   return {
@@ -2484,45 +3336,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: z17.string().min(1).optional().describe("Existing Joy program ID. Omit to create a new program."),
+  event: z17.string().optional().describe("Program event. Required for create; optional for update."),
+  title: z17.string().min(1).optional().describe("Customer-facing program title."),
+  status: z17.boolean().optional().describe("Set false to disable this rule instead of deleting it."),
+  priority: z17.number().int().optional().describe("Optional program priority."),
+  start_date: z17.string().optional().describe("Optional ISO start date."),
+  end_date: z17.string().optional().describe("Optional ISO end date."),
+  earn_by: z17.enum(["price", "fixed_order", "quantity", "order"]).optional(),
+  rate_money: z17.number().optional(),
+  rate_item: z17.number().optional(),
+  earn_point: z17.number().optional(),
+  date_format: z17.enum(["MM/DD", "DD/MM", "MM/DD/YYYY", "DD/MM/YYYY", "YYYY/MM/DD"]).optional(),
+  type_reward_timing: z17.enum(["exact_birthday", "begin_of_month", "around_birthday"]).optional(),
+  limit_unit: z17.string().optional(),
+  limit_interval: z17.number().int().positive().optional(),
+  url_account: z17.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: z17.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: z17.string().optional().describe("Required only when review_app is a Shopify Flow app (stampedApp, looxApp, okendoApp, ReviewsIoApp, growaveApp, segunoReviewApp, typdalApp) \u2014 the merchant-facing note describing how the Flow awards points."),
+  extra_points_for_images: z17.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: z17.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: z17.number().int().positive().optional(),
+  earn_amount: z17.number().optional(),
+  shipping_discount_type: z17.enum(["percentage", "fixedAmount"]).optional(),
+  shipping_discount_amount: z17.number().optional(),
+  applied_to: z17.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: z17.array(z17.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: z17.array(z17.unknown()).optional(),
+  applied_collection_ids: z17.array(z17.string()).optional().describe("free_gift with applied_to specific or exclude_collection only \u2014 merchant-provided collection IDs."),
+  collection_quantity: z17.number().int().positive().optional().describe("Required for collection-based free_gift rules (applied_to specific or exclude_collection)."),
+  product_url: z17.array(z17.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: z17.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: z17.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: z17.record(z17.object({
+    earn_point: z17.number().optional().describe("Points this tier earns, replacing the flat earn_point."),
+    rate_money: z17.number().optional().describe("place_order only: money amount that earns earn_point for this tier."),
+    type_earn: z17.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: z17.string().min(3).describe("Why the merchant wants this configuration change."),
+  apply: z17.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 +3383,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 +3476,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 +3502,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 +3518,10 @@ function registerProgramConfigTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/tiersWrite.js
-import { z as z14 } from "zod";
+import { z as z18 } 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 +3583,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 +3607,7 @@ var TIER_SETTINGS_FIELDS = [
   "notificationDowngradeBefore",
   "notificationDowngradeBeforeUnit"
 ];
-var rewardEventSchema = z14.enum([
+var rewardEventSchema = z18.enum([
   "amount_discount",
   "percentage_discount",
   "free_shipping",
@@ -2754,95 +3615,101 @@ var rewardEventSchema = z14.enum([
   "bonus_point",
   "buy_x_get_y"
 ]);
-var finiteNumber = () => z14.number().finite();
-var tierRewardInputSchema = z14.object({
+var finiteNumber = () => z18.number().finite();
+var tierRewardInputSchema = z18.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: z18.string().min(1).optional(),
+  type: z18.enum(["tier_spending", "tier_privileges", "pre_tier_reward"]).optional(),
+  status: z18.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: z18.string().optional(),
+  redeem_type: z18.string().optional(),
+  applied_to: z18.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: z18.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: z18.array(z18.unknown()).optional(),
+  specific_collections: z18.array(z18.unknown()).optional(),
+  applied_collection_ids: z18.array(z18.unknown()).optional(),
+  combined_with: z18.array(z18.enum(["orderDiscounts", "shippingDiscounts", "productDiscounts"])).optional(),
+  has_limit_shipping: z18.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: z18.enum(["day", "month"]).optional(),
+  is_refund_coupon: z18.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: z18.boolean().optional(),
+  perk_title_language: z18.record(z18.unknown()).optional(),
+  reward_product_selection_mode: z18.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: z18.string().min(1).optional().describe("Existing tier ID. Omit to create a tier."),
+  name: z18.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: z18.string().optional(),
+  icon_custom: z18.string().optional(),
+  bg_image: z18.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: z18.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: z18.string().optional(),
+  is_exclusive_tier: z18.boolean().optional(),
+  hide_default_tier: z18.boolean().optional(),
+  text_color: z18.string().optional(),
+  progress_bar_color: z18.string().optional(),
+  box_bg_color: z18.string().optional(),
+  box_text_color: z18.string().optional(),
+  bg_card_color: z18.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: z18.string().optional(),
+  bg_type: z18.string().optional(),
+  tier_names_language: z18.record(z18.unknown()).optional(),
+  rewards: z18.array(tierRewardInputSchema).optional().describe("Optional rewards to create with a NEW tier in this one configuration write."),
+  reason: z18.string().min(3).describe("Why the merchant wants this tier configuration."),
+  apply: z18.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: z18.string().min(1).describe("Tier ID from joy_list_tiers."),
+  reward_id: z18.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: z18.array(z18.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: z18.string().min(3).describe("Why the merchant wants this reward configuration."),
+  apply: z18.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: z18.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: z18.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: z18.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: z18.boolean().optional().describe("When true, tier reward codes use prefix instead of the shop default."),
+  show_tier_point_settings: z18.boolean().optional().describe("Show tier-point editing on the customer admin page."),
+  allow_give_entry_reward_again: z18.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: z18.boolean().optional(),
+  type_demotion: z18.enum(["downgrade_tier", "reset_tier"]).optional(),
+  downgrade_after: z18.number().int().positive().optional(),
+  downgrade_after_unit: z18.enum(["day", "month", "year"]).optional(),
+  use_reset_tier: z18.boolean().optional(),
+  reset_after: z18.number().int().positive().optional(),
+  reset_after_unit: z18.enum(["day", "month", "year"]).optional(),
+  reset_frequency: z18.enum(["monthly", "quarterly", "half_yearly", "yearly", "custom"]).optional(),
+  reset_interval_value: z18.number().int().positive().optional(),
+  reset_interval_unit: z18.enum(["day", "month", "year"]).optional(),
+  reset_start_date: z18.string().min(1).optional(),
+  month_reset_tier: z18.number().int().min(1).max(12).optional(),
+  day_reset_tier: z18.number().int().min(1).max(31).optional(),
+  is_sync_tags_customer_tier: z18.boolean().optional(),
+  customer_tier_tag_prefix: z18.string().optional(),
+  notification_downgrade_before: z18.number().int().positive().optional(),
+  notification_downgrade_before_unit: z18.enum(["day", "month"]).optional(),
+  reason: z18.string().min(3).describe("Why the merchant wants these tier settings."),
+  apply: z18.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: z18.string().min(1).describe("Tier ID from joy_list_tiers."),
+  perks: z18.array(z18.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: z18.string().min(3).describe("Why the merchant wants to replace this tier perk list."),
+  apply: z18.boolean().optional().describe("Set true only after the dry-run preview is approved.")
 };
 function tierFreeGiftSelectionError(args, requireAppliedTo = false) {
   if (args.event !== "free_gift")
@@ -2941,7 +3808,7 @@ function buildTierConfigPreview(params) {
 }
 function rethrowTierCreateConflict(error) {
   if (error instanceof JoyApiError && error.status === 409) {
-    throw new JoyApiError("conflict", "Cannot create this tier because another tier already has this name or target_point. Call joy_list_tiers, then update the existing tier with tier_id instead of retrying the create.", error.status);
+    throw new JoyApiError("conflict", "Cannot create this tier because another tier already has this name or target_point. Call joy_list_tiers, then update the existing tier with tier_id instead of retrying the create.", error.status, error.serverCode);
   }
   throw error;
 }
@@ -3138,6 +4005,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 +4036,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 +4050,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 +4081,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 +4099,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);
   }
@@ -3238,7 +4128,7 @@ async function readTierSettings(ctx) {
 }
 function rethrowTierSettingsNotLaunched(error) {
   if (error instanceof JoyApiError && error.kind === "not_found") {
-    throw new JoyApiError("not_found", "This shop has never launched tiers, so tier settings do not exist yet. Launch the tier program in Joy admin first; this MCP tool cannot launch it.", error.status);
+    throw new JoyApiError("not_found", "This shop has never launched tiers, so tier settings do not exist yet. Launch the tier program in Joy admin first; this MCP tool cannot launch it.", error.status, error.serverCode);
   }
   throw error;
 }
@@ -3308,8 +4198,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 +4214,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 +4318,7 @@ function isAfterOrEqual(candidate, cursor, inclusive) {
 }
 
 // ../mcp-core/build/tools/shopConfig.js
-import { z as z15 } from "zod";
+import { z as z19 } from "zod";
 var SHOP_SETTINGS_FIELDS = [
   "primaryLanguageInApp",
   "dateFormat",
@@ -3517,8 +4416,8 @@ function toShopSettingsBody(args) {
 function getDroppedShopSettingsFields(args) {
   return getUnknownArguments(args, SHOP_SETTINGS_VALID_ARGUMENTS);
 }
-function selectedFields(body, fields) {
-  const selected = fields.filter((field) => body[field] !== void 0);
+function selectedFields(body, fields2) {
+  const selected = fields2.filter((field) => body[field] !== void 0);
   return selected.length > 0 ? selected.join(", ") : "none selected";
 }
 function buildShopSettingsPreview(current, args) {
@@ -3562,20 +4461,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: z19.enum(["en", "en-US", "fr", "es", "de", "it", "ja", "id", "zh-CN"]).optional(),
+      date_format: z19.enum(["MM/DD/YYYY", "DD/MM/YYYY", "YYYY/MM/DD", "YYYY-MM-DD"]).optional(),
+      date_format_for_activity: z19.enum(["HH:mm", "hh:mm A"]).optional(),
+      point_position: z19.enum(["before", "after"]).optional(),
+      customer_apply_discount_behavior: z19.enum(["stay_current", "go_to_cart", "open_cart_drawer"]).optional(),
+      customer_redeem_coupon_behavior: z19.enum(["auto_apply", "save_for_later"]).optional(),
+      customer_free_gift_behavior: z19.enum(["manual_add_to_cart", "auto_add_to_cart"]).optional(),
+      status_for_review: z19.enum(["pending", "approveAuto"]).optional(),
+      earn_by_order_status: z19.enum(["financial_status", "fulfillment_status"]).optional(),
+      enable_global_earning_limit: z19.boolean().optional(),
+      global_earning_limit_timeframe: z19.enum(["yearly", "monthly", "rolling"]).optional(),
+      global_earning_limit_rolling_days: z19.number().int().min(1).max(365).optional(),
+      reason: z19.string().min(3).describe("Why the merchant wants these shop-wide settings changed."),
+      apply: z19.boolean().optional().describe("Set true only after the merchant has approved the dry-run preview.")
     },
     destructiveHint: false,
     strictArguments: true,
@@ -3597,10 +4496,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: z19.enum(TRANSLATION_LOCALES),
+      additional_language: z19.enum(TRANSLATION_LOCALES),
+      reason: z19.string().min(3).describe("Why the merchant wants this storefront language added."),
+      apply: z19.boolean().optional().describe("Set true only after the merchant has approved the dry-run preview.")
     },
     destructiveHint: false,
     strictArguments: true,
@@ -3619,7 +4518,7 @@ function registerShopConfigTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/brandingWrite.js
-import { z as z16 } from "zod";
+import { z as z20 } 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 +4561,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: z20.enum(["v3", "v4"]).describe("Widget version to change. A live target is accepted only when this is the shop\u2019s currently live version."),
+  target: z20.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: z20.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: z20.string().url().startsWith("https://").optional().describe("Optional public HTTPS storefront URL to scan when apply_scan is true."),
+  storefront_password: z20.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: z20.boolean().optional().describe("When apply_scan is true, also replace detected logo and card imagery. Defaults to false."),
+  color_overrides: z20.record(z20.string()).optional().describe(`Optional hex overrides for supported V4 color roles: ${COLOR_ROLES.join(", ")}.`),
+  design_overrides: z20.object({
+    corner_radius: z20.enum(CORNER_RADIUS_VALUES).optional().describe("Corner style. radiusNone is square/not rounded; radiusExtra is the most rounded."),
+    button_style: z20.enum(BUTTON_STYLE_VALUES).optional().describe("store matches the storefront, custom uses the widget\u2019s own button colours."),
+    content_style: z20.enum(CONTENT_STYLE_VALUES).optional().describe("text_only removes the icons beside earn/redeem rows; icons_and_text shows them."),
+    display_type: z20.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: z20.object({ heading: z20.string().min(1).optional(), body: z20.string().min(1).optional() }).optional().describe("Optional heading and body font overrides."),
+  reason: z20.string().min(3).describe("Why the merchant wants this widget draft."),
+  apply: z20.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: z20.string().url().startsWith("https://").optional().describe("Optional public HTTPS storefront URL. Omit it to scan this shop\u2019s own storefront."),
+  storefront_password: z20.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);
@@ -3706,19 +4605,19 @@ function brandingErrorGuidance(error, operation, target = "draft") {
   const passwordIncorrect = errorCode === "PASSWORD_INCORRECT" || /PASSWORD_INCORRECT|storefront password (?:did not unlock|was not accepted)|incorrect storefront password/i.test(error.modelMessage);
   const passwordRequired = errorCode === "PASSWORD_REQUIRED" || error.status === 409 || /PASSWORD_REQUIRED|storefront is password-protected|storefront password is required/i.test(error.modelMessage);
   if (operation === "scan" && passwordIncorrect) {
-    return new JoyApiError("validation", "The storefront password was not accepted. Ask the merchant to verify the storefront password, then pass the corrected value as storefront_password. Do not guess it.", error.status);
+    return new JoyApiError("validation", "The storefront password was not accepted. Ask the merchant to verify the storefront password, then pass the corrected value as storefront_password. Do not guess it.", error.status, error.serverCode);
   }
   if (operation === "scan" && passwordRequired) {
-    return new JoyApiError("conflict", "The storefront is password-protected. Ask the merchant for the storefront password, then pass it as storefront_password to joy_scan_brand_design. Do not guess the password, and do not invent colors or fonts.", error.status);
+    return new JoyApiError("conflict", "The storefront is password-protected. Ask the merchant for the storefront password, then pass it as storefront_password to joy_scan_brand_design. Do not guess the password, and do not invent colors or fonts.", error.status, error.serverCode);
   }
   if (operation === "scan" && error.status === 503) {
-    return new JoyApiError("server", "Joy could not complete the storefront design scan. No design has been returned, so do not invent colors, fonts, or button styling. Ask the merchant to retry later or configure the draft manually.", error.status);
+    return new JoyApiError("server", "Joy could not complete the storefront design scan. No design has been returned, so do not invent colors, fonts, or button styling. Ask the merchant to retry later or configure the draft manually.", error.status, error.serverCode);
   }
   if (operation === "draft" && target === "live" && error.status === 409) {
-    return new JoyApiError("conflict", "The live widget document exists only for the version the shop is currently using. This target: 'live' request used a non-live version and was refused. Check which widget version is currently live before retrying; do not blindly retry the other version.", error.status);
+    return new JoyApiError("conflict", "The live widget document exists only for the version the shop is currently using. This target: 'live' request used a non-live version and was refused. Check which widget version is currently live before retrying; do not blindly retry the other version.", error.status, error.serverCode);
   }
   if (operation === "draft" && error.status === 409) {
-    return new JoyApiError("conflict", "The requested widget version is currently live. This tool only writes the non-live draft so it cannot alter the storefront. Choose the other version or edit the live widget manually in Joy admin.", error.status);
+    return new JoyApiError("conflict", "The requested widget version is currently live. This tool only writes the non-live draft so it cannot alter the storefront. Choose the other version or edit the live widget manually in Joy admin.", error.status, error.serverCode);
   }
   return void 0;
 }
@@ -3781,7 +4680,7 @@ function errorWithoutCredential(error, credential) {
   if (!credential)
     return error;
   if (error instanceof JoyApiError) {
-    return new JoyApiError(error.kind, redactCredential(error.modelMessage, credential), error.status);
+    return new JoyApiError(error.kind, redactCredential(error.modelMessage, credential), error.status, error.serverCode);
   }
   if (error instanceof Error)
     return new Error(redactCredential(error.message, credential));
@@ -3934,7 +4833,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 +4899,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,22 +4921,40 @@ ${WIDGET_DRAFT_SAVED_MESSAGE}` : ""}`;
 
 // ../mcp-core/build/tools/widgetFields.js
 import { isDeepStrictEqual } from "node:util";
-import { z as z17 } from "zod";
+import { z as z21 } 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(fields2, current) {
+  const byPath = new Map(fields2.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 = z21.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: z21.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: z21.array(z21.object({
+    path: z21.string().min(1),
+    value: z21.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: z21.string().min(3).describe("Why the merchant wants these widget changes."),
+  apply: z21.boolean().optional().describe("Omit or set false for a dry run. Set true only after the merchant approves the preview.")
 };
 var MAX_FIELD_RESPONSE_CHARS = 12e3;
-function estimateSize(fields) {
-  return fields.reduce((total, field) => total + field.path.length + field.label.length + 60 + (field.values?.join("").length ?? 0), 0);
+function estimateSize(fields2) {
+  return fields2.reduce((total, field) => total + field.path.length + field.label.length + 60 + (field.values?.join("").length ?? 0), 0);
 }
 async function getWidgetFields(ctx, version2) {
   const { data } = await ctx.api.getData(fieldsPath, { query: { version: version2 } });
@@ -4047,30 +4964,30 @@ 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: z21.string().optional().describe("Return only this group. Omit to get the group index first."),
+      search: z21.string().optional().describe('Return only fields whose label or path contains this text, e.g. "corner" or "launcher".')
     },
     handler: async (args) => {
-      const fields = await getWidgetFields(ctx, args.version);
+      const fields2 = await getWidgetFields(ctx, args.version);
       const term = args.search?.trim().toLocaleLowerCase();
-      const matched = fields.filter((field) => (args.group === void 0 || field.group === args.group) && (term === void 0 || term === "" || field.label.toLocaleLowerCase().includes(term) || field.path.toLocaleLowerCase().includes(term)));
+      const matched = fields2.filter((field) => (args.group === void 0 || field.group === args.group) && (term === void 0 || term === "" || field.label.toLocaleLowerCase().includes(term) || field.path.toLocaleLowerCase().includes(term)));
       const wouldNotFit = estimateSize(matched) > MAX_FIELD_RESPONSE_CHARS;
       if (args.group === void 0 && !term && wouldNotFit) {
         const index = {};
-        for (const field of fields) {
+        for (const field of fields2) {
           const entry = index[field.group] ?? { fields: 0, examples: [] };
           entry.fields += 1;
           if (entry.examples.length < 2)
             entry.examples.push(field.path);
           index[field.group] = entry;
         }
-        return summaryWithJson(`${fields.length} settable ${args.version.toUpperCase()} widget fields across ${Object.keys(index).length} groups. Call again with group: "<name>" or search: "<text>" to see fields and their allowed values.`, { groups: index });
+        return summaryWithJson(`${fields2.length} settable ${args.version.toUpperCase()} widget fields across ${Object.keys(index).length} groups. Call again with group: "<name>" or search: "<text>" to see fields and their allowed values.`, { groups: index });
       }
       if (matched.length === 0) {
         return `No ${args.version.toUpperCase()} widget field matches ${args.group === void 0 ? `search "${args.search}"` : `group "${args.group}"`}. Call joy_get_widget_fields with no arguments to list the groups.`;
@@ -4081,7 +4998,7 @@ function registerWidgetFieldReadTools(server, ctx) {
         entries.push({ label, path, type, current, ...values === void 0 ? {} : { values } });
         groups.set(group, entries);
       }
-      return summaryWithJson(`${matched.length} of ${fields.length} settable ${args.version.toUpperCase()} widget fields. Use the server-provided paths and values when preparing changes.`, { groups: Object.fromEntries(groups) });
+      return summaryWithJson(`${matched.length} of ${fields2.length} settable ${args.version.toUpperCase()} widget fields. Use the server-provided paths and values when preparing changes.`, { groups: Object.fromEntries(groups) });
     }
   });
 }
@@ -4089,13 +5006,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 fields2 = expandLauncherHideFields(args.fields, current);
+      const changes = fields2.map(({ path, value }) => ({
         path,
         from: current.find((field) => field.path === path)?.current,
         to: value
@@ -4110,7 +5028,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: fields2 }
         });
       } catch (error) {
         throw brandingErrorGuidance(error, "draft", args.target) ?? error;
@@ -4123,23 +5041,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 fields2) {
         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 +5071,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 z22 } from "zod";
 var POPUP_DISPLAY_TYPES = ["auto_show_popup", "show_bubble_teaser", "do_not_show"];
 var REFERRAL_WIDGET_ARGUMENTS = {
   brand_color: "brandColor",
@@ -4169,24 +5087,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) => z22.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: z22.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: z22.string().trim().min(1).optional().describe("Referral-widget font family, for example Open+Sans."),
+  type_show_popup: z22.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: z22.boolean().optional().describe("Whether an automatically shown referral popup closes itself."),
+  closing_pop_up_time: z22.number().int().min(1).optional().describe("Auto-close delay in seconds; must be a positive integer."),
+  frequency_show_popup: z22.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: z22.boolean().optional().describe("Show the newsletter subscription option in the referral popup."),
+  reason: z22.string().min(3).describe("Why the merchant wants the live referral widget changed."),
+  apply: z22.boolean().optional().describe("Set true only after the merchant has approved the dry-run preview.")
 };
-var referralWidgetArgsSchema = z18.object(referralWidgetInputShape).strict();
+var referralWidgetArgsSchema = z22.object(referralWidgetInputShape).strict();
 function parseReferralWidgetArgs(input) {
   const parsed = referralWidgetArgsSchema.safeParse(input);
   if (parsed.success)
@@ -4252,6 +5170,369 @@ function registerReferralBrandingWriteTools(server, ctx) {
   });
 }
 
+// ../mcp-core/build/tools/redeemInCart.js
+import { z as z23 } 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 = z23.string().refine((value) => value === "" || isHexColor(value), "Use a hex color or an empty string to clear.");
+var https = z23.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 = z23.object({
+  fillType: z23.enum(fills).optional(),
+  colors: z23.array(z23.string()).min(1).max(2).optional(),
+  lastGradient: z23.enum(gradients).optional()
+}).strict();
+var colorFields = [
+  "text",
+  "dropdown",
+  "primary",
+  "buttonText",
+  "buttonHover",
+  "buttonHoverText",
+  "savings",
+  "sliderPrimary",
+  "sliderTrack",
+  "icon",
+  "dropdownAccent"
+];
+var colorsSchema = z23.object({
+  background: fill.optional(),
+  button: fill.optional(),
+  ...Object.fromEntries(colorFields.map((key) => [key, hex.optional()])),
+  buttonBorder: z23.string().optional(),
+  buttonHoverBorder: z23.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 = z23.object({
+  ...Object.fromEntries(cssShapeFields.map((key) => [key, z23.string().optional()])),
+  borderColor: hex.optional(),
+  patternColor: hex.optional(),
+  dividerColor: hex.optional(),
+  borderRadius: z23.enum(["none", "sharp", "soft", "rounded", "extra"]).optional(),
+  backgroundPattern: z23.enum(["none", "diagonal", "crosshatch", "grid", "column"]).optional(),
+  headingFont: z23.enum(fonts).optional(),
+  bodyFont: z23.enum(["", ...fonts]).optional(),
+  buttonFont: z23.enum(["", ...fonts]).optional(),
+  applyLoadingStyle: z23.enum(["spinner", "spinner-label", "dots"]).optional(),
+  buttonHoverEffect: z23.enum(["auto", "color", "fade", "lift", "none", "sweep"]).optional(),
+  boxShadow: z23.enum(["none", "small", "medium", "large", "hard"]).optional(),
+  iconName: z23.enum([
+    "gift",
+    "crown",
+    "shopping-bag",
+    "star",
+    "heart",
+    "trophy",
+    "sparkle",
+    "ticket",
+    "none"
+  ]).optional(),
+  iconImage: https.optional(),
+  backgroundImage: https.optional(),
+  backgroundImageOverlay: z23.number().min(0).max(100).optional(),
+  dividerWidth: z23.enum(["thin", "medium", "thick"]).optional(),
+  dividerStyle: z23.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, z23.boolean().optional()]));
+var common = { reason: z23.string().min(3), apply: z23.boolean().optional() };
+var behaviorArgs = z23.object({
+  ...behaviorInput,
+  position_mode: z23.enum(["above_cart_summary", "custom"]).optional(),
+  custom_type: z23.enum(["snippet", "selector"]).optional(),
+  css_selector: z23.string().optional(),
+  ...common
+}).strict();
+var designArgs = z23.object({
+  style: z23.enum(styles).optional(),
+  set_active: z23.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(z23.object({ style: z23.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: z23.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 +5560,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 +5579,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,26 +5592,26 @@ function registerThemeSetupTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/imageUpload.js
-import { z as z19 } from "zod";
+import { z as z24 } 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: z24.string().url().optional().describe("Public URL of an already hosted image. Provide exactly one of source_url or data_url."),
+  data_url: z24.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: z24.string().min(1).max(200).optional().describe("Filename to use for the uploaded image."),
+  alt: z24.string().max(512).optional().describe("Merchant-provided alternative text for the image."),
+  reason: z24.string().min(3).describe("Why the merchant wants this image uploaded."),
+  apply: z24.boolean().optional().describe("Omit or set false for a dry run. Set true only after the merchant approves the preview.")
 };
 function imageUploadErrorGuidance(error) {
   if (!(error instanceof JoyApiError))
     return void 0;
   if (error.status === 400) {
-    return new JoyApiError("validation", "The image source was rejected (not an image, unsupported type, or a blocked URL). Do not retry the same input.", error.status);
+    return new JoyApiError("validation", "The image source was rejected (not an image, unsupported type, or a blocked URL). Do not retry the same input.", error.status, error.serverCode);
   }
   if (error.status === 413) {
-    return new JoyApiError("validation", "The image is too large; the upload cap is 20 MB. Resize or compress it before trying again.", error.status);
+    return new JoyApiError("validation", "The image is too large; the upload cap is 20 MB. Resize or compress it before trying again.", error.status, error.serverCode);
   }
   if (error.status === 502) {
-    return new JoyApiError("server", "Shopify rejected the upload or the file never went live. Safe to retry ONCE; if it fails again, stop and report the failure to the merchant.", error.status);
+    return new JoyApiError("server", "Shopify rejected the upload or the file never went live. Safe to retry ONCE; if it fails again, stop and report the failure to the merchant.", error.status, error.serverCode);
   }
   return void 0;
 }
@@ -4336,7 +5619,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 +5644,14 @@ function registerImageUploadTools(server, ctx) {
 }
 
 // ../mcp-core/build/prompts.js
-import { z as z20 } from "zod";
+import { z as z25 } 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: z25.string().describe("Customer's email address"),
+      order_number: z25.string().optional().describe("Order name/number the customer says earned nothing, e.g. #1234")
     }
   }, ({ email, order_number }) => ({
     messages: [
@@ -4395,7 +5678,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: z25.string().optional().describe("Reporting period, e.g. 'last 30 days', 'last month', 'this quarter'. Defaults to last 30 days.")
     }
   }, ({ period }) => ({
     messages: [
@@ -4426,7 +5709,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: z25.string().describe("Email of the member to investigate")
     }
   }, ({ email }) => ({
     messages: [
@@ -4453,8 +5736,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: z25.string().optional().describe("Business type, e.g. 'fashion' or 'coffee shop'."),
+      goal: z25.string().optional().describe("Primary loyalty goal, e.g. 'increase repeat purchases'.")
     }
   }, ({ business_type, goal }) => ({
     messages: [
@@ -4479,7 +5762,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: z25.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 +5789,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: z25.string().optional().describe("Optional setup focus, e.g. 'loyalty widget', 'points calculator', or 'loyalty page'.")
     }
   }, ({ focus }) => ({
     messages: [
@@ -4544,16 +5827,25 @@ function registerAllTools(server, ctx) {
   registerOrderExplainTools(server, ctx);
   registerActivityAuditTools(server, ctx);
   registerTierUpgradeTools(server, ctx);
+  registerLoyaltyPageTools(server, ctx);
+  registerLoyaltyPageTextTools(server, ctx);
+  registerLoyaltyHubTools(server, ctx);
+  registerLoyaltyHubTextTools(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);
-    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.");
+    registerLoyaltyPageWriteTools(server, ctx);
+    registerLoyaltyPageTextWriteTools(server, ctx);
+    registerLoyaltyHubWriteTools(server, ctx);
+    registerLoyaltyHubTextWriteTools(server, ctx);
+    log.info("write tools ENABLED (award/deduct/adjust/redeem/set-tier/refund-coupon/create-referral-invite/enable-analytics-v2/loyalty-hub-design/loyalty-hub-text). Requires the deployed REST v2 write-path (reason/source/Idempotency-Key support) \u2014 against an older backend, reason/source are silently dropped and idempotency is not enforced.");
   }
   if (ctx.config.configWritesEnabled) {
     registerProgramConfigTools(server, ctx);
@@ -4563,24 +5855,492 @@ 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.");
   }
 }
 
+// ../mcp-core/build/telemetry/knownTools.js
+var KNOWN_TOOLS = Object.freeze({
+  joy_add_translation_language: "config_write",
+  joy_adjust_points: "write",
+  joy_award_points: "write",
+  joy_check_theme_setup: "read",
+  joy_configure_earning_program: "config_write",
+  joy_configure_redeem_in_cart: "config_write",
+  joy_configure_redeem_in_cart_design: "config_write",
+  joy_configure_redemption_program: "config_write",
+  joy_configure_referral_program: "config_write",
+  joy_configure_referral_widget: "config_write",
+  joy_configure_shop_settings: "config_write",
+  joy_configure_tier: "config_write",
+  joy_configure_tier_perks: "config_write",
+  joy_configure_tier_reward: "config_write",
+  joy_configure_tier_settings: "config_write",
+  joy_configure_widget_draft: "config_write",
+  joy_create_referral_invite: "write",
+  joy_deduct_points: "write",
+  joy_enable_analytics_v2: "write",
+  joy_explain_order_points: "read",
+  joy_find_member: "read",
+  joy_get_analytics_report: "read",
+  joy_get_loyalty_health_check: "read",
+  joy_get_loyalty_hub_design: "read",
+  joy_get_loyalty_hub_text: "read",
+  joy_get_loyalty_overview: "read",
+  joy_get_loyalty_page_design: "read",
+  joy_get_loyalty_page_text: "read",
+  joy_get_loyalty_revenue_report: "read",
+  joy_get_member_activity: "read",
+  joy_get_member_referrals: "read",
+  joy_get_member_rewards: "read",
+  joy_get_member_store_credit: "read",
+  joy_get_redeem_in_cart: "read",
+  joy_get_referral_performance: "read",
+  joy_get_referral_program: "read",
+  joy_get_retention_risk_members: "read",
+  joy_get_tier_performance_breakdown: "read",
+  joy_get_tier_upgrade_candidates: "read",
+  joy_get_widget_fields: "read",
+  joy_investigate_member_risk: "read",
+  joy_list_activities: "read",
+  joy_list_earning_rules: "read",
+  joy_list_members: "read",
+  joy_list_redemption_rules: "read",
+  joy_list_tiers: "read",
+  joy_redeem_reward: "write",
+  joy_refund_coupon: "write",
+  joy_revert_loyalty_hub_design: "write",
+  joy_revert_loyalty_hub_text: "write",
+  joy_revert_loyalty_page_design: "write",
+  joy_scan_brand_design: "read",
+  joy_set_member_tier: "write",
+  joy_set_widget_fields: "config_write",
+  joy_update_loyalty_hub_design: "write",
+  joy_update_loyalty_hub_text: "write",
+  joy_update_loyalty_page_design: "write",
+  joy_update_loyalty_page_text: "write",
+  joy_upload_image: "config_write"
+});
+
+// ../mcp-core/build/telemetry/recorder.js
+import { randomUUID as randomUUID2 } from "node:crypto";
+var fields = TELEMETRY_SCHEMA.events["mcp.tool_call"].fields;
+var toMillis = (value) => Math.min(36e5, Math.max(0, Math.round(value)));
+function classify(record, response, { exposed, known = KNOWN_TOOLS }) {
+  let outcome = record.outcome ?? "internal_error";
+  let error_kind = record.error_kind;
+  if ("error" in response) {
+    outcome = "internal_error";
+    error_kind = "jsonrpc_error";
+  } else if (!record.entered && "result" in response && response.result.isError) {
+    outcome = "rejected";
+    error_kind = exposed.has(record.tool) ? "invalid_input" : Object.hasOwn(known, record.tool) ? "tool_not_exposed" : "unknown_tool";
+  } else if (!record.outcome) {
+    error_kind = "unclassified";
+  }
+  const result = "result" in response ? response.result : void 0;
+  const content = Array.isArray(result?.content) ? result.content : [];
+  const result_bytes = content.reduce((sum, item) => sum + (typeof item?.text === "string" ? Buffer.byteLength(item.text, "utf8") : 0), 0);
+  return {
+    tool_kind: Object.hasOwn(known, record.tool) ? known[record.tool] : "unknown",
+    outcome,
+    ...outcome !== "success" && error_kind ? { error_kind } : {},
+    ...outcome === "tool_error" && record.error_code ? { error_code: record.error_code } : {},
+    ...outcome === "tool_error" && record.http_status ? { http_status: record.http_status } : {},
+    result_bytes: Math.min(1e9, result_bytes)
+  };
+}
+function createRecorder({ sink, base: inputBase, receivedAt, sweepTtlMs, now = performance.now.bind(performance) }) {
+  const base = {};
+  telemetrySafe("base", () => {
+    for (const [key, value] of Object.entries(inputBase)) {
+      const clean = sanitizeString(TELEMETRY_SCHEMA, "mcp.session_start", key, value);
+      if (clean !== void 0)
+        base[key] = clean;
+    }
+  });
+  const pending = /* @__PURE__ */ new Map();
+  const exposed = /* @__PURE__ */ new Set();
+  const instrumented = /* @__PURE__ */ new WeakSet();
+  let closed = false;
+  let initialized = false;
+  function emit(event) {
+    const transport = inputBase.transport;
+    const checked = validateEvent(TELEMETRY_SCHEMA, event, { mode: transport === "stdio" ? "client" : "full", transport });
+    if (!checked.ok) {
+      reportOnce(`invalid ${checked.errors[0]}`);
+      return;
+    }
+    sink.emit(checked.event);
+  }
+  function finish(id, record, response) {
+    if (record.closed || pending.get(id) !== record)
+      return;
+    record.closed = true;
+    pending.delete(id);
+    const elapsed = now();
+    const duration_ms = toMillis(elapsed - record.t0);
+    const busy = record.api_inflight ? elapsed - (record.api_busy_since ?? elapsed) : 0;
+    emit({
+      ...base,
+      event: "mcp.tool_call",
+      schema_version: 1,
+      event_id: randomUUID2(),
+      call_id: record.call_id,
+      tool: record.tool,
+      ...classify(record, response, { exposed }),
+      duration_ms,
+      ...base.transport === "remote" && receivedAt !== void 0 ? { pre_ms: toMillis(record.t0 - receivedAt) } : {},
+      api_calls: Math.min(1e4, record.api_calls),
+      api_ms: Math.min(duration_ms, toMillis(record.api_ms_acc + busy))
+    });
+  }
+  function cancel(id, record, outcome, kind) {
+    record.outcome = outcome;
+    record.error_kind = kind;
+    finish(id, record, { jsonrpc: "2.0", id, result: {} });
+  }
+  function buildHeaders(call_id, tool) {
+    const values = { call_id, tool, ...base };
+    const mapping = {
+      call_id: "Call-Id",
+      tool: "Tool",
+      transport: "Transport",
+      server_version: "Version",
+      ...base.transport === "stdio" ? { mcp_client_name: "Client", session_id: "Session" } : {}
+    };
+    const result = {};
+    for (const [field, suffix] of Object.entries(mapping)) {
+      const value = sanitizeString(TELEMETRY_SCHEMA, "mcp.tool_call", field, values[field]);
+      if (value !== void 0)
+        result[`X-Joy-Mcp-${suffix}`] = value;
+    }
+    return Object.freeze(result);
+  }
+  const timer = sweepTtlMs === void 0 ? void 0 : setInterval(() => {
+    for (const [id, record] of pending) {
+      telemetrySafe("sweep", () => {
+        if (now() - record.t0 >= sweepTtlMs)
+          cancel(id, record, "cancelled", "no_response");
+      });
+    }
+  }, 6e4);
+  timer?.unref();
+  return {
+    expose(name) {
+      telemetrySafe("expose", () => {
+        if (sanitizeString(TELEMETRY_SCHEMA, "mcp.tool_call", "tool", name))
+          exposed.add(name);
+      });
+    },
+    instrumentTransport(transport) {
+      telemetrySafe("instrument", () => {
+        if (instrumented.has(transport))
+          return;
+        instrumented.add(transport);
+        if (!transport.onmessage)
+          reportOnce("instrumentTransport called before connect");
+        const onmessage = transport.onmessage;
+        const send = transport.send;
+        transport.onmessage = function(message, extra) {
+          const record = telemetrySafe("receive", () => {
+            if (closed || !("method" in message))
+              return;
+            const params = message.params;
+            if (message.method === "initialize" && !(base.transport === "stdio" && initialized)) {
+              initialized = true;
+              const info = params?.clientInfo;
+              const session = {
+                ...base,
+                event: "mcp.session_start",
+                schema_version: 1,
+                event_id: randomUUID2(),
+                tools_exposed: exposed.size
+              };
+              const capabilities = Object.keys(params?.capabilities ?? {}).filter((key) => /^[a-z][a-zA-Z0-9_]{0,31}$/.test(key)).sort().slice(0, 10).join(",");
+              for (const [key, value] of Object.entries({
+                mcp_client_name: info?.name,
+                mcp_client_version: info?.version,
+                protocol_version: params?.protocolVersion,
+                client_capabilities: capabilities
+              })) {
+                const clean = sanitizeString(TELEMETRY_SCHEMA, "mcp.session_start", key, value);
+                if (clean === void 0)
+                  continue;
+                session[key] = clean;
+                if (base.transport === "stdio" && fields[key])
+                  base[key] = clean;
+              }
+              emit(session);
+            }
+            if (message.method === "notifications/cancelled" && base.transport === "stdio") {
+              const id = params?.requestId;
+              const previous2 = pending.get(id);
+              if (previous2)
+                cancel(id, previous2, "cancelled", "client_cancelled");
+            }
+            if (message.method !== "tools/call" || !("id" in message))
+              return;
+            const previous = pending.get(message.id);
+            if (previous)
+              telemetrySafe("duplicate", () => cancel(message.id, previous, "internal_error", "duplicate_request_id"));
+            const tool = sanitizeString(TELEMETRY_SCHEMA, "mcp.tool_call", "tool", params?.name) ?? "invalid_name";
+            const call_id = randomUUID2();
+            const record2 = {
+              call_id,
+              tool,
+              t0: now(),
+              entered: false,
+              closed: false,
+              api_calls: 0,
+              api_inflight: 0,
+              api_ms_acc: 0,
+              headers: buildHeaders(call_id, tool),
+              now
+            };
+            pending.set(message.id, record2);
+            return record2;
+          });
+          if (record)
+            return als.run(record, () => onmessage?.call(this, message, extra));
+          return onmessage?.call(this, message, extra);
+        };
+        transport.send = function(...args) {
+          telemetrySafe("send", () => {
+            const message = args[0];
+            if (!("id" in message) || message.id === void 0 || !("result" in message || "error" in message))
+              return;
+            const record = currentCall() ?? pending.get(message.id);
+            if (record)
+              finish(message.id, record, message);
+          });
+          return send.apply(this, args);
+        };
+      });
+    },
+    close() {
+      closed = true;
+      if (timer)
+        clearInterval(timer);
+      for (const [id, record] of pending) {
+        telemetrySafe("close", () => cancel(id, record, "cancelled", "no_response"));
+      }
+    }
+  };
+}
+
+// ../mcp-core/build/telemetry/sinks.js
+var noopSink = { emit() {
+} };
+function createRelaySink({ apiBaseUrl, authHeaders: authHeaders2, fetchImpl = fetch, now = Date.now, timers = globalThis }) {
+  const queue = [];
+  let disabled = false;
+  let dueAt = 0;
+  let timer;
+  let active;
+  let flushing;
+  const headers = { "Content-Type": "application/json" };
+  telemetrySafe("relay_headers", () => {
+    for (const [key, value] of Object.entries(authHeaders2)) {
+      if (["x-joy-loyalty-app-key", "x-joy-loyalty-secret-key", "x-joy-private-bot-key"].includes(key.toLowerCase()))
+        headers[key] = value;
+    }
+  });
+  function clearTimer() {
+    if (timer)
+      timers.clearTimeout(timer);
+    timer = void 0;
+  }
+  function schedule() {
+    if (disabled || flushing || queue.length === 0)
+      return;
+    if (!active && queue.length >= 20) {
+      startBatch();
+      return;
+    }
+    if (timer)
+      return;
+    timer = timers.setTimeout(() => {
+      timer = void 0;
+      telemetrySafe("relay_timer", () => {
+        if (!active)
+          startBatch();
+      });
+    }, Math.max(0, dueAt - now()));
+    timer.unref();
+  }
+  function startBatch() {
+    if (active)
+      return active.done;
+    if (disabled || queue.length === 0)
+      return Promise.resolve();
+    clearTimer();
+    const events = queue.splice(0, 50);
+    const controller = new AbortController();
+    let release;
+    const cancelled = new Promise((resolve) => {
+      release = resolve;
+    });
+    const abort = () => {
+      controller.abort();
+      release();
+    };
+    const timeout = timers.setTimeout(abort, 15e3);
+    timeout.unref();
+    const request = Promise.resolve().then(async () => {
+      if (controller.signal.aborted)
+        return;
+      const response = await fetchImpl(`${apiBaseUrl.replace(/\/$/, "")}/rest_api/v2/internal/mcp-telemetry`, {
+        method: "POST",
+        redirect: "error",
+        headers,
+        body: JSON.stringify({ schema_version: 1, events }),
+        signal: controller.signal
+      });
+      let dailyQuotaExceeded = false;
+      if (response.status === 429) {
+        const body = await response.json().catch(() => void 0);
+        dailyQuotaExceeded = body !== null && typeof body === "object" && "error" in body && body.error === "daily_quota_exceeded";
+      }
+      if ([401, 403, 404, 410].includes(response.status) || dailyQuotaExceeded) {
+        disabled = true;
+        queue.length = 0;
+        clearTimer();
+      }
+      if (!response.ok)
+        throw new Error("relay rejected");
+      await response.body?.cancel();
+    }).catch(() => {
+      telemetrySafe("relay_request", () => {
+        throw new Error("relay request failed");
+      });
+    });
+    const done = Promise.race([request, cancelled]).then(() => {
+      timers.clearTimeout(timeout);
+      active = void 0;
+      telemetrySafe("relay_schedule", schedule);
+    });
+    active = { done, abort };
+    return done;
+  }
+  async function flush(deadlineMs) {
+    clearTimer();
+    const deadline = now() + Math.max(0, deadlineMs);
+    let expired = false;
+    let release;
+    const timeout = new Promise((resolve) => {
+      release = resolve;
+    });
+    const end = timers.setTimeout(() => {
+      expired = true;
+      queue.length = 0;
+      active?.abort();
+      release();
+    }, Math.max(0, deadlineMs));
+    try {
+      while (!expired && !disabled && (active || queue.length)) {
+        if (now() >= deadline) {
+          queue.length = 0;
+          active?.abort();
+          break;
+        }
+        await Promise.race([active?.done ?? startBatch(), timeout]);
+      }
+    } finally {
+      timers.clearTimeout(end);
+    }
+  }
+  return {
+    get disabled() {
+      return disabled;
+    },
+    emit(event) {
+      telemetrySafe("relay_emit", () => {
+        if (disabled)
+          return;
+        if (!TELEMETRY_SCHEMA.ingest_events.includes(event.event))
+          return;
+        const fields2 = TELEMETRY_SCHEMA.events[event.event].fields;
+        const client = Object.fromEntries(Object.entries(event).filter(([key]) => !fields2[key]?.server_stamped));
+        const checked = validateEvent(TELEMETRY_SCHEMA, client, { mode: "client", transport: "stdio" });
+        if (!checked.ok)
+          return;
+        if (queue.length >= 200)
+          queue.shift();
+        if (queue.length === 0)
+          dueAt = now() + 1e4;
+        queue.push(checked.event);
+        schedule();
+      });
+    },
+    flushNow(deadlineMs) {
+      if (flushing)
+        return flushing;
+      flushing = Promise.resolve().then(() => flush(deadlineMs)).catch(() => {
+        telemetrySafe("relay_flush", () => {
+          throw new Error("relay flush failed");
+        });
+      }).finally(() => {
+        flushing = void 0;
+      });
+      return flushing;
+    }
+  };
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
 async function main() {
   const config = loadConfig();
   const api = new JoyApi(config);
+  const mode = telemetryMode();
+  const relay = mode === "full" ? createRelaySink({ apiBaseUrl: config.apiBaseUrl, authHeaders: authHeaders(config) }) : void 0;
+  const telemetry = mode === "off" ? void 0 : createRecorder({
+    sink: relay ?? noopSink,
+    base: { transport: "stdio", server_version: version, session_id: randomUUID3() },
+    sweepTtlMs: 6e5
+  });
+  if (relay) {
+    let exiting = false;
+    let exitWork;
+    const shutdown = async (signal = false) => {
+      if (!exiting) {
+        exiting = true;
+        telemetry?.close();
+        exitWork = relay.flushNow(2e3);
+      }
+      if (signal) {
+        await exitWork;
+        process.exit(0);
+      }
+    };
+    process.stdin.on("end", () => {
+      void shutdown();
+    });
+    process.stdin.on("close", () => {
+      void shutdown();
+    });
+    process.on("beforeExit", () => {
+      void shutdown();
+    });
+    process.on("SIGINT", () => {
+      void shutdown(true);
+    });
+    process.on("SIGTERM", () => {
+      void shutdown(true);
+    });
+  }
   const server = new McpServer({ name: "joy-loyalty", version });
-  registerAllTools(server, { api, config, cache: new TtlCache() });
+  registerAllTools(server, { api, config, cache: new TtlCache(), telemetry });
   registerAllPrompts(server);
   const transport = new StdioServerTransport();
   await server.connect(transport);
+  telemetry?.instrumentTransport(transport);
   log.info(
-    `joy-mcp v${version} ready \u2014 mode=${config.mode}, tools=${config.writesEnabled ? "read+write" : "read-only"}, api=${config.apiBaseUrl}`
+    `joy-mcp v${version} ready \u2014 mode=${config.mode}, tools=${config.writesEnabled ? "read+write" : "read-only"}, api=${config.apiBaseUrl}, telemetry=${mode}`
   );
 }
 main().catch((error) => {