Add agent customization: agents, hooks, skills, and instructions

- Add security-reviewer agent definition
- Add run-validation-after-edits hook (config + script)
- Add feature-doc-updates skill; expand bsblan-testing skill
- Restructure AGENTS.md and slim copilot-instructions.md
- Point CLAUDE.md at AGENTS.md
- Update code-review prompt

Author: liudger

.github/agents/security-reviewer.agent.md

@@ -0,0 +1,32 @@
+---
+description: "Use when you need a security review, threat modeling, vulnerability triage, secrets exposure checks, auth/session risk analysis, input validation review, dependency risk review, or secure coding feedback."
+name: "Security Reviewer"
+tools: [read, search]
+argument-hint: "Provide scope (files, PR, or feature), threat context, and any known attack surface."
+---
+You are a specialist security code reviewer. Your job is to find exploitable risks and provide precise, actionable remediation guidance.
+
+## Constraints
+- DO NOT refactor for style or performance unless it directly affects security.
+- DO NOT propose broad rewrites when a targeted fix is sufficient.
+- DO NOT claim an issue without explaining exploitability, impact, and preconditions.
+- ONLY report findings that are security-relevant or materially increase security risk.
+
+## Approach
+1. Map attack surface first: inputs, trust boundaries, secrets, authn/authz, network calls, file/system access, and third-party dependencies.
+2. Prioritize exploitability over code smell; assess realistic attacker paths and blast radius.
+3. Verify mitigations already present to avoid false positives.
+4. Provide concrete fixes with smallest safe change and validation steps.
+
+## Output Format
+1. Findings (ordered by severity: critical, high, medium, low)
+- Title
+- Severity
+- Location (file and line)
+- Why this is vulnerable
+- Exploit scenario
+- Recommended fix
+2. Open questions or assumptions
+3. Residual risk and security test gaps
+
+If no findings are discovered, explicitly state that and list residual risks or testing gaps.

.github/copilot-instructions.md

@@ -1,277 +1,7 @@
-# GitHub Copilot Instructions for python-bsblan
+# Canonical Instructions
 
-This repository contains the `python-bsblan` library, an asynchronous Python client for BSB-LAN devices (heating controllers).
+The canonical instruction file for this repository is:
 
-## Project Overview
+- `AGENTS.md`
 
