boost-skill-cli 1.0.316__tar.gz → 1.0.317__tar.gz

{boost_skill_cli-1.0.316 → boost_skill_cli-1.0.317}/CLAUDE.md

@@ -228,9 +228,16 @@ each agent's skills dir, and updating the lock file.
 **Search has two engines**, both in `core/`: `rag.py` is the always-on,
 zero-dependency BM25 engine (full-content index, auto-builds on first
 search — this is what the required `eval` gate floors at recall@k ≥ 0.85).
-`dense.py` is optional dense/vector retrieval behind the `[rag]` extra plus
-an embeddings key (`VOYAGE_API_KEY`/`OPENAI_API_KEY`); it's used when both
-are present and falls back to BM25 otherwise. `core/ai.py` wraps the
+`dense.py` is optional dense/vector retrieval behind the `[rag]` extra —
+**no API key required**: `embed.py` tries Voyage, then OpenAI, then a local
+`BAAI/bge-small-en-v1.5` that ships with the extra, so a key is a quality
+upgrade rather than the entry fee. When both engines are built, `retrieve_any`
+fuses them with reciprocal rank fusion (`rag.rrf_fuse`, `RRF_K = 60`) and
+reports `hybrid RRF`; it degrades to whichever single engine is ready, and to
+BM25 alone otherwise. `dense.status()` names which of the three links (extra,
+backend, built store) is missing, and `dense.fix_hint()` maps that to the one
+next action — both `boost doctor` and `boost search` read that same table, so
+they can't give contradictory advice. `core/ai.py` wraps the
 opt-in LLM-assisted paths (`search --smart`, `explain`, `distill`, `infer`,
 `absorb`, `evolve`, `simulate`, …), shelling out to the `claude` CLI or
 `ANTHROPIC_API_KEY` when available and degrading to heuristics when not.

{boost_skill_cli-1.0.316/boost_skill_cli.egg-info → boost_skill_cli-1.0.317}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.316
+Version: 1.0.317
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE
@@ -786,17 +786,37 @@ pipx upgrade boost-skill-cli        # or: pip install --upgrade boost-skill-cli
 The default install is **zero-dependency** (pure stdlib). `boost search` and the
 `boost_search` MCP tool rank results with a built-in full-content BM25 engine —
 the index builds automatically on your first search, so BM25 is the default with
-no setup (`boost reindex` just forces a rebuild). For optional **dense semantic
-search**, install the `[rag]` extra and set an embeddings key — retrieval then
-embeds every skill and ranks by vector similarity, falling back to BM25 whenever
-the extra or key is absent:
+no setup (`boost reindex` just forces a rebuild).
+
+### Configuring semantic search
+
+BM25 matches words. It is very good when your query shares vocabulary with the
+docs and poor when it doesn't — ask it *"my app is slow"* and it has nothing to
+match on. Semantic search ranks by meaning instead, and boost fuses the two so
+each covers the other's blind spot.
+
+**No API key is required.** Two steps:
 
 ```bash
-pip install "boost-skill-cli[rag]"            # adds the sqlite-vec vector store
-export VOYAGE_API_KEY=...                      # or OPENAI_API_KEY
-boost reindex --dense                          # embed chunks into the vector store
+pip install "boost-skill-cli[rag]"   # vector store + local embedding model
+boost reindex --dense                # embed your tapped registries
 ```
 
+The first search after that downloads a small embedding model once (~133 MB,
+sha256-pinned, cached under `~/.boost/cache/models`) and runs it on CPU. Nothing
+is sent anywhere.
+
+| | required | what you get |
+|---|---|---|
+| BM25 | nothing — it is the default | keyword matching, always on |
+| `[rag]` extra + `reindex --dense` | no account, no key | meaning-based search, fused with BM25 |
+| `VOYAGE_API_KEY` or `OPENAI_API_KEY` | an account | a larger embedding model; same behaviour otherwise |
+
+A key is a **quality upgrade, not an entry fee** — set one and boost prefers it
+automatically, re-embedding on the next `reindex --dense`. Every layer degrades
+rather than failing: no extra, no key, or no built store each fall back to BM25,
+and `boost doctor` reports which engine is actually serving and why.
+
 Want the whole ecosystem instead of the starter set? boost ships a **curated
 registry catalog** — 460+ classified GitHub registries of skills, Cursor/Windsurf
 **rules**, and Claude Code **workflows** (slash commands & subagents),

