rmcdaniel · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026
diff --git a/docs/compatibility.md b/docs/compatibility.md
@@ -218,13 +218,16 @@ and image digests used for each completed check.
 | Component | Supported version | Install identity |
 |-----------|-------------------|------------------|
 | Server | `%%artifact.serverVersion%%` | `%%artifact.serverDockerHubImage%%` |
+| Helm chart | `%%artifact.helmChartVersion%%` | `%%artifact.helmChartInstallIdentity%%` |
 | CLI | `%%artifact.cliVersion%%` | `%%artifact.cliInstallerEnv%%` |
 | Workflow engine | `%%artifact.workflowVersion%%` | `%%artifact.workflowComposerPackage%%` |
 | Waterline operator | `%%artifact.waterlineVersion%%` | `%%artifact.waterlineComposerPackage%%` |
 | PHP SDK | `%%artifact.phpSdkVersion%%` | `%%artifact.phpSdkComposerPackage%%` |
 | Python SDK | `%%artifact.pythonSdkVersion%%` | `%%artifact.pythonPackagePin%%` |
 | Rust SDK | `%%artifact.rustSdkVersion%%` | `%%artifact.rustCargoRequirement%%` |
 
+The Helm chart's recorded `appVersion` is `%%artifact.helmChartAppVersion%%`, matching the selected Server. Its [published pairing receipt](%%artifact.helmChartQualificationUrl%%) verifies OCI/package digests and source identity; it is not a fresh cluster-install result. See [chart selection and upgrades](./deployment.md#helm-chart-selection) before installing or overriding the image.
+
 PyPI renders the Python distribution version as
 `%%artifact.pythonRegistryVersion%%`; the documented PEP 440 install spelling
 `%%artifact.pythonSdkVersion%%` resolves to that same release. This

diff --git a/docs/deployment.md b/docs/deployment.md
@@ -436,18 +436,27 @@ Install the published chart from the OCI registry:
 
 ```bash
 helm install durable-workflow \
-  oci://ghcr.io/durable-workflow/charts/durable-workflow \
+  %%artifact.helmChartRepository%% \
+  --version %%artifact.helmChartVersion%% \
   --namespace durable-workflow --create-namespace \
   -f my-values.yaml
 ```
 
 Your values file must point to an external MySQL/PostgreSQL database and
 external Redis, provide production credentials through existing Kubernetes
 Secrets, and configure ingress/TLS for your environment. The chart does not
