@@ -2,19 +2,18 @@
 "@objectstack/spec": minor
 ---
 
-feat(spec): the stack definition admits `appName` and the non-secret members of `email` and `sms`; their credentials are refused by name
+feat(spec): the stack definition admits `appName`, the non-secret members of `email`, and `sms.retries`; credentials and the SMS provider are refused by name
 
-Clause-②: yes (widening: the stack definition admits `appName` and the non-secret members of `email` and `sms`, which it refused as unrecognized keys)
+Clause-②: yes (widening: the stack definition admits `appName`, the non-secret members of `email`, and `sms` carrying `retries` alone, which it refused as unrecognized keys)
 
-- **What you can write now.** `defineStack()` accepts three top-level keys it used to refuse as unrecognized. The mail and SMS readers already read all three, and `objectstack serve` and `bootStack` construct the email and SMS providers through those readers:
+- **What you can write now.** `defineStack()` accepts three top-level keys it used to refuse as unrecognized. The mail and SMS readers already read them, and `objectstack serve` and `bootStack` construct the email and SMS providers through those readers:
   - `appName`: the deployment's product name. It is the last configured rung of the name chain (`OS_APP_NAME` > `email.appName` > `email.defaultTemplateContext.appName` > `appName` > `'ObjectStack'`), and it reaches the email templates and AuthPlugin.
-  - `email` (`StackEmailConfigSchema`): every member of `EmailServiceConfigSchema` except `apiKey`. That is `provider`, `defaultFrom`, `retries`, `persist`, `queueDelivery`, `appName` and `defaultTemplateContext`, plus `options` narrowed to `host` / `port` / `secure` / `user` / `messageStream`.
-  - `sms` (`StackSmsConfigSchema`): `provider` (`SmsProviderSchema`: `log` / `aliyun` / `twilio`) and `retries`.
-  - `OS_EMAIL_*` and `OS_SMS_PROVIDER` still override the file per key.
-- **What stays in the environment, and is refused by name.** A stack definition is compiled into the published artifact, so it does not carry credentials. Each refusal names the key and the variable that replaces it:
-  - `email.apiKey` and `email.options.apiKey`: set `OS_EMAIL_API_KEY`.
-  - `email.options.password`: set `OS_EMAIL_SMTP_PASSWORD`. The reader layers it over the host / port / secure / user the file carries.
-  - `sms.providerOptions`: configure the provider in Setup → Settings → SMS Delivery, or through that namespace's overrides (`OS_SMS_PROVIDER`, `OS_SMS_TWILIO_*`, `OS_SMS_ALIYUN_*`). It is refused whole, because every non-`log` SMS transport needs a credential inside it and nothing merges an environment credential into it.
+  - `email` (`StackEmailConfigSchema`): every member of `EmailServiceConfigSchema` except `apiKey`. That is `provider`, `defaultFrom`, `retries`, `persist`, `queueDelivery`, `appName` and `defaultTemplateContext`, plus `options` narrowed to `host` / `port` / `secure` / `user` / `messageStream`. `OS_EMAIL_*` still overrides it per key.
+  - `sms` (`StackSmsConfigSchema`): `retries`, the SMS service's attempt budget. It applies to whichever transport the `sms` settings namespace selects.
+- **What stays elsewhere, and is refused by name.** Each refusal names the key and the setting that replaces it:
+  - `email.apiKey` and `email.options.apiKey`: a credential, and a stack definition is compiled into the published artifact. Set `OS_EMAIL_API_KEY`.
+  - `email.options.password`: a credential. Set `OS_EMAIL_SMTP_PASSWORD`; the reader layers it over the host / port / secure / user the file carries.
+  - `sms.provider`, `sms.providerOptions` (and a flat `authToken` / `accessKeySecret`): the delivering SMS transport is built by the `sms` settings namespace from its own provider and credentials, never from a stack definition. Configure them in Setup → Settings → SMS Delivery, or through that namespace's overrides (`OS_SMS_PROVIDER`, `OS_SMS_TWILIO_*`, `OS_SMS_ALIYUN_*`).
 - **Composition.** All three keys compose as single values. `composeStacks` passes an identical value through and refuses two different ones by key.
