docs(auth): state what the SMS invite rung yields today, and give its pins their own #14641 describe

Two wording items from the Clause-2 contract review, which passed. No
behaviour, assertion or fixture changes.

1. The changeset claimed an imported phone-only account's `locale` wins on the
   SMS invite path. Re-measured: `admin-import-users.ts` contains 0
   occurrences of `locale` (positive control: `sendInviteSms` twice in the
   same file) and `sys_user.locale` declares no column default (positive
   control: `defaultValue` appears 15 times elsewhere in that object). So on
   the only in-repo caller the row exists but its column is empty at send
   time, and that flow still resolves to the deployment default — the
   pre-change behaviour. The rung is wired and answers for an out-of-repo
   caller or a future import that populates the column; a changeset becomes
   release notes, so it now says exactly that. The same overstatement is
   corrected in the three code comments carrying it (`sendPhoneInviteSms`,
   `setDefaultSmsLocale`, `phone-sms-texts.ts`).

2. The five SMS invitation pins were nested inside `describe('#14762 ...')`,
   so their reporter path credited the wrong card. They now sit in their own
   sibling describe naming #14641. Move only — no re-indentation, and no
   `expect`/`await`/`const` line in the diff.

`content/docs/**` deliberately untouched: the review found the shipped
sentence literally accurate as written.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

Author: claude

.changeset/invitation-invitee-stored-locale.md

@@ -16,11 +16,13 @@ That reason covers only one of the two populations an invitation reaches. This
 change gives both invitation sends the same top rung the other four already
 read, on a **two-branch** shape:
 
-1. the address (or phone number) **already carries** a `sys_user` row — an
-   existing platform user invited into a second organization, a re-invitation,
-   or an imported phone-only account — the row's `locale` wins;
+1. the address (or phone number) **already carries** a `sys_user` row whose
+   `locale` is set — an existing platform user invited into a second
+   organization, or a re-invitation — that row's `locale` wins;
 2. a genuinely **new** invitee with **no** row keeps the deployment default,
-   because their language is still truly unknown at invitation time.
+   because their language is still truly unknown at invitation time. So does an
+   invitee whose row exists but names no language: an unset column is not a
+   choice.
 
 ⛔ The inviter direction stays rejected on both branches, and is now pinned
 against a manager that has the top rung wired rather than against one with no
@@ -33,10 +35,20 @@ inviter's header.
 address that is already a member of *this* organization
 (`USER_IS_ALREADY_A_MEMBER_OF_THIS_ORGANIZATION`, `routes/crud-invites.mjs` in
 the installed 1.7.2), so an existing account invited elsewhere — and the
-`resend` branch — reach the callback normally. `sendPhoneInviteSms` is the
-branch-1 case in its purest form: its one in-repo caller, the identity import
-endpoint's `invite` policy, **creates** the account and only then sends the SMS,
-so the row exists before the send does.
+`resend` branch — reach the callback normally. `sendPhoneInviteSms` reaches a row by
+construction: its one in-repo caller, the identity import endpoint's `invite`
+policy, **creates** the account and only then sends the SMS.
+
+⚠️ **What the SMS path yields today, stated precisely, because a changeset
+becomes release notes.** The rung is wired there and reads the row whenever the
+row carries a locale — but `admin-import-users.ts` never writes `locale` (0
+occurrences; positive control: `sendInviteSms` appears twice in the same file),
+and `sys_user.locale` declares no column default. So on the only in-repo caller
+the column is empty at send time and the invitation SMS still resolves to the
+**deployment default** — the pre-change behaviour, unchanged for that flow. What
+this buys on that surface is the rung itself: an out-of-repo caller, or a future
+import that populates `locale`, is read rather than ignored. The behaviour users
+see change today is on the invitation **email**.
 
 **Matching is exact, and that is safe rather than merely tolerable here.**
 better-auth lowercases the invitee address on the invite route and the stored

packages/plugins/plugin-auth/src/auth-manager.test.ts

@@ -2631,14 +2631,21 @@ describe('AuthManager', () => {
         expect(sms.sent[0].body).toContain('验证码');
         expect(sms.sent[0].body).toContain('555555');
       });
+    });
 
