From 3b27160d0ce64d3f13e610c45cc6ddf57aa3e6b0 Mon Sep 17 00:00:00 2001
From: Pierre Brisorgueil <pierrebrisorgueil@me.com>
Date: Sun, 4 Oct 2026 01:20:27 +0200
Subject: [PATCH 1/4] feat(templates): convert the 15 shared emails to body
 fragments on the default layout

Strip the full-document shell, the copied CTA button table, the hardcoded
sign-off, and the no-reply footer out of config/templates/*.html. Each
fragment now renders through the default layout's header/footer/button
partials: brand.signature (no fallback) replaces the hardcoded sign-off,
the contact footer reaches every mail (5 templates gain it for the first
time), and the CTA templates use {{> button url=url label="..."}}. Each
mail-specific caveat sentence (reset-password/signup/verify) stays in its
body; the generic no-reply tail does not. No hardcoded colors remain in
any of the 15 templates.

Tests: regenerated the baseline normalize() snapshot (now strips <style>
content too, so shared layout CSS doesn't leak into the copy diff) to the
new fragment+layout output, added a brand-colors-and-logo coverage test
across all 15 templates, extended extractVariables to see a bare-var hash
arg inside a {{> partial}} call, and added a real on-disk full-document
fixture so the legacy passthrough path stays exercised now that none of
the shared templates take it any more.

Refs #4133
---
 .../templates/billing-credit-exhausted.html   |  24 +---
 config/templates/billing-credit-warning.html  |  24 +---
 config/templates/billing-payment-failed.html  |  20 +---
 .../templates/billing-quota-reached-100.html  |  26 ++---
 .../templates/billing-quota-warning-80.html   |  26 ++---
 config/templates/org-member-added.html        |  41 +------
 config/templates/org-request-approved.html    |  15 +--
 config/templates/org-request-new.html         |  41 +------
 config/templates/org-request-rejected.html    |  13 +--
 config/templates/referral-reward-earned.html  |  15 +--
 .../reset-password-confirm-email.html         |  16 +--
 config/templates/reset-password-email.html    |  48 +-------
 config/templates/signup-invite.html           |  47 +-------
 config/templates/verify-email.html            |  50 ++-------
 config/templates/welcome.html                 |  50 ++-------
 lib/helpers/mailer/index.js                   |  11 +-
 lib/helpers/mailer/layout.js                  |   9 +-
 .../mailer.templates.unit.tests.js.snap       |  30 ++---
 .../tests/fixtures/legacy-full-document.html  |   9 ++
 .../tests/mailer.layout.real.unit.tests.js    |  24 ++++
 .../tests/mailer.templates.unit.tests.js      | 105 ++++++++++++++----
 21 files changed, 222 insertions(+), 422 deletions(-)
 create mode 100644 lib/helpers/mailer/tests/fixtures/legacy-full-document.html

diff --git a/config/templates/billing-credit-exhausted.html b/config/templates/billing-credit-exhausted.html
index 36723d202..ca28e1213 100644
--- a/config/templates/billing-credit-exhausted.html
+++ b/config/templates/billing-credit-exhausted.html
@@ -1,18 +1,6 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <title></title>
-  </head>
-  <body>
-    <p>Hello,</p>
-    <p>Your <b>{{appName}}</b> account is <b>out of credits</b>.</p>
-    <p>
-      Usage is paused until you add more credits or upgrade your plan — nothing is charged automatically.
-    </p>
-    <p>Add credits or upgrade your plan on your <a href="{{billingUrl}}">billing dashboard</a>.</p>
-    <br />
-    <p>The <b>{{appName}}</b> Team.</p>
-    <br />
-    <i style="color: #9b9b9b">Please do not reply to this email, you can contact us <a href="mailto:{{appContact}}">here</a>.</i>
-  </body>
-</html>
+<p>Hello,</p>
+<p>Your <b>{{appName}}</b> account is <b>out of credits</b>.</p>
+<p>
+  Usage is paused until you add more credits or upgrade your plan — nothing is charged automatically.
+</p>
+<p>Add credits or upgrade your plan on your <a href="{{billingUrl}}">billing dashboard</a>.</p>
diff --git a/config/templates/billing-credit-warning.html b/config/templates/billing-credit-warning.html
index 1680f0ab8..834075ec3 100644
--- a/config/templates/billing-credit-warning.html
+++ b/config/templates/billing-credit-warning.html
@@ -1,18 +1,6 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <title></title>
-  </head>
-  <body>
-    <p>Hello,</p>
-    <p>Your <b>{{appName}}</b> account has <b>{{remaining}} credits left</b>.</p>
-    <p>
-      Usage keeps working while credits remain. Once they run out, usage is paused until you add credits — nothing is charged automatically.
-    </p>
-    <p>Add more credits or upgrade your plan on your <a href="{{billingUrl}}">billing dashboard</a>.</p>
-    <br />
-    <p>The <b>{{appName}}</b> Team.</p>
-    <br />
-    <i style="color: #9b9b9b">Please do not reply to this email, you can contact us <a href="mailto:{{appContact}}">here</a>.</i>
-  </body>
-</html>
+<p>Hello,</p>
+<p>Your <b>{{appName}}</b> account has <b>{{remaining}} credits left</b>.</p>
+<p>
+  Usage keeps working while credits remain. Once they run out, usage is paused until you add credits — nothing is charged automatically.
+</p>
+<p>Add more credits or upgrade your plan on your <a href="{{billingUrl}}">billing dashboard</a>.</p>
diff --git a/config/templates/billing-payment-failed.html b/config/templates/billing-payment-failed.html
index a91468af0..446246163 100644
--- a/config/templates/billing-payment-failed.html
+++ b/config/templates/billing-payment-failed.html
@@ -1,16 +1,4 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <title></title>
-  </head>
-  <body>
-    <p>Hello,</p>
-    <p>We were unable to process the latest payment for your <b>{{appName}}</b> subscription.</p>
-    <p>Your account remains active for now. Please update your payment method before the grace period ends to avoid any service interruption.</p>
-    <p>Update your card on your <a href="{{billingPortalUrl}}">billing portal</a>.</p>
-    <br />
-    <p>The <b>{{appName}}</b> Team.</p>
-    <br />
-    <i style="color: #9b9b9b">Please do not reply to this email, you can contact us <a href="mailto:{{appContact}}">here</a>.</i>
-  </body>
-</html>
+<p>Hello,</p>
+<p>We were unable to process the latest payment for your <b>{{appName}}</b> subscription.</p>
+<p>Your account remains active for now. Please update your payment method before the grace period ends to avoid any service interruption.</p>
+<p>Update your card on your <a href="{{billingPortalUrl}}">billing portal</a>.</p>
diff --git a/config/templates/billing-quota-reached-100.html b/config/templates/billing-quota-reached-100.html
index 3d2fceff6..8baf3d89e 100644
--- a/config/templates/billing-quota-reached-100.html
+++ b/config/templates/billing-quota-reached-100.html
@@ -1,19 +1,7 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <title></title>
-  </head>
-  <body>
-    <p>Hello,</p>
-    <p>Your <b>{{appName}}</b> weekly quota is now fully used ({{meterUsed}} / {{meterQuota}} units).</p>
-    <p>
-      If you have an extras pack, your usage continues drawing from its remaining balance until it's used up. Otherwise it pauses until you add an
-      extras pack or upgrade your plan — nothing is charged automatically.
-    </p>
-    <p>Check your consumption or add an extras pack on your <a href="{{billingUrl}}">billing dashboard</a>.</p>
-    <br />
-    <p>The <b>{{appName}}</b> Team.</p>
-    <br />
-    <i style="color: #9b9b9b">Please do not reply to this email, you can contact us <a href="mailto:{{appContact}}">here</a>.</i>
-  </body>
-</html>
+<p>Hello,</p>
+<p>Your <b>{{appName}}</b> weekly quota is now fully used ({{meterUsed}} / {{meterQuota}} units).</p>
+<p>
+  If you have an extras pack, your usage continues drawing from its remaining balance until it's used up. Otherwise it pauses until you add an
+  extras pack or upgrade your plan — nothing is charged automatically.
+</p>
+<p>Check your consumption or add an extras pack on your <a href="{{billingUrl}}">billing dashboard</a>.</p>
diff --git a/config/templates/billing-quota-warning-80.html b/config/templates/billing-quota-warning-80.html
index 5ad4872ba..bf4b78535 100644
--- a/config/templates/billing-quota-warning-80.html
+++ b/config/templates/billing-quota-warning-80.html
@@ -1,19 +1,7 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <title></title>
-  </head>
-  <body>
-    <p>Hello,</p>
-    <p>Your <b>{{appName}}</b> plan has reached <b>{{threshold}}%</b> of its weekly quota ({{meterUsed}} / {{meterQuota}} units used).</p>
-    <p>
-      You still have room to keep going. Once you reach 100%, runs continue only while you have an extras-pack balance; without one they pause until
-      you add an extras pack or upgrade your plan — nothing is charged automatically.
-    </p>
-    <p>Review your usage, add an extras pack, or upgrade your plan on your <a href="{{billingUrl}}">billing dashboard</a>.</p>
-    <br />
-    <p>The <b>{{appName}}</b> Team.</p>
-    <br />
-    <i style="color: #9b9b9b">Please do not reply to this email, you can contact us <a href="mailto:{{appContact}}">here</a>.</i>
-  </body>
-</html>
+<p>Hello,</p>
+<p>Your <b>{{appName}}</b> plan has reached <b>{{threshold}}%</b> of its weekly quota ({{meterUsed}} / {{meterQuota}} units used).</p>
+<p>
+  You still have room to keep going. Once you reach 100%, runs continue only while you have an extras-pack balance; without one they pause until
+  you add an extras pack or upgrade your plan — nothing is charged automatically.
+</p>
+<p>Review your usage, add an extras pack, or upgrade your plan on your <a href="{{billingUrl}}">billing dashboard</a>.</p>
diff --git a/config/templates/org-member-added.html b/config/templates/org-member-added.html
index 0b00ab255..b749da766 100644
--- a/config/templates/org-member-added.html
+++ b/config/templates/org-member-added.html
@@ -1,36 +1,5 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <title>{{appName}} invitation</title>
-  </head>
-  <body>
-    <p>Hello {{displayName}},</p>
-    <p>You have been invited to join <b>{{orgName}}</b> on {{appName}}.</p>
-    <p>Review and accept the invitation:</p>
-    <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin: 24px 0">
-      <tr>
-        <td align="center" bgcolor="#1a1a1a" style="border-radius: 6px">
-          <a
-            href="{{url}}"
-            target="_blank"
-            rel="noopener noreferrer"
-            style="
-              display: inline-block;
-              padding: 12px 28px;
-              font-family: Arial, Helvetica, sans-serif;
-              font-size: 16px;
-              font-weight: bold;
-              line-height: 20px;
-              color: #ffffff;
-              text-decoration: none;
-              border-radius: 6px;
-            "
-            >Accept invitation</a
-          >
-        </td>
-      </tr>
-    </table>
-    <p style="font-size: 13px; color: #9b9b9b">Button not working? <a href="{{url}}">{{url}}</a></p>
-    <p>The <b>{{appName}}</b> Team.</p>
-  </body>
-</html>
+<p>Hello {{displayName}},</p>
+<p>You have been invited to join <b>{{orgName}}</b> on {{appName}}.</p>
+<p>Review and accept the invitation:</p>
+{{> button url=url label="Accept invitation"}}
+<p style="font-size: 13px">Button not working? <a href="{{url}}">{{url}}</a></p>
diff --git a/config/templates/org-request-approved.html b/config/templates/org-request-approved.html
index 5422a6600..911b5d4d6 100644
--- a/config/templates/org-request-approved.html
+++ b/config/templates/org-request-approved.html
@@ -1,12 +1,3 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <title></title>
-  </head>
-  <body>
-    <p>Hello {{displayName}},</p>
-    <p>Your request to join <b>{{orgName}}</b> on {{appName}} has been approved.</p>
-    <p>You can now access the organization.</p>
-    <p>The <b>{{appName}}</b> Team.</p>
-  </body>
-</html>
+<p>Hello {{displayName}},</p>
+<p>Your request to join <b>{{orgName}}</b> on {{appName}} has been approved.</p>
+<p>You can now access the organization.</p>
diff --git a/config/templates/org-request-new.html b/config/templates/org-request-new.html
index d7c5a4b07..851d823cb 100644
--- a/config/templates/org-request-new.html
+++ b/config/templates/org-request-new.html
@@ -1,36 +1,5 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <title></title>
-  </head>
-  <body>
-    <p>Hello,</p>
-    <p><b>{{requesterName}}</b> ({{requesterEmail}}) has requested to join your organization <b>{{orgName}}</b> on {{appName}}.</p>
-    <p>Review this request in your dashboard:</p>
-    <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin: 24px 0">
-      <tr>
-        <td align="center" bgcolor="#1a1a1a" style="border-radius: 6px">
-          <a
-            href="{{url}}"
-            target="_blank"
-            rel="noopener noreferrer"
-            style="
-              display: inline-block;
-              padding: 12px 28px;
-              font-family: Arial, Helvetica, sans-serif;
-              font-size: 16px;
-              font-weight: bold;
-              line-height: 20px;
-              color: #ffffff;
-              text-decoration: none;
-              border-radius: 6px;
-            "
-            >Review request</a
-          >
-        </td>
-      </tr>
-    </table>
-    <p style="font-size: 13px; color: #9b9b9b">Button not working? <a href="{{url}}">{{url}}</a></p>
-    <p>The <b>{{appName}}</b> Team.</p>
-  </body>
-</html>
+<p>Hello,</p>
+<p><b>{{requesterName}}</b> ({{requesterEmail}}) has requested to join your organization <b>{{orgName}}</b> on {{appName}}.</p>
+<p>Review this request in your dashboard:</p>
+{{> button url=url label="Review request"}}
+<p style="font-size: 13px">Button not working? <a href="{{url}}">{{url}}</a></p>
diff --git a/config/templates/org-request-rejected.html b/config/templates/org-request-rejected.html
index 79fcc9390..c69031300 100644
--- a/config/templates/org-request-rejected.html
+++ b/config/templates/org-request-rejected.html
@@ -1,11 +1,2 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <title></title>
-  </head>
-  <body>
-    <p>Hello {{displayName}},</p>
-    <p>Your request to join <b>{{orgName}}</b> on {{appName}} has been declined.</p>
-    <p>The <b>{{appName}}</b> Team.</p>
-  </body>
-</html>
+<p>Hello {{displayName}},</p>
+<p>Your request to join <b>{{orgName}}</b> on {{appName}} has been declined.</p>
diff --git a/config/templates/referral-reward-earned.html b/config/templates/referral-reward-earned.html
index 71b49828a..2a4958d8e 100644
--- a/config/templates/referral-reward-earned.html
+++ b/config/templates/referral-reward-earned.html
@@ -1,12 +1,3 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <title>{{appName}} referral reward</title>
-  </head>
-  <body>
-    <p>Hello {{displayName}},</p>
-    <p>Great news — someone you invited just joined {{appName}}, and you've earned a referral reward of {{units}} units.</p>
-    <p>Thanks for helping grow {{appName}}.</p>
-    <p>The <b>{{appName}}</b> Team.</p>
-  </body>
-</html>
+<p>Hello {{displayName}},</p>
+<p>Great news — someone you invited just joined {{appName}}, and you've earned a referral reward of {{units}} units.</p>
+<p>Thanks for helping grow {{appName}}.</p>
diff --git a/config/templates/reset-password-confirm-email.html b/config/templates/reset-password-confirm-email.html
index 6df17b307..3ef200a01 100644
--- a/config/templates/reset-password-confirm-email.html
+++ b/config/templates/reset-password-confirm-email.html
@@ -1,14 +1,2 @@
-<!doctype html>
-<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
-  <head>
-    <title></title>
-  </head>
-
-  <body>
-    <p>Dear {{displayName}},</p>
-    <p>This is a confirmation that the password for your account has just been changed</p>
-    <p>The <b>{{appName}}</b> Support Team.</p>
-    <br />
-    <i style="color: #9b9b9b">Please do not reply to this email, you can contact us <a href="mailto:{{appContact}}">here</a>.</i>
-  </body>
-</html>
+<p>Dear {{displayName}},</p>
+<p>This is a confirmation that the password for your account has just been changed</p>
diff --git a/config/templates/reset-password-email.html b/config/templates/reset-password-email.html
index 71ca5c26d..1313e7290 100644
--- a/config/templates/reset-password-email.html
+++ b/config/templates/reset-password-email.html
@@ -1,42 +1,6 @@
-<!doctype html>
-<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
-  <head>
-    <title></title>
-  </head>
-
-  <body>
-    <p>Dear {{displayName}},</p>
-    <p>You have requested to reset your password on {{appName}}</p>
-    <p>Click the button below to choose a new password:</p>
-    <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin: 24px 0">
-      <tr>
-        <td align="center" bgcolor="#1a1a1a" style="border-radius: 6px">
-          <a
-            href="{{url}}"
-            target="_blank"
-            rel="noopener noreferrer"
-            style="
-              display: inline-block;
-              padding: 12px 28px;
-              font-family: Arial, Helvetica, sans-serif;
-              font-size: 16px;
-              font-weight: bold;
-              line-height: 20px;
-              color: #ffffff;
-              text-decoration: none;
-              border-radius: 6px;
-            "
-            >Reset password</a
-          >
-        </td>
-      </tr>
-    </table>
-    <p style="font-size: 13px; color: #9b9b9b">Button not working? <a href="{{url}}">{{url}}</a></p>
-    <p>The <b>{{appName}}</b> Support Team.</p>
-    <br />
-    <i style="color: #9b9b9b"
-      >If you didn't make this request, you can ignore this email. Please do not reply to this email, you can contact us
-      <a href="mailto:{{appContact}}">here</a>.</i
-    >
-  </body>
-</html>
+<p>Dear {{displayName}},</p>
+<p>You have requested to reset your password on {{appName}}</p>
+<p>Click the button below to choose a new password:</p>
+{{> button url=url label="Reset password"}}
+<p style="font-size: 13px">Button not working? <a href="{{url}}">{{url}}</a></p>
+<p><i>If you didn't make this request, you can ignore this email.</i></p>
diff --git a/config/templates/signup-invite.html b/config/templates/signup-invite.html
index e40fce3ac..4f58ec4f8 100644
--- a/config/templates/signup-invite.html
+++ b/config/templates/signup-invite.html
@@ -1,41 +1,6 @@
-<!doctype html>
-<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
-  <head>
-    <title>You've been invited — complete your signup</title>
-  </head>
-  <body>
-    <p>Hello,</p>
-    <p>You've been invited to join <b>{{appName}}</b>.</p>
-    <p>Click the button below to create your account:</p>
-    <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin: 24px 0">
-      <tr>
-        <td align="center" bgcolor="#1a1a1a" style="border-radius: 6px">
-          <a
-            href="{{url}}"
-            target="_blank"
-            rel="noopener noreferrer"
-            style="
-              display: inline-block;
-              padding: 12px 28px;
-              font-family: Arial, Helvetica, sans-serif;
-              font-size: 16px;
-              font-weight: bold;
-              line-height: 20px;
-              color: #ffffff;
-              text-decoration: none;
-              border-radius: 6px;
-            "
-            >Create your account</a
-          >
-        </td>
-      </tr>
-    </table>
-    <p style="font-size: 13px; color: #9b9b9b">Button not working? <a href="{{url}}">{{url}}</a></p>
-    <p>The <b>{{appName}}</b> Team.</p>
-    <br />
-    <i style="color: #9b9b9b"
-      >If you weren't expecting this invitation you can ignore this email. Please do not reply to this email, you can contact us
-      <a href="mailto:{{appContact}}">here</a>.</i
-    >
-  </body>
-</html>
+<p>Hello,</p>
+<p>You've been invited to join <b>{{appName}}</b>.</p>
+<p>Click the button below to create your account:</p>
+{{> button url=url label="Create your account"}}
+<p style="font-size: 13px">Button not working? <a href="{{url}}">{{url}}</a></p>
+<p><i>If you weren't expecting this invitation you can ignore this email.</i></p>
diff --git a/config/templates/verify-email.html b/config/templates/verify-email.html
index 3dfe7de17..ba2d2aa47 100644
--- a/config/templates/verify-email.html
+++ b/config/templates/verify-email.html
@@ -1,43 +1,7 @@
-<!doctype html>
-<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
-  <head>
-    <title></title>
-  </head>
-
-  <body>
-    <p>Dear {{displayName}},</p>
-    <p>Thank you for signing up on {{appName}}.</p>
-    <p>Please verify your email address by clicking the button below:</p>
-    <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin: 24px 0">
-      <tr>
-        <td align="center" bgcolor="#1a1a1a" style="border-radius: 6px">
-          <a
-            href="{{url}}"
-            target="_blank"
-            rel="noopener noreferrer"
-            style="
-              display: inline-block;
-              padding: 12px 28px;
-              font-family: Arial, Helvetica, sans-serif;
-              font-size: 16px;
-              font-weight: bold;
-              line-height: 20px;
-              color: #ffffff;
-              text-decoration: none;
-              border-radius: 6px;
-            "
-            >Verify email address</a
-          >
-        </td>
-      </tr>
-    </table>
-    <p style="font-size: 13px; color: #9b9b9b">Button not working? <a href="{{url}}">{{url}}</a></p>
-    <p>This link will expire in 24 hours.</p>
-    <p>The <b>{{appName}}</b> Support Team.</p>
-    <br />
-    <i style="color: #9b9b9b"
-      >If you didn't create this account, you can ignore this email. Please do not reply to this email, you can contact us
-      <a href="mailto:{{appContact}}">here</a>.</i
-    >
-  </body>
-</html>
+<p>Dear {{displayName}},</p>
+<p>Thank you for signing up on {{appName}}.</p>
+<p>Please verify your email address by clicking the button below:</p>
+{{> button url=url label="Verify email address"}}
+<p style="font-size: 13px">Button not working? <a href="{{url}}">{{url}}</a></p>
+<p>This link will expire in 24 hours.</p>
+<p><i>If you didn't create this account, you can ignore this email.</i></p>
diff --git a/config/templates/welcome.html b/config/templates/welcome.html
index 856bd3f21..e27da3ad4 100644
--- a/config/templates/welcome.html
+++ b/config/templates/welcome.html
@@ -1,43 +1,7 @@
-<!doctype html>
-<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
-  <head>
-    <title>{{appName}}</title>
-  </head>
-
-  <body>
-    <p>Hello {{displayName}},</p>
-    <p>
-      Welcome to {{appName}}{{#if orgName}} — your workspace <b>{{orgName}}</b> is ready{{/if}}.
-    </p>
-    <p>Here's where to pick things up:</p>
-    <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin: 24px 0">
-      <tr>
-        <td align="center" bgcolor="#1a1a1a" style="border-radius: 6px">
-          <a
-            href="{{url}}"
-            target="_blank"
-            rel="noopener noreferrer"
-            style="
-              display: inline-block;
-              padding: 12px 28px;
-              font-family: Arial, Helvetica, sans-serif;
-              font-size: 16px;
-              font-weight: bold;
-              line-height: 20px;
-              color: #ffffff;
-              text-decoration: none;
-              border-radius: 6px;
-            "
-            >Get started</a
-          >
-        </td>
-      </tr>
-    </table>
-    <p style="font-size: 13px; color: #9b9b9b">Button not working? <a href="{{url}}">{{url}}</a></p>
-    <p>The <b>{{appName}}</b> Team.</p>
-    <br />
-    <i style="color: #9b9b9b"
-      >Please do not reply to this email, you can contact us <a href="mailto:{{appContact}}">here</a>.</i
-    >
-  </body>
-</html>
+<p>Hello {{displayName}},</p>
+<p>
+  Welcome to {{appName}}{{#if orgName}} — your workspace <b>{{orgName}}</b> is ready{{/if}}.
+</p>
+<p>Here's where to pick things up:</p>
+{{> button url=url label="Get started"}}
+<p style="font-size: 13px">Button not working? <a href="{{url}}">{{url}}</a></p>
diff --git a/lib/helpers/mailer/index.js b/lib/helpers/mailer/index.js
index fca8ffc08..8f5de0bde 100644
--- a/lib/helpers/mailer/index.js
+++ b/lib/helpers/mailer/index.js
@@ -103,8 +103,10 @@ const hbs = handlebars.create();
  *   returns before this is ever called (epic-audit follow-up on
  *   #4160/#4127) and is compiled on its own pristine `handlebars.create()`
  *   instance instead, so `{{> partial}}` is NOT available to a legacy full
- *   document, deliberately (none of the 15 shipped legacy templates use
- *   one today). The 4 reads are independent, so they run in parallel.
+ *   document, deliberately (none of today's shared Devkit templates are
+ *   full documents any more — #4133 — so only a downstream's own
+ *   full-document template takes this path). The 4 reads are independent,
+ *   so they run in parallel.
  *   Re-read and re-registered on every render, same no-cache behavior as
  *   the template/layout file reads below.
  * @returns {Promise<void>}
@@ -141,8 +143,9 @@ const registerPartials = async () => {
  *   inherit a `{{> partial}}` registration left over from a prior fragment
  *   render in the same process — a legacy document that references a partial
  *   now always throws, deterministically, instead of sometimes resolving
- *   depending on render order. None of the 15 shipped legacy templates
- *   reference a partial today.
+ *   depending on render order. None of today's shared Devkit templates
+ *   take this path any more (#4133); only a downstream's own full-document
+ *   template does.
  *
  *   Every other template is a body fragment: it is wrapped in `mailer.layout`
  *   (or the Devkit default), which receives `{{{body}}}` (the only unescaped
diff --git a/lib/helpers/mailer/layout.js b/lib/helpers/mailer/layout.js
index d0ef55fb8..cccca778e 100644
--- a/lib/helpers/mailer/layout.js
+++ b/lib/helpers/mailer/layout.js
@@ -19,10 +19,11 @@ export const PARTIAL_NAMES = Object.keys(DEFAULT_PARTIAL_PATHS);
 const LEGACY_FULL_DOCUMENT_RE = /^\s*<(!doctype|html)\b/i;
 
 /**
- * @desc Detect a legacy full-document template (today's 15 shared mails,
- *   and any full-document template a downstream owns): it is already a
- *   complete HTML document, so it is sent unwrapped instead of through the
- *   layout.
+ * @desc Detect a legacy full-document template (a downstream's own full
+ *   document, e.g. its own branded email a project ships outside Devkit's
+ *   `config/templates/`): it is already a complete HTML document, so it is
+ *   sent unwrapped instead of through the layout. The 15 shared Devkit
+ *   mails (#4133) are body fragments and never match this.
  * @param {string} source - Raw (uncompiled) template source
  * @returns {boolean} True when the source is a full document
  */
diff --git a/lib/helpers/mailer/tests/__snapshots__/mailer.templates.unit.tests.js.snap b/lib/helpers/mailer/tests/__snapshots__/mailer.templates.unit.tests.js.snap
index 06d0ed473..59ae0bc07 100644
--- a/lib/helpers/mailer/tests/__snapshots__/mailer.templates.unit.tests.js.snap
+++ b/lib/helpers/mailer/tests/__snapshots__/mailer.templates.unit.tests.js.snap
@@ -1,31 +1,31 @@
 // Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
-exports[`mailer baseline render — all shared templates: renders billing-credit-exhausted with every referenced variable present in its fixture 1`] = `"Hello, Your Acme account is out of credits . Usage is paused until you add more credits or upgrade your plan — nothing is charged automatically. Add credits or upgrade your plan on your billing dashboard . The Acme Team. Please do not reply to this email, you can contact us here ."`;
+exports[`mailer baseline render — all shared templates: renders billing-credit-exhausted with every referenced variable present in its fixture 1`] = `"Acme Hello, Your Acme account is out of credits . Usage is paused until you add more credits or upgrade your plan — nothing is charged automatically. Add credits or upgrade your plan on your billing dashboard . Questions? help@example.com https://acme.test"`;
 
-exports[`mailer baseline render — all shared templates: renders billing-credit-warning with every referenced variable present in its fixture 1`] = `"Hello, Your Acme account has 12 credits left . Usage keeps working while credits remain. Once they run out, usage is paused until you add credits — nothing is charged automatically. Add more credits or upgrade your plan on your billing dashboard . The Acme Team. Please do not reply to this email, you can contact us here ."`;
+exports[`mailer baseline render — all shared templates: renders billing-credit-warning with every referenced variable present in its fixture 1`] = `"Acme Hello, Your Acme account has 12 credits left . Usage keeps working while credits remain. Once they run out, usage is paused until you add credits — nothing is charged automatically. Add more credits or upgrade your plan on your billing dashboard . Questions? help@example.com https://acme.test"`;
 
