boost-skill-cli 1.2.131__tar.gz → 1.2.132__tar.gz

{boost_skill_cli-1.2.131 → boost_skill_cli-1.2.132}/.lighthouserc.json

@@ -28,7 +28,7 @@
           "matchingUrlPattern": "roadmap\\.html$",
           "aggregationMethod": "median-run",
           "assertions": {
-            "categories:performance": ["error", { "minScore": 0.8 }],
+            "categories:performance": ["error", { "minScore": 0.75 }],
             "categories:accessibility": ["error", { "minScore": 0.95 }],
             "categories:best-practices": ["error", { "minScore": 0.9 }],
             "categories:seo": ["error", { "minScore": 0.95 }]

{boost_skill_cli-1.2.131 → boost_skill_cli-1.2.132}/CLAUDE.md

@@ -116,7 +116,20 @@ opt-in evals stay out of `check` and all degrade cleanly:
   avoid. Rates carry a Wilson interval over N runs and floors are judged
   against the bound, not the point estimate: at 3/3 the normal approximation
   claims [1.00, 1.00] and would let a wording regression hide behind one lucky
-  run. Drives a real host, so it is opt-in, out of `check`, and degrades
+  run. A bound judged that way needs **enough N to be reachable**, and the
+  ceiling half is where that bites: at k=0 the Wilson upper bound is
+  z²/(n+z²), a function of N alone, so at the old `--runs 1` default a
+  flawless host was told it FAILED (0.3244 against a 0.20 ceiling, which no
+  sample below n=16 can clear). `--runs` defaults to 3, `min_n_for_ceiling` computes the
+  minimum for any ceiling, and a sample below it reports INCONCLUSIVE with its
+  own exit code (2) rather than a red that says nothing about the host —
+  unless its Wilson *lower* bound is already over the ceiling. Too small to
+  pass is not too small to fail: a conclusive red below the minimum is still a
+  red (exit 1), and a no-call half with no observations at all is
+  INCONCLUSIVE, never a pass. The
+  ceiling is 0.25 so one slip in 24 passes and two do not — a zero-tolerance
+  half beside a floor that absorbs four misses is not the same measurement
+  twice. Drives a real host, so it is opt-in, out of `check`, and degrades
   cleanly when `claude` is not on `PATH`.
 
 The `[eval]` extra (`pip install -e '.[eval]'`) carries `ranx` + `ragas`; nothing
@@ -295,8 +308,11 @@ line coverage. Target `boost_cli/core` behavior with assertions, not just import
   `noxfile.py` opens with `# Copyright the boost contributors.` and
   `# SPDX-License-Identifier: Apache-2.0`. Run
   `python3 scripts/add_spdx_headers.py` (idempotent) — the file list and the
-  expression live there, so changing the licence expression is one edit rather
-  than hundreds. Separately, `prose-lint.yml` names the Markdown files vale checks
+  expression live there (`SPDX_ID`), so changing the licence is one edit
+  rather than hundreds, and `tests/unit/test_spdx_headers.py` pins this
+  paragraph to that constant: #587 moved the tree off `GPL-3.0-only` and left
+  this sentence naming the old expression for every agent that read it since.
+  Separately, `prose-lint.yml` names the Markdown files vale checks
   **explicitly**: a new doc that is not added to that list is never linted, and
   `make lint` will not tell you.
 
@@ -608,9 +624,15 @@ upgrade rather than the entry fee. When both engines are built, `retrieve_any`
 fuses them with reciprocal rank fusion (`rag.rrf_fuse`, `RRF_K = 60`) and
 reports `hybrid RRF`; it degrades to whichever single engine is ready, and to
 BM25 alone otherwise. `dense.status()` names which of the three links (extra,
-backend, built store) is missing, and `dense.fix_hint()` maps that to the one
-next action — both `boost doctor` and `boost search` read that same table, so
-they can't give contradictory advice.
+backend, built store) is missing — or `disabled`, a fourth state that is no
+missing link at all but the `BOOST_NO_EMBED` kill switch, which sits **first**
+in the ladder (`embed.provider()` reads it before any key, so every other
+remedy is a measured no-op under it) and is excluded from `degraded`, so a
+deliberate opt-out never moves doctor's exit code. `dense.fix_hint()` maps
+whichever state it is to the one next action — `boost doctor`, `boost search`,
+the MCP `SEARCH ENGINE` line and both shard surfaces (`reindex --fetch-shards`,
+`update --shards`) all read that same table, so they can't give contradictory
+advice.
 
 **The dense store ranks twice, and `vec0` is why.** `sqlite-vec` has no ANN
 index: a float32 `MATCH` scores *every* vector in the store, which on a real

