Wave 9 #122.c — Phase 6 Tailscale wizard Path C (Nabu Casa HA Cloud)

[bernardc6]

Wave 9 #122.c — Phase 6 Tailscale wizard Path C (Nabu Casa HA Cloud)

Wires the Phase 6 guided remote-access wizard's third path (Nabu Casa HA Cloud) end-to-end on top of the Path A (Tailscale) foundation from #122.a, while leaving Path A / Path B / Path D code paths UNTOUCHED.

What changed (8 files / +677 / −43 — purely additive)

File	Purpose
connections/remote-access/connection.yml	Flip wizard.setup_paths.nabu_casa from "coming soon" stub to fully wired (tier-b honest, side_effects + requires_inputs + setup_notes refreshed in plain English).
homeassistant/packages/roamcore_remote_access_setup.yaml	Add Path C sub-section: 4 new wizard stages + 1 new input_text helper + 2 new Path C detection binary_sensors + sensor.rc_remote_access_setup_status extensions + 3 new §8 automations (advance + recovery + detect_existing).
homeassistant/packages/tests/test_remote_access_setup.py	Extend pytest rig with 18 new Path C assertions (account email mode:password + 3 automation contract tests + no-hardcoded-secrets + 13 new parametrized status-template branch tests covering Path C stage × path × integration combos).
scripts/checks/remote-access-setup-smoke.sh	Extend with 3 new bash-level assertions (Nabu Casa secrets-leak grep + Path C wiring completeness check + Path C plain-English recovery check).
scripts/check.sh	+1 line: re-label the wired smoke from "Tailscale Path A" to "Tailscale Path A + Nabu Casa Path C" so the chain log honestly reflects Path C coverage.
docs/setup/guided-remote-access.md	New §6 "How to set up Nabu Casa HA Cloud" (5-step IKEA: what it is / what you see / what you do / what to do if it goes wrong / Useful links). §1 + §4 updated to surface Path C.
docs/catalog/connectivity/remote-access.md	+1 line (vanlifer-facing mention of Path C as the recommended simple choice for Nabu Casa subscribers).
docs/mvp/features-build-status.md	Flip Wave 9 #122.c Path C row from Planned to Shipped (with full slice metadata: helpers, binary_sensors, §8 automations, IKEA doc, no-secrets-in-repo assertions, verification summary).

homeassistant/packages/roamcore_setup_wizard.yaml was NOT touched — the existing automation.rc_setup_advance_after_remote_access from #122.a already advances the global setup wizard past networking when binary_sensor.rc_remote_access_setup_complete flips to on, and Path C's §8.5 advance moves the wizard stage to nabu_casa_done (same complete-binary_sensor flip). The global advance fires automatically.

Doctrine applied

Bernard (2026-08-04 ~21:15 UTC): "must not fail + super intuitive + critical infrastructure."

• Verification is real: pytest rig parses the YAML + asserts every contract (18 Path C assertions). Bash smoke wraps pytest with 3 new bash-level assertions.
• Auto-recover: Path C verify-timeout advances to recovery stage via automation.rc_remote_access_setup_recovery_nabu_casa (60s window, mirrors Path A's automation.rc_remote_access_setup_recovery).
• Plain-English errors: "We couldn't reach Nabu Casa. Check that your subscription is active (log into home.nabu-casa.com to check). Your account email is still there — you don't need to re-type it." — NOT "hassio: cloud subscription inactive" or "403 Forbidden". Hard-enforced by test_automation_recovery_nabu_casa_contract + the bash smoke plain-English check.
• Idempotent installer: the recovery automation NEVER calls input_text.set_value on the account email helper (operator can retry without re-typing). Hard-enforced by the same assertion.
• Tier discipline: tier-b honest, tier-b label stays. RoamCore does NOT ship a Nabu Casa native bridge — the wizard wraps the upstream HA Core cloud integration (since 2022.x) + reads sensor.home_assistant_cloud_remote + wraps cloud.remote_connect / cloud.remote_disconnect services. Tier-a would require a RoamCore-native Nabu Casa bridge which this slice does NOT ship.
• No secrets in repo: operator Nabu Casa email is input_text.rc_nabu_casa_account_email mode:password; the smoke + pytest greps for hardcoded @nabu-casa.com / hass-*.nabu-casa.com / nabucasa_* tokens and would catch any leak. The plain-English home.nabu-casa.com (the public login portal) is intentionally allowlisted as user-facing copy in the recovery notice.

GOLDEN.md alignment (re-read 2026-08-06)

Product principles served:

• P1 (Novice-first UX): the wizard replaces Nabu Casa manual panel-click setup with three plain-English taps (operator picks Path C → confirms Nabu Casa subscription is active → wizard auto-detects + auto-wires the upstream cloud integration). Fail-softly UI: if the Nabu Casa subscription lapses, the wizard surfaces a plain-English banner rather than dropping the operator into a manual recovery.
• P2 (Mission-critical connectivity): Path C is the canonical remote-access path for vanlifers who already pay for Nabu Casa HA Cloud. The wizard auto-verifies the remote URL is reachable from the upstream sensor.home_assistant_cloud_remote entity + auto-advances the §8 mandatory automation to set up the 60-second re-verify cycle.
• P6 (OpenClaw first-class): the new binary_sensor / sensor rc_remote_access_setup_nabu_casa_* entities are readable from OpenClaw — operator can ask "is my Nabu Casa wizard finished?" + "is my Nabu Casa subscription active?"

Engineering principles respected:

• E1 (Customer-facing repo): no internal logs, no sensitive infra; user-facing doc at docs/setup/guided-remote-access.md; Nabu Casa credentials NEVER appear in the repo.
• E2 (Documentation-driven): IKEA guide + pytest contract + bash smoke.
• E3 (Backup + rollback discipline): no Proxmox / HA / OpenWrt / networking change; pure repo-local code + data; rollback is a single git revert.
• E4 (Git fast mode): direct-to-branch push on subagent/phase6-tailscale-nabu-casa; one PR for Bernard per protocol.
• E5 (do not touch vmbr0): no networking config touched.
• E7 (rc-entity-naming.md): every new entity_id starts with rc_remote_access_setup_nabu_casa_*; test rig extended to allow the rc_nabu_casa_ subsystem prefix alongside the existing rc_remote_access_setup_ + rc_tailscale_ prefixes.

Anti-patterns explicitly avoided:

• ❌ "Adding 'advanced' features before the novice path is solid" — Path C IS the novice path for Nabu Casa subscribers.
• ❌ "Wide PRs that mix networking + UI + infra changes" — wizard-only slice, all additive to existing files.
• ❌ "Committing secrets or HA tokens" — operator-entered email is input_text mode:password; greps enforced.
• ❌ "Hand-configuring Victron" — Nabu Casa path, out of scope.
• ❌ "Touching vmbr0" — no networking config touched.
• ❌ "Putting internal engineering logs on the public GitHub" — IKEA doc, no SUPERSEDED banners.
• ❌ "Pulling in unrelated project context" — strictly Path C wizard scope; Path A/B/D UNTOUCHED.

User-facing one-liner

If I already pay for Nabu Casa HA Cloud, RoamCore wires it up for me in three plain-English taps so I can check my van from anywhere without setting up Tailscale, and tells me honestly if my subscription lapses.

Verification

• bash scripts/check.sh --core-only → GREEN exit 0
• bash scripts/checks/remote-access-setup-smoke.sh → 11/11 PASS, exit 0
• python3 -m pytest homeassistant/packages/tests/test_remote_access_setup.py -v → 56/56 PASS (was 38/38 in Wave 9 #119b — Phase 2 canonical vehicle model mapping layer #122.a; +18 Path C tests)

Files changed

 connections/remote-access/connection.yml                    |  19 +/-
 docs/catalog/connectivity/remote-access.md                  |  12 +/-
 docs/mvp/features-build-status.md                           |  13 +/-
 docs/setup/guided-remote-access.md                          | 154 ++/-
 homeassistant/packages/roamcore_remote_access_setup.yaml     | 188 ++/-
 homeassistant/packages/tests/test_remote_access_setup.py    | 237 ++/-
 scripts/check.sh                                            |   2 +/-
 scripts/checks/remote-access-setup-smoke.sh                 |  95 ++/-
 8 files changed, 677 insertions(+), 43 deletions(-)

Branch hygiene

• ONE branch (subagent/phase6-tailscale-nabu-casa)
• ONE commit (3d0472c)
• Branched off 5f94405 (current main HEAD — Wave 9 #122.a — Phase 6 Tailscale wizard (Path A wired, B/C/D stubs))
• No force-push history

Rollback

git revert 3d0472c restores the "coming soon" stub for wizard.setup_paths.nabu_casa + removes the 3 new Path C §8 automations + removes the new Path C binary_sensors + removes the §6 Nabu Casa IKEA doc section + removes the new pytest tests. No state to recover, no schema changes.