[M7] Decide Capabilities API version semantics against Helm upstream

[GaTTGeng]

Background

A parity review against Helm upstream main (543b94d) found that HelmSharp's .Capabilities behavior is useful but not logically identical to Helm upstream.

Helm upstream builds capabilities from pkg/chart/common/capabilities.go and action discovery:

• DefaultCapabilities derives KubeVersion from the Kubernetes client-go module version, or stable test defaults.
• DefaultVersionSet is generated from the registered Kubernetes scheme plus CRD API groups.
• Configuration.getCapabilities() uses live cluster discovery when available and appends custom --api-versions for client-side template rendering.
• --kube-version overrides the reported KubeVersion but does not by itself prune API versions by Kubernetes removal history.

HelmSharp currently uses a hand-maintained API catalog and filters removed API versions by the requested KubeVersion. That can be desirable for offline target-version rendering, but it is not Helm's exact logic path.

Scope

Decide and document the intended HelmSharp semantics for .Capabilities:

• Exact Helm-compatible mode: mirror Helm default capabilities and custom apiVersions behavior as closely as possible.
• Target Kubernetes mode: keep version-aware pruning as an explicit HelmSharp extension.
• Cluster-aware mode: when a Kubernetes client is available, discover API versions from the cluster instead of relying only on static data.

Questions to answer

• Should KubeVersion = null match Helm's default KubeVersion, or keep HelmSharp's broader backward-compatible API set?
• Should specifying KubeVersion affect .Capabilities.APIVersions, or only .Capabilities.KubeVersion as in Helm template dry-run behavior?
• Should user-provided ApiVersions append to defaults, replace defaults, or support both?
• How should HelmSharp expose a compatibility mode without breaking existing consumers?

Suggested tests

• Compare .Capabilities.KubeVersion.{Version,Major,Minor} with Helm for default rendering and explicit kube version.
• Compare .Capabilities.APIVersions.Has for built-in APIs under default rendering.
• Verify custom API versions append/override according to the chosen mode.
• Add docs covering any HelmSharp-specific target-version behavior.

Acceptance criteria

• The chosen behavior is documented as either Helm-compatible or intentionally extended.
• Tests cover default, explicit kube version, and custom API versions.
• Any behavioral change is isolated behind options if it would break existing callers.
• Static API catalog maintenance requirements are documented if target-version pruning remains supported.