boost-skill-cli 1.2.55__tar.gz → 1.2.57__tar.gz

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.57}/CLAUDE.md

@@ -105,6 +105,20 @@ opt-in evals stay out of `check` and all degrade cleanly:
   the `[eval]` extra **and** a judge key (`OPENAI_API_KEY`, or `ANTHROPIC_API_KEY`
   with `langchain-anthropic`) plus boost AI to generate the explanations.
 
+- `make eval-tools` — Tier 3 tool-call **behaviour**. Every tier above grades
+  what boost returns *once it is asked*; this grades whether it is asked, which
+  is the step they all depend on — a gate flooring recall@k at 0.78 reports
+  nothing when retrieval was never invoked. It scores **two** numbers and
+  gating on one would be the same hole `eval` had before hit@1: a floor on a
+  should-call prompt set, and a **ceiling on a should-not-call set** drawn from
+  the shipped skip list, because call rate alone rewards making the tool
+  descriptions maximally assertive — the capture `core/mcp.py` is written to
+  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
+  cleanly when `claude` is not on `PATH`.
+
 The `[eval]` extra (`pip install -e '.[eval]'`) carries `ranx` + `ragas`; nothing
 in it is ever imported by the CLI or the required gate. It pins the langchain 0.3
 stack because ragas 0.2.x breaks against langchain ≥1.0 — an isolated cost of the

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.57}/Makefile

@@ -10,7 +10,7 @@ PYTEST    := $(VENV)/bin/pytest
 # pinned taps out of the developer's real ~/.boost.
 EVAL_HOME := $(CURDIR)/.eval-home
 
-.PHONY: venv test unit functional smoke coverage patch-coverage mutation lint check demo carousel clean-test eval eval-ai eval-rec eval-stats eval-explain evals evals-baseline evals-golden evals-online audit dist-check bdd bench bench-cli fuzz post-deploy
+.PHONY: venv test unit functional smoke coverage patch-coverage mutation lint check demo carousel clean-test eval eval-ai eval-rec eval-stats eval-explain eval-tools evals evals-baseline evals-golden evals-online audit dist-check bdd bench bench-cli fuzz post-deploy
 
 # Every tool comes from a hash-pinned requirements/*.txt — the same files CI
 # installs (see scripts/lock_toolchain.py). pip enforces the hashes, so a dev
@@ -165,6 +165,17 @@ eval-explain:
 	PYTHON=$(PY) BOOST_HOME=$(EVAL_HOME) bash scripts/ensure_eval_corpus.sh
 	BOOST_HOME=$(EVAL_HOME) $(PY) scripts/eval_explain.py --fail-under 0.80
 
+# Tier 3: tool-call BEHAVIOUR — does an agent call boost's tools when it
+# should, and stay away when it should not. Tiers 1 and 2 grade what boost
+# returns once it is asked; this grades whether it is asked, which is the step
+# everything downstream depends on. Two numbers, never one: a floor on the
+# should-call half AND a ceiling on the should-not-call half, because scoring
+# call rate alone rewards an assertive surface — the capture core/mcp.py is
+# written to avoid. Drives a real host and spends real tokens, so it is opt-in
+# and OUT of `check`; degrades cleanly when no host is on PATH.
+eval-tools:
+	$(PY) scripts/eval_tools.py --runs 3
+
 # Retrieval-quality gate over the HERMETIC golden set: recall@5/@10, MRR, and
 # nDCG@5/@10 with graded (3/2/1) relevance, plus a paired-bootstrap regression
 # test against the committed evals/baseline.json. Part of `check` and required

{boost_skill_cli-1.2.55/boost_skill_cli.egg-info → boost_skill_cli-1.2.57}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.55
+Version: 1.2.57
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0
@@ -448,8 +448,10 @@ purely local operation, for CI images and air-gapped machines.
 | Claude Code | `claude` | `claude mcp add` → its user-scope MCP config |
 | Gemini CLI | `gemini` | `gemini mcp add -s user` → `~/.gemini/settings.json` |
 
-Six tools are exposed: `boost_search`, `boost_list`, `boost_info`,
-`boost_install`, `boost_doctor` and `boost_discover_github`.
+Seven tools are exposed: `boost_search`, `boost_list`, `boost_info`,
+`boost_read`, `boost_install`, `boost_doctor` and
+`boost_discover_github`. `boost_read` is the one that returns an item's
+actual text — without it, installing was the only way to read a skill.
 
 The server also returns MCP `instructions`, telling the agent when boost is
 relevant. The two hosts place those differently, and it matters. Claude Code

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.57}/README.md

@@ -406,8 +406,10 @@ purely local operation, for CI images and air-gapped machines.
 | Claude Code | `claude` | `claude mcp add` → its user-scope MCP config |
 | Gemini CLI | `gemini` | `gemini mcp add -s user` → `~/.gemini/settings.json` |
 
-Six tools are exposed: `boost_search`, `boost_list`, `boost_info`,
-`boost_install`, `boost_doctor` and `boost_discover_github`.
+Seven tools are exposed: `boost_search`, `boost_list`, `boost_info`,
+`boost_read`, `boost_install`, `boost_doctor` and
+`boost_discover_github`. `boost_read` is the one that returns an item's
+actual text — without it, installing was the only way to read a skill.
 
 The server also returns MCP `instructions`, telling the agent when boost is
 relevant. The two hosts place those differently, and it matters. Claude Code

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.57}/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.55'
-__version_tuple__ = version_tuple = (1, 2, 55)
+__version__ = version = '1.2.57'
+__version_tuple__ = version_tuple = (1, 2, 57)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.57}/boost_cli/commands/configuration.py

@@ -1169,6 +1169,47 @@ def _tool_info(args: dict):
     return "\n".join(lines), False
 
 
+def _tool_read(args: dict):
+    """`boost_read` — the item's own text, so an agent can look before it acts.
+
+    The gap this closes: ``boost_info`` returns the same one-line description
+    ``boost_search`` already returned, so an agent deciding whether a procedure
+    is worth adopting had one sentence written by whoever published it, and its
+    only route to the actual steps was to install into the user's real
+    ``~/.agents/skills`` and read it off disk. That inverts the surface's own
+    pitch — ``boost_search`` spends 10-15 s of rerank so the top result is worth
+    acting on, and then nothing let the agent look at it.
+
+    The body is also the only thing separating a written skill from a generated
+    stub, and the catalogue holds both: two ranked hits share the description
+    "To optimize **Skill**, we enforce the following foundational rules:" — an
+    unfilled template — and ``superpowers-lab`` is an 868-byte SKILL.md whose
+    Instructions section is its own name echoed back. Both index, rank and
+    render exactly like real results. The eval gate cannot catch it either:
+    ``golden.jsonl`` grades by *name*, and a stub matches its own name
+    perfectly.
+
+    Read-only, and that is the whole point rather than a side note — this is
+    the tool that exists so an agent does *not* have to install to look, so it
+    must never become a second install path. It reuses ``boost cat``'s
+    resolution (``info._resolve_text``): the installed copy when there is one,
+    the tap source otherwise, with the same integrity and quarantine rules. A
+    second resolver would be a second opinion about what "this item" means,
+    disagreeing with the tool it is advising about.
+
+    ``cat`` rather than ``explain``: cat is offline, deterministic and free,
+    while ``explain`` goes through ``core/ai.py`` and costs seconds plus a key.
+    The cheap answer must not sit behind the expensive one's latency — the same
+    reason ``boost_list`` never reads the catalog.
+    """
+    from . import info
+    name = str(args.get("name", ""))
+    if not name.strip():
+        return "boost_read needs a name — pass one as boost_search returned it", True
+    text, kind, lock, _cat = info._resolve_text(name)
+    return mcp.read_reply(name, text, kind=kind, installed=lock is not None), False
+
+
 def _tool_install(args: dict):
     entry = catalog.resolve_one(str(args.get("name", "")))
     res = store.install(entry)
@@ -1369,19 +1410,54 @@ REGISTRY.register(
     _tool_list)
 REGISTRY.register(
     "boost_info",
-    "The whole picture of one skill, rule or workflow by name — what it does, "
-    "its kind, the tap it came "
-    "from, its version, and whether it is already installed — so you can "
-    "commit or move on without guessing. Reach for it when a name arrives from "
-    "somewhere else: a teammate, a README, a repo you are reading. You do not "
-    "need this between a search and an install — boost_search already returns "
-    "each match's kind and description.",
+    # This used to promise "the whole picture" and return five fields, one of
+    # which — description — is byte-identical to the one-liner boost_search
+    # already returned. So the tool added `installed: no`, which the search
+    # reply already marks, to an agent that had been told to expect what the
+    # item does. An overstated description costs a wasted call and teaches an
+    # agent to discount the rest of the surface, which is the expensive half.
+    # It now says what it returns (status and provenance) and names the tool
+    # that returns the body.
+    "Where one skill, rule or workflow came from, by name, and whether it is "
+    "already here — its kind, tap, version, install state, and which agents "
+    "it reached. It is the STATUS of an item, not its contents: the description "
+    "it echoes is the same one-liner boost_search returned, so to read what "
+    "the item actually says, call boost_read. Reach for boost_info when a "
+    "name arrives from somewhere else — a teammate, a README, a repo you are "
+    "reading — and you need to know whether this machine already has it. You "
+    "do not need this between a search and an install: boost_search already "
+    "returns each match's kind, description and installed marker.",
     {"type": "object",
      "properties": {"name": {"type": "string",
                              "description": "the item's name, as boost_search "
                              "or boost_list returned it"}},
      "required": ["name"]},
     _tool_info)
+REGISTRY.register(
+    "boost_read",
+    "Read the actual procedure before you commit to it — the item's own text, "
+    "not its one-line description. This is the tool that makes looking cheaper "
+    "than installing: without it the only way to see what a skill actually "
+    "says is to install it into the user's machine and read it off disk, which "
+    "is a change to their setup made in order to answer a question. Reach for "
+    "it on the top hit from boost_search before boost_install, and whenever a "
+    "one-liner is doing more selling than describing. What you are checking "
+    "for is specific: the catalogue is indexed rather than reviewed, so it "
+    "holds unfilled templates and stubs that echo their own name back, and "
+    "those rank and render exactly like a procedure someone debugged. The body "
+    "is the only thing that tells them apart. Read-only and offline — it "
+    "installs nothing, changes nothing, and unlike boost_search costs no "
+    "rerank, so it is fast. Long items are truncated at a stated character "
+    "count and the reply says so and names the command that returns the rest; "
+    "a body that arrives whole is whole.",
+    {"type": "object",
+     "properties": {"name": {"type": "string",
+                             "description": "the item's name, as boost_search "
+                             "or boost_list returned it; qualify with the tap "
+                             "(\"owner/repo:name\") when the same name exists "
+                             "in more than one"}},
+     "required": ["name"]},
+    _tool_read)
 REGISTRY.register(
     "boost_install",
     "Turn a skill you found with boost_search into permanent capability: copied "

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.57}/boost_cli/commands/info.py

@@ -149,7 +149,21 @@ def _resolve_text(name: str):
     found = lockfile.find_any(bare)
     if found is None or found[0] == "skill":
         path, lock, cat = _resolve_skill_md(name)
-        return _read(path), "skill", lock, cat
+        # The lock file is the authority for an INSTALLED item, and for one
+        # that is not installed it has no opinion at all — so a rule or
+        # workflow that is only in a tap arrived here and was reported as a
+        # skill, contradicting this function's own "any kind" contract. The
+        # catalog entry knows, and `_resolve_skill_md` has already resolved it:
+        # it returns a catalog entry on exactly the branch where `lock` is
+        # None, so no second lookup is needed (and a fallback for `cat is None`
+        # here would guard a state that function cannot produce).
+        #
+        # Every caller before `boost_read` discarded this value (`_kind`), so
+        # the wrong answer was invisible: the resolution and the text were
+        # always right, only the label was not.
+        kind = ((cat.get("kind") or "skill")
+                if lock is None and cat else "skill")
+        return _read(path), kind, lock, cat
     kind, entry = found
     lock = _for_tap(entry, qualifier)
     if lock is not None:

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.57}/boost_cli/commands/quality.py

@@ -395,7 +395,14 @@ def cmd_doctor(argv):
     if taps and tap_ok == len(taps):
         out.ok("%d tap%s cloned & cached" % (len(taps), _s(len(taps))))
     elif not taps:
-        out.info("no taps configured — add one with `boost tap owner/repo`")
+        # `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
+        # in one session must not see the recommendation flip and read it as
+        # two different fixes — which is exactly what happened here: search
+        # said `--defaults`, doctor said `owner/repo`.
+        out.info("no registries tapped — nothing is searchable yet; add the "
+                 "recommended ones with `boost tap --defaults`", wrap=True)
 
     lock_ok = True
     lp = paths.lockfile_path()
@@ -598,10 +605,22 @@ def cmd_doctor(argv):
     else:
         out.warn("lock file integrity or log rotation needs attention")
 
-    out.verdict(issues == 0,
-                "healthy" if not issues else
-                "%d issue%s need attention — see the suggestions above"
-                % (issues, _s(issues)))
+    # A machine with no taps has nothing to disagree about, so every check
+    # above passes and the verdict read "healthy" — directly under the line
+    # saying no registries are tapped. That is the one state where a clean bill
+    # of health actively misleads: boost cannot answer anything yet, which is a
+    # setup step rather than a fault. Reported, never fatal — the exit code
+    # still turns only on real issues, so scripts and CI are unaffected. The
+    # MCP `boost_doctor` tool already refused to say "healthy" here; this is
+    # the CLI half of the same rule.
+    if issues == 0 and not taps:
+        out.verdict(True, "ready to set up — tap a registry to make boost "
+                          "searchable")
+    else:
+        out.verdict(issues == 0,
+                    "healthy" if not issues else
+                    "%d issue%s need attention — see the suggestions above"
+                    % (issues, _s(issues)))
     return 1 if issues else 0
 
 

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.57}/boost_cli/commands/quickstart.py

@@ -162,6 +162,26 @@ def cmd_quickstart(argv) -> int:
         planned = [n for n in names if n in pins] if manifest else []
         out.info("would build the keyword index, then import %d shard(s)"
                  % len(planned))
+        # "0 shard(s)" reads as "none are published" when the real cause is
+        # local, and --dry-run is exactly what a cautious new user runs first.
+        # The live path already explains both cases; without this the preview
+        # is the one surface that reports the symptom and withholds the reason.
+        if not planned:
+            if args.no_vectors:
+                out.info(out.role("(0 because --no-vectors was asked for)",
+                                  "muted"))
+            elif not dense.have_backend():
+                out.info("0 because semantic search needs the extra: "
+                         "`pipx inject boost-skill-cli "
+                         "\"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)
+            else:
+                out.info(out.role("(0 because none of these registries have a "
+                                  "published shard yet)", "muted"), wrap=True)
         return 0
 
     with spin.Spinner("building the keyword index"):

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.57}/boost_cli/core/mcp.py

@@ -266,6 +266,62 @@ def hit_line(entry: dict, *, installed: bool = False) -> str:
                                entry.get("tap", "?"))
 
 
+# `boost_read`'s budget, and it is a measured number rather than a round one.
+# An MCP reply lands directly in an agent's context and a SKILL.md is not
+# bounded above, so a tool that returns one whole is how a single lookup costs
+# a session. Measured over the 63,053 items in a real 467-tap install: median
+# 6,063 bytes, p90 16,225, p99 35,275, **max 567,484** — three orders of
+# magnitude between the middle and the tail, which is the shape that makes an
+# unbounded read a real hazard rather than a theoretical one.
+#
+# 12,000 is the knee. It delivers 80.3% of the catalogue whole against 62.8%
+# at 8,000 — two thirds of the remaining truncations bought for 50% more bytes
+# — and caps the worst case near 3,000 tokens. Raising it to 16,000 buys 9.3
+# points for another third again, which is the wrong side of the trade for a
+# tool an agent may call several times in one turn.
+#
+# The cap counts CHARACTERS, deliberately: boost cannot know the caller's
+# tokenizer, and a character count is one an agent can check against the reply
+# it is already holding. Truncation is never the failure mode this guards
+# against, because it is announced — see :func:`read_reply`.
+READ_LIMIT = 12000
+
+
+def read_reply(name: str, text: str, *, kind: str = "skill",
+               installed: bool = False, limit: int = READ_LIMIT) -> str:
+    """`boost_read`'s reply: a header, then the item's own content.
+
+    The header exists because the body alone does not say what the agent is
+    holding. A tap-qualified name resolves to one item out of several that
+    share a bare name, and whether it is already installed decides whether the
+    next call is `boost_install` or nothing at all — both are one line here and
+    neither is recoverable from Markdown.
+
+    **Truncation is announced, in the reply, at the point it happens.** A body
+    cut silently reads as a complete document that simply ends — which for a
+    procedure is worse than no body at all, because the agent acts on the half
+    it can see and never learns there was a second half. The notice names the
+    command that returns the rest, so the reply carries its own recovery path
+    the way ``tool-design`` asks agent-facing errors to.
+
+    Truncation cuts at a LINE boundary within the budget rather than mid-line.
+    A Markdown body cut mid-fence or mid-sentence is text an agent has to
+    guess about; a whole-line cut is unambiguously "the document continues".
+    A body whose first line already exceeds the budget has no such boundary,
+    so it falls back to a hard character cut — announced the same way.
+    """
+    head = ["name: %s" % name]
+    if kind != "skill":
+        head.append("kind: %s" % kind)
+    head.append("installed: %s" % ("yes" if installed else "no"))
+    body = text.strip("\n")
+    if len(body) > limit:
+        cut = body[:limit].rpartition("\n")[0] or body[:limit]
+        body = ("%s\n\n[truncated at %d of %d characters — read the rest with "
+                "`boost cat %s`]" % (cut, len(cut), len(text), name))
+    return "\n".join(head) + "\n\n" + body
+
+
 # The lock sections, in the order every boost surface names them. Fixed here
 # rather than read off the caller's dict, so the footer's column order cannot
 # drift between a machine that has rules and one that does not.

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.57/boost_skill_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.55
+Version: 1.2.57
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0
@@ -448,8 +448,10 @@ purely local operation, for CI images and air-gapped machines.
 | Claude Code | `claude` | `claude mcp add` → its user-scope MCP config |
 | Gemini CLI | `gemini` | `gemini mcp add -s user` → `~/.gemini/settings.json` |
 
-Six tools are exposed: `boost_search`, `boost_list`, `boost_info`,
-`boost_install`, `boost_doctor` and `boost_discover_github`.
+Seven tools are exposed: `boost_search`, `boost_list`, `boost_info`,
+`boost_read`, `boost_install`, `boost_doctor` and
+`boost_discover_github`. `boost_read` is the one that returns an item's
+actual text — without it, installing was the only way to read a skill.
 
 The server also returns MCP `instructions`, telling the agent when boost is
 relevant. The two hosts place those differently, and it matters. Claude Code

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.57}/boost_skill_cli.egg-info/SOURCES.txt

@@ -542,6 +542,7 @@ scripts/eval_gate.py
 scripts/eval_recommend.py
 scripts/eval_retrieval.py
 scripts/eval_stats_summary.py
+scripts/eval_tools.py
 scripts/import_budget.py
 scripts/lock_toolchain.py
 scripts/measure_registry.py
