boost-skill-cli 1.2.97__tar.gz → 1.2.98__tar.gz

{boost_skill_cli-1.2.97/boost_skill_cli.egg-info → boost_skill_cli-1.2.98}/PKG-INFO

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

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.98}/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.97'
-__version_tuple__ = version_tuple = (1, 2, 97)
+__version__ = version = '1.2.98'
+__version_tuple__ = version_tuple = (1, 2, 98)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.98}/boost_cli/commands/configuration.py

@@ -529,7 +529,9 @@ def cmd_policy(argv) -> int:
     everything = lockfile.all_installed()
     min_score = int(pol.get("min_quality_score") or 0)
     violations = []  # (name, problem)
+    not_checked: set[str] = set()
     total = 0
+    skill_count = len(everything.get("skill", {}))
     for kind, section in everything.items():
         for name, entry in sorted(section.items()):
             total += 1
@@ -541,12 +543,36 @@ def cmd_policy(argv) -> int:
                 violations.append((label, "tap %s is blocked" % tap))
             if pol["allowed_taps"] and tap not in pol["allowed_taps"] and tap != "local":
                 violations.append((label, "tap %s is not on the allowlist" % tap))
+            violations.extend(
+                (label, msg) for msg in policy.check_installed_version(entry))
+            # require_description and denied_capabilities need the item's
+            # own content, which only a skill has on disk (see
+            # store.read_skill_meta) — a rule or workflow lands in a shared
+            # agent file with no per-item body to check.
+            if kind == "skill" and (pol["require_description"] or pol["denied_capabilities"]):
+                meta_body = store.read_skill_meta(name)
+                if meta_body is None:
+                    not_checked.add(
+                        "require_description/denied_capabilities "
+                        "(store copy unreadable)")
+                else:
+                    meta, body = meta_body
+                    violations.extend(
+                        (label, msg)
+                        for msg in policy.check_installed_meta(meta, body))
+            elif kind != "skill" and (pol["require_description"] or pol["denied_capabilities"]):
+                not_checked.add(
+                    "require_description/denied_capabilities for %s items "
+                    "(no on-disk body to check)" % kind)
             # Quality scoring reads a store directory, which only skills have.
             if min_score and kind == "skill":
                 score, _notes = util.score_skill(store.skill_store_dir(name))
                 if score < min_score:
                     violations.append(
                         (label, "quality score %d < required %d" % (score, min_score)))
+    max_skills_msg = policy.max_skills_violation(skill_count)
+    if max_skills_msg:
+        violations.append(("(environment)", max_skills_msg))
     unpinned = sorted(
         n if k == "skill" else "%s (%s)" % (n, k)
         for k, section in everything.items()
@@ -560,6 +586,8 @@ def cmd_policy(argv) -> int:
                else ", ".join("%d %s%s" % (n, kind, _s(n))
                               for kind, n in counts.items()))
 
+    enforce = config.get("policy_enforce", True)
+
     if args.json:
         print(json.dumps({
             # "skills" keeps its original meaning — the skill count — with the
@@ -570,14 +598,23 @@ def cmd_policy(argv) -> int:
             "violations": [{"skill": s, "violation": v} for s, v in violations],
             "pin_only": bool(pol["pin_only"]),
             "unpinned": unpinned if pol["pin_only"] else [],
+            "enforce": enforce,
+            "not_checked": sorted(not_checked),
         }, indent=2))
         return 1 if violations else 0
 
     _warn_invalid_policy_values()
+    if not enforce:
+        out.warn("policy_enforce is off — `boost install` does not enforce "
+                 "any of the rules below; this report names what would be "
+                 "flagged, not what is currently blocked")
     if pol["pin_only"]:
