boost-skill-cli 1.2.59__tar.gz → 1.2.61__tar.gz

{boost_skill_cli-1.2.59 → boost_skill_cli-1.2.61}/.vale/styles/config/vocabularies/boost/accept.txt

@@ -34,6 +34,8 @@ config
 configs
 CPython
 CRM
+cron
+crontab
 cyclomatic
 Dependabot
 deps

{boost_skill_cli-1.2.59 → boost_skill_cli-1.2.61}/CLAUDE.md

@@ -543,6 +543,41 @@ each agent's skills dir, and updating the lock file.
   by another key-holder; `scripts/publish_shards.py manifest` refuses to
   describe two spaces in one file.
 
+- **`sync` and `ingest` differ in which side is authoritative, and only one of
+  them survives a republish.** `shards.sync` takes this machine's commits as
+  given and asks whether a published shard happens to match — right on setup
+  day, wrong a week later, because the weekly run republishes against whatever
+  the registries moved to. So for most taps the answer becomes "no", and the
+  user is told their vectors are stale with no way to act on it but hours of
+  local CPU: `boost update` chases branch HEAD and `--force` chases it while
+  dropping the pin, neither of which can land on a commit a manifest names.
+  `shards.ingest` reads the manifest as the **target**: a row for a tap held at
+  another commit is a reason to move the tap (`registry.retarget` — checkout
+  then pin, never the reverse), and `boost update --shards` is the surface. Two
+  invariants are load-bearing. **Download and verify before moving**: a move
+  followed by a failed download leaves vectors stale but present, the failure
+  that looks like nothing at all — `retarget` is injected so the ordering is
+  testable without a git remote. **Skip on `built`, not on `commits`**:
+  `dense.tap_commits()` says which commit the *vectors* were built at, and a tap
+  matching on both is skipped without a download, which is the whole reason a
+  weekly cron line costs one manifest fetch. A registry that dropped out of the
+  manifest is left pinned where it sits — falling back to HEAD would invent a
+  target no published vectors describe. And a tap that moves invalidates more
+  than vectors: its catalog cache and the BM25 index name entries from the old
+  tree, so `catalog.rebuild_tap` and `rag.build` run for anything that moved.
+
+- **Search reads two mtimes and makes zero network calls, and cheapness is not
+  the argument.** The manifest is ~170 KB, so an inline check would be
+  affordable; acting on its answer means moving taps and downloading hundreds of
+  megabytes, which cannot happen inside a sub-second search. So the most an
+  inline check could ever produce is the one line `_hint_stale_shards` already
+  prints for one `stat` — at the price of a round trip per query and
+  unannounced egress. `paths.shard_sync_marker()` lives under `state/`, not
+  `cache/`, because `boost clean` sweeps `cache/*.json` and would delete it,
+  after which search would nag about vectors refreshed that morning. The shard
+  hint suppresses the tap-age hint when it fires: its remedy moves the taps too,
+  and two staleness lines under one result set is how a hint becomes noise.
+
 **Search has two engines**, both in `core/`: `rag.py` is the always-on,
 zero-dependency BM25 engine (full-content index, auto-builds on first
 search — this is what the required `eval` gate floors at recall@k ≥ 0.78).

{boost_skill_cli-1.2.59/boost_skill_cli.egg-info → boost_skill_cli-1.2.61}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.59
+Version: 1.2.61
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0
@@ -197,14 +197,34 @@ for every one that has a published shard.
 Already tapped? `boost reindex --fetch-shards` does the download half alone,
 and `boost reindex --dense` embeds locally whatever has no published shard.
 
