docs(readme): show what search_notes actually returns - #108
Merged
Merged
Conversation
search_notes is the flagship tool but appeared only in prose — six mentions of "hybrid search", not one call or response. query_notes, an auxiliary tool, had the only worked example in the file. Invert that. - Add a "One search, both legs" section: an array query (synonyms and translations across languages), a real match object, and what `found_in` / `blocks[]` buy the caller. Block-level line ranges are where the tagline's "low-token retrieval" comes from, and nothing in the README showed them. - State the two properties that are easy to miss: RRF lifts a note found by several legs while keeping it a single entry, and the tool degrades to its lexical leg (reporting `semantic_status`) instead of failing while the index builds. - Regroup so the pre-filter section follows the search section it describes, ahead of query_notes: search -> its filter -> structured queries. Text unchanged, order only. - Drop the guide pointer above these sections; each section now carries its own precise reference link. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
search_notesis the flagship tool, but the README only ever talked about it — six prose mentions of "hybrid search" and not a single call or response. Meanwhile #107 gavequery_notes, an auxiliary tool, the only worked example in the file. This inverts that asymmetry.What changed
New section — 🔭 One search, both legs, placed ahead of the query section:
found_in: ["semantic", "lexical:title"]alongside its per-leg evidence. The provenance array is the most convincing artifact the server produces: it shows both legs ran and fused, which no amount of prose about "hybrid" conveys.blocks[]with line ranges. The tagline promises "low-token retrieval" and the README never showed where that comes from — the assistant pulls the matched section, not the whole note.semantic_status, rather than failing.Regroup. The pre-filter section documents a
search_notesparameter but sat afterquery_notes. It now follows the section it describes: search → its filter → structured queries. Section text is unchanged; only the order moved.One deletion. The
→ See docs/guide/finding-notes.mdpointer above these sections is gone — each of the three sections now carries its own precise reference link, so it had become a vaguer duplicate of the three below it.Deliberately left alone: the 🧠 hybrid-search bullet and the "Two superpowers" table. They work as the short pitch; the new section expands on them rather than repeating them.
Verification
npm test— 1288 passed (104 files)npm run lint,npm run typecheck— cleanprettier --checkclean (also via pre-commit hook)#search_notesand#query_notesresolve to headings infinding-notes.md, and the moved pre-filter link still resolves to### Pre-filter (\filter` parameter)`.Docs-only, not planned ahead, so no issue trailer.
🤖 Generated with Claude Code