@@ -588,6 +589,7 @@ tests/eval/golden.jsonl
 tests/eval/recommend.jsonl
 tests/eval/taps-scale.txt
 tests/eval/taps.txt
+tests/eval/tool_calls.jsonl
 tests/functional/test_bmad_all_hosts.py
 tests/functional/test_capabilities_policy.py
 tests/functional/test_cli_adapt.py
@@ -711,6 +713,7 @@ tests/unit/test_eval_gate.py
 tests/unit/test_eval_grading.py
 tests/unit/test_eval_metrics.py
 tests/unit/test_eval_stats_summary.py
+tests/unit/test_eval_tools.py
 tests/unit/test_failure_alerting_covers_unattended.py
 tests/unit/test_faithfulness.py
 tests/unit/test_frontmatter.py
@@ -738,6 +741,7 @@ tests/unit/test_logs.py
 tests/unit/test_marketing_counts.py
 tests/unit/test_mcp.py
 tests/unit/test_mcp_install_scan.py
+tests/unit/test_mcp_read.py
 tests/unit/test_mcpdecl.py
 tests/unit/test_mcphost.py
 tests/unit/test_measure_registry.py

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.57}/docs/mcp-hub.html

@@ -329,7 +329,7 @@
         (like GitHub) probe for their dependency and <b>degrade to a message instead of crashing</b>.</p>
 
       <div class="diagram reveal">
-        <svg viewBox="0 0 920 500" role="img" aria-label="Architecture: an MCP client speaks JSON-RPC over stdio to the boost server, which routes tools/list and tools/call through the core/mcp Registry to six self-registering handlers; the boost_discover_github handler reaches out to the gh CLI and degrades gracefully.">
+        <svg viewBox="0 0 920 500" role="img" aria-label="Architecture: an MCP client speaks JSON-RPC over stdio to the boost server, which routes tools/list and tools/call through the core/mcp Registry to seven self-registering handlers; the boost_discover_github handler reaches out to the gh CLI and degrades gracefully.">
           <defs>
             <marker id="ah" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
               <path d="M0 0L10 5L0 10z" fill="#7dd3fc"/>
@@ -375,16 +375,18 @@
             <text x="672" y="119" class="lbl-s">boost_list</text>
             <rect x="660" y="134" width="220" height="26" rx="6" fill="rgba(255,255,255,.04)" stroke="var(--line-hi)"/>
             <text x="672" y="151" class="lbl-s">boost_info</text>
-            <rect x="660" y="166" width="220" height="26" rx="6" fill="rgba(255,255,255,.04)" stroke="var(--line-hi)"/>
-            <text x="672" y="183" class="lbl-s">boost_install</text>
+            <rect x="660" y="166" width="220" height="26" rx="6" fill="rgba(125,211,252,.10)" stroke="#7dd3fc" stroke-width="1.2"/>
+            <text x="672" y="183" class="lbl-s" fill="#bae6fd">boost_read  ✦ new</text>
             <rect x="660" y="198" width="220" height="26" rx="6" fill="rgba(255,255,255,.04)" stroke="var(--line-hi)"/>
-            <text x="672" y="215" class="lbl-s">boost_doctor</text>
-            <rect x="660" y="230" width="220" height="26" rx="6" fill="rgba(245,143,215,.10)" stroke="#f58fd7" stroke-width="1.2"/>
-            <text x="672" y="247" class="lbl-s" fill="#f9a8d4">boost_discover_github  ✦ new</text>
+            <text x="672" y="215" class="lbl-s">boost_install</text>
+            <rect x="660" y="230" width="220" height="26" rx="6" fill="rgba(255,255,255,.04)" stroke="var(--line-hi)"/>
+            <text x="672" y="247" class="lbl-s">boost_doctor</text>
+            <rect x="660" y="262" width="220" height="26" rx="6" fill="rgba(245,143,215,.10)" stroke="#f58fd7" stroke-width="1.2"/>
+            <text x="672" y="279" class="lbl-s" fill="#f9a8d4">boost_discover_github</text>
           </g>
           <!-- registry to handlers -->
           <line x1="610" y1="180" x2="660" y2="150" stroke="#7dd3fc" stroke-width="1.2" marker-end="url(#ah)"/>
-          <line x1="610" y1="205" x2="660" y2="243" stroke="#f58fd7" stroke-width="1.2" marker-end="url(#ahp)"/>
+          <line x1="610" y1="205" x2="660" y2="275" stroke="#f58fd7" stroke-width="1.2" marker-end="url(#ahp)"/>
 
           <!-- reach-out -->
           <rect x="620" y="330" width="260" height="72" rx="12" fill="rgba(245,143,215,.06)" stroke="#f58fd7" stroke-width="1.2"/>

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.57}/docs/roadmap/items/mcp-cannot-read-a-skill-before-installing.md

@@ -2,14 +2,14 @@
 id: mcp-cannot-read-a-skill-before-installing
 board: code
 section: dx
-status: next
+status: shipped
 category: MCP · UX
 complexity: S
 impact: High
 wow: 3
-note: boost_info returns the same one line boost_search already gave
+note: shipped — boost_read returns the body; boost_info now says what it returns
 order: 127
-owner:
+owner: feat/mcp-read-before-install
 pr:
 title: MCP has no way to read a skill before installing it
 ---
@@ -65,3 +65,25 @@ to look; it must not become a second install path.
 <b>And fix the description either way.</b> If <code>boost_info</code> keeps returning five fields, it
 should stop claiming the whole picture &mdash; an overstated tool description costs an agent a wasted
 call and teaches it to distrust the rest of the surface.
+
+<b>Shipped as <code>boost_read</code>.</b> It returns the item's own text with a two-line header
+&mdash; name, kind where it is not a skill, install state, all decisions the Markdown cannot answer
+&mdash; and reuses <code>boost cat</code>'s resolution through <code>info._resolve_text</code>, so
+installed copies, tap fallback, tap-qualified names, integrity enforcement and quarantine behave
+identically. All three of the card's requirements landed: <code>cat</code> over <code>explain</code>
+(offline, deterministic, free); a stated cap; read-only, with a test that fails if the handler ever
+reaches <code>store.install</code>.
+
+<b>The cap is measured rather than round.</b> Over the 63,053 items in a real 467-tap install the
+distribution is median <b>6,063</b> bytes, p90 <b>16,225</b>, p99 <b>35,275</b>, max <b>567,484</b>
+&mdash; three orders of magnitude between the middle and the tail, which is what makes an unbounded
+read a hazard rather than a theory. <code>READ_LIMIT = 12000</code> delivers <b>80.3%</b> of the
+catalogue whole against 62.8% at 8,000, and caps the worst case near 3,000 tokens; 16,000 would buy
+9.3 points for another third again. Truncation is announced where it happens, cuts on a line
+boundary, reports both the cut and the true size, and names the command that returns the rest.
+
+<b>And the stub case was confirmed against the live catalogue, not predicted.</b>
+<code>j4flmao/agent-skills:rag-patterns</code> opens <code>#&nbsp;Skill</code> /
+&ldquo;<em>To optimize **Skill**, we enforce the following foundational rules:</em>&rdquo; &mdash; a
+template whose placeholder was never filled, 8,934 bytes of it, indexed and ranked like any written
+procedure. Its one-liner gives no sign. That is the gap the body closes.

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.57}/docs/roadmap/items/tool-call-eval-tier.md

@@ -2,12 +2,13 @@
 id: tool-call-eval-tier
 board: code
 section: planned
-status: planned
+status: inflight
 category: Quality · Eval
 complexity: L
 impact: High
 wow: 4
 note: boost floors four retrieval metrics and measures whether an agent ever calls the tools zero times
+owner: feat/tool-call-eval
 order: 96
 title: a Tier 3 eval for tool-call behaviour, floored in <b>both</b> directions
 ---

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.57}/docs/roadmap.html

@@ -814,7 +814,7 @@ an oversight.</p></details>
       </article>
 
       <article class="cap rcard" id="tool-call-eval-tier">
-        <div class="head"><span class="pill planned">Planned</span><span class="cat">Quality · Eval</span></div>
+        <div class="head"><span class="pill inflight">In flight</span><span class="cat">Quality · Eval</span></div>
         <h3>a Tier 3 eval for tool-call behaviour, floored in <b>both</b> directions</h3>
         <p>boost's required gate floors <b>four</b> retrieval metrics — recall@k &ge; 0.78, hit@1 &ge; 0.40,
 MRR &ge; 0.52, nDCG@k &ge; 0.58 — over a 91-query golden set and a 10,152-entry corpus, every
@@ -10088,8 +10088,9 @@ rediscover them as new.</p>
       </article>
 
       <article class="cap rcard" id="mcp-cannot-read-a-skill-before-installing">
-        <div class="head"><span class="pill next">Next</span><span class="cat">MCP · UX</span></div>
+        <div class="head"><span class="pill shipped">Shipped</span><span class="cat">MCP · UX</span></div>
         <h3>MCP has no way to read a skill before installing it</h3>
+        <details class="cardbody"><summary>Write-up</summary>
         <p><code>boost_info</code>'s MCP description promises &ldquo;<em>the whole picture of one skill, rule or
 workflow by name &mdash; what it does, its kind, the tap it came from, its version, and whether it is
 already installed</em>&rdquo;. Called on a real hit it returns five fields:
@@ -10141,12 +10142,34 @@ to look; it must not become a second install path.
 
 <b>And fix the description either way.</b> If <code>boost_info</code> keeps returning five fields, it
 should stop claiming the whole picture &mdash; an overstated tool description costs an agent a wasted
-call and teaches it to distrust the rest of the surface.</p>
+call and teaches it to distrust the rest of the surface.
+
+<b>Shipped as <code>boost_read</code>.</b> It returns the item's own text with a two-line header
+&mdash; name, kind where it is not a skill, install state, all decisions the Markdown cannot answer
+&mdash; and reuses <code>boost cat</code>'s resolution through <code>info._resolve_text</code>, so
+installed copies, tap fallback, tap-qualified names, integrity enforcement and quarantine behave
+identically. All three of the card's requirements landed: <code>cat</code> over <code>explain</code>
+(offline, deterministic, free); a stated cap; read-only, with a test that fails if the handler ever
+reaches <code>store.install</code>.
+
+<b>The cap is measured rather than round.</b> Over the 63,053 items in a real 467-tap install the
+distribution is median <b>6,063</b> bytes, p90 <b>16,225</b>, p99 <b>35,275</b>, max <b>567,484</b>
+&mdash; three orders of magnitude between the middle and the tail, which is what makes an unbounded
+read a hazard rather than a theory. <code>READ_LIMIT = 12000</code> delivers <b>80.3%</b> of the
+catalogue whole against 62.8% at 8,000, and caps the worst case near 3,000 tokens; 16,000 would buy
+9.3 points for another third again. Truncation is announced where it happens, cuts on a line
+boundary, reports both the cut and the true size, and names the command that returns the rest.
+
+<b>And the stub case was confirmed against the live catalogue, not predicted.</b>
+<code>j4flmao/agent-skills:rag-patterns</code> opens <code>#&nbsp;Skill</code> /
+&ldquo;<em>To optimize **Skill**, we enforce the following foundational rules:</em>&rdquo; &mdash; a
+template whose placeholder was never filled, 8,934 bytes of it, indexed and ranked like any written
+procedure. Its one-liner gives no sign. That is the gap the body closes.</p></details>
         <div class="meta">
           <span class="m">Complexity <b>S</b></span>
           <span class="m hi">Impact <b>High</b></span>
           <span class="m">Wow <b class="wow">★★★</b></span>
-          <span class="m">boost_info returns the same one line boost_search already gave</span>
+          <span class="m">shipped — boost_read returns the body; boost_info now says what it returns</span>
         </div>
       </article>
       <!-- /ROADMAP:cards -->