-exports[`mailer baseline render — all shared templates: renders billing-payment-failed with every referenced variable present in its fixture 1`] = `"Hello, We were unable to process the latest payment for your Acme subscription. Your account remains active for now. Please update your payment method before the grace period ends to avoid any service interruption. Update your card on your billing portal . The Acme Team. Please do not reply to this email, you can contact us here ."`;
+exports[`mailer baseline render — all shared templates: renders billing-payment-failed with every referenced variable present in its fixture 1`] = `"Acme Hello, We were unable to process the latest payment for your Acme subscription. Your account remains active for now. Please update your payment method before the grace period ends to avoid any service interruption. Update your card on your billing portal . Questions? help@example.com https://acme.test"`;
 
-exports[`mailer baseline render — all shared templates: renders billing-quota-reached-100 with every referenced variable present in its fixture 1`] = `"Hello, Your Acme weekly quota is now fully used (1000 / 1000 units). If you have an extras pack, your usage continues drawing from its remaining balance until it's used up. Otherwise it pauses until you add an extras pack or upgrade your plan — nothing is charged automatically. Check your consumption or add an extras pack on your billing dashboard . The Acme Team. Please do not reply to this email, you can contact us here ."`;
+exports[`mailer baseline render — all shared templates: renders billing-quota-reached-100 with every referenced variable present in its fixture 1`] = `"Acme Hello, Your Acme weekly quota is now fully used (1000 / 1000 units). If you have an extras pack, your usage continues drawing from its remaining balance until it's used up. Otherwise it pauses until you add an extras pack or upgrade your plan — nothing is charged automatically. Check your consumption or add an extras pack on your billing dashboard . Questions? help@example.com https://acme.test"`;
 
-exports[`mailer baseline render — all shared templates: renders billing-quota-warning-80 with every referenced variable present in its fixture 1`] = `"Hello, Your Acme plan has reached 80% of its weekly quota (800 / 1000 units used). You still have room to keep going. Once you reach 100%, runs continue only while you have an extras-pack balance; without one they pause until you add an extras pack or upgrade your plan — nothing is charged automatically. Review your usage, add an extras pack, or upgrade your plan on your billing dashboard . The Acme Team. Please do not reply to this email, you can contact us here ."`;
+exports[`mailer baseline render — all shared templates: renders billing-quota-warning-80 with every referenced variable present in its fixture 1`] = `"Acme Hello, Your Acme plan has reached 80% of its weekly quota (800 / 1000 units used). You still have room to keep going. Once you reach 100%, runs continue only while you have an extras-pack balance; without one they pause until you add an extras pack or upgrade your plan — nothing is charged automatically. Review your usage, add an extras pack, or upgrade your plan on your billing dashboard . Questions? help@example.com https://acme.test"`;
 
-exports[`mailer baseline render — all shared templates: renders org-member-added with every referenced variable present in its fixture 1`] = `"Acme invitation Hello Alice, You have been invited to join Acme Org on Acme. Review and accept the invitation: Accept invitation Button not working? https://acme.test/org The Acme Team."`;
+exports[`mailer baseline render — all shared templates: renders org-member-added with every referenced variable present in its fixture 1`] = `"Acme Hello Alice, You have been invited to join Acme Org on Acme. Review and accept the invitation: Accept invitation Button not working? https://acme.test/org Questions? help@example.com https://acme.test"`;
 