+Vectors are republished weekly, and `boost update --shards` is the ingestion
+side of that. It reads the manifest as the *target* state: each tap is moved
+onto the commit its published vectors were built from, those vectors are
+imported, and the keyword index is rebuilt for anything that moved. A tap
+already sitting at the published commit with those vectors already built is
+skipped without downloading anything, so in a week where a registry did not
+move the command does nothing at all — which is what makes it safe to schedule:
+
+```bash
+# refresh prebuilt vectors every Monday at 09:00 — crontab -e
+0 9 * * 1 /full/path/to/boost update --shards >> ~/.boost/logs/shards.log 2>&1
+```
+
+Plain `boost update` moves each tap to its branch head; `--shards` moves each
+tap to the commit the published vectors describe. Two different targets, so
+they are separate modes rather than one pass, and `--shards --taps-only` is
+refused rather than silently picking one.
+
 Because vectors are keyed to a registry's commit, `quickstart` **pins** each tap
 it fetches vectors for, and `boost update` skips a pinned tap rather than moving
 it out from under them (`--force` moves it anyway and drops the pin). When a tap
 does move, boost checks whether a newer shard exists for the new commit and
 imports it; if none does, it says so instead of leaving stale vectors looking
-fresh. `boost search` never refreshes taps behind your back — it prints one line
-when they are more than two weeks old and leaves the fetching to
-`boost update --taps-only`.
+fresh. `boost search` never refreshes taps behind your back, and never checks
+the manifest either — acting on that answer means moving taps and downloading
+hundreds of megabytes, which cannot happen inside a sub-second search. It prints
+one line when the taps or the prebuilt vectors are more than two weeks old and
+leaves the fetching to `boost update --taps-only` or `boost update --shards`.
 Every download is checked against the sha256 in the manifest and refused on a
 mismatch, and shards for a registry that has moved since publication are
 refused rather than merged — stale vectors would otherwise look fresh forever.

{boost_skill_cli-1.2.59 → boost_skill_cli-1.2.61}/README.md

@@ -155,14 +155,34 @@ for every one that has a published shard.
 Already tapped? `boost reindex --fetch-shards` does the download half alone,
 and `boost reindex --dense` embeds locally whatever has no published shard.
 
+Vectors are republished weekly, and `boost update --shards` is the ingestion
+side of that. It reads the manifest as the *target* state: each tap is moved
+onto the commit its published vectors were built from, those vectors are
+imported, and the keyword index is rebuilt for anything that moved. A tap
+already sitting at the published commit with those vectors already built is
+skipped without downloading anything, so in a week where a registry did not
+move the command does nothing at all — which is what makes it safe to schedule:
+
+```bash
+# refresh prebuilt vectors every Monday at 09:00 — crontab -e
+0 9 * * 1 /full/path/to/boost update --shards >> ~/.boost/logs/shards.log 2>&1
+```
+
+Plain `boost update` moves each tap to its branch head; `--shards` moves each
+tap to the commit the published vectors describe. Two different targets, so
+they are separate modes rather than one pass, and `--shards --taps-only` is
+refused rather than silently picking one.
+
 Because vectors are keyed to a registry's commit, `quickstart` **pins** each tap
 it fetches vectors for, and `boost update` skips a pinned tap rather than moving
 it out from under them (`--force` moves it anyway and drops the pin). When a tap
 does move, boost checks whether a newer shard exists for the new commit and
 imports it; if none does, it says so instead of leaving stale vectors looking
-fresh. `boost search` never refreshes taps behind your back — it prints one line
-when they are more than two weeks old and leaves the fetching to
-`boost update --taps-only`.
+fresh. `boost search` never refreshes taps behind your back, and never checks
+the manifest either — acting on that answer means moving taps and downloading
+hundreds of megabytes, which cannot happen inside a sub-second search. It prints
+one line when the taps or the prebuilt vectors are more than two weeks old and
+leaves the fetching to `boost update --taps-only` or `boost update --shards`.
 Every download is checked against the sha256 in the manifest and refused on a
 mismatch, and shards for a registry that has moved since publication are
 refused rather than merged — stale vectors would otherwise look fresh forever.