-- **Nothing to migrate.** No stack that was accepted before is refused now. A configuration that set these keys only in an object `defineStack` did not build (the one `objectstack serve` boots) reads the same as before. To build it, move any credential it carries into the environment.
-- New exports from `@objectstack/spec/system`: `StackEmailConfigSchema`, `StackEmailProviderOptionsSchema`, `StackSmsConfigSchema`, `SmsProviderSchema`, and their `z.input` / `z.infer` types.
+- **Nothing to migrate.** No stack that was accepted before is refused now. A configuration that set these keys only in an object `defineStack` did not build (the one `objectstack serve` boots) reads the same as before. To build it, move any credential, and the SMS provider, into the environment or Settings.
+- New exports from `@objectstack/spec/system`: `StackEmailConfigSchema`, `StackEmailProviderOptionsSchema`, `StackSmsConfigSchema`, and their `z.input` / `z.infer` types.
@@ -1,7 +1,7 @@
 ---
 title: Protocol reference — every schema by module
 navTitle: Protocol Reference
-description: Every schema published by @objectstack/spec — 1521 schemas across 14 protocol modules
+description: Every schema published by @objectstack/spec — 1520 schemas across 14 protocol modules
 ---
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
@@ -32,9 +32,9 @@ counts are sums of the rows they head. Regenerate with
 | [Security Protocol](/docs/references/security) | 5 | 30 | Permission sets, row-level security, sharing rules, tenancy posture. |
 | [Shared Protocol](/docs/references/shared) | 10 | 31 | Primitives used across every protocol — identifiers, HTTP, expressions, error maps, enums. |
 | [Studio Protocol](/docs/references/studio) | 3 | 35 | Studio designer metadata — the authoring surfaces for the protocols above. |
-| [System Protocol](/docs/references/system) | 35 | 279 | The runtime environment — logging, jobs, cache, metrics, notifications, i18n and compliance. |
+| [System Protocol](/docs/references/system) | 35 | 278 | The runtime environment — logging, jobs, cache, metrics, notifications, i18n and compliance. |
 | [UI Protocol](/docs/references/ui) | 16 | 166 | Apps, pages, views, dashboards, reports, actions and themes — the ObjectUI layer. |
-| **Total** | **196** | **1521** | 14 protocol modules |
+| **Total** | **196** | **1520** | 14 protocol modules |
 
 ---
 
@@ -317,7 +317,7 @@ Studio designer metadata — the authoring surfaces for the protocols above.
 
 ## System Protocol
 
-**Source:** `packages/spec/src/system/` · **Import:** `@objectstack/spec/system` · **35 pages, 279 schemas**
+**Source:** `packages/spec/src/system/` · **Import:** `@objectstack/spec/system` · **35 pages, 278 schemas**
 
 The runtime environment — logging, jobs, cache, metrics, notifications, i18n and compliance.
 
@@ -351,7 +351,7 @@ The runtime environment — logging, jobs, cache, metrics, notifications, i18n a
 | [`security-context.zod.ts`](/docs/references/system/security-context) | `ComplianceAuditRequirement`, `ComplianceEncryptionRequirement`, `ComplianceFramework`, `DataClassification`, `DataClassificationPolicy`, `MaskingVisibilityRule`, `SecurityContextConfig`, `SecurityEventCorrelation` |
 | [`settings-client.zod.ts`](/docs/references/system/settings-client) | `SettingsChangeEvent` |
 | [`settings-manifest.zod.ts`](/docs/references/system/settings-manifest) | `ResolvedSettingValue`, `SettingsActionResult`, `SettingsManifest`, `SettingsNamespacePayload`, `Specifier`, `SpecifierHandler`, `SpecifierOption`, `SpecifierScope`, `SpecifierType`, `SpecifierValueDomain` |
