fix(flows): point the empty-forms error at step_values step ids

step_values is a directive, not a field, so a config of nothing but a
step_values entry naming a step the flow never presents tripped the
empty-forms guard and was told to check its field names. The likely
mistake there is the step_id. Guidance now branches on what was actually
supplied.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012d29UJTiH4Uy2Pm37SBPtr

Author: kingpanther13

src/ha_mcp/tools/config_entry_flow_walker.py

@@ -19,6 +19,7 @@
 from ..redaction import redact_flow_schema, redaction_enabled
 from .config_entry_flow_form import (
     _MENU_SELECTION_KEYS,
+    _PER_STEP_VALUES_KEY,
     _auto_confirm_form_payload,
     _handle_form_step,
     _ReuseState,
@@ -493,6 +494,27 @@ def _raise_reconfigure_no_answer(
     )
 
 
+def _empty_forms_suggestions(supplied_keys: list[str]) -> list[str]:
+    """Guidance for a flow that consumed none of the caller's keys.
+
+    ``step_values`` is a directive rather than a field, so "check the field
+    names" is the wrong advice when it is what the caller supplied: the likely
+    mistake is a step_id the flow never presents, not a misspelled field.
+    """
+    if _PER_STEP_VALUES_KEY in supplied_keys:
+        return [
+            "Check each step_values step_id against the steps this flow "
+            "actually presents — a step_id the flow never reaches applies "
+            "nothing — and check the field names inside each entry with "
+            "ha_get_integration(entry_id=..., include_schema=True).",
+        ]
+    return [
+        "Check the field names against the flow's data_schema — "
+        "ha_get_integration(entry_id=..., include_schema=True) "
+        "shows the accepted fields — then retry with corrected keys.",
+    ]
+
+
 def _finish_flow_entry(
     flow_id: str,
     current_step: dict[str, Any],
@@ -521,12 +543,7 @@ def _finish_flow_entry(
                 "Flow completed without consuming any of the supplied "
                 "config keys — every form step was submitted empty, so "
                 "the flow saved its defaults, not your values",
-                suggestions=[
-                    "Check the field names against the flow's data_schema — "
-                    "ha_get_integration(entry_id=..., include_schema=True) "
-                    "shows the accepted fields — then retry with corrected "
-                    "keys.",
-                ],
+                suggestions=_empty_forms_suggestions(supplied_keys),
                 context={
                     "flow_id": flow_id,
                     "supplied_keys": supplied_keys,

tests/src/unit/test_flow_options_preserve.py

@@ -1041,6 +1041,52 @@ def test_a_schemaless_step_does_not_submit_the_reserved_key(self) -> None:
         assert payload == {"host": "10.0.0.5"}
 
 
+class TestEmptyFormsGuidance:
+    """The empty-forms error must point at the right mistake."""
+
+    async def test_a_step_values_only_config_is_told_to_check_step_ids(self) -> None:
+        """step_values is a directive, so "check the field names" misleads.
+
+        A config of nothing but step_values that names a step the flow never
+        presents consumes no field key and trips the empty-forms guard. The
+        likely mistake there is the step_id, not a misspelled field.
+        """
+        submit_fn = AsyncMock(
+            side_effect=[{"type": "create_entry", "result": {"entry_id": "e"}}]
+        )
+
+        with pytest.raises(ToolError) as exc_info:
+            await _handle_flow_steps(
+                client=None,
+                flow_id="flow-2254",
+                initial_step=_workday_options_step(),
+                config={"step_values": {"never_shown": {"days_offset": 3}}},
+                submit_fn=submit_fn,
+                keep_current_values=True,
+            )
+
+        message = str(exc_info.value)
+        assert "step_values step_id" in message
+        assert "a step_id the flow never reaches" in message
+
+    async def test_a_plain_typo_still_gets_the_field_name_guidance(self) -> None:
+        submit_fn = AsyncMock(
+            side_effect=[{"type": "create_entry", "result": {"entry_id": "e"}}]
+        )
+
+        with pytest.raises(ToolError) as exc_info:
+            await _handle_flow_steps(
+                client=None,
+                flow_id="flow-2254",
+                initial_step=_workday_options_step(),
+                config={"days_ofset": 3},
+                submit_fn=submit_fn,
+                keep_current_values=True,
+            )
+
+        assert "Check the field names" in str(exc_info.value)
+
+
 class TestBackfillIsNotCallerConsumption:
     """Schema data must not make a config of typos look partially applied."""