feat(backup): on-demand snapshot via scope=edits,action=create + UX polish

Three things from BAT validation feedback:

1. **On-demand snapshot for ``ha_manage_backup(scope='edits',
   action='create', domain=..., entity_id=...)``.** Mirrors the
   ``@with_auto_backup`` decorator's path — same handler registry,
   same throttle/rotation — but triggered explicitly when the user
   is about to manually edit something in the HA UI (outside the
   MCP-tool surface). Bypasses ``enable_auto_backup`` because the
   request is explicit; clears the per-entity throttle tracker so
   the capture always fires. Both ``domain`` and ``entity_id`` are
   required; unknown domain returns a structured 400 listing the
   registered domain set. The handler does ``object.__setattr__``
   for the temporary toggle flip so the override is tight to this
   one call (Settings is a shared singleton).

2. **Strip leading ``automation.`` prefix from snapshot filenames.**
   When the caller passes ``identifier="automation.foo"`` (typical
   ``python_transform`` path with no config body), the snapshot
   filename was ``automation.automation.foo.<ts>.yaml`` — the
   domain segment duplicated. ``automation_backup_target`` now
   strips the leading ``automation.`` from the identifier on the
   fallback path; YAML body's ``entity_id`` keeps the full form
   for restore-side compatibility. Other domains (helper, label,
   etc.) already pass bare IDs and are unaffected.

3. **Bump default ``auto_backup_retain_per_entity`` from 20 to 100.**
   Real-world file sizes from BAT testing: medium automation 4 KB,
   complex AI-vision script 8 KB. 100 retention × 8 KB = 800 KB per
   entity — trivial. Old 20 default was conservative; 100 gives a
   week-plus of edit history at typical usage. Updated in:
   ``Settings`` field default, both addon config.yaml defaults,
   start.py default, both translations description text, and the
   ``test_apply_overrides_keeps_defaults_for_unset_envs`` unit
   assert.

E2E coverage:
- New ``TestEditsCreateOnDemandSnapshot`` class with a positive
  round-trip (create → on-demand snapshot → list → cleanup) and a
  negative (unknown domain → 400).
- Existing ``TestManageBackupGating.test_edits_create_rejected``
  renamed + rewritten to ``test_edits_create_requires_domain_and_entity_id``
  — the combo is no longer rejected outright, but bare call without
  domain/entity_id still must fail with a structured validation error.

Tool docstring + routing-matrix updated with the new
``(edits, create)`` row and a usage example for the "snapshot before
manual UI edit" pattern.

Author: kingpanther13

homeassistant-addon-dev/config.yaml

@@ -29,7 +29,7 @@ options:
   enable_lite_docstrings: false
   enable_auto_backup: false
   auto_backup_throttle_minutes: 0
-  auto_backup_retain_per_entity: 20
+  auto_backup_retain_per_entity: 100
   tool_search_max_results: 5
   disabled_tools: ""
   pinned_tools: ""

homeassistant-addon-dev/translations/en.yaml

@@ -67,7 +67,7 @@ configuration:
     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,
+      this cap are rotated out on each successful capture. Default 100,
       range 1–10000.
   enable_lite_docstrings:
     name: Enable lite tool docstrings (beta)

homeassistant-addon/config.yaml

@@ -34,7 +34,7 @@ options:
   enable_tool_search: false
   enable_auto_backup: false
   auto_backup_throttle_minutes: 0
-  auto_backup_retain_per_entity: 20
+  auto_backup_retain_per_entity: 100
   verify_ssl: true
 schema:
   backup_hint: list(strong|normal|weak|auto)

homeassistant-addon/start.py

@@ -226,7 +226,7 @@ def main() -> int:
     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
+    auto_backup_retain_per_entity = 100  # default
     tool_search_max_results = 5  # default
     disabled_tools_raw = ""  # default
     pinned_tools_raw = ""  # default
@@ -277,9 +277,9 @@ def main() -> int:
             auto_backup_throttle_minutes = (
                 raw_throttle if isinstance(raw_throttle, int) else 0
             )
