Manage routine operations through Ansible

docs/matrix-upstream.md

@@ -64,19 +64,20 @@ The ESS chart is deployed via Ansible (`ansible/playbooks/matrix-stack.yml`) wit
 
 ## Upgrades
 
+Update the pinned `matrix_stack_chart_version` in
+`ansible/inventory/hosts.yml` through normal review, then apply the chart via
+the gated Ansible playbook:
+
 ```bash
-# Pull latest chart version
-helm pull oci://ghcr.io/element-hq/ess-helm/matrix-stack --version <new-version>
-
-# Review changes
-helm diff upgrade ess oci://ghcr.io/element-hq/ess-helm/matrix-stack \
-  -n ess -f /etc/ess/hostnames.yaml -f /etc/ess/tls.yaml
-
-# Apply
-helm upgrade --install ess oci://ghcr.io/element-hq/ess-helm/matrix-stack \
-  -n ess -f /etc/ess/hostnames.yaml -f /etc/ess/tls.yaml --wait
+cd ansible
+ansible-playbook playbooks/matrix-preflight.yml
+ansible-playbook playbooks/matrix-stack.yml --limit matrix \
+  -e 'matrix_stack_enabled=true'
 ```
 
+Use `helm diff` on the target only as a read-only supplement when the plugin is
+installed; do not apply a release with a hand-written `helm upgrade` command.
+
 Before upgrading:
 - Matrix backup automation is currently paused; establish and test a reviewed backup design before treating the deployment as recoverable.
 - Review chart changelog and database migration notes