{boost_skill_cli-1.2.131/boost_skill_cli.egg-info → boost_skill_cli-1.2.132}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.131
+Version: 1.2.132
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0
@@ -62,9 +62,9 @@ Antigravity CLI (`agy`) is wired up the same way: skills link into
 
 ```bash
 pipx install boost-skill-cli
-boost quickstart              # taps the 7 starter registries, loads prebuilt vectors
-boost search tdd              # keyword + semantic, fused
-boost install tdd-workflow    # → every agent, version-pinned, one lock file
+boost quickstart                       # taps the 7 starter registries, builds the index
+boost search tdd                       # ranked by full-content BM25
+boost install test-driven-development  # → every agent, version-pinned, one lock file
 ```
 
 (No `pipx` yet? macOS ships neither it nor a new enough Python — run the

{boost_skill_cli-1.2.131 → boost_skill_cli-1.2.132}/README.md

@@ -20,9 +20,9 @@ Antigravity CLI (`agy`) is wired up the same way: skills link into
 
 ```bash
 pipx install boost-skill-cli
-boost quickstart              # taps the 7 starter registries, loads prebuilt vectors
-boost search tdd              # keyword + semantic, fused
-boost install tdd-workflow    # → every agent, version-pinned, one lock file
+boost quickstart                       # taps the 7 starter registries, builds the index
+boost search tdd                       # ranked by full-content BM25
+boost install test-driven-development  # → every agent, version-pinned, one lock file
 ```
 
 (No `pipx` yet? macOS ships neither it nor a new enough Python — run the

{boost_skill_cli-1.2.131 → boost_skill_cli-1.2.132}/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.131'
-__version_tuple__ = version_tuple = (1, 2, 131)
+__version__ = version = '1.2.132'
+__version_tuple__ = version_tuple = (1, 2, 132)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.131 → boost_skill_cli-1.2.132}/boost_cli/cli.py

@@ -118,7 +118,7 @@ COMMANDS = [
     ("health",      "chk", "quality", "Dashboard of skill-environment health"),
     ("trust",       "chk", "quality", "Manage signing keys & verify tap provenance"),
     # Configuration (13)
-    ("quickstart",  "cfg", "quickstart", "Tap the starter registries and load prebuilt vectors"),
+    ("quickstart",  "cfg", "quickstart", "Tap the starter registries and index them for search"),
     ("config",      "cfg", "configuration", "Display or modify boost configuration"),
     ("clean",       "cfg", "configuration", "Clear stale caches & broken symlinks"),
     ("compact",     "cfg", "configuration", "Shrink tap clones to the files boost indexes"),
@@ -199,6 +199,7 @@ def print_help() -> None:
     print(out.c(
         "Options:  -V/--version   -v/--verbose   --debug   -q/--quiet",
         out.DIM))
+    _print_first_run_line(cols)
 
     width = max(len(n) for n, _, _, _ in COMMANDS)
     for idx, (gkey, (_icon, title, desc)) in enumerate(GROUPS.items()):
@@ -223,6 +224,35 @@ def print_help() -> None:
     print(out.c("%d commands · %d groups" % (len(COMMANDS), len(GROUPS)), out.DIM))
 
 
+def _print_first_run_line(cols: int) -> None:
+    """Name where setup lives, but only on a machine that has none.
+
+    This screen read no state at all, so it was byte-for-byte identical on a
+    virgin machine and a working one, and a newcomer met 81 commands with
+    `quickstart` sitting at line 80, in the same dim body type as the other 80.
+    The pointer is one line, it appears only while `config.first_run()` holds,
+    and it disappears the moment there is a tap: a permanent banner would be
+    noise for every user past their first minute, which is the reason there
+    wasn't one.
+
+    Asked of `config`, which help has already loaded for its log level, so the
+    question costs `boost --help` no module it was not importing anyway. Any
+    failure is swallowed — a broken config must cost the user a hint, never
+    their help screen.
+    """
+    with contextlib.suppress(Exception):
+        from .core import config
+        if not config.first_run():
+            return
+        print()
+        # Wrap, then colour: `out.role` brackets its argument with a start code
+        # and a reset, so colouring first and splitting after leaves line one
+        # unterminated. The backtick span stays one atomic token, because a
+        # `boost quickstart` folded across two lines is not copy-pasteable.
+        for line in out.wrap(config.FIRST_RUN_HINT, max(cols, 20)):
+            print(out.role(line, "muted"))
+
+
 def print_command_help(name: str) -> int:
     # `main`'s own aliases (-h/--help, -V/--version/version, help itself)
     # never appear in COMMANDS, so `boost help --help` used to fall straight

{boost_skill_cli-1.2.131 → boost_skill_cli-1.2.132}/boost_cli/commands/configuration.py

@@ -1538,6 +1538,10 @@ def _tool_install(args: dict):
     lines.append("quality score: %d/100" % res.score)
     if res.conflicts:
         lines.append("conflicts (left in place): %s" % ", ".join(res.conflicts))
+    if res.unwritable:
+        lines.append("not linked, directory not writable: %s — ask the user to "
+                     "`chmod u+w` it, then `boost sync`"
+                     % ", ".join(res.unwritable))
     # The same prompt-injection and secret scan `boost install` runs. This path
     # needs it more, not less: nobody is watching a terminal here, and the skill
     # was chosen and installed by an agent acting on its own. The install still
@@ -1591,7 +1595,16 @@ def _tool_doctor(args: dict):
     # Additive, deliberately: an untapped machine can ALSO have a broken
     # materialization, and folding the two into one branch would hide the
     # issue count behind the setup note.
-    if not taps:
+    # With config.json unreadable the tap list reads as DEFAULTS' empty one,
+    # and the note below would send the agent to re-tap the defaults over the
+    # user's real list — the fix CLI `boost doctor` now names instead.
+    cfg_err = config.check()
+    if cfg_err:
+        total += 1
+        lines.append("%s — boost is running on defaults, so the user's taps are "
+                     "not listed; ask the user to repair the file or re-add "
+                     "their taps (run `boost doctor` for details)" % cfg_err)
+    elif not taps:
         # Same command, same order, as mcp.no_results: an agent that calls
         # both tools in one session must not see the recommendation flipped
         # and read it as two different fixes. `boost tap --defaults` leads
@@ -1603,7 +1616,7 @@ def _tool_doctor(args: dict):
     if total == 0:
         if taps:
             lines.append("healthy — no issues found")
-    elif mat_issues:
+    elif mat_issues or cfg_err:
         lines.append("%d issue(s) — run `boost doctor` for details" % total)
     else:
         lines.append("%d issue(s) — run `boost sync` to fix" % issues)
@@ -1684,7 +1697,14 @@ REGISTRY.register(
     "Coming back empty is a real answer too, not a "
     "wasted turn: it means build it yourself, now knowing nothing already "
     "covers it — and on a machine with nothing tapped yet it says so and names "
-    "the one command that fixes it, rather than reporting a miss.",
+    "the one command that fixes it, rather than reporting a miss. "
+    # The bound, verbatim from `mcp.INSTRUCTIONS`: six of its seven
+    # load-bearing elements were already duplicated into this description and
+    # the seventh — the one that says when not to call — was in none of the
+    # seven. On a Gemini-family host the description is the only boost text
+    # reliably in context, so what shipped there was every persuasive element
+    # and none of the restraint.
+    + mcp.SKIP_IT,
     {"type": "object",
      "properties": {"query": {"type": "string",
                               "description": "what you are trying to do, in "

{boost_skill_cli-1.2.131 → boost_skill_cli-1.2.132}/boost_cli/commands/discovery.py

@@ -233,18 +233,25 @@ def cmd_search(argv):
     installed: set[str] = set()
     with contextlib.suppress(Exception):
         installed = set(store.installed())
-    top = max((s for _e, s in shown), default=0) or 1
+    # The meter reads across the whole shown page, so its fractions are one
+    # screen-wide decision rather than a per-row division — see
+    # out.relevance_fractions for why the top score alone cannot say it.
+    fracs = out.relevance_fractions([s for _e, s in shown])
     # One column plan for the whole screen (name, kind, tap, description with
     # a stated drop order), one assembler per row — both pure and unit-tested
     # in core.output, so this loop only feeds and prints.
-    lay = out.search_layout(out.term_width(),
+    # Against the *pane*: a pipe has none, and planning for `term_width()`'s
+    # assumed 80 dropped the TAP column (it needs 84), so `boost search x |
+    # grep owner/repo` found nothing the same search shows on a wide pane.
+    # No pane (None) plans nothing to fit — see `search_layout`.
+    lay = out.search_layout(out.pane_width(),
                             [e["name"] for e, _ in shown],
                             [str(e.get("kind") or "skill") for e, _ in shown],
                             [str(e.get("tap") or "") for e, _ in shown])
-    for e, sc in shown:
+    for (e, _sc), frac in zip(shown, fracs, strict=True):
         out.info(out.format_search_row(
             e["name"], e.get("description") or "",
-            str(e.get("kind") or "skill"), str(e.get("tap") or ""), sc / top,
+            str(e.get("kind") or "skill"), str(e.get("tap") or ""), frac,
             curated=bool(e.get("curated")),
             installed=e["name"] in installed, lay=lay))
     if hit_cap:
@@ -1983,6 +1990,9 @@ def cmd_browse(argv):
                      + ", ".join(agents.display_name(a) for a in res.linked))
         for conflict in res.conflicts:
             out.warn("conflict: %s exists and is not a symlink" % _tilde(conflict))
+        for adir in res.unwritable:
+            out.warn("not linked: %s is not writable — `chmod u+w %s`, then "
+                     "`boost sync`" % (_tilde(adir), _tilde(adir)))
     return 0
 
 

{boost_skill_cli-1.2.131 → boost_skill_cli-1.2.132}/boost_cli/commands/info.py

@@ -769,6 +769,13 @@ def cmd_preview(argv):
 _FAITHFULNESS_MIN_KEY = "ai.explain_faithfulness_min"
 _FAITHFULNESS_DEFAULT = 0.5
 
+# The heuristic explain's outline is a summary, not a reprint of the file.
+# Uncapped it printed 521 lines for one catalog entry, while "Key rules:" in
+# the same function stopped at 12. 25 is the line the audit measured against:
+# the median entry (16 headings) prints unchanged, and the ~28% over it get a
+# counted "… and N more headings" instead of a wall.
+_OUTLINE_CAP = 25
+
 
 def _faithfulness_threshold() -> float:
     """The minimum faithfulness score an AI explanation must clear (config-tunable).
@@ -841,8 +848,12 @@ def cmd_explain(argv):
     if headings:
         print()
         out.info(out.c("Outline:", out.BOLD))
-        for hashes, title in headings:
+        for hashes, title in headings[:_OUTLINE_CAP]:
             out.info("  " * len(hashes) + title)
+        if len(headings) > _OUTLINE_CAP:
+            more = len(headings) - _OUTLINE_CAP
+            out.info(out.role("  … and %d more heading%s"
+                              % (more, "" if more == 1 else "s"), "muted"))
     rules, seen = [], set()
     for line in body.splitlines():
         stripped = re.sub(r"^\s*(?:[-*]|\d+\.)\s+", "", line).strip()

{boost_skill_cli-1.2.131 → boost_skill_cli-1.2.132}/boost_cli/commands/pkg.py

@@ -260,12 +260,23 @@ def _report_result(res: store.InstallResult, no_mcp: bool = False) -> None:
                % " · ".join(agents.display_name(a) for a in res.native))
     for path in res.conflicts:
         out.warn("not linked: %s exists and is not managed by boost" % _tilde(path))
+    _warn_unwritable(res)
     out.ok("lock updated (.skill-lock.json)")
     _warn_injection(res)
     _warn_secrets(res)
     _offer_mcp(res, no_mcp=no_mcp)
 
 
+def _warn_unwritable(res) -> None:
+    """Name the remedy for each agent skills dir an install could not link
+    into — every path that installs, reinstall and update included, so none
+    reports success over a link it silently skipped."""
+    for adir in res.unwritable:
+        out.warn("not linked: %s is not writable — `chmod u+w %s`, then "
+                 "`boost sync` adds the link" % (_tilde(adir), _tilde(adir)),
+                 wrap=True)
+
+
 def _boostfile_text(skills: dict[str, dict], via: str = "boost bundle dump") -> str:
     """Render lock entries as a Boostfile (taps first, then sorted skills)."""
     lines = ["# Boostfile — generated by %s" % via]
@@ -1159,7 +1170,7 @@ def cmd_update(argv: list[str]) -> int:
                      "--yes` to apply" % name)
             continue
         try:
-            store.install(entry, force=True)
+            _warn_unwritable(store.install(entry, force=True))
         except BoostError as err:
             out.warn("%s: %s" % (name, err.message))
             continue
@@ -1245,8 +1256,9 @@ def cmd_reinstall(argv: list[str]) -> int:
             if warning:
                 out.warn(warning)
             try:
-                store.install(entry, force=True,
-                              scope=lk.get("scope", "user"), base=lk.get("base"))
+                _warn_unwritable(store.install(
+                    entry, force=True,
+                    scope=lk.get("scope", "user"), base=lk.get("base")))
             except BoostError as err:
                 out.warn("%s: %s" % (name, err.message))
                 failed += 1
@@ -1288,7 +1300,7 @@ def cmd_reinstall(argv: list[str]) -> int:
         if warning:
             out.warn(warning)
         try:
-            store.install(entry, force=True)
+            _warn_unwritable(store.install(entry, force=True))
         except BoostError as err:
             out.warn("%s: %s" % (name, err.message))
             failed += 1

{boost_skill_cli-1.2.131 → boost_skill_cli-1.2.132}/boost_cli/commands/quality.py

@@ -27,6 +27,7 @@ from ..core import (
     catalog,
     claude_settings,
     complete,
+    config,
     frontmatter,
     gitutil,
     imperative,
@@ -412,6 +413,20 @@ def cmd_doctor(argv):
         bad("git", "git not found on PATH — install git")
     paths.ensure_dirs()  # create silently; never a failure
 
+    # A corrupt config.json reads as DEFAULTS, so the tap list below comes
+    # back empty and the verdict used to be "ready to set up", exit 0, on a
+    # machine whose clones were all still on disk. Say what was lost instead.
+    cfg_err = config.check()
+    if cfg_err:
+        clones = config.unlisted_clones()
+        bad("config", "%s — boost is running on defaults, so %s. Repair the "
+            "file, or re-add your taps; the next write moves the bad file "
+            "to config.json.corrupt" % (cfg_err, (
+                "the %d tap clone%s on disk %s not listed" % (
+                    len(clones), _s(len(clones)),
+                    "is" if len(clones) == 1 else "are"))
+                if clones else "no taps or settings are read"), wrap=True)
+
     taps = registry.list_taps()
     tap_ok = 0
     for tap in taps:
@@ -422,9 +437,21 @@ def cmd_doctor(argv):
                 % (tap.name, tap.name))
         else:
             tap_ok += 1
+    # A cache dir boost cannot write leaves every command rescanning its taps
+    # and warning that it could not keep the result (catalog.rebuild_tap), so
+    # "cloned & cached" below would be the one line on the screen claiming
+    # otherwise.
+    cache_writable = (not paths.cache_dir().is_dir()
+                      or os.access(paths.cache_dir(), os.W_OK))
+    if taps and not cache_writable:
+        bad("cache", "%s is not writable — every command rescans its taps and "
+            "cannot keep the result; make it writable"
+            % _tilde(paths.cache_dir()), wrap=True)
     if taps and tap_ok == len(taps):
-        rep.ok("taps", "%d tap%s cloned & cached" % (len(taps), _s(len(taps))))
-    elif not taps:
+        rep.ok("taps", "%d tap%s cloned%s" % (len(taps), _s(len(taps)),
+                                              " & cached" if cache_writable
+                                              else ""))
+    elif not taps and not cfg_err:
         # `boost tap --defaults` leads, and it is the same command in the same
         # order that `boost search`'s error, `mcp.no_results` and the MCP
         # `boost_doctor` tool all name. A user who hits two of these surfaces
@@ -660,9 +687,16 @@ def cmd_doctor(argv):
             % (dup.name, agents.display_name(dup.agent), _tilde(dup.path),
                _tilde(dup.target)), wrap=True)
 
-    for adir in enabled.values():
+    # Linking agents only: a native-store agent's skills dir (Gemini's) is
+    # never written, so its permissions are not boost's problem and `boost
+    # sync` could not act on them.
+    for adir in agents.linking_agents().values():
         if adir.is_dir() and not os.access(str(adir), os.W_OK):
-            bad("agent-dir", "agent dir %s is not writable" % _tilde(adir))
+            # A next action, like the log line below it: without one this was
+            # the only issue doctor names that nothing can act on.
+            bad("agent-dir", "agent dir %s is not writable — `chmod u+w %s`, "
+                "then `boost sync` relinks what it missed"
+                % (_tilde(adir), _tilde(adir)), wrap=True)
 
     rotation = journal.rotation_healthy()
     if not rotation:
@@ -798,6 +832,27 @@ def _report_search_engine(rep) -> None:
                   hint=fix, wrap=True)
         return
 
+    if st["reason"] == "disabled":
+        # A deliberate opt-out, not a fault, so it stays a note and doctor
+        # stays green: BOOST_NO_EMBED is documented as the hard kill switch,
+        # and the CI job that sets it is the one caller that most needs a
+        # zero exit code. Say the vectors are still there, because the user
+        # who turned it off is the user deciding whether to turn it back on.
+        held = ""
+        if st["store_exists"] and st["chunks"]:
+            # "still on disk", not "intact": the switch shadows every rung
+            # below it, so a store that is *also* stale (version/model/dim
+            # changed) reaches this line too, and unsetting the switch would
+            # turn it red rather than green. Say what is measured — the
+            # vectors were not discarded — and let the next status say more.
+            held = (" — the %d-chunk vector store is still on disk"
+                    % st["chunks"])
+        rep.note("search-engine",
+                 "semantic search off by BOOST_NO_EMBED — using the "
+                 "full-content BM25 engine%s (%s)" % (held, fix),
+                 hint=fix, wrap=True)
+        return
+
     rep.note("search-engine",
              "semantic search not configured — using the full-content BM25 "
              "engine (%s)" % fix, hint=fix, wrap=True)
@@ -1139,18 +1194,26 @@ def cmd_heal(argv):
             out.warn("%s is no longer a symlink into the store — left alone"
                      % _tilde(dup.path))
 
+    # A dir that exists and refuses writes. A MISSING one is not stuck: the
+    # real run creates it above, so a preview that called it unwritable would
+    # exit 1 where the run it previews exits 0.
+    cache_dir = paths.cache_dir()
+    cache_stuck = cache_dir.is_dir() and not os.access(cache_dir, os.W_OK)
     for tap in registry.list_taps():
         if not tap.is_cloned:
             out.warn("tap %s not cloned — skipped (run `boost update`)" % tap.name)
             continue
         had_cache = tap.cache_file.exists()
         if dry:
-            if not had_cache:
+            if not had_cache and not cache_stuck:
                 out.info("would rebuild catalog cache for %s" % tap.name)
                 actions.append("cache %s" % tap.name)
         else:
             catalog.rebuild_tap(tap)
-            if not had_cache:
+            # rebuild_tap survives a cache it cannot write and warns; claiming
+            # the rebuild under that warning would certify a file that is
+            # still missing, and every later run would claim it again.
+            if not had_cache and tap.cache_file.exists():
                 out.ok("rebuilt catalog cache for %s" % tap.name)
                 actions.append("cache %s" % tap.name)
 
@@ -1164,15 +1227,38 @@ def cmd_heal(argv):
             out.ok("journal rotation scheduled (next write rotates)")
         actions.append("rotate")
 
-    if not actions:
+    # Not repairable from here — the tap list is the user's, not derivable —
+    # and never covered by an all-clear: with it unreadable, every check
+    # above ran against DEFAULTS.
+    cfg_err = config.check()
+    if cfg_err:
+        out.warn("%s — heal cannot repair it: boost is running on defaults "
+                 "until the file is fixed or your taps are re-added"
+                 % cfg_err, wrap=True)
+    # Permissions are the user's to change, not heal's; but a dir heal saw and
+    # cannot fix must not sit under an all-clear.
+    stuck = [adir for adir in agents.linking_agents().values()
+             if adir.is_dir() and not os.access(str(adir), os.W_OK)]
+    for adir in stuck:
+        out.warn("agent dir %s is not writable — heal does not change "
+                 "permissions; run `chmod u+w %s`, then `boost sync`"
+                 % (_tilde(adir), _tilde(adir)), wrap=True)
+    # The same rule for the cache dir doctor flags: heal cannot make it
+    # writable, so it must not answer "nothing to heal" beneath the problem.
+    if registry.list_taps() and cache_stuck:
+        stuck.append(cache_dir)
+        out.warn("%s is not writable — heal does not change permissions; "
+                 "run `chmod u+w %s`" % (_tilde(cache_dir), _tilde(cache_dir)),
+                 wrap=True)
+    if not actions and not stuck and not cfg_err:
         # A duplicate this run declined to prune is something `heal` saw, can
         # fix, and deliberately left. A bare "nothing to heal" printed under
         # the line offering the flag contradicts it.
         out.ok("nothing to heal automatically"
                if declined_duplicates else "nothing to heal")
-    elif not dry:
+    if actions and not dry:
         journal.log("heal", "%d actions" % len(actions))
-    return 0
+    return 1 if cfg_err or stuck else 0
 
 
 def cmd_conflict(argv):

{boost_skill_cli-1.2.131 → boost_skill_cli-1.2.132}/boost_cli/commands/quickstart.py

@@ -135,6 +135,18 @@ def _report(results: list[dict]) -> None:
                  "`boost reindex --dense`")
 
 
+def _muted(msg: str) -> None:
+    """An indented muted line, wrapped to the pane.
+
+    Wrap first, colour each line after: `out.role` brackets its argument with
+    a start code and a reset, so colouring first and folding after leaves
+    line 1 unterminated and the rest unstyled (CLAUDE.md's wrap rule). `- 2`
+    pays for the indent `out.info` adds.
+    """
+    for line in out.wrap(msg, max(out.term_width() - 2, 20)):
+        out.info(out.role(line, "muted"))
+
+
 def cmd_quickstart(argv) -> int:
     """boost quickstart [--catalog] [--no-vectors] [--dry-run]"""
     p = cliparse.parser(
@@ -161,7 +173,15 @@ def cmd_quickstart(argv) -> int:
                 manifest = shards.fetch_manifest()
             pins = shards.rows(manifest)
         except BoostError as exc:
-            out.warn("no published shards: %s" % exc.message)
+            # "no published shards" named the wrong cause — the project's
+            # shards are fine; this machine could not read the manifest (a
+            # proxy, a dropped connection, a BOOST_SHARD_MANIFEST typo, an
+            # air-gapped mirror). And the hint was the actionable half: every
+            # transport-shaped failure raised here carries one.
+            out.warn("could not read the shard manifest: %s" % exc.message,
+                     wrap=True)
+            if exc.hint:
+                _muted(exc.hint)
             manifest = None
 
     selection = _selection(args.catalog)
@@ -184,12 +204,11 @@ def cmd_quickstart(argv) -> int:
                          "\"boost-skill-cli[rag]\"` — keyword search works "
                          "without it", wrap=True)
             elif manifest is None:
-                out.info(out.role("(0 because the shard manifest could not be "
-                                  "read — keyword search is unaffected)",
-                                  "muted"), wrap=True)
+                _muted("(0 because the shard manifest could not be read — "
+                       "keyword search is unaffected)")
             else:
-                out.info(out.role("(0 because none of these registries have a "
-                                  "published shard yet)", "muted"), wrap=True)
+                _muted("(0 because none of these registries have a "
+                       "published shard yet)")
         return 0
 
     with spin.Spinner("building the keyword index"):
@@ -215,6 +234,13 @@ def cmd_quickstart(argv) -> int:
         out.info("semantic search needs the extra: "
                  "`pipx inject boost-skill-cli \"boost-skill-cli[rag]\"`, "
                  "then `boost quickstart` again")
+    elif want_vectors:
+        # The whole vector step was skipped, and the only word about it was a
+        # warning many screens back. Without this the run ends "✓ ready" as
+        # though vectors had been imported.
+        _muted("no vectors imported — the shard manifest could not be read; "
+               "`boost update --shards` retries it, and `boost reindex "
+               "--dense` builds them locally")
 
     complete.refresh_names()
     out.ok("ready — try `boost search brainstorming`")