Wave 3 #52: Connection: Approach lights (welcome-home exterior + underbody lighting) (tier-b) — vendor-neutral light/switch scene + camera-override soft-deterrent

[bernardc6]

Promote the legacy tier-c docs/catalog/lighting/approach-and-underbody-lights.md spec (24-line placeholder, no recipe + no contract + no automations) into a tier-b recipe connection at connections/approach-lights/. Follows the same pattern proven by the Wave 3 #35 Frigate / #42 bluetooth-wifi-presence / #44 heated-floors / #45 smoke-co-gas / #50 water-tanks / #51 electronic-valves slices.

What this slice ships

Three install paths (operator picks based on hardware ownership + vendor preference):

• Path A — Smart switches / smart bulbs (recommended for operators with existing smart lighting). Vendor: Shelly 1 / Shelly Plus 1 / Zooz ZEN17 / Aeotec Nano Switch (A1 wired switches) + Philips Hue / LIFX / IKEA TRÅDFRI (A2 smart bulbs) + generic-Zigbee / generic-Z-Wave / Tuya (A3 vendor-neutral). The vendor integration exposes light.* or switch.* entities; the recipe maps each via HA core template: light wrappers or HA core light: group (since 2022.x).
• Path B — Generic relay + HA template light (no smart bulb; just a 12 V underbody LED strip + a relay-driven entry light). Vendor: Shelly 1 / Shelly Plus 1 / Zooz ZEN17 / Aeotec Nano Switch (HA core, GUI flow since 2022.x) wired into the 12 V / 24 V LED driver; HA core template: light wraps the relay into a virtual light.entry + light.underbody + light.soft_interior.
• Path C — All-in-one smart scene controller (Hue Bridge / Lutron Caséta / IKEA TRÅDFRI / Bond Home for ceiling-fan-light combos). Vendor: any hub that exposes all lights as light.*; the recipe walks the operator through grouping the approach lights into a light.approach_scene group entity (HA light: group domain since 2022.x).