-exports[`mailer baseline render — all shared templates: renders org-request-approved with every referenced variable present in its fixture 1`] = `"Hello Alice, Your request to join Acme Org on Acme has been approved. You can now access the organization. The Acme Team."`;
+exports[`mailer baseline render — all shared templates: renders org-request-approved with every referenced variable present in its fixture 1`] = `"Acme Hello Alice, Your request to join Acme Org on Acme has been approved. You can now access the organization. Questions? help@example.com https://acme.test"`;
 
-exports[`mailer baseline render — all shared templates: renders org-request-new with every referenced variable present in its fixture 1`] = `"Hello, Bob (bob@example.com) has requested to join your organization Acme Org on Acme. Review this request in your dashboard: Review request Button not working? https://acme.test/request The Acme Team."`;
+exports[`mailer baseline render — all shared templates: renders org-request-new with every referenced variable present in its fixture 1`] = `"Acme Hello, Bob (bob@example.com) has requested to join your organization Acme Org on Acme. Review this request in your dashboard: Review request Button not working? https://acme.test/request Questions? help@example.com https://acme.test"`;
 
-exports[`mailer baseline render — all shared templates: renders org-request-rejected with every referenced variable present in its fixture 1`] = `"Hello Alice, Your request to join Acme Org on Acme has been declined. The Acme Team."`;
+exports[`mailer baseline render — all shared templates: renders org-request-rejected with every referenced variable present in its fixture 1`] = `"Acme Hello Alice, Your request to join Acme Org on Acme has been declined. Questions? help@example.com https://acme.test"`;
 
-exports[`mailer baseline render — all shared templates: renders referral-reward-earned with every referenced variable present in its fixture 1`] = `"Acme referral reward Hello Alice, Great news — someone you invited just joined Acme, and you've earned a referral reward of 5 units. Thanks for helping grow Acme. The Acme Team."`;
+exports[`mailer baseline render — all shared templates: renders referral-reward-earned with every referenced variable present in its fixture 1`] = `"Acme Hello Alice, Great news — someone you invited just joined Acme, and you've earned a referral reward of 5 units. Thanks for helping grow Acme. Questions? help@example.com https://acme.test"`;
 
-exports[`mailer baseline render — all shared templates: renders reset-password-confirm-email with every referenced variable present in its fixture 1`] = `"Dear Alice, This is a confirmation that the password for your account has just been changed The Acme Support Team. Please do not reply to this email, you can contact us here ."`;
+exports[`mailer baseline render — all shared templates: renders reset-password-confirm-email with every referenced variable present in its fixture 1`] = `"Acme Dear Alice, This is a confirmation that the password for your account has just been changed Questions? help@example.com https://acme.test"`;
 
-exports[`mailer baseline render — all shared templates: renders reset-password-email with every referenced variable present in its fixture 1`] = `"Dear Alice, You have requested to reset your password on Acme Click the button below to choose a new password: Reset password Button not working? https://acme.test/reset The Acme Support Team. If you didn't make this request, you can ignore this email. Please do not reply to this email, you can contact us here ."`;
+exports[`mailer baseline render — all shared templates: renders reset-password-email with every referenced variable present in its fixture 1`] = `"Acme Dear Alice, You have requested to reset your password on Acme Click the button below to choose a new password: Reset password Button not working? https://acme.test/reset If you didn't make this request, you can ignore this email. Questions? help@example.com https://acme.test"`;
 
-exports[`mailer baseline render — all shared templates: renders signup-invite with every referenced variable present in its fixture 1`] = `"You've been invited — complete your signup Hello, You've been invited to join Acme . Click the button below to create your account: Create your account Button not working? https://acme.test/invite The Acme Team. If you weren't expecting this invitation you can ignore this email. Please do not reply to this email, you can contact us here ."`;
+exports[`mailer baseline render — all shared templates: renders signup-invite with every referenced variable present in its fixture 1`] = `"Acme Hello, You've been invited to join Acme . Click the button below to create your account: Create your account Button not working? https://acme.test/invite If you weren't expecting this invitation you can ignore this email. Questions? help@example.com https://acme.test"`;
 
