tau-all-agent 0.1.0

package/skills/homeassistant-ops/references/api.md

@@ -0,0 +1,64 @@
+# API cheat sheet
+
+This skill prefers the official Home Assistant **REST** + **WebSocket** APIs (not SSH-ing into the host).
+
+## Auth
+
+- Use a **long-lived access token**.
+- REST: `Authorization: Bearer $HA_TOKEN`
+- WS: connect to `$HA_URL/api/websocket`, then send:
+  - `{"type":"auth","access_token":"..."}` after `auth_required`
+
+## REST endpoints used most often
+
+- Core discovery:
+  - `GET /api/config` (location name, latitude/longitude, version, etc)
+  - `GET /api/services` (what services exist + schemas)
+- Events list (handy when tailing):
+  - `GET /api/events`
+- Entity state inventory:
+  - `GET /api/states`
+  - `GET /api/states/<entity_id>`
+- Call a service:
+  - `POST /api/services/<domain>/<service>`
+  - Example domain/service: `homeassistant/turn_on`, `light/turn_off`
+- Automations (UI-stored YAML / `automations.yaml`):
+  - `GET /api/config/automation/config/<id>`
+  - `POST /api/config/automation/config/<id>` (replace full config)
+- Scripts and scenes (when present in your build/version):
+  - `GET /api/config/script/config/<id>` / `POST /api/config/script/config/<id>`
+  - `GET /api/config/scene/config/<id>` / `POST /api/config/scene/config/<id>`
+- Config entry flows (used for helper creation, e.g. `group` integration):
+  - `POST /api/config/config_entries/flow` with `{"handler":"group"}`
+  - Continue flow by POSTing to `/api/config/config_entries/flow/<flow_id>`
+  - Update options via:
+    - `POST /api/config/config_entries/options/flow` with `{"handler":"<config_entry_id>"}`
+    - Continue via `/api/config/config_entries/options/flow/<flow_id>`
+
+## WebSocket message types used most often
+
+Registries:
+
+- `config/area_registry/list`
+- `config/device_registry/list`
+- `config/entity_registry/list`
+- `config/entity_registry/get` with `{"entity_id":"switch.kitchen_lights"}`
+- `config/entity_registry/update` with fields like:
+  - `{"entity_id":"switch.kitchen_lights","name":"Kitchen Lights"}`
+  - `{"entity_id":"switch.old","new_entity_id":"switch.new"}`
+  - `{"entity_id":"switch.kitchen_lights","area_id":"kitchen"}`
+  - Hide from UI: `{"entity_id":"sensor.foo","hidden_by":"user"}` (unhide with `hidden_by: null`)
+  - Disable: `{"entity_id":"sensor.foo","disabled_by":"user"}` (enable with `disabled_by: null`)
+
+Events (for debugging):
+
+- `subscribe_events` with optional `{"event_type":"state_changed"}` or `{"event_type":"zha_event"}`
+
+## Notes / gotchas
+
+- Friendly names shown in the UI typically come from the entity registry’s `name` override; update via `config/entity_registry/update`.
+- `use_blueprint.input` is **not templatable**; blueprint triggers (e.g., `platform: state entity_id: !input ...`) require a static entity list at config-load time.
+- HA “group helpers” are great for UI organization, but they don’t make Zigbee unicast faster; they just expand to member service calls.
+- Dashboard editing depends on dashboard mode:
+  - Auto-generated Overview is strategy-driven (not layout-editable).
+  - Storage dashboards can usually be fetched/updated via Lovelace APIs; YAML dashboards are file-managed.

package/skills/homeassistant-ops/references/id_conventions.md

