vdev example-config generator emits invalid configs for mutually-exclusive-but-optional fields

Summary

The example-config generator emits a value for every field that has docs::examples metadata. It has no notion of "at most one of these fields", so for fields that are mutually exclusive but not required, it generates an example config that violates the component's own validation. The only existing mechanism, required_one_of, means "exactly one must be set" (it emits a JSON-Schema oneOf constraint and a docs note "Exactly one of X or Y must be set"). That is semantically wrong for fields where neither being set is valid.

Impact

• check-generated-docs (which validates every generated example with vector validate --no-environment) fails on any sink whose mutually-exclusive fields both have examples.
• Surfaced concretely by the axiom sink in #26171: url and region are mutually exclusive but neither is required. The auto-generated advanced.yaml set both, failing validation.
  • Workaround: url's docs::examples were removed so the generator only emits region. This keeps the example valid but degrades the docs: the url field no longer shows example values.

Proposed fix

1. Deprecate the top-level flattened fields in favor of a non-flattened enum. The axiom sink's url/region are currently flattened into AxiomConfig as top-level fields. Deprecate them and introduce a single non-flattened endpoint field that is an enum (e.g. endpoint: { type: url, url: ... } | endpoint: { type: region, region: ... }). Mutual exclusivity becomes structural — an enum can only be one variant — so the example generator produces valid configs naturally, and the "at most one" problem disappears for this sink.

2. If the above is not possible/feasible/doesn't make sense for all sinks: Add "at most one" support to the example generator (docs-only metadata, e.g. docs::exclusive / mutually_exclusive, distinct from required_one_of's "exactly one" semantics) so generated examples stay valid during the deprecation period and for any future mutually-exclusive-but-optional fields. The generator emits only one member of the group (reusing the existing group-selection logic in make_example_params), with no JSON-Schema oneOf constraint and no "exactly one required" docs note.

3. After the deprecation window, remove the old top-level fields and the generator workaround, restoring full example values on the enum variants.

Start with the example-config generator and its make_example_params group-selection logic; reproduce the failure through check-generated-docs or vector validate --no-environment using the axiom advanced.yaml case. Compare required_one_of with the desired optional-exclusivity semantics and assess the proposed endpoint/deprecation path. Done means generated examples validate while retaining endpoint examples.