diff --git a/runbooks/README.md b/runbooks/README.md
index c21430a..35fbd91 100644
--- a/runbooks/README.md
+++ b/runbooks/README.md
@@ -17,6 +17,7 @@ runbooks start from [`_template.md`](_template.md).
 | RustDesk health check | [rustdesk-health.md](rustdesk-health.md) | read-only |
 | Matrix health check | [matrix-health.md](matrix-health.md) | read-only |
 | AdGuard Home health check | [adguard-home-health.md](adguard-home-health.md) | read-only |
+| Home Assistant maintenance | [home-assistant-maintenance.md](home-assistant-maintenance.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 |
diff --git a/runbooks/home-assistant-maintenance.md b/runbooks/home-assistant-maintenance.md
index 10df096..c1c9990 100644
--- a/runbooks/home-assistant-maintenance.md
+++ b/runbooks/home-assistant-maintenance.md
@@ -8,6 +8,32 @@ supervisor CLI**. All commands are wrapped by a single script
 [`scripts/ha-maintenance.sh`](scripts/ha-maintenance.sh); the sections below
 document the exact commands it runs, for manual/agent use.
 
+## Purpose
+
+Run routine Home Assistant maintenance on `hass.windy.lan` (health snapshot,
+config validation, log inspection, updates, and recovery) through the `ha`
+supervisor CLI.
+
+## Scope
+
+Applies to `hass.windy.lan` only (HAOS, `machine: green`). Covers both
+read-only checks and gated mutating operations; the "Command families
+intentionally NOT scripted" table below lists what is deliberately out of
+scope.
+
+## Safety
+
+- Prefer read-only checks first; the health snapshot mutates nothing.
+- Every mutating mode (update / restart / rebuild / rollback / reboot /
+  backup / restore / add-on lifecycle) refuses to run without `--yes`.
+- `--restore` overwrites the current installation; `--rollback-os`,
+  `--reboot`, and `--rebuild-core` are disruptive. Run them only from a
+  planned recovery with the backup verified.
+- Never commit `SUPERVISOR_TOKEN` or a long-lived `HA_TOKEN`; read entity
+  state via Supervisor (`SUPERVISOR_TOKEN` after `sudo -n -i`).
+- The `--restart-core` wrapper exits 1 silently on ssh failure — treat an
+  empty/exit-1 result as failure and confirm with `ha core info`.
+
 ## Access pattern
 
 `ha` authenticates to the Supervisor with `SUPERVISOR_TOKEN`. Interactive SSH