fallback

name: fallback description: Mandatory fallback for any HA NOVA task without a dedicated subskill. Must be invoked before any raw relay write operation. Covers blueprints, energy, calendars, zones/persons/tags, destructive registry admin, system health, Apps, HACS, Zigbee/Z-Wave, and unsupported config-entry helper families.

HA NOVA Fallback

Scope

Mandatory fallback for HA features without a dedicated skill. Three tiers:

• Relay-Ready: API works via Relay, no skill yet -- provide experimental relay calls with safety guardrails.
• Roadmap: Planned for future Relay phases -- explain timeline + workaround.
• External: Outside HA NOVA scope -- web search + HA UI pointer.

All relay calls in this skill are experimental -- always follow Safety Guardrails below.

Safety Baseline

• Correct invalid Home Assistant premises explicitly.
• Do not silently compensate for a wrong premise.
• Keep corrections brief and technical, not preachy.

Bootstrap (only before Relay-Ready calls)

Only needed when executing experimental relay calls (not for Roadmap/External guidance).

Verify relay CLI: ha-nova relay health If this fails: ha-nova setup

Relay Contract

For every Relay-Ready call in this skill:

• write request JSON with the client's native file-writing tool
• use ha-nova relay ws --data-file <payload-file> or ha-nova relay core --method <METHOD> --path <PATH> --body-file <payload-file>
• use --out <result-file> for large responses
• treat inline -d as an optional tiny diagnostic path, not the canonical contract

Capability Map

Agent Flow

1. Check Capability Map for user's request
2. If "Covered" -> STOP, use the listed skill instead
3. If "Relay-Ready":
   a. FIRST: Search web using the provided Search query — understand current payload schema before any call
   b. Show experimental relay call examples informed by search results
   c. Preview full payload before any write — never guess fields
   d. Execute only after user confirms preview
4. If "Roadmap":
   a. Explain which phase and what blocks it
   b. Search web for manual workaround or alternative approach
   c. Suggest HA UI as interim solution
5. If "External":
   a. Explain why it's outside HA NOVA scope
   b. Search web for current best practice (how to do it directly in HA)
   c. Point to HA UI path

Web search is mandatory for Relay-Ready writes. The relay call examples below cover common read patterns, but write payloads change across HA versions. Always verify the current schema via web search before constructing a write payload.

Relay-Ready Features

Blueprints -- RELAY-READY

List and import automation/script blueprints from the community or custom URLs.

Search: home assistant blueprint import automation api 2026

Experimental relay calls (no skill guardrails):

ha-nova relay ws --data-file <payload-file>

Risks: Imported blueprints execute when instantiated. Review blueprint source before import.

Zone / Person / Tag Management -- RELAY-READY

Manage location zones, person entities, and NFC/QR tags.

Search: home assistant zone person tag management api websocket 2026

Experimental relay calls (no skill guardrails):

ha-nova relay ws --data-file <payload-file>

Risks: Zone changes affect presence detection automations. Person changes affect device trackers.

Energy Configuration -- RELAY-READY

Configure energy dashboard sources (grid, solar, gas, water, individual devices).

Search: home assistant energy dashboard configuration api preferences 2026

Experimental relay calls (no skill guardrails):

ha-nova relay ws --data-file <payload-file>

Risks: Field-level list replacement — omitted top-level keys (energy_sources, device_consumption, device_consumption_water) are preserved, but each provided key replaces its entire list. To add one source: read existing via energy/get_prefs, append to list, save back full list. Requires admin auth.

System Health / Repairs -- RELAY-READY

Check system health status and view deprecation/repair issues.

Search: home assistant system health repairs issues api 2026

Experimental relay calls (no skill guardrails):

ha-nova relay ws --data-file <payload-file>

Risks: None (read-only). Note: system_health/info uses a subscription pattern -- call via relay returns first response only.

Calendar Queries -- RELAY-READY

List calendars and query upcoming events.

Search: home assistant calendar api rest events query 2026

Experimental relay calls (no skill guardrails):

ha-nova relay core --method GET --path /api/calendars --jq .data.body
ha-nova relay core --method GET --path <calendar-events-path> --jq .data.body

Use <calendar-events-path> for the full /api/calendars/<calendar_id>?start=...&end=... query string.

Risks: None (read-only).

Other Config-Entry Helpers -- RELAY-READY

Handle unsupported config-entry helper types that are not yet owned by ha-nova:helper.

Owned by ha-nova:helper now:

• utility_meter
• derivative
• integration
• min_max
• threshold
• tod
• statistics
• group
• history_stats

Still handled here:

• template
• trend
• random
• filter
• generic_thermostat
• switch_as_x
• generic_hygrostat

Search: home assistant config entry flow helper template trend random filter generic_thermostat api 2026

Supported types in this fallback section: template, trend, random, filter, generic_thermostat, switch_as_x, generic_hygrostat

Experimental relay calls (no skill guardrails):

# Start create/reconfigure flow
ha-nova relay core --method POST --path /api/config/config_entries/flow --body-file <payload-file>

# Submit create/reconfigure step
ha-nova relay core --method POST --path /api/config/config_entries/flow/{flow_id} --body-file <payload-file>

