@@ -0,0 +1,15 @@
+---
+'@objectstack/formula': minor
+---
+
+feat(formula): a mail template hole may name the `option` formatter, `{{ stage | option:opportunity.stage }}`, which prints a select value as its option's label from the table the mail renderer hands in
+
+Clause-②: yes (widening)
+Metadata-protocol: added
+Skills-docs: follow-up #30731 — `skills/objectstack-automation/SKILL.md` (the `notify` section) gains one line: an option label in a notice is written with the mail formatter `{{ stage | option:opportunity.stage }}`, not with `label()` in `templateData`. The skills lane owns that file.
+
+- **`option` is a mail template's formatter.** `judgeHoleFormatter(…, 'mail')`, `parseMailHole` and `judgeMailHoleGrammar` accept `option:object.field`, and `parseMailHole` returns the reference as `optionField: { object, field }`. `MAIL_TEMPLATE_FORMATTERS` (new) is the mail list, `TEMPLATE_FORMATTERS` then `option`, and the mail refusals list it as the known formatters. `OPTION_ARGUMENT_RULE` (new) is the one sentence the spec, the renderer and the authoring rule quote; `optionFieldReference` (new) parses the argument.
+- **The argument is a bare `object.field`.** No argument, an empty one, a field with no object (`option:stage`), a quoted reference (`option:'opportunity.stage'`), a marked path (`option:@stage_ref`) and a second dot are refused (`option-field-shape`), naming the hole, the argument and the rule.
+- **The object and field are judged when the caller hands in the app's objects.** `judgeMailHoleGrammar(face, { objects })` takes each object's name to its fields, each `true` when the field declares options, each `null` for an object that resolves with its fields not in hand (whose field is then not judged), and refuses an object it does not name (`option-object-unknown`), a field that object does not have (`option-field-unknown`) and a field with no options (`option-field-no-options`). A name it does not carry that has a platform prefix (`sys_`, `cloud_`, `ai_`) is rung ④ of the object-reference ladder, neither refused nor judged, since a package outside the app may register it; `optionObjectUnregisteredPlatform` (new) answers which references those are, for a caller that advises on them. `judgeMailHoleGrammar(face, { objects, liveUniverse: true })` says the objects are the deployment's whole served universe (the publish door, the renderer at send): there rung ④ does not apply and such a name is refused (`option-object-unknown`). `packageScope: { packageId }` says those objects are narrowed to a written package's closure (implying `liveUniverse`): a name they do not carry is refused as outside that closure (`option-object-outside-closure`), naming the remedy, a dependency declared in the package's manifest.
+- **The formatter prints from the table it is handed.** `formatValue('option', value, 'opportunity.stage', { optionLabels })` takes `optionLabels` (`OptionLabelTable`, new): for each `object.field`, each option's label keyed by its stored value, in the locale the face renders in. A value the table does not hold prints as stored, and a multi-select value labels each element joined with `, `. With no table for that `object.field` the call throws a `RangeError` carrying `optionTableRefusal`'s sentence (new export, the `currencyDefaultRefusal` shape, so a renderer can ask it before it formats): the stored value is never printed where a label was promised. This package reads no metadata and no translations: the mail renderer builds the table per recipient.
+- **In-app template text refuses it.** `TEMPLATE_FORMATTERS` is unchanged, and the in-app dialect (flow notice `title` / `message`, action and bulk-action copy) refuses `option` as a formatter it does not know (`known-formatter`), saying it formats only in a mail template.
@@ -0,0 +1,11 @@
+---
+'@objectstack/lint': minor
+---
+
+feat(lint): `email-template-hole-grammar` accepts an `option` hole whose `object.field` names a field with options, and refuses one that names an object, field or option list the app does not have
+
+Clause-②: yes (widening)
+Metadata-protocol: added
+Skills-docs: follow-up #30731 — `skills/objectstack-automation/SKILL.md` (the `notify` section) gains one line: an option label in a notice is written with the mail formatter `{{ stage | option:opportunity.stage }}`, not with `label()` in `templateData`. The skills lane owns that file.
+
+`os validate`, `os build`, `os lint` and the metadata publish door judge each `{{ value | option:object.field }}` hole of a template's three faces against the object-reference ladder: the stack's own objects as the registry serves them (`objectExtensions` fields folded in, the injected system columns beside the declared fields; at the publish door, the live object universe the gate carries), then the objects another entry of the artifact's `packages[]` provides. A platform-provided object the stack does not carry (`option:sys_user.status`) resolves, and its field is left to the publish door and the send. A name none of these carries that has a platform prefix (`sys_`, `cloud_`, `ai_`) is the ladder's rung ④: a package outside the app may register it, so at `os validate`, `os build` and `os lint` the hole is advised at `warning` under the same rule id (`EmailTemplateHoleGrammarFinding.severity` widens to `'error' | 'warning'`), its field unjudged. The publish door judges against the live object universe alone, the whole of what resolves, so there a name it does not carry is refused whatever its prefix (the reading `list-view-object-unknown` gives a list view's binding); A write into a package is judged against the live universe narrowed to that package's closure, and an object outside it is refused with the closure verdict and the declare-the-dependency remedy (the reading `list-view-object-outside-closure` gives), not as an unknown object. `validateEmailTemplateHoleGrammar(stack, { liveUniverse, packageScope })` takes the switches; `EmailTemplateHoleGrammarOptions` is exported beside `EmailTemplateHoleGrammarFinding`. A select field with inline `options` or a `picklist` name is accepted. An object that resolves to none of these, a field that object does not have and a field that declares no options are each refused at `error` under the existing rule id, naming the hole and what to fix, and so is an argument that is not a bare `object.field`. The finding's hint quotes `OPTION_ARGUMENT_RULE`. A misspelled formatter's refusal now lists `option` among the known mail formatters.
@@ -0,0 +1,13 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec): the email template hole grammar names the `option` formatter, which prints a select value as its option's label in the recipient's language
+
+Clause-②: yes (widening)
+Metadata-protocol: added
+Skills-docs: follow-up #30731 — `skills/objectstack-automation/SKILL.md` (the `notify` section) gains one line: an option label in a notice is written with the mail formatter `{{ stage | option:opportunity.stage }}`, not with `label()` in `templateData`. The skills lane owns that file.
+
+The `subject`, `bodyHtml` and `bodyText` descriptions of `email_template` state the hole grammar. They now carry one more sentence, `OPTION_ARGUMENT_RULE` from `@objectstack/formula` word for word: an `option` hole, in a mail template only, prints the label of the select option whose value it holds, in the recipient's language. Its argument is the object and field the value belongs to, written bare as `object.field` (`{{ stage | option:opportunity.stage }}`); the object is one the app has, the field one of its fields that declares options; a multi-select value prints the label of each of its values, joined with `, `, and a value outside the field's options prints as stored.
+
+A flow notice is filled once per run and sent to each recipient in their own locale, so a select field's value reached the template as stored (`needs_analysis`), and a template could not print its label: `{{ stage | label }}` was refused as an unknown formatter, and CEL `label()` in `templateData` has no option labels to read. Additive only: every template that was accepted before is accepted unchanged.
@@ -96,7 +96,7 @@ in that shape.
 **The formatter is one the whitelist names.** `{{ amount | curency:EUR }}` is
 refused by `os validate`, `os build`, `os lint` and the metadata publish door
 (`email-template-hole-grammar`, a `422 INVALID_METADATA` at the publish door),