-        out.info("pin-only mode is on — installs/updates are frozen"
+        out.info("pin-only mode is on — new installs and skill updates are "
+                 "frozen (tap refreshes via `boost update` are unaffected)"
                  + (" (%d unpinned item(s): %s)"
                     % (len(unpinned), ", ".join(unpinned)) if unpinned else ""))
+    for note in sorted(not_checked):
+        out.dim("  not checked: %s" % note)
     if violations:
         out.table(violations, headers=("ITEM", "VIOLATION"))
         print()
@@ -960,6 +997,21 @@ def _interval_label(seconds) -> str:
     return "%ss" % seconds
 
 
+def _plist_interval_seconds(text: str) -> int | None:
+    """Parse a usable ``StartInterval`` out of plist ``text``.
+
+    None for both "no ``StartInterval`` key" and "``StartInterval`` present
+    but not positive" — a zero or negative interval can never fire, and
+    treating it as usable is what let the next-run loop in ``cmd_schedule``
+    spin forever advancing ``nxt`` by zero seconds each pass.
+    """
+    m = re.search(r"<key>StartInterval</key>\s*<integer>(-?\d+)</integer>", text)
+    if not m:
+        return None
+    secs = int(m.group(1))
+    return secs if secs > 0 else None
+
+
 def cmd_schedule(argv) -> int:
     """boost schedule [status|enable [--interval 6h|12h|daily]|disable]"""
     p = cliparse.parser(
@@ -985,10 +1037,8 @@ def cmd_schedule(argv) -> int:
             plist = _plist_path()
             if plist.exists():
                 present = True
-                m = re.search(r"<key>StartInterval</key>\s*<integer>(\d+)</integer>",
-                              plist.read_text(encoding="utf-8"))
-                if m:
-                    secs = int(m.group(1))
+                secs = _plist_interval_seconds(plist.read_text(encoding="utf-8"))
+                if secs is not None:
                     interval = _interval_label(secs)
                     nxt = datetime.fromtimestamp(plist.stat().st_mtime + secs)
                     while nxt < datetime.now():
@@ -1015,7 +1065,8 @@ def cmd_schedule(argv) -> int:
         out.kv("platform", "%s (%s)" % (sys.platform, "launchd" if darwin else "cron"))
         out.kv("scheduled", "yes" if present else "no")
         if present:
-            out.kv("interval", "every %s" % interval)
+            out.kv("interval", "every %s" % interval if interval is not None
+                   else "unknown (plist has no usable StartInterval)")
             out.kv("next run", next_run.strftime("%Y-%m-%d %H:%M (approx)")
                    if next_run else "unknown")
         else:

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.98}/boost_cli/commands/discovery.py

@@ -37,6 +37,7 @@ from ..core import (
     store,
     util,
 )
+from ..core import discovery as discovery_core
 from ..core import output as out
 from ..core.stackprobe import detect_stack  # re-exported: shared with Quality
 from ..errors import BoostError
@@ -64,6 +65,17 @@ def _discovery_path() -> Path:
     return paths.cache_dir() / "discovery.json"
 
 
+def _index_item_count(path: Path) -> int:
+    """Item count of an existing discovery.json, or 0 if absent/unreadable."""
+    if not path.exists():
+        return 0
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return 0
+    return len(data.get("items") or [])
+
+
 def _ai_rank(query: str, scored):
     """Ask Claude to reorder the top hits. Returns a new scored list or None."""
     top = scored[:15]
@@ -172,14 +184,18 @@ def cmd_search(argv):
     # is pinned in tests/eval/baseline.json. Map instead of moving either.
     ranker = _ENGINE_LABEL.get(engine, engine) if use_rag else "heuristic relevance"
     if args.smart:
+        reranked = None
         if ai.available():
             with spin.Spinner("ranking %d matches with Claude" % len(scored)):
                 reranked = _ai_rank(query, scored)
-            if reranked:
-                scored, ranker = reranked, "Claude Haiku relevance"
+        if reranked:
+            scored, ranker = reranked, "Claude Haiku relevance"
         else:
-            # On stderr and unconditional on --json: a script reading stdout
-            # as JSON must still learn --smart silently did nothing.
+            # Fires whether AI was never available or was tried and failed —
+            # a silent unranked list otherwise looks identical to a
+            # deliberate BM25-only result. On stderr and unconditional on
+            # --json: a script reading stdout as JSON must still learn that
+            # --smart silently did nothing.
             out.warn(ai.fallback_note(), wrap=True, stream=sys.stderr)
     if args.as_json:
         print(json.dumps([e | {"score": s, "ranker": ranker}
@@ -648,19 +664,21 @@ def cmd_index(argv):
                  % (urllib.parse.quote(q, safe=":"), page)],
                 capture_output=True, text=True, timeout=120)
         except (subprocess.TimeoutExpired, OSError) as e:
+            spin.progress_clear()
             raise BoostError("gh api timed out on page %d" % page, hint=str(e)) from e
         if proc.returncode != 0:
-            tail = "\n".join((proc.stderr or proc.stdout or "").strip()
-                             .splitlines()[-3:])
+            spin.progress_clear()
             if not items:
                 raise BoostError("GitHub code search failed",
-                                hint=tail or "check `gh auth status`")
+                                hint=discovery_core.gh_failure_hint(
+                                    proc.stderr or proc.stdout or ""))
             out.warn("page %d failed — keeping the %d items fetched so far"
                      % (page, len(items)))
             break
         try:
             data = json.loads(proc.stdout)
         except json.JSONDecodeError:
+            spin.progress_clear()
             raise BoostError("gh api returned unparseable JSON",
                             hint="try `boost index` again, or `gh auth status`") from None
         if page == 1:
@@ -678,8 +696,14 @@ def cmd_index(argv):
                 break
         if len(items) >= args.limit or len(batch) < 100:
             break
+    dpath = _discovery_path()
+    if not discovery_core.should_write_index(len(items), dpath.exists()):
+        prev = _index_item_count(dpath)
+        out.warn("no SKILL.md files match %s — keeping the previous index "
+                 "of %d entries" % (query or "your query", prev))
+        return 0
     paths.ensure_dirs()
-    _discovery_path().write_text(json.dumps(
+    dpath.write_text(json.dumps(
         {"generated": util.now_iso(), "github_total": total, "query": query,
          "items": items}, indent=1), encoding="utf-8")
     repos = len({it["repo"] for it in items})

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.98}/boost_cli/commands/info.py

@@ -767,6 +767,11 @@ def cmd_explain(argv):
                      "extractive summary instead"
                      % ", ".join(faithfulness.ungrounded_terms(reply, text)[:4]),
                      stream=sys.stderr)
+        else:
+            # The backend was available but the call itself produced nothing —
+            # distinct from "no backend at all", so it gets the same
+            # attributed note rather than silence.
+            out.warn(ai.fallback_note(), wrap=True, stream=sys.stderr)
     else:
         out.warn(ai.fallback_note(), wrap=True, stream=sys.stderr)
     meta, body = frontmatter.parse(text)

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.98}/boost_cli/commands/intelligence.py

@@ -1192,6 +1192,8 @@ def cmd_impact(argv: list[str]) -> int:
             if reply:
                 print()
                 print(textwrap.indent(textwrap.fill(reply, width=76), "  "))
+            else:
+                _note_fallback()
         else:
             _note_fallback()
     out.dim("  " + note)
@@ -1256,6 +1258,11 @@ def _print_reply(reply: chat_engine.Reply, show_sources: bool) -> None:
         # a downgraded answer that looks identical to a confident one.
         out.warn("the AI reply named something outside the retrieved skills — "
                  "showing the grounded matches instead")
+    elif reply.ai_failed:
+        # AI was available and was tried, but the call itself produced
+        # nothing — distinct from never having a backend, and otherwise
+        # indistinguishable from a deliberate extractive answer.
+        out.warn(ai.fallback_note(), wrap=True, stream=sys.stderr)
 
 
 def cmd_chat(argv: list[str]) -> int:

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.98}/boost_cli/commands/pkg.py

@@ -1073,9 +1073,12 @@ def cmd_update(argv: list[str]) -> int:
         out.info("no taps configured — start with `boost tap --defaults`")
         return 0
     moved = []
+    pinned_skips = 0
     for tname, summary in results.items():
         if "skipped" not in summary:
             catalog.rebuild_tap(registry.get(tname))
