fix: resolve merge conflicts and fix create_timeout_error context merge order

Address review comment from sergeykad: reverse context merge order in
create_timeout_error so explicit parameters (operation, timeout_seconds)
always take precedence over caller-provided context dict.

Resolve 3 merge conflicts with upstream/master:
- tools_config_helpers.py: import formatting + raise_tool_error
- tools_search.py: imports, search error handling, new ha_get_states tool
- test_tools_voice_assistant.py: import ordering

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: kingpanther13

.github/workflows/e2e-tests.yml

@@ -20,6 +20,8 @@ permissions:
 env:
   PYTHON_VERSION: "3.13"
   UV_CACHE_DIR: /tmp/.uv-cache
+  # renovate: datasource=docker depName=ghcr.io/home-assistant/home-assistant
+  HA_IMAGE_GHCR: "ghcr.io/home-assistant/home-assistant:2026.1.3"
 
 jobs:
   # Comprehensive E2E validation for main branch
@@ -33,6 +35,8 @@ jobs:
 
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@v3
+      with:
+        cache-binary: true
 
     - name: Install uv
       uses: astral-sh/setup-uv@v7
@@ -45,6 +49,37 @@ jobs:
     - name: Install dependencies
       run: uv sync --all-extras --dev
 
+    - name: Cache HA Docker image
+      id: cache-ha-image
+      uses: actions/cache@v4
+      with:
+        path: /tmp/ha-image.tar
+        key: ha-image-${{ env.HA_IMAGE_GHCR }}-${{ runner.arch }}
+
+    - name: Load cached HA image
+      if: steps.cache-ha-image.outputs.cache-hit == 'true'
+      run: docker load -i /tmp/ha-image.tar
+
+    - name: Pull HA image (GHCR → Docker Hub fallback)
+      if: steps.cache-ha-image.outputs.cache-hit != 'true'
+      run: |
+        HA_VERSION="${HA_IMAGE_GHCR##*:}"
+        HA_IMAGE_DOCKERHUB="homeassistant/home-assistant:${HA_VERSION}"
+        for registry in "$HA_IMAGE_GHCR" "$HA_IMAGE_DOCKERHUB"; do
+          echo "Trying $registry..."
+          if docker pull "$registry"; then
+            if [ "$registry" != "$HA_IMAGE_GHCR" ]; then
+              docker tag "$registry" "$HA_IMAGE_GHCR"
+            fi
+            docker save "$HA_IMAGE_GHCR" -o /tmp/ha-image.tar
+            echo "Pulled and cached from $registry"
+            exit 0
+          fi
+          echo "Failed to pull from $registry, trying next..."
+          sleep 15
+        done
+        echo "All registries failed" && exit 1
+
     - name: Run full E2E test suite
       run: |
         echo "🚀 Running full E2E test suite with 3 workers..."

.github/workflows/pr.yml

@@ -10,8 +10,43 @@ on:
 env:
   PYTHON_VERSION: "3.13"
   UV_CACHE_DIR: /tmp/.uv-cache
+  # renovate: datasource=docker depName=ghcr.io/home-assistant/home-assistant
+  HA_IMAGE_GHCR: "ghcr.io/home-assistant/home-assistant:2026.1.3"
 
 jobs:
+  lint:
+    name: Ruff Lint
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/astral-sh/uv:0.9.30-python3.13-bookworm-slim
+    timeout-minutes: 5
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Install dependencies
+      run: uv sync --dev
+
+    - name: Run ruff check
+      run: uv run ruff check src/ tests/
+
+  # Fast unit tests (no Docker, no HA instance needed)
+  unit-tests:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/astral-sh/uv:0.9.30-python3.13-bookworm-slim
+    timeout-minutes: 5
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Install dependencies
+      run: uv sync --all-extras --dev
+
+    - name: Run unit tests
+      run: uv run pytest tests/src/unit/ -n auto --tb=short -v
+
   # Comprehensive E2E validation for all PRs
   e2e-validation:
     name: E2E Validation (${{ matrix.os }})
