gloomberb 0.16.4 → 0.16.5

package/src/cli/commands/news-hints.ts

@@ -0,0 +1,62 @@
+import { futuresBoardContract, type FuturesContract, type FuturesSector } from "../../market-data/futures-board";
+import { isFuturesInstrument } from "../../market-data/futures-contract";
+import type { Quote } from "../../types/financials";
+
+/**
+ * A company whose news follows a futures market, for the hint `news` gives a
+ * futures code: news is filed under company tickers, and funds such as UNG
+ * rarely carry stories of their own. Index, rates and currency futures have
+ * none; market headlines fit them better.
+ */
+const CONTRACT_COMPANIES: Readonly<Record<string, string>> = {
+  NG: "EQT", TTF: "LNG", CL: "XOM", BZ: "XOM", RB: "XOM", HO: "XOM",
+  GC: "NEM", SI: "NEM", PL: "NEM", PA: "NEM", HG: "FCX", ALI: "AA",
+};
+const SECTOR_COMPANIES: Partial<Record<FuturesSector, string>> = {
+  energy: "XOM",
+  metals: "NEM",
+  agriculture: "DE",
+  livestock: "TSN",
+};
+
+/** "try news LNG", or market headlines where no company follows the contract. */
+function contractSuggestion(contract: FuturesContract): string {
+  const company = CONTRACT_COMPANIES[contract.code] ?? SECTOR_COMPANIES[contract.sector];
+  return company ? `try news ${company}` : "for market headlines run news with no symbol";
+}
+
+/**
+ * What `news <symbol>` says when it finds no stories: news is filed under
+ * company tickers, so a futures board code (TTF), a futures contract (CL=F)
+ * or a symbol no listing answers to gets told so, with something to try.
+ * `searched` says a text search for the word found no story either.
+ */
+export function newsEmptyMessage(
+  symbol: string,
+  title: string,
+  quote: Pick<Quote, "instrumentType"> | null,
+  resolved: boolean,
+  searched = false,
+): string {
+  const contract = futuresBoardContract(symbol);
+  const typed = symbol.trim().toUpperCase();
+  if (!resolved) {
+    if (searched) {
+      return contract
+        ? `No stories match ${typed}, the futures board's code for ${contract.name}. It is not a ticker: ${contractSuggestion(contract)}.`
+        : `No listing answers to ${typed} and no stories match it. Try \`gloomberb search ${typed}\`.`;
+    }
+    return contract
+      ? `${typed} is the futures board's code for ${contract.name}, not a ticker. news takes a company ticker: ${contractSuggestion(contract)}.`
+      : `No listing answers to ${typed}. news takes a company ticker, such as news AAPL. Try \`gloomberb search ${typed}\`.`;
+  }
+  if (isFuturesInstrument(symbol, quote?.instrumentType)) {
+    if (searched) {
+      return `No stories match ${typed}, and news is filed under company tickers, not futures${contract ? `; ${contractSuggestion(contract)}` : ""}.`;
+    }
+    return `No news for ${title}: news is filed under company tickers, not futures${contract ? `; ${contractSuggestion(contract)}` : ""}.`;
+  }
+  return contract
+    ? `No news for ${title}. ${typed} is also the futures board's code for ${contract.name}: ${contractSuggestion(contract)}.`
+    : `No news for ${title}.`;
+}

package/src/cli/commands/news-search.ts

