refactor: address PR #1397 KP13 second-pass review (D4 available_*_ids parity)

Extend the #1297 RESOURCE_NOT_FOUND classifier audit to the three remaining
sites flagged in KP13's second-pass review — same audit family as the labels /
categories / zones / devices sibling sites already covered in this PR:

- ``ha_config_delete_dashboard`` (tools_config_dashboards.py): reuse the
  dashboard list returned by ``_resolve_dashboard`` (previously discarded
  via ``_``) and splice first-10 ``url_path`` entries into
  ``available_dashboard_ids``.

- ``_get_automation_config_internal`` (tools_config_automations.py): new
  central not-found raise — catches ``HomeAssistantAPIError(status_code=404)``
  from the REST client and emits ``RESOURCE_NOT_FOUND`` with
  ``available_automation_ids`` sourced from a best-effort
  ``config/entity_registry/list`` filtered by ``automation.`` prefix.
  Other ``HomeAssistantAPIError`` instances propagate unchanged.

- ``_fetch_script_config_envelope`` (tools_config_scripts.py): new private
  helper mirroring the automations shape, used by both ``ha_config_get_script``
  and ``_get_script_config_internal`` to centralize the 404→RESOURCE_NOT_FOUND
  translation. ``available_script_ids`` populated the same way.

Both list-fetch helpers (``_list_automation_entity_ids`` /
``_list_script_entity_ids``) are best-effort: a registry-list failure
yields an empty list rather than masking the 404 behind a registry error.

5 new regression tests in ``tests/src/unit/test_error_code_consistency_1297.py``
pin the new shape at sibling depth — error code + list-tool suggestion +
``available_*_ids`` payload, plus the empty-list-on-registry-failure
fallback for the automations and scripts paths.

Author: Patch76

src/ha_mcp/tools/tools_config_automations.py

@@ -13,6 +13,7 @@
 from pydantic import Field
 
 from ..client.rest_client import (
+    HomeAssistantAPIError,
     HomeAssistantAuthError,
     HomeAssistantConnectionError,
 )
@@ -838,15 +839,68 @@ async def ha_config_set_automation(
                 suggestions=suggestions,
             )
 
+    async def _list_automation_entity_ids(self) -> list[str]:
+        """Best-effort list of automation entity_ids from the entity registry.
+
+        Used to populate ``available_automation_ids`` in RESOURCE_NOT_FOUND
+        error context. Returns an empty list on any failure — caller treats
+        absence as "no IDs to report" rather than failing the structured
+        error raise.
+        """
+        try:
+            result = await self._client.send_websocket_message(
+                {"type": "config/entity_registry/list"}
+            )
+        except Exception as e:
+            logger.debug(
+                "Failed to list automation entity_ids from registry: %s", e
+            )
+            return []
+        entries = result.get("result", []) if isinstance(result, dict) else result
+        if not isinstance(entries, list):
+            return []
+        return [
+            entry["entity_id"]
+            for entry in entries
+            if isinstance(entry, dict)
+            and isinstance(entry.get("entity_id"), str)
+            and entry["entity_id"].startswith("automation.")
+        ]
+
     async def _get_automation_config_internal(
         self, identifier: str
     ) -> tuple[dict[str, Any], str]:
         """Fetch and normalize automation config without logging or category injection.
 
         Returns (normalized_config, config_hash) tuple.
         Used internally by _fetch_and_verify_hash and ha_config_get_automation.
+
+        Raises a structured ``RESOURCE_NOT_FOUND`` ToolError when the REST
+        client returns 404, populating ``available_automation_ids`` so
+        agents can recover without a separate search round-trip. Other
+        ``HomeAssistantAPIError`` instances propagate unchanged to caller
+        exception handlers (``exception_to_structured_error`` route).
         """
-        config_result = await self._client.get_automation_config(identifier)
+        try:
+            config_result = await self._client.get_automation_config(identifier)
+        except HomeAssistantAPIError as e:
+            if e.status_code == 404:
+                available_ids = await self._list_automation_entity_ids()
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.RESOURCE_NOT_FOUND,
+                        f"Automation not found: {identifier}",
+                        context={
+                            "automation_id": identifier,
+                            "available_automation_ids": available_ids[:10],
+                        },
+                        suggestions=[
+                            "Use ha_search_entities(domain_filter='automation') to find existing automations",
+                            "Verify the entity_id or unique_id is correct",
+                        ],
+                    )
+                )
+            raise
         normalized_config = _normalize_config_for_roundtrip(config_result)
         config_hash_value = compute_config_hash(normalized_config)
         return normalized_config, config_hash_value

src/ha_mcp/tools/tools_config_dashboards.py

@@ -1530,8 +1530,13 @@ async def ha_config_delete_dashboard(
                 ],
                 context={"action": "delete"},
             )
-            resolved, _ = await _resolve_dashboard(client, url_path)
+            resolved, dashboards = await _resolve_dashboard(client, url_path)
             if resolved is None:
+                available_ids = [
+                    d.get("url_path")
+                    for d in (dashboards or [])[:10]
+                    if d.get("url_path")
+                ]
                 raise_tool_error(
                     create_error_response(
                         ErrorCode.RESOURCE_NOT_FOUND,
@@ -1541,7 +1546,11 @@ async def ha_config_delete_dashboard(
                             "Use ha_config_get_dashboard(list_only=True) to see available dashboards",
                             "YAML-mode and default dashboards are not deletable via this tool",
                         ],
-                        context={"action": "delete", "url_path": url_path},
+                        context={
+                            "action": "delete",
+                            "url_path": url_path,
+                            "available_dashboard_ids": available_ids,
+                        },
                     )
                 )
             resolved_id = resolved["id"]

src/ha_mcp/tools/tools_config_scripts.py

@@ -13,6 +13,7 @@
 from pydantic import Field
 
 from ..client.rest_client import (
+    HomeAssistantAPIError,
     HomeAssistantAuthError,
     HomeAssistantConnectionError,
 )
@@ -122,7 +123,7 @@ async def ha_config_get_script(
                     "Use ha_search_entities(domain_filter='script') to list scripts",
                 ],
             )
-            config_result = await self._client.get_script_config(script_id)
+            config_result = await self._fetch_script_config_envelope(script_id)
             # Extract actual script config body and compute hash before category injection
             actual_config = config_result.get("config", config_result)
             config_hash_value = compute_config_hash(actual_config)
@@ -170,6 +171,65 @@ async def ha_config_get_script(
                 ],
             )
 
+    async def _list_script_entity_ids(self) -> list[str]:
+        """Best-effort list of script entity_ids from the entity registry.
+
+        Used to populate ``available_script_ids`` in RESOURCE_NOT_FOUND
+        error context. Returns an empty list on any failure — caller
+        treats absence as "no IDs to report" rather than failing the
+        structured error raise.
+        """
+        try:
+            result = await self._client.send_websocket_message(
+                {"type": "config/entity_registry/list"}
+            )
+        except Exception as e:
+            logger.debug("Failed to list script entity_ids from registry: %s", e)
+            return []
+        entries = result.get("result", []) if isinstance(result, dict) else result
+        if not isinstance(entries, list):
+            return []
+        return [
+            entry["entity_id"]
+            for entry in entries
+            if isinstance(entry, dict)
+            and isinstance(entry.get("entity_id"), str)
+            and entry["entity_id"].startswith("script.")
+        ]
+
+    async def _fetch_script_config_envelope(self, script_id: str) -> dict[str, Any]:
+        """Fetch the raw REST envelope, mapping 404 to RESOURCE_NOT_FOUND.
+
+        Returns the dict envelope from ``rest_client.get_script_config``
+        (``success``/``script_id``/``config`` keys). Raises a structured
+        ``RESOURCE_NOT_FOUND`` ToolError when the REST client returns 404,
+        populating ``available_script_ids`` so agents can recover without
+        a separate search round-trip. Other ``HomeAssistantAPIError``
+        instances propagate unchanged to caller exception handlers.
+        """
+        try:
+            return cast(
+                dict[str, Any], await self._client.get_script_config(script_id)
+            )
+        except HomeAssistantAPIError as e:
+            if e.status_code == 404:
+                available_ids = await self._list_script_entity_ids()
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.RESOURCE_NOT_FOUND,
+                        f"Script not found: {script_id}",
+                        context={
+                            "script_id": script_id,
+                            "available_script_ids": available_ids[:10],
+                        },
+                        suggestions=[
+                            "Use ha_search_entities(domain_filter='script') to find existing scripts",
+                            "Verify the script identifier is correct",
+                        ],
+                    )
+                )
+            raise
+
     async def _get_script_config_internal(
         self, script_id: str
     ) -> tuple[dict[str, Any], str]:
@@ -178,8 +238,11 @@ async def _get_script_config_internal(
         Returns (actual_config, config_hash) tuple where actual_config is
         the inner script body (not the REST wrapper).
         Used internally by _fetch_and_verify_hash and ha_config_get_script.
+
+        404 responses from the REST client are mapped to a structured
+        ``RESOURCE_NOT_FOUND`` ToolError via ``_fetch_script_config_envelope``.
         """
-        config_result = await self._client.get_script_config(script_id)
+        config_result = await self._fetch_script_config_envelope(script_id)
         actual_config = config_result.get("config", config_result)
         config_hash_value = compute_config_hash(actual_config)
         return actual_config, config_hash_value