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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.55
+Version: 1.2.56
 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.56}/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.56}/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.56'
+__version_tuple__ = version_tuple = (1, 2, 56)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.56}/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.56}/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.56}/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.56}/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.56}/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.56/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.56
 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.56}/boost_skill_cli.egg-info/SOURCES.txt

@@ -738,6 +738,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.56}/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.56}/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.56}/docs/roadmap.html

@@ -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 -->

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.56}/tests/bdd/features/doctor.feature

@@ -4,11 +4,13 @@ Feature: boost doctor
   Background:
     Given a fresh boost environment
 
-  Scenario: an empty environment is healthy
+  Scenario: an empty environment is set up, not healthy
     When I run "boost doctor"
     Then the exit code should be 0
     And the output should contain "boost doctor"
-    And the output should contain "no taps configured — add one with `boost tap owner/repo`"
+    And the output should contain "no registries tapped"
+    And the output should contain "boost tap --defaults"
+    And the output should contain "ready to set up"
     And the output should contain "0 skills installed · 0 taps synced · 0 broken links"
 
   Scenario: a healthy environment with installed skills

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.56}/tests/functional/test_cli_configuration.py

@@ -971,8 +971,8 @@ class TestMcp:
         assert isinstance(server_info["version"], str) and server_info["version"]
         tools = by_id[2]["result"]["tools"]
         assert [t["name"] for t in tools] == [
-            "boost_search", "boost_list", "boost_info", "boost_install",
-            "boost_doctor", "boost_discover_github"]
+            "boost_search", "boost_list", "boost_info", "boost_read",
+            "boost_install", "boost_doctor", "boost_discover_github"]
         assert all(t["inputSchema"]["type"] == "object" for t in tools)
 
         def text(id_):

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.56}/tests/functional/test_cli_info.py

@@ -379,6 +379,46 @@ class TestCat:
         assert "local edit" not in boost("cat", "rival-tap:brainstorming").out
 
 
+class TestMcpReadHonoursTheQualifier:
+    """`boost_read`'s `installed:` line answers about the item that was NAMED.
+
+    `_for_tap` returns None when a `tap:` qualifier names a different tap than
+    the installed record — its docstring is explicit that reporting tap A's
+    lock entry for a `tap-b:` question "would describe another tap's install as
+    this one's". `boost_read` derives `installed` from that same value, so it
+    inherits the precision.
+
+    Worth pinning because it is deliberately STRICTER than `mcp.hit_line`'s
+    `[installed]` marker, which is name-keyed and documents its own
+    false-positive rate. The two answer different questions — a search hit is
+    one of ten lines, a read is about one named item — and someone reconciling
+    them later should have to delete this test on purpose.
+    """
+
+    def test_the_named_taps_copy_decides_the_installed_line(self, boost,
+                                                            rival_tap):
+        from boost_cli.commands import configuration
+        boost("install", "fixture-tap:brainstorming")
+
+        installed, _ = configuration._tool_read(
+            {"name": "fixture-tap:brainstorming"})
+        other, _ = configuration._tool_read({"name": "rival-tap:brainstorming"})
+
+        assert "installed: yes" in installed.split("\n\n")[0]
+        assert "installed: no" in other.split("\n\n")[0]
+
+    def test_the_uninstalled_copy_still_returns_its_own_body(self, boost,
+                                                             rival_tap):
+        # Saying "not installed" must not mean "no content": the whole point is
+        # to read a thing before installing it.
+        from boost_cli.commands import configuration
+        boost("install", "fixture-tap:brainstorming")
+        other, is_err = configuration._tool_read(
+            {"name": "rival-tap:brainstorming"})
+        assert is_err is False
+        assert "The other tap's copy." in other
+
+
 # ── edit ─────────────────────────────────────────────────────────────────
 
 class TestEdit:

{boost_skill_cli-1.2.55 → boost_skill_cli-1.2.56}/tests/functional/test_cli_quality.py

@@ -74,6 +74,40 @@ class TestDoctor:
         assert "lock file integrity OK · log rotation healthy" in r.out
         assert "● healthy" in r.out               # dashboard verdict
 
+    def test_an_untapped_machine_is_not_called_healthy(self, boost):
+        """The one state where a clean bill of health actively misleads.
+
+        A machine with no taps has nothing to disagree about, so every check
+        passes and the verdict read "healthy" — directly under the line saying
+        no registries are tapped. boost cannot answer anything yet: that is a
+        setup step, not health. The MCP `boost_doctor` tool already refused to
+        say it here; this is the CLI half of the same rule.
+        """
+        r = boost("doctor")
+        assert "● healthy" not in r.out
+        assert "ready to set up" in r.out
+
+    def test_an_untapped_machine_is_still_rc0(self, boost):
+        # Reported, never fatal. The exit code turns on real issues only, so
+        # scripts and CI on a fresh machine are unaffected — which is what
+        # makes saying the true thing safe.
+        boost("doctor")            # the fixture asserts rc == 0
+
+    def test_the_setup_hint_names_the_same_command_search_does(self, boost):
+        """doctor said `boost tap owner/repo`; search says `boost tap
+        --defaults`. A user who hits both in one session read one problem as
+        two, and `--defaults` is the precise one — it is what `mcp.no_results`
+        and the MCP `boost_doctor` tool already name, in that order.
+        """
+        out = boost("doctor").out
+        assert "boost tap --defaults" in out
+        assert "boost tap owner/repo" not in out
+
+    def test_a_tapped_machine_is_still_healthy(self, boost, tapped):
+        # The regression that would matter: the new branch must fire only on
+        # an untapped machine.
+        assert "● healthy" in boost("doctor").out
+
     def test_broken_symlink_rc1(self, boost, installed):
         ghost = paths.home() / ".claude" / "skills" / "ghost"
         ghost.symlink_to(paths.store_dir() / "nowhere")
@@ -123,7 +157,12 @@ class TestDoctor:
 
     def test_empty_env_rc0(self, boost, sandbox):
         r = boost("doctor")
-        assert "no taps configured — add one with `boost tap owner/repo`" in r.out
+        # `boost tap --defaults`, not `boost tap owner/repo`: the same command
+        # `boost search`'s error and the MCP `boost_doctor` tool already name,
+        # so a user hitting two of these surfaces reads one problem rather than
+        # two. Pinned by TestDoctor's setup-hint test just above.
+        assert "no registries tapped" in r.out
+        assert "boost tap --defaults" in r.out
         assert "0 skills installed · 0 taps synced · 0 broken links" in r.out
 
     def test_tampered_content_rc1(self, boost, installed):