@@ -0,0 +1,71 @@
+# ID conventions
+
+This is a practical naming scheme for `entity_id`s (and helper ids) that stays readable, stable, and automation-friendly.
+
+## Basic grammar
+
+`<domain>.<object_id>`
+
+- `domain` is the entity type (`switch`, `sensor`, `cover`, `automation`, ...).
+- `object_id` is lowercase, with tokens separated by underscores.
+
+Recommended object_id shape:
+
+`<location>[_<sub_location>...]_<kind>[_<n>]`
+
+Where:
+
+- `<location>` is usually the area slug (e.g., `bedroom`, `livingroom`, `storageroom`).
+- `<kind>` is the thing (`lights`, `cove`, `blind`, `thermometer_temperature`, ...).
+- `<n>` is a numeric suffix when there are multiple similar entities.
+
+## Area/location slugs
+
+Common patterns in this instance:
+
+- Multi-word areas are usually concatenated: `Living Room` → `livingroom`, `Storage Room` → `storageroom`.
+- Apostrophes are dropped: `Leonardo's Room` → `leonardosroom`.
+- Floor/range areas use semantic tokens:
+  - `Hall -1` → `hallminus1`
+  - `Stairs -1-0` → `stairsminus10`
+  - `Stairs 0-1` → `stairs01`, `Stairs 1-2` → `stairs12`, `Stairs 2-3` → `stairs23`
+
+## Lights / Cove switch circuits
+
+Switch-controlled lighting circuits use `switch.*` entities:
+
+- Circuit (main): `switch.<location>_lights` or `switch.<location>_cove`
+- Additional switches (multi-control): `switch.<location>_lights_2`, `switch.<location>_lights_3`, ...
+
+Guideline:
+
+- Keep the “main” physical switch as the suffix-less id.
+- Use numeric suffixes only for extra physical switches.
+
+## Helper groups
+
+Use `_group` to avoid collisions with “real” entities and to make refactoring safer:
+
+- Switch group helper: `switch.<location>_lights_group` / `switch.<location>_cove_group`
+
+Recommended helper options:
+
+- “Hide members” ON (so Overview shows only the group)
+- “All entities” OFF (explicit membership)
+- Area set explicitly to the intended area (usually the area of the primary member)
+
+## Examples
+
+- Multi-switch lighting circuit:
+  - Members: `switch.bedroom_lights`, `switch.bedroom_lights_2`, `switch.bedroom_lights_3`
+  - Helper: `switch.bedroom_lights_group`
+- Shared circuit across areas:
+  - `switch.diningroom_livingroom_lights`
+- Stairs segment controlling another area:
+  - `switch.stairsminus10_hall_lights` (stairs segment is part of the id; “Hall Lights” is the controlled circuit)
+
+## When to rename entity_ids (and when not to)
+
+- Rename early (right after adding a device) if the entity_id is ugly/vendor-ish.
+- Avoid renaming stable ids unless you also have a plan to update references.
+- Always use a reference finder before/after large id migrations (automations, scripts, scenes, dashboards, templates).

package/skills/homeassistant-ops/references/playbook.md