-create persistence or provider-managed infrastructure. For reproducible
-production deployments, add `--version <validated-chart-version>` and pin the
-Server image by digest. The Server repository publishes chart versions and
-documents chart upgrades alongside the chart source.
+create persistence or provider-managed infrastructure. Pin the Server image by
+digest for a reproducible deployment.
+
+### Choosing a chart release {#helm-chart-selection}
+
+One chart release records the Server image it was tested against in `Chart.yaml`'s `appVersion`; the chart and Server have independent version numbers. The selected [compatibility tuple](./compatibility.md#last-qualified-reproducible-tuple) pairs chart **%%artifact.helmChartVersion%%** with Server **%%artifact.helmChartAppVersion%%**, from the same release metadata as the table and install command. Its [published OCI/package receipt](%%artifact.helmChartQualificationUrl%%) verifies that pairing, not a fresh Kubernetes installation.
+
+For another Server version, inspect the candidate published chart's `Chart.yaml` (the [selected chart source](%%artifact.helmChartSourceUrl%%) is an example) and select an exact chart version whose `appVersion` matches your intended Server. Read the selected release's [UPGRADING notes](%%artifact.helmChartUpgradeUrl%%), including every chart version crossed. Do not infer a chart version from the Server version or select an unpublished chart from current source.
+
+Overriding `image.tag` changes the image without changing the chart's recorded `appVersion`. That produces a custom chart/image tuple until it receives its own rendered-manifest, bootstrap, rollout and runtime qualification. Keep ordinary database backups and rollback boundaries in the upgrade plan; a successful render alone does not prove the deployment works.
+
+The published history includes an exception: chart 0.2.2 crossed a Server minor under a chart patch number. The later [published correction](https://github.com/durable-workflow/server/blob/2.11.0/k8s/helm/durable-workflow/docs/UPGRADING.md#chart-022--server-210) acknowledges that exception and resumes the stated minor-version policy. Historical versions stay unchanged; this note does not select the later Server/chart tuple.
 
 ## Kubernetes manifests
 

diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -74,7 +74,7 @@ const config = {
       ({
         docs: {
           sidebarPath: require.resolve('./sidebars.js'),
-          remarkPlugins: [artifactVersionRemarkPlugin],
+          beforeDefaultRemarkPlugins: [artifactVersionRemarkPlugin],
           editUrl:
             'https://github.com/durable-workflow/durable-workflow.github.io/edit/main/',
           editLocalizedFiles: true,

diff --git a/i18n/de/docusaurus-plugin-content-docs/current/compatibility.md b/i18n/de/docusaurus-plugin-content-docs/current/compatibility.md
@@ -157,13 +157,17 @@ Die Tabelle zeigt die für diese Dokumentation geprüfte stabile Kombination aus
 | Komponente | Unterstützte Version | Installationsidentität |
 |-----------|-------------------|------------------|
 | Server | `%%artifact.serverVersion%%` | `%%artifact.serverDockerHubImage%%` |
+| Helm-Chart | `%%artifact.helmChartVersion%%` | `%%artifact.helmChartInstallIdentity%%` |
 | CLI | `%%artifact.cliVersion%%` | `%%artifact.cliInstallerEnv%%` |
 | Workflow-Engine | `%%artifact.workflowVersion%%` | `%%artifact.workflowComposerPackage%%` |
 | Waterline-Operator | `%%artifact.waterlineVersion%%` | `%%artifact.waterlineComposerPackage%%` |
 | PHP-SDK | `%%artifact.phpSdkVersion%%` | `%%artifact.phpSdkComposerPackage%%` |
 | Python-SDK | `%%artifact.pythonSdkVersion%%` | `%%artifact.pythonPackagePin%%` |
 | Rust-SDK | `%%artifact.rustSdkVersion%%` | `%%artifact.rustCargoRequirement%%` |
 
+Die aufgezeichnete `appVersion` des Helm-Charts ist `%%artifact.helmChartAppVersion%%` und entspricht dem ausgewählten Server. Der [Prüfbericht zur veröffentlichten Kombination](%%artifact.helmChartQualificationUrl%%) bestätigt OCI-/Paket-Digests und die Quellidentität; er belegt keine neue Clusterinstallation. Lesen Sie vor der Installation oder einem Image-Override die [Chart-Auswahl und Upgrade-Hinweise](./deployment.md#helm-chart-selection).
+
+
 PyPI stellt die Python-Distributionsversion als `%%artifact.pythonRegistryVersion%%` dar. Die dokumentierte PEP-440-Installationsschreibweise `%%artifact.pythonSdkVersion%%` löst dieselbe Veröffentlichung auf. Diese Normalisierung erzeugt keine zweite unterstützte Version.
 
 Die gewählte Kombination wird nach Qualifizierung der betroffenen Verbraucher weitergeführt. Die veröffentlichten Serverregistries und generierten Schnellstarts verwenden die gewählten Artefakte. Pakete können unabhängig veröffentlicht werden. Ihre Kompatibilität wird über Protokollmanifeste, Fähigkeiten und Verbraucherprüfungen bestätigt.

diff --git a/i18n/de/docusaurus-plugin-content-docs/current/deployment.md b/i18n/de/docusaurus-plugin-content-docs/current/deployment.md
@@ -324,12 +324,23 @@ Das Serverrepository verantwortet [Chart-Quellcode und Veröffentlichungshinweis
 
 ```bash
 helm install durable-workflow \
-  oci://ghcr.io/durable-workflow/charts/durable-workflow \
+  %%artifact.helmChartRepository%% \
+  --version %%artifact.helmChartVersion%% \
   --namespace durable-workflow --create-namespace \
   -f my-values.yaml
 ```
 
-Ihre Values-Datei muss eine externe MySQL-/PostgreSQL-Datenbank und externes Redis angeben, Produktionszugangsdaten über bestehende Kubernetes-Secrets liefern und Ingress/TLS für Ihre Umgebung konfigurieren. Das Chart erstellt weder Persistenz noch providerverwaltete Infrastruktur. Ergänzen Sie für reproduzierbare Produktion `--version <validated-chart-version>` und legen Sie das Serverimage per Digest fest. Das Serverrepository veröffentlicht Chartversionen und dokumentiert Chart-Upgrades neben dem Chart-Quellcode.
+Ihre Values-Datei muss auf externes MySQL/PostgreSQL und Redis verweisen, Produktionszugangsdaten über vorhandene Kubernetes Secrets bereitstellen und ingress/TLS für Ihre Umgebung konfigurieren. Das Chart erstellt weder Persistenz noch vom Anbieter verwaltete Infrastruktur. Fixieren Sie das Server-Image für ein reproduzierbares Deployment per Digest.
+
+### Einen Chart-Release auswählen {#helm-chart-selection}
+
+Jeder Chart-Release hält das getestete Server-Image in der `appVersion` der `Chart.yaml` fest; Chart und Server haben unabhängige Versionsnummern. Die ausgewählte [kompatible Kombination](./compatibility.md#last-qualified-reproducible-tuple) verbindet Chart **%%artifact.helmChartVersion%%** mit Server **%%artifact.helmChartAppVersion%%** aus denselben Release-Metadaten wie Tabelle und Installationsbefehl. Der [Prüfbericht zu OCI/veröffentlichtem Paket](%%artifact.helmChartQualificationUrl%%) bestätigt diese Kombination, keine neue Kubernetes-Installation.
+
+Prüfen Sie für eine andere Server-Version die `Chart.yaml` des vorgesehenen veröffentlichten Charts (die [ausgewählte Chart-Quelle](%%artifact.helmChartSourceUrl%%) dient als Beispiel) und wählen Sie eine exakte Chart-Version, deren `appVersion` dem gewünschten Server entspricht. Lesen Sie die [UPGRADING-Hinweise](%%artifact.helmChartUpgradeUrl%%) des ausgewählten Releases einschließlich jeder übersprungenen Chart-Version. Leiten Sie die Chart-Version nicht aus der Server-Version ab und wählen Sie kein unveröffentlichtes Chart aus dem aktuellen Quellstand.
+
+Ein Override von `image.tag` ändert das Image, ohne die aufgezeichnete `appVersion` des Charts zu ändern. Damit entsteht eine eigene Chart-/Image-Kombination, bis gerenderte Manifeste, Bootstrap, Rollout und Runtime gesondert qualifiziert wurden. Behalten Sie übliche Datenbanksicherungen und Rollback-Grenzen im Upgrade-Plan bei; erfolgreiches Rendern allein belegt kein funktionierendes Deployment.
+
+Die veröffentlichte Historie enthält eine Ausnahme: Chart 0.2.2 wechselte unter einer Chart-Patchnummer auf eine neue Server-Minor-Version. Die spätere [veröffentlichte Korrektur](https://github.com/durable-workflow/server/blob/2.11.0/k8s/helm/durable-workflow/docs/UPGRADING.md#chart-022--server-210) erkennt die Ausnahme an und kehrt zur erklärten Minor-Versionspolitik zurück. Historische Versionen bleiben unverändert; dieser Hinweis wählt keine spätere Server-/Chart-Kombination aus.
 
 ## Kubernetes-Manifeste {#kubernetes-manifests}
 

diff --git a/i18n/de/source-hashes.json b/i18n/de/source-hashes.json
@@ -4,7 +4,7 @@
   "ai-agent-workflow-engine.md": "28016466b179adbabdff6467ce351100c9bee48529a8bec9df7ec22c8d786d4d",
   "ai-assisted-development.md": "b246bb60585fb7a69bc534978f470f3f16e899e1f8f203ba0847d2d11b8a1ec3",
   "capabilities.md": "d9a2bbc0d04adf8cb3f4c7f42d779a43aafab60791210305e7e476c0499528fc",
-  "compatibility.md": "28e6e3a55920762b4c9380721710de994335831db573447a60d92b213938d3fb",
+  "compatibility.md": "5d88e55a566f4103307871846ffc042c8e1e1d10ea57a44bcb3b3542643743d5",
   "configuration/customization-matrix.md": "3d115863eaee7852b541bcd01615f424cc19c5847c7cd7d75e5ae63bc3f5cc78",
   "configuration/database-connection.md": "a4657d239673a4ecdc3981bcc5a7cf33aa2d37c709768131cd5ba3292987681f",
   "configuration/ensuring-same-server.md": "6c665f37cc198c7b1a775a60a94aab5ff4e55383385e76f1834c7840559b512a",
@@ -27,7 +27,7 @@
   "defining-workflows/workflow-id.md": "91b94211e2f8f405895ad82cfe2ef9baadb7a2cbd06e9c1e7aa6362231e0d424",
   "defining-workflows/workflow-status.md": "8e8cb27ff44c890d489d89bf166375acfdfaecabd990a2235e106fab1592d529",
   "defining-workflows/workflows.md": "f467bc73de32aa5d722c61ce085065460382ae7dd44cea4625847d9fcdc4c97c",
-  "deployment.md": "6f1e88e2d67a5b086c73cc9b42b7f9583f46a45a1bf3b95ceff06457ebe17564",
+  "deployment.md": "2f272a9c37aade0a8bd7ab5ab388a9aaef9b9d4a9ae387ca303bf67e6c860d97",
   "failures-and-recovery.md": "b142a2edc4c9836bca2634b6a0a2358336f99103e9da04ed64053d12b74b796e",
   "features/activity-execution-model.md": "e8c37520ae46a7efb30438f4fc06bf893c1df430cb1f92c48963697adaf09082",
   "features/cancel-and-terminate.md": "c678fc7a0c9b11f0e1bee295aff259de9803219c0aa6769fb801622799e7deb1",

diff --git a/i18n/es/docusaurus-plugin-content-docs/current/compatibility.md b/i18n/es/docusaurus-plugin-content-docs/current/compatibility.md
@@ -217,13 +217,17 @@ huellas de imágenes exactas usadas en cada comprobación completada.
 | Componente | Versión admitida | Identidad de instalación |
 |-----------|-------------------|------------------|
 | Server | `%%artifact.serverVersion%%` | `%%artifact.serverDockerHubImage%%` |
+| Chart de Helm | `%%artifact.helmChartVersion%%` | `%%artifact.helmChartInstallIdentity%%` |
 | CLI | `%%artifact.cliVersion%%` | `%%artifact.cliInstallerEnv%%` |
 | Motor Workflow | `%%artifact.workflowVersion%%` | `%%artifact.workflowComposerPackage%%` |
 | Operador Waterline | `%%artifact.waterlineVersion%%` | `%%artifact.waterlineComposerPackage%%` |
 | SDK PHP | `%%artifact.phpSdkVersion%%` | `%%artifact.phpSdkComposerPackage%%` |
 | SDK Python | `%%artifact.pythonSdkVersion%%` | `%%artifact.pythonPackagePin%%` |
 | SDK Rust | `%%artifact.rustSdkVersion%%` | `%%artifact.rustCargoRequirement%%` |
 
+El `appVersion` registrado del chart de Helm es `%%artifact.helmChartAppVersion%%`, que coincide con el Server seleccionado. La [verificación del par publicado](%%artifact.helmChartQualificationUrl%%) comprueba los digests OCI/del paquete y la identidad del código fuente; no es una nueva instalación de clúster verificada. Consulte la [selección y actualización del chart](./deployment.md#helm-chart-selection) antes de instalar o sustituir la imagen.
+
+
 PyPI muestra la versión de distribución de Python como
 `%%artifact.pythonRegistryVersion%%`. La forma de instalación PEP 440 documentada
 `%%artifact.pythonSdkVersion%%` resuelve a esa misma publicación. Esta

diff --git a/i18n/es/docusaurus-plugin-content-docs/current/deployment.md b/i18n/es/docusaurus-plugin-content-docs/current/deployment.md
@@ -417,17 +417,23 @@ Instala el chart publicado desde el registro OCI:
 
 ```bash
 helm install durable-workflow \
-  oci://ghcr.io/durable-workflow/charts/durable-workflow \
+  %%artifact.helmChartRepository%% \
+  --version %%artifact.helmChartVersion%% \
   --namespace durable-workflow --create-namespace \
   -f my-values.yaml
 ```
 
-Tu archivo de valores debe apuntar a MySQL/PostgreSQL y Redis externos, aportar
-credenciales de producción mediante Secrets existentes y configurar ingress/TLS.
-El chart no crea persistencia ni infraestructura gestionada. Para reproducir
-producción, añade `--version <validated-chart-version>` y fija la imagen de
-Server por resumen. El repositorio publica versiones y documenta actualizaciones
-junto al código del chart.
+El archivo de valores debe apuntar a MySQL/PostgreSQL y Redis externos, proporcionar credenciales de producción mediante Kubernetes Secrets existentes y configurar ingress/TLS para su entorno. El chart no crea almacenamiento persistente ni infraestructura administrada por el proveedor. Fije la imagen del Server por digest para un despliegue reproducible.
+
+### Elegir una versión del chart {#helm-chart-selection}
+
+Cada versión del chart registra en `appVersion` de `Chart.yaml` la imagen del Server con la que se probó; el chart y el Server tienen números de versión independientes. La [combinación compatible seleccionada](./compatibility.md#last-qualified-reproducible-tuple) empareja el chart **%%artifact.helmChartVersion%%** con Server **%%artifact.helmChartAppVersion%%**, usando los mismos metadatos de versiones que la tabla y el comando de instalación. La [verificación OCI/del paquete publicado](%%artifact.helmChartQualificationUrl%%) comprueba ese par, no una instalación nueva de Kubernetes.
+
+Para otra versión del Server, inspeccione el `Chart.yaml` del chart publicado candidato (el [código del chart seleccionado](%%artifact.helmChartSourceUrl%%) es un ejemplo) y seleccione una versión exacta cuyo `appVersion` coincida con el Server deseado. Lea las [notas UPGRADING](%%artifact.helmChartUpgradeUrl%%) de la versión seleccionada, incluidas todas las versiones del chart que atraviese. No deduzca la versión del chart a partir de la del Server ni seleccione un chart sin publicar del código actual.
+
+Sustituir `image.tag` cambia la imagen sin cambiar el `appVersion` registrado del chart. Eso produce una combinación personalizada hasta que se valide por separado con sus manifiestos generados, bootstrap, despliegue y runtime. Mantenga las copias de seguridad habituales y los límites de reversión en el plan de actualización; generar correctamente los manifiestos no demuestra que el despliegue funcione.
+
+El historial publicado contiene una excepción: el chart 0.2.2 cruzó una versión menor del Server bajo un número patch del chart. La [corrección publicada posterior](https://github.com/durable-workflow/server/blob/2.11.0/k8s/helm/durable-workflow/docs/UPGRADING.md#chart-022--server-210) reconoce la excepción y retoma la política declarada de versiones menores. Las versiones históricas permanecen intactas; esta nota no selecciona la combinación posterior del Server/chart.
 
 ## Manifiestos Kubernetes {#kubernetes-manifests}
 

diff --git a/i18n/es/source-hashes.json b/i18n/es/source-hashes.json
@@ -4,7 +4,7 @@
   "ai-agent-workflow-engine.md": "28016466b179adbabdff6467ce351100c9bee48529a8bec9df7ec22c8d786d4d",
   "ai-assisted-development.md": "b246bb60585fb7a69bc534978f470f3f16e899e1f8f203ba0847d2d11b8a1ec3",
   "capabilities.md": "d9a2bbc0d04adf8cb3f4c7f42d779a43aafab60791210305e7e476c0499528fc",
-  "compatibility.md": "28e6e3a55920762b4c9380721710de994335831db573447a60d92b213938d3fb",
+  "compatibility.md": "5d88e55a566f4103307871846ffc042c8e1e1d10ea57a44bcb3b3542643743d5",
   "configuration/customization-matrix.md": "3d115863eaee7852b541bcd01615f424cc19c5847c7cd7d75e5ae63bc3f5cc78",
   "configuration/database-connection.md": "a4657d239673a4ecdc3981bcc5a7cf33aa2d37c709768131cd5ba3292987681f",
   "configuration/ensuring-same-server.md": "6c665f37cc198c7b1a775a60a94aab5ff4e55383385e76f1834c7840559b512a",
@@ -27,7 +27,7 @@
   "defining-workflows/workflow-id.md": "91b94211e2f8f405895ad82cfe2ef9baadb7a2cbd06e9c1e7aa6362231e0d424",
   "defining-workflows/workflow-status.md": "8e8cb27ff44c890d489d89bf166375acfdfaecabd990a2235e106fab1592d529",
   "defining-workflows/workflows.md": "f467bc73de32aa5d722c61ce085065460382ae7dd44cea4625847d9fcdc4c97c",
-  "deployment.md": "6f1e88e2d67a5b086c73cc9b42b7f9583f46a45a1bf3b95ceff06457ebe17564",
+  "deployment.md": "2f272a9c37aade0a8bd7ab5ab388a9aaef9b9d4a9ae387ca303bf67e6c860d97",
   "failures-and-recovery.md": "b142a2edc4c9836bca2634b6a0a2358336f99103e9da04ed64053d12b74b796e",
   "features/activity-execution-model.md": "e8c37520ae46a7efb30438f4fc06bf893c1df430cb1f92c48963697adaf09082",
   "features/cancel-and-terminate.md": "c678fc7a0c9b11f0e1bee295aff259de9803219c0aa6769fb801622799e7deb1",

diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/compatibility.md b/i18n/fr/docusaurus-plugin-content-docs/current/compatibility.md
@@ -215,13 +215,17 @@ pour chaque vérification terminée.
 | Composant | Version prise en charge | Identité d'installation |
 |-----------|-------------------|------------------|
 | Server | `%%artifact.serverVersion%%` | `%%artifact.serverDockerHubImage%%` |
+| Chart Helm | `%%artifact.helmChartVersion%%` | `%%artifact.helmChartInstallIdentity%%` |
 | CLI | `%%artifact.cliVersion%%` | `%%artifact.cliInstallerEnv%%` |
 | Moteur Workflow | `%%artifact.workflowVersion%%` | `%%artifact.workflowComposerPackage%%` |
 | Opérateur Waterline | `%%artifact.waterlineVersion%%` | `%%artifact.waterlineComposerPackage%%` |
 | SDK PHP | `%%artifact.phpSdkVersion%%` | `%%artifact.phpSdkComposerPackage%%` |
 | SDK Python | `%%artifact.pythonSdkVersion%%` | `%%artifact.pythonPackagePin%%` |
 | SDK Rust | `%%artifact.rustSdkVersion%%` | `%%artifact.rustCargoRequirement%%` |
 
+L’`appVersion` enregistré du chart Helm est `%%artifact.helmChartAppVersion%%`, correspondant au Server sélectionné. La [vérification de la paire publiée](%%artifact.helmChartQualificationUrl%%) contrôle les digests OCI/du paquet et l’identité source ; ce n’est pas le résultat d’une nouvelle installation de cluster. Consultez le [choix et la mise à niveau du chart](./deployment.md#helm-chart-selection) avant d’installer ou de remplacer l’image.
+
+
 PyPI affiche la version de distribution Python sous
 `%%artifact.pythonRegistryVersion%%`. La forme d'installation PEP 440 documentée
 `%%artifact.pythonSdkVersion%%` désigne cette même publication. Cette