# Fallback

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-markusleben-ha-nova-fallback`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [markusleben](https://agentstack.voostack.com/s/markusleben)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [markusleben](https://github.com/markusleben)
- **Source:** https://github.com/markusleben/ha-nova/tree/main/skills/fallback
- **Website:** https://github.com/markusleben/ha-nova

## Install

```sh
agentstack add skill-markusleben-ha-nova-fallback
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 ` or `ha-nova relay core --method  --path  --body-file `
- use `--out ` for large responses
- treat inline `-d` as an optional tiny diagnostic path, not the canonical contract

## Capability Map

| Feature | Status | Skill |
|---------|--------|-------|
| Automations CRUD | Covered | read / write |
| Scripts CRUD | Covered | read / write |
| Config Review | Covered | review |
| Helpers (9 storage + 9 config-entry) | Covered | helper |
| Entity Search | Covered | entity-discovery |
| Service Calls | Covered | service-call |
| Relay Setup | Covered | onboarding |
| Dashboard / Lovelace (storage lifecycle, cards, resources) | Covered | dashboard |
| History Queries | Covered | history |
| Logbook Queries | Covered | history |
| Statistics / Trend Queries | Covered | history |
| Area / Floor CRUD | Covered | organize |
| Label CRUD / Rich label metadata | Covered | organize |
| Category CRUD / Entity category assignment | Covered | organize |
| Entity / Device metadata updates | Covered | organize |
| Blueprints | Relay-Ready | this skill |
| Zone / Person / Tag Mgmt | Relay-Ready | this skill |
| Energy Configuration | Relay-Ready | this skill |
| System Health / Repairs | Relay-Ready | this skill |
| Calendar Queries | Relay-Ready | this skill |
| Other Config-Entry Helpers | Relay-Ready | this skill |
| Entity remove / Device config-entry detach | Relay-Ready | this skill |
| Event Subscriptions | Roadmap Phase 1c | -- |
| Template / YAML Sensors | Roadmap Phase 3 | -- |
| Configuration Backups | Roadmap Phase 2 | -- |
| Apps / Supervisor | External | -- |
| HACS | External | -- |
| Zigbee / Z-Wave Config | External | -- |

## 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):**
```text
ha-nova relay ws --data-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):**
```text
ha-nova relay ws --data-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):**
```text
ha-nova relay ws --data-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):**
```text
ha-nova relay ws --data-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):**
```text
ha-nova relay core --method GET --path /api/calendars --jq .data.body
ha-nova relay core --method GET --path  --jq .data.body
```
Use `` for the full `/api/calendars/?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):**
```text
# Start create/reconfigure flow
ha-nova relay core --method POST --path /api/config/config_entries/flow --body-file 

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

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

# Submit options step
ha-nova relay core --method POST --path /api/config/config_entries/options/flow/{flow_id} --body-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):**
```text
# Remove entity
ha-nova relay ws --data-file 

# Remove config entry from device
ha-nova relay ws --data-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:`)
- 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

| Type | Behavior | Safe pattern | Examples |
|------|----------|-------------|----------|
| Full-document overwrite | Entire config replaced | Read → modify → save full document | `lovelace/config/save` |
| Field-level list replace | Omitted keys preserved, provided keys fully replaced | Read existing list → append/modify → save full list | `energy/save_prefs` |
| Merge/patch | Only provided fields updated | Send only changed fields | `config/area_registry/update`, `config/entity_registry/update` |
| Delete | Irreversible for areas/zones/labels; soft-delete (30 days) for entities | Always `search/related` first, tokenized confirmation | `config/area_registry/delete`, `config/entity_registry/remove` |

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`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [markusleben](https://github.com/markusleben)
- **Source:** [markusleben/ha-nova](https://github.com/markusleben/ha-nova)
- **License:** MIT
- **Homepage:** https://github.com/markusleben/ha-nova

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-markusleben-ha-nova-fallback
- Seller: https://agentstack.voostack.com/s/markusleben
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.