[finding] The auth EMAIL locale ladder is undocumented on every shipped page, while the auth SMS ladder is documented in full

[os-sales]

Surfaced by the docs sweep on #14641 (PR #15119), which corrected the one shipped sentence that card falsified. Recording the asymmetry the sweep exposed rather than widening that PR's scope.

Observation

content/docs/permissions/authentication.mdx documents the auth SMS locale ladder in full, under its own heading (SMS text customisation & localisation): which topics are templated, that sys_notification_template rows win, that the recipient's own sys_user.locale is read and matched on phone_number, that the deployment default (localization.locale) stands underneath, and the zh-CN then zh then en fallback chain.

The auth EMAIL ladder has no equivalent anywhere in content/docs/**, despite now being the deeper of the two:

1. the recipient's own sys_user.locale ([Decision] Per-user notification locale —— 2026-08-13 裁决所等的「实测拉力」已到(hotcrm:4 个已发布语言 × 16 个 notify 节点 × 0 可本地化) #13881 / plugin-auth: auth SMS (OTP / invite texts) and request-less auth mail keep the deployment locale — sys_user.locale exists now and is not read #14762, and finding(plugin-auth): 邀请邮件的语言仍取部署默认——等用户级语言列落地后给邀请单独一梯级（#14319 裁 A-now/C-later 的追踪） #14641 for invitations),
2. the request's Accept-Language, narrowed to AUTH_EMAIL_TEMPLATE_LOCALES (auth 邮件（验证/重置）不按用户语言选模板：中文界面注册收到英文主题与正文 #14319),
3. the deployment default, itself with two producers (fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591).

So an operator can discover why their auth SMS arrived in a given language and cannot discover the same for auth mail — including the rule that decides whether a workspace's invitations arrive in the invitee's language.

Measurement

Swept on origin/main at the time of PR #15119, with a positive control so the zero is a reading rather than a broken search:

• POSITIVE CONTROL: invitation is live in the corpus - 16 occurrences in authentication.mdx alone, hits across 10 pages under content/docs/**.
• ZERO: no page pairs an invitation or auth-email locale rule with Accept-Language, sys_user.locale or a deployment default. The only content/docs hits for those terms are the SMS paragraph above, the notification/messaging pages (automation/email-templates.mdx, references/automation/io-node-config.mdx), and the general i18n pages, none of which describe the auth mail send path.

Why this is a finding and not part of #14641

Nothing shipped is FALSE - the pages are silent, not wrong, so no guardrail fires and no gate can see it. The absence predates #14641: it has been there since #8195 gave the sends a locale at all, and neither #14319 nor #14762 added a page. Documenting a three-rung ladder for the whole auth mail surface is a docs unit of work in its own right, not a rider on a card whose diff is one rung on one send.

Suggested shape

A sibling subsection under the same authentication.mdx heading that already carries the SMS ladder, so the two read together and the invitation's two branches (an address that already holds a sys_user row uses that row's locale; a genuinely new invitee takes the deployment default) are stated once, next to the SMS rule they now match.

⚠️ Deliberately filed UNASSIGNED and without pm:queue - observation class, for triage to rank.

Back-link: #14641 · PR #15119

Generated by Claude Code