Add Mermaid diagrams to docs

docs/api/integrations.md

@@ -4,6 +4,29 @@ SQMeter exposes device data through three supported integration paths. The legac
 
 ## Supported integration paths
 
+```mermaid
+flowchart LR
+    Sensors["Sensor readings<br/>sky, environment, clouds, rain, GPS"]
+    Firmware["SQMeter firmware<br/>normalises current state"]
+    REST["REST API<br/>pull snapshots"]
+    WS["WebSocket<br/>live browser/app streams"]
+    MQTT["MQTT<br/>scheduled broker publish"]
+    HA["Home Assistant / Grafana"]
+    Scripts["Scripts and local tools"]
+    Browser["Dashboard UI"]
+
+    Sensors --> Firmware
+    Firmware --> REST
+    Firmware --> WS
+    Firmware --> MQTT
+    REST --> Scripts
+    REST --> HA
+    WS --> Browser
+    WS --> Scripts
+    MQTT --> HA
+    MQTT --> Scripts
+```
+
 ### REST API
 
 Pull sensor data, status, and configuration over plain HTTP. See [REST API](rest.md) for full endpoint reference.

docs/getting-started/first-setup.md

@@ -4,6 +4,20 @@ SQMeter ships with no WiFi credentials. On first power-on it starts in **hotspot
 
 ---
 
+```mermaid
+stateDiagram-v2
+    [*] --> Boot
+    Boot --> SetupAP: no WiFi credentials in NVS
+    SetupAP --> CaptivePortal: phone or laptop joins SQM-Setup
+    CaptivePortal --> SaveCredentials: user selects 2.4 GHz WiFi
+    SaveCredentials --> Reboot: credentials saved to NVS
+    Reboot --> LanMode: device joins configured network
+    LanMode --> Dashboard: open sqmeter.local or device IP
+    LanMode --> SetupAP: NVS erased or full chip erase
+```
+
+---
+
 ## Step 1 — Power On
 
 Connect the ESP32 to USB or a 5V supply. Within a few seconds it broadcasts:

docs/index.md

@@ -9,6 +9,44 @@ SQMeter is an open-source sky quality meter built on the ESP32. It measures ligh
 
 ---
 
+```mermaid
+flowchart LR
+    subgraph Sensors["Sensors"]
+        TSL["TSL2591<br/>sky brightness"]
+        BME["BME280<br/>environment"]
+        MLX["MLX90614<br/>cloud temperature"]
+        GPS["GPS<br/>optional time/location"]
+        RG15["RG-15<br/>optional rain"]
+    end
+
+    subgraph Device["ESP32 SQMeter"]
+        FW["Firmware<br/>sampling, calibration, config"]
+        FS["LittleFS<br/>embedded web UI"]
+        NVS["NVS<br/>saved settings"]
+    end
+
+    subgraph Clients["Local network clients"]
+        Browser["Browser dashboard"]
+        REST["REST API"]
+        WS["WebSocket streams"]
+        MQTT["MQTT broker"]
+    end
+
+    TSL -->|"I2C"| FW
+    BME -->|"I2C"| FW
+    MLX -->|"I2C"| FW
+    GPS -->|"UART"| FW
+    RG15 -->|"UART"| FW
+    FW <--> NVS
+    FS --> Browser
+    FW --> REST
+    FW --> WS
+    FW --> MQTT
+    Browser <--> FW
+```
+
+---
+
 ## Features
 
 <div class="grid cards" markdown>

docs/user-guide/ota.md

@@ -73,6 +73,22 @@ esptool.py --chip esp32 --port PORT --baud 115200 \
 
 The partition table has two app slots (`app0` at `0x10000`, `app1` at `0x190000`). OTA writes the new firmware to the inactive slot, then updates the `otadata` partition to point the bootloader at it on next boot. If the new firmware fails to boot, the bootloader stays on the old slot.
 
+```mermaid
+stateDiagram-v2
+    [*] --> RunningApp0: bootloader selects app0
+    RunningApp0 --> UploadToApp1: upload firmware via /api/update
+    UploadToApp1 --> MarkApp1: write complete, update otadata
+    MarkApp1 --> RebootToApp1: restart
+    RebootToApp1 --> RunningApp1: new firmware boots
+    RebootToApp1 --> RunningApp0: boot fails, keep previous slot
+
+    RunningApp1 --> UploadToApp0: next OTA writes inactive app0
+    UploadToApp0 --> MarkApp0: write complete, update otadata
+    MarkApp0 --> RebootToApp0: restart
+    RebootToApp0 --> RunningApp0: new firmware boots
+    RebootToApp0 --> RunningApp1: boot fails, keep previous slot
+```
+
 This means you always have a working rollback as long as you don't erase the flash.
 
 The LittleFS filesystem update is separate from app OTA slots. It replaces the dashboard/settings assets and preserves NVS configuration, but an interrupted filesystem upload can leave the web UI unavailable until LittleFS is flashed again over USB or a later successful OTA filesystem upload.

mkdocs.yml

@@ -46,7 +46,11 @@ theme:
 markdown_extensions:
   - admonition
   - pymdownx.details
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.highlight:
       anchor_linenums: true
       line_spans: __span