Helper

HA NOVA Helper

Scope

ha-nova:helper has two helper families:

• Storage-based family — full CRUD for:
• input_boolean, input_number, input_text, input_select, input_datetime, input_button, counter, timer, schedule
• Config-entry family — CRUD support for:
• utility_meter, derivative, integration, min_max, threshold, tod, statistics, history_stats
• group through the live menu-driven flow; end-to-end support is verified for the sensor subtype, and other subtypes must stay anchored to the live step schema instead of guessed fields

Not handled here:

• other config-entry helper families:
• template, trend, random, filter, generic_thermostat, switch_as_x, generic_hygrostat
• automations/scripts config mutations (use ha-nova:write)

Bootstrap (once per session)

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

Relay Contract

Write payloads with the client's native file-writing tool, then use:

• ha-nova relay ws --data-file
• ha-nova relay core --method --path --body-file
• ha-nova relay ... --out for larger read/verify output
• --jq-file for non-trivial filters; keep inline --jq for short selectors only

Family-specific transport:

• Storage-based family: WS CRUD + WS list
• Config-entry family: WS config_entries/get + WS entity-registry joins for list/read; relay /core config-entry flow, options-flow, and delete writes

Flow

Family 1: Storage-based helpers

Listing helpers

Use the compact entity registry (abbreviated keys: ei = entityid, en = name, ai = areaid).

Create ` with {"type":"config/entityregistry/listfor_display"}`, then run:

ha-nova relay ws --data-file  --jq-file 

Write `` with:

[.data.entities[] | (.ei | split(".")[0]) as $domain | select(["input_boolean","input_number","input_text","input_select","input_datetime","input_button","counter","timer","schedule"] | index($domain)) | {entity_id: .ei, name: .en, area_id: .ai}] | .[0:30]

If user filters by type, narrow the domain filter to that single storage-based domain.

Keyword search

ha-nova relay ws --data-file  --jq-file 

Write `` with:

[.data.entities[] | (.ei | split(".")[0]) as $domain | select(["input_boolean","input_number","input_text","input_select","input_datetime","input_button","counter","timer","schedule"] | index($domain)) | select((.ei + " " + (.en // "")) | test("KEYWORD";"i")) | {entity_id: .ei, name: .en, area_id: .ai}] | .[0:20]

If 0 results: try synonyms or shorter stems. Never dump entire domains.

Reading a single helper

1. Determine type from entity_id domain prefix.
2. Fetch full config via type-specific list:

``text ha-nova relay ws --data-file --jq-file ` Write with: `jq [.data[] | select(.name | test("KEYWORD";"i"))] ``

1. No single-item read endpoint — always {type}/list + filter.

Creating a helper

1. Validate intent against skills/ha-nova/helper-schemas.md for required/optional fields.
2. Use-case defaults (create only, skip on update/delete):

• Infer use-case from helper name + type using general HA knowledge.
• Consult skills/ha-nova/helper-schemas.md → Suggested Defaults for principles and field name reminders.
• If sensible defaults can be inferred: show max 4 as numbered list. Group related fields into one item.

``` Suggested defaults for "{name}" ({type}):

1. min: 16, max: 30, step: 0.5
2. unitofmeasurement: "°C"
3. mode: slider
4. icon: mdi:thermometer

Accept all, pick by number (e.g. "1 and 3"), or "skip". ```

• User accepts all, picks by number, or says "skip".
• Accepted → merge into payload BEFORE preview.
• No useful defaults inferable → silently skip.

1. Preview the payload.
2. Ask for natural confirmation.

• for unobserved group subtypes, this first confirmation authorizes only the non-persisting menu-step submit, not the final subtype-specific payload

1. Execute:

``text ha-nova relay ws --data-file ``

1. Verify — list back and confirm new item exists.
2. No domain reload needed — immediate effect.
3. Run storage-family post-write review (see below).

Updating a helper

1. Resolve target from {type}/list by name or internal id.
2. Extract id from the list response (this is the {type}_id for the update command).
3. Preview current vs proposed as a ## Changes diff (see skills/ha-nova/write-safety.md → Pre-Write Diff). Then run a pre-write impact check — search/related on this helper entity (see skills/review/SKILL.md Step 2) — and surface affected automations/scripts as an advisory. Advisory only; never block.
4. Ask for natural confirmation.
5. Execute:

``text ha-nova relay ws --data-file ``

1. Verify by re-reading the same list item.
2. Run storage-family post-write review (see below).
3. Update-Revert: after the verified update, capture the snapshot and offer revert — see skills/ha-nova/write-safety.md → Update-Revert. Storage-family restore rebuilds a schema-valid {type}/update from before_config (typed {type}_id from its id + writable fields only — never the raw list item, which lacks {type}_id and carries read-only id/entity_id); expected_after is the post-update read-back.

Deleting a helper

1. Resolve target from {type}/list; extract its id (the {type}_id used for the delete call — internal, not shown to the user).
2. Preview (see skills/ha-nova/write-safety.md → Output hygiene — no raw internal id):

• name
• type
• entity_id

1. Token confirmation: confirm: (strict: only exact token accepted; see context skill → Safety Baseline).
2. Execute:

``text ha-nova relay ws --data-file ``

1. Verify absence from {type}/list.

Family 2: Config-entry helpers

Canonical config-entry helper item:

• entry_id
• domain
• title
• state
• linked_entities[]
• supports_options

entry_id is the canonical identity for config-entry helper writes. If the user gives only a linked entity_id, resolve it back to config_entry_id through the full entity registry before continuing.

Supported domains

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

Listing helpers

1. Read all config entries:

``text ha-nova relay ws --data-file --out ` with {"type":"config_entries/get"}`.

1. Read full entity registry:

``text ha-nova relay ws --data-file --out ` with {"type":"config/entity_registry/list"}`.

1. Filter config entries to the nine supported domains.
2. Join linked entities by matching config_entry_id.
3. Present a compact table with:

• title
• domain
• entry_id
• state
• supports_options
• linked entities (compact comma-separated summary)

Keyword search

Search against:

• config-entry title
• domain
• linked entity_id
• linked original/display names when available

If multiple matches remain, present max 5 candidates and ask one blocking question.

Reading a single helper

1. Resolve by one of:

• entry_id
• config-entry title
• linked entity_id
• if multiple candidates remain after resolution, stop and ask one blocking question
• never guess between duplicate titles or ambiguous linked-entity matches

1. Re-read config_entries/get.
2. Re-read full entity registry and attach linked_entities[].
3. If supports_options: true, start an options flow:

``text ha-nova relay core --method POST --path /api/config/config_entries/options/flow --body-file ` with containing {"handler":"","showadvancedoptions":false}`.

1. Treat the returned current step as the current editable options snapshot:

• record step_id
• summarize each exposed field from description.suggested_value when present
• if an exposed field has no description.suggested_value, mark its value as unavailable instead of guessing
• ignore hidden fields that are not exposed in the current step

1. If the options flow is unavailable even though the domain is supported:

• still show canonical metadata
• mark update as unsupported on this HA version

1. Present:

**Helper: {title}** (config-entry `{domain}`)
- **Entry ID:** {entry_id}
- **Config-entry state:** {state}
- **Linked entities:** {linked_entities summary}
- **Supports options-flow editing:** {yes/no}
- **Current flow step:** {step_id or "metadata-only fallback"}
- **Current editable fields:** {field summary from the current options step when available}

Creating a helper

1. Confirm the requested domain is supported in skills/ha-nova/helper-flow-schemas.md.

• treat that file as observed field inventory, not a full validation schema
• if required field semantics remain uncertain, fail loud and ask one blocking question

1. Prepare the full create plan using skills/ha-nova/helper-flow-schemas.md:

• for one-step domains, the plan is one submit body
• for group with subtype sensor, include the required next_step_id menu choice and the observed final form
• for any other group subtype, plan only the menu choice before the flow starts; inspect the live subtype form before promising the final field set
• for statistics and history_stats, prepare every later step body before preview

1. Preview:

• title/name
• domain
• known step plan
• all fields already known at this point
• for unobserved group subtypes, say that the final subtype form will be previewed after the menu step returns live fields

1. Ask for natural confirmation.
2. Capture a pre-create baseline:

``text ha-nova relay ws --data-file --out ` with containing {"type":"config_entries/get"}`.

1. Start the flow:

``text ha-nova relay core --method POST --path /api/config/config_entries/flow --body-file ` ` must contain the handler-start body only.

1. Read the start response and extract flow_id before continuing.

• persist it in a variable or note file
• fail loud if the start response did not return flow_id

1. Iterate the flow until terminal success:

• if the current response is a menu step, submit only the selected next_step_id
• if that menu step leads to an unobserved group subtype form, stop and preview the live subtype fields before the terminal submit
• after that live subtype preview, ask for a second natural confirmation before sending the terminal subtype-specific payload
• if the current response is a form step, submit only the fields exposed for that step
• the submit body for a form step must contain form fields only
• if a required field is still unresolved and there is no safe value, stop and ask one blocking question
• if HA returns a form with validation errors, fail loud instead of guessing

1. Verify success at the config-entry layer first:

• re-read config_entries/get into ``
• if the terminal flow result includes entry_id, passed=true only when that same entry_id is present in ``
• if the terminal flow result omits entry_id, diff config_entries/get before vs after by entry_id
• in the diff fallback, collect the new entry_id values that were absent before and present after
• in the diff fallback, passed=true only when exactly one new entry_id appeared and its metadata is consistent with the requested create
• if the diff fallback yields zero or multiple new entry_id values, or the new entry metadata is inconsistent with the request, fail loud as ambiguous create verification
• domain/title are fallback tie-breakers only; they never override a terminal-flow entry_id

1. Resolve linked_entities[] through the entity registry as secondary evidence only.
2. If the created entry exposes supports_options: true, reopen the options flow and store the current editable options snapshot for the post-write response.
3. Run config-entry-family post-write review (see below).

Updating a helper

1. Resolve the canonical config-entry helper item:

• entry_id
• domain
• title
• linked_entities[]
• supports_options
• if multiple candidates remain after resolution, stop and ask one blocking question
• never guess between duplicate titles or ambiguous linked-entity matches

1. If supports_options is false for this entry:

• fail loud with update unsupported for this helper on this HA version
• do not recreate
• do not guess a direct patch body

1. Start the options flow:

``text ha-nova relay core --method POST --path /api/config/config_entries/options/flow --body-file ` with containing {"handler":"","showadvancedoptions":false}`.

1. Read the start response and extract flow_id before continuing.

• if the start response explicitly shows that options editing is unsupported for this entry on this HA version, fail loud with update unsupported for this helper on this HA version
• if the start call fails for another reason, surface that relay/HA error directly instead of relabeling it as unsupported
• persist it in a variable or note file
• fail loud if the start response did not return flow_id

1. Capture the current editable options snapshot from the returned form:

• use description.suggested_value as the current value source
• if a requested field is exposed but lacks description.suggested_value, fail loud instead of guessing its current value
• do not submit read-only fields
• treat the current step as the authoritative mutable field set

1. Build the update body by merging requested changes over the current options snapshot:

• carry forward unchanged required fields
• if the user requests a field the current step does not expose, fail loud as unsupported update for that field on this HA version
• do not silently ignore non-exposed requested fields
• do not invent values for fields the current step does not expose
• for history_stats, preserve HA's two-key window invariant across start, end, and duration
• for history_stats, if the requested change switches to a different valid window pair, drop the old third key explicitly so the submit body still contains exactly two of start, end, and duration

1. Preview current vs proposed as a ## Changes diff (see skills/ha-nova/write-safety.md → Pre-Write Diff).
2. Ask for natural confirmation.
3. Submit the current step:

``text ha-nova relay core --method POST --path /api/config/config_entries/options/flow/{flow_id} --body-file ``

1. If HA returns another form step, repeat the same merge-and-submit rule until terminal create_entry or explicit failure.
2. Verify success:

• re-read config_entries/get
• passed=true only when the same entry_id still exists
• reopen the options flow
• passed=true only when the changed fields now appear in description.suggested_value as requested
• if a requested changed field is exposed in the verification step but lacks description.suggested_value, fail loud as unverifiable update on this HA version

1. Resolve linked_entities[] again as secondary evidence only.
2. Run config-entry-family post-write review (see below).

Deleting a helper

1. Resolve target to the canonical config-entry helper item:

• entry_id
• domain
• title
• linked_entities[] when available
• if multiple candidates remain after resolution, stop and ask one blocking question
• never guess between duplicate titles or ambiguous linked-entity matches

1. Enforce the helper-domain allowlist before any delete:

• allowed here: utility_meter, derivative, integration, min_max, threshold, tod, statistics, group, history_stats
• if the resolved domain is outside that allowlist, stop
• do not call `DELETE /api/config/config_entries

…

Source & license

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

• Author: markusleben
• Source: markusleben/ha-nova
• License: MIT
• Homepage: https://github.com/markusleben/ha-nova

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