Guard incomplete clangd references

AGENTS.md

@@ -76,9 +76,13 @@ The helper talks to `clangd` using an existing `compile_commands.json`. It
 defaults to `out/build/windows-clangcl-asan` and then `out/build/android-arm64`;
 pass `--compile-commands-dir` or set `PP_CLANGD_COMPILE_COMMANDS_DIR` when using
 another Ninja build tree. Use `--name` and `--max-results` to keep output small.
-References are fast/current-translation-unit by default; add
-`--background-index` only when broader cross-file references are worth the extra
-indexing work.
+Treat symbol, hover, declaration, definition, and implementation lookups as the
+reliable path. Reference lookups are riskier because a one-shot clangd process
+may not have a complete project index; the helper refuses reference queries
+unless callers pass `--background-index` for broader best-effort results or
+`--allow-incomplete-references` for explicitly current-translation-unit-only
+results. Do not use incomplete reference output as proof that a symbol has no
+other users.
 
 ## Current Architecture Direction