docs: Set-up-Grafana-dashboard how-to

Five-minute walkthrough for the new grafana/ bundle shipped in
the integration repo. Covers booting InfluxDB+Grafana via docker
compose, wiring HA's influxdb integration via ha-snippet.yaml,
opening the dashboard, the four-row layout, and the iteration
loop (UI edits -> JSON Model export -> commit).

Sidebar.order: 6 puts it after the other panel-related how-tos.

src/content/docs/how-to/set-up-grafana-dashboard.mdx

@@ -0,0 +1,130 @@
+---
+title: Set up the Grafana dashboard
+description: Stand up InfluxDB v2 + Grafana with the pre-built Omni Pro II dashboard, wired to your existing Home Assistant install in under five minutes.
+sidebar:
+  order: 6
+---
+
+import { Image } from 'astro:assets';
+import shotDashboard from '../../../assets/screenshots/grafana-dashboard-overview.png';
+
+The `omni_pca` integration ships a Grafana dashboard bundle under
+[`grafana/`](https://git.supported.systems/warehack.ing/omni-pca/src/branch/main/grafana)
+in the integration repo. It's a self-contained docker-compose stack
+(InfluxDB v2 + Grafana) pre-provisioned with the *Omni Pro II — Panel
+Overview* dashboard — security state, climate trends, push-event
+activity, system health, all in one view.
+
+<Image src={shotDashboard} alt="Grafana dashboard with four rows: system health single-stats (all green), area arming + event log + zone trip timeline, thermostat temperatures + HVAC mode, event rate + unit brightness heatmap" style="border: 1px solid color-mix(in srgb, currentColor 25%, transparent); border-radius: 6px; margin: 1rem 0;" />
+
+## What you need
+
+- A working `omni_pca` install — see
+  [Install in Home Assistant](/how-to/install-in-home-assistant/) if
+  you haven't done that yet.
+- Docker + docker compose.
+- ~30 minutes of panel runtime so there's interesting data to graph.
+
+## 1. Boot the stack
+
+Clone (or pull) the integration repo and bring up the bundle:
+
+```bash
+git clone https://git.supported.systems/warehack.ing/omni-pca.git
+cd omni-pca/grafana/
+cp .env.example .env
+```
+
+Edit `.env`. Three secrets matter:
+
+```bash
+INFLUX_PASSWORD=<a strong password>
+INFLUX_TOKEN=<32 hex chars, generated with: openssl rand -hex 32>
+GRAFANA_PASSWORD=<a different strong password>
+```
+
+Then:
+
+```bash
+docker compose up -d
+```
+
+First boot takes ~30 seconds — InfluxDB provisions the `omni-pca` org,
+the `ha` bucket, and the admin token; Grafana then auto-wires the
+datasource and loads the dashboard.
+
+## 2. Tell Home Assistant to ship state
+
+Paste the contents of `grafana/ha-snippet.yaml` into your HA
+`configuration.yaml`. The default settings assume HA and InfluxDB
+live on the same machine and reach each other by container name; if
+your setup is different, change the `host:` value (see the snippet's
+inline comments).
+
+Add the token to `secrets.yaml`:
+
+```yaml
+# secrets.yaml
+influxdb_token: <same INFLUX_TOKEN from .env>
+```
+
+Restart HA. Within ~30 seconds, state changes from omni_pca entities
+start landing in InfluxDB.
+
+## 3. Open the dashboard
+
+Browse to `http://localhost:3000`. Log in as `admin` with your
+`GRAFANA_PASSWORD`. The dashboard is on the home page (it's the only
+one provisioned). If you don't see live data yet, give it a minute —
+HA's InfluxDB shipper batches writes.
+
+The dashboard's four rows cover:
+
+- **System health** — AC power, backup battery, system trouble,
+  24-hour event count. All four are single-stat panels; green = OK,
+  red = problem.
+- **Security** — area arming state timeline, recent panel events log,
+  zone trip timeline (every binary zone painted when open).
+- **Climate** — per-thermostat current temperatures + setpoints,
+  HVAC mode timeline per thermostat.
+- **Activity** — event rate by typed event class, unit brightness
+  heatmap (Y axis = unit, X axis = time, color = brightness %).
+
+## Adapting the dashboard
+
+The provisioned dashboard is read-only in the Grafana UI by design —
+the source of truth is the JSON file in
+`grafana/provisioning/dashboards/omni-pro-ii.json`. To edit:
+
+1. Make changes in the Grafana UI (everything works, you just can't
+   click *Save*).
+2. **Dashboard settings → JSON Model → Save to file**.
+3. Overwrite `omni-pro-ii.json` with the exported version, commit if
+   you want to keep your changes across redeploys.
+4. `docker compose restart grafana` to reload.
+
+## What's in the data
+
+HA's `influxdb:` integration ships state changes for the seven
+omni_pca platforms (`alarm_control_panel`, `binary_sensor`, `climate`,
+`event`, `light`, `sensor`, `switch`). The bundle's snippet tags
+events with `event_type` and `event_class`, so Flux queries can filter
+by typed event kind without parsing strings.
+
+| Tag | Source | Examples |
+|---|---|---|
+| `domain` | HA entity domain | `alarm_control_panel`, `binary_sensor`, `event` |
+| `entity_id` | HA entity ID minus the domain prefix | `omni_pro_ii_main`, `omni_pro_ii_front_door` |
+| `event_type` | `event` entity's typed kind | `unit_state_changed`, `alarm_activated`, `ac_lost` |
+| `event_class` | `event` entity's wire class name | `UnitStateChanged`, `AlarmActivated`, `AcLost` |
+
+Fields vary by entity type — numeric metrics (temperature, brightness,
+loop_reading) write to `_field == "value"`; string states (alarm mode,
+HVAC mode) write to `_field == "state"`. Climate entities additionally
+emit `current_temperature`, `target_temp_high`/`_low`, `humidity`.
+
+See the [HA entity catalogue](/reference/ha-entities/) for the full
+entity surface, and the bundle's own
+[README](https://git.supported.systems/warehack.ing/omni-pca/src/branch/main/grafana/README.md)
+for advanced configuration (custom networking, dashboard extension
+patterns, troubleshooting).