Document next_flow in async_create_entry in RepairsFlow

docs/core/platform/repairs.md

@@ -59,8 +59,7 @@ from __future__ import annotations
 
 import voluptuous as vol
 
-from homeassistant import data_entry_flow
-from homeassistant.components.repairs import ConfirmRepairFlow, RepairsFlow
+from homeassistant.components.repairs import RepairsFlow, RepairsFlowResult
 from homeassistant.core import HomeAssistant
 
 
@@ -69,14 +68,14 @@ class Issue1RepairFlow(RepairsFlow):
 
     async def async_step_init(
         self, user_input: dict[str, str] | None = None
-    ) -> data_entry_flow.FlowResult:
+    ) -> RepairsFlowResult:
         """Handle the first step of a fix flow."""
 
         return await (self.async_step_confirm())
 
     async def async_step_confirm(
         self, user_input: dict[str, str] | None = None
-    ) -> data_entry_flow.FlowResult:
+    ) -> RepairsFlowResult:
         """Handle the confirm step of a fix flow."""
         if user_input is not None:
             return self.async_create_entry(title="", data={})
@@ -94,6 +93,79 @@ async def async_create_fix_flow(
         return Issue1RepairFlow()
 ```
 
+### Issues that can be repaired via entry/options/subentry reconfiguration
+
+Repair flows can forward issue fixes to config, options, or subentry flows:
+
+```python
+import voluptuous as vol
+
+from homeassistant import data_entry_flow
+from homeassistant.components.repairs import RepairsFlow, RepairsFlowResult
+from homeassistant.config_entries import (
+    FlowType,
+    SOURCE_RECONFIGURE,
+    SubentryFlowContext,
+    SubentryFlowResult,
+)
+from homeassistant.core import HomeAssistant
+
+class Issue1RepairFlow(RepairsFlow):
+    """Handler for an issue fixing flow."""
+
+    async def async_step_init(
+        self, user_input: dict[str, str] | None = None
+    ) -> RepairsFlowResult:
+        return await (self.async_step_confirm())
+
+    async def async_step_confirm(
+        self, user_input: dict[str, str] | None = None
+    ) -> RepairsFlowResult:
+        """Handle the confirm step of a fix flow."""
+        if user_input is not None:
+            next_flow: SubentryFlowResult = (
+                await self.hass.config_entries.subentries.async_init(
+                    (self.data["entry_id"], "subentry_type"),
+                    context=SubentryFlowContext(
+                        subentry_id=self.data["subentry_id"],
+                        source=SOURCE_RECONFIGURE,
+                    ),
+                )
+            )
+            return self.async_create_entry(
+                title="", data={},
+                next_flow=(
+                    FlowType.CONFIG_SUBENTRIES_FLOW,
+                    next_flow["flow_id"]
+                )
+            )
+
+        return self.async_show_form(
+            step_id="confirm",
+            data_schema=vol.Schema({})
+        )
+```
+
+`context = {"source": SOURCE_RECONFIGURE}` is the only context source supported for `next_flow` issue repair flows for `FlowType.CONFIG_FLOW` and `FlowType.CONFIG_SUBENTRIES_FLOW`.  Issue repairs should not be directing to new config/options/subentry flows (which cannot need a repair if they do not exist).
+
+When using `next_flow` in `async_create_entry` the issue lifecycle is altered, and the issue will remain registered until manually removed by the integration. See [Repair flows using `next_flow`](#repair-flows-using-next_flow) for more information and an example.
+
+#### Example options flow
+
+```python
+next_flow: ConfigFlowResult = (
+    await self.hass.config_entries.options.async_init(
+        self.data["entry_id]
+    )
+)
+return self.async_create_entry(
+    title="", data={},
+    next_flow=(
+        FlowType.OPTIONS_FLOW,
+        next_flow["flow_id"]
+    )
+)
+```
 
 ## Issue life cycle
 
@@ -118,4 +190,25 @@ from homeassistant.helpers import issue_registry as ir
 
 ir.async_delete_issue(hass, DOMAIN, "manual_migration")
 ```
+### Repair flows using `next_flow`
+
+Integration repair flows using `next_flow` will have to delete an issue once the repair is completed as the `RepairFlow.async_create_entry` will not remove the issue from the registry when `next_flow` is specified as an argument. Issues can be deleted in `config_flow.py` or in `async_setup_entry`: 
 
+```python
+async def async_step_reconfigure(
+    self, user_input: dict[str, Any] | None = None
+) -> ConfigFlowResult:
+    """Config entry reconfigure
+    if user_input is not None:
+        # Verify user_input is valid
+        if success:
+            ir.async_delete_issue(
+                self.hass,
+                DOMAIN,
+                "url_invalid",
+            )
+            return self.async_update_reload_and_abort(
+                self._get_reconfigure_entry(),
+                data=data,
+            )
+```