All three paths land on the same 12 rc_lighting_* contract tiles (per docs/reference/rc-entity-naming.md §lighting subsystem — NEW — added by this slice, mirroring how media was added by Music Assistant Wave 3 #41 + how presence was added by bluetooth-wifi-presence Wave 3 #42 + how water was added by water-tanks Wave 3 #50 + how bed_lift was added by happijac Wave 3 #43 + how hvac was added by heated-floors Wave 3 #44 + how safety was added by smoke-co-gas-sensors Wave 3 #45):

• binary_sensor.rc_lighting_approach_active (approach scene running)
• binary_sensor.rc_lighting_approach_available (meta-gate)
• binary_sensor.rc_lighting_underbody_state (per-zone state mirror)
• binary_sensor.rc_lighting_entry_state (per-zone state mirror)
• binary_sensor.rc_lighting_soft_interior_state (per-zone state mirror)
• sensor.rc_lighting_approach_minutes_remaining (countdown remaining)
• sensor.rc_lighting_last_approach_trigger_minutes_ago (last-triggered badge)
• binary_sensor.rc_lighting_dark_outside (sun.sun OR sensor.rc_weather_light_lux < 50 lx)
• select.rc_lighting_approach_mode (auto / dark_only / stealth_only / disabled)
• number.rc_lighting_approach_duration_min (default 2; range 1–10)
• button.rc_lighting_run_approach_now (HA button: integration since 2023.x)
• binary_sensor.rc_lighting_camera_override (TRUE for 30 seconds on Frigate person detection in entry zone after dark)

The 5 §7 automations (MANDATORY before first use):

1. First-arrival-after-dark — trigger when binary_sensor.rc_presence_all_away (from bluetooth-wifi-presence Wave 3 Wave 3 #38: Connection: NAS (tier-b) — Synology / QNAP / SMB local storage #42) transitions TRUE → FALSE AND binary_sensor.rc_lighting_dark_outside is TRUE AND select.rc_lighting_approach_mode != disabled AND select.rc_mode (from mode/automation-builder) != stealth.
2. Run-on-demand — trigger on button.rc_lighting_run_approach_now press.
3. Auto-stop-after-N-min — trigger on the HA timer: N-minute countdown fire; fire light.turn_off for each approach light.
4. Camera-override-on-frigate-person — trigger on a Frigate person detection in the entry zone after dark (cross-references Frigate Wave 3 Wave 2 #10: PWA scaffold (real install + offline detection + push notifications) #35); fire binary_sensor.rc_lighting_camera_override TRUE for 30 seconds + set underbody lights to full brightness.
5. Stealth-mode-suppression — when select.rc_mode == stealth, suppress ALL approach lighting (don't fire the §7.1 first-arrival-after-dark automation).

New lighting subsystem in docs/reference/rc-entity-naming.md (one-line addition: lighting — exterior + interior lights + lighting scenes + lighting mode overrides; vendor-neutral rc_lighting_* ids).

Cross-references

• Bluetooth / Wi-Fi presence Wave 3 Wave 3 #38: Connection: NAS (tier-b) — Synology / QNAP / SMB local storage #42 — the §7.1 first-arrival-after-dark trigger depends on binary_sensor.rc_presence_all_away + binary_sensor.rc_presence_anyone_home. Connection: connections/bluetooth-wifi-presence/.
• Mode / automation-builder — the §7.5 stealth-mode-suppression automation uses select.rc_mode. Connection: connections/mode-automation-builder/.
• Frigate Wave 3 Wave 2 #10: PWA scaffold (real install + offline detection + push notifications) #35 — the §7.4 camera-override-on-frigate-person automation depends on binary_sensor.<camera>_<zone>_person_detected. Connection: connections/frigate/.
• Time / weather contract — the §6 dark-outside signal is wired via sun.sun (HA core, GUI flow since 2022.x) OR sensor.rc_weather_light_lux (from homeassistant/packages/roamcore_weather_time.yaml).
• Motion-based lighting Wave 3 Wave 3 #50: Connection: Water tanks (tier-b) — fresh/grey monitoring #53 — companion slice for the driving + ignition path; same lighting subsystem prefix.

Files

New (6):

• connections/approach-lights/connection.yml (tier-b manifest; 12 contract tiles + 11 OpenClaw queries + 11 OpenClaw summary keys + 5 tier_warnings honesty markers)
• connections/approach-lights/__init__.py (DOMAIN = "approach_lights" marker stub)
• connections/approach-lights/README.md (folder overview + supersession pointer)
• connections/approach-lights/docs/recipe.md (~1083-line howto, 11 §sections; mirrors electronic-valves §1–§11 shape)
• connections/approach-lights/tests/test_connection_yml.py (7 manifest-honesty tests; 7/7 PASS via bash scripts/check.sh --core-only)
• Cron-handoff/2026-07-30-approach-lights-connection.md (Context / Changes / Verification / Rollback)

Modified (4):

• scripts/check.sh (append run_if_present entry for the new approach-lights smoke check directly after the existing electronic-valves entry)
• docs/catalog/lighting/approach-and-underbody-lights.md (add supersession banner pointing at the new connection folder; legacy content preserved for historical context)
• docs/reference/rc-entity-naming.md (add lighting subsystem to the Allowed subsystems list)
• docs/mvp/features-build-status.md (add "Shipped (repo)" row for Wave 3 Wave 3 #48: Connection: Deadbolts (tier-b) — smart lock control for van doors #52 mirroring the electronic-valves row shape)

Verification

• bash scripts/check.sh --core-only — exit 0; ✓ all requested smoke checks passed
• 7/7 manifest-honesty tests pass (connections/approach-lights/tests/test_connection_yml.py): test_id_matches_folder_name, test_tier_b_without_tier_a_markers (with explicit config_flow substring guard for the init.py docstring, mirroring the happijac defensive lesson — the test caught the rephrasing before commit), test_requires_docs_recipe_published (recipe is ~1083 lines, all 11 §sections present), test_category_matches_existing_legacy_doc (category=lighting, legacy doc has SUPERSEDED banner pointing at connections/approach-lights/), test_dashboard_tiles_follow_rc_naming (12 tiles; vendor name absolute-forbidden — shelly / hue / lifx / tradfri / ikea / philips / zigbee / zha / zwave / tuya / lutron / bond / sonoff / nous / aqara / 12v / 24v / led / led_ / relay / bulb / driver / strip / sensor_ / binary_sensor_), test_status_reflects_no_real_approach_lights (status=beta, all 5 honesty warnings in tier_warnings), test_automations_are_documented (all 5 §7 automations documented — first-arrival-after-dark + run-on-demand + auto-stop-after-N-min + camera-override-on-frigate-person + stealth-mode-suppression — plus cross-references to bluetooth-wifi-presence + Frigate + mode/automation-builder + time/weather contract + the "MANDATORY before first use" emphasis)
• All other 19 connection smoke checks remain green

Why tier-b, not tier-a

Tier-a requires a working RoamCore-owned config_flow.py, integration tests against a real approach-light bench (a Shelly 1 + a 12 V / 24 V LED strip + Hue Bridge + Frigate entry zone, all wired together in a controlled environment), and wizard.one_tap: true. We have no operator-side approach-light bench on the CI to integration-test against (the bench requires physical hardware + a way to simulate the first-arrival / dark / Frigate person trigger conditions). So this connection is honestly beta-tier: the recipe is sound but we cannot claim one-tap automation.