feat: auto-backup edited entities before write/destructive tool calls

Closes #1288. Captures a per-entity snapshot of every wrapped write or
destructive MCP tool call (automation, script, scene, helper, dashboard,
dashboard resource, label, category, group, zone, area/floor, todo item,
calendar event, entity, integration enable/disable + matching remove /
delete tools — 28 wrapped points). Captures land as YAML files in a
local directory (default /data/ha_mcp_backups on the addon,
${XDG_DATA_HOME:-~/.local/share}/ha_mcp/backups elsewhere; override via
HAMCP_BACKUP_DIR) and are listable, viewable, diffable, restorable, and
deletable via:

- Polymorphic MCP tool ha_manage_backup(scope, action, ...). Replaces
  the previous ha_backup_create + ha_backup_restore pair under
  scope="snapshot" (existing full-HA-tarball behavior, no semantic
  change) and adds the new scope="edits" actions list/view/restore/
  delete. Strong gating against accidental wrong-mode usage: invalid
  (scope, action) combos return VALIDATION_INVALID_PARAMETER with the
  legal set in suggestions; required params validated per cell so
  "restore my automation" can never route through the heavy
  HA-restart restore path.
- New "Backups" tab in the existing /settings web UI with filter, view,
  diff, restore, per-row delete, and bulk-delete-by-filter actions —
  list / view / diff / restore / delete REST endpoints at
  /api/settings/backups[/<name>[/diff|/restore]].

Capture is gated by the new enable_auto_backup setting (default off).
Throttle window is configurable via auto_backup_throttle_minutes
(default 0 = capture every write); retention is configurable via
auto_backup_retain_per_entity (default 20). All three plumb through the
addon config + dev mirror + dev translation + start.py env mapping.

Implementation lives in src/ha_mcp/backup_manager.py (BackupManager +
DomainHandler registry) and src/ha_mcp/tools/auto_backup.py
(@with_auto_backup decorator). Captures are best-effort: any failure in
the pre-write hook logs a WARNING and the wrapped tool proceeds. The
existing ha_config_set_yaml backup precedent in
custom_components/ha_mcp_tools is untouched — this PR adds a
parallel system that works without the custom component installed.

Author: kingpanther13

docs/superpowers/specs/2026-05-21-1288-auto-backup-design.md

@@ -121,17 +121,78 @@ User-facing entry points (both call `BackupManager.restore`):
 
 Restore is upsert: re-creates entities that were deleted between backup and restore. If HA rejects (validation error, etc.), error propagates with structured suggestions.
 
-## List / view / diff / delete flow
+## Polymorphic `ha_manage_backup` tool
 
-Each operation is a thin method on `BackupManager`, exposed via:
+`ha_backup_create` and `ha_backup_restore` are **merged** into a single
+polymorphic tool `ha_manage_backup` that handles BOTH the existing full-HA-
+snapshot functionality AND the new per-edit auto-backup operations. Net tool
+count change: **-1** (remove 2 tools, add 1).
 
-| MCP tool | UI endpoint | UI element |
+```python
+ha_manage_backup(
+    scope: Literal["snapshot", "edits"],
+    action: Literal["create", "restore", "list", "view", "delete"],
+    # snapshot scope params
+    name: str | None = None,          # snapshot.create: tarball name
+    backup_id: str | None = None,     # snapshot.restore: tarball ID
+    restore_database: bool = False,   # snapshot.restore: include DB
+    # edits scope params
+    domain: str | None = None,        # edits.list / edits.delete: filter
+    entity_id: str | None = None,     # edits.list / edits.delete: filter
+    backup_name: str | None = None,   # edits.view / edits.restore / edits.delete
+    older_than_days: int | None = None,  # edits.delete: bulk-by-age
+)
+```
+
+### Routing matrix
+
+| scope | action | Behavior |
+|---|---|---|
+| `snapshot` | `create` | Existing `ha_backup_create` behavior — full HA tarball via HA's native backup integration |
+| `snapshot` | `restore` | Existing `ha_backup_restore` behavior — HA restarts, pre-restore safety tarball created automatically |
+| `edits` | `list` | List auto-backup files filterable by `domain` and/or `entity_id` |
+| `edits` | `view` | Return one auto-backup's YAML content + parsed `config` |
+| `edits` | `restore` | Re-apply one auto-backup (creates fresh safety snapshot first); no HA restart |
+| `edits` | `delete` | Delete one auto-backup by name OR bulk-delete by filter (domain/entity_id/older_than_days) |
+
+### Gating against accidental wrong-mode usage
+
+This is the main design risk — without strong gates, the LLM could route
+"restore my automation" through `(scope="snapshot", action="restore")`,
+which would restart HA. Layered defenses:
+
+1. **Type validation**: `scope` and `action` are `Literal`-typed so Pydantic
+   rejects unknown values before the tool body runs.
+2. **Scope+action matrix validation**: invalid combinations
+   (`(snapshot, list)`, `(snapshot, view)`, `(snapshot, delete)`,
+   `(edits, create)`) raise `VALIDATION_INVALID_PARAMETER` with the valid
+   combinations listed in `suggestions`.
+3. **Required-param checks per cell**:
+   - `(snapshot, restore)` requires `backup_id`; if `backup_name` or
+     `entity_id` is passed instead, structured error explains the param
+     belongs to the other scope.
+   - `(edits, restore/view/delete-single)` requires `backup_name` (which
+     follows the `<domain>.<entity_id>.<timestamp>.yaml` shape — clearly
+     not a tarball ID).
+4. **Annotation differentiation**:
+   - `(snapshot, restore)` keeps the existing `destructiveHint: True` AND
+     surfaces the "LAST RESORT — HA will restart" warning in the response.
+   - `(edits, restore)` is also destructive but explicitly safer; response
+     includes `restart_required: false` and the path of the safety backup
+     created.
+5. **Docstring**: the tool's docstring leads with a routing table so the
+   LLM picks the right cell. Per-scope sections clearly state what each
+   does and how they differ.
+
+### UI mapping
+
+| Tool call | UI endpoint | UI element |
 |---|---|---|
