homeassistant-ai
diff --git a/‎.github/workflows/pr.yml‎
Lines changed: 62 additions & 0 deletions b/‎.github/workflows/pr.yml‎
Lines changed: 62 additions & 0 deletions
diff --git a/‎.github/workflows/sync-integration-mirror.yml‎
Lines changed: 22 additions & 2 deletions b/‎.github/workflows/sync-integration-mirror.yml‎
Lines changed: 22 additions & 2 deletions
diff --git a/‎AGENTS.md‎
Lines changed: 9 additions & 0 deletions b/‎AGENTS.md‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎custom_components/ha_mcp_tools/websocket_api.py‎
Lines changed: 109 additions & 6 deletions b/‎custom_components/ha_mcp_tools/websocket_api.py‎
Lines changed: 109 additions & 6 deletions
@@ -27,6 +27,68 @@ jobs:
   # DO matter and always count as code. On non-PR events (manual dispatch)
   # always run. Consumed by e2e-validation's `if:` below — a job-level skip
   # reports Success to a required check (a workflow path-skip would not).
+  # PR-time guard for the release-cycle version invariant (AGENTS.md "Version
+  # bumps ride the stable release cycle"): a PR that changes the component
+  # while the manifest version EQUALS the mirror's latest stable release would
+  # merge changes onto an already-shipped version — the mirror's stable tag
+  # step skips existing tags and v<VER>-dev.N pre-release tags sort BELOW the
+  # equal stable tag, so the changes would silently reach nobody. Level with
+  # stable means: bump once to open the pending version. The gate fires only
+  # on a provable component diff and fails open (with a warning) when the base
+  # or the mirror API cannot be read — the mirror sync's stable tag step
+  # carries the loud release-time backstop for what this check cannot see
+  # (stable shipping while the PR sits idle re-runs no PR checks).
+  component-version-gate:
+    name: Component Version Gate
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v7
+      - name: Fail component changes riding an already-released version
+        env:
+          BASE_REF: ${{ github.base_ref }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if ! git fetch --depth=1 origin "$BASE_REF" \
+            || ! base_sha=$(git rev-parse "origin/$BASE_REF"); then
+            echo "::warning::could not resolve the base ref - skipping the version gate (the release-time backstop still applies)"
+            exit 0
+          fi
+          if git diff --quiet "$base_sha" HEAD -- custom_components/ha_mcp_tools; then
+            echo "no component changes - gate not applicable"
+            exit 0
+          fi
+          VER=$(python3 -c "import json; print(json.load(open('custom_components/ha_mcp_tools/manifest.json'))['version'])")
+          if ! latest=$(gh api repos/homeassistant-ai/ha-mcp-integration/releases/latest --jq .tag_name); then
+            echo "::warning::could not read the mirror's latest stable release - skipping the version gate (the release-time backstop still applies)"
+            exit 0
+          fi
+          stable="${latest#v}"
+          echo "component changed; manifest=${VER} released-stable=${stable}"
+          # Strict version comparison, not equality: a version BEHIND the
+          # released stable (a stale tree or bad merge resurrecting an old
+          # manifest) must fail here too, not slip through to a late
+          # release-time failure. sort -V gives semver ordering; both inputs
+          # come from our own manifest / release automation.
+          if [ "$VER" = "$stable" ]; then
+            verdict=equal
+          elif [ "$(printf '%s\n%s\n' "$stable" "$VER" | sort -V | tail -1)" = "$VER" ]; then
+            verdict=ahead
+          else
+            verdict=behind
+          fi
+          case "$verdict" in
+            ahead)
+              echo "version gate ok: pending ${VER} is strictly ahead of released ${stable}" ;;
+            equal)
+              echo "::error::This PR changes custom_components/ha_mcp_tools but keeps the component version at ${VER}, which is already released as the mirror's latest stable - merged this way the changes never ship (the stable tag step skips existing tags; dev pre-release tags sort below the equal stable). Master is level with stable: bump manifest.json + const.py (and the parity-test literal) once to open the next pending version, per AGENTS.md 'Version bumps ride the stable release cycle'."
+              exit 1 ;;
+            behind)
+              echo "::error::This PR changes custom_components/ha_mcp_tools with version ${VER}, which is BEHIND the mirror's released stable ${stable} - a stale tree or bad merge resurrected an old version. Restore the version to lead the released stable (per AGENTS.md 'Version bumps ride the stable release cycle')."
+              exit 1 ;;
+          esac
+
   changes:
     name: Detect relevant changes
     runs-on: ubuntu-latest
 
@@ -268,8 +268,28 @@ jobs:
           # aborts loud instead.
           existing=$(git -C /tmp/mirror ls-remote --tags origin "refs/tags/v${VER}")
           if [ -n "$existing" ]; then
