boost-skill-cli 1.2.134__tar.gz → 1.2.135__tar.gz

{boost_skill_cli-1.2.134 → boost_skill_cli-1.2.135}/CLAUDE.md

@@ -645,10 +645,12 @@ attempt for an hour (`RETRY_AFTER`): measured on a 5-chunk store, each search
 paid one failed fetch (~3.6 s against 0.1 s) while doctor said "active".
 `boost reindex --dense` retries at once, because it is the remedy the hint
 names. `dense.ready()` still answers for the store alone. `dense.fix_hint()` maps
-whichever state it is to the one next action — `boost doctor`, `boost search`,
-the MCP `SEARCH ENGINE` line and both shard surfaces (`reindex --fetch-shards`,
-`update --shards`) all read that same table, so they can't give contradictory
-advice.
+whichever state it is to the one next action — `boost doctor`, `boost search`
+and the MCP `SEARCH ENGINE` line all read that same table, so they can't give
+contradictory advice. The shard surfaces (`reindex --fetch-shards`, `update
+--shards`, `quickstart` and the vector refresh in `boost update`) answer a refused
+manifest through `shards.remedy()`, which hands back to that table, with the
+whole status, whenever the store or a missing provider is the real answer.
 
 **The dense store ranks twice, and `vec0` is why.** `sqlite-vec` has no ANN
 index: a float32 `MATCH` scores *every* vector in the store, which on a real

{boost_skill_cli-1.2.134/boost_skill_cli.egg-info → boost_skill_cli-1.2.135}/PKG-INFO

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

{boost_skill_cli-1.2.134 → boost_skill_cli-1.2.135}/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.134'
-__version_tuple__ = version_tuple = (1, 2, 134)
+__version__ = version = '1.2.135'
+__version_tuple__ = version_tuple = (1, 2, 135)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.134 → boost_skill_cli-1.2.135}/boost_cli/commands/configuration.py

@@ -1594,9 +1594,10 @@ def _tool_install(args: dict):
     if res.conflicts:
         lines.append("conflicts (left in place): %s" % ", ".join(res.conflicts))
     if res.unwritable:
-        lines.append("not linked, directory not writable: %s — ask the user to "
+        lines.append("not %s, directory not writable: %s — ask the user to "
                      "`chmod u+w` it, then `boost sync`"
-                     % ", ".join(res.unwritable))
+                     % ("linked" if res.kind == "skill" else "written",
+                        ", ".join(res.unwritable)))
     # The same prompt-injection and secret scan `boost install` runs. This path
     # needs it more, not less: nobody is watching a terminal here, and the skill
     # was chosen and installed by an agent acting on its own. The install still
@@ -2059,13 +2060,21 @@ def _offer_boost_first(hosts: list[str]) -> None:
     try:
         builtin.ensure_tap()
         catalog.rebuild_tap(registry.get(builtin.BUILTIN_TAP))
-        store.install(catalog.resolve_one(builtin.BUILTIN_RULES[0]),
-                     only_agents=[a for a in scoped_agents if a])
+        res = store.install(catalog.resolve_one(builtin.BUILTIN_RULES[0]),
+                            only_agents=[a for a in scoped_agents if a])
     except (BoostError, OSError) as exc:
         out.warn("could not install %s: %s" % (builtin.BUILTIN_RULES[0], exc))
         return
-    out.ok("installed %s — remove it with `boost uninstall %s`"
-           % (builtin.BUILTIN_RULES[0], builtin.BUILTIN_RULES[0]))
+    from .pkg import _warn_unwritable
+    if not res.linked:
+        # Every file it was offered for refused the write. The lock records
+        # the refusal so `boost sync` can finish it, but "installed" would be
+        # a success nothing on disk backs.
+        out.warn("%s was not written anywhere yet" % builtin.BUILTIN_RULES[0])
+    else:
+        out.ok("installed %s — remove it with `boost uninstall %s`"
+               % (builtin.BUILTIN_RULES[0], builtin.BUILTIN_RULES[0]))
+    _warn_unwritable(res)
 
 
 def cmd_mcp(argv) -> int:

{boost_skill_cli-1.2.134 → boost_skill_cli-1.2.135}/boost_cli/commands/discovery.py

@@ -109,7 +109,7 @@ def cmd_search(argv):
                    help="rerank the top hits with Claude")
     p.add_argument("--category", default="",
                    help="only show entries whose category matches (case-insensitive)")
-    p.add_argument("--limit", type=util.positive_int, default=15,
+    p.add_argument("-k", "--limit", type=util.positive_int, default=15,
                    help="max results (default 15)")
     p.add_argument("--collapse-near-duplicates", action="store_true",
                    dest="collapse_dupes",
@@ -2017,8 +2017,9 @@ def cmd_browse(argv):
         for conflict in res.conflicts:
             out.warn("conflict: %s exists and is not a symlink" % _tilde(conflict))
         for adir in res.unwritable:
-            out.warn("not linked: %s is not writable — `chmod u+w %s`, then "
-                     "`boost sync`" % (_tilde(adir), _tilde(adir)))
+            out.warn("not %s: %s is not writable — `chmod u+w %s`, then "
+                     "`boost sync`" % ("linked" if res.kind == "skill" else "written",
+                                       _tilde(adir), _tilde(adir)))
     return 0
 
 

{boost_skill_cli-1.2.134 → boost_skill_cli-1.2.135}/boost_cli/commands/intelligence.py

@@ -1294,8 +1294,10 @@ def cmd_chat(argv: list[str]) -> int:
     ap.add_argument("question", nargs="*", metavar="QUESTION",
                     help="ask once and exit; omit for an interactive session")
     ap.add_argument("-k", "--limit", type=util.positive_int, default=chat_engine.TOP_K,
-                    metavar="N", help="candidate skills to consider (default %d)"
-                                      % chat_engine.TOP_K)
+                    metavar="N",
+                    help="candidate skills per search (default %d); a follow-up "
+                         "that points back also keeps the previous list"
+                         % chat_engine.TOP_K)
     ap.add_argument("--no-sources", action="store_true",
                     help="hide the citation block under each answer")
     ap.add_argument("--json", action="store_true", dest="as_json",
@@ -1336,26 +1338,33 @@ def _chat_session(args) -> int:
     assistant, and a long transcript encourages answering from the conversation
     rather than from what retrieval actually returned.
     """
-    if not ai.available():
+    have_ai = ai.available()
+    if not have_ai:
         # Worth saying up front rather than letting every answer look terse for
         # an unexplained reason.
         note = ("no AI configured — answers are the grounded matches "
                 "themselves (%s)" % ai.fallback_note())
         for line in out.wrap(note, max(out.term_width() - 2, 20)):
             out.info(out.role(line, "muted"))
-    out.info(out.role("ask about skills; blank line or Ctrl-D to exit", "muted"))
+    # With stdin piped nobody is typing, so the prompt and the typing hint are
+    # only chrome in the answers a script captures — the same rule
+    # output.confirm applies. A terminal is unchanged.
+    typing = sys.stdin.isatty()
+    if typing:
+        out.info(out.role("ask about skills; blank line or Ctrl-D to exit", "muted"))
     history: list[chat_engine.Turn] = []
     while True:
         try:
-            question = input("\n> ").strip()
+            question = input("\n> " if typing else "").strip()
         except (EOFError, KeyboardInterrupt):
-            out.info("")
+            if typing:
+                out.info("")    # end the prompt line the EOF left open
             return 0
         if not question:
             return 0
         reply = chat_engine.answer(question, history=history, k=args.limit)
         out.info("")
         _print_reply(reply, not args.no_sources)
-        history.append(chat_engine.Turn(question, reply.text))
-        for follow in chat_engine.suggest_followups(reply.skills)[:2]:
+        history.append(chat_engine.Turn(question, reply.text, reply.skills))
+        for follow in chat_engine.suggest_followups(reply.skills, with_ai=have_ai)[:2]:
             out.info(out.role("  try: %s" % follow, "muted"))

{boost_skill_cli-1.2.134 → boost_skill_cli-1.2.135}/boost_cli/commands/pkg.py

@@ -231,6 +231,7 @@ def _report_result(res: store.InstallResult, no_mcp: bool = False) -> None:
         where = " (this repo)" if res.scope == "project" else ""
         out.ok("materialized%s → %s"
                % (where, " · ".join(res.linked) or "(no enabled agents)"))
+        _warn_unwritable(res)
         out.ok("lock updated (.skill-lock.json)")
         _warn_injection(res)
         _warn_secrets(res)
@@ -258,8 +259,6 @@ def _report_result(res: store.InstallResult, no_mcp: bool = False) -> None:
     if res.native:
         out.ok("available to %s (reads the store directly)"
                % " · ".join(agents.display_name(a) for a in res.native))
-    for path in res.conflicts:
-        out.warn("not linked: %s exists and is not managed by boost" % _tilde(path))
     _warn_unwritable(res)
     out.ok("lock updated (.skill-lock.json)")
     _warn_injection(res)
@@ -268,13 +267,20 @@ def _report_result(res: store.InstallResult, no_mcp: bool = False) -> None:
 
 
 def _warn_unwritable(res) -> None:
-    """Name the remedy for each agent skills dir an install could not link
-    into — every path that installs, reinstall and update included, so none
-    reports success over a link it silently skipped."""
+    """Name what an install skipped, and the remedy — every path that
+    installs, reinstall and update included, so none reports success over an
+    agent it silently left out.
+
+    A conflict is a real file squatting a skill's link path. An unwritable dir
+    refused a link, or a rule or workflow file; the refused agent is still
+    recorded, so `boost sync` writes it once the dir allows it."""
+    for path in res.conflicts:
+        out.warn("not linked: %s exists and is not managed by boost" % _tilde(path))
+    what = ("not linked", "adds the link") if res.kind == "skill" else (
+        "not written", "writes it")
     for adir in res.unwritable:
-        out.warn("not linked: %s is not writable — `chmod u+w %s`, then "
-                 "`boost sync` adds the link" % (_tilde(adir), _tilde(adir)),
-                 wrap=True)
+        out.warn("%s: %s is not writable — `chmod u+w %s`, then `boost sync` %s"
+                 % (what[0], _tilde(adir), _tilde(adir), what[1]), wrap=True)
 
 
 def _boostfile_text(skills: dict[str, dict], via: str = "boost bundle dump") -> str:
@@ -776,7 +782,14 @@ def cmd_sync(argv: list[str]) -> int:
                  % (_plural(len(blocked), "agent link"),
                     ", ".join("%s → %s (%s in the way)"
                               % (n, a, _tilde(Path(p))) for n, a, p in blocked)))
-    if not actions and not pruned and not left and not oos and not blocked:
+    # A dir that refused a link or a file: sync wrote what it could and says
+    # what it could not, rather than "everything in sync" over it.
+    stuck = store.unwritable_agent_dirs()
+    for adir in stuck:
+        out.warn("agent dir %s is not writable — `chmod u+w %s`, then re-run "
+                 "`boost sync`" % (_tilde(adir), _tilde(adir)), wrap=True)
+    if (not actions and not pruned and not left and not oos and not blocked
+            and not stuck):
         out.ok("everything in sync")
     return 0
 
@@ -917,8 +930,10 @@ def _update_materialized(kind: str, installed: dict[str, dict], results) -> int:
             continue
         try:
             # keep the item where it was installed (user vs a specific repo).
-            store.install(entry, force=True,
-                          scope=lk.get("scope", "user"), base=lk.get("base"))
+            # A dir that refused the refresh is named here, as for a skill.
+            _warn_unwritable(store.install(
+                entry, force=True,
+                scope=lk.get("scope", "user"), base=lk.get("base")))
         except BoostError as err:
             out.warn("%s: %s" % (name, err.message))
             continue
@@ -1540,13 +1555,14 @@ def _bundle_install(file: str | None, dry_run: bool = False) -> int:
                 installed_n += 1
                 continue
             try:
-                store.install(entry)
+                res = store.install(entry)
             except BoostError as err:
                 out.warn("%s: %s" % (sname, err.message))
                 failed += 1
                 continue
             out.ok("installed %s v%s (%s)" % (sname, entry.get("version"),
                                               entry["tap"]))
+            _warn_unwritable(res)
             have_installed[sname] = (entry_kind, entry)
             installed_kinds.add(entry_kind)
             installed_n += 1

{boost_skill_cli-1.2.134 → boost_skill_cli-1.2.135}/boost_cli/commands/quality.py

@@ -597,9 +597,22 @@ def cmd_doctor(argv):
     quarantined_rules = len(all_rules) - len(rules)
     quarantined_workflows = len(all_workflows) - len(workflows)
     mat_issues = 0
+    for kind, section in (("rule", rules), ("workflow", workflows)):
+        for name, entry in sorted(section.items()):
+            for m in entry.get("materializations") or []:
+                if m.get("unwritable"):
+                    # Refused at install, so `boost reinstall` would be refused
+                    # too until the dir allows it; the agent-dir line below
+                    # names the `chmod`. Any file there predates the refusal.
+                    bad(kind, "%s %s was not written for %s: its dir was not "
+                        "writable — `boost sync` writes it once it is"
+                        % (kind, name, m.get("agent", "?")), wrap=True)
+                    mat_issues += 1
     for name, entry in sorted(rules.items()):
         for m in entry.get("materializations") or []:
             p = Path(m.get("path", ""))
+            if m.get("unwritable"):
+                continue
             if m.get("mode") == "claude":
                 try:
                     present = p.exists() and ("boost:rule:%s start" % name) in \
@@ -614,7 +627,7 @@ def cmd_doctor(argv):
                 mat_issues += 1
     for name, entry in sorted(workflows.items()):
         for m in entry.get("materializations") or []:
-            if not Path(m.get("path", "")).is_file():
+            if not m.get("unwritable") and not Path(m.get("path", "")).is_file():
                 bad("workflow", "workflow %s missing its %s file — run `boost reinstall %s`"
                     % (name, m.get("agent", "?"), name))
                 mat_issues += 1
@@ -689,16 +702,16 @@ def cmd_doctor(argv):
             % (dup.name, agents.display_name(dup.agent), _tilde(dup.path),
                _tilde(dup.target)), wrap=True)
 
-    # Linking agents only: a native-store agent's skills dir (Gemini's) is
-    # never written, so its permissions are not boost's problem and `boost
-    # sync` could not act on them.
-    for adir in agents.linking_agents().values():
-        if adir.is_dir() and not os.access(str(adir), os.W_OK):
-            # A next action, like the log line below it: without one this was
-            # the only issue doctor names that nothing can act on.
-            bad("agent-dir", "agent dir %s is not writable — `chmod u+w %s`, "
-                "then `boost sync` relinks what it missed"
-                % (_tilde(adir), _tilde(adir)), wrap=True)
+    # Every dir boost writes into: the linking agents' skills dirs, and the
+    # rules/ and commands/ dirs rules and workflows materialize into. Not a
+    # native-store agent's skills dir (Gemini's): boost never writes it, and
+    # `boost sync` could not act on it.
+    for adir in store.unwritable_agent_dirs():
+        # A next action, like the log line below it: without one this was
+        # the only issue doctor names that nothing can act on.
+        bad("agent-dir", "agent dir %s is not writable — `chmod u+w %s`, "
+            "then `boost sync` writes what it missed"
+            % (_tilde(adir), _tilde(adir)), wrap=True)
 
     rotation = journal.rotation_healthy()
     if not rotation:
@@ -1254,8 +1267,7 @@ def cmd_heal(argv):
                  % cfg_err, wrap=True)
     # Permissions are the user's to change, not heal's; but a dir heal saw and
     # cannot fix must not sit under an all-clear.
-    stuck = [adir for adir in agents.linking_agents().values()
-             if adir.is_dir() and not os.access(str(adir), os.W_OK)]
+    stuck = store.unwritable_agent_dirs()
     for adir in stuck:
         out.warn("agent dir %s is not writable — heal does not change "
                  "permissions; run `chmod u+w %s`, then `boost sync`"

{boost_skill_cli-1.2.134 → boost_skill_cli-1.2.135}/boost_cli/commands/team.py

@@ -28,7 +28,7 @@ from ..core import (
 from ..core import output as out
 from ..errors import BoostError
 from ._common import _s
-from .pkg import _report_result
+from .pkg import _report_result, _warn_unwritable
 
 _tilde = paths.tilde
 
@@ -202,6 +202,7 @@ def cmd_cohort(argv) -> int:
                 res = store.install(entry)
                 if not args.json:
                     out.ok("installed %s → %s" % (skill, " · ".join(res.linked)))
+                    _warn_unwritable(res)
                 installed_here.append(skill)
                 applied += 1
             per_cohort.append({"cohort": cname, "member": True,
@@ -462,6 +463,7 @@ def cmd_profile(argv) -> int:
         res = store.install(entry)
         if not args.json:
             out.ok("installed %s → %s" % (n, " · ".join(res.linked)))
+            _warn_unwritable(res)
         installed_now.append(n)
     for n in changed:
         # Mirrors `diff`'s "~ NAME (version differs)" — `use` used to discard
@@ -880,6 +882,8 @@ def cmd_replay(argv) -> int:
                          % (n, entry.get("version"), want.get("version")))
         elif not args.json:
             out.ok("restored %s → %s" % (n, " · ".join(res.linked)))
+        if not args.json:
+            _warn_unwritable(res)
         restored.append(n)
     for n in changed:
         if not args.json:

{boost_skill_cli-1.2.134 → boost_skill_cli-1.2.135}/boost_cli/core/chat.py

@@ -76,10 +76,17 @@ _SYSTEM = (
 
 
 class Turn(NamedTuple):
-    """One exchange, kept so a follow-up can refer back to it."""
+    """One exchange, kept so a follow-up can refer back to it.
+
+    ``skills`` is what the answer drew on, in the order it was shown. A
+    follow-up like "which of these should I install first?" points at exactly
+    that list, and the list cannot be rebuilt from the question — re-querying
+    the catalogue with it retrieved skills the user had never been shown.
+    """
 
     question: str
     answer: str
+    skills: Sequence[dict] = ()
 
 
 class Reply(NamedTuple):
@@ -131,11 +138,149 @@ def expand_query(question: str, history: Sequence[Turn]) -> str:
     if not history:
         return question
     # Long questions carry their own context; short ones are the follow-ups.
+    # This is also the fresh search a pointer ("which of these…") runs
+    # alongside the rows it points at, so it must stay the query main sends:
+    # that is what keeps a misread pointer from losing main's answer.
     if len(question.split()) > 6:
         return question
     return "%s %s" % (history[-1].question, question)
 
 
+# Phrases that point back at the list the previous answer showed. Kept narrow,
+# though a false match now costs order rather than the answer (see
+# :func:`retrieve`): "those flaky tests" is a new subject, "those skills" is a
+# reference; "which one is best for linting?" asks the catalogue, "which one of
+# these" asks the list; "the other SKILL.md field" is a new subject, "from the
+# others" is not; "this one-liner" and "best of both worlds" are English.
+_REFERS = re.compile(
+    r"\b(?:(?:of|between|among|from|compare)\s+(?:these|those|them)"
+    r"|(?:of|between|among|from|than|to|about|vs\.?|versus|compared?)\s+the\s+others"
+    r"|(?:these|those)\s+(?:ones?|skills?|options?|results?|matches)"
+    r"|(?:that|this)\s+one\b(?!-))\b", re.IGNORECASE)
+
+# "the second one", "the 2nd skill?" — one row of the previous list. The
+# ordinal needs a pointer in front ("the", "that", "this", or nothing but the
+# ordinal in the whole question): "my first skill" is a new subject. With a
+# noun rather than "one" it must also end the clause, because "the last skill I
+# should install for linting" is a new question that happens to say "the last",
+# and "one" must not start a compound: "the first one-shot prompt".
+_ORDINAL = re.compile(
+    r"(?:\b(?:the|that|this)\s+|^\W*(?:and\s+)?)"
+    r"(?P<word>first|second|third|fourth|fifth|last|1st|2nd|3rd|4th|5th)\s+"
+    r"(?:one\b(?!-)|(?:skill|option|result|match)\b(?=\s*(?:[?.!,;]|$)))",
+    re.IGNORECASE)
+
+# "#3", "number 2" — only where a row number can stand: the whole question, a
+# question that opens "and #3" / "is number 1", or after a verb or preposition
+# that takes one ("about #3", "try #2"). "is", "and" and "or" count only at the
+# start: mid-question they join numbers that count something else ("which
+# skill is #1 for security?", "PRs #2 and #3").
+_ROW_NUMBER = re.compile(
+    r"(?:^\W*(?:(?:and|or|is)\s+)?|\b(?:about|try|install|use|pick|choose|vs|than|with)\s+)"
+    r"(?:#\s*|number\s+)(?P<n>\d+)\b", re.IGNORECASE)
+# A number after one of these numbers that thing, and so does every number in
+# a question that has one: "compare PR #2 with #3" is two pull requests.
+_TRACKED = re.compile(
+    r"\b(?:prs?|pull\s+requests?|issues?|bugs?|tickets?)\s*(?:#\s*|number\s+)?\d",
+    re.IGNORECASE)
+_ORDINALS = {"first": 1, "second": 2, "third": 3, "fourth": 4, "fifth": 5,
+             "1st": 1, "2nd": 2, "3rd": 3, "4th": 4, "5th": 5}
+
+
+def _row_number(question: str) -> int | None:
+    """The row a "#N" / "number N" in ``question`` names, if it names one."""
+    if _TRACKED.search(question):
+        return None
+    m = _ROW_NUMBER.search(question)
+    return int(m.group("n")) if m else None
+
+
+def is_referential(question: str) -> bool:
+    """Whether ``question`` points back at the previous answer's list."""
+    return bool(_REFERS.search(question) or _ORDINAL.search(question)
+                or _row_number(question) is not None)
+
+
+def referenced(question: str, previous: Sequence[dict]) -> list[dict] | None:
+    """The previous answer's rows if ``question`` points at them, else None.
+
+    An ordinal or a row number moves its row to the front, numbered as the
+    answer numbered it, and keeps the others after it: the pointer might be a
+    misreading, and the rest of the list costs nothing to keep. A word ordinal
+    past the end still points at the list. A number past the end does not:
+    "what about #42?" is not a row of five, and gets an ordinary search.
+    """
+    if not previous or not is_referential(question):
+        return None
+    word = _ORDINAL.search(question)
+    number = _row_number(question)
+    if word:
+        w = word.group("word").lower()
+        n = len(previous) if w == "last" else _ORDINALS[w]
+    elif number is not None:
+        n = number
+    else:
+        return list(previous)
+    if 1 <= n <= len(previous):
+        return [previous[n - 1], *previous[:n - 1], *previous[n:]]
+    # Past the end, a word ordinal still points at the list; a number numbers
+    # something else unless the question also points back.
+    if word or _REFERS.search(question):
+        return list(previous)
+    return None
+
+
+def _name(entry: dict) -> str:
+    return str(entry.get("name", "")).lower()
+
+
+def _row(entry: dict) -> tuple:
+    """Row identity (``rag.entry_key``'s fields), tolerant of synthesised rows.
+
+    Equality rather than ``is``: the previous turn's rows and this turn's hits
+    can be equal dicts from two catalogue loads, and must not be listed twice.
+    """
+    return (entry.get("tap"), entry.get("skill_md"), entry.get("name"))
+
+
+def promote_named(question: str, ranked: Sequence[dict],
+                  previous: Sequence[dict] = (),
+                  catalogue: Sequence[dict] = ()) -> list[dict]:
+    """``ranked`` with any skill the question names moved to the front.
+
+    Asking "what does orch-review actually do?" is a lookup, and a ranker can
+    score a sibling that repeats the query terms above the skill it names — the
+    audit saw ``orch-refine-code`` outrank ``orch-review`` for exactly that
+    question. A name counts when it is catalogue-shaped (hyphenated), or when
+    it is any word naming a skill the previous answer showed: "teach" in an
+    arbitrary question is English, but not right after the user was shown a
+    skill called ``teach``.
+
+    For each name the row the user was just shown wins, then the best-ranked
+    hit, then the catalogue — so a name several taps carry resolves to the one
+    the conversation is about. Namesakes are kept, ranked after.
+    """
+    shown = {_name(e) for e in previous}
+    words = re.findall(r"[a-z0-9][a-z0-9-]*[a-z0-9]|[a-z0-9]", question.lower())
+    # dict.fromkeys: each name once, in the order the question gives them.
+    names = dict.fromkeys(w for w in words if _TOKEN.fullmatch(w) or w in shown)
+    pools = (previous, ranked, catalogue)
+    found = (next((e for pool in pools for e in pool if _name(e) == n), None)
+             for n in names)
+    front = [e for e in found if e is not None]
+    placed = {_row(e) for e in front}
+    return front + [e for e in ranked if _row(e) not in placed]
+
+
+def _search(query: str, k: int, entries: list[dict]) -> tuple[list[dict], str]:
+    """The top ``k`` for ``query`` from whichever engine the machine has."""
+    hits, engine = rag.retrieve_any(query, k=k, entries=entries)
+    if hits is None:
+        # No index of any kind: catalog.search is the documented floor.
+        return [e for e, _score in catalog.search(query)[:k]], "frontmatter scan"
+    return [h["entry"] for h in hits[:k]], engine
+
+
 def retrieve(question: str, history: Sequence[Turn] = (),
              k: int = TOP_K) -> tuple[list[dict], str]:
     """Candidate catalogue entries for ``question``, best first.
@@ -144,15 +289,39 @@ def retrieve(question: str, history: Sequence[Turn] = (),
     gets whatever the machine has — hybrid, dense, or BM25 — rather than pinning
     an engine of its own, and falls back to the frontmatter scan when no index
     exists at all so a fresh install still answers.
+
+    A follow-up that points back at the previous answer ("which of these…",
+    "the second one") leads with that answer's rows, the row it names first:
+    the audit measured "which of these should I install first?" coming back
+    with nothing from the turn before. It never *replaces* the search, though.
+    The same search runs, and its results follow the carried rows, so a
+    question misread as a pointer ("this one-liner", "PRs #2 and #3") loses
+    order, not the answer. That makes such a turn longer than ``k``: ``k``
+    carried rows (plus any the question names that fell past ``k``), then a
+    skill named but never shown, then the search's ``k``.
+
+    A skill the question names is ranked first on an ordinary search, and may
+    come from the catalogue: "is pre-commit better than those skills?" names a
+    skill the list never showed, and an answer about it is only grounded if
+    it is among the sources. On a pointer it goes after the carried rows,
+    which are what the question is about.
     """
-    query = expand_query(question, history)
+    previous = list(history[-1].skills) if history else []
     entries = catalog.all_entries()
-    hits, engine = rag.retrieve_any(query, k=k, entries=entries)
-    if hits is None:
-        # No index of any kind: catalog.search is the documented floor.
-        scored = catalog.search(query)
-        return [e for e, _score in scored[:k]], "frontmatter scan"
-    return [h["entry"] for h in hits[:k]], engine
+    found, engine = _search(expand_query(question, history), k, entries)
+    carried = referenced(question, previous)
+    if carried is None:
+        return promote_named(question, found, previous, entries)[:k], engine
+    head = carried[:k]
+    # Search hits before the rest of the catalogue, so a name several taps
+    # carry resolves to the copy the search ranked.
+    lead = promote_named(question, head, previous, [*found, *entries])
+    shown = {_row(e) for e in previous}
+    placed = {_row(e) for e in lead}
+    return ([e for e in lead if _row(e) in shown]
+            + [e for e in lead if _row(e) not in shown]
+            + [e for e in found if _row(e) not in placed],
+            "previous answer + %s" % engine)
 
 
 # Catalogue descriptions are untrusted upstream text and some are enormous:
@@ -389,19 +558,26 @@ def citations(entries: Sequence[dict]) -> list[dict[str, str]]:
     return out
 
 
-def suggest_followups(entries: Sequence[dict]) -> list[str]:
+def suggest_followups(entries: Sequence[dict], with_ai: bool = True) -> list[str]:
     """Concrete next questions, drawn from what was actually retrieved.
 
     Generic prompts ("ask me anything!") teach nothing; naming a real retrieved
     skill shows the user the shape of a question that works.
+
+    ``with_ai=False`` offers only what the extractive answer can answer: a
+    lookup of one named skill, which :func:`promote_named` puts first. A
+    comparison or a "which first" needs prose that path does not write, so
+    suggesting one invites a question whose answer is the same list again.
     """
     if not entries:
-        return ["what skills do I have installed?"]
+        return ["what skills do I have installed?"] if with_ai else []
     top: dict | None = entries[0]
     name = str(top.get("name", "")) if top else ""
     out: list[str] = []
     if name:
-        out.extend(("what does %s actually do?" % name,
-                    "how is %s different from the others?" % name))
-    out.append("which of these should I install first?")
+        out.append("what does %s actually do?" % name)
+    if with_ai:
+        if name:
+            out.append("how is %s different from the others?" % name)
+        out.append("which of these should I install first?")
     return out