-naming the hole and listing the known formatters (`TEMPLATE_FORMATTERS`,
+naming the hole and listing the known formatters (`MAIL_TEMPLATE_FORMATTERS`,
 exported from `@objectstack/formula`). A template stored before this rule fails its render with
 `TEMPLATE_INVALID` and sends nothing, rather than print the raw value (`1234.5`)
 where a formatted one was meant; republish it with the name corrected.
@@ -150,6 +150,41 @@ sent: the amount is never formatted in US dollars or any other guess. Set the
 organization's default currency, or name the currency in the hole: a literal
 code (`currency:EUR`) or a marked path to it (`currency:@currency_code`).
 
+**`option` prints a select value as its option's label.** A flow notice is
+filled once per run and then sent to each recipient in their own locale, so a
+select field's value reaches the template as it is stored (`needs_analysis`).
+`option` names the object and field the value belongs to, written bare as
+`object.field`, and the hole prints that option's label in the recipient's
+language:
+
+```ts
+subject: 'Deal stalled at {{ stage | option:opportunity.stage }}',
+```
+
+The renderer builds the label table for each `object.field` the template names,
+in the locale it renders that recipient's copy in. A multi-select value prints
+the label of each of its values, joined with `, `, and a value that is not one
+of the field's options prints as stored. A render that reaches an `option` hole
+with no label table for its field is refused and nothing is sent: the stored
+value is never printed where the label was promised. `os validate`, `os build`,
+`os lint` and the metadata publish door refuse an `option` hole whose object
+resolves to nothing (the app's own objects, those another package of the same
+artifact provides, and the platform's objects all resolve), whose field that
+object does not have, or whose field declares no options (`email-template-hole-grammar`, a `422 INVALID_METADATA` at the publish
+door), and an argument that is not a bare `object.field`: a quoted one
+(`option:'opportunity.stage'`), a field with no object (`option:stage`) or a
+marked path (`option:@stage_ref`). An object none of those carries whose name
+has a platform prefix (`sys_`, `cloud_`, `ai_`) gets a warning at `os validate`,
+`os build` and `os lint`, its field not judged, because a package outside the
+app may register it; the publish door judges against every object the
+deployment serves and refuses it there if none of them is that object. A
+template saved into a package is judged against that package's closure (its
+own objects, the objects of the packages its manifest declares in
+`dependencies`, and platform objects): an object outside it is refused, and the
+fix is to declare the dependency. `option` belongs to mail templates: in-app
+template text (flow notifications, action and bulk-action copy) refuses it as a
+formatter it does not know.
+
 **Where a hole may sit in `bodyHtml`.** The renderer's escaping is right for
 element text and for a quoted attribute value that holds plain text, so those
 are the supported placements for `{{path}}`. A hole anywhere else — inside a
 
@@ -49,9 +49,9 @@ const result = EmailTemplateDefinitionSchema.parse(data);
 | **label** | `string` | ✅ | Display label |
 | **category** | `never` | optional | [REMOVED] `email_template.category` was removed in @objectstack/spec 18 (ADR-0049 enforce-or-remove) — nothing read it: the Studio listing never offered the filter facet it promised, and delivery never depended on it. Delete the key. A template is found by its `name`, so group templates with a dotted namespace prefix instead (`auth.password_reset`, `crm.welcome`). Run `os migrate meta --from 17` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand. |
 | **locale** | `string` | optional (default: `"en-US"`) | BCP-47 locale (e.g. en-US, zh-CN) — the bundle key. Each rung of the resolver reads one row at one tag exactly, so `en` and `en-US` are different ROWS of one bundle. A call that NAMES a locale, over the built-in template loader, folds it against the bundle's tags (exact, case-insensitive, platform locale table language, base language, then variant expansion: `en-GB` reaches `en`, `zh-TW` reaches `zh-Hant`, else `zh-CN`), then folds the stack's declared fallback locale (`i18n.fallbackLocale`, else `defaultLocale`) the same way, then tries the literal `en-US`; a replacement template loader matches the tag exactly and retries only `en-US`. `en-US` is the floor every loader honours: when no rung lands on a row the call raises TEMPLATE_NOT_FOUND, which is permanent — the delivery dead-letters with no retry. A call naming NO locale folds nothing and does not dead-letter: it starts at `en-US` and otherwise drops to the bundle's lowest locale tag and renders that silently. Tag the English row `en-US` so every loader has the floor. |
-| **subject** | `string` | ✅ | Subject template. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over the send's `data`, with at most one formatter per hole (a second, chained formatter is refused). A formatter is one word, optionally followed by `:` and its argument (text that is not, such as `date-long`, is refused), and it is one the template engine knows (an unknown name, such as a misspelled `curency`, is refused, naming the known formatters). A `currency` argument is either a literal ISO 4217 code in three capital letters (`currency:EUR`) or, in a mail template only, `@` followed by a path into the send's data whose value is such a code (`currency:@currency_code`). |
-| **bodyHtml** | `string` | ✅ | HTML body template. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over the send's `data`, with at most one formatter per hole (a second, chained formatter is refused). A formatter is one word, optionally followed by `:` and its argument (text that is not, such as `date-long`, is refused), and it is one the template engine knows (an unknown name, such as a misspelled `curency`, is refused, naming the known formatters). A `currency` argument is either a literal ISO 4217 code in three capital letters (`currency:EUR`) or, in a mail template only, `@` followed by a path into the send's data whose value is such a code (`currency:@currency_code`). |
-| **bodyText** | `string` | optional | Plain-text body template (auto-derived from HTML when omitted). Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over the send's `data`, with at most one formatter per hole (a second, chained formatter is refused). A formatter is one word, optionally followed by `:` and its argument (text that is not, such as `date-long`, is refused), and it is one the template engine knows (an unknown name, such as a misspelled `curency`, is refused, naming the known formatters). A `currency` argument is either a literal ISO 4217 code in three capital letters (`currency:EUR`) or, in a mail template only, `@` followed by a path into the send's data whose value is such a code (`currency:@currency_code`). |
+| **subject** | `string` | ✅ | Subject template. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over the send's `data`, with at most one formatter per hole (a second, chained formatter is refused). A formatter is one word, optionally followed by `:` and its argument (text that is not, such as `date-long`, is refused), and it is one the template engine knows (an unknown name, such as a misspelled `curency`, is refused, naming the known formatters). A `currency` argument is either a literal ISO 4217 code in three capital letters (`currency:EUR`) or, in a mail template only, `@` followed by a path into the send's data whose value is such a code (`currency:@currency_code`). An `option` hole, in a mail template only, prints the label of the select option whose value it holds, in the recipient's language, and its argument names the object and the field the value belongs to, written bare as `object.field` (`{{ stage \| option:opportunity.stage }}`): the object is one the app has and the field one of its fields that declares options. A multi-select value prints the label of each of its values, joined with `, `, and a value outside the field's options prints as stored. |
+| **bodyHtml** | `string` | ✅ | HTML body template. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over the send's `data`, with at most one formatter per hole (a second, chained formatter is refused). A formatter is one word, optionally followed by `:` and its argument (text that is not, such as `date-long`, is refused), and it is one the template engine knows (an unknown name, such as a misspelled `curency`, is refused, naming the known formatters). A `currency` argument is either a literal ISO 4217 code in three capital letters (`currency:EUR`) or, in a mail template only, `@` followed by a path into the send's data whose value is such a code (`currency:@currency_code`). An `option` hole, in a mail template only, prints the label of the select option whose value it holds, in the recipient's language, and its argument names the object and the field the value belongs to, written bare as `object.field` (`{{ stage \| option:opportunity.stage }}`): the object is one the app has and the field one of its fields that declares options. A multi-select value prints the label of each of its values, joined with `, `, and a value outside the field's options prints as stored. |
+| **bodyText** | `string` | optional | Plain-text body template (auto-derived from HTML when omitted). Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over the send's `data`, with at most one formatter per hole (a second, chained formatter is refused). A formatter is one word, optionally followed by `:` and its argument (text that is not, such as `date-long`, is refused), and it is one the template engine knows (an unknown name, such as a misspelled `curency`, is refused, naming the known formatters). A `currency` argument is either a literal ISO 4217 code in three capital letters (`currency:EUR`) or, in a mail template only, `@` followed by a path into the send's data whose value is such a code (`currency:@currency_code`). An `option` hole, in a mail template only, prints the label of the select option whose value it holds, in the recipient's language, and its argument names the object and the field the value belongs to, written bare as `object.field` (`{{ stage \| option:opportunity.stage }}`): the object is one the app has and the field one of its fields that declares options. A multi-select value prints the label of each of its values, joined with `, `, and a value outside the field's options prints as stored. |
 | **variables** | `{ name: string; type?: Enum<'string' \| 'number' \| 'boolean' \| 'date' \| 'url' \| 'user' \| 'record'>; required?: boolean; description?: string }[]` | optional (default: `[]`) |  |
 | **fromOverride** | `{ name?: string; address: string }` | optional |  |
 | **replyTo** | `string` | optional |  |