{boost_skill_cli-1.2.59 → boost_skill_cli-1.2.61}/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.59'
-__version_tuple__ = version_tuple = (1, 2, 59)
+__version__ = version = '1.2.61'
+__version_tuple__ = version_tuple = (1, 2, 61)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.59 → boost_skill_cli-1.2.61}/boost_cli/commands/discovery.py

@@ -218,6 +218,8 @@ def _hint_stale_taps() -> None:
     price of one stat, and a machine that has never refreshed says nothing at
     all rather than inventing an age.
     """
+    if _hint_stale_shards():
+        return
     age = registry.refresh_age_days()
     if age is None or age < registry.STALE_TAPS_DAYS:
         return
@@ -226,6 +228,37 @@ def _hint_stale_taps() -> None:
         % int(age), "muted"))
 
 
+def _hint_stale_shards() -> bool:
+    """Mention un-ingested published vectors. One `stat`, and never a network call.
+
+    The published manifest is ~170 KB, so checking it inline would be cheap —
+    and cheapness is not the argument. Acting on the answer means moving taps
+    and downloading hundreds of megabytes, which cannot happen inside a
+    sub-second search, so the most an inline check could ever produce is this
+    one line: the same line, for the price of a network round trip on every
+    query and unannounced egress at that. The marker's mtime answers it for
+    free, and a machine that has never ingested a shard says nothing rather
+    than inventing an age.
+
+    Returns True when it printed, so the tap-age hint stays quiet. The remedy
+    named here moves the taps as well, and two staleness lines under one set of
+    results is how a hint turns into noise.
+    """
+    from ..core import shards
+    age = shards.sync_age_days()
+    if age is None or age < shards.STALE_SHARDS_DAYS:
+        return False
+    from ..core import dense
+    if not dense.status().get("ready"):
+        # Vectors that are not serving queries cannot be stale in a way the
+        # user can act on; `_hint_semantic_search` owns that conversation.
+        return False
+    out.info(out.role(
+        "prebuilt vectors last refreshed %d days ago — `boost update --shards`"
+        % int(age), "muted"))
+    return True
+
+
 def _hint_semantic_search(engine: str) -> None:
     """Say that a better engine exists, when BM25 answered alone.
 
@@ -315,8 +348,12 @@ def _fetch_shards(args) -> int:
                         hint=dense.fix_hint(dense.status().get("reason", "")))
     commits = rag._tap_commits()
     by_name = {t.name: commits.get(t.safe_name, "") for t in registry.list_taps()}
-    results = shards.sync(list(by_name), by_name, manifest=manifest,
-                          on_event=_shard_event)
+    results = shards.sync(
+        list(by_name), by_name, manifest=manifest,
+        # Progress goes to stdout, and so does the JSON: emitting both left
+        # `--json` printing "fetching ..." lines ahead of the document, which
+        # no parser can read past.
+        on_event=None if args.as_json else _shard_event)
     if args.as_json:
         print(json.dumps({"shards": results}, indent=2))
         return 0
@@ -335,6 +372,12 @@ def _fetch_shards(args) -> int:
         out.info(out.role("%d tap(s) without usable vectors: %s"
                           % (len(missing), ", ".join(missing[:5])
                              + (" …" if len(missing) > 5 else "")), "muted"))
+        if any(r["status"] == "refused" for r in results):
+            # A refusal here is almost always "the tap has moved past the
+            # commit these vectors describe", which local embedding is the
+            # expensive answer to and `--shards` is the cheap one: it moves the
+            # tap back onto a published commit instead.
+            out.info("taps that moved past their vectors: `boost update --shards`")
         out.info("embed those locally with `boost reindex --dense`")
     return 0
 

{boost_skill_cli-1.2.59 → boost_skill_cli-1.2.61}/boost_cli/commands/pkg.py

@@ -16,7 +16,7 @@ from datetime import UTC, datetime
 from itertools import chain
 from pathlib import Path
 