# Start options flow for update when supported
ha-nova relay core --method POST --path /api/config/config_entries/options/flow --body-file <payload-file>

# Submit options step
ha-nova relay core --method POST --path /api/config/config_entries/options/flow/{flow_id} --body-file <payload-file>

# Delete unsupported config-entry helper by entry_id
ha-nova relay core --method DELETE --path /api/config/config_entries/entry/{entry_id}

Risks: Multi-step flows are complex. Each step returns the next step's schema. Update support can be domain- and version-specific. Delete requires correct entry_id resolution first. Prefer HA UI for these.

Entity Removal / Device Detach -- RELAY-READY

Destructive registry admin that is still outside ha-nova:organize v1:

• remove an entity from the entity registry
• remove a config entry from a device

Search: home assistant entity registry remove device remove config entry websocket api 2026

Experimental relay calls (no skill guardrails):

# Remove entity
ha-nova relay ws --data-file <payload-file>

# Remove config entry from device
ha-nova relay ws --data-file <payload-file>

Risks: Entity remove is not the same as a reversible rename/disable. Device detach depends on integration support and can sever the current device/config-entry relationship. Preview impact first.

Roadmap Features

Event Subscriptions -- ROADMAP (Phase 1c)

Real-time event streams for state changes, automation triggers, and custom events.

Search: home assistant event subscription state_changed real time api 2026

Status: Coming in Phase 1c. Blocked by: No SSE streaming endpoint in Relay. Workaround: Poll entity state periodically via GET /api/states/{entity_id}.

Template / REST / Command-Line Sensors -- ROADMAP (Phase 3)

Define custom sensors using Jinja2 templates, REST endpoints, or shell commands.

Search: home assistant template sensor yaml configuration 2026

Status: Coming in Phase 3. Blocked by: No filesystem access in Relay (sensors defined in YAML files). Workaround: Create via HA UI: Settings > Devices & Services > Helpers (for template helpers) or add YAML manually.

Configuration Backups -- ROADMAP (Phase 2)

Create and restore full configuration backups.

Search: home assistant backup restore api supervisor 2026

Status: Coming in Phase 2. Blocked by: No backup endpoint in Relay. Workaround: Use HA UI: Settings > System > Backups. Or use Supervisor API if HA OS.

External Features

Apps / Supervisor Management -- EXTERNAL

Supervisor API is separate from HA Core API. Requires different auth and endpoints.

Search: home assistant supervisor app add-on install manage api 2026

Alternative: HA UI: Settings > Apps. Or ha CLI on HA OS.

HACS (Home Assistant Community Store) -- EXTERNAL

Third-party integration with no stable public API.

Search: home assistant hacs install custom integration repository 2026

Alternative: HACS sidebar panel in HA UI.

Zigbee / Z-Wave / Network Configuration -- EXTERNAL

Device pairing is hardware-specific, requires direct coordinator access (ZHA, Z2M, Z-Wave JS).

Search: home assistant zigbee2mqtt zha device pairing configuration 2026

Alternative: HA UI: Settings > Devices & Services > [Zigbee/Z-Wave integration].

Safety Guardrails

Rules for all experimental relay calls in this skill:

• Always preview the full payload before execution
• Read before write: fetch current state first for any destructive operation
• Full-document overwrites (e.g., lovelace/config/save): MUST read full config, merge changes in memory, preview merged result, then write. There is no partial update endpoint — the entire config is replaced.
• Field-level list replacements (e.g., energy/save_prefs): omitted top-level keys are preserved, but each provided key replaces its entire list. To add one item, read the existing list first, append, then save back the full list.
• Web search before write: always search for current payload schema before constructing any write payload. HA APIs evolve across versions — the examples in this skill are starting points, not authoritative schemas.
• Every experimental call must show: "EXPERIMENTAL: No skill guardrails. Proceed with caution."
• No diff or auto-undo here: these writes have no ## Changes preview or revert. When a write may be hard to reverse, say so plainly and point to Home Assistant Backups (Settings > System > Backups) as the safety net before confirming.
• One resource at a time (no batch writes)
• Delete requires tokenized confirmation (confirm:<token>)
• Never guess IDs: resolve via list/search first
• Experimental results may be unexpected — verify data-target match before presenting conclusions (see skills/ha-nova/SKILL.md → Claim-Evidence Binding)

Write Safety by Endpoint Type

No HA WS endpoint has optimistic locking (no ETags, no version numbers). Last writer wins silently.

Anti-Patterns (never do this)

• Sending lovelace/config/save with a guessed or partial payload — this overwrites the ENTIRE dashboard config, destroying all other views and cards
• Sending energy/save_prefs with a single source — this replaces the entire energy_sources list, deleting all existing sources
• Probing write endpoints to "see what happens" — read the Relay-Ready section first
• Skipping this skill and going straight to relay ws/relay core for unfamiliar operations
• Using trial-and-error to discover payload schemas — search web for the WS type schema instead

Error Handling

Experimental calls may fail with unfamiliar errors. General rules:

• 400/VALIDATION_ERROR: payload schema wrong -- search web for current WS type schema
• 404/NOT_FOUND: endpoint may not exist in this HA version -- check HA release notes
• 502/504: relay connection issue -- retry once, then route to ha-nova:onboarding