-| [`sms-config.zod.ts`](/docs/references/system/sms-config) | `SmsProvider`, `StackSmsConfig` |
+| [`sms-config.zod.ts`](/docs/references/system/sms-config) | `StackSmsConfig` |
 | [`stack-server.zod.ts`](/docs/references/system/stack-server) | `ServerRateLimitConfig`, `StackServerConfig`, `StackServerSecurity` |
 | [`supplier-security.zod.ts`](/docs/references/system/supplier-security) | `SupplierAssessmentStatus`, `SupplierRiskLevel`, `SupplierSecurityAssessment`, `SupplierSecurityPolicy`, `SupplierSecurityRequirement` |
 | [`tenant.zod.ts`](/docs/references/system/tenant) | `DatabaseLevelIsolationStrategy`, `DatabaseProvider`, `QuotaEnforcementResult`, `RowLevelIsolationStrategy`, `SchemaLevelIsolationStrategy`, `Tenant`, `TenantConnectionConfig`, `TenantIsolationConfig`, `TenantIsolationLevel`, `TenantQuota`, `TenantSecurityPolicy`, `TenantUsage` |
 
@@ -12,29 +12,47 @@ There was no SMS configuration schema in the spec before this file. The
 shape below is typed from what its one reader reads:
 `resolveSmsCapabilityArg` in `@objectstack/service-sms`, which
 `objectstack serve` and `bootStack` both construct `SmsServicePlugin`
-through. It reads three keys off `config.sms`:
-
-| key | secret? | here |
-|---|---|---|
-| `provider` | no — a transport tag | admitted (`SmsProviderSchema`); `OS_SMS_PROVIDER` wins |
-| `retries` | no | admitted |
-| `providerOptions` | YES — every non-`log` transport requires a credential inside it (Twilio `authToken`, Aliyun `accessKeySecret`) | refused by name |
-
-`providerOptions` is refused WHOLE rather than narrowed to its non-secret
+through. It reads three keys off `config.sms`, and only one of them can do
+from a stack definition what it says:
+
+| key | secret? | delivered from a stack? | here |
+|---|---|---|---|
+| `retries` | no | yes | admitted |
+| `provider` | no — a transport tag | NO, measured | refused by name |
+| `providerOptions` | YES — every non-`log` transport requires a credential inside it (Twilio `authToken`, Aliyun `accessKeySecret`) | — | refused by name |
+
+**`retries`** is the SMS service's own attempt budget. The service keeps it
+when the `sms` settings namespace swaps its transport at `kernel:ready`
+(`setTransport` replaces the transport and nothing else), so it applies to
+whichever transport ends up delivering. It has no environment or settings
+carrier, so this block is its only authoring door.
+
+**`provider`** cannot select a delivering transport from here. A stack is
+not allowed credentials (below), so the transport the plugin constructs from
+this tag falls back to its log transport, and the transport that DOES
+deliver is the one the settings namespace builds at `kernel:ready` from its
+own `provider` setting — it never reads this one. Measured through
+`bootStack`: `sms: { provider: 'twilio' }` with the Twilio credentials in the
+environment boots with `isConfigured() === false`; adding `OS_SMS_PROVIDER`
+makes it `true`. A declared key the runtime does not honour is refused rather
+than admitted, with the setting that does work as its prescription. It comes
+back, with a provider vocabulary, in the change that makes `SmsServicePlugin`
+honour it.
+
+**`providerOptions`** is refused WHOLE rather than narrowed to its non-secret
 members, and the difference from mail's `options` is measured, not a
 preference. The mail reader layers `OS_EMAIL_SMTP_*` over `config.email.options`
 per key, so a file carrying host and user composes with an environment
 carrying the password. The SMS reader hands `providerOptions` to the
 transport as written, and nothing merges an environment credential into it:
 a Twilio or Aliyun transport built from the non-secret members alone cannot
-be constructed, so the plugin falls back to its log transport. A narrowed
-`providerOptions` would therefore be a declared key no deployment could ever
-deliver through. SMS provider settings — credentials included — live in the
-`sms` settings namespace (Setup → Settings → SMS Delivery), whose every key
-accepts its `OS_SMS_*` environment override, and the refusal says so.
+be constructed, so the plugin falls back to its log transport.
 
 Why the credentials stop at this door at all: the stack definition is what
 `objectstack build` compiles into the artifact, and artifacts are published.
+SMS provider settings — the provider and its credentials — live in the `sms`
+settings namespace (Setup → Settings → SMS Delivery), whose every key
+accepts its `OS_SMS_*` environment override; every refusal here says so.
 
 <Callout type="info">
 **Source:** `packages/spec/src/system/sms-config.zod.ts`
