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

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

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

{boost_skill_cli-1.2.150 → boost_skill_cli-1.2.152}/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.150'
-__version_tuple__ = version_tuple = (1, 2, 150)
+__version__ = version = '1.2.152'
+__version_tuple__ = version_tuple = (1, 2, 152)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.150 → boost_skill_cli-1.2.152}/boost_cli/core/catalog.py

@@ -26,6 +26,7 @@ import operator
 import os
 import re
 import sys
+from collections.abc import Iterable
 from pathlib import Path
 
 from ..errors import BoostError
@@ -115,6 +116,49 @@ def _content_digest(name: str, description: str, body: str) -> str:
     return hashlib.sha256(text.strip().encode("utf-8", "replace")).hexdigest()[:16]
 
 
+def content_unique(entries: Iterable[dict]) -> list[dict]:
+    """The first entry of each distinct ``content`` digest, in scan order.
+
+    An entry carrying no digest is always kept. Two absences are not a match:
+    a cache written before ``CACHE_FORMAT`` stamped the field, or an entry
+    synthesised without one, says nothing about what that item *is*, and
+    collapsing unknowns into each other silently deletes real items.
+
+    The digest is :func:`_content_digest` — ``name``, ``description`` and the
+    frontmatter-stripped body — which is the identity
+    :func:`rag.dedupe_by_content` collapses a ranked list on. It is not
+    ``scripts/measure_registry.py``'s digest, which hashes the body alone with
+    agent dotdir tokens normalised so one skill rendered into ``.claude/``,
+    ``.cursor/`` and ``.gemini/`` counts once. That is the right question for
+    ``est_items`` and the wrong one here: the gate scores those renders as
+    separate competing rows, so a measure that merges them cannot describe the
+    corpus it ranks.
+    """
+    seen: set[str] = set()
+    out: list[dict] = []
+    for entry in entries:
+        digest = entry.get("content")
+        if not digest:
+            out.append(entry)
+            continue
+        if digest in seen:
+            continue
+        seen.add(digest)
+        out.append(entry)
+    return out
+
+
+def distinct_content(entries: Iterable[dict]) -> int:
+    """How many distinct content identities ``entries`` holds.
+
+    ``len(content_unique(entries))``, and deliberately not
+    ``len({e["content"] for e in entries})``: the set comprehension collapses
+    every entry with no recorded digest into one ``None``, which is the one
+    answer :func:`content_unique` exists to refuse.
+    """
+    return len(content_unique(entries))
+
+
 def _entry_category(meta: dict, tap_category: str) -> str:
     """An item's own category, falling back to its tap's curated category.
 
@@ -406,9 +450,8 @@ def lint_targets(entries: list[dict], tap_root: Path,
                 "no such name%s in this tap: %s"
                 % ("" if len(unknown) == 1 else "s", ", ".join(unknown)),
                 hint="run without NAMEs to lint everything in the tap")
-    skills: list[dict] = []
+    kept: list[dict] = []
     skipped: list[dict] = []
-    seen_content: set = set()
     for entry in entries:
         if wanted and entry["name"] not in wanted:
             continue
@@ -416,12 +459,10 @@ def lint_targets(entries: list[dict], tap_root: Path,
         if kind != KIND_SKILL:
             skipped.append({"name": entry["name"], "kind": kind})
             continue
-        digest = entry.get("content")
-        if digest:
-            if digest in seen_content:
-                continue
-            seen_content.add(digest)
-        skills.append(entry)
+        kept.append(entry)
+    # One rule, one implementation: mirrors of one skill lint once, and an
+    # entry with no digest is never absorbed into another.
+    skills = content_unique(kept)
 
     name_counts: dict[str, int] = {}
     for entry in skills:

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

@@ -568,10 +568,12 @@ _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.
+    # Only right when the live space is the one the user wants. Two kinds of
+    # store land here without wanting it: one built through a paid provider
+    # that has merely lost its key, and one the local model built on a machine
+    # that has since exported a key. For both this row is the bill the guards
+    # in `fix_hint` exist to prevent, so it answers from the status dict —
+    # `_restore_built_space` and `_restore_local_space` — before reaching here.
     "provider-changed": "rebuild it: `boost reindex --dense --force`",
     "model-changed": "rebuild it: `boost reindex --dense --force`",
     "dim-changed": "rebuild it: `boost reindex --dense --force`",
@@ -664,6 +666,49 @@ def _restore_built_space(built: str, env: str) -> str | None:
     return None
 
 
+def _restore_local_space() -> str | None:
+    """How to put the *local* model back in front of a key, or None.
+
+    The mirror of :func:`_restore_built_space`, and the expensive direction.
+    A store the local model built is displaced by exactly the mechanism that
+    displaces a keyed one — a provider `embed.provider` prefers appears on the
+    machine — and it is the common case rather than the exotic one: `boost
+    quickstart` imports the published shards, those are keyless 384-d local
+    vectors by policy, so the default on-ramp leaves every user one `export`
+    away from this.
+
+    Separate from :func:`_restore_built_space` rather than a fourth branch in
+    it, because the predicate is different in two ways:
+
+    * **`unset` is only right advice when the local model is installed.**
+      Dropping the one key in force on a partial ``[rag]`` install sends
+      `embed.provider` to ``None`` and the ladder to ``no-key`` — advice that
+      switches off the only backend that was working. :func:`free_shard_path`
+      guards the same way and for the same reason; ``local_installed`` rather
+      than ``local_available`` because wording a hint must not import an ONNX
+      runtime.
+    * **There is no ``export`` half.** Local has no key, so the two-fact shape
+      collapses to one, and the sentence has to say what is being put back —
+      the local model, not "the store's own key", which a keyless store does
+      not have.
+
+    None when nothing outranks local, which through :func:`status` means the
+    store is not displaced at all. :func:`fix_hint` is a pure function of its
+    arguments, though, so the case is reachable by a caller and answered.
+    """
+    if not embed.local_installed():
+        return None
+    # `outranking` reads the one preference order there is. Local is not in
+    # `KEY_ENV`, and its docstring is explicit that a name outside the table
+    # is outranked by every key in force — which is the semantics wanted here:
+    # dropping `VOYAGE_API_KEY` alone falls through to `OPENAI_API_KEY`, no
+    # nearer the local space than the key it replaced.
+    drop = embed.outranking("local")
+    if not drop:
+        return None
+    return "`unset %s` puts the local model back in front" % " ".join(drop)
+
+
 def fix_hint(reason: str, status: dict | None = None) -> str:
     """The single next action for a `status()` reason, or a safe default.
 
@@ -686,6 +731,17 @@ def fix_hint(reason: str, status: dict | None = None) -> str:
     ``built_provider`` is what separates a store worth reviving from an
     unfinished install with nothing to revive.
 
+    ``built_provider`` is also read for the mirror case, which is the one most
+    users can reach: a store the **local** model built, on a machine that has
+    since exported a key. `boost quickstart` imports keyless 384-d shards, so
+    that is the default shape, and one `export` for an unrelated tool takes
+    semantic search off. `_restore_local_space` answers it with the `unset`
+    that is free, where the table would sell a re-embed through the very API
+    whose key caused the problem. Only ``local`` and the names in
+    :data:`embed.KEY_ENV` are admitted — a blank ``built_provider`` is not a
+    store to revive, and `embed.outranking` would answer for it with every
+    key on the machine.
+
     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
@@ -719,23 +775,39 @@ def fix_hint(reason: str, status: dict | None = None) -> str:
         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
-        # falls through — that user does need the package back.
+        # there is nothing to revive, and "build it" is the real next step.
         count = status.get("chunks")
         # `None` is "a store is here and never recorded its total" — a legacy
         # store, not an unfinished one. Only a *known* zero means there are no
         # 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):
+        #
+        # `env or built == "local"` is the admission test, and it is spelled
+        # out rather than "has a recorded provider" on purpose: `outranking`
+        # answers for a name outside `KEY_ENV` with *every* key in force, so a
+        # store whose meta records no provider — `""` here, from a legacy
+        # cache or a synthesised status — would be handed `unset` over the
+        # machine's entire keyring on the strength of a blank field.
+        if (env or built == "local") and (count is None or count > 0):
             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))
+                if env:
+                    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))
+                # Local-built, and the model it was built with is what went
+                # missing. The table's row would be nearly right and ends in
+                # the one suggestion that is wrong for this store: setting a
+                # key displaces it into another space, and with the local
+                # backend still absent the next status is `provider-changed`
+                # with nothing to unset back to — the full re-embed.
+                return ("reinstall the extra: `%s` — it is the model all %s "
+                        "were built with, and a key instead re-embeds them"
+                        % (install_extra(), n))
             live = status.get("provider")
-            restore = _restore_built_space(built, env)
+            restore = (_restore_built_space(built, env) if env
+                       else _restore_local_space())
             if restore:
                 # Names the live space rather than "the local model": the
                 # provider that displaced this store is whatever `provider()`

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

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

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

@@ -903,6 +903,7 @@ tests/unit/test_builtin.py
 tests/unit/test_canary_deps.py
 tests/unit/test_capabilities.py
 tests/unit/test_catalog.py
+tests/unit/test_catalog_distinct.py
 tests/unit/test_catalog_keyword_words.py
 tests/unit/test_catalogbundle.py
 tests/unit/test_chat.py

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

@@ -1,14 +1,16 @@
 ---
 id: dense-local-built-store-displaced-by-a-key
 board: code
-section: planned
-status: planned
+section: shipped
+status: shipped
 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
+owner: loop/dense-local-displaced
+pr: 990
 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.
@@ -34,4 +36,4 @@ title: A locally built vector store displaced by a new API key is told to re-emb
 
 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.
+<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 #990 removes the qualifier <code>docs/semantic-search.md</code> was carrying in the meantime.

{boost_skill_cli-1.2.150 → boost_skill_cli-1.2.152}/docs/roadmap/items/eval-corpus-counted-by-the-method-the-repo-disavows.md

@@ -1,19 +1,34 @@
 ---
 id: eval-corpus-counted-by-the-method-the-repo-disavows
 board: code
-section: planned
-status: planned
+section: shipped
+status: shipped
 category: Quality · Retrieval eval
 complexity: L
 impact: High
 wow: 4
-note: scripts/eval_corpus.py counts a repo's contribution as len(entries) from a raw scan (…
+note: taps.txt rows gained a distinct-content count and the gate gained a second ceiling. The raw count stays — BM25 indexes without de-duplicating, so the copies really are documents — but sickn33 is 61.8% of the rows and 35.7% of the content, and only one number was being floored.
 order: 208
-owner:
-pr:
+owner: loop/eval-corpus-distinct-count
+pr: 992
 title: The eval corpus's size and its concentration ceiling are counted with <code>len(scan_dir)</code> — the measure <code>measure_registry.py</code> exists to say is wrong — so 44.7% of the gate's corpus is vendored …
 ---
-<b>Measured.</b> Two tools in this repo, run on the same clone at the same pinned SHA, give item counts 3.16x apart — <code>scripts/measure_registry.py</code> says <code>est_items=2100</code> while <code>scripts/eval_corpus.py --ensure</code> records <code>6634 entries</code> — and the tool that is right is the one the eval gate does not use: measure_registry.py's own docstring (lines 6-11) states that <code>len(catalog.scan_dir(repo))</code> is not the measurement, "the same rule the eval gate's ranked list uses". <code>eval_corpus.py:299</code> is still <code>counts[repo] = len(entries)</code>, and <code>MAX_SHARE = 0.65</code> (line 113) ratchets on that number inside CI's required <code>lint</code> job — so 976 extra vendored copies from one stranger's repository, containing zero new content, turn every open pull request red.
+<b>SHIPPED.</b> taps.txt rows gained a fourth field — the distinct-content count — and the concentration gate became two ceilings instead of one.
+
+<code>anthropics/skills   3b3fad9…   20    20</code><br>
+<code>sickn33/antigravity-awesome-skills   782f684…   6634  2117</code>
+
+<code>MAX_SHARE</code> is now <code>MAX_ROW_SHARE</code> (0.65) and is joined by <code>MAX_CONTENT_SHARE</code> (0.40), and both are checked on every <code>--ensure</code>, <code>--relock</code>, <code>--refresh</code> and <code>--audit</code>. At the current pins: sickn33 is <b>61.8% of the rows and 35.7% of the content</b>, and affaan-m/ECC is <b>15.1% of rows and 26.7% of content</b> — the two orderings differ, which is the whole reason there are two numbers. The corpus is 10,731 rows over 5,938 distinct items, so the rows overstate it <b>1.81x</b>, and taps.txt now says so in its own generated size block.
+
+<b>The raw count was kept, deliberately.</b> This card's title reads as "the raw count is wrong", and the fix is not to replace it. <code>rag.build</code> indexes <code>catalog.all_entries()</code> with <b>no</b> de-duplication, so a registry vendoring the same skill sixty-eight times really does occupy sixty-eight of the documents BM25 ranks a query against: the raw count is the honest number for the DRIFT check and for "BM25 scored N documents". What was missing was the second number, not a correction to the first. Hence two fields and two ceilings rather than one replaced.
+
+<b>The identity is <code>catalog._content_digest</code>, not <code>measure_registry.py</code>'s.</b> Two new helpers in <code>boost_cli/core/catalog.py</code> — <code>content_unique()</code> and <code>distinct_content()</code> — collapse on <code>entry["content"]</code>, the digest over name + description + body already stamped at scan time and already what <code>rag.dedupe_by_content</code> uses. <code>measure_registry.py</code>'s digest hashes the body <em>alone</em> with agent-dotdir tokens normalised, which is right for <code>est_items</code> (one skill rendered into five agents' directories is one item) and wrong here (two different skills with the same body are two documents in the index). The card's premise that these are the same rule is what <code>measure_registry.py</code>'s docstring claims and is not true; the gate now uses the one that matches what it scores.
+
+<b>An unsatisfiable ceiling is not a strict one.</b> A ceiling of <em>c</em> cannot be met by fewer than <code>1/c</code> repositories, because the smallest possible top share is <code>1/N</code> — two repos cannot get below 50%, so a 40% content ceiling would refuse every two-repo corpus however it was balanced, and the only remedy it could print ("add breadth") is the only thing that could ever clear it. <code>check_concentration</code> therefore does not judge a corpus below that floor. The shipped list has twenty repos against a floor of three, so the real gate is untouched; what it buys is that a fixture corpus can exercise the same code path.
+
+<b>Not regenerated: <code>tests/eval/baseline.json</code>.</b> No pin moved and the indexed corpus is byte-identical, so the scores are unchanged — regenerating it would have been noise in the diff and a claim that something had been re-measured.
+
+<b>Measured.</b> Two tools in this repo, run on the same clone at the same pinned SHA, give item counts 3.16x apart — <code>scripts/measure_registry.py</code> says <code>est_items=2100</code> while <code>scripts/eval_corpus.py --ensure</code> records <code>6634 entries</code> — and the tool that is right is the one the eval gate does not use: measure_registry.py's own docstring (lines 6-11) states that <code>len(catalog.scan_dir(repo))</code> is not the measurement, "the same rule the eval gate's ranked list uses". <code>eval_corpus.py</code> was still <code>counts[repo] = len(entries)</code>, and <code>MAX_SHARE = 0.65</code> ratcheted on that number inside CI's required <code>lint</code> job — so 975 extra vendored copies from one stranger's repository, containing zero new content, turn every open pull request red.
 
 <b>Reproduce it.</b>
 
@@ -33,7 +48,7 @@ title: The eval corpus's size and its concentration ceiling are counted with <co
 
 <b>What adversarial verification corrected.</b> This card's numbers are the re-measured ones, not the ones first reported.
 
-1. MATERIALLY WRONG — "The vendoring is 60 <code>plugins/agentic-bundle-*/</code> directories". There are 58 <code>agentic-bundle-*</code> dirs (60 <code>plugins/*</code> dirs total), and they hold only 449 of the 6,634 entries (6.8%; median 8 entries each). The 3.13x inflation is two FULL CATALOG MIRRORS: <code>plugins/agentic-awesome-skills-claude</code> (2,049 entries) and <code>plugins/agentic-awesome-skills</code> (2,027) = 4,076 entries, digest-identical to <code>skills/</code> (2,107 entries, all distinct). This reframes the ceiling scenario: "one more bundle render... adds ~2,117 entries" is impossible — a bundle is ~8-10 entries. The correct unit is "one more per-agent mirror", ~2,049 entries -&gt; 67.9%, still over 65%. Sharper still: only 976 extra vendored sickn33 entries are needed to cross the ceiling (&lt; half a mirror). The conclusion survives; the unit does not — and the correct unit is exactly the pattern the <code>est-items</code> card already documents.
+1. MATERIALLY WRONG — "The vendoring is 60 <code>plugins/agentic-bundle-*/</code> directories". There are 58 <code>agentic-bundle-*</code> dirs (60 <code>plugins/*</code> dirs total), and they hold only 449 of the 6,634 entries (6.8%; median 8 entries each). The 3.13x inflation is two FULL CATALOG MIRRORS: <code>plugins/agentic-awesome-skills-claude</code> (2,049 entries) and <code>plugins/agentic-awesome-skills</code> (2,027) = 4,076 entries, digest-identical to <code>skills/</code> (2,107 entries, all distinct). This reframes the ceiling scenario: "one more bundle render... adds ~2,117 entries" is impossible — a bundle is ~8-10 entries. The correct unit is "one more per-agent mirror", ~2,049 entries -&gt; 67.9%, still over 65%. Sharper still: only 975 extra vendored sickn33 entries are needed to cross the ceiling (&lt; half a mirror) — 6634+975 of 10731+975 is 65.001%, and 974 is 64.998%. The conclusion survives; the unit does not — and the correct unit is exactly the pattern the <code>est-items</code> card already documents.
 
 2. "Read all 318 titles from <code>grep -h '^title:' docs/roadmap/items/*.md</code>" — there are 432 items / 432 title lines today (verified identical to origin/main except one unrelated file). The not-carded sweep was run over a smaller set than exists.
 

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

@@ -140,9 +140,9 @@
   <section class="block reveal">
     <div class="stats">
       <!-- ROADMAP:stats -->
-      <div class="stat"><b>22</b><span>Shipped</span></div>
+      <div class="stat"><b>24</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>77</b><span>Planned</span></div>
       <div class="stat"><b>505</b><span>Loop finds</span></div>
       <!-- /ROADMAP:stats -->
     </div>
@@ -408,6 +408,18 @@
         </div>
       </article>
 
+      <article class="cap rcard" id="eval-corpus-counted-by-the-method-the-repo-disavows">
+        <div class="head"><span class="pill shipped">Shipped</span><span class="cat">Quality · Retrieval eval</span></div>
+        <h3>The eval corpus's size and its concentration ceiling are counted with <code>len(scan_dir)</code> — the measure <code>measure_registry.py</code> exists to say is wrong — so 44.7% of the gate's corpus is vendored …</h3>
+        <p class="cardbody"><a class="writeup" href="https://github.com/jonnyeclectic/boost/blob/main/docs/roadmap/items/eval-corpus-counted-by-the-method-the-repo-disavows.md">Write-up &middot; eval-corpus-counted-by-the-method-the-repo-disavows.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">taps.txt rows gained a distinct-content count and the gate gained a second ceiling. The raw count stays — BM25 indexes without de-duplicating, so the copies really are documents — but sickn33 is 61.8% of the rows and 35.7% of the content, and only one number was being floored.</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>
@@ -419,6 +431,18 @@
           <span class="m">The premise was wrong — boost has always followed <code>requires:</code>. It is the narrowest spelling in the ecosystem (101 values); <code>skills:</code> and <code>dependencies:</code> carry 2,388 more and were invisible.</span>
         </div>
       </article>
+
+      <article class="cap rcard" id="dense-local-built-store-displaced-by-a-key">
+        <div class="head"><span class="pill shipped">Shipped</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 class="cardbody"><a class="writeup" href="https://github.com/jonnyeclectic/boost/blob/main/docs/roadmap/items/dense-local-built-store-displaced-by-a-key.md">Write-up &middot; dense-local-built-store-displaced-by-a-key.md</a></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>
@@ -1136,52 +1160,6 @@ space before trusting a number in it.</p>
         </div>
       </article>
 
-      <article class="cap rcard" id="eval-corpus-counted-by-the-method-the-repo-disavows">
-        <div class="head"><span class="pill planned">Planned</span><span class="cat">Quality · Retrieval eval</span></div>
-        <h3>The eval corpus's size and its concentration ceiling are counted with <code>len(scan_dir)</code> — the measure <code>measure_registry.py</code> exists to say is wrong — so 44.7% of the gate's corpus is vendored …</h3>
-        <p><b>Measured.</b> Two tools in this repo, run on the same clone at the same pinned SHA, give item counts 3.16x apart — <code>scripts/measure_registry.py</code> says <code>est_items=2100</code> while <code>scripts/eval_corpus.py --ensure</code> records <code>6634 entries</code> — and the tool that is right is the one the eval gate does not use: measure_registry.py's own docstring (lines 6-11) states that <code>len(catalog.scan_dir(repo))</code> is not the measurement, "the same rule the eval gate's ranked list uses". <code>eval_corpus.py:299</code> is still <code>counts[repo] = len(entries)</code>, and <code>MAX_SHARE = 0.65</code> (line 113) ratchets on that number inside CI's required <code>lint</code> job — so 976 extra vendored copies from one stranger's repository, containing zero new content, turn every open pull request red.
-
-<b>Reproduce it.</b>
-
-<code>cd &lt;repo&gt;</code><br>
-<code>export HOME=$TMPDIR/audit-corpus-verify &amp;&amp; mkdir -p "$HOME" &amp;&amp; export BOOST_HOME=$HOME/.boost</code><br>
-<code>.venv/bin/python scripts/eval_corpus.py --ensure      # -&gt; "corpus: 10731 entries"; "concentration: ... 61.8%"</code><br>
-<code>.venv/bin/python scripts/measure_registry.py "$BOOST_HOME/repos/sickn33__antigravity-awesome-skills"   # -&gt; est_items=2100</code><br>
-<code>.venv/bin/python - &lt;&lt;'PY'</code><br>
-<code>import json, pathlib, collections, os</code><br>
-<code>home=pathlib.Path(os.environ["BOOST_HOME"]); ents=[]</code><br>
-<code>for f in sorted((home/"cache").glob("*.json")):</code><br>
-<code>    if f.stem.startswith("rag_"): continue</code><br>
-<code>    d=json.loads(f.read_text())</code><br>
-<code>    for e in d["skills"]: e["_tap"]=d["tap"]; ents.append(e)</code><br>
-<code>alld={e["content"] for e in ents}</code><br>
-…
-
-<b>What adversarial verification corrected.</b> This card's numbers are the re-measured ones, not the ones first reported.
-
-1. MATERIALLY WRONG — "The vendoring is 60 <code>plugins/agentic-bundle-*/</code> directories". There are 58 <code>agentic-bundle-*</code> dirs (60 <code>plugins/*</code> dirs total), and they hold only 449 of the 6,634 entries (6.8%; median 8 entries each). The 3.13x inflation is two FULL CATALOG MIRRORS: <code>plugins/agentic-awesome-skills-claude</code> (2,049 entries) and <code>plugins/agentic-awesome-skills</code> (2,027) = 4,076 entries, digest-identical to <code>skills/</code> (2,107 entries, all distinct). This reframes the ceiling scenario: "one more bundle render... adds ~2,117 entries" is impossible — a bundle is ~8-10 entries. The correct unit is "one more per-agent mirror", ~2,049 entries -&gt; 67.9%, still over 65%. Sharper still: only 976 extra vendored sickn33 entries are needed to cross the ceiling (&lt; half a mirror). The conclusion survives; the unit does not — and the correct unit is exactly the pattern the <code>est-items</code> card already documents.
-
-2. "Read all 318 titles from <code>grep -h '^title:' docs/roadmap/items/*.md</code>" — there are 432 items / 432 title lines today (verified identical to origin/main except one unrelated file). The not-carded sweep was run over a smaller set than exists.
-
-3. "Every one of them... none measures distinct content" is wrong.
-
-<b>What is NOT established.</b> Recorded because a card that overstates its own evidence is worse than no card.
-
-SCOPE OF MY REPRO — what I actually settled, and what I did not. - I materialised the corpus at the CURRENT taps.txt pins in my own disposable HOME and reproduced every headline number independently. The pre-refresh figures (10,152 / 5,790 / 62.1% / 34.5% / 3.16x) I took from the SHARED read-only eval-home at $TMPDIR/eval-home, which is still at the older pins — a read-only census, no writes. - The repo checkout was on a peer session's branch <code>loop/missing-json</code>, not <code>main</code>. I diffed every file this finding touches (scripts/eval_corpus.py, tests/eval/taps.txt, boost_cli/core/rag.py, .github/workflows/eval-corpus-refresh.yml, all of docs/roadmap/items/) against origin/main: identical except one unrelated roadmap item. The verification holds against main (origin/main af4bdbfd). - I could NOT isolate the causal mechanism of the 22 rank changes. The finding asserts "BM25 statistics (N and document frequency), not slot consumption". My data is CONSISTENT with that — <code>dedupe_by_content</code> does run over the full pool before k (rag.py:1053, confirmed), and recall@k is bit-identical while the rank-sensitive metrics move — but I did not separate idf from avgdl, nor rule out that a different byte-identical copy survives dedupe and carries a different <code>grade_key</code>. Write it as "consistent with", not "confirmed".
-
-WHY HIGH RATHER THAN MEDIUM. The metric movement alone cannot fail anything: hit@1 +0.011, MRR +0.010, nDCG +0.008 against 0.06-0.10 of headroom over the floors. The severity is the ratchet's teeth, which the finder never traced.
-
-<b>Why it is worth doing.</b> <code>MAX_SHARE</code> is the only shipped guard against the gate's corpus becoming one publisher's house style, and it is measured on a quantity a third party can inflate by ~3x without publishing a single new skill — so it can fire on a repo contributing a third of the content, and cannot fire on a repo that dominates the content without vendoring. The same raw count is the headline everywhere (<code>10,152 entries</code> / <code>62%</code>) and is what the monthly refresh PR reports as growth, overstating real content growth 4x.
-
-<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">scripts/eval_corpus.py counts a repo's contribution as len(entries) from a raw scan (…</span>
-        </div>
-      </article>
-
       <article class="cap rcard" id="eval-corpus-duplication-is-intra-tap-not-mirrors">
         <div class="head"><span class="pill planned">Planned</span><span class="cat">Quality · Retrieval eval</span></div>
         <h3>The corpus's 65.6% duplication is 99.93% inside a single tap, so the required gate never once exercises the cross-tap trust ordering dedup exists for — 0 swaps in 264,735 comparisons</h3>
@@ -2171,41 +2149,6 @@ 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.150 → boost_skill_cli-1.2.152}/docs/semantic-search.md

@@ -146,6 +146,12 @@ A key buys a larger embedding model. Nothing else changes.
 Set one and boost prefers it automatically, re-embedding on your next
 `boost reindex --dense`. Voyage wins if both are set.
 
+If you came in through `boost quickstart`, your vectors are the keyless local
+ones, and exporting a key is what takes them out of service — boost prefers
+the key, and nothing it has on disk is in that key's space. `boost doctor`
+names the `unset` that puts them back, so this is recoverable for free rather
+than at the price of a re-embed.
+
 Be deliberate about this, because switching providers is not free. Vectors are
 only meaningful inside the embedding space that produced them, so changing
 provider or model invalidates every vector you have and forces a full re-embed.
@@ -187,6 +193,7 @@ deliberately no vectors, for the same reason.
 | store is empty | `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 |
+| provider changed, and a store built by the local model | `unset` the keys in front of it. Free, and instant |
 | 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 |
 
 Those last two rows are the ones worth reading twice, and the first of them is
@@ -208,10 +215,17 @@ its own provider, and doctor names whichever applies:
 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.
+A store built by the **local** model is displaced the same way, and it is the
+case most people can reach: `boost quickstart` imports keyless vectors, so
+exporting a key for anything at all takes semantic search off. Doctor answers
+that one with the `unset` too — every key in front of local, since dropping
+`VOYAGE_API_KEY` alone falls through to `OPENAI_API_KEY`, which is no nearer
+the local space. There is no `export` half, because a local store has no key
+of its own.
+
+The one time doctor withholds that advice is when the local model is not
+installed. Dropping your only key there would leave no provider at all, so
+the rebuild really is the way out, and that is what it says.
 
 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