Skip to content

docs(readme): show what search_notes actually returns - #108

Merged
AlexMost merged 1 commit into
mainfrom
docs/readme-search-notes-section
Aug 26, 2026
Merged

AlexMost merged 1 commit into
mainfrom
docs/readme-search-notes-section

Conversation

@AlexMost

Copy link
Copy Markdown
Owner

Why

search_notes is 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 gave query_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:

  • An array query. Up to eight queries per call for synonyms, jargon, and translations, with the cross-language property spelled out — a note in one language found by a query in another. Nothing in the README hinted this was possible.
  • A real match object, showing 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.
  • Two properties that are easy to miss: RRF lifts a note found by several legs while keeping it a single entry (no caller-side merging, no double-counting), and the tool degrades to its lexical leg while the index builds, reporting semantic_status, rather than failing.

Regroup. The pre-filter section documents a search_notes parameter but sat after query_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.md pointer 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 — clean
  • prettier --check clean (also via pre-commit hook)
  • Checked every anchor the new and moved text links to: #search_notes and #query_notes resolve to headings in finding-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

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>
@AlexMost
AlexMost merged commit a92aecc into main Aug 26, 2026
2 checks passed
@AlexMost
AlexMost deleted the docs/readme-search-notes-section branch August 26, 2026 09:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant