boost-skill-cli 1.2.148__tar.gz → 1.2.150__tar.gz

{boost_skill_cli-1.2.148 → boost_skill_cli-1.2.150}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.148
+Version: 1.2.150
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0

{boost_skill_cli-1.2.148 → boost_skill_cli-1.2.150}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.2.148'
-__version_tuple__ = version_tuple = (1, 2, 148)
+__version__ = version = '1.2.150'
+__version_tuple__ = version_tuple = (1, 2, 150)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.148 → boost_skill_cli-1.2.150}/boost_cli/commands/quality.py

@@ -915,9 +915,12 @@ def _report_search_engine(rep) -> None:
         built = st["built_model"] or st["built_provider"] or "an older build"
         detail = "built with %s" % built
         if st["reason"] == "model-changed":
-            detail += ", live key is %s" % st["model"]
+            detail += ", live model is %s" % st["model"]
         elif st["reason"] == "provider-changed":
-            detail += ", live key is %s" % st["provider"]
+            # "live key is local" named a key that does not exist: the local
+            # model is what `provider()` falls through to when every key is
+            # gone, which is the commonest way a store reaches this reason.
+            detail += ", live provider is %s" % st["provider"]
         elif st["reason"] == "empty":
             detail += " but holds no vectors"
         elif st["reason"] == "model-unavailable":

{boost_skill_cli-1.2.148 → boost_skill_cli-1.2.150}/boost_cli/core/dense.py

@@ -568,6 +568,10 @@ _FIX = {
     # instead: with it in force, this build goes through the paid API.
     "no-store": "build it: `boost reindex --dense`",
     "version-changed": "rebuild it: `boost reindex --dense --force`",
+    # Only right when the live space is the one the user wants. A store built
+    # through a paid provider that has merely lost its key lands here too, and
+    # for that user this row is the bill `no-key`'s guard exists to prevent —
+    # so `fix_hint` answers it from the status dict before reaching this table.
     "provider-changed": "rebuild it: `boost reindex --dense --force`",
     "model-changed": "rebuild it: `boost reindex --dense --force`",
     "dim-changed": "rebuild it: `boost reindex --dense --force`",
@@ -611,6 +615,55 @@ def free_shard_path(prov: str | None) -> str | None:
             % (" ".join(keys), "s" if len(keys) > 1 else "", prov))
 
 
+def _restore_built_space(built: str, env: str) -> str | None:
+    """How to put a store's own provider back in force, or None if nothing can.
+
+    ``built`` is the provider the vectors were embedded with and ``env`` its
+    key variable. Like :func:`free_shard_path` above, a pure function of the
+    environment: both facts it needs are read from ``os.environ`` through
+    :data:`embed.KEY_ENV`, so its answer cannot disagree with what
+    :func:`embed.provider` will do next.
+
+    **Two independent things can be wrong, and an earlier draft ordered them
+    instead of combining them.** The key can be gone, and a key the resolver
+    prefers can be in force; either alone, or both at once:
+
+    * the key is gone — ``export`` brings it back;
+    * something outranks it — ``unset`` what is in front hands the store back
+      its own provider;
+    * both — an OpenAI-built store with no OpenAI key on a machine holding a
+      Voyage one. Answering only the first is what the ordered version did,
+      and ``export OPENAI_API_KEY=...`` moves ``provider()`` not at all: the
+      user runs it, lands on the same reason, and is then told to unset the
+      other key. A remedy that has to be followed twice to do anything is the
+      no-op this branch exists to replace, arrived at one step at a time.
+
+    None when the key is in force and nothing outranks it: whatever else is
+    wrong with that store, a key is not it.
+    """
+    gone = not os.environ.get(env)
+    # Not `live != built`: inequality says another provider won, not that it
+    # would *keep* winning once this one's key came back. A voyage-built store
+    # displaced by an OpenAI key needs the export alone, because voyage
+    # outranks openai — `unset OPENAI_API_KEY` there is a step that buys
+    # nothing. `outranking` reads the one preference order there is.
+    drop = embed.outranking(built)
+    # `unset A B` rather than one command per key: it is a single shell verb
+    # taking a list, and the surfaces that print this have one line. No
+    # `if drop else ""` guard — every branch that reads this one has already
+    # tested `drop`, so the guard was a value nothing could observe, which is
+    # a mutant no test can kill rather than a safety net.
+    unset = "`unset %s`" % " ".join(drop)
+    if gone and drop:
+        return ("set the key it was built with: `export %s=...`, then %s "
+                "puts it back in front" % (env, unset))
+    if gone:
+        return "set the key it was built with: `export %s=...`" % env
+    if drop:
+        return "%s puts the store's own key back in front" % unset
+    return None
+
+
 def fix_hint(reason: str, status: dict | None = None) -> str:
     """The single next action for a `status()` reason, or a safe default.
 
@@ -622,11 +675,26 @@ def fix_hint(reason: str, status: dict | None = None) -> str:
     status into ``provider-changed`` — a full re-embed of every vector they
     already paid for. Seen in the wild at 750,416 chunks.
 
-    The reason ladder cannot distinguish these two states on its own, because
-    ``no-key`` is checked before the store is even looked at: an unfinished
-    install with no store and a complete install whose key merely went missing
-    both land here. ``built_provider`` is what separates them, and it lives in
-    the status dict.
+    ``no-key`` means no key *and* no local backend, which in practice is a
+    partial install. A complete install whose key merely went missing does
+    **not** land there — ``provider()`` falls through to the local model that
+    the ``[rag]`` extra ships, so the ladder reaches ``provider-changed``
+    instead, whose table row is that same full re-embed. The guard was written
+    for a reason it could not be reached through: measured on a voyage-4 store
+    with the key unexported, `boost doctor` prescribed
+    `boost reindex --dense --force`. So both reasons consult the status, and
+    ``built_provider`` is what separates a store worth reviving from an
+    unfinished install with nothing to revive.
+
+    The two remedies differ in their tail, because the cost differs. Under
+    ``no-key`` the local model is missing, so the alternative is installing it
+    — which is what re-embeds everything. Under ``provider-changed`` a
+    provider resolved, so *some* backend is already in force and "reinstall
+    the extra" names a remedy for a state this is not. (Not "the user already
+    has the local model": the provider that displaced this store may well be
+    another key, and that machine need never have installed it.) The
+    alternative there is the explicit rebuild, named with the space it would
+    land in.
 
     ``no-store`` needs the status too. With a key in force and the local model
     installed, the table's "build it" is the paid build, while `boost
@@ -644,8 +712,12 @@ def fix_hint(reason: str, status: dict | None = None) -> str:
         free = free_shard_path(status.get("provider"))
         if free:
             return free
-    if reason == "no-key" and status:
-        env = embed.KEY_ENV.get(status.get("built_provider") or "")
+    if reason in ("no-key", "provider-changed") and status:
+        # `or ""` rather than a `get` default: a status that carries the key
+        # explicitly set to None must reach the same lookup as one that omits
+        # it, and `KEY_ENV` is missed either way.
+        built = status.get("built_provider") or ""
+        env = embed.KEY_ENV.get(built)
         # `chunks` guards the unfinished-install case: without vectors on disk
         # there is nothing a key would revive, and "build it" is the real next
         # step. A store built by the local model has no env var and correctly
@@ -656,10 +728,21 @@ def fix_hint(reason: str, status: dict | None = None) -> str:
         # vectors to revive; reading unknown as zero would send exactly the
         # user this branch exists to protect to the re-embed-everything answer.
         if env and (count is None or count > 0):
-            n = f"{int(count):,} vectors" if count else "vectors"
-            return ("set the key it was built with: `export %s=...` — "
-                    "reinstalling the extra swaps in the local model and "
-                    "forces all %s to be re-embedded" % (env, n))
+            n = (f"{int(count):,} vector{'' if count == 1 else 's'}"
+                 if count else "vectors")
+            if reason == "no-key":
+                return ("set the key it was built with: `export %s=...` — "
+                        "reinstalling the extra swaps in the local model and "
+                        "forces all %s to be re-embedded" % (env, n))
+            live = status.get("provider")
+            restore = _restore_built_space(built, env)
+            if restore:
+                # Names the live space rather than "the local model": the
+                # provider that displaced this store is whatever `provider()`
+                # picked, and a rebuild lands the vectors in *its* space.
+                return ("%s — or `boost reindex --dense --force` re-embeds "
+                        "all %s in %s's space"
+                        % (restore, n, live or "the live provider"))
     if (reason == "model-unavailable" and status
             and (status.get("model_failure") or {}).get("stage") == "load"):
         # The files are on disk and the load itself failed: promising a

{boost_skill_cli-1.2.148 → boost_skill_cli-1.2.150}/boost_cli/core/embed.py

@@ -49,6 +49,15 @@ from . import nethttp
 # exact variable that would revive a store built with a given provider — and a
 # second copy of that string is precisely how a surface ends up naming the
 # wrong one at the only moment the name matters.
+#
+# **Insertion order is preference order**, and it is the only *executable*
+# statement of it (`dense._FIX["no-key"]` and this module's own docstring
+# restate it in prose, where nothing can act on the wrong copy):
+# `provider` and `outranking` both walk this dict rather than testing the two
+# keys in a hardcoded sequence. Stating it twice is what let `fix_hint`
+# prescribe `export OPENAI_API_KEY=...` to an OpenAI-built store on a machine
+# holding a Voyage key — a remedy that leaves `provider()` exactly where it
+# was. `tests/unit/test_embed_outranking.py` pins the order itself.
 KEY_ENV = {"voyage": "VOYAGE_API_KEY", "openai": "OPENAI_API_KEY"}
 
 VOYAGE_URL = "https://api.voyageai.com/v1/embeddings"
@@ -194,15 +203,37 @@ def provider() -> str | None:
     """
     if not enabled():
         return None
-    if os.environ.get(KEY_ENV["voyage"]):
-        return "voyage"
-    if os.environ.get(KEY_ENV["openai"]):
-        return "openai"
+    for name, env in KEY_ENV.items():
+        if os.environ.get(env):
+            return name
     if local_available():
         return "local"
     return None
 
 
+def outranking(name: str) -> tuple[str, ...]:
+    """The set keys :func:`provider` would pick ahead of ``name``, in order.
+
+    Empty when ``name`` is already first among the keys in force — including
+    when it is the only one. Every key for a name outside :data:`KEY_ENV`,
+    since local comes last and any key displaces it.
+
+    It exists so a caller can ask what stands between a store and its own
+    provider without re-deriving the preference order. ``provider`` alone
+    cannot answer that: it names the winner, not what would have to go for
+    somebody else to win, and an OpenAI-built store whose own key is *also*
+    missing needs both facts — the export and the unset — where the winner's
+    name implies only one of them.
+    """
+    ahead = []
+    for other, env in KEY_ENV.items():
+        if other == name:
+            break
+        if os.environ.get(env):
+            ahead.append(env)
+    return tuple(ahead)
+
+
 def available() -> bool:
     """True when embeddings are enabled and a provider key is present."""
     return provider() is not None

{boost_skill_cli-1.2.148 → boost_skill_cli-1.2.150}/boost_skill_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.148
+Version: 1.2.150
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0

{boost_skill_cli-1.2.148 → boost_skill_cli-1.2.150}/boost_skill_cli.egg-info/SOURCES.txt

@@ -395,6 +395,7 @@ docs/roadmap/items/demo-cannot-open-its-own-pr.md
 docs/roadmap/items/demo-gif-workflow-has-never-succeeded.md
 docs/roadmap/items/demo-workflow-cancels-other-prs.md
 docs/roadmap/items/dense-kill-switch-has-no-reason-state.md
+docs/roadmap/items/dense-local-built-store-displaced-by-a-key.md
 docs/roadmap/items/dense-no-key-guard-is-unreachable.md
 docs/roadmap/items/dense-ready-but-embedder-cannot-run.md
 docs/roadmap/items/dense-reindex-has-no-progress-or-durability.md
@@ -959,6 +960,7 @@ tests/unit/test_dry_run_parity.py
 tests/unit/test_ed25519.py
 tests/unit/test_embed.py
 tests/unit/test_embed_local.py
+tests/unit/test_embed_outranking.py
 tests/unit/test_embed_truncated_response.py
 tests/unit/test_entry_key.py
 tests/unit/test_errors_and_cli_table.py

boost_skill_cli-1.2.150/docs/roadmap/items/dense-local-built-store-displaced-by-a-key.md

@@ -0,0 +1,37 @@
+---
+id: dense-local-built-store-displaced-by-a-key
+board: code
+section: planned
+status: planned
+category: Quality · Retrieval eval
+complexity: S
+impact: High
+wow: 4
+note: Exporting an API key takes a locally built store off the air, and doctor answers with a paid re-embed where `unset` is free. Every user who came in through `boost quickstart` is one `export` away from this.
+order: 353
+title: A locally built vector store displaced by a new API key is told to re-embed through the paid provider, where unsetting the key is free
+---
+<b>The mirror of #989, and the expensive direction.</b> #989 taught <code>fix_hint</code> that a store built with an API key can be displaced two ways, and to name the <code>export</code> or the <code>unset</code> that restores it. A store built by the <b>local</b> model is displaced by exactly the same mechanism — a key the resolver prefers appears on the machine — and gets none of it: the branch is gated on <code>env = embed.KEY_ENV.get(built)</code> being truthy, and <code>local</code> has no env var, so it falls through to the table.
+
+<b>Measured.</b> Two stores of 645,592 chunks, same machine, only <code>VOYAGE_API_KEY</code> set. Verbatim, through the real <code>dense.status()</code> ladder:
+
+<code>##### store built with 'local', live key = VOYAGE</code><br>
+<code>  status reason : provider-changed</code><br>
+<code>  outranking('local') : ('VOYAGE_API_KEY',)</code><br>
+<code>  DOCTOR |   ! semantic search silently off — 645592-chunk vector store built with</code><br>
+<code>  DOCTOR |     rebuild it: `boost reindex --dense --force`</code><br>
+<br>
+<code>##### store built with 'openai', live key = VOYAGE</code><br>
+<code>  status reason : provider-changed</code><br>
+<code>  DOCTOR |     set the key it was built with: `export OPENAI_API_KEY=...`, then</code><br>
+<code>  DOCTOR |     `unset VOYAGE_API_KEY` puts it back in front — or …</code>
+
+<code>embed.outranking('local')</code> already computes the answer — <code>unset VOYAGE_API_KEY</code> — and restores that store instantly and for nothing. The line boost actually prints re-embeds 645,592 chunks through a metered API.
+
+<b>Why it is not a corner case.</b> <code>boost quickstart</code> imports the published vector shards, and those are keyless: <code>BAAI/bge-small-en-v1.5</code> at 384 dimensions, built by the local model. So the default on-ramp leaves every user with a local-built store, and the first time one of them exports a Voyage or OpenAI key for anything at all, semantic search goes quiet and doctor bills them to get it back.
+
+<b>The constraint any fix has to clear</b>, and the reason this is a separate card rather than a line in #989: <code>unset</code> is only the right advice for a local-built store <b>if the local model is installed</b>. On a partial <code>[rag]</code> install, unsetting the one key in force sends <code>provider()</code> to <code>None</code> and the ladder to <code>no-key</code> — the advice would switch off the only thing making search work. So the predicate needs to ask whether the local model is there — and the one to ask is <code>embed.local_installed()</code>, not <code>embed.local_available()</code>: <code>local_available</code> answers by importing the ONNX runtime, which is right for a caller about to embed and wrong for one about to word a sentence. <code>dense.free_shard_path</code>, the sibling that words the other keyed-machine hint, already uses <code>local_installed</code> for exactly that reason. Either way it is a check the key-built branches do not need.
+
+Two more things fall out of that. The sentence needs a third variant — "puts the store's own key back in front" is false for a store that has no key; it is the local model being put back in front. And the admission test must be <code>built in embed.KEY_ENV or built == "local"</code>, never "has a recorded provider": <code>embed.outranking("")</code> returns <b>every</b> set key, so a store whose meta records no provider would be told to unset the machine's entire keyring on the strength of a blank field.
+
+<b>Where it was found.</b> The adversarial verification pass on #989, which is also why the measurement exists. #989's PR body originally scoped this out as "not measured here"; it is measured now, and <code>docs/semantic-search.md</code> carries a qualifier pointing at this card until it lands.

{boost_skill_cli-1.2.148 → boost_skill_cli-1.2.150}/docs/roadmap/items/dense-no-key-guard-is-unreachable.md

@@ -1,18 +1,20 @@
 ---
 id: dense-no-key-guard-is-unreachable
 board: code
-section: planned
-status: planned
+section: shipped
+status: shipped
 category: Quality · Retrieval eval
 complexity: L
 impact: High
 wow: 4
-note: dense.status() checks prov is None before it looks at the store (dense.py:618-621), b…
+note: A complete [rag] extra falls through a missing key to the local model, so the ladder reaches provider-changed and prescribes the full re-embed the guard exists to prevent. Two things can displace a store, and the fix answers both.
 order: 204
-owner:
-pr:
+owner: loop/dense-no-key-guard
+pr: 989
 title: fix_hint's no-key guard has been unreachable since the day it was written; a missing API key now prescribes the full re-embed the guard exists to prevent
 ---
+<b>Shipped in #989.</b> <code>fix_hint</code> now fires on <code>provider-changed</code> as well as <code>no-key</code>, with a different tail for each, and <code>embed.KEY_ENV</code> became the single statement of the provider preference order that <code>provider()</code> and the new <code>embed.outranking()</code> both walk. Adversarial verification of the first cut caught a second defect in the fix itself: two independent things can stand between a store and its own provider — its key being gone, and a key the resolver prefers being in force — and ordering them instead of combining them prescribed <code>export OPENAI_API_KEY=...</code> to an OpenAI-built store on a Voyage-keyed machine, which moves <code>provider()</code> not at all. All eight key combinations are now pinned whole.
+
 <b>Measured.</b> On a complete <code>[rag]</code> extra with a voyage-4-built vector store and no API key exported, <code>dense.status()</code> returns <code>reason='provider-changed'</code> (not <code>no-key</code>), so all three status-passing surfaces print <code>rebuild it: \</code>boost reindex --dense --force\`<code> and </code>boost doctor<code> exits 1 — measured verbatim, including doctor's "live key is local; searches are using BM25" line — while the guard written to prevent exactly that (</code>21f28223<code>, #444) fires only under </code>BOOST_NO_EMBED=1` or a partial install, both confirmed by direct probe.
 
 <b>Reproduce it.</b>
@@ -54,6 +56,6 @@ THE REAL MACHINE IS NOT CURRENTLY IN THE BUG STATE. <code>~/.boost/cache/rag_vec
 
 THE MISDIAGNOSIS WAS REFUTABLE FROM THE SAME FILE. The <code>_FIX</code> comment — "This reason means 'no key AND no local backend', which in practice is a partial install or BOOST_NO_EMBED" — was already in <code>dense.py</code> from 86163e03 (07-31) when #444 (08-03) added a guard whose docstring asserts the opposite: "an unfinished install with no store and a complete install whose key merely went missing both land here." Two claims about <code>no-key</code>, 30 lines apart, that contradict each other.
 
-<b>Why it is worth doing.</b> A user who opens a new shell without exporting their key is told by doctor, search and the MCP server to re-embed their whole store. On the real machine in this repo that is 645,592 chunks / 1.20 GB, which CLAUDE.md prices at ~1.2 s per chunk on CPU — hours of compute, or a real API bill — to fix a problem whose actual remedy is one <code>export</code>. The repo already decided this was unacceptable and wrote six tests plus a paragraph of docstring to prevent it; the guard has simply never been able to fire.
+<b>Why it is worth doing.</b> A user who opens a new shell without exporting their key is told by doctor, search and the MCP server to re-embed their whole store. On the real machine in this repo that is 645,592 chunks / 1.20 GB, which the roadmap prices at ~1.2 s per chunk on CPU (<code>keyless-semantic-search-for-everyone.md:298</code> — not CLAUDE.md, per correction 1 above) — hours of compute, or a real API bill — to fix a problem whose actual remedy is one <code>export</code>. The repo already decided this was unacceptable and wrote six tests plus a paragraph of docstring to prevent it; the guard has simply never been able to fire.
 
-<em>Found by an automated audit of retrieval/eval quality, the search &amp; browse surfaces, and first-run onboarding; every finding was then re-measured from scratch by an independent adversarial verifier whose instruction was to refute it. Verdict: <b>CORRECTED</b>. No fix is prescribed here — the measurement is the contribution.</em>
+<em>Found by an automated audit of retrieval/eval quality, the search &amp; browse surfaces, and first-run onboarding; every finding was then re-measured from scratch by an independent adversarial verifier whose instruction was to refute it. Verdict: <b>CORRECTED</b>. The measurement was the first contribution; the fix followed in #989, and was itself sent back once by the same adversarial pass.</em>

{boost_skill_cli-1.2.148 → boost_skill_cli-1.2.150}/docs/roadmap.html

@@ -140,10 +140,10 @@
   <section class="block reveal">
     <div class="stats">
       <!-- ROADMAP:stats -->
-      <div class="stat"><b>21</b><span>Shipped</span></div>
+      <div class="stat"><b>22</b><span>Shipped</span></div>
       <div class="stat"><b>1</b><span>Next up</span></div>
       <div class="stat"><b>79</b><span>Planned</span></div>
-      <div class="stat"><b>504</b><span>Loop finds</span></div>
+      <div class="stat"><b>505</b><span>Loop finds</span></div>
       <!-- /ROADMAP:stats -->
     </div>
   </section>
@@ -396,6 +396,18 @@
         </div>
       </article>
 
+      <article class="cap rcard" id="dense-no-key-guard-is-unreachable">
+        <div class="head"><span class="pill shipped">Shipped</span><span class="cat">Quality · Retrieval eval</span></div>
+        <h3>fix_hint's no-key guard has been unreachable since the day it was written; a missing API key now prescribes the full re-embed the guard exists to prevent</h3>
+        <p class="cardbody"><a class="writeup" href="https://github.com/jonnyeclectic/boost/blob/main/docs/roadmap/items/dense-no-key-guard-is-unreachable.md">Write-up &middot; dense-no-key-guard-is-unreachable.md</a></p>
+        <div class="meta">
+          <span class="m">Complexity <b>L</b></span>
+          <span class="m hi">Impact <b>High</b></span>
+          <span class="m">Wow <b class="wow">★★★★</b></span>
+          <span class="m">A complete [rag] extra falls through a missing key to the local model, so the ladder reaches provider-changed and prescribes the full re-embed the guard exists to prevent. Two things can displace a store, and the fix answers both.</span>
+        </div>
+      </article>
+
       <article class="cap rcard" id="install-cannot-tell-a-skill-needs-another-one">
         <div class="head"><span class="pill shipped">Shipped</span><span class="cat">Install · Research</span></div>
         <h3>Research: how <code>boost install</code> could tell that a skill needs something else installed first</h3>
@@ -1100,61 +1112,6 @@ space before trusting a number in it.</p>
         </div>
       </article>
 
-      <article class="cap rcard" id="dense-no-key-guard-is-unreachable">
-        <div class="head"><span class="pill planned">Planned</span><span class="cat">Quality · Retrieval eval</span></div>
-        <h3>fix_hint's no-key guard has been unreachable since the day it was written; a missing API key now prescribes the full re-embed the guard exists to prevent</h3>
-        <p><b>Measured.</b> On a complete <code>[rag]</code> extra with a voyage-4-built vector store and no API key exported, <code>dense.status()</code> returns <code>reason='provider-changed'</code> (not <code>no-key</code>), so all three status-passing surfaces print <code>rebuild it: \</code>boost reindex --dense --force\`<code> and </code>boost doctor<code> exits 1 — measured verbatim, including doctor's "live key is local; searches are using BM25" line — while the guard written to prevent exactly that (</code>21f28223<code>, #444) fires only under </code>BOOST_NO_EMBED=1` or a partial install, both confirmed by direct probe.
-
-<b>Reproduce it.</b>
-
-<code>cd &lt;repo&gt;</code><br>
-<code>export HOME=$TMPDIR/verify-dense-f1; export BOOST_HOME=$HOME/.boost; mkdir -p "$HOME"</code><br>
-<code>unset VOYAGE_API_KEY OPENAI_API_KEY BOOST_NO_EMBED</code><br>
-<code>python3 tests/make_fixture.py $TMPDIR/verify-dense-f1-fix &gt;/dev/null</code><br>
-<code>./boost tap $TMPDIR/verify-dense-f1-fix &gt;/dev/null</code><br>
-<code># NOTE: ./boost execs system python3, which has no sqlite_vec, so it always says</code><br>
-<code># "no-backend". Every dense command below MUST run under .venv.</code><br>
-<code>.venv/bin/python - &lt;&lt;'PY'</code><br>
-<code>import hashlib, sys; sys.path.insert(0, ".")</code><br>
-<code>from boost_cli.core import catalog, dense, embed</code><br>
-<code>DIM = 1024</code><br>
-<code>def fake(texts, input_type=None, timeout=60):          # no network, no API spend</code><br>
-<code>    out = []</code><br>
-<code>    for t in texts:</code><br>
-<code>        h = hashlib.sha256(t.encode()).digest()</code><br>
-…
-
-<b>What adversarial verification corrected.</b> This card's numbers are the re-measured ones, not the ones first reported.
-
-The defect is real and reproduced verbatim, but five stated details are wrong:
-
-1. SOURCE ATTRIBUTION OF THE COST FIGURE. <code>why_it_matters</code> says "which CLAUDE.md prices at ~1.2 s per chunk on CPU". <code>grep -n 'per chunk\|1\.2 s' CLAUDE.md</code> returns nothing. The figure is real but lives in the roadmap: <code>docs/roadmap/items/keyless-semantic-search-for-everyone.md:298</code> ("4,431 s — 74 minutes, about 1.2 s per chunk") and <code>:308</code>, plus <code>the-shard-job-that-could-not-finish.md:17</code> and <code>keyless-dense-tier-local-static-embeddings.md:75</code>. Cite the roadmap, not CLAUDE.md.
-
-2. <code>quality.py:769</code> is wrong -&gt; the fix_hint call is <code>boost_cli/commands/quality.py:780</code> (<code>fix = dense.fix_hint(st["reason"], st)</code>). Line 769 sits inside the unrelated <code>search-quantization</code> warning.
-
-3. <code>pyproject.toml:55-57</code> is wrong -&gt; the three pins are at lines <b>56, 67 and 68</b> (<code>sqlite-vec&gt;=0.1.6</code>, <code>onnxruntime&gt;=1.17</code>, <code>tokenizers&gt;=0.15</code>), split by a 10-line comment justifying the fastembed rejection. They are in one extra, which is the load-bearing part, but the range is not 55-57.
-
-4. THE CAUSAL-ORDER COMMIT PAIR NAMES THE WRONG COMMIT FOR THE GUARD. <code>86163e03</code> (2026-07-31, #364) created <code>test_dense_fix_hint.py</code> <b>and the <code>_FIX</code> table</b>, but not the guard.
-
-<b>What is NOT established.</b> Recorded because a card that overstates its own evidence is worse than no card.
-
-PRECONDITION — state it on the card so nobody reads it as unconditional. The misroute needs (a) a store built with an API provider, (b) the complete <code>[rag]</code> extra so <code>provider()</code> falls through to <code>local</code>, and (c) the key absent from the *process* environment. #444's own commit message documents that shape as recurring in the wild: "the shell exports one; the spawned server does not inherit it."
-
-THE REAL MACHINE IS NOT CURRENTLY IN THE BUG STATE. <code>~/.boost/cache/rag_vectors.sqlite</code> reads provider="local", model="BAAI/bge-small-en-v1.5", dim=384 — so <code>provider()</code> matches <code>built_provider</code> and its reason is None. The 645,592-chunk / 1.20 GB / 440-tap figure is <b>cost-if-the-hint-is-followed</b>, not present harm. Do not let the card imply the machine is broken today. (The 750,416-chunk voyage-4 store in the #444 message and the test docstring is a past state of the same machine.)
-
-THE MISDIAGNOSIS WAS REFUTABLE FROM THE SAME FILE. The <code>_FIX</code> comment — "This reason means 'no key AND no local backend', which in practice is a partial install or BOOST_NO_EMBED" — was already in <code>dense.py</code> from 86163e03 (07-31) when #444 (08-03) added a guard whose docstring asserts the opposite: "an unfinished install with no store and a complete install whose key merely went missing both land here." Two claims about <code>no-key</code>, 30 lines apart, that contradict each other.
-
-<b>Why it is worth doing.</b> A user who opens a new shell without exporting their key is told by doctor, search and the MCP server to re-embed their whole store. On the real machine in this repo that is 645,592 chunks / 1.20 GB, which CLAUDE.md prices at ~1.2 s per chunk on CPU — hours of compute, or a real API bill — to fix a problem whose actual remedy is one <code>export</code>. The repo already decided this was unacceptable and wrote six tests plus a paragraph of docstring to prevent it; the guard has simply never been able to fire.
-
-<em>Found by an automated audit of retrieval/eval quality, the search &amp; browse surfaces, and first-run onboarding; every finding was then re-measured from scratch by an independent adversarial verifier whose instruction was to refute it. Verdict: <b>CORRECTED</b>. No fix is prescribed here — the measurement is the contribution.</em></p>
-        <div class="meta">
-          <span class="m">Complexity <b>L</b></span>
-          <span class="m hi">Impact <b>High</b></span>
-          <span class="m">Wow <b class="wow">★★★★</b></span>
-          <span class="m">dense.status() checks prov is None before it looks at the store (dense.py:618-621), b…</span>
-        </div>
-      </article>
-
       <article class="cap rcard" id="dense-ready-but-embedder-cannot-run">
         <div class="head"><span class="pill shipped">Shipped</span><span class="cat">Quality · Retrieval eval</span></div>
         <h3>status() has no state for "ready but the embedder does not work": doctor green-ticks a tier that never ran, the search hint is suppressed, and every search re-pays the failed model fetch</h3>
@@ -2214,6 +2171,41 @@ instead of on a user's machine.</p>
           <span class="m">Two functions built the same `mcp add` command line, one had never heard of agy, and both got Gemini wrong…</span>
         </div>
       </article>
+
+      <article class="cap rcard" id="dense-local-built-store-displaced-by-a-key">
+        <div class="head"><span class="pill planned">Planned</span><span class="cat">Quality · Retrieval eval</span></div>
+        <h3>A locally built vector store displaced by a new API key is told to re-embed through the paid provider, where unsetting the key is free</h3>
+        <p><b>The mirror of #989, and the expensive direction.</b> #989 taught <code>fix_hint</code> that a store built with an API key can be displaced two ways, and to name the <code>export</code> or the <code>unset</code> that restores it. A store built by the <b>local</b> model is displaced by exactly the same mechanism — a key the resolver prefers appears on the machine — and gets none of it: the branch is gated on <code>env = embed.KEY_ENV.get(built)</code> being truthy, and <code>local</code> has no env var, so it falls through to the table.
+
+<b>Measured.</b> Two stores of 645,592 chunks, same machine, only <code>VOYAGE_API_KEY</code> set. Verbatim, through the real <code>dense.status()</code> ladder:
+
+<code>##### store built with 'local', live key = VOYAGE</code><br>
+<code>  status reason : provider-changed</code><br>
+<code>  outranking('local') : ('VOYAGE_API_KEY',)</code><br>
+<code>  DOCTOR |   ! semantic search silently off — 645592-chunk vector store built with</code><br>
+<code>  DOCTOR |     rebuild it: `boost reindex --dense --force`</code><br>
+<br>
+<code>##### store built with 'openai', live key = VOYAGE</code><br>
+<code>  status reason : provider-changed</code><br>
+<code>  DOCTOR |     set the key it was built with: `export OPENAI_API_KEY=...`, then</code><br>
+<code>  DOCTOR |     `unset VOYAGE_API_KEY` puts it back in front — or …</code>
+
+<code>embed.outranking('local')</code> already computes the answer — <code>unset VOYAGE_API_KEY</code> — and restores that store instantly and for nothing. The line boost actually prints re-embeds 645,592 chunks through a metered API.
+
+<b>Why it is not a corner case.</b> <code>boost quickstart</code> imports the published vector shards, and those are keyless: <code>BAAI/bge-small-en-v1.5</code> at 384 dimensions, built by the local model. So the default on-ramp leaves every user with a local-built store, and the first time one of them exports a Voyage or OpenAI key for anything at all, semantic search goes quiet and doctor bills them to get it back.
+
+<b>The constraint any fix has to clear</b>, and the reason this is a separate card rather than a line in #989: <code>unset</code> is only the right advice for a local-built store <b>if the local model is installed</b>. On a partial <code>[rag]</code> install, unsetting the one key in force sends <code>provider()</code> to <code>None</code> and the ladder to <code>no-key</code> — the advice would switch off the only thing making search work. So the predicate needs to ask whether the local model is there — and the one to ask is <code>embed.local_installed()</code>, not <code>embed.local_available()</code>: <code>local_available</code> answers by importing the ONNX runtime, which is right for a caller about to embed and wrong for one about to word a sentence. <code>dense.free_shard_path</code>, the sibling that words the other keyed-machine hint, already uses <code>local_installed</code> for exactly that reason. Either way it is a check the key-built branches do not need.
+
+Two more things fall out of that. The sentence needs a third variant — "puts the store's own key back in front" is false for a store that has no key; it is the local model being put back in front. And the admission test must be <code>built in embed.KEY_ENV or built == "local"</code>, never "has a recorded provider": <code>embed.outranking("")</code> returns <b>every</b> set key, so a store whose meta records no provider would be told to unset the machine's entire keyring on the strength of a blank field.
+
+<b>Where it was found.</b> The adversarial verification pass on #989, which is also why the measurement exists. #989's PR body originally scoped this out as "not measured here"; it is measured now, and <code>docs/semantic-search.md</code> carries a qualifier pointing at this card until it lands.</p>
+        <div class="meta">
+          <span class="m">Complexity <b>S</b></span>
+          <span class="m hi">Impact <b>High</b></span>
+          <span class="m">Wow <b class="wow">★★★★</b></span>
+          <span class="m">Exporting an API key takes a locally built store off the air, and doctor answers with a paid re-embed where `unset` is free. Every user who came in through `boost quickstart` is one `export` away from this.</span>
+        </div>
+      </article>
       <!-- /ROADMAP:cards -->
 
     </div>

{boost_skill_cli-1.2.148 → boost_skill_cli-1.2.150}/docs/semantic-search.md

@@ -185,13 +185,37 @@ deliberately no vectors, for the same reason.
 | no backend | `pip install "boost-skill-cli[rag]"` (`pipx inject boost-skill-cli "boost-skill-cli[rag]"` under pipx) |
 | no store | `boost reindex --dense` |
 | store is empty | `boost reindex --dense --force` |
-| version, model, provider or dimension changed | `boost reindex --dense --force` |
+| version, model or dimension changed | `boost reindex --dense --force` |
+| provider changed, and a store built with a key | put that key back in force. The rebuild is offered as the alternative, and it re-embeds everything |
 | no key, and a store built with one | set the key it was built with. Reinstalling the extra swaps in the local model and forces a full re-embed |
 
-That last row is the one worth reading twice. If your store was built against
-Voyage or OpenAI and the key later goes missing, the fix is to put the key back.
-The generic "reinstall the extra" answer would install the local model, change
-the provider, and re-embed every vector you already paid for.
+Those last two rows are the ones worth reading twice, and the first of them is
+the one you are likely to meet. If your store was built against Voyage or
+OpenAI and the key later goes missing, doctor reports **provider changed**, not
+**no key**: the `[rag]` extra ships a local model, so a provider still
+resolves — it is simply not the one your vectors are in. The fix is to put the
+key back, and the generic "rebuild" answer would re-embed every vector you
+already paid for.
+
+For a store **built with a key**, two separate things can stand between it and
+its own provider, and doctor names whichever applies:
+
+- the key is gone, so `export` brings it back;
+- a key boost prefers is in force. The order is Voyage, then OpenAI, then the
+  local model, so an OpenAI-built store goes dark the moment a Voyage key
+  appears on the machine — `unset VOYAGE_API_KEY` is what hands it back.
+
+Both can be true at once, and then doctor names both steps. Running only the
+export would leave the resolver exactly where it was.
+
+A store built by the **local** model is displaced the same way — exporting a
+key on a machine whose vectors are local ones takes semantic search off — but
+doctor does not yet name the `unset` for it, and offers the rebuild instead.
+Tracked as a follow-up; `unset` is the free fix in the meantime.
+
+If you would rather move to the live provider than restore the old one,
+`boost reindex --dense --force` is the command, and doctor names the space it
+would land the vectors in.
 
 ## Search is slow