docs: document applies_to authoring for settings YAML

docs/syntax/applies.md

@@ -24,11 +24,14 @@ When documenting a new feature or behavior, answer these two questions:
 | You need to show entirely different content for each variant, not just tag the same content | [Versioned tabs](applies-switch.md) |
 | You're adding a version-specific note, tip, or warning | [Admonition annotation](admonitions.md) |
 | You're adding a version-specific dropdown | [Dropdown annotation](dropdowns.md) |
+| You're tagging a `{settings}` YAML entry | [applies_to in settings YAML](automated_settings.md#settings-yaml) |
 
 ## Syntax reference
 
 The `applies_to` metadata supports an [exhaustive list of keys](#key-value-reference). When you write or edit documentation, only specify the keys that apply to that content.
 
+`{settings}` YAML is an exception. Each setting renders a **Supported on** line, so you list every deployment key. Refer to [applies_to in settings YAML](automated_settings.md#settings-yaml).
+
 Each key accepts values with the following syntax:
 
 ```

docs/syntax/automated_settings.md

@@ -18,7 +18,7 @@ The `{settings}` directive is generic. Although the largest current examples com
 
     Valid values: `ech` (Elastic Cloud Hosted), `ece` (Elastic Cloud Enterprise), `eck` (Elastic Cloud on Kubernetes), `self` (self-managed).
 
-    A setting is considered available for a deployment type if its `applies_to.deployment` block explicitly lists that deployment with a non-removed lifecycle. If a setting has `applies_to` metadata but no entry for the requested deployment, it is treated as unavailable and hidden.
+    A setting is considered available for a deployment type if its `applies_to` metadata lists that deployment with a lifecycle other than `removed` or `unavailable`. Flat keys such as `ech: ga` and a nested `deployment:` map both work. If a setting has `applies_to` metadata but no entry for the requested deployment, it is treated as unavailable and hidden.
 
     Settings with no `applies_to` metadata at all are always shown, regardless of the filter.
 
@@ -54,12 +54,16 @@ groups:
         # id: OPTIONAL
         # applies_to: OPTIONAL docs-builder applicability metadata
         #
-        # Supports docs-builder applies_to syntax, for example:
+        # Same keys as applies.md. The authoring contract is different.
+        # See "applies_to in settings YAML" on this page.
         #
         # applies_to:
         #   stack: ga 9.2
         #   ech: ga
+        #   ece: ga
+        #   eck: ga
         #   self: ga
+        #   serverless: ga
         #
         # note: OPTIONAL
         # tip: OPTIONAL
@@ -73,12 +77,90 @@ groups:
         #     description: OPTIONAL
         # example: OPTIONAL multiline Markdown
         # settings: OPTIONAL nested settings list
-        #   Child settings inherit applies_to from the parent unless overridden.
+        #   Child settings inherit applies_to when they omit the field.
+        #   A child applies_to map replaces the parent. It does not merge keys.
         #   - setting: "[n].url"
         #     description: |
         #       REQUIRED
 ```
 
+### applies_to in settings YAML [settings-yaml]
+
+The keys are the same as [Applies to](applies.md). The authoring contract is different, because each setting renders a **Supported on** line.
+
+In settings YAML, list every deployment key so that line is complete and the `:deployment:` filter is explicit.
+
+| Key | What it means here | Write |
+|---|---|---|
+| `stack` | The setting's lifecycle and versions it's available in | `ga`, `preview 9.2`, or a history such as `preview 9.0-9.2, ga 9.3+`. Omit the version if the setting was added before 9.0. |
+| `ech`, `ece`, `eck`, `self` | Supported on that deployment, or not | Always list all four. `ga` if supported. `unavailable` if not. Never a version. Never `preview`, `experimental`, `deprecated`, or `removed`. |
+| `serverless` | Supported on serverless, or not | Always list it. `ga` if every serverless project supports it. `unavailable` if none do. Never a version. Never `preview`, `experimental`, `deprecated`, or `removed`. If only some projects support it, nest those project keys. |
+
+`ga` on a deployment key is a support flag. It does not mean the setting is generally available. If `stack` is `preview` and the setting exists on Elastic Cloud Hosted, write `ech: ga`.
+
+Some settings exist on only some serverless projects. This is common for Advanced Settings. When that is the case, nest those project keys under `serverless`. The keys are `elasticsearch`, `observability`, `security`, and `vectordb`. Write `ga` on the projects that include the setting. Those keys are support flags. Never write a version. Never write `preview`, `experimental`, `deprecated`, or `removed`. Do not nest `workplace_ai`. That project type never shipped, and docs-builder has no `workplace_ai` key.
+
+Do not mix a scalar `serverless:` with project keys.
+
+Existing settings YAML sometimes lists those project keys as siblings of `stack`. That form still parses. Prefer the nested `serverless:` map for new entries.
+
+`unavailable` is not rendered as a badge. It hides the setting from `:deployment:`. Omitting a deployment key also hides it from that filter. Still write `unavailable` so the Supported on line is complete.
+
+Child settings inherit the parent's `applies_to` when they omit the field. If a child sets `applies_to`, that map replaces the parent. It does not merge keys.
+
+To scope a `note`, `tip`, `warning`, or `important` to a version or deployment, put `:applies_to:` on the first line of that field. docs-builder wraps the field in an admonition. Do not add a `:::{note}` wrapper.
+
+Preferred map (supported everywhere):
+
+```yaml
+applies_to:
+  stack: ga 9.2
+  ech: ga
+  ece: ga
+  eck: ga
+  self: ga
+  serverless: ga
+```
+
+Technical preview that is still supported on every deployment:
+
+```yaml
+applies_to:
+  stack: preview 9.2
+  ech: ga
+  ece: ga
+  eck: ga
+  self: ga
+  serverless: ga
+```
+
+Self-managed only:
+
+```yaml
+applies_to:
+  stack: ga 9.2
+  ech: unavailable
+  ece: unavailable
+  eck: unavailable
+  self: ga
+  serverless: unavailable
+```
+
+Observability serverless only:
+
+```yaml
+applies_to:
+  stack: ga 9.2
+  ech: ga
+  ece: ga
+  eck: ga
+  self: ga
+  serverless:
+    observability: ga
+```
+
+The same nested shape works for `elasticsearch`, `security`, and `vectordb`.
+
 ### Example
 
 See `/syntax/settings-with-applies-example.yml` for a full, schema-compliant sample.
@@ -89,8 +171,10 @@ It demonstrates:
 - Setting `id`, `datatype`, `default`, and `options`.
 - `note`, `tip`, `warning`, `important`, and `deprecation_details`.
 - Nested `settings`.
-- `applies_to` inheritance and override behavior.
-- Inline `{applies_to}` badges inside a setting `description` (for example, to label per-version defaults in a bulleted list).
+- A complete `applies_to` map, including `unavailable` keys and `stack: preview` with `ech: ga`.
+- `applies_to` inheritance when a child omits the field, and replacement when it sets its own map.
+- Inline `{applies_to}` badges inside a setting `description` for version-scoped behavior that is not the `default` field.
+- A gated `note` for a previous default, and a gated `warning` with `:applies_to:` on the first line.
 - Top-level `page_description`.
 
 ### Result

docs/syntax/settings-with-applies-example.yml

@@ -23,8 +23,12 @@ groups:
         datatype: bool
         default: "true"
         applies_to:
-          stack: ga 9.2
+          stack: preview 9.2
           ech: ga
+          ece: ga
+          eck: ga
+          self: ga
+          serverless: ga
         options:
           - option: "true"
             description: Turns the feature on.
@@ -40,13 +44,20 @@ groups:
         datatype: enum
         default: strict
         applies_to:
-          stack: ga 9.2
+          stack: ga 9.1
+          ech: ga
+          ece: ga
+          eck: ga
+          self: ga
+          serverless: ga
         options:
           - option: strict
             description: Full validation.
           - option: lenient
             description: Reduced validation.
-        warning: Lenient mode may hide configuration mistakes.
+        warning: |
+          :applies_to: stack: ga 9.2
+          Lenient mode may hide configuration mistakes.
         important: Strict mode is recommended for production.
         deprecation_details: The `lenient` option will be deprecated in a future release.
         example: |
@@ -57,11 +68,21 @@ groups:
       - setting: xpack.example.defaultModel
         id: xpack-example-default-model
         description: |
-          Default model used by the feature. The default varies by version:
+          Default model used by the feature.
 
-          * {applies_to}`stack: ga 9.2` Defaults to `model-v2`.
-          * {applies_to}`stack: ga 9.1` Defaults to `model-v1`.
+          {applies_to}`stack: ga 9.2` The model picker is also available in Discover.
         datatype: string
+        default: model-v2
+        applies_to:
+          stack: ga 9.1
+          ech: ga
+          ece: ga
+          eck: ga
+          self: ga
+          serverless: ga
+        note: |
+          :applies_to: stack: ga =9.1
+          In this version, this setting defaults to `model-v1`.
 
   - group: Advanced settings
     id: advanced-settings
@@ -76,7 +97,11 @@ groups:
         default: "[]"
         applies_to:
           stack: ga 9.2
+          ech: unavailable
+          ece: unavailable
+          eck: unavailable
           self: ga
+          serverless: unavailable
         settings:
           - setting: "[n].url"
             id: xpack-example-hosts-url
@@ -87,7 +112,7 @@ groups:
           - setting: "[n].mode"
             id: xpack-example-hosts-mode
             description: |
-              Child setting overrides applies_to.
+              Child setting replaces the parent applies_to map.
             datatype: enum
             default: strict
             tip: Keep all host modes aligned to simplify troubleshooting and reduce drift.
@@ -98,6 +123,11 @@ groups:
                 description: Allows lenient checks.
             applies_to:
               stack: preview 9.3
+              ech: unavailable
+              ece: unavailable
+              eck: unavailable
+              self: ga
+              serverless: unavailable
             example: |
               ```yaml
               xpack.example.hosts: