[1.8.0][HOME ASSISTANT][UX] Browse and pick boolean entities during season-sync setup

[GonzRon]

Release placement

ServiceTag 1.8.0. Coordinator: #104. This was filed as the 1.7.2 Home Assistant setup UX patch; by the owner's ruling of 2026-10-04 the former 1.7.2 work is folded into the combined 1.8.0 train with the former 1.7.1 work (#94 #99 #101 #103) and #102, and ships there.

Its classification is unchanged by the fold: it does not add a new season-sync capability or change #16's domain/transport semantics. It improves the existing setup flow by replacing manual entity-ID recall with browse/search/select, while preserving the same exact entity-ID binding underneath.

Owner rulings of 2026-10-05 (plan: docs/superpowers/plans/2026-10-05-issue-105-home-assistant-entity-picker.md): REST GET /api/states only, no WebSocket; device grouping/context and the entity/device registries explicitly deferred; an 8 MiB cap for the foreground list call only; input_boolean.* only, manual entry the escape hatch; changing an already-linked Asset's entity out of scope; the ten strings P105-1…10 ratified; the browser a mode of the existing setup sheet.

Goal

Replace the error-prone “remember and type the Home Assistant entity ID” step in the shipped #16 season-sync setup with a browse / search / pick flow.

The owner should be able to connect ServiceTag to Home Assistant, tap Choose entity, search by a human-readable name, and select the exact boolean helper/entity to use for the Asset's operating season.

This is a UX/discovery enhancement to the shipped Home Assistant season-sync contract. It does not change season semantics: the selected entity still resolves to an exact entity ID, and exact on / off remain the only season decisions.

Coordinator: #104.

User problem

Today the owner must know and manually enter an entity ID such as:

input_boolean.pellet_stove_in_season

That is precise but unnecessarily hostile on a phone:

• entity IDs are implementation identifiers, not the names people normally remember;
• a Home Assistant installation may contain hundreds or thousands of entities;
• users may remember “Pellet Stove In Season” but not its exact slug;
• typos are discovered only after validation/sync;
• browsing Home Assistant separately just to copy an ID makes the setup flow feel unfinished.

Desired setup flow

From Link to Home Assistant on the Asset season card:

1. ServiceTag verifies the configured Home Assistant connection using the existing connection/token/network policy.
2. The entity field becomes a Choose entity row rather than requiring manual entry first.
3. Tapping it opens a Home Assistant entity browser.
4. The browser defaults to the safest/recommended season-source class: input_boolean helpers.
5. The owner can search by:
   • Home Assistant display/friendly name;
   • exact/partial entity ID.
6. Results are sorted by human-readable name by default, with the entity ID shown as secondary text.
7. Selecting a row returns the exact entity ID to the existing [SHIPPED][FEATURE] Home Assistant operating-season synchronization #16 binding flow.
8. The existing setup/reconciliation warning is still shown before the Asset's season authority is changed.
9. Enter entity ID manually remains available as an advanced/fallback path.

Example row:

Pellet Stove In Season
input_boolean.pellet_stove_in_season

The ordinary case should never require the owner to remember the slug.

Entity-first, device-aware — not device-only

The browser must be entity-first.

Home Assistant Devices can be useful for grouping/browsing, but helpers such as input_boolean.* may not belong to a physical Device. A device-only picker would therefore hide or complicate the canonical season-helper use case.

Where Home Assistant supplies a device association, ServiceTag may show/group by the Device and allow:

Browse
  Entities
  Devices

or an equivalent single searchable list with device context.

A Device view is a convenience for finding entities; the stored binding remains the exact entity ID, never a display name or device name.

Ruling 2026-10-05: the device view and device context are deferred from 1.8.0 (no registry reads); helpers without devices remain fully selectable.

Recommended eligibility and filters

Initial picker:

• default filter: Input booleans / helpers (input_boolean.*);
• show only enabled entities returned by Home Assistant's display registry;
• search display name and entity ID;
• sort by display name, then entity ID;
• optional All compatible on/off entities filter may be considered during planning, but it must not make a runtime power/motion/contact sensor look equivalent to a deliberate season helper without a clear warning.

The product documentation should continue recommending a dedicated persistent input_boolean owned by the user's HA automation.

Do not infer that an entity is a season source merely because its current state happens to be on or off.

Ruling 2026-10-05: input_boolean.* only in 1.8.0; no “all on/off entities” mode and no warning copy.

Home Assistant discovery contract

Use Home Assistant's authenticated read APIs rather than scraping the frontend.

Current HA developer APIs provide:

• WebSocket config/entity_registry/list_for_display — a lightweight entity-registry list explicitly intended for displaying entity lists in UIs; entries include entity ID, display/name metadata, and optional device ID.
• WebSocket config/device_registry/list — device registry entries for optional device grouping/context.
• REST GET /api/states / GET /api/states/<entity_id> — current state objects, including entity_id, state, and attributes such as friendly_name.

Planning should prefer the display-oriented registry contract for the picker and use state data only where current-state validation/display is useful.

Be compatible with current HA device-registry behavior: device lists can include child devices, so ServiceTag must not assume every returned device has the same physical-device metadata shape.

Ruling 2026-10-05: 1.8.0 uses REST GET /api/states only (one foreground read, 8 MiB cap for that call, the ordinary poll unchanged at 64 KiB); no WebSocket transport is added for the registries.

Security and network boundary

Discovery reuses #16's existing connection, token, TLS, and network-eligibility policy.

• read-only Home Assistant requests only;
• no service calls;
• no Home Assistant writes;
• no inbound listener;
• no new remote-access mechanism;
• no token, URL/host, Wi-Fi name, entity inventory, or exception text in logs;
• never send the bearer token when [SHIPPED][FEATURE] Home Assistant operating-season synchronization #16's selected-home-Wi-Fi gate cannot be verified;
• manual entry must remain possible if discovery is unavailable on an otherwise usable HA version/configuration.

Opening the picker is an explicit foreground user action. Do not introduce a background inventory crawler or persist the entire HA registry locally merely for convenience.

Refresh / failure UX

The picker should:

• show a bounded loading state;
• support Refresh;
• distinguish authentication/network failure from “no matching entities”;
• preserve the current selection if a refresh fails;
• never change the Asset binding just because an entity disappeared from a discovery result;
• validate the selected entity before saving through the existing setup path.

If the currently bound entity is renamed in Home Assistant, ServiceTag continues using its stored exact entity ID until the owner changes the binding. Display-name changes alone must not silently retarget anything.

Scope boundaries

In scope:

• browse/search/select Home Assistant boolean entities;
• optional device-aware browsing/grouping (deferred by ruling);
• friendly-name display;
• manual-ID fallback;
• connection/setup flow polish around the picker.

Out of scope:

• auto-creating the Home Assistant helper;
• writing Home Assistant state;
• editing HA devices/entities;
• generic telemetry browsing ([FUTURE][TELEMETRY][FOUNDATION] Canonical telemetry source bindings and ingestion pipeline #56);
• arbitrary REST source discovery ([FUTURE][ENHANCEMENT] Generic REST boolean-state source adapter #100);
• importing Home Assistant measurements;
• live WebSocket subscriptions after selection;
• automatic retargeting based on renamed/matching display names;
• changing the entity of an already-linked Asset (ruling 2026-10-05).

Acceptance

• From an Asset's Home Assistant season setup, the owner can choose an entity without knowing its entity ID.
• A Home Assistant input_boolean named “Pellet Stove In Season” is searchable by that name and displays its exact entity ID.
• Search also matches the entity ID.
• Default results prioritize/filter to input_boolean season-helper candidates.
• Helpers without a Home Assistant Device association remain selectable.
• When device metadata exists, the UI can show useful device context without changing binding identity. Deferred by owner ruling 2026-10-05.
• Selecting a result stores/passes the exact entity ID into the existing [SHIPPED][FEATURE] Home Assistant operating-season synchronization #16 binding flow.
• Manual entity-ID entry remains available.
• Discovery performs no Home Assistant writes and follows [SHIPPED][FEATURE] Home Assistant operating-season synchronization #16's token/network/redaction rules.
• Failed discovery cannot change the existing binding or effective season.
• Entity/device display names are presentation only; no binding is inferred or retargeted by name.
• JVM tests cover filtering/search/sorting/mapping; Android tests cover the picker and setup navigation; HA transport tests use deterministic fake registry/state responses.

References

• [SHIPPED][FEATURE] Home Assistant operating-season synchronization #16 — shipped Home Assistant operating-season synchronization
• [ROADMAP] ServiceTag post-1.7 backlog and execution tracker #104 — current roadmap
• [FUTURE][ENHANCEMENT] Generic REST boolean-state source adapter #100 — future generic REST boolean-state source adapter
• Home Assistant WebSocket API: config/entity_registry/list_for_display, config/device_registry/list
• Home Assistant REST API: GET /api/states

[GonzRon]

Done — shipped in ServiceTag 1.8.0 (servicetag-v1.8.0 → 50bc0328; PR #107 merged as 29d5876; follow-ups #108 the instrumented sources and #110 the connected suite).

Proofs at the release commit:

• Connected suite on emulator-5554: SeasonSyncScreensTest alone 17/17, then the complete suite — 78 classes, 430 tests, 0 failures, 0 skips, one run. (The first run on master found the instrumented sources did not compile after #105 Browse and pick a Home Assistant entity during season-sync setup #107 and 14 cases stale after [1.8.0][LOCALIZATION] Android localization foundation and language packs #102/[1.7.1][UI/UX] Maintenance tab and Settings cleanup; move Reminder health to Utilities #103; both fixed in #105 follow-up: the instrumented sources compile again; CI compiles them #108 and Connected suite catches up with #102 and #103; the lending back-key case; the loopback stop test #110 with no app change. CI now compiles the instrumented sources and runs lint.)
• The controller's proof against a real Home Assistant (emulator over the LAN, 9 runs, all PASS): the picker listed every input_boolean helper on the server and nothing else; the fixture helper appeared under its friendly name with its exact entity ID beneath; search by name, by ID and by a nonsense query; picking it filled the row with the exact ID; Save stayed disabled until an entity was chosen; a fresh check read OFF and, after the helper was turned on from the host, wrote the season START — the picked ID is the one polled; manual entry remained available; dismissing the whole sheet during the list read caused no crash and a reopen worked. The app wrote nothing to Home Assistant. No address, host name, token, friendly name or entity ID is in anything kept (leak check 0).
• In-place upgrade from signed 1.7.0 with a saved connection, token and link: the token survives ("A token is saved on this phone.", needsToken false, the binding unchanged).

Acceptance: every open bullet is met; the device-context bullet stays deferred by the 2026-10-05 ruling (no registry reads in 1.8.0).

Recorded limits (in the 1.8.0 notes): input_boolean helpers only; one foreground read of GET /api/states (8 MiB cap); the system Back gesture closes the whole sheet (the list's own Cancel returns to it); changing an already-linked Asset's entity is out of scope.