home-assistant: document rewritten HDMI matrix integration

Add a whole-house <hdmi-matrix> section: NHAV-1632 device, the
hdmi_matrix integration's entity set (16 source selects enabled, 16
stream switches + 16 signal sensors disabled-by-default) and
send_command service, deploy steps (and the custom_components-subdir
backup trap), and the rear-panel LED semantics plus the suspect-dead
port-1 transmitter. Protocol depth points to the repo's docs/device-api.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

SKILL.md

@@ -27,9 +27,9 @@ user-invocable: true
 
 <references>
   <reference file="reference/home-assistant.md"
-    summary="HA app layer on home.vino.network: Nest Matter naming and cloud-fallback target, storage-mode Lovelace editing, Great Room AV topology and Denon recovery, set_mode scripts, and virtual-remote subviews. Infra/access owned by fritzlab skill."
+    summary="HA app layer on home.vino.network: Nest Matter naming and cloud-fallback target, storage-mode Lovelace editing, whole-house HDMI matrix integration, Great Room AV topology and Denon recovery, set_mode scripts, and virtual-remote subviews. Infra/access owned by fritzlab skill."
     categories=["services", "automation", "display"]
-    keywords=["Home Assistant", "Lovelace", "dashboard", "virtual remote", "TV remote", "great room", "Frame TV", "HDMI matrix", "Denon AVR", "Roku", "Fire TV", "set_mode", "home.vino.network", "subview", "media_player.great_room"] />
+    keywords=["Home Assistant", "Lovelace", "dashboard", "virtual remote", "TV remote", "great room", "Frame TV", "HDMI matrix", "hdmi_matrix", "NHAV-1632", "HDBaseT", "send_command", "Denon AVR", "Roku", "Fire TV", "set_mode", "home.vino.network", "subview", "media_player.great_room"] />
   <reference file="reference/boat.md"
     summary="Boat details: Stranger Fins, 2025 MasterCraft 21 — specs and info"
     categories=["boat", "fun", "entertainment"]

reference/home-assistant.md

@@ -41,7 +41,7 @@ Both dashboards (`Overview` url_path `lovelace`, `Map`) are **storage mode** (UI
 ## Great Room TV / AV topology
 TV = **Samsung Frame** (`media_player.the_frame_tv` power+vol+source `['TV','HDMI']`; `remote.the_frame_tv` needs Samsung `KEY_*` codes — see <great-room-remote-card>). WoL power-on MAC `C8:A6:EF:AE:E5:FA` via `script.turn_on_great_room_tv_2`.
 
-Sources feed an **HDMI matrix**; `select.hdmi_matrix_vino_network_output_1` (named "Great Room TV") = current TV input, `..._output_3` = speakers. Options incl. `Roku-Ultra`, `Roku-3`, `FireTvStick`, `From-GR-AVR`, `Kiosk1/2`.
+Sources feed an **HDMI matrix** (see <hdmi-matrix>); `select.hdmi_matrix_vino_network_output_1` (named "Great Room TV") = current TV input, `..._output_3` = speakers. Options incl. `Roku-Ultra`, `Roku-3`, `FireTvStick`, `From-GR-AVR`, `Kiosk1/2`.
 
 **Matrix-source audio is the Denon AVR**, not the TV: zones `media_player.great_room` (+ `media_player.kitchen`), source `HDMI Matrix`; volume = `media_player.great_room`, and the TV's own speaker is set near-mute by the building block. TV-direct audio = the TV itself (the remote card's volume is context-aware — see <great-room-remote-card>).
 
@@ -58,6 +58,21 @@ is Denon telnet command `NSRBT`, wait for Deviceinfo HTTP 200, then reload the
 `media_player.great_room` + `media_player.kitchen`.
 </great-room-av>
 
+<hdmi-matrix>
+## HDMI matrix (whole-house AV routing)
+No Hassle AV **NHAV-1632** 16×32 HDMI/HDBaseT matrix at `hdmi-matrix.vino.network` (172.24.15.50, IPv4-only); the `admin/admin` web login is cosmetic — no auth on any endpoint, the LAN is the boundary. Drives every house display (Living Room, Office, bedrooms, Terrace, Great Room, speakers) through 16 output pairs (HDBaseT run + mirrored local HDMI).
+
+Integration `hdmi_matrix` (repo `dfritz/haas-hdmi-matrix-custom-component`, its own repo — gitignored from the config mirror) is built on the device's binary state protocol. One HA device keyed on the matrix MAC:
+- `select.hdmi_matrix_vino_network_output_1..16` — source per output (**enabled**); friendly names track the device's live port names.
+- `switch.…_output_N_stream` (blank one output's video) + `binary_sensor.…_input_N_signal` (live source detect) — **disabled by default**, enable as needed.
+- `hdmi_matrix.send_command` service — raw `!`/`#` device command (wire numbering is 0-based).
+Coordinator delta-polls every 2 s (idle poll ~32 B); front-panel/IR/web changes converge within a poll. Full protocol + a stdlib decoder (`tools/dump_state.py`) live in the repo's `docs/device-api.md` — not restated here.
+
+**Deploy:** rsync `custom_components/hdmi_matrix/` → `/config/custom_components/hdmi_matrix/`, then a full `ha core restart` (a config-entry reload does NOT re-import changed Python; `ha` CLI needs the login shell for `SUPERVISOR_TOKEN`, sudo drops it). NEVER stage a backup dir inside `custom_components/` — HA scans every subdir, and a dotted name (`hdmi_matrix.bak`) plus its `manifest.json` shadows the `hdmi_matrix` domain and breaks import.
+
+**Physical (rear panel):** a port LED lights only when its TX drives live video into an OPEN, unlinked port; a linked receiver or a no-signal input reads dark; blinking = link-training failure. The RemoteTV EDID slots are a last-seen sink cache, not live state — the matrix exposes NO live HDBaseT link status anywhere. Known-bad: matrix **port 1 (Output1, the Great Room TV feed) HDBaseT transmitter is suspect-dead** — its config is identical to working ports yet it stays dark through stream-toggle, source re-switch, standby cycle, and reboot; migrate that run to a spare output (12–16 are proven-good) if it stays dark.
+</hdmi-matrix>
+
 <remotes>
 ## Virtual remotes (Lovelace subviews, Overview dashboard)
 - `great-room-tv-remote` — **the main one.** A bespoke custom card `custom:great-room-remote-card`: plus-shaped D-pad, context-aware volume, source pills (set_mode scripts), apps/playback, power toggle. Fits an iPhone with no scrolling; details in <great-room-remote-card>.