+        else:
+            pinned_skips += 1
         # "abc1234 → def5678" is a tap whose tree changed; "already up to date"
         # and "pinned at ..." are not. Only the first invalidates vectors.
         if "→" in summary:
@@ -1091,6 +1094,14 @@ def cmd_update(argv: list[str]) -> int:
             "%d of %d taps could not be refreshed — the rest are up to date. "
             "Drop a dead one with `boost untap <name>`."
             % (len(failures), len(results) + len(failures)), "muted"))
+    if pinned_skips:
+        out.info(out.role(
+            "%d tap%s pinned and left alone — `boost update --force` moves "
+            "%s too, dropping %s pin%s"
+            % (pinned_skips, "s" if pinned_skips != 1 else "",
+               "them" if pinned_skips != 1 else "it",
+               "their" if pinned_skips != 1 else "its",
+               "s" if pinned_skips != 1 else ""), "muted"))
     # A pulled tap can add, drop, or rename catalogue entries, so the
     # completion name cache must not survive an update unrefreshed.
     complete.refresh_names()
@@ -1145,10 +1156,18 @@ def cmd_update(argv: list[str]) -> int:
     upgraded += _update_materialized("rule", lockfile.installed_rules(), results)
     upgraded += _update_materialized("workflow", lockfile.installed_workflows(), results)
     if not upgraded:
-        # Don't claim "everything up to date" when some taps were never
-        # reached — that is exactly the false all-clear this fix exists to stop.
-        out.ok("everything up to date" if not failures
-               else "everything up to date, except the taps above")
+        if pinned_skips and pinned_skips == len(results) and not failures:
+            # Every tap was a pinned skip: nothing was actually checked over
+            # the network, which "everything up to date" would misreport as
+            # a fresh confirmation rather than the truth — the run never left
+            # config.json.
+            out.ok("nothing to refresh — all taps pinned")
+        else:
+            # Don't claim "everything up to date" when some taps were never
+            # reached — that is exactly the false all-clear this fix exists
+            # to stop.
+            out.ok("everything up to date" if not failures
+                   else "everything up to date, except the taps above")
     # Non-zero only when nothing was refreshed at all. A partial run did the job
     # it could do, and failing it would put us back to one dead upstream
     # breaking `boost update` for the other 79.

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.98}/boost_cli/commands/quality.py

@@ -1233,6 +1233,12 @@ def cmd_conflict(argv):
             for i, p in enumerate(heuristic, 1):
                 if i in confirmed:
                     p["kind"] = "ai-confirmed"
+        elif not args.json:
+            # The backend was available but the call itself produced nothing —
+            # distinct from "no backend at all", so it gets the same
+            # attributed note rather than leaving the pairs silently
+            # unconfirmed.
+            out.warn(ai.fallback_note(), wrap=True)
     elif heuristic and not args.json:
         out.warn(ai.fallback_note(), wrap=True)
 

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.98}/boost_cli/commands/taps.py

@@ -326,6 +326,13 @@ def cmd_outdated(argv) -> int:
             continue
         matches = [e for e in catalog.find(name) if e["tap"] == tap_name]
         if not matches:
+            # The tap is untapped, or dropped this entry entirely — same
+            # condition the rule/workflow loop below reports honestly, so a
+            # skill shouldn't just vanish from the table.
+            results.append({"name": name, "kind": "skill",
+                            "installed": str(lk.get("version") or "0.0.0"),
+                            "latest": staleness.OUTDATED_SOURCE_MISSING,
+                            "tap": tap_name, "pinned": bool(lk.get("pinned"))})
             continue
         entry, _warning = catalog.select_lock_source(matches, lk)
         entry = cast(dict, entry)             # matches is non-empty above
@@ -348,7 +355,7 @@ def cmd_outdated(argv) -> int:
                 except BoostError:
                     src_missing = True
         if src_missing:
-            stale, latest_disp = True, "source missing"
+            stale, latest_disp = True, staleness.OUTDATED_SOURCE_MISSING
         else:
             reason = staleness.upstream_reason(
                 installed_v, latest, lk.get("commit", ""), head,
@@ -379,7 +386,8 @@ def cmd_outdated(argv) -> int:
             except (OSError, BoostError):
                 results.append({"name": name, "kind": kind,
                                 "installed": installed_v,
-                                "latest": "source missing", "tap": tap_name,
+                                "latest": staleness.OUTDATED_SOURCE_MISSING,
+                                "tap": tap_name,
                                 "pinned": bool(lk.get("pinned"))})
                 continue
             if hashlib.sha256(raw.encode("utf-8")).hexdigest() == lk.get("sha256"):
@@ -406,8 +414,9 @@ def cmd_outdated(argv) -> int:
              r["latest"], r["tap"]) for r in results]
     out.table(rows, headers=("NAME", "INSTALLED", "LATEST", "TAP"))
     print()
-    out.dim("%d outdated · `boost update` upgrades (pinned items stay put)"
-            % len(results))
+    source_missing = sum(1 for r in results
+                         if r["latest"] == staleness.OUTDATED_SOURCE_MISSING)
+    out.dim(staleness.outdated_footer(len(results), source_missing))
     return 0
 
 

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.98}/boost_cli/commands/team.py

@@ -782,10 +782,9 @@ def cmd_who(argv) -> int:
         # being installed would contradict `boost list`.
         found = lockfile.find_any(args.skill)
         kind, lk = found if found is not None else (None, None)
-        expertise = ("install", "edit", "evolve", "distill", "tag")
         rows = [(util.rel_time(e.get("ts", "")), e.get("user", "?"),
                  e.get("action", "?"))
-                for e in events if e.get("action") in expertise] or \
+                for e in events if journal.is_expertise_event(e)] or \
                [(util.rel_time(e.get("ts", "")), e.get("user", "?"),
                  e.get("action", "?")) for e in events]
         if args.json:
@@ -809,7 +808,7 @@ def cmd_who(argv) -> int:
         u = users.setdefault(e.get("user", "?"), {
             "events": 0, "skills": set(), "installs": 0, "last": e.get("ts", "")})
         u["events"] += 1
-        if e.get("subject"):
+        if e.get("subject") and journal.is_expertise_event(e):
             u["skills"].add(e["subject"])
         if e.get("action") == "install":
             u["installs"] += 1

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.98}/boost_cli/core/ai.py

@@ -35,6 +35,14 @@ API_URL = "https://api.anthropic.com/v1/messages"
 # for the one-line reason ("Invalid API key"), never a whole stack dump.
 STDERR_LOG_CHARS = 200
 
+# The reason the most recent `ask()` fell through, if it did. `ask()` resets
+# this before every attempt, so it always describes the last call — never a
+# stale failure from an attempt several commands ago. `unavailable_reason()`
+# reads it to tell "no backend" apart from "a backend ran and failed", which
+# `fallback_note()` used to collapse into one PATH/API-key message regardless
+# of which was true.
+_last_failure: str | None = None
+
 
 def enabled() -> bool:
     """Return True when `ai.enabled` is on and BOOST_NO_AI is unset."""
@@ -59,23 +67,44 @@ def has_cli() -> bool:
     return cli_backend() is not None
 
 
