Wave 9 #122.d.iv — Phase 6 Tailscale wizard: mDNS roamcore.local fallback (Gate E 'local survives Tailscale failure')

[bernardc6]

Summary

Wave 9 #122.d.iv — Phase 6 Tailscale wizard sub-slice: mDNS roamcore.local fallback so local survives Tailscale failure (Gate E verbatim).

When Tailscale is down, the operator can still reach their dashboard from their phone on the same WiFi as the Hub — at roamcore.local, no IP needed.

What's new

• NEW package homeassistant/packages/roamcore_local_mdns_fallback.yaml (separate from roamcore_remote_access_setup.yaml to avoid file-scope conflicts with Wave 9 #119b — Phase 2 canonical vehicle model mapping layer #122.a/b/c/d.i):

  • input_boolean.rc_local_mdns_fallback_enabled (default ON, no operator input)
  • input_text.rc_local_mdns_hostname (default roamcore, operator-editable)
  • input_button.rc_local_mdns_retest
  • shell_command.rc_local_mdns_probe (5s timeout via avahi-resolve / getent)
  • binary_sensor.rc_local_mdns_resolvable (UNKNOWN until first probe — doesn't pretend fallback is up)
  • sensor.rc_local_mdns_resolved_ip + sensor.rc_local_mdns_status (3 plain-English states)
  • 3 §8 MANDATORY AUTOMATIONS:
    • §8.M.1 rc_local_mdns_register_on_start — registers hostname on HA startup
    • §8.M.2 rc_local_mdns_probe_periodic — probes every 60s
    • §8.M.3 rc_local_mdns_fallback_tile_surfacing — surfaces fallback notification on retest

• NEW pytest rig homeassistant/packages/tests/test_local_mdns_fallback.py — 32 tests covering YAML parse + every required helper + every §8 automation contract + hostname operator-editable + status template covers all 4 (enabled × resolvable × ip) combos + status copy has no operator jargon + idempotency + single shell_command (no duplicate mDNS service) + rc-entity-naming compliance + no secrets/hard-coded IPs leaked + IKEA doc 5-step shape + IKEA doc translation table + no SUPERSEDED banner.

• NEW bash smoke scripts/checks/local-mdns-fallback-smoke.sh — 13 assertions: file presence + YAML parse + rc-naming + helpers/automations/templates present + status coverage + no jargon + secrets-leak + idempotency + IKEA doc 5-step + §8.M.3 wiring + pytest rig green.

• NEW IKEA doc docs/setup/local-access-fallback.md — 5 numbered sections (What this is / What you see / What you do / What to do if it goes wrong / Useful links) + operator→vanlifer translation table. Opens with one plain-English sentence.

• MOD connections/remote-access/connection.yml — +35 lines: local_mdns_fallback entry under wizard.setup_paths as a separate entry from the four remote paths (A/B/C/D), explicitly documented as the Gate E safety net that is always-on by default.

• MOD scripts/check.sh — +1 line wiring scripts/checks/local-mdns-fallback-smoke.sh into the core-only chain.

Tier discipline

Tier-b recipe over the HA Core zeroconf integration (since 2022.x — exposes an mDNS service registration service that this slice consumes) + a shell_command fallback to avahi-set-hostname for Hub installs where the upstream zeroconf integration isn't loaded yet. HAOS ships an avahi-based mDNS responder by default; this slice wires the canonical RoamCore hostname (roamcore.local) into the dashboard fallback path.

Verification

• bash scripts/check.sh --core-only → exit 0 (GREEN)
• bash scripts/checks/local-mdns-fallback-smoke.sh → 13/13 PASS
• python3 -m pytest homeassistant/packages/tests/test_local_mdns_fallback.py -v → 32/32 PASS

Doctrine / GOLDEN.md alignment

• Product principle 1 (novice-first UX): the IKEA doc opens with one plain-English sentence; the dashboard status copy is one of 3 plain-English states.
• Product principle 2 (mission-critical connectivity): this slice IS the safety net for Gate E — keeps the dashboard reachable when the primary remote-access path is down.
• Engineering principle 1 (customer-facing repo): user-facing doc lives in docs/setup/, NOT memory/ or Cron-handoff/.
• Engineering principle 5 (do not touch vmbr0): no networking change at all — pure repo-local code that orchestrates the upstream zeroconf integration.
• Engineering principle 7 (rc-entity-naming): every entity_id starts with rc_local_mdns_; tested explicitly.
• Anti-patterns avoided:
  • No secrets committed (tskey- / ts-auth- / hard-coded IPs all asserted absent).
  • No wide PR (additive + tiny, not a rewrite).
  • No "RoamCore ships a native mDNS engine" tier-claim stub — the YAML honestly calls itself a tier-b recipe over the upstream zeroconf integration.
  • No SUPERSEDED banner / no Cron-handoff / no internal jargon in the user-facing tree.

Rollback

Revert this commit + any follow-up. The slice is purely additive (new package + new files + tiny additive edits to connection.yml and check.sh); no destructive ops, no Proxmox/HA/OpenWrt/vmbr0 touched.