-- **Language**: Python 3.12+
-- **Type**: Async library using `aiohttp`
-- **Purpose**: Communicate with BSB-LAN devices to read/write heating parameters
-- **License**: MIT
-
-## Code Quality Standards
-
-### Required Before Committing
-
-Always run these commands after making changes:
-
-```bash
-# Run all prek hooks (ruff, ty, pylint)
-uv run prek run --all-files
-```
-
-### Prek Includes
-- **Ruff**: Linting and formatting (88 char line limit)
-- **ty**: Static type checking
-- **Pylint**: Code analysis
-
-### Coverage Requirements
-- Maintain **95%+ total test coverage**
-- **Patch coverage must be 100%** - all new/modified code must be fully tested
-- GitHub Actions will fail if patch coverage is below 100%
-- Run coverage check: `uv run pytest --cov=src/bsblan --cov-report=term-missing`
-
-## Project Structure
-
-```
-src/bsblan/
-├── __init__.py          # Package exports
-├── bsblan.py            # Main BSBLAN client class
-├── constants.py         # Parameter IDs and mappings
-├── models.py            # Dataclass models for API responses
-├── utility.py           # Helper utilities
-├── exceptions.py        # Custom exceptions
-└── py.typed             # PEP-561 marker
-
-tests/
-├── conftest.py          # Pytest fixtures
-├── fixtures/            # JSON test data
-└── test_*.py            # Test files
-```
-
-## Parameter Naming Conventions
-
-### BSB-LAN Parameters
-Parameters are identified by numeric IDs and mapped to readable names in `constants.py`.
-
-**Naming Rules:**
-- Use `snake_case` for all parameter names
-- Group related parameters with common prefixes
-- Legionella-related parameters use `legionella_function_*` prefix:
-  - `legionella_function_setpoint` (ID: 1645)
-  - `legionella_function_periodicity` (ID: 1641)
-  - `legionella_function_day` (ID: 1642)
-  - `legionella_function_time` (ID: 1644)
-  - `legionella_function_dwelling_time` (ID: 1646)
-- DHW (Domestic Hot Water) parameters use `dhw_*` prefix
-
-### Adding New Parameters
-
-1. **Add to `constants.py`**:
-   ```python
-   BASE_HOT_WATER_PARAMS: Final[dict[str, str]] = {
-       "1645": "legionella_function_setpoint",  # Parameter ID: name
-   }
-   ```
-
-2. **Add to model in `models.py`**:
-   ```python
-   class HotWaterConfig(BaseModel):
-       legionella_function_setpoint: EntityInfo[float] | None = None
-   ```
-
-3. **Update method in `bsblan.py`** if the parameter is settable:
-   ```python
-   async def set_hot_water(
-       self,
-       params: SetHotWaterParam,
-   ) -> None:
-   ```
-   And add the field to `SetHotWaterParam` in `models.py`:
-   ```python
-   @dataclass
-   class SetHotWaterParam:
-       legionella_function_setpoint: float | None = None
-   ```
-
-4. **Add tests in `tests/test_*.py`**
-
-## Polling Categories
-
-Parameters are organized into polling categories based on how frequently they change:
-
-### Fast Poll (State - every update)
-- Current temperatures
-- HVAC action/state
-- Pump states
-
-### Slow Poll (Config - every 5 minutes)
-- Operating modes
-- Setpoints
-- Legionella function settings
-- Time programs
-
-### Static (rarely changes)
-- Device identification
-- Min/max temperature limits
-
-## Hot Water Parameter Groups
-
-Hot water parameters are split into groups for granular lazy loading:
-
-| Group | Params | Method | Use Case |
-|-------|--------|--------|----------|
-| essential | 5 | `hot_water_state()` | Frequent polling |
-| config | 16 | `hot_water_config()` | Advanced settings |
-| schedule | 8 | `hot_water_schedule()` | Time programs |
-
-Defined in `constants.py`:
-- `HOT_WATER_ESSENTIAL_PARAMS` - operating_mode, nominal_setpoint, etc.
-- `HOT_WATER_CONFIG_PARAMS` - legionella settings, eco mode, etc.
-- `HOT_WATER_SCHEDULE_PARAMS` - daily time programs
-
-## Data Models
-
-### Model Pattern
-All models use `pydantic` `BaseModel` for validation and serialization:
-
-```python
-from pydantic import BaseModel
-
-class HotWaterConfig(BaseModel):
-    """Hot water configuration parameters."""
-    operating_mode: EntityInfo[int] | None = None
-    nominal_setpoint: EntityInfo[float] | None = None
-```
-
-### EntityInfo Structure
-Each parameter returns an `EntityInfo[T]` (generic `BaseModel`) with:
-- `value`: The actual value (typed via generic `T`)
-- `unit`: Unit of measurement
-- `desc`: Human-readable description
-- `data_type`: Data type information
-
-## Async Patterns
-
-### Client Usage
-```python
-from bsblan import BSBLAN, BSBLANConfig, SetHotWaterParam
-
-async with BSBLAN(BSBLANConfig(host="192.168.1.100")) as client:
-    state = await client.state()
-    await client.set_hot_water(SetHotWaterParam(nominal_setpoint=55.0))
-```
-
-### Lazy Loading Architecture
-The library uses lazy loading for optimal performance:
-- **Initialization**: Only fetches firmware version (fast startup)
-- **Section validation**: Deferred until section is first accessed
-- **Hot water granular loading**: Each method validates only its param group
-- **Race condition prevention**: Per-section/group asyncio locks
-
-```python
-# Initialize() is fast - only fetches firmware
-await client.initialize()  # ~0.02s
-
-# Section validated on first access
-await client.state()  # Validates heating section on first call
-
-# Hot water methods validate only their param groups:
-await client.hot_water_state()    # 5 essential params only
-await client.hot_water_config()   # 16 config params only
-await client.hot_water_schedule() # 8 schedule params only
-```
-
-### Concurrency & Locking
-The library uses asyncio locks to prevent race conditions during lazy loading:
-- `_section_locks`: Per-section locks (heating, sensor, etc.)
-- `_hot_water_group_locks`: Per-group locks (essential, config, schedule)
-
-Double-checked locking pattern:
-1. Fast path: Check if validated (no lock)
-2. Acquire lock for specific section/group
-3. Double-check after acquiring lock
-4. Perform validation inside the lock
-
-This prevents duplicate network requests when concurrent calls access the same section before validation completes.
-
-### Error Handling
-- Use `BSBLANError` for general errors
-- Use `BSBLANConnectionError` for connection issues
-- Always validate only one parameter is set per API call
-
-## Testing Patterns
-
-### Test Structure
-```python
-@pytest.mark.asyncio
-async def test_set_hot_water(mock_bsblan: BSBLAN) -> None:
-    """Test setting BSBLAN hot water state."""
-    await mock_bsblan.set_hot_water(
-        SetHotWaterParam(nominal_setpoint=60.0)
-    )
-    mock_bsblan._request.assert_awaited_with(
-        base_path="/JS",
-        data={"Parameter": "1610", "Value": "60.0", "Type": "1"},
-    )
-```
-
-### Fixtures Location
-Test fixtures (JSON responses) are in `tests/fixtures/`
-
-## Common Tasks
-
-### Fetching Parameters from a Real Device
-
-Use `examples/fetch_param.py` to query raw parameter data from a real BSB-LAN device before adding new parameters:
-
-```bash
-# Set your device connection details
-# Leave BSBLAN_HOST unset to use auto-discovery, or set it explicitly:
-export BSBLAN_HOST="192.168.1.100"
-export BSBLAN_PASSKEY=your_passkey  # if needed
-
-# Fetch one or more parameters
-cd examples && python fetch_param.py 1645
-cd examples && python fetch_param.py 1645 1641 1642 1644 1646
-```
-
-The output shows the raw JSON response including value, unit, description, and data type — use this to determine the correct model field type and naming.
-
-### Adding a New Settable Parameter
-
-0. Fetch the parameter from a real device using `examples/fetch_param.py` to inspect the raw response
-1. Add parameter ID mapping in `constants.py`
-2. Add field to appropriate model in `models.py`
-3. Add parameter to method signature in `bsblan.py`
-4. Update docstring with parameter description
-5. Add state preparation logic in `_prepare_*_state()` method
-6. Add tests for the new parameter
-7. Run `uv run prek run --all-files`
-
-### Renaming a Parameter
-
-When renaming parameters for consistency:
-1. Update `constants.py` - parameter mapping
-2. Update `models.py` - dataclass field
-3. Update `bsblan.py` - method parameters and state handling
-4. Update `tests/` - all test files using the parameter
-5. Update `examples/` - any example code
-6. Run `uv run prek run --all-files`
-
-## API Versions
-
-The library supports BSB-LAN API versions:
-- **v1**: Original API
-- **v3**: Extended API with additional parameters
-
-Version-specific parameters are handled in `constants.py` with extension dictionaries.
-
-## Don't Forget
-
-- ✅ Run `uv run prek run --all-files` after every change
-- ✅ Maintain 95%+ test coverage
-- ✅ Use type hints on all functions
-- ✅ Add docstrings to public methods
-- ✅ Keep line length under 88 characters
-- ✅ Use consistent parameter naming (check existing patterns)
+Keep this file as a lightweight compatibility pointer to avoid duplicated guidance.