-      // ── #14641 — the SMS INVITE path's two branches ───────────────────
-      //
+    // ── #14641 — the SMS INVITE path gets the same rung ──────────────────
+    //
+    // Its OWN describe, sibling to #14762 above rather than nested inside it:
+    // the reporter path is what the next reader greps, and these pins answer
+    // for #14641, not for the card that gave the OTP send its rung.
+    describe("#14641 — the invitation SMS reads the invitee's own locale", () => {
       // Was a scope fence ("untouched — its rung is #14641's") until #14641
-      // landed. This is the branch-1 case in its purest form: the one in-repo
-      // caller (the identity import endpoint's `invite` policy) CREATES the
-      // account and only then sends this SMS, so the row exists before the
-      // send does — the existing-row branch is not a hypothetical here.
+      // landed. The existing-row branch is reachable by construction: the one
+      // in-repo caller (the identity import endpoint's `invite` policy) CREATES
+      // the account before sending. ⚠️ It does NOT populate `locale`, and the
+      // column has no default, so that caller still lands on the deployment
+      // rung today — these pins drive the engine directly, which is what lets
+      // them measure the rung the in-repo flow does not yet exercise.
       //
       // ⚠️ The two built-in invite bodies genuinely differ, so each assertion
       // names one locale in BOTH directions: the marker for the locale that

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -4805,13 +4805,20 @@ export class AuthManager {
     // templates that still interpolate `{{baseUrl}}`.
     //
     // #14641 — the invitee's OWN stored language, on the same two branches the
-    // invitation EMAIL takes. This surface is the branch-1 case in its purest
-    // form: the doc comment above is not describing a possibility but the
-    // invariant of the one in-repo caller — the identity import endpoint
-    // CREATES the account and only then sends this SMS, so the row exists
-    // before the send does. A number that resolves no row (a caller outside
-    // that flow) keeps the deployment default. Matched exactly on
+    // invitation EMAIL takes. A number that resolves no row, or a row naming no
+    // language, keeps the deployment default. Matched exactly on
     // `phone_number`, the same predicate {@link deliverPhoneOtp} matches on.
+    //
+    // ⚠️ What this yields TODAY, so the next reader does not over-read it: the
+    // one in-repo caller (the identity import endpoint's `invite` policy)
+    // CREATES the account before sending, so a ROW is always there — but
+    // `admin-import-users.ts` never writes `locale` and the column declares no
+    // default, so the value is empty at send time and this path still resolves
+    // to the deployment default, exactly as it did before #14641. The rung is
+    // wired, not yet exercised in-repo: it answers for an out-of-repo caller,
+    // or for a future import that populates the column. ⛔ Do not read this
+    // site as a behaviour change users see today — that one is on the
+    // invitation EMAIL, whose invitee may already hold a locale-bearing row.
     const storedLocale = await this.storedRecipientLocale({ phone_number: phone });
     const body = await this.renderPhoneSmsBody(
       PHONE_SMS_TOPICS.invite,
@@ -4850,9 +4857,9 @@ export class AuthManager {
    * reads the recipient's own `sys_user.locale` first (#13881, ruling
    * 2026-09-01, the same column the messaging channels resolve per recipient)
    * and falls here when the account holds none. #14641 gave the SMS INVITE
-   * path the same rung — matched on `phone_number`, and for the one in-repo
-   * caller (identity import) the row always exists, since the account is
-   * created before the invitation SMS is sent. This rung answers when the
+   * path the same rung, matched on `phone_number` — though the one in-repo
+   * caller (identity import) creates a row that never carries a `locale`, so
+   * that flow still lands HERE in practice. This rung answers when the
    * number resolves no row, or the row names no language.
    */
   setDefaultSmsLocale(locale: string | undefined): void {

packages/plugins/plugin-auth/src/phone-sms-texts.ts

@@ -22,11 +22,13 @@
  * send-OTP callbacks `{ phoneNumber, code }` and nothing else, so the ruled
  * chain (#14788 option D, 2026-09-03) collapses to stored → deployment here.
  *
- * #14641 gave the SMS **invite** path the same two rungs. Its recipient is
- * matched on `phone_number`, and for the one in-repo caller — the identity
- * import endpoint's `invite` policy — the account is CREATED before the SMS is
- * sent, so the row is there to read. A number that resolves no row keeps the
- * deployment default.
+ * #14641 gave the SMS **invite** path the same two rungs, matched on
+ * `phone_number`. A number that resolves no row — or a row naming no language
+ * — keeps the deployment default. ⚠️ That is what the one in-repo caller gets
+ * today: the identity import endpoint creates the account before sending, so a
+ * ROW is always there, but it never writes `locale` and the column has no
+ * default, so that flow still resolves to the deployment rung. The rung is
+ * wired for an out-of-repo caller, or a future import that populates it.
  *
  * Whatever arrives, {@link phoneSmsLocaleChain}'s terminal `en` remains the
  * floor: this module never returns nothing, and an OTP never fails to render.