Update existing cumulative docs contributing guidelines

contribute-docs/_snippets/applies_to-version.md

@@ -1,9 +1,18 @@
 `applies_to` accepts the following version formats:
 
-* `Major.Minor`
-* `Major.Minor.Patch`
+| Format | Syntax | Examples | Badge Display | Description |
+|:-------|:-------|:---------|:--------------|:------------|
+| **Greater than or equal to** (default) | `x.x+`<br>`x.x`<br>`x.x.x+`<br>`x.x.x` | `ga 9.1`<br>`ga 9.1+` | `9.1+` | Applies from this version onwards |
+| **Range** (inclusive) | `x.x-y.y`<br>`x.x.x-y.y.y` | `preview 9.0-9.2` | `9.0-9.2`<br>`9.0+`* | Applies within the specified range |
+| **Exact version** | `=x.x`<br>`=x.x.x` | `beta =9.1` | `9.1` | Applies only to this specific version |
 
-Regardless of the version format used in the source file, the version number is always rendered in the `Major.Minor.Patch` format.
+\* Range display depends on release status of the second version.
+
+**Important notes:**
+
+- Versions are always displayed as **Major.Minor** (for example, `9.1`) in badges, regardless of whether you specify patch versions in the source.
+- Each version statement corresponds to the **latest patch** of the specified minor version (for example, `9.1` represents 9.1.6 if 9.1.6 is the latest patch available for the 9.1 series).
+- When critical patch-level differences exist, use plain text descriptions alongside the badge rather than specifying patch versions.
 
 :::{note}
 **Automatic Version Sorting**: When you specify multiple versions for the same product, the build system automatically sorts them in descending order (highest version first) regardless of the order you write them in the source file. For example, `stack: preview =9.0, ga 9.1-9.7, deprecated =9.8, removed 9.9+` will be displayed as `stack: removed 9.9+, deprecated =9.8, ga 9.1-9.7, preview =9.0`. Items without versions (like `ga` without a version or `all`) are sorted last.

contribute-docs/_snippets/stack-serverless-lifecycle-example.md

@@ -4,7 +4,7 @@ If a change is released in Serverless and will be released in a future version o
 ---
 applies_to:
   serverless: ga
-  stack: ga 9.2
+  stack: ga 9.2+
 ---
 ```
 
@@ -18,4 +18,4 @@ Because these changes need to be published as soon as the feature is released in
 * After the {{stack}} version is released, the same badges will render with the version number without any changes to the badge value in the source.
 
     {applies_to}`serverless: ga`
-    {applies_to}`stack: ga 9.0`
+    {applies_to}`stack: ga 9.2+`

contribute-docs/_snippets/tag-processing.md

@@ -17,9 +17,7 @@ The following table shows how badges for versioned products are displayed based
 | removed     | prerelease     | {applies_to}`stack: removed 99.99`    |
 |             | post-release   | {applies_to}`stack: removed 9.1`      |
 
-This is computed at build time (there is a docs build every 30 minutes). The documentation team tracks and maintains released versions for these products centrally in [`versions.yml`](https://github.com/elastic/docs-builder/blob/main/config/versions.yml).
-
-When multiple lifecycle statuses and versions are specified in the sources, several badges are shown.
+This is computed at build time. The documentation team tracks and maintains released versions for these products centrally in [`versions.yml`](https://github.com/elastic/docs-builder/blob/main/config/versions.yml).
 
 :::{note}
 Visuals and wording in the output documentation are subject to changes and optimizations.

contribute-docs/how-to/cumulative-docs/badge-placement.md

@@ -3,7 +3,7 @@
 :::{note}
 This content is still in development.
 If you have questions about how to write cumulative documentation while contributing,
-reach out to **@elastic/docs** in the related GitHub issue or PR. 
+reach out to **@elastic/docs** in the related GitHub issue or PR.
 :::
 
 As you continue contributing to documentation and more versions are released,
@@ -19,13 +19,12 @@ version and deployment type differences in your docs:
 * **Headings**: Provide signals about a section’s scope so a user can choose to read or skip it as needed.
 * **Lists**: Identify features in a list of features that are exclusive to a specific context, or that were introduced in a specific version or comparing differing requirements, limits, and other simple, mirrored facts.
 * **Definition lists**: Identify settings or options that are exclusive to a specific context, or that were introduced in a specific version.
-* **Tabs**: Provide two sets of procedures when one or more steps in a process differs between contexts or versions.
+* **Tabs**: Provide two sets of procedures when one or more steps in a process differs between contexts. For differences per version or deployment type, you should use [`applies-switch`](https://elastic.github.io/docs-builder/syntax/applies-switch/) instead of a generic [`tab-set`](https://elastic.github.io/docs-builder/syntax/tabs/).
 * **Admonitions**: Draw attention to happy differences and basic clarifications.
 * **Sibling pages**: When the information is too complex to be addressed with only the other content patterns.
 
 ## General placement principles
 
-% Source: Brandon's PR review comment
 At a high level, you should follow these badge placement principles:
 
 * Place badges where they're most visible but least disruptive to reading flow.

contribute-docs/how-to/cumulative-docs/example-scenarios.md

@@ -7,7 +7,7 @@
 :::{note}
 This content is still in development.
 If you have questions about how to write cumulative documentation while contributing,
-reach out to **@elastic/docs** in the related GitHub issue or PR. 
+reach out to **@elastic/docs** in the related GitHub issue or PR.
 :::
 
 Browse common scenarios you might run into as a docs contributor that require different approaches to labeling cumulative docs.
@@ -226,7 +226,7 @@
 
 #### Tables
 
-**Density** {applies_to}`stack: ga 9.1` {applies_to}`serverless: ga`
+**Density** {applies_to}`stack: ga 9.1+` {applies_to}`serverless: ga`
 :   Make the table more or less compact. Choose between **Compact**, **Normal** (default), and **Expanded**.
 ```
 ::::
@@ -278,9 +278,11 @@
 Then, the functionality became generally available in Elastic Stack in 9.1.0 and shortly before the
 Elastic Stack 9.1.0 release in Serverless.
 
-* For Elastic Stack, a versioned product, label the section with both lifecycles: `ga 9.1` and `preview 9.0`.
 * For Serverless, an unversioned product, update the section label from `serverless: preview` to `serverless: ga`.
   Do _not_ list both lifecycles.
+* For Elastic Stack, a versioned product, label the section with both lifecycles: `ga 9.1+` and `preview =9.0`.
+  The latest released version is rendered in the badge and other lifecycle/versions is included in the popover attached to the badge.
+  Hover over the badge to see the popover.
 
 :::::{tab-set}
 ::::{tab-item} Image
@@ -304,7 +306,7 @@
 ### Assign colors to terms [assign-colors-to-terms]
 
 ```{applies_to}
-stack: ga 9.1+, preview =9.0,
+stack: ga 9.1+, preview =9.0
 serverless: ga
 ```
 
@@ -346,7 +348,7 @@
     security: all
 ---
 
-# Configure advanced settings [security-advanced-settings]
+# Configure advanced settings for Elastic Security
 
 [...]
 
@@ -400,25 +402,52 @@
 :screenshot:
 ::::
 
-### Solution B: Use tabs [code-block-tabs]
+### Solution B: Use applies switch tabs [code-block-tabs]
 
-:::{include} _snippets/applies-switch-and-tabs.md
-:::
-
-**When to use tabs**: If using a [code callout](#code-block-callout) isn't appropriate.
+**When to use applies switch tabs**: If using a [code callout](#code-block-callout) isn't appropriate.
 
 **Best practices**:
 
 * Try to minimize the number of tabs where possible,
-  but do not mix tabs and `applies_to`-related code callouts.
+  but do not mix applies switch and `applies_to`-related code callouts.
 * Try not to include information surrounding a code block in the tabs.
   Make the tab content as small as possible apart from the procedure itself.
 
 **Example**: On the [Upstream OpenTelemetry Collectors and language SDKs](https://www.elastic.co/docs/solutions/observability/apm/upstream-opentelemetry-collectors-language-sdks#apm-connect-open-telemetry-collector) page, we use tabs to show two different code blocks: one for Serverless and one for Elastic Stack (stateful).
 
+::::::{tab-set}
+:::::{tab-item} Image
 ::::{image} ./images/example-code-block-tabs.png
 :screenshot:
 ::::
+:::::
+
+:::::{tab-item} Code
+
+````
+Connect your OpenTelemetry Collector instances to Elastic {{observability}}
+or {{obs-serverless}} using the OTLP exporter:
+
+::::{applies-switch}
+:::{applies-item} stack: ga
+
+```
+[...]
+```
+
+:::
+:::{applies-item} serverless: ga
+
+```
+[...]
+```
+
+:::
+::::
+````
+
+:::::
+::::::
 
 ## Workflows vary [workflow]
 
@@ -442,18 +471,30 @@
 
 **Example**: Only one item in an ordered list varies between Serverless and stateful.
 
-::::{image} ./images/workflow-inline.png
+:::::{tab-set}
+
+::::{tab-item} Image
+:::{image} ./images/workflow-inline.png
 :screenshot:
+:::
 ::::
 
-### Solution B: Use tabs [workflow-tabs]
+::::{tab-item} Code
+```md
+1. Get started:
+    * {applies_to}`serverless: ga` In your {{obs-serverless}} project, go to **Add Data**.
+    * {applies_to}`stack: ga` In {{kib}}, go to the **Observability** UI and click **Add Data**.
+1. Under **What do you want to monitor?** select **Host**, and then select **Elastic Agent: Logs & Metrics**.
+1. Copy the install command.
+```
+::::
+:::::
 
-:::{include} _snippets/applies-switch-and-tabs.md
-:::
+### Solution B: Use applies switch tabs [workflow-tabs]
 
-Tabs are minimally disruptive in many situations.
+Applies switch tabs are minimally disruptive in many situations.
 
-**When to use tabs**:
+**When to use applies switch tabs**:
 
 * Using [inline `applies_to` badges](#workflow-inline) isn't appropriate.
 * All the tabs fit horizontally on a single row on a typical laptop screen.
@@ -469,19 +510,51 @@
   Make the tab content as small as possible apart from the procedure itself.
 * Consider breaking up procedures into sets of procedures if only one section differs between contexts.
 
-**Example**: On the [Enable audit logging](https://www.elastic.co/docs/deploy-manage/security/logging-configuration/enabling-audit-logs#enable-audit-logging-procedure) page, we use tabs to show separate ordered lists outlining the workflow for each deployment type.
+**Example**: On the [Enable audit logging](https://www.elastic.co/docs/deploy-manage/security/logging-configuration/enabling-audit-logs#enable-audit-logging-procedure) page, we use applies switch tabs to show separate ordered lists outlining the workflow for each deployment type.
 
+::::::{tab-set}
+
+:::::{tab-item} Image
 ::::{image} ./images/example-workflow-tabs.png
 :screenshot:
 ::::
+:::::
+
+:::::{tab-item} Code
+
+```
+::::{applies-switch}
+
+:::{applies-item} ess: ga
+[...]
+:::
+
+:::{applies-item} eck: ga
+[...]
+:::
+
+:::{applies-item} ece: ga
+[...]
+:::
+
+:::{applies-item} self: ga
+[...]
+:::
+
+::::
+```
+
+:::::
+
+::::::
 
 ### Solution C: Use sibling pages [workflow-sibling-pages]
 
 Sibling pages are a last resort when no other solutions are appropriate.
 
 **When to use sibling pages**:
 
-* Neither [inline `applies_to` badges](#workflow-inline) or [tabs](#workflow-tabs) are appropriate.
+* Neither [inline `applies_to` badges](#workflow-inline) or [applies switch tabs](#workflow-tabs) are appropriate.
 * The workflow has significant differences across multiple procedures.
 * There are chained procedures where not all of the procedures are needed for all contexts
   or where the flow across procedures is muddied when versioning context is added.
@@ -503,12 +576,9 @@
 
 Sometimes the UI differs between versions, deployment types or other conditions.
 
-### Solution A: Use tabs [screenshot-tabs]
-
-:::{include} _snippets/applies-switch-and-tabs.md
-:::
+### Solution A: Use applies switch tabs [screenshot-tabs]
 
-**When to use tabs**:
+**When to use applies switch tabs**:
 * When the screenshot shows significantly different interfaces or workflows for each product, deployment type, or version.
 * When the screenshot represents a specific, interactive action, like clicking a button or navigating a UI that changes meaningfully between contexts.
 
@@ -542,13 +612,10 @@
 
 ## Multiple adjacent block elements vary [multiple-block]
 
-### Solution A: Use tabs [multiple-block-tabs]
+### Solution A: Use applies switch tabs [multiple-block-tabs]
 
-:::{include} _snippets/applies-switch-and-tabs.md
-:::
-
-**When to use tabs**:
+**When to use applies switch tabs**:
 * When the content is structurally similar but differs in detail — for example, slightly different instructions, outputs, or paths.
 * When you want to avoid repeating most of the surrounding content and isolate just the difference.
 
 **Best practices**:
@@ -571,13 +638,12 @@
 
 ## Functionality is added to multiple patch versions [multiple-patch]
 
-Sometimes, features and enhancements slip through into patch versions, and the same functionality might be added for the first time to multiple patch versions at the same time. 
+Sometimes, features and enhancements slip through into patch versions, and the same functionality might be added for the first time to multiple patch versions at the same time.
 
 - **Standard case**: Our docs are aligned with the latest patch of any given minor version. That means that in most cases, we don't need to call out the exact patch version that introduced a change (that's for the release notes).
-
 - **Exceptions**: In rare cases, it can happen that the change is important enough to be explicitly called out in the docs with a precise patch-level information. In that case, you can add a callout and indicate patch-level versions using plain text to explain the change.
 
-For example, on the [HTTP JSON input](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-httpjson) page, the `terminate` helper function was added to a 9.0.x and 9.1.x patch version at the same time.
+For example, on the [HTTP JSON input](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-httpjson) page, the `terminate` helper function was added to a 9.0.x and 9.1.x patch version at the same time. Since the new functionality is available in the latest patch of both 9.0.x and 9.1.x, use the earlier version: 9.0.x.
 
 :::::{tab-set}
 ::::{tab-item} Image