Clarify phone type validation limitations and international support

- Added Important Limitation section explaining that valid only checks area code/exchange
- Clarified that the line portion (last 4 digits) is not verified for connectivity
- Recommended third-party services (Trestle, Telesign, BriteVerify) for deliverability
- Corrected international number handling - they return valid: false, not parsed
- Added "What It Does NOT Verify" section listing connectivity limitations
- Updated geographic limitation to be clearer about international numbers

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: alexkwolfe

Reference.md

@@ -547,7 +547,24 @@ Parses numeric values from strings, handling currency symbols and thousands sepa
 
 ### Phone Type
 
-Comprehensive phone number parsing for US/Canada numbers with component extraction.
+Comprehensive phone number parsing and validation for US/Canada numbers with real-world verification.
+
+**Geographic Limitation**: Currently only supports US and Canadian phone numbers. International numbers from other countries will be marked as invalid (valid: false) and will not parse correctly, even if they have a valid format in their home country.
+
+**Advanced Validation**: The `valid` property indicates more than just format correctness - it verifies:
+- The area code is a real, assigned area code
+- The exchange is a real exchange within that area code
+- The area code and exchange legitimately belong together
+- The number follows valid North American Numbering Plan rules
+
+This means a phone number like "(999) 555-1234" would be invalid even though the format is correct, because 999 is not a real area code.
+
+**What It Does NOT Verify**: The validation does NOT check if:
+- The complete 10-digit number is actually connected/in service
+- The line (last 4 digits) is valid for that area code and exchange
+- The number can receive calls or texts
+
+A number can pass type validation but still be disconnected or undeliverable.
 
 **Components:**
 - Raw: Unmodified value
@@ -572,11 +589,15 @@ Comprehensive phone number parsing for US/Canada numbers with component extracti
 
 **Examples:**
 ```
-US Standard:
+Valid US Numbers (real area codes and exchanges):
 "(512) 789-1111" → area: "512", exchange: "789", line: "1111"
 "512-789-1111" → "5127891111"
 "512.789.1111" → "5127891111"
 
+Invalid Despite Good Format (fake area code):
+"(999) 555-1234" → valid: false (999 not a real area code)
+"(123) 456-7890" → valid: false (123 not a real area code)
+
 With Extensions:
 "5127891111x123" → extension: "123"
 "5127891111 x 43" → extension: "43"
@@ -593,12 +614,17 @@ Masked Numbers:
 "1-(512) *** ****" → valid: true (masked)
 "**********" → valid: true (fully masked)
 
-International:
-"+49 30 22610" → country_code: "DE" (Germany)
-"+44 1484 519892" → country_code: "GB" (UK)
+International (will NOT parse correctly):
+"+49 30 22610" → valid: false (not US/Canadian format)
+"+44 1484 519892" → valid: false (not US/Canadian format)
+Note: International numbers are not supported unless they coincidentally match US/Canadian patterns
 ```
 
-**Invalid inputs** (valid=false): `"donkey kong"`, `"964523331"` (too short)
+**Invalid inputs** (valid=false): 
+- `"donkey kong"` (not a number)
+- `"964523331"` (too short)
+- `"(999) 555-1234"` (invalid area code)
+- `"(512) 999-1111"` (invalid exchange for 512 area code)
 
 **Field Examples:** Phone 1, Phone 2, Mobile Phone, Work Phone
 
@@ -608,6 +634,8 @@ International:
 - Format for display: `{{Phone 1 > Area}}-{{Phone 1 > Exchange}}-{{Phone 1 > Line}}`
 - Check validity: `Phone 1 > Valid is true`
 
+**Important Limitation**: The `valid` property only confirms the area code and exchange are legitimate - it does NOT verify the full number is connected or deliverable. The "line" portion (last 4 digits) could still be invalid or disconnected. For true deliverability verification, use third-party Add-On services like Trestle, Telesign, or BriteVerify in a flow step to collect carrier-level metadata, then evaluate the appended data in a subsequent filter step to block disconnected numbers.
+
 ---
 
 ### Postal Code Type
@@ -1138,6 +1166,9 @@ This ensures sensitive data can be used for processing (validation, delivery to
 - Normalizes to lowercase
 
 **Phone**:
+- Validates actual area codes and exchanges (not just format)
+- Verifies area code/exchange combinations are real
+- Only supports US/Canadian numbers currently
 - Supports type hints (h=home, w=work, m=mobile)
 - Detects toll-free numbers
 - Handles extensions