-from .. import cliparse
+from .. import cliparse, spin
 from ..core import (
     adapters,
     agents,
@@ -878,6 +878,103 @@ def _resync_vectors(moved: list[str]) -> None:
                           "`boost reindex --dense`" % left, "muted"))
 
 
+def _ingest_event(tap: str, status: str, detail: str) -> None:
+    """Progress for one tap, quiet enough to run over four hundred of them."""
+    if status == "downloading":
+        out.info(out.role("fetching %s %s" % (tap, detail), "muted"))
+    elif status == "moving":
+        out.info(out.role("moving %s to %s" % (tap, detail), "muted"))
+    elif status == "failed":
+        out.info(out.role("%s: failed%s"
+                          % (tap, " (%s)" % detail if detail else ""), "muted"))
+
+
+def _ingest_shards(args) -> int:
+    """`boost update --shards`: refresh vectors from the published manifest.
+
+    Its own mode rather than a step of the normal update, because the two move
+    taps toward different targets: a plain `boost update` moves each tap to its
+    branch HEAD, and this moves each tap to the commit the published vectors
+    were built from. Running both in one pass would move every tap twice and
+    leave the second answer standing, so the flag replaces the update rather
+    than extending it.
+
+    This is the ingestion path for the weekly shard run. It is a no-op on a
+    machine that already holds this week's vectors, which is what makes it
+    safe to put in a cron line — see the docs.
+    """
+    from ..core import dense, shards
+    taps = registry.list_taps()
+    if not taps:
+        raise BoostError("no taps configured — nothing to refresh",
+                         hint="`boost quickstart` taps the starters and loads "
+                              "their vectors in one pass")
+    manifest = shards.fetch_manifest()
+    why = shards.incompatible(manifest)
+    if why:
+        raise BoostError("published shards cannot serve this machine — %s" % why,
+                         hint=dense.fix_hint(dense.status().get("reason", "")))
+    commits = rag._tap_commits()
+    stored = dense.tap_commits()
+    # Both maps are keyed by tap name; the two sources are keyed by safe name.
+    by_name = {t.name: commits.get(t.safe_name, "") for t in taps}
+    built = {t.name: stored.get(t.safe_name, "") for t in taps}
+    results = shards.ingest(
+        list(by_name), by_name, built=built, manifest=manifest,
+        # Progress goes to stdout, which is where the JSON goes: under `--json`
+        # the two would interleave into something no parser can read.
+        on_event=None if args.as_json else _ingest_event)
+
+    imported = [r for r in results if r["status"] == "imported"]
+    current = [r for r in results if r["status"] == "current"]
+    failed = [r for r in results if r["status"] == "failed"]
+    moved = [r["tap"] for r in results if r.get("moved")]
+    # Before the output branch, never inside it: a tap that moved is describing
+    # a different tree, so its catalog cache and the keyword index both name
+    # entries that may no longer exist. Vectors are not the only thing a commit
+    # is load-bearing for, and a `--json` caller is owed the same repair.
+    for name in moved:
+        catalog.rebuild_tap(registry.get(name))
+    if moved:
+        # Spinners write to stderr, so this is safe under `--json`.
+        with spin.Spinner("rebuilding the keyword index"):
+            rag.build()
+        complete.refresh_names()
+    journal.log("update", "--shards")
+    # Nothing landed and nothing was already current: the manifest and this
+    # machine have nothing to say to each other, which a cron line should
+    # notice rather than read as a quiet success.
+    rc = 1 if failed and not imported and not current else 0
+    if args.as_json:
+        print(json.dumps({"shards": results}, indent=2))
+        return rc
+
+    if imported:
+        total = sum(int(r.get("chunks") or 0) for r in imported)
+        out.ok("imported %s (%s chunk%s)%s"
+               % (_plural(len(imported), "shard"), format(total, ","),
+                  "" if total == 1 else "s",
+                  ", %d moved to a newer commit" % len(moved) if moved else ""))
+    if current:
+        out.info(out.role("%s already at the published commit"
+                          % _plural(len(current), "tap"), "muted"))
+    if not imported and not current:
+        # Never a tick. Nothing landed, and "imported 0" with a tick reads as a
+        # job well done to the one user who most needs to know otherwise.
+        out.warn("no published vectors matched your taps")
+    unpublished = [r["tap"] for r in results if r["status"] == "unpublished"]
+    if unpublished:
+        out.info(out.role(
+            "%s not in the manifest, left where they are: %s"
+            % (_plural(len(unpublished), "tap"), ", ".join(unpublished[:5])
+               + (" …" if len(unpublished) > 5 else "")), "muted"))
+    for r in failed:
+        out.warn("%s: %s" % (r["tap"], r.get("detail") or "failed"))
+    if failed:
+        out.info("embed those locally with `boost reindex --dense`")
+    return rc
+
+
 def cmd_update(argv: list[str]) -> int:
     ap = cliparse.parser(prog="boost update",
                                  description="Sync taps or update installed skills")
@@ -894,7 +991,16 @@ def cmd_update(argv: list[str]) -> int:
                     help="skip the confirmation prompt")
     ap.add_argument("--force", action="store_true",
                     help="move pinned taps too, clearing their pin")
+    ap.add_argument("--shards", action="store_true",
+                    help="refresh prebuilt vectors from the published "
+                         "manifest, moving taps to the commits it names")
+    ap.add_argument("--json", dest="as_json", action="store_true",
+                    help="with --shards: print the per-tap result as JSON")
     args = ap.parse_args(argv)
+    if args.shards:
+        if args.taps_only:
+            ap.error("--shards and --taps-only move taps to different commits")
+        return _ingest_shards(args)
     results, failures = registry.update(args.tap or None, force=args.force)
     if not results and not failures:
         out.info("no taps configured — start with `boost tap --defaults`")

{boost_skill_cli-1.2.59 → boost_skill_cli-1.2.61}/boost_cli/core/dense.py

@@ -289,6 +289,25 @@ def _recorded_meta(*, count: bool = False) -> dict:
         con.close()
 
 
+def tap_commits() -> dict[str, str]:
+    """Which registry commit this store holds vectors for, per tap safe-name.
+
+    The store already records this — ``build`` writes it and ``import_shard``
+    updates it — but only as a private meta field, so every caller that wanted
+    to ask "are these vectors for the commit I have?" had to re-open the
+    database. That question is the whole basis of skipping work: a weekly shard
+    refresh is a no-op exactly when the answer is yes, and without an accessor
+    the refresh would download and re-import a store's own rows every week.
+
+    Read without sqlite-vec (see :func:`_recorded_meta`) so a machine that lost
+    the extra still gets a truthful answer rather than an empty one.
+    """
+    commits = _recorded_meta().get("commits")
+    if not isinstance(commits, dict):
+        return {}
+    return {str(k): str(v) for k, v in commits.items() if v}
+
+
 # Why dense retrieval isn't serving, keyed by the `reason` status() returns.
 # Each names the ONE next action; the reason order in status() guarantees only
 # the first missing link is ever reported, so these never chain.

{boost_skill_cli-1.2.59 → boost_skill_cli-1.2.61}/boost_cli/core/paths.py

@@ -113,6 +113,18 @@ def tap_refresh_marker() -> Path:
     return state_dir() / "last-tap-refresh"
 
 
+def shard_sync_marker() -> Path:
+    """File whose mtime records when published vectors were last ingested.
+
+    Deliberately beside the tap marker and NOT under ``cache/``: `boost clean`
+    sweeps `cache/*.json` whose stem is not a tap, and a marker there would be
+    deleted on every clean — after which search would nag about vectors that
+    were refreshed this morning. Same one-`stat` contract as the tap marker,
+    for the same reason: search reads it, and search does no network.
+    """
+    return state_dir() / "last-shard-sync"
+
+
 def snapshots_dir() -> Path:
     """Return the directory for ``snap-*`` store snapshot tarballs."""
     return state_dir() / "snapshots"

{boost_skill_cli-1.2.59 → boost_skill_cli-1.2.61}/boost_cli/core/registry.py

@@ -419,6 +419,27 @@ def unpin(name: str) -> Tap:
     return tap
 
 
+def retarget(name: str, commit: str) -> Tap:
+    """Move an existing tap's clone to `commit` and pin it there.
+
+    The operation a published-vector refresh needs and no other entry point
+    offers. :func:`add` refuses a registry that is already tapped — deliberately
+    — so its ``at=`` pin only ever serves a first tap; :func:`update` moves a tap
+    to its branch HEAD and ``--force`` moves it and drops the pin. None of the
+    three can land on the commit a manifest names, and the chance that HEAD
+    happens to be that commit falls with every push upstream, which is why a
+    week-old install could see its vectors go stale with no way to act on it
+    but re-embedding locally.
+
+    Checkout first, pin second, and never the reverse: a pin recorded for a
+    tree that was not checked out is a lie :func:`update` would then honour by
+    skipping the tap forever.
+    """
+    tap = get(name)
+    gitutil.checkout_commit(tap.path, commit)
+    return pin(name, commit)
+
+
 def remove(name: str) -> Tap:
     """Deregister a tap and delete its clone and cache file.
 

{boost_skill_cli-1.2.59 → boost_skill_cli-1.2.61}/boost_cli/core/shards.py

@@ -34,9 +34,11 @@ from __future__ import annotations
 import hashlib
 import json
 import os
+import time
 import urllib.error
 import urllib.parse
 import urllib.request
+from contextlib import suppress
 from pathlib import Path
 
 from ..errors import BoostError
@@ -328,6 +330,13 @@ def sync(taps: list[str], commits: dict[str, str],
         results.append({"tap": tap, "status": status, "detail": reason,
                         "chunks": int(row.get("chunks") or 0)})
         _emit(on_event, tap, status, reason)
+    if any(r["status"] == "imported" for r in results):
+        # Stamped here as well as in `ingest`, because this is the path a new
+        # machine takes: `boost quickstart` imports through `sync`, so without
+        # this the marker stays unset for exactly the users the staleness hint
+        # is written for, and the one surface that teaches `boost update
+        # --shards` exists would never fire on the onboarding path.
+        mark_synced()
     return results
 
 
@@ -343,3 +352,127 @@ def _size_label(row: dict) -> str:
     if not isinstance(size, int) or size <= 0:
         return ""
     return util.human_size(size)
+
+
+#: How long published vectors may go un-ingested before `boost search` says so.
+#: The publish cadence is weekly, so this is two missed runs — a hint that fires
+#: the morning after every run is one users learn to read past, and the remedy
+#: it names moves taps, which is not a thing to nag anyone into hourly.
+STALE_SHARDS_DAYS = 14
+
+
+def mark_synced() -> None:
+    """Stamp "published vectors were ingested just now"; never fails a run."""
+    with suppress(OSError):
+        paths.ensure_dirs()
+        paths.shard_sync_marker().write_text("", encoding="utf-8")
+
+
+def sync_age_days() -> float | None:
+    """Days since published vectors were last ingested, or None if never.
+
+    None is not zero and not infinity, the same distinction
+    ``registry.refresh_age_days`` draws: a machine that embedded everything
+    locally has never ingested a shard and must not be nagged about the age of
+    something it does not use.
+    """
+    try:
+        age = time.time() - paths.shard_sync_marker().stat().st_mtime
+    except OSError:
+        return None
+    return max(0.0, age / 86400.0)
+
+
+def ingest(taps: list[str], commits: dict[str, str],
+           built: dict[str, str] | None = None, manifest: dict | None = None,
+           cache_dir: Path | None = None, on_event=None,
+           retarget=None) -> list[dict]:
+    """Bring `taps` to the state the published manifest describes.
+
+    WHICH SIDE IS AUTHORITATIVE is the whole difference from :func:`sync`.
+    `sync` takes this machine's commits as given and asks whether a published
+    shard happens to match. That is right on the day a machine is set up, and
+    wrong a week later: the weekly run republishes against whatever the
+    registries have moved to, so for most taps the answer becomes "no", and the
+    user is told their vectors are stale with no way to act on it but hours of
+    local CPU. `ingest` reads the manifest as the *target*: a row for a tap this
+    machine holds at another commit is a reason to move the tap, because the
+    commit was pinned to match the vectors in the first place.
+
+    `built` maps tap name -> the commit this machine's vector store holds for
+    it (``dense.tap_commits``), and it is what makes the weekly case free: a tap
+    already at the row's commit *with vectors already built there* is skipped
+    without downloading anything. Passing only `commits` would re-download a
+    store's own rows every week.
+
+    ORDER IS LOAD-BEARING: download and verify the bytes, and only then move the
+    tap. Moving first and failing the download leaves the clone on a commit
+    whose vectors are stale but still present — the failure that looks like
+    nothing at all, and the one this module exists to refuse. `retarget` is
+    injected so the ordering can be tested without a git remote; it defaults to
+    ``registry.retarget``.
+
+    Never raises for one tap. A registry that dropped out of the manifest is
+    reported "unpublished" and left pinned exactly where it sits — falling back
+    to moving it to HEAD would be inventing a target no vectors describe.
+    """
+    from . import dense
+    manifest = manifest if manifest is not None else fetch_manifest()
+    why = incompatible(manifest)
+    if why:
+        return [{"tap": t, "status": "incompatible", "detail": why,
+                 "moved": False} for t in taps]
+    if retarget is None:
+        from . import registry
+        retarget = registry.retarget
+    index = rows(manifest)
+    cache_dir = cache_dir or (paths.cache_dir() / "shards")
+    built = built or {}
+    results: list[dict] = []
+    for tap in taps:
+        row = index.get(tap)
+        if row is None:
+            results.append({"tap": tap, "status": "unpublished", "moved": False})
+            _emit(on_event, tap, "unpublished", "")
+            continue
+        want = str(row.get("commit") or "")
+        local = commits.get(tap, "")
+        if want and local == want == built.get(tap, ""):
+            results.append({"tap": tap, "status": "current", "moved": False})
+            _emit(on_event, tap, "current", "")
+            continue
+        dest = cache_dir / (tap.replace("/", "__") + ".shard.json")
+        moved = False
+        try:
+            _emit(on_event, tap, "downloading", _size_label(row))
+            download(row, dest, manifest)
+            shard = json.loads(dest.read_text(encoding="utf-8"))
+            if local != want:
+                _emit(on_event, tap, "moving", want[:7])
+                retarget(tap, want)
+                moved = True
+            ok, reason = dense.import_shard(shard, commit=want)
+        except BoostError as exc:
+            results.append({"tap": tap, "status": "failed", "moved": moved,
+                            "detail": exc.message})
+            _emit(on_event, tap, "failed", exc.message)
+            continue
+        except (OSError, json.JSONDecodeError) as exc:
+            results.append({"tap": tap, "status": "failed", "moved": moved,
+                            "detail": str(exc)})
+            _emit(on_event, tap, "failed", str(exc))
+            continue
+        finally:
+            # The shard is a transfer format, not a cache — see `sync`.
+            dest.unlink(missing_ok=True)
+        status = "imported" if ok else "failed"
+        results.append({"tap": tap, "status": status, "detail": reason,
+                        "moved": moved, "chunks": int(row.get("chunks") or 0)})
+        _emit(on_event, tap, status, reason)
+    if any(r["status"] in ("imported", "current") for r in results):
+        # Stamped for "the manifest was read and acted on", not for "something
+        # changed": a run where every tap was already current is the successful
+        # weekly case, and leaving the marker cold would make search nag about
+        # vectors refreshed this morning.
+        mark_synced()
+    return results

{boost_skill_cli-1.2.59 → boost_skill_cli-1.2.61/boost_skill_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.59
+Version: 1.2.61
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0
@@ -197,14 +197,34 @@ for every one that has a published shard.
 Already tapped? `boost reindex --fetch-shards` does the download half alone,
 and `boost reindex --dense` embeds locally whatever has no published shard.
 
+Vectors are republished weekly, and `boost update --shards` is the ingestion
+side of that. It reads the manifest as the *target* state: each tap is moved
+onto the commit its published vectors were built from, those vectors are
+imported, and the keyword index is rebuilt for anything that moved. A tap
+already sitting at the published commit with those vectors already built is
+skipped without downloading anything, so in a week where a registry did not
+move the command does nothing at all — which is what makes it safe to schedule:
+
+```bash
+# refresh prebuilt vectors every Monday at 09:00 — crontab -e
+0 9 * * 1 /full/path/to/boost update --shards >> ~/.boost/logs/shards.log 2>&1
+```
+
+Plain `boost update` moves each tap to its branch head; `--shards` moves each
+tap to the commit the published vectors describe. Two different targets, so
+they are separate modes rather than one pass, and `--shards --taps-only` is
+refused rather than silently picking one.
+
 Because vectors are keyed to a registry's commit, `quickstart` **pins** each tap
 it fetches vectors for, and `boost update` skips a pinned tap rather than moving
 it out from under them (`--force` moves it anyway and drops the pin). When a tap
 does move, boost checks whether a newer shard exists for the new commit and
 imports it; if none does, it says so instead of leaving stale vectors looking
-fresh. `boost search` never refreshes taps behind your back — it prints one line
-when they are more than two weeks old and leaves the fetching to
-`boost update --taps-only`.
+fresh. `boost search` never refreshes taps behind your back, and never checks
+the manifest either — acting on that answer means moving taps and downloading
+hundreds of megabytes, which cannot happen inside a sub-second search. It prints
+one line when the taps or the prebuilt vectors are more than two weeks old and
+leaves the fetching to `boost update --taps-only` or `boost update --shards`.
 Every download is checked against the sha256 in the manifest and refused on a
 mismatch, and shards for a registry that has moved since publication are
 refused rather than merged — stale vectors would otherwise look fresh forever.

{boost_skill_cli-1.2.59 → boost_skill_cli-1.2.61}/boost_skill_cli.egg-info/SOURCES.txt

@@ -479,6 +479,7 @@ docs/roadmap/items/update-refreshes-rules-and-workflows.md
 docs/roadmap/items/update-reinstall-widens-agent-scope.md
 docs/roadmap/items/vex-openvex-feed.md
 docs/roadmap/items/visual-regression-pass-on-the-guide.md
+docs/roadmap/items/weekly-vectors-had-no-ingestion-path.md
 docs/roadmap/items/widen-the-ruff-rule-surface-b-sim-c4-perf-ruf.md
 docs/roadmap/items/windows-in-the-ci-matrix.md
 docs/roadmap/items/wire-bdd-suite-into-ci.md
@@ -672,6 +673,7 @@ tests/unit/test_check_licenses.py
 tests/unit/test_check_reproducible.py
 tests/unit/test_claude_settings.py
 tests/unit/test_clean_internal_cache.py
+tests/unit/test_cli_update_shards.py
 tests/unit/test_cliparse.py
 tests/unit/test_codeql_analysis_key.py
 tests/unit/test_command_reference_fresh.py
@@ -792,6 +794,7 @@ tests/unit/test_serve_docs.py
 tests/unit/test_shard_plan.py
 tests/unit/test_shards.py
 tests/unit/test_shards_incremental.py
+tests/unit/test_shards_ingest.py
 tests/unit/test_shards_matrix.py
 tests/unit/test_smoke_covers_every_command.py
 tests/unit/test_spdx_headers.py