docs: document SMS Contact setup requirement and SMS_PLACEHOLDER_EMAIL constant location

composite-envelope-builder/QUICK_START.md

@@ -235,6 +235,12 @@ All docs are in the `docs/` folder:
 - Replace the loop that sends individual envelopes
 - Add the Apex Action in place of the loop
 
+**SMS Delivery Setup (Flow V4):**
+- Use **Flow V4** (`Docusign_Envelope_Templates_V4`) when recipients may not have an email address
+- The `Docusign_Recipient_1__c` field on the Client Case **must be populated** with a Contact — a null lookup causes the recipient to be omitted from the envelope entirely
+- To trigger SMS delivery: link the Contact to the case but **leave the Contact's Email field blank** — the flow detects this and prompts the operator for a mobile number
+- The placeholder email (`placeholder_email@docusign.com`) substituted by Apex is defined as the constant `SMS_PLACEHOLDER_EMAIL` in `DocusignCompositeEnvelopeBuilder.cls` — **update the constant there** if the address ever needs to change
+
 ---
 
 ## ❓ Need Help?

composite-envelope-builder/docs/api-reference.md

@@ -523,7 +523,34 @@ Rather than calling the Docusign REST API directly for SMS delivery, this projec
 
 This approach requires no additional REST endpoints, no extra authentication, and no HTTP callouts beyond what the toolkit already handles.
 
-### 11.2 `dfsle.Recipient.withSmsDelivery(phone)`
+### 11.2 Salesforce Data Setup Prerequisite
+
+Before SMS delivery can work, the Client Case record must be set up correctly:
+
+| Field | Requirement |
+|-------|-------------|
+| `Docusign_Recipient_1__c` | **Must be populated** — set to a Contact record |
+| Contact `Name` | **Must be populated** — used as the recipient's display name in Docusign |
+| Contact `Email` | **Must be blank** — the flow checks this field to route through the SMS path |
+
+> ⚠️ **Important**: If `Docusign_Recipient_1__c` is null (no Contact linked at all), the Apex code skips that recipient entirely and Docusign Recipient #1 will be missing from the envelope. The Contact must exist — only the email needs to be absent.
+
+### 11.3 Placeholder Email Constant
+
+The Docusign API requires an `email` field on every recipient even when SMS delivery is configured. When the recipient contact has no email address, the Apex layer substitutes a placeholder automatically — **no actual email is sent to this address**.
+
+> 🔧 **Configuration**: The placeholder address is defined as a single constant in `DocusignCompositeEnvelopeBuilder.cls`. **This is the only place that needs to be updated if the placeholder address ever changes.**
+
+```apex
+// ============================================================
+// SMS DELIVERY: Placeholder email used when the primary recipient
+// (Docusign Recipient #1) has no email address and SMS delivery is
+// requested via recipientSmsPhone.  Docusign requires an email on
+// every recipient even when dfsle.Recipient.withSmsDelivery() is used.
+// ============================================================
+@TestVisible
+private static final String SMS_PLACEHOLDER_EMAIL = 'placeholder_email@docusign.com';
+```
 
 **Method signature**:
 ```apex
@@ -542,7 +569,7 @@ dfsle.Recipient withSmsDelivery(String phone)
 - The Docusign API still requires an `email` field on every recipient even when SMS delivery is configured. When the recipient contact has no email address, a placeholder (`placeholder_email@docusign.com`) is substituted automatically by the Apex layer. No actual email is sent to this address.
 - Only applied to **Docusign Recipient #1**. The Service Coordinator always uses email delivery.
 
-### 11.3 Invocable Action Parameter
+### 11.4 Invocable Action Parameter
 
 The `recipientSmsPhone` input parameter on the `Send_Composite_Envelope` Apex action activates SMS delivery:
 
@@ -550,15 +577,17 @@ The `recipientSmsPhone` input parameter on the `Send_Composite_Envelope` Apex ac
 |-----------|------|----------|-------------|
 | `recipientSmsPhone` | `String` | No | Mobile phone number for SMS delivery. When blank (or not provided), the envelope is sent normally by email. E.164 format preferred: `+15551234567`. |
 
-### 11.4 Apex Usage Pattern
+### 11.5 Apex Usage Pattern
 
 ```apex
 // Resolve email from Contact record
 String recipientEmail = contact.Email;
 
-// Substitute placeholder when email is blank and SMS phone is provided
+// Substitute placeholder when email is blank and SMS phone is provided.
+// SMS_PLACEHOLDER_EMAIL is a constant in DocusignCompositeEnvelopeBuilder.cls —
+// update the constant there if the placeholder address ever needs to change.
 if (String.isBlank(recipientEmail) && String.isNotBlank(smsPhone)) {
-    recipientEmail = 'placeholder_email@docusign.com';
+    recipientEmail = SMS_PLACEHOLDER_EMAIL;
 }
 
 // Build recipient using dfsle toolkit
@@ -576,7 +605,7 @@ if (String.isNotBlank(smsPhone)) {
 }
 ```
 
-### 11.5 Flow V4 Integration
+### 11.6 Flow V4 Integration
 
 In `Docusign_Envelope_Templates_V4`, the flow checks the recipient contact's email before presenting the send screen:
 
@@ -598,7 +627,7 @@ In `Docusign_Envelope_Templates_V4`, the flow checks the recipient contact's ema
 ---
 
 **Document Version**: 1.2  
-**Last Updated**: March 13, 2026  
+**Last Updated**: March 15, 2026  
 **Change Log**:
 
 | Version | Date | Summary |
@@ -606,4 +635,5 @@ In `Docusign_Envelope_Templates_V4`, the flow checks the recipient contact's ema
 | 1.0 | 2026-02-23 | Initial release |
 | 1.1 | 2026-03-11 | No changes (version aligned with design/requirements) |
 | 1.2 | 2026-03-13 | Added section 11 — SMS delivery via `dfsle.Recipient.withSmsDelivery()`; documented `recipientSmsPhone` parameter; renumbered Reference Links to section 12 |
+| 1.2 | 2026-03-15 | Added 11.2 Contact setup prerequisite; added 11.3 placeholder email constant callout; renumbered 11.3–11.5 to 11.4–11.6; updated code example to reference `SMS_PLACEHOLDER_EMAIL` constant |
 

composite-envelope-builder/docs/design.md

@@ -2,7 +2,7 @@
 
 **Project**: Salesforce Composite Envelope Builder  
 **Version**: 1.2  
-**Date**: February 23, 2026 (updated March 13, 2026)  
+**Date**: February 23, 2026 (updated March 15, 2026)  
 **Author**: Paul Huliganga
 
 ---
@@ -350,9 +350,21 @@ This feature is surfaced through **Flow V4** (`Docusign_Envelope_Templates_V4`),
 | Phone collection | Screen in flow (not Apex) | Keeps Apex free of UI logic; phone can also be supplied programmatically by bypassing the screen |
 | Recipient scope | Docusign Recipient #1 only | Service Coordinator always has an email; only the primary recipient may lack one |
 
-### Configuration
+### Salesforce Data Setup Requirement
 
-A single constant in `DocusignCompositeEnvelopeBuilder.cls` holds the placeholder email address:
+For SMS delivery to work, the **Docusign Recipient #1 Contact record must exist** on the Client Case — but with **no email address**. This is the trigger that causes the flow to route through the SMS path.
+
+| Requirement | Detail |
+|-------------|--------|
+| `Docusign_Recipient_1__c` on Client Case | **Must be populated** with a Contact record |
+| Contact's `Email` field | **Must be blank** — the flow checks this to decide whether to collect a phone number |
+| Contact's `Name` field | **Must be populated** — Docusign uses this as the recipient's display name in the envelope |
+
+> ⚠️ **Common mistake**: Removing the Contact from `Docusign_Recipient_1__c` entirely (setting it to null) will cause the Apex code to skip that recipient completely — the Docusign Recipient #1 will be missing from the envelope. The Contact must be linked; only the email needs to be absent.
+
+### Configuration: Placeholder Email Constant
+
+A single constant in `DocusignCompositeEnvelopeBuilder.cls` holds the placeholder email address used when the recipient has no real email. **This is the only place that needs to be updated if the placeholder address ever changes.**
 
 ```apex
 // ============================================================

composite-envelope-builder/docs/requirements.md

@@ -2,7 +2,7 @@
 
 **Project**: Salesforce Composite Envelope Builder  
 **Version**: 1.2  
-**Date**: February 23, 2026 (updated March 13, 2026)  
+**Date**: February 23, 2026 (updated March 15, 2026)  
 **Author**: Paul Huliganga
 
 ---
@@ -65,6 +65,8 @@ Replace combination templates with **28 single-form templates** (14 forms × 2 l
 - Upon entering a phone number, the envelope is sent and the recipient receives a Docusign signing invitation via SMS instead of email
 - The Service Coordinator recipient is unaffected and always receives delivery by email
 - A placeholder email address is substituted automatically in the Apex layer so the Docusign API requirement for an email field is satisfied without routing any real email to the recipient
+- The placeholder email is defined as the constant `SMS_PLACEHOLDER_EMAIL` in `DocusignCompositeEnvelopeBuilder.cls` — **this is the single location to update if the placeholder address ever needs to change**
+- **Setup requirement**: The `Docusign_Recipient_1__c` field on the Client Case **must be populated** with a Contact record. The Contact must have a `Name` but **no `Email`** — a null lookup (no Contact at all) will cause the recipient to be omitted from the envelope entirely
 - This functionality is delivered via **Flow V4** (`Docusign_Envelope_Templates_V4`); Flow V3 is unchanged
 
 #### FR-003: Single Envelope Generation