-exports[`mailer baseline render — all shared templates: renders verify-email with every referenced variable present in its fixture 1`] = `"Dear Alice, Thank you for signing up on Acme. Please verify your email address by clicking the button below: Verify email address Button not working? https://acme.test/verify This link will expire in 24 hours. The Acme Support Team. If you didn't create this account, you can ignore this email. Please do not reply to this email, you can contact us here ."`;
+exports[`mailer baseline render — all shared templates: renders verify-email with every referenced variable present in its fixture 1`] = `"Acme Dear Alice, Thank you for signing up on Acme. Please verify your email address by clicking the button below: Verify email address Button not working? https://acme.test/verify This link will expire in 24 hours. If you didn't create this account, you can ignore this email. Questions? help@example.com https://acme.test"`;
 
-exports[`mailer baseline render — all shared templates: renders welcome with every referenced variable present in its fixture 1`] = `"Acme Hello Alice, Welcome to Acme — your workspace Acme Org is ready. Here's where to pick things up: Get started Button not working? https://acme.test/dashboard The Acme Team. Please do not reply to this email, you can contact us here ."`;
+exports[`mailer baseline render — all shared templates: renders welcome with every referenced variable present in its fixture 1`] = `"Acme Hello Alice, Welcome to Acme — your workspace Acme Org is ready. Here's where to pick things up: Get started Button not working? https://acme.test/dashboard Questions? help@example.com https://acme.test"`;
diff --git a/lib/helpers/mailer/tests/fixtures/legacy-full-document.html b/lib/helpers/mailer/tests/fixtures/legacy-full-document.html
new file mode 100644
index 000000000..da56c60a9
--- /dev/null
+++ b/lib/helpers/mailer/tests/fixtures/legacy-full-document.html
@@ -0,0 +1,9 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <title>Legacy document</title>
+  </head>
+  <body>
+    <p>Hi {{name}}, this is a full document a downstream project ships on its own, outside the shared layout.</p>
+  </body>
+</html>
diff --git a/lib/helpers/mailer/tests/mailer.layout.real.unit.tests.js b/lib/helpers/mailer/tests/mailer.layout.real.unit.tests.js
index f43bd4c2d..7b2193de2 100644
--- a/lib/helpers/mailer/tests/mailer.layout.real.unit.tests.js
+++ b/lib/helpers/mailer/tests/mailer.layout.real.unit.tests.js
@@ -31,6 +31,11 @@ const mockConfig = {
   mailer: {
     templates: {
       'layout-smoke-fragment': 'lib/helpers/mailer/tests/fixtures/layout-smoke-fragment.html',
+      // A downstream's own full document (#4133: none of the 15 shared
+      // Devkit templates are full documents any more, so the legacy
+      // passthrough path needs its own fixture to stay exercised against
+      // real, unmocked files).
+      'legacy-full-document': 'lib/helpers/mailer/tests/fixtures/legacy-full-document.html',
     },
     layout: undefined,
     partials: {},
@@ -131,4 +136,23 @@ describe('mailer layout — real shipped defaults (unmocked files):', () => {
     expect(styleBlock).not.toContain('&#x27;');
     expect(styleBlock).not.toContain('#112233'); // brand.primaryColor — also left <style> entirely
   });
+
+  test('a real full-document fixture (a downstream template) stays on the legacy passthrough path, byte-identical, with no layout/brand applied (#4133)', async () => {
+    const html = await mailer.render('legacy-full-document', { name: 'Alice' });
+
+    expect(html).toBe(`<!doctype html>
+<html lang="en">
+  <head>
+    <title>Legacy document</title>
+  </head>
+  <body>
+    <p>Hi Alice, this is a full document a downstream project ships on its own, outside the shared layout.</p>
+  </body>
+</html>
+`);
+    // None of the brand/layout machinery leaked in: no header/footer
+    // partials, no brand.logoUrl, no Email settings/Questions? links.
+    expect(html).not.toContain(FULL_BRAND.logoUrl);
+    expect(html).not.toContain('Questions?');
+  });
 });
diff --git a/lib/helpers/mailer/tests/mailer.templates.unit.tests.js b/lib/helpers/mailer/tests/mailer.templates.unit.tests.js
index b3519b2b9..190cd9a57 100644
--- a/lib/helpers/mailer/tests/mailer.templates.unit.tests.js
+++ b/lib/helpers/mailer/tests/mailer.templates.unit.tests.js
@@ -2,23 +2,38 @@
  * Baseline render coverage for all shared `config/templates/*.html` files.
  *
  * `files.js` is left unmocked so `mailer.render()` reads the real templates
- * from disk — this is the "today's behavior" baseline that a future
- * fragments-on-layout conversion (#4133) diffs against via the snapshot
- * below. Only `config/index.js` is mocked, matching the rest of this suite.
+ * (and the real `_layout/*.html` partials/layout they render through,
+ * post-#4133) from disk. Only `config/index.js` is mocked, matching the
+ * rest of this suite. The snapshot below is the current baseline — a body
+ * fragment wrapped in the default layout, not the pre-#4133 full-document
+ * output, so it no longer carries each template's old `<title>` text or
+ * its old hardcoded sign-off ("The Acme Team."/"Support Team.", gone with
+ * no `brand.signature` configured) — see the brand-colors test further
+ * down for the config-driven replacements (signature, logo, link).
  */
 import { jest, describe, test, expect } from '@jest/globals';
 import fs from 'fs';
 import path from 'path';
 
+// Mutable mock config (like mailer.brand.unit.tests.js /
+// mailer.layout.unit.tests.js): the brand-colors-and-logo test below
+// reassigns `mockConfig.mailer.brand` per test without re-mocking the
+// module.
+const mockConfig = {
+  // app.title/app.contact match every fixture's appName/appContact below —
+  // render() injects brand.name/brand.contact (falling back to these) as
+  // the legacy appName/appContact keys, so the baseline stays unchanged
+  // with no mailer.brand configured (#4130).
+  app: { title: 'Acme', contact: 'help@example.com' },
+  // Resolves `brand.url` (via getBaseUrl()) to a real link for the
+  // baseline — every template is now a body fragment wrapped in the
+  // default footer, which renders a `brand.url` link when it's truthy.
+  cors: { origin: ['https://acme.test'] },
+  mailer: { templates: {}, brand: {} },
+};
+
 jest.unstable_mockModule('../../../../config/index.js', () => ({
-  default: {
-    // app.title/app.contact match every fixture's appName/appContact below —
-    // render() now injects brand.name/brand.contact (falling back to these)
-    // as the legacy appName/appContact keys, so the baseline snapshot stays
-    // byte-identical with no mailer.brand configured (#4130).
-    app: { title: 'Acme', contact: 'help@example.com' },
-    mailer: { templates: {}, brand: {} },
-  },
+  default: mockConfig,
 }));
 
 const { default: mailer } = await import('../index.js');
@@ -120,9 +135,13 @@ const FIXTURES = {
 
 /**
  * @desc Extract every plain variable a handlebars source references,
- *   including the subject of a `{{#if x}}` / `{{#unless x}}` block.
- *   Skips closers (`{{/if}}`), `{{else}}` and partials (`{{> x}}`) — this
- *   corpus has no `{{#each}}` or triple-stash `{{{x}}}` yet.
+ *   including the subject of a `{{#if x}}` / `{{#unless x}}` block and a
+ *   bare-identifier hash arg on a partial call (e.g. `{{> button url=url
+ *   label="Go"}}` yields `url` — `label` is a quoted string literal, not
+ *   a variable, so it's skipped; needed since #4133's CTA templates
+ *   reference `url` only inside `{{> button}}`, never as a bare `{{url}}`
+ *   any more). Skips closers (`{{/if}}`) and `{{else}}` — this corpus has
+ *   no `{{#each}}` or triple-stash `{{{x}}}` yet.
  * @param {string} source - Raw handlebars template text
  * @returns {Set<string>} Variable names referenced by the template
  */
@@ -131,7 +150,17 @@ const extractVariables = (source) => {
   const vars = new Set();
   for (const raw of tokens) {
     const inner = raw.slice(2, -2).trim();
-    if (inner === 'else' || inner.startsWith('/') || inner.startsWith('!') || inner.startsWith('>')) continue;
+    if (inner === 'else' || inner.startsWith('/') || inner.startsWith('!')) continue;
+    if (inner.startsWith('>')) {
+      const parts = inner.slice(1).trim().match(/[^\s"]+="[^"]*"|\S+/g) || [];
+      for (const part of parts.slice(1)) {
+        const eq = part.indexOf('=');
+        if (eq === -1) continue;
+        const value = part.slice(eq + 1);
+        if (!value.startsWith('"')) vars.add(value);
+      }
+      continue;
+    }
     if (inner.startsWith('#')) {
       const subject = inner.slice(1).trim().split(/\s+/)[1];
       if (subject) vars.add(subject);
@@ -143,17 +172,27 @@ const extractVariables = (source) => {
 };
 
 /**
- * @desc Normalize rendered HTML for snapshot comparison: strip tags,
- *   collapse whitespace. Insensitive to markup changes, sensitive to copy —
- *   #4133 (body-fragment conversion) diffs its output against this.
+ * @desc Normalize rendered HTML for snapshot comparison: drop the
+ *   `<style>` block entirely (its CSS text is shared layout markup, not
+ *   per-template copy, and `<style>` is a raw-text element whose content
+ *   would otherwise survive a plain tag strip), strip the remaining tags,
+ *   collapse whitespace. Insensitive to markup changes, sensitive to copy.
  * @param {string} html
  * @returns {string} Normalized text
  */
-const normalize = (html) => html.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+const normalize = (html) => html
+  .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, ' ')
+  .replace(/<[^>]+>/g, ' ')
+  .replace(/\s+/g, ' ')
+  .trim();
 
 const TEMPLATE_KEYS = Object.keys(FIXTURES);
 
 describe('mailer baseline render — all shared templates:', () => {
+  beforeEach(() => {
+    mockConfig.mailer.brand = {};
+  });
+
   // Subset, not equality: this stack test file ships byte-identical to every
   // downstream via update-stack, and a downstream legitimately has flat
   // templates of its own in config/templates/ (the fallback finds them —
@@ -180,3 +219,31 @@ describe('mailer baseline render — all shared templates:', () => {
     expect(normalize(html)).toMatchSnapshot();
   });
 });
+
+// #4133: every shared template is now a body fragment wrapped in the
+// default layout, so a configured brand (colors + logo) must reach every
+// one of them via the shared header/footer/button partials — not just the
+// 6 that carry a `{{> button}}` CTA. `brand.logoUrl` is rendered by the
+// header partial on every mail; `brand.primaryColor` colors the footer's
+// contact link on every mail (present here on all 15 since the fixture
+// brand sets `contact`) and, additionally, the button background on the
+// 6 CTA mails.
+describe('mailer brand coverage — brand colors and logo reach every shared template (#4133):', () => {
+  const BRAND = {
+    name: 'Acme',
+    contact: 'help@example.com',
+    logoUrl: 'https://acme.test/logo.png',
+    primaryColor: '#112233',
+  };
+
+  beforeEach(() => {
+    mockConfig.mailer.brand = BRAND;
+  });
+
+  test.each(TEMPLATE_KEYS)('%s renders brand.logoUrl and brand.primaryColor from config.mailer.brand', async (key) => {
+    const html = await mailer.render(key, FIXTURES[key]);
+
+    expect(html).toContain(BRAND.logoUrl);
+    expect(html).toContain(BRAND.primaryColor);
+  });
+});

From 8e0b5195b0ac4b414cddf27a2ea428ce33505986 Mon Sep 17 00:00:00 2001
From: Pierre Brisorgueil <pierrebrisorgueil@me.com>
Date: Sun, 4 Oct 2026 01:27:03 +0200
Subject: [PATCH 2/4] chore(templates): explicit beforeEach import +
 MIGRATIONS.md entry for #4133

Import beforeEach from @jest/globals explicitly (sibling test files all
do), and document the downstream-visible behavior change: the 15 shared
mails lose their hardcoded sign-off unless config.mailer.brand.signature
is set, consistent with the #4164-4171 MIGRATIONS.md entries this epic
already added.

Refs #4133
---
 MIGRATIONS.md                                     | 15 +++++++++++++++
 .../mailer/tests/mailer.templates.unit.tests.js   |  2 +-
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/MIGRATIONS.md b/MIGRATIONS.md
index 2c1f8c142..ed9172c08 100644
--- a/MIGRATIONS.md
+++ b/MIGRATIONS.md
@@ -4,6 +4,21 @@ Breaking changes and upgrade notes for downstream projects.
 
 ---
 
+## mailer: the 15 shared `config/templates/*.html` mails are now body fragments on the default layout (2026-10-04)
+
+#4133: `billing-*`, `org-*`, `referral-reward-earned`, `reset-password-*`, `signup-invite`, `verify-email` and `welcome` are no longer full HTML documents — each is now a body fragment rendered inside the default layout (`_layout/layout.html` + its header/footer/button partials, #4132/#4166), the same mechanism #4164–#4171 already added for a downstream's own templates.
+
+- Each template's old hardcoded sign-off ("The `{{appName}}` Team." / "... Support Team.") is gone — replaced by `brand.signature`, which has **no fallback**: unset, none of the 15 sign off any more.
+- Each template's old inline "Please do not reply…" footer is gone, replaced by the shared footer's standardized contact line, which now reaches all 15 (5 of them — the 4 `org-*` mails and `referral-reward-earned` — never rendered a contact line before).
+- The 6 CTA templates render their button via `{{> button url=url label="..."}}` instead of a copy-pasted table.
+- Unchanged: every other variable each template renders, its CTA `url`, its "Button not working?" fallback link, and the three mail-specific caveat sentences (reset-password-email, signup-invite, verify-email).
+
+### Action for downstream
+
+Set `config.mailer.brand.signature` (and `brand.logoUrl`/`brand.primaryColor`/etc., #4165) if you want these mails to keep a sign-off or look branded — nothing renders by default. No other action needed: a downstream's own full-document template (source starting with `<!doctype`/`<html>`) is unaffected, it still bypasses the layout entirely.
+
+---
+
 ## skills: thin service re-export, zero-logic unit-test exception, `create-module` `crud-only` option (2026-10-03)
 
 `.claude/skills/{naming,feature,create-module,verify}/SKILL.md` updated — no runtime code changed:
diff --git a/lib/helpers/mailer/tests/mailer.templates.unit.tests.js b/lib/helpers/mailer/tests/mailer.templates.unit.tests.js
index 190cd9a57..e6507277b 100644
--- a/lib/helpers/mailer/tests/mailer.templates.unit.tests.js
+++ b/lib/helpers/mailer/tests/mailer.templates.unit.tests.js
@@ -11,7 +11,7 @@
  * no `brand.signature` configured) — see the brand-colors test further
  * down for the config-driven replacements (signature, logo, link).
  */
-import { jest, describe, test, expect } from '@jest/globals';
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
 import fs from 'fs';
 import path from 'path';
 

From 63bb398c4bcbaf6f282030417f66c6d8f8fa3919 Mon Sep 17 00:00:00 2001
From: Pierre Brisorgueil <pierrebrisorgueil@me.com>
Date: Sun, 4 Oct 2026 01:46:32 +0200
Subject: [PATCH 3/4] docs(mailer): migration recipe for shared templates
 edited in place

---
 MIGRATIONS.md | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/MIGRATIONS.md b/MIGRATIONS.md
index ed9172c08..0a7f21d75 100644
--- a/MIGRATIONS.md
+++ b/MIGRATIONS.md
@@ -11,12 +11,15 @@ Breaking changes and upgrade notes for downstream projects.
 - Each template's old hardcoded sign-off ("The `{{appName}}` Team." / "... Support Team.") is gone — replaced by `brand.signature`, which has **no fallback**: unset, none of the 15 sign off any more.
 - Each template's old inline "Please do not reply…" footer is gone, replaced by the shared footer's standardized contact line, which now reaches all 15 (5 of them — the 4 `org-*` mails and `referral-reward-earned` — never rendered a contact line before).
 - The 6 CTA templates render their button via `{{> button url=url label="..."}}` instead of a copy-pasted table.
-- Unchanged: every other variable each template renders, its CTA `url`, its "Button not working?" fallback link, and the three mail-specific caveat sentences (reset-password-email, signup-invite, verify-email).
+- `appName`/`appContact` no longer come from a caller-passed param — both are now resolved from the brand (#4177). `appContact` is gone from every body (10 of the 15 used to render it inline, now 0 do; it's footer-only, `brand.contact`). `appName` still renders inline in 14 of the 15 bodies (now brand-sourced, `brand.name`, and also used by the header partial); `reset-password-confirm-email` is the one template with none left — its only use was the removed sign-off. Each template's own `<title>` is gone too — 4 of them (`org-member-added`, `referral-reward-earned`, `signup-invite`, `welcome`) had a non-empty one (the other 11 were empty); the layout now has a single `<title>`, always the mail's `subject`.
+- Unchanged otherwise: every remaining variable each template renders, its CTA `url`, its "Button not working?" fallback link, and the three mail-specific caveat sentences (reset-password-email, signup-invite, verify-email).
 
 ### Action for downstream
 
 Set `config.mailer.brand.signature` (and `brand.logoUrl`/`brand.primaryColor`/etc., #4165) if you want these mails to keep a sign-off or look branded — nothing renders by default. No other action needed: a downstream's own full-document template (source starting with `<!doctype`/`<html>`) is unaffected, it still bypasses the layout entirely.
 
+**If a downstream already edited one of these 15 shared templates in place** (your copy of `config/templates/<name>.html` no longer matches upstream): move your edited copy to `config/templates/<project>/<name>.html`, add one `config.mailer.templates` entry pointing `<name>` at it (`{ templates: { '<name>': 'config/templates/<project>/<name>.html' } }`), then restore the shared file to upstream's version — explicitly (`git checkout devkit-node/master -- config/templates/<name>.html`) before your next `/update-stack`, or let that run's own ISO merge do it (`config/templates/*.html` is ISO-merge scope, same as `modules/`/`lib/`) — in that order, override first, so the ISO merge's overwrite never touches the only copy of your edits. Until that restore happens, your moved copy is still a full HTML document, so it keeps rendering unwrapped (the legacy-full-document path) the whole time — nothing breaks mid-migration, and converting it to a fragment on the shared layout afterward is optional.
+
 ---
 
 ## skills: thin service re-export, zero-logic unit-test exception, `create-module` `crud-only` option (2026-10-03)
@@ -126,11 +129,15 @@ rejected send can never break or delay the signup / OAuth redirect response.
 **What you will see:** every new signup receives a welcome email once the
 mailer is configured. To opt out, set `organizations.welcomeEmail.enabled:
 false` in the project config (default `true`, fail-open — read with `?? true`
-so an absent key never silently disables it). To customize the copy, edit the
-same-named template at `config/templates/welcome.html` (`{{displayName}}`,
-`{{appName}}`, `{{url}}`, `{{appContact}}`, and an optional
-`{{#if orgName}}` block, omitted in B2C mode). No schema change, no migration
-to run.
+so an absent key never silently disables it). To customize the copy, don't
+edit `config/templates/welcome.html` in place — it's a Devkit-owned shared
+template (#4133) and `/update-stack`'s ISO merge will overwrite it. Add a
+`config.mailer.templates` entry instead (`{ templates: { welcome:
+'config/templates/<project>/welcome.html' } }`) pointing at your own copy,
+seeded from the shared one (`{{displayName}}`, `{{appName}}`, `{{url}}`, and
+an optional `{{#if orgName}}` block, omitted in B2C mode — `appContact` is no
+longer a body variable, it's the brand-driven footer's contact line, #4133).
+No schema change, no migration to run.
 
 ## Billing: public plans listing now requires a plan tag (2026-09-25)
 

From 9f4dbeaf56cdfd29b599c7750f71bef3977fe3eb Mon Sep 17 00:00:00 2001
From: Pierre Brisorgueil <pierrebrisorgueil@me.com>
Date: Sun, 4 Oct 2026 02:04:08 +0200
Subject: [PATCH 4/4] test(mailer): assert brand.primaryColor on the CTA button
 background, not only the footer

---
 lib/helpers/mailer/tests/mailer.templates.unit.tests.js | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/lib/helpers/mailer/tests/mailer.templates.unit.tests.js b/lib/helpers/mailer/tests/mailer.templates.unit.tests.js
index e6507277b..7d1d8befb 100644
--- a/lib/helpers/mailer/tests/mailer.templates.unit.tests.js
+++ b/lib/helpers/mailer/tests/mailer.templates.unit.tests.js
@@ -236,6 +236,12 @@ describe('mailer brand coverage — brand colors and logo reach every shared tem
     primaryColor: '#112233',
   };
 
+  // The 6 templates that carry a `{{> button}}` CTA (#4133) — the footer's
+  // contact link alone makes BRAND.primaryColor appear in all 15, so a
+  // generic substring check never proves the color also reaches the button
+  // background; these keys get that extra, button-specific assertion below.
+  const CTA_TEMPLATE_KEYS = new Set(['org-member-added', 'org-request-new', 'reset-password-email', 'signup-invite', 'verify-email', 'welcome']);
+
   beforeEach(() => {
     mockConfig.mailer.brand = BRAND;
   });
@@ -245,5 +251,8 @@ describe('mailer brand coverage — brand colors and logo reach every shared tem
 
     expect(html).toContain(BRAND.logoUrl);
     expect(html).toContain(BRAND.primaryColor);
+    if (CTA_TEMPLATE_KEYS.has(key)) {
+      expect(html).toContain(`<td style="border-radius: 6px; background-color: ${BRAND.primaryColor};">`);
+    }
   });
 });