gloomberb 0.17.2 → 0.17.3

package/src/cli/desktop-pane-shot.ts

@@ -60,9 +60,12 @@ export interface DesktopPaneShotPayload {
   statusLine?: boolean;
   /**
    * The tallest the capture may grow, in cells, to show every row its tables
-   * scroll past; absent keeps the requested height (`--height`, most panes).
+   * scroll past or all the text its reader scrolls past; absent keeps the
+   * requested height (`--height`, most panes).
    */
   maxHeightCells?: number;
+  /** The `data-gloom-role`s of the scrolling boxes the capture grows to fit; the tables' bodies when absent. */
+  fitRoles?: string[];
   tickers: TickerRecord[];
   /** Broker accounts as last synced, by profile, so a broker portfolio shows its equity and cash. */
   brokerAccounts?: Record<string, BrokerAccount[]>;
@@ -127,6 +130,12 @@ interface DesktopPaneShotSurface {
 
 export interface DesktopPaneShotRenderResult {
   visibleText: string;
+  /**
+   * The visible text a line per block of the page, as the browser lays it out,
+   * where `visibleText` has run them together: the words of a pane that is prose
+   * and not a table, to be read as paragraphs. Absent in a capture that did not read it.
+   */
+  visibleLines?: string[];
   /**
    * The rows a report reads, when a table reports every row (an option chain's
    * strike window) rather than those in the viewport; `rows` stays what the
@@ -222,7 +231,13 @@ export async function renderDesktopPaneScreenshot(
       userDataDir: join(tempDir, "chrome-profile"),
       captureImage: options.captureImage !== false,
       statusLine: payload.statusLine ? options.statusLine : undefined,
-      ...(payload.maxHeightCells ? { fitRows: { heightCells: payload.heightCells, maxHeightCells: payload.maxHeightCells } } : {}),
+      ...(payload.maxHeightCells ? {
+        fitRows: {
+          heightCells: payload.heightCells,
+          maxHeightCells: payload.maxHeightCells,
+          roles: payload.fitRoles ?? ["data-table-body-scroll"],
+        },
+      } : {}),
     });
   } finally {
     server?.stop(true);
@@ -458,7 +473,7 @@ async function capturePageScreenshot({
   userDataDir: string;
   captureImage: boolean;
   statusLine?: ShotStatusLine;
-  fitRows?: { heightCells: number; maxHeightCells: number };
+  fitRows?: { heightCells: number; maxHeightCells: number; roles: readonly string[] };
 }): Promise<DesktopPaneShotRenderResult> {
   await mkdir(userDataDir, { recursive: true });
   const port = 43000 + Math.floor(Math.random() * 10000);
@@ -531,9 +546,10 @@ async function capturePageScreenshot({
 }
 
 /**
- * Grows the viewport and the pane by the rows their tables scroll past, up to
- * `maxHeightCells`, then waits for the taller pane to settle: a board a
- * default capture would cut (FUT's last sectors) shows every row.
+ * Grows the viewport and the pane by the rows their tables scroll past, or the
+ * text a reader's body scrolls past, up to `maxHeightCells`, then waits for the
+ * taller pane to settle: a board a default capture would cut (FUT's last
+ * sectors) shows every row, and a docs page its whole text.
  */
 async function growToFitRows(session: CdpSession, size: {
   widthPx: number;
@@ -541,9 +557,11 @@ async function growToFitRows(session: CdpSession, size: {
   deviceScaleFactor: number;
   heightCells: number;
   maxHeightCells: number;
+  roles: readonly string[];
 }): Promise<void> {
+  const selector = size.roles.map((role) => `[data-gloom-role="${role}"]`).join(", ");
   const result = await session.send("Runtime.evaluate", {
-    expression: `Math.max(0, ...[...document.querySelectorAll('[data-gloom-role="data-table-body-scroll"]')]
+    expression: `Math.max(0, ...[...document.querySelectorAll(${JSON.stringify(selector)})]
       .map((element) => element.scrollHeight - element.clientHeight))`,
     returnByValue: true,
   }) as { result?: { value?: unknown } };
@@ -646,6 +664,7 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
         const table = element.closest('[data-gloom-role="data-table"]');
         return !!table && reportedTables.has(table);
       };
+      const managesRows = (element) => element.getAttribute("data-gloom-role") === "data-table-body-scroll";
       const markScrollTruncation = (element) => {
         if (!(element instanceof HTMLElement) || !isVisible(element)) return;
         const reasons = scrollReasons({
@@ -655,8 +674,10 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
           scrollLeft: element.scrollLeft,
           scrollWidth: element.scrollWidth,
           clientWidth: element.clientWidth,
-          scrollbarY: element.getAttribute("data-gloom-scrollbar-y") === "visible",
-          scrollbarX: element.getAttribute("data-gloom-scrollbar-x") === "visible",
+          // A scroll box draws its scrollbar by default and its content is all in the page, so its
+          // measures say what is cut; only a table's body holds rows it has not drawn.
+          scrollbarY: managesRows(element) && element.getAttribute("data-gloom-scrollbar-y") === "visible",
+          scrollbarX: managesRows(element) && element.getAttribute("data-gloom-scrollbar-x") === "visible",
         });
         reasons.forEach((reason) => truncationReasons.add(reason));
         if (!inReportedTable(element)) reasons.forEach((reason) => reportTruncationReasons.add(reason));
@@ -810,8 +831,12 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
   if (textShowsEllipsis && !truncationReasons.includes("one or more cells are visibly clipped")) {
     truncationReasons.push("one or more cells are visibly clipped");
   }
+  const visibleLines = (value?.visibleText ?? "").split("\n")
+    .map((line) => line.replace(/\u00a0/g, " ").trimEnd())
+    .filter((line) => line.trim().length > 0);
   return {
     visibleText,
+    visibleLines,
     footerText: typeof value?.footerText === "string" ? value.footerText : "",
     visibleKeyValues: Array.isArray(value?.visibleKeyValues) ? value.visibleKeyValues : [],
     ...(Array.isArray(value?.surfaces) && value.surfaces.length > 0 ? { surfaces: value.surfaces } : {}),

package/src/cli/fx-pair.ts

@@ -13,11 +13,28 @@ export interface FxRequest {
 
 const CURRENCY_CODE = /^[A-Z]{3}$/;
 
+let knownCurrencies: ReadonlySet<string> | undefined;
+
+/** An ISO 4217 code the runtime lists, or the offshore yuan it has none for. */
+function isKnownCurrency(code: string): boolean {
+  if (!knownCurrencies) {
+    try {
+      knownCurrencies = new Set([...Intl.supportedValuesOf("currency"), "CNH"]);
+    } catch {
+      knownCurrencies = new Set();
+    }
+  }
+  return knownCurrencies.has(code);
+}
+
 /** The request, or the sentence saying what is wrong with the argument. */
 export function parseFxRequest(raw: string, baseCurrency: string): FxRequest | { error: string } {
   const text = raw.trim().toUpperCase();
   const parts = text.split("/").map((part) => part.trim());
   if (parts.length > 2 || parts.some((part) => !part)) return { error: `"${raw}" is not a currency or a pair such as USD/NGN.` };
+  // EURUSD is the pair typed without its slash: say how to write it.
+  const joined = parts.length === 1 && /^[A-Z]{6}$/.test(text) && isKnownCurrency(text.slice(0, 3)) && isKnownCurrency(text.slice(3));
+  if (joined) return { error: `${text} is not a currency code; write the pair as ${text.slice(0, 3)}/${text.slice(3)}.` };
   const bad = parts.filter((part) => !CURRENCY_CODE.test(part));
   if (bad.length > 0) return { error: `${bad.join(" and ")} ${bad.length > 1 ? "are not currency codes" : "is not a currency code"}; use three letters such as NGN.` };
   return parts.length === 2

package/src/cli/glossary.ts

@@ -1,8 +1,9 @@
 import { cliStyles, cliTerminalWidth, renderDefinitions, renderSection, wrapText } from "../utils/cli-output";
 
 /**
- * Plain-words meanings of the rates, auction, energy, perpetual-futures, portfolio
- * and fund terms the functions show in their rows, headers and footers.
+ * Plain-words meanings of the rates, auction, energy, perpetual-futures, portfolio,
+ * fund, short interest, quote-board, futures and economic-calendar terms the functions
+ * show in their rows, headers and footers.
  * `catalog glossary` lists them, `catalog explain <term>` prints one, and
  * `fn <function> --explain` and `portfolio show --explain` follow a report with
  * the ones it shows. Only terms a pane or report actually prints belong here.
@@ -286,8 +287,11 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
     definition: "EU Allowance: the right to emit one tonne of CO2 under the EU Emissions Trading System, priced in euros per tonne.",
   },
   {
-    term: "Front month", aliases: ["front-month", "front contract", "continuous contract", "front-month contract"], functions: ["FUT", "CTM"],
-    definition: "The nearest contract still trading. FUT quotes each root's front month by its continuous symbol (TTF=F), which rolls to the next contract as one expires.",
+    term: "Front month", aliases: ["front-month", "front contract", "continuous contract", "front-month contract", "most active", "most active contract"],
+    functions: ["FUT", "CTM"], shown: ["most active"],
+    definition: "The nearest contract still trading, which is the one about to expire. Rolls follow volume: a continuous symbol (CL=F), "
+      + "and FUT with it, moves to the next contract when that one becomes the most active (it holds more open interest, or trades more "
+      + "where none is reported), usually days before expiry, and until then FUT names the nearer contract and its expiry.",
   },
   // Perpetual futures (PERP).
   {
@@ -370,6 +374,122 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
     definition: "How loosely a fund follows its index: how much the gap between the fund's return and the index's swings, usually over a year. "
       + "Fees, cash and holdings that differ from the index widen it.",
   },
+  // Short interest (SI, SIW) and daily short volume (SIV).
+  {
+    term: "Short interest", short: "SI", aliases: ["shares short", "short position", "short positions", "short shares"],
+    functions: ["SI", "SIW"], shown: ["Shares Short", "Short interest"],
+    definition: "The number of shares sold short and not yet bought back, counted across US broker-dealers on each settlement date. "
+      + "It is a position, not trading volume, and it is published seven business days after the date it counts.",
+  },
+  {
+    term: "Settlement", aliases: ["settlement date", "settlement dates", "settled", "reporting settlement date"],
+    functions: ["SI", "SIW"], shown: ["Date", "Settled", "settlement"],
+    definition: "The date short positions are counted, twice a month: the 15th (the business day before when it is not one) and the month's last business day. "
+      + "FINRA publishes each count seven business days later, and the report's source line gives that date and the next settlement's.",
+  },
+  {
+    term: "Days to cover", aliases: ["short ratio", "short interest ratio", "days-to-cover", "dtc"], functions: ["SI", "SIW"],
+    shown: ["Days to cover"],
+    definition: "Shares short divided by the average daily volume FINRA reports with the settlement: how many days of normal trading it would take "
+      + "the shorts to buy their shares back. The overview, fundamentals, SI, SIW and EQS all give FINRA's figure. "
+      + "A higher number means a squeeze would take longer to unwind.",
+  },
+  {
+    term: "Average daily volume", short: "ADV", aliases: ["avg daily vol", "avg daily volume", "average daily share volume", "avg volume"], functions: ["SI"],
+    shown: ["Avg Daily Vol"],
+    definition: "The shares traded per day on average, as FINRA reports it with each settlement. Days to cover divides shares short by it.",
+  },
+  {
+    term: "Float", aliases: ["free float", "public float", "float shares", "floating stock", "% float", "percent of float"],
+    functions: ["SI", "SIW"], shown: ["Float"],
+    definition: "The shares open to public trading: those outstanding less shares held by insiders and strategic holders, never more than the shares outstanding. "
+      + "% Float is shares short over today's float, so a settlement is measured against the float as it is now, not as it was then; "
+      + "SI gives it for the latest settlement only.",
+  },
+  {
+    // SIW's Setup column prints these two words.
+    term: "Crowded", aliases: ["crowded short", "crowded shorts", "crowded trade", "crowded, rising", "crowded rising", "setup"], functions: ["SIW"],
+    shown: ["Crowded", "Crowded, rising"],
+    definition: "SIW's flag for a heavily shorted name: at least 10% of the float short, or five or more days to cover with at least 5% of the float short "
+      + "(days to cover alone when the float is unknown). Crowded, rising adds a price up over the month. A fixed threshold, not a squeeze forecast.",
+  },
+  {
+    term: "Squeeze", aliases: ["short squeeze", "squeezes", "short covering"], functions: ["SIW"], shown: ["Short squeeze watch"],
+    definition: "A price rise that forces short sellers to buy shares back to limit their losses, which lifts the price further. "
+      + "It needs a crowded short and little trading to absorb the buying; SIW lists the names where that could happen and does not predict one.",
+  },
+  {
+    term: "SI change", aliases: ["si chg", "short interest change"], functions: ["SIW"], shown: ["SI Chg %"],
+    definition: "The change in shares short from the settlement before, in percent. A split between the two settlements is not adjusted.",
+  },
+  {
+    term: "1M return", aliases: ["1m", "one month return", "month move"], functions: ["SIW"], shown: ["1M %"],
+    definition: "The price change over one calendar month, from the latest daily close to the last close on or before the same day a month earlier.",
+  },
+  {
+    term: "Short volume", aliases: ["daily short volume", "short sale volume", "exempt volume"], functions: ["SIV"],
+    shown: ["Short volume", "Short %", "Exempt volume"],
+    definition: "Shares sold short in a day's off-exchange trading, which FINRA publishes daily; Short % is its share of the day's volume there. "
+      + "It is a flow of trades, not the open position short interest counts, and it includes exempt volume.",
+  },
+  // Quote boards (QQ). The words a beginner meets in a quote's rows and its status line.
+  {
+    term: "Ticker", aliases: ["tickers", "ticker symbol", "symbol", "stock symbol"], functions: ["QQ"], shown: ["Ticker", "Symbol"],
+    definition: "The short code a security trades under, such as AAPL for Apple or ^GSPC for the S&P 500. Type it after a function: fn QQ AAPL.",
+  },
+  {
+    term: "Pre-market", aliases: ["pre-mkt", "pre-market session", "pre-market trading", "pre-market price"], functions: ["QQ"],
+    shown: ["Pre-Market", "pre-market", "PRE-MKT"],
+    definition: "Trading in a US stock before the regular session opens, from 4:00 to 9:30 am New York time, when fewer trades happen and prices can jump. "
+      + "An index does not trade then: its pre-market status means it has not opened, and its level is still the last close.",
+  },
+  {
+    term: "After hours", aliases: ["after-hrs", "post-market", "extended hours", "after-hours trading"], functions: ["QQ"],
+    shown: ["After Hours", "after hours", "AFTER-HRS"],
+    definition: "Trading in a US stock after the regular session closes, from 4:00 to 8:00 pm New York time. "
+      + "Like the pre-market it is thin, so a price there can move more than the regular close suggests.",
+  },
+  {
+    term: "Regular close", aliases: ["close", "closing price", "last close", "prior close", "regular session", "regular session close"],
+    functions: ["QQ"], shown: ["close", "Close"],
+    definition: "The last price of the regular session, 9:30 am to 4:00 pm New York time for US stocks. "
+      + "From the close until the next open a quote's Last and change stay at it, and pre-market and after-hours prices are shown beside it.",
+  },
+  {
+    term: "Delayed", aliases: ["delayed quote", "delayed quotes", "delay", "15 min delayed", "live", "real-time"], functions: ["QQ", "FUT"],
+    shown: ["delayed", "Delayed"],
+    definition: "A price that reaches you some minutes after it traded; the status line gives the lag, such as 15 min delayed. A live (real-time) price has no lag.",
+  },
+  // Futures (FUT, CTM).
+  {
+    term: "Futures contract", aliases: ["futures", "future", "futures contracts", "contract", "contract month", "expiry", "expiration"],
+    functions: ["FUT", "CTM"], shown: ["CONTRACT", "Contract"],
+    definition: "An agreement to buy or sell something, such as oil, gold or the S&P 500, at a set price on a set date. Each contract has a month (Dec 26) and expires, "
+      + "and most traders close out before then. A contract's own Settlement line says how it ends: in cash or by physical delivery.",
+  },
+  {
+    term: "Settle (futures)", aliases: ["settle", "settle price", "settlement price", "futures settle", "daily settlement price"],
+    functions: ["FUT", "CTM"], shown: ["Settle", "PREV"],
+    definition: "A futures contract's official price for the day, set by its exchange from trading near the close. "
+      + "The day's change and margin are measured from it, and it can differ from the last trade. FUT's PREV is the previous one.",
+  },
+  // The economic calendar (ECO).
+  {
+    term: "Actual", aliases: ["actual release", "actual value"], functions: ["ECO"], shown: ["ACTUAL", "Actual"],
+    definition: "The figure a release came in at, filled in once it is published. A dash means it is still to come.",
+  },
+  {
+    term: "Forecast", aliases: ["forecasts", "consensus", "expected"], functions: ["ECO"], shown: ["FORECAST", "Forecast"],
+    definition: "What economists expected the release to show, the consensus before it comes out. Markets move on the gap between Actual and Forecast more than on the number alone.",
+  },
+  {
+    term: "Prior", aliases: ["previous", "prior value", "previous release"], functions: ["ECO"], shown: ["PRIOR", "Prior"],
+    definition: "The previous release's figure, the one Actual and Forecast are compared with.",
+  },
+  {
+    term: "Impact", short: "IMP", aliases: ["importance", "event impact", "high impact"], functions: ["ECO"],
+    definition: "How much a release usually moves markets: HIGH for the big ones (CPI, jobs, rate decisions), MED and LOW for speeches and smaller data.",
+  },
 ];
 
 const ANSI = /\x1b\[[0-9;]*m/g;
@@ -390,7 +510,10 @@ function names(entry: GlossaryEntry): string[] {
 export interface GlossaryLookup {
   /** The entries the query names: by the term, its abbreviation or an alias. */
   exact: GlossaryEntry[];
-  /** The others whose names start a word with each word of the query: `stop-out` finds stop-out vs average. */
+  /**
+   * The others whose names start a word with each word of the query: `stop-out` finds stop-out vs average.
+   * Those that hold the words whole come first.
+   */
   partial: GlossaryEntry[];
 }
 
@@ -407,7 +530,12 @@ export function lookupGlossary(query: string): GlossaryLookup {
     const have = names(entry).flatMap(words);
     return wanted.every((word) => have.some((name) => name.startsWith(word)));
   });
-  return { exact, partial };
+  // The entries that hold the words whole come before those that only start with them: `float` is the float, not the floating rate note.
+  const whole = (entry: GlossaryEntry) => {
+    const have = names(entry).flatMap(words);
+    return wanted.every((word) => have.includes(word));
+  };
+  return { exact, partial: partial.sort((left, right) => Number(whole(right)) - Number(whole(left))) };
 }
 
 function escapeRegExp(text: string): string {

package/src/cli/history-rows.ts

@@ -67,6 +67,8 @@ export interface HistoryRow {
   partial?: true;
   /** The bar's prices were rebuilt from hourly bars where the source left the day empty. */
   filled?: true;
+  /** A future's session has closed but its settlement is not confirmed yet: the close is the last trade. */
+  unsettled?: true;
   /** What the volume counts, when the history says: a coin's is traded value in its quote currency (`USD`). */
   volumeUnit?: string;
   /** Why a coin's bar has no volume: `day in progress`, `rebuilt from hourly bars`, `not reported`. */
@@ -216,6 +218,7 @@ export function historyRows(
       flag: flags.length > 0 ? flags.join(",") : null,
       ...(point.partial ? { partial: true as const } : {}),
       ...(point.filled ? { filled: true as const } : {}),
+      ...(point.unsettled ? { unsettled: true as const } : {}),
       ...(volume ? { volumeUnit: volume.unit } : {}),
       // A coin trades every day, so a bar without volume says why.
       ...(volume && values.volume == null
@@ -255,13 +258,18 @@ function listDates(dates: readonly string[]): string {
 }
 
 /**
- * What the partial and filled bars are: "2026-10-12 is still forming
- * (partial), with no volume until the day closes", and the bars rebuilt from
- * hourly bars. Null when no bar is either.
+ * What the partial, filled and unsettled bars are: "2026-10-12 is still
+ * forming (partial), with no volume until the day closes", the bars rebuilt
+ * from hourly bars, and a future's closed session that "closes on its last
+ * trade until its settlement is confirmed (unsettled)". Null when no bar is
+ * any of them.
  */
-export function historyBarStatusNote(rows: readonly Pick<HistoryRow, "date" | "partial" | "filled" | "volume">[]): string | null {
+export function historyBarStatusNote(
+  rows: readonly Pick<HistoryRow, "date" | "partial" | "filled" | "unsettled" | "volume">[],
+): string | null {
   const partial = rows.filter((row) => row.partial);
   const filled = rows.filter((row) => row.filled);
+  const unsettled = rows.filter((row) => row.unsettled);
   const notes = [
     partial.length > 0
       ? `${listDates(partial.map((row) => row.date))} ${partial.length === 1 ? "is" : "are"} still forming (partial)`
@@ -271,6 +279,10 @@ export function historyBarStatusNote(rows: readonly Pick<HistoryRow, "date" | "p
       ? `${listDates(filled.map((row) => row.date))} ${filled.length === 1 ? "was" : "were"} rebuilt from hourly bars (filled)`
         + (filled.every((row) => row.volume == null) ? ", without volume" : "")
       : null,
+    unsettled.length > 0
+      ? `${listDates(unsettled.map((row) => row.date))} ${unsettled.length === 1 ? "closes" : "close"} on the last trade until the`
+        + ` settlement is confirmed (unsettled)`
+      : null,
   ].filter((note): note is string => note != null);
   return notes.length > 0 ? notes.join("; ") : null;
 }

package/src/cli/index.ts

@@ -37,7 +37,8 @@ import { createSystemCliCommands } from "./commands/system";
 import { brokerCliCommand, ibkrCliCommand } from "./commands/broker";
 import { listPlugins, updatePlugins } from "./commands/plugins";
 import { installListedPlugin, removePlugin } from "../plugins/installer";
-import { functionCodeCommand, runPaneCatalog, runPaneFunction, runPaneScreenshot } from "./pane-functions";
+import { catalogCommandHits, functionCodeCommand, runPaneCatalog, runPaneFunction, runPaneScreenshot } from "./pane-functions";
+import { catalogPointer, type CatalogCommandHit } from "./unknown-command";
 import { catalogFredSeriesIds } from "./series-search";
 
 const { width: SHOT_WIDTH, height: SHOT_HEIGHT } = SHOT_SIZE_LIMITS;
@@ -64,7 +65,7 @@ function createCoreCliCommands(
         const topic = args[0];
         if (topic) {
           const command = lookupCommand(topic);
-          if (!command) failUnknownCommand(topic, allCommands(), await functionCodeCommand(ctx, topic, []));
+          if (!command) failUnknownCommand(topic, allCommands(), await unknownCommandPointers(ctx, topic, [], allCommands()));
           printCommandHelp(command, ctx);
           return;
         }
@@ -306,18 +307,47 @@ function printCommandHelp(command: CliCommandDef, ctx: CliCommandContext): void
   ctx.printResult({ data: { ...describeCliCommand(command), sections: command.help?.sections ?? [] } });
 }
 
-/** `function` is what the word is when it is a function's code, and the command that runs it. */
-function failUnknownCommand(token: string, commands: CliCommandDef[], fn: { code: string; command: string } | null = null): never {
-  if (fn) fail(`${fn.code} is a function: ${fn.command}`);
-  const suggestion = suggestCliCommand(
+function nearCommand(token: string, commands: CliCommandDef[]): string | null {
+  return suggestCliCommand(
     normalizeCliCommandToken(token),
     commands.flatMap((command) => [command.name, ...(command.aliases ?? [])]),
   );
+}
+
+interface UnknownCommandPointers {
+  /** The word is a function's code: the command that runs it. */
+  fn: { code: string; command: string } | null;
+  /** Functions the catalog finds for the word, read only when it is no code and no command is close to it. */
+  hits: CatalogCommandHit[];
+  /** What the reader typed after the word, which a pointer runs the function with. */
+  args: readonly string[];
+}
+
+/** What an unknown command word may point at: a function's code first, then what the catalog finds for it. */
+async function unknownCommandPointers(
+  ctx: CliCommandContext,
+  token: string,
+  args: readonly string[],
+  commands: CliCommandDef[],
+): Promise<UnknownCommandPointers> {
+  const fn = await functionCodeCommand(ctx, token, args);
+  const hits = fn || nearCommand(token, commands) ? [] : await catalogCommandHits(ctx, token);
+  return { fn, hits, args };
+}
+
+/**
+ * A function's code is pointed at `fn`; a typo of a command at the command;
+ * a word the catalog knows (`comps`, `peers`) at the functions it finds.
+ */
+function failUnknownCommand(token: string, commands: CliCommandDef[], pointers: UnknownCommandPointers): never {
+  if (pointers.fn) fail(`${pointers.fn.code} is a function: ${pointers.fn.command}`);
+  const suggestion = nearCommand(token, commands);
+  const catalog = suggestion ? null : catalogPointer(token, pointers.hits, pointers.args);
   fail(
     `Unknown command "${token}".`,
     suggestion
       ? `Did you mean ${suggestion}? Run gloomberb help to see every command.`
-      : "Run gloomberb help to see every command.",
+      : catalog ? `${catalog}\nRun gloomberb help to see every command.` : "Run gloomberb help to see every command.",
   );
 }
 
@@ -408,11 +438,13 @@ export async function failUnknownCliCommand(args: string[], options: DispatchCli
     // dispatchCli already reported flags that do not parse.
   }
   const registry = await createRegistry(options);
-  // A function's code typed as a command is pointed at `fn`, with the arguments the reader gave.
-  const fn = token && parsed
-    ? await functionCodeCommand(createCliCommandContext("core", registry, parsed.options, parsed.args.slice(1)), token, parsed.args.slice(1))
-    : null;
-  return failUnknownCommand(token, listedCommands(registry).map((entry) => entry.command), fn);
+  const commands = listedCommands(registry).map((entry) => entry.command);
+  // A function's code typed as a command is pointed at `fn`, and a word the catalog knows at its
+  // functions, with the arguments the reader gave.
+  const pointers = token && parsed
+    ? await unknownCommandPointers(createCliCommandContext("core", registry, parsed.options, parsed.args.slice(1)), token, parsed.args.slice(1), commands)
+    : { fn: null, hits: [], args: [] };
+  return failUnknownCommand(token, commands, pointers);
 }
 
 export async function runCli(args: string[], options: DispatchCliOptions = {}): Promise<boolean> {

package/src/cli/known-gaps.ts

@@ -49,7 +49,11 @@ const KNOWN_GAPS: ReadonlyArray<{ terms: readonly string[]; message: string }> =
  */
 const TOPIC_POINTERS: ReadonlyArray<{
   topic: string;
+  /** What is true of it, when "not in the terminal yet" is not: no source carries it. */
+  availability?: string;
   phrases: readonly string[];
+  /** Words that ask for the topic only as the whole query: "utilization" alone, but "capacity utilization" is another thing. */
+  whole?: readonly string[];
   closest: ReadonlyArray<readonly [code: string, gives: string]>;
 }> = [
   {
@@ -58,6 +62,16 @@ const TOPIC_POINTERS: ReadonlyArray<{
       "military budget", "military spending", "pentagon budget", "pentagon spending"],
     closest: [["AWARDS", "government contract awards by company"], ["THEM", "defense and aerospace theme: fn THEM defense"]],
   },
+  {
+    // SI's own limitations say the same, so a search for a borrow fee does not read SI as a source of one.
+    topic: "borrow fee, utilization and locate",
+    availability: "not available (no securities-lending data)",
+    phrases: ["borrow fee", "borrow fees", "borrow rate", "borrow rates", "borrow cost", "borrow costs", "cost to borrow", "short borrow",
+      "stock borrow", "borrow availability", "borrow utilization", "borrow utilisation", "shares to borrow", "hard to borrow",
+      "easy to borrow", "securities lending", "stock loan", "stock lending", "locate fee", "short locate"],
+    whole: ["borrow", "borrowing", "utilization", "utilisation", "locate", "locates", "htb", "lendable shares"],
+    closest: [["SI", "FINRA short interest and days to cover"], ["SIW", "crowded shorts across your names"], ["SIV", "daily short volume"]],
+  },
 ];
 
 /** The words of a text, lower case: `DoD-budget` and `dod budget` read alike. */
@@ -76,10 +90,15 @@ function containsWords(query: readonly string[], phrase: readonly string[]): boo
 /** The pointer for a query that asks about a topic no function covers, with the function codes it names. */
 export function topicPointer(query: string): { message: string; codes: string[] } | null {
   const asked = words(query);
-  const pointer = TOPIC_POINTERS.find(({ phrases }) => phrases.some((phrase) => containsWords(asked, words(phrase))));
+  const key = lookupKey(query);
+  const pointer = TOPIC_POINTERS.find(({ phrases, whole }) => phrases.some((phrase) => containsWords(asked, words(phrase)))
+    || whole?.some((word) => lookupKey(word) === key));
   if (!pointer) return null;
   const closest = pointer.closest.map(([code, gives]) => `${code} (${gives})`).join(", ");
-  return { message: `${pointer.topic}: not in the terminal yet; closest: ${closest}`, codes: pointer.closest.map(([code]) => code) };
+  return {
+    message: `${pointer.topic}: ${pointer.availability ?? "not in the terminal yet"}; closest: ${closest}`,
+    codes: pointer.closest.map(([code]) => code),
+  };
 }
 
 /**

package/src/cli/listing-arg.ts

@@ -39,6 +39,7 @@ import {
   typedExchangeCode,
 } from "../utils/exchanges";
 import { withMarketData } from "./scoped-context";
+import { stripStrayEdges } from "./symbol-args";
 import { isNoProviderMessage } from "../sources/provider-errors";
 import { dashedCoinPair } from "../utils/crypto-pair";
 import { currencyPairSpelling } from "../utils/currency-pair";
@@ -91,9 +92,21 @@ export interface ListingArg {
  * `resolveCliListing` asks search before reading them as USDNGN=X.
  */
 export function parseListingArg(
-  raw: string,
+  rawArg: string,
   exchangeOption?: string | null,
   { ownExchangeWins = false }: { ownExchangeWins?: boolean } = {},
+): ListingArg {
+  // A pasted ticker can bring the separator or quote marks that sat beside it (`UPST;`); search would ask for them.
+  const stripped = stripStrayEdges(rawArg);
+  const raw = stripped.text || rawArg;
+  const listing = parseCleanListingArg(raw, exchangeOption, { ownExchangeWins });
+  return stripped.text && stripped.notes.length > 0 ? { ...listing, readAs: stripped.notes.join(" ") } : listing;
+}
+
+function parseCleanListingArg(
+  raw: string,
+  exchangeOption: string | null | undefined,
+  { ownExchangeWins }: { ownExchangeWins: boolean },
 ): ListingArg {
   const optionCode = (exchangeOption ?? "").trim().toUpperCase();
   const option = canonicalExchange(optionCode);
@@ -167,9 +180,11 @@ async function settleSharedCode(listing: ListingArg, deps: ListingDeps): Promise
   }
   const { exchange } = reading;
   const key = `${symbol}:${exchange}`;
-  const readAs = exchange === meanings[0] ? {}
-    : { readAs: `Read ${symbol}:${code} as ${key}: ${code} is ${venueChoices(meanings)}, and ${symbol} trades on ${exchange}.` };
-  return { symbol, exchange, key, ...readAs };
+  const readAs = [
+    listing.readAs,
+    exchange === meanings[0] ? null : `Read ${symbol}:${code} as ${key}: ${code} is ${venueChoices(meanings)}, and ${symbol} trades on ${exchange}.`,
+  ].filter(Boolean).join(" ");
+  return { symbol, exchange, key, ...readAs ? { readAs } : {} };
 }
 
 /**

package/src/cli/listing-suggestion.ts

@@ -2,6 +2,8 @@ import type { DataProvider } from "../types/data-provider";
 import type { TickerRecord } from "../types/ticker";
 import { LISTING_SEARCH_LIMIT, searchTickerCandidates, type TickerSearchCandidate } from "../tickers/search";
 import { mapWithConcurrency } from "../utils/concurrency";
+import { isUsListingExchange } from "../utils/exchanges";
+import { STARTER_SYMBOLS } from "../tickers/starter-symbols";
 import { TickerNotFoundError } from "./ticker-resolution";
 
 /** How long a suggestion waits for search; a slow search leaves the plain "not found" as it was. */
@@ -118,13 +120,18 @@ async function searchAsCommand(query: string, { store, dataProvider }: Suggestio
 export async function suggestListing(input: string, deps: SuggestionDeps): Promise<ListingSuggestion | null> {
   const query = input.trim().replace(/^\$/, "");
   if (!query) return null;
+  const candidates = await searchCandidates(query, deps);
+  return candidates ? nearestListing(query, candidates) : null;
+}
+
+/** The search's candidates for a query, or null when it fails or is slow; it never throws and never waits longer than the timeout. */
+async function searchCandidates(query: string, deps: SuggestionDeps): Promise<TickerSearchCandidate[] | null> {
   let timer: ReturnType<typeof setTimeout> | undefined;
   try {
-    const candidates = await Promise.race([
+    return await Promise.race([
       Promise.resolve().then(() => (deps.search ?? ((text: string) => searchAsCommand(text, deps)))(query)),
       new Promise<null>((resolve) => { timer = setTimeout(() => resolve(null), deps.timeoutMs ?? SUGGESTION_TIMEOUT_MS); }),
     ]);
-    return candidates ? nearestListing(query, candidates) : null;
   } catch {
     return null;
   } finally {
@@ -132,6 +139,30 @@ export async function suggestListing(input: string, deps: SuggestionDeps): Promi
   }
 }
 
+/**
+ * The US ticker a symbol that quoted on a listing abroad was most likely typed
+ * for: APPL, which is Aptus Pharma on BSE, for AAPL. Search lists no AAPL for
+ * APPL, so the match comes from the US symbols a person is likely to mean (the
+ * starter watchlist and their own saved US tickers) that are one slip away,
+ * and only a single one counts. Search then names it; a US listing it does not
+ * find is no suggestion. Null when nothing is near, and for a symbol too short
+ * for one edit to leave it recognisable.
+ */
+export async function suggestUsTicker(typed: string, deps: SuggestionDeps): Promise<ListingSuggestion | null> {
+  const wanted = compact(typed);
+  if (wanted.length < MIN_TYPO_LENGTH) return null;
+  const saved = (await deps.store.loadAllTickers().catch(() => [])).filter((ticker) => isUsListingExchange(ticker.metadata.exchange));
+  const near = new Set([...STARTER_SYMBOLS, ...saved.map((ticker) => ticker.metadata.ticker)]
+    .map((symbol) => symbol.trim().toUpperCase())
+    .filter((symbol) => compact(symbol).length >= MIN_TYPO_LENGTH && editDistance(wanted, compact(symbol)) === 1));
+  if (near.size !== 1) return null;
+  const [symbol] = near;
+  const candidates = await searchCandidates(symbol!, deps);
+  if (!candidates) return { symbol: symbol!, name: "" };
+  const listed = candidates.find((candidate) => (candidate.label || candidate.symbol).toUpperCase() === symbol && isUsListingExchange(candidate.exchangeLabel));
+  return listed ? { symbol: symbol!, name: candidateName(listed) } : null;
+}
+
 /** The answer for a symbol search lists nothing for, with nothing else said (a company that left its symbol, a wrong exchange, a stopped listing each say more). */
 const PLAIN_NO_MATCH = /^No ticker match found for ".*"\.$/s;