eman · eman · May 12, 2026 · May 12, 2026 · May 12, 2026 · May 12, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -5,12 +5,15 @@ on:
     branches: [main]
   workflow_dispatch:
 
-permissions:
-  contents: write
+concurrency:
+  group: pages
+  cancel-in-progress: false
 
 jobs:
-  build-and-deploy:
+  build:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -24,15 +27,23 @@ jobs:
         run: pip install ".[docs]"
 
       - name: Build documentation
-        run: mkdocs build
+        run: mkdocs build --strict
 
-      - name: Ensure .nojekyll in site
-        run: touch site/.nojekyll
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
 
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
       - name: Deploy to GitHub Pages
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
-          mkdocs gh-deploy --force --clean --remote-branch gh-pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/README.md b/README.md
@@ -145,6 +145,10 @@ async with AlphaHWRClient(address) as client:
 
 Actively maintained and tested on real ALPHA HWR hardware.
 
+## Home Assistant
+
+For Home Assistant integration, it is suggested to use the ESPHome component instead of this library: [esphome-alpha-hwr](https://github.com/eman/esphome-alpha-hwr). It runs on an ESP32 as a Bluetooth proxy, exposing the pump as native Home Assistant sensors without requiring a Python host.
+
 ## Contributing
 
 Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

diff --git a/docs/TESTING_STRATEGY.md b/docs/TESTING_STRATEGY.md
@@ -2,7 +2,7 @@
 
 ## Overview
 
-This document outlines the comprehensive testing strategy for the alpha-hwr library, designed to ensure reliability, maintainability, and serve as a reference for other language implementations.
+This document outlines the testing strategy for the alpha-hwr library, covering reliability, maintainability, and serving as a reference for other language implementations.
 
 ## Testing Pyramid
 

diff --git a/docs/api/constants.md b/docs/api/constants.md
@@ -69,7 +69,7 @@ Addresses for Legacy Class 3 Register Polling.
 
 ## ERROR_CODES (Dictionary)
 
-A comprehensive lookup table mapping error codes to human-readable descriptions. Extracted from the GENI profile.
+A lookup table mapping error codes to human-readable descriptions. Extracted from the GENI profile.
 
 ```python
 from alpha_hwr.constants import ERROR_CODES

diff --git a/docs/guides/cli_guide.md b/docs/guides/cli_guide.md
@@ -1,6 +1,6 @@
 # Command Line Interface (CLI) Guide
 
-The `alpha-hwr` command-line tool provides a modern, user-friendly interface for interacting with your Grundfos ALPHA HWR pump. Built with Typer and Rich, it offers beautiful terminal output and intuitive command structure.
+The `alpha-hwr` command-line tool for interacting with Grundfos ALPHA HWR pumps. Built on Typer and Rich.
 
 ## Table of Contents
 

diff --git a/docs/guides/control_modes.md b/docs/guides/control_modes.md
@@ -1,6 +1,6 @@
 # Control Modes and Setpoints
 
-This guide provides comprehensive information about the ALPHA HWR's control modes and setpoint configuration.
+This guide covers the ALPHA HWR's control modes and setpoint configuration.
 
 ## Overview
 

diff --git a/docs/protocol/architecture.md b/docs/protocol/architecture.md
@@ -21,7 +21,7 @@ graph TD
 
 ## 2. Authentication Sequence
 
-The authentication process is a strict sequence of "magic packets" required to unlock the pump's capabilities.
+The authentication process is a strict sequence of "magic packets" that must succeed before the pump accepts commands.
 
 ```mermaid
 sequenceDiagram

diff --git a/docs/protocol/control_modes.md b/docs/protocol/control_modes.md
@@ -1,6 +1,6 @@
 # Control Modes - Complete Support Matrix
 
-This document provides a comprehensive overview of all 32 control modes defined in the GENI protocol and their support status on the Grundfos ALPHA HWR pump.
+This document covers all 32 control modes defined in the GENI protocol and their support status on the Grundfos ALPHA HWR pump.
 
 ## Executive Summary
 

diff --git a/docs/protocol/schedules.md b/docs/protocol/schedules.md
@@ -613,7 +613,7 @@ alpha-hwr schedule
 
 ## Schedule Validation
 
-The library includes comprehensive validation for schedule entries to prevent conflicts and errors.
+The library validates schedule entries to prevent conflicts and errors.
 
 ### ScheduleEntry Model
 

diff --git a/docs/reference/data_models.md b/docs/reference/data_models.md
@@ -154,7 +154,7 @@ if alarms:
 
 ## ScheduleEntry Model
 
-The `ScheduleEntry` class represents a single schedule time window with comprehensive validation.
+The `ScheduleEntry` class represents a single schedule time window. All fields are validated on construction.
 
 ### Properties