@blamejs/blamejs-shop 0.3.23 → 0.3.25

package/lib/admin.js

@@ -33,6 +33,8 @@
 var pricing = require("./pricing");
 var collectionsModule = require("./collections");
 var quantityDiscountsModule = require("./quantity-discounts");
+var loyaltyEarnRulesModule = require("./loyalty-earn-rules");
+var loyaltyRedemptionModule = require("./loyalty-redemption");
 var textGuard = require("./text-guard");
 var { AsyncLocalStorage } = require("node:async_hooks");   // allow:non-shop-require — Node-core per-request context (no npm dep); the framework itself composes it in db-role-context / log. No b.* request-context primitive exists to wrap it.
 
@@ -495,6 +497,9 @@ function mount(router, deps) {
   var productQa     = deps.productQa     || null;   // Q&A moderation endpoints disabled when absent
   var returns       = deps.returns       || null;   // RMA moderation endpoints disabled when absent
   var customers     = deps.customers     || null;   // read-only customers console disabled when absent
+  var storeCredit      = deps.storeCredit      || null;  // per-customer store-credit panel + grant/deduct disabled when absent
+  var customerNotes    = deps.customerNotes    || null;  // per-customer CRM notes panel disabled when absent
+  var customerSegments = deps.customerSegments || null;  // per-customer segment-membership panel disabled when absent
   var orderTracking = deps.orderTracking || null;   // shipment/tracking panel disabled when absent
   var salesReports  = deps.salesReports  || null;   // /admin/reports degrades to an unconfigured notice when absent
   var printReceipts = deps.printReceipts || null;   // order receipt document disabled when absent
@@ -510,7 +515,7 @@ function mount(router, deps) {
   // `reports` is always present in the nav (read-only sales summary needs no
   // extra dep); its route mounts unconditionally and renders an unconfigured
   // notice when the salesReports primitive isn't wired.
-  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, blog: !!deps.blog, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels };
+  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, blog: !!deps.blog, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -2595,6 +2600,276 @@ function mount(router, deps) {
         }));
       },
     ));
+
+    // ---- customer detail ----------------------------------------------
+    // The per-customer operator screen. The roster (above) is read-only by
+    // design — the storefront owns account mutation via the passkey / OIDC
+    // ceremonies — so this screen READS the customer's identity fields +
+    // recent orders, and WRITES only the operator-managed satellites:
+    // store-credit (an audited wallet), CRM notes, and (read-only) segment
+    // membership. It does NOT edit the customer profile: the only mutable
+    // identity field is display_name, and the roster's stated design intent
+    // is read-only identity, so the operator-managed satellites are the
+    // write surface here. Each satellite panel renders only when its
+    // primitive is wired; an unwired one degrades to a "not wired" notice
+    // rather than vanishing.
+
+    // Free-text reason gate for a store-credit adjustment. A store-credit
+    // grant / deduct is a money-adjacent action, so the reason is MANDATORY
+    // — it rides into the ledger row's source_ref (grant) / reason (deduct)
+    // column so every balance change is attributed. Throws a TypeError
+    // (→ 400) on a missing / blank / over-long / control-byte reason so the
+    // form surfaces a clean notice and writes nothing. 128 chars matches the
+    // primitive's source_ref cap (storeCredit MAX_SOURCE_REF_LEN); the
+    // primitive re-validates, so this gate fails fast with operator-facing
+    // text rather than relying on the deeper throw.
+    var STORE_CREDIT_REASON_MAX = 128;
+    function _storeCreditReason(raw) {
+      if (raw == null) throw new TypeError("admin: a reason is required for a store-credit adjustment");
+      var s = String(raw).trim();
+      if (!s.length) throw new TypeError("admin: a reason is required for a store-credit adjustment");
+      if (s.length > STORE_CREDIT_REASON_MAX) throw new TypeError("admin: reason must be <= " + STORE_CREDIT_REASON_MAX + " chars");
+      if (/[\x00-\x1f\x7f]/.test(s)) throw new TypeError("admin: reason must not contain control bytes");
+      return s;
+    }
+    // Coerce the grant/deduct form into a positive minor-unit amount + a
+    // direction. `direction` is "grant" or "deduct"; `amount_minor` is a
+    // positive integer (the strict reader refuses "", floats, "12abc").
+    function _storeCreditDirection(body) {
+      var dir = typeof body.direction === "string" ? body.direction.trim() : "";
+      if (dir !== "grant" && dir !== "deduct") {
+        throw new TypeError("admin: direction must be 'grant' or 'deduct'");
+      }
+      return dir;
+    }
+
+    // Best-effort hydrate of a customer's satellites for the detail render.
+    // A satellite whose primitive isn't wired (or whose table isn't migrated
+    // on a given deploy) degrades that panel to a notice rather than 500-ing
+    // the page — same discipline as the order-detail tracking panel.
+    async function _customerDetailModel(customer, flags) {
+      flags = flags || {};
+      var currency = await _defaultCurrency();
+
+      var recentOrders = [];
+      try {
+        var ordersPage = await order.listForCustomer(customer.id, { limit: 10 });
+        recentOrders = ordersPage.rows || [];
+      } catch (_e) { recentOrders = []; }
+
+      var creditBalanceMinor = null;
+      var creditHistory = [];
+      if (storeCredit) {
+        try { creditBalanceMinor = (await storeCredit.balance(customer.id)).balance_minor; }
+        catch (_e) { creditBalanceMinor = null; }
+        try { creditHistory = (await storeCredit.history({ customer_id: customer.id, limit: 10 })).rows || []; }
+        catch (_e) { creditHistory = []; }
+      }
+
+      var loyaltyInfo = null;
+      if (deps.loyalty) {
+        try { loyaltyInfo = await deps.loyalty.balance(customer.id); }
+        catch (_e) { loyaltyInfo = null; }
+      }
+
+      var notes = [];
+      if (customerNotes) {
+        try { notes = (await customerNotes.notesForCustomer({ customer_id: customer.id, limit: 20 })).rows || []; }
+        catch (_e) { notes = []; }
+      }
+
+      var segments = null;
+      if (customerSegments) {
+        try { segments = await customerSegments.segmentsForCustomer(customer.id); }
+        catch (_e) { segments = []; }
+      }
+
+      return Object.assign({
+        shop_name:      deps.shop_name,
+        nav_available:  navAvailable,
+        customer:       customer,
+        currency:       currency,
+        recent_orders:  recentOrders,
+        can_store_credit:    !!storeCredit,
+        store_credit_minor:  creditBalanceMinor,
+        store_credit_history: creditHistory,
+        loyalty:        loyaltyInfo,
+        loyalty_link:   !!deps.loyalty,
+        can_notes:      !!customerNotes,
+        notes:          notes,
+        can_segments:   !!customerSegments,
+        segments:       segments,
+      }, flags);
+    }
+
+    // Resolve the :id to a customer record. A malformed id throws inside the
+    // defensive id reader (customers.get) — caught and treated as "no such
+    // customer" so the route renders a clean 404, never a 500. An unknown
+    // (well-formed) id returns null → the same 404.
+    async function _resolveCustomer(id) {
+      try { return await customers.get(id); }
+      catch (e) { if (e instanceof TypeError) return null; throw e; }
+    }
+
+    router.get("/admin/customers/:id", _pageOrApi(true,
+      R(async function (req, res) {
+        var c = await _resolveCustomer(req.params.id);
+        if (!c) return _problem(res, 404, "customer-not-found");
+        // Bearer JSON: the customer record + its satellites (no HTML).
+        var model = await _customerDetailModel(c, {});
+        _json(res, 200, {
+          customer:             c,
+          recent_orders:        model.recent_orders,
+          store_credit_minor:   model.store_credit_minor,
+          store_credit_history: model.store_credit_history,
+          loyalty:              model.loyalty,
+          notes:                model.notes,
+          segments:             model.segments,
+        });
+      }),
+      async function (req, res) {
+        var c = await _resolveCustomer(req.params.id);
+        if (!c) return _sendHtml(res, 404, renderAdminCustomers({
+          shop_name: deps.shop_name, nav_available: navAvailable, customers: [], notice: "Customer not found.",
+        }));
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var flags = {
+          saved:        url && url.searchParams.get("saved"),
+          credit_notice: url && url.searchParams.get("credit_err") ? url.searchParams.get("credit_err") : null,
+          note_notice:   url && url.searchParams.get("note_err") ? url.searchParams.get("note_err") : null,
+        };
+        _sendHtml(res, 200, renderAdminCustomerDetail(await _customerDetailModel(c, flags)));
+      },
+    ));
+
+    // ---- store-credit adjustment (grant / deduct) ----------------------
+    // Scoped to the :id customer — the customer the adjustment targets is the
+    // path id, never a form field, so an operator can't grant credit to a
+    // different customer than the screen they're on. A grant composes
+    // storeCredit.credit (source goodwill / source_ref reason); a deduct
+    // composes storeCredit.expire (the operator-initiated burn that carries a
+    // required reason). Over-deduction is refused at the route as a clean 409
+    // BEFORE any write — the expire primitive caps silently at the balance,
+    // so the route enforces the no-overdraft contract by reading the balance
+    // first (nothing is written when the deduction exceeds the balance).
+    if (storeCredit) {
+      router.post("/admin/customers/:id/store-credit", _pageOrApi(false,
+        W("customer.store_credit.adjust", async function (req, res) {
+          var c = await _resolveCustomer(req.params.id);
+          if (!c) return _problem(res, 404, "customer-not-found");
+          var body = req.body || {};
+          var dir, amount, reason;
+          try {
+            dir    = _storeCreditDirection(body);
+            amount = _strictMinorInt(body.amount_minor, "admin", "amount_minor");
+            if (amount <= 0) throw new TypeError("admin: amount_minor must be a positive integer (minor units)");
+            reason = _storeCreditReason(body.reason);
+          } catch (e) {
+            if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+            throw e;
+          }
+          var result;
+          if (dir === "grant") {
+            result = await storeCredit.credit({
+              customer_id: c.id, amount_minor: amount, source: "goodwill", source_ref: reason,
+            });
+          } else {
+            var bal = (await storeCredit.balance(c.id)).balance_minor;
+            if (amount > bal) {
+              return _problem(res, 409, "insufficient-balance", "Deduction exceeds the available store-credit balance.");
+            }
+            result = await storeCredit.expire({ customer_id: c.id, amount_minor: amount, reason: reason });
+          }
+          _json(res, 200, result);
+          return { id: c.id };
+        }),
+        async function (req, res) {
+          var c = await _resolveCustomer(req.params.id);
+          if (!c) return _sendHtml(res, 404, renderAdminCustomers({
+            shop_name: deps.shop_name, nav_available: navAvailable, customers: [], notice: "Customer not found.",
+          }));
+          var body = req.body || {};
+          var dir, amount, reason;
+          try {
+            dir    = _storeCreditDirection(body);
+            amount = _strictMinorInt(body.amount_minor, "admin", "amount_minor");
+            if (amount <= 0) throw new TypeError("admin: amount_minor must be a positive integer (minor units)");
+            reason = _storeCreditReason(body.reason);
+          } catch (e) {
+            var n = _safeNotice(e, "customer.store_credit.adjust");
+            return _redirect(res, "/admin/customers/" + encodeURIComponent(c.id) +
+              "?credit_err=" + encodeURIComponent(n.message.replace(/^admin[.:]\s*/, "")));
+          }
+          if (dir === "deduct") {
+            var bal = (await storeCredit.balance(c.id)).balance_minor;
+            if (amount > bal) {
+              return _redirect(res, "/admin/customers/" + encodeURIComponent(c.id) +
+                "?credit_err=" + encodeURIComponent("That deduction exceeds the available balance."));
+            }
+          }
+          try {
+            if (dir === "grant") {
+              await storeCredit.credit({ customer_id: c.id, amount_minor: amount, source: "goodwill", source_ref: reason });
+            } else {
+              await storeCredit.expire({ customer_id: c.id, amount_minor: amount, reason: reason });
+            }
+          } catch (e) {
+            var n2 = _safeNotice(e, "customer.store_credit.adjust");
+            return _redirect(res, "/admin/customers/" + encodeURIComponent(c.id) +
+              "?credit_err=" + encodeURIComponent(n2.message.replace(/^(?:admin|storeCredit)[.:]\s*/, "")));
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".customer.store_credit.adjust", outcome: "success", metadata: { id: c.id, direction: dir } });
+          _redirect(res, "/admin/customers/" + encodeURIComponent(c.id) + "?saved=1");
+        },
+      ));
+    }
+
+    // ---- customer notes (add) ------------------------------------------
+    // Scoped to the :id customer — the note attaches to the path customer.
+    // Composes customerNotes.addNote (the body is required + length-capped by
+    // the primitive). The author is stamped "operator" — the console never
+    // adds a system note. Bad input (empty / over-long body, bad kind) is a
+    // clean 4xx with nothing written.
+    if (customerNotes) {
+      router.post("/admin/customers/:id/notes", _pageOrApi(false,
+        W("customer.note.add", async function (req, res) {
+          var c = await _resolveCustomer(req.params.id);
+          if (!c) return _problem(res, 404, "customer-not-found");
+          var body = req.body || {};
+          var note;
+          try {
+            note = await customerNotes.addNote({
+              customer_id: c.id, author: "operator",
+              body: body.body, kind: (body.kind != null && body.kind !== "") ? body.kind : undefined,
+            });
+          } catch (e) {
+            if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+            throw e;
+          }
+          _json(res, 201, note);
+          return { id: c.id };
+        }),
+        async function (req, res) {
+          var c = await _resolveCustomer(req.params.id);
+          if (!c) return _sendHtml(res, 404, renderAdminCustomers({
+            shop_name: deps.shop_name, nav_available: navAvailable, customers: [], notice: "Customer not found.",
+          }));
+          var body = req.body || {};
+          try {
+            await customerNotes.addNote({
+              customer_id: c.id, author: "operator",
+              body: body.body, kind: (body.kind != null && body.kind !== "") ? body.kind : undefined,
+            });
+          } catch (e) {
+            var n = _safeNotice(e, "customer.note.add");
+            return _redirect(res, "/admin/customers/" + encodeURIComponent(c.id) +
+              "?note_err=" + encodeURIComponent(n.message.replace(/^(?:admin|customerNotes)[.:]\s*/, "")));
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".customer.note.add", outcome: "success", metadata: { id: c.id } });
+          _redirect(res, "/admin/customers/" + encodeURIComponent(c.id) + "?saved=1");
+        },
+      ));
+    }
   }
 
   // ---- refunds --------------------------------------------------------
@@ -6628,6 +6903,535 @@ function mount(router, deps) {
     ));
   }
 
+  // ---- loyalty --------------------------------------------------------
+  // Manage the loyalty program from the console: the earn rules that mint
+  // points, the rewards catalog customers redeem against, and a direct
+  // per-customer points adjustment (grant / deduct with a required reason,
+  // recorded in the loyalty ledger). The customer-facing /account/loyalty
+  // page shows ONLY active earn rules + active rewards, so the console
+  // flags inactive rows and an archive removes them from the storefront.
+  //
+  // `loyalty` (the points ledger) is the core dep — the overview + the
+  // adjustment action mount on it. Earn rules + the rewards catalog mount
+  // additionally on their own primitives, so a deployment that wired only
+  // the ledger still gets the adjustment surface (and the nav link).
+  if (deps.loyalty) {
+    var loyalty = deps.loyalty;
+    var loyaltyEarnRules  = deps.loyaltyEarnRules  || null;
+    var loyaltyRedemption = deps.loyaltyRedemption || null;
+
+    // Validate the operator's free-text adjustment reason at the route.
+    // A points adjustment is a money-adjacent action, so the reason is
+    // MANDATORY — it rides into the ledger row's `notes` column. Throws a
+    // TypeError (→ 400) on a missing / blank / over-long / control-byte
+    // reason so the browser form surfaces a clean notice and writes
+    // nothing. The amount goes through the strict signed-integer reader
+    // (refuses "", floats, "12abc") and must be non-zero.
+    var LOYALTY_REASON_MAX = 256;
+    function _loyaltyReason(raw) {
+      if (raw == null) throw new TypeError("admin: a reason is required for a points adjustment");
+      var s = String(raw).trim();
+      if (!s.length) throw new TypeError("admin: a reason is required for a points adjustment");
+      if (s.length > LOYALTY_REASON_MAX) throw new TypeError("admin: reason must be <= " + LOYALTY_REASON_MAX + " chars");
+      if (/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(s)) throw new TypeError("admin: reason must not contain control bytes");
+      return s;
+    }
+    // Coerce the grant/deduct form into a signed delta. `direction` is
+    // "grant" (positive) or "deduct" (negative); `amount` is a positive
+    // integer count of points. The two compose into the non-zero signed
+    // delta loyalty.adjust expects, so the operator never types a sign.
+    function _loyaltyDelta(body) {
+      var amount = _strictMinorInt(body.amount, "admin", "amount");
+      if (amount <= 0) throw new TypeError("admin: amount must be a positive integer");
+      var dir = typeof body.direction === "string" ? body.direction.trim() : "";
+      if (dir !== "grant" && dir !== "deduct") {
+        throw new TypeError("admin: direction must be 'grant' or 'deduct'");
+      }
+      return dir === "deduct" ? -amount : amount;
+    }
+
+    // Build the overview model: thresholds + ratios from the ledger, plus
+    // (best-effort) the earn-rule + reward lists. A not-wired or
+    // not-migrated sub-primitive degrades that panel rather than the page.
+    async function _loyaltyOverview(flags) {
+      flags = flags || {};
+      var earnRules = null;
+      if (loyaltyEarnRules) {
+        try { earnRules = await loyaltyEarnRules.listRules({ limit: 200 }); }
+        catch (_e) { earnRules = []; }
+      }
+      var rewards = null;
+      if (loyaltyRedemption) {
+        try { rewards = await loyaltyRedemption.listRewards({ limit: 200 }); }
+        catch (_e) { rewards = []; }
+      }
+      return Object.assign({
+        shop_name:        deps.shop_name,
+        nav_available:    navAvailable,
+        tiers:            loyalty.TIERS,
+        tier_thresholds:  loyalty.TIER_THRESHOLDS,
+        points_per_usd:   loyalty.POINTS_PER_USD,
+        redemption_points_per_usd: loyalty.REDEMPTION_POINTS_PER_USD,
+        earn_triggers:    loyaltyEarnRulesModule.TRIGGERS,
+        reward_kinds:     loyaltyRedemptionModule.KINDS,
+        earn_rules:       earnRules,
+        rewards:          rewards,
+        can_manage_rules:   !!loyaltyEarnRules,
+        can_manage_rewards: !!loyaltyRedemption,
+      }, flags);
+    }
+
+    router.get("/admin/loyalty", _pageOrApi(true,
+      R(async function (_req, res) {
+        // Bearer JSON: the program's configuration snapshot.
+        _json(res, 200, {
+          tiers:            loyalty.TIERS,
+          tier_thresholds:  loyalty.TIER_THRESHOLDS,
+          points_per_usd:   loyalty.POINTS_PER_USD,
+          redemption_points_per_usd: loyalty.REDEMPTION_POINTS_PER_USD,
+          earn_rules:       loyaltyEarnRules  ? await loyaltyEarnRules.listRules({ limit: 200 }) : null,
+          rewards:          loyaltyRedemption ? await loyaltyRedemption.listRewards({ limit: 200 }) : null,
+        });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var flags = {
+          adjusted: url && url.searchParams.get("adjusted"),
+          notice:   (url && url.searchParams.get("err")) ? "That action couldn't be completed." : null,
+        };
+        // A failed adjustment round-trips its message through a one-shot
+        // query flag set on the redirect (kept short + already escaped on
+        // render) so the operator sees WHY without a 5xx.
+        if (url && url.searchParams.get("adjust_err")) {
+          flags.adjust_notice = url.searchParams.get("adjust_err");
+        }
+        _sendHtml(res, 200, renderAdminLoyalty(await _loyaltyOverview(flags)));
+      },
+    ));
+
+    // Points adjustment — grant or deduct a specific customer's balance
+    // with a required reason. Composes loyalty.adjust, which writes the
+    // signed delta to loyalty_transactions (the audited ledger) and
+    // recomputes the tier. A bad customer id / amount / missing reason is
+    // a clean 4xx with nothing written; an underflowing deduction surfaces
+    // the primitive's LOYALTY_INSUFFICIENT_BALANCE as a notice.
+    router.post("/admin/loyalty/adjust", _pageOrApi(false,
+      W("loyalty.adjust", async function (req, res) {
+        var body = req.body || {};
+        var customerId = body.customer_id;
+        var delta;
+        var reason;
+        try {
+          delta  = _loyaltyDelta(body);
+          reason = _loyaltyReason(body.reason);
+        } catch (e) {
+          if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+          throw e;
+        }
+        var result;
+        try {
+          result = await loyalty.adjust({
+            customer_id: customerId,
+            points:      delta,
+            source:      "admin-adjustment",
+            notes:       reason,
+          });
+        } catch (e) {
+          if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+          if (e && e.code === "LOYALTY_INSUFFICIENT_BALANCE") {
+            return _problem(res, 409, "insufficient-balance", "Adjustment would drop the balance below zero.");
+          }
+          throw e;
+        }
+        _json(res, 200, result);
+        return { id: customerId };
+      }),
+      async function (req, res) {
+        var body = req.body || {};
+        var customerId = body.customer_id;
+        var cidPrefill = typeof customerId === "string" ? customerId : "";
+        // Re-render the overview with the adjustment form's error notice.
+        // The message is classified by the shared _safeNotice funnel (so
+        // the cookie/HTML path can never reveal more than the bearer JSON
+        // path); the `admin:`/`loyalty:` namespace prefix is stripped for
+        // the operator. An insufficient-balance refusal is the one
+        // primitive code _safeNotice would otherwise genericize to a 500,
+        // so it's mapped to a clean 4xx notice ahead of the funnel.
+        async function _adjustFail(e) {
+          if (e && e.code === "LOYALTY_INSUFFICIENT_BALANCE") {
+            return _sendHtml(res, 409, renderAdminLoyalty(await _loyaltyOverview({
+              adjust_notice: "That deduction would drop the balance below zero.",
+              adjust_customer_id: cidPrefill,
+            })));
+          }
+          var n = _safeNotice(e, "loyalty.adjust");
+          return _sendHtml(res, n.status, renderAdminLoyalty(await _loyaltyOverview({
+            adjust_notice: n.message.replace(/^(?:admin|loyalty)[.:]\s*/, ""),
+            adjust_customer_id: cidPrefill,
+          })));
+        }
+        var delta;
+        var reason;
+        try {
+          delta  = _loyaltyDelta(body);
+          reason = _loyaltyReason(body.reason);
+        } catch (e) {
+          return _adjustFail(e);
+        }
+        try {
+          await loyalty.adjust({
+            customer_id: customerId,
+            points:      delta,
+            source:      "admin-adjustment",
+            notes:       reason,
+          });
+        } catch (e) {
+          return _adjustFail(e);
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".loyalty.adjust", outcome: "success" });
+        _redirect(res, "/admin/loyalty?adjusted=1");
+      },
+    ));
+
+    // ---- earn rules ---------------------------------------------------
+    if (loyaltyEarnRules) {
+      // Translate the create / edit form into a defineRule / updateRule
+      // input. The status list is a comma-separated free-text field
+      // (e.g. "active, vip"); a blank field means no restriction (null).
+      function _loyaltyStatusList(raw) {
+        if (raw == null) return null;
+        var s = String(raw).trim();
+        if (!s.length) return null;
+        return s.split(",").map(function (x) { return x.trim(); }).filter(Boolean);
+      }
+      function _earnDefineInput(body) {
+        var input = {
+          slug:            typeof body.slug === "string" ? body.slug.trim() : body.slug,
+          trigger:         typeof body.trigger === "string" ? body.trigger.trim() : body.trigger,
+          points_per_unit: _strictMinorInt(body.points_per_unit, "admin", "points_per_unit"),
+          active:          (body.active === "on" || body.active === "1" || body.active === true),
+        };
+        var maxRaw = body.max_per_event == null ? "" : String(body.max_per_event).trim();
+        if (maxRaw !== "") input.max_per_event = _strictMinorInt(maxRaw, "admin", "max_per_event");
+        var statusList = _loyaltyStatusList(body.customer_status_in);
+        if (statusList) input.customer_status_in = statusList;
+        return input;
+      }
+
+      router.get("/admin/loyalty/earn-rules", _pageOrApi(true,
+        R(async function (_req, res) {
+          _json(res, 200, { rows: await loyaltyEarnRules.listRules({ limit: 200 }) });
+        }),
+        async function (req, res) {
+          var url = req.url ? new URL(req.url, "http://localhost") : null;
+          _sendHtml(res, 200, renderAdminLoyaltyEarnRules({
+            shop_name: deps.shop_name, nav_available: navAvailable,
+            triggers: loyaltyEarnRulesModule.TRIGGERS,
+            rules: await loyaltyEarnRules.listRules({ limit: 200 }),
+            created: url && url.searchParams.get("created"),
+            saved:   url && url.searchParams.get("saved"),
+            archived: url && url.searchParams.get("archived_ok"),
+            notice:  (url && url.searchParams.get("err")) ? "That action couldn't be completed for the rule." : null,
+          }));
+        },
+      ));
+
+      router.post("/admin/loyalty/earn-rules", _pageOrApi(false,
+        W("loyalty.earn_rule.create", async function (req, res) {
+          var rule;
+          try { rule = await loyaltyEarnRules.defineRule(_earnDefineInput(req.body || {})); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          _json(res, 201, rule);
+          return { id: rule.slug };
+        }),
+        async function (req, res) {
+          try {
+            await loyaltyEarnRules.defineRule(_earnDefineInput(req.body || {}));
+          } catch (e) {
+            var n = _safeNotice(e, "loyalty.earn_rule.create");
+            return _sendHtml(res, n.status, renderAdminLoyaltyEarnRules({
+              shop_name: deps.shop_name, nav_available: navAvailable,
+              triggers: loyaltyEarnRulesModule.TRIGGERS,
+              rules: await loyaltyEarnRules.listRules({ limit: 200 }),
+              notice: n.message.replace(/^loyaltyEarnRules[.:]\s*/, ""),
+            }));
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".loyalty.earn_rule.create", outcome: "success" });
+          _redirect(res, "/admin/loyalty/earn-rules?created=1");
+        },
+      ));
+
+      router.get("/admin/loyalty/earn-rules/:slug", _pageOrApi(true,
+        R(async function (req, res) {
+          var rule;
+          try { rule = await loyaltyEarnRules.getRule(req.params.slug); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          if (!rule) return _problem(res, 404, "loyalty-earn-rule-not-found");
+          _json(res, 200, rule);
+        }),
+        async function (req, res) {
+          var url = req.url ? new URL(req.url, "http://localhost") : null;
+          var rule;
+          try { rule = await loyaltyEarnRules.getRule(req.params.slug); }
+          catch (e) { if (!(e instanceof TypeError)) throw e; rule = null; }
+          if (!rule) return _sendHtml(res, 404, renderAdminLoyaltyEarnRule({
+            shop_name: deps.shop_name, nav_available: navAvailable, rule: null,
+          }));
+          _sendHtml(res, 200, renderAdminLoyaltyEarnRule({
+            shop_name: deps.shop_name, nav_available: navAvailable,
+            triggers: loyaltyEarnRulesModule.TRIGGERS, rule: rule,
+            saved:  url && url.searchParams.get("saved"),
+            notice: (url && url.searchParams.get("err")) ? "That action couldn't be completed." : null,
+          }));
+        },
+      ));
+
+      router.post("/admin/loyalty/earn-rules/:slug/edit", _pageOrApi(false,
+        W("loyalty.earn_rule.update", async function (req, res) {
+          var patch = _earnPatchFromForm(req.body || {});
+          var rule;
+          try { rule = await loyaltyEarnRules.updateRule(req.params.slug, patch); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          if (!rule) return _problem(res, 404, "loyalty-earn-rule-not-found");
+          _json(res, 200, rule);
+          return { id: rule.slug };
+        }),
+        async function (req, res) {
+          var slug = req.params.slug;
+          var enc = encodeURIComponent(slug);
+          try {
+            var rule = await loyaltyEarnRules.updateRule(slug, _earnPatchFromForm(req.body || {}));
+            if (!rule) return _redirect(res, "/admin/loyalty/earn-rules?err=1");
+          } catch (e) {
+            if (!(e instanceof TypeError)) throw e;
+            return _redirect(res, "/admin/loyalty/earn-rules/" + enc + "?err=1");
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".loyalty.earn_rule.update", outcome: "success", metadata: { slug: slug } });
+          _redirect(res, "/admin/loyalty/earn-rules/" + enc + "?saved=1");
+        },
+      ));
+
+      router.post("/admin/loyalty/earn-rules/:slug/archive", _pageOrApi(false,
+        W("loyalty.earn_rule.archive", async function (req, res) {
+          var rule;
+          try { rule = await loyaltyEarnRules.archiveRule(req.params.slug); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          if (!rule) return _problem(res, 404, "loyalty-earn-rule-not-found");
+          _json(res, 200, rule);
+          return { id: req.params.slug };
+        }),
+        async function (req, res) {
+          var slug = req.params.slug;
+          try { await loyaltyEarnRules.archiveRule(slug); }
+          catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/loyalty/earn-rules?err=1"); }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".loyalty.earn_rule.archive", outcome: "success", metadata: { slug: slug } });
+          _redirect(res, "/admin/loyalty/earn-rules?archived_ok=1");
+        },
+      ));
+    }
+
+    // ---- rewards catalog ----------------------------------------------
+    if (loyaltyRedemption) {
+      // The reward's value_json shape depends on its kind. The console
+      // collects one numeric field (percent / amount_minor / product_id)
+      // and the create path assembles the per-kind payload the primitive
+      // validates. free_shipping carries an empty object.
+      function _rewardValueJson(kind, body) {
+        if (kind === "discount_percent") {
+          return { percent: _strictMinorInt(body.value_number, "admin", "percent") };
+        }
+        if (kind === "discount_amount") {
+          return { amount_minor: _strictMinorInt(body.value_number, "admin", "amount_minor") };
+        }
+        if (kind === "free_product") {
+          var pid = typeof body.value_text === "string" ? body.value_text.trim() : "";
+          return { product_id: pid };
+        }
+        // free_shipping (or an unknown kind the primitive will reject).
+        return {};
+      }
+      function _rewardDefineInput(body) {
+        var kind = typeof body.kind === "string" ? body.kind.trim() : body.kind;
+        var input = {
+          slug:       typeof body.slug === "string" ? body.slug.trim() : body.slug,
+          kind:       kind,
+          title:      typeof body.title === "string" ? body.title : body.title,
+          point_cost: _strictMinorInt(body.point_cost, "admin", "point_cost"),
+          value_json: _rewardValueJson(kind, body),
+          active:     (body.active === "on" || body.active === "1" || body.active === true),
+        };
+        var maxRaw = body.max_per_customer == null ? "" : String(body.max_per_customer).trim();
+        if (maxRaw !== "") input.max_per_customer = _strictMinorInt(maxRaw, "admin", "max_per_customer");
+        var expRaw = body.expires_days_after_redemption == null ? "" : String(body.expires_days_after_redemption).trim();
+        if (expRaw !== "") input.expires_days_after_redemption = _strictMinorInt(expRaw, "admin", "expires_days_after_redemption");
+        return input;
+      }
+
+      router.get("/admin/loyalty/rewards", _pageOrApi(true,
+        R(async function (_req, res) {
+          _json(res, 200, { rows: await loyaltyRedemption.listRewards({ limit: 200 }) });
+        }),
+        async function (req, res) {
+          var url = req.url ? new URL(req.url, "http://localhost") : null;
+          _sendHtml(res, 200, renderAdminLoyaltyRewards({
+            shop_name: deps.shop_name, nav_available: navAvailable,
+            kinds: loyaltyRedemptionModule.KINDS,
+            rewards: await loyaltyRedemption.listRewards({ limit: 200 }),
+            created: url && url.searchParams.get("created"),
+            saved:   url && url.searchParams.get("saved"),
+            archived: url && url.searchParams.get("archived_ok"),
+            notice:  (url && url.searchParams.get("err")) ? "That action couldn't be completed for the reward." : null,
+          }));
+        },
+      ));
+
+      router.post("/admin/loyalty/rewards", _pageOrApi(false,
+        W("loyalty.reward.create", async function (req, res) {
+          var reward;
+          try { reward = await loyaltyRedemption.defineReward(_rewardDefineInput(req.body || {})); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          _json(res, 201, reward);
+          return { id: reward.slug };
+        }),
+        async function (req, res) {
+          try {
+            await loyaltyRedemption.defineReward(_rewardDefineInput(req.body || {}));
+          } catch (e) {
+            var n = _safeNotice(e, "loyalty.reward.create");
+            return _sendHtml(res, n.status, renderAdminLoyaltyRewards({
+              shop_name: deps.shop_name, nav_available: navAvailable,
+              kinds: loyaltyRedemptionModule.KINDS,
+              rewards: await loyaltyRedemption.listRewards({ limit: 200 }),
+              notice: n.message.replace(/^loyaltyRedemption[.:]\s*/, ""),
+            }));
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".loyalty.reward.create", outcome: "success" });
+          _redirect(res, "/admin/loyalty/rewards?created=1");
+        },
+      ));
+
+      router.get("/admin/loyalty/rewards/:slug", _pageOrApi(true,
+        R(async function (req, res) {
+          var reward;
+          try { reward = await loyaltyRedemption.getReward(req.params.slug); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          if (!reward) return _problem(res, 404, "loyalty-reward-not-found");
+          _json(res, 200, reward);
+        }),
+        async function (req, res) {
+          var url = req.url ? new URL(req.url, "http://localhost") : null;
+          var reward;
+          try { reward = await loyaltyRedemption.getReward(req.params.slug); }
+          catch (e) { if (!(e instanceof TypeError)) throw e; reward = null; }
+          if (!reward) return _sendHtml(res, 404, renderAdminLoyaltyReward({
+            shop_name: deps.shop_name, nav_available: navAvailable, reward: null,
+          }));
+          _sendHtml(res, 200, renderAdminLoyaltyReward({
+            shop_name: deps.shop_name, nav_available: navAvailable, reward: reward,
+            saved:  url && url.searchParams.get("saved"),
+            notice: (url && url.searchParams.get("err")) ? "That action couldn't be completed." : null,
+          }));
+        },
+      ));
+
+      router.post("/admin/loyalty/rewards/:slug/edit", _pageOrApi(false,
+        W("loyalty.reward.update", async function (req, res) {
+          var reward;
+          try { reward = await loyaltyRedemption.updateReward(req.params.slug, await _rewardPatchFromForm(req.params.slug, req.body || {})); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          _json(res, 200, reward);
+          return { id: reward.slug };
+        }),
+        async function (req, res) {
+          var slug = req.params.slug;
+          var enc = encodeURIComponent(slug);
+          try {
+            await loyaltyRedemption.updateReward(slug, await _rewardPatchFromForm(slug, req.body || {}));
+          } catch (e) {
+            if (!(e instanceof TypeError)) throw e;
+            return _redirect(res, "/admin/loyalty/rewards/" + enc + "?err=1");
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".loyalty.reward.update", outcome: "success", metadata: { slug: slug } });
+          _redirect(res, "/admin/loyalty/rewards/" + enc + "?saved=1");
+        },
+      ));
+
+      router.post("/admin/loyalty/rewards/:slug/archive", _pageOrApi(false,
+        W("loyalty.reward.archive", async function (req, res) {
+          var reward;
+          try { reward = await loyaltyRedemption.archiveReward(req.params.slug); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          _json(res, 200, reward);
+          return { id: req.params.slug };
+        }),
+        async function (req, res) {
+          var slug = req.params.slug;
+          try { await loyaltyRedemption.archiveReward(slug); }
+          catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/loyalty/rewards?err=1"); }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".loyalty.reward.archive", outcome: "success", metadata: { slug: slug } });
+          _redirect(res, "/admin/loyalty/rewards?archived_ok=1");
+        },
+      ));
+
+      // Build the updateReward patch from the edit form. Only the columns
+      // the operator changed are forwarded; value_json is re-validated
+      // against the reward's STORED kind (kind is immutable on update), so
+      // the helper reads the current reward to resolve it.
+      async function _rewardPatchFromForm(slug, body) {
+        var patch = {};
+        if (typeof body.title === "string" && body.title.length) patch.title = body.title;
+        if (body.point_cost != null && String(body.point_cost).trim() !== "") {
+          patch.point_cost = _strictMinorInt(body.point_cost, "admin", "point_cost");
+        }
+        if (body.active_present === "1") {
+          patch.active = (body.active === "on" || body.active === "1");
+        }
+        var maxRaw = body.max_per_customer == null ? "" : String(body.max_per_customer).trim();
+        if (maxRaw !== "") patch.max_per_customer = _strictMinorInt(maxRaw, "admin", "max_per_customer");
+        var expRaw = body.expires_days_after_redemption == null ? "" : String(body.expires_days_after_redemption).trim();
+        if (expRaw !== "") patch.expires_days_after_redemption = _strictMinorInt(expRaw, "admin", "expires_days_after_redemption");
+        // A supplied value field rewrites value_json against the stored
+        // kind. Absent it, value_json is left untouched.
+        if ((body.value_number != null && String(body.value_number).trim() !== "") ||
+            (typeof body.value_text === "string" && body.value_text.trim() !== "")) {
+          var current = await loyaltyRedemption.getReward(slug);
+          if (current) patch.value_json = _rewardValueJson(current.kind, body);
+        }
+        return patch;
+      }
+    }
+  }
+
+  // Patch builder for the loyalty earn-rule edit form. trigger is
+  // immutable on update (the primitive refuses a change), so the form
+  // never sends it; only points_per_unit / max_per_event /
+  // customer_status_in / active are editable. Hoisted above the rewards
+  // block's IIFE-free scope so both the bearer + browser edit paths share
+  // it. Defined as a closure inside mount() so it can stay near its
+  // callers without polluting the module surface.
+  function _earnPatchFromForm(body) {
+    var patch = {};
+    if (body.points_per_unit != null && String(body.points_per_unit).trim() !== "") {
+      patch.points_per_unit = _strictMinorInt(body.points_per_unit, "admin", "points_per_unit");
+    }
+    if (body.max_per_event != null) {
+      var maxRaw = String(body.max_per_event).trim();
+      // An explicit "0" / "" clears the cap (null); a positive value sets it.
+      if (maxRaw === "" || maxRaw === "0") patch.max_per_event = null;
+      else patch.max_per_event = _strictMinorInt(maxRaw, "admin", "max_per_event");
+    }
+    if (body.customer_status_in != null) {
+      var s = String(body.customer_status_in).trim();
+      patch.customer_status_in = s.length
+        ? s.split(",").map(function (x) { return x.trim(); }).filter(Boolean)
+        : null;
+    }
+    if (body.active_present === "1") {
+      patch.active = (body.active === "on" || body.active === "1");
+    }
+    return patch;
+  }
+
   // Render the discounts screen — gathers rules + (optional) stacking
   // policies, then hands them to the renderer with whatever banner flags
   // the caller passed.
@@ -7084,6 +7888,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "discounts",    href: "/admin/discounts",    label: "Discounts",    requires: "autoDiscount" },
   { key: "discount-allocation", href: "/admin/discount-allocation", label: "Discount splits", requires: "discountAllocation" },
   { key: "quantity-discounts", href: "/admin/quantity-discounts", label: "Quantity breaks", requires: "quantityDiscounts" },
+  { key: "loyalty",      href: "/admin/loyalty",      label: "Loyalty",      requires: "loyalty" },
   { key: "tax",          href: "/admin/tax-rates",    label: "Tax",          requires: "taxRates" },
   { key: "tax-filings",  href: "/admin/tax-filings",  label: "Tax filings",  requires: "salesTaxFilings" },
   { key: "shipping",     href: "/admin/shipping",     label: "Shipping",     requires: "shippingZones" },
@@ -8218,17 +9023,21 @@ function renderAdminCustomers(opts) {
     }
     var method = methodCells.length ? methodCells.join(" ") : "<span class=\"meta\">—</span>";
     var orders = orderCounts[c.id] || 0;
+    var enc = encodeURIComponent(c.id);
     return "<tr>" +
-      "<td><strong>" + _htmlEscape(c.display_name) + "</strong></td>" +
+      "<td><a href=\"/admin/customers/" + _htmlEscape(enc) + "\"><strong>" + _htmlEscape(c.display_name) + "</strong></a></td>" +
       "<td><code class=\"order-id\">" + _htmlEscape(String(c.id).slice(0, 8)) + "</code></td>" +
       "<td>" + _htmlEscape(_fmtDate(c.created_at)) + "</td>" +
       "<td>" + method + "</td>" +
       "<td class=\"num\">" + _htmlEscape(String(orders)) + "</td>" +
+      "<td><a class=\"btn btn--ghost btn--sm\" href=\"/admin/customers/" + _htmlEscape(enc) + "\">Manage</a></td>" +
       "</tr>";
   }).join("");
 
+  var notice = opts.notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
   var table = customers.length
-    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Name</th><th scope=\"col\">ID</th><th scope=\"col\">Joined</th><th scope=\"col\">Sign-in method</th><th scope=\"col\" class=\"num\">Orders</th></tr></thead><tbody>" + rows + "</tbody></table></div>"
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Name</th><th scope=\"col\">ID</th><th scope=\"col\">Joined</th><th scope=\"col\">Sign-in method</th><th scope=\"col\" class=\"num\">Orders</th><th scope=\"col\"><span class=\"sr-only\">Manage</span></th></tr></thead><tbody>" + rows + "</tbody></table></div>"
     : "<p class=\"empty\">No customers yet.</p>";
 
   // Cursor pager — a Next link when the page filled and more rows remain.
@@ -8237,12 +9046,165 @@ function renderAdminCustomers(opts) {
     ? "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/customers?cursor=" + _htmlEscape(encodeURIComponent(opts.next_cursor)) + "\">Next page <span aria-hidden=\"true\">→</span></a></div>"
     : "";
 
-  var body = "<section><h2>Customers</h2>" +
-    "<p class=\"meta\">Accounts are passwordless — customers enrol a passkey or sign in with a federated provider. Email addresses aren't stored in the clear, so they're not shown here.</p>" +
+  var body = "<section><h2>Customers</h2>" + notice +
+    "<p class=\"meta\">Accounts are passwordless — customers enrol a passkey or sign in with a federated provider. Email addresses aren't stored in the clear, so they're not shown here. Open a customer to manage their store credit, loyalty, notes, and segment membership.</p>" +
     table + pager + "</section>";
   return _renderAdminShell(opts.shop_name, "Customers", body, "customers", opts.nav_available);
 }
 
+// Per-customer operator detail screen. READS the customer's identity fields
+// + recent orders; WRITES only the operator-managed satellites (store-credit
+// + CRM notes). Segment membership is read-only — it is rule-derived (RFM
+// predicates recomputed by the scheduler), so there is no per-customer
+// manual assign / remove in the segments primitive; the panel shows the
+// segments the customer currently sits in and says so. Every panel renders
+// only when its primitive is wired.
+function renderAdminCustomerDetail(opts) {
+  opts = opts || {};
+  var c = opts.customer || {};
+  var currency = opts.currency || "USD";
+  var enc = encodeURIComponent(c.id);
+
+  var saved = opts.saved ? "<div class=\"banner banner--ok\">Saved.</div>" : "";
+
+  // ---- identity (read-only) -----------------------------------------
+  var identity = "<div class=\"panel\"><h3 class=\"subhead\">Customer</h3>" +
+    "<dl class=\"kv-list\">" +
+      "<div><dt>Name</dt><dd>" + _htmlEscape(c.display_name) + "</dd></div>" +
+      "<div><dt>Customer id</dt><dd><code class=\"order-id\">" + _htmlEscape(String(c.id)) + "</code></dd></div>" +
+      "<div><dt>Joined</dt><dd>" + _htmlEscape(_fmtDate(c.created_at)) + "</dd></div>" +
+    "</dl>" +
+    "<p class=\"meta\">Identity is read-only here — customers manage their own profile through the storefront (passkey / federated sign-in). Email addresses aren't stored in the clear.</p>" +
+  "</div>";
+
+  // ---- recent orders -------------------------------------------------
+  var orderRows = (opts.recent_orders || []).map(function (o) {
+    return "<tr>" +
+      "<td><a class=\"order-id\" href=\"/admin/orders/" + _htmlEscape(encodeURIComponent(o.id)) + "\">" + _htmlEscape(String(o.id).slice(0, 8)) + "</a></td>" +
+      "<td><span class=\"status-pill " + _htmlEscape(o.status) + "\">" + _htmlEscape(o.status) + "</span></td>" +
+      "<td class=\"num\">" + _htmlEscape(pricing.format(o.grand_total_minor, o.currency)) + "</td>" +
+      "<td>" + _htmlEscape(_fmtDate(o.created_at)) + "</td>" +
+    "</tr>";
+  }).join("");
+  var ordersPanel = "<div class=\"panel\"><h3 class=\"subhead\">Recent orders</h3>" +
+    ((opts.recent_orders || []).length
+      ? "<table><thead><tr><th scope=\"col\">Order</th><th scope=\"col\">Status</th><th scope=\"col\" class=\"num\">Total</th><th scope=\"col\">Placed</th></tr></thead><tbody>" + orderRows + "</tbody></table>"
+      : "<p class=\"empty\">No orders yet.</p>") +
+  "</div>";
+
+  // ---- store credit --------------------------------------------------
+  var creditPanel;
+  if (!opts.can_store_credit) {
+    creditPanel = "<div class=\"panel\"><h3 class=\"subhead\">Store credit</h3>" +
+      "<p class=\"empty\">Store credit isn't wired in this deployment.</p></div>";
+  } else {
+    var bal = opts.store_credit_minor != null ? opts.store_credit_minor : 0;
+    var creditNotice = opts.credit_notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.credit_notice) + "</div>" : "";
+    var histRows = (opts.store_credit_history || []).map(function (h) {
+      var sign = h.kind === "credit" ? "+" : "−";
+      var note = h.source_ref != null ? h.source_ref : (h.source != null ? h.source : "");
+      return "<tr>" +
+        "<td>" + _htmlEscape(h.kind) + "</td>" +
+        "<td class=\"num\">" + _htmlEscape(sign + pricing.format(h.amount_minor, currency)) + "</td>" +
+        "<td class=\"num\">" + _htmlEscape(pricing.format(h.balance_after_minor, currency)) + "</td>" +
+        "<td>" + _htmlEscape(note) + "</td>" +
+        "<td>" + _htmlEscape(_fmtDate(h.occurred_at)) + "</td>" +
+      "</tr>";
+    }).join("");
+    var histTable = (opts.store_credit_history || []).length
+      ? "<table><thead><tr><th scope=\"col\">Kind</th><th scope=\"col\" class=\"num\">Amount</th><th scope=\"col\" class=\"num\">Balance after</th><th scope=\"col\">Reason</th><th scope=\"col\">When</th></tr></thead><tbody>" + histRows + "</tbody></table>"
+      : "<p class=\"empty\">No store-credit activity yet.</p>";
+    creditPanel = "<div class=\"panel\"><h3 class=\"subhead\">Store credit</h3>" +
+      creditNotice +
+      "<p class=\"stat-figure\">" + _htmlEscape(pricing.format(bal, currency)) + "</p>" +
+      "<p class=\"meta\">Account-bound balance — applied at checkout. Every grant or deduct is recorded with your reason in the ledger below.</p>" +
+      "<form method=\"post\" action=\"/admin/customers/" + _htmlEscape(enc) + "/store-credit\">" +
+        "<fieldset class=\"box\"><legend class=\"legend-sm\">Direction</legend>" +
+          "<label class=\"kv\"><input type=\"radio\" name=\"direction\" value=\"grant\" checked> Grant (add credit)</label>" +
+          "<label class=\"kv\"><input type=\"radio\" name=\"direction\" value=\"deduct\"> Deduct (remove credit)</label>" +
+        "</fieldset>" +
+        "<label class=\"form-field\"><span>Amount (" + _htmlEscape(currency) + " minor units)</span>" +
+          "<input type=\"number\" name=\"amount_minor\" min=\"1\" step=\"1\" required class=\"input-code\" placeholder=\"e.g. 500 = " + _htmlEscape(pricing.format(500, currency)) + "\"></label>" +
+        "<label class=\"form-field\"><span>Reason</span>" +
+          "<input type=\"text\" name=\"reason\" required maxlength=\"128\" placeholder=\"e.g. goodwill for the late delivery\">" +
+          "<small>Required. Recorded with the adjustment in the ledger.</small></label>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Apply adjustment</button></div>" +
+      "</form>" +
+      histTable +
+    "</div>";
+  }
+
+  // ---- loyalty -------------------------------------------------------
+  var loyaltyPanel = "";
+  if (opts.loyalty_link) {
+    var loy = opts.loyalty || { balance: 0, lifetime: 0, tier: "bronze" };
+    loyaltyPanel = "<div class=\"panel\"><div class=\"actions-row\"><h3 class=\"subhead\">Loyalty</h3>" +
+      "<a class=\"btn btn--ghost\" href=\"/admin/loyalty\">Adjust points</a></div>" +
+      "<dl class=\"kv-list\">" +
+        "<div><dt>Balance</dt><dd>" + _htmlEscape(String(loy.balance)) + " pts</dd></div>" +
+        "<div><dt>Lifetime</dt><dd>" + _htmlEscape(String(loy.lifetime)) + " pts</dd></div>" +
+        "<div><dt>Tier</dt><dd>" + _htmlEscape(String(loy.tier)) + "</dd></div>" +
+      "</dl>" +
+      "<p class=\"meta\">Grant or deduct points from the Loyalty screen — paste this customer's id (above) into the adjustment form.</p>" +
+    "</div>";
+  }
+
+  // ---- notes ---------------------------------------------------------
+  var notesPanel;
+  if (!opts.can_notes) {
+    notesPanel = "<div class=\"panel\"><h3 class=\"subhead\">Notes</h3>" +
+      "<p class=\"empty\">Customer notes aren't wired in this deployment.</p></div>";
+  } else {
+    var noteNotice = opts.note_notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.note_notice) + "</div>" : "";
+    var noteRows = (opts.notes || []).map(function (n) {
+      return "<li><div class=\"note-meta\">" + _htmlEscape(n.kind) + " · " + _htmlEscape(_fmtDate(n.created_at)) + "</div>" +
+        "<div class=\"note-body\">" + _htmlEscape(n.body) + "</div></li>";
+    }).join("");
+    notesPanel = "<div class=\"panel\"><h3 class=\"subhead\">Notes</h3>" +
+      noteNotice +
+      "<p class=\"meta\">Operator-only annotations on this customer. Never shown to the customer.</p>" +
+      ((opts.notes || []).length
+        ? "<ul class=\"note-list\">" + noteRows + "</ul>"
+        : "<p class=\"empty\">No notes yet.</p>") +
+      "<form method=\"post\" action=\"/admin/customers/" + _htmlEscape(enc) + "/notes\">" +
+        "<label class=\"form-field\"><span>Kind</span>" +
+          "<select name=\"kind\">" +
+            "<option value=\"general\">general</option>" +
+            "<option value=\"preference\">preference</option>" +
+            "<option value=\"escalation\">escalation</option>" +
+            "<option value=\"warning\">warning</option>" +
+            "<option value=\"billing\">billing</option>" +
+          "</select></label>" +
+        "<label class=\"form-field\"><span>Note</span>" +
+          "<textarea name=\"body\" required maxlength=\"8000\" rows=\"3\" placeholder=\"e.g. VIP — comp shipping where possible\"></textarea></label>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Add note</button></div>" +
+      "</form>" +
+    "</div>";
+  }
+
+  // ---- segments (read-only) ------------------------------------------
+  var segmentsPanel = "";
+  if (opts.can_segments) {
+    var segChips = (opts.segments || []).map(function (s) {
+      return "<span class=\"chip\">" + _htmlEscape(s.title || s.slug) + "</span>";
+    }).join(" ");
+    segmentsPanel = "<div class=\"panel\"><h3 class=\"subhead\">Segments</h3>" +
+      ((opts.segments || []).length
+        ? "<div class=\"chip-row\">" + segChips + "</div>"
+        : "<p class=\"empty\">Not in any segment.</p>") +
+      "<p class=\"meta\">Segment membership is rule-derived — the scheduler recomputes it from each segment's RFM predicates, so there is no manual assign / remove per customer. Define or edit segments under their own console.</p>" +
+    "</div>";
+  }
+
+  var body = "<section>" +
+    "<div class=\"actions-row\"><h2>" + _htmlEscape(c.display_name) + "</h2>" +
+      "<a class=\"btn btn--ghost\" href=\"/admin/customers\"><span aria-hidden=\"true\">←</span> All customers</a></div>" +
+    saved +
+    identity + ordersPanel + creditPanel + loyaltyPanel + notesPanel + segmentsPanel +
+  "</section>";
+  return _renderAdminShell(opts.shop_name, c.display_name || "Customer", body, "customers", opts.nav_available);
+}
+
 // The RMA states an operator can filter the returns queue by — drives the
 // filter chips, lifecycle order then terminal.
 var RETURN_STATUS_FILTERS = ["pending", "approved", "received", "refunded", "rejected"];