.github/hooks/run-validation-after-edits.json

@@ -0,0 +1,11 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "type": "command",
+        "command": "./.github/hooks/run_validation_after_edits.sh",
+        "timeout": 1800
+      }
+    ]
+  }
+}

.github/hooks/run_validation_after_edits.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+payload="$(cat)"
+
+should_run="$(HOOK_PAYLOAD="$payload" python3 - <<'PY'
+import json
+import os
+import sys
+
+edit_tool_tokens = {
+    "edit",
+    "write",
+    "multi_edit",
+    "multiedit",
+    "apply_patch",
+    "create_file",
+    "edit_notebook_file",
+    "create_new_jupyter_notebook",
+    "mcp_github_create_or_update_file",
+    "mcp_io_github_git_create_or_update_file",
+}
+
+def walk(value):
+    if isinstance(value, dict):
+        for key, item in value.items():
+            yield str(key)
+            yield from walk(item)
+    elif isinstance(value, list):
+        for item in value:
+            yield from walk(item)
+    elif isinstance(value, str):
+        yield value
+
+raw = os.environ.get("HOOK_PAYLOAD", "").strip()
+if not raw:
+    print("skip")
+    raise SystemExit(0)
+
+try:
+    data = json.loads(raw)
+except json.JSONDecodeError:
+    print("skip")
+    raise SystemExit(0)
+
+haystack = "\n".join(s.lower() for s in walk(data))
+if any(token in haystack for token in edit_tool_tokens):
+    print("run")
+else:
+    print("skip")
+PY
+)"
+
+if [[ "$should_run" != "run" ]]; then
+    exit 0
+fi
+
+echo "[hook] File edit detected. Running validation commands..."
+
+echo "[hook] Running tests"
+if ! uv run pytest --no-cov; then
+    echo "[hook] Tests failed"
+    exit 2
+fi
+
+echo "[hook] Running prek"
+if ! uv run prek run --all-files; then
+    echo "[hook] Prek failed"
+    exit 2
+fi
+
+echo "[hook] Validation passed"