Add MQTT/Zigbee diagnostics tool and documentation updates

- Introduced `scripts/mqtt_z2m_diag.py` for reusable MQTT and Zigbee2MQTT diagnostics.
- Added `copilot-instructions.md` section for MQTT/Zigbee diagnostics tool usage.
- Created `docs/mqtt-broker-broad-analysis.md` for comprehensive MQTT broker analysis.
- Documented Salotto Overview Switch investigation in `docs/salotto-overview-switch-investigation.md`.

.github/copilot-instructions.md

@@ -76,6 +76,15 @@ For broker-level MQTT investigations in this workspace, first check for a local
 - If the file is missing, incomplete, or clearly stale for the requested task, prompt the user to update it before attempting deeper MQTT diagnostics.
 - Treat the file as local machine state, not repository configuration.
 
+## Repository MQTT/Zigbee Diagnostics Tool
+
+For broker-level MQTT and Zigbee2MQTT diagnostics in this repository, prefer the reusable script at `scripts\mqtt_z2m_diag.py` over one-off session scripts.
+
+- Use the script for retained state checks, `get` requests, `device/configure` probes, permit-join flows, pair watches, raw topic watches, and side-by-side device comparisons.
+- Prefer read-only script commands first unless the investigation explicitly needs a write-like action such as `configure`, `permit-join`, or raw publish.
+- Keep `scripts\mqtt_z2m_diag.py` updated as new recurring diagnostics needs appear in this workspace.
+- Keep the skill at `.github\skills\mqtt-z2m-diagnostics\SKILL.md` aligned with the script as it evolves.
+
 ## Usage Examples
 
 - If the user says `turn on the kitchen light`, ask which instance.

.github/skills/mqtt-z2m-diagnostics/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: mqtt-z2m-diagnostics
+description: Use the repository MQTT/Zigbee2MQTT diagnostics script for broker-level Home Assistant and Zigbee2MQTT investigations.
+---
+
+# MQTT and Zigbee2MQTT diagnostics
+
+Use `scripts\mqtt_z2m_diag.py` for broker-level diagnostics in this repository instead of ad hoc one-off MQTT scripts.
+
+## When to use this skill
+
+- Zigbee2MQTT devices are stale, unavailable, or not responding to Home Assistant
+- Home Assistant entity state does not match broker state
+- You need device records, retained state, `get` responses, `device/configure` probes, permit-join, or pair watches
+- You want to compare a broken Zigbee device with a known-good one
+
+## Requirements
+
+1. Check `.local\mqtt-home.env` first.
+2. If it is missing, incomplete, or stale, ask the user for the current broker details before going deeper.
+3. Treat `.local\mqtt-home.env` as local machine state, not repository configuration.
+
+## Primary commands
+
+```powershell
+python scripts\mqtt_z2m_diag.py health
+python scripts\mqtt_z2m_diag.py device-record nitori_salotto_1
+python scripts\mqtt_z2m_diag.py state nitori_salotto_1
+python scripts\mqtt_z2m_diag.py get nitori_salotto_1 --keys state_left state_center state_right
+python scripts\mqtt_z2m_diag.py configure nitori_salotto_1
+python scripts\mqtt_z2m_diag.py compare nitori_salotto_1 Switch_Cucina_Neo --configure
+python scripts\mqtt_z2m_diag.py permit-join --time 90 --watch
+python scripts\mqtt_z2m_diag.py pair-watch nitori_salotto_1 --time 90 --duration 95
+```
+
+## Guidance
+
+- Prefer read-only commands first: `health`, `device-record`, `state`, `get`, `compare`, `watch`
+- Use `configure`, `permit-join`, `pair-watch`, or `publish` only when the investigation clearly needs them
+- When comparing devices, use the same command flow on a known-good device to prove whether the fault is in the broker path or the device itself
+- If the script reveals a new recurring diagnostic need, extend `scripts\mqtt_z2m_diag.py` and keep this skill aligned with it