docs(internal): correct the reference-graph ranking comment (#2285)

* docs(internal): correct the reference-graph ranking comment

_GRAPH_HIT_SCORE said fuzzy scores are capped at 100, so a confirmed reference
ranks at or above every fuzzy name match. The cap lives in _search_in_dict and
bounds the config-body score. The fuzzy name score comes from
_calculate_entity_score, which accumulates its bonuses with no ceiling, so a
name echoing the queried entity's words can pass 100 on its own and outrank a
graph hit's fixed 100.

The exact-mode half of the claim holds and stays. The comment now states what
fuzzy mode does, scoped to graph-ONLY hits (_merge_graph_hits leaves an
already-scored record's score alone) and to the case where visibility
enforcement does not scrub the record.

Also name the scene caller in _individual_fetch_budgeted's deprioritize
paragraph: it passes the set too, alongside automation and script.

* docs(internal): qualify the graph-hit score impossibility claim

The comment said no value of _GRAPH_HIT_SCORE makes fuzzy mode
symmetric, and rested that on _calculate_entity_score having no
ceiling. The absent clamp does not carry the claim: that score is a sum
of bounded parts, so a large enough constant would dominate it. What
actually rules such a constant out is the exact-mode property the
paragraph above asserts - every survivor scores 100 there, and raising
the constant breaks that tie. Name the condition instead of leaving it
implicit.

* docs(internal): say the name score is not capped, not that it is unbounded

The comment described `_calculate_entity_score` as accumulating "without a
ceiling". The function is a finite sum of bounded terms — three
`calculate_*_ratio` helpers that each return 0-100, plus fixed exact/partial
and keyword bonuses — so a bound does exist. What matters for the surrounding
argument is only that the bound is not 100, which is what the sentence now
says. The rest of the comment is unchanged.

---------

Co-authored-by: kingpanther13 <25392815+kingpanther13@users.noreply.github.com>

Author: Patch76

src/ha_mcp/tools/smart_search/_fetch.py

@@ -201,7 +201,7 @@ async def _individual_fetch_budgeted(
 
         ``deprioritize`` moves the named ids to the BACK of the queue while
         keeping every id in it (relative order preserved within each group).
-        The automation and script callers pass the ids Home Assistant's
+        The automation, script and scene callers pass the ids Home Assistant's
         reference graph already confirmed reference the queried entity: their
         match status is settled without reading the body, so under budget
         pressure the budget belongs to the ids that are NOT in the set, which

src/ha_mcp/tools/smart_search/_graph.py

@@ -357,10 +357,17 @@ async def fetch_related_buckets(client: Any, entity_id: str) -> GraphResult | No
 # Score assigned to a reference-graph hit. In the default exact mode every
 # surviving match scores exactly 100 (``_score_deep_match`` takes the max of
 # two 0-or-100 signals against a threshold of 100), so a graph hit sorts
-# indistinguishably from a body hit. Fuzzy scores are capped at 100 too, so
-# there a confirmed reference ranks at or above every fuzzy name match, which
-# is the intent: HA naming the reference is exact evidence, not an
-# approximate one.
+# indistinguishably from a body hit.
+#
+# Fuzzy mode is not symmetric, and no value here makes it so without breaking
+# the tie above: the 100 cap belongs to the config-body score
+# (``_search_in_dict``), while the NAME score from ``_calculate_entity_score``
+# is not capped at 100 — a name echoing the queried entity's words can pass
+# 100 on its own. So with ``exact_match=False`` a graph-ONLY hit
+# (``_merge_graph_hits`` leaves an already-scored record's score alone) can sort
+# below a match that merely resembles the query, and land on a later page under
+# a small ``limit``. It is still counted in ``total_matches`` unless visibility
+# enforcement scrubs it.
 _GRAPH_HIT_SCORE = 100