feat(search): use Home Assistant's reference graph for entity dependency discovery

AGENTS.md

@@ -1,3 +1,3 @@
 # CLAUDE.md
 
 Guidance for Claude Code when working with this repository.
@@ -417,6 +417,16 @@
 
 Test token centralized in `tests/test_constants.py`.
 
+**Unit tests** (`tests/src/unit/`, no Docker) — run them in parallel, as CI does
+(`pr.yml`); serial takes 25+ minutes for ~11k tests:
+
+```bash
+cd tests && uv run pytest src/unit/ -n auto --tb=short
+```
+
+`tests/pytest.ini` sets `--maxfail=3`, so a run reporting "3 failed" has stopped
+early rather than finished — pass `--maxfail=0` when you need the full picture.
+
 ### Code Quality
 
 C901 (mccabe complexity ≤10) is enforced repo-wide with zero per-file exemptions (issue #925 cleared the grandfathered list) — never reintroduce a `["C901"]` per-file-ignore; extract helpers instead.
@@ -896,7 +906,10 @@
 definition in `src/ha_mcp/tools/` — the `title=` kwarg and the summary
 paragraph of the docstring, or the `FEATURE_GATED_TOOLS` stub where a gated
 tool shows one instead. Editing that summary moves the English out from under
-six catalogs; the pipeline retranslates them. One deliberate exception: a
+six catalogs; the pipeline retranslates them. A parameter's
+`Field(description=...)` is NOT in the baseline — only the title and the
+docstring summary are — so editing one owes no translation work. One
+deliberate exception: a
 change to a feature-gated tool's PARSED docstring (its stub unchanged) is
 stub-review work, not translation work — the pipeline holds that baseline key
 stale, and the locale-sync run stays red until a human confirms the stub

src/ha_mcp/tools/smart_search/__init__.py

@@ -20,9 +20,8 @@
 # keep resolving.
 from ._config import (
     AUTOMATION_CONFIG_TIME_BUDGET,
-    BULK_REST_TIMEOUT,
-    BULK_WEBSOCKET_TIMEOUT,
     DEFAULT_CONCURRENCY_LIMIT,
+    ENTITY_REGISTRY_TIMEOUT,
     INDIVIDUAL_CONFIG_TIMEOUT,
     INDIVIDUAL_FETCH_BATCH_SIZE,
     SCENE_CONFIG_TIME_BUDGET,

src/ha_mcp/tools/smart_search/_config.py

@@ -10,13 +10,13 @@
 # Default concurrency limit for parallel operations
 DEFAULT_CONCURRENCY_LIMIT = 20
 
-# Bulk fetch timeouts (in seconds)
-BULK_REST_TIMEOUT = 5.0  # Timeout for bulk REST endpoint calls
-BULK_WEBSOCKET_TIMEOUT = 3.0  # Timeout for bulk WebSocket calls
+# Timeout for the entity-registry WebSocket list used by the scene walk.
+ENTITY_REGISTRY_TIMEOUT = 3.0
 
 
-# Attempt-C (per-id fallback; the letter predates the removal of the phantom
-# WS bulk tier in #1889 and is kept as a proper name) tuning knobs. Sourced from the resolved
+# Per-id config-fetch tuning knobs. The code calls this pass "Attempt C":
+# a proper name left from when two earlier bulk tiers were tried first,
+# both since removed as phantoms (#1889, #2258). It is now the only pass. Sourced from the resolved
 # Settings (issues #1538 / #1784) so the env var, the web Settings UI
 # override file, and the field defaults all flow through one precedence path
 # — and so add-on users (who cannot set raw env vars) can tune them from the
@@ -25,7 +25,7 @@
 # carry a restart-required notice in the UI).
 _settings = get_global_settings()
 
-# Time budgets for fallback individual fetching (in seconds).
+# Wall-clock budgets for the per-id config fetch (in seconds).
 AUTOMATION_CONFIG_TIME_BUDGET = _settings.automation_config_time_budget
 SCRIPT_CONFIG_TIME_BUDGET = _settings.script_config_time_budget
 SCENE_CONFIG_TIME_BUDGET = _settings.scene_config_time_budget