@@ -0,0 +1,150 @@
+# Home Assistant ops playbook
+
+Use this as a checklist of common operations. Prefer small, reviewable changes and keep a before/after log.
+
+## 0) Decide how to apply the change
+
+- **Prefer API (REST/WS)** when you want validation, no restarts, and live feedback.
+- **Prefer config YAML** when the thing is explicitly YAML-managed in your setup (packages, custom integrations, etc).
+- **Avoid editing `.storage/*` directly** on a live instance; use the registries/flows APIs instead.
+
+## 1) Inventory / discovery
+
+Pick the smallest truth source that answers the question:
+
+- **Current runtime state**: `/api/states` (REST)
+- **Registries (source of truth for names/areas/disabled/hidden)**:
+  - areas: `config/area_registry/list` (WS)
+  - devices: `config/device_registry/list` (WS)
+  - entities: `config/entity_registry/list` (WS)
+- **Snapshot for diff/rollback**: run `scripts/ha_ops.js snapshot` before/after bulk changes to capture registries + key configs in one JSON file.
+- **Backup audit** (good for planning changes offline):
+  - `.storage/core.entity_registry`, `.storage/core.device_registry`, `.storage/core.area_registry`
+
+Snapshot tips:
+
+- Default output is already stable for diffs (sorted keys; registries sorted by id), so `diff -u before.json after.json` is usually enough.
+- Skip noisy sections when you don’t need them (e.g., `--no-lovelace`, `--no-scenes`); avoid `--include-states` for long-lived baselines.
+
+## 2) Naming and IDs
+
+### Friendly names vs entity_id
+
+- **Friendly name (UI label)**: change via `config/entity_registry/update` with `name=...`.
+- **Entity ID**: change via `config/entity_registry/update` with `new_entity_id=...`.
+- House style for entity ids: see `references/id_conventions.md`.
+
+Guidelines:
+
+- Keep a consistent convention (area prefixing is usually best for repeated device types).
+- Don’t rename just to rename: aim for fewer surprises in voice control, dashboards, and automations.
+- For “noisy” entities (RSSI/LQI/firmware/identify): prefer hiding/disabling over renaming.
+
+### Ref updates (important)
+
+Entity ID changes can break references in:
+
+- automations, scripts, scenes, dashboards
+- template sensors, trigger IDs, notify targets
+- **group helper memberships** (config entry–based groups do NOT auto-update when member entity_ids are renamed; members silently disappear)
+
+Make a plan to **search and update references** before applying large ID renames.
+
+Tip: use `scripts/ha_ops.js find-references` with `--map-json` to locate old ids in automations/dashboards/backups.
+Add `--json-out ha_refs.json` when you want a machine-readable report for follow-up tooling.
+
+### Rename/migrate checklist (entity_id or helper id)
+
+Use this whenever changing `entity_id`s (or helper ids) in bulk:
+
+1. Snapshot baseline: `scripts/ha_ops.js snapshot` (keep the JSON).
+2. Find references: `scripts/ha_ops.js find-references --needle <old>` (or `--map-json rename_map.json`).
+3. Write a rename map (`old -> new`) and a timestamped change log (markdown).
+4. Apply renames via WS `config/entity_registry/update` in small batches (stop if a target id already exists).
+5. Update group helper memberships: `scripts/ha_ops.js update-groups --map-json rename_map.json` (renames are not propagated to config entry–based groups automatically).
+6. Update references (automations/scripts/scenes/dashboards/templates) and re-run the reference finder until clean.
+7. Validate behavior: automation traces + event tail (`state_changed`, `zha_event`) for the specific entities.
+8. Snapshot after and diff with baseline (fast way to confirm what actually changed).
+
+## 3) Areas, floors, labels
+
+Use these to reduce UI clutter and improve automation targeting:
+
+- Assign devices/entities to an area (usually device-level, sometimes entity-level).
+- Prefer areas for UI grouping and “overview” naming conventions.
+- Use labels/tags when you want cross-cutting collections (e.g., “security”, “critical”, “outdoor”).
+
+## 4) Helpers and groups (UI + maintainability)
+
+Common helpers:
+
+- `group` helpers (light/switch/cover): reduce dashboard clutter; make targeting easier.
+- `input_boolean`, `input_select`, `input_number`, `timer`: encode state machines and modes.
+- `scene`, `script`: normalize complex actions into reusable building blocks.
+
+Notes:
+
+- HA “group helpers” can “Hide members” so only the group shows up in Overview.
+- Groups don’t speed up unicast devices; they help maintainability.
+
+## 5) Automations, scripts, scenes
+
+### Safe editing strategy
+
+1. Fetch current config (API).
+2. Make minimal changes (prefer surgical edits).
+3. POST the full updated config back (API validates).
+4. Verify behavior using traces and event tailing.
+
+### Loop-avoidance patterns
+
+If an automation changes entities that can re-trigger it:
+
+- Use `this.context.id` / `trigger.to_state.context.parent_id` guards (blueprint-style).
+- Use `mode` deliberately (`restart`, `queued`, `parallel`) to avoid oscillation.
+- Avoid “invert/toggle” logic unless you can prove idempotence.
+
+### Blueprints
+
+- Blueprint **inputs aren’t templatable**; triggers need static entity lists at config-load time.
+- If you want “dynamic membership”, either:
+  - keep automations listing members and update the list when the group changes, or
+  - change the blueprint to trigger broadly (`state_changed`) and filter membership at runtime (more overhead/complexity).
+
+## 6) Zigbee / ZHA (when relevant)
+
+- `zha_event` is useful for debugging, but it doesn’t imply Zigbee groupcast/binding.
+- HA “group helpers” are UI/helpers; they expand into member calls and don’t make Zigbee unicast faster.
+- Zigbee groupcast/binding is a separate ZHA concept and depends on device support.
+
+## 7) Dashboards / UI compaction
+
+- Auto-generated Overview: you mainly influence it by **hiding/disabling entities** and using helpers/groups.
+- Manual dashboards: use `grid`/`tile` cards to put many covers on one row; use stacks; create “Maintenance” views for noisy entities.
+
+### Hide vs disable (mini-guide)
+
+- **Hide from UI**: keeps the entity available to automations/services, but reduces dashboard noise (especially auto-generated Overview). Prefer this for “member” entities of helpers/groups and for diagnostics you still want available.
+- **Disable entity**: removes it from normal use (often stops the integration from setting it up). Use this only when you’re sure nothing relies on it (or it’s a duplicated/unsupported feature). Disabling can break automations/cards that reference the entity.
+
+Rules of thumb:
+
+- If you still want to target it in an automation/script, **hide** it (don’t disable).
+- If it’s never used and you want it gone from lists/pickers (and possibly reduce polling), **disable** it.
+- When in doubt, hide first; disable later after a few days of “nothing broke”.
+
+## 8) Rollback strategy
+
+Before risky operations:
+
+- Keep a mapping of `old -> new` for entity names and IDs.
+- Keep one markdown log per run (timestamped).
+- Keep pre/post `ha_snapshot_*.json` files so you can diff and reconstruct intent later.
+- To revert registry changes to a baseline snapshot: `scripts/ha_ops.js rollback <snapshot_before.json> --dry-run` then `--yes`.
+- Prefer incremental changes so rollback is “undo the last run”, not “rebuild everything”.
+
+## 9) Integrations and config entries
+
+- Many helpers/integrations are configured via config entry flows (and sometimes require reload/restart).
+- Prefer options flows over editing `.storage/*` when something is integration-owned.
+- After changing options, verify entities didn’t get re-created with new ids/names.