@@ -34,6 +69,8 @@ jobs:
 
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@v3
+      with:
+        cache-binary: true
 
     - name: Install uv
       uses: astral-sh/setup-uv@v7
@@ -46,6 +83,37 @@ jobs:
     - name: Install dependencies
       run: uv sync --all-extras --dev
 
+    - name: Cache HA Docker image
+      id: cache-ha-image
+      uses: actions/cache@v4
+      with:
+        path: /tmp/ha-image.tar
+        key: ha-image-${{ env.HA_IMAGE_GHCR }}-${{ runner.arch }}
+
+    - name: Load cached HA image
+      if: steps.cache-ha-image.outputs.cache-hit == 'true'
+      run: docker load -i /tmp/ha-image.tar
+
+    - name: Pull HA image (GHCR → Docker Hub fallback)
+      if: steps.cache-ha-image.outputs.cache-hit != 'true'
+      run: |
+        HA_VERSION="${HA_IMAGE_GHCR##*:}"
+        HA_IMAGE_DOCKERHUB="homeassistant/home-assistant:${HA_VERSION}"
+        for registry in "$HA_IMAGE_GHCR" "$HA_IMAGE_DOCKERHUB"; do
+          echo "Trying $registry..."
+          if docker pull "$registry"; then
+            if [ "$registry" != "$HA_IMAGE_GHCR" ]; then
+              docker tag "$registry" "$HA_IMAGE_GHCR"
+            fi
+            docker save "$HA_IMAGE_GHCR" -o /tmp/ha-image.tar
+            echo "Pulled and cached from $registry"
+            exit 0
+          fi
+          echo "Failed to pull from $registry, trying next..."
+          sleep 15
+        done
+        echo "All registries failed" && exit 1
+
     - name: Run full E2E test suite
       run: |
         echo "🚀 Running full E2E test suite with ${{ matrix.pytest_workers }} workers..."
@@ -68,6 +136,8 @@ jobs:
 
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@v3
+      with:
+        cache-binary: true
 
     - name: Install uv
       uses: astral-sh/setup-uv@v7

.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+  - repo: local
+    hooks:
+      - id: unit-tests
+        name: unit tests
+        entry: uv run pytest tests/src/unit/ -n auto -m "not slow" --tb=short -q
+        language: system
+        pass_filenames: false
+        files: ^(src/|tests/|pyproject\.toml)

AGENTS.md

@@ -437,6 +437,20 @@ Balance improvement against regression risk. Consider:
 | **Tests exist, quality is low** | Improve test quality if it's straightforward (better assertions, clearer names, remove duplication) |
 | **Code quality is really low** | Open an issue describing the technical debt instead of fixing it inline |
 
+### Test Coverage Requirements
+
+**When tests ARE required:**
+- New MCP tools in `src/ha_mcp/tools/` without any E2E tests
+- Tools that previously had NO tests — add E2E tests even if not part of current PR
+- Core functionality changes in `client/`, `server.py`, or `errors.py` without coverage
+- Bug fixes without regression tests
+
+**When tests may NOT be required:**
+- Refactoring with existing comprehensive test coverage
+- Documentation-only changes (`*.md` files)
+- Minor parameter additions to well-tested tools
+- Internal utilities already covered by E2E tests
+
 **Examples:**
 
 ```python
@@ -598,21 +612,48 @@ def register_<domain>_tools(mcp, client, **kwargs):
 ```
 
 ### Safety Annotations
-| Annotation | Use For |
-|------------|---------|
-| `readOnlyHint: True` | No side effects |
-| `idempotentHint: True` | Safe to retry |
-| `destructiveHint: True` | Deletes data |
+| Annotation | Default | Use For |
+|------------|---------|--------|
+| `readOnlyHint: True` | `False` | Tool does not modify its environment |
+| `destructiveHint: True` | `True` | Tool may perform destructive updates (only meaningful when `readOnlyHint` is false). Set to `False` for non-destructive writes (e.g., creating a record) |
+| `idempotentHint: True` | `False` | Repeated calls with same args have no additional effect (only meaningful when `readOnlyHint` is false) |
 
 ### Error Handling