@@ -43,24 +61,13 @@ Why the credentials stop at this door at all: the stack definition is what
 ## TypeScript Usage
 
 ```typescript
-import { SmsProviderSchema, StackSmsConfigSchema } from '@objectstack/spec/system';
-import type { SmsProvider, StackSmsConfig } from '@objectstack/spec/system';
+import { StackSmsConfigSchema } from '@objectstack/spec/system';
+import type { StackSmsConfig } from '@objectstack/spec/system';
 
 // Validate data
-const result = SmsProviderSchema.parse(data);
+const result = StackSmsConfigSchema.parse(data);
 ```
 
----
-
-## SmsProvider
-
-### Allowed Values
-
-* `log`
-* `aliyun`
-* `twilio`
-
-
 ---
 
 ## StackSmsConfig
@@ -69,8 +76,7 @@ const result = SmsProviderSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **provider** | `Enum<'log' \| 'aliyun' \| 'twilio'>` | optional | SMS transport tag (OS_SMS_PROVIDER env wins). Default log. Credentials never come from the stack: the delivering aliyun / twilio transport is built at kernel:ready from the sms settings namespace (Setup → Settings → SMS Delivery, or its OS_SMS_* env overrides), whose own provider setting decides |
-| **retries** | `integer` | optional | Retry attempts on transport throw (default 0) |
+| **retries** | `integer` | optional | Retry attempts on transport throw (default 0); applies to whichever transport the sms settings namespace selects. The provider and its credentials are not authorable here: Setup → Settings → SMS Delivery, or OS_SMS_PROVIDER and the other OS_SMS_* overrides |
 
 
 ---
 
@@ -1,8 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 //
 // A `defineStack`-built `email` / `sms` / `appName` reaches the providers
-// `objectstack serve` constructs — and the SMS provider vocabulary the stack
-// declares is the one the transports can build.
+// `objectstack serve` constructs.
 //
 // The stack definition used to refuse all three keys while the mail and SMS
 // readers read them, so the configuration arm of both readers was reachable
@@ -17,23 +16,16 @@
 // pinned by the source scan in `serve-auth-app-name.contract.test.ts`; the two
 // files together are the reading from authored stack to constructed provider.
 //
-// The second half is a CROSS-PACKAGE vocabulary assertion, for the reason
-// `@objectstack/plugin-email`'s `spec-provider-parity.contract.test.ts` gives
-// for mail: `SmsProviderSchema` (the authoring contract) and
-// `SMS_TRANSPORT_PROVIDERS` (the array `makeSmsTransport` switches on) are two
-// literals describing one vocabulary, and two literals left alone drift. It
-// lives here because this package depends on both `@objectstack/spec` and
-// `@objectstack/service-sms`; the SMS package's own tests read no spec value.
-// This package's `tsconfig.json` includes `src`, tests and all, so the
-// compile-time half below is real.
+// `sms` carries `retries` alone: the stack refuses `sms.provider` by name,
+// because the delivering SMS transport is built by the `sms` settings
+// namespace from its own provider setting (`OS_SMS_PROVIDER`), so the provider
+// below always comes from the environment.
 
 import { describe, it, expect } from 'vitest';
 import { resolveCapabilityArgument } from '@objectstack/core';
 import { defineStack } from '@objectstack/spec';
-import { SmsProviderSchema, type SmsProvider } from '@objectstack/spec/system';
 import * as pluginEmail from '@objectstack/plugin-email';
 import * as serviceSms from '@objectstack/service-sms';
-import { SMS_TRANSPORT_PROVIDERS, type SmsProviderTag } from '@objectstack/service-sms';
 
 const manifest = {
   id: 'com.example.mailer',
@@ -79,17 +71,17 @@ describe('a defineStack-built email / sms / appName reaches the providers serve
     expect(pluginEmail.resolveDeploymentAppName(stack.email ?? {}, {}, stack.appName)).toBe('Acme');
   });
 
