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

docs/pdns-upstream.md

@@ -79,3 +79,6 @@ Drop-in (from `.env`, never commit): `gpgsql-dbname`, `gpgsql-user`, `gpgsql-pas
 
 - Host facts: [hosts/hk2.chans.xyz.md](../hosts/hk2.chans.xyz.md)
 - Health runbook: [runbooks/pdns-health.md](../runbooks/pdns-health.md)
+- Routine status: `ansible/playbooks/health-report.yml --limit powerdns`
+- Reviewed Compose reconciliations: `ansible/playbooks/compose-reconcile.yml`
+  (`auth`, `poweradmin`, and `backup` are the only allowlisted targets)

docs/vaultwarden-upstream.md

@@ -50,4 +50,13 @@ Official stance: prefer environment variables; `config.json` is **not** the reco
 5. Do not commit secrets; do not copy passwords from Obsidian into this repo.
 6. Verify SMTP with AUTH (not TCP-only) — [vaultwarden-health](../runbooks/vaultwarden-health.md) §5.
 
+## Operations path
+
+Use `ansible/playbooks/health-report.yml --limit vaultwarden` for routine
+status. After a reviewed effective-configuration change that needs a container
+recreate, use the allowlisted `compose-reconcile.yml` target `vaultwarden`.
+Add `service_reconcile_restart_traefik=true` only when the documented
+post-recreate 404 occurs. Direct Compose commands remain diagnostic tools, not
+the routine control path.
+
 Replay migration steps: [runbooks/vaultwarden-sqlite-to-postgres.md](../runbooks/vaultwarden-sqlite-to-postgres.md).