fix(tools): clarify search_code path: vs filename: (#2343)

[beejak]

Summary

• Extend the \search_code\ query schema description so \path:\ (directory prefix) vs \ilename:\ (file name) is explicit.
• When GitHub returns zero code results and the query uses \path:\ with a file-like token (contains ., no path separators), append a second text content block pointing agents at \ilename:.

Context

Addresses the confusion described in #2343 (silent empty results when \path:\ is used like a filename filter).

Test plan

• \go test ./pkg/github -run 'Test_SearchCode|TestPathQualifier' -count=1\
• \UPDATE_TOOLSNAPS=true go test ./pkg/github -run '^Test_SearchCode$' -count=1\ (schema snap updated)

Fixes #2343

[jluocsa]

Thanks for tackling #2343 — the description tweak plus a runtime nudge is a nice belt-and-braces approach.

A few observations on pathQualifierLooksLikeFilename that may be worth addressing before merge:

1. False positives on legitimate top-level paths. The heuristic is "no separator + contains a dot", which fires for real paths that happen to be dotted top-level files. For example:

• path:setup.py
• path:Makefile.am
• path:.gitignore
• path:requirements.txt

These are all valid path: qualifier values that match top-level files in many repos. When they legitimately return zero results (e.g., the file truly doesn't exist in any matched repo), the user gets a misleading hint telling them to switch to filename:. The hint message is only opt-in on zero-result queries, so the user-visible impact is bounded, but it's worth deciding whether the heuristic should also require something file-extension-shaped (e.g. an extension from a small allowlist, or "no leading dot").

2. Quoted multi-word path tokens get split. strings.Fields splits on whitespace, so a query like path:"some name.cs" becomes two tokens: path:"some and name.cs". The first happens to have no separator but no dot either, so it doesn't fire — but path:"foo.bar baz" does: the first token path:"foo.bar has a dot and no separator, triggering the hint on what was actually a valid quoted path. GitHub does support quoted qualifier values; consider stripping surrounding quotes or skipping tokens that begin a quoted span.

3. Polish — include the offending token in the hint. The hint currently always shows the generic WaitUtils.cs example. If you echo the user's actual token (e.g. did you mean filename:%s?), the message becomes directly actionable for agents that route on substrings.

Toolsnap update and unit test coverage both look good. The runtime-only message (i.e. not changing the schema for behavior) keeps the contract clean.