-  it('sms { provider, retries } reaches the SMS provider', () => {
-    const stack = defineStack({ manifest, sms: { provider: 'twilio', retries: 3 } });
-    expect(argumentFor('sms', stack, {})).toEqual({ provider: 'twilio', retries: 3 });
+  it('sms { retries } reaches the SMS provider, beside the provider OS_SMS_PROVIDER names', () => {
+    const stack = defineStack({ manifest, sms: { retries: 3 } });
+    expect(argumentFor('sms', stack, {})).toEqual({ provider: 'log', retries: 3 });
+    expect(argumentFor('sms', stack, { OS_SMS_PROVIDER: 'twilio' })).toEqual({ provider: 'twilio', retries: 3 });
   });
 
-  it('OS_EMAIL_* / OS_SMS_PROVIDER still override the stack per key', () => {
-    const stack = defineStack({ manifest, email: { provider: 'log', retries: 1 }, sms: { provider: 'log' } });
+  it('OS_EMAIL_* still override the stack per key', () => {
+    const stack = defineStack({ manifest, email: { provider: 'log', retries: 1 } });
     const email = argumentFor('email', stack, { OS_EMAIL_PROVIDER: 'smtp', OS_EMAIL_SMTP_HOST: 'relay.example', OS_EMAIL_RETRIES: '4' });
     expect(email.provider).toBe('smtp');
     expect(email.retries).toBe(4);
-    expect(argumentFor('sms', stack, { OS_SMS_PROVIDER: 'aliyun' }).provider).toBe('aliyun');
   });
 
   it('CONTROL — env-only configuration is unchanged: a stack with no block builds what the reader builds from no config', () => {
@@ -110,24 +102,3 @@ describe('a defineStack-built email / sms / appName reaches the providers serve
     expect(argumentFor('sms', stack, env)).toEqual({ provider: 'aliyun' });
   });
 });
-
-/**
- * Compile-time halves of the vocabulary invariant: each union must be
- * assignable to the other, so a member added on one side only makes `true`
- * unassignable — a type error in this package's `typecheck`.
- */
-type SpecAssignableToTransport = SmsProvider extends SmsProviderTag ? true : never;
-type TransportAssignableToSpec = SmsProviderTag extends SmsProvider ? true : never;
-const MUTUALLY_ASSIGNABLE: [SpecAssignableToTransport, TransportAssignableToSpec] = [true, true];
-
-describe('SmsProviderSchema ↔ SMS_TRANSPORT_PROVIDERS', () => {
-  it('declares exactly the providers the SMS transports can build, both directions', () => {
-    expect(MUTUALLY_ASSIGNABLE).toEqual([true, true]);
-    const declared = [...SmsProviderSchema.options].sort();
-    const buildable = [...SMS_TRANSPORT_PROVIDERS].sort();
-    expect(declared.filter((p) => !buildable.includes(p as SmsProviderTag))).toEqual([]);
-    expect(buildable.filter((p) => !declared.includes(p))).toEqual([]);
-    // Anti-vacuity: two empty lists would agree.
-    expect(buildable.length).toBeGreaterThan(1);
-  });
-});
@@ -615,8 +615,6 @@
     "SettingsUnsubscribe (type)",
     "Sha256Digest (type)",
     "Sha256DigestSchema (const)",
-    "SmsProvider (type)",
-    "SmsProviderSchema (const)",
     "SocialProviderConfig (type)",
     "SocialProviderConfigParsed (type)",
     "SocialProviderConfigSchema (const)",
 
@@ -1125,7 +1125,6 @@
     "system/StackServerConfig:security",
     "system/StackServerConfig:trustProxy",
     "system/StackServerSecurity:rateLimit",
-    "system/StackSmsConfig:provider",
     "system/StackSmsConfig:retries",
     "system/StorageConnection:accessKeyId",
     "system/StorageConnection:accountKey",
 
@@ -398,8 +398,6 @@
     "SettingsNamespacePayloadSchema": "system/SettingsNamespacePayload",
     "Sha256Digest": "system/Sha256Digest",
     "Sha256DigestSchema": "system/Sha256Digest",
-    "SmsProvider": "system/SmsProvider",
-    "SmsProviderSchema": "system/SmsProvider",
     "SocialProviderConfig": "system/SocialProviderConfig",
     "SocialProviderConfigSchema": "system/SocialProviderConfig",
     "Span": "system/Span",