+def unavailable_reason() -> str:
+    """Why the last AI attempt degraded, as a specific, attributable clause.
+
+    Three causes used to render as one static PATH/API-key message: the user
+    disabled AI (`BOOST_NO_AI` or `ai.enabled=false`), no backend exists at
+    all, or a backend exists and was tried and failed (an expired login, an
+    untrusted workspace, a network error). Only the middle one is a PATH/key
+    problem — blaming it for the other two sends a user with a working
+    backend chasing an environment issue they do not have.
+    """
+    if os.environ.get("BOOST_NO_AI"):
+        return "disabled (BOOST_NO_AI is set)"
+    if not bool(config.get("ai.enabled", True)):
+        return "disabled (ai.enabled is off)"
+    if not (has_cli() or os.environ.get("ANTHROPIC_API_KEY")):
+        clis = " or ".join("`%s`" % aihost.cli(n) for n in aihost.backends())
+        return "unavailable — need one of %s on PATH, or ANTHROPIC_API_KEY set" % clis
+    if _last_failure:
+        return "%s — see ~/.boost/logs/boost.log" % _last_failure
+    return "unavailable"
+
+
 def fallback_note() -> str:
     """Return the one-line hint shown when a command degrades to heuristics.
 
-    Names every CLI that would work, not just Claude's — telling a Gemini user
-    to install Claude is a worse answer than telling them boost could not find
-    either.
+    Routed through :func:`unavailable_reason` so the note names the real
+    cause instead of always pointing at PATH and API keys.
     """
-    clis = " or ".join("`%s`" % aihost.cli(n) for n in aihost.backends())
-    return ("AI features need one of %s on PATH, or ANTHROPIC_API_KEY set "
-            "— using the heuristic fallback" % clis)
+    return "AI %s — using the heuristic fallback" % unavailable_reason()
 
 
 def ask(prompt: str, system: str | None = None, model: str | None = None,
         max_tokens: int = 1500, timeout: int = 120) -> str | None:
     """Ask Claude. Returns the text reply, or None if AI is unavailable/fails."""
+    global _last_failure
     if not enabled():
         return None
+    _last_failure = None
     model = model or str(config.get("ai.model"))
     backend = cli_backend()
     if backend:
@@ -101,8 +130,12 @@ def _log_failure(route: str, reason: str) -> None:
     degrade quietly, which is the right UX but leaves a user with an expired
     key or a flaky network no way to tell *why* every AI command went
     heuristic. DEBUG keeps it out of normal runs: the rotating log file always
-    records it, and ``--debug`` surfaces it on stderr.
+    records it, and ``--debug`` surfaces it on stderr. It also lands in
+    ``_last_failure`` so ``unavailable_reason()`` can name it on stderr too,
+    where a user who never passes ``--debug`` will actually see it.
     """
+    global _last_failure
+    _last_failure = "%s failed (%s)" % (route, reason)
     logs.get_logger().debug("ai: %s call failed: %s", route, reason)
 
 

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.98}/boost_cli/core/chat.py

@@ -88,6 +88,13 @@ class Reply(NamedTuple):
     ``grounded`` is False only when the AI path was tried and rejected — the
     caller may want to say so, since a silently downgraded answer looks the same
     as a confident one.
+
+    ``ai_failed`` is True only when :func:`ai.available` said yes but
+    :func:`ai.ask` came back with nothing — a backend that ran and failed,
+    not one that was never tried. Kept separate from ``grounded``: an
+    invented name or an unfaithful reply is a *rejection*, with its own
+    warning already shown by the caller, while this is a call that produced
+    no reply to reject in the first place and would otherwise fail silently.
     """
 
     text: str
@@ -95,6 +102,7 @@ class Reply(NamedTuple):
     engine: str             # which retrieval engine ran, for attribution
     source: str             # "ai" | "extractive"
     grounded: bool
+    ai_failed: bool = False
 
 
 def _history_context(history: Sequence[Turn]) -> str:
@@ -308,7 +316,11 @@ def answer(question: str, history: Sequence[Turn] = (),
         source, question)
     reply = ai.ask(prompt, system=_SYSTEM)
     if not reply:
-        return Reply(extractive, entries.copy(), engine, "extractive", True)
+        # AI was available and was tried — this is a call that failed, not a
+        # call that was never made, so the caller gets to say so rather than
+        # showing the extractive answer as if AI had never been in the loop.
+        return Reply(extractive, entries.copy(), engine, "extractive", True,
+                    ai_failed=True)
 
     reply = reply.strip()
     invented = ungrounded_names(reply, entries)

boost_skill_cli-1.2.98/boost_cli/core/discovery.py

@@ -0,0 +1,46 @@
+# Copyright the boost contributors.
+# SPDX-License-Identifier: Apache-2.0
+"""Pure logic behind `boost index`, kept out of the command layer so it's
+covered by the unit suite and targeted by the mutation gate.
+
+Two failure modes an audit found in `commands/discovery.cmd_index`:
+zero GitHub results silently wiping a working ``discovery.json``, and a
+`gh` rate-limit failure surfacing as raw multi-line stderr instead of a
+boost-native hint.
+"""
+from __future__ import annotations
+
+_RATE_LIMIT_MARKERS = ("rate limit", "gh auth login")
+_RATE_LIMIT_HINT = ("GitHub rate limit hit — wait a minute or authenticate: "
+                     "`gh auth login` / GH_TOKEN")
+
+
+def gh_failure_hint(raw: str) -> str:
+    """A one-line, boost-native hint for a failed ``gh api`` call.
+
+    `gh` reports rate limiting and auth failures as multi-line prose plus a
+    JSON blob — passed straight through as a :class:`BoostError` hint it
+    reads as noise with no boost-native next step. Detected here by the
+    markers `gh` itself uses (a rate-limit message, an HTTP 403, or its own
+    ``gh auth login`` suggestion) and replaced with one line naming the fix.
+    Anything else falls back to the tool's own last few lines, which is at
+    least specific to what broke.
+    """
+    lowered = raw.lower()
+    if any(marker in lowered for marker in _RATE_LIMIT_MARKERS) or "403" in raw:
+        return _RATE_LIMIT_HINT
+    tail = "\n".join(raw.strip().splitlines()[-3:])
+    return tail or "check `gh auth status`"
+
+
+def should_write_index(item_count: int, index_exists: bool) -> bool:
+    """Whether a `boost index` run should write its ``discovery.json``.
+
+    A zero-result run (an over-narrow query, a `gh` hiccup that still
+    returns 200 with an empty page) still exits 0, so nothing else signals
+    the loss if it overwrites a working index with an empty one. Write only
+    when there's something to write, or when nothing was there before —
+    a first run still leaves a valid (if empty) file behind rather than
+    none at all.
+    """
+    return item_count > 0 or not index_exists

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.98}/boost_cli/core/journal.py

@@ -13,6 +13,17 @@ from . import paths, util
 ROTATE_AT = 5000
 ROTATE_KEEP = 2500
 
+# Actions that reflect hands-on skill expertise, as opposed to any journal
+# subject at all (tap names, cohort names, reindex summaries, ...). `who`'s
+# per-skill view already filters to this set; the aggregate view must use the
+# same set so a "skill" it counts is actually a skill.
+EXPERTISE_ACTIONS = ("install", "edit", "evolve", "distill", "tag")
+
+
+def is_expertise_event(event: dict) -> bool:
+    """True when `event`'s action reflects hands-on skill expertise."""
+    return event.get("action") in EXPERTISE_ACTIONS
+
 
 def log(action: str, subject: str = "", **fields) -> None:
     """Append one event line to the pulse feed, rotating when oversized.

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.98}/boost_cli/core/output.py

@@ -238,10 +238,18 @@ def warn(msg: str, stream=None, wrap: bool = False) -> None:
 
 
 def err(msg: str, hint: str | None = None) -> None:
-    """Print `Error: msg` to stderr, plus a dim hint line when given."""
+    """Print `Error: msg` to stderr, plus a dim hint line when given.
+
+    A hint that carries its own newlines — gh's own multi-line failure text,
+    passed through as-is — used to print continuation lines flush at column
+    0, unindented and visually disconnected from the "hint:" label above
+    them. Every line after the first is indented to align under it instead.
+    """
     print(c("Error: ", RED, BOLD) + msg, file=sys.stderr)
     if hint:
-        print(c("  hint: " + hint, DIM), file=sys.stderr)
+        lead = "  hint: "
+        body = ("\n" + " " * len(lead)).join(hint.splitlines())
+        print(c(lead + body, DIM), file=sys.stderr)
 
 
 def info(msg: str = "", stream=None, wrap: bool = False) -> None: