boost-skill-cli 1.0.332__tar.gz → 1.0.334__tar.gz

{boost_skill_cli-1.0.332/boost_skill_cli.egg-info → boost_skill_cli-1.0.334}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.332
+Version: 1.0.334
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.332 → boost_skill_cli-1.0.334}/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.332'
-__version_tuple__ = version_tuple = (1, 0, 332)
+__version__ = version = '1.0.334'
+__version_tuple__ = version_tuple = (1, 0, 334)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.332 → boost_skill_cli-1.0.334}/boost_cli/commands/discovery.py

@@ -194,6 +194,38 @@ def _hint_semantic_search(engine: str) -> None:
         out.info(out.role(line, "muted"))
 
 
+def _shard_io(args) -> int:
+    """`--export-shard` / `--import-shard`, the two halves of a prebuilt shard.
+
+    Embedding is ~1.2 s/chunk on CPU — 74 minutes for 743 entries — so without
+    a way to move vectors between machines the keyless tier is available in
+    principle and unreachable in practice. Import validates rather than trusts;
+    see `dense.import_shard` for why a mismatched shard must be refused instead
+    of merged.
+    """
+    from ..core import dense
+    if args.export_shard:
+        shard = dense.export_shard(args.export_shard)
+        if not shard.get("chunks"):
+            raise BoostError("no vectors for %r" % args.export_shard,
+                            hint="build them first with `boost reindex --dense`")
+        print(json.dumps(shard))
+        return 0
+    path = Path(args.import_shard)
+    try:
+        shard = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise BoostError("cannot read shard %s: %s" % (path, exc)) from exc
+    tap = str(shard.get("tap") or "")
+    commit = rag._tap_commits().get(tap.replace("/", "__"), "")
+    ok, reason = dense.import_shard(shard, commit=commit)
+    if not ok:
+        raise BoostError("shard refused — %s" % reason,
+                        hint="`boost reindex --dense` embeds it locally instead")
+    out.ok("%s: %s" % (tap, reason))
+    return 0
+
+
 def cmd_reindex(argv):
     """Build/refresh the full-content (RAG) search index over tapped items."""
     p = cliparse.parser(
@@ -203,10 +235,19 @@ def cmd_reindex(argv):
                    help="reindex every tap, ignoring cached commits")
     p.add_argument("--dense", action="store_true",
                    help="also embed chunks into the opt-in dense vector store "
-                        "(needs the `rag` extra and an embeddings API key)")
+                        "(needs the `rag` extra; no API key required)")
+    p.add_argument("--export-shard", metavar="TAP",
+                   help="write TAP's prebuilt vectors to stdout as JSON, for "
+                        "publishing so others need not re-embed them")
+    p.add_argument("--import-shard", metavar="FILE",
+                   help="merge a prebuilt vector shard, skipping the embed "
+                        "cost; refused unless it matches this store's backend "
+                        "and the tap's current commit")
     p.add_argument("--json", action="store_true", dest="as_json",
                    help="machine-readable output")
     args = p.parse_args(argv)
+    if args.export_shard or args.import_shard:
+        return _shard_io(args)
     if not registry.list_taps():
         raise BoostError("no taps configured — nothing to index",
                         hint="add the recommended registries with `boost tap --defaults`")

{boost_skill_cli-1.0.332 → boost_skill_cli-1.0.334}/boost_cli/core/dense.py

@@ -12,6 +12,7 @@ are the expensive step, so an unchanged tap is never re-embedded.
 """
 from __future__ import annotations
 
+import base64
 import json
 import sqlite3
 from pathlib import Path
@@ -345,6 +346,116 @@ def build(entries: Optional[List[dict]] = None,
         con.close()
 
 
+def export_shard(tap: str) -> dict:
+    """One tap's vectors plus the provenance needed to validate them later.
+
+    Embedding is the expensive half of the keyless tier — measured at ~1.2 s per
+    chunk on CPU, so 74 minutes for 743 entries — while querying is milliseconds.
+    A shard lets that cost be paid once in CI and downloaded by everyone else.
+
+    The provenance fields are not decoration: vectors are only comparable inside
+    the embedding space that produced them, so provider/model/dim have to travel
+    with the rows, and the registry commit has to travel too or a stale shard
+    would be indistinguishable from a current one.
+    """
+    # Plain sqlite3, NOT _connect: exporting reads `chunks`, `meta` and the
+    # stored embedding blobs, all ordinary tables. Routing through _connect
+    # would make export impossible without the sqlite-vec extension — the same
+    # trap `_recorded_meta` documents — and a machine that built vectors and
+    # then dropped the extra is exactly the one whose shard is worth having.
+    if not db_path().exists():
+        return {"tap": tap, "chunks": []}
+    try:
+        con = sqlite3.connect(str(db_path()))
+    except sqlite3.Error:
+        return {"tap": tap, "chunks": []}
+    try:
+        meta = _read_meta(con)
+        commits = meta.get("commits")
+        commit = ""
+        if isinstance(commits, dict):
+            commit = str(commits.get(tap.replace("/", "__")) or "")
+        chunks = []
+        for row in con.execute(
+                "SELECT c.name, c.tap, c.path, c.kind, c.cix, c.snip, v.embedding "
+                "FROM chunks c JOIN vec_chunks v ON v.rowid = c.id "
+                "WHERE c.tap = ? ORDER BY c.id", (tap,)):
+            name, ctap, path, kind, cix, snip, emb = row
+            chunks.append({
+                "name": name, "tap": ctap, "path": path, "kind": kind,
+                "cix": cix, "snip": snip,
+                # base64 so the shard is plain JSON and can be published as a
+                # release artifact without a binary format of its own.
+                "embedding": base64.b64encode(bytes(emb)).decode("ascii"),
+            })
+        return {"tap": tap, "commit": commit,
+                "provider": meta.get("provider"), "model": meta.get("model"),
+                "dim": meta.get("dim"), "version": INDEX_VERSION,
+                "chunks": chunks}
+    except sqlite3.Error:
+        return {"tap": tap, "chunks": []}
+    finally:
+        con.close()
+
+
+def import_shard(shard: dict, commit: str) -> Tuple[bool, str]:
+    """Merge a prebuilt shard into this machine's store. ``(ok, reason)``.
+
+    Refuses rather than degrades. A vector is only meaningful against others
+    from the same embedding space, so a shard from a different provider, model
+    or dimension cannot be mixed in: doing so would not raise, it would quietly
+    return nonsense rankings, which is the worse failure. A shard whose commit
+    does not match the tap as it stands now is refused for a different reason —
+    accepting it would let `build()` mark that tap "reused" and never re-embed
+    it, pinning the user to stale vectors indefinitely.
+    """
+    for field in ("provider", "model", "dim"):
+        if shard.get(field) in (None, ""):
+            return False, "shard is missing %s" % field
+    if str(shard.get("commit") or "") != commit:
+        return False, ("commit mismatch: shard %r, tap %r"
+                       % (shard.get("commit"), commit))
+    con = _connect()
+    if con is None:
+        return False, "no vector backend available"
+    try:
+        meta = _read_meta(con)
+        # An empty store has no opinion yet, so it adopts the shard's backend.
+        if meta.get("provider"):
+            for field in ("provider", "model", "dim"):
+                if meta.get(field) != shard.get(field):
+                    return False, ("%s mismatch: store %r, shard %r"
+                                   % (field, meta.get(field), shard.get(field)))
+        dim = int(shard["dim"])
+        _ensure_schema(con, dim)
+        # Replace, never append: re-importing must not double a tap's rows.
+        _delete_taps(con, [str(shard.get("tap") or "")])
+        mod = _load()
+        for c in shard.get("chunks") or []:
+            cur = con.execute(
+                "INSERT INTO chunks (name, tap, path, kind, cix, snip) "
+                "VALUES (?, ?, ?, ?, ?, ?)",
+                (c.get("name"), c.get("tap"), c.get("path"), c.get("kind"),
+                 c.get("cix"), c.get("snip")))
+            blob = base64.b64decode(c["embedding"])
+            con.execute("INSERT INTO vec_chunks (rowid, embedding) VALUES (?, ?)",
+                        (cur.lastrowid, blob))
+        commits = meta.get("commits")
+        commits = dict(commits) if isinstance(commits, dict) else {}
+        commits[str(shard.get("tap") or "").replace("/", "__")] = commit
+        _write_meta(con, {"version": INDEX_VERSION,
+                          "provider": shard.get("provider"),
+                          "model": shard.get("model"), "dim": dim,
+                          "commits": commits})
+        con.commit()
+        _ = mod          # extension loaded by _connect; kept for symmetry
+        return True, "imported %d chunks" % len(shard.get("chunks") or [])
+    except sqlite3.Error as exc:
+        return False, "store error: %s" % exc
+    finally:
+        con.close()
+
+
 def _indexed_taps(con: sqlite3.Connection) -> set:
     """Every tap name the vector index currently holds chunks for."""
     try:

{boost_skill_cli-1.0.332 → boost_skill_cli-1.0.334}/boost_cli/core/rag.py

@@ -219,17 +219,33 @@ def _make_docs(entries: List[dict], tap_paths: Dict[str, Path]) -> List[dict]:
 
 
 def _postings_to_doc_tf(raw: dict) -> Dict[int, Dict[str, int]]:
-    """Invert persisted postings back to per-doc term frequencies."""
+    """Invert persisted postings back to per-doc term frequencies.
+
+    Pure: it inverts whatever ``raw`` carries and reads nothing. An earlier
+    version fell back to the SQLite store with ``or``, which made a caller
+    passing ``{}`` silently receive tens of thousands of postings from the live
+    index — invisible in CI, where no store exists, and wrong everywhere else.
+    Callers that need the store now say so; see :func:`_kept_docs`.
+    """
     doc_tf: Dict[int, Dict[str, int]] = defaultdict(dict)
-    for term, plist in (raw.get("postings") or _all_postings()).items():
+    for term, plist in (raw.get("postings") or {}).items():
         for doc_id, tf in plist:
             doc_tf[doc_id][term] = tf
     return doc_tf
 
 
 def _kept_docs(raw: dict, keep_safe: set) -> List[dict]:
-    """Recover cached docs (with term freqs) for taps that did not change."""
-    doc_tf = _postings_to_doc_tf(raw)
+    """Recover cached docs (with term freqs) for taps that did not change.
+
+    Term frequencies live in the SQLite postings store since they left the JSON
+    index, so an index without an inline ``postings`` key is normal rather than
+    empty — this is the caller that reaches for the store, explicitly.
+    """
+    # Key ABSENCE, not falsiness: an index carrying an explicit empty
+    # `postings` is stating it has none, and must not be answered from the
+    # store. Only an index with no such key predates the SQLite move.
+    doc_tf = _postings_to_doc_tf(
+        raw if "postings" in raw else {"postings": _all_postings()})
     return [{**meta, "tf": doc_tf.get(doc_id, {})}
             for doc_id, meta in enumerate(raw.get("docs", []))
             if meta["t"].replace("/", "__") in keep_safe]

{boost_skill_cli-1.0.332 → boost_skill_cli-1.0.334/boost_skill_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.332
+Version: 1.0.334
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.332 → boost_skill_cli-1.0.334}/boost_skill_cli.egg-info/SOURCES.txt

@@ -489,6 +489,7 @@ tests/unit/test_dedup_trust.py
 tests/unit/test_dense.py
 tests/unit/test_dense_fallback.py
 tests/unit/test_dense_fix_hint.py
+tests/unit/test_dense_shards.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.332 → boost_skill_cli-1.0.334}/docs/commands.html

@@ -117,7 +117,7 @@
     <div class="group" data-group="find">
       <div class="group-h">Find &amp; search</div>
       <a class="cmd-link" href="#cmd-search" data-search="search search skills across tap registries (ai-ranked)  --smart --limit limit --json query">search</a>
-      <a class="cmd-link" href="#cmd-reindex" data-search="reindex build/refresh the full-content search index build or refresh the full-content search index --force --dense --json">reindex</a>
+      <a class="cmd-link" href="#cmd-reindex" data-search="reindex build/refresh the full-content search index build or refresh the full-content search index --force --dense --export-shard tap --import-shard file --json">reindex</a>
       <a class="cmd-link" href="#cmd-discover" data-search="discover browse &amp; search the github-wide skill discovery index  --limit limit --json query">discover</a>
       <a class="cmd-link" href="#cmd-recommend" data-search="recommend suggest skills based on your project&#x27;s tech stack  --path path --limit limit --json">recommend</a>
       <a class="cmd-link" href="#cmd-browse" data-search="browse interactive full-screen tui with fuzzy search ">browse</a>
@@ -413,15 +413,17 @@
           <div class="arg"><code>--json</code><span>machine-readable output</span></div>
         </div>
       </section>
-      <section class="cmd" id="cmd-reindex" data-search="reindex build/refresh the full-content search index build or refresh the full-content search index --force --dense --json">
+      <section class="cmd" id="cmd-reindex" data-search="reindex build/refresh the full-content search index build or refresh the full-content search index --force --dense --export-shard tap --import-shard file --json">
         <h3><span class="cname">reindex</span><span class="gtag">find</span></h3>
         <p class="summary">Build/refresh the full-content search index</p>
-        <pre class="syn">boost reindex [--force] [--dense] [--json]</pre>
+        <pre class="syn">boost reindex [--force] [--dense] [--export-shard TAP] [--import-shard FILE] [--json]</pre>
         <p class="desc">Build or refresh the full-content search index</p>
         <div class="args-h">Options</div>
         <div class="args">
           <div class="arg"><code>--force</code><span>reindex every tap, ignoring cached commits</span></div>
-          <div class="arg"><code>--dense</code><span>also embed chunks into the opt-in dense vector store (needs the `rag` extra and an embeddings API key)</span></div>
+          <div class="arg"><code>--dense</code><span>also embed chunks into the opt-in dense vector store (needs the `rag` extra; no API key required)</span></div>
+          <div class="arg"><code>--export-shard TAP</code><span>write TAP&#x27;s prebuilt vectors to stdout as JSON, for publishing so others need not re-embed them</span></div>
+          <div class="arg"><code>--import-shard FILE</code><span>merge a prebuilt vector shard, skipping the embed cost; refused unless it matches this store&#x27;s backend and the tap&#x27;s current commit</span></div>
           <div class="arg"><code>--json</code><span>machine-readable output</span></div>
         </div>
       </section>

{boost_skill_cli-1.0.332 → boost_skill_cli-1.0.334}/docs/roadmap/items/a11y-sweep-flakes-on-color-contrast.md

@@ -60,3 +60,31 @@ runs fine locally (<code>npm ci</code> with <code>npm_config_cache</code> redire
 single-instance app: launching the bundle binary attaches to the running instance instead of starting
 an isolated one. Nothing to fix in the harness &mdash; it is why the reproduction loop belongs on a
 Linux runner (or against Chrome for Testing), not on a developer laptop with Chrome open.
+
+<b>Cause found &mdash; and my earlier &ldquo;maybe axe is right about the contrast&rdquo; caveat was
+wrong.</b> It is a harness defect, and the harness predicted it in a comment.
+
+<code>a11y_check.mjs</code> loads each page over <code>file://</code> and passes
+<code>--allow-file-access-from-files</code>, with this note: &ldquo;without this Chrome treats each
+file as its own opaque origin and the stylesheet never applies, <em>which would make every contrast
+result meaningless</em>.&rdquo; That is exactly what happens intermittently. Every failing element
+resolves its colour from <code>var(--text-3)</code>, defined once in
+<code>style/boost.css</code> and linked <em>relatively</em> (<code>../style/boost.css</code>).
+
+The arithmetic settles it. The shipped token is <code>#767c96</code>, which is
+<b>4.85:1 on <code>#07080f</code> &mdash; passing AA</b>, and it was already raised once from
+<code>#676d86</code> (3.9:1) by <code>#243</code>. The colours axe reported &mdash;
+<code>#505467</code> on <code>roadmap.html</code>, <code>#656a81</code> on <code>mcp-hub.html</code>
+&mdash; <b>appear nowhere in this repository</b>. They are Chrome's unstyled fallbacks. So both
+&ldquo;contrast failures&rdquo; were the same defect: the stylesheet silently not applying.
+
+<b>The fix is therefore not a colour and not a settle delay.</b> Both would be treating a symptom.
+The real options are to stop depending on a flag that intermittently fails &mdash; serve the docs
+over a throwaway <code>http://</code> origin for the sweep, or inline the stylesheet into a temporary
+copy &mdash; and, more importantly, to <b>fail loudly when it happens</b>: assert that a known token
+resolves before running axe at all, so an unstyled page reports &ldquo;stylesheet did not load&rdquo;
+rather than twenty plausible-looking contrast violations against colours that do not exist.
+
+That guard matters more than the flake. Without it the sweep produces confident, specific,
+<em>entirely wrong</em> findings &mdash; which is what sent me to check a token that had been correct
+for months.

{boost_skill_cli-1.0.332 → boost_skill_cli-1.0.334}/docs/roadmap/items/keyless-semantic-search-for-everyone.md

@@ -306,3 +306,28 @@ deltas.
 <b>Claim released.</b> Steps 1, 4 and 6 have shipped; steps 2, 3 and 5 are unowned and open. Step 2
 is the one to take next and it is better justified than when it was written: embedding measured at
 ~1.2 s/chunk locally, so prebuilt per-registry shards are a requirement rather than an optimisation.
+
+<b>Step 2, the shard mechanism, is shipped.</b> <code>boost reindex --export-shard TAP</code> writes
+one registry's vectors as JSON; <code>--import-shard FILE</code> merges them. Measured end to end on
+the real store: exporting <code>anthropics/skills</code> gives <b>262 chunks in 0.63 MB</b>, and
+importing it into a fresh <code>BOOST_HOME</code> takes <b>0.12 s</b> against roughly five minutes to
+embed the same rows locally. That ratio is the whole point of the step.
+
+<b>Import refuses rather than degrades.</b> A shard carries the provider, model, dimension and the
+registry commit it was built from, and all four are checked. Mixing vectors from a different
+embedding space would not raise &mdash; it would quietly return nonsense rankings, which is worse
+than failing &mdash; and accepting a shard from a stale commit would let <code>build()</code> mark
+that tap &ldquo;reused&rdquo; and never re-embed it, pinning the user to old vectors indefinitely.
+Verified: a shard with a doctored commit is rejected with a message naming both hashes.
+
+<b>What this does NOT remove: the query-side model download.</b> A shard eliminates the
+<em>document</em> embedding cost, but a keyless user still needs the ~133&nbsp;MB local model to embed
+their own <em>query</em>. Confirmed by importing into a fresh <code>BOOST_HOME</code>, where retrieval
+returned zero hits until the model was present &mdash; <code>dense.status()</code> reported
+<code>ready</code> the whole time, because the store genuinely was ready. The card's framing of
+&ldquo;the only API-bound step is turning text into vectors&rdquo; is right, but that step runs on
+both sides, and only the document half can be shipped ahead of time.
+
+<b>Still open in step 2:</b> the CI workflow that publishes shards as release artifacts, and the
+<code>boost tap</code> integration that fetches one automatically. Both are now plumbing on top of a
+verified mechanism rather than open questions. Steps 3 and 5 are untouched.

{boost_skill_cli-1.0.332 → boost_skill_cli-1.0.334}/docs/roadmap.html

@@ -893,7 +893,32 @@ deltas.
 
 <b>Claim released.</b> Steps 1, 4 and 6 have shipped; steps 2, 3 and 5 are unowned and open. Step 2
 is the one to take next and it is better justified than when it was written: embedding measured at
-~1.2 s/chunk locally, so prebuilt per-registry shards are a requirement rather than an optimisation.</p>
+~1.2 s/chunk locally, so prebuilt per-registry shards are a requirement rather than an optimisation.
+
+<b>Step 2, the shard mechanism, is shipped.</b> <code>boost reindex --export-shard TAP</code> writes
+one registry's vectors as JSON; <code>--import-shard FILE</code> merges them. Measured end to end on
+the real store: exporting <code>anthropics/skills</code> gives <b>262 chunks in 0.63 MB</b>, and
+importing it into a fresh <code>BOOST_HOME</code> takes <b>0.12 s</b> against roughly five minutes to
+embed the same rows locally. That ratio is the whole point of the step.
+
+<b>Import refuses rather than degrades.</b> A shard carries the provider, model, dimension and the
+registry commit it was built from, and all four are checked. Mixing vectors from a different
+embedding space would not raise &mdash; it would quietly return nonsense rankings, which is worse
+than failing &mdash; and accepting a shard from a stale commit would let <code>build()</code> mark
+that tap &ldquo;reused&rdquo; and never re-embed it, pinning the user to old vectors indefinitely.
+Verified: a shard with a doctored commit is rejected with a message naming both hashes.
+
+<b>What this does NOT remove: the query-side model download.</b> A shard eliminates the
+<em>document</em> embedding cost, but a keyless user still needs the ~133&nbsp;MB local model to embed
+their own <em>query</em>. Confirmed by importing into a fresh <code>BOOST_HOME</code>, where retrieval
+returned zero hits until the model was present &mdash; <code>dense.status()</code> reported
+<code>ready</code> the whole time, because the store genuinely was ready. The card's framing of
+&ldquo;the only API-bound step is turning text into vectors&rdquo; is right, but that step runs on
+both sides, and only the document half can be shipped ahead of time.
+
+<b>Still open in step 2:</b> the CI workflow that publishes shards as release artifacts, and the
+<code>boost tap</code> integration that fetches one automatically. Both are now plumbing on top of a
+verified mechanism rather than open questions. Steps 3 and 5 are untouched.</p>
         <div class="meta">
           <span class="m">Complexity <b>L</b></span>
           <span class="m hi">Impact <b>High</b></span>
@@ -1936,7 +1961,35 @@ runs fine locally (<code>npm ci</code> with <code>npm_config_cache</code> redire
 <em>newly created</em> <code>userDataDir</code> each time, because Chrome on macOS is a
 single-instance app: launching the bundle binary attaches to the running instance instead of starting
 an isolated one. Nothing to fix in the harness &mdash; it is why the reproduction loop belongs on a
-Linux runner (or against Chrome for Testing), not on a developer laptop with Chrome open.</p>
+Linux runner (or against Chrome for Testing), not on a developer laptop with Chrome open.
+
+<b>Cause found &mdash; and my earlier &ldquo;maybe axe is right about the contrast&rdquo; caveat was
+wrong.</b> It is a harness defect, and the harness predicted it in a comment.
+
+<code>a11y_check.mjs</code> loads each page over <code>file://</code> and passes
+<code>--allow-file-access-from-files</code>, with this note: &ldquo;without this Chrome treats each
+file as its own opaque origin and the stylesheet never applies, <em>which would make every contrast
+result meaningless</em>.&rdquo; That is exactly what happens intermittently. Every failing element
+resolves its colour from <code>var(--text-3)</code>, defined once in
+<code>style/boost.css</code> and linked <em>relatively</em> (<code>../style/boost.css</code>).
+
+The arithmetic settles it. The shipped token is <code>#767c96</code>, which is
+<b>4.85:1 on <code>#07080f</code> &mdash; passing AA</b>, and it was already raised once from
+<code>#676d86</code> (3.9:1) by <code>#243</code>. The colours axe reported &mdash;
+<code>#505467</code> on <code>roadmap.html</code>, <code>#656a81</code> on <code>mcp-hub.html</code>
+&mdash; <b>appear nowhere in this repository</b>. They are Chrome's unstyled fallbacks. So both
+&ldquo;contrast failures&rdquo; were the same defect: the stylesheet silently not applying.
+
+<b>The fix is therefore not a colour and not a settle delay.</b> Both would be treating a symptom.
+The real options are to stop depending on a flag that intermittently fails &mdash; serve the docs
+over a throwaway <code>http://</code> origin for the sweep, or inline the stylesheet into a temporary
+copy &mdash; and, more importantly, to <b>fail loudly when it happens</b>: assert that a known token
+resolves before running axe at all, so an unstyled page reports &ldquo;stylesheet did not load&rdquo;
+rather than twenty plausible-looking contrast violations against colours that do not exist.
+
+That guard matters more than the flake. Without it the sweep produces confident, specific,
+<em>entirely wrong</em> findings &mdash; which is what sent me to check a token that had been correct
+for months.</p>
         <div class="meta">
           <span class="m">Complexity <b>S</b></span>
           <span class="m">Impact <b>Med</b></span>

{boost_skill_cli-1.0.332 → boost_skill_cli-1.0.334}/tests/functional/test_cli_discovery.py

@@ -1226,3 +1226,63 @@ class TestSearchSemanticHint:
         boost("reindex")
         r = boost("search", "brainstorming")
         assert "semantic search is off" not in r.out
+
+
+class TestReindexShards:
+    """`--export-shard` / `--import-shard`, the user-facing half of shards.
+
+    The engine is covered in tests/unit/test_dense_shards.py; this pins the CLI
+    contract — exit codes, JSON on stdout, and that a refused shard reports why
+    rather than half-importing.
+    """
+
+    def test_exporting_a_tap_with_no_vectors_fails_with_a_hint(self, boost,
+                                                               tapped):
+        r = boost("reindex", "--export-shard", "acme/skills", expect=1)
+        assert "no vectors" in r.err
+        assert "reindex --dense" in r.err        # names the one next action
+
+    def test_export_writes_json_to_stdout(self, boost, tapped, monkeypatch):
+        from boost_cli.core import dense
+        monkeypatch.setattr(dense, "export_shard", lambda tap: {
+            "tap": tap, "commit": "c1", "provider": "local", "model": "bge",
+            "dim": 3, "chunks": [{"name": "a", "tap": tap, "path": "a/SKILL.md",
+                                  "kind": "skill", "cix": 0, "snip": "s",
+                                  "embedding": "AAAA"}]})
+        r = boost("reindex", "--export-shard", "acme/skills")
+        payload = json.loads(r.out)              # must be parseable, not pretty
+        assert payload["tap"] == "acme/skills"
+        assert len(payload["chunks"]) == 1
+
+    def test_importing_a_missing_file_is_an_error(self, boost, tapped, tmp_path):
+        r = boost("reindex", "--import-shard", str(tmp_path / "nope.json"),
+                  expect=1)
+        assert "cannot read shard" in r.err
+
+    def test_importing_malformed_json_is_an_error(self, boost, tapped, tmp_path):
+        bad = tmp_path / "bad.json"
+        bad.write_text("{not json", encoding="utf-8")
+        r = boost("reindex", "--import-shard", str(bad), expect=1)
+        assert "cannot read shard" in r.err
+
+    def test_a_refused_shard_reports_the_reason(self, boost, tapped, tmp_path,
+                                                monkeypatch):
+        from boost_cli.core import dense
+        monkeypatch.setattr(dense, "import_shard",
+                            lambda shard, commit: (False, "dim mismatch"))
+        f = tmp_path / "s.json"
+        f.write_text(json.dumps({"tap": "acme/skills"}), encoding="utf-8")
+        r = boost("reindex", "--import-shard", str(f), expect=1)
+        assert "dim mismatch" in r.err
+        assert "reindex --dense" in r.err        # the fallback that always works
+
+    def test_a_good_shard_reports_what_landed(self, boost, tapped, tmp_path,
+                                              monkeypatch):
+        from boost_cli.core import dense
+        monkeypatch.setattr(dense, "import_shard",
+                            lambda shard, commit: (True, "imported 7 chunks"))
+        f = tmp_path / "s.json"
+        f.write_text(json.dumps({"tap": "acme/skills"}), encoding="utf-8")
+        r = boost("reindex", "--import-shard", str(f))
+        assert "imported 7 chunks" in r.out
+        assert "acme/skills" in r.out