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