@@ -0,0 +1,53 @@
+import { apiClient } from "../../api-client";
+import type { NewsArticle } from "../../news/types";
+import { mapCloudNewsArticle } from "../../sources/gloomberb-cloud/news";
+import { cliStyles } from "../../utils/cli-output";
+
+/** What the service accepts of a search: two characters to two hundred, with a letter or a number in them. */
+const MIN_TEXT_LENGTH = 2;
+const MAX_TEXT_LENGTH = 200;
+const MIN_FALLBACK_LENGTH = 3;
+
+/**
+ * The text `news` was asked to search for rather than a symbol: several words,
+ * quoted or not (`news "european gas"`, `news european gas`). A single word
+ * is a symbol until nothing answers to it (`newsFallbackText`).
+ */
+export function newsSearchText(args: readonly string[]): string | null {
+  const text = args.join(" ").trim().replace(/\s+/g, " ");
+  return args.length > 1 || /\s/.test(text) ? text : null;
+}
+
+/** Why the service would refuse the text, or null when it can search it. */
+export function newsSearchTextProblem(text: string): string | null {
+  if (text.length < MIN_TEXT_LENGTH || !/[\p{L}\p{N}]/u.test(text)) return "Search text needs at least two characters, with a letter or a number.";
+  if (text.length > MAX_TEXT_LENGTH) return `Search text is limited to ${MAX_TEXT_LENGTH} characters.`;
+  return null;
+}
+
+/**
+ * The word a symbol lookup found no stories for, as text to search stories for.
+ * Null under three characters, where the fuzzy match finds names that merely
+ * contain it (ZN, Telomir-Zn) and the lookup's own answer is the better one.
+ */
+export function newsFallbackText(symbol: string): string | null {
+  const text = symbol.trim().replace(/^\$/, "");
+  return text.length < MIN_FALLBACK_LENGTH || newsSearchTextProblem(text) ? null : text;
+}
+
+/**
+ * The stories matching the text, newest first. The service answers best match
+ * first and holds stories back from an account without real-time access, as
+ * every other news request.
+ */
+export async function searchNewsStories(text: string, limit: number): Promise<NewsArticle[]> {
+  const response = await apiClient.searchCloudNews(text, limit);
+  return response.items
+    .map((item) => mapCloudNewsArticle(item))
+    .sort((a, b) => b.publishedAt.getTime() - a.publishedAt.getTime());
+}
+
+/** The line above the stories: "Stories matching "european gas"", with why a word typed as a symbol is searched. */
+export function newsSearchHeading(text: string, reason?: string): string {
+  return `${cliStyles.bold(`Stories matching "${text}"`)}${reason ? cliStyles.muted(`  ·  ${reason}`) : ""}`;
+}

package/src/cli/commands/options-leaps.ts

@@ -2,7 +2,7 @@ import type { OptionContract, OptionsChain } from "../../types/financials";
 import type { CliCommandContext } from "../../types/plugin";
 import type { MarketContext } from "../types";
 import type { CliResultColumn } from "../result";
-import { requireCliListing, loadListingQuote, type CliListing } from "../listing-arg";
+import { listingReadNotes, requireCliListing, loadListingQuote, type CliListing } from "../listing-arg";
 import { rowsFreshness } from "../freshness";
 import { formatCountCell } from "../helpers";
 import { cliStyles } from "../../utils/cli-output";
@@ -388,7 +388,10 @@ export async function runLeapsScreen(
     ctx.fail(screened.map((entry) => entry.warning).filter(Boolean).join("\n"));
   }
   const rows = sortLeapsRows(screened.flatMap((entry) => entry.rows), criteria.sort);
-  const warnings = screened.map((entry) => entry.warning).filter((warning): warning is string => warning != null);
+  const warnings = [
+    ...listings.flatMap(listingReadNotes),
+    ...screened.map((entry) => entry.warning).filter((warning): warning is string => warning != null),
+  ];
   const { format, limit: rowLimit, tail } = ctx.cliOptions;
   const capped = format === "text" && rowLimit == null && tail == null && rows.length > LEAPS_TEXT_ROWS;
   const describe = (data: readonly LeapsRow[]) => {

package/src/cli/commands/overview.ts

@@ -10,7 +10,7 @@ import {
   rankScreenerQuotes,
   type ScreenerCategory,
 } from "../../plugins/builtin/market-movers/screener";
-import { formatMoverPrice, moverReferencePrice } from "../../plugins/builtin/market-movers/model";
+import { formatMoverPrice, moverReferencePrice, moverRegularSession } from "../../plugins/builtin/market-movers/model";
 import { EXTENDED_SESSION_LABELS, getQuoteSessionFields, type ExtendedSession } from "../../market-data/market/status";
 import {
   COUNTRY_CYCLE,
@@ -27,14 +27,24 @@ import { buildCorrelationSeries } from "../../plugins/builtin/correlation/matrix
 import { alignDailyCloses, correlateDailyCloses } from "../../plugins/builtin/correlation/compute";
 import { mixedSessionCloseNote } from "../../market-data/market/session-close-note";
 import { CORRELATION_RETURN_BASIS, loadCorrelationHistory } from "../../plugins/builtin/correlation/history";
-import { EXCHANGE_OPTION, listingIdentity, loadForListing, loadListingQuote, requireCliListing, type CliListing } from "../listing-arg";
+import { EXCHANGE_OPTION, listingIdentity, listingReadNotes, loadForListing, loadListingQuote, requireCliListing, type CliListing } from "../listing-arg";
 import { CLI_COMMAND_GROUPS } from "../help";
 import { formatChangePercentCell, formatCompactCell } from "../helpers";
 import { WORLD_INDICES } from "../../plugins/builtin/world-indices/indices";
 import { getSectorCollection, SECTOR_COLLECTIONS } from "../../plugins/builtin/sectors/sector-data";
 import { DAILY_CLOSES } from "../../plugins/builtin/shared/report-freshness";
-import { newestReportTime, oldestReportTime } from "../../utils/utc-time";
+import { localTimeSuffix, newestReportTime, oldestReportTime } from "../../utils/utc-time";
 import { quotesFreshness, rowsFreshness } from "../freshness";
+import { periodicityOf } from "../pane-functions/freshness";
+import { formatBasisPoints, toBasisPoints } from "../../utils/basis-points";
+import {
+  DEFAULT_FRED_START,
+  fredEmptyMessage,
+  fredHistoryNotes,
+  isSpreadSeries,
+  laggingSeriesNote,
+  spreadBasisPointsCell,
+} from "./fred-series";
 
 // Batch quotes often omit names for indices and ETFs; these baskets are fixed, so name them here.
 const BASKET_NAMES = new Map<string, string>([
@@ -80,7 +90,10 @@ const MOVER_COLUMNS = [
   { key: "volume", header: "Volume", align: "right" as const, format: formatCompactCell },
   { ...MARKET_CAP_CELL, format: formatCompactCell },
 ];
-const START_OPTION = { flags: "--start <yyyy-mm-dd>", description: "First observation date (default 2021-01-01)" };
+const START_OPTION = {
+  flags: "--start <yyyy-mm-dd>",
+  description: `First observation date; yyyy or yyyy-mm start at the first of that year or month (default ${DEFAULT_FRED_START})`,
+};
 
 const MOVER_LISTS: Record<string, ScreenerCategory | "trending"> = {
   gainers: "day_gainers",
@@ -150,13 +163,25 @@ async function runMoverCommand(args: string[], ctx: Parameters<CliCommandDef["ex
   }
 
   const screener = await fetchScreenerResult(category, limit, undefined, { forceRefresh: ctx.cliOptions.refresh });
-  const rows = rankScreenerQuotes(category, screener.data);
+  // Ranked by the live print, as the list is; then Last and Chg% are the regular
+  // session, as `ticker` reads it, and a pre-market or after-hours print is its own column.
+  const rows = rankScreenerQuotes(category, screener.data).map((quote) => {
+    const { extended, ...row } = moverRegularSession(quote);
+    return {
+      ...row,
+      extendedSession: extended?.session ?? null,
+      extendedPrice: extended?.price ?? null,
+      extendedChange: extended?.change ?? null,
+      extendedChangePercent: extended?.changePercent ?? null,
+    };
+  });
   // A screener snapshot, as the MOST report reads it: delayed, each row dated by its own last price.
   ctx.printResult({ data: rows, freshness: rowsFreshness(rows, { status: "delayed" }, { stale: screener.stale === true }) }, {
     columns: [
       ...MOVER_COLUMNS.slice(0, 4),
+      ...EXTENDED_COLUMNS,
       { key: "volume", header: "Volume", align: "right", value: (row) => formatCompact(Number(row.volume)) },
-      { key: "marketCap", header: "Mkt Cap", align: "right", value: (row) => row.marketCap == null ? "" : formatCompact(Number(row.marketCap)) },
+      { ...MARKET_CAP_CELL, value: (row) => row.marketCap == null ? "" : formatCompact(Number(row.marketCap)) },
     ],
   });
 }
@@ -180,12 +205,12 @@ async function runQuoteBasket(symbols: string[], ctx: Parameters<CliCommandDef["
   });
 }
 
-/** The UTC date, or the UTC time with its zone named, of an event's timestamp. */
+/** The UTC date, or the UTC time with its zone named (and the reader's own beside it), of an event's timestamp. */
 function utcDateTimePart(value: unknown, part: "date" | "time"): string {
   const date = new Date(String(value));
   if (Number.isNaN(date.getTime())) return "";
   const iso = date.toISOString();
-  return part === "date" ? iso.slice(0, 10) : `${iso.slice(11, 16)} UTC`;
+  return part === "date" ? iso.slice(0, 10) : `${iso.slice(11, 16)} UTC${localTimeSuffix(date.getTime())}`;
 }
 
 const ECON_USAGE = "econ [--country <region>] [--impact <level>] [--from <yyyy-mm-dd>]";
@@ -204,13 +229,22 @@ function econEmptyMessage(from: string | null, listedThrough: string | null, sto
     : `No matching events${range} through ${listedThrough}.`;
 }
 
-/** A `yyyy-mm-dd` option, checked here; null when it was not given. */
-function parseDateOption(value: string | undefined, flag: string, ctx: Parameters<CliCommandDef["execute"]>[1]): string | null {
+/**
+ * A `yyyy-mm-dd` option, checked here; null when it was not given. `expand`
+ * reads a shorthand as a full date first, and `form` is how the message names
+ * what the option takes.
+ */
+function parseDateOption(
+  value: string | undefined,
+  flag: string,
+  ctx: Parameters<CliCommandDef["execute"]>[1],
+  { expand = (text: string) => text, form = "yyyy-mm-dd" }: { expand?: (text: string) => string; form?: string } = {},
+): string | null {
   if (value == null) return null;
-  const date = value.trim();
+  const date = expand(value.trim());
   const time = /^\d{4}-\d{2}-\d{2}$/.test(date) ? Date.parse(`${date}T00:00:00Z`) : Number.NaN;
   if (!Number.isFinite(time) || new Date(time).toISOString().slice(0, 10) !== date) {
-    ctx.fail(`${flag} takes a date as yyyy-mm-dd, got "${value}".`);
+    ctx.fail(`${flag} takes a date as ${form}, got "${value}".`);
   }
   return date;
 }
@@ -281,9 +315,15 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
 const FRED_USAGE = "fred <series-id> [--start <yyyy-mm-dd>] [--sort desc|asc]";
 const FRED_LIST_USAGE = "fred --list [filter]";
 
-/** `--start`, checked here: Gloom Cloud cannot read anything but yyyy-mm-dd. */
+/** A year or a month stands for the first day of it. */
+function startOfPeriod(text: string): string {
+  if (/^\d{4}$/.test(text)) return `${text}-01-01`;
+  return /^\d{4}-\d{2}$/.test(text) ? `${text}-01` : text;
+}
+
+/** `--start`, checked here: Gloom Cloud cannot read anything but yyyy-mm-dd, so yyyy and yyyy-mm are spelled out. */
 function parseStartDate(value: string | undefined, ctx: Parameters<CliCommandDef["execute"]>[1]): string {
-  return parseDateOption(value, "--start", ctx) ?? "2021-01-01";
+  return parseDateOption(value, "--start", ctx, { expand: startOfPeriod, form: "yyyy-mm-dd, yyyy-mm or yyyy" }) ?? DEFAULT_FRED_START;
 }
 
 /** Gloom Cloud serves a curated set of FRED series and answers 400 for any other id. */
@@ -336,15 +376,37 @@ async function runFred(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
     throw error;
   });
   const rows = data.observations;
+  // The default start hides older history and a start before the series begins is moved up silently: say where it really starts.
+  const notes = [
+    ...fredHistoryNotes({ startDate, startGiven: start != null, seriesStart: data.info?.observationStart }),
+    laggingSeriesNote(seriesId),
+  ].filter((note): note is string => note != null);
+  // Nothing on or after the start: name where the series ends, so an empty answer is not a dead end.
+  const latest = rows.length > 0 ? null : await apiClient.getCloudFredSeries(seriesId, { limit: 1, sortOrder: "desc" })
+    .then((payload) => payload.observations[0] ?? null).catch(() => null);
+  const periodicity = periodicityOf(data.info?.frequency);
   ctx.printResult({
     data: rows,
-    metadata: { info: data.info, seriesId, startDate, sortOrder },
-    freshness: rowsFreshness(rows, { source: "FRED", status: "not-a-feed", basis: "published statistics", observedKey: "date", oldest: null }),
+    metadata: {
+      info: data.info, seriesId, startDate, sortOrder,
+      ...(notes.length ? { notes } : {}),
+      ...(latest ? { latestObservation: latest } : {}),
+    },
+    freshness: rowsFreshness(rows, {
+      source: "FRED", status: "not-a-feed", basis: "published statistics", observedKey: "date", oldest: null,
+      // A monthly or quarterly observation is dated the first of its period, not a day it was seen.
+      ...(periodicity ? { periodicity } : {}),
+    }),
   }, {
     dateKey: "date",
+    empty: fredEmptyMessage(startDate, latest),
+    ...(notes.length ? { footnote: notes.join("\n") } : {}),
     textColumns: [
       { key: "date", header: "Date" },
-      { key: "value", header: data.info?.units ? `Value (${data.info.units})` : "Value", align: "right" },
+      isSpreadSeries(seriesId)
+        // A spread is read in basis points; JSON and CSV keep FRED's percentage points.
+        ? { key: "value", header: "Value (bp)", align: "right", format: spreadBasisPointsCell }
+        : { key: "value", header: data.info?.units ? `Value (${data.info.units})` : "Value", align: "right" },
     ],
   });
 }
@@ -358,12 +420,16 @@ async function runYieldCurve(rawArgs: string[], ctx: Parameters<CliCommandDef["e
   const series = Object.keys(YIELD_TENORS);
   const results = await Promise.all(series.map(async (seriesId) => {
     const data = await apiClient.getCloudFredSeries(seriesId, { startDate, sortOrder: "desc" });
-    const latest = data.observations[0];
+    const [latest, previous] = data.observations;
     return {
       seriesId,
       date: latest?.date ?? "",
       value: latest?.value ?? null,
       title: data.info?.title ?? "",
+      // The move since the previous observation FRED has, not calendar yesterday: a Monday reads against Friday.
+      previousDate: previous?.date ?? null,
+      previousValue: previous?.value ?? null,
+      changeBasisPoints: latest?.value != null && previous?.value != null ? toBasisPoints(latest.value - previous.value, 1) : null,
     };
   }));
   ctx.printResult({
@@ -373,7 +439,13 @@ async function runYieldCurve(rawArgs: string[], ctx: Parameters<CliCommandDef["e
   }, {
     textColumns: [
       { key: "tenor", header: "Tenor", value: (row) => YIELD_TENORS[String(row.seriesId)] ?? row.seriesId },
-      { key: "value", header: "Yield %", align: "right" },
+      { key: "value", header: "Yield %", align: "right", format: (value) => typeof value === "number" ? value.toFixed(2) : "-" },
+      {
+        key: "changeBasisPoints",
+        header: "1D bp",
+        align: "right",
+        format: (value) => typeof value === "number" ? formatBasisPoints(value / 100) : "-",
+      },
       { key: "date", header: "Date" },
       { key: "seriesId", header: "Series" },
     ],
@@ -419,9 +491,10 @@ async function runCorrelation(rawArgs: string[], ctx: Parameters<CliCommandDef["
       asOf: newestReportTime(lastBars),
       oldest: oldestReportTime(lastBars),
     });
+    const warnings = [...listingReadNotes(leftListing!), ...listingReadNotes(rightListing!), ...sessionNote ? [sessionNote] : []];
     ctx.printResult({
       data: [{ left, right, samples: sampleSize, correlation }],
-      ...(sessionNote ? { warnings: [sessionNote] } : {}),
+      ...(warnings.length > 0 ? { warnings } : {}),
       metadata: { range: "1Y", basis: CORRELATION_RETURN_BASIS },
       freshness,
     }, {

package/src/cli/commands/remote.ts

@@ -41,9 +41,10 @@ export const remoteCliCommand: CliCommandDef = {
       return;
     }
 
+    // No data folder means this profile never opened the app, so none is running to drive.
     const dataDir = await getDataDir();
     if (!dataDir) {
-      ctx.fail("No data directory configured.", "Run gloomberb once before using remote control.");
+      ctx.fail("No running Gloomberb app found.", "Open the desktop app or run gloomberb, then try again.");
       return;
     }
 

package/src/cli/commands/search.ts

@@ -6,6 +6,7 @@ import {
 import type { DataProvider } from "../../types/data-provider";
 import type { TickerRecord } from "../../types/ticker";
 import {
+  LISTING_SEARCH_LIMIT,
   searchTickerCandidates,
   type TickerSearchCandidate,
 } from "../../tickers/search";
@@ -14,6 +15,10 @@ import { fail } from "../errors";
 import type { MarketContext } from "../types";
 import type { CliCommandContext } from "../../types/plugin";
 import { indexRootFor, indexRootTryLine } from "../index-roots";
+import { knownGapMessage } from "../known-gaps";
+import { instrumentTypeLabel } from "../../tickers/instrument-kind";
+import { canonicalExchange, isUsListingExchange } from "../../utils/exchanges";
+import { groupByCompany } from "../../tickers/company-name";
 
 interface SearchCommandDependencies {
   initMarketData?: () => Promise<MarketContext>;
@@ -41,18 +46,64 @@ export async function searchCandidatesForCli({
     tickers.map((ticker) => [ticker.metadata.ticker.toUpperCase(), ticker] as const),
   );
   try {
-    return await searchTickerCandidates({
+    const candidates = await searchTickerCandidates({
       query: trimmedQuery,
       tickers: localTickerMap,
       dataProvider,
       localLimit,
-      totalLimit,
+      // Every company's listing of a symbol several use (CAR's ASX line is past the first ten), cut after ordering.
+      totalLimit: Math.max(totalLimit, LISTING_SEARCH_LIMIT),
+      searchContext: { limit: LISTING_SEARCH_LIMIT },
     });
+    return (await withPrimaryListingFirst(trimmedQuery, candidates, dataProvider)).slice(0, totalLimit);
   } catch {
     return [];
   }
 }
 
+function candidateExchange(candidate: TickerSearchCandidate): string {
+  return canonicalExchange(candidate.result?.exchange === "SMART"
+    ? candidate.result.primaryExchange
+    : candidate.result?.exchange || candidate.result?.primaryExchange || candidate.ticker?.metadata.exchange || candidate.right);
+}
+
+/**
+ * For a bare symbol several companies list (CAR: Avis, Carrefour, CAR Group),
+ * the listing `quote CAR` reads goes first as the primary listing, then each
+ * other company's first listing, then the rest of their venues, so a short
+ * list still shows every company. A saved listing is the user's choice and
+ * stays where search put it. Any other query keeps search's order.
+ */
+async function withPrimaryListingFirst(
+  query: string,
+  candidates: TickerSearchCandidate[],
+  dataProvider: DataProvider,
+): Promise<TickerSearchCandidate[]> {
+  const symbol = query.toUpperCase();
+  if (!/^[A-Z0-9][A-Z0-9.\-]{0,11}$/.test(symbol)) return candidates;
+  const exact = candidates.filter((candidate) => candidate.symbol.toUpperCase() === symbol);
+  if (exact.some((candidate) => candidate.kind === "ticker" || candidate.saved)) return candidates;
+  const listed = exact.filter((candidate) => candidate.kind === "search" && (candidate.instrumentClass === "equity" || candidate.instrumentClass === "other"));
+  const companies = groupByCompany(listed, resolveSearchName);
+  if (companies.length < 2) return candidates;
+  const quote = await dataProvider.getQuote(symbol, "").catch(() => null);
+  const quoted = canonicalExchange(quote?.listingExchangeName || quote?.exchangeName);
+  if (!quoted) return candidates;
+  // The US exchanges share one symbol: a quote on any of them is the symbol's one US line.
+  const primary = listed.find((candidate) => candidateExchange(candidate) === quoted)
+    ?? (isUsListingExchange(quoted) ? listed.find((candidate) => isUsListingExchange(candidateExchange(candidate))) : undefined);
+  if (!primary) return candidates;
+  const firsts = companies.filter((group) => !group.includes(primary)).map((group) => group[0]!);
+  const ordered = [primary, ...firsts, ...listed.filter((candidate) => candidate !== primary && !firsts.includes(candidate))];
+  const at = candidates.indexOf(listed[0]!);
+  const rest = candidates.filter((candidate) => !listed.includes(candidate));
+  return [...rest.slice(0, at), ...ordered, ...rest.slice(at)].map((candidate) => (
+    candidate === primary ? { ...candidate, category: "Primary Listing" as const }
+      : listed.includes(candidate) || candidate.category === "Primary Listing" ? { ...candidate, category: "Other Listings" as const }
+      : candidate
+  ));
+}
+
 /** "Saved", or the broker a row came from; never the data service's internal id. */
 function searchSourceLabel(candidate: TickerSearchCandidate): string {
   return candidate.kind === "ticker" ? "Saved" : candidate.result?.brokerLabel || "";
@@ -62,6 +113,13 @@ function resolveSearchName(candidate: TickerSearchCandidate): string {
   return candidate.detail.split(" | ")[0] || candidate.detail || "—";
 }
 
+/** The listing's type as the table shows it; a perpetual price a provider types as a coin says what it is. */
+function searchType(candidate: TickerSearchCandidate): string | undefined {
+  return instrumentTypeLabel(candidate.result?.type
+    || candidate.result?.brokerContract?.secType
+    || candidate.ticker?.metadata.assetCategory, resolveSearchName(candidate));
+}
+
 function searchCandidateRows(candidates: TickerSearchCandidate[]) {
   return candidates.map((candidate) => ({
     category: candidate.category,
@@ -92,6 +150,22 @@ function indexRootNote(query: string, candidates: TickerSearchCandidate[]): stri
   return indexRootTryLine(root);
 }
 
+/** Search finds tickers and companies; a function, a dataset or a term is in the catalog, so an empty search points there. */
+function catalogHint(query: string): string {
+  return `Search finds tickers and company names. Try: gloomberb catalog "${query.replace(/"/g, "")}"`;
+}
+
+/**
+ * The notes beside the results: the index a bare root names, data the query
+ * asks for that no source carries yet, and for an empty search the catalog,
+ * unless a known gap already said where to look instead.
+ */
+function searchNotes(query: string, candidates: TickerSearchCandidate[]): string[] {
+  const gap = knownGapMessage(query);
+  return [indexRootNote(query, candidates), gap, candidates.length === 0 && !gap ? catalogHint(query) : null]
+    .filter((note): note is string => !!note);
+}
+
 export function buildSearchReport({
   query,
   candidates,
@@ -102,9 +176,11 @@ export function buildSearchReport({
   const lines = [renderSection(`Search: ${query}`)];
   const indexNote = indexRootNote(query, candidates);
   if (indexNote) lines.push("", indexNote);
+  const gap = knownGapMessage(query);
+  if (gap) lines.push("", gap);
 
   if (candidates.length === 0) {
-    lines.push(cliStyles.muted("No matches found."));
+    if (!gap) lines.push(cliStyles.muted("No matches found."), cliStyles.muted(catalogHint(query)));
     return lines.join("\n");
   }
 
@@ -131,10 +207,7 @@ export function buildSearchReport({
           || candidate.ticker?.metadata.exchange
           || candidate.right
           || "—",
-        candidate.result?.type
-          || candidate.result?.brokerContract?.secType
-          || candidate.ticker?.metadata.assetCategory
-          || "—",
+        searchType(candidate) ?? "—",
         ...(showSource ? [searchSourceLabel(candidate) || "—"] : []),
       ]),
     ));
@@ -160,11 +233,11 @@ export async function search(query: string, dependencies: SearchCommandDependenc
     });
 
     if (dependencies.printResult) {
-      const indexNote = indexRootNote(trimmedQuery, candidates);
+      const warnings = searchNotes(trimmedQuery, candidates);
       dependencies.printResult({
         data: searchCandidateRows(candidates),
         metadata: { query: trimmedQuery },
-        warnings: indexNote ? [indexNote] : undefined,
+        warnings: warnings.length ? warnings : undefined,
       }, {
         columns: [
           { key: "category", header: "Category" },