@@ -10960,6 +11922,354 @@ function renderAdminQuantityDiscount(opts) {
   return _renderAdminShell(opts.shop_name, "Quantity break", body, "quantity-discounts", opts.nav_available);
 }
 
+// ---- loyalty render functions ------------------------------------------
+
+// Status pill for an active / inactive / archived loyalty row — shared by
+// the earn-rule + reward lists.
+function _loyaltyStatusPill(active, archivedAt) {
+  if (archivedAt != null) return "<span class=\"status-pill cancelled\">archived</span>";
+  return active
+    ? "<span class=\"status-pill paid\">active</span>"
+    : "<span class=\"status-pill pending\">inactive</span>";
+}
+
+// Render a reward's value_json as a short human label per kind.
+function _loyaltyRewardValueLabel(reward) {
+  var v = reward.value_json || {};
+  if (reward.kind === "discount_percent") return _htmlEscape(String(v.percent)) + "% off";
+  if (reward.kind === "discount_amount")  return _htmlEscape(String(v.amount_minor)) + " minor off";
+  if (reward.kind === "free_product")     return "free product " + _htmlEscape(String(v.product_id || ""));
+  if (reward.kind === "free_shipping")    return "free shipping";
+  return _htmlEscape(reward.kind);
+}
+
+// Loyalty overview / settings — the program's tiers + conversion ratios,
+// a summary of earn rules + rewards (with links to manage each), and the
+// per-customer points-adjustment form (grant / deduct with a required
+// reason, recorded in the loyalty ledger). The customer's /account/loyalty
+// page shows only ACTIVE earn rules + ACTIVE rewards, so the summary flags
+// inactive rows.
+function renderAdminLoyalty(opts) {
+  opts = opts || {};
+  var adjusted = opts.adjusted ? "<div class=\"banner banner--ok\">Points adjusted. The ledger recorded the change.</div>" : "";
+  var notice   = opts.notice   ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var adjustNotice = opts.adjust_notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.adjust_notice) + "</div>" : "";
+
+  var thresholds = opts.tier_thresholds || {};
+  var tiers = opts.tiers || [];
+  var tierRows = tiers.map(function (t) {
+    return "<tr><td><strong>" + _htmlEscape(t) + "</strong></td>" +
+      "<td class=\"num\">" + _htmlEscape(String(thresholds[t] == null ? "—" : thresholds[t])) + "</td></tr>";
+  }).join("");
+  var tierTable =
+    "<div class=\"panel\"><h3 class=\"subhead\">Tiers</h3>" +
+      "<p class=\"meta\">Lifetime points (never decremented) place a customer in a tier. " +
+        "Earning $1 grants " + _htmlEscape(String(opts.points_per_usd)) + " points; " +
+        _htmlEscape(String(opts.redemption_points_per_usd)) + " points redeem for $1 of value.</p>" +
+      "<table><thead><tr><th scope=\"col\">Tier</th><th scope=\"col\" class=\"num\">Lifetime points to reach</th></tr></thead>" +
+      "<tbody>" + tierRows + "</tbody></table></div>";
+
+  // Earn-rule summary.
+  var earnSummary;
+  if (!opts.can_manage_rules) {
+    earnSummary = "<div class=\"panel\"><h3 class=\"subhead\">Earn rules</h3>" +
+      "<p class=\"empty\">Earn-rule management isn't wired in this deployment.</p></div>";
+  } else {
+    var earnRules = opts.earn_rules || [];
+    var earnRows = earnRules.map(function (r) {
+      var enc = encodeURIComponent(r.slug);
+      return "<tr>" +
+        "<td><a href=\"/admin/loyalty/earn-rules/" + _htmlEscape(enc) + "\"><strong>" + _htmlEscape(r.slug) + "</strong></a></td>" +
+        "<td>" + _htmlEscape(r.trigger) + "</td>" +
+        "<td class=\"num\">" + _htmlEscape(String(r.points_per_unit)) + "</td>" +
+        "<td>" + _loyaltyStatusPill(r.active, r.archived_at) + "</td>" +
+      "</tr>";
+    }).join("");
+    earnSummary = "<div class=\"panel\"><div class=\"actions-row\"><h3 class=\"subhead\">Earn rules</h3>" +
+      "<a class=\"btn btn--ghost\" href=\"/admin/loyalty/earn-rules\">Manage earn rules</a></div>" +
+      (earnRules.length
+        ? "<table><thead><tr><th scope=\"col\">Slug</th><th scope=\"col\">Trigger</th><th scope=\"col\" class=\"num\">Points/unit</th><th scope=\"col\">Status</th></tr></thead><tbody>" + earnRows + "</tbody></table>"
+        : "<p class=\"empty\">No earn rules yet. Customers only earn points from active rules.</p>") +
+      "</div>";
+  }
+
+  // Reward summary.
+  var rewardSummary;
+  if (!opts.can_manage_rewards) {
+    rewardSummary = "<div class=\"panel\"><h3 class=\"subhead\">Rewards catalog</h3>" +
+      "<p class=\"empty\">Rewards-catalog management isn't wired in this deployment.</p></div>";
+  } else {
+    var rewards = opts.rewards || [];
+    var rewardRows = rewards.map(function (rw) {
+      var enc = encodeURIComponent(rw.slug);
+      return "<tr>" +
+        "<td><a href=\"/admin/loyalty/rewards/" + _htmlEscape(enc) + "\"><strong>" + _htmlEscape(rw.slug) + "</strong></a></td>" +
+        "<td>" + _htmlEscape(rw.title) + "</td>" +
+        "<td class=\"num\">" + _htmlEscape(String(rw.point_cost)) + "</td>" +
+        "<td>" + _loyaltyStatusPill(rw.active, rw.archived_at) + "</td>" +
+      "</tr>";
+    }).join("");
+    rewardSummary = "<div class=\"panel\"><div class=\"actions-row\"><h3 class=\"subhead\">Rewards catalog</h3>" +
+      "<a class=\"btn btn--ghost\" href=\"/admin/loyalty/rewards\">Manage rewards</a></div>" +
+      (rewards.length
+        ? "<table><thead><tr><th scope=\"col\">Slug</th><th scope=\"col\">Title</th><th scope=\"col\" class=\"num\">Point cost</th><th scope=\"col\">Status</th></tr></thead><tbody>" + rewardRows + "</tbody></table>"
+        : "<p class=\"empty\">No rewards yet. Customers only see active rewards in their catalog.</p>") +
+      "</div>";
+  }
+
+  // Points-adjustment form. The customer id is pasted (the customers
+  // roster shows each customer's id); the amount is a positive integer; a
+  // grant / deduct radio sets the sign; the reason is required and lands
+  // in the ledger row.
+  var prefillCid = opts.adjust_customer_id ? _htmlEscape(opts.adjust_customer_id) : "";
+  var adjustForm =
+    "<div class=\"panel mw-40\"><h3 class=\"subhead\">Adjust a customer's points</h3>" +
+      "<p class=\"meta\">Grant or deduct points for one customer. Every adjustment is recorded in the loyalty ledger with the reason you give. A grant also counts toward the customer's lifetime tier.</p>" +
+      adjustNotice +
+      "<form method=\"post\" action=\"/admin/loyalty/adjust\">" +
+        "<label class=\"form-field\"><span>Customer id</span>" +
+          "<input type=\"text\" name=\"customer_id\" value=\"" + prefillCid + "\" required maxlength=\"64\" class=\"input-code\" placeholder=\"customer UUID\">" +
+          "<small>From the Customers roster — each row's id column.</small></label>" +
+        "<fieldset class=\"box\"><legend class=\"legend-sm\">Direction</legend>" +
+          "<label class=\"kv\"><input type=\"radio\" name=\"direction\" value=\"grant\" checked> Grant (add points)</label>" +
+          "<label class=\"kv\"><input type=\"radio\" name=\"direction\" value=\"deduct\"> Deduct (remove points)</label>" +
+        "</fieldset>" +
+        "<label class=\"form-field\"><span>Amount (points)</span>" +
+          "<input type=\"number\" name=\"amount\" min=\"1\" step=\"1\" required class=\"input-code\"></label>" +
+        "<label class=\"form-field\"><span>Reason</span>" +
+          "<input type=\"text\" name=\"reason\" required maxlength=\"256\" placeholder=\"e.g. service recovery for order #1234\">" +
+          "<small>Required. Recorded with the adjustment in the ledger.</small></label>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Apply adjustment</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var bodyHtml = "<section><h2>Loyalty</h2>" + adjusted + notice +
+    tierTable + earnSummary + rewardSummary + adjustForm + "</section>";
+  return _renderAdminShell(opts.shop_name, "Loyalty", bodyHtml, "loyalty", opts.nav_available);
+}
+
+// Earn-rules list + create form. Customers earn points only from ACTIVE
+// rules, so the create form defaults `active` on and the list flags
+// inactive / archived rows.
+function renderAdminLoyaltyEarnRules(opts) {
+  opts = opts || {};
+  var rules = opts.rules || [];
+  var triggers = opts.triggers || loyaltyEarnRulesModule.TRIGGERS;
+  var created  = opts.created  ? "<div class=\"banner banner--ok\">Earn rule saved.</div>" : "";
+  var saved    = opts.saved    ? "<div class=\"banner banner--ok\">Saved.</div>" : "";
+  var archived = opts.archived ? "<div class=\"banner banner--ok\">Earn rule archived.</div>" : "";
+  var notice   = opts.notice   ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var bodyRows = rules.map(function (r) {
+    var enc = encodeURIComponent(r.slug);
+    var statusList = (r.customer_status_in && r.customer_status_in.length) ? r.customer_status_in.join(", ") : "all";
+    return "<tr>" +
+      "<td><a href=\"/admin/loyalty/earn-rules/" + _htmlEscape(enc) + "\"><strong>" + _htmlEscape(r.slug) + "</strong></a></td>" +
+      "<td>" + _htmlEscape(r.trigger) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(String(r.points_per_unit)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(r.max_per_event == null ? "—" : String(r.max_per_event)) + "</td>" +
+      "<td>" + _htmlEscape(statusList) + "</td>" +
+      "<td>" + _loyaltyStatusPill(r.active, r.archived_at) + "</td>" +
+      "<td><div class=\"actions-row\">" +
+        "<a class=\"btn btn--ghost\" href=\"/admin/loyalty/earn-rules/" + _htmlEscape(enc) + "\">Manage</a>" +
+        (r.archived_at == null
+          ? "<form method=\"post\" action=\"/admin/loyalty/earn-rules/" + _htmlEscape(enc) + "/archive\" class=\"form-inline\">" +
+              "<button class=\"btn btn--danger\" type=\"submit\">Archive</button></form>"
+          : "") +
+      "</div></td>" +
+    "</tr>";
+  }).join("");
+  var table = rules.length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Slug</th><th scope=\"col\">Trigger</th><th scope=\"col\" class=\"num\">Points/unit</th><th scope=\"col\" class=\"num\">Max/event</th><th scope=\"col\">Statuses</th><th scope=\"col\">Status</th><th scope=\"col\">Actions</th></tr></thead><tbody>" + bodyRows + "</tbody></table></div>"
+    : "<p class=\"empty\">No earn rules yet.</p>";
+
+  var triggerOpts = triggers.map(function (t) {
+    return "<option value=\"" + _htmlEscape(t) + "\">" + _htmlEscape(t) + "</option>";
+  }).join("");
+
+  var createForm =
+    "<div class=\"panel mt mw-40\"><h3 class=\"subhead\">Create an earn rule</h3>" +
+      "<p class=\"meta\">An earn rule grants points when a trigger fires. points/unit is the multiplier for per_dollar_spent / per_purchase and the flat amount for the bonus triggers. Customers earn only from active rules.</p>" +
+      "<form method=\"post\" action=\"/admin/loyalty/earn-rules\">" +
+        _setupField("Slug", "slug", "", "text", "Lowercase letters, digits, dashes (e.g. spend-1pt-per-dollar).", " maxlength=\"100\" required") +
+        "<label class=\"form-field\"><span>Trigger</span><select name=\"trigger\">" + triggerOpts + "</select></label>" +
+        _setupField("Points per unit", "points_per_unit", "", "number", "Positive integer.", " min=\"1\" step=\"1\" required class=\"input-code\"") +
+        _setupField("Max per event", "max_per_event", "", "number", "Optional cap so a huge order doesn't mint a giant balance. Leave blank for uncapped.", " min=\"1\" step=\"1\" class=\"input-code\"") +
+        _setupField("Customer statuses", "customer_status_in", "", "text", "Optional comma-separated list (e.g. active, vip). Blank means every customer is eligible.", " maxlength=\"256\"") +
+        "<label class=\"kv\"><input type=\"checkbox\" name=\"active\" value=\"on\" checked> Active — show this rule to customers and award on its trigger.</label>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Create earn rule</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var bodyHtml = "<section><h2>Earn rules</h2>" +
+    "<p class=\"meta\"><a href=\"/admin/loyalty\">&larr; Loyalty</a></p>" +
+    created + saved + archived + notice + table + createForm + "</section>";
+  return _renderAdminShell(opts.shop_name, "Earn rules", bodyHtml, "loyalty", opts.nav_available);
+}
+
+// Earn-rule detail — the rule's stored fields and an edit form. trigger
+// is immutable on update (the primitive refuses a change), so the form
+// shows it read-only.
+function renderAdminLoyaltyEarnRule(opts) {
+  opts = opts || {};
+  var r = opts.rule;
+  if (!r) {
+    var nf = "<section><h2>Earn rule</h2><p class=\"empty\">Earn rule not found.</p>" +
+      "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/loyalty/earn-rules\">Back to earn rules</a></div></section>";
+    return _renderAdminShell(opts.shop_name, "Earn rule", nf, "loyalty", opts.nav_available);
+  }
+  var saved  = opts.saved  ? "<div class=\"banner banner--ok\">Saved.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var enc = encodeURIComponent(r.slug);
+  var statusList = (r.customer_status_in && r.customer_status_in.length) ? r.customer_status_in.join(", ") : "";
+  var isArchived = r.archived_at != null;
+
+  var editForm = isArchived
+    ? "<div class=\"panel mw-40\"><p class=\"empty\">This rule is archived and can no longer be edited. Archived rules don't award points or show to customers.</p></div>"
+    : "<div class=\"panel mw-40\"><h3 class=\"subhead\">Edit</h3>" +
+        "<form method=\"post\" action=\"/admin/loyalty/earn-rules/" + _htmlEscape(enc) + "/edit\">" +
+          _setupField("Points per unit", "points_per_unit", String(r.points_per_unit), "number", "Positive integer.", " min=\"1\" step=\"1\" class=\"input-code\"") +
+          _setupField("Max per event", "max_per_event", r.max_per_event == null ? "" : String(r.max_per_event), "number", "Blank or 0 clears the cap.", " min=\"0\" step=\"1\" class=\"input-code\"") +
+          _setupField("Customer statuses", "customer_status_in", statusList, "text", "Comma-separated; blank means all customers.", " maxlength=\"256\"") +
+          "<input type=\"hidden\" name=\"active_present\" value=\"1\">" +
+          "<label class=\"kv\"><input type=\"checkbox\" name=\"active\" value=\"on\"" + (r.active ? " checked" : "") + "> Active</label>" +
+          "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Save rule</button></div>" +
+        "</form>" +
+      "</div>";
+
+  var archiveBlock = isArchived ? "" :
+    "<div class=\"actions-row mt-1\">" +
+      "<form method=\"post\" action=\"/admin/loyalty/earn-rules/" + _htmlEscape(enc) + "/archive\" class=\"form-inline\">" +
+        "<button class=\"btn btn--danger\" type=\"submit\">Archive rule</button></form>" +
+    "</div>";
+
+  var head =
+    "<p class=\"meta\"><a href=\"/admin/loyalty/earn-rules\">&larr; Earn rules</a> · " +
+      "<span class=\"status-pill paid\">" + _htmlEscape(r.trigger) + "</span> · " +
+      _loyaltyStatusPill(r.active, r.archived_at) + "</p>";
+
+  var body = "<section><h2>" + _htmlEscape(r.slug) + "</h2>" + saved + notice + head + editForm + archiveBlock + "</section>";
+  return _renderAdminShell(opts.shop_name, "Earn rule", body, "loyalty", opts.nav_available);
+}
+
+// Rewards-catalog list + create form. A reward must be active (and not
+// archived) to appear in the customer's redemption catalog, so the create
+// form defaults active on and the list flags inactive / archived rows.
+function renderAdminLoyaltyRewards(opts) {
+  opts = opts || {};
+  var rewards = opts.rewards || [];
+  var kinds = opts.kinds || loyaltyRedemptionModule.KINDS;
+  var created  = opts.created  ? "<div class=\"banner banner--ok\">Reward saved.</div>" : "";
+  var saved    = opts.saved    ? "<div class=\"banner banner--ok\">Saved.</div>" : "";
+  var archived = opts.archived ? "<div class=\"banner banner--ok\">Reward archived.</div>" : "";
+  var notice   = opts.notice   ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var bodyRows = rewards.map(function (rw) {
+    var enc = encodeURIComponent(rw.slug);
+    return "<tr>" +
+      "<td><a href=\"/admin/loyalty/rewards/" + _htmlEscape(enc) + "\"><strong>" + _htmlEscape(rw.slug) + "</strong></a></td>" +
+      "<td>" + _htmlEscape(rw.title) + "</td>" +
+      "<td>" + _htmlEscape(rw.kind) + "</td>" +
+      "<td>" + _loyaltyRewardValueLabel(rw) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(String(rw.point_cost)) + "</td>" +
+      "<td>" + _loyaltyStatusPill(rw.active, rw.archived_at) + "</td>" +
+      "<td><div class=\"actions-row\">" +
+        "<a class=\"btn btn--ghost\" href=\"/admin/loyalty/rewards/" + _htmlEscape(enc) + "\">Manage</a>" +
+        (rw.archived_at == null
+          ? "<form method=\"post\" action=\"/admin/loyalty/rewards/" + _htmlEscape(enc) + "/archive\" class=\"form-inline\">" +
+              "<button class=\"btn btn--danger\" type=\"submit\">Archive</button></form>"
+          : "") +
+      "</div></td>" +
+    "</tr>";
+  }).join("");
+  var table = rewards.length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Slug</th><th scope=\"col\">Title</th><th scope=\"col\">Kind</th><th scope=\"col\">Value</th><th scope=\"col\" class=\"num\">Point cost</th><th scope=\"col\">Status</th><th scope=\"col\">Actions</th></tr></thead><tbody>" + bodyRows + "</tbody></table></div>"
+    : "<p class=\"empty\">No rewards yet.</p>";
+
+  var kindOpts = kinds.map(function (k) {
+    return "<option value=\"" + _htmlEscape(k) + "\">" + _htmlEscape(k) + "</option>";
+  }).join("");
+
+  var createForm =
+    "<div class=\"panel mt mw-40\"><h3 class=\"subhead\">Create a reward</h3>" +
+      "<p class=\"meta\">A reward debits points at redemption. The value field's meaning depends on the kind: discount_percent → a whole-number percent (1–100); discount_amount → minor units off; free_product → a product id; free_shipping → leave it blank. A reward must be active to appear to customers.</p>" +
+      "<form method=\"post\" action=\"/admin/loyalty/rewards\">" +
+        _setupField("Slug", "slug", "", "text", "Letters, digits, dashes, dots, underscores.", " maxlength=\"80\" required") +
+        "<label class=\"form-field\"><span>Kind</span><select name=\"kind\">" + kindOpts + "</select></label>" +
+        _setupField("Title", "title", "", "text", "Shown to customers in the catalog.", " maxlength=\"200\" required") +
+        _setupField("Point cost", "point_cost", "", "number", "Positive integer — points spent to redeem.", " min=\"1\" step=\"1\" required class=\"input-code\"") +
+        _setupField("Value (number)", "value_number", "", "number", "percent (1–100) or amount in minor units. Leave blank for free_product / free_shipping.", " min=\"1\" step=\"1\" class=\"input-code\"") +
+        _setupField("Value (product id)", "value_text", "", "text", "Only for free_product — the product id the reward grants.", " maxlength=\"128\"") +
+        _setupField("Max per customer", "max_per_customer", "", "number", "Optional lifetime cap per customer. Blank for unlimited.", " min=\"1\" step=\"1\" class=\"input-code\"") +
+        _setupField("Expires (days)", "expires_days_after_redemption", "", "number", "Optional — an unconsumed redemption expires after N days. Blank never expires.", " min=\"1\" step=\"1\" class=\"input-code\"") +
+        "<label class=\"kv\"><input type=\"checkbox\" name=\"active\" value=\"on\" checked> Active — show this reward in the customer catalog.</label>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Create reward</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var bodyHtml = "<section><h2>Rewards catalog</h2>" +
+    "<p class=\"meta\"><a href=\"/admin/loyalty\">&larr; Loyalty</a></p>" +
+    created + saved + archived + notice + table + createForm + "</section>";
+  return _renderAdminShell(opts.shop_name, "Rewards catalog", bodyHtml, "loyalty", opts.nav_available);
+}
+
+// Reward detail — the reward's stored fields and an edit form. kind is
+// immutable on update (the primitive validates value_json against the
+// stored kind), so the form shows it read-only and re-validates value on
+// change.
+function renderAdminLoyaltyReward(opts) {
+  opts = opts || {};
+  var rw = opts.reward;
+  if (!rw) {
+    var nf = "<section><h2>Reward</h2><p class=\"empty\">Reward not found.</p>" +
+      "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/loyalty/rewards\">Back to rewards</a></div></section>";
+    return _renderAdminShell(opts.shop_name, "Reward", nf, "loyalty", opts.nav_available);
+  }
+  var saved  = opts.saved  ? "<div class=\"banner banner--ok\">Saved.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var enc = encodeURIComponent(rw.slug);
+  var isArchived = rw.archived_at != null;
+  var v = rw.value_json || {};
+  var valueNumber = rw.kind === "discount_percent" ? (v.percent == null ? "" : String(v.percent))
+                  : rw.kind === "discount_amount"  ? (v.amount_minor == null ? "" : String(v.amount_minor))
+                  : "";
+  var valueText = rw.kind === "free_product" ? String(v.product_id || "") : "";
+
+  var editForm = isArchived
+    ? "<div class=\"panel mw-40\"><p class=\"empty\">This reward is archived. Archived rewards stay readable for past redemptions but never show to customers.</p></div>"
+    : "<div class=\"panel mw-40\"><h3 class=\"subhead\">Edit</h3>" +
+        "<form method=\"post\" action=\"/admin/loyalty/rewards/" + _htmlEscape(enc) + "/edit\">" +
+          _setupField("Title", "title", rw.title, "text", "", " maxlength=\"200\"") +
+          _setupField("Point cost", "point_cost", String(rw.point_cost), "number", "", " min=\"1\" step=\"1\" class=\"input-code\"") +
+          (rw.kind === "free_product"
+            ? _setupField("Value (product id)", "value_text", valueText, "text", "Leave unchanged to keep the current product.", " maxlength=\"128\"")
+            : rw.kind === "free_shipping"
+              ? "<p class=\"meta\">free_shipping carries no value field.</p>"
+              : _setupField("Value (number)", "value_number", valueNumber, "number", "percent (1–100) or amount in minor units.", " min=\"1\" step=\"1\" class=\"input-code\"")) +
+          _setupField("Max per customer", "max_per_customer", rw.max_per_customer == null ? "" : String(rw.max_per_customer), "number", "", " min=\"1\" step=\"1\" class=\"input-code\"") +
+          _setupField("Expires (days)", "expires_days_after_redemption", rw.expires_days_after_redemption == null ? "" : String(rw.expires_days_after_redemption), "number", "", " min=\"1\" step=\"1\" class=\"input-code\"") +
+          "<input type=\"hidden\" name=\"active_present\" value=\"1\">" +
+          "<label class=\"kv\"><input type=\"checkbox\" name=\"active\" value=\"on\"" + (rw.active ? " checked" : "") + "> Active — show in the customer catalog.</label>" +
+          "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Save reward</button></div>" +
+        "</form>" +
+      "</div>";
+
+  var archiveBlock = isArchived ? "" :
+    "<div class=\"actions-row mt-1\">" +
+      "<form method=\"post\" action=\"/admin/loyalty/rewards/" + _htmlEscape(enc) + "/archive\" class=\"form-inline\">" +
+        "<button class=\"btn btn--danger\" type=\"submit\">Archive reward</button></form>" +
+    "</div>";
+
+  var head =
+    "<p class=\"meta\"><a href=\"/admin/loyalty/rewards\">&larr; Rewards catalog</a> · " +
+      "<span class=\"status-pill paid\">" + _htmlEscape(rw.kind) + "</span> · " +
+      _loyaltyStatusPill(rw.active, rw.archived_at) + " · " +
+      "<code class=\"order-id\">" + _htmlEscape(String(rw.point_cost)) + " pts</code></p>";
+
+  var body = "<section><h2>" + _htmlEscape(rw.title) + "</h2>" + saved + notice + head + editForm + archiveBlock + "</section>";
+  return _renderAdminShell(opts.shop_name, "Reward", body, "loyalty", opts.nav_available);
+}
+
 // Product detail / management screen — the console's full editor for a
 // single catalog product: its fields (slug / title / description /
 // status), its variants (create / edit / delete), each variant's price
@@ -11219,6 +12529,7 @@ module.exports = {
   renderAdminOrders:       renderAdminOrders,
   renderAdminOrder:        renderAdminOrder,
   renderAdminCustomers:    renderAdminCustomers,
+  renderAdminCustomerDetail: renderAdminCustomerDetail,
   renderAdminReturns:      renderAdminReturns,
   renderAdminReturn:       renderAdminReturn,
   renderAdminReviews:      renderAdminReviews,
@@ -11239,5 +12550,10 @@ module.exports = {
   renderAdminDiscountAllocation: renderAdminDiscountAllocation,
   renderAdminQuantityDiscounts: renderAdminQuantityDiscounts,
   renderAdminQuantityDiscount:  renderAdminQuantityDiscount,
+  renderAdminLoyalty:           renderAdminLoyalty,
+  renderAdminLoyaltyEarnRules:  renderAdminLoyaltyEarnRules,
+  renderAdminLoyaltyEarnRule:   renderAdminLoyaltyEarnRule,
+  renderAdminLoyaltyRewards:    renderAdminLoyaltyRewards,
+  renderAdminLoyaltyReward:     renderAdminLoyaltyReward,
   renderAdminConfirm:      renderAdminConfirm,
 };