docs: align runbooks and validation structure

runbooks/README.md

@@ -19,6 +19,7 @@ runbooks start from [`_template.md`](_template.md).
 | AdGuard Home health check | [adguard-home-health.md](adguard-home-health.md) | read-only |
 | Matter packet capture | [matter-packet-capture.md](matter-packet-capture.md) | read-only |
 | Home Assistant maintenance | [home-assistant-maintenance.md](home-assistant-maintenance.md) | change (gated) |
+| matrix_e2ee integration update | [matrix-e2ee-update.md](matrix-e2ee-update.md) | change (gated) |
 | Routine Ansible operations | [ansible-operations.md](ansible-operations.md) | change (allowlisted) |
 | Linear issue → mergeable change | [issue-to-merge.md](issue-to-merge.md) | delivery |
 | Failing health/playbook run | [fix-ci.md](fix-ci.md) | change |

runbooks/issue-to-merge.md

@@ -56,8 +56,8 @@ scan, inventory cross-check, markdown link check, runbook-spec check, and
 Ansible `--syntax-check`); for changes that alter playbook behavior, also run
 a read-only `ansible-playbook --check` where possible.
 
-**Verification** — `scripts/validate-repo.sh` exits 0; see `RUNBOOKS.md`
-§校验; the concrete checks must match the change type.
+**Verification** — `scripts/validate-repo.sh` exits 0; the concrete checks
+must match the change type.
 
 **Decision** — verification passed → Step 4; failed → Troubleshooting A.
 

runbooks/matrix-e2ee-update.md

@@ -1,32 +1,35 @@
 # matrix_e2ee update (hass.windy.lan)
 
-Update the custom **`matrix_e2ee`** integration on `hass.windy.lan`.
+## Purpose
 
-- Last reviewed: 2026-08-18
+Update the custom **`matrix_e2ee`** integration on `hass.windy.lan` while
+preserving a verified rollback point and confirming that Home Assistant loads it.
+
+## Scope
+
+- Applicable: deploying a reviewed `matrix_e2ee` source revision to
+  `hass.windy.lan`.
+- Not applicable: Home Assistant Core upgrades, integration configuration
+  changes, or recovery without a usable live-tree backup.
+
+## Ownership
+
+- Owner: personal ops (Windy)
+- Last reviewed: 2026-08-23
 - Related systems: hass.windy.lan (HAOS, `machine: green`)
 
-Facts: [hosts/hass.windy.lan.md](../hosts/hass.windy.lan.md) (see § `matrix_e2ee` live tree)
-Source: `/home/windy/project/ha-matrix-e2ee` (development clone on workstation)
-Access: `ssh -o BatchMode=yes hassio@hass.windy.lan 'sudo -n -i <cmd>'`
+## Approval gates
 
-> **STOP conditions:** live state conflicts with the prerequisites below (e.g.
-> the source repo is not on the target state, the host manifest does not match
-> the source after rsync, or Core fails to start after restart) — stop and
-> record evidence; never bypass a failed check. Roll back per the Rollback
-> section when Core does not come back up.
+| Action | Risk | Explicit approval |
+|---|---|---|
+| Replace the live integration tree and restart Home Assistant Core | Medium | Yes — user confirmation required |
 
-> **SSH config gotcha (verified 2026-08-18):** on the WSL client the systemwide
-> `/etc/ssh/ssh_config.d/20-systemd-ssh-proxy.conf` can be owned by `nobody`
-> (e.g. under the agent sandbox), making plain `ssh` fail with
-> `Bad owner or permissions on /etc/ssh/ssh_config.d/20-systemd-ssh-proxy.conf`.
-> Workaround: add `-F /dev/null` to every ssh/rsync command below (still uses
-> the default key and `~/.ssh/known_hosts`). If your plain `ssh hassio@...`
-> works, you can drop it.
+## Safety
 
-> Domain is **`matrix_e2ee`** (double-e). Older notes may say `matrix_e2e`;
-> paths, events, and services all use `matrix_e2ee`.
+- Do not replace the live tree or restart Core without explicit user confirmation.
+- If any precondition or verification fails, `STOP` and record evidence before continuing.
 
-## Prerequisites
+## Preconditions
 
 - The source repo at `/home/windy/project/ha-matrix-e2ee` is on the **target
   state**: either a release tag (`git tag -l 'v*'`) or a commit whose
@@ -41,8 +44,11 @@ Access: `ssh -o BatchMode=yes hassio@hass.windy.lan 'sudo -n -i <cmd>'`
 - The remote host is reachable and `sudo -n -i ha core info` succeeds.
 - The workstation HTTP proxy does not interfere — LAN hosts must be reachable
   without proxying (unset `http_proxy` / `HTTP_PROXY` if needed).
+- If the agent sandbox hits `Bad owner or permissions on /etc/ssh/ssh_config.d/20-systemd-ssh-proxy.conf`, add `-F /dev/null` to the `ssh` / `rsync` commands below.
+- Domain is **`matrix_e2ee`** (double-e). Older notes may say `matrix_e2e`;
+  paths, events, and services all use `matrix_e2ee`.
 
-## Update procedure
+## Procedure
 
 ### 1. Backup the live tree