{boost_skill_cli-1.0.316 → boost_skill_cli-1.0.317}/README.md

@@ -68,17 +68,37 @@ pipx upgrade boost-skill-cli        # or: pip install --upgrade boost-skill-cli
 The default install is **zero-dependency** (pure stdlib). `boost search` and the
 `boost_search` MCP tool rank results with a built-in full-content BM25 engine —
 the index builds automatically on your first search, so BM25 is the default with
-no setup (`boost reindex` just forces a rebuild). For optional **dense semantic
-search**, install the `[rag]` extra and set an embeddings key — retrieval then
-embeds every skill and ranks by vector similarity, falling back to BM25 whenever
-the extra or key is absent:
+no setup (`boost reindex` just forces a rebuild).
+
+### Configuring semantic search
+
+BM25 matches words. It is very good when your query shares vocabulary with the
+docs and poor when it doesn't — ask it *"my app is slow"* and it has nothing to
+match on. Semantic search ranks by meaning instead, and boost fuses the two so
+each covers the other's blind spot.
+
+**No API key is required.** Two steps:
 
 ```bash
-pip install "boost-skill-cli[rag]"            # adds the sqlite-vec vector store
-export VOYAGE_API_KEY=...                      # or OPENAI_API_KEY
-boost reindex --dense                          # embed chunks into the vector store
+pip install "boost-skill-cli[rag]"   # vector store + local embedding model
+boost reindex --dense                # embed your tapped registries
 ```
 
+The first search after that downloads a small embedding model once (~133 MB,
+sha256-pinned, cached under `~/.boost/cache/models`) and runs it on CPU. Nothing
+is sent anywhere.
+
+| | required | what you get |
+|---|---|---|
+| BM25 | nothing — it is the default | keyword matching, always on |
+| `[rag]` extra + `reindex --dense` | no account, no key | meaning-based search, fused with BM25 |
+| `VOYAGE_API_KEY` or `OPENAI_API_KEY` | an account | a larger embedding model; same behaviour otherwise |
+
+A key is a **quality upgrade, not an entry fee** — set one and boost prefers it
+automatically, re-embedding on the next `reindex --dense`. Every layer degrades
+rather than failing: no extra, no key, or no built store each fall back to BM25,
+and `boost doctor` reports which engine is actually serving and why.
+
 Want the whole ecosystem instead of the starter set? boost ships a **curated
 registry catalog** — 460+ classified GitHub registries of skills, Cursor/Windsurf
 **rules**, and Claude Code **workflows** (slash commands & subagents),

{boost_skill_cli-1.0.316 → boost_skill_cli-1.0.317}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.316'
-__version_tuple__ = version_tuple = (1, 0, 316)
+__version__ = version = '1.0.317'
+__version_tuple__ = version_tuple = (1, 0, 317)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.316 → boost_skill_cli-1.0.317}/boost_cli/commands/discovery.py

@@ -12,6 +12,7 @@ import re
 import shutil
 import subprocess
 import sys
+import textwrap
 import threading
 import time
 import urllib.parse
@@ -122,6 +123,7 @@ def cmd_search(argv):
     if not scored:
         out.info("no matches for %r" % query)
         out.info(out.role("try `boost discover %s` to search all of GitHub" % query, "muted"))
+        _hint_semantic_search(engine)
         return 0
     # The CLI's long-standing wording for the BM25 engine differs from the label
     # rag/eval use ("BM25 full-content"), and both are load-bearing: the latter
@@ -154,9 +156,44 @@ def cmd_search(argv):
                  + out.truncate(e["description"] or "", desc_w) + tag)
     out.info(out.role("%d match%s · ranked by %s"
                    % (len(scored), "" if len(scored) == 1 else "es", ranker), "muted"))
+    _hint_semantic_search(engine)
     return 0
 
 