-            echo "mirror tag v${VER} exists"
-            exit 0
+            # Stranded-changes backstop (issue #2008 review follow-up): the
+            # idempotent skip is harmless ONLY when the already-tagged content
+            # matches the current snapshot (a hotfix without component
+            # changes). If master took component changes WITHOUT a version
+            # bump after v${VER} went stable — e.g. a PR opened while the
+            # version was still pending merged after the stable cut — a
+            # silent skip here strands them: no mirror release ever carries
+            # them, and v${VER}-dev.N pre-release tags sort BELOW the equal
+            # stable tag so even pre-release users never see them. Fail loud
+            # with the bump instruction instead. Tag-fetch failure keeps the
+            # old silent skip (a network blip must not fail the release) but
+            # says so.
+            if ! git -C /tmp/mirror fetch --quiet --depth=1 origin "refs/tags/v${VER}:refs/tags/v${VER}"; then
+              echo "::warning::mirror tag v${VER} exists but could not be fetched for the stranded-changes check - skipping the stable tag as before"
+              exit 0
+            fi
+            if git -C /tmp/mirror diff --quiet "v${VER}" HEAD -- custom_components; then
+              echo "mirror tag v${VER} exists and the component snapshot is identical - nothing new to release"
+              exit 0
+            fi
+            echo "::error::mirror tag v${VER} already exists but the current component snapshot DIFFERS from its content - master took component changes without a version bump after v${VER} went stable; skipping would strand them with no installable release. Bump manifest.json + const.py (and the parity-test literal) to open the next pending version per AGENTS.md 'Version bumps ride the stable release cycle', then let the next stable carry the stranded changes."
+            exit 1
           fi
           python3 scripts/build_mirror_release_notes.py \
             --component-version "$VER" \
 
@@ -674,6 +674,15 @@ fully validate a component change before merge.
     go straight to that minor, not an extra patch. Never go past the current
     pending version otherwise; per-revision bumps skip never-shipped numbers and
     desync the version from the release cycle.
+  - CI enforces the level-with-stable case twice: the PR-level **Component
+    Version Gate** fails a component change whose manifest version does not
+    strictly lead the mirror's released stable (equal = bump to open the
+    pending version; behind = a stale tree or bad merge resurrected an old
+    version), and the mirror sync's stable tag step fails loud
+    when an already-tagged version's component content has drifted (changes
+    merged onto a shipped version would otherwise strand with no installable
+    release — the gap is a PR opened while a version is pending that merges
+    only after that version goes stable, which re-runs no PR checks).
 - **When the change adds a service or argument the server depends on**, this PR
   must **open a fresh pending component version** (bump `manifest.json` +
   `COMPONENT_VERSION`) and raise `MIN_COMPONENT_VERSION` in
 
@@ -357,6 +357,13 @@
     "backup_prep",
     "registries",
     "dashboards",
+    # A flag, not a standalone command: gates the additive whole-document
+    # search-result keys on ``ha_mcp_tools/dashboards`` mode=search
+    # (``document_matches`` + ``yaml_skipped`` + ``load_failed``, issue #2008).
+    # The server's ha_search dashboard bucket routes through the component only
+    # when this is advertised — an older component without the keys would
+    # silently narrow coverage to the card-scoped walk and hide load failures.
+    "dashboards_doc_search",
     "services_list",
     "reference_data",
     # A flag, not a standalone command: gates the optional ``visibility`` param
@@ -4086,6 +4093,15 @@ def _do_dashboards(
             "available": True,
             "matches": matches,
             "truncated": truncated,
+            # ``dashboards_doc_search`` additions (issue #2008): the whole-
+            # document per-dashboard verdicts + honesty counters the server's
+            # ha_search dashboard bucket needs. Additive — a pre-#2008 server
+            # ignores them.
+            "document_matches": _dashboard_document_matches(
+                prepped.get("docs") or [], query_lower
+            ),
+            "yaml_skipped": prepped.get("yaml_skipped", 0),
+            "load_failed": prepped.get("load_failed", 0),
         }
     return {"mode": "list", "available": True, "dashboards": prepped.get("rows") or []}
 
@@ -4108,7 +4124,11 @@ async def _dashboards_prep(hass: HomeAssistant, msg: dict[str, Any]) -> dict[str
     if mode == "get":
         prepped.update(await _dashboard_get_config(dashboards_map, msg.get("url_path")))
     elif mode == "search":
-        prepped["docs"] = await _dashboard_search_docs(dashboards_map)
+        (
+            prepped["docs"],
+            prepped["yaml_skipped"],
+            prepped["load_failed"],
+        ) = await _dashboard_search_docs(dashboards_map)
     else:
         prepped["rows"] = _dashboard_list_rows(dashboards_map)
     return {"prepped": prepped}
@@ -4198,35 +4218,72 @@ async def _dashboard_get_config(
 
 async def _dashboard_search_docs(
     dashboards_map: Mapping[Any, Any],
-) -> list[dict[str, Any]]:
+) -> tuple[list[dict[str, Any]], int, int]:
     """Load every STORAGE dashboard's config for the ``search`` walk.
 
     Only storage dashboards are loaded — YAML bodies are never searched/emitted.
-    A per-dashboard load error is skipped (fail-soft) rather than failing the
-    whole search. Returns ``[{url_path, title, config}, ...]`` plain dicts.
+    Returns ``(docs, yaml_skipped, load_failed)``: ``docs`` are
+    ``[{url_path, title, registry_title, config}, ...]`` plain dicts —
+    ``title`` stays the config body's (the card-scoped ``matches`` records pin
+    byte parity with the server's legacy MODE 4 walk on it) while the additive
+    ``registry_title`` carries the list-row metadata title that
+    ``document_matches`` emits (what the legacy ha_search bucket records
+    carry); ``yaml_skipped`` counts
+    the YAML-mode entries this walk never reads, INCLUDING a default dashboard
+    forced to YAML (``lovelace: mode: yaml``), which has no ``list`` row for
+    the server to count — the server treats a non-zero count as its
+    fall-back-to-legacy signal, since the legacy walk DOES read YAML bodies
+    and coverage must not depend on which path served (issue #2008 review);
+    ``load_failed`` counts storage
+    dashboards whose config load raised or returned a non-dict — real gaps the
+    caller must surface as partial rather than fail-soft into a clean-looking
+    result. A ``ConfigNotFound`` load is a clean skip, not a failure: an
+    auto-generated (never taken control of) dashboard has no stored config to
+    scan. If core drift breaks the guarded ``ConfigNotFound`` import, those
+    loads degrade to ``load_failed`` — over-reported as partial, never silent.
     """
+    try:
+        from homeassistant.components.lovelace.const import ConfigNotFound
+    except Exception:  # pragma: no cover - defensive; core drift
+        ConfigNotFound = None
+
     docs: list[dict[str, Any]] = []
+    yaml_skipped = 0
+    load_failed = 0
     for url_path, dash in dashboards_map.items():
+        if _dashboard_mode(dash) == _LOVELACE_MODE_YAML:
+            yaml_skipped += 1
+            continue
         if _dashboard_mode(dash) != _LOVELACE_MODE_STORAGE:
             continue
         loader = getattr(dash, "async_load", None)
         if not callable(loader):
             continue
         try:
             config = await loader(False)
-        except Exception:  # skip an unreadable dashboard, keep going (fail-soft)
+        except Exception as err:
+            if ConfigNotFound is not None and isinstance(err, ConfigNotFound):
+                # Auto-generated dashboard: nothing stored, nothing to scan.
+                continue
+            load_failed += 1
             continue
         if not isinstance(config, dict):
+            load_failed += 1
             continue
+        meta = getattr(dash, "config", None)
+        registry_title = meta.get("title") if isinstance(meta, Mapping) else None
         title = config.get("title")
         docs.append(
             {
                 "url_path": url_path,
                 "title": str(title) if title is not None else None,
+                "registry_title": (
+                    str(registry_title) if registry_title is not None else None
+                ),
                 "config": config,
             }
         )
-    return docs
+    return docs, yaml_skipped, load_failed
 
 
 def _dashboard_mode(dash: Any) -> str | None:
@@ -4235,6 +4292,52 @@ def _dashboard_mode(dash: Any) -> str | None:
     return str(mode) if isinstance(mode, str) else None
 
 
+def _dashboard_document_matches(
+    docs: list[dict[str, Any]], query_lower: str
+) -> list[dict[str, Any]]:
+    """Per-dashboard whole-document verdicts: ``[{url_path, title}, ...]``.
+
+    One entry per doc whose ENTIRE config contains ``query_lower`` — the
+    coverage the server's legacy ``_search_in_dict`` walk provides (view
+    titles, dashboard-level keys, every leaf), which the card-scoped
+    ``matches`` walk deliberately narrows to. ``title`` is the registry
+    metadata's (falling back to the body's) — what the legacy ha_search
+    bucket records carry. An empty query matches nothing. Bounded by the
+    dashboard count, so no cap/truncation applies.
+    """
+    if not query_lower:
+        return []
+    return [
+        {
+            "url_path": doc.get("url_path"),
+            "title": doc.get("registry_title") or doc.get("title"),
+        }
+        for doc in docs
+        if _doc_contains(doc.get("config"), query_lower)
+    ]
+
+
+def _doc_contains(data: Any, query_lower: str) -> bool:
+    """Case-insensitive substring test over keys and every leaf of a config.
+
+    Exact port of the server's ``_search_in_dict_exact`` (keys + string
+    leaves + ``str()`` of non-None scalars) so the component-served verdict
+    matches the legacy walk's, leaf for leaf.
+    """
+    if isinstance(data, dict):
+        return any(
+            query_lower in str(key).lower() or _doc_contains(value, query_lower)
+            for key, value in data.items()
+        )
+    if isinstance(data, list):
+        return any(_doc_contains(item, query_lower) for item in data)
+    if isinstance(data, str):
+        return query_lower in data.lower()
+    if data is not None:
+        return query_lower in str(data).lower()
+    return False
+
+
 def _search_dashboard_docs(
     docs: list[dict[str, Any]], query_lower: str
 ) -> tuple[list[dict[str, Any]], bool]: