docs(spec): regenerate the email-template reference page and add the changeset

`gen:docs` projects `EmailTemplateDefinitionSchema.locale`'s describe into
content/docs/references/system/email-template.mdx, so the source correction
without this regeneration would have shipped the old sentence to every reader
of the reference page.

Claude-Session: https://claude.ai/code/session_01KB5PFtxuy1x3dcR5gxudx6
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/18056-email-template-locale-rungs.md

@@ -0,0 +1,46 @@
+---
+'@objectstack/spec': minor
+---
+
+docs(spec): scope the email-template locale-floor claims to a call that NAMES a locale (#18056)
+
+Clause-②: yes — no accept set moves (no key is added, removed or revalidated),
+but what a PUBLISHED package states about its own resolution contract is
+corrected, which is a contract act in substance.
+
+`packages/spec` stated two different rung counts for one resolution.
+`EmailTemplateDefinitionSchema.locale`'s `describe` and the
+`EMAIL_TEMPLATE_FLOOR_LOCALE` docblock published **one** retry rung and an
+explicit "no fallback floor at all"; `SendTemplateInput.locale` in
+`contracts/email-service.ts`, same package, documents a **three-rung** ladder
+whose third rung is reachable exactly on the path the first says cannot exist.
+
+Measured against the runtime rather than reconciled by preference —
+`EmailService.resolveAndRenderTemplate` and `createSysEmailTemplateLoader` in
+`@objectstack/plugin-email`, and the CI pins in
+`template-locale-resolution.test.ts` — the three-rung text is the correct one:
+
+1. the named locale, matched exactly (no language-subtag folding);
+2. the literal `en-US`, which is also where a call naming no locale starts;
+3. **only for a call that named no locale**, and only when the bundle carries
+   no `en-US` row: the bundle's lowest locale tag.
+
+So a bundle with no `en-US` row dead-letters (`TEMPLATE_NOT_FOUND`, permanent)
+for every recipient whose locale was NAMED, and silently renders whichever
+language sorts first for every call that named none. The shipped declaration
+promised the loud permanent refusal on the path where the runtime performs the
+silent fill; an author reading it was told a missing locale always
+dead-letters. Both call shapes are now named wherever the floor is claimed, and
+the ladder itself is stated in one place only.
+
+Also corrected: `SendTemplateInput.template` said the service "picks the
+best-matching locale row", which the resolver has never done — there is no
+best match and no folding, only the ladder above.
+
+`defineStack`'s `warnEmailTemplateLocaleFloor` gains a declaration of the two
+shapes it deliberately does NOT examine (a stack whose `i18n.supportedLocales`
+is absent or empty; a bundle whose tags all fall outside `supportedLocales`) —
+both can still ship a floorless bundle. Its logic is unchanged and its warning
+stays advisory; whether either shape should warn is the ADR-0049
+enforce-or-remove question and is not answered here. Both shapes are now pinned
+against a warning discriminator so neither can change without a test saying so.

content/docs/references/system/email-template.mdx

@@ -44,7 +44,7 @@ const result = EmailTemplateDefinitionSchema.parse(data);
 | **name** | `string` | ✅ | Template identifier (dotted snake_case) |
 | **label** | `string` | ✅ | Display label |
 | **category** | `Enum<'auth' \| 'notification' \| 'workflow' \| 'marketing' \| 'custom'>` | optional (default: `"custom"`) |  |
-| **locale** | `string` | optional (default: `"en-US"`) | BCP-47 locale (e.g. en-US, zh-CN) — the bundle key the resolver matches EXACTLY, with one retry rung: the literal `en-US`. No language-subtag folding, so `en` and `en-US` are different bundles and neither reaches the other. A bundle with no `en-US` row therefore has no fallback floor: any recipient locale it does not carry a row for raises TEMPLATE_NOT_FOUND, which is permanent — the delivery dead-letters with no retry. Your stack's own `i18n.defaultLocale` is the wrong tag here unless it is spelled `en-US`. |
+| **locale** | `string` | optional (default: `"en-US"`) | BCP-47 locale (e.g. en-US, zh-CN) — the bundle key the resolver matches EXACTLY. A call that NAMES a locale gets exactly one retry rung, the literal `en-US`, with no language-subtag folding: `en` and `en-US` are different ROWS of one bundle and neither reaches the other, so a bundle with no `en-US` row has no fallback floor for those calls and every recipient locale it does not carry a row for raises TEMPLATE_NOT_FOUND, which is permanent — the delivery dead-letters with no retry. A call naming NO locale is the other case and does not dead-letter: it drops to the bundle's lowest locale tag and renders that silently. Your stack's own `i18n.defaultLocale` is the wrong tag here unless it is spelled `en-US`. |
 | **subject** | `string` | ✅ | Subject template |
 | **bodyHtml** | `string` | ✅ | HTML body template |
 | **bodyText** | `string` | optional | Plain-text body template (auto-derived from HTML when omitted) |