-| `ha_manage_auto_backup(action="list", domain?, entity_id?, since?, limit?)` | `GET /api/settings/backups?...` | Backup list table with filters |
-| `ha_manage_auto_backup(action="view", name=...)` | `GET /api/settings/backups/<name>` | "View" button → modal showing YAML |
-| `ha_manage_auto_backup(action="diff", name=...)` | `GET /api/settings/backups/<name>/diff` | "Diff" button → modal with unified diff vs current state |
-| `ha_manage_auto_backup(action="restore", name=...)` | `POST /api/settings/backups/<name>/restore` | "Restore" button (confirmation modal) |
-| `ha_manage_auto_backup(action="delete", name=...)` *or* `(action="delete_bulk", domain?, entity_id?, older_than?)` | `DELETE /api/settings/backups/<name>`, `DELETE /api/settings/backups?...` | Per-row "Delete" + bulk "Delete all matching filters" |
+| `(edits, list)` | `GET /api/settings/backups?...` | Backups tab list table with filters |
+| `(edits, view)` | `GET /api/settings/backups/<name>` | "View" button → modal showing YAML |
+| (no tool — UI-only diff) | `GET /api/settings/backups/<name>/diff` | "Diff" button → modal with unified diff vs current state |
+| `(edits, restore)` | `POST /api/settings/backups/<name>/restore` | "Restore" button (confirmation modal) |
+| `(edits, delete)` | `DELETE /api/settings/backups/<name>` and `DELETE /api/settings/backups?...` | Per-row "Delete" + bulk "Delete matching filters" |
 
 **List item shape:**
 ```json
@@ -208,12 +269,12 @@ One test file per backed-up domain (`test_automation.py`, `test_script.py`, ...,
 **New:**
 - `src/ha_mcp/backup_manager.py`
 - `src/ha_mcp/tools/auto_backup.py` (decorator)
-- `src/ha_mcp/tools/tools_auto_backup.py` (`ha_manage_auto_backup` tool)
 - `tests/src/unit/test_backup_manager.py`
 - `tests/src/e2e/workflows/auto_backup/` (one test file per domain)
 
 **Modified:**
 - `src/ha_mcp/config.py` (4 settings)
+- `src/ha_mcp/tools/backup.py` — merge `ha_backup_create`+`ha_backup_restore` into a single `ha_manage_backup` polymorphic tool; add the `edits` scope handlers
 - `src/ha_mcp/settings_ui.py` (5 routes + Backups tab)
 - `homeassistant-addon/config.yaml` + `homeassistant-addon-dev/config.yaml` (4 options + schema)
 - `homeassistant-addon-dev/translations/en.yaml` (4 translations)

homeassistant-addon-dev/config.yaml

@@ -27,6 +27,9 @@ options:
   enable_yaml_config_editing: false
   enable_code_mode: false
   enable_lite_docstrings: false
+  enable_auto_backup: false
+  auto_backup_throttle_minutes: 0
+  auto_backup_retain_per_entity: 20
   tool_search_max_results: 5
   disabled_tools: ""
   pinned_tools: ""
@@ -40,6 +43,9 @@ schema:
   enable_lite_docstrings: bool?
   enable_filesystem_tools: bool?
   enable_custom_component_integration: bool?
+  enable_auto_backup: bool?
+  auto_backup_throttle_minutes: int(0,1440)?
+  auto_backup_retain_per_entity: int(1,10000)?
   tool_search_max_results: int(2,10)?
   disabled_tools: str?
   pinned_tools: str?

homeassistant-addon-dev/translations/en.yaml

@@ -45,6 +45,30 @@ configuration:
       Saved tools persist to /data/saved_tools.json by default so they
       survive add-on restarts. See docs/beta.md for known limitations.
       Requires restart to take effect.
+  enable_auto_backup:
+    name: Enable auto-backup of edits
+    description: >-
+      Captures a per-entity snapshot before every wrapped write/destructive
+      MCP tool call (automation, script, scene, helper, dashboard, label,
+      category, group, zone, area, calendar, todo, entity, integration, and
+      sibling remove/delete tools). Snapshots are saved as YAML files under
+      /data/ha_mcp_backups/ (override via HAMCP_BACKUP_DIR) and listed,
+      restored, or deleted via the Backups tab in the web settings UI or
+      via ha_manage_backup(scope='edits', ...). Best-effort — failures log
+      a WARNING but never block the underlying write. Off by default. No
+      restart required to take effect.
+  auto_backup_throttle_minutes:
+    name: Auto-backup throttle (minutes)
+    description: >-
+      Per-entity throttle window. 0 (default) captures a snapshot on every
+      wrapped write. N>0 captures at most one snapshot per N minutes per
+      entity. Range 0–1440.
+  auto_backup_retain_per_entity:
+    name: Auto-backup retention (per entity)
+    description: >-
+      Maximum number of snapshots kept per entity. Older snapshots beyond
+      this cap are rotated out on each successful capture. Default 20,
+      range 1–10000.
   enable_lite_docstrings:
     name: Enable lite tool docstrings (beta)
     description: >-

homeassistant-addon/config.yaml

@@ -32,11 +32,17 @@ image: "ghcr.io/homeassistant-ai/ha-mcp-addon-{arch}"
 options:
   backup_hint: "normal"
   enable_tool_search: false
+  enable_auto_backup: false
+  auto_backup_throttle_minutes: 0
+  auto_backup_retain_per_entity: 20
   verify_ssl: true
 schema:
   backup_hint: list(strong|normal|weak|auto)
   secret_path: str?
   enable_tool_search: bool?
+  enable_auto_backup: bool?
+  auto_backup_throttle_minutes: int(0,1440)?
+  auto_backup_retain_per_entity: int(1,10000)?
   verify_ssl: bool?
   advanced_debug_logging: bool?
 # Add-on exposes HTTP port for MCP communication (fixed internal port)

homeassistant-addon/start.py

@@ -218,6 +218,9 @@ def main() -> int:
     enable_custom_component_integration = False  # default
     enable_code_mode = False  # default
     enable_lite_docstrings = False  # default
+    enable_auto_backup = False  # default (#1288)
+    auto_backup_throttle_minutes = 0  # default — every write
+    auto_backup_retain_per_entity = 20  # default
     tool_search_max_results = 5  # default
     disabled_tools_raw = ""  # default
     pinned_tools_raw = ""  # default
@@ -242,6 +245,12 @@ def main() -> int:
             enable_code_mode = raw_code_mode if isinstance(raw_code_mode, bool) else False
             raw_lite_docstrings = config.get("enable_lite_docstrings", False)
             enable_lite_docstrings = raw_lite_docstrings if isinstance(raw_lite_docstrings, bool) else False
+            raw_auto_backup = config.get("enable_auto_backup", False)
+            enable_auto_backup = raw_auto_backup if isinstance(raw_auto_backup, bool) else False
+            raw_throttle = config.get("auto_backup_throttle_minutes", 0)
+            auto_backup_throttle_minutes = raw_throttle if isinstance(raw_throttle, int) else 0
+            raw_retain = config.get("auto_backup_retain_per_entity", 20)
+            auto_backup_retain_per_entity = raw_retain if isinstance(raw_retain, int) else 20
             raw_max_results = config.get("tool_search_max_results", 5)
             tool_search_max_results = raw_max_results if isinstance(raw_max_results, int) else 5
             raw_disabled = config.get("disabled_tools", "")
@@ -282,6 +291,9 @@ def main() -> int:
     os.environ["HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION"] = str(enable_custom_component_integration).lower()
     os.environ["ENABLE_CODE_MODE"] = str(enable_code_mode).lower()
     os.environ["ENABLE_LITE_DOCSTRINGS"] = str(enable_lite_docstrings).lower()
+    os.environ["ENABLE_AUTO_BACKUP"] = str(enable_auto_backup).lower()
+    os.environ["AUTO_BACKUP_THROTTLE_MINUTES"] = str(auto_backup_throttle_minutes)
+    os.environ["AUTO_BACKUP_RETAIN_PER_ENTITY"] = str(auto_backup_retain_per_entity)
     # Persist saved custom tools across addon restarts. /data is the
     # per-addon writable directory mapped by Supervisor and survives
     # add-on updates (but not uninstall/reinstall — users should copy