-Use structured errors from `errors.py`:
+
+**Always use the dedicated error functions** from `errors.py` and `helpers.py`. Never construct raw error dicts manually — the helpers ensure consistent structure, error codes, and suggestions across all tools.
+
+**Domain-specific errors** (`errors.py`) — use these when the error type is known:
 ```python
-from ..errors import create_error_response, ErrorCode
-return create_error_response(
-    code=ErrorCode.ENTITY_NOT_FOUND,
-    message="Entity not found",
-    suggestions=["Use ha_search_entities() to find valid IDs"]
-)
+from ..errors import create_entity_not_found_error, create_validation_error, create_service_error
+
+# Entity lookup failures (404 / not found)
+return create_entity_not_found_error(entity_id, details=str(e))
+
+# Invalid parameters
+return create_validation_error("Invalid format", parameter="entity_ids", details=str(e))
+
+# Service call failures
+return create_service_error(domain, service, message=f"Service call failed: {e}", details=str(e))
+```
+
+Available helpers: `create_entity_not_found_error`, `create_connection_error`, `create_auth_error`, `create_service_error`, `create_validation_error`, `create_config_error`, `create_timeout_error`, `create_resource_not_found_error`, and the generic `create_error_response`.
+
+**Catch-all exception handler** (`helpers.py`) — use in `except Exception` blocks:
+```python
+from .helpers import exception_to_structured_error
+
+except Exception as e:
+    return exception_to_structured_error(e, context={"entity_id": entity_id})
+```
+
+**Pattern for tools**: Use `exception_to_structured_error` as the catch-all — it already classifies 404s, auth errors, timeouts, etc. based on exception type and message. Pass `context={"entity_id": ...}` so it can produce `ENTITY_NOT_FOUND` for 404 errors automatically. No manual 404 string matching needed:
+```python
+try:
+    result = await client.get_entity_state(entity_id)
+    return await add_timezone_metadata(client, result)
+except Exception as e:
+    error_response = exception_to_structured_error(e, context={"entity_id": entity_id})
+    return await add_timezone_metadata(client, error_response)
 ```
 
 ### Return Values

CONTRIBUTING.md

@@ -6,9 +6,10 @@ Thank you for your interest in contributing!
 
 1. **Fork and clone** the repository
 2. **Install**: `uv sync --group dev`
-3. **Test**: `uv run pytest tests/src/e2e/ -v` (requires Docker)
-4. **Make changes** and commit
-5. **Open Pull Request**
+3. **Install hooks**: `uv run pre-commit install`
+4. **Test**: `uv run pytest tests/src/e2e/ -v` (requires Docker)
+5. **Make changes** and commit
+6. **Open Pull Request**
 
 ## 🧪 Testing
 
@@ -20,6 +21,7 @@ See **[tests/README.md](tests/README.md)**.
 ```bash
 cp .env.example .env    # Edit with your HA details
 uv sync --group dev
+uv run pre-commit install  # Install pre-commit hooks
 ```
 
 **Code quality:**
@@ -29,6 +31,8 @@ uv run ruff check --fix src/ tests/ # Lint
 uv run mypy src/                   # Type check
 ```
 
+On every commit, a `pre-commit` hook runs `ruff check --fix` to auto-fix and catch lint violations. The **Ruff Lint** CI job also enforces this on pull requests.
+
 ## 📋 Guidelines
 
 - **Code**: Follow existing patterns, add type hints, test new features

README.md

@@ -192,14 +192,22 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## 👥 Contributors
 
-- **[@julienld](https://github.com/julienld)** — Project maintainer & core contributor.
-- **[@kingbear2](https://github.com/kingbear2)** — Windows UV setup guide.
-- **[@sergeykad](https://github.com/sergeykad)** — Dashboard card-level CRUD operations, better changelogs and removed the dependency to textdistance/numpy.
-- **[@konradwalsh](https://github.com/konradwalsh)** — Financial support via [GitHub Sponsors](https://github.com/sponsors/julienld). Thank you! ☕
-- **[@cj-elevate](https://github.com/cj-elevate)** — Integration & entity management tools (enable/disable/delete).
-- **[@kingpanther13](https://github.com/kingpanther13)** — Dev channel documentation, bulk control validation, OAuth 2.1 docs, tool consolidation, error handling improvements, and native solutions guidance.
+### Maintainers
+
+- **[@julienld](https://github.com/julienld)** — Project creator & core maintainer.
+- **[@sergeykad](https://github.com/sergeykad)** — Dashboard CRUD, search pagination, `__main__` security refactor, pre-commit hooks & CI lint, addon Docker fixes, `.gitattributes` enforcement, human-readable log timestamps, and removed the textdistance/numpy dependency.
+- **[@kingpanther13](https://github.com/kingpanther13)** — Dev channel documentation, bulk control validation, OAuth 2.1 docs, tool consolidation, error handling improvements, native solutions guidance, default dashboard editing fix, and search response optimization.
+
+### Contributors
+
+- **[@airlabno](https://github.com/airlabno)** — Support for `data` field in schedule time blocks.
+- **[@ryphez](https://github.com/ryphez)** — Codex Desktop UI MCP quick setup guide.
 - **[@Danm72](https://github.com/Danm72)** — Entity registry tools (`ha_set_entity`, `ha_get_entity`) for managing entity properties.
 - **[@Raygooo](https://github.com/Raygooo)** — SOCKS proxy support.
+- **[@cj-elevate](https://github.com/cj-elevate)** — Integration & entity management tools (enable/disable/delete).
+- **[@maxperron](https://github.com/maxperron)** — Beta testing.
+- **[@kingbear2](https://github.com/kingbear2)** — Windows UV setup guide.
+- **[@konradwalsh](https://github.com/konradwalsh)** — Financial support via [GitHub Sponsors](https://github.com/sponsors/julienld). Thank you! ☕
 
 ---
 

custom_components/ha_mcp_tools/__init__.py

@@ -16,7 +16,12 @@
 
 import voluptuous as vol
 from homeassistant.config_entries import ConfigEntry
-from homeassistant.core import HomeAssistant, ServiceCall, ServiceResponse, SupportsResponse
+from homeassistant.core import (
+    HomeAssistant,
+    ServiceCall,
+    ServiceResponse,
+    SupportsResponse,
+)
 from homeassistant.helpers import config_validation as cv
 
 from .const import ALLOWED_READ_DIRS, ALLOWED_WRITE_DIRS, DOMAIN
@@ -137,12 +142,7 @@ def _is_path_allowed_for_read(config_dir: Path, rel_path: str) -> bool:
         return True
 
     # Check for custom_components/**/*.py pattern
-    if fnmatch.fnmatch(normalized, "custom_components/*/*.py"):
-        return True
-    if fnmatch.fnmatch(normalized, "custom_components/**/*.py"):
-        return True
-
-    return False
+    return fnmatch.fnmatch(normalized, "custom_components/**/*.py")
 
 
 def _mask_secrets_content(content: str) -> str:
@@ -296,7 +296,7 @@ async def handle_read_file(call: ServiceCall) -> ServiceResponse:
             content = await hass.async_add_executor_job(target_file.read_text)
 
             # Apply special handling for specific files
-            normalized = os.path.normpath(rel_path)
+            normalized = os.path.normpath(rel_path)  # noqa: ASYNC240
 
             # Mask secrets.yaml
             if normalized == "secrets.yaml":

homeassistant-addon/start.py

@@ -135,7 +135,7 @@ def main() -> int:
     # Import and run MCP server directly
     try:
         log_info("Importing ha_mcp module...")
-        from ha_mcp.__main__ import mcp, _get_timestamped_uvicorn_log_config
+        from ha_mcp.__main__ import _get_timestamped_uvicorn_log_config, mcp
 
         log_info("Starting MCP server...")
         mcp.run(