def rag_query(user_query: str, graph, llm) -> str:
    mentions = extract_entity_mentions(user_query)
    resolved = []

    for mention in mentions:
        candidates = graph.get_candidates(mention)
        if len(candidates) == 1:
            resolved.append(candidates[0])
            continue

        result = disambiguate(
            mention=mention,
            candidates=candidates,
            context_terms=extract_context_terms(user_query, exclude=mentions),
            query_time=datetime.utcnow(),
        )
        resolved.append(result)

        # Surface the decision before answering
        if result.confidence < 0.85:
            print(f"[disambiguation] '{mention}' → {result.display_name} "
                  f"(confidence: {result.confidence:.0%}, "
                  f"top alternative: {get_second_best(candidates, result.node_id)})")

    subgraph = graph.traverse(start_nodes=[r.node_id for r in resolved])
    return llm.generate(context=subgraph, query=user_query)