@browserstack/mcp-server 1.5.0-beta.2 → 1.5.0-beta.20

package/dist/tools/capability-registry/search.d.ts

@@ -18,6 +18,14 @@ import { Capability, Mode, ProductIndex } from "./types.js";
  * camelCase is split before lowercasing, so `testRunId`, `test_run_id` and `test run id`
  * all tokenize alike.
  */
+/**
+ * Is this the browse wildcard rather than a search?
+ *
+ * Accepts `*` and `all` — both are what a caller reaches for when the intent is "show me
+ * everything", and treating only one of them as the wildcard means the other silently
+ * becomes a bad search. Whitespace is tolerated so a pasted value still works.
+ */
+export declare function isBrowseQuery(query?: string): boolean;
 export declare function terms(text: string | undefined): string[];
 /**
  * A term plus its naive singular variants.
@@ -29,6 +37,21 @@ export declare function terms(text: string | undefined): string[];
  * for no additional match.
  */
 export declare function termForms(term: string): string[];
+/**
+ * ONE canonical spelling of a word, so two spellings of a noun cannot look like two terms.
+ *
+ * `termForms` is deliberately generous — it offers every candidate and lets substring
+ * containment sort them out. Canonicalising needs the opposite: exactly one answer, and
+ * the right one. Taking the SHORTEST candidate is what a first cut did, and it folded
+ * `cases` to `cas`, so the vocabulary entry `test case` matched no query containing "test
+ * cases" — the phrase it exists for. The ambiguity check then fell through to `test`
+ * alone, reaching the right verdict by the wrong route.
+ *
+ * Strip `es` only after a sibilant, where English actually inserts it (`boxes`,
+ * `batches`, `statuses`). Otherwise strip the single `s`, which is right for the `-e`
+ * plurals this vocabulary is full of: case, suite, phase, template.
+ */
+export declare function singular(word: string): string;
 export declare function modeHint(query: string | undefined): "" | Mode;
 export declare function wantsCollection(query: string | undefined): boolean;
 /**
@@ -36,8 +59,9 @@ export declare function wantsCollection(query: string | undefined): boolean;
  *
  * Pagination is the reliable signal — a paged operation is a listing by construction. The
  * plural terminal path segment is a weaker fallback for unpaged collections. (The Python
- * side used the capability NAME here; the artifact publishes no name, and the path's own
- * terminal noun carries the same signal because operationIds were derived from it.)
+ * side used the capability NAME here. tm now publishes one, but its verbs are not
+ * consistent — the endpoint that lists folders is `get_root_folders_v1` — so the path's
+ * terminal noun remains the better signal.)
  */
 export declare function isCollection(capability: Capability): boolean;
 /**
@@ -45,7 +69,7 @@ export declare function isCollection(capability: Capability): boolean;
  *
  * Attribution is not decoration: the response tables are per product, so dereferencing a
  * hit's schemas needs to know whose tables to read. It is also what lets a caller pass
- * `product` to invokeEndpoint when two products share an endpoint — until now search
+ * `product` to invokeCapability when two products share an endpoint — until now search
  * ranked across products and then threw away the only thing that could disambiguate them.
  */
 export interface SearchHit {
@@ -56,10 +80,91 @@ export interface SearchResult {
     hits: SearchHit[];
     truncated: boolean;
     total_matched: number;
+    /**
+     * Where this page started, and where the next one begins.
+     *
+     * `truncated` has always said more matched than fit; nothing said how to reach it, so
+     * the only way past the first page was to raise `limit` and re-read everything already
+     * seen. `next_offset` is absent on the last page, which is what makes "walk until it
+     * stops" terminate without the caller comparing counts.
+     */
+    offset: number;
+    next_offset?: number;
+    /** True when the query was the browse wildcard rather than a search. */
+    browse?: boolean;
+    /**
+     * The best pre-penalty term score, and whether it is weak enough to doubt.
+     *
+     * A vocabulary miss does NOT look like a miss from the outside: "make a new bucket for my
+     * tests" returns a full page of eight confident hits, exactly like a query that worked,
+     * because containment finds *something* for `make`, `new` and `tests`. The only thing that
+     * separates them is how little the match is worth.
+     */
+    top_matched: number;
+    /** `top_matched` as a fraction of a perfect match — the corpus-independent form. */
+    coverage: number;
+    weak: boolean;
+}
+/** Which products a query could plausibly be about, when more than one could. */
+export interface ProductAmbiguity {
+    /** The products that claim the query's words. Empty when the query settles itself. */
+    products: string[];
+    /** The shared vocabulary that caused it — what to put in front of the user. */
+    terms: string[];
 }
+/**
+ * Products whose OWN vocabulary the query hits, when no word in the query settles it.
+ *
+ * Requiring `product` made every CALL unambiguous and did nothing about the agent making
+ * two of them: "list all projects" was answered by searching tm, then Load Testing, then
+ * merging — a question about which product the user meant, answered by guessing both.
+ * Tool-description prose asking the agent to check with the user is a suggestion it is
+ * free to decline, and declining is cheaper than interrupting someone.
+ *
+ * WHOLE VOCABULARY ENTRIES, never their constituent words. Splitting them makes almost
+ * everything look shared: Load Testing's "load test" and tm's "test case" both yield
+ * `test`, which flagged 135 of the 198 eval queries. Matching entries whole flags 27.
+ *
+ * A UNIQUE TERM SETTLES IT. "create a test case in a folder" contains `folder`, which
+ * both products claim, and `test case`, which only tm does — so the query has already
+ * answered the question and there is nothing to ask. Only queries whose every recognised
+ * word is shared are genuinely undecided.
+ */
+export declare function ambiguousProducts(products: Record<string, ProductIndex>, query: string | undefined): ProductAmbiguity;
+/** One entity's caller-facing vocabulary: what it is called, and what else it is called. */
+export interface VocabularyEntry {
+    entity: string;
+    description?: string;
+    aliases?: string[];
+}
+/**
+ * The product's vocabulary, for a caller whose words are not the product's words.
+ *
+ * THE ONE FAILURE LEXICAL SEARCH CANNOT FIX. "make a new bucket for my tests" wants the
+ * folder-create capability, and `bucket` appears nowhere in the index — no scoring change
+ * reaches it, because the word is simply absent. What CAN reach it is the caller: it is a
+ * language model, and given tm's entity list it maps bucket -> folder without effort. It
+ * just cannot guess the list unprompted.
+ *
+ * Aliases and a one-line `description`; `title` stays dropped as a near-duplicate of
+ * `entity` ("Test run" next to `test_run` buys nothing). Aliases alone route but do not
+ * DEFINE — `result -> outcome, execution-result, test-result` never says whether that is
+ * the per-case verdict inside a run or a run-level rollup — so an agent holding names and
+ * aliases has exactly one way to find out, which is describeEntity once per entity. For
+ * tm that is 19 calls at ~1.4KB each, ~27KB, to answer what ~1.6KB of description answers
+ * here for every entity at once. The `key_facts` remain out: ten times the size, and the
+ * caller can ask describeEntity for the one entity it settles on.
+ *
+ * Its share of the response grew when search became a shortlist: 3.2KB against a 38KB full
+ * search was 8%, against a 6.8KB shortlist it is nearly half. The absolute cost did not
+ * change and is still under a thousand tokens — far less than one wrong invoke — so this
+ * is budgeted in bytes rather than as a fraction of a baseline that now moves.
+ */
+export declare function vocabularyOf(products: Record<string, ProductIndex>, only?: string): Record<string, VocabularyEntry[]>;
 export declare function searchCapabilities(products: Record<string, ProductIndex>, query?: string, options?: {
     entity?: string;
     product?: string;
     mode?: Mode;
     limit?: number;
+    offset?: number;
 }): SearchResult;

package/dist/tools/capability-registry/search.js

@@ -16,7 +16,7 @@
  *
  * `_` used to be a word character, which made `test_case` a single token while every
  * haystack rendered it as "test case" — so the two could never match. That is the exact
- * string `listEntities` hands back, so a caller following the documented flow searched with
+ * string `listProducts` hands back, so a caller following the documented flow searched with
  * a term guaranteed to score zero: "list test_runs" matched 19 capabilities and put an
  * admin settings endpoint first, where "list test runs" matched 103 and put the test-runs
  * listing first.
@@ -111,6 +111,17 @@ const PLURAL_INTENT = new Set([
  * camelCase is split before lowercasing, so `testRunId`, `test_run_id` and `test run id`
  * all tokenize alike.
  */
+/**
+ * Is this the browse wildcard rather than a search?
+ *
+ * Accepts `*` and `all` — both are what a caller reaches for when the intent is "show me
+ * everything", and treating only one of them as the wildcard means the other silently
+ * becomes a bad search. Whitespace is tolerated so a pasted value still works.
+ */
+export function isBrowseQuery(query) {
+    const q = (query || "").trim().toLowerCase();
+    return q === "*" || q === "all";
+}
 export function terms(text) {
     return [
         ...(text || "")
@@ -145,6 +156,36 @@ export function termForms(term) {
         add(term.slice(0, -1));
     return forms;
 }
+/**
+ * ONE canonical spelling of a word, so two spellings of a noun cannot look like two terms.
+ *
+ * `termForms` is deliberately generous — it offers every candidate and lets substring
+ * containment sort them out. Canonicalising needs the opposite: exactly one answer, and
+ * the right one. Taking the SHORTEST candidate is what a first cut did, and it folded
+ * `cases` to `cas`, so the vocabulary entry `test case` matched no query containing "test
+ * cases" — the phrase it exists for. The ambiguity check then fell through to `test`
+ * alone, reaching the right verdict by the wrong route.
+ *
+ * Strip `es` only after a sibilant, where English actually inserts it (`boxes`,
+ * `batches`, `statuses`). Otherwise strip the single `s`, which is right for the `-e`
+ * plurals this vocabulary is full of: case, suite, phase, template.
+ */
+export function singular(word) {
+    if (word.endsWith("ss"))
+        return word;
+    // histories -> history. Without this the alias `histories` and the entity word
+    // `history` are two unrelated terms, which is the same defect in another spelling.
+    if (word.endsWith("ies") && word.length > 4)
+        return `${word.slice(0, -3)}y`;
+    // Only where the `e` is genuinely inserted. `s` is NOT in this set: `cases` ends in
+    // `ses` and is `case` + `s`, not `cas` + `es`, and no rule can tell it from `statuses`
+    // by suffix alone — so the commoner reading wins and `-s` is stripped below.
+    if (/(?:ch|sh|x|z)es$/.test(word))
+        return word.slice(0, -2);
+    if (word.endsWith("s") && word.length > 3)
+        return word.slice(0, -1);
+    return word;
+}
 /** A haystack as one lowercased, space-separated string, ready for containment tests. */
 function haystack(text) {
     return terms(text).join(" ");
@@ -165,8 +206,9 @@ export function wantsCollection(query) {
  *
  * Pagination is the reliable signal — a paged operation is a listing by construction. The
  * plural terminal path segment is a weaker fallback for unpaged collections. (The Python
- * side used the capability NAME here; the artifact publishes no name, and the path's own
- * terminal noun carries the same signal because operationIds were derived from it.)
+ * side used the capability NAME here. tm now publishes one, but its verbs are not
+ * consistent — the endpoint that lists folders is `get_root_folders_v1` — so the path's
+ * terminal noun remains the better signal.)
  */
 export function isCollection(capability) {
     if (capability.paginated)
@@ -177,6 +219,26 @@ export function isCollection(capability) {
     const tail = segments[segments.length - 1] || "";
     return tail.endsWith("s") && !tail.endsWith("ss");
 }
+/**
+ * Does this capability's mode answer what the caller asked to DO?
+ *
+ * `destructive` counts as a write. It has to: `modeHint` reads "delete" and "remove" as
+ * WRITE verbs, but a delete endpoint's mode is `destructive`, so a strict equality check
+ * penalised every destructive capability by 20 FOR BEING A DELETE — on exactly the queries
+ * that wanted one. "bulk delete test cases" scored 15.8 on terms, the highest of any missed
+ * query in the eval, and still fell out of the top 8.
+ *
+ * That accounted for 15 of the eval's 36 misses. The mode hint exists to separate reading
+ * from changing; destructive is changing.
+ *
+ * A read hint still refuses destructive, which is the useful half: "show me the test plans"
+ * must not surface a delete.
+ */
+function satisfiesHint(mode, hint) {
+    if (hint === "write")
+        return mode === "write" || mode === "destructive";
+    return mode === hint;
+}
 /** Everything a caller might say that lives on a parameter rather than in the prose. */
 function parameterText(capability) {
     const parts = [];
@@ -195,7 +257,49 @@ function parameterText(capability) {
     }
     return parts.join(" ");
 }
-/** Path words stand in for the capability name as the identity haystack. */
+/**
+ * Path words are the identity haystack. The published `name` is deliberately NOT scored.
+ *
+ * That is a measured result, not an oversight. tm now names every capability, and adding
+ * the name to the ranking was tried three ways against tests/fixtures/search-eval.json,
+ * which the pre-names index serves 18/18:
+ *
+ *   folded into this field, weight 6          17/18
+ *   its own field, weights 1 / 2 / 3 / 4 / 6  17 / 17 / 17 / 17 / 16
+ *   only the words the path lacks, 1..6       17 / 16 / 15 / 15 / 14
+ *
+ * Every variant loses, for two reasons. The nouns in a name are the route restated — the
+ * name is snake-cased from the operationId, itself derived from the path — so scoring them
+ * again rewards verbose names for repeating themselves: `get_test_cases_for_v1_test_run`
+ * displaced `create_test_result_for_test_case` on "record a pass or fail for a test case in
+ * a run", putting a read above the write that answers it. And what a name adds beyond the
+ * route is mostly its verb, which tm applies inconsistently (`get_root_folders_v1` lists,
+ * `list_folder_test_cases_v1` also lists), so the verb is noise as often as signal.
+ *
+ * The query this was meant to fix, "list all projects", only went 7 -> 4 even where it
+ * helped: `projects` is in 156 of 173 paths as a scope prefix, so rarity correctly values it
+ * near zero and no amount of name weighting recovers it. That one is fixed instead by the
+ * terminal-segment bonus in `score`, which tells "is that thing" from "is scoped by it".
+ *
+ * Revisit when a product ships a consistent verb convention — then the verb becomes signal.
+ */
+/**
+ * The terminal path segment — the thing this endpoint is actually ABOUT.
+ *
+ * A REST path mixes two different things: the resources it is SCOPED BY, and the resource it
+ * ADDRESSES. Only the last segment is the latter. See the bonus in `score` for why that
+ * distinction matters and why it is applied flat rather than weighted.
+ *
+ * Trailing placeholders are skipped, so `/test-cases/{id}` is still about test cases.
+ * Action tails (`close`, `edit`, `delete`) are kept rather than skipped: for "close a test
+ * run" the tail IS the most specific thing the caller said.
+ */
+function resourceText(capability) {
+    const segments = capability.path
+        .split("/")
+        .filter((s) => s && !s.startsWith("{") && s !== "api");
+    return (segments[segments.length - 1] || "").replace(/[-_]/g, " ");
+}
 function identityText(capability) {
     return capability.path
         .split("/")
@@ -225,11 +329,56 @@ function rarity(documents, forms) {
     const total = documents.length || 1;
     return Math.log((total + 1) / (df + 1)) / Math.log(total + 1);
 }
+/**
+ * Sized to sit alongside the mode (+6) and cardinality (+8) constants, not to dwarf them.
+ * The pinned eval is unchanged at every value from 2 to 14 — the bonus only ever fires on
+ * queries it does not cover — so this was chosen on the wider sweep: at 10, "close a test
+ * run" starts pulling `close_exploratory_session` into second place on the tail match alone.
+ */
+const RESOURCE_BONUS = 6;
+/**
+ * How much a cardinality guess is worth. It used to be 8, and it should not have been.
+ *
+ * `isCollection` is a GUESS read off the URL, and the index carries nothing better: of 88
+ * read capabilities, zero declare an array in their response schema, and `paginated` — the
+ * one signal that looks trustworthy — is true for `get_report_detail`, a single-record
+ * endpoint. There is no derived cardinality in this artifact to appeal to.
+ *
+ * At ±8 that guess swung 16 points and buried 11 correct answers: `/test-runs/closed` and
+ * `/{entity}/search` are listings whose last path segment is not a plural noun, `users-v2`
+ * is plural with a version suffix in the way, and the count endpoints answer "how many"
+ * with a scalar. All were penalised for what they are called.
+ *
+ * The fix is not a better classifier — a qualifier word-list would encode tm's route
+ * conventions into generic code and rot on the next product. It is to stop betting so much
+ * on an unreliable signal. Swept against the eval, holding top1 at 138 with no ceiling
+ * violations: ±7 retires 1, ±6 retires 2, ±5 retires 5, ±4 retires 6. Below that it starts
+ * costing more than it returns — ±3.5 retires 8 but breaks a case, ±3 breaks two.
+ */
+const CARDINALITY = 4;
+/**
+ * The mode penalty stays at 20, unlike the cardinality one — it is earned.
+ *
+ * Where `isCollection` is a guess off the URL, `modeHint` is measured right: across the
+ * eval it agrees with the correct answer's mode 125 times and disagrees 3. A signal that
+ * accurate deserves to be decisive.
+ *
+ * Sweeping it 20 -> 6 retires none of the three misses filed against it and regresses
+ * nothing, which says the penalty is not what holds them back. It isn't: they sit at ranks
+ * 41, 62 and 78 of the matched set, far below anything a constant could lift. All three
+ * are vocabulary gaps wearing a mode-penalty label — "what gets removed" wants a path
+ * spelled `rm-summary`, "get rid of" wants `delete`, and "the option set" wants what the
+ * product calls a `dataset`. The target barely matches on TERMS; the hint is incidental.
+ *
+ * Left at 20 deliberately. There was no evidence for moving it, and an unjustified constant
+ * is how this scorer got into trouble in the first place.
+ */
+const MODE_PENALTY = 20;
 function score(capability, wanted, weights, aliases, hint, plural) {
     if (wanted.length === 0)
         return { matched: 1, ranked: 1 };
     const haystacks = [
-        [identityText(capability), 6],
+        [identityText(capability), IDENTITY_WEIGHT],
         [capability.entity, 4],
         [(aliases[capability.entity] || []).join(" "), 4],
         [capability.intent || "", 2],
@@ -273,16 +422,220 @@ function score(capability, wanted, weights, aliases, hint, plural) {
         }
     }
     const matched = ranked;
-    if (hint && capability.mode !== hint)
-        ranked -= 20;
-    else if (hint && capability.mode === hint)
-        ranked += 6;
+    // THE ENDPOINT IS THAT THING, not merely scoped by it.
+    //
+    // A REST path mixes the resources it is SCOPED BY with the one it ADDRESSES. `projects` is
+    // in 156 of tm's 173 paths but is the terminal segment in 3, so whole-corpus rarity —
+    // correctly — values it near nothing, and every project-scoped listing scored the same as
+    // the projects listing itself. The top 8 for "list all projects" spanned 15.9 to 14.8,
+    // where +8 collection and +6 mode already account for 14: the term signal was ~1 point of
+    // noise and the right answer sat 7th.
+    //
+    // Flat, and deliberately NOT rarity-scaled. Rarity would reintroduce the same problem in
+    // reverse — a rare scope noun outranking the real target, which is exactly how a weighted
+    // version of this put `/projects/{id}/folders` above `/folder/{id}/test-cases` for "tc list
+    // for a folder". This asks one yes/no question instead: is the caller's own word the last
+    // thing in the path?
+    //
+    // Equality is against the QUERY's forms, never the haystack's — the same one-directional
+    // rule as containment. `projects` is in forms("projects"), so the projects listing hits;
+    // `folders` is not in forms("folder"), so a folder-scoped query does not drag in the
+    // folders listing.
+    const tail = terms(resourceText(capability));
+    if (tail.length &&
+        wanted.some((forms) => tail.every((word) => forms.includes(word)))) {
+        ranked += RESOURCE_BONUS;
+    }
+    if (hint)
+        ranked += satisfiesHint(capability.mode, hint) ? 6 : -MODE_PENALTY;
     if (plural)
-        ranked += isCollection(capability) ? 8 : -8;
+        ranked += isCollection(capability) ? CARDINALITY : -CARDINALITY;
     return { matched, ranked };
 }
+/**
+ * How much of a perfect match the best hit actually achieved, below which we doubt it.
+ *
+ * A RATIO, because the raw score is corpus-relative and an absolute threshold therefore
+ * cannot travel. `rarity` is measured over whatever is being searched, so the same query
+ * scores differently depending on scope: "list my load tests" tops out at 1.9 against Load
+ * Testing alone and 10.1 against both products. The old absolute cut of 3 called the first
+ * of those weak and the second strong — the same query, the same right answer, opposite
+ * verdicts, with the smaller corpus penalised precisely because it is smaller.
+ *
+ * Both halves of this ratio move with the corpus, so it does not:
+ *
+ *     coverage = top_matched / (identity weight x Σ rarity of the query's terms)
+ *
+ * — "what fraction of a perfect identity match did the best hit manage". Above 1 is
+ * ordinary, since a good hit matches several fields, not just the route.
+ *
+ * Measured across tm-only, LT-only and both: genuine misses land at 0.00–0.18, queries
+ * that work at 0.44–1.94. The absolute score cannot separate those (misses reach 2.9,
+ * good queries drop to 1.9); this does, with the gap in the same place in all three
+ * corpora, which is the property that was missing.
+ *
+ * RECALIBRATED AT v1.14, and the reason matters more than the number. The ratio is
+ * corpus-relative and still is — "make a new bucket for my tests" scores 0.259 against tm
+ * alone and 0.258 against both products, which is the property this was built for. What
+ * moved is neither corpus size nor query: it is how much TEXT each capability carries.
+ * v1.13 gave all 242 entries guidance and tripled the length of `intent`, so the numerator
+ * — the best hit's term score — roughly doubled, while the denominator depends only on the
+ * rarity of the query's own terms and did not. Both bands shifted up together: genuine
+ * misses now land at 0.00–0.46 and working queries at 0.24–4.16.
+ *
+ * At the old 0.25 the hand-off had silently stopped firing — "bucket", which is nobody's
+ * word for a folder, came in at 0.259 and read as a confident answer. Re-measured over 173
+ * served eval cases against five queries the product has no words for, 0.50 catches 5 of 5
+ * while flagging 3 of 173 served queries (1.7%), which is the same trade the original cut
+ * made. Expect to move it again the next time the artifact's text volume changes; the
+ * threshold tracks prose per capability, not the number of capabilities.
+ */
+const WEAK_COVERAGE = 0.5;
+/** The heaviest field, and so the yardstick a perfect match is measured against. */
+const IDENTITY_WEIGHT = 6;
+/**
+ * Products whose OWN vocabulary the query hits, when no word in the query settles it.
+ *
+ * Requiring `product` made every CALL unambiguous and did nothing about the agent making
+ * two of them: "list all projects" was answered by searching tm, then Load Testing, then
+ * merging — a question about which product the user meant, answered by guessing both.
+ * Tool-description prose asking the agent to check with the user is a suggestion it is
+ * free to decline, and declining is cheaper than interrupting someone.
+ *
+ * WHOLE VOCABULARY ENTRIES, never their constituent words. Splitting them makes almost
+ * everything look shared: Load Testing's "load test" and tm's "test case" both yield
+ * `test`, which flagged 135 of the 198 eval queries. Matching entries whole flags 27.
+ *
+ * A UNIQUE TERM SETTLES IT. "create a test case in a folder" contains `folder`, which
+ * both products claim, and `test case`, which only tm does — so the query has already
+ * answered the question and there is nothing to ask. Only queries whose every recognised
+ * word is shared are genuinely undecided.
+ */
+export function ambiguousProducts(products, query) {
+    const none = { products: [], terms: [] };
+    if (terms(query).length === 0)
+        return none;
+    /**
+     * One spelling per word, so a plural cannot masquerade as a different term.
+     *
+     * Both halves need it. On the QUERY side, the entry is `project` and the user types
+     * "list all projects" — the reported case, which exact containment missed. On the
+     * VOCABULARY side the same fold is what keeps the answer honest: tm lists both `report`
+     * and `reports` as aliases, and treating them as two entries made `reports` look
+     * tm-exclusive, so "show me the report" read as settled when both products claim it.
+     */
+    const fold = (text) => terms(text).map(singular).join(" ");
+    const asked_ = ` ${fold(query || "")} `;
+    const owners = new Map();
+    for (const [product, entries] of Object.entries(vocabularyOf(products))) {
+        for (const entry of entries) {
+            for (const word of [entry.entity, ...(entry.aliases ?? [])]) {
+                const key = fold(String(word));
+                if (!key)
+                    continue;
+                if (!owners.has(key))
+                    owners.set(key, new Set());
+                owners.get(key).add(product);
+            }
+        }
+    }
+    const shared = new Map();
+    for (const [key, claimants] of owners) {
+        if (!asked_.includes(` ${key} `))
+            continue;
+        // A term only one product claims decides the query outright.
+        if (claimants.size < 2)
+            return none;
+        shared.set(key, claimants);
+    }
+    if (shared.size === 0)
+        return none;
+    const claimed = new Set();
+    for (const claimants of shared.values())
+        for (const product of claimants)
+            claimed.add(product);
+    return { products: [...claimed].sort(), terms: [...shared.keys()].sort() };
+}
+/**
+ * The product's vocabulary, for a caller whose words are not the product's words.
+ *
+ * THE ONE FAILURE LEXICAL SEARCH CANNOT FIX. "make a new bucket for my tests" wants the
+ * folder-create capability, and `bucket` appears nowhere in the index — no scoring change
+ * reaches it, because the word is simply absent. What CAN reach it is the caller: it is a
+ * language model, and given tm's entity list it maps bucket -> folder without effort. It
+ * just cannot guess the list unprompted.
+ *
+ * Aliases and a one-line `description`; `title` stays dropped as a near-duplicate of
+ * `entity` ("Test run" next to `test_run` buys nothing). Aliases alone route but do not
+ * DEFINE — `result -> outcome, execution-result, test-result` never says whether that is
+ * the per-case verdict inside a run or a run-level rollup — so an agent holding names and
+ * aliases has exactly one way to find out, which is describeEntity once per entity. For
+ * tm that is 19 calls at ~1.4KB each, ~27KB, to answer what ~1.6KB of description answers
+ * here for every entity at once. The `key_facts` remain out: ten times the size, and the
+ * caller can ask describeEntity for the one entity it settles on.
+ *
+ * Its share of the response grew when search became a shortlist: 3.2KB against a 38KB full
+ * search was 8%, against a 6.8KB shortlist it is nearly half. The absolute cost did not
+ * change and is still under a thousand tokens — far less than one wrong invoke — so this
+ * is budgeted in bytes rather than as a fraction of a baseline that now moves.
+ */
+export function vocabularyOf(products, only) {
+    const out = {};
+    for (const [name, bundle] of Object.entries(products)) {
+        if (only && name !== only)
+            continue;
+        const entries = [];
+        for (const [entity, doc] of Object.entries(bundle.entities || {})) {
+            const aliases = (doc.aliases || []);
+            const description = doc.description;
+            entries.push({
+                entity,
+                // Before the aliases, because it is what the reader needs first: what the thing
+                // is, then what else it is called.
+                ...(description ? { description } : {}),
+                ...(aliases.length ? { aliases } : {}),
+            });
+        }
+        if (entries.length)
+            out[name] = entries;
+    }
+    return out;
+}
 export function searchCapabilities(products, query, options = {}) {
     const limit = options.limit && options.limit > 0 ? options.limit : 8;
+    const offset = options.offset && options.offset > 0 ? Math.floor(options.offset) : 0;
+    // BROWSE MODE: `*` lists the product instead of searching it.
+    //
+    // Scoring keeps only capabilities with matched > 0, so there was no query that returned
+    // everything — an agent that wanted to see what exists had to guess words until the
+    // shortlist looked complete, and could never tell when it was. `*` skips scoring
+    // entirely and pages the filtered set in a STABLE order (name, then path), because a
+    // ranked order is not a safe thing to paginate: ranking is query-dependent and ties
+    // break arbitrarily, so page 2 of a ranked list can repeat or skip rows. Browse is
+    // ordered by identity, so offset means the same thing on every call.
+    if (isBrowseQuery(query)) {
+        const all = Object.entries(products)
+            .filter(([name]) => !options.product || name === options.product)
+            .flatMap(([name, bundle]) => bundle.capabilities
+            .filter((capability) => (!options.entity || capability.entity === options.entity) &&
+            (!options.mode || capability.mode === options.mode))
+            .map((capability) => ({ product: name, capability })))
+            .sort((a, b) => (a.capability.name || "").localeCompare(b.capability.name || "") ||
+            a.capability.path.localeCompare(b.capability.path));
+        const page = all.slice(offset, offset + limit);
+        const end = offset + page.length;
+        return {
+            hits: page,
+            truncated: end < all.length,
+            total_matched: all.length,
+            top_matched: 0,
+            coverage: 1,
+            weak: false,
+            offset,
+            ...(end < all.length ? { next_offset: end } : {}),
+            browse: true,
+        };
+    }
     // Forms are computed once per query, not per capability: 173 capabilities x 6 haystacks
     // would otherwise rebuild the same handful of strings a thousand times.
     const wanted = terms(query).map(termForms);
@@ -332,11 +685,25 @@ export function searchCapabilities(products, query, options = {}) {
         }
     }
     scored.sort((a, b) => b.ranked - a.ranked || a.capability.path.localeCompare(b.capability.path));
+    // Ranked order decides the page; the best TERM score decides confidence. They are
+    // different questions: the mode and cardinality constants can lift a weakly-matched
+    // capability to the top of a page that is entirely wrong.
+    const topMatched = scored.reduce((best, s) => Math.max(best, s.matched), 0);
+    // What a perfect identity match would have scored for THIS query in THIS corpus. Both
+    // this and `topMatched` scale with the corpus, so their ratio is comparable across
+    // products and across `product`/`entity` narrowing — which the raw score is not.
+    const perfect = weights.reduce((sum, w) => sum + IDENTITY_WEIGHT * w, 0);
+    const coverage = perfect > 0 ? topMatched / perfect : 1;
+    const page = scored.slice(offset, offset + limit);
+    const end = offset + page.length;
     return {
-        hits: scored
-            .slice(0, limit)
-            .map(({ product, capability }) => ({ product, capability })),
-        truncated: scored.length > limit,
+        hits: page.map(({ product, capability }) => ({ product, capability })),
+        truncated: end < scored.length,
         total_matched: scored.length,
+        offset,
+        ...(end < scored.length ? { next_offset: end } : {}),
+        top_matched: topMatched,
+        coverage,
+        weak: wanted.length > 0 && perfect > 0 && coverage < WEAK_COVERAGE,
     };
 }