-            raw_retain = config.get("auto_backup_retain_per_entity", 20)
+            raw_retain = config.get("auto_backup_retain_per_entity", 100)
             auto_backup_retain_per_entity = (
-                raw_retain if isinstance(raw_retain, int) else 20
+                raw_retain if isinstance(raw_retain, int) else 100
             )
             raw_max_results = config.get("tool_search_max_results", 5)
             tool_search_max_results = (

homeassistant-addon/translations/en.yaml

@@ -42,7 +42,7 @@ configuration:
     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,
+      this cap are rotated out on each successful capture. Default 100,
       range 1–10000.
   verify_ssl:
     name: Verify TLS certificate

src/ha_mcp/backup_manager.py

@@ -211,7 +211,9 @@ def throttle_seconds(self) -> int:
 
     @property
     def retain_per_entity(self) -> int:
-        return max(1, int(getattr(self._settings, "auto_backup_retain_per_entity", 20)))
+        return max(
+            1, int(getattr(self._settings, "auto_backup_retain_per_entity", 100))
+        )
 
     # ----- handler registration ------------------------------------------
 

src/ha_mcp/config.py

@@ -168,7 +168,7 @@ class Settings(BaseSettings):
     # Max snapshots kept per entity. Older snapshots beyond this cap
     # are rotated out on each successful capture.
     auto_backup_retain_per_entity: int = Field(
-        20, ge=1, le=10_000, alias="AUTO_BACKUP_RETAIN_PER_ENTITY"
+        100, ge=1, le=10_000, alias="AUTO_BACKUP_RETAIN_PER_ENTITY"
     )
 
     # Backup directory override. Empty ("") resolves at runtime to a

src/ha_mcp/tools/auto_backup.py

@@ -75,7 +75,17 @@ def automation_backup_target(kw: dict[str, Any]) -> str:
         config_id = config.get("id")
         if config_id:
             return str(config_id)
-    return _resolve_str(kw.get("identifier"))
+    identifier = _resolve_str(kw.get("identifier"))
+    # Strip the leading ``automation.`` prefix when the caller passed an
+    # entity_id form (typical for ``python_transform`` calls that don't
+    # carry a config body). Without this, snapshot files duplicate the
+    # domain segment as ``automation.automation.<slug>.<ts>.yaml`` — the
+    # body's entity_id keeps the prefix, only the filename / list key
+    # tighten up. HA's automation upsert accepts either form for the
+    # ``identifier`` param, so restore is unaffected.
+    if identifier.startswith("automation."):
+        identifier = identifier[len("automation.") :]
+    return identifier
 
 
 def with_auto_backup(

src/ha_mcp/tools/backup.py

@@ -544,6 +544,7 @@ async def restore_backup(
 _VALID_COMBOS: set[tuple[str, str]] = {
     ("snapshot", "create"),
     ("snapshot", "restore"),
+    ("edits", "create"),
     ("edits", "list"),
     ("edits", "view"),
     ("edits", "restore"),
@@ -607,6 +608,7 @@ def register_backup_tools(
 |---|---|---|
 | `snapshot` | `create` | Create a full HA tarball (config + addons, no DB by default). Heavy, seconds-long. |
 | `snapshot` | `restore` | Restore a full HA tarball. **Restarts HA.** Last-resort recovery. |
+| `edits` | `create` | On-demand snapshot of one entity (`domain` + `entity_id` required). Use before the user manually edits in the HA UI. Same handler path the decorator takes on writes; bypasses the `enable_auto_backup` toggle. |
 | `edits` | `list` | List per-entity auto-backups (lightweight). Filter by `domain` and/or `entity_id`. |
 | `edits` | `view` | Read one auto-backup file by name; returns YAML and parsed `config`. |
 | `edits` | `restore` | Re-apply one auto-backup. Creates a fresh safety snapshot first. **No HA restart.** |
@@ -624,6 +626,7 @@ def register_backup_tools(
 **Examples:**
 - Snapshot before risky op: `ha_manage_backup(scope="snapshot", action="create", name="Before_Big_Change")`
 - Restore full snapshot: `ha_manage_backup(scope="snapshot", action="restore", backup_id="dd7550ed")`
+- On-demand entity snapshot before a manual UI edit: `ha_manage_backup(scope="edits", action="create", domain="helper_input_boolean", entity_id="kitchen_lights_active")`
 - List recent auto-backups for one automation: `ha_manage_backup(scope="edits", action="list", domain="automation", entity_id="kitchen_lights")`
 - View an auto-backup: `ha_manage_backup(scope="edits", action="view", backup_name="automation.kitchen_lights.20260521_153000.yaml")`
 - Restore an auto-backup: `ha_manage_backup(scope="edits", action="restore", backup_name="automation.kitchen_lights.20260521_153000.yaml")`
@@ -729,6 +732,79 @@ async def ha_manage_backup(
         settings = get_global_settings()
         mgr = get_backup_manager(client, settings)
 
+        if action == "create":
+            # On-demand snapshot for "I'm about to edit this in the HA UI,
+            # save the current state first." Mirrors the path the
+            # ``@with_auto_backup`` decorator takes on writes — same
+            # handler registry, same throttle/rotation rules — but
+            # triggered explicitly by the caller for entities they're
+            # about to mutate outside the MCP-tool surface. Bypasses
+            # ``enable_auto_backup`` because the request is explicit.
+            dom = _require("domain", domain, scope, action)
+            eid = _require("entity_id", entity_id, scope, action)
+            if mgr._handlers.get(dom) is None:
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.VALIDATION_INVALID_PARAMETER,
+                        f"No backup handler registered for domain={dom!r}",
+                        context={"domain": dom, "entity_id": eid},
+                        suggestions=[
+                            "Supported domains: "
+                            + ", ".join(sorted(mgr._handlers.keys())),
+                        ],
+                    )
+                )
+            # ``maybe_snapshot`` returns None when ``enable_auto_backup``
+            # is off OR throttle blocks. For an explicit on-demand call,
+            # the off-state and the throttle-block are both wrong reasons
+            # to skip — temporarily flip the toggle + clear the throttle
+            # tracker entry so the capture always fires.
+            was_enabled = mgr.enabled
+            prev_ts = mgr._last_snapshot.pop(f"{dom}:{eid}", None)
+            path = None
+            try:
+                # Force-enable for this call: read the live attr, override,
+                # restore after. Settings object is shared with other
+                # callers, so the override must be tight to this scope.
+                if not was_enabled:
+                    object.__setattr__(settings, "enable_auto_backup", True)
+                path = await mgr.maybe_snapshot(
+                    dom, eid, tool_name="ha_manage_backup.edits.create"
+                )
+            finally:
+                if not was_enabled:
+                    object.__setattr__(settings, "enable_auto_backup", False)
+                if path is None and prev_ts is not None:
+                    # Restore the throttle tracker only when the capture
+                    # didn't write (e.g. entity didn't exist at fetch
+                    # time). A successful capture sets a new timestamp
+                    # already.
+                    mgr._last_snapshot[f"{dom}:{eid}"] = prev_ts
+            if path is None:
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.RESOURCE_NOT_FOUND,
+                        f"Could not snapshot {dom}:{eid} — entity not found "
+                        "or fetch returned no config",
+                        context={"domain": dom, "entity_id": eid},
+                        suggestions=[
+                            "Verify the entity exists via the matching "
+                            "ha_config_get_* tool first",
+                            "For helpers, pass domain='helper_<helper_type>' "
+                            "(e.g. 'helper_input_boolean')",
+                        ],
+                    )
+                )
+            return {
+                "success": True,
+                "data": {
+                    "backup_name": path.name,
+                    "domain": dom,
+                    "entity_id": eid,
+                    "size": path.stat().st_size,
+                },
+            }
+
         if action == "list":
             # list_snapshots does sync directory globbing + per-file stat;
             # offload to the executor so it doesn't block the event loop

tests/src/e2e/workflows/auto_backup/test_capture_and_restore.py

@@ -131,14 +131,21 @@ async def test_rejects_invalid_combo(self, mcp_client) -> None:
         suggestions = error.get("suggestions", []) if isinstance(error, dict) else []
         assert any("Valid combinations" in s for s in suggestions)
 
-    async def test_edits_create_rejected(self, mcp_client) -> None:
-        # (edits, create) is not valid — captures happen automatically via the decorator.
+    async def test_edits_create_requires_domain_and_entity_id(self, mcp_client) -> None:
+        # (edits, create) is the on-demand-snapshot combo — needs both
+        # ``domain`` and ``entity_id`` to know what to capture. The
+        # bare call must fail with a structured validation error rather
+        # than silently routing through the decorator's auto-on-write
+        # path (which only fires on actual writes).
         result = await safe_call_tool(
             mcp_client,
             "ha_manage_backup",
             {"scope": "edits", "action": "create"},
         )
         assert result.get("success") is False
+        error = result.get("error", {})
+        msg = error.get("message", "") if isinstance(error, dict) else ""
+        assert "domain" in msg or "entity_id" in msg
 
     async def test_snapshot_restore_requires_backup_id(self, mcp_client) -> None:
         # Validation should mention that backup_id is missing — not silently dispatch.
@@ -179,6 +186,115 @@ async def test_list_without_filter_returns_state(
         assert "retain_per_entity" in data
 
 
+# ---------------------------------------------------------------- on-demand snapshot
+
+
+@pytest.mark.automation
+@pytest.mark.cleanup
+@pytest.mark.external_only
+class TestEditsCreateOnDemandSnapshot:
+    """``ha_manage_backup(scope='edits', action='create', ...)`` — captures
+    a snapshot of the named entity on demand. Use case: "I'm about to
+    edit this in the HA UI; snapshot it first." Distinct from the
+    auto-on-write path the ``@with_auto_backup`` decorator drives.
+
+    Exercises against an automation entity to share the existing
+    automation create+edit fixture; the underlying maybe_snapshot path
+    is domain-agnostic, so coverage of one domain is sufficient to
+    pin the routing.
+    """
+
+    async def test_on_demand_snapshot_round_trip(
+        self, mcp_client, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        _enable_auto_backup(monkeypatch)
+
+        suffix = uuid.uuid4().hex[:8]
+        identifier = f"e2e_ondemand_{suffix}"
+        # Create an automation to snapshot. We do NOT edit it — the
+        # on-demand snapshot path must work without a write triggering
+        # the decorator.
+        original = {
+            "alias": f"E2E On-Demand Original {suffix}",
+            "trigger": [{"platform": "time", "at": "12:00:00"}],
+            "action": [{"service": "homeassistant.no_op"}],
+        }
+        create = await safe_call_tool(
+            mcp_client,
+            "ha_config_set_automation",
+            {"config": original, "identifier": identifier},
+        )
+        assert create.get("success") is not False
+
+        # On-demand snapshot.
+        snap = await safe_call_tool(
+            mcp_client,
+            "ha_manage_backup",
+            {
+                "scope": "edits",
+                "action": "create",
+                "domain": "automation",
+                "entity_id": identifier,
+            },
+        )
+        assert snap.get("success") is True, f"on-demand snapshot failed: {snap}"
+        data = snap.get("data", {})
+        backup_name = data.get("backup_name")
+        assert backup_name, f"backup_name missing from response: {snap}"
+        assert data.get("domain") == "automation"
+        assert data.get("entity_id") == identifier
+        assert data.get("size", 0) > 0
+
+        # The snapshot must also show up in the list query.
+        listing = await safe_call_tool(
+            mcp_client,
+            "ha_manage_backup",
+            {
+                "scope": "edits",
+                "action": "list",
+                "domain": "automation",
+                "entity_id": identifier,
+            },
+        )
+        assert listing.get("success") is True
+        entries = listing.get("data", {}).get("backups", [])
+        assert any(b["name"] == backup_name for b in entries), (
+            f"on-demand snapshot {backup_name!r} not in list: "
+            f"{[b['name'] for b in entries]}"
+        )
+
+        # Cleanup: delete the snapshot + remove the automation.
+        await safe_call_tool(
+            mcp_client,
+            "ha_manage_backup",
+            {"scope": "edits", "action": "delete", "backup_name": backup_name},
+        )
+        await safe_call_tool(
+            mcp_client,
+            "ha_config_remove_automation",
+            {"identifier": identifier},
+        )
+
+    async def test_on_demand_snapshot_unknown_domain_rejected(
+        self, mcp_client, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        _enable_auto_backup(monkeypatch)
+        result = await safe_call_tool(
+            mcp_client,
+            "ha_manage_backup",
+            {
+                "scope": "edits",
+                "action": "create",
+                "domain": "not_a_real_domain",
+                "entity_id": "anything",
+            },
+        )
+        assert result.get("success") is False
+        error = result.get("error", {})
+        msg = error.get("message", "") if isinstance(error, dict) else ""
+        assert "handler" in msg.lower() or "domain" in msg.lower()
+
+
 # ---------------------------------------------------------------- automation lane