+def _hint_semantic_search(engine: str) -> None:
+    """Say that a better engine exists, when BM25 answered alone.
+
+    `boost search` reported which engine *ran* and never that a better one was
+    available, so a user who installed the extra but never reindexed had no way
+    to learn the semantic search they think they enabled has never once run.
+    That is the silent half of the three-things-must-line-up problem, and
+    `boost doctor` was the only surface that said anything about it.
+
+    Deliberately quiet: one muted line, only when dense contributed nothing, and
+    naming the ONE next action rather than the whole setup. The remedy comes
+    from core.dense.fix_hint — the same table doctor reads — so the two surfaces
+    can never disagree about whether an API key is needed.
+    """
+    if engine != "BM25 full-content":
+        # Anything else either already used vectors ("dense vectors", "hybrid
+        # RRF") or is the frontmatter fallback, where the BM25 index failed to
+        # build — a louder problem that this hint would only paper over.
+        return
+    from ..core import dense
+    st = dense.status()
+    if st.get("ready"):
+        return
+    # Wrap to the pane like every other row here: at COLUMNS=60 the longest
+    # remedy is 82 characters and would be the one line in this output that
+    # blows the terminal width. `break_long_words=False` keeps the shell command
+    # runnable — a copy-pasteable `pip install ...` matters more than a hard
+    # clamp, and _FIX is tested to hold no token long enough to overflow.
+    msg = "semantic search is off — %s" % dense.fix_hint(st.get("reason", ""))
+    for line in textwrap.wrap(msg, max(out.term_width(), 20),
+                              break_long_words=False, break_on_hyphens=False):
+        out.info(out.role(line, "muted"))
+
+
 def cmd_reindex(argv):
     """Build/refresh the full-content (RAG) search index over tapped items."""
     p = cliparse.parser(

{boost_skill_cli-1.0.316 → boost_skill_cli-1.0.317}/boost_cli/commands/quality.py

@@ -407,24 +407,8 @@ def cmd_doctor(argv):
     return 1 if issues else 0
 
 
-# Why dense retrieval isn't serving, keyed by `dense.status()["reason"]`. Each
-# names the ONE next action; the reason order in `status()` guarantees only the
-# first missing link is ever reported, so these never chain.
-_DENSE_FIX = {
-    "no-backend": "install the extra: `pip install 'boost-skill-cli[rag]'`",
-    # Names the keyless remedy first: since the [rag] extra carries a local
-    # embedding model, an API key is the quality ceiling, not the entry fee.
-    # This reason now means "no key AND no local backend", which in practice is
-    # a partial install or BOOST_NO_EMBED.
-    "no-key": ("reinstall the extra: `pip install 'boost-skill-cli[rag]'` "
-               "(or set VOYAGE_API_KEY / OPENAI_API_KEY for a larger model)"),
-    "no-store": "build it: `boost reindex --dense`",
-    "version-changed": "rebuild it: `boost reindex --dense --force`",
-    "provider-changed": "rebuild it: `boost reindex --dense --force`",
-    "model-changed": "rebuild it: `boost reindex --dense --force`",
-    "dim-changed": "rebuild it: `boost reindex --dense --force`",
-    "empty": "rebuild it: `boost reindex --dense --force`",
-}
+# The remedy table moved to core.dense.fix_hint so `boost search` reports the
+# same next action as `boost doctor` — see that function for why.
 
 
 def _report_search_engine(bad) -> None:
@@ -445,7 +429,7 @@ def _report_search_engine(bad) -> None:
                   st["chunks"], _s(st["chunks"]), st["taps"], _s(st["taps"])))
         return
 
-    fix = _DENSE_FIX.get(str(st["reason"]), "see `boost reindex --dense`")
+    fix = dense.fix_hint(st["reason"])
     if st["degraded"]:
         # The store was built and is now dead weight: say what it holds, what
         # changed, and that search has silently been on BM25 the whole time.

{boost_skill_cli-1.0.316 → boost_skill_cli-1.0.317}/boost_cli/core/dense.py

@@ -134,6 +134,36 @@ def _recorded_meta() -> dict:
         con.close()
 
 
+# Why dense retrieval isn't serving, keyed by the `reason` status() returns.
+# Each names the ONE next action; the reason order in status() guarantees only
+# the first missing link is ever reported, so these never chain.
+#
+# Lives here rather than in a command module because two surfaces need the same
+# answer — `boost doctor` and `boost search` — and two copies would drift, which
+# is how a surface ends up telling a user to set an API key that the [rag]
+# extra's local model already made unnecessary.
+_FIX = {
+    "no-backend": "install the extra: `pip install 'boost-skill-cli[rag]'`",
+    # Names the keyless remedy first: since the [rag] extra carries a local
+    # embedding model, an API key is the quality ceiling, not the entry fee.
+    # This reason means "no key AND no local backend", which in practice is a
+    # partial install or BOOST_NO_EMBED.
+    "no-key": ("reinstall the extra: `pip install 'boost-skill-cli[rag]'` "
+               "(or set VOYAGE_API_KEY / OPENAI_API_KEY for a larger model)"),
+    "no-store": "build it: `boost reindex --dense`",
+    "version-changed": "rebuild it: `boost reindex --dense --force`",
+    "provider-changed": "rebuild it: `boost reindex --dense --force`",
+    "model-changed": "rebuild it: `boost reindex --dense --force`",
+    "dim-changed": "rebuild it: `boost reindex --dense --force`",
+    "empty": "rebuild it: `boost reindex --dense --force`",
+}
+
+
+def fix_hint(reason: str) -> str:
+    """The single next action for a `status()` reason, or a safe default."""
+    return _FIX.get(reason, "see `boost reindex --dense`")
+
+
 def status() -> dict:
     """Why dense retrieval is, or is not, serving queries.
 

{boost_skill_cli-1.0.316 → boost_skill_cli-1.0.317}/boost_cli/core/mcp.py

@@ -132,6 +132,31 @@ INSTRUCTIONS = (
 )
 
 
+def engine_note() -> str:
+    """One line telling the agent which retrieval engine `boost_search` will use.
+
+    MCP hosts load `instructions` into the agent's context, and an agent that
+    cannot tell a keyword index from a semantic one will phrase queries for a
+    vector search that is not running — asking "my containers keep restarting"
+    of a BM25 index that needs the word "docker". Naming the engine, and the one
+    command that upgrades it, costs a line and removes the guess.
+
+    Appended at `initialize` rather than baked into INSTRUCTIONS because the
+    answer depends on machine state at connect time, not on the build.
+    """
+    from . import dense
+    st = dense.status()
+    if st.get("ready"):
+        return ("\n\nSEARCH ENGINE: hybrid — BM25 keywords fused with dense "
+                "vectors (%s). Natural-language problem descriptions retrieve "
+                "well; you do not need to guess the skill's vocabulary."
+                % st.get("model"))
+    return ("\n\nSEARCH ENGINE: BM25 keyword matching only — dense vectors are "
+            "not configured, so queries are matched on shared words rather than "
+            "meaning. Prefer concrete terms over paraphrase. To enable semantic "
+            "search, %s." % dense.fix_hint(st.get("reason", "")))
+
+
 def handle_request(req: dict, *, version: str,
                    registry: Registry) -> Optional[dict]:
     """Map one parsed JSON-RPC request to its response dict.
@@ -149,7 +174,7 @@ def handle_request(req: dict, *, version: str,
         resp["result"] = {"protocolVersion": PROTOCOL_VERSION,
                           "capabilities": {"tools": {}},
                           "serverInfo": {"name": "boost", "version": version},
-                          "instructions": INSTRUCTIONS}
+                          "instructions": INSTRUCTIONS + engine_note()}
     elif method == "ping":
         resp["result"] = {}
     elif method == "tools/list":

