Wave 9 #108 — Starlink 3-path wizard

[bernardc6]

Rebased onto main d3d596b

Rebased onto main d3d596b to strip the pre-existing afb743a (Wave 8 #315 OpenWrt controls = PR #82, separate work item, still OPEN).

Context

Bernard chat #7563-7574 priority 4: Starlink integration must be perfect, with extremely clear and simple instructions for using Starlink Mini as the sole router, plus a setup flow that asks the user which topology they want (Mini-only / separate router / VM router inside the VP2430) and auto-sets up the chosen path.

Changes

• connections/starlink/connection.yml: wizard now exposes setup_paths with 3 entries (starlink_mini_only / separate_router / vp2430_vm_router); each carries connection_kind, estimated_time, requires_reboot, setup_notes. New tier_a_promotion_candidate: starlink_mini_only marker. install.config_flow flipped to true (wizard exposes a Starlink step).
• connections/starlink/init.py: now exports apply_setup_path() (the wizard entry point) + describe_setup_paths() + the 3 PATH_* constants. Path A wires the input_text + REST + 3 template sensors (reachable, signal_pct, sleep_state). Path B validates the user's smart plug entity (exposed + controllable) + creates switch.rc_net_starlink_plug. Path C validates the OpenWrt API URL + bearer token + creates the REST chain. 3×-retry-with-backoff HTTP probe (10s window). Plain-English errors throughout. Idempotent.
• connections/starlink/docs/recipe.md: restructured around a "Choose your setup" section at the top with a decision tree + table of the 3 paths. The legacy Path A / Path B sections preserved (now under §A / §B / §C headings). Errors section expanded with plain-English "what to do" per error.
• connections/starlink/tests/test_connection_yml.py: 14 tests (was 6). New tests: 3-path wizard setup_paths structure, Path A no inputs + side_effects check, Path B requires plug entity, Path C requires openwrt api url + token, tier_a_promotion_candidate is Path A, absence-of-required-config failure case, recipe documents all 3 paths, init exports wizard-wiring helpers.
• docs/catalog/connectivity/starlink.md: rewritten as 5-step IKEA howto (Pick your setup → Answer 2-3 questions → RoamCore does the rest → Tiles appear → Done). Includes a "Common questions" Q&A covering which path to pick, switching paths, the unreachable error, credentials privacy, mid-setup cancellation safety.
• homeassistant/custom_components/roamcore/config_flow.py: added async_step_starlink that renders the 3 paths as radio buttons + collects path-specific input (Path A: nothing; Path B: plug entity id; Path C: OpenWrt API URL + token) + calls connections.starlink.apply_setup_path(). Errors surface as form errors (no exceptions bubble up). Lazy import of the starlink module so the rest of the config_flow works without the connection folder being installed.

Verification

• python3 -m pytest connections/starlink/tests/test_connection_yml.py -v: 14 passed in 0.09s
• bash scripts/check.sh --core-only: green (all 33 connection tests + HA-beta smoke pass)
• YAML / Python parses clean
• Path A idempotent: re-running apply_setup_path with the same args is a no-op
• Path B validates plug entity is exposed + controllable BEFORE writing anything
• Path C verifies OpenWrt API reachable BEFORE writing anything
• Plain-English errors verified by string-matching the format strings (ERROR_STARLINK_UNREACHABLE, ERROR_PLUG_NOT_EXPOSED, ERROR_PLUG_NOT_CONTROLLABLE, ERROR_OPENWRT_UNREACHABLE, ERROR_PATH_REQUIRES_INPUT)

Rollback

git revert HEAD (one commit, 6 files). No schema migrations; no helper state outside HA's normal registry; the in-package YAML + REST sensors Path A wires are guarded by the wizard's verification step.

Tier discipline

• Path A is the tier-a promotion CANDIDATE (manifest declares tier_a_promotion_candidate: starlink_mini_only). Tier stays b until a Starlink test fixture lands.
• Paths B and C stay tier-b (recipe, depend on operator wiring).
• install.config_flow flipped to true (wizard exists); install.hacs stays false (no HACS integration of our own).

Diff: 6 files changed, 1793 insertions(+), 243 deletions(-)