{boost_skill_cli-1.0.316 → boost_skill_cli-1.0.317/boost_skill_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.316
+Version: 1.0.317
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE
@@ -786,17 +786,37 @@ pipx upgrade boost-skill-cli        # or: pip install --upgrade boost-skill-cli
 The default install is **zero-dependency** (pure stdlib). `boost search` and the
 `boost_search` MCP tool rank results with a built-in full-content BM25 engine —
 the index builds automatically on your first search, so BM25 is the default with
-no setup (`boost reindex` just forces a rebuild). For optional **dense semantic
-search**, install the `[rag]` extra and set an embeddings key — retrieval then
-embeds every skill and ranks by vector similarity, falling back to BM25 whenever
-the extra or key is absent:
+no setup (`boost reindex` just forces a rebuild).
+
+### Configuring semantic search
+
+BM25 matches words. It is very good when your query shares vocabulary with the
+docs and poor when it doesn't — ask it *"my app is slow"* and it has nothing to
+match on. Semantic search ranks by meaning instead, and boost fuses the two so
+each covers the other's blind spot.
+
+**No API key is required.** Two steps:
 
 ```bash
-pip install "boost-skill-cli[rag]"            # adds the sqlite-vec vector store
-export VOYAGE_API_KEY=...                      # or OPENAI_API_KEY
-boost reindex --dense                          # embed chunks into the vector store
+pip install "boost-skill-cli[rag]"   # vector store + local embedding model
+boost reindex --dense                # embed your tapped registries
 ```
 
+The first search after that downloads a small embedding model once (~133 MB,
+sha256-pinned, cached under `~/.boost/cache/models`) and runs it on CPU. Nothing
+is sent anywhere.
+
+| | required | what you get |
+|---|---|---|
+| BM25 | nothing — it is the default | keyword matching, always on |
+| `[rag]` extra + `reindex --dense` | no account, no key | meaning-based search, fused with BM25 |
+| `VOYAGE_API_KEY` or `OPENAI_API_KEY` | an account | a larger embedding model; same behaviour otherwise |
+
+A key is a **quality upgrade, not an entry fee** — set one and boost prefers it
+automatically, re-embedding on the next `reindex --dense`. Every layer degrades
+rather than failing: no extra, no key, or no built store each fall back to BM25,
+and `boost doctor` reports which engine is actually serving and why.
+
 Want the whole ecosystem instead of the starter set? boost ships a **curated
 registry catalog** — 460+ classified GitHub registries of skills, Cursor/Windsurf
 **rules**, and Claude Code **workflows** (slash commands & subagents),

{boost_skill_cli-1.0.316 → boost_skill_cli-1.0.317}/boost_skill_cli.egg-info/SOURCES.txt

@@ -485,6 +485,7 @@ tests/unit/test_community_health_files.py
 tests/unit/test_config.py
 tests/unit/test_dense.py
 tests/unit/test_dense_fallback.py
+tests/unit/test_dense_fix_hint.py
 tests/unit/test_dense_status.py
 tests/unit/test_dependabot_config.py
 tests/unit/test_docs_pages_linked.py

{boost_skill_cli-1.0.316 → boost_skill_cli-1.0.317}/docs/mcp-hub.html

@@ -222,9 +222,9 @@
           <!-- embed -->
           <rect x="480" y="200" width="180" height="86" rx="12" fill="rgba(244,114,208,.07)" stroke="#f472d0" stroke-width="1.2"/>
           <text x="570" y="228" text-anchor="middle" class="head">embed (urllib)</text>
-          <text x="570" y="248" text-anchor="middle" class="lbl-s">Voyage · OpenAI</text>
-          <text x="570" y="265" text-anchor="middle" class="lbl-t" textLength="164" lengthAdjust="spacingAndGlyphs">voyage-3 1024 / t-e-3-small 1536</text>
-          <text x="570" y="280" text-anchor="middle" class="note">opt-in · needs key</text>
+          <text x="570" y="248" text-anchor="middle" class="lbl-s">Voyage · OpenAI · local</text>
+          <text x="570" y="265" text-anchor="middle" class="lbl-t" textLength="164" lengthAdjust="spacingAndGlyphs">voyage-4 1024 / bge-small 384</text>
+          <text x="570" y="280" text-anchor="middle" class="note">opt-in · no key needed</text>
           <line x1="420" y1="170" x2="480" y2="235" stroke="#f472d0" stroke-width="1.4" marker-end="url(#iap)"/>
 
           <!-- dense store -->
@@ -590,13 +590,15 @@ _MCP_TOOLS = REGISTRY.specs()       <span class="cm"># list stays in sync</span>
           <summary>Search by meaning, not words <span class="topic-tag">dense</span></summary>
           <div class="body"><p>An optional upgrade turns every skill into a point in "meaning space,"
             so "test my React app" can find a <code>jest</code> skill even with no shared words —
-            it just finds the nearest points. It's optional because it needs an extra install and a key.</p></div>
+            it just finds the nearest points. It's optional because it needs an extra install — but not a key.</p></div>
         </details>
         <details class="card tech">
           <summary>Dense embeddings + sqlite-vec <span class="topic-tag">Phase 2 · [rag]</span></summary>
           <div class="body"><p>Chunks are embedded via <code>embed</code> over urllib — preferring
-            <code>VOYAGE_API_KEY</code> (<code>voyage-3</code>, 1024-d) then <code>OPENAI_API_KEY</code>
-            (<code>text-embedding-3-small</code>, 1536-d) — and stored in a <code>sqlite-vec</code>
+            <code>VOYAGE_API_KEY</code> (<code>voyage-4</code>, 1024-d), then <code>OPENAI_API_KEY</code>
+            (<code>text-embedding-3-small</code>, 1536-d), and falling back to a local
+            <code>BAAI/bge-small-en-v1.5</code> (384-d) that ships with the extra and needs no
+            key at all — and stored in a <code>sqlite-vec</code>
             <code>vec0(… distance_metric=cosine)</code> table. Retrieval does a KNN over-fetch
             (<code>max(k×8, 200)</code>) then reduces per-entry. A provider/dimension change
             invalidates the store so stale vectors are never served.</p></div>

boost_skill_cli-1.0.317/docs/roadmap/items/prerequisites-and-semantic-search-setup.md

@@ -0,0 +1,49 @@
+---
+id: prerequisites-and-semantic-search-setup
+board: code
+section: docsite
+status: shipped
+category: Docs · Setup
+complexity: M
+impact: High
+wow: 3
+note: silent BM25-only is the default outcome
+order: 58
+owner: loop/semantic-search-setup
+pr: 364
+title: Nothing tells a user semantic search is off — not the README, not <code>search</code>, not <code>/mcp</code>
+---
+<b>Shipped.</b> Dense retrieval needs things to line up — the <code>[rag]</code>
+extra (<code>sqlite-vec</code> plus a bundled local model, so an embeddings key
+is now a quality upgrade rather than the entry fee) <em>and</em> a built vector
+store (<code>boost reindex --dense</code>) — and every one of them failed
+<em>silently</em>: <code>rag.retrieve_any</code> floors to BM25 and returns, so a
+user who installed the extra but never set a key, or set a key but never
+reindexed, has no way to learn that the semantic search they think they enabled
+had never once run. Three gaps, all closed:
+<b>(1) README.</b> Prerequisites live in half a sentence (&ldquo;Needs Python 3.9+
+and <code>git</code>&rdquo;) and the optional stack is buried in Install prose.
+Give required vs. optional prerequisites a dedicated
+<b>Configuring semantic search</b> section, and automate the optional install the
+way <code>requirements/*.txt</code> already does for the toolchain, so it is one
+command rather than three remembered ones.
+<b>(2) Surfacing.</b> <code>cmd_search</code> printed which engine <em>ran</em> but
+never that a better one was available — <code>embed.fallback_note()</code> exists
+and is only wired into <code>reindex --dense</code>. Now said on search — including the
+zero-results path, where a keyword engine finding nothing is exactly what a
+semantic one is for — and silent when vectors already served or output is
+<code>--json</code>. The remedy table moved out of <code>commands/quality.py</code>
+into <code>core.dense.fix_hint</code>, so <code>doctor</code> and
+<code>search</code> cannot give contradictory advice; it had no tests at all,
+which is how its &ldquo;set an API key&rdquo; entry went stale. Engine state also
+lands in the MCP <code>initialize</code> <code>instructions</code>, appended at
+connect time, so an agent reading <code>/mcp</code> sees
+&ldquo;BM25 keyword matching only&rdquo; instead of assuming vector search.
+<b>(3) Stale docs.</b> <code>mcp-hub.html</code> advertised
+<code>voyage-3</code> (1024-d) in the pipeline diagram and the Phase&nbsp;2
+details block; <code>core/embed.py</code> has pinned <code>voyage-4</code> since
+the complimentary-token change; the sweep also caught the diagram and prose
+still calling a key mandatory, and the same claim in <code>CLAUDE.md</code>.
+Three environment-dependent tests were fixed on the way: they asserted answers
+that were only correct where the <code>[rag]</code> extra was <em>absent</em>,
+so they were green on CI and red on any machine that had installed it.

{boost_skill_cli-1.0.316 → boost_skill_cli-1.0.317}/docs/roadmap.html

@@ -4571,34 +4571,42 @@ pip/pipx installs and telling a PyPI user to clone the repo — is separate and
       </article>
 
       <article class="cap rcard" id="prerequisites-and-semantic-search-setup">
-        <div class="head"><span class="pill planned">Planned</span><span class="cat">Docs · Setup</span></div>
+        <div class="head"><span class="pill shipped">Shipped</span><span class="cat">Docs · Setup</span></div>
         <h3>Nothing tells a user semantic search is off — not the README, not <code>search</code>, not <code>/mcp</code></h3>
-        <p>Dense retrieval needs three separate things to line up — the <code>[rag]</code>
-extra (<code>sqlite-vec</code>), an embeddings key (<code>VOYAGE_API_KEY</code> or
-<code>OPENAI_API_KEY</code>), <em>and</em> a built vector store
-(<code>boost reindex --dense</code>) — and every one of them fails
+        <p><b>Shipped.</b> Dense retrieval needs things to line up — the <code>[rag]</code>
+extra (<code>sqlite-vec</code> plus a bundled local model, so an embeddings key
+is now a quality upgrade rather than the entry fee) <em>and</em> a built vector
+store (<code>boost reindex --dense</code>) — and every one of them failed
 <em>silently</em>: <code>rag.retrieve_any</code> floors to BM25 and returns, so a
 user who installed the extra but never set a key, or set a key but never
 reindexed, has no way to learn that the semantic search they think they enabled
-has never once run. Three gaps to close:
+had never once run. Three gaps, all closed:
 <b>(1) README.</b> Prerequisites live in half a sentence (&ldquo;Needs Python 3.9+
 and <code>git</code>&rdquo;) and the optional stack is buried in Install prose.
 Give required vs. optional prerequisites a dedicated
 <b>Configuring semantic search</b> section, and automate the optional install the
 way <code>requirements/*.txt</code> already does for the toolchain, so it is one
 command rather than three remembered ones.
-<b>(2) Surfacing.</b> <code>cmd_search</code> prints which engine <em>ran</em> but
-never that a better one is available — <code>embed.fallback_note()</code> exists
-and is only wired into <code>reindex --dense</code>. Say it on search too, and
-put engine state in the MCP <code>initialize</code> response
-(<code>serverInfo</code>/<code>instructions</code>) so an agent reading
-<code>/mcp</code> can see &ldquo;BM25 only — dense not configured&rdquo; instead of
-assuming vector search.
-<b>(3) Stale docs.</b> <code>mcp-hub.html</code> still advertises
+<b>(2) Surfacing.</b> <code>cmd_search</code> printed which engine <em>ran</em> but
+never that a better one was available — <code>embed.fallback_note()</code> exists
+and is only wired into <code>reindex --dense</code>. Now said on search — including the
+zero-results path, where a keyword engine finding nothing is exactly what a
+semantic one is for — and silent when vectors already served or output is
+<code>--json</code>. The remedy table moved out of <code>commands/quality.py</code>
+into <code>core.dense.fix_hint</code>, so <code>doctor</code> and
+<code>search</code> cannot give contradictory advice; it had no tests at all,
+which is how its &ldquo;set an API key&rdquo; entry went stale. Engine state also
+lands in the MCP <code>initialize</code> <code>instructions</code>, appended at
+connect time, so an agent reading <code>/mcp</code> sees
+&ldquo;BM25 keyword matching only&rdquo; instead of assuming vector search.
+<b>(3) Stale docs.</b> <code>mcp-hub.html</code> advertised
 <code>voyage-3</code> (1024-d) in the pipeline diagram and the Phase&nbsp;2
 details block; <code>core/embed.py</code> has pinned <code>voyage-4</code> since
-the complimentary-token change. Same sweep should catch any other drifted model
-or extra names across <code>docs/*.html</code>.</p>
+the complimentary-token change; the sweep also caught the diagram and prose
+still calling a key mandatory, and the same claim in <code>CLAUDE.md</code>.
+Three environment-dependent tests were fixed on the way: they asserted answers
+that were only correct where the <code>[rag]</code> extra was <em>absent</em>,
+so they were green on CI and red on any machine that had installed it.</p>
         <div class="meta">
           <span class="m">Complexity <b>M</b></span>
           <span class="m hi">Impact <b>High</b></span>

{boost_skill_cli-1.0.316 → boost_skill_cli-1.0.317}/tests/functional/test_cli_discovery.py

@@ -1084,7 +1084,15 @@ class TestReindex:
         r = boost("search", "brainstorming")
         assert "ranked by full-content BM25" in r.out
 
-    def test_dense_skipped_without_embeddings_key(self, boost, tapped):
+    def test_dense_skipped_when_no_backend_at_all(self, boost, tapped, monkeypatch):
+        """No key and no local model: BM25 still builds, dense says why it didn't.
+
+        `local_available` is forced off because the [rag] extra now ships a
+        model — without this the command really does build a dense index here,
+        and the assertion below was passing only where the extra was absent.
+        """
+        from boost_cli.core import embed
+        monkeypatch.setattr(embed, "local_available", lambda: False)
         r = boost("reindex", "--dense")
         assert "indexed" in r.out                 # BM25 still builds
         assert "dense index skipped" in r.out
@@ -1162,3 +1170,59 @@ class TestReindex:
         assert "dense vector store is empty" in r.out
         assert "--force" in r.out
         assert dense.ready() is False
+
+
+class TestSearchSemanticHint:
+    """`boost search` must say a better engine exists, not just which one ran.
+
+    The gap this closes: search reported "ranked by full-content BM25" and
+    stopped. A user who installed the [rag] extra but never ran `boost reindex
+    --dense` saw nothing to suggest the semantic search they think they enabled
+    has never once run — `boost doctor` was the only surface that said so, and
+    nobody runs doctor after a search that merely felt mediocre.
+
+    The hint is deliberately quiet, so these tests pin the *silences* as hard as
+    the message: no hint when vectors already served, and none in --json.
+    """
+
+    def test_bm25_only_search_says_semantic_is_off(self, boost, tapped):
+        boost("reindex")
+        r = boost("search", "brainstorming")
+        assert "ranked by full-content BM25" in r.out      # unchanged
+        assert "semantic search is off" in r.out
+
+    def test_hint_names_the_one_next_action(self, boost, tapped):
+        # Without the extra the remedy is the install; with it, the reindex.
+        # Either way exactly one command is named, never the whole setup.
+        #
+        # Matched against the whole output with whitespace collapsed, because
+        # the hint legitimately wraps across lines in a narrow pane — asserting
+        # on a single line made this test fail at COLUMNS=40 for a layout the
+        # code was getting right.
+        boost("reindex")
+        r = boost("search", "brainstorming")
+        flat = " ".join(r.out.split())
+        assert "semantic search is off" in flat
+        assert "pip install" in flat or "boost reindex --dense" in flat
+
+    def test_zero_results_still_hints(self, boost, tapped):
+        # The strongest case for the hint: a keyword engine finding nothing is
+        # exactly the shape of query a semantic one exists to answer.
+        r = boost("search", "zzzznotathinginanycatalog")
+        assert "no matches" in r.out
+        assert "semantic search is off" in r.out
+
+    def test_json_output_carries_no_hint(self, boost, tapped):
+        # --json is parsed by other programs; a stray human line corrupts it.
+        boost("reindex")
+        r = boost("search", "brainstorming", "--json")
+        assert "semantic search is off" not in r.out
+        json.loads(r.out)                                  # still valid JSON
+
+    def test_no_hint_once_dense_is_ready(self, boost, tapped, monkeypatch):
+        # The inverse: a user who finished the setup must never be nagged.
+        from boost_cli.core import dense
+        monkeypatch.setattr(dense, "status", lambda: {"ready": True, "reason": None})
+        boost("reindex")
+        r = boost("search", "brainstorming")
+        assert "semantic search is off" not in r.out